# developer Commerce Cloud - Full Documentation

<!-- document id=807c91a861af04f31fbe540336525a747bf1939d88a21fdb372c961aed47e3c7 url=/developer/current/en-us/commerce-cloud/marketplace/references/about.md -->

# About the Marketplace Seller Integration API

This document aims to help sellers who wish to perform the management of their items within Commerce Marketplace through a custom integration.

The following documentation focuses on the basic flow for the integration of the seller data, including example requests and responses.

The Marketplace Seller Integration API is based on the main REST API from Salesforce. For more information, see the [REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_what_is_rest_api.htm).

## Authorization

To use the API, you must authenticate using the **Login** and **Get/Refresh Token** endpoints. These endpoints include an access token in the response that you can supply as a parameter to make authorized requests to the other endpoints. For step-by-step instructions, see the [authorization instructions](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/quickstart_oauth.htm) for the REST API.

## Rate Limits

To ensure availability and protect from denial of service attacks, requests to the API are rate limited. For details, see the [Limits](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_limits.htm) page in the REST API Developer Guide.

<!-- document id=b02f1aac5ce2cdbf51d330da20222367ce9208b60a2370e68a086c24cb7e63f1 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/env-var-3rd-party-CMS.md -->

# Access Protected Resources with Environment Variables

Managed Runtime environment variables allow you to add variables to the application process running in an environment, without having to make code changes. Environment variables are stored securely, making them ideal for use cases such as:

- Calling third-party resources that are protected by API keys
- Conditionally changing React.js rendering


For more details, see [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

Let’s use an environment variable to store an API key used to access a secure external resource. In this tutorial the resource is an imaginary third-party content management system (CMS). We'll add a handler to the Express.js server in `ssr.js` that makes requests to the CMS and responds with the protected data. We then access the data by calling the handler.

For security reasons, the API key calls the CMS from server-side code, not client-side code.

## Prerequisites

To complete this tutorial, first:

- Get access to Managed Runtime and Runtime Admin. See [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html).
- Have an API key to use the Managed Runtime API. To find your API key, log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool and go to the [Account Settings](https://runtime.commercecloud.com/account/settings) page.
- Have a developer or admin role on the project for which you’re setting environment variables. If you don't have access, ask someone in a Managed Runtime admin role to help you with that.


## On Your Local Machine

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

### Set the Environment Variable Locally

1. To set the environment variable in the current session, open a terminal and run this command:

   - **Windows:** `set CMS_API_KEY='my-cms-api-key'`
   - **Most Unix-like operating systems, including macOS:** `export CMS_API_KEY='my-cms-api-key'`

2. Check if the environment variable is set correctly by running:

   - **Windows:** `echo %CMS_API_KEY%`
   - **Most Unix-like operating systems, including macOS:** `echo $CMS_API_KEY`

   The command returns this output: `my-cms-api-key`

3. Add this JavaScript code for calling the CMS in `ssr.js`:

```jsx
async function fetchCMSData() {
  const key = process.env.CMS_API_KEY;
  if (!key) {
    throw new Error("Environment variable CMS_API_KEY isn't set.");
  }

  return await fetch("https://api.example.com/", {
    headers: {
      Authorization: "Bearer " + key,
    },
  }).json();
}

async function handlerCMS(req, res) {
  try {
    const data = await fetchCMSData();
    return res.json(data);
  } catch (err) {
    return res.status(500).json({ error: err.message });
  }
}
```

4. Bind the handler to a route in the Express.js server. Next, start the development server using `npm start`. Finally navigate to the handler locally to verify the CMS data is returned.

## In a Non-production or Production Environment

We recommend testing these steps in a non-production environment before deploying your changes to production.

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

1. Call the [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update) endpoint to set the environment variable. This deploys your bundle. Wait for the environment to redeploy before using the API key in your code. You can also use Runtime Admin to manage environment variables. See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY='your-runtime-admin-api-key'
npx @salesforce/b2c-cli mrt env var set 'CMS_API_KEY=your-cms-api-key' \
  --project my-storefront --environment staging
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/$ENVIRONMENT_ID/env-var/" \
  --request 'PATCH' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $MOBIFY_API_KEY" \
  --data   '{"CMS_API_KEY": {"value": "'$YOUR_API_KEY_VALUE'"}}'
```

2. [Deploy your bundle](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) from your local machine to your chosen environment.

## See Also

- [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md)
- [Environment Variable Tutorials](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md#tutorials)
- [Troubleshoot Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md#troubleshoot-environment-variables)
- [Debugging Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debugging-locally)

<!-- document id=7f8bdac4319613011a93d6e8e455272f7ddeca1d20b3c524139635e68f67dd54 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-site-prefs.md -->

# Access Site Preferences in Your Composable Storefront from the MRT Data Store

If your composable storefront code requires access to the site preferences that administrators manage in Business Manager, access site preferences directly from the Managed Runtime (MRT) Data Store. Accessing site preferences from the MRT data store is faster than making a Salesforce B2C Commerce API (SCAPI) call. Enable the MRT data store by using a configuration or an environment variable.

## Prerequisites

- [PWA Kit](https://github.com/SalesforceCommerceCloud/pwa-kit) v3.21 or later.

## Enable the MRT Data Store

Before accessing the MRT Data Store, enable it in the app configuration file or by using an MRT environment variable.

Enable the MRT Data Store in the app configuration value in `config/default.js` as shown in this example.

```
module.exports = {
    app: {
        mrtDataStore: {
            enabled: true  // Enable MRT Data Store bootstrap
        },
        // ... rest of config
    }
}
```

Alternatively, use an environment variable to enable the MRT Data Store.

```
PWAKIT_MRT_DATA_STORE_ENABLED=true npm start
```

**note:** If the `PWAKIT_MRT_DATA_STORE_ENABLED` environment variable is set to a valid value, it takes precedence over the app configuration value.

## Usage in ssr.js (Server Middleware)

Access preferences at the server middleware layer, before React renders. The async `getCustomSitePreferences` and `getCustomGlobalPreferences` functions from `@salesforce/pwa-kit-runtime/utils/ssr-server` let you inspect preference values and modify the HTTP response—for example, returning a 503 status during maintenance or populating an API endpoint with feature flags. Because middleware runs before rendering, this is the right place when preferences need to gate or redirect requests. To access preferences inside React components instead, use the utility functions or hooks.

```
// app/ssr.js
import {
    getCustomSitePreferences,
    getCustomGlobalPreferences
} from '@salesforce/pwa-kit-runtime/utils/ssr-server'

export default function(app) {
    app.use(async (req, res, next) => {
        const siteId = res.locals.site?.id

        const [sitePrefs, globalPrefs] = await Promise.all([
            getCustomSitePreferences({siteId}),
            getCustomGlobalPreferences()
        ])

        if (sitePrefs.maintenanceMode) {
            return res.status(503).send('Maintenance')
        }

        next()
    })

    app.get('/api/config', async (req, res) => {
        const siteId = res.locals.site?.id
        const prefs = await getCustomSitePreferences({siteId})

        res.json({
            enableFeature: prefs.enableFeature || false
        })
    })
}
```

### Usage in React Components (Utilities)

Use the utility functions from `@salesforce/pwa-kit-runtime/utils/ssr-server` when you need direct control over how preferences are fetched and cached. Wrap them in `useQuery` from `@tanstack/react-query` to configure caching behavior—for example, `staleTime: Infinity` fetches data once per session, and `enabled: Boolean(siteId)` prevents the query from running until a site ID is available. Extract this logic into shared custom hooks and call them from any component that needs to conditionally render content based on preference flags.

```
// app/hooks/useStorePreferences.js
  import {useQuery} from '@tanstack/react-query'
  import {
      getCustomSitePreferences,
      getCustomGlobalPreferences
  } from '@salesforce/pwa-kit-runtime/utils/ssr-server'

  export function useSitePreferences(siteId) {
      return useQuery({
          queryKey: ['sitePreferences', siteId],
          queryFn: () => getCustomSitePreferences({siteId}),
          staleTime: Infinity,
          enabled: Boolean(siteId)
      })
  }

  export function useGlobalPreferences() {
      return useQuery({
          queryKey: ['globalPreferences'],
          queryFn: () => getCustomGlobalPreferences(),
          staleTime: Infinity
      })
  }

  // app/pages/home/index.jsx
  const Home = () => {
      const {data: sitePrefs} = useSitePreferences('RefArch')
      const {data: globalPrefs} = useGlobalPreferences()

      return (
          <div>
              {sitePrefs?.showBanner && <HeroBanner />}
              {globalPrefs?.enableChat && <ChatWidget />}
          </div>
      )
  }
```

## Usage in React Components (Hooks)

Use the React hooks for the most idiomatic way to access preferences in React function components. The `useCustomSitePreferences` and `useCustomGlobalPreferences` hooks from `@salesforce/pwa-kit-react-sdk/ssr/universal/hooks` integrate with React's component model, follow standard hook conventions, and can be composed into custom hooks. This is the recommended approach for React function components.

```
// app/pages/home/index.jsx
import React from 'react'
import {
    useCustomSitePreferences,
    useCustomGlobalPreferences
} from '@salesforce/pwa-kit-react-sdk/ssr/universal/hooks'

const Home = () => {
    const sitePrefs = useCustomSitePreferences()
    const globalPrefs = useCustomGlobalPreferences()

    return (
        <div>
            {sitePrefs.showBanner && <HeroBanner />}
            {globalPrefs.enableChat && <ChatWidget />}
        </div>
    )
}
```

## Local Development

Use `MRT_DATA_STORE_DEFAULTS` to seed values without a real data store for local testing. You can use either a flat object or the SCAPI envelope format with `data` and `total`.

Use flat objects for simplicity:

```
MRT_DATA_STORE_DEFAULTS='{
  "custom-global-preferences":{
    "enableChat": true,
    "maintenanceMode": false
  },
  "RefArch-custom-site-preferences":{
    "productsPerPage": 24,
    "showBanner": true
  }
}' PWAKIT_MRT_DATA_STORE_ENABLED=true npm start
```

Or use the SCAPI envelope format to match the actual data store structure. Include both `data` (array) and `total` (number) — both fields are required to trigger envelope unwrapping:

```
MRT_DATA_STORE_DEFAULTS='{
  "custom-global-preferences":{
    "data": [{ "enableChat": true, "maintenanceMode": false }],
    "total": 1
  },
  "RefArch-custom-site-preferences":{
    "data": [{ "productsPerPage": 24, "showBanner": true }],
    "total": 1
  }
}' PWAKIT_MRT_DATA_STORE_ENABLED=true npm start
```

For example, based on the `MRT_DATA_STORE_DEFAULTS` definition, `getCustomSitePreferences({siteId: 'RefArch'})` returns:

```
{
  productsPerPage: 24,
  showBanner: true
}
```

And `getCustomGlobalPreferences()` returns:

```
{
  enableChat: true,
  maintenanceMode: false
}
```

## Data Store Structure

The MRT Data Store is populated automatically when enabled. You don't need to manually configure keys. The utilities and hooks handle key resolution internally based on the site ID you provide.

**For reference, data is stored under these keys:**

- Global preferences: `custom-global-preferences`
- Site preferences: `{siteId}-custom-site-preferences`

The exact structure of the preference objects depends on the custom preferences defined in Business Manager for your B2C Commerce instance.

<!-- document id=3c91f7b4be6c14f36faa398232f15c5342e73cbe8df120e7c79221ff232dfa69 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-access-violation-logs.md -->

# Access Violation Logs

## Prerequisites

Before you can view Page Shield violation logs, you must:

- Configure at least one Page Shield policy in the zone.
- Have access to the Log Center. For details, see [Start Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_start_log_center.htm&type=5).

## View Log Center Violation Logs

In the Log Center, specify a **Service Type** of **ecdn** to restrict the search. This provides violation logs and audit logs with details of when and how a policy was changed.

![Log Center Service Type ecdn](https://developer.salesforce.com/docs/media/commerce-api/ecdn-log-center-search.png '{"class": "image-sm"}')

Audit logs contain both old and new policy information, for example:

- Old value:
  ```json
  {"action":"allow","description":"Page shield Test Policy Allow-Non Payment",
  "enabled":true,
  "expression":"(http.host contains \"/shop.stg.bcxg.sfcc-store-internal.net\" and http.request.full_uri contains \"cart\") or (http.host contains \"shop.stg.bcxg.sfcc-store-internal.net\" and http.request.full_uri contains \"checkout\")",
  "value":"script-src cquotient.com _.cquotient.com paypal.com _.paypal.com salesforce.com _.salesforce.com sfcc-store-internal.net _.sfcc-store-internal.net stripe.com _.stripe.com",
  "id":"d01673584c044c699782bd99b453dd5b"},
  ```
- New value:
  ```json
  {"action":"allow","description":"Page shield Test Policy Allow-Non Payment",
  "enabled":false,"expression":"(http.host contains \"/shop.stg.bcxg.sfcc-store-internal.net\" and http.request.full_uri contains \"cart\") or (http.host contains \"shop.stg.bcxg.sfcc-store-internal.net\" and http.request.full_uri contains \"checkout\")",
  "value":"script-src stripe.com _.stripe.com",
  "id":"d01673584c044c699782bd99b453dd5b"}
  ```

![Log Center example log entries and details](https://developer.salesforce.com/docs/media/commerce-api/ecdn-log-center-example1.png '{"class": "image-lg"}')

![ Log Center example log entries and details](https://developer.salesforce.com/docs/media/commerce-api/ecdn-log-center-example2.png '{"class": "image-lg"}')

![ Log Center example log entries and details](https://developer.salesforce.com/docs/media/commerce-api/ecdn-log-center-example3.png '{"class": "image-lg"}')

<!-- document id=d871b88cd73b295f0e6adf8bb571ecf4b32a90d2884481820e6c059290bfaa25 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/activation-code-spi.md -->

Activation Code SPI

# Activation Code SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/activation-code-spi/activation-code-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to get activation codes and details.

**Version:** 2.3.4

## Tags

### Activation Code SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/activation-code-spi/activation-code-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to get activation codes and details.

## Operations

### POST Retrieve activation code.

`POST /merchant/spi/sample/endpoint/sa/activation/code/activation/code/from/external/system`

Operation ID: `getActivationCode`. Tags: Activation Code SPI.

Retrieve activation code from merchant's system based on provided input. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `ACTIVATION_CODE`
    *   **API Endpoint:** Provide the external endpoint to get activation code and details, for example: /merchant/spi/sample/endpoint/sa/activation/code
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"contentType": "application/json"} **Invoke:** The SPI is invoked during the order checkout flow or submit order only if the order has a product that needs population of activation code from the external service (i.e., **CMS** > **Product Class** > **Requires Activation Code via External Source is enabled**). **Response:** If the SPI has an empty response or error, the order checkout or submit order flow is not completed and the associate sees an error. For more details, refer to [Point of Sale SPI Error Handling](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-spi-error-handling.html)

#### Request body

Media type: `application/json`. Schema: `ActivationCodeRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ActivationCodeResponse`.
    

## Schemas

### ActivationCodeRequest

*   `orderId` (_string_, required) The order ID of the customer order.
*   `storeId` (_string_, required) The store ID of the store where the transaction is happening.
*   `transactionId` (_string_, required) Sale transaction ID.  
    Example: `1-test-20240612131829-4-1`.
*   `productList` (_array of ExternalProduct_, required) List of products that need serialized-unit attributes. For example, activation code, context code, etc.

### ActivationCodeResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `serializedUnitDetailList` (_array of ExternalSerializedUnitDetail_) The list of attributes about a serialized unit, for example, activation code or context code.
*   `error` (_boolean_)

### ExternalProduct

Products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.

### ExternalSerializedUnitDetail

The list of attributes about a serialized unit, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### ExternalStoreAssociateAttribution

Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.

*   `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction.
*   `contributionPercentage` (_number_, required) Associate's contribution towards sales.
*   `attributionNote` (_string_) Note related to attribution.
*   `firstName` (_string_, required) Associate's first name.
*   `lastName` (_string_, required) Associate's last name.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item.
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request.

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### ExternalProductTax

Tax/Vat details.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption.
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates.
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates.
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### ExternalPriceAdjustment

Price adjustments applied on the item.  
It includes all the price adjustments like transaction discount, price override etc...  
Mandatory if any type of price adjustments is applied.

*   `description` (_string_, required) Price adjustment description.
*   `adjustment` (_string_, required) Price adjustment.
*   `id` (_string_) Promotion Id for applied coupon or auto promotion.
*   `price` (_number_, required) Price adjustment amount.
*   `priceAdjustmentType` (_string_, required) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reason` (_Reason_)
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied.  
    Not applicable for auto promotions,  
    manual price adjustments like price override & transaction discount.
*   `auto` (_boolean_, nullable) Applied promotion is auto or not.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system.  
    If an order is placed directly in the POS, this identifier will not be available.  
    The external system provides this identifier, which will then be replayed to that  
    external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.

### ExternalNote

Notes for the transaction.

*   `cartId` (_string_)
*   `noteId` (_string_)
*   `noteText` (_string_)
*   `transactionId` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

<!-- document id=b4935ff9fe30e1c5db0654bd64a21597946de5e0769eb22041b0bc92d5ff5487 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/active-data.md -->

# Active Data

You can use [Active Data](https://help.salesforce.com/s/articleView?id=cc.b2c_active_merchandising.htm&type=5) in your [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.md) site to:

- Observe product performance and order metrics.
- Set automated rules for merchandising (for example, search result sorting).

Active Data works by collecting engagement data from shoppers browsing your site and interacting with products. This data is then aggregated into predefined dimensions that are stored and associated with each product in your catalog. Active Data also collects order metrics. The metrics in Active Data can be used to:

- Analyze shopper on-site behavior so you can enhance the shopper experience and optimize product offerings to drive sales growth.
- Configure site rules - like automated merchandising - in Business Manager.

**note:** When a shopper opts out of [behavior tracking](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-tracking-preferences.html), the Active Data for that shopper’s session isn't collected or reflected in Active Data. This applies regardless of whether you enabled tracking in Business Manager.

## Prerequisites

To use Active Data:

- To access the product impression and product view events, build your site using PWA Kit version 3.3.0 or later. If you have an earlier version that doesn't support Active Data, upgrade your project to use PWA Kit 3.3.0 or later.
- If you haven't already done so, configure an ocapi proxy that points to your B2C Commerce instance. To see the Active Data metrics or attributes in Business Manager, you must use a production environment. See [Configure Managed Runtime Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md#configure-managed-runtime-environments).
- [Configure Business Manager](#configure-business-manager).

### Configure Business Manager

#### Enable Data Collection

Open a support case asking Salesforce Customer Support to enable data collection.

#### Confirm that Sites are Online

1. Log into Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration > Sites > Manage Sites**.
3. Confirm that the status is **Online** for the sites for which you want to track metrics. Active Data is collected only for live (online) sites.

#### Confirm that Tracking (Default for New Storefront Session) is Enabled

1. Log into Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Merchant Tools > Site Preferences > Privacy**.
3. Confirm that Tracking (Default for New Storefront Session) is set to **Enabled**.

## Supported Events

This table identifies the events in a PWA Kit site that Active Data tracks.

| Event              | Description                                                                                                                          | PWA Kit Support |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| Product Impression | Counts how many times a product is shown in minimal detail on a page. Examples include search results, recommendations, and banners. | Yes             |
| Product View       | Counts how many times a product is shown in great detail on a page. Examples include product detail and comparison pages.            | Yes             |
| Order              | Counts how many times a customer placed an order.                                                                                    | Yes             |

## Install Active Data

After completing the [prerequisites](#prerequisites), install Active Data by following these steps:

1. Run `npm run build` to rebuild the PWA Kit bundle.
2. Run `npm run push` to push the rebuilt bundle to Managed Runtime.

## Verify your Data

**note:** Events from storefront interactions are collated nightly, so there’s latency between when events occur and when you see data appearing on the **Active Data** tab.

Data collected from events on your storefront is automatically associated with the relevant products and aggregated at various time durations. To confirm that this data is flowing correctly:

1. Log into Business Manager.
2. Open your Product Catalog.
3. Open a product.
4. Click the **Active Data** tab to confirm that the traffic and conversion metrics in the sample data shown below are incrementing based on the time durations.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/product-order-data3.png)

## Debug Metrics Issues

If the metrics aren’t incrementing as expected, complete these debugging steps:

- Ensure that you've waited for 24 hours after a [supported event](#supported-events) happened.
- Inspect the network activity for the project and confirm that Active Data requests are returning a 200 status code. The URL for an Active Data request includes "\_Analytics-Start".

If you completed the debugging steps and the metrics still aren’t incrementing, open a support case.

## Configure Sorting

After you [Verify your Data](#verify-your-data), you can use [Active Data attributes](https://help.salesforce.com/s/articleView?id=cc.b2c_sorting_rules.htm&type=5) to power dynamic sort and search result sorting.

To configure sorting, in Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Merchant Tools > Search > Sorting Rules**. For more information, see [Sorting Rules for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_sorting_rules.htm&type=5).

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/active-data-sorting2.png)

## Limitations

Currently, Active Data in PWA Kit is limited to product-based use cases. Active Data as a mechanism for customer group segmentation isn’t supported.

## See Also

- [Data and Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/data-and-analytics.md)

<!-- document id=5b12aa49c1a5ff25452b7f74a99126d918c0640551d1805675e8db37288a544d url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-customize-data.md -->

# Add a Component That Fetches Data

Extend a Storefront Next page to fetch data on the server and pass it to a React component. This guide builds on [Add a Page and a Component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-customize.md) by adding a server-side loader that retrieves products from B2C Commerce and renders them in a new component.

## Prerequisites

- A Storefront Next app created in Business Manager, which includes a SLAS client set up automatically for authorization to Shopper APIs. See [Create a Storefront in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md) or [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-sf.md).
- A custom page created in [Add a Page and a Component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-customize.md).
- An Integrated Development Environment (IDE), such as VS Code, Cursor, or your favorite IDE. See [Download VS Code](https://code.visualstudio.com/download) or [Download Cursor](https://cursor.com/download).

## Steps

1. Create a `FeaturedProducts` component that renders a grid of products.

   a. In `{project-folder}/src/components`, create a folder named `featured-products`.

   b. In the new `featured-products` folder, create `index.tsx` with this code.

   ```tsx
   import { type ReactElement } from 'react';

   export interface Product {
       productId: string;
       productName: string;
       priceMax?: number;
       image?: { link: string; alt: string };
   }

   export interface FeaturedProductsProps {
       products: Product[];
       title?: string;
   }

   export default function FeaturedProducts({ products, title = 'Featured Products' }: FeaturedProductsProps): ReactElement {
       return (
           <section className="container mx-auto px-4 py-8">
               <h2 className="text-2xl font-bold mb-6">{title}</h2>
               <ul className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4">
                   {products.map((product) => (
                       <li key={product.productId} className="border rounded-lg p-4">
                           {product.image && (
                               <img
                                   src={product.image.link}
                                   alt={product.image.alt}
                                   className="w-full aspect-square object-cover rounded mb-2"
                               />
                           )}
                           <p className="font-medium text-sm">{product.productName}</p>
                           {product.priceMax && (
                               <p className="text-muted-foreground text-sm">${product.priceMax.toFixed(2)}</p>
                           )}
                       </li>
                   ))}
               </ul>
           </section>
       );
   }
   ```

   `FeaturedProducts` accepts a `products` array and an optional `title`. It renders a responsive grid of product cards, each showing the product image, name, and price.

2. Add a loader to the custom page route to fetch products from B2C Commerce. Open `{project-folder}/src/routes/_app.custom-page.tsx` and replace its contents with this code.

   ```tsx
   import { type ReactElement } from 'react';
   import { type LoaderFunctionArgs } from 'react-router';
   import { createPage, type RouteComponentProps } from '@/components/create-page';
   import CustomBanner from '@/components/custom-banner';
   import FeaturedProducts, { type Product } from '@/components/featured-products';
   import { createApiClients } from '@/lib/api-clients.server';

   export async function loader({ context }: LoaderFunctionArgs) {
       const clients = createApiClients(context);
       const { data } = await clients.shopperSearch.productSearch({
           params: {
               query: {
                   q: 'dress',
                   limit: 4,
                   allImages: true,
               },
           },
       });
       const products: Product[] = (data.hits ?? []).map((hit) => ({
           productId: hit.productId,
           productName: hit.productName ?? '',
           priceMax: hit.priceMax,
           image: hit.image
               ? { link: hit.image.link, alt: hit.image.alt ?? hit.productName ?? '' }
               : undefined,
       }));
       return { products };
   }

   export type CustomPageData = Awaited<ReturnType<typeof loader>>;

   function CustomPageView({ loaderData }: RouteComponentProps<CustomPageData>): ReactElement {
       return (
           <div className="pb-16">
               <CustomBanner title="Welcome to the Custom Collection!" />
               <FeaturedProducts products={loaderData.products} />
           </div>
       );
   }

   export default createPage<CustomPageData>({
       component: CustomPageView,
   });
   ```

   The `loader` function runs on the server before the page renders. `createApiClients(context)` returns all Shopper API clients configured for the current site. The `createApiClients` function is a template wrapper around the framework's `createCommerceApiClients` function. `createApiClients` reads site configuration, credentials, and locale from context and sets up authentication automatically so you don't need to pass those values manually. The loader calls the Shopper Search API to retrieve four products matching the query `dress` and destructures `data` from the response. The results are mapped to the `Product` type and returned as `loaderData`. `CustomPageView` receives `loaderData` as a prop and passes the products to `FeaturedProducts`. `CustomPageData` is derived directly from the loader's return type, so the component stays in sync with the data shape automatically.

3. In a terminal window, go to the storefront folder.

   ```bash
   cd {project-folder}
   ```

4. Build the storefront and run the development server.

   ```bash
   pnpm run build
   pnpm run dev
   ```

5. Navigate to `http://localhost:5173/custom-page`. The page now shows the banner followed by a grid of products fetched from B2C Commerce.

![Custom page shows the featured products that are fetched with the Shopper API](https://developer.salesforce.com/docs/media/sfnext/sfnext-product-grid.png '{"class": "image-xl"}')

## Next Steps

- [Deploy Storefront Next to Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md)

## See Also

- [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md)
- [SCAPI Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md)

<!-- document id=fc84335a4489ecb18ea8f5421a5bb41ec20a338ec5da029107005866dd89d69d url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-add-lwc-component.md -->

# Add a Custom Component to Your Store

Add a component to the canvas of your B2B or D2C store created with an LWR template. Optionally edit its properties.

**note:** Before placing a custom component, assign a custom theme layout to the page in Experience Builder.

1.  In the Visual Studio Code editor, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).

2.  Enter `SFDX`.

3.  Select **SFDX: Open Default Org**.

    Your store opens in a separate browser.

4.  In the left Navigation panel, click **Components**.

    The custom component displays under **Components** | **Custom Components**.

5.  From the Custom area of the Lightning Components list, drag your Lightning web component to the page canvas.

6.  To edit the component properties, select the component on the page canvas, and enter changes in the component property editor.

    To include properties that are editable when the component is selected in Experience Builder, open the .js-meta.xml file and add `{lightningCommunity__Default}` in targets and then define the properties in `targetConfigs`.

    ![Screenshot of component on page canvas in Experience Builder.](https://developer.salesforce.com/media/d2c-commerce/place_lwc_in_builder.png)

<!-- document id=e21297d2e147e6aca5e8f0b1d42fc07b7350cf5081f8f23e53fe1ba86c3b1584 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-customize.md -->

# Add a Page and a Component

Customize the storefront by adding a custom page and component.

## Prerequisites

- Generate a Storefront Next app by following the steps in [Create a Storefront in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md) or [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-sf.md).
- An Integrated Development Environment (IDE), such as VS Code, Cursor, or your favorite IDE. See [Download VS Code](https://code.visualstudio.com/download) or [Download Cursor](https://cursor.com/download).

## Steps

1. Create a component that displays a banner. Later, add this component to a new page.

   a. In `{project-folder}/src/components`, create a folder with the name `custom-banner`.

   b. In the new `custom-banner` folder, create the `index.tsx` file with this code.

   ````
   import { type ReactElement } from 'react';

    export interface CustomBannerProps {
        /** The title text to display in the banner */
        title: string;
        /** Optional subtitle text */
        subtitle?: string;
        /** Optional CSS class name for custom styling */
        className?: string;
    }

    /**
    * CustomBanner component that displays a prominent title banner.
    *
    * @param props - The component props
    * @param props.title - The title text to display (required)
    * @param props.subtitle - Optional subtitle text
    * @param props.className - Optional CSS class name for custom styling
    *
    * @returns A React element containing the banner
    *
    * @example
    * ```tsx
    * <CustomBanner title="Welcome to the Custom Collection!" />
    * ```
    *
    * @example
    * ```tsx
    * <CustomBanner title="Welcome" subtitle="This is a subtitle" />
    * ```
    */
    export default function CustomBanner({ title, subtitle, className }: CustomBannerProps): ReactElement {
        return (
            <div className={`w-full bg-primary text-primary-foreground py-12 md:py-16 lg:py-20 ${className || ''}`}>
                <div className="container mx-auto px-4 sm:px-6 lg:px-8">
                    <div className="max-w-4xl mx-auto text-center">
                        <h1 className="text-4xl sm:text-5xl md:text-6xl lg:text-7xl font-bold mb-4 leading-tight">
                            {title}
                        </h1>
                        {subtitle && (
                            <p className="text-lg sm:text-xl md:text-2xl text-primary-foreground/90">
                                {subtitle}
                            </p>
                        )}
                    </div>
                </div>
            </div>
        );
    }
   ````

   The `CustomBanner` component in `/custom-banner/index.tsx` renders a centered banner with a large title and optional subtitle. It accepts `title` (required), `subtitle` (optional), and `className` (optional) via `CustomBannerProps`. It uses Tailwind classes for responsive typography, primary theme colors, and spacing, and centers content within a max-width container. The component returns a React element with the title as an `<h1>` and conditionally renders the subtitle as a paragraph, if provided.

2. Add a page that includes this new component. The new page is created as a route file. In `{project-folder}/src/routes`, create a route file with the name `_app.custom-page.tsx` and add this code.

   ```
    import { type ReactElement } from 'react';
    import { createPage, type RouteComponentProps } from '@/components/create-page';
    import CustomBanner from '@/components/custom-banner';

    /**
    * Data structure for the custom-page.
    * This page doesn't require any loader data, so we use an empty type.
    */
    export type CustomPageData = Record<string, never>;

    /**
    * Custom page view component that displays a banner with the title "Welcome to the Custom Collection!".
    * @returns JSX element representing the custom page
    */
    // eslint-disable-next-line react-refresh/only-export-components
    function CustomPageView({}: RouteComponentProps<CustomPageData>): ReactElement {
        return (
            <div className="pb-16">
                <CustomBanner title="Welcome to the Custom Collection!" />
            </div>
        );
    }

    /**
    * Custom page component with loading fallback.
    * This creates a page component that wraps the CustomPageView component with a loading fallback.
    * The createPage utility provides consistent loading states and error handling.
    * @returns Page component with custom page functionality and loading states
    */
    // eslint-disable-next-line react-refresh/only-export-components
    export default createPage<CustomPageData>({
        component: CustomPageView,
    });
   ```

   The `_app.custom-page.tsx` file defines a React Router page at `/custom-page`. The `_app.` prefix in the file name causes the React Router to nest your custom page route under the `_app.tsx` layout. That layout renders the header, your page content, and the footer. It exports a default page via `createPage`, which wraps `CustomPageView` with Suspense and loading handling. `CustomPageView` renders the `CustomBanner` component inside a container with bottom padding. The page uses `CustomPageData`, an empty record. It doesn't require loading data so it renders immediately without async data fetching.

3. In a terminal window, go to the storefront folder.

   ```
   cd {project-folder}
   ```

4. If you haven't already, install Storefront Next project dependencies that are specified in `package.json`.

   ```
   pnpm install
   ```

5. Build the storefront and then run the development server.

   ```
   pnpm run build
   pnpm run dev
   ```

6. Navigate to the new page that you created by appending `/custom-page` to the storefront URL. For example, go to this default URL: `http://localhost:5173/MarketStreet/en-US/custom-page`. The new page shows the banner with a title.

![New page in Storefront Next displays the products by category](https://developer.salesforce.com/docs/media/sfnext/sfnext-new-page2.png '{"class": "image-xl"}')

## Next Steps

- [Add a Component That Fetches Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-customize-data.md)
- [Deploy Storefront Next to Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md)

<!-- document id=2e9f71bc270322d305e218933635eee3f9c595d9b2e69f633f18568ab6c974a4 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-add-to-cart.md -->

# Add to Cart

The workflow begins when a user adds items to the cart from either the Product Detail Page (PDP) or the Product List Page (PLP). The system then determines whether the user is initiating a new checkout or resuming an existing one and triggers the appropriate logic.

**Endpoint:** POST [`/commerce/carts/{activeCartOrId}/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemCollection)

<!-- document id=07003149cc6a91c43dbad785dbce13b3b58187164d76858ef2c67dd5d0ea2973 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-aeo-geo.md -->

# AEO and GEO

Storefront Next ships built-in support for Answer Engine Optimization (AEO) and Generative Engine Optimization (GEO) on the Product Detail Page (PDP) and Product Listing Page (PLP).

**AEO (Answer Engine Optimization)** makes product and category facts machine-readable and consistent so search engines and crawlers can parse and enrich results (for example, rich product snippets), and so assistants, voice search, and other answer-style surfaces can cite accurate who, what, how much, and in-stock information without guessing from unstructured HTML alone.

**GEO (Generative Engine Optimization)** supplies clear entity structure (products, offers, collections, breadcrumbs) and aligned metadata (titles, descriptions, canonical URLs) so generative and retrieval-augmented systems can ground responses in your storefront's authoritative data.

AEO and GEO have these benefits:

- Rich results in search engines: Structured `Product` data enables Google rich snippets: price, availability, and review stars inline in search results.
- AI citation and grounding: Clear entity graphs (products, offers, breadcrumbs) give Large Language Models (LLMs) and Retrieval-Augmented Generation (RAG) systems verifiable facts to cite rather than fabricated summaries.
- Voice and assistant surfaces: Answer engines can resolve who, what, how much, and in-stock queries directly from your structured data.
- Multisite consistency: URL helpers respect site/locale path prefixes and proxy headers, so structured data links are correct across all your storefronts without manual configuration. Managed Runtime and proxy hosts do not leak internal origins into structured data.
- Zero page-breakage risk: Schema generation runs in a deferred Promise. If it fails, the page renders normally with no script tag.

## How It Works

Two technical mechanisms work together: JSON-LD and `SeoMeta`.

| Mechanism                                       | Purpose                                                         | Where                                           |
| ----------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------- |
| JSON-LD (`<script type="application/ld+json">`) | Structured entity data for crawlers and AI systems              | PDP and PLP route loaders → `JsonLd` component  |
| `SeoMeta`                                       | Classic `<title>`, `<meta name="description">`, Open Graph tags | `ProductContent` (PDP) and category route (PLP) |

JSON-LD is the primary AEO and GEO signal. `SeoMeta` complements it—crawlers and social previews still read `<head>` tags even when structured data is present.

## Where It Is Implemented

| Concern            | PDP                                                              | PLP (category)                             |
| ------------------ | ---------------------------------------------------------------- | ------------------------------------------ |
| Route              | `src/routes/_app.product.$productId.tsx`                         | `src/routes/_app.category.$categoryId.tsx` |
| JSON-LD generator  | `src/utils/product-schema.ts`                                    | `src/utils/category-schema.ts`             |
| Public URL helpers | `src/utils/schema-url.ts`                                        | Same                                       |
| JSON-LD injection  | `src/components/json-ld/index.tsx`, script `id="product-schema"` | Same, `id="category-schema"`               |
| Page meta          | `SeoMeta` in `ProductContent`                                    | `SeoMeta` on category page                 |

## Product Detail Page (PDP)

### What Gets Emitted

The PDP emits a `schema.org/Product` graph with these fields populated from B2C Commerce API (SCAPI) data when available.

| Field                             | Source                                                                                                            |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `name`                            | `product.name`                                                                                                    |
| `description`                     | `product.longDescription`, falling back to `shortDescription`, then `pageDescription` if earlier fields are empty |
| `image`                           | Primary image; up to 5 large or medium image URLs when multiple views exist (thumbnails excluded)                 |
| `sku`, `productID`                | `product.id`                                                                                                      |
| `url`                             | Public storefront origin + current path                                                                           |
| `brand`                           | `product.brand`                                                                                                   |
| `mpn`                             | `product.manufacturerSKU`                                                                                         |
| `gtin`                            | `product.ean`                                                                                                     |
| `category`                        | `product.primaryCategoryId`                                                                                       |
| `color`                           | First `color` variation attribute value                                                                           |
| `additionalProperty`              | All variation attributes + custom attributes as `PropertyValue`                                                   |
| `offers.price`                    | Effective price (base or promo)                                                                                   |
| `offers.priceCurrency`            | `product.currency`                                                                                                |
| `offers.availability`             | Derived from inventory (`InStock`, `OutOfStock`, `BackOrder`, and `PreOrder`)                                     |
| `offers.priceValidUntil`          | One year from generation date (default horizon)                                                                   |
| `offers.lowPrice` and `highPrice` | Populated for master products with a price range across variants                                                  |

`SeoMeta` sets `<title>` to the product name, meta description to `pageDescription` or `shortDescription`, and Open Graph `og:type` to `product` with the page URL and primary image.

File:

```
In src/utils/product-schema.ts:
generateProductSchema(product, productUrl)
```

## Product Listing Page (PLP)

### What Gets Emitted

The PLP emits a `schema.org/CollectionPage` with a `mainEntity` of type `ItemList`.

`CollectionPage`

- `name`: Category name
- `description`: `category.pageDescription`, when present
- `url`: Canonical category URL

`ItemList` (inside `mainEntity`)

- `numberOfItems`: Total from search result when present
- `itemListElement`: Up to 24 products (for payload size), each as a `ListItem` wrapping a lightweight `Product` (name, url, image, offers)

#### Pricing

Each list item uses an effective price: the lowest promotional price when promotions exist, otherwise the base price. For master products, the schema considers variant-level prices when applicable.

#### Availability

The `orderable` field on the search hit drives `InStock` or `OutOfStock` availability when known. If the hit doesn't expose orderability but `config.search.products.refine.orderableOnly` is `true`, then availability is inferred as in stock for listed hits.

#### `BreadcrumbList`

Built from `parentCategoryTree` when present, plus the current category. Category links use `buildCategorySchemaUrl` so paths stay consistent with multi-site prefixes.

**note:** The loader merges critical and non-critical search hits before schema generation, so the `ItemList` reflects the full first page of results, not just the above-the-fold slice.

#### `SeoMeta`

Sets `<title>` to the category name, meta description to `pageDescription` or the general description, and `og:type` to `website` with the canonical page URL.

File:

```
In src/utils/category-schema.ts:
generateCategorySchema({ category, searchResult, pageUrl, defaultCurrency, config })
```

## URL Construction

Storefront Next builds all JSON-LD URLs from the public storefront origin and current path, not from `product.slugUrl` or internal API URLs. This approach is critical in serverless or proxied environments, such as Managed Runtime and content delivery networks (CDNs), where `request.url` can contain internal routing addresses.

File:

```
src/utils/schema-url.ts
```

Key functions:

```ts
// Reads x-forwarded-host / x-forwarded-proto headers to resolve the public domain
getPublicOrigin(request: Request): string

// Builds product and category URLs that preserve the site/locale path prefix
buildProductSchemaUrl({ productId, origin, currentPageUrl }): string | undefined
buildCategorySchemaUrl({ categoryId, origin, currentPageUrl }): string | undefined
```

### Example: Multisite URL Preservation

```ts
// Current page: https://example.com/global/en-GB/category/womens
// Built product URL:
buildProductSchemaUrl({
  productId: "12345",
  origin: "https://example.com",
  currentPageUrl: "https://example.com/global/en-GB/category/womens",
});
// → 'https://example.com/global/en-GB/product/12345'
```

Storefront Next extracts the site/locale prefix (for example, `/global/en-GB`) from the current page URL and prepends it to every linked URL inside the schema.

## Rendering

Both PDP and PLP inject JSON-LD via the `JsonLd` component, which renders a `<script type="application/ld+json">` tag. The loader defers schema generation and returns an unresolved Promise. `JsonLd` is wrapped in `<Suspense>` using React's `use()` so that JSON-LD can stream with Server-Side Rendering (SSR) after the product or category payload is ready.

```tsx
// JsonLd component usage (already wired in the routes)
import { JsonLd } from "@/components/json-ld";

<Suspense fallback={null}>
  <JsonLdWrapper schemaPromise={loaderData.productSchema} id="product-schema" />
</Suspense>;
```

If `generateProductSchema` or `generateCategorySchema` throws, failures in schema generation are logged and result in no script tag rather than breaking the page. The page continues to load normally.

Script IDs:

- PDP: `id="product-schema"`
- PLP: `id="category-schema"`

## Tests and Stories

- Unit tests: `src/utils/category-schema.test.ts`, `src/components/json-ld/index.test.tsx`
- Route-level coverage touches JSON-LD in `src/routes/_app.category.$categoryId.test.tsx` and `src/routes/_app.product.$productId.test.tsx`
- Storybook: `src/components/json-ld/stories/index.stories.tsx` (includes ItemList-oriented examples)

## Customizing the Schema

### Add Aggregate Ratings (PDP)

The `ProductSchema` type already includes an `aggregateRating` field. Wire it in `product-schema.ts` after fetching rating data from your review provider:

```ts
schema.aggregateRating = {
  "@type": "AggregateRating",
  ratingValue: "4.5",
  reviewCount: "128",
  bestRating: "5",
  worstRating: "1",
};
```

### Add FAQ Structured Data

If your PDP or editorial pages include FAQ content, add a `FAQPage` or `QAPage` schema alongside the product schema:

```tsx
<JsonLd
  id="faq-schema"
  data={{
    "@context": "https://schema.org",
    "@type": "FAQPage",
    mainEntity: [
      {
        "@type": "Question",
        name: "What sizes are available?",
        acceptedAnswer: {
          "@type": "Answer",
          text: "Available in XS–XXL.",
        },
      },
    ],
  }}
/>
```

### Enrich Catalog Fields

The quality of AEO/GEO signals depends directly on the data in your B2C Commerce catalog. Ensure Business Manager catalog fields are populated so generators and answer engines have factual text to align with structured data. Make sure that these Business Manager fields are populated for every product and category.

- `pageDescription`: Used as the meta description and JSON-LD description
- `longDescription` or `shortDescription`: Fallbacks for JSON-LD description
- `brand`: Populates `schema:brand`
- `ean`: Populates `schema:gtin`
- `manufacturerSKU`: Populates `schema:mpn`

**important:** Google's Rich Results Test flags structured data that contradicts visible on-page content as a quality issue. Keep JSON-LD in sync with visible on-page content to avoid conflicting signals. Keep catalog fields in sync with what shoppers see.

## Validation

After making changes, validate with:

- [Google Rich Results Test](https://search.google.com/test/rich-results): Checks eligibility for rich snippets
- [Schema.org Validator](https://validator.schema.org): Validates against the schema.org spec

Keep JSON-LD in sync with visible on-page content to avoid conflicting signals.

**note:** In development, `JsonLd` logs errors to the console when invalid data is passed. These errors are suppressed in production.

## See Also

- [SEO and Metadata](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-seo-metadata.md): Canonical URLs, `hreflang`, full `SeoMeta` prop reference, query-parameter allowlists
- [Images](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-images.md): Image URLs and alt text

<!-- document id=ab49ff0aed78cbb6006f4f7ce442d8488d8fb3d6a1f1644da77e4160a85fdafa url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/taob-in-composable.md -->

# Agent Order on Behalf

Use [SLAS Trusted Agent on Behalf](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html) (TAOB) functionality in your PWA Kit application to allow agents to place orders on behalf of customers. PWA Kit comes with TAOB authentication hooks. Learn how to use these and check out sample code for implementing order-on-behalf UI components.

## Prerequisites

- Familiarize yourself with the [SLAS Trusted Agent on Behalf documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html#configure-trusted-agent-authorization) to understand the auth flows, client requirements, and requirements for Business Manager users to login and place orders on behalf of customers.
- Ensure the private SLAS client used by PWA Kit is configured with the `sfcc.ta_ext_on_behalf_of` scope.

## PWA Kit Hooks

The `@salesforce/commerce-sdk-react` package in PWA Kit contains a `useTrustedAgent` React hook. This hook allows inspection of the agent state as well as actions to log in and log out agents via Account Manager (AM).

```javascript
import {useTrustedAgent} from '@salesforce/commerce-sdk-react'

// Inside a React component
const {isAgent, agentId, loginId, login, logout} = useTrustedAgent()
```

The `login(loginId?: string, usid?: string, refresh = false)` action handles the complete agent login flow within the agent's browser:

1. The hook invokes the [`getTrustedAgentAuthorizationToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedAgentAuthorizationToken) SLAS API. This API returns a login URL at Salesforce B2C Commerce Account Manager (AM) for the agent to authenticate. If provided, the `loginId` and `usid` parameters are included in the request. A `loginId` value of `guest` can be used to login as a guest user.
2. The hook opens this URL in a browser "popup" window and the agent authenticates with AM.
3. Upon successful authentication, AM redirects to a URL (the `/callback` redirectURI used by PWA Kit and configured on your SLAS client) that includes an authorization code.
4. The popup handling code reads this authorization code and uses it to invoke the [`getTrustedAgentAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedAgentAccessToken) SLAS API to exchange the code for an access token. This access token replaces the normal access token used by the PWA Kit application to make authenticated requests to SLAS APIs.
5. The hook updates its internal state to reflect that an agent is now logged in (`isAgent` is `true` and `agentId` and `loginId` are populated).

From this point onward, all SCAPI API requests made by the PWA Kit application will be made on behalf of the customer represented by the trusted agent access token. The agent can now place orders on behalf of customers.

To log out the agent and revert to normal customer authentication, simply call the `logout()` action provided by the hook. This will clear the trusted agent access token and revert to the normal customer access token.

### Agent Access Token Expiration

TAOB access tokens have a limited lifetime (default is 15 minutes). If the agent is still active after the token expires, the PWA Kit application can call the `login` action again with the `refresh` parameter set to `true` to obtain a new access token. Agent access tokens don't support refresh tokens. This `refresh` parameter is instead used to re-initiate the full login flow described above but keeps the popup from being focused. Since the agent would have recently been authenticated with AM, they don't need to re-enter their credentials and the authentication can complete seamlessly.

The normal refresh handling flow in PWA Kit automatically invokes the `login` action in this manner when an agent access token is present.

## Sample UI Implementation

This sample code implements a new component, a `TrustedAgentBanner`. We place this component in our PWA Kit applications `app/components` directory.

```javascript
import React, {useState} from 'react'
import {useLocation} from 'react-router-dom'

import {
  Box,
  Button,
  Center,
  Flex,
  Input,
  Text
} from '@salesforce/retail-react-app/app/components/shared/ui'

import {useTrustedAgent} from '@salesforce/commerce-sdk-react'

const TrustedAgentBanner = () => {
  const {isAgent, agentId, loginId, login, logout} = useTrustedAgent()
  const [inputValue, setInputValue] = useState(loginId === 'Guest' ? 'guest' : loginId)
  const location = useLocation()
  const searchParams = new URLSearchParams(location.search)
  const showAgentBanner = searchParams.has('showAgentBanner')

  // Only show banner if isAgent is true OR showAgentBanner query param is present
  if (!isAgent && !showAgentBanner) {
    return null
  }

  return (
    <Box px={8} py={2} bg="gray.100">
      <Flex>
        <Center>
          <Text as="h2" color={'black'} fontWeight={700} fontSize={20} pr={8}>
            Trusted Agent
          </Text>
        </Center>
        <Center>
          {agentId && (
            <>
              <Text as="div" fontWeight={700} fontSize={16} px={4}>
                Agent ID
              </Text>
              <Text as="div">{agentId}</Text>
            </>
          )}
          {isAgent && loginId && (
            <>
              <Text as="div" fontWeight={700} fontSize={16} px={4}>
                Login ID
              </Text>
              <Text as="div">{loginId}</Text>
            </>
          )}
        </Center>
        <Box flex={1} />
        <Center>
          {!isAgent ? (
            <form onSubmit={(e) => (e.preventDefault(), login(inputValue))}>
              <Flex>
                <Input
                  mr={4}
                  bg="white.100"
                  value={inputValue && inputValue !== 'guest' ? inputValue : ''}
                  placeholder="Login ID"
                  onChange={(e) => setInputValue(e.target.value)}
                />
                <Button type="submit">Login</Button>
              </Flex>
            </form>
          ) : (
            <Button onClick={() => logout()}>Logout</Button>
          )}
        </Center>
      </Flex>
    </Box>
  )
}

export default TrustedAgentBanner
```

This component displays a banner at the top of the page when an agent is logged in or when the `showAgentBanner` query parameter is present in the URL. It shows the agent ID and login ID when available, and provides a form for logging in as an agent or a button to logout.

Let's add this component to our PWA Kit application's main layout so that it appears on all pages. Open the `app/_app/index.jsx` file and import the `TrustedAgentBanner` component at the top:

```javascript
// imports...
import TrustedAgentBanner from '@salesforce/retail-react-app/app/components/TrustedAgentBanner'

// inside <App/> component
<>
    <AboveHeader />
    <TrustedAgentBanner />
    <Header
        onMenuClick={onOpen}
// ...
```

This places the `TrustedAgentBanner` above the main `Header` component. Remember this will only display when an agent is logged in or when the `showAgentBanner` query parameter is present.

Finally we need to make a small change to our apps `ssr.js` file in the Express handler for the `/callback` route. This route is used by PWA Kit to handle OAuth redirects. We need to ensure it returns a proper content type to be loaded in our popup window. Open the `ssr.js` file and locate the `/callback` route handler. Update it as follows, adding the `Content-Type` header:

```javascript
app.get('/callback', (req, res) => {
  // This endpoint does nothing and is not expected to change
  // Thus we cache it for a year to maximize performance
  res.set('Cache-Control', `max-age=31536000`)
  // Add this line
  res.set('Content-Type', 'text/plain')
  res.send()
})
```

Now when we test our application, the trusted agent banner should appear by adding a `showAgentBanner` query parameter to the URL. For example: `http://localhost:3000/?showAgentBanner`.

![Custom TAOB Banner Logged Out](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/taob-pwa-kit.png)

We can enter a customer login ID or simply click `Login` to login as a guest user. This action opens the Account Manager login page in a popup window. After authenticating, the banner updates to show the agent is logged in:

![Custom TAOB Banner Logged Out](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/taob-pwa-kit-logged-in.png)

### Logging In from External Applications

The previous solution uses a banner to allow agents to log in from within the PWA Kit application. In some cases, you may want to allow agents to log in from an external application or portal. This portal could have already initiated the Account Manager login process and therefore an active AM session already exists. In this case, we can adjust the `TrustedAgentBanner` component to accept a query parameter with the target customer ID and automatically trigger the login flow. Update the `TrustedAgentBanner` component as follows:

```javascript
import React, {useState, useEffect} from 'react'

// ...

const TrustedAgentBanner = () => {
    const {isAgent, agentId, loginId, login, logout} = useTrustedAgent()
    const [inputValue, setInputValue] = useState(loginId === 'Guest' ? 'guest' : loginId)
    const location = useLocation()
    const searchParams = new URLSearchParams(location.search)
    const showAgentBanner = searchParams.has('showAgentBanner')
    const trustedAgentCustomerID = searchParams.get('trustedAgentCustomerID')

    useEffect(() => {
        if (!isAgent && trustedAgentCustomerID) {
            // set refresh = true to login in the background
            login(trustedAgentCustomerID, undefined, true)
        }
    }, [isAgent, trustedAgentCustomerID, login])
```

In this example, we read a new `trustedAgentCustomerID` query parameter. If this parameter is present and no agent is currently logged in, we automatically call the `login` action with this customer ID (this can be set to `guest` as well) and set the `refresh` parameter to `true` (because an Account Manager Session already exists). The `login` action triggers the login flow in the background without focusing the popup window.

**note:** In order for the popup window to open in this scenario, you must ensure that your browser allows popups always. In Chrome, this can be done under the site settings for your PWA Kit application domain by setting the "Pop-ups and redirects" setting to "Allow".

<!-- document id=6539df747807519cd4f32b5afeaeb627d63f4e7afbad252557bc433daed786cc url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/agentforce-commerce-client-overview.md -->

# Agentforce Commerce Client Overview

The Agentforce Commerce Client is an embeddable, brand-native widget that connects a B2C Commerce storefront to an AI-powered shopping agent. It renders the conversational UI, product displays, and agent-action responses that shoppers interact with, and it exposes a JavaScript SDK so your storefront can drive and observe that UI.

The client is distributed as the `@cimulate/copilot-widget` npm package and as UMD bundles you load from a CDN. It's built with React 18 and TypeScript, but you don't need React to use it: the CDN bundles expose a global SDK that works from plain JavaScript on any storefront.

**note:** This guide documents the reusable client itself. Some storefront frameworks have their own enablement path. For Storefront Next, see [Shopper Agent for Storefront Next](https://developer.salesforce.com/docs/sfnext/guides/sfnext-shopping-agent.md), which handles enablement and container setup. For SFRA, see [Install the Agentforce Commerce Client on SFRA](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-sfra.md), which installs the `plugin_commerce_client` cartridge and configures the widget from Business Manager. For PWA Kit, see [Install the Agentforce Commerce Client on PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-pwa-kit.md), which enables the client through the `COMMERCE_AGENT_SETTINGS` Managed Runtime environment variable. This guide covers the client's configuration, styling, and extension surface. On a custom or headless storefront, you set up the container yourself, following this guide.

## When you need this guide

Most storefront frameworks wrap the client and manage its setup for you. Read this guide when you:

- Embed the client directly on a custom or headless storefront.
- Style or theme the widget to match your brand.
- Override the widget's built-in product and agent-action rendering with your own components.
- Control the widget from your storefront code (for example, open it from your own button), or listen for widget events.

## How the client connects

The client connects your storefront to a Salesforce Agentforce agent, streaming the conversation over Agentforce SCRT2 using Server-Sent Events. You work with it through these integration surfaces:

| Surface | Value |
| --- | --- |
| npm import | `@cimulate/copilot-widget/messaging` |
| CDN global | `window.CimulateMessaging` |
| Injection function | `injectMessagingWidget()` |
| Top-level React component | `AgentForceWidget` |
| Required config | `messagingConfig` with `scrt2Url`, `orgId`, and `esDeveloperName` |

## Architecture at a glance

The client sits between your storefront and the agent backend:

- **Presentation.** A React component tree renders into a DOM container element you provide.
- **UI state.** The widget holds its open, minimized, and presentation state outside React's lifecycle, so vanilla JavaScript can drive it.
- **Event bus.** UI state changes propagate as browser `CustomEvent`s on `window`, decoupling your storefront from the widget's internals.
- **Backend connection.** The widget streams from Agentforce SCRT2 over Server-Sent Events.

Communication runs in two directions. Your storefront controls the widget through the SDK's `eventHandlers` (app to widget), for example to open the widget from your own launcher button. The widget reports activity back through the `onProductResult` callback, which fires when the agent returns products (widget to app).

The widget is non-opinionated by design. It ships with no CSS framework, and every element carries a `cim-widget-` class prefix so widget styles never leak into your page and your page's styles never bleed into the widget.

## Related resources

- [Install the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-the-commerce-client.md)
- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md)
- [Choose a Customization Approach](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/customization-decision-guide.md)
- [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md)

<!-- document id=95b59b0f28b520ff603c51b8ec394d1086f3c3aec261c682031aefc32b0e9a17 url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-agentforce-commerce-vibes.md -->

# Agentforce Commerce Vibes

Agentforce Commerce Vibes is a Visual Studio Code extension that helps you build, administer, and debug B2C storefront projects with AI-assisted chat and agent skills based on the Agentic B2C Developer Toolkit.

## Get Started

- [Agentforce Commerce Vibes Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-agentforce-commerce-vibes-intro.md)
- [Install and Launch the Commerce Vibes Extension](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-install-extension.md)
- [Get Started with Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-build-storefront-next-project.md)
- [Chat with Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-chat-interface.md)

## Settings, Telemetry, and Troubleshooting

- [Agentforce Commerce Vibes Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-settings.md)
- [Telemetry in Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-telemetry.md)
- [Agentforce Commerce Vibes Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-troubleshooting.md)

<!-- document id=dbec00c02181cb8a12afd2b46231e3271ceb75c4fe318b991f7db84ea53b0a15 url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-agentforce-commerce-vibes-intro.md -->

# Agentforce Commerce Vibes Overview

Agentforce Commerce Vibes brings intelligent coding assistance directly into your development workflow. Use Commerce Vibes to develop and customize B2C storefronts, debug cartridges, manage B2C Commerce instance configuration, and automate administration tasks including managing site preferences, Business Manager configuration, and Salesforce B2C Commerce API (SCAPI) integrations. Commerce Vibes supports these storefront types: Storefront Next, SFRA, and PWA Kit.

![Welcome page appears the first time you launch Commerce Vibes](https://developer.salesforce.com/docs/media/commerce-vibes/cv-welcome3.png '{"class": "image-xl"}')

## How Does Commerce Vibes Work?

Rather than completing one file at a time, Commerce Vibes delegates multi-step Commerce tasks to an autonomous agent that understands your storefront project and connected B2C Commerce instance. It plans the work, coordinates specialized subagents across storefront layers, and iterates when things go wrong, without stopping to ask you to provide context again.

Commerce Vibes coordinates changes that span multiple layers, for example, a new checkout feature that touches a storefront route, a SCAPI custom API endpoint, and a Business Manager preference. The changes are orchestrated as a single planned unit with a checkpoint for rollback.

The agent is aware of Commerce-specific conventions: SCAPI endpoint shapes, Open Commerce API (OCAPI) resource paths, cartridge path ordering, site preferences structure, Business Manager configuration patterns, and the template and SDK boundaries of your storefront type. It applies your team's coding standards from the saved rules automatically on every task. You still define business logic, validate that generated code meets B2C Commerce platform requirements, and decide when to accept or reject the agent's work.

## Develop and Administer B2C Storefronts

Generate and modify storefront components, controllers, routes, hooks, and templates. Commerce Vibes understands the conventions of your storefront type and keeps changes consistent with surrounding code: ISML and pipeline patterns for SFRA, React Router loaders and middleware for Storefront Next, and React components and SDK hooks for PWA Kit.

Automate common administration tasks: configure site preferences, manage cartridge paths, set up SCAPI client permissions, and stage metadata changes across environments.

## Commerce Vibes Features

Commerce Vibes includes these features.

### Chat

Use chat to get AI-assisted development help in natural language. Describe what you want to build, debug, or understand—the agent determines the best approach and works directly in your workspace. Chat supports streaming responses, multi-tab conversations, inline diff review for file changes, and automatic context management for long sessions.

### Plan Mode

For complex tasks, use Plan Mode to review and approve a structured plan before anything executes. Describe your feature, iterate on the plan in conversation, and click **Approve Plan** to start execution. No files change until you approve.

### Diff Review

Every file the agent edits is surfaced for your review with line-by-line diffs. Accept or reject changes file by file, or accept all changes at once. Select any file to open a native VS Code diff editor showing exactly what changed.

### Skills, MCP Servers, and Rules

Enable or disable agent skills, MCP servers, and rules, or add new ones in the B2C Toolkit panel.

- Skills: Pre-built B2C Commerce skills from the Agentic B2C Developer Toolkit, auto-updated on every activation. Toggle skills on or off or create your own. See [Agent Skills & Plugins](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills.html) in the Agentic B2C Developer Toolkit.
- Model Context Protocol (MCP) Server: The B2C Commerce DX MCP server ships out of the box, giving the agent access to tools for documentation search, cartridge debugging, logs, deployment, and SCAPI Admin API operations. Add custom MCP servers via `.mcp.json`. See [MCP Server](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/) in the Agentic B2C Developer Toolkit.
- Rules: Persistent developer instructions the agent respects across every session. Store them in your project, under `.afv/rules/`, and commit to version control so your whole team benefits.

## License

The Commerce Vibes extension is licensed under the [Apache 2.0 License](https://github.com/SalesforceCommerceCloud/commerce-vibes-builder/blob/latest/packages/extension/LICENSE.txt).

## See Also

- [Install and Launch the Commerce Vibes Extension](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-install-extension.md)
- [Build a B2C Storefront with Commerce Vibes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-build-storefront-next-project.md)

<!-- document id=5a396e86470c8a89db85f5e094e7927abfe9c18f16cdae92a8962fce35ddaa66 url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-settings.md -->

# Agentforce Commerce Vibes Settings

Learn how to access Agentforce Commerce Vibes settings in VS Code, and configure agent permissions, session mode, and logging.

To access the Agentforce Commerce Vibes settings:

1. Open the Agentforce Commerce Vibes panel by clicking the Agentforce Commerce Vibes icon in the Activity Bar.
2. In the Agentforce Commerce Vibes panel, click the settings icon (⚙) at the top right corner of the panel.

   ![Settings panel for Agentforce Commerce Vibes](https://developer.salesforce.com/docs/media/commerce-vibes/cv-settings-panel.png '{"class": "image-xl"}')

   **tip:** Alternatively, access the Settings from the Command Palette. Open the Command Palette by pressing Cmd+Shift+P, and then entering `Agentforce Commerce Vibes` in the search field. A list of commands that match your search appear. Select `Agentforce Commerce Vibes: Settings`.

3. Manage various settings about permissions, safety, and logging, among others. For example, under "Default session mode", choose whether you want to allow the agent to run all actions without asking for approval, only run trusted actions without approval, or always ask for permission.

## See Also

- [Agentforce Vibes Developer Guide: Settings](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-settings.html).

<!-- document id=697be0ce83f65b79344c2e752ea281f3f03040f55b8346de3714defde1849495 url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-troubleshooting.md -->

# Agentforce Commerce Vibes Troubleshooting

Resolve common issues when you install, connect, or use Agentforce Commerce Vibes.

## Commerce Vibes Setup Issues

### Skills Not Loading

Run `Agentforce Commerce Vibes: Refresh Commerce Skills` from the Command Palette to re-download the latest skill set.

### MCP Server Not Connecting

Open the Toolkit panel, check the MCP tab for the server status, and click **Reconnect**.

## Debugging and Diagnostics

### Capture Diagnostics

Run `Agentforce Commerce Vibes: Copy Diagnostics` from the Command Palette to copy system info and recent events to your clipboard for support.

### Enable Debug Logs

Open the Agentforce Commerce Vibes Settings panel, enable debug logging, then run `Agentforce Commerce Vibes: Open Debug Logs`.

<!-- document id=1092def5e83faff477a10ddfa7842bcd3fd41bd1706dac571b34301378ed8d66 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/b2c-developer-tooling.md -->

# Agentic B2C Developer Toolkit

Build, debug, deploy, and manage Salesforce B2C Commerce from your terminal, editor, or AI assistant. The Agentic B2C Developer Toolkit supports developers building storefronts and integrations, and administrators managing their sites.

- **B2C CLI:** Deploy cartridges, manage code versions, run jobs, configure SLAS and eCDN, and manage Managed Runtime environments and On-Demand Sandboxes. Use the same commands interactively or in automation.
- **IDE Extension:** Work with cartridges, logs, and the script debugger in VS Code and compatible editors.
- **B2C MCP:** Connect your assistant to B2C Commerce tools, official documentation search, and workflow skills. Investigate issues, debug live cartridge code, or work with B2C Commerce data through SCAPI Admin APIs.
- **Agent Skills:** Give your assistant B2C Commerce development guidance, CLI workflows, Storefront Next patterns, and operational runbooks. Use skills through the MCP or install them separately.

## Run the B2C CLI

Run commands with `npx`, without a global installation:

```bash
npx @salesforce/b2c-cli --help
npx @salesforce/b2c-cli setup
```

Or install the CLI to use the shorter `b2c` command:

```bash
npm install -g @salesforce/b2c-cli
b2c setup
```

For prerequisites and other installation options, see [Install the B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/installation.html).

## Configuration and Authentication

Use `b2c setup` for guided configuration, or supply settings through `dw.json`, environment variables, and command flags. The CLI, MCP, and IDE Extension share B2C Commerce configuration. Configure one instance or name multiple instances and select one with `--instance`. For configuration information, see [Configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html).

For SCAPI administrative commands, create an [Account Manager API client](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-admin-apis.md). In Account Manager, assign the client the **Salesforce Commerce API** role, select each instance that the client needs to access through SCAPI, and add the scopes required by the task. For example, listing eCDN zones requires the `sfcc.cdn-zones` scope.

The following shell examples use placeholder values. Replace them with your credentials and your realm's [short code](https://developer.salesforce.com/docs/commerce/commerce-api/guides/base-url.md). Keep credentials out of source control.

```bash
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn zones list --tenant-id abcd_stg
```

`--tenant-id` accepts a tenant ID such as `abcd_stg` or its organization ID, `f_ecom_abcd_stg`. The CLI requests the access token for the command; you don't need to obtain or paste a bearer token first.

SLAS client administration uses the **SLAS Organization Administrator** role. Managed Runtime commands that use an API key accept `MRT_API_KEY`, available from [Runtime Admin Account Settings](https://runtime.commercecloud.com/account/settings). Cartridge and WebDAV operations can also require an instance hostname, username, and WebDAV access key, depending on the authentication method.

See [Configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html) for project and global `dw.json` files, multiple instances, and environment variables. See [Authentication](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.html) for client roles, scopes, OCAPI permissions, and WebDAV access. [Safety Mode](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/safety.html) can restrict supported write and delete operations across the CLI, MCP, and IDE Extension.

## Connect Your AI Assistant

Install the [B2C MCP](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/) through an agent plugin in supported clients. For example, in Claude Code:

```bash
claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
claude plugin install b2c-dx-mcp@b2c-developer-tooling --scope project
```

See the [B2C MCP guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/) for complete setup instructions and supported AI assistants. The plugins use the open [Agent Plugins](https://agent-plugins.org/) standard. For clients that require manual MCP configuration, use `npx` with arguments `--yes @salesforce/b2c-dx-mcp` as the local server command.

The MCP provides official B2C Commerce documentation search, live cartridge debugging, log investigation, deployment tools, and general-purpose SCAPI Admin API access. Your assistant can combine API requests and summarize the results, such as reviewing products and their category assignments. Available actions depend on the credentials and permissions you configure.

It also makes the `b2c`, `b2c-cli`, `storefront-next`, and `b2c-ops` skill collections available to your assistant through MCP tools. You don't need to separately install the skills plugins. You can still [install Agent Skills separately](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling-agent-skills.md) if you want skills without an MCP connection or as native skills in your assistant.

Example requests:

> Find the official guidance for Custom API authorization, then help me diagnose why my endpoint isn't registered.

> Investigate failed orders on my sandbox. Summarize the affected period, supporting evidence, and next steps before making changes.

Operational skills help your assistant correlate evidence and prepare a handoff to your team or Salesforce Support. See [Operations and Administration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/operations.html).

## Explore the Tools

- [CLI command reference](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/): Code, jobs, sandboxes, SLAS, eCDN, Managed Runtime, and more.
- [IDE Extension](https://salesforcecommercecloud.github.io/b2c-developer-tooling/vscode-extension/): Installation, cartridge development, and debugging.
- [MCP tools](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets.html): Capabilities and access requirements.
- [Agent Skills](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling-agent-skills.md): Skill collections and standalone installation.
- [TypeScript SDK](https://salesforcecommercecloud.github.io/b2c-developer-tooling/api/): Build custom tooling or inspect the behavior of the official tools.
- [GitHub repository](https://github.com/SalesforceCommerceCloud/b2c-developer-tooling): Source code, contributions, and issue reporting.

<!-- document id=b0b1471606d7f4b888d68dd6311ca009922178375807b565ac03de95b2d2163a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentic-mcp-shopper-tools-quick-start.md -->

# Agentic MCP Shopper Tools Quick Start (Pilot)

AI agents like Claude, Agentforce, and ChatGPT are powerful, but they often struggle to give truly accurate, brand-based, storefront-specific suggestions. That's why we built the B2C Commerce [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) Service, focusing on the most important users: your shoppers.

## B2C Commerce MCP Shopper Service Overview

The B2C Commerce MCP Service is a fully-hosted service for linking an AI agent to real-time B2C Commerce data access. The B2C Commerce MCP Service provides MCP tools for the agentic shopper experience, and supports the latest standards, including Google’s Agent to Agent (A2A), Model Context Protocol (MCP) /tools, HTTP SSE. Because it leverages a secure, standards-based protocol that supports robust authentication and authorization, the B2C Commerce MCP Service ensures data privacy and platform integrity.

This quick start explains how to connect an AI agent to the B2C Commerce MCP Shopper Service. It doesn't cover Salesforce Agentforce Shopper Agent setup or Shopper Agents API session initialization.

### Which approach should I use?

The B2C Commerce MCP Shopper Service and the Salesforce Agentforce Shopper Agent are separate offerings. Use this table to find the applicable path for your goal.

| Your goal                                                                                                       | What to use                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Let external AI assistants (such as ChatGPT or Claude) search your catalog, build a cart, and link to checkout. | The B2C Commerce MCP Shopper Service (this guide).                                                                                                                                                                                                                                                                                                 |
| Add a conversational Shopper Agent (chat) to your storefront.                                            | The Shopper Agent setup docs: [Set Up Salesforce Agent Guided Shopping](https://help.salesforce.com/s/articleView?id=cc.b2c_agent_guided_shopping.htm&type=5). |
| Connect the B2C Commerce MCP Service to Agentforce.                                                              | Not currently supported.                                                                                                                                                                                                                                                                                          |

**note:** The Shopper Agents API (including its `sessionInitKey`) is part of Salesforce Agentforce Shopper Agent setup, not the B2C Commerce MCP Service, and is out of scope for this quick start. In this guide, the MCP `sessionId` from the `/sse` connection is used only for MCP Service messaging calls. For Shopper Agent setup, see the Help docs linked in the table.

With the B2C Commerce MCP Service, your AI agent always has access to the most up-to-date resources (product lists, details, and images) from Salesforce B2C Commerce. External AI assistants, such as ChatGPT and Perplexity, are enabled with seamless conversational access to a brand's ecommerce capabilities, so that shoppers can use natural language to discover and buy products via the AI assistants, for example:

- Search for any product on your storefront.
- List products and product details with images.
- Add one or more products to a cart.
- Link to the checkout page.

The following image shows how the B2C Commerce MCP Service makes product data, inventory, pricing, order information, and merchant operational functions machine-readable and easily accessible to authorized AI agents.

**note:** The B2C Commerce MCP Shopper Service pilot provides the functionality shown in the **MCP Server (Tools & Data)** box.

![B2C Commerce MCP Service](https://developer.salesforce.com/docs/media/commerce-api/mcp-shopper-service-flow.png '{"class": "image-lg"}'))

## B2C Commerce MCP Service (Pilot)

The B2C Commerce MCP Service offers a range of features, such as shopper, merchant, and intelligence capabilities. The pilot program for the B2C Commerce MCP Shopper Service, however, is centered around the shopper experience.

To participate in the pilot program:

- Onboard to SLAS and use the B2C Commerce API (SCAPI).
- Contact your Salesforce account executive.

**note:** The B2C Commerce MCP Service doesn't return a `sessionInitKey`. The `sessionId` returned when connecting to the MCP Service via `/sse` is only for making additional MCP Service requests within that session.

### Configure the B2C Commerce MCP Server

To demonstrate the B2C Commerce MCP Shopper Service, we are providing a demo shopper agent that uses the OpenAI GPT API and accepts simple HTTP requests using [Agent2Agent (A2A) JSON RPC](https://www.a2aprotocol.org/en/docs/json-rpc-2-0) calls from a chat UI in your storefront.

**important:** Your AI agent configuration can vary depending on your environment. Check the documentation for your specific AI agent.

1. Configure your agent library, for example: [langchain](https://docs.langchain4j.dev/) or [Springframework.ai](https://docs.spring.io/spring-ai/reference/index.html), as part of your storefront so shoppers can ask natural language shopping questions.
2. For authentication:
   - [Create a new SLAS client ID](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#slas-admin-ui-create-a-slas-client) or update your current SLAS client ID to include the `sfcc.shopper-mcpagent` scope in the SLAS JWT scopes field.
     - All Shopper MCP APIs require a Shopper Login and API Access Service (SLAS) token. These tokens contain specific tenants, user IDs, and scopes to control data access. You can use either a guest or registered user access token.
     - Pass this access token as a Bearer Token in the Authorization header to the B2C Commerce MCP Server.
     - You can use your existing PWA-kit Storefront guest or shopper login by incorporating the SLAS JWT into your newly built chat window and making calls to the shopper agent instance that your team develops. Validate the SLAS JWT on each call to the shopper agent. The SLAS JWT serves as the API authentication for the B2C Commerce MCP Server, so it's crucial to pass the SLAS JWT through the entire process using an auth header.
     - For details, review the instructions in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).
3. Locate your B2C Commerce MCP Service tools:
   1. Call the following endpoints using your `short-code`, `org-id`, and the `mcp` family. You can find your organization’s `short-code` and tenant ID in Business Manager, for example: `kv7kzm70` and `f_ecom_zzrr_dev`, respectively.
      - `https://<short-code>.api.comm…om/mcp/shopper/v1/organizations/<org_id>/sse`
      - `https://<short-code>.api.comm…om/mcp/shopper/v1//organizations/<org_id>/mcp/messages?sessionId=<session_id>`, where `session_id` is received in the first event from the `/sse` request.
4. Create a connection for each shopper. Per the HTTP SSE spec, and leveraging Spring AI, your shopper agent calls the SSE endpoint to establish a connection with the B2C commerce MCP Server.
5. Use the B2C Commerce MCP Service tools location to call the B2C Commerce MCP Shopper Service tools/endpoints using the JSON RPC `/messaging` protocol.

## B2C Commerce MCP Shopper Service Tools

These tables summarize the available B2C Commerce MCP Service shopper tools for AI-powered product search, product detail pages with images, adding one or more products to a cart, and a link to checkout that redirects to the storefront for both guest and registered users:

### Shopper Products Tools

| **Functionality** | **Description**                              | **Parameters**                                                                                 |
| ----------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| search_product    | Get a list of products based on query value. | <ul><li>`siteId`: Site ID to search</li><li>`queryValue`: Query value for the search</li></ul> |
| get_product       | Get a specific product by ID.                | <ul><li>`siteId`: Site ID to search</li><li>`productId`: Product ID for the search</li></ul>   |

### Shopper Checkout Tools

| **Functionality**     | **Description**                                                                                              | **Parameters**                                                                                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| create_basket         | Create a basket (cart) with a product for a given site ID and usid.                                          | <ul><li>`siteId`: Site ID to search</li><li>`productId`: Product ID</li><li>`quantity`: Number of each product to add</li></ul>                                     |
| add_product_to_basket | Add a product to a cart with a given basket ID, site ID, and usid.                                           | <ul><li>`siteId`: Site ID to search</li><li>`basketId`: Cart identifier</li><li>`productId`: Product ID</li><li>`quantity`: Number of each product to add</li></ul> |
| get_basket            | Return the basket (cart) details for the given site ID and basket ID.                                        | <ul><li>`siteId`: Site ID to search</li><li>`basketId`: Cart identifier</li></ul>                                                                                   |
| remove_basket         | Remove (delete) the given basket (cart) by site ID and basket ID.                                            | <ul><li>`siteId`: Site ID to search</li><li>`basketId`: Cart identifier</li></ul>                                                                                   |
| checkout              | Start checkout for given cart ID, site, and usid. This returns a link to the configured PWA kit store front. | <ul><li>`siteId`: Site ID to search</li><li>`basketId`: Cart identifier</li></ul>                                                                                   |

## Security

In compliance with Salesforce Security Guidelines, every API requires a SLAS JWT for authentication, uses TLS over the network, monitoring and logging and auditing, and provides rate limits for all API calls.

## Restrictions

- MCP servers will have limited access to data sources, ensuring only relevant data is exposed, for example: shopper data for shopper APIs and merchant data for data APIs. The entire SCAPI API suite isn't generically exposed.
- The performance of the pilot is for demonstration purposes only and doesn't fully represent the final product's capabilities.

<!-- document id=f7c7698dcf9d6690fd425ec0e46c67eced2f0d15d831ffc13344fc624a9f0e46 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/mcp-shopper-tools.md -->

# Agentic MCP  Shopper Tools Quick Start (Pilot)

AI agents like Claude, Agentforce, and ChatGPT are powerful, but they often struggle to give truly accurate, brand-based, storefront-specific suggestions. That's why we built the B2C Commerce Model Context Protocol (MCP) Service, focusing on the most important users: your shoppers. 

For details, see [Agentic MCP  Shopper Tools Quick Start](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/agentic-mcp-shopper-tools-quick-start.md).

<!-- document id=fc15c3b50562c7bfcee1206d4f52bb661b167f3f3153cc8420e0caffa75a0526 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_aggregate_tables.md -->

# Aggregate Tables

Aggregate tables store pre-calculated summarized data, optimized for reporting and analysis.

## Robot Traffic and IP Address Filtering

### Tables Containing Robot Traffic

The following tables include robot traffic:

- `ccdw_aggr_visit_ip_address`
- `ccdw_aggr_visit_robot`

All other aggregate tables don't include robot traffic.

### IP Address Filter Impact

When you configure IP Address Filters in Business Manager, the filter applies only to customer-focused analytics tables. The following tables are **not** constrained by IP Address Filters:

- `ccdw_aggr_visit_ip_address`
- `ccdw_aggr_visit_robot`
- `ccdw_aggr_controller_request`
- `ccdw_aggr_include_controller_request`
- `ccdw_aggr_ocapi_request`
- `ccdw_aggr_scapi_request`

The following tables **are** constrained by IP Address Filters:

- `ccdw_aggr_search_conversion`
- `ccdw_aggr_search_query`
- `ccdw_aggr_visit_referrer`
- `ccdw_aggr_visit_checkout`
- `ccdw_aggr_visit`
- `ccdw_aggr_visit_user_agent`

| Aggregate Table Name                                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                         | Indices                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| [ccdw_aggr_controller_request](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_controller_request.md)                                 | Aggregates daily performance metrics for pipeline requests.                                                                                                                                                                                                                                                                                                                                         | None listed                                                                                                                               |
| [ccdw_aggr_include_controller_request](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_include_controller_request.md)                 | Aggregates daily performance metrics for include pipeline requests.                                                                                                                                                                                                                                                                                                                                 | None listed                                                                                                                               |
| [ccdw_aggr_impression](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_impression.md)                                                 | Aggregates product impression and click metrics.                                                                                                                                                                                                                                                                                                                                                    | None listed                                                                                                                               |
| [ccdw_aggr_inventory_by_location](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_inventory_by_location.md)                           | Aggregates daily inventory levels by individual location.                                                                                                                                                                                                                                                                                                                                           | None listed                                                                                                                               |
| [ccdw_aggr_inventory_by_location_group](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_inventory_by_location_group.md)               | Aggregates daily inventory levels by location group.                                                                                                                                                                                                                                                                                                                                                | None listed                                                                                                                               |
| [ccdw_aggr_ocapi_request](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_ocapi_request.md)                                           | Aggregates daily performance metrics for OCAPI requests.                                                                                                                                                                                                                                                                                                                                            | None listed                                                                                                                               |
| [ccdw_aggr_payment_sales_summary](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_payment_sales_summary.md)                           | Summarizes payment-related sales metrics by various dimensions.                                                                                                                                                                                                                                                                                                                                     | `submit_date,business_channel_id,registered,site_id,first_time_buyer,device_class_code, locale_code,payment_method_id`                    |
| [ccdw_aggr_product_cobuy](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_cobuy.md)                                           | Identifies products that are frequently bought together.                                                                                                                                                                                                                                                                                                                                            | `submit_date, product_one_id, product_two_id,registered, nsite_id,first_time_buyer,device_class_code,locale_code`                         |
| [ccdw_aggr_product_recommendation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_recommendation.md)                         | Aggregates overall product recommendation performance.                                                                                                                                                                                                                                                                                                                                              | None listed                                                                                                                               |
| [ccdw_aggr_product_recommendation_recommender](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_recommendation_recommender.md) | Aggregates product recommendation performance broken down by individual recommender.                                                                                                                                                                                                                                                                                                                | None listed                                                                                                                               |
| [ccdw_aggr_product_sales_summary](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_sales_summary.md)                           | Summarizes product sales metrics by various dimensions.                                                                                                                                                                                                                                                                                                                                             | `submit_date, business_channel_id,registered,site_id,first_time_buyer,sku_id, product_id, device_class_code,locale_code`                  |
| [ccdw_aggr_promotion_activation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_promotion_activation.md)                             | Summarizes promotion activation metrics.                                                                                                                                                                                                                                                                                                                                                            | None listed                                                                                                                               |
| [ccdw_aggr_promotion_sales_summary](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_promotion_sales_summary.md)                       | Summarizes sales attributed to promotions by various dimensions.                                                                                                                                                                                                                                                                                                                                    | `submit_date, business_channel_id,registered,site_id,first_time_buyer,promotion_id,campaign_id,coupon_id, device_class_code, locale_code` |
| [ccdw_aggr_registration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_registration.md)                                             | Summarizes customer registration activity.                                                                                                                                                                                                                                                                                                                                                          | `registration_date, site_id,locale_code, device_class_code`                                                                               |
| [ccdw_aggr_sales_summary](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_sales_summary.md)                                           | Provides a daily summary of sales metrics aggregated by various dimensions.                                                                                                                                                                                                                                                                                                                         | `submit_date, business_channel_id,registered,site_id,first_time_buyer,device_class_code, locale_code`                                     |
| [ccdw_aggr_scapi_request](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_scapi_request.md)                                           | Aggregates daily performance metrics for SCAPI requests.                                                                                                                                                                                                                                                                                                                                            | None listed                                                                                                                               |
| [ccdw_aggr_search](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_search.md)                                                         | Summarizes general search activity. <br><p>Note: `ccdw_aggr_search` aggregates data directly from visits, while `ccdw_aggr_search_query` aggregates data specifically from search events. Because these tables track different events and methods, aggregating the `ccdw_aggr_search_query` table does not reproduce the same numerical results found in `ccdw_aggr_search`.</p>                    | `search_date, registered, site_id,device_class_code,locale_code`                                                                          |
| [ccdw_aggr_search_conversion](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_search_conversion.md)                                   | Tracks conversion rates related to search queries.                                                                                                                                                                                                                                                                                                                                                  | `search_date,registered,site_id,device_class_code,locale_code,query`                                                                      |
| [ccdw_aggr_search_query](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_search_query.md)                                             | Provides details on search queries and their outcomes. <br><p>Note: `ccdw_aggr_search` aggregates data directly from visits, while `ccdw_aggr_search_query` aggregates data specifically from search events. Because these tables track different events and methods, aggregating the `ccdw_aggr_search_query` table does not reproduce the same numerical results found in `ccdw_aggr_search`.</p> | `search_date,registered,site_id,device_class_code,locale_code,query`                                                                      |
| [ccdw_aggr_source_code_activation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_source_code_activation.md)                         | Summarizes the activation of source codes.                                                                                                                                                                                                                                                                                                                                                          | None listed                                                                                                                               |
| [ccdw_aggr_source_code_sales](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_source_code_sales.md)                                   | Summarizes sales attributed to source codes.                                                                                                                                                                                                                                                                                                                                                        | None listed                                                                                                                               |
| [ccdw_aggr_visit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit.md)                                                           | Summarizes website visit activity.                                                                                                                                                                                                                                                                                                                                                                  | None listed                                                                                                                               |
| [ccdw_aggr_visit_checkout](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_checkout.md)                                         | Summarizes visitor progression through checkout steps.                                                                                                                                                                                                                                                                                                                                              | None listed                                                                                                                               |
| [ccdw_aggr_visit_ip_address](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_ip_address.md)                                     | Summarizes visits by IP address.                                                                                                                                                                                                                                                                                                                                                                    | None listed                                                                                                                               |
| [ccdw_aggr_visit_referrer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_referrer.md)                                         | Summarizes visits by referrer information.                                                                                                                                                                                                                                                                                                                                                          | None listed                                                                                                                               |
| [ccdw_aggr_visit_robot](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_robot.md)                                               | Summarizes visits identified as coming from robots/crawlers.                                                                                                                                                                                                                                                                                                                                        | None listed                                                                                                                               |
| [ccdw_aggr_visit_user_agent](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_user_agent.md)                                     | Summarizes visits by user agent details.                                                                                                                                                                                                                                                                                                                                                            | None listed                                                                                                                               |

<!-- document id=0a0ce8c5e37127bd753c24aeb4f314347192c3ca63fe12b26d336ef49e225369 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/analytics.md -->

Analytics

# Analytics

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/analytics/analytics-oas-v1-public.yaml)

## API Overview

The Commerce Intelligence API provides access to metadata and query capabilities for analytics data available in the Commerce Intelligence Platform. Use this API to discover available subject areas and their dimensions and measures, and to query data for reporting and analytics purposes.

### Features

*   **List Subject Areas**: Retrieve all available subject areas for an organization
*   **Subject Area Details**: Get detailed metadata including dimensions, measures, display names, and data types for a specific subject area
*   **Query Subject Area Data**: Query specific subject area data for reporting and analytics
*   **Flexible Filtering**: Filter by dimensions using operators such as equals, gt, lt, contains, date ranges, and more
*   **Sorting**: Order results by any field in ascending or descending order
*   **Pagination**: Built-in pagination support with configurable limit and offset

### Endpoints

#### GET /organizations/{organizationId}/subject-areas

Retrieve a list of all available subject areas in an organization.

**Parameters:**

*   `organizationId` (required) - The organization identifier

#### GET /organizations/{organizationId}/subject-areas/{subjectAreaId}

Retrieve metadata about a specific subject area, including its dimensions and measures.

**Parameters:**

*   `organizationId` (required) - The organization identifier
*   `subjectAreaId` (required) - The subject area to retrieve metadata for (e.g., orderitems)

#### POST /organizations/{organizationId}/query/{subjectAreaId}

Query subject area data within an organization. Specify dimensions, measures, filters, and ordering in the request body.

**Parameters:**

*   `organizationId` (required) - The organization identifier
*   `subjectAreaId` (required) - The subject area to query (e.g., orderitems)

### Authentication and Authorization

This API uses OAuth 2.0 client credentials flow via Account Manager with the following scope:

*   `sfcc.analytics` - Access to analytics subject areas, metadata, and query operations

**Version:** 1.0.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/intelligence/analytics/v1`
    *   `shortCode (default 0dnz6oep) A region-specific merchant identifier.`

## Security

*   `AmOAuth2` (oauth2) Account Manager OAuth 2.0 bearer token authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.analytics: Access to analytics subject areas, metadata, and query operations
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.analytics: Access to analytics subject areas, metadata, and query operations

## Operations

### GET Get Subject Areas

`GET /organizations/{organizationId}/subject-areas`

Operation ID: `getSubjectAreas`. Security: AmOAuth2 (sfcc.analytics).

Retrieve a list of subject areas.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Subject Areas Response
    
    Media type: `application/json`. Schema: `SubjectAreasResponse`.
    
    _Example: subjectAreasExample_
    
    ```
    {
      "data": [
        "orderitems",
        "sessions",
        "pageviews"
      ]
    }
    ```
    
*   **400** Malformed query or request body parameter
    
    Media type: `application/problem+json`. Schema: `MalformedParameterErrorResponse`.
    
    _Example: MalformedParameterErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-parameter",
      "detail": "The requested query or request body parameter 'subjectAreaId' is malformed.",
      "title": "Malformed Parameter"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get Subject Area by ID

`GET /organizations/{organizationId}/subject-areas/{subjectAreaId}`

Operation ID: `getSubjectAreaById`. Security: AmOAuth2 (sfcc.analytics).

Access metadata about a subject area

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `subjectAreaId` (path, SubjectAreaId, required) The subject area to retrieve metadata for or to query

#### Responses

*   **200** Subject Area Response
    
    Media type: `application/json`. Schema: `SubjectArea`.
    
    _Example: subjectAreaResponseExample_
    
    ```
    {
      "id": "orderitems",
      "displayName": "Order Items",
      "description": "Order item level data",
      "tags": [
        "orders",
        "commerce"
      ],
      "dimensions": [
        {
          "id": "utc_submit_timestamp",
          "displayName": "Submit Timestamp (UTC)",
          "description": "The UTC timestamp when the order was submitted",
          "type": "timestamp"
        },
        {
          "id": "site_name",
          "displayName": "Site Name",
          "description": "The name of the site",
          "type": "string"
        }
      ],
      "measures": [
        {
          "id": "units",
          "displayName": "Units",
          "description": "Number of units ordered",
          "type": "integer"
        },
        {
          "id": "revenue",
          "displayName": "Revenue",
          "description": "Total revenue amount",
          "type": "decimal"
        }
      ]
    }
    ```
    
*   **400** Malformed query or request body parameter
    
    Media type: `application/problem+json`. Schema: `MalformedParameterErrorResponse`.
    
    _Example MalformedParameterErrorResponseExample: same as GET /organizations/{organizationId}/subject-areas 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Subject Area Not Found
    
    Media type: `application/problem+json`. Schema: `SubjectAreaNotFoundErrorResponse`.
    
    _Example: SubjectAreaNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subject-area-not-found",
      "detail": "The requested 'orderitems' subject area was not found.",
      "title": "Subject Area Not Found"
    }
    ```
    

### POST Query subject area data

`POST /organizations/{organizationId}/query/{subjectAreaId}`

Operation ID: `querySubjectArea`. Security: AmOAuth2 (sfcc.analytics).

Query subject area data for reporting and analytics purposes. Use `limit` and `offset` in the request body to control pagination. The response echoes the original query, including pagination parameters, in the `query` object.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `subjectAreaId` (path, SubjectAreaId, required) The subject area to retrieve metadata for or to query

#### Request body (required)

The query request document

Media type: `application/json`. Schema: `QueryRequest`.

_Example: queryRequestExample_

```
{
  "dimensions": [
    "utc_submit_timestamp",
    "site_name"
  ],
  "measures": [
    "units"
  ],
  "filters": [
    {
      "dimension": "utc_submit_timestamp",
      "operator": "gt",
      "values": [
        "2020-01-01"
      ]
    }
  ],
  "order": [
    {
      "field": "utc_submit_timestamp",
      "order": "asc"
    }
  ],
  "limit": 100,
  "offset": 0
}
```

_Example: queryRequestSetOperatorExample_ Filter using set / not\_set operators

Example showing the `set` and `not_set` operators. These check for the presence or absence of a value on a dimension and do not take operands, so `values` must be an empty array (`[]`).

```
{
  "dimensions": [
    "utc_submit_timestamp",
    "site_name"
  ],
  "measures": [
    "units"
  ],
  "filters": [
    {
      "dimension": "site_name",
      "operator": "set",
      "values": []
    },
    {
      "dimension": "campaign_id",
      "operator": "not_set",
      "values": []
    }
  ],
  "limit": 100,
  "offset": 0
}
```

#### Responses

*   **200** Successful query response
    
    Media type: `application/json`. Schema: `QueryResponse`.
    
    _Example: queryResponseExample_
    
    ```
    {
      "subjectAreaId": "orderitems",
      "query": {
        "dimensions": [
          "utc_submit_timestamp",
          "site_name"
        ],
        "measures": [
          "units"
        ],
        "filters": [
          {
            "dimension": "utc_submit_timestamp",
            "operator": "gt",
            "values": [
              "2020-01-01"
            ]
          }
        ],
        "order": [
          {
            "field": "utc_submit_timestamp",
            "order": "asc"
          }
        ],
        "limit": 100,
        "offset": 0
      },
      "dimensions": [
        "utc_submit_timestamp",
        "site_name"
      ],
      "measures": [
        "units"
      ],
      "fields": [
        "utc_submit_timestamp",
        "site_name",
        "units"
      ],
      "data": [
        {
          "utc_submit_timestamp": "2020-01-01",
          "site_name": "Sites-SiteGenesis-Site",
          "units": 42
        },
        {
          "utc_submit_timestamp": "2020-01-01",
          "site_name": "Sites-SiteGenesisGlobal-Site",
          "units": 37
        },
        {
          "utc_submit_timestamp": "2020-01-02",
          "site_name": "Sites-SiteGenesis-Site",
          "units": 12
        },
        {
          "utc_submit_timestamp": "2020-01-02",
          "site_name": "Sites-SiteGenesisGlobal-Site",
          "units": 75
        }
      ]
    }
    ```
    
*   **400** Malformed query or request body parameter
    
    Media type: `application/problem+json`. Schema: `MalformedParameterErrorResponse`.
    
    _Example MalformedParameterErrorResponseExample: same as GET /organizations/{organizationId}/subject-areas 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Subject Area Not Found
    
    Media type: `application/problem+json`. Schema: `SubjectAreaNotFoundErrorResponse`.
    
    _Example SubjectAreaNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/subject-areas/{subjectAreaId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SubjectAreasResponse

*   `data` (_array of string_)  
    Items: Minimum length: 1. Maximum length: 256. Example: `orderitems`.

_Example_

```
{
  "data": [
    "orderitems",
    "sessions",
    "pageviews"
  ]
}
```

### MalformedParameterErrorResponse

Returned when a query or request body parameter is malformed.

Includes all fields of `ErrorResponse`.

*   `parameterId` (_string_)  
    Minimum length: 1. Maximum length: 256. Example: `subjectAreaId`.

_Example_

```
{
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-parameter",
  "title": "Malformed Parameter",
  "detail": "The requested query or request body parameter 'subjectAreaId' is malformed."
}
```

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SubjectAreaId

The unique identifier of the subject area

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `orderitems`.

### SubjectArea

*   `id` (_SubjectAreaId_, required)
*   `description` (_string_) Description of the subject area  
    Minimum length: 1. Maximum length: 1024. Example: `Order item level data`.
*   `tags` (_array of string_) Tags associated with the subject area  
    Items: Minimum length: 1. Maximum length: 256. Example: `orders`.
    
    _Example_
    
    ```
    [
      "orders",
      "commerce"
    ]
    ```
    
*   `displayName` (_string_, required) The display name of the subject area  
    Minimum length: 1. Maximum length: 256. Example: `Order Items`.
*   `dimensions` (_array of Dimension_, required) Array of dimension metadata for the subject area
*   `measures` (_array of Measure_, required) Array of measure metadata for the subject area

### SubjectAreaNotFoundErrorResponse

Returned when the requested subject area was not found.

Includes all fields of `ErrorResponse`.

*   `subjectAreaId` (_SubjectAreaId_)

_Example_

```
{
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subject-area-not-found",
  "title": "Subject Area Not Found",
  "detail": "The requested 'orderitems' subject area was not found.\"",
  "subjectAreaId": "orderitems"
}
```

### QueryRequest

*   `dimensions` (_array of DimensionId_, required) Array of dimension IDs to include in the query
    
    _Example_
    
    ```
    [
      "utc_submit_timestamp",
      "site_name"
    ]
    ```
    
*   `measures` (_array of MeasureId_, required) Array of measure IDs to include in the query
    
    _Example_
    
    ```
    [
      "units"
    ]
    ```
    
*   `filters` (_array of DimensionFilter | MeasureFilter_) Array of filter expressions for dimensions or measures
    
    _Example_
    
    ```
    [
      {
        "dimension": "utc_submit_timestamp",
        "operator": "gt",
        "values": [
          "2020-01-01"
        ]
      }
    ]
    ```
    
*   `order` (_array of SortOrder_) Array of ordering expressions
    
    _Example_
    
    ```
    [
      {
        "field": "utc_submit_timestamp",
        "order": "asc"
      }
    ]
    ```
    
*   `limit` (_integer_) Maximum number of results to return  
    Minimum: 1. Example: `100`.
*   `offset` (_integer_) Number of results to skip  
    Minimum: 0. Example: `0`.

### QueryResponse

*   `subjectAreaId` (_object_, required) The subject area that was queried  
    Example: `orderitems`.
    
    Includes all fields of `SubjectAreaId`.
    
    Example: `orderitems`.
    
*   `query` (_QueryRequest_, required)
*   `dimensions` (_array of DimensionId_, required) Array of dimension IDs in the response
    
    _Example_
    
    ```
    [
      "utc_submit_timestamp",
      "site_name"
    ]
    ```
    
*   `measures` (_array of MeasureId_, required) Array of measure IDs in the response
    
    _Example_
    
    ```
    [
      "units"
    ]
    ```
    
*   `fields` (_array of string_, required) Ordered list of all column keys in the response — the concatenation of `dimensions` and `measures`. Each entry is a `DimensionId` or `MeasureId` string. Provided as a convenience for tabular rendering so consumers can iterate columns in order without having to concatenate `dimensions` and `measures` themselves.  
    Items: Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`.
    
    _Example_
    
    ```
    [
      "utc_submit_timestamp",
      "site_name",
      "units"
    ]
    ```
    
*   `data` (_array of object_, required) Array of result objects containing the queried data. Each object has keys corresponding to the requested dimension and measure IDs. Value types vary based on each field's data type as described in the subject area metadata (e.g., string, integer, decimal, timestamp).

### Dimension

*   `id` (_DimensionId_, required)
*   `displayName` (_string_) The display name of the dimension  
    Minimum length: 1. Maximum length: 256. Example: `Submit Timestamp (UTC)`.
*   `description` (_string_) Description of the dimension  
    Minimum length: 1. Maximum length: 1024. Example: `The UTC timestamp when the order was submitted`.
*   `type` (_string_, required) The data type of the dimension  
    Minimum length: 1. Maximum length: 256. Example: `timestamp`.

### Measure

*   `id` (_MeasureId_, required)
*   `displayName` (_string_) The display name of the measure  
    Minimum length: 1. Maximum length: 256. Example: `Units`.
*   `description` (_string_) Description of the measure  
    Minimum length: 1. Maximum length: 1024. Example: `Number of units ordered`.
*   `type` (_string_, required) The data type of the measure  
    Minimum length: 1. Maximum length: 256. Example: `integer`.

### DimensionId

The unique identifier of the dimension

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`.

### MeasureId

The unique identifier of the measure

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `units`.

### DimensionFilter

Includes all fields of `Filter`.

*   `dimension` (_string_, required) The dimension to filter on  
    Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`.

### MeasureFilter

Includes all fields of `Filter`.

*   `measure` (_string_, required) The measure to filter on  
    Minimum length: 1. Maximum length: 256. Example: `units`.

### SortOrder

*   `field` (_string_, required) The field to order by  
    Minimum length: 1. Maximum length: 256. Example: `utc_submit_timestamp`.
*   `order` (_string_, required) The sort order (ascending or descending)  
    Allowed values: `asc`, `desc`. Example: `asc`.

### Filter

*   `operator` (_string_, required) The filter operator to apply  
    Allowed values: `equals`, `not_equals`, `contains`, `not_contains`, `gt`, `lt`, `gte`, `lte`, `set`, `not_set`, `in_date_range`, `not_in_date_range`, `before_date`, `after_date`. Example: `gt`.
*   `values` (_array of string_, required) Array of values for the filter. For operators `set` and `not_set`, which check for the presence or absence of a value, pass an empty array (`[]`) since these operators do not take operands.  
    Items: Minimum length: 1. Maximum length: 256. Example: `2020-01-01`.
    
    _Example_
    
    ```
    [
      "2020-01-01"
    ]
    ```

<!-- document id=a52cc8bc3ea88645c78a5fcb6b8af2b9fff3a59a39b951991986bcda5636899d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/doc-announcement.md -->

# Announcements

## January 2026: Developer Doc Consolidation

In response to your feedback, we've completed the **first phase** of our developer documentation consolidation. This update streamlines the developer experience by reducing fragmentation across our core product guides.

### What Has Changed?

- Unified Table of Contents (TOC): We combined the guides for **B2C Commerce**, **B2C Commerce APIs (SCAPI)**, and **Composable Storefront** into a single, shared TOC. Whether you're working in B2C Commerce or building with Composable Storefront, selecting the **Guides** tab now presents the same comprehensive navigation tree.
- Centralized API Reference: We created a new parent reference page to simplify how you access technical specifications. This single landing page serves as your starting point to navigate to different sets of API specs, ensuring you no longer have to hunt for individual reference links across different sections.
- Release Notes access: We created a new parent release notes page to simplify how you access B2C Commerce, SCAPI, and Composable Storefront release notes.

### How to Navigate the New Structure

1. Accessing Guides: Navigate to any of the three product areas (B2C Commerce, SCAPI, or Composable Storefront) and select the **Guides** tab to view the unified content list.
2. Accessing API Specs: Navigate to any of the three product areas (B2C Commerce, SCAPI, or Composable Storefront) and select the **Reference** tab. You can then choose the specific API specification you need from the centralized menu.
3. Accessing Release Notes:  Navigate to the [B2C Commerce Release Notes](https://help.salesforce.com/s/articleView?id=commerce.b2c_parent.htm&type=5) page. Or, for developer documentation release notes, you can navigate to the [B2C Commerce Developer Documentation Release Notes](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-new-and-changed-in-upcoming-release.html) page and then then choose the specific release notes from the list.


### Content Availability and Bookmarks

While the navigation is now unified, the content itself hasn't been physically moved. Your existing bookmarks should continue to function.

**important:** You might notice that the URL in your browser varies depending on whether you access a topic through the new consolidated TOC or via a direct bookmark. Both paths lead to the same source material, ensuring your saved resources remain reliable.

### Next Steps

We remain committed to further improving your documentation experience and will continue to refine and merge technical topics in upcoming phases. We will notify you as additional updates and phases of this consolidation become available.

<!-- document id=5018e01ebf709e3b2b9f03def7798b4fb104c6452bd96be3d268dcafa6f9d028 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-place-order-api-comparison.md -->

# API Comparison

Use the [Commerce Webstore Checkout Place Order Action API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm) for new implementations. It provides improved error handling, supports webhooks, processes payments asynchronously, and enables greater flexibility for modular customization.

| Feature               | Commerce Webstore Checkout Orders API (v1)                                                                                                                  | Commerce Webstore Checkout Place Order Action API (v2)                                                                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Model                 | Single-step                                                                                                                                                 | Two-step (Prepare + Submit)                                                                                                                                                                                           |
| Endpoint              | `/orders`                                                                                                                                                   | `/orders/actions`                                                                                                                                                                                                     |
| Enablement            | Available by default when the Place Order Action API is enabled                                                                                             | Requires Place Order Action API to be enabled. See Streamlined Place Order.                                                                                                                                           |
| Success Response      | 201 Created                                                                                                                                                 | 200 OK                                                                                                                                                                                                                |
| Orchestration         | After payments                                                                                                                                              | Prepare before payments, Submit after payments                                                                                                                                                                        |
| Cart States           | CHECKOUT, PENDING_CLOSED                                                                                                                                    | CHECKOUT, PENDING_CLOSED                                                                                                                                                                                              |
| Execution             | All operations in single call                                                                                                                               | Split between Prepare and Submit                                                                                                                                                                                      |
| Cart-to-Order         | Async after API call                                                                                                                                        | Async after Submit                                                                                                                                                                                                    |
| Validation Timing     | During order placement                                                                                                                                      | Split between Prepare and Submit                                                                                                                                                                                      |
| Default Validations   | Shipping and payments                                                                                                                                       | Shipping (Prepare), payments (Submit)                                                                                                                                                                                 |
| Extensions            | Not supported                                                                                                                                               | Supported for pricing, promotions, tax, shipping. See CheckoutPlaceOrder.                                                                                                                                             |
| Inventory             | Creates final reservation                                                                                                                                   | Prepare creates temporary, final during order placement                                                                                                                                                               |
| Payment Validation    | Only when V2 enabled                                                                                                                                        | Always during Submit                                                                                                                                                                                                  |
| Webhook Support       | Not supported                                                                                                                                               | Supported                                                                                                                                                                                                             |
| Orphaned Payment Risk | Higher – payments before all validations                                                                                                                    | Lower – validations before payment                                                                                                                                                                                    |
| Operations            | Performs validations, inventory handling, coupon processing, and order placement in a single API call. Cart-to-order processing is executed asynchronously. | Performs validations, inventory handling, and coupon processing during the Prepare action, and order placement during the Submit action. Cart-to-order processing is executed asynchronously after the Submit action. |

<!-- document id=f6b346b5cd834655e6111b341f5afc3a88d4f322c14ac5da6ac7749670d16c10 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/apiexplorer.md -->

# API Explorer

The API Explorer tool allows application developers to interactively explore the Open Commerce APIs in a few ways:

- Browse and review APIs.
- Test APIs by launching requests.

It’s built on [Swagger-UI](https://github.com/swagger-api/swagger-ui) and uses Swagger 2.0 specs that get delivered by the meta APIs.

## Log in to API Explorer

- Make sure that your user account has the **Documentation User** role.
- Navigate to [https://api-explorer.commercecloud.salesforce.com](https://api-explorer.commercecloud.salesforce.com).
- Authenticate yourself via Account Manager.
- Get the Swagger API schema from metadata. For the Digital API, you may have to authenticate your client application using a client id and password. If you provide a different Swagger-compatible meta API instead of a Digital meta API, then the default Swagger behavior applies, and no credentials are required.

  **note:** You can access the demo metadata at the default pre-populated URL (`https://demo-ocapi.demandware.net/s/-/dw/meta/v1/rest`) using the demo client id `{your_own_client_id}` and password `{your_own_client_id}`.

- When the metadata is validated, the APIs are displayed.

## Select a Different Instance

You can connect API Explorer to a different system as follows:

1.  Enter the target system URL in the field at the top of the page. For example, if the instance is at sandbox_domain.net, the URL might be `https://sandbox_domain.net/s/-/dw/meta/v1/rest`.
2.  Click **Authorize**. This opens the Available Authorizations popup.
3.  Click **Logout**.
4.  Enter the appropriate Client ID and Password for the system and click **Authorize**.
5.  Click **Dismiss** to close the popup.
6.  Click **Explore** to load the metadata from the new target system.

## Browse APIs

The navigation bar at the top of the page includes dropdown lists for selecting the specific API and version. Selecting an API refreshes the values available in the version dropdown. For OCAPI, you can view any version of the Data, Shop, or Meta APIs. Here are some usage examples:

- View version 24.5 of the Shop API:
  1.  Select **shop** from the Select API dropdown. This action refreshes the page so the Select API Version dropdown includes the available versions for the Shop API.
  2.  Select **24.5** from the Select API Version dropdown. This action displays the resources in the Shop API version 24.5.
  3.  Select a resource to expand its details.
- Examine the **GET /catalogs/{catalog_id}** operation.
  1.  Select **data** from the Select API dropdown list. This action refreshes the page so the Select API Version dropdown includes the available versions for the Data API.
  2.  Select **24.5** from the Select API Version dropdown list. This action displays the resources in the Data API version 24.5.
  3.  Select the **catalogs** resource. It expands to display the available endpoints.
  4.  Select the **GET /catalogs/{catalog_id}** operation. It expands to display the details of this endpoint:
      - Implementation Notes
      - Response Class (Status default) (If the operation requires authorization, then a red exclamation point icon appears on the right side of this section.)
        - Model
        - Example Value
        - Response content type
      - Parameters
      - Response Messages

## Try an HTTP Request

Here's an example of launching a request from the explorer.

1.  Select **data** from the Select API dropdown list. This action refreshes the page so the Select API Version dropdown includes the available versions for the Data API.
2.  Select **24.5** from the Select API Version dropdown list. This action displays the resources in the Data API version 24.5.
3.  Select the **catalogs** resource. It expands to display the available endpoints.
4.  Select the **GET /catalogs/{catalog_id}** operation. It expands to display the details of this endpoint.
5.  Enter `electronics-catalog` in the **catalog_id** parameter.
6.  Launch the request by clicking **Try it out!** The request and response are displayed. A successful call returns HTTP response code 200 and information about the specified catalog.

    **note:** You can copy the Curl request displayed here and paste it directly into a terminal.

## Running Requests Against Sandboxes Using the Shop API

You can use the Shop API to launch HTTP requests against specific sandboxes. To do that, enter the site ID of the sandbox (for example, `SiteGenesis`) in the **Write Site Id** field.

**note:** The **Write Site Id** field is only visible when **shop** is selected from the API dropdown.

## Log Out

You may need to log out in order to use different client credentials. Follow these steps to log out:

1.  Click **Authorize** at the top of the page. This action opens the **Available Authorizations** dialog.
2.  Click **Logout** in the dialog. This refreshes the page.

<!-- document id=a141b120df369dfbaed5008cb4d7ca338b21c6f0a4e1b22c19eaa202584b3944 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-api-integration.md -->

# API Integration Differences with PWA Kit

While both PWA Kit and Storefront Next use SCAPI for commerce functionality, they take fundamentally different approaches to API client architecture.

## Architecture

| Aspect            | PWA Kit                             | Storefront Next                             |
| ----------------- | ----------------------------------- | ------------------------------------------- |
| Package           | `@salesforce/commerce-sdk-react`    | `@salesforce/storefront-next-runtime/scapi` |
| Underlying Client | `commerce-sdk-isomorphic`           | `openapi-fetch`                             |
| Pattern           | React hooks                         | Direct API calls                            |
| Type Generation   | Manual TypeScript                   | Generated from OpenAPI specs                |
| Bundle Size       | Larger (includes React Query + SDK) | Smaller (lightweight client)                |

## API Call Location

| Aspect            | PWA Kit                              | Storefront Next       |
| ----------------- | ------------------------------------ | --------------------- |
| Reads (GET)       | Inside components via hooks          | In route loaders      |
| Writes (POST/PUT) | Inside components via mutation hooks | In action routes      |
| Authentication    | Automatic via provider               | Manual via middleware |

## Client Initialization

| Aspect | PWA Kit                    | Storefront Next                |
| ------ | -------------------------- | ------------------------------ |
| When   | Once at app root           | Per-request in loaders/actions |
| Where  | `CommerceApiProvider`      | `createApiClients()` helper    |
| Auth   | Automatic token management | Middleware injects tokens      |

## Caching

| Aspect       | PWA Kit                    | Storefront Next                  |
| ------------ | -------------------------- | -------------------------------- |
| Strategy     | React Query cache          | React Router revalidation        |
| Invalidation | Automatic after mutations  | Manual or via `shouldRevalidate` |
| Stale Time   | Configurable (default 10s) | No built-in stale time           |

## Code Examples Comparison

Fetching a product:

```jsx
// PWA Kit - in component
const { data: product, isLoading } = useProduct({
  parameters: { id: productId },
});
```

```typescript
// Storefront Next - in loader
const { data } = await clients.shopperProducts.getProduct({
  params: {
    path: { organizationId, id: productId },
    query: { siteId },
  },
});
```

Adding to Cart:

```jsx
// PWA Kit - in component
const addItem = useShopperBasketsMutation("addItemToBasket");
addItem.mutate({
  parameters: { basketId },
  body: { productId, quantity },
});
```

```typescript
// Storefront Next - in action route
const { data } = await clients.shopperBasketsV2.addItemToBasket({
  params: {
    path: { organizationId, basketId },
    query: { siteId },
  },
  body: [{ productId, quantity }],
});
```

## Key Similarities

- Both use SCAPI for commerce operations.
- Both support SLAS authentication.
- Both proxy API requests through the server.
- Both provide TypeScript support.

## Storefront Conversion Considerations

When migrating from PWA Kit to Storefront Next:

1. Move API calls to loaders: Replace `useProduct`, `useCategory`, and so on with loader fetches.
2. Move mutations to actions: Replace `useShopperBasketsMutation` with action routes.
3. Update parameter format: Change from `{ parameters: {} }` to `{ params: { path: {}, query: {} } }`.
4. Handle auth manually: Create auth middleware instead of relying on provider.
5. Remove React Query: No longer needed; caching handled by React Router.
6. Update error handling: Use `ApiError` class instead of hook error states.
7. Review non-personalized SCAPI responses: Before classifying affected requests, review custom hooks, fields, headers, schema overrides, and custom APIs. Remove explicit `personalized=none` values from individual requests when the central Storefront Next policy classifies the corresponding responses. See [Classify Non-Personalized Responses](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md#classify-non-personalized-responses).

<!-- document id=6b0b8adbaaf7d892ac42c26b9ac5de5168c241fd05d2b15debb31cac18fe194e url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/appium-setup-for-pos-ui-automation-testing.md -->

# Appium Setup for POS UI Automation Testing

Set up Appium and automate an app on a physical iPad using its bundle ID.

## Configuration & Setup

This section provides a comprehensive setup guide for configuring Appium to work with your iPad for POS UI automation testing. The setup process involves installing necessary tools, configuring Xcode, setting up WebDriverAgent, and configuring Appium Inspector. Follow each step carefully to make sure the setup is successful.

### Install Required Tools

Before setting up Xcode and WebDriverAgent, install required command-line tools and dependencies. These tools provide the foundation for iOS automation testing and ensure compatibility between your development environment and iOS devices.

#### Install Homebrew

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

#### Install Node.js and npm

```bash
brew install node
```

#### Install Appium

```bash
npm install -g appium
```

#### Install Appium Doctor

```bash
npm install -g appium-doctor
```

#### Install Carthage

```bash
brew install carthage
```

#### Install iOS Deploy

```bash
brew install ios-deploy
```

#### Verify iOS Deploy Installation

```bash
ios-deploy -c
```

### Setup Xcode

Xcode is essential for iOS development and automation. It provides the necessary tools, simulators, and device management capabilities required to work with iOS devices and WebDriverAgent.

#### Install Xcode

1. Open the Mac App Store.
2. Search for "Xcode" and install it if not already installed.

#### Verify Xcode Installation

1. Open Xcode from the Applications folder.
2. Go to **Window** > **Devices and Simulators**.
3. Make sure your iPad appears under the **Devices** tab.

#### Enable Developer Mode on iPad

1. On your iPad, go to **Settings** > **Privacy & Security**.
2. Scroll down and select **Developer Mode**.
3. Turn on **Developer Mode** and allow your iPad to restart.

#### Obtain iPad's UDID

1. Open Xcode on your Mac.
2. Go to **Window** > **Devices and Simulators**.
3. Select your iPad from the list of connected devices.
4. Copy the UDID displayed for your iPad.

### WebDriverAgent

#### Clone the WebDriverAgent Repository

```bash
git clone https://github.com/appium/WebDriverAgent.git
```

#### Navigate to WebDriverAgent Directory

```bash
cd WebDriverAgent
```

#### Bootstrap Carthage

```bash
carthage bootstrap
```

#### Open WebDriverAgent in Xcode

```bash
open WebDriverAgent.xcodeproj
```

#### Configure Signing for Targets

1. In Xcode, select the **WebDriverAgentLib** target.
2. Go to **Signing & Capabilities**.
3. Select your development team from the drop-down list.
4. Repeat steps 1-3 for the **WebDriverAgentRunner** and **IntegrationApp** targets.

#### Build and Run WebDriverAgent on the iPad

1. Select your connected iPad as the target device in Xcode.
2. Choose the **WebDriverAgentRunner** scheme.
3. Press `Cmd + R` to build and run WebDriverAgent on your iPad.

#### Troubleshooting

If the build-and-run process is not successful, try the following:

1. Install the **IntegrationApp** by selecting it as the scheme and pressing `Cmd + R`.
2. Execute a test of the **WebDriverAgentRunner** by selecting it as the scheme and pressing `Cmd + U`.

#### Access WebDriverAgent

After the test is triggered, access the WebDriverAgent at the following URL:

```bash
http://<your device IP>:8100/
```

![mceclip1.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip1.png)

![mceclip2.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip2.png)

![mceclip3.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip3a.png)

### Start Appium Server

1. Open a terminal window.
2. Run the following command:

```bash
appium
```

### Configure Appium Inspector

#### Download and Install Appium Inspector

1. Go to the [official Appium releases page](https://github.com/appium/appium-inspector/releases).
2. Download and install the latest version of Appium Inspector for your operating system.

#### Launch Appium Inspector and Configure Desired Capabilities

1. Open Appium Inspector.
2. Configure the following settings:

   - **Remote Host:** `localhost` (use your device IP if necessary)
   - **Remote Port:** `4723`
   - **Remote Path:** `/`

3. Add the following desired capabilities:

   - **platformName:** `iOS`
   - **platformVersion:** (Your iPad's iOS version, for example, `14.0`)
   - **deviceName:** (Your iPad's name, for example, `iPad`)
   - **automationName:** `XCUITest`
   - **udid:** (Your iPad's UDID)
   - **app:** (The bundle ID of the app you want to automate)

### Verify Setup

#### Start a New Session in Appium Inspector

1. Open Appium Inspector.
2. Click on the **Start Session** button.
3. The app specified by the `bundleId` should launch on the iPad.
4. You should be able to inspect and interact with the app elements.

#### Example Configuration for Appium Inspector

Here is an example of how the desired capabilities configuration should look in Appium Inspector:

```json
{
  "appium:deviceName": "PS API iPad",
  "platformName": "iOS",
  "appium:platformVersion": "17.5.1",
  "appium:automationName": "XCUITest",
  "appium:app": "com.psstore.beta.ios",
  "appium:udid": "00008030-000A69C92EA3C02E",
  "appium:xcodeSigningId": "iPhone Developer"
}
```

![mceclip4.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip4a.png)

**important:** Replace the placeholders with the actual values specific to your setup.

<!-- document id=5af6b1c8af5114a6fc715f92ef1fffec0b8ae4ff41e68a8773eceab571bf2240 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-recommendations/applications.md -->

# Applications

The following illustrations show how implementations work for some use cases.

## PWA and Mobile App

![PWA and Mobile](https://developer.salesforce.com/media/commerce-einstein-api/pwa-and-mobile.png)

## Agentforce Service

![Agentforce Service](https://developer.salesforce.com/media/commerce-einstein-api/service-cloud.png)

<!-- document id=ffe693290781727b0f471230b4935ee6a18c56e1e08164bce56364b0b7a39459 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/architecture.md -->

# Architecture Overview

Understand the Commerce Apps framework, extension points, and packaging structure.

## The Commerce Apps Framework

Commerce Apps are the "feature packaging" layer that merchants use to apply native or third-party customizations to their site and storefront. Commerce Apps support both backend and frontend (Storefront Next) code. Public apps use the centralized [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps) hosted on GitHub; private apps install from WebDAV without a registry listing. Both paths use the same install framework to bridge third-party service logic and the storefront through metadata, code, and UI orchestration.

> **Note:** The examples in this guide focus on the tax domain, but the same architectural patterns and automation workflows apply identically to all other merchant service categories (for example, address verification, ratings & reviews, and shipping).

## Architecture Hierarchy: Domain, Extension, UI Target, Component

Commerce Apps are organized in a hierarchy:

**Domains** are the top-level commerce categories: Payments, Tax, Shipping, Order Management System (OMS), Ratings & Reviews, Loyalty, Fraud, and so on. Each domain represents a functional feature area of a commerce application.

**Storefront extensions** are UI features within a domain that merchants can turn on individually. For example, the Shipping domain has separate storefront extensions for Delivery Estimation and Shipping Options & Calculations, so merchants can turn on only the features they need.

**UI targets** are named landing zones on Storefront Next pages where components render. Each extension contains one or more components that can target defined UI targets across different storefront surfaces (PDP, PLP, Cart, Checkout, My Account, and so on). Targets follow a semantic namespace: `{namespace}.{surface}.{domain}.{feature}`.

**Components** are the React elements that render within each UI target. They can come from the platform (as pre-built Storefront Next components) or from an ISV extension (replacing the platform component).

**Example:** The Ratings & Reviews domain includes extensions for Star Rating, Review Summary, Reviews List, Q&A, and Review Purchase. The Star Rating extension has UI targets on PDP (`sfcc.pdp.reviews.rating`), Product Card (shared), and Quick Add. Each target renders a component that displays the aggregate star rating for a product.

## The Three Architectures for Commerce Apps

There are three distinct architectures for building a Commerce App. Each architecture determines what goes into your Commerce App Package (CAP). The right one depends on your domain, your needs, and what platform capabilities you want to use.

### UI-Only

Your Commerce App delivers only Storefront Next extensions — React components that replace or extend platform UI targets. There is no backend cartridge or IMPEX in your CAP. This architecture is appropriate when the platform already provides the backend APIs you need, and you only want to customize the shopper-facing experience.

Your CAP includes the `storefront-next/` and `app-configuration/` directories, but no `cartridges/` or `impex/` directories.

### Backend-Only

Your Commerce App delivers only backend cartridges and IMPEX configuration — no Storefront Next extensions. This architecture is appropriate when the platform already provides the frontend components and a formal backend interface contract, and you supply only the backend logic that fulfills that contract.

You implement platform-defined extension point hooks (for example, `sfcc.app.tax.calculate` or `sfcc.app.oms.order.retrieve`). The platform provides both the frontend components (where the domain has storefront UI) and the extension point interface — you implement only the script API endpoints. This is the most turnkey approach, but it requires the platform to have defined extension points for your domain. Tax and OMS currently have live extension points.

Your CAP includes the `cartridges/`, `impex/`, and `app-configuration/` directories but no `storefront-next/` directory.

### Fullstack

Your Commerce App delivers both Storefront Next extensions and backend cartridges. You own the full stack for your feature: frontend components, backend SCAPI or service integrations, and all data handling. This architecture gives you full creative and functional control over both the UX and the data layer.

Your CAP includes the `storefront-next/`, `cartridges/`, `impex/`, and `app-configuration/` directories.

There are two sub-types of fullstack apps:

#### Extension Points

You replace the platform's default UI components with your own Storefront Next extensions, and your backend implements platform-defined extension point hooks. The platform defines the backend interface contract — you supply the hook implementations that fulfill it. This sub-type is available for domains where the platform has defined formal extension points.

#### Custom SCAPI

You replace the platform's default UI components with your own Storefront Next extensions, and your backend is a custom SCAPI that supplies data to those components. No platform-defined extension points are required — you define your own API contract. This sub-type is available for any domain, even if the platform hasn't defined formal extension points yet.

## Commerce App Package (CAP) Structure

A CAP is a standardized `.zip` file with the following directory layout:

```
commerce-{app-name}-app-v{n.n.n}/
├── commerce-app.json                  # App metadata (required)
├── README.md                          # Documentation (required)
├── app-configuration/
│   ├── tasksList.json                 # Post-install merchant setup steps (required)
│   ├── adminComponents.json           # BM admin UI components (optional)
│   └── translations/                  # Localized BM-rendered strings (optional)
│       ├── en-US.json                 #   required when translations/ exists
│       ├── de.json
│       └── ja.json
├── icons/                             # App icon (required)
│   └── {isv-name}.png                 # CI extracts to commerce-apps-manifest/icons/
├── cartridges/                        # Backend-only or Fullstack apps
│   ├── site_cartridges/
│   │   └── int_cartridge_name/
│   │       ├── package.json
│   │       ├── cartridge/scripts/
│   │       │   ├── hooks.json         # Registers hooks with the platform
│   │       │   ├── hooks/             # Hook implementations
│   │       │   ├── helpers/           # Business logic
│   │       │   └── services/          # Service framework wrappers
│   │       └── test/                  # Unit tests
│   └── bm_cartridges/                 # Business Manager extensions (optional)
│       └── bm_cartridge_name/
│           └── cartridge/
│               ├── controllers/
│               └── scripts/
├── storefront-next/                   # UI-only or Fullstack apps
│   └── src/extensions/{app-name}/
│       ├── target-config.json         # Maps components → UI targets
│       ├── index.ts                   # Barrel exports
│       ├── components/                # React components
│       └── locales/                   # i18n translation files
│           ├── en-US/translations.json
│           ├── en-GB/translations.json
│           └── it-IT/translations.json
├── impex/                             # Backend-only or Fullstack apps
│   ├── install/
│   │   ├── jobs.xml
│   │   ├── services.xml
│   │   ├── meta/
│   │   │   ├── system-objecttype-extensions.xml
│   │   │   └── custom-objecttype-definitions.xml
│   │   └── sites/SITEID/
│   │       └── preferences.xml
│   └── uninstall/                     # Cleanup for uninstalled apps
│       └── services.xml
```

## Extension Points and Domain Isolation

Commerce Apps introduce domain-specific extension points that replace the legacy shared hooks (both business defined hooks like `dw.order.calculate` and general before/after SCAPI hooks). This eliminates code conflicts where multiple integrations (for example, two tax providers) compete for the same hook.

| Domain   | Commerce Action     | Legacy Hook                                          | Commerce App Extension Point  |
| :------- | :------------------ | :--------------------------------------------------- | :---------------------------- |
| Tax      | Any basket mutation | `dw.order.calculateTax`                              | `sfcc.app.tax.calculate`      |
| Tax      | Order creation      | `dw.order.createOrderNo`                             | `sfcc.app.tax.commit`         |
| Tax      | Payment/order fails | N/A                                                  | `sfcc.app.tax.cancel`         |
| OMS      | Retrieve one order  | N/A                                                  | `sfcc.app.oms.order.retrieve` |
| OMS      | List customer orders | N/A                                                 | `sfcc.app.oms.order.list`     |
| OMS      | Cancel or return     | N/A                                                  | `sfcc.app.oms.order.cancel` or `sfcc.app.oms.order.return` |
| Shipping | Calculate rates     | `dw.order.calculateShipping`                         | `sfcc.app.shipping.calculate` |
| Fraud    | Pre-auth check      | `dw.ocapi.shop.basket.payment_instrument.beforePOST` | `sfcc.app.fraud.preAuth`      |
| Fraud    | Post-auth check     | `dw.ocapi.shop.basket.payment_instrument.afterPOST`  | `sfcc.app.fraud.postAuth`     |

> **Note:** Tax and OMS extension points are live. See [Supported Domains](/docs/commerce/b2c-commerce/guide/supported-domains.md) for the full domain timeline, and [Connect a Third-Party OMS](/docs/commerce/b2c-commerce/guide/connect-third-party-oms.md) for the OMS contracts.

## UI Targets Framework

The UI Targets framework is how Commerce Apps deliver frontend components to the storefront. It is a build-time mechanism, not a runtime injection.

**How it works:** The core Storefront Next application defines explicit placeholders using `<UITarget targetId="..." />` React components. These contain no business logic and serve only as injection points. During the build process, a Vite plugin replaces UITarget entries with the actual React components specified in the extension's `target-config.json`.

**Naming convention:** Platform-defined targets use the `sfcc` namespace: `sfcc.{surface}.{domain}.{feature}`. For example, `sfcc.pdp.reviews.rating` identifies the star rating component location on the product detail page.

**Custom namespaces:** SI partners and customers can create their own UI targets with their own namespace prefix (not `sfcc`). This makes the target's framework extensible beyond platform-defined locations.

**Installation mechanism:** When storefront PR creation is requested, the install job processes eligible Storefront Next or cartridge content from the CAP and attempts to create a pull request against the merchant's Storefront Next repository. The PR includes the extension code and target configuration. The branch is named `commerce-app-install/{app-name}/{version}/{site-id}` and the PR title follows the pattern `[Commerce App] Add {app-name} {version} storefront UI`. When PR creation succeeds, a "Merge Storefront PR" task is prepended to the merchant's configuration task list. Components become part of the merchant's build after the PR is merged.

**Manual integration:** If the merchant prefers not to use the automated pull request flow (for example, when installing from Business Manager without GitHub integration configured), they can use `b2c cap pull` to download the installed app package. The `storefront-next/` extensions and `cartridges/` can then be reviewed and integrated into the merchant's storefront and cartridge projects through their standard source control and deployment processes. See [b2c cap pull](/docs/commerce/b2c-commerce/guide/development-environment.md#b2c-cap-pull) for details.

## Installation and State Machine

Commerce App installation is tracked at the site level but the app's artifacts are deployed at the instance level. Cartridges, service definitions, custom object types, and other instance-scoped resources are shared across all sites on the instance. However, each site has its own installation record (`CommerceFeatureState`), its own cartridge path entry, and its own configuration state. This means a merchant installs an app per site, but the underlying code and instance resources are only deployed once and shared.

### Happy Path

The standard lifecycle from installation through activation:

`INSTALLING` → `INSTALLED` → `NOT_CONFIGURED` → `CONFIGURING` → `CONFIGURED`

- **INSTALLING:** The platform is processing the CAP. It unpacks the archive, deploys cartridges to the active code version, executes IMPEX data imports, and optionally attempts a storefront pull request when requested.
- **INSTALLED:** Code is deployed and metadata is imported, but the app isn't yet active. The merchant completes the configuration tasks.
- **NOT_CONFIGURED:** The app is installed but configuration hasn't started yet. To begin, the merchant opens the setup wizard.
- **CONFIGURING:** The merchant has started but not yet finished the setup wizard (defined by `tasksList.json`). Tasks can include verifying API credentials, setting site preferences, or running a test transaction.
- **CONFIGURED:** All configuration tasks are complete. The platform automatically transitions to this state when the last task is marked complete. The app is now active and the app extension point hooks begin executing.

### Error Paths

- `INSTALLING` → `INSTALL_FAILED` — The installation job encountered an error. Check system job logs for details.
- `CONFIGURING` → `CONFIGURATION_FAILED` — Configuration encountered an error during the setup process.

### Uninstall Flow

Any post-install state (`INSTALLED`, `NOT_CONFIGURED`, `CONFIGURING`, or `CONFIGURED`) can transition to `UNINSTALLING`:

`{any post-install state}` → `UNINSTALLING` → `UNINSTALLED`

- **UNINSTALLING:** The platform is removing the app. This includes removing cartridges from the site's cartridge path, and — if this is the last site using the app — deleting cartridge files and executing uninstall IMPEX.
- **UNINSTALLED:** The app has been successfully removed from the site.
- **UNINSTALL_FAILED:** The uninstallation job encountered an error (`UNINSTALLING` → `UNINSTALL_FAILED`). Check system job logs for details.

### Per-Site Tracking

State is tracked per-site in the `CommerceFeatureState` system object. Site A can have an app fully configured while Site B is still in progress, even though they share the same code baseline.

## Two Ways to Install

Install Commerce Apps using either method:

**Business Manager (no-code, registry apps):** Navigate to the Cart & Checkout Hub in Business Manager, select a registry Commerce App, and click Install. The platform handles the installation. After installation, you're redirected to a configuration task list.

**CLI (pro-code, private or local CAPs):** Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md#run-the-b2c-cli) to validate your CAP (`b2c cap validate`), package it (`b2c cap package`), and install it on a target instance (`b2c cap install`). The CLI handles packaging, WebDAV upload, and job execution automatically. See [Development Environment Setup](/docs/commerce/b2c-commerce/guide/development-environment.md) for the full command reference.

<!-- document id=720e4d55c29e763c39b1771a110e67e2ed9c933fdcf4b431eb9a6149f4dc11c3 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/assignments.md -->

Assignments

# Assignments

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/assignments/assignments-oas-v1-public.yaml)

## API Overview

Use the Assignments API to search for promotions associated with campaigns.

For more information, see [Campaigns and Promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_campaigns_and_promotions.htm&type=5) in the B2C Commerce documentation.

### Authentication & Authorization

The client requesting the promotion information must have access to the Promotion resource. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account Manager to log in.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Find All Associated Promotions

Use the Assignments API to find all associated promotions for a given campaign.

### Related APIs

*   [Campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns?meta=Summary) — Manage campaigns that contain assignments.
*   [Promotions (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions?meta=Summary) — Manage promotions referenced by assignments.

**Version:** 1.0.39

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/assignments/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.promotions: promotions READONLY
    *   Scope sfcc.promotions.rw: promotions read/write
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### POST Search for promotion campaign assignments.

`POST /organizations/{organizationId}/assignments`

Operation ID: `assignmentsSearch`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

The promotion campaign assignment search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets.

The following is a list of searchable attributes with their corresponding buckets:

main:

| Attribute | Type |
| --- | --- |
| rank | Integer |
| startDate | Date |
| endDate | Date |

campaign:

| Attribute | Type |
| --- | --- |
| campaign | String |

promotion:

| Attribute | Type |
| --- | --- |
| promotionId | String |
| description | String |
| enabled | Boolean |

special handling:

| Attribute | Type |
| --- | --- |
| couponId | String |

Only fields in the same bucket can be joined using a disjunction (or). For instance, when joining campaignId and rank, only a conjunction (and) is allowed, while promotionId and description can be joined using a disjunction because they are in the same bucket. Special handling fields must always use conjunctions. If the field is used in a disjunction that violates this rule, an exception is thrown.

Note that only searchable attributes can be used in sorting.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SearchRequest`.

#### Responses

*   **200** Promotion campaign information successfully returned.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignmentSearchResult`.
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PromotionCampaignAssignmentSearchResult

Document representing a promotion campaign assignment search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of PromotionCampaignAssignment_, required) The sorted array of campaign search hits. Can be empty.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### PromotionCampaignAssignment

Document representing a promotion campaign assignment.

*   `campaign` (_object_, required) The campaign.
    
    Includes all fields of `Campaign`.
    
*   `campaignId` (_string_, required) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_, required) The sorted array of assigned coupon IDs.
*   `customerGroups` (_array of string_, required) The sorted array of assigned customer groups.
*   `description` (_string_, required) The description of the promotion campaign assignment.  
    Maximum length: 4000.
*   `enabled` (_boolean_, required) True if the assignment resource is enabled.
*   `promotion` (_object_, required) The promotion.
    
    Includes all fields of `Promotion`.
    
*   `promotionId` (_string_, required) The ID of the promotion.  
    Minimum length: 1. Maximum length: 256.
*   `rank` (_integer (int32)_, required) The rank of promotion campaign assignment.
*   `schedule` (_object_, required) The schedule of the assignment resource.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeGroups` (_array of SourceCodeGroupId_, required) The sorted array of assigned source code groups.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Campaign

Document representing a campaign.

*   `campaignId` (_CampaignId_, required)
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted.
    
    _Example_
    
    ```
    [
      "20%offOrder",
      "10%offWelcomeNewUser"
    ]
    ```
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `customerGroups` (_array of string_) The array of assigned customer groups, not sorted.
    
    _Example_
    
    ```
    [
      "BigShoppers",
      "NorthAmericanShoppers"
    ]
    ```
    
*   `description` (_string_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.  
    Example: `true`.
*   `endDate` (_string (date-time)_) The date the scenario ends.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `sourceCodeGroups` (_array of string_) The array of assigned source code groups, not sorted.
    
    _Example_
    
    ```
    [
      "affiliate-email",
      "gaming-email"
    ]
    ```
    
*   `startDate` (_string (date-time)_) The date the scenario begins.  
    Example: `2019-10-03T19:36:56.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Promotion

Document representing a promotion. Unless otherwise stated, attributes of this document are not supported when using the Open Commerce API to update multiple promotions at once.

*   `archived` (_boolean_) Determines if this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `assignmentInformation` (_object_) Information about the assignments and assignment schedules of this promotion.
    
    Includes all fields of `PromotionAssignmentInformation`.
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.
*   `currencyCode` (_string_) The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.  
    Maximum length: 3.
*   `disableGloballyExcluded` (_boolean_) Determines if this promotion ignores the global product exclusions for promotions.
*   `enabled` (_boolean_) Determines if this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `exclusivity` (_string_, required) Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Allowed values: `no`, `class`, `global`.
*   `id` (_string_, required) The ID for the promotion.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.
*   `name` (_object_) The user supplied name of this promotion, which can be localized.
    
    Additional properties: `string`.
    
*   `promotionClass` (_string_) The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, are reset.  
    Allowed values: `product`, `shipping`, `order`.
*   `tags` (_array of Tag_) Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags are removed.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Schedule

Document representing a time schedule. Defines an optional validity window (startDate/endDate) and an optional recurrence. Omitting a bound leaves that side of the window open (unbounded).

*   `startDate` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-31T23:59:59.000Z`.
*   `recurrence` (_object_) The recurrence of the schedule by day of week and time of day. Not all schedules support a recurrence.
    
    Includes all fields of `Recurrence`.
    

### SourceCodeGroupId

The ID of source code group.

Type: `string`.

Minimum length: 1. Maximum length: 28. Example: `TV-Email`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CampaignId

The ID of the campaign.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.

### PromotionAssignmentInformation

*   `abtestId` (_string_, required) If there is only one assignment, and that assignment is an A/B test segment, the ID of the A/B test the segment belongs to. Otherwise, empty.
*   `abtestSegmentId` (_string_, required) If there is only one assignment, and that assignment is an A/B test segment, the ID of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_, required) True if the individual assignment or the multiple assignments are currently active.
*   `activeAbtestAssignments` (_array of PromotionAbtestGroupAssignment_, required) A list of currently active A/B tests this is assigned to.
*   `activeCampaignAssignments` (_array of PromotionCampaignAssignment_, required) A list of currently active campaigns this is assigned to.
*   `campaignId` (_string_, required) If there is only one assignment, and that assignment is a campaign, the ID of the campaign. Otherwise, empty.
*   `enabled` (_boolean_, required)
*   `endDate` (_string (date-time)_, required) The end date of the container of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null. Also, a null date returns null.
*   `schedule` (_object_, required) The schedule of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null.
    
    Includes all fields of `Schedule`.
    
*   `scheduleType` (_string_, required) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (scheduleType : "campaign" or scheduleType : "abtest"). If there are no assignments, it is scheduleType : "none", otherwise, scheduleType : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `startDate` (_string (date-time)_, required) The start date of the container of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null. Also, a null date returns null.
*   `upcomingAbtestAssignments` (_array of PromotionAbtestGroupAssignment_, required) A list of upcoming A/B tests this is assigned to.
*   `upcomingCampaignAssignments` (_array of PromotionCampaignAssignment_, required) A list of upcoming campaigns this is assigned to.

### Tag

Document representing a tag

*   `tagId` (_string_, required) The ID of the tag.

### Recurrence

Document representing a schedule recurrence.

*   `dayOfWeek` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Example: `monday`.
*   `timeOfDay` (_object_) The time of the day for recurrence.
    
    Includes all fields of `TimeOfDay`.
    

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### PromotionAbtestGroupAssignment

*   `abtestDescription` (_string_, required)
*   `abtestId` (_string_, required)
*   `enabled` (_boolean_, required)
*   `schedule` (_Schedule_, required)
*   `segmentDescription` (_string_, required)
*   `segmentId` (_string_, required)

### TimeOfDay

Document representing a time schedule within a single day.

*   `timeFrom` (_string_) The time to start from. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `09:00:00`.
*   `timeTo` (_string_) The time to end on. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `17:00:00`.

<!-- document id=adcf23f48cd28251be84355ee52653c853896515f204c290dc261b5cf706074b url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-authentication.md -->

# Authentication and Authorization

To make sure that the setup is complete, you must provide a scope for custom code execution and also a scope for API administration:

- Functional scopes (`c_` prefix): These custom scopes authorize the execution of your specific business logic. They handle the request authorization for the code itself.
- Diagnostic/Administrative Scope (`sfcc.custom-apis` and `sfcc.custom-apis.rw`): This scope is required to access the DX API. While your `c_` scope runs your custom code, the `sfcc.custom-apis` scope provides the necessary visibility into the registration status and scaffolding of the Custom API framework.

Custom APIs must be secured by a security scheme which includes exactly one functional scope. Custom API clients must obtain a token with the required scope. To secure your custom endpoints and make authorized requests to them, complete the following steps:

1. Choose a security scheme and custom scope for the endpoint.
2. Update your API client to include the custom scope in tokens.

The [Custom APIs DX endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=getEndpoints) uses an Account Manager OAuth 2.0 bearer token for authentication and you must specify one of the following scopes to access this API endpoint:

`sfcc.custom-apis`: Provides read-only access.
`sfcc.custom-apis.rw`: Provides read-write acc

For additional Custom API DX details, see [Custom APIs Authentication and Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=Summary).

## Secure Endpoints

Your Custom API endpoints must be associated with a security scheme in the API contract.

- `ShopperToken`: For Shopper APIs and storefront use cases. Use [Shopper Login and API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md) to obtain tokens.
- `AmOAuth2`: For SCAPI Admin APIs to be used with backoffice apps. Use [Account Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md) to obtain tokens.

Association is either per operation or global, with the operation scheme taking precedence. The schemes are the same as those used for non-custom B2C Commerce APIs (SCAPI).

The scheme must set exactly one custom scope.

Schemes used in the contract must be defined in the `components` section, for example:

```yaml
components:
  securitySchemes:
    ShopperToken: {}
    AmOAuth2:
      type: oauth2

# 👇 A global scheme applies to all operations in this file.
security:
  - AmOAuth2: ["c_loyalty_rw"]

paths:
  /customer:
    get:
      operationId: getLoyaltyInfo
      parameters:
        - in: query
          name: siteId
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        200:
          description: OK
      # 👇 An operation scheme applies only to this operation and takes precedence over the global scheme.
      security:
        - ShopperToken: ["c_loyalty"]
```

Custom scopes must meet the following requirements:

- The name must begin with `c_`.
- The name must not contain characters other than alphanumeric, period, hyphen and underscore.
- The name must not be more than 25 characters.

Endpoints without correct scheme or scope assignments are not registered.

You can review registration errors by searching in the Log Center for messages with a category that includes `CustomApiRegistry`.

## Request Endpoints

### ShopperLogin

Scopes for `ShopperLogin` can be assigned to a client in the [SLAS Admin UI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html). For example:

![Custom API SLAS scope configuration and permissions](https://developer.salesforce.com/docs/media/commerce-api/custom-api-slas-scopes.png)

To obtain a SLAS token, follow the steps in the [Shopper Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) overview.

### AmOAuth2

Custom scopes for `AmOAuth2` can be assigned to a client in [Account Manager](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html). For example:

![Account Manager OAuth2 scopes configuration for Custom APIs](https://developer.salesforce.com/docs/media/commerce-api/custom-api-amoauth2-scopes.png)

To obtain an Account Manager token follow the steps in the [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) guide.

Unauthorized requests receive a `401 Unauthorized` response.

## Complete Security Scheme Definition

While endpoint registration does not require the complete definition of the security schemes, it can be useful to have a complete and valid scheme to enable the creation of documentation, tests and code stubs, and mock requests. The following code provides a complete example:

```yaml
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize
          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes:
            c_my-scopes: description of my-scopes
        clientCredentials:
          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes:
            c_my-scopes: description of my-scopes
    AmOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes:
            c_my-scopes: description of my-scopes
        clientCredentials:
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes:
            c_my-scopes: description of my-scopes
```

<!-- document id=221ec340eefe9218d1a078dbe296ba5b67246c89f68bbb4b2114d5d14a78e0c5 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/authorization.md -->

# Authorization

Authorization for the B2C Commerce API resources is handled not through user permissions, but through _client_ permissions.

A client for the B2C Commerce API can take many forms: anything from an online storefront to custom merchandising tools.

To authorize this wide range of client types, we’ve defined a set of scopes based on the OAuth 2.1 standard. The [available scopes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/auth-z-scope-catalog.md) give you control over exactly what clients are authorized to do with the SCAPI Admin APIs and Shopper APIs.

**important:** Not all endpoints use the same security scheme for authorization. Always check the Security section of the endpoint documentation, which is hidden by default.

## Access Tokens

Both the Admin and Shopper APIs are authorized using an access token in the form of a [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token) (JWT).

Using JWTs offers the following benefits:

- Coarse-grained client permissions with read-only and read-write permissions.
- Allows you to grant the same permissions for multiple B2C Commerce instances.
- Standardized, mature, and established technology.

The JWT access tokens for both SCAPI Admin APIs and Shopper APIs are included in your API requests as an HTTP header that follows the [Bearer authentication scheme](https://swagger.io/docs/specification/authentication/bearer-authentication/).

**important:** The SCAPI Admin APIs and Shopper APIs each have their own mechanisms for setting up API clients and requesting access tokens.

## Quick Path to a Token

| I need a... | Fastest path |
|-------------|-------------|
| **Shopper API token** | Create a SLAS client ([guide](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md)), then call the `/token` endpoint ([SLAS overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md)). |
| **Admin API token** | Create an API client in Account Manager ([guide](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md)), then POST to `oauth2/access_token`. |

For a runnable example that fetches a token and calls an endpoint, see [Make Your First Request](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-get-started.md#make-your-first-request).

## Next Steps

- To set up SCAPI Admin API access, see the [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md) guide.
- To set up Shopper API access, see the [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md) guide.
- For advanced SLAS topics (grant types, token types, refresh tokens), see the [SLAS overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md).
- Review the complete [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/auth-z-scope-catalog.md).

<!-- document id=11cb59db011461a2afdaafcfb3c9fa8d84271679ee6dc9d1e31caeddef1f5a13 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/authorization-for-admin-apis.md -->

# Authorization for SCAPI Admin APIs

Learn how to create an API client in Account Manager and use the API client’s credentials to request an access token for the SCAPI Admin APIs.

**important:** - SCAPI Admin APIs are secured with Account Manager, but SCAPI Shopper APIs are secured with the Shopper Login and API Access Service (SLAS). This guide _only_ covers how to access the SCAPI Admin APIs. To learn how to access the Shopper APIs, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).
- Calls to SLAS Admin APIs require the role **Sandbox API User**.
- For the Account Manager API Client secret, only use alphanumeric passwords.

## Before You Begin

Before you create your API client (or clients) for accessing the SCAPI Admin APIs, you must compile a list of OAuth scopes for each API family that you need to access. All the available scopes are listed in the [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/auth-z-scope-catalog.md).

To use CDN Zones, for example, add the following scopes to your list:

```text
sfcc.cdn-zones
sfcc.cdn-zones.rw
```

After you’ve compiled your list of scopes, come back to this guide and read on. Your list is needed when it comes time to populate the **Allowed Scopes** field in Account Manager.

## Create an API Client

To use the SCAPI Admin APIs, you (or someone with administrator access) must first create an API client by following these steps:

1. Log in to [Account Manager](https://account.demandware.com/).
2. Click **API Client** from the left navigation.
3. Click **Add API Client**.
4. In the **Display Name** field, enter unique and descriptive name for the API client. Example: Admin Client for Pia Larson.
5. In the **Password** field, enter a secure password.
6. In the **Confirm Password** field, reenter the password.
7. Save the password (also known as the client secret) in a password manager or other secure location.
8. Go to the **Organizations** section and do the following:
   1. Click **Add**.
   2. Select one or more organizations.
   3. Click **Add**.
9. Go to the **Roles** section and do the following:
   1. Click **Add**.
   2. Look for the **Salesforce Commerce API** category and select the `Salesforce Commerce API`.
   3. Click **Add**.
   4. Click the filter button.
   5. Select an organization.
   6. For each instance that you want to access with the API client:
      1. Select the instance.
      2. Click **Add**.
10. Go to the **OpenID Connect** section and do the following:

    1. In the **Default Scopes** field, enter the following scopes (on separate lines):

    ```text
    mail
    roles
    tenantFilter
    profile
    openId
    ```

    2. In the **Allowed Scopes** field, enter the list of scopes that you prepared earlier. Enter each scope on a separate line.

       **important:** - Do not add shopper-related scopes to Account Manager clients.
       - Do not add data- or admin-related scopes to SLAS clients.
       - The previous actions cause token bloat and do not work as expected.

    3. For the **Token Endpoint Auth Method** field, select `client_secret_post`.
    4. For the **Access Token Format** field, select `JWT`.

11. In the **Redirect URIs** field, add `http://localhost:8080`.
12. Click **Save**.
13. Find your new API client in the table of API clients that appears after saving.
14. Copy the value in the **API Client ID** column of the table. Example: `1d763261-6522-4913-9d52-5d947d3b94c4`.important
An API client that is used for the B2C Commerce API can’t be used with the [Open Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html) (OCAPI), and vice versa. Each API framework (B2C Commerce API and OCAPI) requires its own API client. Also, an API client that is meant for OCAPI must not have the role “Salesforce Commerce API” assigned to it.
:::

## Request an Access Token

To request an access token for the SCAPI Admin APIs, make a request to Account Manager’s `oauth2` resource.

Get an access token with the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'

npx @salesforce/b2c-cli auth token \
  --auth-scope sfcc.cdn-zones \
  --auth-scope SALESFORCE_COMMERCE_API:{realm}_{instance}
```

For a complete list of authentication CLI commands, see [Auth Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/auth.html).

**note:** In the examples provided, we’re using Unix shell commands to set environment variables to simplify the formation of the request. If you’re not using a Unix-based operating system, do the string replacement manually or use a tool like Postman to handle variable substitution.

### Credentials String

In your request, you must provide a credentials string in the HTTP header that is composed of your client ID, followed by a colon (`:`), followed by your client secret (password). The `client_id` is a universally unique identifier (UUID) for the API client.

Use the following commands to format the credentials string correctly and save it as an environment variable.

Before running the following commands, replace the example client ID (`1d763261-6522-4913-9d52-5d947d3b94c4`) and example client secret (`GS8KmdDEUKfWnEnv`) with the credentials for the API client that you created earlier.

```bash
export "SFCC_OAUTH_CLIENT_ID=1d763261-6522-4913-9d52-5d947d3b94c4"
export "SFCC_OAUTH_CLIENT_SECRET=GS8KmdDEUKfWnEnv"
export "SFCC_CREDENTIALS=${SFCC_OAUTH_CLIENT_ID}:${SFCC_OAUTH_CLIENT_SECRET}"
```

### The Scope Parameter

Your request must also include additional information using the `scope` query parameter.

Although you can add roles for multiple instances to an API client, you can only request an access token for one instance at a time. To identify the instance that you want to associate with the access token, set its realm ID and instance ID as environment variables.

Before running the following commands, replace the example realm ID (`zzte`) and example instance ID (`053`) with the values for your B2C Commerce instance. (To learn how to look up these values, see the [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md) guide.)

```bash
export "SFCC_REALM_ID=zzte"
export "SFCC_INSTANCE_ID=053"
```

There’s one more string you must include in the `scope` parameter: a space-separated list of requested scopes. The requested scopes are checked against the list allowed scopes that you configured earlier for the client ID.

For our example, we only need one scope (`sfcc.catalogs`). If you’re requesting multiple scopes, separate them with spaces.

```bash
export SFCC_OAUTH_SCOPES=sfcc.catalogs
```

**important:** If you include the `-rw` version for a scope, avoid using the read-only counterpart, as it is redundant. This applies to both Account Manager and SLAS client scopes, but is particularly important for SLAS shopper access calls, since SLAS provides all scopes in the token, and redundancy can make the token unnecessarily bulky.

### HTTP Request

Now that you’ve collected all the strings for the `oauth2` endpoint, request an access token using an HTTP request like this:

```bash
curl "https://account.demandware.com/dwsso/oauth2/access_token" \
--request 'POST' \
--user "$SFCC_CREDENTIALS" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data "grant_type=client_credentials" \
--data-urlencode "scope=SALESFORCE_COMMERCE_API:${SFCC_REALM_ID}_${SFCC_INSTANCE_ID} $SFCC_OAUTH_SCOPES"
```

If you’re not using environment variables, make sure to do the manual string replacement before running the `curl` command. Here’s what the same command looks like with example strings instead of environment variables:

```bash
curl "https://account.demandware.com/dwsso/oauth2/access_token" \
--request 'POST' \
--user "1d763261-6522-4913-9d52-5d947d3b94c4:GS8KmdDEUKfWnEnv" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data "grant_type=client_credentials" \
--data-urlencode "scope=SALESFORCE_COMMERCE_API:zzte_053 sfcc.catalogs"
```

**note:** Note that only the `client_credentials` grant type is supported for accessing SCAPI Admin APIs.

### Success Response

A successful request returns your access token as part of a JSON object:

```json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiJEMWhPUDdEODN4TjBqZWlqaTI3WWFvZFRjL0E9IiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIxZDc2MzI2MS02NTIyLTQ5MTMtOWQ1Mi01ZDk0N2QzYjk0YzQiLCJjdHMiOiJPQVVUSDJfU1RBVEVMRVNTX0dSQU5UIiwiYXVkaXRUcmFja2luZ0lkIjoiZDBkZDk4MjItMmI3ZC00MThiLTkzZTktYzg2YjgxYjZjZGFhLTE2OTY2NTI3MSIsInN1Ym5hbWUiOiIxZDc2MzI2MS02NTIyLTQ5MTMtOWQ1Mi01ZDk0N2QzYjk0YzQiLCJpc3MiOiJodHRwczovL2FjY291bnQuZGVtYW5kd2FyZS5jb206NDQzL2R3c3NvL29hdXRoMiIsInRva2VuTmFtZSI6ImFjY2Vzc190b2tlbiIsInRva2VuX3R5cGUiOiJCZWFyZXIiLCJhdXRoR3JhbnRJZCI6IjcyWTZ0Slk1bm9vdEhMX2YzLWN5SzZrajVsOCIsImF1ZCI6IjFkNzYzMjYxLTY1MjItNDkxMy05ZDUyLTVkOTQ3ZDNiOTRjNCIsIm5iZiI6MTY1MTYyMjUzOCwiZ3JhbnRfdHlwZSI6ImNsaWVudF9jcmVkZW50aWFscyIsInNjb3BlIjpbIlNBTEVTRk9SQ0VfQ09NTUVSQ0VfQVBJOnp6dGVfMDUzIiwic2ZjYy5jYXRhbG9ncyIsIm1haWwiLCJ0ZW5hbnRGaWx0ZXIiLCJvcGVuSWQiLCJyb2xlcyJdLCJhdXRoX3RpbWUiOjE2NTE2MjI1MzgsInJlYWxtIjoiLyIsImV4cCI6MTY1MTYyNDMzOCwiaWF0IjoxNjUxNjIyNTM4LCJleHBpcmVzX2luIjoxODAwLCJqdGkiOiJlaXdlanNyWmxRdEpmMXhPZ0lJaVQ3REo2LTgiLCJjbGllbnRfaWQiOiIxZDc2MzI2MS02NTIyLTQ5MTMtOWQ1Mi01ZDk0N2QzYjk0YzQiLCJ0ZW5hbnRGaWx0ZXIiOiJTQUxFU0ZPUkNFX0NPTU1FUkNFX0FQSTp6enRlXzA1MyIsInJvbGVzIjpbIlNBTEVTRk9SQ0VfQ09NTUVSQ0VfQVBJIl19.N_D2gZuJfQcIo-X42O4i-hz1j4_KxYzaqYb4CqVSf96Zt9w5-WmDPP_swuIz2eCivxwrs0hyfKmDTS7mQG_fLXiuAr6FT0bMVYndfmSbngJl24eCXu2U6b5-cMlUmwAG7mO7Uji4_cXtayUCA9XGUSVXxu1HuiFzANws_D-cCWlgoaWpEvPmkhq3o_ICJvhcqaZTYDaoQ62hDToMqdojbRQFe6s2kDLiqOIi6Ey_VYev8bRTu4RtXmJ6Pfj_xp0mgc4ak8zaxCVcykZ-ziEE9TqO-tN1U6n0QnuTh-t3wz2iSyEcfJ3fOtv9v9zz1BYpe1qMCYDTkKnMq_alERtKZg",
  "scope": "SALESFORCE_COMMERCE_API:zzte_053 sfcc.catalogs mail tenantFilter openId roles",
  "token_type": "Bearer",
  "expires_in": 1799,
  "refresh_expires_in": 0,
  "not-before-policy": 0
}
```

With an access token from Account Manager (and the correct scopes), access any of the SCAPI Admin APIs, including: [Assignments](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=assignments:Summary), [Catalogs](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=catalogs:Summary), [Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=customers:Summary), [Inventory Availability](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=inventory-availability:Summary), [Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=orders:Summary), [Products](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=products:Summary), and [8 more](https://developer.salesforce.com/docs/commerce/commerce-api/references).

## Next Steps

Now that you have set up your API client in Account Manager and know how to get an access token for SCAPI Admin APIs, it’s time to make some API requests!

Learn how to formulate your API requests with the last guide in the Get Started series: [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md).

To learn how to access the Shopper APIs, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).

<!-- document id=a159e4f853636dfda7ba268f31f3ea1f00bb9b39b14265fff8adf49a522a1a3b url=/developer/current/en-us/commerce-cloud/commerce-api/guides/authorization-for-shopper-apis.md -->

# Authorization for Shopper APIs

Learn how to set up the Shopper Login and API Access Service (SLAS) so that you can request access tokens for Shopper APIs.

**important:** Shopper APIs are secured with the Shopper Login and API Access Service (SLAS), but SCAPI Admin APIs are secured with Account Manager (AM) instead. This guide _only_ covers how to access the Shopper APIs. To learn how to access the SCAPI Admin APIs, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md).

To get you up and running as fast as possible, the instructions provided here use a web application called the SLAS Admin UI. If you require additional configuration options or are building automated setup tools, also use the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary) instead of the UI.

## SLAS Admin UI\: Set Up User Roles and Filters

To do this task, you need:

- Your AM token
- The **Account Administrator** role in Account Manager. If you get stuck, ask an administrator on your team for help or contact Support.

For each user performing the SLAS administration tasks described in this guide, follow these steps to set up their roles and filters:

1. Log in to [Account Manager](https://account.demandware.com/).
2. Click **User** from the left navigation.
3. Click the user’s ID.
4. Scroll down to **Roles** and click **Add.**

   ![Screenshot showing interface for adding new SLAS roles and permissions](https://developer.salesforce.com/docs/media/commerce-api/slas-roles-add.png '{"class": "image-lg"}')

5. Enter "slas" in the filter search box.
6. (If you see no results, the role has likely been added already, so click **Cancel** and skip to step 9.)
7. Select **SLAS Organization Administrator**.

   ![Screenshot showing form for creating new SLAS role with permissions](https://developer.salesforce.com/docs/media/commerce-api/slas-add-new-role.png '{"class": "image-sm"}')

8. Click **Add**.
9. Look for the **SLAS Shopper Admin API** category with the **SLAS Organization Administrator** role below it.
10. Click the filter button next to the **SLAS Organization Administrator** role.

    ![Screenshot of SLAS roles filtering and search interface](https://developer.salesforce.com/docs/media/commerce-api/slas-roles-filters.png '{"class": "image-lg"}')

11. Select an organization.
12. Select the hostnames for specific B2C Commerce instances that you want to configure. Also select **All Sandboxes** instead of selecting each sandbox individually.
13. Click **Add**.

    ![Screenshot showing interface for adding SLAS filters and criteria](https://developer.salesforce.com/docs/media/commerce-api/slas-filters-add.png '{"class": "image-sm"}')

14. Scroll down to the bottom of the page.
15. Click **Save**.

Now log in to the SLAS Admin UI. (It can take up to 15 minutes for role changes to propagate and take effect.)

![Screenshot of SLAS Admin UI interface showing client configuration options and navigation menu](https://developer.salesforce.com/docs/media/commerce-api/slas-admin-ui.png '{"class": "image-lg"}')

## SLAS Admin UI\: Create a SLAS Client

The easiest way to create a SLAS client is to use the SLAS Admin UI. To access the SLAS Admin UI, replace `{short-code}` in the following URL with the short code used by your B2C Commerce instances:

```text
https://{short-code}.api.commercecloud.salesforce.com/shopper/auth-admin/v1/ui/
```

Create a private client or append a redirect URI with the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Requires the SLAS Organization Administrator role for the target instance.
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli slas client create \
  --user-auth --tenant-id abcd_001 \
  --name 'Mobile-App-Client' \
  --channels RefArch \
  --scopes sfcc.shopper-products,sfcc.shopper-product-search \
  --redirect-uri 'http://localhost:3000/callback'

# Append a redirect URI to an existing client.
npx @salesforce/b2c-cli slas client list \
  --user-auth --tenant-id abcd_001

npx @salesforce/b2c-cli slas client update your-slas-client-id \
  --user-auth --tenant-id abcd_001 \
  --redirect-uri 'https://www.example.com/callback'
```

To learn more about B2C Commerce short codes, see the [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md) guide.

**note:** If you create Storefront Next in Business Manager, the automated setup creates a private SLAS client ID and secret for you. See [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-quick-start-create-bm-github.md) or [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-quick-start-create-bm.md).

Repeat these steps to create a SLAS client for each B2C Commerce instance that requires access to Shopper APIs:

1. Log in to the SLAS Admin UI using your Account Manager credentials.
2. From the top navigation, click **Clients**.
3. Click **Add Client**.
4. Click **Choose Tenant...** and select a B2C Commerce instance.
5. Select an app type with the “Which App Type will be used?” field:

   - Choosing **PWA Kit or SFRA or Mobile** creates a public client (no secret generated).
   - Choosing **BFF or Web App** creates a private client (secret generated automatically).

6. Click **Submit**.

Now use your SLAS client to request an access token for Shopper APIs.

If your app type is **BFF or Web App** (private client), the automatically generated secret is displayed at the top of the results page.

![Success confirmation screen for adding a new SLAS private client with client details](https://developer.salesforce.com/docs/media/commerce-api/slas-private-client-add-success.png)

To initialize an Agentforce session, obtain a SLAS shopper access token that includes the `sfcc.shopper-agents.rw` scope, and then call the [Shopper Agents API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-agents?meta=Summary) with the `sessionInitKey` received at session start.
The Shopper Agent API starts the Agentforce session and associates it with the shopper context that `sessionInitKey` references. It doesn't move profile or basket data. Any access to shopper data continues via standard Shopper APIs, governed by your SLAS token’s scopes.

**important:** A secret can only be displayed once for security reasons, so be sure to copy it and save it in a secure location whenever you create a client for a BFF or Web App.

To generate a new secret for an existing client:

1. From the top navigation, click **Clients**.
2. Click the **Edit** link next to the client ID that you created earlier.
3. Change the app type to **PWA Kit or SFRA or Mobile**.
4. Click **Save**.
5. Click the **Edit** button.
6. Change the app type back to **BFF or Web App**.
7. Click **Save**.
8. Copy the secret at the top of the results page.

<!-- ### Client Secret Management and Rotation

Client secret rotation for SLAS enables secure, nondisruptive rotation of private client secrets. You can simultaneously maintain two active secrets, a primary and a secondary, and rotate them without service interruption. This rotation reduces the risks associated with static keys and aligns with modern credential management best practices.

To rotate a client secret in the SLAS Admin UI:

1. From the top navigation, click **Clients**.
2. Click **Edit** for the client you want to update.
3. Select **Do Secret Rotation**.

![Screenshot showing SLAS secret rotation setting for a client](https://developer.salesforce.com/docs/media/commerce-api/slas-do-secret-rotation.png '{"class": "image-md"}')

4. Before you proceed, make sure that you understand the results of client secret rotation. After you rotate a client secret:
   - A new primary secret is generated and displayed.
   - The current primary secret (`Secret`) becomes the secondary secret (`Secret2`).
   - Both secrets remain active for authentication.
   - If there’s an existing secondary secret (because you’ve rotated this secret before), it gets overwritten and is no longer valid.
5. Click **Acknowledge** to confirm that you want to rotate the client’s secrets.
6. Click **Save** to rotate the secret. If you’re not ready for changes to be applied immediately, click **Cancel** to discard your edits.
7. Copy and securely store the new primary secret value.
   :::important
   The full secret value is displayed only once during rotation. Make sure that you copy and securely store it before leaving the page.
   :::
8. Update your application configuration with the new primary secret.

Both secrets remain valid for authentication until the next rotation cycle, when the secondary secret gets replaced and invalidated. The UI displays a mask with the last three characters of each secret for identification purposes while maintaining security. For example, `**ABC`.

This screenshot shows a client with one active secret. Following secret rotation, `**REY` moves to the empty `Secret2` field, and a new primary secret populates the `Secret` field.

![Screenshot showing the list of active secrets for a client](https://developer.salesforce.com/docs/media/commerce-api/slas-client-secrets.png '{"class": "image-md"}')
-->

## Extra Steps for Phased Rollouts of PWA Kit

If you’re planning to do a [phased rollout](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html) of a PWA Kit experience, you must also create a redirect URI and associate it with your API client.

To create the redirect URI, replace `PLACEHOLDER_HOSTNAME` and `PLACEHOLDER_SITE_ID` in the following string with actual values for your B2C Commerce instance:

```text
https://PLACEHOLDER_HOSTNAME/on/demandware.store/Sites-PLACEHOLDER_SITE_ID-Site/default/SLASCallback-RetrieveCode
```

To associate the redirect with your API client, follow these steps in the SLAS Admin UI:

1. From the top navigation, click **Clients**.
2. Click the **Edit** link next to the client ID that you created earlier.

   ![SLAS client edit interface displaying client configuration fields and options](https://developer.salesforce.com/docs/media/commerce-api/slas-client-edit.png)

3. In the redirect field, append a `|` character followed by the redirect URI that you just created.

   ![SLAS client redirect URI configuration screen showing redirect URL settings and validation](https://developer.salesforce.com/docs/media/commerce-api/slas-client-edit-redirect.png)

4. Click **Save**.

## Advanced\: SLAS Admin API

**note:** If you already created your SLAS clients using the SLAS Admin UI, skip this section.

The SLAS Admin API offers an alternative to the SLAS Admin UI that makes it easier to automate SLAS administration tasks, such as creating public and private clients. The API also provides access to a wider range of configuration options.

### Get a SLAS Admin Token

To access the SLAS Admin API, use the SLAS Admin UI to get an admin token:

1. Log in to the SLAS Admin UI.
2. Click **Token** from the top navigation.
3. Click **Copy Admin Token to Clipboard**. (The token will expire after 30 minutes.)

![Screenshot showing SLAS admin token configuration interface with token details and settings](https://developer.salesforce.com/docs/media/commerce-api/slas-admin-token.png)

**important:** An admin token is not the same as a SLAS access token. An admin token can only be used to access the SLAS Admin API, not Shopper APIs.

### Set Environment Variables

To form your API requests correctly, it helps to set some environment variables first.

**note:** If you’re not using a Unix-based operating system, adapt the commands for setting environment variables or manually replace the variables later in the `curl` command provided.

To store the admin token, replace `{clipboard_contents}` in the following command by pasting the token that you just copied from the SLAS Admin UI:

```bash
export "SFCC_ACCESS_TOKEN={clipboard_contents}"
```

Before running the next series of commands, replace `zzte`, `053`, and `kv7kzm78` with your realm ID, instance ID, and shortcode. To learn more about these identifiers, including how to look them up in Business Manager, see the [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md) guide.

```bash
export "SFCC_REALM_ID=zzte"
export "SFCC_INSTANCE_ID=053"
export "SFCC_SCAPI_TENANTID=${SFCC_REALM_ID}_${SFCC_INSTANCE_ID}"
export "SFCC_SCAPI_SHORTCODE=kv7kzm78"
```

### Create a SLAS Tenant

Now that your environment variables are set, start making requests to the SLAS Admin API. To create a SLAS tenant (or update an existing one) and associate it with a B2C Commerce instance, make a request to the `tenants` endpoint like this:

```bash
curl "https://$SFCC_SCAPI_SHORTCODE.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/$SFCC_SCAPI_TENANTID" \
--request 'PUT' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $SFCC_ACCESS_TOKEN" \
--data-raw '{
    "instance": "'"$SFCC_SCAPI_TENANTID"'",
    "description": "Example tenant for SLAS",
    "merchantName": "Northern Trail Outfitters",
    "contact": "Pia Larson",
    "emailAddress": "pia@northerntrailoutfitters.com"
}'
```

### Create a SLAS Client

To create a SLAS client using the SLAS Admin API, you must provide some additional configuration information, starting with a client ID.

#### Client ID

The `client_id` is a universally unique identifier (UUID) for each tenant that the SLAS service requires. There are several ways to generate a UUID, but go to [uuidgenerator.net](https://www.uuidgenerator.net/) and click **Copy** at the top of the page. The identifier must follow the UUID version 4 format: 36 characters long, including 3 hyphens.

To store the client ID in an environment variable for your API requests, replace `f58d60fd-9230-4ed7-90a4-ee11b5e7f27b` in the following command with the UUID that you generated:

```bash
export SLAS_CLIENT_ID=f58d60fd-9230-4ed7-90a4-ee11b5e7f27b
```

#### Client Secret

If you’re creating a private client, you also must create a secret (a password) for your SLAS client. We recommend using a password manager to generate and store the secret.

To store the secret in an environment variable for your API requests, replace `D*HHUrgO2%qADp2JTIUi` in the following command with your secret:

```bash
export SLAS_CLIENT_SECRET=D*HHUrgO2%qADp2JTIUi
```

**tip:** You can also create and store your client ID and secret in Account Manager. For detailed instructions, see [Add an API Client](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5) in the B2C Commerce documentation.

#### JSON Data

For creating both public and private clients, you must provide JSON data in the request body that controls important settings for SLAS:

- Use the `channels` array to associate the SLAS client with one or more channels. A channel is what we call the string used to identify a particular ecommerce site.
- The `scopes` array lists all the API families that the SLAS API has access to. Note that SLAS is capable of handling a maximum of 30 Custom Object scopes. For details, see [Shopper Custom Objects API.](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-custom-objects?meta=Summary)
- The `redirectUri` array allows specific URIs for redirects. Wildcard characters (`*`) are supported for hostnames.

In the example requests provided, the request body includes common settings that you can customize for your application.

#### Example Request\: Create a Public SLAS Client

To create a public SLAS client, run this command:

```bash
curl "https://$SFCC_SCAPI_SHORTCODE.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/$SFCC_SCAPI_TENANTID/clients/$SLAS_CLIENT_ID" \
--request "PUT"
--header "Content-Type: application/json" \
--header "Authorization: Bearer $SFCC_ACCESS_TOKEN" \
--data-raw '{
    "clientId": "'"$SLAS_CLIENT_ID"'",
    "isPrivateClient": false,
    "name": "Test Client",
    "channels": [
        "RefArch",
        "RefArchGlobal",
        "SiteGenesis"
    ],
    "scopes": [
        "sfcc.shopper-baskets-orders.rw",
        "sfcc.shopper-categories",
        "sfcc.shopper-customers.login",
        "sfcc.shopper-customers.register",
        "sfcc.shopper-gift-certificates",
        "sfcc.shopper-myaccount.rw",
        "sfcc.shopper-product-search",
        "sfcc.shopper-productlists",
        "sfcc.shopper-products",
        "sfcc.shopper-promotions",
        "sfcc.shopper-stores"
    ],
    "redirectUri": ["http://localhost:3000/callback", "https://*.mobify-storefront.com/callback", "https://*.exp-delivery.com/callback"]
}'
```

Since the request is for setting up a public client, no client secret is required.

#### Example Request\: Create a Private SLAS Client

**warning:** Don't use the `sfcc.shopper-context.rw` scope with a PUBLIC Client because it offers fewer protections and could potentially enable malicious actors to access Shopper Context enabled promotions. It is highly recommended to use `sfcc.shopper-context.rw` scope with a private client.

To create a private SLAS client, run this command:

```bash
curl "https://$SFCC_SCAPI_SHORTCODE.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/$SFCC_SCAPI_TENANTID/clients/$SLAS_CLIENT_ID" \
--request 'PUT'
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $SFCC_ACCESS_TOKEN' \
--data-raw '{
    "clientId": "'"$SLAS_CLIENT_ID"'",
    "secret": "'"$SLAS_CLIENT_SECRET"'",
    "isPrivateClient": true,
    "name": "Test Client",
    "channels": [
        "RefArch",
        "RefArchGlobal",
        "SiteGenesis"
    ],
    "scopes": [
        "sfcc.shopper-baskets-orders.rw",
        "sfcc.shopper-categories",
        "sfcc.shopper-customers.login",
        "sfcc.shopper-customers.register",
        "sfcc.shopper-gift-certificates",
        "sfcc.shopper-myaccount.rw",
        "sfcc.shopper-product-search",
        "sfcc.shopper-productlists",
        "sfcc.shopper-products",
        "sfcc.shopper-promotions",
        "sfcc.shopper-stores"
    ],
    "redirectUri": ["http://localhost:3000/callback", "http://example.com/callback"]
}'
```

## Next Steps

Now that you know how to set up SLAS clients, it’s time to make some API requests! Learn how to formulate your API requests with the last guide in the Get Started series: [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md).

To learn more about using public SLAS clients and private SLAS clients to access the Shopper APIs, see the [SLAS guides](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md).

For more technical details on the capabilities of the SLAS APIs, explore the API specifications in the Reference section:

- [SLAS API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary)
- [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary)

To learn how to access the SCAPI Admin APIs, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md).

<!-- document id=99dc1c7e689b00135a9919b1cfdcb3168c225f89beb3d3af2ae039a11f97f72b url=/developer/current/en-us/commerce-cloud/commerce-api/guides/auth-z-scope-catalog.md -->

# Authorization Scopes Catalog

Scopes control which B2C Commerce endpoints a token can access and define the permissions and operations a token can perform, so that only authorized operations are allowed.

Scopes use the format `sfcc.{family}[.rw]`. The optional `.rw` suffix indicates read and write permissions.

To assign scopes to tokens and configure them based on your storefront needs:

1. Understand the capabilities of your storefront and what shoppers can do.
2. Determine the API families with which your storefront needs to interact and the specific actions needed: Shopper APIs, SCAPI Admin APIs, and SLAS Admin APIs.
3. Identify the required scopes using the following tables.
   - For security reasons, limit scopes to the minimum you need.
   - Optimize the size of your JSON Web Token (JWT). Scopes make up a large portion of the SLAS JWT, and in many cases, this SLAS token is stored as a cookie and is passed back-and-forth in both requests and responses.
   - To reduce JWT size, use the `sfcc.shopper-standard` scope. For more information, see [Standard Shopper Scope](https://developer.salesforce.com/docs/commerce/commerce-api/guide/standard-shopper-scope.html).
     **tip:** For each selected scope, configure the specific permissions to avoid redundancy. If you include the `.rw` version for a scope, avoid using the read-only counterpart, as it's redundant and can make the token unnecessarily bulky.
   - Include only scopes for the applicable API family. For example, don't include SCAPI Admin API scopes in a SLAS JWT.
4. Configure your token with the correct scopes:
   - To configure tokens for use with the Shopper APIs, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).
   - To configure tokens for use with the SCAPI Admin APIs, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md).
   - To use scopes with Custom APIs, see [Custom API Authentication and Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-authentication.html).
5. Save the token configuration. To test it, make API calls. A successful call returns a `200` response. A `401` or `403` response indicates a missing or incorrect scope.

## Default Scopes

By default, the following SLAS scopes are assigned:

```text
sfcc.shopper-baskets-orders.rw
sfcc.shopper-categories
sfcc.shopper-customers.login
sfcc.shopper-customers.register
sfcc.shopper-discovery-search
sfcc.shopper-gift-certificates
sfcc.shopper-myaccount.addresses.rw
sfcc.shopper-myaccount.baskets
sfcc.shopper-myaccount.orders
sfcc.shopper-myaccount.paymentinstruments.rw
sfcc.shopper-myaccount.productlists.rw
sfcc.shopper-myaccount.rw
sfcc.shopper-configurations
sfcc.shopper-product-search
sfcc.shopper-productlists
sfcc.shopper-products
sfcc.shopper-promotions
sfcc.shopper-stores
sfcc.shopper-experience
```

## List of SCAPI Shopper API Scopes

These scopes are only useful inside a SLAS JWT.

To configure tokens for use with the Shopper APIs, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).

| Scope                                        | API Family    | API Name                   | Purpose                                                                                                                                                          |
| -------------------------------------------- | ------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sfcc.shopper-agents.rw                       | Shopper       | Shopper Agents             | Initialize Shopper Agent session.                                                                                                                                |
| sfcc.shopper-baskets-orders                  | Checkout      | Shopper Baskets            | Read baskets and orders from a shopper perspective.                                                                                                              |
| sfcc.shopper-baskets-orders.rw               | Checkout      | Shopper Baskets            | Create, read, update, and delete an order, including shipping and tax information.                                                                               |
| sfcc.shopper-categories                      | Product       | Shopper Products           | Read categories to be displayed on a storefront for shoppers.                                                                                                    |
| sfcc.shopper-configurations                  | Configuration | Shopper Configurations     | Retrieve global and site-specific configuration details.                                                                                                         |
| sfcc.shopper-consents                        | Shopper       | Shopper Consents           | Read Shopper Consents.                                                                                                                                           |
| sfcc.shopper-consents.rw                     | Shopper       | Shopper Consents           | Create, read, update, and delete Shopper Consents.                                                                                                               |
| sfcc.shopper-context                         | Shopper       | Shopper Context            | Read Shopper Context.                                                                                                                                            |
| sfcc.shopper-context.rw                      | Shopper       | Shopper Context            | Create, read, update, and delete Shopper Context.                                                                                                                |
| sfcc.shopper-custom-objects                  | Custom Object | Shopper Custom Objects     | Read all custom object information.                                                                                                                              |
| sfcc.shopper-custom-objects.{object-type}    | Custom Object | Shopper Custom Objects     | Read custom object information. Access can be restricted at the {object-type} level. This extends the standard objects provided by B2C Commerce.                 |
| sfcc.shopper-customers.login                 | Customer      | Shopper Customers          | Log in a shopper.                                                                                                                                                |
| sfcc.shopper-customers.register              | Customer      | Shopper Customers          | Register a shopper.                                                                                                                                              |
| sfcc.shopper-delivery-estimates              | Product       | Shopper Delivery Estimates | Read carrier-calculated delivery date estimates for a product at a destination postal code, for example, to show "Arrives by" messaging on product detail pages. |
| sfcc.shopper-experience                      | Experience    | Shopper Experience         | Read access for assets created in Page Designer.                                                                                                                 |
| sfcc.shopper-experience.contents             | Experience    | Shopper Experience         | Read content assets available on a storefront.                                                                                                                   |
| sfcc.shopper-experience.folders              | Experience    | Shopper Experience         | Read content folders used to organize storefront content assets.                                                                                                 |
| sfcc.shopper-experience.pages                | Experience    | Shopper Experience         | Read pages created in Page Designer.                                                                                                                             |
| sfcc.shopper-experience.qualifiers           | Experience    | Shopper Experience         | Resolve qualifiers for customer groups, campaign promotions, and data binding contexts.                                                                          |
| sfcc.shopper-gift-certificates               | Pricing       | Shopper Gift Certificates  | Read gift certificates from a shopper perspective.                                                                                                               |
| sfcc.shopper-myaccount                       | Customer      | Shopper Customers          | Read all data in a shopper account.                                                                                                                              |
| sfcc.shopper-myaccount.addresses             | Customer      | Shopper Customers          | Read shopper addresses.                                                                                                                                          |
| sfcc.shopper-myaccount.addresses.rw          | Customer      | Shopper Customers          | Create, read, update, and delete addresses in a shopper account.                                                                                                 |
| sfcc.shopper-myaccount.baskets               | Customer      | Shopper Customers          | Read a shopper’s baskets.                                                                                                                                        |
| sfcc.shopper-myaccount.orders                | Customer      | Shopper Customers          | Read a shopper’s orders.                                                                                                                                         |
| sfcc.shopper-myaccount.paymentinstruments    | Customer      | Shopper Customers          | Read a shopper’s payment instruments.                                                                                                                            |
| sfcc.shopper-myaccount.paymentinstruments.rw | Customer      | Shopper Customers          | Create, read, update, and delete payment instruments in a shopper account.                                                                                       |
| sfcc.shopper-myaccount.productlists          | Customer      | Shopper Customers          | Read wishlists associated with a shopper account.                                                                                                                |
| sfcc.shopper-myaccount.productlists.rw       | Customer      | Shopper Customers          | Create, read, update, and delete wishlists associated with a shopper account.                                                                                    |
| sfcc.shopper-myaccount.rw                    | Customer      | Shopper Customers          | Create, read, update, and delete all data in a shopper account.                                                                                                  |
| sfcc.shopper-product-search                  | Search        | Shopper Search             | Search for products and product suggestions.                                                                                                                     |
| sfcc.shopper-productlists                    | Customer      | Shopper Customers          | Read public product lists or wishlists.                                                                                                                          |
| sfcc.shopper-products                        | Product       | Shopper Products           | Read products merchandised and available to be sold on a particular site.                                                                                        |
| sfcc.shopper-promotions                      | Pricing       | Shopper Promotions         | Read promotions from a shopper perspective.                                                                                                                      |
| sfcc.shopper-seo                             | Site          | Shopper SEO                | Read SEO-related information.                                                                                                                                    |
| sfcc.shopper-stores                          | Store         | Shopper Stores             | Search for and read details on stores.                                                                                                                           |

## List of SCAPI Admin API Scopes

These scopes are only useful inside an Account Manager JWT.

To configure tokens for use with the SCAPI Admin APIs, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md).

| Scope                             | API Family     | API Name                | Purpose                                                                                                                                     |
| --------------------------------- | -------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| sfcc.analytics                    | Intelligence   | Analytics               | Access analytics subject areas, metadata, and query operations.                                                                             |
| sfcc.catalogs                     | Product        | Catalogs                | Read catalog information.                                                                                                                   |
| sfcc.catalogs.rw                  | Product        | Catalogs                | Create, read, update, and delete catalogs.                                                                                                  |
| sfcc.cdn-zones                    | CDN Zones      | CDN Zones               | Read information related to CDN Zones.                                                                                                      |
| sfcc.cdn-zones.rw                 | CDN Zones      | CDN Zones               | Create, read, update, and delete information related to CDN Zones.                                                                          |
| sfcc.consents                     | Customer       | Consents                | Read customer consent preferences.                                                                                                          |
| sfcc.consents.rw                  | Customer       | Consents                | Create, read, update, and delete customer consent preferences.                                                                              |
| sfcc.cors-preferences             | Configuration  | CORS Preferences        | Read Cross-Origin Resource Sharing (CORS) preferences.                                                                                      |
| sfcc.cors-preferences.rw          | Configuration  | CORS Preferences        | Create, read, update, and delete Cross-Origin Resource Sharing (CORS) preferences.                                                          |
| sfcc.custom-apis                  | DX             | Custom APIs             | Read resolved Custom API endpoints and their registration status (active/not_registered), including error reasons for failed registrations. |
| sfcc.custom-apis.rw               | DX             | Custom APIs             | Read endpoints and perform admin-level management actions for Custom APIs (read/write when available).                                      |
| sfcc.customergroups               | Customer       | Customer Groups         | Read customer groups.                                                                                                                       |
| sfcc.customergroups.rw            | Customer       | Customer Groups         | Create, read, update, and delete customer groups.                                                                                           |
| sfcc.customerlists                | Customer       | Customers               | Read customer list associated with a site.                                                                                                  |
| sfcc.customerlists.rw             | Customer       | Customers               | Create, read, update, and delete customer lists associated with a site.                                                                     |
| sfcc.experiences                  | Experience     | Experiences             | Read merchandiser experiences.                                                                                                              |
| sfcc.experiences.rw               | Experience     | Experiences             | Create, read, update, and delete merchandiser experiences.                                                                                  |
| sfcc.gift-certificates            | Pricing        | Gift Certificates       | Read gift certificates.                                                                                                                     |
| sfcc.gift-certificates.rw         | Pricing        | Gift Certificates       | Create, read, update, and delete gift certificates.                                                                                         |
| sfcc.granular-replications        | Administration | Replications            | Read replication information.                                                                                                               |
| sfcc.granular-replications.rw     | Administration | Replications            | Create, read, update, and delete replications.                                                                                              |
| sfcc.inventory-lists              | Inventory      | Inventory Lists         | Read inventory lists.                                                                                                                       |
| sfcc.inventory-lists.rw           | Inventory      | Inventory Lists         | Create, read, update, and delete inventory lists.                                                                                           |
| sfcc.inventory.availability       | Inventory      | Inventory Availability  | Read availability. Account Manager Authentication.                                                                                          |
| sfcc.inventory.availability.rw    | Inventory      | Inventory Availability  | Create, read, update, and delete availability. Account Manager Authentication.                                                              |
| sfcc.inventory.impex-graphs       | Inventory      | Inventory Impex         | Read location graph exports. Account Manager Authentication.                                                                                |
| sfcc.inventory.impex-inventory    | Inventory      | Inventory Impex         | Read inventory exports. Account Manager Authentication.                                                                                     |
| sfcc.inventory.impex-inventory.rw | Inventory      | Inventory Impex         | Read inventory imports. Account Manager Authentication.                                                                                     |
| sfcc.inventory.reservations       | Inventory      | Inventory Reservation   | Read reservation information. Account Manager Authentication.                                                                               |
| sfcc.inventory.reservations.rw    | Inventory      | Inventory Reservation   | Create, read, update, and delete reservations. Account Manager Authentication.                                                              |
| sfcc.jobs                         | Administration | Jobs                    | Read job information.                                                                                                                       |
| sfcc.jobs.rw                      | Administration | Jobs                    | Create, read, update, and delete jobs.                                                                                                      |
| sfcc.metrics                      | Observability  | Metrics                 | Read metrics and observability data.                                                                                                        |
| sfcc.object-definitions           | Configuration  | Object Definitions      | Read object definitions.                                                                                                                    |
| sfcc.object-definitions.rw        | Configuration  | Object Definitions      | Create, read, update, and delete object definitions.                                                                                        |
| sfcc.orders                       | Checkout       | Orders                  | Read orders from a management perspective.                                                                                                  |
| sfcc.orders.rw                    | Checkout       | Orders                  | Create, read, update, and delete an existing order, for example, with a status update.                                                      |
| sfcc.preferences                  | Configuration  | Preferences             | Read site and environment-specific settings.                                                                                                |
| sfcc.price-books                  | Pricing        | Price Books             | Read price books.                                                                                                                           |
| sfcc.price-books.rw               | Pricing        | Price Books             | Create, read, update, and delete price books.                                                                                               |
| sfcc.products                     | Product        | Products                | Read products assigned to a catalog.                                                                                                        |
| sfcc.products.rw                  | Product        | Products                | Create, read, update, and delete products from a catalog.                                                                                   |
| sfcc.promotions                   | Pricing        | Promotions              | Read campaigns, coupons, promotions, and assignments.                                                                                       |
| sfcc.promotions.rw                | Pricing        | Promotions              | Create, read, update, and delete campaigns, coupons, promotions, and assignments.                                                           |
| sfcc.roles                        | Administration | Roles                   | Read roles.                                                                                                                                 |
| sfcc.roles.rw                     | Administration | Roles                   | Create, read, update, and delete roles.                                                                                                     |
| sfcc.scapi-schemas                | DX             | SCAPI Schemas           | Read SCAPI schema registry.                                                                                                                 |
| sfcc.scripts                      | DX             | Scripts                 | Read scripts.                                                                                                                               |
| sfcc.scripts.rw                   | DX             | Scripts                 | Create, read, update, and delete scripts.                                                                                                   |
| sfcc.seo                          | Site           | SEO                     | Read SEO configurations.                                                                                                                    |
| sfcc.seo.rw                       | Site           | SEO                     | Create, read, update, and delete SEO configurations.                                                                                        |
| sfcc.sites                        | Configuration  | Sites                   | Read site information.                                                                                                                      |
| sfcc.sites.rw                     | Configuration  | Sites                   | Create, read, update, and delete site information.                                                                                          |
| sfcc.source-codes                 | Pricing        | Source Code Groups      | Read source codes.                                                                                                                          |
| sfcc.source-codes.rw              | Pricing        | Source Code Groups      | Create, read, update, and delete source codes.                                                                                              |
| sfcc.store-redirect-mappings      | Site           | Store Redirect Mappings | Read store redirect mappings.                                                                                                               |
| sfcc.store-redirect-mappings.rw   | Site           | Store Redirect Mappings | Create, read, update, and delete store redirect mappings.                                                                                   |
| sfcc.storefront.deployments.rw    | Deployment     | Deployments             | Upload, deploy, and get a bundle and all bundles. Get one or all deployments.                                                               |
| sfcc.storefront.environments.rw   | Environment    | Environments            | Create, clone, delete, and edit environments, access control headers, redirects. List environments. Create cache invalidation.              |
| sfcc.storefront.storefronts.rw    | Storefront     | Storefronts             | Create, get, edit, and delete storefronts.                                                                                                  |
| sfcc.stores                       | Store          | Stores                  | Read store information.                                                                                                                     |
| sfcc.timeouts                     | Configuration  | Timeouts                | Read timeout configuration.                                                                                                                 |
| sfcc.timeouts.rw                  | Configuration  | Timeouts                | Create, read, update, and delete timeout configuration.                                                                                     |
| sfcc.users                        | Administration | Users                   | Read user information.                                                                                                                      |
| sfcc.users.rw                     | Administration | Users                   | Create, read, update, and delete users.                                                                                                     |

## List of SLAS Scopes

| Scope                    | API Family | API Name      | Purpose                                                                                                                                                                          |
| ------------------------ | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sfcc.pwdless_login       | Shopper    | Shopper Login | Allow users with a B2C Commerce profile to request a token by email that can be used to log in without a password even when their identity provider (Salesforce) is unavailable. |
| sfcc.session_bridge      | Shopper    | Shopper Login | Allow session bridging.                                                                                                                                                          |
| sfcc.ta_ext_on_behalf_of | Shopper    | Shopper Login | Call trusted agent endpoints.                                                                                                                                                    |
| sfcc.ts_ext_on_behalf_of | Shopper    | Shopper Login | Call trusted system endpoints.                                                                                                                                                   |
| sfcc.shopper-mcpagent    | Shopper    | Shopper Login | Allow access to the B2C Commerce Model Context Protocol (MCP) Shopper Service from an AI Agent, for example, Claude or ChatGPT.                                                  |

## Example Scopes

Here's an example set of scopes required for a shopping application (such as a PWA Kit storefront):

```text
sfcc.shopper-baskets-orders.rw
sfcc.shopper-categories
sfcc.shopper-customers.login
sfcc.shopper-customers.register
sfcc.shopper-gift-certificates
sfcc.shopper-myaccount.rw
sfcc.shopper-product-search
sfcc.shopper-productlists
sfcc.shopper-products
sfcc.shopper-promotions
sfcc.shopper-stores
```

<!-- document id=c0a31df0417f5ee62c1c1d523fa015470b983499f8c1a8b209f96d649ff4d07b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-auth-org-lwc-project.md -->

# Authorize an Org for an SFDX Project

To streamline deployment, authorize the org to which SFDX deploys custom objects.

1.  In the Visual Studio Code editor, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).

2.  Enter `SFDX`.

3.  Select **SFDX: Authorize an Org**

    ![Screnshot of VS Code Command Palette showing Org options.](https://developer.salesforce.com/media/d2c-commerce/auth_org_vscode.png)

4.  Choose the Project Default (org URL in your project.json file), or a Production, Sandbox, or Custom org login URL.

    SFDX opens the Salesforce login portal to your org in a separate browser window.

5.  Log in using your admin credentials.

6.  If you’re prompted to allow access, click **Allow**.

    After you authenticate in the browser, the CLI remembers your credentials. The success message looks like this:

    ![Screenshot of successful org authorizaiton message.](https://developer.salesforce.com/media/d2c-commerce/auth_org_success.png)

**See Also**

- [Create a Sample Lightning Web Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-sample-lwc.htm)

<!-- document id=1922424000e4d61d814e9b64ca36916261f7c792d75cd3a54a25b4f3dcf77eec url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/active-merchandising/b2c-automating-feed-import-of-active-data.md -->

# Automate Feed Import of Active Data

Use the ImportActiveData pipelet to automate the import of active data feeds into an instance, either via a job or a pipeline.

If you are testing data on a Staging instance, sometimes you must import extra custom attributes not included in the Production instance for testing purposes. In this case, you must rebuild the product index after import. Incremental indexing doesn't automatically rebuild based on imported feed data.

If you are implementing feed import in an existing system, easily edit a copy of your existing product import pipelines to automate feed import. If you are creating a project, we recommend using the Simple Feed Integration project as a starting point for product and active data feeds. This project is available in the code library.

<!-- document id=3eae2bd02db70e86ffcf60bb65540a8dbf16ec61400f936a98dfac2793feddd3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-cli.md -->

**Applies to: Storefront Next and Composable Storefront**

# Automate Storefront Administration Tasks with the B2C CLI

Use the B2C CLI to create environments and environment variables and to deploy bundles. Do these tasks in the CLI rather than in Business Manager or Runtime Admin. The CLI streamlines your storefront development lifecycle. See [MRT Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html) in the Agentic B2C Developer Toolkit.

**note:** Access environment variables in Node.js with [`process.env`](https://nodejs.org/docs/latest/api/process.html#processenv).

## Point the CLI to the API Backend

By default, the CLI calls Managed Runtime API. Some commands, including `b2c mrt bundle` and `b2c mrt env var`, can call SCAPI and authorize with an Account Manager API client. See [SCAPI-supported commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html#scapi-supported-commands). To point the CLI to an API backend, add the `--mrt-backend` argument and one of these values.

- `--mrt-backend scapi` uses SCAPI.
- `--mrt-backend legacy` uses Managed Runtime API.
- `--mrt-backend auto` uses SCAPI when its prerequisites are detected. Otherwise, the CLI uses Managed Runtime API. If a SCAPI request fails with a safe pre-execution error, the CLI falls back to Managed Runtime API.

## Set Up the B2C CLI

1. Install the B2C CLI or use it from the `@salesforce/b2c-cli` package by following the instructions in [Run the B2C CLI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-developer-tooling.html#run-the-b2c-cli).
2. Set up the authorization for the B2C CLI. For the environment variable examples in this page, set up SCAPI or the MRT API key authorization depending which API backend you want the CLI to use.
   - To set up MRT API key for the Managed Runtime API backend, see [Getting an API Key](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html#getting-an-api-key).
   - To set up SCAPI authentication for the SCAPI backend and Account Manager scopes, see [SCAPI Authorization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-api.md#scapi-authorization).

## Manage Environment Variables with the B2C CLI

Use the B2C CLI to list all environment variables for an environment, update an environment variable value, and create environment variables from an environment file.

**note:** A storefront in Business Manager corresponds to a project in Managed Runtime.
The examples use `my-storefront` and `staging` as the project and environment. Replace them with the actual values for your storefront. To get the project ID, see [Find a Project](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md).

### List All Environment Variables for an Environment

Use this command to list the environment variables for a storefront and environment.

```bash
npx @salesforce/b2c-cli mrt env var list --project my-storefront --environment staging
```

### Set or Update an Environment Variable

Use the `mrt env var set` command to create an environment variable for a storefront and environment with the specified value.

```bash
npx @salesforce/b2c-cli mrt env var set "MY_VAR=hello world" \
  --project my-storefront --environment staging
```

To remove a variable, use `delete`. Setting `MY_VAR=null` with the CLI stores the text `null` instead of removing the variable.

```bash
npx @salesforce/b2c-cli mrt env var delete MY_VAR \
  --project my-storefront --environment staging
```

When you modify environment variables, the environment redeploys. Updated values are available when the redeploy completes.

### Create Environment Variables from an `.env` File

Use this command to create environment variables from the `.env` file created during storefront setup in Business Manager. To skip the confirmation prompt, add the `--yes` argument.

```bash
npx @salesforce/b2c-cli mrt env var push \
  --project my-storefront --environment staging --file .env
```

**note:** When you add a new environment variable, wait for the redeploy of the bundle to complete, and then deploy a new bundle that uses the new variable.

## Create and Deploy Bundles with the B2C CLI

Use the `mrt bundle` commands to create and deploy bundles to an environment. For the deployment commands, see [Bundle Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html#bundle-commands). To set up authorization for the B2C CLI, see [Set Up the B2C CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-cli.md#set-up-the-b2c-cli).

This example creates and deploys the bundle for a storefront and environment. Replace `my-storefront` and `staging` with your project ID and environment.

```bash
npx @salesforce/b2c-cli mrt bundle deploy -p my-storefront -e staging --message "Test Release"
```

The `--storefront` argument is an alias for the `-p` project ID argument, which is also the storefront ID.

```bash
npx @salesforce/b2c-cli mrt bundle deploy --storefront my-storefront -e staging --message "Test Release"
```

## See Also

- [Agentic B2C Developer Toolkit: MRT Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html)
- [Troubleshoot Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-env-var-troubleshoot.md)

<!-- document id=3c8ade117301fbcacb7bc30ca93f9245151a1cb53810d6499a40fa2449b9d46f url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-api.md -->

**Applies to: Storefront Next and Composable Storefront**

# Automate Storefront Administration with APIs

Perform automated storefront administration and development tasks to streamline your storefront development lifecycle and CI/CD. Using the API, create a storefront, update, edit, and delete storefronts. Create and manage environments, environment variables, access control headers, and redirects. Also, upload bundles and start deployments. Use one of two APIs: B2C Commerce (SCAPI) or Managed Runtime (MRT) API. We recommend you use SCAPI for automation based on a bot user. Also, use SCAPI to create and edit storefronts, and edit environment settings, which are not available in the MRT API.

**note:** Creating a storefront is currently available for Storefront Next only and isn't supported for Composable Storefront.

## Administer Your Storefront with SCAPI

SCAPI offers ease of setup because you use the same Account Manager API authorization as other SCAPI endpoints that you're already familiar with for other API administration tasks. You don't need to create a separate Managed Runtime API key. The authorization mechanism used in SCAPI enables using a bot user for full automation.

These API families are available for managing the storefront resources.

- [B2C Commerce API: Storefronts](https://developer.salesforce.com/docs/commerce/commerce-api/references/storefronts?meta=Summary)
- [B2C Commerce API: Environments](https://developer.salesforce.com/docs/commerce/commerce-api/references/environments?meta=Summary)
- [B2C Commerce API: Deployments](https://developer.salesforce.com/docs/commerce/commerce-api/references/deployments?meta=Summary)

## SCAPI Authorization

Accessing each storefront API family requires OAuth2 authorization and setting up specific scopes in Account Manager.

1. Create an Account Manager API client with the scopes required to access the storefront APIs. See [Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html). These are the scopes you need per API family.
   - `sfcc.storefront.storefronts.rw`: Read and write access to storefronts. Write access is needed to create, edit, or delete a storefront.
   - `sfcc.storefront.environments.rw`: Read and write access to environments and environment variables. Write access is needed to create and delete environments, edit environment settings, and create, edit, and delete environment variables.
   - `sfcc.storefront.deployments.rw`: Read and write access to deployments. Write access is needed to upload bundles and deploy them.
2. Request an access token to use for OAuth2 authorization.

## Example SCAPI Requests

Here are examples of common tasks. Configure the correct scope in Account Manager for each API family. See [SCAPI Authorization](#scapi-authorization). For all API requests that you can make, see the API reference.

These examples use the `curl` tool to send API requests. For more information, see [Curl](https://curl.se/).

### Create a Storefront Next Store

```
curl "https://{shortCode}.api.commercecloud.salesforce.com/storefront/storefronts/v1/organizations/{organizationId}/storefronts" \
  -X POST \
  -H "content-type: application/json" \
  -d '{
  "storefrontName": "MarketStreet",
  "type": "storefront_next",
  "sites": [
    "MarketStreet"
  ]
}'
```

For a full description, see [createStorefront](https://developer.salesforce.com/docs/commerce/commerce-api/references/storefronts?meta=createStorefront).

### Create an Environment

```
curl "https://{shortCode}.api.commercecloud.salesforce.com/storefront/environments/v1/organizations/{organizationId}/storefronts/{storefrontId}/environments" \
  -X POST \
  -H "content-type: application/json" \
  -d '{
  "displayName": "Production"
}'
```

For a full description, see [createEnvironmentForStorefront](https://developer.salesforce.com/docs/commerce/commerce-api/references/environments?meta=createEnvironmentForStorefront).

### Create an Environment Variable

The endpoint for creating an environment variable is common for updating and deleting environment variables. All use the PATCH method.

```
curl "https://{shortCode}.api.commercecloud.salesforce.com/storefront/environments/v1/organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/environment-variables" \
  -X PATCH \
  -H "content-type: application/json" \
  -d '{
  "MAX_CART_ITEMS": {
    "value": 50
  },
  "PAYMENT_GATEWAY_API_KEY": {
    "value": "sk_live_a1b2c3d4e5f6"
  },
  "LEGACY_CHECKOUT_URL": {
    "value": null
  }
}'
```

For a full description, see [updateEnvironmentVariables](https://developer.salesforce.com/docs/commerce/commerce-api/references/environments?meta=updateEnvironmentVariables).

### Upload a Bundle

```
curl "https://{shortCode}.api.commercecloud.salesforce.com/storefront/deployments/v1/organizations/{organizationId}/storefronts/{storefrontId}/bundles" \
  -X POST \
  -H "content-type: multipart/form-data" \
  -d '"bundle": "<binary .tar.gz archive, e.g. storefront-bundle.tar.gz>"
"message": "Release 2.1.0"
"rootDir": "bld"
"configPath": ".mrt/config.json"
"matchMode": "strict"'
```

For a full description, see [uploadBundleForStorefront](https://developer.salesforce.com/docs/commerce/commerce-api/references/deployments?meta=uploadBundleForStorefront).

## Managed Runtime API

Use the Managed Runtime API to automate the administration tasks in your app. The API offers similar capabilities to SCAPI but requires a different authorization mechanism and doesn't support creating storefronts. It precedes SCAPI and is based on Runtime Admin resources. Managed Runtime API is available for Storefront Next and Composable Storefront. To learn more, see [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/using-the-managed-runtime-api.md).

## Read-Only Mode During Maintenance

During planned maintenance windows, the Managed Runtime API rejects write requests (POST, PUT, PATCH, and DELETE) with an HTTP `503 Service Unavailable` response and error code `service_read_only`. Read requests (GET) continue to work normally. Retry write requests after the maintenance window concludes.

<!-- document id=d4a2309d24c76ffb63ace4599331080a46549e3afb675ec28ec6b27cdd105657 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/available-extensions.md -->

# Available Extensions

This page lists all the extensions that are available for Salesforce Commerce. New extensions are added as they become available.

To create an extension provider, you must know which base Apex class to extend and the extension point name for mapping. Both the the base Apex class name and extension point name are listed for each extension.

This page lists two types of extensions: domain and endpoint.

Domain extensions extend functional domains, such as cart calculation. In contrast, endpoint extensions extend selected Connect API endpoints.

**important:** The release status and availability varies from extension to extension. This page is updated to reflect the latest release status of each extension.

## Domain Extensions for Buyer Group

The extension listed in this section is used for Buyer Group.

### Buyer Groups Extensibility Service

Dynamically assign users to buyer groups by executing custom Apex business logic.

- **Base Apex class**: [CommerceBuyGrp.BuyerGroupEvaluationService](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_CommerceBuyGrp_BuyerGroupEvaluationService.htm)
- **Extension point name**: Commerce_Domain_BuyerGroup_EvaluationService
- **Namespace**: `CommerceBuyGrp`. See [Buyer Group Reference](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_namespace_CommerceBuyGrp.htm).

## Domain Extensions for Cart Calculate API

The extensions listed in this section are all functionally related, and they all support cart calculations, including cart calculations that occur during checkout. These extensions comprise the [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.md).

### Cart Calculate

Orchestrates multiple calculators to summarize the total cost in a cart. See [Orchestrators and Calculators](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.md#orchestrators-and-calculators).

Each calculator is a separate extension that you can customize separately.

- **Base Apex class**: [CartExtension.CartCalculate](/docs/commerce/salesforce-commerce/references/comm-apex-reference/CartCalculate.html)
- **Extension point name**: Commerce_Domain_Cart_Calculate
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

CartCalculate currently supports the following set of cart and checkout operations:

- AddItemToCart
- EditCartItem
- DeleteCartItem
- AddCoupon
- DeleteCoupon
- StartCheckout
- PatchCheckout (address, set delivery method)

### Inventory Cart Calculator

Calculates inventory for cart and checkout based on the [inventory service](#inventory-service).

- **Base Apex class**: [CartExtension.InventoryCartCalculator](/docs/commerce/salesforce-commerce/references/comm-apex-reference/InventoryCartCalculator.html)
- **Extension point name**: Commerce_Domain_Inventory_CartCalculator
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

### Inventory Service

Reserves and tracks available inventory. By default, this extension uses the [Omnichannel Inventory](https://help.salesforce.com/s/articleView?id=commerce.inv_omnichannel_inventory_service.htm) (OCI) system for inventory data.

- **Base Apex class**: [commerce_inventory.CommerceInventoryService](/docs/commerce/salesforce-commerce/references/comm-apex-reference/CommerceInventoryService.html)
- **Extension point name**: Commerce_Domain_Inventory_Service
- **Namespace**: `commerce_inventory`. See [Inventory Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/inventory-reference.html).

### Pricing Cart Calculator

Calculates pricing for cart and checkout based on the [pricing service](#pricing-service).

- **Base Apex class**: [CartExtension.PricingCartCalculator](/docs/commerce/salesforce-commerce/references/comm-apex-reference/PricingCartCalculator.html)
- **Extension point name**: Commerce_Domain_Pricing_CartCalculator
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

### Pricing Service

Tracks how products and services are priced. By default, this extension uses Salesforce price books for pricing data. If your store uses [Faster Add-to-Cart](https://help.salesforce.com/s/articleView?id=commerce.comm_faster_add_to_cart.htm), make sure that all products have an entry in a store price book before implementing the pricing service extension.

- **Base Apex class**: [commercestorepricing.PricingService](/docs/commerce/salesforce-commerce/references/comm-apex-reference/PricingService.html)
- **Extension point name**: Commerce_Domain_Pricing_Service
- **Namespace**: `commercestorepricing`. See [Pricing Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/pricing-reference.html).

### Promotions Cart Calculator

Calculates promotions for cart and checkout. By default, this extension uses the Salesforce promotions service to perform its calculations.

- **Base Apex class**: [CartExtension.PromotionsCartCalculator](/docs/commerce/salesforce-commerce/references/comm-apex-reference/PromotionsCartCalculator.html)
- **Extension point name**: Commerce_Domain_Promotions_CartCalculator
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

### Shipping Cart Calculator

Calculates shipping costs. By default, there's no charge for shipping, so you must extend the base Apex class to see any effect.

- **Base Apex class**: [CartExtension.ShippingCartCalculator](/docs/commerce/salesforce-commerce/references/comm-apex-reference/ShippingCartCalculator.html)
- **Extension point name**: Commerce_Domain_Shipping_CartCalculator
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

### Tax Cart Calculator

Calculates taxes for cart and checkout. By default, this extension uses the Salesforce tax service to perform its calculations.

- **Base Apex class**: [CartExtension.TaxCartCalculator](/docs/commerce/salesforce-commerce/references/comm-apex-reference/TaxCartCalculator.html)
- **Extension point name**: Commerce_Domain_Tax_CartCalculator
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

### Tax Service

Applies taxes to products in the cart.

- **Base Apex class**: [commercestoretax.TaxService](/docs/commerce/salesforce-commerce/references/comm-apex-reference/TaxService.html)
- **Extension point name**: Commerce_Domain_Tax_Service
- **Namespace**: `commercestoretax`. See [Tax Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/tax-reference.html).

## Domain Extensions for Checkout

The extensions listed in this section are used for checkout but don't affect cart calculations, so they aren't part of the Cart Calculate API.

### CreateOrder Service

During checkout, this extension creates an order using information from the cart.

- **Base Apex class**: [CartExtension.CheckoutCreateOrder](/docs/commerce/salesforce-commerce/references/comm-apex-reference/CheckoutCreateOrder.html)
- **Extension point name**: Commerce_Domain_Checkout_CreateOrder
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

### PlaceOrder Service

During checkout, when a buyer places an order, this extension runs cart validations as part of the [Place Order Action API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm). To implement custom validation logic, extend the base Apex class and override the `validate` method.

- **Base Apex class**: [CartExtension.CheckoutPlaceOrder](/docs/commerce/salesforce-commerce/references/comm-apex-reference/CheckoutPlaceOrder.html)
- **Extension point name**: Commerce_Domain_Checkout_PlaceOrder
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

### SplitShipment Service

During checkout, this extension arranges cart items across delivery groups. To implement custom Item Arrangement logic, extend the base Apex class and override the `arrangeItems` method.

- **Base Apex class**: [CartExtension.SplitShipmentService](/docs/commerce/salesforce-commerce/references/comm-apex-reference/SplitShipmentService.html)
- **Extension point name**: Commerce_Domain_Shipping_SplitShipment
- **Namespace**: `CartExtension`. See [Cart Reference](/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html).

## Domain Extensions for Order Management

The extension listed in this section is used for Order Management.

### ProductExpand Service

Expands product information by adding return reasons.

- **Base Apex class**: [commerce_ordermanagement.ProductExpandService](/docs/commerce/salesforce-commerce/references/comm-apex-reference/ProductExpandService.html)
- **Extension point name**: Commerce_Domain_OrderManagement_Product
- **Namespace**: `commerce_ordermanagement`. See [commerce_ordermanagement](/docs/commerce/salesforce-commerce/references/comm-apex-reference/ordermanagement-reference.html).

## Endpoint Extensions

Extends selected Connect API endpoints, allowing you to modify the endpoints request payload before the endpoint is called, or to modify the response after the endpoint is called, or both.

Unlike domain extensions, endpoint extensions extend the same base class.

- **Base Apex class**: [connectapi.BaseEndpointExtension](/docs/commerce/salesforce-commerce/references/comm-apex-reference/BaseEndpointExtension.html)

- **Namespace**: `connectapi`. See [connectapi](/docs/commerce/salesforce-commerce/references/comm-apex-reference/connectapi-reference.html).

### Account

- **Extension point name**: `Commerce_Endpoint_Account_Addresses` -- extends the [Commerce Webstore Account Addresses](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm) endpoint.
- **Extension point name**: `Commerce_Endpoint_Account_Address` -- extends the [Commerce Webstore Account Address](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm) endpoint.

### Product Catalog

- **Extension point name**: `Commerce_Endpoint_Catalog_Products` -- extends the [Commerce Webstore Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_products.htm) endpoint.
- **Extension point name**: `Commerce_Endpoint_Catalog_Product` -- extends the [Commerce Webstore Product](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product.htm) endpoint.

### Cart

- **Extension point name**: `Commerce_Endpoint_Cart_Item` -- extends the [Commerce Webstore Cart Item](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_item.htm) endpoint. Available in version 62.0 and later.
- **Extension point name**: `Commerce_Endpoint_Cart_ItemCollection` -- extends the [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm) endpoint. Available in version 62.0 and later.

### Product Search

- **Extension point name**: `Commerce_Endpoint_Search_Products` -- extends the [Commerce Webstore Search Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm) endpoint.
- **Extension point name**: `Commerce_Endpoint_Search_ProductSearch` -- extends the [Commerce Webstore Product Search](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm) endpoint.

### Product Suggestions

- **Extension point name**: `Commerce_Endpoint_Search_Suggestions` -- extends the [Commerce Webstore Product Search Suggestions](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_suggestions.htm) endpoint. Available in version 67.0 and later.

**See Also**

- [_B2B Commerce Developer Guide_: Register and Map Extension Class](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extensions.html)
- [_B2B Commerce Developer Guide_: Extension Provider Examples](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extension-provider-examples.html)

<!-- document id=76eee37d00d7bca7716063f96458b4b82e6dfda87c2a1435e092f276a318ea08 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-avoid-misconfigurations.md -->

# Avoid Common Misconfigurations

Diagnose and resolve common configuration issues across cart, checkout, pricing, and account-based flows.

- **Using Custom UI Before Checkout Completes**

  **Problem:** Custom UI components invoke before previous Checkout API completes (still returns 202).

  **Impact:** Components use incomplete or inconsistent data.

  **Solution:** Disable or hide custom components until API returns 200 OK.

- **Executing Custom Apex Prematurely**

  **Problem:** Custom Apex calls run without verifying Checkout API completed.

  **Impact:** Logic consumes incomplete data, leading to inconsistent results.

  **Solution:** Poll GET `/checkouts` until you receive 200 OK, then execute custom logic.

- **Invalid Custom Payment Configuration**

  **Problem:** Custom payment (like Cash on Delivery) doesn't meet API expectations.

  **Impact:** API returns "Looks like the payment method isn't authorized" error.

  **Requirements — Place Order API:**

  - Provide Purchase Order Number, OR
  - Provide valid PaymentMethod and PaymentGroup on WebCart

  **Place Order Action API:**

  - Provide Purchase Order Number, OR
  - Provide valid PaymentGroup on WebCart AND
  - Verify: TotalAuthAndSaleAmount + PendingAuthAndSaleAmount = GrandTotalAmount (or FirstPymtGrandTotalAmount for subscriptions)

- **Concurrent Cart Updates**

  **Problem:** Custom Apex modifies cart while Checkout API is in progress.

  **Impact:** Cart state mismatch causes "cart is currently in use" error.

  **Solution:** Avoid concurrent operations on the cart. Wait for Checkout APIs to return 200 OK before running custom code that modifies cart.

- **Price Book Mismatch on Order**

  **Problem:** Custom logic sets or updates Order.Pricebook2Id, creating mismatch with order products.

  **Impact:** Validation fails with "Order Products must have a Price Book Entry that belongs to the Price Book related to the parent Order" error.

  **Solution:**

  - Make sure that Order.Pricebook2Id matches the price book used by all order products, OR
  - Turn on the **Enable Multiple Price Books for Orders** setting

- **Billing Address Override**

  **Problem:** Custom Apex updates billing address before user enters checkout or before shipping address is provided.

  **Impact:** Payment details become invalidated, billing address is overridden or lost.

  **Solution:**

  - Use Checkout Payment API to set billing address, OR
  - Update billing address only after checkout reaches payment stage

- **Duplicate Orders and Order Summaries**

  **Problem:** Custom Record-After-Save flow (like Create Order Summary) runs on Order object, automatically creating Order Summary when Order record is created.

  **Impact:**

  - Cart isn't properly closed
  - OrderIngestionJob retries processing
  - Creates duplicate Orders and Order Summaries

  **Solution:** Configure the flow to exclude B2B web stores. Add conditions so the flow doesn't run for B2B checkout scenarios.

- **Order Summary Failure Without Payment Reversal**

  **Problem:** Place Order Actions API succeeds but asynchronous Order Summary creation fails (only affects Place Order Actions API).

  **Impact:** Order is placed but Order Summary creation fails, leaving transaction inconsistent. Payment remains captured and isn't automatically refunded.

  **Solution:** Turn on the `CheckoutReverseAuthEnabled` org permission to reverse payments if checkout fails or is cancelled. Note: Refunds can incur additional charges from the payment provider.

- **Missing Pay Now Template**

  **Problem:** Pay Now template doesn't appear when creating new store in Salesforce Foundation org.

  **Impact:** Can't access Pay Now template during store creation.

  **Solution:** Add free Salesforce add-on Payments license to enable Pay Now template.

- **Phone Number Validation Errors**

  **Problem:** Checkout fails with "Select your country from the dropdown menu, and then enter your phone number" or unexpected phone number format changes.

  **Impact:**

  - Validation fails for unsupported country codes (like Costa Rica)
  - Phone numbers normalize to E164 format, removing hyphens and formatting

  **Solution:** Enable CheckoutSkipPhoneValidation org permission to bypass validation if default behavior doesn't meet requirements.

- **Invalid Checkout Session Status**

  **Problem:** Custom flows invoke `Sfdc_Checkout.CheckoutOrderService.cartToOrderSummary` while Place Order Actions API is enabled.

  **Impact:** Method expects CheckoutSessionStatus to be PENDING_CLOSED but actual status is ACTIVE, causing "Invalid checkout session status" error.

  **Solution:**

  - Switch to Commerce Webstore Checkout Orders API, OR
  - Use Commerce Webstore Checkout Place Order Action API instead of custom Apex method

- **Asynchronous Payment Providers with Place Order API**

  **Problem:** Payment providers confirm payments asynchronously but you're using Place Order V1.

  **Impact:** Orders are created regardless of payment status. Payment confirmation occurs later, potentially after order creation without successful payment.

  **Solution:** Switch to Commerce Webstore Checkout Place Order Action API, which creates orders only after receiving payment confirmation.

- **Concurrent Order Retrieval After Order Placement**

  **Problem:** Custom Apex retrieves orders immediately after invoking Place Order API.

  **Impact:** Order creation occurs asynchronously. Concurrent requests cause record locking issues and failures in order creation.

  **Solution:** Avoid running custom logic that queries or modifies orders concurrently with asynchronous cart-to-order process.

- **Long-Running Callouts in Extensions**

  **Problem:** Extensions include callouts taking longer than 2 seconds.

  **Impact:** Total processing time exceeds limits (over 5 seconds), causing integration retries. Multiple processes contend for same cart resources.

  **Solution:**

  - Make sure that callouts complete within 2 seconds, OR
  - Don't invoke GET /checkouts prematurely—allow time for previous operation to complete

- **Custom Validation Exceptions**

  **Problem:** Validation rule or trigger blocks record updates during cart-to-order or order summary processing.

  **Impact:** Process fails with FIELD_CUSTOM_VALIDATION_EXCEPTION, interrupting checkout completion.

  **Solution:** Review and update validation rules and triggers to align with checkout and order creation flow.

- **ListPrice Mapping**

  **Problem:** CartItem.SalesPrice maps to OrderItem.ListPrice by default, but you expect CartItem.ListPrice to map instead.

  **Impact:** Mapping appears incorrect based on expectations.

  **Solution:** Enable SalesPriceToListPriceMap org permission to map CartItem.ListPrice to OrderItem.ListPrice.

- **Missing CartValidationOutput Records**

  **Problem:** Custom extensions (Tax, Inventory, Pricing, Promotions, Shipping) don't create CartValidationOutput records when failures occur.

  **Impact:** Checkout remains in inconsistent or blocked state, making it difficult to surface and handle errors.

  **Solution:** Make sure that all extensions create CartValidationOutput records upon failure.

- **Creating Checkout Session via Custom Apex**

  **Problem:** Custom Apex creates CartCheckoutSession records while also using POST /checkouts API.

  **Impact:** POST `/checkouts` API doesn't expect existing checkout session, leading to conflicts or unexpected behavior.

  **Solution:** Use the POST `/checkouts` API exclusively to manage checkout session creation. Avoid custom implementations for out-of-the-box functionality.

<!-- document id=5c9ee3fe7561ce783a63c1dcf5526fe279021dd9d0db3d4a817d4a688cd516c4 url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-aws-s3.md -->

AWS S3

# AWS S3

If integration is configured with AWS, some integrated operations may be used.

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### POST Create Pre-Signed URL

`POST /services/apexrest/Atonit_Mktplace/v1/aws/get_pre_signed_url`

Operation ID: `Create Pre-Signed URL`. Tags: AWS S3. Security: bearerAuth.

This call allows the creation of a pre-authenticated URL for a file on the AWS S3. The returned URL may be used for a PUT call to upload the content of the file and the URL without the query string may be sent subsequently as a file URL field value, e.g., to record an invoiced payment slip.

The URL only allows temporary PUT access for the specific file.

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "objectType": "BilledTicket",
  "objectId": "billed-1",
  "fileName": "nf.xml"
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Thu, 27 May 2021 13:03:15 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    https://[example].s3.sa-east-1.amazonaws.com/salesforce/c9THr3vbxs6DgG3d6Ru88lmxiHYM4m2Zc5cgJpG_01o-/c-BilledTicket/pIBvnG.Qnw6lKouiHy5XS81IU2HZx1iGYKV4lwHgGSQ-/nf.xml?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=XXXXXXXXXXXXXXXXXXX%2F20210527%2Fsa-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210527T130315Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=55023f3a48588a2f7a3a57f98df3322c65bc48991bbc1c7c7965339374fd58c2
    ```

<!-- document id=39ef51491a2b8d1f05edc12e5c6cffe5d555b0c9b14e83d0b39beb50593e23e1 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-calculators.md -->

# B2B Commerce Checkout Calculators

Calculators run automatically when you invoke Checkout APIs. They compute pricing, promotions, taxes, inventory, and shipping for the cart. See [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.html) for calculator execution details.

![Diagram showing how checkout calculators compute taxes, shipping, and promotions during the B2B Commerce checkout process](https://developer.salesforce.com/media/d2c-commerce/commerce-checkout-calculators.png '{"class": "image-lg", "title": "Commerce Checkout Calculators"}')

## Calculator Execution by API

**Start Checkout:** PUT [`/commerce/webstores/{webstoreId}/checkouts`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm)

Always runs:

- Pricing
- Promotions
- Inventory

Additionally runs if address is available:

- Shipping
- Tax

**Update Checkout:** PATCH [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)

Runs when payload includes address:

- Shipping
- Tax

Runs when payload includes shipping method:

- Tax

## Wait for Completion

While calculators run, the API returns 202 Accepted. Continue polling GET [/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) until you receive 200 OK, indicating all calculators completed.

**Note:** Don't invoke another Checkout API until the previous request returns 200 OK.

<!-- document id=8479c0b41091164fee7c71a1e0889e1cdb9c0f829b24937fd3bf825c8e58f957 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-data-deployment.md -->

# B2B Commerce Data Deployment

The data deployment process is a critical step in integrating existing commerce systems into a new platform.

Deploying B2B Commerce store data involves moving these datasets in ‌this order.

- Store Metadata
- Experience Bundle Metadata
- Object Data

To ensure accuracy and efficiency for each data deployment, organize your deployment into phases.

1. **Plan**–Set goals and develop a migration strategy.
2. **Prepare data**–Clean, organize, and make sure that it meets the new system requirements.
3. **Map data fields**–From the old system to the new, a crucial task that dictates how data is transferred and interpreted in the new environment.
4. **Deploy data**–Use your preferred tools or scripts.
5. **Test and validate data**–Confirm that the store functions correctly and the data integrity is maintained.
6. **Correct deployment errors**–Based on feedback and performance analysis, identify and resolve errors.

## Create a Deployment Plan

Deploying a B2B Commerce store involves coordinating the deployment of store metadata, experience metadata, and Salesforce object data. All aspects of the store are moved to the target org. Developing a detailed deployment plan is critical to a successful deployment and having the store function as expected in the new environment.
Use this sample plan as a basis for executing your deployment process from a source org to a target org, modifying the steps as needed.

1. Review your business objectives.

   - Confirm that the deployment aligns with your business goals.
   - Make sure that the target org launch is scheduled at a time that minimizes impact on business operations.

2. Assess the source org.

   - Make sure that the source org meets your requirements.
     - Performance: load time, response time, and scalability
     - Functionality: feature verification, customization verification, and integration
     - Security: vulnerability scanning, access controls, and data protection
     - Data integrity
     - Regulatory compliance
     - Backup and recovery: rollback procedures, backup procedures, and disaster recovery
     - Monitoring and logging
   - Determine the scope of object data, experience metadata, and store metadata that you plan to migrate.

3. Specify how the existing object data and metadata map to the new Salesforce environment.

   - Data mapping can involve field mapping, data transformation requirements, and identifying gaps in functionality.

4. Develop a data deployment strategy.

   - Outline the order of deployment to account for data dependencies and how to recreate or improve the new environment.

5. Validate the data.

   - Perform a thorough analysis of the object data being deployed, for example, product catalogs, customer information, order history, entitlements, and pricing.
   - Validate that all the necessary object data is correctly configured.
   - Plan for data cleansing, deduplication, and transformation as necessary.
   - Make sure that all demo data used in the source org is identified and excluded from the deployment to the target org.

6. Conduct performance benchmarking.

   - Conduct performance testing in the source org to establish benchmarks.
   - Make sure that the target org is scaled appropriately to handle expected traffic and transaction volumes.

7. Complete a security compliance check.

   - Review security settings and compliance with relevant object data protection regulations.
   - Verify that the required user roles and permissions are correctly set up for the target org.

8. Construct a deployment checklist.

   - Create a checklist of all items that are being migrated, including metadata, configurations, code, and object data.
   - Make sure that all dependencies and the order of operations are documented.

9. Develop a backup strategy and rollback plan in case issues arise during the deployment.

   - Have a rollback plan in case issues arise during the deployment.

10. Conduct a dry run to identify potential issues.

    - Validate the deployment checklist, and refine the process.
    - Use a version control system.
    - Test in a sandbox environment.

11. Plan the deployment window and downtime.

    - To minimize the impact on users and operations, schedule the deployment during a low-traffic period.
    - Communicate the planned downtime to all stakeholders well in advance.

12. Develop a User Acceptance Testing (UAT) plan to execute immediately after deployment.

    - Define clear criteria for success, and establish a process for reporting and addressing issues.

13. Develop training and documentation.

    - Update existing documentation to make sure that it reflects changes made to the target org.
    - Schedule training sessions for users on new features or changes in the target org.

14. Develop a communication plan.

    - Inform internal teams and external customers about the deployment and expected changes.
    - Establish a support plan that handles inquiries and issues post-deployment.

<!-- document id=42bb274d7ee43a372fad8a0325f63234ab15509ff38c7a4f23f100612524b7b4 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-dev-data-model.md -->

# B2B Commerce Data Model

The Commerce store template is built on a pre-configured data model. The data model supports standard and customizable business objects for a multitude of business relationships and interoperability with B2B stores, Salesforce Order Management, and Agentforce Service.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

The Commerce data model connects the store objects. Default object relationships support a full-featured B2B store experience.

![Diagram of B2C data  model.](https://developer.salesforce.com/media/d2c-commerce/commerce_data_model.png)

Among the object relationships in the Commerce app data model are those that you use to quickly:

- Add product catalogs to provision your stores.
- Configure product variants (product size, shape, color, and so on), categories, bundles, and more.
- Select customer search capabilities and how your store displays results.
- Differentiate buyer groups and associate them with specific products and volume-discounted prices.
- Configure tax, shipping, and payment for cart checkout.
- Create promotional campaigns for targeted products.

Here’s a list of some of the default data model objects.

| Data Model Object  | Description                                                                                                                                                                                                                             | API Name                                                                                                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Store              | A website where buyers and shoppers complete wholesale and retail transactions. Includes the fields and properties that define your store. For example, supported currencies, languages, and price books. Many fields are customizable. | [WebStore](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm?q=webstore)                                                    |
| Cart               | Represents an online shopping cart in a store built with B2B Commerce on Lightning, with total amounts for products, shipping and handling, and taxes.                                                                                  | [WebCart](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webcart.htm)                                                                 |
| Catalog            | A catalog is a collection of the products that you sell, organized into different categories. The Commerce Admin or Merchandiser uses data import to set up the catalog.                                                                | [ProductCatalog](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcatalog.htm?q=ProductCatalog)                                  |
| Category           | Categories and subcategories organize and group products in your catalog and on your storefront. Layout is customizable.                                                                                                                | [ProductCategory](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcategory.htm?q=ProductCategory)                               |
| Entitlement Policy | Entitlement policies are simple entities that bring together buyer groups and products. Filtered by BuyerGroup membership. Includes CanViewPrice and CanViewProduct fields, which are customizable.                                     | [CommerceEntitlementPolicy](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_commerceentitlementpolicy.htm?q=CommerceEntitlementPolicy) |
| Product            | The items and services you sell. The Commerce Admin or Merchandiser uses data import to fill in a default compact layout, which includes a variety of customizable fields (name, family, and so on).                                    | [Product2](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm?q=Product2)                                                    |
| Buyer Account      | The buyer’s or shopper’s financial information, including credit and order limits, some of which pertain only to B2B.                                                                                                                   | [BuyerAccount](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyeraccount.htm?q=BuyerAccount)                                        |
| Buyer Group        | A group of buyers with the same assigned entitlement policies, price books, and products. Buyer Group name and description are customizable.                                                                                            | [BuyerGroup](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergroup.htm?q=BuyerGroup)                                              |
| Buyer Group Member | An individual buyer associated with a buyer group.                                                                                                                                                                                      | [BuyerGroupMember](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergroupmember.htm?q=BuyerGroup)                                  |
| Price Book         | A price book contains price definitions for a group of products. Typically added during setup with your store’s data import, but you can add custom fields.                                                                             | [PriceBook2](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebook2.htm?q=PriceBook2)                                              |
| Price Book Entry   | A product entry (an association between a Pricebook2 and Product2) in a price book.                                                                                                                                                     | [PricebookEntry](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebookentry.htm?q=PricebookEntry)                                  |

<!-- document id=b334e3edfca2224e5425e23a225a7f02aa6a7be44e5a4caf41048bf6b2d0f8ce url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-einstein-b2b-reco-api-ref.md -->

# B2B Commerce Einstein Product Recommendations API

Calls to the Product Recommendation API deliver Einstein recommendations. The API is accessed using a Connect API to provide data to a Lightning web component. The Connect API returns a set of products to populate the Commerce Einstein Recommb2b_b2c_comm_einstein_reco_api_refendations component.

## Commerce Einstein Webstore Recommendations Resource

The Commerce Einstein Recommendations Connect API resource (`/commerce/webstores/{webstoreId}/ai/recommendations`) returns Einstein product recommendations.

## Recommender Names and Anchors

You can add one or more Einstein Recommendations components to any page in B2B Commerce stores. When using a product recommender, such as `SimilarProducts` or `ComplementaryProducts`, specify product IDs. When using a category recommender, such as `MostViewedByCategory` or `TopSellingByCategory`, specify category IDs. All other anchors are supported on any page, but they’re intended for use on certain pages.

B2B recommenders don’t require that you specify an anchor type. The Connect API automatically determines the anchor type based on the anchor values and the recommendation use case that you specify.

| Anchor Type | Anchor Value                                                                                                                   | Fields Returned                                                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No anchor   | Any value that evaluates to false. For example: null or undefined.                                                             | <ul><li>RecentlyViewed</li><li>TopSelling</li><li>PersonalizedForShopper</li></ul>                                                                                      |
| Product ID  | A list of one or more 18-character product IDs. For example: `01t000000000000001`, `01t000000000000002`, `01t000000000000003`  | <ul><li>RecentlyViewed</li><li>SimilarProducts</li><li>ComplementaryProducts</li><li>CustomersWhoBoughtAlsoBought</li><li>Upsell (not supported at this time)</li></ul> |
| Category ID | A list of one or more 18-character category IDs. For example: `0ZG000000000000001`, `0ZG000000000000002`, `0ZG000000000000003` | <ul><li>RecentlyViewed</li><li>MostViewedByCategory</li><li>TopSellingByCategory</li></ul>                                                                              |

For example, a URL containing an anchor value for the connect API looks like this.

```nolang
/services/data/v55.0/commerce/webstores/0ZERM00000009eR/ai/recommendations?recommender=SimilarProducts&anchorValues=01tRM000000R8DnYAK,01tRM000000R8DWYA0
```

**See Also**

- [Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_apis.htm)
- [Prepare Commerce Einstein to Use Custom Components](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_prepare_einstein_custom_comps.htm)
- [Create a Custom Recommendations Component for B2B Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_create_b2b_cust_ein_reco_comp.htm)
- [Commerce Einstein Webstore Recommendations](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_ai_recommendations.htm)

<!-- document id=db5405c770b105cdb84d1c514b4b303e3b9a59c7bad5850b82dd563af34b1896 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-api-architecture.md -->

# B2B Commerce Headless API Architecture

Salesforce B2B Commerce Headless enables organizations to build fully customized buyer experiences while leveraging Salesforce Commerce APIs as the backend commerce engine.

![High-level architecture for Salesforce B2B Commerce Headless](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-api-architecture-figure-image-3-1.png '{"class": "image-lg", "title": "B2B Commerce Headless API Architecture"}')

In a headless architecture, the frontend presentation layer is separated from the commerce backend. This allows frontend teams to design and deliver modern digital commerce experiences across multiple channels and platforms.

The Salesforce Commerce Connect REST APIs provide the core commerce capabilities required to power the storefront experience, including:

- Authentication
- Product discovery and search
- Category navigation
- Product detail retrieval
- Cart and checkout orchestration
- Pricing and promotions
- Order placement and order history
- Account and profile management

**Benefits of Headless Commerce Architecture**

- Frontend Flexibility–Build custom buyer experiences using any frontend framework.
- API-Driven Architecture–Reuse commerce capabilities across web, mobile, and other channels.
- Independent Release Cycles–Frontend and backend teams can iterate independently.
- Omnichannel Enablement–Support multiple customer touchpoints consistently.
- Scalability–Scale frontend applications independently from commerce services.
- Faster Innovation–Rapid experimentation and UI modernization.
- Composable Architecture–Integrate external systems and services more easily.

**Architecture Comparison: Headless and Experience Builder**

Choose a headless architecture or an Experience Builder storefront based on your business needs, customization needs, and operating model.

Both architectures support Salesforce B2B Commerce capabilities. A headless architecture is useful when your organization requires an independently managed storefront experience or a custom frontend implementation.

| Architectural Dimension     | Experience Builder (Standard Site)                                                    | Headless Architecture                                                                     |
| --------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Speed to market             | Uses prebuilt templates and components to accelerate storefront setup and deployment. | Requires custom storefront development and frontend implementation.                       |
| Design and UI customization | Supports customization within the Experience Builder framework and component model.   | Supports full control over storefront design, layout, and user experience.                |
| Deployment model            | Frontend and backend updates follow Salesforce deployment and release processes.      | Frontend applications can be deployed independently from backend commerce services.       |
| Operational responsibility  | Salesforce manages hosting, scaling, and core platform infrastructure.                | Your organization manages frontend hosting, deployment pipelines, and integration layers. |

<!--
**Multi-Framework Commerce API Support**

Salesforce Multi-Framework currently supports React. You can also use the Salesforce Commerce Connect REST APIs to build storefronts with other frontend frameworks, such as Angular or Vue.js, or with custom frontend implementations. However, storefronts built with frameworks other than React aren’t part of Salesforce Multi-Framework support.

This approach lets organizations adopt a composable commerce architecture while using a centralized backend commerce platform.
-->

<!-- document id=8d660ac49d7cb8734e11cca1e5c0b7c09117952d281355a647fc718846bd3179 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-end-to-end-buyer-journey.md -->

# B2B Commerce Headless Flow Orchestration

The storefront implementation is organized around the following buyer lifecycle:

![Storefront Home Overview](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-storefront-home-overview-6-1.png '{"class": "image-lg", "title": "Storefront Home Overview"}')

To see this buyer journey implemented end to end, explore the [B2B Commerce headless reference app](https://trailsignup-9caf26dfcaf0fa.my.site.com/commerceb2bheadless) and its [source code on GitHub](https://github.com/trailheadapps/commerce-b2b-headless).

Each stage is documented with:

- User flows
- Frontend implementation details
- Connect REST APIs used
- Authentication requirements
- State transitions
- Error handling considerations
- Performance recommendations

The full journey sections are documented in these topics:

- [Storefront (Home)](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-storefront-home.md)
- [Product List Page (Category/PLP)](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-product-list-page.md)
- [Product Detail Page (PDP)](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-product-detail-page.md)
- [Cart](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-cart.md)
- [Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-checkout.md)
- [Order Confirmation](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-order-confirmation.md)
- [Orders (History)](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-orders-history.md)
- [Login](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-login.md)
- [Register](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-register.md)
- [Profile](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-profile.md)

<!-- document id=dbb729abd10e2627ddc5ff4e41214be0192cbb78b9fa2fc5042b7f2039b3ed39 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-journey-overview.md -->

# B2B Commerce Headless Storefront Implementation Overview

Build fully customized B2B storefront journeys for registered users using Salesforce B2B Commerce APIs. This topic provides a comprehensive reference for leveraging Salesforce Commerce Connect REST APIs with the front-end framework and architecture of your choice.

<!--This topic covers a React-based Salesforce B2B Commerce store that shows how to use the React-based system and how buyers experience the entire process.-->

To see these APIs in a working implementation, explore the [B2B Commerce headless reference app](https://trailsignup-9caf26dfcaf0fa.my.site.com/commerceb2bheadless) and its [source code on GitHub](https://github.com/trailheadapps/commerce-b2b-headless).

Topics covered include:

- B2B Commerce Headless API Architecture
- Authentication and session management
- Product discovery and search
- Category navigation
- Product detail retrieval
- Cart and checkout orchestration
- Pricing and promotions
- Order placement and order history
- Account and profile management

<!--- Topics covered include:

- [B2B Commerce Headless API Architecture](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-api-architecture.md)
[Reference React Storefront Implementation](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-reference-react-storefront-implementation.md)
- [B2B Commerce Headless Flow Orchestration](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-end-to-end-buyer-journey.md)
  - [Storefront Home](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-storefront-home.md)
  - [Product List Page](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-product-list-page.md)
  - [Product Detail Page](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-product-detail-page.md)
  - [Cart](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-cart.md)
  - [Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-checkout.md)
  - [Order Confirmation](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-order-confirmation.md)
  - [Orders History](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-orders-history.md)
  - [Login](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-login.md)
  - [Register](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-register.md)
  - [Profile](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-headless-profile.md)-->

<!-- document id=04678d25d6314c9b535c722325732f2be984d942de3a60ca9a1d1d899bd64c06 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/b2c-developer-tooling-agent-skills.md -->

# B2C Commerce Agent Skills

Empower your AI assistant with B2C Commerce knowledge and practical workflows. Agent Skills in the [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md) cover storefront development, CLI operations, and incident investigation for administrators and operators.

## Skill Collections

| Collection | What it helps your assistant do |
| --- | --- |
| `b2c` | Build controllers, ISML templates, forms, services, Custom APIs, Page Designer components, and custom job steps. |
| `b2c-cli` | Use the B2C CLI for deployments, jobs, site archives, sandboxes, SLAS, eCDN, Managed Runtime, and logs. |
| `storefront-next` | Build Storefront Next routes and components, work with Page Designer, and deploy storefronts. |
| `b2c-ops` | Investigate incidents and failed orders, gather evidence, and prepare an actionable handoff. |

## Use Skills with the B2C MCP

For an assistant that can both provide guidance and work with your B2C Commerce environment, [install the B2C MCP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md#connect-your-ai-assistant). It includes these collections and makes their guidance available through MCP tools. No need to separately install the skills plugins.

You can also install collections as native skills in your assistant, alongside the MCP or on their own. This is useful when you want development guidance without a server connection, or prefer to use the CLI for operations.

## Install Skills Separately

Install the collections you need through your assistant's plugin support. For example, in Claude Code:

```bash
claude plugin marketplace add SalesforceCommerceCloud/b2c-developer-tooling
claude plugin install b2c@b2c-developer-tooling --scope project
claude plugin install b2c-cli@b2c-developer-tooling --scope project
# Optional: install storefront-next or b2c-ops from the same marketplace.
```

The plugins use the open [Agent Plugins](https://agent-plugins.org/) standard; individual skills follow the [Agent Skills](https://agentskills.io/) format. See [Agent Skills installation](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills.html) for Codex, VS Code, other assistants, and manual installation. If your assistant uses CLI commands, it also needs access to the [B2C CLI and configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md#run-the-b2c-cli).

**note:** Manually installed skills don't auto-update. Refresh your local copies to receive new guidance, or use your assistant's plugin update mechanism.

## Try a Task

Describe the outcome you want and identify the project or instance to use:

> Help me create a Custom API for loyalty information and check its registration on my sandbox.

> Add logging to my checkout controller using B2C Commerce conventions.

> Investigate failed orders from the last hour. Gather evidence and recommend next steps before making changes.

Skills guide your assistant's work. They don't grant access to an instance. The tools your assistant uses still require the appropriate credentials and permissions. See [Configuration and Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md#configuration-and-authentication).

<!-- document id=c71835947d26898466f4955ab63c4834f1d8a6e781d86203470a6908364243d6 url=/developer/current/en-us/commerce-cloud/commerce-api/references/about/scapi-api-doc.md -->

# B2C Commerce API (SCAPI) Specifications

You are viewing SCAPI documentation. To view the full SCAPI reference specifications in the left navigation, select the **Reference** tab (if you are currently in the **Guides** tab).

To view additional API specifications:

- <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/" target="_blank" class="external-link-guide">Composable Storefront API</a>
- [OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/)
- [B2C Commerce Developer Resources (Script API)](https://salesforcecommercecloud.github.io/b2c-dev-doc/)
- <a href="https://developer.salesforce.com/docs/commerce/einstein-api/references/" target="_blank" class="external-link-guide">B2C Commerce Einstein API</a>

<!-- document id=7e00bfc10cdfd880493a9e53ee3f887514a49e1a2c628f8a13391df14c513d6d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/api-doc.md -->

# B2C Commerce API Documentation

Use these B2C Commerce APIs to customize your storefront or build your own custom storefront.

- [Get Started with B2C Commerce API](https://developer.salesforce.com/docs/commerce/commerce-api/guide) (also called Salesforce Commerce API or SCAPI)
- [Get Started with Open Commerce API (OCAPI)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/)
- [B2C Commerce Developer Resources (Script API)](https://salesforcecommercecloud.github.io/b2c-dev-doc/)
- [Get Started with B2C Commerce Einstein API](https://developer.salesforce.com/docs/commerce/einstein-api/guide)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)
- [Determine Deprecated API Usage](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-customize-business-manager.md#determine-deprecated-api-usage)
- [B2C Commerce Storefront Options](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/which-product.md)

<!-- document id=d0d960907babfdb4e8617469c9462d429093b6a45a706d63a75466d28d62eafe url=/developer/current/en-us/commerce-cloud/commerce-api/references/about/about.md -->

# B2C Commerce API Release Notes

Use B2C Commerce API (also known as Salesforce Commerce API or SCAPI) to build headless commerce experiences.

- For status updates and trust notifications, go to the [B2C Commerce Status Page](https://status.salesforce.com/products/B2C_Commerce_Cloud).
- For the general B2C Commerce release notes, go to [Salesforce Help](https://help.salesforce.com/s/articleView?id=commerce.b2c_rn_release_notes.htm&language=en_US&type=5).
- To view the change policy, see: [Change Policy](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html#change-policy).
- To use the SDK to **make your first call quickly**, see the [Quick Start](/docs/commerce/commerce-api/guide/api-and-sdk-demo.html).
- For details about **auth**, see [Authorization](/docs/commerce/commerce-api/guide/authorization.html).
- To learn about **using B2C Commerce API**, see the [Guides](/docs/commerce/commerce-api/guide).
- To learn about **using correlation IDs**, see [Investigate by Correlation ID](/docs/commerce/commerce-api/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id).
- To **browse the API endpoints**, use the left navigation. B2C Commerce API is broken into two main groups: Shopper APIs and Admin APIs. All Shopper API groups start with _Shopper_. For details about the differences, see [Get Started](/docs/commerce/commerce-api/guide).
- Note: All secrets and tokens are fictional and provided as placeholders only.
- Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

## 10/13/2026

### SLAS Release

- SLAS infrastructure updates for US-East. No customer impact is anticipated.
  - Schedule:
    - US-East: October 13, 2026 at 9:00 PM MT (October 14, 2026 at 3:00 AM UTC)

## 10/08/2026

### SLAS Release

- SLAS infrastructure updates for EU-Central. No customer impact is anticipated.
  - Schedule:
    - EU-Central: October 8, 2026 at 5:00 PM MT (11:00 PM UTC)
- mTLS Enforcement
  - To enhance the security of the SLAS authentication service, we’re enabling mutual TLS (mTLS) client-certificate enforcement at the SLAS gateway. Starting October 7, 2026, SLAS rejects any request that reaches the SLAS origin without a valid client certificate, including a request that bypasses the SCAPI zone.
  - Who is affected:
    - No action is required for integrations that use the standard, published Commerce Cloud SLAS endpoints through the SCAPI zone. This path is the supported integration path and continues to work without changes.
    - Action is required for integrations that connect directly to the SLAS origin and bypass the SCAPI zone, for example integrations that use a hardcoded origin hostname, IP address, or custom network path. SLAS rejects these requests after mTLS enforcement is enabled.
  - Schedule:
    - AP2: October 7, 2026
    - AP3: October 8, 2026
    - EU: October 12, 2026
    - US-East: October 15, 2026

## 10/07/2026

### SCAPI Release

Updated APIs:

- [Assignments](https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments?meta=Summary) 1.0.39
  - `Schedule` no longer requires `startDate`, `endDate`, or `recurrence`. Omitting a bound leaves that side of the validity window open.
  - `timeFrom` and `timeTo` accept `HH:mm` or `HH:mm:ss`. Seconds are ignored and set to 0.
- [Campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns?meta=Summary) 1.1.1
  - Promotion campaign assignment `rank` must be null or a multiple of 10 from 0 to 100.
  - `Schedule` no longer requires `startDate` or `endDate`. Omitting a bound leaves that side of the validity window open.
  - `timeFrom` and `timeTo` accept `HH:mm` or `HH:mm:ss`. Seconds are ignored and set to 0.
- [Environments](https://developer.salesforce.com/docs/commerce/commerce-api/references/environments?meta=Summary) 1.0.5
  - `updateEnvironment` (`PATCH /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}`) now updates server-side rendering configuration in addition to `displayName`. The request is a partial update: only the supplied fields change, and at least one field is required. `displayName` is no longer required.
  - The environment resource and the update request now include `ssrRegion`, `ssrArchitecture` (`x86` or `arm64`), `ssrExternalHostname`, `ssrExternalDomain`, `ssrWhitelistedIps`, `ssrProxyConfigs` (up to 8 proxies; `path`, `host`, and `https` only), `isProduction`, `allowCookies`, `preserveProxyUserAgent`, `enableSourceMaps`, `logLevel` (`trace`, `debug`, `info`, `warn`, `error`, `fatal`), `distributedTracing`, `distributedTracingSamplingRate`, and `certificateId`.
  - For an environment served through eCDN, update `ssrExternalHostname`, `ssrExternalDomain`, and `ssrWhitelistedIps` in Business Manager. The API rejects those changes.
  - `allowCookies` can't be changed on a Storefront Next environment. Cookies stay enabled.
  - Selecting `x86` for `ssrArchitecture` is rejected when the organization isn't permitted to configure SSR architecture, and after x86 end of life. Use `arm64`.
  - `certificateId` is rejected when the certificate is missing, not validated, doesn't match the hostname domain, or the environment uses the default Managed Runtime domain.
- [Preferences](https://developer.salesforce.com/docs/commerce/commerce-api/references/preferences?meta=Summary) 1.2.3
  - Site `cartridges` is now read-only. It returns the effective cartridge path, including system cartridges and the site's custom cartridges.
  - Added `customCartridges`, the configurable custom cartridge path. It does not include system cartridges.
- [Schemas](https://developer.salesforce.com/docs/commerce/commerce-api/references/scapi-schemas?meta=Summary) 1.0.3
  - Schema search accepts `cartridgeName` to filter Custom API schemas. The schema listing includes `cartridgeName` for Custom APIs.
- [Shopper Agents](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-agents?meta=Summary) 1.1.5
  - Guest shopper calls can use `ShopperClientContextToken` with the `sfdc_usid` header. Registered shoppers continue to use `ShopperToken`.
- [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) 1.1.4
  - Guest shopper calls can use `ShopperClientContextToken` with the `sfdc_usid` header. Registered shoppers continue to use `ShopperToken`.
  - Error responses for these operations use `application/problem+json`.
- [Storefronts](https://developer.salesforce.com/docs/commerce/commerce-api/references/storefronts?meta=Summary) 1.0.4
  - `ssrRegion` values use underscores instead of hyphens. For example, `us-east-2` is now `us_east_2`.
  - `DELETE /organizations/{organizationId}/storefronts/{storefrontId}` returns 409 (`StorefrontBusyErrorResponse`) when a deletion of that storefront is already in progress.

- Updated list of cached API responses: `/shopper-experience` and `/custom` are temporarily not cached in SCAPI CDN cache for its specific handling of authentication.
- Infrastructure change for API validation on Staging and Production instances only. No customer impact is anticipated.
- Bug fixes and internal improvements.

## 09/29/2026

### SLAS Release

- [Auth Admin](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=Summary)
  - The [Delete Shopper endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=deleteShopper) (`DELETE /tenants/{tenantId}/customers/{customerId}`) now accepts tenant-scoped Account Manager automation tokens, in addition to service-admin and organization-admin credentials.
    - To use it, call the endpoint with a `client_credentials` Account Manager token that has the CCDX_SBX_USER role and is scoped to the target tenant. Tokens without a matching tenant scope are rejected. Deletion behavior, including the rate limit of 100 requests per minute, is otherwise unchanged.
- mTLS Enforcement
  - To enhance the security of the SLAS authentication service, we’re enabling mutual TLS (mTLS) client-certificate enforcement at the SLAS gateway. Starting October 6, 2026, according to the new per-region schedule listed below, any request reaching the SLAS origin without a valid client certificate—including requests that bypass the SCAPI zone—will be rejected.
  - Who is affected:
    - No action required: for integrations using the standard, published Commerce Cloud SLAS endpoints through the SCAPI zone. This is the supported integration path and will continue to work without changes.
    - Action required: for integrations that connect directly to the SLAS origin and bypass the SCAPI zone—for example, by using hardcoded origin hostnames/IP addresses or a custom network path. These requests will be rejected once mTLS enforcement is enabled.
  - Schedule:
    - AP2: October 6, 2026
    - AP3: October 8, 2026
    - EU: October 12, 2026
    - US-East: October 15, 2026

## 09/25/2026

### SCAPI Release

New APIs:

- [Deployments](https://developer.salesforce.com/docs/commerce/commerce-api/references/deployments?meta=Summary) 1.0.5
  - Upload versioned server-side rendering (SSR) bundles and deploy them to a storefront environment on Managed Runtime.
  - Endpoints:
    - `GET/POST /organizations/{organizationId}/storefronts/{storefrontId}/bundles`
    - `GET/POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/deployments`
    - `GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/deployments/{deploymentId}`
- [Environments](https://developer.salesforce.com/docs/commerce/commerce-api/references/environments?meta=Summary) 1.0.3
  - SCAPI-native access to Managed Runtime environments for a storefront: create, list, update display name, delete, clone, and promote to primary.
  - Also manages environment variables, CDN cache invalidations, header-based access control, and URL redirects.
  - Environment create/delete are asynchronous. Poll the environment by ID.
  - Endpoints:
    - `GET/POST /organizations/{organizationId}/storefronts/{storefrontId}/environments`
    - `POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/clone`
    - `GET/PATCH/DELETE /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}`
    - `PUT /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/primary`
    - `POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/cache-invalidations`
    - `GET/PATCH /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/environment-variables`
    - `GET/POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/access-control-headers`
    - `GET/DELETE /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/access-control-headers/{accessControlHeaderId}`
    - `GET/POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects`
    - `GET/PATCH/DELETE /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/{redirectId}`
    - `POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/actions/clone`
- [Storefronts](https://developer.salesforce.com/docs/commerce/commerce-api/references/storefronts?meta=Summary) 1.0.2
  - Added SCAPI-native provisioning for Storefront Next and partial administration for PWA Kit. This API replaces the Business Manager and Data API setup flow so that the CLI and tooling can automate the storefront lifecycle.
  - Create and delete operations are asynchronous. The API returns immediately. Poll the storefront by ID until setup completes.
  - Endpoints:
    - `GET /organizations/{organizationId}/storefronts`
    - `POST /organizations/{organizationId}/storefronts`: The first request returns 202. A retry with the same name returns 409 while the record exists.
    - `GET /organizations/{organizationId}/storefronts/{storefrontId}`
    - `PATCH /organizations/{organizationId}/storefronts/{storefrontId}`: Replaces the assigned sites list.
    - `DELETE /organizations/{organizationId}/storefronts/{storefrontId}`: The first request returns 202. After the storefront is deleted, a retry returns 404.

Updated APIs:

- [Auth Admin](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=Summary) 1.19.0
  - Log out up to 50 shoppers in one request by `loginId`. This request revokes refresh tokens and inactivates access tokens across all sessions. Shoppers must sign in again. Passwords are unchanged.
  - The API skips duplicate `loginId` values as `not_processed`. The response reports `success`, `failure`, or `not_processed` for each `loginId`.
  - New endpoint:
    - `POST /tenants/{tenantId}/batch-logout`
  - For details, see [Log Out Multiple Shoppers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-batch-logout.html).
- [Experiences](https://developer.salesforce.com/docs/commerce/commerce-api/references/experiences?meta=Summary) 1.4.0
  - Added admin retrieval of Page Designer types for a site. The `siteId` query parameter is required.
  - New endpoints:
    - `GET /organizations/{organizationId}/component-types`: Returns component types with group, region definitions, and attribute definitions.
    - `GET /organizations/{organizationId}/page-types`: Returns page types with region definitions, attribute definitions, and supported aspect types.
- [Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=Summary) 1.6.4
  - Added normalized, read-only payment enrichment on existing order resources. The API omits these objects when no data is available. Historical orders remain readable.
  - `PaymentInstrument.fraudDecisions`: `preAuthorization` and `postAuthorization`.
  - `PaymentInstrument.paymentDetails`: `type`, `brand`, `last4`, `walletType`, `expirationMonth`, `expirationYear`, `token`, `tokenType`, `accountHolderName`, `bin`, `dpanLast4`, `issuingCountry`, and `fundingType`.
  - `PaymentTransaction.transactionDetails`: `cvcResult`, `avsResult`, `threeDSResult`, `threeDSVersion`, `threeDSTransactionId`, `electronicCommerceIndicator`, `approvalCode`, `reasonCode`, and `processorResponseText`.
- [Price Books](https://developer.salesforce.com/docs/commerce/commerce-api/references/price-books?meta=Summary) 1.1.0
  - Added create, read, update, and delete (CRUD) for price books, price book entries, and site assignments. Search remains available. List endpoints return paginated results without a search query.
  - Price books created through this API are always type `standard`. For `feed_based` price books, metadata remains editable. Writes to price book entries are rejected.
  - Supports quantity-tier pricing through `priceTables` (absolute amount or percentage discount, each with a validity window). A PATCH replaces the `priceTables` array.
  - New endpoints:
    - `GET /organizations/{organizationId}/price-books`
    - `GET/PUT/PATCH/DELETE /organizations/{organizationId}/price-books/{priceBookId}`
    - `GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries`
    - `GET/PUT/PATCH/DELETE /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}`
    - `GET /organizations/{organizationId}/price-books/{priceBookId}/site-assignments`
    - `PUT/DELETE /organizations/{organizationId}/price-books/{priceBookId}/site-assignments/{siteId}` — `PUT` is idempotent: HTTP 201 when newly assigned, HTTP 200 when already assigned.
- [Promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions?meta=Summary) 1.2.0
  - `GET/PUT/PATCH /promotions/{id}/compatibility`
  - `GET/PUT/PATCH/DELETE /promotions/{id}/discount-rule`
- [Replications](https://developer.salesforce.com/docs/commerce/commerce-api/references/replications?meta=Summary) 1.0.8
  - Documentation update for timeouts and RFC 7807 error handling.
- [Shopper Baskets V2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) 2.13.4
  - `OrderPaymentInstrument` now includes shopper-safe, read-only `fraudDecisions` (`preAuthorization` only) and `paymentDetails` (`type`, `brand`, `last4`, `walletType`, `expirationMonth`, `expirationYear`, `token`, `tokenType`, and `accountHolderName`).
- [Shopper Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary) 1.10.0
  - Completes saved-payment setup after the provider succeeds (registered customer ShopperToken only). `paymentMethodReferenceSetupId` is the provider setup identifier (for example a Stripe SetupIntent ID).
  - `gatewayProperties` is no longer required on payment-method-reference setup.
  - `CustomerPaymentMethodReference` now returns read-only `accountHolderName` (SEPA), and `brand` / `expiryMonth` / `expiryYear` (cards).
  - Embedded Product includes `slug` and `primaryCategory`.
  - New endpoint:
    - `POST /customers/{customerId}/payment-method-references/actions/complete`
- [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) 1.22.4
  - Added the same `fraudDecisions` and `paymentDetails` enrichment as Shopper Baskets V2.
  - `OmsReturnProductItem.reasonText`: optional free-text note alongside the coded return reason.
- [Shopper Payments](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments?meta=Summary) 1.7.0
  - `POST /payment-instruments/balance` is provider-generic instead of gift-card-specific.
  - The request now requires `provider` and `providerProperties` instead of `giftCard`. Don't send PCI data (PAN). Use a client-side token or encrypted fields.
- [Shopper Products](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=Summary) 1.13.0
  - When the Enable Shopper SEO Slug (CFT) feature toggle is on, Shopper Products returns an SEO slug for the request locale, generated from the site’s storefront URL rules. `getCategory` and `getCategories` accept a category ID or `slug`, and the `category` and each `parentCategoryTree` entry include `slug`. A product includes `slug` only when `expand=slug` is requested, and its primary category includes `slug` when `expand=primary_category` is requested. The toggle is off by default, so existing requests continue to return categories by ID and omit `slug`. To enable the feature toggle, contact Customer Support.
- [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary) 1.15.0
  - Added `SuggestedProduct.slug` for SEO-friendly suggestion links. This is the slug segment, not a full URL.

## 09/23/2026

### SCAPI Release

- Configured SCAPI CDN caching ahead of an upcoming release to reduce response times for non-personalized Custom APIs.
- Bug fixes and internal improvements.
- Infrastructure change for API validation on Sandbox and Development instances only.

### SLAS Release

- SLAS Infrastructure Deployment:
  - During the deployment of required infrastructure updates, registered shopper logins and token refresh calls may have elevated response times and 5xx errors for less than one minute. Our internal simulations of production peak traffic resulted in less than 15 seconds of performance degradation, with no impact on existing sessions and guest shoppers.
  - The deployment is scheduled at these times (UTC):
    - AP2: September 23, 16:00
    - AP3: September 23, 17:00
    - EU-Central: September 23, 23:00
    - US-East: September 24, 03:00

## 09/22/2026

### SLAS Release

- Infrastructure updates.
- Fixed an intermittent bad signature verifier error on /userinfo that could occur during tenant signing key rotation. Tokens signed with the previous key are now accepted during the rotation window, and token handling has been strengthened to ensure signatures are fully verified.
- **Fixed Trusted-Agent guest flow authorization errors**: Resolved a 403 SSO Unauthorized error that could occur in the Trusted-Agent guest flow (/trusted-agent/callback → /token) when client-state pass-through was enabled. Guest sessions now complete successfully in this scenario.
- **Improved IDP error message clarity**: Updated IDP error messages returned as 412 responses to clearly distinguish between missing configuration fields and IDP HTTP errors. There is no behavioral change, and detailed error message exposure remains controlled by the existing configuration setting.
- **mTLS Enforcement**
  - To enhance the security of the SLAS authentication service, we’re enabling mutual TLS (mTLS) client-certificate enforcement at the SLAS gateway. Starting October 6, 2026, according to the new per-region schedule listed below, any request reaching the SLAS origin without a valid client certificate—including requests that bypass the SCAPI zone—will be rejected.
  - Who is affected:
    - No action required: for integrations using the standard, published Commerce Cloud SLAS endpoints through the SCAPI zone. This is the supported integration path and will continue to work without changes.
    - Action required: for integrations that connect directly to the SLAS origin and bypass the SCAPI zone—for example, by using hardcoded origin hostnames/IP addresses or a custom network path. These requests will be rejected once mTLS enforcement is enabled.
  - Schedule:
    - AP2: October 6, 2026
    - AP3: October 8, 2026
    - EU: October 12, 2026
    - US East: October 15, 2026

## 08/26/2026

### SCAPI Release

- Prepared standard cacheable endpoints for SCAPI CDN caching to reduce response times for Shopper API traffic.

### SLAS Release

- SLAS Admin Batch Logout: Admin users can now log out up to 50 shoppers in a single request, invalidating their sessions and refresh tokens. Existing single-shopper logout functionality remains unchanged. For details, see [Log Out Multiple Shoppers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-batch-logout.html).
- The SLAS Admin [Delete Shopper](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=deleteShopper) endpoint is now rate limited to 100 requests per minute per tenant by default. Requests exceeding the limit receive HTTP 429 responses and should be retried after backing off. For details, see [Delete Shopper Rate Limiting](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-best-practices.html#delete-shopper-rate-limiting).
- SLAS now forwards `c_*` custom headers to ECOM on the `/login` endpoint, enabling per-request context for third-party security and bot mitigation solutions. For details, see [Custom Header Forwarding](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-best-practices.html#custom-header-forwarding).
- The OAuth `state` parameter is now preserved end-to-end through the [Trusted Agent On Behalf](https://developer.salesforce.com/docs/commerce/sfra/guide/slas-trusted-agent.html) (TAOB) flow, enabling consistent state handling across the authentication flow. For details, see [Preserve OAuth State in Trusted Agent On Behalf Flows](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-best-practices.html#preserve-oauth-state-in-trusted-agent-on-behalf-flows).
- SLAS Admin idle-session timeout and Account Manager JWT acceptance window are now extended to 30 minutes, reducing unnecessary session expirations.
- **[Refresh Token Service Protection](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-best-practices.html#refresh-token-service-protection)**
  - To protect against refresh-token replay abuse, SLAS is limiting how frequently a single refresh token can be exchanged at `/oauth2/token`.
    - A refresh token can be exchanged up to 3 times within 60 seconds.
    - Additional attempts return HTTP 429 (Too Many Requests) with a `Retry-After` header.
    - Repeated use of revoked, expired, or unknown tokens may also result in HTTP 429 responses.
  - Action Required
    - Review your integration to avoid reusing or concurrently exchanging the same refresh token, and ensure your application properly handles HTTP 429 responses.
- **mTLS Enforcement**
  - To enhance the security of the SLAS authentication service, we’re enabling mutual TLS (mTLS) client-certificate enforcement at the SLAS gateway. Starting October 6, 2026, according to the new per-region schedule listed below, any request reaching the SLAS origin without a valid client certificate—including requests that bypass the SCAPI zone—will be rejected. This change was originally scheduled for September 1, and then September 23.
  - Who is affected:
    - No action required: for integrations using the standard, published Commerce Cloud SLAS endpoints through the SCAPI zone. This is the supported integration path and will continue to work without changes.
    - Action required: for integrations that connect directly to the SLAS origin and bypass the SCAPI zone—for example, by using hardcoded origin hostnames/IP addresses or a custom network path. These requests will be rejected once mTLS enforcement is enabled.
  - Schedule:
    - AP2: October 6, 2026
    - AP3: October 8, 2026
    - EU: October 12, 2026
    - US-East: October 15, 2026
- **Strict Client Auth Enforcement for Private Clients**
  - [Strict Client Auth](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-best-practices.html#strict-client-auth), previously optional for SLAS private clients, is scheduled to become mandatory on these dates:
    - Non-production: January 26, 2027
    - Production: February 24, 2027
  - Prior to these enforcement dates, make sure that your private clients use the following header on all `/login` and `/authorize` requests:
    - `x-slas-client-auth: Base64(client_id:client_secret)`
  - After enforcement, requests with a missing or invalid header will be rejected with 401 Unauthorized.

## 08/12/2026

### SCAPI Release

- For B2C Commerce version 26.8 or later, Custom API timeouts are now configurable. By default, Custom API requests use a gateway timeout of 60 seconds, up from the previous 10-second limit on Shopper Custom APIs. To change this default, use the [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary) to set a timeout up to a maximum of 120 seconds. For Shopper-facing Custom APIs, use a 10-second timeout to keep storefronts responsive. For details, see [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html).
- Prepared for infrastructure updates (Development and Sandbox instances only).

## 08/05/2026

### SLAS Release (US-East Region)

- Resolved an intermittent SLAS Admin UI login issue where some users encountered an HTTP 431 ("Request Header Fields Too Large").
- Improved profile linking for first-time LINE IDP sign-in: SLAS now matches an identifier returned by LINE against existing storefront profiles and links the sign-in to that profile, instead of creating a duplicate account for a shopper who already exists in your customer base. This change applies only to the first-time linking step. LINE token refresh behavior is unchanged, and linking for other identity providers (Apple, Azure, etc.) is unchanged.
- **SLAS JWT Updates**
  - The SLAS `id_token` includes a `ctg` claim.
  - The SLAS `access_token` includes a `CRM` claim.
- **Updated `aud` Claim Formatting**
  - We've updated the formatting of the OAuth token `aud` (audience) claim to use the Commerce Cloud tenant's globally unique identifier (GUID), when available, instead of the tenant ID.
  - As a best practice, applications should not validate or hardcode the specific value of the aud claim, as its format may change over time. Applications should rely on standard OAuth/OIDC token validation and use the `aud` claim only to verify that the token is intended for the receiving service, rather than matching a specific expected value.
  - **Action Required & Best Practices:** For most customers, no action is required. The addition of new JWT claims—and the reordering of existing ones—are considered non-breaking changes under our documented SLAS and SCAPI change policy. Future SLAS releases may introduce additional claims to both the `access_token` and `id_token`.
  - If your integration uses custom logic to parse the SLAS JWT, ensure your implementation follows these documented best practices:
    - Do not rely on claim ordering. As noted in SLAS documentation, integrations should not expect a fixed set or specific sequence of claims.
    - Handle new claims gracefully. Ensure your code does not throw errors when encountering new or previously undefined claims.

## 07/29/2026

### SCAPI Release

- Enable SCAPI Direct Routing grid wide. No customer impact is anticipated.

## 07/22/2026

### SLAS Release (EU, AP2, and AP3 Regions)

- Resolved an intermittent SLAS Admin UI login issue where some users encountered an HTTP 431 ("Request Header Fields Too Large").
- Improved profile linking for first-time LINE IDP sign-in: SLAS now matches an identifier returned by LINE against existing storefront profiles and links the sign-in to that profile, instead of creating a duplicate account for a shopper who already exists in your customer base. This change applies only to the first-time linking step. LINE token refresh behavior is unchanged, and linking for other identity providers (Apple, Azure, etc.) is unchanged.
- **SLAS JWT Updates**
  - The SLAS `id_token` includes a `ctg` claim.
  - The SLAS `access_token` includes a `CRM` claim.
  - Fixed a formatting issue with the existing `AUD` claim which uses the ECOM tenant Global Unique ID, when available, in place of the Tenant ID.
  - **Action Required & Best Practices:** For most customers, no action is required. The addition of new JWT claims—and the reordering of existing ones—are considered non-breaking changes under our documented SLAS and SCAPI [change policy](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html#change-policy). Future SLAS releases may introduce additional claims to both the `access_token` and `id_token`.
  - If your integration uses custom logic to parse the SLAS JWT, ensure your implementation follows these documented best practices:
    - Do not rely on claim ordering. As noted in [SLAS documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens), integrations should not expect a fixed set or specific sequence of claims.
    - Handle new claims gracefully. Ensure your code does not throw errors when encountering new or previously undefined claims.

## 07/21/2026

### SCAPI Release

- [Metrics](https://developer.salesforce.com/docs/commerce/commerce-api/references/metrics?meta=Summary) 1.0.1
  - Added closed beta details to API Overview.
- [Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=Summary) 1.5.2
  - Added `POST /orders/{orderNo}/oms-status-events`.
- [Shopper Baskets V2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) 2.11.1
  - Added extension hooks for promoting a temporary basket:
    - `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.beforePOST`
    - `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.afterPOST`
    - `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.modifyPOSTResponse`
  - Added the `expand=approaching_discounts` option on `getBasket`. This option returns the `approachingDiscounts` array (order- and shipping-level promotions) on the basket.
- [Shopper Delivery Estimates](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-delivery-estimates?meta=Summary) 1.1.0
  - Returns carrier-calculated delivery date ranges for a product at a destination postal code, enabling "Arrives by" messaging on product detail pages before checkout.
- [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) 1.17.1
  - Guest shoppers can regain access to an order with a time-limited access code sent to the order's email address. They can then view the order and self-service their cancellations or returns without creating an account. The access code works alongside the existing `OrderViewCode`.
  - Unlike `OrderViewCode`, which grants view-only access to order details, the access code also authorizes guest cancel and return actions for the complete self-service flow.
  - New endpoint:
    - `POST /orders/{orderNo}/actions/request-access-code`
      - Generates a 6-digit access code when the supplied email matches the order. The code is valid for 15 minutes and locks after 3 failed attempts, with a cooldown before a new code can be requested. Guest orders only.
      - Code delivery uses the `sfcc.app.order.sendOrderAccessCode` hook, so you control the email template and branding.
  - These Shopper Orders endpoints accept the access code as an alternative access grant for guest orders:
    - `POST /orders/{orderNo}/lookup` — also accepts `OrderViewCode` (view-only).
    - `POST /orders/{orderNo}/actions/oms-cancel-order` — requires the access code.
    - `POST /orders/{orderNo}/actions/oms-return-order` — requires the access code.
- [Shopper Promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-promotions?meta=Summary) 1.3.0
  - Added retrieval of multiple promotions by ID.
  - Added validation errors for unknown promotion IDs and invalid date ranges (start without end, end without start, end before start).
- [Sites](https://developer.salesforce.com/docs/commerce/commerce-api/references/sites?meta=Summary) 1.3.0
  - Added endpoints: `GET /sites/{siteId}/custom-cartridges` and `PUT /sites/{siteId}/custom-cartridges`.
- [Timeouts](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary) 1.0.6
  - Documentation update.
- New `personalized` query parameter:
  - Controls whether personalization applies to the response. Set to `none` to opt out of personalized response handling and enable caching at the CDN layer.
  - APIs that support this parameter:
    - [Shopper SEO](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=Summary) 1.2.0
    - [Shopper Stores](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-stores?meta=Summary) 1.3.0
    - [Shopper Availability](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-availability?meta=Summary) 1.3.0
    - [Shopper Configurations](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-configurations?meta=Summary) 1.3.0
    - [Shopper Experience](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary) 1.6.0
    - [Shopper Products](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=Summary) 1.11.1

## 07/14/2026

### SCAPI Release

- Provision dedicated short codes for on-demand sandboxes (ODS) to isolate API routing and resolve errors with the Shopper Login and API Access Service (SLAS). Previously, on-demand sandboxes shared a common short code (`kv7kzm78`). The shared short code continues to work. However, if you use SLAS hybrid authentication or encounter the error `Cannot construct SLAS session-bridge URL: no ACTIVE SCAPI short code found for this organization`, generate your dedicated short code to resolve the issue. For details, see [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#short-code) and [Generate a Short Code and Create an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_generate_a_shortcode_and_api_client_id.htm&type=5).
  - B2C Commerce is in the process of retrofitting existing on-demand sandboxes with dedicated short codes, but you can provision your own short code in the meantime.
  - See also: [Default Domain on On-Demand Sandboxes (ODS)](https://help.salesforce.com/s/articleView?id=cc.b2c_default_domain.htm&type=5).
- CORS preflight requests now contain an `Access-Control-Max-Age` header, set to 10 minutes. This prevents browsers from making unnecessary preflight requests. As a result, changes to a CORS configuration or endpoint can take up to 10 minutes to appear in preflight requests.
- Improved the resilience of the log distribution layer against automated bot attacks and extreme traffic anomalies. Previously, such incidents could exhaust your realm's Log Center quota, causing legitimate logs to become unavailable. With this update, excessive log events generated during such incidents are automatically detected and sampled down before reaching Log Center, preserving quota for meaningful log data.

## 07/07/2026

### SLAS Release

- Enhanced Passkey Management and Multi-Site Support
  - The [Get Passkey User API](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getPasskeyUserByLoginId) now includes passkey creation date, last-used timestamp, and usage count, making it easier to build enhanced passkey management experiences for shoppers.
  - Shoppers can now use a passkey registered on one storefront channel to authenticate to other channels within the same tenant, without needing to re-register their passkey.
- Enhanced Authentication Security with Verification Attempt Rate Limiting
  - Added per-shopper rate limiting for email one-time password (OTP) and passwordless authentication flows. After 6 invalid verification attempts within 10 minutes, further attempts are temporarily blocked to help protect shopper accounts from brute-force attacks.
- Corrected the `idp_access_token` returned by the `/token` endpoint for Hybrid Authentication flows to make sure that the expected identity provider access token is returned for new logins.

## 06/30/2026

### SCAPI Release

- [Metrics API](https://developer.salesforce.com/docs/commerce/commerce-api/references/metrics?meta=Summary)
  - For B2C Commerce version 26.7, this API is in closed beta and will be available on July 1, 2026.
  - Provides programmatic access to time-series operational metrics.
  - Exposes the same metrics available in the Log Center UI for ingestion by third-party monitoring tools such as Tableau and Grafana, and for observability workflows.
  - Metric category endpoints:
    - `GET /organizations/{organizationId}/metrics/overall`
      - Overall application performance metrics (platform requests, sessions, response time, emails sent, system workload).
    - `GET /organizations/{organizationId}/metrics/sales`
      - Sales and commerce metrics (orders, basket creations, and basket updates).
    - `GET /organizations/{organizationId}/metrics/ecdn`
      - eCDN performance and caching metrics (success/errors, cache hit percentage, requests, bandwidth, pageviews, and unique visitors).
    - `GET /organizations/{organizationId}/metrics/third-party`
      - Third-party service integration metrics (call counts, call duration p95, and remote exceptions).
      - Optional `thirdPartyServiceId` filter.
    - `GET /organizations/{organizationId}/metrics/scapi`
      - SCAPI request and performance metrics (request latency, response counts, and cache hit statistics).
      - Optional `apiFamily` and `apiName` filters.
    - `GET /organizations/{organizationId}/metrics/scapi-hooks`
      - SCAPI hooks execution metrics (hook execution times, hook errors).
    - `GET /organizations/{organizationId}/metrics/mrt`
      - Managed Runtime metrics (request counts, cache hit rates, error rates, Lambda invocations, and request times).
    - `GET /organizations/{organizationId}/metrics/controller`
      - Controller and pipeline metrics (total calls, average duration).
    - `GET /organizations/{organizationId}/metrics/ocapi`
      - OCAPI request and performance metrics (total calls, average duration, and total errors).
      - Optional `ocapiCategory` and `ocapiApi` filters.
  - Deployed internal routing bug fix on July 6, 2026.
- Shopper Baskets v2 2.9.0
  - These updates will be available on July 1, 2026.
  - `POST /checkout/shopper-baskets/v2/organizations/{organizationId}/baskets/{basketId}/actions/promote` promotes a temporary basket and clears its `isTemporary` flag.
  - To retrieve baskets with Salesforce Payments via PayPal, use `expand=payment_references`.
  - `PATCH /baskets/{bid}/payment-instruments/{pid}` now accepts `paymentReferenceRequest` in the request payload. This change is relevant only for Salesforce Payments.
- Stabilized and hardened internal APIs. No customer impact is anticipated.
- Prepared SCAPI to support services with a broader range of applicable tenant identifiers. No customer impact is anticipated.
- Prepared validation support in SCAPI admin use cases for merchant users, merchant agents, and custom Business Manager models. No customer impact is anticipated.

## 06/23/2026

### SCAPI Release

- [Custom Objects](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-objects?meta=Summary) 1.1.0
  - Added a search request example that demonstrates a `termQuery` on the `siteId` attribute to filter custom objects by site.
- [Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=Summary) and [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary)
  - When Salesforce Order Management (SOM) integration is enabled and the `expand=oms` parameter is requested, order detail and order lookup endpoints additionally return payment instrument data sourced from SOM.
  - Order Lookup: `GET /orders/{order_no}/lookup`
  - Shopper Orders: `GET /orders/{order_no}`
- [Shopper Auth](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=Summary) 1.50.0
  - The passwordless-token endpoint now documents Issuer Subject (`isb`) construction and its 256-character limit. Requests whose assembled `isb` exceeds 256 characters return `400 BAD_REQUEST` ("Issuer Subject length must be less than 256 characters"). For details, see [Shopper Login and API Access Service (SLAS) Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).
- [Shopper Experience](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary) 1.5.2
  - New endpoint:
    - `GET /experience/shopper-experience/v1/organizations/{organizationId}/components/{componentId}`
      - Retrieve a single Page Designer component by ID.
- [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) 1.15.0
  - New endpoints for order cancellation and returns:
    - `GET /orders/oms-meta-data`
      - Provides the cancel and return reason codes synchronized from Salesforce Order Management.
    - `POST /orders/{orderNo}/actions/oms-cancel-order`
      - Cancel an order.
    - `POST /orders/{orderNo}/actions/oms-return-order`
      - Specify items to return.
- [Shopper Products](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=Summary) 1.10.0
  - New endpoints:
    - `GET /product/shopper-products/v1/organizations/{organizationId}/products/{productId}/images`
      - Retrieve image data for a single product.
    - `GET /product/shopper-products/v1/organizations/{organizationId}/products/{productId}/prices`
      - Retrieve price details for a single product.
    - `GET /product/shopper-products/v1/organizations/{organizationId}/products/{productId}/promotions`
      - Retrieve active promotion details for a single product.
- [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary) 1.10.0
  - Page meta tags in search results now include a type field indicating how the storefront should render the tag: name, property, title, or jsonld. The field might not appear when the kind can't be determined.

## 06/17/2026

### SCAPI Release

- Completed Edge caching support preparation for SCAPI requests.
- SCAPI OAS specifications now allow parameter of type `header`.
- Enabled the first phase of SCAPI Direct Routing enablement for selected realms. No customer impact is anticipated.
- Fixed authentication failures for Custom APIs.

## 05/28/2026

### SCAPI Release

- [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) 1.14.1
  - Documentation update
- [Shopper Availability](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-availability?meta=Summary)
  - `GET /product/shopper-availability/v1/organizations/{organizationId}/availability`
    - Added `sfcc.shopper-standard` scope to the endpoint.

## 05/27/2026

### SLAS Release

- SLAS OAuth2 endpoints now reject requests that contain a trailing slash or malformed path delimiters, such as `;`, `\`, or their URL-encoded equivalents, in the endpoint URL. Affected endpoints include `/oauth2/token`, `/oauth2/authorize`, and `/oauth2/login` under both `/organization/` and `/organizations/` path prefixes.
  - What to check: Make sure that your integration constructs OAuth 2.0 request URLs using the canonical path format with no trailing slash and no matrix-style path parameters. Requests using non-standard URL formats receive an HTTP `404` response.
  - Correct format example: `POST /organization/{organizationId}/oauth2/token`
- When a shopper account is deleted through SLAS, all associated passkey data — including registered passkey records and passkey credentials — is now automatically removed.
  - What this means for your integration: No action is required. Account deletion flows that call the SLAS user deletion API will now result in complete cleanup of all passkey-related data for that shopper. If your integration performs account deletion followed by re-registration flows, then passkey data is fully cleared before any new registration.
- Security and infrastructure updates. No customer impact is anticipated.

## 05/22/2026

### SCAPI Release

- [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) 1.14.0
  - **important:** The endpoints in this section are available only on B2C Commerce instances that are integrated with Salesforce Order Management (OMS). On instances that are not integrated with OMS, calls to these endpoints return an error.
  - Added new endpoints that allow shoppers to cancel an order, request returns, and retrieve the reason codes used by both flows. All three endpoints require an authenticated shopper token.
    - `GET /orders/oms-meta-data`: Returns the cancellation and return reason codes that a storefront should present to the shopper, including the default selection for each list.
    - `POST /orders/{orderNo}/actions/oms-cancel-order`: Cancels an entire order. Partial cancellations are not supported.
    - `POST /orders/{orderNo}/actions/oms-return-order`: Requests a return for one or more product items on an order. Each requested item specifies an `itemId`, a quantity, and an optional reason.
  - Error responses for the new endpoints are served as `application/problem+json` (RFC 7807) and use typed schemas that describe the failure, for example, when a requested return quantity exceeds what is available, or when one of the supplied product item IDs is not part of the order.
  - The new endpoints support `before`, `after`, and `modifyResponse` hooks for the cancel and return operations, and a `modifyResponse` hook for the meta-data operation.

## 05/20/2026

### SCAPI Release

- New SCAPI APIs and endpoints:
  - [Shopper Availability](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-availability:Summary)
    - `GET /product/shopper-availability/v1/organizations/{organizationId}/availability`
      - Retrieve availability data for one or more products with improved caching performance.
      - This new API deprecates the `expand=availability` parameter on the [Shopper Products API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=Summary) `getProduct` and `getProducts` endpoints.
  - [Shopper Product Images](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=Summary)
    - `GET /product/shopper-products/v1/organizations/{organizationId}/products/{productId}/images`
      - Retrieve image data for a given product ID.
      - This new API adds a `viewTypeLimit` parameter and uses a dedicated images endpoint instead of the `expand=images` parameter on the [Shopper Products API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=Summary) `getProduct` endpoint.
  - [Preferences API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=preferences:Summary)
    - `GET`/`PATCH` `/global-preference-groups/{groupId}/{instanceType}`
      - Get and update global preference groups.
    - `GET`/`PATCH` `/site-preference-groups/{groupId}/{instanceType}`
      - Get and update site preference groups.
    - `POST` `/site-preference-groups/{groupId}/{instanceType}/preference-search`
      - Search preferences.
    - `GET` `/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId}`
      - Get and update preferences.
  - [Inventory Lists API](https://developer.salesforce.com/docs/commerce/commerce-api/references/inventory-lists?meta=Summary)
    - `GET`/`PUT`/`PATCH`/`DELETE` `/inventory-lists/{inventoryListId}`
      - CRUD operations for inventory lists.
  - [Experiences API](https://developer.salesforce.com/docs/commerce/commerce-api/references/experiences?meta=Summary)
    - `GET` `/slots/{slotId}/{contextType}`
      - Get a slot.
    - `POST` `/slot-search`
      - Search for slots.
    - `GET`/`PUT`/`PATCH`/`DELETE` `/slots/{slotId}/slot-configurations/{configurationId}`
      - CRUD operations for slots.
  - [Custom Objects API](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-objects?meta=Summary)
    - `GET`/`PUT`/`PATCH`/`DELETE` `/custom-objects/{objectType}/{key}`
      - Object type key operations.
    - `POST` `/custom-objects-search/{objectType}`
      - Search custom objects by object type.
    - `GET`/`PUT`/`PATCH`/`DELETE` `/sites/{siteId}/custom-objects/{objectType}/{key}`
      - Site-specific object type key operations.
  - [Stores API](https://developer.salesforce.com/docs/commerce/commerce-api/references/stores?meta=Summary)
    - `DELETE`/`PATCH`/`PUT` `/stores/{id}`
      - Additional CRUD operations for stores.
- [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary)
  - New query parameter `imgTypes` on `productSearch`:
    - Filters product images by type with optional per-type count limits, for example, `imgTypes=large:2,small:1`.
    - Requires `expand=images` and `allImages=true`.
  - `q` parameter: The `maxLength` increases from **50** to **500**. Lexical search queries remain limited to 50 characters.
  - `limit` parameter: Adds an explicit `minimum: 1` constraint in addition to the existing `maximum: 200` and the default of 25.
  - `allImages`: Updated the parameter description to clarify that it can be combined with `imgTypes` for filtered image responses.
  - The `OrganizationId` schema and `organizationId` path parameter now use a regex pattern (`^f_ecom_[a-z]{4}_(prd|stg|dev|s[0-9]{2}|[0-9]{3})$`) instead of `minLength`/`maxLength`, with a more descriptive description referencing realm and instance identifiers.
- Prepare for OCI migration to Hyperforce in AMER and EMEA. No customer impact is anticipated.

## 05/06/2026

### SCAPI Release

- Prepare for user authorization support in SCAPI Admin APIs via Business Manager. No customer impact is anticipated.
- Update SCAPI log center messages for customer relevance and readability.
- Prepare for OCI migration to Hyperforce in APAC. No customer impact is anticipated.

## 04/28/2026

### SLAS Release

- SLAS passwordless login (with email one-time password) now includes default support for [Domain-based Message Authentication, Reporting, and Conformance (DMARC)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#2-configure-a-domain-identity).
- Private clients now support [Strict Client Auth](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#strict-client-auth) for enhanced security and protection.
- [SCAPI authorization scopes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) now provide expanded options for finer-grained access control of Shopper and Admin APIs. Improve storefront security while simplifying integration with predefined permissions by using the [Standard Shopper Scope](https://developer.salesforce.com/docs/commerce/commerce-api/guide/standard-shopper-scope.html).
- Security and infrastructure updates
- **Upcoming SLAS JWT enhancements:** Starting April 28, 2026, the JSON Web Token (JWT) returned by SLAS includes several enhancements.
  - The JWT returned by SLAS includes the `ssc` claim to support short code functionality.
  - The SLAS `access_token` includes a `CRM` claim.
  - The SLAS `id_token` that’s returned in the token response includes these updates:
    - The user’s email and name are used in place of the `idp_origin`.
    - The `id_token` is signed with the same tenant key as the `access_token` so the `id_token` signature can be verified. Retrieve the public key by using the `/jwks` endpoint.
    - The header now includes a `typ` claim with a value of `JWT`.
    - An `isb` claim has been added.
    - The existing `AUD` claim uses the ECOM tenant Global Unique ID, when available, in place of the Tenant ID.
  - **Action Required & Best Practices:** For most customers, no action is required. The addition of new JWT claims—and the reordering of existing ones—are considered non-breaking changes under our documented SLAS and SCAPI [change policy](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html#change-policy). Future SLAS releases may introduce additional claims to both the `access_token` and `id_token`.
  - If your integration uses custom logic to parse the SLAS JWT, ensure your implementation follows these documented best practices:
    - Do not rely on claim ordering. As noted in [SLAS documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens), integrations should not expect a fixed set or specific sequence of claims.
    - Handle new claims gracefully. Ensure your code does not throw errors when encountering new or previously undefined claims.

## 04/21/2026

### SCAPI Release

New APIs and endpoints:

- [Jobs API](https://developer.salesforce.com/docs/commerce/commerce-api/references/jobs?meta=Summary)
  - POST `/jobs/{jobId}/executions`
    - Create a job execution.
    - GET `/jobs/{jobId}/executions/{id}`
      - Retrieve job execution details.
    - DELETE `/jobs/{jobId}/executions/{id}`
      - Delete a job execution.
    - POST `/job-execution-search`
      - Search job executions.
- [Roles API](https://developer.salesforce.com/docs/commerce/commerce-api/references/roles?meta=Summary)
  - GET `/roles`
    - Retrieve role information.
  - GET/PUT/DELETE `/roles/{roleId}`
    - Get, create, or delete a role by ID.
  - GET/PUT `/roles/{roleId}/permissions`
    - Get and create role permissions.
  - GET `/roles/{roleId}/users`
    - Retrieve users assigned to a specified role.
  - PUT/DELETE `/roles/{roleId}/users/{login}`
    - Assign and unassign users to roles.
  - POST `/roles/{roleId}/user-search`
    - Search user roles by login credentials.
- [Scripts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/scripts?meta=Summary)
  - GET `/code-versions`
    - List code versions.
  - PUT/GET `/code-versions/{codeVersionId}`
    - Create/Get code version details.
  - PATCH `/code-versions/{codeVersionId}`
    - Activate a code version.
  - DELETE `/code-versions/{codeVersionId}`
    - Delete a code version.
- [Shopper Agents](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-agents?meta=Summary)
  - POST `/organizations/{organizationId}/session/init`
    - Initialize an Agentforce shopper session.
- [Sites API](https://developer.salesforce.com/docs/commerce/commerce-api/references/sites?meta=Summary)
  - GET `/sites`
    - Retrieve details for all sites.
  - GET `/sites/{siteId}` - Retrieve site details by ID.
    - POST `/site-search`
      - Search sites.
- [Users API](https://developer.salesforce.com/docs/commerce/commerce-api/references/users?meta=Summary)
  - GET `/users`
    - Retrieve user information.
  - GET/PUT/PATCH/DELETE `/users/{login}`
    - Create, retrieve, update, delete (CRUD) users using login credentials.

Updated APIs and endpoints:

- [Replications API](https://developer.salesforce.com/docs/commerce/commerce-api/references/replications?meta=Summary)
  - Added support for Page Designer (PD) pages: PD pages replicate as content assets, including all their components.
- [Shopper Customers API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary)
  - Added support for saving and deleting payment method references for Salesforce Payments
    - Payment Method Reference Setup (POST `/organizations/{organizationId}/customers/{customerId}/payment-method-references/actions/setup`) — Shoppers can now save a payment method for future use.
    - Delete Payment Method Reference (DELETE `/organizations/{organizationId}/customers/{customerId}/payment-method-references/{paymentMethodReferenceId}`) Shoppers can now delete a saved payment method reference.
- [Shopper Experience API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary)
  - POST `/qualifiers/resolve`
    - Checks user qualification for customer groups, campaigns/promotions, and data binding contexts.

## 04/15/2026

### SLAS Release

- Security Updates. No customer impact is anticipated for these changes.

### SCAPI Release

- Security updates. No customer impact is anticipated for these changes.

## 04/08/2026

### SCAPI Release

- Enabled preference-based response timeout settings for all instances types. The [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary) provides self-service timeout configuration.

## 04/06/2026

### SCAPI Release

- With B2C Commerce v26.4, Business Manager displays an option for HTTP cookies for Hybrid Auth. Until further notice is provided, leave the **HTTPOnly True** setting at the default value (disabled). We will provide additional information when this setting can be enabled. For details, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-authentication.html#step-1-set-up-your-storefront-with-hybrid-auth).

## 03/26/2026

### SCAPI Release

- No customer impact is anticipated for these changes:
  - Security and infrastructure updates.
  - Preparation for new, upcoming SCAPI timeout handling in production environments.
  - Hook transaction handling.

## 03/24/2026

New SCAPI APIs:

- [Object Definitions](https://developer.salesforce.com/docs/commerce/commerce-api/references/object-definitions?meta=Summary):
  - System Object Types
    - `GET /system/object-types`
      - Get system object types.
    - `POST /system/object-types-search`
      - Search system object types.
    - `GET /system/object-types/{objectType}`
      - Get system object type.
  - Attribute Definitions
    - `POST /system/object-types/{objectType}/attribute-definition-search`
      - Search attribute definitions.
    - `GET /system/object-types/{objectType}/attribute-definitions`
      - Get attribute definitions.
    - `GET/PUT/PATCH/DELETE /system/object-types/{objectType}/attribute-definitions/{id}`
      - Create, Read, Update, and Delete (CRUD) attribute definition.
  - Attribute Groups
    - `POST /system/object-types/{objectType}/attribute-group-search`
      - Search attribute groups.
    - `GET /system/object-types/{objectType}/attribute-groups`
      - Get attribute groups
    - `GET/PUT/PATCH/DELETE /system/object-types/{objectType}/attribute-groups/{id}`
      - CRUD an attribute group.
  - Attribute Group Assignments
    - `PUT/DELETE /system/object-types/{objectType}/attribute-groups/{groupId}/attribute-definitions/{defId}`
      - Assign/unassign attribute definition to a group.
- New [Experiences API](https://developer.salesforce.com/docs/commerce/commerce-api/references/experiences?meta=Summary) endpoints:
  - Library Folders
    - `GET/PUT/PATCH/DELETE /libraries/{libraryId}/folders/{folderId}`
      - CRUD a content folder.
    - `GET /libraries/{libraryId}/folders/{folderId}/sub-folders`
      - Get sub-folders.
    - `GET /libraries/{libraryId}/folders/{folderId}/content`
      - Get content assets in a folder.
  - Library Content Assets
    - `GET/PUT/PATCH/DELETE /libraries/{libraryId}/content/{contentId}`
      - CRUD a content asset.
    - `GET /libraries/{libraryId}/content/{contentId}/folders`
      - Get folder information for a content asset.
  - Library Folder Assignments
    - `GET/PUT/PATCH/DELETE /libraries/{libraryId}/folder-assignments/{contentId}/{folderId}`
      - CRUD a folder assignment.
    - `DELETE /libraries/{libraryId}/folder-assignments/{contentId}/{folderId}`
      - Delete a folder assignment.
- [Inventory Impex (OCI)](https://developer.salesforce.com/docs/commerce/commerce-api/references/impex?meta=Summary) Updates:

  - Added the `fileFormat` field to the `submitEventsActivityExport` endpoint. Use this field to change the output format to CSV or JSON.

## 03/12/2026

### Explore SCAPI and Build Custom Endpoints with the B2C DX MCP Server (Developer Preview)

Use the B2C DX Model Context Protocol (MCP) to enhance your development workflow by connecting an AI assistant, such as Claude, Cursor, or GitHub Copilot, to your B2C Commerce environment. The new B2C DX MCP server is a unified MCP that is the starting point for various development tools and storefronts. The B2C DX MCP server provides your AI assistant with real-time access to B2C Commerce APIs (SCAPI), storefront development, cartridge deployment, and Managed Runtime (MRT) deployments. For example, you can use natural language prompts to list SCAPI schemas, create a custom SCAPI endpoint, and deploy a storefront to MRT, among other things, without leaving your IDE!

**important:** The [B2C DX MCP Server](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/) is available as a developer preview. The B2C DX MCP Server isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality in production with these commands or tools.

## 03/11/2026

SCAPI Release

- New [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary) :
  - Provides self-service timeout configuration with preference-based response timeout settings for Sandbox and Development instances types.
- Hybrid Auth flow:
  - Now returns the correct HTTP 401 response code in cases where the login failed. Previously a HTTP 500 was returned.
  - Now properly includes trusted-system authentication requests. Previously, this endpoint was not supported by Hybrid Auth.
- The ETag response header was removed, as it wasn't relevant to SCAPI.

## 03/03/2026

### SLAS Release (Originally Scheduled for 02/25/26)

- The passwordless login flow for customer registration now supports an optional customer number (`customer_no`) request parameter. See [Authorize the Passwordless Customer with Registration](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-registration.html#1-authorize-the-passwordless-customer-with-registration).
- Callbacks with no matching trusted agent record now return `400` (Bad Request) instead of `502` (Bad Gateway) for more accurate error reporting.
- Security and infrastructure updates.
- **Upcoming SLAS JWT Enhancements:** Starting March 10, 2026, the JSON Web Token (JWT) returned by SLAS will include several enhancements. We’re proactively sharing this update to give customers using custom JWT parsing logic ample time to review and update their integrations.
  - **New JWT Claims:**
    - `ssc`: Added to support short code functionality.
    - `CRM`: Added as a new standard claim.
  - **Updates to the `id_token` from the SLAS token response:**
    - User information: The user’s email and name will now be used in place of the `idp_origin`.
    - Signature verification: The `id_token` is now signed with the same tenant key as the `access_token`, allowing its signature to be verified. The public key can be retrieved using the `/jwks` [endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getJwksUri).
    - Header update: A `typ` claim with the value `JWT` has been added to the header.
    - New claim: An `isb` claim has been added.
  - **Action Required & Best Practices:** For most customers, no action is required. The addition of new JWT claims—and the reordering of existing ones—are considered non-breaking changes under our documented SLAS and SCAPI [change policy](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html#change-policy). Future SLAS releases can introduce additional claims to both the `access_token` and `id_token`.
  - If your integration uses custom logic to parse the SLAS JWT, ensure your implementation follows these documented best practices:
    - Do not rely on claim ordering. As noted in [SLAS documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens), integrations should not expect a fixed set or specific sequence of claims.
    - Handle new claims gracefully. Ensure your code does not throw errors when encountering new or previously undefined claims.

## 02/25/2026

### SCAPI Release

- New APIs:
  - [Stores](https://developer.salesforce.com/docs/commerce/commerce-api/references/stores?meta=Summary)
    - `GET /stores`
      - Retrieve a list of all stores in an organization.
    - `GET /stores/{id}`
      - Retrieve information for a specific store by ID.
    - `POST /store-search`
      - Search for stores.
  - [Store Redirect Mappings](https://developer.salesforce.com/docs/commerce/commerce-api/references/store-redirect-mappings?meta=Summary)
    - `GET /store-redirect-mappings`
      - Get all store redirect mappings.
    - `POST /store-redirect-mappings/actions/bulk`
      - Create or update store redirect mappings.
    - `POST /store-redirect-mappings/actions/bulk-delete`
      - Delete store redirect mappings (batch).
    - `GET /store-redirect-mappings/{sourceStoreId}`
      - Get a specific store redirect mapping.
- API updates - [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary) - Added a new `processedQuery` field to the `productSearch` endpoint. This field lists the `appliedProcessors` used on the search phrase. Currently, this only includes Attribute Aware Search for detecting price filters. If Attribute Aware Search is enabled and executes, the `processedQuery` field is added to the response.
- Updates for which no customer impact is anticipated:
  - Reliability enhancements for internal configuration handling
  - Security infrastructure updates

## 02/24/2026

### SCAPI Release

- Starting with B2C Commerce version 26.3:
  - For the [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) and [Shopper Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary) APIs, added Salesforce Order Management (OMS) support:
    - Added expand support to allow Salesforce Order Management (OMS) data to be returned if available. If the instance isn't integrated with OMS, the `expand=oms` command is disregarded. OMS data is preferred, but B2C Commerce data is returned if an order hasn't been sent to OMS.
    - OMS data for Product Items, including the `status` and `quantityAvailableToCancel` properties, is displayed for the product items in the order.
    - OMS data for Order, including the `status` and `shipments`.
    - Shopper Orders additionally supports `expand=oms,oms_shipments` to include detailed shipment data:
      - Status
      - Provider
      - Tracking Number
      - Tracking URL
      - Expected Delivery Date
      - Actual Delivery Date
      - Shipment Items
        - Product Item ID (reference to the product item)
        - Quantity (quantity shipped for the referenced product item)
- [Shopper Payments API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments?meta=Summary) 1.4.0:
  - Added Adyen payment method configuration support. If an Adyen account is onboarded to Salesforce Payments, the API now returns configuration settings for Adyen based on payment methods enabled in the merchant's payment zone site.
  - Added a new, optional amount query parameter. Some payment gateways, such as Adyen, qualify or disqualify payment methods based on the transaction amount.
- [Shopper Orders API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) 1.12.0 documentation update
- Resolved an issue where custom logic utilizing the `dw.order.calculateShipping` and `dw.order.calculateTax` hooks was unintentionally bypassed or ignored during site requests.
- Fixed an issue where the SCAPI CORS configuration on production instances was overwritten with the STG configuration with a replication of domain preference.

## 02/16/2026

### SLAS Release

- **Upcoming SLAS JWT Enhancements**: As part of an upcoming SLAS update, the JSON Web Token (JWT) returned by SLAS includes the `ssc` claim to support short code functionality.
  - Future SLAS releases can introduce additional claims in the JWT, including the `access_token` and `id_token`.
  - To provide customers with ample time to review and update their integrations if needed, the changes will be enabled starting March 10, 2026.
  - The addition of new JWT claims—and reordering of existing claims—are considered non-breaking changes under our documented SLAS and SCAPI [change policy](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html#change-policy). As noted in the [SLAS documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens), the JWT returned by SLAS can evolve over time, and integrations must not rely on a fixed set or order of claims. While no action is required for most customers, we're proactively sharing this update to help teams that implement custom JWT parsing logic prepare accordingly.
  - We recommend following the below best practices in your custom implementation as per our documentation. If your integration uses custom logic to parse the SLAS JWT:
    - Don't rely on claim ordering.
    - Ensure your implementation gracefully handles the presence of new or previously undefined claims without errors.

## 02/11/2026

### SCAPI Release

- [Schema API](https://developer.salesforce.com/docs/commerce/commerce-api/references/scapi-schemas?meta=Summary) bug fix. Correct API names consistent with the URL schema are now returned for these APIs:
  - `cdn-api-process-apis`: `zones`
  - `cors-preferences`: `cors`
  - `shopper-login`: `auth`
  - `slas-admin`: `auth-admin`
- Requests executed in verbose mode, for example, requests including the `sfdc_verbose` header, create `scapi-http` log entries in Log Center for all responses, while only error logs are available for non-verbose requests.

## 01/28/2026

### SCAPI Release

- New APIs and endpoints:
  - New [Inventory Lists API](https://developer.salesforce.com/docs/commerce/commerce-api/references/inventory-lists) that provides comprehensive management capabilities for product inventory records within inventory lists:
    - `GET inventory-lists/{inventoryListId}/product-inventory-records/{productId}`
      - Retrieve a product inventory record.
    - `PUT inventory-lists/{inventoryListId}/product-inventory-records/{productId}`
      - Create a product inventory record using the information provided.
    - `PATCH inventory-lists/{inventoryListId}/product-inventory-records/{productId}`
      - Update a product inventory record with the specified information.
    - `DELETE inventory-lists/{inventoryListId}/product-inventory-records/{productId}`
      - Delete a product inventory record by ID.
  - New [Experiences API](https://developer.salesforce.com/docs/commerce/commerce-api/references/experiences) for creating and updating Page Designer pages for headless and PWA storefront management outside of Business Manager:
    - `PUT /pages/{pageId}`
      - Create or update a Page Designer page.
    - `POST slot-configurations-search`
      - Search for slot configurations.
- Bug fix for [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/references/custom-apis?meta=Summary) timeouts for shopper use cases. Documented [timeouts](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html#shopper-and-admin-api-endpoints) have been re-enforced.
- Updates for which no customer impact is anticipated:
  - Reliability enhancements for internal configuration handling.
  - Cleaned up obsolete feature switches and infrastructure updates.
  - Prepared for an upcoming feature to support User Authorization for SCAPI Admin APIs.
  - Security updates.
  - Prepared for routing OCI to Hyperforce.
  - Geolocation information will be set to rest session.

## 01/27/2026

### SCAPI Release

- Starting with B2C Commerce version 26.2:
  - Enhanced SCAPI verbose logging in LogCenter when `sfdc_verbose` is enabled.
    - Logged information now includes request latency for Custom APIs along with existing details.
    - Added service runtimes with request latency for granular performance tracking.
  - Checkout API updates:
    - [Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=Summary) \- 1.4.13 documentation update
    - [Shopper Basket V1](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary) \- 1.9.2 documentation update
    - [Shopper Basket V2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) \- 2.3.3
      - Added the new query parameter `populateCustomerDetails` to the `createBasket` and `transferBasket` endpoints.
      - Added fields in the `/baskets/{}/paymentInstruments` POST request for SalesforcePayments.
      - Added fields in the Basket schema for Salesforce Payments ( Basket → PaymentInstrument).
    - [Shopper Payments](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments?meta=Summary) \- 1.2.1 documentation update
    - [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) \- 1.9.0
      - Added a fail order endpoint: `/orders/{}/actions/fail`
      - Added fields in the Order schema response for SalesforcePayments (Order → PaymentInstrument).
      - Added fields in the `/orders/{}/paymentInstruments` PATCH request for SalesforcePayments.
      - Added the `expand = oms` and `oms` fields.
- Starting with B2C Commerce version 26.1, Agent/OOBO is supported out of the box in Hybrid Auth with PWA Kit when using the Customer Service Center in Business Manager. See [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-authentication.html#hybrid-auth-feature-support-matrix).

## 01/21/2026 (Originally Scheduled for 01/14/2026)

### SLAS Release

- The JSON Web Token (JWT) returned by SLAS now includes an `ssc` claim for short code support.
  - The addition of new JWT claims—and reordering of existing claims—are considered non-breaking changes under our documented SLAS and SCAPI [change policy](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html#change-policy).
  - As noted in [SLAS documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens), the JWT returned by SLAS may evolve over time, and integrations shouldn't rely on a fixed set or order of claims. While no action is required for most customers, we're proactively sharing this update to help teams that implement custom JWT parsing logic prepare accordingly.
  - If your integration uses custom logic to parse the SLAS JWT:
    - Don't rely on claim ordering.
    - Ensure your implementation gracefully handles the presence of new or previously undefined claims without errors.
- Use SLAS to send a registered shopper a one-time password (OTP) through email. No third-party integration is required. Email OTP support in SLAS makes it easy for shoppers to register and log in without requiring password. For details, see [Passwordless Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html) or [Implement Passwordless Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/passwordless-login.html) in the _Composable Storefront Developer Guide_.
  - You can now configure OTP size to 6 or 8 digits (8 digit is default).
- Use SLAS to authenticate shoppers securely with passkeys. Passkeys are a next-generation login experience which significantly enhance protection against fraud and unauthorized access. Passkey-based authentication methods leverage WebAuthn standards with biometrics and hardware tokens. For details, see [Passwordless Login with Passkeys](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html).
- Starting with B2C Commerce version 26.1, Agent/OOBO is supported out of the box in Hybrid Auth with PWA Kit when using the Customer Service Center in Business Manager. See [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-authentication.html#hybrid-auth-feature-support-matrix).
- Updated authentication responses so that requests for locked or disabled customer accounts now return a 401 (Unauthorized) instead of a 502 error, providing clearer and more accurate error signaling.
- To enhance security and align with **OAuth 2.1 specifications,** the SLAS public client `refresh token` issued is required to be one time use only. For public clients, reuse of the same `refresh_token` is now prohibited. You must use the NEW refresh token that SLAS issues on each `/token` call following the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - [Here](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025) is the original notification from early May 2025. All Production (PRD) tenant_ids that reuse old refresh tokens will receive a 400 invalid refresh token error.
- The `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change enhances security by preventing unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).
  - [Here](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#03182025) is the original notification from March 2025.

## 01/14/2026

### SCAPI Release

- Process optimization to improve performance of non-cacheable APIs.

## 01/07/2026

### SLAS Relesae

- To enhance security and align with **OAuth 2.1 specifications,** the SLAS public client `refresh token` issued is required to be one time use only. For public clients, reuse of the same `refresh_token` is now prohibited. You must use the NEW refresh token that SLAS issues on each `/token` call following the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - [Here](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025) is the original notification from early May 2025. Starting Jan 8th 2026, all Production (PRD) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
- Security and infrastructure updates. No customer impact is anticipated.

## 12/4/2025

### SCAPI Release

With B2C Commerce version 26.1:

- Added Custom APIs to the [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary). This allows configuration of request timeouts for Custom API requests up to a maximum of 120 seconds.
- New SCAPI APIs and endpoints:
  - [Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/customers?meta=Summary)
    - `PUT customer-groups/{customerGroupId}/members`
      - Adds multiple customers to a customer group by their customer numbers in a single batch operation.
    - `DELETE customer-groups/{customerGroupId}/members`
      - Removes multiple customers from a customer group by their customer numbers in a single batch operation.
    - `GET /customer-groups`
      - Retrieves customer groups with support for pagination (offset/limit) and field selection via the select parameter.
  - [Price Books](https://developer.salesforce.com/docs/commerce/commerce-api/references/price-books?meta=Summary)
    - `POST /price-book-search`
      - Searches for price books using query-based criteria, enabling discovery and filtering of price book configurations.
  - [Products](https://developer.salesforce.com/docs/commerce/commerce-api/references/products?meta=Summary)
    - `POST /unassigned-product-search`
      - Searches for products that aren't assigned to any catalog.
  - [SCAPI Schemas](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-schema-api.html)
    - `GET /schemas`
      - Retrieves a list of available SCAPI OAS schemas.
    - `GET /schemas/{apiFamily}/{apiName}/{apiVersion}`
      - Retrieves the OAS schema identified by API family, name, and version.
  - [Shopper Experience](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary)
    - `GET /contents/{id}`
      - Retrieves a single content asset by ID with optional locale parameter for localized content.
    - `GET /contents`
      - Retrieves multiple content assets by their IDs in a single batch request, supporting locale-based content retrieval.
    - `GET /folders/{id}`
      - Retrieves a content folder by ID with support for hierarchical navigation via the `levels` parameter and optional locale.
    - `GET /folders`
      - Retrieves multiple content folders by their IDs in batch, with support for hierarchical levels and localization.
    - `GET content-search`
      - Searches content assets using query parameters with support for sorting, pagination (offset/limit), refinements, and locale-specific results.
  - [Shopper Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary)
    - `GET /product-lists/{listId}/items`
      - Retrieves all items in a product list, for example: wish list and gift registry, with support for expansion parameters to include product details, availability, images, and prices.
  - [Shopper Payments](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments?meta=Summary)
  - [Shopper Products](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products)
    - New expansion `shipping_methods` for `/products` and `/products/{id}`. Adds shipping method information to product responses, allowing clients to retrieve available shipping options for products.
    - New expansion `set_products` and `bundled_products` for `/products`. Enables retrieval of product set members and bundled product details within product responses.
  - [Sites](https://developer.salesforce.com/docs/commerce/commerce-api/references/sites?meta=Summary)
    - `POST /site-search`
      - Searches for sites using a query-based search with configurable search criteria in the request body.

## 11/5/2025

### SCAPI Release

- Updated non-customer-facing infrastructure to support a future move of the OCI service to Hyperforce. No customer impact is anticipated.

## 10/29/2025

### SCAPI Release

- Updated non-customer-facing infrastructure to support a future move of the OCI service to Hyperforce. No customer impact is anticipated.
- Improved Hybrid login support for the `SameSite` cookie parameter:
  - Consistently verifies that the `SameSite` attribute for the `dwsid` cookie returned during token calls for Hybrid Auth matches the `SameSite` attribute for `dwsid` cookies set in Controller calls.

## 10/22/2025

### SCAPI Release

- SCAPI Direct Routing, [originally enabled on 10/01/2025](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#10012025), has been disabled grid-wide. No customer impact is anticipated.

## 10/21/2025

### SCAPI Release

- With B2C Commerce version 25.10, you can use the [Replications API](https://developer.salesforce.com/docs/commerce/commerce-api/references/replications?meta=Summary) to publish a product, price table, and content asset. Publishing an item is only available from STG to PRD and isn't testable on sandboxes. You will be able to use this API when B2C Commerce version 25.10 is rolled out on PIG instances.

### SLAS Release

- Strengthened SLAS Resilience and Scale for holiday season preparation.
- To enhance security and align with **OAuth 2.1 specifications,** the issued SLAS public client refresh token is required to be one-time use only, and reuse of the same `refresh_token` is now prohibited. You must make sure to use the NEW refresh token that SLAS issues on each `/token` call using the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).

  - [The original notification was provided in early May](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give additional time for customers to make changes to their implementation, we extended the due date:
    - Starting Sep 9th 2025, all Production (PRD) `tenant_ids` that reuse old refresh tokens receive a 400 invalid refresh token error.

## 10/01/2025

### SCAPI Release

- Internal logging improvements as part of holiday season preparation.
- Added preference-based response timeout settings for Sandbox instances types:
  - A new [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary) provides customer self-service timeout configuration.
    **note:** This is only available for B2C Commerce Sandbox instances, but will be rolled out to all instance types in the future.
    **note:** Custom APIs are currently not supported.
- Grid-wide enablement of SCAPI Direct Routing. No customer impact is anticipated.
- Improved internal SCAPI configuration update resiliency. No customer impact is anticipated.

### SLAS Release

- Strengthened SLAS Resilience and Scale for holiday season preparation.
- Enhanced validation for passwordless login to ensure the provided login ID matches the one used for time-based one-time password (TOTP).
- Fixed an issue where a request to `/idp/callback` without an `idpName` returned a 500 error. It now correctly returns a 404.
- To enhance security and align with **OAuth 2.1 specifications,** the issued SLAS public client refresh token is required to be one-time use only, and reuse of the same `refresh_token` is now prohibited. You must make sure to use the NEW refresh token that SLAS issues on each `/token` call using the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - [The original notification was provided in early May](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025): - To give additional time for customers to make changes to their implementation, we are extending the due date: - Starting Sep 9th 2025, all Production (PRD) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
- Added support for OpenID Connect (OIDC) private key JWT authentication. For details, see [Configure Client Authentication with Private Key JWT](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-key-jwt.html).

## 09/25/2025

### SCAPI Release

- The SCAPI geolocation service does not support Anycast-related IP addresses. Anycast allows the same IP in multiple locations, and, therefore, can't resolve to one single location. For geolocation details, see [Shopper Geolocation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-geolocation.html) and [Geolocation Lookup for IP Addresses in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_geolocation_lookup_for_ip_addresses.htm&type=5).

## 09/24/2025

### SCAPI Release

- Updated non-customer facing infrastructure to support a future move of the OCI service to Hyperforce. No customer impact is anticipated.

## 09/22/2025

### SCAPI Release

With B2C Commerce version 25.10:

- The [CORS configuration API](https://developer.salesforce.com/docs/commerce/commerce-api/references/cors?meta=Summary) now supports the configuration of allowed origins with schemes other than HTTP and HTTPS.
- New Shopper Configuration API:
  - A read-only API that returns merchant-configured instance and site-specific property details including, but not limited to, site ID, name, status, locales , currencies, timezone, and certain enabled features, such as Salesforce Payments.
  - Each configuration value contains a configuration type detailing if it's global- or site-specific.
  - As B2C Commerce evolves, additional instance- and site-specific configuration details will be added to this API.
- Updated [Shopper Customers API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary):
  - Added an optional parameter for making a default customer payment instrument during creation.
  - Now returns the default flag when retrieving payment instruments using the `get /customer` and `get/customer/payment-instrument/{id}` endpoints.
- For the [Shopper Search API `productSearch` endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch), updated the `select` parameter documentation, including the example.
- Added a new, read-only Custom API status report endpoint that provides:
  - Registration status of your Custom APIs. When you activate a code version containing Custom APIs, this endpoint generates a report that contains comprehensive details about each endpoint's registration outcome, including status, configuration details, and error diagnostics when registration fails.
  - Real-time endpoint monitoring: Get immediate feedback on whether your Custom API endpoints successfully registered as `ACTIVE` or failed with `NOT_REGISTERED` status, eliminating the need to manually search through logs for troubleshooting.
  - Comprehensive endpoint details: Each endpoint response includes complete metadata, such as API name and version, cartridge name, HTTP method, implementation script, OpenAPI schema file, site ID, security scheme, and detailed error information for failed registrations.
  - Flexible filtering capabilities: Query all endpoints or filter by registration status to focus on problematic endpoints, with support for organization-level visibility across all sites and cartridges in your B2C Commerce instance.
- Introduced the new `dw.order.mergeBasket hook` to standardize and simplify basket merging customization. We recommend this method for merging. You can invoke this hook using the `transferBasket` endpoint with the new`merge=true` parameter. This ensures that the same merge script can be used consistently across all relevant functionalities, unifying the previous discrepancies between controller and REST API merging strategies.
- Added a download link for each SCAPI OAS specification on the respective API summary page.

### SLAS Release

- Use OpenID Connect (OIDC) private key JWT authentication. See [Configure Client Authentication with Private Key JWT](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-key-jwt.html).
<!-- You can now simultaneously maintain two active secrets, a primary and a secondary, and rotate them without service interruption. See [Client Secret Management and Rotation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#client-secret-management-and-rotation). -->

## 09/17/2025

### SCAPI Release

- Added a download capability for SCAPI OAS specifications in the summary section of every API.
- Added the new `dw.order.mergeBasket` hook to standardize and simplify basket merging customization. You can invoke this hook using the `transferBasket` endpoint with the new merge=true parameter. This ensures that the same merge script can be used consistently across all relevant functionalities, unifying the previous discrepancies between controller and REST API merging strategies. We recommend this method for merging, because other merging methods are now deprecated.
  - `https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v2/organizations/{organizationId}/baskets/actions/transfer`
- With the Custom API endpoint, you can now list your custom APIs on an instance via a user-friendly and secure approach and obtain real-time feedback on endpoint registration status, including successful registrations and failed attempts with error codes.
  - `https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints`
- Added the Granular Replication API for publishing a product, price table, and content asset. Publishing an item is only available from STG to PRD and is not testable on sandboxes. This will be available for use when 25.10 is rolled out on PIG instances.
  - `https://{shortCode}.api.commercecloud.salesforce.com/operation/replications/v1/organizations/{organizationId}/granular-processes`
- Updated non-customer-facing infrastructure to support a future move of the OCI service to Hyperforce. No customer impact is anticipated.
- Updated internal routing configuration to easier onboard pilot customers. No customer impact is anticipated.

## 09/16/2025

### SLAS Release

- Strengthening SLAS resilience and scale for holiday readiness
- To enhance security and align with OAuth 2.1 specifications, reuse of the same `refresh_token` for public clients is now prohibited. Implement one-time usage for the `refresh_token`, using the new `refresh_token` issued by SLAS on each `/token` call. For details, see [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - This requirement was originally published in the [05/06/2025 release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give SLAS customers additional time to make the necessary changes, we are extending the enforcement timeline as follows:
    - Starting September 9th, 2025, all Production (PRD) `tenant_id`s that reuse old refresh tokens receive a 400 invalid refresh token error.

## 09/08/2025

### SLAS Release

- SLAS security & infrastructure updates
- SLAS resilience improvements for holiday readiness
- To enhance security and align with OAuth 2.1 specifications, reuse of the same `refresh_token` for public clients is now prohibited. Implement one-time usage for the `refresh_token`, using the new `refresh_token` issued by SLAS on each `/token` call. For details, see [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - This requirement was originally published in the [05/06/2025 release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give SLAS customers additional time to make the necessary changes, we are extending the enforcement timeline as follows:
    - Starting September 9th, 2025, all Production (PRD) `tenant_id`s that reuse old refresh tokens receive a 400 invalid refresh token error.

## 09/03/2025

### SLAS Release

- SLAS resilience improvements
- Improved Apple IDP login with external profile fallback and default name generation for uninterrupted sign-in
- To enhance security and align with OAuth 2.1 specifications, reuse of the same `refresh_token` for public clients is now prohibited. Implement one-time usage for the `refresh_token`, using the new `refresh_token` issued by SLAS on each `/token` call. For details, see [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - This requirement was originally published in the [05/06/2025 release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give SLAS customers additional time to make the necessary changes, we are extending the enforcement timeline as follows:
    - Starting September 9th, 2025, all Production (PRD) `tenant_id`s that reuse old refresh tokens receive a 400 invalid refresh token error.

## 08/27/2025

### SCAPI Release

- Preparation for new, upcoming SCAPI routing functionalities. No customer impact is anticipated.

## 08/26/2025

### SLAS Release

- Security & compliance updates
- Enhanced support for the Sectigo certificate
- To enhance security and align with OAuth 2.1 specifications, reuse of the same `refresh_token` for public clients is now prohibited. Implement one-time usage for the `refresh_token`, using the new `refresh_token` issued by SLAS on each `/token` call. For details, see [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).

  - This requirement was originally published in the [05/06/2025 release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give SLAS customers additional time to make the necessary changes, we are extending the enforcement timeline as follows:
    - Starting September 9th, 2025, all Production (PRD) `tenant_id`s that reuse old refresh tokens receive a 400 invalid refresh token error.

## 08/19/2025

### SCAPI Release

- For [Shopper Baskets v1](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary), [Shopper Baskets v2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary), [Shopper Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary), and [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary), a new, optional field `qualifyingProductItemId` has been added to the `ProductItem` schema to help you reference the specific product that qualified the bonus promotion.
- Enhanced the Shopper Search API to support custom attribute retrieval for product search and search suggestions:
  - [Product Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch): Use the new query parameter `includedCustomVariationProperties` to specify up to 5 custom properties to return with product search results.
  - [Get Search Suggestions](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=getSearchSuggestions): Use the new query parameters `expand` and `includedCustomProductProperties` to specify up to 5 custom properties to return with product suggestions.
- Added support for Einstein suggestions in the Shopper Search [getSearchSuggestions](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=getSearchSuggestions) endpoint.
- The refine parameter on the Shopper Search [productSearch](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch) endpoint now supports refining by multiple promotions. For example: refine=pmid=20-off-clothes|15-off-shoes.
- Fixed an issue with the `request.getGeoLocation()` Script API when the `geoLocation` couldn’t be created during a REST session (OCAPI and SCAPI).

## 08/13/2025

### SCAPI Release

- Cleaned up non-customer-facing, obsolete SCAPI code and configuration. No customer impact is anticipated.

### SLAS Release

- SLAS resilience improvements
- Security library updates
- Enhanced support for the Sectigo CA certificate.
- Fixed an issue where the SLAS `/logout` and `/session-bridge/token` endpoints failed for customers with names containing specific international characters.
- To enhance security and align with OAuth 2.1 specifications, reuse of the same `refresh_token` for public clients is now prohibited. Implement one-time usage for the `refresh_token`, using the new `refresh_token` issued by SLAS on each `/token` call. For details, see [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - This requirement was originally published in the [05/06/2025 release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give SLAS customers additional time to make the necessary changes, we are extending the enforcement timeline as follows:
    - Starting August 13th, 2025, Sandbox, Staging (STG) and Development (DEV) `tenant_id`s that reuse old refresh tokens receive a 400 invalid refresh token error.
    - Starting September 9th, 2025, all Production (PRD) `tenant_id`s that reuse old refresh tokens receive a 400 invalid refresh token error.
    - This is the final extension. Please make the changes as soon as possible.

## 07/30/2025

### SCAPI Release

- Fixed an issue on production systems when hybrid customers using the `plugin_slas` and `shopper-experience` APIs experienced invalid redirects. The `plugin_slas` `onSession` hook was unintentionally triggered when the `shopper-experience` API was called.
- Enabled system quotas based on the SCAPI `ActivityType` as performance guardrails on production systems. Violation of system quotas can lead to quota exceptions.
- Fixed an issue on production systems when the requested locale-based customer group membership was not applied during on-request calls, which led to incorrect personalized SCAPI response caches.
- Enabled corrected behavior with the Script API `Request.getHttpRemoteAddress()` to get the true client IP from `shopper-context` on DEV and SBX environments. PROD and STG shopper context-based true client IPs are still disabled and will be enabled in a later release.

## 07/16/2025

### SCAPI Release

- Enabled on all instances, including Production (PRD): API path and parameter validation based on the OAS standard.

### SLAS Release

- Improved login experience by addressing a case sensitivity issue with shopper credentials.
- SLAS scale and performance improvements.
- To enhance security and align with OAuth 2.1 specifications, reuse of the same `refresh_token` for public clients is now prohibited. Implement one-time usage for the `refresh_token`, using the new `refresh_token` issued by SLAS on each `/token` call. For details, see [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - This requirement was orignially published in the [05/06/2025 release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give SLAS customers additional time to make the necessary changes, we are extending the enforcement timeline as follows:
    - Beginning July 14th, 2025, Sandbox, Staging (STG) and Development (DEV) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - Beginning August 4th 2025, all Production (PRD) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - This is the final extension. Please make the changes as soon as possible.

## 07/09/2025 (Originally scheduled for 06/24/2025)

### SLAS Release

- [Hybrid Auth](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-authentication.html): Support added for SLAS public clients and SFRA Storefront Protection.
- To enhance security and align with OAuth 2.1 specifications, reuse of the same `refresh_token` for public clients is now prohibited. Implement one-time usage for the `refresh_token`, using the new `refresh_token` issued by SLAS on each `/token` call. For details, see [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens).
  - This requirement was orignially published in the [05/06/2025 release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#05062025). To give SLAS customers additional time to make the necessary changes, we are extending the enforcement timeline as follows:
    - Beginning July 14th, 2025, Sandbox, Staging (STG) and Development (DEV) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - Beginning August 4th 2025, all Production (PRD) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - This is the final extension. Please make the changes as soon as possible.

## 07/02/2025

### SCAPI Release

- You can now more conveniently grant client applications access to multiple sandboxes. This speeds up the provisioning of development environments.
- Enabled on Sandbox, Staging (STG) and Development (DEV): API contract validation based on the OAS standard.

## 06/27/2025

### SCAPI Release

- Enabled on Sandbox and Development instances: ActivityTypeEnablement for quotas. No customer impact is anticipated.

## 06/26/2025

### SCAPI Release

- Enabled on ODS instances only: Custom OnRequest and OnSession hooks are no longer executed for the SCAPI `/shopper-experience` APIs. Make sure you validate your SCAPI `/shopper-experience` API calls.

## 06/25/2025

### SCAPI Release

- Enabled on Sandbox instances only: API contract validation based on OAS standard.

## 06/19/2025

### SCAPI Release

- On selected sandboxes, enabled OAS-based SCAPI request validation for parameters, authN / authZ, and request path.
- Updated non-customer-facing infrastructure to support a future move of the OCI service to Hyperforce. No customer impact is anticipated.
- Cleaned up non-customer-facing, deprecated SCAPI code and configuration. No customer impact is anticipated.

## 06/12/2025

### SCAPI Release

- Converted SCAPI RAML specifications to OpenAPI Specification (OAS) format. With this specification format change, a future developer experience feature will offer several key benefits:

  - Improved tooling support: Widespread OAS tooling aids in generating client libraries, API validation, and interactive documentation.
  - Better integration: OAS is the industry standard, ensuring seamless integration with existing systems and tools.
  - Streamlined development: OAS features help developers design, test, and document APIs more efficiently, leading to faster development cycles and higher quality APIs.

## 06/11/2025

### SLAS Release

- For AP2 and AP3 regions:
  - For public clients, reuse of the same `refresh_token` is now prohibited. You must rotate the refresh token following the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens). Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the Commerce Cloud repositories. For customers using the plugin-slas cartridge, upgrade to [Plugin SLAS v7.4.1](https://github.com/SalesforceCommerceCloud/plugin_slas/releases/tag/v7.4.1). To give SLAS customers time to make the necessary changes, we are strictly enforcing this restriction according to the following schedule:
    - Beginning May 20th, 2025, Sandbox, Staging (STG), and Development (DEV) tenant_ids that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - Beginning June 24th 2025, all Production (PRD) tenant_ids that reuse old refresh tokens will receive a 400 invalid refresh token error.
- Scale and performance improvements

## 06/09/2025

### SLAS Release

- For US and EU regions:
  - For public clients, reuse of the same `refresh_token` is now prohibited. You must rotate the refresh token following the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens). Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the Commerce Cloud repositories. For customers using the plugin-slas cartridge, upgrade to [Plugin SLAS v7.4.1](https://github.com/SalesforceCommerceCloud/plugin_slas/releases/tag/v7.4.1). To give SLAS customers time to make the necessary changes, we are strictly enforcing this restriction according to the following schedule:
    - Beginning May 20th, 2025, Sandbox, Staging (STG), and Development (DEV) tenant_ids that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - Beginning June 24th 2025, all Production (PRD) tenant_ids that reuse old refresh tokens will receive a 400 invalid refresh token error.
- Scale and performance improvements

## 06/04/2025

### SCAPI Release

- Non customer-facing infrastructure updates to better support more granular SCAPI log message forwarding to Log Center. No customer impact is anticipated.
- Non customer-facing “log-only“ validation update for future OAS spec updates. No customer impact is anticipated.

### SLAS Release

- AP2 and AP3 Regions:
  - Scale and performance improvements.
  - Minor infrastructure updates.
  - For public clients, reuse of the same `refresh_token` is now prohibited. You must rotate the refresh token following the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens). Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the Commerce Cloud repositories. For customers using the plugin-slas cartridge, upgrade to [Plugin SLAS v7.4.1](https://github.com/SalesforceCommerceCloud/plugin_slas/releases/tag/v7.4.1). To give SLAS customers time to make the necessary changes, we are strictly enforcing this restriction according to the following schedule:
    - Beginning May 20th, 2025, Sandbox, Staging (STG), and Development (DEV) tenant_ids that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - Beginning June 24th 2025, all Production (PRD) tenant_ids that reuse old refresh tokens will receive a 400 invalid refresh token error.

## 06/02/2025

### SLAS Release

- EU and US-East Regions:
  - SLAS now supports LINE as 3rd party IDP.
  - SLAS scale and performance improvements.
  - SLAS minor infrastructure updates.
  - SLAS [/password/action](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=resetPassword) endpoint now returns `locale` in the response.
  - Improved SLAS log integration with the Log Center.
  - Fixed an issue in the SLAS Admin client configuration (UI and API) to allow selection of the `sfcc.orders` scope.
  - Fixed a bug related to SLAS token management with the Do Not Track (DNT) setting.
  - For public clients, reuse of the same `refresh_token` is now prohibited. You must rotate the refresh token following the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens). To give SLAS customers time to make the necessary changes, we are strictly enforcing this restriction according to the following schedule:
    - For customers using the plugin-slas cartridge, upgrade to [Plugin SLAS v7.4.1](https://github.com/SalesforceCommerceCloud/plugin_slas/releases/tag/v7.4.1).
    - Beginning May 20th, 2025, Sandbox, Staging (STG), and Development (DEV) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
    - Beginning June 24th 2025, all Production (PRD) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.

## 05/21/2025

### SCAPI Release

- Completed rollout of stricter realm short code validation for SCAPI requests. Make sure you validate your used short codes in Business Manager: **Administration > Site Development > Salesforce Commerce API Settings**.
- Fully removed the deprecated `x-correlation-id` response header from all instance types. The header is replaced by the `sfdc_correlation_id` response header.
- Non customer-facing infrastructure updates for SCAPI Metrics in Log Center. No customer impact is anticipated.
- Added read-only mode system monitoring for internal SCAPI request validation to support upcoming OAS API definitions. No changes are made as a result of the request validation.
- Updated the summary documentation for multiple APIs to ensure consistency and enhance clarity.

## 05/20/2025

### OCAPI Release

- With B2C Commerce version 25.6:
  - Enhanced the [Get customers list Data API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-customer-lists?meta=Get%2Bcustomer%2Blist) to allow developers to retrieve customer configuration preferences. Developers can use this API to retrieve information that was previously only part of the header data in [Customer Lists export](https://help.salesforce.com/s/articleView?id=cc.b2c_customer_list_object_import_export.htm&type=5).

## 05/13/2025

### SLAS Release

- Rollout for AP3, EU, and US regions begins 05/13/2025 through 05/15/2025.

## 05/06/2025

### SLAS Release

- Completed SLAS scale and performance improvements. No customer impact anticipated.
- SLAS /password/action endpoint now returns `locale` in the response.
- Made improvements in the SLAS Logs integration with the Log Center.
- Fixed an issue in the SLAS Admin client configuration (UI and API) to allow selection of the `sfcc.orders` scope.
- Fixed a bug related to SLAS token management with the Do Not Track (DNT) setting.
- For public clients, reuse of the same `refresh_token` is now prohibited. You must rotate the refresh token following the process outlined in [Access Tokens and Refresh Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens). To give SLAS customers time to make the necessary changes, we are strictly enforcing this restriction according to the following schedule:
  - For customers using the plugin-slas cartridge, upgrade to [Plugin SLAS v7.4.1](https://github.com/SalesforceCommerceCloud/plugin_slas/releases/tag/v7.4.1).
  - Beginning 05/20/2025, Sandbox, Staging (STG) and Development (DEV) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.
  - Beginning 06/24/2025, all Production (PRD) `tenant_ids` that reuse old refresh tokens will receive a 400 invalid refresh token error.

## 04/23/2025

### SCAPI Release

- SCAPI support for the custom [Client IP Header](https://developer.salesforce.com/docs/commerce/commerce-api/guide/client-ip-forwarding.html) and [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-auth.html?q=hybrid#hybrid-auth-overview) is now enabled on all instances.
- Performance improvements in API validation. No customer impact is anticipated.
- Bug fixed for `OPTIONS` requests that previously failed with and HTTP 500 error response.

## 04/16/2025

### SCAPI Release

SCAPI support for the custom [Client IP Header](https://developer.salesforce.com/docs/commerce/commerce-api/guide/client-ip-forwarding.html) and [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-auth.html?q=hybrid#hybrid-auth-overview) is now enabled on Sandbox and Development instances. Enablement on Staging and Production instances is being planned.

## 04/09/2025

### SCAPI Release

- Stricter realm validation for SCAPI requests:
  - For additional security, SCAPI request realm IDs are now verified for correct short code assignment. If the realm ID does not match the short code, an HTTP error status code 404 is returned. You can use Business Manager to find the assigned short code for a realm.
  - As of 04/09/2025, stricter realm validation is enabled on all instance types, including Staging and Production. Make sure you validate your used short codes in Business Manager: **Administration > Site Development > Salesforce Commerce API Settings**.
- Media type validation of SCAPI requests is enabled on all instance types.
- SCAPI support for the custom Client IP Header and Hybrid Authentication is now enabled on Sandbox instances. Enablement on Development, Staging, and Production instances is being planned.

## 04/08/2025

### SLAS Release

- Performed required database updates. No customer impact is anticipated.
- The Hybrid Authentication (Hybrid Auth) feature becomes available on customer environments according to the following deployment schedule. Hybrid Auth must be enabled by Salesforce on a given environment and configured in Business Manager for your site to receive the `dwsid` cookie from SLAS `getAccessToken` endpoint responses.

  - ODS: 04/09/2025
  - Development instances: 04/16/2025
  - All remaining instances, including Production: 04/23/2025

## 04/03/2025

### SCAPI Release

- You can now view HTTP log entries with status codes 5xx in the Log Center, and filter them with the service type `scapi`.

## 03/27/2025

### SCAPI Release

- Stricter realm validation for SCAPI requests:
  - For additional security, SCAPI request realm IDs are now verified for correct short code assignment. If the realm ID does not match the short code, an HTTP error status code 404 is returned. You can use Business Manager to find the assigned short code for a realm.
  - As of 03/27/2025, stricter realm validation is only enabled for Sandboxes and Development instances. Make sure you validate your used short codes on your Sandbox and Development instances in Business Manager: **Administration > Site Development > Salesforce Commerce API Settings**.
  - Rollout to Staging and Production instances is being planned.
- Media type validation of SCAPI requests is enabled for Sandbox and Development instances. Rollout to Staging and Production instances is planned as the next enablement step.

## 03/25/2025

### SLAS Release

- SLAS Infrastructure Deployment:
  - During the deployment of required database updates, shoppers might experience elevated response times for less than one minute. Our internal simulations of production peak traffic resulted in several seconds of performance degradation.

## 03/20/2025

### SCAPI Release

- B2C Commerce version 25.3:
  - Fixed a bug for `ProductListID`, which was missing in the Shopper Customers API [`getPublicProductListsBySearchTerm`](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=getPublicProductListsBySearchTerm) endpoint.
- B2C Commerce version 25.4:
  - The SCAPI Shopper Products GET [`/product/shopper-products/v1/organizations/{organizationId}/products/{id}?expand=promotions`](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProducts) endpoint and the OCAPI GET [`/products/{id}/promotions`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-products?meta=Get%2Bproduct%2Bpromotions) endpoint now return promotions with the same sort criteria as the Script API default:
    - Exclusivity: `GLOBAL` exclusive promotions are considered first, followed by `CLASS` exclusive promotions, and `NO` exclusive promotions are considered last.
    - Rank: Sorted ascending
    - Promotion Class: `PRODUCT` promotions are considered first, followed by `ORDER` promotions, and `SHIPPING` promotions are considered last.
    - Discount type: Fixed price promotions are considered first, followed by free, amount-off, and percentage-off. Bonus product promotions are considered last.
    - Best discount: Sorted in descending order. For example, 30% off is considered before 20% off.
    - ID: Alphanumeric ascending.
- B2C Commerce version 25.5:
  - Fixed a bug with SCAPI `sfdc_verbose` mode. With this fix, no exception occurs if a SCAPI hook script doesn’t return a status code.
- Stricter realm validation for SCAPI requests:
  - For additional security, SCAPI request realm IDs are now verified for correct short code assignment. If the realm ID doesn't match the short code, an HTTP error status code 404 is returned. You can use Business Manager to find the assigned short code for a realm.
  - As of 03/19/2025, stricter realm validation is currently in preview and is only enabled for Sandboxes. Make sure you validate your used short codes on your Sandbox instances in Business Manager: **Administration > Site Development > Salesforce Commerce API Settings**.
  - Rollout to Development, Staging, and Production instances is being planned.
- Custom APIs are now aligned with SCAPI Admin API endpoints with the following constraints:
  - The default timeout limit has been increased from 10 seconds to 60 seconds.
  - The maximum request body size has been increased from 5 MB to 20 MB.
  - Business Manager quota limits apply.
  - A SCAPI Admin API request is defined by the absence of the `siteId` query parameter. These requests must use `AmOAuth2` as the security scheme.
- System monitoring is performed in read-only mode for media type validation of SCAPI requests, but media type validation is not enforced.

## 03/18/2025

### SLAS Release

- Improved the SLAS Admin UI design and user experience.
- The SLAS Admin UI now displays the login page after 15 minutes of user inactivity.
- SLAS 404 and 5xx error logs are now available in the Log Center.
- The `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change enhances security by preventing unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id parameter` in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).
  - The original schedule was 09/01/2024 for all sandbox tenants and 10/01/2024 for all other non-production tenants. We implemented this change for all non-production tenants starting February 10th, 2025. We have started enforcing the change for all production tenants effective 3/25/25.

## 03/11/2025

### SCAPI Release

- With B2C Commerce version 25.3, hybrid authentication (Hybrid Auth) replaces Plugin SLAS. Hybrid Auth improves the performance and stability of hybrid storefronts by moving the feature directly into the B2C Commerce platform. For details, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-auth.html).

## 03/05/2025

### SLAS Release

- The `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change enhances security by preventing unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).
  - The original schedule was 09/01/2024 for all sandbox tenants and 10/01/2024 for all other non-production tenants. We implemented this change for all non-production tenants starting 02/10/2025. We are going to strictly enforce the change for all production tenants starting 03/25/20.

## 02/19/2025

### SCAPI Release

- Runtime version update for internal SCAPI supporting applications. No customer impact is anticipated.

## 02/18/2025

### SLAS Release

- Fixed a bug related to the [Trusted System On Behalf (TSOB)](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedSystemAccessToken) endpoint returning an incorrect Customer ID when different client IDs are used.
- SLAS `[/authorize](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer)` endpoint now supports custom query parameters for 3rd party IDP consumption. For details, see [SLAS Identity Providers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html).
- The `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change enhances security by preventing unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id parameter` in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).
  - The original schedule was 09/01/2024 for all sandbox tenants and 10/01/2024 for all other non-production tenants. We implemented this change for all non-production tenants starting 02/10/2025.
- In preparation for the removal of the Account Manager SLAS_ORGANIZATION_ADMIN (Account Manager API Client) and SLAS_TRUSTED_AGENT_READ_ONLY & SLAS_TRUSTED_AGENT_READ_WRITE (Account Manager User) roles, these roles were removed from the SLAS code base. Because these roles were never made available for SLAS production use, no customer impact is anticipated.

## 02/05/2025

### SCAPI Release

- API request path validation now identifies empty path segments and handles them consistently across various components.
- Support added for CORS headers with ports.
- Update to the 01/07/2025 correlation ID header announcement: The new `sfdc_correlation_id` response header for the SCAPI Correlation ID is now fully enabled for SCAPI on all instances:
  - On sandbox and development instances, the deprecated `x-correlation-id` response header is no longer returned.
  - On staging and production instances, the deprecated `x-correlation-id` response header is still available, but is subject to removal in a future release.
- Security updates. No customer impact is anticipated.

## 02/03/2025

### SCAPI Release

- With B2C Commerce version 25.2:
  - The [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary) and [Shopper Products](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=Summary) APIs now support Page Meta Tag Rules. You can create Page Meta Tags in Business Manager (Merchant Tools > SEO > Page Meta Tag Rules) using a rule-based approach to enhance storefront pages with unique meta tag content and increase the SEO value across Product List Pages (PLPs) and Product Detail Pages (PDPs). A new optional `page_meta_tags` expansion, which controls the inclusion of page meta tags rules, has been added to `/product-search` and `/products`.

### OCAPI Release

- With B2C Commerce version 25.2:
  - Fixed an issue with the [createScapiRemoteInclude()](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_RemoteInclude.html) script functionality when used in combination with a Shopper API. As an example, this led to a 500 exception during the use of the Shopper Baskets API.

### SLAS Release

- [SLAS 4xx Logs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#view-slas-error-logs-in-log-center) are now available in Log Center. Log information includes the `correlationID`, which you can use for end-to-end request tracking.
- SLAS now supports custom query parameters for the [/login](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer) endpoint.
- SLAS now supports merging claims for [Azure IDP](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#supported-identity-providers).
- The SLAS [PasswordReset](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html#slas-password-reset-flow) flow no longer requires PKCE. You can now make password reset requests using the new, optional `hint` query parameter instead of a Proof Key for Code Exchange (PKCE) `code_challenge` and `code_verifier`. For details, see [Password Reset](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html).
- Fixed a `/userinfo` endpoint bug related to using a Google IDP.
- Fixed a bug related to password reset support across different devices.
- Improved error handling and validation to return more meaningful error messages for [Auth0 IDP](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#supported-identity-providers).
- The `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change enhances security by preventing unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).
  - The original schedule was 09/01/2024 for all sandbox tenants and 10/01/2024 for all other non-production tenants. We will now implement this change for all non-production tenants starting 02/10/2025.
- As of 02/10/25, we are now strictly enforcing the [documented rate limit](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#slas-rate-limits) of 25 requests per minute (RPM) for the [/jwks endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getJwksUri).
- In preparation for the removal of the SLAS_ORGANIZATION_ADMIN (Account Manager API-Client) and SLAS_TRUSTED_AGENT_READ_ONLY (Account Manager User) Account Manager roles, these roles were removed from the SLAS code base. Because these roles were never made available for SLAS production use, no customer impact is anticipated.
- Additional performance improvements included.

## 01/22/2025

### SCAPI Release

- API request path validation now identifies invalid path segments.
- Support added for CORS headers with ports.
- Update to the 01/07/2025 correlation ID header announcement: The `sfdc_correlation_id` response header for the SCAPI Correlation ID is now fully enabled for SCAPI on all instances:
  - On sandbox and development instances, the deprecated `x-correlation-id` RESPONSE header is no longer returned.
  - On staging and production instances, the deprecated `x-correlation-id` RESPONSE header is still available, but is subject to removal in a future release.
- Security updates. No customer impact is anticipated.

## 01/20/2025

### SCAPI Release

- Security updates. No customer impact is anticipated.

## 01/07/2025

### SCAPI Release

- With B2C Commerce version 25.1:
  - SCAPI/OCAPI Coupons API update:
    - Retrieved coupons are now sorted by `couponId` if no (optional) sorting order was passed. Previously, the sort order of retrieved coupons wasn't deterministic.
    - Retrieved coupons in the existing Coupons APIs:
      - OCAPI: https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-coupons?meta=Get%2BCoupons and
      - SCAPI: https://developer.salesforce.com/docs/commerce/commerce-api/references/coupons?meta=couponsSearch
  - Remote Includes: You can now add multiple remote includes from different sources in the array and create complex and powerful responses. For details, see [Remote Includes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/remote-includes.html).
  - The `x-correlation-id` response header is deprecated for some instances and is replaced by the `correlation-id` `RESPONSE` header:
    - For B2C Commerce SBX and DEV instance requests, the removal of the deprecated `x-correlation-id` `RESPONSE` header is included in this release.
    - for B2C Commerce STG and PRD instance requests, the removal of the deprecated `x-correlation-id` `RESPONSE` header is not included in this release.
    - For details, see [Investigate by Correlation ID](/docs/commerce/commerce-api/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id).

### SLAS Release

- As of July 31 2024, to enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id parameter` in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

## 2024

### 10/23/2024

#### SCAPI Release

- Server-Side Web-Tier Caching is now enabled for a select few realms in which it was previously disabled. For the list of cached APIs and other details, see [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).
- Upgraded security infrastructure. No customer impact anticipated.

#### SLAS Release

- SLAS 4xx error logs are available in Log Center, which provides multiple benefits, including a single URL for all realms, up to 14 days of log data, and improved search capabilities. For details, see Shopper Login and API Access Service(SLAS) Overview.
- Resolved a bug in the `/login` process when registered shoppers change their email and/or login ID multiple times. In this case, SLAS no longer triggers a 500 error.
- SLAS Service Protection: As part of our bot mitigation strategy for the upcoming holiday season, we are introducing additional service protection:
  - A SLAS service protection mechanism to restrict bad actors or BOTs calling the same SLAS endpoint repeatedly using the same Unique Shopper ID (USID)) within a short span of time. This returns a 409 HTTP response.
- To enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

### 10/16/2024

#### SCAPI Release

- Server-Side Web-Tier Caching is now enabled for a select few realms in which it was previously disabled. For the list of cached APIs and other details, see [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).

#### SLAS Release

- With B2C Commerce version 24.10, the SLAS 4xx error logs are available in Log Center, which provides multiple benefits, including a single URL for all realms, up to 14 days of log data, and improved search capabilities. For details, see [View SLAS Error Logs in Log Center](https://developer.salesforce.com/docs/commerce/commerce-api/guides/slas.md#view-slas-error-logs-in-log-center).
- By default, shopper tracking preferences are disabled for [Trusted Agent on Behalf (TAOB)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html) authorization, which means the Do Not Track `dnt` parameter is set to `true`. This differs from other SLAS token requests, for which the default `dnt` value is `false`.
- SLAS Service Protection: As part of our bot mitigation strategy for the upcoming holiday season, we are introducing additional service protection:
  - A SLAS service protection mechanism to restrict bad actors or BOTs calling the same SLAS endpoint repeatedly using the same Unique Shopper ID (USID)) within a short span of time. This returns a 409 HTTP response.
- To enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

### 10/08/2024

#### SCAPI Release

- Server-Side Web-Tier Caching is now enabled for a select few realms in which it was previously disabled. For the list of cached APIs and other details, see [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).

#### SLAS Release

- [Trusted Agent on Behalf (TAOB) authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html) now allows an agent to perform actions on behalf of guest shoppers.
- Refined documentation, including best practices and sample code for [validating SLAS JWTs with JWKS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-validate-jwt-with-jwks.html), to simplify key management and enhance security.
- SLAS Service Protection: As part of our bot mitigation strategy for the upcoming holiday season, we are introducing additional service protection:
  - A SLAS service protection mechanism to restrict bad actors or BOTs calling the same SLAS endpoint repeatedly using the same Unique Shopper ID (USID)) within a short span of time. This returns a 409 HTTP response.
  - SLAS Trusted System on Behalf (TSOB) logins will have the SAME service protection window of 3 seconds across all regions.
    - Beginning 10/02/2024 in the AP-Northeast-1 region and 10/09/2024 in the US-East-1 region, customers attempting to log in more than once through TSOB during a period of 3 seconds will receive a 409 HTTP error. No customer impact is anticipated. If you see an increase in 409 HTTP errors, open a support case.
    - No change for the SLAS AP-Southeast-2 and EU-Central-1 regions, which utilize the existing protection window of 3 seconds.
- To enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

### 10/02/2024

#### SLAS Release

- Enhanced error handling for the `/passwordless/login` endpoint. The endpoint now returns a 404 error instead of a 502 error when no shopper is found.
- SLAS Service Protection: As part of our bot mitigation strategy for the upcoming holiday season, we are introducing additional service protection:
  - A SLAS service protection mechanism to restrict bad actors or BOTs calling the same SLAS endpoint repeatedly using the same Unique Shopper ID (USID)) within a short span of time. This returns a 409 HTTP response.
  - SLAS Trusted System on Behalf (TSOB) logins will have the SAME service protection window of 3 seconds across all regions.
    - Beginning 10/02/2024 in the AP-Northeast-1 region and 10/09/2024 in the US-East-1 region, customers attempting to log in more than once through TSOB during a period of 3 seconds will receive a 409 HTTP error. No customer impact is anticipated. If you see an increase in 409 HTTP errors, open a support case.
    - No change for the SLAS AP-Southeast-2 and EU-Central-1 regions, which utilize the existing protection window of 3 seconds.
- To enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

#### SLAS Fixes

- Fixed a SLAS Admin UI bug to ensure the `UserInfo` URL value is not auto-populated with token information.

### 10/01/2024

#### SCAPI Release

- With B2C Commerce version 24.10, added performance and stability improvements in SCAPI caching, specifically for price/promotion calculations. No customer impact is anticipated.
- Stability and visibility enhancements. No customer impact is anticipated.

### 09/24/2024

#### SLAS Release

- SLAS Service Protection: As part of our bot mitigation strategy for the upcoming holiday season, we are introducing additional service protection:
  - A SLAS service protection mechanism to restrict bad actors or BOTs calling the same SLAS endpoint repeatedly using the same USID (Unique Shopper ID) within a short span of time. This returns a 409 HTTP response.
  - SLAS Trusted System on Behalf (TSOB) logins will have a service protection window of 3 seconds.
    - Beginning 10/02/2024 in the AP-Northeast-1 region and 10/09/2024 in the US-East-1 region, customers attempting to log in more than once through TSOB during a period of 3 seconds will receive a 409 HTTP error. No customer impact is anticipated. If you see an increase in 409 HTTP errors, open a support case.
    - No change is planned for the SLAS AP-Southeast-2 and EU-Central-1 regions, which are configured for 3 seconds.
- To help you verify the authenticity of callback requests, SLAS provides a `SlasCallbackToken` (JWT) for each passwordless login and password reset callback that SLAS sends. For more details, see [Verify the SLAS Password Action Callback](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.md#verify-the-slas-password-action-callback).
- To enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

#### SLAS Fixes

- Fixed a JWT validation issue when special characters, especially colons(:) were used in the first name or last name.

### 09/04/2024

#### SLAS Release

- Updated SLAS Infrastructure for holiday readiness.
- To enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id parameter` in the client credential call in guest flows using the schedule in [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

#### SCAPI Fixes

- CORS: Header `Access-Control-Allow-Methods` are no longer returned in SCAPI responses, but are returned for `OPTIONS` requests per HTTP specifications. No customer impact anticipated.
- Security: Added the `strict-transport-security` header with a one year expiration. No customer impact anticipated.

### 08/27/2024

#### SCAPI Release

With B2C Commerce version 24.9.1, added a read-only, optional `hashedLogin` field in the response as applicable for the following [Shopper Customers API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary) endpoints:

- `PATCH /customers/{customerId} (updateCustomer)`
- `GET /customers/{customerId} (getCustomer)`
- `POST /customers (registerCustomer)`

#### SLAS Release

- Updated SLAS third-party library information for holiday readiness.
- Addressed a limitation in the SLAS refresh token flow. If a public client logs in and then a private client logs in with the same USID, the public client refresh_token is now deleted and replaced.
- Fixed a SLAS bug in the registered user third-party IDP login flow. When a guest USID is used and the login process does not complete, the access token now remains as a guest token until a successful registered user 3rd party IDP login occurs.
- Improved Error Handling:
  - Refactored the idp/callback 503 error when the state is null to no longer return a 503 error. A 400 bad request error is now returned.
- Updated the SLAS Admin UI to allow customers to access the UI through their short-code.
- Fixed a rare and intermittent spike in SLAS response times.

### 08/22/2024

#### SCAPI Release

- For SCAPI calls using a SLAS JWT, added the `Disable the Modification of the Issuer Date` toggle to invalidate a [customer JWT](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/%3Chttps://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=Get%2Bor%2Brefresh%2Bcustomer%2BJWT%2B(JSON%2BWeb%2BToken)>) after a password change. When the toggle is set, a 401 `InvalidAccessTokenException` response code is returned when trying to use an existing request token after a password change. When the toggle is not set, the error response is only thrown if the time between the token issuer date and the password modification date exceeds 30 seconds.

### 08/21/2024

#### SCAPI Release

- Added infrastructure enhancements for new installation configurations. No customer impact anticipated.
- In preparation for the holiday season, enabled cache infrastructure enhancements.
- Upgraded security infrastructure. No customer impact anticipated.

### 08/14/2024

#### SCAPI Release

- Added response timeout handling for all instance types:
  - In preparation for the holiday season, documented timeouts are enforced on all instance types, including Production instances. Shopper APIs and Custom APIs must respond within 10 seconds, and Admin API requests must respond within 60 seconds. If a response to a SCAPI request exceeds the specified threshold, an HTTP 504 status code is returned. For details, see [Error Response Codes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html#504-gateway-timeout).
  - See the [Added response timeout handling for Sandbox instances](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#03112024) release note for more details.
- With B2C Commerce 24.8, you can set cache expiration for objects with a Validity Period for the Shopper Products [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProduct) and [getCategory](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getCategory) endpoints and the Campaigns [getCampaign](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns?meta=getCampaign) endpoint. For details, see [Cache Expiration for Objects with a Validity Period](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#cache-expiration-for-objects-with-a-validity-period).

#### SCAPI Fixes

- HTTP2 protocol issues fixed when using CORS.

### 08/07/2024

#### SCAPI Release

- With B2C Commerce version 24.8:
  - Added support for Cross-Origin Resource Sharing (CORS). For details, see [CORS in SCAPI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-cors.html) and the [CORS API](https://developer.salesforce.com/docs/commerce/commerce-api/references/cors?meta=Summary).
  - For the Shopper Products [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProduct) and [getCategory](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getCategory) endpoints and the Campaigns [getCampaign](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns?meta=getCampaign) endpoint, you can now set a time window, called the Validity Period. The validity period is used for server-side cache expiration to prevent serving stale content. For additional details, see “Cache Expiration for Objects with a Validity Period” in [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).

### 07/31/2024

#### SLAS Release

- To enhance security for the Shopper Login API Access Service (SLAS), a `channel_id` (site) parameter is now required when requesting a guest access token with a `grant_type` of `client_credentials`. This change prevents unauthorized access across different storefronts. Existing customers must update their implementation to include the `channel_id` parameter in the client credential call in guest flows by 7/31/2024. For details, see [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).
- The total number of scopes is now limited to 85 entries, which is enforced in both the SLAS API and SLAS Admin UI.
- Added client credentials to the POST body when refreshing an `access_token` from IDP. You can control this using a flag in the SLAS-IDP configuration. For details, refer to the documentation for the SLAS Admin [IdentityProvider](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=type%3AIdentityProvider) endpoint.

### 07/15/2024

#### SCAPI Release

With B2C Commerce version 24.7.2:

- [Preferences API](https://developer.salesforce.com/docs/commerce/commerce-api/references/preferences?meta=Summary)
  - Returns the value of the most recent custom preference ID version if the preference ID definition is changed.

#### SLAS Release

- SLAS infrastructure updated in preparation for the holiday season.

### 07/10/2024

#### SCAPI Release

- Server-Side Web-Tier Caching is automatically turned on for:
  - SBX and ODS instances
  - PRD instances that don't use use hooks in [Shopper Search API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary) `productSearch` and `getSearchSuggestions` endpoints. For details, see: [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).
- Internal infrastructure upgrades. No customer impact is anticipated.

### 06/26/2024

#### SCAPI Release

- Server-Side Web-Tier Caching is automatically turned on for all instances that don't use [Shopper Search API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary) `productSearch` and `getSearchSuggestions` endpoints on their PRD instances. For details, see [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).

### 06/20/2024

#### SCAPI Release

With B2C Commerce version 24.7:

- [Collect Request Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-logs-request-tracking.md#collect-detailed-request-information) for SCAPI requests by using the HTTP request header `sfdc_verbose: true`.
- Merchants and developers can update the status of redeemed coupons using the new [Coupons API](https://developer.salesforce.com/docs/commerce/commerce-api/references/coupons?meta=Summary) `redeemCoupon` endpoint.
- Use the [SEO API](https://developer.salesforce.com/docs/commerce/commerce-api/references/seo?meta=Summary) to upload a custom sitemap and trigger the sitemap generation process. You can now combine your external routes with those in B2C Commerce in a single sitemap.
- [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary)
  - Now provides geolocation capabilities. For details, see [Shopper Geolocation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-geolocation.html).
- Checkout APIs
  - For Shopper Baskets [v1](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary) and [v2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) `createBasket` and `updateBasket` endpoints, the product line item quantity limit is now set to the API quota [`api.basket.productLineItemQuantity`](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/quota/html/API_Quotas.html#category_Basket) of 1000, and the API no longer returns a 400 Bad Request for values greater than 999.
  - In addition, the 999 product line item quantity limit on [createOrders](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=createOrders) is removed, and the quantity set by this endpoint is now unlimited.

With B2C Commerce version 24.7.1:

- [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary)
  - Now requires a `siteId` to be passed. For details, see the [Shopper Context Guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html#constraints).
  - Constraints have been relaxed, and all SCAPI and OCAPI endpoints are now fully compatible with Shopper Context. For details, see [Shopper Context Constraints](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html#constraints).
- The [Shopper Customers API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary) `updateCustomer` endpoint allows `loginId` to be updated if a valid current password is provided for the shopper.
- [Preferences API](https://developer.salesforce.com/docs/commerce/commerce-api/references/preferences?meta=Summary)
  - When retrieving site and global preferences, the Preferences API first checks for custom settings, and if no custom settings exist, now instead returns the default settings in Business Manager.

### 06/18/2024

#### SLAS Release

- SLAS Admin: Added validation for SLAS Client callback URLs to prevent the use of localhost or loopback addresses as host names in production environments.
- Added SLAS resilience improvements for holiday readiness.

### 06/12/2024

#### SCAPI Release

- Server-Side Web-Tier Caching is enabled for all SCAPI customers who aren’t currently using the cached APIs and haven’t made production requests to any cached APIs in the last seven days. For the list of cached APIs and other details, see [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).

### 06/11/2024

#### SCAPI Release

- The `siteId` query parameter is no longer mandatory for custom API calls. If a site is not provided, the default site is the Business Manager site. For details, see [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html).
- With B2C Commerce version 24.5, the Shopper endpoint constraint for supporting trusted agent tokens on a specific subset of Shopper endpoints has been removed. For details, see [Trusted Agent Authorization.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html#constraints)
- Internal infrastructure change: additional internal header introduced. No customer impact is anticipated.

### 06/04/2024

#### SCAPI Release

- The Shopper Context API now requires a `siteId` for new customers. For details, see the [Shopper Context Guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html#constraints).
- The following Script API methods are available to support SCAPI external taxation APIs with hooks:
  - [dw.order.LineItemCtnr#isExternallyTaxed](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_order_LineItemCtnr.html#dw_order_LineItemCtnr_isExternallyTaxed_DetailAnchor): Returns true if the basket was created with taxMode = external.
  - [dw.order.TaxMgr#applyExternalTax](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_order_TaxMgr.html#dw_order_TaxMgr_applyExternalTax_Basket_DetailAnchor): Applies externally set tax rates to the given basket. Use when `dw.order.LineItemCtnr#isExternallyTaxed` returns true.
    For details, see [Extensibility via Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#taxes-apis-and-hooks) and [updateItemsinBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=updateItemsInBasket).

#### SCAPI Fixes

- With B2C Commerce version 24.6, the [mergeBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=mergeBasket) endpoint now merges the guest shopper’s `shippingAddress` and `shippingMethod` into the registered basket when the registered basket does not contain `shippingAddress` or `shippingMethod`.

### 05/29/2024

#### SCAPI Release

- The new [Preferences API](https://developer.salesforce.com/docs/commerce/commerce-api/references/preferences?meta=Summary) allows you to retrieve Site and Global preferences.
- The Shopper Products API [getCategories](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getCategories) endpoint now provides the `onlineSubCategoriesCount` property.
- Internal infrastructure upgrade and security updates. No customer impact is anticipated.

#### SLAS Release

- SLAS now allows shoppers to have multiple clients and authenticate on the same device with a single USID, provided the clients use their respective `refresh_tokens` to refresh their sessions.
- SLAS IDP integration has enhanced error handling to return more meaningful error messages to the caller. No change in error code information.
- The refined error message: “The Account is disabled” is returned for any user account disabled in B2C Commerce. No change in the error code.
- [Shopper Custom Object](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-custom-objects?meta=Summary) API scopes are now limited to 20 entries. This is now enforced in both SLAS API and SLAS Admin UI.
- Enhanced SLAS internal error handling and log messages.

### 05/13/2024

#### SCAPI Release

- With B2C Commerce version 24.5, the Shopper Baskets API supports patching variations within product bundles in a single call. This enhancement provides:

  - More efficient and streamlined product bundle management, making it easier to update multiple variations within a bundle without the need for multiple API calls.
  - Increased productivity for developers managing complex product bundles.

  For details, see [updateItemInBasket.](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=updateItemInBasket)

### 05/07/2024

#### SLAS Release

- SLAS database performance improvements. No customer impact is anticipated.
- SLAS internal infrastructure optimization. No customer impact is anticipated.

### 05/02/2024

#### Deprecation Notification

- The following Shopper Baskets (v1 and v2) endpoints are deprecated and are no longer supported:
  - [addPriceBooksToBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addPriceBooksToBasket)
  - [getPriceBooksForBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=getPriceBooksForBasket)

#### Maintenance Notification

- Internal infrastructure change for SCAPI contract validation. No customer impact is anticipated.
- Removed obsolete code modules related to encoding issues. For encoding details, see [URL Encoding of Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### 04/25/2024

#### SCAPI Features

With B2C Commerce 24.5, You can use external taxation mode with the Shopper Baskets API when hooks are enabled. For details, see [External Taxation Documentation.](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary#:~:text=the%20line%20totals.-,External%20Taxation,-The%20B2C%20Commerce)

### 04/23/2024

#### SCAPI Features

- You can now use the Script API response object to set custom response headers. For details, see [Custom Headers.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html?q=c_#custom-headers)
- Update on encoding handling for special characters. For details, see [URL Encoding of Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### 04/10/2024

#### Maintenance Notification

- Optimization performed in internal infrastructure routing. No customer impact anticipated.

### 04/09/2024

#### SCAPI New Features

- SLAS now supports [merging user profile attributes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html) for the Apple IDP.

### 03/27/2024

#### SCAPI New Features

With B2C Commerce 24.4:

- Added the Shopper Custom Objects API for retrieving Custom Objects. For details, see [Shopper Custom Objects.](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-custom-objects)
- Added support for additional HTTP methods for Custom APIs. For details, see [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html).

#### Maintenance Notification

- SCAPI: Routine maintenance of infrastructure. No customer impact is anticipated.
- SLAS: Database and infrastructure updates. During the deployment period, shoppers might experience elevated response times for less than a minute.

### 03/18/2024

#### SCAPI Maintenance Notification

- Routine maintenance of infrastructure. No customer impact is anticipated.

### 03/11/2024

#### SCAPI New Features

- Added response timeout handling for Sandbox instances:
  - If responding to a SCAPI request takes too long (60 seconds for Data API requests), an HTTP 504 status code is returned.
  - This is only enforced for requests to Sandbox instances, but will be rolled out to all instance types in the future.
  - For more information see [Error Response Codes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html#504-gateway-timeout).
- With B2C Commerce 24.3, updated the Orders API [updateOrderStatus endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=updateOrderStatus) to support a new update status `failed_with_reopen`:
  - When an order is updated with the `failed_with_reopen` status, the order status is set to `failed`.
  - If the basket can be reopened, the API returns response code 201 with the reopened basket URL in the location header.
  - If the basket cannot be reopened, the API returns response code 204 with an empty location header.
- With B2C Commerce 24.3, expanded the Shopper Search API [productSearch endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch) to include additional parameters: `productPromotions`, `imageGroups`, `priceRanges`, and `variants`:
  - The corresponding expansion and query parameters are required in order to get the additional product data in the response. For details and best practices, refer to the [Shopper Search API documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary).
- Added the Customer API [searchCustomerGroup endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/customers?meta=searchCustomerGroup), which searches for customer groups for the siteId.

#### SCAPI Maintenance Notification

- Routine maintenance of infrastructure. No customer impact is anticipated.

### 03/05/2024

#### SLAS: Maintenance Notification

- During the maintenance window, shoppers might experience elevated response times.
- For the latest B2C Commerce service status and deployment information, subscribe to [Trust Center notifications.](https://status.salesforce.com/instances/COMMERCECLOUDSERVICESUS)

### 2/29/2024

#### SCAPI - Shopper SEO

- This feature is generally available from B2C Commerce 24.2:

  - Updated [getUrlMapping](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=getUrlMapping)'s response to include the optional property `resourceSubType`, which indicates whether the resolved object is a Page Designer content asset or a Content Slot asset. For more information, see the [UrlMapping type reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=type%3AUrlMapping).

- These features are generally available from B2C Commerce 24.3:

  - Updated getUrlMapping to support [URL redirects](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&language=en_US&type=5). For more information, see the [URL Resolution guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-resolution.html).

  - Updated getUrlMapping to support these hooks: `dw.shop.seo.url_mapping.beforeGET` and `dw.shop.seo.url_mapping.modifyGETResponse`.

### 02/28/2024

#### SCAPI New Features

- Custom Request Headers
  - Developers can send custom request headers that are passed and made available in server-side custom implementations.
  - The required pattern is: `c\_{yourHeader}`.
- [Update order](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=updateOrder) now supports the [ShopperTokenTsob](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=security%3AShopperTokenTsob) security scheme.
- Shopper Baskets v2 available with B2C Commerce 24.1
  - Provides support for temporary baskets. Temporary baskets can perform calculations to generate totals, line items, promotions, and item availability without affecting the shopper’s storefront cart. You can use these calculations for temporary basket checkout.
  - New Shopper Basket v2 response fields:
    - `groupedTaxItems`
    - `taxRoundedAtGroup`
    - `temporaryBasket`
  - Temporary basket use cases include:
    - A shopper wants to purchase an item without affecting their existing shopping cart, which contains items for an unrelated purchase:
      - A shopper selects an Apple Pay button for a product.
      - A shopper selects a reorder button for a product on an order history page.
      - A shopper selects an order button on a wish list page to purchase one or more items.
    - A merchant shares a link through social channels to purchase promotional items.
    - A customer support agent sends a **Buy Now** link with pre-set products to a shopper for self-checkout (no passing of payment details to support).
  - For additional details, see [Shopper Baskets V2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary).

**note:** The `dw.ocapi.shop.basket.beforePOST` hook is no longer supported in Shopper Baskets V2 and is replaced by the `dw.ocapi.shop.basket.beforePOST_v2` hook.

#### SCAPI Fixes

- Stricter request header filtering is performed. Custom code must use custom request headers.
- Identical `CorrelationId` information is no longer returned for independent requests.
- Correct 503 status code is now returned during a site maintenance window.

### 2/22/2024

#### SLAS: Maintenance Notification

- During the maintenance window, shoppers might experience elevated response times.
- For the latest B2C Commerce service status and deployment information, subscribe to [Trust Center notifications.](https://status.salesforce.com/instances/COMMERCECLOUDSERVICESUS)

### 2/14/2024

#### SCAPI Load Shedding

- Introduced new load shedding functionality that:
  - If the system reaches a load threshold, an HTTP 503 response is returned for a subset of API families.
  - Covers APIs not covered by rate limits that are considered non-critical, for example: endpoints related to search, products, and authentication. Load shedding is not used for checkout-related endpoints, such as Shopper Baskets and Shopper Orders, to ensure that shoppers can complete an in-progress checkout.
  - Includes additional HTTP response headers that allow you to understand the current system load: `sfdc_load`, which represents a load percentage with higher percentages indicating higher loads, and `sfdc_load_status`, which is a enum `WARN|THROTTLE` that helps you understand the relative health of the system.

#### SCAPI Maintenance Release

- Routing for `/shopper-experience` requests resulting in HTTP 500 errors.
- Cleanup of deprecated infrastructure and configuration.

### 2/13/2024

#### SLAS

- SLAS Admin UI: Added client name to the client list and detail pages.
- SLAS API: Added support for the `DoNotTrack` (DNT) query parameter in token calls for headless customers. This is in preparation for a future SCAPI B2C Commerce rollout. Additional documentation will be provided.
- SLAS to B2C Commerce Data consistency: Addressed a limitation around customer records synchronization between B2C Commerce and SLAS.
- SLAS third-party IDP configuration is tolerant of missing `idToken` when refreshing third-party IDPs.
- Security updates.

### 2/8/2024

#### SCAPI - Shopper Search

These features are generally available with B2C Commerce 24.3:

- The `select` query parameter in the [Product Search API endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch) filters the response payload by a specified field or set of fields. This allows you to focus on the data that's important to you and improve page loading speed.
- Save time and improve product listing page (PLP) performance by using the enhanced [Product Search API endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch). Use the new optional expansion on the Product Search API endpoint to retrieve product metadata and avoid the use of additional API calls to Get Products. Use these features to provide the additional information needed to render your PLP:
  - **Allowable value:** `promotions` value in the `expand` query parameter
  - **Query parameters:** `perPricebook`, `allImages`, and `allVariationProperties`
  - **Responses:** `productPromotions`, `imageGroups`, `priceRanges`, `tieredPrices`, `variants`, and `variationGroups`

### 2/06/2024

#### SCAPI - Custom APIs Generally Available with B2C Commerce 24.2

Salesforce now provides a new framework that enables you to write custom B2C commerce script code, such as controllers, and expose this functionality as a custom REST API endpoint under the SCAPI framework. Those custom API endpoints accept the same AuthN/AuthZ model as our Shopper and Admin APIs.

With the transition from Beta to General Availability (GA), future changes to B2C Commerce Custom APIs will follow our [change policy.](https://developer.salesforce.com/docs/commerce/commerce-api/guide#change-policy)

If you are new to Custom APIs, see [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html) as a starting point.

- New features (non-breaking changes) not included in the Beta:
  - Added the [RestResponseMgr Script API class](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/scriptapi/html/api/class_dw_system_RESTResponseMgr.html) to simplify writing custom APIs.
  - Added support for local references of [shared objects](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-components-references.html) in the API contract.
  - Added support for the `AmOauth2` method for Admin APIs. For details, see [Custom API Authentication and Authorization.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-authentication.html)
- If you particpated in the Custom APIs Beta, the transition to General Availability causes the following BREAKING changes. Review and update your code as needed:
  - Custom endpoints now require custom scopes. For details, see [Scopes.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-authentication.html)
  - Storefront quota limits are now enforced. Review these limits and fix any errors. For details, see [API Quotas.](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/API_Quotas.html) The quota limits relevant for Custom APIs are the ones marked as `Storefront Limit`.
  - We've added Circuit Breaker functionality that is similar to what exists for hooks to Custom APIs. This is a protective measure that blocks API requests when the error rate is too high. For details, see [Circuit Breaker.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-circuit-breaker.html)
    B2C Commerce Custom APIs support HTTP GET requests as well as DELETE, HEAD, and OPTIONS. Future transaction support with POST, PUT, PATCH is being planned.

#### Replace Firewall Rules with New Custom Rules

- Custom rules allow you to control incoming traffic by setting up firewall policies based on various request parameters. These API endpoints expand on the existing functionality of firewall rules. With custom rules, you have complete control over the rule expression. We’ve also extended the list of allowed request field types and rule actions, which offer increased flexibility and allow you to create expressions that match your specific traffic needs.
- B2C Commerce has migrated all existing firewall rules to a new custom rules CDN-API endpoint. All customers are directed to transition to using custom rules in place of firewall rules. The firewall rules are scheduled for deprecation. Complete the transition to custom firewall rules in place of firewall rules before February 1, 2024.
- For additional details, see: [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html)

### 1/31/2024

#### SCAPI Maintenance Release

- Cleanup of deprecated SCAPI migration code and configuration. These are nonbehavioral changes.

### 1/18/2024

#### SCAPI Maintenance Release

- Resilience improvements for the SCAPI CDN layer

### 1/17/2024

#### SLAS

- Improved error handling for TSOB(Trusted system on Behalf) for "customer not found" user scenarios.
- Support added for using SAP Customer Data Cloud [socialize REST endpoints](https://help.sap.com/docs/SAP_CUSTOMER_DATA_CLOUD/8b8d6fffe113457094a17701f63e3d6a/4176c45f70b21014bbc5a10ce4041860.html).
- IDP configuration now allows the IDP client credentials to be added to the POST body.
  - SLAS now supports OIDC client_secret_basic and client_secret_post for client authentication.
- Updated the `/introspect` endpoint to include a “sub” claim in the [response](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=introspectToken).
- Improved validation in Session Bridge(SESB) flow by checking for the `customer_id` and failing the request if the customer is already registered.
- Includes SLAS Admin UI and API fix to address the cache synchronization issue when a client is edited or deleted.

### 1/4/2024

#### SCAPI Maintenance Release

- Minor fixes
- Added new `sfdc_maintenance` header in SCAPI responses during maintenance windows

## 2023

### 11/07/2023

#### SCAPI Maintenance and PIG Feature Release (holiday preparation)

- Resilience improvements for the SCAPI CDN layer
- Update on encoding handling for special characters

### 11/02/2023

#### SCAPI Maintenance and PIG Feature Release (holiday preparation)

- Holiday preparation: Improve visibility and stability
  - Improve header handling for resiliency

### 10/31/2023

#### Shopper Login (SLAS)

- Enhanced error handling for SLAS TSOB (Trusted System on Behalf) when IDP is B2C Commerce. For the first time call with a non-existing shopper ID, error code 400 is returned in place of the incorrect 409 error code. This change is specific to B2C IDP and does not impact TSOB using Okta or any other 3rd-party IDPs.
- Infrastructure and scale improvements to handle higher transaction volume for the upcoming holiday season.
- In view of Salesforce wide Holiday moratorium, no planned SLAS releases during 11/6/2023 and 1/2/2024.
- **Deprecation Notice**: After January 31st, 2024, merchants will no longer be able to use the DWSID parameter and `loginId=guest` on the `/session-bridge/token`. Beyond this timeline, accessing this API returns a 404 error and prevents your guest shoppers access to your storefront. For more information, see [Shopper Login and API Access Service(SLAS) Session Bridge DWSID GUEST Deprecation](https://help.salesforce.com/s/articleView?id=000396631&type=1).

### 10/27/2023

#### SCAPI - Shopper SEO

- The Get URL Mapping API endpoint allows headless storefronts to support localized, user-friendly URLs based on URL rules set up in [Business Manager](https://help.salesforce.com/s/articleView?id=cc.b2c_using_url_rules_for_seo.htm&type=5). This endpoint helps you to increase your site traffic and improve site navigation. Get URL Mapping is in a new API named Shopper SEO. For more information, see [URL Resolution](https://developer.salesforce.com/docs/commerce/commerce-api/guides/url-resolution.md) and the [Shopper SEO API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo/shopper-seo.raml).

### 10/26/2023

#### SCAPI - Shopper Stores

- Use the Shopper Stores API to find details about stores. Shoppers can locate nearby stores for delivery or offline shopping. See the [Shopper Stores API reference](/docs/commerce/commerce-api/references/shopper-stores?meta=Summary).

### 10/25/2023

#### Shopper Login (SLAS)

- **Deprecation Notice**: After January 31st, 2024, merchants will no longer be able to use the DWSID parameter and `loginId=guest` on the `/session-bridge/token`. Beyond this timeline, accessing this API returns a 404 error and prevents your guest shoppers access to your storefront. For more information, see [Shopper Login and API Access Service(SLAS) Session Bridge DWSID GUEST Deprecation](https://help.salesforce.com/s/articleView?id=000396631&type=1).
- In view of Salesforce wide Holiday moratorium, no planned SLAS releases during 11/6/2023 and 1/2/2024.
- Addressed a bug in SLAS Session Bridge (SESB) functionality when a guest user transitions to registered user with the authorize (/authorize) flow.
- SLAS Admin UI validation and messaging for Shopper context API public client customers.
- SLAS Monitoring enhancements as part of Holiday readiness.
- SLAS now supports Last Name(family_name claim) as optional for Google IDP client.

#### SCAPI

#### Shopper Orders

- Shopper Orders Guest Order Lookup secured by SLAS Trusted System On Behalf Token is available now.
- The Order response document now contains an order view code that can be used to retrieve guest orders securely using the Guest Order Lookup endpoint. The order view code contains only URL-safe characters.

  **Warning**: Do not expose the order view code in the URL. The order view code can only be displayed to the shopper or sent as an email. Do not log the order view code in the code.

#### SCAPI Maintenance and PIG Feature Release (holiday preparation)

- Request header size optimizations
- Bugfix for shopper-search refinement parameter encoding

### 10/18/2023

#### Shopper Login (SLAS)

- **Deprecation Notice**: After January 31st, 2024, merchants will no longer be able to use the DWSID parameter and `loginId=guest` on the `/session-bridge/token`. Beyond this timeline, accessing this API returns a 404 error and prevents your guest shoppers access to your storefront. For more information, see [Shopper Login and API Access Service(SLAS) Session Bridge DWSID GUEST Deprecation](https://help.salesforce.com/s/articleView?id=000396631&type=1).
- In view of Salesforce wide Holiday moratorium, there will not be any planned SLAS releases during 11/6/2023 and 1/2/2024.
- SLAS Infrastructure and scale improvements to handle higher transaction volume for the upcoming holiday season.
- Fixed a bug related to Cache synchronization across SLAS PODs.
- Security library updates

#### SCAPI - Shopper Context

- `CustomerGroupIds` is now supported in Shopper Context API.

### 10/11/2023

#### Shopper Login (SLAS)

- **Deprecation Notice**: After January 31st, 2024, merchants will no longer be able to use the DWSID parameter and `loginId=guest` on the `/session-bridge/token`. Beyond this timeline, accessing this API returns a 404 error and prevents your guest shoppers access to your storefront. For more information, see [Shopper Login and API Access Service(SLAS) Session Bridge DWSID GUEST Deprecation](https://help.salesforce.com/s/articleView?id=000396631&type=1).
- Aligning with the Salesforce-wide Holiday moratorium, there are no planned SLAS releases between 11/6/2023 and 1/2/2024.
- SLAS now supports OIDC locales parameter on [/authorize endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer).
- Security Bug fixes

#### SCAPI Maintenance and PIG Feature Release (holiday preparation)

- Holiday preparation: Improve performance, visibility, and stability
  - Following the preview release from 08/30/2023 we are now releasing this feature and iinfrastructure update to production environments.
  - Affected PODs are all PODs that were not listed in the two releases from 09/27/2023 and 09/21/2023.
  - Updated infrastructure layers and routing rules for SCAPI requests to use fewer hops in the network.
  - Introduction of new custom query parameters: `c\_<yourparameter>`` can now be defined on SCAPI requests and is be routed end to end, Parameters are available in hooks for custom control logic.

### 10/05/2023

#### SCAPI Maintenance and PIG Feature Release (holiday preparation)

- Holiday preparation: Improve visibility and stability
  - Updated infrastructure layers for SCAPI requests

### 10/03/2023

#### Shopper Login (SLAS)

- SLAS Infrastructure and scale improvements to handle higher transaction volume for the upcoming holiday season.

### 09/28/2023

#### SCAPI Maintenance and PIG Feature Release (holiday preparation)

- Holiday preparation: Improve performance by enabling of caching
  - Affected PODs are: POD94, POD112, POD122, POD159, POD162, POD173, POD192, POD194, POD198, POD204, POD226

### 09/27/2023

#### SCAPI Maintenance and PIG Feature Release (holiday preparation)

- Holiday preparation: Improve performance, visibility, and stability
  - Following the preview release from 08/30/2023 we are now releasing this feature update to production environments.
  - Affected PODs are: POD114, POD136, POD149, POD173, POD174, POD210, POD229, POD250, POD253, POD260
  - Updated infrastructure layers and routing rules for SCAPI requests to use fewer hops in the network.
  - Introduction of new custom query parameters: `c_<yourparameter>` can now be defined on SCAPI requests and is routed end to end. Parameters are available in hooks for custom control logic.
  - CORS headers handling, ALL customers.
  - CORS headers like _Origin_ are NOT interpreted any longer, to avoid CORS errors.
  - SCAPI currently does not support CORS.

### 09/26/2023

#### Shopper Login (SLAS)

- SLAS Infrastructure and scale improvements to handle higher transaction volume for the upcoming holiday season.
- SLAS IDP authorize now enables merge shopper profile capability. We've extended [`registerIdentityProvider`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider) to support a new parameter `loginMergeClaims`. This parameter allows you to specify whether shopper accounts created via this IDP should be merged with existing accounts using one of those parameter values, preserving order history (amongst other things). Refer to the [Merge Shopper Profiles User Guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html) and [`registerIdentityProvider`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider).

### 09/21/2023

#### SCAPI Maintenance and PIG Feature Release (Holiday Preparation)

- Following the preview release from 08/30/2023 we are now releasing this feature update to production environments.
- Affected PODs are: POD94, POD112, POD122, POD136, POD159, POD162, POD173, POD192, POD194, POD198, POD204, POD226, POD240, POD248, and POD253
- Holiday preparation: Improve performance, visibility, and stability
- Updated infrastructure layers and routing rules for SCAPI requests to use fewer hops in the network
- New custom query parameters: `c_<yourparameter>` can now be defined on SCAPI requests and will be routed end to end. Parameters are available in hooks for custom control logic.

### 09/19/2023

#### Shopper Login (SLAS)

- Infrastructure and scale improvements to handle higher transaction volume for the upcoming holiday season
- SLAS Admin UI: Default IDP claims removed from UI map if they are not a Generic IDP
- Addressed a bug related to 3rd party logout on ECOM during SLAS /logout endpoint call https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=logoutCustomer

#### SCAPI Maintenance Release

- Security Updates

### 09/18/2023

#### SCAPI Maintenance Release

- Log Improvements

### 08/30/2023

#### SCAPI Maintenance and SIG Feature Release (Holiday Preparation)

- Preview release to sandboxes only (SIG and ODS).
- Holiday preparation: Improve performance, visibility, and stability.
- Updated infrastructure layers and routing rules for SCAPI requests to use fewer hops in the network.
- Introduction of **new custom query parameters**: `c\_<yourparameter>` can now be defined on SCAPI requests and are routed end to end, and therefore available in hooks for custom control logic.

  **note:** We'd like all customers to verify your existing SCAPI implementation on sandboxes and report any issues back.

### 08/29/2023

#### Shopper Login (SLAS)

- **Trust Notification**
  - SLAS Infrastructure and scale improvements to handle higher transaction volume for the upcoming holiday season.
  - Improvements to Trusted System on Behalf (TSOB) flow to be able to better handle simultaneous requests.
  - As part of our efforts to scale the SLAS service for the upcoming holiday volume, temporarily, starting the week of August 7, registered shopper refresh tokens (existing and new) are valid for only 45 days, instead of the earlier validity of 90 days. This applies to shopping apps integrated with SLAS, and to shoppers who have not returned to the shopping app at least once in the last 45 days need to relogin. This temporary state ends on September 15. After September 15, registered shopper refresh tokens will resume their full 90 day, standard duration. Shopper Guest sessions and B2C Commerce basket retention is not affected in any way.

### 08/28/2023

#### Shopper Search

- [productSearch](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch) now correctly handles storefront search filters and refinement values with the `&` character, and considers all terms in the refinement attribute before and after the `&`. Previously, the search filter and refinement parameter was incorrectly truncated, and requested refinements with the `&` character in the attribute name did not match the configured refinements in Business Manager.

### 08/24/2023

#### SCAPI Maintenance Release

- Security updates

### 08/22/2023

#### Shopper Login (SLAS)

- SLAS Infrastructure and scale improvements to handle higher transaction volume for the upcoming holiday season.
- Addressed a limitation in SLAS Session Bridge (SESB) functionality when a guest user creates a cart, add products to the cart, and then login as a registered user WITH trusted system (TSOB) to merge the cart and it fails.
- Addressed a bug related to case sensitive `login_id` comparison for Session Bridge (SESB) token requests, where the casing of the `login_id` passed to `getSessionBridgeAccessToken` was different from the casing of the `login_id` in B2C Commerce.
- As part of our efforts to scale the SLAS service for the upcoming holiday volume, temporarily, starting the week of August 7, registered shopper refresh tokens (existing and new) are valid for only 45 days, instead of the earlier validity of 90 days. This applies to shopping apps integrated with SLAS, and to shoppers who have not returned to the shopping app at least once in the last 45 days need to relogin. This temporary state ends on September 15. After September 15, registered shopper refresh tokens will resume their full 90 day, standard duration. Shopper Guest sessions and B2C Commerce basket retention is not affected in any way.

### 08/16/2023

#### SCAPI Maintenance Release

- Security Updates

### 08/15/2023

#### Shopper Login (SLAS)

- Addressed a limitation in `plugin_slas` integration with SLAS around Merge Cart for Guest to Registered flow.
- For the `getSessionBridgeAccessToken` endpoint, the returned `TokenResponse` now correctly includes the `enc_user_id attribute`.
- As part of our efforts to scale the SLAS service for the upcoming holiday volume, temporarily, starting the week of August 7, registered shopper refresh tokens (existing and new) are valid for only 45 days, instead of the earlier validity of 90 days. This applies to shopping apps integrated with SLAS, and to shoppers who have not returned to the shopping app at least once in the last 45 days need to relogin. This temporary state ends on September 15. After September 15, registered shopper refresh tokens will resume their full 90 day, standard duration. Shopper Guest sessions and B2C Commerce basket retention is not affected in any way.

### 08/11/2023

#### SCAPI Maintenance Release

- Security Updates

### 08/10/2023

#### SCAPI - Products

- Increased timeout from 10 seconds to 25 seconds for incoming requests to Products data endpoints.

### 08/08/2023

#### Shopper Login (SLAS)

- Default IDP configuration allows for SSO/OIDC configuration with other IDPs outside the list of SLAS supported IDPs. Configuration can be performed via the Admin API or Admin UI. For more information, see [Configure a Default IDP](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-default-idp.html).
- Preferred IDP configuration cleanup and functionality added to Admin UI.
- As part of our efforts to scale the SLAS service for the upcoming holiday volume, temporarily, starting the week of August 7, registered shopper refresh tokens (existing and new) are valid for only 45 days, instead of the earlier validity of 90 days. This applies to shopping apps integrated with SLAS, and to shoppers who have not returned to the shopping app at least once in the last 45 days need to relogin. This temporary state ends on September 15. After September 15, registered shopper refresh tokens will resume their full 90 day, standard duration. Shopper Guest sessions and B2C Commerce basket retention is not affected in any way.
  Ideally, customers should be Shopper Guest sessions and B2C Commerce basket retention is not affected in any way.

### 08/07/2023

#### SCAPI

Certificate rotation for SCAPI logging and metrics infrastructure.

- One certificate pair per region: EUC1, USE1, APS2, and APN1

### 08/03/2023

#### SCAPI Maintenance Release

- Security Updates

### 07/31/2023

#### SCAPI Maintenance Release

- Logging Optimizations
- Security Updates

### 07/18/2023

#### Shopper Login (SLAS)

- SLAS Infrastructure and scale improvements.
- SLAS Admin UI improvements related to user search and get user statistics.
- Fixed logout implementation. SLAS to OCAPI calls no longer fail throwing [ClientAccessForbiddenException](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=logoutCustomer).
- As part of our efforts to scale the SLAS service for the upcoming holiday volume, temporarily, starting the week of August 7, registered shopper refresh tokens (existing and new) are valid for only 45 days, instead of the earlier validity of 90 days. This applies to shopping apps integrated with SLAS, and to shoppers who have not returned to the shopping app at least once in the last 45 days need to relogin. This temporary state ends on September 15. After September 15, registered shopper refresh tokens will resume their full 90 day, standard duration. Shopper Guest sessions and B2C Commerce basket retention is not affected in any way.

### 07/17/2023

#### SCAPI Maintenance Release

- Performance optimizations

### 07/14/2023

#### Shopper Baskets and Shopper Orders

- Optional query parameter `locale`, is now supported for [mergeBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=mergeBasket), [transferBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=transferBasket) and all delete endpoints in Shopper Orders and Shopper Baskets, with the exception of [deleteBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=deleteBasket).
- [PaymentCardSpec](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3APaymentCardSpec) includes a new field `securityCodeLength`. This is available in the response for Shopper [baskets - getPaymentMethodsForBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=getPaymentMethodsForBasket) and [Shopper Orders- getPaymentMethodsForOrder](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=getPaymentMethodsForOrder) endpoints.
- Coming soon: [mergeBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=mergeBasket) and [transferBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=transferBasket) response will no longer include the property `notes`. Previously, this property was sent with an empty value in the response.
- Fix coming soon: [mergeBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=mergeBasket) will return an HTTP 409 error response `no-source-basket-exception` if the guest's basket has already been ordered. _Previously, the ordered guest basket was merged with the new basket._

### 07/12/2023

#### SCAPI Maintenance Release

- Performance optimizations

### 07/11/2023

#### Shopper Login (SLAS)

- SLAS Infrastructure and scale improvements to handle higher transaction volume.

### 07/10/2023

#### Shopper Search

- [productSearch](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch) now correctly handles storefront search queries with the `&` character and considers all terms before and after the `&`. Previously, the search query was incorrectly truncated before the `&` character and subsequent terms were missing in the query.

### 06/27/2023

#### Shopper Login (SLAS)

- SLAS `/token` endpoint includes refresh token time to live (TTL) claim, and the value is in seconds to be consistent with `expires_in` for the `access_token` TTL. For more information, see [`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken).

- Improved error handling to send clear 4xx messages on `/revoke` endpoint if a null token is provided. For more information, see [`revokeToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=revokeToken).

- SLAS Admin has enhanced validation in place to help customers create tenants in the correct region.

#### SCAPI Maintenance Release

- Performance optimizations

### 06/21/2023

#### SCAPI Maintenance Release

- Performance optimizations

### 06/15/2023

- Shopper Customers API and Customers API security updates.

### 06/14/2023

#### SCAPI Maintenance Release

- Updated configuration handling to improve performance.
- Update on metrics and logging to improve supportability.

### 06/13/2023

#### Shopper Login (SLAS)

- [introspectToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=introspectToken) returns more specific error messages on failures.
- [authenticateCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer) and other endpoints which result in calls to a B2C Commerce instance return more specific error messages when that instance is down.
- To support native mobile apps, added support for custom scheme redirects.

#### Salesforce Commerce API

- Updated routing and mapping policies to prepare for future functionality.
- Security updates.

### 05/30/2023

#### Shopper Login (SLAS)

- Updated [TokenResponse](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=type%3ATokenResponse), extending the maximum size of `idp_access_token` to 8k bytes.
- [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getSessionBridgeAccessToken) supports a new optional parameter `dwsgst`. Its value is a guest session signature created from Script API's `Session.generateGuestSessionSignature()`. Passing this parameter improves the performance of this API.
- [Guest refresh tokens are now valid for 30 days](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#access-tokens-and-refresh-tokens). _Previously, they were valid for 90 days._

### 05/17/2023

#### Shopper Login (SLAS)

- Updated the [getTrustedAgentAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedAgentAccessToken) endpoint to make the `agent_id` parameter _optional_.
- Updated the SLAS Admin UI with specific error messaging for issues with logging into Account Manager.
- Private clients now support `grant_type=authorization_code` in addition to `grant_type=authorization_code_pkce`.
- Removals of customer records in B2C Commerce are now synchronized with SLAS. If a customer record is deleted in B2C Commerce, this change is recognized by SLAS.

### 04/25/2023

#### Shopper Login (SLAS)

- **NEW** SLAS-Agentforce Marketing SMS for Passwordless login is ready! See [Passwordless Login with SMS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-sms.html) to get started.
- [resetPassword](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=resetPassword) rejects weak passwords with an HTTP 400 error.
- [getUserInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getUserInfo) supports names with special characters.
- [getUserInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getUserInfo) supports Trusted System on Behalf of tokens.
- Credential Quality APIs deprecated and removed.
- Improved Guest Shopper validation to allow B2C Commerce IDP origin for session bridge.
- Session Bridge: fixed 500 server error on incorrect hint.
- SLAS Admin UI: Fixed issues related to Tenant ID format check at browser level.

### 04/06/2023

- Shopper Baskets now supports the following SLAS _Trusted-Agent-On-Behalf_-only endpoints:
  - PUT `/baskets/{basketId}/agent`
  - PUT `/baskets/{basketId}/storefront`
  - POST `baskets/{basketId}/price-adjustments`
  - DELETE `baskets/{basketId}/price-adjustments/{priceAdjustmentId}`
  - PATCH `baskets/{basketId}/price-adjustments/{priceAdjustmentId}`
- The following new channel types are supported by Baskets and Orders apps: TikTok, SnapChat, Google, WhatsApp, and YouTube

### 03/29/2023

- BOT Mitigation improvements: Reduced the time window from 2 seconds to 1 second for the same user login that returns Error 409.
- Fixed the issue around deletion of a user with different loginID and IDP, when the tenant and customerID remains the same.
- SLAS Tenant creation improvements to include region validation.
- SLAS Service Introducing Rate Limit of 25 TPM per tenant for JWKs and well-known endpoints.
- SLAS service redirect to customer’s registered callback URL on IDP errors and return Error 412 for refresh token calls.

### 03/14/2023

- Trusted agent on behalf (TAOB): Client ID present check fix on `/auth` rather than `/token`.
- Guest SESB refresh bug fix.
- Improved IDP message errors back from third-party IDP.

### 03/09/2023

- [Shopper Context API](/docs/commerce/commerce-api/references/shopper-context) update.

### 02/22/2023

#### Shopper Login (SLAS)

- Increase shopper authorization code size to accommodate larger code sent from Identity Providers.
- SLAS Admin UI fixes for tenant display post deletion and faster IDP creation.
- SLAS Admin: Client scope update fix.
- Trusted agent on behalf: additional redirect URI parameters for authorize are separated properly.

### 02/09/2023

- Shopper-Experience API global rollout.

### 02/01/2023

#### Shopper Login (SLAS)

- Bug fixes:
  - Admin UI, client create claims fix
  - SESB fix for OCAPI calls
- Features:
  - Support for Active Directory Federated Service IDP

### 01/23/2023

- The [Shopper Context API](/docs/commerce/commerce-api/references/shopper-context) is now generally available!
- Rate limit update to the rules endpoint in the Catalogs API.

### 01/16/2023

- Update TrustedAgentOnBehalf support for Shopper Token policy.

### 01/12/2023

#### Shopper Login (SLAS)

- Support for Forgerock IDP.
- Trusted agent on behalf (TAOB) now supports Private ClientID flow. Changed the TAOB JWT token expiry from 30 to 15 minutes for PCI compliance.
- `/jwks` endpoint now returns 3 key IDs (past, current, and future KeyID).
- Reduced the Passwordless OTP - token length from 20 to 8 characters.
- Enhanced BOT mitigation strategy within SLAS.
- Fixed inconsistencies related to failed tokens.
- Session Bridge: Improved error messaging & guest support.
- SLAS no longer calls ecom, when a shopper account is locked.
- User cache refinements & Fixed cache inconsistencies after tenant key rotation.
- Addressed login ID inconsistencies for passwordless login.
- Fixed AppleIDP issue related to middle name.

## 2022

### 11/03/2022

#### Shopper Customers

- Rate limit increase for `GET /customers/*(Shopper-Customers)`. <!-- see [Rate Limits](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html). -->

### 11/01/2022

#### Shopper Customers

- Rate limit increase for `GET /products-lists/{id}(Shopper-Customers)`. <!-- see [Rate Limits](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html).  -->

### 10/27/2022

#### Orders

- Rate limit increase for `Orders` API. <!-- see [Rate Limits](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html). -->
- Rate limit updates: API families have either a 5s tier or a 60s tier. <!-- see [Rate Limits](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html). -->

#### Shopper Products

- Response compression has been introduced.
- The `expand` query parameter has been added for `getProducts`.

### 10/24/2022

- Added support for `correlation-id` and `x-correlation-id` headers.

### 09/14/2022

The scheduled deactivation of `/customers/actions/login`, `/trusted-system/actions/login`, and other related endpoints has been extended from mid-2022 to March 31st, 2023 for existing customers. These endpoints are still not available to new customers, and we still discourage existing customers from using them. Instead, we strongly recommend that you use the [Shopper Login and API Access Service](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) (SLAS) because it meets a higher standard for security and availability.

### 09/13/2022

- Increased performance and response times through caching on the edge layer.
- Resources affected: `/product`, `/category`, and `/product_search`.
- Updates to the personalization handling ensure that personalized content is cached correctly.
- No action is required by developers to take advantage of this update.

#### Shopper Login (SLAS)

- Replace `SlasJWT-BearerSecurityScheme.BearerToken` security scheme with `CommerceCloudStandards.ShopperToken`.

<!-- document id=d293e0996e0dbc82c0e5a6135b78a5c485f71f9cadc21056e36de944031bca27 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/get-started.md -->

# B2C Commerce Architecture

We provide several resources to help you learn about Salesforce B2C Commerce.

For a summary of the developer workflow, see [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md).

## Concepts and Terminology

B2C Commerce provides the resources and processing for your ecommerce sites, called a storefront in the B2C Commerce documentation. You create and build your sites in your realm.

A customer realm includes a primary instance group and a secondary instance group.

### Realm

Typically, you have a single realm. The realm contains instances on which to develop, test, and deploy your online storefront. A B2C Commerce instance is an application infrastructure. It includes web servers, application servers, and database servers. You usually have six B2C Commerce instances: three or more sandbox instances for code development, and three instances for site staging, testing, and deployment.
Development instance: used for site configuration, data enrichment, and data import.
Staging instance: used to test your site before deployment.
Production instance: hosts the live site that is used by customers.
A Merchant can control their storefront online merchandising, configuration, and customization options. The instance administrator for the merchant has direct control over password management, user permissions, and stopping or starting instances within their realm.

#### Single and Multiple-Realm Configurations

In most cases, you have a single realm in which to develop, stage, and deploy multiple sites with different branding or locales. The people managing the storefront site don't have to be in the same location. Sites can share product catalogs or have different catalogs.

If you have different lines of business or global teams that each have their own processes or business policies, consider maintaining multiple realms. Also consider separate realms if you have distinct organizations with separate back-end integrations, schedules, or other concerns that make it advantageous to let each team manage their sites independently. Sites in the same realm can share the product catalog for product data. Sites in different realms can't share data through the catalog structure. However, import data into different realms to share it.
Example: Let's say that you have sites with separate brands in Europe and the Pacific Rim. Optionally, configure a realm for the team managing the Pacific Rim sites and another realm for Europe.

### Primary Instance Group

The primary instance group has three instances, which merchants use to add data, test code, and run live sites. A realm can have only one PIG per realm.

### Secondary Instance Group

The secondary instance group (SIG) contains your sandbox instances. The minimum number of sandboxes in a SIG is 3, and the maximum is 47.

## Instances

A B2C Commerce instance contains the tools and resources for customizing storefronts. Access an instance through your browser, or use Business Manager.

### Instance Types

There are four instance types: Sandbox, Staging, Development, and Production. Depending on the type, the instance is either in the realm's primary instance group (PIG) or a secondary instance group (SIG).

|                | Sandboxes                                                                                                                           | Staging                                                                                 | Development                                                                                                                                                                     | Production                                                                                                                                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage          | Used by customer developers to create and update storefront code. Used by customer developers to create and update storefront code. | Merchandising work is done here.                                                        | Simulates the production environment. Used as the final step in testing the intersection of content and code. Goes through the CDN provided by B2C Commerce, but doesn't cache. | Live instance used for storefront transactions. Connected to the CDN provided by B2C Commerce. If active merchandising is enabled, collects active data. Storefront toolkit is disabled.     |
| Location       | SIG                                                                                                                                 | PIG                                                                                     | PIG                                                                                                                                                                             | PIG                                                                                                                                                                                          |
| Data I/O       | Most system jobs are disabled for sandboxes.                                                                                        | Data and code are uploaded to Staging and then replicated to Production or Development. | Data and code are replicated from Staging. Data can be exported from the instance.                                                                                              | Data and code are replicated from Staging. Active data is gathered from Production and imported into other instance types. Data can be exported from the instance and imported into Staging. |
| Global Release | Updated for: Preview and General Availability                                                                                       | Updated for: General Availability                                                       | Updated for: General Availability                                                                                                                                               | Updated for: General Availability                                                                                                                                                            |
| Caching        | Caching is disabled. Full file system checks are performed.                                                                         | Caching is disabled. Full file system checks are performed.                             | Caching is disabled. No file system checks are performed.                                                                                                                       | Caching is enabled all the way through to the browser.                                                                                                                                       |

### Who Uses Which Instance Type?

Depending on the size of your team, one person can play more than one role.

| Role                       | Instance Type    | Responsibilities                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Developer                  | Sandbox, Staging | A developer creates or modifies templates, pipelines, and scripts on a local machine and uploads them to a Sandbox instance to test. Ultimately, the developer is responsible for uploading code to the Staging instance. The developer can also export data added by merchandisers on the Staging instance to use as test data for the sandboxes. Developers never use the Development instance unless they are involved in the testing process for the production site. |
| Merchandiser               | Staging          | A merchandiser or online marketer is typically responsible for creating campaigns and promotions, managing product information, and configuring search behavior.                                                                                                                                                                                                                                                                                                          |
| Administrator              | All instances    | An admin is responsible for granting access to instances and functionality on instances. The admin restarts instances, manages data feeds, and uploads certificates.                                                                                                                                                                                                                                                                                                      |
| Quality Assurance Engineer | Development      | This role is responsible for testing the site in conditions as close to production as possible. No code development is done on the Development instance.                                                                                                                                                                                                                                                                                                                  |

## B2C Commerce Tools

If you have the correct permissions, access the B2C Commerce tools.

- Business Manager--Configure storefronts in real time. Categorize, price, search, display, navigate, and promote merchandise.
- Control Center--Gives your IT staff operational control over your site, such as starting instances, and managing users.
- Account Manager--Lets your IT staff create user accounts on B2C Commerce, grant and revoke user access to B2C Commerce instan

## Data Input and Output

Import to and export from staging, development, and production instances and replicate between instances. If your storefront uses a third-party application, you are responsible for managing feeds into the catalog. Create feeds from Salesforce B2C Commerce for other backend systems, such as an order management system (OMS), enterprise resource planning system (ERP), product information management system (PIM), or warehouse management system (WMS).

| B2C Commerce Feature                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Import and Export                     | Feeds data from external systems into B2C Commerce, such as product, pricing, and inventory information. You also Import and Export to move data from one instance type to another. Create XML feed files that conform to B2C Commerce schemas to import data into B2C Commerce. We recommend using the scheduled job feature to automate data import and export. Developers, administrators, and merchants must work together to determine the frequency and schedule of import feeds. Developers are responsible for implementing the cartridges. Admins are responsible for creating the XML files containing data from the systems of record for products, pricing, and other data. They are also responsible for configuring the jobs required to run the import. Data is validated during import. If the import experiences too many errors, it can fail. To recover from a failed import, you must successfully complete another import. |
| Data Replication and Code Replication | Securely moves data and code between instances. Replication is a one-way process from Staging to either a Development or Production instances. Roll back from a replication to the previous version of the instance.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Code Upload                           | Used to upload code from a developer's local machine via UX Studio to a Sandbox or Staging instance. Developers are responsible for code upload.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Catalog Feeds                         | Used to process .zip files. This feature is only for additional information that is added to the catalog that isn't part of the normal catalog import and export process.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

**note:** The Batch Processing feature isn't used for data input and output.

## Sites and Storefronts

In B2C Commerce, a site is the application and associated code that runs a storefront. A storefront the user's online experience. A site can have multiple storefronts with different URLs for different brands, locales (with currency and tax differences), or multiple channels. If you are referring to a specific URL, B2C Commerce uses the term storefront.

### Site Architecture Scenarios

When designing your site, your architect must consider the following:

- The geographical relationship between storefronts and the teams that maintain them
- Data that is shared between sites, such as product data, tax and payment information, user roles and permissions, promotions, or application code
- Whether the storefront must be localized for different market locales or restructured for them
- Data that must remain separately controlled due to corporate structure or legal requirements
- Whether customer, basket, or transaction data carries over from one storefront to the next
  Example: An apparel retailer lets customers shop simultaneously at both their adult and children's sites. But a retailer with two different customer bases, such as a book publisher for religious books and fantasy fiction, can prevent crossover.

### One Site, One Storefront

The simplest scenario is one site and one storefront that it supports.

### One Site, Multiple Storefronts

If you have many storefronts and a single team maintaining them, manage them more easily as a single site, even if the products are different for each site. Similarly, if you want to share baskets between storefronts, the storefronts must be part of a single site. If you are deploying many localized sites with similar branding and products, it's faster and easier to manage new storefronts as an extension of an existing site.

### Multiple Sites, Multiple Storefronts

Multiple sites each support multiple storefronts. Share site data, such as customer data, between sites.

### Site Definition

A live site is defined as a listing in the Manage Sites screen on the merchant's production instance of Business Manager with a status set to Online, not including those sites with other statuses or sites that have been deleted.

### See Also

- [Build Your Site Structure](https://help.salesforce.com/s/articleView?id=cc.b2c_building_your_sites_informational_structure.htm&type=5)
- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=84b57296565db164337f46a773668dfef3cb91d5b5fd8496b745b38d85a45e8a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/b2c-mappings.md -->

# B2C Commerce Content Mappings

**note:** The Salesforce B2C Commerce Infocenter was retired on July 15, 2023. This change applies to all versions of Salesforce B2C Commerce.
**Where:** Documentation originally hosted on the Infocenter will be published in three new locations, as appropriate.

- [Salesforce Help](https://help.salesforce.com/s/products/commerce?language=en_US) is the new home for administrator and merchandiser content.
- [Agentforce Commerce Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud) is the new home for most developer-focused content.
- [Salesforce B2C Commerce Developer Documentation Resources](https://salesforcecommercecloud.github.io/b2c-dev-doc/) is the new home for the B2C Commerce Script API and other developer-focused content, including legacy developer documentation.

| Links to Infocenter Documents                                                                                                                                                                                    | Audience                     | Links to New Locations                                                                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [B2C Commerce Release Notes](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/ReleaseNotes/b2c_rn_release_notes.html)                                                    | Administrator and Developer  | [B2C Commerce Release Notes](https://help.salesforce.com/s/articleView?id=commerce.b2c_rn_release_notes.htm&language=en_US&type=5) in Salesforce Help                                              |
| [Get Started](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/getting_started/b2c_getting_started.html)                                     | Administrator & Merchandiser | [Get Started](https://help.salesforce.com/s/articleView?id=cc.b2c_getting_started.htm&language=en_US&type=5) in Salesforce Help                                                                    |
| [B2C Commerce Videos](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/video_content/b2c_videos.html)                                        | Administrator & Merchandiser | [B2C Commerce Videos](https://help.salesforce.com/s/articleView?id=cc.b2c_videos.htm&language=en_US&type=5) in Salesforce Help                                                                     |
| [Data Protection and Privacy](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/DataProtectionAndPrivacy/DataProtectionAndPrivacy.html)                                   | Administrator & Merchandiser | [Data Protection and Privacy](https://help.salesforce.com/s/articleView?id=cc.b2c_data_protection_and_privacy.htm&language=en_US&type=5) in Salesforce Help                                        |
| [Merchandising Your Site](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/active_merchandising/b2c_merchandising_your_site.html)            | Administrator & Merchandiser | [Merchandising Your Site](https://help.salesforce.com/s/articleView?id=cc.b2c_merchandising_your_site.htm&language=en_US&type=5) in Salesforce Help                                                |
| [Administering Your Organization](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/admin/b2c_administering_your_organization.html)           | Administrator & Merchandiser | [Administering Your Organization](https://help.salesforce.com/s/articleView?id=cc.b2c_administering_your_organization.htm&language=en_US&type=5) in Salesforce Help                                |
| [Developing Your Site](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/site_development/b2c_commerce_development.html)                      | Developer                    | [Get Started](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/get-started.html) in Agentforce Commerce Developer Center                                                               |
| Developing Your Site > [Legacy Developer Documentation](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/LegacyDevDoc/LegacyDevDoc.html)                                 | Developer                    | [Legacy Developer Documentation (PDF)](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/LegacyDeveloperDocumentation.pdf) in Salesforce B2C Developer Documentation Resources    |
| [B2C Commerce Security Guide](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/b2c_security_best_practices/b2c_commerce_security_guide.html) | Administrator & Developer    | [B2C Commerce Security Guide](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_security_guide.htm&language=en_US&type=5) in Salesforce Help                                            |
| [Commerce Einstein](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/einstein/b2c_commerce_cloud_einstein.html)                        | Administrator & Merchandiser | [Commerce Einstein](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_cloud_einstein.htm&language=en_US&type=5) in Salesforce Help                                                |
| [Endless Aisle 2.5.4](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/dss/b2c_endless_aisle_pdf.html)                        | Administrator & Developer    | N/A. This documentation is being retired because the app is no longer supported.                                                                                                                   |
| [Account Manager](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/account_manager/b2c_account_manager_overview.html)                        | Administrator & Merchandiser | [Account Manager](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_overview.htm&language=en_US&type=5) in Salesforce Help                                                       |
| [Log Center](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/site_development/b2c_log_center.html)                                          | Administrator & Merchandiser | [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&language=en_US&type=5) in Salesforce Help                                                                          |
| [Control Center](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/control_center/b2c_cc.html)                                                | Administrator & Merchandiser | [Control Center](https://help.salesforce.com/s/articleView?id=cc.b2c_cc.htm&language=en_US&type=5) in Salesforce Help                                                                              |
| [Customer Service Center](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/customer_service_center/b2c_customer_service_center.html?)        | Developer                    | [Customer Service Center](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-customer-service-center.html) in Agentforce Commerce Developer Center                                   |
| [Salesforce Payments](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/salesforce_payments/b2c_salesforce_payments.html)                     | Administrator                | [Salesforce Payments](https://help.salesforce.com/s/articleView?id=cc.b2c_salesforce_payments.htm&language=en_US&type=5) in Salesforce Help                                                        |
| [Storefront Toolkit](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/storefront_toolkit/b2c_sftk_container.html)                            | Administrator                | [Storefront Toolkit](https://help.salesforce.com/s/articleView?id=cc.b2c_sftk_container.htm&language=en_US&type=5) in Salesforce Help                                                              |
| [Open Commerce API (OCAPI)](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/OCAPI/current/usage/OpenCommerceAPI.html)                                                   | Developer                    | [Get Started with OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html) in Agentforce Commerce Developer Center                 |
| [Script Debugger API (SDAPI)](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/ScriptDebuggerAPI/latest/usage/ScriptDebuggerAPI.html)                                    | Developer                    | [Script Debugger API (PDF)](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/sdapi_2_0.pdf) in Salesforce B2C Developer Documentation Resources                                  |
| [Glossary](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/Glossary/aGlossary.html)                                                                                     |                              | N/A. This documentation has been retired.                                                                                                                                                          |
| [B2C Commerce API](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/DWAPI/compareapi/html/whatsnew/overview.html)                                                        | Developer                    | [Salesforce B2C Developer Documentation Resources](https://salesforcecommercecloud.github.io/b2c-dev-doc)                                                                                          |
| [Storefront Reference Architecture (SFRA) JavaScript](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/sfrajsdoc/index.html)                                             | Developer                    | [Storefront Reference Architecture (SFRA) JavaScript](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/sfrajsdoc/index.html) in Salesforce B2C Developer Documentation Resources |
| [SiteGenesis Server-side JavaScript](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/jsdoc/dist/js/server/index.html)                                                   | Developer                    | [SiteGenesis Server-Side JavaScript](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/jsdoc/dist/js/server/index.html) in Salesforce B2C Developer Documentation Resources       |

To find new and changed topics for features that are available in the Preview release in Salesforce Help, see [New and Changed in the Upcoming Release](https://help.salesforce.com/s/articleView?id=cc.b2c_new_and_changed_in_upcoming_release.htm&language=en_US&type=5).
To find new and changed topics for features that are available in the Preview release in Agentforce Commerce Developer Center, see [New and Changed in the Upcoming Release](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-new-and-changed-in-upcoming-release.html).

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=2a421ff78d60bd53371553dcb0413100fc4b4d7982a5e7b4ce6e84a32915999b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_lakehouse_schema.md -->

# B2C Commerce Data Warehouse Schema Reference

The JDBC Driver can directly access the B2C Commerce data wareehouse schema. This section describes the various tables (dimensions and facts) and their constituent columns, using only their assigned aliases.

- [Schema Conventions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_schema_conventions.md)
- [Dimension Tables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_dimension_tables.md)
- [Fact Tables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_fact_tables.md)
- [Aggregate Tables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_aggregate_tables.md)

<!-- document id=192025d41fc7e6afec9eac83e7b5f0b072e18edd63623d48cbb14736c0aa5d5d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/b2c-legacy.md -->

# B2C Commerce Developer Documentation Resources (Script API)

Use this documentation to learn about APIs for creating custom ecommerce experiences.

- [B2C Commerce Script API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html)
- [B2C Commerce Pipelet API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/pipeletapi/html/index.html)
- [B2C Commerce Job Steps API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/jobstepapi/html/index.html)
- [API and Object Quotas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/)
- [B2C Commerce Import and Export Schemas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/xsd/)
- [B2C Commerce Content JSON Schemas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/content/)
- [Legacy Developer Documentation (PDF)](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/LegacyDeveloperDocumentation.pdf)
- [Script Debugger API (SDAPI)](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/sdapi_2_0.pdf)
- [Storefront Reference Architecture (SFRA) JavaScript](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/sfrajsdoc/)

API Limits:

- [API Quotas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/API_Quotas.html)
- [Object Quotas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/Object_Quotas.html)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)
- [B2C Commerce Storefront Options](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/which-product.md)
- [B2C Commerce API Documentation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/api-doc.md)
- [Determine Deprecated API Usage](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-customize-business-manager.md#determine-deprecated-api-usage)

<!-- document id=abf93a5bdf078cca0d85a9299f03a638e30546ce8c11fa650122210aebdf6b1c url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ods-rest-api.md -->

B2C Commerce Developer Sandbox REST API

# B2C Commerce Developer Sandbox REST API

B2C Commerce provides a REST API to manage developer sandboxes. The API allows you to create, manage, and delete developer sandboxes.

**Version:** 1.0

## Servers

*   `https://admin.dx.commercecloud.salesforce.com/api/v1`

Protocols: https.

## Security

*   `AccountManager` (oauth2) Authenticate using Commerce Cloud Account Manager with your SSO credentials.
    *   OAuth flow implicit (authorizationUrl: https://account.demandware.com:443/dwsso/oauth2/authorize)
*   `ClientCredentials` (oauth2) Authenticate using Commerce Cloud Account Manager with your client credentials.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)

## Tags

### Common

General purpose API endpoints.

### Realms

Operations on the realm level.

### Sandboxes

Operations on the sandbox level.

## Operations

### GET Retrieve API information.

`GET /`

Operation ID: `getApiInfo`. Tags: Common.

Return API version information.

#### Responses

*   **200** API version information.
    
    Media type: `application/json`. Schema: `ApiVersionResponse`.
    

### GET Retrieve user information.

`GET /me`

Operation ID: `getUserInfo`. Tags: Common. Security: AccountManager; ClientCredentials.

Return information about the user interacting with the API.

#### Responses

*   **200** Metadata about the authenticated API user.
    
    Media type: `application/json`. Schema: `UserInfoResponse`.
    

### GET Retrieve system information

`GET /system`

Operation ID: `getSystemInfo`. Tags: Common. Security: AccountManager; ClientCredentials.

Returns information about the system, the user is interacting with.

#### Responses

*   **200** Metadata about the system
    
    Media type: `application/json`. Schema: `SystemInfoResponse`.
    

### GET Retrieve system information

`GET /realms/{realm}/system`

Operation ID: `getRealmSystemInfo`. Tags: Common. Security: AccountManager; ClientCredentials.

Returns information about the system, the user is interacting with.

#### Parameters

*   `realm` (path, string, required) The four-letter ID of the realm.

#### Responses

*   **200** Metadata about the system
    
    Media type: `application/json`. Schema: `SystemInfoResponse`.
    

### GET Show realm information.

`GET /realms/{realm}`

Operation ID: `getRealm`. Tags: Realms. Security: AccountManager; ClientCredentials.

Return metadata about a realm.

#### Parameters

*   `realm` (path, string, required) The four-letter ID of the realm.
*   `expand` (query, array of string) Additional information, which should be shown in the realm query. Available options are: \[configuration,usage\].  
    Items: Allowed values: `configuration`, `usage`.

#### Responses

*   **200** Realm metadata.
    
    Media type: `application/json`. Schema: `RealmResponse`.
    
*   **400** The ID is not a valid realm ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **401** The user isn't authenticated.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Show realm configuration.

`GET /realms/{realm}/configuration`

Operation ID: `getRealmConfiguration`. Tags: Realms. Security: AccountManager; ClientCredentials.

Return the current configuration values of the realm.

#### Parameters

*   `realm` (path, string, required) The four-letter ID of the realm.

#### Responses

*   **200** Current configuration values of the realm.
    
    Media type: `application/json`. Schema: `RealmConfigurationResponse`.
    
*   **400** The ID isn't valid or the configuration isn't valid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to that realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### PATCH Update realm configuration.

`PATCH /realms/{realm}/configuration`

Operation ID: `patchRealmConfiguration`. Tags: Realms. Security: AccountManager; ClientCredentials.

Update the customizable configuration of a realm. Note that the internal time format in weekday schedules is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times).

#### Parameters

*   `realm` (path, string, required) The four-letter ID of the realm.

#### Request body (required)

Realm values to update.

Media type: `application/json`. Schema: `RealmConfigurationUpdateRequestModel`.

#### Responses

*   **200** Updated realm configuration data.
    
    Media type: `application/json`. Schema: `RealmConfigurationResponse`.
    
*   **400** The ID isn't a valid realm ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **401** The user isn't authenticated.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to that realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Show usage information for realm.

`GET /realms/{realm}/usage`

Operation ID: `getRealmUsage`. Tags: Realms. Security: AccountManager; ClientCredentials.

Return information about the realm's usage.

#### Parameters

*   `realm` (path, string, required) The four-letter ID of the realm.
*   `from` (query, string (date)) Earliest date for which data is in the response. Thirty days in the past by default. Format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
*   `to` (query, string (date)) Latest date for which data is included in the response. Today's date by default. Format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
*   `detailedReport` (query, boolean) Field to check whether detailed report is to be retrieved, by default detailed report will not be pulled  
    Allowed values: `false`, `true`. Default: `false`.

#### Responses

*   **200** Realm's usage information.
    
    Media type: `application/json, text/csv`. Schema: `RealmUsageResponse`.
    
*   **400** The ID isn't valid.
    
    Media type: `application/json, text/csv`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the realm.
    
    Media type: `application/json, text/csv`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json, text/csv`. Schema: `ErrorResponse`.
    

### POST Show usage information for given realms.

`POST /realms/usages`

Operation ID: `searchRealmUsage`. Tags: Realms. Security: AccountManager; ClientCredentials.

Update the customizable configuration of a realm. Note that the internal time format in weekday schedules is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times).

#### Request body (required)

Return information for given all realm's usage

Media type: `application/json`. Schema: `MultiRealmUsageRequest`.

#### Responses

*   **200** Aggregates all realm usage data.
    
    Media type: `application/json, text/csv`. Schema: `MultiRealmUsageResponse`.
    
*   **400** The ID isn't a valid realm ID.
    
    Media type: `application/json, text/csv`. Schema: `ErrorResponse`.
    
*   **401** The user isn't authenticated.
    
    Media type: `application/json, text/csv`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to that realm.
    
    Media type: `application/json, text/csv`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json, text/csv`. Schema: `ErrorResponse`.
    

### GET List sandboxes.

`GET /sandboxes`

Operation ID: `getSandboxes`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Return all sandboxes of a realm.

#### Parameters

*   `include_deleted` (query, boolean) If set, return deleted sandboxes.
*   `filter_params` (query, string) If passed in supported format, returns sandboxes that matches the query. Supported format: state=active&resourceProfile=medium&createdBy=user1&tags=\[tag1,tag2,tag3\].

#### Responses

*   **200** List of sandboxes.
    
    Media type: `application/json`. Schema: `SandboxListResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to that realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### POST Create sandbox.

`POST /sandboxes`

Operation ID: `createSandbox`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Create a new sandbox within the realm.

#### Request body (required)

Metadata about the new sandbox.

Media type: `application/json`. Schema: `SandboxProvisioningRequestModel`.

#### Responses

*   **201** The sandbox creation has started.
    
    Headers:
    
    *   `Location` (string) URI of the created sandbox.
    
    Media type: `application/json`. Schema: `SandboxResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **500** There were server errors initiating the sandbox deployment.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Retrieve sandbox information.

`GET /sandboxes/{sandboxId}`

Operation ID: `getSandbox`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Return details on a specific sandbox in a realm.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Responses

*   **200** Details on the sandbox (including its state).
    
    Media type: `application/json`. Schema: `SandboxResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the requested realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any realm with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### DELETE Delete sandbox.

`DELETE /sandboxes/{sandboxId}`

Operation ID: `deleteSandbox`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Delete a specific sandbox in a realm.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Responses

*   **202** The request for deleting the sandbox has been accepted by the API server. This doesn't mean that the sandbox has already been deleted, since the actual deletion process does not necessarily start immediately and might take a while. You can track the deletion process using sandbox GET requests.
    
    Media type: `application/json`. Schema: `StatusResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to that realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** ID not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### PATCH Update sandbox.

`PATCH /sandboxes/{sandboxId}`

Operation ID: `patchSandbox`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Update a sandbox.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Request body (required)

Sandbox values to update.

Media type: `application/json`. Schema: `SandboxUpdateRequestModel`.

#### Responses

*   **200** Updated details on the sandbox (including its state).
    
    Media type: `application/json`. Schema: `SandboxResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the realm.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Read all sandbox aliases

`GET /sandboxes/{sandboxId}/aliases`

Operation ID: `getAliases`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Retrieve a list of all past and present operations on a sandbox within the realm.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Responses

*   **200** List of Alias configurations.
    
    Media type: `application/json`. Schema: `SandboxAliasListResponse`.
    
*   **403** The user doesn't have access to the realm or sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### POST Create sandbox alias.

`POST /sandboxes/{sandboxId}/aliases`

Operation ID: `createAlias`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Create a new sandbox alias.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Request body (required)

The alias for the sandbox

Media type: `application/json`. Schema: `SandboxAliasModel`.

#### Responses

*   **200** The sandbox alias already exists.
    
    Media type: `application/json`. Schema: `SandboxAliasResponse`.
    
*   **201** The alias has been created.
    
    Media type: `application/json`. Schema: `SandboxAliasResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Read Alias configuration

`GET /sandboxes/{sandboxId}/aliases/{sandboxAliasId}`

Operation ID: `getAlias`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Retrieves a dedicated alias for the sandbox. Can be called without authentication to get cookie values for the alias.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.
*   `sandboxAliasId` (path, string (uuid), required) The sandbox alias UUID.

#### Responses

*   **200** The Alias configuration.
    
    Media type: `application/json`. Schema: `SandboxAliasResponse`.
    
*   **403** The user doesn't have access to the realm or sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox or any alias with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### DELETE Delete Alias configuration

`DELETE /sandboxes/{sandboxId}/aliases/{sandboxAliasId}`

Operation ID: `deleteAlias`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Deletes a dedicated alias configuration for a sandbox.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.
*   `sandboxAliasId` (path, string (uuid), required) The sandbox alias UUID.

#### Responses

*   **202** Shows, that alias currently gets deleted.
    
    Media type: `application/json`. Schema: `StatusResponse`.
    
*   **403** The user doesn't have access to the realm or sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox or any alias with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET List sandbox operations.

`GET /sandboxes/{sandboxId}/operations`

Operation ID: `getSandboxOperations`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Retrieve a list of all past and present operations on a sandbox within the realm.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.
*   `from` (query, string (date)) Earliest date for which data is in the response. Thirty days in the past by default. Format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
*   `to` (query, string (date)) Latest date for which data is included in the response. Today's date by default. Format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
*   `operation_state` (query, string) State of operations included in the response. By default, all operations are included.  
    Allowed values: `pending`, `running`, `finished`.
*   `status` (query, string) Status of operations included in the response. By default, all operations are included.  
    Allowed values: `success`, `failure`.
*   `operation` (query, string) Type of operations included in the response. By default, all operations are included.  
    Allowed values: `start`, `stop`, `restart`, `reset`, `create`, `delete`, `upgrade`.
*   `sort_order` (query, string) Order of the list. Default value is ''asc''.  
    Allowed values: `asc`, `desc`.
*   `sort_by` (query, string) Field by which to order the list. By default, the list is not ordered.  
    Allowed values: `created`, `operation_state`, `status`, `operation`.
*   `page` (query, integer (int32)) The page to access in a paged response. Page numbers start with '0', which is the default value.  
    Minimum: 0.
*   `per_page` (query, integer (int32)) Count of elements on a page. The default value is '20'.  
    Minimum: 1.

#### Responses

*   **200** List of operations.
    
    Headers:
    
    *   `Link` (string) Paging metadata, as described in [RFC-5988](https://tools.ietf.org/html/rfc5988)
    *   `X-Pagination-Count` (integer (int32)) Total count of elements.
    *   `X-Pagination-Page` (integer (int32)) Current page index.
    *   `X-Pagination-Limit` (integer (int32)) Maximum count of pages.
    
    Media type: `application/json`. Schema: `SandboxOperationListResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **500** There were server errors during the operation.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### POST Run sandbox operation.

`POST /sandboxes/{sandboxId}/operations`

Operation ID: `createSandboxOperation`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Request an operation on a sandbox within the realm.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Request body (required)

Operation to be carried out on a sandbox.

Media type: `application/json`. Schema: `SandboxOperationRequestModel`.

#### Responses

*   **202** The operation has been accepted.
    
    Media type: `application/json`. Schema: `SandboxOperationResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox with that ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **422** The operation isn't allowed in the current state of the sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **500** There were server errors during the operation.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Retrieve sandbox operation.

`GET /sandboxes/{sandboxId}/operations/{operationId}`

Operation ID: `getSandboxOperation`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Return details of a sandbox operation that was recently submitted, is currently in progress, or has already finished.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.
*   `operationId` (path, string (uuid), required) The operation UUID.

#### Responses

*   **200** Details of the sandbox operation's state and the state of its target. If the operation has already finished, indicates whether the operation was successful.
    
    Media type: `application/json`. Schema: `SandboxOperationResponse`.
    
*   **400** The request parameters are invalid (bad request).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the requested operation or sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox or realm matching the given parameters.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Show sandbox settings.

`GET /sandboxes/{sandboxId}/settings`

Operation ID: `getSandboxSettings`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Return all settings of the sandbox.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Responses

*   **200** Details of the sandbox settings.
    
    Media type: `application/json`. Schema: `SandboxSettingsResponse`.
    
*   **400** The sandbox ID isn't valid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the requested sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox matching the ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Show sandbox usage.

`GET /sandboxes/{sandboxId}/usage`

Operation ID: `getSandboxUsage`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Return information on sandbox usage.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.
*   `from` (query, string (date)) Earliest date for which data is in the response. Thirty days in the past by default. Format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
*   `to` (query, string (date)) Latest date for which data is included in the response. Today's date by default. Format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).

#### Responses

*   **200** Sandbox usage information.
    
    Media type: `application/json`. Schema: `SandboxUsageResponse`.
    
*   **400** The sandbox ID isn't valid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the requested sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox matching the ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Show sandbox storage

`GET /sandboxes/{sandboxId}/storage`

Operation ID: `getSandboxStorage`. Tags: Sandboxes. Security: AccountManager; ClientCredentials.

Return information on sandbox storage capacity for a currently running sandbox.

#### Parameters

*   `sandboxId` (path, string (uuid), required) The sandbox UUID.

#### Responses

*   **200** Sandbox storage information.
    
    Media type: `application/json`. Schema: `SandboxStorageResponse`.
    
*   **400** The sandbox ID isn't valid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **403** The user doesn't have access to the requested sandbox.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404** There isn't any sandbox matching the ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

## Schemas

### ApiVersionResponse

Includes all fields of `StatusResponse`.

*   `data` (_ApiVersion_)

### UserInfoResponse

Includes all fields of `StatusResponse`.

*   `data` (_UserInfoSpec_)

### SystemInfoResponse

Includes all fields of `StatusResponse`.

*   `data` (_SystemInfoSpec_)

### RealmResponse

Includes all fields of `StatusResponse`.

*   `data` (_RealmModel_)

### ErrorResponse

Includes all fields of `StatusResponse`.

*   `error` (_ErrorModel_)

### RealmConfigurationResponse

Includes all fields of `StatusResponse`.

*   `data` (_RealmConfigurationModel_)

### RealmConfigurationUpdateRequestModel

*   `emails` (_array of string_)  
    Items: Pattern: (.+)@(.+).
    
    _Example_
    
    ```
    [
      "email1@example.com",
      "email2@example.com"
    ]
    ```
    
*   `sandbox` (_RealmSandboxConfigurationUpdateModel_)

### RealmUsageResponse

Includes all fields of `StatusResponse`.

*   `data` (_RealmUsageModel_)

### MultiRealmUsageRequest

*   `from` (_string (date)_) Time the sandbox was started.
*   `to` (_string (date)_) Time the sandbox was stopped. If the sandbox is still running, this value will not exist for the last block.
*   `realms` (_array of string_)
*   `detailedReport` (_boolean_) Field to check whether detailed report is to be retrieved, by default detailed report will not be pulled.  
    Allowed values: `false`, `true`. Default: `false`.

### MultiRealmUsageResponse

Includes all fields of `StatusResponse`.

*   `data` (_array of MultiRealmUsageModel_)

### SandboxListResponse

Includes all fields of `StatusResponse`.

*   `data` (_array of SandboxModel_)

### SandboxProvisioningRequestModel

*   `realm` (_string_, required)
*   `emails` (_array of string_)  
    Items: Pattern: (.+)@(.+).
*   `ttl` (_integer (int32)_) Number of hours the sandbox will live (must adhere to the maximum TTL quotas). If set to 0 or less, the sandbox will have an infinite lifetime.
*   `autoScheduled` (_boolean_) Defaults to false. If set to true, the sandbox is covered by automatic start/stop actions, which can be set to a dedicated time via realm- configuration API.
*   `tags` (_array of string_)
*   `startScheduler` (_any_, nullable)
*   `stopScheduler` (_any_, nullable)
*   `resourceProfile` (_SandboxResourceProfile_)
*   `settings` (_SandboxSettings_)

_Example_

```
{
  "realm": "<your realm id>",
  "emails": [
    "email1@example.com",
    "email2@example.com"
  ],
  "ttl": 24,
  "autoScheduled": false,
  "tags": [
    "<your-custom-tag>"
  ],
  "startScheduler": {
    "weekdays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY"
    ],
    "time": "08:00:00+03:00"
  },
  "stopScheduler": {
    "weekdays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY"
    ],
    "time": "19:00:00Z"
  },
  "resourceProfile": "medium",
  "settings": {
    "ocapi": [
      {
        "client_id": "<your client id>",
        "resources": [
          {
            "resource_id": "/**",
            "methods": [
              "get",
              "post",
              "put",
              "patch",
              "delete"
            ],
            "read_attributes": "(**)",
            "write_attributes": ""
          }
        ]
      }
    ],
    "webdav": [
      {
        "client_id": "<your client id>",
        "permissions": [
          {
            "path": "/cartridges",
            "operations": [
              "read_write"
            ]
          },
          {
            "path": "/impex",
            "operations": [
              "read_write"
            ]
          }
        ]
      }
    ]
  }
}
```

### SandboxResponse

Includes all fields of `StatusResponse`.

*   `data` (_SandboxModel_)

### StatusResponse

Includes all fields of `Response`.

*   `status` (_string_, required) String with value 'Success' or 'Failure' to indicate request outcome.  
    Allowed values: `Success`, `Failure`.

### SandboxUpdateRequestModel

*   `emails` (_array of string_)  
    Items: Pattern: (.+)@(.+).
*   `ttl` (_integer (int32)_) Number of hours added to the sandbox lifetime (must, together with previous extensions, adhere to the maximum TTL configuration). If set to 0 or less, the sandbox will have an infinite lifetime.
*   `autoScheduled` (_boolean_) If set to true, this sandbox will be captured by automated start-/stop -management.
*   `tags` (_array of string_)
*   `startScheduler` (_any_, nullable)
*   `stopScheduler` (_any_, nullable)

_Example_

```
{
  "emails": [
    "email1@example.com",
    "email2@example.com"
  ],
  "ttl": null,
  "autoScheduled": false,
  "tags": [
    "<your-custom-tag>"
  ],
  "startScheduler": {
    "weekdays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY"
    ],
    "time": "08:00:00+03:00"
  },
  "stopScheduler": {
    "weekdays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY"
    ],
    "time": "19:00:00Z"
  }
}
```

### SandboxAliasListResponse

Includes all fields of `StatusResponse`.

*   `data` (_array of SandboxAliasModel_)

### SandboxAliasModel

*   `id` (_string (uuid)_, read-only) The sandbox alias UUID.
*   `name` (_string_, required) The alias name.  
    Example: `www.example.com`.
*   `unique` (_boolean_) Define if it's a unique configuration  
    Example: `false`.
*   `requestLetsEncryptCertificate` (_boolean_) Request a valid certificate to be generated on the fly through Lets Encrypt. This action consumes certificate requests from the domain quota imposed by Let's Encrypt, please read the Alias documentation carefully.  
    Example: `false`.
*   `sandboxId` (_string (uuid)_, read-only) The UUID of the sandbox the sandbox alias is pointing to.
*   `cookie` (_object_, read-only) The cookie required for each request to this alias.
    *   `name` (_string_, required)
    *   `value` (_string_, required)
    *   `path` (_string_)
    *   `domain` (_string_)
*   `registration` (_string_, read-only) The link that can be used to save the required cookie for this alias in the browser.
*   `domainVerificationRecord` (_string_, read-only) The verification code to be added as TXT record in the DNS
*   `status` (_string_, read-only) The status of the alias creation process  
    Allowed values: `pending`, `verified`.

### SandboxAliasResponse

Includes all fields of `StatusResponse`.

*   `data` (_SandboxAliasModel_)

### SandboxOperationListResponse

Includes all fields of `PagedResponse`.

*   `data` (_array of SandboxOperationModel_)

### SandboxOperationRequestModel

*   `operation` (_string_, required)  
    Allowed values: `start`, `stop`, `restart`, `reset`.

### SandboxOperationResponse

Includes all fields of `StatusResponse`.

*   `data` (_SandboxOperationModel_)

### SandboxSettingsResponse

Includes all fields of `StatusResponse`.

*   `data` (_SandboxSettings_)

### SandboxUsageResponse

Includes all fields of `StatusResponse`.

*   `data` (_SandboxUsageModel_)

### SandboxStorageResponse

Includes all fields of `StatusResponse`.

*   `data` (_SandboxStorageModel_)

### ApiVersion

*   `version` (_string_)  
    Allowed values: `v1`.
*   `git` (_object_)
    *   `commit` (_string_)
    *   `time` (_string (date-time)_)
*   `build` (_object_)
    *   `version` (_string_)
    *   `time` (_string (date-time)_)

### UserInfoSpec

*   `user` (_object_)
    *   `id` (_string_) User's unique ID on Account Manager.
    *   `email` (_string_) User's email address.
    *   `name` (_string_) User's human-readable, full name.
*   `client` (_object_)
    *   `id` (_string_) OAuth client ID used to retrieve the access token.
*   `roles` (_array of string_) User's roles as returned by Account Manager.
*   `realms` (_array of string_) Realms that the user is allowed to access. All sandboxes within these realms are accessible.
*   `sandboxes` (_array of string_) Sandboxes that the user is allowed to access.

### SystemInfoSpec

*   `region` (_string_) The region, the system is deployed on.
*   `systemIps` (_array of string_) Public IP addresses of internal services like API server
*   `sandboxIps` (_array of string_) Public IP addresses of all sandboxes
*   `inboundIps` (_array of string_) IP addresses for incoming traffic.
*   `outboundIps` (_array of string_) IP addresses for outgoing traffic.

### RealmModel

*   `id` (_string_, required) GUID of the realm in the system.
*   `name` (_string_) Human-readable four-letter ID of the realm.
*   `enabled` (_boolean_) Flag indicating whether the realm is enabled for any operations.
*   `usage` (_RealmUsageSummaryModel_)
*   `configuration` (_RealmConfigurationModel_)

### ErrorModel

*   `status` (_string_, required) String with value 'Success' or 'Failure' to indicate request outcome.  
    Allowed values: `Success`, `Failure`.
*   `message` (_string_) Human-readable description of the error.
*   `reason` (_string_) Machine-readable, one-word, CamelCase description of why the operation failed. If this value is empty, there is no information available. The reason clarifies an HTTP status code but does not override it.
*   `details` (_object_) Extended data associated with the reason. Each reason can define its own extended details. This field is optional, and the data returned is not guaranteed to conform to any schema except that defined by the reason type.
    
    Additional properties: `string`.
    

### RealmConfigurationModel

*   `emails` (_array of string_)  
    Items: Pattern: (.+)@(.+).
    
    _Example_
    
    ```
    [
      "email1@example.com",
      "email2@example.com"
    ]
    ```
    
*   `sandbox` (_RealmSandboxConfigurationModel_)
*   `requests` (_RealmRequestConfigurationModel_)
*   `startScheduler` (_WeekdaySchedule_)
*   `stopScheduler` (_WeekdaySchedule_)

### RealmSandboxConfigurationUpdateModel

Update data for configuration data related to sandboxes of a realm. The time formats within the weekday schedules have to be passed in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times) format.

*   `sandboxTTL` (_ConfigurationIntegerValue_)
*   `startScheduler` (_any_, nullable)
*   `stopScheduler` (_any_, nullable)

_Example_

```
{
  "sandboxTTL": {
    "maximum": 240,
    "defaultValue": 24
  },
  "startScheduler": {
    "weekdays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY"
    ],
    "time": "08:00:00+03:00"
  },
  "stopScheduler": {
    "weekdays": [
      "MONDAY",
      "TUESDAY",
      "WEDNESDAY",
      "THURSDAY",
      "FRIDAY"
    ],
    "time": "19:00:00Z"
  }
}
```

### RealmUsageModel

*   `id` (_string_, required) GUID of the realm in the system.
*   `createdSandboxes` (_integer (int64)_) Total number of sandboxes created during the requested timeframe (by default, the previous 30 days).  
    Example: `93`.
*   `activeSandboxes` (_integer (int64)_) Total number of sandboxes active during the requested timeframe (by default, the previous 30 days).  
    Example: `128`.
*   `deletedSandboxes` (_integer (int64)_) Total number of sandboxes deleted during the requested timeframe (by default, the previous 30 days).  
    Example: `86`.
*   `sandboxSeconds` (_integer (int64)_) Total number of seconds sandboxes ran during the requested timeframe (by default, the previous 30 days).  
    Example: `360000`.
*   `minutesUpByProfile` (_array of object_)
    *   `profile` (_SandboxResourceProfile_)
    *   `minutes` (_integer (int64)_) How many minutes sandboxes of this profile type were running during the report timeframe.
*   `minutesUp` (_integer (int64)_) Sum of minutes sandboxes in this realm were running during the requested timeframe (by default, the previous 30 days).  
    Example: `360000`.
*   `minutesDown` (_integer (int64)_) Sum of minutes sandboxes in this realm were not running during the requested timeframe (by default, the previous 30 days).  
    Example: `180000`.
*   `sandboxDetails` (_array of SandboxInfo_)

### MultiRealmUsageModel

*   `realmName` (_string_, required) GUID of the realm in the system.
*   `realmUsage` (_RealmUsageModel_)
*   `error` (_string_) Error while getting usage.

### SandboxModel

*   `id` (_string_)
*   `realm` (_string_)
*   `emails` (_array of string_)  
    Items: Pattern: (.+)@(.+).
*   `instance` (_string_)
*   `versions` (_object_)
    
    SandboxModelVersions
    
    Versions of the components that make up the sandbox.
    
    *   `app` (_string_) Version of the commerce application.  
        Pattern: \\d(\\.\\d)\*.
    *   `web` (_string_) Version of the web proxy.  
        Pattern: \\d(\\.\\d)\*.
*   `autoScheduled` (_boolean_) Defaults to false. If set to true, the sandbox is covered by automatic start/stop actions, which can be set to a dedicated time via realm- configuration API.
*   `resourceProfile` (_SandboxResourceProfile_)
*   `state` (_SandboxState_)
*   `createdAt` (_string (date-time)_)
*   `createdBy` (_string_)
*   `deletedAt` (_string (date-time)_) Time when the delete operation was created.
*   `deletedBy` (_string_) User who requested the sandbox deletion.
*   `eol` (_string (date-time)_)
*   `tags` (_array of string_)
*   `hostName` (_string_)
*   `links` (_object_) Set of named links for accessing the sandbox.
    *   `bm` (_string_) Fully qualified URL of the sandbox Business Manager web app.
    *   `ocapi` (_string_) Fully qualified URL of OCAPI data API (excluding version selector).
    *   `impex` (_string_) Fully qualified WebDAV URL for accessing import and export files.
    *   `code` (_string_) Fully qualified WebDAV URL for accessing code.
    *   `logs` (_string_) Fully qualified WebDAV URL for accessing log files.
*   `startScheduler` (_WeekdaySchedule_)
*   `stopScheduler` (_WeekdaySchedule_)

### SandboxResourceProfile

Determines the resource allocation for the sandbox, "medium" is the default. Be careful, more powerful profiles consume more credits.

Type: `string`.

Allowed values: `medium`, `large`, `xlarge`.

### SandboxSettings

Map of additional settings evaluated when the sandbox is provisioned and initialized.

*   `ocapi` (_OcapiSettings_)
*   `webdav` (_WebDavSettings_)

### Response

*   `kind` (_string_, required) Type of response object.  
    Allowed values: `ApiVersion`, `UserInfo`, `SystemInfo`, `Realm`, `RealmConfiguration`, `RealmUsage`, `Sandbox`, `SandboxList`, `SandboxAlias`, `SandboxAliasList`, `SandboxSettings`, `SandboxUsage`, `SandboxStorage`, `SandboxOperationList`, `Status`.
*   `code` (_integer (int32)_, required) Response code sent along with the status.

### PagedResponse

Includes all fields of `StatusResponse`.

*   `metadata` (_PagingMetadata_)

### SandboxOperationModel

*   `id` (_string_, required)
*   `operation` (_string_, required)  
    Allowed values: `start`, `stop`, `restart`, `reset`, `create`, `delete`, `upgrade`.
*   `createdAt` (_string (date-time)_)
*   `operationState` (_string_, required)  
    Allowed values: `pending`, `running`, `finished`.
*   `sandboxState` (_SandboxState_)
*   `status` (_string_) Indicates whether the operation finished successfully ('Success') or not ('Failure').  
    Allowed values: `success`, `failure`.

### SandboxUsageModel

*   `id` (_string_, required)
*   `sandboxSeconds` (_integer (int64)_) Total number of seconds during which the sandbox ran.
*   `minutesUp` (_integer (int64)_) Sum of minutes sandboxes in this realm were running during the requested timeframe (by default, the previous 30 days).  
    Example: `360000`.
*   `minutesDown` (_integer (int64)_) Sum of minutes sandboxes in this realm were not running during the requested timeframe (by default, the previous 30 days).  
    Example: `180000`.
*   `history` (_array of object_) List of blocks, which describe the separate uptimes of a sandbox
    *   `from` (_string (date-time)_, required) Time the sandbox was started.
    *   `to` (_string (date-time)_) Time the sandbox was stopped. If the sandbox is still running, this value will not exist for the last block.
    *   `sandboxSeconds` (_integer (int64)_) Number of seconds that the sandbox was running for this block.
    *   `resourceProfile` (_SandboxResourceProfile_)
    *   `exceedsTimeframe` (_boolean_) This property is set to true if the block exceeds the given timeframe and was therefore trimmed.
    *   `clusterName` (_string_) Cluster where sandbox resides.

### SandboxStorageModel

Shows all filesystem storages and how much space is left on them.

Additional properties: `StorageUsageModel`.

### RealmUsageSummaryModel

*   `activeSandboxes` (_integer (int64)_, required) Number of currently active sandboxes for a realm.  
    Example: `42`.

### RealmSandboxConfigurationModel

Configuration object related to sandboxes of a realm.

*   `limitsEnabled` (_boolean_, required) Flag indicating whether sandbox specific limits are enforced for the realm.
*   `totalNumberOfSandboxes` (_integer_, required) Total number of sandboxes (regardless of state) that the realm can hold.
*   `sandboxTTL` (_ConfigurationIntegerValue_, required)
*   `localUsersAllowed` (_boolean_, required) Flag indicating whether users outside the Account Manager are allowed.

_Example_

```
{
  "limitsEnabled": true,
  "totalNumberOfSandboxes": 50,
  "sandboxTTL": {
    "maximum": 240,
    "defaultValue": 8
  },
  "localUsersAllowed": false
}
```

### RealmRequestConfigurationModel

Configuration object related to requests targeting the sandboxes of a realm.

*   `enforced` (_boolean_, required) If enabled, rate limiting is active.
*   `maxRate` (_integer_) Maximum requests allowed per time period.
*   `timePeriod` (_integer_) Number of seconds during which to count requests.

_Example_

```
{
  "enforced": true,
  "maxRate": 50000,
  "timePeriod": 60
}
```

### WeekdaySchedule

A schedule definition for a dedicated time on specific weekdays.

*   `weekdays` (_array of string_) List of weekdays, where the action should take place  
    Items: Allowed values: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.
*   `time` (_string_) Time (with timezone) where the action should take place on the specified weekdays. Time format is [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Times). If no time zone is given, the timezone defaults to GMT.  
    Example: `20:10:00Z`.

### ConfigurationIntegerValue

Object that holds an integer-based configuration property. A zero value means "unlimited".

*   `fixedValue` (_integer (int32)_) Fixed value for this configuration property. You can't use this along with a maximum or default value.
*   `maximum` (_integer (int32)_) Maximum value for this property.
*   `defaultValue` (_integer (int32)_) Default value for this property.

### SandboxInfo

*   `realm` (_string_)
*   `resourceProfile` (_SandboxResourceProfile_)
*   `createdAt` (_string (date-time)_)
*   `deletedAt` (_string (date-time)_) Time when the delete operation was created.
*   `name` (_string_) Name of the sandbox
*   `instanceId` (_string_) instanceId of the sandbox
*   `minutesUp` (_integer (int64)_) Minutes sandbox in this realm was running during the requested timeframe (by default, the previous 30 days).  
    Example: `360000`.
*   `minutesDown` (_integer (int64)_) Minutes sandbox in this realm was not running during the requested timeframe (by default, the previous 30 days).  
    Example: `180000`.
*   `autoScheduled` (_boolean_) Defaults to false. If set to true, the sandbox is covered by automatic start/stop actions, which can be set to a dedicated time via realm- configuration API.:
*   `startScheduler` (_WeekdaySchedule_)
*   `stopScheduler` (_WeekdaySchedule_)
*   `clusterName` (_string_) Cluster where sandbox resides.

### SandboxState

Type: `string`.

Allowed values: `new`, `creating`, `starting`, `started`, `stopping`, `stopped`, `deleting`, `deleted`, `resetting`, `failed`, `unknown`, `upgrading`.

### OcapiSettings

Use this document to configure Open Commerce API permissions for multiple client applications in the context of a single site.

Array of `object`.

Each item: Describes Open Commerce API permissions for a client application.

Minimum items: 1.

Describes Open Commerce API permissions for a client application.

*   `client_id` (_string (uuid)_, required) Client application ID.
*   `resources` (_array of object_) Array of resource-specific permission documents.
    
    Each item: Configures resource specific permissions and settings.
    
    *   `methods` (_array of string_, required) Open Commerce API HTTP method filter. For example, the filter \["get","patch"\] allows access to the GET and PATCH methods for the specified resource path. You can specify methods that are supported for a resource. You can list all available resources and methods for the Shop API, version 18.1, with the following meta data call: http://{your-domain}/dw/meta/rest/shop/v18\_1?client\_id={your-client-id}  
        Items: Allowed values: `get`, `delete`, `patch`, `post`, `put`.
    *   `read_attributes` (_string_) String that controls which properties are included in the response document. The configuration value must be specified using property selection syntax.
    *   `write_attributes` (_string_) String that controls which properties can be included in the request document. The configuration value must be specified using property selection syntax.
    *   `resource_id` (_string_, required) OCAPI resource identifier. For example: /products/\*/images or /products/specific\_id/images. This property supports Ant path style to describe resource IDs. You can specify wildcards or specific product IDs; you can also specify the pattern /products/\*\* to access to all available sub-resources. You can list all resource identifiers for the Shop API, version 18.1, with the following meta data call: http://{your-domain}/dw/meta/rest/shop/v18\_1?client\_id={your-client-id}
    *   `version_range` (_array of object_) Version range documents granting permissions only to a subset of OCAPI versions.
        
        Each item: Use this document to grant resource permissions only to a subset of Open Commerce API versions. You can use the properties from and until to define the range. At least one of both must be specified.
        
        *   `from` (_string_) From version (for example, 18.1). If you don't specify the from version, all versions including the oldest are accessible.
        *   `until` (_string_) Until version (for example, 18.1). The until version is exclusive, which means that it is not part of the range. If you don't specify the until version, all versions including the most recent one are accessible.

### WebDavSettings

WebDAV settings contain WebDAV client permissions for multiple client applications in the context of your organization. WebDAV client permissions enable you to configure which API clients can access your WebDAV files. These permissions also give you fine-grained control over which directories each client can access.

Array of `object`.

Each item: An array of client-specific permission documents.

Minimum items: 1.

An array of client-specific permission documents.

*   `client_id` (_string (uuid)_, required) Client ID indicating the API client for which the permissions are configured.
*   `permissions` (_array of object_, required) Array of directory-based permissions documents. Multiple permissions paths cannot intersect each other; for example, the following two paths intersect and are therefore invalid: /impex/src and /impex/src/foo.
    
    Each item: Use this document to configure WebDAV permissions.
    
    *   `path` (_string_, required) Directory for which the WebDAV permission is granted, including all subdirectories. File-specific permissions are not permitted.
    *   `operations` (_array of string_, required) Array of operations granted on this directory. Possible values are read and read\_write.  
        Items: Allowed values: `read`, `read_write`. Minimum items: 1.

### PagingMetadata

*   `page` (_integer (int32)_) Index of the current page.
*   `perPage` (_integer (int32)_) Maximum count of elements per page.
*   `pageCount` (_integer (int32)_) Total count of pages.
*   `totalCount` (_integer (int64)_) Total count of elements.
*   `links` (_PagingLinks_)

### StorageUsageModel

Represents a single filesystem storage unit with its available space.

*   `spaceTotal` (_integer (int64)_) Total available space in MB.
*   `spaceUsed` (_integer (int64)_) Used space in MB.
*   `percentageUsed` (_integer (int32)_) Used space in percent, compared to total space.

### PagingLinks

*   `self` (_string_) Relative link to this page.
*   `first` (_string_) Relative link to the first page.
*   `previous` (_string_) Relative link to the previous page. 'null' if the current page is the first page.
*   `next` (_string_) Relative link to the next page. 'null' if the current page is the last page.
*   `last` (_string_) Relative link to the last page.

<!-- document id=6b7db2cdad61edc3edb3611c8ac716903aea028af1721abfc70660b2d391b0e9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc_intro.md -->

# B2C Commerce Intelligence JDBC Driver

Use the B2C Commerce Intelligence JDBC driver to access comprehensive analytics data for the B2C Commerce Data Lakehouse. This section describes how to set up and use the JDBC driver and provides reference information for the B2C Commerce Data Lakehouse schema.

- [Setting Up the B2C Commerce Intelligence JDBC Driver](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc/jdbc_access_guide.md)
- [B2C Commerce Data Lakehouse Schema Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc/jdbc_lakehouse_schema.md)

<!-- document id=987f68fda6b0bd643d41c97ce651169cd1339ba87afd2495fb0d27c9238a1cc5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/about/b2c-api-doc.md -->

# B2C Commerce Platform API Specifications and Resources

You are currently viewing the OCAPI reference documentation. To view additional API specifications:

- <a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/" target="_blank" class="external-link-guide">B2C Commerce API (also known as Salesforce Commerce API or SCAPI)</a>
- <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/" target="_blank" class="external-link-guide">Composable Storefront API</a>
- [B2C Commerce Developer Resources (Script API)](https://salesforcecommercecloud.github.io/b2c-dev-doc/)
- <a href="https://developer.salesforce.com/docs/commerce/einstein-api/references/" target="_blank" class="external-link-guide">B2C Commerce Einstein API</a>

<!-- document id=7c8ee3b934104f841f36d5932f0a981a5875e2163552363f9a2c70bff38db26c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/quick-start-landing-page.md -->

# B2C Commerce Quick Start

Try out some basic steps for using a few of the B2C Commerce storefront options:

- [Agentic MCP  Shopper Tools Quick Start (Pilot)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/agentic-mcp-shopper-tools-quick-start.md)
- [Storefront Reference Architecture (SFRA) Getting Started](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture?tab=readme-ov-file#getting-started) (first get access to the [Private GitHub Repos](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-github-repo-access.md#accessing-private-github-repos))
- [Composable Storefront Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.html)
- [B2C Commerce API and SDK Quick Start](https://developer.salesforce.com/docs/commerce/commerce-api/guide/api-and-sdk-demo.html)

### See Also

- [B2C Commerce Storefront Options](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/which-product.md)
- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=f087c53989c51980686de065a4f2d2284c417a12182fb348d1c7b80121cfd0ea url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/b2c-new-and-changed-in-upcoming-release.md -->

# B2C Commerce Release Notes

Stay informed about new features in B2C Commerce, B2C Commerce API, Storefront Next, Managed Runtime, Composable Storefront, Storefront Reference Architecture (SFRA), and more.

- [B2C Commerce Release Notes](https://help.salesforce.com/s/articleView?id=commerce.b2c_parent.htm&type=5).
- [B2C Commerce API Release Notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)
- [Storefront Next Release Notes](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-release-notes.html)
- [Managed Runtime Release Notes](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-release-notes.html)
- [Composable Storefront Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html)

For summaries of new Commerce features in each Salesforce release, check out the release highlights in [Prepare for Salesforce Releases](https://trailhead.salesforce.com/content/learn/trails/sf_release_prep).

If there are new developer topics in the upcoming release, or modified developer topics with significant customer impact, view them in [New and Changed Help Topics in the Upcoming Release](https://help.salesforce.com/s/articleView?id=cc.b2c_new_and_changed_in_upcoming_release.htm&type=5).

<!-- document id=f7a8b9a2e149afc699dbe4d9d5c01d38aa26ba5a397a0122872c87811013bb8a url=/developer/current/en-us/commerce-cloud/script-api/references/current/index.md -->

# B2C Commerce Script API 26.8

## Packages

| Package                                                         | Description                                                                                                        |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [TopLevel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.md)                                         | Contains top-level language classes such as Array, Number and String.                                              |
| [dw.alert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.md)                                         | Contains classes for creating and managing system alerts for Business Manager users.                               |
| [dw.campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.md)                                   | Contains classes that allow you to interact with promotions and campaigns.                                         |
| [dw.catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.md)                                     | Contains classes that allow you to interact with Products.                                                         |
| [dw.commerceapps](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.md)                           | Contains classes for working with Commerce Apps, including connection health status.                               |
| [dw.commerceapps.hooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.hooks.md)               | Contains classes that participate in customization of Commerce Apps, such as connection health checks.             |
| [dw.content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.md)                                     | Contains classes that allow you to access content.                                                                 |
| [dw.crypto](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.md)                                       | Contains classes that allow you to perform cryptographic operations.                                               |
| [dw.customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.md)                                   | Contains classes that allow you to interact with and manage Customer-related information.                          |
| [dw.customer.consent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.md)                   | Contains classes that allow you to manage shopper marketing consent subscriptions.                                 |
| [dw.customer.oauth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.md)                       | Contains classes for OAuth authentication flows with third-party providers.                                        |
| [dw.customer.shoppercontext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.md)     | Contains classes for managing Shopper Context.                                                                     |
| [dw.experience](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.md)                               | Contains classes for Page Designer managed pages and components.                                                   |
| [dw.experience.cms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.md)                       | Contains classes for accessing Salesforce CMS records.                                                             |
| [dw.experience.image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.md)                   | Contains classes for image configuration and metadata.                                                             |
| [dw.extensions.applepay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.md)             | Contains classes that allow you to customize Apple Pay functionality.                                              |
| [dw.extensions.facebook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.md)             | Contains classes that allow you to customize Facebook functionality.                                               |
| [dw.extensions.paymentapi](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentapi.md)         | Contains extension points for customizing Payment API requests.                                                    |
| [dw.extensions.paymentrequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.md) | Contains classes that allow you to customize Payment Request functionality.                                        |
| [dw.extensions.payments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.md)             | Contains classes for use with Salesforce Payments functionality.                                                   |
| [dw.extensions.pinterest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.md)           | Contains classes that allow you to customize Pinterest functionality.                                              |
| [dw.io](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.md)                                               | Contains classes that allow you to perform file and I/O-related operations.                                        |
| [dw.job](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.md)                                             | Contains classes for job and step execution management.                                                            |
| [dw.net](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.md)                                             | Contains classes that allow you to perform FTP client, HTTP client and WebDAV-related operations.                  |
| [dw.object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.md)                                       | Contains classes that allow you to interact with custom objects and attributes.                                    |
| [dw.order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.md)                                         | Contains classes that allow you to perform order and payment-related operations.                                   |
| [dw.order.hooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.md)                             | Contains classes that participate in customization of Order processes.                                             |
| [dw.rpc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.md)                                             | Contains classes that allow you to perform web service-related operations.                                         |
| [dw.sitemap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.md)                                     | Contains classes for accessing and modifying custom sitemap files.                                                 |
| [dw.suggest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.md)                                     | Contains classes that allow you to interact with suggestions based on terms entered into storefront search fields. |
| [dw.svc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.md)                                             | Contains classes that allow you to define and execute remote services.                                             |
| [dw.system](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.md)                                       | Contains classes that allow you to access system objects such as logs and sites.                                   |
| [dw.template](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.md)                                   | Contains classes for rendering ISML and Velocity templates.                                                        |
| [dw.util](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.md)                                           | Contains classes that provide utility methods.                                                                     |
| [dw.value](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.md)                                         | Contains classes associated with values, such as Money and Quantity.                                               |
| [dw.web](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.md)                                             | Contains classes that allow you to perform HTTP-related operations.                                                |
| [dw.ws](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.md)                                               | Contains classes for SOAP-based web service operations.                                                            |

<!-- document id=ce507a647a3de511fc78a9fd31680357db73870aa61ff175f6f791238aaf7779 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/scriptprogramming/usingjavascriptmodules.md -->

# B2C Commerce Script Modules

Access JavaScript/B2C Commerce script modules within your storefront script code.

Starting in 13.6, B2C Commerce supports the [Modules 1.1.1](http://wiki.commonjs.org/wiki/Modules/1.1.1) CommonJS specification. Script modules within your storefront code can be located in cartridges. But unlike traditional B2C Commerce script files, the script modules within your storefront script code don't have to be located in cartridges.

**note:** This topic assumes that you’re familiar with the [Modules 1.1.1](http://wiki.commonjs.org/wiki/Modules/1.1.1) CommonJS specification.

## What Is a B2C Commerce Script Module?

A CommonJS-compliant B2C Commerce script module is either a script file (with a .js, .json, or .ds extension) or a directory containing script files. A module can hide private data, while exposing public objects and methods via a _free_ variable named `exports`.

**note:** A free variable is accessible within a function but isn’t a local variable defined within the function and isn't a parameter of the function. A free variable can be (but doesn't have to be) a global variable.

Before 13.6, you had to use the `importScript` and `importPackage` methods to access other scripts; these methods automatically export everything into the global context. Access CommonJS-compliant modules using the `require` method. These modules don't automatically export everything into the global context.

Within a script file, you load a CommonJS-compliant B2C Commerce script module using the `TopLevel.global.require(path:String)` method. When the module is loaded, use any of its exported variables or methods.

### Example 1: Creating the Mod1.Js Module

In the following example, the `mod1` module exports the `doit()` method and the `aaa` variable, but hides the `localMethod(`).

```
exports.aaa = "bbb";
exports.doit = function() {
	return "done.";
}
var localVariable = 1;

/**
* @param {String} Error message.
* @returns {Error} New object.
*/
function localMethod(message, localVariable) {
	return new Error({message: localVariable});
}

```

### Example 2: Loading the Mod1 Module

In the following example, the script loads the `mod1` module, retrieves the `aaa` variable from the module, and runs the `doit()` method.

```
/*
 * @output ModuleId : String
 * @output Mod1_1 : String
 * @output Mod1_2 : String
 */
var m1 = require( './mod1.js' );

function execute( pdict )
{
	pdict.ModuleId = module.id;
	pdict.Mod1_1 = m1.aaa;
	pdict.Mod1_2 = m1.doit();

	return PIPELET_NEXT;
}
```

## Path Lookup Behavior of the Require Method

B2C Commerce's `TopLevel.global.require(path:String)` method has different lookup behavior than the `require()` function as specified in the [Modules 1.1.1](http://wiki.commonjs.org/wiki/Modules/1.1.1) CommonJS specification:

- If the `path` argument starts with "./" or "../", then it loads relative to the current module. The module can be a file or a directory. A file extension is acknowledged, but not required. If it's a directory, a `package.json` or a `main` file is expected in the directory.

  **note:** A `main` file is a file named `main`, with either a .js, .ds, or .json extension.

  If the `package.json` file doesn’t contain a `main` property, then the script defaults to the `main` file in the directory, if one exists. Access to parent files can't go beyond the top-level version directory. Access to other cartridges is allowed.

- If the `path` argument starts with "\*/", it's a path relative to the start of the cartridge path.
- If the `path` argument starts with "~/", it's a path relative to the current cartridge in the cartridge path.
- A `path` argument that prepends "dw", or that starts with "dw/", references B2C Commerce built-in functions and classes, for example:

  ```
   var u = require( 'dw/util' );
  ```

  loads the classes in the `util` package, which can be then used as follows:

  ```
  var h = new u.HashMap();
  ```

- A `path` argument that doesn't start with "./" or "../" is resolved as top-level module.
  - The `path` argument is used to find a folder in the top-level version directory, typically a cartridge itself, but it can also be a simple folder.
  - If nothing is found, the `path` argument is used to look into a special folder (named `modules`) in the top version directory. Use this folder to manage different modules. For example, drop a module like `express.js` into that folder.

If the `TopLevel.global.require(path:String)` method is used to reference a file, an optional file extension is used to determine the content of the file. Currently, B2C Commerce supports the following extensions, listed in priority order:

- .js - JavaScript file
- .ds - B2C Commerce script file
- .json - JSON file

**note:** If you use JSON to define a module, the entire JSON object is implicitly exported via the `exports` variable.

**note:** The `importScript` and `importPackage` methods are still available. However, it's recommended that you replace them with the `TopLevel.global.require(path:String)` method.

### Example: Path Lookup for Mymodule.Js

Assume that you have a script (used in SiteGenesis) with the following call to the `require()` method:

```
var u = require( 'mymodule');
```

Further assume the following files and structure on the server:

```
TOP_LEVEL_VERSION_DIRECTORY
│
│   mymodule.js    (2)
│
├───modules                         // Directory
│       mymodule.js  (3)
│
├───mymodule                        // Directory
│       myScript.ds  (1)
│       package.json                // References myScript.ds
│       main.js
│
├───SiteGenesis Storefront Core     // Cartridge directory
└─── Controllers   // Cartridge directory

```

**note:** This structure includes directories and files that are outside of cartridges. To upload such directories and files to a version directory, use the B2C Commerce Build Suite cartridge.

Regardless of where the script that requires a module is located, B2C Commerce finds the module as follows:

1.  First, B2C Commerce searches the `mymodule` directory for a `package.json` file.
    1.  In this example, the `package.json` is present, so B2C Commerce checks the value of the `main` property in the file.
    2.  This property references the `myScript.ds` file, so B2C Commerce loads `myScript.ds` as a module.
    3.  If there’s no `package.json` or if the `main` property is missing, B2C Commerce searches the directory for a `main` file to load.
    4.  If B2C Commerce finds a `main` file, the file is loaded; otherwise, B2C Commerce continues to search.
2.  Next, B2C Commerce finds the `mymodule.js` file because it's in the top-level version directory. If there’s no file at this level, B2C Commerce continues to search.
3.  Last, B2C Commerce searches the `modules` directory in the top level for a `mymodule` script file.

Although Salesforce provides a sophisticated fallback mechanism for scripts in the global namespace, we generally discourage polluting the global namespace with utility scripts. We recommend adding scripts to specific project cartridges.

<!-- document id=93bfbaeaaf5e617b74a39142069f5d52566261ecda6141691a2b20807d4e048d url=/developer/current/en-us/commerce-cloud/solutions/guides/automotive-sk.md -->

# B2C Commerce Solution for Automotive

![Automotive](https://developer.salesforce.com/docs/media/solutions/automotive.png)

## Digital First Automotive Experience

Digitization of the purchasing experience has permeated the automotive industry from vehicles to aftermarket parts and service, causing customer expectations to accelerate tremendously. Customers now expect to be able to interact with digital retail channels as part of their car-buying journey. And dealers are becoming focused on purchasing aftermarket parts and accessories for resale.
With the rapid transformation of the automotive industry, meeting customers where they are and embracing the new way of shopping is a must. Also important is connecting data between OEM and dealers on top of a flexible, trusted, integrated, and proven Commerce Platform as the foundation of a digital commerce experience.

## Business Value

As part of the ever-evolving automotive customer buying journey:

- 80% of customers now do the majority of their shopping for a new vehicle digitally. [Source](https://www.zdnet.com/article/the-automotive-industry-must-embrace-a-digital-first-customer-experience-strategy/)
- By the year 2025, it's estimated that over 25% of global auto sales are going to be conducted online. [Source](https://www.zdnet.com/article/the-automotive-industry-must-embrace-a-digital-first-customer-experience-strategy/)

Today’s ecommerce buying experience is personalized, targeted, intuitive, and puts all interactions in the hands of the consumer. And for dealers who provide a friendly face and facilitate customer transactions in the dealership, the car buying experience must integrate the in-store and ecommerce experience.
By automating the paper cycle for dealers, businesses can facilitate a digital-centric experience. Sales reps encounter an all-in-one guided approach using a customer relationship management (CRM) platform, while also obtaining input and insight from the customer’s interactions with the brand’s digital assets. This capability allows the customer to shop and gives them the option to complete the sale from a representative.

## Automotive Use Cases

Using a complete business-to-business-to-consumer (B2B2C) commerce journey can facilitate easy transactions to help dealers drive more revenue or build a better experience.
For example, use:

- Multi-site commerce storefronts
- Guided selling and lead management
- OEM operated sites for dealers with local flavors
- Scheduled test drives
- Posted sales, accessories, and parts sales
- Dealer B2B sites

For more information, see [Salesforce Industry Solutions for Automotive](https://www.salesforce.com/solutions/industries/automotive/overview/).

## Platform Features and Accelerators

As IT leaders in the auto industry know, there are hazards of building out monolithic single-purpose systems. Think platform, not product. A platform should enable scalability, continuous innovation, and flexibility for growth. This includes automation, intelligence, and personalization at scale, along with an ecosystem of technology partners.

### Top Features for Auto

- [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (Mobile First)
- Multiple and Localized Site Management
- SEO Optimization and URL Management
- Onsite Search
- Product Management (Price Books, Catalogs, Navigation)
- Marketing, Campaigns, & Promotions Engine
- Customer Profile and Account Management
- Customer Segmentation
- AB Testing
- Page Designer and Content
- Dynamic Imaging Service
- Inventory
- Analytics
- Privacy Tools
- Embedded CDN
- Integrated Payments
- Guided Selling
- Curbside Pickup
- Headless API Experience
- AI-Driven Capabilities Powered by Einstein
  - Einstein Predictive Sort
  - Einstein Product Recommendations
  - Einstein Commerce Insights
  - Einstein Search Dictionaries
  - Einstein Search Recommendations
- Salesforce Order Management
- Ecosystem
  - [Commerce Partner Marketplace](https://www.salesforce.com/products/commerce-cloud/partner-marketplace/)
  - [AppExchange](https://appexchange.salesforce.com/)
- Agentforce Marketing and Agentforce Service Integration

## Implementation Overview

Build automotive commerce solutions on top of the Commerce Platform leveraging developer tooling, sample apps, headless APIs, and best practices.

### Salesforce Commerce Platform

### B2C Developer Tools

- [Agentforce Commerce Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud)
- Open Commerce API (OCAPI)
- Salesforce Commerce API
- Software Development Kits (SDK)
- Mulesoft Connector for Data API

### B2C Commerce

- [Build Your Ecommerce Site with Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/build-ecommerce-site-with-cc-digital?trailmix_creator_id=bcommerce&trailmix_slug=get-started-with-salesforce-b-2-c-commerce)
- [Develop for Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/develop-for-commerce-cloud)
- Headless Commerce: [Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-commerce-basics), [Implementation Strategies](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-implementation-strategies), [PWA Kit & Managed Runtime](https://trailhead.salesforce.com/en/content/learn/modules/commerce-pwa-kit-and-managed-runtime)
- [Configure On-Demand Sandboxes](https://trailhead.salesforce.com/content/learn/modules/b2c-on-demand-sandbox)
- [Documentation Hub: B2C & OMS](https://help.salesforce.com/s/articleView?id=cc.b2c_data_input_output_overview.htm&type=5)

### Salesforce Professional Services

Salesforce Professional Services teams help you every step of the way. With deep industry and commerce expertise, customer success experts can help plan, scope, and build your next Automotive project.

<!-- document id=ed42af9b1f58d808f88fa6168daa9dfe18b625823ba3681b6e7256c34aebc436 url=/developer/current/en-us/commerce-cloud/solutions/guides/comm-and-media-sk.md -->

# B2C Commerce Solution for Communications and Media

![Communications and Media](https://developer.salesforce.com/docs/media/solutions/commandmedia.png)

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Accelerate Your Integration to Communication and Media Cloud

An increasing number of CSPs and telco providers are moving beyond connectivity, to deliver new innovative digital commerce offerings. Opening an online storefront is only the start. In an attempt to have a 360-degree view of their customer, communications and media companies want to connect all omnichannel interactions. This includes all consumer touchpoints, along with an ecosystem of independent partners, data sources, and legacy systems.
To advance this digital transformation, companies are launching new direct-to-consumer channels, curbside pickup apps, and integrated marketing and service experiences. A flexible commerce platform with pre-built accelerators and toolkits enhances speed and efficiency to enable commerce transformation.

## Business Value

What’s driving communications and media companies to transform with digital commerce? Increasing Customer Lifetime Value and reducing cost.
Customer Lifetime Value is all about cross-selling, up-selling, and maintaining existing customers. With an integrated digital commerce solution that connects marketing and service, companies can personalize engagements via product recommendations, target communications to individual customers, and merge in-store and digital channels.

Companies can also use customer data to reduce costs to help them maintain their profitability. For example, online portals can reduce service hours. Implementing digital commerce can also help companies lower the cost of entering new markets, reduce physical store footprints, and enable new business models.

## Communications and Media Developer Toolkit for B2C

To jumpstart development, the Communications and Media Industry Toolkit for B2C details how to deploy digital commerce for the communications and media industry
Developers. The aim is to teach these Developers how to publish a commerce catalog and extend the Salesforce [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (SFRA) to accelerate time to market. This toolkit further customizes the SFRA cartridge for industry use cases, and it uses Communications Cloud and Media Cloud product configurations.

The toolkit helps our telco and media customers provide a highly scalable self-service buying experience for B2C shoppers. It enables our customers to develop storefronts with these features:

- Registered User Browse, Cart (Basket), Order Creation, and Submission Operations
- Anonymous Browse and Cart (Basket) Operations
- New Mobile Equipment Purchase
- New Postpaid and Prepaid Mobile Plan Activation
- New Home Internet Plan Activation
- New Bundles with Optional Add-Ons
- New TV Plans and Equipment
- New OTT Services
- New Media and Entertainment Services, for example, Spotify or Pandora

## Platform Features and Accelerators

B2C Platform: Top Features for Communications and Media for Commerce:

- High-Scale Customer Experience (with Storefront Reference Architecture)
- Multiple and Localized Site Management
- Page Designer and Content
- Embedded CDN
- Integrated Payments
- B2C Developer Tools
  - Salesforce Commerce API
  - Open Commerce API (OCAPI)

Salesforce Communications Cloud and Media Cloud for Industry-Specific Capabilities:

- Product Management for complex bundles with cardinality rules
- Attribute-based pricing
- Omni-Channel services

## Implementation Overview

The SFRA Extension Toolkit For Communications and Media is a free cartridge showcasing an integration approach. This cartridge is not a turnkey solution and doesn't have all the use cases implemented. This cartridge showcases a proof of concept for how the two products can be integrated. This is available for all customers and partners that are part of the Commerce Cloud GitHub community.

Product, pricing, and context rules are merchandised on Salesforce Communications Cloud and Salesforce Media Cloud. The catalog containing the configured products is then published to B2C Commerce. The high scale storefront is built with a combination of out-of-the-box [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (SFRA) and B2C Commerce capabilities, Configure Price Quote (CPQ) from Salesforce Communications Cloud, Salesforce Media Cloud, leverages Digital Commerce cacheable APIs.

Consumers can create an account in B2C Commerce, and the respective consumer account is created in Communications and Media cloud in real time.
This version of B2C Commerce Toolkit for Communications and Media includes:


- **SFRA Extension Toolkit For Communications and Media**: Use this to accelerate your integration to our industry cloud. Supports, Browse, Configure, and Checkout processes using our APIs along with a sample Comms-specific UI.
  [Available on Salesforce B2C Commerce GitHub](https://github.com/SalesforceCommerceCloud/B2C_Commerce_Toolkit_for_Communications_and_Media) (You must have access to Salesforce Commerce Cloud GitHub organization via Concierge.)

The Communications and Media Industry Toolkit for B2C is built using the following on-platform native capabilities: OmniScripts, Integration Procedures, and DataRaptor. In addition, we leverage TM Forum Open API 620 and our Digital Commerce, GetOffers API to extract the commercial products from our shared product catalog. Therefore, any limitations governed by the platform and features would be applied to this toolkit.

The SFRA Extension Toolkit For Communications and Media is built as a B2C Commerce Cartridge. Therefore, modifications and enhancements are expected to be made by our customers, partners, and services teams.

To make the Communications and Media toolkit to work on your demo environment, you need SFRA Extension cartridges deployed on a B2C Commerce environment and Vlocity Managed package (Fall '20 release) installed on the Salesforce Org.
B2C Commerce licensing and professional services aren't included as part of the toolkit, which is provided under the BS-3-Clause. For full license text, see the LICENSE file in the repo root, or go to https://opensource.org/licenses/BSD-3-Clause.

To implement and enhance the toolkit, we expect you to work with our services team. Therefore we strongly recommend and invite you to test and try out our toolkit to measure if this solution meets your customer’s needs.

## Developer Journey

A developer customizing this cartridge needs a Salesforce Communications and Media license and a B2C Commerce Sandbox.

## The Consumer Subscriber Journey

Consumers in the Communications and Media industry are often referred to as subscribers.

### Browse and Configure

1. A subscriber or a potential customer starts as a guest. The guest subscriber is eligible to view all based products information on the commerce storefront.
2. After browsing the storefront, the subscriber signs in (existing users) or signs up (new user). The user record is created on B2C Commerce and on Communications Cloud and Media Cloud, and the person account ID is stored in Commerce as a custom attribute.
3. The subscriber selects a catalog and gets eligibility and context-based product offers.
4. The subscriber selects a product in Communications Cloud and Media Cloud.

### Basket Operations

1. The subscriber adds products to the cart, changes quantities, and selects different options on bundles.
2. The prices are updated based on the price rules configured in Communications Cloud and Media Cloud CPQ.

### Checkout

1. The subscriber places an order or subscribes to a new plan.
2. The order is sent to Communications Cloud and Media Cloud, and then the assetatization process begins.

## Additional Resources

Learn how to get started quickly from these tutorials.

### B2C Developer Tools

- [Agentforce Commerce Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud)
- Open Commerce API (OCAPI)
- Salesforce Commerce API
- Software Development Kits (SDK)
- Mulesoft Connector for Data API

### B2C Commerce

- [Build Your Ecommerce Site with Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/build-ecommerce-site-with-cc-digital?trailmix_creator_id=bcommerce&trailmix_slug=get-started-with-salesforce-b-2-c-commerce)
- [Develop for Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/develop-for-commerce-cloud)
- Headless Commerce: [Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-commerce-basics), [Implementation Strategies](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-implementation-strategies), [PWA Kit & Managed Runtime](https://trailhead.salesforce.com/en/content/learn/modules/commerce-pwa-kit-and-managed-runtime)
- [Configure On-Demand Sandboxes](https://trailhead.salesforce.com/content/learn/modules/b2c-on-demand-sandbox)
- [Documentation Hub: B2C & OMS](https://help.salesforce.com/s/articleView?id=cc.b2c_data_input_output_overview.htm&type=5)

### Order Management

- [Getting Started with Salesforce Order Management](https://trailhead.salesforce.com/content/learn/modules/om-salesforce-order-management)
- [Salesforce Order Management Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/order_management_developer_guide_intro.htm)

### Salesforce Industries

- [Salesforce Industries Platform](https://vlocity.com/platform)
- [Omnistudio](https://trailhead.salesforce.com/en/content/learn/trails/get-to-know-omnistudio)

### Salesforce Professional Services

Salesforce Professional Services teams can help you every step of the way. With deep industry and commerce expertise, customer success experts can help plan, scope, and build your next communications and media project.

## Tools

To access the Salesforce Commerce Cloud GitHub repository, you must have a [GitHub](https://github.com/join) account that is linked with your Account Manager Credentials. Authenticate your account with the [Salesforce B2C Commerce SSO Signup](https://github.com/orgs/SalesforceCommerceCloud/sso).

- [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra)

<!-- document id=d08b8b11bce90be38b84ef18efd2f09cb79230430d9804bafb8d9912d90227db url=/developer/current/en-us/commerce-cloud/solutions/guides/grocery-sk.md -->

# B2C Commerce Solution for Grocery

![Groceries](https://developer.salesforce.com/docs/media/solutions/grocery.png)

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Sell Groceries Online for Store Pickup

In January 2020, [only 5%](https://www.onespace.com/blog/2018/08/online-grocery-food-shopping-statistics/) of grocery purchases were made online. Then, COVID-19 arrived. Almost overnight, grocery stores experienced an unprecedented spike in demand. Demand has slowed, but certain behaviors are here to stay as consumers continue to rely on digital-first shopping for grocery.
See [Salesforce Industry Solutions for Retail](https://www.salesforce.com/solutions/industries/retail/overview/).

## Business Value

Convenience and safety are driving online grocery shopping. Pre-COVID, this space was already trending, with 10% of U.S. consumers regularly shopping online for groceries and a market value that doubled from 2016 through 2018.

COVID-19 has accelerated the growth of this opportunity, with a 30% increase in global online grocery sales, and over $7 billion in sales in the U.S. in the month of June 2020 ([Digital Commerce 360](https://www.digitalcommerce360.com/2020/07/20/the-coronavirus-pandemic-lifts-global-online-grocery-sales/), [Supermarket News](https://www.supermarketnews.com/retail-financial/us-online-grocery-sales-growth-tails-june), [Sharecast](https://www.sharecast.com/news/news-and-announcements/uk-grocery-sales-continue-to-grow-at-record-rate--7581078.html)). That same month, Salesforce partners saw a 200% surge in B2C grocery revenue and customer visits (B2C Commerce Cloud GMV July 2019 - June 2020).

Offering groceries for online purchase and store pickup adds convenience to the shopping experience. And it offers unique opportunities for cross-selling, up-selling, recipe pages that inspire shoppers, nutritional requirement filters that guide their purchases, and analytics-informed promotions that are triggered by store-specific criteria.

## Grocery Developer Toolkit

The B2C Commerce Toolkit for Grocery allows developers to quickly stand up a digital storefront with prebuilt components to increase customer convenience at brick-and-mortar grocery stores. The full-featured implementation lets customers shop online and purchase groceries for store pickup at a time they select.

Bundled and ready-to-configure apps provide speed to launch. The [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (SFRA) grocery components provide an authentic grocery shopping experience. Shoppers can compare and filter groceries by price, brand, or nutritional profile. They can save shopping lists for future visits, fulfill targeted promotions, or select items by choosing a recipe.
A time-slot manager app manages pickup scheduling, and even parking space reservations.

Also, store associates can pick and pack orders using a mobile Sample Picker App that accelerates order fulfillment.

## Grocery Developer Toolkit Use Cases

- Digital grocery storefront experience: reference architecture that includes grocery-specific PLP and PDP pages.
- Store based pricing, promotions, and availability.
- Pick up time management and selection.
- Picker app for store associates (coming soon).

## Platform Features & Accelerators

The Salesforce Commerce platform enables grocers with features and accelerators to meet the needs of digital-first customers.

### B2C Platform: Top Features for Grocery

- High-Scale Customer Experience (with Storefront Reference Architecture)
- Multiple and Localized Site Management
- High-Scale Commerce Services: Search, Promotions, Campaigns, and More
- Omnichannel Inventory - Across Hundreds of Stores and Thousands of SKUs
- Page Designer and Content
- Dynamic Imaging Service
- Analytics
- Privacy Tools
- Embedded CDN
- Integrated Payments
- Curbside Pickup
- Headless APIs - Extend commerce services to shopper touchpoints
- Integration - integrate third-party data sources
- AI-Driven Capabilities Powered by Einstein
  - Einstein Predictive Sort
  - Einstein Product Recommendations
  - Einstein Commerce Insights
  - Einstein Search Dictionaries
  - Einstein Search Recommendations
- Salesforce Order Management - to decompose, orchestrate, and complete provisioning to assetize services and products.
- B2C Developer Tools
  - Salesforce Commerce API
  - Open Commerce API (OCAPI)
  - Software Development Kits (SDK)
  - Mulesoft Connector for Data API
- Ecosystem
  - [Agentforce Commerce Partner Marketplace](https://www.salesforce.com/products/commerce-cloud/partner-marketplace/)
  - [AppExchange](https://appexchange.salesforce.com/)
- Agentforce Marketing and Agentforce Service integration

### B2C Platform: Toolkit Accelerators for Grocery

- B2C Commerce Toolkit for Grocery from GitHub
- Time Slot Manager from GitHub
- Sample Picker App for Grocery from GitHub
- Store locator
- Heroku (or comparable PaaS) for Time Slot Manager app

## Implementation Overview

The B2C Commerce Toolkit for Grocery is a free Salesforce Community solution offered as an unmanaged package. With this toolkit, access the full power of the community, such as shared code enhancements, and contribute to the toolkit yourself.

You customize, brand, and stand up your storefront on B2C Commerce and a platform-as-a-service (PaaS) such as Heroku, using a suite of [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (SFRA) GitHub plugins and assets. The solution incorporates best practices based on our proven and imminently scalable B2C Commerce grocery architecture.

The toolkit comes with sample configurations and data for best practice sharing on an operational grocery storefront. Implementation time depends on integration into your existing application landscape and customization requirements.

B2C Commerce licensing and professional services aren't included as part of the toolkit, which is provided under the BS-3-Clause. For full license text, see the LICENSE file in the repo root, or go to [The 3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause).

Use B2C Commerce Toolkit for Grocery assets to brand your storefront and craft grocery-optimized customer journeys:

- Build a self-serve digital grocery storefront for your chain.
- Offer store-specific product range, pricing (including price-per-unit), and promotions dynamically loaded when customers select a store.
- Manage time slots and capacity by store for shopper pickup times.
- Feature grocery style product lists and product detail pages.
- Support shopping list memory, filtered searches, and recipe and promotion pages.
- Use and extend a sample picker mobile app (coming soon) for order assembly and order updates.

### Storefront Plugins

- Grocery Storefront cartridges: A full-featured storefront use case with sample configurations that you operationalize with your SFRA integration.
- Select Store plugin: Displays available stores, open times, and launches the selected storefront.
- Theme Plugin: Supports customizing and branding of your storefront.
- The Time Slot Manager:
  - Runs on Heroku or a comparable PaaS.
  - Integrated into the storefront.
  - APIs to manage time slots per store.
  - User interface for slot management via the B2C Commerce Business Manager cartridge.
  - Extensible to support parking space booking, table reservations, and so on.
- Coming soon, the Sample Picker App for Grocery for store associates (mobile):
  - View order details (Fulfilled, In Progress).
  - Substitute products as needed.

## Developer Journey

The developer community and Salesforce Professional Services can advise and help every step of the way.

- Gather payment gateway, product images, prices, inventory, and store feeds.
- Acquire SFRA for Grocery GitHub assets and plugins from B2C Commerce.
- Deploy a PaaS such as Heroku to run the Time Slot Manager service.
- Brand and customize assets using low-code Page Designer.
- Explore, model, and build out your solution using the included reference architecture storefront and sample data.
- Integrate with existing warehouse management (for Sample Picker App), point-of-sale, and order management systems as needed.

## The Shopping-to-Store-Pickup Journey

1. On the Homepage, shoppers choose between Just browsing or Select My Store.
2. Shoppers find your store by entering their location, or searching by postal code, city, or state. Selecting a store displays its profile page, showing general information such as open hours. Clicking through launches the storefront, with store-specific assortment, pricing, availability, promotions, recipe pages, and pickup scheduling.
3. Select a pickup time. Shoppers navigate available day and time slots, which the grocer configures using the Time Slot Manager cartridge for Business Manager. The earliest available times appear atop the list. Unavailable slots are listed as unavailable.
4. Browse items on a Product List Page or Product Detail Page:

   - View available products by their price, including price per unit.
   - View nutritional badges, such as vegan and dairy.
   - Save to the shopping list.
   - Add to the cart.
   - View and modify the item quantity in cart.
   - View related promotions.
   - Filter by category, nutrition, brand, and so on.
   - Sort by popularity, price, or other metrics.

5. View cart and mini cart, which allows shoppers to highlight substitutable (low inventory) products and save items to a shopping list. Items are grouped by category for a quick overview.
6. Complete the order by converting all or some of the cart or shopping list to check out and pay.
7. Save the order as a shopping list for future purchases. The shopping list is displayed on the shopper’s My Account page.
8. Edit the order before pick up.
9. Store associates fulfill the order using the integrated mobile Sample Picker App (coming soon). The app shows the order status, sorted by shopper pickup time. If a colleague is picking an order, the app displays an In Progress tag and it's locked for other pickers.
10. Associates use the mobile Sample Picker App to check for products that the shopper highlighted as ok-to-substitute if inventory is depleted.

## Additional Grocery Resources

Launch a Commerce Quick Start Solution that provides out-of-the-box solutions for Grocery and Quick Service Restaurants, along with a Curbside Pickup with Order Management. Developers can offload implementation and managed services to partners in these offerings.

[Buy Online, Pick up In-Store (BOPIS)](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-curbside-pickup_data-sheet.pdf)
Provide options for low- and no-contact pickup
[Quick Start for Grocery and Quick Service](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-grocery-data-sheet.pdf)
Sell essential grocery and food items online

### Salesforce Professional Services

Salesforce Professional Services teams can help you every step of the way. With deep industry and commerce expertise, customer success experts can help plan, scope, and build your next grocery project.

## Tools

- [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra)
- [Time Slot Manager Overview](https://salesforce.quip.com/mtccA6KheUac)

## Sample Apps

To access the Salesforce Commerce Cloud GitHub repository, you must have a [GitHub](https://github.com/join) account that is linked to your Account Manager Credentials. Authenticate your account with the [Salesforce B2C Commerce SSO Signup](https://github.com/orgs/SalesforceCommerceCloud/sso).

- [B2C Commerce for Grocery - Storefront Cartridges on GitHub](https://github.com/SalesforceCommerceCloud/b2c-commerce-toolkit-for-grocery)
- [B2C Commerce for Grocery - Time Slot Manager on GitHub](https://github.com/SalesforceCommerceCloud/Time_Slot_Manager)

<!-- document id=cfb25466b070d876be5d5aaa9abe23b726e719fa006c834c03f7af6b42467f3d url=/developer/current/en-us/commerce-cloud/solutions/guides/healthcare-life-sciences-sk.md -->

# B2C Commerce Solution for Healthcare and Life Sciences

![Healthcare and Life Sciences](https://developer.salesforce.com/docs/media/solutions/health.png)

## Digital and Direct Solution for HLS Companies

Healthcare and life science (HLS) organizations, including providers, payers, and medical suppliers are deploying digital platforms to improve efficiency, reduce transaction costs, and better patient experiences.
An omnichannel approach provides HLS organizations flexibility to manage relationships and interactions with customers, across marketing, product discovery, sales, and post-sale services, among others.
Many organizations also rely on their commerce platform to absorb complex rules related to provisioning, procurement, and reporting, and to present them to providers and payers in a digestible way. Add in regulatory and compliance considerations, and it’s clear that HLS organizations have their own unique commerce requirements.

## Business Value

Consumers increasingly expect to engage with healthcare companies digitally like they do in other aspects of their lives. According to a recent Health Industry Distributors Association Insights report, in 2020, 85% of all B2B buyer and seller relationships took place without human interaction.
Selling HLS products and services digitally in a patient-direct manner is a significant opportunity for pharmaceutical and medical device companies. The global medical device market alone is expected to hit $409 billion by 2023, and Deloitte predicts global healthcare expenditures reaching a staggering $10 trillion by 2022.
Additionally, more and more insurance companies (payers) are incorporating digital into sales and account management.

## Healthcare and Life Sciences Use Cases

Agentforce Commerce enables developers to launch an ecommerce channel quickly and deliver the connected online experiences that buyers expect. These experiences include:

- Guided online ordering that allows HLS companies to reach patients directly while delivering a personalized experience based on member status.
  - Direct-to-consumer (D2C) commerce for pharmaceuticals, medical devices, and so on.
  - Online payer and insurance registration, signup, and purchasing.
  - B2B purchasing and change management of complex orders.
- Patient portal support for multiple interactions, including organization-to-provider, provider-to-patient, and organization-to-provider-to-patient.
- High-value content such as videos, images, and community streams that enhance customer decision making.
- Appointment picking and time slot management.
- Elevated support tools that meet complex customer needs, such as:
  - Contract-based group purchasing organization (GPO) pricing so providers can negotiate discounts and other savings based on purchasing volume.
  - Shared carts that allow payers to easily toggle between sites and add items, with all carts aligned across sites to show all items.
  - Split shipments so orders can arrive in multiple packages to one location or to different locations.
- Support for regulatory requirements, such as HIPAA.

For more information, see [Salesforce Industry for HLS](https://www.salesforce.com/solutions/industries/healthcare/overview/).

## Platform Features and Accelerators

The Salesforce Commerce platform enables healthcare providers of all kinds to deliver exceptional online buying experiences and adapt to changing market dynamics.

### Top Features for Healthcare and Life Sciences

- HIPAA: B2C Commerce provides tools that align with HIPAA.
  - [BAA Amendment Page](https://www.salesforce.com/products/commerce-cloud/business-associate-addendum-restrictions/) - Only B2C Commerce, excluding Einstein, Order Management and certain other components, was included in the review.
- HIPAA: Salesforce provides tools that align with HIPAA.
  - [HIPAA Compliance Page](https://compliance.salesforce.com/en/hipaa)
- [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (Mobile First)
- Multiple and Localized Site Management
- SEO Optimization and URL Management
- Onsite Search
- Product Management (Price Books, Catalogs, Navigation)
- Marketing, Campaigns, & Promotions Engine
- Customer Profile and Account Management
- Customer Segmentation
- AB Testing
- Page Designer and Content
- Dynamic Imaging Service
- Inventory
- Analytics
- Privacy Tools
- Embedded CDN
- Integrated Payments
- Guided Selling
- Curbside Pickup
- Headless API Experience
- AI-Driven Capabilities Powered by Einstein
  - Einstein Predictive Sort
  - Einstein Product Recommendations
  - Einstein Commerce Insights
  - Einstein Search Dictionaries
  - Einstein Search Recommendations
- Salesforce Order Management
- Ecosystem
  - [Agentforce Commerce Partner Marketplace](https://www.salesforce.com/products/commerce-cloud/partner-marketplace/)
  - [AppExchange](https://appexchange.salesforce.com/)
- Agentforce Marketing and Agentforce Service Integration

## Implementation Overview

Build an HLS commerce solution on top of the Commerce Platform using developer tooling, sample apps, headless APIs, and best practices. The Commerce Platform’s seamless API Integration with multiple tools ensures business continuity to run your business.

### B2C Developer Tools

- [Agentforce Commerce Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud)
- Open Commerce API (OCAPI)
- Salesforce Commerce API
- Software Development Kits (SDK)
- Mulesoft Connector for Data API

### B2C Commerce

- [Build Your Ecommerce Site with Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/build-ecommerce-site-with-cc-digital?trailmix_creator_id=bcommerce&trailmix_slug=get-started-with-salesforce-b-2-c-commerce)
- [Develop for Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/develop-for-commerce-cloud)
- Headless Commerce: [Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-commerce-basics), [Implementation Strategies](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-implementation-strategies), [PWA Kit & Managed Runtime](https://trailhead.salesforce.com/en/content/learn/modules/commerce-pwa-kit-and-managed-runtime)
- [Configure On-Demand Sandboxes](https://trailhead.salesforce.com/content/learn/modules/b2c-on-demand-sandbox)
- [Documentation Hub: B2C & OMS](https://help.salesforce.com/s/articleView?id=cc.b2c_data_input_output_overview.htm&type=5)

### Order Management

- [Getting Started with Salesforce Order Management](https://trailhead.salesforce.com/content/learn/modules/om-salesforce-order-management)
- [Salesforce Order Management Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/order_management_developer_guide_intro.htm)

### B2B Commerce

- [Salesforce B2B Commerce Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2b-commerce-basics)
- [Administer Salesforce B2B Commerce on Lightning Experience](https://trailhead.salesforce.com/en/content/learn/trails/administer-salesforce-b2b-commerce-on-lightning-experience)
- [Documentation Hub: B2B](https://help.salesforce.com/articleView?id=commerce.b2b_commerce.htm&type=5)

### Salesforce Professional Services

Salesforce Professional Services teams help you every step of the way. With deep industry and commerce expertise, customer success experts can help plan, scope, and build your next HLS project.

## Additional Consumer Good Resources

Launch a Commerce Quick Start Solution that provides out-of-the-box solutions for D2C and B2B use cases. Developers can offload implementation and managed services to partners in these offerings.
[Quick Start for Direct-to-Consumer](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-consumer-essential-goods-data-sheet.pdf)
Launch a direct-to-consumer commerce site for essential and consumer goods.
[Quick Start for B2B Commerce](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-B2b-data-sheet.pdf)
Deploy a B2B Commerce storefront for self-service ordering.

<!-- document id=7ef61757369e17da1b120896ac07f72ad69a9ee1047f37023a2e9f20f962b6f9 url=/developer/current/en-us/commerce-cloud/solutions/guides/insurance-sk.md -->

# B2C Commerce Solutions for Insurance

![Insurance](https://developer.salesforce.com/docs/media/solutions/insurance.png)

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Reach Insurance Shoppers Directly with Salesforce Industries, Commerce, and Marketing

Consumer trends and new technology advances have brought disruptive change, and accelerated digital adoption across virtually all industries. In insurance, shoppers are increasingly looking for ways to connect digitally and directly for Property & Casualty offerings.
The insurance industry has also evolved rapidly with carriers starting to take a digital-first mindset along with the rise of new InsurTech companies. A digital solution can provide the foundation for a better consumer experience, alongside efficiencies in the current insurance industry model.

## Business Value

Today, everyone expects to buy products and services online. The same is true in the insurance segment, as shoppers say they prefer to shop for insurance directly instead of going through an agent. As a result, 40% of insurers expect to increase investment in digitalization in 2021 and beyond.
Taking insurance direct-to-consumer (D2C), is only one channel. Insurers also want to have a single view of their shopper, extending into customer support, along with agent and call center channels, and into marketing engagements. Only Salesforce can provide an integrated experience with best-in-class tools that developers can use to speed new consumer focused channels to market fast.

## Insurance Developer Toolkit

The B2C Commerce Toolkit for Insurance brings together the power of Salesforce Industries, Commerce, and Marketing solutions to help insurers harness technology that optimizes their digital channels. Insurers can launch secure, scalable, and personalizable storefronts that host direct quote-to-buy capabilities that are deeply integrated with Salesforce Industries.
An insurance shopper can land on the storefront, receive quotes for multiple insurance products, add quotes to their cart, and purchase the policies online—all from their preferred device.
The toolkit provides an integrated consumer buying journey. If the shopper abandons their cart, providers can reach them in other digital channels and allow the shopper to retrieve their quote to bind the policy online. Agents and service representatives can also view the shopper’s account, quotes, and policies in Salesforce Insurance, ensuring a personalized agent followup.

## Insurance Use Cases

Salesforce powers a digital-first, 360-degree solution.

- Consumer Experience: A digital consumer looking for an insurance quote lands on a provider’s web page and browses for a solution on the home and product pages. The shopper begins a quote online and adds the quote to the cart. They also complete another quote for a different product and add that product to the cart. The shopper checks out with a multi-product cart, creating multiple policies with the insurer.
- Insurer Licensed Representative Experience: If a shopper abandons the online quote and calls in to the insurer call center, the licensed representative can open the quote in Salesforce Industries and bind the policy offline.
- Insurer: As the shopper is browsing and adding insurance products to the cart, the insurer can show them related non-insurance products from partners for purchase. For example, the insurer can show home automation devices with a home policy, or pet food and products for a pet policy. The insurer can also use B2C Commerce’s native analytics to observe shopping trends, policies bound, and other critical digital metrics.

## Platform Features and Accelerators

Top B2C Commerce features:

- Secure, scalable, and personalizable [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (mobile-first)
- Cart and checkout capabilities
- Tracking and retargeting integrations
- Page Designer: clicks, not-code WYSIWYG editor
- Multiple and localized site management
- SEO optimization
- Einstein Product Recommendations
- Headless APIs to extend commerce services to shopper touchpoints
- Agentforce Marketing integration for cart abandonment email targeting

Top Salesforce Industries features:

- Quote-to-bind OmniScript
- Product model and rating engine
- Quotes, contracts, and assets (policies)
- Data Raptors
- Integration Procedures

Top Agentforce Marketing features:

- Journey Builder
- Event triggering emails
- Email templates

## Implementation Overview


The B2C Commerce Toolkit for Insurance is a free Salesforce Community solution offered as an unmanaged package. With this toolkit, access the full power of the Salesforce developer community, such as from shared code enhancements, and contribute to the toolkit yourself.
This toolkit is built with the best-in-class capabilities of B2C Commerce Cloud, Salesforce Industries, and Salesforce Marketing Cloud. Providers can customize, brand, and stand up their storefront on B2C Commerce Cloud and a platform-as-a-service (PaaS), such as Heroku, using a suite of [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (SFRA) GitHub plugins and assets.
Products, pricing, and quoting OmniScripts are configured on Salesforce Industry Cloud. The catalog containing the top-level products is then published to B2C Commerce Cloud. The high-scale storefront is built with a combination of out-of-the-box SFRA, Commerce platform capabilities, and Salesforce Industry Cloud’s insurance-specific capabilities.
To deploy the toolkit on your demo environment, you need SFRA Extension cartridges deployed on a Commerce Cloud environment and Vlocity Managed package (Fall ’20 release) installed on the Salesforce Org.

B2C Commerce licensing and professional services aren't included as part of the toolkit, which is provided under the BS-3-Clause. For full license text, see the LICENSE file in the repo root, or see the [Open Source Initiative 3-Clause BSD License](https://opensource.org/licenses/BSD-3-Clause).

## Developer Journey

Developers can use these Salesforce resources:

- Build on the Salesforce Commerce Platform: Enable developer tooling, sample apps, headless APIs, and best practices
- Build with Salesforce Industries: Provide an integrated and full featured industry solution with native features.

A developer customizing this cartridge needs a Salesforce Industries license and a B2C Commerce Sandbox.
A developer guide for building on Salesforce B2C Commerce will be published to Github shortly.

## Digital Quote-to-bind Insurance Journey

1. An anonymous insurance shopper clicks through a digital ad and lands on the insurer’s homepage.
2. After browsing product information, the shopper decides to get an auto insurance quote.
3. The shopper enters details about them, their vehicles, and drivers in their households, and then receives a quoted premium.
4. After adjusting coverages to meet their needs, the shopper proceeds to add the quote to the cart.
5. The shopper is shown recommendations for related products that they can add to the cart.
6. The shopper adds another related product to the cart, but then abandons the cart before completing their purchase.
7. The shopper receives an email to remind them of their quote and details on how to retrieve it. Alternatively, the shopper can be retargeted in a social channel, such as Facebook or Instagram.
8. The shopper retrieves the quote, continues to bind the policy, and then purchases the related products online.
9. An account, quote, and policy is created in Salesforce Industries so that all the information about the policy and policyholder acquired digitally is available to the service rep for post-sale servicing.

## Additional Resources

Get started quickly with these tutorials.

### B2C Developer Tools

- [Agentforce Commerce Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud)
- Open Commerce API (OCAPI)
- Salesforce Commerce API
- Software Development Kits (SDK)
- Mulesoft Connector for Data API

### B2C Commerce

- [Build Your Ecommerce Site with Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/build-ecommerce-site-with-cc-digital?trailmix_creator_id=bcommerce&trailmix_slug=get-started-with-salesforce-b-2-c-commerce)
- [Develop for Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/develop-for-commerce-cloud)
- Headless Commerce: [Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-commerce-basics), [Implementation Strategies](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-implementation-strategies), [PWA Kit & Managed Runtime](https://trailhead.salesforce.com/en/content/learn/modules/commerce-pwa-kit-and-managed-runtime)
- [Configure On-Demand Sandboxes](https://trailhead.salesforce.com/content/learn/modules/b2c-on-demand-sandbox)
- [B2C Commerce Help](https://help.salesforce.com/s/articleView?id=cc.b2c_getting_started.htm)
- [B2C Commerce Developer Center](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide)

### Salesforce Industries

- [Salesforce Industries Platform](https://vlocity.com/platform)
- [Omnistudio](https://trailhead.salesforce.com/en/content/learn/trails/get-to-know-omnistudio)

### Salesforce Professional Services

Salesforce Professional Services teams help you every step of the way. With deep industry and commerce expertise, customer success experts can help plan, scope, and build your next Insurance project.

## Tools & Sample Apps

To access the Salesforce Commerce Cloud GitHub repository, you must have a [GitHub](https://github.com/join) account that is linked with your Account Manager Credentials. Authenticate your account with the [Salesforce B2C Commerce SSO Signup](https://github.com/orgs/SalesforceCommerceCloud/sso).

- [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra)
- [Building on B2C Commerce Developer Guide](https://github.com/SalesforceCommerceCloud/B2C_Commerce_Toolkit_for_Communications_and_Media)

<!-- document id=d2e4f74a42c9860143eb3c3c395893e6820fb0ca598e952d19a38cc3def54b0f url=/developer/current/en-us/commerce-cloud/commerce-api/guides/base-url.md -->

# Base URL and Request Formation

Before you start working with B2C Commerce APIs, you must understand the configuration of the base URL and the specific parameters for your instance.

This guide covers how to construct well-formed requests to the B2C Commerce API with all required parameters. To identify your specific configuration information needed in your URLs, refer to the Configuration Values section.

## Base URL Pattern

The base URL for all requests to the B2C Commerce API follows a pattern to help you identify your B2C Commerce instance and direct your request to the correct API family. To understand the pattern, let’s look at the base URL with placeholders (enclosed in curly braces) for the parts of the URL that vary according to your instance and API family:

```text
https://{shortCode}.api.commercecloud.salesforce.com/{apiFamily}/{apiName}/v1/organizations/{organizationId}/
```

**note:** Make sure to specify `v1` for the version, unless you are working with the Shopper Baskets API. For the Shopper Baskets API, specify `v1` or `v2`, as applicable.

Replace the placeholders with these example values:

| Placeholder        | Value              |
| ------------------ | ------------------ |
| `{shortCode}`      | `kv7kzm78`         |
| `{apiFamily}`      | `product`          |
| `{apiName}`        | `shopper-products` |
| `{organizationId}` | `f_ecom_zzte_053`  |

With example values, the base URL looks like this:

```text
https://kv7kzm78.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_zzte_053/
```

The short code and organization ID in our examples belong to the demo sandbox. How to look up these values for your own B2C Commerce instance is discussed in the next section.

## Configuration Values

For each B2C Commerce instance that uses the B2C Commerce API, gather a set of configuration values related to that instance. These configuration values are required to complete the setup process and to formulate API requests.

A typical set of configuration values looks like this:

| Configuration Value | Example         |
| ------------------- | --------------- |
| Organization ID     | f_ecom_zzte_053 |
| Short code          | kv7kzm78        |
| Site ID             | RefArch         |

This guide provides more details on each configuration value and shows you where to find them.

### Organization ID

The organization ID is a short string that identifies a B2C Commerce instance. Each instance gets its own unique organization ID, such as `f_ecom_zzte_053`.

To look up the organization ID for an instance through Business Manager, you must have the Business Manager Administrator role in Account Manager and know the Business Manager URL for the instance.

A Business Manager URL looks like this:

```text
https://zzte-053.dx.commercecloud.salesforce.com/on/demandware.store/Sites-Site
```

To look up the organization ID:

1. Go to the Business Manager URL for your instance.
2. Log in using your Account Manager credentials.
3. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Salesforce Commerce API Settings**.

The organization ID is displayed on the page. Copy and paste it in a location that is easy to refer to later.

![Site Development settings with Short code and Organization ID examples](https://developer.salesforce.com/docs/media/commerce-api/commerce-api-configuration-values-2.jpg)

#### Realm ID

A realm describes a set of B2C Commerce instances, including both primary and secondary instances. The realm ID is part of the organization ID. It’s a four-character string that comes after the second underscore (`_`) in the organization ID. For example, if the organization ID is `f_ecom_zzte_053`, then the realm ID is `zzte`. To learn more about realms, see [Concepts and Terminology](https://help.salesforce.com/s/articleView?id=cc.b2c_platform_overview.htm&type=5) in the B2C Commerce documentation.

#### Instance ID

The instance ID identifies an instance within a realm. It’s a three-character string that comes after the third underscore in the organization ID. For example, if the organization ID is `f_ecom_zzte_053`, then the instance ID is `053`.

Different types of instances follow different ID patterns:

- For production, staging, or development instances, the instance IDs are `prd`, `stg`, or `dev`, respectively.
- For on-demand sandboxes, the instance ID is a three-digit number that increases as more sandboxes are created.
- For POD sandboxes, the format of the instance ID is `sXX`, where `XX` is a number between from 01 to 99.

#### Tenant ID

A B2C Commerce instance is considered a “tenant” when it's associated with a supporting system, such as the Shopper Login and API Access Service (SLAS). To associate an instance with a system like SLAS, identify the instance with a tenant ID. A tenant ID begins with a four-character realm ID, followed by an underscore (`_`) and an instance ID.

For Omnichannel Inventory (OCI) updates, retrieve the tenant ID from OCI. See [Salesforce Omnichannel Inventory Implementation Guide for B2C Commerce.](https://resources.docs.salesforce.com/latest/latest/en-us/sfdc/pdf/salesforce_omnichannel_inventory_implementation_guide.pdf)

These are example tenant IDs for various types of instances:

| Instance Type     | Realm ID | Instance ID | Tenant ID |
| ----------------- | -------- | ----------- | --------- |
| Staging           | bcgl     | stg         | bcgl_stg  |
| On-demand sandbox | zzte     | 053         | zzte_053  |
| POD sandbox       | zzrf     | s01         | zzrf_s01  |

### Short Code

The short code is an eight-character string that's assigned to a realm for routing purposes. It’s concatenated with `api.commercecloud.salesforce.com` to create the API host name for your API calls, for example: `u8ak193h.api.commercecloud.salesforce.com`.

The short code applies to the entire realm, across all instances.

To look up the short code for your realm:

1. Go to the Business Manager URL for your instance.
2. Log in using your Account Manager credentials.
3. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Salesforce Commerce API Settings**.
4. If you’ve never used the B2C Commerce API in your realm, click **Request Short Code**. It can take up to 24 hours for the short code to propagate through the CDN and all the routing systems in your configuration.

<!-- REVIEW(SME): Confirm the current Business Manager button label and menu path. Engineering's 26.7 release note refers to a "Get Short Code" button under "Administration > Commerce API Settings", while these steps use "Request Short Code" under "Administration > Site Development > Salesforce Commerce API Settings". Reconcile if the UI changed. -->

![Short code in pending status](https://developer.salesforce.com/docs/media/commerce-api/commerce-api-configuration-values-1.jpg)

**note:** Starting in B2C Commerce 26.7, on-demand sandbox (ODS) realms can have their own dedicated short code, generated the same way as for other realms. Previously, ODS realms shared a common short code (`kv7kzm78`), which continues to work. If you use SLAS hybrid authentication or encounter the error `Cannot construct SLAS session-bridge URL: no ACTIVE SCAPI short code found for this organization`, generate a dedicated short code to resolve the issue. For more information, see [Generate a Short Code and Create an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_generate_a_shortcode_and_api_client_id.htm&type=5) in Salesforce Help.

### Site ID

The site ID is the name of the site (sometimes called a “channel”) for which you want to access data. For example: `RefArch` or `SiteGenesis`.

To see a list of sites in Business Manager:

1. Go to the Business Manager URL for your instance.
2. Log in using your Account Manager credentials.
3. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

See [Create a Site in Business Manager](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-managing-sites-for-dev.html) in the B2C Commerce documentation.

### Version

For shopper baskets, specify `v1` or `v2`, as applicable.

For all other APIs, specify `v1`.

## Endpoint Example

To get product information for product ID `25695327M` on the `RefArchGlobal` site, combine the base URL with the [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-products:getProduct) endpoint.

```text
https://kv7kzm78.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_zzte_053/products/25695327M?siteId=RefArchGlobal
```

Notice that the name of the endpoint, `getProduct`, doesn’t appear in the URL. The `getProduct` string is only used as an identifier for the endpoint in the documentation. The URL for that endpoint is formulated by adding `products/{productID}` to the base URL.

## Query Parameters

The full URL in our endpoint example also includes a required query parameter, `siteId`, to the query string.

Many endpoints have required query parameters. For the Shopper APIs, the `siteId` parameter is often required.

## Other Endpoint Requirements

To make a valid request, a well-formed URL isn't sufficient. Most endpoints have additional requirements for HTTP headers and the request body (usually in the form of a JSON object). Always check the [API specification](https://developer.salesforce.com/docs/commerce/commerce-api/references) to learn the exact requirements of each endpoint.

## Next Steps

To set up an API client for API access, gather the configuration values for your B2C Commerce instances, and refer to [Authorization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization.md). This setup differs for Shopper APIs and SCAPI Admin APIs.

To learn from other Commerce API users, see the [Community](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/community.md) guide.

See also:

- [SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md)
- [Security](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/security.md)
- [Performance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/performance.md)

<!-- document id=9833b015debe48103135256357dc2fb2cec28b5a7d7d0d4b816b55df6ca30d1c url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-basket-management.md -->

# Basket Management

Basket management provides a consistent way to preserve cart state across the server and client while removing the need to fetch or create a basket on every request. Our React Router middleware stores a snapshot of the current basket as a cookie, enabling the basket ID and item count to persist across page refreshes. Full basket state hydration is performed lazily, which helps keep page loads fast.

## Dependencies

| Package        | Version  | Purpose                        |
| -------------- | -------- | ------------------------------ |
| React Router 7 | 7.12.0   | Middleware and context system. |
| React Context  | Built-in | Basket provider state.         |

## Overview

Here's an overview of the basket management process.

1. Middleware initializes context with a cookie snapshot on every request.
2. Root loader passes the snapshot into the `BasketProvider` without hydrating the full basket.
3. Client components hydrate lazily via `useBasket()` when full basket data is required.
4. Middleware updates or deletes the cookie based on the final basket state after loaders or actions finish.

```mermaid
sequenceDiagram
    participant Browser
    box Server
        participant Middleware
        participant Loader
        participant SCAPI
    end

    Browser->>Middleware: Request with basket cookie
    Middleware->>Middleware: Parse snapshot into context
    opt Eager mode only
        Middleware->>SCAPI: getOrCreateBasket(basketId)
        SCAPI-->>Middleware: Full basket payload
    end
    Middleware->>Loader: Continue to loader
    Loader-->>Browser: Return basket snapshot for provider
    Middleware->>Middleware: Update cookie snapshot on response
```

```mermaid
sequenceDiagram
    participant Browser
    box Client
        participant Provider
    end
    participant SCAPI

    Browser->>Provider: useBasket() called
    Provider->>SCAPI: getOrCreateBasket(basketId)
    SCAPI-->>Provider: Full basket payload
    Provider-->>Browser: Context hydrated
```

## Basket Middleware

The server-side middleware is the source of truth for basket state and cookie management.

### Configuration Options

`createBasketMiddleware` accepts these optional settings.

- `mode`: `'lazy'` (default) or `'eager'` hydration.
- `cookieName`: Override the basket cookie name (default `__sfdc_basket`).
- `cookieDurationRegistered`: Cookie duration (TTL) in ms for registered shoppers.
- `cookieDurationGuest`: Cookie duration (TTL) in ms for guest shoppers.
- `currency`: Currency used when creating a basket.
- `calculateBasketSnapshot`: Add custom fields to the cookie snapshot.

**note:** The cookie duration (TTL) default values are set to the same default values for your ECOM instance. If you have customized those values, you'll want to ensure that you are properly configuring these values to be in alignment.

**Context value:**

- `basketResourceContext`: snapshot, basket, hydration state, and error.

**Modes:**

- `lazy` (default): Only the snapshot is set. Full basket is fetched on demand.
- `eager`: Middleware hydrates basket before calling `next()`.

**Cookie snapshot characteristics:**
The cookie snapshot:

- Is stored in `__sfdc_basket`.
- Includes `basketId`, `totalItemCount`, and `uniqueProductCount`.
- Contains optional custom fields via `calculateBasketSnapshot`.

Here's a minimal cookie snapshot configuration for the default lazy mode.

```typescript
// root.tsx
import createBasketMiddleware from "@/middlewares/basket.server";

export const middleware = [
  // ...other middleware
  createBasketMiddleware(),
];
```

### Context Getters and Mutations

Use these helpers in loaders or actions (server) to interact with the request-scoped basket.

```typescript
import {
  getBasket,
  getBasketSnapshot,
  ensureBasketId,
  updateBasketResource,
  destroyBasket,
} from "@/middlewares/basket.server";

export async function loader({ context }) {
  const snapshot = getBasketSnapshot(context);
  const basketResource = await getBasket(context, { ensureBasket: true });
  return { snapshot, basket: basketResource.current };
}

export async function action({ context }) {
  const basketId = await ensureBasketId(context);
  // ...perform SCAPI calls to mutate basket
  updateBasketResource(context, (current) => ({
    ...current,
    basketId: basketId ?? current?.basketId,
  }));
}
```

## Basket Provider and Client Hooks

`BasketProvider` keeps basket data in React context for the client. It receives the snapshot from the root loader, exposes lazy hydration, and updates through hooks.

### Provider Configuration

`BasketProvider` accepts:

- `snapshot`: Cookie-safe basket snapshot for initial render.
- `basket`: Full basket payload (optional, for eager client hydration).

### Provider State Shape

The provider stores:

- `snapshot`: Cookie-safe basket summary.
- `current`: Full basket payload (when hydrated).
- `hydrated`: Whether hydration has been attempted.
- `error`: Hydration error info (if any).

The root loader intentionally passes only `basketSnapshot` to avoid eager basket creation.

```typescript
// root.tsx (simplified)
const basketSnapshot = context.get(basketResourceContext)?.snapshot ?? null;

const providers = [
  // ...other providers
  [BasketProvider, { snapshot: basketSnapshot }],
] as const;
```

### Lazy Hydration (`useBasket`)

`useBasket()` triggers a client-side fetch when:

- A snapshot exists (has `basketId`).
- No full basket is yet in context.

**note:** The client-side fetch is useful for components, such as the minicart, that render outside a full page loader and still need full basket data.

```typescript
import { useBasket } from "@/providers/basket";

export function CartBadge() {
  const basket = useBasket();
  return <span>{basket?.totalProductCount ?? 0}</span>;
}
```

### Updating and Resetting the Basket

Use these hooks in client components after mutations or checkout completion. Common use cases include sharing updated basket data across the React app and clearing basket state after order completion. You typically call `useBasketUpdater` after basket actions, such as adding or removing items, or applying or removing promotions. Updates aren't automatically inferred from route loaders because of the default lazy behavior.

```typescript
import { useBasketUpdater, useBasketReset } from "@/providers/basket";

const setBasket = useBasketUpdater();
const resetBasket = useBasketReset();

// After a successful mutation
setBasket(updatedBasket);

// On checkout completion
resetBasket();
```

## Advanced Configuration

Use these options only when needed.

1. **Eager hydration**: Set `mode: 'eager'` if a route always needs a full basket.
2. **Custom snapshot fields**: Add metadata (for example, pickup flags) via `calculateBasketSnapshot`.
3. **Force refresh**: Call `getBasket(context, { ensureBasket: true })` to hydrate server-side before action logic that requires a full basket.

Example custom snapshot:

```typescript
createBasketMiddleware({
  calculateBasketSnapshot: (basket) => ({
    hasShipments: Boolean(basket.shipments?.length),
  }),
});
```

## Basket Lifecycle Summary

| Phase                 | Behavior                                                         | Example                    |
| --------------------- | ---------------------------------------------------------------- | -------------------------- |
| Initial request       | Middleware reads cookie → snapshot only                          | Cart badge shows count.    |
| Full basket data      | Loaded when the route or component explicitly needs it.          | Cart page loader.          |
| Client-side hydration | Happens during basket actions or when the UI needs data.         | `<CartSheet />` component. |
| Updates and cleanup   | Mutations update context/cookie. `destroyBasket()` clears state. | After checkout completion. |

<!-- document id=2e40b34251225f60af569a013d42a8ab8c7281b270442b5d7a8899bc4b8f9264 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-basket-management.md -->

# Basket Management Differences with PWA Kit

PWA Kit and Storefront Next rely on the Shopper Baskets API, but they differ in where basket state is managed and how it is hydrated in the app lifecycle. PWA Kit commonly uses hook-driven basket reads and mutations in components, while Storefront Next uses middleware, request context, and route loaders and actions to manage basket state with a server-first model.

## Architecture

| Aspect                    | PWA Kit                                                                           | Storefront Next                                                                  |
| ------------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Basket API baseline       | Shopper Baskets V1 is available and remains the default for many existing imports | Basket flows are implemented with `shopperBasketsV2` patterns in loaders/actions |
| Primary integration model | `@salesforce/commerce-sdk-react` hooks in components                              | Middleware + request context + route loaders/actions                             |
| Basket state location     | React Query cache and component hook state                                        | Cookie snapshot on the server plus optional client hydration in provider state   |
| Hydration strategy        | Data fetched when basket hooks run in UI                                          | Lazy by default: hydrate full basket only when required                          |

## Request and State Lifecycle

| Phase                  | PWA Kit                                                                           | Storefront Next                                                                        |
| ---------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Initial request        | Basket data is typically fetched through basket hooks used by rendered components | Middleware reads basket cookie snapshot and attaches it to request context             |
| Basket creation/access | Hook and mutation flows resolve or create basket during shopper actions           | `ensureBasketId` and server helpers manage basket identity in loaders/actions          |
| Client updates         | Mutations update React Query caches and UI state                                  | Actions update server resource context; client can sync through provider updater hooks |
| Post-checkout cleanup  | App-specific hook/mutation flows clear basket                                     | `destroyBasket()` and provider reset hooks clear server/client basket state            |

## Migration Considerations

When moving basket functionality from PWA Kit to Storefront Next:

1. Move basket reads out of components and into route loaders when possible.
2. Move basket mutations to route actions and update request-scoped basket context.
3. Treat basket cookie snapshot data as the default source for lightweight UI state (for example, cart badge counts).
4. Use lazy hydration for full basket payloads only in routes or components that require full basket detail.
5. Keep basket API usage consistent across the codebase to avoid stale or mismatched basket state behavior.

## Key Similarities

- Both storefronts use SCAPI basket endpoints for cart operations.
- Both support guest and authenticated shopper basket flows.
- Both can preserve basket continuity across shopper navigation.

## References

- [Shopper Baskets V1 API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary)
- `sfnext-basket-management`

<!-- document id=5bb526b7ce32975279440ec9ff3cb92a675ce191bf68e51d13ac5493bdab3180 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-begin-file-log-ds.md -->

# BeginFileLog.ds

Review the BeginFileLog.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application. You can use this code to write all logging events to a file.

```
/**************************************************
 * Name: BeginFileLog.ds
 *
 * Description:
 * Create new FileLogger to write all logging events to file.
 * This FileLogger will replace the normal logger in the pdict for
 * the length of the operation, then its contents are appended
 * to the original logger (to avoid writing everything else to file).
 * If the filename is specified, the logger will write to this file
 * in the TEMP directory. Otherwise, the default logs are used.
 *
 * @input CUSTLogger   		: Object
 * @input LogFileName 		: Object
 * @output custLogger     	: Object
 * @output custError     	: Object
 *
 *****************************************************/
importScript("bc_cust:library/common/libContext.ds");
importScript("bc_cust:library/utility/exception/libcustException.ds");
importScript("bc_cust:library/utility/logging/libLog.ds");



function execute(pdict: PipelineDictionary): Number {



    var _context: Context = new Context("BeginFileLog.ds");
    var _logger: Log = Log.getLogger(pdict);

    try {

        // retrieve filename
        var LogFileName: String = pdict.LogFileName;
        if (!empty(LogFileName) && LogFileName.length > 0) {

            _logger = Log.getFileLogger(LogFileName, _logger);
            _logger.debug(_context, "Now logging to file: " + LogFileName);
        } else {

            _logger.warn(_context, "No filename specified, using default DemandWare logs");
            _logger.setLogWriter(Log.DemandWareLogWriter);
            _logger.debug(_context, "Now logging to default log file");
        }

        pdict.custLogger = _logger;
    } catch (e) {

        // Call into error handler
        _logger.error(_context, "Error occurred processing pipelet: " + e.message);

        // wrap error into custom exception
        var exception: custException = new custException(_context, "Error occured in pipelet", e);
        pdict.custError = exception;

        return PIPELET_ERROR;
    }

    return PIPELET_NEXT;
}
```

<!-- document id=73512c8c3e011f8f00d50b14021419d2482352c3eafe8e3b4a610e2b31e04d3f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_clone_best_practices.md -->

# Best Practices for Cloning On-Demand Sandboxes

Follow these recommendations to optimize your sandbox cloning workflow.

| Best Practice                        | Description                                                                                                                                                                               |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Choose Appropriate Resource Profiles | Select the profile that meets your requirements. For cloning, the target profile should be the same size or larger than the source sandbox profile.                                       |
| Review Custom Configurations         | After cloning completes, test all integrations and custom configurations. Update third-party endpoints, keystores, and Business Manager customizations that reference the source sandbox. |
| Manage Cloned Sandboxes              | Delete cloned sandboxes when no longer needed to reduce credit consumption.                                                                                                               |
| Plan Clone Operations                | Where feasible, execute large clone operations during times when sandbox usage is low.                                                                                                    |
| Save Your Work                       | During the clone process, the source sandbox is stopped. Make sure to save any open work before triggering the clone operation.                                                           |
| Monitor Clone Progress               | Monitor the progress of a clone using the Monitor Clone Progress API. Poll the API every 30–60 seconds to check status, but avoid excessive polling, which can trigger rate limits.       |
| Set Time-to-Live Values              | Configure the TTL parameter to automatically clean up temporary clones and avoid consuming unnecessary credits.                                                                           |

<!-- document id=68435b1c66dd4510690e0cc2d9bb3a3f3bfe4be09135e16b2d327fa2ee169106 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/store-locator.md -->

# Boost In-Store Sales with Store Locator

With the [Retail React app template](https://pwa-kit.mobify-storefront.com/), you can include a store locator on your [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) site with reduced implementation time. Shoppers can find store locations worldwide based on ZIP code, city, and more. Extend your store information in Business Manager to customize the displayed location metadata on your site.

This guide explains how to configure and use a store locator.

## Prerequisites

To include a store locator:

- Build your site with:
  - The [Retail React app template](https://pwa-kit.mobify-storefront.com/)
  - Retail React App version 4.0 or later
  - Commerce SDK React version 2.0.1 or later
- Use a [Shopper Login and API Access (SLAS)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) client with the scope `sfcc.shopper-stores`. Follow the steps in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client) or use the [registerClient API endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerClient) to create or update a SLAS public or private client.

  - In the **Scopes** field, include this scope: `sfcc.shopper-stores`.

  A SLAS private client offers several advantages over a public client. See [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html).

## Configure a Store Locator

1. In Business Manager:

   - Add the countries that you want shoppers to find on your site. See [Store Geolocation Data in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_store_geolocation_data.htm&type=5).
   - Add the stores that you want shoppers to find on your site. You can edit store information that you already added. Also, you can bulk import stores. See [Create Stores in B2C Commerce.](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_stores.htm&type=5)

2. In [`app/constants.js`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/cdea5994a47174d7ea38b3f3412b4e4393fe701a/packages/template-retail-react-app/app/constants.js):

   - In the `SUPPORTED_STORE_LOCATOR_COUNTRIES` constant, add the list of countries that you want shoppers to see in the Country dropdown.

     The country codes that you add must match those of the stores that you added in Business Manager.

     If the `SUPPORTED_STORE_LOCATOR_COUNTRIES` constant is empty, when a shopper searches for stores, store locator uses the postal or ZIP code entered by the shopper. Store locator searches in the country specified in the `DEFAULT_STORE_LOCATOR_COUNTRY` constant defined in [`app/constants.js`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/cdea5994a47174d7ea38b3f3412b4e4393fe701a/packages/template-retail-react-app/app/constants.js).

3. In [config/default.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/config/default.js), set the `storeLocatorEnabled` value to `true`.

```
   module.exports = {
    app: {
        ...
        storeLocatorEnabled: true
    },
```

## Initial Store Locator Rendering

For shoppers who have location sharing already enabled on their device, store locator shows results around the GPS location of the shopper’s device.

For shoppers who don’t have location sharing enabled on their device, the initial rendering of the store locator shows results for the default geolocation specified in these constants in [`app/constants.js`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/cdea5994a47174d7ea38b3f3412b4e4393fe701a/packages/template-retail-react-app/app/constants.js).

- `DEFAULT_STORE_LOCATOR_POSTAL_CODE`
- `DEFAULT_STORE_LOCATOR_COUNTRY`

## Constraints

Store locator:

- Returns up to 200 stores at a time
- Searches for stores within a maximum radius of 100 kilometers

  The default unit is `km` (kilometers), as specified in the `STORE_LOCATOR_DISTANCE_UNIT` constant in [`app/constants.js`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/cdea5994a47174d7ea38b3f3412b4e4393fe701a/packages/template-retail-react-app/app/constants.js). Optionally, to use miles for the unit, you can set `STORE_LOCATOR_DISTANCE_UNIT` to `mi`.

  The default maximum radius is 100, as specified in the `STORE_LOCATOR_DISTANCE` constant in [`app/constants.js`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/cdea5994a47174d7ea38b3f3412b4e4393fe701a/packages/template-retail-react-app/app/constants.js). Optionally, you can set `STORE_LOCATOR_DISTANCE` to your chosen maximum radius.

## Troubleshoot Store Locator

This section provides a suggested solution for a common error that you might encounter while using store locator.

### Inaccurate Location Data

**Potential Cause:** Your location data in Business Manager is inaccurate.

**Suggested Solution:** Ensure that your store location information is accurate and reflects any changes in address, phone numbers, operating hours, or other store data. See [Managing Stores in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_managing_stores.htm&language=en_US&release=2.0.1&type=5).

<!-- document id=66d9ed59df6cf44551354b3830c1b4679360c2eaa60c5f516e1b7780b3a7ff22 url=/developer/current/en-us/commerce-cloud/solutions/guides/bot-management.md -->

# Bot Management

Successful bot protection and management for Salesforce B2C Commerce storefronts is a shared responsibility between Salesforce and our customers. These frequently asked questions cover key topics related to our product offering, bot management strategies, and implementation best practices, helping to make sure we gain a common understanding of our shared responsibility.

## Product Offering

**What is the Salesforce B2C Commerce approach to bot management?**

Bot protection efforts by B2C Commerce are focused primarily on maintaining the availability, stability, and performance of our multi-tenant commerce platform. When gaps are identified or issues arise related to bot management, we promptly take action to maintain the availability of the platform.

B2C Commerce offers tools and extensibility within the platform to protect customer origins, and customers own the monitoring and tuning of the controls to protect against bots on a continuous basis. Our approach is to provide customers with configurable options to protect their origins from bots by using our embedded Content Delivery Network (eCDN). This solution gives customers the extensibility to stack another CDN, or use a third-party bot management solution that provides fine-grained control for identifying and controlling bots, according to their unique needs.

**Why doesn’t Salesforce B2C Commerce provide a bot protection solution out-of-the-box?**

When it comes to bot detection and subsequent action, each customer’s business strategy, CDN setup, and sales pattern is unique. A bot protection solution that is too strict or falsely recognizes bots as malicious might work for one customer but could be disruptive for another customer. Therefore, we refrain from identifying which bots are good or bad, and we don’t determine whether certain traffic is allowed to make purchases on our commerce platform.

At B2C Commerce, our approach is to provide customers the configurability to protect their origins against bots via our embedded CDN. Customers also have the extensibility to stack another CDN or use a third-party bot management solution of their choice.

## Bot Management Strategy

**Can I choose a bot management strategy that allows sales to both human shoppers and bots?**

B2C Commerce doesn’t identify bots as good or bad, nor do we suggest whether certain traffic is allowed to make purchases on our commerce platform. Our customers have the flexibility to adopt the bot management strategy that aligns with their business needs.

However, regardless of the bot management strategy, we recommend certain best practices so that bots don’t overwhelm customer origins and our multi-tenant platform. These best practices include regulating the flow of traffic to a customer storefront by following [Traffic Management Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/traffic-management-sk.md), conducting load tests to understand the constraints of the storefront, configuring rate limits and firewall rules to block unwanted traffic, and, for Composable Storefront or Storefront Next on Managed Runtime, restricting SCAPI to Managed Runtime traffic. See [How do I restrict SCAPI to Managed Runtime traffic?](#how-do-i-restrict-scapi-to-managed-runtime-traffic).

For more information about steps to make sure you have a successful flash sale, see [Bot Mitigation Best Practices for Flash Sales](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-mitigation-sk.md) and [Launching a Successful Flash Sale](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-flash-sale-sk.md).

**Can non-malicious crawler traffic cause performance problems even when request rates look normal?**

Yes. Not every bot problem is a purchasing-abuse problem. Well-behaved crawlers, such as search indexers, AI crawlers, and feed fetchers, generally honor robots.txt and aren’t trying to check out. But they can still exhaust a customer origin purely through the volume and cost of the pages they request. Request cost isn’t uniform. Certain URL patterns, such as uncached pages, search and category grids that combine many refinements into one result set, and pages that fan out into many internal calls, can be far more expensive to render than a typical page. When a crawler discovers a large or effectively unbounded space of these URLs (for example, a page that accepts many combined filter or category values), it can generate a continuous stream of the most expensive request the storefront produces, saturating origin resources even though the aggregate request rate appears normal.

As a best practice, identify your most expensive, least-cacheable URL patterns as part of load testing, make sure those patterns aren’t needlessly crawlable or indexable (using robots.txt, noindex, and canonical URLs), and improve their cacheability where possible. Bounding these patterns in storefront code, for example by capping how many filter or category values a single request can combine, removes the cost at the source regardless of who requests the page.

When many different IPs request the same expensive pattern, per-client rate limiting might not help, because each client stays under the threshold while the aggregate still overwhelms the origin. In that case, apply a control keyed on the request pattern itself (such as a Managed Challenge or a block on the expensive URL class) rather than on client identity or request velocity. Deploy such rules in log or monitor mode first to confirm that they match the intended traffic before you enforce them.

**When should I consider a third-party bot management solution?**

Many factors determine whether a third-party bot management solution is warranted. If a sale event meets the following criteria, consider using a third-party solution.

- **Crawler traffic.** Most traffic patterns involve some amount of crawler traffic, such as marketing bots, product restock checkers, feed fetchers, and so on. This traffic usually hits category pages, product detail pages, and Product-Variation calls. At times, the hit rate (requests per second) of crawler traffic becomes substantial, consuming valuable processing seconds and hindering the user experience for human shoppers. Typically, customers can manage crawler bots with effective rate limiting at the CDN layer. However, sometimes crawler bots generate enough IPs to evade even the most effective rate limit radars, warranting the use of a specialized bot mitigation solution.
- **Discounted high-resale products.** Sale items with a high resale value include \*\*\*\* limited release shoes, celebrity branded items, and in general, merchandise that is highly promoted presale. Malicious bots try to buy as much highly sought after inventory as possible during a flash sale, maximizing chances for hefty resale profits. This situation makes it much more challenging for human shoppers to complete purchases.
- **Business requirements.** A business requirement might limit the sale of an item to one per shopper or household. This requirement also means limiting bot sales to one successful transaction, if any. Typically, bots try to overwhelm a site and maximize the number of successful checkouts.
- **General popularity or hype.** The hype surrounding a particular line of apparel or shoes, or perhaps a single product in limited release can be substantial. Hype almost always attracts sophisticated bots, and typically, warrants working with a third-party bot mitigation partner to stop them.

**What third-party solutions does B2C Commerce recommend for enhancing security against advanced bots?**

B2C Commerce provides a robust partner ecosystem on the [LINK Marketplace](https://www.salesforce.com/products/commerce-cloud/partner-marketplace/), our Technology Partner Program. Partners like PerimeterX and Datadome provide pre-built cartridge integrations for B2C Commerce. In scenarios where customers are concerned about fraudulent orders, customers can also subscribe to fraud prevention services like Cybersource or Forter. We recommend that customers do their due diligence and choose a solution that meets the needs of their sale event, and then, enable that solution according to the best practices recommended by the partner.

**Why should I consider deploying a stacked CDN configuration?**

For better control, increased visibility, and more flexibility in security configurations for shopper traffic versus bot traffic, customers can deploy a stacked CDN configuration. In some cases, customers migrating to B2C Commerce might already have a contract with a third-party CDN provider, offering the features and configurations that are specific to their business needs. In other cases, customers might want to enable features that are not available out-of-the-box from the B2C Commerce embedded CDN. In these scenarios, choose to stack a third-party CDN in front of the B2C Commerce eCDN.

**Are there any disadvantages of stacking a third-party CDN in front of the B2C Commerce eCDN?**

A stacked CDN will change the view of traffic to lower CDNs. For example, some protection capabilities, such as the Web Application Firewall (WAF), the firewall, rate limiting, geo IP blocking, and so on, might result in false positives. To avoid these false positives and unintentionally blocking traffic, customers can add the IP address ranges for the third-party CDN to the B2C Commerce eCDN trusted IP list. To adequately protect customer web origins, we strongly recommend that customers enable protection capabilities at the third-party CDN stacked in front of B2C Commerce eCDN.

**Can customers use only a third-party CDN and request removal of the B2C Commerce eCDN?**

Customers can use the CDN of their choice by stacking it in front of the B2C Commerce eCDN. However, even when stacking another CDN, traffic must pass through the B2C Commerce eCDN to make sure there is a single point of entry into our infrastructure. The B2C Commerce eCDN is an embedded feature that’s required for platform functionality, and it provides availability and security benefits.

With traffic flowing through the embedded CDN, B2C Commerce can help to control and protect customer origins from bots, bad actors trying to subvert customer controls, and distributed denial-of-service (DDoS) attacks. The embedded CDN helps us to assist customers during incidents, provides observability into site performance, and protects the B2C Commerce infrastructure.

## Implementation Best Practices

**What are the configuration best practices for flash sales?**

For detailed information about hosting a successful flash sale, see [Bot Mitigation Best Practices for Flash Sales](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-mitigation-sk.md) and [Launching a Successful Flash Sale](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-flash-sale-sk.md). In addition, follow [Traffic Management Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/traffic-management-sk.md) to regulate the flow of traffic coming into customer origins.

**What are some configuration best practices for the outermost CDN in a stacked CDN setup?**

In a stacked CDN setup, B2C Commerce eCDN protection capabilities, such as the Web Application Firewall (WAF), the firewall, rate limiting, geo IP blocking, and so on, are effectively bypassed. In this scenario, we strongly recommend that customers enable these capabilities at the outermost CDN that’s stacked in front of the B2C Commerce eCDN.

The outermost CDN should also monitor malformed URLs and block them at the outset. Add the CDN and other legitimate IP ranges in the allowlist for the B2C Commerce eCDN. Customers with a specialized bot management solution should implement that solution at the third-party CDN (outermost CDN) to regulate the flow of traffic flowing into the B2C Commerce eCDN and origin. Use secret headers at the outermost CDN to make sure that incoming requests are routed through the correct zone in the outermost CDN.

**What are the ways of deploying third-party bot solutions on B2C Commerce?**

Customers can deploy third-party bot solutions at the origin by using cartridges or at the stacked CDN level (outermost edge). Some customers choose to deploy at both layers, implementing a defense-in-depth strategy.

Bot detection and mitigation at the origin by using cartridges requires consumption of resources at the B2C Commerce application layer. When choosing this strategy, take into account the volume of traffic and the characteristics of the sale event.

On the other hand, blocking bots at the edge (by using a stacked CDN, or otherwise) regulates the traffic flowing into the eCDN and prevents resource exhaustion at the origin. However, this strategy requires following stringent best practices to avoid subversion.

**For bot management, what are customers responsible for compared to Salesforce B2C Commerce?**

Successful bot management requires multiple approaches and a defense-in-depth strategy, including many different tools, configurations, and best practices. This defense-in-depth strategy requires a shared responsibility model between Salesforce and our customers.

To help protect customer origins, B2C Commerce provides multiple features out-of-the-box with our embedded CDN. However, customers are responsible for configuring firewalls on our eCDN so that legitimate traffic from known IP addresses (such as proxies, stacked CDNs, and so on) is allowed, and traffic from other sources is blocked or challenged. Customers are also responsible for setting the appropriate sensitivity levels in the firewall and enabling Web Application Firewall (WAF) rules to protect against OWASP top 10 attacks.

For flash sales, customers should evaluate the characteristics of the sale event and consider implementing specialized bot management solutions. If storefronts experience performance issues, customers should identify individual pages or controllers that are under attack, and can raise the threat level of their entire site by using B2C Commerce eCDN settings, while continuing to identify which specific areas are being attacked.

On a continuous basis, customers should analyze traffic patterns and call formats to their origin to identify malformed URLs that are hitting their origin. Customers should also identify their most expensive or least-cacheable URL patterns and confirm that those aren’t needlessly crawlable, since high-volume crawler traffic against expensive pages can exhaust an origin even without any malicious intent. Customers can use third-party bot monitoring tools or CDNs stacked in front of the B2C Commerce eCDN. After customers identify unwanted traffic, Salesforce B2C Commerce teams can help implement custom firewall rules to block or challenge this type of traffic.

For Managed Runtime storefronts, Salesforce provides and rotates the SCAPI Identity Header secret and the allow rule on the SCAPI zone. Customers own the block rule on that zone, its exclusions, and monitoring. See [How do I restrict SCAPI to Managed Runtime traffic?](#how-do-i-restrict-scapi-to-managed-runtime-traffic).

The Salesforce B2C Commerce team is responsible for monitoring the availability of our multi-tenant commerce platform. B2C Commerce will enforce rate limits, firewall rules, and other protective controls on a routine basis to maintain the availability of our platform.

When faced with volumetric attacks with impact to availability or performance, B2C Commerce implements mitigations—such as rate limiting, managed challenges, or blocking access—to prevent bad actors from continuing their attacks, with as little impact to legitimate shoppers as possible, often none at all. When credential stuffing or account takeover activity is detected, B2C Commerce implements mitigations—such as rate limiting, managed challenges, or blocking access—to protect shopper accounts and the platform, with as little impact to legitimate shoppers as possible, often none at all.

**How do I protect Commerce API (SCAPI) traffic?**

Starting with B2C Commerce 26.10, SCAPI traffic has its own eCDN zone, separate from storefront zones. This separation matters for headless and PWA Kit implementations, where clients call SCAPI directly.

On the Production instance, configure custom rules, rate-limiting rules, and IP access lists for that zone in Business Manager (**Administration > Sites > Embedded CDN Settings**). No support case is required. IP access lists are on Realm Security Rules and can allow or block traffic.

Open and configure the zone only on the Production instance. The zone doesn't appear in Business Manager or the CDN API on Development or Staging. There's one SCAPI zone for Development, Staging, and Production. Scope every rule by the org ID in the URL path of the expression, for example `/organizations/{organizationId}/`. A rule that isn't scoped applies to all three environments. Business Manager shows a warning banner on the Security Rules tab as a reminder.

eCDN managed WAF rules, Under Attack mode, mutual TLS (mTLS), HTTP Strict Transport Security (HSTS), hostname and certificate management, and cache rules aren't available on this zone. Cache purge by tag or path is available. The Crypto tab is read-only.

Some rules are Salesforce-managed and locked. An example is an allowlist for valid Managed Runtime (MRT) to SCAPI traffic that skips custom, rate-limiting, and managed WAF checks. Those rules are visible and not editable.

For the full control matrix, see [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5). For verified-bot and leaked-credentials expression fields, see [Create a Custom Firewall Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_create_eCDN_firewall_rule.htm&type=5) and [Create a Rate Limiting Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_eCDN_create_rate_limiting_rule.htm&type=5).

### How do I restrict SCAPI to Managed Runtime traffic?

Starting with B2C Commerce 26.10, Composable Storefront and Storefront Next on Managed Runtime can close the path bots use to bypass the CDN and Managed Runtime and call Shopper APIs directly.

Enable the **Managed Runtime SCAPI Request Identification** feature switch in Business Manager for each instance you want to protect: Development, Staging, and Production. Managed Runtime then attaches a SCAPI Identity Header (SIH) to every request it makes to SCAPI. Salesforce generates and rotates that secret and adds a locked allow rule on the SCAPI zone's **Security Rules** tab. That tab is available when **SCAPI Zone Visibility** is enabled in Business Manager, which is on by default starting with B2C Commerce 26.10. See [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5). Each allow rule is scoped to that instance's org-specific path segment.

Enabling the switch doesn't stop direct Shopper API traffic. You add the block rule on that same tab. Lock down Shopper API and SLAS traffic, not every SCAPI call. Admin APIs authenticate with Account Manager credentials, and blocking them breaks Admin API and B2C CLI use cases.

- **Scope the rule.** Use the same org-specific path segment as that instance's allow rule, and add `/shopper`. For example, **URI Path contains** the org segment and **URI Path contains** `/shopper`. An unscoped rule applies to Development, Staging, and Production. `/shopper` matches the Shopper APIs and the SLAS path and leaves Admin API paths alone. Custom APIs use `/custom/<api>/...` paths that don't contain `/shopper`, so to block one custom endpoint, use the org segment and `/custom/<api>` instead.
- **Order the rule.** Place the block rule directly after that instance's allow rule. Rules evaluate in order, so a block rule above the allow rule also blocks Managed Runtime traffic.
- **Use `block`.** Shopper API callers are API clients and can't solve a challenge, so don't use Managed Challenge.
- **Start in `log` mode.** Run the rule in `log` for at least a full business cycle (about 1-7 days), including scheduled jobs and peak hours. Review matches by path, user agent, and ASN. Look for legitimate direct Shopper API callers, such as native mobile apps, synthetic monitoring, and QA automation. OMS, ERP, and PIM integrations call Admin APIs, so the rule doesn't match them.
- **Keep exclusions narrow.** Route legitimate Shopper API callers through Managed Runtime, or exclude a specific path plus a known signal, such as a client ID or a short list of fixed IPs. Don't allowlist whole IP ranges or networks.
- **Time the switch.** Switch the action to `block` only after that review, and not during a flash sale, a holiday code freeze, or another peak window.
- **Plan a rollback.** Set the block rule back to `log`, or disable it, before you turn off the feature switch. After you enforce the rule, watch for a spike in SCAPI-zone blocks or 403 responses, for example with Log Center anomaly detection.

This control closes the Managed Runtime bypass path for Shopper API traffic. It doesn't replace rate limiting, WAF rules, or other bot mitigation.

Salesforce provides the secret, rotation, and the allow rule. You own the block rule, its exclusions, monitoring, and your existing rate-limit, WAF, and bot controls.

- [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-request-identification.html) for Composable Storefront
- [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-scapi-request-identification.html) for Storefront Next

**Under what conditions should customers enable the Under Attack mode in Business Manager?**

Under Attack mode presents a CAPTCHA to every unique user before they're allowed to see the storefront. During an attempted distributed denial-of-service (DDoS) attack, use this mode only as a last resort to stop the attack.

**How can I protect login against credential stuffing and account takeover (ATO)?**

Credential stuffing targets every authentication surface B2C Commerce exposes: the SFRA `Account-Login` controller, OCAPI `/customers/auth`, and SLAS `/oauth2/login` and `/oauth2/authorize`. Each surface returns clear success and failure signals that attackers use to validate stolen credential lists.

Harden SLAS authentication:

- Follow [SLAS Best Practices](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-best-practices.html), including [Strict Client Auth](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-best-practices.html#strict-client-auth) and [passwordless login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-overview.html).
- Use a [SLAS private client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) wherever the app can securely store a client secret (full-stack or backend-for-frontend architectures). Private clients authenticate with `Authorization: Basic <base64(client_id:client_secret)>`.
- Enable **Strict Client Auth** on private clients. It requires the `x-slas-client-auth` header (Base64 `client_id:client_secret`) on every `/login` and `/authorize` request. Missing or invalid headers return 401. Public and PKCE clients ignore this header, so don't assume it protects public-client flows.
- Offer [passwordless login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-overview.html) when your storefront supports it. Passwordless login verifies identity without a password and helps protect against phishing and brute-force password cracking.

Detect leaked and stuffed credentials at the edge with eCDN custom (firewall) rules. Leaked Credentials Detection fields include `cf.waf.auth_detected`, `cf.waf.credential_check.password_leaked`, `cf.waf.credential_check.username_leaked`, `cf.waf.credential_check.username_and_password_leaked`, and `cf.waf.credential_check.username_password_similar`. Detection scans storefront form-field logins and HTTP Basic credentials in the `Authorization` header, so you can use these fields on storefront login (for example, `/Account-Login`), on SLAS login (for example, `/shopper/auth/v1/organizations/{organizationId}/oauth2/login`), and on OCAPI Shop login (`POST /dw/shop/{version}/customers/auth`).

SLAS login typically arrives on the SCAPI hostname (`{shortcode}.api.commercecloud.salesforce.com`), not the storefront zone. Apply equivalent expressions to SLAS login paths. OCAPI is deprecated, and existing integrations still call `POST /dw/shop/{version}/customers/auth`. That call submits shopper credentials as HTTP Basic in the `Authorization` header and arrives on the storefront zone. Apply the leaked-credentials fields on that zone. See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html) and [Create a Custom Firewall Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_create_eCDN_firewall_rule.htm&type=5).

Example custom rule for storefront login, with the `managed_challenge` action:

```
(http.request.uri.path contains "/Account-Login" and cf.waf.credential_check.password_leaked)
```

Don't apply `js_challenge`, `legacy_captcha`, or `managed_challenge` to SLAS login or to OCAPI `POST /dw/shop/{version}/customers/auth` unless the client can present the challenge to the shopper. Both are API surfaces and can't serve an interactive challenge. For leaked-credentials matches on those logins, use a rate-limiting rule with the `block` action (HTTP 429). Start the rule with the `log` action, monitor matching traffic, and then switch to an enforcement action.

Rate-limit authentication endpoints. eCDN rate-limiting rules separate the **rule expression** (when to evaluate) from the **counting expression** (what increments the counter), so you can count only failed logins:

- **Rule expression:** matches `/login` POST requests
- **Counting expression:** `/login` POSTs with 401 or 403 response codes
- **Threshold:** 5 requests per minute, characteristic `ip.src` (or `cf.unique_visitor_id` for NAT or stacked-CDN environments)
- **Action:** `managed_challenge` for storefront login; `block` for SLAS login and for OCAPI `/customers/auth`

For field descriptions, see [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rule-expression-fields.html). For characteristics and SLAS action guidance, see [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html) and [Create a Rate Limiting Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_eCDN_create_rate_limiting_rule.htm&type=5).

**How can I stop bots from bypassing Managed Runtime and calling Shopper APIs directly?**

See [How do I restrict SCAPI to Managed Runtime traffic?](#how-do-i-restrict-scapi-to-managed-runtime-traffic). That control closes the path bots use to call Shopper APIs without going through Managed Runtime. Scope the block rule to `/shopper` so Admin APIs and B2C CLI calls stay outside it.

**How can Log Center anomaly detection give me an early warning of credential stuffing?**

Use [Anomaly Detection in Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_anomaly_detection.htm&type=5) as the visibility layer that complements eCDN custom rules, rate limiting, and Leaked Credentials Detection. Log Center compares incoming logs with a learned baseline and flags anomalies when data meets your thresholds. Each user can configure up to 10 detectors.

Start with authentication-failure logs on storefront login and SLAS endpoints so you get an early-warning signal rather than waiting for a reactive report.

Results include summary cards (total anomalies, anomaly rate, and last occurrence), an actual-versus-predicted chart, and per-anomaly severity and confidence scores from 0.0 to 1.0:

- Low: less than 0.3
- Medium: 0.3 to less than 0.6
- High: 0.6 to less than 0.8
- Critical: 0.8 and higher

Open related logs from about 30 minutes before and after each anomaly. Optionally send alerts by email (up to five addresses), Slack, or PagerDuty when severity exceeds your threshold. See [Set Up Anomaly Detectors in Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_set_up_anomaly_detectors.htm&type=5).

<!-- document id=358449759e9eb17eb1cb2cbb4d255d7e990fde6b57b009826509cfd99673e1ab url=/developer/current/en-us/commerce-cloud/solutions/guides/bot-mitigation-sk.md -->

# Bot Mitigation Best Practices for Flash Sales

As you might expect, flash sales are an extremely attractive target for bot attacks. During a flash sale (also called a hype or high-volume sale), a large amount of traffic is driven to a storefront for a limited number of products. Flash sales that offer deeply discounted or strictly limited stock tend to attract malicious users, who try to amass a large inventory of the discounted products to resell later for a profit. The deeper the discount and the more limited the inventory, the higher the risk of bot traffic overwhelming your site. However, if you plan ahead for bot mitigation, you can help to make sure that human shoppers are buying your products during the busy holiday season!

## Why Worry About Bots?

First, let’s review how malicious bots operate as they try to obtain large amounts of discounted inventory. Most bot attacks are simple and automated, but these attacks can impact site performance and create a frustrating shopping experience.

Bots target online storefronts by:

- **Creating systemic chaos and instability.** Some bots try to destabilize a system by sending large bursts of traffic. The individual calls in these bursts might not accomplish much, but the sheer volume of calls can temporarily slow down a system and degrade the shopper experience. For example, when a large number of calls go to a product detail page (PDP), page caching can ensure fast response times, but the increased call volume eventually uses processing seconds on the servers.

- **Leveraging security loopholes.** Other malicious bots try to steal sensitive information, like credit card numbers, passwords, and email addresses, from the server side by using injection-style attacks (for example, cross-site scripting). These bots typically target flash sales, because during a short span of time, many shoppers are interacting with an online storefront and providing their personal information to complete a purchase.

- **Crawling or scraping sites.** Bots can crawl and scrape websites, looking for product launches and checking on the inventory availability, and even size and color combinations, for popular items. Web scrapers might seem innocuous, because they don’t purchase large quantities of inventory, but even aggressive crawling by legitimate search bots can reduce a website’s search engine optimization (SEO) ranking.

- **Overrunning flash sales to purchase high-resale products.** Malicious bots try to purchase as much highly sought after inventory as possible during a flash sale, maximizing chances for hefty resale profits. Hype bots can vary by industry, but the most sophisticated ones target sneakers because of the combination of marketing, celebrity branding, and limited inventory. These sneaker bots focus on speed and are constantly evolving, routinely switching tactics and attack vectors. Sneaker bots have a thriving developer community, where anyone interested in acquiring sneakers can purchase bot software and learn how to attack a site. The innovation behind these bots is relentless, making them the most challenging to combat.

## Bot Attack Vectors

Commonly, malicious bots use _script routing_ and _UI routing_ as potential vectors for attacks. Of these two attack vectors, UI routing is less of a concern. With UI routing, a bot typically launches a browser and manipulates UI elements, such as buttons and drop-down menus, to automate browser activity while maintaining a browser session. These attacks tend to be relatively low volume, and are subject to the speed of the device they’re running on and browser render times. In one sense, these types of bots are just fast humans.

However, by using simple tools or Python scripts, bots can use script routing to scrape sites for data, attack popular controllers (for example, Cart-AddProduct and CheckoutServices-PlaceOrder), and direct traffic at its origin in an attempt to bypass protection at the CDN layer. In advanced cases, script routing can penetrate the CDN stack in large numbers, attacking thousands of IPs in a few seconds. Some are also able to float under established rate limits, solve CAPTCHAs with a high level of reliability, and avoid bot protection tools. Some bots that use script routing focus on the Cart and Checkout pipelines, looking for the fastest path to placing an order. Others have been known to take advantage of mobile app implementations and to launch attacks on the Open Commerce API (OCAPI) framework.

Storefronts on Managed Runtime, including Composable Storefront and Storefront Next, have a related vector. Bots and scrapers call Shopper APIs directly and bypass both the storefront CDN and Managed Runtime. Starting with B2C Commerce 26.10, the SCAPI Identity Header (SIH) is the equivalent of selective origin shielding and the secret-header check described below. Managed Runtime attaches the header, and you block direct Shopper API calls on the SCAPI zone. Admin API calls stay outside that rule. See [How do I restrict SCAPI to Managed Runtime traffic?](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-management.md#how-do-i-restrict-scapi-to-managed-runtime-traffic).

To protect your site from script routing, continue reading to learn about the bot mitigation strategies provided by B2C Commerce.

## Bot Mitigation Strategies Provided by B2C Commerce

Salesforce B2C Commerce comes with an embedded Content Delivery Network (CDN). Enabled by default when creating proxy zones, the eCDN Web Application Firewall (WAF) is a layered approach to security and an important component of a multitiered approach to bot mitigation.

The eCDN provides the following bot protection strategies:

- **Allowlist of traffic sources.** If you have a stacked CDN configuration, allowlist IP ranges on the eCDN so that blocking mechanisms are bypassed for known sources of legitimate traffic. When used with a firewall rule, this approach blocks any traffic that isn’t from allowlisted IP ranges.

- **Under Attack mode.** Use the built-in eCDN functionality and consider increasing the threat level or even enabling Under Attack mode during a flash sale. Under Attack mode presents a CAPTCHA to every unique user before they're allowed to see the storefront. For more information, see [Configure the Embedded CDN](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_the_embedded_cdn.htm&type=5).

- **Firewall rules.** Set up firewall rules on the eCDN that log, block, or challenge suspect traffic. Firewall rules are based on a variety of conditions and are built on filters and regular expressions. Salesforce Support can help you create firewall rules that help manage suspect traffic, such as traffic from specific countries, user agents, or paths. This approach is an effective way to control storefront access and minimize malicious traffic during a flash sale.

- **SCAPI zone rules.** Starting with B2C Commerce 26.10, Production Business Manager exposes custom rules, rate-limiting rules, and IP access lists for the SCAPI zone. No support case is required. The zone is shared by Development, Staging, and Production. Open and configure it only on the Production instance. Scope every rule by the org ID in the URL path, for example `/organizations/{organizationId}/`. A rule that isn't scoped applies to all three environments. Under Attack mode and eCDN managed WAF rules remain storefront-zone controls and aren't available on the SCAPI zone. For the control matrix, see [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5).

In addition to the eCDN layer of protection, Salesforce B2C Commerce offers a few other effective options for blocking bot traffic. These solutions typically stop bots that try to bypass the eCDN or CDN stack. The bots target sensitive endpoints, such as the Cart and Checkout pipelines.

A combination of the following strategies yields successful results in helping us protect your storefronts from malicious access, while still allowing vetted traffic.

- **Selective origin shielding (SOS).** To restrict external sources, such as third-party integrations or partners, from bypassing the eCDN or directly accessing the B2C Commerce POD origin, we implemented selective origin shielding (SOS) on all PODs. SOS prevents bots from accessing the origin outside the eCDN, and increases site security and availability by allowing traffic from only a known list of IPs that are essential for internal services to run. Other traffic is not responded to, and the requests time out. For more information, see [B2C Commerce Selective Origin Shielding Security Update](https://help.salesforce.com/s/articleView?id=000359040&type=1).

- **Rewrite rules.** As the name suggests, rewrite rules are a URL rewrite framework that can block traffic at the origin. This framework checks for certain paths and identifies mistakes that bots make when trying to spoof regular calls. This feature is available on the backend servers as part of the B2C Commerce infrastructure.

  Bots consistently try to exploit broken versions of hostnames and sensitive paths, like the Cart and Checkout pipelines, to find implementation vulnerabilities. Thankfully, rewrite rules provide a quick way to block and redirect malicious traffic, based on conditions that match the call signature (call path, referrers, query strings, HTTP method, and so on). Rewrite rules are particularly effective with bots trying to bypass the CDN stack. For more information about using rewrite rules, consult with your Salesforce Support representative.

- **Secret headers.** A secret header is an extra HTTP header that’s typically attached at the CDN level. An example of a secret header is`x-extra_header_name: extra_header_value`. What’s secret about this header? This extra header is not sent back to the end user or client and remains unknown to shoppers and bot operators.

  To verify that incoming requests pass through the eCDN, the presence of the header is checked for and validated at the B2C Commerce origin. This validation is done by rewrite rules that check for the header and block malicious traffic. All requests that fail the header check return a 403 response code.

- **SCAPI Identity Header (SIH).** For storefronts on Managed Runtime, enable **Managed Runtime SCAPI Request Identification** in each instance. Managed Runtime attaches a secret header to every request it makes to SCAPI, and Salesforce adds a locked allow rule on the SCAPI zone **Security Rules** tab. You add the block rule on that tab. Scope it to that instance's org-specific path segment and to Shopper API paths (`/shopper`), so Admin API and B2C CLI calls aren't affected, and place it directly after that instance's allow rule. Use `block`, not Managed Challenge, because Shopper API callers can't solve a challenge. Run the rule in `log` mode before you switch it to `block`. Enabling the feature switch alone doesn't stop direct Shopper API traffic. This control closes the Managed Runtime bypass path only. See [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-request-identification.html) for Composable Storefront and [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-scapi-request-identification.html) for Storefront Next.

## Your Role in Bot Mitigation

In addition to the powerful bot mitigation strategies provided by Salesforce B2C Commerce, you play an important role in helping to protect your storefront from malicious bot attacks.

Consider these best practices to help make sure you have a successful holiday shopping season.

- **Allowlist legitimate traffic sources.** Use the Salesforce eCDN to allowlist legitimate IP ranges for incoming traffic. When you allowlist IP ranges, incoming traffic from those IPs is not subject to some bot defense strategies, such as distributed denial-of-service (DDoS) and rate limiting. When used with firewall rules, this strategy is an effective way to block traffic that’s trying to bypass the frontend CDN.

  Use the CDN Zones API to allowlist IP ranges. For more information about this API, see [CDN Zones](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary), and contact your Salesforce Support representative.

  Allowlist, rate-limit, or block API-direct bot and scraper traffic, for example, sneaker bots calling SCAPI instead of the storefront, with SCAPI-zone IP access lists and rate-limiting rules. Configure those rules on the Production instance.

  If the storefront runs on Managed Runtime, enable **Managed Runtime SCAPI Request Identification** and run the SCAPI-zone Shopper API block rule in `log` mode before the holiday or flash sale. Review the matches, then switch the rule to `block`. Don't change it from `log` to `block` during the sale, a code freeze, or another peak window. See [How do I restrict SCAPI to Managed Runtime traffic?](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-management.md#how-do-i-restrict-scapi-to-managed-runtime-traffic).

- **Leverage WAF protection on eCDN.** As previously mentioned, the eCDN Web Application Firewall (WAF) can help mitigate many bot attacks. The WAF rule engine benefits from intelligence and heuristics gained from analyzing traffic all across the web. For more information about setting up and using the eCDN WAF, see [eCDN Web Application Firewall](https://help.salesforce.com/s/articleView?id=cc.b2c_waf_application.htm&type=5).

- **Set up firewall rules.** Consider working with your Salesforce Support representative to set up firewall rules to block and challenge suspect traffic. For example, set up rules that block traffic from certain countries, IPs, and autonomous system numbers (ASNs).

- **Protect login against credential stuffing.** Leaked Credentials Detection applies to storefront login, to SLAS login, and to OCAPI Shop `POST /dw/shop/{version}/customers/auth`. Storefront `/Account-Login` can use `managed_challenge`. SLAS `/oauth2/login` on the SCAPI hostname and OCAPI `/customers/auth` on the storefront zone use a rate-limiting rule with the `log` action, then `block`. For field details and actions, see [Bot Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-management.md).

- **Analyze traffic patterns and call formats.** Bots have a tendency to focus on certain pipelines, and often make mistakes with the call formats. For example, Cart-AddProduct is a crucial transaction that manages basket creation and the path to checkout. Potentially, bots could target a broken version of the calls, like `Cart-Add%43roduct`. Although unsuccessful, these calls consume processing seconds on the platform and can degrade performance.

  Traffic patterns on a storefront constantly change, and bot traffic can begin subtly with a heightened number of calls against common endpoints, such as Product-Variation or product detail pages (PDP). Check for and know the typical traffic patterns for your site, especially during sale events. This information helps you to identify patterns that are consistent (or inconsistent) with your implementation or line of business. Then, work with your Salesforce Support representative to mitigate bot activity. We suggest reviewing B2C Commerce [Reports and Dashboards](https://help.salesforce.com/s/articleView?id=cc.b2c_reports_and_dashboards.htm&type=5) and monitoring upstream at the CDN layer, if using a stacked CDN setup.

- **Evaluate bot management solutions.** Employ specialized third-party solutions that integrate with Salesforce B2C Commerce to tailor a protection package against shopping bots. Key features of most bot management tools include a constantly updated blocklist, and advanced machine learning that scores and rates requests prior to making block or allow decisions. This type of protection becomes more effective after multiple sale events, as more implementation data trains the machine learning models. Just like shopping bots, bot management solutions continually evolve to update their strategies. Some options include PerimeterX, DataDome, Shape, Akamai BotMan, Cloudflare Bot Management, and so on. If you are using one of these solutions, we can advise and evaluate traffic patterns.

- **Create a virtual waiting room.** Especially during the first few minutes of a flash sale, bots send requests from a large number of IPs and cause spikes in traffic. To help make sure your storefront isn’t overwhelmed by bot traffic for popular products in limited stock, create a virtual waiting room. Waiting rooms limit the number of shoppers allowed to purchase products at a given time. When the maximum number of shoppers is reached on designated pages, new shoppers receive a waiting page that doesn’t access backend systems. When paired with presale load testing and traffic forecasting, waiting rooms help control the storefront load while maintaining a positive shopper experience. Create a customized waiting room experience that enhances your brand. (Hello, positive social media feedback!)
  A virtual waiting room also provides you with the opportunity to analyze incoming requests for a traffic signature and understand how human shoppers (and bots) are interacting with your storefront. This knowledge can provide insights that help you tailor your bot mitigation strategies. Consult with your Salesforce Support representative to identify the levels of traffic bursts your storefront can handle, while maintaining optimal performance. Determine the waiting room size, how many shoppers to allow into a waiting room, and which pages should have a waiting room.

- **Review the settings in robots.txt.** To control the crawl rate and site paths for non-malicious bots (for example, search spiders, known marketing crawlers, feed fetchers, and AI crawlers), review and update the settings in your robots.txt file. This approach helps us be proactive with managing “good” bot activity and avoids scenarios of heightened activity during a flash sale. For more information, see [Generate a robots.txt File](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_a_robots_txt_file.htm&type=5).

  `robots.txt` is advisory: crawlers must honor it voluntarily, and it has no enforcement mechanism. eCDN verified-bot fields (`cf.client.bot` and `cf.verified_bot_category`) give you control to allow, challenge, or block traffic at the edge regardless of crawler compliance. You can also rate limit AI crawlers with these fields. Categories include Search Engine Crawler and AI Crawler. Publish the crawl policy in `robots.txt`, then enforce it with a verified-bot rule. For example, apply `managed_challenge` to non-verified-bot traffic on expensive paths while allowing verified search and AI crawlers through. For expression syntax, see [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rule-expression-fields.html).

When faced with volumetric attacks with impact to availability or performance, B2C Commerce implements mitigations—such as rate limiting, managed challenges, or blocking access—to prevent bad actors from continuing their attacks, with as little impact to legitimate shoppers as possible, often none at all. Configuring allowlists, firewall rules, and monitoring in advance is the most effective way to reduce this risk. For more information, see [Shared Responsibility Model](https://help.salesforce.com/s/articleView?id=cc.b2c_shared_responsibility_model.htm&type=5), [Security Managed by Salesforce](https://help.salesforce.com/s/articleView?id=cc.b2c_security_managed_by_salesforce.htm&type=5), and [Security Managed by Customer](https://help.salesforce.com/s/articleView?id=cc.b2c_security_managed_by_customer.htm&type=5).

By implementing these bot mitigation best practices, you can host a flash sale knowing that your site is prepared to manage malicious attacks and reduce the chance of bots getting large amounts of inventory. And remember: When you start planning for a flash sale, engage the Salesforce B2C Commerce team and your Support representative. We’re here to help!

<!-- document id=68963669f367287091e62ff472b8b5228b79543423fcd61bcd6e4c77df058463 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-browser-comp.md -->

# Browser Compatibility for Storefront Next

Check out the browsers that Storefront Next supports for various devices and desktops.

### Mobile Phones and Tablets

| Operating System | Browsers                                               |
| :--------------- | :----------------------------------------------------- |
| Android          | Last two major versions of Chrome and Samsung Internet |
| iOS              | Last two major versions of Chrome and Safari           |

### Desktops and Laptops

| Operating System | Browsers                                                |
| :--------------- | :------------------------------------------------------ |
| macOS and Linux  | Last two major versions of Safari, Firefox, and MS Edge |
| Windows          | Last two major versions of Chrome, Firefox, and MS Edge |

## Underlying Framework Browser Compatibility

Storefront Next's browser compatibility depends on its underlying frameworks: Vite and Tailwind CSS. These frameworks set the minimum baseline browser versions, which are often lower than what Storefront Next officially supports, which is the last two major versions of each browser. Storefront Next doesn't guarantee support for these baseline versions for older browsers, especially for browsers that are more than two years old. For reference, these are the baseline browser versions that are supported by Vite and TailwindCSS.

- Vite targets [Baseline](https://web-platform-dx.github.io/baseline/) widely available features. For details, see [Supported browsers](https://web-platform-dx.github.io/supported-browsers/) in the Vite documentation.
- TailwindCSS publishes its own supported browsers. For details, see the [Browser support](https://tailwindcss.com/docs/compatibility#browser-support) in the TailwindCSS documentation.

<!-- document id=ef178fa75972017e84ce841ec1db4af68bc76099e24bfd29f217e5477fed92b4 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-storybook.md -->

# Build and Test Components with Storybook

Your Storefront Next app includes [Storybook](https://storybook.js.org/). Storybook is an open-source frontend tool for building, viewing, testing, and documenting React UI components. With Storybook in Storefront Next, you can explore the built-in Storefront Next components, build components in isolation, run automated tests, and create component documentation. Using Storybook for component development leads to easier component discoverability, faster development, higher component quality, and reduced regressions.

Use Storybook to perform these tasks.

- Preview and learn about components in different rendered states, variants, and scenarios, such as light or dark mode and different screen sizes.
- Develop components in isolation without running the entire app or dealing with server and state logic.
- Run automated tests, including interaction tests, snapshot tests, and accessibility (a11y) tests.
- Create interactive documentation for designers and developers.

## Storybook Stories

A story is a single, isolated rendered state of a UI component. It's like an example component or a test case that shows how the component looks or behaves in different states. The component developer can provide multiple stories for each component. For example, stories for an address card can include a default address card, a preferred address card with a preferred badge, an address card with no action buttons, and an international address card.

## Start Storybook and Browse Components

To start Storybook in your Storefront Next app, run this command. Make sure to have install the project dependencies first with `pnpm install`.

```
pnpm storybook
```

After you run this command, a web page opens and shows the Storybook component library. In Storybook, browse each component, read its documentation, and check its stories to view how the component looks and behaves in different states.

To view the standard components that are available in the Storefront Next template, check out the public [Storybook instance](https://reimagined-adventure-n22pn7v.pages.github.io/).

In this section:

- [Create a Storybook Story](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storybook-create-story.md)
- [Storybook File and Folder Structure](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storybook-structure.md)
- [Test Components in Storybook ](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storybook-test.md)

<!-- document id=632441fcc75dd4033ef85f8190c721852957eea1155fd5a0e628fe38e8ad87e1 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/work-with-baskets-orders.md -->

# Build Baskets and Place Orders

B2C Commerce API (SCAPI) supports checkout through the [Shopper Baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary), [Shopper Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary), and [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) API families.

This topic outlines best practices for constructing and submitting baskets, and provides high-level guidance on how to approach payment processing with SCAPI.

**important:** Never pass payment card data to B2C Commerce. Instead, have the shopper provide payment card data directly to the payment provider using the provider's script/iframe, and pass the token returned from the provider to the API. Validate the token, and if the token is valid, accept the order, otherwise reject it.

This article assumes that you are interacting with a payment gateway from which you get a payment token.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Prerequisites

Make sure that you have implemented:

- A payment gateway
- A strategy for how you will create orders. In SCAPI, the recommended strategy is to create an order before you validate payment.
- A SLAS private client or SLAS public client. The code examples provided in this topic use a private client. For details, see [Create a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client).

## Build a Basket

You have two options for building baskets:

- Build a basket incrementally
- Build a basket with a single request

### Build a Basket Incrementally

When you build a basket incrementally, you enter the information as the shopper provides it. This persists the basket in the B2C Commerce backend, and is useful if you can’t easily persist the basket.
It also performs validation and returns API errors as you go, as shown in the following code examples. Note that the comments included in the code examples are provided for clarity and must be removed for the code to work.

```sh
#!/bin/bash
set -euo pipefail

CODE='kv7kzm78'
ORG='f_ecom_zzrf_001'
SITE='RefArchGlobal'
CLIENT=
SECRET=

BASE="https://$CODE.api.commercecloud.salesforce.com"
BASE_AUTH="$BASE/shopper/auth/v1/organizations/$ORG"
BASE_BASKETS="$BASE/checkout/shopper-baskets/v1/organizations/$ORG"

# 1. Get guest token (Note: The following code provides a rough flow using a private client. The commands for getting a token for a public client differ.)
TOKEN=$(
  curl "$BASE_AUTH/oauth2/token" \
    -sS --fail-with-body \
    -u "$CLIENT:$SECRET" \
    -d 'grant_type=client_credentials' | jq -r .'access_token'
)

# 2. Create basket (Note: When you create a basket, you store a reference to the basket, and use the reference in subsequent calls.)
BASKET=$(
  curl "$BASE_BASKETS/baskets?siteId=$SITE" \
    -sS --fail-with-body \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "productItems": [{ "quantity": 1, "productId": "682875090845M"}]}' | jq -r '.basketId'
)

# 3. Set basket customer
curl "$BASE_BASKETS/baskets/$BASKET/customer?siteId=$SITE" \
  -sS --fail-with-body -o /dev/null \
  -X 'PUT' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "shopper@salesforce.com" }'

# 4. Set shipping address. All baskets have a shipment called `me`. For multiple shipments, you must create those shipments yourself. See [createShipmentForBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=createShipmentForBasket).
curl "$BASE_BASKETS/baskets/$BASKET/shipments/me?siteId=$SITE" \
  -sS --fail-with-body -o /dev/null \
  -X 'PATCH' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "shippingAddress": {
          "firstName": "Joe",
          "lastName": "Shopper",
          "address1": "415 Mission St.",
          "city": "San Francisco",
          "postalCode": "94105",
          "stateCode": "CA",
          "countryCode": "US"
        }
      }'

# 5. Get applicable shipping methods (Note: This example defaults to the first shipping method that is available.)
SHIPPING_METHOD=$(
  curl "$BASE_BASKETS/baskets/$BASKET/shipments/me/shipping-methods?siteId=$SITE" \
    -sS --fail-with-body \
    -H "Authorization: Bearer $TOKEN" | jq -r '.applicableShippingMethods[0].id'
)

# 6. Set shipping method
curl "$BASE_BASKETS/baskets/$BASKET/shipments/me/shipping-method?siteId=$SITE" \
  -sS --fail-with-body -o /dev/null \
  -X 'PUT' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "'$SHIPPING_METHOD'"}'

# 7. Set payment instrument (Note: This example uses PayPal.)
curl "$BASE_BASKETS/baskets/$BASKET/payment-instruments?siteId=$SITE" \
  -sS --fail-with-body -o /dev/null \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "paymentMethodId": "PayPal" }'

# 8. Set billing address
curl "$BASE_BASKETS/baskets/$BASKET/billing-address?siteId=$SITE&useAsShipping=false" \
  -sS --fail-with-body -o /dev/null \
  -X 'PUT' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "firstName": "Joe",
        "lastName": "Shopper",
        "address1": "415 Mission St",
        "city": "San Francisco",
        "postalCode": "94105",
        "stateCode": "CA",
        "countryCode": "US"
      }'

# 9. Submit order
curl "$BASE/checkout/shopper-orders/v1/organizations/$ORG/orders?siteId=$SITE" \
  -sS --fail-with-body \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "basketId": "'$BASKET'"}' | jq
```

### Build Basket with a Single Request

Create the basket with just one request, and provide the relevant parts you want to fill.
The following example builds an entire basket and its nested documents with one request:

```sh
#!/bin/bash
set -euo pipefail

CODE='kv7kzm78'
ORG='f_ecom_zzrf_001'
SITE='RefArchGlobal'
CLIENT=
SECRET=

BASE="https://$CODE.api.commercecloud.salesforce.com"
BASE_AUTH="$BASE/shopper/auth/v1/organizations/$ORG"
BASE_BASKETS="$BASE/checkout/shopper-baskets/v1/organizations/$ORG"

# 1. Get guest token
TOKEN=$(
    curl "$BASE_AUTH/oauth2/token" \
        -sS --fail-with-body \
        -u "$CLIENT:$SECRET" \
        -d 'grant_type=client_credentials' | jq -r .'access_token'
)

# 2. Create a basket
BASKET=$(
    curl "$BASE_BASKETS/baskets?siteId=$SITE" \
        -sS --fail-with-body \
        -H "Authorization: Bearer $TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
              "productItems": [{ "quantity": 1, "productId": "682875090845M" }],
              "customerInfo": { "email": "shopper@salesforce.com" },
              "shipments": [
                {
                  "shipmentId": "me",
                  "shippingAddress": {
                    "firstName": "Joe",
                    "lastName": "Shopper",
                    "address1": "415 Mission St.",
                    "city": "San Francisco",
                    "postalCode": "94105",
                    "stateCode": "CA",
                    "countryCode": "US"
                  },
                  "shippingMethod": { "id": "GBP001" }
                }
              ],
              "paymentInstruments": [{ "paymentMethodId": "PayPal" }],
              "billingAddress": {
                "firstName": "Joe",
                "lastName": "Shopper",
                "address1": "415 Mission St",
                "city": "San Francisco",
                "postalCode": "94105",
                "stateCode": "CA",
                "countryCode": "US"
              }
            }' | jq -r '.basketId'
)

# 3. Submit order
curl "$BASE/checkout/shopper-orders/v1/organizations/$ORG/orders?siteId=$SITE" \
    -sS --fail-with-body \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "basketId": "'$BASKET'"}'
```

## Retrieve an Existing Basket

To retrieve an existing basket, use the Shopper Customers API `getCustomerBaskets` endpoint.

The following example retrieves customer baskets using a customer ID:

```sh
curl  "$BASE/customer/shopper-customers/v1/organizations/$ORG/customers/$CUSTOMERID/baskets?siteId=$SITE' \
  -sS --fail-with-body \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
```

The following example retrieves a basket using a basket ID:

```sh
curl  "$BASE_BASKETS/baskets/$BASKETID?siteId=$SITE' \
  -sS --fail-with-body \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
```

<!-- document id=0c200009f6e5cc17bada0eff3aa5015fa0c07c51e36abcb1a931638a8a4f2a20 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-pd-site-wide-regions.md -->

# Build Content Blocks for Site-Wide Regions in PWA Kit

Build content blocks that merchants add to site-wide regions, such as the header and the mega menu. These site-wide content blocks appear on every page containing the region. With content blocks in site-wide regions, merchants maintain brand consistency and save time when updating promotional messages or navigation elements that appear site-wide. For example, merchants can add an announcement banner to a header that appears on every page in the storefront.

Let's walk though the process of building an announcement banner content block that can be added to the storefront header as an example. The announcement banner will appear on all page headers in the storefront. A Page Designer component (instance id header) exposes an announcement region above the storefront's header. This task involves two React components, their registry entries, and two B2C descriptors.

- A `useComponent` fetch of the site-wide component in your app shell, rendered inline through `<Region>`.
- An `EmbeddedSubtreeProvider` wrapper (new in `storefront-next-runtime@1.2.0`) that tells the design runtime this subtree is a site-wide region, not a page.
- Two new components: a `Header` layout that hosts the region and an `AnnouncementBanner` content block, in addition to their registry and type-map entries.
- Two new cartridge descriptors, one of which uses the site-wide-region `"embedded": true` flag and an explicit `component_id`.

## Prerequisites

- [PWA Kit](https://github.com/SalesforceCommerceCloud/pwa-kit/) v3.21 or later.
- Page Designer integration with PWA Kit. See [Integrate Page Designer with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.md).
- `@salesforce/commerce-sdk-react` with the `useComponent` hook. Import `useComponent` from the package root. Import `Region`/`Page`/`registry`/`PageDesignerProvider` from the `/page-designer` subpath.
- `@salesforce/storefront-next-runtime@1.1.0` or later—this is the version that exports `EmbeddedSubtreeProvider` from `@salesforce/storefront-next-runtime/design/react/core`. Site-Wide Regions don't work on version `0.4.2`.
- Node 24 or later for tooling and local development.
- A SLAS client with the `sfcc.shopper-experience` scope—`useComponent` calls the Shopper Experience `getComponent` endpoint.

### Use New Fields from the PWA Kit Template

The Site-Wide Regions for Content Blocks feature requires [PWA Kit](https://github.com/SalesforceCommerceCloud/pwa-kit/) v3.21 or later, which includes new fields that this feature uses. If you built your storefront with v3.21 or later of the template, your storefront contains the new fields. Otherwise, add the new fields manually.

The new fields are:

- `embedded`: This field indicates whether the header component can contain a content block.
- `component_id`: This field identifies the header and is required for calling the `getComponent` B2C Commerce API (SCAPI) call to get the embedded content block in a page that's not in Page Designer—a page that's not a product detail or listing, about us, or home page. The get Component API endpoint is: `GET /experience/shopper-experience/v1/organizations/{organizationId}/components/{componentId}`. See [Shopper Experience](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary) endpoints.

## Step 1: Add the `Header` Layout Component

The header component holds no chrome of its own—your storefront's existing `Header` or `AboveHeader` remain the visual header. This component's only job is to expose the `announcement` region so content managers have a place to drop blocks. It is a thin `<Region>` passthrough.

```jsx
// file: app/page-designer/layouts/header/index.jsx

import React from 'react'
import PropTypes from 'prop-types'
import {Region} from '@salesforce/commerce-sdk-react/page-designer'

/**
 * Header component (site-wide region host).
 *
 * A single Page Designer component (instance id `header`) whose sole purpose is to
 * expose an `announcement` region above the storefront header. It holds no chrome of its
 * own—the storefront's own `Header`/`AboveHeader` remain the visual header. Authors place
 * content blocks (e.g. Announcement Banner) into the `announcement` region.
 *
 * @param {object} props
 * @param {object} props.component - The Page Designer component data (injected by the V2 pipeline).
 * @returns {React.ReactElement|null} - The rendered announcement region, or null when absent.
 */
export const Header = ({component}) => {
  return <Region component={component} regionId="announcement" />
}

Header.propTypes = {
  component: PropTypes.object.isRequired
}

Header.displayName = 'PageDesignerHeader'

export default Header
```

In this example:

- The header component renders a single named region. `<Region component={component} regionId="announcement" />` renders whatever content blocks a merchandiser placed in the `announcement` region of this component instance.
- `component` is required. When the V2 pipeline renders this component (via `<Region>`/`<Component>`), it injects the component's own data as the `component` prop. You pass it to the nested `<Region>`.
- Export the header component from the layouts barrel so that the component map can import it (Step 4).

## Step 2: Add the `AnnouncementBanner` Content Block

This is the actual content block a merchandiser drops into the header's `announcement` region. It is a leaf component: no regions, just editable attributes.

```jsx
// file: app/page-designer/content/announcement-banner/index.jsx

import React from 'react'
import PropTypes from 'prop-types'
import {
  Box,
  Skeleton,
  Text,
  Link as ChakraLink
} from '@salesforce/retail-react-app/app/components/shared/ui'
import Link from '@salesforce/retail-react-app/app/components/link'
import {isAbsoluteURL} from '@salesforce/retail-react-app/app/page-designer/utils'

const HEIGHT_STYLE = {
  sm: {py: 1.5, fontSize: 'xs'},
  md: {py: 3, fontSize: 'sm'},
  lg: {py: 5, fontSize: 'md'}
}

const ALIGNMENT_JUSTIFY = {
  left: 'flex-start',
  center: 'center',
  right: 'flex-end'
}

const COLOR_SCHEME_STYLE = {
  primary: {bg: 'blue.600', color: 'white'},
  secondary: {bg: 'gray.100', color: 'gray.800'},
  destructive: {bg: 'red.600', color: 'white'}
}

const normalize = (value, allowed, fallback) => (allowed.includes(value) ? value : fallback)

/**
 * Announcement Banner component.
 *
 * A banner for announcements, promotions, and alerts. Rendered as an authorable
 * content block; typically placed in the header's `announcement` region.
 *
 * @param {object} props
 * @param {string} props.message - The announcement text (required; renders nothing when empty).
 * @param {string} [props.linkUrl] - Optional link target. Rendered only with linkText.
 * @param {string} [props.linkText] - Optional link label. Rendered only with linkUrl.
 * @param {string} [props.colorScheme] - primary | secondary | destructive (default primary).
 * @param {string} [props.height] - sm | md | lg (default md).
 * @param {string} [props.alignment] - left | center | right (default center).
 * @returns {React.ReactElement|null} - AnnouncementBanner component.
 */
export const AnnouncementBanner = ({
  message,
  linkUrl,
  linkText,
  colorScheme,
  height,
  alignment
}) => {
  if (!message) return null

  const heightStyle = HEIGHT_STYLE[normalize(height, ['sm', 'md', 'lg'], 'md')]
  const resolvedAlignment = normalize(alignment, ['left', 'center', 'right'], 'center')
  const colorStyle =
    COLOR_SCHEME_STYLE[normalize(colorScheme, ['primary', 'secondary', 'destructive'], 'primary')]

  const isAbsolute = isAbsoluteURL(linkUrl)
  const LinkWrapper = isAbsolute ? ChakraLink : Link
  const linkProps = isAbsolute ? {href: linkUrl} : {to: linkUrl}

  return (
    <Box
      role="status"
      className={'announcement-banner'}
      data-testid={'announcement-banner'}
      display="flex"
      alignItems="center"
      gap={2}
      px={{base: 4, md: 10}}
      letterSpacing="wide"
      justifyContent={ALIGNMENT_JUSTIFY[resolvedAlignment]}
      {...heightStyle}
      {...colorStyle}
    >
      <Text textAlign={resolvedAlignment} margin={0}>
        {message}
        {linkUrl && linkText && (
          <>
            {' '}
            <LinkWrapper
              {...linkProps}
              textDecoration="underline"
              fontWeight="medium"
              whiteSpace="nowrap"
              color="inherit"
            >
              {linkText}
            </LinkWrapper>
          </>
        )}
      </Text>
    </Box>
  )
}

AnnouncementBanner.propTypes = {
  message: PropTypes.string,
  linkUrl: PropTypes.string,
  linkText: PropTypes.string,
  colorScheme: PropTypes.string,
  height: PropTypes.string,
  alignment: PropTypes.string
}

AnnouncementBanner.displayName = 'AnnouncementBanner'

/**
 * Suspense fallback for the Announcement Banner. Mirrors the default md/center/primary
 * height so switching from fallback to real content does not shift layout.
 *
 * @returns {React.ReactElement} - Skeleton placeholder.
 */
export function AnnouncementBannerFallback() {
  return (
    <Box
      aria-hidden="true"
      display="flex"
      alignItems="center"
      justifyContent="center"
      px={{base: 4, md: 10}}
      py={3}
      bg="blue.600"
    >
      <Skeleton height="16px" width="192px" />
    </Box>
  )
}

AnnouncementBannerFallback.displayName = 'AnnouncementBannerFallback'

export default AnnouncementBanner

// The V2 registry reads a module's named `fallback` export to render during the
// client Suspense boundary while the component chunk loads.
export {AnnouncementBannerFallback as fallback}
```

In this example:

- The prop names are the descriptor's attribute ids. `message`, `linkUrl`, `linkText`, `colorScheme`, `height`, `alignment` map 1:1 to the `attribute_definitions` you author in Step 5. Keep them in sync.
- `if (!message) return null`**.** A banner with no message renders nothing—a required attribute, defensively enforced in the component too.
- Token-based color/height/alignment, normalized. `normalize()` clamps any unexpected value back to a safe default (`md`/`center`/`primary`) so a bad authored value can't break layout or contrast.
- Absolute vs. relative links. `isAbsoluteURL` (from `page-designer/utils`) picks between the Chakra `Link` (external `href`) and the app router `Link` (internal `to`), so internal links stay client-side.
- The `fallback` named export is the Suspense placeholder. The V2 registry renders a module's `fallback` export while the component's code-split chunk loads. Exporting `AnnouncementBannerFallback as fallback` wires that up; the skeleton mirrors the default banner height to avoid layout shift.

Add a content barrel so the component map can import from a single path:

```js
// file: app/page-designer/content/index.js

export * from './announcement-banner'
```

## Step 3: Wire the Site-Wide Region into the App Shell

In your full storefront shell (`StorefrontApp`), fetch the `header` component with `useComponent` and render its `announcement` region above the storefront header, wrapped in `EmbeddedSubtreeProvider`.

```jsx
// file: app/components/_app/index.jsx  (excerpts)
// Add useComponent to the existing commerce-sdk-react import
import {
  useAccessToken,
  useCategory,
  useComponent,
  useShopperBasketsMutation,
  useUsid
} from '@salesforce/commerce-sdk-react'

// Add Region to the existing page-designer import
import {PageDesignerProvider, Region} from '@salesforce/commerce-sdk-react/page-designer'
import PageDesignerInit from '@salesforce/retail-react-app/app/components/page-designer-init'

// New for site-wide regions: the embedded-subtree provider from storefront-next-runtime 1.2.0
import {EmbeddedSubtreeProvider} from '@salesforce/storefront-next-runtime/design/react/core'
```

Inside `StorefrontApp`, fetch the site-wide component alongside the other top-level data hooks:

```jsx
// file: app/components/_app/index.jsx  (inside StorefrontApp)
// Site-wide header region: a Page Designer component (instance id `header`) that
// exposes an `announcement` region rendered above the storefront header.
// `useComponent` is Page-Designer-mode aware (handles mode/pdToken internally).
const {data: embeddedHeader} = useComponent({parameters: {componentId: 'header'}})
```

Then render the region above `<AboveHeader />`, gated on the component existing:

```jsx
// file: app/components/_app/index.jsx  (inside the header wrapper, non-checkout branch)
<Box {...styles.headerWrapper}>
    {!isCheckout ? (
        <>
            {embeddedHeader && (
                <EmbeddedSubtreeProvider embedded>
                    <Region component={embeddedHeader} regionId="announcement" />
                </EmbeddedSubtreeProvider>
            )}
            <AboveHeader />
            <Header
                onMenuClick={onOpen}
                {/* …existing props… */}
            />
        </>
    ) : (
        {/* …checkout header… */}
    )}
</Box>
```

In this example:

- `useComponent({parameters: {componentId: 'header'}})` fetches the site-wide component. The `componentId` is a fixed, well-known ID (`'header'`). It matches the descriptor's `component_id` in Step 5. Unlike Content Block Editor, nothing supplies this ID per-request. The storefront always asks for the same component.
- `useComponent` is already Page-Designer-mode aware. It reads `mode` or `pdToken` from the provider config (the Content Block Editor plumbing you already have) and switches to `rawResponse: true` in design or preview mode. You don't add any mode handling here.
- Gate on `embeddedHeader`. Until the component resolves—or if no header content is authored—render nothing. There is no banner or layout shift beyond the component's own fallback.
- `EmbeddedSubtreeProvider embedded` marks this subtree as a site-wide region, which is the new runtime piece. It tells the design runtime that the wrapped `<Region>` is a site-wide region living in your layout (not a Page Designer page), so Content Block Editor can target and edit it in place. The `embedded` boolean prop turns that behavior on.
- The `embedded` boolean prop renders the same `announcement` region as the `Header` layout component (Step 1). The app-shell path (`<Region component={embeddedHeader} regionId="announcement" />`) is what shows on the live storefront. The `Header` layout component is the registry-resolved rendering used when the component is reached through the V2 pipeline (e.g. in Content Block Editor). Both render the identical region.
- Not on checkout. The header region renders only in the non-checkout branch, matching where the storefront normally shows its header.

## Step 4: Register the New Components

Add the two new components to the eager type map and the lazy importer registry. Site-wide regions add `Header` and `AnnouncementBanner`.

```js
// file: app/page-designer/component-map.js

import {ImageWithText, ImageTile} from '@salesforce/retail-react-app/app/page-designer/assets'
import {
  Carousel,
  Header,
  MobileGrid1r1c,
  MobileGrid2r1c,
  MobileGrid2r2c,
  MobileGrid2r3c,
  MobileGrid3r1c,
  MobileGrid3r2c
} from '@salesforce/retail-react-app/app/page-designer/layouts'
import {AnnouncementBanner} from '@salesforce/retail-react-app/app/page-designer/content'

// Map Page Designer component type IDs to React components
export const PAGEDESIGNER_TO_COMPONENT = {
  'commerce_assets.imageAndText': ImageWithText,
  'commerce_assets.imageTile': ImageTile,
  'commerce_layouts.carousel': Carousel,
  'commerce_layouts.header': Header,
  'commerce_layouts.mobileGrid1r1c': MobileGrid1r1c,
  'commerce_layouts.mobileGrid2r1c': MobileGrid2r1c,
  'commerce_layouts.mobileGrid2r2c': MobileGrid2r2c,
  'commerce_layouts.mobileGrid2r3c': MobileGrid2r3c,
  'commerce_layouts.mobileGrid3r1c': MobileGrid3r1c,
  'commerce_layouts.mobileGrid3r2c': MobileGrid3r2c,
  'commerce_assets.announcementBanner': AnnouncementBanner
}
```

Export `Header` from the layouts barrel so the map import above resolves:

```js
// file: app/page-designer/layouts/index.js
export * from './carousel'
export * from './header'
export * from './mobileGrid1r1c'
export * from './mobileGrid2r1c'
export * from './mobileGrid2r2c'
export * from './mobileGrid2r3c'
export * from './mobileGrid3r1c'
export * from './mobileGrid3r2c'
```

Add the two lazy importers to the registry:

```js
// file: app/page-designer/registry.js  (added lines)
export function initializeRegistry() {
  // …existing importers (imageAndText, imageTile, carousel, mobileGrid*)…
  registry.registerImporter('commerce_layouts.carousel', () => import('./layouts/carousel'))
  registry.registerImporter('commerce_layouts.header', () => import('./layouts/header'))
  registry.registerImporter('commerce_assets.announcementBanner', () =>
    import('./content/announcement-banner')
  )
}
```

Each `typeId` is `{group}.{componentId}`, which must equal `{descriptor-folder}.{descriptor-filename}`. For site-wide regions that means:

| **typeId**                           | **Map Key**          | **Registry Importer Key**            | **Descriptor Path**                       |
| ------------------------------------ | -------------------- | ------------------------------------ | ----------------------------------------- |
| `commerce_layouts.header`            | `Header`             | `commerce_layouts.header`            | `commerce_layouts/header.json`            |
| `commerce_assets.announcementBanner` | `AnnouncementBanner` | `commerce_assets.announcementBanner` | `commerce_assets/announcementBanner.json` |

**important:** All three columns must match byte-for-byte, or the component silently fails to resolve.

## Step 5: Author and Upload the Descriptors (Cartridge)

As with Content Block Editor, the React side only teaches the storefront how to _render_. The B2C Commerce side needs descriptors for both new components. The header descriptor is the one that uses the site-wide-region fields.

### The header descriptor

```json
// file: cartridges/app_pwa_base/cartridge/experience/components/commerce_layouts/header.json
{
  "name": "Header",
  "description": "Header component that exposes a site-wide announcement region above the storefront header.",
  "group": "commerce_layouts",
  "arch_type": "headless",
  "embedded": true,
  "component_id": "header",
  "region_definitions": [
    {
      "id": "announcement",
      "name": "Announcement",
      "description": "Displayed above the header."
    }
  ],
  "attribute_definition_groups": [
    {
      "id": "header",
      "name": "Header",
      "description": "Global site header with an announcement region.",
      "attribute_definitions": []
    }
  ]
}
```

In this example:

- `"embedded": true`. This field marks the component as hosting a _site-wide region_—a fixed component that lives in your storefront chrome, not one dropped into a Page Designer page. It is the flag Content Block Editor and the Content Blocks editor use to treat it as a site-wide region.
- `"component_id": "header"`. This field fixes the instance ID so the storefront can fetch it by a known ID—exactly the `componentId` your app shell passes to `useComponent({parameters: {componentId: 'header'}})` in Step 3.
- `region_definitions` declares the `announcement` region. The region `id` (`announcement`) is what both the app-shell `<Region regionId="announcement">` and the `Header` layout component render. It's where the merchandiser drops the banner.
- No editable attributes on the header. `attribute_definitions` is empty—the header is a structural container. The editable content lives in the banner it hosts.

**note:** `embedded` and `component_id` are site-wide-region fields. A standard Content Block Editor component (leaf or layout, like the carousel) doesn't use these. If you're adding a normal editable component, follow the Content Block Editor guide's descriptor shape instead.

### The Announcement Banner Descriptor

The banner is a normal leaf content block—no `embedded` flag. Its `attribute_definitions` are the props the React component reads (Step 2).

```json
// file: cartridges/app_pwa_base/cartridge/experience/components/commerce_assets/announcementBanner.json
{
  "name": "Announcement Banner",
  "description": "A banner for announcements, promotions, and alerts.",
  "group": "commerce_assets",
  "arch_type": "headless",
  "region_definitions": [],
  "attribute_definition_groups": [
    {
      "id": "announcementBanner",
      "name": "Announcement Banner",
      "description": "A banner for announcements, promotions, and alerts.",
      "attribute_definitions": [
        {
          "id": "message",
          "name": "Message",
          "type": "string",
          "required": true,
          "description": "The announcement text."
        },
        {
          "id": "linkUrl",
          "name": "Link URL",
          "type": "url",
          "required": false,
          "description": "Optional link target. Shown only when Link Text is also set."
        },
        {
          "id": "linkText",
          "name": "Link Text",
          "type": "string",
          "required": false,
          "description": "Optional link label. Shown only when Link URL is also set."
        },
        {
          "id": "colorScheme",
          "name": "Color Scheme",
          "type": "enum",
          "required": false,
          "values": ["primary", "secondary", "destructive"],
          "default_value": "primary",
          "description": "Token-based color treatment for guaranteed contrast."
        },
        {
          "id": "height",
          "name": "Height",
          "type": "enum",
          "required": false,
          "values": ["sm", "md", "lg"],
          "default_value": "md",
          "description": "Vertical density of the banner."
        },
        {
          "id": "alignment",
          "name": "Alignment",
          "type": "enum",
          "required": false,
          "values": ["left", "center", "right"],
          "default_value": "center",
          "description": "Horizontal alignment of the message."
        }
      ]
    }
  ]
}
```

**note:** The six attribute `id`s (`message`, `linkUrl`, `linkText`, `colorScheme`, `height`, `alignment`) are exactly the props the `AnnouncementBanner` component destructures. The `enum` `values` and `default_value`s match the component's `normalize()` allow-lists and fallbacks—keep the two definitions in lockstep.

### Deploy the Cartridge and Register

Deploy the cartridge to B2C Commerce using the CLI. See [Cartridges](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-cartridges.html). Then add it to your site's cartridge path in **Administration > Sites > Manage Sites > {site} > Settings**. After the descriptors are live, author the content in the Content Block editor in **Merchant Tools > Content > Content Blocks**. Create a block of the announcement-banner type, set its properties, and add it as a site-wide region on the header. To learn more, see the steps in [Add a Content Block in a Site-Wide Region](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-page-designer-content-blocks.md) for Storefront Next. The Page Designer steps in Business Manager are identical for any supported storefront type.

Next, reload any storefront page—the banner renders above the header. Open it in the focused visual canvas to edit it in Content Block Editor.

## Step 6: (Optional) Mock Data for Tests and Storybook

If you test the components in isolation, this mock mirrors the shape `useComponent` returns for the header, including a nested announcement banner.

```js
// file: app/mocks/page-designer.js  (excerpt—site-wide-region additions)
export const mockAnnouncementBanner = {
  message: 'Free standard shipping on orders over $50',
  linkUrl: '/sale',
  linkText: 'Shop the sale',
  colorScheme: 'primary',
  height: 'md',
  alignment: 'center'
}

export const mockEmbeddedHeader = {
  id: 'header',
  typeId: 'commerce_layouts.header',
  regions: [
    {
      id: 'announcement',
      components: [
        {
          id: 'announcement-banner-1',
          typeId: 'commerce_assets.announcementBanner',
          data: mockAnnouncementBanner
        }
      ]
    }
  ]
}
```

`mockEmbeddedHeader` has `id: 'header'` and `typeId: 'commerce_layouts.header'`, and its single `announcement` region holds one `commerce_assets.announcementBanner` component whose `data` is the banner attributes. This is the exact shape `<Region component={embeddedHeader} regionId="announcement">` expects—use it to render the subtree without a live `getComponent` call.

## See Also

- [Integrate Page Designer with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.md)
- [Salesforce Help: Page Designer Content Blocks](https://help.salesforce.com/s/articleView?id=cc.b2c_content_blocks.htm&type=5)

<!-- document id=36145882eb3e36ec0fad8a6fa4bdd46aaf0ff2a213f399fc8ce86757a5ff6e08 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-custom-component.md -->

# Build Custom Components

In addition to the Commerce App standard components, you can add custom components to your B2B or D2C store created with an LWR template. Custom Lightning web components (LWC) are easy to build, and they perform well in the web browser that hosts your B2B or D2C store created with an LWR template.

Build a Lightning web component by using HTML, JavaScript, and CSS. HTML provides the structure. JavaScript defines the core business logic, event handling, API calls to fetch page data, and related metadata. CSS provides the look, feel, and animation. Then deploy the component to Experience Builder with Commerce metadata. From start to finish, including deploying the component to your store, an SFDX project framework and related utilities assist you.

**note:** Your LWR-based B2B or D2C store has dozens of standard Lightning web components. Before building a custom component, review the already-built LWCs described in [LWR Store Components](https://help.salesforce.com/s/articleView?id=commerce.comm_components.htm) or, to view all the components available in your store template, see [View All Components](https://help.salesforce.com/s/articleView?id=commerce.comm_view_comps.htm).

To get started building a custom component, see [Create an SFDX Project for the Custom Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-sample-lwc-project.htm). To accelerate the development process, you can also reference the [Public Commerce LWR Library GitHub Repository](https://github.com/forcedotcom/commerce-on-lightning-components).

To bring dynamic data into a custom component, use expressions. Note that your component can be rendered multiple times as different parts of the data tree are filled in. If you have custom components that use data expressions, verify that they can handle the initial absence of data and re-render as data updates. Before attempting to use data with expressions in a component, check that the data is defined and of the correct type. For more information, see [Expressions in Commerce Components](https://help.salesforce.com/s/articleView?id=commerce.comm_components_expressions.htm).

For guidance on specific custom components, see these topics:

- [Create a Pricing Component that Displays Discount Percentage](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-discount-percentage-lwc.htm)
- [Create Commerce Einstein Recommendations Components](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-einstein-rec-comps.htm)
- [Customize a Checkout Component for a B2B or B2C Store (LWR)](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-checkout-component.htm)
- [Create a Custom Payment Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-integrate-payment-lwc.htm)
- [LWR Sites for Experience Cloud](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/intro.htm)
- [Server-Side Rendering](https://developer.salesforce.com/docs/platform/lwr/guide/lwr-ssr.html)
- [Commerce LWR Storefront Performance Best Practices](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-storefront-performance-best-practices.html)

<!-- document id=6e506af0db637a211206177eb26e084c068e73e61447e8a475ab2c8380bf485c url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-get-started.md -->

# Build Modern and Scalable Storefronts with Storefront Next

Storefront Next delivers a performant, reliable, and personalized storefront experience by using modern web technologies, such as React 19 and Tailwind CSS.

Storefront Next uses React Router 7 framework mode, which renders pages on the server for initial page loads and reduces client-heavy processing in the browser. This server-driven processing boosts storefront shopping experience and client performance. With server-side personalization and user state management via cookies, Storefront Next delivers tailored content and data without sacrificing performance. Storefront Next uses Tailwind and shadcn/ui for CSS styling, which results in smaller storefront bundles and improved Core Web Vitals.

Storefront Next provides these benefits.

- High-performance server rendering: Optimizes for Core Web Vitals through streaming server-side rendering (SSR) and intelligent hydration.
- Personalization-first: Delivers tailored content and data without sacrificing performance.
- AI-ready: Provides AI-assisted development with the [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md) and AI-assisted shopping with Shopper Agent.
- Unified workflows: Bridges the gap between Page Designer for business users and pro-code routes for developers.
- Storybook integration: Accelerates development and enhances component quality through the Storybook component library and automated testing.

In this section:

## 1. Get Started

Learn about the architecture and core concepts that power Storefront Next, and review browser compatibility requirements to ensure your storefront works across different platforms. Get up and running with Storefront Next by creating a new storefront or connecting an existing one to B2C Commerce.

- [Get Started](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-get-started-section.md)

## 2. Customize and Build the Storefront

Customize your storefront and build the main shopping flows. Manage shopper identity, control access to your storefront environments, and deliver content and merchandise.

- [Customize Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-customize-sf.md)
- [Build the Shopping Experience](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-build-shopping-section.md)
- [Manage Shopper Identity](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-identity-section.md)
- [Present Content and Merchandise](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-present-content-section.md)
- [Secure Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-secure-storefront-section.md)
- [CLI Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-cli.md)

## 3. Deploy, Test, and Monitor Storefront Next

Managed Runtime provides the cloud infrastructure to deploy, host, and monitor Storefront Next.

- [Deploy and Manage Storefront Next on Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-section.md)
- [Preview, Test, and Debug Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-test-debug-section.md)
- [Optimize the Performance of Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-perf-section.md)
- [Integrate Storefront Next with Analytics and Data Platforms](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-analytics-section.md)

## 4. Use Storefront Next in a Hybrid Implementation

To run Storefront Next alongside your existing SFRA or SiteGenesis storefront, use Hybrid Auth. This section covers hybrid storefront setup, routing configuration, and login and registration support for hybrid deployments.

- [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid.md)

## 5. Go Live

When your storefront is ready for staging or production, launch it to make it accessible from a public web address. Configure routing rules in Business Manager for vanity or custom domains to direct traffic to the right environment.

- [Launch Your Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-launch-storefront.md)
- [Configure Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-routing-bm.md)

## 6. PWA Kit to Storefront Next Migration Reference

If you're a PWA Kit developer and are building a Storefront Next storefront, learn about the differences in the technologies and architecture used in PWA Kit and Storefront Next. Storefront Next keeps the same B2C Commerce backend model as PWA Kit (SCAPI, SLAS, and Managed Runtime), but it shifts implementation patterns across the stack. The storefront architecture shifts from a client-heavy, hook-driven architecture in PWA Kit to a server-first architecture built on React Router 7, Vite, and TypeScript in Storefront Next.

- [Migrate from PWA Kit to Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-overview.md)

<!-- document id=e225df1764a568b239ecf37a6dba50834840091eda541a5bea364f314dfc7d1b url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-build-tools.md -->

# Build System Differences with PWA Kit

PWA Kit relies on Webpack, Babel, and Jest with multiple build concerns split across separate configs. PWA Kit supports TypeScript optionally through Babel while Storefront Next has TypeScript as a first-class citizen with strict mode enabled. Storefront Next standardizes on Vite, Vitest, and TypeScript-first configuration, which reduces config complexity and speeds up local iteration through faster startup and hot updates. Code splitting and bundle analysis also become more route- and chunk-oriented by default.

## Build Tool

| Aspect        | PWA Kit                                | Storefront Next                |
| ------------- | -------------------------------------- | ------------------------------ |
| Bundler       | Webpack 5                              | Vite 7 (Rollup for production) |
| Dev Server    | Webpack Dev Server                     | Vite Dev Server                |
| HMR           | webpack-hot-middleware + React Refresh | Native Vite HMR                |
| Dev Speed     | Slower (full bundle)                   | Instant (native ES modules)    |
| Configuration | Complex, multi-target                  | Simpler, plugin-based          |

## Language Support

| Aspect           | PWA Kit               | Storefront Next               |
| ---------------- | --------------------- | ----------------------------- |
| Primary Language | JavaScript            | TypeScript                    |
| TypeScript       | Optional (via Babel)  | Native                        |
| Type Checking    | External (`tsc`)      | Integrated (`pnpm typecheck`) |
| Path Aliases     | Babel module resolver | Native via tsconfig paths     |

## Testing

| Aspect        | PWA Kit                   | Storefront Next                |
| ------------- | ------------------------- | ------------------------------ |
| Test Runner   | Jest                      | Vitest                         |
| Configuration | Separate `jest.config.js` | Integrated in `vite.config.ts` |
| Watch Mode    | `jest --watch`            | `vitest` (default)             |
| Coverage      | Jest coverage             | Vitest V8 coverage             |
| Component Dev | N/A                       | Storybook with a11y testing    |

## Code Splitting

| Aspect         | PWA Kit                  | Storefront Next                       |
| -------------- | ------------------------ | ------------------------------------- |
| Mechanism      | `@loadable/component`    | React Router + native dynamic imports |
| Chunk Strategy | Vendor + route-based     | Route-based with locale chunks        |
| Configuration  | Manual in Webpack config | Automatic via React Router            |

### Bundle Size Monitoring

| Aspect        | PWA Kit                 | Storefront Next          |
| ------------- | ----------------------- | ------------------------ |
| Tool          | bundlesize2             | vite-plugin-bundlesize   |
| Granularity   | 2 limits (main, vendor) | Per-chunk limits         |
| Visualization | webpack-bundle-analyzer | rollup-plugin-visualizer |

## Key Differences

1. Development Speed: Vite's native ES modules provide near-instant HMR compared to Webpack's full bundle approach. This is especially noticeable in larger codebases.

2. Configuration complexity: PWA Kit's Webpack config handles 5 different build targets with complex plugin composition. Storefront Next's Vite config is simpler with most complexity abstracted into plugins.

3. TypeScript Integration: Storefront Next has TypeScript as a first-class citizen with strict mode enabled. PWA Kit supports TypeScript optionally through Babel.

4. Testing Integration: Vitest shares the same configuration as Vite, eliminating the need for a separate test configuration. Jest requires more module mapping and transformation setup.

5. Bundle Analysis: Both support bundle analysis, but Storefront Next has more granular per-chunk size limits for better bundle size control.

## Storefront Conversion Considerations

When converting your storefront from PWA Kit to Storefront Next, keep in mind these considerations.

1. Configuration Files:

   - Remove `babel.config.js` (not needed)
   - Remove `jest.config.js` (use vite.config.ts test section)
   - Create `vite.config.ts` and `react-router.config.ts`
   - Create `tsconfig.json` for TypeScript

2. Dependencies:

   - Remove Webpack-related packages
   - Remove Babel packages
   - Remove Jest packages
   - Add Vite, Vitest, TypeScript packages

3. Scripts:

   - Replace `pwa-kit-dev` commands with `sfnext` and `react-router` commands
   - Update test commands from Jest to Vitest

4. Code Changes:

   - Convert JavaScript files to TypeScript (`.js` → `.ts`, `.jsx` → `.tsx`)
   - Replace `@loadable/component` with native dynamic imports
   - Update import paths to use TypeScript aliases (`@/`)

5. Environment Variables:
   - Vite uses `PUBLIC_` or `VITE_` prefix (not exposed otherwise)
   - Update `.env` files to use new prefix convention

<!-- document id=b91f6a81014c8331caa3d993306a45258bcefe0356a4531c99e1f98f55aa7685 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-build-shopping-section.md -->

# Build the Shopping Experience

Customize and extend your storefront, then build and configure the core shopping flows, from basket management and checkout to order management, store locator, and AI-assisted shopping with Shopper Agent.

In this section:

- [Basket Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-basket-management.md)
- [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md)
- [Configure Checkout for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-one-click-checkout.md)
- [Configure Salesforce Payments for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-salesforce-payments.md)
- [Configure Address Autocomplete for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-address-autocomplete.md)
- [Guest Order Lookup for Unregistered Shoppers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-guest-order.md)
- [Integrate Storefront Next with Salesforce Order Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-order-mgmt.md)
- [Enhance Shopper Experience with Store Locator and In-Store Pickup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-instore-pickup.md)
- [Shopper Agent for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopping-agent.md)

<!-- document id=a0062501b559d56376a5946bf80e70d2c921784b923618f3f46d031c517ff0ef url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-build-tools.md -->

# Build Tools

Storefront Next uses [Vite](https://vite.dev/) as its build tool, providing fast development builds through native ES modules and optimized production builds through Rollup. The toolchain includes native TypeScript support and Vitest for testing.

## Vite Configuration

The `vite.config.ts` file configures these plugins for your storefront.

- `reactRouter()`: Enables React Router 7 framework mode with file-based routing and Server-Side Rendering (SSR).
- `tailwindcss()`: Compiles Tailwind CSS styles.
- `tsconfigPaths()`: Resolves TypeScript path aliases like `@/components`.
- `storefrontNextPlugin()`: Prepares your build for deployment to Managed Runtime (MRT), including bundle formatting, manifest generation, and React Router compatibility patches.

You can add more [Vite plugins](https://vite.dev/plugins/) to customize your build.

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import { reactRouter } from "@react-router/dev/vite";
import tailwindcss from "@tailwindcss/vite";
import tsconfigPaths from "vite-tsconfig-paths";
import storefrontNextPlugin from "@salesforce/storefront-next-dev";

export default defineConfig({
  plugins: [reactRouter(), tailwindcss(), tsconfigPaths(), storefrontNextPlugin()],
});
```

### Storefront Next Plugin Options

The `storefrontNextPlugin` accepts this optional configuration object.

```typescript
storefrontNextPlugin({
  readableChunkNames: true,
});
```

| Option               | Type      | Default | Description                                                                                 |
| -------------------- | --------- | ------- | ------------------------------------------------------------------------------------------- |
| `readableChunkNames` | `boolean` | `false` | Generate human-readable chunk file names for easier debugging. Useful with bundle analyzer. |

When `readableChunkNames` is enabled, chunk files are named based on their source location.

```
// With readableChunkNames: true
(package)-(react-router)-(dist)-chunk.a1b2c3.js
(components)-(ui)-(button)-index.d4e5f6.js

// Default (readableChunkNames: false)
chunk.a1b2c3.js
index.d4e5f6.js
```

### Vite Plugins

| Plugin                     | Purpose                                   |
| -------------------------- | ----------------------------------------- |
| `@react-router/dev/vite`   | React Router 7 framework mode integration |
| `@tailwindcss/vite`        | Tailwind CSS compilation                  |
| `vite-tsconfig-paths`      | TypeScript path alias resolution          |
| `storefrontNextPlugin`     | MRT deployment and bundle optimization    |
| `vite-plugin-bundlesize`   | Bundle size validation                    |
| `rollup-plugin-visualizer` | Bundle analysis visualization             |

## React Router Configuration

The `react-router.config.ts` file uses a preset that enforces standard configuration for B2C Commerce.

```typescript
// react-router.config.ts
import type { Config } from '@react-router/dev/config';
import { odysseyPreset } from '@salesforce/storefront-next-dev/react-router-preset';

export default {
    presets: [odysseyPreset()],
} satisfies Config;
```

The preset configures:

- `appDirectory: './src'` — App source directory
- `buildDirectory: 'build'` — Build output directory
- `serverModuleFormat: 'cjs'` — Server bundle format for MRT compatibility
- `ssr: true` — Server-side rendering enabled
- Middleware support enabled

## TypeScript Configuration

Storefront Next uses TypeScript with strict settings enabled by default.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "paths": {
      "@/*": ["./src/*"],
      "@/config/server": ["./config.server.ts"]
    }
  }
}
```

The `@/*` path alias lets you import from the `src` directory using absolute paths:

```typescript
import { Button } from "@/components/ui/button";
import { useCart } from "@/hooks/use-cart";
```

## Testing with Vitest

Storefront Next uses [Vitest](https://vitest.dev/) for unit testing. Vitest integrates natively with Vite, sharing the same configuration and transformation pipeline.

Configure testing options in the `test` section of `vite.config.ts`.

```typescript
// vite.config.ts
export default defineConfig({
  // ... other config
  test: {
    globals: true,
    environment: "jsdom",
    setupFiles: ["./vitest.setup.ts"],
    include: ["**/*.{test,spec}.{ts,tsx}"],
    coverage: {
      reporter: ["text", "json", "json-summary"],
      include: ["src/**/*.{ts,tsx}"],
      exclude: ["src/**/*.d.ts", "src/components/ui/**/*", "src/**/*.stories.{ts,tsx}"],
    },
  },
});
```

## Development Commands

| Command                   | Description                                           |
| ------------------------- | ----------------------------------------------------- |
| `pnpm dev`                | Start development server with hot module replacement. |
| `pnpm build`              | Create a production build.                            |
| `pnpm start`              | Preview a production build locally.                   |
| `pnpm push`               | Deploy to MRT.                                        |
| `pnpm typecheck`          | Run TypeScript type checking.                         |
| `pnpm test`               | Run Vitest tests with coverage.                       |
| `pnpm bundlesize:test`    | Build and validate bundle sizes.                      |
| `pnpm bundlesize:analyze` | Build and visualize bundle composition.               |

## Source Maps

Production builds generate source maps by default. Source maps map minified code back to your original source files, giving you readable stack traces when errors occur.

### Configure Source Maps in Vite

Control source map generation in `vite.config.ts` using Vite's `[build.sourcemap](https://vite.dev/config/build-options.html#build-sourcemap)` option.

```typescript
// vite.config.ts
export default defineConfig({
  build: {
    sourcemap: true, // default
  },
  plugins: [reactRouter(), tailwindcss(), tsconfigPaths(), storefrontNextPlugin()],
});
```

| Value      | Behavior                                                                    |
| ---------- | --------------------------------------------------------------------------- |
| `true`     | Generates `.map` files alongside your build output. (Default)               |
| `"hidden"` | Generates `.map` files but omits the `sourceMappingURL` comment in bundles. |
| `false`    | Disables source map generation entirely.                                    |

### Enable Source Maps on Managed Runtime

Source maps are included in your deployed bundle, but MRT must be configured to use them at runtime. When enabled, MRT starts your server with the `--enable-source-maps` Node.js flag, which gives you original file names and line numbers in error stack traces.

#### Using Runtime Admin

1. Log in to [Runtime Admin](https://runtime.commercecloud.com).
2. Click your project.
3. Click your target environment.
4. Click **Environment Settings**.
5. In the Advanced section, click **Edit**.
6. Enable **Source Maps**.
7. Click **Update** and wait for the bundle to redeploy.

#### Using the Managed Runtime API

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$API_KEY"

npx @salesforce/b2c-cli mrt env update \
  --project my-storefront --environment staging --enable-source-maps
```

Alternatively, use the API:

```bash
curl -X PATCH \
https://cloud.mobify.com/api/projects/{project_id}/target/{target_id}/ \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data '{"enable_source_maps": true}'
```

## Bundle Size Monitoring

Storefront Next enforces bundle size limits to maintain performance. Configure limits in `package.json`.

```json
"bundlesize": {
    "server": [
        { "name": "**/*", "limit": "5 mB" }
    ],
    "client": [
        { "name": "assets/-root.*.js", "limit": "113 kB" },
        { "name": "**/*", "limit": "50 kB" }
    ]
}
```

Run `pnpm bundlesize:test` to validate that your build stays within limits. If a chunk exceeds the baseline 50-KB limit, add an explicit entry for that chunk with an approved limit.

To generate a visual treemap of your bundle composition, run `pnpm bundlesize:analyze`. This command helps you identify optimization opportunities.

<!-- document id=feee09eab302ea4fba7b22e7d7ed0ae0ff29a1616d08695ff5dffcbd6d7ab04b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/build-your-site.md -->

# Build Your Site

Get your B2C Commerce site up and running quickly. Follow these guides to understand the recommended process for developing your site. This section contains these guides.

## Configure Your Site

Set up your site data and preferences.

- [Code Repositories](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-github-repo-access.md): Access our open source repositories and code shared by B2C Commerce customers and partners.
- In Business Manager, [Create and Manage Sites for Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-managing-sites-for-dev.md).
- Configure [Global Preferences](https://help.salesforce.com/s/articleView?id=cc.b2c_global_preferences.htm&type=5) for all sites within your organization.
- Configure [Site Preferences](https://help.salesforce.com/s/articleView?id=cc.b2c_site_preferences.htm&type=5) for individual sites within your organization.
- [Import and Export](https://help.salesforce.com/s/articleView?id=cc.b2c_import_and_export.htm&type=5) site data.
- Use the [Import and Export Object Cheatsheet](https://help.salesforce.com/s/articleView?id=cc.b2c_import_export_object_cheatsheet.htm&type=5) (schema definitions) as a reference guide to learn about the B2C Commerce object type-specific import and export capabilities.
- [Customize Inventory Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/inventory/b2c-inventory-for-developers.md).
- Configure an [Embedded CDN](https://help.salesforce.com/s/articleView?id=cc.b2c_embedded_cdn.htm&type=5) to accelerate site speed.
- [Merchandising Your Site in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_merchandising_your_site.htm&type=5): Learn about adding data such as product and marketing information.
- [Create Custom Business Objects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scriptprogramming/creatingbusinessobjects.md) to extend the data model to store complex information specific to your business needs.
- Use [Web Services](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/web-services/b2c-webservices.md) to manage calls to web services and analyze service performance.

## Design Your Site

Build functionality and implement integrations on your site.

- Use [Page Designer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer/b2c-dev-for-page-designer.md) to manage templates that your merchant team can use to create site pages.
- Customize [Content Assets](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/content/b2c-content-assets-for-developers.md) to design reusable pieces of content for your site.
- SFRA only: Integrate with [Salesforce Payments](https://help.salesforce.com/s/articleView?id=cc.b2c_salesforce_payments.htm&type=5) to collect payments.
- Integrate with [Third-Party Applications](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/third-party/b2c-third-party.md) such as:

  - [Apple Pay](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/third-party/b2c-third-party.md#apple-pay-on-the-web)
  - [Server-Side Activity Tracking for Facebook](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/third-party/b2c-third-party.md#server-side-activity-tracking-for-facebook)
  - [Facebook Dynamic Ads](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/third-party/b2c-third-party.md#facebook-dynamic-ads-integration)

- Create personalized shopping experiences with [Commerce Einstein](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_cloud_einstein.htm&type=5).

Watch this video to learn how to power up your ecommerce with AI.

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/xxMS9jvwKnpwrzudvfKyQ2" title="Commerce Einstein Demo" type="vidyard"}

- Use [Active Merchandising](https://help.salesforce.com/s/articleView?id=cc.b2c_active_merchandising.htm&type=5) to improve how you target your customers.
- SFRA only: Use [Velocity Templates](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-velocity-templates.md) to design content with a Java-based server-side templating language.
- [Use APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/api-doc.md) such as B2C Commerce API or B2C Commerce Developer Resources (Script API) to customize your storefront or build your own custom storefront.

## Troubleshoot Your Site

- [Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ops-troubleshooting/b2c-troubleshooting.md)
- [Storefront Toolkit](https://help.salesforce.com/s/articleView?id=cc.b2c_sftk_container.htm&type=5)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)
- [B2C Commerce Storefront Options](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/which-product.md)
- [B2C Commerce Videos](https://help.salesforce.com/s/articleView?id=cc.b2c_videos.htm&type=5)
- [Trailhead Resources](https://help.salesforce.com/s/articleView?id=cc.b2c_trailhead.htm&type=5)
- [Salesforce Order Management Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide_html.meta/order_management_developer_guide_html/order_management_developer_guide_intro.html)
- [Additional Commerce Einstein Resources](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_additional_resources.htm&type=5)

<!-- document id=e739a158525d4516d0bcbc4f0e4406863312f1a6152ad2d51c810373488215b3 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/build-customize.md -->

# Build Your Site

Get your Progressive Web App (PWA) Kit site up and running quickly. Follow these guides to understand the recommended process for developing your site. Use template extensibility with the Retail React app to customize your site. This section contains the following guides.

- [Integrate Page Designer with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.md)
- [Template Extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md)
  - Tutorials:
    - [Customize a Component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-custom-component.md)
    - [Customize a Page](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/customize-a-page.md)
- [Protect Privacy with a Tracking Consent Banner](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/tracking-consent.md)
- [Maximize Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.md)

**Optional:**

- [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md)
  - Tutorials:
    - [Access Protected Resources with Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/env-var-3rd-party-CMS.md)
    - [Use Environment Variables in React.js](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/env-var-feature-access.md)
- Tutorial: [Personalize with Cookies](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/personalize-with-cookies.md)
- [Personalize with Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/personalize-with-shopper-context.md)
- [Boost In-Store Sales with Store Locator](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/store-locator.md)
- [Improve SEO with a Sitemap](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-sitemap.md)

### See Also

- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)
- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.md)
- Salesforce Commerce API (SCAPI) Overviews and Tutorials:
  - [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html)
  - [Promotion Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/promotion-details.html)
  - [Coupons, Gift Certificates, and Bonus Products](https://developer.salesforce.com/docs/commerce/commerce-api/guide/coupons-giftcerts-bonus-products.html)
- [Page Designer Pages](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_pd_pages.htm&type=5)
- [Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/commerce-vibes/guides/cv-agentforce-commerce-vibes.md)

<!-- document id=dc58615b482922972df17acdac8a3b6ae3a47d52d483cb4557f3ad07840a8da9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/building-your-app.md -->

# Building Your Commerce App

Use this guide to build your Commerce App. Choose the architecture that matches your domain — UI-only, Backend-only, or Fullstack — and follow the guidance below.

## Getting Started with Claude Code

The Commerce Apps repository includes Claude Code skills to accelerate development. Start with `/scaffold-app` to generate a complete app directory structure with templates for your chosen architecture (UI-only, Backend-only, or Fullstack). The scaffold skill prompts for your app's domain, name, and ISV details, then generates all required files including `commerce-app.json`, `tasksList.json`, and starter IMPEX files.

For IMPEX generation (`/generate-service-impex`, `/generate-site-preferences-impex`, `/generate-custom-object-impex`) and incremental IMPEX validation (`/validate-impex`), see the full catalog in [Development Environment Setup — Claude Code Skills](/docs/commerce/b2c-commerce/guide/development-environment.md#claude-code-skills).

## Backend-Only Apps

Backend-only apps implement platform-defined extension point hooks. See [The Three Architectures](/docs/commerce/b2c-commerce/guide/architecture.md#the-three-architectures-for-commerce-apps) for an overview.

### Extension Points

If your domain has a platform-defined extension point (currently Tax and OMS), your backend-only or fullstack app will include hook implementations that fulfill the interface contract. Each extension point defines a contract: when the platform calls your code, what data it passes, and what response it expects. Your cartridge provides script implementations for these hooks.

For example, for the Tax domain, you implement:

- `sfcc.app.tax.calculate`: Receives a `dw.order.LineItemCtnr` (basket). Called on **every basket operation** (adding items, changing quantities, updating shipping address, and so on), not only at checkout. Returns `dw.system.Status` or `null` for success. **Both returning `Status.ERROR` and throwing an exception always block the basket operation** — there is no non-blocking error path for this hook.
- `sfcc.app.tax.commit`: Receives a `dw.order.Order` (status `CREATED`). Called immediately after successful order creation. Returns `dw.system.Status` or `null` for success. Returning `Status.ERROR` is non-blocking (logged as a warning, order proceeds); throwing an exception is blocking (rolls back order creation).
- `sfcc.app.tax.cancel`: Receives a `dw.order.Order`. Called during `OrderMgr.failOrder()` or `OrderMgr.cancelOrder()`. Returns `dw.system.Status` or `null` for success. Returning `Status.ERROR` is non-blocking (logged as a warning, cancellation proceeds); throwing an exception is blocking (rolls back the cancellation).

Unlike legacy hooks (where all integrations share `dw.order.calculateTax` and conflict), these domain-specific extension points are resolved through the Extension Registry, not cartridge path scanning. Only the registered provider for a given domain is called.

> **Important:** App-specific extension points (for example, `sfcc.app.tax.*`) can only be invoked through the Commerce Apps installation process. You can't implement these hooks outside of a Commerce App — the platform gates their invocation on the app being installed and its feature toggles being enabled.

> **Reference:** The `sfcc.app.tax.*` extension points will be included in the [26.6 Script API documentation](https://salesforcecommercecloud.github.io/b2c-dev-doc/) with full contract details, parameter types, and return value specifications. Any new extension points introduced for Commerce Apps in future releases will also be documented there. For the OMS domain (`oms`), implement `sfcc.app.oms.order.retrieve`, `.list`, `.cancel`, and `.return`. See [Connect a Third-Party OMS](/docs/commerce/b2c-commerce/guide/connect-third-party-oms.md) for the full contract.

Example `hooks.json` structure:

```json
{
  "hooks": [
    {
      "name": "sfcc.app.tax.calculate",
      "script": "./hooks/taxCalculate"
    },
    {
      "name": "sfcc.app.tax.commit",
      "script": "./hooks/taxCommit"
    },
    {
      "name": "sfcc.app.tax.cancel",
      "script": "./hooks/taxCancel"
    }
  ]
}
```

> **Important — Function naming convention:** The exported JavaScript function name in each hook script **must match the last segment of the extension point name**. For example, the script referenced by `sfcc.app.tax.calculate` must export a function named `calculate`; the script for `sfcc.app.tax.commit` must export `commit`; and so on.
>
> ```js
> // hooks/taxCalculate.js
> exports.calculate = function(basket) { ... };
> ```

> **Important — SiteGenesis and SFRA cartridges are incompatible with Commerce Apps:** SiteGenesis (`sitegenesis_storefront_controllers`, `sitegenesis_storefront_core`) and SFRA (`app_storefront_base`) cartridges override the `dw.order.calculate` hook, which **bypasses the platform's Commerce App tax hook selection entirely**. These cartridges must be **removed** from your site's cartridge path before installing or running a Commerce App. Commerce Apps (CAP) are designed for use with Storefront Next and aren't compatible with SiteGenesis or SFRA storefronts.

#### Example: non-blocking error (returning `Status.ERROR`)

For most hooks, returning `Status.ERROR` is non-blocking — the platform logs a warning and allows the operation to continue. Use this approach when the failure should not prevent the shopper from completing their action. Note that some hooks (such as `sfcc.app.tax.calculate`) block regardless of whether you return `Status.ERROR` or throw an exception — check the extension point contract for your domain.

```js
"use strict";

var Status = require("dw/system/Status");
var Logger = require("dw/system/Logger");

var log = Logger.getLogger("myapp", "hooks");

exports.commit = function (order) {
  var result = callExternalProvider(order);

  if (!result.success) {
    // Non-blocking: the platform logs this as a warning and the operation proceeds.
    log.warn("Provider returned error for order {0}: {1}", order.orderNo, result.errorMessage);
    return new Status(Status.ERROR, "PROVIDER_CALL_FAILED", "External provider returned an error");
  }

  return new Status(Status.OK);
};
```

#### Example: blocking error (throwing an exception)

When your hook throws an exception, the platform **blocks** the operation and rolls back the transaction. Use this only when the operation must not proceed.

```js
"use strict";

var Status = require("dw/system/Status");
var Logger = require("dw/system/Logger");

var log = Logger.getLogger("myapp", "hooks");

exports.commit = function (order) {
  var result = callExternalProvider(order);

  if (!result.success) {
    // Blocking: throw to prevent the operation from proceeding.
    log.error("Provider call failed for order {0}: {1}", order.orderNo, result.errorMessage);
    throw new Error("Provider call failed: " + result.errorMessage);
  }

  return new Status(Status.OK);
};
```

**Platform behavior:** The basket operation (or order creation, or cancellation) is rolled back. The shopper receives a 500 error response.

#### Implementation best practices

##### Service timeout handling

Extension point hooks run synchronously within the shopper request. If your hook calls an external API, the service timeout directly impacts shopper-facing latency. Use the Commerce Cloud Service Framework (`dw.svc`) with a service profile that defines explicit timeouts, rate limits, and circuit breakers.

**Recommended service profile settings for checkout-path hooks:**

```xml
<service-profile profile-id="myapp.provider.profile">
    <timeout-millis>5000</timeout-millis>
    <rate-limit-enabled>true</rate-limit-enabled>
    <rate-limit-calls>100</rate-limit-calls>
    <rate-limit-millis>1000</rate-limit-millis>
    <circuit-breaker-enabled>true</circuit-breaker-enabled>
    <circuit-breaker-max-calls>3</circuit-breaker-max-calls>
</service-profile>
```

- **`timeout-millis`:** Keep at 5000 ms or less for real-time checkout hooks. A 10-second timeout will cause unacceptable shopper latency.
- **Circuit breaker:** Enable with a low threshold (`max-calls: 3`) so the platform fails fast if your provider is down, rather than making shoppers wait through repeated timeouts.
- **Rate limiting:** Protect your provider from burst traffic during flash sales or load tests.

When a service call times out or the circuit breaker trips, the service framework returns a `Result` with `status !== 'OK'`. Handle this in your hook:

```js
var result = myService.call(requestPayload);

if (result.status !== "OK") {
  log.error("Service call failed: {0} (error: {1})", result.errorMessage, result.error);
  // Decide based on your extension point contract whether to throw or return Status.ERROR
}
```

##### Logging best practices

Use `dw.system.Logger` with a consistent category and prefix for all log messages. This makes it straightforward to filter your app's logs in Log Center.

```js
var Logger = require("dw/system/Logger");
var log = Logger.getLogger("myapp", "hooks");
```

- **`log.debug()`** — verbose details during development (request/response payloads)
- **`log.info()`** — key lifecycle events (hook invoked, service call succeeded)
- **`log.warn()`** — recoverable issues (returning `Status.ERROR`, fallback behavior)
- **`log.error()`** — unrecoverable failures (throwing an exception, data integrity issues)

Always include identifiers in log messages so issues can be traced:

```js
log.info(
  "Hook called for basket {0}, shipment count: {1}",
  lineItemCtnr.getUUID(),
  lineItemCtnr.getShipments().size(),
);

log.error("Hook failed for order {0}: {1}", order.orderNo, result.errorMessage);
```

> **Tip:** Enable `communication-log` on your service definition during development to capture full HTTP request/response details in Log Center. Disable it in production to avoid logging sensitive data.

##### Transaction ID tracking

If your external provider assigns a transaction ID, persist it on the order so subsequent hooks can reference the same transaction. Use order-level custom attributes for this:

```js
// In your first hook — store the transaction ID from your provider's response
var Transaction = require("dw/system/Transaction");

Transaction.wrap(function () {
  lineItemCtnr.custom.myAppTransactionId = providerResponse.transactionId;
});
```

```js
// In a later hook — reference the same transaction
var transactionId = order.custom.myAppTransactionId;
if (!transactionId) {
  log.warn("No transaction ID found on order {0}, skipping commit", order.orderNo);
  return new Status(Status.ERROR, "NO_TRANSACTION_ID", "Missing transaction ID");
}
callExternalProvider(transactionId, order);
```

Define the custom attribute in your IMPEX under `meta/system-objecttype-extensions.xml`:

```xml
<type-extension type-id="Order">
    <custom-attribute-definitions>
        <attribute-definition attribute-id="myAppTransactionId">
            <display-name xml:lang="x-default">Provider Transaction ID</display-name>
            <type>string</type>
            <mandatory-flag>false</mandatory-flag>
            <externally-managed-flag>true</externally-managed-flag>
        </attribute-definition>
    </custom-attribute-definitions>
</type-extension>
```

> **Naming convention:** Prefix all custom attribute IDs with your app name (for example, `myApp`) to avoid collisions with other Commerce Apps or merchant customizations.

##### Custom attribute usage patterns

Beyond transaction IDs, Commerce Apps commonly use custom attributes for:

- **Basket-level details:** Store intermediate calculation results so your hook can detect when a recalculation is actually needed (for example, by comparing a hash of line items and addresses).
- **Order-level audit data:** Store the provider's response code, document status, or error details for post-order reconciliation.
- **Site preferences:** Store merchant-configurable values like API mode (sandbox vs. production), default codes, or enable/disable flags.

Use `externally-managed-flag` set to `true` for attributes that should not appear in Business Manager's attribute editor (internal tracking fields). Set it to `false` for attributes merchants need to see or edit.

#### Optional: delivering Storefront Next components

Backend-only apps that implement extension points can optionally include Storefront Next extensions to provide custom UI beyond what the platform components offer. For example, Avalara provides an `avatax-tax-breakdown` extension that displays a detailed tax breakdown not covered by the standard tax line item component.

## Connection Health Check

Any Commerce App — UI-only, Backend-only, or Fullstack — can implement an optional **connection health check hook** so Business Manager displays connectivity status on the app's tile in the Cart & Checkout Hub. The platform calls the hook when a merchant loads the app details page or manually refreshes the connection status. How you define "connection" is up to you: an API ping, a credential validation, a third-party service check, or any verification that confirms your app's external dependency is reachable.

### Registering the hook

Add a `checkConnectionHealth` entry to your cartridge's `hooks.json`:

```json
{
  "hooks": [
    {
      "name": "sfcc.app.<domain>.checkConnectionHealth",
      "script": "./hooks/checkConnectionHealth.js"
    }
  ]
}
```

Replace `<domain>` with your app's domain (for example, `tax`, `shipping`, `payment`, `ratings-and-reviews`). The hook name must follow the `sfcc.app.<domain>.checkConnectionHealth` convention — the platform uses it to associate the hook with your app's installation.

> **Function naming convention:** The exported function must be named `checkConnectionHealth`, matching the last segment of the extension point name.

### Implementing the hook

The hook must export a `checkConnectionHealth` function that returns a `dw.system.Status`. Use `Status.OK` for healthy, `Status.ERROR` with code `DEGRADED` for partial impairment, and `Status.ERROR` with code `UNHEALTHY` (or any other error code) for failures.

```js
"use strict";

var Status = require("dw/system/Status");

exports.checkConnectionHealth = function () {
  var myService = require("*/cartridge/scripts/services/myService");

  try {
    var result = myService.call("GET", "/health", null);

    if (result.success) {
      var status = new Status(Status.OK, "HEALTHY");
      status.addDetail("message", "Service responded in " + result.latency + "ms");
      return status;
    }

    var unhealthy = new Status(Status.ERROR, "UNHEALTHY");
    unhealthy.addDetail("message", "Unable to reach service");
    unhealthy.addDetail(
      "remediation",
      "Verify credentials in Administration > Operations > Services > myvendor.api",
    );
    return unhealthy;
  } catch (e) {
    var errorStatus = new Status(Status.ERROR, "UNHEALTHY");
    errorStatus.addDetail("message", "Unexpected error: " + e.message);
    errorStatus.addDetail(
      "remediation",
      "Verify credentials in Administration > Operations > Services > myvendor.api",
    );
    return errorStatus;
  }
};
```

### Status codes

The Business Manager endpoint interprets the returned `Status` as follows:

| Return value | Health badge | When to use |
| :--- | :--- | :--- |
| `new Status(Status.OK, 'HEALTHY')` | **Healthy** | Service is reachable and credentials are valid |
| `new Status(Status.ERROR, 'DEGRADED')` | **Degraded** | Service is reachable but partially impaired (for example, auth failed, rate-limited) |
| `new Status(Status.ERROR, 'UNHEALTHY')` | **Unhealthy** | Service is unreachable or returning errors |
| `null` or exception thrown | **Unknown** | Hook timed out or threw — platform handles gracefully |

### Status details

Use `status.addDetail(key, value)` to attach structured information that Business Manager surfaces in the health indicator UI:

| Detail key | Purpose | Example |
| :--- | :--- | :--- |
| `"message"` | Brief description of the current state | `"Service responded in 142ms"` |
| `"remediation"` | Actionable steps the merchant can take to fix a degraded or unhealthy state | `"Verify your API credentials in Administration > Operations > Services > myvendor.api"` |

Business Manager surfaces both values **verbatim**. Keep them concise and merchant-friendly.

### Localizing health check messages

The hook executes in the Business Manager session locale context, so use `dw.web.Resource` to provide translated messages:

```js
var Resource = require("dw/web/Resource");
var Status = require("dw/system/Status");

exports.checkConnectionHealth = function () {
  // ... service call logic ...
  var degraded = new Status(Status.ERROR, "DEGRADED");
  degraded.addDetail("message", Resource.msg("healthcheck.degraded.message", "myapp", null));
  degraded.addDetail(
    "remediation",
    Resource.msgf("healthcheck.degraded.remediation", "myapp", null, serviceName),
  );
  return degraded;
};
```

Place resource bundles under `cartridge/templates/resources/` in your cartridge (for example, `myapp.properties` for English, `myapp_de.properties` for German). The `Resource.msg()` call resolves against the Business Manager admin's current language.

If you do not need localization, hard-coded English strings are acceptable — they flow through to the UI as-is.

### Best practices

- **Keep it lightweight.** The platform applies a CPU timeout. Prefer a simple ping or auth-check endpoint over heavy operations.
- **Always return a Status.** Never return `undefined` — return `null` if you cannot determine health, and the platform shows "Unknown."
- **Wrap in try/catch.** An unhandled exception produces an "Unknown" badge with no message. Catching the error lets you return a meaningful remediation hint.
- **Be specific in remediation.** Include the exact Business Manager navigation path where the merchant can fix the issue (for example, `Administration > Operations > Services > myvendor.api`).
- **Test degraded states.** Use invalid credentials or an unreachable endpoint in your sandbox to verify that degraded and unhealthy responses render correctly.

### Apps without a health check

If an app does not register `sfcc.app.<domain>.checkConnectionHealth`, the Cart & Checkout Hub tile does not display a health badge. The health check is optional — apps that don't depend on an external connection typically skip it.

## UI-Only and Fullstack Apps

If you want full control over the UX, you replace the platform component with your own React extension. For UI-only apps, the platform provides the backend. For fullstack apps, you also build your own backend.

### Building your Storefront Next extension

Your extension lives in the `storefront-next/src/extensions/{app-name}/` directory of your CAP. A typical extension includes:

- One or more React components
- A `target-config.json` that maps your components to UI target IDs and declares context providers
- Localization files under `locales/` (minimum: `en-US`, `en-GB`, `it-IT`)
- Optionally, route files under `routes/` for custom pages
- Optionally, a context provider component

**Storefront Next tech stack:**

| Layer        | Technology                                       |
| :----------- | :----------------------------------------------- |
| Framework    | React 19                                         |
| Language     | TypeScript (strict)                              |
| Build        | Vite                                             |
| Styling      | Tailwind CSS 4 (`@theme inline`, no config file) |
| Components   | ShadCN UI (Radix UI primitives)                  |
| Variants     | CVA (class-variance-authority)                   |
| Routing      | React Router 7                                   |
| i18n         | react-i18next                                    |
| Unit testing | Vitest + React Testing Library                   |
| E2E testing  | CodeceptJS + Playwright                          |

Example extension directory structure:

```
src/extensions/my-app/
  target-config.json
  components/
    my-widget.tsx
    my-other-widget.tsx
  locales/
    en-US/translations.json
    en-GB/translations.json
    it-IT/translations.json
  providers/
    my-app-provider.tsx        # optional context provider
  routes/
    _app.my-app-page.tsx       # optional custom route
  hooks/
    use-my-app.ts              # optional custom hooks
```

#### target-config.json

The `target-config.json` defines which platform UI targets your components replace or extend, and optionally declares context providers that wrap the application root.

**Components** map to `UITarget` placeholders defined throughout the Storefront Next application. Each `UITarget` has a unique `targetId` — your extension specifies which target IDs to fill, the component file path (relative to `src/`), and an `order` value for controlling render order when multiple extensions target the same ID.

Target IDs follow the naming convention `sfcc.{location}.{domain}.{capability}` — for example, `sfcc.orderSummary.tax.line` targets the tax line item within the order summary, and `sfcc.pdp.reviews.rating` targets the star rating display on the product detail page.

```json
{
  "components": [
    {
      "targetId": "sfcc.orderSummary.tax.line",
      "path": "extensions/avatax-tax-breakdown/components/tax-line.tsx",
      "order": 0
    }
  ]
}
```

Multiple components can target different insertion points in the same `target-config.json`. For example, a Ratings & Reviews extension might target the star rating, the full reviews list, and the Q&A section on the PDP:

```json
{
  "components": [
    {
      "targetId": "sfcc.pdp.reviews.rating",
      "path": "extensions/yotpo-reviews/components/star-rating.tsx",
      "order": 0
    },
    {
      "targetId": "sfcc.pdp.reviews.list",
      "path": "extensions/yotpo-reviews/components/reviews-list.tsx",
      "order": 0
    },
    {
      "targetId": "sfcc.pdp.reviews.qna",
      "path": "extensions/yotpo-reviews/components/qna-section.tsx",
      "order": 0
    }
  ]
}
```

When multiple components target the same `targetId`, they are rendered in ascending `order`.

**Context providers** let your extension inject a React context provider at the application root (wrapping `root.tsx`). This is useful when your extension needs shared state accessible across multiple components or routes:

```json
{
  "components": [
    {
      "targetId": "sfcc.checkout.payment.paymentMethods",
      "path": "extensions/my-payments/components/payment-methods.tsx",
      "order": 0
    }
  ],
  "contextProviders": [
    {
      "path": "extensions/my-payments/providers/payments-provider.tsx",
      "order": 0
    }
  ]
}
```

**Available UI target IDs** are defined throughout the Storefront Next application using the `<UITarget targetId="..." />` component. Each target ID corresponds to a specific domain and location in the storefront. Consult the Storefront Next template application for the full list of available target IDs.

#### How UITarget replacement works at build time

`UITarget` is a **build-time placeholder**, not a runtime component. When the merchant runs `pnpm dev` or `pnpm build`, a Vite plugin scans all `target-config.json` files under `src/extensions/`, builds a component registry, and uses Babel AST transforms to:

1. **Replace** each `<UITarget targetId="X">` with the registered extension component(s) for that target ID, generating the necessary `import` statements automatically.
2. **Preserve children** if no extension targets that ID — `<UITarget targetId="X">{defaultContent}</UITarget>` renders `defaultContent`.
3. **Remove** `<UITarget>` entirely if no extension targets it and no children are provided.

Context providers declared in `contextProviders` are similarly injected at build time by replacing the `<UITargetProviders>` placeholder in `root.tsx` with nested provider wrappers.

> **Important:** Changes to `target-config.json` during development automatically restart the Vite dev server so the registry is rebuilt.

#### Extension routes

Extensions can add custom pages by placing route files in a `routes/` subdirectory. These follow the same file-based routing conventions as the main application (React Router v7 flat routes). Route files are automatically discovered and merged into the application's route tree at build time — no manual route registration is needed.

```
src/extensions/my-app/
  routes/
    _app.my-app-settings.tsx    # page route under the _app layout
    action.my-app-action.ts     # resource route (action endpoint)
    resource.my-app-data.ts     # resource route (data endpoint)
```

#### Extension localization

Extensions must include translation files for at least `en-US`, `en-GB`, and `it-IT` locales. Place them at `locales/{locale}/translations.json` within your extension directory.

Translation namespaces are automatically generated from the extension folder name using PascalCase with an `ext` prefix. For example, an extension in `src/extensions/my-app/` gets the namespace `extMyApp`.

```typescript
import { useTranslation } from "react-i18next";

export function MyAppWidget() {
  const { t } = useTranslation("extMyApp");
  return <h1>{t("widget.title")}</h1>;
}
```

An aggregation script (`aggregate-extension-locales`) runs during the build process to discover extension locale files and generate import manifests. This is handled automatically — you don't need to manually register your translations.

#### Extension installation

During installation, the extension code from your CAP is copied into the merchant's Storefront Next project under `src/extensions/{app-name}/`.

On the next build, the Vite plugin reads the new `target-config.json`, rebuilds the component registry, and replaces `UITarget` placeholders with your components.

### Injecting External SDK Scripts

Many Commerce Apps need to load an external JavaScript library from a vendor's CDN — fraud beacons, analytics tags, payment SDKs, review widgets, live chat, and more. This section explains how to inject those scripts using the existing Storefront Next extension mechanisms (`contextProviders` and `components`). No framework changes are required.

> **Important — CDN delivery is required by most vendors.** Many payment and fraud vendors' terms of service require loading from their CDN. Fraud detection vendors use CDN delivery as part of integrity verification. Personalization tools need CDN delivery for real-time experiment configurations. Bundling these scripts would add hundreds of KB to the storefront and freeze vendors at specific versions. Always load external SDKs via `<script src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/...">` rather than bundling them.

#### How script injection works in Storefront Next

Storefront Next is a Single Page Application (SPA) built on React 19. Two properties of this architecture are critical for script injection:

1. **React 19 script hoisting:** Any `<script src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/...">` tag rendered anywhere in the React component tree is automatically hoisted to `<head>` and deduplicated by `src`. This means a `contextProvider` or component that renders a `<script>` tag gets that script in `<head>` regardless of where the component appears in the tree. The `async` and `defer` attributes pass through correctly.

2. **SPA navigation:** Unlike traditional multi-page sites, Storefront Next navigates between pages by swapping content in place — no full page reload occurs. SDK scripts that rely on page loads to re-initialize (review widgets, fraud beacons, analytics) must be explicitly notified of route changes. Use the `useLocation()` hook from `react-router` to detect SPA navigation and re-trigger SDK logic.

> **Note:** Inline `<script>` blocks (containing code rather than a `src` URL) are **not** hoisted by React 19. Use `useEffect` for any `window` object initialization logic instead.

#### Choosing the right mechanism

| Scenario                                                                             | Mechanism                                                                                        |
| :----------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------- |
| SDK must load on every page (fraud, analytics, tag manager, chat)                    | `contextProviders` — wraps the entire app, loads once                                            |
| SDK only needed on specific pages (payment SDK at checkout)                          | `components` at a scoped UI target (for example, `sfcc.checkout.page.before`)                    |
| SDK needed on multiple page types (BNPL messaging on PDP + payment form at checkout) | `contextProviders` (loads SDK globally) + `components` at each target (renders UI)               |
| Widget requires DOM container + SPA re-initialization                                | `contextProviders` (loads SDK) + `components` (renders container, calls re-init on route change) |

#### Example: Global SDK via contextProvider

SDKs that must load on every page — fraud beacons, analytics, tag managers, live chat — use a `contextProvider` that renders a `<script>` tag and wraps the entire application. The provider reads merchant configuration from `useConfig()` and uses `useLocation()` to detect SPA navigation.

**target-config.json:**

```json
{
  "components": [],
  "contextProviders": [
    {
      "path": "extensions/my-fraud-app/providers/FraudBeaconProvider.tsx",
      "order": 0
    }
  ]
}
```

**FraudBeaconProvider.tsx:**

```tsx
'use client';
import { useEffect, useState, type ReactNode, type ReactElement } from 'react';
import { useLocation } from 'react-router';
import { useConfig } from '@salesforce/storefront-next-runtime/config';

interface AppConfig {
  extension?: { myFraudApp?: { siteId: string; enabled: boolean } };
}

export default function FraudBeaconProvider({ children }: { children: ReactNode }): ReactElement {
  const appConfig = useConfig<AppConfig>();
  const siteId = appConfig.extension?.myFraudApp?.siteId ?? '';
  const enabled = appConfig.extension?.myFraudApp?.enabled !== false;
  const location = useLocation();

  useEffect(() => {
    if (!enabled || !siteId) return;
    // Re-notify the vendor SDK on each SPA navigation.
    // Replace with your vendor's page-notify API.
    const win = window as Window & { vendorSdk?: { notifyPageView?: (id: string) => void } };
    win.vendorSdk?.notifyPageView?.(siteId);
  }, [enabled, siteId, location.pathname]);

  return (
    <>
      {enabled && siteId && (
        <script src="https://cdn.example.com/fraud-beacon.js" data-site-id={siteId} />
      )}
      {children}
    </>
  );
}
```

- No `async` attribute — fraud beacons must load near-synchronously to capture session start. For analytics or tag manager scripts that don't need to block rendering, add `async`.
- `useLocation()` triggers the `useEffect` on every SPA navigation so the vendor SDK is notified of route changes.
- Configuration comes from `useConfig()`, which reads values the merchant sets during app configuration.

#### Example: Checkout-scoped SDK via components

SDKs needed only on specific pages — payment processors at checkout — use `components` at scoped UI targets instead of `contextProviders`. The script loads only while the target's route is active.

**target-config.json:**

```json
{
  "components": [
    {
      "targetId": "sfcc.checkout.page.before",
      "path": "extensions/my-payment/components/PaymentScriptLoader.tsx",
      "order": 0
    },
    {
      "targetId": "sfcc.checkout.payment.paymentMethods",
      "path": "extensions/my-payment/components/PaymentForm.tsx",
      "order": 0
    }
  ]
}
```

**PaymentScriptLoader.tsx:**

```tsx
export default function PaymentScriptLoader() {
  return <script src="https://cdn.example.com/payment-sdk.js" async />;
}
```

- `sfcc.checkout.page.before` renders only on the checkout route. React 19 hoists the `<script>` to `<head>` only while that route is active.
- `sfcc.checkout.payment.paymentMethods` is a wrap-behavior target that replaces the default payment method UI.

#### Handling SPA re-initialization

Widget SDKs (common in ratings & reviews) that scan the DOM for containers on initialization don't know when React mounts new content during SPA navigation. For these, use both mechanisms: a `contextProvider` loads the SDK globally and exposes a `refreshWidgets()` function via React context, and a `component` renders the DOM container and calls `refreshWidgets()` in a `useEffect` that watches `useLocation().pathname`. This triggers the SDK to re-scan the DOM after each route change.

#### Script placement decision guide

| Question                                   | Mechanism                                                                    |
| :----------------------------------------- | :--------------------------------------------------------------------------- |
| Must run on every page from session start? | `contextProviders` — no `async` (fraud beacons)                              |
| Must run on every page, non-blocking?      | `contextProviders` — with `async` (analytics, tag managers)                  |
| Must run before React renders?             | Not possible today — requires future framework update                        |
| Only needed on checkout?                   | `components` at `sfcc.checkout.page.before` (payment SDKs)                   |
| Needs DOM container + SPA re-init?         | `contextProviders` (SDK) + `components` (container + `refreshWidgets()`)     |
| Same SDK serves multiple page types?       | `contextProviders` (SDK) + `components` at each target (BNPL)                |
| Needs customer identity after auth?        | `contextProviders`, identity update in `useEffect` watching auth state       |
| Manages other vendor scripts?              | `contextProviders` with `dataLayer`, virtual page views on route change      |
| Blocks or gates other scripts on consent?  | `contextProviders` at low `order`, others check consent hook — partial today |

### Storefront Action Hooks

While UI targets and context providers handle the client side, many Commerce App domains also need to run server-side logic at key points in the shopper experience — verifying a shipping address against an external service, checking a fraud score before placing an order, or authorizing a payment. Storefront action hooks provide these server-side extension points within the Storefront Next application.

Action hooks run inside the Storefront Next server as part of React Router actions (not in the Commerce Cloud Script API like backend extension points such as `sfcc.app.tax.*`). They are declared in `target-config.json` under the `actionHooks` key and processed at build time by a Vite plugin. At runtime, hooks execute in a **waterfall** pattern: each handler receives the previous handler's output, with a **5-second timeout** per handler.

The hooks available today cover the checkout flow. Additional action hooks for other storefront surfaces will be added in future releases.

#### Available action hooks

| Hook ID                                                        | Blocking | Surface  | Purpose                                                          |
| :------------------------------------------------------------- | :------- | :------- | :--------------------------------------------------------------- |
| `sfcc.checkout.fraud.afterSubmitContactInfo`                   | No       | Checkout | Fraud or identity checks after email and phone submission        |
| `sfcc.checkout.addressVerification.afterSubmitShippingAddress` | No       | Checkout | Address validation and standardization                           |
| `sfcc.checkout.shipping.afterMethodsFetch`                     | No       | Checkout | Enrich or filter shipping methods (for example, real-time rates) |
| `sfcc.checkout.shipping.afterMethodSelect`                     | No       | Checkout | Post-processing after shipping method selection                  |
| `sfcc.checkout.payments.afterSubmitPayment`                    | No       | Checkout | Post-payment processing (for example, tokenization)              |
| `sfcc.checkout.fraud.beforePlace`                              | **Yes**  | Checkout | Final fraud gate — can block order creation                      |
| `sfcc.checkout.payments.beforePlaceOrder`                      | **Yes**  | Checkout | Payment authorization gate — can block order creation            |
| `sfcc.checkout.payments.afterPlaceOrder`                       | No       | Checkout | Post-order processing (for example, payment capture)             |

**Blocking** hooks abort the action on any handler failure. **Non-blocking** hooks log errors and continue to the next handler. Throwing an `ActionHookError` always aborts the action with a user-facing error, regardless of blocking mode.

#### Declaring and writing action hooks

Add an `actionHooks` array to your `target-config.json`. Each entry specifies the hook ID, the handler file path (relative to `src/`), and an `order` value. When multiple extensions target the same hook, handlers execute in ascending `order`.

```json
{
  "actionHooks": [
    {
      "hookId": "sfcc.checkout.addressVerification.afterSubmitShippingAddress",
      "handler": "extensions/my-address-app/hooks/verify-address.server.ts",
      "order": 0
    }
  ]
}
```

A handler is a default-exported async function that receives an `ActionHookContext` (containing `data` from the checkout step and the React Router `actionContext`) and returns a modified context, or `void` to pass through unchanged.

```typescript
import type { ActionHookContext } from "@/targets/action-hook.server";
import { ActionHookError } from "@/targets/action-hook.server";

export default async function verifyAddress(
  context: ActionHookContext,
): Promise<ActionHookContext> {
  const { data } = context;

  const response = await fetch("https://api.example.com/address/verify", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ address: data.shippingAddress }),
  });
  const verified = await response.json();

  if (!verified.valid) {
    throw new ActionHookError(
      "Please check your shipping address and try again.",
      "sfcc.checkout.addressVerification.afterSubmitShippingAddress",
      "shippingAddress",
    );
  }

  return { ...context, data: { ...data, shippingAddress: verified.standardizedAddress } };
}
```

`ActionHookError` returns a 400 JSON response to the storefront. The third argument (`step`) identifies the checkout step where the error should display.

#### Listing available extension points

The Storefront Next template includes a script that enumerates all UI targets and action hooks:

```bash
pnpm run list:extension-points
```

This outputs a grouped table of every UI target ID (with its source file) and every action hook ID (with its blocking status and invocation site). Pass `--json` for machine-readable output.

### Building the back-end

Fullstack apps have two sub-types: **Extension Points** and **Custom SCAPI**. See [The Three Architectures](/docs/commerce/b2c-commerce/guide/architecture.md#the-three-architectures-for-commerce-apps) for an overview of each.

#### Extension Points

For fullstack apps using extension points, your backend follows the same patterns as backend-only apps (hook implementations, service integrations, IMPEX). The difference is that you also provide your own Storefront Next extensions that replace or extend the platform's default UI components.

#### Custom SCAPI

For domains without platform-defined extension points, you build a custom SCAPI that supplies data to your own Storefront Next components. You define the data contract between your components and your SCAPI.

Examine the mocked component in the Storefront Next reference application (Market Street or Salesforce Foundations) to understand what data shape to target. Build your custom SCAPI to return data in a format your components can consume.

**Reference:** SCAPI documentation for building custom API endpoints is maintained in [B2C API Documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html). This guide provides the Commerce App context; refer to the SCAPI docs for the implementation details.

## Backend Development Notes

Backend cartridges use the Commerce Cloud Script API (CommonJS modules with `require('dw/...')` imports). Key points for Commerce App backend development:

- **Service framework:** Use the Service Framework (`dw.svc`) for all outbound API calls. Define service credentials, profiles, and definitions in your IMPEX. Use placeholder credentials — merchants configure real values during setup.
- **Hook registration:** Register extension point hooks in `cartridge/scripts/hooks.json`. The platform resolves hooks through the Extension Registry, not cartridge path scanning.
- **Feature toggles:** Enable required prerequisite toggles before installation. When the supplied app ID and domain match a registry entry, the installer checks `requiredFeatureToggle` when that entry defines it, but doesn't enable the toggle. Hook validation can also identify disabled hook prerequisites that require remediation.
- **Error handling:** Extension point hooks have defined error semantics per hook. Review the hook contract carefully — some hooks block on errors while others log warnings and proceed. See [Extension Points](#extension-points) for per-hook details.

## Example Apps in the Registry

The [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps) contains reference implementations to study when building your own app. These aren't open source — they're packaged CAPs available through the registry — but their structure, IMPEX patterns, and `commerce-app.json` files serve as practical templates.

| App         | Domain | Architecture                                                         | What It Demonstrates                                                                                              |
| :---------- | :----- | :------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
| Avalara Tax | `tax`  | Backend-only (extension points) + optional Storefront Next extension | Extension point hooks (`calculate`, `commit`, `cancel`), service integration, `avatax-tax-breakdown` UI extension |

> **Tip:** Use the `/scaffold-app` Claude Code skill to generate a starter app structure modeled after these reference apps. The scaffold includes all required files and follows the same conventions.

### Anti-patterns to avoid

- **Hardcoded site IDs in IMPEX.** Use `SITEID` and `LIBRARYID` placeholders. The install job replaces them at runtime. Hardcoded values cause failures on any site other than the one you tested with.
- **Skipping uninstall IMPEX.** Every resource your app creates (services, custom objects, site preferences) must have a corresponding uninstall entry with `mode="delete"`. Missing uninstall IMPEX leaves orphaned configuration on the merchant's instance.
- **Omitting the service profile.** Always define a service profile with explicit `timeout-millis` and circuit breaker settings. Without a profile, service calls use platform defaults that may be too generous for checkout-path hooks.
- **Generic custom attribute names.** Prefix all custom attribute IDs with your app name (for example, `avalaraTaxDocumentId`, not `taxDocumentId`). Generic names risk collisions with other Commerce Apps or merchant customizations.
- **Bundling SiteGenesis or SFRA cartridges.** Commerce Apps are Storefront Next-only. Including legacy storefront cartridges in your CAP will cause conflicts and is a review rejection reason.

<!-- document id=82a87745f65eed5a3c6d5f2b6871f754710d2af7662431b1c5339ddbde8348d0 url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-bulk.md -->

Bulk

# Bulk

The Salesforce API allows bulk operations to upload thousands of records in a batch.

In this section, we will show examples using Inventory Records, but the same logic may be used for any type of record.

The entire process may be summarized as creating a bulk job with the record-type data, uploading the data in CSV format, starting the processing of the job and periodically checking whether the job has finished and its respective result. Full API documentation can be found at: [https://developer.salesforce.com/docs/atlas.en-us.232.0.api\_asynch.meta/api\_asynch/bulk\_api\_2\_0.htm](https://developer.salesforce.com/docs/atlas.en-us.232.0.api_asynch.meta/api_asynch/bulk_api_2_0.htm).

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### POST Create a Job

`POST /services/data/v51.0/jobs/ingest`

Operation ID: `Create a Job`. Tags: Bulk. Security: bearerAuth.

Create a new job for data upload. Define the general data on the job, such as record type, field used as ID and operation type.

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "object": "Atonit_Mktplace__Inventory_Record__c",
  "externalIdFieldName": "Atonit_Mktplace__External_Id__c",
  "contentType": "CSV",
  "operation": "upsert",
  "lineEnding": "CRLF"
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Wed, 26 May 2021 13:35:28 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1581/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "7505Y00000QJI8TQAX",
      "operation": "upsert",
      "object": "Atonit_Mktplace__Inventory_Record__c",
      "createdById": "0055Y00000GrvNkQAJ",
      "createdDate": "2021-05-26T13:35:28.000+0000",
      "systemModstamp": "2021-05-26T13:35:28.000+0000",
      "state": "Open",
      "externalIdFieldName": "Atonit_Mktplace__External_Id__c",
      "concurrencyMode": "Parallel",
      "contentType": "CSV",
      "apiVersion": 51,
      "contentUrl": "services/data/v51.0/jobs/ingest/7505Y00000QJI8TQAX/batches",
      "lineEnding": "CRLF",
      "columnDelimiter": "COMMA"
    }
    ```
    

### PUT Upload Job Data

`PUT /services/data/v51.0/jobs/ingest/[jobID]/batches`

Operation ID: `Upload Job Data`. Tags: Bulk. Security: bearerAuth.

This call allows the data to be uploaded to a created job in CSV format. To call this endpoint, a jobID returned by the “Create a Job” call needs to be used. This upload may be broken down into various calls if there is a lot of data to be updated, with processing only starting when the start call is made in the job.

#### Parameters

*   `Content-Type` (header, string)
    
    _Example_
    
    ```
    text/csv
    ```
    

#### Request body

Media type: `application/json`. Schema: `object`.

Example: `Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Inventory__r.Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Product_Variant__r.Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Quantity__c{{seller-api-prefix}}-inventory-{{seller-api-prefix}}-sku-1,{{seller-api-prefix}}-inventory,{{seller-api-prefix}}-sku-1,99{{seller-api-prefix}}-incorrect_id-{{seller-api-prefix}}-sku-1,{{seller-api-prefix}}-incorrect_id,{{seller-api-prefix}}-sku-1,99`.

#### Responses

*   **201** Created
    
    Headers:
    
    *   `Date` (string)  
        Example: `Wed, 26 May 2021 13:36:10 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Content-Security-Policy` (string)  
        Example: `upgrade-insecure-requests` .
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1581/101002`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `text/plain`. Schema: `string`.
    
    Type: `string`.
    

### GET Get Job Info

`GET /services/data/v51.0/jobs/ingest/[jobID]`

Operation ID: `Get Job Info`. Tags: Bulk. Security: bearerAuth.

This call allows the current status of a job to be checked. The state field may have the following values:

*   Open: the job has just been created.
*   UploadComplete: the job has finished and is waiting to be queued for updating.
*   InProgress: the updates are in progress.
*   Aborted: the job was cancelled manually.
*   JobComplete: the job was completed (this does not necessarily mean that no errors occurred).
*   Failed: some kind of error occurred that prevented the job from running.

After ending, the fields `numberRecordsProcessed` and `numberRecordsFailed` show how many fields were processed in total and how many of these produced an error.

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Wed, 26 May 2021 13:37:28 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1582/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "7505Y00000QJI8TQAX",
      "operation": "upsert",
      "object": "Atonit_Mktplace__Inventory_Record__c",
      "createdById": "0055Y00000GrvNkQAJ",
      "createdDate": "2021-05-26T13:35:28.000+0000",
      "systemModstamp": "2021-05-26T13:36:38.000+0000",
      "state": "JobComplete",
      "externalIdFieldName": "Atonit_Mktplace__External_Id__c",
      "concurrencyMode": "Parallel",
      "contentType": "CSV",
      "apiVersion": 51,
      "jobType": "V2Ingest",
      "lineEnding": "CRLF",
      "columnDelimiter": "COMMA",
      "numberRecordsProcessed": 2,
      "numberRecordsFailed": 1,
      "retries": 0,
      "totalProcessingTime": 97,
      "apiActiveProcessingTime": 43,
      "apexProcessingTime": 0
    }
    ```
    

### PATCH Close a Job

`PATCH /services/data/v51.0/jobs/ingest/[jobID]`

Operation ID: `Close a Job`. Tags: Bulk. Security: bearerAuth.

Finalizes the upload of the job data and flags it to start the processing. Upon making this call, Salesforce will queue to start updating the data and no more uploads of data within the job will be permitted.

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "state": "UploadComplete"
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Wed, 26 May 2021 13:36:36 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1582/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "7505Y00000QJI8TQAX",
      "operation": "upsert",
      "object": "Atonit_Mktplace__Inventory_Record__c",
      "createdById": "0055Y00000GrvNkQAJ",
      "createdDate": "2021-05-26T13:35:28.000+0000",
      "systemModstamp": "2021-05-26T13:35:28.000+0000",
      "state": "UploadComplete",
      "externalIdFieldName": "Atonit_Mktplace__External_Id__c",
      "concurrencyMode": "Parallel",
      "contentType": "CSV",
      "apiVersion": 51
    }
    ```
    

### GET Get Job Failed Results

`GET /services/data/v51.0/jobs/ingest/[jobID]/failedResults/`

Operation ID: `Get Job Failed Results`. Tags: Bulk. Security: bearerAuth.

This call allows the reason for the error to be consulted when it was not possible to update a given field.

The response will be a CSV file and it is important to take care with its size, if there are many records with errors.

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Wed, 26 May 2021 13:38:46 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1585/101002`.
    *   `Content-Type` (string)  
        Example: `text/csv`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `text/plain`. Schema: `string`.
    
    Type: `string`.
    
    _Example_
    
    ```
    "sf__Id","sf__Error",Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Inventory__r.Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Product_Variant__r.Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Quantity__c"","INVALID_FIELD:Foreign key external ID: atonit-vitta-incorrect_id not found for field Atonit_Mktplace__External_Id__c in entity Atonit_Mktplace__Inventory__c:--","atonit-vitta-incorrect_id-atonit-vitta-sku-1","atonit-vitta-incorrect_id","atonit-vitta-sku-1","99.0"
    ```

<!-- document id=dff279d5d46e4df95d650283ce1af35f92d91cdd42281b0ca462dc92529afa9f url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/bulk-apis-for-creating-updating-store-associates.md -->

# Bulk APIs for Creating & Updating Store Associates

Point of Sale provides a set of bulk APIs to create, update, or upsert multiple store associates at once. The bulk endpoint supports three main operations:

- Create new or update existing associates based on storeAssociateID
- Create new associates in bulk
- Update existing associates

## Upsert Associates (Create or Update)

Use this `PUT` request to create a new associate (if the ID doesn't exist) or update the existing associate (if the ID exists).

```bash
curl --location --request PUT 'https://staging.predictspring.com/service/merchant/v1/associates/bulk' \
--header 'PredictSpring-API-Key: 5vQyY72pGz8jLwMh3k' \
--header 'PredictSpring-MerchantID: SHOPNOW20140910' \
--header 'PredictSpring-Locale: en_US' \
--header 'PredictSpring-Region: US' \
--header 'PredictSpring-Username: user@predictspring.com' \
--header 'Content-Type: application/json' \
--data-raw '{
    "associateList": [
        {
            "firstName": "Richard",
            "lastName": "Britto",
            "role": "STORE_MANAGER",
            "storeAssociateID": "9000102",
            "storeID": "1920",
            "gender": "Male",
            "hireDate": 1679081600000,
            "emailId": "rb@gmail.com",
            "storeType": "Retail",
            "active": false,
            "storeAssociatePassword": "200000Es",
            "storeAssociatePasswordPin": "1234"
        }
     ]
}'
```

## Create Associates

Use this `POST` request to create new associates. Each `storeAssociateID` must be unique and must not exist in the system yet.

```bash
curl --location 'https://staging.predictspring.com/service/merchant/v1/associates/bulk' \
--header 'PredictSpring-API-Key: 5vQyY72pGz8jLwMh3k' \
--header 'PredictSpring-MerchantID: SHOPNOW20140910' \
--header 'PredictSpring-Locale: en_US' \
--header 'PredictSpring-Region: US' \
--header 'PredictSpring-Username: user@predictspring.com' \
--header 'Content-Type: application/json' \
--data-raw '{
    "associateList": [
        {
            "firstName": "Richard",
            "lastName": "Britto",
            "role": "STORE_MANAGER",
            "storeAssociateID": "9000101",
            "storeID": "1920",
            "gender": "Male",
            "hireDate": 1679081600000,
            "emailId": "rb@gmail.com",
            "storeType": "Retail",
            "active": false,
            "storeAssociatePassword": "200000Es",
            "storeAssociatePasswordPin": "1234"
        }
     ]
}'
```

## Update Associates

Use this `PATCH` request to update existing associates. Only provide the fields you want to update.

```bash
curl --location --request PATCH 'https://staging.predictspring.com/service/merchant/v1/associates/bulk' \
--header 'PredictSpring-API-Key: 5vQyY72pGz8jLwMh3k' \
--header 'PredictSpring-MerchantID: SHOPNOW20140910' \
--header 'PredictSpring-Locale: en_US' \
--header 'PredictSpring-Region: US' \
--header 'PredictSpring-Username: user@predictspring.com' \
--header 'Content-Type: application/json' \
--data '{
    "associateList": [
        {
            "storeAssociateID": "2025",
            "storeAssociatePassword": "2026"
        }
    ]
}'
```

<!-- document id=0a0fb1f2919156d91370458f7ee89d9cb6633a3a8afd21012cece7b011bc9ae4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_use_cases.md -->

# Business Use Cases for the B2C Commerce Intelligence JDBC Driver

This section provides analytics scenarios with production SQL queries to copy, paste, and execute against the Commerce Intelligence data warehouse. Each use case includes the business question being answered, the data tables involved, sample SQL queries, and practical implementation tips.

**Note**: Refer to the [Apache Calcite SQL Reference](https://calcite.apache.org/docs/reference.html) for a list of supported SQL functions and expressions. The Commerce Intelligence JDBC Driver uses the PostgreSQL dialect for query parsing and execution.

| Use Case                                                             | Business Question                                                                   | Key Tables                                   | Primary Users                  |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- | ------------------------------ |
| [Sales Analytics](#sales-analytics)                                  | How is my business performing across revenue and orders?                            | `ccdw_aggr_sales_summary`                    | Merchandising                  |
| [Payment Method Analytics](#payment-method-analytics)                | Which payment methods are customers using and how do they perform?                  | `ccdw_aggr_payment_sales_summary`            | Operations                     |
| [Traffic Source Analytics](#traffic-source-analytics)                | Where is my traffic coming from and which sources drive the most valuable visitors? | `ccdw_aggr_visit_referrer`                   | Marketing, Digital             |
| [Customer Registration Analytics](#customer-registration-analytics)  | How effectively are we acquiring new customers and what drives registrations?       | `ccdw_aggr_registration`                     | Marketing, CRM                 |
| [Inventory Analytics](#inventory-analytics)                          | Do we have the right products available where customers want them?                  | `ccdw_fact_inventory_record_snapshot_hourly` | Operations, Supply Chain       |
| [Promotion Analytics](#promotion-analytics)                          | Are my promotions driving incremental sales or just discounting existing sales?     | `ccdw_aggr_promotion_sales_summary`          | Marketing, Merchandising       |
| [Search Analytics](#search-analytics)                                | Which search terms drive revenue vs which represent missed opportunities?           | `ccdw_aggr_search_conversion`                | Merchandising, UX              |
| [Product Analytics](#product-analytics)                              | How do my products perform across different channels?                               | `ccdw_aggr_product_sales_summary`            | Buyers, Merchandising          |
| [Customer Analytics](#customer-analytics)                            | How are we acquiring and retaining customers?                                       | `ccdw_dim_customer`                          | Marketing, CRM                 |
| [Visit & Traffic Analytics](#visit--traffic-analytics)               | What's the complete picture of site performance from traffic to revenue?            | `ccdw_aggr_visit`                            | Marketing, UX                  |
| [Technical Performance Analytics](#technical-performance-analytics)  | Is our system performing well enough to support customer experience?                | `ccdw_aggr_ocapi_request`                    | Operations, Engineering        |
| [Source Code & Campaign Analytics](#source-code--campaign-analytics) | Which marketing campaigns are driving actual sales vs just traffic?                 | `ccdw_aggr_source_code_activation`           | Marketing, Campaign Management |
| [Recommendation Analytics](#recommendation-analytics)                | How effective are our product recommendations and personalization?                  | `ccdw_aggr_product_recommendation`           | Merchandising, Personalization |

---

## Sales Analytics

**Business Question**: _How is my business performing across revenue and orders?_

**Primary Schema Tables**:

- [`ccdw_aggr_sales_summary`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_sales_summary.md) - Core sales metrics aggregation
- [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) - Site dimension for multi-site analysis
- [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) - Time dimension for trend analysis

**Business Value**: Merchandising teams track daily performance with automatic AOV/AOS calculations, seasonal trends, and cross-site comparisons.

**SQL Query**:

```sql
SELECT
    ss.submit_date AS "date",
    SUM(std_revenue) AS std_revenue,
    SUM(num_orders) AS orders,
    SUM(std_revenue) / SUM(num_orders) AS std_aov,
    SUM(num_units) AS units,
    SUM(num_units) / SUM(num_orders) AS aos,
    SUM(std_tax) AS std_tax,
    SUM(std_shipping) AS std_shipping
FROM ccdw_aggr_sales_summary ss
JOIN ccdw_dim_site s
    ON s.site_id = ss.site_id
WHERE ss.submit_date >= ?
    AND ss.submit_date <= ?
    AND s.nsite_id = ?
GROUP BY ss.submit_date
ORDER BY ss.submit_date
```

**Tip**: If you surface this in a UI, consider automatically calculating Average Order Value (AOV) and Average Order Size (AOS) from the aggregated data. Implement multiple currency support with automatic conversion display for global commerce scenarios.

**Key Metrics**: Revenue, Order count, Average Order Value, Units sold, Tax/Shipping amounts

---

## Payment Method Analytics

**Business Question**: _Which payment methods are customers using and how do they perform?_

**Primary Schema Tables**:

- [`ccdw_aggr_payment_sales_summary`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_payment_sales_summary.md) - Payment method performance metrics
- [`ccdw_fact_order_payments`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_order_payments.md) - Individual payment transactions
- [`ccdw_dim_payment_method`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_payment_method.md) - Payment method details

**Business Value**: Operations teams track payment method adoption, optimize payment processing costs, and analyze gift certificate usage patterns.

**SQL Query - Payment Method Performance**:

```sql
SELECT
    pm.display_name AS payment_method,
    SUM(pss.num_payments) AS total_payments,
    SUM(pss.num_orders) AS orders_with_payment,
    SUM(pss.std_captured_amount) AS std_captured_amount,
    SUM(pss.std_refunded_amount) AS std_refunded_amount,
    SUM(pss.std_transaction_amount) AS std_transaction_amount,
    (SUM(pss.std_captured_amount) / SUM(pss.num_payments)) AS avg_payment_amount
FROM ccdw_aggr_payment_sales_summary pss
JOIN ccdw_dim_payment_method pm ON pm.payment_method_id = pss.payment_method_id
JOIN ccdw_dim_site s ON s.site_id = pss.site_id
WHERE pss.submit_date >= ? AND pss.submit_date <= ?
    AND s.nsite_id = ?
GROUP BY pm.display_name
ORDER BY std_captured_amount DESC
```

**SQL Query - Gift Certificate Analysis**:

```sql
SELECT
    pss.submit_date AS "date",
    s.nsite_id AS site,
    SUM(pss.num_orders) AS redemption_count,
    SUM(pss.std_transaction_amount) AS std_redemption_value
FROM ccdw_aggr_payment_sales_summary pss
JOIN ccdw_dim_site s
    ON s.site_id = pss.site_id
JOIN ccdw_dim_payment_method pm
    ON pm.payment_method_id = pss.payment_method_id
WHERE pss.submit_date >= ?
    AND pss.submit_date <= ?
    AND s.nsite_id = ?
    AND pm.npayment_method_id = 'GIFT_CERTIFICATE'
GROUP BY
    pss.submit_date,
    s.nsite_id
ORDER BY
    pss.submit_date ASC,
    s.nsite_id ASC
```

**Tip**: If you surface this in a UI, consider calculating payment method conversion rates and failure rates. Track gift certificate redemption patterns to optimize gift certificate marketing campaigns and identify seasonal trends in gift giving behavior.

**Key Metrics**: Payment volume by method, Average payment amount, Gift certificate redemption rates, Payment success/failure rates

---

## Traffic Source Analytics

**Business Question**: _Where is my traffic coming from and which sources drive the most valuable visitors?_

**Primary Schema Tables**:

- [`ccdw_aggr_visit_referrer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_referrer.md) - Traffic source attribution
- [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md) - External traffic source dimension for order attribution
- [`ccdw_fact_line_item`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_line_item.md) - Order line items, including external-traffic columns
- [`ccdw_aggr_visit`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit.md) - Visit performance metrics
- [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) - Site dimension for multi-site analysis

**Business Value**: Marketing teams optimize ad spend by traffic source, measure campaign effectiveness, identify high-value referrer domains, and understand traffic performance.

**SQL Query - Top Referrers Analysis**:

```sql
WITH total AS (
    SELECT SUM(num_visits) AS total_visits
    FROM ccdw_aggr_visit_referrer
    WHERE visit_date >= ?
        AND visit_date <= ?
)
SELECT
    vr.referrer_medium AS traffic_medium,
    vr.referrer_source AS traffic_source,
    SUM(vr.num_visits) AS total_visits,
    SUM(vr.num_visits) * 100.0 / total.total_visits AS visit_percentage
FROM ccdw_aggr_visit_referrer vr
JOIN ccdw_dim_site s
    ON s.site_id = vr.site_id
JOIN total ON TRUE
WHERE vr.visit_date >= ?
    AND vr.visit_date <= ?
    AND s.nsite_id = ?
GROUP BY
    vr.referrer_medium,
    vr.referrer_source,
    total.total_visits
ORDER BY total_visits DESC
LIMIT 20
```

**SQL Query - Traffic Source Conversion Analysis**:

```sql
SELECT
    vr.referrer_medium AS traffic_medium,
    SUM(v.num_visits) AS total_visits,
    SUM(v.num_converted_visits) AS converted_visits,
    SUM(v.std_revenue) AS std_revenue,
    CASE WHEN SUM(v.num_visits) > 0
         THEN (CAST(SUM(v.num_converted_visits) AS FLOAT) / SUM(v.num_visits)) * 100
         ELSE 0
    END AS conversion_rate,
    CASE WHEN SUM(v.num_visits) > 0
         THEN SUM(v.std_revenue) / SUM(v.num_visits)
         ELSE 0
    END AS revenue_per_visit
FROM ccdw_aggr_visit_referrer vr
JOIN ccdw_aggr_visit v
    ON v.visit_date = vr.visit_date
    AND v.site_id = vr.site_id
    AND v.device_class_code = vr.device_class_code
JOIN ccdw_dim_site s
    ON s.site_id = vr.site_id
WHERE vr.visit_date >= ?
    AND vr.visit_date <= ?
    AND s.nsite_id = ?
GROUP BY vr.referrer_medium
ORDER BY std_revenue DESC
```

**Tip**: If you surface this in a UI, consider creating traffic source performance scorecards that combine visit volume, conversion rates, and revenue per visit. Distinguish between direct traffic, search engines, social media, and email campaigns to help marketing teams allocate budget effectively.

**Key Metrics**: Visit volume by source, Conversion rates by traffic medium, Revenue per visit by source, Traffic source diversity

---

## Customer Registration Analytics

**Business Question**: _How effectively are we acquiring new customers and what drives registrations?_

**Primary Schema Tables**:

- [`ccdw_aggr_registration`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_registration.md) - Customer acquisition tracking
- [`ccdw_fact_customer_registration`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_customer_registration.md) - Individual registration events
- [`ccdw_fact_customer_list_snapshot`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_customer_list_snapshot.md) - Customer counts over time
- [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md) - Customer master data

**Business Value**: Marketing teams track customer acquisition trends, measure registration conversion rates, identify optimal acquisition channels, and monitor customer base growth over time.

**SQL Query - Customer Registration Trends**:

```sql
SELECT
    r.registration_date AS "date",
    SUM(r.num_registrations) AS new_registrations,
    r.device_class_code,
    s.nsite_id
FROM ccdw_aggr_registration r
JOIN ccdw_dim_site s ON s.site_id = r.site_id
WHERE r.registration_date >= ? AND r.registration_date <= ?
    AND s.nsite_id = ?
GROUP BY r.registration_date, r.device_class_code, s.nsite_id
ORDER BY r.registration_date
```

**SQL Query - Total Customer Growth**:

```sql
WITH customer_snapshots AS (
    SELECT
        cls.site_id,
        cls.ncustomer_list_id,
        CAST(cls.utc_record_timestamp AS DATE) AS snapshot_date,
        cls.utc_record_timestamp,
        cls.num_customers,
        ROW_NUMBER() OVER (
            PARTITION BY cls.site_id, CAST(cls.utc_record_timestamp AS DATE)
            ORDER BY cls.utc_record_timestamp DESC
        ) AS rn
    FROM ccdw_fact_customer_list_snapshot cls
    JOIN ccdw_dim_site s
        ON cls.site_id = s.site_id
    WHERE CAST(cls.utc_record_timestamp AS DATE) >= ?
        AND CAST(cls.utc_record_timestamp AS DATE) <= ?
        AND s.nsite_id = ?
),
unique_lists AS (
    SELECT
        ncustomer_list_id,
        snapshot_date,
        num_customers,
        ROW_NUMBER() OVER (
            PARTITION BY ncustomer_list_id, snapshot_date
            ORDER BY utc_record_timestamp DESC
        ) AS rn
    FROM customer_snapshots
    WHERE rn = 1
)
SELECT
    snapshot_date,
    SUM(num_customers) AS total_customers
FROM unique_lists
WHERE rn = 1
GROUP BY snapshot_date
ORDER BY snapshot_date
```

**Tip**: If you surface this in a UI, consider calculating registration conversion rates from visits, tracking registration velocity trends, and segmenting registrations by acquisition source. Create cohort analysis to show customer lifetime value by registration period and device type.

**Key Metrics**: Daily registration counts, Total customer base growth, Registration conversion rates, Device-based registration patterns

---

## Inventory Analytics

**Business Question**: _Do we have the right products available where customers want them?_

**Primary Schema Tables**:

- [`ccdw_fact_inventory_record_snapshot_hourly`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_inventory_record_snapshot_hourly.md) - Real-time inventory levels
- [`ccdw_aggr_inventory_by_location`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_inventory_by_location.md) - Location-specific inventory
- [`ccdw_aggr_inventory_by_location_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_inventory_by_location_group.md) - Location group aggregations
- [`ccdw_dim_location_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location_group.md) - Location hierarchy
- [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) - Product details

**Business Value**: Operations teams monitor stock levels, optimize allocation across locations, reduce carrying costs, prevent stockouts, and improve fulfillment efficiency.

<!-- **SQL Query - Current Inventory Levels by Location Group**:

```sql
SELECT
    lg.nlocation_group_id,
    p.nsku_id,
    p.nproduct_id,
    SUM(ibl.available_to_fulfill) AS available_to_fulfill,
    SUM(ibl.available_to_order) AS available_to_order,
    SUM(ibl.on_hand) AS on_hand,
    SUM(ibl.reserved) AS reserved
FROM ccdw_aggr_inventory_by_location_group ibl
JOIN ccdw_dim_location_group lg ON lg.location_group_id = ibl.location_group_id
JOIN ccdw_dim_product p ON p.sku_id = ibl.sku_id
WHERE ibl.record_date = CURRENT_DATE
    AND lg.nlocation_group_id = ?
GROUP BY lg.nlocation_group_id, p.nsku_id, p.nproduct_id
ORDER BY available_to_fulfill DESC
LIMIT 100
```-->

**SQL Query - Inventory Trends Over Time for Specific SKU**:

```sql
SSELECT
    ih.utc_record_timestamp AS "timestamp",
    p.nsku_id,
    p.nproduct_id,
    SUM(ih.available_to_fulfill) AS available_to_fulfill,
    SUM(ih.available_to_order) AS available_to_order,
    SUM(ih.on_hand) AS on_hand,
    SUM(ih.reserved) AS reserved
FROM
    (SELECT utc_record_timestamp, sku_id, location_group_id,
            available_to_fulfill, available_to_order, on_hand, reserved
     FROM ccdw_fact_inventory_record_snapshot_hourly) ih
JOIN
    (SELECT sku_id, nsku_id, nproduct_id FROM ccdw_dim_product) p
    ON p.sku_id = ih.sku_id
JOIN
    (SELECT location_group_id, nlocation_group_id FROM ccdw_dim_location_group) lg
    ON lg.location_group_id = ih.location_group_id
WHERE
    ih.utc_record_timestamp >= ?
    AND ih.utc_record_timestamp <= ?
    AND p.nsku_id = ?
    AND lg.nlocation_group_id = ?
GROUP BY
    ih.utc_record_timestamp, p.nsku_id, p.nproduct_id
ORDER BY
    ih.utc_record_timestamp
```

**Tip**: If you surface this in a UI, consider creating inventory alerts for low stock situations, tracking inventory velocity trends, and providing fulfillment optimization recommendations. Implement location-based inventory allocation suggestions to optimize shipping costs and delivery times.

**Key Metrics**: Available to fulfill quantities, Available to order quantities, On-hand inventory, Reserved inventory, Inventory turnover rates

---

## Promotion Analytics

**Business Question**: _Are my promotions driving incremental sales or just discounting existing sales?_

**Data Combination Strategy**: Combines 3 data sources for comprehensive promotion effectiveness:

1. **Promotion Performance** - [`ccdw_aggr_promotion_sales_summary`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_promotion_sales_summary.md)
2. **Overall Visit Data** - [`ccdw_aggr_visit`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit.md)
3. **Overall Sales Data** - [`ccdw_aggr_sales_summary`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_sales_summary.md)

**Primary Schema Tables**:

- [`ccdw_aggr_promotion_sales_summary`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_promotion_sales_summary.md) - Promotion-specific sales data
- [`ccdw_dim_promotion`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_promotion.md) - Promotion details and classification
- [`ccdw_dim_campaign`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_campaign.md) - Campaign information
- [`ccdw_dim_coupon`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_coupon.md) - Coupon details

**SQL Query - Total Discount Analysis**:

```sql
WITH TOTAL_ORDERS AS (
    SELECT
        ss.submit_date AS submit_day,
        SUM(num_orders) AS total_orders
    FROM ccdw_aggr_sales_summary ss
    WHERE ss.submit_date >= ?
        AND ss.submit_date <= ?
    GROUP BY ss.submit_date
),
PROMOTION_DISCOUNT AS (
    SELECT
        pss.submit_date AS submit_day,
        p.promotion_class AS promotion_class,
        SUM(std_total_discount) AS std_total_discount,
        SUM(num_orders) AS promotion_orders
    FROM ccdw_aggr_promotion_sales_summary pss
    JOIN ccdw_dim_promotion p
        ON p.promotion_id = pss.promotion_id
    WHERE pss.submit_date >= ?
        AND pss.submit_date <= ?
    GROUP BY pss.submit_date, p.promotion_class
)
SELECT
    t.submit_day,
    t.total_orders,
    p.promotion_class,
    p.std_total_discount,
    p.promotion_orders,
    p.std_total_discount / p.promotion_orders AS avg_discount_per_order
FROM TOTAL_ORDERS t
LEFT JOIN PROMOTION_DISCOUNT p
    ON t.submit_day = p.submit_day
```

**Tip**: If you surface this in a UI, consider calculating incremental metrics by subtracting promotional performance from total performance to show "Without Promo" analysis. Create side-by-side comparison views showing promotional vs non-promotional conversion rates for clear impact assessment.

**Business Value**: Marketing teams compare promotional vs non-promotional performance, measure incremental revenue, and optimize promotion mix by type (product/order/shipping).

---

## Search Analytics

**Business Question**: _Which search terms drive revenue vs which represent missed opportunities?_

**Data Combination**: Search queries + results filtering → revenue attribution analysis

**Primary Schema Tables**:

- [`ccdw_aggr_search_conversion`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_search_conversion.md) - Search-to-purchase conversion data
- [`ccdw_aggr_search_query`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_search_query.md) - Search behavior and results
- [`ccdw_aggr_search`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_search.md) - Search volume metrics

**SQL Query - Search Query Performance**:

```sql
WITH conversion AS (
    SELECT
        LOWER(sc.query) AS query,
        SUM(sc.num_searches) AS converted_searches,
        SUM(sc.num_orders) AS orders,
        SUM(sc.std_revenue) AS std_revenue,
        SUM(sc.std_revenue) / NULLIF(CAST(SUM(sc.num_orders) AS FLOAT), 0) AS std_revenue_per_order
    FROM ccdw_aggr_search_conversion sc
    JOIN ccdw_dim_site s
        ON s.site_id = sc.site_id
    WHERE sc.search_date >= ?
        AND sc.search_date <= ?
        AND s.nsite_id = ?
        AND sc.has_results = ?
    GROUP BY LOWER(sc.query)
)
SELECT
    query,
    converted_searches,
    orders,
    std_revenue,
    std_revenue_per_order,
    CASE WHEN converted_searches > 0
         THEN (CAST(orders AS FLOAT) / converted_searches) * 100
         ELSE 0
    END AS conversion_rate
FROM conversion
ORDER BY std_revenue DESC
```

**Tip**: If you surface this in a UI, consider providing toggles between "With Results" vs "Without Results" to highlight successful vs failed searches. Calculate revenue per search and conversion rates to show search effectiveness. Present failed searches as catalog gaps and missed opportunities for merchandising teams.

**Business Value**: Merchandising teams identify high-converting search terms, optimize product catalog for failed searches, and improve search result relevance.

---

## Product Analytics

**Business Question**: _How do my products perform across different and channels?_

**Multi-Dimensional Transformation**: Single product query → 4 different dimensional views:

1. By Device Type (Mobile vs Desktop)
2. By Site (Multi-site performance)
3. By Channel (Online vs other channels)
4. By Customer Type (Registered vs guest)

**Primary Schema Tables**:

- [`ccdw_aggr_product_sales_summary`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_sales_summary.md) - Product sales by dimensions
- [`ccdw_fact_line_item`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_line_item.md) - Individual purchase transactions
- [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) - Product master data
- [`ccdw_aggr_product_cobuy`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_cobuy.md) - Cross-sell analysis

**SQL Query - Top Selling Products**:

```sql
SELECT
    p.nproduct_id,
    p.product_display_name,
    SUM(pss.num_units) as units_sold,
    SUM(pss.std_revenue) as std_revenue,
    SUM(pss.num_orders) as order_count,
    pss.device_class_code,
    pss.registered,
    s.nsite_id
FROM ccdw_aggr_product_sales_summary pss
JOIN ccdw_dim_product p ON p.product_id = pss.product_id
JOIN ccdw_dim_site s ON s.site_id = pss.site_id
WHERE pss.submit_date >= ? AND pss.submit_date <= ?
    AND s.nsite_id = ?
GROUP BY p.nproduct_id, p.product_display_name, pss.device_class_code, pss.registered, s.nsite_id
ORDER BY std_revenue DESC
```

**SQL Query - Product Co-Purchase Analysis**:

```sql
SELECT
    p1.nproduct_id as product_1_id,
    p1.product_display_name as product_1_name,
    p2.nproduct_id as product_2_id,
    p2.product_display_name as product_2_name,
    pcb.frequency_count as co_purchase_count,
    pcb.std_cobuy_revenue
FROM ccdw_aggr_product_cobuy pcb
JOIN ccdw_dim_product p1 ON p1.product_id = pcb.product_one_id
JOIN ccdw_dim_product p2 ON p2.product_id = pcb.product_two_id
JOIN ccdw_dim_site s ON s.nsite_id = pcb.nsite_id
WHERE pcb.submit_date >= ? AND pcb.submit_date <= ?
    AND s.nsite_id = ?
ORDER BY pcb.frequency_count DESC
```

**Tip**: If you surface this in a UI, consider transforming single product queries into multiple dimensional views (Device/Site/Channel/Customer) with toggleable filters. Calculate cross-sell opportunities and product affinity scores from co-purchase data to guide merchandising decisions.

**Business Value**: Buyers optimize product placement by channel and guide inventory allocation decisions.

---

## Customer Analytics

**Business Question**: _How are we acquiring and retaining customers?_

**Primary Schema Tables**:

- [`ccdw_aggr_registration`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_registration.md) - Customer acquisition tracking
- [`ccdw_fact_customer_registration`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_customer_registration.md) - Individual registration events
- [`ccdw_fact_customer_list_snapshot`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_customer_list_snapshot.md) - Customer counts over time
- [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md) - Customer master data

**SQL Query - Customer Registration Trends**:

```sql
SELECT
    r.registration_date AS registration_dt,
    SUM(r.num_registrations) AS new_registrations,
    r.device_class_code,
    s.nsite_id
FROM ccdw_aggr_registration r
JOIN ccdw_dim_site s
    ON s.site_id = r.site_id
WHERE r.registration_date >= ?
    AND r.registration_date <= ?
    AND s.nsite_id = ?
GROUP BY
    r.registration_date,
    r.device_class_code,
    s.nsite_id
ORDER BY r.registration_date
```

**SQL Query - Total Customer Counts**:

```sql
SELECT
    cls.std_record_timestamp as snapshot_date,
    SUM(cls.num_customers) as total_customers,
    s.nsite_id
FROM ccdw_fact_customer_list_snapshot cls
JOIN ccdw_dim_site s ON s.site_id = cls.site_id
WHERE cls.std_record_timestamp >= ? AND cls.std_record_timestamp <= ?
    AND s.nsite_id = ?
GROUP BY cls.std_record_timestamp, s.nsite_id
ORDER BY cls.std_record_timestamp
```

**Tip**: If you surface this in a UI, consider calculating new vs returning customer ratios and tracking customer acquisition velocity over time. Segment customers by registration source and device type to understand acquisition patterns and optimize marketing channels.

**Business Value**: Marketing teams track customer acquisition trends, segment new vs returning customers, and measure retention rates.

---

## Visit & Traffic Analytics

**Business Question**: _What's the complete picture of site performance from traffic to revenue?_

**Multi-Query Coordination**: 5 different data sources in unified presentation:

1. Visit Volume - [`ccdw_aggr_visit`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit.md)
2. Visit Duration - [`ccdw_aggr_visit`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit.md) with duration calculations
3. Revenue per Visit - [`ccdw_aggr_visit`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit.md) conversion data
4. Traffic Sources - [`ccdw_aggr_visit_referrer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_referrer.md)
5. Device Analysis - [`ccdw_aggr_visit_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_user_agent.md)

**Primary Schema Tables**:

- [`ccdw_aggr_visit`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit.md) - Core visit metrics and conversion
- [`ccdw_aggr_visit_referrer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_referrer.md) - Traffic source attribution
- [`ccdw_aggr_visit_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_user_agent.md) - Device and browser analysis
- [`ccdw_aggr_visit_checkout`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_visit_checkout.md) - Checkout funnel analysis

**SQL Query - Visit Metrics by Device**:

```sql
SELECT
    v.visit_date AS visit_dt,
    v.device_class_code,
    SUM(v.num_visits) AS visits,
    SUM(v.num_converted_visits) AS converted_visits,
    SUM(v.visit_duration) AS total_duration,
    SUM(v.std_revenue) AS std_revenue,
    CASE WHEN SUM(v.num_visits) > 0
         THEN SUM(v.std_revenue) / SUM(v.num_visits)
         ELSE 0
    END AS revenue_per_visit
FROM ccdw_aggr_visit v
JOIN ccdw_dim_site s
    ON s.site_id = v.site_id
WHERE v.visit_date >= ?
    AND v.visit_date <= ?
    AND s.nsite_id = ?
GROUP BY
    v.visit_date,
    v.device_class_code
ORDER BY
    v.visit_date,
    v.device_class_code
```

**Tip**: If you surface this in a UI, consider coordinating multiple data sources to create a unified traffic dashboard. Calculate conversion rates, average session duration, and revenue per visit across different dimensions for comprehensive traffic analysis.

**Business Value**: Marketing managers see complete traffic funnel from visits to revenue to customer acquisition.

---

## Technical Performance Analytics

**Business Question**: _Is our system performing well enough to support customer experience?_

**UI Data Transformation**: Raw technical data → business-relevant performance indicators:

- **OCAPI Performance**: [`ccdw_aggr_ocapi_request`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_ocapi_request.md) → Average response times
- **SCAPI Cache**: [`ccdw_aggr_scapi_request`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_scapi_request.md) → Cache hit percentages
- **Controller Performance**: [`ccdw_aggr_controller_request`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_controller_request.md) → Performance buckets

**Primary Schema Tables**:

- [`ccdw_aggr_ocapi_request`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_ocapi_request.md) - Open Commerce API performance
- [`ccdw_aggr_scapi_request`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_scapi_request.md) - Storefront API performance
- [`ccdw_aggr_controller_request`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_controller_request.md) - Controller performance
- [`ccdw_aggr_include_controller_request`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_include_controller_request.md) - Include controller metrics

**SQL Query - OCAPI Performance**:

```sql
SELECT
    o.request_date,
    o.api_name,
    o.api_resource,
    SUM(o.num_requests) as total_requests,
    SUM(o.response_time) as total_response_time,
    CASE WHEN SUM(o.num_requests) > 0
         THEN SUM(o.response_time) / SUM(o.num_requests)
         ELSE 0 END as avg_response_time,
    o.client_id
FROM ccdw_aggr_ocapi_request o
JOIN ccdw_dim_site s ON s.site_id = o.site_id
WHERE o.request_date >= ? AND o.request_date <= ?
    AND s.nsite_id = ?
GROUP BY o.request_date, o.api_name, o.api_resource, o.client_id
ORDER BY total_requests DESC
```

**Tip**: If you surface this in a UI, consider calculating average response times from raw request counts and total response times. Create performance bucket visualizations and cache hit percentage calculations for operational monitoring and SLA tracking.

**Business Value**: Operations teams monitor system health, identify performance issues before customer impact, and optimize infrastructure spend.

---

## Source Code & Campaign Analytics

**Business Question**: _Which marketing campaigns are driving actual sales vs just traffic?_

**Data Combination Strategy**: Combines source code activations with order data to calculate campaign conversion rates and attribution:

1. **Campaign Activations** - [`ccdw_aggr_source_code_activation`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_source_code_activation.md)
2. **Campaign Orders** - [`ccdw_aggr_source_code_sales`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_source_code_sales.md)
3. **Campaign Organization** - [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md)

**Primary Schema Tables**:

- [`ccdw_aggr_source_code_activation`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_source_code_activation.md) - Campaign activation tracking
- [`ccdw_aggr_source_code_sales`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_source_code_sales.md) - Sales attribution to campaigns
- [`ccdw_fact_source_codes_activation`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_source_codes_activation.md) - Individual activation events
- [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md) - Campaign organization

**SQL Query - Source Code Activations Analysis**:
_This query measures marketing campaign traffic volume and health status across different sites and campaign groups._

```sql
SELECT
    s.nsite_id AS site,
    g.nsource_code_group_id AS group_id,
    CASE
        WHEN sca.source_code_status = '0' THEN 'ACTIVE'
        WHEN sca.source_code_status = '1' THEN 'INACTIVE'
        WHEN sca.source_code_status = '2' THEN 'INVALID'
        ELSE sca.source_code_status
    END AS status,
    SUM(sca.num_activations) AS activations
FROM ccdw_aggr_source_code_activation sca
JOIN ccdw_dim_site s
    ON s.site_id = sca.site_id
JOIN ccdw_dim_source_code_group g
    ON g.source_code_group_id = sca.source_code_group_id
WHERE sca.activation_date >= ?
    AND sca.activation_date <= ?
    AND s.nsite_id = ?
    AND sca.device_class_code = ?
    AND sca.registered = ?
GROUP BY
    s.nsite_id,
    g.nsource_code_group_id,
    sca.source_code_status
ORDER BY
    s.nsite_id ASC,
    g.nsource_code_group_id ASC
```

#### Query Details

- **Business Purpose**: Tracks how many times customers clicked on or activated marketing campaigns (source codes)
- **Status Logic**: Converts numeric status codes (0/1/2) to human-readable campaign states
- **Segmentation**: Groups results by site and campaign group for campaign portfolio analysis
- **Filters**: Allows filtering by date range, site, device type (mobile/desktop), and customer registration status
- **Key Metric**: `activations` = total number of times campaigns were activated/clicked

**SQL Query - Source Code Sales Performance**:
_This query measures actual sales results (orders, units, revenue) attributed to marketing campaigns, enabling ROI calculation and campaign effectiveness analysis._

```sql
SELECT
    s.nsite_id AS site,
    g.nsource_code_group_id AS group_id,
    CASE
        WHEN sco.source_code_status = '0' THEN 'ACTIVE'
        WHEN sco.source_code_status = '1' THEN 'INACTIVE'
        WHEN sco.source_code_status = '2' THEN 'INVALID'
        ELSE sco.source_code_status
    END AS status,
    SUM(sco.num_orders) AS orders,
    SUM(sco.num_units) AS units,
    SUM(sco.std_revenue) AS std_revenue
FROM ccdw_aggr_source_code_sales sco
JOIN ccdw_dim_site s
    ON s.site_id = sco.site_id
JOIN ccdw_dim_source_code_group g
    ON g.source_code_group_id = sco.source_code_group_id
WHERE sco.submit_date >= ?
    AND sco.submit_date <= ?
    AND s.nsite_id = ?
    AND sco.device_class_code = ?
    AND sco.registered = TRUE
GROUP BY
    s.nsite_id,
    g.nsource_code_group_id,
    sco.source_code_status
ORDER BY
    s.nsite_id ASC,
    g.nsource_code_group_id ASC
```

#### Query Details

- **Business Purpose**: Measures actual sales attributed to marketing campaigns for ROI analysis
- **Attribution Logic**: Only counts orders that were directly attributed to specific source codes/campaigns
- **Key Metrics**:
  - `orders` = number of orders attributed to this campaign
  - `units` = total units sold through this campaign
  - `std_revenue` = gross merchandise value in site's base currency
- **ROI Calculation**: Combine with activations data to calculate conversion rate (orders/activations)
- **Campaign Performance**: Compare revenue across different campaign groups and statuses

**Tip**: If you surface this in a UI, consider combining activations and orders data to calculate campaign conversion rates (orders/activations) and campaign efficiency metrics. Track ACTIVE vs INACTIVE vs INVALID source codes separately to understand campaign lifecycle performance.

**Business Value**: Marketing teams measure campaign effectiveness, calculate ROI by source code group, and optimize marketing spend allocation based on actual sales attribution rather than just traffic volume.

---

## Recommendation Analytics

**Business Question**: _How effective are our product recommendations and personalization?_

**Data Transformation Strategy**: Combines recommendation viewing data with purchase attribution to calculate recommendation algorithm effectiveness:

1. **Recommendation Performance** - [`ccdw_aggr_product_recommendation_recommender`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_recommendation_recommender.md)
2. **Product-Level Details** - [`ccdw_aggr_detail_product_recommendation_recommender`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_detail_product_recommendation_recommender.md)
3. **Cross-Algorithm Comparison** - Multiple recommender performance analysis

**Primary Schema Tables**:

- [`ccdw_aggr_product_recommendation`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_recommendation.md) - Overall recommendation performance
- [`ccdw_aggr_product_recommendation_recommender`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_product_recommendation_recommender.md) - Performance by recommender type
- [`ccdw_aggr_detail_product_recommendation_recommender`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_detail_product_recommendation_recommender.md) - Product-level recommendation data

**SQL Query - Recommendation Performance by Algorithm**:
_This query analyzes the effectiveness of different recommendation algorithms (Einstein, collaborative filtering, etc.) by measuring user engagement and sales attribution across the entire recommendation funnel._

```sql
SELECT
    s.nsite_id,
    rpr.recommender_name,
    SUM(rpr.num_recommender_views) AS recommender_views_count,
    SUM(rpr.num_product_views) AS product_views_count,
    SUM(rpr.num_clicks) AS clicks_count,
    SUM(rpr.num_cart_adds) AS add_to_cart_count,
    SUM(rpr.num_products_purchased) AS product_purchased_count,
    SUM(rpr.num_orders) AS order_count,
    SUM(rpr.std_attributed_revenue) AS std_attributed_revenue,
    CASE SUM(rpr.num_recommender_views)
        WHEN 0 THEN 0
        ELSE CAST(SUM(rpr.num_clicks) AS FLOAT) / SUM(rpr.num_recommender_views)
    END AS ctr,
    CASE SUM(rpr.num_clicks)
        WHEN 0 THEN 0
        ELSE CAST(SUM(rpr.num_cart_adds) AS FLOAT) / SUM(rpr.num_clicks)
    END AS atc_rate,
    CASE SUM(rpr.num_cart_adds)
        WHEN 0 THEN 0
        ELSE CAST(SUM(rpr.num_products_purchased) AS FLOAT) / SUM(rpr.num_cart_adds)
    END AS conversion_rate
FROM (
    SELECT
        site_id, recommender_name, recommendation_date,
        num_recommender_views, num_product_views, num_clicks,
        num_cart_adds, num_products_purchased, num_orders, std_attributed_revenue
    FROM ccdw_aggr_product_recommendation_recommender
) rpr
JOIN (
    SELECT site_id, nsite_id
    FROM ccdw_dim_site
) s ON s.site_id = rpr.site_id
WHERE rpr.recommendation_date >= DATE ?
  AND rpr.recommendation_date <= DATE ?
  AND s.nsite_id = ?
  AND rpr.recommender_name = ?
GROUP BY s.nsite_id, rpr.recommender_name
ORDER BY std_attributed_revenue DESC
```

#### Query Details

- **Business Purpose**: Compares effectiveness of different recommendation algorithms to optimize personalization strategy
- **Recommendation Funnel Analysis**:
  - `recommender_views_count` = how many times recommendation widgets were shown
  - `product_views_count` = how many times users viewed products within recommendations
  - `clicks_count` = how many times users clicked on recommended products
  - `add_to_cart_count` = how many times users added recommended products to cart
  - `product_purchased_count` = how many recommended products were actually purchased
- **Performance Metrics**:
  - `ctr` (Click-Through Rate) = clicks / widget views (measures initial engagement)
  - `atc_rate` (Add-to-Cart Rate) = cart adds / clicks (measures purchase intent)
  - `conversion_rate` = purchases / cart adds (measures final conversion)
- **Revenue Attribution**: `std_attributed_revenue` = revenue directly attributed to recommendations
- **Algorithm Comparison**: Results ordered by revenue to identify best-performing algorithms

<!-- **SQL Query - Top Products by Recommendation Algorithm**:
_This query identifies which specific products perform best with each recommendation algorithm, enabling optimization of product placement and merchandising strategy for recommendation widgets._

```sql
SELECT
    s.nsite_id AS site,
    dpr.recommender_name,
    CASE p.product_id
        WHEN 0 THEN 'Unknown'
        ELSE p.nproduct_id
    END as nproduct_id,
    CASE p.product_id
        WHEN 0 THEN 'Unknown'
        ELSE p.product_display_name
    END as product_display_name,
    SUM(dpr.num_recommender_views) as recommender_views_count,
    SUM(dpr.num_product_views) as product_views_count,
    SUM(dpr.num_clicks) as clicks_count,
    SUM(dpr.num_cart_adds) as add_to_cart_count,
    SUM(dpr.num_products_purchased) as product_purchased_count,
    SUM(dpr.num_orders) as order_count,
    SUM(dpr.std_attributed_revenue) as std_attributed_revenue,
    CASE SUM(dpr.num_recommender_views)
        WHEN 0 THEN 0
        ELSE CAST(SUM(dpr.num_clicks) AS FLOAT) / SUM(dpr.num_recommender_views)
    END as ctr,
    CASE SUM(dpr.num_clicks)
        WHEN 0 THEN 0
        ELSE CAST(SUM(dpr.num_cart_adds) AS FLOAT) / SUM(dpr.num_clicks)
    END as atc_rate,
    CASE SUM(dpr.num_cart_adds)
        WHEN 0 THEN 0
        ELSE CAST(SUM(dpr.num_products_purchased) AS FLOAT) / SUM(dpr.num_cart_adds)
    END as conversion_rate
FROM ccdw_aggr_detail_product_recommendation_recommender dpr
JOIN ccdw_dim_product p ON p.product_id = dpr.product_id
JOIN ccdw_dim_site s ON s.site_id = dpr.site_id
WHERE dpr.recommendation_date >= ? AND dpr.recommendation_date <= ?
    AND s.nsite_id = ?
    AND dpr.recommender_name = ?
GROUP BY s.nsite_id, dpr.recommender_name, p.nproduct_id, p.product_id, p.product_display_name
ORDER BY std_attributed_revenue DESC
LIMIT 100
```

#### Query Details

- **Business Purpose**: Identifies top-performing products within specific recommendation algorithms for merchandising optimization
- **Product-Level Analysis**: Breaks down recommendation performance by individual product rather than algorithm aggregate
- **Cross-sell Optimization**: Shows which products work best as recommendations vs. primary purchases
- **Unknown Product Handling**: Gracefully handles cases where product_id = 0 (deleted or missing products)
- **Performance Ranking**: Orders results by attributed revenue to identify highest-value recommended products
- **Top 100 Limit**: Focuses on most significant products to avoid overwhelming results
- **Merchandising Insights**:
  - Which products should be featured more prominently in recommendation widgets?
  - Which products have high click rates but low conversion (need better targeting)?
  - Which products drive the most incremental revenue through recommendations?
- **Algorithm-Specific Results**: Filter by `recommender_name` to compare product performance across different engines

**Tip**: If you surface this in a UI, consider calculating click-through rates (CTR), add-to-cart rates, and conversion rates to measure recommendation algorithm effectiveness. Compare different recommender algorithms side-by-side and track revenue attribution to optimize personalization strategy.

**Business Value**: Merchandising teams optimize recommendation algorithms, identify best-performing product combinations, improve cross-sell/up-sell effectiveness, and increase average order value through data-driven personalization decisions. -->

<!-- document id=cfd3f87ff31087c2d97992e084956305b8797fa6a908e0d64f1ff30a09cb7ec5 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-caching.md -->

# Caching

Custom APIs support the caching of responses.
Using this feature enhances the performance by reducing the need to repeatedly retrieve or compute data, resulting in faster response times and improved overall system efficiency.
For more information on caching strategies, see [Caching Strategies for Salesforce B2C Commerce](https://developer.salesforce.com/docs/commerce/solutions/guides/caching-strategies-sk.md).

To use caching for your Custom API endpoints, enable _Page Caching_ for the sites using the Custom API. After that, a response can be cached in the implementation script in these ways:

- Use the `dw.system.Response#setExpires(milliseconds)` Script API method [as described here](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_Response.html#dw_system_Response_setExpires_Number_DetailAnchor) to set the cache time.
- Use the `dw.system.Response#setVaryBy(identifier)` Script API method [as described here](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_Response.html#dw_system_Response_setVaryBy_String_DetailAnchor) to mark the response as personalized. Use this with caution as it might result in performance degradation in places where the response is not actually personalized.

**Example 1:** An implementation of a custom product API that caches responses for 60 seconds:

```javascript
var RESTResponseMgr = require("dw/system/RESTResponseMgr");

exports.getCustomProduct = function () {
  var customProduct = // ... some lookup of custom product data ...
    // set cache time to 60 seconds
    response.setExpires(Date.now() + 60000);

  RESTResponseMgr.createSuccess(customProduct).render();
};

exports.getCustomProduct.public = true;
```

**Example 2:** An implementation of a custom product API that caches responses based on promotion:

```javascript
var RESTResponseMgr = require("dw/system/RESTResponseMgr");

exports.getCustomProduct = function () {
  var customProduct = // ... some lookup of custom product data ...
    // set caching based on promotion
    response.setVaryBy("price_promotion");

  RESTResponseMgr.createSuccess(customProduct).render();
};

exports.getCustomProduct.public = true;
```

<!-- document id=f16d7247f1a45182eed2e0d4f6516ad0a4624d4a0f602992f0ef25546901cc20 url=/developer/current/en-us/commerce-cloud/solutions/guides/caching-strategies-sk.md -->

# Caching Strategies for Salesforce B2C Commerce

Every merchant strives to have a fast and reliable website as the foundation of their shopper experience. One essential part of achieving great website speed is implementing efficient caching strategies that move content delivery as close to the consumer as possible.

A common misperception is that caching in Salesforce B2C Commerce means adding to a few templates, but there’s a lot more to it than that. First of all, you must understand the different layers of caching, which include:

- the shopper’s browser
- the CDN
- the web server
- the application server
- the storage layer (database)

An efficient caching strategy tries to move the cached content up this ladder as much as possible. The more layers being traversed, the slower the response times and the smaller the potential throughput of the website.

Well-cached, well-architected pages are also more resilient to bot traffic. Uncached, expensive endpoints are the most common attack target and the most likely to trigger platform-side protective action during an incident. For more information, see [Bot Mitigation Best Practices for Flash Sales](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-mitigation-sk.md) and [Shared Responsibility Model](https://help.salesforce.com/s/articleView?id=cc.b2c_shared_responsibility_model.htm&type=5).

## Example Use Case

Let’s consider some examples that illustrate what an effective caching strategy looks like. Often developers work in silos or have a limited understanding of all the available architectural layers (while having a good understanding of one or two of the layers). This situation leads to solutions with limited scalability. The following example illustrates the power of using a combination of layers, instead of trying to solve the problem as a single one.

### Requirement

Show a heart icon (with a red outline) for each product of a search result, but show a heart icon that’s solid red for items the shopper saved to a wishlist.

### A Typical Solution

A common approach is that the backend developer implements a solution that renders HTML representing the wishlist state of a given product. This approach is functionally correct but problematic. Because the result is specific to each shopper, the application needs to dynamically calculate this information for each product tile (the small product area shown in search results), traversing all the architectural layers.

### A Better Solution

By looking at the requirement, you notice that the wishlist contents don’t change frequently, and for scalability reasons, it’s desirable to have product tiles cached (without any dynamic calculations). With this in mind, a better solution exposes the wishlist content as an HTML data attribute in a pre-existing dynamic include (such as shopper information or login state in the header), and then updates the heart icon status via client-side JavaScript. On the server side, this approach comes at almost no additional cost, and the operation on the client side is relatively minor, too.

As a result, we have a solution that more efficiently leverages the available layers to achieve great end-consumer performance and allows for much better scalability compared to the server-side solution.

## Caching in Salesforce B2C Commerce

Now that we’ve addressed caching fundamentals, let’s focus on some of the specifics in Salesforce B2C Commerce. The following architectural layers manage caching.

- Web Server Layer > Page Cache
- Application Server Layer > Custom Caches (CacheMgr)
- Storage Layer > Custom Attributes or Custom Objects.

Let’s consider how you’d leverage each of these layers.

### Page Caching

Page caching is one of the most critical concepts of the cache mix as it represents the topmost layer of the platform. Requests served from the page cache don't create load on the application or storage layers.
Remote includes make this concept even more powerful. These Server Side Includes (SSI) are placeholders in the page for which the web tier issues a new request, which can have its own cache policy.

For example, assume you have a static content page, which is entirely cacheable, and you want to include dynamic information like the shopper’s login state. Do this by using a remote include. While the main request might be cached for a number of days, another request is issued that dynamically retrieves the shopper information to display in the header. This subrequest isn’t cached. The web tier inserts the dynamically computed piece of the page into the cached frame. The result is a whole page that contains both cached and uncached elements.

In essence, the page cache is a key value store. The key is the full URL including query string and the value is the cached page. The page can contain markers for remote includes that are resolved the same way. The high-level processing logic is as follows.

1. The request is made.
2. Check if the cache entry for the given request path exists.

   - If Yes: Use the cached response and continue with processing remote includes. For each remote include, start at 1.
   - If No:

     1. Call the application layer to obtain a response.
     2. Check if the response is marked for caching. If yes, save in the page cache.
     3. Return the response.

### Examples of Different URLs

The following URLs all create different cache entries and can (involuntarily) contribute to excessively high amounts of cache entries and a lower cache hit rate, because all those results are computed first. As such, it’s important to avoid adding dynamic parameters to includes, which are likely to change frequently (but don’t impact the response).

`https://www.domain.com/path?param1=1`
`https://www.domain.com/path?param1=2` (change in parameter)
`https://www.domain.com/path?param1=1&param2=abc` (additional parameter)
`https://www.domain.com/path?param2=abc&param1=1` (change in parameter order)
`https://www.domain.de/path?param1=1` (different domain)
`https://www.domain.com/otherpath?param1=1` (different path)

One commonly applied anti-pattern is adding a position parameter to product tiles in a search result, which causes ineffective tile caching. Each tile is cached numerous times depending on its positioning in the search result, even though the same product is always displayed. This implementation allows navigation of the search result on the product detail page (PDP) by passing the search information via the product detail page URL. Also achieve this use case by applying a client-side solution, which drastically increases the throughput of the search pages.

Sometimes parameters are appended to your URLs that have no meaning for your page, such as the campaign ID of a newsletter campaign. The platform can ignore certain parameters for the purpose of caching. Configure this option in Business Manager by going to **Administration > Feature Switches**. In the same section, enable caching of 404 responses, which can positively contribute to your site’s scalability as well.

### Personalized Caching

The platform also offers an out-of-the-box solution to personalize caching. With personalized caching the cache key is amended by the currently active price books and the applicable promotions.

Let’s look at what that means for two shoppers looking at the same page (as in, the same URL). In this example, shopper A has price book X registered, and shopper B has price book Y registered. The same product (no change in URL) is cached twice. All shoppers with price book X registered are subsequently served with the respective cache entry, as are shoppers with price book Y. Depending on the number of price books and promotions, this scenario can lead to a large increase in the number of cache entries, regardless of the price of the product being different. Thus, consider using personalized caching only when necessary.

### Implementation

Two APIs can control the caching behavior of the response.

- the `dw.system.Response#setExpires(milliseconds)` script API
- the `<iscache>` tag

Note: SFRA provides decorators that you can use instead of 1. The decorators apply to preconfigured caching times.
Historically, the ISML tag was the only option, and the script API was introduced later. As a best practice, we strongly recommend discontinuing usage of the ISML tag, and leveraging the script API instead. Both approaches control the caching of the entire response, not individual templates. Although both APIs have the same effect, using the script API is recommended for a number of reasons.

By using the script API, you define the caching behavior in the controller and avoid some of the challenges of the ISML tag. For example, using the `<iscache>` tag can be confusing, as it might suggest you're just caching a template. In addition, it’s often difficult to understand which template defines the caching behavior of a response, because they can be nested, and each template can have its own `<iscache>` tag. (If so, the lowest defined cache time is applied.) Finally, a template might be used in different contexts that require different cache policies, making the implementation even more complex.

### Examples

```js
// SFRA controller cached via decorator
server.get("Show", cache.applyDefaultCache, function (req, res, next) {});

// Set cache time directly at the response (doesn’t rely on SFRA)
response.setExpires(new Date().getTime() + durationInMinutes * 60 * 1000);

// Apply personalized caching
response.setVaryBy("price_promotion");

// Cache times don’t have to be constants. Let's get creative!
// Apply layered caching times by product availability levels
var availabilityModel = product.getAvailabilityModel();
if (availabilityModel.isOrderable(50)) {
  // Cache 5 days when >= 50 orderable
  response.setExpires(new Date().getTime() + 120 * 60 * 60 * 1000);
} else if (availabilityModel.isOrderable(20)) {
  // Cache 1 day when >= 20 orderable
  response.setExpires(new Date().getTime() + 24 * 60 * 60 * 1000);
} else if (availabilityModel.isOrderable(5)) {
  // Cache 4 hours when >= 5 orderable
  response.setExpires(new Date().getTime() + 4 * 60 * 60 * 1000);
} else {
  // Cache 30 minutes when < 5 orderable
  response.setExpires(new Date().getTime() + 30 * 60 * 1000);
}
```

### Application Level Caching

Some endpoints (entire pages or remote includes) must serve dynamic information, such as consumer data or cart information, so page caching can't be applied. However, expensive calculations can still happen on those pages, and the results can be cached to reduce the overall processing time of the dynamic request.

A prominent example is configuration as code. This is typically (but not exclusively) used by companies with many brands in multiple countries. The configuration is stored in JSON files and can be extended by brand- and country-specific overrides. While reading a JSON file and merging JavaScript objects isn't an expensive operation, the frequency of this operation makes it consume a significant amount of processing time. By caching the configuration for each brand and country combination, avoid this recalculation across every request (and every remote include), and the site benefits from faster page rendering times.

Let’s consider the various options for caching information at the application layer.

### Request Caching

To save information within a single request, store data inside a module. In case the data is required again, this approach keeps its state. You save the data in the request with the additional logic attached. Request caching is useful, for example, if you want to save the shopper’s selected store but don’t want developers to directly interact with that data. The module saves the store ID internally and only exposes methods to return the store object, or to perform actions with the store, while hiding the implementation specifics (and keeping them in a single, central place).
If your use case is to store just a small piece of data, use request.custom to save and read the information.

### Custom Objects

Custom objects are very versatile. Import and export custom objects. You can both write to and read them, and custom objects are persistent and consistent across all application servers. Common use cases for using custom objects include a scenario where the cached data must not get lost, or when a custom object acts as intermediate storage for data that’s processed later. The downside of custom objects is that they're stored in the database, and therefore, all architectural tiers are traversed.

### Custom Caches

Custom caches enable developers to store a limited amount of information. Because they aren’t shared across application servers, the data isn’t synchronized. Use custom caches to save intermediate results of expensive operations that must happen within dynamic requests, or operations that happen frequently.

### File Caches

File caches are great for build-time optimizations. Use file caches, for example:

- To generate templates (in scenarios where template languages other than ISML are used)
- To optimize development code
- To create environment-specific configurations

### Session

If you want to cache smaller pieces of information for a shopper, consider using a session. Sessions are easy to implement, and you can use the data for building dynamic customer groups.
Use the following options to store data in a session.

- Use `session.custom` when data is used for building dynamic customer groups. When data is stored in `session.custom`, the platform updates the dynamic customer groups. Use this option sparingly, as it can consume many system resources.
- Use `session.privacy` when data isn’t used for building dynamic customer groups. This option doesn’t trigger customer group updates, and consumes fewer resources. The data is cleared out after logout.

### Static Content Caching

Static content caching is a slightly different form of caching. Static content refers to images, style sheets, and client-side JavaScript — any files that are downloaded and consumed by the browser. Those files are delivered by the origin server and then cached within the eCDN.
Static files are either managed directly in the environment or included in the code. For the latter, they are often generated during the build process. After those sources are on the server, they are served as-is and can't contain any dynamically calculated information.

## Replications and Cache Clears

All of the caches covered so far can be cleared or flushed. This point is important to understand, because you want to make sure that data isn’t cached longer than needed. But also, frequent cache clears negatively impact performance and scalability.

|                      | Caching Time         | Configuration                                        | How the cache is cleared                                                                           |
| -------------------- | -------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Page Cache           | Controlled via code. | Enable in Business Manager. Always on in production. | Via Business Manager, or implicitly when replication occurs.                                       |
| ---                  | ---                  | ---                                                  | ---                                                                                                |
| Static Content Cache | Fix (on production)  | Enable in Business Manager. Always on in production. | Via Business Manager, or implicitly when replication occurs.                                       |
| Custom Objects       | Controlled via code. | Control via metadata.                                | Custom objects exist until explicitly deleted, or based on retention settings in Business Manager. |
| Custom Caches        | Controlled via code. | Enable in Business Manager.                          | Via Business Manager, or implicitly when replication occurs.                                       |

## Performance Insights and Optimization

Shoppers typically spend most of their time on certain key pages. Those pages translate into controller or pipeline endpoints, which you should monitor closely.

### Key Pages

- Homepage: `Default-Start` and `Home-Show`
- Product Listing Pages (Search & Category Navigation): `Search-Show`
- Product Detail Pages: `Product-Show`
- Content Pages: `Page-Show`

Make sure that all of these pages have a high cache hit rate and fast response times. Quantifying _high_ and _fast_ is challenging, as many factors play into these numbers, and numbers don’t necessarily mean a positive shopper experience.

### Example Scenario

Consider this scenario. An implementation generates links to variants on listing pages while the product detail page (PDP) always redirects to the primary product as a best practice. This solution likely leads to fast PDP metrics, because each call is effectively two requests: One to a variant that responds with a fast redirect, and the other is the PDP. As a result, the reported PDP average response time is skewed and appears twice as fast as it actually is (assuming the redirect response time is close to zero). The actual shopper experience, however, won’t be optimal, because not only is the PDP slow, there’s an additional redirect.

A wide variety of situations can impact the average response times, so it’s important to look holistically at performance rather than focusing on a single number as an indicator.

Use _percentage of processing time_ as a good indicator, because it offers the best potential for optimization. Either improve page caching or optimize processing times by using other forms of caching or code optimizations.

### Common Pitfalls

A common pitfall is missing cache directives, like ones that have been either removed from the code by developers, or not added when new endpoints were created. Detect missed cache directives by using the Reports & Dashboards tool to identify endpoints that have a 100 percent cache miss rate.

### Note

As a best practice, review all endpoints a few days after site launch to make sure that endpoints are being cached as expected.

### Key Includes

- Product Tile: `Product-Tile` (can vary)
- Content Snippets: `Page-Include`
- Content Slots: `__Slot-Render`

All three key includes should have a very high cache hit rate and fast response times.
Ideally, product search hit tiles have at least a 99 percent cache hit rate and a response time of <=1 ms. This time might sound very high at first, but in practice, it’s quite achievable due to the high request amount to product tiles. A drop of only a few percentage points leads to slow search result pages and reduced scalability.

### Common Problems

The issue of missing cache directives applies to key pages just as it does for key includes. Use the Reports & Dashboards tool to identify endpoints that have a 100 percent cache miss rate.

### Page Designer

When `PageMgr.renderPage()` renders a Page Designer page, the rendering process uses two nested remote includes.

- The first-level remote include is the system controller `__SYSTEM__Page-Include`. This remote include determines the visibility fingerprint of the page and its components based on schedules, customer groups, or other visibility settings. This remote include passes the visibility fingerprint to the second-level remote include.
- The second-level remote is the system controller `__SYSTEM__Page-Render`. This remote include invokes the `render` function to render the page.

Based on different visibility settings, each variation of the page is cached separately. For more information, see [Page Designer Caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html).

### Content Slots

Content slots are served within remote includes to allow independent cache control. Developers can use cache directives in the rendering template, which controls the caching for the slot content.
The system automatically recalculates the slot configuration to display, regardless of the cache settings in the rendering template, through an additional dynamic include.

### Tooling

To optimize server-side performance, and increase the scalability and predictability of the system, start by referring to the Technical tab in the Reports & Dashboards tool. Focus on the top contributors of your overall processing time, and sort by that column (as shown in the following screen capture).

![Tooling](https://developer.salesforce.com/docs/media/solutions/caching1.png)

Now, you know the endpoint that contributes most to overall processing and offers the biggest potential for improvement. The last three columns indicate how many requests have been read from cache, calculated and stored to cache, and always dynamically calculated. If the last column shows 100 percent, the endpoint is uncached. Check and fix this issue first, because perhaps some endpoints haven’t been cached that should be.

Next, validate the pages that are cached. If the last column is not zero percent, some requests aren’t being cached and can indicate errors or code issues. A page that’s cached has zero percent in this column, and only has either cache hits or misses getting stored to cache.

After this, review the cache hit rates for areas of improvement. Consider how the page cache works and possible optimizations.

Finally, after you’ve investigated page caching optimizations, focus on the (now updated) processing times again. Review the code for optimizations. You might want to leverage the detailed report (accessed by clicking an endpoint).

Besides the Reports & Dashboards tool, the Code Profiler is another tool that provides great insights (after optimizing page caching).
To use the Code Profiler:

1. Select **Extended Script Development Mode**.
2. Filter by **Category equals REQUEST**.
3. Sort by **Elapsed time > Sum**.

![Code Profiler](https://developer.salesforce.com/docs/media/solutions/caching2.png)

This list shows you the most calculation heavy requests at the top. Click to see the functions that contributed to the runtime. With production data, you usually find a short list of endpoints that contribute to a large part of the processing time. To identify which scripts and methods are contributing most to the total runtime, sort by **Elapsed Time Own > Sum**.
Now, start at the top and investigate making those methods more efficient.

![Investigate](https://developer.salesforce.com/docs/media/solutions/caching3.png)

<!-- document id=3437489d6a36a0f681d0a617a56c64b02c5f8f2e969cd89d5776463dbcd605fe url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/campaigns.md -->

Campaigns

# Campaigns

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/campaigns/campaigns-oas-v1-public.yaml)

## API Overview

Campaigns enable experiences based on an optional schedule and qualifying criteria.

When an experience is assigned to a campaign, the schedule and qualifiers can only refine the containing campaign. A campaign is defined in the context of a site and is not shared among sites. A campaign can be enabled or disabled. A disabled campaign is inactive and not available to consumers. Enabled promotions contained within a disabled campaign are also inactive.

### Qualifiers

Qualifiers are requirements that must be met to enable a campaign's experience.

*   Schedule: A start and end time and date. This can be open ended at one or both ends.
*   Coupon: A coupon
*   Customer Group: Membership in a customer group.
*   Source Code: A code attached to the site URL that identifies where the customer was redirected from.

For more details, see [Qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_qualifiers.htm&type=5) on the B2C Commerce documentation.

### Experiences

Promotion: A monetary discount or bonus item. Promotions can have additional criteria such as quantity or number of products gating the discount.

### Authentication & Authorization

The client requesting the campaign information must have access to the Campaign resource. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account Manager to log in.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Use Cases

#### Flash Sales

Use single date promotions when you want to run a campaign for a short period of time.

For example, a '20% Off Black Friday' campaign enables a 20% off promotion for registered customers on Black Friday.

#### No Date or Time Restrictions

You can also configure promotions with no time or date restrictions. This is useful when running coupon-coded promotions, or qualifier-based promotions that require certain criteria to be met.

For example, a 'Free Shipping' campaign enables a free shipping promotion when the coupon code "freeship" is added to the cart.

#### Redirections

Use redirection promotions to trigger a promotion when a customer arrives at the storefront from a specific location. You may want to use this when partnering with other resources or running external advertisements.

For example, all users directed from Facebook receive a free hat with purchase.

For more information, see [Use Source Codes as Qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_using_source_codesas_qualifiers.htm&type=5) in the B2C Commerce documentation.

### Related APIs

*   [Promotions (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions?meta=Summary) — Manage promotions assigned to campaigns.
*   [Assignments](https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments?meta=Summary) — Assign promotions and discounts to campaigns.
*   [Coupons](https://developer.salesforce.com/docs/commerce/commerce-api/references/coupons?meta=Summary) — Manage coupons used as campaign qualifiers.

**Version:** 1.1.1

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/campaigns/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.promotions: promotions READONLY
    *   Scope sfcc.promotions.rw: promotions read/write
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### POST Search for campaigns using a search request object that allows filtering on various attributes.

`POST /organizations/{organizationId}/campaigns`

Operation ID: `campaignsSearch`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

### Supported Query Attributes

The query attribute specifies a complex query that you can use to narrow down the search. A subset of these attributes can optionally be used to sort the returned results.

| Attribute | Type | Sortable |
| --- | --- | --- |
| campaignId | String | yes |
| description | String | yes |
| enabled | Boolean | yes |
| couponId | String | no |
| customerGroup | String | no |
| sourceCode | String | no |
| startDate | Date | no |
| endDate | Date | no |
| lastModified | Date | no |

These fields can only be used in queries as conjunctions (using `AND`). If the field is used in a disjunction (`OR`), an exception is thrown.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SearchRequest`.

#### Responses

*   **200** Campaign search successfully executed.
    
    Media type: `application/json`. Schema: `CampaignSearchResult`.
    
    _Example: CampaignSearchResult_
    
    ```
    {
      "limit": 2,
      "hits": [
        {
          "campaignId": "mens-clothing-dress-shirts",
          "creationDate": "2019-11-06T21:12:35.000Z",
          "customerGroups": [
            "Everyone"
          ],
          "description": "This a campaign for the Mens Dress Shirts Category offering a specific banner as well as a 20% off dress shirts promotion, and a custom sort rule of product name ascending",
          "enabled": false,
          "lastModified": "2019-11-06T21:12:35.000Z"
        },
        {
          "campaignId": "mens-clothing-suits",
          "creationDate": "2019-11-06T21:12:35.000Z",
          "customerGroups": [
            "Everyone"
          ],
          "description": "This is a campaign that displays a landing banner, with a 25% discount on all suits and default sorting rule of top selling suits.",
          "enabled": false,
          "lastModified": "2019-11-06T21:12:35.000Z"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id",
            "description"
          ],
          "searchPhrase": "campaign"
        }
      },
      "offset": 1,
      "total": 4
    }
    ```
    
*   **400** Returned when the query is ill-formed.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidOperation_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-operation",
      "detail": "Failed to execute search query: wrong syntax.",
      "title": "Incorrect Syntax"
    }
    ```
    

### GET Get campaign information.

`GET /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `getCampaign`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Campaign information successfully retrieved.
    
    Media type: `application/json`. Schema: `Campaign`.
    
    _Example: GetCampaign_
    
    ```
    {
      "campaignId": "NewYearCampaign",
      "coupons": [
        "20%offOrdersAbove100",
        "10%offties"
      ],
      "creationDate": "2019-10-03T19:36:56.000Z",
      "customerGroups": [
        "Registered"
      ],
      "description": "Campaign for the New Year",
      "enabled": true,
      "endDate": "2020-07-31T23:09:08.000Z",
      "lastModified": "2019-10-10T14:27:00.867Z",
      "sourceCodeGroups": [
        "affiliate-email",
        "gaming-email"
      ],
      "startDate": "2019-04-01T11:30:15.000Z"
    }
    ```
    
*   **404** Returned when there is no campaign found with the given ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: getCampaign404_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/campaign-not-found",
      "detail": "No campaign with ID 'SpecialCampaign' in site 'SiteGenesis' could be found.",
      "title": "Not Found Error"
    }
    ```
    

### PUT Create a campaign using the information provided.

`PUT /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `createCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `Campaign`.

_Example: PutCampaign_

```
{
  "campaignId": "NewWinterCampaign",
  "coupons": [
    "WinterSpecial"
  ],
  "creationDate": "2019-10-03T19:36:56.000Z",
  "customerGroups": [
    "Registered"
  ],
  "description": "Campaign for winter specials",
  "enabled": true,
  "endDate": "2020-07-31T23:09:08.000Z",
  "lastModified": "2019-10-10T14:52:47.356Z",
  "startDate": "2019-04-01T11:30:15.000Z"
}
```

#### Responses

*   **200** Campaign successfully created.
    
    Media type: `application/json`. Schema: `Campaign`.
    
    _Example GetCampaign: same as PUT /organizations/{organizationId}/campaigns/{campaignId} request._
    
*   **400** Returned when the ID in the request does not match the ID in the document.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the request body ('CampaignXYZ') doesn't match the ID in the URL ('NewWinterCampaign')",
      "title": "Duplicate Error"
    }
    ```
    

### DELETE Deletes a campaign with a specified ID.

`DELETE /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `deleteCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Campaign deleted successfully.

### PATCH Update a campaign with the specified information.

`PATCH /organizations/{organizationId}/campaigns/{campaignId}`

Operation ID: `updateCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `Campaign`.

_Example: PatchCampaign_

```
{
  "description": "Thanksgiving campaign enabling special promotions",
  "enabled": true,
  "coupons": [
    "thanksgiving",
    "special"
  ]
}
```

#### Responses

*   **200** Campaign successfully updated.
    
    Media type: `application/json`. Schema: `Campaign`.
    
    _Example PutCampaign: same as PUT /organizations/{organizationId}/campaigns/{campaignId} request._
    
*   **400** Returned when a campaign with the specified campaign ID already exists in the site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: updateCampaign400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/campaign-duplicate",
      "detail": "The campaign couldn't be created because of duplicate ID 'CampaignXYZ'.",
      "title": "Duplicate Error"
    }
    ```
    
*   **404** Returned when there is no campaign found with the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example getCampaign404: same as GET /organizations/{organizationId}/campaigns/{campaignId} 404 response._
    

### GET List promotions assigned to a campaign.

`GET /organizations/{organizationId}/campaigns/{campaignId}/promotions`

Operation ID: `getCampaignPromotionAssignments`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Promotion campaign assignments successfully retrieved, ordered by rank ascending.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignmentResult`.
    
    _Example: GetCampaignPromotionAssignments_
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "campaign": {
            "campaignId": "NewYearCampaign",
            "description": "Campaign for the New Year",
            "enabled": true
          },
          "campaignId": "NewYearCampaign",
          "coupons": [
            "10offsku"
          ],
          "couponsBased": true,
          "customerGroups": [
            "Registered"
          ],
          "customerGroupsBased": true,
          "enabled": true,
          "promotionId": "10offsku",
          "rank": 1,
          "requiredQualifier": "all",
          "schedule": {
            "startDate": "2026-01-01T00:00:00.000Z",
            "endDate": "2026-01-31T23:59:59.000Z",
            "recurrence": {
              "dayOfWeek": [
                "monday",
                "tuesday"
              ],
              "timeOfDay": {
                "timeFrom": "09:00:00",
                "timeTo": "17:00:00"
              }
            }
          },
          "sourceCodeBased": true,
          "sourceCodeGroups": [
            "affiliate-email"
          ]
        },
        {
          "campaign": {
            "campaignId": "NewYearCampaign",
            "description": "Campaign for the New Year",
            "enabled": true
          },
          "campaignId": "NewYearCampaign",
          "coupons": [],
          "couponsBased": false,
          "customerGroups": [],
          "customerGroupsBased": false,
          "enabled": true,
          "promotionId": "freeshipping50",
          "rank": 2,
          "requiredQualifier": "any",
          "schedule": {
            "startDate": "2026-01-01T00:00:00.000Z",
            "endDate": "2026-01-31T23:59:59.000Z",
            "recurrence": {
              "dayOfWeek": [
                "saturday",
                "sunday"
              ],
              "timeOfDay": {
                "timeFrom": "00:00:00",
                "timeTo": "23:59:59"
              }
            }
          },
          "sourceCodeBased": false,
          "sourceCodeGroups": []
        }
      ],
      "total": 2
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse`.
    
    _Example: CampaignNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/campaign-not-found",
      "detail": "No campaign with ID 'NewYearCampaign' was found for site 'RefArch'.",
      "title": "Campaign Not Found"
    }
    ```
    

### GET Get a promotion campaign assignment.

`GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `getCampaignPromotionAssignment`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Promotion campaign assignment successfully retrieved.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example: GetCampaignPromotionAssignment_
    
    ```
    {
      "campaign": {
        "campaignId": "NewYearCampaign",
        "description": "Campaign for the New Year",
        "enabled": true,
        "startDate": "2026-01-01T00:00:00.000Z",
        "endDate": "2026-01-31T23:59:59.000Z"
      },
      "campaignId": "NewYearCampaign",
      "coupons": [
        "10offsku"
      ],
      "couponsBased": true,
      "customerGroups": [
        "Registered"
      ],
      "customerGroupsBased": true,
      "enabled": true,
      "promotionId": "10offsku",
      "rank": 1,
      "requiredQualifier": "any",
      "schedule": {
        "startDate": "2026-01-01T00:00:00.000Z",
        "endDate": "2026-01-31T23:59:59.000Z",
        "recurrence": {
          "dayOfWeek": [
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday"
          ],
          "timeOfDay": {
            "timeFrom": "09:00:00",
            "timeTo": "17:00:00"
          }
        }
      },
      "sourceCodeBased": true,
      "sourceCodeGroups": [
        "affiliate-email"
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion campaign assignment was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example: PromotionCampaignAssignmentNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/promotion-campaign-assignment-not-found",
      "detail": "No assignment of promotion '10offsku' to campaign 'NewYearCampaign' was found for site 'RefArch'.",
      "title": "Promotion Campaign Assignment Not Found"
    }
    ```
    

### PUT Create or replace a promotion campaign assignment.

`PUT /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `assignPromotionToCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PromotionCampaignAssignmentRequest`.

_Example: AssignPromotionToCampaign_

```
{
  "campaignId": "NewYearCampaign",
  "promotionId": "10offsku",
  "rank": 10,
  "coupons": [
    "10offsku"
  ],
  "couponsBased": true,
  "customerGroups": [
    "Registered"
  ],
  "customerGroupsBased": true,
  "sourceCodeGroups": [
    "affiliate-email"
  ],
  "sourceCodeBased": true,
  "requiredQualifier": "all",
  "schedule": {
    "startDate": "2026-01-01T00:00:00.000Z",
    "endDate": "2026-01-31T23:59:59.000Z",
    "recurrence": {
      "dayOfWeek": [
        "monday",
        "tuesday",
        "wednesday",
        "thursday",
        "friday"
      ],
      "timeOfDay": {
        "timeFrom": "09:00:00",
        "timeTo": "17:00:00"
      }
    }
  }
}
```

#### Responses

*   **200** Promotion campaign assignment successfully replaced.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example AssignPromotionToCampaign: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 200 response._
    
*   **201** Promotion campaign assignment successfully created.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example AssignPromotionToCampaign: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 200 response._
    
*   **400** Bad Request. The request body is ill-formed, the composite key does not match the path, or a business rule rejected the request.
    
    Media type: `application/problem+json`. Schema: `AssignmentIdMismatchErrorResponse | AssignmentBusinessRuleViolationErrorResponse`.
    
    One of: `AssignmentIdMismatchErrorResponse`, `AssignmentBusinessRuleViolationErrorResponse`.
    
    _Example: AssignmentIdMismatchErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/assignment-id-mismatch",
      "detail": "The campaignId or promotionId in the request body does not match the IDs in the request path.",
      "title": "Assignment Id Mismatch"
    }
    ```
    
    _Example: AssignmentBusinessRuleViolationErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/assignment-business-rule-violation",
      "detail": "The promotion campaign assignment could not be saved because a business rule was violated.",
      "title": "Assignment Business Rule Violation"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example: PromotionNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/promotion-not-found",
      "detail": "No promotion with ID '10offsku' was found for site 'RefArch'.",
      "title": "Promotion Not Found"
    }
    ```
    

### DELETE Unassign a promotion from a campaign.

`DELETE /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `unassignPromotionFromCampaign`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Promotion campaign assignment successfully deleted.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion campaign assignment was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example PromotionCampaignAssignmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 404 response._
    

### PATCH Update a promotion campaign assignment.

`PATCH /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId}`

Operation ID: `updateCampaignPromotionAssignment`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `campaignId` (path, object, required) The ID of the campaign.  
    Minimum length: 1.
*   `promotionId` (path, string, required) The ID of the promotion assigned to the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PromotionCampaignAssignmentUpdate`.

_Example: UpdateCampaignPromotionAssignment_

```
{
  "rank": 20,
  "coupons": [
    "10offsku",
    "15offsku"
  ]
}
```

#### Responses

*   **200** Promotion campaign assignment successfully updated.
    
    Media type: `application/json`. Schema: `PromotionCampaignAssignment`.
    
    _Example UpdateCampaignPromotionAssignment: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 200 response._
    
*   **400** Bad Request. The request body is ill-formed, the composite key does not match the path, or a business rule rejected the request.
    
    Media type: `application/problem+json`. Schema: `AssignmentIdMismatchErrorResponse | AssignmentBusinessRuleViolationErrorResponse`.
    
    One of: `AssignmentIdMismatchErrorResponse`, `AssignmentBusinessRuleViolationErrorResponse`.
    
    _Example AssignmentIdMismatchErrorResponseExample: same as PUT /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 400 response._
    
    _Example AssignmentBusinessRuleViolationErrorResponseExample: same as PUT /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The campaign or the promotion campaign assignment was not found for the requested site.
    
    Media type: `application/problem+json`. Schema: `CampaignNotFoundErrorResponse | PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    One of: `CampaignNotFoundErrorResponse`, `PromotionCampaignAssignmentNotFoundErrorResponse`.
    
    _Example CampaignNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions 404 response._
    
    _Example PromotionCampaignAssignmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/campaigns/{campaignId}/promotions/{promotionId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### CampaignSearchResult

Document representing a campaign search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Campaign_, required) The sorted array of campaign search hits. Can be empty.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CampaignId

The ID of the campaign.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.

### Campaign

Document representing a campaign.

*   `campaignId` (_CampaignId_)
*   `coupons` (_array of CouponId_) The array of assigned coupon IDs, not sorted.
    
    _Example_
    
    ```
    [
      "20%offOrder",
      "10%offWelcomeNewUser"
    ]
    ```
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `customerGroups` (_array of CustomerGroupId_) The array of assigned customer groups, not sorted.
    
    _Example_
    
    ```
    [
      "BigShoppers",
      "NorthAmericanShoppers"
    ]
    ```
    
*   `description` (_string_) The description of the campaign.  
    Maximum length: 4000. Example: `Campaign for the New Year`.
*   `enabled` (_boolean_) The enabled flag for campaign.  
    Example: `true`.
*   `endDate` (_string (date-time)_) The date the scenario ends.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `sourceCodeGroups` (_array of SourceCodeGroupId_) The array of assigned source code groups, not sorted.
    
    _Example_
    
    ```
    [
      "affiliate-email",
      "gaming-email"
    ]
    ```
    
*   `startDate` (_string (date-time)_) The date the scenario begins.  
    Example: `2019-10-03T19:36:56.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PromotionCampaignAssignmentResult

Result document representing a list of promotion campaign assignments assigned to a campaign.

Includes all fields of `ResultBase`.

*   `data` (_array of PromotionCampaignAssignment_, required) The array of promotion campaign assignments, ordered by rank ascending. Can be empty.

### CampaignNotFoundErrorResponse

Returned when no campaign with the given ID exists for the requested site.

Includes all fields of `ErrorResponse`.

*   `campaignId` (_CampaignId_)
*   `siteId` (_SiteId_)

### PromotionCampaignAssignment

Document representing a promotion campaign assignment.

*   `campaign` (_object_, required) The campaign.
    
    Includes all fields of `Campaign`.
    
*   `campaignId` (_string_, required) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.
*   `coupons` (_array of CouponId_, required) The sorted array of assigned coupon IDs.
*   `couponsBased` (_CouponsBased_, required)
*   `customerGroups` (_array of CustomerGroupId_, required) The sorted array of assigned customer groups.
*   `customerGroupsBased` (_CustomerGroupsBased_, required)
*   `enabled` (_boolean_, required, read-only) Read-only. True if the assigned promotion is enabled. Derived from the promotion's enabled state; cannot be set on the assignment. Use the Promotions API to change it.  
    Example: `true`.
*   `promotionId` (_string_, required) The ID of the promotion. Use the Promotions API to fetch the full promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `rank` (_integer (int32)_, required) The rank of promotion campaign assignment.  
    Example: `1`.
*   `requiredQualifier` (_RequiredQualifier_, required)
*   `schedule` (_object_, required) The schedule of the assignment resource.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeBased` (_SourceCodeBased_, required)
*   `sourceCodeGroups` (_array of SourceCodeGroupId_, required) The sorted array of assigned source code groups.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PromotionCampaignAssignmentNotFoundErrorResponse

Returned when the promotion is not assigned to the campaign for the requested site.

Includes all fields of `ErrorResponse`.

*   `campaignId` (_CampaignId_)
*   `promotionId` (_string_) The ID of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `siteId` (_SiteId_)

### PromotionCampaignAssignmentRequest

Request body for creating or replacing a promotion campaign assignment (PUT). Omits the read-only nested campaign and promotion courtesy copies, which are response-only.

*   `campaignId` (_string_) The ID of the campaign. If supplied, must equal the campaignId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.
*   `coupons` (_array of CouponId_) The sorted array of assigned coupon IDs.
*   `couponsBased` (_CouponsBased_)
*   `customerGroups` (_array of CustomerGroupId_) The sorted array of assigned customer groups.
*   `customerGroupsBased` (_CustomerGroupsBased_)
*   `promotionId` (_string_) The ID of the promotion. If supplied, must equal the promotionId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `rank` (_integer (int32)_) The rank of the promotion campaign assignment. Must be null or a multiple of 10 from 0 to 100 (0, 10, 20, ..., 100).  
    Minimum: 0. Maximum: 100. Multiple of: 10. Example: `10`.
*   `requiredQualifier` (_RequiredQualifier_)
*   `schedule` (_object_, required) The schedule of the assignment resource.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeBased` (_SourceCodeBased_)
*   `sourceCodeGroups` (_array of SourceCodeGroupId_) The sorted array of assigned source code groups.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### AssignmentIdMismatchErrorResponse

Returned when the composite key in the request body does not match the campaignId or promotionId path parameters.

Includes all fields of `ErrorResponse`.

### AssignmentBusinessRuleViolationErrorResponse

Returned when a backend business rule rejects the assignment (for example, an invalid schedule or qualifier combination).

Includes all fields of `ErrorResponse`.

### PromotionNotFoundErrorResponse

Returned when the promotion referenced by the request does not exist for the requested site.

Includes all fields of `ErrorResponse`.

*   `promotionId` (_string_) The ID of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `siteId` (_SiteId_)

### PromotionCampaignAssignmentUpdate

Request body for partially updating a promotion campaign assignment (PATCH). Same properties as the create request, but all properties are optional. Omits the read-only nested campaign and promotion courtesy copies.

*   `campaignId` (_string_) The ID of the campaign. If supplied, must equal the campaignId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.
*   `coupons` (_array of CouponId_) The sorted array of assigned coupon IDs.
*   `couponsBased` (_CouponsBased_)
*   `customerGroups` (_array of CustomerGroupId_) The sorted array of assigned customer groups.
*   `customerGroupsBased` (_CustomerGroupsBased_)
*   `promotionId` (_string_) The ID of the promotion. If supplied, must equal the promotionId path parameter.  
    Minimum length: 1. Maximum length: 256. Example: `10offsku`.
*   `rank` (_integer (int32)_) The rank of the promotion campaign assignment. Must be null or a multiple of 10 from 0 to 100 (0, 10, 20, ..., 100).  
    Minimum: 0. Maximum: 100. Multiple of: 10. Example: `10`.
*   `requiredQualifier` (_RequiredQualifier_)
*   `schedule` (_object_, nullable) The schedule of the assignment resource. Send schedule null to clear the assignment-level schedule.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeBased` (_SourceCodeBased_)
*   `sourceCodeGroups` (_array of SourceCodeGroupId_) The sorted array of assigned source code groups.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### CouponId

The ID of the coupon.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `20%offOrder`.

### CustomerGroupId

The ID of the customer group.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `Registered`.

### SourceCodeGroupId

The ID of source code group.

Type: `string`.

Minimum length: 1. Maximum length: 28. Example: `TV-Email`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CouponsBased

Whether the coupons qualifier participates in the assignment's qualification rule. When true, the assigned coupons gate the promotion (combined with campaign-level coupons). When omitted, defaults to true if a non-empty coupons array is supplied, otherwise false.

Type: `boolean`.

Example: `false`.

### CustomerGroupsBased

Whether the customer-groups qualifier participates in the assignment's qualification rule. When true, the assigned customer groups gate the promotion (combined with campaign-level customer groups). When omitted, defaults to true if a non-empty customerGroups array is supplied, otherwise false.

Type: `boolean`.

Example: `false`.

### RequiredQualifier

Controls how the active qualifier types (coupons, customer groups, source-code groups) combine. 'all' requires every active qualifier type to be satisfied (AND); 'any' requires at least one (OR). Defaults to 'any' when omitted.

Type: `string`.

Allowed values: `all`, `any`. Default: `any`. Example: `any`.

### Schedule

Document representing a time schedule. Defines an optional validity window (startDate/endDate) and an optional recurrence. Omitting a bound leaves that side of the window open (unbounded).

*   `startDate` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-31T23:59:59.000Z`.
*   `recurrence` (_object_) The recurrence of the schedule by day of week and time of day. Not all schedules support a recurrence.
    
    Includes all fields of `Recurrence`.
    

### SourceCodeBased

Whether the source-code-groups qualifier participates in the assignment's qualification rule. When true, the assigned source-code groups gate the promotion (combined with campaign-level source-code groups). When omitted, defaults to true if a non-empty sourceCodeGroups array is supplied, otherwise false.

Type: `boolean`.

Example: `false`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Recurrence

Document representing a schedule recurrence.

*   `dayOfWeek` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Example: `monday`.
*   `timeOfDay` (_object_) The time of the day for recurrence.
    
    Includes all fields of `TimeOfDay`.
    

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### TimeOfDay

Document representing a time schedule within a single day.

*   `timeFrom` (_string_) The time to start from. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `09:00:00`.
*   `timeTo` (_string_) The time to end on. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `17:00:00`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=68eab39feac912619a40527114cc56a22849f18c86e1cf5fa04a00ef3f801171 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-cart.md -->

# Cart

### Overview

The Cart page shows all the items in the cart. Buyers can change the number of items or remove items, calculate the total amount of items in the cart, and add items to the cart to continue shopping.

Each buyer action on this page links to a specific Salesforce Commerce Cart REST API operation. This keeps the cart state in sync between the storefront and the commerce backend.

This flow demonstrates how a headless storefront can render cart experiences, including cart item management, pricing, and checkout actions, using B2B Commerce Cart APIs.

![Cart Overview Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-cart-overview-14-1.png '{"class": "image-lg", "title": "Cart Overview Flow"}')

### B2B Commerce APIs Used in the Flow

| Purpose              | HTTP Method | Endpoint                                                                                                                                                                                    |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Load cart items      | GET         | [`/commerce/webstores/{webstoreId}/carts/current/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartItemCollection)       |
| Update line quantity | PATCH       | [`/commerce/webstores/{webstoreId}/carts/current/cart-items/{cartItemId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=patchCartItem)  |
| Remove line items    | DELETE      | [`/commerce/webstores/{webstoreId}/carts/current/cart-items/{cartItemId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteCartItem) |
| Cart summary         | GET         | [`/commerce/webstores/{webstoreId}/carts/compact-summary`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartBadge)                   |

### Buyer Journey

**Render the Cart Page**

1. Load the active cart.

2. Call the following endpoint to retrieve cart items and cart summary details:

   GET [`/commerce/webstores/{webstoreId}/carts/current/cart-items?includePromotions=true&includeCoupons=true&productFields=*`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartItemCollection)

3. Pass the following query parameters:

   - `includePromotions`=`true`
   - `includeCoupons`=`true`
   - `productFields`=`\*`

4. The `productFields=\*` parameter is required to hydrate product information for each cart line item. Without this parameter, the response includes only product IDs and pricing data.

5. Use the response to render:

   - Cart line items
   - Product names
   - Product SKUs
   - Pricing information
   - Promotions
   - Applied coupons
   - Cart totals

6. Store both the `cartSummary` and cart item collection in client-side state so other storefront surfaces, such as the cart badge and checkout summary, can reuse the data without additional API requests.

**Update Item Quantity**

1. Change the quantity using the line-item quantity selector.

2. Call the following endpoint to update the cart item quantity:

   PATCH [`/commerce/webstores/{webstoreId}/carts/current/cart-items/{cartItemId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=patchCartItem)

   Example request body:

   ```json
   { "quantity": 2 }
   ```

3. After the request succeeds, refresh the cart summary and cart items to ensure totals and line-item data remain synchronized.

**Remove a Cart Item**

1. Select the remove or delete action for a cart line item.

2. Call the following endpoint to remove the item from the cart:

   DELETE [`/commerce/webstores/{webstoreId}/carts/current/cart-items/{cartItemId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteCartItem)

   A successful request returns `204 No Content`.

3. Refresh the cart summary and cart item collection after the item is removed.

4. Re-render the cart page to remove the deleted line item from the UI.

5. Display a confirmation message or toast notification indicating that the item was removed successfully.

**Proceed to Checkout**

1. Select Proceed to Checkout to continue to the checkout flow.

2. No API request is required during this action. The checkout page initializes its required data when the page loads.

### Extend the Flow

<!--
- Add a Clear Cart action by sending:

  POST `/commerce/webstores/{webstoreId}/carts/{cartId}/actions/clear`

  This removes all line items from the active cart in a single operation.
-->

- Add coupon and promotion support using the following APIs:

  - Apply a coupon: POST [`/commerce/webstores/{webstoreId}/carts/current/cart-coupons`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartCouponCollection)
  - Remove a coupon: DELETE [`/commerce/webstores/{webstoreId}/carts/current/cart-coupons/{cartCouponId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteCartCoupon)

  These APIs enable buyers to apply and manage promotional discounts directly from the cart experience.

## See Also

- [_B2B Commerce Developer Guide_: Cart and Checkout Features](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-cart-checkout.html)
- [_B2B Commerce Developer Guide_: B2B Commerce Cart APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-cart-apis.html)
- [_B2B Commerce Developer Guide_: B2B Commerce Checkout APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-checkout-apis.html)

<!-- document id=4888380619c0848a72d7523ac266fef94e07cafa08bad95a5a293a4d8fb1f9bb url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-cart-checkout.md -->

# Cart and Checkout Features

Set up guest checkout and handle currency changes. Understand cart and checkout architecture, including the simplified cart cleanup and streamlined place order features.

- [Set Up Guest Checkout for Headless Commerce Stores](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-set-up-guest-checkout-headless.md)
- [Handle Currency Changes for Active Carts](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-cart-currency-change.md)
- [Simplified Cart Cleanup](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-cart-cleanup.md)
- [Streamlined Place Order](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-streamlined-place-order.md)

## B2B Commerce Checkout Process with Commerce APIs

Use these topics when you're building or integrating a B2B checkout experience with Commerce APIs: background calculators, checkout sessions, payments, place order, concurrency, and troubleshooting.

- [Get Started with B2B Commerce Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-get-started.md)
- [How Standard B2B Commerce Checkout Works](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-how-standard-works.md)
- [Implement B2B Commerce Checkout Flow](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-implement-overview.md)
- [Add to Cart](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-add-to-cart.md)
- [Start Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-start-checkout.md)
- [Poll Checkout Status](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-poll-status.md)
- [Update Checkout Information](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-update-information.md)
- [Process Payment](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-process-payment.md)
- [Place Order](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order.md)
- [B2B Commerce Checkout Calculators](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-calculators.md)
- [Calculator Execution by API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-calculators.md#calculator-execution-by-api)
- [Wait for Completion](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-calculators.md#wait-for-completion)
- [Prevent Concurrency Conflicts](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-prevent-concurrency.md)
- [Handle Asynchronous Processing](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-async-processing.md)
- [Concurrent Update Example](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-async-processing.md#concurrent-update-example)
- [Asynchronous Operation Example](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-async-processing.md#asynchronous-operation-example)
- [Avoid Conflicts](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-async-processing.md#avoid-conflicts)
- [Avoid Common Misconfigurations](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-avoid-misconfigurations.md)
- [Troubleshooting Checkout Issues](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-troubleshooting.md)
- [Understanding B2B Checkout Place Order APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order-apis-overview.md)
- [Commerce Webstore Checkout Orders API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-orders-api.md)
- [Commerce Webstore Checkout Place Order Action API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order-action-api.md)
- [API Comparison](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order-api-comparison.md)

<!-- document id=830294daebaf4d7c483b3696c16f4d54a19d880e20b56173e8dd4ef691a29c3a url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/cart-calculate-api.md -->

# Cart Calculate API

The Cart Calculate API (CCA) enables you to customize cart calculation, including calculations that occur during checkout.

The Cart Calculate API provides more control and flexibility with common integrations used in cart and checkout, including tax, inventory, pricing, promotions, and shipping. The Cart Calculate API contains individual calculators for each integration that can be configured and extended based on your business needs.

With the Cart Calculate API, you have granular control over selective integrations. You can easily turn off entire services that aren't needed. For example, if you only sell digital products, you don’t need a shipping service. In addition, you can control integrations at the step level. For example, you only want to show estimated tax in cart, but callout to your tax integration to display calculated tax in checkout. With full control over your integrations, cart and checkout can be optimized to run only the integrations you need, when you need them, optimizing both your storefront and API performance.

The Cart Calculate API consists of three levels of control:

- Orchestrators -- control which calculators are invoked and when they’re invoked.
- Calculators -- control cart calculations, such as those needed for shipping and tax.
- Services -- control specific calculations but aren’t necessarily limited to use cases involving cart calculation. For example, the Pricing service, which is used in cart calculations, also affects your store's PDP (Product Detail Page) pages.

**note:** By default, the Cart Calculate API is enabled for new webstores created in Spring '24 and later releases. See [Enable and Disable the Cart Calculate API for a Webstore](#enable-and-disable-the-cart-calculate-api-for-a-webstore) to toggle the Cart Calculate API on and off. If the Cart Calculate API is off and your store has customizations that trigger cart item changes using SObject, Apex DML, or Delivery Group APIs then you must configure the [Apex Price integration](/docs/commerce/salesforce-commerce/references/comm-apex-reference/pricing-reference.html). If the Cart Calculate API is off and pricing integration isn’t configured, re-pricing won’t occur during checkout.

## Orchestrators and Calculators

With a custom orchestrator, you can control which calculators are invoked and when they’re invoked. If you implement a custom orchestrator, the system invokes your orchestrator whenever cart calculations are needed.

For example, if the buyer adds a product to the cart, the system invokes your custom orchestrator, assuming that your custom orchestrator is both available and registered with the system.

Custom orchestrators extend the `CartExtension.CartCalculate` class and are registered for the `Commerce_Domain_Cart_Calculate` extension point.

### Default Calculator Invocation Order

By default, the system invokes calculators in the following order, but your orchestrator can modify this order or even skip one or more calculators:

| Order | Calculator        | Invoked for Cart | Invoked for Checkout | EPN/Base Class                                                                                    |
| ----- | ----------------- | ---------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| 1     | pricing           | Yes              | Yes                  | <p>`Commerce_Domain_Pricing_CartCalculator`</p><p>`CartExtension.PricingCartCalculator`</p>       |
| 2     | promotions        | Yes              | Yes                  | <p>`Commerce_Domain_Promotions_CartCalculator`</p><p>`CartExtension.PromotionsCartCalculator`</p> |
| 3     | inventory         | Yes              | Yes                  | <p>`Commerce_Domain_Inventory_CartCalculator`</p><p>`CartExtension.InventoryCartCalculator`</p>   |
| 4     | shipping          | No               | Yes                  | <p>`Commerce_Domain_Shipping_CartCalculator`</p><p>`CartExtension.ShippingCartCalculator`</p>     |
| 5     | postShipping      | No               | Yes                  | N/A                                                                                               |
| 5     | shippingPromotion | No               | No                   | N/A                                                                                               |
| 6     | taxes             | No               | Yes                  | <p>`Commerce_Domain_Tax_CartCalculator`</p><p>`CartExtension.TaxCartCalculator`</p>               |

Although calculators are invoked in this order, the shipping, postShipping, and taxes calculators are only invoked during checkout by default. See [Default Calculator Invocation Logic](#default-calculator-invocation-logic) for more information about default behavior. Also see [Custom Invocation Logic Example](#custom-invocation-logic-example) for an example of how to customize the default behavior.

**note:** The postShipping calculator selects the least expensive delivery method and adds a shipping charge for the method. You can't modify this behavior with a custom calculator. Your custom orchestrator, however, can skip this calculator if that's appropriate for your use case.

### Default Calculator Invocation Logic

This following code snippet is taken from the [CartCalculateSample.cls](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/domain/orchestrators/classes/CartCalculateSample.cls) sample orchestrator.

This sample shows the default system invocation logic for calculators. A boolean variable is defined for each calculator, and the corresponding calculator is invoked only if the boolean variable evaluates to `true`.

```java
CartExtension.BuyerActions buyerActions = request.getBuyerActions();
boolean runPricing = buyerActions.isCheckoutStarted() || buyerActions.isCartItemChanged();
boolean runPromotions = buyerActions.isCheckoutStarted() || buyerActions.isCouponChanged() || buyerActions.isCartItemChanged();
boolean runInventory = buyerActions.isCheckoutStarted();
boolean runShipping = buyerActions.isDeliveryGroupChanged();
boolean runPostShipping = buyerActions.isDeliveryGroupChanged() || buyerActions.isDeliveryMethodSelected();
boolean runTaxes = buyerActions.isDeliveryGroupChanged() || buyerActions.isDeliveryMethodSelected();
```

For example, the `runPricing` variable is set to `true` only if the buyer adds, deletes, or updates a cart item, or if the buyer starts checkout.

If the `runPricing` variable evaluates to `true`, the price calculator is invoked. Otherwise, the price calculator is skipped and the orchestrator proceeds to the next calculator.

```java
if (runPricing) {
    prices(calculatorRequest);

    if (hasErrorsInCVO(cvoList, CartExtension.CartValidationOutputTypeEnum.PRICING)) {
        return;
    }
}

if (runPromotions) {
    promotions(calculatorRequest);

    if (hasErrorsInCVO(cvoList, CartExtension.CartValidationOutputTypeEnum.PROMOTIONS)) {
        return;
    }
}

// ...
```

In your custom orchestrator, you can change the invocation logic as needed for your own use cases.

When implementing your custom orchestrator, it's important to understand how buyer actions impact cart and checkout calculations.

By default, shipping and tax calculators are invoked only during checkout, but you can customize this logic if you want.

### Custom Invocation Logic Example

The following code snippet shows an example of custom invocation logic. In this example, the shipping, post shipping, and taxes calculators can be invoked before the buyer starts checkout:

```java
CartExtension.BuyerActions buyerActions = request.getBuyerActions();
boolean runPricing = buyerActions.isCheckoutStarted() || buyerActions.isCartItemChanged();
boolean runPromotions = buyerActions.isCheckoutStarted() || buyerActions.isCouponChanged() || buyerActions.isCartItemChanged();
boolean runInventory = buyerActions.isCheckoutStarted();
boolean runShipping = buyerActions.isDeliveryGroupChanged() || buyerActions.isCartItemChanged() || buyerActions.isCouponChanged();
boolean runPostShipping = buyerActions.isDeliveryGroupChanged() || buyerActions.isDeliveryMethodSelected() || buyerActions.isCartItemChanged() || buyerActions.isCouponChanged();
boolean runTaxes = buyerActions.isDeliveryGroupChanged() || buyerActions.isDeliveryMethodSelected() || buyerActions.isCartItemChanged() || buyerActions.isCouponChanged();
```

In the default invocation logic, the `runShipping` variable is only set to `true` if the buyer changes a delivery group:

```java
boolean runShipping = buyerActions.isDeliveryGroupChanged();
```

This buyer action (changing a delivery group) is allowed only during checkout in B2B and B2C stores. Therefore, by default, the shipping calculator is invoked only during checkout.

In the custom invocation logic, this variable is also set to `true` if the buyer changes an item in the cart or changes a coupon:

```java
boolean runShipping = buyerActions.isDeliveryGroupChanged() || buyerActions.isCartItemChanged() || buyerActions.isCouponChanged();
```

Two of these buyer actions -- `buyerActions.isCartItemChanged()` and `buyerActions.isCouponChanged()` -- can occur before checkout. Therefore, in the custom logic, the shipping calculator is invoked both before and during checkout.

The custom invocation logic makes similar changes to the `runPostShipping` and `runTaxes` variables, enabling them to be invoked before and during checkout.

**note:** This example shows how to modify calculator invocation logic, but the custom logic wouldn't work in production without further customizations. For example, the Connect API resources for carts don’t accept a shipping address as an input. The sample invocation logic, therefore, would only make sense for a “flat rate” shipping scheme, not one based on address. Also, a custom tax calculator would be required, because the default tax calculator logic requires a shipping address.

## Cart and Checkout Calculations

Before checkout, a buyer can perform various actions that affect calculations for the cart:

- Add an item to the cart: sets `buyerAction.isCartItemChanged()` to `true`, which executes the pricing and promotions calculators by default.
- Remove an item from the cart: sets `buyerAction.isCartItemChanged()` to `true`, which executes the pricing and promotions calculators by default.
- Change the quantity of an item in the cart: sets `buyerAction.isCartItemChanged()` to `true`, which executes the pricing and promotions calculators by default.
- Add a coupon to the cart: sets `buyerAction.isCouponChanged()` to `true`, which executes the promotions calculator by default.
- Remove a coupon from the cart: sets `buyerAction.isCouponChanged()` to `true`, which executes the promotions calculator by default.

**note:** See [PromotionCalculatorSample.cls](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/domain/promotion/cart/calculator/classes/PromotionCalculatorSample.cls) to skip promotions when a cart contains a quote.

When the buyer is ready to proceed to checkout, or after the buyer has already started checkout, the buyer can perform other actions that affect calculations for checkout:

- Start checkout: sets `buyerAction.isCheckoutStarted()` to `true`, which executes the pricing, promotions, and inventory calculators by default.
- Update shipping address: sets `buyerAction.isDeliveryGroupChanged()` to `true`, which executes the shipping and taxes calculators by default.
- Update delivery method: sets `buyerAction.isDeliveryMethodSelected()` to `true`, which executes the taxes calculator by default.

## Buyer Actions and Buyer Action Details

To get information about buyer actions, you can use the [BuyerActions](/docs/commerce/salesforce-commerce/references/comm-apex-reference/BuyerActions.html) and [BuyerActionDetails](/docs/commerce/salesforce-commerce/references/comm-apex-reference/BuyerActionDetails.html) objects.

### BuyerActions Object

The `BuyerActions` object provides several boolean methods that indicate which buyer actions have occurred since the previous cart calculation:

- `isCartItemChanged()` -- Returns `true` if the buyer has created, updated, or deleted a cart item; `false` otherwise.
<!-- - `isCheckoutCancelled()` -- Returns `true` if the buyer has cancelled checkout; `false` otherwise. -->
- `isCheckoutStarted()` -- Returns `true` if the buyer has started checkout; `false` otherwise.
- `isCouponChanged()` -- Returns `true` if the buyer has created, updated, or deleted a coupon; `false` otherwise.
- `isDeliveryGroupChanged()` -- Returns `true` if the buyer has created, updated, or deleted a delivery group; `false` otherwise.
- `isDeliveryMethodSelected()` -- Returns `true` if the buyer has selected a delivery method; `false` otherwise.

You obtain a `BuyerActions` object from the `CartExtension.CartCalculateOrchestratorRequest` object passed into your custom orchestrator's `calculate()` method. The `CartExtension.CartCalculateOrchestratorRequest` provides a `getBuyerActions()` method, which returns the `BuyerActions` object for the cart.

### BuyerActionDetails Object

The `BuyerActionDetails` object provides additional details about buyer actions. This object isn't typically used in your custom orchestrator class, but it can be useful in one or more of your custom calculator classes.

The `BuyerActionDetails` object provides the following methods:

- `isCheckoutStarted()` -- Returns `true` if the buyer has started checkout; `false` otherwise. This method behaves the same as the `BuyerActions.isCheckoutStarted()` method, but is accessible within a custom calculator class.
- `getDeliveryGroupChanges()` -- Returns a list of `CartDeliveryGroupChange` objects with detailed info about the changes.
- `getCartItemChanges()` -- Returns a list of `CartItemChange` objects with detailed info about the changes.
- `getCouponChanges()` -- Returns a list of `CouponChange` objects with detailed info about the changes.

You obtain a `BuyerActionDetails` object from the `CartExtension.CartCalculateCalculatorRequest` object passed into your custom calculator's `calculate()` method. The `CartExtension.CartCalculateCalculatorRequest` object provides a `getOptionalBuyerActionDetails()` method, which returns a `CartExtension.OptionalBuyerActionDetails` object.

The `CartExtension.OptionalBuyerActionDetails` object provides a `get()` method, which returns a `BuyerActionDetails` object.

#### CartDeliveryGroupChange Object

The `BuyerActionDetails.getDeliveryGroupChanges()` method returns a List of `CartDeliveryGroupChange` objects.

See [CartDeliveryGroupChange](/docs/commerce/salesforce-commerce/references/comm-apex-reference/CartDeliveryGroupChange.html).

The `CartDeliverGroupChange` object provides one method -- `getChangedDeliveryGroup()` -- which returns an `OptionalCartDeliveryGroup` object. This object is "optional" because it's possible the delivery group was deleted.

#### CartItemChange Object

The `BuyerActionDetails.getCartItemChanges()` method returns a List of `CartItemChange` objects.

See [CartItemChange](/docs/commerce/salesforce-commerce/references/comm-apex-reference/CartItemChange.html).

The `CartItemChange` object provides the following methods:

- `getChangedItem()` -- returns an `OptionalCartItem` object. This object is "optional" because it's possible the cart item was deleted.
- `isAdded()` -- returns `true` if the cart item was added to the cart; otherwise, `false`.
- `isRemoved()` -- returns `true` if the cart item was removed from the cart; otherwise, `false`.
- `isQuantityIncreased()` -- returns `true` if the quantity was increased for the cart item; otherwise, `false`.
- `isQuantityDecreased()` -- returns `true` if the quantity was decreased for the cart item; otherwise, `false`.

#### CouponChange Object

The `BuyerActionDetails.getCouponChanges()` method returns a List of `CouponChange` objects.

See [CouponChange](/docs/commerce/salesforce-commerce/references/comm-apex-reference/CouponChange.html).

The `CouponChange` object provides the following methods:

- `getChangedAdjustmentBasis()` -- returns an `OptionalCartAdjustmentBasis` object. This object is "optional" because it's possible the coupon was deleted.
- `isAdded()` -- returns `true` if the coupon was added to the cart; otherwise, `false`.
- `isRemoved()` -- returns `true` if the coupon was removed from the cart; otherwise, `false`.

## Calculators and Services

Some calculator default implementations call underlying services:

1. pricing -- invokes the pricing service, which is extensible via the `Commerce_Domain_Pricing_Service` base class.
2. promotions -- invokes the promotions service, which isn’t extensible.
3. inventory -- invokes the inventory service, which is extensible via the `Commerce_Domain_Inventory_Service` base class.
4. shipping -- doesn't invoke a service.
5. postShipping -- doesn't invoke a service.
6. shippingPromotion -- doesn't invoke a service.
7. taxes -- invokes the tax service, which is extensible via the `Commerce_Domain_Tax_Service` base class.

**note:** The shippingPromotion service applies shipping promotions within the out-of-the-box cart calculation orchestrator. It isn't supported for use with a custom cart calculator orchestrator.

## Enable and Disable the Cart Calculate API for a Webstore

Starting in Spring '24, the Cart Calculate API is enabled for all new webstores.

If you create a webstore in the Spring '24 release (or later) and the store is based on an LWR template, you can immediately use the Cart Calculate API.

If you created a webstore prior to the Spring '24 release and the store is based on an LWR template, you can manually enable the Cart Calculate API for your store.

If your webstore is based on an Aura template, the Cart Calculate API isn't supported. You can manually disable the Cart Calculate API for your store.

**important:** The Cart Calculate API isn't compatible with [integrations](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_integration_architecture.htm?q=integrations). Your webstore can either use extensions or integrations, but not both. Although extensions are now the preferred way to customize Salesforce Commerce, integrations remain fully supported. If you want your Spring '24 (or later) webstore to use integrations, you must disable the Cart Calculate API.

To disable the Cart Calculate API for a webstore:

1. In the Developer Console, click **Query Editor**.
2. Enter the following query and click **Execute**:
   `Select Id, Name, OptionsCartCalculateEnabled FROM Webstore`
3. In the OptionsCartCalculateEnabled column, set the value to `false` for the Webstore.

To enable the Cart Calculate API for a webstore:

1. In the Developer Console, click **Query Editor**.
2. Enter the following query and click **Execute**:
   `Select Id, Name, OptionsCartCalculateEnabled FROM Webstore`
3. In the OptionsCartCalculateEnabled column, set the value to `true` for the Webstore.

<!-- document id=5331340736f962e982243d1e237c14bb72bf02a3a1b4bc46238962fae9f42c6b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-cart-limits.md -->

# Cart Data Limits

| Object                            | Limit for B2B                                                             | Store or Org | Notes                                                                                                                                                                                                                                                                                                                      |
| --------------------------------- | ------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Total Open Carts                  | No limit                                                                  | N/A          | The number of carts with items.                                                                                                                                                                                                                                                                                            |
| Line Items per Cart               | 2,000 unique items                                                        | N/A          | Most stores limit cart size to 500 line items per order. However, if your B2B or B2C store requires a higher limit, you can enable support for large carts to process up to 2,000 line items per order. See Considerations for Large Carts.                                                                                |
| Carts                             | 100<sup>\*</sup> carts per user                                           | N/A          | 1 active cart + up to 99 secondary carts. A cart is active as long as the customer is still shopping or has not completed the checkout process. Active carts can consume a lot of data. An active cart tracks products added to the cart by their quantity, price, promotions, and the like.                               |
| Tax Items                         | 5 tax items per cart item. Five tax items per cart item price adjustment. | N/A          | A tax item refers to the specific tax that is applied to a product or service in the shopping cart. It is calculated based on various factors such as the type of product, the location of the buyer, and the tax laws of the region. Your business rules can apply up to 5 tax items per cart.                            |
| Shipping Charges                  | 20                                                                        | N/A          | Charges added to the cart to ship the order.                                                                                                                                                                                                                                                                               |
| Wish List Items                   | 500 items                                                                 | N/A          | Items set aside to consider for a future purchase.                                                                                                                                                                                                                                                                         |
| Wish Lists                        | 10 per user                                                               | N/A          | A list of items a buyer sets aside to consider for a future purchase.                                                                                                                                                                                                                                                      |
| Maximum Number of secondary carts | 100 per user                                                              | N/A          | A single user can only have one primary cart at a time and up to 100 secondary carts. Secondary cart limits are applied to each unique user ID per account ID and webstore ID. Because the user ID is the same for all guest users, any guest users on the same account are limited to up to 100 secondary carts in total. |
| Time to Live                      | 30 days                                                                   | N/A          | Time to Live specifies the time limit on an active checkout to prevent users from checking out with outdated information. The default value is 7 days and the maximum value is 30 days.                                                                                                                                    |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce customer support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

The items per cart limit is a generous 2,000 items. If you know your buyers never approach this limit, you can lower the limit saving data usage for other objects. Consider the same approach for wish list items and wish lists.

All of the cart and wish list data limits can be managed at lower limits. Monitor cart and wish list data usage and if your buyers consistently stay below the limits, you can lower the limits for some or all of the cart and wish list limits. This saves data allowances for other objects.

If you have cart data requirements that exceed the limits, consider the impact on checkout performance and data storage limits.

- Does the additional data push any related data objects beyond their limits?
- Can you offset a data increase by decreasing data requirements in other store functions?

After you assess the impact of a data increase, if you still want to request an increase, contact Support.

<!-- document id=7490bb86209f583dfe4f3ad0523ba2e1e90cecaa49ecfe12f34963de9a451a27 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-cart.md -->

# Cart Data Model

The Cart data model connects objects used to support shopping cart and checkout functionality in a B2B or B2C store. This data model includes objects used to process shipping, taxes, and promotions.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the cart data model require at least one of the following licenses: B2B Commerce, Salesforce Order Management, or Salesforce Payments.

![Diagram of the Cart data model](https://developer.salesforce.com/media/d2c-commerce/cart_data_model.png)

- [Cart (WebCart)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webcart.htm)
- [Cart Adjustment Basis (WebCartAdjustmentBasis)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webcartadjustmentbasis.htm)
- [Cart Adjustment Group (WebCartAdjustmentGroup)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webcartadjustmentgroup.htm)
- [Cart Checkout Session (CartCheckoutSession)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_cartcheckoutsession.htm)
- [Cart Delivery Group (CartDeliveryGroup)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_cartdeliverygroup.htm)
- [Cart Item (CartItem)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_cartitem.htm)
- [Cart Item Price Adjustment (CartItemPriceAdjustment)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_cartitempriceadjustment.htm)
- [Cart Tax (CartTax)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_carttax.htm)
- [Cart Validation Output (CartValidationOutput)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_cartvalidationoutput.htm)
- [Payment Group (PaymentGroup)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentgroup.htm)
- [Payment Method (PaymentMethod)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentmethod.htm)
- [Store (WebStore)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)
- [Cart Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-cart-limits.md)

<!-- document id=b49c2e649338e661f443ecde2d7e9dff853ea546b1fee57d7b1f177519d57968 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/cart-events-webhook.md -->

Cart Events Webhook

# Cart Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-events-webhook/cart-events-webhook-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send cart events data.

**Version:** 2.3.4

## Tags

### Cart Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-events-webhook/cart-events-webhook-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send cart events data.

## Operations

### POST Send suspended cart information.

`POST /merchant/spi/sample/endpoint/sa/customer/cart/suspendCart`

Operation ID: `suspendCartWebhook`. Tags: Cart Events Webhook.

Send the cart details as payload to the external system whenever the cart is suspended on the app.

#### Request body

Media type: `application/json`. Schema: `CartPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Send voided cart information.

`POST /merchant/spi/sample/endpoint/sa/customer/cart/voidCart`

Operation ID: `voidCartWebhook`. Tags: Cart Events Webhook.

Send the cart details as payload to the external system when a void cart operation is done on the app.

#### Request body

Media type: `application/json`. Schema: `CartPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### CartPayload

*   `cartId` (_string_) Cart ID.
*   `suspendedCartId` (_string_, nullable) Unique UUID value present for suspended carts. The value is different from the Cart ID.
*   `storeId` (_string_, nullable) Store ID.
*   `transactionId` (_string_) The unique identifier for this transaction, for example, Void cart.
*   `storeRegisterId` (_string_) Store Register ID. Local to each store.
*   `associateId` (_string_, nullable) Store Associate ID.
*   `cartType` (_string_) The type of cart payload ( Void cart or suspended cart).
*   `cartItemList` (_array of Product_) The list of products added to the cart.
*   `subTotal` (_number_) The subtotal amount of the products added to the cart.
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_) The list of price adjustments done on the items in cart.
*   `orderPriceAdjustments` (_array of OrderPriceAdjustment_) The list of price adjustments done on the total order in the cart.
*   `promotionCodes` (_array of string_) The list of promotion codes applied to the items in cart.
*   `taxTotal` (_number_) The total tax amount for the items in cart.
*   `taxExemption` (_number_) The tax exemption applicable on the items in cart.
*   `transactionDiscountAmount` (_number_) The transaction discount amount for the items in cart.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `shippingTotal` (_number_) The total Shipping amount in case of online orders.
*   `customerEmail` (_string_) The email address of the customer.
*   `profile` (_Profile_)
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the actions performed on the cart. For example, reason for discounts applied to the order.
*   `fullfillmentType` (_string_) The fulfillment type of the order: IN\_STORE or ONLINE.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxRates` (_array of OrderTaxRate_) Sale-side tax rate.
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions.
*   `vatRates` (_array of OrderTaxRate_) Sale-side VAT rate.
*   `netTaxRates` (_array of OrderTaxRate_) Net tax rate calculated based on sale-side tax rate and return-side tax rate.
*   `netVatRates` (_array of OrderTaxRate_) Net VAT rate calculated based on sale-side VAT rate and return-side VAT rate.
*   `amountToBeCharged` (_number_) Amount to be charged.
*   `transactionDiscount` (_Discount_)
*   `exchangeItemRequests` (_array of ExchangeItemRequest_) Request for items that are being returned or exchanged.
*   `summary` (_CartSummary_)
*   `notesList` (_array of OrderNote_, nullable) The order-level notes.
*   `employee` (_Employee_)
*   `transactionStartDate` (_string (date-time)_) The timestamp when the cart was created.
*   `transactionDate` (_string (date-time)_) The timestamp when the cart was voided or suspended.
*   `rewardList` (_array of Reward_, nullable) List of rewards applied to the cart.
*   `tariffAmount` (_number_, nullable) Tariff amount applied to the cart.
*   `tariffRate` (_number_, nullable) Tariff rate applied to the cart.
*   `customerLoyaltyProfile` (_CustomerLoyaltyProfile_)
*   `loyaltyId` (_string_, nullable) Loyalty ID of the customer.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup details for the cart.
*   `shippingMethod` (_ShippingMethod_)
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### OrderPriceAdjustment

The list of price adjustments done on the total order in the cart.

*   `description` (_string_)
*   `adjustment` (_number_)
*   `discount` (_Discount_)
*   `price` (_number_)
*   `promotionId` (_string_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Discount

Transaction discount applied on the cart with information like discount type and discount value. In online mode it is copied from app's request payload for transaction discount and in case of offline mode it is copied from app's submit order request.

*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`, `AMOUNT, PERCENT`. Default: `AMOUNT`.
*   `discount` (_number_, required) Discount either in percentage or in amount.

### ExchangeItemRequest

Request for items that are being returned or exchanged.

*   `storeAssociateId` (_string_, required) ID of the store associate who performs the returns.
*   `storeId` (_string_, required) ID of the store where the return is being performed.
*   `installationId` (_string_, required) Installation ID of the register from where the return is being performed.
*   `noReceiptReturns` (_boolean_, nullable) Flag to indicate returns without receipt.  
    Default: `false`.
*   `receiptType` (_string_, nullable) Receipt type enum.  
    Allowed values: `ORDER`, `QUOTE`, `GIFT`, `GIFT_SKU_LEVEL`, `GIFT_REWARD_CARD`, `INVENTORY_TRANSFER_PACKING_SLIP`, `PO_ORDER`, `STORE_TO_STORE_TRANSFER`, `RETURN_TO_VENDOR_TRANSFER`, `PICK_LIST`.
*   `editOrderId` (_string_, nullable) Set in case of edit order mode. Value will be same as orderId.
*   `refundFees` (_array of RefundFee_) Refund fees applied when cancelling or returning items from an order during the edit order flow.
*   `offlineMode` (_boolean_) Flag to indicate whether returns or exchange is being performed in offline mode or not.
*   `returnProducts` (_array of ReturnProductIdentification_) Returning item's orderItemId and quantity.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakup for return items.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakup for return items.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `storeAttribution` (_StoreAttribution_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `employee` (_Employee_)
*   `orderSource` (_string_, nullable) Order Source - Indicates channel from where the order originated.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariffAmount` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `giftCardCashOut` (_boolean_)
*   `exchangeOrderPaymentDetails` (_array of ExchangeOrderPaymentDetail_)

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### CustomerLoyaltyProfile

The loyalty profile of the customer if they are enrolled in Loyalty program.

*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `firstName` (_string_) Customer's first name.
*   `lastName` (_string_) Customer's last name.
*   `accountNumber` (_string_) Customer's loyalty account number.
*   `loyaltyStatusCode` (_string_, nullable) Customer's loyalty status code.
*   `currentPoints` (_integer (int32)_, nullable) Customer's current loyalty points. If provided, it will be used for validation against the individual reward points (If points are sent in reward).
*   `currentStoreCredit` (_number (double)_, nullable) Customer's current store credit.
*   `lifetimePoints` (_integer (int32)_, nullable) Loyalty point accumulated so far by the customer.
*   `nextRewardPoints` (_integer (int32)_, nullable) Loyalty point eligible for next reward cycle.
*   `transactions` (_Transactions_)
*   `rewards` (_array of Reward_, nullable) Earned rewards.
*   `tierLevelLabel` (_string_, nullable) Customer's tier level label.
*   `tierLevelValue` (_string_, nullable) Customer's tier level value.
*   `tierLevelCode` (_string_, nullable) Customer's tier level code.
*   `redemptionType` (_string_)
*   `internalMemberId` (_string_, nullable) Customer's internal member ID.
*   `homePhoneNumber` (_string_, nullable) Customer's home phone number.
*   `mobilePhoneNumber` (_string_, nullable) Customer's mobile phone number.
*   `address` (_Address_)
*   `currentTier` (_Tier_)
*   `nextTier` (_Tier_)
*   `customLoyaltyAttributes` (_CustomAttributes_)
*   `totalRewardsAmount` (_number_, nullable) Total amount value of all the rewards available for the customer. If provided, this will be used for validation when applying the individual rewards.
*   `loyaltyIdBarCodeType` (_string_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### RefundFee

Refund fees applied when cancelling or returning items from an order during the edit order flow.

*   `id` (_string_) Refund fee ID. For example, Restocking or 001.
*   `label` (_string_) Refund fee display name. For example, Restocking Fee.
*   `value` (_number_, nullable) Refund fee amount.

### ReturnProductIdentification

Returning item's orderItemId and quantity.

*   `orderItemId` (_string_, required) Order item ID of returning product obtained from original order. It provides the returning item's line item number from the original order.
*   `quantity` (_integer (int32)_, required) Total quantity being returned.
*   `reason` (_Reason_)
*   `epc` (_string_) Electronic Product Code/RFID.
*   `serialNumbers` (_array of string_, nullable) Provide serial numbers for returning product if applicable and captured by store associate.  
    Unique items.

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### ExchangeOrderPaymentDetail

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `refundAmount` (_number_)
*   `amountToBeAppliedForExchange` (_number_)
*   `refundTransactionId` (_number_)
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use refundMode instead.
*   `refundRoundingAmount` (_number_)
*   `refundMode` (_string_, nullable) If the tender requires special handling when performing a refund, provide the specific refund mode here. Supported modes are Unreferenced and ExternalAuth. For example, during a credit card authorization call, provide the refund mode ExternalAuth when the app issues the refund instead of the regular flow.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `splitRefund` (_boolean_) If an original tender is split into multiple refunds during return and if the current refund tender is one of the split refunds of the original tender. Used in MaxCashReturn policy where original tender might get split into two during returns.
*   `validRefundTender` (_boolean_)
*   `remapped` (_boolean_)
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### Transactions

Loyalty transactions.

*   `nextStartMonth` (_integer (int32)_)
*   `txnActivity` (_array of TransactionActivity_)

### Tier

Customer's next tier details.

*   `name` (_string_) Tier name.
*   `minPoints` (_number_) Minimum points required for the tier.
*   `display` (_string_)
*   `points` (_integer (int32)_)
*   `memberSince` (_integer (int64)_) Member since, of this tier.
*   `title` (_string_)
*   `subTitle` (_string_)
*   `imageUrl` (_string_)
*   `expiryDate` (_integer (int64)_) Expiry date of the customer's membership.

### CustomAttributes

Custom attributes.

*   `customLabel` (_string_)
*   `customValues` (_array of CustomValue_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### TransactionActivity

*   `orderId` (_string_)
*   `date` (_integer (int64)_)
*   `description` (_string_)
*   `points` (_integer (int32)_)
*   `amount` (_number_)
*   `pointStatus` (_string_)  
    Allowed values: `EARNED`, `PENDING`, `REWARD`, `REDEEMED`.
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    

### CustomValue

*   `laabel` (_string_)
*   `value` (_string_)
*   `iconType` (_string_)

<!-- document id=977918f4e1bd2d263ee1080289ef002ff18c5f4ccf9df89c6ddb32c1c1f41915 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/cart-validation-spi.md -->

Cart Validation SPI

# Cart Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-validation-spi/cart-validation-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations.

**Version:** 2.3.4

## Tags

### Cart Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-validation-spi/cart-validation-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations.

## Operations

### POST Validate cart.

`POST /merchant/spi/sample/endpoint/sa/cartValidation`

Operation ID: `cartValidation`. Tags: Cart Validation SPI.

This SPI endpoint enables POS to send a cart to the merchant's external system for validation. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `CART_VALIDATION`
    *   **API Endpoint:** Provide the external endpoint to get the cart validation, for example: [https://sample/external/endpoint/cartValidation](https://sample/external/endpoint/cartValidation)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `*/*`. Schema: `ExternalCart`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CartValidationResponse`.
    

## Schemas

### ExternalCart

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `cartItemList` (_array of ExternalProduct_, required) All the items from the cart. Each item has a link to its delivery group via deliveryGroupId.
*   `deliveryGroupList` (_array of ExternalDeliveryGroup_) All delivery groups corresponding to the delivery items from the cart.
*   `billingAddress` (_ExternalAddress_)
*   `profile` (_ExternalCustomerProfile_)
*   `pickUpDetailList` (_array of ExternalPickUpDetail_, nullable) Pickup details.

### CartValidationResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `displayMessage` (_string_, nullable) This message is for informational purposes only and is intended for display to users or associates. Please ensure it is not used in error scenarios. For error messages, use 'errorMessage' instead, as this will trigger the creation of a new cart and the execution of tax and other SPI calls.
*   `error` (_boolean_)

### ExternalProduct

Products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.

### ExternalDeliveryGroup

In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.

*   `deliveryGroupId` (_string_, required) Delivery group ID.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup, i.e., buy online ship to store |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_ExternalAddress_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `fulfillmentAddress` (_ExternalAddress_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ExternalAddress

Billing address.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, required, nullable) Customer first name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `addressLine1` (_string_, required, nullable) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required, nullable) City.  
    Maximum length: 64.
*   `state` (_string_, required, nullable) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required, nullable) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, required, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `addressType` (_string_, nullable) Address type- Home, Business.
*   `emailAddress` (_string_, nullable) Customer Email Address.  
    Maximum length: 64.
*   `country` (_string_, nullable) Country.

### ExternalCustomerProfile

Customer profile. It is mandatory for customer logged-in during the transaction. It is optional for guest customer.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.  
    Maximum length: 128.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.  
    Maximum length: 128.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.

### ExternalPickUpDetail

Pickup details.

*   `pickupDetailId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `email` (_string_)
*   `phone` (_string_)

### ExternalStoreAssociateAttribution

Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.

*   `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction.
*   `contributionPercentage` (_number_, required) Associate's contribution towards sales.
*   `attributionNote` (_string_) Note related to attribution.
*   `firstName` (_string_, required) Associate's first name.
*   `lastName` (_string_, required) Associate's last name.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item.
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request.

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### ExternalProductTax

Tax/Vat details.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption.
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates.
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates.
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### ExternalPriceAdjustment

Price adjustments applied on the item.  
It includes all the price adjustments like transaction discount, price override etc...  
Mandatory if any type of price adjustments is applied.

*   `description` (_string_, required) Price adjustment description.
*   `adjustment` (_string_, required) Price adjustment.
*   `id` (_string_) Promotion Id for applied coupon or auto promotion.
*   `price` (_number_, required) Price adjustment amount.
*   `priceAdjustmentType` (_string_, required) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reason` (_Reason_)
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied.  
    Not applicable for auto promotions,  
    manual price adjustments like price override & transaction discount.
*   `auto` (_boolean_, nullable) Applied promotion is auto or not.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system.  
    If an order is placed directly in the POS, this identifier will not be available.  
    The external system provides this identifier, which will then be replayed to that  
    external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.

### ExternalNote

Notes for the transaction.

*   `cartId` (_string_)
*   `noteId` (_string_)
*   `noteText` (_string_)
*   `transactionId` (_string_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

<!-- document id=54ba28b8cb93f26bc4bf895899e42192b30a1ddec634b62f47915ba7d9b19a3d url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/cart-validation-via-spi.md -->

# Cart Validation using SPI

Point of Sale Cart Validation SPI allows the POS app to send a cart to a merchant's external system for validation before order placement. The SPI also reserves inventory, ensuring that items are held for the customer until the order is confirmed. Triggered early in the order flow, this can help merchants manage stock and prevent fraud.

- Modern POS App Build: 10.7.1 or greater
- Platform Support: iPad & iPhone
- Offline Support: No

**note:** For details on this SPI, see [Cart Validation SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/cart-validation-spi?meta=Summary) in the Point of Sale reference documentation.

For a comprehensive list of Point of Sale APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Configure Cart Validation SPI

1. In CMS, go to **Integrations** | **Custom Connectors**.

2. Click **Create**.

3. For Connector Type, select **SPI**.

4. For Endpoint Name, select **CART_VALIDATION**.

5. For API Endpoint, specify the external endpoint.

6. For Integration Type, select **HTTP_POST**.

7. Specify any required JSON headers. For example, `{"Content-Type":"application/json"}`. See [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) for examples.

8. Configure the rest of the fields as needed.

9. Save your changes.

![Example of settings for the SPI.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-process-validate-cart-spi-settings.png)

## Configure Additional SPI and Omnichannel

This section covers optional configurations that can help with inventory tracking, tax calculation, and delivery flexibility. While not required for basic functionality, configuring these settings can unlock advanced features like store-level inventory visibility, SPI-based tax handling, and support for complex fulfillment scenarios.

### Configure Inventory SPI

1. Configure an inventory. See [Inventory Configuration](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_modules_inventory_configuration.htm&type=5) in _Salesforce Help_.

2. Select **SPI** as the Provider.

3. Enable Track Store Inventory in the same Inventory Configuration.

### Configure Tax Engine SPI

1. Configure a tax engine. See [Integrate Tax Engines](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_3p_int_tax_overview.htm) in _Salesforce Help_.

2. Select **SPI** as the Tax Engine.

3. Configure the [Tax Calculation SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html).

### Configure Omni Settings

1.  Enable these [Omnichannel](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_modules_enabling_omni_settings.htm) settings.

    - Enable Order Delivery Grouping

    - Allow Multiple Shipments Per Cart/Order

    - Allow Multiple Delivery and Pickup Dates Per Order

    - Allow Multiple Shipping Addresses Per Order

2.  Configure the [Delivery Group SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-groups-via-spi.html).

## Sample Request and Response

The Cart Validation SPI is triggered just before an order is placed, validating the cart’s contents. It can also manage inventory, such as making reservations. There are two phases during the order placement process: phase 1 and phase 2.

Once a tender type is selected, the app makes the phase 1 call to Point of Sale backend services. During this phase, the POS app invokes the Cart Validation SPI. Because phase 1 occurs before payment is fully processed, inventory reservation also takes place at this stage. The SPI is called only once, even in multi-tender or remote Pay By Link scenarios. Regardless of the number or type of tenders, only one phase 1 call is made.

In this example, if a product’s quantity exceeds 4, a validation failure occurs, displaying an error that the product is out of inventory. For quantities below 4, the validation completes successfully and does not block the checkout flow. The quantity of 4 is just an example, and merchants can customize the validation rules, including the thresholds and error messages, according to their needs.

![The POS shows a shopping cart with 4 selected as the quantity for a product.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-process-validate-cart-spi-pos-1.jpg)![The POS shows an error message indicating that the cart cannot be exported.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-process-validate-cart-spi-pos-2.png)

### Request

`POST/merchant/spi/sample/endpoint/sa/cartValidation`

The request includes all cart items and their associated details. The `cartItemList` contains information for each product in the cart. Key product identifiers such as `productId` and `variantGroupId` are paired with attributes like name, size, color, and quantity. Pricing fields include base price, discounts, subtotal, and total. Each item also includes fulfillment data, such as `fulfillmentType`, `fulfillmentSubType`, and delivery or pickup time slots. Tax information is provided at both item and unit levels, with support for VAT, exemptions, and detailed tax rate metadata. The request also accounts for price adjustments, including promotional discounts and manager-approved overrides.

Additionally, each item supports metadata such as sales associate attribution, return eligibility, required deposits, serial numbers, product condition, and optional notes or return reasons. These details ensure all validations—pricing, taxes, fulfillment, and returnability—are covered before proceeding to checkout.

#### Special Use Case – Delivery Groups

In the Delivery Group SPI, merchants can pass custom product attributes as part of the request. These attributes are defined in the CMS under **Store Management** | **Store Settings** | **Product**, by setting the Merchant-specific product attributes to be provided in SPI request (spiCustomProductAttributes). Merchants can enter a comma-separated list of case-insensitive fields from the product collection. For example, `variantGroupId`, `salePrice`, `manufacturer`, and `brand`. After configuration, these attributes are included in the Delivery Group SPI response.

Note that these custom attributes must be real fields in the product schema and configured at the store level. The overall request schema includes `cartId`, `editOrderId`, `cartItemList`, and `deliveryGroupList`.

```java
{
  "cartId": "string",
  "editOrderId": "string",
  "cartItemList": [
    {
      "productId": "string",
      "variantGroupId": "string",
      "name": "string",
      "price": 0,
      "quantity": 0,
      "orderItemId": "It can have values like 1, 2, 3, etc... which represents line item number within the order.",
      "imageURL": "string",
      "subTotal": 0,
      "discount": 0,
      "total": 0,
      "size": "39-42 or M or 38 etc...",
      "color": "Light Grey or Black etc...",
      "itemStatus": "COMPLETED",
      "gtin": "string",
      "fulfillmentType": "IN_STORE",
      "fulfillmentSubType": "DEFAULT",
      "salesAssociateAttributionList": [
        {
          "storeAssociateId": "string",
          "contributionPercentage": 0,
          "attributionNote": "string",
          "firstName": "string",
          "lastName": "string"
        }
      ],
      "epc": "string",
      "masterProductId": "string",
      "subProducts": [
        "string"
      ],
      "productClass": "string",
      "serialNumber": "string",
      "productCondition": "NEW",
      "reasons": [
        {
          "reasonCodeType": "TRANSACTION_DISCOUNT",
          "reasonCode": "string",
          "reasonText": "string"
        }
      ],
      "dateTimeSlot": {
        "slotId": "1234",
        "slotDate": 0,
        "selectedTimeSlot": "09:00 - 12:00",
        "dateTimeSlotType": "Delivery"
      },
      "priceCorrection": {
        "originalPrice": 0,
        "approvingManagerId": "string"
      },
      "deliveryGroupId": "string",
      "formAttributes": [
        [
          {
            "key": "color",
            "value": "red"
          }
        ]
      ],
      "pickupDetailId": "string",
      "productTax": {
        "totalTax": 0,
        "taxExemption": 0,
        "taxRateList": [
          {
            "countryCode": "US",
            "state": "string",
            "postalCode": "string",
            "taxType": "CLASS",
            "chargeType": "TAX",
            "nonRefundable": false,
            "taxRate": 7.25,
            "taxClass": "Tax Class for Shoes and Clothing - PS0001",
            "taxCode": "string",
            "taxAmount": 7.25,
            "perUnitTaxAmount": 1.25,
            "taxName": "string",
            "displayTaxName": "string",
            "corporateTaxId": "HST-74252RT0001",
            "printTaxName": "string",
            "externalTaxId": "string",
            "isExempt": false,
            "taxDescription": "string",
            "jurisdiction": "string",
            "registrationNumber": "string"
          }
        ],
        "vatRateList": [
          {
            "countryCode": "US",
            "state": "string",
            "postalCode": "string",
            "taxType": "CLASS",
            "chargeType": "TAX",
            "nonRefundable": false,
            "taxRate": 7.25,
            "taxClass": "Tax Class for Shoes and Clothing - PS0001",
            "taxCode": "string",
            "taxAmount": 7.25,
            "perUnitTaxAmount": 1.25,
            "taxName": "string",
            "displayTaxName": "string",
            "corporateTaxId": "HST-74252RT0001",
            "printTaxName": "string",
            "externalTaxId": "string",
            "isExempt": false,
            "taxDescription": "string",
            "jurisdiction": "string",
            "registrationNumber": "string"
          }
        ],
        "valueAddedTax": 0,
        "taxableAmount": 0
      },
      "priceAdjustmentList": [
        {
          "description": "string",
          "adjustment": "string",
          "id": "string",
          "price": 0,
          "priceAdjustmentType": "PRICE_OVERRIDE",
          "promoCode": "string",
          "auto": true,
          "discountValue": 0,
          "discountType": "AMOUNT"
        }
      ],
      "returnsEligibility": "ELIGIBLE_FOR_RETURNS",
      "returnsEligibilityText": "string",
      "pickupStoreId": "string",
      "fulfillmentStoreId": "string",
      "totalAdditionalCharge": 0,
      "tlogCustomProductAttributes": "string",
      "externalId": "string",
      "productBundleId": "string",
      "noteList": [
        {
          "cartId": "string",
          "noteId": "string",
          "noteText": "string",
          "transactionId": "string"
        }
      ],
      "registryId": "string",
      "requiredDeposit": 0,
      "paidDeposit": 0
    }
  ],
  "deliveryGroupList": [
    {
      "deliveryGroupId": "string",
      "fulfillmentType": "IN_STORE",
      "fulfillmentSubType": "DEFAULT",
      "shippingMethod": {
        "shippingMethodId": "001",
        "name": "Standard Shipping",
        "description": "string",
        "carrier": "UPS",
        "serviceLevel": "3-5 Days",
        "price": 0,
        "priceAfterShippingDiscount": 0,
        "sortOrder": 0,
        "taxRates": [
          {
            "countryCode": "US",
            "state": "string",
            "postalCode": "string",
            "taxType": "CLASS",
            "chargeType": "TAX",
            "nonRefundable": false,
            "taxRate": 7.25,
            "taxClass": "Tax Class for Shoes and Clothing - PS0001",
            "taxCode": "string",
            "taxAmount": 7.25,
            "perUnitTaxAmount": 1.25,
            "taxName": "string",
            "displayTaxName": "string",
            "corporateTaxId": "HST-74252RT0001",
            "printTaxName": "string",
            "externalTaxId": "string",
            "isExempt": false,
            "taxDescription": "string",
            "jurisdiction": "string",
            "registrationNumber": "string"
          }
        ],
        "vatRates": [
          {
            "countryCode": "US",
            "state": "string",
            "postalCode": "string",
            "taxType": "CLASS",
            "chargeType": "TAX",
            "nonRefundable": false,
            "taxRate": 7.25,
            "taxClass": "Tax Class for Shoes and Clothing - PS0001",
            "taxCode": "string",
            "taxAmount": 7.25,
            "perUnitTaxAmount": 1.25,
            "taxName": "string",
            "displayTaxName": "string",
            "corporateTaxId": "HST-74252RT0001",
            "printTaxName": "string",
            "externalTaxId": "string",
            "isExempt": false,
            "taxDescription": "string",
            "jurisdiction": "string",
            "registrationNumber": "string"
          }
        ],
        "shippingTax": 0,
        "shippingValueAddedTax": 0,
        "taxExemption": 0,
        "deliveryDate": 0,
        "deliveryTimeSlot": "09:00 - 12:00"
      },
      "shippingAddress": {
        "salutation": "string",
        "firstName": "string",
        "lastName": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "countryCode": "string",
        "phone": "string",
        "storeId": "string",
        "addressType": "string",
        "emailAddress": "string",
        "country": "string"
      },
      "dateTimeSlot": {
        "slotId": "1234",
        "slotDate": 0,
        "selectedTimeSlot": "09:00 - 12:00",
        "dateTimeSlotType": "Delivery"
      },
      "fulfillmentAddress": {
        "salutation": "string",
        "firstName": "string",
        "lastName": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "countryCode": "string",
        "phone": "string",
        "storeId": "string",
        "addressType": "string",
        "emailAddress": "string",
        "country": "string"
      }
    }
  ]
}

```

### Response

The response includes an error code and error message if there's a validation issue. The schema follows a standard response format, including fields such as `errorMessage`, `errorCode`, and `error`.

```java
{
  "errorMessage": "Invalid request. Please check the request and try again.",
  "errorCode": "INTERNAL_ERROR",
  "error": true
}

```


If the cart validation fails, any reserved inventory is released. Merchants must configure the Inventory Service SPI to make sure that all reserved inventory is properly reverted. For more information, see [Retail Cloud API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

<!-- document id=4364b87f256e8c7012dfce069399af340d6c842e0be304282627035d9e91df42 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-cartridges.md -->

# Cartridges

Business functionality in B2C Commerce is organized in cartridges.

## Deploy and Iterate with the B2C Commerce CLI

Using the B2C Commerce CLI, deploy and manage cartridges directly from your terminal. To install the tool and authenticate, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md).

```bash
# Deploy all cartridges in the current project and activate the code version
b2c code deploy --code-version version1 --reload

# Deploy only specific cartridges
b2c code deploy --code-version version1 --cartridge app_custom,int_payment

# Activate a previously uploaded code version
b2c code activate version1

# Live-sync local file changes to the sandbox during development
b2c code watch --code-version version1

# List code versions on the instance
b2c code list
```

For the full command reference, see [Code Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/code.html) in the Agentic B2C Developer Toolkit documentation.

## What Is a Cartridge?

A cartridge is a mechanism for packaging and deploying program code and data. Use cartridges to extend business functionality or integrate with external systems. A cartridge can deliver generic or application-specific functionality.

- Generic cartridges: contain reusable business functionality that can be deployed to many sites.
- Application-specific cartridges: designed to provide functionality that is specific to the needs of a particular ecommerce site.

Add a cartridge for functionality that is:

- Generic: you want to reuse functionality among multiple projects.
- Large and self-contained: you want the functionality self-contained for easier maintenance.

**note:** New functionality doesn't always require a new cartridge.

Cartridges can contain:

- Controllers
- Templates
- Scripts
- Form definitions
- Static content (images, CSS files, and client-side JavaScript files)
- WSDL files

You configure which cartridges are in use by entering a list of those cartridges in Business Manager. The order in which cartridges are listed matters. The list is basically a classpath, with the cartridge as the class. If you want to overwrite files with a particular cartridge, put the cartridge at the end of the list. Use the code upload version directories to change the active directory.

## Cartridge Directory Using WebDAV

Download or view cartridges using a browser or a WebDAV client.

Use the following URL convention:

```
https://<hostname>/on/demandware.servlet/webdav/<organization>/​cartridges/<code version ID>
```

**note:** An example of `<organization>` is `Sites`, for example, `https://ddd.ddd.dw.demandware.net/on/demandware.servlet/webdav/Sites/Cartridges`

**note:** If you want to use WebDAV to access cartridges, the name of the directory that contains the cartridges can contain no more than 50 characters.

The currently selected code version is stored in this file:

```
https://<hostname>/on/demandware.servlet/webdav/<organization>/​Cartridges/.version
```

When using WebDAV to access your cartridges, you’re prompted to enter a username and password. Use your Business Manager username and password.

There are other WebDAV URLs for accessing catalog and content library assets. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup** for WebDAV access via URL references.

Using WebDAV is one way to access a server-based file system to verify if the correct code has been uploaded. Another way is via the Business Manager.

Common problems include:

- The server connection was disabled.
- The server didn’t access your cartridge.

## Download a Cartridge from an Instance

A best practice is to maintain cartridge code in a source control system available to developers. However, in rare cases, it’s useful to download a cartridge from a working instance.

Downloading the cartridge doesn't download the related site data. To download that data, use Site Import or Export.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Code Deployment**.

2.  Click the code version you want to download.

    Usually you want to download the currently active code version, indicated by a green check mark in the Active column.

3.  On the Version Summary page, click **Download**.

## Register a Cartridge

After creating a cartridge, upload it to a server and register it to a site. Register a cartridge to multiple sites.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites** > **_site_**.

2.  On the **Settings** tab, enter one or more cartridge names in **Cartridges**, separated by colons.

    Cartridges take precedence in order from left to right.

3.  Click **Apply**.

<!-- document id=25677e0e5030f09100355102ac382c47d301a0c4c62bef773fb349c355957680 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/catalogs.md -->

Catalogs

# Catalogs

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/catalogs/catalogs-oas-v1-public.yaml)

## API Overview

With the Catalogs API, you can:

*   Create, view, edit, and delete catalogs and categories.
*   Assign and unassign products to categories.
*   Search for a product within a category.
*   Search for categories within a catalog or within a merchandising system.

For more information, see the [Catalogs](https://help.salesforce.com/s/articleView?id=cc.b2c_catalogs.htm&type=5) section in the B2C Commerce documentation.

### Authentication & Authorization

The client managing catalog and category information must have access to the Categories and Catalogs resources. This API requires a bearer token in the header of the request. The client accessing the API must first authenticate against Account Manager to get the bearer token.

You must include the relevant scope(s) in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

Here are some common use cases for the API:

#### Categorize Products

Use the Catalogs API to assign products to categories so that shoppers can find all products that are merchandized in that category.

![b2c-commerce-catalogs-screenshot-1.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-catalogs-screenshot-1.png)

#### Validate Product Category Assignments

Use the Catalogs API to search for products assigned to a category within a site catalog to validate whether a product is merchandized and ready to be sold in one or more ecommerce channels. You can also update a product to make sure it meets the readiness criteria for each channel.

![b2c-commerce-catalogs-screenshot-2.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-catalogs-screenshot-2.png)

#### Edit Categories

Use the Catalogs API to edit categories assigned to a catalog to change the navigation path, make a category online or offline, change position of a category relative to other categories within a catalog.

![b2c-commerce-catalogs-screenshot-3.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-catalogs-screenshot-3.png)

### Resources

A Salesforce B2C Commerce storefront implementation uses a Catalog, Category, and Product architecture to organize your storefront. Product data is stored in a catalog, and the stored product data is organized by categories. You can create any number of catalog, category, and product scenarios to address your business needs.

#### Catalogs

A catalog is a collection of categories, products, and images. It’s best practice to create two catalogs: the master catalog and the storefront catalog. The master catalog provides the same structure as an external system of record for your products. The storefront catalog is where you create categories that appear on your storefront.

#### Categories

You create and organize categories and subcategories to organize and group products in your catalog and on your storefront. Categories allow Products to be organized into hierarchical structures. Categories can have relationships to other parent categories. Each category also can provide a context that is inherited by subcategories, for example a category may have an attribute value assigned to it and any product assigned to the category or a subcategory would inherit the attribute value as long as the product is assigned. Once the product is removed from the category those attribute values would no longer be in the context of the product.

#### Products

Products are the items and services for sale on the storefront. All of your product data is stored in your master catalog. For a product or service to show on your storefront, it must be assigned to a category.

### Related APIs

*   [Products (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/products?meta=Summary) — Manage products within catalogs.

**Version:** 1.0.47

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/catalogs/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.catalogs: catalogs scope READONLY
    *   Scope sfcc.catalogs.rw: catalogs scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Retrieve a list of catalog IDs.

`GET /organizations/{organizationId}/catalogs`

Operation ID: `getCatalogs`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get the list of catalog IDs with no filtering.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Catalogs retrieved successfully.
    
    Media type: `application/json`. Schema: `Catalogs`.
    
    _Example: Catalogs_
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "id": "apparel-catalog"
        },
        {
          "id": "electronics-catalog"
        }
      ],
      "offset": 0,
      "total": 2
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getCategoryFromCatalog400_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter",
      "detail": "offset-BAD-REQUEST parameters are not defined in RAML."
    }
    ```
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getCatalog401_
    
    ```
    {
      "title": "Invalid Access Token",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token",
      "detail": "The request is unauthorized, the access token is invalid.",
      "accessToken": "iI6IjEiLCJhbGciOiJIUzI1NiIsInR5cCI6Ik"
    }
    ```
    

### GET Retrieve details of a specific catalog.

`GET /organizations/{organizationId}/catalogs/{catalogId}`

Operation ID: `getCatalog`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Gets the catalog with the specified information.

#### Parameters

*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Catalog retrieved successfully.
    
    Media type: `application/json`. Schema: `Catalog`.
    
    _Example: Catalog_
    
    ```
    {
      "categoryCount": 30,
      "creationDate": "2019-02-21T22:09:39.000Z",
      "id": "apparel-catalog",
      "lastModified": "2019-02-21T22:09:39.000Z",
      "name": {
        "default": "Apparel Master Catalog"
      },
      "online": true,
      "recommendationCount": 0,
      "rootCategory": "root"
    }
    ```
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getCatalog404_
    
    ```
    {
      "title": "Catalog Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/catalog-not-found",
      "detail": "No catalog with ID '095c2082-5f2a-47d5-bc73-27d06c5c9db8' could be found.",
      "catalogId": "095c2082-5f2a-47d5-bc73-27d06c5c9db8"
    }
    ```
    

### PATCH Update details of a specific catalog.

`PATCH /organizations/{organizationId}/catalogs/{catalogId}`

Operation ID: `updateCatalog`. Security: AmOAuth2 (sfcc.catalogs.rw).

Update the catalog with the specified information.

#### Parameters

*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Catalog`.

_Example: CatalogBody_

```
{
  "id": "apparel-catalog",
  "online": true
}
```

#### Responses

*   **200** Catalog updated successfully.
    
    Media type: `application/json`. Schema: `Catalog`.
    
    _Example Catalog: same as GET /organizations/{organizationId}/catalogs/{catalogId} 200 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### GET Retrieve all categories within a catalog.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories`

Operation ID: `getCategoriesFromCatalog`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get all categories with no filtering.

#### Parameters

*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Categories retrieved successfully.
    
    Media type: `application/json`. Schema: `Categories`.
    
    _Example: Catalog_
    
    ```
    {
      "limit": 3,
      "data": [
        {
          "id": "kids-wear"
        },
        {
          "id": "mens"
        },
        {
          "id": "mens-accessories-luggage"
        }
      ],
      "offset": 0,
      "total": 3
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### GET Retrieve details of a specific category within a catalog.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}`

Operation ID: `getCategoryFromCatalog`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

By default, the server returns the first level of sub-categories, but you can specify another level by setting the levels parameter. Using a large value for levels can cause performance issues with large and deep category trees.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `levels` (query, integer (int32)) The level number.  
    Minimum: 0. Example: `1`.

#### Responses

*   **200** Category retrieved successfully.
    
    Media type: `application/json`. Schema: `Category`.
    
    _Example: CategoryExample_
    
    ```
    {
      "catalogId": "apparel-catalog",
      "categories": [
        {
          "catalogId": "apparel-catalog",
          "creationDate": "2019-02-21T22:09:40.000Z",
          "id": "mens-accessories",
          "lastModified": "2019-02-21T22:10:14.000Z",
          "name": {
            "default": "Accessories"
          },
          "online": true,
          "parentCategoryId": "mens"
        },
        {
          "catalogId": "apparel-catalog",
          "creationDate": "2019-02-21T22:09:40.000Z",
          "id": "mens-clothing",
          "lastModified": "2019-02-21T22:10:15.000Z",
          "name": {
            "default": "Clothing"
          },
          "online": true,
          "parentCategoryId": "mens"
        }
      ],
      "creationDate": "2019-02-21T22:09:40.000Z",
      "id": "mens",
      "lastModified": "2019-09-04T15:07:14.000Z",
      "online": true,
      "parentCategoryId": "root",
      "position": 2
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### PUT Create or update a category within a catalog.

`PUT /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}`

Operation ID: `createCategoryInCatalog`. Security: AmOAuth2 (sfcc.catalogs.rw).

Create a catalog category using the information provided.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Category`.

_Example: CategoryBody_

```
{
  "catalogId": "apparel-catalog",
  "id": "mens",
  "online": true
}
```

#### Responses

*   **200** Category updated successfully.
    
    Media type: `application/json`. Schema: `Category`.
    
    _Example: SingleCategory_
    
    ```
    {
      "catalogId": "apparel-catalog",
      "creationDate": "2019-02-21T22:09:40.000Z",
      "id": "mens",
      "lastModified": "2019-09-04T15:07:14.000Z",
      "online": true,
      "parentCategoryId": "root",
      "position": 2
    }
    ```
    
*   **201** Category created successfully.
    
    Media type: `application/json`. Schema: `Category`.
    
    _Example SingleCategory: same as PUT /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId} 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### DELETE Delete a specific category from a catalog.

`DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}`

Operation ID: `deleteCategoryFromCatalog`. Security: AmOAuth2 (sfcc.catalogs.rw).

Delete a category by catalog ID and category ID.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Category deleted successfully.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### PATCH Update a specific category within a catalog.

`PATCH /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}`

Operation ID: `updateCategoryInCatalog`. Security: AmOAuth2 (sfcc.catalogs.rw).

Update a catalog category using the information provided.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Category`.

_Example: CategoryBody_

```
{
  "catalogId": "apparel-catalog",
  "id": "mens",
  "online": true
}
```

#### Responses

*   **200** Category updated successfully.
    
    Media type: `application/json`. Schema: `Category`.
    
    _Example SingleCategory: same as PUT /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId} 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### POST Search for category product assignments.

`POST /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/category-product-assignment-search`

Operation ID: `searchProductsAssignedToCategory`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

The query attribute specifies a complex query that can be used to narrow down the search.

Searchable attributes:

| Attribute | Type |
| --- | --- |
| productId | String |
| productName | String |
| onlineFlag | Boolean |
| searchable | Boolean |
| validFrom | DateTime |
| validTo | DateTime |
| creationDate | DateTime |

Sortable Fields:

| Attribute | Type |
| --- | --- |
| productId | String |
| productName | String |
| position | Double |
| creationDate | DateTime |

Expansions that can be applied for the search request:

*   product\_base - String

The product\_base expand enables retrieval of the following basic product information:

| Attribute | Type | Function |
| --- | --- | --- |
| none | String | Does not fetch any expanded information. |
| product\_images | String | Fetch preview image and image groups specified for the given product. |
| product\_all\_images | String | Fetch preview image, image groups specified for the product, and variant and variation group images. |
| product\_variations | String | Fetch variations-related information. |
| product\_availability | String | Fetch availability-related information. |
| product\_categories | String | Fetch category-related information. |
| product\_prices | String | Fetch price-related information. |
| product\_options | String | Fetch options-related information. |
| product\_all | String | Fetch all expanded information. This is the default used when no expand value is included in the request. |

Note: productAll includes the following:

*   brand
*   ean
*   link
*   longDescription
*   manufacturerName
*   manufacturerSku
*   name
*   pageDescription
*   pageKeywords
*   pageTitle
*   searchable
*   shortDescription
*   type
*   unit
*   upc

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.

#### Request body (required)

Media type: `application/json`. Schema: `CategoryProductAssignmentSearchRequest`.

_Example: ProductAssignmentBody_

```
{
  "query": {
    "termQuery": {
      "fields": [
        "product_id"
      ],
      "operator": "is",
      "values": [
        "NTOSimpleBundle"
      ]
    }
  },
  "expand": [
    "product_categories",
    "product_images"
  ]
}
```

#### Responses

*   **200** Assignments searched successfully.
    
    Media type: `application/json`. Schema: `CategoryProductAssignmentSearchResult`.
    
    _Example: CategoryProductAssignment_
    
    ```
    {
      "hits": [
        {
          "catalogId": "NTOCatalog",
          "categoryId": "NTOFirstClassCategory",
          "creationDate": "2024-05-27T10:11:48.000Z",
          "lastModified": "2024-05-27T10:11:48.000Z",
          "owningCatalogName": {
            "default": "NTO Product Image Catalog"
          },
          "product": {
            "assignedCategories": [
              {
                "catalogId": "NTOCatalog",
                "categoryId": "NTOFirstClassCategory"
              }
            ],
            "brand": "Wapi brand",
            "creationDate": "2024-05-27T10:11:45.000Z",
            "id": "NTOSimpleBundle",
            "image": {
              "absUrl": "https://www.yoursecureimageserver.com/foo/bar/bundle_image_detail.jpg",
              "alt": {
                "default": "ALT bundle image detail"
              },
              "path": "bundle_image_detail.jpg",
              "title": {
                "default": "TITLE bundle image detail"
              }
            },
            "onlineFlag": {
              "default": true
            },
            "searchable": {
              "default": true
            }
          },
          "productId": "NTOSimpleBundle",
          "productName": {
            "default": "Simple Web API Bundle"
          }
        }
      ],
      "query": {
        "termQuery": {
          "fields": [
            "product_id"
          ],
          "operator": "is",
          "values": [
            "NTOSimpleBundle"
          ]
        }
      },
      "limit": 1,
      "offset": 0,
      "total": 1
    }
    ```
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### GET Retrieve a category product assignment.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/products/{productId}`

Operation ID: `getAssignedProductFromCategory`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Retrieve a category product assignment.

For example, if we have products A, B, C at positions 1, 2, 7.5, and we delete the assignment for product B, the result is products A, B, C at positions 1, null, 7.5.

#### Parameters

*   `productId` (path, ProductId, required) The ID (SKU) of the requested product to assign.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Assignment retrieved successfully.
    
    Media type: `application/json`. Schema: `CategoryProductAssignment`.
    
    _Example: CatalogCategoryPrdAssignmentExample_
    
    ```
    {
      "catalogId": "apparel-catalog",
      "categoryId": "kids-wear",
      "owningCatalogName": {
        "default": "Electronics Master Catalog"
      },
      "position": 1,
      "productId": "apple-ipod-shuffle",
      "productName": {
        "default": "Apple iPod Shuffle"
      }
    }
    ```
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### PUT Create a category product assignment.

`PUT /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/products/{productId}`

Operation ID: `assignProductToCategory`. Security: AmOAuth2 (sfcc.catalogs.rw).

Create a category product assignment using the information provided.

Because the assigned position n is a normalized target position, we verify that the product is assigned to a position that maintains the position order.

For example, if we have products A, B, C at positions 1, 2, 3, and product D is assigned to position 2, the end result is products A, D, B, C with position order 1, 2, 3, 4.

If there are n existing position assignments, assigning a new product to position >= n+1 results in a new assignment with position n+1.

#### Parameters

*   `productId` (path, ProductId, required) The ID (SKU) of the requested product to assign.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CategoryProductAssignment`.

_Example: CatalogCategoryProdAssignmentBody_

```
{
  "catalogId": "apparel-catalog",
  "categoryId": "kids-wear",
  "productId": "apple-ipod-shuffle",
  "position": 1
}
```

#### Responses

*   **200** Assignment updated successfully.
    
    Media type: `application/json`. Schema: `CategoryProductAssignment`.
    
    _Example CatalogCategoryPrdAssignmentExample: same as GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/products/{productId} 200 response._
    
*   **201** Assignment created successfully.
    
    Media type: `application/json`. Schema: `CategoryProductAssignment`.
    
    _Example CatalogCategoryPrdAssignmentExample: same as GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/products/{productId} 200 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### DELETE Remove a category product assignment.

`DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/products/{productId}`

Operation ID: `unassignProductFromCategory`. Security: AmOAuth2 (sfcc.catalogs.rw).

Remove a category product assignment.

For example, if we have products A, B, C at positions 1, 2, 7.5, and we delete the assignment for product B, the result is products A, B, C at positions 1, null, 7.5.

#### Parameters

*   `productId` (path, ProductId, required) The ID (SKU) of the requested product to assign.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Assignment deleted successfully.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### PATCH Update a category product assignment.

`PATCH /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/products/{productId}`

Operation ID: `updateProductCategoryAssignment`. Security: AmOAuth2 (sfcc.catalogs.rw).

Update the category product assignment with the specified information, such as position. Because the assigned position n is a normalized target position, we verify that the product is assigned to a position that maintains position order.

For example, if we have products A, B, C, D at positions 1, 2, 3, 4 and we update product A with a new position of 3, the end result is products B, C, A, D with position order 1, 2, 3, 4. If we then update product C to no position, the end result is products B, A, D, C with position order 1, 2, 3, null.

If there are n existing positioned assignments, updating a product to position >= n results in a new assignment with a position that maintains the position order.

#### Parameters

*   `productId` (path, ProductId, required) The ID (SKU) of the requested product to assign.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CategoryProductAssignment`.

_Example: CatalogCategoryProdAssignmentBody_

```
{
  "catalogId": "apparel-catalog",
  "categoryId": "kids-wear",
  "productId": "apple-ipod-shuffle",
  "position": 1
}
```

#### Responses

*   **200** Assignment updated successfully.
    
    Media type: `application/json`. Schema: `CategoryProductAssignment`.
    
    _Example CatalogCategoryPrdAssignmentExample: same as GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/products/{productId} 200 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### GET Get the status of the latest categorization job.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules-execution`

Operation ID: `getCategorizationStatus`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get the status of the latest categorization job, which could be evaluation or execution. For evaluation, the matched count and a paginated list of product IDs are returned. For execution, the counts of the products that are assigned or unassigned are returned.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, Limit) Maximum records to retrieve per request, not to exceed the maximum defined. A limit must be at least 1 so at least one record is returned (if any match the criteria).
    
    _Example: limit_
    
    ```
    25
    ```
    
*   `offset` (query, Offset) The zero-based index of the first hit/data to include in the result.
    
    _Example: offset_
    
    ```
    25
    ```
    

#### Responses

*   **200** Job executed status returned successfully.
    
    Media type: `application/json`. Schema: `ExecutionJobStatusResult`.
    
    _Example: ExecutionJobStatusResponse_
    
    ```
    {
      "type": "evaluation",
      "assignedCount": 1,
      "unassignedCount": 0,
      "matchedCount": 1,
      "jobStatus": "success",
      "message": "Job execution success.",
      "lastRunDate": "2019-02-21T22:09:40.000Z",
      "productIds": [
        "25772719"
      ],
      "limit": 10,
      "offset": 0
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getCategorizationStatus404_
    
    ```
    {
      "title": "JobExecution Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/job-execition-not-found",
      "detail": "No JobExecution could be found for given catalog, category",
      "catalogId": "apparel-catalog",
      "category": "Mens"
    }
    ```
    

### POST Submit a job to evaluate or execute the rules.

`POST /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules-execution`

Operation ID: `runCategoryRules`. Security: AmOAuth2 (sfcc.catalogs.rw).

Submit a job to evaluate or execute the rules. The evaluation returns a set of matching products based on the rules and conditions. The execution categorizes the products based on the evaluated results.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ExecutionRequest`.

_Example: ExecutionRequestBody_

```
{
  "evaluation": true
}
```

#### Responses

*   **202** Job submitted successfully.
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### GET Get the list of excluded products.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products`

Operation ID: `getExclusionList`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get the list of excluded products for a given catalog and category.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Excluded products retrieved successfully.
    
    Media type: `application/json`. Schema: `ExcludedProductsResult`.
    
    _Example: GetExcludedProducts_
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "productId": "red-shirt"
        },
        {
          "productId": "blue-shirt"
        }
      ],
      "total": 2
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### POST Add products to the exclusion list.

`POST /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products`

Operation ID: `addProductsToExclusionList`. Security: AmOAuth2 (sfcc.catalogs.rw).

Add the product to the excluded product list for a given catalog and category. After a product is added as an excluded product for the category, the categorization process no longer categorizes that product for that category.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ExcludedProductRequest`.

_Example: ExcludedProductsRequestBody_

```
{
  "data": [
    {
      "productId": "red-shirt"
    },
    {
      "productId": "blue-shirt"
    }
  ]
}
```

#### Responses

*   **200** Excluded products list added for a catalog category.
    
    Media type: `application/json`. Schema: `ExcludedProductsResult`.
    
    _Example: GetExcludedProducts_
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "productId": "red-shirt"
        },
        {
          "productId": "blue-shirt"
        }
      ],
      "total": 2
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### DELETE Remove products from the exclusion list.

`DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products`

Operation ID: `removeProductsFromExclusionList`. Security: AmOAuth2 (sfcc.catalogs.rw).

Delete products from the excluded products list for a catalog category.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ExcludedProductRequest`.

_Example: ExcludedProductsRequestBody_

```
{
  "data": [
    {
      "productId": "red-shirt"
    },
    {
      "productId": "blue-shirt"
    }
  ]
}
```

#### Responses

*   **204** No content.
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getRuleById404_
    
    ```
    {
      "title": "Rule Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/rule-not-found",
      "detail": "No Rule with ID 'VHRULE' could be found.",
      "ruleId": "VHRULE"
    }
    ```
    

### GET Retrieve all rules for a catalog and category.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules`

Operation ID: `getCategoryRules`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get all rules for the given catalog and category.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Rules retrieved successfully
    
    Media type: `application/json`. Schema: `RulesResult`.
    
    _Example: GetRules_
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "id": "VHRule",
          "enabled": true,
          "exclusion": false,
          "categorizationLocaleId": "en-US",
          "categorizationClassificationFlag": true,
          "categorizationPrimaryFlag": true,
          "conditions": [
            {
              "id": "NameCondition",
              "attributeKey": "name",
              "attributeValue": [
                "Shirt"
              ],
              "attributeName": "name",
              "operator": "starts_with"
            },
            {
              "id": "BrandCondition",
              "attributeKey": "brand",
              "attributeValue": [
                "Van Heusen"
              ],
              "attributeName": "brand",
              "operator": "equals"
            }
          ]
        },
        {
          "id": "DXRule",
          "enabled": true,
          "exclusion": false,
          "categorizationLocaleId": "en-US",
          "categorizationClassificationFlag": true,
          "categorizationPrimaryFlag": true,
          "conditions": [
            {
              "id": "NameCondition",
              "attributeKey": "name",
              "attributeValue": [
                "Shirt"
              ],
              "attributeName": "name",
              "operator": "starts_with"
            },
            {
              "id": "BrandCondition",
              "attributeKey": "brand",
              "attributeValue": [
                "DX"
              ],
              "attributeName": "brand",
              "operator": "equals"
            }
          ]
        }
      ],
      "total": 2
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### POST Create rules and conditions for a catalog and category.

`POST /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules`

Operation ID: `createCategoryRules`. Security: AmOAuth2 (sfcc.catalogs.rw).

Create all rules and conditions within the catalog and category. This deletes any existing rules and conditions for that catalog and category combination, and recreates them based on the new request. The LocaleID, PrimaryFlag, and ClassificationFlag can be set on any of the individual rules, but they apply to the entire ruleset. For simplicity, those values can be provided with one of the rules. If they are provided with multiple rules, then they must all have the same value for all rules or it could produce undesired effects.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `RulesRequest`.

_Example: PostRuleRequestBody_

```
{
  "data": [
    {
      "id": "VHRule",
      "enabled": true,
      "exclusion": false,
      "categorizationLocaleId": "en-US",
      "categorizationClassificationFlag": true,
      "categorizationPrimaryFlag": true,
      "conditions": [
        {
          "id": "NameCondition",
          "attributeKey": "name",
          "attributeValue": [
            "Shirt"
          ],
          "operator": "starts_with"
        },
        {
          "id": "BrandCondition",
          "attributeKey": "brand",
          "attributeValue": [
            "Van Heusen"
          ],
          "operator": "equals"
        }
      ]
    },
    {
      "id": "DXRule",
      "enabled": true,
      "exclusion": false,
      "categorizationLocaleId": "en-US",
      "categorizationClassificationFlag": true,
      "categorizationPrimaryFlag": true,
      "conditions": [
        {
          "id": "NameCondition",
          "attributeKey": "name",
          "attributeValue": [
            "Shirt"
          ],
          "operator": "starts_with"
        },
        {
          "id": "BrandCondition",
          "attributeKey": "brand",
          "attributeValue": [
            "DX"
          ],
          "operator": "equals"
        }
      ]
    }
  ]
}
```

#### Responses

*   **200** Rules created successfully.
    
    Media type: `application/json`. Schema: `RulesResult`.
    
    _Example GetRules: same as GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### DELETE Delete all rules and conditions for a catalog and category.

`DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules`

Operation ID: `deleteCategoryRules`. Security: AmOAuth2 (sfcc.catalogs.rw).

Delete all rules and conditions for the given catalog and category.

#### Parameters

*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** No content.
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getRuleById404: same as DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products 404 response._
    

### GET Retrieve a rule by ID.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}`

Operation ID: `getRuleById`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get a rule by ID.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Rule retrieved successfully
    
    Media type: `application/json`. Schema: `Rule`.
    
    _Example: GetRulesByID_
    
    ```
    {
      "id": "VHRule",
      "enabled": true,
      "exclusion": false,
      "categorizationLocaleId": "en-US",
      "categorizationClassificationFlag": true,
      "categorizationPrimaryFlag": true,
      "conditions": [
        {
          "id": "NameCondition",
          "attributeKey": "name",
          "attributeValue": [
            "Shirt"
          ],
          "attributeName": "name",
          "operator": "starts_with"
        },
        {
          "id": "BrandCondition",
          "attributeKey": "brand",
          "attributeName": "brand",
          "attributeValue": [
            "Van Heusen"
          ],
          "operator": "equals"
        }
      ]
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getRuleById404: same as DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products 404 response._
    

### PUT Create or update a rule.

`PUT /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}`

Operation ID: `createUpdateRule`. Security: AmOAuth2 (sfcc.catalogs.rw).

Create or update a rule.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `RuleRequest`.

_Example: PutRuleRequestBody_

```
{
  "id": "VHRule",
  "enabled": true,
  "exclusion": false
}
```

#### Responses

*   **200** Rule updated successfully.
    
    Media type: `application/json`. Schema: `Rule`.
    
    _Example: PutRuleRequestBody_
    
    ```
    {
      "id": "VHRule",
      "enabled": true,
      "exclusion": false
    }
    ```
    
*   **201** Rule created successfully.
    
    Media type: `application/json`. Schema: `Rule`.
    
    _Example: PutRuleRequestBody_
    
    ```
    {
      "id": "VHRule",
      "enabled": true,
      "exclusion": false
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### DELETE Delete a rule.

`DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}`

Operation ID: `deleteRule`. Security: AmOAuth2 (sfcc.catalogs.rw).

Delete a rule.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** No content.
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getRuleById404: same as DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products 404 response._
    

### GET Retrieve conditions for a rule.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}/conditions`

Operation ID: `getCategoryRuleConditions`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get the conditions for a given rule, catalog and category.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Conditions retrieved successfully.
    
    Media type: `application/json`. Schema: `ConditionsResult`.
    
    _Example: GetConditions_
    
    ```
    {
      "limit": 2,
      "conditions": [
        {
          "id": "NameCondition",
          "attributeKey": "name",
          "attributeValue": [
            "Shirt"
          ],
          "attributeName": "name",
          "operator": "starts_with"
        },
        {
          "id": "BrandCondition",
          "attributeKey": "brand",
          "attributeValue": [
            "Van Heusen"
          ],
          "attributeName": "brand",
          "operator": "equals"
        }
      ],
      "total": 2
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### DELETE Delete all conditions for a rule.

`DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}/conditions`

Operation ID: `deleteCategoryRuleConditions`. Security: AmOAuth2 (sfcc.catalogs.rw).

Deletes all conditions for a given rule, catalog, and category.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** No content.
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getRuleById404: same as DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products 404 response._
    

### GET Retrieve a condition by ID.

`GET /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}/conditions/{conditionId}`

Operation ID: `getCategoryRuleCondition`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Get a condition by ID.

#### Parameters

*   `conditionId` (path, string, required) The Id of the condition.  
    Maximum length: 256. Example: `NameCondition`.
*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Condition retrieved successfully.
    
    Media type: `application/json`. Schema: `Condition`.
    
    _Example: GetConditionByID_
    
    ```
    {
      "id": "NameCondition",
      "attributeKey": "name",
      "attributeValue": [
        "Shirt"
      ],
      "attributeName": "name",
      "operator": "starts_with"
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### PUT Create or update a condition.

`PUT /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}/conditions/{conditionId}`

Operation ID: `createOrUpdateCategoryRuleCondition`. Security: AmOAuth2 (sfcc.catalogs.rw).

Create or update a condition.

#### Parameters

*   `conditionId` (path, string, required) The Id of the condition.  
    Maximum length: 256. Example: `NameCondition`.
*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Condition`.

_Example: PutConditionRequestBody_

```
{
  "id": "NameCondition",
  "attributeKey": "brand",
  "attributeValue": [
    "Van Heusen"
  ],
  "operator": "equals"
}
```

#### Responses

*   **200** Condition updated successfully.
    
    Media type: `application/json`. Schema: `Condition`.
    
    _Example: GetConditionByID_
    
    ```
    {
      "id": "NameCondition",
      "attributeKey": "name",
      "attributeValue": [
        "Shirt"
      ],
      "attributeName": "name",
      "operator": "starts_with"
    }
    ```
    
*   **201** Condition created successfully.
    
    Media type: `application/json`. Schema: `Condition`.
    
    _Example: GetConditionByID_
    
    ```
    {
      "id": "NameCondition",
      "attributeKey": "name",
      "attributeValue": [
        "Shirt"
      ],
      "attributeName": "name",
      "operator": "starts_with"
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### DELETE Delete a condition.

`DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/rules/{ruleId}/conditions/{conditionId}`

Operation ID: `deleteCategoryRuleCondition`. Security: AmOAuth2 (sfcc.catalogs.rw).

Delete a condition.

#### Parameters

*   `conditionId` (path, string, required) The Id of the condition.  
    Maximum length: 256. Example: `NameCondition`.
*   `ruleId` (path, string, required) The unique identifier of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `categoryId` (path, CategoryId, required) The ID of the category to be created.
*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** No content.
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getRuleById404: same as DELETE /organizations/{organizationId}/catalogs/{catalogId}/categories/{categoryId}/excluded-products 404 response._
    

### POST Search for catalog categories.

`POST /organizations/{organizationId}/catalogs/{catalogId}/category-search`

Operation ID: `searchCategoriesInCatalog`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Search for catalog categories in the scope of a catalog. By default, the server returns the first level of subcategories, but you can specify another level by setting the levels parameter. Subcategories are sorted by category position, then by categoryId. Using a large value for levels can cause performance issues with large and deep category trees.

The query attribute specifies a complex query that can be used to narrow down the search with the following searchable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| description | String |
| creationDate | DateTime |
| online | Boolean |
| parentCategoryId | String |

The output of the query can also be sorted with the following sortable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| description | String |
| creationDate | DateTime |
| online | Boolean |
| position | Double |

If no sorting clause is provided, categories are sorted by categoryId. If sorting clause(s) are provided, categoryId is used as a tiebreaker.

#### Parameters

*   `catalogId` (path, CatalogId, required) The ID of the requested catalog.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `levels` (query, integer (int32)) The level number.  
    Minimum: 0. Example: `1`.

#### Request body (required)

Media type: `application/json`. Schema: `CatalogCategorySearchRequest`.

_Example: CatalogSearchBody_

```
{
  "start": 0,
  "count": 50,
  "query": {
    "boolQuery": {
      "should": [
        {
          "textQuery": {
            "searchPhrase": "Luggage",
            "fields": [
              "name"
            ]
          }
        }
      ]
    }
  }
}
```

#### Responses

*   **200** Categories searched successfully.
    
    Media type: `application/json`. Schema: `CategorySearchResult`.
    
    _Example: CategorySearchResultExample_
    
    ```
    {
      "limit": 1,
      "hits": [
        {
          "catalogId": "storefront-catalog-en",
          "creationDate": "2019-02-21T22:10:04.000Z",
          "id": "electronics-accessories",
          "lastModified": "2019-02-21T22:10:49.000Z",
          "name": {
            "default": "Accessories"
          },
          "online": false,
          "pageTitle": {
            "default": "Electronics Accessories"
          },
          "parentCategoryId": "electronics",
          "position": 14
        }
      ],
      "query": {
        "termQuery": {
          "fields": [
            "online"
          ],
          "operator": "is",
          "values": [
            "false"
          ]
        }
      },
      "offset": 0,
      "total": 1
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### POST Search for catalogs.

`POST /organizations/{organizationId}/catalog-search`

Operation ID: `searchCatalogs`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Search for catalogs.

The query attribute specifies a complex query that can be used to narrow down the search with the following searchable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| description | String |
| creationDate | DateTime |

There are two additional fields that can be used as search filters. They are not attributes in the CatalogWO object, but they can be used as filters to query catalogs based on site assignments.

| Attribute | Type |
| --- | --- |
| isMasterCatalog | Boolean |
| isStorefrontCatalog | Boolean |
| description | String |
| creationDate | DateTime |
| online | Boolean |
| position | Double |

When you use isMasterCatalog in the search query, catalogs without any site assignments are returned. When you use isStorefrontCatalog in the search query, catalogs with one or more site assignments are returned.

The output of the query can also be sorted with the following sortable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| description | String |
| creationDate | DateTime |

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CatalogSearchRequest`.

_Example: CatalogSearchBodyQuery_

```
{
  "query": {
    "termQuery": {
      "fields": [
        "is_storefront_catalog"
      ],
      "operator": "is",
      "values": [
        "true"
      ]
    }
  }
}
```

#### Responses

*   **200** Catalogs searched successfully.
    
    Media type: `application/json`. Schema: `CatalogSearchResult`.
    
    _Example: CatalogSearchResultQuery_
    
    ```
    {
      "limit": 3,
      "hits": [
        {
          "assignedSites": [
            {
              "cartridges": "sitegenesis_storefront_pipelines:sitegenesis_storefront_core:plugin_apple_pay:plugin_facebook:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
              "customerListLink": {
                "customerListId": "Site_1"
              },
              "displayName": {
                "default": "Site Site_1"
              },
              "id": "Site_1",
              "inDeletion": false,
              "storefrontStatus": "online"
            }
          ],
          "categoryCount": 53,
          "creationDate": "2019-02-22T00:11:14.000Z",
          "id": "NavigationCatalog_9430935",
          "lastModified": "2019-02-22T00:11:14.000Z",
          "name": {
            "default": "Root Category"
          },
          "online": true,
          "recommendationCount": 0,
          "rootCategory": "root"
        },
        {
          "assignedSites": [
            {
              "cartridges": "sitegenesis_storefront_controllers:sitegenesis_storefront_core:plugin_apple_pay:plugin_facebook:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
              "customerListLink": {
                "customerListId": "SiteGenesis"
              },
              "displayName": {
                "default": "SiteGenesis"
              },
              "id": "SiteGenesis",
              "inDeletion": false,
              "storefrontStatus": "online"
            }
          ],
          "categoryCount": 66,
          "creationDate": "2019-02-21T22:10:04.000Z",
          "id": "storefront-catalog-en",
          "lastModified": "2019-02-21T22:10:04.000Z",
          "name": {
            "it-IT": "Catalogo dello storefront - IT",
            "default": "Storefront Catalog - EN",
            "fr-FR": "Catalogue de boutique en ligne - FR",
            "zh-CN": "网店目录 - EN",
            "ja-JP": "ストアフロントカタログ - EN"
          },
          "online": true,
          "recommendationCount": 1865,
          "rootCategory": "root"
        },
        {
          "assignedSites": [
            {
              "cartridges": "sitegenesis_storefront_controllers:sitegenesis_storefront_core:plugin_apple_pay:plugin_facebook:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
              "customerListLink": {
                "customerListId": "SiteGenesis"
              },
              "displayName": {
                "default": "SiteGenesisGlobal"
              },
              "id": "SiteGenesisGlobal",
              "inDeletion": false,
              "storefrontStatus": "online"
            }
          ],
          "categoryCount": 42,
          "creationDate": "2019-02-21T22:10:09.000Z",
          "id": "storefront-catalog-non-en",
          "lastModified": "2019-02-21T22:10:09.000Z",
          "name": {
            "it-IT": "Storefront Catalog - Non-EN",
            "default": "Storefront Catalog - Non-EN",
            "fr-FR": "Catalogue de boutique en ligne - Non - EN",
            "zh-CN": "Storefront Catalog - Non-EN",
            "ja-JP": "ストアフロントカタログ - Non-EN"
          },
          "online": true,
          "recommendationCount": 1865,
          "rootCategory": "root"
        }
      ],
      "query": {
        "termQuery": {
          "fields": [
            "is_storefront_catalog"
          ],
          "operator": "is",
          "values": [
            "true"
          ]
        }
      },
      "offset": 0,
      "total": 3
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

### POST Search for categories within an organization.

`POST /organizations/{organizationId}/category-search`

Operation ID: `searchCategories`. Security: AmOAuth2 (sfcc.catalogs, sfcc.catalogs.rw).

Search for catalog categories. By default, the server returns the first level of subcategories, but you can specify another level by setting the levels parameter. Subcategories are sorted by category position, then by categoryId. Using a large value for levels can cause performance issues with large and deep category trees.

The query attribute specifies a complex query that can be used to narrow down the search with the following searchable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| description | String |
| creationDate | DateTime |
| online | Boolean |
| catalogId | String |

The output of the query can also be sorted with the following sortable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| description | String |
| creationDate | DateTime |
| online | Boolean |
| position | Double |

If no sorting clause is provided, categories are sorted by categoryId. If sorting clause(s) are provided, categoryId is used as a tiebreaker.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `levels` (query, integer (int32)) The level number.  
    Minimum: 0. Example: `1`.

#### Request body (required)

Media type: `application/json`. Schema: `CategorySearchRequest`.

_Example: CategorySearchBody_

```
{
  "query": {
    "termQuery": {
      "fields": [
        "online"
      ],
      "operator": "is",
      "values": [
        "false"
      ]
    }
  }
}
```

#### Responses

*   **200** Categories searched successfully.
    
    Media type: `application/json`. Schema: `CategorySearchResult`.
    
    _Example CategorySearchResultExample: same as POST /organizations/{organizationId}/catalogs/{catalogId}/category-search 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCategoryFromCatalog400: same as GET /organizations/{organizationId}/catalogs 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog401: same as GET /organizations/{organizationId}/catalogs 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCatalog404: same as GET /organizations/{organizationId}/catalogs/{catalogId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### Catalogs

Catalogs allow categories to be organized into hierarchical structures.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Catalog_, required) The collection of catalogs.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CatalogId

The ID of the catalog.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `apparel-catalog`.

### Catalog

Document representing a catalog.

*   `assignedProductCount` (_integer (int32)_) The count of products assigned to the catalog. It is read only.  
    Example: `20`.
*   `assignedSites` (_array of Site_) The sites assigned to the catalog. It is read only.
*   `categoryCount` (_integer (int32)_) The category count of catalog. It is read only.  
    Example: `10`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. It is read only.  
    Maximum length: 30. Example: `253402214400`.
*   `description` (_object_) The description of catalog.
    
    Additional properties: `string`.
    
*   `id` (_CatalogId_, required)
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. It is read only.  
    Maximum length: 30. Example: `253402214400`.
*   `name` (_object_) The catalog name.
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The online status of catalog.  
    Example: `false`.
*   `ownedProductCount` (_integer (int32)_) The count of products owned by the catalog. It is read only.  
    Example: `100`.
*   `recommendationCount` (_integer (int32)_) The recommendation count of the catalog. It is read only.  
    Example: `50`.
*   `rootCategory` (_string_) The root category of the catalog. It is read only.  
    Maximum length: 256. Example: `apparel-master-catalog`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Categories

Categories allow products to be organized into hierarchical structures. Categories can have relationships to other parent categories. Each category also can provide a context inherited by subcategories. For example, a category may have an attribute value assigned to it, and any product assigned to the category or a subcategory would inherit the attribute value as long as the product is assigned. Once the product is removed from the category those attribute values would no longer be in the context of the product. Linking of categories is also used for Site hierarchical navigation. For example, inside 'Clothing' you may have 'Mens', and inside 'Mens' you may have 'Pants'. Categories are not _Tags_."

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Category_, required) Category data

### CategoryId

The ID of the category.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `mens`.

### Category

Document representing a category.

*   `catalogId` (_object_) The ID of the catalog that contains it.  
    Example: `apparel-catalog`.
    
    Includes all fields of `CatalogId`.
    
    Example: `apparel-catalog`.
    
*   `categories` (_array of Category_) The array of subcategories for the category.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. It is read only.  
    Maximum length: 30. Example: `253402214400`.
*   `description` (_object_) The localized description of the category.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Mens Clothing Outerwear"
    }
    ```
    
*   `id` (_object_, required) The ID of the category.  
    Example: `mens-clothing-outerwear`.
    
    Includes all fields of `CategoryId`.
    
    Example: `mens-clothing-outerwear`.
    
*   `image` (_string_) The name of the category image. The URL to the image is computed.  
    Minimum length: 1. Maximum length: 256. Example: `Summer Bomber Jacket`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. It is read only.  
    Maximum length: 30. Example: `253402214400`.
*   `name` (_object_) The localized name of the category.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Mens Clothing Outerwear"
    }
    ```
    
*   `online` (_boolean_) The online status of the category determines if it is visible in the storefront. Defaults to false if not specified on creation.  
    Example: `true`.
*   `pageDescription` (_object_) The localized page description of the category.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Mens Outerwear Category"
    }
    ```
    
*   `pageKeywords` (_object_) The localized page keywords for the category.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Outerwear"
    }
    ```
    
*   `pageTitle` (_object_) The localized page title of the category.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Mens Clothing Outerwear"
    }
    ```
    
*   `parentCategoryId` (_string_) The ID of the parent category. Defaults to root if not specified on creation.  
    Minimum length: 1. Maximum length: 256. Example: `mens-clothing`.
*   `paths` (_array of PathRecord_) The path record.
*   `position` (_number (double)_) The position of the category determines the display order in the storefront.  
    Example: `3`.
*   `sortingRules` (_array of SortingRule_) The category sorting rules.
*   `thumbnail` (_string_) The name of the category thumbnail. The URL to the thumbnail is computed.  
    Minimum length: 1. Maximum length: 256. Example: `Summer Bomber Jacket Large`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### CategoryProductAssignmentSearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

Includes all fields of `SearchRequest`.

_Example_

```
{
  "limit": 4,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "campaign"
    }
  },
  "offset": 2
}
```

### CategoryProductAssignmentSearchResult

Document representing a product search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of CategoryProductAssignment_, required) The sorted array of search hits. This array can be empty.

_Example_

```
{
  "value": [
    {
      "limit": 1,
      "hits": [
        {
          "couponId": "MyCoupon",
          "creationDate": "2019-10-20T12:00:00Z",
          "description": "This coupon is used to give 10% off stuff.",
          "enabled": false,
          "exportedCodeCount": 0,
          "lastModified": "2019-10-30T04:23:59Z",
          "redemptionCount": 3,
          "redemptionLimits": {
            "limitPerCode": 1,
            "limitPerCustomer": 1,
            "limitPerTimeFrame": {
              "limit": 2,
              "redemptionTimeFrame": 24
            }
          },
          "singleCode": "MyCode",
          "systemCodesConfig": {
            "codePrefix": "SG",
            "numberOfCodes": 500000
          },
          "totalCodesCount": 50,
          "type": "single_code"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id",
            "description"
          ],
          "searchPhrase": "stuff"
        }
      },
      "sorts": [
        {
          "field": "couponId",
          "sortOrder": "desc"
        }
      ],
      "offset": 2,
      "total": 8
    }
  ]
}
```

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### CategoryProductAssignment

Document representing a category product assignment.

*   `catalogId` (_object_, required) The ID of the catalog.  
    Example: `apparel-catalog`.
    
    Includes all fields of `CatalogId`.
    
    Example: `apparel-catalog`.
    
*   `categoryId` (_object_, required) The ID of the category.  
    Example: `mens`.
    
    Includes all fields of `CategoryId`.
    
    Example: `mens`.
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. It is read only.  
    Maximum length: 30. Example: `253402214400`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. It is read only.  
    Maximum length: 30. Example: `253402214400`.
*   `owningCatalogName` (_object_) The name of the catalog that owns the product.
    
    Additional properties: `string`.
    
*   `position` (_number (double)_) The position of product category assignment.  
    Example: `2`.
*   `product` (_Product_)
*   `productId` (_ProductId_, required)
*   `productName` (_object_) The name of the product.
    
    _Example_
    
    ```
    {
      "default": "Summer Bomber Jacket"
    }
    ```
    

### Limit

Maximum records to retrieve per request, not to exceed the maximum defined. A limit must be at least 1 so at least one record is returned (if any match the criteria).

Type: `integer (int32)`.

Default: `10`. Minimum: 1. Example: `10`.

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### ExecutionJobStatusResult

The status of the execution job.

*   `type` (_string_) The type of execution job.  
    Allowed values: `evaluation`, `execution`. Example: `evaluation`.
*   `assignedCount` (_integer_) Indicates total number of products assigned by the execution job.  
    Example: `100`.
*   `unassignedCount` (_integer_) Indicates total number of products unassigned by the execution job.  
    Example: `100`.
*   `matchedCount` (_integer_) Indicates total number of products evaluated and matched by the evaluation job.  
    Example: `100`.
*   `jobStatus` (_string_, required) Indicates the status of the rules execution job (that is, indicates whether the job completed successfully or an error occurred).  
    Allowed values: `inProgress`, `success`, `error`, `unavailable`. Example: `success`.
*   `message` (_string_) A description of any errors, failures, and exceptions that caused the job to fail.  
    Example: `Job execution failed to start.`.
*   `lastRunDate` (_string (date-time)_) The date that the rules categorization job was last run for given catalog and category.  
    Maximum length: 30. Example: `253402214400`.
*   `productIds` (_array of string_) The list of matched product IDs returned by the execution job.  
    Items: Maximum length: 256. Example: `apple-ipod-classic`.
    
    _Example_
    
    ```
    [
      25772717,
      25772792
    ]
    ```
    
*   `limit` (_Limit_)
*   `offset` (_Offset_)

### ExecutionRequest

The document representing the execution Request for categorization.

*   `evaluation` (_boolean_, required) A flag indicating whether only an evaluation job needs to be performed.  
    Default: `true`. Example: `true`.

### ExcludedProductsResult

The list of excluded products.

*   `limit` (_Limit_, required)
*   `data` (_array of ExcludedProduct_) The list of the excluded products. This can be empty.
*   `total` (_Total_, required)

### ExcludedProductRequest

The excluded product record

*   `data` (_array of ExcludedProduct_, required) The list of the excluded products.

### RulesResult

Result document containing an array of rules.

Includes all fields of `ResultBase`.

*   `data` (_array of Rule_) The list of rules. This can be empty. _Note_ - If the exclusion attribute is set to true, the rule is designated as an Exclusion rule. Any item matching an Exclusion rule is omitted from the final result set.

### RulesRequest

Request document containing an array of rules for saving multiple rules.

*   `data` (_array of Rule_) The list of rules. This can be empty.

### Rule

Document representing a categorization rule.

*   `id` (_string_, required) The ID of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `enabled` (_boolean_, required) A flag indicating whether this rule is enabled.  
    Default: `false`. Example: `false`.
*   `exclusion` (_boolean_, required) A flag indicating whether this rule is an exclusion.  
    Default: `false`. Example: `false`.
*   `categorizationLocaleId` (_string_) This field indicates the locale to be used for evaluating rules/conditions for the entire category. Note: this applies to all the rules for that category, and the last modification for this field will apply to the entire ruleset for that category.  
    Maximum length: 10. Example: `en-US`.
*   `categorizationClassificationFlag` (_boolean_) This field indicates if the matching products assigned as a result of the rules run will be given the tag for classification category. Note: this applies to all the rules for that category, and the last modification for this field will apply to the entire ruleset for that category.  
    Default: `false`. Example: `true`.
*   `categorizationPrimaryFlag` (_boolean_) This field indicates if the matching products assigned as a result of the rules run will be given the tag for primary category. Note: this applies to all the rules for that category, and the last modification for this field will apply to the entire ruleset for that category.  
    Default: `false`. Example: `true`.
*   `conditions` (_array of Condition_) The list of conditions for the rule.

### RuleRequest

This document represents the request body while creating a rule.

*   `id` (_string_, required) The ID of the rule.  
    Maximum length: 256. Example: `VHRule`.
*   `enabled` (_boolean_, required) A flag indicating whether this rule is enabled.  
    Default: `false`. Example: `false`.
*   `exclusion` (_boolean_, required) A flag indicating whether this rule is an exclusion.  
    Default: `false`. Example: `false`.
*   `categorizationLocaleId` (_string_) This field indicates the locale to be used for evaluating rules/conditions for the entire category. Note: this applies to all the rules for that category, and the last modification for this field will apply to the entire ruleset for that category.  
    Maximum length: 10. Example: `en-US`.
*   `categorizationClassificationFlag` (_boolean_) This field indicates if the matching products assigned as a result of the rules run will be given the tag for classification category. Note: this applies to all the rules for that category, and the last modification for this field will apply to the entire ruleset for that category.  
    Default: `false`. Example: `true`.
*   `categorizationPrimaryFlag` (_boolean_) This field indicates if the matching products assigned as a result of the rules run will be given the tag for primary category. Note: this applies to all the rules for that category, and the last modification for this field will apply to the entire ruleset for that category.  
    Default: `false`. Example: `true`.

### ConditionsResult

Result document containing an array of conditions.

*   `limit` (_Limit_, required)
*   `conditions` (_array of Condition_) The list of conditions for a rule. This can be empty.
*   `total` (_Total_, required)

### Condition

Document representing a condition.

*   `id` (_string_, required) The ID of the condition.  
    Maximum length: 256. Example: `NameCondition`.
*   `attributeKey` (_string_, required) The key of the attribute(system or custom). This represents the ID of the attribute.  
    Maximum length: 256. Example: `name`.
*   `attributeName` (_string_) The human-readable name of the attribute(system or custom). This is a read-only field.  
    Maximum length: 4000. Example: `name`.
*   `attributeValue` (_array of string_, required) Array of attribute values.
    
    Each item: The value of the attribute.
    
      
    Items: Maximum length: 4000. Example: `someValue`.
    
    _Example_
    
    ```
    [
      "Shirt"
    ]
    ```
    
*   `operator` (_string_, required) The operator for the condition.  
    Allowed values: `starts_with`, `contains`, `equals`, `not_equals`, `greater_than`, `less_than`, `is_one_of`, `not_one_of`, `is_defined`, `is_not_defined`. Example: `starts_with`.

### CatalogCategorySearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

Includes all fields of `SearchRequest`.

_Example_

```
{
  "limit": 4,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "campaign"
    }
  },
  "offset": 2
}
```

### CategorySearchResult

Document representing a catalog search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Category_, required) The sorted array of search hits. Can be empty.

_Example_

```
{
  "value": [
    {
      "limit": 1,
      "hits": [
        {
          "couponId": "MyCoupon",
          "creationDate": "2019-10-20T12:00:00Z",
          "description": "This coupon is used to give 10% off stuff.",
          "enabled": false,
          "exportedCodeCount": 0,
          "lastModified": "2019-10-30T04:23:59Z",
          "redemptionCount": 3,
          "redemptionLimits": {
            "limitPerCode": 1,
            "limitPerCustomer": 1,
            "limitPerTimeFrame": {
              "limit": 2,
              "redemptionTimeFrame": 24
            }
          },
          "singleCode": "MyCode",
          "systemCodesConfig": {
            "codePrefix": "SG",
            "numberOfCodes": 500000
          },
          "totalCodesCount": 50,
          "type": "single_code"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id",
            "description"
          ],
          "searchPhrase": "stuff"
        }
      },
      "sorts": [
        {
          "field": "couponId",
          "sortOrder": "desc"
        }
      ],
      "offset": 2,
      "total": 8
    }
  ]
}
```

### CatalogSearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

Includes all fields of `SearchRequest`.

_Example_

```
{
  "limit": 4,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "campaign"
    }
  },
  "offset": 2
}
```

### CatalogSearchResult

Document representing a catalog search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Catalog_, required) The sorted array of catalog search hits. Can be empty.

_Example_

```
{
  "value": [
    {
      "limit": 1,
      "hits": [
        {
          "couponId": "MyCoupon",
          "creationDate": "2019-10-20T12:00:00Z",
          "description": "This coupon is used to give 10% off stuff.",
          "enabled": false,
          "exportedCodeCount": 0,
          "lastModified": "2019-10-30T04:23:59Z",
          "redemptionCount": 3,
          "redemptionLimits": {
            "limitPerCode": 1,
            "limitPerCustomer": 1,
            "limitPerTimeFrame": {
              "limit": 2,
              "redemptionTimeFrame": 24
            }
          },
          "singleCode": "MyCode",
          "systemCodesConfig": {
            "codePrefix": "SG",
            "numberOfCodes": 500000
          },
          "totalCodesCount": 50,
          "type": "single_code"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id",
            "description"
          ],
          "searchPhrase": "stuff"
        }
      },
      "sorts": [
        {
          "field": "couponId",
          "sortOrder": "desc"
        }
      ],
      "offset": 2,
      "total": 8
    }
  ]
}
```

### CategorySearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

Includes all fields of `SearchRequest`.

_Example_

```
{
  "limit": 4,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "campaign"
    }
  },
  "offset": 2
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Site

Document representing a site.

*   `cartridges` (_string_) The cartridge path of the site.  
    Example: `sitegenesis_storefront_controllers:sitegenesis_storefront_core`.
*   `customerListLink` (_object_) Document representing a link to a customer list.
    *   `customerListId` (_string_, required) The customerList ID.  
        Maximum length: 256. Example: `SiteGenesis`.
    *   `title` (_object_) The link title.
        
        Additional properties: `string`.
        
*   `description` (_object_) The description of this site.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Prototypical site used for starting point"
    }
    ```
    
*   `displayName` (_object_, required) The display name entered by the user.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Site Genesis"
    }
    ```
    
*   `id` (_SiteId_, required)
*   `inDeletion` (_boolean_) The deletion status of this site, true if in deletion.  
    Example: `false`.
*   `storefrontStatus` (_string_) The storefront status of the site, it can be optionally be set to online, maintenance, to\_be\_deleted, and protected.  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`. Example: `online`.

### PathRecord

Document representing most basic info (ID and name) of a category or catalog.

*   `id` (_object_) The ID of the category path.  
    Example: `mens-clothing`.
    
    Includes all fields of `CategoryId`.
    
    Example: `mens-clothing`.
    
*   `name` (_object_) The name of the category path.
    
    Additional properties: `string`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### SortingRule

Document representing a product sorting rule.

*   `creationDate` (_string (date-time)_) The creation date, read only.  
    Maximum length: 30. Example: `253402214400`.
*   `description` (_string_) The description of the product sorting rule.  
    Maximum length: 4000. Example: `Sorts by price descending`.
*   `id` (_string_) The ID of the product sorting rule.  
    Maximum length: 256. Example: `price-high-to-low`.
*   `productSortingRuleSteps` (_array of SortingRuleStep_) The steps involved in sorting by this rule.
*   `ruleContext` (_string_) The context of the rule, either site or global.  
    Allowed values: `site`, `global`. Example: `site`.
*   `site` (_SiteId_)

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### Product

Any product that is sold, shown alone, and does not have variations such as different sizes or colors. Product that has no reliance on any other product for inheritance. _A product has a SKU and can have a product option, which has a different SKU_.

*   `assignedCategories` (_array of CatalogCategoryId_) The catalog categories that the product is assigned to. It is read only.
*   `ats` (_number (double)_) The Available To Sell (ATS) inventory value of the product. This is a calculated value.  
    Example: `15`.
*   `brand` (_string_) The brand of the product.  
    Example: `Apple`.
*   `bundledProducts` (_array of Product_) The array of bundled products which the product includes. It is read only.
*   `classificationCategory` (_CatalogCategoryId_)
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. It is read only.  
    Example: `253402214400`.
*   `defaultVariantId` (_string_) The ID of the product's default variant. It is read only.  
    Example: `apple-ipod-classic-8gb-black`.
*   `ean` (_string_) The European Article Number of the product.  
    Example: `ksdf69w4`.
*   `id` (_ProductId_, required)
*   `image` (_MediaFile_)
*   `imageGroups` (_array of ImageGroup_) The array of product image groups. It is read only.
*   `inStock` (_boolean_) The flag that indicates if the product is in stock, or not. This is a calculated value.  
    Example: `true`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. It is read only.  
    Example: `253402214400`.
*   `localizedTaxClassId` (_object_) The localized tax class identifier of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "exempt"
    }
    ```
    
*   `longDescription` (_object_) The localized long description of the product.
    
    Additional properties: `MarkupText`.
    
*   `manufacturerName` (_string_) The name of the product's manufacturer.  
    Example: `Apple`.
*   `manufacturerSku` (_string_) The SKU of the product's manufacturer.  
    Example: `HSD68J`.
*   `master` (_Master_)
*   `name` (_object_) The localized name of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Apple Ipod Classic"
    }
    ```
    
*   `online` (_boolean_) The flag that indicates if the product is online, or not. This is a calculated value.  
    Example: `true`.
*   `onlineFlag` (_object_) The site-specific online status of the product.
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "Site1": true
    }
    ```
    
*   `owningCatalogId` (_string_) The ID of the catalog that owns the product.  
    Example: `apple-master-catalog`.
*   `owningCatalogName` (_object_) The localized name of the catalog that owns the product. It is read only.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Apple Master Catalog"
    }
    ```
    
*   `pageDescription` (_object_) The localized page description of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Page Description"
    }
    ```
    
*   `pageKeywords` (_object_) The localized page keywords of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Keywords"
    }
    ```
    
*   `pageTitle` (_object_) The localized page title of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Page Title"
    }
    ```
    
*   `price` (_number (double)_) The price of the product.  
    Example: `219.99`.
*   `priceCurrency` (_string_) The currency code for a product's price.  
    Example: `USD`.
*   `pricePerUnit` (_number (double)_) The price per unit of the product. This is a read only field.  
    Example: `1`.
*   `primaryCategories` (_array of CatalogCategoryId_) The primary catalog categories that the product is assigned to. It is read only.
*   `primaryCategoryId` (_string_) The ID of the products primary category. This is a read only field. It is read only.  
    Example: `electronics-media-players`.
*   `productBundles` (_array of Product_) The array of product bundles which the product belongs to. It is read only.
*   `productOptions` (_array of ProductOption_) The array of product options. This is applicable for products of type "option". It is read only.
*   `productSets` (_array of Product_) The array of product sets which the product belongs to. It is read only.
*   `searchable` (_object_) The site-specific searchable status of the product.
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "Site1": true
    }
    ```
    
*   `setProducts` (_array of Product_) The array of set products which the product includes. It is read only.
*   `shortDescription` (_object_) The localized short description of the product.
    
    Additional properties: `MarkupText`.
    
*   `taxClassId` (_string_) The tax class identifier of the product.  
    Example: `standard`.
*   `type` (_ProductType_)
*   `unit` (_string_) The sales unit of the product.  
    Example: `single`.
*   `unitMeasure` (_string_) The unitMeasure of the product.  
    Example: `each`.
*   `unitQuantity` (_number (double)_) The unitQuantity of the product.  
    Example: `15`.
*   `upc` (_string_) The Universal Product Code (UPC) of the product.  
    Example: `66JSD88JASD`.
*   `validFrom` (_object_) The valid/online from date of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default@SiteGenesis": "2000-05-11T00:00:00.000Z"
    }
    ```
    
*   `validTo` (_object_) The valid/online to date of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default@SiteGenesis": "2050-05-11T00:00:00.000Z"
    }
    ```
    
*   `variants` (_array of Variant_) The array of variants of the product. This is applicable for product types "master" and "variationGroup" only. It is read only.
*   `variationAttributes` (_array of VariationAttribute_) The sorted array of variation attributes assigned to the product. This is applicable for product types "master", "variationGroup" and "variant" only. It is read only.
*   `variationGroups` (_array of VariationGroup_) The array of variation groups in the product. This is applicable for product type "master" only. It is read only.
*   `variationValues` (_object_) The variation values selected for the product in variation attribute id and value pairs. This is applicable for product types "Variant" and "VariationGroup" only. It is read only.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "red",
      "size": "8gb"
    }
    ```
    

### ExcludedProduct

The excluded product record.

*   `productId` (_ProductId_, required)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### SortingRuleStep

Document representing a product sorting rule step.

*   `attributeId` (_string_) The ID for sorting attribute.  
    Maximum length: 256. Example: `price`.
*   `direction` (_string_) The direction of the sorting attribute.  
    Allowed values: `asc`, `desc`. Example: `desc`.
*   `isSystem` (_boolean_) Whether or not the attribute is a system attribute.  
    Example: `false`.
*   `position` (_integer (int32)_) The position of product sorting rule step.  
    Example: `1`.
*   `textRelevanceIncluded` (_boolean_) The text relevance included.  
    Example: `true`.
*   `typeId` (_string_) The sorting type for sorting attribute.  
    Maximum length: 256. Example: `price`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### CatalogCategoryId

Document representing a catalog category ID.

*   `catalogId` (_CatalogId_, required)
*   `categoryId` (_CategoryId_, required)

### MediaFile

Document representing media file.

*   `absUrl` (_string_) The absolute URL with request protocol.  
    Example: `https://www.example-image.com/images/apple-ipod-classic.jpg`.
*   `alt` (_object_) The alternative image text.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "iPod"
    }
    ```
    
*   `disBaseUrl` (_string_) The Dynamic Image Service (DIS) base URL for product images only.  
    Example: `https://www.dis-base-url/images/apple-ipod-clasic.jpg`.
*   `path` (_string_, required) The raw media file path.  
    Example: `/images/apple-ipod-classic.jpg`.
*   `title` (_object_) The image title.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "iPod"
    }
    ```
    

### ImageGroup

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of MediaFile_, required) The images of the image group.
*   `variationAttributes` (_array of VariationAttribute_) Returns a list of variation attributes applying to this image group.
*   `viewType` (_string_, required) The image view type.  
    Example: `hi-res`.

### MarkupText

Document representing markup text.

*   `markup` (_string_, required) The rendered HTML.
*   `source` (_string_, required) The raw markup text.

### Master

Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for it's product variants, and is used for navigation. _Does'nt have a SKU._

*   `masterId` (_ProductId_, required)
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The minimum sales price of the related variants.  
    Example: `199.99`.
*   `priceMax` (_number (double)_) The maximum sales of related variants.  
    Example: `219.99`.
*   `prices` (_object_) prices
    
    Additional properties: `number (double)`.
    

### ProductOption

Product options enable you to sell configurable products that have optional accessories, upgrades, or additional services. Options are always purchased with a product and can't be purchased separately.

*   `customName` (_object_) The localized custom name of the product option.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Warranty"
    }
    ```
    
*   `defaultProductOptionValue` (_string_) The default product option value.  
    Example: `5-years`.
*   `description` (_object_) The localized description of the product option.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Option Description"
    }
    ```
    
*   `id` (_string_, required) The object attribute definition ID which is also the identifier for the product option.  
    Minimum length: 1. Example: `warranty`.
*   `image` (_MediaFile_)
*   `name` (_string_) The name of the object attribute definition.  
    Example: `Warranty`.
*   `selectedOptionValue` (_string_) The selected option value of the product option.  
    Example: `2-years`.
*   `shared` (_boolean_) The flag that indicates if the product option is shared or local.  
    Example: `false`.
*   `sortingMode` (_string_) The sorting mode for the product option values.  
    Allowed values: `byexplicitorder`, `byoptionprice`. Example: `byoptionprice`.
*   `values` (_array of ProductOptionValue_) The sorted array of values of the product option.

### ProductType

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.  
    Example: `false`.
*   `bundled` (_boolean_) A flag indicating whether the product is bundled.  
    Example: `false`.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.  
    Example: `false`.
*   `master` (_boolean_, required) A flag indicating whether the product is a master.  
    Example: `true`.
*   `option` (_boolean_) A flag indicating whether the product is an option.  
    Example: `false`.
*   `partOfProductSet` (_boolean_) A flag indicating whether the product is part of product set.  
    Example: `false`.
*   `partOfRetailSet` (_boolean_) A flag indicating whether the product is part of retail set.  
    Example: `false`.
*   `retailSet` (_boolean_) A flag indicating whether the product is a retail set.  
    Example: `false`.
*   `set` (_boolean_) A flag indicating whether the product is a set.  
    Example: `false`.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.  
    Example: `false`.
*   `variationGroup` (_boolean_) A flag indicating whether the product is a variation group.  
    Example: `false`.

### Variant

A product which is a variation within a master product that describes different colors, sizes, or other variation attributes. _Has a SKU_

*   `ats` (_number (double)_) The Available To Sell (ATS) inventory value of the product. This is a calculated value.  
    Example: `10`.
*   `defaultProductVariation` (_boolean_) A flag indicating whether the variant is a default variant.  
    Example: `true`.
*   `image` (_MediaFile_)
*   `inStock` (_boolean_) True if the product is in stock, false if not.  
    Example: `true`.
*   `online` (_boolean_) If the product is currently online. True if online, false if not.  
    Example: `true`.
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The sales price of the variant.  
    Example: `29.99`.
*   `priceCurrency` (_string_) Currency code for the price of the product.  
    Example: `USD`.
*   `productId` (_ProductId_, required)
*   `searchable` (_object_) A flag indicating whether the variant is searchable.
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "Site1": true
    }
    ```
    
*   `variationAttributes` (_array of VariationAttribute_) Variation attributes.
*   `variationValues` (_object_) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "black"
    }
    ```
    

### VariationAttribute

Document representing a variation attribute.

*   `attributeDefinitionId` (_string_, required) The id of the requested attribute definition.  
    Example: `color`.
*   `attributeDefinitionName` (_object_) The localized display name of the variation attribute definition.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Color"
    }
    ```
    
*   `defaultValue` (_string_) Default variation attribute value.  
    Example: `black`.
*   `id` (_string_) The ID of the variation attribute.  
    Minimum length: 1. Example: `color`.
*   `name` (_object_) The localized display name of the variation attribute.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Color"
    }
    ```
    
*   `shared` (_boolean_) Returns the value of attribute 'shared' if attribute is local or shared.  
    Example: `false`.
*   `slicing` (_boolean_) Returns the value of attribute 'slicing'.  
    Example: `true`.
*   `values` (_array of VariationAttributeValue_) The sorted array of variation values. This array can be empty.
*   `variationAttributeType` (_string_) Variation attribute type.  
    Allowed values: `string`, `int`, `unknown`. Example: `string`.

### VariationGroup

Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for it's product variants, and is used for navigation. _Doesn't have a SKU._

*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The sales price of the variation group.  
    Example: `229.99`.
*   `productId` (_string_, required) The ID (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic-black`.
*   `variationValues` (_object_) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "red"
    }
    ```
    

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### ProductOptionValue

Document representing a product option Value

*   `defaultProductOptionValue` (_boolean_) Flag indicating if the product option value is the default value for the product option.  
    Example: `true`.
*   `id` (_string_, required) The ID of the product option value.  
    Minimum length: 1. Example: `5-year`.
*   `optionPrices` (_array of Money_) The list of prices in the product option value.
*   `skuExtension` (_string_) The SKU extension of the product option value.  
    Example: `extension`.
*   `value` (_object_, required) The localized value of the product option.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "5 Year Warranty"
    }
    ```
    

### VariationAttributeValue

Document representing a variation attribute value.

*   `description` (_object_) The localized description of the variation value.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Red"
    }
    ```
    
*   `image` (_MediaFile_)
*   `imageSwatch` (_MediaFile_)
*   `name` (_object_) The localized display name of the variation value.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "Red"
    }
    ```
    
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.  
    Example: `true`.
*   `position` (_number (double)_) The position of the value among all values of a variation attribute.  
    Example: `2`.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1. Example: `red`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### Money

A combination of a Currency and an amount of that Currency.

*   `currencyMnemonic` (_CurrencyCode_)
*   `value` (_number (double)_) The amount of money for the given currency.  
    Example: `1234.56`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

<!-- document id=0ab2199f7da135e13ac6e6aaad2c0ad16b7bafe52be25e86fb6455ac984de446 url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-categories.md -->

Categories

# Categories

Categories are necessary so that your products appear on the site. Sellers may upload their own categories, but these will not appear directly in the e-commerce environment. This is because, after uploading your categories, you can access the salesforce environment and perform a match with the e-commerce categories, so that the products in your categories are automatically uploaded into the e-commerce categories.

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### PATCH Create or Update Category

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Category__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-category-1`

Operation ID: `Create or Update Category`. Tags: Category. Security: bearerAuth.

To perform different types of updates on categories, you can provide different JSON data in the request body. The following examples are included in the request body section of this page:

**Example 1 of 2**: `Create or update category`

This call allows you to both create and update a seller category. If a category already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

The value of `Atonit_Mktplace__Matched_Category__r` must be one of the IDs of the marketplace categories from "Get All Marketplace Category". It is not mandatory to create a category, but it may need to be completed either by integration or directly on the Seller Center match screen.

**Example 2 of 2**: `Match category with Marketplace category`

This call allows you to associate a seller category to a marketplace category. This action needs to use "Get All Marketplace Category" to find the ID of the Marketplace category. This operation can also be performed directly in the Seller Center or during the creation of the category itself.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `string`.

Type: `string`.

_Example: Create or update category_

```
Create or update category example:

{
  "Name": "Casa e Cozinha",
  "Atonit_Mktplace__Is_Deleted__c": false,
  "Atonit_Mktplace__Description__c": "Produtos para Casa e Cozinha",
  "Atonit_Mktplace__Full_Path__c": "Casa e Cozinha",
  "Atonit_Mktplace__Matched_Category__r": {
    "Atonit_Mktplace__Marketplace_Id__c": "electronics" }
}
```

_Example: Match category with Marketplace category_

```
Match category with Marketplace category example: 

{
  "Atonit_Mktplace__Matched_Category__r": {
    "Atonit_Mktplace__Marketplace_Id__c": "electronics" }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 17:14:16 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1655/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Category__c/a005Y00002HSIoCQAX`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a005Y00002HSIoCQAX",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### GET Query

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Category__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-category-2`

Operation ID: `Query`. Tags: Category. Security: bearerAuth.

To look up information about categories, use the [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) resource of the main REST API from Salesforce and set the value of the `q` parameter to an SOQL query. The following example is included in the query parameters section of this page with a corresponding example in the responses section:

**Example 1 of 1**: `Get all Marketplace categories`

One piece of information that must be configured in a category is which marketplace category corresponds to it. This value must be one of the values from the marketplace (if none of them apply, contact the marketplace to check whether a new one can be inserted). This information can be uploaded via integration or using the categories match screen in the Seller Center.

In order to insert this relationship via integration, you must first request an export of the data to the marketplace or access the API directly and save the list. If the item limit is exceeded, pagination may be necessary, in which case please refer to the following [documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm#retrieve_remaining_results_title).

#### Parameters

*   `q` (query, string)
    
    _Example: Get all Marketplace categories_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__Category__c WHERE  RecordType.Name = 'Marketplace Category' AND Atonit_Mktplace__Is_Storefront__c = TRUE LIMIT 200
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 19:19:40 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1372/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example: Get all Marketplace categories_
    
    ```
    {
      "totalSize": 67,
      "done": true,
      "records": [
        {
          "Id": "a005Y00002HPaM6QAL",
          "Name": "iPod & MP3 Players",
          "CreatedDate": "2021-03-22T21:04:19.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:29.000+0000",
          "Atonit_Mktplace__Description__c": "Shop Digital Media Players including iPods, Creative Zen, Sony & the latest from all the top brands, makes and models at Commerce Cloud.",
          "Atonit_Mktplace__Is_Deleted__c": false,
          "Atonit_Mktplace__Is_Storefront__c": true,
          "Atonit_Mktplace__Marketplace_Id__c": "electronics-digital-media-players",
          "Atonit_Mktplace__Full_Path__c": "Eletrônicos >> iPod & MP3 Players"
        },
        {
          "Id": "a005Y00002HPaM7QAL",
          "Name": "Gaming",
          "CreatedDate": "2021-03-22T21:04:19.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:29.000+0000",
          "Atonit_Mktplace__Description__c": "Shop games and game consoles from Xbox, Xbox360, Playstation 2, Playstation 3, Game Cube, Wii, Playstation Portable and Nintento DS at Commerce Cloud.",
          "Atonit_Mktplace__Is_Deleted__c": false,
          "Atonit_Mktplace__Is_Storefront__c": true,
          "Atonit_Mktplace__Marketplace_Id__c": "electronics-gaming",
          "Atonit_Mktplace__Full_Path__c": "Eletrônicos >> Gaming"
        },
        {
          "Id": "a005Y00002HPaM8QAL",
          "Name": "GPS Navigation",
          "CreatedDate": "2021-03-22T21:04:19.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:29.000+0000",
          "Atonit_Mktplace__Description__c": "Shop the latest in GPS units from Garmin and Tom Tom along with other brands, makes and models at Commerce Cloud.",
          "Atonit_Mktplace__Is_Deleted__c": false,
          "Atonit_Mktplace__Is_Storefront__c": true,
          "Atonit_Mktplace__Marketplace_Id__c": "electronics-gps-units",
          "Atonit_Mktplace__Full_Path__c": "Eletrônicos >> GPS Navigation"
        }
      ]
    }
    ```
    

### PATCH Create or Update Child Category

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Category__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-category-2`

Operation ID: `Create or Update Child Category`. Tags: Category. Security: bearerAuth.

To create a category as a subcategory of another primary category, a parent category must be created. After this, it is possible to configure the parent when creating the subcategory by completing the field `Atonit_Mktplace__Parent_Category__r`, using the value of the External-ID to make the connection. The Full Path field is not required, but if completed, it will facilitate display of the full category path in the Seller Center.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Name": "Ferramentas",
  "Atonit_Mktplace__Is_Deleted__c": false,
  "Atonit_Mktplace__Description__c": "Ferramentas de construção",
  "Atonit_Mktplace__Full_Path__c": "Casa e Cozinha >> Ferramentas",
  "Atonit_Mktplace__Parent_Category__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-category-1"
  },
  "Atonit_Mktplace__Matched_Category__r": {
    "Atonit_Mktplace__Marketplace_Id__c": "electronics-accessories"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 17:16:06 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1669/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Category__c/a005Y00002HSIoMQAX`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a005Y00002HSIoMQAX",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### GET Get Category by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Category__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-category-2/get-category-by-id`

Operation ID: `Get Category by ID`. Tags: Category. Security: bearerAuth.

This call will upload all the available category information using the External ID as the key.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 17:16:32 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1670/101002`.
    *   `Last-Modified` (string)  
        Example: `Fri, 23 Apr 2021 17:16:06 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a005Y00002HSIoMQAX",
      "Name": "Ferramentas",
      "CreatedDate": "2021-04-22T17:14:59.000+0000",
      "LastModifiedDate": "2021-04-23T17:16:06.000+0000",
      "Atonit_Mktplace__Calculated_Marketplace_Id__c": null,
      "Atonit_Mktplace__Description__c": "Ferramentas de construção",
      "Atonit_Mktplace__Image_URL__c": null,
      "Atonit_Mktplace__Is_Deleted__c": false,
      "Atonit_Mktplace__Matched_Category__c": null,
      "Atonit_Mktplace__Parent_Category__c": "a005Y00002HSIoCQAX",
      "Atonit_Mktplace__Full_Path__c": "Casa e Cozinha >> Ferramentas",
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-category-2"
    }
    ```

<!-- document id=7fda4184cb3f3eff2790b56cc26eca3a83690ce8a3b58a1e2e0b2c1913b81cf8 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_controller_request.md -->

# ccdw_aggr_controller_request

This table aggregates daily performance metrics for pipeline requests.

> **Note:** This table is not constrained by IP Address Filters configured in Business Manager.

| Column Alias            | Data Type | Key    | Description                                              | Index? |
| ----------------------- | --------- | ------ | -------------------------------------------------------- | ------ |
| `request_date`          | DATE      |        | Date of the request.                                     | No     |
| `controller_name`       | VARCHAR   |        | Name of the pipeline/controller.                         | No     |
| `site_id`               | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md). | No     |
| `cache_behavior`        | VARCHAR   |        | Cache behavior of the request.                           | No     |
| `status_code`           | SMALLINT  |        | HTTP status code of the response.                        | No     |
| `num_requests`          | INTEGER   |        | Total number of requests.                                | No     |
| `response_time`         | NUMERIC   |        | Average response time for the requests.                  | No     |
| `num_requests_bucket1`  | INTEGER   |        | Number of requests in response time bucket 1.            | No     |
| `num_requests_bucket2`  | INTEGER   |        | Number of requests in response time bucket 2.            | No     |
| `num_requests_bucket3`  | INTEGER   |        | Number of requests in response time bucket 3.            | No     |
| `num_requests_bucket4`  | INTEGER   |        | Number of requests in response time bucket 4.            | No     |
| `num_requests_bucket5`  | INTEGER   |        | Number of requests in response time bucket 5.            | No     |
| `num_requests_bucket6`  | INTEGER   |        | Number of requests in response time bucket 6.            | No     |
| `num_requests_bucket7`  | INTEGER   |        | Number of requests in response time bucket 7.            | No     |
| `num_requests_bucket8`  | INTEGER   |        | Number of requests in response time bucket 8.            | No     |
| `num_requests_bucket9`  | INTEGER   |        | Number of requests in response time bucket 9.            | No     |
| `num_requests_bucket10` | INTEGER   |        | Number of requests in response time bucket 10.           | No     |
| `num_requests_bucket11` | INTEGER   |        | Number of requests in response time bucket 11.           | No     |

<!-- **Indices**: None listed -->

<!-- document id=5bc614252565a1735012d592e0bb669330ea7fa95a8a868a8dbafe254dd175af url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_detail_product_recommendation_recommender.md -->

# ccdw_aggr_detail_product_recommendation_recommender

Product-level recommendation performance by recommender algorithm for detailed analysis of which products perform best with specific recommendation engines.

| Column Alias             | Data Type | Key    | Description                                                                                  | Index? |
| ------------------------ | --------- | ------ | -------------------------------------------------------------------------------------------- | ------ |
| `recommendation_date`    | DATE      | **PK** | The date the product recommendations were shown.                                             | Yes    |
| `site_id`                | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) for site-specific analysis.          | Yes    |
| `recommender_name`       | VARCHAR   | **PK** | Name of the recommendation algorithm for algorithm-specific analysis.                        | Yes    |
| `product_id`             | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for product-specific analysis. | Yes    |
| `num_recommender_views`  | INTEGER   |        | Total number of recommendation widget impressions for this product and algorithm.            | No     |
| `num_product_views`      | INTEGER   |        | Total number of views of this specific product within recommendations.                       | No     |
| `num_clicks`             | INTEGER   |        | Total number of clicks on this product from this recommendation algorithm.                   | No     |
| `num_cart_adds`          | INTEGER   |        | Total number of add-to-cart actions for this product from recommendations.                   | No     |
| `num_products_purchased` | INTEGER   |        | Total number of times this product was purchased from recommendations.                       | No     |
| `num_orders`             | INTEGER   |        | Total number of orders containing this product from recommendations.                         | No     |
| `std_attributed_revenue` | NUMERIC   |        | Total revenue attributed to this product and recommendation algorithm in standard currency.  | No     |

<!-- **Indices**: None listed -->

<!-- document id=1deee830727d0af581529165800bc51a46418b140caf7710412285881a27bc57 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_impression.md -->

# ccdw_aggr_impression

This table aggregates product impression and click metrics.

| Column Alias        | Data Type | Key    | Description                                                                    | Index? |
| ------------------- | --------- | ------ | ------------------------------------------------------------------------------ | ------ |
| `impression_date`   | DATE      |        | Date of the impression activity.                                               | No     |
| `product_id`        | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the product. | No     |
| `nproduct_id`       | VARCHAR   |        | Natural key of the product in the source system.                               | No     |
| `impression_type`   | VARCHAR   |        | Type of product impression.                                                    | No     |
| `site_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                       | No     |
| `registered`        | BOOLEAN   |        | Boolean indicating if the user was registered.                                 | No     |
| `device_class_code` | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).   | No     |
| `locale_code`       | VARCHAR   | **FK** | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                 | No     |
| `num_impressions`   | INTEGER   |        | Total number of product impressions.                                           | No     |
| `num_clicks`        | INTEGER   |        | Total number of clicks on this product.                                        | No     |

<!-- **Indices**: None listed -->

<!-- document id=17b83e5c4250d6f626abb8d35cfa05f48ce05b04e43ad57ce2cbbbbc15d8a99a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_include_controller_request.md -->

# ccdw_aggr_include_controller_request

This table aggregates daily performance metrics for include pipeline requests.

> **Note:** This table is not constrained by IP Address Filters configured in Business Manager.

| Column Alias           | Data Type | Key    | Description                                              | Index? |
| ---------------------- | --------- | ------ | -------------------------------------------------------- | ------ |
| `request_date`         | DATE      |        | Date of the request.                                     | No     |
| `controller_name`      | VARCHAR   |        | Name of the include pipeline/controller.                 | No     |
| `main_controller_name` | VARCHAR   |        | Name of the main pipeline/controller.                    | No     |
| `site_id`              | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md). | No     |
| `cache_behavior`       | VARCHAR   |        | Cache behavior of the request.                           | No     |
| `status_code`          | SMALLINT  |        | HTTP status code of the response.                        | No     |
| `num_requests`         | INTEGER   |        | Total number of requests.                                | No     |
| `response_time`        | NUMERIC   |        | Average response time for the requests.                  | No     |

<!-- **Indices**: None listed -->

<!-- document id=11365c4ec2a0025a5efb4aff4c29755f5e91a6c513ac89335b540fd58486312b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_inventory_by_location.md -->

# ccdw_aggr_inventory_by_location

This table aggregates daily inventory levels by individual location.

| Column Alias           | Data Type | Key    | Description                                                                | Index? |
| ---------------------- | --------- | ------ | -------------------------------------------------------------------------- | ------ |
| `record_date`          | DATE      |        | Date of the inventory record.                                              | No     |
| `location_id`          | INTEGER   | **FK** | Foreign key to [`ccdw_dim_location`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location.md).           | No     |
| `sku_id`               | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the SKU. | No     |
| `available_to_fulfill` | INTEGER   |        | Total quantity available to fulfill orders at this location.               | No     |
| `available_to_order`   | INTEGER   |        | Total quantity available to be ordered at this location.                   | No     |
| `reserved`             | INTEGER   |        | Total quantity reserved at this location.                                  | No     |
| `soft_reserved`        | INTEGER   |        | Total quantity soft reserved at this location.                             | No     |
| `on_hand`              | INTEGER   |        | Total quantity on hand at this location.                                   | No     |

<!-- **Indices**: None listed -->

<!-- document id=047c96399ccd653a541773cf35a7329bb57772d1cea1a26845051f9411400775 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_inventory_by_location_group.md -->

# ccdw_aggr_inventory_by_location_group

This table aggregates daily inventory levels by location group.

| Column Alias           | Data Type | Key    | Description                                                                  | Index? |
| ---------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `record_date`          | DATE      |        | Date of the inventory record.                                                | No     |
| `location_group_id`    | INTEGER   | **FK** | Foreign key to [`ccdw_dim_location_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location_group.md). | No     |
| `sku_id`               | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the SKU.   | No     |
| `available_to_fulfill` | INTEGER   |        | Total quantity available to fulfill orders for this location group.          | No     |
| `available_to_order`   | INTEGER   |        | Total quantity available to be ordered for this location group.              | No     |
| `reserved`             | INTEGER   |        | Total quantity reserved for this location group.                             | No     |
| `soft_reserved`        | INTEGER   |        | Total quantity soft reserved for this location group.                        | No     |
| `on_hand`              | INTEGER   |        | Total quantity on hand for this location group.                              | No     |

<!-- **Indices**: None listed -->

<!-- document id=8f915cc3340d75d33ff4e800ba799adb2b3fd4af02331d3042cd35b8baf12c1a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_ocapi_request.md -->

# ccdw_aggr_ocapi_request

This table aggregates daily performance metrics for OCAPI requests.

> **Note:** This table is not constrained by IP Address Filters configured in Business Manager.

| Column Alias            | Data Type | Key    | Description                                              | Index? |
| ----------------------- | --------- | ------ | -------------------------------------------------------- | ------ |
| `request_date`          | DATE      |        | Date of the request.                                     | No     |
| `api_name`              | VARCHAR   |        | Name of the OCAPI API.                                   | No     |
| `api_resource`          | VARCHAR   |        | Specific OCAPI resource accessed.                        | No     |
| `api_version`           | VARCHAR   |        | Version of the OCAPI API.                                | No     |
| `site_id`               | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md). | No     |
| `client_id`             | VARCHAR   |        | Client identifier making the request.                    | No     |
| `status_code`           | SMALLINT  |        | HTTP status code of the response.                        | No     |
| `method`                | VARCHAR   |        | HTTP method used (for example, "GET", "POST").           | No     |
| `num_requests`          | INTEGER   |        | Total number of requests.                                | No     |
| `response_time`         | NUMERIC   |        | Average response time for the requests.                  | No     |
| `num_requests_bucket1`  | INTEGER   |        | Number of requests in response time bucket 1.            | No     |
| `num_requests_bucket2`  | INTEGER   |        | Number of requests in response time bucket 2.            | No     |
| `num_requests_bucket3`  | INTEGER   |        | Number of requests in response time bucket 3.            | No     |
| `num_requests_bucket4`  | INTEGER   |        | Number of requests in response time bucket 4.            | No     |
| `num_requests_bucket5`  | INTEGER   |        | Number of requests in response time bucket 5.            | No     |
| `num_requests_bucket6`  | INTEGER   |        | Number of requests in response time bucket 6.            | No     |
| `num_requests_bucket7`  | INTEGER   |        | Number of requests in response time bucket 7.            | No     |
| `num_requests_bucket8`  | INTEGER   |        | Number of requests in response time bucket 8.            | No     |
| `num_requests_bucket9`  | INTEGER   |        | Number of requests in response time bucket 9.            | No     |
| `num_requests_bucket10` | INTEGER   |        | Number of requests in response time bucket 10.           | No     |
| `num_requests_bucket11` | INTEGER   |        | Number of requests in response time bucket 11.           | No     |

<!-- **Indices**: None listed -->

<!-- document id=80110ad69772610f1341b7bee5bbcdb790910d4ce149be54d48f9ed9cf9086e7 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_payment_sales_summary.md -->

# ccdw_aggr_payment_sales_summary

This table summarizes payment-related sales metrics by various dimensions.

| Column Alias             | Data Type | Key    | Description                                                                                                                                                                                             | Index? |
| ------------------------ | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `submit_date`            | DATE      |        | Date of the sales submission.                                                                                                                                                                           | Yes    |
| `business_channel_id`    | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md).                                                                                                                        | Yes    |
| `registered`             | BOOLEAN   |        | Boolean indicating if the customer was registered.                                                                                                                                                      | Yes    |
| `site_id`                | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                                                                                                                                                | Yes    |
| `first_time_buyer`       | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established | Yes    |
| `first_time_buyer`       | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established. | Yes    |
| `locale_code`            | VARCHAR   |        | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                                                          | Yes    |
| `payment_method_id`      | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_payment_method`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_payment_method.md).                                                                                                                            | Yes    |
| `num_payments`           | INTEGER   |        | Total number of payments.                                                                                                                                                                               | No     |
| `num_orders`             | INTEGER   |        | Total number of orders associated with payments.                                                                                                                                                        | No     |
| `std_captured_amount`    | NUMERIC   |        | Total captured amount in standard currency.                                                                                                                                                             | No     |
| `std_refunded_amount`    | NUMERIC   |        | Total refunded amount in standard currency.                                                                                                                                                             | No     |
| `std_transaction_amount` | NUMERIC   |        | Total transaction amount in standard currency.                                                                                                                                                          | No     |

<!-- **Indices**: `submit_date,business_channel_id,registered,site_id,first_time_buyer,device_class_code, locale_code,payment_method_id` -->

<!-- document id=c45e148adb6086be5d7392fb7184e2d34bfd6f01b11384a9744f869a0b23ed04 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_product_cobuy.md -->

# ccdw_aggr_product_cobuy

This table identifies products that are frequently bought together.

| Column Alias        | Data Type | Key    | Description                                                                                                                                                                                              | Index? |
| ------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `submit_date`       | DATE      |        | Date of the co-buy event.                                                                                                                                                                                | Yes    |
| `product_one_id`    | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the first product.                                                                                                                     | Yes    |
| `product_two_id`    | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the second product.                                                                                                                    | Yes    |
| `order_channel`     | VARCHAR   |        | Order channel (from [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md)).                                                                                                                   | No     |
| `nsite_id`          | VARCHAR   |        | Normalized site ID (from [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md)).                                                                                                                                      | Yes    |
| `registered`        | BOOLEAN   |        | Boolean indicating if the customer was registered.                                                                                                                                                       | Yes    |
| `first_time_buyer`  | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established  | Yes    |
| `first_time_buyer`  | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established. | Yes    |
| `locale_code`       | VARCHAR   |        | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                                                           | Yes    |
| `frequency_count`   | INTEGER   |        | Number of times these two products were co-bought.                                                                                                                                                       | No     |
| `std_cobuy_revenue` | NUMERIC   |        | Total revenue generated from co-bought products in standard currency.                                                                                                                                    | No     |
| `traffic_medium`    | VARCHAR   |        | The traffic medium from [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md) `medium` (for example, "organic", "paid"). Historical rows can be null.                                             | No     |

<!-- **Indices**: `submit_date, product_one_id, product_two_id,registered, nsite_id,first_time_buyer,device_class_code,locale_code` -->

<!-- document id=a239cdebe14dcc5f6d9283c2642ec33c358a9999acc10cc0a7430b9da8681cf4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_product_recommendation.md -->

# ccdw_aggr_product_recommendation

This table aggregates overall product recommendation performance.

| Column Alias             | Data Type | Key    | Description                                                      | Index? |
| ------------------------ | --------- | ------ | ---------------------------------------------------------------- | ------ |
| `recommendation_date`    | DATE      |        | Date of the recommendation event.                                | No     |
| `site_id`                | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).         | No     |
| `num_recommender_views`  | INTEGER   |        | Total number of times recommenders were viewed.                  | No     |
| `num_product_views`      | INTEGER   |        | Total number of product views from recommenders.                 | No     |
| `num_clicks`             | INTEGER   |        | Total number of clicks on recommended products.                  | No     |
| `num_cart_adds`          | INTEGER   |        | Total number of products added to cart from recommenders.        | No     |
| `num_products_purchased` | INTEGER   |        | Total number of products purchased from recommenders.            | No     |
| `num_orders`             | INTEGER   |        | Total number of orders resulting from recommenders.              | No     |
| `std_attributed_revenue` | NUMERIC   |        | Total attributed revenue in standard currency from recommenders. | No     |

<!-- **Indices**: None listed -->

<!-- document id=a8cd34b6b490fdc07c44aecc4fb45d43af42fd6ae8e0b9e6f273b80b2cab8fa1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_product_recommendation_recommender.md -->

# ccdw_aggr_product_recommendation_recommender

This table aggregates product recommendation performance broken down by individual recommender.

| Column Alias             | Data Type | Key    | Description                                                           | Index? |
| ------------------------ | --------- | ------ | --------------------------------------------------------------------- | ------ |
| `recommendation_date`    | DATE      |        | Date of the recommendation event.                                     | No     |
| `site_id`                | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).              | No     |
| `recommender_name`       | VARCHAR   |        | Name of the specific recommender.                                     | No     |
| `num_recommender_views`  | INTEGER   |        | Total number of times this recommender was viewed.                    | No     |
| `num_product_views`      | INTEGER   |        | Total number of product views from this recommender.                  | No     |
| `num_clicks`             | INTEGER   |        | Total number of clicks on recommended products from this recommender. | No     |
| `num_cart_adds`          | INTEGER   |        | Total number of products added to cart from this recommender.         | No     |
| `num_products_purchased` | INTEGER   |        | Total number of products purchased from this recommender.             | No     |
| `num_orders`             | INTEGER   |        | Total number of orders resulting from this recommender.               | No     |
| `std_attributed_revenue` | NUMERIC   |        | Total attributed revenue in standard currency from this recommender.  | No     |

<!-- **Indices**: None listed -->

<!-- document id=0f3c79093f57ce4d094375e6e4d24aae7c8dade6302a20719f4711ddd222d41d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_product_sales_summary.md -->

# ccdw_aggr_product_sales_summary

This table summarizes product sales metrics by various dimensions. This table is aggregated from [`ccdw_fact_line_item`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_line_item.md)

| Column Alias               | Data Type | Key    | Description                                                                                                                                                                                              | Index? |
| -------------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `submit_date`              | DATE      |        | Date of the sales submission.                                                                                                                                                                            | Yes    |
| `business_channel_id`      | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md).                                                                                                                         | Yes    |
| `registered`               | BOOLEAN   |        | Boolean indicating if the customer was registered.                                                                                                                                                       | Yes    |
| `site_id`                  | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                                                                                                                                                 | Yes    |
| `first_time_buyer`         | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established  | Yes    |
| `first_time_buyer`         | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established. | Yes    |
| `product_id`               | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the product.                                                                                                                           | Yes    |
| `device_class_code`        | VARCHAR   |        | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                                             | Yes    |
| `locale_code`              | VARCHAR   |        | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                                                           | Yes    |
| `num_orders`               | INTEGER   |        | Total number of orders.                                                                                                                                                                                  | No     |
| `num_units`                | INTEGER   |        | Total number of units sold.                                                                                                                                                                              | No     |
| `std_revenue`              | NUMERIC   |        | Total revenue in standard currency. This column is aggregated from `std_li_gross_merchandise_value`.                                                                                                     | No     |
| `std_tax`                  | NUMERIC   |        | Total tax in standard currency.                                                                                                                                                                          | No     |
| `std_shipping`             | NUMERIC   |        | Total shipping cost in standard currency.                                                                                                                                                                | No     |
| `std_total_discount`       | NUMERIC   |        | Total discount in standard currency.                                                                                                                                                                     | No     |
| `std_promotional_discount` | NUMERIC   |        | Total promotional discount in standard currency.                                                                                                                                                         | No     |
| `traffic_medium`           | VARCHAR   |        | The traffic medium from [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md) `medium` (for example, "organic", "paid"). Historical rows can be null.                                             | No     |

<!-- **Indices**: `submit_date, business_channel_id,registered,site_id,first_time_buyer,sku_id, product_id, device_class_code,locale_code` -->

<!-- document id=bae5910d1c2136c411c1260c2b11ef273d922797b345ec9dab2aa3af96209854 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_promotion_activation.md -->

# ccdw_aggr_promotion_activation

This table summarizes promotion activation metrics.

| Column Alias        | Data Type | Key    | Description                                                                  | Index? |
| ------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `activation_date`   | DATE      |        | Date of promotion activation.                                                | No     |
| `site_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | No     |
| `device_class_code` | VARCHAR   |        | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | No     |
| `registered`        | BOOLEAN   |        | Boolean indicating if the user was registered.                               | No     |
| `locale_code`       | VARCHAR   |        | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | No     |
| `promotion_id`      | INTEGER   | **FK** | Foreign key to [`ccdw_dim_promotion`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_promotion.md).           | No     |
| `campaign_id`       | INTEGER   | **FK** | Foreign key to [`ccdw_dim_campaign`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_campaign.md).             | No     |
| `num_visits`        | INTEGER   |        | Number of visits associated with the promotion activation.                   | No     |
| `num_activations`   | INTEGER   |        | Total number of promotion activations.                                       | No     |

<!-- **Indices**: None listed -->

<!-- document id=5c7a09e16bf97a4e00705f7e23a5f0ea5dd55cf14818b1dc935db77811a6b421 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_promotion_cobuy.md -->

# ccdw_aggr_promotion_cobuy

Each row in this table represents a pair of promotions in the same purchases.

| Column Alias          | Data Type | Key    | Description                                                                                                                                                                                              | Index? |
| --------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `submit_date`         | DATE      | **PK** | The date the orders were submitted.                                                                                                                                                                      | Yes    |
| `promotion_one_id`    | INTEGER   | **FK** | Foreign key to [`ccdw_dim_promotion`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_promotion.md) for first promotion.                                                                                                                   | Yes    |
| `promotion_two_id`    | INTEGER   | **FK** | Foreign key to [`ccdw_dim_promotion`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_promotion.md) for second promotion.                                                                                                                  | Yes    |
| `promotion_one_class` | VARCHAR   | **PK** | The class of the first promotion (ex 'Shipping').                                                                                                                                                        | Yes    |
| `promotion_two_class` | VARCHAR   | **PK** | The class of the second promotion (ex 'Shipping').                                                                                                                                                       | Yes    |
| `order_channel`       | VARCHAR   | **PK** | Order channel designation.                                                                                                                                                                               | Yes    |
| `nsite_id`            | VARCHAR   | **PK** | Natural site identifier.                                                                                                                                                                                 | Yes    |
| `registered`          | BOOLEAN   | **PK** | true for records that represent register users, false otherwise.                                                                                                                                         | Yes    |
| `first_time_buyer`    | BOOLEAN   | **PK** | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established  | Yes    |
| `first_time_buyer`    | BOOLEAN   | **PK** | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established. | Yes    |
| `locale_code`         | VARCHAR   | **PK** | Locale code for language/region.                                                                                                                                                                         | Yes    |
| `frequency_count`     | BIGINT    |        | The frequency of occurrences between the two promotions.                                                                                                                                                 | No     |
| `traffic_medium`      | VARCHAR   |        | The traffic medium from [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md) `medium` (for example, "organic", "paid"). Historical rows can be null.                                             | No     |

<!-- **Indices**: None listed -->

<!-- document id=4123be1f72872126653b6d14cc722b7e288aabb0c40f8a3e657c1b6d2e78ea3b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_promotion_sales_summary.md -->

# ccdw_aggr_promotion_sales_summary

This table summarizes sales attributed to promotions by various dimensions. This table is aggregated from [`ccdw_fact_promotion_line_item`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_promotion_line_item.md).

| Column Alias            | Data Type | Key    | Description                                                                                                                                                                                              | Index? |
| ----------------------- | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `submit_date`           | DATE      |        | Date of the sales submission.                                                                                                                                                                            | Yes    |
| `business_channel_id`   | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md).                                                                                                                         | Yes    |
| `registered`            | BOOLEAN   |        | Boolean indicating if the customer was registered.                                                                                                                                                       | Yes    |
| `site_id`               | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                                                                                                                                                 | Yes    |
| `first_time_buyer`      | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established  | Yes    |
| `first_time_buyer`      | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established. | Yes    |
| `campaign_id`           | INTEGER   | **FK** | Foreign key to [`ccdw_dim_campaign`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_campaign.md).                                                                                                                                         | Yes    |
| `coupon_id`             | INTEGER   | **FK** | Foreign key to [`ccdw_dim_coupon`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_coupon.md).                                                                                                                                             | Yes    |
| `device_class_code`     | VARCHAR   |        | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                                             | Yes    |
| `locale_code`           | VARCHAR   |        | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                                                           | Yes    |
| `num_orders`            | INTEGER   |        | Total number of orders involving the promotion.                                                                                                                                                          | No     |
| `num_units`             | INTEGER   |        | Total number of units sold with the promotion.                                                                                                                                                           | No     |
| `std_revenue`           | NUMERIC   |        | Total revenue involving the promotion. This column is aggregated from `std_li_gross_merchandise_value`.                                                                                                  | No     |
| `std_tax`               | Numeric   |        | Total tax in standard currency attributed to the promotion.                                                                                                                                              | No     |
| `std_shipping`          | NUMERIC   |        | Total shipping cost in standard currency attributed to the promotion.                                                                                                                                    | No     |
| `num_promotion_uses`    | INTEGER   |        | Number of times the promotion was used.                                                                                                                                                                  | No     |
| `std_total_discount`    | NUMERIC   |        | Total discount in standard currency from the promotion.                                                                                                                                                  | No     |
| `std_item_discount`     | NUMERIC   |        | Item-level discount in standard currency from the promotion.                                                                                                                                             | No     |
| `std_order_discount`    | NUMERIC   |        | Order-level discount in standard currency from the promotion.                                                                                                                                            | No     |
| `std_shipping_discount` | NUMERIC   |        | Shipping discount in standard currency from the promotion.                                                                                                                                               | No     |
| `std_order_net`         | NUMERIC   |        | Net order value in standard currency after promotions.                                                                                                                                                   | No     |
| `std_shipping_net`      | NUMERIC   |        | Net shipping value in standard currency after promotions.                                                                                                                                                | No     |
| `std_discount`          | NUMERIC   |        | Total discount in standard currency.                                                                                                                                                                     | No     |
| `num_order_units`       | INTEGER   |        | Number of units associated with orders.                                                                                                                                                                  | No     |
| `traffic_medium`        | VARCHAR   |        | The traffic medium from [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md) `medium` (for example, "organic", "paid"). Historical rows can be null.                                             | No     |

<!-- **Indices**: `submit_date, business_channel_id,registered,site_id,first_time_buyer,promotion_id,campaign_id,coupon_id, device_class_code, locale_code` -->

<!-- document id=8251e0c21aa470fa2742c385ddd8bc24c0ab0f4103cd6982a04e03ce58d63112 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_registration.md -->

# ccdw_aggr_registration

This table summarizes customer registration activity.

| Column Alias        | Data Type | Key    | Description                                                                  | Index? |
| ------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `registration_date` | DATE      |        | Date of customer registration.                                               | Yes    |
| `site_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | Yes    |
| `locale_code`       | VARCHAR   |        | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | Yes    |
| `device_class_code` | VARCHAR   |        | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | Yes    |
| `num_registrations` | INTEGER   |        | Total number of customer registrations.                                      | No     |

<!-- **Indices**: `registration_date, site_id,locale_code, device_class_code` -->

<!-- document id=db59f7cd5d17561e72746413566a1ab63cd6a60bc8f847d2e8ec05bde9644591 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_sales_summary.md -->

# ccdw_aggr_sales_summary

This table provides a daily summary of sales metrics aggregated by various dimensions. This table is aggregated from [`ccdw_fact_line_item`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_line_item.md)

| Column Alias                        | Data Type | Key    | Description                                                                                                                                                                                             | Index? |
| ----------------------------------- | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `submit_date`                       | DATE      |        | Date of the sales submission.                                                                                                                                                                           | Yes    |
| `business_channel_id`               | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md).                                                                                                                        | Yes    |
| `registered`                        | BOOLEAN   |        | Boolean indicating if the customer was registered.                                                                                                                                                      | Yes    |
| `site_id`                           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                                                                                                                                                | Yes    |
| `first_time_buyer`                  | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established | Yes    |
| `device_class_code`                 | VARCHAR   |        | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                                            | Yes    |
| `locale_code`                       | VARCHAR   |        | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                                                          | Yes    |
| `num_orders`                        | INTEGER   |        | Total number of orders.                                                                                                                                                                                 | No     |
| `num_units`                         | INTEGER   |        | Total number of units sold.                                                                                                                                                                             | No     |
| `std_revenue`                       | NUMERIC   |        | Total revenue in standard currency. This column is aggregated from `std_li_gross_merchandise_value`                                                                                                     | No     |
| `std_tax`                           | NUMERIC   |        | Total tax in standard currency.                                                                                                                                                                         | No     |
| `std_shipping`                      | NUMERIC   |        | Total shipping cost in standard currency.                                                                                                                                                               | No     |
| `std_total_discount`                | NUMERIC   |        | Total discount in standard currency.                                                                                                                                                                    | No     |
| `std_promotional_order_discount`    | NUMERIC   |        | Promotional discount applied at the order level in standard currency.                                                                                                                                   | No     |
| `std_promotional_shipping_discount` | NUMERIC   |        | Promotional discount applied to shipping in standard currency.                                                                                                                                          | No     |
| `std_promotional_product_discount`  | NUMERIC   |        | Promotional discount applied to products in standard currency.                                                                                                                                          | No     |
| `std_manual_order_discount`         | NUMERIC   |        | Manual discount applied at the order level in standard currency.                                                                                                                                        | No     |
| `std_manual_shipping_discount`      | NUMERIC   |        | Manual discount applied to shipping in standard currency.                                                                                                                                               | No     |
| `std_manual_product_discount`       | NUMERIC   |        | Manual discount applied to products in standard currency.                                                                                                                                               | No     |
| `traffic_medium`                    | VARCHAR   |        | The traffic medium from [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md) `medium` (for example, "organic", "paid"). Historical rows can be null.                                            | No     |

<!-- **Indices**: `submit_date, business_channel_id,registered,site_id,first_time_buyer,device_class_code, locale_code` -->

<!-- document id=e39d7291bce3e6a93f324d7a9cc621a1395a148512db33420f624a55b1cb0b0d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_scapi_request.md -->

# ccdw_aggr_scapi_request

This table aggregates daily performance metrics for SCAPI requests.

> **Note:** This table is not constrained by IP Address Filters configured in Business Manager.

| Column Alias            | Data Type | Key    | Description                                              | Index? |
| ----------------------- | --------- | ------ | -------------------------------------------------------- | ------ |
| `request_date`          | DATE      |        | Date of the request.                                     | No     |
| `api_family`            | VARCHAR   |        | Family of the SCAPI API.                                 | No     |
| `api_name`              | VARCHAR   |        | Name of the SCAPI API.                                   | No     |
| `api_resource`          | VARCHAR   |        | Specific SCAPI resource accessed.                        | No     |
| `api_version`           | VARCHAR   |        | Version of the SCAPI API.                                | No     |
| `site_id`               | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md). | No     |
| `status_code`           | INTEGER   |        | HTTP status code of the response.                        | No     |
| `method`                | VARCHAR   |        | HTTP method used (for example, "GET", "POST").           | No     |
| `num_requests`          | INTEGER   |        | Total number of requests.                                | No     |
| `response_time`         | NUMERIC   |        | Average response time for the requests.                  | No     |
| `num_requests_bucket1`  | INTEGER   |        | Number of requests in response time bucket 1.            | No     |
| `num_requests_bucket2`  | INTEGER   |        | Number of requests in response time bucket 2.            | No     |
| `num_requests_bucket3`  | INTEGER   |        | Number of requests in response time bucket 3.            | No     |
| `num_requests_bucket4`  | INTEGER   |        | Number of requests in response time bucket 4.            | No     |
| `num_requests_bucket5`  | INTEGER   |        | Number of requests in response time bucket 5.            | No     |
| `num_requests_bucket6`  | INTEGER   |        | Number of requests in response time bucket 6.            | No     |
| `num_requests_bucket7`  | INTEGER   |        | Number of requests in response time bucket 7.            | No     |
| `num_requests_bucket8`  | INTEGER   |        | Number of requests in response time bucket 8.            | No     |
| `num_requests_bucket9`  | INTEGER   |        | Number of requests in response time bucket 9.            | No     |
| `num_requests_bucket10` | INTEGER   |        | Number of requests in response time bucket 10.           | No     |
| `num_requests_bucket11` | INTEGER   |        | Number of requests in response time bucket 11.           | No     |

<!-- **Indices**: None listed -->

<!-- document id=9deae00e849dd79716c40526dd69b095228ae8faa791129d4e56c49b2462e065 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_search.md -->

# ccdw_aggr_search

This table summarizes general search activity.

**note:** `ccdw_aggr_search` aggregates data directly from visits, while `ccdw_aggr_search_query` aggregates data specifically from search events. Because these tables track different events and methods, aggregating the `ccdw_aggr_search_query` table doesn't reproduce the same numerical results found in `ccdw_aggr_search`.

| Column Alias                   | Data Type | Key    | Description                                                                  | Index? |
| ------------------------------ | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `search_date`                  | DATE      |        | Date of the search activity.                                                 | Yes    |
| `site_id`                      | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | Yes    |
| `registered`                   | BOOLEAN   |        | Boolean indicating if the user was registered.                               | Yes    |
| `device_class_code`            | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | Yes    |
| `locale_code`                  | VARCHAR   | **FK** | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | Yes    |
| `num_searches_with_results`    | INTEGER   |        | Number of searches that yielded results.                                     | No     |
| `num_searches_without_results` | INTEGER   |        | Number of searches that yielded no results.                                  | No     |
| `num_results`                  | INTEGER   |        | Total number of search results returned.                                     | No     |
| `num_clicks`                   | INTEGER   |        | Total number of clicks on search results.                                    | No     |

<!-- **Indices**: `search_date, registered, site_id,device_class_code,locale_code` -->

<!-- document id=658d6212822515a3f7e080384d4ef35872548f674eaae22eb35039ff7b13fb84 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_search_conversion.md -->

# ccdw_aggr_search_conversion

This table tracks conversion rates related to search queries. Records are included only when one or more orders resulted from the search query. To calculate the search conversion rate for a query, divide the `num_orders` from this table by the total number of searches for that query from [`ccdw_aggr_search`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_aggr_search.md).

> **Note:** This table is constrained by IP Address Filters configured in Business Manager.

| Column Alias        | Data Type | Key    | Description                                                                  | Index? |
| ------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `search_date`       | DATE      |        | Date of the search activity.                                                 | Yes    |
| `site_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | Yes    |
| `registered`        | BOOLEAN   |        | Boolean indicating if the user was registered.                               | Yes    |
| `device_class_code` | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | Yes    |
| `locale_code`       | VARCHAR   | **FK** | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | Yes    |
| `query`             | VARCHAR   |        | The actual search query entered.                                             | Yes    |
| `has_results`       | BOOLEAN   |        | Boolean indicating if the search query yielded results.                      | No     |
| `num_searches`      | INTEGER   |        | Total number of searches for this query.                                     | No     |
| `num_visits`        | INTEGER   |        | Total number of visits associated with this query.                           | No     |
| `num_orders`        | INTEGER   |        | Total number of orders resulting from this query.                            | No     |
| `num_units`         | INTEGER   |        | Total number of units sold resulting from this query.                        | No     |
| `std_revenue`       | NUMERIC   |        | Total revenue in standard currency resulting from this query.                | No     |

<!-- **Indices**: `search_date,registered,site_id,device_class_code,locale_code,query` -->

<!-- document id=d6cdc3d7db099f1fcd4e701b986343528c8b748de9d76c80305ecab2f68454c1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_search_query.md -->

# ccdw_aggr_search_query

This table provides details on search queries and their outcomes.

> **Note:** This table is constrained by IP Address Filters configured in Business Manager.

**note:** `ccdw_aggr_search_query` aggregates data specifically from search events, while `ccdw_aggr_search` aggregates data directly from visits. Because these tables track different events and methods, aggregating the `ccdw_aggr_search_query` table doesn't reproduce the same numerical results found in `ccdw_aggr_search`.

| Column Alias                        | Data Type | Key    | Description                                                                  | Index? |
| ----------------------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `search_date`                       | DATE      |        | Date of the search activity.                                                 | Yes    |
| `site_id`                           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | Yes    |
| `registered`                        | BOOLEAN   |        | Boolean indicating if the user was registered.                               | Yes    |
| `device_class_code`                 | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | Yes    |
| `locale_code`                       | VARCHAR   | **FK** | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | Yes    |
| `query`                             | VARCHAR   |        | The actual search query entered.                                             | Yes    |
| `num_searches_with_results`         | INTEGER   |        | Number of searches for this query that yielded results.                      | No     |
| `num_searches_without_results`      | INTEGER   |        | Number of searches for this query that yielded no results.                   | No     |
| `num_results`                       | INTEGER   |        | Total number of search results returned for this query.                      | No     |
| `num_visits_with_search_results`    | INTEGER   |        | Number of visits that included searches with results.                        | No     |
| `num_visits_without_search_results` | INTEGER   |        | Number of visits that included searches without results.                     | No     |
| `num_clicks`                        | INTEGER   |        | Total number of clicks on search results for this query.                     | No     |

<!-- **Indices**: `search_date,registered,site_id,device_class_code,locale_code,query` -->

<!-- document id=d176baed5e2e872523fa2548dc10a78ffddec9d5c4bcb9b60425635cfe787919 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_source_code_activation.md -->

# ccdw_aggr_source_code_activation

This table summarizes the activation of source codes.

| Column Alias             | Data Type | Key    | Description                                                                        | Index? |
| ------------------------ | --------- | ------ | ---------------------------------------------------------------------------------- | ------ |
| `activation_date`        | DATE      |        | Date of source code activation.                                                    | No     |
| `registered`             | BOOLEAN   |        | Boolean indicating if the user was registered.                                     | No     |
| `site_id`                | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                           | No     |
| `device_class_code`      | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).       | No     |
| `source_code_group_id`   | INTEGER   | **FK** | Foreign key to [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md). | No     |
| `source_code_status`     | VARCHAR   |        | Status of the source code.                                                         | No     |
| `num_activations`        | INTEGER   |        | Total number of source code activations.                                           | No     |
| `num_source_codes`       | INTEGER   |        | Number of distinct source codes activated.                                         | No     |
| `num_source_code_groups` | INTEGER   |        | Number of distinct source code groups activated.                                   | No     |

<!-- **Indices**: None listed -->

<!-- document id=c954774b83d2c1d03c8aa0ece77a463828a4bea3bc9f289a4adfb93a973818c3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_source_code_sales.md -->

# ccdw_aggr_source_code_sales

This table summarizes sales attributed to source codes.

| Column Alias           | Data Type | Key    | Description                                                                                                                                                                                             | Index? |
| ---------------------- | --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `submit_date`          | DATE      |        | Date of the sales submission.                                                                                                                                                                           | No     |
| `business_channel_id`  | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md).                                                                                                                        | No     |
| `registered`           | BOOLEAN   |        | Boolean indicating if the customer was registered.                                                                                                                                                      | No     |
| `site_id`              | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                                                                                                                                                | No     |
| `first_time_buyer`     | BOOLEAN   |        | Boolean indicating if the customer was a first-time buyer across any site in the realm. Includes orders placed in sessions with tracking disabled (dw_dnt = 1) where buyer status cannot be established | No     |
| `device_class_code`    | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                                            | No     |
| `source_code_group_id` | INTEGER   | **FK** | Foreign key to [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md).                                                                                                                      | No     |
| `source_code_status`   | VARCHAR   |        | Status of the source code.                                                                                                                                                                              | No     |
| `num_orders`           | INTEGER   |        | Total number of orders attributed to the source code.                                                                                                                                                   | No     |
| `num_units`            | INTEGER   |        | Total number of units sold attributed to the source code.                                                                                                                                               | No     |
| `std_revenue`          | NUMERIC   |        | Total revenue in standard currency attributed to the source code.                                                                                                                                       | No     |

<!-- **Indices**: None listed -->

<!-- document id=2951d95027f34979550c67e5385b8bed6c0dddeb431314c8fda42f5c769bf752 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_visit.md -->

# ccdw_aggr_visit

This table summarizes website visit activity.

> **Note:** This table is constrained by IP Address Filters configured in Business Manager.

| Column Alias           | Data Type | Key    | Description                                                                                 | Index? |
| ---------------------- | --------- | ------ | ------------------------------------------------------------------------------------------- | ------ |
| `visit_date`           | DATE      |        | Date of the visit.                                                                          | No     |
| `site_id`              | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                                    | Yes    |
| `registered`           | BOOLEAN   |        | Boolean indicating if the visitor was registered.                                           | Yes    |
| `device_class_code`    | VARCHAR   | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                        | Yes    |
| `locale_code`          | VARCHAR   | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                | Yes    |
| `search_state`         | VARCHAR   |        | State of search activity during the visit (for example, "with_results", "without_results"). | Yes    |
| `num_visits`           | INTEGER   |        | Total number of visits.                                                                     | No     |
| `fvivisit_duration`    | NUMERIC   |        | Sum of visit durations.                                                                     | No     |
| `num_converted_visits` | INTEGER   |        | Number of visits that resulted in a conversion.                                             | No     |
| `num_orders`           | INTEGER   |        | Number of orders placed during visits.                                                      | No     |
| `num_units`            | INTEGER   |        | Number of units ordered during visits.                                                      | No     |
| `std_revenue`          | NUMERIC   |        | Gross merchandise value in standard currency during visits.                                 | No     |
| `num_baskets`          | INTEGER   |        | Number of visits where items were added to the basket.                                      | No     |
| `num_checkouts`        | INTEGER   |        | Number of visits where checkout was initiated.                                              | No     |

<!-- **Indices**: None listed -->

<!-- document id=024d51a5494840a4fec56e438f78bc932d9a4713fbe5567cacc1c434a331da2e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_visit_checkout.md -->

# ccdw_aggr_visit_checkout

This table summarizes visitor progression through checkout steps.

> **Note:** This table is constrained by IP Address Filters configured in Business Manager.

| Column Alias        | Data Type | Key    | Description                                                                  | Index? |
| ------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `visit_date`        | DATE      |        | Date of the visit.                                                           | No     |
| `site_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | No     |
| `registered`        | BOOLEAN   |        | Boolean indicating if the visitor was registered.                            | No     |
| `device_class_code` | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | No     |
| `locale_code`       | VARCHAR   | **FK** | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | No     |
| `step_number`       | INTEGER   |        | The numerical order of the checkout step.                                    | No     |
| `step_name`         | VARCHAR   |        | Name of the checkout step.                                                   | No     |
| `num_hits`          | INTEGER   |        | Number of hits on this checkout step.                                        | No     |
| `num_visits`        | INTEGER   |        | Number of visits that reached this checkout step.                            | No     |

<!-- **Indices**: None listed -->

<!-- document id=4b4d998946412dbdd4a53d345bab35150c569abdf0ba7ae558978b9a75029beb url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_visit_ip_address.md -->

# ccdw_aggr_visit_ip_address

This table summarizes visits by IP address.

> **Note:** This table contains robot traffic and is not constrained by IP Address Filters configured in Business Manager.

| Column Alias        | Data Type | Key    | Description                                                                  | Index? |
| ------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `visit_date`        | DATE      |        | Date of the visit.                                                           | No     |
| `site_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | No     |
| `registered`        | BOOLEAN   |        | Boolean indicating if the visitor was registered.                            | No     |
| `device_class_code` | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | No     |
| `locale_code`       | VARCHAR   | **FK** | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | No     |
| `ip_address`        | VARCHAR   |        | Masked IP address of the visitor.                                            | No     |
| `num_visits`        | INTEGER   |        | Total number of visits from this IP address.                                 | No     |

<!-- **Indices**: None listed -->

<!-- document id=c9ed3a6ed0217e55e8f82be7782ef66288e25a5a1023a0443ec9059160c7250f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_visit_referrer.md -->

# ccdw_aggr_visit_referrer

This table summarizes visits by referrer information.

> **Note:** This table is constrained by IP Address Filters configured in Business Manager.

| Column Alias        | Data Type | Key    | Description                                                                  | Index? |
| ------------------- | --------- | ------ | ---------------------------------------------------------------------------- | ------ |
| `visit_date`        | DATE      |        | Date of the visit.                                                           | No     |
| `site_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                     | No     |
| `registered`        | BOOLEAN   |        | Boolean indicating if the visitor was registered.                            | No     |
| `device_class_code` | VARCHAR   | **FK** | Device class code from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). | No     |
| `locale_code`       | VARCHAR   | **FK** | Locale code from [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).               | No     |
| `referrer_medium`   | VARCHAR   |        | The medium of the referrer (for example, "organic", "paid").                 | No     |
| `referrer_source`   | VARCHAR   |        | The source of the referrer (for example, "google", "facebook").              | No     |
| `num_visits`        | INTEGER   |        | Total number of visits from this referrer.                                   | No     |

<!-- **Indices**: None listed -->

<!-- document id=95722e5b7c34f26ac71220ca07747e9b5967e1ec6368d039df0065d185ac07a1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_visit_robot.md -->

# ccdw_aggr_visit_robot

This table summarizes visits identified as coming from robots/crawlers.

> **Note:** This table contains robot traffic and is not constrained by IP Address Filters configured in Business Manager.

| Column Alias         | Data Type | Key    | Description                                                                            | Index? |
| -------------------- | --------- | ------ | -------------------------------------------------------------------------------------- | ------ |
| `visit_date`         | DATE      |        | Date of the visit.                                                                     | No     |
| `site_id`            | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                               | No     |
| `registered`         | BOOLEAN   |        | Boolean indicating if the visitor was registered (likely false for robots).            | No     |
| `device_class_code`  | VARCHAR   | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                   | No     |
| `locale_code`        | VARCHAR   | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                           | No     |
| `ua_class`           | VARCHAR   |        | User agent classification (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)). | No     |
| `ua_family`          | VARCHAR   |        | User agent family (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).         | No     |
| `ua_engine`          | VARCHAR   |        | User agent engine (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).         | No     |
| `ua_os`              | VARCHAR   |        | Operating system (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).          | No     |
| `ua_os_family`       | VARCHAR   |        | Operating system family (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).   | No     |
| `device_class_code`  | VARCHAR   |        | Device class code (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).         | No     |
| `device_market_name` | VARCHAR   |        | Device market name (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).        | No     |
| `device_brand`       | VARCHAR   |        | Device brand (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).              | No     |
| `num_visits`         | INTEGER   |        | Total number of visits from this robot.                                                | No     |

<!-- **Indices**: None listed -->

<!-- document id=e092d1a8bed54881e357a5c1b9a83140db16281e13b53db80fcbe50b5940bad5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_aggr_visit_user_agent.md -->

# ccdw_aggr_visit_user_agent

This table summarizes visits by user agent details.

> **Note:** This table is constrained by IP Address Filters configured in Business Manager.

| Column Alias         | Data Type | Key    | Description                                                                            | Index? |
| -------------------- | --------- | ------ | -------------------------------------------------------------------------------------- | ------ |
| `visit_date`         | DATE      |        | Date of the visit.                                                                     | No     |
| `site_id`            | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                               | No     |
| `registered`         | BOOLEAN   |        | Boolean indicating if the visitor was registered.                                      | No     |
| `device_class_code`  | VARCHAR   | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                   | No     |
| `locale_code`        | VARCHAR   | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                           | No     |
| `ua_class`           | VARCHAR   |        | User agent classification (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)). | No     |
| `ua_family`          | VARCHAR   |        | User agent family (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).         | No     |
| `ua_engine`          | VARCHAR   |        | User agent engine (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).         | No     |
| `ua_os`              | VARCHAR   |        | Operating system (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).          | No     |
| `ua_os_family`       | VARCHAR   |        | Operating system family (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).   | No     |
| `device_class_code`  | VARCHAR   |        | Device class code (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).         | No     |
| `device_market_name` | VARCHAR   |        | Device market name (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).        | No     |
| `device_brand`       | VARCHAR   |        | Device brand (from [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)).              | No     |
| `num_visits`         | INTEGER   |        | Total number of visits for this user agent.                                            | No     |

<!-- **Indices**: None listed -->

<!-- document id=6213276ccd08ab69c28ef21d3d8f27c8200e6bf8b6b528f6354611780b64dffc url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_business_channel.md -->

# ccdw_dim_business_channel

This table categorizes different business channels.

| Column Alias               | Data Type | Key    | Description                                                                                       | Index? |
| -------------------------- | --------- | ------ | ------------------------------------------------------------------------------------------------- | ------ |
| `business_channel_id (PK)` | SMALLINT  | **PK** | Unique identifier for a business channel.                                                         | Yes    |
| `business_type`            | VARCHAR   |        | Type of business (for example, "B2C", "B2B").                                                     | Yes    |
| `order_channel`            | VARCHAR   |        | Channel through which an order was placed (for example, "Storefront", "Customer Service Center"). | Yes    |

<!-- **Indices**: `business_channel_id`, `business_type,order_channel` -->

<!-- document id=907712b1b9ea6893358b1d7d0c8afa832dbf5226bb146a01b127deee193c53e4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_campaign.md -->

# ccdw_dim_campaign

This table describes various marketing campaigns.

| Column Alias       | Data Type | Key    | Description                                                                            | Index? |
| ------------------ | --------- | ------ | -------------------------------------------------------------------------------------- | ------ |
| `campaign_id (PK)` | INTEGER   | **PK** | Unique identifier for a campaign.                                                      | Yes    |
| `ncampaign_id`     | VARCHAR   |        | Natural key of the campaign, representing the ID of the campaign in the source system. | Yes    |
| `description`      | VARCHAR   |        | Description of the campaign.                                                           | No     |
| `is_continuous`    | BOOLEAN   |        | Boolean indicating if the campaign is continuous.                                      | No     |
| `valid_from`       | TIMESTAMP |        | Start date and time when the campaign is valid.                                        | No     |
| `valid_to`         | TIMESTAMP |        | End date and time when the campaign is valid.                                          | No     |

<!-- **Indices**: `campaign_id`, `ncampaign_id` -->

<!-- document id=ee06ae87a4ec3830d4b8d113e49a077bf5f11dfbcdf001a18de787795ed6b2d3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_coupon.md -->

# ccdw_dim_coupon

This table provides details about coupons.

| Column Alias       | Data Type | Key    | Description                                                                        | Index? |
| ------------------ | --------- | ------ | ---------------------------------------------------------------------------------- | ------ |
| `coupon_id (PK)`   | INTEGER   | **PK** | Unique identifier for a coupon.                                                    | Yes    |
| `ncoupon_id`       | VARCHAR   |        | Natural key of the coupon, representing the ID of the coupon in the source system. | Yes    |
| `coupon_type`      | VARCHAR   |        | Type of coupon (for example, "Percentage", "Fixed Amount").                        | No     |
| `description`      | VARCHAR   |        | Description of the coupon.                                                         | No     |
| `is_enabled`       | BOOLEAN   |        | Boolean indicating if the coupon is enabled.                                       | No     |
| `redemption_limit` | INTEGER   |        | Maximum number of redemptions allowed per coupon code.                             | No     |
| `codes_count`      | INTEGER   |        | Total number of coupon codes available.                                            | No     |

<!-- **Indices**: `coupon_id`, `ncoupon_id` -->

<!-- document id=e6abda7ca863a04d1996dcf851bbcbfeac1dff90724d918dddb3b6de6dafbe40 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_currency.md -->

# ccdw_dim_currency

This table provides details about various currencies. Each row represents an ISO 4217 currency.

| Column Alias              | Data Type | Key    | Description                                                | Index? |
| ------------------------- | --------- | ------ | ---------------------------------------------------------- | ------ |
| `currency_id (PK)`        | SMALLINT  | **PK** | Unique identifier for a currency.                          | Yes    |
| `alpha_code`              | VARCHAR   |        | Alpha-3 code for the currency (for example, "USD", "EUR"). | Yes    |
| `display_name`            | VARCHAR   |        | User-friendly display name for the currency.               | No     |
| `numeric_code`            | INTEGER   |        | Numeric code for the currency.                             | No     |
| `symbol`                  | VARCHAR   |        | Symbol for the currency (for example, "\$", "€").          | No     |
| `default_fraction_digits` | SMALLINT  |        | Number of default fraction digits for the currency.        | No     |

<!-- **Indices**: `currency_id`, `alpha_code` -->

<!-- document id=3a87311e6043f6a3cf1260ba255c1894adc94cbdc3f5a9e39a1e039f149c4a56 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_customer.md -->

# ccdw_dim_customer

This table contains detailed information about registered customers. Unregistered buyers (guest checkouts) aren't included in this table. In fact tables, records for unregistered buyers have `customer_id = 1`, which can't be used to distinguish one unregistered buyer from another.

| Column Alias       | Data Type | Key    | Description                                                                            | Index? |
| ------------------ | --------- | ------ | -------------------------------------------------------------------------------------- | ------ |
| `customer_id (PK)` | BIGINT    | **PK** | Unique identifier for a customer.                                                      | Yes    |
| `ncustomer_id`     | VARCHAR   |        | Natural key of the customer, representing the ID of the customer in the source system. | Yes    |
| `login`            | VARCHAR   |        | Customer's login name or ID.                                                           | No     |
| `salutation`       | VARCHAR   |        | Customer's salutation (for example, "Mr.", "Ms.").                                     | No     |
| `title`            | VARCHAR   |        | Customer's title.                                                                      | No     |
| `job_title`        | VARCHAR   |        | Customer's job title.                                                                  | No     |
| `first_name`       | VARCHAR   |        | Customer's first name.                                                                 | No     |
| `second_name`      | VARCHAR   |        | Customer's middle name.                                                                | No     |
| `last_name`        | VARCHAR   |        | Customer's last name.                                                                  | No     |
| `suffix`           | VARCHAR   |        | Customer's name suffix.                                                                | No     |
| `gender`           | VARCHAR   |        | Customer's gender.                                                                     | No     |
| `dob`              | DATE      |        | Customer's date of birth.                                                              | No     |
| `email_address`    | VARCHAR   |        | Customer's email address.                                                              | No     |
| `phone_home`       | VARCHAR   |        | Customer's home phone number.                                                          | No     |
| `phone_business`   | VARCHAR   |        | Customer's business phone number.                                                      | No     |
| `phone_mobile`     | VARCHAR   |        | Customer's mobile phone number.                                                        | No     |
| `fax`              | VARCHAR   |        | Customer's fax number.                                                                 | No     |
| `repeat_buyer`     | BOOLEAN   |        | Boolean indicating if the customer is a repeat buyer.                                  | No     |
| `purchase_count`   | INTEGER   |        | Total number of purchases made by the customer.                                        | No     |

<!-- **Indices**: `customer_id`, `ncustomer_id` -->

<!-- document id=b7e96ed88be6daa385cf15d662e6c7fb333e35be95ec5d6c86c7f8793a529139 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_date.md -->

# ccdw_dim_date

This table contains various attributes related to dates, providing detailed temporal information. Each record represents a calendar date and its component parts (year, quarter, month, week, day).

| Column Alias            | Data Type | Key    | Description                                                        | Index? |
| ----------------------- | --------- | ------ | ------------------------------------------------------------------ | ------ |
| `day_id (PK)`           | SMALLINT  | **PK** | Unique identifier for a specific day.                              | Yes    |
| `day_timestamp`         | DATE      |        | Timestamp representing the start of the day.                       | Yes    |
| `day_of_year`           | SMALLINT  |        | Day number within the year (1-366).                                | No     |
| `day_of_month`          | SMALLINT  |        | Day number within the month (1-31).                                | Yes    |
| `day_of_week`           | SMALLINT  |        | Day number within the week (for example, 1 for Monday).            | No     |
| `day_of_week_short`     | VARCHAR   |        | Short name for the day of the week (for example, "Mon").           | No     |
| `day_of_week_long`      | VARCHAR   |        | Long name for the day of the week (for example, "Monday").         | No     |
| `day_display_name`      | VARCHAR   |        | User-friendly display name for the day.                            | No     |
| `week_id`               | SMALLINT  |        | Unique identifier for a specific week.                             | Yes    |
| `week_timestamp`        | DATE      |        | Timestamp representing the start of the week.                      | Yes    |
| `week_of_year`          | SMALLINT  |        | Week number within the year (1-53).                                | No     |
| `week_of_year_short`    | VARCHAR   |        | Short representation of the week of the year.                      | No     |
| `week_of_year_long`     | VARCHAR   |        | Long representation of the week of the year.                       | No     |
| `week_display_name`     | VARCHAR   |        | User-friendly display name for the week.                           | No     |
| `month_id`              | SMALLINT  |        | Unique identifier for a specific month.                            | Yes    |
| `month_timestamp`       | DATE      |        | Timestamp representing the start of the month.                     | Yes    |
| `month_of_year`         | SMALLINT  |        | Month number within the year (1-12).                               | Yes    |
| `month_of_year_short`   | VARCHAR   |        | Short representation of the month of the year.                     | No     |
| `month_of_year_long`    | VARCHAR   |        | Long representation of the month of the year (for example, 'Jan'). | No     |
| `month_display_name`    | VARCHAR   |        | User-friendly display name for the month (for example, 'January'). | No     |
| `quarter_id`            | SMALLINT  |        | Unique identifier for a specific quarter.                          | Yes    |
| `quarter_timestamp`     | DATE      |        | Timestamp representing the start of the quarter.                   | Yes    |
| `quarter_of_year`       | SMALLINT  |        | Quarter number within the year (1-4).                              | No     |
| `quarter_short`         | VARCHAR   |        | Short representation of the quarter.                               | No     |
| `quarter_long`          | VARCHAR   |        | Long representation of the quarter.                                | No     |
| `quarter_display_name`  | VARCHAR   |        | User-friendly display name for the quarter.                        | No     |
| `year_id`               | SMALLINT  |        | Unique identifier for a specific year.                             | Yes    |
| `year_timestamp`        | DATE      |        | Timestamp representing the start of the year.                      | Yes    |
| `year_of_era`           | SMALLINT  |        | Year number within its era.                                        | Yes    |
| `year_display_name`     | VARCHAR   |        | User-friendly display name for the year.                           | No     |
| `weekyear_id`           | SMALLINT  |        | Unique identifier for a specific week-year.                        | Yes    |
| `weekyear_timestamp`    | DATE      |        | Timestamp representing the start of the week-year.                 | Yes    |
| `weekyear_of_era`       | SMALLINT  |        | Week-year number within its era.                                   | No     |
| `weekyear_display_name` | VARCHAR   |        | User-friendly display name for the week-year.                      | No     |

<!-- **Indices**: `day_id`, `day_timestamp`, `week_id`, `week_timestamp`, `month_id`, `month_timestamp`, `quarter_id`, `quarter_timestamp`, `year_id`, `year_timestamp`, `weekyear_id`, `weekyear_timestamp`, `year_of_era,month_of_year,day_of_month` -->

<!-- document id=2f8d31f319977db24a93bece2dcaf34cdfbc6c33a97f46dcc51eb30b0ed7049b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_geography.md -->

# ccdw_dim_geography

This table provides geographical information, particularly for regions and countries. Each region rolls up to a country.

| Column Alias         | Data Type | Key    | Description                               | Index? |
| -------------------- | --------- | ------ | ----------------------------------------- | ------ |
| `geography_id (PK)`  | INTEGER   | **PK** | Unique identifier for a state or region.  | Yes    |
| `region_id`          | INTEGER   |        | Unique identifier for a state or region.  | No     |
| `region_code`        | VARCHAR   |        | Abbreviated code for the state or region. | No     |
| `region_name`        | VARCHAR   |        | Full name of the state or region.         | No     |
| `country_id`         | INTEGER   |        | Unique identifier for a country.          | No     |
| `country_code`       | VARCHAR   |        | Abbreviated code for the country.         | Yes    |
| `country_name`       | VARCHAR   |        | Full name of the country.                 | No     |
| `iso3166_alpha_code` | VARCHAR   |        | ISO 3166 alpha code for the country.      | Yes    |

<!-- **Indices**: `geography_id`, `iso3166_alpha_code`, `country_code` -->

<!-- document id=7b3b113547b9029e23e86f3fa3c65978160b4ace682ec508edf6540fbe36cec2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_locale.md -->

# ccdw_dim_locale

This table stores information about different locales, such as language and country settings.

| Column Alias     | Data Type | Key    | Description                                                   | Index? |
| ---------------- | --------- | ------ | ------------------------------------------------------------- | ------ |
| `locale_id (PK)` | SMALLINT  | **PK** | Unique identifier for a locale.                               | Yes    |
| `language`       | VARCHAR   |        | Language code (for example, "English", "French").             | No     |
| `country`        | VARCHAR   |        | Country code (for example, "United States", "Great Britain"). | No     |
| `locale_tag`     | VARCHAR   |        | Full locale tag (for example, "en-US").                       | No     |
| `locale_code`    | VARCHAR   |        | Abbreviated locale code.                                      | Yes    |
| `display_name`   | VARCHAR   |        | User-friendly display name for the locale.                    | No     |

<!-- **Indices**: `locale_id`, `locale_code` -->

<!-- document id=28dcfc37e04366dda380399a067bcc06f583a7e1f727c1b1f5eb44181e019545 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_location.md -->

# ccdw_dim_location

This table represents individual physical locations, likely for inventory or shipping.

| Column Alias       | Data Type | Key    | Description                       | Index? |
| ------------------ | --------- | ------ | --------------------------------- | ------ |
| `location_id (PK)` | INTEGER   | **PK** | Unique identifier for a location. | Yes    |
| `nlocation_id`     | VARCHAR   |        | Normalized location identifier.   | Yes    |

<!-- **Indices**: `location_id`, `nlocation_id` -->

<!-- document id=a6e6e724991ec70354a095996878c3fad4ad79c488b10eec555be7e8ce8b2667 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_location_group.md -->

# ccdw_dim_location_group

This table groups physical locations together.

| Column Alias             | Data Type | Key    | Description                             | Index? |
| ------------------------ | --------- | ------ | --------------------------------------- | ------ |
| `location_group_id (PK)` | INTEGER   | **PK** | Unique identifier for a location group. | Yes    |
| `nlocation_group_id`     | VARCHAR   |        | Normalized location group identifier.   | Yes    |

<!-- **Indices**: `location_group_id`, `nlocation_group_id` -->

<!-- document id=753aab4749c9b8ae69063c7fbe07e841f29eea9153058ffd993a6b65c833994c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_payment_method.md -->

# ccdw_dim_payment_method

This table lists available payment methods.

| Column Alias             | Data Type | Key    | Description                                        | Index? |
| ------------------------ | --------- | ------ | -------------------------------------------------- | ------ |
| `payment_method_id (PK)` | SMALLINT  | **PK** | Unique identifier for a payment method.            | Yes    |
| `npayment_method_id`     | VARCHAR   |        | Normalized payment method identifier.              | Yes    |
| `display_name`           | VARCHAR   |        | User-friendly display name for the payment method. | No     |

<!-- **Indices**: `payment_method_id`, `npayment_method_id` -->

<!-- document id=17c779a805db0040e7a0df955f554d4865c928122cb15c1c9480c6758e12acfd url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_product.md -->

# ccdw_dim_product

This table contains detailed information about products and SKUs. Each SKU rolls up to a product.

| Column Alias               | Data Type | Key    | Description                                                                          | Index? |
| -------------------------- | --------- | ------ | ------------------------------------------------------------------------------------ | ------ |
| `sku_id (PK)`              | INTEGER   | **PK** | Unique identifier for a Stock Keeping Unit (SKU).                                    | Yes    |
| `nsku_id`                  | VARCHAR   |        | Natural key of the SKU, representing the ID of the SKU in the source system.         | Yes    |
| `sku_display_name`         | VARCHAR   |        | User-friendly display name for the SKU.                                              | No     |
| `sku_upc_code`             | VARCHAR   |        | UPC (Universal Product Code) for the SKU.                                            | No     |
| `sku_ean_code`             | VARCHAR   |        | EAN (European Article Number) for the SKU.                                           | No     |
| `sku_brand`                | VARCHAR   |        | Brand name of the SKU.                                                               | No     |
| `sku_manufacture_name`     | VARCHAR   |        | Manufacturer's name for the SKU.                                                     | No     |
| `sku_manufacture_sku`      | VARCHAR   |        | Manufacturer's SKU for the product.                                                  | No     |
| `product_id`               | INTEGER   |        | Unique identifier for a product.                                                     | Yes    |
| `nproduct_id`              | VARCHAR   |        | Natural key of the product, representing the ID of the product in the source system. | Yes    |
| `product_display_name`     | VARCHAR   |        | User-friendly display name for the product.                                          | No     |
| `product_upc_code`         | VARCHAR   |        | UPC for the product.                                                                 | No     |
| `product_ean_code`         | VARCHAR   |        | EAN for the product.                                                                 | No     |
| `product_brand`            | VARCHAR   |        | Brand name of the product.                                                           | No     |
| `product_manufacture_name` | VARCHAR   |        | Manufacturer's name for the product.                                                 | No     |
| `product_manufacture_sku`  | VARCHAR   |        | Manufacturer's SKU for the product.                                                  | No     |
| `is_master`                | BOOLEAN   |        | Boolean indicating if it's a master product.                                         | No     |
| `is_bundle`                | BOOLEAN   |        | Boolean indicating if it's a product bundle.                                         | No     |

<!-- **Indices**: `sku_id`, `nsku_id`, `product_id`, `nproduct_id` -->

<!-- document id=46edc4ba239af226965e48a6044709d8f214822ecccf63744428200cb561380a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_promotion.md -->

# ccdw_dim_promotion

This table describes various promotions.

| Column Alias        | Data Type | Key    | Description                                                                                                       | Index? |
| ------------------- | --------- | ------ | ----------------------------------------------------------------------------------------------------------------- | ------ |
| `promotion_id (PK)` | INTEGER   | **PK** | Unique identifier for a promotion.                                                                                | Yes    |
| `npromotion_id`     | VARCHAR   |        | Natural key of the promotion, representing the ID of the promotion in the source system.                          | Yes    |
| `display_name`      | VARCHAR   |        | User-friendly display name for the promotion.                                                                     | No     |
| `promotion_class`   | VARCHAR   |        | Type or class of the promotion (for example, shipping, order, product).                                           | No     |
| `is_continuous`     | BOOLEAN   |        | Boolean indicating if the promotion is continuous.                                                                | No     |
| `valid_from`        | TIMESTAMP |        | Start date and time when the promotion is valid. Populated for promotions created or updated after February 2025. | No     |
| `valid_to`          | TIMESTAMP |        | End date and time when the promotion is valid. Populated for promotions created or updated after February 2025.   | No     |

<!-- **Indices**: `promotion_id`, `npromotion_id` -->

<!-- document id=365cf2a9ac1e66e4b1c1a40903ac4d6ef46c3841aef153c97a9856abdd8a38cf url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_site.md -->

# ccdw_dim_site

This table stores information about different e-commerce sites or storefronts.

| Column Alias        | Data Type | Key    | Description                                                       | Index? |
| ------------------- | --------- | ------ | ----------------------------------------------------------------- | ------ |
| `site_id (PK)`      | SMALLINT  | **PK** | Unique identifier for a site.                                     | Yes    |
| `nsite_id`          | VARCHAR   |        | The natural key of the site as represented in the source system.  | Yes    |
| `site_display_name` | VARCHAR   |        | User-friendly display name for the site.                          | No     |
| `site_sitezone`     | VARCHAR   |        | Normalized timezone for the site.                                 | No     |
| `site_currency`     | VARCHAR   |        | Alpha-3 currency code used by the site.                           | No     |
| `site_taxation`     | VARCHAR   |        | Taxation rules or status for the site (for example, gross/net).   | No     |
| `site_status`       | VARCHAR   |        | Current operational status of the site.                           | No     |
| `realm_id`          | SMALLINT  |        | Unique identifier for the realm the site belongs to.              | No     |
| `nrealm_id`         | VARCHAR   |        | The natural key of the realm as represented in the source system. | Yes    |
| `realm_timezone`    | VARCHAR   |        | Timezone of the realm.                                            | No     |
| `realm_currency`    | VARCHAR   |        | Alpha-3 currency code used by the realm.                          | No     |

<!-- **Indices**: `site_id`, `nsite_id,nrealm_id` -->

<!-- document id=e27835ac624d1549041e21e346a4d90095389a1a218329f32ee054d61e0928e8 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_source_code_group.md -->

# ccdw_dim_source_code_group

This table categorizes source code groups, often used for tracking marketing channels.

| Column Alias                | Data Type | Key    | Description                                | Index? |
| --------------------------- | --------- | ------ | ------------------------------------------ | ------ |
| `source_code_group_id (PK)` | INTEGER   | **PK** | Unique identifier for a source code group. | Yes    |
| `nsource_code_group_id`     | VARCHAR   |        | Normalized source code group identifier.   | Yes    |

<!-- **Indices**: `source_code_group_id`, `nsource_code_group_id` -->

<!-- document id=640b97e50e9a3e80ef8a3329ec4a2b0ecdb83eee6588526a17da99d5b26e0229 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_time.md -->

# ccdw_dim_time

This table contains various attributes related to time, providing detailed temporal information within a day. Each row represents a minute of a clock.

| Column Alias                  | Data Type | Key    | Description                                                                      | Index? |
| ----------------------------- | --------- | ------ | -------------------------------------------------------------------------------- | ------ |
| `time_id (PK)`                | SMALLINT  | **PK** | Unique identifier for a specific time.                                           | Yes    |
| `minute_of_day`               | SMALLINT  |        | Minute number within the day (0-1439).                                           | Yes    |
| `minute_of_hour`              | SMALLINT  |        | Minute number within the hour (0-59).                                            | No     |
| `hour_of_day`                 | SMALLINT  |        | Hour number within the day (0-23, 24-hour format).                               | Yes    |
| `hour_of_half_day`            | SMALLINT  |        | Hour number within the half-day (1-12).                                          | No     |
| `clock_hour_of_day`           | SMALLINT  |        | Clock hour within the day (1-24).                                                | No     |
| `clock_hour_of_halfday`       | SMALLINT  |        | Clock hour within the half-day (1-12).                                           | No     |
| `halfday_of_day`              | SMALLINT  |        | Indicator for AM/PM (for example, 0 for AM, 1 for PM).                           | No     |
| `halfday_of_day_display_name` | VARCHAR   |        | Display name for half-day (for example, "AM", "PM").                             | No     |
| `time_display_name_24hr`      | VARCHAR   |        | User-friendly display name for time in 24-hour format (for example, "14:30").    | No     |
| `time_display_name_12hr`      | VARCHAR   |        | User-friendly display name for time in 12-hour format (for example, "11:22 PM"). | No     |

<!-- **Indices**: `time_id`, `minute_of_day`, `hour_of_day` -->

<!-- document id=9ba7c12783336310235548406ce133793dd3d544fa83d7e0ae35e2cd3d0401e3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_timezone.md -->

# ccdw_dim_timezone

This table contains information about different time zones.

| Column Alias          | Data Type | Key    | Description                                                                | Index? |
| --------------------- | --------- | ------ | -------------------------------------------------------------------------- | ------ |
| `timezone_id (PK)`    | SMALLINT  | **PK** | Unique identifier for a time zone.                                         | Yes    |
| `ntimezone_id`        | VARCHAR   |        | Normalized time zone identifier.                                           | Yes    |
| `display_name`        | VARCHAR   |        | User-friendly display name for the time zone.                              | No     |
| `standard_time_short` | VARCHAR   |        | Short abbreviation for standard time (for example, "EST").                 | No     |
| `daylight_time_short` | VARCHAR   |        | Short abbreviation for daylight saving time (for example, "EDT").          | No     |
| `standard_time_long`  | VARCHAR   |        | Long name for standard time (for example, "Eastern Standard Time").        | No     |
| `daylight_time_long`  | VARCHAR   |        | Long name for daylight saving time (for example, "Eastern Daylight Time"). | No     |
| `utc_offset_millis`   | INTEGER   |        | Offset from UTC in milliseconds.                                           | No     |
| `observes_dst`        | BOOLEAN   |        | Boolean indicating if the time zone observes Daylight Saving Time.         | No     |
| `dst_savings_millis`  | INTEGER   |        | Daylight Saving Time savings in milliseconds.                              | No     |

<!-- **Indices**: `timezone_id`, `ntimezone_id` -->

<!-- document id=ef8239301b2399be74df32f21b292bce99cb7733f4618de57fc63898f546276d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_traffic_source.md -->

# ccdw_dim_traffic_source

This table describes attributed external traffic sources.

| Column Alias             | Data Type | Key    | Description                                             | Index? |
| ------------------------ | --------- | ------ | ------------------------------------------------------- | ------ |
| `traffic_source_id (PK)` | SMALLINT  | **PK** | Unique identifier for a traffic source.                 | Yes    |
| `source`                 | VARCHAR   |        | The traffic source (for example, "google", "facebook"). | No     |
| `medium`                 | VARCHAR   |        | The traffic medium (for example, "organic", "paid").    | No     |
| `channel_type`           | VARCHAR   |        | The channel classification for the traffic source.      | No     |

<!-- **Indices**: `traffic_source_id` -->

<!-- document id=35167d80fae9b8cede8f64ad1fe23de1bd628b45f84373f2bdf055dc6732f483 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_dim_user_agent.md -->

# ccdw_dim_user_agent

This table stores details about user agents, which describe the client software making a request.

| Column Alias            | Data Type | Key    | Description                                                                | Index? |
| ----------------------- | --------- | ------ | -------------------------------------------------------------------------- | ------ |
| `user_agent_id (PK)`    | INTEGER   | **PK** | Unique identifier for a user agent.                                        | Yes    |
| `nuser_agent_id`        | VARCHAR   |        | Normalized user agent identifier.                                          | Yes    |
| `ua_engine`             | VARCHAR   |        | Rendering engine of the user agent (for example, "WebKit", "Gecko").       | No     |
| `ua_version`            | VARCHAR   |        | Full version string of the user agent.                                     | No     |
| `ua_version_major`      | INTEGER   |        | Major version number of the user agent.                                    | No     |
| `ua_class`              | VARCHAR   |        | Classification of the user agent (for example, "Browser", "Crawler").      | No     |
| `ua_class_code`         | VARCHAR   |        | Code for the user agent classification.                                    | Yes    |
| `ua_family`             | VARCHAR   |        | Family name of the user agent (for example, "Chrome", "Firefox").          | No     |
| `ua_family_code`        | VARCHAR   |        | Code for the user agent family.                                            | Yes    |
| `ua_family_vendor`      | VARCHAR   |        | Vendor of the user agent family.                                           | No     |
| `ua_family_vendor_code` | VARCHAR   |        | Code for the user agent family vendor.                                     | Yes    |
| `crawler_category`      | VARCHAR   |        | Category of the crawler (if applicable).                                   | No     |
| `crawler_category_code` | VARCHAR   |        | Code for the crawler category.                                             | Yes    |
| `os_family`             | VARCHAR   |        | Operating system family (for example, "Windows", "macOS").                 | No     |
| `os_family_code`        | VARCHAR   |        | Code for the operating system family.                                      | Yes    |
| `os`                    | VARCHAR   |        | Specific operating system (for example, "Windows 10", "iOS").              | No     |
| `os_code`               | VARCHAR   |        | Code for the operating system.                                             | No     |
| `os_family_vendor`      | VARCHAR   |        | Vendor of the operating system family.                                     | No     |
| `os_family_vendor_code` | VARCHAR   |        | Code for the operating system family vendor.                               | Yes    |
| `device_class`          | VARCHAR   |        | Classification of the device (for example, "Desktop", "Mobile", "Tablet"). | No     |
| `device_class_code`     | VARCHAR   |        | Code for the device classification.                                        | Yes    |
| `device_market_name`    | VARCHAR   |        | Market name of the device (for example, "iPhone", "Galaxy S").             | No     |
| `device_brand`          | VARCHAR   |        | Brand of the device (for example, "Apple", "Samsung").                     | No     |
| `device_brand_code`     | VARCHAR   |        | Code for the device brand.                                                 | Yes    |

<!-- **Indices**: `user_agent_id`, `nuser_agent_id`, `ua_family_code`, `ua_class_code`, `ua_family_vendor_code`, `crawler_category_code`, `os_family_code`, `os_family_vendor_code`, `device_class_code`, `device_brand_code` -->

<!-- document id=779966f470f86b03af1030a88252c571e203801906e86b8f186502e340471249 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_customer_list_snapshot.md -->

# ccdw_fact_customer_list_snapshot

This table provides snapshots of customer list metrics over time.

| Column Alias                   | Data Type | Key    | Description                                                                                        | Index? |
| ------------------------------ | --------- | ------ | -------------------------------------------------------------------------------------------------- | ------ |
| `customer_list_record_id (PK)` | BIGINT    | **PK** | Unique identifier for a customer list snapshot record.                                             | No     |
| `ncustomer_list_id`            | VARCHAR   |        | Normalized customer list identifier.                                                               | No     |
| `utc_record_timestamp`         | TIMESTAMP |        | UTC timestamp of the snapshot.                                                                     | No     |
| `utc_record_day_id`            | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC record day.                    | No     |
| `utc_record_time_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC record time.                   | No     |
| `utc_update_timestamp`         | TIMESTAMP |        | Last modified UTC timestamp of this record.                                                        | Yes    |
| `std_record_timestamp`         | TIMESTAMP |        | Timestamp of the snapshot, in standard time.                                                       | No     |
| `std_record_day_id`            | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the standard record day.               | No     |
| `std_record_time_id`           | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the standard record time.              | No     |
| `std_record_timezone_id`       | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md) for the standard record time zone. | No     |
| `site_id`                      | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md).                                           | No     |
| `num_customers`                | INTEGER   |        | Total number of registered customers at the time of snapshot.                                      | No     |

<!-- document id=a4c660034c935f99352acee2abec411bd15f1d39eed17ea228e06c88d76a36b4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_customer_registration.md -->

# ccdw_fact_customer_registration

This table records customer registration events.

| Column Alias                   | Data Type | Key    | Description                                                                                                                                                            | Index? |
| ------------------------------ | --------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `registration_id (PK)`         | BIGINT    | **PK** | Unique identifier for a customer registration.                                                                                                                         | No     |
| `utc_registration_timestamp`   | TIMESTAMP |        | UTC timestamp of the registration.                                                                                                                                     | No     |
| `utc_registration_day_id`      | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC registration day.                                                                                  | No     |
| `utc_registration_time_id`     | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC registration time.                                                                                 | No     |
| `utc_update_timestamp`         | TIMESTAMP |        | Last modified UTC timestamp of this record.                                                                                                                            | Yes    |
| `std_registration_timestamp`   | TIMESTAMP |        | Timestamp of the registration, in standard time.                                                                                                                       | No     |
| `std_registration_day_id`      | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the standard registration day.                                                                             | No     |
| `std_registration_time_id`     | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the standard registration time.                                                                            | No     |
| `std_registration_timezone_id` | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md) for the standard registration time zone.                                                               | No     |
| `registration_site_id`         | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) where the registration occurred.                                                                               | No     |
| `visitor_id`                   | VARCHAR   |        | Unique identifier for a visitor session. This ID persists across sessions and is associated with an anonymous tracking cookie (for example, dwanonymous).              | No     |
| `customer_id`                  | BIGINT    | **FK** | Foreign key to [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md). For unregistered buyers, this value is `1` and can't distinguish one unregistered buyer from another. | No     |
| `locale_id`                    | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                           | No     |
| `user_agent_id`                | INTEGER   | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                   | No     |

<!-- document id=d6eb41e088f43fd4f0197e724715d68dccbc3b68c82007bf48db8f703f7d7e43 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_inventory_record_snapshot.md -->

# ccdw_fact_inventory_record_snapshot

This table captures daily snapshots of inventory levels. This table currently only represents data sourced from OCI.

| Column Alias                 | Data Type | Key    | Description                                                                      | Index? |
| ---------------------------- | --------- | ------ | -------------------------------------------------------------------------------- | ------ |
| `inventory_record_id`        | BIGINT    | **PK** | Unique identifier for an inventory record snapshot.                              | Yes    |
| `utc_record_timestamp`       | TIMESTAMP |        | UTC timestamp of the inventory record snapshot.                                  | Yes    |
| `utc_record_day_id`          | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC record day.  | Yes    |
| `utc_record_time_id`         | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC record time. | Yes    |
| `utc_update_timestamp`       | TIMESTAMP |        | Last modified UTC timestamp of this record.                                      | Yes    |
| `location_id`                | INTEGER   | **FK** | Foreign key to [`ccdw_dim_location`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location.md).                 | Yes    |
| `location_group_id`          | INTEGER   | **FK** | Foreign key to [`ccdw_dim_location_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location_group.md).     | Yes    |
| `sku_id`                     | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the SKU.       | Yes    |
| `available_to_fulfill_alloc` | NUMERIC   |        | Allocated quantity available to fulfill orders.                                  | No     |
| `available_to_order_alloc`   | NUMERIC   |        | Allocated quantity available to be ordered.                                      | No     |
| `on_hand_alloc`              | NUMERIC   |        | Allocated quantity currently on hand.                                            | No     |
| `reserved_alloc`             | NUMERIC   |        | Allocated quantity that is reserved.                                             | No     |
| `soft_reserved_alloc`        | NUMERIC   |        | Allocated quantity that is soft reserved.                                        | No     |
| `safety_stock_count_alloc`   | NUMERIC   |        | Allocated quantity for safety stock.                                             | No     |
| `available_to_fulfill`       | NUMERIC   |        | Total quantity available to fulfill orders.                                      | No     |
| `available_to_order`         | NUMERIC   |        | Total quantity available to be ordered.                                          | No     |
| `on_hand`                    | NUMERIC   |        | Total quantity currently on hand.                                                | No     |
| `reserved`                   | NUMERIC   |        | Total quantity that is reserved.                                                 | No     |
| `soft_reserved`              | NUMERIC   |        | Total quantity that is soft reserved.                                            | No     |
| `safety_stock_count`         | NUMERIC   |        | Total quantity for safety stock.                                                 | No     |
| `total_futures_quantity`     | NUMERIC   |        | Total quantity of future inventory.                                              | No     |

<!-- **Indices**: `inventory_record_id`, `utc_record_timestamp`, `utc_record_day_id`, `utc_record_time_id`, `location_id`, `location_group_id`, `sku_id` -->

<!-- document id=d2ffe3f5e4d7291dacb52bd57a8ab266226fbc101aca7344b436c45ee8548d2d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_inventory_record_snapshot_hourly.md -->

# ccdw_fact_inventory_record_snapshot_hourly

This table captures hourly snapshots of inventory levels. It contains similar fields to the daily snapshot but at a finer granularity. This table currently only represents data sourced from OCI.

| Column Alias                 | Data Type | Key    | Description                                                                      | Index? |
| ---------------------------- | --------- | ------ | -------------------------------------------------------------------------------- | ------ |
| `inventory_record_id (PK)`   | BIGINT    | **PK** | Unique identifier for an inventory record snapshot.                              | Yes    |
| `utc_record_timestamp`       | TIMESTAMP |        | UTC timestamp of the inventory record snapshot.                                  | Yes    |
| `utc_record_day_id`          | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC record day.  | Yes    |
| `utc_record_time_id`         | SMALLINT  | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC record time. | Yes    |
| `utc_update_timestamp`       | TIMESTAMP |        | Last modified UTC timestamp of this record.                                      | Yes    |
| `location_id`                | INTEGER   | **FK** | Foreign key to [`ccdw_dim_location`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location.md).                 | Yes    |
| `location_group_id`          | INTEGER   | **FK** | Foreign key to [`ccdw_dim_location_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location_group.md).     | Yes    |
| `sku_id`                     | INTEGER   | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the SKU.       | Yes    |
| `available_to_fulfill_alloc` | INTEGER   |        | Allocated quantity available to fulfill orders.                                  | No     |
| `available_to_order_alloc`   | INTEGER   |        | Allocated quantity available to be ordered.                                      | No     |
| `on_hand_alloc`              | INTEGER   |        | Allocated quantity currently on hand.                                            | No     |
| `reserved_alloc`             | INTEGER   |        | Allocated quantity that is reserved.                                             | No     |
| `soft_reserved_alloc`        | INTEGER   |        | Allocated quantity that is soft reserved.                                        | No     |
| `safety_stock_count_alloc`   | INTEGER   |        | Allocated quantity for safety stock.                                             | No     |
| `available_to_fulfill`       | INTEGER   |        | Total quantity available to fulfill orders.                                      | No     |
| `available_to_order`         | INTEGER   |        | Total quantity available to be ordered.                                          | No     |
| `on_hand`                    | INTEGER   |        | Total quantity currently on hand.                                                | No     |
| `reserved`                   | INTEGER   |        | Total quantity that is reserved.                                                 | No     |
| `soft_reserved`              | INTEGER   |        | Total quantity that is soft reserved.                                            | No     |
| `safety_stock_count`         | INTEGER   |        | Total quantity for safety stock.                                                 | No     |
| `total_futures_quantity`     | INTEGER   |        | Total quantity of future inventory.                                              | No     |

<!-- **Indices**: `inventory_record_id`, `utc_record_timestamp`, `utc_record_day_id`, `utc_record_time_id`, `location_id`, `location_group_id`, `sku_id` -->

<!-- document id=1c705bc604cde54e37dd0f3c9eeaf8889fa42cc7e3752f9de1e45a478b102b91 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_line_item.md -->

# ccdw_fact_line_item

This table captures details of individual line items within orders. Each row represents a line item in a placed order.

| Column Alias                     | Data Type    | Key    | Description                                                                                                                                                                                                                                                                                                 | Index? |
| -------------------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `line_item_id`                   | BIGINT       | **PK** | Unique identifier for the line item.                                                                                                                                                                                                                                                                        | Yes    |
| `nline_item_id`                  | VARCHAR(50)  |        | The natural key representing the line item in the source system.                                                                                                                                                                                                                                            | No     |
| `order_id`                       | BIGINT       | **FK** | A surrogate key representing the order associated with the line item.                                                                                                                                                                                                                                       | Yes    |
| `norder_id`                      | VARCHAR(50)  |        | The natural key representing the order in the source system.                                                                                                                                                                                                                                                | Yes    |
| `document_no`                    | VARCHAR(50)  |        | Document number associated with the order.                                                                                                                                                                                                                                                                  | No     |
| `utc_submit_timestamp`           | TIMESTAMP    |        | UTC timestamp when the line item was submitted.                                                                                                                                                                                                                                                             | Yes    |
| `utc_submit_day_id`              | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC submission day.                                                                                                                                                                                                                         | Yes    |
| `utc_submit_time_id`             | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC submission time.                                                                                                                                                                                                                        | No     |
| `utc_update_timestamp`           | TIMESTAMP    |        | Last modified UTC timestamp of this record.                                                                                                                                                                                                                                                                 | Yes    |
| `std_submit_timestamp`           | TIMESTAMP    |        | Timestamp when the line item was submitted, in standard time.                                                                                                                                                                                                                                               | No     |
| `std_submit_day_id`              | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the standard submission day.                                                                                                                                                                                                                    | Yes    |
| `std_submit_time_id`             | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the standard submission time.                                                                                                                                                                                                                   | No     |
| `std_timezone_id`                | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md) for the standard time zone.                                                                                                                                                                                                                 | No     |
| `sku_id`                         | INTEGER      | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the SKU.                                                                                                                                                                                                                                  | Yes    |
| `locale_id`                      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                                                                                                                                                                | Yes    |
| `site_id`                        | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) for the submission site.                                                                                                                                                                                                                            | Yes    |
| `business_channel_id`            | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md).                                                                                                                                                                                                                            | Yes    |
| `user_agent_id`                  | INTEGER      | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                                                                                                                                                        | Yes    |
| `source_code_group_id`           | INTEGER      | **FK** | Foreign key to [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md).                                                                                                                                                                                                                          | No     |
| `visitor_id`                     | VARCHAR(100) |        | Unique identifier for a visitor session. This ID persists across sessions and is associated with an anonymous tracking cookie (for example, dwanonymous).                                                                                                                                                   | No     |
| `customer_id`                    | BIGINT       | **FK** | Foreign key to [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md). For unregistered buyers, this value is `1` and can't distinguish one unregistered buyer from another.                                                                                                                                      | Yes    |
| `buyer_email`                    | VARCHAR(256) |        | Hashed email address of the buyer. If order was placed in session with tracking disabled (dw_dnt = 1) or shopper subsequently requested deletion of personal data, this will return `anonymous`                                                                                                             | No     |
| `is_anonymous`                   | BOOLEAN      |        | Indicates whether customer is anonymous or registered.                                                                                                                                                                                                                                                      | No     |
| `do_not_track`                   | BOOLEAN      |        | Indicates whether the customer has opted out of tracking.                                                                                                                                                                                                                                                   | No     |
| `lcl_currency_id`                | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_currency`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_currency.md) for local currency.                                                                                                                                                                                                                         | No     |
| `std_currency_id`                | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_currency`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_currency.md) for standard currency.                                                                                                                                                                                                                      | No     |
| `shipping_geography_id`          | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the shipping address provided at checkout. Populated for orders placed after October 2024.                                                                                                                                            | No     |
| `invoice_geography_id`           | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the billing or invoice address. Populated for orders placed after October 2024.                                                                                                                                                       | No     |
| `customer_geography_id`          | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the customer's profile address. Populated for registered customers only (orders placed after October 2024).                                                                                                                           | No     |
| `quantity`                       | NUMERIC      |        | The number of units of this line item that were purchased.                                                                                                                                                                                                                                                  | No     |
| `lcl_li_retail_price`            | NUMERIC      |        | Line item retail price in local currency.                                                                                                                                                                                                                                                                   | No     |
| `lcl_li_markdown`                | NUMERIC      |        | Line item markdown amount in local currency.                                                                                                                                                                                                                                                                | No     |
| `lcl_li_markdown_price`          | NUMERIC      |        | Line item markdown price in local currency.                                                                                                                                                                                                                                                                 | No     |
| `lcl_li_unit_price`              | NUMERIC      |        | The unit price, before promotional or manual discounts, associated with the line item.                                                                                                                                                                                                                      | No     |
| `lcl_li_markdown_disc`           | NUMERIC      |        | Line item markdown discount in local currency.                                                                                                                                                                                                                                                              | No     |
| `lcl_li_promo_disc`              | NUMERIC      |        | The line item promotional discounts associated with the line item.                                                                                                                                                                                                                                          | No     |
| `lcl_li_promo_disc_order_alloc`  | NUMERIC      |        | The order level promotional discounts associated with the line item (pro-rated).                                                                                                                                                                                                                            | No     |
| `lcl_li_promo_disc_ship_alloc`   | NUMERIC      |        | The line item shipping level promotional discounts associated with the line item (pro-rated).                                                                                                                                                                                                               | No     |
| `lcl_li_manual_disc`             | NUMERIC      |        | The line item manual discounts associated with the line item.                                                                                                                                                                                                                                               | No     |
| `lcl_li_manual_disc_order_alloc` | NUMERIC      |        | The order level manual discounts associated with the line item (pro-rated).                                                                                                                                                                                                                                 | No     |
| `lcl_li_manual_disc_ship_alloc`  | NUMERIC      |        | The shipping level manual discounts associated with the line item (pro-rated).                                                                                                                                                                                                                              | No     |
| `lcl_li_tax`                     | NUMERIC      |        | Line item tax in local currency.                                                                                                                                                                                                                                                                            | No     |
| `lcl_li_tax_order_alloc`         | NUMERIC      |        | The order level tax (pro-rated).                                                                                                                                                                                                                                                                            | No     |
| `lcl_li_shipping`                | NUMERIC      |        | The line item level shipping.                                                                                                                                                                                                                                                                               | No     |
| `lcl_li_shipping_order_alloc`    | NUMERIC      |        | The order level shipping (pro-rated).                                                                                                                                                                                                                                                                       | No     |
| `lcl_li_gross_merchandise_value` | NUMERIC      |        | The Gross Merchandise Value (GMV) of the line item in the tenderd currency. GMV is derived using the following row-based calculation `(quantity * lcl_li_unit_price) - ((lcl_li_promo_disc + lcl_li_manual_disc_order_alloc) + (lcl_li_manual_disc + lcl_li_manual_disc_order_alloc))`                      | No     |
| `lcl_li_net_merchandise_value`   | NUMERIC      |        | Line item net merchandise value in tenderd currency. This is derived using the following row-based calculation `lcl_li_gross_merchandise_value + (lcl_li_tax + lcl_li_tax_order_alloc) + (lcl_li_shipping + lcl_li_shipping_order_alloc) - (lcl_li_promo_disc_ship_alloc + lcl_li_manual_disc_ship_alloc)`  | No     |
| `std_li_retail_price`            | NUMERIC      |        | Line item retail price in standard currency.                                                                                                                                                                                                                                                                | No     |
| `std_li_markdown`                | NUMERIC      |        | Line item markdown amount in standard currency.                                                                                                                                                                                                                                                             | No     |
| `std_li_markdown_price`          | NUMERIC      |        | Line item markdown price in standard currency.                                                                                                                                                                                                                                                              | No     |
| `std_li_unit_price`              | NUMERIC      |        | The unit price, before promotional or manual discounts, associated with the line item.                                                                                                                                                                                                                      | No     |
| `std_li_markdown_disc`           | NUMERIC      |        | Line item markdown discount in standard currency.                                                                                                                                                                                                                                                           | No     |
| `std_li_promo_disc`              | NUMERIC      |        | The line item promotional discounts associated with the line item.                                                                                                                                                                                                                                          | No     |
| `std_li_promo_disc_order_alloc`  | NUMERIC      |        | The order level promotional discounts associated with the line item (pro-rated).                                                                                                                                                                                                                            | No     |
| `std_li_promo_disc_ship_alloc`   | NUMERIC      |        | The line item shipping level promotional discounts associated with the line item (pro-rated).                                                                                                                                                                                                               | No     |
| `std_li_manual_disc`             | NUMERIC      |        | The line item manual discounts associated with the line item.                                                                                                                                                                                                                                               | No     |
| `std_li_manual_disc_order_alloc` | NUMERIC      |        | The order level manual discounts associated with the line item (pro-rated).                                                                                                                                                                                                                                 | No     |
| `std_li_manual_disc_ship_alloc`  | NUMERIC      |        | The shipping level manual discounts associated with the line item (pro-rated).                                                                                                                                                                                                                              | No     |
| `std_li_tax`                     | NUMERIC      |        | The line item level tax.                                                                                                                                                                                                                                                                                    | No     |
| `std_li_tax_order_alloc`         | NUMERIC      |        | The order level tax (pro-rated).                                                                                                                                                                                                                                                                            | No     |
| `std_li_shipping`                | NUMERIC      |        | The line item level shipping.                                                                                                                                                                                                                                                                               | No     |
| `std_li_shipping_order_alloc`    | NUMERIC      |        | The order level shipping (pro-rated).                                                                                                                                                                                                                                                                       | No     |
| `std_li_gross_merchandise_value` | NUMERIC      |        | The Gross Merchandise Value (GMV) of the line item in the standard currency. GMV is derived using the following row-based calculation `(quantity * std_li_unit_price) - ((std_li_promo_disc + std_li_manual_disc_order_alloc) + (std_li_manual_disc + std_li_manual_disc_order_alloc))`                     | No     |
| `std_li_net_merchandise_value`   | NUMERIC      |        | Line item net merchandise value in standard currency. This is derived using the following row-based calculation `std_li_gross_merchandise_value + (std_li_tax + std_li_tax_order_alloc) + (std_li_shipping + std_li_shipping_order_alloc) - (std_li_promo_disc_ship_alloc + std_li_manual_disc_ship_alloc)` | No     |
| `traffic_source_id`              | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md). Identifies the attributed external traffic source for this order.                                                                                                                                                              | No     |
| `traffic_campaign`               | VARCHAR      |        | Campaign name associated with the attributed external traffic.                                                                                                                                                                                                                                              | No     |
| `referer_net_loc`                | VARCHAR      |        | Network location (hostname) of the referring site.                                                                                                                                                                                                                                                          | No     |
| `referer_term`                   | VARCHAR      |        | Search term from the referring site, when present.                                                                                                                                                                                                                                                          | No     |

<!-- **Indices**: `line_item_id`, `order_id`, `sku_id`, `std_submit_day_id`, `site_id`, `business_channel_id`, `norder_id`, `locale_id`, `user_agent_id`, `customer_id`, `utc_submit_timestamp`, `utc_submit_day_id` -->

<!-- document id=6dfee565aa4c76c49c441a7b71f4fa9396e85b1d87451a091417420d0b25d4c6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_order_payments.md -->

# ccdw_fact_order_payments

This table records payment transactions for orders. Each row represents an order payment.

| Column Alias             | Data Type    | Key    | Description                                                                                                                                                                                     | Index? |
| ------------------------ | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `order_payment_id`       | BIGINT       | **PK** | Unique identifier for the order payment record.                                                                                                                                                 | Yes    |
| `norder_id`              | VARCHAR(50)  |        | The natural key representing the order in the source system.                                                                                                                                    | Yes    |
| `utc_submit_timestamp`   | TIMESTAMP    |        | UTC timestamp when the payment was submitted.                                                                                                                                                   | No     |
| `utc_submit_day_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC submission day.                                                                                                             | No     |
| `utc_submit_time_id`     | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC submission time.                                                                                                            | No     |
| `utc_update_timestamp`   | TIMESTAMP    |        | Last modified UTC timestamp of this record.                                                                                                                                                     | Yes    |
| `std_submit_timestamp`   | TIMESTAMP    |        | Timestamp when the payment was submitted, in standard time.                                                                                                                                     | No     |
| `std_submit_day_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the standard submission day.                                                                                                        | Yes    |
| `std_submit_time_id`     | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the standard submission time.                                                                                                       | No     |
| `std_timezone_id`        | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md) for the standard time zone.                                                                                                     | No     |
| `locale_id`              | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                                                    | Yes    |
| `site_id`                | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) for the submission site.                                                                                                                | Yes    |
| `business_channel_id`    | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md).                                                                                                                | Yes    |
| `user_agent_id`          | INTEGER      | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                                            | Yes    |
| `source_code_group_id`   | INTEGER      | **FK** | Foreign key to [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md).                                                                                                              | No     |
| `payment_method_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_payment_method`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_payment_method.md).                                                                                                                    | Yes    |
| `visitor_id`             | VARCHAR(100) |        | Unique identifier for a visitor session. This ID persists across sessions and is associated with an anonymous tracking cookie (for example, dwanonymous).                                       | No     |
| `customer_id`            | BIGINT       | **FK** | Foreign key to [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md). For unregistered buyers, this value is `1` and can't distinguish one unregistered buyer from another.                          | Yes    |
| `buyer_email`            | VARCHAR(256) |        | Hashed email address of the buyer. If order was placed in session with tracking disabled (dw_dnt = 1) or shopper subsequently requested deletion of personal data, this will return `anonymous` | No     |
| `is_anonymous`           | BOOLEAN      |        | Indicates whether customer is anonymous or registered.                                                                                                                                          | No     |
| `do_not_track`           | BOOLEAN      |        | Indicates whether the customer has opted out of tracking.                                                                                                                                       | No     |
| `lcl_currency_id`        | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_currency`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_currency.md) for local currency.                                                                                                             | No     |
| `std_currency_id`        | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_currency`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_currency.md) for standard currency.                                                                                                          | No     |
| `shipping_geography_id`  | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the shipping address provided at checkout. Populated for orders placed after October 2024.                                | No     |
| `invoice_geography_id`   | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the billing or invoice address. Populated for orders placed after October 2024.                                           | No     |
| `customer_geography_id`  | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the customer's profile address. Populated for registered customers only (orders placed after October 2024).               | No     |
| `lcl_captured_amount`    | NUMERIC      |        | Captured amount in local currency.                                                                                                                                                              | No     |
| `lcl_refunded_amount`    | NUMERIC      |        | Refunded amount in local currency.                                                                                                                                                              | No     |
| `lcl_transaction_amount` | NUMERIC      |        | Transaction amount in local currency.                                                                                                                                                           | No     |
| `std_captured_amount`    | NUMERIC      |        | Captured amount in standard currency.                                                                                                                                                           | No     |
| `std_refunded_amount`    | NUMERIC      |        | Refunded amount in standard currency.                                                                                                                                                           | No     |
| `std_transaction_amount` | NUMERIC      |        | Transaction amount in standard currency.                                                                                                                                                        | No     |
| `traffic_source_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md). Identifies the attributed external traffic source for this order.                                                  | No     |
| `traffic_campaign`       | VARCHAR      |        | Campaign name associated with the attributed external traffic.                                                                                                                                  | No     |
| `referer_net_loc`        | VARCHAR      |        | Network location (hostname) of the referring site.                                                                                                                                              | No     |
| `referer_term`           | VARCHAR      |        | Search term from the referring site, when present.                                                                                                                                              | No     |

<!-- **Indices**: `order_payment_id`, `site_id`, `business_channel_id`, `payment_method_id`, `std_submit_day_id`, `locale_id`, `user_agent_id`, `norder_id`, `customer_id` -->

<!-- document id=92974aa6550bb2270a54920ffc5185723b034e045f246feab7104d78fa33e37c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_promotion_activation.md -->

# ccdw_fact_promotion_activation

This table records instances where promotions are activated.

| Column Alias                 | Data Type    | Key    | Description                                                                                                                                                            | Index? |
| ---------------------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `promotion_activation_id`    | BIGINT       | **PK** | Unique identifier for a promotion activation event.                                                                                                                    | Yes    |
| `utc_activation_timestamp`   | TIMESTAMP    |        | UTC timestamp of the promotion activation.                                                                                                                             | Yes    |
| `utc_activation_day_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC activation day.                                                                                    | Yes    |
| `utc_activation_time_id`     | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC activation time.                                                                                   | No     |
| `utc_update_timestamp`       | TIMESTAMP    |        | Last modified UTC timestamp of this record.                                                                                                                            | Yes    |
| `std_activation_timestamp`   | TIMESTAMP    |        | Timestamp of the promotion activation, in standard time.                                                                                                               | No     |
| `std_activation_day_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the standard activation day.                                                                               | Yes    |
| `std_activation_time_id`     | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the standard activation time.                                                                              | No     |
| `std_activation_timezone_id` | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md) for the standard activation time zone.                                                                 | No     |
| `promotion_id`               | INTEGER      | **FK** | Foreign key to [`ccdw_dim_promotion`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_promotion.md).                                                                                                     | Yes    |
| `campaign_id`                | INTEGER      | **FK** | Foreign key to [`ccdw_dim_campaign`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_campaign.md).                                                                                                       | Yes    |
| `activation_site_id`         | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) where the promotion was activated.                                                                             | Yes    |
| `visitor_id`                 | VARCHAR(100) |        | Unique identifier for a visitor session. This ID persists across sessions and is associated with an anonymous tracking cookie (for example, dwanonymous).              | No     |
| `customer_id`                | BIGINT       | **FK** | Foreign key to [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md). For unregistered buyers, this value is `1` and can't distinguish one unregistered buyer from another. | Yes    |
| `is_anonymous`               | BOOLEAN      |        | Indicates whether customer is anonymous or registered.                                                                                                                 | No     |
| `locale_id`                  | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                           | Yes    |
| `user_agent_id`              | INTEGER      | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                   | Yes    |

<!-- **Indices**: `promotion_activation_id`, `promotion_id`, `campaign_id`, `std_activation_day_id`, `activation_site_id`, `locale_id`, `user_agent_id`, `customer_id`, `utc_activation_timestamp`, `utc_activation_day_id` -->

<!-- document id=48bf71354dc585c63715e40a587b33316cc1d1db638d0b290d8b6b58f1065062 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_promotion_line_item.md -->

# ccdw_fact_promotion_line_item

This table records the application of promotions to individual line items. Each row represents a promotion line item in an order.

| Column Alias                     | Data Type    | Key    | Description                                                                                                                                                                                     | Index? |
| -------------------------------- | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `promotion_line_item_id`         | BIGINT       | **PK** | Surrogate key uniquely identifying this promotion line item. Use for joins and deduplication.                                                                                                   | Yes    |
| `promotion_id`                   | INTEGER      | **FK** | Foreign key to [`ccdw_dim_promotion`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_promotion.md). Use for promotion-level reporting and attribution.                                                                           | Yes    |
| `sku_id`                         | INTEGER      | **FK** | Foreign key to [`ccdw_dim_product`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md) for the SKU affected by the promotion. Use for product- or SKU-level promotion analysis.                                          | Yes    |
| `promotion_instance_id`          | VARCHAR(50)  |        | Unique key for one application of a promotion within an order. A single order-level promotion can generate multiple instances (one per qualifying line).                                        | No     |
| `line_item_id`                   | BIGINT       | **FK** | Foreign key to [`ccdw_fact_line_item`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_line_item.md). Links to the fact line item for quantity, unit price, and other line-level details.                                        | No     |
| `nline_item_id`                  | VARCHAR(50)  |        | Natural key for the line item in the source system, for example, OCAPI/SCAPI line item identifier). Normalized for cross-system use.                                                            | No     |
| `order_id`                       | BIGINT       | **FK** | Surrogate key for the order. Use to join with [`ccdw_fact_line_item`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_line_item.md) and other order-level facts.                                                                 | Yes    |
| `norder_id`                      | VARCHAR(50)  |        | Natural key for the order in the source system, for example, order number or document ID).                                                                                                      | No     |
| `utc_submit_timestamp`           | TIMESTAMP    |        | UTC timestamp when the promotion was applied to the line item. Use for exact-time filtering and incremental loads.                                                                              | Yes    |
| `utc_submit_day_id`              | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC submission day. Use for UTC-based date partitioning and calendar joins.                                                     | Yes    |
| `utc_submit_time_id`             | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC submission time. Use for time-of-day analysis in UTC.                                                                       | No     |
| `utc_update_timestamp`           | TIMESTAMP    |        | Last modified UTC timestamp for this record. Use for incremental loads or change detection.                                                                                                     | Yes    |
| `std_submit_timestamp`           | TIMESTAMP    |        | Timestamp when the promotion was applied, expressed in the realm's standard (reporting) time zone.                                                                                              | No     |
| `std_submit_day_id`              | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the standard submission day. Use for reporting-date partitioning and day-level reporting.                                           | Yes    |
| `std_submit_time_id`             | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the standard submission time. Use for time-of-day analysis in reporting time zone.                                                  | No     |
| `std_timezone_id`                | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md) for the time zone used to derive `std_submit_*` date and time columns (realm reporting time zone).                              | No     |
| `locale_id`                      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md) (language and country). Represents the session locale when the promotion was applied.                                               | Yes    |
| `site_id`                        | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) for the site where the order was placed (submission site).                                                                              | Yes    |
| `business_channel_id`            | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_business_channel`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md), for example, storefront, call center). Use for channel-level reporting.                                        | Yes    |
| `user_agent_id`                  | INTEGER      | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md). Represents device or browser context when the promotion was applied.                                                       | Yes    |
| `campaign_id`                    | INTEGER      | **FK** | Foreign key to [`ccdw_dim_campaign`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_campaign.md) for the marketing campaign associated with this promotion, if any. Nullable.                                                    | No     |
| `source_code_group_id`           | INTEGER      | **FK** | Foreign key to [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md). Use for source code or affiliate attribution. Nullable.                                                      | No     |
| `coupon_id`                      | INTEGER      | **FK** | Foreign key to [`ccdw_dim_coupon`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_coupon.md) for the coupon applied with this promotion line item, if any. Null when no coupon was used.                                         | No     |
| `visitor_id`                     | VARCHAR(100) |        | Anonymous or persistent visitor identifier from the session. Use for visit-level or anonymous-user analysis.                                                                                    | No     |
| `customer_id`                    | BIGINT       | **FK** | Foreign key to [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md). Use for customer-level promotion analysis. Might reference guest or registered customer.                                       | Yes    |
| `buyer_email`                    | VARCHAR(256) |        | Hashed email address of the buyer. If order was placed in session with tracking disabled (dw_dnt = 1) or shopper subsequently requested deletion of personal data, this will return `anonymous` | No     |
| `is_anonymous`                   | BOOLEAN      |        | Indicates whether customer is anonymous or registered.                                                                                                                                          | No     |
| `do_not_track`                   | BOOLEAN      |        | Indicates whether the customer has opted out of tracking.                                                                                                                                       | No     |
| `lcl_currency_id`                | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_currency`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_currency.md) for the tendered (local) currency—the currency in which the order was placed.                                                   | No     |
| `std_currency_id`                | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_currency`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_currency.md) for the realm's reporting currency. All `std_*` monetary values in this row are converted to this currency.                     | No     |
| `shipping_geography_id`          | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the shipping address (region/country). Use for geographic reporting.                                                      | No     |
| `invoice_geography_id`           | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the invoice or billing address (region/country).                                                                          | No     |
| `customer_geography_id`          | INTEGER      | **FK** | Foreign key to [`ccdw_dim_geography`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md) for the customer's address (region/country).                                                                                  | No     |
| `quantity`                       | NUMERIC      |        | Number of units of the line item to which this promotion application applies (quantity purchased for this line).                                                                                | No     |
| `lcl_li_promo_disc`              | NUMERIC      |        | Line-item-level promotional discount amount in tendered (local) currency.                                                                                                                       | No     |
| `lcl_li_promo_disc_order_alloc`  | NUMERIC      |        | Portion of an order-level promotional discount allocated to this line item (prorated), in tendered currency.                                                                                    | No     |
| `lcl_li_promo_disc_ship_alloc`   | NUMERIC      |        | Portion of a shipping-level promotional discount allocated to this line item (prorated), in tendered currency.                                                                                  | No     |
| `lcl_li_manual_disc`             | NUMERIC      |        | Line-item-level manual discount amount in tendered (local) currency.                                                                                                                            | No     |
| `lcl_li_manual_disc_order_alloc` | NUMERIC      |        | Portion of an order-level manual discount allocated to this line item (prorated), in tendered currency.                                                                                         | No     |
| `lcl_li_manual_disc_ship_alloc`  | NUMERIC      |        | Portion of a shipping-level manual discount allocated to this line item (prorated), in tendered currency.                                                                                       | No     |
| `lcl_li_tax`                     | NUMERIC      |        | Line-item-level tax amount in tendered (local) currency.                                                                                                                                        | No     |
| `lcl_li_tax_order_alloc`         | NUMERIC      |        | Portion of order-level tax allocated to this line item (prorated), in tendered currency.                                                                                                        | No     |
| `lcl_li_shipping`                | NUMERIC      |        | Line-item-level shipping charge in tendered (local) currency.                                                                                                                                   | No     |
| `lcl_li_shipping_order_alloc`    | NUMERIC      |        | Portion of order-level shipping allocated to this line item (prorated), in tendered currency.                                                                                                   | No     |
| `lcl_li_gross_merchandise_value` | NUMERIC      |        | Gross Merchandise Value (GMV) of the line item in tendered currency allocated to the promotion line item.                                                                                       | No     |
| `std_li_promo_disc`              | NUMERIC      |        | Line-item-level promotional discount in standard (reporting) currency. Converted from tendered currency for cross-currency reporting.                                                           | No     |
| `std_li_promo_disc_order_alloc`  | NUMERIC      |        | Portion of order-level promotional discount allocated to this line item (prorated), in standard reporting currency.                                                                             | No     |
| `std_li_promo_disc_ship_alloc`   | NUMERIC      |        | Portion of shipping-level promotional discount allocated to this line item (prorated), in standard reporting currency.                                                                          | No     |
| `std_li_manual_disc`             | NUMERIC      |        | Line-item-level manual discount in standard (reporting) currency. Converted from tendered currency.                                                                                             | No     |
| `std_li_manual_disc_order_alloc` | NUMERIC      |        | Portion of order-level manual discount allocated to this line item (prorated), in standard reporting currency.                                                                                  | No     |
| `std_li_manual_disc_ship_alloc`  | NUMERIC      |        | Portion of shipping-level manual discount allocated to this line item (prorated), in standard reporting currency.                                                                               | No     |
| `std_li_tax`                     | NUMERIC      |        | Line-item-level tax in standard (reporting) currency. Converted from tendered currency.                                                                                                         | No     |
| `std_li_tax_order_alloc`         | NUMERIC      |        | Portion of order-level tax allocated to this line item (prorated), in standard reporting currency.                                                                                              | No     |
| `std_li_shipping`                | NUMERIC      |        | Line-item-level shipping charge in standard (reporting) currency. Converted from tendered currency.                                                                                             | No     |
| `std_li_shipping_order_alloc`    | NUMERIC      |        | Portion of order-level shipping allocated to this line item (prorated), in standard reporting currency.                                                                                         | No     |
| `std_li_gross_merchandise_value` | NUMERIC      |        | Gross Merchandise Value (GMV) of the line item in standard currency allocated to the promotion line item.                                                                                       | No     |
| `traffic_source_id`              | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_traffic_source`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md). Identifies the attributed external traffic source for this order.                                                  | No     |
| `traffic_campaign`               | VARCHAR      |        | Campaign name associated with the attributed external traffic.                                                                                                                                  | No     |
| `referer_net_loc`                | VARCHAR      |        | Network location (hostname) of the referring site.                                                                                                                                              | No     |
| `referer_term`                   | VARCHAR      |        | Search term from the referring site, when present.                                                                                                                                              | No     |

<!-- document id=f24068757442e68871a9a178f763e876c42f7b77e685450b795129aaaf69c4fe url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_realtime_metric.md -->

# ccdw_fact_realtime_metric

This table captures real time metrics.

| Column Alias   | Data Type    | Key    | Description                                     | Index? |
| -------------- | ------------ | ------ | ----------------------------------------------- | ------ |
| `metric_id`    | BIGINT       | **PK** | Unique identifier for real time metrics.        | Yes    |
| `metric_name`  | VARCHAR(100) |        | Name given to the real time metric.             | Yes    |
| `metric_value` | NUMERIC      |        | Value associated with the real time metric.     | No     |
| `create_date`  | TIMESTAMP    |        | Timestamp associated with the real time metric. | Yes    |

<!-- **Indices**: `metric_id`, `metric_name,create_date` -->

<!-- document id=17010d7117940a84b0a37d06496797049f5b3709da82704eee61a90c4d96d15a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_ccdw_fact_source_codes_activation.md -->

# ccdw_fact_source_codes_activation

This table records the activation of source codes.

| Column Alias                 | Data Type    | Key    | Description                                                                                                                                                            | Index? |
| ---------------------------- | ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
| `source_code_activation_id`  | BIGINT       | **PK** | Unique identifier for a source code activation event.                                                                                                                  | Yes    |
| `nsource_code_id`            | VARCHAR(50)  |        | Normalized source code identifier.                                                                                                                                     | No     |
| `utc_activation_timestamp`   | TIMESTAMP    |        | UTC timestamp of the source code activation.                                                                                                                           | No     |
| `utc_activation_day_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the UTC activation day.                                                                                    | Yes    |
| `utc_activation_time_id`     | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the UTC activation time.                                                                                   | No     |
| `utc_update_timestamp`       | TIMESTAMP    |        | Last modified UTC timestamp of this record.                                                                                                                            | Yes    |
| `std_activation_timestamp`   | TIMESTAMP    |        | Timestamp of the source code activation, in standard time.                                                                                                             | No     |
| `std_activation_day_id`      | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_date`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md) for the standard activation day.                                                                               | Yes    |
| `std_activation_time_id`     | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_time`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md) for the standard activation time.                                                                              | No     |
| `std_activation_timezone_id` | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_timezone`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md) for the standard activation time zone.                                                                 | No     |
| `source_code_group_id`       | INTEGER      | **FK** | Foreign key to [`ccdw_dim_source_code_group`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md).                                                                                     | Yes    |
| `source_code_status`         | VARCHAR(50)  |        | Status of the source code activation.                                                                                                                                  | No     |
| `activation_site_id`         | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_site`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md) where the source code was activated.                                                                           | Yes    |
| `visitor_id`                 | VARCHAR(100) |        | Unique identifier for a visitor session. This ID persists across sessions and is associated with an anonymous tracking cookie (for example, dwanonymous).              | No     |
| `customer_id`                | BIGINT       | **FK** | Foreign key to [`ccdw_dim_customer`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md). For unregistered buyers, this value is `1` and can't distinguish one unregistered buyer from another. | Yes    |
| `locale_id`                  | SMALLINT     | **FK** | Foreign key to [`ccdw_dim_locale`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md).                                                                                                           | Yes    |
| `user_agent_id`              | INTEGER      | **FK** | Foreign key to [`ccdw_dim_user_agent`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md).                                                                                                   | Yes    |

<!-- **Indices**: `source_code_activation_id`, `source_code_group_id`, `user_agent_id`, `customer_id`, `utc_activation_day_id`, `std_activation_day_id`, `activation_site_id`, `locale_id` -->

<!-- document id=a21198262385cad06df8e2466164d52f67a1d3d4ebaf0b2d2060c7d48c0349df url=/developer/current/en-us/commerce-cloud/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md -->

# CDN Routing Rules for Hybrid Implementations

A phased headless rollout is a technique for delivering a single shopping experience using multiple storefront technologies like Storefront Reference Architecture (SFRA) and Composable Storefront.

**note:** **Applies to:** Hybrid storefronts whose headless runtime is hosted on Managed Runtime (MRT)—both Storefront Next and PWA Kit (Composable Storefront). For a custom headless storefront hosted on a different origin, use your CDN's origin-routing equivalent with the same path split. The local-development hybrid proxy is a PWA Kit feature.

## Traffic Routing for Hybrid Apps with and without eCDN

An embedded CDN (eCDN) is available for Primary Instance Group (PIG) environments, such as production or staging, and for on-demand sandbox (ODS) instances. eCDN can route traffic to both SFRA and Managed Runtime (MRT) at the same time, allowing you to gradually roll out a Composable Storefront. Local development servers don't have an eCDN; in that case, use the hybrid proxy to route traffic to SFRA.

![Hybrid app sequence of requests and responses for a SIG instance](https://developer.salesforce.com/docs/media/commerce-api/hybrid-app-traffic-routing2.png '{"class": "image-lg"}')

## Traffic Routing for Local Development without eCDN

For local development servers, which don't have an eCDN, develop and test hybrid shopper apps that use PWA Kit and SFRA or SiteGenesis by enabling the hybrid proxy feature in the `pwa-kit-runtime` package in PWA Kit v3.14.0 and later. On ODS instances, use eCDN instead of the hybrid proxy.

For more information, see [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

## Traffic Routing for PIG Instances with eCDN

For PIG instances, an eCDN zone can route traffic to both SFRA and MRT at the same time, allowing you to gradually roll out a Composable Storefront.

This diagram shows the sequence of requests and responses when an eCDN routes an incoming page request for a hybrid app for a PIG instance. If the request matches MRT rules, it is forwarded to MRT. Otherwise, if the request doesn't match MRT rules, it is sent to the B2C Commerce instance, and then a response is returned.

![Hybrid app sequence of requests and responses for a SIG instance](https://developer.salesforce.com/docs/media/commerce-api/hybrid-app-with-cdn.png '{"class": "image-lg"}')

You can configure hybrid routing rules in two ways. We recommend using the Business Manager eCDN UI for most implementations. Use the [B2C CLI](#route-traffic-to-managed-runtime) or [CDN Zones API](#configure-routing-rules-with-the-cdn-zones-api) when you need to automate or script rule management.

## Configure Routing Rules in the Business Manager UI

The embedded CDN (eCDN) UI in Business Manager is the recommended way to add and manage hybrid routing rules. It lets you configure rules without writing API payloads.

1. In Business Manager, go to **Administration > Sites > Embedded CDN Settings**.
2. Locate the zone that contains your storefront hostname (typically the default zone).
3. Click the caret on the right side of the zone title, then select **Configure Routing Rules**.

   ![Embedded CDN settings zone actions for configuring routing rules](https://developer.salesforce.com/docs/media/commerce-api/ecdn-configure-routing-rules.png '{"class": "image-xl"}')

4. Locate the routing rule for your hostname and click **Edit**.
5. Confirm that the **Hostnames** and **MRT Origin** fields are prefilled and match your setup. Find your MRT Origin (the Managed Runtime environment domain) in **Environment Settings** in Runtime Admin.
6. In **Rule expression**, enter the Cloudflare expression that matches the routes you want to serve from Managed Runtime.
7. Click **Save**.

For architecture-specific, copy-ready rule expressions, see:

- Storefront Next: [Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-ods.md) and [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-routing-matrix.md).
- PWA Kit / Composable Storefront: [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

**note:** The eCDN UI is available for Primary Instance Group (PIG) and on-demand sandbox (ODS) instances. For local development, use the hybrid proxy instead of eCDN routing rules.

## Configure Routing Rules with the CDN Zones API

If you need to automate or script routing-rule management, use the [Commerce API CDN Zones](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary) API to route traffic to Managed Runtime.

Before running the commands in this section, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`. Throughout this section, we use an example storefront with the production URL `https://www.example.com`.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


### Prerequisites

1. Familiarize yourself with [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)
2. You must have an Account Manager API Client with the scope `sfcc.cdn-zones.rw`.
3. You must know the zone ID of the eCDN zone to be used with Managed Runtime. To get this info, use the [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo) endpoint of the CDN Zones API.
4. Use [updateSecuritySettings](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateSecuritySettings) to enable `alwaysUseHttps` on the zone. _Managed Runtime only supports traffic over HTTPS._
5. Set your SLAS API Client’s `redirect_uri` to include the zone.
6. If you have [restricted the set of IPs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#edit-environment-settings) allowed to access your Managed Runtime environment, add the [CloudFlare IPs](https://www.cloudflare.com/ips/) used by eCDN to the set of allowed IPs.

### Route Traffic to Managed Runtime

With the [createMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createMrtRules) endpoint, create rules that route traffic to a Managed Runtime environment:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn zones list --tenant-id abcd_stg

npx @salesforce/b2c-cli ecdn mrt-rules create \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --mrt-hostname example-production.mobify-storefront.com \
  --expressions 'http.host eq "www.example.com" and http.request.uri.path matches "^/products"'
```

Alternatively, use the API:

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "mrtHostname": "example-production.mobify-storefront.com",
    "expressions": [
      "http.host eq \"www.example.com\" and http.request.uri.path matches \"^/products\""
    ]
  }'
```

Let’s examine the data provided in the request body.

The value of `mrtHostname` is the domain of the Managed Runtime environment for traffic routing. It must refer to a Managed Runtime environment hosted on the `mobify-storefront.com` or `exp-delivery.com` domain. If the provided value is used by an existing rule, the request fails.

**note:** Managed Runtime is the only supported routing destination.

The value of `expressions` is an array of [Cloudflare rule expressions](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/) that controls which requests are routed to Managed Runtime. For most implementations, a single routing expression is sufficient.

In addition to the provided expressions, the following default routing rules are used:

```text
(
  http.request.uri.path matches "^/callback.*" or
  http.request.uri.path matches "^/mobify.*" or
  http.request.uri.path matches "^/worker\.js.*"
)
```

Routing changes are applied immediately, and navigating to a URL that matches an expression returns content retrieved from Managed Runtime.

#### Routing Scenarios

- The following routing scenarios are supported:

  - A single hostname mapped to a single MRT environment:

    - For example, `http.host eq \"www.example.com\"` → `example-production.mobify-storefront.com`

  - Multiple hostnames mapped to a single MRT environment:

    - For example, `http.host in {\"www.example.com\" \"prod.example.com\" \"us.example.com\"}`→ `example-production.mobify-storefront.com`

- The following routing scenario is currently **not** supported:
  - A single hostname mapped to multiple MRT environments based on different paths

#### Expression Constraints

Expressions are validated against the following criteria:

- `http.host` must occur exactly once and must be followed by either the `eq` or `in` operator. See above for usage examples.
- The hostname(s) must match the zone. Or in other words, the eCDN zone must have a valid certificate that covers the provided hostname(s).
- The following fields are supported:
  - `http.host`
  - `http.request.uri.path`
  - `http.request.uri`
  - `http.cookie`
- The maximum length of an expression is 3072 characters.
- A maximum of 300 expressions can be associated with a zone.

### Modify Routing Configuration

As you continue your phased rollout, route more requests to Managed Runtime.

To modify a routing expression, use [getMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getMrtRules) to get the IDs of the ruleset and rule associated with the expression you want to update:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
--header "Authorization: Bearer $TOKEN"
```

Next, use [updateMrtRule](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateMrtRule) to update the expression:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli ecdn mrt-rules rules update \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --ruleset-id your-ruleset-id --rule-id your-rule-id \
  --expression 'http.host eq "www.example.com" and (http.request.uri.path matches "^/products" or http.request.uri.path matches "^/categories")'
```

Alternatively, use the API:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET/rules/$RULE" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "expression": "http.host eq \"www.example.com\" and (http.request.uri.path matches \"^/products\" or http.request.uri.path matches \"^/categories\")"
  }'
```

#### Add More Routing Configurations

To add more routing rules to **an existing** Managed Runtime environment, use [updateMrtRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateMrtRuleset) and provide the `mrtHostname` and additional routing expressions:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
  --request 'PATCH' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "mrtHostname": "example-production.mobify-storefront.com",
    "expressions": ["http.host eq \"www.example.com\" and http.request.uri.path matches \"^/home\""]
  }'
```

To add routing rules for a **new** Managed Runtime environment, use the [createMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createMrtRules) endpoint and provide a new `mrtHostname` value:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "mrtHostname": "example-development.mobify-storefront.com",
    "expressions": [
      "http.host eq \"dev.example.com\" and http.request.uri.path matches \"^/products\""
    ]
  }'
```

#### Modify Managed Runtime Environment

To update existing rules to route to a different Managed Runtime environment, use [updateMrtRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateMrtRuleset) and provide the `oldMrtHostname` and the (new) `mrtHostname` that you want to route to:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
  --request 'PATCH' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "oldMrtHostname": "example-old.mobify-storefront.com",
    "mrtHostname": "example-new.mobify-storefront.com"
  }'
```

### Disable Routing

If you're switching to a third-party CDN or you no longer want to route a particular path from eCDN to MRT, disable routing.

To disable routing, use [getMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getMrtRules) to get the IDs of the configuration that you want to delete:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules" \
--header "Authorization: Bearer $TOKEN"
```

Then, to remove the Managed Runtime routing rule, use [deleteMrtRule](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=deleteMrtRule) and pass in the applicable IDs returned by [getMrtRules](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getMrtRules):

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET/rules/$RULE" \
--request 'DELETE' \
--header "Authorization: Bearer $TOKEN"
```

If you want to remove all Managed Runtime routing rules, use [deleteMrtRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=deleteMrtRuleset):

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/mrtrules/$RULESET" \
--request 'DELETE' \
--header "Authorization: Bearer $TOKEN"
```

### Route All Traffic to Managed Runtime

When you complete your phased rollout or if you are launching a new site, route all traffic for a zone to Managed Runtime using a single expression:

```text
http.host eq \"www.example.com\"
```

## See Also

- [Hybrid Implementation Guidance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-storefront-baskets.md)
- [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-authentication.md)

<!-- document id=bb6f5b58d7a8e0ed17f773d7b6adebf3422c7cd046d32177cac1131f26813cdf url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones.md -->

# CDN Zones

The [CDN Zones API](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary) provides for multiple use cases, ranging from bad actor targeting scenarios to security enhancement ruleset options.

The initial release of the CDN API supports the Content Delivery domain, and focuses on security improvements. Over time, Salesforce expects the CDN API to support other features, many of which we currently provide in the Business Manager eCDN.

## General Usage Guidelines

When defining API methods, keep the following in mind:

- POST methods can return a **409 Conflict** response status code when a call encounters an existing rule with the same **type** and **action**.
- Changing rules using the PUT method overwrites existing values. When updating a rule using the PUT method, make sure to include all desired values in a list payload, not just the values you want to change.

## Storefront Zone Creation

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn zones create \
  --tenant-id abcd_stg --domain-name www.example.com
```

When you create a new storefront zone, it is created as a proxy zone and is configured with a `zoneName` that ends in `ecdn.net`. Use separate zones for development, staging, and production instances.

For each storefront zone that you create, you must create a custom hostname and update your storefront’s DNS records to send traffic to that custom hostname (CNAME):

1. Determine your custom hostname, for example: `examplecustomhost.com`.
2. [Add an SSL certificate to an eCDN Zone and Configure DNS Mapping](https://help.salesforce.com/s/articleView?id=cc.b2c_add_a_certificate_to_a_zone.htm&language=en_US&type=5) to activate your custom hostname.
3. Get the DNS CNAME record value from [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo)'s name property. For example: `www.example.com CNAME commcloud.prod-abcd-example-com.cc-ecdn.net`
4. Configure your DNS to send traffic to the zone with your custom hostname (CNAME). For example: `prod-bcnx-examplecustomhost-com.cc-ecdn.net`.`

See [Create a Zone in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_zone.htm&language=en_US&type=5) for details on creating zones using Business Manager.

## Access Control Usage Guidelines

Access control rules should now be configured using eCDN custom rules. When configuring access control rules, keep the following in mind:

- When specifying more than one IP address or Country Code value in an allowlist or blocklist, include them all in a single expression using the `in` operator and list notation. This practice makes sure that you do not issue more calls than necessary when a rule is employed. For details, see the [eCDN Custom Rules guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html)
- You can specify any two-letter combination as a Country Code. However, the API recognizes only valid Country Codes in ISO 3166-1 alpha-2 (two-letter code) format. For more information, see the International Organization for Standardization (ISO) [3166 Country Code page](https://www.iso.org/iso-3166-country-codes.html).
- Regardless of their use, any Country Codes for countries embargoed or sanctioned by the United States remain blocked. For more information, see the US Department of Commerce [Bureau of Industry and Security page](https://www.bis.doc.gov/index.php/policy-guidance/country-guidance/sanctioned-destinations).
- Make sure that any IP addresses that you include in Business Manager eCDN allowlists do not contradict IP Access or Regional Access deny rule settings in the CDN API.

  **note:** Allowlist settings in Business Manager override any contradicting rules in the CDN API.

- IP and Regional access rules execute in a specific order: 1) embargoed countries (no override due to platform compliance), 2) IP access lists in Business Manager, 3) CDN API IP access deny lists, 4) CDN API Regional Access allowlists, and 5) any customer-requested IP or Regional blocking by Salesforce.

**note:** When using firewall rules, all remaining traffic following any configured allowlist rules was blocked. Custom rules provide more flexibility and allow you to control this behavior as needed.

## CDN Stacking

The CDN API can enforce that all traffic navigates through a third-party proxy into the eCDN before accessing the B2C Commerce infrastructure. In the following use case, an architect wants to stack another, third-party CDN, or any cloud proxy, in front of the B2C Commerce eCDN and leverage features of that third-party proxy.

### Create a CDN Stacking Rule

To create a CDN stacking rule, use the following method:

`POST /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Example body:

```json
{
  "description": "IP Allowlist",
  "expression": "(ip.src in {123.123.0.0/32 123.123.0.1/32 123.124.127.0/32})",
  "actions": ["skip_custom_rules"]
}
```

For more information on creating allowlists using custom rules, refer to the [eCDN Custom Rules guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html)

### Update a CDN Stacking Rule

To update an existing CDN stacking rule, use the following method to obtain the specific rule ID that you want to update:

`GET /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Include the rule ID in the following method to update the rule:

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules/{ruleId}`

Example body:

```json
{
  "expression": "(ip.src in {123.123.0.0 123.123.0.1 123.124.127.0})"
}
```

## IP Access Control

The API provides the ability to use a blocklist to deny specific CIDR or IP addresses. The API can prevent known bad actors from accessing the storefront as they attempt to harm or access your web application.

### Create an Access Control Rule

To create an access control rule, use the following method:

`POST /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Example body:

```json
{
  "description": "IP Blocklist",
  "expression": "(ip.src in {123.123.0.0/32 123.123.0.1/32 123.124.127.0/32})",
  "actions": ["block"]
}
```

### Update an Access Control Rule

To update an existing access control rule, use the following method to obtain the specific rule ID that you want to update:

`GET /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Include the rule ID in the following method to update the rule:

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules/{ruleId}`

Example body:

```json
{
  "expression": "(ip.src in {123.123.0.0 123.123.0.1 123.124.127.0})"
}
```

## Region Access Control

The API provides the ability to block or allow traffic from specific countries. The API can restrict storefront access to certain countries. In the following use case, a security-conscious eCom director wants to limit orders to within the United Kingdom, and disallow orders from outside of this region.

### Create a Region Access Control Rule

To create a region access control rule, use the following method:

`POST /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Example body:

```json
{
  "description": "Country Allowlist",
  "expression": "(ip.geoip.country in {\"UK\"})",
  "actions": ["skip_custom_rules"]
}
```

### Update a Region Access Control Rule

To update an existing access control rule, use the following method to obtain the specific rule ID that you want to update:

`GET /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Include the rule ID in the following method to update the rule:

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules/{ruleId}`

Example body:

```json
{
  "expression": "(ip.geoip.country in {\"UK\" \"US\"})"
}
```

## Site Testing

To test changes before pushing to a production instance, create a custom hostname for your Development instance.

## Application Firewall Rule Enhancements

Company security teams want to safeguard their storefront against a landscape in which application attacks continually change. In this use case, the API enables the team to address existing attack vectors, and provides protections against new vulnerabilities as Salesforce updates the ruleset. To enable Salesforce to manage these rulesets for you, use “Default” as the action in the API.

**note:** The API updates each rule individually, and reports back if an error occurs. However, when using the ruleset group method to change an action, we recommend that you check that all rules update appropriately as a best practice. If you determine that a rule was updated inappropriately, rerun the group change.

When turning on a Web Application Firewall (WAF) group, we recommend the following general process:

1. Put the group in monitor mode for 7 days.
2. Check logs for any triggered WAF events.
3. Check that the WAF rule would stop bad actors properly, or if any WAF rules were triggered incorrectly.
4. Change the group to default mode.
5. Check the default setting for any rules triggered over the monitoring period, and adjust as necessary. For example, if the default setting for a triggered rule is “monitor,” change the rule setting to “challenge” or “block”.

### Turn a WAF Group On in Monitor Mode

To update an existing access control rule, use the following method to obtain the specific rule ID that you want to update:

`GET /organizations/{organizationId}/zones/{zoneId}/waf/groups`

Include the group ID in the following method to turn on the group, and place it in **monitor** mode:

`PUT /organizations/{organizationId}/zones/{zoneId}/waf/groups/{groupId}`

Example body:

```json
{
  "action": "monitor",
  "mode": "on"
}
```

### Check WAF Rule Settings

Use the following method to obtain a list of all WAF rules, and locate the rule ID of the rule that you want to check:

`GET /organizations/{organizationId}/zones/{zoneId}/waf/rules`

Include the rule ID in the following method to view information specific to the rule:

`GET /organizations/{organizationId}/zones/{zoneId}/waf/rules/{ruleId}`

### Set a WAF Group to Default Mode

Use the following method to obtain a list of all WAF groups, and locate the group ID of the group that you want to set to default mode:

`GET /organizations/{organizationId}/zones/{zoneId}/waf/groups`

Include the group ID in the following method to turn on the group, and place it in **default** mode:

`PUT /organizations/{organizationId}/zones/{zoneId}/waf/groups/{groupId}`

Example body:

```json
{
  "action": "default",
  "mode": "on"
}
```

### Modify a WAF Rule

Use the following method to obtain a list of all WAF rules in a WAF group, and locate the rule ID of the rule that you want to modify:

`GET /organizations/{organizationId}/zones/{zoneId}/waf/rules`

Include the rule ID in the following method to modify the rule:

`PUT /organizations/{organizationId}/zones/{zoneId}/waf/rules/{ruleId}`

Example body:

```json
{
  "action": "challenge"
}
```

## Brotli Compression

Brotli is a compression algorithm developed by Google. Developed to decrease the size of transmissions, and best used for text compression, Brotli compression is applied intelligently for large files to reduce downloaded bytes to the browser and improve site performance.

Use the following method to obtain the current state of the API speed settings:

`GET /organizations/{organizationId}/zones/{zoneId}/speed-settings`

To modify the Brotli compression setting:

`PATCH /organizations/{organizationId}/zones/{zoneId}/speed-settings`

Example body:

```json
{
  "brotliCompression": "on"
}
```

## HTTP/2 Prioritization

HTTP/2 is a major revision of the HTTP network protocol. When enabled, HTTP/2 is used on supporting browsers to decrease latency and improve browser page load speed.

Use the following method to obtain the current state of the API speed settings:

`GET /organizations/{organizationId}/zones/{zoneId}/speed-settings`

To modify the HTTP/2 prioritization setting:

`PATCH /organizations/{organizationId}/zones/{zoneId}/speed-settings`

Example body:

```json
{
  "http2Prioritization": "on"
}
```

## Rule Firing Investigation

Using the WAF eCDN logs in Business Manager, view which firewall rules are firing. By knowing the rule ID, use the CDN API endpoints to obtain context and details about why a specific rule is firing for a given HTTP request.

## Glossary of Terms

**Cache**: Where the CDN stores copies of resources that it returns to end users. What the cache stores, and for how long, is determined by the cache-control headers returned by the origin. By default, only static content is stored in cache.

**CDN Hostname**: The part of a zone configured by clients to indicate traffic configured for the CDN (for example, `www.customer.com.cdn.cloudflare.net`). The CDN Hostname is the _target_ for client hostnames. You can use this hostname to spoof host files to direct traffic to the CDN for testing purposes.

**Client**: The primary user (customer) of the CDN service.

**Client Domain**: The DNS zone owned and maintained by the client (for example, `https://www.customer.com`).

**Client Hostname**: Hostnames tied to client-owned domains that clients configure to direct traffic to the CDN hostname.

**Consumer**: The end user, that is, the consumer of the resources proxied by the CDN.

**Custom Rule**: A rule that enables the client to set up firewall policies based on various request parameters. These rules expand previous firewall rule functionality with an extended list of fields and actions. With custom rules, you have complete control over the rule expression and increased flexibility to tailor rules to your traffic needs.

**Origin**: The source of truth, meaning where actual resources are stored. The origin is what the CDN proxies and protects.

**Resource**: Any content owned and managed by the client that can be delivered using the Internet, such as web pages, images, JavaScript, CSS, fonts, and so on.

**WAF Group**: A collection of WAF rules compiled under a single unit. WAF Groups enable batch update of all rules in a particular group.

**WAF Rule**: A WAF policy designed to defend against a specific application vulnerability or attack.

**Web Application Firewall (WAF)**: Firewall that enables clients to protect the origin from various _application_ level attacks, such as SQL injection, cross-site scripting (XSS), and so on. By definition, a WAF is stateless and uses a request signature to identify threats.

**Zone**: The container of hostnames and properties. Each zone is tied to a single origin.

<!-- document id=33e0c05b067aca44be8078aabed4c230e14c08735d58959b4a7856aa76bebfdd url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/zones.md -->

CDN Zones

# CDN Zones

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/zones/zones-oas-v1-public.yaml)

## API Overview

The Content Delivery Network (CDN) API is for managing the embedded CDN (eCDN) that is included with Commerce Cloud and configured with Business Manager.

Use the API to:

*   Ensure that traffic doesn’t circumvent proxies layered in front of your eCDN.
*   Accelerate the delivery of resources to users with caching, compression, and prioritization.
*   Customize how users interact with resources and how requests are processed, including custom pages and routing rules.
*   Provide proactive and complete application protection against new and existing exploits from bad actors.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the `Authorization` header of your API request.

The API client must also have at least one of the following OAuth scopes: `sfcc.cdn-zones` or `sfcc.cdn-zones.rw`.

For detailed setup instructions, see the [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) guide.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

For detailed usage information, refer to the [CDN Zones Guides.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones.html)

**Version:** 1.3.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.cdn-zones: CDN API Scope READONLY
    *   Scope sfcc.cdn-zones.rw: CDN API Scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.cdn-zones: CDN API Scope READONLY
    *   Scope sfcc.cdn-zones.rw: CDN API Scope

## Operations

### POST Create a new storefront zone.

`POST /organizations/{organizationId}/storefront-zones`

Operation ID: `createStorefrontZone`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Create a new storefront zone for the organization. Use this endpoint to set up a new CDN zone with specific configurations for storefront applications.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `StorefrontZoneCreateRequest`.

_Example: StorefrontZoneCreateRequestBodyExample_

```
{
  "domainName": "cc-merchant.com"
}
```

#### Responses

*   **201** Successfully created new storefront zone.
    
    Media type: `application/json`. Schema: `StorefrontZoneCreateEnvelope`.
    
    _Example: StorefrontZoneCreateResponse_
    
    ```
    {
      "data": {
        "zoneId": "023e105f4ecef8ad9ca31a8372d0c353",
        "zoneName": "stg-zzzz-cc-merchant-com.cc-ecdn.net",
        "createdOn": "2022-01-01T05:20:00.12345Z",
        "status": "active"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Request body contains 1 or more attributes that contains errors."
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InternalServerError_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/internal-server",
      "title": "Internal Server Error",
      "detail": "An internal server error occured. Please contact support."
    }
    ```
    

### GET Return all the mTLS certificates for the account.

`GET /organizations/{organizationId}/mtls/code-upload-certificates`

Operation ID: `getCodeUploadCertificates`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve all mTLS certificates for the account. These certificates are used for secure code upload operations and client authentication.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved details of the mTLS certificates requested by the caller.
    
    Media type: `application/json`. Schema: `MtlsCertificatesResponseEnvelope`.
    
    _Example: MtlsCodeUploadGetCertificatesResponse_
    
    ```
    {
      "data": [
        {
          "mtlsCertificateId": "465a48f6-3d98-4c15-9312-211984ee8629",
          "expiresOn": "2022-01-12T04:15:57Z",
          "issuer": "DigiCert",
          "signature": "SHA256WithRSA",
          "uploadedOn": "2020-01-12T04:15:57Z",
          "ca": true,
          "serialNumber": "432217133297895665180570788458463042229861757760",
          "mtlsCertificateName": "mtls_cert_name",
          "mtlsAssociatedCodeUploadHostname": "mtls.cert.salesforce.com"
        },
        {
          "mtlsCertificateId": "465a48f6-3d98-4c15-9312-211984ee8630",
          "expiresOn": "2022-01-12T04:15:57Z",
          "issuer": "DigiCert",
          "signature": "SHA256WithRSA",
          "uploadedOn": "2020-01-12T04:15:57Z",
          "ca": true,
          "serialNumber": "432217133297895665180570788458463042229861757761",
          "mtlsCertificateName": "mtls_cert_name",
          "mtlsAssociatedCodeUploadHostname": "mtls.cert.salesforce.com"
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Set up two-factor mTLS certificates for the account and associate the staging zone code upload hostname.

`POST /organizations/{organizationId}/mtls/code-upload-certificates`

Operation ID: `createCodeUploadCertificate`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Create a new mTLS certificate for code upload operations. This certificate enables secure client authentication for code deployment processes.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `MtlsCertificateRequest`.

_Example: MtlsCodeUploadPostCertificateRequestBodyExample_

```
{
  "name": "mtls_cert_name",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----",
  "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----"
}
```

#### Responses

*   **201** Returns information about the uploaded mTLS certificate.
    
    Media type: `application/json`. Schema: `MtlsCertificateResponseEnvelope`.
    
    _Example: MtlsCodeUploadGetCertificateResponse_
    
    ```
    {
      "data": {
        "mtlsCertificateId": "465a48f6-3d98-4c15-9312-211984ee8629",
        "expiresOn": "2022-01-12T04:15:57Z",
        "issuer": "DigiCert",
        "signature": "SHA256WithRSA",
        "uploadedOn": "2020-01-12T04:15:57Z",
        "ca": true,
        "serialNumber": "432217133297895665180570788458463042229861757760",
        "mtlsCertificateName": "mtls_cert_name",
        "mtlsAssociatedCodeUploadHostname": "mtls.cert.salesforce.com"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Return the mTLS certificate for the given account's mTLS certificate ID.

`GET /organizations/{organizationId}/mtls/code-upload-certificates/{mtlsCertificateId}`

Operation ID: `getCodeUploadCertificate`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve a specific mTLS certificate by its ID. This endpoint provides detailed information about the certificate's configuration, status, and associated hostname.

#### Parameters

*   `mtlsCertificateId` (path, string, required) The unique identifier of an mTLS certificate.  
    Pattern: ^.\*$. Example: `465a48f6-3d98-4c15-9312-211984ee8629`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved mTLS certificate information from the mTLS certificate ID requested by the caller.
    
    Media type: `application/json`. Schema: `MtlsCertificateResponseEnvelope`.
    
    _Example MtlsCodeUploadGetCertificateResponse: same as POST /organizations/{organizationId}/mtls/code-upload-certificates 201 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Remove an mTLS certificate and associated hostname.

`DELETE /organizations/{organizationId}/mtls/code-upload-certificates/{mtlsCertificateId}`

Operation ID: `deleteCodeUploadCertificate`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Permanently delete an mTLS certificate and its associated hostname from the account. This operation cannot be undone.

#### Parameters

*   `mtlsCertificateId` (path, string, required) The unique identifier of an mTLS certificate.  
    Pattern: ^.\*$. Example: `465a48f6-3d98-4c15-9312-211984ee8629`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the mTLS certificate from the account.
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    

### GET Get page shield notification webhooks.

`GET /organizations/{organizationId}/page-shield/notifications`

Operation ID: `getPageShieldNotification`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved notification webhooks.
    
    Media type: `application/json`. Schema: `PageShieldNotificationWebhookListEnvelope`.
    
    _Example: PageShieldNotificationWebhookListResponse_
    
    ```
    {
      "data": [
        {
          "id": "webhook_1234567890abcdef",
          "name": "Security Alert Webhook",
          "webhookUrl": "https://example.com/webhook/security",
          "type": "security_alert",
          "createdAt": "2023-01-01T00:00:00Z",
          "lastSuccess": "2023-01-01T12:00:00Z",
          "lastFailure": "2023-01-01T18:00:00Z",
          "enabled": true,
          "zones": [
            "zone_1234567890abcdef"
          ]
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Setup page shield notification webhook.

`POST /organizations/{organizationId}/page-shield/notifications`

Operation ID: `postPageShieldNotification`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PageShieldNotificationWebhookRequest`.

_Example: PageShieldNotificationWebhookRequest_

```
{
  "webhookUrl": "https://example.com/webhook/security",
  "name": "Security Alert Webhook",
  "secret": "webhook_secret_123",
  "enabled": true,
  "zones": [
    "zone_1234567890abcdef"
  ]
}
```

#### Responses

*   **200** Successfully added notification webhook.
    
    Media type: `application/json`. Schema: `PageShieldNotificationWebhookEnvelope`.
    
    _Example: PageShieldNotificationWebhookResponse_
    
    ```
    {
      "data": {
        "id": "webhook_1234567890abcdef",
        "name": "Security Alert Webhook",
        "webhookUrl": "https://example.com/webhook/security",
        "type": "security_alert",
        "createdAt": "2023-01-01T00:00:00Z",
        "lastSuccess": "2023-01-01T12:00:00Z",
        "lastFailure": "2023-01-01T18:00:00Z",
        "enabled": true,
        "zones": [
          "zone_1234567890abcdef"
        ]
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete page shield notification webhook.

`DELETE /organizations/{organizationId}/page-shield/notifications/{webhookId}`

Operation ID: `deletePageShieldNotification`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `webhookId` (path, string, required) The unique identifier of a webhook.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted notification webhook.
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update page shield notification webhook.

`PATCH /organizations/{organizationId}/page-shield/notifications/{webhookId}`

Operation ID: `updatePageShieldNotification`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `webhookId` (path, string, required) The unique identifier of a webhook.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PageShieldNotificationWebhookUpdateRequest`.

_Example: PageShieldNotificationWebhookUpdateRequest_

```
{
  "webhookId": "ffffe61cf25e4ec49c34b029ff3060f7",
  "enabled": true,
  "zones": [
    "zone_1234567890abcdef"
  ]
}
```

#### Responses

*   **200** Successfully updated notification webhook.
    
    Media type: `application/json`. Schema: `PageShieldNotificationWebhookEnvelope`.
    
    _Example PageShieldNotificationWebhookResponse: same as POST /organizations/{organizationId}/page-shield/notifications 200 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET List webhooks.

`GET /organizations/{organizationId}/webhook`

Operation ID: `getWebhooks`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve all webhooks.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved webhooks.
    
    Media type: `application/json`. Schema: `WebhookListEnvelope`.
    
    _Example: WebhookListResponse_
    
    ```
    {
      "data": [
        {
          "id": "ffffe61cf25e4ec49c34b029ff3060f7",
          "name": "My Webhook",
          "url": "https://example.com/webhook",
          "type": "webhook",
          "createdAt": "2023-01-01T00:00:00Z",
          "lastSuccess": "2023-01-01T12:00:00Z",
          "lastFailure": "2023-01-01T18:00:00Z"
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The requested resource was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create webhook.

`POST /organizations/{organizationId}/webhook`

Operation ID: `createWebhook`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Create a new webhook.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `WebhookRequest`.

_Example: WebhookRequestBodyExample_

```
{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "secret": "webhook_secret_123"
}
```

#### Responses

*   **201** Successfully created webhook.
    
    Media type: `application/json`. Schema: `WebhookEnvelope`.
    
    _Example: WebhookResponse_
    
    ```
    {
      "data": {
        "id": "ffffe61cf25e4ec49c34b029ff3060f7",
        "name": "My Webhook",
        "url": "https://example.com/webhook",
        "type": "webhook",
        "createdAt": "2023-01-01T00:00:00Z",
        "lastSuccess": "2023-01-01T12:00:00Z",
        "lastFailure": "2023-01-01T18:00:00Z"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get webhook by ID.

`GET /organizations/{organizationId}/webhook/{webhookId}`

Operation ID: `getWebhook`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve a specific webhook.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `webhookId` (path, string, required) The unique identifier of a webhook.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.

#### Responses

*   **200** Successfully retrieved webhook.
    
    Media type: `application/json`. Schema: `WebhookEnvelope`.
    
    _Example WebhookResponse: same as POST /organizations/{organizationId}/webhook 201 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The requested resource was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Update webhook.

`PUT /organizations/{organizationId}/webhook/{webhookId}`

Operation ID: `updateWebhook`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update an existing webhook.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `webhookId` (path, string, required) The unique identifier of a webhook.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.

#### Request body (required)

Media type: `application/json`. Schema: `WebhookRequest`.

_Example: WebhookRequestBodyExample_

```
{
  "name": "My Webhook",
  "url": "https://example.com/webhook",
  "secret": "webhook_secret_123"
}
```

#### Responses

*   **200** Successfully updated webhook.
    
    Media type: `application/json`. Schema: `WebhookEnvelope`.
    
    _Example WebhookResponse: same as POST /organizations/{organizationId}/webhook 201 response._
    
*   **201** Successfully created webhook.
    
    Media type: `application/json`. Schema: `WebhookEnvelope`.
    
    _Example WebhookResponse: same as POST /organizations/{organizationId}/webhook 201 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The requested resource was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete webhook.

`DELETE /organizations/{organizationId}/webhook/{webhookId}`

Operation ID: `deleteWebhook`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Delete a webhook.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `webhookId` (path, string, required) The unique identifier of a webhook.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.

#### Responses

*   **204** Successfully deleted webhook.
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The requested resource was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET List page shield policies.

`GET /organizations/{organizationId}/zones/{zoneId}/page-shield/policies`

Operation ID: `getPageShieldPolicies`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** List current page shield policies.
    
    Media type: `application/json`. Schema: `PageShieldPoliciesListEnvelope`.
    
    _Example: PageShieldPoliciesGetResponse_
    
    ```
    {
      "data": [
        {
          "action": "log",
          "description": "example page shield policy 1",
          "enabled": true,
          "expression": "(http.request.full_uri contains \"/Checkout-Begin\" and http.host eq \"www.example.com\")",
          "value": "script-src salesforce.com *.salesforce.com https://www.example.com/on/demandware.static/Sites-RefArch-Site/-/en_US/v1738096133818/js/checkout.js 'unsafe-inline'",
          "id": "4805ab87bb867579757a4564ba46ebca"
        },
        {
          "action": "log",
          "description": "example page shield policy 2",
          "enabled": true,
          "expression": "ends_with(http.request.uri.path, \"/test1\")",
          "value": "script-src 'none'",
          "id": "7650c87c9c2846c296ea4564ba46ebca"
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create page shield policy.

`POST /organizations/{organizationId}/zones/{zoneId}/page-shield/policies`

Operation ID: `createPageShieldPolicy`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PageShieldPolicyRequest`.

_Example: PageShieldPolicyRequestBodyExample_

```
{
  "action": "log",
  "description": "example page shield policy",
  "enabled": true,
  "expression": "ends_with(http.request.uri.path, \"/test1\")",
  "value": "script-src 'none'"
}
```

#### Responses

*   **200** Successfully created page shield policy.
    
    Media type: `application/json`. Schema: `PageShieldPoliciesEnvelope`.
    
    _Example: PageShieldPolicyGetResponse_
    
    ```
    {
      "data": {
        "action": "log",
        "description": "example page shield policy",
        "enabled": true,
        "expression": "ends_with(http.request.uri.path, \"/test1\")",
        "value": "script-src 'none'",
        "id": "7650c87c9c2846c296ea4564ba46ebca"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get page shield policy by policy ID.

`GET /organizations/{organizationId}/zones/{zoneId}/page-shield/policies/{policyId}`

Operation ID: `getPageShieldPolicy`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `policyId` (path, string, required) The unique identifier of a Page Shield policy.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved the details of the page shield policy.
    
    Media type: `application/json`. Schema: `PageShieldPoliciesEnvelope`.
    
    _Example PageShieldPolicyGetResponse: same as POST /organizations/{organizationId}/zones/{zoneId}/page-shield/policies 200 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Update page shield policy by policy ID.

`PUT /organizations/{organizationId}/zones/{zoneId}/page-shield/policies/{policyId}`

Operation ID: `updatePageShieldPolicy`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `policyId` (path, string, required) The unique identifier of a Page Shield policy.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PageShieldPolicyRequest`.

_Example: PageShieldPolicyPutRequestBodyExample_

```
{
  "action": "allow",
  "enabled": true
}
```

#### Responses

*   **200** Successfully updated the page shield policy.
    
    Media type: `application/json`. Schema: `PageShieldPoliciesEnvelope`.
    
    _Example: PageShieldPoliciesEnvelope_
    
    ```
    {
      "data": {
        "action": "allow",
        "description": "example page shield policy",
        "enabled": true,
        "expression": "ends_with(http.request.uri.path, \"/test1\")",
        "value": "script-src 'none'",
        "id": "7650c87c9c2846c296ea4564ba46ebca"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete page shield policy.

`DELETE /organizations/{organizationId}/zones/{zoneId}/page-shield/policies/{policyId}`

Operation ID: `deletePageShieldPolicy`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `policyId` (path, string, required) The unique identifier of a Page Shield policy.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the page shield policy.
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve a list of scripts detected by page shield for a specific zone.

`GET /organizations/{organizationId}/zones/{zoneId}/page-shield/scripts`

Operation ID: `getPageShieldScripts`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `direction` (query, string) The direction used to sort returned scripts.  
    Allowed values: `asc`, `desc`. Example: `asc`.
*   `excludeCdnCgi` (query, boolean) When true, excludes scripts existing in a /cdn-cgi path from the returned scripts. Default is true.  
    Example: `true`.
*   `excludeDuplicates` (query, boolean) When true, excludes duplicate scripts. Default is false.  
    Example: `false`.
*   `excludeUrls` (query, string) Excludes scripts with a URL that contains one of the URL-encoded URLs separated by commas.  
    Pattern: ^.\*$. Example: `https://example.com/script1.js,https://example.com/script2.js`.
*   `hosts` (query, string) Includes scripts that match one or more URL-encoded hostnames separated by commas. Wildcards are supported at the beginning and end of each hostname.  
    Pattern: ^.\*$. Example: `*.example.com,test.example.com`.
*   `orderBy` (query, string) The field used to sort returned scripts.  
    Allowed values: `first_seen_at`, `last_seen_at`. Example: `last_seen_at`.
*   `pageUrl` (query, string) Includes scripts that match one or more page URLs (separated by commas) where they were last detected. Wildcards are supported at the beginning and end of each page URL.  
    Pattern: ^.\*$. Example: `https://example.com/page1,https://example.com/page2`.
*   `prioritizeMalicious` (query, boolean) When true, lists malicious scripts first in the returned scripts.  
    Example: `true`.
*   `status` (query, string) Filters the returned scripts using a comma-separated list of script statuses. Accepted values are 'active', 'infrequent', and 'inactive'. Default is 'active'.  
    Pattern: ^.\*$. Example: `active,infrequent`.
*   `urls` (query, string) Includes scripts with a URL that contains one or more URL-encoded URLs separated by commas.  
    Pattern: ^.\*$. Example: `https://example.com/script1.js,https://example.com/script2.js`.
*   `page` (query, string) When set to 'all', retrieves all scripts without pagination, disregarding offset and limit parameters.  
    Allowed values: `all`. Example: `all`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 200.  
    Default: `200`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** List current page shield scripts.
    
    Media type: `application/json`. Schema: `PageShieldScriptListEnvelope`.
    
    _Example: PageShieldScriptListResponse_
    
    ```
    {
      "data": [
        {
          "id": "12345678901234asdfasfasdf",
          "url": "https://sfdc-test.net/on/demandware.static/Sites-SiteNemesis-Site/-/en_US//lib/jquery/ui/jquery-ui.min.js",
          "host": "sfdc-test.net",
          "addedAt": "2022-01-01T05:20:00Z",
          "firstSeenAt": "2022-01-01T05:20:00Z",
          "lastSeenAt": "2022-01-01T05:20:00Z",
          "fetchedAt": "2022-01-01T05:20:00Z",
          "domainReportedMalicious": false,
          "hash": "1243453456abc",
          "cryptoMiningScore": 1,
          "dataflowScore": 1,
          "jsIntegrityScore": 1,
          "mageCartScore": 2,
          "malwareScore": 1,
          "obfuscationScore": 2,
          "maliciousDomainCategories": [
            "Malware"
          ],
          "maliciousUrlCategories": [
            "Malware"
          ],
          "urlContainsCdnCgiPath": false,
          "urlReportedMalicious": false,
          "pageUrls": [
            "blog.test.salesforce.com/page1",
            "blog.test.salesforce.com/page2"
          ],
          "firstPageUrl": "blog.test.salesforce.com",
          "status": "active",
          "versions": []
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Fetch a script detected by Page Shield by script ID.

`GET /organizations/{organizationId}/zones/{zoneId}/page-shield/scripts/{scriptId}`

Operation ID: `getPageShieldScript`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-pci-4-compliance.html).

#### Parameters

*   `scriptId` (path, string, required) The unique identifier of a Page Shield script.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** A script detected by Page Shield by script ID.
    
    Media type: `application/json`. Schema: `PageShieldScriptEnvelope`.
    
    _Example: PageShieldScriptResponse_
    
    ```
    {
      "data": {
        "id": "12345678901234asdfasfasdf",
        "url": "https://sfdc-test.net/on/demandware.static/Sites-SiteNemesis-Site/-/en_US//lib/jquery/ui/jquery-ui.min.js",
        "host": "sfdc-test.net",
        "addedAt": "2022-01-01T05:20:00Z",
        "firstSeenAt": "2022-01-01T05:20:00Z",
        "lastSeenAt": "2022-01-01T05:20:00Z",
        "fetchedAt": "2022-01-01T05:20:00Z",
        "domainReportedMalicious": false,
        "hash": "1243453456abc",
        "cryptoMiningScore": 1,
        "dataflowScore": 1,
        "jsIntegrityScore": 1,
        "mageCartScore": 2,
        "malwareScore": 1,
        "obfuscationScore": 2,
        "maliciousDomainCategories": [
          "Malware"
        ],
        "maliciousUrlCategories": [
          "Malware"
        ],
        "urlContainsCdnCgiPath": false,
        "urlReportedMalicious": false,
        "pageUrls": [
          "blog.test.salesforce.com/page1",
          "blog.test.salesforce.com/page2"
        ],
        "firstPageUrl": "blog.test.salesforce.com",
        "status": "active",
        "versions": []
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve zone information.

`GET /organizations/{organizationId}/zones/info`

Operation ID: `getZonesInfo`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve information about all zones for the organization. This endpoint provides an overview of all CDN zones, including their status, configuration, and basic details.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Successfully retrieved zone information requested by the caller.
    
    Media type: `application/json`. Schema: `ZonesEnvelope`.
    
    _Example: ZonesGetResponse_
    
    ```
    {
      "data": [
        {
          "zoneId": "e4288c0a1f80fa5490b598d74c69bde4",
          "name": "sfcc-cdn.net",
          "status": "pending"
        }
      ]
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve all WAF groups accessible to the caller.

`GET /organizations/{organizationId}/zones/{zoneId}/waf/groups`

Operation ID: `getWafGroups`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve all Web Application Firewall (WAF) groups accessible to the caller. This endpoint provides information about WAF groups and their configurations for the specified zone. Not applicable for zones using WAFv2. For zones created after the 24.5 release, use the endpoints for WAF managed rulesets.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved details of WAF groups to which the caller has access.
    
    Media type: `application/json`. Schema: `WafGroupsEnvelope`.
    
    _Example: WafGroupsGetResponse_
    
    ```
    {
      "data": [
        {
          "groupId": "f90712123fb02287348dd34c0a282bb9",
          "mode": "on",
          "description": "This WAF Group contains a number of rules that have been created to deal with specific attack types. "
        },
        {
          "groupId": "da9d75b083345c63f48e6fde5f617a8b",
          "mode": "on",
          "description": "This WAF Group contains rules to deal with known malicious traffic or patch flaws in specific web applications."
        }
      ]
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Update the action or mode of a specific WAF group.

`PUT /organizations/{organizationId}/zones/{zoneId}/waf/groups/{groupId}`

Operation ID: `updateWafGroup`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update the action or mode of a specific Web Application Firewall (WAF) group. Use this endpoint to modify the security settings and behavior of a WAF group. Not applicable for zones using WAFv2. For any zones created after the 24.5 release, use the endpoints for WAF managed rulesets.

#### Parameters

*   `groupId` (path, string, required) WAF Group that contains the WAF rules.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
    
    _Example_
    
    ```
    f90712123fb02287348dd34c0a282bb9
    ```
    
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `WafGroup`.

_Example: WafGroupPutRequestBodyExample_

```
{
  "action": "monitor",
  "mode": "on"
}
```

#### Responses

*   **200** Successfully updated the WAF group specified by the caller.
    
    Media type: `application/json`. Schema: `WafGroupEnvelope`.
    
    _Example: WafGroupPutResponse_
    
    ```
    {
      "data": {
        "groupId": "f90712123fb02287348dd34c0a282bb9",
        "mode": "on",
        "description": "This WAF Group contains a number of rules that have been created to deal with specific attack types. "
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve WAF rules for the WAF group specified by the caller.

`GET /organizations/{organizationId}/zones/{zoneId}/waf/rules`

Operation ID: `getWafRules`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve WAF rules for the WAF group specified by the caller. This endpoint provides information about the security rules configured for a specific WAF group. Not applicable for zones using WAFv2. For any zones created after the 24.5 release, use the endpoints for WAF managed rulesets.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (query, string) WAF Group that contains the WAF rules.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
    
    _Example_
    
    ```
    f90712123fb02287348dd34c0a282bb9
    ```
    

#### Responses

*   **200** Successfully retrieved the WAF rules requested by the caller.
    
    Media type: `application/json`. Schema: `WafRulesEnvelope`.
    
    _Example: WafGroupPutResponse_
    
    ```
    {
      "data": [
        {
          "ruleId": "100001",
          "groupId": "f90712123fb02287348dd34c0a282bb9",
          "action": "monitor",
          "defaultAction": "challenge",
          "description": "Anomaly:Header:User-Agent - Missing"
        },
        {
          "ruleId": "100002",
          "groupId": "f90712123fb02287348dd34c0a282bb9",
          "action": "monitor",
          "defaultAction": "challenge",
          "description": "DoS - IE6 Binary POST"
        },
        {
          "ruleId": "100002A",
          "groupId": "f90712123fb02287348dd34c0a282bb9",
          "action": "monitor",
          "defaultAction": "challenge",
          "description": "DoS - CtrlFunc Botnet"
        }
      ]
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve details of a specific WAF rule.

`GET /organizations/{organizationId}/zones/{zoneId}/waf/rules/{ruleId}`

Operation ID: `getWafRule`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve details of a specific WAF rule by its ID. This endpoint provides comprehensive information about the rule's configuration and settings. Not applicable for zones using WAFv2. For any zones created after the 24.5 release, use the endpoints for WAF managed rulesets.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved details of the WAF rule requested by the caller.
    
    Media type: `application/json`. Schema: `WafRuleEnvelope`.
    
    _Example: WafRuleGetResponse_
    
    ```
    {
      "data": {
        "ruleId": "100001",
        "groupId": "f90712123fb02287348dd34c0a282bb9",
        "action": "monitor",
        "defaultAction": "challenge",
        "description": "Anomaly:Header:User-Agent - Missing"
      }
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Update the action of a specific WAF rule.

`PUT /organizations/{organizationId}/zones/{zoneId}/waf/rules/{ruleId}`

Operation ID: `updateWafRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update the action of a specific WAF rule. Use this endpoint to modify the security behavior and response actions of a WAF rule. Not applicable for zones using WAFv2. For any zones created after the 24.5 release, use the endpoints for WAF managed rulesets.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `WafRule`.

_Example: WafRulePutRequestBodyExample_

```
{
  "action": "monitor"
}
```

#### Responses

*   **200** Successfully updated the WAF rule specified by the caller.
    
    Media type: `application/json`. Schema: `WafRuleEnvelope`.
    
    _Example: WafRulePutResponse_
    
    ```
    {
      "data": {
        "ruleId": "100001",
        "groupId": "f90712123fb02287348dd34c0a282bb9",
        "action": "monitor",
        "defaultAction": "challenge",
        "description": "Anomaly:Header:User-Agent - Missing "
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve the speed settings for a zone.

`GET /organizations/{organizationId}/zones/{zoneId}/speed-settings`

Operation ID: `getSpeedSettings`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve speed settings for the specified zone. This endpoint provides information about performance optimizations.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the speed settings requested by the caller.
    
    Media type: `application/json`. Schema: `SpeedSettingsEnvelope`.
    
    _Example: SpeedSettingsResponse_
    
    ```
    {
      "data": {
        "brotliCompression": "off",
        "http2Prioritization": "off",
        "webp": "off",
        "polish": "off",
        "earlyHints": "off",
        "http3": "off",
        "http2ToOrigin": "off"
      }
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update the speed settings for a zone.

`PATCH /organizations/{organizationId}/zones/{zoneId}/speed-settings`

Operation ID: `updateSpeedSettings`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update speed settings for the specified zone. Use this endpoint to modify performance optimizations.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `SpeedSetting`.

_Example: SpeedSettingsPatchRequestBodyExample_

```
{
  "brotliCompression": "off",
  "http2Prioritization": "off"
}
```

#### Responses

*   **200** Successfully updated the speed settings requested by the caller.
    
    Media type: `application/json`. Schema: `SpeedSettingsEnvelope`.
    
    _Example: SpeedSettingsResponse_
    
    ```
    {
      "data": {
        "brotliCompression": "off",
        "http2Prioritization": "off",
        "webp": "off",
        "polish": "off",
        "earlyHints": "off",
        "http3": "off",
        "http2ToOrigin": "off"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve the security settings for a zone.

`GET /organizations/{organizationId}/zones/{zoneId}/security-settings`

Operation ID: `getSecuritySettings`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve security settings for the specified zone. This endpoint provides information about security configurations and protection settings.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned security settings for zone.
    
    Media type: `application/json`. Schema: `SecuritySettingsEnvelope`.
    
    _Example: SecuritySettingsResponse_
    
    ```
    {
      "data": {
        "hsts": {
          "enabled": false,
          "includeSubdomains": false,
          "maxAge": 200,
          "preload": false
        },
        "securityLevel": "medium",
        "tls13Enabled": false,
        "alwaysUseHttps": true
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update the security settings for a zone.

`PATCH /organizations/{organizationId}/zones/{zoneId}/security-settings`

Operation ID: `updateSecuritySettings`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update security settings for the specified zone. Use this endpoint to modify security configurations and protection settings.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `SecuritySetting`.

_Example: SecuritySettingsUpdateRequestBodyExample_

```
{
  "hsts": {
    "enabled": false,
    "preload": true
  },
  "securityLevel": "high",
  "tls13Enabled": true,
  "alwaysUseHttps": true
}
```

#### Responses

*   **200** Successfully updated the security settings.
    
    Media type: `application/json`. Schema: `SecuritySettingsEnvelope`.
    
    _Example SecuritySettingsResponse: same as GET /organizations/{organizationId}/zones/{zoneId}/security-settings 200 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Purge the cache for the host specified in the request body.

`POST /organizations/{organizationId}/zones/{zoneId}/cachepurge`

Operation ID: `cachePurge`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Purge cache for the specified zone. Use this endpoint to clear cached content and force fresh content to be fetched from origin servers. Unlike storefronts, SCAPI only uses server-side web tier caching, and eCDN edge caching is not at all applicable to SCAPI.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CachePurgeRequest`.

_Example: CachePurgeRequest_

```
{
  "path": "www.sfcc-ecdn-test5.net/dw/shop/v21_9/products",
  "tags": [
    "product-123",
    "category-456"
  ]
}
```

#### Responses

*   **200** Successfully returned the complete operationId statuses for the rule list operations that the server processed.
    
    Media type: `application/json`. Schema: `CachePurgeResponseEnvelope`.
    
    _Example: CachePurgeResponse_
    
    ```
    {
      "data": {
        "cachePurged": true,
        "details": "Cache purged successfully"
      }
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Enable or disable the OCAPI Caching page rule.

`PATCH /organizations/{organizationId}/zones/{zoneId}/ocapicachingpagerule`

Operation ID: `toggleOcapiCachingPageRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Use this endpoint to toggle the caching behavior for caching requests.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `OCAPICachingToggleRequest`.

_Example: CachingToggleRequest_

```
{
  "enableOCAPICachingPageRule": true
}
```

#### Responses

*   **200** Successfully returned the current state of the Caching page rule.
    
    Media type: `application/json`. Schema: `OCAPICachingToggleRequest`.
    
    _Example: CachingToggleResponse_
    
    ```
    {
      "data": {
        "enableOCAPICachingPageRule": true
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve existing cache rules.

`GET /organizations/{organizationId}/zones/{zoneId}/cache/rules`

Operation ID: `getCacheRules`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve the list of cache rules for a zone.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the list of cache rules.
    
    Media type: `application/json`. Schema: `CacheRulesEnvelope`.
    
    _Example: CacheRulesResponse_
    
    ```
    {
      "data": [
        {
          "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
          "description": "Cache static assets on product pages",
          "expression": "(http.request.uri.path matches \"^/product/.*\")",
          "action": "cache",
          "excludeQueryStrings": [
            "gclid",
            "utm_campaign"
          ],
          "ignoreQueryStringsOrder": true,
          "respectStrongEtags": false,
          "lastUpdated": "2022-01-01T05:20:00Z",
          "enabled": true
        },
        {
          "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
          "description": "Cache category pages",
          "expression": "(http.request.uri.path matches \"^/category/.*\")",
          "action": "cache",
          "ignoreQueryStringsOrder": false,
          "respectStrongEtags": true,
          "lastUpdated": "2022-12-14T21:25:22.329194Z",
          "enabled": false
        }
      ]
    }
    ```
    
*   **401** You are not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** You do not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The requested resource was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create a cache rule.

`POST /organizations/{organizationId}/zones/{zoneId}/cache/rules`

Operation ID: `createCacheRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Create a cache rule for a zone.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CacheRulesPostRequest`.

_Example: CacheRulesPostRequestBodyExample_

```
{
  "description": "Cache static assets on product pages.",
  "expression": "(http.request.uri.path matches \"^/product/.*\")",
  "action": "cache",
  "excludeQueryStrings": [
    "gclid",
    "utm_campaign"
  ],
  "ignoreQueryStringsOrder": true,
  "respectStrongEtags": false,
  "enabled": true
}
```

#### Responses

*   **201** Successfully created the cache rule.
    
    Media type: `application/json`. Schema: `CacheRulesEnvelope`.
    
    _Example: CacheRuleResponse_
    
    ```
    {
      "data": [
        {
          "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
          "description": "Cache static assets on product pages",
          "expression": "(http.request.uri.path matches \"^/product/.*\")",
          "action": "cache",
          "excludeQueryStrings": [
            "gclid",
            "utm_campaign"
          ],
          "ignoreQueryStringsOrder": true,
          "respectStrongEtags": false,
          "lastUpdated": "2022-01-01T05:20:00Z",
          "enabled": true
        }
      ]
    }
    ```
    
*   **400** Invalid request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** You are not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** You do not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete a cache rule.

`DELETE /organizations/{organizationId}/zones/{zoneId}/cache/rules/{ruleId}`

Operation ID: `deleteCacheRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Delete an existing cache rule.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the cache rule.
*   **401** You are not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** You do not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The requested resource was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update a cache rule.

`PATCH /organizations/{organizationId}/zones/{zoneId}/cache/rules/{ruleId}`

Operation ID: `updateCacheRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update an existing cache rule.

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CacheRulesPatchRequest`.

_Example: CacheRulesPatchRequestBodyExample_

```
{
  "description": "Updated description for the cache rule",
  "enabled": false
}
```

#### Responses

*   **200** Successfully updated the cache rule.
    
    Media type: `application/json`. Schema: `CacheRulesEnvelope`.
    
    _Example CacheRuleResponse: same as POST /organizations/{organizationId}/zones/{zoneId}/cache/rules 201 response._
    
*   **400** Invalid request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** You are not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** You do not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The requested resource was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET List certificates for a zone.

`GET /organizations/{organizationId}/zones/{zoneId}/certificates`

Operation ID: `getCertificates`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

For information on automatic certificates, see [eCDN Automatic Certificates](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-automatic-certs.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Successfully retrieved the list of certificates for the specified zone.
    
    Media type: `application/json`. Schema: `CertificatesEnvelope`.
    
    _Example: CertificatesGetResponse1_
    
    ```
    {
      "data": [
        {
          "certificateId": "14b72e2c-db8e-40ec-9f89-d80ca431a36e",
          "status": "PENDING_VALIDATION",
          "minTlsVersion": "1.2",
          "certificateType": "automatic",
          "certificateAuthority": "google",
          "certificateValidation": "txt",
          "certificateVerificationTXTName": "_acme-challenge.test.example.com",
          "certificateVerificationTXTValue": "DBCtxdyQSyo9eXxys-uGVCwPFHLsc8_lu11QetQz4IA",
          "certificateVerificationStatus": "PENDING",
          "customHostnameId": "6c8beb36-a679-4eca-a09a-e3d6aca12787",
          "customHostname": "test.example.com",
          "customHostnameStatus": "ACTIVE"
        },
        {
          "certificateId": "16b3f671-de15-4ba8-8c02-84ba011b7751",
          "hosts": [
            "shop.example.com"
          ],
          "expiresOn": "2024-05-27T22:58:10Z",
          "uploadedOn": "2024-02-27T22:58:11Z",
          "issuer": "LetsEncrypt",
          "signature": "SHA256WithRSA",
          "status": "ACTIVE",
          "minTlsVersion": "1.2",
          "certificateType": "automatic",
          "certificateAuthority": "lets_encrypt",
          "certificateValidation": "http",
          "customHostnameId": "dd625c6d-8553-4d14-abc2-6d747866c8d9",
          "customHostname": "shop.example.com",
          "customHostnameStatus": "ACTIVE"
        },
        {
          "certificateId": "f135013c-2bf7-4225-b043-84cf35a93e12",
          "hosts": [
            "*.example.com"
          ],
          "expiresOn": "2024-04-09T20:36:39Z",
          "uploadedOn": "2024-03-19T22:32:41Z",
          "issuer": "LetsEncrypt",
          "signature": "SHA256WithRSA",
          "status": "ACTIVE",
          "minTlsVersion": "1.2",
          "certificateType": "custom",
          "customHostnameId": "6567aee6-bdbe-4cb1-9f4b-73209c5e867a",
          "customHostname": "www.example.com",
          "customHostnameStatus": "ACTIVE"
        }
      ]
    }
    ```
    
    _Example: CertificatesGetResponse2_
    
    ```
    {
      "data": [
        {
          "certificateId": "dc95610a-9a20-4e24-b6d6-232df5fc32d1",
          "hosts": [
            "shop.example.com"
          ],
          "expiresOn": "2024-05-14T23:00:45Z",
          "uploadedOn": "2024-03-19T21:28:36Z",
          "issuer": "LetsEncrypt",
          "signature": "SHA256WithRSA",
          "status": "ACTIVE",
          "certificateType": "custom_legacy"
        },
        {
          "certificateId": "3a2a71c6-c00f-41c4-86dd-d6dc434851d5",
          "hosts": [
            "www.example.com"
          ],
          "expiresOn": "2024-04-15T17:07:59Z",
          "uploadedOn": "2024-03-19T21:28:36Z",
          "issuer": "LetsEncrypt",
          "signature": "SHA256WithRSA",
          "status": "ACTIVE",
          "certificateType": "custom_legacy"
        }
      ]
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Add certificate for a zone.

`POST /organizations/{organizationId}/zones/{zoneId}/certificates`

Operation ID: `addCertificateForZone`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

For information on automatic certificates, see [eCDN Automatic Certificates](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-automatic-certs.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CertificateRequest`.

_Example: CertificatePostRequestBodyExample_

```
{
  "hostname": "www.salesforce.com",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----",
  "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----"
}
```

#### Responses

*   **201** Returned information about the added certificate.
    
    Media type: `application/json`. Schema: `CertificateEnvelope`.
    
    _Example: CertificatePostResponse1_
    
    ```
    {
      "data": {
        "certificateId": "730a1be4-22d7-11eb-aff1-0242ac120002",
        "status": "ACTIVE",
        "hosts": [
          "salesforce.com"
        ],
        "expiresOn": "2022-01-12T04:15:57Z",
        "uploadedOn": "2020-01-12T04:15:57Z",
        "issuer": "DigiCert",
        "signature": "SHA256WithRSA",
        "certificateType": "custom",
        "customHostnameVerificationTXTName": "_salesforce.com",
        "customHostnameVerificationTXTValue": "4c9c3f4f-2e91-4c5d-a902-f12f9c285b9e",
        "customHostnameId": "465a48f6-3d98-4c15-9312-211984ee8629",
        "customHostname": "test.salesforce.com",
        "customHostnameStatus": "ACTIVE"
      }
    }
    ```
    
    _Example: CertificatePostResponse2_
    
    ```
    {
      "data": {
        "certificateId": "730a1be4-22d7-11eb-aff1-0242ac120002",
        "hosts": [
          "salesforce.com"
        ],
        "expiresOn": "2022-01-12T04:15:57Z",
        "uploadedOn": "2020-01-12T04:15:57Z",
        "status": "PENDING",
        "certificateType": "automatic",
        "certificateAuthority": "google",
        "certificateValidation": "txt",
        "certificateVerificationTXTName": "_acme-challenge.test.example.com",
        "certificateVerificationTXTValue": "SH5Yet8S5dBwPXcRcCjXdf9FXMBVnQjihQ8oN8LoMv0",
        "certificateVerificationStatus": "PENDING",
        "customHostnameVerificationTXTName": "_salesforce.com",
        "customHostnameVerificationTXTValue": "4c9c3f4f-2e91-4c5d-a902-f12f9c285b9e",
        "customHostnameId": "465a48f6-3d98-4c15-9312-211984ee8629",
        "customHostname": "test.salesforce.com",
        "customHostnameStatus": "ACTIVE"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **409** The request sent by the caller has conflicts.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Conflict_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/conflicted",
      "title": "Resource Conflict",
      "detail": "The request made for the resource is not valid."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete a custom hostname and the certificate associated with it. Note that a valid certificate is necessary for a site to remain operational. DELETING A CERTIFICATE THAT IS IN USE CAN RESULT IN DOWNTIME.

`DELETE /organizations/{organizationId}/zones/{zoneId}/certificates/{certificateId}`

Operation ID: `deleteCertificate`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

This operation removes both the custom hostname configuration and the associated SSL certificate.

#### Parameters

*   `certificateId` (path, string, required) The unique identifier of a certificate.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the custom hostname and the certificate associated with it.
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update the certificate for a given certificateId for a particular zone.

`PATCH /organizations/{organizationId}/zones/{zoneId}/certificates/{certificateId}`

Operation ID: `updateCertificate`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

For information on automatic certificates, see [eCDN Automatic Certificates](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-automatic-certs.html).

#### Parameters

*   `certificateId` (path, string, required) The unique identifier of a certificate.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CertificateRequest`.

_Example: CertificateUpdateRequestBodyExample_

```
{
  "hostname": "www.salesforce.com",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBTLbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----",
  "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----"
}
```

#### Responses

*   **200** Successfully updated the certificate requested by the caller.
    
    Media type: `application/json`. Schema: `CertificateEnvelope`.
    
    _Example CertificateUpdateResponse2: same as POST /organizations/{organizationId}/zones/{zoneId}/certificates 201 response._
    
    _Example: CertificateUpdateResponse1_
    
    ```
    {
      "data": {
        "certificateId": "730a1be4-22d7-11eb-aff1-0242ac120002",
        "status": "ACTIVE",
        "hosts": [
          "salesforce.com"
        ],
        "expiresOn": "2022-01-12T04:15:57Z",
        "uploadedOn": "2020-01-12T04:15:57Z",
        "customHostnameVerificationTXTName": "_salesforce.com",
        "customHostnameVerificationTXTValue": "4c9c3f4f-2e91-4c5d-a902-f12f9c285b9e",
        "customHostnameId": "465a48f6-3d98-4c15-9312-211984ee8629",
        "customHostname": "test.salesforce.com",
        "customHostnameStatus": "ACTIVE",
        "certificateType": "custom"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Trigger the validation of a custom hostname.

`PATCH /organizations/{organizationId}/zones/{zoneId}/certificates/custom-hostnames/{customHostnameId}`

Operation ID: `validateCustomHostname`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

This endpoint initiates the DNS validation process for custom hostnames associated with the zone.

#### Parameters

*   `customHostnameId` (path, string, required) The unique identifier of a custom hostname.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully triggered the custom hostname validation process.
    
    Media type: `application/json`. Schema: `CustomHostnameValidationEnvelope`.
    
    _Example: CustomHostnamesPatchResponse_
    
    ```
    {
      "data": {
        "customHostnameId": "465a48f6-3d98-4c15-9312-211984ee8629",
        "customHostname": "test.salesforce.com",
        "customHostnameVerificationTXTName": "_salesforce.com",
        "customHostnameVerificationTXTValue": "4c9c3f4f-2e91-4c5d-a902-f12f9c285b9e",
        "customHostnameStatus": "ACTIVE"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get all MRT rules.

`GET /organizations/{organizationId}/zones/{zoneId}/mrtrules`

Operation ID: `getMrtRules`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved all MRT rules.
    
    Media type: `application/json`. Schema: `MRTRulesResponseEnvelope`.
    
    _Example: MrtRulesGetResponse_
    
    ```
    {
      "data": {
        "ruleset": {
          "id": "12345678901234asdfasfasdf1234567",
          "name": "MRT Rules",
          "lastUpdated": "2022-09-27T18:32:34.675182Z",
          "rules": [
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"/on/path1/.*\" or http.request.uri.path matches \"/on/path2/.*\" or http.request.uri.path matches \".*routeDetails=true\" or http.request.uri.path eq \"/path3.txt\" ))",
              "description": "Phased rollout rule for dev-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1234567",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            },
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host in {\"test-customer.salesforce.com\" \"test2-customer.salesforce.com\"} and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))",
              "description": "Phased rollout rule for test-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1233333",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            },
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host eq \"prd-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))",
              "description": "Phased rollout rule for prd-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "98745678901234asdfasfasdf1234567",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            }
          ]
        }
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create MRT rules to route to a new MRT environment.

`POST /organizations/{organizationId}/zones/{zoneId}/mrtrules`

Operation ID: `createMrtRules`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `MRTRulesPostRequest`.

_Example: MrtRulesPostRequestSingleHostnameBodyExample_

```
{
  "mrtHostname": "customer.mobify-storefront.com",
  "expressions": [
    "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"/on/path1/.*\" or http.request.uri.path matches \"/on/path2/.*\" or http.request.uri.path matches \".*routeDetails=true\" or http.request.uri.path eq \"/path3.txt\" ))"
  ],
  "descriptions": [
    "Phased rollout rule for dev-customer.salesforce.com"
  ]
}
```

_Example: MrtRulesPostRequestMultipleHostnamesBodyExample_

```
{
  "mrtHostname": "customer.mobify-storefront.com",
  "expressions": [
    "(http.host in {\"test-customer.salesforce.com\" \"test2-customer.salesforce.com\"} and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))"
  ],
  "descriptions": [
    "Phased rollout rule for test-customer.salesforce.com and test2-customer.salesforce.com"
  ]
}
```

#### Responses

*   **201** Created MRT rules to route to a new MRT environment.
    
    Media type: `application/json`. Schema: `MRTRulesResponseEnvelope`.
    
    _Example: MrtRulesPostResponseSingleHostname_
    
    ```
    {
      "data": {
        "ruleset": {
          "id": "12345678901234asdfasfasdf1234567",
          "name": "MRT Rules",
          "lastUpdated": "2022-09-27T18:32:34.675182Z",
          "rules": [
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"/on/path1/.*\" or http.request.uri.path matches \"/on/path2/.*\" or http.request.uri.path matches \".*routeDetails=true\" or http.request.uri.path eq \"/path3.txt\" ))",
              "description": "Phased rollout rule for dev-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1234567",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            }
          ]
        }
      }
    }
    ```
    
    _Example: MrtRulesPostResponseMultipleHostnames_
    
    ```
    {
      "data": {
        "ruleset": {
          "id": "12345678901234asdfasfasdf1234567",
          "name": "MRT Rules",
          "lastUpdated": "2022-09-27T18:32:34.675182Z",
          "rules": [
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host in {\"test-customer.salesforce.com\" \"test2-customer.salesforce.com\"} and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))",
              "description": "Phased rollout rule for test-customer.salesforce.com and test2-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1234567",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            }
          ]
        }
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update the MRT environment hostname or add MRT rules to route to an existing MRT environment.

`PATCH /organizations/{organizationId}/zones/{zoneId}/mrtrules`

Operation ID: `updateMrtRuleset`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `MRTRulesetPatchRequest`.

_Example: MrtRulesetPatchRequestUpdateHostnameBodyExample_

```
{
  "oldMrtHostname": "old-hostname.mobify-storefront.com",
  "mrtHostname": "new-hostname.mobify-storefront.com"
}
```

_Example: MrtRulesetPatchRequestAddRulesBodyExample_

```
{
  "mrtHostname": "customer.mobify-storefront.com",
  "expressions": [
    "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"/on/path1/.*\" or http.request.uri.path matches \"/on/path2/.*\" or http.request.uri.path matches \".*routeDetails=true\" or http.request.uri.path eq \"/path3.txt\" ))",
    "(http.host in {\"test-customer.salesforce.com\" \"test2-customer.salesforce.com\"} and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))"
  ],
  "descriptions": [
    "Phased rollout rule for dev-customer.salesforce.com"
  ]
}
```

#### Responses

*   **200** Updated the MRT environment hostname or added MRT rules to route to an existing MRT environment.
    
    Media type: `application/json`. Schema: `MRTRulesResponseEnvelope`.
    
    _Example: MrtRulesetPatchResponseUpdateHostname_
    
    ```
    {
      "data": {
        "ruleset": {
          "id": "12345678901234asdfasfasdf1234567",
          "name": "MRT Rules",
          "lastUpdated": "2022-09-27T18:32:34.675182Z",
          "rules": [
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"/on/path1/.*\" or http.request.uri.path matches \"/on/path2/.*\" or http.request.uri.path matches \".*routeDetails=true\" or http.request.uri.path eq \"/path3.txt\" ))",
              "description": "Phased rollout rule for dev-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1234567",
              "enabled": true,
              "mrtHostname": "new-hostname.mobify-storefront.com"
            },
            {
              "id": "12345678901234asdfasfasdf1234568",
              "expression": "(http.host in {\"test-customer.salesforce.com\" \"test2-customer.salesforce.com\"} and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))",
              "description": "Phased rollout rule for test-customer.salesforce.com and test2-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1234568",
              "enabled": true,
              "mrtHostname": "new-hostname.mobify-storefront.com"
            }
          ]
        }
      }
    }
    ```
    
    _Example: MrtRulesetPatchResponseAddRules_
    
    ```
    {
      "data": {
        "ruleset": {
          "id": "12345678901234asdfasfasdf1234567",
          "name": "MRT Rules",
          "lastUpdated": "2022-09-27T18:32:34.675182Z",
          "rules": [
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"/on/path1/.*\" or http.request.uri.path matches \"/on/path2/.*\" or http.request.uri.path matches \".*routeDetails=true\" or http.request.uri.path eq \"/path3.txt\" ))",
              "description": "Phased rollout rule for dev-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1234567",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            },
            {
              "id": "12345678901234asdfasfasdf1234568",
              "expression": "(http.host in {\"test-customer.salesforce.com\" \"test2-customer.salesforce.com\"} and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))",
              "description": "Phased rollout rule for test-customer.salesforce.com and test2-customer.salesforce.com",
              "lastUpdated": "2022-09-15T21:14:42.372459Z",
              "ref": "12345678901234asdfasfasdf1234568",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            }
          ]
        }
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete the MRT ruleset and all rules within the ruleset.

`DELETE /organizations/{organizationId}/zones/{zoneId}/mrtrules/{rulesetId}`

Operation ID: `deleteMrtRuleset`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html).

#### Parameters

*   `rulesetId` (path, string, required) The unique identifier of a managed ruleset.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted the MRT ruleset and all rules within the ruleset.
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete an MRT rule.

`DELETE /organizations/{organizationId}/zones/{zoneId}/mrtrules/{rulesetId}/rules/{ruleId}`

Operation ID: `deleteMrtRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `rulesetId` (path, string, required) The unique identifier of a managed ruleset.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted an MRT rule.
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update an MRT rule.

`PATCH /organizations/{organizationId}/zones/{zoneId}/mrtrules/{rulesetId}/rules/{ruleId}`

Operation ID: `updateMrtRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `rulesetId` (path, string, required) The unique identifier of a managed ruleset.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `MRTRulePatchRequest`.

_Example: MrtRulePatchRequestBodyExample_

```
{
  "enabled": true,
  "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))",
  "description": "Phased rollout rule for dev-customer.salesforce.com"
}
```

#### Responses

*   **200** Successfully updated the MRT rule.
    
    Media type: `application/json`. Schema: `MRTRulesResponseEnvelope`.
    
    _Example: MrtRulePatchResponse_
    
    ```
    {
      "data": {
        "ruleset": {
          "id": "12345678901234asdfasfasdf1234567",
          "name": "MRT Rules",
          "lastUpdated": "2022-09-15T21:14:42.372459Z",
          "rules": [
            {
              "id": "12345678901234asdfasfasdf1234567",
              "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path4/.*\" or http.request.uri.path matches \"^.*/path5/.*/products/.*\"))",
              "description": "Phased rollout rule for dev-customer.salesforce.com",
              "lastUpdated": "2022-09-27T18:32:34.675182Z",
              "ref": "12345678901234asdfasfasdf1234567",
              "enabled": true,
              "mrtHostname": "customer.mobify-storefront.com"
            }
          ]
        }
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create Logpush ownership token file.

`POST /organizations/{organizationId}/zones/{zoneId}/logpush/ownership`

Operation ID: `createLogpushOwnership`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `LogpushOwnershipPostRequest`.

_Example: LogpushOwnershipPostRequestBodyExample_

```
{
  "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256"
}
```

#### Responses

*   **201** Created a new Logpush Ownership token.
    
    Media type: `application/json`. Schema: `LogpushOwnershipPostResponse`.
    
    _Example: LogpushOwnershipPostResponse_
    
    ```
    {
      "data": {
        "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
        "fileName": "site-name/20230101/ownership-challenge-f1234567.txt"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET List Logpush job.

`GET /organizations/{organizationId}/zones/{zoneId}/logpush/jobs`

Operation ID: `listLogpushJob`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Returned all jobs with details for the zone.
    
    Media type: `application/json`. Schema: `LogpushJobsEnvelope`.
    
    _Example: LogpushGetListJob_
    
    ```
    {
      "data": [
        {
          "jobId": 123456,
          "name": "example1-job-name",
          "logType": "http_requests",
          "logFields": [
            "ClientRequestBytes",
            "ClientRequestHost",
            "ClientRequestMethod"
          ],
          "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
          "lastComplete": "2023-03-14T02:09:32Z",
          "createdOn": "2023-01-01T00:00:27Z"
        },
        {
          "jobId": 123457,
          "name": "example2-job-name",
          "logType": "firewall_events",
          "logFields": [
            "RuleID",
            "ClientRequestUserAgent",
            "ClientRequestPath"
          ],
          "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}, {\"key\":\"EdgeResponseStatus\",\"operator\":\"in\",\"value\":[502, 503, 504, 520, 521, 522, 522, 523, 524, 525, 526, 530]}]}}",
          "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
          "lastComplete": "2023-03-22T02:09:32Z",
          "createdOn": "2023-01-03T00:00:27Z"
        },
        {
          "jobId": 123458,
          "name": "example3-job-name",
          "logType": "page_shield_events",
          "logFields": [
            "Action",
            "CSPDirective",
            "Host",
            "PageURL",
            "PolicyID",
            "ResourceType",
            "Timestamp",
            "URL",
            "URLHost"
          ],
          "destinationPath": "s3://customer-bucket/site-name/page-shield-events/{DATE}?region=us-east-1&sse=AES256",
          "lastComplete": "2025-01-02T02:09:32Z",
          "createdOn": "2025-01-01T00:00:27Z"
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create Logpush job.

`POST /organizations/{organizationId}/zones/{zoneId}/logpush/jobs`

Operation ID: `createLogpushJob`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `LogpushCreateRequest`.

_Example: LogpushCreateRequestBodyExample1_

```
{
  "name": "example-job-name",
  "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
  "ownershipChallengeToken": "abc00000000000000000000",
  "logFields": [
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestMethod"
  ],
  "logType": "http_requests"
}
```

_Example: LogpushCreateRequestBodyExample2_

```
{
  "name": "example-job-name-with-filter",
  "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
  "ownershipChallengeToken": "abc00000000000000000000",
  "logFields": [
    "ClientRequestBytes",
    "ClientRequestPath",
    "ClientRequestHost",
    "ClientRequestMethod",
    "EdgeResponseStatus"
  ],
  "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}, {\"key\":\"EdgeResponseStatus\",\"operator\":\"in\",\"value\":[502, 503, 504, 520, 521, 522, 522, 523, 524, 525, 526, 530]}]}}",
  "logType": "http_requests"
}
```

_Example: LogpushCreateRequestBodyExample3_

```
{
  "name": "example-job-name",
  "destinationPath": "s3://customer-bucket/site-name/page-shield-events/{DATE}?region=us-east-1&sse=AES256",
  "ownershipChallengeToken": "abc00000000000000000000",
  "logFields": [
    "Action",
    "CSPDirective",
    "Host",
    "PageURL",
    "PolicyID",
    "ResourceType",
    "Timestamp",
    "URL",
    "URLHost"
  ],
  "logType": "page_shield_events"
}
```

#### Responses

*   **201** Successfully created the Logpush job and returned the job details.
    
    Media type: `application/json`. Schema: `LogpushEnvelope`.
    
    _Example: LogpushCreateResponse1_
    
    ```
    {
      "data": {
        "jobId": 123456,
        "name": "example-job-name",
        "logType": "http_requests",
        "logFields": [
          "ClientRequestBytes",
          "ClientRequestHost",
          "ClientRequestMethod"
        ],
        "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
        "enabled": false,
        "createdOn": "2023-01-01T00:00:27Z"
      }
    }
    ```
    
    _Example: LogpushCreateResponse2_
    
    ```
    {
      "data": {
        "jobId": 123456,
        "name": "example-job-name-with-filter",
        "logType": "http_requests",
        "logFields": [
          "ClientRequestBytes",
          "ClientRequestPath",
          "ClientRequestHost",
          "ClientRequestMethod",
          "EdgeResponseStatus"
        ],
        "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}, {\"key\":\"EdgeResponseStatus\",\"operator\":\"in\",\"value\":[502, 503, 504, 520, 521, 522, 522, 523, 524, 525, 526, 530]}]}}",
        "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
        "enabled": false,
        "createdOn": "2023-01-01T00:00:27Z"
      }
    }
    ```
    
    _Example: LogpushCreateResponse3_
    
    ```
    {
      "data": {
        "jobId": 123458,
        "name": "example-job-name",
        "logType": "page_shield_events",
        "logFields": [
          "Action",
          "CSPDirective",
          "Host",
          "PageURL",
          "PolicyID",
          "ResourceType",
          "Timestamp",
          "URL",
          "URLHost"
        ],
        "destinationPath": "s3://customer-bucket/site-name/page-shield-events/{DATE}?region=us-east-1&sse=AES256",
        "enabled": true,
        "createdOn": "2025-01-01T00:00:27Z"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to therequested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get Logpush job details.

`GET /organizations/{organizationId}/zones/{zoneId}/logpush/jobs/{jobId}`

Operation ID: `getLogpushJob`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).

#### Parameters

*   `jobId` (path, string, required) The unique identifier of a logpush job.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Returned job details for the specified Logpush job ID.
    
    Media type: `application/json`. Schema: `LogpushEnvelope`.
    
    _Example: LogpushGetJobById1_
    
    ```
    {
      "data": {
        "jobId": 123456,
        "name": "example-job-name",
        "logType": "http_requests",
        "logFields": [
          "ClientRequestBytes",
          "ClientRequestHost",
          "ClientRequestMethod"
        ],
        "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
        "lastComplete": "2023-03-14T02:09:32Z",
        "createdOn": "2023-01-01T00:00:27Z"
      }
    }
    ```
    
    _Example: LogpushGetJobById2_
    
    ```
    {
      "data": {
        "jobId": 123456,
        "name": "example-job-name",
        "logType": "http_requests",
        "logFields": [
          "ClientRequestBytes",
          "ClientRequestHost",
          "ClientRequestMethod"
        ],
        "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
        "lastComplete": "2023-03-14T02:09:32Z",
        "lastError": "2023-03-16T02:00:00Z",
        "errorMessage": "No permissions to write to destination bucket",
        "createdOn": "2023-01-01T00:00:27Z"
      }
    }
    ```
    
    _Example: LogpushGetJobById3_
    
    ```
    {
      "data": {
        "jobId": 123456,
        "name": "example-job-name",
        "logType": "http_requests",
        "logFields": [
          "ClientRequestBytes",
          "ClientRequestPath",
          "ClientRequestHost",
          "ClientRequestMethod",
          "EdgeResponseStatus"
        ],
        "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}, {\"key\":\"EdgeResponseStatus\",\"operator\":\"in\",\"value\":[502, 503, 504, 520, 521, 522, 522, 523, 524, 525, 526, 530]}]}}",
        "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
        "lastComplete": "2023-03-14T02:09:32Z",
        "createdOn": "2023-01-01T00:00:27Z"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Update Logpush job.

`PUT /organizations/{organizationId}/zones/{zoneId}/logpush/jobs/{jobId}`

Operation ID: `updateLogpushJob`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).

#### Parameters

*   `jobId` (path, string, required) The unique identifier of a logpush job.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `LogpushUpdateRequest`.

_Example: LogpushUpdateRequestBodyExample_

```
{
  "enabled": true,
  "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
  "logFields": [
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestMethod"
  ]
}
```

#### Responses

*   **200** Successfully enabled or disabled the Logpush job and returned job details.
    
    Media type: `application/json`. Schema: `LogpushEnvelope`.
    
    _Example: LogpushUpdateResponse_
    
    ```
    {
      "data": {
        "jobId": 123456,
        "name": "example-job-name",
        "enabled": true,
        "logType": "http_requests",
        "logFields": [
          "ClientRequestBytes",
          "ClientRequestHost",
          "ClientRequestMethod"
        ],
        "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
        "lastComplete": "2023-03-14T02:09:32Z",
        "lastError": "2023-01-01T00:00:27Z",
        "errorMessage": ""
      }
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete Logpush job by job ID.

`DELETE /organizations/{organizationId}/zones/{zoneId}/logpush/jobs/{jobId}`

Operation ID: `deleteLogpushJob`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).

#### Parameters

*   `jobId` (path, string, required) The unique identifier of a logpush job.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted the Logpush job for the specified job ID.
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get a OWASP ModSecurity Core Rule Set.

`GET /organizations/{organizationId}/zones/{zoneId}/firewall/waf/packages/owasp`

Operation ID: `getOwaspWafPackage`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve OWASP WAF package information for the specified zone. This endpoint provides details about the OWASP security rules and configurations.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved the OWASP ModSecurity Core Rule Set.
    
    Media type: `application/json`. Schema: `WAFRulePackageEnvelope`.
    
    _Example: WafPackagesGetExample_
    
    ```
    {
      "data": {
        "id": "c504870194831cd12c3fc0284f294abb",
        "name": "OWASP ModSecurity Core Rule Set",
        "description": "OWASP Core Ruleset (2013) provides protection against common attack categories, including SQL Injection and Cross-Site Scripting.",
        "zone_id": "56702a674281951f541f9f304f7431f0",
        "detection_mode": "anomaly",
        "sensitivity": "low",
        "action_mode": "simulate"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Patch a OWASP ModSecurity Core Rule Set.

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall/waf/packages/owasp`

Operation ID: `patchOwaspWafPackage`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update OWASP WAF package settings for the specified zone. Use this endpoint to modify OWASP security rule configurations.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `WafPackagePatchRequest`.

_Example: WafPackagesPatchRequestBodyExample_

```
{
  "sensitivity": "low",
  "action_mode": "simulate"
}
```

#### Responses

*   **200** Successfully patched the OWASP ModSecurity Core Rule Set.
    
    Media type: `application/json`. Schema: `WAFRulePackageEnvelope`.
    
    _Example WafPackagesGetExample: same as GET /organizations/{organizationId}/zones/{zoneId}/firewall/waf/packages/owasp 200 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve existing custom rules.

`GET /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Operation ID: `getCustomRules`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve existing custom rules. See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Successfully returned the list of custom rules requested by the caller.
    
    Media type: `application/json`. Schema: `CustomRulesEnvelope`.
    
    _Example: CustomRulesResponse_
    
    ```
    {
      "data": [
        {
          "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
          "description": "Block traffic for malformed URL requests",
          "expression": "(http.request.uri.path matches \"^/path1/.*\")",
          "actions": [
            "block"
          ],
          "lastUpdated": "2022-12-14T21:25:22.329194Z",
          "enabled": false
        },
        {
          "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
          "description": "Skip user agent",
          "expression": "(http.user_agent contains \"Client\")",
          "actions": [
            "skip_custom_rules, skip_waf"
          ],
          "lastUpdated": "2022-12-14T21:30:34.263795Z",
          "enabled": true
        }
      ]
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create a custom rule.

`POST /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Operation ID: `createCustomRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CustomRulesPostRequest`.

_Example: CustomRulesPostRequestBodyExample_

```
{
  "description": "Block traffic for malformed URL requests",
  "expression": "(http.request.uri.path matches \"^/path1/.*\")",
  "actions": [
    "block"
  ],
  "enabled": false,
  "position": {
    "before": "2c0fc9fa937b11eaa1b71c4d701ab86e"
  }
}
```

#### Responses

*   **201** Successfully created the custom rule requested by the caller.
    
    Media type: `application/json`. Schema: `CustomRuleEnvelope`.
    
    _Example: CustomRuleResponse_
    
    ```
    {
      "data": {
        "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
        "description": "Block traffic for malformed URL requests",
        "expression": "(http.request.uri.path matches \"^/path1/.*\")",
        "actions": [
          "block"
        ],
        "lastUpdated": "2022-12-14T21:25:22.329194Z",
        "enabled": false
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update the order of all existing custom rules.

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules`

Operation ID: `updateOrderOfCustomRules`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CustomRulesPatchOrderRequest`.

_Example: CustomRulesPatchOrderRequest_

```
{
  "ruleIds": [
    "ffffe61cf25e4ec49c34b029ff3060f7",
    "2c0fc9fa937b11eaa1b71c4d701ab86e"
  ]
}
```

#### Responses

*   **200** Successfully updated the order of existing custom rules as requested by the caller.
    
    Media type: `application/json`. Schema: `CustomRulesEnvelope`.
    
    _Example CustomRulesResponse: same as GET /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules 200 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve a specific custom rule.

`GET /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules/{ruleId}`

Operation ID: `getCustomRule`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the custom rule requested by the caller.
    
    Media type: `application/json`. Schema: `CustomRuleEnvelope`.
    
    _Example CustomRuleResponse: same as POST /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules 201 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete a specific custom rule.

`DELETE /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules/{ruleId}`

Operation ID: `deleteCustomRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the custom rule requested by the caller.
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update a specific custom rule.

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules/{ruleId}`

Operation ID: `updateCustomRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CustomRulesPatchRequest`.

_Example: CustomRulesPatchRequest_

```
{
  "description": "Updated description for the custom rule",
  "expression": "(http.request.uri.path matches \"^/updated-path/.*\")",
  "actions": [
    "block"
  ]
}
```

#### Responses

*   **200** Successfully updated the custom rule requested by the caller.
    
    Media type: `application/json`. Schema: `CustomRuleEnvelope`.
    
    _Example CustomRuleResponse: same as POST /organizations/{organizationId}/zones/{zoneId}/firewall-custom/rules 201 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve existing rate limiting rules.

`GET /organizations/{organizationId}/zones/{zoneId}/rate-limiting/rules`

Operation ID: `getRateLimitingRules`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the list of rate limiting rules requested by the caller.
    
    Media type: `application/json`. Schema: `RateLimitingRulesEnvelope`.
    
    _Example: RateLimitingRulesResponse_
    
    ```
    {
      "data": [
        {
          "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
          "description": "Rate limit /path1",
          "expression": "http.request.uri.path matches \"^/path1/.*\"",
          "characteristics": [
            "cf.unique_visitor_id"
          ],
          "action": "block",
          "period": 60,
          "requestsPerPeriod": 50,
          "mitigationTimeout": 600,
          "countingExpression": "http.request.uri.path matches \"^/path1/.*\" and http.response.code eq 400",
          "enabled": false,
          "lastUpdated": "2022-12-14T21:25:22.329194Z"
        },
        {
          "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
          "description": "Rate limit AS number 12345",
          "expression": "ip.src.asnum eq 12345",
          "characteristics": [
            "ip.src"
          ],
          "action": "managed_challenge",
          "period": 600,
          "requestsPerPeriod": 1000,
          "mitigationTimeout": 0,
          "enabled": true,
          "lastUpdated": "2022-12-14T21:47:24.323223Z"
        }
      ]
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create a rate limiting rule.

`POST /organizations/{organizationId}/zones/{zoneId}/rate-limiting/rules`

Operation ID: `createRateLimitingRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `RateLimitingRulesPostRequest`.

_Example: RateLimitingRulesPostRequestBodyExample_

```
{
  "description": "Rate limit /path1",
  "expression": "http.request.uri.path matches \"^/path1/.*\"",
  "characteristics": [
    "cf.unique_visitor_id"
  ],
  "action": "block",
  "period": 60,
  "requestsPerPeriod": 50,
  "mitigationTimeout": 600,
  "countingExpression": "http.request.uri.path matches \"^/path1/.*\" and http.response.code eq 400",
  "enabled": false,
  "position": {
    "before": "2c0fc9fa937b11eaa1b71c4d701ab86e"
  }
}
```

#### Responses

*   **201** Successfully created the rate limiting rule requested by the caller.
    
    Media type: `application/json`. Schema: `RateLimitingRuleEnvelope`.
    
    _Example: RateLimitingRuleResponse_
    
    ```
    {
      "data": {
        "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
        "description": "Rate limit /path1",
        "expression": "http.request.uri.path matches \"^/path1/.*\"",
        "characteristics": [
          "cf.unique_visitor_id"
        ],
        "action": "block",
        "period": 60,
        "requestsPerPeriod": 50,
        "mitigationTimeout": 600,
        "countingExpression": "http.request.uri.path matches \"^/path1/.*\" and http.response.code eq 400",
        "enabled": false,
        "lastUpdated": "2022-12-14T21:25:22.329194Z"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve a specific rate limiting rule.

`GET /organizations/{organizationId}/zones/{zoneId}/rate-limiting/rules/{ruleId}`

Operation ID: `getRateLimitingRule`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the rate limiting rule requested by the caller.
    
    Media type: `application/json`. Schema: `RateLimitingRuleEnvelope`.
    
    _Example RateLimitingRuleResponse: same as POST /organizations/{organizationId}/zones/{zoneId}/rate-limiting/rules 201 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete a specific rate limiting rule.

`DELETE /organizations/{organizationId}/zones/{zoneId}/rate-limiting/rules/{ruleId}`

Operation ID: `deleteRateLimitingRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the rate limiting rule requested by the caller.
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update a specific rate limiting rule.

`PATCH /organizations/{organizationId}/zones/{zoneId}/rate-limiting/rules/{ruleId}`

Operation ID: `updateRateLimitingRule`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).

#### Parameters

*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `RateLimitingRulesPatchRequest`.

_Example: RateLimitingRulesPatchRequest_

```
{
  "description": "Updated rate limiting rule description",
  "expression": "http.request.uri.path matches \"^/updated-path/.*\"",
  "characteristics": [
    "cf.unique_visitor_id"
  ],
  "action": "block",
  "period": 120,
  "requestsPerPeriod": 100,
  "mitigationTimeout": 1200,
  "countingExpression": "http.request.uri.path matches \"^/updated-path/.*\" and http.response.code eq 400",
  "enabled": true
}
```

#### Responses

*   **200** Successfully updated the rate limiting rule requested by the caller.
    
    Media type: `application/json`. Schema: `RateLimitingRuleEnvelope`.
    
    _Example RateLimitingRuleResponse: same as POST /organizations/{organizationId}/zones/{zoneId}/rate-limiting/rules 201 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve WAFv2 managed rulesets.

`GET /organizations/{organizationId}/zones/{zoneId}/firewall-managed/rulesets`

Operation ID: `getWafManagedRulesets`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN WAFv2](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-wafv2.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the list of WAFv2 managed rulesets.
    
    Media type: `application/json`. Schema: `WAFManagedRulesetsEnvelope`.
    
    _Example: WAFManagedRulesetsResponse_
    
    ```
    {
      "data": [
        {
          "name": "Managed Ruleset",
          "rulesetId": "efb7b8c949ac4650a09736fc376e9aee",
          "action": "default",
          "enabled": true
        },
        {
          "name": "OWASP Core Ruleset",
          "rulesetId": "4814384a9e5d4991b9815dcfc25d2f1f",
          "action": "log",
          "anomalyScoreThreshold": 25,
          "anomalyScore": "high",
          "paranoiaLevel": 1,
          "enabled": true
        },
        {
          "name": "Leaked Crednetials Check Ruleset",
          "rulesetId": "c2e184081120413c86c3ab7e14069605",
          "action": "block",
          "enabled": true
        }
      ]
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update WAFv2 managed ruleset.

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall-managed/rulesets/{rulesetId}`

Operation ID: `updateWafManagedRuleset`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN WAFv2](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-wafv2.html).

#### Parameters

*   `rulesetId` (path, string, required) The unique identifier of a managed ruleset.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `WAFManagedRulesetRequest`.

_Example: WAFManagedRulesetsUpdateRequestBodyExample_

```
{
  "action": "js_challenge",
  "enabled": true
}
```

#### Responses

*   **200** Successfully updated the WAFv2 managed rulesets.
    
    Media type: `application/json`. Schema: `WAFManagedRulesetEnvelope`.
    
    _Example: WAFManagedRulesetsUpdateResponse_
    
    ```
    {
      "data": {
        "name": "Managed Ruleset",
        "rulesetId": "efb7b8c949ac4650a09736fc376e9aee",
        "action": "js_challenge",
        "enabled": true
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Retrieve all rules in the specified WAFv2 managed ruleset.

`GET /organizations/{organizationId}/zones/{zoneId}/firewall-managed/rulesets/{rulesetId}/rules`

Operation ID: `getWafManagedRulesInRuleset`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

See [eCDN WAFv2](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-wafv2.html).

#### Parameters

*   `rulesetId` (path, string, required) The unique identifier of a managed ruleset.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the rules in the WAFv2 managed ruleset.
    
    Media type: `application/json`. Schema: `WAFManagedRulesEnvelope`.
    
    _Example: WAFManagedRulesResponse_
    
    ```
    {
      "data": [
        {
          "ruleId": "8ac8bc2a661e475d940980f9317f28e1",
          "action": "block",
          "score": 5,
          "categories": [
            "application-multi",
            "attack-generic",
            "capec-1000",
            "capec-210",
            "capec-220",
            "capec-272",
            "capec-274",
            "language-multi",
            "paranoia-level-1",
            "pci-12-1",
            "platform-multi"
          ],
          "description": "911100: Method is not allowed by policy",
          "lastUpdated": "2024-08-19T17:26:58.593021Z",
          "enabled": false
        },
        {
          "ruleId": "53065ac9bd9449f3895f1865467a0e6a",
          "action": "block",
          "score": 5,
          "categories": [
            "application-multi",
            "attack-reputation-scanner",
            "capec-1000",
            "capec-118",
            "capec-224",
            "capec-310",
            "capec-541",
            "language-multi",
            "paranoia-level-1",
            "pci-6-5-10",
            "platform-multi"
          ],
          "description": "913100: Found User-Agent associated with security scanner",
          "lastUpdated": "2024-08-19T17:26:58.593021Z",
          "enabled": true
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update a WAF managed rule in the specified WAFv2 managed ruleset.

`PATCH /organizations/{organizationId}/zones/{zoneId}/firewall-managed/rulesets/{rulesetId}/rules/{ruleId}`

Operation ID: `updateWafManagedRuleInRuleset`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN WAFv2](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-wafv2.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `rulesetId` (path, string, required) The unique identifier of a managed ruleset.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `ruleId` (path, string, required) The unique identifier of a rule.  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `WAFManagedRuleRequest`.

_Example: WAFManagedRulesUpdateRequestBodyExample_

```
{
  "action": "log",
  "enabled": true
}
```

#### Responses

*   **200** Successfully updated the WAF managed rule in the specified WAFv2 managed ruleset.
    
    Media type: `application/json`. Schema: `WAFManagedRuleEnvelope`.
    
    _Example: WAFManagedRulesUpdateResponse_
    
    ```
    {
      "data": {
        "ruleId": "53065ac9bd9449f3895f1865467a0e6a",
        "action": "log",
        "score": 5,
        "categories": [
          "application-multi",
          "attack-reputation-scanner",
          "capec-1000",
          "capec-118",
          "capec-224",
          "capec-310",
          "capec-541",
          "language-multi",
          "paranoia-level-1",
          "pci-6-5-10",
          "platform-multi"
        ],
        "description": "913100: Found User-Agent associated with security scanner",
        "lastUpdated": "2024-08-19T17:26:58.593021Z",
        "enabled": true
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Migrate a zone to WAFv2. Only applicable for existing zones using WAFv1.

`PUT /organizations/{organizationId}/zones/{zoneId}/firewall-managed/migration`

Operation ID: `migrateZoneToWafV2`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

See [eCDN WAFv2](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-wafv2.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully migrated the zone to WAFv2 and returned the WAF managed rulesets.
    
    Media type: `application/json`. Schema: `WAFManagedRulesetsEnvelope`.
    
    _Example WAFManagedRulesetsResponse: same as GET /organizations/{organizationId}/zones/{zoneId}/firewall-managed/rulesets 200 response._
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get the origin header modification associated with a zone. Only the \`mrt\` type is supported.

`GET /organizations/{organizationId}/zones/{zoneId}/origin-header-modification/{type}`

Operation ID: `getOriginHeaderModification`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve origin header modification settings for the specified zone. This endpoint provides information about how headers are modified when forwarding requests to origin servers.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `type` (path, string, required) The type of origin header modification. Only the `mrt` type is supported.  
    Pattern: ^.\*$. Example: `mrt`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned the origin header modification associated with a zone.
    
    Media type: `application/json`. Schema: `OriginHeaderModificationEnvelope`.
    
    _Example: MrtPutRequest_
    
    ```
    {
      "data": {
        "headerName": "x-sfdc-access-control",
        "headerValue": "********789",
        "lastUpdated": "2024-04-27T18:32:34.675182Z"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Upsert an origin header modification. Only the \`mrt\` type is supported.

`PUT /organizations/{organizationId}/zones/{zoneId}/origin-header-modification/{type}`

Operation ID: `upsertOriginHeaderModification`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Create or update origin header modification settings for the specified zone. Use this endpoint to configure how headers are modified when forwarding requests to origin servers.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `type` (path, string, required) The type of origin header modification. Only the `mrt` type is supported.  
    Pattern: ^.\*$. Example: `mrt`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `OriginHeaderModificationPutRequest`.

_Example: MrtPutRequestBodyExample_

```
{
  "headerValue": "123456789"
}
```

#### Responses

*   **200** Successfully upserted the origin header modification.
    
    Media type: `application/json`. Schema: `OriginHeaderModificationEnvelope`.
    
    _Example: MrtPutUpdateResponse_
    
    ```
    {
      "data": {
        "headerName": "x-sfdc-access-control",
        "headerValue": "********789",
        "lastUpdated": "2024-04-27T18:32:34.675182Z"
      }
    }
    ```
    
*   **201** Successfully created the origin header modification.
    
    Media type: `application/json`. Schema: `OriginHeaderModificationEnvelope`.
    
    _Example: MrtPutCreateResponse_
    
    ```
    {
      "data": {
        "headerName": "x-sfdc-access-control",
        "headerValue": "********789",
        "lastUpdated": "2024-04-27T18:32:34.675182Z"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete the origin header modification associated with a zone. Only the \`mrt\` type is supported.

`DELETE /organizations/{organizationId}/zones/{zoneId}/origin-header-modification/{type}`

Operation ID: `deleteOriginHeaderModification`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Delete origin header modification settings for the specified zone. This endpoint removes header modification configurations.

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `type` (path, string, required) The type of origin header modification. Only the `mrt` type is supported.  
    Pattern: ^.\*$. Example: `mrt`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the origin header modification associated with a zone.
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get cipher suites settings by zoneId.

`GET /organizations/{organizationId}/zones/{zoneId}/settings/ciphers`

Operation ID: `getCipherSuites`. Security: AmOAuth2 (sfcc.cdn-zones, sfcc.cdn-zones.rw).

Retrieve cipher suite settings for the specified zone. This endpoint provides information about supported encryption algorithms and security protocols. See [eCDN Supported Cipher Suites](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-cipher-suite-types.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Retrieves current zone level cipher settings.
    
    Media type: `application/json`. Schema: `CipherSuitesEnvelope`.
    
    _Example: CipherSettingsGetResponse_
    
    ```
    {
      "data": {
        "ciphers": [
          "ECDHE-ECDSA-AES128-GCM-SHA256",
          "ECDHE-RSA-AES128-GCM-SHA256"
        ],
        "cipherSuiteType": "Custom"
      }
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PATCH Update cipher suite settings for the zone.

`PATCH /organizations/{organizationId}/zones/{zoneId}/settings/ciphers`

Operation ID: `updateCipherSuites`. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update cipher suite settings for the specified zone. Use this endpoint to modify supported encryption algorithms and security protocols. See [eCDN Supported Cipher Suites](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-cipher-suite-types.html).

#### Parameters

*   `zoneId` (path, string, required) The unique identifier of a CDN zone.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CipherSuitesRequest`.

_Example: CipherSettingsPatchRequestBodyExample_

```
{
  "ciphers": [
    "ECDHE-ECDSA-AES128-GCM-SHA256"
  ],
  "cipherSuiteType": "Custom"
}
```

#### Responses

*   **200** Updates current zone level cipher settings.
    
    Media type: `application/json`. Schema: `CipherSuitesEnvelope`.
    
    _Example: CipherSettingsPatchResponse_
    
    ```
    {
      "data": {
        "ciphers": [
          "ECDHE-ECDSA-AES128-GCM-SHA256"
        ],
        "cipherSuiteType": "Custom"
      }
    }
    ```
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The resource requested by the caller was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET List Turnstile widgets for the requesting instance.

`GET /organizations/{organizationId}/turnstile/widgets`

Operation ID: `listTurnstileWidgets`. Tags: Turnstile. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Retrieves Turnstile widgets for the requesting instance. The API identifies widgets using the `{name}-{environment}` naming convention (for example, `checkout-dev`, `checkout-prd`) established by the create-widget story. Only widgets whose names end with `-{environment}` for the requesting instance and returns only those matching the instance environment. The response strips the environment suffix from the `name` so callers see the logical widget name. The response includes secrets per Phase 1 alignment with Security and MRT. The system caches results for 5 minutes.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `name` (query, string) Case-insensitive substring match against the logical widget name (after stripping the environment suffix).  
    Maximum length: 255. Example: `checkout`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Successfully retrieved the list of Turnstile widgets.
    
    Media type: `application/json`. Schema: `TurnstileWidgetsEnvelope`.
    
    _Example: TurnstileWidgetsListResponse_
    
    ```
    {
      "data": [
        {
          "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
          "name": "checkout-widget",
          "mode": "managed",
          "domains": [
            "shop.example.com",
            "www.example.com"
          ],
          "bot_fight_mode": false,
          "region": "world",
          "offlabel": false,
          "clearance_level": "interactive",
          "created_on": "2026-01-15T12:00:00Z",
          "modified_on": "2026-02-20T08:30:00Z",
          "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
        },
        {
          "sitekey": "0x4BBBBBBBBcDe2fGhIjKlMn",
          "name": "login-widget",
          "mode": "invisible",
          "domains": [
            "login.example.com"
          ],
          "bot_fight_mode": false,
          "region": "world",
          "offlabel": false,
          "clearance_level": "interactive",
          "created_on": "2026-01-20T10:00:00Z",
          "modified_on": "2026-02-15T14:30:00Z",
          "secret": "0x4BBBBBBBBcDe2fGhIjKlMn_secretvalue"
        }
      ]
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### POST Create a Turnstile widget for the requesting instance.

`POST /organizations/{organizationId}/turnstile/widgets`

Operation ID: `createTurnstileWidget`. Tags: Turnstile. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Creates a new Cloudflare Turnstile widget for the requesting instance. The widget name in the request is the logical name; the environment suffix (`-{environment}`) automatically before creating the widget in Cloudflare, producing the `{name}-{environment}` naming convention (for example `checkout-dev`). The response includes the shared secret from Cloudflare.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `TurnstileWidgetCreateRequest`.

_Example: TurnstileWidgetCreateRequestExample_

```
{
  "name": "checkout",
  "domains": [
    "shop.example.com",
    "www.example.com"
  ],
  "mode": "managed"
}
```

#### Responses

*   **201** Successfully created the Turnstile widget.
    
    Media type: `application/json`. Schema: `TurnstileWidgetEnvelope`.
    
    _Example: TurnstileWidgetCreateResponse_
    
    ```
    {
      "data": {
        "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
        "name": "checkout-widget",
        "mode": "managed",
        "domains": [
          "shop.example.com",
          "www.example.com"
        ],
        "bot_fight_mode": false,
        "region": "world",
        "offlabel": false,
        "clearance_level": "interactive",
        "created_on": "2026-01-15T12:00:00Z",
        "modified_on": "2026-01-15T12:00:00Z",
        "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid (for example, hostname limit exceeded, invalid naming, or the instance has reached the 5000 widget limit).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### GET Get Turnstile widget details.

`GET /organizations/{organizationId}/turnstile/widgets/{sitekey}`

Operation ID: `getTurnstileWidget`. Tags: Turnstile. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Retrieve the full configuration of a Cloudflare Turnstile widget by sitekey, including the shared secret.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `sitekey` (path, string, required) Cloudflare Turnstile widget sitekey.  
    Minimum length: 1. Maximum length: 64. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `0x4AAAAAAAAbCd1eFgHiJkLm`.

#### Responses

*   **200** Successfully retrieved the Turnstile widget.
    
    Media type: `application/json`. Schema: `TurnstileWidgetEnvelope`.
    
    _Example: TurnstileWidgetResponse_
    
    ```
    {
      "data": {
        "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
        "name": "checkout-widget",
        "mode": "managed",
        "domains": [
          "shop.example.com",
          "www.example.com"
        ],
        "bot_fight_mode": false,
        "region": "world",
        "offlabel": false,
        "clearance_level": "interactive",
        "created_on": "2026-01-15T12:00:00Z",
        "modified_on": "2026-02-20T08:30:00Z",
        "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The Turnstile widget with the given sitekey was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### PUT Update an existing Turnstile widget.

`PUT /organizations/{organizationId}/turnstile/widgets/{sitekey}`

Operation ID: `updateTurnstileWidget`. Tags: Turnstile. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Update the domains and/or mode for an existing Cloudflare Turnstile widget. Returns 404 if the widget does not exist and 400 if the request is invalid (for example, when the Cloudflare hostname/domain limit for the widget has been reached).

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `sitekey` (path, string, required) Cloudflare Turnstile widget sitekey.  
    Minimum length: 1. Maximum length: 64. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `0x4AAAAAAAAbCd1eFgHiJkLm`.

#### Request body (required)

Media type: `application/json`. Schema: `TurnstileWidgetUpdateRequest`.

_Example: TurnstileWidgetUpdateRequestExample_

```
{
  "domains": [
    "shop.example.com",
    "www.example.com",
    "checkout.example.com"
  ],
  "mode": "invisible"
}
```

#### Responses

*   **200** Successfully updated the Turnstile widget.
    
    Media type: `application/json`. Schema: `TurnstileWidgetEnvelope`.
    
    _Example: TurnstileWidgetUpdateResponse_
    
    ```
    {
      "data": {
        "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
        "name": "checkout-widget",
        "mode": "invisible",
        "domains": [
          "shop.example.com",
          "www.example.com",
          "checkout.example.com"
        ],
        "bot_fight_mode": false,
        "region": "world",
        "offlabel": false,
        "clearance_level": "interactive",
        "created_on": "2026-01-15T12:00:00Z",
        "modified_on": "2026-02-22T16:45:00Z",
        "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
      }
    }
    ```
    
*   **400** The request sent by the caller is not valid (for example, hostname limit reached).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** The caller does not have access to the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The Turnstile widget with the given sitekey was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

### DELETE Delete a Turnstile widget.

`DELETE /organizations/{organizationId}/turnstile/widgets/{sitekey}`

Operation ID: `deleteTurnstileWidget`. Tags: Turnstile. Security: AmOAuth2 (sfcc.cdn-zones.rw).

Delete an existing Cloudflare Turnstile widget. This operation is irreversible and immediately invalidates the sitekey and secret.

**Safety Controls:**

*   Production widgets (environment=prd) require explicit `forceProduction=true` query parameter
*   Returns 403 Forbidden if attempting to delete production widget without force flag
*   Supports dry-run mode via `?dryRun=true` query parameter for validation without deletion

**Post-deletion verification** runs automatically to confirm deletion.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `sitekey` (path, string, required) Cloudflare Turnstile widget sitekey.  
    Minimum length: 1. Maximum length: 64. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `0x4AAAAAAAAbCd1eFgHiJkLm`.
*   `forceProduction` (query, boolean) Required to delete production widgets (environment=prd). Provides an additional safety check to prevent accidental deletion of production widgets. Non-production widgets (dev, stg, sbx) do not require this flag.  
    Default: `false`. Example: `false`.
*   `dryRun` (query, boolean) When true, validates the delete request but does not actually delete the widget. Use this to verify production protection checks before committing to deletion.  
    Default: `false`. Example: `false`.

#### Responses

*   **204** Successfully deleted the Turnstile widget. No content returned.
*   **400** Bad request. Invalid sitekey format or malformed request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/storefront-zones 400 response._
    
*   **401** The caller is not authorized to access the requested resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "UnAuthorized Access",
      "detail": "The authorization token passed is no longer valid"
    }
    ```
    
*   **403** Forbidden. Production widgets require explicit forceProduction flag.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ProductionProtection_
    
    ```
    {
      "title": "Production deletion requires force flag",
      "detail": "Cannot delete production widget without forceProduction: true",
      "type": "Forbidden"
    }
    ```
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden-access",
      "title": "Forbidden",
      "detail": "Access to requested resource is forbidden."
    }
    ```
    
*   **404** The Turnstile widget with the given sitekey was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Not Found",
      "detail": "Requested resource was not found"
    }
    ```
    
*   **500** An error occurred on the server side.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InternalServerError: same as POST /organizations/{organizationId}/storefront-zones 500 response._
    

## Schemas

### StorefrontZoneCreateRequest

The storefront zone information to be created.

*   `domainName` (_string_, required) Domain name for the site.  
    Pattern: ^.\*$. Example: `cc-merchant.com`.
*   `lastMigrationStep` (_string_) Optional. Specifies the final migration step from which to resume (for example, 8-LegacyToProxyIpAccessRuleMigrationStep).  
    Pattern: ^.\*$. Example: `8-LegacyToProxyIpAccessRuleMigrationStep`.

### StorefrontZoneCreateEnvelope

*   `data` (_StorefrontZoneCreateResponse_, required)

_Example_

```
{
  "data": {
    "zoneId": "023e105f4ecef8ad9ca31a8372d0c353",
    "zoneName": "stg-zzzz-cc-merchant-com.cc-ecdn.net",
    "status": "active",
    "createdOn": "2014-01-01T05:20:00.12345Z"
  }
}
```

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### MtlsCertificatesResponseEnvelope

*   `data` (_array of MtlsCertificateResponse_, required)

_Example_

```
{
  "data": [
    {
      "mtlsCertificateId": "465a48f6-3d98-4c15-9312-211984ee8629",
      "expiresOn": "2022-01-12T04:15:57Z",
      "issuer": "DigiCert",
      "signature": "SHA256WithRSA",
      "uploadedOn": "2020-01-12T04:15:57Z",
      "ca": true,
      "serialNumber": "432217133297895665180570788458463042229861757760",
      "mtlsCertificateName": "mtls_cert_name",
      "mtlsAssociatedCodeUploadHostname": "mtls.cert.salesforce.com"
    }
  ]
}
```

### MtlsCertificateRequest

mTLS certificate request information.

*   `certificate` (_string_, required) Public key for the CA certificate in mTLS.  
    Pattern: ^.\*$. Example: `-----BEGIN CERTIFICATE----- MIIDtTCCAp2gAwIBAgIJAMHAwfXZ5PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV BAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX aWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF MQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50 ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB CgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1 CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB KwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5 0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI dZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2 izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4 9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI GKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV BAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF MAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2 2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP Mlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG SvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq 2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw YbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY= -----END CERTIFICATE-----`.
*   `privateKey` (_string_, required) Private key of the CA certificate in mTLS.  
    Pattern: ^.\*$. Example: `-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG dtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn abIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid tnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py FxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE ewooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb HBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/ axiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb +ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g +j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv KLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7 9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo /WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu iacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9 N2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe VAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB vULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U lySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR 9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7 mEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX dFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe PG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS fhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W qu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T lv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi -----END RSA PRIVATE KEY-----`.
*   `name` (_string_, required) Certificate name used for ease of understanding.  
    Pattern: ^.\*$. Example: `mtls_cert_name`.

_Example_

```
{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----",
  "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----",
  "name": "mtls_cert_name"
}
```

### MtlsCertificateResponseEnvelope

*   `data` (_MtlsCertificateResponse_, required)

_Example_

```
{
  "data": {
    "mtlsCertificateId": "465a48f6-3d98-4c15-9312-211984ee8629",
    "expiresOn": "2022-01-12T04:15:57Z",
    "issuer": "DigiCert",
    "signature": "SHA256WithRSA",
    "uploadedOn": "2020-01-12T04:15:57Z",
    "ca": true,
    "serialNumber": "432217133297895665180570788458463042229861757760",
    "mtlsCertificateName": "mtls_cert_name",
    "mtlsAssociatedCodeUploadHostname": "mtls.cert.salesforce.com"
  }
}
```

### PageShieldNotificationWebhookListEnvelope

*   `data` (_array of PageShieldNotificationWebhookResponse_, required)

_Example_

```
{
  "data": [
    {
      "id": "webhook_1234567890abcdef",
      "name": "Security Alert Webhook",
      "webhookUrl": "https://example.com/webhook/security",
      "type": "security_alert",
      "createdAt": "2023-01-01T00:00:00Z",
      "lastSuccess": "2023-01-01T12:00:00Z",
      "lastFailure": "2023-01-01T18:00:00Z",
      "enabled": true,
      "zones": [
        "zone_1234567890abcdef"
      ]
    }
  ]
}
```

### PageShieldNotificationWebhookRequest

Page shield notification for the webhook request.

*   `webhookId` (_string_) Webhook ID  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `webhookUrl` (_string_, required) Webhook URL.  
    Pattern: ^.\*$. Example: `https://example.com/webhook/security`.
*   `name` (_string_, required) Webhook name  
    Pattern: ^.\*$. Example: `Security Alert Webhook`.
*   `secret` (_string_) Webhook optional secret.  
    Pattern: ^.\*$. Example: `webhook_secret_123`.
*   `enabled` (_boolean_) Specifies whether or not the notification is enabled.  
    Example: `true`.
*   `zones` (_array of string_) Zone names on which to filter notifications alerts. An empty array indicates all storefront zones.  
    Items: Pattern: ^.\*$. Example: `zone_1234567890abcdef`.

_Example_

```
{
  "webhookUrl": "https://example.com/webhook/security",
  "name": "Security Alert Webhook",
  "secret": "webhook_secret_123",
  "enabled": true,
  "zones": [
    "zone_1234567890abcdef"
  ]
}
```

### PageShieldNotificationWebhookEnvelope

*   `data` (_PageShieldNotificationWebhookResponse_, required)

_Example_

```
{
  "data": {
    "id": "webhook_1234567890abcdef",
    "name": "Security Alert Webhook",
    "webhookUrl": "https://example.com/webhook/security",
    "type": "security_alert",
    "createdAt": "2023-01-01T00:00:00Z",
    "lastSuccess": "2023-01-01T12:00:00Z",
    "lastFailure": "2023-01-01T18:00:00Z",
    "enabled": true,
    "zones": [
      "zone_1234567890abcdef"
    ]
  }
}
```

### PageShieldNotificationWebhookUpdateRequest

Request body to update a page shield notification. You must include at least one of the following properties: webhookId, enabled, or zones.

*   `webhookId` (_string_) Webhook ID  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `enabled` (_boolean_) Specifies whether or not the notification is enabled.  
    Example: `true`.
*   `zones` (_array of string_) Zone names on which to filter notifications alerts. An empty array indicates all storefront zones.  
    Items: Pattern: ^.\*$. Example: `zone_1234567890abcdef`.

_Example_

```
{
  "webhookId": "ffffe61cf25e4ec49c34b029ff3060f7",
  "enabled": true,
  "zones": [
    "zone_1234567890abcdef"
  ]
}
```

### WebhookListEnvelope

*   `data` (_array of WebhookResponse_, required)

### WebhookRequest

Webhook request

*   `name` (_string_, required) Webhook name  
    Pattern: ^.\*$. Example: `My Webhook`.
*   `url` (_string_, required) Webhook URL  
    Pattern: ^.\*$. Example: `https://example.com/webhook`.
*   `secret` (_string_) Webhook optional secret  
    Pattern: ^.\*$. Example: `webhook_secret_123`.

### WebhookEnvelope

*   `data` (_WebhookResponse_, required)

### PageShieldPoliciesListEnvelope

*   `data` (_array of PageShieldPolicyResponse_, required)

_Example_

```
{
  "data": [
    {
      "action": "allow",
      "description": "Allow scripts from trusted CDN sources",
      "enabled": true,
      "expression": "http.request.uri.path contains \"/trusted-cdn/\"",
      "value": "script-src",
      "id": "policy_1234567890abcdef"
    }
  ]
}
```

### PageShieldPolicyRequest

Page shield policy request object.

*   `action` (_string_) Action taken when expression matches allow or log.  
    Allowed values: `allow`, `log`. Example: `allow`.
*   `description` (_string_) Description for the policy.  
    Pattern: ^.\*$. Example: `Allow scripts from trusted CDN sources`.
*   `enabled` (_boolean_) Enable/disable the policy.  
    Example: `true`.
*   `expression` (_string_) Expression of the policy.  
    Pattern: ^.\*$. Example: `http.request.uri.path contains "/trusted-cdn/"`.
*   `value` (_string_) Policy to be applied.  
    Pattern: ^.\*$. Example: `script-src`.

_Example_

```
{
  "action": "allow",
  "description": "Allow scripts from trusted CDN sources",
  "enabled": true,
  "expression": "http.request.uri.path contains \"/trusted-cdn/\"",
  "value": "script-src"
}
```

### PageShieldPoliciesEnvelope

*   `data` (_PageShieldPolicyResponse_, required)

_Example_

```
{
  "data": {
    "action": "allow",
    "description": "Allow scripts from trusted CDN sources",
    "enabled": true,
    "expression": "http.request.uri.path contains \"/trusted-cdn/\"",
    "value": "script-src",
    "id": "policy_1234567890abcdef"
  }
}
```

### PageShieldScriptListEnvelope

*   `data` (_array of PageShieldScriptResponse_, required)

_Example_

```
{
  "data": [
    {
      "id": "12345678901234asdfasfasdf",
      "url": "https://sfdc-test.net/on/demandware.static/Sites-SiteNemesis-Site/-/en_US//lib/jquery/ui/jquery-ui.min.js",
      "host": "sfdc-test.net",
      "addedAt": "2022-01-01T05:20:00Z",
      "firstSeenAt": "2022-01-01T05:20:00Z",
      "lastSeenAt": "2022-01-01T05:20:00Z",
      "fetchedAt": "2022-01-01T05:20:00Z",
      "domainReportedMalicious": false,
      "hash": "1243453456abc",
      "cryptoMiningScore": 1,
      "dataflowScore": 1,
      "jsIntegrityScore": 1,
      "mageCartScore": 2,
      "malwareScore": 1,
      "obfuscationScore": 2,
      "maliciousDomainCategories": [
        "Malware"
      ],
      "maliciousUrlCategories": [
        "Malware"
      ],
      "urlContainsCdnCgiPath": false,
      "urlReportedMalicious": false,
      "pageUrls": [
        "blog.test.salesforce.com/page1",
        "blog.test.salesforce.com/page2"
      ],
      "firstPageUrl": "blog.test.salesforce.com",
      "status": "active",
      "versions": []
    }
  ]
}
```

### PageShieldScriptEnvelope

*   `data` (_PageShieldScriptResponse_, required)

_Example_

```
{
  "data": {
    "id": "12345678901234asdfasfasdf",
    "url": "https://sfdc-test.net/on/demandware.static/Sites-SiteNemesis-Site/-/en_US//lib/jquery/ui/jquery-ui.min.js",
    "host": "sfdc-test.net",
    "addedAt": "2022-01-01T05:20:00Z",
    "firstSeenAt": "2022-01-01T05:20:00Z",
    "lastSeenAt": "2022-01-01T05:20:00Z",
    "fetchedAt": "2022-01-01T05:20:00Z",
    "domainReportedMalicious": false,
    "hash": "1243453456abc",
    "cryptoMiningScore": 1,
    "dataflowScore": 1,
    "jsIntegrityScore": 1,
    "mageCartScore": 2,
    "malwareScore": 1,
    "obfuscationScore": 2,
    "maliciousDomainCategories": [
      "Malware"
    ],
    "maliciousUrlCategories": [
      "Malware"
    ],
    "urlContainsCdnCgiPath": false,
    "urlReportedMalicious": false,
    "pageUrls": [
      "blog.test.salesforce.com/page1",
      "blog.test.salesforce.com/page2"
    ],
    "firstPageUrl": "blog.test.salesforce.com",
    "status": "active",
    "versions": []
  }
}
```

### ZonesEnvelope

*   `data` (_array of Zone_, required)

_Example_

```
{
  "data": [
    {
      "zoneId": "example1-zone-Id",
      "name": "example1.com",
      "status": "pending"
    },
    {
      "zoneId": "example2-zone-Id",
      "name": "example2.com",
      "status": "active"
    }
  ]
}
```

### WafGroupsEnvelope

*   `data` (_array of WafGroup_, required)

### WafGroup

*   `groupId` (_string_)  
    Maximum length: 100. Example: `372e67954025e0ba6aaa6d586b9e0b60`.
*   `action` (_string_) The action to apply to WAF group  
    Allowed values: `block`, `challenge`, `monitor`, `default`. Example: `block`.
*   `mode` (_string_, required) Mode of the waf rule - on vs off  
    Allowed values: `on`, `off`. Example: `on`.
*   `description` (_string_) Description of the WAF Group.  
    Pattern: ^.\*$. Example: `Test WAF Group to protect against SQL injection`.

_Example_

```
{
  "groupId": "372abe67954025e0ba6aaa6d586b9e0b",
  "zoneId": "example1-zone-Id",
  "action": "monitor",
  "mode": true,
  "description": "SQL injection protection"
}
```

### WafGroupEnvelope

*   `data` (_WafGroup_)

### WafRulesEnvelope

*   `data` (_array of WafRule_, required)

_Example_

```
{
  "data": [
    {
      "ruleId": "892e67954025e0ba6atefd586b9e58b3",
      "groupId": "372abe67954025e0ba6aaa6d586b9e0b",
      "action": "monitor",
      "defaultAction": "challenge",
      "description": "SQL injection protection"
    }
  ]
}
```

### WafRuleEnvelope

*   `data` (_WafRule_, required)

_Example_

```
{
  "data": {
    "ruleId": "892e67954025e0ba6atefd586b9e58b3",
    "groupId": "372abe67954025e0ba6aaa6d586b9e0b",
    "action": "monitor",
    "defaultAction": "challenge",
    "description": "SQL injection protection"
  }
}
```

### WafRule

*   `ruleId` (_string_)  
    Pattern: ^.\*$. Example: `892e67954025e0ba6atefd586b9e58b3`.
*   `groupId` (_string_)  
    Maximum length: 100. Example: `372e67954025e0ba6aaa6d586b9e0b60`.
*   `action` (_string_, required) The action to apply to WAF rule  
    Allowed values: `block`, `challenge`, `monitor`, `disable`, `default`. Example: `block`.
*   `defaultAction` (_string_) The action to apply to WAF rule  
    Allowed values: `block`, `challenge`, `monitor`, `disable`. Example: `block`.
*   `description` (_string_) Description of the WAF Group.  
    Pattern: ^.\*$. Example: `Test WAF Rule to protect against SQL injection`.

_Example_

```
{
  "ruleId": "892e67954025e0ba6atefd586b9e58b3",
  "groupId": "372abe67954025e0ba6aaa6d586b9e0b",
  "action": "monitor",
  "defaultAction": "challenge",
  "description": "SQL injection protection"
}
```

### SpeedSettingsEnvelope

*   `data` (_SpeedSetting_, required)

### SpeedSetting

*   `brotliCompression` (_string_) Brotli compression setting of a zone.  
    Allowed values: `on`, `off`. Default: `off`. Example: `off`.
*   `http2Prioritization` (_string_) Http2 prioritization setting for a zone.  
    Allowed values: `on`, `off`. Default: `off`. Example: `off`.
*   `webp` (_string_) Support for the WebP image format when using image modification for a zone. The WebP image format can be used with supported clients for added performance benefits. Setting this property to `on` will return an error when the `polish` property is set to `off`.  
    Allowed values: `on`, `off`. Default: `off`. Example: `off`.
*   `polish` (_string_) The level of polish (image quality) used for image modification. The value `lossless` corresponds to **Polish Level Basic** in the UI, and the value `lossy` corresponds to **Polish Level Basic+JPEG.** To disable image modification, set this property to `off`. Setting this property to `off` will prevent you from setting the `webp` property to `on`.  
    Allowed values: `off`, `lossless`, `lossy`. Default: `off`. Example: `off`.
*   `earlyHints` (_string_) Early Hints for a zone.  
    Allowed values: `on`, `off`. Default: `off`. Example: `off`.
*   `http3` (_string_) Http3 for a zone.  
    Allowed values: `on`, `off`. Default: `off`. Example: `off`.
*   `http2ToOrigin` (_string_) Http2 to Origin for a zone.  
    Allowed values: `on`, `off`. Default: `off`. Example: `off`.

_Example_

```
{
  "brotliCompression": "off"
}
```

### SecuritySettingsEnvelope

*   `data` (_SecuritySetting_, required)

_Example_

```
{
  "data": {
    "hsts": {
      "enabled": true,
      "includeSubdomains": true,
      "maxAge": 31536000,
      "preload": false
    },
    "securityLevel": "medium",
    "tls13Enabled": true,
    "wafEnabled": true,
    "alwaysUseHttps": true
  }
}
```

### SecuritySetting

*   `hsts` (_object_) The security header for a zone.
    
    *   `enabled` (_boolean_) Enable strict transport security.  
        Example: `true`.
    *   `includeSubdomains` (_boolean_) Include all subdomains for strict transport security.  
        Example: `true`.
    *   `maxAge` (_number_) Max age in seconds of the strict transport security.  
        Example: `31536000`.
    *   `preload` (_boolean_) Preload any URLs that are included in the response headers.  
        Example: `false`.
    
    _Example_
    
    ```
    {
      "enabled": true,
      "includeSubdomains": true,
      "maxAge": 31536000,
      "preload": false
    }
    ```
    
*   `securityLevel` (_string_) Security profile for your zone, which will automatically adjust each of the security settings.  
    Allowed values: `off`, `essentially_off`, `low`, `medium`, `high`, `under_attack`. Example: `medium`.
*   `tls13Enabled` (_boolean_) Enable Crypto TLS 1.3 feature for this zone.  
    Example: `true`.
*   `wafEnabled` (_boolean_) Enable WAF (OWASP) protection for this zone. Not applicable for zones using WAFv2.  
    Example: `true`.
*   `alwaysUseHttps` (_boolean_, required) Redirect all http requests to https.  
    Example: `true`.

_Example_

```
{
  "hsts": {
    "enabled": true,
    "includeSubdomains": true,
    "maxAge": 31536000,
    "preload": false
  },
  "securityLevel": "medium",
  "tls13Enabled": true,
  "wafEnabled": true,
  "alwaysUseHttps": true
}
```

### CachePurgeRequest

Request for doing a cache purge

*   `path` (_string_) Cache clearing path. Accepts any valid path. Provide 'path' or 'tags', not both.  
    Pattern: ^.\*$. Example: `www.sfcc-ecdn-test5.net/dw/shop/v21_9/products`.
*   `tags` (_array of string_) List of cache tags to purge. When specified, all cached content associated with these tags will be purged.  
    Items: Pattern: ^.\*$. Example: `product-123`.
    
    _Example_
    
    ```
    [
      "product-123",
      "category-456"
    ]
    ```
    

_Example_

```
{
  "path": "www.sfcc-ecdn-test5.net/dw/shop/v21_9/products",
  "tags": [
    "product-123",
    "category-456"
  ]
}
```

### CachePurgeResponseEnvelope

*   `data` (_CachePurgeResponse_, required)

_Example_

```
{
  "data": {
    "cachePurged": false,
    "details": "1084 : Unable to purge '<url>'."
  }
}
```

### OCAPICachingToggleRequest

Request to enable or disable API Caching Page rule

*   `enableOCAPICachingPageRule` (_boolean_, required) True to enable API Caching Page rule, false to disable.  
    Example: `true`.

### CacheRulesEnvelope

*   `data` (_array of CacheRule_, required)

_Example_

```
{
  "data": [
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Cache static assets on product pages",
      "expression": "(http.request.uri.path matches \"^/product/.*\")",
      "action": "cache",
      "excludeQueryStrings": [
        "gclid",
        "utm_campaign"
      ],
      "ignoreQueryStringsOrder": true,
      "respectStrongEtags": false,
      "lastUpdated": "2022-01-01T05:20:00Z",
      "enabled": true
    }
  ]
}
```

### CacheRulesPostRequest

Request body for creating a cache rule.

*   `description` (_string_, required) A description of what the cache rule does.  
    Pattern: ^.\*$. Example: `Cache static assets on product pages.`.
*   `expression` (_string_, required) The expression that defines when this cache rule applies.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/product/.*")`.
*   `action` (_string_, required) The action to take (currently only supports "cache").  
    Pattern: ^.\*$. Example: `cache`.
*   `excludeQueryStrings` (_array of string_) List of query string parameters to exclude from the cache key.  
    Items: Pattern: ^.\*$. Example: `gclid`.
    
    _Example_
    
    ```
    [
      "gclid",
      "utm_campaign"
    ]
    ```
    
*   `ignoreQueryStringsOrder` (_boolean_) Specifies whether the order of query string parameters in the cache key is ignored.  
    Example: `true`.
*   `respectStrongEtags` (_boolean_) Specifies whether strong ETags are respected.  
    Example: `false`.
*   `enabled` (_boolean_) Specifies whether the rule is enabled.  
    Example: `true`.
*   `position` (_RulePosition_)

### CacheRulesPatchRequest

Request body for updating a cache rule. All fields are optional, but at least one field must be provided.

*   `description` (_string_) A description of what the cache rule does.  
    Pattern: ^.\*$. Example: `Cache static assets on product pages.`.
*   `expression` (_string_) The expression that defines when this cache rule applies.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/product/.*")`.
*   `action` (_string_) The action to take (currently only supports "cache").  
    Pattern: ^.\*$. Example: `cache`.
*   `excludeQueryStrings` (_array of string_) List of query string parameters to exclude from the cache key.  
    Items: Pattern: ^.\*$. Example: `gclid`.
    
    _Example_
    
    ```
    [
      "gclid",
      "utm_campaign"
    ]
    ```
    
*   `ignoreQueryStringsOrder` (_boolean_) Specifies whether the order of query string parameters in the cache key is ignored.  
    Example: `true`.
*   `respectStrongEtags` (_boolean_) Specifies whether strong ETags are respected.  
    Example: `false`.
*   `enabled` (_boolean_) Specifies whether the rule is enabled.  
    Example: `true`.
*   `position` (_RulePosition_)

### CertificatesEnvelope

*   `data` (_array of Certificate_, required)

_Example_

```
{
  "data": [
    {
      "certificateId": "f90712123fb02287348dd34c0a282bb9",
      "hosts": [
        "example.com",
        "www.example.com"
      ],
      "expiresOn": "2025-12-31T23:59:59Z",
      "uploadedOn": "2024-01-01T00:00:00Z",
      "issuer": "Let's Encrypt Authority X3",
      "signature": "SHA256",
      "status": "ACTIVE",
      "minTlsVersion": "1.2",
      "certificateType": "custom",
      "certificateAuthority": "lets_encrypt",
      "certificateValidation": "http",
      "certificateVerificationTXTName": "_acme-challenge.example.com",
      "certificateVerificationTXTValue": "abc123def456ghi789",
      "certificateVerificationStatus": "ACTIVE",
      "wildcardHostname": false,
      "wildcardCertificateVerificationTXTName": "_acme-challenge.wildcard.example.com",
      "wildcardCertificateVerificationTXTValue": "wildcard_abc123def456",
      "wildcardCertificateVerificationStatus": "ACTIVE",
      "customHostnameVerificationTXTName": "_acme-challenge.custom.example.com",
      "customHostnameVerificationTXTValue": "custom_abc123def456",
      "customHostnameId": "f90712123fb02287348dd34c0a282bb9",
      "customHostname": "custom.example.com",
      "customHostnameStatus": "ACTIVE",
      "dcvDelegationRecords": []
    }
  ]
}
```

### CertificateRequest

Certificate request information

*   `hostname` (_string_, required) Hostname that certificate needs to be applied to.  
    Pattern: ^.\*$. Example: `example.com`.
*   `bundleMethod` (_string_) Bundle method of the custom certificate chain for verification.  
    Pattern: ^.\*$. Example: `ubiquitous`.
*   `certificateType` (_string_) Indicates certificate is custom or automatic certificate renewal by eCDN. Optional field, if nothing specified the default value is custom. Valid values are custom or automatic.  
    Pattern: ^.\*$. Example: `custom`.
*   `certificate` (_string_) Public key of the custom certificate. Required if the certificateType value is custom.  
    Pattern: ^.\*$. Example: `-----BEGIN CERTIFICATE----- MIIDtTCCAp2gAwIBAgIJAMHAwfXZ5PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV BAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX aWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF MQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50 ZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB CgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1 CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB KwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5 0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI dZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2 izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4 9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI GKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV BAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF MAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2 2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP Mlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG SvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq 2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw YbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY= -----END CERTIFICATE-----`.
*   `privateKey` (_string_) Private key associated with the custom certificate. Required if the `certificateType` value is custom.  
    Pattern: ^.\*$. Example: `-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG dtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn abIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid tnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py FxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE ewooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb HBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/ axiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb +ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g +j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv KLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7 9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo /WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu iacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9 N2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe VAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB vULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U lySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR 9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7 mEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX dFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe PG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS fhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W qu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T lv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi -----END RSA PRIVATE KEY-----`.
*   `certificateAuthority` (_string_) Certificate authority only for automatic certificate renewal by eCDN. Required if the `certificateType` value is automatic. Valid values are `google` or `lets_encrypt`.  
    Pattern: ^.\*$. Example: `lets_encrypt`.
*   `certificateValidation` (_string_) Certificate validation type is optional only for `certificateType` automatic, default value is `http`. Valid values are `http` or `txt`.  
    Pattern: ^.\*$. Example: `http`.
*   `wildcardHostname` (_boolean_) Set to true for a wildcard custom hostname.  
    Example: `false`.

_Example_

```
{
  "hostname": "example.com",
  "bundleMethod": "ubiquitous",
  "certificateType": "custom",
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDtTCCAp2gAwIBAgIJAMHAwfXZ5PWMA0GCSqGSIb3DQEBCwUAMEUxCzAJBgNV\nBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRlMSEwHwYDVQQKExhJbnRlcm5ldCBX\naWRnaXRzIFB0eSBMdGQwHhcNMTYwODI0MTY0MzAxWhcNMTYxMTIyMTY0MzAxWjBF\nMQswCQYDVQQGEwJBVTETMBEGA1UECBMKU29tZS1TdGF0ZTEhMB8GA1UEChMYSW50\nZXJuZXQgV2lkZ2l0cyBQdHkgTHRkMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB\nCgKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmGdtcGbg/1\nCGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKnabIRuGvB\nKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpidtnKX/a+5\n0GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+pyFxIXjbEI\ndZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pEewooaeO2\nizNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABo4GnMIGkMB0GA1UdDgQWBBT/LbE4\n9rWf288N6sJA5BRb6FJIGDB1BgNVHSMEbjBsgBT/LbE49rWf288N6sJA5BRb6FJI\nGKFJpEcwRTELMAkGA1UEBhMCQVUxEzARBgNVBAgTClNvbWUtU3RhdGUxITAfBgNV\nBAoTGEludGVybmV0IFdpZGdpdHMgUHR5IEx0ZIIJAMHAwfXZ5/PWMAwGA1UdEwQF\nMAMBAf8wDQYJKoZIhvcNAQELBQADggEBAHHFwl0tH0quUYZYO0dZYt4R7SJ0pCm2\n2satiyzHl4OnXcHDpekAo7/a09c6Lz6AU83cKy/+x3/djYHXWba7HpEu0dR3ugQP\nMlr4zrhd9xKZ0KZKiYmtJH+ak4OM4L3FbT0owUZPyjLSlhMtJVcoRp5CJsjAMBUG\nSvD8RX+T01wzox/Qb+lnnNnOlaWpqu8eoOenybxKp1a9ULzIVvN/LAcc+14vioFq\n2swRWtmocBAs8QR9n4uvbpiYvS8eYueDCWMM4fvFfBhaDZ3N9IbtySh3SpFdQDhw\nYbjM2rxXiyLGxB4Bol7QTv4zHif7Zt89FReT/NBy4rzaskDJY5L6xmY=\n-----END CERTIFICATE-----",
  "privateKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAwQHoetcl9+5ikGzV6cMzWtWPJHqXT3wpbEkRU9Yz7lgvddmG\ndtcGbg/1CGZu0jJGkMoppoUo4c3dts3iwqRYmBikUP77wwY2QGmDZw2FvkJCJlKn\nabIRuGvBKwzESIXgKk2016aTP6/dAjEHyo6SeoK8lkIySUvK0fyOVlsiEsCmOpid\ntnKX/a+50GjB79CJH4ER2lLVZnhePFR/zUOyPxZQQ4naHf7yu/b5jhO0f8fwt+py\nFxIXjbEIdZliWRkRMtzrHOJIhrmJ2A1J7iOrirbbwillwjjNVUWPf3IJ3M12S9pE\newooaeO2izNTERcG9HzAacbVRn2Y2SWIyT/18QIDAQABAoIBACbhTYXBZYKmYPCb\nHBR1IBlCQA2nLGf0qRuJNJZg5iEzXows/6tc8YymZkQE7nolapWsQ+upk2y5Xdp/\naxiuprIs9JzkYK8Ox0r+dlwCG1kSW+UAbX0bQ/qUqlsTvU6muVuMP8vZYHxJ3wmb\n+ufRBKztPTQ/rYWaYQcgC0RWI20HTFBMxlTAyNxYNWzX7RKFkGVVyB9RsAtmcc8g\n+j4OdosbfNoJPS0HeIfNpAznDfHKdxDk2Yc1tV6RHBrC1ynyLE9+TaflIAdo2MVv\nKLMLq51GqYKtgJFIlBRPQqKoyXdz3fGvXrTkf/WY9QNq0J1Vk5ERePZ54mN8iZB7\n9lwy/AkCgYEA6FXzosxswaJ2wQLeoYc7ceaweX/SwTvxHgXzRyJIIT0eJWgx13Wo\n/WA3Iziimsjf6qE+SI/8laxPp2A86VMaIt3Z3mJN/CqSVGw8LK2AQst+OwdPyDMu\niacE8lj/IFGC8mwNUAb9CzGU3JpU4PxxGFjS/eMtGeRXCWkK4NE+G08CgYEA1Kp9\nN2JrVlqUz+gAX+LPmE9OEMAS9WQSQsfCHGogIFDGGcNf7+uwBM7GAaSJIP01zcoe\nVAgWdzXCv3FLhsaZoJ6RyLOLay5phbu1iaTr4UNYm5WtYTzMzqh8l1+MFFDl9xDB\nvULuCIIrglM5MeS/qnSg1uMoH2oVPj9TVst/ir8CgYEAxrI7Ws9Zc4Bt70N1As+U\nlySjaEVZCMkqvHJ6TCuVZFfQoE0r0whdLdRLU2PsLFP+q7qaeZQqgBaNSKeVcDYR\n9B+nY/jOmQoPewPVsp/vQTCnE/R81spu0mp0YI6cIheT1Z9zAy322svcc43JaWB7\nmEbeqyLOP4Z4qSOcmghZBSECgYACvR9Xs0DGn+wCsW4vze/2ei77MD4OQvepPIFX\ndFZtlBy5ADcgE9z0cuVB6CiL8DbdK5kwY9pGNr8HUCI03iHkW6Zs+0L0YmihfEVe\nPG19PSzK9CaDdhD9KFZSbLyVFmWfxOt50H7YRTTiPMgjyFpfi5j2q348yVT0tEQS\nfhRqaQKBgAcWPokmJ7EbYQGeMbS7HC8eWO/RyamlnSffdCdSc7ue3zdVJxpAkQ8W\nqu80pEIF6raIQfAf8MXiiZ7auFOSnHQTXUbhCpvDLKi0Mwq3G8Pl07l+2s6dQG6T\nlv6XTQaMyf6n1yjzL+fzDrH3qXMxHMO/b13EePXpDMpY7HQpoLDi\n-----END RSA PRIVATE KEY-----",
  "certificateAuthority": "lets_encrypt",
  "certificateValidation": "http",
  "wildcardHostname": false
}
```

### CertificateEnvelope

*   `data` (_Certificate_, required)

_Example_

```
{
  "data": {
    "certificateId": "f90712123fb02287348dd34c0a282bb9",
    "hosts": [
      "example.com",
      "www.example.com"
    ],
    "expiresOn": "2025-12-31T23:59:59Z",
    "uploadedOn": "2024-01-01T00:00:00Z",
    "issuer": "Let's Encrypt Authority X3",
    "signature": "SHA256",
    "status": "ACTIVE",
    "minTlsVersion": "1.2",
    "certificateType": "custom",
    "certificateAuthority": "lets_encrypt",
    "certificateValidation": "http",
    "certificateVerificationTXTName": "_acme-challenge.example.com",
    "certificateVerificationTXTValue": "abc123def456ghi789",
    "certificateVerificationStatus": "ACTIVE",
    "wildcardHostname": false,
    "wildcardCertificateVerificationTXTName": "_acme-challenge.wildcard.example.com",
    "wildcardCertificateVerificationTXTValue": "wildcard_abc123def456",
    "wildcardCertificateVerificationStatus": "ACTIVE",
    "customHostnameVerificationTXTName": "_acme-challenge.custom.example.com",
    "customHostnameVerificationTXTValue": "custom_abc123def456",
    "customHostnameId": "f90712123fb02287348dd34c0a282bb9",
    "customHostname": "custom.example.com",
    "customHostnameStatus": "ACTIVE",
    "dcvDelegationRecords": []
  }
}
```

### CustomHostnameValidationEnvelope

*   `data` (_CustomHostnameValidationResponse_, required)

_Example_

```
{
  "data": {
    "customHostnameId": "a439eb1f-5e71-4544-bb29-54d18ax62277",
    "customHostname": "test.example.com",
    "customHostnameVerificationTXTName": "_acme-challenge.test.example.com",
    "customHostnameVerificationTXTValue": "DBCtxdyQSyo9eXxys-uGVCwPFHLsc8_lu11QetQz4IA",
    "customHostnameStatus": "ACTIVE"
  }
}
```

### MRTRulesResponseEnvelope

*   `data` (_MRTRulesResponse_, required)

_Example_

```
{
  "data": {
    "ruleset": {
      "id": "12345678901234asdfasfasdf",
      "name": "MRT Rules",
      "lastUpdated": "2022-01-01T05:20:00Z",
      "rules": []
    }
  }
}
```

### MRTRulesPostRequest

POST request for creating MRT rules. MRT rules are a way to route certain storefront requests to the managed runtime instance.

*   `mrtHostname` (_string_, required) The customer's MRT instance hostname.  
    Pattern: ^.\*$. Example: `customer-react-project-production.mobify-storefront.com`.
*   `expressions` (_array of string_, required) An array containing the expressions for each MRT rule.  
    Items: Pattern: ^.\*$. Example: `(http.host eq "dev-customer.salesforce.com" and not ( http.request.uri.path matches "^/path1/.*" or http.request.uri.path matches "^.*/path2/.*/products/.*"))`.
    
    _Example_
    
    ```
    [
      "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path1/.*\" or http.request.uri.path matches \"^.*/path2/.*/products/.*\"))"
    ]
    ```
    
*   `descriptions` (_array of string_) An array containing the descriptions for each MRT rule. The number of descriptions provided must match the number of expressions provided. Optional.  
    Items: Pattern: ^.\*$. Example: `Phased rollout rule for dev-customer.salesforce.com`.
    
    _Example_
    
    ```
    [
      "Phased rollout rule for dev-customer.salesforce.com"
    ]
    ```
    

_Example_

```
{
  "mrtHostname": "customer-react-project-production.mobify-storefront.com",
  "expressions": [
    "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path1/.*\" or http.request.uri.path matches \"^.*/path2/.*/products/.*\"))"
  ],
  "descriptions": [
    "Phased rollout rule for dev-customer.salesforce.com"
  ]
}
```

### MRTRulesetPatchRequest

PATCH request for updating the MRT environment hostname or adding MRT rules to route to an existing MRT environment.

*   `oldMrtHostname` (_string_) The customer's current MRT instance hostname.  
    Pattern: ^.\*$. Example: `customer-react-projec-production.mobify-storefront.com`.
*   `mrtHostname` (_string_, required) The customer's MRT instance hostname.  
    Pattern: ^.\*$. Example: `customer-react-projec-production.mobify-storefront.com`.
*   `expressions` (_array of string_) An array containing the expressions for each MRT rule.  
    Items: Pattern: ^.\*$. Example: `(http.host eq "dev-customer.salesforce.com" and not ( http.request.uri.path matches "^/path1/.*" or http.request.uri.path matches "^.*/path2/.*/products/.*"))`.
    
    _Example_
    
    ```
    [
      "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path1/.*\" or http.request.uri.path matches \"^.*/path2/.*/products/.*\"))"
    ]
    ```
    
*   `descriptions` (_array of string_) An array containing the descriptions for each MRT rule. The number of descriptions provided must match the number of expressions provided. Optional.  
    Items: Pattern: ^.\*$. Example: `Phased rollout rule for dev-customer.salesforce.com`.
    
    _Example_
    
    ```
    [
      "Phased rollout rule for dev-customer.salesforce.com"
    ]
    ```
    

_Example_

```
{
  "mrtHostname": "customer-react-projec-production.mobify-storefront.com",
  "expressions": [
    "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path1/.*\" or http.request.uri.path matches \"^.*/path2/.*/products/.*\"))"
  ],
  "descriptions": [
    "Phased rollout rule for dev-customer.salesforce.com"
  ]
}
```

### MRTRulePatchRequest

PATCH request for updating an MRT rule. You may use the PATCH request to update the rule's expression and description as well as disable/enable the rule.

*   `enabled` (_boolean_) Whether or not the rule is enabled.  
    Example: `true`.
*   `expression` (_string_) The expression that determines the MRT rule's routing behavior.  
    Pattern: ^.\*$. Example: `(http.host eq "dev-customer.salesforce.com" and not ( http.request.uri.path matches "^/path1/.*" or http.request.uri.path matches "^.*/path2/.*/products/.*"))`.
*   `description` (_string_) The description of the rule. Optional.  
    Pattern: ^.\*$. Example: `Phased rollout rule for dev-customer.salesforce.com`.

_Example_

```
{
  "enabled": true,
  "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path1/.*\" or http.request.uri.path matches \"^.*/path2/.*/products/.*\"))",
  "description": "Phased rollout rule for dev-customer.salesforce.com"
}
```

### LogpushOwnershipPostRequest

POST request for creating new Logpush Ownership.

*   `destinationPath` (_string_, required) Uniquely identifies a resource (such as an s3 bucket) where data will be pushed. Additional configuration parameters supported by the destination may be included. You can use the special string {DATE} in the URL path to separate logs into daily subdirectories; for example s3://customer-bucket/logs/{DATE}?region=us-east-1&sse=AES256. The name of the directory will be replaced with the date in YYYYMMDD format (e.g. 20220215) when the logs are stored.  
    Pattern: ^.\*$. Example: `s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256`.

_Example_

```
{
  "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256"
}
```

### LogpushOwnershipPostResponse

POST response for created new Logpush Ownership.

*   `data` (_object_, required) The customer's new Logpush Ownership.
    *   `destinationPath` (_string_, required) Destination where logs will be sent (S3 bucket only).  
        Pattern: ^.\*$. Example: `s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256`.
    *   `fileName` (_string_, required) File path where the ownership challenge file is written.  
        Pattern: ^.\*$. Example: `site-name/20230101/ownership-challenge-d12345678.txt`.

_Example_

```
{
  "data": {
    "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
    "fileName": "site-name/20230101/ownership-challenge-d12345678.txt"
  }
}
```

### LogpushJobsEnvelope

*   `data` (_array of LogpushResponse_, required)

_Example_

```
{
  "data": [
    {
      "jobId": 123456,
      "name": "my-logpush-job",
      "logType": "http_requests",
      "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
      "logFields": [
        "ClientRequestBytes",
        "ClientRequestHost",
        "ClientRequestMethod"
      ],
      "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
      "enabled": false,
      "lastComplete": "2023-01-02T00:00:00Z",
      "lastError": "2023-01-01T10:00:00Z",
      "errorMessage": "No permissions to write to destination bucket",
      "createdOn": "2023-01-01T00:00:27Z"
    }
  ]
}
```

### LogpushCreateRequest

Request for create Logpush job.

*   `destinationPath` (_string_, required) Uniquely identifies s3 bucket for logs. Additional configuration parameters like region can be included. The string {DATE} in the URL path to separate logs into daily subdirectories; for example `s3://customer-bucket/logs/{DATE}?region=us-east-1&sse=AES256` The name of the directory will be replaced with the date in YYYYMMDD format (e.g. 20220215) when the logs are stored.  
    Pattern: ^.\*$. Example: `s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256`.
*   `name` (_string_, required) Logpush job name; the name cannot be changed after the job is created.  
    Pattern: ^.\*$. Example: `my-logpush-job`.
*   `filter` (_string_) Filter provides a way to customize which logs you want to receive. Filters are added as escaped JSON strings formatted. Default will include all logs.  
    Pattern: ^.\*$. Example: `{"where":{"key":"ClientRequestPath","operator":"contains","value":"/example-path"}}`.
*   `logFields` (_array of string_, required) List of log fields. Depending on the type of log, the list of fields that you would like to see in the logs may vary.  
    Items: Pattern: ^.\*$. Example: `ClientRequestBytes`.
    
    _Example_
    
    ```
    [
      "ClientRequestBytes",
      "ClientRequestHost",
      "ClientRequestMethod"
    ]
    ```
    
*   `ownershipChallengeToken` (_string_) Ownership token to proves the ownership of the destinationPath.  
    Pattern: ^.\*$. Example: `abc00000000000000000000`.
*   `enabled` (_boolean_) Enable logpush job while creating it.  
    Example: `true`.
*   `logType` (_string_, required) Type of logs. Available log types are `http_requests`, `firewall_events`, and `page_shield_events`.  
    Allowed values: `http_requests`, `firewall_events`, `page_shield_events`. Example: `http_requests`.

_Example_

```
{
  "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
  "name": "my-logpush-job",
  "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
  "logFields": [
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestMethod"
  ],
  "ownershipChallengeToken": "abc00000000000000000000",
  "logType": "http_requests"
}
```

### LogpushEnvelope

*   `data` (_LogpushResponse_, required)

_Example_

```
{
  "data": {
    "jobId": 123456,
    "name": "my-logpush-job",
    "logType": "http_requests",
    "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
    "logFields": [
      "ClientRequestBytes",
      "ClientRequestHost",
      "ClientRequestMethod"
    ],
    "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
    "enabled": false,
    "lastComplete": "2023-01-02T00:00:00Z",
    "lastError": "2023-01-01T10:00:00Z",
    "errorMessage": "No permissions to write to destination bucket",
    "createdOn": "2023-01-01T00:00:27Z"
  }
}
```

### LogpushUpdateRequest

Request for update Logpush job

*   `destinationPath` (_string_) Uniquely identifies the destination path for log storage. This string can include additional configuration parameters, such as the AWS region. Use the {DATE} placeholder in the URL path to automatically organize logs into daily subdirectories; for example, `s3://customer-bucket/logs/{DATE}?region=us-east-1&sse=AES256`. At runtime, the {DATE} variable is replaced with the current date in YYYYMMDD format, for example, 20260127, to ensure logs are stored in the appropriate daily folder.  
    Pattern: ^.\*$. Example: `s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256`.
*   `enabled` (_boolean_) Flag that indicates if the job is enabled or disabled.  
    Example: `true`.
*   `filter` (_string_) Provides customized selection for logs you want to receive. Filters are added as escaped, formatted JSON strings. By default, all logs are included.  
    Pattern: ^.\*$. Example: `{"where":{"key":"ClientRequestPath","operator":"contains","value":"/example-path"}}`.
*   `logFields` (_array of string_) List of log fields. Depending on the log type, the list of fields that you can specify to be displayed in the log might vary.  
    Items: Pattern: ^.\*$. Example: `ClientRequestBytes`.
    
    _Example_
    
    ```
    [
      "ClientRequestBytes",
      "ClientRequestHost",
      "ClientRequestMethod"
    ]
    ```
    

_Example_

```
{
  "enabled": true,
  "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
  "logFields": [
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestMethod"
  ]
}
```

### WAFRulePackageEnvelope

*   `data` (_WAFRulePackage_, required)

_Example_

```
{
  "data": {
    "id": "a25a9a7e9c00afc1fb2e0245519d725b",
    "name": "OWASP Top 10 Protection",
    "description": "Protection against OWASP Top 10 vulnerabilities",
    "detection_mode": "traditional",
    "zone_id": "zone_1234567890abcdef",
    "sensitivity": "medium",
    "action_mode": "block"
  }
}
```

### WafPackagePatchRequest

*   `sensitivity` (_string_, required) Sensitivity for traditional (owasp) rule package.  
    Allowed values: `low`, `medium`, `high`, `off`. Example: `medium`.
*   `action_mode` (_string_, required) The default action that is taken for rules under traditional(owasp) firewall package.  
    Allowed values: `simulate`, `challenge`, `block`. Example: `block`.

_Example_

```
{
  "sensitivity": "medium",
  "action_mode": "block"
}
```

### CustomRulesEnvelope

*   `data` (_array of CustomRule_, required)

_Example_

```
{
  "data": [
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Block traffic for malformed URL requests.",
      "expression": "(http.request.uri.path matches \"^/path1/.*\")",
      "actions": [
        "block"
      ],
      "lastUpdated": "2022-01-01T05:20:00Z",
      "enabled": true
    },
    {
      "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
      "description": "Rate limit form traffic",
      "expression": "http.request.uri.path eq \"/form\"",
      "actions": [
        "block"
      ],
      "lastUpdated": "2022-12-14T21:25:22.329194Z",
      "enabled": false
    }
  ]
}
```

### CustomRulesPostRequest

Create a custom rule.

*   `description` (_string_, required) A description of the custom rule.  
    Pattern: ^.\*$. Example: `Block traffic for malformed URL requests`.
*   `expression` (_string_, required) The expression that determines the custom rule's behavior.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches \"^/path1/.*\")`.
*   `actions` (_array of string_, required) The action(s) applied by the custom rule.  
    Items: Pattern: ^.\*$. Example: `block`.
    
    _Example_
    
    ```
    [
      "block"
    ]
    ```
    
*   `enabled` (_boolean_) Whether or not the custom rule is enabled.  
    Example: `true`.
*   `position` (_RulePosition_)

### CustomRuleEnvelope

*   `data` (_CustomRule_, required)

_Example_

```
{
  "data": {
    "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "description": "Block traffic for malformed URL requests.",
    "expression": "(http.request.uri.path matches \"^/path1/.*\")",
    "actions": [
      "block"
    ],
    "lastUpdated": "2022-01-01T05:20:00Z",
    "enabled": true
  }
}
```

### CustomRulesPatchOrderRequest

Update the order of all existing custom rules.

*   `ruleIds` (_array of string_, required) An array of ruleIds representing the new order of custom rules.  
    Items: Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
    
    _Example_
    
    ```
    [
      "ffffe61cf25e4ec49c34b029ff3060f7",
      "2c0fc9fa937b11eaa1b71c4d701ab86e"
    ]
    ```
    

### CustomRulesPatchRequest

Update a custom rule.

*   `description` (_string_) A description of the custom rule.  
    Pattern: ^.\*$. Example: `Block traffic for malformed URL requests`.
*   `expression` (_string_) The expression that determines the custom rule's behavior.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches \"^/path1/.*\")`.
*   `actions` (_array of string_) The action(s) applied by the custom rule.  
    Items: Pattern: ^.\*$. Example: `block`.
    
    _Example_
    
    ```
    [
      "block"
    ]
    ```
    
*   `enabled` (_boolean_) Whether or not the custom rule is enabled.  
    Example: `true`.
*   `position` (_RulePosition_)

### RateLimitingRulesEnvelope

*   `data` (_array of RateLimitingRule_, required)

### RateLimitingRulesPostRequest

Create a rate limiting rule.

*   `description` (_string_, required) The description of the rate limiting rule.  
    Pattern: ^.\*$. Example: `Rate limit /path1.`.
*   `expression` (_string_, required) The expression that defines when to evaluate the rate limiting rule.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/path1/.*")`.
*   `characteristics` (_array of string_, required) Set of parameters defining how to group requests when tracking the request rate.  
    Items: Pattern: ^.\*$. Example: `cf.unique_visitor_id`.
    
    _Example_
    
    ```
    [
      "cf.unique_visitor_id"
    ]
    ```
    
*   `action` (_string_, required) The action applied by the rate limiting rule. Valid actions are "block", "managed\_challenge", "js\_challenge", "legacy\_captcha", and "log".  
    Pattern: ^.\*$. Example: `block`.
*   `period` (_integer_, required) The period of time to consider when evaluating the request rate (in seconds). Valid values are 10, 60, 120, 300, and 600.  
    Example: `60`.
*   `requestsPerPeriod` (_integer_, required) The limit for the number of requests in the specified period of time.  
    Example: `50`.
*   `mitigationTimeout` (_integer_, required) After the rate is reached, the rate limiting rule applies the rule action to further requests for the period of time defined in this field (in seconds). When set to 0, the rule throttles requests over the maximum configured rate. When greater than 0, the action is presented for the selected duration after the configured rate is exceeded. Valid values are 0, 60, 120, 300, 600, 3600, and 86400.  
    Example: `600`.
*   `countingExpression` (_string_) The expression that defines what kind of requests we want to rate limit.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/path1/.*" and http.response.code eq 400)`.
*   `enabled` (_boolean_) Whether or not the rate limiting rule is enabled.  
    Example: `true`.
*   `position` (_RulePosition_)

### RateLimitingRuleEnvelope

*   `data` (_RateLimitingRule_, required)

### RateLimitingRulesPatchRequest

Update a rate limiting rule.

*   `description` (_string_) The description of the rate limiting rule.  
    Pattern: ^.\*$. Example: `Rate limit /path1.`.
*   `expression` (_string_) The expression that defines when to evaluate the rate limiting rule.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/path1/.*")`.
*   `characteristics` (_array of string_) Set of parameters defining how to group requests when tracking the request rate.  
    Items: Pattern: ^.\*$. Example: `cf.unique_visitor_id`.
    
    _Example_
    
    ```
    [
      "cf.unique_visitor_id"
    ]
    ```
    
*   `action` (_string_) The action applied by the rate limiting rule. Valid actions are "block", "managed\_challenge", "js\_challenge", "legacy\_captcha", and "log".  
    Pattern: ^.\*$. Example: `block`.
*   `period` (_integer_) The period of time to consider when evaluating the request rate (in seconds). Valid values are 10, 60, 120, 300, and 600.  
    Example: `60`.
*   `requestsPerPeriod` (_integer_) The limit for the number of requests in the specified period of time.  
    Example: `50`.
*   `mitigationTimeout` (_integer_) After the rate is reached, the rate limiting rule applies the rule action to further requests for the period of time defined in this field (in seconds). When set to 0, the rule throttles requests over the maximum configured rate. When greater than 0, the action is presented for the selected duration after the configured rate is exceeded. Valid values are 0, 60, 120, 300, 600, 3600, and 86400.  
    Example: `600`.
*   `countingExpression` (_string_) The expression that defines what kind of requests we want to rate limit.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/path1/.*" and http.response.code eq 400)`.
*   `enabled` (_boolean_) Whether or not the rate limiting rule is enabled.  
    Example: `true`.
*   `position` (_RulePosition_)

### WAFManagedRulesetsEnvelope

*   `data` (_array of WAFManagedRuleset_, required)

_Example_

```
{
  "data": [
    {
      "name": "OWASP Core Ruleset",
      "rulesetId": "4814384a9e5d4991b9815dcfc25d2f1f",
      "action": "default",
      "anomalyScore": "low",
      "anomalyScoreThreshold": 60,
      "paranoiaLevel": 1,
      "enabled": true
    }
  ]
}
```

### WAFManagedRulesetRequest

A WAF managed ruleset request body.

*   `action` (_string_) The action applied by the WAF managed ruleset.  
    Pattern: ^.\*$. Example: `default`.
*   `anomalyScore` (_string_) The anomaly score threshold of the WAF managed ruleset. Only applicable for the OWASP Core Ruleset.  
    Pattern: ^.\*$. Example: `low`.
*   `paranoiaLevel` (_integer_) The paranoia level of the WAF managed ruleset. Higher paranoia levels activate more aggressive rules. Only applicable for the OWASP Core Ruleset.  
    Example: `1`.
*   `enabled` (_boolean_) Whether or not the WAF managed ruleset is enabled.  
    Example: `true`.

_Example_

```
{
  "action": "default",
  "anomalyScore": "low",
  "paranoiaLevel": 1,
  "enabled": true
}
```

### WAFManagedRulesetEnvelope

*   `data` (_WAFManagedRuleset_, required)

_Example_

```
{
  "data": {
    "name": "OWASP Core Ruleset",
    "rulesetId": "4814384a9e5d4991b9815dcfc25d2f1f",
    "action": "default",
    "anomalyScore": "low",
    "anomalyScoreThreshold": 60,
    "paranoiaLevel": 1,
    "enabled": true
  }
}
```

### WAFManagedRulesEnvelope

*   `data` (_array of WAFManagedRule_, required)

_Example_

```
{
  "data": [
    {
      "ruleId": "5de7edfa648c4d6891dc3e7f84534ffa",
      "action": "block",
      "score": 5,
      "categories": [
        "broken-access-control",
        "wordpress"
      ],
      "description": "Wordpress - Broken Access Control",
      "lastUpdated": "2024-01-01T05:20:00Z",
      "enabled": true
    }
  ]
}
```

### WAFManagedRuleRequest

A PATCH request for updating a WAF managed rule.

*   `action` (_string_) The action applied by the WAF managed rule.  
    Pattern: ^.\*$. Example: `block`.
*   `enabled` (_boolean_) Whether or not the WAF managed rule is enabled.  
    Example: `true`.

_Example_

```
{
  "action": "block",
  "enabled": true
}
```

### WAFManagedRuleEnvelope

*   `data` (_WAFManagedRule_, required)

_Example_

```
{
  "data": {
    "ruleId": "5de7edfa648c4d6891dc3e7f84534ffa",
    "action": "block",
    "score": 5,
    "categories": [
      "broken-access-control",
      "wordpress"
    ],
    "description": "Wordpress - Broken Access Control",
    "lastUpdated": "2024-01-01T05:20:00Z",
    "enabled": true
  }
}
```

### OriginHeaderModificationEnvelope

*   `data` (_OriginHeaderModification_, required)

### OriginHeaderModificationPutRequest

Put request for creating/updating the origin header modification.

*   `headerValue` (_string_, required) The value of the header forwarded to the origin.  
    Pattern: ^.\*$. Example: `123456789`.
*   `headerName` (_string_) The name of the header forwarded to the origin. Cannot be modified for the MRT origin.  
    Pattern: ^.\*$. Example: `x-sfdc-access-control`.

### CipherSuitesEnvelope

*   `data` (_CipherSuitesResponse_, required)

_Example_

```
{
  "data": {
    "cipherSuiteType": "Modern"
  }
}
```

### CipherSuitesRequest

Cipher suites information.

*   `ciphers` (_array of string_) List of zone level ciphers in the suite.  
    Items: Pattern: ^.\*$. Example: `ECDHE-ECDSA-AES128-GCM-SHA256`.
    
    _Example_
    
    ```
    [
      "ECDHE-ECDSA-AES128-GCM-SHA256",
      "ECDHE-RSA-AES128-GCM-SHA256"
    ]
    ```
    
*   `cipherSuiteType` (_string_, required) Classification of all ciphers in the suite.  
    Allowed values: `Compatible`, `Modern`, `Custom`, `Legacy`. Example: `Modern`.

_Example_

```
{
  "cipherSuiteType": "Modern"
}
```

### TurnstileWidgetsEnvelope

*   `data` (_array of TurnstileWidget_, required)

### TurnstileWidgetCreateRequest

Request body to create a new Cloudflare Turnstile widget.

*   `name` (_string_, required) Logical widget name. Must be non-blank, not already contain the environment suffix, and must be at most 227 characters long so that the full Cloudflare-side name (`{name}-{environment}`) stays within the 255 character limit enforced for widgets.  
    Minimum length: 1. Maximum length: 227. Example: `checkout`.
*   `domains` (_array of string_, required) Hostnames allowed to present this widget.  
    Items: Minimum length: 1. Maximum length: 253. Example: `shop.example.com`. Minimum items: 1.
    
    _Example_
    
    ```
    [
      "shop.example.com",
      "www.example.com"
    ]
    ```
    
*   `mode` (_TurnstileWidgetMode_, required)

### TurnstileWidgetEnvelope

*   `data` (_TurnstileWidget_, required)

### TurnstileWidgetUpdateRequest

Request body to update an existing Cloudflare Turnstile widget. At least one of `domains` or `mode` must be supplied.

*   `domains` (_array of string_) Replacement list of hostnames allowed to present this widget.  
    Items: Minimum length: 1. Maximum length: 253. Example: `shop.example.com`. Minimum items: 1.
    
    _Example_
    
    ```
    [
      "shop.example.com",
      "www.example.com"
    ]
    ```
    
*   `mode` (_TurnstileWidgetMode_)

### StorefrontZoneCreateResponse

The response of create zone, includes zone and zone properties.

*   `zoneId` (_string_, required) The zone id tag.  
    Pattern: ^.\*$. Example: `023e105f4ecef8ad9ca31a8372d0c353`.
*   `zoneName` (_string_, required) The domain name for the zone.  
    Pattern: ^.\*$. Example: `stg-zzzz-cc-merchant-com.cc-ecdn.net`.
*   `status` (_string_, required) current status of the zone  
    Allowed values: `active`, `pending`, `initializing`, `moved`, `deleted`, `deactivated`. Example: `active`.
*   `createdOn` (_string (date-time)_, required) Date and time of zone creation.  
    Example: `2014-01-01T05:20:00.12345Z`.

### MtlsCertificateResponse

mTLS certificate information.

*   `mtlsCertificateId` (_string_) ID generated by the CDN provider for the certificate.  
    Pattern: ^.\*$. Example: `465a48f6-3d98-4c15-9312-211984ee8629`.
*   `expiresOn` (_string (date-time)_) Expiration date for the mTLS certificate.  
    Example: `2022-01-12T04:15:57Z`.
*   `issuer` (_string_) The certificate authority that issued the mTLS certificate.  
    Pattern: ^.\*$. Example: `DigiCert`.
*   `signature` (_string_) The type of hash used for the mTLS certificate.  
    Pattern: ^.\*$. Example: `SHA256WithRSA`.
*   `uploadedOn` (_string (date-time)_) Date the mTLS certificate was uploaded.  
    Example: `2020-01-12T04:15:57Z`.
*   `ca` (_boolean_) Indicates whether the mTLS certificate is a CA or leaf certificate.  
    Example: `true`.
*   `serialNumber` (_string_) The mTLS certificate serial number.  
    Pattern: ^.\*$. Example: `432217133297895665180570788458463042229861757760`.
*   `mtlsCertificateName` (_string_) Optional name for the mTLS certificate used for ease of understanding.  
    Pattern: ^.\*$. Example: `mtls_cert_name`.
*   `mtlsAssociatedCodeUploadHostname` (_string_) Hostname associated with this mTLS certificate.  
    Pattern: ^.\*$. Example: `mtls.cert.salesforce.com`.

### PageShieldNotificationWebhookResponse

Page shield notification for the webhook response.

*   `id` (_string_, required) Webhook ID.  
    Pattern: ^.\*$. Example: `webhook_1234567890abcdef`.
*   `name` (_string_, required) Webhook name.  
    Pattern: ^.\*$. Example: `Security Alert Webhook`.
*   `webhookUrl` (_string_, required) Webhook URL.  
    Pattern: ^.\*$. Example: `https://example.com/webhook/security`.
*   `type` (_string_, required) Webhook type.  
    Pattern: ^.\*$. Example: `security_alert`.
*   `createdAt` (_string (date-time)_, required) Timestamp of webhook creation.  
    Example: `2023-01-01T00:00:00Z`.
*   `lastSuccess` (_string (date-time)_) Timestamp of the last successful notification.  
    Example: `2023-01-01T12:00:00Z`.
*   `lastFailure` (_string (date-time)_) Timestamp of the last failed notification.  
    Example: `2023-01-01T18:00:00Z`.
*   `enabled` (_boolean_) Specifies whether or not the notification is enabled.  
    Example: `true`.
*   `zones` (_array of string_) Zone IDs on which to filter notifications alerts.  
    Items: Pattern: ^.\*$. Example: `zone_1234567890abcdef`.

_Example_

```
{
  "id": "webhook_1234567890abcdef",
  "name": "Security Alert Webhook",
  "webhookUrl": "https://example.com/webhook/security",
  "type": "security_alert",
  "createdAt": "2023-01-01T00:00:00Z",
  "lastSuccess": "2023-01-01T12:00:00Z",
  "lastFailure": "2023-01-01T18:00:00Z",
  "enabled": true,
  "zones": [
    "zone_1234567890abcdef"
  ]
}
```

### WebhookResponse

Webhook response

*   `id` (_string_, required) Webhook ID  
    Pattern: ^.\*$. Example: `ffffe61cf25e4ec49c34b029ff3060f7`.
*   `name` (_string_, required) Webhook name  
    Pattern: ^.\*$. Example: `My Webhook`.
*   `url` (_string_, required) Webhook URL  
    Pattern: ^.\*$. Example: `https://example.com/webhook`.
*   `type` (_string_, required) Webhook type  
    Pattern: ^.\*$. Example: `webhook`.
*   `createdAt` (_string (date-time)_, required) Timestamp of webhook creation  
    Example: `2023-01-01T00:00:00Z`.
*   `lastSuccess` (_string (date-time)_) Timestamp of the last successful notification  
    Example: `2023-01-01T12:00:00Z`.
*   `lastFailure` (_string (date-time)_) Timestamp of the last failed notification  
    Example: `2023-01-01T18:00:00Z`.

### PageShieldPolicyResponse

Page shield policy response.

*   `action` (_string_) Action taken when expression matches allow or log.  
    Allowed values: `allow`, `log`. Example: `allow`.
*   `description` (_string_) Description for the policy.  
    Pattern: ^.\*$. Example: `Allow scripts from trusted CDN sources`.
*   `enabled` (_boolean_) Enable/disable the policy.  
    Example: `true`.
*   `expression` (_string_) Expression of the policy.  
    Pattern: ^.\*$. Example: `http.request.uri.path contains "/trusted-cdn/"`.
*   `value` (_string_) Policy to be applied.  
    Pattern: ^.\*$. Example: `script-src`.
*   `id` (_string_) Policy ID  
    Pattern: ^.\*$. Example: `policy_1234567890abcdef`.

_Example_

```
{
  "action": "allow",
  "description": "Allow scripts from trusted CDN sources",
  "enabled": true,
  "expression": "http.request.uri.path contains \"/trusted-cdn/\"",
  "value": "script-src",
  "id": "policy_1234567890abcdef"
}
```

### PageShieldScriptResponse

Response of Page Shield script object.

*   `id` (_string_) Page Shield script ID.  
    Pattern: ^.\*$. Example: `12345678901234asdfasfasdf`.
*   `url` (_string_) Page Shield script URL.  
    Pattern: ^.\*$. Example: `https://sfdc-test.net/on/demandware.static/Sites-SiteNemesis-Site/-/en_US//lib/jquery/ui/jquery-ui.min.js`.
*   `host` (_string_) Hostname where the script was detected by Page Shield.  
    Pattern: ^.\*$. Example: `sfdc-test.net`.
*   `addedAt` (_string (date-time)_) Date the script was added to Page Shield.  
    Example: `2022-01-01T05:20:00Z`.
*   `firstSeenAt` (_string (date-time)_) Date the script was detected by Page Shield.  
    Example: `2022-01-01T05:20:00Z`.
*   `lastSeenAt` (_string (date-time)_) Date the script was recently detected by Page Shield.  
    Example: `2022-01-01T05:20:00Z`.
*   `fetchedAt` (_string (date-time)_) The timestamp when the script was last fetched.  
    Example: `2022-01-01T05:20:00Z`.
*   `domainReportedMalicious` (_boolean_) Reported domain is malicious.  
    Example: `false`.
*   `hash` (_string_) The computed hash of the analyzed script.  
    Pattern: ^.\*$. Example: `1243453456abc`.
*   `cryptoMiningScore` (_integer_) The crypto mining score of the JavaScript content.  
    Example: `1`.
*   `dataflowScore` (_integer_) The dataflow score of the JavaScript content.  
    Example: `1`.
*   `jsIntegrityScore` (_integer_) The integrity score of the JavaScript content.  
    Example: `1`.
*   `mageCartScore` (_integer_) The Magecart score of the JavaScript content.  
    Example: `2`.
*   `malwareScore` (_integer_) The malware score of the JavaScript content.  
    Example: `1`.
*   `obfuscationScore` (_integer_) The obfuscation score of the JavaScript content.  
    Example: `2`.
*   `maliciousDomainCategories` (_array of string_) Malicious domain category.  
    Items: Pattern: ^.\*$. Example: `Malware`.
    
    _Example_
    
    ```
    [
      "Malware"
    ]
    ```
    
*   `maliciousUrlCategories` (_array of string_) Malicious URL category.  
    Items: Pattern: ^.\*$. Example: `Malware`.
    
    _Example_
    
    ```
    [
      "Malware"
    ]
    ```
    
*   `urlContainsCdnCgiPath` (_boolean_) URL contains CDN CGI path.  
    Example: `false`.
*   `urlReportedMalicious` (_boolean_) Reported URL is malicious.  
    Example: `false`.
*   `pageUrls` (_array of string_) Page URLs  
    Items: Pattern: ^.\*$. Example: `blog.test.salesforce.com/page1`.
    
    _Example_
    
    ```
    [
      "blog.test.salesforce.com/page1",
      "blog.test.salesforce.com/page2"
    ]
    ```
    
*   `firstPageUrl` (_string_) First page URL for the JavaScript.  
    Pattern: ^.\*$. Example: `blog.test.salesforce.com`.
*   `status` (_string_) The current status of the script. Possible values are active, inactive, or infrequent.  
    Pattern: ^.\*$. Example: `active`.
*   `versions` (_array of PageShieldScriptVersion_) List of script versions.

_Example_

```
{
  "id": "12345678901234asdfasfasdf",
  "url": "https://sfdc-test.net/on/demandware.static/Sites-SiteNemesis-Site/-/en_US//lib/jquery/ui/jquery-ui.min.js",
  "host": "sfdc-test.net",
  "addedAt": "2022-01-01T05:20:00Z",
  "firstSeenAt": "2022-01-01T05:20:00Z",
  "lastSeenAt": "2022-01-01T05:20:00Z",
  "fetchedAt": "2022-01-01T05:20:00Z",
  "domainReportedMalicious": false,
  "hash": "1243453456abc",
  "cryptoMiningScore": 1,
  "dataflowScore": 1,
  "jsIntegrityScore": 1,
  "mageCartScore": 2,
  "malwareScore": 1,
  "obfuscationScore": 2,
  "maliciousDomainCategories": [
    "Malware"
  ],
  "maliciousUrlCategories": [
    "Malware"
  ],
  "urlContainsCdnCgiPath": false,
  "urlReportedMalicious": false,
  "pageUrls": [
    "blog.test.salesforce.com/page1",
    "blog.test.salesforce.com/page2"
  ],
  "firstPageUrl": "blog.test.salesforce.com",
  "status": "active",
  "versions": []
}
```

### Zone

Zone

Zone is the container for hostnames and various CDN settings/properties. Each zone is tied to a single origin.

*   `zoneId` (_string_, required) Identity of the zone.  
    Maximum length: 100. Example: `example1-zone-Id`.
*   `name` (_string_, required) Name given to the zone. This needs to be a DNS domain name for eg example.com  
    Maximum length: 100. Example: `example1.com`.
*   `status` (_string_, required) Status of the zone for eg "Pending" , "Active"  
    Allowed values: `active`, `pending`, `initializing`, `moved`, `deleted`, `deactivated`. Example: `pending`.

_Example_

```
{
  "zoneId": "example1-zone-Id",
  "name": "example1.com",
  "status": "pending"
}
```

### CachePurgeResponse

Response from a cache purge request

*   `cachePurged` (_boolean_, required) The name of the list.  
    Example: `false`.
*   `details` (_string_, required) Details of errors if any.  
    Pattern: ^.\*$. Example: `1084 : Unable to purge '<url>'.`.

_Example_

```
{
  "cachePurged": false,
  "details": "1084 : Unable to purge '<url>'."
}
```

### CacheRule

A cache rule configuration.

*   `ruleId` (_string_, required) The unique identifier for the cache rule.  
    Pattern: ^.\*$. Example: `2c0fc9fa937b11eaa1b71c4d701ab86e`.
*   `description` (_string_, required) A description of what the cache rule does.  
    Pattern: ^.\*$. Example: `Cache static assets on product pages`.
*   `expression` (_string_, required) The expression that defines when this cache rule applies.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/product/.*")`.
*   `action` (_string_, required) The action to take ("cache" to enable caching, "bypass" to bypass cache).  
    Pattern: ^.\*$. Example: `cache`.
*   `excludeQueryStrings` (_array of string_) List of query string parameters to exclude from the cache key.  
    Items: Pattern: ^.\*$. Example: `gclid`.
    
    _Example_
    
    ```
    [
      "gclid",
      "utm_campaign"
    ]
    ```
    
*   `ignoreQueryStringsOrder` (_boolean_) Specifies whether the order of query string parameters in the cache key is ignored.  
    Example: `true`.
*   `respectStrongEtags` (_boolean_) Specifies whether strong ETags are respected.  
    Example: `false`.
*   `lastUpdated` (_string (date-time)_) The timestamp when the rule was last updated.  
    Example: `2022-01-01T05:20:00Z`.
*   `enabled` (_boolean_, required) Specifies whether the rule is enabled.  
    Example: `true`.

### RulePosition

Used to specify the position of a rule.

*   `before` (_string_) Insert the current rule before this ruleId.  
    Pattern: ^.\*$. Example: `2c0fc9fa937b11eaa1b71c4d701ab86e`.
*   `after` (_string_) Insert the current rule after this ruleId.  
    Pattern: ^.\*$. Example: `2c0fc9fa937b11eaa1b71c4d701ab86e`.

### Certificate

The certificate information

*   `certificateId` (_string_, required) Id generated by CDN provider for the certificate.  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `hosts` (_array of string_) List of hosts the certificate applies to.  
    Items: Pattern: ^.\*$. Example: `example.com`.
    
    _Example_
    
    ```
    [
      "example.com",
      "www.example.com"
    ]
    ```
    
*   `expiresOn` (_string (date-time)_) Date of expiration for the certificate.  
    Example: `2025-12-31T23:59:59Z`.
*   `uploadedOn` (_string (date-time)_) Date the certificate was uploaded.  
    Example: `2024-01-01T00:00:00Z`.
*   `issuer` (_string_) The certificate authority that issued the certificate.  
    Pattern: ^.\*$. Example: `Let's Encrypt Authority X3`.
*   `signature` (_string_) The type of hash used for the certificate.  
    Pattern: ^.\*$. Example: `SHA256`.
*   `status` (_string_, required) Current status of the certificate.  
    Allowed values: `ACTIVE`, `EXPIRED`, `DELETED`, `PENDING`, `INITIALIZING`, `PENDING_VALIDATION`, `PENDING_ISSUANCE`, `PENDING_DEPLOYMENT`, `PENDING_DELETION`, `VALIDATION_TIMED_OUT`, `DEPLOYMENT_TIMED_OUT`, `DELETION_TIMED_OUT`, `INITIALIZING_TIMED_OUT`, `PENDING_EXPIRATION`, `ISSUANCE_TIMED_OUT`. Example: `ACTIVE`.
*   `minTlsVersion` (_string_) Minimum TLS Version only allows HTTPS connections from visitors that support the selected TLS protocol version or newer.  
    Pattern: ^.\*$. Example: `1.2`.
*   `certificateType` (_string_, required) Indicates certificate is custom cert uploaded by customer or automatic renewal certificate by eCDN.  
    Allowed values: `custom`, `automatic`, `custom_legacy`. Example: `custom`.
*   `certificateAuthority` (_string_) Indicates certificate issuer for automatic renewal certificate by eCDN.  
    Allowed values: `google`, `lets_encrypt`, `digicert`. Example: `lets_encrypt`.
*   `certificateValidation` (_string_) Indicates certificate validation type for automatic renewal certificate by eCDN.  
    Allowed values: `http`, `txt`. Example: `http`.
*   `certificateVerificationTXTName` (_string_) eCDN automatic renewal certificate verification txt name.  
    Pattern: ^.\*$. Example: `_acme-challenge.example.com`.
*   `certificateVerificationTXTValue` (_string_) eCDN automatic renewal certificate verification txt value.  
    Pattern: ^.\*$. Example: `abc123def456ghi789`.
*   `certificateVerificationStatus` (_string_) Current status of certificate verification.  
    Allowed values: `ACTIVE`, `EXPIRED`, `PENDING`, `INITIALIZING`, `PENDING_VALIDATION`, `PENDING_ISSUANCE`, `PENDING_DEPLOYMENT`. Example: `ACTIVE`.
*   `wildcardHostname` (_boolean_) Set to true for a wildcard custom hostname.  
    Example: `false`.
*   `wildcardCertificateVerificationTXTName` (_string_) eCDN automatic renewal certificate verification txt name.  
    Pattern: ^.\*$. Example: `_acme-challenge.wildcard.example.com`.
*   `wildcardCertificateVerificationTXTValue` (_string_) eCDN automatic renewal certificate verification txt value.  
    Pattern: ^.\*$. Example: `wildcard_abc123def456`.
*   `wildcardCertificateVerificationStatus` (_string_) Current status of certificate verification.  
    Allowed values: `ACTIVE`, `EXPIRED`, `PENDING`, `INITIALIZING`, `PENDING_VALIDATION`, `PENDING_ISSUANCE`, `PENDING_DEPLOYMENT`. Example: `ACTIVE`.
*   `customHostnameVerificationTXTName` (_string_) Custom Hostname verification txt name.  
    Pattern: ^.\*$. Example: `_acme-challenge.custom.example.com`.
*   `customHostnameVerificationTXTValue` (_string_) Custom Hostname verification txt value.  
    Pattern: ^.\*$. Example: `custom_abc123def456`.
*   `customHostnameId` (_string_) Custom hostname associated with the zone  
    Pattern: ^.\*$. Example: `f90712123fb02287348dd34c0a282bb9`.
*   `customHostname` (_string_) Custom hostname associated with the zone  
    Pattern: ^.\*$. Example: `custom.example.com`.
*   `customHostnameStatus` (_string_) Current status of custom hostname validation.  
    Allowed values: `ACTIVE`, `EXPIRED`, `DELETED`, `PENDING`, `INITIALIZING`, `PENDING_VALIDATION`, `PENDING_ISSUANCE`, `PENDING_DEPLOYMENT`, `PENDING_DELETION`, `MOVED`. Example: `ACTIVE`.
*   `verificationErrors` (_array of string_) When the custom hostname is not active, Cloudflare returns one or more verification error messages explaining why. This field is omitted if the hostname is active or no errors are present.  
    Items: Pattern: ^.\*$. Example: `The hostname is using Cloudflare and cannot be activated with a TXT or HTTP validation token. To activate the custom hostname, the DNS target needs to point to the SaaS zone.`.
    
    _Example_
    
    ```
    [
      "custom hostname does not CNAME to this zone.",
      "The hostname is using Cloudflare and cannot be activated with a TXT or HTTP validation token. To activate the custom hostname, the DNS target needs to point to the SaaS zone."
    ]
    ```
    
*   `dcvDelegationRecords` (_array of DCVDelegationRecord_) eCDN automatic renewal certificate DCV delegation records

_Example_

```
{
  "certificateId": "f90712123fb02287348dd34c0a282bb9",
  "hosts": [
    "example.com",
    "www.example.com"
  ],
  "expiresOn": "2025-12-31T23:59:59Z",
  "uploadedOn": "2024-01-01T00:00:00Z",
  "issuer": "Let's Encrypt Authority X3",
  "signature": "SHA256",
  "status": "ACTIVE",
  "minTlsVersion": "1.2",
  "certificateType": "custom",
  "certificateAuthority": "lets_encrypt",
  "certificateValidation": "http",
  "certificateVerificationTXTName": "_acme-challenge.example.com",
  "certificateVerificationTXTValue": "abc123def456ghi789",
  "certificateVerificationStatus": "ACTIVE",
  "wildcardHostname": false,
  "wildcardCertificateVerificationTXTName": "_acme-challenge.wildcard.example.com",
  "wildcardCertificateVerificationTXTValue": "wildcard_abc123def456",
  "wildcardCertificateVerificationStatus": "ACTIVE",
  "customHostnameVerificationTXTName": "_acme-challenge.custom.example.com",
  "customHostnameVerificationTXTValue": "custom_abc123def456",
  "customHostnameId": "f90712123fb02287348dd34c0a282bb9",
  "customHostname": "custom.example.com",
  "customHostnameStatus": "ACTIVE",
  "dcvDelegationRecords": []
}
```

### CustomHostnameValidationResponse

Custom hostname validation information.

*   `customHostnameId` (_string_, required) Identifier generated by the CDN provider for the custom hostname.  
    Pattern: ^.\*$. Example: `a439eb1f-5e71-4544-bb29-54d18ax62277`.
*   `customHostname` (_string_, required) Name of the custom hostname  
    Pattern: ^.\*$. Example: `test.example.com`.
*   `customHostnameVerificationTXTName` (_string_, required) Custom hostname verification txt name.  
    Pattern: ^.\*$. Example: `_acme-challenge.test.example.com`.
*   `customHostnameVerificationTXTValue` (_string_, required) Custom hostname verification txt value.  
    Pattern: ^.\*$. Example: `DBCtxdyQSyo9eXxys-uGVCwPFHLsc8_lu11QetQz4IA`.
*   `customHostnameStatus` (_string_, required) Current status of the custom hostname.  
    Allowed values: `PENDING`, `ACTIVE`, `MOVED`, `DELETED`. Example: `ACTIVE`.

_Example_

```
{
  "customHostnameId": "a439eb1f-5e71-4544-bb29-54d18ax62277",
  "customHostname": "test.example.com",
  "customHostnameVerificationTXTName": "_acme-challenge.test.example.com",
  "customHostnameVerificationTXTValue": "DBCtxdyQSyo9eXxys-uGVCwPFHLsc8_lu11QetQz4IA",
  "customHostnameStatus": "ACTIVE"
}
```

### MRTRulesResponse

Response for MRT rules. MRT rules are a way to route certain storefront requests to the managed runtime instance.

*   `ruleset` (_MRTRuleset_, required)

_Example_

```
{
  "ruleset": {
    "id": "12345678901234asdfasfasdf",
    "name": "MRT Rules",
    "lastUpdated": "2022-01-01T05:20:00Z",
    "rules": []
  }
}
```

### LogpushResponse

Logpush job response

*   `jobId` (_integer_) Unique ID of the job.  
    Example: `123456`.
*   `name` (_string_) Logpush job name; the name cannot be changed after the job is created.  
    Pattern: ^.\*$. Example: `my-logpush-job`.
*   `logType` (_string_) Type of logs; available log types are `http_requests`, `firewall_events`, and `page_shield_events`.  
    Allowed values: `http_requests`, `firewall_events`, `page_shield_events`. Example: `http_requests`.
*   `filter` (_string_) Filter provides a way to customize which logs you want to receive. Filters are added as escaped JSON strings formatted. If the filter is not displayed, it indicates that all logs should be included.  
    Pattern: ^.\*$. Example: `{"where":{"key":"ClientRequestPath","operator":"contains","value":"/example-path"}}`.
*   `logFields` (_array of string_) List of log fields. Depending on the type of log, the list of fields that you would like to see in the logs may vary.  
    Items: Pattern: ^.\*$. Example: `ClientRequestBytes`.
    
    _Example_
    
    ```
    [
      "ClientRequestBytes",
      "ClientRequestHost",
      "ClientRequestMethod"
    ]
    ```
    
*   `destinationPath` (_string_) Uniquely identifies s3 bucket for logs.  
    Pattern: ^.\*$. Example: `s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256`.
*   `enabled` (_boolean_) Flag that indicates if the job is enabled or disabled.  
    Example: `false`.
*   `lastComplete` (_string (date-time)_) The last time that the log has been successfully transmitted to the destination.  
    Example: `2023-01-02T00:00:00Z`.
*   `lastError` (_string (date-time)_) The last time the job failed. If empty, the job has either never failed or has run successfully at least once since the last failure.  
    Example: `2023-01-01T10:00:00Z`.
*   `errorMessage` (_string_) Provide details for the last failure message. If this field is empty, it indicates that the job successfully transmitted logs to the destination.  
    Pattern: ^.\*$. Example: `No permissions to write to destination bucket`.
*   `createdOn` (_string (date-time)_) Job creation time.  
    Example: `2023-01-01T00:00:27Z`.

_Example_

```
{
  "jobId": 123456,
  "name": "my-logpush-job",
  "logType": "http_requests",
  "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
  "logFields": [
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestMethod"
  ],
  "destinationPath": "s3://customer-bucket/site-name/{DATE}?region=us-east-1&sse=AES256",
  "enabled": false,
  "lastComplete": "2023-01-02T00:00:00Z",
  "lastError": "2023-01-01T10:00:00Z",
  "errorMessage": "No permissions to write to destination bucket",
  "createdOn": "2023-01-01T00:00:27Z"
}
```

### WAFRulePackage

*   `id` (_string_, required)  
    Maximum length: 32. Example: `a25a9a7e9c00afc1fb2e0245519d725b`.
*   `name` (_string_, required) Name of the firewall package  
    Pattern: ^.\*$. Example: `OWASP Top 10 Protection`.
*   `description` (_string_, required) Summary of purpose/function of firewall package  
    Pattern: ^.\*$. Example: `Protection against OWASP Top 10 vulnerabilities`.
*   `detection_mode` (_string_, required) How the rules within the package are evaluated during the course of a request. When a package uses anomaly detection, each rule is given a score when triggered. If the total score of all triggered rules exceeds the sensitivity defined on the package, the action defined on the package is taken. Traditional detection decides which action to take when it is triggered by the request. If multiple rules are triggered, the action with highest protection is used. For example, a block action beats a challenge.  
    Pattern: ^.\*$. Example: `traditional`.
*   `zone_id` (_string_, required) Zone identifier with which this rule package is associated.  
    Pattern: ^.\*$. Example: `zone_1234567890abcdef`.
*   `sensitivity` (_string_, required) Sensitivity for traditional (owasp) rule package.  
    Allowed values: `low`, `medium`, `high`, `off`. Example: `medium`.
*   `action_mode` (_string_, required) The default action that is taken for rules under traditional(owasp) firewall package.  
    Allowed values: `simulate`, `challenge`, `block`. Example: `block`.

### CustomRule

A custom rule.

*   `ruleId` (_string_, required) The ID of the custom rule.  
    Pattern: ^.\*$. Example: `2c0fc9fa937b11eaa1b71c4d701ab86e`.
*   `description` (_string_, required) The description of the custom rule.  
    Pattern: ^.\*$. Example: `Block traffic for malformed URL requests.`.
*   `expression` (_string_, required) The expression that determines the custom rule's behavior.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches \"^/path1/.*\")`.
*   `actions` (_array of string_, required) The action(s) applied by the custom rule.  
    Items: Pattern: ^.\*$. Example: `block`.
    
    _Example_
    
    ```
    [
      "block"
    ]
    ```
    
*   `lastUpdated` (_string (date-time)_, required) Date when the custom rule was last updated.  
    Example: `2022-01-01T05:20:00Z`.
*   `enabled` (_boolean_, required) Whether or not the custom rule is enabled.  
    Example: `true`.

### RateLimitingRule

A rate limiting rule.

*   `ruleId` (_string_, required) The ID of the rate limiting rule.  
    Pattern: ^.\*$. Example: `2c0fc9fa937b11eaa1b71c4d701ab86e`.
*   `description` (_string_, required) The description of the rate limiting rule.  
    Pattern: ^.\*$. Example: `Rate limit /path1.`.
*   `expression` (_string_, required) The expression that defines when to evaluate the rate limiting rule.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/path1/.*")`.
*   `characteristics` (_array of string_, required) Set of parameters defining how to group requests when tracking the request rate.  
    Items: Pattern: ^.\*$. Example: `cf.unique_visitor_id`.
    
    _Example_
    
    ```
    [
      "cf.unique_visitor_id"
    ]
    ```
    
*   `action` (_string_, required) The action applied by the rate limiting rule. Valid actions are "block", "managed\_challenge", "js\_challenge", "legacy\_captcha", and "log".  
    Pattern: ^.\*$. Example: `block`.
*   `period` (_integer_, required) The period of time to consider when evaluating the request rate (in seconds). Valid values are 10, 60, 120, 300, and 600.  
    Example: `60`.
*   `requestsPerPeriod` (_integer_, required) The limit for the number of requests in the specified period of time.  
    Example: `50`.
*   `mitigationTimeout` (_integer_, required) After the rate is reached, the rate limiting rule applies the rule action to further requests for the period of time defined in this field (in seconds). When set to 0, the rule throttles requests over the maximum configured rate. When greater than 0, the action is presented for the selected duration after the configured rate is exceeded. Valid values are 0, 60, 120, 300, 600, 3600, and 86400.  
    Example: `600`.
*   `countingExpression` (_string_) The expression that defines what kind of requests we want to rate limit.  
    Pattern: ^.\*$. Example: `(http.request.uri.path matches "^/path1/.*" and http.response.code eq 400)`.
*   `lastUpdated` (_string (date-time)_, required) Date when the rate limiting rule was last updated.  
    Example: `2022-01-01T05:20:00Z`.
*   `enabled` (_boolean_, required) Whether or not the rate limiting rule is enabled.  
    Example: `true`.

### WAFManagedRuleset

A WAF managed ruleset.

*   `name` (_string_, required) The name of the WAF managed ruleset.  
    Pattern: ^.\*$. Example: `OWASP Core Ruleset`.
*   `rulesetId` (_string_, required) The ID of the WAF managed ruleset.  
    Pattern: ^.\*$. Example: `4814384a9e5d4991b9815dcfc25d2f1f`.
*   `action` (_string_, required) The action applied by the WAF managed ruleset.  
    Pattern: ^.\*$. Example: `default`.
*   `anomalyScore` (_string_) The anomaly score threshold of the WAF managed ruleset. Only applicable for the OWASP Core Ruleset.  
    Pattern: ^.\*$. Example: `low`.
*   `anomalyScoreThreshold` (_integer_) The numerical value of the anomaly score threshold of the WAF managed ruleset. Only applicable for the OWASP Core Ruleset.  
    Example: `60`.
*   `paranoiaLevel` (_integer_) The paranoia level of the WAF managed ruleset. Higher paranoia levels activate more aggressive rules. Only applicable for the OWASP Core Ruleset.  
    Example: `1`.
*   `enabled` (_boolean_, required) Whether or not the WAF managed ruleset is enabled.  
    Example: `true`.

_Example_

```
{
  "name": "OWASP Core Ruleset",
  "rulesetId": "4814384a9e5d4991b9815dcfc25d2f1f",
  "action": "default",
  "anomalyScore": "low",
  "anomalyScoreThreshold": 60,
  "paranoiaLevel": 1,
  "enabled": true
}
```

### WAFManagedRule

A WAF managed rule.

*   `ruleId` (_string_, required) The ID of the WAF managed rule.  
    Pattern: ^.\*$. Example: `5de7edfa648c4d6891dc3e7f84534ffa`.
*   `action` (_string_, required) The action applied by the WAF managed rule.  
    Pattern: ^.\*$. Example: `block`.
*   `score` (_integer_) The score of the WAF managed rule. Only applicable for the OWASP Managed Ruleset.  
    Example: `5`.
*   `categories` (_array of string_, required) A list of categories describing the function of the WAF managed rule.  
    Items: Pattern: ^.\*$. Example: `broken-access-control`.
    
    _Example_
    
    ```
    [
      "broken-access-control",
      "wordpress"
    ]
    ```
    
*   `description` (_string_, required) The description of the WAF managed rule.  
    Pattern: ^.\*$. Example: `Wordpress - Broken Access Control`.
*   `lastUpdated` (_string (date-time)_, required) Date when the WAF managed rule was last updated.  
    Example: `2024-01-01T05:20:00Z`.
*   `enabled` (_boolean_, required) Whether or not the WAF managed rule is enabled.  
    Example: `true`.

_Example_

```
{
  "ruleId": "5de7edfa648c4d6891dc3e7f84534ffa",
  "action": "block",
  "score": 5,
  "categories": [
    "broken-access-control",
    "wordpress"
  ],
  "description": "Wordpress - Broken Access Control",
  "lastUpdated": "2024-01-01T05:20:00Z",
  "enabled": true
}
```

### OriginHeaderModification

An origin header modification rule.

*   `headerName` (_string_, required) The name of the header forwarded to the origin.  
    Pattern: ^.\*$. Example: `x-sfdc-access-control`.
*   `headerValue` (_string_, required) The masked value of the header forwarded to the origin.  
    Pattern: ^.\*$. Example: `****************789`.
*   `lastUpdated` (_string (date-time)_, required) Date when the rule was last updated.  
    Example: `2022-01-01T05:20:00Z`.

### CipherSuitesResponse

Cipher suites information.

*   `ciphers` (_array of string_, required) List of zone level ciphers in the suite.  
    Items: Pattern: ^.\*$. Example: `ECDHE-ECDSA-AES128-GCM-SHA256`.
    
    _Example_
    
    ```
    [
      "ECDHE-ECDSA-AES128-GCM-SHA256",
      "ECDHE-RSA-AES128-GCM-SHA256"
    ]
    ```
    
*   `cipherSuiteType` (_string_, required) Classification of the ciphers in the suite.  
    Allowed values: `Compatible`, `Modern`, `Custom`, `Legacy`. Example: `Modern`.

_Example_

```
{
  "cipherSuiteType": "Modern"
}
```

### TurnstileWidget

Cloudflare Turnstile widget details, including the shared secret.

*   `sitekey` (_string_) Unique identifier for the widget.  
    Minimum length: 1. Maximum length: 64. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `0x4AAAAAAAAbCd1eFgHiJkLm`.
*   `name` (_string_) Human-readable widget name.  
    Minimum length: 1. Maximum length: 255. Example: `checkout-widget`.
*   `mode` (_TurnstileWidgetMode_)
*   `domains` (_array of string_) Domains associated with the widget.  
    Items: Minimum length: 1. Maximum length: 253. Example: `shop.example.com`.
    
    _Example_
    
    ```
    [
      "shop.example.com",
      "www.example.com"
    ]
    ```
    
*   `bot_fight_mode` (_boolean_) Whether bot fight mode is enabled.  
    Example: `false`.
*   `region` (_string_) Widget region.  
    Minimum length: 1. Maximum length: 50. Example: `world`.
*   `offlabel` (_boolean_) Whether the widget is off-label.  
    Example: `false`.
*   `clearance_level` (_string_) Clearance level for the widget.  
    Minimum length: 1. Maximum length: 50. Example: `interactive`.
*   `created_on` (_string (date-time)_) Timestamp when the widget was created.  
    Example: `2026-01-15T12:00:00Z`.
*   `modified_on` (_string (date-time)_) Timestamp when the widget was last modified.  
    Example: `2026-02-20T08:30:00Z`.
*   `secret` (_string_) The widget shared secret. Handle with care.  
    Minimum length: 1. Maximum length: 255. Example: `0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue`.

### TurnstileWidgetMode

The widget operating mode. Determines the challenge behavior.

Type: `string`.

Allowed values: `non-interactive`, `invisible`, `managed`. Example: `managed`.

### PageShieldScriptVersion

Version details for the JavaScript script.

*   `hash` (_string_) The computed hash of the analyzed script.  
    Pattern: ^.\*$. Example: `1243453456abc`.
*   `jsIntegrityScore` (_integer_) The integrity score of the JavaScript content.  
    Example: `1`.
*   `obfuscationScore` (_integer_) The obfuscation score of the JavaScript content.  
    Example: `2`.
*   `dataflowScore` (_integer_) The dataflow score of the JavaScript content.  
    Example: `1`.
*   `malwareScore` (_integer_) The malware score of the JavaScript content.  
    Example: `1`.
*   `cryptoMiningScore` (_integer_) The crypto mining score of the JavaScript content.  
    Example: `1`.
*   `mageCartScore` (_integer_) The Magecart score of the JavaScript content.  
    Example: `2`.
*   `fetchedAt` (_string (date-time)_) The timestamp of when the script was last fetched.  
    Example: `2023-01-01T00:00:00Z`.
*   `isMaliciousCode` (_boolean_, required) Indicates whether the script has been reported as malicious.  
    Example: `false`.

_Example_

```
{
  "hash": "1243453456abc",
  "jsIntegrityScore": 1,
  "obfuscationScore": 2,
  "dataflowScore": 1,
  "malwareScore": 1,
  "cryptoMiningScore": 1,
  "mageCartScore": 2,
  "fetchedAt": "2023-01-01T00:00:00Z",
  "isMaliciousCode": false
}
```

### DCVDelegationRecord

eCDN automatic renewal certificate DCV delegation records.

*   `dcvCname` (_string_) DNS CNAME for Domain Control Validation.  
    Pattern: ^.\*$. Example: `_acme-challenge.example.com`.
*   `dcvCnameValue` (_string_) DNS CNAME value for Domain Control Validation.  
    Pattern: ^.\*$. Example: `abc123def456ghi789.acme-validation.com`.

_Example_

```
{
  "dcvCname": "_acme-challenge.example.com",
  "dcvCnameValue": "abc123def456ghi789.acme-validation.com"
}
```

### MRTRuleset

An MRT ruleset. Defines a list of MRT rules that will route certain storefront requests to the managed runtime instance.

*   `id` (_string_, required) The ID of the ruleset.  
    Pattern: ^.\*$. Example: `12345678901234asdfasfasdf`.
*   `name` (_string_, required) The name of the ruleset.  
    Pattern: ^.\*$. Example: `MRT Rules`.
*   `lastUpdated` (_string (date-time)_, required) Date when the ruleset was last updated.  
    Example: `2022-01-01T05:20:00Z`.
*   `rules` (_array of MRTRules_, required) The rules defined by the ruleset.

_Example_

```
{
  "id": "12345678901234asdfasfasdf",
  "name": "MRT Rules",
  "lastUpdated": "2022-01-01T05:20:00Z",
  "rules": []
}
```

### MRTRules

A rule in an MRT ruleset.

*   `id` (_string_, required) The ID of the rule.  
    Pattern: ^.\*$. Example: `12345678901234asdfasfasdf`.
*   `expression` (_string_, required) The expression that determines the rule's routing behavior.  
    Pattern: ^.\*$. Example: `(http.host eq "dev-customer.salesforce.com" and not ( http.request.uri.path matches "^/path1/.*" or http.request.uri.path matches "^.*/path2/.*/products/.*"))`.
*   `description` (_string_) The description of the rule.  
    Pattern: ^.\*$. Example: `Phased rollout rule for dev-customer.salesforce.com`.
*   `lastUpdated` (_string (date-time)_, required) Date when the rule was last updated.  
    Example: `2022-01-01T05:20:00Z`.
*   `ref` (_string_, required) The ref of the rule.  
    Pattern: ^.\*$. Example: `12345678901234asdfasfasdf1234567`.
*   `enabled` (_boolean_, required) Whether or not the rule is enabled.  
    Example: `true`.
*   `mrtHostname` (_string_, required) Managed runtime hostname this rule targets.  
    Pattern: ^.\*$. Example: `customer-pwa-hybrid.mobify-storefront.com`.

_Example_

```
{
  "id": "12345678901234asdfasfasdf",
  "expression": "(http.host eq \"dev-customer.salesforce.com\" and not ( http.request.uri.path matches \"^/path1/.*\" or http.request.uri.path matches \"^.*/path2/.*/products/.*\"))",
  "description": "Phased rollout rule for dev-customer.salesforce.com",
  "lastUpdated": "2022-01-01T05:20:00Z",
  "ref": "12345678901234asdfasfasdf1234567",
  "enabled": true,
  "mrtHostname": "customer-pwa-hybrid.mobify-storefront.com"
}
```

<!-- document id=7b3776b457fd75161eecec1fad2bc19cecd5559832d02c72b47f9c597e2ea3ec url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-chat-interface.md -->

# Chat with Agentforce Commerce Vibes

Use the Agentforce Commerce Vibes chat interface to write prompts and get AI assistance for storefront development and administration tasks. Use Plan mode within the chat interface to plan and approve a complex task before carrying it out.

## Choose the AI Model

Commerce Vibes lets you choose which AI model handles your requests. The models you see depend on which AI provider your organization has configured. Click the model name in the bottom-left corner of the Chat interface (for example, Claude Opus or OpenAI GPT) to open the model selector. Available models appear grouped by provider. Select a model to start using it immediately.

## View Sample Prompts

The chat panel displays sample prompts that give you ideas of what you can do in Commerce Vibes and saves you time. When you open VS Code in a folder that doesn't contain a storefront project, a small set of generic prompts appear in a new chat tab. If the current folder contains a storefront project, a new chat panel shows prompts that are tailored to the storefront type—prompts for Storefront Next, SFRA, and PWA Kit.

![View sample prompts in the chat panel](https://developer.salesforce.com/docs/media/commerce-vibes/cv-sample-prompts.png '{"class": "image-xl"}')

## Use Plan Mode for Complex Tasks

Use Plan mode for tasks that span multiple layers, have ordering dependencies, or carry real risk if the sequence is incorrect. Plan Mode tells Agentforce Vibes to map out multi-step work as a structured plan before executing anything. The agent proposes a plan and invites you to approve it before it carries out the work.

**tip:** When you write prompts for Plan mode, make sure to include all the necessary details and instructions for the agent to figure out the entire plan of work to carry out.

To switch to Plan mode, click **Plan** in the bottom bar of the Chat interface, next to the model selector.

![Plan mode presents a plan to approve](https://developer.salesforce.com/docs/media/commerce-vibes/cv-plan.png '{"class": "image-xl"}')

These are some examples of prompts that require multi-step execution that are suitable for Plan mode.

- `Add a promotional banner to the home page with a hero image, headline text, call-to-action button that links to a category or product listing page, and configurable background color.`
- `Add image zoom functionality to the product detail page that opens a full-screen zoom modal when clicking on the product image, with zoom controls and thumbnail navigation.`
- `Add social media share buttons to the product detail page that let customers share the product on Facebook, Twitter, and Pinterest with the product image, name, and URL.`
- `Extend an existing SFRA controller from app_storefront_base: use server.extend to inherit the base routes, add custom middleware for caching or validation, and append new data to the view model with server.append.`
- `Create a product comparison extension for Storefront Next: set up the extension folder structure, add a compare checkbox to product tiles using UITarget, create a comparison page showing side-by-side product attributes, and register the extension.`

## See Also

- [Agentforce Vibes Developer Guide: Model Selection](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-model-selection.html)
- [Agentforce Vibes Developer Guide: Plan Mode](https://developer.salesforce.com/docs/platform/agentforcevibes/guide/afv-plan-mode.html)

<!-- document id=5863a9f1118654bd17f49d7b0d62746bff3574d9b6fdb55d957b9544af6ac0fa url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-checkout.md -->

# Checkout

### Overview

The Checkout page implements a four-step single-page checkout flow:

- Address
- Delivery Method
- Payment
- Review

Each checkout step advances only after the corresponding server-side API operation completes successfully. An order summary remains visible throughout the checkout flow to provide buyers with continuous visibility into pricing, quantities, shipping, and totals.

When saved buyer addresses are available, the checkout experience displays them as selectable options by default. If no saved addresses exist, the page falls back to a manual address entry form.

This flow demonstrates how a headless storefront can render checkout experiences, including address selection, delivery methods, payment processing, and order submission, using B2B Commerce Checkout APIs. Detailed flow diagrams for each checkout step are provided after this end-to-end flow.

![Checkout APIs Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-section-figure-image-18-1.png '{"class": "image-lg", "title": "Checkout APIs Flow"}')

### B2B Commerce APIs Used in the Flow

| Operation            | HTTP Method | Endpoint                                                                                                                                                                                                            |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get active checkout  | GET         | [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                               |
| Start checkout       | PUT         | [`/commerce/webstores/{webstoreId}/checkouts`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm)                       |
| List saved addresses | GET         | [`/commerce/webstores/{webstoreId}/accounts/current/addresses`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm)            |
| Save new address     | POST        | [`/commerce/webstores/{webstoreId}/accounts/current/addresses`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm)            |
| Set shipping address | PATCH       | [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                               |
| Pick delivery method | PATCH       | [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                               |
| Authorize PO payment | POST        | [`/commerce/webstores/{webstoreId}/checkouts/active/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm)             |
| Place order          | POST        | [`/commerce/webstores/{webstoreId}/checkouts/active/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm) |

### Buyer Journey

**Initialize Checkout**

1. Load the checkout experience.

2. Call the following endpoint to retrieve the active checkout:

   GET [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)

3. Handle a 404 Not Found response as a valid initialization path. A 404 response indicates that no active checkout exists for the current buyer session.

4. If no active checkout exists, create one by calling:

   PUT [`/commerce/webstores/{webstoreId}/checkouts`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm)

   Example request body:

   ```json
   {
     "cartId": "active",
     "deliveryAddressInput": {
       "shouldUseDefaultAddress": true
     }
   }
   ```

5. Set `shouldUseDefaultAddress=true` to instruct the platform to:

   - Apply the buyer’s default shipping address
   - Preselect an available delivery method
   - Calculate shipping and totals during checkout creation

   This reduces additional checkout update requests later in the flow.

6. Retrieve the buyer’s saved shipping addresses by calling:

   GET [`/commerce/webstores/{webstoreId}/accounts/current/addresses?addressType=Shipping`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm)

7. Retrieve cart items for the checkout summary panel by calling:

   GET [`/commerce/webstores/{webstoreId}/carts/current/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartItemCollection)

8. Use the responses to render:

   - Checkout summary
   - Shipping address selection
   - Delivery methods
   - Cart side panel
   - Order totals

**Select a Saved Shipping Address**

This flow demonstrates how a headless storefront can orchestrate address selection and shipping address management during checkout using B2B Commerce Checkout APIs.

![Checkout Address Selection Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-section-figure-image-19-2.png '{"class": "image-lg", "title": "Checkout Address Selection Flow"}')

1. Select a shipping address from the saved-address list.

2. Call the following endpoint to apply the address to the active checkout:

   PATCH [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)

   Example request body:

   ```json
   {
     "deliveryAddress": {
       "street": "1 Market St",
       "city": "San Francisco",
       "region": "CA",
       "postalCode": "94105",
       "country": "US"
     }
   }
   ```

3. Use the `deliveryAddress` field in the request body. The legacy `shippingAddress` field isn't supported by this endpoint.

4. Use the updated checkout response to refresh checkout totals and delivery information.

5. Advance the checkout flow to the delivery step.

**Add and Apply a New Shipping Address**

1. Enter a new shipping address in the checkout address form.

2. Save the address to the buyer account by calling:

   POST [`/commerce/webstores/{webstoreId}/accounts/current/addresses`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm)

3. Allow the platform to validate and normalize the address before applying it to the checkout.

4. After the address is saved successfully, apply the address to the active checkout by calling:

   PATCH [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)

   Example request body:

   ```json
   {
     "deliveryAddress": {
       "street": "1 Market St",
       "city": "San Francisco",
       "region": "CA",
       "postalCode": "94105",
       "country": "US"
     }
   }
   ```

5. Save the address before applying it to the checkout to reduce downstream validation failures during checkout updates.

6. Use the updated checkout response to refresh delivery methods and totals.

7. Advance the checkout flow to the delivery step.

**Select a Delivery Method**

This flow demonstrates how a headless storefront can orchestrate delivery method selection during checkout using B2B Commerce Checkout APIs.

![Checkout Delivery Method Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-checkout-b2b-commerce-apis-used-in-the-flow-20-1.png '{"class": "image-lg", "title": "Checkout Delivery Method Flow"}')

1. Select a delivery method from the list of available shipping options.

2. Use the delivery methods returned in the checkout response. No additional request is required to retrieve delivery methods.

3. Call the following endpoint to apply the selected delivery method:

   PATCH [`/commerce/webstores/{webstoreId}/checkouts/active`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)

   Example request body:

   ```json
   {
     "deliveryMethodId": "<delivery-method-id>"
   }
   ```

4. Use the updated `CheckoutState` response to refresh shipping totals and order summary information.

5. Advance the checkout flow to the payment step.

**Authorize a Purchase Order Payment**

1. Enter a purchase order number and billing address information in the payment form.

2. Call the following endpoint to authorize the payment:

   POST [`/commerce/webstores/{webstoreId}/checkouts/active/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm)

   Example request body:

   ```json
   {
     "paymentToken": "<po-number>",
     "requestType": "SimplePurchaseOrder",
     "billingAddress": {
       "name": "Jane Doe",
       "companyName": "Acme Inc.",
       "street": "1 Market St",
       "city": "San Francisco",
       "region": "CA",
       "postalCode": "94105",
       "country": "US"
     }
   }
   ```

3. Use a single concatenated name value for the billing address. Separate first-name and last-name fields aren't supported by this endpoint.

4. Use the payment response to update the checkout payment state.

5. Advance the checkout flow to the review step.

**Place the Order**

This flow demonstrates how a headless storefront can orchestrate payment processing and order submission during checkout using B2B Commerce Checkout APIs.

![Checkout Payment and Place Order Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-section-figure-image-19-1.png '{"class": "image-lg", "title": "Checkout Payment and Place Order Flow"}')

1. Select Place Order to submit the checkout.

2. Finalize totals, tax, and checkout calculations by calling:

   POST [`/commerce/webstores/{webstoreId}/checkouts/active/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm)

   Example request body:

   ```json
   {
     "actions": [{ "action": "prepare" }]
   }
   ```

3. After the prepare action succeeds, submit the order by calling the same endpoint again:

   POST [`/commerce/webstores/{webstoreId}/checkouts/active/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm)

   Example request body:

   ```json
   {
     "actions": [{ "action": "submit", "parameters": {} }]
   }
   ```

4. Retrieve the following values from the successful submit response:

   - `orderReferenceNumber`
   - `orderSummaryId`
   - `salesOrderId`

5. Refresh the cart summary after order submission because the active cart is now empty.

6. Use the order confirmation page to display order details and confirmation information.

### Extend the Flow

- Replace the purchase order (PO) payment form with a tokenized card payment integration such as Stripe or another payment gateway. The request body sent to POST [`/commerce/webstores/{webstoreId}/checkouts/active/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm) supports the `paymentToken` field for tokenized payment flows. Integrate the payment gateway of your choice to generate the token, then update the `requestType` and payment payload accordingly.
- Add coupon and promotion support during checkout using POST [`/commerce/webstores/{webstoreId}/checkouts/active/coupons`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupons.htm) This enables buyers to apply promotional discounts directly within the checkout experience.
- Replace the four-step checkout wizard with a fully expanded single-page or accordion-based checkout layout by reading the `currentStep` value returned from the active checkout response and rendering all checkout sections inline.

## See Also

- [_B2B Commerce Developer Guide_: Cart and Checkout Features](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-cart-checkout.html)
- [_B2B Commerce Developer Guide_: Get Started with B2B Commerce Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-get-started.html)
- [_B2B Commerce Developer Guide_: Setup Payment Processing](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-payment-b2b-setup.html)
- [_B2B Commerce Developer Guide_: B2B Commerce Checkout APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-checkout-apis.html)
- [_B2B Commerce Developer Guide_: B2B Commerce Checkout APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-checkout-apis.html)

<!-- document id=1b7f8da04dda071829738f23f64f2107bb245b0a448b6ba3e2db091d4c0d0710 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/checkout-fulfillment.md -->

# Checkout and Fulfillment

Validate carts, configure delivery and pickup options, apply tax and promotions, and support special product types at checkout.

## In this section

- [Cart Validation using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/cart-validation-via-spi.html)
- [Enable Activation Codes With the SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/activation-codes-via-spi.html)
- [Retrieve Delivery Groups via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-groups-via-spi.html)
- [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
- [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html)
- [Single-Use Promotion Code](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/single-use-promotion-code.html)

<!-- document id=876f46246fe9ae292c64ec7cf2a293a3384cfaa4d7f17bd26bf2effb2c486a9c url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-component-communication.md -->

# Checkout Component Communication

Checkout components communicate with each other during checkout processing. Understanding how they communicate helps you develop a custom checkout component for a B2B or B2C store created with an LWR template.

## Checkout Layout Options

There are two checkout layout options: one-page and accordion. The layout option that you choose affects how the data provider and sections interact with your custom child components.

In the one-page layout, the shopper can generally complete checkout sections in any order. All checkout components are kept in edit mode, so the shopper can edit each section. In Experience Builder, you can reorder the sections and components.

In the accordion layout, the shopper completes the sections in a prescribed order from top to bottom: Shipping Address, Shipping Method, and Payment. The default minimum set of sections and components must be kept in this order. Each section in this layout has a Proceed (or Next) button.

In both layouts, an authenticated customer must provide or confirm their shipping address, shipping method, payment, and billing information. A guest customer must also enter an email address and a phone number as part of the shipping address. To place the order, the customer clicks **Place Order**.

## One-Page Layout Processing Flow

In the one-page layout, shoppers can edit sections in any order. Editing autosaves on the shipping component, which triggers the shipping methods to load. The checkout place order operation triggered by the Place Order button succeeds when all required sections and forms are completed and they report as valid. The address and shipping methods autoload for a returned authenticated shopper, and only payment information must be entered.

**Form Updates and Autosave**

One-page layout sections are always expanded and editable. After a customer enters valid information into a component’s form fields, the component typically calls two methods, `dispatchUpdateAsync()` and `dispatchCommit()`, to notify the checkout data provider or parent section containers that they’re ready to be saved.

The `dispatchUpdateAsync()` method notifies the checkout page data provider to update the internal form store with the supplied changes. To avoid updating the internal form store with invalid data, the component typically calls the `checkValidity()` method first. The `dispatchCommit()` method informs the section to attempt to save the new internal form store changes. The component `stageAction()` method handles the `CHECKOUT_VALIDITY_UPDATE` and REPORT_VALIDITY_SAVE actions. When the component `checkValidity()` and `reportValidity()` methods return true, the subsequent `dispatchCommit()` calls are made through the intermediary one-page layout container component. Finally, the checkout data provider handles the commit and saves the checkout data.

This diagram shows the sequence initiated when a customer interacts with a component form.

![Diagram of checkout validity workflow](https://developer.salesforce.com/media/d2c-commerce/comm_checkout_onepagelayout_validity.png)

**One-Page Place Order Sequence**

In one-page checkout, after the user clicks the place order button, the button calls the helper `dispatchFinalizeAsync` to start the validation cycle. The checkout page data provider executes `reportValidity` on each child component to determine if all forms are valid and ready. This validity check is complete when components implement the `stageAction()` method with `CHECK_VALIDITY_UPDATE` and `REPORT_VALIDITY_SAVE` handlers. See [Sample Custom Checkout Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-sample-checkout-component.md).

If any form fields are invalid, errors are shown and the place order operation is halted. The customer can then provide missing information or correct mistakes.

If all initial `stageAction(...)` calls report valid and return true, the `ACTION_CHECKOUT_FINALIZE` operation continues with `stageAction(PAYMENT)` and calls `completePayment()` on the Payment component.

If `completePayment()` succeeds and returns true from the `stageAction(PAYMENT)` call, the checkout data provider continues to process calls `stageAction(BEFORE_PLACE_ORDER)` and `stageAction(PLACE_ORDER)`. When `stageAction(PLACE_ORDER)` is called, the component uses `dispatchPlaceOrderAsync` to make the server API call.

Finally, the Place Order Button component handles the `PLACE_ORDER` option and dispatches the `ACTION_CHEKOUT_PLACE_ORDER` action. This component also navigates to the order confirmation summary. Custom components can also implement the `stageAction(checkoutStage:CheckoutStage)` method and handle `BEFORE_PAYMENT` and `BEFORE_PLACE_ORDER` for any custom processing needed at those stages.

This diagram shows the sequence initiated when the customer clicks Place Order.

![Diagram of the checkout layout one-page place order flow](https://developer.salesforce.com/media/d2c-commerce/comm_checkout_onepagelayout_placeorder.png)

## Accordion Layout Processing Flow

The shopper clicks **Proceed** on each section to go to the next section.

By default, the accordion layout shows these sections in order: Guest Information (for unauthenticated shoppers), Shipping Address, Shipping Methods, and Payment and Billing. You can add custom sections and components, but you must keep the default sections for checkout to work.

## Error Handling

Error handling behaves similarly for both layout options. Whenever an error is caught, a `dispatchUpdateErrorAsync()` call can be made. For example, in the Place Order diagram, a `dispatchUpdateErrorAsync()` call is made on the Payment component `completePayment()` method. The checkout page data provider then updates the Checkout Notification component to display the error. The checkout process is halted until the shopper corrects any issues and clicks **Place Order** or **Proceed** again. See FormNotification details in [Checkout Interfaces](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-checkoutsavable.md).

To clear previous error messages, use a `dispatchUpdateErrorAsync()` call with only the `groupId` parameter specified.

<!-- document id=d1b9b2b7b8d7ebcc137e9afa5e14472801808306bb13aa7bffc0d811b45c0978 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-component-hierarchy.md -->

# Checkout Component Hierarchy

The checkout page for a B2B or B2C store created with an LWR template contains a recommended hierarchy of nested checkout components. These components rely on a checkout data provider that loads and saves all of the necessary data for checkout.

The checkout component hierarchy consists of three levels. At the top of the component hierarchy is a layout component. The layout component contains multiple section components, and it organizes the customer experience into a one-page workflow or an accordion workflow. The Layout: One Page component shows all sections at once, and the customer can complete them in any order. The Layout: Accordion layout expands one section at a time, and the customer must complete them in a specific order.

![Three Levels of Checkout Component Hierarchy](https://developer.salesforce.com/media/d2c-commerce/comm_custom_component_checkout_hierarchy.png)

Section components group related child components. For example, a Shipping section can contain a Shipping Address component and a Shipping Instructions component. You can add, remove, reorder, or rename section components as needed.

Child components show and accept the customer details that are required to complete checkout. These components apply the mixin `extend useCheckoutComponent(LightningElement)` and implement certain checkout methods, depending on the desired behavior, to be managed by the page, layout, and section components.

Some components on the Checkout Page, such as the Place Order Button component and Checkout Notification component, are placed directly on the page and aren’t part of this hierarchy.

## Default Checkout Components

When you create a new store in Experience Builder, we provide a preconfigured Checkout Page by default that follows this setup.

![Default checkout page with a one-page layout at the top level. On the second level is a shipping section component that contains a contact information component, a shipping address component, and a shipping instructions component. Next is a delivery option section that contains a shipping methods component. Last is a payment section component that contains a payment information component with a nested billing component.](https://developer.salesforce.com/media/d2c-commerce/comm_checkout_components_default.png)

You can add custom components anywhere in the workflow and expect the same or different behavior as the default components, depending on the implementation.

<!-- document id=644f43d5a8389ae014b5f2655eaf9962a29024f11e92d85d3f570f613d9a3499 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-api-container.md -->

# Checkout Integration

Commerce checkout provides integration points to third-party services.

**note:** In the Winter ‘24 release, we introduced Commerce extensions for pricing, inventory, shipping, taxes, and other services. While the checkout integrations framework is still supported, we recommend extensions over integrations because they offer more targeted customizations for your B2B or B2C store. Plus, they’re available for more Commerce domains. See [Get Started With Salesforce Commerce Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extensions.html).

Calls to the API services are triggered when shoppers click Checkout or revisit a checkout session from their browser. Store components that embed the Checkout APIs are implemented in Lightning Web Runtime.

![Diagram of checkout apis.](https://developer.salesforce.com/media/d2c-commerce/checkout_overview.png)

<!-- document id=523300c7c72b354130317c22ac7b1a0fd2e6ed486185167992664c22a4d39fd2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-authentication.md -->

# Checkout Session Authentication

Checkout Session APIs are authorized with the Shopper Login and API Access Service (SLAS). This page covers the SLAS private client and scope you need to call those APIs.

The **business profile** at `/.well-known/ucp` is unauthenticated. Configure and publish that profile in [Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md).

- [Calling Checkout Session APIs](#calling-checkout-session-apis) — required scope and a dedicated SLAS private client
- [Create a SLAS Private Client](#create-a-slas-private-client)
- [Request an Access Token](#request-an-access-token)

## Calling Checkout Session APIs

`POST`, `GET`, and `PUT` on `/checkout-sessions`, plus `complete` and `cancel`, require a SLAS access token.

The required shopper scope is:

```
dev.ucp.shopping.checkout:manage
```

A token without that scope can't create, update, complete, or cancel a checkout session. Storefront SLAS clients typically don't include it, so create a **new SLAS private client** for UCP rather than reusing a public storefront client.

## Create a SLAS Private Client

Create the client in the SLAS Admin UI. Sign in with Account Manager credentials. You need the **SLAS Organization Administrator** role and the correct instance filters. The full role setup and client-creation steps are in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).

To access the SLAS Admin UI, replace `{short-code}` with the short code for your B2C Commerce instances:

```
https://{{short-code}}.api.commercecloud.salesforce.com/shopper/auth-admin/v1/ui/
```

Then:

1. Click **Clients**, and then click **Add Client**.
2. Select the tenant for the B2C Commerce instance.
3. Select **BFF or Web App** in **Which App Type will be used?** so SLAS creates a private client and generates a client secret.
4. In **Enter the shopper scopes**, include `dev.ucp.shopping.checkout:manage` (scopes are separated by a space if you add more than one).
5. Associate the client with the site (channel) you are enabling for UCP.
6. Copy the client ID and the generated secret. The secret is displayed only once.

**important:** Don't add shopper scopes such as `dev.ucp.shopping.checkout:manage` to an Account Manager API client. Shopper API scopes belong on SLAS clients. See [SLAS Clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#slas-clients).

Alternatively, create the client with the SLAS Admin API or the B2C Commerce CLI (`b2c slas client create`). Those options are covered in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).

## Request an Access Token

For guest checkout—the usual way to call Checkout Session APIs from Postman or a similar tool—use the private-client **client credentials** grant. The numbered guest-user flow is in [Private SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html):

- Send an `Authorization` header with a Base64-encoded `client_id:client_secret` string.
- Set `grant_type=client_credentials`.
- Include `channel_id` set to your site ID. Guest `client_credentials` requests without `channel_id` fail.
- Request the scope `dev.ucp.shopping.checkout:manage`.

Send the returned access token as `Authorization: Bearer` on Checkout Session requests.

<!-- document id=d7ec180aa197adf5734f89a96311ae8d80e7a859ac4a58ee6341e0f797ba60f9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/customization-decision-guide.md -->

# Choose a Customization Approach

The Agentforce Commerce Client gives you three levels of customization. Start with the lightest one that meets your need: configuration is the cheapest to maintain, custom CSS is next, and component overrides are the most powerful but carry the most responsibility.

## Decision guide

Work down this list and stop at the first level that solves your problem.

1. **Change behavior, text, colors, or layout mode?** Use [configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md) and [theme properties](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md). Setting `theme`, `headerConfig`, `componentConfig`, `searchConfig`, and related props covers most brand and behavior needs with no code.

2. **Restyle existing elements beyond what theme properties allow?** Use [custom CSS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md) targeting the `cim-widget-*` classes, with `globalClassName` as a specificity hook. This restyles what the widget already renders without changing its structure.

3. **Replace what the widget renders for products or agent actions with your own markup?** Use the [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md). Use overrides to supply custom elements for product tiles, carousels, product detail cards, comparison tables, progress steps, and custom agent-action blocks. This is a messaging-mode capability.

## What each level can and can't do

| Need | Configuration | Custom CSS | Component Overrides |
| --- | --- | --- | --- |
| Brand colors, fonts, borders | Yes | Yes | Yes |
| Header logo and title | Yes | Yes | Yes |
| Presentation mode (chat, dialog, modal) | Yes | Partial | No |
| Restyle an existing element | No | Yes | Yes |
| Restructure product cards or carousels | No | No | Yes |
| Render a custom agent-action block (orders, pickers, forms) | No | No | Yes |

## What overrides do not cover

Component overrides replace product and agent-action rendering, not the widget's chrome. The header, search bar, and follow-up suggestions are intentionally not overridable. Style those with theme properties and custom CSS instead. See [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md) for the exact list of overridable slots.

## Related resources

- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md)
- [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md)

<!-- document id=2f4a613eb93431441ef515af303d5b4e5ee9ab5ab7506cc0028cb01c5bcd66fc url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/which-product.md -->

# Choose Your B2C Commerce Storefront Type

Review the available B2C Commerce storefront types and their key features. Choose the storefront type that best fits your use case.

| If you want to:                                                                                                                                                                                                                                                                                                                                                | Then use this option:                                                                                                                                          | With this development environment:                                                                                                    | With these key APIs for customization:\*                                                                                                                                                          | With these key tools to speed up development:                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| - Set up storefronts using an automated workflow in Business Manager. Integrate your storefront with GitHub Actions.<br>- Build high-performing storefronts with server-side rendering for initial page loads using modern web technologies.<br>- Provide AI-assisted shopping with Shopper Agent.<br>- Use Storybook to build, test, and document components. | **Recommended option:** [Storefront Next](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-get-started.html), which includes Managed Runtime | React Router 7 framework mode, React 19 components, Tailwind CSS for styling, shadcn/ui component library, and the Vite build system. | Use the SCAPI client that Storefront Next provides to make [B2C Commerce API (SCAPI)](https://developer.salesforce.com/docs/commerce/commerce-api/guide) calls from your storefront.              | **Optional**: [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md)                                                  |
| - Benefit from existing skills and code from a previous Storefront Reference Architecture (SFRA) implementation<br>- Build and launch campaigns and promotions with minimal developer involvement<br>- Access a trusted ecosystem of connectors/plug-and-play apps                                                                                             | [SFRA](https://developer.salesforce.com/docs/commerce/sfra/guide)                                                                                              | Server-side HTML and JavaScript                                                                                                       | [B2C Commerce Developer Resources](https://salesforcecommercecloud.github.io/b2c-dev-doc/) (Script API)                                                                                           | **Optional**: [B2C Commerce CLI](https://github.com/SalesforceCommerceCloud/sfcc-ci)                                                                             |
| Gradually migrate your site from SFRA to Storefront Next                                                                                                                                                                                                                                                                                                       | [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-hybrid.html)                               | Combination of: server-side HTML and JavaScript, React components and Tailwind CSS                                                    | [B2C Commerce API](https://developer.salesforce.com/docs/commerce/commerce-api/guide) and [B2C Commerce Developer Resources](https://salesforcecommercecloud.github.io/b2c-dev-doc/) (Script API) | **Optional**: [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md)                                                  |
| Use your own custom implementation to suit your unique business needs                                                                                                                                                                                                                                                                                          | Build your own site                                                                                                                                            | Your chosen development environment                                                                                                   | [B2C Commerce API](https://developer.salesforce.com/docs/commerce/commerce-api/guide)                                                                                                             | **Optional:** [Commerce SDK](https://github.com/SalesforceCommerceCloud/commerce-sdk) and [B2C Commerce CLI](https://github.com/SalesforceCommerceCloud/sfcc-ci) |

To build advanced features, use the B2C Commerce API ([SCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/scapi-get-started.html)) and [B2C Commerce Einstein API](https://developer.salesforce.com/docs/commerce/einstein-api/guide).

### See Also

- [Why Use SCAPI Instead of OCAPI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/why-use-scapi.html)
- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=d55a594a0f6af538e359f87af0cd49fa88db4832483d3d74df560d58788fa815 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-circuit-breaker.md -->

# Circuit Breaker

To ensure the stability of the platform by protecting it from excessive load, Custom APIs contain a **Circuit Breaker** mechanism. This functionality blocks API requests when a specific error threshold is exceeded.

## How it works

A circuit breaker is configured for every registered endpoint and each incoming request to that endpoint passes through it. How the circuit breaker acts depends on its internal state, which is defined by the recent script execution on the corresponding endpoint. The circuit breaker can be in one of three states: `closed`, `open`, or `half-open`.

The default state of a circuit breaker is `closed`, which means that the request is allowed to pass through to the implementation script.

If the execution of the implementation script results in an error, this error is tracked. Once the error rate exceeds the threshold of **50%**, this process is triggered:

1. The internal state changes to `open`. This change is logged.
2. For **60** seconds, any calls to the failing endpoint return an HTTP status code **503 - Service Unavailable** with the error type `custom-api-circuit-breaker-error`.
3. After **60** seconds, the internal state changes to `half-open`. This change is logged.
4. The circuit breaker tracks the next **10** calls to the failing endpoint. If more than **5** of them fail, return to step 1.
5. The internal state changes to `closed` and the endpoint is unblocked. The circuit breaker continues tracking requests to this endpoint. This change is logged.

**note:** In the `closed` state, the circuit breaker will evaluate the previous **100** requests in order to calculate the error rate. This means that at least **50** of them must have failed when the circuit breaker opens.

## Investigate Script Errors

If Custom API requests return errors of the type `custom-api-internal-server-error` or `custom-api-circuit-breaker-error`, use Log Center to investigate the cause.

1. In Business Manager, navigate to **Administration** > **Site Development** > **Development Setup**.
2. In the _Log Files_ section, click _Log Center_.
3. Select the Day of Year.
4. In the **LCQL** field, enter `CustomApiCircuitBreaker`.
5. In the query hits, look for a `CustomApiInvocationException` entry and click its **Stack Trace UUID** link.
6. In the stack trace, find the `Caused by` section. It can contain information about the cause of the failures. Some possible causes include:
- The script contains a remote call that never returns a response, causing the script execution to time out. In this case, try making an asynchronous call instead.
- The script contains errors. Fix the code and consider adding error handling measures.

<!-- document id=b432d44d0db6c0e62739b53a0f4e3ccfe65d2f1e80665ca7bfb01aac7629dd2a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.AbstractItem.md -->

<!-- prettier-ignore-start -->
# Class AbstractItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md)

An item which references, or in other words is based upon, an [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md). Provides methods to access the
OrderItem, the order [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md) which has been extended, and the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md). In addition it defines
methods to access item level prices and the item id. Supports custom-properties.



## All Known Subclasses
[AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md), [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md), [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md), [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md), [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
## Property Summary

| Property | Description |
| --- | --- |
| [grossPrice](#grossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Gross price of item. |
| [itemID](#itemid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The item-id used for referencing between items |
| [lineItem](#lineitem): [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md) `(read-only)` | Returns the Order Product- or Shipping- LineItem associated with this item. |
| [netPrice](#netprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Net price of item. |
| [orderItem](#orderitem): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)` | Returns the order item extensions related to this item. |
| [orderItemID](#orderitemid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The order-item-id used for referencing the [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) |
| [tax](#tax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Total tax for item. |
| [taxBasis](#taxbasis): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Price of entire item on which tax calculation is based. |
| [taxItems](#taxitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Tax items representing a tax breakdown |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice)() | Gross price of item. |
| [getItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getitemid)() | The item-id used for referencing between items |
| [getLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getlineitem)() | Returns the Order Product- or Shipping- LineItem associated with this item. |
| [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice)() | Net price of item. |
| [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitem)() | Returns the order item extensions related to this item. |
| [getOrderItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitemid)() | The order-item-id used for referencing the [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) |
| [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax)() | Total tax for item. |
| [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis)() | Price of entire item on which tax calculation is based. |
| [getTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxitems)() | Tax items representing a tax breakdown |

### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### grossPrice
- grossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Gross price of item.


---

### itemID
- itemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The item-id used for referencing between items


---

### lineItem
- lineItem: [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md) `(read-only)`
  - : Returns the Order Product- or Shipping- LineItem associated with this item. Should never return null.


---

### netPrice
- netPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Net price of item.


---

### orderItem
- orderItem: [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)`
  - : Returns the order item extensions related to this item. Should never return null.


---

### orderItemID
- orderItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The order-item-id used for referencing the [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)


---

### tax
- tax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Total tax for item.


---

### taxBasis
- taxBasis: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Price of entire item on which tax calculation is based. Same as [getNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice)
      or [getGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice) depending on whether the order is based on net or gross prices.



---

### taxItems
- taxItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Tax items representing a tax breakdown

    **See Also:**
    - [TaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md)


---

## Method Details

### getGrossPrice()
- getGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Gross price of item.

    **Returns:**
    - Gross price of item.


---

### getItemID()
- getItemID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The item-id used for referencing between items

    **Returns:**
    - the item-id used for referencing between items


---

### getLineItem()
- getLineItem(): [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
  - : Returns the Order Product- or Shipping- LineItem associated with this item. Should never return null.

    **Returns:**
    - the Order Product- or Shipping- LineItem associated with this item


---

### getNetPrice()
- getNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Net price of item.

    **Returns:**
    - Net price of item.


---

### getOrderItem()
- getOrderItem(): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)
  - : Returns the order item extensions related to this item. Should never return null.

    **Returns:**
    - the order item extensions related to this item


---

### getOrderItemID()
- getOrderItemID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The order-item-id used for referencing the [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)

    **Returns:**
    - the order-item-id used for referencing the OrderItem


---

### getTax()
- getTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Total tax for item.

    **Returns:**
    - Total tax for item.


---

### getTaxBasis()
- getTaxBasis(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Price of entire item on which tax calculation is based. Same as [getNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice)
      or [getGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice) depending on whether the order is based on net or gross prices.


    **Returns:**
    - Price of entire item on which tax calculation is based


---

### getTaxItems()
- getTaxItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Tax items representing a tax breakdown

    **Returns:**
    - tax items representing a tax breakdown

    **See Also:**
    - [TaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md)


---

<!-- prettier-ignore-end -->

<!-- document id=b1c4e0f7d806f00b88015634fc9008da2f7e24b7ffbe49f3690fe9ead19932a8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.AbstractItemCtnr.md -->

<!-- prettier-ignore-start -->
# Class AbstractItemCtnr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md)

Basis for item-based objects stemming from a single [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), with these common
properties (Invoice is used as an example):


- The object has been created from an Order accessible using [getOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder)
- Contains a collection of [items](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems), each item related to exactly one [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)which in turn represents  an extension to one of the order [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)or one [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md).  Example: an [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)has [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s
- The items hold various prices which are summed, resulting in a  [product-subtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getproductsubtotal), a  [service-subtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getservicesubtotal)and a [grand-total](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getgrandtotal),  each represented by a [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md).
- The object is customizable using custom properties



## All Known Subclasses
[Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md), [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md), [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)
## Property Summary

| Property | Description |
| --- | --- |
| [createdBy](#createdby): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Created by this user. |
| [creationDate](#creationdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | The time of creation. |
| [grandTotal](#grandtotal): [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md) `(read-only)` | Returns the sum-item representing the grandtotal for all items. |
| [items](#items): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the unsorted collection of items |
| [lastModified](#lastmodified): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | The last modification time. |
| [modifiedBy](#modifiedby): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Last modified by this user. |
| [order](#order): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)` | Returns the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) this object was created for. |
| [productSubtotal](#productsubtotal): [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md) `(read-only)` | Returns the sum-item representing the subtotal for product items. |
| [serviceSubtotal](#servicesubtotal): [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md) `(read-only)` | Returns the sum-item representing the subtotal for service items such as  shipping. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreatedby)() | Created by this user. |
| [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreationdate)() | The time of creation. |
| [getGrandTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getgrandtotal)() | Returns the sum-item representing the grandtotal for all items. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems)() | Returns the unsorted collection of items |
| [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getlastmodified)() | The last modification time. |
| [getModifiedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getmodifiedby)() | Last modified by this user. |
| [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder)() | Returns the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) this object was created for. |
| [getProductSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getproductsubtotal)() | Returns the sum-item representing the subtotal for product items. |
| [getServiceSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getservicesubtotal)() | Returns the sum-item representing the subtotal for service items such as  shipping. |

### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### createdBy
- createdBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Created by this user.


---

### creationDate
- creationDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : The time of creation.


---

### grandTotal
- grandTotal: [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md) `(read-only)`
  - : Returns the sum-item representing the grandtotal for all items.


---

### items
- items: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the unsorted collection of items


---

### lastModified
- lastModified: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : The last modification time.


---

### modifiedBy
- modifiedBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Last modified by this user.


---

### order
- order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)`
  - : Returns the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) this object was created for.


---

### productSubtotal
- productSubtotal: [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md) `(read-only)`
  - : Returns the sum-item representing the subtotal for product items.


---

### serviceSubtotal
- serviceSubtotal: [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md) `(read-only)`
  - : Returns the sum-item representing the subtotal for service items such as
      shipping.



---

## Method Details

### getCreatedBy()
- getCreatedBy(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Created by this user.

    **Returns:**
    - Created by this user


---

### getCreationDate()
- getCreationDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : The time of creation.

    **Returns:**
    - time of creation.


---

### getGrandTotal()
- getGrandTotal(): [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md)
  - : Returns the sum-item representing the grandtotal for all items.

    **Returns:**
    - sum-item for all items


---

### getItems()
- getItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the unsorted collection of items

    **Returns:**
    - the unsorted collection of items


---

### getLastModified()
- getLastModified(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : The last modification time.

    **Returns:**
    - last modification time..


---

### getModifiedBy()
- getModifiedBy(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Last modified by this user.

    **Returns:**
    - Last modified by this user


---

### getOrder()
- getOrder(): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Returns the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) this object was created for.

    **Returns:**
    - the Order this object was created for.


---

### getProductSubtotal()
- getProductSubtotal(): [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md)
  - : Returns the sum-item representing the subtotal for product items.

    **Returns:**
    - sum-item for product items


---

### getServiceSubtotal()
- getServiceSubtotal(): [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md)
  - : Returns the sum-item representing the subtotal for service items such as
      shipping.


    **Returns:**
    - sum-item for service items such as shipping


---

<!-- prettier-ignore-end -->

<!-- document id=40b04272a49a6b544ca42b093d09ee9c656af94b4e49eac99dcc1845c7b3d3eb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.ABTest.md -->

<!-- prettier-ignore-start -->
# Class ABTest

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.campaign.ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md)

Object representing an AB-test in Commerce Cloud Digital.


AB-tests provide the merchant the ability to compare one set of storefront
"experiences" - promotions, sorting rules, and slot configurations in
particular - against another set. The merchant configures different AB-test
segments which define the sets of experiences that the merchant wishes to
test. AB-tests run for a configured period of time, and customers are
randomly assigned by the platform to the test segments according to
allocation percentages defined by the merchant.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the test ID for this AB-test. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md#getid)() | Get the test ID for this AB-test. |

### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the test ID for this AB-test.


---

## Method Details

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the test ID for this AB-test.

    **Returns:**
    - the test ID for this AB-test.


---

<!-- prettier-ignore-end -->

<!-- document id=f30ef12395e97328c9cb299af51c03bbc8fee99e5f16424b703570e00e76d450 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.ABTestMgr.md -->

<!-- prettier-ignore-start -->
# Class ABTestMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.ABTestMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestMgr.md)

Manager class used to access AB-test information in the storefront.


## Property Summary

| Property | Description |
| --- | --- |
| [assignedTestSegments](#assignedtestsegments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Return the AB-test segments to which the current customer is assigned. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getAssignedTestSegments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestMgr.md#getassignedtestsegments)() | Return the AB-test segments to which the current customer is assigned. |
| static [isParticipant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestMgr.md#isparticipantstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Test whether the current customer is a member of the specified AB-test  segment. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### assignedTestSegments
- assignedTestSegments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Return the AB-test segments to which the current customer is assigned.
      AB-test segments deleted in the meantime will not be returned.



---

## Method Details

### getAssignedTestSegments()
- static getAssignedTestSegments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Return the AB-test segments to which the current customer is assigned.
      AB-test segments deleted in the meantime will not be returned.


    **Returns:**
    - unordered collection of ABTestSegment instances representing the
              AB-test segments to which the current customer is assigned.



---

### isParticipant(String, String)
- static isParticipant(testID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), segmentID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Test whether the current customer is a member of the specified AB-test
      segment. This method can be used to customize the storefront experience
      in ways that are not supported using Business Manager configuration
      alone.


    **Parameters:**
    - testID - The ID of the AB-test, must not be null.
    - segmentID - The ID of the segment within the AB-test, must not be             null.

    **Returns:**
    - true if the current customer is a member of the specified AB-test
              segment, false otherwise.



---

<!-- prettier-ignore-end -->

<!-- document id=2ca08e82e31855eb6373da3c9d8df1036e36c42e219596038f286a99f5f79703 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.ABTestSegment.md -->

<!-- prettier-ignore-start -->
# Class ABTestSegment

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.campaign.ABTestSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md)

Object representing an AB-test segment in the Commerce Cloud Digital.


Each AB-test defines 1 or more segments to which customers are randomly
assigned by the platform when they qualify for the AB-test. Customers are
assigned to segments according to allocation percentages controlled by the
merchant. Each AB-test segment defines a set of "experiences" that the
merchant is testing and which which apply only to the customers in that
segment.  There is always one "control" segment which contains only the
default set of experiences for that site.



## Property Summary

| Property | Description |
| --- | --- |
| [ABTest](#abtest): [ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md) `(read-only)` | Get the AB-test to which this segment belongs. |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the ID of the AB-test segment. |
| [controlSegment](#controlsegment): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this is the "control segment" for the AB-test, meaning  the segment that has no experiences associated with it. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md#getabtest)() | Get the AB-test to which this segment belongs. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md#getid)() | Get the ID of the AB-test segment. |
| [isControlSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md#iscontrolsegment)() | Returns true if this is the "control segment" for the AB-test, meaning  the segment that has no experiences associated with it. |

### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ABTest
- ABTest: [ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md) `(read-only)`
  - : Get the AB-test to which this segment belongs.


---

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the ID of the AB-test segment.


---

### controlSegment
- controlSegment: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this is the "control segment" for the AB-test, meaning
      the segment that has no experiences associated with it.



---

## Method Details

### getABTest()
- getABTest(): [ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md)
  - : Get the AB-test to which this segment belongs.

    **Returns:**
    - the AB-test to which this segment belongs.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the ID of the AB-test segment.

    **Returns:**
    - the ID of the AB-test segment.


---

### isControlSegment()
- isControlSegment(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this is the "control segment" for the AB-test, meaning
      the segment that has no experiences associated with it.


    **Returns:**
    - true if this segment is the "control segment" for the AB-test, or
              false otherwise.



---

<!-- prettier-ignore-end -->

<!-- document id=32c29b99d997419815482ee1eb002a3711528b48c97afd6c1538aaaf2d37c04d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.ActiveData.md -->

<!-- prettier-ignore-start -->
# Class ActiveData

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.object.ActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md)

Represents the active data for an object in Commerce Cloud Digital.


## All Known Subclasses
[CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md), [ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md)
## Property Summary

| Property | Description |
| --- | --- |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes for this object. |
| [empty](#empty): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Return true if the ActiveData doesn't exist for the object |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md#getcustom)() | Returns the custom attributes for this object. |
| [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md#isempty)() | Return true if the ActiveData doesn't exist for the object |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes for this object. The returned object can
      only be used for retrieving attribute values, not storing them. See
      [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) for a detailed example of the syntax for
      working with custom attributes.



---

### empty
- empty: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Return true if the ActiveData doesn't exist for the object


---

## Method Details

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes for this object. The returned object can
      only be used for retrieving attribute values, not storing them. See
      [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) for a detailed example of the syntax for
      working with custom attributes.


    **Returns:**
    - the custom attributes for this object.


---

### isEmpty()
- isEmpty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Return true if the ActiveData doesn't exist for the object

    **Returns:**
    - true if ActiveData is empty, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=bedbb3357a556d3c4517faccd3a775f11fd94ca3f64caefef65ef13d3a0d7232 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.AddressBook.md -->

<!-- prettier-ignore-start -->
# Class AddressBook

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md)

Represents a set of addresses associated with a specific customer.
The AddressBook object gets its data from the Profile object for the customer.
When scripting, this class allows AddressBook to be treated as a separate object
from the Profile. However, data is only stored in the platform in the Profile object
and there is no separate AddressBook object. For this reason, the AddressBook ID is
always the customer profile ID.


**Note:** this class allows access to sensitive personal and private information.
Pay attention to appropriate legal and regulatory requirements when developing.



## Property Summary

| Property | Description |
| --- | --- |
| [addresses](#addresses): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns a sorted list of addresses in the address book. |
| [preferredAddress](#preferredaddress): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md) | Returns the address that has been defined as the customer's preferred  address. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md#createaddressstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new, empty address object with the specified name. |
| [getAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md#getaddressstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the address with the given name from the address book. |
| [getAddresses](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md#getaddresses)() | Returns a sorted list of addresses in the address book. |
| [getPreferredAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md#getpreferredaddress)() | Returns the address that has been defined as the customer's preferred  address. |
| [removeAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md#removeaddresscustomeraddress)([CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)) | Removes the specified address from the address book. |
| [setPreferredAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md#setpreferredaddresscustomeraddress)([CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)) | Sets the specified address as the customer's preferred address. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### addresses
- addresses: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns a sorted list of addresses in the address book.  The addresses
      are sorted so that the preferred address is always sorted first.  The
      remaining addresses are sorted alphabetically by ID.



---

### preferredAddress
- preferredAddress: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Returns the address that has been defined as the customer's preferred
      address.



---

## Method Details

### createAddress(String)
- createAddress(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Creates a new, empty address object with the specified name.

    **Parameters:**
    - name - the ID of the address to create, must not be null.

    **Returns:**
    - the new address object or null if an address with the given name
              already exists in the address book.


    **Throws:**
    - NullArgumentException - If passed 'name' is null.
    - IllegalArgumentException - If passed 'name' is not null, but an                 empty string.


---

### getAddress(String)
- getAddress(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Returns the address with the given name from the address book. The name
      is a unique identifier of the address within the address book.


    **Parameters:**
    - id - An address ID, must not be null.

    **Returns:**
    - The Address object or null if the address does not exist.

    **Throws:**
    - NullArgumentException - If passed 'id' is null.
    - IllegalArgumentException - If passed 'id' is not null, but an                 empty string.


---

### getAddresses()
- getAddresses(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a sorted list of addresses in the address book.  The addresses
      are sorted so that the preferred address is always sorted first.  The
      remaining addresses are sorted alphabetically by ID.


    **Returns:**
    - Sorted List of customer addresses in the address book.


---

### getPreferredAddress()
- getPreferredAddress(): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Returns the address that has been defined as the customer's preferred
      address.


    **Returns:**
    - the default CustomerAddress object, or null if there is no
              preferred address.



---

### removeAddress(CustomerAddress)
- removeAddress(address: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)): void
  - : Removes the specified address from the address book. Because an address
      can be associated with a product list, you may want to verify if the
      address is being used by a product list. See ProductListMgr.findAddress().


    **Parameters:**
    - address - the address to remove, must not be null.


---

### setPreferredAddress(CustomerAddress)
- setPreferredAddress(anAddress: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)): void
  - : Sets the specified address as the customer's preferred address. If null
      is passed, and there is an existing preferred address, then the address
      book will have no preferred address.


    **Parameters:**
    - anAddress - the address to be set as preferred, or null if the goal             is to unset the existing preferred address.


---

<!-- prettier-ignore-end -->

<!-- document id=a76ec9ac599966de8e021f13a31a01dccb62ab550dbecdb425a657645ccdd191 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.AgentUserMgr.md -->

<!-- prettier-ignore-start -->
# Class AgentUserMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.AgentUserMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md)

Provides helper methods for handling agent user functionality (login and logout)
Pay attention to appropriate legal and regulatory requirements related to this functionality.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [loginAgentUser](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md#loginagentuserstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Logs in an agent user (which for example is authorized to login on-behalf of a customer for  instance to place an order). |
| static [loginOnBehalfOfCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md#loginonbehalfofcustomercustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | This method logs the specified customer into the current session if the  current agent user has the functional permission 'Login\_On\_Behalf' in the  current site. |
| static [logoutAgentUser](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md#logoutagentuser)() | Performs a logout of the agent user and the current customer which are attached to the current session. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### loginAgentUser(String, String)
- static loginAgentUser(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Logs in an agent user (which for example is authorized to login on-behalf of a customer for
      instance to place an order). The login is only allowed during a secure protocol
      request (https) and only in the storefront context. The user must have the permission 'Login\_Agent'.
      
      When the login is successful, a new session will be created. Any objects that need
      to be preserved in the session need to bet set on the session afterwards.
      
      A Status object is returned which signals whether the login was successful or not.
      In case of a login failure the status object contains the reason for this.
      See [AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserStatusCodes.md) for more information.


    **Parameters:**
    - login - the login name for the agent user.
    - password - the password for the agent user.

    **Returns:**
    - the login status (OK if successful, error code otherwise).


---

### loginOnBehalfOfCustomer(Customer)
- static loginOnBehalfOfCustomer(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : This method logs the specified customer into the current session if the
      current agent user has the functional permission 'Login\_On\_Behalf' in the
      current site.
      
      The dwcustomer cookie will not be set.
      The login is only allowed during a secure protocol request (https).
      A Status object is returned indicating whether the login was successful or not (and indicating the
      failure reason). See [AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserStatusCodes.md) for more information.
      Error conditions include:
      
      - if the method is not called in the storefront context
      - if the given customer is not a registered customer (anonymous)
      - if the given customer is not registered for the current site
      - if the given customer is disabled
      - if there is no agent user at the current session
      - if the agent user is not logged in
      - if the agent user has not the functional permission 'Login\_On\_Behalf'


    **Parameters:**
    - customer - The customer, which should be logged instead of the agent user

    **Returns:**
    - the login status (OK if successful, error code otherwise).


---

### logoutAgentUser()
- static logoutAgentUser(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Performs a logout of the agent user and the current customer which are attached to the current session.
      The logout is only allowed during a secure protocol request (https) and only in the storefront context.


    **Returns:**
    - the logout status (OK if successful, error code otherwise).


---

<!-- prettier-ignore-end -->

<!-- document id=42c37796a3e8002d8209b47e3c4e1c4aca46293b0e65eb1ba894db98b4ea08db url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.AgentUserStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class AgentUserStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserStatusCodes.md)

AgentUserStatusCodes contains constants representing status codes that can be
used with a [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) object to indicate the success or failure of the agent
user login process.


**See Also:**
- [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)


## All Known Subclasses
[AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.AgentUserStatusCodes.md)
## Constant Summary

| Constant | Description |
| --- | --- |
| [AGENT_USER_NOT_AVAILABLE](#agent_user_not_available): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AGENT_USER_NOT_AVAILABLE" | Indicates that the agent user is not available. |
| [AGENT_USER_NOT_LOGGED_IN](#agent_user_not_logged_in): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AGENT_USER_NOT_LOGGED_IN" | Indicates that the agent user is not logged in. |
| [CREDENTIALS_INVALID](#credentials_invalid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDENTIALS_INVALID" | Indicates that the given agent user login or password was wrong. |
| [CUSTOMER_DISABLED](#customer_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_DISABLED" | Indicates that the customer is disabled. |
| [CUSTOMER_UNREGISTERED](#customer_unregistered): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_UNREGISTERED" | Indicates that the customer is either not registered or not registered with the current site. |
| [INSECURE_CONNECTION](#insecure_connection): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INSECURE_CONNECTION" | Indicates that the current connection is not secure (HTTP instead of HTTPS)  and the server is configured to require a secure connection. |
| [INSUFFICIENT_PERMISSION](#insufficient_permission): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INSUFFICIENT_PERMISSION" | Indicates that the given agent user does not have the permission  'Login\_Agent' which is required to login to the storefront as an agent  user. |
| [LOGIN_SUCCESSFUL](#login_successful): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "LOGIN_SUCCESSFUL" | Indicates that the agent user login was successful. |
| [NO_STOREFRONT](#no_storefront): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_STOREFRONT" | Indicates that the current context is not a storefront request. |
| [PASSWORD_EXPIRED](#password_expired): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PASSWORD_EXPIRED" | Indicates that the given agent user password has expired and needs to be  changed in the Business Manager. |
| [USER_DISABLED](#user_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "USER_DISABLED" | Indicates that the agent user account has been disabled in the Business  Manager. |
| [USER_LOCKED](#user_locked): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "USER_LOCKED" | Indicates that the agent user account is locked, because the maximum  number of failed login attempts was exceeded. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [AgentUserStatusCodes](#agentuserstatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### AGENT_USER_NOT_AVAILABLE

- AGENT_USER_NOT_AVAILABLE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AGENT_USER_NOT_AVAILABLE"
  - : Indicates that the agent user is not available.


---

### AGENT_USER_NOT_LOGGED_IN

- AGENT_USER_NOT_LOGGED_IN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AGENT_USER_NOT_LOGGED_IN"
  - : Indicates that the agent user is not logged in.


---

### CREDENTIALS_INVALID

- CREDENTIALS_INVALID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDENTIALS_INVALID"
  - : Indicates that the given agent user login or password was wrong.


---

### CUSTOMER_DISABLED

- CUSTOMER_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_DISABLED"
  - : Indicates that the customer is disabled.


---

### CUSTOMER_UNREGISTERED

- CUSTOMER_UNREGISTERED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_UNREGISTERED"
  - : Indicates that the customer is either not registered or not registered with the current site.


---

### INSECURE_CONNECTION

- INSECURE_CONNECTION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INSECURE_CONNECTION"
  - : Indicates that the current connection is not secure (HTTP instead of HTTPS)
      and the server is configured to require a secure connection.



---

### INSUFFICIENT_PERMISSION

- INSUFFICIENT_PERMISSION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INSUFFICIENT_PERMISSION"
  - : Indicates that the given agent user does not have the permission
      'Login\_Agent' which is required to login to the storefront as an agent
      user.



---

### LOGIN_SUCCESSFUL

- LOGIN_SUCCESSFUL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "LOGIN_SUCCESSFUL"
  - : Indicates that the agent user login was successful.


---

### NO_STOREFRONT

- NO_STOREFRONT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_STOREFRONT"
  - : Indicates that the current context is not a storefront request.


---

### PASSWORD_EXPIRED

- PASSWORD_EXPIRED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PASSWORD_EXPIRED"
  - : Indicates that the given agent user password has expired and needs to be
      changed in the Business Manager.



---

### USER_DISABLED

- USER_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "USER_DISABLED"
  - : Indicates that the agent user account has been disabled in the Business
      Manager.



---

### USER_LOCKED

- USER_LOCKED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "USER_LOCKED"
  - : Indicates that the agent user account is locked, because the maximum
      number of failed login attempts was exceeded.



---

## Constructor Details

### AgentUserStatusCodes()
- AgentUserStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=d2ec82036c26d721aafc4305cc7e3d0716e45791081d287010a0c961795dd948 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.AgentUserStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class AgentUserStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserStatusCodes.md)
    - [dw.system.AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.AgentUserStatusCodes.md)

AgentUserStatusCodes contains constants representing status codes that can be
used with a [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) object to indicate the success or failure of the agent
user login process.


**See Also:**
- [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)

**Deprecated:**
**warning:** see [AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserStatusCodes.md) - this class should only be used for the LoginAgentUser / LoginOnBehalfCustomer pipelets

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [AgentUserStatusCodes](#agentuserstatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### AgentUserStatusCodes()
- AgentUserStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=4227d74a575c36d74eeb022611139e18b9772dd0afa55e6ef97256050c26dab3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.alert.Alert.md -->

<!-- prettier-ignore-start -->
# Class Alert

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.alert.Alert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alert.md)

This class represents a single system alert to be shown to a Business Manager user.


## Constant Summary

| Constant | Description |
| --- | --- |
| [PRIORITY_ACTION](#priority_action): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ACTION" | String constant to denote the 'action required' priority. |
| [PRIORITY_INFO](#priority_info): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INFO" | String constant to denote the 'informational' priority. |
| [PRIORITY_WARN](#priority_warn): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WARN" | String constant to denote the 'warning' priority. |

## Property Summary

| Property | Description |
| --- | --- |
| [alertDescriptorID](#alertdescriptorid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the referenced alert description. |
| [contextObjectID](#contextobjectid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the referenced context object (or null, if no context object is assigned to this alert). |
| [displayMessage](#displaymessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Resolves the display message to be shown. |
| [priority](#priority): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the priority assigned to the message. |
| [remediationURL](#remediationurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The URL of the page where the user can resolve the alert, as provided in the  'alerts.json' descriptor file. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAlertDescriptorID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alert.md#getalertdescriptorid)() | Returns the ID of the referenced alert description. |
| [getContextObjectID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alert.md#getcontextobjectid)() | Returns the ID of the referenced context object (or null, if no context object is assigned to this alert). |
| [getDisplayMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alert.md#getdisplaymessage)() | Resolves the display message to be shown. |
| [getPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alert.md#getpriority)() | Returns the priority assigned to the message. |
| [getRemediationURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alert.md#getremediationurl)() | The URL of the page where the user can resolve the alert, as provided in the  'alerts.json' descriptor file. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### PRIORITY_ACTION

- PRIORITY_ACTION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ACTION"
  - : String constant to denote the 'action required' priority.


---

### PRIORITY_INFO

- PRIORITY_INFO: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INFO"
  - : String constant to denote the 'informational' priority.


---

### PRIORITY_WARN

- PRIORITY_WARN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WARN"
  - : String constant to denote the 'warning' priority.


---

## Property Details

### alertDescriptorID
- alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the referenced alert description.


---

### contextObjectID
- contextObjectID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the referenced context object (or null, if no context object is assigned to this alert).


---

### displayMessage
- displayMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Resolves the display message to be shown.
      It refers to the message resource ID specified in the alert descriptor file ("message-resource-id") and the message provided
      by the 'alerts.properties' resource bundle.
      When the referenced message contains parameter placeholders (such as '{0}' and '{1}') they are replaced by the parameters stored with the alert.



---

### priority
- priority: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the priority assigned to the message.
      One of the string constants defined in this class (PRIORITY\_INFO, PRIORITY\_WARN, PRIORITY\_ACTION).



---

### remediationURL
- remediationURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The URL of the page where the user can resolve the alert, as provided in the
      'alerts.json' descriptor file.



---

## Method Details

### getAlertDescriptorID()
- getAlertDescriptorID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the referenced alert description.

    **Returns:**
    - the ID of the referenced alert description


---

### getContextObjectID()
- getContextObjectID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the referenced context object (or null, if no context object is assigned to this alert).

    **Returns:**
    - the ID of the referenced context object


---

### getDisplayMessage()
- getDisplayMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Resolves the display message to be shown.
      It refers to the message resource ID specified in the alert descriptor file ("message-resource-id") and the message provided
      by the 'alerts.properties' resource bundle.
      When the referenced message contains parameter placeholders (such as '{0}' and '{1}') they are replaced by the parameters stored with the alert.


    **Returns:**
    - the display message


---

### getPriority()
- getPriority(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the priority assigned to the message.
      One of the string constants defined in this class (PRIORITY\_INFO, PRIORITY\_WARN, PRIORITY\_ACTION).


    **Returns:**
    - the priority


---

### getRemediationURL()
- getRemediationURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The URL of the page where the user can resolve the alert, as provided in the
      'alerts.json' descriptor file.


    **Returns:**
    - the remediation URL


---

<!-- prettier-ignore-end -->

<!-- document id=fd3812b6f2c0b7137d55379acc0a5d0e2899a396f9a530964bd66669f324b9a9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.alert.Alerts.md -->

<!-- prettier-ignore-start -->
# Class Alerts

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.alert.Alerts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md)


Allow creation, removal, re-validation and retrieval of alerts that might get visible to Business Manager users.


The alerts have to be registered by the 'alerts.json' descriptor file in a cartridge assigned to the Business Manager site.
The descriptor file itself has to be defined in 'package.json' of that cartridge using a property 'alerts' and providing its path
that is relative to the 'package.json'.
The 'alert.json' descriptor files contain the 'alert descriptions', which are referenced by their ID throughout the API.


For example, the 'alerts.json' file could have the following content:


```
{
  "alerts": [
    {
      "alert-id": "missing_org_config",
      "menu-action": "global-prefs_custom_prefs",
      "message-resource-id": "global.missing_org_config",
      "priority": "ACTION",
      "remediation": {
        "pipeline":"GlobalCustomPreferences",
        "start-node":"View"
      }
    },
    {
      "alert-id":"promo_in_past",
      "menu-action":"marketing_promotions",
      "context-object-type":"Promotion",
      "message-resource-id":"promotion.in_the_past",
      "priority":"WARN",
      "remediation": {
        "pipeline":"ViewApplication",
        "start-node":"BM",
        "parameter":"screen=Promotion"
      }
    }
  ]
}
```

The referenced menu actions can be found in the 'bm\_extensions.xml' file of a Business manager extension cartridge
(a sample file containing all current menu entries is provided when creating a new extension cartridge in Studio).



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [addAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#addalertstring-persistentobject-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md), [String\[\]](TopLevel.String.md)) | Creates a new alert for the given ID and context object. |
| static [addAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#addalertstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String\[\]](TopLevel.String.md)) | Creates a new alert for the given ID and ID of the context object. |
| static [addAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#addalertstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String\[\]](TopLevel.String.md)) | Creates a new alert for the given ID. |
| static [getAlerts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#getalertsstring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Retrieves all alerts for a set of alert descriptor ID. |
| static [getAlertsForContextObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#getalertsforcontextobjectpersistentobject-string)([PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Retrieves all alerts for a set of alert descriptor ID and the given context object. |
| static [getAlertsForContextObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#getalertsforcontextobjectstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Retrieves all alerts for a set of alert descriptor ID and the given context object ID. |
| static [removeAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#removealertstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Removes all alerts for the given alert descriptor ID. |
| static [removeAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#removealertstring-persistentobject)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)) | Removes the alert for the given alert description and context object. |
| static [removeAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#removealertstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Removes the alert for the given alert description and context object ID. |
| static [revalidateAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#revalidatealertstring-function-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [String\[\]](TopLevel.String.md)) | Re-evaluates the process function, and creates or removes the respective alert. |
| static [revalidateAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#revalidatealertstring-persistentobject-function-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [String\[\]](TopLevel.String.md)) | Re-evaluates the process function, and creates or removes the respective alert. |
| static [revalidateAlert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md#revalidatealertstring-object-string-function-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [String\[\]](TopLevel.String.md)) | Re-evaluates the process function, and creates or removes the respective alert. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### addAlert(String, PersistentObject, String[])
- static addAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextObject: [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md), params: [String\[\]](TopLevel.String.md)): void
  - : Creates a new alert for the given ID and context object.
      If such an alert already exists, no new one is created, and the existing one is not modified.
      Multiple alerts for the same alert descriptor ID may exist, as long as they reference different objects.
      To refer to the same alert afterwards (e.g. to remove the alert) the same object must be provided.


    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - contextObject - the context object
    - params - parameters which may be shown in the alert message


---

### addAlert(String, String, String[])
- static addAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextObjectID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), params: [String\[\]](TopLevel.String.md)): void
  - : Creates a new alert for the given ID and ID of the context object.
      If such an alert already exists, no new one is created, and the existing one is not modified.
      Multiple alerts for the same alert descriptor ID may exist, as long as they reference different objects.
      To refer to the same alert afterwards (e.g. to remove it) the same object ID must be provided.
      
      Use this method when the alerts refers to an object which is not a PersistentObject.


    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - contextObjectID - the ID of the referenced object
    - params - parameters which may be shown in the alert message


---

### addAlert(String, String[])
- static addAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), params: [String\[\]](TopLevel.String.md)): void
  - : Creates a new alert for the given ID.
      If such an alert already exists, no new one is created, and the existing one is not modified.


    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - params - parameters which may be shown in the alert message


---

### getAlerts(String...)
- static getAlerts(alertDescriptorIDs: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Retrieves all alerts for a set of alert descriptor ID.

    **Parameters:**
    - alertDescriptorIDs - the IDs of the referenced alert descriptions

    **Returns:**
    - the list of alerts (of type Alert)


---

### getAlertsForContextObject(PersistentObject, String...)
- static getAlertsForContextObject(contextObject: [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md), alertDescriptorIDs: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Retrieves all alerts for a set of alert descriptor ID and the given context object.

    **Parameters:**
    - contextObject - the context object
    - alertDescriptorIDs - the IDs of the referenced alert descriptions

    **Returns:**
    - the list of alerts (of type Alert)


---

### getAlertsForContextObject(String, String...)
- static getAlertsForContextObject(contextObjectID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), alertDescriptorIDs: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Retrieves all alerts for a set of alert descriptor ID and the given context object ID.

    **Parameters:**
    - contextObjectID - the ID of the referenced object
    - alertDescriptorIDs - the IDs of the referenced alert descriptions

    **Returns:**
    - the list of alerts (of type Alert)


---

### removeAlert(String)
- static removeAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Removes all alerts for the given alert descriptor ID. This method will remove also alert referencing
      context objects, as long as they reference the same alert description.


    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description


---

### removeAlert(String, PersistentObject)
- static removeAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextObject: [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)): void
  - : Removes the alert for the given alert description and context object.

    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - contextObject - the context object


---

### removeAlert(String, String)
- static removeAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextObjectID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Removes the alert for the given alert description and context object ID.

    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - contextObjectID - the context object ID


---

### revalidateAlert(String, Function, String[])
- static revalidateAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), processFunction: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), params: [String\[\]](TopLevel.String.md)): void
  - : Re-evaluates the process function, and creates or removes the respective alert.
      The process function must return true when the alert should be created, and false when it should be removed.
      When the process function states that the alert should be created, but it already exists, it is not created again. Instead, the existing
      alert is updated with the supplied parameters.


    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - processFunction - the validation function. Must return true when the alert needs to be created.
    - params - parameters which may be shown in the alert message


---

### revalidateAlert(String, PersistentObject, Function, String[])
- static revalidateAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextObject: [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md), processFunction: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), params: [String\[\]](TopLevel.String.md)): void
  - : Re-evaluates the process function, and creates or removes the respective alert. The context object is handed as the only parameter to the process function.
      The process function must return true when the alert should be created, and false when it should be removed.
      When the process function states that the alert should be created, but it already exists, it is not created again. Instead, the existing
      alert is updated with the supplied parameters.


    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - contextObject - the context object for which the validation is done, might be null
    - processFunction - the validation function. Must return true when the alert needs to be created.
    - params - parameters which may be shown in the alert message


---

### revalidateAlert(String, Object, String, Function, String[])
- static revalidateAlert(alertDescriptorID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), contextObjectID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), processFunction: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), params: [String\[\]](TopLevel.String.md)): void
  - : Re-evaluates the process function, and creates or removes the respective alert. When the optional
      context object is supplied, it is handed as the only parameter to the process function (if its not supplied,
      no parameter is given to the function).
      The process function must return true when the alert should be created, and false when it should be removed.
      When the process function states that the alert should be created, but it already exists, it is not created again. Instead, the existing
      alert is updated with the supplied parameters.
      Use this variant of the function when the context object is not a persistent object. In this case the ID to be assigned
      to the alert must be supplied as an additional parameter. (Either both the context object and the ID must be provided, or none of them)


    **Parameters:**
    - alertDescriptorID - the ID of the referenced alert description
    - contextObject - the context object for which the validation is done
    - contextObjectID - the id of the context object for which the validation is done (and which is used to add / remove the alert object)
    - processFunction - the validation function. Must return true when the alert needs to be created.
    - params - parameters which may be shown in the alert message


---

<!-- prettier-ignore-end -->

<!-- document id=e62bbc06c72c7bc1750b38f207f7eeedb6e7e1e2ed89db8307ede202fdf50fa1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.AmountDiscount.md -->

<!-- prettier-ignore-start -->
# Class AmountDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md)

Represents an _amount-off_ discount in the discount plan, for example
"$10 off all orders $100 or more".



## Property Summary

| Property | Description |
| --- | --- |
| [amount](#amount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the discount amount, for example 10.00 for a "$10 off" discount. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [AmountDiscount](#amountdiscountnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Create an amount-discount on the fly. |

## Method Summary

| Method | Description |
| --- | --- |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md#getamount)() | Returns the discount amount, for example 10.00 for a "$10 off" discount. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### amount
- amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the discount amount, for example 10.00 for a "$10 off" discount.


---

## Constructor Details

### AmountDiscount(Number)
- AmountDiscount(amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Create an amount-discount on the fly. Can be used to create a custom price adjustment.

    **Parameters:**
    - amount - amount off, e.g. 15.00 for a "15$ off" discount


---

## Method Details

### getAmount()
- getAmount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the discount amount, for example 10.00 for a "$10 off" discount.

    **Returns:**
    - Discount amount


---

<!-- prettier-ignore-end -->

<!-- document id=e3611859846443c4189ff21717ec4bd080c01536013e296b670cd0c4ab86f3b4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.APIException.md -->

<!-- prettier-ignore-start -->
# Class APIException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.APIException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.APIException.md)

This error indicates an exceptional outcome of some business logic. Instances of
this exception in general provide additional information about the reason of this case.
See the actual type referred by the type property for the description of the properties
with this additional information.



Limitation: The sub classes of this APIException shown in this documentation actually do not exist.
All instances are of type APIException, but with different property sets as listed in the sub classes.



The APIException is always related to a systems internal Java exception. The class provides
access to some more details about this internal Java exception.



## All Known Subclasses
[AspectAttributeValidationException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.AspectAttributeValidationException.md), [CreateAgentBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateAgentBasketLimitExceededException.md), [CreateBasketFromOrderException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateBasketFromOrderException.md), [CreateCouponLineItemException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateCouponLineItemException.md), [CreateOrderException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateOrderException.md), [CreateTemporaryBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateTemporaryBasketLimitExceededException.md), [ShopperConsentException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentException.md), [ShopperContextException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextException.md)
## Property Summary

| Property | Description |
| --- | --- |
| [causeFullName](#causefullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the full name of the associated Java exception. |
| [causeMessage](#causemessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the message of the associated Java exception. |
| [causeName](#causename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the simplified name of the associated Java exception. |
| [javaFullName](#javafullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The full name of the underlying Java exception. |
| [javaMessage](#javamessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The message of the underlying Java exception. |
| [javaName](#javaname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The simplified name of the underlying Java exception. |
| [type](#type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The name of the actual APIException type, without the package name. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [APIException](#apiexception)() |  |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### causeFullName
- causeFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the full name of the associated Java exception.



---

### causeMessage
- causeMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the message of the associated Java exception.



---

### causeName
- causeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the simplified name of the associated Java exception.



---

### javaFullName
- javaFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The full name of the underlying Java exception.


---

### javaMessage
- javaMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The message of the underlying Java exception.


---

### javaName
- javaName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The simplified name of the underlying Java exception.


---

### type
- type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The name of the actual APIException type, without the package name.


---

## Constructor Details

### APIException()
- APIException()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=5cdb6eb4dfbe0833db38bbcbab95018d20a52ee7586699c5897da485e1ba859d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.Appeasement.md -->

<!-- prettier-ignore-start -->
# Class Appeasement

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md)
      - [dw.order.Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)

The Appeasement represents a shopper request for an order credit.

Example: The buyer finds any problem with the products but he agrees to preserve them, if he would be compensated,
rather than return them.



The Appeasement contains 1..n appeasement items.
Each appeasement item is associated with one [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) usually representing an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
[ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md). 



An Appeasement can have one of these status values:

- OPEN - the appeasement is open and appeasement items could be added to it
- COMPLETED - the appeasement is complete and it is not allowed to add new items to it, this is a precondition  for refunding the customer for an appeasement.



Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [ORDERBY_ITEMID](#orderby_itemid): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by item id. |
| [ORDERBY_ITEMPOSITION](#orderby_itemposition): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by the position of the related order item. |
| [ORDERBY_UNSORTED](#orderby_unsorted): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Unsorted, as it is. |
| [QUALIFIER_PRODUCTITEMS](#qualifier_productitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the product items. |
| [QUALIFIER_SERVICEITEMS](#qualifier_serviceitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the service items. |
| [STATUS_COMPLETED](#status_completed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COMPLETED" | Constant for Appeasement Status COMPLETED |
| [STATUS_OPEN](#status_open): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OPEN" | Constant for Appeasement Status OPEN |

## Property Summary

| Property | Description |
| --- | --- |
| [appeasementNumber](#appeasementnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the appeasement number. |
| [invoice](#invoice): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)` | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [invoiceNumber](#invoicenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns `null` or the invoice-number. |
| [items](#items): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns a filtering collection of the appeasement items belonging to the appeasement. |
| [reasonCode](#reasoncode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the reason code for the appeasement. |
| [reasonNote](#reasonnote): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the reason note for the appeasement. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Gets the status of this appeasement.  The possible values are [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_open), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_completed). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#additemsmoney-list)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Creates appeasement items corresponding to certain order items and adds them to the appeasement. |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoice)() | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Appeasement. |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoicestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Appeasement. |
| [getAppeasementNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getappeasementnumber)() | Returns the appeasement number. |
| [getInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getinvoice)() | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [getInvoiceNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getinvoicenumber)() | Returns `null` or the invoice-number. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getitems)() | Returns a filtering collection of the appeasement items belonging to the appeasement. |
| [getReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getreasoncode)() | Returns the reason code for the appeasement. |
| [getReasonNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getreasonnote)() | Returns the reason note for the appeasement. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getstatus)() | Gets the status of this appeasement.  The possible values are [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_open), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_completed). |
| [setReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#setreasoncodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the reason code for the appeasement. |
| [setReasonNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#setreasonnotestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the reason note for the appeasement. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#setstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the appeasement status. |

### Methods inherited from class AbstractItemCtnr

[getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreatedby), [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreationdate), [getGrandTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getgrandtotal), [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getlastmodified), [getModifiedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getmodifiedby), [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder), [getProductSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getproductsubtotal), [getServiceSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getservicesubtotal)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ORDERBY_ITEMID

- ORDERBY_ITEMID: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by item id. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### ORDERBY_ITEMPOSITION

- ORDERBY_ITEMPOSITION: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by the position of the related order item. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### ORDERBY_UNSORTED

- ORDERBY_UNSORTED: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Unsorted, as it is. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### QUALIFIER_PRODUCTITEMS

- QUALIFIER_PRODUCTITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the product items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getitems) as an argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).


---

### QUALIFIER_SERVICEITEMS

- QUALIFIER_SERVICEITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the service items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#getitems) as an argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).


---

### STATUS_COMPLETED

- STATUS_COMPLETED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COMPLETED"
  - : Constant for Appeasement Status COMPLETED


---

### STATUS_OPEN

- STATUS_OPEN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OPEN"
  - : Constant for Appeasement Status OPEN


---

## Property Details

### appeasementNumber
- appeasementNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the appeasement number.


---

### invoice
- invoice: [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)`
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoicestring)


---

### invoiceNumber
- invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns `null` or the invoice-number.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoicestring)


---

### items
- items: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns a filtering collection of the appeasement items belonging to the appeasement.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) could be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#qualifier_serviceitems)



---

### reasonCode
- reasonCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code for the appeasement. The list of reason codes can be updated
      by updating meta-data for Appeasement.



---

### reasonNote
- reasonNote: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the reason note for the appeasement.


---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the status of this appeasement.
      
      The possible values are [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_open), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_completed).



---

## Method Details

### addItems(Money, List)
- addItems(totalAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), orderItems: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): void
  - : Creates appeasement items corresponding to certain order items and adds them to the appeasement.

    **Parameters:**
    - totalAmount - the appeasement amount corresponding to the provided order items; this amount is the net price                     when the order is net based and respectively - gross price when the order is gross based
    - orderItems - the order items for which appeasement items should be created


---

### createInvoice()
- createInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Appeasement. The appeasement-number
      will be used as the invoice-number.
      
      
      The method must not be called more than once for an Appeasement,
      nor may 2 invoices exist with the same invoice-number.
      
      
      The new Invoice is a credit-invoice with a [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid) status, and
      should be passed to the refund payment-hook in a separate database transaction for processing.


    **Returns:**
    - the created invoice


---

### createInvoice(String)
- createInvoice(invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Appeasement. The
      invoice-number must be specified as an argument.
      
      
      The method must not be called more than once for an Appeasement,
      nor may 2 invoices exist with the same invoice-number.
      
      
      The new Invoice is a credit-invoice with a [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid) status, and
      should be passed to the refund payment-hook in a separate database transaction for processing.


    **Parameters:**
    - invoiceNumber - the invoice-number to be used in the appeasement creation process

    **Returns:**
    - the created invoice


---

### getAppeasementNumber()
- getAppeasementNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the appeasement number.

    **Returns:**
    - the appeasement number


---

### getInvoice()
- getInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **Returns:**
    - null or the previously created invoice

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoicestring)


---

### getInvoiceNumber()
- getInvoiceNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns `null` or the invoice-number.

    **Returns:**
    - `null` or the number of the previously created invoice

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoicestring)


---

### getItems()
- getItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns a filtering collection of the appeasement items belonging to the appeasement.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) could be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#qualifier_serviceitems)


    **Returns:**
    - the filtering collection of the appeasement items


---

### getReasonCode()
- getReasonCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code for the appeasement. The list of reason codes can be updated
      by updating meta-data for Appeasement.


    **Returns:**
    - the appeasement reason code


---

### getReasonNote()
- getReasonNote(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the reason note for the appeasement.

    **Returns:**
    - the reason note or `null`


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the status of this appeasement.
      
      The possible values are [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_open), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_completed).


    **Returns:**
    - the status


---

### setReasonCode(String)
- setReasonCode(reasonCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the reason code for the appeasement. The list of reason codes can be updated
      by updating meta-data for Appeasement.


    **Parameters:**
    - reasonCode - the reason code to set


---

### setReasonNote(String)
- setReasonNote(reasonNote: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the reason note for the appeasement.

    **Parameters:**
    - reasonNote - the reason note for the appeasement to set


---

### setStatus(String)
- setStatus(appeasementStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the appeasement status.
      
      
      The possible values are [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_open), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#status_completed).
      
      
      When set to status COMPLETED, only the the custom attributes of its appeasement items can be changed.


    **Parameters:**
    - appeasementStatus - the appeasement status to set.


---

<!-- prettier-ignore-end -->

<!-- document id=8d915dac4d1057b5d8f921c9da08107aa3ef6811d959d2e255d84962459156cd url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.AppeasementItem.md -->

<!-- prettier-ignore-start -->
# Class AppeasementItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md)
      - [dw.order.AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)

Represents an item of an [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) which is associated with one [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) usually representing an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
[ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md). Items are created using method [Appeasement.addItems(Money, List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#additemsmoney-list)


When the related Appeasement were set to status COMPLETED, only the the custom attributes of the appeasement item can be changed.


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Property Summary

| Property | Description |
| --- | --- |
| [appeasementNumber](#appeasementnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the number of the [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) to which this item belongs. |
| [parentItem](#parentitem): [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md) | Returns null or the parent item. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAppeasementNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md#getappeasementnumber)() | Returns the number of the [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) to which this item belongs. |
| [getParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md#getparentitem)() | Returns null or the parent item. |
| [setParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md#setparentitemappeasementitem)([AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)) | Set a parent item. |

### Methods inherited from class AbstractItem

[getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice), [getItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getitemid), [getLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getlineitem), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice), [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitem), [getOrderItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitemid), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis), [getTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxitems)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### appeasementNumber
- appeasementNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the number of the [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) to which this item belongs.


---

### parentItem
- parentItem: [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)
  - : Returns null or the parent item.


---

## Method Details

### getAppeasementNumber()
- getAppeasementNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the number of the [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) to which this item belongs.

    **Returns:**
    - the number of the Appeasement to which this item belongs


---

### getParentItem()
- getParentItem(): [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)
  - : Returns null or the parent item.

    **Returns:**
    - null or the parent item.


---

### setParentItem(AppeasementItem)
- setParentItem(parentItem: [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)): void
  - : Set a parent item. The parent item must belong to the same
      [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md). An infinite parent-child loop is disallowed
      as is a parent-child depth greater than 10. Setting a parent item
      indicates a dependency of the child item on the parent item, and can be
      used to form a parallel structure to that accessed using
      [ProductLineItem.getParent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getparent).


    **Parameters:**
    - parentItem - The parent item, null is allowed


---

<!-- prettier-ignore-end -->

<!-- document id=d99155c1ef7a70b027c9895855cd1948a0970c6c2657b81acf2df1b54eec1178 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.applepay.ApplePayHookResult.md -->

<!-- prettier-ignore-start -->
# Class ApplePayHookResult

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.applepay.ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)



Result of a hook handling an Apple Pay request.





Use the constants in this type to indicate specific error reasons to be provided
to Apple Pay JS. For example, the following code creates a [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
that indicates the shipping contact information provided by Apple Pay is invalid:




```
var ApplePayHookResult = require('dw/extensions/applepay/ApplePayHookResult');
var Status = require('dw/system/Status');

var error = new Status(Status.ERROR);
error.addDetail(ApplePayHookResult.STATUS_REASON_DETAIL_KEY, ApplePayHookResult.REASON_SHIPPING_CONTACT);
```




If a specific error reason is not provided, the generic Apple Pay `STATUS_FAILURE`
reason will be used when necessary.



## Constant Summary

| Constant | Description |
| --- | --- |
| [REASON_BILLING_ADDRESS](#reason_billing_address): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "InvalidBillingPostalAddress" | Error reason code representing an invalid billing address. |
| [REASON_FAILURE](#reason_failure): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Failure" | Error reason code representing an error or failure not otherwise specified. |
| [REASON_PIN_INCORRECT](#reason_pin_incorrect): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PINIncorrect" | Error reason code representing the PIN is incorrect. |
| [REASON_PIN_LOCKOUT](#reason_pin_lockout): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PINLockout" | Error reason code representing a PIN lockout. |
| [REASON_PIN_REQUIRED](#reason_pin_required): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PINRequired" | Error reason code representing a PIN is required. |
| [REASON_SHIPPING_ADDRESS](#reason_shipping_address): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "InvalidShippingPostalAddress" | Error reason code representing an invalid shipping address. |
| [REASON_SHIPPING_CONTACT](#reason_shipping_contact): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "InvalidShippingContact" | Error reason code representing invalid shipping contact information. |
| [STATUS_REASON_DETAIL_KEY](#status_reason_detail_key): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "reason" | Key for the detail to be used in [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) objects to indicate  the reason to communicate to Apple Pay for errors. |

## Property Summary

| Property | Description |
| --- | --- |
| [eventDetail](#eventdetail): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Detail to the JS custom event to dispatch in response to this result. |
| [eventName](#eventname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Name of the JS custom event to dispatch in response to this result. |
| [redirect](#redirect): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)` | URL to navigate to in response to this result. |
| [status](#status): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) `(read-only)` | Status describing the outcome of this result. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ApplePayHookResult](#applepayhookresultstatus-url)([Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md), [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Constructs a result with the given outcome information. |

## Method Summary

| Method | Description |
| --- | --- |
| [getEventDetail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md#geteventdetail)() | Detail to the JS custom event to dispatch in response to this result. |
| [getEventName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md#geteventname)() | Name of the JS custom event to dispatch in response to this result. |
| [getRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md#getredirect)() | URL to navigate to in response to this result. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md#getstatus)() | Status describing the outcome of this result. |
| [setEvent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md#seteventstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the JS custom event to dispatch in response to this result. |
| [setEvent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md#seteventstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the name and detail of the JS custom event to dispatch in response to this result. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### REASON_BILLING_ADDRESS

- REASON_BILLING_ADDRESS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "InvalidBillingPostalAddress"
  - : Error reason code representing an invalid billing address.


---

### REASON_FAILURE

- REASON_FAILURE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Failure"
  - : Error reason code representing an error or failure not otherwise specified.


---

### REASON_PIN_INCORRECT

- REASON_PIN_INCORRECT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PINIncorrect"
  - : Error reason code representing the PIN is incorrect.


---

### REASON_PIN_LOCKOUT

- REASON_PIN_LOCKOUT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PINLockout"
  - : Error reason code representing a PIN lockout.


---

### REASON_PIN_REQUIRED

- REASON_PIN_REQUIRED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PINRequired"
  - : Error reason code representing a PIN is required.


---

### REASON_SHIPPING_ADDRESS

- REASON_SHIPPING_ADDRESS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "InvalidShippingPostalAddress"
  - : Error reason code representing an invalid shipping address.


---

### REASON_SHIPPING_CONTACT

- REASON_SHIPPING_CONTACT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "InvalidShippingContact"
  - : Error reason code representing invalid shipping contact information.


---

### STATUS_REASON_DETAIL_KEY

- STATUS_REASON_DETAIL_KEY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "reason"
  - : Key for the detail to be used in [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) objects to indicate
      the reason to communicate to Apple Pay for errors.



---

## Property Details

### eventDetail
- eventDetail: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Detail to the JS custom event to dispatch in response to this result.


---

### eventName
- eventName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Name of the JS custom event to dispatch in response to this result.


---

### redirect
- redirect: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)`
  - : URL to navigate to in response to this result.


---

### status
- status: [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) `(read-only)`
  - : Status describing the outcome of this result.


---

## Constructor Details

### ApplePayHookResult(Status, URL)
- ApplePayHookResult(status: [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md), redirect: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md))
  - : Constructs a result with the given outcome information.

    **Parameters:**
    - status - status of the result
    - redirect - optional URL to which to navigate to in response to this outcome


---

## Method Details

### getEventDetail()
- getEventDetail(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Detail to the JS custom event to dispatch in response to this result.

    **Returns:**
    - event detail


---

### getEventName()
- getEventName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Name of the JS custom event to dispatch in response to this result.

    **Returns:**
    - event name


---

### getRedirect()
- getRedirect(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : URL to navigate to in response to this result.

    **Returns:**
    - redirect URL


---

### getStatus()
- getStatus(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Status describing the outcome of this result.

    **Returns:**
    - status of this result


---

### setEvent(String)
- setEvent(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the JS custom event to dispatch in response to this result.

    **Parameters:**
    - name - JS custom event name


---

### setEvent(String, Object)
- setEvent(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), detail: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the name and detail of the JS custom event to dispatch in response to this result.

    **Parameters:**
    - name - JS custom event name
    - detail - JS custom event detail


---

<!-- prettier-ignore-end -->

<!-- document id=98529f38948f573a379f9366725385ec956b1bd5d04ba2b5726e47f3da36279e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.applepay.ApplePayHooks.md -->

<!-- prettier-ignore-start -->
# Class ApplePayHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.applepay.ApplePayHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md)

ApplePayHooks interface containing extension points for customizing Apple Pay.


These hooks are executed in a transaction.


The extension points (hook names), and the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the exported hook function must be located
inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.




```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
     {"name": "dw.extensions.applepay.getRequest", "script": "./applepay.ds"}
     {"name": "dw.extensions.applepay.shippingContactSelected", "script": "./applepay.ds"}
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointCancel](#extensionpointcancel): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.cancel" | The extension point name dw.extensions.applepay.cancel. |
| [extensionPointGetRequest](#extensionpointgetrequest): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.getRequest" | The extension point name dw.extensions.applepay.getRequest. |
| [extensionPointPaymentAuthorizedAuthorizeOrderPayment](#extensionpointpaymentauthorizedauthorizeorderpayment): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.authorizeOrderPayment" | The extension point name dw.extensions.applepay.paymentAuthorized.authorizeOrderPayment. |
| [extensionPointPaymentAuthorizedCreateOrder](#extensionpointpaymentauthorizedcreateorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.createOrder" | The extension point name dw.extensions.applepay.paymentAuthorized.createOrder. |
| [extensionPointPaymentAuthorizedFailOrder](#extensionpointpaymentauthorizedfailorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.failOrder" | The extension point name dw.extensions.applepay.paymentAuthorized.failOrder. |
| [extensionPointPaymentAuthorizedPlaceOrder](#extensionpointpaymentauthorizedplaceorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.placeOrder" | The extension point name dw.extensions.applepay.paymentAuthorized.placeOrder. |
| [extensionPointPaymentMethodSelected](#extensionpointpaymentmethodselected): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentMethodSelected" | The extension point name dw.extensions.applepay.paymentMethodSelected. |
| [extensionPointPrepareBasket](#extensionpointpreparebasket): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.prepareBasket" | The extension point name dw.extensions.applepay.prepareBasket. |
| [extensionPointShippingContactSelected](#extensionpointshippingcontactselected): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.shippingContactSelected" | The extension point name dw.extensions.applepay.shippingContactSelected. |
| [extensionPointShippingMethodSelected](#extensionpointshippingmethodselected): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.shippingMethodSelected" | The extension point name dw.extensions.applepay.shippingMethodSelected. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [authorizeOrderPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#authorizeorderpaymentorder-object)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called to authorize the Apple Pay payment for the order. |
| [cancel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#cancelbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | <p>  Called after the Apple Pay payment sheet was canceled. |
| [createOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#createorderbasket-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called after handling the given `ApplePayPaymentAuthorizedEvent` for the given basket. |
| [failOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#failorderorder-status)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)) | <p>  Called after payment authorization is unsuccessful and the given Apple Pay order must be failed. |
| [getRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#getrequestbasket-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called to get the Apple Pay JS `PaymentRequest` for the given basket. |
| [paymentMethodSelected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#paymentmethodselectedbasket-object-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called after handling the given `ApplePayPaymentMethodSelectedEvent` for the given basket. |
| [placeOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#placeorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  Called after payment has been authorized and the given Apple Pay order is ready to be placed. |
| [prepareBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#preparebasketbasket-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called to prepare the given basket for an Apple Pay checkout. |
| [shippingContactSelected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#shippingcontactselectedbasket-object-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called after handling the given `ApplePayShippingContactSelectedEvent` for the given basket. |
| [shippingMethodSelected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#shippingmethodselectedbasket-shippingmethod-object-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called after handling the given `ApplePayShippingMethodSelectedEvent` for the given basket. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointCancel

- extensionPointCancel: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.cancel"
  - : The extension point name dw.extensions.applepay.cancel.


---

### extensionPointGetRequest

- extensionPointGetRequest: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.getRequest"
  - : The extension point name dw.extensions.applepay.getRequest.


---

### extensionPointPaymentAuthorizedAuthorizeOrderPayment

- extensionPointPaymentAuthorizedAuthorizeOrderPayment: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.authorizeOrderPayment"
  - : The extension point name dw.extensions.applepay.paymentAuthorized.authorizeOrderPayment.


---

### extensionPointPaymentAuthorizedCreateOrder

- extensionPointPaymentAuthorizedCreateOrder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.createOrder"
  - : The extension point name dw.extensions.applepay.paymentAuthorized.createOrder.


---

### extensionPointPaymentAuthorizedFailOrder

- extensionPointPaymentAuthorizedFailOrder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.failOrder"
  - : The extension point name dw.extensions.applepay.paymentAuthorized.failOrder.


---

### extensionPointPaymentAuthorizedPlaceOrder

- extensionPointPaymentAuthorizedPlaceOrder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentAuthorized.placeOrder"
  - : The extension point name dw.extensions.applepay.paymentAuthorized.placeOrder.


---

### extensionPointPaymentMethodSelected

- extensionPointPaymentMethodSelected: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.paymentMethodSelected"
  - : The extension point name dw.extensions.applepay.paymentMethodSelected.


---

### extensionPointPrepareBasket

- extensionPointPrepareBasket: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.prepareBasket"
  - : The extension point name dw.extensions.applepay.prepareBasket.


---

### extensionPointShippingContactSelected

- extensionPointShippingContactSelected: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.shippingContactSelected"
  - : The extension point name dw.extensions.applepay.shippingContactSelected.


---

### extensionPointShippingMethodSelected

- extensionPointShippingMethodSelected: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.applepay.shippingMethodSelected"
  - : The extension point name dw.extensions.applepay.shippingMethodSelected.


---

## Method Details

### authorizeOrderPayment(Order, Object)
- authorizeOrderPayment(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), event: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Called to authorize the Apple Pay payment for the order. The given order will have been created by the
      [extensionPointPaymentAuthorizedCreateOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#extensionpointpaymentauthorizedcreateorder) hook, after the basket was populated with data from
      the `ApplePayPaymentAuthorizedEvent`.
      
      
      
      
      Return a non-error status if you have successfully authorized the payment with your payment service provider.
      Your hook implementation must set the necessary payment status and transaction identifier data on the order as
      returned by the provider.
      
      
      
      
      Return an error status to indicate a problem, including unsuccessful authorization. See
      [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md) for how to indicate error statuses with detail information to
      be provided to Apple Pay.
      
      
      
      
      See the [Apple Pay JS API Reference](https://developer.apple.com/reference/applepayjs) for more information.


    **Parameters:**
    - order - the order paid using Apple Pay
    - event - `ApplePayPaymentAuthorizedEvent` object

    **Returns:**
    - a non-null status ends the hook execution


---

### cancel(Basket)
- cancel(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called after the Apple Pay payment sheet was canceled. There is no Apple Pay JS event object for this case. The
      given basket is the one that was passed to other hooks earlier in the Apple Pay checkout process.
      
      
      
      
      It is not guaranteed that this hook will be executed for all Apple Pay payment sheets canceled by shoppers or
      otherwise ended without a successful order. Calls to this hook are provided on a best-effort basis.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if possible. It
      is not guaranteed that the response with the hook result will be handled in the shopper browser in all cases.


    **Parameters:**
    - basket - the basket that was being checked out using Apple Pay

    **Returns:**
    - a non-null result ends the hook execution


---

### createOrder(Basket, Object)
- createOrder(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), event: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : 
      
      Called after handling the given `ApplePayPaymentAuthorizedEvent` for the given basket. Customer
      information, billing address, and/or shipping address for the default shipment will have already been updated to
      reflect the available contact information provided by Apple Pay based on the Apple Pay configuration for your
      site. Any preexisting payment instruments on the basket will have been removed, and a single
      `DW_APPLE_PAY` payment instrument added for the total amount.
      
      
      
      
      The purpose of this hook is to populate the created order with any necessary information from the basket
      or the Apple Pay event. Do not use this hook for address verification, or any other validation. Instead
      use the [extensionPointPaymentAuthorizedAuthorizeOrderPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#extensionpointpaymentauthorizedauthorizeorderpayment) hook which allows you to return
      an `ApplePayHookResult` with error status information.
      
      
      
      
      The default implementation of this hook simply calls `OrderMgr.createOrder` and returns the created
      order.
      
      
      
      
      Throw an error to indicate a problem creating the order.


    **Parameters:**
    - basket - the basket being checked out using Apple Pay
    - event - `ApplePayPaymentAuthorizedEvent` object

    **Returns:**
    - a non-null order ends the hook execution


---

### failOrder(Order, Status)
- failOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), status: [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called after payment authorization is unsuccessful and the given Apple Pay order must be failed. The purpose
      of this hook is to fail the order, or return a redirect URL that results in the order being failed when the shopper
      browser is navigated to it. The given status object is the result of calling the
      [extensionPointPaymentAuthorizedAuthorizeOrderPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#extensionpointpaymentauthorizedauthorizeorderpayment) hook.
      
      
      
      
      The default implementation of this hook simply calls `OrderMgr.failOrder`, and returns a result
      with the given status and no redirect URL.
      
      
      
      
      Return a result with an error status to indicate a problem. See [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
      for how to indicate error statuses with detail information to be provided to Apple Pay. If the returned result includes
      a redirect URL, the shopper browser will be navigated to that URL if the Apple Pay payment sheet is canceled.


    **Parameters:**
    - order - the order created for a failed Apple Pay checkout
    - status - status code returned by the [extensionPointPaymentAuthorizedAuthorizeOrderPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md#extensionpointpaymentauthorizedauthorizeorderpayment) hook

    **Returns:**
    - ApplePayHookResult containing a status code to be provided to Apple Pay. A non-null result ends the hook execution


---

### getRequest(Basket, Object)
- getRequest(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), request: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called to get the Apple Pay JS `PaymentRequest` for the given basket. You can set properties in the
      given request object to extend or override default properties set automatically based on the Apple Pay
      configuration for your site.
      
      
      
      
      Return a result with an error status to indicate a problem. See [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
      for how to indicate error statuses with detail information to be provided to Apple Pay.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if the Apple
      Pay payment sheet is canceled.
      
      
      
      
      See the [Apple Pay JS API Reference](https://developer.apple.com/reference/applepayjs) for more information.


    **Parameters:**
    - basket - the basket for the Apple Pay request
    - request - the Apple Pay payment request object

    **Returns:**
    - a non-null result ends the hook execution


---

### paymentMethodSelected(Basket, Object, Object)
- paymentMethodSelected(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), event: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), response: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called after handling the given `ApplePayPaymentMethodSelectedEvent` for the given basket. This Apple
      Pay event does not contain payment card or device information.
      
      
      
      
      The given response object will contain properties whose values are to be passed as parameters to the
      `ApplePaySession.completePaymentMethodSelection` event callback:
      
      
      
      - total - Updated total line item object
      - lineItems - Array of updated line item objects
      
      
      
      Return a result with an error status to indicate a problem. See [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
      for how to indicate error statuses with detail information to be provided to Apple Pay.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if the Apple
      Pay payment sheet is canceled.
      
      
      
      
      See the [Apple Pay JS API Reference](https://developer.apple.com/reference/applepayjs) for more information.


    **Parameters:**
    - basket - the basket being checked out using Apple Pay
    - event - `ApplePayPaymentMethodSelectedEvent` object
    - response - JS object containing Apple Pay event callback parameters

    **Returns:**
    - a non-null result ends the hook execution


---

### placeOrder(Order)
- placeOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called after payment has been authorized and the given Apple Pay order is ready to be placed. The purpose of this
      hook is to place the order, or return a redirect URL that results in the order being placed when the shopper
      browser is navigated to it.
      
      
      
      
      The default implementation of this hook returns a redirect to `COPlaceOrder-Submit` with URL
      parameters `order_id` set to [Order.getOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderno) and `order_token` set to
      [Order.getOrderToken()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getordertoken) which corresponds to SiteGenesis-based implementations. Your hook
      implementation should return a result with a different redirect URL as necessary to place the order and show an
      order confirmation.
      
      
      
      
      Alternatively, your hook implementation itself can place the order and return a result with a redirect URL to an
      order confirmation page that does not place the order. This is inconsistent with SiteGenesis-based
      implementations so is not the default.
      
      
      
      
      Return an error status to indicate a problem. See [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md) for how to
      indicate error statuses with detail information to be provided to Apple Pay. If the returned result includes a
      redirect URL, the shopper browser will be navigated to that URL if the Apple Pay payment sheet is canceled.


    **Parameters:**
    - order - the order paid using Apple Pay

    **Returns:**
    - a non-null result ends the hook execution


---

### prepareBasket(Basket, Object)
- prepareBasket(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), parameters: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called to prepare the given basket for an Apple Pay checkout. This hook will be executed after the user
      clicks the Apple Pay button.
      
      
      
      
      The default implementation of this hook calculates the basket. A custom hook implementation that returns a
      non-null result must calculate the basket.
      
      
      
      
      The given parameters object will contain properties whose values are passed from the
      `<isapplepay></isapplepay>` tag:
      
      
      
      - sku - SKU of product to checkout exclusively
      
      
      
      Return a result with an error status to indicate a problem. For this hook there is no opportunity to provide user
      feedback, so if any error status is returned, the Apple Pay payment sheet will be aborted.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL after the Apple
      Pay payment sheet is aborted.


    **Parameters:**
    - basket - the basket for the Apple Pay request
    - parameters - parameters from the `<isapplepay></isapplepay>` tag

    **Returns:**
    - a non-null result ends the hook execution


---

### shippingContactSelected(Basket, Object, Object)
- shippingContactSelected(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), event: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), response: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called after handling the given `ApplePayShippingContactSelectedEvent` for the given basket. Basket
      customer information and/or shipping address for the default shipment will have already been updated to reflect
      the available shipping contact information provided by Apple Pay based on the Apple Pay configuration for your
      site. The basket will have already been calculated before this hook is called.
      
      
      
      
      The given response object will contain properties whose values are to be passed as parameters to the
      `ApplePaySession.completeShippingContactSelection` event callback:
      
      
      
      - shippingMethods - Array of applicable shipping method JS objects
      - total - Updated total line item object
      - lineItems - Array of updated line item objects
      
      
      
      Return a result with an error status to indicate a problem. See [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
      for how to indicate error statuses with detail information to be provided to Apple Pay.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if the Apple
      Pay payment sheet is canceled.
      
      
      
      
      See the [Apple Pay JS API Reference](https://developer.apple.com/reference/applepayjs) for more information.


    **Parameters:**
    - basket - the basket being checked out using Apple Pay
    - event - `ApplePayShippingContactSelectedEvent` object
    - response - JS object containing Apple Pay event callback parameters

    **Returns:**
    - a non-null result ends the hook execution


---

### shippingMethodSelected(Basket, ShippingMethod, Object, Object)
- shippingMethodSelected(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), event: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), response: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
  - : 
      
      Called after handling the given `ApplePayShippingMethodSelectedEvent` for the given basket. The given
      shipping method will have already been set on the basket.  The basket will have already been calculated before
      this hook is called.
      
      
      
      
      The given response object will contain properties whose values are to be passed as parameters to the
      `ApplePaySession.completeShippingMethodSelection` event callback:
      
      
      
      - total - Updated total line item object
      - lineItems - Array of updated line item objects
      
      
      
      Return a result with an error status to indicate a problem. See [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md)
      for how to indicate error statuses with detail information to be provided to Apple Pay.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if the Apple
      Pay payment sheet is canceled.
      
      
      
      
      See the [Apple Pay JS API Reference](https://developer.apple.com/reference/applepayjs) for more information.


    **Parameters:**
    - basket - the basket being checked out using Apple Pay
    - shippingMethod - the shipping method that was selected
    - event - `ApplePayShippingMethodSelectedEvent` object
    - response - JS object containing Apple Pay event callback parameters

    **Returns:**
    - a non-null result ends the hook execution


---

<!-- prettier-ignore-end -->

<!-- document id=6043f01e92c183d92a054b9d2fca62157aa5547b35379df4abba454781d7cc96 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.ApproachingDiscount.md -->

<!-- prettier-ignore-start -->
# Class ApproachingDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.ApproachingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ApproachingDiscount.md)

Transient class representing a discount that a [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)
"almost" qualifies for based on the amount of merchandise in it. Storefronts
can display information about approaching discounts to customers in order to
entice them to buy more merchandise.


Approaching discounts are calculated on the basis of a
[DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md) instead of a LineItemCtnr itself. When one
of [PromotionMgr.getDiscounts(LineItemCtnr)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr) or
[PromotionMgr.getDiscounts(LineItemCtnr, PromotionPlan)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr-promotionplan) is
called, the promotions engine calculates the discounts the LineItemCtnr
receives based on the promotions in context, and also tries to determine the
discounts the LineItemCtnr would receive if additional merchandise were
added. DiscountPlan provides different methods to retrieve this approaching
discount info. Merchants can use these fine-grained methods to display
information about approaching order discounts on the cart page, and
approaching shipping discounts on the shipping method page during checkout,
for example.


The merchant may include or exclude individual promotions from being included
in this list, and define distance thresholds when configuring their
promotions.



## Property Summary

| Property | Description |
| --- | --- |
| [conditionThreshold](#conditionthreshold): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | The amount of merchandise required in the cart in order to receive the  discount. |
| [discount](#discount): [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) `(read-only)` | The discount that the customer will receive if he adds more merchandise  to the cart. |
| [distanceFromConditionThreshold](#distancefromconditionthreshold): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Convenience method that returns  `getConditionThreshold().subtract(getMerchandiseValue())` |
| [merchandiseTotal](#merchandisetotal): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | The amount of merchandise in the cart contributing towards the condition  threshold. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getConditionThreshold](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ApproachingDiscount.md#getconditionthreshold)() | The amount of merchandise required in the cart in order to receive the  discount. |
| [getDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ApproachingDiscount.md#getdiscount)() | The discount that the customer will receive if he adds more merchandise  to the cart. |
| [getDistanceFromConditionThreshold](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ApproachingDiscount.md#getdistancefromconditionthreshold)() | Convenience method that returns  `getConditionThreshold().subtract(getMerchandiseValue())` |
| [getMerchandiseTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ApproachingDiscount.md#getmerchandisetotal)() | The amount of merchandise in the cart contributing towards the condition  threshold. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### conditionThreshold
- conditionThreshold: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : The amount of merchandise required in the cart in order to receive the
      discount. For an order promotion "Get 15% off orders of $100 or more",
      the condition threshold is $100.00.



---

### discount
- discount: [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) `(read-only)`
  - : The discount that the customer will receive if he adds more merchandise
      to the cart. For an order promotion "Get 15% off orders of $100 or more",
      the discount is a PercentageDiscount object.



---

### distanceFromConditionThreshold
- distanceFromConditionThreshold: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Convenience method that returns
      `getConditionThreshold().subtract(getMerchandiseValue())`



---

### merchandiseTotal
- merchandiseTotal: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : The amount of merchandise in the cart contributing towards the condition
      threshold. This will always be less than the condition threshold.



---

## Method Details

### getConditionThreshold()
- getConditionThreshold(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : The amount of merchandise required in the cart in order to receive the
      discount. For an order promotion "Get 15% off orders of $100 or more",
      the condition threshold is $100.00.


    **Returns:**
    - The amount of merchandise required in the cart in order to
              receive the discount.



---

### getDiscount()
- getDiscount(): [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
  - : The discount that the customer will receive if he adds more merchandise
      to the cart. For an order promotion "Get 15% off orders of $100 or more",
      the discount is a PercentageDiscount object.


    **Returns:**
    - The discount that the customer will receive if he adds more
              merchandise to the cart.



---

### getDistanceFromConditionThreshold()
- getDistanceFromConditionThreshold(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Convenience method that returns
      `getConditionThreshold().subtract(getMerchandiseValue())`


    **Returns:**
    - The amount of money needed to add to the order or shipment in
              order to receive the discount.



---

### getMerchandiseTotal()
- getMerchandiseTotal(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : The amount of merchandise in the cart contributing towards the condition
      threshold. This will always be less than the condition threshold.


    **Returns:**
    - The amount of merchandise in the cart contributing towards the
              condition threshold.



---

<!-- prettier-ignore-end -->

<!-- document id=de1a7ef3a9dd77ad84c2e993c27b8499857827834871ebb6896d9599548083ba url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.arguments.md -->

<!-- prettier-ignore-start -->
# Class arguments

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.arguments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.arguments.md)

The arguments of a function.

**See Also:**
- [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)


## Property Summary

| Property | Description |
| --- | --- |
| [callee](#callee): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | A reference to the function that is currently executing. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of arguments passed to the function. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [arguments](#arguments)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### callee
- callee: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : A reference to the function that is currently executing.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of arguments passed to the function.


---

## Constructor Details

### arguments()
- arguments()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=f5904f07bac7757426a1137c9bdee018a77866de6313c7f8b4525d8698d105ff url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Array.md -->

<!-- prettier-ignore-start -->
# Class Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)

An Array of items.


## Property Summary

| Property | Description |
| --- | --- |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The length of the Array. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Array](#array)() | Constructs an Array. |
| [Array](#arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs an Array of the specified  length. |
| [Array](#arrayobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs an Array using the specified values. |

## Method Summary

| Method | Description |
| --- | --- |
| [concat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#concatobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs an Array by concatenating multiple values. |
| [copyWithin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#copywithinnumber-number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies elements within this array. |
| [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#entries)() | Returns an iterator containing all index/value pairs of this array. |
| [every](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#everyfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Returns true if every element in this array satisfies the test  performed in the callback function. |
| [every](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#everyfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if every element in the thisObject argument satisfies the  test performed in the callback function, false otherwise. |
| [fill](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#fillobject-number-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets multiple entries of this array to specific value. |
| [filter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#filterfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Returns a new Array with all of the elements that pass the test  implemented by the callback function. |
| [filter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#filterfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a new Array with all of the elements that pass the test  implemented by the callback function that is run against the  specified Array, thisObject. |
| [find](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#findfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the first value within the array that satisfies the test  defined in the callback function. |
| [findIndex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#findindexfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the index of the first value within the array that satisfies the test  defined in the callback function. |
| [forEach](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#foreachfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Runs the provided callback function once for each element present in  the Array. |
| [forEach](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#foreachfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Runs the provided callback function once for each element present in  the specified Array, thisObject. |
| static [from](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#fromobject-function-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a new array from an array-like object or an [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md). |
| [includes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#includesobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns if the array contains a specific value. |
| [indexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#indexofobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the first index at which a given element can be found in the  array, or -1 if it is not present. |
| [indexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#indexofobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the first index at which a given element can be found in the  array starting at fromIndex, or -1 if it is not present. |
| static [isArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#isarrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Checks if the passed object is an array. |
| [join](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#join)() | Converts all Array elements to Strings and concatenates them. |
| [join](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#joinstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Converts all array elements to Strings and concatenates them. |
| [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#keys)() | Returns an iterator containing all indexes of this array. |
| [lastIndexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#lastindexofobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the last index at which a given element can be found in the  array, or -1 if it is not present. |
| [lastIndexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#lastindexofobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the last index at which a given element can be found in the  array starting at fromIndex, or -1 if it is not present. |
| [map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#mapfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Creates a new Array with the results of calling the specified function  on every element in this Array. |
| [map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#mapfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a new Array with the results of calling the specified function  on every element in the specified Array. |
| static [of](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#ofobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a new array from a variable list of elements. |
| [pop](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#pop)() | Removes and returns the last element of the Array. |
| [push](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#pushobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Appends elements to the Array. |
| [reverse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#reverse)() | Reverses the order of the elements in the Array. |
| [shift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#shift)() | Shifts elements down in the Array and returns the  former first element. |
| [slice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#slicenumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new Array containing a portion of the  Array using the specified start and end positions. |
| [some](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#somefunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Returns true if any of the elements in the Array pass the test  defined in the callback function, false otherwise. |
| [some](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#somefunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if any of the elements in the specified Array pass the test  defined in the callback function, false otherwise. |
| [sort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#sort)() | Sorts the elements of the Array in alphabetical order based on character encoding. |
| [sort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#sortfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Sorts the elements of the Array in alphabetical  order based on character encoding. |
| [splice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#splicenumber-number-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Deletes the specified number of elements from the Array at the specified position,  and then inserts values into the Array at that location. |
| [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#tolocalestring)() | Converts the Array to a localized String. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#tostring)() | Converts the Array to a String. |
| [unshift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#unshiftobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Inserts elements at the beginning of the Array. |
| [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#values)() | Returns an iterator containing all values of this array. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The length of the Array.


---

## Constructor Details

### Array()
- Array()
  - : Constructs an Array.


---

### Array(Number)
- Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs an Array of the specified
      length.


    **Parameters:**
    - length - the length of the Array.


---

### Array(Object...)
- Array(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructs an Array using the specified values.

    **Parameters:**
    - values - zero or more values that are stored in the Array.


---

## Method Details

### concat(Object...)
- concat(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Constructs an Array by concatenating multiple values.

    **Parameters:**
    - values - one or more Array values.

    **Returns:**
    - a new Array containing the concatenated values.


---

### copyWithin(Number, Number, Number)
- copyWithin(target: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Copies elements within this array. The array length is not changed.

    **Parameters:**
    - target - The target of the first element to copy.
    - start - Optional. The first index to copy. Default is 0.
    - end - Optional. The index of the end. This element is not included. Default is copy all to the array end.

    **Returns:**
    - This array.

    **API Version:**
**note:** Available from version 21.2.

---

### entries()
- entries(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator containing all index/value pairs of this array.
      The iterator produces a series of two-element arrays with the first element as the index and the second element as the value.


    **API Version:**
**note:** Available from version 21.2.

---

### every(Function)
- every(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if every element in this array satisfies the test
      performed in the callback function.  The callback function is
      invoked with three arguments: the value of the element,
      the index of the element, and the Array object being traversed.


    **Parameters:**
    - callback - the function to call to determine if every element  in this array satisfies the test defined by the function.  The callback function is  invoked with three arguments: the value of the element,  the index of the element, and the Array object being traversed.

    **Returns:**
    - true if every element in this array satisfies the test
      performed in the callback function.


    **See Also:**
    - [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)


---

### every(Function, Object)
- every(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if every element in the thisObject argument satisfies the
      test performed in the callback function, false otherwise.
      The callback function is invoked with three arguments: the value of the
      element, the index of the element, and the Array object being traversed.


    **Parameters:**
    - callback - the function to call to determine if every element  in this array satisfies the test defined by the function. The callback  function is invoked with three arguments: the value of the element,  the index of the element, and the Array object being traversed.
    - thisObject - the Object to use as 'this' when executing callback.

    **Returns:**
    - true if every element in thisObject satisfies the test
      performed in the callback function, false otherwise.


    **See Also:**
    - [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)


---

### fill(Object, Number, Number)
- fill(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Sets multiple entries of this array to specific value.

    **Parameters:**
    - value - The value to set.
    - start - Optional. The first index to copy. Default is 0.
    - end - Optional. The index of the end. This element is not included. Default is copy all to the array end.

    **Returns:**
    - This array.

    **API Version:**
**note:** Available from version 21.2.

---

### filter(Function)
- filter(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns a new Array with all of the elements that pass the test
      implemented by the callback function. The callback function is
      invoked with three arguments: the value of the element,
      the index of the element, and the Array object being traversed.


    **Parameters:**
    - callback - the function that is called on this Array and  which returns a new Array containing the elements that satisfy the  function's test. The callback function is  invoked with three arguments: the value of the element,  the index of the element, and the Array object being traversed.

    **Returns:**
    - a new Array containing the elements that satisfy the
      function's test.



---

### filter(Function, Object)
- filter(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns a new Array with all of the elements that pass the test
      implemented by the callback function that is run against the
      specified Array, thisObject. The callback function is
      invoked with three arguments: the value of the element,
      the index of the element, and the Array object being traversed.


    **Parameters:**
    - callback - the function that is called on the thisObject Array and  which returns a new Array containing the elements that satisfy the  function's test. The callback function is  invoked with three arguments: the value of the element,  the index of the element, and the Array object being traversed.
    - thisObject - the Object to use as 'this' when executing callback.

    **Returns:**
    - a new Array containing the elements that satisfy the
      function's test.



---

### find(Function, Object)
- find(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the first value within the array that satisfies the test
      defined in the callback function.


    **Parameters:**
    - callback - The function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.
    - thisObject - The object to use as 'this' when executing callback.

    **Returns:**
    - The first value within the array that satisfies the test
      defined in the callback function, `undefined` if no matching value was found.


    **API Version:**
**note:** Available from version 21.2.

---

### findIndex(Function, Object)
- findIndex(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index of the first value within the array that satisfies the test
      defined in the callback function.


    **Parameters:**
    - callback - The function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.
    - thisObject - The object to use as 'this' when executing callback.

    **Returns:**
    - The index of the first value within the array that satisfies the test
      defined in the callback function, `-1` if no matching value was found.


    **API Version:**
**note:** Available from version 21.2.

---

### forEach(Function)
- forEach(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): void
  - : Runs the provided callback function once for each element present in
      the Array. The callback function is invoked only for indexes of the
      Array which have assigned values; it is not invoked for indexes which
      have been deleted or which have never been assigned a value.


    **Parameters:**
    - callback - the function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.


---

### forEach(Function, Object)
- forEach(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Runs the provided callback function once for each element present in
      the specified Array, thisObject. The callback function is invoked only
      for indexes of the Array which have assigned values; it is not invoked
      for indexes which have been deleted or which have never been assigned
      a value.


    **Parameters:**
    - callback - the function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.
    - thisObject - the Object to use as 'this' when executing callback.


---

### from(Object, Function, Object)
- static from(arrayLike: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), mapFn: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Creates a new array from an array-like object or an [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md).

    **Parameters:**
    - arrayLike - An array-like object or an iterable that provides the elements for the new array.
    - mapFn - Optional. A function that maps the input elements into the value for the new array.
    - thisObject - Optional. The Object to use as 'this' when executing mapFn.

    **Returns:**
    - The newly created array.

    **API Version:**
**note:** Available from version 21.2.

---

### includes(Object, Number)
- includes(valueToFind: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), fromIndex: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the array contains a specific value.

    **Parameters:**
    - valueToFind - The value to look for.
    - fromIndex - Optional. The index to start from.

    **Returns:**
    - `true` if the value is found in the array else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### indexOf(Object)
- indexOf(elementToLocate: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the first index at which a given element can be found in the
      array, or -1 if it is not present.


    **Parameters:**
    - elementToLocate - the element to locate in the Array.

    **Returns:**
    - the index of the element or -1 if it is no preset.


---

### indexOf(Object, Number)
- indexOf(elementToLocate: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), fromIndex: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the first index at which a given element can be found in the
      array starting at fromIndex, or -1 if it is not present.


    **Parameters:**
    - elementToLocate - the element to locate in the Array.
    - fromIndex - the index from which to start looking for the element.

    **Returns:**
    - the index of the element or -1 if it is no preset.


---

### isArray(Object)
- static isArray(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks if the passed object is an array.

    **Parameters:**
    - object - The object to ckeck.

    **Returns:**
    - `true` if the passed object is an array else `false`.


---

### join()
- join(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts all Array elements to Strings and concatenates them.

    **Returns:**
    - a concatenated list of all Array elements as a String.


---

### join(String)
- join(separator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts all array elements to Strings and concatenates them.

    **Parameters:**
    - separator - an optional character or string used to separate one element  of the Array from the next element in the return String.

    **Returns:**
    - a concatenated list of all Array elements as a String where the
      specified delimiter is used to separate elements.



---

### keys()
- keys(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator containing all indexes of this array.

    **API Version:**
**note:** Available from version 21.2.

---

### lastIndexOf(Object)
- lastIndexOf(elementToLocate: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the last index at which a given element can be found in the
      array, or -1 if it is not present. The array is searched backwards.


    **Parameters:**
    - elementToLocate - the element to locate in the Array.

    **Returns:**
    - the index of the element or -1 if it is no preset.


---

### lastIndexOf(Object, Number)
- lastIndexOf(elementToLocate: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), fromIndex: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the last index at which a given element can be found in the
      array starting at fromIndex, or -1 if it is not present.
      The array is searched backwards.


    **Parameters:**
    - elementToLocate - the element to locate in the Array.
    - fromIndex - the index from which to start looking for the element.  The array is searched backwards.

    **Returns:**
    - the index of the element or -1 if it is no present.


---

### map(Function)
- map(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Creates a new Array with the results of calling the specified function
      on every element in this Array. The callback function is invoked only
      for indexes of the Array which have assigned values; it is not invoked
      for indexes which have been deleted or which have never been assigned
      values.


    **Parameters:**
    - callback - the function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.

    **Returns:**
    - a new Array with the results of calling the specified function
      on every element in this Array.



---

### map(Function, Object)
- map(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Creates a new Array with the results of calling the specified function
      on every element in the specified Array. The callback function is invoked only
      for indexes of the Array which have assigned values; it is not invoked
      for indexes which have been deleted or which have never been assigned
      values.


    **Parameters:**
    - callback - the function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.
    - thisObject - the Object to use as 'this' when executing callback.

    **Returns:**
    - a new Array with the results of calling the specified function
      on every element in this Array.



---

### of(Object...)
- static of(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Creates a new array from a variable list of elements.

    **Parameters:**
    - values - The array values.

    **Returns:**
    - The newly created array.

    **API Version:**
**note:** Available from version 21.2.

---

### pop()
- pop(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Removes and returns the last element of the Array.

    **Returns:**
    - the last element of the Array.


---

### push(Object...)
- push(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Appends elements to the Array.

    **Parameters:**
    - values - one or more values that will be appended to the Array.

    **Returns:**
    - the new length of the Array.


---

### reverse()
- reverse(): void
  - : Reverses the order of the elements in the Array.


---

### shift()
- shift(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Shifts elements down in the Array and returns the
      former first element.


    **Returns:**
    - the former first element.


---

### slice(Number, Number)
- slice(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns a new Array containing a portion of the
      Array using the specified start and end positions.


    **Parameters:**
    - start - the location in the Array to start the slice  operation.
    - end - the location in the Array to stop the slice  operation.

    **Returns:**
    - a new Array containing the members bound by
      start and end.



---

### some(Function)
- some(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if any of the elements in the Array pass the test
      defined in the callback function, false otherwise.


    **Parameters:**
    - callback - the function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.

    **Returns:**
    - true if any of the elements in the Array pass the test
      defined in the callback function, false otherwise.



---

### some(Function, Object)
- some(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if any of the elements in the specified Array pass the test
      defined in the callback function, false otherwise.


    **Parameters:**
    - callback - the function to call, which is invoked with three  arguments: the value of the element, the index of the element, and the  Array object being traversed.
    - thisObject - the Object to use as 'this' when executing callback.

    **Returns:**
    - true if any of the elements in the Array pass the test
      defined in the callback function, false otherwise.



---

### sort()
- sort(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Sorts the elements of the Array in alphabetical order based on character encoding.
      
      
      This sort is guaranteed to be _stable_: equal elements will not be reordered as a result of the sort.


    **Returns:**
    - a reference to the Array.


---

### sort(Function)
- sort(function: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Sorts the elements of the Array in alphabetical
      order based on character encoding.
      
      
      
      This sort is guaranteed to be _stable_: equal elements will not be reordered as a result of the sort.


    **Parameters:**
    - function - a Function used to specify the sorting  order.

    **Returns:**
    - a reference to the Array.

    **See Also:**
    - [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)


---

### splice(Number, Number, Object...)
- splice(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), deleteCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Deletes the specified number of elements from the Array at the specified position,
      and then inserts values into the Array at that location.


    **Parameters:**
    - start - the start location.
    - deleteCount - the number of items to delete.
    - values - zero or more values to be inserted into the Array.


---

### toLocaleString()
- toLocaleString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts the Array to a localized String.

    **Returns:**
    - a localized String representing the Array.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts the Array to a String.

    **Returns:**
    - a String representation of the Array.


---

### unshift(Object...)
- unshift(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Inserts elements at the beginning of the Array.

    **Parameters:**
    - values - one or more vales that will be inserted  into the beginning of the Array.

    **Returns:**
    - the new length of the Array.


---

### values()
- values(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator containing all values of this array.

    **API Version:**
**note:** Available from version 21.2.

---

<!-- prettier-ignore-end -->

<!-- document id=4cddb464ce5918d36718e0dd3fe90c0493c5e5e5764a58ccfef3cca265cb323a url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.ArrayBuffer.md -->

<!-- prettier-ignore-start -->
# Class ArrayBuffer

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)

The ArrayBuffer represents a generic array of bytes with fixed length. 

To access and manipulate content, use [DataView](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md) or a typed array.


**API Version:**
**note:** Available from version 21.2.

## Property Summary

| Property | Description |
| --- | --- |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ArrayBuffer](#arraybuffer)() | Creates an empty array buffer. |
| [ArrayBuffer](#arraybuffernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array buffer with the given number of bytes. |

## Method Summary

| Method | Description |
| --- | --- |
| static [isView](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md#isviewobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if the given object is one of the views for an ArrayBuffer, such as a typed array or a [DataView](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md). |
| [slice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md#slicenumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array buffer with a copy of the data of this buffer. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer.


---

## Constructor Details

### ArrayBuffer()
- ArrayBuffer()
  - : Creates an empty array buffer.


---

### ArrayBuffer(Number)
- ArrayBuffer(byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array buffer with the given number of bytes.

    **Parameters:**
    - byteLength - The number of bytes.


---

## Method Details

### isView(Object)
- static isView(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the given object is one of the views for an ArrayBuffer, such as a typed array or a [DataView](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md).

    **Parameters:**
    - object - The object to check.

    **Returns:**
    - `true` if the passed object is a view to an array buffer else return false.


---

### slice(Number, Number)
- slice(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : Returns a new array buffer with a copy of the data of this buffer.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=5804f706a080e131d935f9d78f2ee30dbb57ef055fcd94021bb209beae5f41bf url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.ArrayList.md -->

<!-- prettier-ignore-start -->
# Class ArrayList

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
    - [dw.util.List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
      - [dw.util.ArrayList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.ArrayList.md)

The ArrayList class is a container for a list of objects.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ArrayList](#arraylist)() | Constructor for a new ArrayList. |
| [ArrayList](#arraylistcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Constructor for a new ArrayList. |
| [ArrayList](#arraylistiterator)([Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)) | Constructor for a new ArrayList. |
| [ArrayList](#arraylistobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructor for a new ArrayList. |

## Method Summary

| Method | Description |
| --- | --- |
| [clone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.ArrayList.md#clone)() | Returns a shallow copy of this array list. |

### Methods inherited from class List

[addAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#addatnumber-object), [concat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#concatobject), [fill](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#fillobject), [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#getnumber), [indexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#indexofobject), [join](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#join), [join](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#joinstring), [lastIndexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#lastindexofobject), [pop](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#pop), [push](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#pushobject), [removeAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#removeatnumber), [replaceAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#replaceallobject-object), [reverse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#reverse), [rotate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#rotatenumber), [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#setnumber-object), [shift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#shift), [shuffle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#shuffle), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#size), [slice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#slicenumber), [slice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#slicenumber-number), [sort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#sort), [sort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#sortobject), [subList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#sublistnumber-number), [swap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#swapnumber-number), [unshift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#unshiftobject)
### Methods inherited from class Collection

[add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject), [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object), [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection), [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear), [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject), [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty), [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject), [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection), [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### ArrayList()
- ArrayList()
  - : Constructor for a new ArrayList.


---

### ArrayList(Collection)
- ArrayList(collection: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))
  - : Constructor for a new ArrayList. The constructor initializes the
      ArrayList with the elements of the given collection.


    **Parameters:**
    - collection - the elements to insert into the list.


---

### ArrayList(Iterator)
- ArrayList(iterator: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md))
  - : Constructor for a new ArrayList. The constructor initializes the
      ArrayList with the elements of the given iterator.


    **Parameters:**
    - iterator - the iterator that provides access to the elements to insert             into the list.


---

### ArrayList(Object...)
- ArrayList(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructor for a new ArrayList. The constructor initializes the
      ArrayList with the arguments given as constructor parameters. The method
      can also be called with an ECMA array as argument.
      
      If called with a single ECMA array as argument the individual elements of
      that array are used to initialize the ArrayList. To create an ArrayList
      with a single array as element, create an empty ArrayList and then call
      the method add1() on it.


    **Parameters:**
    - values - the set of objects to insert into the list.


---

## Method Details

### clone()
- clone(): [ArrayList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.ArrayList.md)
  - : Returns a shallow copy of this array list.

    **Returns:**
    - a shallow copy of this array list.


---

<!-- prettier-ignore-end -->

<!-- document id=01bf025449709fb7f5da4bd32c2619314a67068e5e58595319a5a883522555a5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.AspectAttributeValidationException.md -->

<!-- prettier-ignore-start -->
# Class AspectAttributeValidationException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.AspectAttributeValidationException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.AspectAttributeValidationException.md)

This APIException is thrown by method [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)
and [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)
to indicate that the passed aspect attributes failed during validation against the
definition provided through the aspect type of the page.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=22ac9dfae0a32e81ab45162184977d3ef92cd71d6cc2cfe02727323bab5778ae url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Assert.md -->

<!-- prettier-ignore-start -->
# Class Assert

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Assert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md)

The Assert class provides utility methods for assertion events.


## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [areEqual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#areequalobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion  if the specified objects are not equal. |
| static [areEqual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#areequalobject-object-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified objects are not equal. |
| static [areNotEqual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#arenotequalobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion  if the specified objects are equal. |
| static [areNotEqual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#arenotequalobject-object-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified objects are equal. |
| static [areSame](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#aresameobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion  if the specified objects are not the same. |
| static [areSame](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#aresameobject-object-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified objects are not the same. |
| static [fail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#fail)() | Propagates a failure assertion. |
| static [fail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#failstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates a failure assertion using the  specified message. |
| static [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isemptyobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion  if the specified check does not evaluate to  an empty object. |
| static [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isemptyobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified check does not evaluate to  an empty object. |
| static [isFalse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isfalseboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Propagates an assertion if the  specified check does not evaluate to false. |
| static [isFalse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isfalseboolean-string)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified check does not evaluate to false. |
| static [isInstanceOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isinstanceofobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion if the specified object 'arg' is not an instance  of the specified class 'clazz'. |
| static [isInstanceOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isinstanceofobject-object-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified object is not an instance of the specified class. |
| static [isNotEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isnotemptyobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion  if the specified object is empty. |
| static [isNotEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isnotemptyobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified object is empty. |
| static [isNotNull](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isnotnullobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion if the  specified object is null. |
| static [isNotNull](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isnotnullobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified object is null. |
| static [isNull](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isnullobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Propagates an assertion  if the specified object is not null. |
| static [isNull](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#isnullobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified object is not null. |
| static [isTrue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#istrueboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Propagates an assertion if the  specified check does not evaluate to true. |
| static [isTrue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md#istrueboolean-string)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Propagates an assertion using the specified message  if the specified check does not evaluate to true. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### areEqual(Object, Object)
- static areEqual(arg1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion
      if the specified objects are not equal.


    **Parameters:**
    - arg1 - the first object to check.
    - arg2 - the second object to check.


---

### areEqual(Object, Object, String)
- static areEqual(arg1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified objects are not equal.


    **Parameters:**
    - arg1 - the first object to check.
    - arg2 - the second object to check.
    - msg - the assertion message.


---

### areNotEqual(Object, Object)
- static areNotEqual(arg1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion
      if the specified objects are equal.


    **Parameters:**
    - arg1 - the first object to check.
    - arg2 - the second object to check.


---

### areNotEqual(Object, Object, String)
- static areNotEqual(arg1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified objects are equal.


    **Parameters:**
    - arg1 - the first object to check.
    - arg2 - the second object to check.
    - msg - the assertion message.


---

### areSame(Object, Object)
- static areSame(arg1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion
      if the specified objects are not the same.


    **Parameters:**
    - arg1 - the first object to check.
    - arg2 - the second object to check.


---

### areSame(Object, Object, String)
- static areSame(arg1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified objects are not the same.


    **Parameters:**
    - arg1 - the first object to check.
    - arg2 - the second object to check.
    - msg - the assertion message.


---

### fail()
- static fail(): void
  - : Propagates a failure assertion.


---

### fail(String)
- static fail(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates a failure assertion using the
      specified message.


    **Parameters:**
    - msg - the assertion message.


---

### isEmpty(Object)
- static isEmpty(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion
      if the specified check does not evaluate to
      an empty object.


    **Parameters:**
    - arg - the object to check.


---

### isEmpty(Object, String)
- static isEmpty(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified check does not evaluate to
      an empty object.


    **Parameters:**
    - arg - the object to check.
    - msg - the assertion message.


---

### isFalse(Boolean)
- static isFalse(check: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Propagates an assertion if the
      specified check does not evaluate to false.


    **Parameters:**
    - check - the condition to check.


---

### isFalse(Boolean, String)
- static isFalse(check: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified check does not evaluate to false.


    **Parameters:**
    - check - the condition to check.
    - msg - the assertion message.


---

### isInstanceOf(Object, Object)
- static isInstanceOf(clazz: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion if the specified object 'arg' is not an instance
      of the specified class 'clazz'.
      
      
      For example, the following call does not propagate an assertion:
      
      ```
      
          var test = new dw.util.HashMap();
          dw.util.Assert.isInstanceOf(dw.util.HashMap, test);
      ```
      
      
      
      But the following call will propagate an assertion:
      
      ```
      
          var test = new dw.util.Set();
          dw.util.Assert.isInstanceOf(dw.util.HashMap, test);
      ```
      
      
      
      Note that 'clazz' can only be a Demandware API Scripting class.


    **Parameters:**
    - clazz - the scripting class to use to check the object.
    - arg - the object to check.


---

### isInstanceOf(Object, Object, String)
- static isInstanceOf(clazz: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified object is not an instance of the specified class.
      
      
      For example, the following call does not propagate an assertion:
      
      ```
      
          var test = new dw.util.HashMap();
          dw.util.Assert.isInstanceOf(dw.util.HashMap, test);
      ```
      
      
      
      But the following call will propagate an assertion:
      
      ```
      
          var test = new dw.util.Set();
          dw.util.Assert.isInstanceOf(dw.util.HashMap, test);
      ```
      
      
      
      Note that 'clazz' can only be a Demandware API Scripting class.


    **Parameters:**
    - clazz - the scripting class to use to check the object.
    - arg - the object to check.
    - msg - the assertion message.


---

### isNotEmpty(Object)
- static isNotEmpty(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion
      if the specified object is empty.


    **Parameters:**
    - arg - the object to check.


---

### isNotEmpty(Object, String)
- static isNotEmpty(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified object is empty.


    **Parameters:**
    - arg - the object to check.
    - msg - the assertion message.


---

### isNotNull(Object)
- static isNotNull(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion if the
      specified object is null.


    **Parameters:**
    - arg - the object to check.


---

### isNotNull(Object, String)
- static isNotNull(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified object is null.


    **Parameters:**
    - arg - the object to check.
    - msg - the assertion message.


---

### isNull(Object)
- static isNull(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Propagates an assertion
      if the specified object is not null.


    **Parameters:**
    - arg - the object to check.


---

### isNull(Object, String)
- static isNull(arg: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified object is not null.


    **Parameters:**
    - arg - the object to check.
    - msg - the assertion message.


---

### isTrue(Boolean)
- static isTrue(check: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Propagates an assertion if the
      specified check does not evaluate to true.


    **Parameters:**
    - check - the condition to check.


---

### isTrue(Boolean, String)
- static isTrue(check: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Propagates an assertion using the specified message
      if the specified check does not evaluate to true.


    **Parameters:**
    - check - the condition to check.
    - msg - the assertion message.


---

<!-- prettier-ignore-end -->

<!-- document id=a7e0e6d37987fe817f29c511e48924df7d1fc984600d616cf61fa3724d9b5015 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.AuthenticationStatus.md -->

<!-- prettier-ignore-start -->
# Class AuthenticationStatus

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.AuthenticationStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md)

Holds the status of an authentication process.


## Constant Summary

| Constant | Description |
| --- | --- |
| [AUTH_OK](#auth_ok): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTH_OK" | Authentication was successful |
| [ERROR_CUSTOMER_DISABLED](#error_customer_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_CUSTOMER_DISABLED" | customer could be found, but is disabled. |
| [ERROR_CUSTOMER_LOCKED](#error_customer_locked): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_CUSTOMER_LOCKED" | customer could be found, but is locked (too many failed login attempts). |
| [ERROR_CUSTOMER_NOT_FOUND](#error_customer_not_found): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_CUSTOMER_NOT_FOUND" | customer could not be found |
| [ERROR_PASSWORD_EXPIRED](#error_password_expired): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_PASSWORD_EXPIRED" | Password does match, but is expired. |
| [ERROR_PASSWORD_MISMATCH](#error_password_mismatch): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_PASSWORD_MISMATCH" | the used password is not correct |
| [ERROR_UNKNOWN](#error_unknown): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_UNKNOWN" | Any other error |

## Property Summary

| Property | Description |
| --- | --- |
| [authenticated](#authenticated): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | checks whether the authentication was successful or not |
| [customer](#customer): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)` | The customer, corresponding to the login used during authentication. |
| [status](#status): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | the status code (see the constants above) |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md#getcustomer)() | The customer, corresponding to the login used during authentication. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md#getstatus)() | the status code (see the constants above) |
| [isAuthenticated](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md#isauthenticated)() | checks whether the authentication was successful or not |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### AUTH_OK

- AUTH_OK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTH_OK"
  - : Authentication was successful


---

### ERROR_CUSTOMER_DISABLED

- ERROR_CUSTOMER_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_CUSTOMER_DISABLED"
  - : customer could be found, but is disabled. Password was not verified.


---

### ERROR_CUSTOMER_LOCKED

- ERROR_CUSTOMER_LOCKED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_CUSTOMER_LOCKED"
  - : customer could be found, but is locked (too many failed login attempts). Password was verified before.


---

### ERROR_CUSTOMER_NOT_FOUND

- ERROR_CUSTOMER_NOT_FOUND: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_CUSTOMER_NOT_FOUND"
  - : customer could not be found


---

### ERROR_PASSWORD_EXPIRED

- ERROR_PASSWORD_EXPIRED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_PASSWORD_EXPIRED"
  - : Password does match, but is expired.


---

### ERROR_PASSWORD_MISMATCH

- ERROR_PASSWORD_MISMATCH: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_PASSWORD_MISMATCH"
  - : the used password is not correct


---

### ERROR_UNKNOWN

- ERROR_UNKNOWN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR_UNKNOWN"
  - : Any other error


---

## Property Details

### authenticated
- authenticated: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : checks whether the authentication was successful or not


---

### customer
- customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)`
  - : The customer, corresponding to the login used during authentication. This customer is not logged in after authentication.


---

### status
- status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : the status code (see the constants above)


---

## Method Details

### getCustomer()
- getCustomer(): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : The customer, corresponding to the login used during authentication. This customer is not logged in after authentication.

    **Returns:**
    - the customer described by the login


---

### getStatus()
- getStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : the status code (see the constants above)

    **Returns:**
    - the status code


---

### isAuthenticated()
- isAuthenticated(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : checks whether the authentication was successful or not

    **Returns:**
    - the when the authentication was successful


---

<!-- prettier-ignore-end -->

<!-- document id=3ccc0f4f4d0213815150b000f63f83a5679bc15341ea2389b6c6b6775566beb8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.Basket.md -->

<!-- prettier-ignore-start -->
# Class Basket

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)
        - [dw.order.Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)

The Basket class represents a shopping cart.


## Property Summary

| Property | Description |
| --- | --- |
| [agentBasket](#agentbasket): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns if the basket was created by an agent. |
| [inventoryReservationExpiry](#inventoryreservationexpiry): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the timestamp when the inventory for this basket expires. |
| [orderBeingEdited](#orderbeingedited): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)` | Returns the order that this basket represents if the basket is being used to edit an order, otherwise this method  returns null. |
| [orderNoBeingEdited](#ordernobeingedited): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the number of the order that this basket represents if the basket is being used to edit an order,  otherwise this method returns null. |
| [taxRoundedAtGroup](#taxroundedatgroup): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Use this method to check if the Basket was calculated with grouped taxation calculation. |
| [temporary](#temporary): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns if the basket is temporary. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getInventoryReservationExpiry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#getinventoryreservationexpiry)() | Returns the timestamp when the inventory for this basket expires. |
| [getOrderBeingEdited](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#getorderbeingedited)() | Returns the order that this basket represents if the basket is being used to edit an order, otherwise this method  returns null. |
| [getOrderNoBeingEdited](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#getordernobeingedited)() | Returns the number of the order that this basket represents if the basket is being used to edit an order,  otherwise this method returns null. |
| [isAgentBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#isagentbasket)() | Returns if the basket was created by an agent. |
| [isTaxRoundedAtGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#istaxroundedatgroup)() | Use this method to check if the Basket was calculated with grouped taxation calculation. |
| [isTemporary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#istemporary)() | Returns if the basket is temporary. |
| [releaseInventory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#releaseinventory)() | <p>  Release all inventory previously reserved for this basket. |
| [reserveInventory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventory)() | <p>  Reserves inventory for all items in this basket for 10 minutes. |
| [reserveInventory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventorynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | <p>  Reserve inventory for all items in this basket for 10 minutes. |
| [reserveInventory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventorynumber-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | <p>  Reserve inventory for all items in this basket for 10 minutes. |
| [setBusinessType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#setbusinesstypenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the type of the business this order has been placed in.<br/>  Possible values are [LineItemCtnr.BUSINESS_TYPE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2c) or [LineItemCtnr.BUSINESS_TYPE_B2B](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2b). |
| [setChannelType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#setchanneltypenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the channel type in which sales channel this order has been created. |
| ~~[setCustomerNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#setcustomernostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the customer number of the customer associated with this container. |
| [startCheckout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#startcheckout)() | Register a "start checkout" event for the current basket. |
| [updateCurrency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#updatecurrency)() | Updates the basket currency if different to session currency, otherwise does nothing. |

### Methods inherited from class LineItemCtnr

[addNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#addnotestring-string), [createBillingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbillingaddress), [createBonusProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbonusproductlineitembonusdiscountlineitem-product-productoptionmodel-shipment), [createCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring), [createCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring-boolean), [createGiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#creategiftcertificatelineitemnumber-string), [createGiftCertificatePaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#creategiftcertificatepaymentinstrumentstring-money), [createPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpaymentinstrumentstring-money), [createPaymentInstrumentFromWallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpaymentinstrumentfromwalletcustomerpaymentinstrument-money), [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring), [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring-discount), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemproduct-productoptionmodel-shipment), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemproductlistitem-shipment), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-shipment), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-quantity-shipment), [createShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createshipmentstring), [createShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createshippingpriceadjustmentstring), [getAdjustedMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalgrossprice), [getAdjustedMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalnetprice), [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalprice), [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalpriceboolean), [getAdjustedMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotaltax), [getAdjustedShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalgrossprice), [getAdjustedShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalnetprice), [getAdjustedShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalprice), [getAdjustedShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotaltax), [getAllGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallgiftcertificatelineitems), [getAllLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getalllineitems), [getAllProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductlineitems), [getAllProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductlineitemsstring), [getAllProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductquantities), [getAllShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallshippingpriceadjustments), [getBillingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbillingaddress), [getBonusDiscountLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbonusdiscountlineitems), [getBonusLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbonuslineitems), [getBusinessType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbusinesstype), [getChannelType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getchanneltype), [getCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcouponlineitemstring), [getCouponLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcouponlineitems), [getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcurrencycode), [getCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomer), [getCustomerEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomeremail), [getCustomerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomername), [getCustomerNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomerno), [getDefaultShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getdefaultshipment), [getEtag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getetag), [getGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitems), [getGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitemsstring), [getGiftCertificatePaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstruments), [getGiftCertificatePaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstrumentsstring), [getGiftCertificateTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalgrossprice), [getGiftCertificateTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalnetprice), [getGiftCertificateTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalprice), [getGiftCertificateTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotaltax), [getMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalgrossprice), [getMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalnetprice), [getMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalprice), [getMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotaltax), [getNotes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getnotes), [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstrument), [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstruments), [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstrumentsstring), [getPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpriceadjustmentbypromotionidstring), [getPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpriceadjustments), [getProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductlineitems), [getProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductlineitemsstring), [getProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantities), [getProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitiesboolean), [getProductQuantityTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitytotal), [getShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshipmentstring), [getShipments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshipments), [getShippingPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustmentbypromotionidstring), [getShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustments), [getShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalgrossprice), [getShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalnetprice), [getShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalprice), [getShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotaltax), [getTaxTotalsPerTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettaxtotalspertaxrate), [getTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotalgrossprice), [getTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotalnetprice), [getTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotaltax), [isExternallyTaxed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#isexternallytaxed), [isTaxRoundedAtGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#istaxroundedatgroup), [removeAllPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeallpaymentinstruments), [removeBonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removebonusdiscountlineitembonusdiscountlineitem), [removeCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removecouponlineitemcouponlineitem), [removeGiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removegiftcertificatelineitemgiftcertificatelineitem), [removeNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removenotenote), [removePaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removepaymentinstrumentpaymentinstrument), [removePriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removepriceadjustmentpriceadjustment), [removeProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeproductlineitemproductlineitem), [removeShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshipmentshipment), [removeShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshippingpriceadjustmentpriceadjustment), [setCustomerEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#setcustomeremailstring), [setCustomerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#setcustomernamestring), [updateOrderLevelPriceAdjustmentTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#updateorderlevelpriceadjustmenttax), [updateTotals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#updatetotals), [verifyPriceAdjustmentLimits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#verifypriceadjustmentlimits)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### agentBasket
- agentBasket: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns if the basket was created by an agent.
      
      
      An agent basket is created by an agent on behalf of the customer in comparison to a storefront basket which is
      created by the customer e.g. in the storefront. An agent basket can be created with
      [BasketMgr.createAgentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createagentbasket).



---

### inventoryReservationExpiry
- inventoryReservationExpiry: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the timestamp when the inventory for this basket expires.
      
      
      It will return `null` for the following reasons:
      
      - No reservation for the basket was done
      - Reservation is outdated meaning the timestamp is in the past
      
      
      
      
      
      Please note that the expiry timestamp will not always be valid for the whole basket. It will not be valid for
      new items added or items whose quantity has changed after the reservation was done.



---

### orderBeingEdited
- orderBeingEdited: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)`
  - : Returns the order that this basket represents if the basket is being used to edit an order, otherwise this method
      returns null. Baskets created via [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder) will create a reference
      to the order that was used to create this basket (please check limitations around basket accessibility in
      [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)).



---

### orderNoBeingEdited
- orderNoBeingEdited: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the number of the order that this basket represents if the basket is being used to edit an order,
      otherwise this method returns null. Baskets created via [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)
      will create a reference to the order that was used to create this basket (please check limitations around basket
      accessibility in [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)).



---

### taxRoundedAtGroup
- taxRoundedAtGroup: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Use this method to check if the Basket was calculated with grouped taxation calculation.
      
      
      If the tax is rounded on group level, the tax is applied to the summed-up tax basis for each tax rate.



---

### temporary
- temporary: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns if the basket is temporary.
      
      
      Temporary baskets are separate from shopper storefront and agent baskets, and are intended for use to perform
      calculations or create an order without disturbing a shopper's open storefront basket. A temporary basket can be
      created with [BasketMgr.createTemporaryBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createtemporarybasket).



---

## Method Details

### getInventoryReservationExpiry()
- getInventoryReservationExpiry(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the timestamp when the inventory for this basket expires.
      
      
      It will return `null` for the following reasons:
      
      - No reservation for the basket was done
      - Reservation is outdated meaning the timestamp is in the past
      
      
      
      
      
      Please note that the expiry timestamp will not always be valid for the whole basket. It will not be valid for
      new items added or items whose quantity has changed after the reservation was done.


    **Returns:**
    - the inventory reservation expiry timestamp or `null`


---

### getOrderBeingEdited()
- getOrderBeingEdited(): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Returns the order that this basket represents if the basket is being used to edit an order, otherwise this method
      returns null. Baskets created via [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder) will create a reference
      to the order that was used to create this basket (please check limitations around basket accessibility in
      [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)).


    **Returns:**
    - the order that this basket represents if the basket is being used to edit an order, otherwise this method
              returns null.



---

### getOrderNoBeingEdited()
- getOrderNoBeingEdited(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the number of the order that this basket represents if the basket is being used to edit an order,
      otherwise this method returns null. Baskets created via [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)
      will create a reference to the order that was used to create this basket (please check limitations around basket
      accessibility in [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)).


    **Returns:**
    - the number of the order that this basket represents if the basket is being used to edit an order,
              otherwise this method returns null.



---

### isAgentBasket()
- isAgentBasket(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the basket was created by an agent.
      
      
      An agent basket is created by an agent on behalf of the customer in comparison to a storefront basket which is
      created by the customer e.g. in the storefront. An agent basket can be created with
      [BasketMgr.createAgentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createagentbasket).


    **Returns:**
    - `true` if the basket was created by an agent otherwise `false`


---

### isTaxRoundedAtGroup()
- isTaxRoundedAtGroup(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Use this method to check if the Basket was calculated with grouped taxation calculation.
      
      
      If the tax is rounded on group level, the tax is applied to the summed-up tax basis for each tax rate.


    **Returns:**
    - `true` if the Basket was calculated with grouped taxation


---

### isTemporary()
- isTemporary(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the basket is temporary.
      
      
      Temporary baskets are separate from shopper storefront and agent baskets, and are intended for use to perform
      calculations or create an order without disturbing a shopper's open storefront basket. A temporary basket can be
      created with [BasketMgr.createTemporaryBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createtemporarybasket).


    **Returns:**
    - `true` if the basket is temporary otherwise `false`


---

### releaseInventory()
- releaseInventory(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Release all inventory previously reserved for this basket. This is not needed for a normal workflow.
      You can call `dw.order.Basket.reserveInventory()` one time after every basket change.
      For performance and scaling reasons, avoid calling `dw.order.Basket.releaseInventory()`
      before `dw.order.Basket.reserveInventory()`. The `reserveInventory` function works in
      an optimized way to release inventory reservations that are no longer relevant.
      
      
      
      
      The method implements its own transaction handling. Calling the method from inside a transaction is disallowed
      and results in an exception being thrown. This behavior differs when calling the method from an **OCAPI
       hook**. OCAPI hooks handle transactions themselves, so in this case there is also no need to do any transaction
      handling, but to ensure the shortest possible locking of the inventory this method should only be called _as
       the last step_ in the OCAPI hook.


    **Returns:**
    - a Status instance with - Status.OK if release inventory was successful, otherwise Status.ERROR.


---

### reserveInventory()
- reserveInventory(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Reserves inventory for all items in this basket for 10 minutes. Any reservations created by previous calls of
      this method are replaced.
      
      
      
      
      Sample workflow for subsequent basket reservations:
      
      
      
      
      1. Request: Add item to basket and reserve the basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.createProductLineItem("sku1",2,basket.defaultShipment)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku1:2} is complete.
      ```
      
      
      
      
      
      2. Request: Add item to basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.createProductLineItem("sku2",2,basket.defaultShipment)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku1:2, sku2:2} is complete. The previous reservation was overwritten.
      ```
      
      
      
      
      
      3. Request: Remove item from basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.removeProductLineItem(item1)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku2:2} is complete. The previous reservation was
         // overwritten and a quantity of 2 is released for sku1.
      ```
      
      
      
      
      
      The method can be used to reserve basket items before checkout to ensure that inventory is still available at the
      time an order is created from the basket using [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket). If all or some
      basket items are not reserved before creating an order, [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) will
      validate item availability and will fail if any item is unavailable. Calling this method in the same request as
      [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) is unnecessary and discouraged for performance reasons.
      
      
      
      
      The maximum quantity that can be reserved at one time is equal to the ATS (Available To Sell) quantity. (See
      [ProductInventoryRecord.getATS()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getats).)
      
      
      
      
      When using B2C Commerce inventory, reserving basket inventory does not reduce ATS. In this case, converting the
      basket to an order reduces ATS by the reserved amount. For example, consider a product with an ATS quantity of 5
      and no reservations. If a basket reserves a quantity of 3, then other baskets still see an ATS of 5 but can only
      reserve a quantity of 2.
      
      
      
      
      When using Omnichannel Inventory, reserving basket inventory reduces ATS. In this case, converting the basket to
      an order doesn't reduce ATS. In the previous example, after the first basket reserved a quantity of 3, other
      baskets would see an ATS of 2.
      
      
      
      
      Reservations can only be made for products with an inventory record. The reservation of product bundles is
      controlled by the _Use Bundle Inventory Only_ setting on the inventory list. The setting allows inventory to
      be reserved for just the bundle or for the bundle and its bundled products.
      
      
      
      
      The following conditions must be met for the method to succeed:
      
      - an inventory list must be assigned to the current site
      - all products in the basket must exist, and must not be of type Master or ProductSet
      - each product line item must have a valid quantity
      - each product must have an inventory record, or the inventory list must define that products without inventory  record are available by default
      - the reservation must succeed for each item as described above.
      
      
      
      
      
      The method implements its own transaction handling. Calling the method from inside a transaction is disallowed
      and results in an exception being thrown. This behavior differs when calling the method from an **OCAPI
       hook**. OCAPI hooks handle transactions themselves, so in this case there is also no need to do any transaction
      handling, but to ensure the shortest possible locking of the inventory this method should only be called _as
       the last step_ in the OCAPI hook.
      
      
      
      
      If the reservation fails with an ERROR status, existing valid reservations for the basket will remain unchanged
      but no new reservations will be made. This might lead to a partially reserved basket.
      
      
      
      
      Behaves same as `reserveInventory( null, false );`.
      
      
      
      
      This method must not be used with
      
      - the **CreateOrder2**pipelet, or
      - [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket), or
      - [OrderMgr.createOrder(Basket, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket-string)
      
      in the same request.


    **Returns:**
    - a Status instance with - Status.OK if all items could be reserved, otherwise Status.ERROR meaning no
              items were reserved.



---

### reserveInventory(Number)
- reserveInventory(reservationDurationInMinutes: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Reserve inventory for all items in this basket for 10 minutes. Any reservations created by previous calls of
      this method are replaced.
      
      
      
      
      Sample workflow for subsequent basket reservations:
      
      
      
      
      1. Request: Add item to basket and reserve the basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.createProductLineItem("sku1",2,basket.defaultShipment)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku1:2} is complete.
      ```
      
      
      
      
      
      2. Request: Add item to basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.createProductLineItem("sku2",2,basket.defaultShipment)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku1:2, sku2:2} is complete. The previous reservation was overwritten.
      ```
      
      
      
      
      
      3. Request: Remove item from basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.removeProductLineItem(item1)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku2:2} is complete. The previous reservation was
         // overwritten and a quantity of 2 is released for sku1.
      ```
      
      
      
      
      
      The method can be used to reserve basket items before checkout to ensure that inventory is still available at the
      time an order is created from the basket using [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket). If all or some
      basket items are not reserved before creating an order, [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) will
      validate item availability and will fail if any item is unavailable. Calling this method in the same request as
      [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) is unnecessary and discouraged for performance reasons.
      
      
      
      
      The maximum quantity that can be reserved at one time is equal to the ATS (Available To Sell) quantity. (See
      [ProductInventoryRecord.getATS()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getats).)
      
      
      
      
      When using B2C Commerce inventory, reserving basket inventory does not reduce ATS. In this case, converting the
      basket to an order reduces ATS by the reserved amount. For example, consider a product with an ATS quantity of 5
      and no reservations. If a basket reserves a quantity of 3, then other baskets still see an ATS of 5 but can only
      reserve a quantity of 2.
      
      
      
      
      When using Omnichannel Inventory, reserving basket inventory reduces ATS. In this case, converting the basket to
      an order doesn't reduce ATS. In the previous example, after the first basket reserved a quantity of 3, other
      baskets would see an ATS of 2.
      
      
      
      
      Reservations can only be made for products with an inventory record. The reservation of product bundles is
      controlled by the _Use Bundle Inventory Only_ setting on the inventory list. The setting allows inventory to
      be reserved for just the bundle or for the bundle and its bundled products.
      
      
      
      
      The following conditions must be met for the method to succeed:
      
      - an inventory list must be assigned to the current site
      - all products in the basket must exist, and must not be of type Master or ProductSet
      - each product line item must have a valid quantity
      - each product must have an inventory record, or the inventory list must define that products without inventory  record are available by default
      - the reservation must succeed for each item as described above.
      
      
      
      
      
      The method implements its own transaction handling. Calling the method from inside a transaction is disallowed
      and results in an exception being thrown. This behavior differs when calling the method from an **OCAPI
       hook**. OCAPI hooks handle transactions themselves, so in this case there is also no need to do any transaction
      handling, but to ensure the shortest possible locking of the inventory this method should only be called _as
       the last step_ in the OCAPI hook.
      
      
      
      
      [getInventoryReservationExpiry()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#getinventoryreservationexpiry) can be used to determine when the expiration will expire.
      
      
      
      
      If the reservation fails with an ERROR status, existing valid reservations for the basket will remain unchanged
      but no new reservations will be made. This might lead to a partially reserved basket.
      
      
      
      
      Behaves same as `reserveInventory( reservationDurationInMinutes, false );`.
      
      
      
      
      This method must not be used with
      
      - the **CreateOrder2**pipelet, or
      - [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket), or
      - [OrderMgr.createOrder(Basket, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket-string)
      
      in the same request.


    **Parameters:**
    - reservationDurationInMinutes - reservation duration in minutes, specifying how long the reservation will             last. The maximum value for the reservation duration is 240 minutes.

    **Returns:**
    - a Status instance with - Status.OK if all items could be reserved, otherwise Status.ERROR meaning no
              items were reserved.



---

### reserveInventory(Number, Boolean)
- reserveInventory(reservationDurationInMinutes: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), removeIfNotAvailable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Reserve inventory for all items in this basket for 10 minutes. Any reservations created by previous calls of
      this method are replaced.
      
      
      
      
      Sample workflow for subsequent basket reservations:
      
      
      
      
      1. Request: Add item to basket and reserve the basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.createProductLineItem("sku1",2,basket.defaultShipment)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku1:2} is complete
      ```
      
      
      
      
      
      2. Request: Add item to basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.createProductLineItem("sku2",2,basket.defaultShipment)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku1:2, sku2:2} is complete. The previous reservation was overwritten.
      ```
      
      
      
      
      
      3. Request: Remove item from basket.
      
      
      
      
      
      ```
         transaction.begin()
         basket.removeProductLineItem(item1)
         basket.commit()
         basket.reserveInventory()
         // The reservation {sku2:2} is complete. The previous reservation was
         // overwritten and a quantity of 2 is released for sku1.
      ```
      
      
      
      
      
      The method can be used to reserve basket items before checkout to ensure that inventory is still available at the
      time an order is created from the basket using [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket). If all or some
      basket items are not reserved before creating an order, [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) will
      validate item availability and will fail if any item is unavailable. Calling this method in the same request as
      [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) is unnecessary and discouraged for performance reasons.
      
      
      
      
      The maximum quantity that can be reserved at one time is equal to the ATS (Available To Sell) quantity. (See
      [ProductInventoryRecord.getATS()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getats).)
      
      
      
      
      When using B2C Commerce inventory, reserving basket inventory does not reduce ATS. In this case, converting the
      basket to an order reduces ATS by the reserved amount. For example, consider a product with an ATS quantity of 5
      and no reservations. If a basket reserves a quantity of 3, then other baskets still see an ATS of 5 but can only
      reserve a quantity of 2.
      
      
      
      
      When using Omnichannel Inventory, reserving basket inventory reduces ATS. In this case, converting the basket to
      an order doesn't reduce ATS. In the previous example, after the first basket reserved a quantity of 3, other
      baskets would see an ATS of 2.
      
      
      
      
      Reservations can only be made for products with an inventory record. The reservation of product bundles is
      controlled by the _Use Bundle Inventory Only_ setting on the inventory list. The setting allows inventory to
      be reserved for just the bundle or for the bundle and its bundled products.
      
      
      
      
      The following conditions must be met for the method to succeed:
      
      - an inventory list must be assigned to the current site
      - all products in the basket must exist, and must not be of type Master or ProductSet
      - each product line item must have a valid quantity
      - each product must have an inventory record, or the inventory list must define that products without inventory  record are available by default
      - the reservation must succeed for each item as described above or `removeIfNotAvailable`is set to  `true`
      
      
      
      
      
      The method implements its own transaction handling. Calling the method from inside a transaction is disallowed
      and results in an exception being thrown. This behavior differs when calling the method from an **OCAPI
       hook**. OCAPI hooks handle transactions themselves, so in this case there is also no need to do any transaction
      handling, but to ensure the shortest possible locking of the inventory this method should only be called _as
       the last step_ in the OCAPI hook.
      
      
      
      
      [getInventoryReservationExpiry()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#getinventoryreservationexpiry) can be used to determine when the expiration will expire.
      
      
      
      
      If the reservation fails with an ERROR status, existing valid reservations for the basket will remain unchanged
      but no new reservations will be made. This might lead to a partially reserved basket.
      
      
      
      
      If the reservation succeeds with an OK status and `removeIfNotAvailable` is `true`, basket
      line items quantities might have been changed or line items might have been removed. The returned
      [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) object will contain information about the changes. Possible values for
      [StatusItem.getCode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getcode) are:
      
      - BUNDLE\_REMOVED - a bundle item was removed completely
      - ITEM\_REMOVED - a product line item was removed completely
      - ITEM\_QUANTITY\_REDUCED - the quantity of a line item was reduced
      
      [StatusItem.getDetails()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getdetails) will contain for each item the **sku** and **uuid** of the item
      which was changed/removed.
      
      
      
      
      This method must not be used with
      
      - the **CreateOrder2**pipelet, or
      - [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket), or
      - [OrderMgr.createOrder(Basket, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket-string)
      
      in the same request.


    **Parameters:**
    - reservationDurationInMinutes - reservation duration in minutes, specifying how long the reservation will             last. The maximum value for the reservation duration is 240 minutes.
    - removeIfNotAvailable - if `true` is specified it will not fail if not the full quantity of the             items can be reserved. Item quantity will be reduced to the quantity that could be reserved. Item will             be removed if not at least quantity 1 for the item could be reserved. Different to that if a bundle             line item cannot be reserved completely it will be removed including dependent line item (bundled             items).

    **Returns:**
    - a Status instance with - Status.OK meaning reservation process was successful. In case of
              `removeIfNotAvailable` is true, status might contain status items
              ([Status.getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getitems)) for each item that needed to be changed or removed. In the worst
              case this could result in an empty basket and no items reserved. A Status instance with - Status.ERROR
              will be returned if `removeIfNotAvailable` is false and not all items could be reserved fully
              or any unexpected error occurred.



---

### setBusinessType(Number)
- setBusinessType(aType: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the type of the business this order has been placed in.
      
      Possible values are [LineItemCtnr.BUSINESS_TYPE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2c) or [LineItemCtnr.BUSINESS_TYPE_B2B](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2b).


    **Parameters:**
    - aType - the business type to set for this basket


---

### setChannelType(Number)
- setChannelType(aType: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the channel type in which sales channel this order has been created. This can be used to distinguish order
      placed through e.g. Storefront, Call Center or Marketplace.
      
      Possible values are [LineItemCtnr.CHANNEL_TYPE_STOREFRONT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_storefront),
      [LineItemCtnr.CHANNEL_TYPE_CALLCENTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_callcenter), [LineItemCtnr.CHANNEL_TYPE_MARKETPLACE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_marketplace),
      [LineItemCtnr.CHANNEL_TYPE_DSS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_dss), [LineItemCtnr.CHANNEL_TYPE_STORE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_store),
      [LineItemCtnr.CHANNEL_TYPE_PINTEREST](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_pinterest), [LineItemCtnr.CHANNEL_TYPE_TWITTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_twitter),
      [LineItemCtnr.CHANNEL_TYPE_FACEBOOKADS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_facebookads), [LineItemCtnr.CHANNEL_TYPE_SUBSCRIPTIONS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_subscriptions),
      [LineItemCtnr.CHANNEL_TYPE_ONLINERESERVATION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_onlinereservation),
      [LineItemCtnr.CHANNEL_TYPE_INSTAGRAMCOMMERCE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_instagramcommerce), [LineItemCtnr.CHANNEL_TYPE_GOOGLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_google),
      [LineItemCtnr.CHANNEL_TYPE_YOUTUBE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_youtube), [LineItemCtnr.CHANNEL_TYPE_TIKTOK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_tiktok),
      [LineItemCtnr.CHANNEL_TYPE_SNAPCHAT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_snapchat), [LineItemCtnr.CHANNEL_TYPE_WHATSAPP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_whatsapp) The
      value for [LineItemCtnr.CHANNEL_TYPE_CUSTOMERSERVICECENTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_customerservicecenter) and
      [LineItemCtnr.CHANNEL_TYPE_CHATGPT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_chatgpt) and [LineItemCtnr.CHANNEL_TYPE_GEMINI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_gemini) are also
      available, but it can not be set by the scripting API, it is set only internally.


    **Parameters:**
    - aType - the channel type to set for this basket


---

### setCustomerNo(String)
- ~~setCustomerNo(customerNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the customer number of the customer associated with this container.
      
      
      Note this method has little effect as it only sets the customer number and it does _not re-link the basket with
       a customer profile</> object, nor is the number copied into the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) should one be created from
       the basket. Use [Order.setCustomer(Customer)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcustomercustomer) instead for a registered customer. For a
       guest customer the customerNo is usually generated during order creation and the attribute is set at order level.


    **Parameters:**
    - customerNo - the customer number of the customer associated with this container.

    **Deprecated:**
**warning:** The method has been deprecated. Please use [Order.setCustomer(Customer)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcustomercustomer)
            instead for registered customer. For guest customer the customerNo is usually generated during order
            creation and the attribute is set at order level.

---

### startCheckout()
- startCheckout(): void
  - : Register a "start checkout" event for the current basket. This event is tracked for AB test statistics
      but otherwise has no effect on the basket. The system will register at most one checkout per basket per session.



---

### updateCurrency()
- updateCurrency(): void
  - : Updates the basket currency if different to session currency, otherwise does nothing.
      
      
      Use [Session.setCurrency(Currency)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#setcurrencycurrency) to set the currency for the session. To reflect the session
      currency change to the basket you need to update the basket with this method. This ensures that any upcoming
      basket recalculation, which is based on the session currency, matches the basket currency.
      
      
      
      
      ```
      ...
          if (basket.getBillingAddress().getCountryCode() == 'DE'){
            var newCurrency : Currency = Currency.getCurrency('EUR');
            session.setCurrency( newCurrency );
            basket.updateCurrency();
          }
          customBasketRecalculate();
      ...
      ```



---

<!-- prettier-ignore-end -->

<!-- document id=abc255323a6f03c429a143a490753d6d1edf5fa7ebc32d52c20417d83dbadcd4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.BasketMergeHooks.md -->

<!-- prettier-ignore-start -->
# Class BasketMergeHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.BasketMergeHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.BasketMergeHooks.md)

This interface represents all script hooks that can be registered to merge baskets. It contains the extension points
(hook names), and the functions that are called by each extension point. A function must be defined inside a
JavaScript source and must be exported. The script with the exported hook function must be located inside a site
cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.


```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:


```
"hooks": [
     {"name": "dw.order.mergeBasket", "script": "./mergeBasket.js"}
]
```


A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointMerge](#extensionpointmerge): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.mergeBasket" | The extension point name dw.order.mergeBasket. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [mergeBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.BasketMergeHooks.md#mergebasketbasket-basket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Merges content from a source basket (typically a former registered shopper's basket) into the current basket  (usually a former guest shopper's basket that was transferred to the registered shopper). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointMerge

- extensionPointMerge: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.mergeBasket"
  - : The extension point name dw.order.mergeBasket.


---

## Method Details

### mergeBasket(Basket, Basket)
- mergeBasket(source: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), currentBasket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Merges content from a source basket (typically a former registered shopper's basket) into the current basket
      (usually a former guest shopper's basket that was transferred to the registered shopper).
      
      
      If no override script is registered, the system defaults to the platform's standard basket merging logic.
      
      
      This method is automatically invoked after a successful execution of the /transfer REST API with the query
      parameter merge=true, if either the guest or the registered users had baskets assigned. The registered shopper's
      basket will be the source for the merge, and the transferred guest shopper's basket will be the current basket.


    **Parameters:**
    - source - the basket from which data will be merged into the current basket. Will be `null` if the             former guest shopper did not have an assigned basket.
    - currentBasket - the current basket to merge data into


---

<!-- prettier-ignore-end -->

<!-- document id=8d9ba348ee123851ae62beaf6713b2b86ff666fd98337c444a83beb7c0ae7860 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.BasketMgr.md -->

<!-- prettier-ignore-start -->
# Class BasketMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.BasketMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md)

Provides static helper methods for managing baskets.


## Property Summary

| Property | Description |
| --- | --- |
| [baskets](#baskets): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | <p>  Retrieve all open baskets for the logged in customer including the temporary baskets. |
| [currentBasket](#currentbasket): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) `(read-only)` | This method returns the current valid basket of the session customer or `null` if no current valid  basket exists. |
| [currentOrNewBasket](#currentornewbasket): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) `(read-only)` | <p>  This method returns the current valid basket of the session customer or creates a new one if no current valid  basket exists. |
| [storedBasket](#storedbasket): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) `(read-only)` | <p>  This method returns the stored basket of the session customer or `null` if none is found. |
| [temporaryBaskets](#temporarybaskets): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Retrieve all open temporary baskets for the logged in customer. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [createAgentBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createagentbasket)() | Creates a new agent basket for the current session customer. |
| static [createBasketFromOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  Creates a Basket from an existing Order for the purposes of changing an Order. |
| static [createTemporaryBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createtemporarybasket)() | Creates a new temporary basket for the current session customer. |
| static [deleteBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#deletebasketbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Remove a customer basket including a temporary basket. |
| static [deleteTemporaryBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#deletetemporarybasketbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Remove a customer temporary basket. |
| static [getBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getbasketstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method returns a valid basket of the session customer or `null` if none is found. |
| static [getBaskets](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getbaskets)() | <p>  Retrieve all open baskets for the logged in customer including the temporary baskets. |
| static [getCurrentBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket)() | This method returns the current valid basket of the session customer or `null` if no current valid  basket exists. |
| static [getCurrentOrNewBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket)() | <p>  This method returns the current valid basket of the session customer or creates a new one if no current valid  basket exists. |
| static [getStoredBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getstoredbasket)() | <p>  This method returns the stored basket of the session customer or `null` if none is found. |
| static [getTemporaryBasket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#gettemporarybasketstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method returns a valid temporary basket of the session customer or `null` if none is found. |
| static [getTemporaryBaskets](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#gettemporarybaskets)() | Retrieve all open temporary baskets for the logged in customer. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### baskets
- baskets: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : 
      
      Retrieve all open baskets for the logged in customer including the temporary baskets.
      
      
      
      
      Restricted to agent scenario use cases: The returned list contains all agent baskets created with
      [createAgentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createagentbasket) and the current storefront basket which can also be retrieved with
      [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket). This method will result in an exception if called by a user without permission
      Create\_Order\_On\_Behalf\_Of or if no customer is logged in the session.
      
      
      
      
      Please notice that baskets are invalidated after a certain amount of time and may not be returned anymore.



---

### currentBasket
- currentBasket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) `(read-only)`
  - : This method returns the current valid basket of the session customer or `null` if no current valid
      basket exists.
      
      
      The methods [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket) and [getCurrentOrNewBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket) work based on the selected basket
      persistence, which can be configured in the Business Manager site preferences / baskets section. A basket is
      valid for the configured basket lifetime.
      
      
      
      
      In hybrid storefront scenarios _(Phased Launch sites that utilize SFRA/SiteGenesis for some part while also
       utilizing PWA Kit or other custom headless solution for another part of the same site)_, this method must
      **NOT** be used. Instead, retrieve baskets via `GET baskets/{basketId}` or
      `GET customers/{customerId}/baskets`. Do not use [getCurrentOrNewBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket) for basket creation
      in any scenario.
      
      
      
      
      The current basket, if one exists, is usually updated by the method. In particular the last-modified date is
      updated. **_No update is done when method [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket) is used within a read-only hook
       implementation (such as a beforeGet or a modifyResponse hook)._** The lifetime of a basket can be extended
      in 2 ways:
      
      - The basket is modified in some way, e.g. a product is added resulting in the basket total being newly  calculated. This results in the basket lifetime being reset.
      - The basket has not been modified for 60 minutes, then using this method to access the basket will also reset  the basket lifetime.
      
      
      
      
      
      What happens when a customer logs in? Personal data held inside the basket such as addresses, email addresses and
      payment settings is associated with the customer to whom the basket belongs. If the basket being updated belongs
      to a different customer this data is removed. This happens when a guest customer that has a basket logs in and
      hence identifies as a registered customer. In this case the basket which was previously created by the guest
      customer gets transferred to the (now logged in) registered customer. Should the registered customer already have
      a basket, this basket is effectively invalidated, but made available using [getStoredBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getstoredbasket) allowing
      the script to merge content from it if desired.
      
      
      
      
      What happens when a customer logs out or when the customer session times out? After the customer logs out, a
      basket belonging to the registered customer (now logged out) is stored (where applicable) and this method 
      returns `null`. Personal data is also cleared when the session times out for a guest customer.
      
      
      
      
      The following personal data is cleared:
      
      - product line items that were added from a wish list
      - shipping method
      - coupon line items
      - gift certificate line items
      - billing and shipping addresses
      - payment instruments
      - buyer email
      
      If the session currency no longer matches the basket currency, the basket currency should be updated with
      [Basket.updateCurrency()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#updatecurrency).
      
      
      
      
      Typical usage:
      
      
      ```
      var basket : Basket = BasketMgr.getCurrentBasket();
      if (basket) {
          // do something with basket
      }
      ```
      
      
      
      
      
      Constraints:
      
      - The method only accesses the basket for the session customer, an exception is thrown when the session  customer is `null`.
      - Method [getCurrentOrNewBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket)only creates a basket when method [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket)returns  `null`.



---

### currentOrNewBasket
- currentOrNewBasket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) `(read-only)`
  - : 
      
      This method returns the current valid basket of the session customer or creates a new one if no current valid
      basket exists. See [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket) for more details.
      
      
      
      
      In hybrid storefront scenarios _(Phased Launch sites that utilize SFRA/SiteGenesis for some part while also
       utilizing PWA Kit or other custom headless solution for another part of the same site)_, this method must
      **NOT** be used. For these scenarios, create baskets via `POST baskets` REST calls.



---

### storedBasket
- storedBasket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) `(read-only)`
  - : 
      
      This method returns the stored basket of the session customer or `null` if none is found. A stored
      basket is returned in the following situation:
      
      1. During one visit, a customer-Q logs in and creates a basket-A by adding products to it.
      2. During a subsequent visit, a second basket-B is created for a guest customer who then logs in as   customer-Q.
      
      In this case, basket-B is reassigned to customer-Q and basket-A is accessible as the stored basket using this
      method. It is now possible to merge the information from the stored basket (basket-A) to the active basket
      (basket-B). If this method returns `null` in the previous scenario, verify that:
      
      1. The session handling between the two visits is correct - the first visit and second visit must be in   different sessions. Furthermore, the second session must contain both basket creations: as guest and the customer   login.
      2. The stored basket is not expired.
      3. Basket persistence settings are configured correctly in the Business Manager.
      
      
      
      
      
      A stored basket exists only if the corresponding setting is selected in Business Manager. preferences' baskets
      section. A basket is valid for the configured basket lifetime.
      
      
      
      
      Typical usage:
      
      
      ```
      var currentBasket : Basket = BasketMgr.getCurrentOrNewBasket();
      var storedBasket : Basket = BasketMgr.getStoredBasket();
      if (storedBasket) {
          // transfer all the data needed from the stored to the active basket
      }
      ```
      
      
      A exhaustive example on how to use this method in the context of the Merge Basket functionality can be found
      here: [Merge Basket utility
      functions using Script API](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f)



---

### temporaryBaskets
- temporaryBaskets: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Retrieve all open temporary baskets for the logged in customer.
      
      
      Please notice that baskets are invalidated after a certain amount of time and may not be returned anymore.



---

## Method Details

### createAgentBasket()
- static createAgentBasket(): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : Creates a new agent basket for the current session customer.
      
      
      By default only 4 open agent baskets are allowed per customer. If this is exceeded a
      [CreateAgentBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateAgentBasketLimitExceededException.md) will be thrown.
      
      
      
      
      This method will result in an exception if called by a user without permission Create\_Order\_On\_Behalf\_Of or if no
      customer is logged in the session.


    **Returns:**
    - the newly created basket for the customer which is logged in

    **Throws:**
    - CreateAgentBasketLimitExceededException - indicates that no agent basket could be created because the agent              basket limit is already exceeded


---

### createBasketFromOrder(Order)
- static createBasketFromOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : 
      
      Creates a Basket from an existing Order for the purposes of changing an Order. When an Order is later created
      from the Basket, the original Order is changed to status [Order.ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced). Restricted
      to agent scenario use cases.
      
      
      
      
      In case a storefront customer is using it the created storefront basket cannot be retrieved via
      
      - [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket)(ScriptAPI),
      - GET /baskets/<basketid>(REST APIs) or
      - DELETE /baskets/<basketid>(REST APIs) or
      - GetBasket (Pipelet) or
      - Basket-related CSC Operations from BM (these also use OCAPI REST API).
      
      Baskets containing an "orderNumberBeingEdited" are explicitly excluded from the list of baskets that can be
      retrieved. Responsible for this behavior (this kind of basket cannot be used as general purpose shopping baskets)
      - see [Basket.getOrderNoBeingEdited()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#getordernobeingedited) / [Basket.getOrderBeingEdited()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#getorderbeingedited).
      
      
      
      
      In case a Business Manager user is logged in into the session the basket will be marked as an agent basket. See
      [Basket.isAgentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#isagentbasket)</>.
      
      
      
      
      Any inventory reservation associated with the order will be canceled either early when
      [Basket.reserveInventory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventory) is called for the new basket or (later) when a new replacement order
      is created from the basket. Consider reserving the basket following its creation.
      
      
      
      
      The method only succeeds for an Order
      
      - without gift certificates,
      - status is not cancelled,
      - was not previously replaced and
      - was not previously exported.
      
      Failures are indicated by throwing an APIException of type CreateBasketFromOrderException which provides one of
      these errorCodes:
      
      - Code [OrderProcessStatusCodes.ORDER_CONTAINS_GC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#order_contains_gc)- the Order contains a gift certificate and  cannot be replaced.
      - Code [OrderProcessStatusCodes.ORDER_ALREADY_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#order_already_replaced)- the Order was already replaced.
      - Code [OrderProcessStatusCodes.ORDER_ALREADY_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#order_already_cancelled)- the Order was cancelled.
      - Code [OrderProcessStatusCodes.ORDER_ALREADY_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#order_already_exported)- the Order has already been  exported.
      
      
      
      
      
      Usage:
      
      
      ```
      var order : Order; // known
      try
      {
        var basket : Basket = BasketMgr.createBasketFromOrder(order);
      }
      catch (e)
      {
        if (e instanceof APIException && e.type === 'CreateBasketFromOrderException')
        {
          // handle e.errorCode
        }
      }
      ```


    **Parameters:**
    - order - Order to create a Basket for

    **Returns:**
    - a new Basket

    **Throws:**
    - dw.order.CreateBasketFromOrderException - indicates the Order is in an invalid state.

    **See Also:**
    - [AgentUserMgr.loginAgentUser(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md#loginagentuserstring-string)
    - [AgentUserMgr.loginOnBehalfOfCustomer(Customer)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md#loginonbehalfofcustomercustomer)


---

### createTemporaryBasket()
- static createTemporaryBasket(): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : Creates a new temporary basket for the current session customer. Temporary baskets are separate from shopper
      storefront and agent baskets, and are intended for use to perform calculations or create an order without
      disturbing a shopper's open storefront basket. Temporary baskets are automatically deleted after a time duration
      of 15 minutes.
      
      
      By default only 4 open temporary baskets are allowed per customer. If this is exceeded a
      [CreateTemporaryBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateTemporaryBasketLimitExceededException.md) will be thrown.


    **Returns:**
    - the newly created basket for the current session customer


---

### deleteBasket(Basket)
- static deleteBasket(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): void
  - : Remove a customer basket including a temporary basket.
      
      
      This method will result in an exception if called by a user without permission Create\_Order\_On\_Behalf\_Of or if no
      customer is logged in the session.


    **Parameters:**
    - basket - the basket to be removed

    **See Also:**
    - [AgentUserMgr.loginAgentUser(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md#loginagentuserstring-string)
    - [AgentUserMgr.loginOnBehalfOfCustomer(Customer)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md#loginonbehalfofcustomercustomer)


---

### deleteTemporaryBasket(Basket)
- static deleteTemporaryBasket(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): void
  - : Remove a customer temporary basket.

    **Parameters:**
    - basket - the temporary basket to be removed


---

### getBasket(String)
- static getBasket(uuid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : This method returns a valid basket of the session customer or `null` if none is found. This method can
      also be used to get a temporary basket for the session customer.
      
      
      If the basket does not belong to the session customer, the method returns `null`.
      
      
      If the registered customer is not logged in, the method returns `null`.
      
      
      
      
      Restricted to agent scenario use cases: This method will result in an exception if called by a user without
      permission Create\_Order\_On\_Behalf\_Of or if no customer is logged in the session.
      
      
      The basket, if accessible, is usually updated in the same way as [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket).
      
      
      If the session currency no longer matches the basket currency, the basket currency should be updated with
      [Basket.updateCurrency()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#updatecurrency).


    **Parameters:**
    - uuid - the id of the requested basket.

    **Returns:**
    - the basket or `null`


---

### getBaskets()
- static getBaskets(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : 
      
      Retrieve all open baskets for the logged in customer including the temporary baskets.
      
      
      
      
      Restricted to agent scenario use cases: The returned list contains all agent baskets created with
      [createAgentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createagentbasket) and the current storefront basket which can also be retrieved with
      [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket). This method will result in an exception if called by a user without permission
      Create\_Order\_On\_Behalf\_Of or if no customer is logged in the session.
      
      
      
      
      Please notice that baskets are invalidated after a certain amount of time and may not be returned anymore.


    **Returns:**
    - all open baskets


---

### getCurrentBasket()
- static getCurrentBasket(): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : This method returns the current valid basket of the session customer or `null` if no current valid
      basket exists.
      
      
      The methods [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket) and [getCurrentOrNewBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket) work based on the selected basket
      persistence, which can be configured in the Business Manager site preferences / baskets section. A basket is
      valid for the configured basket lifetime.
      
      
      
      
      In hybrid storefront scenarios _(Phased Launch sites that utilize SFRA/SiteGenesis for some part while also
       utilizing PWA Kit or other custom headless solution for another part of the same site)_, this method must
      **NOT** be used. Instead, retrieve baskets via `GET baskets/{basketId}` or
      `GET customers/{customerId}/baskets`. Do not use [getCurrentOrNewBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket) for basket creation
      in any scenario.
      
      
      
      
      The current basket, if one exists, is usually updated by the method. In particular the last-modified date is
      updated. **_No update is done when method [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket) is used within a read-only hook
       implementation (such as a beforeGet or a modifyResponse hook)._** The lifetime of a basket can be extended
      in 2 ways:
      
      - The basket is modified in some way, e.g. a product is added resulting in the basket total being newly  calculated. This results in the basket lifetime being reset.
      - The basket has not been modified for 60 minutes, then using this method to access the basket will also reset  the basket lifetime.
      
      
      
      
      
      What happens when a customer logs in? Personal data held inside the basket such as addresses, email addresses and
      payment settings is associated with the customer to whom the basket belongs. If the basket being updated belongs
      to a different customer this data is removed. This happens when a guest customer that has a basket logs in and
      hence identifies as a registered customer. In this case the basket which was previously created by the guest
      customer gets transferred to the (now logged in) registered customer. Should the registered customer already have
      a basket, this basket is effectively invalidated, but made available using [getStoredBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getstoredbasket) allowing
      the script to merge content from it if desired.
      
      
      
      
      What happens when a customer logs out or when the customer session times out? After the customer logs out, a
      basket belonging to the registered customer (now logged out) is stored (where applicable) and this method 
      returns `null`. Personal data is also cleared when the session times out for a guest customer.
      
      
      
      
      The following personal data is cleared:
      
      - product line items that were added from a wish list
      - shipping method
      - coupon line items
      - gift certificate line items
      - billing and shipping addresses
      - payment instruments
      - buyer email
      
      If the session currency no longer matches the basket currency, the basket currency should be updated with
      [Basket.updateCurrency()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#updatecurrency).
      
      
      
      
      Typical usage:
      
      
      ```
      var basket : Basket = BasketMgr.getCurrentBasket();
      if (basket) {
          // do something with basket
      }
      ```
      
      
      
      
      
      Constraints:
      
      - The method only accesses the basket for the session customer, an exception is thrown when the session  customer is `null`.
      - Method [getCurrentOrNewBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket)only creates a basket when method [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket)returns  `null`.


    **Returns:**
    - the current basket or `null` if no valid current basket exists.


---

### getCurrentOrNewBasket()
- static getCurrentOrNewBasket(): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : 
      
      This method returns the current valid basket of the session customer or creates a new one if no current valid
      basket exists. See [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket) for more details.
      
      
      
      
      In hybrid storefront scenarios _(Phased Launch sites that utilize SFRA/SiteGenesis for some part while also
       utilizing PWA Kit or other custom headless solution for another part of the same site)_, this method must
      **NOT** be used. For these scenarios, create baskets via `POST baskets` REST calls.


    **Returns:**
    - the basket, existing or newly created


---

### getStoredBasket()
- static getStoredBasket(): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : 
      
      This method returns the stored basket of the session customer or `null` if none is found. A stored
      basket is returned in the following situation:
      
      1. During one visit, a customer-Q logs in and creates a basket-A by adding products to it.
      2. During a subsequent visit, a second basket-B is created for a guest customer who then logs in as   customer-Q.
      
      In this case, basket-B is reassigned to customer-Q and basket-A is accessible as the stored basket using this
      method. It is now possible to merge the information from the stored basket (basket-A) to the active basket
      (basket-B). If this method returns `null` in the previous scenario, verify that:
      
      1. The session handling between the two visits is correct - the first visit and second visit must be in   different sessions. Furthermore, the second session must contain both basket creations: as guest and the customer   login.
      2. The stored basket is not expired.
      3. Basket persistence settings are configured correctly in the Business Manager.
      
      
      
      
      
      A stored basket exists only if the corresponding setting is selected in Business Manager. preferences' baskets
      section. A basket is valid for the configured basket lifetime.
      
      
      
      
      Typical usage:
      
      
      ```
      var currentBasket : Basket = BasketMgr.getCurrentOrNewBasket();
      var storedBasket : Basket = BasketMgr.getStoredBasket();
      if (storedBasket) {
          // transfer all the data needed from the stored to the active basket
      }
      ```
      
      
      A exhaustive example on how to use this method in the context of the Merge Basket functionality can be found
      here: [Merge Basket utility
      functions using Script API](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f)


    **Returns:**
    - the stored basket or `null` if no valid stored basket exists.


---

### getTemporaryBasket(String)
- static getTemporaryBasket(uuid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)
  - : This method returns a valid temporary basket of the session customer or `null` if none is found.
      
      
      If the basket does not belong to the session customer, the method returns `null`.
      
      
      
      
      If the basket is not a temporary basket, the method returns `null`.
      
      
      
      
      The basket, if accessible, is usually updated in the same way as [getCurrentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentbasket).
      
      
      If the session currency no longer matches the basket currency, the basket currency should be updated with
      [Basket.updateCurrency()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#updatecurrency).


    **Parameters:**
    - uuid - the id of the requested temporary basket.

    **Returns:**
    - the temporary basket or `null`


---

### getTemporaryBaskets()
- static getTemporaryBaskets(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Retrieve all open temporary baskets for the logged in customer.
      
      
      Please notice that baskets are invalidated after a certain amount of time and may not be returned anymore.


    **Returns:**
    - all open temporary baskets


---

<!-- prettier-ignore-end -->

<!-- document id=6c0f7ddbb0c98b068d95bcbab1f76ea7b126c7c0b61b5a508f83e0f02a344f6e url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.BigInt.md -->

<!-- prettier-ignore-start -->
# Class BigInt

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)

A BigInt object is a wrapper for a primitive `bigint` value.
`bigint` values can be numbers too large to be stored as `number` values.


A `bigint` literal in code is an integer number with an appended `n`.


Example:

```
var hugeNumber = 1245678901234567890n;
var hugeNumberObject = BigInt( hugeNumber );
```


**API Version:**
**note:** Available from version 22.7.

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [BigInt](#bigint)() | Constructs a BigInt with value 0. |
| [BigInt](#bigintbigint)([BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)) | Constructs a new BigInt using the specified BigInt. |
| [BigInt](#bigintstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a BigInt using the specified value. |

## Method Summary

| Method | Description |
| --- | --- |
| static [asIntN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md#asintnnumber-bigint)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)) | Clamps the given BigInt value to a signed integer with a given precision. |
| static [asUintN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md#asuintnnumber-bigint)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)) | Clamps the given BigInt value to an unsigned integer with a given precision. |
| [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md#tolocalestring)() | Converts this BigInt to a String using local number formatting conventions. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md#tostring)() | A String representation of this BigInt. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md#tostringnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Converts the BigInt into a string using the specified radix (base). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### BigInt()
- BigInt()
  - : Constructs a BigInt with value 0.


---

### BigInt(BigInt)
- BigInt(value: [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md))
  - : Constructs a new BigInt using the specified BigInt.

    **Parameters:**
    - value - the BigInt to use.


---

### BigInt(String)
- BigInt(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a BigInt using the specified value.
      
      
      Beside decimal numbers also binary, octal and hexadecimal numbers are supported:
      
      ```
      var decimal = BigInt( "12" );
      var binary  = BigInt( "0b1100" );
      var octal   = BigInt( "0o14" );
      var hex     = BigInt( "0xC" );
      ```


    **Parameters:**
    - value - the value to use when creating the BigInt.


---

## Method Details

### asIntN(Number, BigInt)
- static asIntN(bits: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)): [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)
  - : Clamps the given BigInt value to a signed integer with a given precision.

    **Parameters:**
    - bits - Number of bits required for resulting integer.
    - value - The value to be clamped to the given number of bits.

    **Returns:**
    - The `value` modulo 2`bits`, as a signed integer.


---

### asUintN(Number, BigInt)
- static asUintN(bits: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)): [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)
  - : Clamps the given BigInt value to an unsigned integer with a given precision.

    **Parameters:**
    - bits - Number of bits required for resulting integer.
    - value - The value to be clamped to the given number of bits.

    **Returns:**
    - The `value` modulo 2`bits`, as an unsigned integer.


---

### toLocaleString()
- toLocaleString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts this BigInt to a String using local number formatting conventions. 
      
      The current implementation actually only returns the same as [toString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md#tostring).


    **Returns:**
    - a String using local number formatting conventions.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : A String representation of this BigInt.

    **Returns:**
    - a String representation of this BigInt.


---

### toString(Number)
- toString(radix: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts the BigInt into a string using the specified radix (base).

    **Parameters:**
    - radix - the radix to use.

    **Returns:**
    - a String representation of this BigInt.


---

<!-- prettier-ignore-end -->

<!-- document id=e1a8e1170a430af84e2a8b1ff8ad4d5de1e92f945c8054f7ff05bc8b9882f615 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.BigInteger.md -->

<!-- prettier-ignore-start -->
# Class BigInteger

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)

The BigInteger class is a helper class to represent an arbitrary long integer number.
The Demandware framework doesn't use this class, but in some special cases
web services that declare an XML element with "xsd:integer", which is by definition
an arbitrary long integer number, require the use of this class.


The class is designed in a way that it can be used very similar to a
desktop calculator. For example:


```
var i = new BigInteger( 10 );
var result = d.add( 2 ).sub( 3 ).get();
```


The above code will return 9 as result.


**Deprecated:**
**warning:** Replaced by [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md).
**API Version:**
**note:** No longer available as of version 22.7.

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [BigInteger](#biginteger)() | Constructs a new BigInteger with the value 0. |
| [BigInteger](#bigintegernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a new BigInteger using the specified Number value. |
| [BigInteger](#bigintegerstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new BigInteger using the specified string representation of  a number. |

## Method Summary

| Method | Description |
| --- | --- |
| [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#abs)() | Returns a new BigInteger with the absolute value of this BigInteger. |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#addbiginteger)([BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)) | Adds an BigInteger value to this BigInteger and returns the new BigInteger. |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#addnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Adds a Number value to this BigInteger and returns the new BigInteger. |
| [divide](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#dividebiginteger)([BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)) | Divides this BigInteger by the specified BigInteger and returns the new BigInteger. |
| [divide](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#dividenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Divides this BigInteger by the specified BigInteger and returns the new BigInteger. |
| [equals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#equalsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Compares two BigInteger values whether they are equivalent. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#get)() | Returns the value of the BigInteger as a Number. |
| [hashCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#hashcode)() | Calculates the hash code for this BigInteger; |
| [multiply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#multiplybiginteger)([BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)) | Multiples the specified BigInteger value with this BigInteger and returns the new BigInteger. |
| [multiply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#multiplynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Multiples the specified Number value with this BigInteger and returns the new BigInteger. |
| [negate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#negate)() | Returns a new BigInteger with the negated value of this BigInteger. |
| [subtract](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#subtractbiginteger)([BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)) | Subtracts the specified BigInteger value from this BigInteger and returns the new BigInteger. |
| [subtract](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#subtractnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Subtracts the specified Number value from this BigInteger and returns the new BigInteger. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#tostring)() | Returns a string representation of this object. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md#valueof)() | The valueOf() method is called by the ECMAScript interpret to return  the "natural" value of an object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### BigInteger()
- BigInteger()
  - : Constructs a new BigInteger with the value 0.


---

### BigInteger(Number)
- BigInteger(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs a new BigInteger using the specified Number value.

    **Parameters:**
    - value - the value to use.


---

### BigInteger(String)
- BigInteger(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a new BigInteger using the specified string representation of
      a number.


    **Parameters:**
    - value - the value to use.


---

## Method Details

### abs()
- abs(): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Returns a new BigInteger with the absolute value of this BigInteger.

    **Returns:**
    - the new BigInteger


---

### add(BigInteger)
- add(value: [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Adds an BigInteger value to this BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to add to this BigInteger.

    **Returns:**
    - the new BigInteger with the value added.


---

### add(Number)
- add(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Adds a Number value to this BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to add to this BigInteger.

    **Returns:**
    - the new BigInteger with the value added.


---

### divide(BigInteger)
- divide(value: [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Divides this BigInteger by the specified BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to use to divide this BigInteger.

    **Returns:**
    - the new BigInteger.


---

### divide(Number)
- divide(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Divides this BigInteger by the specified BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to use to divide this BigInteger.

    **Returns:**
    - the new BigInteger.


---

### equals(Object)
- equals(other: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Compares two BigInteger values whether they are equivalent.

    **Parameters:**
    - other - the object to compare against this BigInteger.


---

### get()
- get(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the BigInteger as a Number.

    **Returns:**
    - the value of the BigInteger.


---

### hashCode()
- hashCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Calculates the hash code for this BigInteger;


---

### multiply(BigInteger)
- multiply(value: [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Multiples the specified BigInteger value with this BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to multiply with this BigInteger.

    **Returns:**
    - the new BigInteger.


---

### multiply(Number)
- multiply(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Multiples the specified Number value with this BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to multiply with this BigInteger.

    **Returns:**
    - the new BigInteger.


---

### negate()
- negate(): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Returns a new BigInteger with the negated value of this BigInteger.

    **Returns:**
    - the new BigInteger


---

### subtract(BigInteger)
- subtract(value: [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Subtracts the specified BigInteger value from this BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to add to this BigInteger.

    **Returns:**
    - the new BigInteger with the value subtracted.


---

### subtract(Number)
- subtract(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)
  - : Subtracts the specified Number value from this BigInteger and returns the new BigInteger.

    **Parameters:**
    - value - the value to add to this BigInteger.

    **Returns:**
    - the new BigInteger with the value subtracted.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this object.

    **Returns:**
    - a string representation of this object.


---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : The valueOf() method is called by the ECMAScript interpret to return
      the "natural" value of an object. The BigInteger object returns its
      current value as number. With this behavior script snippets can
      be written like:
      
      
      ```
      var i = new BigInteger( 10 );
      var x = 1 + d.add( 2 );
      ```
      
      
      where x will be at the end 13.


    **Returns:**
    - the value of this object.


---

<!-- prettier-ignore-end -->

<!-- document id=1c434f7596b29e4ef458dcd5abe756ea9042ff07b093eb0ba3d1919ed48872f4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.BonusChoiceDiscount.md -->

<!-- prettier-ignore-start -->
# Class BonusChoiceDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.BonusChoiceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md)

Represents a _choice of bonus products_ discount in the discount plan,
for example "Choose 3 DVDs from a list of 20 options with your purchase of
any DVD player."



## Property Summary

| Property | Description |
| --- | --- |
| [bonusProducts](#bonusproducts): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Get the list of bonus products which the customer is allowed to choose  from for this discount. |
| [maxBonusItems](#maxbonusitems): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the maximum number of bonus items that a customer is entitled to  select for this discount. |
| [ruleBased](#rulebased): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this is a "rule based" bonus choice discount. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBonusProductPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getbonusproductpriceproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Get the effective price for the passed bonus product. |
| [getBonusProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getbonusproducts)() | Get the list of bonus products which the customer is allowed to choose  from for this discount. |
| [getMaxBonusItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getmaxbonusitems)() | Returns the maximum number of bonus items that a customer is entitled to  select for this discount. |
| [isRuleBased](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#isrulebased)() | Returns true if this is a "rule based" bonus choice discount. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bonusProducts
- bonusProducts: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Get the list of bonus products which the customer is allowed to choose
      from for this discount. This list is configured by a merchant entering a
      list of SKUs for the discount. Products which do not exist in the system,
      or are offline, or are not assigned to a category in the site catalog are
      filtered out. Unavailable (i.e. out-of-stock) products are NOT filtered
      out. This allows merchants to display out-of-stock bonus products with
      appropriate messaging.
      
      
      If a returned product is a master product, the customer is entitled to
      choose from any variant. If the product is an option product, the
      customer is entitled to choose any value for each option. Since the
      promotions engine does not touch the value of the product option line
      items, it is the responsibility of custom code to set option prices.
      
      
      If the promotion is rule based, then this method will return an empty list.
      A ProductSearchModel should be used to return the bonus products the
      customer may choose from instead. See
      [ProductSearchModel.PROMOTION_PRODUCT_TYPE_BONUS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#promotion_product_type_bonus) and
      [ProductSearchModel.setPromotionID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidstring)



---

### maxBonusItems
- maxBonusItems: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the maximum number of bonus items that a customer is entitled to
      select for this discount.



---

### ruleBased
- ruleBased: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this is a "rule based" bonus choice discount.
      For such discounts, there is no static list of bonus products
      associated with the discount but rather a discounted product
      rule associated with the promotion which defines the bonus
      products. To retrieve the list of selectable bonus products for
      display in the storefront, it is necessary to search for the
      bonus products using the [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md)
      API since the method [getBonusProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getbonusproducts) in this class
      will always return an empty list. Furthermore, for rule based
      bonus-choice discounts, [getBonusProductPrice(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getbonusproductpriceproduct)
      will always return a price of 0.00 for bonus products.



---

## Method Details

### getBonusProductPrice(Product)
- getBonusProductPrice(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Get the effective price for the passed bonus product. This is expected to
      be one of the products returned by [getBonusProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getbonusproducts) with one
      exception: If a master product is configured as a bonus product, this
      implies that a customer may choose from any of its variants. In this
      case, it is allowed to pass in a variant to this method and a price will
      be returned. If the passed product is not a valid bonus product, this
      method throws an exception.


    **Parameters:**
    - product - The bonus product to retrieve a price for, must not be             null.

    **Returns:**
    - The price of the passed bonus product as a Number.


---

### getBonusProducts()
- getBonusProducts(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Get the list of bonus products which the customer is allowed to choose
      from for this discount. This list is configured by a merchant entering a
      list of SKUs for the discount. Products which do not exist in the system,
      or are offline, or are not assigned to a category in the site catalog are
      filtered out. Unavailable (i.e. out-of-stock) products are NOT filtered
      out. This allows merchants to display out-of-stock bonus products with
      appropriate messaging.
      
      
      If a returned product is a master product, the customer is entitled to
      choose from any variant. If the product is an option product, the
      customer is entitled to choose any value for each option. Since the
      promotions engine does not touch the value of the product option line
      items, it is the responsibility of custom code to set option prices.
      
      
      If the promotion is rule based, then this method will return an empty list.
      A ProductSearchModel should be used to return the bonus products the
      customer may choose from instead. See
      [ProductSearchModel.PROMOTION_PRODUCT_TYPE_BONUS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#promotion_product_type_bonus) and
      [ProductSearchModel.setPromotionID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidstring)


    **Returns:**
    - An ordered list of bonus products that the customer may choose
              from for this discount.



---

### getMaxBonusItems()
- getMaxBonusItems(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum number of bonus items that a customer is entitled to
      select for this discount.


    **Returns:**
    - The maximum number of bonus items that this discount permits a
              customer to select.



---

### isRuleBased()
- isRuleBased(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this is a "rule based" bonus choice discount.
      For such discounts, there is no static list of bonus products
      associated with the discount but rather a discounted product
      rule associated with the promotion which defines the bonus
      products. To retrieve the list of selectable bonus products for
      display in the storefront, it is necessary to search for the
      bonus products using the [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md)
      API since the method [getBonusProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getbonusproducts) in this class
      will always return an empty list. Furthermore, for rule based
      bonus-choice discounts, [getBonusProductPrice(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md#getbonusproductpriceproduct)
      will always return a price of 0.00 for bonus products.


    **Returns:**
    - True if this is a rule-based bonus-choice discount, or
              false if this discount defines a simple static list of
              bonus products.



---

<!-- prettier-ignore-end -->

<!-- document id=88e4749b0928bd7084d553ddd08c42773677f6a0556c3ec402b1d35c821b06a0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.BonusDiscount.md -->

<!-- prettier-ignore-start -->
# Class BonusDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.BonusDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusDiscount.md)

Represents a _bonus_ discount in the discount plan, for example
"Get a free DVD with your purchase of any DVD player."



## Property Summary

| Property | Description |
| --- | --- |
| [bonusProducts](#bonusproducts): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the bonus products associated with this discount that are in  stock, online and assigned to site catalog. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBonusProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusDiscount.md#getbonusproducts)() | Returns the bonus products associated with this discount that are in  stock, online and assigned to site catalog. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bonusProducts
- bonusProducts: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the bonus products associated with this discount that are in
      stock, online and assigned to site catalog.



---

## Method Details

### getBonusProducts()
- getBonusProducts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the bonus products associated with this discount that are in
      stock, online and assigned to site catalog.


    **Returns:**
    - Collection of bonus products


---

<!-- prettier-ignore-end -->

<!-- document id=da69666d1db57f77f53772e9f63b6a58a9042fee5e24e3cbbe34aff9c6923f40 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.BonusDiscountLineItem.md -->

<!-- prettier-ignore-start -->
# Class BonusDiscountLineItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md)

Line item representing an applied [BonusChoiceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md) in a LineItemCtnr. This type of line item
can only be created by the B2C Commerce promotions engine when applying a BonusChoiceDiscount.
A BonusDiscountLineItem is basically a placeholder in the cart which entitles a customer to add one or more bonus
products to his basket from a configured list of products. Merchants typically display this type of line item in the
cart by showing the corresponding promotion callout message. They typically provide links to the bonus products that
the customer can choose from. This line item can be removed from the cart but will be re-added each time the
promotions engine re-applies discounts. Merchants may however add custom logic to show/hide this line item since it
just a placeholder and not an actual product line item.


The number of products that a customer is allowed to choose from is determined by [getMaxBonusItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getmaxbonusitems). The
collection of products the customer can choose from is determined by [getBonusProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproducts). When a customer
chooses a bonus product in the storefront, it is necessary to use the `AddBonusProductToBasket` pipelet
instead of the usual `AddProductToBasket` pipelet, in order to associate this BonusDiscountLineItem with
the newly created bonus ProductLineItem. Alternatively, the API method
[LineItemCtnr.createBonusProductLineItem(BonusDiscountLineItem, Product, ProductOptionModel, Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbonusproductlineitembonusdiscountlineitem-product-productoptionmodel-shipment)
can be used instead. The system does proper validations in order to prevent incorrect or too many bonus products from
being associated with this BonusDiscountLineItem. Once a customer has selected bonus products, the product line items
representing the chosen bonus products can be retrieved with [getBonusProductLineItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproductlineitems).


**See Also:**
- [BonusChoiceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md)


## Property Summary

| Property | Description |
| --- | --- |
| [bonusChoiceRuleBased](#bonuschoicerulebased): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether the promotion that triggered the creation of this line item uses a rule to determine the list of  bonus products. |
| [bonusProductLineItems](#bonusproductlineitems): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Get the product line items in the current LineItemCtnr representing the  bonus products that the customer has selected for this discount. |
| [bonusProducts](#bonusproducts): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Get the list of bonus products which the customer is allowed to choose  from for this discount. |
| [couponLineItem](#couponlineitem): [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md) `(read-only)` | Get the coupon line item associated with this discount. |
| [maxBonusItems](#maxbonusitems): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Get the maximum number of bonus items that the customer is permitted to  select for this bonus discount. |
| [promotion](#promotion): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) `(read-only)` | Get the promotion associated with this discount. |
| [promotionID](#promotionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the promotion ID associated with this discount. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBonusProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproductlineitems)() | Get the product line items in the current LineItemCtnr representing the  bonus products that the customer has selected for this discount. |
| [getBonusProductPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproductpriceproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Get the effective price for the passed bonus product. |
| [getBonusProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproducts)() | Get the list of bonus products which the customer is allowed to choose  from for this discount. |
| [getCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getcouponlineitem)() | Get the coupon line item associated with this discount. |
| [getMaxBonusItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getmaxbonusitems)() | Get the maximum number of bonus items that the customer is permitted to  select for this bonus discount. |
| [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getpromotion)() | Get the promotion associated with this discount. |
| [getPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getpromotionid)() | Get the promotion ID associated with this discount. |
| [isBonusChoiceRuleBased](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#isbonuschoicerulebased)() | Returns whether the promotion that triggered the creation of this line item uses a rule to determine the list of  bonus products. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bonusChoiceRuleBased
- bonusChoiceRuleBased: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether the promotion that triggered the creation of this line item uses a rule to determine the list of
      bonus products.
      
      
      If the promotion is rule based, then a ProductSearchModel should be used to return the bonus products the
      customer may choose from, as the methods that return lists will return nothing. See [getBonusProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproducts)



---

### bonusProductLineItems
- bonusProductLineItems: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Get the product line items in the current LineItemCtnr representing the
      bonus products that the customer has selected for this discount.


    **See Also:**
    - [LineItemCtnr.createBonusProductLineItem(BonusDiscountLineItem, Product, ProductOptionModel, Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbonusproductlineitembonusdiscountlineitem-product-productoptionmodel-shipment)


---

### bonusProducts
- bonusProducts: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Get the list of bonus products which the customer is allowed to choose
      from for this discount. This list is configured by a merchant entering a
      list of SKUs for the discount. Products which do not exist in the system,
      or are offline, or are not assigned to a category in the site catalog are
      filtered out. Unavailable (i.e. out-of-stock) products are NOT filtered
      out. This allows merchants to display out-of-stock bonus products with
      appropriate messaging.
      
      
      If the promotion which triggered this discount does not exist, or this
      promotion is rule based, then this method returns an empty list.
      
      
      If the promotion is rule based, then this method will return an empty list.
      A ProductSearchModel should be used to return the bonus products the
      customer may choose from instead. See
      [ProductSearchModel.PROMOTION_PRODUCT_TYPE_BONUS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#promotion_product_type_bonus) and
      [ProductSearchModel.setPromotionID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidstring)
      
      
      If a returned product is a master product, the customer is entitled to
      choose from any variant. If the product is an option product, the
      customer is entitled to choose any value for each option. Since the
      promotions engine does not touch the value of the product option line
      items, it is the responsibility of custom code to set option prices.



---

### couponLineItem
- couponLineItem: [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md) `(read-only)`
  - : Get the coupon line item associated with this discount.


---

### maxBonusItems
- maxBonusItems: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Get the maximum number of bonus items that the customer is permitted to
      select for this bonus discount.
      
      
      If the promotion which triggered this discount does not exist, then this
      method returns 0.



---

### promotion
- promotion: [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) `(read-only)`
  - : Get the promotion associated with this discount.


---

### promotionID
- promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the promotion ID associated with this discount.


---

## Method Details

### getBonusProductLineItems()
- getBonusProductLineItems(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Get the product line items in the current LineItemCtnr representing the
      bonus products that the customer has selected for this discount.


    **Returns:**
    - The selected product line items, never null.

    **See Also:**
    - [LineItemCtnr.createBonusProductLineItem(BonusDiscountLineItem, Product, ProductOptionModel, Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbonusproductlineitembonusdiscountlineitem-product-productoptionmodel-shipment)


---

### getBonusProductPrice(Product)
- getBonusProductPrice(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Get the effective price for the passed bonus product. This is expected to
      be one of the products returned by [getBonusProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproducts) with one
      exception: If a master product is configured as a bonus product, this
      implies that a customer may choose from any of its variants. In this
      case, it is allowed to pass in a variant to this method and a price will
      be returned. If the passed product is not a valid bonus product, this
      method throws an exception.


    **Parameters:**
    - product - The bonus product to retrieve a price for, must not be             null.

    **Returns:**
    - The price of the passed bonus product as a Number.


---

### getBonusProducts()
- getBonusProducts(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Get the list of bonus products which the customer is allowed to choose
      from for this discount. This list is configured by a merchant entering a
      list of SKUs for the discount. Products which do not exist in the system,
      or are offline, or are not assigned to a category in the site catalog are
      filtered out. Unavailable (i.e. out-of-stock) products are NOT filtered
      out. This allows merchants to display out-of-stock bonus products with
      appropriate messaging.
      
      
      If the promotion which triggered this discount does not exist, or this
      promotion is rule based, then this method returns an empty list.
      
      
      If the promotion is rule based, then this method will return an empty list.
      A ProductSearchModel should be used to return the bonus products the
      customer may choose from instead. See
      [ProductSearchModel.PROMOTION_PRODUCT_TYPE_BONUS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#promotion_product_type_bonus) and
      [ProductSearchModel.setPromotionID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidstring)
      
      
      If a returned product is a master product, the customer is entitled to
      choose from any variant. If the product is an option product, the
      customer is entitled to choose any value for each option. Since the
      promotions engine does not touch the value of the product option line
      items, it is the responsibility of custom code to set option prices.


    **Returns:**
    - An ordered list of bonus products that the customer may choose
              from for this discount.



---

### getCouponLineItem()
- getCouponLineItem(): [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)
  - : Get the coupon line item associated with this discount.

    **Returns:**
    - The coupon line item associated with this discount, or null if it no
              longer exists or there is no one.



---

### getMaxBonusItems()
- getMaxBonusItems(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Get the maximum number of bonus items that the customer is permitted to
      select for this bonus discount.
      
      
      If the promotion which triggered this discount does not exist, then this
      method returns 0.


    **Returns:**
    - The maximum number of bonus items that the customer is permitted
              to select for this bonus discount, or 0 if the promotion no
              longer exists.



---

### getPromotion()
- getPromotion(): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)
  - : Get the promotion associated with this discount.

    **Returns:**
    - The promotion associated with this discount, or null if it no
              longer exists.



---

### getPromotionID()
- getPromotionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the promotion ID associated with this discount.

    **Returns:**
    - The promotion ID associated with this discount, never null.


---

### isBonusChoiceRuleBased()
- isBonusChoiceRuleBased(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether the promotion that triggered the creation of this line item uses a rule to determine the list of
      bonus products.
      
      
      If the promotion is rule based, then a ProductSearchModel should be used to return the bonus products the
      customer may choose from, as the methods that return lists will return nothing. See [getBonusProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md#getbonusproducts)


    **Returns:**
    - If the promotion no longer exists, then null, otherwise, true if the promotion that triggered the
              creation of this line item uses a rule to determine the bonus products to choose from.



---

<!-- prettier-ignore-end -->

<!-- document id=b573408e0263eddf8bde1b466c0c758fdddb5992e5e238819dc9fc942de92c9a url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Boolean.md -->

<!-- prettier-ignore-start -->
# Class Boolean

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)

Provides support for boolean values.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Boolean](#booleanstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the Boolean using the specified   String value. |
| [Boolean](#booleannumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs the Boolean using the specified   Number value. |

## Method Summary

| Method | Description |
| --- | --- |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md#tostring)() | Returns true or false depending on the value used to create   the Boolean. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md#valueof)() | Returns the primitive boolean contained in the Boolean   object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### Boolean(String)
- Boolean(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the Boolean using the specified 
      String value.


    **Parameters:**
    - value - the String value to use to construct the   Boolean. If _value_ is null or an empty String,   the Boolean is set to false.


---

### Boolean(Number)
- Boolean(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs the Boolean using the specified 
      Number value.


    **Parameters:**
    - value - the Number value to use to construct the   Boolean. If _value_ is null or 0,   the Boolean is set to false.


---

## Method Details

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns true or false depending on the value used to create 
      the Boolean.


    **Returns:**
    - true or false depending on the value used to create 
      the Boolean.



---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the primitive boolean contained in the Boolean 
      object.


    **Returns:**
    - the primitive boolean contained in the Boolean 
      object.



---

<!-- prettier-ignore-end -->

<!-- document id=eb55f52a500f5d1eb1b9f649abf61b3f26e1eb8ad94c6df881becb8f3aceb6fc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.BrandSuggestions.md -->

<!-- prettier-ignore-start -->
# Class BrandSuggestions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md)
    - [dw.suggest.BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md)

The brands suggestion container provides access to
brands found using the suggested terms.


The method [SearchPhraseSuggestions.getSuggestedPhrases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedphrases) can be used to
get the list of found brand names. The brand lookup
is being executed in the current catalog and locale.


Furthermore the list of suggested terms, after processing
the original user input search query, is accessible
through [SearchPhraseSuggestions.getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms) method.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Suggestions

[getSearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions), [getSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedphrases), [getSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms), [hasSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases), [hasSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedterms), [hasSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=7b2d1e3cbf4402d477541ccae228ed37629f5a816c99783aa3fb215e945bba1f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Bytes.md -->

<!-- prettier-ignore-start -->
# Class Bytes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)

A simple immutable class representing an array of bytes, used for working
with binary data in a scripting context.


It acts as a view to [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). The buffer can be accessed through [asUint8Array()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#asuint8array).

**Limitation:**
The size of the resulting byte representation is limited by the quota _api.jsArrayBufferSize_ that is defining the max size for a [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).



## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[MAX_BYTES](#max_bytes): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10240~~ | The maximum number of bytes that a Bytes object can represent == 10KB |

## Property Summary

| Property | Description |
| --- | --- |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of bytes represented by this object. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Bytes](#bytesobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Construct a Bytes object from the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) or view. |
| [Bytes](#bytesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a Bytes object from the given string using the default  encoding. |
| [Bytes](#bytesstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a Bytes object from the given string using the given encoding. |

## Method Summary

| Method | Description |
| --- | --- |
| [asUint8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#asuint8array)() | Returns a [Uint8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md) based on the [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) used for this Bytes object. |
| [byteAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#byteatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value of the byte at position index as an integer. |
| [bytesAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#bytesatnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Return a new Bytes object containing the subsequence of this object's bytes specified by the index and length  parameters. |
| [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#getlength)() | Returns the number of bytes represented by this object. |
| [intAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#intatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Absolute get method for reading a signed integer value (32 bit) in  network byte order(= big endian). |
| [reverse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#reverse)() | Return a new Bytes object which has the same bytes as this one in reverse  order. |
| [shortAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#shortatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Absolute get method for reading a signed short value (16 bit) in network  byte order(= big endian). |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#tostring)() | Constructs a new String by decoding this array of bytes using the  default encoding. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md#tostringstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new String by decoding this array of bytes using the  specified encoding. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### MAX_BYTES

- ~~MAX_BYTES: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10240~~
  - : The maximum number of bytes that a Bytes object can represent == 10KB

    **Deprecated:**
**warning:** No longer used by the Bytes class.

---

## Property Details

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of bytes represented by this object.


---

## Constructor Details

### Bytes(Object)
- Bytes(arrayBufferOrView: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Construct a Bytes object from the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) or view. The bytes object also acts as a
      view on the underlying [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). If a view is given that makes only a part of the storage
      array visible then this Bytes object will also make only the same part visible. The storage data is not copied.


    **Parameters:**
    - arrayBufferOrView - An [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) or view to a buffer that is the storage.

    **API Version:**
**note:** Available from version 21.2.

---

### Bytes(String)
- Bytes(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a Bytes object from the given string using the default
      encoding. Convenience for Bytes( string, "UTF-8" ).


    **Parameters:**
    - string - The string to encode into a Bytes object, must not be null.

    **Throws:**
    - IllegalArgumentException - If the encoded byte sequence exceeds the              maximum number of bytes.


---

### Bytes(String, String)
- Bytes(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a Bytes object from the given string using the given encoding.
      This method always replaces malformed input and unmappable character
      sequences with encoding defaults.


    **Parameters:**
    - string - The string to encode into a Bytes object, must not be null.
    - encoding - The name of a supported encoding, or null in which case             the default encoding (UTF-8) is used.

    **Throws:**
    - IllegalArgumentException - If the named encoding is not supported              or if the encoded byte sequence exceeds the maximum number of              bytes.


---

## Method Details

### asUint8Array()
- asUint8Array(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns a [Uint8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md) based on the [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) used for this Bytes object.
      Changes to the returned [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) will be visible in the Bytes object.


    **Returns:**
    - A newly created [Uint8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md) based on the existing [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **API Version:**
**note:** Available from version 21.2.

---

### byteAt(Number)
- byteAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the byte at position index as an integer. If index
      is out of range an exception is thrown. The byte is interpreted as signed
      and so the value returned will always be between -128 and +127.


    **Parameters:**
    - index - The index of the byte.

    **Returns:**
    - The byte value at the specified index.

    **Throws:**
    - IndexOutOfBoundsException - If the index argument is negative or              not less than the length of this byte array.


---

### bytesAt(Number, Number)
- bytesAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Return a new Bytes object containing the subsequence of this object's bytes specified by the index and length
      parameters. The returned object is a new view onto the same data, no data is copied.


    **Parameters:**
    - index - The initial index for the new view, inclusive.
    - length - The number of bytes visible in the new view.

    **Returns:**
    - a new Bytes object representing a subsequence of this Bytes object.

    **Throws:**
    - ArrayIndexOutOfBoundsException - If index < 0 or index > getLength() or index + length >              getLength()
    - IllegalArgumentException - If length < 0


---

### getLength()
- getLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of bytes represented by this object.

    **Returns:**
    - The number of bytes.


---

### intAt(Number)
- intAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Absolute get method for reading a signed integer value (32 bit) in
      network byte order(= big endian).


    **Parameters:**
    - index - The byte index at which to read the number.

    **Returns:**
    - The read number.

    **Throws:**
    - IndexOutOfBoundsException - If index is negative or not smaller              than the number of bytes minus three.


---

### reverse()
- reverse(): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Return a new Bytes object which has the same bytes as this one in reverse
      order.


    **Returns:**
    - a new Bytes object representing the reverse of this Bytes object.


---

### shortAt(Number)
- shortAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Absolute get method for reading a signed short value (16 bit) in network
      byte order(= big endian).


    **Parameters:**
    - index - The byte index at which to read the number.

    **Returns:**
    - The read number.

    **Throws:**
    - IndexOutOfBoundsException - If index is negative or not smaller              than the number of bytes minus one.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Constructs a new String by decoding this array of bytes using the
      default encoding. Convenience for toString( "UTF-8" ).
      **Limitation:**
      The method is protected by the quota _api.jsStringLength_ that prevents creation of too long strings.


    **Returns:**
    - A String representing the decoded array of bytes.


---

### toString(String)
- toString(encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Constructs a new String by decoding this array of bytes using the
      specified encoding.
      **Limitation:**
      The method is protected by the quota _api.jsStringLength_ that prevents creation of too long strings.


    **Parameters:**
    - encoding - The name of a supported encoding.

    **Returns:**
    - A String representing the decoded array of bytes.

    **Throws:**
    - IllegalArgumentException - If the named encoding is not supported.


---

<!-- prettier-ignore-end -->

<!-- document id=352c626d2d2d571737d689bac4b6eabb84e85b56c541dadf3f2052fadd12d3d0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Cache.md -->

<!-- prettier-ignore-start -->
# Class Cache

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Cache](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md)

The Cache class represents a custom cache.


A cache stores data over multiple requests. Each cartridge can define its own
caches for different business requirements. To limit the
visibility of cache entries by scope, for example, by site, catalog, or
external system, include the scope reference when constructing the
key. For example:


```
   var cache = CacheMgr.getCache( 'SiteConfigurations' );
   cache.get( Site.current.ID + "config", function loadSiteConfiguration() {return loadCfg( Site.current );} );
```




Do not build the cache key using personal user data, since the key might be
visible in log messages.



There is never a guarantee that a stored object can be retrieved from the
cache. The storage allocated for entries is limited and clearing or
invalidation might occur at any time. To maintain the cache size limits, the
cache evicts entries that are less likely to be used again. For example, the
cache might evict an entry because it hasn't been used recently or very
often. Cache entries aren't synchronized between different application
servers.



The cache returns immutable copies of the original objects put into the
cache. Lists are converted to arrays during this process. Only JavaScript
primitive values and tree-like object structures can be stored as entries.
Object structures can consist of arrays, lists, and basic JavaScript
objects. Script API classes are not supported, except [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
and its subclasses. `null` can be stored as a value.
`undefined` can't be stored.



See [CacheMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.CacheMgr.md) for details about how to configure a custom cache.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md#getstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the value associated with key in this cache. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md#getstring-function)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Returns the value associated with key in this cache, or invokes the loader function to generate the entry if  there is no entry found. |
| [invalidate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md#invalidatestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Removes the cache entry for key (if one exists) manually before the cache's eviction strategy goes into effect. |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md#putstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Stores the specified entry directly into the cache, replacing any previously cached entry for key if one exists. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### get(String)
- get(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value associated with key in this cache. If there is no entry in the cache then
      `undefined` is returned.


    **Parameters:**
    - key - The cache key.

    **Returns:**
    - The stored value or `undefined` if no value is found in the cache.


---

### get(String, Function)
- get(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), loader: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value associated with key in this cache, or invokes the loader function to generate the entry if
      there is no entry found. The generated entry is stored for future retrieval. If the loader function returns
      `undefined`, this value is not stored in the cache.


    **Parameters:**
    - key - The cache key.
    - loader - The loader function that is called if no value is stored in the cache.

    **Returns:**
    - The value found in the cache or the value returned from the loader function call.


---

### invalidate(String)
- invalidate(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Removes the cache entry for key (if one exists) manually before the cache's eviction strategy goes into effect.

    **Parameters:**
    - key - The cache key.


---

### put(String, Object)
- put(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Stores the specified entry directly into the cache, replacing any previously cached entry for key if one exists.
      Storing `undefined` as value has the same effect as calling [invalidate(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md#invalidatestring) for that key.


    **Parameters:**
    - key - The cache key.
    - value - The value to be store in the cache.


---

<!-- prettier-ignore-end -->

<!-- document id=b3c492dd0fcde98d888a32b7ab9f2fb52386558bc118dac66b6fe30b08d378f2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.CacheMgr.md -->

<!-- prettier-ignore-start -->
# Class CacheMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.CacheMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.CacheMgr.md)

The CacheMgr class is the entry point for using custom caches.


The CacheMgr can manage multiple custom caches that share one storage space. Each individual cache has a unique ID
and an optional expiration time that specifies the maximum time (in seconds) an entry is stored in the cache. For
registering caches inside the cartridge root folder, a 'package.json' file with a 'caches' entry must exist. The
registration of caches is independent of any site context.


```
"caches": "./caches.json"
```


The caches entry links to a JSON file, with a path relative to the 'package.json' file. This file lists all
registered caches inside the caches property:


```
{
  "caches": [
    {
      "id": "UnlimitedTestCache"
    },
    {
      "id": "TestCacheWithExpiration",
      "expireAfterSeconds": 10
    }
  ]
}
```



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getCache](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.CacheMgr.md#getcachestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the defined cache instance for the given ID. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### getCache(String)
- static getCache(cacheID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Cache](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md)
  - : Returns the defined cache instance for the given ID. Throws an exception when the requested cache has not been
      defined in any caches.json descriptor.


    **Parameters:**
    - cacheID - The ID of the cache.

    **Returns:**
    - The registered cache.


---

<!-- prettier-ignore-end -->

<!-- document id=72bf699b227a9a15dd4949e3271b121c461c4e6aa66bcd51cb41f0b72e9b0fbd url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.CalculateHooks.md -->

<!-- prettier-ignore-start -->
# Class CalculateHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.CalculateHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md)

This interface represents all script hooks that can be registered to customize the order and basket calculation
functionality. It contains the extension points (hook names), and the functions that are called by each extension
point. A function must be defined inside a JavaScript source and must be exported. The script with the exported hook
function must be located inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks'
entry must exist.


```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:


```
"hooks": [
     {"name": "dw.order.calculate", "script": "./calculate.js"}
]
```


A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointCalculate](#extensionpointcalculate): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.calculate" | The extension point name dw.order.calculate. |
| [extensionPointCalculateShipping](#extensionpointcalculateshipping): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.calculateShipping" | The extension point name dw.order.calculateShipping. |
| [extensionPointCalculateTax](#extensionpointcalculatetax): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.calculateTax" | The extension point name dw.order.calculateTax. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [calculate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#calculatelineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | The function is called by extension point [extensionPointCalculate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculate). |
| [calculateShipping](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#calculateshippinglineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | The function is called by extension point [extensionPointCalculateShipping](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculateshipping). |
| [calculateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#calculatetaxlineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | The function is called by extension point [extensionPointCalculateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculatetax). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointCalculate

- extensionPointCalculate: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.calculate"
  - : The extension point name dw.order.calculate.


---

### extensionPointCalculateShipping

- extensionPointCalculateShipping: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.calculateShipping"
  - : The extension point name dw.order.calculateShipping.


---

### extensionPointCalculateTax

- extensionPointCalculateTax: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.calculateTax"
  - : The extension point name dw.order.calculateTax.


---

## Method Details

### calculate(LineItemCtnr)
- calculate(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointCalculate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculate). It provides a single place for
      the line item container calculation.
      
      
      To provide a fallback for existing implementations, the default implementation calls the hook
      dw.ocapi.shop.basket.calculate. However, this hook is deprecated, and calling it will create entries in the
      deprecated API usage logs. You should override this function to use dw.order.calculate instead.
      
      
      
      
      If you provide your own implementation, you should provide and use the following hooks. Best practice is
      to use the hook manager to retrieve them in the calculate hook, and avoid calling them directly.
      
      
      
      - [extensionPointCalculateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculatetax)for tax calculation
      - [extensionPointCalculateShipping](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculateshipping)for shipping calculation


    **Parameters:**
    - lineItemCtnr - the line item container to be (re)calculated.


---

### calculateShipping(LineItemCtnr)
- calculateShipping(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointCalculateShipping](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculateshipping). It provides a single
      place for shipping calculation during the line item container calculation.


    **Parameters:**
    - lineItemCtnr - the line item container to be (re)calculated.


---

### calculateTax(LineItemCtnr)
- calculateTax(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointCalculateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md#extensionpointcalculatetax). It provides a single place
      for tax calculation during the line item container calculation.


    **Parameters:**
    - lineItemCtnr - the line item container to be (re)calculated.


---

<!-- prettier-ignore-end -->

<!-- document id=49b3184f31628dd9c9fc94348a99a6a4b83aff470942b497665900761bd7f565 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Calendar.md -->

<!-- prettier-ignore-start -->
# Class Calendar

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)

Represents a Calendar and is based on the java.util.Calendar
class. Refer to the java.util.Calendar documentation for
more information.


**IMPORTANT NOTE:** Please use the [StringUtils.formatCalendar(Calendar)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatcalendarcalendar)
functions to convert a Calendar object into a String.



## Constant Summary

| Constant | Description |
| --- | --- |
| [AM_PM](#am_pm): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9 | Indicates whether the HOUR is before or after noon. |
| [APRIL](#april): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | Value for the month of year field representing April. |
| [AUGUST](#august): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | Value for the month of year field representing August. |
| [DATE](#date): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Represents a date. |
| [DAY_OF_MONTH](#day_of_month): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Represents a day of the month. |
| [DAY_OF_WEEK](#day_of_week): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | Represents a day of the week. |
| [DAY_OF_WEEK_IN_MONTH](#day_of_week_in_month): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | Represents a day of the week in a month. |
| [DAY_OF_YEAR](#day_of_year): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | Represents a day of the year. |
| [DECEMBER](#december): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11 | Value for the month of year field representing December. |
| [DST_OFFSET](#dst_offset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 16 | Indicates the daylight savings offset in milliseconds. |
| [ERA](#era): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Indicates the era such as 'AD' or 'BC' in the Julian calendar. |
| [FEBRUARY](#february): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Value for the month of year field representing February. |
| [FRIDAY](#friday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | Value for the day of the week field representing Friday. |
| [HOUR](#hour): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | Represents an hour. |
| [HOUR_OF_DAY](#hour_of_day): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11 | Represents an hour of the day. |
| [INPUT_DATE_PATTERN](#input_date_pattern): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | The input date pattern, for instance MM/dd/yyyy |
| [INPUT_DATE_TIME_PATTERN](#input_date_time_pattern): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | The input date time pattern, for instance MM/dd/yyyy h:mm a |
| [INPUT_TIME_PATTERN](#input_time_pattern): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | The input time pattern, for instance h:mm a |
| [JANUARY](#january): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Value for the month of year field representing January. |
| [JULY](#july): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | Value for the month of year field representing July. |
| [JUNE](#june): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Value for the month of year field representing June. |
| [LONG_DATE_PATTERN](#long_date_pattern): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | The long date pattern, for instance MMM/d/yyyy |
| [MARCH](#march): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Value for the month of year field representing March. |
| [MAY](#may): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Value for the month of year field representing May. |
| [MILLISECOND](#millisecond): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 14 | Represents a millisecond. |
| [MINUTE](#minute): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12 | Represents a minute. |
| [MONDAY](#monday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Value for the day of the week field representing Monday. |
| [MONTH](#month): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Represents a month where the first month of the year is 0. |
| [NOVEMBER](#november): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | Value for the month of year field representing November. |
| [OCTOBER](#october): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9 | Value for the month of year field representing October. |
| [SATURDAY](#saturday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | Value for the day of the week field representing Saturday. |
| [SECOND](#second): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13 | Represents a second. |
| [SEPTEMBER](#september): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | Value for the month of year field representing September. |
| [SHORT_DATE_PATTERN](#short_date_pattern): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | The short date pattern, for instance M/d/yy |
| [SUNDAY](#sunday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Value for the day of the week field representing Sunday. |
| [THURSDAY](#thursday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Value for the day of the week field representing Thursday. |
| [TIME_PATTERN](#time_pattern): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | The time pattern, for instance h:mm:ss a |
| [TUESDAY](#tuesday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | Value for the day of the week field representing Tuesday. |
| [WEDNESDAY](#wednesday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Value for the day of the week field representing Wednesday. |
| [WEEK_OF_MONTH](#week_of_month): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Represents a week of the month. |
| [WEEK_OF_YEAR](#week_of_year): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | Represents a week in the year. |
| [YEAR](#year): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Represents a year. |
| [ZONE_OFFSET](#zone_offset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 15 | Indicates the raw offset from GMT in milliseconds. |

## Property Summary

| Property | Description |
| --- | --- |
| [firstDayOfWeek](#firstdayofweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the first day of the week base on locale context. |
| [time](#time): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns the current time stamp of this calendar. |
| [timeZone](#timezone): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the current time zone of this calendar. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Calendar](#calendar)() | Creates a new Calendar object that is set to the current  time. |
| [Calendar](#calendardate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Creates a new Calendar object for the given Date object. |

## Method Summary

| Method | Description |
| --- | --- |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#addnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Adds or subtracts the specified amount of time to the given  calendar field, based on the calendar's rules. |
| [after](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#afterobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Indicates if this Calendar represents a time after  the time represented by the specified Object. |
| [before](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#beforeobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Indicates if this Calendar represents a time before  the time represented by the specified Object. |
| [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#clear)() | Sets all the calendar field values and the time value  (millisecond offset from the Epoch) of this Calendar undefined. |
| [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#clearnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the given calendar field value and the time value  (millisecond offset from the Epoch) of this Calendar undefined. |
| [compareTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#comparetocalendar)([Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)) | Compares the time values (millisecond offsets from the Epoch)  represented by two Calendar objects. |
| [equals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#equalsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Compares two calendar values whether they are equivalent. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value of the given calendar field. |
| [getActualMaximum](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#getactualmaximumnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the maximum value that the specified calendar  field could have. |
| [getActualMinimum](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#getactualminimumnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the minimum value that the specified calendar  field could have. |
| [getFirstDayOfWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#getfirstdayofweek)() | Returns the first day of the week base on locale context. |
| [getMaximum](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#getmaximumnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the maximum value for the given calendar  field. |
| [getMinimum](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#getminimumnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the minimum value for the given calendar  field. |
| [getTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#gettime)() | Returns the current time stamp of this calendar. |
| [getTimeZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#gettimezone)() | Returns the current time zone of this calendar. |
| [hashCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#hashcode)() | Calculates the hash code for a calendar; |
| [isLeapYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#isleapyearnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Indicates if the specified year is a leap year. |
| [isSameDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#issamedaycalendar)([Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)) | Checks, whether two calendar dates fall on the same day. |
| [isSameDayByTimestamp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#issamedaybytimestampcalendar)([Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)) | Checks, whether two calendar dates fall on the same day. |
| [isSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#issetnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Indicates if the field is set. |
| [parseByFormat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#parsebyformatstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parses the string according to the date and time format pattern and set  the time at this calendar object. |
| [parseByLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#parsebylocalestring-string-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Parses the string according the date format pattern of the given locale. |
| [roll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#rollnumber-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Rolls the specified field up or down one value. |
| [roll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#rollnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Rolls the specified field using the specified value. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#setnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the given calendar field to the given value. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#setnumber-number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the values for the calendar fields YEAR, MONTH, and DAY\_OF\_MONTH. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#setnumber-number-number-number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the values for the calendar fields YEAR, MONTH,  DAY\_OF\_MONTH, HOUR\_OF\_DAY, and MINUTE. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#setnumber-number-number-number-number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the values for the calendar fields YEAR, MONTH,  DAY\_OF\_MONTH, HOUR\_OF\_DAY, MINUTE and SECOND. |
| [setFirstDayOfWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#setfirstdayofweeknumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets what the first day of the week is. |
| [setTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#settimedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the current time stamp of this calendar.<br/>  <br/>  **WARNING:** Keep in mind that the set Date object's time is always           interpreted in the time zone GMT. |
| [setTimeZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#settimezonestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the current time zone of this calendar.<br/>  <br/>  **WARNING:** Keep in mind that the time stamp represented by the calendar is           always interpreted in the time zone GMT. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### AM_PM

- AM_PM: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9
  - : Indicates whether the HOUR is before or after noon.


---

### APRIL

- APRIL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : Value for the month of year field representing April.


---

### AUGUST

- AUGUST: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : Value for the month of year field representing August.


---

### DATE

- DATE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Represents a date.


---

### DAY_OF_MONTH

- DAY_OF_MONTH: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Represents a day of the month.


---

### DAY_OF_WEEK

- DAY_OF_WEEK: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : Represents a day of the week.


---

### DAY_OF_WEEK_IN_MONTH

- DAY_OF_WEEK_IN_MONTH: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : Represents a day of the week in a month.


---

### DAY_OF_YEAR

- DAY_OF_YEAR: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : Represents a day of the year.


---

### DECEMBER

- DECEMBER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11
  - : Value for the month of year field representing December.


---

### DST_OFFSET

- DST_OFFSET: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 16
  - : Indicates the daylight savings offset in milliseconds.


---

### ERA

- ERA: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Indicates the era such as 'AD' or 'BC' in the Julian calendar.


---

### FEBRUARY

- FEBRUARY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Value for the month of year field representing February.


---

### FRIDAY

- FRIDAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : Value for the day of the week field representing Friday.


---

### HOUR

- HOUR: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : Represents an hour.


---

### HOUR_OF_DAY

- HOUR_OF_DAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11
  - : Represents an hour of the day.


---

### INPUT_DATE_PATTERN

- INPUT_DATE_PATTERN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : The input date pattern, for instance MM/dd/yyyy


---

### INPUT_DATE_TIME_PATTERN

- INPUT_DATE_TIME_PATTERN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : The input date time pattern, for instance MM/dd/yyyy h:mm a


---

### INPUT_TIME_PATTERN

- INPUT_TIME_PATTERN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : The input time pattern, for instance h:mm a


---

### JANUARY

- JANUARY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Value for the month of year field representing January.


---

### JULY

- JULY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : Value for the month of year field representing July.


---

### JUNE

- JUNE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Value for the month of year field representing June.


---

### LONG_DATE_PATTERN

- LONG_DATE_PATTERN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : The long date pattern, for instance MMM/d/yyyy


---

### MARCH

- MARCH: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Value for the month of year field representing March.


---

### MAY

- MAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Value for the month of year field representing May.


---

### MILLISECOND

- MILLISECOND: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 14
  - : Represents a millisecond.


---

### MINUTE

- MINUTE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12
  - : Represents a minute.


---

### MONDAY

- MONDAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Value for the day of the week field representing Monday.


---

### MONTH

- MONTH: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Represents a month where the first month of the year is 0.


---

### NOVEMBER

- NOVEMBER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : Value for the month of year field representing November.


---

### OCTOBER

- OCTOBER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9
  - : Value for the month of year field representing October.


---

### SATURDAY

- SATURDAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : Value for the day of the week field representing Saturday.


---

### SECOND

- SECOND: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13
  - : Represents a second.


---

### SEPTEMBER

- SEPTEMBER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : Value for the month of year field representing September.


---

### SHORT_DATE_PATTERN

- SHORT_DATE_PATTERN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : The short date pattern, for instance M/d/yy


---

### SUNDAY

- SUNDAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Value for the day of the week field representing Sunday.


---

### THURSDAY

- THURSDAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Value for the day of the week field representing Thursday.


---

### TIME_PATTERN

- TIME_PATTERN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : The time pattern, for instance h:mm:ss a


---

### TUESDAY

- TUESDAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : Value for the day of the week field representing Tuesday.


---

### WEDNESDAY

- WEDNESDAY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Value for the day of the week field representing Wednesday.


---

### WEEK_OF_MONTH

- WEEK_OF_MONTH: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Represents a week of the month.


---

### WEEK_OF_YEAR

- WEEK_OF_YEAR: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : Represents a week in the year.


---

### YEAR

- YEAR: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Represents a year.


---

### ZONE_OFFSET

- ZONE_OFFSET: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 15
  - : Indicates the raw offset from GMT in milliseconds.


---

## Property Details

### firstDayOfWeek
- firstDayOfWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the first day of the week base on locale context. For example, in the US
      the first day of the week is SUNDAY. However, in France the
      first day of the week is MONDAY.



---

### time
- time: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the current time stamp of this calendar. This method
      is also used to convert a Calendar into a Date.
      
      
      
      **WARNING:** Keep in mind that the returned Date object's time is always
               interpreted in the time zone GMT. This means time zone information
               set at the calendar object will not be honored and gets lost.



---

### timeZone
- timeZone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current time zone of this calendar.


---

## Constructor Details

### Calendar()
- Calendar()
  - : Creates a new Calendar object that is set to the current
      time. The default time zone of the Calendar object is GMT.
      
      
      
      **WARNING:** Keep in mind that the time stamp represented by the new calendar
               is always interpreted in the time zone GMT. This means time zone
               information at the calendar object needs to be set separately by
               using the [setTimeZone(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#settimezonestring) method.



---

### Calendar(Date)
- Calendar(date: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md))
  - : Creates a new Calendar object for the given Date object. The time is set to
      the given Date object's time. The default time zone of the Calendar object is GMT.
      
      
      
      **WARNING:** Keep in mind that the given Date object is always
               interpreted in the time zone GMT. This means time zone
               information at the calendar object needs to be set separately by
               using the [setTimeZone(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#settimezonestring) method.


    **Parameters:**
    - date - the date for which the calendar will be set.


---

## Method Details

### add(Number, Number)
- add(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Adds or subtracts the specified amount of time to the given
      calendar field, based on the calendar's rules.


    **Parameters:**
    - field - the calendar field.
    - value - the amount of date or time to be added to the field


---

### after(Object)
- after(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if this Calendar represents a time after
      the time represented by the specified Object.


    **Parameters:**
    - obj - the object to test.

    **Returns:**
    - true if this Calendar represents a time after
      the time represented by the specified Object, false otherwise.



---

### before(Object)
- before(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if this Calendar represents a time before
      the time represented by the specified Object.


    **Parameters:**
    - obj - the object to test.

    **Returns:**
    - true if this Calendar represents a time before
      the time represented by the specified Object, false otherwise.



---

### clear()
- clear(): void
  - : Sets all the calendar field values and the time value
      (millisecond offset from the Epoch) of this Calendar undefined.



---

### clear(Number)
- clear(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the given calendar field value and the time value
      (millisecond offset from the Epoch) of this Calendar undefined.


    **Parameters:**
    - field - the calendar field to be cleared.


---

### compareTo(Calendar)
- compareTo(anotherCalendar: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Compares the time values (millisecond offsets from the Epoch)
      represented by two Calendar objects.


    **Parameters:**
    - anotherCalendar - the Calendar to be compared.

    **Returns:**
    - the value 0 if the time represented by the argument is equal
      to the time represented by this Calendar; a value less than 0 if
      the time of this Calendar is before the time represented by the
      argument; and a value greater than 0 if the time of this Calendar
      is after the time represented by the argument.



---

### equals(Object)
- equals(other: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Compares two calendar values whether they are equivalent.

    **Parameters:**
    - other - the object to compare against this calendar.


---

### get(Number)
- get(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the given calendar field.

    **Parameters:**
    - field - the calendar field to retrieve.

    **Returns:**
    - the value for the given calendar field.


---

### getActualMaximum(Number)
- getActualMaximum(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum value that the specified calendar
      field could have.


    **Parameters:**
    - field - the calendar field.

    **Returns:**
    - the maximum value that the specified calendar
      field could have.



---

### getActualMinimum(Number)
- getActualMinimum(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the minimum value that the specified calendar
      field could have.


    **Parameters:**
    - field - the calendar field.

    **Returns:**
    - the minimum value that the specified calendar
      field could have.



---

### getFirstDayOfWeek()
- getFirstDayOfWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the first day of the week base on locale context. For example, in the US
      the first day of the week is SUNDAY. However, in France the
      first day of the week is MONDAY.


    **Returns:**
    - the first day of the week base on locale context. For example, in the US
      the first day of the week is SUNDAY. However, in France the
      first day of the week is MONDAY.



---

### getMaximum(Number)
- getMaximum(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum value for the given calendar
      field.


    **Parameters:**
    - field - the calendar field.

    **Returns:**
    - the maximum value for the given calendar
      field.



---

### getMinimum(Number)
- getMinimum(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the minimum value for the given calendar
      field.


    **Parameters:**
    - field - the calendar field.

    **Returns:**
    - the minimum value for the given calendar
      field.



---

### getTime()
- getTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the current time stamp of this calendar. This method
      is also used to convert a Calendar into a Date.
      
      
      
      **WARNING:** Keep in mind that the returned Date object's time is always
               interpreted in the time zone GMT. This means time zone information
               set at the calendar object will not be honored and gets lost.


    **Returns:**
    - the current time stamp of this calendar as a Date.


---

### getTimeZone()
- getTimeZone(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current time zone of this calendar.

    **Returns:**
    - the current time zone of this calendar.


---

### hashCode()
- hashCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Calculates the hash code for a calendar;


---

### isLeapYear(Number)
- isLeapYear(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if the specified year is a leap year.

    **Parameters:**
    - year - the year to test.

    **Returns:**
    - true if the specified year is a leap year.


---

### isSameDay(Calendar)
- isSameDay(other: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks, whether two calendar dates fall on the same day.
      
      
      The method performs comparison based on both calendar's
      field values by honoring the defined time zones.
      
      
      
      
      Examples:
      
      
      
      ```
      new Calendar( new Date( "2002/02/28 13:45" ).isSameDay( new Calendar( new Date( "2002/02/28 06:01" ) ) );
      ```
      
      would return true.
      
      ```
      new Calendar( new Date( "2002/02/28 13:45" ).isSameDay( new Calendar( new Date( "2002/02/12 13:45" ) ) );
      ```
      
      would return false.
      
      ```
      new Calendar( new Date( "2002/02/28 13:45" ).isSameDay( new Calendar( new Date( "1970/02/28 13:45" ) ) );
      ```
      
      would return false.
      
      ```
      var cal1 = new Calendar( new Date( "2002/02/28 02:00" );
      cal1.setTimeZone( "Etc/GMT+1" );
      var cal2 = new Calendar( new Date( "2002/02/28 00:00" );
      cal2.setTimeZone( "Etc/GMT+1" );
      cal1.isSameDay( cal2 );
      ```
      
      would return false since the time zone is applied first which results in comparing `2002/02/28 01:00` for `cal1`
      with `2002/02/27 23:00` for `cal2`.


    **Parameters:**
    - other - the calendar to compare against this calendar.


---

### isSameDayByTimestamp(Calendar)
- isSameDayByTimestamp(other: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks, whether two calendar dates fall on the same day.
      
      
      The method performs comparison based on both calendar's
      time stamps by ignoring any defined time zones.
      
      
      
      
      Examples:
      
      
      
      ```
      new Calendar( new Date( "2002/02/28 13:45" ).isSameDayByTimestamp( new Calendar( new Date( "2002/02/28 06:01" ) ) );
      ```
      
      would return true.
      
      ```
      new Calendar( new Date( "2002/02/28 13:45" ).isSameDayByTimestamp( new Calendar( new Date( "2002/02/12 13:45" ) ) );
      ```
      
      would return false.
      
      ```
      new Calendar( new Date( "2002/02/28 13:45" ).isSameDayByTimestamp( new Calendar( new Date( "1970/02/28 13:45" ) ) );
      ```
      
      would return false.
      
      ```
      var cal1 = new Calendar( new Date( "2002/02/28 02:00" );
      cal1.setTimeZone( "Etc/GMT+1" );
      var cal2 = new Calendar( new Date( "2002/02/28 00:00" );
      cal2.setTimeZone( "Etc/GMT+1" );
      cal1.isSameDayByTimestamp( cal2 );
      ```
      
      would return true since the time zone is not applied first which results in comparing `2002/02/28 02:00` for `cal1`
      with `2002/02/28 00:00` for `cal2`.


    **Parameters:**
    - other - the calendar to compare against this calendar.


---

### isSet(Number)
- isSet(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if the field is set.

    **Parameters:**
    - field - the field to test.

    **Returns:**
    - true if the field is set, false otherwise.


---

### parseByFormat(String, String)
- parseByFormat(timeString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Parses the string according to the date and time format pattern and set
      the time at this calendar object. For the specification of the date and
      time format pattern see the javadoc of the JDK class java.text.SimpleDateFormat.
      If a time zone is included in the format string,
      this time zone is used to interpet the time. Otherwise the currently set
      calendar time zone is used to parse the given time string.


    **Parameters:**
    - timeString - the time string to parsed
    - format - the time format string


---

### parseByLocale(String, String, Number)
- parseByLocale(timeString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), pattern: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Parses the string according the date format pattern of the given locale.
      If the locale name is invalid, an exception is thrown. The currently set
      calendar time zone is used to parse the given time string.


    **Parameters:**
    - timeString - the time string to parsed
    - locale - the locale id, which defines the date format pattern
    - pattern - the pattern is one of calendar pattern e.g. SHORT\_DATE\_PATTERN                 as defined in the regional settings for the locale


---

### roll(Number, Boolean)
- roll(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), up: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Rolls the specified field up or down one value.

    **Parameters:**
    - field - the field to roll.
    - up - if true rolls the field up, if false  rolls the field down.


---

### roll(Number, Number)
- roll(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Rolls the specified field using the specified value.

    **Parameters:**
    - field - the field to roll.
    - amount - the amount to roll the field.


---

### set(Number, Number)
- set(field: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the given calendar field to the given value.

    **Parameters:**
    - field - the calendar field to set.
    - value - the value to set in the field.


---

### set(Number, Number, Number)
- set(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), month: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), date: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the values for the calendar fields YEAR, MONTH, and DAY\_OF\_MONTH.

    **Parameters:**
    - year - the value for year.
    - month - the value for month.
    - date - the value for date.


---

### set(Number, Number, Number, Number, Number)
- set(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), month: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), date: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), hourOfDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), minute: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the values for the calendar fields YEAR, MONTH,
      DAY\_OF\_MONTH, HOUR\_OF\_DAY, and MINUTE.


    **Parameters:**
    - year - the value for year.
    - month - the value for month.
    - date - the value for date.
    - hourOfDay - the value for hour of day.
    - minute - the value for minute.


---

### set(Number, Number, Number, Number, Number, Number)
- set(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), month: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), date: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), hourOfDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), minute: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), second: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the values for the calendar fields YEAR, MONTH,
      DAY\_OF\_MONTH, HOUR\_OF\_DAY, MINUTE and SECOND.


    **Parameters:**
    - year - the value for year.
    - month - the value for month.
    - date - the value for date.
    - hourOfDay - the value for hour of day.
    - minute - the value for minute.
    - second - the value for second.


---

### setFirstDayOfWeek(Number)
- setFirstDayOfWeek(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets what the first day of the week is.

    **Parameters:**
    - value - the day to set as the first day of the week.


---

### setTime(Date)
- setTime(date: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the current time stamp of this calendar.
      
      
      
      **WARNING:** Keep in mind that the set Date object's time is always
               interpreted in the time zone GMT. This means that time zone
               information at the calendar object needs to be set separately by
               using the [setTimeZone(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md#settimezonestring) method.


    **Parameters:**
    - date - the current time stamp of this calendar.


---

### setTimeZone(String)
- setTimeZone(timeZone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the current time zone of this calendar.
      
      
      
      **WARNING:** Keep in mind that the time stamp represented by the calendar is
               always interpreted in the time zone GMT. Changing the time zone will not
               change the calendar's time stamp.


    **Parameters:**
    - timeZone - the current time zone value to set.


---

<!-- prettier-ignore-end -->

<!-- document id=5a5c0df129ae5528785bf6aff1b811895ecf209ffe15c2907211301ee8f8761d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.Campaign.md -->

<!-- prettier-ignore-start -->
# Class Campaign

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.campaign.Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md)

A Campaign is a set of experiences (or site configurations) which may be
deployed as a single unit for a given time frame.  The system currently
supports 3 types of experience that may be assigned to a campaign:


- Promotions
- Slot Configurations
- Sorting Rules


This list may be extended in the future.


A campaign can have a start and end date or be open-ended.  It may also have
"qualifiers" which determine which customers the campaign applies to.
The currently supported qualifiers are:


- Customer groups (where "Everyone" is a possible customer group)
- Source codes
- Coupons


A campaign can have list of stores or store groups where it can be applicable to.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique campaign ID. |
| [active](#active): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the campaign is currently active, otherwise  'false'. |
| [applicableInStore](#applicableinstore): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if campaign is applicable to store, otherwise false. |
| [applicableOnline](#applicableonline): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if campaign is applicable to online site, otherwise false. |
| [coupons](#coupons): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the coupons assigned to the campaign. |
| [customerGroups](#customergroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the customer groups assigned to the campaign. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the internal description of the campaign. |
| [enabled](#enabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if campaign is enabled, otherwise false. |
| [endDate](#enddate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the end date of the campaign. |
| [promotions](#promotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns promotions defined in this campaign in no particular order. |
| [sourceCodeGroups](#sourcecodegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the source codes assigned to the campaign. |
| [startDate](#startdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the start date of the campaign. |
| [storeGroups](#storegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns store groups assigned to the campaign. |
| [stores](#stores): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns stores assigned to the campaign. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCoupons](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getcoupons)() | Returns the coupons assigned to the campaign. |
| [getCustomerGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getcustomergroups)() | Returns the customer groups assigned to the campaign. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getdescription)() | Returns the internal description of the campaign. |
| [getEndDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getenddate)() | Returns the end date of the campaign. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getid)() | Returns the unique campaign ID. |
| [getPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getpromotions)() | Returns promotions defined in this campaign in no particular order. |
| [getSourceCodeGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getsourcecodegroups)() | Returns the source codes assigned to the campaign. |
| [getStartDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getstartdate)() | Returns the start date of the campaign. |
| [getStoreGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getstoregroups)() | Returns store groups assigned to the campaign. |
| [getStores](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#getstores)() | Returns stores assigned to the campaign. |
| [isActive](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#isactive)() | Returns 'true' if the campaign is currently active, otherwise  'false'. |
| [isApplicableInStore](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#isapplicableinstore)() | Returns true if campaign is applicable to store, otherwise false. |
| [isApplicableOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#isapplicableonline)() | Returns true if campaign is applicable to online site, otherwise false. |
| [isEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md#isenabled)() | Returns true if campaign is enabled, otherwise false. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique campaign ID.


---

### active
- active: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the campaign is currently active, otherwise
      'false'. 
      
      A campaign is active if it is enabled and scheduled for _now_.



---

### applicableInStore
- applicableInStore: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if campaign is applicable to store, otherwise false.


---

### applicableOnline
- applicableOnline: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if campaign is applicable to online site, otherwise false.


---

### coupons
- coupons: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the coupons assigned to the campaign.


---

### customerGroups
- customerGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the customer groups assigned to the campaign.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the internal description of the campaign.


---

### enabled
- enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if campaign is enabled, otherwise false.


---

### endDate
- endDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the end date of the campaign. If no end date is defined for the
      campaign, null is returned. A campaign w/o end date will run forever.



---

### promotions
- promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns promotions defined in this campaign in no particular order.


---

### sourceCodeGroups
- sourceCodeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the source codes assigned to the campaign.


---

### startDate
- startDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the start date of the campaign. If no start date is defined for the
      campaign, null is returned. A campaign w/o start date is immediately
      effective.



---

### storeGroups
- storeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns store groups assigned to the campaign.


---

### stores
- stores: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns stores assigned to the campaign.


---

## Method Details

### getCoupons()
- getCoupons(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the coupons assigned to the campaign.

    **Returns:**
    - All coupons assigned to the campaign.


---

### getCustomerGroups()
- getCustomerGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the customer groups assigned to the campaign.

    **Returns:**
    - Customer groups assigned to campaign.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the internal description of the campaign.

    **Returns:**
    - Internal description of campaign.


---

### getEndDate()
- getEndDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the end date of the campaign. If no end date is defined for the
      campaign, null is returned. A campaign w/o end date will run forever.


    **Returns:**
    - End date of campaign.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique campaign ID.

    **Returns:**
    - ID of the campaign.


---

### getPromotions()
- getPromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns promotions defined in this campaign in no particular order.

    **Returns:**
    - All promotions defined in campaign.


---

### getSourceCodeGroups()
- getSourceCodeGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the source codes assigned to the campaign.

    **Returns:**
    - All source code groups assigned to campaign.


---

### getStartDate()
- getStartDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the start date of the campaign. If no start date is defined for the
      campaign, null is returned. A campaign w/o start date is immediately
      effective.


    **Returns:**
    - Start date of campaign.


---

### getStoreGroups()
- getStoreGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns store groups assigned to the campaign.

    **Returns:**
    - All store groups assigned to the campaign.


---

### getStores()
- getStores(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns stores assigned to the campaign.

    **Returns:**
    - All stores assigned to the campaign.


---

### isActive()
- isActive(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the campaign is currently active, otherwise
      'false'. 
      
      A campaign is active if it is enabled and scheduled for _now_.


    **Returns:**
    - true of campaign is active, otherwise false.


---

### isApplicableInStore()
- isApplicableInStore(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if campaign is applicable to store, otherwise false.

    **Returns:**
    - true if campaign is applicable to store, otherwise false.


---

### isApplicableOnline()
- isApplicableOnline(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if campaign is applicable to online site, otherwise false.

    **Returns:**
    - true if campaign is applicable to online site, otherwise false.


---

### isEnabled()
- isEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if campaign is enabled, otherwise false.

    **Returns:**
    - true if campaign is enabled, otherwise false.


---

<!-- prettier-ignore-end -->

<!-- document id=52a3b3221fb7ef3d97abb9f012b498fc2e6a09e2e3890f3bd23c9c6f830850cc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.CampaignMgr.md -->

<!-- prettier-ignore-start -->
# Class CampaignMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.CampaignMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md)

CampaignMgr provides static methods for managing campaign-specific operations
such as accessing promotions or updating promotion line items.


**Deprecated:**
**warning:** Use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) instead.

## Property Summary

| Property | Description |
| --- | --- |
| ~~[applicablePromotions](#applicablepromotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)` | Returns the enabled promotions of active campaigns applicable for the  current customer and source code. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| ~~static [applyBonusPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applybonuspromotionslineitemctnr-collection)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))~~ | This method has been deprecated and should not be used anymore. |
| ~~static [applyOrderPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applyorderpromotionslineitemctnr-collection)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))~~ | Applies the applicable order promotions in the specified collection to the  specified line item container. |
| ~~static [applyProductPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applyproductpromotionslineitemctnr-collection)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))~~ | Applies all applicable product promotions in the specified collection to the  specified line item container. |
| ~~static [applyShippingPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applyshippingpromotionslineitemctnr-collection)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))~~ | Applies all applicable shipping promotions in the specified collection to  the specified line item container. |
| ~~static [getApplicableConditionalPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getapplicableconditionalpromotionsproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md))~~ | Returns the enabled promotions of active campaigns applicable for the  current customer and source code for which the specified product  is a qualifiying product. |
| ~~static [getApplicablePromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getapplicablepromotions)()~~ | Returns the enabled promotions of active campaigns applicable for the  current customer and source code. |
| ~~static [getApplicablePromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getapplicablepromotionsproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md))~~ | Returns the enabled promotions of active campaigns applicable for the  current customer and source code for which the specified product is  a discounted product. |
| ~~static [getApplicablePromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getapplicablepromotionslineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md))~~ | Returns the enabled promotions of active campaigns applicable for the  current customer, source code and any coupon contained in the specified  line item container. |
| ~~static [getCampaignByID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getcampaignbyidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns the campaign identified by the specified ID. |
| ~~static [getConditionalPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getconditionalpromotionsproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md))~~ | Returns the enabled promotions of active campaigns for which the  specified product is a qualifiying product. |
| ~~static [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getpromotionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns the promotion associated with the specified coupon code. |
| ~~static [getPromotionByCouponCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getpromotionbycouponcodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns the promotion associated with the specified coupon code. |
| ~~static [getPromotionByID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getpromotionbyidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns the promotion identified by the specified ID. |
| ~~static [getPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getpromotionsproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md))~~ | Returns the enabled promotions of active campaigns for which the  specified product is a discounted product. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### applicablePromotions
- ~~applicablePromotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)`
  - : Returns the enabled promotions of active campaigns applicable for the
      current customer and source code.
      
      
      Note that this method does not return any coupon-based promotions.


    **Deprecated:**
**warning:** Use [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
             [PromotionPlan.getPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getpromotions)

---

## Method Details

### applyBonusPromotions(LineItemCtnr, Collection)
- ~~static applyBonusPromotions(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : This method has been deprecated and should not be used anymore.
      Instead, use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) to apply promotions to
      line item containers.
      
      
      The method does nothing, since bonus promotions  are applied as product
      or order promotions using methods
      [applyProductPromotions(LineItemCtnr, Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applyproductpromotionslineitemctnr-collection) and
      [applyOrderPromotions(LineItemCtnr, Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applyorderpromotionslineitemctnr-collection).
      
      
      The method returns 'true' if any the line item container contains
      any bonus product line items, and otherwise false.


    **Parameters:**
    - lineItemCtnr - Basket or order
    - promotions - Parameter not used, can be null

    **Returns:**
    - True if line item container contains bonus product line items, else false

    **Deprecated:**
**warning:** Use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) instead.

---

### applyOrderPromotions(LineItemCtnr, Collection)
- ~~static applyOrderPromotions(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Applies the applicable order promotions in the specified collection to the
      specified line item container.
      
      
      This method has been deprecated and should not be used anymore.
      Instead, use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) to apply promotions to
      line item containers.
      
      
      Note that the method does also apply any bonus discounts defined
      as order promotions (see also [applyBonusPromotions(LineItemCtnr, Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applybonuspromotionslineitemctnr-collection)).


    **Parameters:**
    - lineItemCtnr - basket or order
    - promotions - list of all promotions to be applied

    **Returns:**
    - true if changes were made to the line item container, false otherwise.

    **Deprecated:**
**warning:** Use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md)

---

### applyProductPromotions(LineItemCtnr, Collection)
- ~~static applyProductPromotions(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Applies all applicable product promotions in the specified collection to the
      specified line item container.
      
      
      This method has been deprecated and should not be used anymore.
      Instead, use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) to apply promotions to
      line item containers.
      
      
      Note that the method does also apply any bonus discounts defined
      as product promotions (see also [applyBonusPromotions(LineItemCtnr, Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#applybonuspromotionslineitemctnr-collection)).


    **Parameters:**
    - lineItemCtnr - basket or order
    - promotions - list of all promotions to be applied

    **Returns:**
    - true if changes were made to the line item container, false otherwise.

    **Deprecated:**
**warning:** Use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md)

---

### applyShippingPromotions(LineItemCtnr, Collection)
- ~~static applyShippingPromotions(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Applies all applicable shipping promotions in the specified collection to
      the specified line item container.
      
      
      This method has been deprecated and should not be used anymore.
      Instead, use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) to apply promotions to
      line item containers.


    **Parameters:**
    - lineItemCtnr - basket or order
    - promotions - list of all promotions to be applied

    **Returns:**
    - true if changes were made to the line item container, false otherwise.

    **Deprecated:**
**warning:** Use [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md)

---

### getApplicableConditionalPromotions(Product)
- ~~static getApplicableConditionalPromotions(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the enabled promotions of active campaigns applicable for the
      current customer and source code for which the specified product
      is a qualifiying product.
      
      
      As a replacement of this deprecated method, use
      [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct).
      Unlike [getApplicableConditionalPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getapplicableconditionalpromotionsproduct),
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)
      returns all promotions related to the specified product, regardless
      of whether the product is qualifying, discounted, or both, and
      also returns promotions where the product is a bonus product.


    **Parameters:**
    - product - Qualifying product

    **Returns:**
    - List of active promotions

    **Deprecated:**
**warning:** Use [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
                 [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)

---

### getApplicablePromotions()
- ~~static getApplicablePromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the enabled promotions of active campaigns applicable for the
      current customer and source code.
      
      
      Note that this method does not return any coupon-based promotions.


    **Returns:**
    - List of active promotions

    **Deprecated:**
**warning:** Use [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
             [PromotionPlan.getPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getpromotions)

---

### getApplicablePromotions(Product)
- ~~static getApplicablePromotions(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the enabled promotions of active campaigns applicable for the
      current customer and source code for which the specified product is
      a discounted product.
      
      
      Note that this method does not return any coupon-based promotions.
      
      
      As a replacement of this deprecated method, use
      [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct).
      Unlike [getApplicablePromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getapplicablepromotionsproduct),
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)
      returns all promotions related to the specified product, regardless
      of whether the product is qualifying, discounted, or both, and
      also returns promotions where the product is a bonus product.


    **Parameters:**
    - product - The product whose promotions are returned.

    **Returns:**
    - A list of promotions

    **Deprecated:**
**warning:** Use [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
                 [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)

---

### getApplicablePromotions(LineItemCtnr)
- ~~static getApplicablePromotions(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the enabled promotions of active campaigns applicable for the
      current customer, source code and any coupon contained in the specified
      line item container.
      
      
      Note that although the method has been deprecated, no replacement
      method is provided.


    **Parameters:**
    - lineItemCtnr - the basket or order

    **Returns:**
    - list of all applicable promotion for the given basket or order

    **Deprecated:**
**warning:** There is no replacement for this method.

---

### getCampaignByID(String)
- ~~static getCampaignByID(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md)~~
  - : Returns the campaign identified by the specified ID.

    **Parameters:**
    - id - Campaign ID

    **Returns:**
    - Campaign or null if not found

    **Deprecated:**
**warning:** Use [PromotionMgr.getCampaign(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getcampaignstring)

---

### getConditionalPromotions(Product)
- ~~static getConditionalPromotions(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the enabled promotions of active campaigns for which the
      specified product is a qualifiying product. 
      
      Note that the method also returns coupon-based promotions.
      
      
      As a replacement of this deprecated method, use
      [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct).
      Unlike [getConditionalPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getconditionalpromotionsproduct),
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)
      returns all promotions related to the specified product, regardless
      of whether the product is qualifying, discounted, or both, and
      also returns promotions where the product is a bonus product.


    **Parameters:**
    - product - The product whose conditional promotions are returned.

    **Returns:**
    - A list of promotions

    **Deprecated:**
**warning:** Use [PromotionMgr.getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions) and
                 [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)

---

### getPromotion(String)
- ~~static getPromotion(couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)~~
  - : Returns the promotion associated with the specified coupon code.

    **Parameters:**
    - couponCode - The coupon code used to lookup the promotion

    **Returns:**
    - The resolved promotion object or null if none was found

    **Deprecated:**
**warning:** Coupons are now related to multiple promotions. Method
                  returns the first promotion associated with the coupon
                  code in case of multiple assigned promotions.

---

### getPromotionByCouponCode(String)
- ~~static getPromotionByCouponCode(couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)~~
  - : Returns the promotion associated with the specified coupon code.

    **Parameters:**
    - couponCode - Coupon code

    **Returns:**
    - The associated promotion or null

    **Deprecated:**
**warning:** Coupons are now related to multiple promotions. Method
                  returns the first promotion associated with the coupon
                  in case of multiple assigned promotions

---

### getPromotionByID(String)
- ~~static getPromotionByID(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)~~
  - : Returns the promotion identified by the specified ID.

    **Parameters:**
    - id - Promotion ID

    **Returns:**
    - Promotion or null if not found

    **Deprecated:**
**warning:** Use [PromotionMgr.getPromotion(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getpromotionstring)

---

### getPromotions(Product)
- ~~static getPromotions(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the enabled promotions of active campaigns for which the
      specified product is a discounted product. 
      
      Note that method does only return promotions based on customer groups
      or source codes.
      
      
      As a replacement of this deprecated method, use
      [PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct).
      Unlike [getPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md#getpromotionsproduct),
      [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)
      returns all promotions related to the specified product, regardless
      of whether the product is qualifying, discounted, or both, and
      also returns promotions where the product is a bonus product.


    **Parameters:**
    - product - Discounted product

    **Returns:**
    - List of promotions

    **Deprecated:**
**warning:** Use [PromotionMgr.getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions) and
                 [PromotionPlan.getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)

---

<!-- prettier-ignore-end -->

<!-- document id=e683363f7d9e23e42e4d90d267c5034a8256bc994f3c3d2ad6d1584125963b5a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.CampaignStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class CampaignStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.CampaignStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignStatusCodes.md)

Deprecated. Formerly used to contain the various statuses that a coupon may
be in.


**Deprecated:**
**warning:** Use [CouponStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md) instead.

## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[COUPON_ALREADY_APPLIED](#coupon_already_applied): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_ALREADY_APPLIED"~~ | Indicates that the coupon has already been applied to the basket. |
| ~~[COUPON_ALREADY_REDEEMED](#coupon_already_redeemed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_ALREADY_REDEEMED"~~ | Indicates that the coupon has already been redeemed. |
| ~~[COUPON_NOT_REDEEMABLE](#coupon_not_redeemable): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_NOT_REDEEMABLE"~~ | Indicates that the coupon is not currently redeemable. |
| ~~[COUPON_UNKNOWN](#coupon_unknown): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_UNKNOWN"~~ | Indicates that the coupon code is not valid. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CampaignStatusCodes](#campaignstatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### COUPON_ALREADY_APPLIED

- ~~COUPON_ALREADY_APPLIED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_ALREADY_APPLIED"~~
  - : Indicates that the coupon has already been applied to the basket.

    **Deprecated:**
**warning:** Use [CouponStatusCodes.COUPON_CODE_ALREADY_IN_BASKET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_already_in_basket),
[CouponStatusCodes.COUPON_ALREADY_IN_BASKET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_already_in_basket) instead.

---

### COUPON_ALREADY_REDEEMED

- ~~COUPON_ALREADY_REDEEMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_ALREADY_REDEEMED"~~
  - : Indicates that the coupon has already been redeemed.

    **Deprecated:**
**warning:** Use [CouponStatusCodes.COUPON_CODE_ALREADY_REDEEMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_already_redeemed) instead.

---

### COUPON_NOT_REDEEMABLE

- ~~COUPON_NOT_REDEEMABLE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_NOT_REDEEMABLE"~~
  - : Indicates that the coupon is not currently redeemable.

    **Deprecated:**
**warning:** Use [CouponStatusCodes.COUPON_DISABLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_disabled),
[CouponStatusCodes.COUPON_CODE_UNKNOWN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_unknown),
[CouponStatusCodes.REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#redemption_limit_exceeded),
[CouponStatusCodes.CUSTOMER_REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#customer_redemption_limit_exceeded),
[CouponStatusCodes.TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#timeframe_redemption_limit_exceeded) or
[CouponStatusCodes.NO_APPLICABLE_PROMOTION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#no_applicable_promotion)

---

### COUPON_UNKNOWN

- ~~COUPON_UNKNOWN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_UNKNOWN"~~
  - : Indicates that the coupon code is not valid.

    **Deprecated:**
**warning:** Use [CouponStatusCodes.COUPON_CODE_UNKNOWN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_unknown) instead

---

## Constructor Details

### CampaignStatusCodes()
- CampaignStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=77360ff60e99086d8a4339c853d578f64e7f61d804c84fe46295c89d88d5e930 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.Catalog.md -->

<!-- prettier-ignore-start -->
# Class Catalog

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)

Represents a Commerce Cloud Digital Catalog. Catalogs are containers of products
and other product-related information and can be shared between sites. Every
product in the system is contained in (or "owned by") exactly one catalog.
Every site has a single "site catalog" which defines the products that are
available to purchase on that site. The static method
[CatalogMgr.getSiteCatalog()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getsitecatalog) returns the site catalog for
the current site.


Catalogs are organized into a tree of categories with a single top-level root
category. Products are assigned to categories within catalogs. They can be
assigned to categories in their owning catalog, or other catalogs. They can
be assigned to multiple categories within the same catalog. Products that are
not assigned to any categories are considered "uncategorized." A product has
a single "classification category" in some catalog, and one
"primary category" per catalog. The classification category defines the
attribute set of the product. The primary category is used as standard
presentation context within that catalog in the storefront.


While Commerce Cloud Digital does not currently distinguish different
catalog types, it is common practice to have two general types of catalog:


- "Product catalogs" typically contain detailed product information and are  frequently generated from some backend PIM system.
- "Site Catalogs" define the category structure of the storefront and  contain primarily the assignments of these categories to the products defined  in the product catalogs. The site catalog is assigned to the site.



In addition to products and categories, catalogs contain recommendations,
shared variation attributes which can be used by multiple master products,
and shared product options which can be used by multiple option products.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value of attribute 'id'. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value of the localized extensible object attribute  "shortDescription" for the current locale. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value of the localized extensible object attribute  "displayName" for the current locale. |
| [root](#root): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the object for the relation 'root'. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md#getdescription)() | Returns the value of the localized extensible object attribute  "shortDescription" for the current locale. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md#getdisplayname)() | Returns the value of the localized extensible object attribute  "displayName" for the current locale. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md#getid)() | Returns the value of attribute 'id'. |
| [getRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md#getroot)() | Returns the object for the relation 'root'. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value of attribute 'id'.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value of the localized extensible object attribute
      "shortDescription" for the current locale.



---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value of the localized extensible object attribute
      "displayName" for the current locale.



---

### root
- root: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the object for the relation 'root'.


---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the localized extensible object attribute
      "shortDescription" for the current locale.


    **Returns:**
    - The value of the attribute for the current locale,
                   or null if it wasn't found.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the localized extensible object attribute
      "displayName" for the current locale.


    **Returns:**
    - The value of the attribute for the current locale,
                   or null if it wasn't found.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of attribute 'id'.

    **Returns:**
    - the value of the attribute 'id'


---

### getRoot()
- getRoot(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the object for the relation 'root'.

    **Returns:**
    - the object for the relation 'root'.


---

<!-- prettier-ignore-end -->

<!-- document id=e442a1d5934429533164f68be8d267e2d7f335a0ef50fce4e9b9244aa091417c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.CatalogMgr.md -->

<!-- prettier-ignore-start -->
# Class CatalogMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.CatalogMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md)

Provides helper methods for getting categories.


## Property Summary

| Property | Description |
| --- | --- |
| [siteCatalog](#sitecatalog): [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md) `(read-only)` | Returns the catalog of the current site or null if no catalog is assigned to the site. |
| [sortingOptions](#sortingoptions): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns a list containing the sorting options configured for this site. |
| [sortingRules](#sortingrules): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing all of the sorting rules for this site, including global sorting rules. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getCatalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getcatalogstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the catalog identified by the specified catalog id. |
| static [getCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getcategorystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the category of the site catalog identified by the specified  category id. |
| static [getSiteCatalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getsitecatalog)() | Returns the catalog of the current site or null if no catalog is assigned to the site. |
| static [getSortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getsortingoptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the sorting option with the given ID for this site, or  `null` if there is no such option. |
| static [getSortingOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getsortingoptions)() | Returns a list containing the sorting options configured for this site. |
| static [getSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getsortingrulestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the sorting rule with the given ID for this site,  or `null` if there is no such rule. |
| static [getSortingRules](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md#getsortingrules)() | Returns a collection containing all of the sorting rules for this site, including global sorting rules. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### siteCatalog
- siteCatalog: [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md) `(read-only)`
  - : Returns the catalog of the current site or null if no catalog is assigned to the site.


---

### sortingOptions
- sortingOptions: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns a list containing the sorting options configured for this site. On a Cimulate-enabled site, restricts
      the result to the Cimulate-managed rule IDs so the storefront "Sort by" dropdown matches what the buyer
      actually gets back from Cimulate.



---

### sortingRules
- sortingRules: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing all of the sorting rules for this site, including global sorting rules.


---

## Method Details

### getCatalog(String)
- static getCatalog(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)
  - : Returns the catalog identified by the specified catalog id.
      Returns null if no catalog with the specified id exists in the
      current organization context.


    **Parameters:**
    - id - Catalog id

    **Returns:**
    - the catalog or null.


---

### getCategory(String)
- static getCategory(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the category of the site catalog identified by the specified
      category id. Returns null if no site catalog is defined, or no category
      with the specified id is found in the site catalog.


    **Parameters:**
    - id - the category identifier.

    **Returns:**
    - the category of the site catalog identified by the specified
      category id or null if no site catalog is found.



---

### getSiteCatalog()
- static getSiteCatalog(): [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)
  - : Returns the catalog of the current site or null if no catalog is assigned to the site.

    **Returns:**
    - the catalog of the current site or null.


---

### getSortingOption(String)
- static getSortingOption(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)
  - : Returns the sorting option with the given ID for this site, or
      `null` if there is no such option.


    **Parameters:**
    - id - the ID of the sorting option

    **Returns:**
    - a SortingOption or null.


---

### getSortingOptions()
- static getSortingOptions(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list containing the sorting options configured for this site. On a Cimulate-enabled site, restricts
      the result to the Cimulate-managed rule IDs so the storefront "Sort by" dropdown matches what the buyer
      actually gets back from Cimulate.


    **Returns:**
    - a list of SortingOption objects


---

### getSortingRule(String)
- static getSortingRule(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)
  - : Returns the sorting rule with the given ID for this site,
      or `null` if there is no such rule.


    **Parameters:**
    - id - the ID of the sorting rule

    **Returns:**
    - a SortingRule or null.


---

### getSortingRules()
- static getSortingRules(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing all of the sorting rules for this site, including global sorting rules.

    **Returns:**
    - a collection of SortingRule objects


---

<!-- prettier-ignore-end -->

<!-- document id=cf0f4eaa318eed14c4e566fa513f932eb628908b77d489c843507218b9ece3ee url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.Category.md -->

<!-- prettier-ignore-start -->
# Class Category

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)

Represents a category in a product catalog.


## Constant Summary

| Constant | Description |
| --- | --- |
| [DISPLAY_MODE_INDIVIDUAL](#display_mode_individual): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Constant representing the Variation Group Display Mode individual setting. |
| [DISPLAY_MODE_MERGED](#display_mode_merged): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Constant representing the Variation Group Display Mode merged setting. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the id of the category. |
| [allRecommendations](#allrecommendations): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all outgoing recommendations for this category. |
| [categoryAssignments](#categoryassignments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of category assignments of the category. |
| [defaultSortingRule](#defaultsortingrule): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md) `(read-only)` | Returns the default sorting rule configured for this category,  or `null` if there is no default rule to be applied for it. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of the catalog category for the current locale. |
| [displayMode](#displaymode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the Variation Groups Display Mode of the category or null if no display mode is defined. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of the of the catalog category for the current locale. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the image reference of this catalog category. |
| [incomingCategoryLinks](#incomingcategorylinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category  is the target. |
| [online](#online): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the value indicating whether the catalog category is "currently  online". |
| [onlineCategoryAssignments](#onlinecategoryassignments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of category assignments of the category where the  referenced product is currently online. |
| [onlineFlag](#onlineflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status flag of the category. |
| [onlineFrom](#onlinefrom): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date from which the category is online or valid. |
| [onlineIncomingCategoryLinks](#onlineincomingcategorylinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for  which this category is the target. |
| [onlineOutgoingCategoryLinks](#onlineoutgoingcategorylinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for  which this category is the source. |
| [onlineProducts](#onlineproducts): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns online products assigned to this category. |
| [onlineSubCategories](#onlinesubcategories): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a sorted collection of currently online subcategories of this  catalog category. |
| [onlineTo](#onlineto): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date until which the category is online or valid. |
| [orderableRecommendations](#orderablerecommendations): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a list of outgoing recommendations for this category. |
| [outgoingCategoryLinks](#outgoingcategorylinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category  is the source. |
| [pageDescription](#pagedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page description of this category for the default locale or null if not defined. |
| [pageKeywords](#pagekeywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page keywords of this category for the default locale or null if not defined. |
| [pageTitle](#pagetitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page title of this category for the default locale or null if not defined. |
| [pageURL](#pageurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page URL property of this category or null if not defined. |
| [parent](#parent): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the parent of this category. |
| [productAttributeModel](#productattributemodel): [ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md) `(read-only)` | Returns this category's ProductAttributeModel, which makes access to the  category's attribute information convenient. |
| [products](#products): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all products assigned to this category. |
| [recommendations](#recommendations): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the outgoing recommendations for this category. |
| [root](#root): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the category is the root category of its catalog. |
| [searchPlacement](#searchplacement): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the search placement of the category or null of no search placement is defined. |
| [searchRank](#searchrank): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the search rank of the category or null of no search rank is defined. |
| [siteMapChangeFrequency](#sitemapchangefrequency): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the category's sitemap change frequency. |
| [siteMapIncluded](#sitemapincluded): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the category's sitemap inclusion. |
| [siteMapPriority](#sitemappriority): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the category's sitemap priority. |
| [subCategories](#subcategories): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a sorted collection of the subcategories of this catalog category,  including both online and offline subcategories. |
| [template](#template): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the template property value , which is the file name of the template  used to display the catalog category. |
| [thumbnail](#thumbnail): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the thumbnail image reference of this catalog category. |
| [topLevel](#toplevel): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the category is a top level category, but not the root  category. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getallrecommendations)() | Returns all outgoing recommendations for this category. |
| [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getallrecommendationsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all outgoing recommendations for this category which are of the  specified type. |
| [getCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getcategoryassignments)() | Returns a collection of category assignments of the category. |
| [getDefaultSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getdefaultsortingrule)() | Returns the default sorting rule configured for this category,  or `null` if there is no default rule to be applied for it. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getdescription)() | Returns the description of the catalog category for the current locale. |
| [getDisplayMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getdisplaymode)() | Returns the Variation Groups Display Mode of the category or null if no display mode is defined. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getdisplayname)() | Returns the display name of the of the catalog category for the current locale. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getid)() | Returns the id of the category. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getimage)() | Returns the image reference of this catalog category. |
| [getIncomingCategoryLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getincomingcategorylinks)() | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category  is the target. |
| [getIncomingCategoryLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getincomingcategorylinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category  is the target and which are of the specified type. |
| [getOnlineCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlinecategoryassignments)() | Returns a collection of category assignments of the category where the  referenced product is currently online. |
| [getOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineflag)() | Returns the online status flag of the category. |
| [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlinefrom)() | Returns the date from which the category is online or valid. |
| [getOnlineIncomingCategoryLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineincomingcategorylinks)() | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for  which this category is the target. |
| [getOnlineOutgoingCategoryLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineoutgoingcategorylinks)() | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for  which this category is the source. |
| [getOnlineProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineproducts)() | Returns online products assigned to this category. |
| [getOnlineSubCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlinesubcategories)() | Returns a sorted collection of currently online subcategories of this  catalog category. |
| [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineto)() | Returns the date until which the category is online or valid. |
| [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getorderablerecommendations)() | Returns a list of outgoing recommendations for this category. |
| [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getorderablerecommendationsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a list of outgoing recommendations for this category. |
| [getOutgoingCategoryLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getoutgoingcategorylinks)() | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category  is the source. |
| [getOutgoingCategoryLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getoutgoingcategorylinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category  is the source and which are of the specified type. |
| [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getpagedescription)() | Returns the page description of this category for the default locale or null if not defined. |
| [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getpagekeywords)() | Returns the page keywords of this category for the default locale or null if not defined. |
| [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getpagetitle)() | Returns the page title of this category for the default locale or null if not defined. |
| [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getpageurl)() | Returns the page URL property of this category or null if not defined. |
| [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getparent)() | Returns the parent of this category. |
| [getProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getproductattributemodel)() | Returns this category's ProductAttributeModel, which makes access to the  category's attribute information convenient. |
| [getProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getproducts)() | Returns all products assigned to this category. |
| [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getrecommendations)() | Returns the outgoing recommendations for this category. |
| [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getrecommendationsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the outgoing recommendations for this category which are of the  specified type. |
| [getSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getsearchplacement)() | Returns the search placement of the category or null of no search placement is defined. |
| [getSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getsearchrank)() | Returns the search rank of the category or null of no search rank is defined. |
| [getSiteMapChangeFrequency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getsitemapchangefrequency)() | Returns the category's sitemap change frequency. |
| [getSiteMapIncluded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getsitemapincluded)() | Returns the category's sitemap inclusion. |
| [getSiteMapPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getsitemappriority)() | Returns the category's sitemap priority. |
| [getSubCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getsubcategories)() | Returns a sorted collection of the subcategories of this catalog category,  including both online and offline subcategories. |
| [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#gettemplate)() | Returns the template property value , which is the file name of the template  used to display the catalog category. |
| [getThumbnail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getthumbnail)() | Returns the thumbnail image reference of this catalog category. |
| [hasOnlineProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#hasonlineproducts)() | Returns true if this catalog category has any online products assigned. |
| [hasOnlineSubCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#hasonlinesubcategories)() | Returns true if this catalog category has any online subcategories. |
| [isDirectSubCategoryOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#isdirectsubcategoryofcategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)) | Returns true if this category is a direct sub-category of the provided  category. |
| [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#isonline)() | Returns the value indicating whether the catalog category is "currently  online". |
| [isRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#isroot)() | Identifies if the category is the root category of its catalog. |
| [isSubCategoryOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#issubcategoryofcategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)) | Returns true if this category is a sub-category of the provided category. |
| [isTopLevel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#istoplevel)() | Returns true if the category is a top level category, but not the root  category. |
| [setDisplayMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#setdisplaymodenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the category's Variation Groups Display Mode. |
| [setSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#setsearchplacementnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the category's search placement. |
| [setSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#setsearchranknumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the category's search rank. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DISPLAY_MODE_INDIVIDUAL

- DISPLAY_MODE_INDIVIDUAL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Constant representing the Variation Group Display Mode individual setting.


---

### DISPLAY_MODE_MERGED

- DISPLAY_MODE_MERGED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Constant representing the Variation Group Display Mode merged setting.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the id of the category.


---

### allRecommendations
- allRecommendations: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all outgoing recommendations for this category.  The
      recommendations are sorted by their explicitly set order.



---

### categoryAssignments
- categoryAssignments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of category assignments of the category.


---

### defaultSortingRule
- defaultSortingRule: [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md) `(read-only)`
  - : Returns the default sorting rule configured for this category,
      or `null` if there is no default rule to be applied for it.
      
      This method returns the default rule for the parent category if this
      category inherits one.  The parent category may inherit its default
      rule from its parent, and so on, up to the root category.
      
      This method returns `null` if no ancestor category for this
      category has a default rule.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of the catalog category for the current locale.


---

### displayMode
- displayMode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the Variation Groups Display Mode of the category or null if no display mode is defined.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of the of the catalog category for the current locale.
      
      This value is intended to be used as the
      external visible name of the catalog category.



---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the image reference of this catalog category.


---

### incomingCategoryLinks
- incomingCategoryLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category
      is the target.  If the source category of a link belongs to a different
      catalog than the catalog owning this category, it is not returned.



---

### online
- online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the value indicating whether the catalog category is "currently
      online".  A category is currently online if its online flag equals true
      and the current site date is within the date range defined by the
      onlineFrom and onlineTo attributes.



---

### onlineCategoryAssignments
- onlineCategoryAssignments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of category assignments of the category where the
      referenced product is currently online. When checking the online status
      of the product, the online flag and the online from & to dates are taken
      into account. Online flag, online from & to dates set for the current site
      takes precedence over the default values.



---

### onlineFlag
- onlineFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status flag of the category.


---

### onlineFrom
- onlineFrom: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date from which the category is online or valid.


---

### onlineIncomingCategoryLinks
- onlineIncomingCategoryLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for
      which this category is the target. If the source category of a link
      belongs to a different catalog than the catalog owning this category, it
      is not returned. Additionally, this method will only return a link if the
      source category is currently online. A category is currently online if
      its online flag equals true and the current site date is within the date
      range defined by the onlineFrom and onlineTo attributes.



---

### onlineOutgoingCategoryLinks
- onlineOutgoingCategoryLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for
      which this category is the source. If the target category of a link
      belongs to a different catalog than the catalog owning this category, it
      is not returned. Additionally, this method will only return a link if the
      target category is currently online. A category is currently online if
      its online flag equals true and the current site date is within the date
      range defined by the onlineFrom and onlineTo attributes.



---

### onlineProducts
- onlineProducts: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns online products assigned to this category.
      Offline products are not included in the returned collection.
      When checking the online status of the product,
      the online flag and the online from & to dates are taken into account.
      Online flag, online from & to dates set for the current site takes precedence
      over the default values. 
      
      
      The order of products in the returned collection corresponds to the
      defined explicit sorting of products in this category.


    **See Also:**
    - [hasOnlineProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#hasonlineproducts)


---

### onlineSubCategories
- onlineSubCategories: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a sorted collection of currently online subcategories of this
      catalog category.
      
      - A category is currently online if its online flag    equals true and the current site date is within the date range defined by    the onlineFrom and onlineTo attributes.   
      - The returned collection is sorted by position. Subcategories marked as    "unsorted" always appear after those marked as "sorted" but are otherwise    not in any guaranteed order.   
      - The returned collection contains direct subcategories only.    


    **See Also:**
    - [hasOnlineSubCategories()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#hasonlinesubcategories)


---

### onlineTo
- onlineTo: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date until which the category is online or valid.


---

### orderableRecommendations
- orderableRecommendations: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a list of outgoing recommendations for this category. This method
      behaves similarly to [getRecommendations()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getrecommendations) but additionally filters out
      recommendations for which the target product is unorderable according to
      its product availability model.


    **See Also:**
    - [ProductAvailabilityModel.isOrderable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderable)


---

### outgoingCategoryLinks
- outgoingCategoryLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category
      is the source.  If the target category of a link belongs to a different
      catalog than the catalog owning this category, it is not returned.
      The collection of links is sorted by the explicitly defined order
      for this category with unsorted links appearing at the end.



---

### pageDescription
- pageDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page description of this category for the default locale or null if not defined.


---

### pageKeywords
- pageKeywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page keywords of this category for the default locale or null if not defined.


---

### pageTitle
- pageTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page title of this category for the default locale or null if not defined.


---

### pageURL
- pageURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page URL property of this category or null if not defined.


---

### parent
- parent: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the parent of this category.


---

### productAttributeModel
- productAttributeModel: [ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md) `(read-only)`
  - : Returns this category's ProductAttributeModel, which makes access to the
      category's attribute information convenient. The model is calculated
      based on the attribute definitions assigned to this category and the
      global attribute definitions for the object type 'Product'.



---

### products
- products: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all products assigned to this category.
      The order of products in the returned collection corresponds to the
      defined explicit sorting of products in this category.


    **See Also:**
    - [getOnlineProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineproducts)


---

### recommendations
- recommendations: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the outgoing recommendations for this category.  If this category
      is not in the site catalog, or there is no site catalog, an empty
      collection is returned.  Only recommendations for which the target
      product exists and is assigned to the site catalog are returned.  The
      recommendations are sorted by their explicitly set order.



---

### root
- root: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the category is the root category of its catalog.


---

### searchPlacement
- searchPlacement: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the search placement of the category or null of no search placement is defined.


---

### searchRank
- searchRank: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the search rank of the category or null of no search rank is defined.


---

### siteMapChangeFrequency
- siteMapChangeFrequency: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the category's sitemap change frequency.


---

### siteMapIncluded
- siteMapIncluded: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the category's sitemap inclusion.


---

### siteMapPriority
- siteMapPriority: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the category's sitemap priority.


---

### subCategories
- subCategories: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a sorted collection of the subcategories of this catalog category,
      including both online and offline subcategories.
      
      - The returned collection is sorted by position. Subcategories marked as    "unsorted" always appear after those marked as "sorted" but are otherwise    not in any guaranteed order.   
      - The returned collection contains direct subcategories only.   


    **See Also:**
    - [getOnlineSubCategories()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlinesubcategories)


---

### template
- template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the template property value , which is the file name of the template
      used to display the catalog category.



---

### thumbnail
- thumbnail: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the thumbnail image reference of this catalog category.


---

### topLevel
- topLevel: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the category is a top level category, but not the root
      category.



---

## Method Details

### getAllRecommendations()
- getAllRecommendations(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all outgoing recommendations for this category.  The
      recommendations are sorted by their explicitly set order.


    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getAllRecommendations(Number)
- getAllRecommendations(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all outgoing recommendations for this category which are of the
      specified type. The recommendations are sorted by their explicitly set
      order.


    **Parameters:**
    - type - the recommendation type.

    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getCategoryAssignments()
- getCategoryAssignments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of category assignments of the category.

    **Returns:**
    - Collection of category assignments of the category.


---

### getDefaultSortingRule()
- getDefaultSortingRule(): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)
  - : Returns the default sorting rule configured for this category,
      or `null` if there is no default rule to be applied for it.
      
      This method returns the default rule for the parent category if this
      category inherits one.  The parent category may inherit its default
      rule from its parent, and so on, up to the root category.
      
      This method returns `null` if no ancestor category for this
      category has a default rule.


    **Returns:**
    - the default SortingRule or null.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the catalog category for the current locale.

    **Returns:**
    - The value of the property for the current locale, or null if it
              wasn't found.



---

### getDisplayMode()
- getDisplayMode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the Variation Groups Display Mode of the category or null if no display mode is defined.

    **Returns:**
    - the value of the attribute 'displayMode' which is either [DISPLAY_MODE_MERGED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#display_mode_merged) or
              [DISPLAY_MODE_INDIVIDUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#display_mode_individual) or null if category is set to inherit the display mode.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of the of the catalog category for the current locale.
      
      This value is intended to be used as the
      external visible name of the catalog category.


    **Returns:**
    - The value of the property for the current locale, or null if it
              wasn't found.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the id of the category.

    **Returns:**
    - the id of the category.


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the image reference of this catalog category.

    **Returns:**
    - the image reference for this category.


---

### getIncomingCategoryLinks()
- getIncomingCategoryLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category
      is the target.  If the source category of a link belongs to a different
      catalog than the catalog owning this category, it is not returned.


    **Returns:**
    - a collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects, possibly empty but not null.


---

### getIncomingCategoryLinks(Number)
- getIncomingCategoryLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category
      is the target and which are of the specified type.  If the source
      category of a link belongs to a different catalog than the catalog owning
      this category, it is not returned.


    **Parameters:**
    - type - the link type type.

    **Returns:**
    - a collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects, possibly empty but not null.


---

### getOnlineCategoryAssignments()
- getOnlineCategoryAssignments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of category assignments of the category where the
      referenced product is currently online. When checking the online status
      of the product, the online flag and the online from & to dates are taken
      into account. Online flag, online from & to dates set for the current site
      takes precedence over the default values.


    **Returns:**
    - Collection of online category assignments of the category.


---

### getOnlineFlag()
- getOnlineFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status flag of the category.

    **Returns:**
    - the online status flag of the category.


---

### getOnlineFrom()
- getOnlineFrom(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date from which the category is online or valid.

    **Returns:**
    - the date from which the category is online or valid.


---

### getOnlineIncomingCategoryLinks()
- getOnlineIncomingCategoryLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for
      which this category is the target. If the source category of a link
      belongs to a different catalog than the catalog owning this category, it
      is not returned. Additionally, this method will only return a link if the
      source category is currently online. A category is currently online if
      its online flag equals true and the current site date is within the date
      range defined by the onlineFrom and onlineTo attributes.


    **Returns:**
    - a collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects, possibly
              empty but not null.



---

### getOnlineOutgoingCategoryLinks()
- getOnlineOutgoingCategoryLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for
      which this category is the source. If the target category of a link
      belongs to a different catalog than the catalog owning this category, it
      is not returned. Additionally, this method will only return a link if the
      target category is currently online. A category is currently online if
      its online flag equals true and the current site date is within the date
      range defined by the onlineFrom and onlineTo attributes.


    **Returns:**
    - a collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects, possibly
              empty but not null.



---

### getOnlineProducts()
- getOnlineProducts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns online products assigned to this category.
      Offline products are not included in the returned collection.
      When checking the online status of the product,
      the online flag and the online from & to dates are taken into account.
      Online flag, online from & to dates set for the current site takes precedence
      over the default values. 
      
      
      The order of products in the returned collection corresponds to the
      defined explicit sorting of products in this category.


    **Returns:**
    - a sorted collection of online products of this category.

    **See Also:**
    - [hasOnlineProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#hasonlineproducts)


---

### getOnlineSubCategories()
- getOnlineSubCategories(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of currently online subcategories of this
      catalog category.
      
      - A category is currently online if its online flag    equals true and the current site date is within the date range defined by    the onlineFrom and onlineTo attributes.   
      - The returned collection is sorted by position. Subcategories marked as    "unsorted" always appear after those marked as "sorted" but are otherwise    not in any guaranteed order.   
      - The returned collection contains direct subcategories only.    


    **Returns:**
    - a sorted collection of currently online subcategories.

    **See Also:**
    - [hasOnlineSubCategories()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#hasonlinesubcategories)


---

### getOnlineTo()
- getOnlineTo(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date until which the category is online or valid.

    **Returns:**
    - the date until which the category is online or valid.


---

### getOrderableRecommendations()
- getOrderableRecommendations(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a list of outgoing recommendations for this category. This method
      behaves similarly to [getRecommendations()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getrecommendations) but additionally filters out
      recommendations for which the target product is unorderable according to
      its product availability model.


    **Returns:**
    - the sorted collection of recommendations, never null but possibly
              empty.


    **See Also:**
    - [ProductAvailabilityModel.isOrderable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderable)


---

### getOrderableRecommendations(Number)
- getOrderableRecommendations(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a list of outgoing recommendations for this category. This method
      behaves similarly to [getRecommendations(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getrecommendationsnumber) but additionally
      filters out recommendations for which the target product is unorderable
      according to its product availability model.


    **Parameters:**
    - type - the recommendation type.

    **Returns:**
    - the sorted collection of recommendations, never null but possibly
              empty.


    **See Also:**
    - [ProductAvailabilityModel.isOrderable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderable)


---

### getOutgoingCategoryLinks()
- getOutgoingCategoryLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category
      is the source.  If the target category of a link belongs to a different
      catalog than the catalog owning this category, it is not returned.
      The collection of links is sorted by the explicitly defined order
      for this category with unsorted links appearing at the end.


    **Returns:**
    - a collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects, possibly empty but not null.


---

### getOutgoingCategoryLinks(Number)
- getOutgoingCategoryLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects for which this category
      is the source and which are of the specified type.  If the target
      category of a link belongs to a different catalog than the catalog owning
      this category, it is not returned.  The collection of links is sorted by
      the explicitly defined order for this category with unsorted links
      appearing at the end.


    **Parameters:**
    - type - the link type type.

    **Returns:**
    - a collection of [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md) objects, possibly empty but not null.


---

### getPageDescription()
- getPageDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page description of this category for the default locale or null if not defined.

    **Returns:**
    - the value of the attribute 'pageDescription'.


---

### getPageKeywords()
- getPageKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page keywords of this category for the default locale or null if not defined.

    **Returns:**
    - the value of the attribute 'pageKeywords'.


---

### getPageTitle()
- getPageTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page title of this category for the default locale or null if not defined.

    **Returns:**
    - the value of the attribute 'pageTitle'.


---

### getPageURL()
- getPageURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page URL property of this category or null if not defined.

    **Returns:**
    - the value of the attribute 'pageURL'.


---

### getParent()
- getParent(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the parent of this category.

    **Returns:**
    - a CatalogCategory instance representing
      the parent of this CatalogCategory or null.



---

### getProductAttributeModel()
- getProductAttributeModel(): [ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md)
  - : Returns this category's ProductAttributeModel, which makes access to the
      category's attribute information convenient. The model is calculated
      based on the attribute definitions assigned to this category and the
      global attribute definitions for the object type 'Product'.


    **Returns:**
    - the ProductAttributeModel for this category.


---

### getProducts()
- getProducts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all products assigned to this category.
      The order of products in the returned collection corresponds to the
      defined explicit sorting of products in this category.


    **Returns:**
    - a sorted collection of all products of this category.

    **See Also:**
    - [getOnlineProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineproducts)


---

### getRecommendations()
- getRecommendations(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the outgoing recommendations for this category.  If this category
      is not in the site catalog, or there is no site catalog, an empty
      collection is returned.  Only recommendations for which the target
      product exists and is assigned to the site catalog are returned.  The
      recommendations are sorted by their explicitly set order.


    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getRecommendations(Number)
- getRecommendations(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the outgoing recommendations for this category which are of the
      specified type.  Behaves the same as [getRecommendations()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getrecommendations) but
      additionally filters by recommendation type.


    **Parameters:**
    - type - the recommendation type.

    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getSearchPlacement()
- getSearchPlacement(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the search placement of the category or null of no search placement is defined.

    **Returns:**
    - the value of the attribute 'searchPlacement'.


---

### getSearchRank()
- getSearchRank(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the search rank of the category or null of no search rank is defined.

    **Returns:**
    - the value of the attribute 'searchRank'.


---

### getSiteMapChangeFrequency()
- getSiteMapChangeFrequency(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the category's sitemap change frequency.

    **Returns:**
    - the value of the attribute 'siteMapChangeFrequency'.


---

### getSiteMapIncluded()
- getSiteMapIncluded(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the category's sitemap inclusion.

    **Returns:**
    - the value of the attribute 'siteMapIncluded'.


---

### getSiteMapPriority()
- getSiteMapPriority(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the category's sitemap priority.

    **Returns:**
    - the value of the attribute 'siteMapPriority'.


---

### getSubCategories()
- getSubCategories(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of the subcategories of this catalog category,
      including both online and offline subcategories.
      
      - The returned collection is sorted by position. Subcategories marked as    "unsorted" always appear after those marked as "sorted" but are otherwise    not in any guaranteed order.   
      - The returned collection contains direct subcategories only.   


    **Returns:**
    - a sorted collection of the subcategories.

    **See Also:**
    - [getOnlineSubCategories()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlinesubcategories)


---

### getTemplate()
- getTemplate(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the template property value , which is the file name of the template
      used to display the catalog category.


    **Returns:**
    - the value of the property 'template'.


---

### getThumbnail()
- getThumbnail(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the thumbnail image reference of this catalog category.

    **Returns:**
    - the thumbnail image reference for this category.


---

### hasOnlineProducts()
- hasOnlineProducts(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this catalog category has any online products assigned.
      When checking the online status of the product,
      the online flag and the online from & to dates are taken into account.
      Online flag, online from & to dates set for the current site takes precedence
      over the default values.


    **Returns:**
    - true, if this category has at least one online product assigned,
              false otherwise.


    **See Also:**
    - [getOnlineProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlineproducts)


---

### hasOnlineSubCategories()
- hasOnlineSubCategories(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this catalog category has any online subcategories.
      
      - A category is currently online if its online flag    equals true and the current site date is within the date range defined by    the onlineFrom and onlineTo attributes.   
      - Only direct subcategories are considered.   


    **Returns:**
    - true, if this category has at least one online subcategory,
              false otherwise.


    **See Also:**
    - [getOnlineSubCategories()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getonlinesubcategories)


---

### isDirectSubCategoryOf(Category)
- isDirectSubCategoryOf(parent: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this category is a direct sub-category of the provided
      category.


    **Parameters:**
    - parent - The parent category, must not be null.

    **Returns:**
    - True if this category is a direct sub-category of parent, false
              otherwise.



---

### isOnline()
- isOnline(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the value indicating whether the catalog category is "currently
      online".  A category is currently online if its online flag equals true
      and the current site date is within the date range defined by the
      onlineFrom and onlineTo attributes.


    **Returns:**
    - true if the category is currently online, false otherwise.


---

### isRoot()
- isRoot(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the category is the root category of its catalog.

    **Returns:**
    - 'true' if the category is the root category of its catalog,
      'false' otherwise.



---

### isSubCategoryOf(Category)
- isSubCategoryOf(ancestor: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this category is a sub-category of the provided category.
      This can be either a direct or an indirect sub-category.


    **Parameters:**
    - ancestor - The ancestor category, must not be null.

    **Returns:**
    - true if this category is a sub-category of ancestor, false
              otherwise.



---

### isTopLevel()
- isTopLevel(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the category is a top level category, but not the root
      category.


    **Returns:**
    - True if the category is a direct sub-category of the root
              category, false otherwise.



---

### setDisplayMode(Number)
- setDisplayMode(displayMode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the category's Variation Groups Display Mode.

    **Parameters:**
    - displayMode - The category's variation groups display mode which is either [DISPLAY_MODE_MERGED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#display_mode_merged) or             [DISPLAY_MODE_INDIVIDUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#display_mode_individual) or null if category is set to inherit the display mode.


---

### setSearchPlacement(Number)
- setSearchPlacement(placement: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the category's search placement.

    **Parameters:**
    - placement - The category's search placement.


---

### setSearchRank(Number)
- setSearchRank(rank: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the category's search rank.

    **Parameters:**
    - rank - The category's search rank.


---

<!-- prettier-ignore-end -->

<!-- document id=a1042c0bb6af874ae5c64cfa449aee3acb40f2f11a042c7d5c3be3dd22b7ab73 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.CategoryAssignment.md -->

<!-- prettier-ignore-start -->
# Class CategoryAssignment

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md)

Represents a category assignment in Commerce Cloud Digital.


## Property Summary

| Property | Description |
| --- | --- |
| [calloutMsg](#calloutmsg): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the category assignment's callout message in the current locale. |
| [category](#category): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the category to which this category assignment is bound. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the category assignment's image. |
| [longDescription](#longdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the category assignment's long description in the current locale. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the category assignment in the current locale. |
| [product](#product): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the product to which this category assignment is bound. |
| [shortDescription](#shortdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the category assignment's short description in the current locale. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCalloutMsg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md#getcalloutmsg)() | Returns the category assignment's callout message in the current locale. |
| [getCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md#getcategory)() | Returns the category to which this category assignment is bound. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md#getimage)() | Returns the category assignment's image. |
| [getLongDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md#getlongdescription)() | Returns the category assignment's long description in the current locale. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md#getname)() | Returns the name of the category assignment in the current locale. |
| [getProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md#getproduct)() | Returns the product to which this category assignment is bound. |
| [getShortDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md#getshortdescription)() | Returns the category assignment's short description in the current locale. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### calloutMsg
- calloutMsg: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the category assignment's callout message in the current locale.


---

### category
- category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the category to which this category assignment is bound.


---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the category assignment's image.


---

### longDescription
- longDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the category assignment's long description in the current locale.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the category assignment in the current locale.


---

### product
- product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the product to which this category assignment is bound.


---

### shortDescription
- shortDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the category assignment's short description in the current locale.


---

## Method Details

### getCalloutMsg()
- getCalloutMsg(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the category assignment's callout message in the current locale.

    **Returns:**
    - the category assignment's callout message in the current locale, or null if it
              wasn't found.



---

### getCategory()
- getCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the category to which this category assignment is bound.

    **Returns:**
    - The category to which this category assignment is bound.


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the category assignment's image.

    **Returns:**
    - the category assignment's image.


---

### getLongDescription()
- getLongDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the category assignment's long description in the current locale.

    **Returns:**
    - The category assignment's long description in the current locale, or null if it
              wasn't found.



---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the category assignment in the current locale.

    **Returns:**
    - The name of the category assignment for the current locale, or null if it
              wasn't found.



---

### getProduct()
- getProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the product to which this category assignment is bound.

    **Returns:**
    - The product to which this category assignment is bound.


---

### getShortDescription()
- getShortDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the category assignment's short description in the current locale.

    **Returns:**
    - the category assignment's short description in the current locale, or null if it
              wasn't found.



---

<!-- prettier-ignore-end -->

<!-- document id=e04c4356bbb9cc584e040fff45a1dd56eb6e7ef68f4cc536a5eb38f27259d226 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.CategoryLink.md -->

<!-- prettier-ignore-start -->
# Class CategoryLink

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md)

A CategoryLink represents a directed relationship between two catalog
categories.  Merchants create category links in order to market similar or
related groups of products.



## Constant Summary

| Constant | Description |
| --- | --- |
| [LINKTYPE_ACCESSORY](#linktype_accessory): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Represents an accessory category link. |
| [LINKTYPE_CROSS_SELL](#linktype_cross_sell): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Represents a cross-sell category link. |
| [LINKTYPE_OTHER](#linktype_other): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Represents a miscellaneous category link. |
| [LINKTYPE_SPARE_PART](#linktype_spare_part): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | Represents a spare part category link. |
| [LINKTYPE_UP_SELL](#linktype_up_sell): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Represents an up-sell category link. |

## Property Summary

| Property | Description |
| --- | --- |
| [sourceCategory](#sourcecategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the object for the relation 'sourceCategory'. |
| [targetCategory](#targetcategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the object for the relation 'targetCategory'. |
| [typeCode](#typecode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the type of this category link (see constants). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSourceCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md#getsourcecategory)() | Returns the object for the relation 'sourceCategory'. |
| [getTargetCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md#gettargetcategory)() | Returns the object for the relation 'targetCategory'. |
| [getTypeCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md#gettypecode)() | Returns the type of this category link (see constants). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### LINKTYPE_ACCESSORY

- LINKTYPE_ACCESSORY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Represents an accessory category link.


---

### LINKTYPE_CROSS_SELL

- LINKTYPE_CROSS_SELL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Represents a cross-sell category link.


---

### LINKTYPE_OTHER

- LINKTYPE_OTHER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Represents a miscellaneous category link.


---

### LINKTYPE_SPARE_PART

- LINKTYPE_SPARE_PART: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : Represents a spare part category link.


---

### LINKTYPE_UP_SELL

- LINKTYPE_UP_SELL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Represents an up-sell category link.


---

## Property Details

### sourceCategory
- sourceCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the object for the relation 'sourceCategory'.


---

### targetCategory
- targetCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the object for the relation 'targetCategory'.


---

### typeCode
- typeCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the type of this category link (see constants).


---

## Method Details

### getSourceCategory()
- getSourceCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the object for the relation 'sourceCategory'.

    **Returns:**
    - the object for the relation 'sourceCategory'


---

### getTargetCategory()
- getTargetCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the object for the relation 'targetCategory'.

    **Returns:**
    - the object for the relation 'targetCategory'


---

### getTypeCode()
- getTypeCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the type of this category link (see constants).

    **Returns:**
    - the type of the link.


---

<!-- prettier-ignore-end -->

<!-- document id=da08199ef86d4fd0aec1e44ab55287c838c6c7f99379701dd29da07cd5e9573c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.CategorySuggestions.md -->

<!-- prettier-ignore-start -->
# Class CategorySuggestions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md)
    - [dw.suggest.CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md)

The category suggestion container provides access to
categories found using the suggested terms as search criteria.
The method [getSuggestedCategories()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md#getsuggestedcategories) can be used to
get the list of found categories.


Furthermore the list of suggested terms, after processing
the original user input search query, is accessible
through [SearchPhraseSuggestions.getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms) method.



## Property Summary

| Property | Description |
| --- | --- |
| [suggestedCategories](#suggestedcategories): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | This method returns a list of categories which were found  using the suggested terms as search criteria. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSuggestedCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md#getsuggestedcategories)() | This method returns a list of categories which were found  using the suggested terms as search criteria. |

### Methods inherited from class Suggestions

[getSearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions), [getSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedphrases), [getSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms), [hasSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases), [hasSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedterms), [hasSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### suggestedCategories
- suggestedCategories: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : This method returns a list of categories which were found
      using the suggested terms as search criteria.
      The category lookup is being executed in the current catalog and locale.


    **See Also:**
    - [Suggestions.hasSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)


---

## Method Details

### getSuggestedCategories()
- getSuggestedCategories(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : This method returns a list of categories which were found
      using the suggested terms as search criteria.
      The category lookup is being executed in the current catalog and locale.


    **Returns:**
    - a iterator containing a [SuggestedCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedCategory.md) instance for
               each found category, the iterator might be empty


    **See Also:**
    - [Suggestions.hasSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)


---

<!-- prettier-ignore-end -->

<!-- document id=5b52af9e5137d17ea225d8b540d81377c8cf15542604d049300bb80ad91809b4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.CertificateRef.md -->

<!-- prettier-ignore-start -->
# Class CertificateRef

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)

This class is used as a reference to a certificate or public key.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## All Known Subclasses
[X509Certificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md)
## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CertificateRef](#certificaterefstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a `CertificateRef` from the passed alias as a reference to a certificate in Business Manager. |

## Method Summary

| Method | Description |
| --- | --- |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md#tostring)() | Returns the string representation of this CertificateRef. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### CertificateRef(String)
- CertificateRef(alias: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a `CertificateRef` from the passed alias as a reference to a certificate in Business Manager.
      No check is made whether the alias is actually valid until the time that this `CertificateRef` is
      used to resolve a certificate or public key.


    **Parameters:**
    - alias - an alias that should refer to a certificate in the keystore.


---

## Method Details

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string representation of this CertificateRef.

    **Returns:**
    - The string representation of this CertificateRef.


---

<!-- prettier-ignore-end -->

<!-- document id=4915757ab15f93097ebb9d2b962395c6cad38d013702ef078dc0e4e703cc4cad url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.CertificateUtils.md -->

<!-- prettier-ignore-start -->
# Class CertificateUtils

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.CertificateUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md)

Utilities for managing certificates and keys.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CertificateUtils](#certificateutils)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| static [getCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md#getcertificatecertificateref)([CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)) | Gets the certificate from the given certificate reference. |
| static [getCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md#getcertificatekeyref)([KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)) | Gets the public certificate from the given private key reference. |
| static [getEncodedCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md#getencodedcertificatecertificateref)([CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)) | Encode the certificate to the base64-encoded DER format. |
| static [getEncodedPublicKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md#getencodedpublickeycertificateref)([CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)) | Gets the public key from the given certificate reference. |
| static [parseEncodedCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md#parseencodedcertificatestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse the certificate from the base64-encoded DER format. |
| static [parseEncodedPublicKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md#parseencodedpublickeystring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse the public key from the given key in X.509 SubjectPublicKeyInfo format. |
| static [parsePublicKeyFromJWK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md#parsepublickeyfromjwkstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse the public key from the given base64-encoded JWK string. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### CertificateUtils()
- CertificateUtils()
  - : 


---

## Method Details

### getCertificate(CertificateRef)
- static getCertificate(certificateRef: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)): [X509Certificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md)
  - : Gets the certificate from the given certificate reference.

    **Parameters:**
    - certificateRef - the certificate reference

    **Returns:**
    - The X509Certificate

    **Throws:**
    - Exception - if the reference is invalid or does not refer to an X.509 certificate


---

### getCertificate(KeyRef)
- static getCertificate(keyRef: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)): [X509Certificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md)
  - : Gets the public certificate from the given private key reference.

    **Parameters:**
    - keyRef - the key reference

    **Returns:**
    - The X509Certificate

    **Throws:**
    - Exception - if the reference is invalid or there is no X.509 certificate


---

### getEncodedCertificate(CertificateRef)
- static getEncodedCertificate(certificateRef: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encode the certificate to the base64-encoded DER format.

    **Parameters:**
    - certificateRef - the certificate to encode

    **Returns:**
    - base64-encoded DER certificate


---

### getEncodedPublicKey(CertificateRef)
- static getEncodedPublicKey(certificateRef: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the public key from the given certificate reference.
      
      
      It is exported in the standard X.509 SubjectPublicKeyInfo format and base64-encoded.


    **Parameters:**
    - certificateRef - the certificate reference with the public key to encode

    **Returns:**
    - The encoded public key


---

### parseEncodedCertificate(String)
- static parseEncodedCertificate(certificate: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)
  - : Parse the certificate from the base64-encoded DER format.

    **Parameters:**
    - certificate - The encoded certificate

    **Returns:**
    - Reference to the parsed certificate


---

### parseEncodedPublicKey(String, String)
- static parseEncodedPublicKey(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encodedKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)
  - : Parse the public key from the given key in X.509 SubjectPublicKeyInfo format.
      
      
      The resulting reference contains only the public key. It can be used for cryptographic operations, but not
      anything that requires the full certificate.


    **Parameters:**
    - algorithm - The public key algorithm, either `EC` or `RSA`
    - encodedKey - The encoded key

    **Returns:**
    - Reference to the public key


---

### parsePublicKeyFromJWK(String)
- static parsePublicKeyFromJWK(jwk: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)
  - : Parse the public key from the given base64-encoded JWK string.
      
      
      This returns the public key portion of the JWK, not the `x5c` certificate chain.
      
      
      Only RSA and EC keys are supported.
      
      
      
      
      The resulting reference contains only the public key. It can be used for cryptographic operations, but not
      anything that requires the full certificate.


    **Parameters:**
    - jwk - Encoded JWK

    **Returns:**
    - Reference to the public key


---

<!-- prettier-ignore-end -->

<!-- document id=d3c31280ae337bcd9b430885fc10db7c1062eb1a8aa79e84319c139821434c6f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.CheckoutHooks.md -->

<!-- prettier-ignore-start -->
# Class CheckoutHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.CheckoutHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CheckoutHooks.md)

This interface represents script hooks that can be registered to populate customer details into a basket. It contains
the extension points (hook names), and the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the exported hook function must be located
inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.


```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:


```
"hooks": [
     {"name": "dw.order.populateCustomerDetails", "script": "./populateCustomerDetails.js"}
]
```


A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointPopulateCustomerDetails](#extensionpointpopulatecustomerdetails): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.populateCustomerDetails" | The extension point name dw.order.populateCustomerDetails. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [populateCustomerDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CheckoutHooks.md#populatecustomerdetailsbasket-customer)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Populates registered customer details into a basket. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointPopulateCustomerDetails

- extensionPointPopulateCustomerDetails: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.populateCustomerDetails"
  - : The extension point name dw.order.populateCustomerDetails.


---

## Method Details

### populateCustomerDetails(Basket, Customer)
- populateCustomerDetails(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Populates registered customer details into a basket. This includes the default shipping address and default
      payment instrument from the registered customer's profile.
      
      
      If no override script is registered, the system defaults to the platform's standard population logic which copies
      the customer's default or first address to the basket's default shipment and billing address, then creates a
      payment instrument from the customer's default or first payment instrument.
      
      
      This method is automatically invoked when the populateCustomerDetails query parameter is set to
      true on createBasket and transferBasket endpoints.


    **Parameters:**
    - basket - the basket to populate with customer details
    - customer - the registered customer whose details should be populated into the basket


---

<!-- prettier-ignore-end -->

<!-- document id=219ab4010f496277d090edddc43d9f23c61f53e4ec7f496edf01519f1095c5b9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.Cipher.md -->

<!-- prettier-ignore-start -->
# Class Cipher

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.Cipher](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md)

This class allows access to encryption services offered through the Java
Cryptography Architecture (JCA). At this time the implementation of the
encryption/decryption methods is based on the default JCE provider of the JDK.
See the Java documentation for a reference guide to the underlying security
provider and information about the Secure Sockets Extension. 

You can find a good overview of the essential purposes of cryptography and
some common implementations in the Wikipedia article on cryptography.
Also see the website of the National Institute of Standards and Technology.
The format of various files used to hold keys, certificate signing requests,
and the like, as well as some related algorithms, are defined in the PKCS series of
documents published by RSALabs (the research arm of RSA Security).

Many internet standards documenting security protocols and concepts are described
in documents originally described as "Request For Comment" and thus widely known
as RFCs. Many of them are available on the Internet FAQ Archives website.


dw.crypto.Cipher is intentionally an Adapter to the full cryptography power supplied
in the security provider implementation.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3 requirements 2, 4, and 12.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CHAR_ENCODING](#char_encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UTF8" | Strings containing keys, plain texts, cipher texts etc. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Cipher](#cipher)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-keyref-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1), which allows  to use a key in the keystore for the decryption. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level decryption API. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-keyref-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2), which allows  to use a key in the keystore for the decryption. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level decryption API. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-keyref-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3), which allows  to use a key in the keystore for the decryption. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level decryption API. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-keyref-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1), which allows  to use a key in the keystore for the decryption. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Decrypts the passed Base-64 encoded message using the passed key and  applying the transformations described by the passed parameters. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-keyref-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2), which allows  to use a key in the keystore for the decryption. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Decrypts the passed Base-64 encoded message using the passed key and  applying the transformations described by the passed parameters. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-keyref-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3), which allows  to use a key in the keystore for the decryption. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Decrypts the passed Base-64 encoded message using the passed key and  applying the transformations described by the passed parameters. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-certificateref-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1), which allows  to use a key in the keystore for the encryption. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level encryption API. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-certificateref-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2), which allows  to use a key in the keystore for the encryption. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level encryption API. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-certificateref-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3), which allows  to use a key in the keystore for the encryption. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level encryption API. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to  [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1), which allows you to  use a key in the keystore for encryption. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to  [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2), which allows you to  use a key in the keystore for encryption. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to  [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3), which allows you to  use a key in the keystore for encryption. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CHAR_ENCODING

- CHAR_ENCODING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UTF8"
  - : Strings containing keys, plain texts, cipher texts etc. are internally
      converted into byte arrays using this encoding (currently UTF8).



---

## Constructor Details

### Cipher()
- Cipher()
  - : 


---

## Method Details

### decryptBytes(Bytes, KeyRef, String, String, Number) - Variant 1
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1), which allows
      to use a key in the keystore for the decryption.


    **Parameters:**
    - encryptedBytes - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1))
    - privateKey - A reference to a private key in the key store.
    - transformation - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1))
    - saltOrIV - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1))
    - iterations - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1))

    **Returns:**
    - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1))

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decryptBytes(Bytes, String, String, String, Number) - Variant 1
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level decryption API. Decrypts the passed bytes using the specified
      key and applying the transformations described by the specified
      parameters.
      
      
      Typical usage:
      
      
      ```
      var base64Msg : String = "some_encoded_encrypted_message";
      var charset : String = "UTF8";  // or "windows-1252", etc.
      
      var encryptedBytes : Bytes = Encoding.fromBase64(base64Msg);
      var messageBytes : Bytes = Cipher.decryptBytes(encryptedBytes, key, transformation, salt, iterations);
      var message : String = messageBytes.toString(charset);
      ```


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - key - The key to use for decryption.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **See Also:**
    - [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1)

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decryptBytes(Bytes, KeyRef, String, String, Number) - Variant 2
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2), which allows
      to use a key in the keystore for the decryption.


    **Parameters:**
    - encryptedBytes - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2))
    - privateKey - A reference to a private key in the key store.
    - transformation - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2))
    - saltOrIV - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2))
    - iterations - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2))

    **Returns:**
    - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2))

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decryptBytes(Bytes, String, String, String, Number) - Variant 2
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level decryption API. Decrypts the passed bytes using the specified
      key and applying the transformations described by the specified
      parameters.
      
      
      Typical usage:
      
      
      ```
      var base64Msg : String = "some_encoded_encrypted_message";
      var charset : String = "UTF8";  // or "windows-1252", etc.
      
      var encryptedBytes : Bytes = Encoding.fromBase64(base64Msg);
      var messageBytes : Bytes = Cipher.decryptBytes(encryptedBytes, key, transformation, salt, iterations);
      var message : String = messageBytes.toString(charset);
      ```


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - key - The key to use for decryption.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **See Also:**
    - [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2)

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decryptBytes(Bytes, KeyRef, String, String, Number) - Variant 3
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3), which allows
      to use a key in the keystore for the decryption.


    **Parameters:**
    - encryptedBytes - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3))
    - privateKey - A reference to a private key in the key store.
    - transformation - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3))
    - saltOrIV - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3))
    - iterations - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3))

    **Returns:**
    - (see [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3))

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### decryptBytes(Bytes, String, String, String, Number) - Variant 3
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level decryption API. Decrypts the passed bytes using the specified
      key and applying the transformations described by the specified
      parameters.
      
      
      Typical usage:
      
      
      ```
      var base64Msg : String = "some_encoded_encrypted_message";
      var charset : String = "UTF8";  // or "windows-1252", etc.
      
      var encryptedBytes : Bytes = Encoding.fromBase64(base64Msg);
      var messageBytes : Bytes = Cipher.decryptBytes(encryptedBytes, key, transformation, salt, iterations);
      var message : String = messageBytes.toString(charset);
      ```


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - key - The key to use for decryption.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **See Also:**
    - [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3)

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### decrypt(String, KeyRef, String, String, Number) - Variant 1
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1), which allows
      to use a key in the keystore for the decryption.
      
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.


    **Parameters:**
    - base64Msg - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1))
    - privateKey - A reference to a private key in the key store.
    - transformation - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1))
    - saltOrIV - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1))
    - iterations - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1))

    **Returns:**
    - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1))

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decrypt(String, String, String, String, Number) - Variant 1
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decrypts the passed Base-64 encoded message using the passed key and
      applying the transformations described by the passed parameters.
      
      
      Decryption is the process of getting back the original data from the
      cipher-text using a decryption key.


    **Parameters:**
    - base64Msg - the base64 encoded cipher bytes
    - key - When using a _symmetric_ cryptographic algorithm, use the same key to encrypt and decrypt.           If the cryptographic algorithm is _symmetric_           (for example, AES)           or _asymmetric_ (for example, RSA), the key needs to be passed as a           base64-encoded string. The only exception is the _symmetric_ cryptographic           algorithms _Password Based Encryption_ (PBE). With PBE the key needs           to be passed as plain string (_without_ any encoding). Note that for RSA the           key length should be at least 2048 bits.
    - transformation - The transformation has to be in _"algorithm/mode/padding"_ format. See           the corresponding encrypt method for supported transformations.
    - saltOrIV - Initialization value appropriate for the algorithm, this might           be a Binary Salt or AlgorithmParameter or InitializationVector           (see the corresponding encrypt method for details).           Should be appropriate for the algorithm being used. If this value is           null, a default initialization value will be used by the engine.           The same value used to Encrypt needs to be supplied to the           Decrypt function for many algorithms to successfully decrypt           the data, so it is best practice to specify an appropriate value.
    - iterations - The number of passes to make when turning a passphrase into a key.           This is only applicable for some types of algorithm.           Password Based Encryption (PBE) algorithms use this parameter,           and Block Encryption algorithms do not.           If this value is relevant to the algorithm it would be best           practice to supply it, as the same value would be needed to           decrypt the data that was used to encrypt the data.

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decrypt(String, KeyRef, String, String, Number) - Variant 2
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2), which allows
      to use a key in the keystore for the decryption.
      
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.


    **Parameters:**
    - base64Msg - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2))
    - privateKey - A reference to a private key in the key store.
    - transformation - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2))
    - saltOrIV - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2))
    - iterations - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2))

    **Returns:**
    - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2))

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decrypt(String, String, String, String, Number) - Variant 2
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decrypts the passed Base-64 encoded message using the passed key and
      applying the transformations described by the passed parameters.
      
      
      Decryption is the process of getting back the original data from the
      cipher-text using a decryption key.


    **Parameters:**
    - base64Msg - the base64 encoded cipher bytes
    - key - When using a _symmetric_ cryptographic algorithm, use the same key to encrypt and decrypt.           If the cryptographic algorithm is _symmetric_           (for example, AES)           or _asymmetric_ (for example, RSA), the key needs to be passed as           a base64-encoded string. The only exception is the _symmetric_ cryptographic           algorithms _Password Based Encryption_ (PBE). With PBE the key needs           to be passed as plain string (_without_ any encoding).
    - transformation - The transformation has to be in _"algorithm/mode/padding"_ format. See           the corresponding encrypt method for supported transformations.
    - saltOrIV - Initialization value appropriate for the algorithm, this might           be a Binary Salt or AlgorithmParameter or InitializationVector           (see the corresponding encrypt method for details).           Should be appropriate for the algorithm being used. If this value is           null, a default initialization value will be used by the engine.           The same value used to Encrypt needs to be supplied to the           Decrypt function for many algorithms to successfully decrypt           the data, so it is best practice to specify an appropriate value.
    - iterations - The number of passes to make when turning a passphrase into a key.           This is only applicable for some types of algorithm.           Password Based Encryption (PBE) algorithms use this parameter,           and Block Encryption algorithms do not.           If this value is relevant to the algorithm it would be best           practice to supply it, as the same value would be needed to           decrypt the data that was used to encrypt the data.

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decrypt(String, KeyRef, String, String, Number) - Variant 3
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3), which allows
      to use a key in the keystore for the decryption.
      
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.


    **Parameters:**
    - base64Msg - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3))
    - privateKey - A reference to a private key in the key store.
    - transformation - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3))
    - saltOrIV - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3))
    - iterations - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3))

    **Returns:**
    - (see [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3))

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### decrypt(String, String, String, String, Number) - Variant 3
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decrypts the passed Base-64 encoded message using the passed key and
      applying the transformations described by the passed parameters.
      
      
      Decryption is the process of getting back the original data from the
      cipher-text using a decryption key.


    **Parameters:**
    - base64Msg - the base64 encoded cipher bytes
    - key - When using a _symmetric_ cryptographic algorithm, use the same key to encrypt and decrypt.           If the cryptographic algorithm is _symmetric_           (for example, AES)           or _asymmetric_ (for example, RSA), the key needs to be passed as a           base64-encoded string. The only exception is the _symmetric_ cryptographic           algorithms _Password Based Encryption_ (PBE). With PBE the key needs           to be passed as plain string (_without_ any encoding).
    - transformation - The transformation has to be in _"algorithm/mode/padding"_ format. See           the corresponding encrypt method for supported transformations.
    - saltOrIV - Initialization value appropriate for the algorithm, this might           be a Binary Salt or AlgorithmParameter or InitializationVector           (see the corresponding encrypt method for details).           Should be appropriate for the algorithm being used.           The same value used to Encrypt needs to be supplied to the           Decrypt function for many algorithms to successfully decrypt           the data, so it is best practice to specify an appropriate value.
    - iterations - The number of passes to make when turning a passphrase into a key.           This is only applicable for some types of algorithm.           Password Based Encryption (PBE) algorithms use this parameter,           and Block Encryption algorithms do not.           If this value is relevant to the algorithm it would be best           practice to supply it, as the same value would be needed to           decrypt the data that was used to encrypt the data.

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encryptBytes(Bytes, CertificateRef, String, String, Number) - Variant 1
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1), which allows
      to use a key in the keystore for the encryption.
      
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.


    **Parameters:**
    - messageBytes - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1))
    - publicKey - A reference to a public key.
    - transformation - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1))
    - saltOrIV - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1))
    - iterations - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1))

    **Returns:**
    - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1))

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encryptBytes(Bytes, String, String, String, Number) - Variant 1
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level encryption API. Encrypts the passed bytes by using the
      specified key and applying the transformations described by the specified
      parameters.
      
      
      Typical usage:
      
      
      ```
      var message : String = "some_message";
      var charset : String = "UTF8"; // or "windows-1252", etc.
      
      // encrypt the message
      var messageBytes : Bytes = new Bytes(message, charset);
      var encryptedBytes : Bytes = Cipher.encryptBytes(messageBytes, key, transformation, salt, iterations);
      var encrypted : String = Encoding.toBase64(encryptedBytes);
      ```


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - key - The key to use for encryption.
    - transformation - The transformation to apply.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase             into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1)

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encryptBytes(Bytes, CertificateRef, String, String, Number) - Variant 2
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2), which allows
      to use a key in the keystore for the encryption.
      
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.


    **Parameters:**
    - messageBytes - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2))
    - publicKey - A reference to a public key.
    - transformation - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2))
    - saltOrIV - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2))
    - iterations - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2))

    **Returns:**
    - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2))

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encryptBytes(Bytes, String, String, String, Number) - Variant 2
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level encryption API. Encrypts the passed bytes by using the
      specified key and applying the transformations described by the specified
      parameters.
      
      
      Typical usage:
      
      
      ```
      var message : String = "some_message";
      var charset : String = "UTF8"; // or "windows-1252", etc.
      
      // encrypt the message
      var messageBytes : Bytes = new Bytes(message, charset);
      var encryptedBytes : Bytes = Cipher.encryptBytes(messageBytes, key, transformation, salt, iterations);
      var encrypted : String = Encoding.toBase64(encryptedBytes);
      ```


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - key - The key to use for encryption.
    - transformation - The transformation to apply.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase             into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2)

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encryptBytes(Bytes, CertificateRef, String, String, Number) - Variant 3
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3), which allows
      to use a key in the keystore for the encryption.
      
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.


    **Parameters:**
    - messageBytes - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3))
    - publicKey - A reference to a public key.
    - transformation - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3))
    - saltOrIV - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3))
    - iterations - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3))

    **Returns:**
    - (see [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3))

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encryptBytes(Bytes, String, String, String, Number) - Variant 3
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level encryption API. Encrypts the passed bytes by using the
      specified key and applying the transformations described by the specified
      parameters.
      
      
      Typical usage:
      
      
      ```
      var message : String = "some_message";
      var charset : String = "UTF8"; // or "windows-1252", etc.
      
      // encrypt the message
      var messageBytes : Bytes = new Bytes(message, charset);
      var encryptedBytes : Bytes = Cipher.encryptBytes(messageBytes, key, transformation, salt, iterations);
      var encrypted : String = Encoding.toBase64(encryptedBytes);
      ```


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - key - The key to use for encryption.
    - transformation - The transformation to apply.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase             into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3)

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encrypt(String, CertificateRef, String, String, Number) - Variant 1
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to
      [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1), which allows you to
      use a key in the keystore for encryption.
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.
      
      
      For asymmetric algorithms a private/public key pair is required.
      Commerce Cloud Digital only allows you to add private keys in the format \*.p12 and \*.pfx.
      You can assign private keys an extra password in Business Manager. Public keys
      can only be imported as trusted certificates in the format \*.crt, \*.pem,
      \*.der, and \*.cer.
      
      
      Key pairs for asymmetric ciphers can be generated with an arbitrary tool.
      One of the most popular options is the open source tool OpenSSL.
      OpenSSL has a command-line syntax and is available on major platforms.
      
      
      The following steps are involved in **creating an RSA key pair:**
      
      1. Generate a public and a non-protected private key ( \*.crt and \*.key ).


    **Parameters:**
    - message - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1))
    - publicKey - A reference to a public key.
    - transformation - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1))
    - saltOrIV - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1))
    - iterations - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1))

    **Returns:**
    - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1))

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encrypt(String, String, String, String, Number) - Variant 1
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      
      Encryption is the process of converting normal data or plain text to
      something incomprehensible or cipher-text by applying transformations,
      which are the operation (or set of operations) to be performed on given input
      to produce some output. A transformation always includes the name of a
      cryptographic algorithm (for example, RSA) and may be followed by a mode and padding scheme.
      The supported algorithms are listed in the parameter description below.
      
      
      The cryptographic algorithms can be partitioned into _symmetric_
      and _asymmetric_ (or public key/private key).
      
      
      **Symmetric** or "secret key" algorithms use the same key to encrypt
      and to decrypt the data. Symmetric algorithms are what most people think
      of as codes: using a well-known algorithm and a secret key to encode information,
      which can be decoded using the same algorithm and the same key. The algorithm
      is not secret, the secrecy is inherent to guarding the key. A significant
      problem with symmetric ciphers is that it is difficult to transfer the keys
      themselves securely. Symmetric algorithms include _password-based_ algorithms.
      
      
      **AES with key length of 256 bits is the preferred choice for symmetric encryption going forward.
       Please consider switching to it if you are using any other scheme or if using AES with a
       shorter key length. The rest of the symmetric algorithms will be deprecated in the future.**
      
      
      **Asymmetric** or "public key" cryptography uses a public/private key pair, and then publishes the public key.
      Only the holder of the private key will be able to decrypt.
      The public key and private key together are also called a "key pair".
      Data encrypted with one key can only be decrypted using the other key
      from the pair, and it is not possible to deduce one key from the other.
      This helps to solve the key distribution problem since it is possible to
      publicise one of the keys widely (the "public key") and keep the other
      a closely guarded secret (the "private key"). Many partners can then
      send data encrypted with the public key, but only the holder of the
      corresponding private key can decrypt it.
      
      
      Key pairs for asymmetric ciphers can be generated with an arbitrary tool.
      One of the most popular options is the open source tool OpenSSL.
      OpenSSL has a command-line syntax and is available on major platforms.
      
      
      The following steps are involved in **creating an RSA key pair:**
      
      1. Generate an RSA private key with keylength of 2048 bits. Store this key in a safe place.
      
         ```
         openssl genrsa -out rsaprivatekey.pem 2048
         ```
      
      2. Generate a public key from the private key. You use the public key to encrypt messages with Cipher.encrypt. OpenSSL saves the key PEM-encoded; this means the key is saved with a base64 encoding. After you removed the header and footer lines you can pass the content directly to the API method.
      
         ```
         openssl rsa -in rsaprivatekey.pem -out publickey.pem -pubout
         ```
      
      3. Generate a private key in PKCS\#8 format. You use that key to decrypt messages with Cipher.decrypt. OpenSSL saves the key PEM-encoded; this means the key is saved with a base64 encoding. After you removed the header and footer lines you can pass the content directly to the API method.
      
         ```
         openssl pkcs8 -topk8 -in rsaprivatekey.pem -out privatekey.pem -nocrypt
         ```
      
      
      
      
      **Modes**
      
      The following modes of operation are block cipher operations that
      are used with some algorithms.
      
      - "NONE" no mode
      - "CBC" Cipher Block Chaining (defined in FIPS PUB 81)
      - "CTR" Counter mode or Segmented Integer Counter mode (defined in FIPS PUB 81)
      - "CTS" CipherText Streaming mode
      - "CFB" Cipher Feedback Mode,  can be referred to with key  length referenced as "CFB8","CFB16","CFB24".."CFB64" (defined in FIPS PUB 81)
      - "ECB" Electronic Cook book  as defined in: The National  Institute of Standards and Technology (NIST) Federal Information  Processing Standard (FIPS) PUB 81, "DES Modes of Operation,"  U.S. Department of Commerce, Dec 1980.
      - "OFB" Output Feedback Mode, can be referred to with key  length referenced as "OFB8","OFB16","OFB24".."OFB64" (defined in FIPS PUB 81)
      - "PCBC" Propagating Cipher Block Chaining (defined in Kerberos V4)
      
      
      
      **Paddings**
      
      - "NoPadding": No padding.
      - OAEPWith<digest>And<mgf>Padding: 
      Optimal Asymmetric Encryption  Padding scheme defined in PKCS\#1, where <digest>should be replaced  by the message digest and <mgf>by the mask generation function.  
      Examples: OAEPWITHSHA-256ANDMGF1PADDING, OAEPWITHSHA-384ANDMGF1PADDING, OAEPWITHSHA-512ANDMGF1PADDING
      - ISO10126PADDING: the ISO10126-2:1991 DEA padding scheme
      - PKCS1Padding: Public Key Cryptography Standard \#1, a standard  for padding from RSA Laboratories that can encrypt messages up  to 11 bytes smaller than the modulus size in bytes.
      - PKCS5Padding: Public Key Cryptography Standard \#1, a standard  for padding from RSA Laboratories, "PKCS\#5: Password-Based Encryption Standard," version 1.5, November 1993.
      - SSL3Padding: The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996, section 5.2.3.2 (CBC block cipher)


    **Parameters:**
    - message - A string to encrypt (will be first converted with UTF-8 encoding           into a byte stream)
    - key - A string ready for use with the algorithm.           The key's format depends on the algorithm specified and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.            The cryptographic algorithms can be partitioned into _symmetric_           and _asymmetric_ (or public key/private key). Symmetric algorithms           include _password-based_ algorithms.           Symmetric keys are usually a base64-encoded array of bytes.           Asymmetric keys are "key pairs" with a public key and a private key.           To encrypt using asymmetric algorithms, provide the public key.           To decrypt using asymmetric algorithms, provide the private key from           the same pair in PKCS\#8 format, base64-encoded.           See class documentation on how to generate a key pair.           If the cryptographic algorithm is _symmetric_           (for example, AES)           or _asymmetric_ (for example, RSA), the key needs to be passed as a           base64-encoded string. The only exception is the _symmetric_ cryptographic           algorithms _Password Based Encryption_ (PBE). With PBE the key needs           to be passed as plain string (_without_ any encoding).
    - transformation - The transformation has to be in _"algorithm/mode/padding"_ format.           Symmetric or "secret key" algorithms use the same key to encrypt           and to decrypt the data. Asymmetric or "public key" cryptography           uses a public/private key pair, and then publishes the public key.           Only the holder of the private key will be able to decrypt.           The public key and private key are also known as a "key pair".            Supported Symmetric transformations include:                       <li>"AES" or Rijndael, Advanced Encryption Standard as specified by NIST           **AES with key length of 256 is the preferred choice for symmetric encryption**           Keysizes: 128, 192, or 256           Modes: "ECB","CBC","PCBC","CTR","CTS","CFB","CFB8","CFB16","CFB24".."CFB64", "OFB","OFB8","OFB16","OFB24".."OFB64"           Padding: "PKCS5Padding"           </li>           </ul>            Note that ARCFOUR, Blowfish, DES, RC2, DESede, DESedeWrap, PBEWithMD5AndDES, PBEWithMD5AndTripleDES1,           PBEWithSHA1AndDESede and PBEWithSHA1AndRC2\_40 transformations have been deprecated. Also, PKCS5Padding is           the only supported Padding. NOPADDING and ISO10126PADDING have been deprecated.            Supported Asymmetric transformations include:                       <li>"RSA"           Mode: "ECB"           Padding: "OAEPWITHSHA-256ANDMGF1PADDING", "OAEPWITHSHA-384ANDMGF1PADDING", "OAEPWITHSHA-512ANDMGF1PADDING"           </li>           </ul>            Note that for RSA the key length should be at least 2048 bits. Also, the following Padding options           have been deprecated: NOPADDING, PKCS1PADDING, OAEPWITHMD5ANDMGF1PADDING,OAEPWITHSHA1ANDMGF1PADDING and           OAEPWITHSHA-1ANDMGF1PADDING.
    - saltOrIV - Initialization value appropriate for the algorithm, this might           be a Binary Salt or AlgorithmParameter or InitializationVector.           (As binary values cannot be passed, the equivalent Base64 String           should be passed for any binary salt value).            Should be appropriate for the algorithm being used. If this value is           null, a default initialization value will be used by the engine.           The same value used to Encrypt needs to be supplied to the           Decrypt function for many algorithms to successfully decrypt           the data, so it is best practice to specify an appropriate value.            Requirements for the size and generation of DES initialization           vectors (IV) are derived from FIPS 74 and FIPS 81 from the National           Institute of Standards and Technology. CBC mode requires an IV           with length 64 bits; CFB uses 48-64 bits; OFB uses 64 bits.           If the IV is to be used with DES in the OFB mode, then it is not           acceptable for the IV to remain fixed for multiple encryptions,           if the same key is used for those encryptions.            For Block Encryption algorithms this is the encoded Base64           String equivalent to the a random number to use as a "salt"           to use with the algorithm.           The algorithm must contain a Feedback Mode other than ECB.           This must be a binary value that is exactly the same size           as the algorithm block size.           RC5 uses an optional 8-byte initialization vector (IV),           but only in feedback mode (see CFB above).           For Password Based Encryption algorithms, the salt is the encoded           Base64 String equivalent to a random number value to transform the           password into a key. PBE derives an encryption key from a password.           In order to make the task of getting from password to key very           time-consuming for an attacker, most PBE implementations will           mix in a random number, known as a salt, to create the key. The salt           value and the iteration count are then combined into a           PBEParameterSpecification to initialize the cipher.            The PKCS\#5 spec from RSA Labs defines the parameters for           password-based encryption (PBE).           The RSA algorithm requires a salt with length as defined in PKCS\#1.
    - iterations - The number of passes to make when turning a passphrase into a key.           This is only applicable for some types of algorithm.           Password Based Encryption (PBE) algorithms use this parameter,           and Block Encryption algorithms do not.           If this value is relevant to the algorithm it would be best           practice to supply it, as the same value would be needed to           decrypt the data.

    **Returns:**
    - the encrypted message encoded as a String using base 64 encoding.

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encrypt(String, CertificateRef, String, String, Number) - Variant 2
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to
      [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2), which allows you to
      use a key in the keystore for encryption.
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.
      
      
      For asymmetric algorithms a private/public key pair is required.
      Commerce Cloud Digital only allows you to add private keys in the format \*.p12 and \*.pfx.
      You can assign private keys an extra password in Business Manager. Public keys
      can only be imported as trusted certificates in the format \*.crt, \*.pem,
      \*.der, and \*.cer.
      
      
      Key pairs for asymmetric ciphers can be generated with an arbitrary tool.
      One of the most popular options is the open source tool OpenSSL.
      OpenSSL has a command-line syntax and is available on major platforms.
      
      
      The following steps are involved in **creating an RSA key pair:**
      
      1. Generate a public and a non-protected private key ( \*.crt and \*.key ).
      
         ```
         openssl req -x509 -newkey rsa:2048 -keyout nopass.key -out nopass.crt -days 365 -nodes
         ```
      
      2. Generate a keystore that contains the public and private keys ( \*.p12 ).
      
         ```
         openssl pkcs12 -export -out nopass.p12 -inkey nopass.key -in nopass.crt
         ```
      
      
      To import a private or public key into the Digital keystore, navigate to
      **Administration > Operations > Private Keys and Certificates**
      Use a .p12 file to import a private key and a \*.crt to import a public key.
      
      
      Typical usage:
      
      
      ```
      var plain : String = "some_plain_text";
      var publicKeyRef = new CertificateRef("rsa-certificate-2048");
      var cipher : Cipher = new Cipher();
      var encrypted : String = cipher.encrypt(plain, publicKeyRef, "RSA", null, 0);
      ```


    **Parameters:**
    - message - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2))
    - publicKey - A reference to a public key.
    - transformation - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2))
    - saltOrIV - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2))
    - iterations - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2))

    **Returns:**
    - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2))

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encrypt(String, String, String, String, Number) - Variant 2
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      
      Encryption is the process of converting normal data or plain text to
      something incomprehensible or cipher-text by applying transformations,
      which are the operation (or set of operations) to be performed on given input
      to produce some output. A transformation always includes the name of a
      cryptographic algorithm (for example, RSA) and may be followed by a mode and padding scheme.
      The supported algorithms are listed in the parameter description below.
      
      The cryptographic algorithms can be partitioned into _symmetric_
      and _asymmetric_ (or public key/private key).
      
      
      **Symmetric** or "secret key" algorithms use the same key to encrypt
      and to decrypt the data. Symmetric algorithms are what most people think
      of as codes: using a well-known algorithm and a secret key to encode information,
      which can be decoded using the same algorithm and the same key. The algorithm
      is not secret, the secrecy is inherent to guarding the key. A significant
      problem with symmetric ciphers is that it is difficult to transfer the keys
      themselves securely. Symmetric algorithms include _password-based_ algorithms.
      
      
      **AES with key length of 256 bits is the preferred choice for symmetric encryption going forward.
       Please consider switching to it if you are using any other scheme or if using AES with a
       shorter key length. The rest of the symmetric algorithms will be deprecated in the future.**
      
      
      **Asymmetric** or "public key" cryptography uses a public/private key pair, and then publishes the public key.
      Only the holder of the private key will be able to decrypt.
      The public key and private key together are also called a "key pair".
      Data encrypted with one key can only be decrypted using the other key
      from the pair, and it is not possible to deduce one key from the other.
      This helps to solve the key distribution problem since it is possible to
      publicise one of the keys widely (the "public key") and keep the other
      a closely guarded secret (the "private key"). Many partners can then
      send data encrypted with the public key, but only the holder of the
      corresponding private key can decrypt it.
      
      
      Key pairs for asymmetric ciphers can be generated with an arbitrary tool.
      One of the most popular options is the open source tool OpenSSL.
      OpenSSL has a command-line syntax and is available on major platforms.
      
      
      The following steps are involved in **creating an RSA key pair:**
      
      1. Generate an RSA private key with keylength of 2048 bits. Store this key in a safe place.
      
         ```
         openssl genrsa -out rsaprivatekey.pem 2048
         ```
      
      2. Generate a public key from the private key. You use the public key to encrypt messages with Cipher.encrypt. OpenSSL saves the key PEM-encoded; this means the key is saved with a base64 encoding. After you removed the header and footer lines you can pass the content directly to the API method.
      
         ```
         openssl rsa -in rsaprivatekey.pem -out publickey.pem -pubout
         ```
      
      3. Generate a private key in PKCS\#8 format. You use that key to decrypt messages with Cipher.decrypt. OpenSSL saves the key PEM-encoded; this means the key is saved with a base64 encoding. After you removed the header and footer lines you can pass the content directly to the API method.
      
         ```
         openssl pkcs8 -topk8 -in rsaprivatekey.pem -out privatekey.pem -nocrypt
         ```
      
      
      
      
      **Modes**
      
      The following modes of operation are block cipher operations that
      are used with some algorithms.
      
      - "NONE" no mode
      - "CBC" Cipher Block Chaining (defined in FIPS PUB 81)
      - "CTR" Counter mode or Segmented Integer Counter mode (defined in FIPS PUB 81)
      - "CTS" CipherText Streaming mode
      - "CFB" Cipher Feedback Mode,  can be referred to with key  length referenced as "CFB8","CFB16","CFB24".."CFB64" (defined in FIPS PUB 81)
      - "ECB" Electronic Cook book  as defined in: The National  Institute of Standards and Technology (NIST) Federal Information  Processing Standard (FIPS) PUB 81, "DES Modes of Operation,"  U.S. Department of Commerce, Dec 1980.
      - "OFB" Output Feedback Mode, can be referred to with key  length referenced as "OFB8","OFB16","OFB24".."OFB64" (defined in FIPS PUB 81)
      - "PCBC" Propagating Cipher Block Chaining (defined in Kerberos V4)
      
      
      
      **Paddings**
      
      - "NoPadding": No padding.
      - OAEPWith<digest>And<mgf>Padding: 
      Optimal Asymmetric Encryption  Padding scheme defined in PKCS\#1, where <digest>should be replaced  by the message digest and <mgf>by the mask generation function.  
      Examples: OAEPWITHSHA-256ANDMGF1PADDING, OAEPWITHSHA-384ANDMGF1PADDING, OAEPWITHSHA-512ANDMGF1PADDING
      - ISO10126PADDING: the ISO10126-2:1991 DEA padding scheme
      - PKCS1Padding: Public Key Cryptography Standard \#1, a standard  for padding from RSA Laboratories that can encrypt messages up  to 11 bytes smaller than the modulus size in bytes.
      - PKCS5Padding: Public Key Cryptography Standard \#1, a standard  for padding from RSA Laboratories, "PKCS\#5: Password-Based Encryption Standard," version 1.5, November 1993.
      - SSL3Padding: The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996, section 5.2.3.2 (CBC block cipher)


    **Parameters:**
    - message - A string to encrypt (will be first converted with UTF-8 encoding           into a byte stream)
    - key - A string ready for use with the algorithm.           The key's format depends on the algorithm specified and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.            The cryptographic algorithms can be partitioned into _symmetric_           and _asymmetric_ (or public key/private key). Symmetric algorithms           include _password-based_ algorithms.           Symmetric keys are usually a base64-encoded array of bytes.           Asymmetric keys are "key pairs" with a public key and a private key.           To encrypt using asymmetric algorithms, provide the public key.           To decrypt using asymmetric algorithms, provide the private key from           the same pair in PKCS\#8 format, base64-encoded.           See class documentation on how to generate a key pair.           If the cryptographic algorithm is _symmetric_           (for example, AES)           or _asymmetric_ (for example, RSA), the key needs to be passed as a           base64-encoded string. The only exception is the _symmetric_ cryptographic           algorithms _Password Based Encryption_ (PBE). With PBE the key needs           to be passed as plain string (_without_ any encoding).
    - transformation - The transformation  has to be in _"algorithm/mode/padding"_ format.           Symmetric or "secret key" algorithms use the same key to encrypt           and to decrypt the data. Asymmetric or "public key" cryptography           uses a public/private key pair, and then publishes the public key.           Only the holder of the private key will be able to decrypt.           The public key and private key are also known as a "key pair".            Supported Symmetric transformations include:                       <li>"AES" or Rijndael, Advanced Encryption Standard as specified by NIST           **AES with key length of 256 is the preferred choice for symmetric encryption**           Keysizes: 128, 192, or 256           Modes: "ECB","CBC","PCBC","CTR","CTS","CFB","CFB8","CFB16","CFB24".."CFB64", "OFB","OFB8","OFB16","OFB24".."OFB64"           Padding: "PKCS5Padding"           </li>           </ul>            Note that ARCFOUR, Blowfish, DES, RC2, DESede, DESedeWrap, PBEWithMD5AndDES, PBEWithMD5AndTripleDES1,           PBEWithSHA1AndDESede and PBEWithSHA1AndRC2\_40 transformations have been deprecated. Also, PKCS5Padding is           the only supported Padding. NOPADDING and ISO10126PADDING have been deprecated.            Supported Asymmetric transformations include:                       <li>"RSA"           Mode: "ECB"           Padding: "OAEPWITHSHA-256ANDMGF1PADDING", "OAEPWITHSHA-384ANDMGF1PADDING", "OAEPWITHSHA-512ANDMGF1PADDING"           </li>           </ul>            Note that for RSA the key length should be at least 2048 bits. Also, the following Padding options           have been deprecated: NOPADDING, PKCS1PADDING, OAEPWITHMD5ANDMGF1PADDING, OAEPWITHSHA1ANDMGF1PADDING and           OAEPWITHSHA-1ANDMGF1PADDING.
    - saltOrIV - Initialization value appropriate for the algorithm, this might           be a Binary Salt or AlgorithmParameter or InitializationVector.           (As binary values cannot be passed, the equivalent Base64 String           should be passed for any binary salt value).            Should be appropriate for the algorithm being used. If this value is           null, a default initialization value will be used by the engine.           The same value used to Encrypt needs to be supplied to the           Decrypt function for many algorithms to successfully decrypt           the data, so it is best practice to specify an appropriate value.            Requirements for the size and generation of DES initialization           vectors (IV) are derived from FIPS 74 and FIPS 81 from the National           Institute of Standards and Technology. CBC mode requires an IV           with length 64 bits; CFB uses 48-64 bits; OFB uses 64 bits.           If the IV is to be used with DES in the OFB mode, then it is not           acceptable for the IV to remain fixed for multiple encryptions,           if the same key is used for those encryptions.            For Block Encryption algorithms this is the encoded Base64           String equivalent to the a random number to use as a "salt"           to use with the algorithm.           The algorithm must contain a Feedback Mode other than ECB.           This must be a binary value that is exactly the same size           as the algorithm block size.           RC5 uses an optional 8-byte initialization vector (IV),           but only in feedback mode (see CFB above).           For Password Based Encryption algorithms, the salt is the encoded           Base64 String equivalent to a random number value to transform the           password into a key. PBE derives an encryption key from a password.           In order to make the task of getting from password to key very           time-consuming for an attacker, most PBE implementations will           mix in a random number, known as a salt, to create the key. The salt           value and the iteration count are then combined into a           PBEParameterSpecification to initialize the cipher.            The PKCS\#5 spec from RSA Labs defines the parameters for           password-based encryption (PBE).           The RSA algorithm requires a salt with length as defined in PKCS\#1.           DSA has a specific initialization that uses three integers to           build a DSAParameterSpec (a prime, a sub-prime and a base).           To use this algorithm you should use the JCE or another           provider to supply a DSAParameterSpec and then supply the           Base64 equivalent string as the "salt". Please see the           documentation from the provider for additional restrictions.
    - iterations - The number of passes to make when turning a passphrase into a key.           This is only applicable for some types of algorithm.           Password Based Encryption (PBE) algorithms use this parameter,           and Block Encryption algorithms do not.           If this value is relevant to the algorithm it would be best           practice to supply it, as the same value would be needed to           decrypt the data.

    **Returns:**
    - the encrypted message encoded as a String using base 64 encoding.

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encrypt(String, CertificateRef, String, String, Number) - Variant 3
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to
      [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3), which allows you to
      use a key in the keystore for encryption.
      
      
      Note: Only asymmetric (public/private key pair) algorithms can be used
      with this method, since only those keys can be added to a keystore.
      
      
      For asymmetric algorithms a private/public key pair is required.
      Commerce Cloud Digital only allows you to add private keys in the format \*.p12 and \*.pfx.
      You can assign private keys an extra password in Business Manager. Public keys
      can only be imported as trusted certificates in the format \*.crt, \*.pem,
      \*.der, and \*.cer.
      
      
      Key pairs for asymmetric ciphers can be generated with an arbitrary tool.
      One of the most popular options is the open source tool OpenSSL.
      OpenSSL has a command-line syntax and is available on major platforms.
      
      
      The following steps are involved in **creating an RSA key pair:**
      
      1. Generate a public and a non-protected private key ( \*.crt and \*.key ).
      
         ```
         openssl req -x509 -newkey rsa:2048 -keyout nopass.key -out nopass.crt -days 365 -nodes
         ```
      
      2. Generate a keystore that contains the public and private keys ( \*.p12 ).
      
         ```
         openssl pkcs12 -export -out nopass.p12 -inkey nopass.key -in nopass.crt
         ```
      
      
      To import a private or public key into the Digital keystore, navigate to
      **Administration > Operations > Private Keys and Certificates**
      Use a .p12 file to import a private key and a \*.crt to import a public key.
      
      
      Typical usage:
      
      
      ```
      var plain : String = "some_plain_text";
      var publicKeyRef = new CertificateRef("rsa-certificate-2048");
      var cipher : Cipher = new Cipher();
      var encrypted : String = cipher.encrypt(plain, publicKeyRef, "RSA", null, 0);
      ```


    **Parameters:**
    - message - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3))
    - publicKey - A reference to a public key.
    - transformation - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3))
    - saltOrIV - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3))
    - iterations - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3))

    **Returns:**
    - (see [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3))

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encrypt(String, String, String, String, Number) - Variant 3
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      
      Encryption is the process of converting normal data or plain text to
      something incomprehensible or cipher-text by applying transformations,
      which are the operation (or set of operations) to be performed on given input
      to produce some output. A transformation always includes the name of a
      cryptographic algorithm (for example, RSA) and may be followed by a mode and padding scheme.
      The supported algorithms are listed in the parameter description below.
      
      The cryptographic algorithms can be partitioned into _symmetric_
      and _asymmetric_ (or public key/private key).
      
      
      **Symmetric** or "secret key" algorithms use the same key to encrypt
      and to decrypt the data. Symmetric algorithms are what most people think
      of as codes: using a well-known algorithm and a secret key to encode information,
      which can be decoded using the same algorithm and the same key. The algorithm
      is not secret, the secrecy is inherent to guarding the key. A significant
      problem with symmetric ciphers is that it is difficult to transfer the keys
      themselves securely. Symmetric algorithms include _password-based_ algorithms.
      
      **AES with key length of 256 bits is the preferred choice for symmetric encryption going forward.
       Please consider switching to it if you are using any other scheme or if using AES with a
       shorter key length. The rest of the symmetric algorithms will be deprecated in the future.**
      
      
      **Asymmetric** or "public key" cryptography uses a public/private key pair, and then publishes the public key.
      Only the holder of the private key will be able to decrypt.
      The public key and private key together are also called a "key pair".
      Data encrypted with one key can only be decrypted using the other key
      from the pair, and it is not possible to deduce one key from the other.
      This helps to solve the key distribution problem since it is possible to
      publicise one of the keys widely (the "public key") and keep the other
      a closely guarded secret (the "private key"). Many partners can then
      send data encrypted with the public key, but only the holder of the
      corresponding private key can decrypt it.
      
      
      Key pairs for asymmetric ciphers can be generated with an arbitrary tool.
      One of the most popular options is the open source tool OpenSSL.
      OpenSSL has a command-line syntax and is available on major platforms.
      
      
      The following steps are involved in **creating an RSA key pair:**
      
      1. Generate an RSA private key with keylength of 2048 bits. Store this key in a safe place.
      
         ```
         openssl genrsa -out rsaprivatekey.pem 2048
         ```
      
      2. Generate a public key from the private key. You use the public key to encrypt messages with Cipher.encrypt. OpenSSL saves the key PEM-encoded; this means the key is saved with a base64 encoding. After you removed the header and footer lines you can pass the content directly to the API method.
      
         ```
         openssl rsa -in rsaprivatekey.pem -out publickey.pem -pubout
         ```
      
      3. Generate a private key in PKCS\#8 format. You use that key to decrypt messages with Cipher.decrypt. OpenSSL saves the key PEM-encoded; this means the key is saved with a base64 encoding. After you removed the header and footer lines you can pass the content directly to the API method.
      
         ```
         openssl pkcs8 -topk8 -in rsaprivatekey.pem -out privatekey.pem -nocrypt
         ```
      
      
      
      
      **Modes**
      
      The following modes of operation are block cipher operations that
      are used with some algorithms.
      
      - "NONE" no mode
      - "CBC" Cipher Block Chaining (defined in FIPS PUB 81)
      - "CTR" Counter mode or Segmented Integer Counter mode (defined in FIPS PUB 81)
      - "CTS" CipherText Streaming mode
      - "CFB" Cipher Feedback Mode,  can be referred to with key  length referenced as "CFB8","CFB16","CFB24".."CFB64" (defined in FIPS PUB 81)
      - "ECB" Electronic Cook book  as defined in: The National  Institute of Standards and Technology (NIST) Federal Information  Processing Standard (FIPS) PUB 81, "DES Modes of Operation,"  U.S. Department of Commerce, Dec 1980.
      - "GCM" Galois/Counter Mode (defined in NIST SP 800-38D)
      - "OFB" Output Feedback Mode, can be referred to with key  length referenced as "OFB8","OFB16","OFB24".."OFB64" (defined in FIPS PUB 81)
      - "PCBC" Propagating Cipher Block Chaining (defined in Kerberos V4)
      
      
      
      **Paddings**
      
      - "NoPadding": No padding.
      - OAEPWith<digest>And<mgf>Padding: 
      Optimal Asymmetric Encryption  Padding scheme defined in PKCS\#1, where <digest>should be replaced  by the message digest and <mgf>by the mask generation function.  
      Examples: OAEPWITHSHA-256ANDMGF1PADDING, OAEPWITHSHA-384ANDMGF1PADDING, OAEPWITHSHA-512ANDMGF1PADDING
      - ISO10126PADDING: the ISO10126-2:1991 DEA padding scheme
      - PKCS1Padding: Public Key Cryptography Standard \#1, a standard  for padding from RSA Laboratories that can encrypt messages up  to 11 bytes smaller than the modulus size in bytes.
      - PKCS5Padding: Public Key Cryptography Standard \#1, a standard  for padding from RSA Laboratories, "PKCS\#5: Password-Based Encryption Standard," version 1.5, November 1993.
      - SSL3Padding: The padding scheme defined in the SSL Protocol Version 3.0, November 18, 1996, section 5.2.3.2 (CBC block cipher)


    **Parameters:**
    - message - A string to encrypt (will be first converted with UTF-8 encoding           into a byte stream)
    - key - A string ready for use with the algorithm.           The key's format depends on the algorithm specified and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.            The cryptographic algorithms can be partitioned into _symmetric_           and _asymmetric_ (or public key/private key). Symmetric algorithms           include _password-based_ algorithms.           Symmetric keys are usually a base64-encoded array of bytes.           Asymmetric keys are "key pairs" with a public key and a private key.           To encrypt using asymmetric algorithms, provide the public key.           To decrypt using asymmetric algorithms, provide the private key from           the same pair in PKCS\#8 format, base64-encoded.           See class documentation on how to generate a key pair.           If the cryptographic algorithm is _symmetric_           (for example, AES)           or _asymmetric_ (for example, RSA), the key needs to be passed as a           base64-encoded string. The only exception is the _symmetric_ cryptographic           algorithms _Password Based Encryption_ (PBE). With PBE the key needs           to be passed as plain string (_without_ any encoding).
    - transformation - The transformation has to be in _"algorithm/mode/padding"_ format.           Symmetric or "secret key" algorithms use the same key to encrypt           and to decrypt the data. Asymmetric or "public key" cryptography           uses a public/private key pair, and then publishes the public key.           Only the holder of the private key will be able to decrypt.           The public key and private key are also known as a "key pair".            Supported Symmetric transformations include:                       <li>"AES" or Rijndael, Advanced Encryption Standard as specified by NIST           **AES with key length of 256 is the preferred choice for symmetric encryption**           Keysizes: 128, 192, or 256           Modes: "GCM","ECB","CBC","PCBC","CTR","CTS","CFB","CFB8","CFB16","CFB24".."CFB64", "OFB","OFB8","OFB16","OFB24".."OFB64"           Padding: "PKCS5Padding" or "NoPadding" (GCM only)           </li>           </ul>            Note that ARCFOUR, Blowfish, DES, RC2, DESede, DESedeWrap, PBEWithMD5AndDES, PBEWithMD5AndTripleDES1,           PBEWithSHA1AndDESede and PBEWithSHA1AndRC2\_40 transformations have been deprecated. PKCS5Padding is           the only supported Padding for most modes. NOPADDING is only supported for GCM, and ISO10126PADDING has been deprecated.            Supported Asymmetric transformations include:                       <li>"RSA"           Mode: "ECB"           Padding: "OAEPWITHSHA-256ANDMGF1PADDING", "OAEPWITHSHA-384ANDMGF1PADDING", "OAEPWITHSHA-512ANDMGF1PADDING"           </li>           </ul>            Note that for RSA the key length should be at least 2048 bits. Also, the following Padding options have           been deprecated: NOPADDING, PKCS1PADDING, OAEPWITHMD5ANDMGF1PADDING, OAEPWITHSHA1ANDMGF1PADDING and OAEPWITHSHA-1ANDMGF1PADDING.
    - saltOrIV - Initialization value appropriate for the algorithm, this might           be a Binary Salt or AlgorithmParameter or InitializationVector.           (As binary values cannot be passed, the equivalent Base64 String           should be passed for any binary salt value).            Should be appropriate for the algorithm being used.           The same value used to Encrypt needs to be supplied to the           Decrypt function for many algorithms to successfully decrypt           the data, so it is best practice to specify an appropriate value.            Requirements for the size and generation of DES initialization           vectors (IV) are derived from FIPS 74 and FIPS 81 from the National           Institute of Standards and Technology. CBC mode requires an IV           with length 64 bits; CFB uses 48-64 bits; OFB uses 64 bits; GCM uses 96 bits.           If the IV is to be used with DES in the OFB mode, then it is not           acceptable for the IV to remain fixed for multiple encryptions,           if the same key is used for those encryptions.            For Block Encryption algorithms this is the encoded Base64           String equivalent to the a random number to use as a "salt"           to use with the algorithm.           The algorithm must contain a Feedback Mode other than ECB.           This must be a binary value that is exactly the same size           as the algorithm block size.           RC5 uses an optional 8-byte initialization vector (IV),           but only in feedback mode (see CFB above).           For Password Based Encryption algorithms, the salt is the encoded           Base64 String equivalent to a random number value to transform the           password into a key. PBE derives an encryption key from a password.           In order to make the task of getting from password to key very           time-consuming for an attacker, most PBE implementations will           mix in a random number, known as a salt, to create the key. The salt           value and the iteration count are then combined into a           PBEParameterSpecification to initialize the cipher.            The PKCS\#5 spec from RSA Labs defines the parameters for           password-based encryption (PBE).           The RSA algorithm requires a salt with length as defined in PKCS\#1.           DSA has a specific initialization that uses three integers to           build a DSAParameterSpec (a prime, a sub-prime and a base).           To use this algorithm you should use the JCE or another           provider to supply a DSAParameterSpec and then supply the           Base64 equivalent string as the "salt". Please see the           documentation from the provider for additional restrictions.           Extra algorithm parameters may be configured using this field. Each parameter is given as           `<name>=<value>`, and multiple parameters may be separated by a vertical           pipe. Unknown parameters will result in an error. Any parameters MUST be given after the salt, even           if the salt is empty. For example, RSA does not use a salt, so to set the MGF1 digest algorithm           to SHA-256, use `|MGFDigest=SHA-256`           Supported Parameters:           | Parameter | Type | Description |
| --- |--- |--- |
| `MGFDigest` | `String` | Overrides the digest algorithm used by the mask generation function when using OAEP padding.                   Valid values include SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512. The default value is SHA-1. |
| `TagLength` | `Integer` | Overrides the tag length in bits used for GCM mode. Note if a number is given                   without a parameter name, it is treated as the tag length for backward compatibility. The                   default tag length is 128 bits. |

    - iterations - The number of passes to make when turning a passphrase into a key.           This is only applicable for some types of algorithm.           Password Based Encryption (PBE) algorithms use this parameter,           and Block Encryption algorithms do not.           If this value is relevant to the algorithm it would be best           practice to supply it, as the same value would be needed to           decrypt the data.

    **Returns:**
    - the encrypted message encoded as a String using base 64 encoding.

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

<!-- prettier-ignore-end -->

<!-- document id=c3f264f444ad0b5d415fe840f71409f84763a65fba55d04eaf4d53cb0b3074ad url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.ClickStream.md -->

<!-- prettier-ignore-start -->
# Class ClickStream

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.ClickStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md)

Represents the click stream in the session. A maximum number of 50 clicks is
recorded per session. After the maximum is reached, each time the customer
clicks on a new link, the oldest click stream entry is purged. The
ClickStream always remembers the first click.


The click stream is consulted when the GetLastVisitedProducts pipelet is
called to retrieve the products that the customer has recently visited.



## Property Summary

| Property | Description |
| --- | --- |
| [clicks](#clicks): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns a collection with all clicks. |
| [enabled](#enabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the clickstream recording is enabled or not. |
| [first](#first): [ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md) `(read-only)` | Returns the first click within this session. |
| [last](#last): [ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md) `(read-only)` | Returns the last recorded click stream, which is also typically  the current click. |
| [partial](#partial): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is only a partial click stream. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getClicks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md#getclicks)() | Returns a collection with all clicks. |
| [getFirst](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md#getfirst)() | Returns the first click within this session. |
| [getLast](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md#getlast)() | Returns the last recorded click stream, which is also typically  the current click. |
| [isEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md#isenabled)() | Identifies if the clickstream recording is enabled or not. |
| [isPartial](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md#ispartial)() | Identifies if this is only a partial click stream. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### clicks
- clicks: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns a collection with all clicks. The first entry is the oldest
      entry. The last entry is the latest entry. The method returns a copy of
      the click stream, which makes it safe to work with the click stream,
      while it might be modified.



---

### enabled
- enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the clickstream recording is enabled or not.
      It is considered enabled if either:
      - the method [Session.isTrackingAllowed()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#istrackingallowed)returns true
      - or if the above method returns false but the preference 'ClickstreamHonorDNT' is set to false.
      
      When clickstream tracking is not enabled the [getFirst()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md#getfirst) method still operates as expected
      but the rest of the clicks are not collected.



---

### first
- first: [ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md) `(read-only)`
  - : Returns the first click within this session. This first click
      is stored independent of whether entries are purged.



---

### last
- last: [ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md) `(read-only)`
  - : Returns the last recorded click stream, which is also typically
      the current click. In where rare cases (e.g. RedirectURL pipeline) this
      is not the current click, but instead the last recorded click.



---

### partial
- partial: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is only a partial click stream. If the maximum number
      of clicks (50) is recorded, the oldest entry is automatically purged with
      each additional click. In this case, this flag indicates that the click
      stream is only partial.



---

## Method Details

### getClicks()
- getClicks(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a collection with all clicks. The first entry is the oldest
      entry. The last entry is the latest entry. The method returns a copy of
      the click stream, which makes it safe to work with the click stream,
      while it might be modified.


    **Returns:**
    - a collection of ClickStreamEntry instances, sorted
              chronologically.



---

### getFirst()
- getFirst(): [ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md)
  - : Returns the first click within this session. This first click
      is stored independent of whether entries are purged.


    **Returns:**
    - the first click within this session.


---

### getLast()
- getLast(): [ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md)
  - : Returns the last recorded click stream, which is also typically
      the current click. In where rare cases (e.g. RedirectURL pipeline) this
      is not the current click, but instead the last recorded click.


    **Returns:**
    - the last recorded click stream, which is also typically
      the current click.



---

### isEnabled()
- isEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the clickstream recording is enabled or not.
      It is considered enabled if either:
      - the method [Session.isTrackingAllowed()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#istrackingallowed)returns true
      - or if the above method returns false but the preference 'ClickstreamHonorDNT' is set to false.
      
      When clickstream tracking is not enabled the [getFirst()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md#getfirst) method still operates as expected
      but the rest of the clicks are not collected.


    **Returns:**
    - whether clickstream tracking is enabled


---

### isPartial()
- isPartial(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is only a partial click stream. If the maximum number
      of clicks (50) is recorded, the oldest entry is automatically purged with
      each additional click. In this case, this flag indicates that the click
      stream is only partial.


    **Returns:**
    - true if this click stream is partial, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=fd36a6900e4ed8939b918e3d18fa5c9ee5d0d179676f960f98cba75e0b84675e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.ClickStreamEntry.md -->

<!-- prettier-ignore-start -->
# Class ClickStreamEntry

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md)

Represent an entry in the click stream.


## Property Summary

| Property | Description |
| --- | --- |
| [host](#host): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the host. |
| [locale](#locale): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the locale sent from the user agent. |
| [path](#path): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the path. |
| [pipelineName](#pipelinename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the called pipeline. |
| [queryString](#querystring): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the query string. |
| [referer](#referer): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the referer. |
| [remoteAddress](#remoteaddress): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the remote address. |
| [timestamp](#timestamp): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the entry's timestamp. |
| [url](#url): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the full URL for this click. |
| [userAgent](#useragent): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the user agent. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getHost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#gethost)() | Returns the host. |
| [getLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getlocale)() | Returns the locale sent from the user agent. |
| [getParameter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getparameterstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a specific parameter value from the stored query  string. |
| [getPath](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getpath)() | Returns the path. |
| [getPipelineName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getpipelinename)() | Returns the name of the called pipeline. |
| [getQueryString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getquerystring)() | Returns the query string. |
| [getReferer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getreferer)() | Returns the referer. |
| [getRemoteAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getremoteaddress)() | Returns the remote address. |
| [getTimestamp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#gettimestamp)() | Returns the entry's timestamp. |
| [getUrl](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#geturl)() | Returns the full URL for this click. |
| [getUserAgent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md#getuseragent)() | Returns the user agent. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### host
- host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the host.


---

### locale
- locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the locale sent from the user agent.


---

### path
- path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the path.


---

### pipelineName
- pipelineName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the called pipeline. In most cases the
      name can be derived from the path, but not in all cases. If with
      URL rewritting a special landing page is defined for a DNS name, than
      the system internally might use a specific pipeline associated with
      this landing page.



---

### queryString
- queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the query string.


---

### referer
- referer: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the referer.


---

### remoteAddress
- remoteAddress: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the remote address.


---

### timestamp
- timestamp: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the entry's timestamp.


---

### url
- url: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the full URL for this click. The URL is returned as relative
      URL.



---

### userAgent
- userAgent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the user agent.


---

## Method Details

### getHost()
- getHost(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the host.

    **Returns:**
    - the host.


---

### getLocale()
- getLocale(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the locale sent from the user agent.

    **Returns:**
    - the locale sent from the user agent.


---

### getParameter(String)
- getParameter(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a specific parameter value from the stored query
      string. The method can be used to extract a source code or
      affiliate id out of the URLs in the click stream.
      
      The method returns null if there is no parameter with the given name.


    **Parameters:**
    - name - the name of the parameter.

    **Returns:**
    - the value associated with the specified parameter,
      or null.



---

### getPath()
- getPath(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the path.

    **Returns:**
    - the path.


---

### getPipelineName()
- getPipelineName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the called pipeline. In most cases the
      name can be derived from the path, but not in all cases. If with
      URL rewritting a special landing page is defined for a DNS name, than
      the system internally might use a specific pipeline associated with
      this landing page.


    **Returns:**
    - the name of the called pipeline.


---

### getQueryString()
- getQueryString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the query string.

    **Returns:**
    - the query string.


---

### getReferer()
- getReferer(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the referer.

    **Returns:**
    - the referer.


---

### getRemoteAddress()
- getRemoteAddress(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the remote address.

    **Returns:**
    - the remote address.


---

### getTimestamp()
- getTimestamp(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the entry's timestamp.

    **Returns:**
    - the entry's timestamp.


---

### getUrl()
- getUrl(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the full URL for this click. The URL is returned as relative
      URL.


    **Returns:**
    - the full URL for this click.


---

### getUserAgent()
- getUserAgent(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the user agent.

    **Returns:**
    - the user agent.


---

<!-- prettier-ignore-end -->

<!-- document id=0648aa8fca0525606db3f1be96c52a8fb7af581ec1f5b9515e5e8e92c0276a3e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.cms.CMSRecord.md -->

<!-- prettier-ignore-start -->
# Class CMSRecord

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.cms.CMSRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md)

This class represents a Salesforce CMS record, exposing its:

- `id`, see [getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#getid)
- `type`, see [getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype)
- `attributes`, see [getAttributes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#getattributes)

The `attributes` are key value pairs:

- the key being the attribute id as given in the `type.attribute_definitions`entries
- the value being a DWScript API object resolved from the raw attribute value based on the attribute type as given in the `type.attribute_definitions`entries          (similar to how [ComponentScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent)exposes the raw attribute value of a [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring)in shape of a DWScript API object based on the attribute type)



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the id of the Salesforce CMS record. |
| [attributes](#attributes): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Return the Salesforce CMS record attributes as key value pairs:  <ul>      <li>the key being the attribute id as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions` entries</li>      <li>the value being a DWScript API object resolved from the raw attribute value based on the attribute type as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions` entries          (similar to how [ComponentScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent) exposes the raw attribute value of a [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring) in shape of a DWScript API object based on the attribute type)</li>  </ul>   The attributes are also conveniently accessible through named property support. |
| [type](#type): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Return the type of the Salesforce CMS record sufficing the `content/schema/cmsrecord.json#/definitions/cms_content_type` schema. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#getattributes)() | Return the Salesforce CMS record attributes as key value pairs:  <ul>      <li>the key being the attribute id as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions` entries</li>      <li>the value being a DWScript API object resolved from the raw attribute value based on the attribute type as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions` entries          (similar to how [ComponentScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent) exposes the raw attribute value of a [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring) in shape of a DWScript API object based on the attribute type)</li>  </ul>   The attributes are also conveniently accessible through named property support. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#getid)() | Return the id of the Salesforce CMS record. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype)() | Return the type of the Salesforce CMS record sufficing the `content/schema/cmsrecord.json#/definitions/cms_content_type` schema. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the id of the Salesforce CMS record.


---

### attributes
- attributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Return the Salesforce CMS record attributes as key value pairs:
      
      - the key being the attribute id as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions`entries
      - the value being a DWScript API object resolved from the raw attribute value based on the attribute type as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions`entries          (similar to how [ComponentScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent)exposes the raw attribute value of a [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring)in shape of a DWScript API object based on the attribute type)
      
      
      The attributes are also conveniently accessible through named property support. That means if `myCmsRecord.getAttributes().get('foo')` yields value `'bar'`,
      then `myCmsRecord.foo` will give the same results.



---

### type
- type: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Return the type of the Salesforce CMS record sufficing the `content/schema/cmsrecord.json#/definitions/cms_content_type` schema. Properties
      can be accessed accordingly:
      
      - `getType().id : string`
      - `getType().name : string`
      - `getType().attribute_definitions : Map`(see `content/schema/attributedefinition.json`)



---

## Method Details

### getAttributes()
- getAttributes(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Return the Salesforce CMS record attributes as key value pairs:
      
      - the key being the attribute id as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions`entries
      - the value being a DWScript API object resolved from the raw attribute value based on the attribute type as given in the `[getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype).attribute_definitions`entries          (similar to how [ComponentScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent)exposes the raw attribute value of a [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring)in shape of a DWScript API object based on the attribute type)
      
      
      The attributes are also conveniently accessible through named property support. That means if `myCmsRecord.getAttributes().get('foo')` yields value `'bar'`,
      then `myCmsRecord.foo` will give the same results.


    **Returns:**
    - the cms record attributes


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the id of the Salesforce CMS record.

    **Returns:**
    - the id of the Salesforce CMS record


---

### getType()
- getType(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Return the type of the Salesforce CMS record sufficing the `content/schema/cmsrecord.json#/definitions/cms_content_type` schema. Properties
      can be accessed accordingly:
      
      - `getType().id : string`
      - `getType().name : string`
      - `getType().attribute_definitions : Map`(see `content/schema/attributedefinition.json`)


    **Returns:**
    - the type of the cms record


---

<!-- prettier-ignore-end -->

<!-- document id=acb7dd79b447119766d92ae025d28e97fc1b0b31c94cdc1d4817522e6ba35389 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Collection.md -->

<!-- prettier-ignore-start -->
# Class Collection

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)

Represents a collection of objects.


## All Known Subclasses
[ArrayList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.ArrayList.md), [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md), [HashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashSet.md), [LinkedHashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashSet.md), [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md), [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md), [SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)
## Property Summary

| Property | Description |
| --- | --- |
| [empty](#empty): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the collection is empty. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the length of the collection. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds the specified objects to the collection. |
| [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method adds a single object to the collection. |
| [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Adds the collection of objects to the collection. |
| [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear)() | Clears the collection. |
| [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if the collection contains the specified object. |
| [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Returns true if the collection contains all of the objects  in the specified collection. |
| [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength)() | Returns the length of the collection. |
| [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty)() | Returns true if the collection is empty. |
| [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator)() | Returns an iterator that can be used to access  the members of the collection. |
| [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Removes the specified object from the collection. |
| [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Removes all of object in the specified object from the collection. |
| [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Removes all of object in the collection that are not in the  specified collection. |
| [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size)() | Returns the size of the collection. |
| [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray)() | Returns all elements of this collection in a newly created array. |
| [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a subset of the elements of this collection in a newly created array. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### empty
- empty: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the collection is empty.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the length of the collection. This is similar to
      to a ECMA array of 'products.length'.



---

## Method Details

### add(Object...)
- add(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Adds the specified objects to the collection. The method can also
      be called with an ECMA array as argument.
      
      If called with a single ECMA array as argument the individual elements of
      that array are added to the collection. If the array object itself should
      be added use the method add1().


    **Parameters:**
    - values - the values to add.

    **Returns:**
    - true if the values were added, false otherwise.


---

### add1(Object)
- add1(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method adds a single object to the collection.

    **Parameters:**
    - object - the object to add.

    **Returns:**
    - true if the object was added, false otherwise.


---

### addAll(Collection)
- addAll(objs: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Adds the collection of objects to the collection.

    **Parameters:**
    - objs - the objects to add.

    **Returns:**
    - true if the objects were added, false otherwise.


---

### clear()
- clear(): void
  - : Clears the collection.


---

### contains(Object)
- contains(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the collection contains the specified object.

    **Parameters:**
    - obj - the object to locate in this collection.

    **Returns:**
    - true if the collection contains the specified object,
      false otherwise.



---

### containsAll(Collection)
- containsAll(objs: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the collection contains all of the objects
      in the specified collection.


    **Parameters:**
    - objs - the collection of objects to locate in this collection.

    **Returns:**
    - true if the collection contains all of the specified objects,
      false otherwise.



---

### getLength()
- getLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the length of the collection. This is similar to
      to a ECMA array of 'products.length'.


    **Returns:**
    - the length of the collection.


---

### isEmpty()
- isEmpty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the collection is empty.

    **Returns:**
    - true if the collection is empty, false otherwise


---

### iterator()
- iterator(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Returns an iterator that can be used to access
      the members of the collection.


    **Returns:**
    - an iterator that can be used to access
      the members of the collection.



---

### remove(Object)
- remove(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Removes the specified object from the collection.

    **Parameters:**
    - obj - the object to remove.

    **Returns:**
    - true if the specified object was removed,
      false otherwise.



---

### removeAll(Collection)
- removeAll(objs: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Removes all of object in the specified object from the collection.

    **Parameters:**
    - objs - the collection of objects to remove.

    **Returns:**
    - true if the all of the specified objects were removed,
      false otherwise.



---

### retainAll(Collection)
- retainAll(objs: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Removes all of object in the collection that are not in the
      specified collection.


    **Parameters:**
    - objs - the collection of objects to retain in the collection.

    **Returns:**
    - true if the collection retains all of the specified objects,
      false otherwise.



---

### size()
- size(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the collection.

    **Returns:**
    - the size of the collection.


---

### toArray()
- toArray(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns all elements of this collection in a newly created array. The returned array is independent of this collection and
      can be modified without changing the collection. The elements in the array are in the same order as they are returned when
      iterating over this collection.


    **Returns:**
    - a newly created array.


---

### toArray(Number, Number)
- toArray(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns a subset of the elements of this collection in a newly created array. The returned array is independent of this collection and
      can be modified without changing the collection. The elements in the array are in the same order as they are returned when
      iterating over this collection.


    **Parameters:**
    - start - the number of elements to iterate before adding elements to             the array. Negative values are treated as 0.
    - size - the maximum number of elements to add to the array.             Nonpositive values always result in empty array.

    **Returns:**
    - a newly created array.


---

<!-- prettier-ignore-end -->

<!-- document id=4bcb2c42abbe7130dd7426e2d0b0f758dccddb0850e502e7bc4f1e2251e47189 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.Component.md -->

<!-- prettier-ignore-start -->
# Class Component

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)

This class represents a page designer managed component as part of a
page. A component comprises of multiple regions that again hold components,
thus spanning a hierarchical tree of components. Using the [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or
[PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings) a region can be rendered which
implicitly includes rendering of all contained visible components. All
content attributes (defined by the corresponding component type) can be
accessed, reading the accordant persisted values as provided by the content editor
who created this component.


**See Also:**
- [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
- [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)
- [PageMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md)


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the id of this component. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of this component |
| [typeID](#typeid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type id of this component. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>Returns the raw attribute value identified by the specified attribute id. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getid)() | Returns the id of this component. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getname)() | Returns the name of this component |
| [getRegion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getregionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the component region that matches the given id. |
| [getTypeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#gettypeid)() | Returns the type id of this component. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the id of this component.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of this component


---

### typeID
- typeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type id of this component.


---

## Method Details

### getAttribute(String)
- getAttribute(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : 
      Returns the raw attribute value identified by the specified attribute id.
      By raw attribute value we denote the unprocessed value as provided for the attribute
      driven by the type of the respective attribute definition:
      
      - `boolean`-> boolean
      - `category`-> string representing a catalog category ID
      - `custom`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)that originates from a stringified curly brackets {} JSON object
      - `cms_record`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)that originates from a stringified curly brackets {} JSON object whose entries must adhere to the `cmsrecord.json`schema
      - `enum`-> either string or integer
      - `file`-> string representing a file path within a library
      - `image`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)that originates from a stringified curly brackets {} JSON object whose entries must adhere to the `content/schema/image.json`schema
      - `integer`-> integer
      - `markup`-> string representing HTML markup
      - `page`-> string representing a page ID
      - `product`-> string representing a product SKU
      - `string`-> string
      - `text`-> string
      - `url`-> string representing a URL
      
      
      
      
      
      There is two places an attribute value can come from - either it was persisted at design time (e.g.
      by the merchant by editing a component in Page Designer) or it was injected in shape of an aspect attribute at rendering time
      through the execution of code. The persistent value, if existing, takes precedence over the injected aspect
      attribute one. Injection of a value through an aspect attribute will only occur if the component attribute's
      attribute definition was declared using the `"dynamic_lookup"` property and its aspect attribute alias matches
      the ID of the respective aspect attribute.
      
      
      
      Accessing the raw value can be helpful if render and serialization logic of the
      component needs to operate on these unprocessed values. An unprocessed value
      might be fundamentally different from its processed counterpart, the latter being
      provided through the content dictionary (see [ComponentScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent))
      when the render/serialize function of the component is invoked.


    **Parameters:**
    - attributeID - the id of the desired attribute

    **Returns:**
    - the unprocessed raw value of the desired attribute, or null if not found


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the id of this component.

    **Returns:**
    - the component id


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of this component

    **Returns:**
    - the component name


---

### getRegion(String)
- getRegion(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)
  - : Returns the component region that matches the given id.

    **Parameters:**
    - id - the id of the desired component region

    **Returns:**
    - the region, or null if not found.


---

### getTypeID()
- getTypeID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type id of this component.

    **Returns:**
    - the component type id


---

<!-- prettier-ignore-end -->

<!-- document id=3fc92fd695805a6df4cfc9d51a007dce65830e3e6c169b5bbdbc53ded79bb06c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.ComponentRenderSettings.md -->

<!-- prettier-ignore-start -->
# Class ComponentRenderSettings

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)

A config that drives how the component is rendered. One can basically decide which kind of tag is used as wrapper
element (e.g. `<div>...</div>`) and which attributes are to be placed into this wrapper
element (e.g. `class="foo bar"`). In case no attributes are provided then the system default settings will
apply. In case no tag name is provided then the system default one will apply.

- tag\_name : div
- attributes : {"class":"experience-component experience-\[COMPONENT\_TYPE\_ID\]"}

As the \[COMPONENT\_TYPE\_ID\] can contain dots due to its package like naming scheme (e.g. assets.image)
any occurrences of these dots will be replaced by dashes (e.g. assets-image) so that CSS selectors
do not have to be escaped.


**See Also:**
- [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)


## Property Summary

| Property | Description |
| --- | --- |
| [attributes](#attributes): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#setattributesobject). |
| [tagName](#tagname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the tag name of the component wrapper element. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ComponentRenderSettings](#componentrendersettings)() | Creates region render settings which can then be configured further. |

## Method Summary

| Method | Description |
| --- | --- |
| [getAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#getattributes)() | Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#setattributesobject). |
| [getTagName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#gettagname)() | Returns the tag name of the component wrapper element. |
| [setAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#setattributesobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the to be configured <String,String> attributes of the wrapper element. |
| [setTagName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#settagnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the tag name of the component wrapper element. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### attributes
- attributes: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#setattributesobject).


---

### tagName
- tagName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tag name of the component wrapper element. Defaults to 'div'.


---

## Constructor Details

### ComponentRenderSettings()
- ComponentRenderSettings()
  - : Creates region render settings which can then be configured further. They are to be used for detailed
      configuration of a [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md) which is subsequently used for
      [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings) calls.


    **See Also:**
    - [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)


---

## Method Details

### getAttributes()
- getAttributes(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md#setattributesobject).

    **Returns:**
    - the configured attributes of the wrapper element


---

### getTagName()
- getTagName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tag name of the component wrapper element. Defaults to 'div'.

    **Returns:**
    - the tag name of the component wrapper element


---

### setAttributes(Object)
- setAttributes(attributes: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)
  - : Sets the to be configured <String,String> attributes of the wrapper element. Set it to `null` in case
      you want to system defaults to be applied.


    **Parameters:**
    - attributes - the to be configured attributes of the wrapper element

    **Returns:**
    - this


---

### setTagName(String)
- setTagName(tagName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)
  - : Sets the tag name of the component wrapper element. Must not be empty.

    **Parameters:**
    - tagName - the tag name of the component wrapper element

    **Returns:**
    - this


---

<!-- prettier-ignore-end -->

<!-- document id=b489f21b62eb52acec5727bbd3925b709a17f81d7ae412dcf0a44284bc449c44 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.ComponentScriptContext.md -->

<!-- prettier-ignore-start -->
# Class ComponentScriptContext

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.ComponentScriptContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md)

This is the context that is handed over to the `render` and `serialize` function of the respective component type
script.

```
    String : render( [ComponentScriptContext](dw.experience.ComponentScriptContext.md) context)
    Object : serialize( [ComponentScriptContext](dw.experience.ComponentScriptContext.md) context)
```



## Property Summary

| Property | Description |
| --- | --- |
| [component](#component): [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md) `(read-only)` | Returns the component for which the corresponding component type script is currently executed. |
| [componentRenderSettings](#componentrendersettings): [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md) `(read-only)` | As components are implicitly rendered as part of their hosting region via  [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings) there is the possibility  to define render settings for the region itself but also for its contained components. |
| [content](#content): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the processed version of the underlying unprocessed raw values (also see [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring))  of this component's attributes which you can use in your respective component type `render` and `serialize` function  implementing your business and rendering/serialization functionality. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getComponent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcomponent)() | Returns the component for which the corresponding component type script is currently executed. |
| [getComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcomponentrendersettings)() | As components are implicitly rendered as part of their hosting region via  [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings) there is the possibility  to define render settings for the region itself but also for its contained components. |
| [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent)() | Returns the processed version of the underlying unprocessed raw values (also see [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring))  of this component's attributes which you can use in your respective component type `render` and `serialize` function  implementing your business and rendering/serialization functionality. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### component
- component: [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md) `(read-only)`
  - : Returns the component for which the corresponding component type script is currently executed.


---

### componentRenderSettings
- componentRenderSettings: [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md) `(read-only)`
  - : As components are implicitly rendered as part of their hosting region via
      [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings) there is the possibility
      to define render settings for the region itself but also for its contained components.
      The latter will be provided here so you further set or refine them for your component
      as part of the `render` function, i.e. to drive the shape of the
      component wrapper element.



---

### content
- content: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the processed version of the underlying unprocessed raw values (also see [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring))
      of this component's attributes which you can use in your respective component type `render` and `serialize` function
      implementing your business and rendering/serialization functionality. Processing the raw value is comprised of **expansion**
      and **conversion**, in this order.
      
      1. **expansion**- dynamic placeholders are transformed into actual values, for example url/link placeholders in       markup text are resolved to real URLs
      2. **conversion**- the raw value (see [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring)) is resolved into an actual       DWScript object depending on the type of the attribute as specified in its respective attribute definition        
         - `boolean`-> boolean
         - `category`-> [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
         - `custom`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
         - `cms_record`-> [CMSRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md)
         - `enum`-> either string or integer 
         - `file`-> [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
         - `image`-> [Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)
         - `integer`-> integer
         - `markup`-> string
         - `page`-> string
         - `product`-> [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
         - `string`-> string
         - `text`-> string
         - `url`-> string



---

## Method Details

### getComponent()
- getComponent(): [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)
  - : Returns the component for which the corresponding component type script is currently executed.

    **Returns:**
    - the currently rendered component


---

### getComponentRenderSettings()
- getComponentRenderSettings(): [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)
  - : As components are implicitly rendered as part of their hosting region via
      [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings) there is the possibility
      to define render settings for the region itself but also for its contained components.
      The latter will be provided here so you further set or refine them for your component
      as part of the `render` function, i.e. to drive the shape of the
      component wrapper element.


    **Returns:**
    - the component render settings


---

### getContent()
- getContent(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the processed version of the underlying unprocessed raw values (also see [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring))
      of this component's attributes which you can use in your respective component type `render` and `serialize` function
      implementing your business and rendering/serialization functionality. Processing the raw value is comprised of **expansion**
      and **conversion**, in this order.
      
      1. **expansion**- dynamic placeholders are transformed into actual values, for example url/link placeholders in       markup text are resolved to real URLs
      2. **conversion**- the raw value (see [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring)) is resolved into an actual       DWScript object depending on the type of the attribute as specified in its respective attribute definition        
         - `boolean`-> boolean
         - `category`-> [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
         - `custom`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
         - `cms_record`-> [CMSRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md)
         - `enum`-> either string or integer 
         - `file`-> [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
         - `image`-> [Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)
         - `integer`-> integer
         - `markup`-> string
         - `page`-> string
         - `product`-> [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
         - `string`-> string
         - `text`-> string
         - `url`-> string


    **Returns:**
    - processed content attributes of the component


---

<!-- prettier-ignore-end -->

<!-- document id=29c26aeba375c3b7df9532017a2b5cb5e4dc9e6a7bd016297ffc780ab6ce2941 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.commerceapps.hooks.ConnectionHealthCheckHooks.md -->

<!-- prettier-ignore-start -->
# Class ConnectionHealthCheckHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.commerceapps.hooks.ConnectionHealthCheckHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.hooks.ConnectionHealthCheckHooks.md)

This interface represents the optional connection health check extension point for Commerce App providers. It lets a
Commerce App report whether its external service is reachable and operating correctly so Business Manager can surface
health on the app's installation details. Implementing this hook is not required &mdash; apps that do not depend on
an external connection may omit it entirely. When omitted, Business Manager does not display health status on the
app's tile.


A function must be defined inside a JavaScript source and must be exported. The script with the exported hook
function must be located inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks'
entry must exist.


```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:


```
"hooks": [
     {"name": "sfcc.app.tax.checkConnectionHealth", "script": "./checkConnectionHealth.js"}
]
```


A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



The hook is registered **per app domain** using the `sfcc.app.<domain>.checkConnectionHealth`
convention &mdash; for example, `sfcc.app.tax.checkConnectionHealth` for a tax app.


**IMPORTANT:** This hook should only be implemented and registered by Commerce Apps (applications
installed via the Commerce App framework with a CAP file). It is not intended for custom merchant cartridges or
storefront implementations.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [checkConnectionHealth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.hooks.ConnectionHealthCheckHooks.md#checkconnectionhealth)() | Reports the current health of the Commerce App's connection to its external service. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### checkConnectionHealth()
- checkConnectionHealth(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Reports the current health of the Commerce App's connection to its external service. The platform applies a CPU
      timeout, so implementations should be lightweight and time-bounded.
      
      
      The Business Manager connection-health endpoint that invokes this hook reports `unknown` when the hook
      times out, throws, or returns `null`. `dw.system.HookMgr#callHook` itself rethrows any exception
      raised by the hook script &mdash; the `unknown` translation is applied by the BM endpoint dispatcher, not
      by `HookMgr`.
      
      
      The BM endpoint interprets the returned [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) as follows: `Status.OK` &rarr; healthy;
      `Status.ERROR` with code [DEGRADED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.ConnectionHealthStatusCodes.md#status_code_degraded)
      &rarr; degraded; `Status.ERROR` with code
      [UNHEALTHY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.ConnectionHealthStatusCodes.md#status_code_unhealthy) (or any other ERROR code)
      &rarr; unhealthy. A `null` return is treated as `unknown`.
      
      
      Use [Status.addDetail(String, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#adddetailstring-object) with keys
      [ConnectionHealthStatusCodes.DETAIL_MESSAGE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.ConnectionHealthStatusCodes.md#detail_message) and
      [ConnectionHealthStatusCodes.DETAIL_REMEDIATION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.ConnectionHealthStatusCodes.md#detail_remediation) to provide structured information for the
      BM UI. [DETAIL\_REMEDIATION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.ConnectionHealthStatusCodes.md#detail_remediation) should describe
      actionable steps the merchant can take when the connection is degraded or unhealthy.
      
      
      Both detail values are surfaced verbatim in Business Manager. To localize them for the BM admin's language, look
      up the strings via `dw.web.Resource` from the cartridge's resource bundles (e.g. files under
      `cartridge/templates/resources/`) instead of hard-coding English. The BM endpoint dispatcher invokes the
      hook in the BM session locale, so `Resource.msg(...)` resolves against the admin's language.
      
      
      ```
      var Resource = require('dw/web/Resource');
      var Status = require('dw/system/Status');
      
      exports.checkConnectionHealth = function () {
          var status = new Status(Status.ERROR, 'DEGRADED');
          status.addDetail('message', Resource.msg('healthcheck.degraded.message', 'taxapp', null));
          status.addDetail('remediation',
              Resource.msgf('healthcheck.degraded.remediation', 'taxapp', null, providerName));
          return status;
      };
      ```


    **Returns:**
    - the connection health status. A `null` return is treated as `unknown` by the BM endpoint.


---

<!-- prettier-ignore-end -->

<!-- document id=9fa1a5dfcc1cee335510d25902f650183937e6ff79a72efe2b054cf7ce282ab0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.commerceapps.ConnectionHealthStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class ConnectionHealthStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.commerceapps.ConnectionHealthStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.ConnectionHealthStatusCodes.md)

Status codes and detail keys returned by the
[ConnectionHealthCheckHooks.checkConnectionHealth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.hooks.ConnectionHealthCheckHooks.md#checkconnectionhealth) hook. The BM connection-health
endpoint translates the returned [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) into a health payload using these values.


**See Also:**
- [ConnectionHealthCheckHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.hooks.ConnectionHealthCheckHooks.md)


## Constant Summary

| Constant | Description |
| --- | --- |
| [DETAIL_MESSAGE](#detail_message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "message" | [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) detail key for the human-readable status message. |
| [DETAIL_REMEDIATION](#detail_remediation): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "remediation" | [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) detail key for the merchant-facing remediation hint. |
| [STATUS_CODE_DEGRADED](#status_code_degraded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DEGRADED" | Status code that indicates a degraded connection (partial functionality available). |
| [STATUS_CODE_UNHEALTHY](#status_code_unhealthy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UNHEALTHY" | Status code that indicates the connection is unhealthy. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ConnectionHealthStatusCodes](#connectionhealthstatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DETAIL_MESSAGE

- DETAIL_MESSAGE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "message"
  - : [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) detail key for the human-readable status message.


---

### DETAIL_REMEDIATION

- DETAIL_REMEDIATION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "remediation"
  - : [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) detail key for the merchant-facing remediation hint.


---

### STATUS_CODE_DEGRADED

- STATUS_CODE_DEGRADED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DEGRADED"
  - : Status code that indicates a degraded connection (partial functionality available).


---

### STATUS_CODE_UNHEALTHY

- STATUS_CODE_UNHEALTHY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UNHEALTHY"
  - : Status code that indicates the connection is unhealthy.


---

## Constructor Details

### ConnectionHealthStatusCodes()
- ConnectionHealthStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=caafe6f190687307c15f9407979e62a2d40fc3874da5650f877130ae7f1e7c1c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.consent.ConsentStatusEntry.md -->

<!-- prettier-ignore-start -->
# Class ConsentStatusEntry

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.consent.ConsentStatusEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ConsentStatusEntry.md)

Represents the consent status for a specific channel and contact point.


This class provides information about the shopper's consent status (OPT\_IN, OPT\_OUT)
for a particular marketing communication channel.



## Property Summary

| Property | Description |
| --- | --- |
| [channel](#channel): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the channel type for this consent status entry. |
| [contactPointValue](#contactpointvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the contact point value (email address or phone number) for this consent entry. |
| [status](#status): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the consent status. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getChannel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ConsentStatusEntry.md#getchannel)() | Returns the channel type for this consent status entry. |
| [getContactPointValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ConsentStatusEntry.md#getcontactpointvalue)() | Returns the contact point value (email address or phone number) for this consent entry. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ConsentStatusEntry.md#getstatus)() | Returns the consent status. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### channel
- channel: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the channel type for this consent status entry.


---

### contactPointValue
- contactPointValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the contact point value (email address or phone number) for this consent entry.


---

### status
- status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the consent status.


---

## Method Details

### getChannel()
- getChannel(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the channel type for this consent status entry.

    **Returns:**
    - The channel type (e.g., "EMAIL", "SMS", "WHATSAPP").


---

### getContactPointValue()
- getContactPointValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the contact point value (email address or phone number) for this consent entry.

    **Returns:**
    - The contact point value.


---

### getStatus()
- getStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the consent status.

    **Returns:**
    - The consent status (e.g., "OPT\_IN", "OPT\_OUT").


---

<!-- prettier-ignore-end -->

<!-- document id=9417f8ea716cf7299e64ebfe0d103e3a2298f3bf648e2e6cb1099f0d1d57f510 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.Content.md -->

<!-- prettier-ignore-start -->
# Class Content

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.content.Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md)

Class representing a Content asset in Commerce Cloud Digital.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the content asset. |
| [classificationFolder](#classificationfolder): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)` | Returns the Folder associated with this Content. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description in the current locale or null. |
| [folders](#folders): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all folders to which this content is assigned. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the content asset. |
| [online](#online): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status of the content. |
| [onlineFlag](#onlineflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status flag of the content. |
| [page](#page): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns if the content is a [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) or not. |
| [pageDescription](#pagedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page description for the content in the current locale  or null if there is no page description. |
| [pageKeywords](#pagekeywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page keywords for the content in the current locale  or null if there is no page title. |
| [pageMetaTags](#pagemetatags): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)` | Returns all page meta tags, defined for this instance for which content can be generated. |
| [pageTitle](#pagetitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page title for the content in the current locale  or null if there is no page title. |
| [pageURL](#pageurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page URL for the content in the current locale  or null if there is no page URL. |
| [searchable](#searchable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the search status of the content. |
| [searchableFlag](#searchableflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status flag of the content. |
| [siteMapChangeFrequency](#sitemapchangefrequency): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the contents change frequency needed for the sitemap creation. |
| [siteMapIncluded](#sitemapincluded): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the status if the content is included into the sitemap. |
| [siteMapPriority](#sitemappriority): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the contents priority needed for the sitemap creation. |
| [template](#template): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value of attribute 'template'. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getClassificationFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getclassificationfolder)() | Returns the Folder associated with this Content. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getdescription)() | Returns the description in the current locale or null. |
| [getFolders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getfolders)() | Returns all folders to which this content is assigned. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getid)() | Returns the ID of the content asset. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getname)() | Returns the name of the content asset. |
| [getOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getonlineflag)() | Returns the online status flag of the content. |
| [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getpagedescription)() | Returns the page description for the content in the current locale  or null if there is no page description. |
| [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getpagekeywords)() | Returns the page keywords for the content in the current locale  or null if there is no page title. |
| [getPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getpagemetatagstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the page meta tag for the specified id. |
| [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getpagemetatags)() | Returns all page meta tags, defined for this instance for which content can be generated. |
| [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getpagetitle)() | Returns the page title for the content in the current locale  or null if there is no page title. |
| [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getpageurl)() | Returns the page URL for the content in the current locale  or null if there is no page URL. |
| [getSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getsearchableflag)() | Returns the online status flag of the content. |
| [getSiteMapChangeFrequency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getsitemapchangefrequency)() | Returns the contents change frequency needed for the sitemap creation. |
| [getSiteMapIncluded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getsitemapincluded)() | Returns the status if the content is included into the sitemap. |
| [getSiteMapPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#getsitemappriority)() | Returns the contents priority needed for the sitemap creation. |
| [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#gettemplate)() | Returns the value of attribute 'template'. |
| [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#isonline)() | Returns the online status of the content. |
| [isPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#ispage)() | Returns if the content is a [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) or not. |
| [isSearchable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#issearchable)() | Returns the search status of the content. |
| [toPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#topage)() | Converts the content into the [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) representation if [isPage()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#ispage) yields true. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the content asset.


---

### classificationFolder
- classificationFolder: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)`
  - : Returns the Folder associated with this Content. The folder is
      used to determine the classification of the content.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description in the current locale or null.


---

### folders
- folders: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all folders to which this content is assigned.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the content asset.


---

### online
- online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status of the content.


---

### onlineFlag
- onlineFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status flag of the content.


---

### page
- page: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns if the content is a [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) or not.


---

### pageDescription
- pageDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page description for the content in the current locale
      or null if there is no page description.



---

### pageKeywords
- pageKeywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page keywords for the content in the current locale
      or null if there is no page title.



---

### pageMetaTags
- pageMetaTags: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)`
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the content detail page meta tag context and rules.
      The rules are obtained from the current content or inherited from the default folder,
      up to the root folder.



---

### pageTitle
- pageTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page title for the content in the current locale
      or null if there is no page title.



---

### pageURL
- pageURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page URL for the content in the current locale
      or null if there is no page URL.



---

### searchable
- searchable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the search status of the content.


---

### searchableFlag
- searchableFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status flag of the content.


---

### siteMapChangeFrequency
- siteMapChangeFrequency: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the contents change frequency needed for the sitemap creation.


---

### siteMapIncluded
- siteMapIncluded: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the status if the content is included into the sitemap.


---

### siteMapPriority
- siteMapPriority: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the contents priority needed for the sitemap creation.
      If no priority is defined, the method returns 0.0.



---

### template
- template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value of attribute 'template'.


---

## Method Details

### getClassificationFolder()
- getClassificationFolder(): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the Folder associated with this Content. The folder is
      used to determine the classification of the content.


    **Returns:**
    - the classification Folder.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description in the current locale or null.

    **Returns:**
    - the description in the current locale or null.


---

### getFolders()
- getFolders(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all folders to which this content is assigned.

    **Returns:**
    - Collection of Folder objects.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the content asset.

    **Returns:**
    - the ID of the content asset.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the content asset.

    **Returns:**
    - the name of the content asset.


---

### getOnlineFlag()
- getOnlineFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status flag of the content.

    **Returns:**
    - true if the content is online, false otherwise.


---

### getPageDescription()
- getPageDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page description for the content in the current locale
      or null if there is no page description.


    **Returns:**
    - the page description for the content in the current locale
      or null if there is no page description.



---

### getPageKeywords()
- getPageKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page keywords for the content in the current locale
      or null if there is no page title.


    **Returns:**
    - the page keywords for the content in the current locale
      or null if there is no page title.



---

### getPageMetaTag(String)
- getPageMetaTag(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)
  - : Returns the page meta tag for the specified id.
      
      
      The meta tag content is generated based on the content detail page meta tag context and rule.
      The rule is obtained from the current content or inherited from the default folder,
      up to the root folder.
      
      
      Null will be returned if the meta tag is undefined on the current instance, or if no rule can be found for the
      current context, or if the rule resolves to an empty string.


    **Parameters:**
    - id - the ID to get the page meta tag for

    **Returns:**
    - page meta tag containing content generated based on rules


---

### getPageMetaTags()
- getPageMetaTags(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the content detail page meta tag context and rules.
      The rules are obtained from the current content or inherited from the default folder,
      up to the root folder.


    **Returns:**
    - page meta tags defined for this instance, containing content generated based on rules


---

### getPageTitle()
- getPageTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page title for the content in the current locale
      or null if there is no page title.


    **Returns:**
    - the page title for the content in the current locale
      or null if there is no page title.



---

### getPageURL()
- getPageURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page URL for the content in the current locale
      or null if there is no page URL.


    **Returns:**
    - the page URL for the content in the current locale
      or null if there is no page URL.



---

### getSearchableFlag()
- getSearchableFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status flag of the content.

    **Returns:**
    - true if the content is searchable, false otherwise.


---

### getSiteMapChangeFrequency()
- getSiteMapChangeFrequency(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the contents change frequency needed for the sitemap creation.

    **Returns:**
    - The contents sitemap change frequency.


---

### getSiteMapIncluded()
- getSiteMapIncluded(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status if the content is included into the sitemap.

    **Returns:**
    - the value of the attribute 'siteMapIncluded'


---

### getSiteMapPriority()
- getSiteMapPriority(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the contents priority needed for the sitemap creation.
      If no priority is defined, the method returns 0.0.


    **Returns:**
    - The contents sitemap priority.


---

### getTemplate()
- getTemplate(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of attribute 'template'.

    **Returns:**
    - the value of the attribute 'template'


---

### isOnline()
- isOnline(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status of the content.

    **Returns:**
    - true if the content is online, false otherwise.


---

### isPage()
- isPage(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the content is a [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) or not.

    **Returns:**
    - true if the content is a [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md), false otherwise.


---

### isSearchable()
- isSearchable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the search status of the content.

    **Returns:**
    - true if the content is searchable, false otherwise.


---

### toPage()
- toPage(): [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
  - : Converts the content into the [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) representation if [isPage()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md#ispage) yields true.

    **Returns:**
    - the [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) representation of the content if it is a page, `null` otherwise.

    **See Also:**
    - [PageMgr.getPage(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagestring)


---

<!-- prettier-ignore-end -->

<!-- document id=816d44cbce99c9266f913745755a564b485a5a5a4842cdbd290ed64755437441 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.ContentMgr.md -->

<!-- prettier-ignore-start -->
# Class ContentMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.content.ContentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md)

Provides helper methods for getting content assets, library folders and the
content library of the current site.



## Constant Summary

| Constant | Description |
| --- | --- |
| [PRIVATE_LIBRARY](#private_library): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PrivateLibrary" | The input string to identify that the library is a private site library when invoking [getLibrary(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getlibrarystring). |

## Property Summary

| Property | Description |
| --- | --- |
| [siteLibrary](#sitelibrary): [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md) `(read-only)` | Returns the content library of the current site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getcontentlibrary-string)([Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the content with the corresponding identifier within the specified library. |
| static [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the content with the corresponding identifier within the current  site's site library. |
| static [getFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getfolderlibrary-string)([Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the folder identified by the specified id within the specified library. |
| static [getFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getfolderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the folder identified by the specified id within the current  site's site library. |
| static [getLibrary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getlibrarystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the content library specified by the given id. |
| static [getSiteLibrary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getsitelibrary)() | Returns the content library of the current site. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### PRIVATE_LIBRARY

- PRIVATE_LIBRARY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PrivateLibrary"
  - : The input string to identify that the library is a private site library when invoking [getLibrary(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getlibrarystring).


---

## Property Details

### siteLibrary
- siteLibrary: [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md) `(read-only)`
  - : Returns the content library of the current site.


---

## Method Details

### getContent(Library, String)
- static getContent(library: [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md), id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md)
  - : Returns the content with the corresponding identifier within the specified library.

    **Parameters:**
    - library - the content library to look for the content in
    - id - the ID of the content asset to find.

    **Returns:**
    - the content if found, or null if not found.


---

### getContent(String)
- static getContent(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md)
  - : Returns the content with the corresponding identifier within the current
      site's site library.


    **Parameters:**
    - id - the ID of the content asset to find.

    **Returns:**
    - the content if found, or null if not found.


---

### getFolder(Library, String)
- static getFolder(library: [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md), id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the folder identified by the specified id within the specified library.

    **Parameters:**
    - library - the content library to look for the folder in
    - id - the ID of the folder to find.

    **Returns:**
    - the folder, or null if not found.


---

### getFolder(String)
- static getFolder(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the folder identified by the specified id within the current
      site's site library.


    **Parameters:**
    - id - the ID of the folder to find.

    **Returns:**
    - the folder, or null if not found.


---

### getLibrary(String)
- static getLibrary(libraryId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md)
  - : Returns the content library specified by the given id. If [PRIVATE_LIBRARY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#private_library) is used, then the current
      site's private library will be returned.


    **Parameters:**
    - libraryId - the id of the library to return.

    **Returns:**
    - the library for the passed id. Returns null if there is no content library with that id.


---

### getSiteLibrary()
- static getSiteLibrary(): [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md)
  - : Returns the content library of the current site.

    **Returns:**
    - the content library of the current site, or null if there is not
              content library assigned to the current site.



---

<!-- prettier-ignore-end -->

<!-- document id=eca8d9be32257ec5ddb7957cc5af42279906a14fe2bbb1dc8f015459d8ed2951 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.ContentSearchModel.md -->

<!-- prettier-ignore-start -->
# Class ContentSearchModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md)
    - [dw.content.ContentSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md)

The class is the central interface to a content search result and a content
search refinement. It also provides utility methods to generate a search URL.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CONTENTID_PARAMETER](#contentid_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cid" | URL Parameter for the content ID |
| [FOLDERID_PARAMETER](#folderid_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "fdid" | URL Parameter for the folder ID |

## Property Summary

| Property | Description |
| --- | --- |
| [content](#content): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Returns an Iterator containing all Content Assets that are the result of the  search. |
| [contentID](#contentid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the content ID against which the search results apply. |
| [deepestCommonFolder](#deepestcommonfolder): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)` | Returns the deepest common folder of all content assets in the search result. |
| [filteredByFolder](#filteredbyfolder): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | The method returns true, if the content search result is filtered by the folder and it is not subsequently  possible to search for content assets that belong to no folder (e.g. |
| [folder](#folder): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)` | Returns the folder against which the search results apply. |
| [folderID](#folderid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the folder ID against which the search results apply. |
| [folderSearch](#foldersearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method returns true, if this is a pure search for a folder. |
| [pageMetaTags](#pagemetatags): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)` | Returns all page meta tags, defined for this instance for which content can be generated. |
| [recursiveFolderSearch](#recursivefoldersearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Get the flag that determines if the folder search will  be recursive. |
| [refinedByFolder](#refinedbyfolder): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method returns true, if the search is refined by a folder. |
| [refinedFolderSearch](#refinedfoldersearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is a folder search and is refined with further  criteria, like a name refinement or an attribute refinement. |
| [refinements](#refinements): [ContentSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md) `(read-only)` | Returns the set of search refinements used in this search. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ContentSearchModel](#contentsearchmodel)() | Constructs a new ContentSearchModel. |

## Method Summary

| Method | Description |
| --- | --- |
| [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getcontent)() | Returns an Iterator containing all Content Assets that are the result of the  search. |
| [getContentID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getcontentid)() | Returns the content ID against which the search results apply. |
| [getDeepestCommonFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getdeepestcommonfolder)() | Returns the deepest common folder of all content assets in the search result. |
| [getFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getfolder)() | Returns the folder against which the search results apply. |
| [getFolderID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getfolderid)() | Returns the folder ID against which the search results apply. |
| [getPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getpagemetatagstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the page meta tag for the specified id. |
| [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getpagemetatags)() | Returns all page meta tags, defined for this instance for which content can be generated. |
| [getRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#getrefinements)() | Returns the set of search refinements used in this search. |
| [isFilteredByFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#isfilteredbyfolder)() | The method returns true, if the content search result is filtered by the folder and it is not subsequently  possible to search for content assets that belong to no folder (e.g. |
| [isFolderSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#isfoldersearch)() | The method returns true, if this is a pure search for a folder. |
| [isRecursiveFolderSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#isrecursivefoldersearch)() | Get the flag that determines if the folder search will  be recursive. |
| [isRefinedByFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#isrefinedbyfolder)() | The method returns true, if the search is refined by a folder. |
| [isRefinedFolderSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#isrefinedfoldersearch)() | Identifies if this is a folder search and is refined with further  criteria, like a name refinement or an attribute refinement. |
| [search](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#search)() | Execute the search. |
| [setContentID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#setcontentidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the contentID used in this search. |
| [setFilteredByFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#setfilteredbyfolderboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set a flag to indicate if the search is filtered by the folder. |
| [setFolderID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#setfolderidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the folderID used in this search. |
| [setRecursiveFolderSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#setrecursivefoldersearchboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set a flag to indicate if the search in folder should be recursive. |
| static [urlForContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlforcontenturl-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to execute a query for a specific  Content. |
| static [urlForContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlforcontentstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to execute a query for a specific  Content. |
| static [urlForFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlforfolderurl-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to execute a query for a specific  Folder. |
| static [urlForFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlforfolderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to execute a query for a specific  Folder. |
| static [urlForRefine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlforrefineurl-string-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to execute a query for a specific  attribute name-value pair. |
| static [urlForRefine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlforrefinestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to execute a query for a specific  attribute name-value pair. |
| [urlRefineFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlrefinefolderurl-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to re-execute the query using the  specified URL and folder refinement. |
| [urlRefineFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlrefinefolderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to re-execute the query using the  specified pipeline action and folder refinement. |
| [urlRelaxFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlrelaxfolderurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Returns an URL that you can use to re-execute the query with no folder  refinement. |
| [urlRelaxFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md#urlrelaxfolderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URL that you can use to re-execute the query with no folder  refinement. |

### Methods inherited from class SearchModel

[addRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#addrefinementvaluesstring-string), [canRelax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#canrelax), [getCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getcount), [getRefinementMaxValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementmaxvaluestring), [getRefinementMinValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementminvaluestring), [getRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluestring), [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluesstring), [getSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsearchphrase), [getSearchRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsearchredirectstring), [getSortingCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsortingconditionstring), [isEmptyQuery](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isemptyquery), [isRefinedByAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattribute), [isRefinedByAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattributestring), [isRefinedByAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattributevaluestring-string), [isRefinedSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedsearch), [isRefinementByValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinementbyvaluerangestring), [isRefinementByValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinementbyvaluerangestring-string-string), [removeRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#removerefinementvaluesstring-string), [search](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#search), [setRefinementValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setrefinementvaluerangestring-string-string), [setRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setrefinementvaluesstring-string), [setSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setsearchphrasestring), [setSortingCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setsortingconditionstring-number), [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlurl), [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlstring), [urlDefaultSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urldefaultsorturl), [urlDefaultSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urldefaultsortstring), [urlRefineAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributeurl-string-string), [urlRefineAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributestring-string-string), [urlRefineAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevalueurl-string-string), [urlRefineAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevaluestring-string-string), [urlRefineAttributeValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevaluerangestring-string-string-string), [urlRelaxAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributeurl-string), [urlRelaxAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributestring-string), [urlRelaxAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributevalueurl-string-string), [urlRelaxAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributevaluestring-string-string), [urlSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlsorturl-string-number), [urlSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlsortstring-string-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CONTENTID_PARAMETER

- CONTENTID_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cid"
  - : URL Parameter for the content ID


---

### FOLDERID_PARAMETER

- FOLDERID_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "fdid"
  - : URL Parameter for the folder ID


---

## Property Details

### content
- content: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Returns an Iterator containing all Content Assets that are the result of the
      search.



---

### contentID
- contentID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the content ID against which the search results apply.


---

### deepestCommonFolder
- deepestCommonFolder: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)`
  - : Returns the deepest common folder of all content assets in the search result.


---

### filteredByFolder
- filteredByFolder: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if the content search result is filtered by the folder and it is not subsequently
      possible to search for content assets that belong to no folder (e.g. those for Page Designer).



---

### folder
- folder: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)`
  - : Returns the folder against which the search results apply.


---

### folderID
- folderID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the folder ID against which the search results apply.


---

### folderSearch
- folderSearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method returns true, if this is a pure search for a folder. The
      method checks, that a folder ID is specified and no search phrase is
      specified.



---

### pageMetaTags
- pageMetaTags: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)`
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the content listing page meta tag context and rules.
      The rules are obtained from the current folder context or inherited from the parent folder,
      up to the root folder.



---

### recursiveFolderSearch
- recursiveFolderSearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Get the flag that determines if the folder search will
      be recursive.



---

### refinedByFolder
- refinedByFolder: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method returns true, if the search is refined by a folder.
      The method checks, that a folder ID is specified.



---

### refinedFolderSearch
- refinedFolderSearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is a folder search and is refined with further
      criteria, like a name refinement or an attribute refinement.



---

### refinements
- refinements: [ContentSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md) `(read-only)`
  - : Returns the set of search refinements used in this search.


---

## Constructor Details

### ContentSearchModel()
- ContentSearchModel()
  - : Constructs a new ContentSearchModel.


---

## Method Details

### getContent()
- getContent(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Returns an Iterator containing all Content Assets that are the result of the
      search.


    **Returns:**
    - an Iterator containing all Content Assets that are the result of the
              search.



---

### getContentID()
- getContentID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the content ID against which the search results apply.

    **Returns:**
    - the content ID against which the search results apply.


---

### getDeepestCommonFolder()
- getDeepestCommonFolder(): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the deepest common folder of all content assets in the search result.

    **Returns:**
    - the deepest common folder of all content assets in the search result of this search model.


---

### getFolder()
- getFolder(): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the folder against which the search results apply.

    **Returns:**
    - the folder against which the search results apply.


---

### getFolderID()
- getFolderID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the folder ID against which the search results apply.

    **Returns:**
    - the folder ID against which the search results apply.


---

### getPageMetaTag(String)
- getPageMetaTag(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)
  - : Returns the page meta tag for the specified id.
      
      
      The meta tag content is generated based on the content listing page meta tag context and rule.
      The rule is obtained from the current folder context or inherited from the parent folder,
      up to the root folder.
      
      
      Null will be returned if the meta tag is undefined on the current instance, or if no rule can be found for the
      current context, or if the rule resolves to an empty string.


    **Parameters:**
    - id - the ID to get the page meta tag for

    **Returns:**
    - page meta tag containing content generated based on rules


---

### getPageMetaTags()
- getPageMetaTags(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the content listing page meta tag context and rules.
      The rules are obtained from the current folder context or inherited from the parent folder,
      up to the root folder.


    **Returns:**
    - page meta tags defined for this instance, containing content generated based on rules


---

### getRefinements()
- getRefinements(): [ContentSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md)
  - : Returns the set of search refinements used in this search.

    **Returns:**
    - the set of search refinements used in this search.


---

### isFilteredByFolder()
- isFilteredByFolder(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if the content search result is filtered by the folder and it is not subsequently
      possible to search for content assets that belong to no folder (e.g. those for Page Designer).


    **Returns:**
    - True if this is filtered by the folder of the content asset.


---

### isFolderSearch()
- isFolderSearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if this is a pure search for a folder. The
      method checks, that a folder ID is specified and no search phrase is
      specified.


    **Returns:**
    - True if this is a folder search.


---

### isRecursiveFolderSearch()
- isRecursiveFolderSearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Get the flag that determines if the folder search will
      be recursive.


    **Returns:**
    - true if the folder search will be recursive, false otherwise


---

### isRefinedByFolder()
- isRefinedByFolder(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if the search is refined by a folder.
      The method checks, that a folder ID is specified.


    **Returns:**
    - true, if the search is refined by a folder, false otherwise.


---

### isRefinedFolderSearch()
- isRefinedFolderSearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is a folder search and is refined with further
      criteria, like a name refinement or an attribute refinement.


    **Returns:**
    - true if this is a folder search and is refined with further
              criteria, false otherwise.



---

### search()
- search(): [SearchStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md)
  - : Execute the search.

    **Returns:**
    - the searchStatus object with search status code and description of search result.


---

### setContentID(String)
- setContentID(contentID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the contentID used in this search.

    **Parameters:**
    - contentID - the contentID used in this search.


---

### setFilteredByFolder(Boolean)
- setFilteredByFolder(filteredByFolder: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set a flag to indicate if the search is filtered by the folder. Must be set to false to return content assets that
      do not belong to any folder.


    **Parameters:**
    - filteredByFolder - filter the search result by folder


---

### setFolderID(String)
- setFolderID(folderID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the folderID used in this search.

    **Parameters:**
    - folderID - the folderID used in this search.


---

### setRecursiveFolderSearch(Boolean)
- setRecursiveFolderSearch(recurse: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set a flag to indicate if the search in folder should be recursive.

    **Parameters:**
    - recurse - recurse the folder in the search


---

### urlForContent(URL, String)
- static urlForContent(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), cid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to execute a query for a specific
      Content. The passed url can be either a full url or just the name for a
      pipeline. In the later case a relative URL is created.


    **Parameters:**
    - url - the URL to use when constructing the new URL.
    - cid - the content id.

    **Returns:**
    - an URL that you can use to execute a query for a specific
              Content. The passed url can be either a full url or just the name
              for a pipeline. In the later case a relative URL is created.



---

### urlForContent(String, String)
- static urlForContent(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), cid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to execute a query for a specific
      Content. The passed action is used to build an initial url. All search
      specific attributes are appended.


    **Parameters:**
    - action - the pipeline action to use.
    - cid - the content id.

    **Returns:**
    - an URL that you can use to execute a query for a specific
              Content. The passed action is used to build an initial url. All
              search specific attributes are appended.



---

### urlForFolder(URL, String)
- static urlForFolder(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), fid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to execute a query for a specific
      Folder.


    **Parameters:**
    - url - the URL to use in constructing the new URL.
    - fid - the id of the Folder to use.

    **Returns:**
    - an URL that you can use to execute a query for a specific
              Folder.



---

### urlForFolder(String, String)
- static urlForFolder(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), fid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to execute a query for a specific
      Folder.


    **Parameters:**
    - action - the pipeline action to use.
    - fid - the id of the Folder to use.

    **Returns:**
    - an URL that you can use to execute a query for a specific
              Folder.



---

### urlForRefine(URL, String, String)
- static urlForRefine(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to execute a query for a specific
      attribute name-value pair.


    **Parameters:**
    - url - the URL to use when constructing the new URL.
    - name - the name of the attribute.
    - value - the value for the attribute.

    **Returns:**
    - an URL that you can use to execute a query for a specific
              attribute name-value pair.



---

### urlForRefine(String, String, String)
- static urlForRefine(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to execute a query for a specific
      attribute name-value pair.


    **Parameters:**
    - action - the pipeline action to use.
    - name - the name of the attribute.
    - value - the value for the attribute.

    **Returns:**
    - an URL that you can use to execute a query for a specific
              attribute name-value pair.



---

### urlRefineFolder(URL, String)
- urlRefineFolder(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), refineFolderID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to re-execute the query using the
      specified URL and folder refinement.


    **Parameters:**
    - url - the existing URL to use when constructing the new URL.
    - refineFolderID - the ID of the folder refinement to use.

    **Returns:**
    - an URL that you can use to re-execute the query using the
              specified URL and folder refinement.



---

### urlRefineFolder(String, String)
- urlRefineFolder(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), refineFolderID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to re-execute the query using the
      specified pipeline action and folder refinement.


    **Parameters:**
    - action - the action to use.
    - refineFolderID - the folder ID to use as a refinement.

    **Returns:**
    - an URL that you can use to re-execute the exact same query using
              the specified pipeline action and folder refinement.



---

### urlRelaxFolder(URL)
- urlRelaxFolder(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to re-execute the query with no folder
      refinement.


    **Parameters:**
    - url - the existing URL to use when constructing the new URL.

    **Returns:**
    - an URL that you can use to re-execute the query with no folder
              refinement.



---

### urlRelaxFolder(String)
- urlRelaxFolder(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL that you can use to re-execute the query with no folder
      refinement.


    **Parameters:**
    - action - the pipeline action to use in the URL.

    **Returns:**
    - an URL that you can use to re-execute the query with no folder
              refinement.



---

<!-- prettier-ignore-end -->

<!-- document id=b2b6e8fe7b19f0ab485ff650b17f79237a1cfb5d6b92810bc0639b385f1fdcac url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.ContentSearchRefinementDefinition.md -->

<!-- prettier-ignore-start -->
# Class ContentSearchRefinementDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.SearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md)
        - [dw.content.ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md)

This class provides an interface to refinement options for content search.


## Property Summary

| Property | Description |
| --- | --- |
| [folderRefinement](#folderrefinement): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is a folder refinement. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [isFolderRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md#isfolderrefinement)() | Identifies if this is a folder refinement. |

### Methods inherited from class SearchRefinementDefinition

[getAttributeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getattributeid), [getCutoffThreshold](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getcutoffthreshold), [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getdisplayname), [getValueTypeCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getvaluetypecode), [isAttributeRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#isattributerefinement)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### folderRefinement
- folderRefinement: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is a folder refinement.


---

## Method Details

### isFolderRefinement()
- isFolderRefinement(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is a folder refinement.

    **Returns:**
    - true if this is a category refinement, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=7bfa066f12da0c326db0a4273689a944de279c248b16332d2b31069738894432 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.ContentSearchRefinements.md -->

<!-- prettier-ignore-start -->
# Class ContentSearchRefinements

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md)
    - [dw.content.ContentSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md)

This class provides an interface to refinement options for the content asset
search. In a typical usage, the client application UI displays the search
refinements along with the search results and allows customers to "refine"
the results (i.e. limit the results that are shown) by specifying additional
criteria, or "relax" (i.e. broaden) the results after previously refining.
The two types of content search refinements are:


- **Refine By Folder:**Limit the content assets to those assigned to  specific child/ancestor folder of the search folder.
- **Refine By Attribute:**Limit the content assets to those with  specific values for a given attribute. Values may be grouped into "buckets"  so that a given set of values are represented as a single refinement option.


Rendering a content search refinement UI typically begins with iterating the
refinement definitions for the search result. Call
[SearchRefinements.getRefinementDefinitions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementdefinitions) or
[SearchRefinements.getAllRefinementDefinitions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementdefinitions) to
retrieve the appropriate collection of refinement definitions. For each
definition, display the available refinement values by calling
[getAllRefinementValues(ContentSearchRefinementDefinition)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getallrefinementvaluescontentsearchrefinementdefinition). Depending
on the type of the refinement definition, the application must use slightly
different logic to display the refinement widgets. For all 2 types, methods
in [ContentSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md) are used to generate URLs to render
hyperlinks in the UI. When clicked, these links trigger a call to the Search
pipelet which in turn applies the appropriate filters to the native search
result.



## Property Summary

| Property | Description |
| --- | --- |
| [folderRefinementDefinition](#folderrefinementdefinition): [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md) `(read-only)` | Returns the appropriate folder refinement definition based on the search  result. |
| [matchingFolders](#matchingfolders): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of matching folders. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getallrefinementvaluescontentsearchrefinementdefinition)([ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md)) | Returns a sorted collection of refinement values for the given refinement  definition. |
| [getFolderHits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getfolderhitsfolder)([Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)) | Returns the number of search hits for the passed folder object. |
| [getFolderRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getfolderrefinementdefinition)() | Returns the appropriate folder refinement definition based on the search  result. |
| [getMatchingFolders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getmatchingfolders)() | Returns a collection of matching folders. |
| [getNextLevelFolderRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getnextlevelfolderrefinementvaluesfolder)([Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)) | Returns folder refinement values based on the current search result  filtered such that only folder refinements representing children of the  given folder are present. |
| [getRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getrefinementvaluecontentsearchrefinementdefinition-string)([ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the refinement value (incl. |
| [getRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getrefinementvaluestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the refinement value (incl. |
| [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md#getrefinementvaluescontentsearchrefinementdefinition)([ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md)) | Returns a collection of refinement values for the given refinement  definition. |

### Methods inherited from class SearchRefinements

[getAllRefinementDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementdefinitions), [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementvaluesstring), [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementvaluesstring-number-number), [getRefinementDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementdefinitions), [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementvaluesstring-number-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### folderRefinementDefinition
- folderRefinementDefinition: [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md) `(read-only)`
  - : Returns the appropriate folder refinement definition based on the search
      result. The folder refinement definition returned will be the first that
      can be found traversing the folder tree upward starting at the deepest
      common folder of the search result.



---

### matchingFolders
- matchingFolders: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of matching folders.


---

## Method Details

### getAllRefinementValues(ContentSearchRefinementDefinition)
- getAllRefinementValues(definition: [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of refinement values for the given refinement
      definition. The returned collection includes all refinement values for
      which the hit count is greater than 0 within the search result when the
      passed refinement definitions is excluded from filtering the search hits
      but all other refinement filters are still applied. This is useful for
      rendering broadening options for the refinement definitions that the
      search is already refined by. It is important to note that this method
      does NOT return refinement values independent of the search result.


    **Parameters:**
    - definition - The refinement definition to return refinement values             for.

    **Returns:**
    - The collection of ContentSearchRefinementValue instances sorted
              according to the settings of the definition.



---

### getFolderHits(Folder)
- getFolderHits(folder: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of search hits for the passed folder object.

    **Parameters:**
    - folder - Folder object.

    **Returns:**
    - Number of search hits.


---

### getFolderRefinementDefinition()
- getFolderRefinementDefinition(): [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md)
  - : Returns the appropriate folder refinement definition based on the search
      result. The folder refinement definition returned will be the first that
      can be found traversing the folder tree upward starting at the deepest
      common folder of the search result.


    **Returns:**
    - The folder refinement definition or `null` if none can
              be found.



---

### getMatchingFolders()
- getMatchingFolders(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of matching folders.

    **Returns:**
    - Collection of matching folders.


---

### getNextLevelFolderRefinementValues(Folder)
- getNextLevelFolderRefinementValues(folder: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns folder refinement values based on the current search result
      filtered such that only folder refinements representing children of the
      given folder are present. If no folder is given, the method uses the
      library's root folder. The refinement value content counts represent all
      hits contained in the library tree starting at the corresponding child
      folder.


    **Parameters:**
    - folder - The folder to return child folder refinement values for.

    **Returns:**
    - The refinement values for all child folders of the given folder.


---

### getRefinementValue(ContentSearchRefinementDefinition, String)
- getRefinementValue(definition: [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ContentSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementValue.md)
  - : Returns the refinement value (incl. content hit count) for the given
      refinement definition and the given (selected) value.


    **Parameters:**
    - definition - The definition to return the refinement for.
    - value - The value to return the refinement value for.

    **Returns:**
    - The refinement value.


---

### getRefinementValue(String, String)
- getRefinementValue(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ContentSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementValue.md)
  - : Returns the refinement value (incl. content hit count) for the given
      attribute refinement and the given (selected) value.


    **Parameters:**
    - name - The name of the refinement attribute.
    - value - The value to return the refinement value for.

    **Returns:**
    - The refinement value.


---

### getRefinementValues(ContentSearchRefinementDefinition)
- getRefinementValues(definition: [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of refinement values for the given refinement
      definition. The returned refinement values only include those that are
      part of the actual search result (i.e. hit count will always be > 0).


    **Parameters:**
    - definition - The refinement definition to return refinement values for.

    **Returns:**
    - The collection of refinement values sorted according to the
              settings of the definition.



---

<!-- prettier-ignore-end -->

<!-- document id=ca54872b4ab6118bb1b3aec5f1b6fc615dd156f99b2c5b9db4a54cce009617b4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.ContentSearchRefinementValue.md -->

<!-- prettier-ignore-start -->
# Class ContentSearchRefinementValue

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md)
    - [dw.content.ContentSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementValue.md)

Represents the value of a content search refinement.


## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class SearchRefinementValue

[getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getdescription), [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getdisplayvalue), [getHitCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#gethitcount), [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getid), [getPresentationID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getpresentationid), [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getvalue)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=c17960fb54561a4c5176bf07ccea109389b22db9a066aded20a1334812c644c4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.ContentSuggestions.md -->

<!-- prettier-ignore-start -->
# Class ContentSuggestions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md)
    - [dw.suggest.ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md)

The content suggestion container provides access to
content pages found using the suggested terms as search criteria.
The method [getSuggestedContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md#getsuggestedcontent) can be used to
get the list of found content pages.


Furthermore the list of suggested terms, after processing
the original user input search query, is accessible
through [SearchPhraseSuggestions.getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms) method.



## Property Summary

| Property | Description |
| --- | --- |
| [suggestedContent](#suggestedcontent): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | This method returns a list of content pages which were found  using the suggested terms as search criteria. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSuggestedContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md#getsuggestedcontent)() | This method returns a list of content pages which were found  using the suggested terms as search criteria. |

### Methods inherited from class Suggestions

[getSearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions), [getSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedphrases), [getSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms), [hasSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases), [hasSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedterms), [hasSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### suggestedContent
- suggestedContent: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : This method returns a list of content pages which were found
      using the suggested terms as search criteria.
      The content lookup is being executed in the current library and locale.


    **See Also:**
    - [Suggestions.hasSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)


---

## Method Details

### getSuggestedContent()
- getSuggestedContent(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : This method returns a list of content pages which were found
      using the suggested terms as search criteria.
      The content lookup is being executed in the current library and locale.


    **Returns:**
    - a iterator containing a [SuggestedContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedContent.md) instance for
               each found content, the iterator might be empty


    **See Also:**
    - [Suggestions.hasSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)


---

<!-- prettier-ignore-end -->

<!-- document id=d72210a6a64774e5bfcc8003600e7d2de218d4339ae8346bc01f396b0dbaaf0d url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.ConversionError.md -->

<!-- prettier-ignore-start -->
# Class ConversionError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.ConversionError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ConversionError.md)

Represents a conversion error.

**API Version:**
**note:** No longer available as of version 21.2.

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ConversionError](#conversionerror)() | Constructs the error. |
| [ConversionError](#conversionerrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the  specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### ConversionError()
- ConversionError()
  - : Constructs the error.


---

### ConversionError(String)
- ConversionError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the
      specified message.


    **Parameters:**
    - msg - the conversion error message.


---

<!-- prettier-ignore-end -->

<!-- document id=e84e6e7714eebad826c49c5adc464f8e860f75904d30b5ca46be4777482bddfe url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.Cookie.md -->

<!-- prettier-ignore-start -->
# Class Cookie

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.Cookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md)

Represents an HTTP cookie used for storing information on a client browser. Cookies are passed along in the HTTP
request and can be retrieved by calling dw.system.Request.getHttpCookies().


Cookies must comply with RFC6265. We recommend you use only printable ASCII characters without separators, such as a
comma or equal sign. If JSON is used as a cookie value, it must be encoded.


**Note:** this class allows access to sensitive security-related data. Pay special attention to PCI DSS v3.
requirements 2, 4, and 12.


See [Request.getHttpCookies()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpcookies).



## Constant Summary

| Constant | Description |
| --- | --- |
| [EMPTYNAME](#emptyname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw_emptyname__" | Default name for cookies with empty strings. |

## Property Summary

| Property | Description |
| --- | --- |
| ~~[comment](#comment): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Returns the comment that was previously set for this cookie, or null if no comment was set. |
| [domain](#domain): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the domain associated with the cookie. |
| [httpOnly](#httponly): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Identifies if the cookie is http-only. |
| [maxAge](#maxage): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the maximum age of the cookie, specified in seconds. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the cookie's name. |
| [path](#path): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the path for the cookie. |
| [secure](#secure): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Identifies if the cookie is secure. |
| [value](#value): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the cookie's value. |
| ~~[version](#version): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~ | Returns the version that was previously set for this cookie. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Cookie](#cookiestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new cookie using the specified name and value. |

## Method Summary

| Method | Description |
| --- | --- |
| ~~[getComment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getcomment)()~~ | Returns the comment that was previously set for this cookie, or null if no comment was set. |
| [getDomain](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getdomain)() | Returns the domain associated with the cookie. |
| [getMaxAge](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getmaxage)() | Returns the maximum age of the cookie, specified in seconds. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getname)() | Returns the cookie's name. |
| [getPath](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getpath)() | Returns the path for the cookie. |
| [getSecure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getsecure)() | Identifies if the cookie is secure. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getvalue)() | Returns the cookie's value. |
| ~~[getVersion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#getversion)()~~ | Returns the version that was previously set for this cookie. |
| [isHttpOnly](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#ishttponly)() | Identifies if the cookie is http-only. |
| ~~[setComment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setcommentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets a comment associated with this cookie. |
| [setDomain](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setdomainstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the domain associated with the cookie. |
| [setHttpOnly](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#sethttponlyboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the http-only state for the cookie. |
| [setMaxAge](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setmaxagenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the maximum age of the cookie in seconds. |
| [setPath](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setpathstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the path for the cookie. |
| [setSecure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setsecureboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the secure state for the cookie. |
| [setValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the cookie's value. |
| ~~[setVersion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setversionnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Returns the version that was previously set for this cookie. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### EMPTYNAME

- EMPTYNAME: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw_emptyname__"
  - : Default name for cookies with empty strings.


---

## Property Details

### comment
- ~~comment: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the comment that was previously set for this cookie, or null if no comment was set. Note that comments
      are no longer supported in RFC 6265 and will not be sent to clients. This method is maintained for backward
      compatibility only.


    **Deprecated:**
**warning:** This method is maintained for backward compatibility only. Cookie comments were removed in RFC 6265
            and are no longer sent to clients. The returned value only reflects what was previously set using
            [setComment(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setcommentstring).
    **API Version:**
**note:** This method is deprecated and will be removed in the next API version.

---

### domain
- domain: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the domain associated with the cookie.


---

### httpOnly
- httpOnly: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cookie is http-only.


---

### maxAge
- maxAge: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum age of the cookie, specified in seconds.
      By default, -1 indicating the cookie will persist until client shutdown.



---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the cookie's name.


---

### path
- path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the path for the cookie.


---

### secure
- secure: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cookie is secure.


---

### value
- value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the cookie's value.


---

### version
- ~~version: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~
  - : Returns the version that was previously set for this cookie. Note that the version is no longer used for
      determining cookie compliance as the system now uses RFC 6265 by default. The returned value only reflects what
      was previously set using [setVersion(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setversionnumber).


    **Deprecated:**
**warning:** This method is maintained for backward compatibility only. The version property is no longer used as
            the system now uses RFC 6265 compliance by default. The returned value has no effect on cookie
            behavior.
    **API Version:**
**note:** This method is deprecated and will be removed in the next API version.

---

## Constructor Details

### Cookie(String, String)
- Cookie(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a new cookie using the specified name and value.

    **Parameters:**
    - name - the name for the cookie.
    - value - the cookie's value.


---

## Method Details

### getComment()
- ~~getComment(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the comment that was previously set for this cookie, or null if no comment was set. Note that comments
      are no longer supported in RFC 6265 and will not be sent to clients. This method is maintained for backward
      compatibility only.


    **Returns:**
    - the comment that was previously set, or null if no comment was set

    **Deprecated:**
**warning:** This method is maintained for backward compatibility only. Cookie comments were removed in RFC 6265
            and are no longer sent to clients. The returned value only reflects what was previously set using
            [setComment(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setcommentstring).
    **API Version:**
**note:** This method is deprecated and will be removed in the next API version.

---

### getDomain()
- getDomain(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the domain associated with the cookie.

    **Returns:**
    - the domain associated with the cookie.


---

### getMaxAge()
- getMaxAge(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum age of the cookie, specified in seconds.
      By default, -1 indicating the cookie will persist until client shutdown.


    **Returns:**
    - an integer specifying the maximum age of the cookie in seconds;
              if negative, means the cookie persists until client shutdown



---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the cookie's name.

    **Returns:**
    - the cookie's name.


---

### getPath()
- getPath(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the path for the cookie.

    **Returns:**
    - the path for the cookie.


---

### getSecure()
- getSecure(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cookie is secure.

    **Returns:**
    - true if the cookie is secure, false otherwise.


---

### getValue()
- getValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the cookie's value.

    **Returns:**
    - the cookie's value.


---

### getVersion()
- ~~getVersion(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~
  - : Returns the version that was previously set for this cookie. Note that the version is no longer used for
      determining cookie compliance as the system now uses RFC 6265 by default. The returned value only reflects what
      was previously set using [setVersion(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setversionnumber).


    **Returns:**
    - the version number that was set, or 0 if no version was explicitly set

    **Deprecated:**
**warning:** This method is maintained for backward compatibility only. The version property is no longer used as
            the system now uses RFC 6265 compliance by default. The returned value has no effect on cookie
            behavior.
    **API Version:**
**note:** This method is deprecated and will be removed in the next API version.

---

### isHttpOnly()
- isHttpOnly(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cookie is http-only.

    **Returns:**
    - true if the cookie is http-only, false otherwise.


---

### setComment(String)
- ~~setComment(comment: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets a comment associated with this cookie. Note that comments are no longer sent to clients as they were removed
      in RFC 6265. This method is maintained for backward compatibility but has no effect on the cookie's behavior.


    **Parameters:**
    - comment - the comment to associate with the cookie (ignored)

    **Deprecated:**
**warning:** This method is maintained for backward compatibility only. Cookie comments were removed in RFC 6265
            and will not be sent to clients. The value will be stored but has no effect on cookie behavior.
    **API Version:**
**note:** This method is deprecated and will be removed in the next API version.

---

### setDomain(String)
- setDomain(domain: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the domain associated with the cookie.

    **Parameters:**
    - domain - the comment associated with the cookie.


---

### setHttpOnly(Boolean)
- setHttpOnly(httpOnly: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets the http-only state for the cookie.

    **Parameters:**
    - httpOnly - sets http-only state for the cookie.


---

### setMaxAge(Number)
- setMaxAge(age: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the maximum age of the cookie in seconds.
      
      A positive value indicates that the cookie will expire after that many
      seconds have passed. Note that the value is the maximum age when the
      cookie will expire, not the cookie's current age.
      
      A negative value means that the cookie is not stored persistently and
      will be deleted when the client exits. A zero value causes the
      cookie to be deleted.


    **Parameters:**
    - age - an integer specifying the maximum age of the cookie in seconds;             if negative, means the cookie is not stored; if zero, deletes             the cookie


---

### setPath(String)
- setPath(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the path for the cookie.

    **Parameters:**
    - path - the path for the cookie.


---

### setSecure(Boolean)
- setSecure(secure: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets the secure state for the cookie.

    **Parameters:**
    - secure - sets secure state for the cookie.


---

### setValue(String)
- setValue(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the cookie's value.

    **Parameters:**
    - value - the value to set in the cookie.


---

### setVersion(Number)
- ~~setVersion(version: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void~~
  - : Returns the version that was previously set for this cookie. Note that the version is no longer used for
      determining cookie compliance as the system now uses RFC 6265 by default. The returned value only reflects what
      was previously set using [setVersion(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md#setversionnumber).


    **Returns:**
    - the version number that was set, or 0 if no version was explicitly set

    **Deprecated:**
**warning:** This method is maintained for backward compatibility only. The version property is no longer used as
            the system now uses RFC 6265 compliance by default. The returned value has no effect on cookie
            behavior.
    **API Version:**
**note:** This method is deprecated and will be removed in the next API version.

---

<!-- prettier-ignore-end -->

<!-- document id=d654a6ee2c0080eab049c30222a6e9bee5ff23d98158fe1af41bba8055c2f502 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.Cookies.md -->

<!-- prettier-ignore-start -->
# Class Cookies

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.Cookies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookies.md)

The class provides an index and associative array like access to the Cookies
of the current request. Cookies can be retrieved by calling
dw.system.Request.getHttpCookies().


**Note:** this class allows access to sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.


See [Request.getHttpCookies()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpcookies).



## Property Summary

| Property | Description |
| --- | --- |
| [cookieCount](#cookiecount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of known cookies. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCookieCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookies.md#getcookiecount)() | Returns the number of known cookies. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### cookieCount
- cookieCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of known cookies.


---

## Method Details

### getCookieCount()
- getCookieCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of known cookies.

    **Returns:**
    - the number of cookies


---

<!-- prettier-ignore-end -->

<!-- document id=68f076a1f9679c5bfbcdda8e60a977156fd8fbab89b8b55c5debcb449c26559a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.Coupon.md -->

<!-- prettier-ignore-start -->
# Class Coupon

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.campaign.Coupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md)

Represents a coupon in Commerce Cloud Digital.


## Constant Summary

| Constant | Description |
| --- | --- |
| [TYPE_MULTIPLE_CODES](#type_multiple_codes): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MULTIPLE_CODES" | Constant representing coupon type _multiple-codes_. |
| [TYPE_SINGLE_CODE](#type_single_code): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SINGLE_CODE" | Constant representing coupon type _single-code_. |
| [TYPE_SYSTEM_CODES](#type_system_codes): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SYSTEM_CODES" | Constant representing coupon type _system-codes_. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the coupon. |
| [codePrefix](#codeprefix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the prefix defined for coupons of type [TYPE_SYSTEM_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_system_codes)  If no prefix is defined, or coupon is of type [TYPE_SINGLE_CODE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_single_code)  or [TYPE_MULTIPLE_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_multiple_codes), null is returned. |
| [enabled](#enabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if coupon is enabled, else false. |
| [nextCouponCode](#nextcouponcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the next unissued code of this coupon. |
| [promotions](#promotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the coupon-based promotions directly or indirectly (through  campaigns) assigned to this coupon. |
| [redemptionLimitPerCode](#redemptionlimitpercode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the defined limit on redemption per coupon code. |
| [redemptionLimitPerCustomer](#redemptionlimitpercustomer): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the defined limit on redemption of this coupon per customer. |
| [redemptionLimitPerTimeFrame](#redemptionlimitpertimeframe): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the defined limit on redemption per customer per time-frame (see  [getRedemptionLimitTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimittimeframe). |
| [redemptionLimitTimeFrame](#redemptionlimittimeframe): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the time-frame (in days) of the defined limit on redemption per  customer per time-frame. |
| [type](#type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the coupon type. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCodePrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getcodeprefix)() | Returns the prefix defined for coupons of type [TYPE_SYSTEM_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_system_codes)  If no prefix is defined, or coupon is of type [TYPE_SINGLE_CODE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_single_code)  or [TYPE_MULTIPLE_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_multiple_codes), null is returned. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getid)() | Returns the ID of the coupon. |
| [getNextCouponCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getnextcouponcode)() | Returns the next unissued code of this coupon. |
| [getPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getpromotions)() | Returns the coupon-based promotions directly or indirectly (through  campaigns) assigned to this coupon. |
| [getRedemptionLimitPerCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimitpercode)() | Returns the defined limit on redemption per coupon code. |
| [getRedemptionLimitPerCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimitpercustomer)() | Returns the defined limit on redemption of this coupon per customer. |
| [getRedemptionLimitPerTimeFrame](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimitpertimeframe)() | Returns the defined limit on redemption per customer per time-frame (see  [getRedemptionLimitTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimittimeframe). |
| [getRedemptionLimitTimeFrame](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimittimeframe)() | Returns the time-frame (in days) of the defined limit on redemption per  customer per time-frame. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#gettype)() | Returns the coupon type. |
| [isEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#isenabled)() | Returns true if coupon is enabled, else false. |

### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TYPE_MULTIPLE_CODES

- TYPE_MULTIPLE_CODES: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MULTIPLE_CODES"
  - : Constant representing coupon type _multiple-codes_.


---

### TYPE_SINGLE_CODE

- TYPE_SINGLE_CODE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SINGLE_CODE"
  - : Constant representing coupon type _single-code_.


---

### TYPE_SYSTEM_CODES

- TYPE_SYSTEM_CODES: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SYSTEM_CODES"
  - : Constant representing coupon type _system-codes_.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the coupon.


---

### codePrefix
- codePrefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the prefix defined for coupons of type [TYPE_SYSTEM_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_system_codes)
      If no prefix is defined, or coupon is of type [TYPE_SINGLE_CODE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_single_code)
      or [TYPE_MULTIPLE_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_multiple_codes), null is returned.



---

### enabled
- enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if coupon is enabled, else false.


---

### nextCouponCode
- nextCouponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the next unissued code of this coupon.
      For single-code coupons, the single fixed coupon code is returned.
      For all multi-code coupons, the next available, unissued coupon code is returned.
      If all codes of the coupon have been issued, then there is no next code, and null is returned.
      
      A transaction is required when calling this method. This needs to be ensured by the calling script.



---

### promotions
- promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the coupon-based promotions directly or indirectly (through
      campaigns) assigned to this coupon.



---

### redemptionLimitPerCode
- redemptionLimitPerCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the defined limit on redemption per coupon code. Null is
      returned if no limit is defined, which means that each code can be
      redeemed an unlimited number of times.



---

### redemptionLimitPerCustomer
- redemptionLimitPerCustomer: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the defined limit on redemption of this coupon per customer.
      Null is returned if no limit is defined, which means that customers can
      redeem this coupon an unlimited number of times.



---

### redemptionLimitPerTimeFrame
- redemptionLimitPerTimeFrame: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the defined limit on redemption per customer per time-frame (see
      [getRedemptionLimitTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimittimeframe). Null is returned if no limit is
      defined, which means that there is no time-specific redemption limit for
      customers.


    **See Also:**
    - [getRedemptionLimitTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimittimeframe)


---

### redemptionLimitTimeFrame
- redemptionLimitTimeFrame: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the time-frame (in days) of the defined limit on redemption per
      customer per time-frame. Null is returned if no limit is defined, which
      means that there is no time-specific redemption limit for customers.


    **See Also:**
    - [getRedemptionLimitPerTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimitpertimeframe)


---

### type
- type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the coupon type.
      Possible values are [TYPE_SINGLE_CODE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_single_code), [TYPE_MULTIPLE_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_multiple_codes)
      and [TYPE_SYSTEM_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_system_codes).



---

## Method Details

### getCodePrefix()
- getCodePrefix(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the prefix defined for coupons of type [TYPE_SYSTEM_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_system_codes)
      If no prefix is defined, or coupon is of type [TYPE_SINGLE_CODE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_single_code)
      or [TYPE_MULTIPLE_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_multiple_codes), null is returned.


    **Returns:**
    - Coupon code prefix or null


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the coupon.

    **Returns:**
    - Coupon ID


---

### getNextCouponCode()
- getNextCouponCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the next unissued code of this coupon.
      For single-code coupons, the single fixed coupon code is returned.
      For all multi-code coupons, the next available, unissued coupon code is returned.
      If all codes of the coupon have been issued, then there is no next code, and null is returned.
      
      A transaction is required when calling this method. This needs to be ensured by the calling script.


    **Returns:**
    - Next available code of this coupon, or null if there are no available codes.


---

### getPromotions()
- getPromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the coupon-based promotions directly or indirectly (through
      campaigns) assigned to this coupon.


    **Returns:**
    - Promotions assigned to the coupon in no particular order.


---

### getRedemptionLimitPerCode()
- getRedemptionLimitPerCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the defined limit on redemption per coupon code. Null is
      returned if no limit is defined, which means that each code can be
      redeemed an unlimited number of times.


    **Returns:**
    - The maximum number of redemption per coupon code


---

### getRedemptionLimitPerCustomer()
- getRedemptionLimitPerCustomer(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the defined limit on redemption of this coupon per customer.
      Null is returned if no limit is defined, which means that customers can
      redeem this coupon an unlimited number of times.


    **Returns:**
    - The maximum number of redemption per customer


---

### getRedemptionLimitPerTimeFrame()
- getRedemptionLimitPerTimeFrame(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the defined limit on redemption per customer per time-frame (see
      [getRedemptionLimitTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimittimeframe). Null is returned if no limit is
      defined, which means that there is no time-specific redemption limit for
      customers.


    **Returns:**
    - The maximum number of redemption per customer within time-frame

    **See Also:**
    - [getRedemptionLimitTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimittimeframe)


---

### getRedemptionLimitTimeFrame()
- getRedemptionLimitTimeFrame(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the time-frame (in days) of the defined limit on redemption per
      customer per time-frame. Null is returned if no limit is defined, which
      means that there is no time-specific redemption limit for customers.


    **Returns:**
    - Timeframe (days) of redemption per time

    **See Also:**
    - [getRedemptionLimitPerTimeFrame()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#getredemptionlimitpertimeframe)


---

### getType()
- getType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the coupon type.
      Possible values are [TYPE_SINGLE_CODE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_single_code), [TYPE_MULTIPLE_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_multiple_codes)
      and [TYPE_SYSTEM_CODES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md#type_system_codes).


    **Returns:**
    - Coupon type


---

### isEnabled()
- isEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if coupon is enabled, else false.

    **Returns:**
    - true if coupon is enabled.


---

<!-- prettier-ignore-end -->

<!-- document id=b8df2605be776f868b4de2319467467b5f8b73aa3ecb2311ba2ea6c2a742c2ab url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.CouponLineItem.md -->

<!-- prettier-ignore-start -->
# Class CouponLineItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)

The CouponLineItem class is used to store redeemed coupons in the Basket.


## Property Summary

| Property | Description |
| --- | --- |
| [applied](#applied): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the coupon is currently applied in the basket. |
| [basedOnCampaign](#basedoncampaign): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the line item represents a coupon of a campaign. |
| [bonusDiscountLineItems](#bonusdiscountlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the bonus discount line items of the line item container triggered  by this coupon. |
| [couponCode](#couponcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the coupon code. |
| [priceAdjustments](#priceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the price adjustments of the line item container triggered  by this coupon. |
| ~~[promotion](#promotion): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)~~ `(read-only)` | Returns the promotion related to the coupon line item. |
| ~~[promotionID](#promotionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | Returns the id of the related promotion. |
| [statusCode](#statuscode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | This method provides a detailed error status in case the coupon code of  this coupon line item instance became invalid. |
| [valid](#valid): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Allows to check whether the coupon code of this coupon line item instance  is valid. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [associatePriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#associatepriceadjustmentpriceadjustment)([PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)) | Associates the specified price adjustment with the coupon line item. |
| [getBonusDiscountLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#getbonusdiscountlineitems)() | Returns the bonus discount line items of the line item container triggered  by this coupon. |
| [getCouponCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#getcouponcode)() | Returns the coupon code. |
| [getPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#getpriceadjustments)() | Returns the price adjustments of the line item container triggered  by this coupon. |
| ~~[getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#getpromotion)()~~ | Returns the promotion related to the coupon line item. |
| ~~[getPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#getpromotionid)()~~ | Returns the id of the related promotion. |
| [getStatusCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#getstatuscode)() | This method provides a detailed error status in case the coupon code of  this coupon line item instance became invalid. |
| [isApplied](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#isapplied)() | Identifies if the coupon is currently applied in the basket. |
| [isBasedOnCampaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#isbasedoncampaign)() | Returns true if the line item represents a coupon of a campaign. |
| [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#isvalid)() | Allows to check whether the coupon code of this coupon line item instance  is valid. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### applied
- applied: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the coupon is currently applied in the basket. A coupon
      line is applied if there exists at least one price adjustment related
      to the coupon line item.



---

### basedOnCampaign
- basedOnCampaign: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the line item represents a coupon of a campaign. If the coupon line item represents a custom
      coupon code, the method returns false.



---

### bonusDiscountLineItems
- bonusDiscountLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the bonus discount line items of the line item container triggered
      by this coupon.



---

### couponCode
- couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the coupon code.


---

### priceAdjustments
- priceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the price adjustments of the line item container triggered
      by this coupon.



---

### promotion
- ~~promotion: [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)~~ `(read-only)`
  - : Returns the promotion related to the coupon line item.

    **Deprecated:**
**warning:** A coupon code and its coupon can be associated with
            multiple promotions. Therefore, this method is not
            appropriate anymore. For backward-compatibility, the method
            returns one of the promotions associated with the coupon
            code.

---

### promotionID
- ~~promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : Returns the id of the related promotion.

    **Deprecated:**
**warning:** A coupon code and it's coupon can be associated with
            multiple promotions. Therefore, this method is not
            appropriate anymore. For backward-compatibility, the method
            returns the ID of one of the promotions associated with
            the coupon code.

---

### statusCode
- statusCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : This method provides a detailed error status in case the coupon code of
      this coupon line item instance became invalid.



---

### valid
- valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Allows to check whether the coupon code of this coupon line item instance
      is valid. Coupon line item is valid, if status code is one of the following:
      
      - [CouponStatusCodes.APPLIED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#applied)
      - [CouponStatusCodes.NO_APPLICABLE_PROMOTION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#no_applicable_promotion)



---

## Method Details

### associatePriceAdjustment(PriceAdjustment)
- associatePriceAdjustment(priceAdjustment: [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)): void
  - : Associates the specified price adjustment with the coupon line item. This method is only applicable if used for
      price adjustments and coupon line items NOT based on B2C Commerce campaigns.


    **Parameters:**
    - priceAdjustment - Price adjustment to be associated with coupon line item.


---

### getBonusDiscountLineItems()
- getBonusDiscountLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the bonus discount line items of the line item container triggered
      by this coupon.


    **Returns:**
    - Price adjustments triggered by the coupon


---

### getCouponCode()
- getCouponCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the coupon code.

    **Returns:**
    - Coupon code


---

### getPriceAdjustments()
- getPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the price adjustments of the line item container triggered
      by this coupon.


    **Returns:**
    - Price adjustments triggered by the coupon


---

### getPromotion()
- ~~getPromotion(): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)~~
  - : Returns the promotion related to the coupon line item.

    **Returns:**
    - Promotion related to coupon represented by line item

    **Deprecated:**
**warning:** A coupon code and its coupon can be associated with
            multiple promotions. Therefore, this method is not
            appropriate anymore. For backward-compatibility, the method
            returns one of the promotions associated with the coupon
            code.

---

### getPromotionID()
- ~~getPromotionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the id of the related promotion.

    **Returns:**
    - the id of the related promotion.

    **Deprecated:**
**warning:** A coupon code and it's coupon can be associated with
            multiple promotions. Therefore, this method is not
            appropriate anymore. For backward-compatibility, the method
            returns the ID of one of the promotions associated with
            the coupon code.

---

### getStatusCode()
- getStatusCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : This method provides a detailed error status in case the coupon code of
      this coupon line item instance became invalid.


    **Returns:**
    - Returns APPLIED if coupon is applied, and otherwise one of the
      codes defined in [CouponStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md)



---

### isApplied()
- isApplied(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the coupon is currently applied in the basket. A coupon
      line is applied if there exists at least one price adjustment related
      to the coupon line item.


    **Returns:**
    - true if the coupon is currently applied in the basket.


---

### isBasedOnCampaign()
- isBasedOnCampaign(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the line item represents a coupon of a campaign. If the coupon line item represents a custom
      coupon code, the method returns false.



---

### isValid()
- isValid(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Allows to check whether the coupon code of this coupon line item instance
      is valid. Coupon line item is valid, if status code is one of the following:
      
      - [CouponStatusCodes.APPLIED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#applied)
      - [CouponStatusCodes.NO_APPLICABLE_PROMOTION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#no_applicable_promotion)


    **Returns:**
    - true if the coupon code is valid, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=539d0b1f8bdce6eaae37ce55eb870f0890cd306d7e9e8b675c2c35060ada421e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.CouponMgr.md -->

<!-- prettier-ignore-start -->
# Class CouponMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.CouponMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponMgr.md)

Manager to access coupons.


## Constant Summary

| Constant | Description |
| --- | --- |
| [MR_ERROR_INVALID_SITE_ID](#mr_error_invalid_site_id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MASKREDEMPTIONS_SITE_NOT_FOUND" | Indicates that an error occurred because a valid data domain cannot be found for given siteID. |

## Property Summary

| Property | Description |
| --- | --- |
| [coupons](#coupons): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all coupons in the current site in no specific order. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getCoupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponMgr.md#getcouponstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the coupon with the specified ID. |
| static [getCouponByCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponMgr.md#getcouponbycodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Tries to find a coupon for the given coupon code. |
| static [getCoupons](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponMgr.md#getcoupons)() | Returns all coupons in the current site in no specific order. |
| static [getRedemptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponMgr.md#getredemptionsstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns list of CouponRedemptions for the specified coupon and coupon code,  sorted by redemption date descending (i.e. |
| static [maskRedemptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponMgr.md#maskredemptionsstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Mask customer email address in coupon redemptions for the given siteID and email address |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### MR_ERROR_INVALID_SITE_ID

- MR_ERROR_INVALID_SITE_ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MASKREDEMPTIONS_SITE_NOT_FOUND"
  - : Indicates that an error occurred because a valid data domain cannot be found for given siteID.


---

## Property Details

### coupons
- coupons: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all coupons in the current site in no specific order.


---

## Method Details

### getCoupon(String)
- static getCoupon(couponID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Coupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md)
  - : Returns the coupon with the specified ID.

    **Parameters:**
    - couponID - the coupon identifier.

    **Returns:**
    - Coupon with specified ID or null


---

### getCouponByCode(String)
- static getCouponByCode(couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Coupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md)
  - : Tries to find a coupon for the given coupon code. The method first
      searches for a coupon with a fixed code matching the passed value. If no
      such fixed coupon is found, it searches for a coupon with a
      system-generated code matching the passed value. If found, the coupon is
      returned. Otherwise, the method returns null.


    **Parameters:**
    - couponCode - The coupon code to get the coupon for.

    **Returns:**
    - The coupon with the matching coupon code or null if no coupon was
              found.



---

### getCoupons()
- static getCoupons(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all coupons in the current site in no specific order.

    **Returns:**
    - Coupons in current site


---

### getRedemptions(String, String)
- static getRedemptions(couponID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns list of CouponRedemptions for the specified coupon and coupon code,
      sorted by redemption date descending (i.e. last redemption first).
      Usually, there should only either be 0 or 1 redemption. But if a coupon and code
      is removed and recreated and re-issued later, there might be multiple such redemption records.
      Returns an empty list if no redemption record exists in system for the specified coupon and code.


    **Parameters:**
    - couponID - The coupon id to find redemption for.
    - couponCode - The coupon code to find redemption for.

    **Returns:**
    - A sorted list of CouponRedemptions for the specified coupon and coupon code or
      an empty list if no redemption record exists.



---

### maskRedemptions(String, String)
- static maskRedemptions(siteID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), email: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Mask customer email address in coupon redemptions for the given siteID and email address

    **Parameters:**
    - siteID - the site ID
    - email - the customer email address

    **Returns:**
    - The status of the masking result


---

<!-- prettier-ignore-end -->

<!-- document id=ca42166aab57076c1852c529ce82807371bb98968c97958e9e77668ec2f937a6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.CouponRedemption.md -->

<!-- prettier-ignore-start -->
# Class CouponRedemption

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.CouponRedemption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponRedemption.md)

Represents a redeemed coupon.


## Property Summary

| Property | Description |
| --- | --- |
| [customerEmail](#customeremail): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns email of redeeming customer. |
| [orderNo](#orderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns number of the order the code was redeemed with. |
| [redemptionDate](#redemptiondate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns date of redemption. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCustomerEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponRedemption.md#getcustomeremail)() | Returns email of redeeming customer. |
| [getOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponRedemption.md#getorderno)() | Returns number of the order the code was redeemed with. |
| [getRedemptionDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponRedemption.md#getredemptiondate)() | Returns date of redemption. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### customerEmail
- customerEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns email of redeeming customer.


---

### orderNo
- orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns number of the order the code was redeemed with.


---

### redemptionDate
- redemptionDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns date of redemption.


---

## Method Details

### getCustomerEmail()
- getCustomerEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns email of redeeming customer.

    **Returns:**
    - email of redeeming customer.


---

### getOrderNo()
- getOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns number of the order the code was redeemed with.

    **Returns:**
    - number of the order the code was redeemed with.


---

### getRedemptionDate()
- getRedemptionDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns date of redemption.

    **Returns:**
    - date of redemption.


---

<!-- prettier-ignore-end -->

<!-- document id=f314bbb3deed85e466e7503e9e8f21a6a48d7051f67a3ac6ae05615988666e6c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.CouponStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class CouponStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.CouponStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md)

Helper class containing status codes for why a coupon code cannot be added
to cart or why a coupon code already in cart is not longer valid for redemption.



## Constant Summary

| Constant | Description |
| --- | --- |
| [APPLIED](#applied): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "APPLIED" | Coupon is currently applied in basket = Coupon code is valid for redemption and  Coupon is assigned to one or multiple applicable promotions. |
| [COUPON_ALREADY_IN_BASKET](#coupon_already_in_basket): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_ALREADY_IN_BASKET" | Indicates that another code of the same MultiCode/System coupon has already been added to basket. |
| [COUPON_CODE_ALREADY_IN_BASKET](#coupon_code_already_in_basket): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODE_ALREADY_IN_BASKET" | Indicates that coupon code has already been added to basket. |
| [COUPON_CODE_ALREADY_REDEEMED](#coupon_code_already_redeemed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODE_ALREADY_REDEEMED" | Indicates that code of MultiCode/System coupon has already been redeemed. |
| [COUPON_CODE_UNKNOWN](#coupon_code_unknown): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODE_UNKNOWN" | Indicates that coupon not found for given coupon code or that the code itself was not found. |
| [COUPON_DISABLED](#coupon_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_DISABLED" | Indicates that coupon is not enabled. |
| [CUSTOMER_REDEMPTION_LIMIT_EXCEEDED](#customer_redemption_limit_exceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_REDEMPTION_LIMIT_EXCEEDED" | Indicates that No. |
| [NO_ACTIVE_PROMOTION](#no_active_promotion): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_ACTIVE_PROMOTION" | Indicates that coupon is not assigned to an active promotion. |
| [NO_APPLICABLE_PROMOTION](#no_applicable_promotion): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_APPLICABLE_PROMOTION" | Coupon is assigned to one or multiple active promotions, but none of these promotions is currently applicable. |
| [REDEMPTION_LIMIT_EXCEEDED](#redemption_limit_exceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "REDEMPTION_LIMIT_EXCEEDED" | Indicates that no. |
| [TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED](#timeframe_redemption_limit_exceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED" | Indicates that No. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### APPLIED

- APPLIED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "APPLIED"
  - : Coupon is currently applied in basket = Coupon code is valid for redemption and
      Coupon is assigned to one or multiple applicable promotions.



---

### COUPON_ALREADY_IN_BASKET

- COUPON_ALREADY_IN_BASKET: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_ALREADY_IN_BASKET"
  - : Indicates that another code of the same MultiCode/System coupon has already been added to basket.


---

### COUPON_CODE_ALREADY_IN_BASKET

- COUPON_CODE_ALREADY_IN_BASKET: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODE_ALREADY_IN_BASKET"
  - : Indicates that coupon code has already been added to basket.


---

### COUPON_CODE_ALREADY_REDEEMED

- COUPON_CODE_ALREADY_REDEEMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODE_ALREADY_REDEEMED"
  - : Indicates that code of MultiCode/System coupon has already been redeemed.


---

### COUPON_CODE_UNKNOWN

- COUPON_CODE_UNKNOWN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODE_UNKNOWN"
  - : Indicates that coupon not found for given coupon code or that the code itself was not found.


---

### COUPON_DISABLED

- COUPON_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_DISABLED"
  - : Indicates that coupon is not enabled.


---

### CUSTOMER_REDEMPTION_LIMIT_EXCEEDED

- CUSTOMER_REDEMPTION_LIMIT_EXCEEDED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_REDEMPTION_LIMIT_EXCEEDED"
  - : Indicates that No. of redemptions per code & customer exceeded.


---

### NO_ACTIVE_PROMOTION

- NO_ACTIVE_PROMOTION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_ACTIVE_PROMOTION"
  - : Indicates that coupon is not assigned to an active promotion.


---

### NO_APPLICABLE_PROMOTION

- NO_APPLICABLE_PROMOTION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_APPLICABLE_PROMOTION"
  - : Coupon is assigned to one or multiple active promotions, but none of these promotions is currently applicable.


---

### REDEMPTION_LIMIT_EXCEEDED

- REDEMPTION_LIMIT_EXCEEDED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "REDEMPTION_LIMIT_EXCEEDED"
  - : Indicates that no. of redemptions per code exceeded.
      Usually happens for single code coupons



---

### TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED

- TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED"
  - : Indicates that No. of redemptions per code,customer & time exceeded.


---

<!-- prettier-ignore-end -->

<!-- document id=aceff368e74d85846747c4e8958d2c555ff1bec56818f3a9c2f0755f73cb5db2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.CreateAgentBasketLimitExceededException.md -->

<!-- prettier-ignore-start -->
# Class CreateAgentBasketLimitExceededException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.CreateAgentBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateAgentBasketLimitExceededException.md)

This exception is thrown by [BasketMgr.createAgentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createagentbasket) to indicate that the open agent basket limit for
the current session customer is already reached, and therefore no new agent basket could be created.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CreateAgentBasketLimitExceededException](#createagentbasketlimitexceededexception)() |  |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### CreateAgentBasketLimitExceededException()
- CreateAgentBasketLimitExceededException()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=029ab910e99d20d2941c6f39d2d4fab1d63b3c7fb1ffedbb3335dbb66d0fba83 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.CreateBasketFromOrderException.md -->

<!-- prettier-ignore-start -->
# Class CreateBasketFromOrderException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.CreateBasketFromOrderException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateBasketFromOrderException.md)

This APIException is thrown by method [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder)
to indicate no Basket could be created from the Order.



## Property Summary

| Property | Description |
| --- | --- |
| [errorCode](#errorcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Indicates reason why [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder) failed. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getErrorCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateBasketFromOrderException.md#geterrorcode)() | Indicates reason why [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder) failed. |

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### errorCode
- errorCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Indicates reason why [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder) failed.


---

## Method Details

### getErrorCode()
- getErrorCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Indicates reason why [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder) failed.

    **Returns:**
    - the error code.


---

<!-- prettier-ignore-end -->

<!-- document id=b90168b67cfdd7c35ccaafd78a97cc8173ed4619f07897260e24cecb5bbefb78 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.CreateCouponLineItemException.md -->

<!-- prettier-ignore-start -->
# Class CreateCouponLineItemException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.CreateCouponLineItemException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateCouponLineItemException.md)

This exception could be thrown by [LineItemCtnr.createCouponLineItem(String, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring-boolean)
when the provided coupon code is invalid.


'errorCode' property is set to one of the following values:

- [CouponStatusCodes.COUPON_CODE_ALREADY_IN_BASKET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_already_in_basket)= Indicates that coupon code has already been added to basket.
- [CouponStatusCodes.COUPON_ALREADY_IN_BASKET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_already_in_basket)= Indicates that another code of the same MultiCode/System coupon has already been added to basket.
- [CouponStatusCodes.COUPON_CODE_ALREADY_REDEEMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_already_redeemed)= Indicates that code of MultiCode/System coupon has already been redeemed.
- [CouponStatusCodes.COUPON_CODE_UNKNOWN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_unknown)= Indicates that coupon not found for given coupon code or that the code itself was not found.
- [CouponStatusCodes.COUPON_DISABLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_disabled)= Indicates that coupon is not enabled.
- [CouponStatusCodes.REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#redemption_limit_exceeded)= Indicates that number of redemptions per code exceeded.
- [CouponStatusCodes.CUSTOMER_REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#customer_redemption_limit_exceeded)= Indicates that number of redemptions per code and customer exceeded.
- [CouponStatusCodes.TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#timeframe_redemption_limit_exceeded)= Indicates that number of redemptions per code, customer and time exceeded.
- [CouponStatusCodes.NO_ACTIVE_PROMOTION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#no_active_promotion)= Indicates that coupon is not assigned to an active promotion.



## Property Summary

| Property | Description |
| --- | --- |
| [errorCode](#errorcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns one of the error codes listed in the class doc. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getErrorCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateCouponLineItemException.md#geterrorcode)() | Returns one of the error codes listed in the class doc. |

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### errorCode
- errorCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns one of the error codes listed in the class doc.


---

## Method Details

### getErrorCode()
- getErrorCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns one of the error codes listed in the class doc.

    **Returns:**
    - the error code


---

<!-- prettier-ignore-end -->

<!-- document id=5a8994c736be51005b2048248da193f99e98bcaed5758e0ccfaa0dcf286c906b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.CreateOrderException.md -->

<!-- prettier-ignore-start -->
# Class CreateOrderException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.CreateOrderException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateOrderException.md)

This APIException is thrown by method [OrderMgr.createOrder(Basket, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket-string)
to indicate no Order could be created from the Basket.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=80c0f0f46e67a766aa189d2b3a14fd1d19ba7a59945c447a1a31b400e07df5d8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.CreateTemporaryBasketLimitExceededException.md -->

<!-- prettier-ignore-start -->
# Class CreateTemporaryBasketLimitExceededException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.CreateTemporaryBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateTemporaryBasketLimitExceededException.md)

This exception is thrown by [BasketMgr.createTemporaryBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createtemporarybasket) to indicate that the open temporary basket
limit for the current session customer is already reached, and therefore no new temporary basket could be created.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CreateTemporaryBasketLimitExceededException](#createtemporarybasketlimitexceededexception)() |  |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### CreateTemporaryBasketLimitExceededException()
- CreateTemporaryBasketLimitExceededException()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=a7c9cfa11289e7f7577e683ac5bbdc6eecd251db3b02250cb52b095d0bc5aa38 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.Credentials.md -->

<!-- prettier-ignore-start -->
# Class Credentials

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.Credentials](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md)

Represents the credentials of a customer.

Since 13.6 it is possible to have customers who are not authenticated through a
login and password but through an external authentication provider via the OAuth2 protocol.

In such cases, the AuthenticationProviderID will point to an OAuth provider configured in the system
and the ExternalID will be the unique identifier of the customer on the Authentication Provider's system.

For example, if an authentication provider with ID "Google123" is configured pointing to Google
and the customer has a logged in into Google in the past and has created a profile there, Google
assigns a unique number identifier to that customer. If the storefront is configured to allow
authentication through Google and a new customer logs into the storefront using Google,
the AuthenticationProviderID property of his Credentials will contain "Google123" and
the ExternalID property will contain whatever unique identifier Google has assigned to him.
In such cases the password-related properties of the Credentials will be empty.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Property Summary

| Property | Description |
| --- | --- |
| ~~[authenticationProviderID](#authenticationproviderid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Returns the authentication provider ID. |
| [enabled](#enabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this customer is enabled and can log in. |
| [enabledFlag](#enabledflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Identifies if this customer is enabled and can log in - same as isEnabled(). |
| ~~[externalID](#externalid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Returns the external ID of the customer. |
| [locked](#locked): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this customer is temporarily locked out because of invalid  login attempts. |
| [login](#login): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the login of the user. |
| [passwordAnswer](#passwordanswer): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the answer to the password question for the customer. |
| [passwordQuestion](#passwordquestion): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the password question for the customer. |
| [passwordSet](#passwordset): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether the password is set. |
| [remainingLoginAttempts](#remainingloginattempts): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of consecutive failed logins after which this customer  will be temporarily locked out and prevented from logging in to the  current site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createResetPasswordToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#createresetpasswordtoken)() | Generate a random token which can be used for resetting the password of the underlying Customer. |
| ~~[getAuthenticationProviderID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#getauthenticationproviderid)()~~ | Returns the authentication provider ID. |
| [getEnabledFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#getenabledflag)() | Identifies if this customer is enabled and can log in - same as isEnabled(). |
| ~~[getExternalID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#getexternalid)()~~ | Returns the external ID of the customer. |
| [getLogin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#getlogin)() | Returns the login of the user. |
| [getPasswordAnswer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#getpasswordanswer)() | Returns the answer to the password question for the customer. |
| [getPasswordQuestion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#getpasswordquestion)() | Returns the password question for the customer. |
| [getRemainingLoginAttempts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#getremainingloginattempts)() | Returns the number of consecutive failed logins after which this customer  will be temporarily locked out and prevented from logging in to the  current site. |
| [isEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#isenabled)() | Identifies if this customer is enabled and can log in. |
| [isLocked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#islocked)() | Identifies if this customer is temporarily locked out because of invalid  login attempts. |
| [isPasswordSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#ispasswordset)() | Returns whether the password is set. |
| ~~[setAuthenticationProviderID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setauthenticationprovideridstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the authentication provider ID corresponding to an OAuth provider configured in the system. |
| [setEnabledFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setenabledflagboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the enabled status of the customer. |
| ~~[setExternalID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setexternalidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the external ID of the customer at the authentication provider. |
| ~~[setLogin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setloginstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the login value for the customer. |
| [setLogin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setloginstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the login value for the customer, and also re-encrypt the customer  password based on the new login. |
| [setPassword](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setpasswordstring-string-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the password of an authenticated customer.<br/>   The method can be called for externally authenticated customers as well but  these customers will still be externally authenticated so calling the method  for such customers does not have an immediate practical benefit. |
| [setPasswordAnswer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setpasswordanswerstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the answer to the password question for the customer. |
| [setPasswordQuestion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setpasswordquestionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the password question for the customer. |
| [setPasswordWithToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setpasswordwithtokenstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the password of the specified customer to the specified value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### authenticationProviderID
- ~~authenticationProviderID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the authentication provider ID.

    **Deprecated:**
**warning:** As of release 17.2, replaced by methods on the new class [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
which can be obtained from [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles)

Until the method is fully removed from the API it will get the Authentication Provider from
the first element of the [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles) collection

---

### enabled
- enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this customer is enabled and can log in.


---

### enabledFlag
- enabledFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this customer is enabled and can log in - same as isEnabled().


---

### externalID
- ~~externalID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the external ID of the customer.

    **Deprecated:**
**warning:** As of release 17.2, replaced by methods on the new class [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
which can be obtained from [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles)

Until the method is fully removed from the API it will get the External ID from
the first element of the [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles) collection

---

### locked
- locked: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this customer is temporarily locked out because of invalid
      login attempts.  If customer locking is not enabled, this method always
      returns false.



---

### login
- login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the login of the user. It must be unique.


---

### passwordAnswer
- passwordAnswer: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the answer to the password question for the customer. The answer is used
      with the password question to confirm the identity of a customer when
      they are trying to fetch their password.



---

### passwordQuestion
- passwordQuestion: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the password question for the customer. The password question is
      used with the password answer to confirm the identity of a customer when
      they are trying to fetch their password.



---

### passwordSet
- passwordSet: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether the password is set. Creating externally authenticated customers
      results in customers with credentials for which the password is not set.



---

### remainingLoginAttempts
- remainingLoginAttempts: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of consecutive failed logins after which this customer
      will be temporarily locked out and prevented from logging in to the
      current site. This value is based on the number of previous invalid
      logins for this customer and customer site preferences defining the
      limits.
      
      If this customer is already locked out, this method will always return 0.
      If customer locking is disabled altogether, or if the system cannot
      determine the number of failed login attempts for this customer, then
      this method will return a negative number.



---

## Method Details

### createResetPasswordToken()
- createResetPasswordToken(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Generate a random token which can be used for resetting the password of the underlying Customer. The token is
      guaranteed to be unique and will be valid for 30 minutes. Any token previously generated for this customer will
      be invalidated.


    **Returns:**
    - The generated token.


---

### getAuthenticationProviderID()
- ~~getAuthenticationProviderID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the authentication provider ID.

    **Returns:**
    - the authentication provider ID.

    **Deprecated:**
**warning:** As of release 17.2, replaced by methods on the new class [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
which can be obtained from [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles)

Until the method is fully removed from the API it will get the Authentication Provider from
the first element of the [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles) collection

---

### getEnabledFlag()
- getEnabledFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this customer is enabled and can log in - same as isEnabled().

    **Returns:**
    - true if the customer is enabled and can log in, false otherwise.


---

### getExternalID()
- ~~getExternalID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the external ID of the customer.

    **Returns:**
    - the external ID of the customer.

    **Deprecated:**
**warning:** As of release 17.2, replaced by methods on the new class [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
which can be obtained from [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles)

Until the method is fully removed from the API it will get the External ID from
the first element of the [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles) collection

---

### getLogin()
- getLogin(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the login of the user. It must be unique.

    **Returns:**
    - the login of the user.


---

### getPasswordAnswer()
- getPasswordAnswer(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the answer to the password question for the customer. The answer is used
      with the password question to confirm the identity of a customer when
      they are trying to fetch their password.


    **Returns:**
    - the answer to the password question for the customer.


---

### getPasswordQuestion()
- getPasswordQuestion(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the password question for the customer. The password question is
      used with the password answer to confirm the identity of a customer when
      they are trying to fetch their password.


    **Returns:**
    - the password question for the customer.


---

### getRemainingLoginAttempts()
- getRemainingLoginAttempts(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of consecutive failed logins after which this customer
      will be temporarily locked out and prevented from logging in to the
      current site. This value is based on the number of previous invalid
      logins for this customer and customer site preferences defining the
      limits.
      
      If this customer is already locked out, this method will always return 0.
      If customer locking is disabled altogether, or if the system cannot
      determine the number of failed login attempts for this customer, then
      this method will return a negative number.


    **Returns:**
    - The number of consecutive failed logins after which this customer
              will be locked out.



---

### isEnabled()
- isEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this customer is enabled and can log in.

    **Returns:**
    - true if the customer is enabled and can log in, false otherwise.


---

### isLocked()
- isLocked(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this customer is temporarily locked out because of invalid
      login attempts.  If customer locking is not enabled, this method always
      returns false.


    **Returns:**
    - true if the customer is locked, false otherwise.


---

### isPasswordSet()
- isPasswordSet(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether the password is set. Creating externally authenticated customers
      results in customers with credentials for which the password is not set.


    **Returns:**
    - true if the password is set.


---

### setAuthenticationProviderID(String)
- ~~setAuthenticationProviderID(authenticationProviderID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the authentication provider ID corresponding to an OAuth provider configured in the system.

    **Parameters:**
    - authenticationProviderID - the authentication Provider ID to set.

    **Deprecated:**
**warning:** As of release 17.2, replaced by methods on the new class [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
which can be obtained from [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles)

Until the method is fully removed from the API it will set the Authentication Provider on
the first element of the [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles) collection if there is only one.
It will create the collection and add an element if no elements are present.
It will not change anything and will log an error if there are more than one elements in the collection.

---

### setEnabledFlag(Boolean)
- setEnabledFlag(enabledFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets the enabled status of the customer.

    **Parameters:**
    - enabledFlag - controls if a customer is enabled or not.


---

### setExternalID(String)
- ~~setExternalID(externalID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the external ID of the customer at the authentication provider.
      The value is provided by the authentication provider during the
      OAuth authentication and is unique within that provider.


    **Parameters:**
    - externalID - the external ID to set.

    **Deprecated:**
**warning:** As of release 17.2, replaced by methods on the new class [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
which can be obtained from [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles)

Until the method is fully removed from the API it will set the ExternalID on
the first element of the [Customer.getExternalProfiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles) collection if there is only one.
It will create the collection and add an element if no elements are present.
It will not change anything and will log an error if there are more than one elements in the collection.

---

### setLogin(String)
- ~~setLogin(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the login value for the customer.
      
      IMPORTANT: This method should no longer be used for the following
      reasons:
      
      
      - It changes the login without re-encrypting the password. (The  customer password is stored internally using a one-way encryption scheme  which uses the login as one of its inputs. Therefore changing the login  requires re-encrypting the password.)
      - It does not validate the structure of the login to ensure that it  only uses acceptable characters.
      - It does not correctly prevent duplicate logins. If the passed login  matches a different customer's login exactly, then this method will throw  an exception. However, it does not prevent the creation of inexact matches,  where two customers have a login differing only by alphabetic case (e.g.  "JaneDoe" and "janedoe")


    **Parameters:**
    - login - The login value for the customer.

    **Deprecated:**
**warning:** Use [setLogin(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#setloginstring-string)

---

### setLogin(String, String)
- setLogin(newLogin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), currentPassword: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Sets the login value for the customer, and also re-encrypt the customer
      password based on the new login. Customer login must be a sequence of
      letters, numbers, and the following characters: space, period, ampersand,
      underscore and dash.
      
      This method fails to set the login and returns false in the following
      cases:
      
      
      - newLogin is of an invalid form (e.g. contains invalid characters).
      - currentPassword is not the customer's correct password.
      - newLogin is already in use by another customer (i.e. there is another  customer in the system with the exact same login name or a name differing  only by alphabetic case.)
      
      
      If newLogin is the same as the existing login, the method does nothing and
      returns true, regardless of whether currentPassword is the correct
      password.


    **Parameters:**
    - newLogin - The login value for the customer.
    - currentPassword - The customer's current password in plain-text.

    **Returns:**
    - true if setting the login succeeded, false otherwise.


---

### setPassword(String, String, Boolean)
- setPassword(newPassword: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), oldPassword: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), verifyOldPassword: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Sets the password of an authenticated customer.
      
      
      The method can be called for externally authenticated customers as well but
      these customers will still be externally authenticated so calling the method
      for such customers does not have an immediate practical benefit. If such customers
      are converted back to regularly authenticated (via login and password) the new password
      will be used.
      
      
      
      Method call will fail under any of these conditions:
      
      - customer is not registered
      - customer is not authenticated
      - verifyOldPassword=true &&oldPassword is empty
      - verifyOldPassword=true and oldPassword does not match the existing password
      - newPassword is empty
      - newPassword does not meet acceptance criteria


    **Parameters:**
    - newPassword - the new password
    - oldPassword - the old password (optional, only needed if 'verifyOldPassword' is set to 'true'
    - verifyOldPassword - whether the oldPassword should be verified

    **Returns:**
    - Status the status of the operation (OK or ERROR). If status is Error, there will be additional information in the Status message


---

### setPasswordAnswer(String)
- setPasswordAnswer(answer: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the answer to the password question for the customer.

    **Parameters:**
    - answer - the answer to the password question.


---

### setPasswordQuestion(String)
- setPasswordQuestion(question: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the password question for the customer.

    **Parameters:**
    - question - the password question.


---

### setPasswordWithToken(String, String)
- setPasswordWithToken(token: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), newPassword: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Set the password of the specified customer to the specified value. This operation will fail if the specified
      token is invalid (i.e. not associated with the specified Customer), the token is expired, or the password does
      not satisfy system password requirements.


    **Parameters:**
    - token - The token required for performing the password reset.
    - newPassword - The new password. Must meet all requirements for passwords

    **Returns:**
    - Status the status of the operation (OK or ERROR). If status is Error, there will be additional
              information in the Status message



---

<!-- prettier-ignore-end -->

<!-- document id=86ec06cd80e89ae3a845745a6b27abdc4d524085a9a93e85358fda1a93be9f1a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.CSRFProtection.md -->

<!-- prettier-ignore-start -->
# Class CSRFProtection

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.CSRFProtection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.CSRFProtection.md)

Used to generate and validate CSRF tokens. CSRFProtection allows
applications to protect themselves against CSRF attacks, using
synchronizer tokens, a best practice. Once created, these tokens
are tied to a user’s session and valid for 60 minutes.


Usage:

Adding CSRF token to forms:


```
//CSRF token generation
<form ... action="<protected location>">
  <input name="foo" value="bar">
  <input name="${dw.web.CSRFProtection.getTokenName()}"
            value="${dw.web.CSRFProtection.generateToken()">
</form>
```


Then, in scripts call:


```
dw.web.CSRFProtection.validateRequest();
```



## Property Summary

| Property | Description |
| --- | --- |
| [tokenName](#tokenname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the system generated CSRF token name. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [generateToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.CSRFProtection.md#generatetoken)() | Constructs a new unique CSRF token for this session. |
| static [getTokenName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.CSRFProtection.md#gettokenname)() | Returns the system generated CSRF token name. |
| static [validateRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.CSRFProtection.md#validaterequest)() | Verifies that a client request contains a valid CSRF token, and that  the token has not expired. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### tokenName
- tokenName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the system generated CSRF token name. Currently, this name is not user configurable. Must be used for
      [validateRequest()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.CSRFProtection.md#validaterequest) to work



---

## Method Details

### generateToken()
- static generateToken(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Constructs a new unique CSRF token for this session.

    **Returns:**
    - a new CSRF token


---

### getTokenName()
- static getTokenName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the system generated CSRF token name. Currently, this name is not user configurable. Must be used for
      [validateRequest()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.CSRFProtection.md#validaterequest) to work


    **Returns:**
    - System-generated CSRF token parameter name


---

### validateRequest()
- static validateRequest(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies that a client request contains a valid CSRF token, and that
      the token has not expired. Returns true if these conditions are met,
      and false otherwise


    **Returns:**
    - true if request contains a valid CSRF token, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=5a9ebfa2a2b5f562c35d4e5bfbadb9d4c11df386e1e0f3f5835df8005c9092f4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.CSVStreamReader.md -->

<!-- prettier-ignore-start -->
# Class CSVStreamReader

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.CSVStreamReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamReader.md)

The class supports reading a CSV file. The reader supports handling CSV
entries where the separator is contained in quotes and also CSV entries where
a quoted entry contains newline characters.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CSVStreamReader](#csvstreamreaderreader)([Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md)) | Creates a new CSVReader with a ',' as separator character and a '"' as  quote character. |
| [CSVStreamReader](#csvstreamreaderreader-string)([Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new CSVReader with the specified separator character and a '"'  as quote character. |
| [CSVStreamReader](#csvstreamreaderreader-string-string)([Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new CSVReader with the specified separator character and the  specified quote character. |
| [CSVStreamReader](#csvstreamreaderreader-string-string-number)([Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a new CSVReader. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamReader.md#close)() | Closes the underlying reader. |
| [readAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamReader.md#readall)() | Returns a list of lines representing the entire CSV file. |
| [readNext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamReader.md#readnext)() | Returns the next line from the input stream. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### CSVStreamReader(Reader)
- CSVStreamReader(ioreader: [Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md))
  - : Creates a new CSVReader with a ',' as separator character and a '"' as
      quote character. The reader doesn't skip any header lines.


    **Parameters:**
    - ioreader - the reader to use.


---

### CSVStreamReader(Reader, String)
- CSVStreamReader(ioreader: [Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md), separator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new CSVReader with the specified separator character and a '"'
      as quote character. The reader doesn't skip any header lines.


    **Parameters:**
    - ioreader - the reader to use.
    - separator - a string, which represents the separator character.


---

### CSVStreamReader(Reader, String, String)
- CSVStreamReader(ioreader: [Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md), separator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quote: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new CSVReader with the specified separator character and the
      specified quote character. The reader doesn't skip any header lines.


    **Parameters:**
    - ioreader - the reader to use.
    - separator - a string, which represents the separator character.
    - quote - a string, which represents the quote character.


---

### CSVStreamReader(Reader, String, String, Number)
- CSVStreamReader(ioreader: [Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md), separator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quote: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), skip: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a new CSVReader. The separator character, the quote character and
      the number of header lines can be specified in the call.


    **Parameters:**
    - ioreader - the reader to use.
    - separator - a string, which represents the separator character.
    - quote - a string, which represents the quote character.
    - skip - the number of lines to skip at the beginning of the file.


---

## Method Details

### close()
- close(): void
  - : Closes the underlying reader.


---

### readAll()
- readAll(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list of lines representing the entire CSV file. Each line is a
      array of strings.
      
      
      Using this method on large feeds is inherently unsafe and may lead to an
      out-of-memory condition. Instead use method [readNext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamReader.md#readnext) and
      process entries line by line.


    **Returns:**
    - a list of lines representing the entire CSV file.


---

### readNext()
- readNext(): [String\[\]](TopLevel.String.md)
  - : Returns the next line from the input stream. The line is returned as an
      array of strings. The method returns null if the end of the stream is
      reached.


    **Returns:**
    - the next line from the input stream as an array of strings.


---

<!-- prettier-ignore-end -->

<!-- document id=1622a1dd2d8aaa1d90b07d1de14ca7ed648689d8a3175c23de0d5aa153e82770 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.CSVStreamWriter.md -->

<!-- prettier-ignore-start -->
# Class CSVStreamWriter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.CSVStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamWriter.md)

The class writes a CSV file.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CSVStreamWriter](#csvstreamwriterwriter)([Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)) | Create a new CSVStreamWriter with a ',' as separator and '"'  as quote character. |
| [CSVStreamWriter](#csvstreamwriterwriter-string)([Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Create a new CSVStreamWriter with the specified separator and '"'  as quote character. |
| [CSVStreamWriter](#csvstreamwriterwriter-string-string)([Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Create a new CSVStreamWriter with the specified separator and the  specified quote character. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamWriter.md#close)() | Closes the underlying writer. |
| [writeNext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamWriter.md#writenextstring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Write a single line to the CSV file. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### CSVStreamWriter(Writer)
- CSVStreamWriter(writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md))
  - : Create a new CSVStreamWriter with a ',' as separator and '"'
      as quote character.


    **Parameters:**
    - writer - the writer to use.


---

### CSVStreamWriter(Writer, String)
- CSVStreamWriter(writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md), separator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Create a new CSVStreamWriter with the specified separator and '"'
      as quote character.


    **Parameters:**
    - writer - the writer to use.
    - separator - the separator to use.


---

### CSVStreamWriter(Writer, String, String)
- CSVStreamWriter(writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md), separator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quote: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Create a new CSVStreamWriter with the specified separator and the
      specified quote character.


    **Parameters:**
    - writer - the writer to use.
    - separator - the separator to use.
    - quote - the quote to use.


---

## Method Details

### close()
- close(): void
  - : Closes the underlying writer.


---

### writeNext(String...)
- writeNext(line: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Write a single line to the CSV file.

    **Parameters:**
    - line - an array of strings.


---

<!-- prettier-ignore-end -->

<!-- document id=890501e2bb29d6153e86a42a795e47f539fad0ce7ab70d5fb67d0901318c5cb6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Currency.md -->

<!-- prettier-ignore-start -->
# Class Currency

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md)

Represents a currency supported by the system.


## Property Summary

| Property | Description |
| --- | --- |
| [currencyCode](#currencycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the ISO 4217 mnemonic currency code of this currency. |
| [defaultFractionDigits](#defaultfractiondigits): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Gets the default number of fraction digits used with this currency. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets a long name for this currency. |
| [symbol](#symbol): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the symbol of this currency. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getCurrency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md#getcurrencystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a `Currency` instance for the given currency code,  or `null` if there is no such currency. |
| [getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md#getcurrencycode)() | Gets the ISO 4217 mnemonic currency code of this currency. |
| [getDefaultFractionDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md#getdefaultfractiondigits)() | Gets the default number of fraction digits used with this currency. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md#getname)() | Gets a long name for this currency. |
| [getSymbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md#getsymbol)() | Gets the symbol of this currency. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md#tostring)() | Returns the ISO 4217 mnemonic currency code of this currency. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### currencyCode
- currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the ISO 4217 mnemonic currency code of this currency.


---

### defaultFractionDigits
- defaultFractionDigits: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Gets the default number of fraction digits used with this currency.
      For example, the default number of fraction digits for the Euro is 2,
      while for the Japanese Yen it's 0.



---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets a long name for this currency. e.g. "United States Dollar".
      The returned name is the one stored in the system for this currency.
      Currently only English names are available, but in the future
      this method may return a locale-specific name.



---

### symbol
- symbol: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the symbol of this currency. e.g. "$" for the US Dollar.


---

## Method Details

### getCurrency(String)
- static getCurrency(currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md)
  - : Returns a `Currency` instance for the given currency code,
      or `null` if there is no such currency.


    **Parameters:**
    - currencyCode - the ISO 4217 mnemonic code of the currency.

    **Returns:**
    - the `Currency` instance for the given currency code.


---

### getCurrencyCode()
- getCurrencyCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the ISO 4217 mnemonic currency code of this currency.

    **Returns:**
    - the ISO 4217 mnemonic currency code of this currency.


---

### getDefaultFractionDigits()
- getDefaultFractionDigits(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Gets the default number of fraction digits used with this currency.
      For example, the default number of fraction digits for the Euro is 2,
      while for the Japanese Yen it's 0.


    **Returns:**
    - the default number of fraction digits used with this currency.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets a long name for this currency. e.g. "United States Dollar".
      The returned name is the one stored in the system for this currency.
      Currently only English names are available, but in the future
      this method may return a locale-specific name.


    **Returns:**
    - a long name for this currency. e.g. "United States Dollar".


---

### getSymbol()
- getSymbol(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the symbol of this currency. e.g. "$" for the US Dollar.

    **Returns:**
    - the symbol of this currency.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ISO 4217 mnemonic currency code of this currency.

    **Returns:**
    - the ISO 4217 mnemonic currency code of this currency.


---

<!-- prettier-ignore-end -->

<!-- document id=51546329ff3e33b476e53436fc78ab86263e7188233f4eb9aab17bbec86e0fe5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.CustomAttributes.md -->

<!-- prettier-ignore-start -->
# Class CustomAttributes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)

This class is used together with other classes that contain custom attributes and is used to read and write these
attributes. The actual attributes are accessible as ECMA properties. The syntax for setting and retrieving the value
of a custom attribute depends upon the type of the attribute. An exception will be thrown, if the wrong syntax is
used to set an individual attribute.


The following script examples demonstrate how to work with custom attributes. Suppose we have an ExtensibleObject
named "eo" possessing attributes of all the different types supported by the Commerce Cloud Digital metadata system.
The following script snippet shows that setting single-valued attributes is simply a matter of using the assignment
operator and standard ECMA primitives and built-in types:




```
// attribute of value type 'Boolean'
eo.custom.bvalue = true;
var b : Boolean = eo.custom.bvalue;

// attribute of value type 'Integer'
eo.custom.ivalue = 10;
var i : Number = eo.custom.ivalue;

// attribute of value type 'Number'
eo.custom.dvalue = 99.99;
var d : Number = eo.custom.dvalue;

// attribute of value type 'String'
eo.custom.svalue = "String1";
var s : String = eo.custom.svalue;

// attribute of value type 'Email'
eo.custom.emailvalue = "email@demandware.com";
var e : String = eo.custom.emailvalue;

// attribute of value type 'Text'
eo.custom.tvalue = "laaaaaaaaaaaarge text";
var t : String = eo.custom.tvalue;

// attribute of value type 'Date'
eo.custom.dtvalue = new Date;
var date : Date = eo.custom.dtvalue;
```



**Retrieving multi-value attributes and working with Java-backed arrays**

Multi-value attributes return Java-backed arrays, which contain copies of the internal data. In contrast to native
JavaScript arrays, a Java-backed array behaves differently in the following ways:

- `Array.isArray( javaBackedArray )`will return `false`. If you want to do something based  on the value type, use `javaBackedArray instanceof Array`instead.
- Adding to or removing elements from a Java-backed array is not supported. You need to create a new native  JavaScript array based on the Java-backed array, e.g. with `Array.from( javaBackedArray )`and do the  modifications there.



```
var setofstring : Array = eo.custom.setofstringvalue;
if( Array.isArray( setofstring ) ) // returns false
{
  // this will never be reached, since setofstring is a Java-backed array and not a native JavaScript array
}
if( setofstring instanceof Array ) // returns true
{
  // this will be reached, since setofstring is a Java-backed array
}
```



**Updating multi-value attributes**

Retrieved data from a multi-value attribute returns a Java-backed array, which contains a copy of the internal data,
so changes made to the Java-backed array do not affect the multi-value attribute. To update the multi-value attribute
(e.g. adding a new element), it needs to be reassigned.


```
// retrieve a Java-backed array and convert it to a native JavaScript array
var setofstring : Array = eo.custom.setofstringvalue;
var newValue = Array.from( setofstring );

// add new element
newValue.append( "new element" );

// reassign the new array to the multi-value attribute to persist the change
eo.custom.setofstringvalue = newValue;
```


If you only want to change individual elements without appending or removing elements from the Java-backed array, you
may even modify it directly.


```
// retrieve a Java-backed array
var setofstring : Array = eo.custom.setofstringvalue;

// change individual element
setofstring[0] = "updated element";

// reassign the array to the multi-value attribute to persist the change
eo.custom.setofstringvalue = setofstring;
```



**Set-of attributes and enum-of attributes**

Set-of attributes and enum-of attributes are handled in a very similar manner. The chief difference is that enum-of
attributes are limited to a prescribed set of value definitions whereas set-of attributes are open-ended.
Furthermore, each value in an enum-of attribute has a value and a display name which affects the retrieval logic.




```
// attribute of value type 'Set of String'
// set the attribute value only if it hasn't been already set
if( !('setofstringvalue' in eo.custom) )
{
    eo.custom.setofstringvalue = new Array("abc","def","ghi");
}

// returns an Array of String instances
var setofstring : Array = eo.custom.setofstringvalue;
var s1 : String = setofstring[0];
var s2 : String = setofstring[1];
var s3 : String = setofstring[2];

// attribute of value type 'Enum of Integer' with multi-value handling
eo.custom.enumofintmultivalue = new Array(1, 2, 3);

// returns an Array of EnumValue instances
var enumofintmulti : Array = eo.custom.enumofintmultivalue;
var value1 : Number = enumofintmulti[0].getValue();
var displayvalue1 : String = enumofintmulti[0].getDisplayValue();
var value2 : Number = enumofintmulti[1].getValue();
var displayvalue2 : String = enumofintmulti[1].getDisplayValue();
var value3 : Number = enumofintmulti[2].getValue();
var displayvalue3 : String = enumofintmulti[2].getDisplayValue();
```



For further details on the Commerce Cloud Digital attribute system, see the core Commerce Cloud Digital
documentation.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=1923ff52016c4a2e308d74084f2cf84202ccec310723ea45a318abdebe2469a7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.CustomEditor.md -->

<!-- prettier-ignore-start -->
# Class CustomEditor

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md)

This class represents a custom editor for component attributes of type `custom`. It is instantiated
by Page Designer and is subsequently used there for editing of such attributes by the merchant in a visual manner.
It therefore serves the Page Designer with all information required by such UI. What exactly
this information will be is up to the developer of the respective custom editor UI, i.e. depends on the respective
json and js files written for both the attribute definition as well as the custom editor type. Currently a configuration can be
served (basically values passed to Page Designer so that it can bootstrap the custom editor UI on the client side).
Furthermore resources can be served, which are URLs to scripts and styles required by the same UI (you will
likely require your own Javascript and CSS there).


You can access the aforementioned configuration as provided through the editor definition of the respective attribute
definition, which you can also adjust in the `init` function (see corresponding js file of your custom editor
type) that is called during initialization of the custom editor, i.e. right before it is passed to the Page Designer UI.
The same applies for the script and style resources which you specified as part of your custom editor type and which you
can refine with the `init` function as needed.



## Property Summary

| Property | Description |
| --- | --- |
| [configuration](#configuration): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the configuration of the custom editor. |
| [dependencies](#dependencies): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | <p>  Returns the dependencies to other custom editors, e.g. |
| [resources](#resources): [CustomEditorResources](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditorResources.md) `(read-only)` | Returns the resources of the custom editor. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md#getconfiguration)() | Returns the configuration of the custom editor. |
| [getDependencies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md#getdependencies)() | <p>  Returns the dependencies to other custom editors, e.g. |
| [getResources](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md#getresources)() | Returns the resources of the custom editor. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### configuration
- configuration: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the configuration of the custom editor. This is initialized with the values as provided
      through the editor definition of the respective attribute definition of type `custom`.
      Be aware that this configuration will have to be serializable to JSON itself as it will be passed
      to Page Designer for processing in the UI. So you must not add any values in this map that are not
      properly serializable. Do not use complex DWScript classes that do not support JSON serialization
      like for instance [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md).



---

### dependencies
- dependencies: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : 
      
      Returns the dependencies to other custom editors, e.g. used as breakout elements. You can use
      this mapping to add more custom editor dependencies as needed. For this purpose you want to create
      a [CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md) instance via [PageMgr.getCustomEditor(String, Map)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getcustomeditorstring-map)) and then add it
      to the dependencies mapping with an ID of your choice. In the client side logic of Page Designer
      you will then be able to access these dependencies again by using the corresponding ID.
      
      
      
      
      This is especially helpful if your custom editor for an attribute requires to open a breakout panel,
      e.g. for a separate picker required by your custom editor. This picker could be another custom editor,
      i.e. the one you declare as dependency here.



---

### resources
- resources: [CustomEditorResources](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditorResources.md) `(read-only)`
  - : Returns the resources of the custom editor. This is initialized with the values as specified
      by the custom editor type json (see the respective styles and scripts section).



---

## Method Details

### getConfiguration()
- getConfiguration(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the configuration of the custom editor. This is initialized with the values as provided
      through the editor definition of the respective attribute definition of type `custom`.
      Be aware that this configuration will have to be serializable to JSON itself as it will be passed
      to Page Designer for processing in the UI. So you must not add any values in this map that are not
      properly serializable. Do not use complex DWScript classes that do not support JSON serialization
      like for instance [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md).


    **Returns:**
    - the configuration of the custom editor


---

### getDependencies()
- getDependencies(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : 
      
      Returns the dependencies to other custom editors, e.g. used as breakout elements. You can use
      this mapping to add more custom editor dependencies as needed. For this purpose you want to create
      a [CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md) instance via [PageMgr.getCustomEditor(String, Map)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getcustomeditorstring-map)) and then add it
      to the dependencies mapping with an ID of your choice. In the client side logic of Page Designer
      you will then be able to access these dependencies again by using the corresponding ID.
      
      
      
      
      This is especially helpful if your custom editor for an attribute requires to open a breakout panel,
      e.g. for a separate picker required by your custom editor. This picker could be another custom editor,
      i.e. the one you declare as dependency here.


    **Returns:**
    - an ID to [CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md) mapping


---

### getResources()
- getResources(): [CustomEditorResources](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditorResources.md)
  - : Returns the resources of the custom editor. This is initialized with the values as specified
      by the custom editor type json (see the respective styles and scripts section).


    **Returns:**
    - the custom editor resources, will never be `null`


---

<!-- prettier-ignore-end -->

<!-- document id=f0cfff92966cc0c52b6ea799393e2015c45bbf57ec943dbaa69f586eb0637144 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.CustomEditorResources.md -->

<!-- prettier-ignore-start -->
# Class CustomEditorResources

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.CustomEditorResources](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditorResources.md)

This class represents the resources of a custom editor, i.e. URLs to scripts and styles which are required for
client side functionality in Page Designer in context of the corresponding custom attribute UI. These resources
are initially specified as part of your custom editor type (i.e. the respective json file). If needed you can
revise and refine them as part of the `init` function that is called during initialization of the
[CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md), i.e. is subject to your implementation of the respective custom editor type js file.


**See Also:**
- [CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md)


## Property Summary

| Property | Description |
| --- | --- |
| [scripts](#scripts): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns the specified script resource URLs. |
| [styles](#styles): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns the specified style URLs. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getScripts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditorResources.md#getscripts)() | Returns the specified script resource URLs. |
| [getStyles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditorResources.md#getstyles)() | Returns the specified style URLs. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### scripts
- scripts: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns the specified script resource URLs. You can further modify this list
      at runtime of your `init` function to add more required scripts.
      Absolute URLs will be retained, relative paths will be resolved to absolute
      ones based on the cartridge path for static resources (e.g. similar to
      what [URLUtils.httpStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring) or
      [URLUtils.httpsStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring)) does.



---

### styles
- styles: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns the specified style URLs. You can further modify this list
      at runtime of your `init` function to add more required styles.
      Absolute URLs will be retained, relative paths will be resolved to absolute
      ones based on the cartridge path for static resources (e.g. similar to
      what [URLUtils.httpStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring) or
      [URLUtils.httpsStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring)) does.



---

## Method Details

### getScripts()
- getScripts(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the specified script resource URLs. You can further modify this list
      at runtime of your `init` function to add more required scripts.
      Absolute URLs will be retained, relative paths will be resolved to absolute
      ones based on the cartridge path for static resources (e.g. similar to
      what [URLUtils.httpStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring) or
      [URLUtils.httpsStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring)) does.


    **Returns:**
    - the script resources, will never be `null`


---

### getStyles()
- getStyles(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the specified style URLs. You can further modify this list
      at runtime of your `init` function to add more required styles.
      Absolute URLs will be retained, relative paths will be resolved to absolute
      ones based on the cartridge path for static resources (e.g. similar to
      what [URLUtils.httpStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring) or
      [URLUtils.httpsStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring)) does.


    **Returns:**
    - the style resources, will never be `null`


---

<!-- prettier-ignore-end -->

<!-- document id=fc43e3d356361929f6c4e0294da5656f2e4efa6ab8f7174020f16aa60a65edf2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.Customer.md -->

<!-- prettier-ignore-start -->
# Class Customer

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)

Represents a customer.


## Property Summary

| Property | Description |
| --- | --- |
| [CDPData](#cdpdata): [CustomerCDPData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerCDPData.md) `(read-only)` | Returns the Salesforce CDP (Customer Data Platform) data for this customer. |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique, system generated ID of the customer. |
| [activeData](#activedata): [CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md) `(read-only)` | Returns the active data for this customer. |
| [addressBook](#addressbook): [AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md) `(read-only)` | Returns the address book for the profile of this customer,  or `null` if this customer has no profile, such as for an  anonymous customer. |
| [anonymous](#anonymous): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the customer is anonymous. |
| [authenticated](#authenticated): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the customer is authenticated. |
| [customerGroups](#customergroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the customer groups this customer is member of. |
| [externalProfiles](#externalprofiles): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of any external profiles the customer may have |
| [externallyAuthenticated](#externallyauthenticated): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the customer is externally authenticated. |
| [globalPartyID](#globalpartyid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Global Party ID for the customer, if there is one. |
| [note](#note): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the note for this customer, or `null` if this customer has no note, such as for an anonymous  customer or when note has 0 length. |
| [orderHistory](#orderhistory): [OrderHistory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md) `(read-only)` | Returns the customer order history. |
| [profile](#profile): [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md) `(read-only)` | Returns the customer profile. |
| [registered](#registered): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the customer is registered. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#createexternalprofilestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates an externalProfile and attaches it to the list of external profiles for the customer |
| [getActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getactivedata)() | Returns the active data for this customer. |
| [getAddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getaddressbook)() | Returns the address book for the profile of this customer,  or `null` if this customer has no profile, such as for an  anonymous customer. |
| [getCDPData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getcdpdata)() | Returns the Salesforce CDP (Customer Data Platform) data for this customer. |
| [getCustomerGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getcustomergroups)() | Returns the customer groups this customer is member of. |
| [getExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofilestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | A convenience method for finding an external profile among the customer's external profiles collection |
| [getExternalProfiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getexternalprofiles)() | Returns a collection of any external profiles the customer may have |
| [getGlobalPartyID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getglobalpartyid)() | Returns the Global Party ID for the customer, if there is one. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getid)() | Returns the unique, system generated ID of the customer. |
| [getNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getnote)() | Returns the note for this customer, or `null` if this customer has no note, such as for an anonymous  customer or when note has 0 length. |
| [getOrderHistory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getorderhistory)() | Returns the customer order history. |
| [getProductLists](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getproductlistsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the product lists of the specified type. |
| [getProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#getprofile)() | Returns the customer profile. |
| [isAnonymous](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#isanonymous)() | Identifies if the customer is anonymous. |
| [isAuthenticated](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#isauthenticated)() | Identifies if the customer is authenticated. |
| [isExternallyAuthenticated](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#isexternallyauthenticated)() | Identifies if the customer is externally authenticated. |
| [isMemberOfAnyCustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#ismemberofanycustomergroupstring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns true if there exist [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md) for all of the given IDs and the customer is member of at least one of that groups. |
| [isMemberOfCustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#ismemberofcustomergroupcustomergroup)([CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md)) | Returns true if the customer is member of the specified  [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md). |
| [isMemberOfCustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#ismemberofcustomergroupstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns true if there is a [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md) with such an ID and the customer is member of that group. |
| [isMemberOfCustomerGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#ismemberofcustomergroupsstring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns true if there exist [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md) for all of the given IDs and the customer is member of all that groups. |
| [isRegistered](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#isregistered)() | Identifies if the customer is registered. |
| [removeExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#removeexternalprofileexternalprofile)([ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)) | Removes an external profile from the customer |
| [setNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md#setnotestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the note for this customer. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### CDPData
- CDPData: [CustomerCDPData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerCDPData.md) `(read-only)`
  - : Returns the Salesforce CDP (Customer Data Platform) data for this customer.


---

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique, system generated ID of the customer.


---

### activeData
- activeData: [CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md) `(read-only)`
  - : Returns the active data for this customer.


---

### addressBook
- addressBook: [AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md) `(read-only)`
  - : Returns the address book for the profile of this customer,
      or `null` if this customer has no profile, such as for an
      anonymous customer.



---

### anonymous
- anonymous: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the customer is anonymous. An anonymous
      customer is the opposite of a registered customer.



---

### authenticated
- authenticated: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the customer is authenticated. This method checks whether
      this customer is the customer associated with the session and than checks
      whether the session in an authenticated state.
      
      Note: The pipeline debugger will always show 'false' for this value
      regardless of whether the customer is authenticated or not.



---

### customerGroups
- customerGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the customer groups this customer is member of.
      
      - Result contains static customer groups in storefront and job session
      - Result contains dynamic customer groups in storefront  and job session.  Dynamic customer groups referring session or request data are not available  when processing the customer in a job session, or when this customer is not the customer assigned to the current session.  
      - Result contains system groups 'Everyone', 'Unregistered', 'Registered' for all customers in storefront and job sessions



---

### externalProfiles
- externalProfiles: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of any external profiles the customer may have


---

### externallyAuthenticated
- externallyAuthenticated: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the customer is externally authenticated. An externally
      authenticated customer does not have the password stored in our system
      but logs in through an external OAuth provider (Google, Facebook, LinkedIn, etc.)



---

### globalPartyID
- globalPartyID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Global Party ID for the customer, if there is one.
      Global Party ID is created by Customer 360 and identifies a person across multiple systems.



---

### note
- note: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the note for this customer, or `null` if this customer has no note, such as for an anonymous
      customer or when note has 0 length.



---

### orderHistory
- orderHistory: [OrderHistory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md) `(read-only)`
  - : Returns the customer order history.


---

### profile
- profile: [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md) `(read-only)`
  - : Returns the customer profile.


---

### registered
- registered: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the customer is registered. A registered customer
      may or may not be authenticated. This method checks whether
      the user has a profile.



---

## Method Details

### createExternalProfile(String, String)
- createExternalProfile(authenticationProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), externalId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
  - : Creates an externalProfile and attaches it to the list of external profiles for the customer

    **Parameters:**
    - authenticationProviderId - the authenticationProviderId for the externalProfile
    - externalId - the externalId for the external Profile

    **Returns:**
    - the new externalProfile


---

### getActiveData()
- getActiveData(): [CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md)
  - : Returns the active data for this customer.

    **Returns:**
    - the active data for this customer.


---

### getAddressBook()
- getAddressBook(): [AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md)
  - : Returns the address book for the profile of this customer,
      or `null` if this customer has no profile, such as for an
      anonymous customer.



---

### getCDPData()
- getCDPData(): [CustomerCDPData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerCDPData.md)
  - : Returns the Salesforce CDP (Customer Data Platform) data for this customer.

    **Returns:**
    - the Salesforce CDP data for this customer.


---

### getCustomerGroups()
- getCustomerGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the customer groups this customer is member of.
      
      - Result contains static customer groups in storefront and job session
      - Result contains dynamic customer groups in storefront  and job session.  Dynamic customer groups referring session or request data are not available  when processing the customer in a job session, or when this customer is not the customer assigned to the current session.  
      - Result contains system groups 'Everyone', 'Unregistered', 'Registered' for all customers in storefront and job sessions


    **Returns:**
    - Collection of customer groups of this customer


---

### getExternalProfile(String, String)
- getExternalProfile(authenticationProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), externalId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)
  - : A convenience method for finding an external profile among the customer's external profiles collection

    **Parameters:**
    - authenticationProviderId - the authenticationProviderId to look for
    - externalId - the externalId to look for

    **Returns:**
    - the externalProfile found among the customer's external profile or null if not found


---

### getExternalProfiles()
- getExternalProfiles(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of any external profiles the customer may have

    **Returns:**
    - a collection of any external profiles the customer may have


---

### getGlobalPartyID()
- getGlobalPartyID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Global Party ID for the customer, if there is one.
      Global Party ID is created by Customer 360 and identifies a person across multiple systems.


    **Returns:**
    - The global party ID


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique, system generated ID of the customer.

    **Returns:**
    - the ID of the customer.


---

### getNote()
- getNote(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the note for this customer, or `null` if this customer has no note, such as for an anonymous
      customer or when note has 0 length.


    **Returns:**
    - the note for this customer.


---

### getOrderHistory()
- getOrderHistory(): [OrderHistory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md)
  - : Returns the customer order history.

    **Returns:**
    - the customer order history.


---

### getProductLists(Number)
- getProductLists(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the product lists of the specified type.

    **Parameters:**
    - type - the type of product lists to return.

    **Returns:**
    - the product lists of the specified type.

    **See Also:**
    - [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)


---

### getProfile()
- getProfile(): [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md)
  - : Returns the customer profile.

    **Returns:**
    - the customer profile.


---

### isAnonymous()
- isAnonymous(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the customer is anonymous. An anonymous
      customer is the opposite of a registered customer.


    **Returns:**
    - true if the customer is anonymous, false otherwise.
      
      
      **Note:** this method handles sensitive security-related data.
      Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



---

### isAuthenticated()
- isAuthenticated(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the customer is authenticated. This method checks whether
      this customer is the customer associated with the session and than checks
      whether the session in an authenticated state.
      
      Note: The pipeline debugger will always show 'false' for this value
      regardless of whether the customer is authenticated or not.


    **Returns:**
    - true if the customer is authenticated, false otherwise.


---

### isExternallyAuthenticated()
- isExternallyAuthenticated(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the customer is externally authenticated. An externally
      authenticated customer does not have the password stored in our system
      but logs in through an external OAuth provider (Google, Facebook, LinkedIn, etc.)


    **Returns:**
    - true if the customer is externally authenticated, false otherwise.
      
      
      **Note:** this method handles sensitive security-related data.
      Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



---

### isMemberOfAnyCustomerGroup(String...)
- isMemberOfAnyCustomerGroup(groupIDs: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if there exist [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md) for all of the given IDs and the customer is member of at least one of that groups.

    **Parameters:**
    - groupIDs - A list of unique semantic customer group IDs.

    **Returns:**
    - True if customer groups exist for the given IDs and the customer is member of at least one of that existing groups.
      False if none of customer groups exist or if the customer is not a member of any of that existing groups.



---

### isMemberOfCustomerGroup(CustomerGroup)
- isMemberOfCustomerGroup(group: [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the customer is member of the specified
      [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md).


    **Parameters:**
    - group - Customer group

    **Returns:**
    - True if customer is member of the group, otherwise false.


---

### isMemberOfCustomerGroup(String)
- isMemberOfCustomerGroup(groupID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if there is a [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md) with such an ID and the customer is member of that group.

    **Parameters:**
    - groupID - The unique semantic customer group ID.

    **Returns:**
    - True if a customer group with such an ID exist and the customer is member of that group.
      False if no such customer group exist or, if the group exist, the customer is not member of that group.



---

### isMemberOfCustomerGroups(String...)
- isMemberOfCustomerGroups(groupIDs: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if there exist [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md) for all of the given IDs and the customer is member of all that groups.

    **Parameters:**
    - groupIDs - A list of unique semantic customer group IDs.

    **Returns:**
    - True if customer groups exist for all of the given IDs and the customer is member of all that groups.
      False if there is at least one ID for which no customer group exist or, if all groups exist, the customer is not member of all that groups.



---

### isRegistered()
- isRegistered(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the customer is registered. A registered customer
      may or may not be authenticated. This method checks whether
      the user has a profile.


    **Returns:**
    - true if the customer is registered, false otherwise.


---

### removeExternalProfile(ExternalProfile)
- removeExternalProfile(externalProfile: [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)): void
  - : Removes an external profile from the customer

    **Parameters:**
    - externalProfile - the externalProfile to be removed


---

### setNote(String)
- setNote(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the note for this customer. This is a no-op for an anonymous customer.

    **Parameters:**
    - aValue - the value of the note


---

<!-- prettier-ignore-end -->

<!-- document id=41cb9d6a6268eff852e02977b082399223396ab113d2c516f56252b07c8f434a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerActiveData.md -->

<!-- prettier-ignore-start -->
# Class CustomerActiveData

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.object.ActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md)
        - [dw.customer.CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md)

Represents the active data for a [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) in Commerce Cloud Digital.


**Note:** this class allows access to sensitive personal and private information.
Pay attention to appropriate legal and regulatory requirements when developing.



## Property Summary

| Property | Description |
| --- | --- |
| [avgOrderValue](#avgordervalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average order value of the customer, or `null`  if none has been set or the value is no longer valid. |
| [discountValueWithCoupon](#discountvaluewithcoupon): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the discount value resulting from coupons, that has been applied  to orders of the customer, or `null` if none has been set or  the value is no longer valid. |
| [discountValueWithoutCoupon](#discountvaluewithoutcoupon): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the discount value resulting from promotions other than coupons,  that has been applied to orders of the customer, or `null`  if none has been set or the value is no longer valid. |
| [giftOrders](#giftorders): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of orders for the Customer that contained at least  one product unit marked as a gift, or `null` if none has been  set or the value is no longer valid. |
| [giftUnits](#giftunits): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of product units in orders for the customer  that were marked as a gift, or `null` if none has been set  or the value is no longer valid. |
| [lastOrderDate](#lastorderdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date of the last order for the customer, or `null`  if there are no orders for the customer. |
| [orderValue](#ordervalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the lifetime order value of the customer, or `null`  if none has been set or the value is no longer valid. |
| [orderValueMonth](#ordervaluemonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the order value of the customer, over the most recent 30 days,  or `null` if none has been set or the value is no longer valid. |
| [orders](#orders): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the orders of the customer, or `null` if none  has been set or the value is no longer valid. |
| [productMastersOrdered](#productmastersordered): [String\[\]](TopLevel.String.md) `(read-only)` | Returns an array containing the master product SKUs of variation products  in orders for the customer, or an empty collection if no SKUs have been  set or the collection of SKUs is no longer valid. |
| [productsAbandonedMonth](#productsabandonedmonth): [String\[\]](TopLevel.String.md) `(read-only)` | Returns an array containing the SKUs of products in baskets abandoned  by the customer in the last 30 days, or an empty collection if no SKUs  have been set or the collection is no longer valid. |
| [productsOrdered](#productsordered): [String\[\]](TopLevel.String.md) `(read-only)` | Returns an array containing the SKUs of products in orders  for the customer, or an empty collection if no SKUs have been set or the  collection of SKUs is no longer valid. |
| [productsViewedMonth](#productsviewedmonth): [String\[\]](TopLevel.String.md) `(read-only)` | Returns an array containing the SKUs of products viewed by the  customer in the last 30 days, or an empty collection if no SKUs have been  set or the collection is no longer valid. |
| [returnValue](#returnvalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the returned revenue of the customer, or `null`  if none has been set or the value is no longer valid. |
| [returns](#returns): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of returns of the customer, or `null`  if none has been set or the value is no longer valid. |
| [sourceCodeOrders](#sourcecodeorders): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of orders for the customer where a source code was  in effect, or `null` if none has been set or the value  is no longer valid. |
| [topCategoriesOrdered](#topcategoriesordered): [String\[\]](TopLevel.String.md) `(read-only)` | Returns an array containing the IDs of up to the top 20 categories for  customer orders, or an empty list if no categories have been set or the  list of categories is no longer valid. |
| [visitsMonth](#visitsmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the visits of the customer, over the most recent 30 days,  or `null` if none has been set or the value  is no longer valid. |
| [visitsWeek](#visitsweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the visits of the customer, over the most recent 7 days,  or `null` if none has been set or the value  is no longer valid. |
| [visitsYear](#visitsyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the visits of the customer, over the most recent 365 days,  or `null` if none has been set or the value  is no longer valid. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAvgOrderValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getavgordervalue)() | Returns the average order value of the customer, or `null`  if none has been set or the value is no longer valid. |
| [getDiscountValueWithCoupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getdiscountvaluewithcoupon)() | Returns the discount value resulting from coupons, that has been applied  to orders of the customer, or `null` if none has been set or  the value is no longer valid. |
| [getDiscountValueWithoutCoupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getdiscountvaluewithoutcoupon)() | Returns the discount value resulting from promotions other than coupons,  that has been applied to orders of the customer, or `null`  if none has been set or the value is no longer valid. |
| [getGiftOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getgiftorders)() | Returns the number of orders for the Customer that contained at least  one product unit marked as a gift, or `null` if none has been  set or the value is no longer valid. |
| [getGiftUnits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getgiftunits)() | Returns the number of product units in orders for the customer  that were marked as a gift, or `null` if none has been set  or the value is no longer valid. |
| [getLastOrderDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getlastorderdate)() | Returns the date of the last order for the customer, or `null`  if there are no orders for the customer. |
| [getOrderValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getordervalue)() | Returns the lifetime order value of the customer, or `null`  if none has been set or the value is no longer valid. |
| [getOrderValueMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getordervaluemonth)() | Returns the order value of the customer, over the most recent 30 days,  or `null` if none has been set or the value is no longer valid. |
| [getOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getorders)() | Returns the orders of the customer, or `null` if none  has been set or the value is no longer valid. |
| [getProductMastersOrdered](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getproductmastersordered)() | Returns an array containing the master product SKUs of variation products  in orders for the customer, or an empty collection if no SKUs have been  set or the collection of SKUs is no longer valid. |
| [getProductsAbandonedMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getproductsabandonedmonth)() | Returns an array containing the SKUs of products in baskets abandoned  by the customer in the last 30 days, or an empty collection if no SKUs  have been set or the collection is no longer valid. |
| [getProductsOrdered](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getproductsordered)() | Returns an array containing the SKUs of products in orders  for the customer, or an empty collection if no SKUs have been set or the  collection of SKUs is no longer valid. |
| [getProductsViewedMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getproductsviewedmonth)() | Returns an array containing the SKUs of products viewed by the  customer in the last 30 days, or an empty collection if no SKUs have been  set or the collection is no longer valid. |
| [getReturnValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getreturnvalue)() | Returns the returned revenue of the customer, or `null`  if none has been set or the value is no longer valid. |
| [getReturns](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getreturns)() | Returns the number of returns of the customer, or `null`  if none has been set or the value is no longer valid. |
| [getSourceCodeOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getsourcecodeorders)() | Returns the number of orders for the customer where a source code was  in effect, or `null` if none has been set or the value  is no longer valid. |
| [getTopCategoriesOrdered](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#gettopcategoriesordered)() | Returns an array containing the IDs of up to the top 20 categories for  customer orders, or an empty list if no categories have been set or the  list of categories is no longer valid. |
| [getVisitsMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getvisitsmonth)() | Returns the visits of the customer, over the most recent 30 days,  or `null` if none has been set or the value  is no longer valid. |
| [getVisitsWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getvisitsweek)() | Returns the visits of the customer, over the most recent 7 days,  or `null` if none has been set or the value  is no longer valid. |
| [getVisitsYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md#getvisitsyear)() | Returns the visits of the customer, over the most recent 365 days,  or `null` if none has been set or the value  is no longer valid. |

### Methods inherited from class ActiveData

[getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md#getcustom), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md#isempty)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### avgOrderValue
- avgOrderValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average order value of the customer, or `null`
      if none has been set or the value is no longer valid.



---

### discountValueWithCoupon
- discountValueWithCoupon: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the discount value resulting from coupons, that has been applied
      to orders of the customer, or `null` if none has been set or
      the value is no longer valid.



---

### discountValueWithoutCoupon
- discountValueWithoutCoupon: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the discount value resulting from promotions other than coupons,
      that has been applied to orders of the customer, or `null`
      if none has been set or the value is no longer valid.



---

### giftOrders
- giftOrders: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of orders for the Customer that contained at least
      one product unit marked as a gift, or `null` if none has been
      set or the value is no longer valid.



---

### giftUnits
- giftUnits: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of product units in orders for the customer
      that were marked as a gift, or `null` if none has been set
      or the value is no longer valid.



---

### lastOrderDate
- lastOrderDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date of the last order for the customer, or `null`
      if there are no orders for the customer.



---

### orderValue
- orderValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the lifetime order value of the customer, or `null`
      if none has been set or the value is no longer valid.



---

### orderValueMonth
- orderValueMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the order value of the customer, over the most recent 30 days,
      or `null` if none has been set or the value is no longer valid.



---

### orders
- orders: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the orders of the customer, or `null` if none
      has been set or the value is no longer valid.



---

### productMastersOrdered
- productMastersOrdered: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns an array containing the master product SKUs of variation products
      in orders for the customer, or an empty collection if no SKUs have been
      set or the collection of SKUs is no longer valid. There is no specific
      limit on the number of SKUs that will be returned in the collection, but
      there is also no guarantee that it will contain the SKUs for all products
      ordered by the customer.



---

### productsAbandonedMonth
- productsAbandonedMonth: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns an array containing the SKUs of products in baskets abandoned
      by the customer in the last 30 days, or an empty collection if no SKUs
      have been set or the collection is no longer valid.  There is no specific
      limit on the number of SKUs that will be returned in the collection, but
      there is also no guarantee that it will contain the SKUs for all products
      in baskets abandoned by the customer.



---

### productsOrdered
- productsOrdered: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns an array containing the SKUs of products in orders
      for the customer, or an empty collection if no SKUs have been set or the
      collection of SKUs is no longer valid.  There is no specific limit on the
      number of SKUs that will be returned in the collection, but there is also
      no guarantee that it will contain the SKUs for all products ordered by
      the customer.



---

### productsViewedMonth
- productsViewedMonth: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns an array containing the SKUs of products viewed by the
      customer in the last 30 days, or an empty collection if no SKUs have been
      set or the collection is no longer valid.  There is no specific limit on
      the number of SKUs that will be returned in the collection, but there is
      also no guarantee that it will contain the SKUs for all products viewed
      by the customer.



---

### returnValue
- returnValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the returned revenue of the customer, or `null`
      if none has been set or the value is no longer valid.



---

### returns
- returns: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of returns of the customer, or `null`
      if none has been set or the value is no longer valid.



---

### sourceCodeOrders
- sourceCodeOrders: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of orders for the customer where a source code was
      in effect, or `null` if none has been set or the value
      is no longer valid.



---

### topCategoriesOrdered
- topCategoriesOrdered: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns an array containing the IDs of up to the top 20 categories for
      customer orders, or an empty list if no categories have been set or the
      list of categories is no longer valid. The top category is the one for
      which the most orders for the customer contained at least one product
      found in that category.



---

### visitsMonth
- visitsMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the visits of the customer, over the most recent 30 days,
      or `null` if none has been set or the value
      is no longer valid.



---

### visitsWeek
- visitsWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the visits of the customer, over the most recent 7 days,
      or `null` if none has been set or the value
      is no longer valid.



---

### visitsYear
- visitsYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the visits of the customer, over the most recent 365 days,
      or `null` if none has been set or the value
      is no longer valid.



---

## Method Details

### getAvgOrderValue()
- getAvgOrderValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average order value of the customer, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average order size.


---

### getDiscountValueWithCoupon()
- getDiscountValueWithCoupon(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the discount value resulting from coupons, that has been applied
      to orders of the customer, or `null` if none has been set or
      the value is no longer valid.


    **Returns:**
    - the discount value resulting from coupons.


---

### getDiscountValueWithoutCoupon()
- getDiscountValueWithoutCoupon(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the discount value resulting from promotions other than coupons,
      that has been applied to orders of the customer, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the discount value resulting from promotions other than coupons.


---

### getGiftOrders()
- getGiftOrders(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of orders for the Customer that contained at least
      one product unit marked as a gift, or `null` if none has been
      set or the value is no longer valid.


    **Returns:**
    - the number of gift orders.


---

### getGiftUnits()
- getGiftUnits(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of product units in orders for the customer
      that were marked as a gift, or `null` if none has been set
      or the value is no longer valid.


    **Returns:**
    - the number of gift product units.


---

### getLastOrderDate()
- getLastOrderDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date of the last order for the customer, or `null`
      if there are no orders for the customer.


    **Returns:**
    - the date of the last order for the customer.


---

### getOrderValue()
- getOrderValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the lifetime order value of the customer, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the lifetime value.


---

### getOrderValueMonth()
- getOrderValueMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the order value of the customer, over the most recent 30 days,
      or `null` if none has been set or the value is no longer valid.


    **Returns:**
    - the value over the last 30 days.


---

### getOrders()
- getOrders(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the orders of the customer, or `null` if none
      has been set or the value is no longer valid.


    **Returns:**
    - the orders.


---

### getProductMastersOrdered()
- getProductMastersOrdered(): [String\[\]](TopLevel.String.md)
  - : Returns an array containing the master product SKUs of variation products
      in orders for the customer, or an empty collection if no SKUs have been
      set or the collection of SKUs is no longer valid. There is no specific
      limit on the number of SKUs that will be returned in the collection, but
      there is also no guarantee that it will contain the SKUs for all products
      ordered by the customer.


    **Returns:**
    - a collection containing the master product SKUs of variation
              products that were ordered.



---

### getProductsAbandonedMonth()
- getProductsAbandonedMonth(): [String\[\]](TopLevel.String.md)
  - : Returns an array containing the SKUs of products in baskets abandoned
      by the customer in the last 30 days, or an empty collection if no SKUs
      have been set or the collection is no longer valid.  There is no specific
      limit on the number of SKUs that will be returned in the collection, but
      there is also no guarantee that it will contain the SKUs for all products
      in baskets abandoned by the customer.


    **Returns:**
    - a collection containing the SKUs of products that were abandoned.


---

### getProductsOrdered()
- getProductsOrdered(): [String\[\]](TopLevel.String.md)
  - : Returns an array containing the SKUs of products in orders
      for the customer, or an empty collection if no SKUs have been set or the
      collection of SKUs is no longer valid.  There is no specific limit on the
      number of SKUs that will be returned in the collection, but there is also
      no guarantee that it will contain the SKUs for all products ordered by
      the customer.


    **Returns:**
    - a collection containing the SKUs of products that were ordered.


---

### getProductsViewedMonth()
- getProductsViewedMonth(): [String\[\]](TopLevel.String.md)
  - : Returns an array containing the SKUs of products viewed by the
      customer in the last 30 days, or an empty collection if no SKUs have been
      set or the collection is no longer valid.  There is no specific limit on
      the number of SKUs that will be returned in the collection, but there is
      also no guarantee that it will contain the SKUs for all products viewed
      by the customer.


    **Returns:**
    - a collection containing the SKUs of products that were ordered.


---

### getReturnValue()
- getReturnValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the returned revenue of the customer, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the returned revenue.


---

### getReturns()
- getReturns(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of returns of the customer, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the returns.


---

### getSourceCodeOrders()
- getSourceCodeOrders(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of orders for the customer where a source code was
      in effect, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the number of orders with source codes in effect.


---

### getTopCategoriesOrdered()
- getTopCategoriesOrdered(): [String\[\]](TopLevel.String.md)
  - : Returns an array containing the IDs of up to the top 20 categories for
      customer orders, or an empty list if no categories have been set or the
      list of categories is no longer valid. The top category is the one for
      which the most orders for the customer contained at least one product
      found in that category.


    **Returns:**
    - a list containing the top 20 categories.


---

### getVisitsMonth()
- getVisitsMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the visits of the customer, over the most recent 30 days,
      or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the visits over the last 30 days.


---

### getVisitsWeek()
- getVisitsWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the visits of the customer, over the most recent 7 days,
      or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the visits over the last 7 days.


---

### getVisitsYear()
- getVisitsYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the visits of the customer, over the most recent 365 days,
      or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the visits over the last 365 days.


---

<!-- prettier-ignore-end -->

<!-- document id=0d499b47ef9e6bcdf3514ac6eb8e84468356c9a405264e043e9a3fb89faa10c7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerAddress.md -->

<!-- prettier-ignore-start -->
# Class CustomerAddress

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)

The Address class represents a customer's address.


**Note:** this class allows access to sensitive personal and private information.
Pay attention to appropriate legal and regulatory requirements.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the address. |
| [address1](#address1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's first address. |
| [address2](#address2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's second address value. |
| [city](#city): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's city. |
| [companyName](#companyname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's company name. |
| [countryCode](#countrycode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the customer's country code. |
| [firstName](#firstname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's first name. |
| [fullName](#fullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns a concatenation of the customer's first, middle,  and last names and its suffix. |
| [jobTitle](#jobtitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's job title. |
| [lastName](#lastname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's last name. |
| [phone](#phone): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's phone number. |
| [postBox](#postbox): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's post box. |
| [postalCode](#postalcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's postal code. |
| [salutation](#salutation): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's salutation. |
| [secondName](#secondname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's second name. |
| [stateCode](#statecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's state. |
| [suffix](#suffix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's suffix. |
| [suite](#suite): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's suite. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's title. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAddress1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getaddress1)() | Returns the customer's first address. |
| [getAddress2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getaddress2)() | Returns the customer's second address value. |
| [getCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getcity)() | Returns the customer's city. |
| [getCompanyName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getcompanyname)() | Returns the customer's company name. |
| [getCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getcountrycode)() | Returns the customer's country code. |
| [getFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getfirstname)() | Returns the customer's first name. |
| [getFullName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getfullname)() | Returns a concatenation of the customer's first, middle,  and last names and its suffix. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getid)() | Returns the name of the address. |
| [getJobTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getjobtitle)() | Returns the customer's job title. |
| [getLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getlastname)() | Returns the customer's last name. |
| [getPhone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getphone)() | Returns the customer's phone number. |
| [getPostBox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getpostbox)() | Returns the customer's post box. |
| [getPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getpostalcode)() | Returns the customer's postal code. |
| [getSalutation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getsalutation)() | Returns the customer's salutation. |
| [getSecondName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getsecondname)() | Returns the customer's second name. |
| [getStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getstatecode)() | Returns the customer's state. |
| [getSuffix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getsuffix)() | Returns the customer's suffix. |
| [getSuite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#getsuite)() | Returns the customer's suite. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#gettitle)() | Returns the customer's title. |
| [isEquivalentAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#isequivalentaddressobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if the specified address is equivalent to  this address. |
| [setAddress1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setaddress1string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value of the customer's first address. |
| [setAddress2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setaddress2string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's second address value. |
| [setCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setcitystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's city. |
| [setCompanyName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setcompanynamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's company name. |
| [setCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setcountrycodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's country code. |
| [setFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setfirstnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's first name. |
| [setID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the address name. |
| [setJobTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setjobtitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's job title. |
| [setLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setlastnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's last name. |
| [setPhone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setphonestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's phone number. |
| [setPostBox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setpostboxstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's post box. |
| [setPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setpostalcodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's postal code. |
| ~~[setSaluation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setsaluationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the customer's salutation. |
| [setSalutation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setsalutationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's salutation. |
| [setSecondName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setsecondnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's second name. |
| [setStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setstatecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's state. |
| [setSuffix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setsuffixstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's suffix. |
| [setSuite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setsuitestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's suite. |
| [setTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#settitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's title. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the address.


---

### address1
- address1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first address.


---

### address2
- address2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second address value.


---

### city
- city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's city.


---

### companyName
- companyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's company name.


---

### countryCode
- countryCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the customer's country code. Commerce Cloud Digital supports two-character
      country codes per ISO 3166-1 alpha-2. See
      [http://www.iso.org/iso/country\_codes/iso\_3166-faqs/iso\_3166\_faqs\_general.htm](http://www.iso.org/iso/country\_codes/iso\_3166-faqs/iso\_3166\_faqs\_general.htm)
      for additional information.



---

### firstName
- firstName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first name.


---

### fullName
- fullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns a concatenation of the customer's first, middle,
      and last names and its suffix.



---

### jobTitle
- jobTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's job title.


---

### lastName
- lastName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's last name.


---

### phone
- phone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's phone number.


---

### postBox
- postBox: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's post box.


---

### postalCode
- postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's postal code.


---

### salutation
- salutation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's salutation.


---

### secondName
- secondName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second name.


---

### stateCode
- stateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's state.


---

### suffix
- suffix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suffix.


---

### suite
- suite: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suite.


---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's title.


---

## Method Details

### getAddress1()
- getAddress1(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first address.

    **Returns:**
    - the first address value.


---

### getAddress2()
- getAddress2(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second address value.

    **Returns:**
    - the value of the second address.


---

### getCity()
- getCity(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's city.

    **Returns:**
    - the customer's city.


---

### getCompanyName()
- getCompanyName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's company name.

    **Returns:**
    - the company name.


---

### getCountryCode()
- getCountryCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the customer's country code. Commerce Cloud Digital supports two-character
      country codes per ISO 3166-1 alpha-2. See
      [http://www.iso.org/iso/country\_codes/iso\_3166-faqs/iso\_3166\_faqs\_general.htm](http://www.iso.org/iso/country\_codes/iso\_3166-faqs/iso\_3166\_faqs\_general.htm)
      for additional information.


    **Returns:**
    - the two-digit country code.


---

### getFirstName()
- getFirstName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first name.

    **Returns:**
    - the customer first name.


---

### getFullName()
- getFullName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a concatenation of the customer's first, middle,
      and last names and its suffix.


    **Returns:**
    - a concatenation of the customer's first, middle,
      and last names and its suffix.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the address.

    **Returns:**
    - the address name.


---

### getJobTitle()
- getJobTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's job title.

    **Returns:**
    - the job title.


---

### getLastName()
- getLastName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's last name.

    **Returns:**
    - the last name.


---

### getPhone()
- getPhone(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's phone number.

    **Returns:**
    - the phone number.


---

### getPostBox()
- getPostBox(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's post box.

    **Returns:**
    - the post box.


---

### getPostalCode()
- getPostalCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's postal code.

    **Returns:**
    - the postal code.


---

### getSalutation()
- getSalutation(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's salutation.

    **Returns:**
    - the salutation.


---

### getSecondName()
- getSecondName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second name.

    **Returns:**
    - the second name.


---

### getStateCode()
- getStateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's state.

    **Returns:**
    - the state.


---

### getSuffix()
- getSuffix(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suffix.

    **Returns:**
    - the suffix.


---

### getSuite()
- getSuite(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suite.

    **Returns:**
    - the suite.


---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's title.

    **Returns:**
    - the title.


---

### isEquivalentAddress(Object)
- isEquivalentAddress(address: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the specified address is equivalent to
      this address. An equivalent address is an address whose
      core attributes contain the same values. The core attributes
      are:
      
      - address1
      - address2
      - city
      - companyName
      - countryCode
      - firstName
      - lastName
      - postalCode
      - postBox
      - stateCode


    **Parameters:**
    - address - the address to test.

    **Returns:**
    - true if the specified address is equivalent to
      this address, false otherwise.



---

### setAddress1(String)
- setAddress1(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value of the customer's first address.

    **Parameters:**
    - value - The value to set.


---

### setAddress2(String)
- setAddress2(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's second address value.

    **Parameters:**
    - value - The value to set.


---

### setCity(String)
- setCity(city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's city.

    **Parameters:**
    - city - the customer's city to set.


---

### setCompanyName(String)
- setCompanyName(companyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's company name.

    **Parameters:**
    - companyName - the name of the company.


---

### setCountryCode(String)
- setCountryCode(countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's country code. Commerce Cloud Digital supports two-character
      country codes per ISO 3166-1 alpha-2. See
      [http://www.iso.org/iso/country\_codes/iso\_3166-faqs/iso\_3166\_faqs\_general.htm](http://www.iso.org/iso/country\_codes/iso\_3166-faqs/iso\_3166\_faqs\_general.htm)
      for additional information.


    **Parameters:**
    - countryCode - the country code, must be no more than 2 characters or                     will be truncated.


---

### setFirstName(String)
- setFirstName(firstName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's first name.

    **Parameters:**
    - firstName - the customer's first  name to set.


---

### setID(String)
- setID(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the address name.

    **Parameters:**
    - value - the name to use.


---

### setJobTitle(String)
- setJobTitle(jobTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's job title.

    **Parameters:**
    - jobTitle - The jobTitle to set.


---

### setLastName(String)
- setLastName(lastName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's last name.

    **Parameters:**
    - lastName - The last name to set.


---

### setPhone(String)
- setPhone(phoneNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's phone number. The length is restricted to 32 characters.

    **Parameters:**
    - phoneNumber - The phone number to set.


---

### setPostBox(String)
- setPostBox(postBox: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's post box.

    **Parameters:**
    - postBox - The post box to set.


---

### setPostalCode(String)
- setPostalCode(postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's postal code.

    **Parameters:**
    - postalCode - The postal code to set.


---

### setSaluation(String)
- ~~setSaluation(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the customer's salutation.

    **Parameters:**
    - value - the salutation.

    **Deprecated:**
**warning:** Use [setSalutation(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md#setsalutationstring)

---

### setSalutation(String)
- setSalutation(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's salutation.

    **Parameters:**
    - value - the salutation.


---

### setSecondName(String)
- setSecondName(secondName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's second name.

    **Parameters:**
    - secondName - The second name to set.


---

### setStateCode(String)
- setStateCode(state: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's state.

    **Parameters:**
    - state - The state to set.


---

### setSuffix(String)
- setSuffix(suffix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's suffix.

    **Parameters:**
    - suffix - The suffix to set.


---

### setSuite(String)
- setSuite(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's suite. The length is restricted to 32 characters.

    **Parameters:**
    - value - the suite to set.


---

### setTitle(String)
- setTitle(title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's title.

    **Parameters:**
    - title - The title to set.


---

<!-- prettier-ignore-end -->

<!-- document id=1b3e9db1bba3eb96888379a9c3aea16516d2c29189e61411bc4ad8647734da0f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerCDPData.md -->

<!-- prettier-ignore-start -->
# Class CustomerCDPData

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.CustomerCDPData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerCDPData.md)

Represents the read-only Customer's Salesforce CDP (Customer Data Platform) data for a [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) in Commerce
Cloud. Please see Salesforce CDP enablement documentation



## Property Summary

| Property | Description |
| --- | --- |
| [empty](#empty): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Return true if the CDPData is empty (has no meaningful data) |
| [segments](#segments): [String\[\]](TopLevel.String.md) `(read-only)` | Returns an array containing the CDP segments for the customer, or an empty array if no segments found |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSegments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerCDPData.md#getsegments)() | Returns an array containing the CDP segments for the customer, or an empty array if no segments found |
| [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerCDPData.md#isempty)() | Return true if the CDPData is empty (has no meaningful data) |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### empty
- empty: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Return true if the CDPData is empty (has no meaningful data)


---

### segments
- segments: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns an array containing the CDP segments for the customer, or an empty array if no segments found


---

## Method Details

### getSegments()
- getSegments(): [String\[\]](TopLevel.String.md)
  - : Returns an array containing the CDP segments for the customer, or an empty array if no segments found

    **Returns:**
    - a collection containing the CDP segments for the customer


---

### isEmpty()
- isEmpty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Return true if the CDPData is empty (has no meaningful data)

    **Returns:**
    - true if CDPData is empty, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=883e1f121a5b5aa80fefade1872c5b00da1faa327b7ef5c88cf89047851ba042 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerContextMgr.md -->

<!-- prettier-ignore-start -->
# Class CustomerContextMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.CustomerContextMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerContextMgr.md)

Provides helper methods for managing customer context, such as the Effective Time for which the customer is shopping
at



## Property Summary

| Property | Description |
| --- | --- |
| [effectiveTime](#effectivetime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Get the effective time associated with the customer. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getEffectiveTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerContextMgr.md#geteffectivetime)() | Get the effective time associated with the customer. |
| static [setEffectiveTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerContextMgr.md#seteffectivetimedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Set the effective time for the customer. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### effectiveTime
- effectiveTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Get the effective time associated with the customer. By default, the effective time is null.


---

## Method Details

### getEffectiveTime()
- static getEffectiveTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Get the effective time associated with the customer. By default, the effective time is null.

    **Returns:**
    - effective time. When null is returned it means no effective time is associated with the customer


---

### setEffectiveTime(Date)
- static setEffectiveTime(effectiveTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Set the effective time for the customer. Null is allowed to remove effective time from the customer.

    **Parameters:**
    - effectiveTime - the effective time.


---

<!-- prettier-ignore-end -->

<!-- document id=54c55e7278a710046640f4133b82da19ea4f15ddcbb9e78792396961aaa96ba1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerGroup.md -->

<!-- prettier-ignore-start -->
# Class CustomerGroup

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md)

CustomerGroups provide a means to segment customers by various criteria. A
merchant can then provide different site experiences (e.g. promotions,
prices, sorting rules) to each customer segment. Customer groups can consist
of either an explicit list of customers or a business rule that dynamically
determines whether a customer is a member. The former type is called
"explicit" and the latter type is called "dynamic".


- **Explicit customer group:**Consists of an explicit list of  customers. Only registered customers can be member of such a group.  isRuleBased==false.
- **Dynamic customer group:**Memberships are evaluated by a business  rule that is attached to the customer group. Registered as well as anonymous  customers can be member of such a group. isRuleBased==true.



**Note:** this class might allow access to sensitive personal and private
information, depending on how you segment your customers and the names given to
your custoemer groups. Pay attention to appropriate legal and regulatory requirements
when developing with this data.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique ID of the customer group. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the value of the description of the customer group. |
| [ruleBased](#rulebased): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the group determines the membership of customers  based on rules. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [assignCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md#assigncustomercustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Assigns the specified customer to this group. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md#getdescription)() | Gets the value of the description of the customer group. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md#getid)() | Returns the unique ID of the customer group. |
| [isRuleBased](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md#isrulebased)() | Returns true if the group determines the membership of customers  based on rules. |
| [unassignCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md#unassigncustomercustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Unassigns the specified customer from this group. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique ID of the customer group.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the value of the description of the customer group.


---

### ruleBased
- ruleBased: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the group determines the membership of customers
      based on rules. Returns false if the group provides explicit assignement
      of customers.



---

## Method Details

### assignCustomer(Customer)
- assignCustomer(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): void
  - : Assigns the specified customer to this group. 
      
      The customer must be registered and the group must not be rule-based.


    **Parameters:**
    - customer - Registered customer, must not be null.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the value of the description of the customer group.

    **Returns:**
    - the description of the customer group


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique ID of the customer group.

    **Returns:**
    - The unique semantic ID of the customer group.


---

### isRuleBased()
- isRuleBased(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the group determines the membership of customers
      based on rules. Returns false if the group provides explicit assignement
      of customers.


    **Returns:**
    - `True`, if the customer group is rule based.


---

### unassignCustomer(Customer)
- unassignCustomer(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): void
  - : Unassigns the specified customer from this group. 
      
      The customer must be registered and the group must not be rule-based.


    **Parameters:**
    - customer - Registered customer, must not be null.


---

<!-- prettier-ignore-end -->

<!-- document id=d65ba84b2ebf9a6b28c10d86514acb2ecc597a6560a4ac45b90aa40c87eb3e03 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerList.md -->

<!-- prettier-ignore-start -->
# Class CustomerList

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.CustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md)

Object representing the collection of customers who are registered
for a given site. In Commerce Cloud Digital, every site has exactly
one assigned customer list but multiple sites may share a customer
list.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the ID of the customer list. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the optional description of the customer list. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md#getdescription)() | Get the optional description of the customer list. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md#getid)() | Get the ID of the customer list. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the ID of the customer list.  For customer lists that were created automatically
      for a given site, this is equal to the ID of the site itself.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the optional description of the customer list.


---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the optional description of the customer list.

    **Returns:**
    - The optional description of the list.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the ID of the customer list.  For customer lists that were created automatically
      for a given site, this is equal to the ID of the site itself.


    **Returns:**
    - The ID of the customer list.


---

<!-- prettier-ignore-end -->

<!-- document id=3dd7632579f5997cfe8a5dba7a6ca9cc1abde14fc44bcb1a2fd6c28f3b3b7710 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerMgr.md -->

<!-- prettier-ignore-start -->
# Class CustomerMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.CustomerMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md)

Provides helper methods for managing customers and customer
profiles.
**Note:** this class allows access to sensitive information through
operations that retrieve the Profile object.
Pay attention to appropriate legal and regulatory requirements related to this data.



## Property Summary

| Property | Description |
| --- | --- |
| [customerGroups](#customergroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the customer groups of the current site. |
| [passwordConstraints](#passwordconstraints): [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md) `(read-only)` | Returns an instance of [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md)  for the customer list assigned to the current site. |
| [registeredCustomerCount](#registeredcustomercount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of registered customers in the system. |
| [siteCustomerList](#sitecustomerlist): [CustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md) `(read-only)` | Returns the customer list of the current site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [authenticateCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#authenticatecustomerstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method authenticates a customer using the supplied login and password. |
| static [createCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#createcustomerstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new Customer using the supplied login, password. |
| static [createCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#createcustomerstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new Customer using the supplied login, password, and a customerNo. |
| static [createExternallyAuthenticatedCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#createexternallyauthenticatedcustomerstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Given an authentication provider Id and an external Id: creates a Customer record in the system if one does not  exist already for the same 'authenticationProviderId' and 'externalId' pair. |
| static [describeProfileType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#describeprofiletype)() | Returns the meta data for profiles. |
| static [getCustomerByCustomerNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getcustomerbycustomernumberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the customer with the specified customer number. |
| static [getCustomerByLogin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getcustomerbyloginstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the customer for the specified login name. |
| static [getCustomerByToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getcustomerbytokenstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the customer associated with the specified password reset token. |
| static [getCustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getcustomergroupstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the customer group with the specified ID or null if group  does not exists. |
| static [getCustomerGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getcustomergroups)() | Returns the customer groups of the current site. |
| static [getCustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getcustomerliststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the customer list identified by the specified ID. |
| static [getExternallyAuthenticatedCustomerProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getexternallyauthenticatedcustomerprofilestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Given an authentication provider Id and external Id returns the Customer Profile  in our system. |
| static [getPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getpasswordconstraints)() | Returns an instance of [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md)  for the customer list assigned to the current site. |
| static [getProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getprofilestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the profile with the specified customer number. |
| static [getRegisteredCustomerCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getregisteredcustomercount)() | Returns the number of registered customers in the system. |
| static [getSiteCustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getsitecustomerlist)() | Returns the customer list of the current site. |
| static [isAcceptablePassword](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#isacceptablepasswordstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Checks if the given password matches the password constraints (for example password length) of  the current site's assigned customerlist. |
| static [isPasswordExpired](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#ispasswordexpiredstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Checks if the password for the given customer is expired |
| static [loginCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#logincustomerauthenticationstatus-boolean)([AuthenticationStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | This method logs in the authenticated customer (from a previous authenticateCustomer() call). |
| ~~static [loginCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#logincustomerstring-string-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))~~ | This method authenticates the current session using the supplied login and password. |
| static [loginExternallyAuthenticatedCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#loginexternallyauthenticatedcustomerstring-string-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Logs in externally authenticated customer if it has already been created in the system and the profile is not disabled or locked |
| static [logoutCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#logoutcustomerboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Logs out the customer currently logged into the storefront. |
| static [processProfiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#processprofilesfunction-string-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Executes a user-definable function on a set of customer profiles. |
| ~~static [queryProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#queryprofilestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | <p/>Searches for a single profile instance. |
| ~~static [queryProfiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#queryprofilesmap-string)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | <p/>Searches for profile instances. |
| ~~static [queryProfiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#queryprofilesstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | Searches for profile instances. |
| static [removeCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#removecustomercustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Logs out the supplied customer and deletes the customer record. |
| static [removeCustomerTrackingData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#removecustomertrackingdatacustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Removes (asynchronously) tracking data for this customer (from external systems or data stores). |
| static [searchProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p/>Searches for a single profile instance. |
| static [searchProfiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesmap-string)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p/>Searches for profile instances. |
| static [searchProfiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Searches for profile instances. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### customerGroups
- customerGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the customer groups of the current site.


---

### passwordConstraints
- passwordConstraints: [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md) `(read-only)`
  - : Returns an instance of [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md)
      for the customer list assigned to the current site.



---

### registeredCustomerCount
- registeredCustomerCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of registered customers in the system. This number can be used for reporting
      purposes.



---

### siteCustomerList
- siteCustomerList: [CustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md) `(read-only)`
  - : Returns the customer list of the current site.


---

## Method Details

### authenticateCustomer(String, String)
- static authenticateCustomer(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [AuthenticationStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md)
  - : This method authenticates a customer using the supplied login and password. It will not log in the customer into
      the current session, but returns only a status indicating success or failure (with different error codes for the failure cases).
      Upon successful authentication (status code 'AUTH\_OK') the status object also holds the authenticated customer.
      To continue the login process, call the loginCustomer(AuthenticationStatus, boolean) method.
      
      This method verifies that the password for the customer is not expired. If it is expired the authentication will fail, with a status code of
      ERROR\_PASSWORD\_EXPIRED. This allows the storefront to require the customer to change the password, and then the login can proceed.


    **Parameters:**
    - login - Login name, must not be null.
    - password - Password, must not be null.

    **Returns:**
    - the status of the authentication process


---

### createCustomer(String, String)
- static createCustomer(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Creates a new Customer using the supplied login, password. The system automatically assigns a customer number based on
      the customer sequence numbers configured for the site or organization. The number is guaranteed to be unique, but is not guaranteed to be sequential.
      It can be higher or lower than a previously created number. As a result, sorting customers by customer number is not guaranteed to sort them in their
      order of creation.
      
      
      The method throws an exception if any of the following conditions are encountered:
      
      - A Customer with the supplied Login already exists
      - The Login is not acceptable.
      - The Password is not acceptable.
      - The system cannot create the Customer.
      
      
      
      A valid login name is between 1 and 256 characters in length (not counting leading or trailing whitespace), and may contain only the
      following characters:
      
      - alphanumeric (Unicode letters or decimal digits)
      - space
      - period
      - dash
      - underscore
      - @
      
      
      
      Note: a storefront can be customized to provide further constraints on characters in a login name, but it cannot remove any constraints described above.
      
      
      If customers are created using this Script API call then any updated to the customer records should be done through Script API calls as well.
      The customer records created with Script API call should not be updated with OCAPI calls as the email validation is handled
      differently in these calls and may result in InvalidEmailException.


    **Parameters:**
    - login - The unique login name associated with the new customer and its profile, must not be null. If login is already in use, an exception will be thrown.
    - password - Customer plain customer password, which is encrypted before it is stored at the profile, must not be null.

    **Returns:**
    - customer The new customer object.


---

### createCustomer(String, String, String)
- static createCustomer(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), customerNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Creates a new Customer using the supplied login, password, and a customerNo. If the customerNo is not specified,
      the system automatically assigns a customer number based on the customer sequence numbers configured for the site or organization. An automatically assigned
      number is guaranteed to be unique, but is not guaranteed to be sequential. It can be higher or lower than a previously created number. As a result, sorting
      customers by customer number is not guaranteed to sort them in their order of creation.
      
      
      The method throws an exception if any of the following conditions are encountered:
      
      - A Customer with the supplied Login already exists
      - A Customer with the explicitly provided or calculated customer number already exists.
      - The Login is not acceptable.
      - The Password is not acceptable.
      - The system cannot create the Customer.
      
      
      
      A valid login name is between 1 and 256 characters in length (not counting leading or trailing whitespace), and may contain only the
      following characters:
      
      - alphanumeric (Unicode letters or decimal digits)
      - space
      - period
      - dash
      - underscore
      - @
      
      
      
      Note: a storefront can be customized to provide further constraints on characters in a login name, but it cannot remove any constraints described above.
      
      
      A valid CustomerNo is between 1 and 100 characters in length (not counting leading or trailing whitespace). Commerce Cloud Digital recommends that a CustomerNo only
      contain characters valid for URLs.
      
      
      If customers are created using this Script API call then any updated to the customer records should be done through Script API calls as well.
      The customer records created with Script API call should not be updated with OCAPI calls as the email validation is handled
      differently in these calls and may result in InvalidEmailException.


    **Parameters:**
    - login - The unique login name associated with the new customer and its profile, must not be null. If login is already in use, an exception will be thrown.
    - password - Customer plain customer password, which is encrypted before it is stored at the profile, must not be null.
    - customerNo - The unique customerNo can be null, the system will then automatically assign a new value. If provided explicitly,  the system will make sure that no other customer uses the same value and will throw an exception otherwise.

    **Returns:**
    - customer The new customer object.


---

### createExternallyAuthenticatedCustomer(String, String)
- static createExternallyAuthenticatedCustomer(authenticationProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), externalId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Given an authentication provider Id and an external Id: creates a Customer record in the system if one does not
      exist already for the same 'authenticationProviderId' and 'externalId' pair. If one already exists - it is returned.


    **Parameters:**
    - authenticationProviderId - the Id of the authentication provider as configured in Commerce Cloud Digital.
    - externalId - the Id of the customer at the authentication provider. Each authentication provider generates  these in a different way, they are unique within their system

    **Returns:**
    - On success: the created customer. On failure - null


---

### describeProfileType()
- static describeProfileType(): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the meta data for profiles.

    **Returns:**
    - the meta data for profiles.


---

### getCustomerByCustomerNumber(String)
- static getCustomerByCustomerNumber(customerNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer with the specified customer number. If no customer with this customer number exists, null is returned.

    **Parameters:**
    - customerNumber - the customer number associated with the customer, must not be null.

    **Returns:**
    - The customer if found, null otherwise


---

### getCustomerByLogin(String)
- static getCustomerByLogin(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer for the specified login name. If no customer with this login name exists, null is returned.

    **Parameters:**
    - login - the unique login name associated with the customer, must not be null.

    **Returns:**
    - The customer if found, null otherwise


---

### getCustomerByToken(String)
- static getCustomerByToken(token: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer associated with the specified password reset token. A valid token is one that is associated
      with a customer record and is not expired. Such a token can be generated by
      [Credentials.createResetPasswordToken()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md#createresetpasswordtoken). If the passed token is valid, the associated customer
      is returned. Otherwise `null` is returned


    **Parameters:**
    - token - password reset token

    **Returns:**
    - The customer associated with the token. `Null` if the token is invalid.


---

### getCustomerGroup(String)
- static getCustomerGroup(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md)
  - : Returns the customer group with the specified ID or null if group
      does not exists.


    **Parameters:**
    - id - the customer group identifier.

    **Returns:**
    - Customer group for ID or null


---

### getCustomerGroups()
- static getCustomerGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the customer groups of the current site.

    **Returns:**
    - Customer groups of current site.


---

### getCustomerList(String)
- static getCustomerList(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md)
  - : Returns the customer list identified by the specified ID.
      Returns null if no customer list with the specified id exists.
      
      
      Note: Typically the ID of an automatically created customer
      list is equal to the ID of the site.


    **Parameters:**
    - id - The ID of the customer list.

    **Returns:**
    - The CustomerList, or null if not found.


---

### getExternallyAuthenticatedCustomerProfile(String, String)
- static getExternallyAuthenticatedCustomerProfile(authenticationProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), externalId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md)
  - : Given an authentication provider Id and external Id returns the Customer Profile
      in our system.


    **Parameters:**
    - authenticationProviderId - the Id of the authentication provider as configured in Commerce Cloud Digital.
    - externalId - the Id of the customer at the authentication provider.  Each authentication provider generates these in a different way, they  are unique within their system

    **Returns:**
    - The Profile of the customer if found, null otherwise


---

### getPasswordConstraints()
- static getPasswordConstraints(): [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md)
  - : Returns an instance of [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md)
      for the customer list assigned to the current site.


    **Returns:**
    - customer password constraints for current site


---

### getProfile(String)
- static getProfile(customerNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md)
  - : Returns the profile with the specified customer number.

    **Parameters:**
    - customerNumber - the customer number of the customer of the to be retrieved profile

    **Returns:**
    - Profile for specified customer number


---

### getRegisteredCustomerCount()
- static getRegisteredCustomerCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of registered customers in the system. This number can be used for reporting
      purposes.


    **Returns:**
    - the number of registered customers in the system.


---

### getSiteCustomerList()
- static getSiteCustomerList(): [CustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md)
  - : Returns the customer list of the current site.

    **Returns:**
    - The customer list assigned to the current site.


---

### isAcceptablePassword(String)
- static isAcceptablePassword(password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks if the given password matches the password constraints (for example password length) of
      the current site's assigned customerlist.


    **Parameters:**
    - password - the to be checked password

    **Returns:**
    - true if the given password matches all required criteria


---

### isPasswordExpired(String)
- static isPasswordExpired(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks if the password for the given customer is expired

    **Parameters:**
    - login - the login for the customer to be checked

    **Returns:**
    - true if the password is expired


---

### loginCustomer(AuthenticationStatus, Boolean)
- static loginCustomer(authStatus: [AuthenticationStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md), rememberMe: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : This method logs in the authenticated customer (from a previous authenticateCustomer() call). If a different customer is currently authenticated in the session, then this
      customer is "logged out" and all privacy-relevant data and all form data are deleted. If the previous authentication was not successful, then null is returned and no changes
      to the session are made.
      
      
       If the input value "RememberMe" is set to true, this method stores a cookie on the customer's machine which will be used to identify the customer when the next
      session is initiated.  The cookie is set to expire in 180 days (i.e. 6 months). Note that a customer who is remembered is not automatically authenticated and will
      have to explicitly log in to access any personal information.


    **Parameters:**
    - authStatus - the authentication status from the previous authenticateCustomer call
    - rememberMe - Boolean value indicating if the customer wants to be remembered on the current computer.  If a value of true is supplied a cookie identifying  the customer is stored upon successful login.  If a value of false, or a null value, is supplied, then no cookie is stored and any existing cookie is removed.

    **Returns:**
    - Customer successfully authenticated customer. Null if the authentication status was not indicating success of the authentication.


---

### loginCustomer(String, String, Boolean)
- ~~static loginCustomer(login: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), rememberMe: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)~~
  - : This method authenticates the current session using the supplied login and password. If a different customer is currently authenticated in the session, then this
      customer is "logged out" and her/his privacy and form data are deleted. If the authentication with the given credentials fails, then null is returned and no changes
      to the session are made. The authentication will be sucessful even when the password of the customer is already expired (according to the customer list settings).
      
      
       If the input value "RememberMe" is set to true, this method stores a cookie on the customer's machine which will be used to identify the customer when the next
      session is initiated.  The cookie is set to expire in 180 days (i.e. 6 months). Note that a customer who is remembered is not automatically authenticated and will
      have to explicitly log in to access any personal information.


    **Parameters:**
    - login - Login name, must not be null.
    - password - Password, must not be null.
    - rememberMe - Boolean value indicating if the customer wants to be remembered on the current computer.  If a value of true is supplied a cookie identifying  the customer is stored upon successful login.  If a value of false, or a null value, is supplied, then no cookie is stored and any existing cookie is removed.

    **Returns:**
    - Customer successfully authenticated customer. Null if the authentication with the given credentials fails.

    **Deprecated:**
**warning:** use authenticateCustomer(login, password) and loginCustomer(authStatus, rememberMe) instead since they correctly check for expired passwords

---

### loginExternallyAuthenticatedCustomer(String, String, Boolean)
- static loginExternallyAuthenticatedCustomer(authenticationProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), externalId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), rememberMe: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Logs in externally authenticated customer if it has already been created in the system and the profile is not disabled or locked

    **Parameters:**
    - authenticationProviderId - the Id of the authentication provider as configured in Commerce Cloud Digital.
    - externalId - the Id of the customer at the authentication provider.
    - rememberMe - whether to drop the remember me cookie

    **Returns:**
    - Customer if found in the system and not disabled or locked.
      [getExternallyAuthenticatedCustomerProfile(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getexternallyauthenticatedcustomerprofilestring-string)



---

### logoutCustomer(Boolean)
- static logoutCustomer(rememberMe: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Logs out the customer currently logged into the storefront. The boolean value "RememberMe" indicates, if the customer would like to be remembered on the current
      browser. If a value of true is supplied, the customer authentication state is set to "not logged in" and additionally the following session data is removed: the customer
      session private data, the form status data, dictionary information of interaction continue nodes, basket reference information, the secure token cookie. If the value is set
      to false or null, the complete session dictionary is cleaned up. The customer and anonymous cookie are removed and a new session cookie is set.


    **Parameters:**
    - rememberMe - Boolean value indicating if the customer wants to be remembered on the current browser. If a value of true is supplied, the customer authentication state  is set to "not logged in" and additionally the following session data is removed: the customer session private data, the form status data, dictionary information of interaction  continue nodes, basket reference information, the secure token cookie. If the value is set to false or null, the complete session dictionary is cleaned up. The customer and anonymous  cookie are removed and a new session cookie is set.

    **Returns:**
    - the new customer identity after logout. If rememberMe is true, null is returned.


---

### processProfiles(Function, String, Object...)
- static processProfiles(processFunction: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Executes a user-definable function on a set of customer profiles. This method is intended to be used in batch processes and jobs,
      since it allows efficient processing of large result sets (which might take a while to process).
      
      First, a search with the given parameters is executed. Then the given function is executed once for each profile of the search result.
      The profile is handed over as the only parameter to this function.
      
      
      The search can be configured using a simple query language, which
      provides most common filter and operator functionality.
      
      For a description of this query language, see the [queryProfile(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#queryprofilestring-object) method.
      
      The callback function will be supplied with a single argument of type 'Profile'. When the callback function defines
      additional arguments, they will be undefined when the function is called. When the callback function doesn't define
      any arguments at all, it will be called anyway (no error will happen, but the function won't get a profile as parameter).
      
      Error during execution of the callback function will be logged, and execution will continue with the next element from the
      result set.
      
      This method can be used as in this example (which counts the number of men):
      
      
      ```
              var count=0;
              function callback(profile: Profile)
              {
                  count++;
                  dw.system.Logger.debug("customer found: "+profile.customerNo)
              }
             CustomerMgr.processProfiles(callback, "gender=1");
             dw.system.Logger.debug("found "+count+" men in customer list");
      ```


    **Parameters:**
    - processFunction - the function to execute for each profile
    - queryString - the query string to use when searching for a profile.
    - args - the query string arguments.


---

### queryProfile(String, Object...)
- ~~static queryProfile(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md)~~
  - : 
      Searches for a single profile instance.
      
      
      The search can be configured using a simple query language, which
      provides most common filter and operator functionality.
      
      
      The identifier for an **attribute**  to use in a query condition is always the
      ID of the  attribute as defined in the type definition. For custom defined attributes
      the prefix custom is required in the search term (e.g. `custom.color = {1}`),
      while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      Supported attribute value **types** with sample expression values:
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      Note, that some system attributes are not queryable by default regardless of the
      actual value type code.
      
      
      
      The following **operators** are supported in a condition:
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than  - Integer, Number and Date types only
      - `>`Greater than - Integer, Number and Date types only
      - `<=`Less or equals than - Integer, Number and Date types only
      - `>=`Greater or equals than  - Integer, Number and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing  wildcards will be used to support substring search(`custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only, use to support  case insensitive query (`custom.country ILIKE 'usa'`), does also support wildcards for  substring matching
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT'
      and nested using parenthesis e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      The query language provides a placeholder syntax to pass objects as
      additional search parameters. Each passed object is related to a
      placeholder in the query string. The placeholder must be an Integer that
      is surrounded by braces. The first Integer value must be '0', the second
      '1' and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      If there is more than one object matching the specified query criteria, the
      result is not deterministic. In order to retrieve a single object from a sorted result
      set it is recommended to use the following code:
      `queryProfiles("", "custom.myAttr asc", null).first()`.
      The method `first()` returns only the next element and closes the
      iterator.
      
      
      
      
      **This method is deprecated and will be removed in a future release.**
      One of the following methods should be used instead:
      [searchProfile(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilestring-object),
      [searchProfiles(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesmap-string) and
      [searchProfiles(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesstring-string-object) to search for customers and
      [processProfiles(Function, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#processprofilesfunction-string-object) to search and process customers in jobs.


    **Parameters:**
    - queryString - the query string to use when searching for a profile.
    - args - the query string arguments.

    **Returns:**
    - the profile which was found when executing the `queryString`.

    **Deprecated:**
**warning:** use [searchProfile(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilestring-object) instead.

---

### queryProfiles(Map, String)
- ~~static queryProfiles(queryAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)~~
  - : 
      Searches for profile instances.
      
      
      The search can be configured with a map, which key-value pairs are
      converted into a query expression. The key-value pairs are turned into a
      sequence of '=' or 'like' conditions, which are combined with AND
      statements.
      
      
      Example:
      
      A map with the key/value pairs: _'name'/'tom\*', 'age'/66_
      will be converted as follows: `"name like 'tom*' and age = 66"`
      
      
      The identifier for an **attribute**  to use in a query condition is always the
      ID of the  attribute as defined in the type definition. For custom defined attributes
      the prefix custom is required in the search term (e.g. `custom.color = {1}`),
      while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      Supported attribute value **types** with sample expression values:
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      Note, that some system attributes are not queryable by default regardless of the
      actual value type code.
      
      
      
      The **sorting** parameter is optional and may contain a comma separated list of
      attribute names to sort by. Each sort attribute name may be followed by an
      optional sort direction specifier ('asc' | 'desc'). Default sorting directions is
      ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is
      currently not supported.
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.
      See [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)
      
      
      
      
      **This method is deprecated and will be removed in a future release.**
      One of the following methods should be used instead:
      [searchProfile(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilestring-object),
      [searchProfiles(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesmap-string) and
      [searchProfiles(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesstring-string-object) to search for customers and
      [processProfiles(Function, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#processprofilesfunction-string-object) to search and process customers in jobs.


    **Parameters:**
    - queryAttributes - key-value pairs that define the query.
    - sortString - an optional sorting or null if no sorting is necessary.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **Deprecated:**
**warning:** use [searchProfiles(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesmap-string) instead.

---

### queryProfiles(String, String, Object...)
- ~~static queryProfiles(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)~~
  - : Searches for profile instances.
      
      
      The search can be configured using a simple query language, which
      provides most common filter and operator functionality.
      
      For a description of this query language, see the [queryProfile(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#queryprofilestring-object) method.
      
      
      
      **This method is deprecated and will be removed in a future release.**
      One of the following methods should be used instead:
      [searchProfile(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilestring-object),
      [searchProfiles(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesmap-string) and
      [searchProfiles(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesstring-string-object) to search for customers and
      [processProfiles(Function, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#processprofilesfunction-string-object) to search and process customers in jobs.


    **Parameters:**
    - queryString - the actual query.
    - sortString - an optional sorting or null if no sorting is necessary.
    - args - optional parameters for the query string.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **Deprecated:**
**warning:** use [searchProfiles(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilesstring-string-object) instead.

---

### removeCustomer(Customer)
- static removeCustomer(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): void
  - : Logs out the supplied customer and deletes the customer record. The customer must be a registered customer and the customer must currently be logged in. The customer must be
      logged in for security reasons to ensure that only the customer itself can remove itself from the system. While logout the customers session is reset to an anonymous session and, if present, the "Remember me" cookie of the customer is removed.
      Deleting the customer record includes the customer credentials, profile, address-book with all addresses, customer payment instruments, product lists and memberships in
      customer groups. Orders placed by this customer won't be deleted. If the supplied customer is not a registered customer or is not logged in, the API throws an exception


    **Parameters:**
    - customer - The customer to remove, must not be null.


---

### removeCustomerTrackingData(Customer)
- static removeCustomerTrackingData(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): void
  - : Removes (asynchronously) tracking data for this customer (from external systems or data stores). This will not remove the
      customer from the database, nor will it prevent tracking to start again in the future for this customer.
      
      The customer is identified by login / email /customerNo / cookie when its a registered customer, and by cookie
      when its an anonymous customer.


    **Parameters:**
    - customer - the customer


---

### searchProfile(String, Object...)
- static searchProfile(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md)
  - : 
      Searches for a single profile instance.
      
      
      The search can be configured using a simple query language, which
      provides most common filter and operator functionality.
      
      
      The identifier for an **attribute** to use in a query condition is always the
      ID of the attribute as defined in the type definition. For custom defined attributes
      the prefix custom is required in the search term (e.g. `custom.color = {1}`),
      while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      Supported attribute value **types** with sample expression values:
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      Note, that some system attributes are not queryable by default regardless of the
      actual value type code.
      
      
      
      The following **operators** are supported in a condition:
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than  - Integer, Number and Date types only
      - `>`Greater than - Integer, Number and Date types only
      - `<=`Less or equals than - Integer, Number and Date types only
      - `>=`Greater or equals than  - Integer, Number and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing  wildcards will be used to support substring search(`custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only, use to support  case insensitive query (`custom.country ILIKE 'usa'`), does also support wildcards for  substring matching
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT'
      and nested using parenthesis e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      The query language provides a placeholder syntax to pass objects as
      additional search parameters. Each passed object is related to a
      placeholder in the query string. The placeholder must be an Integer that
      is surrounded by braces. The first Integer value must be '0', the second
      '1' and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      
      If there is more than one object matching the specified query criteria, the
      result is not deterministic. In order to retrieve a single object from a sorted result
      set it is recommended to use the following code:
      `queryProfiles("", "custom.myAttr asc", null).first()`.
      The method `first()` returns only the next element and closes the
      iterator.
      
      
      If the customer search API is configured to use the new Search Service, these differences apply:
      
      
      - Search may match and return documents with missing (NULL) values in search fields, depending on      how the query is structured, potentially leading to broader result sets. For example, a query like      `custom.searchField != "some value"`also returns documents where `custom.searchField`is NULL — whereas in relational databases, such documents are excluded.
      - Newly created customers might not be found immediately via the search service, and changes to existing      customers might also not be in effect immediately (there is a slight delay in updating the index)
      - Wildcards are filtered from the query (\*, %, +) and replaced by spaces
      - LIKE and ILIKE queries are executed as fulltext queries (working on whole words), not as substring searches
      - LIKE queries are always case insensitive
      - Using logical operators may change the execution of LIKE/ILIKE clauses to exact string comparison, depending on how they are combined
      - Using logical operators may result in degraded performance, depending on how they are combined


    **Parameters:**
    - queryString - the query string to use when searching for a profile.
    - args - the query string arguments.

    **Returns:**
    - the profile which was found when executing the `queryString`.


---

### searchProfiles(Map, String)
- static searchProfiles(queryAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      Searches for profile instances.
      
      
      The search can be configured with a map, which key-value pairs are
      converted into a query expression. The key-value pairs are turned into a
      sequence of '=' or 'like' conditions, which are combined with AND
      statements.
      
      
      Example:
      
      A map with the key/value pairs: _'name'/'tom\*', 'age'/66_
      will be converted as follows: `"name like 'tom*' and age = 66"`
      
      
      The identifier for an **attribute**  to use in a query condition is always the
      ID of the  attribute as defined in the type definition. For custom defined attributes
      the prefix custom is required in the search term (e.g. `custom.color = {1}`),
      while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      Supported attribute value **types** with sample expression values:
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      Note, that some system attributes are not queryable by default regardless of the
      actual value type code.
      
      
      
      The **sorting** parameter is optional and may contain a comma separated list of
      attribute names to sort by. Each sort attribute name may be followed by an
      optional sort direction specifier ('asc' | 'desc'). Default sorting directions is
      ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is
      currently not supported.
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.
      
      [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)
      
      
      If the customer search API is configured to use the new Search Service, these differences apply:
      
      
      - Search may match and return documents with missing (NULL) values in search fields, depending on      how the query is structured, potentially leading to broader result sets. For example, a query like      `custom.searchField != "some value"`also returns documents where `custom.searchField`is NULL — whereas in relational databases, such documents are excluded.
      - Newly created customers might not be found immediately via the search service, and changes to existing      customers might also not be in effect immediately (there is a slight delay in updating the index)
      - Wildcards are filtered from the query (\*, %, +) and replaced by spaces
      - LIKE and ILIKE queries are executed as fulltext queries (working on whole words), not as substring searches
      - LIKE queries are always case insensitive
      - Using logical operators may change the execution of LIKE/ILIKE clauses to exact string comparison, depending on how they are combined
      - Using logical operators may result in degraded performance, depending on how they are combined
      - The search returns only the first 1000 hits from the search result


    **Parameters:**
    - queryAttributes - key-value pairs that define the query.
    - sortString - an optional sorting or null if no sorting is necessary.

    **Returns:**
    - SeekableIterator containing the result set of the query.


---

### searchProfiles(String, String, Object...)
- static searchProfiles(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Searches for profile instances.
      
      
      The search can be configured using a simple query language, which
      provides most common filter and operator functionality.
      
      For a description of this query language, see the [searchProfile(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#searchprofilestring-object) method.
      
      
      If the customer search API is configured to use the new Search Service, these differences apply:
      
      
      - Search may match and return documents with missing (NULL) values in search fields, depending on      how the query is structured, potentially leading to broader result sets. For example, a query like      `custom.searchField != "some value"`also returns documents where `custom.searchField`is NULL — whereas in relational databases, such documents are excluded.
      - Newly created customers might not be found immediately via the search service, and changes to existing      customers might also not be in effect immediately (there is a slight delay in updating the index)
      - Wildcards are filtered from the query (\*, %, +) and replaced by spaces
      - LIKE and ILIKE queries are executed as fulltext queries (working on whole words), not as substring searches
      - LIKE queries are always case insensitive
      - Using logical operators may change the execution of LIKE/ILIKE clauses to exact string comparison, depending on how they are combined
      - Using logical operators may result in degraded performance, depending on how they are combined
      - The search returns only the first 1000 hits from the search result


    **Parameters:**
    - queryString - the actual query.
    - sortString - an optional sorting or null if no sorting is necessary.
    - args - optional parameters for the query string.

    **Returns:**
    - SeekableIterator containing the result set of the query.


---

<!-- prettier-ignore-end -->

<!-- document id=8df0c86da08fd292f1750175480f0fefda861dff5427e84c5142aab4949a17c7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerPasswordConstraints.md -->

<!-- prettier-ignore-start -->
# Class CustomerPasswordConstraints

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md)

Provides access to the constraints of customer passwords. An instance of this class can be obtained via [CustomerMgr.getPasswordConstraints()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md#getpasswordconstraints).


## Property Summary

| Property | Description |
| --- | --- |
| [forceLetters](#forceletters): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if letters are enforced. |
| [forceMixedCase](#forcemixedcase): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if mixed case is enforced. |
| [forceNumbers](#forcenumbers): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if numbers are enforced. |
| [minLength](#minlength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the minimum length. |
| [minSpecialChars](#minspecialchars): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the minimum number of special characters. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getMinLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md#getminlength)() | Returns the minimum length. |
| static [getMinSpecialChars](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md#getminspecialchars)() | Returns the minimum number of special characters. |
| static [isForceLetters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md#isforceletters)() | Returns `true` if letters are enforced. |
| static [isForceMixedCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md#isforcemixedcase)() | Returns `true` if mixed case is enforced. |
| static [isForceNumbers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md#isforcenumbers)() | Returns `true` if numbers are enforced. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### forceLetters
- forceLetters: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if letters are enforced.


---

### forceMixedCase
- forceMixedCase: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if mixed case is enforced.


---

### forceNumbers
- forceNumbers: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if numbers are enforced.


---

### minLength
- minLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the minimum length.


---

### minSpecialChars
- minSpecialChars: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the minimum number of special characters.


---

## Method Details

### getMinLength()
- static getMinLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the minimum length.

    **Returns:**
    - the minimum length


---

### getMinSpecialChars()
- static getMinSpecialChars(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the minimum number of special characters.

    **Returns:**
    - the minimum number of special characters


---

### isForceLetters()
- static isForceLetters(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if letters are enforced.

    **Returns:**
    - if letters are enforced


---

### isForceMixedCase()
- static isForceMixedCase(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if mixed case is enforced.

    **Returns:**
    - if mixed case is enforced


---

### isForceNumbers()
- static isForceNumbers(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if numbers are enforced.

    **Returns:**
    - if numbers are enforced


---

<!-- prettier-ignore-end -->

<!-- document id=28fff15e09b19a71e8d703d49d382ad31184dd243d0751c10b1245d966f64fd4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerPaymentInstrument.md -->

<!-- prettier-ignore-start -->
# Class CustomerPaymentInstrument

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md)
        - [dw.order.PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md)
          - [dw.customer.CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md)

Represents any payment instrument stored in the customers profile, such as
credit card or bank transfer. The object defines standard methods for credit
card payment, and can be extended by attributes appropriate for other
payment methods.



## Property Summary

| Property | Description |
| --- | --- |
| [bankAccountDriversLicense](#bankaccountdriverslicense): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the driver's license number of the bank account number  if the calling context meets the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current customer is registered and authenticated, and the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  </li>  </ul>  Otherwise, the method returns the masked driver's license number of the bank account. |
| [bankAccountNumber](#bankaccountnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank account number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  </li>  </ul>  Otherwise, the method returns the masked bank account number. |
| [creditCardNumber](#creditcardnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the decrypted credit card number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md#getbankaccountdriverslicense)() | Returns the driver's license number of the bank account number  if the calling context meets the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current customer is registered and authenticated, and the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  </li>  </ul>  Otherwise, the method returns the masked driver's license number of the bank account. |
| [getBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md#getbankaccountnumber)() | Returns the bank account number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  </li>  </ul>  Otherwise, the method returns the masked bank account number. |
| [getCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md#getcreditcardnumber)() | Returns the decrypted credit card number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS. |

### Methods inherited from class PaymentInstrument

[getBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicense), [getBankAccountDriversLicenseLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicenselastdigits), [getBankAccountDriversLicenseLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicenselastdigitsnumber), [getBankAccountDriversLicenseStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicensestatecode), [getBankAccountHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountholder), [getBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumber), [getBankAccountNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumberlastdigits), [getBankAccountNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumberlastdigitsnumber), [getBankRoutingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankroutingnumber), [getCreditCardExpirationMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardexpirationmonth), [getCreditCardExpirationYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardexpirationyear), [getCreditCardHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardholder), [getCreditCardIssueNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardissuenumber), [getCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumber), [getCreditCardNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumberlastdigits), [getCreditCardNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumberlastdigitsnumber), [getCreditCardToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardtoken), [getCreditCardType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardtype), [getCreditCardValidFromMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardvalidfrommonth), [getCreditCardValidFromYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardvalidfromyear), [getEncryptedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedbankaccountdriverslicensestring-string), [getEncryptedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedbankaccountnumberstring-string), [getEncryptedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedcreditcardnumberstring-certificateref), [getEncryptedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedcreditcardnumberstring-string), [getGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificatecode), [getGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificateid), [getMaskedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountdriverslicense), [getMaskedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountdriverslicensenumber), [getMaskedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountnumber), [getMaskedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountnumbernumber), [getMaskedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedcreditcardnumber), [getMaskedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedcreditcardnumbernumber), [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedgiftcertificatecode), [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedgiftcertificatecodenumber), [getPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getpaymentmethod), [isCreditCardExpired](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#iscreditcardexpired), [isPermanentlyMasked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked), [setBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountdriverslicensestring), [setBankAccountDriversLicenseStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountdriverslicensestatecodestring), [setBankAccountHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountholderstring), [setBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountnumberstring), [setBankRoutingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankroutingnumberstring), [setCreditCardExpirationMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardexpirationmonthnumber), [setCreditCardExpirationYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardexpirationyearnumber), [setCreditCardHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardholderstring), [setCreditCardIssueNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardissuenumberstring), [setCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardnumberstring), [setCreditCardToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardtokenstring), [setCreditCardType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardtypestring), [setCreditCardValidFromMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardvalidfrommonthnumber), [setCreditCardValidFromYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardvalidfromyearnumber), [setGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setgiftcertificatecodestring), [setGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setgiftcertificateidstring)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bankAccountDriversLicense
- bankAccountDriversLicense: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the driver's license number of the bank account number
      if the calling context meets the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current customer is registered and authenticated, and the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  
      
      Otherwise, the method returns the masked driver's license number of the bank account.
      
      
      **Note:** this method handles sensitive financial and card holder data.
      Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



---

### bankAccountNumber
- bankAccountNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank account number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  
      
      Otherwise, the method returns the masked bank account number.
      
      
      **Note:** this method handles sensitive financial and card holder data.
      Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



---

### creditCardNumber
- creditCardNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the decrypted credit card number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS.  
      
      Otherwise, the method returns the masked credit card number.
      
      
      **Note:** this method handles sensitive financial and card holder data.
      Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



---

## Method Details

### getBankAccountDriversLicense()
- getBankAccountDriversLicense(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the driver's license number of the bank account number
      if the calling context meets the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current customer is registered and authenticated, and the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  
      
      Otherwise, the method returns the masked driver's license number of the bank account.
      
      
      **Note:** this method handles sensitive financial and card holder data.
      Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



---

### getBankAccountNumber()
- getBankAccountNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank account number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS  
      
      Otherwise, the method returns the masked bank account number.
      
      
      **Note:** this method handles sensitive financial and card holder data.
      Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



---

### getCreditCardNumber()
- getCreditCardNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted credit card number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request,  the current customer is registered and authenticated, the payment  instrument is associated to the profile of the current customer, and  the current protocol is HTTPS.  
      
      Otherwise, the method returns the masked credit card number.
      
      
      **Note:** this method handles sensitive financial and card holder data.
      Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



---

<!-- prettier-ignore-end -->

<!-- document id=0634ed474ae93124da5e133a7ef9ebfd0e446ad041db0f4289599e41bff618b9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.CustomerStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class CustomerStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.CustomerStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerStatusCodes.md)

CustomerStatusCodes contains constants representing 
status codes that can be used with a Status object to 
indicate the success or failure of an operation.


**See Also:**
- [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)


## Constant Summary

| Constant | Description |
| --- | --- |
| [CUSTOMER_ADDRESS_REFERENCED_BY_PRODUCT_LIST](#customer_address_referenced_by_product_list): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_ADDRESS_REFERENCED_BY_PRODUCT_LIST" | Indicates that an error occurred when trying to perform   an operation on an address that is currently associated   with a product list. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [CustomerStatusCodes](#customerstatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CUSTOMER_ADDRESS_REFERENCED_BY_PRODUCT_LIST

- CUSTOMER_ADDRESS_REFERENCED_BY_PRODUCT_LIST: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_ADDRESS_REFERENCED_BY_PRODUCT_LIST"
  - : Indicates that an error occurred when trying to perform 
      an operation on an address that is currently associated 
      with a product list.



---

## Constructor Details

### CustomerStatusCodes()
- CustomerStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=9baf1b5ae7398bf7e899bee765c639a800ca4ee77a25477c7e300ff59777d26f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.CustomObject.md -->

<!-- prettier-ignore-start -->
# Class CustomObject

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.object.CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)

Represents a custom object and its corresponding attributes.


## Property Summary

| Property | Description |
| --- | --- |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes of this  object. |
| [type](#type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of the CustomObject. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md#getcustom)() | Returns the custom attributes of this  object. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md#gettype)() | Returns the type of the CustomObject. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes of this
      object.



---

### type
- type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of the CustomObject.


---

## Method Details

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes of this
      object.


    **Returns:**
    - the custom attributes of this
      object.



---

### getType()
- getType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the CustomObject.

    **Returns:**
    - the type of the CustomObject.


---

<!-- prettier-ignore-end -->

<!-- document id=8dc7453c0cfa166af98ef7212a4bd4550a64174d95955d3d521286258abf6694 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.CustomObjectMgr.md -->

<!-- prettier-ignore-start -->
# Class CustomObjectMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.CustomObjectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md)

Manager class which provides methods for creating, retrieving, deleting,
and searching for custom objects.


To search for system objects, use [SystemObjectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md).



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [createCustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#createcustomobjectstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new custom object instance of the specified type, using the  given key value. |
| static [createCustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#createcustomobjectstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a new custom object instance of the specified type, using the  given key value. |
| static [describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#describestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the meta data for the given type. |
| static [getAllCustomObjects](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#getallcustomobjectsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all custom objects of a specific type. |
| static [getCustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#getcustomobjectstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a custom object based on it's type and unique key. |
| static [getCustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#getcustomobjectstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a custom object based on it's type and unique key. |
| static [queryCustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#querycustomobjectstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p/>  Searches for a single custom object instance. |
| static [queryCustomObjects](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#querycustomobjectsstring-map-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p/>  Searches for custom object instances. |
| static [queryCustomObjects](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#querycustomobjectsstring-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Searches for custom object instances. |
| static [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md#removecustomobject)([CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)) | Removes a given custom object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### createCustomObject(String, Number)
- static createCustomObject(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), keyValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)
  - : Returns a new custom object instance of the specified type, using the
      given key value. Custom object keys need to be unique for custom object
      type.


    **Parameters:**
    - type - The unique name of the custom object type.
    - keyValue - The unique key value for the instance.

    **Returns:**
    - The newly created custom object instance.

    **Throws:**
    - IllegalArgumentException - if the given type is invalid


---

### createCustomObject(String, String)
- static createCustomObject(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), keyValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)
  - : Returns a new custom object instance of the specified type, using the
      given key value. Custom object keys need to be unique for custom object
      type.


    **Parameters:**
    - type - The unique name of the custom object type.
    - keyValue - The unique key value for the instance.

    **Returns:**
    - The newly created custom object instance.

    **Throws:**
    - IllegalArgumentException - if the given type is invalid


---

### describe(String)
- static describe(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the meta data for the given type.

    **Parameters:**
    - type - the type whose meta data is returned.

    **Returns:**
    - the meta data for the given type.

    **Throws:**
    - IllegalArgumentException - if the given type is invalid


---

### getAllCustomObjects(String)
- static getAllCustomObjects(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Returns all custom objects of a specific type.
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Parameters:**
    - type - The name of the custom object type.

    **Throws:**
    - IllegalArgumentException - if the given type is invalid

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### getCustomObject(String, Number)
- static getCustomObject(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), keyValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)
  - : Returns a custom object based on it's type and unique key.

    **Parameters:**
    - type - The name of the custom object type.
    - keyValue - The unique key value.

    **Returns:**
    - The matching custom object instance or `null` in case
               no matching custom object instance could be found.


    **Throws:**
    - IllegalArgumentException - if the given type is invalid


---

### getCustomObject(String, String)
- static getCustomObject(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), keyValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)
  - : Returns a custom object based on it's type and unique key.

    **Parameters:**
    - type - The name of the custom object type.
    - keyValue - The unique key value.

    **Returns:**
    - The matching custom object instance or `null` in case
               no matching custom object instance could be found.


    **Throws:**
    - IllegalArgumentException - if the given type is invalid


---

### queryCustomObject(String, String, Object...)
- static queryCustomObject(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)
  - : 
      
      Searches for a single custom object instance.
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality.
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom defined attributes the prefix custom is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      The following types of attributes are not queryable:
      
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      Note, that some system attributes are not queryable by default regardless of the actual value type code.
      
      
      The following **operators** are supported in a condition:
      
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number and Date types only
      - `>`Greater than - Integer, Number and Date types only
      - `<=`Less or equals than - Integer, Number and Date types only
      - `>=`Greater or equals than - Integer, Number and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search(`custom.country LIKE 'US*'`)
      - `ILIKE`Case-independent Like - String types and Email only, use to support case insensitive query  (`custom.country ILIKE 'usa'`), does also support wildcards for substring matching
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT' and nested using parenthesis e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1' and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      If there is more than one object matching the specified query criteria, the result is not deterministic. In order
      to retrieve a single object from a sorted result set it is recommended to use the following code:
      `queryCustomObjects("", "custom.myAttr asc", null).first()`. The method `first()` returns
      only the next element and closes the iterator.
      
      
      This method does not consider locale specific attributes. It returns all objects by checking the default
      non-localizable attributes. Any locale specific filtering after fetching the objects must be done by other custom
      code.
      
      Example:
      
      - Get the custom objects using this method with non-localized attributes query.
      - Access the `obj.getCustom("myattr")`. It returns the localized value of the attribute.


    **Parameters:**
    - type - the custom object type for the query.
    - queryString - the actual query.
    - args - optional parameters for the queryString.

    **Returns:**
    - the custom object defined by `type` which was found when executing the
              `queryString`.


    **Throws:**
    - IllegalArgumentException - if the given type is invalid


---

### queryCustomObjects(String, Map, String)
- static queryCustomObjects(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), queryAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      
      Searches for custom object instances.
      
      
      The search can be configured with a map, which key-value pairs are converted into a query expression. The
      key-value pairs are turned into a sequence of '=' or 'like' conditions, which are combined with AND statements.
      
      
      Example:
      
      A map with the key/value pairs: _'name'/'tom\*', 'age'/66_ will be converted as follows:
      `"name like 'tom*' and age = 66"`
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom defined attributes the prefix custom is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      The following types of attributes are not queryable:
      
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      Note, that some system attributes are not queryable by default regardless of the actual value type code.
      
      
      The **sorting** parameter is optional and may contain a comma separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). Default
      sorting directions is ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator if not all of its
      elements are being retrieved. This will ensure the proper cleanup of system resources.
      
      
      
      
      This method does not consider locale specific attributes. It returns all objects by checking the default
      non-localizable attributes. Any locale specific filtering after fetching the objects must be done by other custom
      code.
      
      Example:
      
      - Get the custom objects using this method with non-localized attributes query.
      - Access the `obj.getCustom("myattr")`. It returns the localized value of the attribute.


    **Parameters:**
    - type - the custom object type for the query.
    - queryAttributes - key-value pairs, which define the query.
    - sortString - an optional sorting or null if no sorting is necessary.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **Throws:**
    - IllegalArgumentException - if the given type is invalid

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### queryCustomObjects(String, String, String, Object...)
- static queryCustomObjects(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Searches for custom object instances.
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality.
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom defined attributes the prefix custom is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      The following types of attributes are not queryable:
      
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      Note, that some system attributes are not queryable by default regardless of the actual value type code.
      
      
      The following **operators** are supported in a condition:
      
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number and Date types only
      - `>`Greater than - Integer, Number and Date types only
      - `<=`Less or equals than - Integer, Number and Date types only
      - `>=`Greater or equals than - Integer, Number and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search(`custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only, use to support case insensitive query  (`custom.country ILIKE 'usa'`), does also support wildcards for substring matching
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT' and nested using parenthesis e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1' and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      The **sorting** parameter is optional and may contain a comma separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). Default
      sorting directions is ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      Sometimes it is desired to get all instances of specified type with a special sorting condition. This can be
      easily done by providing the 'type' of the custom object and the 'sortString' in combination with an empty
      'queryString', e.g. `queryCustomObjects("sample", "", "custom.myAttr asc")`
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator if not all of its
      elements are being retrieved. This will ensure the proper cleanup of system resources.
      
      
      
      
      This method does not consider locale specific attributes. It returns all objects by checking the default
      non-localizable attributes. Any locale specific filtering after fetching the objects must be done by other custom
      code.
      
      Example:
      
      - Get the custom objects using this method with non-localized attributes query.
      - Access the `obj.getCustom("myattr")`. It returns the localized value of the attribute.


    **Parameters:**
    - type - the custom object type for the query.
    - queryString - the actual query.
    - sortString - an optional sorting or null if no sorting is necessary.
    - args - optional parameters for the queryString.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **Throws:**
    - IllegalArgumentException - if the given type is invalid

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### remove(CustomObject)
- static remove(object: [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)): void
  - : Removes a given custom object.

    **Parameters:**
    - object - the custom object to remove, must not be null.


---

<!-- prettier-ignore-end -->

<!-- document id=85a62458df41ba260a5248d433b96c40fdc53e441bfb554b53020d752ccbf208 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.CustomSuggestions.md -->

<!-- prettier-ignore-start -->
# Class CustomSuggestions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md)
    - [dw.suggest.CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md)

The custom suggestion container provides access to
merchant provided search phrases
found using the suggested terms as search criteria.


The method [SearchPhraseSuggestions.getSuggestedPhrases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedphrases) can be used to
get the list of found search phrases. The custom phrases
lookup is being executed in the current site.


Furthermore the list of suggested terms is accessible
through [SearchPhraseSuggestions.getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms) method.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Suggestions

[getSearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions), [getSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedphrases), [getSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms), [hasSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases), [hasSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedterms), [hasSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=eed0d5a434de2f498054fc40c028baa46c1256a9c04b03a4526899e3e6e3c501 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.DataView.md -->

<!-- prettier-ignore-start -->
# Class DataView

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.DataView](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md)

The DataView provides low level access to [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

**API Version:**
**note:** Available from version 21.2.

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this view. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this view. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this view within the array buffer. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [DataView](#dataviewarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a data view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [getFloat32](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getfloat32number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the 32-bit floating point number at the given offset. |
| [getFloat64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getfloat64number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the 64-bit floating point number at the given offset. |
| [getInt16](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getint16number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the 16-bit signed integer number at the given offset. |
| [getInt32](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getint32number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the 32-bit signed integer number at the given offset. |
| [getInt8](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getint8number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the 8-bit signed integer number at the given offset. |
| [getUint16](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getuint16number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the 16-bit unsigned integer number at the given offset. |
| [getUint32](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getuint32number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the 32-bit unsigned integer number at the given offset. |
| [getUint8](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#getuint8number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the 8-bit unsigned integer number at the given offset. |
| [setFloat32](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setfloat32number-number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Writes a 32-bit floating point number into the byte array at the given offset. |
| [setFloat64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setfloat64number-number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Writes a 64-bit floating point number into the byte array at the given offset. |
| [setInt16](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setint16number-number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Writes a 16-bit signed integer number into the byte array at the given offset. |
| [setInt32](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setint32number-number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Writes a 32-bit signed integer number into the byte array at the given offset. |
| [setInt8](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setint8number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Writes an 8-bit signed integer number into the byte array at the given offset. |
| [setUint16](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setuint16number-number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Writes a 16-bit unsigned integer number into the byte array at the given offset. |
| [setUint32](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setuint32number-number-boolean)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Writes a 32-bit unsigned integer number into the byte array at the given offset. |
| [setUint8](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md#setuint8number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Writes an 8-bit unsigned integer number into the byte array at the given offset. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this view.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this view.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this view within the array buffer.


---

## Constructor Details

### DataView(ArrayBuffer, Number, Number)
- DataView(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a data view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - byteLength - Optional. The number of bytes visible to this view.


---

## Method Details

### getFloat32(Number, Boolean)
- getFloat32(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 32-bit floating point number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - littleEndian - Optional. Default is false. Use true if the number is stored in little-endian format.


---

### getFloat64(Number, Boolean)
- getFloat64(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 64-bit floating point number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - littleEndian - Optional. Default is false. Use true if the number is stored in little-endian format.


---

### getInt16(Number, Boolean)
- getInt16(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 16-bit signed integer number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - littleEndian - Optional. Default is false. Use true if the number is stored in little-endian format.


---

### getInt32(Number, Boolean)
- getInt32(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 32-bit signed integer number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - littleEndian - Optional. Default is false. Use true if the number is stored in little-endian format.


---

### getInt8(Number)
- getInt8(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 8-bit signed integer number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.


---

### getUint16(Number, Boolean)
- getUint16(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 16-bit unsigned integer number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - littleEndian - Optional. Default is false. Use true if the number is stored in little-endian format.


---

### getUint32(Number, Boolean)
- getUint32(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 32-bit unsigned integer number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - littleEndian - Optional. Default is false. Use true if the number is stored in little-endian format.


---

### getUint8(Number)
- getUint8(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the 8-bit unsigned integer number at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.


---

### setFloat32(Number, Number, Boolean)
- setFloat32(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Writes a 32-bit floating point number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.
    - littleEndian - Optional. Default is false. Use true if the little-endian format is to be used.


---

### setFloat64(Number, Number, Boolean)
- setFloat64(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Writes a 64-bit floating point number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.
    - littleEndian - Optional. Default is false. Use true if the little-endian format is to be used.


---

### setInt16(Number, Number, Boolean)
- setInt16(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Writes a 16-bit signed integer number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.
    - littleEndian - Optional. Default is false. Use true if the little-endian format is to be used.


---

### setInt32(Number, Number, Boolean)
- setInt32(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Writes a 32-bit signed integer number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.
    - littleEndian - Optional. Default is false. Use true if the little-endian format is to be used.


---

### setInt8(Number, Number)
- setInt8(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Writes an 8-bit signed integer number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.


---

### setUint16(Number, Number, Boolean)
- setUint16(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Writes a 16-bit unsigned integer number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.
    - littleEndian - Optional. Default is false. Use true if the little-endian format is to be used.


---

### setUint32(Number, Number, Boolean)
- setUint32(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), littleEndian: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Writes a 32-bit unsigned integer number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.
    - littleEndian - Optional. Default is false. Use true if the little-endian format is to be used.


---

### setUint8(Number, Number)
- setUint8(byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Writes an 8-bit unsigned integer number into the byte array at the given offset.

    **Parameters:**
    - byteOffset - The offset within the view.
    - value - The value to be written.


---

<!-- prettier-ignore-end -->

<!-- document id=9e14889072b9e85606a7566b152712a91e1233c4516d041e6c37b882b9e2a35d url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Date.md -->

<!-- prettier-ignore-start -->
# Class Date

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)

A Date object contains a number indicating a particular instant in time to within a millisecond. The number may also
be NaN, indicating that the Date object does not represent a specific instant of time.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Date](#date)() | Constructs the Date instance using the current date and time. |
| [Date](#datenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs the Date instance using the specified milliseconds. |
| [Date](#datenumber-number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs the Date instance using the specified year and month. |
| [Date](#datestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the Date instance by parsing the specified String. |

## Method Summary

| Method | Description |
| --- | --- |
| static [UTC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#utcnumber-number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the number of milliseconds since midnight of January 1, 1970 according to universal time. |
| [getDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getdate)() | Returns the day of the month where the value is a Number from 1 to 31. |
| [getDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getday)() | Returns the day of the week where the value is a Number from 0 to 6. |
| [getFullYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getfullyear)() | Returns the year of the Date in four-digit format. |
| [getHours](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#gethours)() | Return the hours field of the Date where the value is a Number from 0 (midnight) to 23 (11 PM). |
| [getMilliseconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getmilliseconds)() | Returns the milliseconds field of the Date. |
| [getMinutes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getminutes)() | Return the minutes field of the Date where the value is a Number from 0 to 59. |
| [getMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getmonth)() | Returns the month of the year as a value between 0 and 11. |
| [getSeconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getseconds)() | Return the seconds field of the Date where the value is a Number from 0 to 59. |
| [getTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#gettime)() | Returns the internal, millisecond representation of the Date object. |
| [getTimezoneOffset](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#gettimezoneoffset)() | Returns the difference between local time and Greenwich Mean Time (GMT) in minutes. |
| [getUTCDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutcdate)() | Returns the day of the month where the value is a Number from 1 to 31 when date is expressed in universal time. |
| [getUTCDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutcday)() | Returns the day of the week where the value is a Number from 0 to 6 when date is expressed in universal time. |
| [getUTCFullYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutcfullyear)() | Returns the year when the Date is expressed in universal time. |
| [getUTCHours](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutchours)() | Return the hours field, expressed in universal time, of the Date where the value is a Number from 0 (midnight) to  23 (11 PM). |
| [getUTCMilliseconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutcmilliseconds)() | Returns the milliseconds field, expressed in universal time, of the Date. |
| [getUTCMinutes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutcminutes)() | Return the minutes field, expressed in universal time, of the Date where the value is a Number from 0 to 59. |
| [getUTCMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutcmonth)() | Returns the month of the year that results when the Date is expressed in universal time. |
| [getUTCSeconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#getutcseconds)() | Return the seconds field, expressed in universal time, of the Date where the value is a Number from 0 to 59. |
| static [now](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#now)() | Returns the number of milliseconds since midnight of January 1, 1970 up until now. |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#parsestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Takes a date string and returns the number of milliseconds since midnight of January 1, 1970. |
| [setDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setdatenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the day of the month where the value is a Number from 1 to 31. |
| [setFullYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setfullyearnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the full year of Date where the value must be a four-digit Number. |
| [setHours](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#sethoursnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the hours field of this Date instance. |
| [setMilliseconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setmillisecondsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the milliseconds field of this Date instance. |
| [setMinutes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setminutesnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the minutes field of this Date instance. |
| [setMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setmonthnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the month of the year where the value is a Number from 0 to 11. |
| [setSeconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setsecondsnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the seconds field of this Date instance. |
| [setTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#settimenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the number of milliseconds between the desired date and time and January 1, 1970. |
| [setUTCDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setutcdatenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the day of the month, expressed in universal time, where the value is a Number from 1 to 31. |
| [setUTCFullYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setutcfullyearnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the full year, expressed in universal time, of Date where the value must be a four-digit Number. |
| [setUTCHours](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setutchoursnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the hours field, expressed in universal time, of this Date instance. |
| [setUTCMilliseconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setutcmillisecondsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the milliseconds field, expressed in universal time, of this Date instance. |
| [setUTCMinutes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setutcminutesnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the minutes field, expressed in universal time, of this Date instance. |
| [setUTCMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setutcmonthnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the month of the year, expressed in universal time, where the value is a Number from 0 to 11. |
| [setUTCSeconds](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#setutcsecondsnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the seconds field, expressed in universal time, of this Date instance. |
| [toDateString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#todatestring)() | Returns the Date as a String value where the value represents the _date_ portion of the Date in the default  locale (en\_US). |
| [toISOString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#toisostring)() | This function returns a string value represent the instance in time represented by this Date object. |
| [toJSON](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#tojsonstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This function returns the same string as Date.prototype.toISOString(). |
| [toLocaleDateString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#tolocaledatestring)() | Returns the Date as a String value where the value represents the _date_ portion of the Date in the default  locale (en\_US). |
| [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#tolocalestring)() | Returns the Date as a String using the default locale (en\_US). |
| [toLocaleTimeString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#tolocaletimestring)() | Returns the Date as a String value where the value represents the _time_ portion of the Date in the default  locale (en\_US). |
| [toTimeString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#totimestring)() | Returns the Date as a String value where the value represents the _time_ portion of the Date in the default  locale (en\_US). |
| [toUTCString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#toutcstring)() | Returns a String representation of this Date, expressed in universal time. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md#valueof)() | Returns the value of this Date represented in milliseconds. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### Date()
- Date()
  - : Constructs the Date instance using the current date and time.


---

### Date(Number)
- Date(millis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs the Date instance using the specified milliseconds.

    **Parameters:**
    - millis - the number of milliseconds between the desired date and January 1, 1970 (UTC). For example, value             of 10000 would create a Date instance representing 10 seconds past midnight on January 1, 1970.


---

### Date(Number, Number, Number...)
- Date(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), month: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs the Date instance using the specified year and month. Optionally, you can pass up to five additional
      arguments representing date, hours, minutes, seconds, and milliseconds.


    **Parameters:**
    - year - a number representing the year.
    - month - a number representing the month.
    - args - a set of numbers representing the date, hours, minutes, seconds, and milliseconds.


---

### Date(String)
- Date(dateString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the Date instance by parsing the specified String.

    **Parameters:**
    - dateString - represents a Date in a valid date format.


---

## Method Details

### UTC(Number, Number, Number...)
- static UTC(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), month: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of milliseconds since midnight of January 1, 1970 according to universal time. Optionally, you
      can pass up to five additional arguments representing date, hours, minutes, seconds, and milliseconds.


    **Parameters:**
    - year - a number representing the year.
    - month - a number representing the month.
    - args - a set of numbers representing the date, hours, minutes, seconds, and milliseconds.

    **Returns:**
    - the number of milliseconds since midnight of January 1, 1970 according to universal time.


---

### getDate()
- getDate(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the day of the month where the value is a Number from 1 to 31.

    **Returns:**
    - the day of the month where the value is a Number from 1 to 31.


---

### getDay()
- getDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the day of the week where the value is a Number from 0 to 6.

    **Returns:**
    - the day of the month where the value is a Number from 0 to 6.


---

### getFullYear()
- getFullYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the year of the Date in four-digit format.

    **Returns:**
    - the year of the Date in four-digit format.


---

### getHours()
- getHours(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the hours field of the Date where the value is a Number from 0 (midnight) to 23 (11 PM).

    **Returns:**
    - the hours field of the Date where the value is a Number from 0 (midnight) to 23 (11 PM).


---

### getMilliseconds()
- getMilliseconds(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the milliseconds field of the Date.

    **Returns:**
    - the milliseconds field of the Date.


---

### getMinutes()
- getMinutes(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the minutes field of the Date where the value is a Number from 0 to 59.

    **Returns:**
    - the minutes field of the Date where the value is a Number from 0 to 59.


---

### getMonth()
- getMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the month of the year as a value between 0 and 11.

    **Returns:**
    - the month of the year as a value between 0 and 11.


---

### getSeconds()
- getSeconds(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the seconds field of the Date where the value is a Number from 0 to 59.

    **Returns:**
    - the seconds field of the Date where the value is a Number from 0 to 59.


---

### getTime()
- getTime(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the internal, millisecond representation of the Date object. This value is independent of time zone.

    **Returns:**
    - the internal, millisecond representation of the Date object.


---

### getTimezoneOffset()
- getTimezoneOffset(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the difference between local time and Greenwich Mean Time (GMT) in minutes.

    **Returns:**
    - the difference between local time and Greenwich Mean Time (GMT) in minutes.


---

### getUTCDate()
- getUTCDate(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the day of the month where the value is a Number from 1 to 31 when date is expressed in universal time.

    **Returns:**
    - the day of the month where the value is a Number from 1 to 31 when date is expressed in universal time.


---

### getUTCDay()
- getUTCDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the day of the week where the value is a Number from 0 to 6 when date is expressed in universal time.

    **Returns:**
    - the day of the week where the value is a Number from 0 to 6 when date is expressed in universal time.


---

### getUTCFullYear()
- getUTCFullYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the year when the Date is expressed in universal time. The return value is a four-digit format.

    **Returns:**
    - the year of the Date in four-digit form.


---

### getUTCHours()
- getUTCHours(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the hours field, expressed in universal time, of the Date where the value is a Number from 0 (midnight) to
      23 (11 PM).


    **Returns:**
    - the hours field, expressed in universal time, of the Date where the value is a Number from 0 (midnight)
              to 23 (11 PM).



---

### getUTCMilliseconds()
- getUTCMilliseconds(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the milliseconds field, expressed in universal time, of the Date.

    **Returns:**
    - the milliseconds field, expressed in universal time, of the Date.


---

### getUTCMinutes()
- getUTCMinutes(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the minutes field, expressed in universal time, of the Date where the value is a Number from 0 to 59.

    **Returns:**
    - the minutes field, expressed in universal time, of the Date where the value is a Number from 0 to 59.


---

### getUTCMonth()
- getUTCMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the month of the year that results when the Date is expressed in universal time. The return value is a
      Number betwee 0 and 11.


    **Returns:**
    - the month of the year as a value between 0 and 11.


---

### getUTCSeconds()
- getUTCSeconds(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the seconds field, expressed in universal time, of the Date where the value is a Number from 0 to 59.

    **Returns:**
    - the seconds field, expressed in universal time, of the Date where the value is a Number from 0 to 59.


---

### now()
- static now(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of milliseconds since midnight of January 1, 1970 up until now.

    **Returns:**
    - the number of milliseconds since midnight of January 1, 1970.


---

### parse(String)
- static parse(dateString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Takes a date string and returns the number of milliseconds since midnight of January 1, 1970.
      
      Supports:
      
      - RFC2822 date strings
      - strings matching the exact ISO 8601 format 'YYYY-MM-DDTHH:mm:ss.sssZ'


    **Parameters:**
    - dateString - represents a Date in a valid date format.

    **Returns:**
    - the number of milliseconds since midnight of January 1, 1970 or NaN if no date could be recognized.


---

### setDate(Number)
- setDate(date: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the day of the month where the value is a Number from 1 to 31.

    **Parameters:**
    - date - the day of the month.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setFullYear(Number, Number...)
- setFullYear(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the full year of Date where the value must be a four-digit Number. Optionally, you can set the month and
      date.


    **Parameters:**
    - year - the year as a four-digit Number.
    - args - the month and day of the month.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setHours(Number, Number...)
- setHours(hours: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the hours field of this Date instance. The minutes value should be a Number from 0 to 23. Optionally, hours,
      seconds and milliseconds can also be provided.


    **Parameters:**
    - hours - the minutes field of this Date instance.
    - args - the hours, seconds and milliseconds values for this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setMilliseconds(Number)
- setMilliseconds(millis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the milliseconds field of this Date instance.

    **Parameters:**
    - millis - the milliseconds field of this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setMinutes(Number, Number...)
- setMinutes(minutes: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the minutes field of this Date instance. The minutes value should be a Number from 0 to 59. Optionally,
      seconds and milliseconds can also be provided.


    **Parameters:**
    - minutes - the minutes field of this Date instance.
    - args - the seconds and milliseconds value for this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setMonth(Number, Number...)
- setMonth(month: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), date: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the month of the year where the value is a Number from 0 to 11. Optionally, you can set the day of the
      month.


    **Parameters:**
    - month - the month of the year.
    - date - the day of the month.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setSeconds(Number, Number...)
- setSeconds(seconds: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), millis: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the seconds field of this Date instance. The seconds value should be a Number from 0 to 59. Optionally,
      milliseconds can also be provided.


    **Parameters:**
    - seconds - the seconds field of this Date instance.
    - millis - the milliseconds field of this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setTime(Number)
- setTime(millis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the number of milliseconds between the desired date and time and January 1, 1970.

    **Parameters:**
    - millis - the number of milliseconds between the desired date and time and January 1, 1970.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setUTCDate(Number)
- setUTCDate(date: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the day of the month, expressed in universal time, where the value is a Number from 1 to 31.

    **Parameters:**
    - date - the day of the month, expressed in universal time.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setUTCFullYear(Number, Number...)
- setUTCFullYear(year: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the full year, expressed in universal time, of Date where the value must be a four-digit Number. Optionally,
      you can set the month and date.


    **Parameters:**
    - year - the year as a four-digit Number, expressed in universal time.
    - args - the month and day of the month.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setUTCHours(Number, Number...)
- setUTCHours(hours: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the hours field, expressed in universal time, of this Date instance. The minutes value should be a Number
      from 0 to 23. Optionally, seconds and milliseconds can also be provided.


    **Parameters:**
    - hours - the minutes field, expressed in universal time, of this Date instance.
    - args - the seconds and milliseconds value, expressed in universal time, for this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setUTCMilliseconds(Number)
- setUTCMilliseconds(millis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the milliseconds field, expressed in universal time, of this Date instance.

    **Parameters:**
    - millis - the milliseconds field, expressed in universal time, of this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setUTCMinutes(Number, Number...)
- setUTCMinutes(minutes: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), args: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the minutes field, expressed in universal time, of this Date instance. The minutes value should be a Number
      from 0 to 59. Optionally, seconds and milliseconds can also be provided.


    **Parameters:**
    - minutes - the minutes field, expressed in universal time, of this Date instance.
    - args - the seconds and milliseconds values, expressed in universal time, for this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setUTCMonth(Number, Number...)
- setUTCMonth(month: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), date: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the month of the year, expressed in universal time, where the value is a Number from 0 to 11. Optionally,
      you can set the day of the month.


    **Parameters:**
    - month - the month of the year, expressed in universal time.
    - date - the day of the month.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### setUTCSeconds(Number, Number...)
- setUTCSeconds(seconds: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), millis: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Sets the seconds field, expressed in universal time, of this Date instance. The seconds value should be a Number
      from 0 to 59. Optionally, milliseconds can also be provided.


    **Parameters:**
    - seconds - the seconds field, expressed in universal time, of this Date instance.
    - millis - the milliseconds field, expressed in universal time, of this Date instance.

    **Returns:**
    - the millisecond representation of the adjusted date.


---

### toDateString()
- toDateString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Date as a String value where the value represents the _date_ portion of the Date in the default
      locale (en\_US). To format a calendar object in an alternate format use the
      `dw.util.StringUtils.formatCalendar()` functions instead.


    **Returns:**
    - the Date as a String value.


---

### toISOString()
- toISOString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : This function returns a string value represent the instance in time represented by this Date object. The date is
      formatted with the Simplified ISO 8601 format as follows: YYYY-MM-DDTHH:mm:ss.sssTZ. The time zone is always UTC,
      denoted by the suffix Z.


    **Returns:**
    - string representation of this date


---

### toJSON(String)
- toJSON(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : This function returns the same string as Date.prototype.toISOString(). The method is called when a Date object is
      stringified.


    **Parameters:**
    - key - the name of the key, which is stringified

    **Returns:**
    - JSON string representation of this date


---

### toLocaleDateString()
- toLocaleDateString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Date as a String value where the value represents the _date_ portion of the Date in the default
      locale (en\_US). To format a calendar object in an alternate format use the
      `dw.util.StringUtils.formatCalendar()` functions instead.


    **Returns:**
    - returns the _date_ portion of the Date as a String.


---

### toLocaleString()
- toLocaleString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Date as a String using the default locale (en\_US). To format a calendar object in an alternate format
      use the `dw.util.StringUtils.formatCalendar()` functions instead.


    **Returns:**
    - the Date as a String using the default locale en\_US


---

### toLocaleTimeString()
- toLocaleTimeString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Date as a String value where the value represents the _time_ portion of the Date in the default
      locale (en\_US). To format a calendar object in an alternate format use the
      `dw.util.StringUtils.formatCalendar()` functions instead.


    **Returns:**
    - returns the _time_ time's portion of the Date as a String.


---

### toTimeString()
- toTimeString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Date as a String value where the value represents the _time_ portion of the Date in the default
      locale (en\_US). To format a calendar object in an alternate format use the
      `dw.util.StringUtils.formatCalendar()` functions instead.


    **Returns:**
    - the Date's time.


---

### toUTCString()
- toUTCString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a String representation of this Date, expressed in universal time.

    **Returns:**
    - a String representation of this Date, expressed in universal time.


---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value of this Date represented in milliseconds.

    **Returns:**
    - the value of this Date represented in milliseconds.


---

<!-- prettier-ignore-end -->

<!-- document id=3ebd4ce3bf009eca4a21d79266bbacd5e49c83559d1df12e260bbea9733ce865 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.DateUtils.md -->

<!-- prettier-ignore-start -->
# Class DateUtils

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.DateUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.DateUtils.md)

A class with several utility methods for Date objects.

**Deprecated:**
**warning:** See each method for additional information.

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| ~~static [nowForInstance](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.DateUtils.md#nowforinstance)()~~ | Returns the current time stamp in the time zone of the  instance. |
| ~~static [nowForSite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.DateUtils.md#nowforsite)()~~ | Returns the current timestamp in the time zone of the   current site. |
| ~~static [nowInUTC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.DateUtils.md#nowinutc)()~~ | Returns the current time stamp in UTC. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### nowForInstance()
- ~~static nowForInstance(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)~~
  - : Returns the current time stamp in the time zone of the
      instance.


    **Returns:**
    - the current time stamp in the time zone of the
      instance.


    **Deprecated:**
**warning:** Use [System.getCalendar()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getcalendar) instead.

---

### nowForSite()
- ~~static nowForSite(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)~~
  - : Returns the current timestamp in the time zone of the 
      current site.


    **Returns:**
    - the current timestamp in the time zone of the
      current site.


    **Deprecated:**
**warning:** Use [Site.getCalendar()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getcalendar) instead.

---

### nowInUTC()
- ~~static nowInUTC(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)~~
  - : Returns the current time stamp in UTC.

    **Returns:**
    - the current time stamp in UTC.

    **Deprecated:**
**warning:** Create a new [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md) object and set
            the time zone "UTC" instead.

---

<!-- prettier-ignore-end -->

<!-- document id=df391db548bebb87e158e3055d2d7cf79eb6dac6b2dc3ee6cb08851dc831363c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Decimal.md -->

<!-- prettier-ignore-start -->
# Class Decimal

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)

The Decimal class is a helper class to perform decimal arithmetic in
scripts and to represent a decimal number with arbitrary length. The decimal
class avoids arithmetic errors, which are typical for calculating with
floating numbers, that are based on a binary mantissa.


The class is designed in a way that it can be used very similar to a
desktop calculator.


```
var d = new Decimal( 10.0 );
var result = d.add( 2.0 ).sub( 3.0 ).get();
```



The above code will return 9 as result.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Decimal](#decimal)() | Constructs a new Decimal with the value 0. |
| [Decimal](#decimalnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a new decimal using the specified Number value. |
| [Decimal](#decimalbigint)([BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)) | Constructs a new decimal using the specified BigInt value. |
| [Decimal](#decimalstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new Decimal using the specified string representation of  a number. |

## Method Summary

| Method | Description |
| --- | --- |
| [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#abs)() | Returns a new Decimal with the absolute value of this Decimal. |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#addnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Adds a Number value to this Decimal and returns the new Decimal. |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#adddecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Adds a Decimal value to this Decimal and returns the new Decimal. |
| [addPercent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#addpercentnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Adds a percentage value to the current value of the  decimal. |
| [addPercent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#addpercentdecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Adds a percentage value to the current value of the  decimal. |
| [divide](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#dividenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Divides the specified Number value with this decimal and returns the new  decimal. |
| [divide](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#dividedecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Divides the specified Decimal value with this decimal and returns the new  decimal. |
| [equals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#equalsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Compares two decimal values whether they are equivalent. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#get)() | Returns the value of the Decimal as a Number. |
| [hashCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#hashcode)() | Calculates the hash code for this decimal; |
| [multiply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#multiplynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Multiples the specified Number value with this Decimal and returns the new Decimal. |
| [multiply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#multiplydecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Multiples the specified Decimal value with this Decimal and returns the new Decimal. |
| [negate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#negate)() | Returns a new Decimal with the negated value of this Decimal. |
| [round](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#roundnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Rounds the current value of the decimal using the specified  number of decimals. |
| [subtract](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#subtractnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Subtracts the specified Number value from this Decimal and returns the new Decimal. |
| [subtract](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#subtractdecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Subtracts the specified Decimal value from this Decimal and returns the new Decimal. |
| [subtractPercent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#subtractpercentnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Subtracts a percentage value from the current value of the  decimal. |
| [subtractPercent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#subtractpercentdecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Subtracts a percentage value from the current value of the  decimal. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#tostring)() | Returns a string representation of this object. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md#valueof)() | The valueOf() method is called by the ECMAScript interpret to return  the "natural" value of an object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### Decimal()
- Decimal()
  - : Constructs a new Decimal with the value 0.


---

### Decimal(Number)
- Decimal(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs a new decimal using the specified Number value.

    **Parameters:**
    - value - the value to use.


---

### Decimal(BigInt)
- Decimal(value: [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md))
  - : Constructs a new decimal using the specified BigInt value.

    **Parameters:**
    - value - the value to use.

    **API Version:**
**note:** Available from version 22.7.

---

### Decimal(String)
- Decimal(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a new Decimal using the specified string representation of
      a number.


    **Parameters:**
    - value - the value to use.


---

## Method Details

### abs()
- abs(): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Returns a new Decimal with the absolute value of this Decimal.

    **Returns:**
    - the new Decimal


---

### add(Number)
- add(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Adds a Number value to this Decimal and returns the new Decimal.

    **Parameters:**
    - value - the value to add to this decimal.

    **Returns:**
    - the new decimal with the value added.


---

### add(Decimal)
- add(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Adds a Decimal value to this Decimal and returns the new Decimal.

    **Parameters:**
    - value - the value to add to this decimal.

    **Returns:**
    - the new decimal with the value added.


---

### addPercent(Number)
- addPercent(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Adds a percentage value to the current value of the
      decimal. For example a value of 10 represent 10% or a value of
      85 represents 85%.


    **Parameters:**
    - value - the value to add.

    **Returns:**
    - a new decimal with the added percentage value.


---

### addPercent(Decimal)
- addPercent(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Adds a percentage value to the current value of the
      decimal. For example a value of 10 represent 10% or a value of
      85 represents 85%.


    **Parameters:**
    - value - the value to add.

    **Returns:**
    - a new decimal with the added percentage value.


---

### divide(Number)
- divide(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Divides the specified Number value with this decimal and returns the new
      decimal.
      
      When performing the division, 34 digits precision and a rounding mode of
      HALF\_EVEN is used to prevent quotients with nonterminating decimal
      expansions.


    **Parameters:**
    - value - the value to use to divide this decimal.

    **Returns:**
    - the new decimal.


---

### divide(Decimal)
- divide(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Divides the specified Decimal value with this decimal and returns the new
      decimal.
      
      When performing the division, 34 digits precision and a rounding mode of
      HALF\_EVEN is used to prevent quotients with nonterminating decimal
      expansions.


    **Parameters:**
    - value - the value to use to divide this decimal.

    **Returns:**
    - the new decimal.


---

### equals(Object)
- equals(other: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Compares two decimal values whether they are equivalent.

    **Parameters:**
    - other - the object to comapre against this decimal.


---

### get()
- get(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the Decimal as a Number.

    **Returns:**
    - the value of the Decimal.


---

### hashCode()
- hashCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Calculates the hash code for this decimal;


---

### multiply(Number)
- multiply(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Multiples the specified Number value with this Decimal and returns the new Decimal.

    **Parameters:**
    - value - the value to multiply with this decimal.

    **Returns:**
    - the new decimal.


---

### multiply(Decimal)
- multiply(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Multiples the specified Decimal value with this Decimal and returns the new Decimal.

    **Parameters:**
    - value - the value to multiply with this decimal.

    **Returns:**
    - the new decimal.


---

### negate()
- negate(): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Returns a new Decimal with the negated value of this Decimal.

    **Returns:**
    - the new Decimal


---

### round(Number)
- round(decimals: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Rounds the current value of the decimal using the specified
      number of decimals. The parameter
      specifies the number of digest after the decimal point.


    **Parameters:**
    - decimals - the number of decimals to use.

    **Returns:**
    - the decimal that has been rounded.


---

### subtract(Number)
- subtract(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Subtracts the specified Number value from this Decimal and returns the new Decimal.

    **Parameters:**
    - value - the value to add to this decimal.

    **Returns:**
    - the new decimal with the value subtraced.


---

### subtract(Decimal)
- subtract(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Subtracts the specified Decimal value from this Decimal and returns the new Decimal.

    **Parameters:**
    - value - the value to add to this decimal.

    **Returns:**
    - the new decimal with the value subtraced.


---

### subtractPercent(Number)
- subtractPercent(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Subtracts a percentage value from the current value of the
      decimal. For example a value of 10 represent 10% or a value of
      85 represents 85%.


    **Parameters:**
    - value - the value to subtract.

    **Returns:**
    - a new decimal with the subtracted percentage value.


---

### subtractPercent(Decimal)
- subtractPercent(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Subtracts a percentage value from the current value of the
      decimal. For example a value of 10 represent 10% or a value of
      85 represents 85%.


    **Parameters:**
    - value - the value to subtract.

    **Returns:**
    - a new decimal with the subtracted percentage value.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this object.

    **Returns:**
    - a string representation of this object.


---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : The valueOf() method is called by the ECMAScript interpret to return
      the "natural" value of an object. The Decimal object returns its
      current value as number. With this behavior script snippets can
      be written like:
      
      `
       var d = new Decimal( 10.0 );
       var x = 1.0 + d.add( 2.0 );
       `
      
      where x will be at the end 13.0.


    **Returns:**
    - the value of this object.


---

<!-- prettier-ignore-end -->

<!-- document id=84df228642fb2ff9e6a0a5515143df33cbe7ded68109366c23c6cc28451b84dc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.Discount.md -->

<!-- prettier-ignore-start -->
# Class Discount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)

Superclass of all specific discount classes.


## All Known Subclasses
[AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md), [BonusChoiceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md), [BonusDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusDiscount.md), [FixedPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceDiscount.md), [FixedPriceShippingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceShippingDiscount.md), [FreeDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FreeDiscount.md), [FreeShippingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FreeShippingDiscount.md), [PercentageDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageDiscount.md), [PercentageOptionDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageOptionDiscount.md), [PriceBookPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PriceBookPriceDiscount.md), [TotalFixedPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.TotalFixedPriceDiscount.md)
## Constant Summary

| Constant | Description |
| --- | --- |
| [TYPE_AMOUNT](#type_amount): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AMOUNT" | Constant representing discounts of type _amount_. |
| [TYPE_BONUS](#type_bonus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BONUS" | Constant representing discounts of type _bonus_. |
| [TYPE_BONUS_CHOICE](#type_bonus_choice): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BONUS_CHOICE" | Constant representing discounts of type _bonus choice_. |
| [TYPE_FIXED_PRICE](#type_fixed_price): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FIXED_PRICE" | Constant representing discounts of type _fixed-price_. |
| [TYPE_FIXED_PRICE_SHIPPING](#type_fixed_price_shipping): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FIXED_PRICE_SHIPPING" | Constant representing discounts of type _fixed price shipping_. |
| [TYPE_FREE](#type_free): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FREE" | Constant representing discounts of type _free_. |
| [TYPE_FREE_SHIPPING](#type_free_shipping): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FREE_SHIPPING" | Constant representing discounts of type _free shipping_. |
| [TYPE_PERCENTAGE](#type_percentage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PERCENTAGE" | Constant representing discounts of type _percentage_. |
| [TYPE_PERCENTAGE_OFF_OPTIONS](#type_percentage_off_options): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PERCENTAGE_OFF_OPTIONS" | Constant representing discounts of type _percent off options_. |
| [TYPE_PRICEBOOK_PRICE](#type_pricebook_price): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRICE_BOOK_PRICE" | Constant representing discounts of type _price book price_. |
| [TYPE_TOTAL_FIXED_PRICE](#type_total_fixed_price): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TOTAL_FIXED_PRICE" | Constant representing discounts of type _total fixed price_. |

## Property Summary

| Property | Description |
| --- | --- |
| [itemPromotionTiers](#itempromotiontiers): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the tier index by quantity Id of Product promotion. |
| [promotion](#promotion): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) `(read-only)` | Returns the promotion this discount is based on. |
| [promotionTier](#promotiontier): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the tier index for promotion at order level or bonus product. |
| [quantity](#quantity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the quantity of the discount. |
| [type](#type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of the discount. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers)() | Returns the tier index by quantity Id of Product promotion. |
| [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion)() | Returns the promotion this discount is based on. |
| [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier)() | Returns the tier index for promotion at order level or bonus product. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity)() | Returns the quantity of the discount. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)() | Returns the type of the discount. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TYPE_AMOUNT

- TYPE_AMOUNT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AMOUNT"
  - : Constant representing discounts of type _amount_.


---

### TYPE_BONUS

- TYPE_BONUS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BONUS"
  - : Constant representing discounts of type _bonus_.


---

### TYPE_BONUS_CHOICE

- TYPE_BONUS_CHOICE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BONUS_CHOICE"
  - : Constant representing discounts of type _bonus choice_.


---

### TYPE_FIXED_PRICE

- TYPE_FIXED_PRICE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FIXED_PRICE"
  - : Constant representing discounts of type _fixed-price_.


---

### TYPE_FIXED_PRICE_SHIPPING

- TYPE_FIXED_PRICE_SHIPPING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FIXED_PRICE_SHIPPING"
  - : Constant representing discounts of type _fixed price shipping_.


---

### TYPE_FREE

- TYPE_FREE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FREE"
  - : Constant representing discounts of type _free_.


---

### TYPE_FREE_SHIPPING

- TYPE_FREE_SHIPPING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FREE_SHIPPING"
  - : Constant representing discounts of type _free shipping_.


---

### TYPE_PERCENTAGE

- TYPE_PERCENTAGE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PERCENTAGE"
  - : Constant representing discounts of type _percentage_.


---

### TYPE_PERCENTAGE_OFF_OPTIONS

- TYPE_PERCENTAGE_OFF_OPTIONS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PERCENTAGE_OFF_OPTIONS"
  - : Constant representing discounts of type _percent off options_.


---

### TYPE_PRICEBOOK_PRICE

- TYPE_PRICEBOOK_PRICE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRICE_BOOK_PRICE"
  - : Constant representing discounts of type _price book price_.


---

### TYPE_TOTAL_FIXED_PRICE

- TYPE_TOTAL_FIXED_PRICE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TOTAL_FIXED_PRICE"
  - : Constant representing discounts of type _total fixed price_.


---

## Property Details

### itemPromotionTiers
- itemPromotionTiers: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the tier index by quantity Id of Product promotion. ProductLineItems may have more than one quantity, but
      not all items of that SKU may have received the same tier of promotion. Each quantity of the ProductLineItem is
      indexed from 1 to n, where n is the quantity of the ProductLineItem, and this method returns a mapping from that
      quantity index to the index of tier of the promotion that item received. For more information about tier indexes,
      see [getPromotionTier()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier)  method.


    **See Also:**
    - [getPromotionTier()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier)


---

### promotion
- promotion: [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) `(read-only)`
  - : Returns the promotion this discount is based on.


---

### promotionTier
- promotionTier: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the tier index for promotion at order level or bonus product.
      Promotion tiers are always evaluated in the order of the highest threshold (e.g. quantity, or amount)
      to the lowest threshold. The tier that is evaluated first (i.e. the highest quantity or amount) is indexed as 0,
      the next tier 1, etc. The lowest tier will have index n - 1, where n is the total number of tiers.



---

### quantity
- quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the quantity of the discount. This quantity specifies how often
      this discount applies to its target object. For example, a 10% off
      discount with quantity 2 associated to a product line item with
      quantity 3 is applied to two items of the product line item. 
      
      Discounts of order and shipping promotions, and bonus discounts
      have a fix quantity of 1.



---

### type
- type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of the discount.


---

## Method Details

### getItemPromotionTiers()
- getItemPromotionTiers(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the tier index by quantity Id of Product promotion. ProductLineItems may have more than one quantity, but
      not all items of that SKU may have received the same tier of promotion. Each quantity of the ProductLineItem is
      indexed from 1 to n, where n is the quantity of the ProductLineItem, and this method returns a mapping from that
      quantity index to the index of tier of the promotion that item received. For more information about tier indexes,
      see [getPromotionTier()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier)  method.


    **Returns:**
    - Map of Tier index by quantity Id or `empty map`

    **See Also:**
    - [getPromotionTier()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier)


---

### getPromotion()
- getPromotion(): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)
  - : Returns the promotion this discount is based on.

    **Returns:**
    - Promotion related to this discount


---

### getPromotionTier()
- getPromotionTier(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the tier index for promotion at order level or bonus product.
      Promotion tiers are always evaluated in the order of the highest threshold (e.g. quantity, or amount)
      to the lowest threshold. The tier that is evaluated first (i.e. the highest quantity or amount) is indexed as 0,
      the next tier 1, etc. The lowest tier will have index n - 1, where n is the total number of tiers.


    **Returns:**
    - Tier index or `null`


---

### getQuantity()
- getQuantity(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the quantity of the discount. This quantity specifies how often
      this discount applies to its target object. For example, a 10% off
      discount with quantity 2 associated to a product line item with
      quantity 3 is applied to two items of the product line item. 
      
      Discounts of order and shipping promotions, and bonus discounts
      have a fix quantity of 1.


    **Returns:**
    - Discount quantity


---

### getType()
- getType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the discount.

    **Returns:**
    - Discount type


---

<!-- prettier-ignore-end -->

<!-- document id=d4a7310237ce1fc4dd9abe9bdf69e41b476459c69407d79d5c9a4b2f34ff9f5e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.DiscountPlan.md -->

<!-- prettier-ignore-start -->
# Class DiscountPlan

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md)

DiscountPlan represents a set of [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)s. Instances of the class are
returned by the [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) when requesting applicable discounts
for a specified set of promotions and a line item container
(see [PromotionMgr.getDiscounts(LineItemCtnr, PromotionPlan)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr-promotionplan)).


DiscountPlan provides methods to access the discounts contained in the plan,
add additional discounts to the plan (future) or remove discounts from the plan.


**See Also:**
- [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md)


## Property Summary

| Property | Description |
| --- | --- |
| [approachingOrderDiscounts](#approachingorderdiscounts): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Get the collection of order discounts that the LineItemCtnr "almost"  qualifies for based on the merchandise total in the cart. |
| [bonusDiscounts](#bonusdiscounts): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all bonus discounts contained in the discount plan. |
| [lineItemCtnr](#lineitemctnr): [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md) `(read-only)` | Returns line item container associated with discount plan. |
| [orderDiscounts](#orderdiscounts): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the percentage and amount order discounts contained in the  discount plan. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getApproachingOrderDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getapproachingorderdiscounts)() | Get the collection of order discounts that the LineItemCtnr "almost"  qualifies for based on the merchandise total in the cart. |
| [getApproachingShippingDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getapproachingshippingdiscountsshipment)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Get the collection of shipping discounts that the passed shipment  "almost" qualifies for based on the merchandise total in the shipment. |
| [getApproachingShippingDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getapproachingshippingdiscountsshipment-shippingmethod)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)) | Get the collection of shipping discounts that the passed shipment  "almost" qualifies for based on the merchandise total in the shipment. |
| [getApproachingShippingDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getapproachingshippingdiscountsshipment-collection)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Get the collection of shipping discounts that the passed shipment  "almost" qualifies for based on the merchandise total in the shipment. |
| [getBonusDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getbonusdiscounts)() | Returns all bonus discounts contained in the discount plan. |
| [getLineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getlineitemctnr)() | Returns line item container associated with discount plan. |
| [getOrderDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getorderdiscounts)() | Returns the percentage and amount order discounts contained in the  discount plan. |
| [getProductDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getproductdiscountsproductlineitem)([ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)) | Returns the percentage, amount and fix price discounts associated  with the specified product line item. |
| [getProductShippingDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getproductshippingdiscountsproductlineitem)([ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)) | Returns the product-shipping discounts associated with the specified  product line item. |
| [getShippingDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#getshippingdiscountsshipment)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Returns the percentage, amount and fix price discounts associated with  the specified shipment. |
| [removeDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md#removediscountdiscount)([Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)) | Removes the specified discount from the discount plan. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### approachingOrderDiscounts
- approachingOrderDiscounts: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Get the collection of order discounts that the LineItemCtnr "almost"
      qualifies for based on the merchandise total in the cart. Nearness is
      controlled by thresholds configured at the promotion level.
      
      
      The collection of returned approaching discounts is ordered by the
      condition threshold of the promotion (e.g. "spend $100 and get 10% off"
      discount is returned before "spend $150 and get 15% off" discount.) A
      discount is not returned if it would be prevented from applying (because
      of compatibility rules) by an order discount already in the DiscountPlan
      or an approaching order discount with a lower condition threshold.



---

### bonusDiscounts
- bonusDiscounts: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all bonus discounts contained in the discount plan.


---

### lineItemCtnr
- lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md) `(read-only)`
  - : Returns line item container associated with discount plan. 
      
      A discount plan is created from and associated with a line item container.
      This method returns the line item container associated with this discount plan.



---

### orderDiscounts
- orderDiscounts: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the percentage and amount order discounts contained in the
      discount plan.



---

## Method Details

### getApproachingOrderDiscounts()
- getApproachingOrderDiscounts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Get the collection of order discounts that the LineItemCtnr "almost"
      qualifies for based on the merchandise total in the cart. Nearness is
      controlled by thresholds configured at the promotion level.
      
      
      The collection of returned approaching discounts is ordered by the
      condition threshold of the promotion (e.g. "spend $100 and get 10% off"
      discount is returned before "spend $150 and get 15% off" discount.) A
      discount is not returned if it would be prevented from applying (because
      of compatibility rules) by an order discount already in the DiscountPlan
      or an approaching order discount with a lower condition threshold.


    **Returns:**
    - Collection of approaching order discounts ordered by the
              condition threshold of the promotion ascending.



---

### getApproachingShippingDiscounts(Shipment)
- getApproachingShippingDiscounts(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Get the collection of shipping discounts that the passed shipment
      "almost" qualifies for based on the merchandise total in the shipment.
      Nearness is controlled by thresholds configured at the promotion level.
      
      
      The collection of returned approaching discounts is ordered by the
      condition threshold of the promotion (e.g.
      "spend $100 and get free standard shipping" discount is returned before
      "spend $150 and get free standard shipping" discount.) A discount is not
      returned if it would be prevented from applying (because of compatibility
      rules) by a shipping discount already in the DiscountPlan or an
      approaching shipping discount with a lower condition threshold.


    **Parameters:**
    - shipment - The shipment to calculate approaching discounts for.

    **Returns:**
    - Collection of approaching shipping discounts ordered by the
              condition threshold of the promotion ascending.



---

### getApproachingShippingDiscounts(Shipment, ShippingMethod)
- getApproachingShippingDiscounts(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Get the collection of shipping discounts that the passed shipment
      "almost" qualifies for based on the merchandise total in the shipment.
      Here "almost" is controlled by thresholds configured at the promotion
      level.
      
      
      This method only returns discounts for shipping promotions which apply to
      the passed shipping method.
      
      
      The collection of returned approaching discounts is ordered by the
      condition threshold of the promotion (e.g.
      "spend $100 and get free standard shipping" discount is returned before
      "spend $150 and get free standard shipping" discount.) A discount is not
      returned if it would be prevented from applying (because of compatibility
      rules) by a shipping discount already in the DiscountPlan or an
      approaching shipping discount with a lower condition threshold.


    **Parameters:**
    - shipment - The shipment to calculate approaching discounts for.
    - shippingMethod - The shipping method to filter by.

    **Returns:**
    - Collection of approaching shipping discounts ordered by the
              condition threshold of the promotion, ascending.



---

### getApproachingShippingDiscounts(Shipment, Collection)
- getApproachingShippingDiscounts(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), shippingMethods: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Get the collection of shipping discounts that the passed shipment
      "almost" qualifies for based on the merchandise total in the shipment.
      Here "almost" is controlled by thresholds configured at the promotion
      level.
      
      
      This method only returns discounts for shipping promotions which apply to
      one of the passed shipping methods.
      
      
      The collection of returned approaching discounts is ordered by the
      condition threshold of the promotion (e.g.
      "spend $100 and get free standard shipping" discount is returned before
      "spend $150 and get free standard shipping" discount.) A discount is not
      returned if it would be prevented from applying (because of compatibility
      rules) by a shipping discount already in the DiscountPlan or an
      approaching shipping discount with a lower condition threshold.


    **Parameters:**
    - shipment - The shipment to calculate approaching discounts for.
    - shippingMethods - The shipping methods to filter by.

    **Returns:**
    - Collection of approaching shipping discounts ordered by the
              condition threshold of the promotion ascending.



---

### getBonusDiscounts()
- getBonusDiscounts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all bonus discounts contained in the discount plan.

    **Returns:**
    - All bonus discounts contained in discount plan


---

### getLineItemCtnr()
- getLineItemCtnr(): [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)
  - : Returns line item container associated with discount plan. 
      
      A discount plan is created from and associated with a line item container.
      This method returns the line item container associated with this discount plan.


    **Returns:**
    - Line item container associated with plan


---

### getOrderDiscounts()
- getOrderDiscounts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the percentage and amount order discounts contained in the
      discount plan.


    **Returns:**
    - Order discounts contained in the discount plan


---

### getProductDiscounts(ProductLineItem)
- getProductDiscounts(productLineItem: [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the percentage, amount and fix price discounts associated
      with the specified product line item. If the specified product line
      item is not contained in the discount plan, an empty collection is
      returned.


    **Parameters:**
    - productLineItem - Product line item

    **Returns:**
    - Discounts associated with specified product line item


---

### getProductShippingDiscounts(ProductLineItem)
- getProductShippingDiscounts(productLineItem: [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the product-shipping discounts associated with the specified
      product line item. If the specified product line item is not contained in
      the discount plan, an empty collection is returned.


    **Parameters:**
    - productLineItem - Product line item

    **Returns:**
    - Product-shipping discounts associated with specified product line
              item



---

### getShippingDiscounts(Shipment)
- getShippingDiscounts(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the percentage, amount and fix price discounts associated with
      the specified shipment. If the specified shipment is not contained in
      the discount plan, an empty collection is returned.


    **Parameters:**
    - shipment - the shipment for which to fetch discounts.

    **Returns:**
    - Discounts associated with specified shipment


---

### removeDiscount(Discount)
- removeDiscount(discount: [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)): void
  - : Removes the specified discount from the discount plan. 
      
      
      This method should only be used for very simple discount scenarios. It
      is not recommended to use the method in case of stacked discounts
      (i.e. multiple order or product discounts), or complex discount types
      like Buy X Get Y or Total Fixed Price, since correct re-calculation of the
      discount plan based on the promotion rules is not guaranteed.


    **Parameters:**
    - discount - Discount to be removed


---

<!-- prettier-ignore-end -->

<!-- document id=629adc3241d70519f1bf0b3b4a70a1618085efbc09181f1ba01234fcfd19c70d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.Encoding.md -->

<!-- prettier-ignore-start -->
# Class Encoding

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.Encoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md)

Utility class which handles several common character encodings.


## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [fromBase64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#frombase64string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Decode the given string which represents a sequence of characters encoded in base-64 to a byte array. |
| static [fromHex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#fromhexstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Converts a String representing hexadecimal values into an array of bytes  of those same values. |
| static [fromURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#fromuristring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Decodes a URL safe string into its original form. |
| static [fromURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#fromuristring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Decodes a URL safe string into its original form using the specified  encoding. |
| static [toBase64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#tobase64bytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Convert the given byte array to a string encoded in base-64. |
| static [toBase64URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#tobase64urlbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Convert the given byte array to a string encoded in base-64 for URLs. |
| static [toHex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#tohexbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Converts an array of bytes into a string representing the hexadecimal  values of each byte in order. |
| static [toURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#touristring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Encodes a string into its URL safe form according to the  "application/x-www-form-urlencoded" encoding scheme using the default  encoding. |
| static [toURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md#touristring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Encodes a string into its URL safe form according to the  "application/x-www-form-urlencoded" encoding scheme using the specified  encoding. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### fromBase64(String)
- static fromBase64(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Decode the given string which represents a sequence of characters encoded in base-64 to a byte array. This
      operation supports both the base-64 and base-64 for URL formats. Characters not in the base-64 alphabet are
      ignored. An exception is thrown if a null value is passed.
      
      
      Note: This decoding operation is limited to the maximum number of bytes that a Bytes object can hold. See
      [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md).


    **Parameters:**
    - string - A string consisting of characters in base-64 alphabet to decode.

    **Returns:**
    - The decoded array of bytes.


---

### fromHex(String)
- static fromHex(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Converts a String representing hexadecimal values into an array of bytes
      of those same values. The returned byte array will be half the length of
      the passed, as it takes two characters to represent any given byte. An
      exception is thrown if the passed string has an odd number of character
      or if any characters in the string are not valid hexadecimal characters.
      An exception is thrown if a null value is passed.
      
      Note: This decoding operation is limited to the maximum number of bytes
      that a Bytes object can hold. See [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md).


    **Parameters:**
    - string - A string containing only hex characters to decode.

    **Returns:**
    - The decoded array of bytes.


---

### fromURI(String)
- static fromURI(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decodes a URL safe string into its original form. Escaped characters are
      converted back to their original representation. An exception is thrown
      if URL decoding is unsuccessful or if null is passed.


    **Parameters:**
    - string - The string to decode.

    **Returns:**
    - The decoded string.


---

### fromURI(String, String)
- static fromURI(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decodes a URL safe string into its original form using the specified
      encoding. Escaped characters are converted back to their original
      representation. An exception is thrown if URL decoding is unsuccessful or
      if the specified encoding is unsupported or if null is passed for either
      argument.


    **Parameters:**
    - string - The string to decode.
    - encoding - The name of a supported encoding.

    **Returns:**
    - The decoded string.


---

### toBase64(Bytes)
- static toBase64(bytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Convert the given byte array to a string encoded in base-64.  This method
      does not chunk the data by adding line breaks.  An exception is thrown
      if a null value is passed.


    **Parameters:**
    - bytes - The array of bytes to encode.

    **Returns:**
    - The encoded string containing only Base64 characters.


---

### toBase64URL(Bytes)
- static toBase64URL(bytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Convert the given byte array to a string encoded in base-64 for URLs.  This method does not chunk the data by
      adding line breaks and it does not add any padding.  An exception is thrown if a null value is passed.


    **Parameters:**
    - bytes - The array of bytes to encode.

    **Returns:**
    - The encoded string containing only Base64URL characters.


---

### toHex(Bytes)
- static toHex(bytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts an array of bytes into a string representing the hexadecimal
      values of each byte in order. The returned string will be double the
      length of the passed array, as it takes two characters to represent any
      given byte. An exception is thrown if a null value is passed.


    **Parameters:**
    - bytes - The array of bytes to encode.

    **Returns:**
    - The encoded string containing only hex characters.


---

### toURI(String)
- static toURI(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encodes a string into its URL safe form according to the
      "application/x-www-form-urlencoded" encoding scheme using the default
      encoding. Unsafe characters are escaped. An exception is thrown if a null
      value is passed.


    **Parameters:**
    - string - The string to encode.

    **Returns:**
    - The encoded string.


---

### toURI(String, String)
- static toURI(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encodes a string into its URL safe form according to the
      "application/x-www-form-urlencoded" encoding scheme using the specified
      encoding. Unsafe characters are escaped. An exception is thrown if the
      specified encoding is unsupported. An exception is thrown if either
      argument is null.


    **Parameters:**
    - string - The string to encode.
    - encoding - The name of a supported encoding.

    **Returns:**
    - The encoded string.


---

<!-- prettier-ignore-end -->

<!-- document id=18137ad88478f52d68902d6b59fe1285359eaac7bf8ac23dec597304d0d6d9ec url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.EncryptedObject.md -->

<!-- prettier-ignore-start -->
# Class EncryptedObject

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md)

Defines a API base class for classes containing
encrypted attributes like credit cards.


**Note:** this method handles sensitive financial and card holder data.
Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



## All Known Subclasses
[CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md), [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md), [ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md)
## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=36fbf240e849e28b3d43f8d2c2be089ce0adbcf02b61a4fd6cc3fc00ddaba440 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.value.EnumValue.md -->

<!-- prettier-ignore-start -->
# Class EnumValue

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.value.EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)

The class represents a single value for an Enumeration type. Enumeration
types can be configured through the business manager for custom attributes.
Some system attributes, e.g. the order status, are also of Enumeration types.


Each EnumValue has a base value and a display value.  The type of the base
value can be either String or Integer. Every EnumValue has a display value.



If the value of an Enumeration type object attribute is
`null`, when that attribute is accessed an EnumValue is returned
that has a base value of `null`, rather than `null`
itself.  This means that `empty(object.attribute)` would be
`false`, and `empty(object.attribute.value)` would be
`true`
.



## Property Summary

| Property | Description |
| --- | --- |
| [displayValue](#displayvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display value of the enumeration value. |
| [value](#value): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the value of the enumeration value. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md#getdisplayvalue)() | Returns the display value of the enumeration value. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md#getvalue)() | Returns the value of the enumeration value. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md#tostring)() | Same as getDisplayValue(). |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md#valueof)() | According the ECMA specification, this method returns the "natural"  primitive value of this object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### displayValue
- displayValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display value of the enumeration value. If no display value
      is configured the method return the string representation of the value.



---

### value
- value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the value of the enumeration value. This is either an integer
      value or a string.



---

## Method Details

### getDisplayValue()
- getDisplayValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display value of the enumeration value. If no display value
      is configured the method return the string representation of the value.



---

### getValue()
- getValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value of the enumeration value. This is either an integer
      value or a string.



---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Same as getDisplayValue().


---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : According the ECMA specification, this method returns the "natural"
      primitive value of this object. Here it is equivalent to getValue().



---

<!-- prettier-ignore-end -->

<!-- document id=9de3b381d4b5a1f7bf48f175a722bf03d9db2e8470b4e84e59bf8847189ee7a9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Error.md -->

<!-- prettier-ignore-start -->
# Class Error

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)

Error represents a generic exception.


## All Known Subclasses
[APIException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.APIException.md)
## Property Summary

| Property | Description |
| --- | --- |
| [message](#message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | An error message that provides details about the exception. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The name of the error based on the constructor used. |
| [stack](#stack): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The script stack trace. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Error](#error)() | Constructs the Error object. |
| [Error](#errorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the Error object  using the specified message. |

## Method Summary

| Method | Description |
| --- | --- |
| static [captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function)([Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Fills the [stack](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#stack) property for the passed error. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)() | Returns a String representation of the Error. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### message
- message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : An error message that provides details about the exception.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The name of the error based on the constructor used.


---

### stack
- stack: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The script stack trace. 
      
      This property is filled on throwing or via an explicit call [captureStackTrace(Error, Function)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function).



---

## Constructor Details

### Error()
- Error()
  - : Constructs the Error object.


---

### Error(String)
- Error(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the Error object
      using the specified message.


    **Parameters:**
    - msg - the message to use,.


---

## Method Details

### captureStackTrace(Error, Function)
- static captureStackTrace(error: [Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md), constructorOpt: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): void
  - : Fills the [stack](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#stack) property for the passed error. 
      
      The optional constructorOpt parameter allows you to pass in a function value. When collecting the stack trace all
      frames above the topmost call to this function, including that call, are left out of the stack trace. This can be
      useful to hide implementation details that won’t be useful to the user. The usual way of defining a custom error
      that captures a stack trace would be:
      
      ```
      function MyError() {
          // fill the stack trace, but hide the call to MyError
          Error.captureStackTrace(this, MyError);
      }
      ```


    **Parameters:**
    - error - The error whose stack trace should be filled.
    - constructorOpt - An optional filter to hide the topmost stack frames.

    **API Version:**
**note:** Available from version 21.2.

---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a String representation of the Error.

    **Returns:**
    - a String representation of the Error.


---

<!-- prettier-ignore-end -->

<!-- document id=5d5c7c0ccfb1a400c824b4af6932d0fc27aed108e27fdbf32378b40343b11e81 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.ES6Iterator.md -->

<!-- prettier-ignore-start -->
# Class ES6Iterator

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)

This isn't a built-in type. It describes the properties an object must have in order
to work as an iterator since ECMAScript 2015.


**API Version:**
**note:** Available from version 21.2.

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md#next)() | Returns an iterator result object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### next()
- next(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns an iterator result object.
      
      
      An iterator result object can have two properties: _done_ and _value_.
      If _done_ is `false` or `undefined`, then the _value_ property contains an iterator value.
      The _value_ property may not be present if the value would be `undefined`.
      
      
      After a call that returns a result where _done_ equals
      `true`, all subsequent calls must also return _done_ as `true`.



---

<!-- prettier-ignore-end -->

<!-- document id=0d45fbcea1a928c63f5fb090a77963c9b66f63b225525ad9a2135a7dae4e3453 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.EvalError.md -->

<!-- prettier-ignore-start -->
# Class EvalError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.EvalError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.EvalError.md)

Represents an evaluation error.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [EvalError](#evalerror)() | Constructs the error. |
| [EvalError](#evalerrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the   specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### EvalError()
- EvalError()
  - : Constructs the error.


---

### EvalError(String)
- EvalError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the 
      specified message.


    **Parameters:**
    - msg - the evaluation error message.


---

<!-- prettier-ignore-end -->

<!-- document id=d730f0829d4be7bfea2b6e3197e167a56b2a61c5ca3b945b807b86b63e07627a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.Extensible.md -->

<!-- prettier-ignore-start -->
# Class Extensible

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)

Base class alternative to ExtensibleObject for objects customizable through the metadata system.
Similar to ExtensibleObject: the [describe()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe) method provides access to the related object-type metadata.
The [getCustom()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom) method is the central point to retrieve and store the objects attribute
values themselves.



## All Known Subclasses
[AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md), [AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md), [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md), [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md), [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md), [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md), [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md), [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md), [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md), [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)
## Property Summary

| Property | Description |
| --- | --- |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes for this object. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe)() | Returns the meta data of this object. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)() | Returns the custom attributes for this object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes for this object.


---

## Method Details

### describe()
- describe(): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the meta data of this object. If no meta data is available the
      method returns null. The returned ObjectTypeDefinition can be used to
      retrieve the metadata for any of the custom attributes.


    **Returns:**
    - the meta data of this object. If no meta data is available the
              method returns null.



---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes for this object.

    **Returns:**
    - the custom attributes for this object.


---

<!-- prettier-ignore-end -->

<!-- document id=413fa141ad9c8988e21801a92ca0a5b3c483e71cdd61a693e092215b2ba9281c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.ExtensibleObject.md -->

<!-- prettier-ignore-start -->
# Class ExtensibleObject

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)

Base class for all persistent business objects in Commerce Cloud Digital that
are customizable through the metadata system. All objects in Digital
that have custom attributes derive from ExtensibleObject including
both system-defined and custom objects. The describe() method provides access
to the related object-type metadata. The method getCustom() is the central
point to retrieve and store the objects attribute values themselves.



## All Known Subclasses
[ActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md), [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md), [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md), [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md), [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), [CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md), [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md), [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md), [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md), [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md), [CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md), [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md), [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md), [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md), [EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md), [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md), [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md), [GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md), [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md), [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md), [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [OrganizationPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.OrganizationPreferences.md), [PaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md), [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md), [PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md), [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md), [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md), [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md), [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md), [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md), [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md), [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md), [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md), [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md), [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md), [ProductListItemPurchase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md), [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md), [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md), [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md), [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md), [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md), [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md), [Recommendation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md), [SearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md), [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md), [ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md), [ServiceProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md), [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), [SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md), [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md), [Store](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md), [StoreGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md), [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md), [VariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md)
## Property Summary

| Property | Description |
| --- | --- |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes for this object. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe)() | Returns the meta data of this object. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)() | Returns the custom attributes for this object. |

### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes for this object. The returned object is
      used for retrieving and storing attribute values. See
      [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) for a detailed example of the syntax for
      working with custom attributes.



---

## Method Details

### describe()
- describe(): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the meta data of this object. If no meta data is available the
      method returns null. The returned ObjectTypeDefinition can be used to
      retrieve the metadata for any of the custom attributes.


    **Returns:**
    - the meta data of this object. If no meta data is available the
              method returns null.



---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes for this object. The returned object is
      used for retrieving and storing attribute values. See
      [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) for a detailed example of the syntax for
      working with custom attributes.


    **Returns:**
    - the custom attributes for this object.


---

<!-- prettier-ignore-end -->

<!-- document id=61a6cef4bcd6b8ff940fd23beb93c51d00dfeab9d4924710ecb08a0704e0600a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.ExternalProfile.md -->

<!-- prettier-ignore-start -->
# Class ExternalProfile

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)

Represents the credentials of a customer.

Since 13.6 it is possible to have customers who are not authenticated through a
login and password but through an external authentication provider via the OAuth2 protocol.

In such cases, the AuthenticationProviderID will point to an OAuth provider configured in the system
and the ExternalID will be the unique identifier of the customer on the Authentication Provider's system.

For example, if an authentication provider with ID "Google123" is configured pointing to Google
and the customer has a logged in into Google in the past and has created a profile there, Google
assigns a unique number identifier to that customer. If the storefront is configured to allow
authentication through Google and a new customer logs into the storefront using Google,
the AuthenticationProviderID property of his Credentials will contain "Google123" and
the ExternalID property will contain whatever unique identifier Google has assigned to him.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Property Summary

| Property | Description |
| --- | --- |
| [authenticationProviderID](#authenticationproviderid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the authentication provider ID. |
| [customer](#customer): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)` | Returns the customer object related to this profile. |
| [email](#email): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's email address. |
| [externalID](#externalid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the external ID. |
| [lastLoginTime](#lastlogintime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the last login time of the customer through the external provider |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAuthenticationProviderID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md#getauthenticationproviderid)() | Returns the authentication provider ID. |
| [getCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md#getcustomer)() | Returns the customer object related to this profile. |
| [getEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md#getemail)() | Returns the customer's email address. |
| [getExternalID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md#getexternalid)() | Returns the external ID. |
| [getLastLoginTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md#getlastlogintime)() | Returns the last login time of the customer through the external provider |
| [setEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md#setemailstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's email address. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### authenticationProviderID
- authenticationProviderID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the authentication provider ID.


---

### customer
- customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)`
  - : Returns the customer object related to this profile.


---

### email
- email: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's email address.


---

### externalID
- externalID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the external ID.


---

### lastLoginTime
- lastLoginTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the last login time of the customer through the external provider


---

## Method Details

### getAuthenticationProviderID()
- getAuthenticationProviderID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the authentication provider ID.

    **Returns:**
    - the authentication provider ID.


---

### getCustomer()
- getCustomer(): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer object related to this profile.

    **Returns:**
    - customer object related to profile.


---

### getEmail()
- getEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's email address.

    **Returns:**
    - the customer's email address.


---

### getExternalID()
- getExternalID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the external ID.

    **Returns:**
    - the external ID.


---

### getLastLoginTime()
- getLastLoginTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the last login time of the customer through the external provider

    **Returns:**
    - the time, when the customer was last logged in through this external provider


---

### setEmail(String)
- setEmail(email: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's email address.

    **Parameters:**
    - email - the customer's email address.


---

<!-- prettier-ignore-end -->

<!-- document id=9d53f00a51c31bf0c8ae0105aa10461d7b6e0050200559715ed0b8e8dbc75ea5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.facebook.FacebookFeedHooks.md -->

<!-- prettier-ignore-start -->
# Class FacebookFeedHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.facebook.FacebookFeedHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookFeedHooks.md)

FacebookFeedHooks interface containing extension points for customizing Facebook export feeds.


These hooks are not executed in a transaction.


The extension points (hook names), and the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the exported hook function must be located
inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.




```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
     {"name": "dw.extensions.facebook.feed.transformProduct", "script": "./hooks.ds"}
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointTransformProduct](#extensionpointtransformproduct): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.facebook.feed.transformProduct" | The extension point name dw.extensions.facebook.feed.transformProduct. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [transformProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookFeedHooks.md#transformproductproduct-facebookproduct-string)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [FacebookProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Called after default transformation of given Demandware product to Facebook product as part of the catalog feed  export. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointTransformProduct

- extensionPointTransformProduct: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.facebook.feed.transformProduct"
  - : The extension point name dw.extensions.facebook.feed.transformProduct.


---

## Method Details

### transformProduct(Product, FacebookProduct, String)
- transformProduct(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), facebookProduct: [FacebookProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md), feedId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Called after default transformation of given Demandware product to Facebook product as part of the catalog feed
      export.
      
      
      
      
      To customize multiple feeds differently, for example if one is for Facebook Dynamic Ads and the other is for
      Instagram Commerce, use the `feedId` parameter to determine which feed is being exported. If the same
      customization should apply to all feeds, ignore the parameter.


    **Parameters:**
    - product - the Demandware product
    - facebookProduct - the Facebook representation of the product
    - feedId - the merchant-selected ID for the feed being exported

    **Returns:**
    - a non-null Status ends the hook execution


---

<!-- prettier-ignore-end -->

<!-- document id=028863bc97d00cf3b8fe413a2ea63a1e5395468f39bcb5d0e44d039f28e79934 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.facebook.FacebookProduct.md -->

<!-- prettier-ignore-start -->
# Class FacebookProduct

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.facebook.FacebookProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md)

Represents a row in the Facebook catalog feed export.


## Constant Summary

| Constant | Description |
| --- | --- |
| [AGE_GROUP_ADULT](#age_group_adult): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "adult" | Indicates that the product is for adults. |
| [AGE_GROUP_INFANT](#age_group_infant): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "infant" | Indicates that the product is for infant children. |
| [AGE_GROUP_KIDS](#age_group_kids): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "kids" | Indicates that the product is for children. |
| [AGE_GROUP_NEWBORN](#age_group_newborn): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "newborn" | Indicates that the product is for newborn children. |
| [AGE_GROUP_TODDLER](#age_group_toddler): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "toddler" | Indicates that the product is for toddler children. |
| [AVAILABILITY_AVAILABLE_FOR_ORDER](#availability_available_for_order): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "available for order" | Indicates that the product can be ordered for later shipment. |
| [AVAILABILITY_IN_STOCK](#availability_in_stock): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "in stock" | Indicates that the product is available to ship immediately. |
| [AVAILABILITY_OUT_OF_STOCK](#availability_out_of_stock): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "out of stock" | Indicates that the product is out of stock. |
| [AVAILABILITY_PREORDER](#availability_preorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "preorder" | Indicates that the product will be available in the future. |
| [CONDITION_NEW](#condition_new): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "new" | Indicates that the product is new. |
| [CONDITION_REFURBISHED](#condition_refurbished): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "refurbished" | Indicates that the product is used but has been refurbished. |
| [CONDITION_USED](#condition_used): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "used" | Indicates that the product has been used. |
| [GENDER_FEMALE](#gender_female): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "female" | Indicates that the product is for females. |
| [GENDER_MALE](#gender_male): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "male" | Indicates that the product is for males. |
| [GENDER_UNISEX](#gender_unisex): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "unisex" | Indicates that the product is for both males and females. |
| [SHIPPING_SIZE_UNIT_CM](#shipping_size_unit_cm): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cm" | Indicates that the product is measured in centimeters. |
| [SHIPPING_SIZE_UNIT_FT](#shipping_size_unit_ft): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ft" | Indicates that the product is measured in feet. |
| [SHIPPING_SIZE_UNIT_IN](#shipping_size_unit_in): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "in" | Indicates that the product is measured in inches. |
| [SHIPPING_SIZE_UNIT_M](#shipping_size_unit_m): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "m" | Indicates that the product is measured in meters. |
| [SHIPPING_WEIGHT_UNIT_G](#shipping_weight_unit_g): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "g" | Indicates that the product is weighed in grams. |
| [SHIPPING_WEIGHT_UNIT_KG](#shipping_weight_unit_kg): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "kg" | Indicates that the product is weighed in kilograms. |
| [SHIPPING_WEIGHT_UNIT_LB](#shipping_weight_unit_lb): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "lb" | Indicates that the product is weighed in pounds. |
| [SHIPPING_WEIGHT_UNIT_OZ](#shipping_weight_unit_oz): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "oz" | Indicates that the product is weighed in ounces. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the Facebook product. |
| [ageGroup](#agegroup): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the age group for the Facebook product. |
| [availability](#availability): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the availability of the Facebook product. |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook brand of the product. |
| [color](#color): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook color value label of the product. |
| [condition](#condition): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the condition of the Facebook product. |
| [customLabel0](#customlabel0): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook custom label 0 value of the product. |
| [customLabel1](#customlabel1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook custom label 1 value of the product. |
| [customLabel2](#customlabel2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook custom label 2 value of the product. |
| [customLabel3](#customlabel3): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook custom label 3 value of the product. |
| [customLabel4](#customlabel4): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook custom label 4 value of the product. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the description of the Facebook product. |
| [expirationDate](#expirationdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns the Facebook expiration date of the product. |
| [gender](#gender): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the gender for the Facebook product. |
| [googleProductCategory](#googleproductcategory): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the category of this product in the Google category taxonomy. |
| [gtin](#gtin): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook GTIN of the product. |
| [imageLinks](#imagelinks): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Returns a list containing the URLs of the images to show in Facebook for the product. |
| [itemGroupID](#itemgroupid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the ID of the Facebook item group for the product, that is, its master product. |
| [link](#link): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) | Returns the URL of the Demandware storefront link to the product. |
| [material](#material): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook material value label of the product. |
| [mpn](#mpn): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook MPN of the product. |
| [pattern](#pattern): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook pattern value label of the product. |
| [price](#price): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the price to show in Facebook for the product. |
| [productType](#producttype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook product type. |
| [salePrice](#saleprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the sale price to show in Facebook for the product. |
| [salePriceEffectiveDateEnd](#salepriceeffectivedateend): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns the end date of the Facebook sale price of the product. |
| [salePriceEffectiveDateStart](#salepriceeffectivedatestart): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns the start date of the Facebook sale price of the product. |
| [shippingHeight](#shippingheight): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the shipping height of the product. |
| [shippingLength](#shippinglength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the shipping length of the product. |
| [shippingSizeUnit](#shippingsizeunit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping size unit of the product. |
| [shippingWeight](#shippingweight): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | Returns the shipping weight for the product. |
| [shippingWidth](#shippingwidth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the shipping width of the product. |
| [size](#size): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Facebook size value label of the product. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the title of the Facebook product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAgeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getagegroup)() | Returns the age group for the Facebook product. |
| [getAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getavailability)() | Returns the availability of the Facebook product. |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getbrand)() | Returns the Facebook brand of the product. |
| [getColor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getcolor)() | Returns the Facebook color value label of the product. |
| [getCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getcondition)() | Returns the condition of the Facebook product. |
| [getCustomLabel0](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getcustomlabel0)() | Returns the Facebook custom label 0 value of the product. |
| [getCustomLabel1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getcustomlabel1)() | Returns the Facebook custom label 1 value of the product. |
| [getCustomLabel2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getcustomlabel2)() | Returns the Facebook custom label 2 value of the product. |
| [getCustomLabel3](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getcustomlabel3)() | Returns the Facebook custom label 3 value of the product. |
| [getCustomLabel4](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getcustomlabel4)() | Returns the Facebook custom label 4 value of the product. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getdescription)() | Returns the description of the Facebook product. |
| [getExpirationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getexpirationdate)() | Returns the Facebook expiration date of the product. |
| [getGender](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getgender)() | Returns the gender for the Facebook product. |
| [getGoogleProductCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getgoogleproductcategory)() | Returns the category of this product in the Google category taxonomy. |
| [getGtin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getgtin)() | Returns the Facebook GTIN of the product. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getid)() | Returns the ID of the Facebook product. |
| [getImageLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getimagelinks)() | Returns a list containing the URLs of the images to show in Facebook for the product. |
| [getItemGroupID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getitemgroupid)() | Returns the ID of the Facebook item group for the product, that is, its master product. |
| [getLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getlink)() | Returns the URL of the Demandware storefront link to the product. |
| [getMaterial](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getmaterial)() | Returns the Facebook material value label of the product. |
| [getMpn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getmpn)() | Returns the Facebook MPN of the product. |
| [getPattern](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getpattern)() | Returns the Facebook pattern value label of the product. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getprice)() | Returns the price to show in Facebook for the product. |
| [getProductType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getproducttype)() | Returns the Facebook product type. |
| [getSalePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getsaleprice)() | Returns the sale price to show in Facebook for the product. |
| [getSalePriceEffectiveDateEnd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getsalepriceeffectivedateend)() | Returns the end date of the Facebook sale price of the product. |
| [getSalePriceEffectiveDateStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getsalepriceeffectivedatestart)() | Returns the start date of the Facebook sale price of the product. |
| [getShippingHeight](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingheight)() | Returns the shipping height of the product. |
| [getShippingLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippinglength)() | Returns the shipping length of the product. |
| [getShippingSizeUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingsizeunit)() | Returns the shipping size unit of the product. |
| [getShippingWeight](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingweight)() | Returns the shipping weight for the product. |
| [getShippingWidth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingwidth)() | Returns the shipping width of the product. |
| [getSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getsize)() | Returns the Facebook size value label of the product. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#gettitle)() | Returns the title of the Facebook product. |
| [setAgeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setagegroupstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the age group for the Facebook product. |
| [setAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setavailabilitystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the availability of the Facebook product. |
| [setBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setbrandstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook brand of the product. |
| [setColor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setcolorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook color value label of the product. |
| [setCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setconditionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the condition of the Facebook product. |
| [setCustomLabel0](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setcustomlabel0string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook custom label 0 value of the product. |
| [setCustomLabel1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setcustomlabel1string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook custom label 1 value of the product. |
| [setCustomLabel2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setcustomlabel2string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook custom label 2 value of the product. |
| [setCustomLabel3](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setcustomlabel3string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook custom label 3 value of the product. |
| [setCustomLabel4](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setcustomlabel4string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook custom label 4 value of the product. |
| [setDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setdescriptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the description of the Facebook product. |
| [setExpirationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setexpirationdatedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the Facebook expiration date of the product. |
| [setGender](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setgenderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the gender for the Facebook product. |
| [setGoogleProductCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setgoogleproductcategorystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the category of this product in the Google category taxonomy. |
| [setGtin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setgtinstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook GTIN of the product. |
| [setImageLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setimagelinkslist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Sets the list of URLs of images to show in Facebook for the product. |
| [setItemGroupID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setitemgroupidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the ID of the Facebook item group for the product, that is, its master product. |
| [setLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setlinkurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Sets the URL of the Demandware storefront link to the product. |
| [setMaterial](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setmaterialstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook material value label of the product. |
| [setMpn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setmpnstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook MPN of the product. |
| [setPattern](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setpatternstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook pattern value label of the product. |
| [setPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setpricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Sets the price to show in Facebook for the product. |
| [setProductType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setproducttypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook product type. |
| [setSalePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setsalepricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Sets the sale price to show in Facebook for the product. |
| [setSalePriceEffectiveDateEnd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setsalepriceeffectivedateenddate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the end date of the Facebook sale price of the product. |
| [setSalePriceEffectiveDateStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setsalepriceeffectivedatestartdate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the start date of the Facebook sale price of the product. |
| [setShippingHeight](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingheightnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the shipping height of the product. |
| [setShippingLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippinglengthnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the shipping length of the product. |
| [setShippingSizeUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingsizeunitstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping size unit of the product. |
| [setShippingWeight](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingweightquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Sets the shipping weight for the product. |
| [setShippingWidth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingwidthnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the shipping width of the product. |
| [setSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setsizestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Facebook size value label of the product. |
| [setTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#settitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the title of the Facebook product. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### AGE_GROUP_ADULT

- AGE_GROUP_ADULT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "adult"
  - : Indicates that the product is for adults.


---

### AGE_GROUP_INFANT

- AGE_GROUP_INFANT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "infant"
  - : Indicates that the product is for infant children.


---

### AGE_GROUP_KIDS

- AGE_GROUP_KIDS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "kids"
  - : Indicates that the product is for children.


---

### AGE_GROUP_NEWBORN

- AGE_GROUP_NEWBORN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "newborn"
  - : Indicates that the product is for newborn children.


---

### AGE_GROUP_TODDLER

- AGE_GROUP_TODDLER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "toddler"
  - : Indicates that the product is for toddler children.


---

### AVAILABILITY_AVAILABLE_FOR_ORDER

- AVAILABILITY_AVAILABLE_FOR_ORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "available for order"
  - : Indicates that the product can be ordered for later shipment.


---

### AVAILABILITY_IN_STOCK

- AVAILABILITY_IN_STOCK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "in stock"
  - : Indicates that the product is available to ship immediately.


---

### AVAILABILITY_OUT_OF_STOCK

- AVAILABILITY_OUT_OF_STOCK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "out of stock"
  - : Indicates that the product is out of stock.


---

### AVAILABILITY_PREORDER

- AVAILABILITY_PREORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "preorder"
  - : Indicates that the product will be available in the future.


---

### CONDITION_NEW

- CONDITION_NEW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "new"
  - : Indicates that the product is new.


---

### CONDITION_REFURBISHED

- CONDITION_REFURBISHED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "refurbished"
  - : Indicates that the product is used but has been refurbished.


---

### CONDITION_USED

- CONDITION_USED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "used"
  - : Indicates that the product has been used.


---

### GENDER_FEMALE

- GENDER_FEMALE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "female"
  - : Indicates that the product is for females.


---

### GENDER_MALE

- GENDER_MALE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "male"
  - : Indicates that the product is for males.


---

### GENDER_UNISEX

- GENDER_UNISEX: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "unisex"
  - : Indicates that the product is for both males and females.


---

### SHIPPING_SIZE_UNIT_CM

- SHIPPING_SIZE_UNIT_CM: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cm"
  - : Indicates that the product is measured in centimeters.


---

### SHIPPING_SIZE_UNIT_FT

- SHIPPING_SIZE_UNIT_FT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ft"
  - : Indicates that the product is measured in feet.


---

### SHIPPING_SIZE_UNIT_IN

- SHIPPING_SIZE_UNIT_IN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "in"
  - : Indicates that the product is measured in inches.


---

### SHIPPING_SIZE_UNIT_M

- SHIPPING_SIZE_UNIT_M: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "m"
  - : Indicates that the product is measured in meters.


---

### SHIPPING_WEIGHT_UNIT_G

- SHIPPING_WEIGHT_UNIT_G: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "g"
  - : Indicates that the product is weighed in grams.


---

### SHIPPING_WEIGHT_UNIT_KG

- SHIPPING_WEIGHT_UNIT_KG: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "kg"
  - : Indicates that the product is weighed in kilograms.


---

### SHIPPING_WEIGHT_UNIT_LB

- SHIPPING_WEIGHT_UNIT_LB: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "lb"
  - : Indicates that the product is weighed in pounds.


---

### SHIPPING_WEIGHT_UNIT_OZ

- SHIPPING_WEIGHT_UNIT_OZ: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "oz"
  - : Indicates that the product is weighed in ounces.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the Facebook product. This is the same as the ID of the Demandware product.


---

### ageGroup
- ageGroup: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the age group for the Facebook product.


---

### availability
- availability: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the availability of the Facebook product.


---

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook brand of the product.


---

### color
- color: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook color value label of the product.


---

### condition
- condition: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the condition of the Facebook product.


---

### customLabel0
- customLabel0: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 0 value of the product.


---

### customLabel1
- customLabel1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 1 value of the product.


---

### customLabel2
- customLabel2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 2 value of the product.


---

### customLabel3
- customLabel3: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 3 value of the product.


---

### customLabel4
- customLabel4: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 4 value of the product.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the Facebook product.


---

### expirationDate
- expirationDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the Facebook expiration date of the product. If the product is expired it will not be shown.


---

### gender
- gender: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the gender for the Facebook product.


---

### googleProductCategory
- googleProductCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the category of this product in the Google category taxonomy. If the value is longer than 250 characters
      it is truncated.



---

### gtin
- gtin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook GTIN of the product.


---

### imageLinks
- imageLinks: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list containing the URLs of the images to show in Facebook for the product.


---

### itemGroupID
- itemGroupID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Facebook item group for the product, that is, its master product.


---

### link
- link: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the Demandware storefront link to the product.


---

### material
- material: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook material value label of the product.


---

### mpn
- mpn: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook MPN of the product.


---

### pattern
- pattern: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook pattern value label of the product.


---

### price
- price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price to show in Facebook for the product.


---

### productType
- productType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook product type. This is the retailer-defined category of the item.


---

### salePrice
- salePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sale price to show in Facebook for the product.


---

### salePriceEffectiveDateEnd
- salePriceEffectiveDateEnd: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the end date of the Facebook sale price of the product.


---

### salePriceEffectiveDateStart
- salePriceEffectiveDateStart: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the start date of the Facebook sale price of the product.


---

### shippingHeight
- shippingHeight: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the shipping height of the product.

    **See Also:**
    - [getShippingLength()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippinglength)
    - [getShippingWidth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingwidth)
    - [getShippingSizeUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingsizeunit)


---

### shippingLength
- shippingLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the shipping length of the product.

    **See Also:**
    - [getShippingWidth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingwidth)
    - [getShippingHeight()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingheight)
    - [getShippingSizeUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingsizeunit)


---

### shippingSizeUnit
- shippingSizeUnit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping size unit of the product.

    **See Also:**
    - [getShippingLength()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippinglength)
    - [getShippingWidth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingwidth)
    - [getShippingHeight()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingheight)


---

### shippingWeight
- shippingWeight: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the shipping weight for the product.


---

### shippingWidth
- shippingWidth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the shipping width of the product.

    **See Also:**
    - [getShippingLength()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippinglength)
    - [getShippingHeight()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingheight)
    - [getShippingSizeUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingsizeunit)


---

### size
- size: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook size value label of the product.


---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the title of the Facebook product.


---

## Method Details

### getAgeGroup()
- getAgeGroup(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the age group for the Facebook product.

    **Returns:**
    - product age group


---

### getAvailability()
- getAvailability(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the availability of the Facebook product.

    **Returns:**
    - product availability


---

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook brand of the product.

    **Returns:**
    - the brand


---

### getColor()
- getColor(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook color value label of the product.

    **Returns:**
    - the color value label


---

### getCondition()
- getCondition(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the condition of the Facebook product.

    **Returns:**
    - product condition


---

### getCustomLabel0()
- getCustomLabel0(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 0 value of the product.

    **Returns:**
    - the custom label 0 value


---

### getCustomLabel1()
- getCustomLabel1(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 1 value of the product.

    **Returns:**
    - the custom label 1 value


---

### getCustomLabel2()
- getCustomLabel2(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 2 value of the product.

    **Returns:**
    - the custom label 2 value


---

### getCustomLabel3()
- getCustomLabel3(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 3 value of the product.

    **Returns:**
    - the custom label 3 value


---

### getCustomLabel4()
- getCustomLabel4(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook custom label 4 value of the product.

    **Returns:**
    - the custom label 4 value


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the Facebook product.

    **Returns:**
    - product description


---

### getExpirationDate()
- getExpirationDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the Facebook expiration date of the product. If the product is expired it will not be shown.

    **Returns:**
    - the expiration date


---

### getGender()
- getGender(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the gender for the Facebook product.

    **Returns:**
    - product gender


---

### getGoogleProductCategory()
- getGoogleProductCategory(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the category of this product in the Google category taxonomy. If the value is longer than 250 characters
      it is truncated.


    **Returns:**
    - the category of this product in the Google category taxonomy


---

### getGtin()
- getGtin(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook GTIN of the product.

    **Returns:**
    - the GTIN


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Facebook product. This is the same as the ID of the Demandware product.

    **Returns:**
    - product ID


---

### getImageLinks()
- getImageLinks(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list containing the URLs of the images to show in Facebook for the product.

    **Returns:**
    - the URLs of the images


---

### getItemGroupID()
- getItemGroupID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Facebook item group for the product, that is, its master product.

    **Returns:**
    - the ID of the Facebook item group


---

### getLink()
- getLink(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the Demandware storefront link to the product.

    **Returns:**
    - the URL of the storefront link


---

### getMaterial()
- getMaterial(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook material value label of the product.

    **Returns:**
    - the material value label


---

### getMpn()
- getMpn(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook MPN of the product.

    **Returns:**
    - the MPN


---

### getPattern()
- getPattern(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook pattern value label of the product.

    **Returns:**
    - the pattern value label


---

### getPrice()
- getPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price to show in Facebook for the product.

    **Returns:**
    - the price to show in Facebook


---

### getProductType()
- getProductType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook product type. This is the retailer-defined category of the item.

    **Returns:**
    - the Facebook product type


---

### getSalePrice()
- getSalePrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sale price to show in Facebook for the product.

    **Returns:**
    - the sale price to show in Facebook


---

### getSalePriceEffectiveDateEnd()
- getSalePriceEffectiveDateEnd(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the end date of the Facebook sale price of the product.

    **Returns:**
    - the end date of the Facebook sale price


---

### getSalePriceEffectiveDateStart()
- getSalePriceEffectiveDateStart(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the start date of the Facebook sale price of the product.

    **Returns:**
    - the start date of the Facebook sale price


---

### getShippingHeight()
- getShippingHeight(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the shipping height of the product.

    **Returns:**
    - the shipping height

    **See Also:**
    - [getShippingLength()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippinglength)
    - [getShippingWidth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingwidth)
    - [getShippingSizeUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingsizeunit)


---

### getShippingLength()
- getShippingLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the shipping length of the product.

    **Returns:**
    - the shipping length

    **See Also:**
    - [getShippingWidth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingwidth)
    - [getShippingHeight()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingheight)
    - [getShippingSizeUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingsizeunit)


---

### getShippingSizeUnit()
- getShippingSizeUnit(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping size unit of the product.

    **Returns:**
    - the shipping size unit

    **See Also:**
    - [getShippingLength()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippinglength)
    - [getShippingWidth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingwidth)
    - [getShippingHeight()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingheight)


---

### getShippingWeight()
- getShippingWeight(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the shipping weight for the product.

    **Returns:**
    - the shipping weight


---

### getShippingWidth()
- getShippingWidth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the shipping width of the product.

    **Returns:**
    - the shipping width

    **See Also:**
    - [getShippingLength()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippinglength)
    - [getShippingHeight()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingheight)
    - [getShippingSizeUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#getshippingsizeunit)


---

### getSize()
- getSize(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Facebook size value label of the product.

    **Returns:**
    - the size value label


---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the title of the Facebook product.

    **Returns:**
    - product title


---

### setAgeGroup(String)
- setAgeGroup(ageGroup: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the age group for the Facebook product. Possible values are
      [AGE_GROUP_ADULT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#age_group_adult),
      [AGE_GROUP_INFANT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#age_group_infant),
      [AGE_GROUP_KIDS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#age_group_kids),
      [AGE_GROUP_NEWBORN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#age_group_newborn),
      [AGE_GROUP_TODDLER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#age_group_toddler), or `null`.


    **Parameters:**
    - ageGroup - the ageGroup to set for this product


---

### setAvailability(String)
- setAvailability(availability: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the availability of the Facebook product. Possible values are
      [AVAILABILITY_AVAILABLE_FOR_ORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#availability_available_for_order),
      [AVAILABILITY_IN_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#availability_in_stock),
      [AVAILABILITY_OUT_OF_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#availability_out_of_stock), or
      [AVAILABILITY_PREORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#availability_preorder)


    **Parameters:**
    - availability - the availability status to set for this product


---

### setBrand(String)
- setBrand(brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook brand of the product. If the value is longer than 70 characters it is truncated.

    **Parameters:**
    - brand - Facebook brand, up to 70 characters


---

### setColor(String)
- setColor(color: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook color value label of the product. If the value is longer than 100 characters it is truncated.

    **Parameters:**
    - color - Facebook color value label, up to 100 characters


---

### setCondition(String)
- setCondition(condition: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the condition of the Facebook product. Possible values are
      [CONDITION_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#condition_new),
      [CONDITION_REFURBISHED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#condition_refurbished), or
      [CONDITION_USED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#condition_used).


    **Parameters:**
    - condition - the condition status to set for this product


---

### setCustomLabel0(String)
- setCustomLabel0(customLabel0: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook custom label 0 value of the product.

    **Parameters:**
    - customLabel0 - custom label 0 value


---

### setCustomLabel1(String)
- setCustomLabel1(customLabel1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook custom label 1 value of the product.

    **Parameters:**
    - customLabel1 - custom label 1 value


---

### setCustomLabel2(String)
- setCustomLabel2(customLabel2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook custom label 2 value of the product.

    **Parameters:**
    - customLabel2 - custom label 2 value


---

### setCustomLabel3(String)
- setCustomLabel3(customLabel3: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook custom label 3 value of the product.

    **Parameters:**
    - customLabel3 - custom label 3 value


---

### setCustomLabel4(String)
- setCustomLabel4(customLabel4: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook custom label 4 value of the product.

    **Parameters:**
    - customLabel4 - custom label 4 value


---

### setDescription(String)
- setDescription(description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the description of the Facebook product. If the value is longer than 5000 characters it is truncated.

    **Parameters:**
    - description - product description, up to 5000 characters


---

### setExpirationDate(Date)
- setExpirationDate(expirationDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the Facebook expiration date of the product.

    **Parameters:**
    - expirationDate - Facebook expiration date


---

### setGender(String)
- setGender(gender: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the gender for the Facebook product. Possible values are
      [GENDER_MALE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#gender_male),
      [GENDER_FEMALE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#gender_female),
      [GENDER_UNISEX](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#gender_unisex), or `null`.


    **Parameters:**
    - gender - the gender to set for this product


---

### setGoogleProductCategory(String)
- setGoogleProductCategory(googleProductCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the category of this product in the Google category taxonomy.

    **Parameters:**
    - googleProductCategory - Google product category


---

### setGtin(String)
- setGtin(gtin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook GTIN of the product. If the value is longer than 70 characters it is truncated.

    **Parameters:**
    - gtin - Facebook GTIN, up to 70 characters


---

### setImageLinks(List)
- setImageLinks(imageLinks: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): void
  - : Sets the list of URLs of images to show in Facebook for the product.

    **Parameters:**
    - imageLinks - links to the product images


---

### setItemGroupID(String)
- setItemGroupID(itemGroupID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the ID of the Facebook item group for the product, that is, its master product.

    **Parameters:**
    - itemGroupID - ID of Facebook item group


---

### setLink(URL)
- setLink(link: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): void
  - : Sets the URL of the Demandware storefront link to the product.

    **Parameters:**
    - link - Demandware storefront link to the product


---

### setMaterial(String)
- setMaterial(material: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook material value label of the product. If the value is longer than 200 characters it is
      truncated.


    **Parameters:**
    - material - Facebook material value label, up to 200 characters


---

### setMpn(String)
- setMpn(mpn: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook MPN of the product. If the value is longer than 70 characters it is truncated.

    **Parameters:**
    - mpn - Facebook MPN, up to 70 characters


---

### setPattern(String)
- setPattern(pattern: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook pattern value label of the product. If the value is longer than 100 characters it is truncated.

    **Parameters:**
    - pattern - Facebook pattern value label, up to 100 characters


---

### setPrice(Money)
- setPrice(price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Sets the price to show in Facebook for the product.

    **Parameters:**
    - price - Facebook price


---

### setProductType(String)
- setProductType(productType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook product type. If the value is longer than 750 characters it is truncated.

    **Parameters:**
    - productType - Facebook product type, up to 750 characters


---

### setSalePrice(Money)
- setSalePrice(salePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Sets the sale price to show in Facebook for the product.

    **Parameters:**
    - salePrice - Facebook sale price


---

### setSalePriceEffectiveDateEnd(Date)
- setSalePriceEffectiveDateEnd(salePriceEffectiveDateEnd: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the end date of the Facebook sale price of the product.

    **Parameters:**
    - salePriceEffectiveDateEnd - end date of Facebook sale price


---

### setSalePriceEffectiveDateStart(Date)
- setSalePriceEffectiveDateStart(salePriceEffectiveDateStart: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the start date of the Facebook sale price of the product.

    **Parameters:**
    - salePriceEffectiveDateStart - start date of Facebook sale price


---

### setShippingHeight(Number)
- setShippingHeight(shippingHeight: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the shipping height of the product. If the value is negative it is truncated to 0.

    **Parameters:**
    - shippingHeight - shipping height, may not be negative

    **See Also:**
    - [setShippingLength(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippinglengthnumber)
    - [setShippingWidth(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingwidthnumber)
    - [setShippingSizeUnit(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingsizeunitstring)


---

### setShippingLength(Number)
- setShippingLength(shippingLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the shipping length of the product. If the value is negative it is truncated to 0.

    **Parameters:**
    - shippingLength - shipping length, may not be negative

    **See Also:**
    - [setShippingWidth(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingwidthnumber)
    - [setShippingHeight(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingheightnumber)
    - [setShippingSizeUnit(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingsizeunitstring)


---

### setShippingSizeUnit(String)
- setShippingSizeUnit(shippingSizeUnit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping size unit of the product.

    **Parameters:**
    - shippingSizeUnit - shipping size unit

    **See Also:**
    - [setShippingLength(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippinglengthnumber)
    - [setShippingWidth(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingwidthnumber)
    - [setShippingHeight(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingheightnumber)


---

### setShippingWeight(Quantity)
- setShippingWeight(shippingWeight: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): void
  - : Sets the shipping weight for the product. Possible unit values are
      [SHIPPING_WEIGHT_UNIT_LB](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#shipping_weight_unit_lb),
      [SHIPPING_WEIGHT_UNIT_OZ](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#shipping_weight_unit_oz),
      [SHIPPING_WEIGHT_UNIT_G](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#shipping_weight_unit_g), or
      [SHIPPING_WEIGHT_UNIT_KG](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#shipping_weight_unit_kg).


    **Parameters:**
    - shippingWeight - product shipping weight


---

### setShippingWidth(Number)
- setShippingWidth(shippingWidth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the shipping width of the product. If the value is negative it is truncated to 0.

    **Parameters:**
    - shippingWidth - shipping width, may not be negative

    **See Also:**
    - [setShippingLength(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippinglengthnumber)
    - [setShippingHeight(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingheightnumber)
    - [setShippingSizeUnit(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md#setshippingsizeunitstring)


---

### setSize(String)
- setSize(size: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Facebook size value label of the product. If the value is longer than 100 characters it is truncated.

    **Parameters:**
    - size - Facebook size value label, up to 100 characters


---

### setTitle(String)
- setTitle(title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the title of the Facebook product. If the value is longer than 100 characters it is truncated.

    **Parameters:**
    - title - product title, up to 100 characters


---

<!-- prettier-ignore-end -->

<!-- document id=217e241ca648f9aa37b1b5cc65719a1dd86f219aa6c07b86de8f71218cdc3225 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Fault.md -->

<!-- prettier-ignore-start -->
# Class Fault

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.Fault](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Fault.md)

This error indicates an RPC related error in the system. The Fault
is always related to a systems internal Java exception. The class provides
access to some more details about this internal Java exception. In particular
it provides details about the error send from the remote system.



## Property Summary

| Property | Description |
| --- | --- |
| [causeFullName](#causefullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the full name of the associated Java exception. |
| [causeMessage](#causemessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the message of the associated Java exception. |
| [causeName](#causename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the simplified name of the associated Java exception. |
| [faultActor](#faultactor): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Provides some information on who cause the fault along the message  path. |
| [faultCode](#faultcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | An identifier for the specific fault. |
| [faultDetail](#faultdetail): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | More detailed information about the fault. |
| [faultString](#faultstring): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | A human readable description for the fault. |
| [javaFullName](#javafullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The full name of the underlying Java exception. |
| [javaMessage](#javamessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The message of the underlying Java exception. |
| [javaName](#javaname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The simplified name of the underlying Java exception. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Fault](#fault)() |  |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### causeFullName
- causeFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the full name of the associated Java exception.



---

### causeMessage
- causeMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the message of the associated Java exception.



---

### causeName
- causeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the simplified name of the associated Java exception.



---

### faultActor
- faultActor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Provides some information on who cause the fault along the message
      path.



---

### faultCode
- faultCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : An identifier for the specific fault.


---

### faultDetail
- faultDetail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : More detailed information about the fault.


---

### faultString
- faultString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : A human readable description for the fault.


---

### javaFullName
- javaFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The full name of the underlying Java exception.


---

### javaMessage
- javaMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The message of the underlying Java exception.


---

### javaName
- javaName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The simplified name of the underlying Java exception.


---

## Constructor Details

### Fault()
- Fault()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=9997c5d577904b7265a0ab2fac1b9b3c4e592584e3cd3f00dbd070aa5abd8afe url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.File.md -->

<!-- prettier-ignore-start -->
# Class File

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)

Represents a file resource accessible from scripting. As with
`java.io.File`, a `File` is essentially an
"abstract pathname" which may or may not denote an actual file on the file
system.  Methods `createNewFile`,
`mkdir`, `mkdirs`, and `remove` are provided
to actually manipulate physical files.


File access is limited to certain virtual directories.  These directories are
a subset of those accessible through WebDAV.  As a result of this
restriction, pathnames must be one of the following forms:



- `/TEMP(/...)`
- `/IMPEX(/...)`
- `/REALMDATA(/...)`
- `/CATALOGS/[Catalog Name](/...)`
- `/LIBRARIES/[Library Name](/...)`


Note, that these paths are analogous to the WebDAV URIs used to access the
same directories.


The files are stored in a shared file system where multiple processes could
access the same file. The programmer has to make sure no more than one process
writes to a file at a given time.



This class provides other useful methods for listing the
children of a directory and for working with zip files.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information.


For performance reasons no more than 100,000 files (regular files and directories) should be stored in a
directory.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CATALOGS](#catalogs): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CATALOGS" | Catalogs root directory. |
| [CUSTOMERPI](#customerpi): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMERPI" | Customer Payment Instrument root directory. |
| [CUSTOMER_SNAPSHOTS](#customer_snapshots): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMERSNAPSHOTS" | Customer snapshots root directory. |
| [DYNAMIC](#dynamic): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DYNAMIC" | Reserved for future use. |
| [IMPEX](#impex): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IMPEX" | Import/export root directory. |
| [LIBRARIES](#libraries): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "LIBRARIES" | Libraries root directory. |
| ~~[REALMDATA](#realmdata): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "REALMDATA"~~ | RealmData root directory. |
| [SEPARATOR](#separator): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "/" | The UNIX style '/' path separator, which must be used for files paths. |
| [STATIC](#static): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "STATIC" | Static content root directory. |
| [TEMP](#temp): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TEMP" | Temp root directory. |

## Property Summary

| Property | Description |
| --- | --- |
| [directory](#directory): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates that this file is a directory. |
| [file](#file): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates if this file is a file. |
| [fullPath](#fullpath): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the full file path denoted by this `File`. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the file or directory denoted by this object. |
| ~~[path](#path): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | Returns the portion of the path relative to the root directory. |
| [rootDirectoryType](#rootdirectorytype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the root directory type, e.g. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [File](#filestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a `File` from the given absolute file path in the  file namespace. |
| [File](#filefile-string)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a `File` given a root directory and a relative path. |

## Method Summary

| Method | Description |
| --- | --- |
| [copyTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#copytofile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Copy a file. |
| [createNewFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#createnewfile)() | Create file. |
| [exists](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#exists)() | Indicates if the file exists. |
| [getFullPath](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getfullpath)() | Return the full file path denoted by this `File`. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getname)() | Returns the name of the file or directory denoted by this object. |
| ~~[getPath](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getpath)()~~ | Returns the portion of the path relative to the root directory. |
| static [getRootDirectory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getrootdirectorystring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a `File` representing a directory for the specified  root directory type. |
| [getRootDirectoryType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getrootdirectorytype)() | Returns the root directory type, e.g. |
| [gunzip](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#gunzipfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Assumes this instance is a gzip file. |
| [gzip](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#gzipfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | GZip this instance into a new gzip file. |
| [isDirectory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#isdirectory)() | Indicates that this file is a directory. |
| [isFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#isfile)() | Indicates if this file is a file. |
| [lastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#lastmodified)() | Return the time, in milliseconds, that this file was last modified. |
| [length](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#length)() | Return the length of the file in bytes. |
| [list](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#list)() | Returns an array of strings naming the files and directories in the  directory denoted by this object. |
| [listFiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#listfiles)() | Returns an array of `File` objects in the directory denoted  by this `File`. |
| [listFiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#listfilesfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Returns an array of `File` objects denoting the files and  directories in the directory denoted by this object that satisfy the  specified filter. |
| [md5](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#md5)() | Returns an MD5 hash of the content of the file of this instance. |
| [mkdir](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#mkdir)() | Creates a directory. |
| [mkdirs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#mkdirs)() | Creates a directory, including, its parent directories, as needed. |
| [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#remove)() | Deletes the file or directory denoted by this object. |
| [renameTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#renametofile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Rename file. |
| [unzip](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#unzipfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Assumes this instance is a zip file. |
| [zip](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#zipfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Zip this instance into a new zip file. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CATALOGS

- CATALOGS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CATALOGS"
  - : Catalogs root directory.


---

### CUSTOMERPI

- CUSTOMERPI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMERPI"
  - : Customer Payment Instrument root directory.


---

### CUSTOMER_SNAPSHOTS

- CUSTOMER_SNAPSHOTS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMERSNAPSHOTS"
  - : Customer snapshots root directory.


---

### DYNAMIC

- DYNAMIC: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DYNAMIC"
  - : Reserved for future use.


---

### IMPEX

- IMPEX: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IMPEX"
  - : Import/export root directory.


---

### LIBRARIES

- LIBRARIES: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "LIBRARIES"
  - : Libraries root directory.


---

### REALMDATA

- ~~REALMDATA: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "REALMDATA"~~
  - : RealmData root directory.

    **Deprecated:**
**warning:** Folder to be removed.

---

### SEPARATOR

- SEPARATOR: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "/"
  - : The UNIX style '/' path separator, which must be used for files paths.


---

### STATIC

- STATIC: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "STATIC"
  - : Static content root directory.


---

### TEMP

- TEMP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TEMP"
  - : Temp root directory.


---

## Property Details

### directory
- directory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates that this file is a directory.


---

### file
- file: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates if this file is a file.


---

### fullPath
- fullPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the full file path denoted by this `File`.
      This value will be the same regardless of which constructor was
      used to create this `File`.



---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the file or directory denoted by this object. This is
      just the last name in the pathname's name sequence. If the pathname's
      name sequence is empty, then the empty string is returned.



---

### path
- ~~path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : Returns the portion of the path relative to the root directory.

    **Deprecated:**
**warning:** Use [getFullPath()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getfullpath) to access the full path.
            This method does not return the correct path for files
            in the CATALOGS or LIBRARIES virtual directories.

---

### rootDirectoryType
- rootDirectoryType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the root directory type, e.g. "IMPEX" represented by this
      `File`.



---

## Constructor Details

### File(String)
- File(absPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a `File` from the given absolute file path in the
      file namespace.  If the specified path is not a valid accessible path,
      an exception will be thrown.
      
      
      The passed path should use the forward slash '/' as the path
      separator and begin with a leading slash.  However, if a leading slash
      is not provided, or the backslash character is used as the separator,
      these problems will be fixed.  The normalized value will then be returned
      by [getFullPath()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getfullpath).


    **Parameters:**
    - absPath - the absolute file path  throws IOException


---

### File(File, String)
- File(rootDir: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a `File` given a root directory and a relative path.

    **Parameters:**
    - rootDir - File object representing root directory
    - relPath - relative file path


---

## Method Details

### copyTo(File)
- copyTo(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)
  - : Copy a file. Directories cannot be copied. This method cannot be used from storefront requests.

    **Parameters:**
    - file - the File object to copy to

    **Returns:**
    - a reference to the copied file.

    **Throws:**
    - IOException - if there is an interruption during file copy.
    - FileAlreadyExistsException - if the file to copy to already exists
    - UnsupportedOperationException - if invoked from a storefront request


---

### createNewFile()
- createNewFile(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Create file.

    **Returns:**
    - boolean, true - if file has been created, false - file already exists

    **Throws:**
    - Exception - 


---

### exists()
- exists(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if the file exists.

    **Returns:**
    - true if file exists, false otherwise.


---

### getFullPath()
- getFullPath(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the full file path denoted by this `File`.
      This value will be the same regardless of which constructor was
      used to create this `File`.


    **Returns:**
    - the full file path.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the file or directory denoted by this object. This is
      just the last name in the pathname's name sequence. If the pathname's
      name sequence is empty, then the empty string is returned.


    **Returns:**
    - The name of the file or directory denoted by this object.


---

### getPath()
- ~~getPath(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the portion of the path relative to the root directory.

    **Returns:**
    - the relative file path, possibly blank but not null.

    **Deprecated:**
**warning:** Use [getFullPath()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#getfullpath) to access the full path.
            This method does not return the correct path for files
            in the CATALOGS or LIBRARIES virtual directories.

---

### getRootDirectory(String, String...)
- static getRootDirectory(rootDir: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)
  - : Returns a `File` representing a directory for the specified
      root directory type. If the root directory
      type is CATALOGS or LIBRARIES, then an additional argument representing
      the specific catalog or library must be provided.  Otherwise, no
      additional arguments are needed.


    **Parameters:**
    - rootDir - root directory type (see the constants defined in this class)
    - args - root directory specific arguments

    **Returns:**
    - File object representing the directory


---

### getRootDirectoryType()
- getRootDirectoryType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the root directory type, e.g. "IMPEX" represented by this
      `File`.


    **Returns:**
    - root directory type


---

### gunzip(File)
- gunzip(root: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): void
  - : Assumes this instance is a gzip file. Unzipping it will
      explode the contents in the directory passed in (root).


    **Parameters:**
    - root - a File indicating root. root must be a directory.

    **Throws:**
    - Exception - if the zip files contents can't be exploded.


---

### gzip(File)
- gzip(outputZipFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): void
  - : GZip this instance into a new gzip file. If you're zipping a file, then a single entry, the instance,
      is included in the output gzip file. Note that a new File is created. GZipping directories is not supported.
      This file is never modified.


    **Parameters:**
    - outputZipFile - the zip file created.

    **Throws:**
    - IOException - if the zip file can't be created.


---

### isDirectory()
- isDirectory(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates that this file is a directory.

    **Returns:**
    - true if the file is a directory, false otherwise.


---

### isFile()
- isFile(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if this file is a file.

    **Returns:**
    - true if the file is a file, false otherwise.


---

### lastModified()
- lastModified(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the time, in milliseconds, that this file was last modified.

    **Returns:**
    - the time, in milliseconds, that this file was last modified.


---

### length()
- length(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the length of the file in bytes.

    **Returns:**
    - the file length in bytes.


---

### list()
- list(): [String\[\]](TopLevel.String.md)
  - : Returns an array of strings naming the files and directories in the
      directory denoted by this object.
      
      
      
      If this object does not denote a directory, then this method returns
      `null`. Otherwise an array of strings is returned, one for
      each file or directory in the directory. Names denoting the directory
      itself and the directory's parent directory are not included in the
      result. Each string is a file name rather than a complete path.
      
      
      
      There is no guarantee that the name strings in the resulting array will
      appear in any specific order; they are not, in particular, guaranteed to
      appear in alphabetical order.


    **Returns:**
    - An array of strings naming the files and directories in the
              directory denoted by this `File`. The array will be
              empty if the directory is empty. Returns `null` if
              this `File` does not denote a directory.



---

### listFiles()
- listFiles(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns an array of `File` objects in the directory denoted
      by this `File`.
      
      
      
      If this `File` does not denote a directory, then this method
      returns `null`. Otherwise an array of `File`
      objects is returned, one for each file or directory in the directory.
      Files denoting the directory itself and the directory's parent directory
      are not included in the result.
      
      
      
      There is no guarantee that the files in the resulting array will appear
      in any specific order; they are not, in particular, guaranteed to appear
      in alphabetical order. Example usage:
      
      
      
      `
       // Assume "foo" is an accessible directory.
      
       var this_directory : dw.io.File = new File("foo");
      
       
      
       // Find all files in directory foo, one level "down".
      
       // listFiles() will _not_ traverse subdirectories.
      
      var folder : dw.util.List = this_directory.listFiles();
      
      var first_element : dw.io.File = folder[0];
      
      
      
      function modification_comparison(lhs : File, rhs : File) 
      
      {
      
      &nbsp;&nbsp;return lhs.lastModified() < rhs.lastModified();
      
      }
      
      
      
      function lexigraphic_comparison(lhs: File, rhs : File)
      
      {
      
      &nbsp;&nbsp;return lhs.getName() < rhs.getName();
      
      }
      
      
      
      var time_ordered_folder : dw.util.ArrayList = folder.sort(modification_comparison);
      
      var alphabetic_folder : dw.util.ArrayList = folder.sort(lexigraphic_comparison); 
      
      `


    **Returns:**
    - a list of `File` objects or `null` if
              this is not a directory.



---

### listFiles(Function)
- listFiles(filter: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns an array of `File` objects denoting the files and
      directories in the directory denoted by this object that satisfy the
      specified filter. The behavior of this method is the same as that of the
      `[listFiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md#listfiles)` method, except that the files in the
      returned array must satisfy the filter. The filter is a Javascript
      function which accepts one argument, a `File`, and returns
      true or false depending on whether the file meets the filter conditions.
      If the given `filter` is `null` then all files
      are accepted. Otherwise, a file satisfies the filter if and only if the
      filter returns `true`. Example usage:
      
      
      
      `
       // Assume "foo" is an accessible directory.
      
       var this_directory : dw.io.File = new File("foo");
      
       
      
       function longer_than_3(candidate : dw.io.File)
      
       {
      
       &nbsp;&nbsp;return candidate.getName().length > 3;
      
       }
      
       
      
       // Find all files in directory foo, one level "down",
      
       // such that the filename is longer than 3 characters.
      
       var folder_long_names : dw.util.List = this_directory.listFiles(longer_than_3);
      
       `


    **Parameters:**
    - filter - a Javascript function which accepts a `File`             argument and returns `true` or `false`.

    **Returns:**
    - list of `File` objects or `null` if
              this is not a directory



---

### md5()
- md5(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an MD5 hash of the content of the file of this instance.

    **Returns:**
    - The MD5 hash of the file's content.

    **Throws:**
    - Exception - if the file could not be read or is a directory.


---

### mkdir()
- mkdir(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Creates a directory.

    **Returns:**
    - true if file creation succeeded, false otherwise.


---

### mkdirs()
- mkdirs(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Creates a directory, including, its parent directories, as needed.

    **Returns:**
    - true if file creation succeeded, false otherwise.


---

### remove()
- remove(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Deletes the file or directory denoted by this object. If this File
      represents a directory, then the directory must be empty in order to be
      deleted.


    **Returns:**
    - true if file deletion succeeded, false otherwise


---

### renameTo(File)
- renameTo(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Rename file.

    **Parameters:**
    - file - the File object to rename to

    **Returns:**
    - boolean, true - if file rename succeeded, false - failed


---

### unzip(File)
- unzip(root: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): void
  - : Assumes this instance is a zip file. Unzipping it will
      explode the contents in the directory passed in (root).


    **Parameters:**
    - root - a File indicating root. root must be a directory.

    **Throws:**
    - Exception - if the zip files contents can't be exploded.


---

### zip(File)
- zip(outputZipFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): void
  - : Zip this instance into a new zip file. If you're zipping a directory,
      the directory itself and all its children files to any level (any number of subdirectories)
      are included in the zip file. The directory will be the only entry in the archive (single root).
      If you're zipping a file, then a single entry, the instance,
      is included in the output zip file. Note that a new File is created.
      This file is never modified.


    **Parameters:**
    - outputZipFile - the zip file created.

    **Throws:**
    - IOException - if the zip file can't be created.


---

<!-- prettier-ignore-end -->

<!-- document id=40cba947a59ffa76fd372d8faa2c4218b681c0adccc142a03cab0697a47295a0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.FileReader.md -->

<!-- prettier-ignore-start -->
# Class FileReader

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md)
    - [dw.io.FileReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileReader.md)

File reader class.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [FileReader](#filereaderfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Constructs the reader. |
| [FileReader](#filereaderfile-string)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the reader. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileReader.md#close)() | Closes the reader. |

### Methods inherited from class Reader

[close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#close), [getLines](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#getlines), [getString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#getstring), [read](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#read), [read](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnumber), [readLine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readline), [readLines](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readlines), [readN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnnumber), [readString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readstring), [ready](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#ready), [skip](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#skipnumber)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### FileReader(File)
- FileReader(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md))
  - : Constructs the reader.
      
      
      To release system resources, close the reader by calling [close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileReader.md#close).


    **Parameters:**
    - file - the file object to read.


---

### FileReader(File, String)
- FileReader(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the reader.
      
      
      To release system resources, close the reader by calling [close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileReader.md#close).


    **Parameters:**
    - file - the file object to read.
    - encoding - the character encoding to use.


---

## Method Details

### close()
- close(): void
  - : Closes the reader.


---

<!-- prettier-ignore-end -->

<!-- document id=437f986eb45021e115c362c502d6a7b7c44b00d9565200987f8066ff374836a4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.FileWriter.md -->

<!-- prettier-ignore-start -->
# Class FileWriter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)
    - [dw.io.FileWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md)

Convenience class for writing character files.


Files are stored in a shared file system where multiple processes could
access the same file. The client code is responsible for ensuring that no
more than one process writes to a file at a given time.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## Property Summary

| Property | Description |
| --- | --- |
| [lineSeparator](#lineseparator): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Get the current line separator (e.g. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [FileWriter](#filewriterfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Constructs the writer for the specified file. |
| [FileWriter](#filewriterfile-boolean)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Constructs the writer for the specified file. |
| [FileWriter](#filewriterfile-string)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the writer for the specified file with the specified encoding. |
| [FileWriter](#filewriterfile-string-boolean)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Constructs the writer for the specified file with the specified encoding. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#close)() | Closes the writer. |
| [getLineSeparator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#getlineseparator)() | Get the current line separator (e.g. |
| [setLineSeparator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#setlineseparatorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the line separator (e.g. |
| [writeLine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#writelinestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes the specified line and appends the line separator. |

### Methods inherited from class Writer

[close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#close), [flush](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#flush), [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring), [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring-number-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### lineSeparator
- lineSeparator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the current line separator (e.g. '\n' or '\r\n'), if no value is set the system default '\n' will be used.


---

## Constructor Details

### FileWriter(File)
- FileWriter(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md))
  - : Constructs the writer for the specified file. Uses "UTF-8" as encoding.
      
      
      To release system resources, close the writer by calling [close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#close).


    **Parameters:**
    - file - the file object to write to.


---

### FileWriter(File, Boolean)
- FileWriter(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), append: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))
  - : Constructs the writer for the specified file. Optional file append mode
      is supported. Uses "UTF-8" as encoding.
      
      
      To release system resources, close the writer by calling [close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#close).


    **Parameters:**
    - file - the file object to write to.
    - append - flag, whether the file should be written in append mode


---

### FileWriter(File, String)
- FileWriter(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the writer for the specified file with the specified encoding.
      
      
      To release system resources, close the writer by calling [close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#close).


    **Parameters:**
    - file - the file object to write to.
    - encoding - the character encoding to use.


---

### FileWriter(File, String, Boolean)
- FileWriter(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), append: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))
  - : Constructs the writer for the specified file with the specified encoding.
      Optional file append mode is supported.
      
      
      To release system resources, close the writer by calling [close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md#close).


    **Parameters:**
    - file - the file object to write to.
    - encoding - the character encoding to use.
    - append - flag indicating whether the file should be written in append mode.


---

## Method Details

### close()
- close(): void
  - : Closes the writer.


---

### getLineSeparator()
- getLineSeparator(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the current line separator (e.g. '\n' or '\r\n'), if no value is set the system default '\n' will be used.


---

### setLineSeparator(String)
- setLineSeparator(lineSeparator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the line separator (e.g. '\n' or '\r\n'), if no value is set the system default '\n' will be used.

    **Parameters:**
    - lineSeparator - that will be written at the end of each line


---

### writeLine(String)
- writeLine(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes the specified line and appends the line separator.

    **Parameters:**
    - str - the line to write to the file.


---

<!-- prettier-ignore-end -->

<!-- document id=85862986fe62ff727d0bdc1ccf7d85f6b60dc4009457dd607e9b86cbf964b587 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.FilteringCollection.md -->

<!-- prettier-ignore-start -->
# Class FilteringCollection

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
    - [dw.util.FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)

[FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) is an extension of
[Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) which provides possibilities to


- _filter_the elements to return a new  [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)with a filtered set of elements
- _sort_the elements to return a new  [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)with a defined sort order
- _transform_the elements to return a new  [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)containing related elements
- _provide a map_of the elements against a predefined key




**Usage** - In the current version each
[FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) provides a set of predefined
_qualifier_ constants which can be passed into the
[select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject) method used to _filter_ the elements. Generally
_qualifiers_ have the prefix _QUALIFIER\__. A second method
[sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject) is used to create a new instance with a different
element ordering, which takes an _orderB<_ constant. Generally
_orderBys_ have the prefix ORDERBY\_: examples are
[ShippingOrder.ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_itemid),
[ShippingOrder.ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_itemposition), and [ORDERBY_REVERSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#orderby_reverse) can
be used to provide a [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) with the reverse
ordering. An example with method [ShippingOrder.getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems):



`
 
var allItems     : FilteringCollection = shippingOrder.items;
 
var productItems : FilteringCollection = allItems.select(ShippingOrder.QUALIFIER_PRODUCTITEMS);
 
var serviceItems : FilteringCollection = allItems.select(ShippingOrder.QUALIFIER_SERVICEITEMS);
 
var byPosition   : FilteringCollection = productItems.sort(ShippingOrder.ORDERBY_ITEMPOSITION);
 
var revByPosition: FilteringCollection = byPosition.sort(FilteringCollection.ORDERBY_REVERSE);
 
var mapByItemID  : Map = allItems.asMap();
 `



## Constant Summary

| Constant | Description |
| --- | --- |
| [ORDERBY_REVERSE](#orderby_reverse): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Pass this _orderBy_ with the [sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject) method to  obtain a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) with the reversed sort  order. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [asMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#asmap)() | Returns a [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) containing the elements of this  [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) against a predefined key. |
| [select](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Select a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) instance by passing a  predefined _qualifier_ as an argument to this method. |
| [sort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Select a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) instance by passing a  predefined _orderBy_ as an argument to this method. |

### Methods inherited from class Collection

[add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject), [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object), [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection), [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear), [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject), [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty), [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject), [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection), [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ORDERBY_REVERSE

- ORDERBY_REVERSE: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Pass this _orderBy_ with the [sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject) method to
      obtain a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) with the reversed sort
      order. Only use on a [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) which has been
      previously sorted.



---

## Method Details

### asMap()
- asMap(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) containing the elements of this
      [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) against a predefined key. The key
      used is documented in the method returning the
      [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) and is typically the ItemID assigned
      to an element in the collection.


    **Returns:**
    - a [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) containing the elements of this
              [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) against a predefined key.



---

### select(Object)
- select(qualifier: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Select a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) instance by passing a
      predefined _qualifier_ as an argument to this method. See
      [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md).


    **Parameters:**
    - qualifier - possible qualifiers are documented in the method returning the [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)

    **Returns:**
    - a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) instance


---

### sort(Object)
- sort(orderBy: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Select a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) instance by passing a
      predefined _orderBy_ as an argument to this method. See
      [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md).


    **Parameters:**
    - orderBy - possible orderBys are documented in the method returning the [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)

    **Returns:**
    - a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) instance


---

<!-- prettier-ignore-end -->

<!-- document id=43bd6368a4099c4b81eddf0c4efbe744d008b613982f7d4eabd700709a7fa486 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.FixedPriceDiscount.md -->

<!-- prettier-ignore-start -->
# Class FixedPriceDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.FixedPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceDiscount.md)

Represents a _fix price_ discount in the discount plan, for example
"Shipping only 0.99 all orders $25 or more."



## Property Summary

| Property | Description |
| --- | --- |
| [fixedPrice](#fixedprice): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"  discount. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [FixedPriceDiscount](#fixedpricediscountnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Create a fixed-price-discount on the fly. |

## Method Summary

| Method | Description |
| --- | --- |
| [getFixedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceDiscount.md#getfixedprice)() | Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"  discount. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### fixedPrice
- fixedPrice: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"
      discount.



---

## Constructor Details

### FixedPriceDiscount(Number)
- FixedPriceDiscount(amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Create a fixed-price-discount on the fly. Can be used to create a custom price adjustment.

    **Parameters:**
    - amount - fixed price e.g. 10.00


---

## Method Details

### getFixedPrice()
- getFixedPrice(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"
      discount.


    **Returns:**
    - Fixed price amount


---

<!-- prettier-ignore-end -->

<!-- document id=134d7413282ae79e88bb51f4acc28db9165588f4361c35d1647842295680e4e2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.FixedPriceShippingDiscount.md -->

<!-- prettier-ignore-start -->
# Class FixedPriceShippingDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.FixedPriceShippingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceShippingDiscount.md)

Represents a _fixed price shipping_ discount in the discount plan, for
example "Shipping only 0.99 for iPods."



## Property Summary

| Property | Description |
| --- | --- |
| [fixedPrice](#fixedprice): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"  discount. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [FixedPriceShippingDiscount](#fixedpriceshippingdiscountnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Create a fixed-price-shipping-discount on the fly. |

## Method Summary

| Method | Description |
| --- | --- |
| [getFixedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceShippingDiscount.md#getfixedprice)() | Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"  discount. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### fixedPrice
- fixedPrice: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"
      discount.



---

## Constructor Details

### FixedPriceShippingDiscount(Number)
- FixedPriceShippingDiscount(amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Create a fixed-price-shipping-discount on the fly. Can be used to create a custom price adjustment.

    **Parameters:**
    - amount - fixed price for shipping e.g. 10.00


---

## Method Details

### getFixedPrice()
- getFixedPrice(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the fixed price amount, for example 0.99 for a "Shipping only $0.99"
      discount.


    **Returns:**
    - Fixed price amount


---

<!-- prettier-ignore-end -->

<!-- document id=65c879557ef510fcc377682d6021ea87ac0aa5c48fa1e49f4e3f5444d117cc11 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Float32Array.md -->

<!-- prettier-ignore-start -->
# Class Float32Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Float32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float32Array.md)

An optimized array to store 32-bit floating point numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Float32Array](#float32array)() | Creates an empty array. |
| [Float32Array](#float32arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Float32Array](#float32arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Float32Array](#float32arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Float32Array](#float32arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float32Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float32Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float32Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Float32Array()
- Float32Array()
  - : Creates an empty array.


---

### Float32Array(Number)
- Float32Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Float32Array(Object)
- Float32Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Float32Array(Array)
- Float32Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Float32Array(ArrayBuffer, Number, Number)
- Float32Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Float32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float32Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=485cb91fce32ee094d025a199772e8aa62bf93edce262fda3e22b2e3c81a3b86 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Float64Array.md -->

<!-- prettier-ignore-start -->
# Class Float64Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Float64Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float64Array.md)

An optimized array to store 64-bit floating point numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Float64Array](#float64array)() | Creates an empty array. |
| [Float64Array](#float64arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Float64Array](#float64arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Float64Array](#float64arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Float64Array](#float64arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float64Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float64Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float64Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Float64Array()
- Float64Array()
  - : Creates an empty array.


---

### Float64Array(Number)
- Float64Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Float64Array(Object)
- Float64Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Float64Array(Array)
- Float64Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Float64Array(ArrayBuffer, Number, Number)
- Float64Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Float64Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float64Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=8ed13f4d702479c2850a34cafcb788eafca1164cd2ccf1386d2a7e2192304f33 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.image.FocalPoint.md -->

<!-- prettier-ignore-start -->
# Class FocalPoint

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.image.FocalPoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md)

This class represents an image focal point.

**See Also:**
- [Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)


## Property Summary

| Property | Description |
| --- | --- |
| [x](#x): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the focal point abscissa. |
| [y](#y): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the focal point ordinate. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getX](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md#getx)() | Returns the focal point abscissa. |
| [getY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md#gety)() | Returns the focal point ordinate. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### x
- x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the focal point abscissa.


---

### y
- y: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the focal point ordinate.


---

## Method Details

### getX()
- getX(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the focal point abscissa.

    **Returns:**
    - the focal point abscissa


---

### getY()
- getY(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the focal point ordinate.

    **Returns:**
    - the focal point ordinate


---

<!-- prettier-ignore-end -->

<!-- document id=a9e487b4a7c560afe51f8696612426d433e703adff931d733a09e4c81526525e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.Folder.md -->

<!-- prettier-ignore-start -->
# Class Folder

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.content.Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)

Class representing a folder for organizing content assets in Commerce Cloud Digital.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the folder. |
| [content](#content): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the content objects for this folder, sorted by position. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description for the folder as known in the current  locale or null if it cannot be found. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name for the folder as known in the current  locale or null if it cannot be found. |
| [online](#online): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates if the folder is set online or  offline. |
| [onlineContent](#onlinecontent): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the online content objects for this folder, sorted by position. |
| [onlineSubFolders](#onlinesubfolders): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the online subfolders of this folder, sorted by position. |
| [pageDescription](#pagedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page description for this folder using the value in  the current locale, or returns null if no value was found. |
| [pageKeywords](#pagekeywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page keywords for this folder using the value in  the current locale, or returns null if no value was found. |
| [pageTitle](#pagetitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page title for this folder using the value in  the current locale, or returns null if no value was found. |
| [pageURL](#pageurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page URL for this folder using the value in  the current locale, or returns null if no value was found. |
| [parent](#parent): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)` | Returns the parent folder of this folder. |
| [root](#root): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates if this is the root folder. |
| [siteMapChangeFrequency](#sitemapchangefrequency): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the folder's sitemap change frequency. |
| [siteMapIncluded](#sitemapincluded): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the folder's sitemap inclusion. |
| [siteMapPriority](#sitemappriority): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the folder's sitemap priority. |
| [subFolders](#subfolders): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the subfolders of this folder, sorted by position. |
| [template](#template): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the template used to render the folder  in the store front. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getcontent)() | Returns the content objects for this folder, sorted by position. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getdescription)() | Returns the description for the folder as known in the current  locale or null if it cannot be found. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getdisplayname)() | Returns the display name for the folder as known in the current  locale or null if it cannot be found. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getid)() | Returns the ID of the folder. |
| [getOnlineContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getonlinecontent)() | Returns the online content objects for this folder, sorted by position. |
| [getOnlineSubFolders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getonlinesubfolders)() | Returns the online subfolders of this folder, sorted by position. |
| [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getpagedescription)() | Returns the page description for this folder using the value in  the current locale, or returns null if no value was found. |
| [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getpagekeywords)() | Returns the page keywords for this folder using the value in  the current locale, or returns null if no value was found. |
| [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getpagetitle)() | Returns the page title for this folder using the value in  the current locale, or returns null if no value was found. |
| [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getpageurl)() | Returns the page URL for this folder using the value in  the current locale, or returns null if no value was found. |
| [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getparent)() | Returns the parent folder of this folder. |
| [getSiteMapChangeFrequency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getsitemapchangefrequency)() | Returns the folder's sitemap change frequency. |
| [getSiteMapIncluded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getsitemapincluded)() | Returns the folder's sitemap inclusion. |
| [getSiteMapPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getsitemappriority)() | Returns the folder's sitemap priority. |
| [getSubFolders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#getsubfolders)() | Returns the subfolders of this folder, sorted by position. |
| [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#gettemplate)() | Returns the name of the template used to render the folder  in the store front. |
| [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#isonline)() | Indicates if the folder is set online or  offline. |
| [isRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md#isroot)() | Indicates if this is the root folder. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the folder. The ID can be used to uniquely
      identify a folder within any given library. This folder ID provides
      an alternative lookup mechanism for folders frequently used in
      the storefront.



---

### content
- content: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the content objects for this folder, sorted by position.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description for the folder as known in the current
      locale or null if it cannot be found.



---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name for the folder as known in the current
      locale or null if it cannot be found.



---

### online
- online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates if the folder is set online or
      offline. Initially, all folders are set online.



---

### onlineContent
- onlineContent: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the online content objects for this folder, sorted by position.


---

### onlineSubFolders
- onlineSubFolders: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the online subfolders of this folder, sorted by position.


---

### pageDescription
- pageDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page description for this folder using the value in
      the current locale, or returns null if no value was found.



---

### pageKeywords
- pageKeywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page keywords for this folder using the value in
      the current locale, or returns null if no value was found.



---

### pageTitle
- pageTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page title for this folder using the value in
      the current locale, or returns null if no value was found.



---

### pageURL
- pageURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page URL for this folder using the value in
      the current locale, or returns null if no value was found.



---

### parent
- parent: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)`
  - : Returns the parent folder of this folder.


---

### root
- root: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates if this is the root folder.


---

### siteMapChangeFrequency
- siteMapChangeFrequency: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the folder's sitemap change frequency.


---

### siteMapIncluded
- siteMapIncluded: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the folder's sitemap inclusion.


---

### siteMapPriority
- siteMapPriority: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the folder's sitemap priority.


---

### subFolders
- subFolders: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the subfolders of this folder, sorted by position.


---

### template
- template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the template used to render the folder
      in the store front.



---

## Method Details

### getContent()
- getContent(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the content objects for this folder, sorted by position.

    **Returns:**
    - the content objects for this folder, sorted by position.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description for the folder as known in the current
      locale or null if it cannot be found.


    **Returns:**
    - the description for the folder as known in the current
      locale or null if it cannot be found.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name for the folder as known in the current
      locale or null if it cannot be found.


    **Returns:**
    - the display name for the folder as known in the current
      locale or null if it cannot be found.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the folder. The ID can be used to uniquely
      identify a folder within any given library. This folder ID provides
      an alternative lookup mechanism for folders frequently used in
      the storefront.


    **Returns:**
    - the ID of the folder.


---

### getOnlineContent()
- getOnlineContent(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the online content objects for this folder, sorted by position.

    **Returns:**
    - the online content objects for this folder, sorted by position.


---

### getOnlineSubFolders()
- getOnlineSubFolders(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the online subfolders of this folder, sorted by position.

    **Returns:**
    - the online subfolders of this folder, sorted by position.


---

### getPageDescription()
- getPageDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page description for this folder using the value in
      the current locale, or returns null if no value was found.


    **Returns:**
    - the page description for this folder using the value in
      the current locale, or returns null if no value was found.



---

### getPageKeywords()
- getPageKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page keywords for this folder using the value in
      the current locale, or returns null if no value was found.


    **Returns:**
    - the page keywords for this folder using the value in
      the current locale, or returns null if no value was found.



---

### getPageTitle()
- getPageTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page title for this folder using the value in
      the current locale, or returns null if no value was found.


    **Returns:**
    - the page title for this folder using the value in
      the current locale, or returns null if no value was found.



---

### getPageURL()
- getPageURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page URL for this folder using the value in
      the current locale, or returns null if no value was found.


    **Returns:**
    - the page URL for this folder using the value in
      the current locale, or returns null if no value was found.



---

### getParent()
- getParent(): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the parent folder of this folder.

    **Returns:**
    - the parent folder of this folder.


---

### getSiteMapChangeFrequency()
- getSiteMapChangeFrequency(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the folder's sitemap change frequency.

    **Returns:**
    - the value of the attribute 'siteMapChangeFrequency'.


---

### getSiteMapIncluded()
- getSiteMapIncluded(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the folder's sitemap inclusion.

    **Returns:**
    - the value of the attribute 'siteMapIncluded'.


---

### getSiteMapPriority()
- getSiteMapPriority(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the folder's sitemap priority.

    **Returns:**
    - the value of the attribute 'siteMapPriority'.


---

### getSubFolders()
- getSubFolders(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the subfolders of this folder, sorted by position.

    **Returns:**
    - the subfolders of this folder, sorted by position.


---

### getTemplate()
- getTemplate(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the template used to render the folder
      in the store front.


    **Returns:**
    - the name of the template used to render the folder.


---

### isOnline()
- isOnline(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if the folder is set online or
      offline. Initially, all folders are set online.


    **Returns:**
    - true if the folder is online, false otherwise.


---

### isRoot()
- isRoot(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if this is the root folder.

    **Returns:**
    - true if this is the root folder, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=cc1c545d9cd7f7302a77c0d0809ed1a8b466ee7be8c779b2dff493adc073ac0f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.Form.md -->

<!-- prettier-ignore-start -->
# Class Form

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)
    - [dw.web.FormGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md)
      - [dw.web.Form](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md)

The class is the top level element in the form instance hierachy.


## Property Summary

| Property | Description |
| --- | --- |
| [secureKeyHtmlName](#securekeyhtmlname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the secure key html name to be used for the hidden input field  that will contain the secure key value. |
| [secureKeyValue](#securekeyvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the secure key value that is generated for the form to use  in a hidden input field for authentication. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSecureKeyHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md#getsecurekeyhtmlname)() | Returns the secure key html name to be used for the hidden input field  that will contain the secure key value. |
| [getSecureKeyValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md#getsecurekeyvalue)() | Returns the secure key value that is generated for the form to use  in a hidden input field for authentication. |

### Methods inherited from class FormGroup

[accept](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#accept), [copyFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copyfromobject), [copyTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copytoobject), [getChildCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getchildcount), [getError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#geterror), [getObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getobject), [getSubmittedAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getsubmittedaction), [getTriggeredAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#gettriggeredaction)
### Methods inherited from class FormElement

[clearFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#clearformelement), [getDynamicHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getdynamichtmlname), [getFormId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getformid), [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#gethtmlname), [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getparent), [getValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getvalidationresult), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelement), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelementstring), [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#isvalid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### secureKeyHtmlName
- secureKeyHtmlName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the secure key html name to be used for the hidden input field
      that will contain the secure key value.



---

### secureKeyValue
- secureKeyValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the secure key value that is generated for the form to use
      in a hidden input field for authentication.



---

## Method Details

### getSecureKeyHtmlName()
- getSecureKeyHtmlName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the secure key html name to be used for the hidden input field
      that will contain the secure key value.


    **Returns:**
    - the secure key html name


---

### getSecureKeyValue()
- getSecureKeyValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the secure key value that is generated for the form to use
      in a hidden input field for authentication.


    **Returns:**
    - the secure key value


---

<!-- prettier-ignore-end -->

<!-- document id=48290e526a6b3a50513ac5a1f69aa73c9daf9d9ff82ad7938399709db470207e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormAction.md -->

<!-- prettier-ignore-start -->
# Class FormAction

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)
    - [dw.web.FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md)

The FormAction class represents the action in form instance hierarchy.


## Property Summary

| Property | Description |
| --- | --- |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the optional description for the action. |
| [label](#label): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the optional label for the action. |
| [object](#object): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the object that was bound to the form in which the action  is contained. |
| [submitted](#submitted): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the form action was submitted from  the client to the server. |
| [triggered](#triggered): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies that this action is triggerd. |
| [x](#x): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | In case of an image button, returns the x coordinate of the last click. |
| [y](#y): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | In case of an image button, returns the y coordinate of the last click. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md#getdescription)() | Returns the optional description for the action. |
| [getLabel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md#getlabel)() | Returns the optional label for the action. |
| [getObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md#getobject)() | Returns the object that was bound to the form in which the action  is contained. |
| [getX](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md#getx)() | In case of an image button, returns the x coordinate of the last click. |
| [getY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md#gety)() | In case of an image button, returns the y coordinate of the last click. |
| [isSubmitted](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md#issubmitted)() | Identifies if the form action was submitted from  the client to the server. |
| [isTriggered](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md#istriggered)() | Identifies that this action is triggerd. |

### Methods inherited from class FormElement

[clearFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#clearformelement), [getDynamicHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getdynamichtmlname), [getFormId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getformid), [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#gethtmlname), [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getparent), [getValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getvalidationresult), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelement), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelementstring), [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#isvalid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the optional description for the action. The description could be used
      as tooltip for the action.



---

### label
- label: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the optional label for the action. The label would be typically used
      as button text.



---

### object
- object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the object that was bound to the form in which the action
      is contained. The method is a convenience method for getParent().getObject().
      In most cases this is actually the object for which
      the specific action is triggered.



---

### submitted
- submitted: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the form action was submitted from
      the client to the server.



---

### triggered
- triggered: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies that this action is triggerd. An
      action is only triggered if it was submitted and the constraints, regarding
      a valid form, are met.



---

### x
- x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : In case of an image button, returns the x coordinate of the last click.


---

### y
- y: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : In case of an image button, returns the y coordinate of the last click.


---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the optional description for the action. The description could be used
      as tooltip for the action.


    **Returns:**
    - the optional description for the action.


---

### getLabel()
- getLabel(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the optional label for the action. The label would be typically used
      as button text.


    **Returns:**
    - the optional label for the action.


---

### getObject()
- getObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the object that was bound to the form in which the action
      is contained. The method is a convenience method for getParent().getObject().
      In most cases this is actually the object for which
      the specific action is triggered.


    **Returns:**
    - the object that was bound to the form in which the action
      is contained.



---

### getX()
- getX(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : In case of an image button, returns the x coordinate of the last click.

    **Returns:**
    - the x coordinate of the last click.


---

### getY()
- getY(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : In case of an image button, returns the y coordinate of the last click.

    **Returns:**
    - the y coordinate of the last click.


---

### isSubmitted()
- isSubmitted(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the form action was submitted from
      the client to the server.


    **Returns:**
    - true if the form action was submitted, false otherwise.


---

### isTriggered()
- isTriggered(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies that this action is triggerd. An
      action is only triggered if it was submitted and the constraints, regarding
      a valid form, are met.


    **Returns:**
    - true if the action is triggered, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=c90ab89e6e8c36bc22deb98996754c3eaff3d7bea8d5ebd76fa4e3f8b2b068f0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormElement.md -->

<!-- prettier-ignore-start -->
# Class FormElement

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)

Represents a form element.


## All Known Subclasses
[Form](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md), [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md), [FormField](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md), [FormGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md), [FormList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md), [FormListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md)
## Property Summary

| Property | Description |
| --- | --- |
| [dynamicHtmlName](#dynamichtmlname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns a dynamic html name for the field. |
| [formId](#formid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The ID of the form element. |
| [htmlName](#htmlname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the global unique name of the field, which can be used as name  in the html form. |
| [parent](#parent): [FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md) `(read-only)` | The parent within the form. |
| [valid](#valid): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this element and all its children elements are  valid. |
| [validationResult](#validationresult): [FormElementValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md) `(read-only)` | Provides a combined view on the validation status as per isValid() and getError(). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [clearFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#clearformelement)() | This method clears the whole form. |
| [getDynamicHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getdynamichtmlname)() | Returns a dynamic html name for the field. |
| [getFormId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getformid)() | The ID of the form element. |
| [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#gethtmlname)() | Returns the global unique name of the field, which can be used as name  in the html form. |
| [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getparent)() | The parent within the form. |
| [getValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getvalidationresult)() | Provides a combined view on the validation status as per isValid() and getError(). |
| [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelement)() | The method can be called to explicitly invalidate a form element. |
| [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelementstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method can be called to explicitly invalidate a field. |
| [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#isvalid)() | Identifies if this element and all its children elements are  valid. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### dynamicHtmlName
- dynamicHtmlName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns a dynamic html name for the field. It can be used to suppress any autocompletion
      support from a browser, e.g. for credit card related fields. It can be also
      used for a unique form name, if one form is used multiple times in a page.



---

### formId
- formId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The ID of the form element. The is is unique within the parent
      element of the form.



---

### htmlName
- htmlName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the global unique name of the field, which can be used as name
      in the html form. For radio buttons this name is not unique.



---

### parent
- parent: [FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md) `(read-only)`
  - : The parent within the form.


---

### valid
- valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this element and all its children elements are
      valid. A form element, which was not submitted in the last
      request is always valid.



---

### validationResult
- validationResult: [FormElementValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md) `(read-only)`
  - : Provides a combined view on the validation status as per isValid() and getError(). In
      addition it also provides the data as returned by the validation in case a validation
      script was used.



---

## Method Details

### clearFormElement()
- clearFormElement(): void
  - : This method clears the whole form. After clearing a form it
      contains no value or the default value, is not bound to any business
      object and has the status of being valid.



---

### getDynamicHtmlName()
- getDynamicHtmlName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a dynamic html name for the field. It can be used to suppress any autocompletion
      support from a browser, e.g. for credit card related fields. It can be also
      used for a unique form name, if one form is used multiple times in a page.


    **Returns:**
    - a dynamic html name.


---

### getFormId()
- getFormId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The ID of the form element. The is is unique within the parent
      element of the form.


    **Returns:**
    - the ID of the form.


---

### getHtmlName()
- getHtmlName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the global unique name of the field, which can be used as name
      in the html form. For radio buttons this name is not unique.


    **Returns:**
    - the global unique name of the field.


---

### getParent()
- getParent(): [FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)
  - : The parent within the form.

    **Returns:**
    - the parent within the form.


---

### getValidationResult()
- getValidationResult(): [FormElementValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md)
  - : Provides a combined view on the validation status as per isValid() and getError(). In
      addition it also provides the data as returned by the validation in case a validation
      script was used.


    **Returns:**
    - the validation status (valid, error, data)


---

### invalidateFormElement()
- invalidateFormElement(): void
  - : The method can be called to explicitly invalidate a form element. The
      error text will be set to the one of two possible preconfigured custom
      error messages associated with the form definition. The "value-error"
      message will be used for FormField instances and "form-error" will be
      used for FormGroup instances.



---

### invalidateFormElement(String)
- invalidateFormElement(error: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : The method can be called to explicitly invalidate a field. The error
      text is set to the given error message.


    **Parameters:**
    - error - the error text to use.


---

### isValid()
- isValid(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this element and all its children elements are
      valid. A form element, which was not submitted in the last
      request is always valid.


    **Returns:**
    - true if this element and all its children elements are valid,
      false otherwise.



---

<!-- prettier-ignore-end -->

<!-- document id=2b56b98aead778803ff032aedf0c69d19b96e78af9c132b14a1a3beb88029189 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormElementValidationResult.md -->

<!-- prettier-ignore-start -->
# Class FormElementValidationResult

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElementValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md)

Represents a form element validation result. The validation script specified for form groups and fields can create
such FormElementValidationResult with the desired validity, message and data and can then return it. The server side form
element validation will evaluate these settings, i.e. calculate the corresponding element validity and message. The optional
data provided with this instance will be kept and can be accessed again from the form element after server side validation.



## Property Summary

| Property | Description |
| --- | --- |
| [data](#data): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Provides optional data acquired during validation. |
| [message](#message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Provides an optional message in case of validation failure. |
| [valid](#valid): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | States if the validation succeeded or failed. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [FormElementValidationResult](#formelementvalidationresultboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Creates a FormElementValidationResult with given setting for the validity but without any message. |
| [FormElementValidationResult](#formelementvalidationresultboolean-string)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a FormElementValidationResult with given setting for the validity and corresponding message. |
| [FormElementValidationResult](#formelementvalidationresultboolean-string-map)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)) | Creates a FormElementValidationResult with given setting for the validity and corresponding message. |

## Method Summary

| Method | Description |
| --- | --- |
| [addData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md#adddataobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds optional data acquired during validation. |
| [getData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md#getdata)() | Provides optional data acquired during validation. |
| [getMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md#getmessage)() | Provides an optional message in case of validation failure. |
| [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md#isvalid)() | States if the validation succeeded or failed. |
| [setMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md#setmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets an optional message in case of validation failure. |
| [setValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md#setvalidboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets if the validation succeeded or failed. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### data
- data: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Provides optional data acquired during validation.


---

### message
- message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Provides an optional message in case of validation failure.


---

### valid
- valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : States if the validation succeeded or failed.


---

## Constructor Details

### FormElementValidationResult(Boolean)
- FormElementValidationResult(valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))
  - : Creates a FormElementValidationResult with given setting for the validity but without any message.

    **Parameters:**
    - valid - the desired validity


---

### FormElementValidationResult(Boolean, String)
- FormElementValidationResult(valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a FormElementValidationResult with given setting for the validity and corresponding message.
      This is especially useful to represent a failed validation including some error message.


    **Parameters:**
    - valid - the desired validity
    - message - the desired message


---

### FormElementValidationResult(Boolean, String, Map)
- FormElementValidationResult(valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), data: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md))
  - : Creates a FormElementValidationResult with given setting for the validity and corresponding message.
      This is especially useful to represent a failed validation including some error message. Additional
      data can be stored, too.


    **Parameters:**
    - valid - the desired validity
    - message - the desired message
    - data - the desired data


---

## Method Details

### addData(Object, Object)
- addData(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Adds optional data acquired during validation.

    **Parameters:**
    - key - the key for which the data value will be stored
    - value - the data value that is stored for the given key


---

### getData()
- getData(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Provides optional data acquired during validation.

    **Returns:**
    - the data acquired during validation


---

### getMessage()
- getMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Provides an optional message in case of validation failure.

    **Returns:**
    - the message for validation failure


---

### isValid()
- isValid(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : States if the validation succeeded or failed.

    **Returns:**
    - true if the validation succeeded


---

### setMessage(String)
- setMessage(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets an optional message in case of validation failure.

    **Parameters:**
    - message - the message for validation failure


---

### setValid(Boolean)
- setValid(valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets if the validation succeeded or failed.

    **Parameters:**
    - valid - if the validation succeeded


---

<!-- prettier-ignore-end -->

<!-- document id=9fabe726e58e7e2d44a6259589089da93aa3ac958fa40b820dbfca9d4e3e0942 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormField.md -->

<!-- prettier-ignore-start -->
# Class FormField

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)
    - [dw.web.FormField](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md)

Represents a field in a form.


## Property Summary

| Property | Description |
| --- | --- |
| [FIELD_TYPE_BOOLEAN](#field_type_boolean): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | indicates a boolean/checkbox field in the form definition |
| [FIELD_TYPE_DATE](#field_type_date): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | indicates a date field in the form definition |
| [FIELD_TYPE_INTEGER](#field_type_integer): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | indicates an integer field in the form definition |
| [FIELD_TYPE_NUMBER](#field_type_number): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | indicates a number field in the form definition |
| [FIELD_TYPE_STRING](#field_type_string): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | indicates a string field in the form definition |
| [checked](#checked): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the current selected state of this field is checked. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns an optinal description for the field. |
| [error](#error): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the error text that will be shown to the user when the field is  invalid. |
| [htmlValue](#htmlvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the current external string representation of the  value in this field. |
| [label](#label): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns an optional label text for the field. |
| [mandatory](#mandatory): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates if the field is mandatory. |
| [maxLength](#maxlength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the maximum length for the form field. |
| [maxValue](#maxvalue): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the maximum value for a form field. |
| [minLength](#minlength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the minimum length for the form field. |
| [minValue](#minvalue): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the minimum value for a form field. |
| [options](#options): [FormFieldOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOptions.md) | Returns a list of possible values for this field. |
| [regEx](#regex): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns an optional regular expression pattern, which was set in the form  definition. |
| [selected](#selected): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the current selected state of this field is selected. |
| [selectedOption](#selectedoption): [FormFieldOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md) `(read-only)` | Returns the selected options or null if the field has no option  or non is selected. |
| [selectedOptionObject](#selectedoptionobject): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the object that was optionally associated with the  currently selected option. |
| [type](#type): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | The method returns the type of the field. |
| [value](#value): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Returns the internal value representation, which can be a string, a  number, a boolean or a date. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getdescription)() | Returns an optinal description for the field. |
| [getError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#geterror)() | Returns the error text that will be shown to the user when the field is  invalid. |
| [getHtmlValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#gethtmlvalue)() | Returns the current external string representation of the  value in this field. |
| [getLabel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getlabel)() | Returns an optional label text for the field. |
| [getMaxLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getmaxlength)() | Returns the maximum length for the form field. |
| [getMaxValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getmaxvalue)() | Returns the maximum value for a form field. |
| [getMinLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getminlength)() | Returns the minimum length for the form field. |
| [getMinValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getminvalue)() | Returns the minimum value for a form field. |
| [getOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getoptions)() | Returns a list of possible values for this field. |
| [getRegEx](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getregex)() | Returns an optional regular expression pattern, which was set in the form  definition. |
| [getSelectedOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getselectedoption)() | Returns the selected options or null if the field has no option  or non is selected. |
| [getSelectedOptionObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getselectedoptionobject)() | Returns the object that was optionally associated with the  currently selected option. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#gettype)() | The method returns the type of the field. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#getvalue)() | Returns the internal value representation, which can be a string, a  number, a boolean or a date. |
| [isChecked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#ischecked)() | Identifies if the current selected state of this field is checked. |
| [isMandatory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#ismandatory)() | Indicates if the field is mandatory. |
| [isSelected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#isselected)() | Identifies if the current selected state of this field is selected. |
| [setHtmlValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#sethtmlvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | A form field has two value representations, the HTML value and the plain  value. |
| [setOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#setoptionsiterator)([Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)) | The method can be called to update an option list based on the  given iterator with objects. |
| [setOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#setoptionsiterator-number-number)([Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | The method can be called to update an option list based on the  given iterator with objects. |
| [setOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#setoptionsmap)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)) | The method can be called to update an option list based on the  given key and values in the given map. |
| [setOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#setoptionsmap-number-number)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | The method can be called to update an option list based on the  given key and values in the given map. |
| [setValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md#setvalueobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the typed value of the field. |

### Methods inherited from class FormElement

[clearFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#clearformelement), [getDynamicHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getdynamichtmlname), [getFormId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getformid), [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#gethtmlname), [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getparent), [getValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getvalidationresult), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelement), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelementstring), [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#isvalid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### FIELD_TYPE_BOOLEAN
- FIELD_TYPE_BOOLEAN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : indicates a boolean/checkbox field in the form definition


---

### FIELD_TYPE_DATE
- FIELD_TYPE_DATE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : indicates a date field in the form definition


---

### FIELD_TYPE_INTEGER
- FIELD_TYPE_INTEGER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : indicates an integer field in the form definition


---

### FIELD_TYPE_NUMBER
- FIELD_TYPE_NUMBER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : indicates a number field in the form definition


---

### FIELD_TYPE_STRING
- FIELD_TYPE_STRING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : indicates a string field in the form definition


---

### checked
- checked: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the current selected state of this field is checked. In case of
      a boolean field the method directly represent the boolean value. In case
      of a string or int field, the method returns true if the current value
      matched with the value specified as "selected-value". In this way a
      selected status can be as determined for non-boolean fields.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns an optinal description for the field.


---

### error
- error: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the error text that will be shown to the user when the field is
      invalid. The error messages that may be returned by this method are
      defined in the form field definition under the following attribute names:
      
      
      - missing-error
      - parse-error
      - range-error
      - value-error
      
      
      The framework performs error checks in a specific order, and so if there
      are multiple errors for a single FormField, the following sequence
      defines which error is returned:
      
      
      - When submitting a form entry, whitespace is first trimmed from user  entry and the entry is parsed into native data type (boolean, date,  integer, number, or string). A regex, if defined, is also matched against  the input. If there is an error while parsing or matching with regex,  "parse-error" is set as error.
      - If field was marked as "mandatory" but there is no entry,  "missing-error" is returned
      - The min/max and minlength/maxlength checks are performed. If test  failed, "range-error" is returned.
      - value-error or form-error are returned when "invalidate()" was called  programatically (or pipelet InvalidateFormElement is used)
      
      
      If the field is valid, this method returns null. If no error message was
      specified in the form field definition, this method also returns null.



---

### htmlValue
- htmlValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current external string representation of the
      value in this field.



---

### label
- label: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns an optional label text for the field.


---

### mandatory
- mandatory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates if the field is mandatory.


---

### maxLength
- maxLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the maximum length for the form field. A maximum length can
      be specified for all form data types, but is only used to validate fields
      of type "string". For other data types the value is just provided as an
      easy way to dynamically format the user interface. If not specified in
      the form definition the default minimum length is Integer.MAX\_VALUE.



---

### maxValue
- maxValue: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the maximum value for a form field. A maximum value is only
      applicable for fields with the data type "int", "number" and "date".
      If a maximum value was not specified in the form definition the method
      returns null.



---

### minLength
- minLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the minimum length for the form field. A minimum length can
      be specified for all form data types, but is only used to validate fields
      of type "string". For other data types the value is just provided as an
      easy way to dynamically format the user interface. If not specified in
      the form definition the default minimum length is 0.



---

### minValue
- minValue: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the minimum value for a form field. A minimum value is only
      applicable for fields with the data type "int", "number" and "date".
      If a minimum value was not specified in the form definition the method
      returns null.



---

### options
- options: [FormFieldOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOptions.md)
  - : Returns a list of possible values for this field. The method
      is typically used to render a selection list or to render radio buttons.



---

### regEx
- regEx: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns an optional regular expression pattern, which was set in the form
      definition. A pattern is only used for validation only for string fields.
      If no pattern was set, the method returns null.



---

### selected
- selected: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the current selected state of this field is selected. In case of
      a boolean field the method directly represent the boolean value. In case
      of a string or int field, the method returns true if the current value
      matched with the value specified as "selected-value". In this way a
      selected status can be as determined for non-boolean fields.



---

### selectedOption
- selectedOption: [FormFieldOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md) `(read-only)`
  - : Returns the selected options or null if the field has no option
      or non is selected.



---

### selectedOptionObject
- selectedOptionObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the object that was optionally associated with the
      currently selected option.



---

### type
- type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : The method returns the type of the field. The type is one of the
      FIELD\_TYPE constants defined in this class.



---

### value
- value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the internal value representation, which can be a string, a
      number, a boolean or a date.



---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an optinal description for the field.

    **Returns:**
    - an optional description for the field.


---

### getError()
- getError(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the error text that will be shown to the user when the field is
      invalid. The error messages that may be returned by this method are
      defined in the form field definition under the following attribute names:
      
      
      - missing-error
      - parse-error
      - range-error
      - value-error
      
      
      The framework performs error checks in a specific order, and so if there
      are multiple errors for a single FormField, the following sequence
      defines which error is returned:
      
      
      - When submitting a form entry, whitespace is first trimmed from user  entry and the entry is parsed into native data type (boolean, date,  integer, number, or string). A regex, if defined, is also matched against  the input. If there is an error while parsing or matching with regex,  "parse-error" is set as error.
      - If field was marked as "mandatory" but there is no entry,  "missing-error" is returned
      - The min/max and minlength/maxlength checks are performed. If test  failed, "range-error" is returned.
      - value-error or form-error are returned when "invalidate()" was called  programatically (or pipelet InvalidateFormElement is used)
      
      
      If the field is valid, this method returns null. If no error message was
      specified in the form field definition, this method also returns null.


    **Returns:**
    - the error text that will be shown to the user when the field is
              invalid.



---

### getHtmlValue()
- getHtmlValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current external string representation of the
      value in this field.


    **Returns:**
    - the current external string representation of the
      value in this field.



---

### getLabel()
- getLabel(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an optional label text for the field.

    **Returns:**
    - an optional label text for the field.


---

### getMaxLength()
- getMaxLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum length for the form field. A maximum length can
      be specified for all form data types, but is only used to validate fields
      of type "string". For other data types the value is just provided as an
      easy way to dynamically format the user interface. If not specified in
      the form definition the default minimum length is Integer.MAX\_VALUE.


    **Returns:**
    - maximum length or MAX\_VALUE


---

### getMaxValue()
- getMaxValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the maximum value for a form field. A maximum value is only
      applicable for fields with the data type "int", "number" and "date".
      If a maximum value was not specified in the form definition the method
      returns null.


    **Returns:**
    - maximum value or null


---

### getMinLength()
- getMinLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the minimum length for the form field. A minimum length can
      be specified for all form data types, but is only used to validate fields
      of type "string". For other data types the value is just provided as an
      easy way to dynamically format the user interface. If not specified in
      the form definition the default minimum length is 0.


    **Returns:**
    - minimum length or 0


---

### getMinValue()
- getMinValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the minimum value for a form field. A minimum value is only
      applicable for fields with the data type "int", "number" and "date".
      If a minimum value was not specified in the form definition the method
      returns null.


    **Returns:**
    - minimum value or null


---

### getOptions()
- getOptions(): [FormFieldOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOptions.md)
  - : Returns a list of possible values for this field. The method
      is typically used to render a selection list or to render radio buttons.


    **Returns:**
    - a list of possible values for this field.


---

### getRegEx()
- getRegEx(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an optional regular expression pattern, which was set in the form
      definition. A pattern is only used for validation only for string fields.
      If no pattern was set, the method returns null.


    **Returns:**
    - the regular expression used for validation or null


---

### getSelectedOption()
- getSelectedOption(): [FormFieldOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md)
  - : Returns the selected options or null if the field has no option
      or non is selected.


    **Returns:**
    - the selected options or null if the field has no option
      or non is selected.



---

### getSelectedOptionObject()
- getSelectedOptionObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the object that was optionally associated with the
      currently selected option.


    **Returns:**
    - the object that was optionally associated with the
      currently selected option.



---

### getType()
- getType(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The method returns the type of the field. The type is one of the
      FIELD\_TYPE constants defined in this class.


    **Returns:**
    - the type of the form field


---

### getValue()
- getValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the internal value representation, which can be a string, a
      number, a boolean or a date.


    **Returns:**
    - the internal value representation, which can be a string, a
      number, a boolean or a date.



---

### isChecked()
- isChecked(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the current selected state of this field is checked. In case of
      a boolean field the method directly represent the boolean value. In case
      of a string or int field, the method returns true if the current value
      matched with the value specified as "selected-value". In this way a
      selected status can be as determined for non-boolean fields.


    **Returns:**
    - true if current selected state of this field is checked.


---

### isMandatory()
- isMandatory(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if the field is mandatory.

    **Returns:**
    - true if the field is mandatory, false otherwise.


---

### isSelected()
- isSelected(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the current selected state of this field is selected. In case of
      a boolean field the method directly represent the boolean value. In case
      of a string or int field, the method returns true if the current value
      matched with the value specified as "selected-value". In this way a
      selected status can be as determined for non-boolean fields.


    **Returns:**
    - true if current selected state of this field is checked.


---

### setHtmlValue(String)
- setHtmlValue(htmlValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : A form field has two value representations, the HTML value and the plain
      value. The HTML value is always a string representation of the field value.
      The plain value is the fully typed and validated field value.
      
      The sets the HTML value for a field. The method is typically called from
      the HTTP POST processing framework. The method than parses, validates
      and assigns the value to the typed field value (see getValue()). If the
      value is invalid the typed field value is set to null and the valid
      flag is set to false. The error property contains an error message
      for the form.


    **Parameters:**
    - htmlValue - the HTML value to use.


---

### setOptions(Iterator)
- setOptions(optionValues: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)): void
  - : The method can be called to update an option list based on the
      given iterator with objects.


    **Parameters:**
    - optionValues - an iterator whose elements are used as option values


---

### setOptions(Iterator, Number, Number)
- setOptions(optionValues: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md), begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : The method can be called to update an option list based on the
      given iterator with objects. The option list is updated using
      the bindings specified in the form definition. If no bindings are
      specified in the form definition the elements are interpreted as
      pure strings.


    **Parameters:**
    - optionValues - an iterator hows elements are used as option values
    - begin - the index of the first element to use as option value
    - end - the last of the last element to use as option value


---

### setOptions(Map)
- setOptions(optionValues: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)): void
  - : The method can be called to update an option list based on the
      given key and values in the given map.


    **Parameters:**
    - optionValues - a Map with the values for the option list


---

### setOptions(Map, Number, Number)
- setOptions(optionValues: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : The method can be called to update an option list based on the
      given key and values in the given map. The method also expects
      and index range. This index range only makes sense when the Map is
      a SortedMap.


    **Parameters:**
    - optionValues - a Map with the values for the option list.
    - begin - the index of the first element to use as option value.
    - end - the last of the last element to use as option value.


---

### setValue(Object)
- setValue(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the typed value of the field. The value is than immediately
      formatted into the external string representation, which is availble
      through the getHtmlValue() method. Also the valid flag is set
      to true. The actual value is not validated against the rules defined
      in the form definition. The method is typically used to directly set
      a typed value and to circumvent the validation rules.
      
      The type of the argument must match with the type of the field.


    **Parameters:**
    - value - the value to set.


---

<!-- prettier-ignore-end -->

<!-- document id=5b64d542519912575c32c6f823b07f5c95723cc18f6e0041eae18b857ecf1c34 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormFieldOption.md -->

<!-- prettier-ignore-start -->
# Class FormFieldOption

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormFieldOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md)

Represents an option for a form field.


## Property Summary

| Property | Description |
| --- | --- |
| [checked](#checked): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this option is checked. |
| [htmlValue](#htmlvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value for the HTML value attribute of a HTML option element. |
| [label](#label): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the value for the HTML label attribute of the HTML option element. |
| [object](#object): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the object that was bound to this option value. |
| [optionId](#optionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the option. |
| [parent](#parent): [FormField](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md) `(read-only)` | The parent, which is a field element. |
| [selected](#selected): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this option is selected. |
| [value](#value): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | The actual value associated with this option. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getHtmlValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#gethtmlvalue)() | Returns the value for the HTML value attribute of a HTML option element. |
| [getLabel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#getlabel)() | Returns the value for the HTML label attribute of the HTML option element. |
| [getObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#getobject)() | Returns the object that was bound to this option value. |
| [getOptionId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#getoptionid)() | Returns the ID of the option. |
| [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#getparent)() | The parent, which is a field element. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#getvalue)() | The actual value associated with this option. |
| [isChecked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#ischecked)() | Identifies if this option is checked. |
| [isSelected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#isselected)() | Identifies if this option is selected. |
| [setLabel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md#setlabelstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the label attribute for this option. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### checked
- checked: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this option is checked.


---

### htmlValue
- htmlValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value for the HTML value attribute of a HTML option element.


---

### label
- label: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value for the HTML label attribute of the HTML option element.
      If not specified in the form option definition the label is identical with
      the string representation of option value (see getValue()).



---

### object
- object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the object that was bound to this option value.


---

### optionId
- optionId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the option. This is an internal ID used to uniquely
      reference this option. If not specified in the form option definition
      the ID is identical with the string representation of the option value
      (see getValue()).



---

### parent
- parent: [FormField](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md) `(read-only)`
  - : The parent, which is a field element.


---

### selected
- selected: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this option is selected.


---

### value
- value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : The actual value associated with this option. This value is formatted
      and than returned as HTML value with the method getHtmlValue().



---

## Method Details

### getHtmlValue()
- getHtmlValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value for the HTML value attribute of a HTML option element.

    **Returns:**
    - the value for the HTML value attribute of a HTML option element.


---

### getLabel()
- getLabel(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value for the HTML label attribute of the HTML option element.
      If not specified in the form option definition the label is identical with
      the string representation of option value (see getValue()).


    **Returns:**
    - the value for the HTML label attribute of the HTML option element.


---

### getObject()
- getObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the object that was bound to this option value.

    **Returns:**
    - the object that was bound to this option value.


---

### getOptionId()
- getOptionId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the option. This is an internal ID used to uniquely
      reference this option. If not specified in the form option definition
      the ID is identical with the string representation of the option value
      (see getValue()).


    **Returns:**
    - the ID of the option.


---

### getParent()
- getParent(): [FormField](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md)
  - : The parent, which is a field element.

    **Returns:**
    - the parent form field.


---

### getValue()
- getValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : The actual value associated with this option. This value is formatted
      and than returned as HTML value with the method getHtmlValue().


    **Returns:**
    - the value associated with this option


---

### isChecked()
- isChecked(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this option is checked.

    **Returns:**
    - true if this option is checked, false otherwise.


---

### isSelected()
- isSelected(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this option is selected.

    **Returns:**
    - true if this option is selected, false otherwise.


---

### setLabel(String)
- setLabel(label: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the label attribute for this option.

    **Parameters:**
    - label - the label value.


---

<!-- prettier-ignore-end -->

<!-- document id=bc157f5f52c2794e85a5dd8be68cf1d51821ff9a4e7daddbad891f96cef49a27 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormFieldOptions.md -->

<!-- prettier-ignore-start -->
# Class FormFieldOptions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormFieldOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOptions.md)

The class represents the list of options for a field. The class supports
an index style access to the options, e.g. myfield.options\[2\] or
myfield.options.red.



## Property Summary

| Property | Description |
| --- | --- |
| [optionsCount](#optionscount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of option values. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getOptionsCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOptions.md#getoptionscount)() | Returns the number of option values. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### optionsCount
- optionsCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of option values.


---

## Method Details

### getOptionsCount()
- getOptionsCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of option values.


---

<!-- prettier-ignore-end -->

<!-- document id=5ce259e32586abc59540a0c320c9fb2ca48ad36b4e7a89de77bb6f86c87da707 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormGroup.md -->

<!-- prettier-ignore-start -->
# Class FormGroup

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)
    - [dw.web.FormGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md)

The class is the central class within the whole form handling. It is
the container element for fields and other form elements. A form group
can contain other forms, also called sub-forms.

Access to the elements of a form is provided via an index based access or
via an associative array access. For example, the field "firstname" can be accessed
with the expression "myform.firstname".



## All Known Subclasses
[Form](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md), [FormList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md), [FormListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md)
## Property Summary

| Property | Description |
| --- | --- |
| [childCount](#childcount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of elements in the form. |
| [error](#error): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns a form-wide error message. |
| [object](#object): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | The object that was bound to this form group. |
| [submittedAction](#submittedaction): [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md) `(read-only)` | Returns the action that was submitted with the last request. |
| [triggeredAction](#triggeredaction): [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md) `(read-only)` | Returns the action that was triggered with the last request. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [accept](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#accept)() | The method copies the value from a form into the object, which was previously  bound to the form. |
| [copyFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copyfromobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method updates the form with the values from the given object.    The method call is basically equivalent to the pipelet UpdateFormWithObject.    The method not only copies the value, it also binds the object to the form. |
| [copyTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copytoobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method updates the object with the values from the form.    The method call is basically equivalent to the pipelet UpdateObjectWithForm.    The method needs a submitted form. |
| [getChildCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getchildcount)() | Returns the number of elements in the form. |
| [getError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#geterror)() | Returns a form-wide error message. |
| [getObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getobject)() | The object that was bound to this form group. |
| [getSubmittedAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getsubmittedaction)() | Returns the action that was submitted with the last request. |
| [getTriggeredAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#gettriggeredaction)() | Returns the action that was triggered with the last request. |

### Methods inherited from class FormElement

[clearFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#clearformelement), [getDynamicHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getdynamichtmlname), [getFormId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getformid), [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#gethtmlname), [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getparent), [getValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getvalidationresult), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelement), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelementstring), [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#isvalid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### childCount
- childCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of elements in the form.


---

### error
- error: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns a form-wide error message. If no error message
      is present the method returns null.



---

### object
- object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : The object that was bound to this form group.


---

### submittedAction
- submittedAction: [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md) `(read-only)`
  - : Returns the action that was submitted with the last request. The action is
      set independent whether the form must be valid for this action. The method
      returns null if no action at all was submitted with the last request for this
      form group.



---

### triggeredAction
- triggeredAction: [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md) `(read-only)`
  - : Returns the action that was triggered with the last request. An action is
      only marked as triggered if the constraints regarding form validation are
      meet. The method returns null if no action was marked as triggered.



---

## Method Details

### accept()
- accept(): void
  - : The method copies the value from a form into the object, which was previously
      bound to the form. The method is equivalent to the pipelet AcceptForm.
      
      This method is equivalent to the call formgroup.copyFrom( formgroup.object ).



---

### copyFrom(Object)
- copyFrom(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method updates the form with the values from the given object.
      
      
      
      The method call is basically equivalent to the pipelet UpdateFormWithObject.
      
      
      
      The method not only copies the value, it also binds the object to the form. Binding means that the form keeps the
      information from which objects the values were taken. This can be used for two purposes:
      
      1. for lists it makes it easier in the code to find the associated object, for example in case of a related   action, and
      2. it allows to copy back the values from the form into the object (see [accept()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#accept)).
      
      Because of this bind behavior, the operation is also sometimes called a bind-operation.


    **Parameters:**
    - obj - the object from, which the values are read


---

### copyTo(Object)
- copyTo(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method updates the object with the values from the form.
      
      
      
      The method call is basically equivalent to the pipelet UpdateObjectWithForm.
      
      
      
      The method needs a submitted form. The copyTo call is delegated to the form fields. Each form field than checks
      if its value was submitted as part of the form:
      
      - If this is _true_, the object gets updated with the form field value.
      - If this is _false_, the object will not be updated.
      
      This is the reason why you cannot copy values from one object into another object by using
      [copyFrom(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copyfromobject) and [copyTo(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copytoobject) within the same request (e.g. by one call to a script or
      controller).


    **Parameters:**
    - obj - the object, which is updated from the form


---

### getChildCount()
- getChildCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of elements in the form.

    **Returns:**
    - the number of elements in the form.


---

### getError()
- getError(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a form-wide error message. If no error message
      is present the method returns null.


    **Returns:**
    - a form-wide error message or null.


---

### getObject()
- getObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : The object that was bound to this form group.

    **Returns:**
    - the bound object.


---

### getSubmittedAction()
- getSubmittedAction(): [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md)
  - : Returns the action that was submitted with the last request. The action is
      set independent whether the form must be valid for this action. The method
      returns null if no action at all was submitted with the last request for this
      form group.


    **Returns:**
    - the action that was submitted with the last request or null.


---

### getTriggeredAction()
- getTriggeredAction(): [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md)
  - : Returns the action that was triggered with the last request. An action is
      only marked as triggered if the constraints regarding form validation are
      meet. The method returns null if no action was marked as triggered.


    **Returns:**
    - the action that was triggered with the last request.


---

<!-- prettier-ignore-end -->

<!-- document id=f1d916f0293cc28e9b57f3be226468ebe29ff706d305ec8e87ec72da3088e2f9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormList.md -->

<!-- prettier-ignore-start -->
# Class FormList

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)
    - [dw.web.FormGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md)
      - [dw.web.FormList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md)

Represents a list of forms.


## Property Summary

| Property | Description |
| --- | --- |
| [selectManyItems](#selectmanyitems): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | returns the selected list items if the list is  configured to support selection of items. |
| [selectManyObjects](#selectmanyobjects): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns a list of all selected objects if the list is configured  to support the selection of items. |
| [selectOneItem](#selectoneitem): [FormListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md) `(read-only)` | Returns the default list item if the list is configured to  support the selection of a default item. |
| [selectOneObject](#selectoneobject): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the selected object if the list is configured to  support the selection of a default item. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSelectManyItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md#getselectmanyitems)() | returns the selected list items if the list is  configured to support selection of items. |
| [getSelectManyObjects](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md#getselectmanyobjects)() | Returns a list of all selected objects if the list is configured  to support the selection of items. |
| [getSelectOneItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md#getselectoneitem)() | Returns the default list item if the list is configured to  support the selection of a default item. |
| [getSelectOneObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md#getselectoneobject)() | Returns the selected object if the list is configured to  support the selection of a default item. |

### Methods inherited from class FormGroup

[accept](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#accept), [copyFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copyfromobject), [copyTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copytoobject), [getChildCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getchildcount), [getError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#geterror), [getObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getobject), [getSubmittedAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getsubmittedaction), [getTriggeredAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#gettriggeredaction)
### Methods inherited from class FormElement

[clearFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#clearformelement), [getDynamicHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getdynamichtmlname), [getFormId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getformid), [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#gethtmlname), [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getparent), [getValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getvalidationresult), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelement), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelementstring), [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#isvalid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### selectManyItems
- selectManyItems: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : returns the selected list items if the list is
      configured to support selection of items.



---

### selectManyObjects
- selectManyObjects: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns a list of all selected objects if the list is configured
      to support the selection of items. The objects are the objects that were
      bound to each row.



---

### selectOneItem
- selectOneItem: [FormListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md) `(read-only)`
  - : Returns the default list item if the list is configured to
      support the selection of a default item.



---

### selectOneObject
- selectOneObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the selected object if the list is configured to
      support the selection of a default item. The object is the object
      bound to the item.



---

## Method Details

### getSelectManyItems()
- getSelectManyItems(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : returns the selected list items if the list is
      configured to support selection of items.


    **Returns:**
    - a List of FormListItem elements or null if no selection was configured for the form.


---

### getSelectManyObjects()
- getSelectManyObjects(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list of all selected objects if the list is configured
      to support the selection of items. The objects are the objects that were
      bound to each row.


    **Returns:**
    - a List of objects or null if no selection was configured for the form.


---

### getSelectOneItem()
- getSelectOneItem(): [FormListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md)
  - : Returns the default list item if the list is configured to
      support the selection of a default item.


    **Returns:**
    - the default FormListItem elements or null if no selection was configured


---

### getSelectOneObject()
- getSelectOneObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the selected object if the list is configured to
      support the selection of a default item. The object is the object
      bound to the item.


    **Returns:**
    - the selected object.


---

<!-- prettier-ignore-end -->

<!-- document id=6f8d45e887ce47a4c782b7df405e3bc0255d43b2904ce0a11608d1e4fd076dcd url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.FormListItem.md -->

<!-- prettier-ignore-start -->
# Class FormListItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)
    - [dw.web.FormGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md)
      - [dw.web.FormListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md)

Represents an item in a form list.


## Property Summary

| Property | Description |
| --- | --- |
| [itemIndex](#itemindex): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the index of this item with the list. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getItemIndex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md#getitemindex)() | Returns the index of this item with the list. |

### Methods inherited from class FormGroup

[accept](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#accept), [copyFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copyfromobject), [copyTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#copytoobject), [getChildCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getchildcount), [getError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#geterror), [getObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getobject), [getSubmittedAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#getsubmittedaction), [getTriggeredAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md#gettriggeredaction)
### Methods inherited from class FormElement

[clearFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#clearformelement), [getDynamicHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getdynamichtmlname), [getFormId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getformid), [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#gethtmlname), [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getparent), [getValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#getvalidationresult), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelement), [invalidateFormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#invalidateformelementstring), [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md#isvalid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### itemIndex
- itemIndex: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the index of this item with the list.


---

## Method Details

### getItemIndex()
- getItemIndex(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index of this item with the list.

    **Returns:**
    - the index of this item with the list.


---

<!-- prettier-ignore-end -->

<!-- document id=1c1cd1b0a5cf46cf13305d86770c5dad3dc3f0d5bc4e0111c67098f18986e4dc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.Forms.md -->

<!-- prettier-ignore-start -->
# Class Forms

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.Forms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Forms.md)

The Forms object provides access to all current forms in the session. The individual forms are retrieved as a dynamic
property, for example 'forms.searchform'. It is typically retrieved from the session via
[Session.getForms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getforms). But it is also available in the [PipelineDictionary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.PipelineDictionary.md) and can be
accessed via 'pdict.CurrentForms'.


Note that values stored with a form on the session are deleted if the request locale is changed during the session.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=0c13a3f566edd81bb5af5d27f028b245d6e5e8cac50de7dddc91ae8ed73a024b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.FreeDiscount.md -->

<!-- prettier-ignore-start -->
# Class FreeDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.FreeDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FreeDiscount.md)

Represents a _free_ discount in the discount plan, for example
"Free shipping on all orders $25 or more."



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=1a13b45dd891fc8080393767147187b3631e8e73aa12c16e3686e848ec637e32 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.FreeShippingDiscount.md -->

<!-- prettier-ignore-start -->
# Class FreeShippingDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.FreeShippingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FreeShippingDiscount.md)

Represents a _free shipping_ discount in the discount plan, for example
"Free shipping on all iPods."



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=b55b2becc24eb8441661243862f7831ba4a8ef0f96a763a10a796dd71cf20a4e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.FTPClient.md -->

<!-- prettier-ignore-start -->
# Class FTPClient

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.FTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md)

The FTPClient class supports the FTP commands CD, GET, PUT, DEL, MKDIR, RENAME, and LIST. The FTP connection is
established using passive transfer mode (PASV). The transfer of files can be text or binary.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.


An example usage is as follows:




```

 var ftp : FTPClient = new dw.net.FTPClient();
 ftp.connect("my.ftp-server.com", "username", "password");
 var data : String = ftp.get("simple.txt");
 ftp.disconnect();
```



The default connection timeout depends on the script context timeout and will be set to a maximum of 30 seconds
(default script context timeout is 10 seconds within storefront requests and 15 minutes within jobs).


**IMPORTANT NOTE:** Before you can make an outbound FTP connection, the FTP server IP address must be enabled for
outbound traffic at the Commerce Cloud Digital firewall for your POD. Please file a support request to request a new firewall
rule.


**Deprecated:**
**warning:** The FTPClient is deprecated. Use [SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md) for a secure alternative.

## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[DEFAULT_GET_FILE_SIZE](#default_get_file_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5242880~~ | The default size for `get()` returning a File is 5MB |
| ~~[DEFAULT_GET_STRING_SIZE](#default_get_string_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2097152~~ | The default size for `get()` returning a String is 2MB |
| [MAX_GET_FILE_SIZE](#max_get_file_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200 | The maximum size for `get()` returning a File is forty times the default size for getting a file. |
| [MAX_GET_STRING_SIZE](#max_get_string_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760 | The maximum size for `get()` returning a String is five times the default size for getting a String. |

## Property Summary

| Property | Description |
| --- | --- |
| [connected](#connected): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the FTP client is currently connected to the FTP server. |
| [replyCode](#replycode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the reply code from the last FTP action. |
| [replyMessage](#replymessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the string message from the last FTP action. |
| [timeout](#timeout): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the timeout for this client, in milliseconds. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [FTPClient](#ftpclient)() | Constructs the FTPClient instance. |

## Method Summary

| Method | Description |
| --- | --- |
| [cd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#cdstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Changes the current directory on the remote server to the given path. |
| [connect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#connectstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Connects and logs on to an FTP Server as "anonymous" and returns a boolean indicating success or failure. |
| [connect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#connectstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Connects and logs on to an FTP Server as "anonymous" and returns a boolean indicating success or failure. |
| [connect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#connectstring-number-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Connects and logs on to an FTP server and returns a boolean indicating success or failure. |
| [connect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#connectstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Connects and logs on to an FTP server and returns a boolean indicating success or failure. |
| [del](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#delstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Deletes the remote file on the server identified by the path parameter. |
| [disconnect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#disconnect)() | The method first logs the current user out from the server and then disconnects from the server. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Reads the content of a remote file and returns it as a string using "ISO-8859-1" encoding to read it. |
| ~~[get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Reads the content of a remote file and returns it as a string using "ISO-8859-1" encoding to read it. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Reads the content of a remote file and returns it as string using the passed encoding. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring-string-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Reads the content of a remote file and creates a local copy in the given file using the passed string encoding to  read the file content and using the system standard encoding "UTF-8" to write the file. |
| ~~[get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring-string-file-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Reads the content of a remote file and creates a local copy in the given file using the passed string encoding to  read the file content and using the system standard encoding "UTF-8" to write the file. |
| ~~[get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring-string-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Reads the content of a remote file and returns it as a string using the specified encoding. |
| [getBinary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getbinarystring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Reads the content of a remote file and creates a local copy in the given file. |
| ~~[getBinary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getbinarystring-file-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Reads the content of a remote file and creates a local copy in the given file. |
| [getConnected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getconnected)() | Identifies if the FTP client is currently connected to the FTP server. |
| [getReplyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getreplycode)() | Returns the reply code from the last FTP action. |
| [getReplyMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getreplymessage)() | Returns the string message from the last FTP action. |
| [getTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#gettimeout)() | Returns the timeout for this client, in milliseconds. |
| [list](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#list)() | Returns a list of FTPFileInfo objects containing information about the files in the current directory. |
| [list](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#liststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a list of FTPFileInfo objects containing information about the files in the remote directory defined by  the given path. |
| [mkdir](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#mkdirstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a directory |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#putstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Puts the specified content to the specified full path using "ISO-8859-1" encoding. |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#putstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Put the given content to a file on the given full path on the FTP server. |
| [putBinary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#putbinarystring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Put the content of the given file into a file on the remote FTP server with the given full path. |
| [removeDirectory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#removedirectorystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Deletes the remote directory on the server identified by the path parameter. |
| [rename](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#renamestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Renames an existing file. |
| [setTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#settimeoutnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the timeout for connections made with the FTP client to the given number of milliseconds. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DEFAULT_GET_FILE_SIZE

- ~~DEFAULT_GET_FILE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5242880~~
  - : The default size for `get()` returning a File is 5MB

    **Deprecated:**
**warning:** The default size is not supported anymore. The `get()` methods returning a file will
            always try to return [MAX_GET_FILE_SIZE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#max_get_file_size) bytes instead.

---

### DEFAULT_GET_STRING_SIZE

- ~~DEFAULT_GET_STRING_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2097152~~
  - : The default size for `get()` returning a String is 2MB

    **Deprecated:**
**warning:** The default size is not supported anymore. The `get()` methods returning a String will
            always try to return [MAX_GET_STRING_SIZE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#max_get_string_size) bytes instead.

---

### MAX_GET_FILE_SIZE

- MAX_GET_FILE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200
  - : The maximum size for `get()` returning a File is forty times the default size for getting a file. The
      largest file allowed is 200MB.



---

### MAX_GET_STRING_SIZE

- MAX_GET_STRING_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760
  - : The maximum size for `get()` returning a String is five times the default size for getting a String.
      The largest String allowed is 10MB.



---

## Property Details

### connected
- connected: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the FTP client is currently connected to the FTP server.


---

### replyCode
- replyCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the reply code from the last FTP action.


---

### replyMessage
- replyMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the string message from the last FTP action.


---

### timeout
- timeout: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the timeout for this client, in milliseconds.


---

## Constructor Details

### FTPClient()
- FTPClient()
  - : Constructs the FTPClient instance.


---

## Method Details

### cd(String)
- cd(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Changes the current directory on the remote server to the given path.

    **Parameters:**
    - path - the new current directory

    **Returns:**
    - true if the directory change was okay


---

### connect(String)
- connect(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Connects and logs on to an FTP Server as "anonymous" and returns a boolean indicating success or failure.

    **Parameters:**
    - host - Name of the FTP sever

    **Returns:**
    - true when connection is successful, false otherwise.


---

### connect(String, Number)
- connect(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), port: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Connects and logs on to an FTP Server as "anonymous" and returns a boolean indicating success or failure.

    **Parameters:**
    - host - Name of the FTP sever
    - port - Port for FTP server

    **Returns:**
    - true when connection is successful, false otherwise.


---

### connect(String, Number, String, String)
- connect(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), port: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), user: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Connects and logs on to an FTP server and returns a boolean indicating success or failure.

    **Parameters:**
    - host - Name of the FTP sever
    - port - Port for FTP server
    - user - Username for the login
    - password - Password for the login

    **Returns:**
    - true when connection is successful, false otherwise.


---

### connect(String, String, String)
- connect(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), user: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Connects and logs on to an FTP server and returns a boolean indicating success or failure.

    **Parameters:**
    - host - Name of the FTP sever
    - user - Username for the login
    - password - Password for the login

    **Returns:**
    - true when connection is successful, false otherwise.


---

### del(String)
- del(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Deletes the remote file on the server identified by the path parameter.

    **Parameters:**
    - path - the path to the file.

    **Returns:**
    - true if the file was successfully deleted, false otherwise.


---

### disconnect()
- disconnect(): void
  - : The method first logs the current user out from the server and then disconnects from the server.


---

### get(String)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a remote file and returns it as a string using "ISO-8859-1" encoding to read it. Read at
      most MAX\_GET\_STRING\_SIZE bytes.


    **Parameters:**
    - path - remote path of the file to be read.

    **Returns:**
    - the contents of the file or null if an error occurred while reading the file.


---

### get(String, Number)
- ~~get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxGetSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Reads the content of a remote file and returns it as a string using "ISO-8859-1" encoding to read it. Read at
      most maxGetSize characters.


    **Parameters:**
    - path - remote path of the file to be read.
    - maxGetSize - the maximum bytes fetched from the remote file.

    **Returns:**
    - the contents of the file or null if an error occurred while reading the file.

    **Deprecated:**
**warning:** The maxGetSize attribute is not supported anymore. Use the method [get(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring) instead.

---

### get(String, String)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a remote file and returns it as string using the passed encoding. Read at most
      MAX\_GET\_STRING\_SIZE characters.


    **Parameters:**
    - path - remote path of the file to be read.
    - encoding - an ISO 8859 character encoding labeled as a string, e.g. "ISO-8859-1"

    **Returns:**
    - the contents of the file or null if an error occurred while reading the file.


---

### get(String, String, File)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote file and creates a local copy in the given file using the passed string encoding to
      read the file content and using the system standard encoding "UTF-8" to write the file. Copies at most
      MAX\_GET\_FILE\_SIZE bytes.


    **Parameters:**
    - path - remote path of the file to be read.
    - encoding - the encoding to use.
    - file - the local file name

    **Returns:**
    - true if remote file is fetched and copied into local file.


---

### get(String, String, File, Number)
- ~~get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), maxGetSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Reads the content of a remote file and creates a local copy in the given file using the passed string encoding to
      read the file content and using the system standard encoding "UTF-8" to write the file. Copies at most maxGetSize
      bytes.


    **Parameters:**
    - path - remote path of the file to be read.
    - encoding - the encoding to use.
    - file - the local file name
    - maxGetSize - the maximum number of bytes to fetch

    **Returns:**
    - true if remote file is fetched and copied into local file.

    **Deprecated:**
**warning:** The maxGetSize attribute is not supported anymore. Use the method [get(String, String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring-string-file)
            instead.

---

### get(String, String, Number)
- ~~get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxGetSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Reads the content of a remote file and returns it as a string using the specified encoding. Returns at most
      maxGetSize characters.


    **Parameters:**
    - path - remote path of the file to be read.
    - encoding - the encoding to use.
    - maxGetSize - the maximum bytes fetched from the remote file.

    **Returns:**
    - the contents of the file or null if an error occurred while reading the file.

    **Deprecated:**
**warning:** The maxGetSize attribute is not supported anymore. Use the method [get(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getstring-string)
            instead.

---

### getBinary(String, File)
- getBinary(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote file and creates a local copy in the given file. Copies at most MAX\_GET\_FILE\_SIZE
      bytes. The FTP transfer is done in Binary mode.


    **Parameters:**
    - path - remote path of the file to be read.
    - file - the local file name

    **Returns:**
    - true if remote file is fetched and copied into local file.


---

### getBinary(String, File, Number)
- ~~getBinary(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), maxGetSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Reads the content of a remote file and creates a local copy in the given file. Copies at most maxGetSize bytes.
      The FTP transfer is done in Binary mode.


    **Parameters:**
    - path - remote path of the file to be read.
    - file - the local file name
    - maxGetSize - the maximum number of bytes to fetch

    **Returns:**
    - true if remote file is fetched and copied into local file.

    **Deprecated:**
**warning:** The maxGetSize attribute is not supported anymore. Use the method [getBinary(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#getbinarystring-file)
            instead.

---

### getConnected()
- getConnected(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the FTP client is currently connected to the FTP server.

    **Returns:**
    - true if the client is currently connected.


---

### getReplyCode()
- getReplyCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the reply code from the last FTP action.

    **Returns:**
    - the reply code from the last FTP action.


---

### getReplyMessage()
- getReplyMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string message from the last FTP action.

    **Returns:**
    - the string message from the last FTP action.


---

### getTimeout()
- getTimeout(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the timeout for this client, in milliseconds.

    **Returns:**
    - the timeout in milliseconds


---

### list()
- list(): [FTPFileInfo\[\]](dw.net.FTPFileInfo.md)
  - : Returns a list of FTPFileInfo objects containing information about the files in the current directory.

    **Returns:**
    - list of objects with remote file information.


---

### list(String)
- list(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [FTPFileInfo\[\]](dw.net.FTPFileInfo.md)
  - : Returns a list of FTPFileInfo objects containing information about the files in the remote directory defined by
      the given path.


    **Parameters:**
    - path - the remote path from which the file info is listed.

    **Returns:**
    - list of objects with remote file information.


---

### mkdir(String)
- mkdir(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Creates a directory

    **Parameters:**
    - path - the path to the directory to create.

    **Returns:**
    - true if the directory was successfully created, false otherwise.


---

### put(String, String)
- put(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Puts the specified content to the specified full path using "ISO-8859-1" encoding. The full path must include the
      path and the file name. If the content of a local file is to be uploaded, please use method
      [putBinary(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#putbinarystring-file) instead.


    **Parameters:**
    - path - full path on the remote FTP server where the file will be stored.
    - content - the content to put.

    **Returns:**
    - true or false indicating success or failure.


---

### put(String, String, String)
- put(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Put the given content to a file on the given full path on the FTP server. The full path must include the path and
      the file name. The transformation from String into binary data is done via the encoding provided with the method
      call. If the content of a local file is to be uploaded, please use method [putBinary(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#putbinarystring-file)
      instead.


    **Parameters:**
    - path - the full path on the remote FTP server where the file will be stored.
    - content - the content to put.
    - encoding - the encoding to use.

    **Returns:**
    - true or false indicating success or failure.


---

### putBinary(String, File)
- putBinary(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Put the content of the given file into a file on the remote FTP server with the given full path. The full path
      must include the path and the file name.


    **Parameters:**
    - path - the full path on the remote FTP server where the file will be stored.
    - file - the file on the local system, which content is send to the remote FTP server.

    **Returns:**
    - true or false indicating success or failure.


---

### removeDirectory(String)
- removeDirectory(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Deletes the remote directory on the server identified by the path parameter. In order to delete the directory
      successfully the directory needs to be empty, otherwise the removeDirectory() method will return false.


    **Parameters:**
    - path - the path to the directory.

    **Returns:**
    - true if the directory was successfully deleted, false otherwise.


---

### rename(String, String)
- rename(from: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), to: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Renames an existing file.

    **Parameters:**
    - from - the file that will be renamed.
    - to - the name of the new file.

    **Returns:**
    - true if the file was successfully renamed, false otherwise.


---

### setTimeout(Number)
- setTimeout(timeoutMillis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the timeout for connections made with the FTP client to the given number of milliseconds. If the given
      timeout is less than or equal to zero, the timeout is set to the same value as the script context timeout but
      will only be set to a maximum of 30 seconds.
      
      
      The maximum and default timeout depend on the script context timeout. The maximum timeout is set to a maximum of
      2 minutes. The default timeout for a new client is set to a maximum of 30 seconds.
      
      
      This method can be called at any time, and will affect the next connection made with this client. It is not
      possible to set the timeout for an open connection.


    **Parameters:**
    - timeoutMillis - timeout, in milliseconds, up to a maximum of 2 minutes.


---

<!-- prettier-ignore-end -->

<!-- document id=b0af78b0f99da274f2dcd6d4faf9eb274a06d463d3de075e092f41159adedfd9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.FTPFileInfo.md -->

<!-- prettier-ignore-start -->
# Class FTPFileInfo

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.FTPFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPFileInfo.md)

The class is used to store information about a remote file.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.


**Deprecated:**
**warning:** The FTPClient is deprecated. Use [SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md) for a secure alternative.

## Property Summary

| Property | Description |
| --- | --- |
| [directory](#directory): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the file is a directory. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the file. |
| [size](#size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the size of the file. |
| [timestamp](#timestamp): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the timestamp of the file. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [FTPFileInfo](#ftpfileinfostring-number-boolean-date)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Constructs the FTPFileInfo instance. |

## Method Summary

| Method | Description |
| --- | --- |
| [getDirectory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPFileInfo.md#getdirectory)() | Identifies if the file is a directory. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPFileInfo.md#getname)() | Returns the name of the file. |
| [getSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPFileInfo.md#getsize)() | Returns the size of the file. |
| [getTimestamp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPFileInfo.md#gettimestamp)() | Returns the timestamp of the file. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### directory
- directory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the file is a directory.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the file.


---

### size
- size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the size of the file.


---

### timestamp
- timestamp: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the timestamp of the file.


---

## Constructor Details

### FTPFileInfo(String, Number, Boolean, Date)
- FTPFileInfo(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), directory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), timestamp: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md))
  - : Constructs the FTPFileInfo instance.

    **Parameters:**
    - name - the name of the file.
    - size - the size of the file.
    - directory - controls if the file is a directory.
    - timestamp - the timestamp of the file.


---

## Method Details

### getDirectory()
- getDirectory(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the file is a directory.

    **Returns:**
    - true if the file is a directory, false otherwise.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the file.

    **Returns:**
    - the name of the file.


---

### getSize()
- getSize(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the file.

    **Returns:**
    - the size of the file.


---

### getTimestamp()
- getTimestamp(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the timestamp of the file.

    **Returns:**
    - the timestamp of the file.


---

<!-- prettier-ignore-end -->

<!-- document id=d2f97c85bda9196b0d3357513a73499a2ac248760b62d873d5d288e995a4e155 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.FTPService.md -->

<!-- prettier-ignore-start -->
# Class FTPService

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
    - [dw.svc.FTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md)

Represents an FTP or SFTP Service.


There are two basic styles of configuration for this service.


In the first style, `createRequest` is implemented to call the setOperation method on the Service. This
will cause the single operation to be performed and returned as the data object in the `parseResponse`
method. Any error status is set automatically based on the returned value of the operation.


In the second style, `execute` is implemented to perform one or more operations using the serviceClient
available on the Service object. This serviceClient will be either an [FTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md) or an
[SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md). The return value of execute will be passed as the data object in the
`parseResponse` method.


Note that the use of the FTP client is deprecated, and SFTP should be used instead.



## Property Summary

| Property | Description |
| --- | --- |
| [autoDisconnect](#autodisconnect): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns the status of whether the underlying FTP connection will be disconnected after the service call. |
| [client](#client): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the underlying client object. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md#getclient)() | Returns the underlying client object. |
| [isAutoDisconnect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md#isautodisconnect)() | Returns the status of whether the underlying FTP connection will be disconnected after the service call. |
| [setAutoDisconnect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md#setautodisconnectboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the auto-disconnect flag. |
| [setOperation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md#setoperationstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets a single operation to perform during the execute phase of the service. |

### Methods inherited from class Service

[call](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getconfiguration), [getCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getcredentialid), [getRequestData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getrequestdata), [getResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getresponse), [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#geturl), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#isthrowonerror), [setCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setcredentialidstring), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setthrowonerror), [setURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#seturlstring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### autoDisconnect
- autoDisconnect: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the underlying FTP connection will be disconnected after the service call.


---

### client
- client: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the underlying client object.
      
      
      This is either an [FTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md) or [SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md), depending on the protocol.



---

## Method Details

### getClient()
- getClient(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the underlying client object.
      
      
      This is either an [FTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md) or [SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md), depending on the protocol.


    **Returns:**
    - (S)FTP Client object.


---

### isAutoDisconnect()
- isAutoDisconnect(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the underlying FTP connection will be disconnected after the service call.

    **Returns:**
    - The auto-disconnect flag.


---

### setAutoDisconnect(Boolean)
- setAutoDisconnect(b: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [FTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md)
  - : Sets the auto-disconnect flag.
      
      
      If true, the underlying FTP connection will be disconnected after the service call. If false then it will remain
      open. The default value is true.


    **Parameters:**
    - b - true to enable auto-disconnect, false otherwise.

    **Returns:**
    - this FTP or SFTP Service.


---

### setOperation(String, Object...)
- setOperation(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [FTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md)
  - : Sets a single operation to perform during the execute phase of the service.
      
      
      The given arguments make up a method name and arguments on the underlying [getClient()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md#getclient) object. This
      method will be invoked during execution, with the result passed into the callback's parseResponse method.
      
      
      This is required unless the callback defines an execute method.


    **Parameters:**
    - name - Method name.
    - args - Method arguments.

    **Returns:**
    - this FTP or SFTP Service.


---

<!-- prettier-ignore-end -->

<!-- document id=66fd0d18aeddc5579cac91a8330178e255adc523bc681f9165b084a96f1b62ca url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.FTPServiceDefinition.md -->

<!-- prettier-ignore-start -->
# Class FTPServiceDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
    - [dw.svc.FTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPServiceDefinition.md)

Represents an FTP or SFTP Service Definition.


There are two basic styles of configuration for this service.


In the first style, `createRequest` is implemented to call the setOperation method on the Service. This
will cause the single operation to be performed and returned as the data object in the `parseResponse`
method. Any error status is set automatically based on the returned value of the operation.


In the second style, `execute` is implemented to perform one or more operations using the serviceClient
available on the Service object. This serviceClient will be either an [FTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md) or an
[SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md). The return value of execute will be passed as the data object in the
`parseResponse` method.


**Deprecated:**
**warning:** This class is only used with the deprecated [ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md). Use the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)
            instead, which allows configuration on the [FTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md) directly.
**API Version:**
**note:** No longer available as of version 19.10.

## Property Summary

| Property | Description |
| --- | --- |
| [autoDisconnect](#autodisconnect): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns the status of whether the underlying FTP connection will be disconnected after the service call. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [isAutoDisconnect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPServiceDefinition.md#isautodisconnect)() | Returns the status of whether the underlying FTP connection will be disconnected after the service call. |
| [setAutoDisconnect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPServiceDefinition.md#setautodisconnectboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the auto-disconnect flag. |

### Methods inherited from class ServiceDefinition

[configure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#configureobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getconfiguration), [getServiceName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getservicename), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#isthrowonerror), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setthrowonerror)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### autoDisconnect
- autoDisconnect: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the underlying FTP connection will be disconnected after the service call.


---

## Method Details

### isAutoDisconnect()
- isAutoDisconnect(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the underlying FTP connection will be disconnected after the service call.

    **Returns:**
    - The auto-disconnect flag.


---

### setAutoDisconnect(Boolean)
- setAutoDisconnect(b: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [FTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPServiceDefinition.md)
  - : Sets the auto-disconnect flag.
      
      
      If true, the underlying FTP connection will be disconnected after the service call. If false then it will remain
      open. The default value is true.


    **Parameters:**
    - b - true to enable auto-disconnect, false otherwise.

    **Returns:**
    - this FTP or SFTP Service Definition.


---

<!-- prettier-ignore-end -->

<!-- document id=fcf360ece8466df478c5438a2c604ab0a0c71ed85140117d7b87a090ca8e0f62 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Function.md -->

<!-- prettier-ignore-start -->
# Class Function

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)

The Function class represent a JavaScript function.


## Property Summary

| Property | Description |
| --- | --- |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of named arguments that were specified  when the function was declared. |
| [prototype](#prototype): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | An object that defines properties and methods  shared by all objects created with that  constructor function. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Function](#functionstring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the function with the specified arguments where the  last argument represents the function body and all preceeding arguments represent  the function parameters. |

## Method Summary

| Method | Description |
| --- | --- |
| [apply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md#applyobject-array)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Invokes this function as a method of the specified object  passing the specified Array of arguments. |
| [call](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md#callobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Invokes this function as a method of the specified object  passing the specified optional arguments. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md#tostring)() | Returns a String representation of this function object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of named arguments that were specified
      when the function was declared.



---

### prototype
- prototype: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : An object that defines properties and methods
      shared by all objects created with that
      constructor function.



---

## Constructor Details

### Function(String...)
- Function(args: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the function with the specified arguments where the
      last argument represents the function body and all preceeding arguments represent
      the function parameters.


    **Parameters:**
    - args - one or more Strings where the last argument in the list  represents the function body and all preceeding arguments represent  the function parameters.


---

## Method Details

### apply(Object, Array)
- apply(thisobj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), args: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Invokes this function as a method of the specified object
      passing the specified Array of arguments.


    **Parameters:**
    - thisobj - the object to which the function is applied.
    - args - Array of values or an arguments object to be passed  as arguments to the function.

    **Returns:**
    - whatever value is returned by the invocation of the function.


---

### call(Object, Object...)
- call(thisobj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Invokes this function as a method of the specified object
      passing the specified optional arguments.


    **Parameters:**
    - thisobj - the object to which the function is applied.
    - args - an optional list of one or more arguments values  that are passed as arguments  to the function.

    **Returns:**
    - whatever value is returned by the invocation of the function.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a String representation of this function object.

    **Returns:**
    - a String representation of this function object.


---

<!-- prettier-ignore-end -->

<!-- document id=640cd21c7c907ac57bb9b1d6d1fafe9e6c620e26793568f41560a3f582b00dd9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Generator.md -->

<!-- prettier-ignore-start -->
# Class Generator

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Generator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Generator.md)

A generator is a special type of function that works as a factory for
iterators and it allows you to define an iterative algorithm by writing a
single function which can maintain its own state. A function becomes a
generator if it contains one or more **yield** statements.


When a generator function is called, the body of the function does not
execute straight away; instead, it returns a generator-iterator object.
Each call to the generator-iterator's next() method will execute the
body of the function up to the next **yield** statement and return its result.
When either the end of the function or a return statement is reached,
a StopIteration exception is thrown.


For example, the following fib() function is a Fibonacci number generator,
that returns the generator when it encounters the **yield** statement:

```
function fib() {
   var fibNum = 0, j = 1;
   while (true) {
      **_yield_** fibNum;
      var t = fibNum;
      fibNum = j;
      j += t;
   }
}
```


To use the generator, simply call the next() method to access the values
returned by the function:

```
 var gen = fib();
 for (var i = 0; i < 10; i++) {
   document.write(**_gen.next()_** " ");
 }
```


**See Also:**
- [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterator.md)
- [StopIteration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.StopIteration.md)


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Generator](#generator)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Generator.md#close)() | Closes the iteration of the generator. |
| [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Generator.md#next)() | Resumes the iteration of the generator by continuing the function  at the statement after the **yield** statement. |
| [send](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Generator.md#sendobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Allows you to control the resumption of the iterative algorithm. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### Generator()
- Generator()
  - : 


---

## Method Details

### close()
- close(): void
  - : Closes the iteration of the generator. Any finally clauses active in
      the generator function are run. If a finally clause throws any
      exception other than StopIteration, the exception is propagated to
      the caller of the close() method.



---

### next()
- next(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Resumes the iteration of the generator by continuing the function
      at the statement after the **yield** statement. This function throws a
      StopIterator exception when there are no additional iterative steps.


    **Returns:**
    - the result of resuming the iterative algorithm or a StopIterator
      exception if the sequence is exhausted.


    **See Also:**
    - [StopIteration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.StopIteration.md)


---

### send(Object)
- send(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Allows you to control the resumption of the iterative algorithm. Once a
      generator has been started by calling its next() method, you can use
      send() and pass a specific value that will be treated as the result
      of the last **yield**. The generator will then return the operand of the
      subsequent **yield**.
      
      
      You can't start a generator at an arbitrary point; you must start
      it with next() before you can send() it a specific value. Note that
      calling send(undefined) is equivalent to calling next(). However,
      starting a newborn generator with any value other than 'undefined' when
      calling send() will result in a TypeError exception.


    **Parameters:**
    - value - the value to use.


---

<!-- prettier-ignore-end -->

<!-- document id=4fa5ac9ddd66eb6f21ddaa0310a11370c4716f1dbd640b26c27b5ffeef6d2c2d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Geolocation.md -->

<!-- prettier-ignore-start -->
# Class Geolocation

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)

Read-only class representing a position on the earth (latitude and longitude)
and information associated with that location (e.g. country, city, etc). The
Commerce Cloud Digital system can provide geolocation information for a Request
and this information can be used in customer group segmentation rules.


Note: This class is not related to the store locator API (i.e. the
GetNearestStores pipelet) which uses a static set of store locations loaded
into the system by the merchant.


This product includes GeoLite2 data created by MaxMind, available from
[http://www.maxmind.com](http://www.maxmind.com).



## Property Summary

| Property | Description |
| --- | --- |
| [available](#available): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if a valid GeoLocation was found for the IP address  (meaning at least Latitude and Longitude were found), false otherwise. |
| [city](#city): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the city name in English associated with this location. |
| [countryCode](#countrycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the ISO country code associated with this location. |
| [countryName](#countryname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the country name in English that the system associates with this location on the  earth. |
| [latitude](#latitude): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Get the latitude coordinate associated with this location which is a  number between -90.0 and +90.0. |
| [longitude](#longitude): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Get the longitude coordinate associated with this location which is a  number between -180.0 and +180.0. |
| [metroCode](#metrocode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the metro code associated with this location. |
| [postalCode](#postalcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the postal code associated with this location. |
| [regionCode](#regioncode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the region (e.g. |
| [regionName](#regionname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the region (e.g. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Geolocation](#geolocationstring-string-string-string-string-string-string-number-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructor for a Geolocation object |

## Method Summary

| Method | Description |
| --- | --- |
| [getCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getcity)() | Get the city name in English associated with this location. |
| [getCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getcountrycode)() | Get the ISO country code associated with this location. |
| [getCountryName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getcountryname)() | Get the country name in English that the system associates with this location on the  earth. |
| [getLatitude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getlatitude)() | Get the latitude coordinate associated with this location which is a  number between -90.0 and +90.0. |
| [getLongitude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getlongitude)() | Get the longitude coordinate associated with this location which is a  number between -180.0 and +180.0. |
| [getMetroCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getmetrocode)() | Get the metro code associated with this location. |
| [getPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getpostalcode)() | Get the postal code associated with this location. |
| [getRegionCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getregioncode)() | Get the region (e.g. |
| [getRegionName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#getregionname)() | Get the region (e.g. |
| [isAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md#isavailable)() | Returns 'true' if a valid GeoLocation was found for the IP address  (meaning at least Latitude and Longitude were found), false otherwise. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### available
- available: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if a valid GeoLocation was found for the IP address
      (meaning at least Latitude and Longitude were found), false otherwise.



---

### city
- city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the city name in English associated with this location.


---

### countryCode
- countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the ISO country code associated with this location.


---

### countryName
- countryName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the country name in English that the system associates with this location on the
      earth.



---

### latitude
- latitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Get the latitude coordinate associated with this location which is a
      number between -90.0 and +90.0.



---

### longitude
- longitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Get the longitude coordinate associated with this location which is a
      number between -180.0 and +180.0.



---

### metroCode
- metroCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the metro code associated with this location.


---

### postalCode
- postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the postal code associated with this location.


---

### regionCode
- regionCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the region (e.g. province or state) code for this location.


---

### regionName
- regionName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the region (e.g. province in state) name in English that the system
      associates with this location.



---

## Constructor Details

### Geolocation(String, String, String, String, String, String, String, Number, Number)
- Geolocation(countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), countryName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), regionCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), regionName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), metroCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), latitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), longitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructor for a Geolocation object

    **Parameters:**
    - countryCode - the ISO country code associated with this location.  The [two-character ISO          3166-1 alpha code](http://en.wikipedia.org/wiki/ISO\_3166-1) for the country.
    - countryName - the country name in English that the system associates with this location on the  earth.
    - regionCode - the region (e.g. province or state) code for this location.  This is a string up to three characters long containing the subdivision portion of the  [code](http://en.wikipedia.org/wiki/ISO\_3166-2).
    - regionName - the region (e.g. province in state) name in English that the system  associates with this location.
    - metroCode - the metro code associated with this location.  The metro code of the location if the location is in the US. See the  [  Google AdWords API](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions) for values
    - city - the city name in English associated with this location.
    - postalCode - the postal code associated with this location.
    - latitude - the latitude coordinate associated with this location which is a  number between -90.0 and +90.0.
    - longitude - the longitude coordinate associated with this location which is a  number between -180.0 and +180.0.


---

## Method Details

### getCity()
- getCity(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the city name in English associated with this location.

    **Returns:**
    - the city that the system associates with this location on the
              earth.



---

### getCountryCode()
- getCountryCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the ISO country code associated with this location.

    **Returns:**
    - The [two-character ISO
              3166-1 alpha code](http://en.wikipedia.org/wiki/ISO\_3166-1) for the country.



---

### getCountryName()
- getCountryName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the country name in English that the system associates with this location on the
      earth.


    **Returns:**
    - the country name that the system associates with this location on the
              earth.



---

### getLatitude()
- getLatitude(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Get the latitude coordinate associated with this location which is a
      number between -90.0 and +90.0.


    **Returns:**
    - The latitude of the location as a floating point number.


---

### getLongitude()
- getLongitude(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Get the longitude coordinate associated with this location which is a
      number between -180.0 and +180.0.


    **Returns:**
    - The longitude of the location as a floating point number.


---

### getMetroCode()
- getMetroCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the metro code associated with this location.

    **Returns:**
    - The metro code of the location if the location is in the US. See
              the [Google AdWords API](https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions) for returned values.



---

### getPostalCode()
- getPostalCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the postal code associated with this location.

    **Returns:**
    - The postal code of the location. Postal codes are not available
              for all countries. In some countries, this will only contain part
              of the postal code.



---

### getRegionCode()
- getRegionCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the region (e.g. province or state) code for this location.

    **Returns:**
    - This is a string up to three characters long containing the
              subdivision portion of the [code](http://en.wikipedia.org/wiki/ISO\_3166-2).



---

### getRegionName()
- getRegionName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the region (e.g. province in state) name in English that the system
      associates with this location.


    **Returns:**
    - the region name that the system associates with this location on
              the earth.



---

### isAvailable()
- isAvailable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if a valid GeoLocation was found for the IP address
      (meaning at least Latitude and Longitude were found), false otherwise.


    **Returns:**
    - 'true' if a valid GeoLocation was found for the IP address
      (meaning at least Latitude and Longitude were found), false otherwise.



---

<!-- prettier-ignore-end -->

<!-- document id=cd3c72af4994f73d0334e254d51bdff2a32b25cc7a4d08c48ea208065f25d0e8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.GiftCertificate.md -->

<!-- prettier-ignore-start -->
# Class GiftCertificate

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md)

Represents a Gift Certificate that can be used to purchase
products.



## Constant Summary

| Constant | Description |
| --- | --- |
| [STATUS_ISSUED](#status_issued): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Represents a status of 'issued', which indicates that the Gift Certificate  has been created and that it can be used to purchase products. |
| [STATUS_PARTIALLY_REDEEMED](#status_partially_redeemed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Represents a status of 'partially redeemed', which indicates that the Gift Certificate  has been used to purchase products, but that there is still a balance on  the gift certificate. |
| [STATUS_PENDING](#status_pending): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Represents a status of 'pending', which indicates that the Gift Certificate  has been created but that it cannot be used yet. |
| [STATUS_REDEEMED](#status_redeemed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | Represents a status of 'redeemed', which indicates that the Gift Certificate  has been used and no longer contains a balance. |

## Property Summary

| Property | Description |
| --- | --- |
| ~~[ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | Returns the code of the gift certificate. |
| [amount](#amount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the original amount on the gift certificate. |
| [balance](#balance): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the balance on the gift certificate. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the description string. |
| [enabled](#enabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns true if the Gift Certificate is enabled, false otherwise. |
| [giftCertificateCode](#giftcertificatecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the code of the gift certificate. |
| [maskedGiftCertificateCode](#maskedgiftcertificatecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the masked gift certificate code with  all but the last 4 characters replaced with a '\*' character. |
| [merchantID](#merchantid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the merchant ID of the gift certificate. |
| [message](#message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the message to include in the email of the person receiving  the gift certificate. |
| [orderNo](#orderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the order number |
| [recipientEmail](#recipientemail): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the email address of the person receiving  the gift certificate. |
| [recipientName](#recipientname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the person receiving  the gift certificate. |
| [senderName](#sendername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the person or organization that  sent the gift certificate or null if undefined. |
| [status](#status): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the status where the possible values are  STATUS\_PENDING, STATUS\_ISSUED, STATUS\_PARTIALLY\_REDEEMED  or STATUS\_REDEEMED. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getamount)() | Returns the original amount on the gift certificate. |
| [getBalance](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getbalance)() | Returns the balance on the gift certificate. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getdescription)() | Returns the description string. |
| [getGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getgiftcertificatecode)() | Returns the code of the gift certificate. |
| ~~[getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getid)()~~ | Returns the code of the gift certificate. |
| [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getmaskedgiftcertificatecode)() | Returns the masked gift certificate code with  all but the last 4 characters replaced with a '\*' character. |
| [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getmaskedgiftcertificatecodenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the masked gift certificate code with  all but the specified number of characters replaced with a '\*' character. |
| [getMerchantID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getmerchantid)() | Returns the merchant ID of the gift certificate. |
| [getMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getmessage)() | Returns the message to include in the email of the person receiving  the gift certificate. |
| [getOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getorderno)() | Returns the order number |
| [getRecipientEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getrecipientemail)() | Returns the email address of the person receiving  the gift certificate. |
| [getRecipientName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getrecipientname)() | Returns the name of the person receiving  the gift certificate. |
| [getSenderName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getsendername)() | Returns the name of the person or organization that  sent the gift certificate or null if undefined. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getstatus)() | Returns the status where the possible values are  STATUS\_PENDING, STATUS\_ISSUED, STATUS\_PARTIALLY\_REDEEMED  or STATUS\_REDEEMED. |
| [isEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#isenabled)() | Returns true if the Gift Certificate is enabled, false otherwise. |
| [setDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setdescriptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | An optional description that you can use to categorize the  gift certificate. |
| [setEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setenabledboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Controls if the Gift Certificate is enabled. |
| [setMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the message to include in the email of the person receiving  the gift certificate. |
| [setOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setordernostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the order number |
| [setRecipientEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setrecipientemailstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the email address of the person receiving  the gift certificate. |
| [setRecipientName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setrecipientnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the person receiving  the gift certificate. |
| [setSenderName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setsendernamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the person or organization that  sent the gift certificate. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#setstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the status of the gift certificate. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### STATUS_ISSUED

- STATUS_ISSUED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Represents a status of 'issued', which indicates that the Gift Certificate
      has been created and that it can be used to purchase products.



---

### STATUS_PARTIALLY_REDEEMED

- STATUS_PARTIALLY_REDEEMED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Represents a status of 'partially redeemed', which indicates that the Gift Certificate
      has been used to purchase products, but that there is still a balance on
      the gift certificate.



---

### STATUS_PENDING

- STATUS_PENDING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Represents a status of 'pending', which indicates that the Gift Certificate
      has been created but that it cannot be used yet.



---

### STATUS_REDEEMED

- STATUS_REDEEMED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : Represents a status of 'redeemed', which indicates that the Gift Certificate
      has been used and no longer contains a balance.



---

## Property Details

### ID
- ~~ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : Returns the code of the gift certificate. This redemption code is send to
      gift certificate recipient.


    **Deprecated:**
**warning:** Use [getGiftCertificateCode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getgiftcertificatecode)

---

### amount
- amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the original amount on the gift certificate.


---

### balance
- balance: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the balance on the gift certificate.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description string.


---

### enabled
- enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the Gift Certificate is enabled, false otherwise.


---

### giftCertificateCode
- giftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the code of the gift certificate. This redemption code is send to
      gift certificate recipient.



---

### maskedGiftCertificateCode
- maskedGiftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the masked gift certificate code with
      all but the last 4 characters replaced with a '\*' character.



---

### merchantID
- merchantID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the merchant ID of the gift certificate.


---

### message
- message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message to include in the email of the person receiving
      the gift certificate.



---

### orderNo
- orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order number


---

### recipientEmail
- recipientEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the person receiving
      the gift certificate.



---

### recipientName
- recipientName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person receiving
      the gift certificate.



---

### senderName
- senderName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person or organization that
      sent the gift certificate or null if undefined.



---

### status
- status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status where the possible values are
      STATUS\_PENDING, STATUS\_ISSUED, STATUS\_PARTIALLY\_REDEEMED
      or STATUS\_REDEEMED.



---

## Method Details

### getAmount()
- getAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the original amount on the gift certificate.

    **Returns:**
    - the original amount on the gift certificate.


---

### getBalance()
- getBalance(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the balance on the gift certificate.

    **Returns:**
    - the balance on the gift certificate.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description string.

    **Returns:**
    - the description.


---

### getGiftCertificateCode()
- getGiftCertificateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the code of the gift certificate. This redemption code is send to
      gift certificate recipient.


    **Returns:**
    - the code of the gift certificate.


---

### getID()
- ~~getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the code of the gift certificate. This redemption code is send to
      gift certificate recipient.


    **Returns:**
    - the code of the gift certificate.

    **Deprecated:**
**warning:** Use [getGiftCertificateCode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#getgiftcertificatecode)

---

### getMaskedGiftCertificateCode()
- getMaskedGiftCertificateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the masked gift certificate code with
      all but the last 4 characters replaced with a '\*' character.


    **Returns:**
    - the masked gift certificate code.


---

### getMaskedGiftCertificateCode(Number)
- getMaskedGiftCertificateCode(ignore: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the masked gift certificate code with
      all but the specified number of characters replaced with a '\*' character.


    **Parameters:**
    - ignore - the number of characters to leave unmasked.

    **Returns:**
    - the masked gift certificate code.

    **Throws:**
    - IllegalArgumentException - if ignore is negative.


---

### getMerchantID()
- getMerchantID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the merchant ID of the gift certificate.

    **Returns:**
    - the merchant ID of the gift certificate.


---

### getMessage()
- getMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message to include in the email of the person receiving
      the gift certificate.


    **Returns:**
    - the message to include in the email of the person receiving
      the gift certificate.



---

### getOrderNo()
- getOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order number

    **Returns:**
    - the order number


---

### getRecipientEmail()
- getRecipientEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the person receiving
      the gift certificate.


    **Returns:**
    - the email address of the person receiving
      the gift certificate.



---

### getRecipientName()
- getRecipientName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person receiving
      the gift certificate.


    **Returns:**
    - the name of the person receiving
      the gift certificate.



---

### getSenderName()
- getSenderName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person or organization that
      sent the gift certificate or null if undefined.


    **Returns:**
    - the name of the person or organization that
      sent the gift certificate or null if undefined.



---

### getStatus()
- getStatus(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status where the possible values are
      STATUS\_PENDING, STATUS\_ISSUED, STATUS\_PARTIALLY\_REDEEMED
      or STATUS\_REDEEMED.


    **Returns:**
    - the status.


---

### isEnabled()
- isEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the Gift Certificate is enabled, false otherwise.

    **Returns:**
    - true if the Gift Certificate is enabled, false otherwise.


---

### setDescription(String)
- setDescription(description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : An optional description that you can use to categorize the
      gift certificate.


    **Parameters:**
    - description - additional description.


---

### setEnabled(Boolean)
- setEnabled(enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Controls if the Gift Certificate is enabled.

    **Parameters:**
    - enabled - if true, enables the Gift Certificate.


---

### setMessage(String)
- setMessage(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the message to include in the email of the person receiving
      the gift certificate.


    **Parameters:**
    - message - the message to include in the email of the person receiving  the gift certificate.


---

### setOrderNo(String)
- setOrderNo(orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the order number

    **Parameters:**
    - orderNo - the order number to be set


---

### setRecipientEmail(String)
- setRecipientEmail(recipientEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the email address of the person receiving
      the gift certificate.


    **Parameters:**
    - recipientEmail - the email address of the person receiving  the gift certificate.


---

### setRecipientName(String)
- setRecipientName(recipient: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the person receiving
      the gift certificate.


    **Parameters:**
    - recipient - the name of the person receiving  the gift certificate.


---

### setSenderName(String)
- setSenderName(sender: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the person or organization that
      sent the gift certificate.


    **Parameters:**
    - sender - the name of the person or organization that  sent the gift certificate.


---

### setStatus(Number)
- setStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the status of the gift certificate. 
      
      Possible values are: [STATUS_ISSUED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#status_issued),
      [STATUS_PENDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#status_pending), [STATUS_PARTIALLY_REDEEMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#status_partially_redeemed)
      and [STATUS_REDEEMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md#status_redeemed).


    **Parameters:**
    - status - Gift certificate status


---

<!-- prettier-ignore-end -->

<!-- document id=085b43873c1ed8197cec86760e2f4553c6845140591c0580c8e9c7e37f9742d7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.GiftCertificateLineItem.md -->

<!-- prettier-ignore-start -->
# Class GiftCertificateLineItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
        - [dw.order.GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md)

Represents a Gift Certificate line item in the cart. When an order is
processed, a Gift Certificate is created based on the information in
the Gift Certificate line item.



## Property Summary

| Property | Description |
| --- | --- |
| [giftCertificateID](#giftcertificateid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the ID of the gift certificate that this line item  was used to create. |
| [message](#message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the message to include in the email of the person receiving  the gift certificate line item. |
| [productListItem](#productlistitem): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md) | Returns the associated ProductListItem. |
| [recipientEmail](#recipientemail): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the email address of the person receiving  the gift certificate line item. |
| [recipientName](#recipientname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the person receiving the gift certificate line item. |
| [senderName](#sendername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the person or organization that  sent the gift certificate line item or null if undefined. |
| [shipment](#shipment): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md) | Returns the associated Shipment. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#getgiftcertificateid)() | Returns the ID of the gift certificate that this line item  was used to create. |
| [getMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#getmessage)() | Returns the message to include in the email of the person receiving  the gift certificate line item. |
| [getProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#getproductlistitem)() | Returns the associated ProductListItem. |
| [getRecipientEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#getrecipientemail)() | Returns the email address of the person receiving  the gift certificate line item. |
| [getRecipientName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#getrecipientname)() | Returns the name of the person receiving the gift certificate line item. |
| [getSenderName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#getsendername)() | Returns the name of the person or organization that  sent the gift certificate line item or null if undefined. |
| [getShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#getshipment)() | Returns the associated Shipment. |
| [setGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#setgiftcertificateidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the ID of the gift certificate associated with this line item. |
| [setMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#setmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the message to include in the email of the person receiving  the gift certificate line item. |
| [setProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#setproductlistitemproductlistitem)([ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)) | Sets the associated ProductListItem. |
| [setRecipientEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#setrecipientemailstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the email address of the person receiving  the gift certificate line item. |
| [setRecipientName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#setrecipientnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the person receiving the gift certificate line item. |
| [setSenderName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#setsendernamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the person or organization that  sent the gift certificate line item. |
| [setShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md#setshipmentshipment)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Associates the gift certificate line item with the specified shipment. |

### Methods inherited from class LineItem

[getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getbaseprice), [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getgrossprice), [getLineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemctnr), [getLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemtext), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getnetprice), [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice), [getPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getpricevalue), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxbasis), [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxclassid), [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxrate), [getTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes), [setBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setbasepricemoney), [setGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setgrosspricemoney), [setLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setlineitemtextstring), [setNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setnetpricemoney), [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setpricevaluenumber), [setTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxmoney), [setTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxclassidstring), [setTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxratenumber), [setTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection), [updatePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber-money), [updateTaxAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxamountmoney)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### giftCertificateID
- giftCertificateID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the gift certificate that this line item
      was used to create. If this line item has not been used to create
      a Gift Certificate, this method returns null.



---

### message
- message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message to include in the email of the person receiving
      the gift certificate line item.



---

### productListItem
- productListItem: [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Returns the associated ProductListItem.


---

### recipientEmail
- recipientEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the person receiving
      the gift certificate line item.



---

### recipientName
- recipientName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person receiving the gift certificate line item.


---

### senderName
- senderName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person or organization that
      sent the gift certificate line item or null if undefined.



---

### shipment
- shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Returns the associated Shipment.


---

## Method Details

### getGiftCertificateID()
- getGiftCertificateID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the gift certificate that this line item
      was used to create. If this line item has not been used to create
      a Gift Certificate, this method returns null.


    **Returns:**
    - the ID of the gift certificate or null if undefined.


---

### getMessage()
- getMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message to include in the email of the person receiving
      the gift certificate line item.


    **Returns:**
    - the message to include in the email of the person receiving
      the gift certificate line item.



---

### getProductListItem()
- getProductListItem(): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Returns the associated ProductListItem.

    **Returns:**
    - item or null.


---

### getRecipientEmail()
- getRecipientEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the person receiving
      the gift certificate line item.


    **Returns:**
    - the email address of the person receiving
      the gift certificate line item.



---

### getRecipientName()
- getRecipientName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person receiving the gift certificate line item.

    **Returns:**
    - the name of the person receiving the gift certificate line item.


---

### getSenderName()
- getSenderName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the person or organization that
      sent the gift certificate line item or null if undefined.


    **Returns:**
    - the name of the person or organization that
      sent the gift certificate line item or null if undefined.



---

### getShipment()
- getShipment(): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Returns the associated Shipment.

    **Returns:**
    - The shipment of the gift certificate line item


---

### setGiftCertificateID(String)
- setGiftCertificateID(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the ID of the gift certificate associated with this line item.

    **Parameters:**
    - id - the ID of the gift certificate associated with this line item.


---

### setMessage(String)
- setMessage(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the message to include in the email of the person receiving
      the gift certificate line item.


    **Parameters:**
    - message - the message to include in the email of the person receiving  the gift certificate line item.


---

### setProductListItem(ProductListItem)
- setProductListItem(productListItem: [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)): void
  - : Sets the associated ProductListItem.
      
      
      The product list item to be set must be of type gift certificate otherwise an exception is thrown.


    **Parameters:**
    - productListItem - the product list item to be associated


---

### setRecipientEmail(String)
- setRecipientEmail(recipientEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the email address of the person receiving
      the gift certificate line item.


    **Parameters:**
    - recipientEmail - the email address of the person receiving  the gift certificate line item.


---

### setRecipientName(String)
- setRecipientName(recipient: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the person receiving the gift certificate line item.

    **Parameters:**
    - recipient - the name of the person receiving the gift certificate line item.


---

### setSenderName(String)
- setSenderName(sender: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the person or organization that
      sent the gift certificate line item.


    **Parameters:**
    - sender - the name of the person or organization that  sent the gift certificate line item.


---

### setShipment(Shipment)
- setShipment(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): void
  - : Associates the gift certificate line item with the specified shipment. 
      
       Gift certificate line item and shipment must belong to the same line item ctnr.


    **Parameters:**
    - shipment - The new shipment of the gift certificate line item


---

<!-- prettier-ignore-end -->

<!-- document id=98b5b3458361d6eb45b9a12f6fe6d0e8501eafb7ce1f705d9fe5d20bbeaf5bdb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.GiftCertificateMgr.md -->

<!-- prettier-ignore-start -->
# Class GiftCertificateMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.GiftCertificateMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md)

The GiftCertificateMgr class contains a set of static methods for
interacting with GiftCertificates.



## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[GC_ERROR_DISABLED](#gc_error_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-100"~~ | Indicates that an error occurred because the Gift Certificate  is currently disabled. |
| ~~[GC_ERROR_INSUFFICIENT_BALANCE](#gc_error_insufficient_balance): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-110"~~ | Indicates that an error occurred because the Gift Certificate  does not have a sufficient balance to perform the requested  operation. |
| ~~[GC_ERROR_INVALID_AMOUNT](#gc_error_invalid_amount): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-140"~~ | Indicates that an error occurred because the Gift Certificate  Amount was not valid. |
| ~~[GC_ERROR_INVALID_CODE](#gc_error_invalid_code): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-150"~~ | Indicates that an error occurred because the Gift Certificate  ID was not valid. |
| ~~[GC_ERROR_PENDING](#gc_error_pending): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-130"~~ | Indicates that an error occurred because the Gift Certificate  has been fully redeemed. |
| ~~[GC_ERROR_REDEEMED](#gc_error_redeemed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-120"~~ | Indicates that an error occurred because the Gift Certificate  has been fully redeemed. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [createGiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md#creategiftcertificatenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a Gift Certificate. |
| static [createGiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md#creategiftcertificatenumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a Gift Certificate. |
| ~~static [getGiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md#getgiftcertificatestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns the Gift Certificate identified by the specified  gift certificate code. |
| static [getGiftCertificateByCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md#getgiftcertificatebycodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the Gift Certificate identified by the specified  gift certificate code. |
| static [getGiftCertificateByMerchantID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md#getgiftcertificatebymerchantidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the Gift Certificate identified by the specified merchant ID. |
| static [redeemGiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md#redeemgiftcertificateorderpaymentinstrument)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)) | Redeems an amount from a Gift Certificate. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### GC_ERROR_DISABLED

- ~~GC_ERROR_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-100"~~
  - : Indicates that an error occurred because the Gift Certificate
      is currently disabled.


    **Deprecated:**
**warning:** Use [GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md) instead.

---

### GC_ERROR_INSUFFICIENT_BALANCE

- ~~GC_ERROR_INSUFFICIENT_BALANCE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-110"~~
  - : Indicates that an error occurred because the Gift Certificate
      does not have a sufficient balance to perform the requested
      operation.


    **Deprecated:**
**warning:** Use [GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md) instead.

---

### GC_ERROR_INVALID_AMOUNT

- ~~GC_ERROR_INVALID_AMOUNT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-140"~~
  - : Indicates that an error occurred because the Gift Certificate
      Amount was not valid.


    **Deprecated:**
**warning:** Use [GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md) instead.

---

### GC_ERROR_INVALID_CODE

- ~~GC_ERROR_INVALID_CODE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-150"~~
  - : Indicates that an error occurred because the Gift Certificate
      ID was not valid.


    **Deprecated:**
**warning:** Use [GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md) instead.

---

### GC_ERROR_PENDING

- ~~GC_ERROR_PENDING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-130"~~
  - : Indicates that an error occurred because the Gift Certificate
      has been fully redeemed.


    **Deprecated:**
**warning:** Use [GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md) instead.

---

### GC_ERROR_REDEEMED

- ~~GC_ERROR_REDEEMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE-120"~~
  - : Indicates that an error occurred because the Gift Certificate
      has been fully redeemed.


    **Deprecated:**
**warning:** Use   [GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md) instead.

---

## Method Details

### createGiftCertificate(Number)
- static createGiftCertificate(amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md)
  - : Creates a Gift Certificate. The system will assign a code to the new Gift Certificate.

    **Parameters:**
    - amount - the amount of the gift certificate. Must not be negative or zero.

    **Returns:**
    - the newly created Gift Certificate.


---

### createGiftCertificate(Number, String)
- static createGiftCertificate(amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md)
  - : Creates a Gift Certificate. If a non-empty Gift Certificate code is specified, the code will be used to create
      the Gift Certificate. Be aware that this code must be unique for the current site. If it is not unique, the Gift
      Certificate will not be created.


    **Parameters:**
    - amount - the amount of the gift certificate. Must not be negative or zero.
    - code - the code for the new gift certificate. If parameter is null or empty , the system will assign a code             to the new gift certificate.

    **Returns:**
    - the newly created Gift Certificate.


---

### getGiftCertificate(String)
- ~~static getGiftCertificate(giftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md)~~
  - : Returns the Gift Certificate identified by the specified
      gift certificate code.


    **Parameters:**
    - giftCertificateCode - to identify the Gift Certificate.

    **Returns:**
    - the Gift Certificate identified by the specified code or null.

    **Deprecated:**
**warning:** Use [getGiftCertificateByCode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md#getgiftcertificatebycodestring)

---

### getGiftCertificateByCode(String)
- static getGiftCertificateByCode(giftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md)
  - : Returns the Gift Certificate identified by the specified
      gift certificate code.


    **Parameters:**
    - giftCertificateCode - to identify the Gift Certificate.

    **Returns:**
    - the Gift Certificate identified by the specified code or null.


---

### getGiftCertificateByMerchantID(String)
- static getGiftCertificateByMerchantID(merchantID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md)
  - : Returns the Gift Certificate identified by the specified merchant ID.

    **Parameters:**
    - merchantID - to identify the Gift Certificate.

    **Returns:**
    - the Gift Certificate identified by the specified merchant ID or
      null.



---

### redeemGiftCertificate(OrderPaymentInstrument)
- static redeemGiftCertificate(paymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Redeems an amount from a Gift Certificate. The Gift Certificate ID
      is specified in the OrderPaymentInstrument and the amount
      specified in the PaymentTransaction associated with the
      OrderPaymentInstrument. If the PaymentTransaction.getTransactionID()
      is not null, the value returned by this method is used as the
      'Order Number' for the redemption transaction. The 'Order Number' is
      visible via the Business Manager.


    **Parameters:**
    - paymentInstrument - the OrderPaymentInstrument containing the ID of  the Gift Certificate to redeem, and the amount of the redemption.

    **Returns:**
    - the status of the redemption operation.


---

<!-- prettier-ignore-end -->

<!-- document id=c9cf85ef8bf138b56ec14ee02fa1775d84ca1eedb6b4d28239ec26d952fb391b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.GiftCertificateStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class GiftCertificateStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md)

Helper class containing status codes for the various errors that can occur
when redeeming a gift certificate. One of these codes is returned as part of
a Status object when a unsuccessful call to the
`RedeemGiftCertificate` pipelet is made.



## Constant Summary

| Constant | Description |
| --- | --- |
| [GIFTCERTIFICATE_CURRENCY_MISMATCH](#giftcertificate_currency_mismatch): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_CURRENCY_MISMATCH" | Indicates that an error occurred because the Gift Certificate  was in a different currency than the Basket. |
| [GIFTCERTIFICATE_DISABLED](#giftcertificate_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_DISABLED" | Indicates that an error occurred because the Gift Certificate  is currently disabled. |
| [GIFTCERTIFICATE_INSUFFICIENT_BALANCE](#giftcertificate_insufficient_balance): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_INSUFFICIENT_BALANCE" | Indicates that an error occurred because the Gift Certificate  does not have a sufficient balance to perform the requested  operation. |
| [GIFTCERTIFICATE_NOT_FOUND](#giftcertificate_not_found): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_NOT_FOUND" | Indicates that an error occurred because the Gift Certificate  was not found. |
| [GIFTCERTIFICATE_PENDING](#giftcertificate_pending): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_PENDING" | Indicates that an error occurred because the Gift Certificate  is pending and is not available for use. |
| [GIFTCERTIFICATE_REDEEMED](#giftcertificate_redeemed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_REDEEMED" | Indicates that an error occurred because the Gift Certificate  has been fully redeemed. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [GiftCertificateStatusCodes](#giftcertificatestatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### GIFTCERTIFICATE_CURRENCY_MISMATCH

- GIFTCERTIFICATE_CURRENCY_MISMATCH: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_CURRENCY_MISMATCH"
  - : Indicates that an error occurred because the Gift Certificate
      was in a different currency than the Basket.



---

### GIFTCERTIFICATE_DISABLED

- GIFTCERTIFICATE_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_DISABLED"
  - : Indicates that an error occurred because the Gift Certificate
      is currently disabled.



---

### GIFTCERTIFICATE_INSUFFICIENT_BALANCE

- GIFTCERTIFICATE_INSUFFICIENT_BALANCE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_INSUFFICIENT_BALANCE"
  - : Indicates that an error occurred because the Gift Certificate
      does not have a sufficient balance to perform the requested
      operation.



---

### GIFTCERTIFICATE_NOT_FOUND

- GIFTCERTIFICATE_NOT_FOUND: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_NOT_FOUND"
  - : Indicates that an error occurred because the Gift Certificate
      was not found.



---

### GIFTCERTIFICATE_PENDING

- GIFTCERTIFICATE_PENDING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_PENDING"
  - : Indicates that an error occurred because the Gift Certificate
      is pending and is not available for use.



---

### GIFTCERTIFICATE_REDEEMED

- GIFTCERTIFICATE_REDEEMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFTCERTIFICATE_REDEEMED"
  - : Indicates that an error occurred because the Gift Certificate
      has been fully redeemed.



---

## Constructor Details

### GiftCertificateStatusCodes()
- GiftCertificateStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=91d1f4cb0902ecb228ca1ffee996d2dce7cdf5f7be59905210766a3b9c091576 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.global.md -->

<!-- prettier-ignore-start -->
# Class global

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.global](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md)

The global object is a pre-defined object that serves as a placeholder for the global
properties and functions of JavaScript. All other predefined objects, functions, and
properties are accessible through the global object.



## Constant Summary

| Constant | Description |
| --- | --- |
| [Infinity](#infinity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | representation for Infinity as an Integer |
| [NaN](#nan): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | representation for Not a Number as an Integer |
| [PIPELET_ERROR](#pipelet_error): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | represents an error during pipelet execution |
| [PIPELET_NEXT](#pipelet_next): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | represents the next pipelet to fire |
| [slotcontent](#slotcontent): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Provides access to the SlotContent object. |
| [undefined](#undefined): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | representation for undefined |
| [webreferences2](#webreferences2): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Provides access to WSDL definition files in a Cartridge's webreferences2  folder. |

## Property Summary

| Property | Description |
| --- | --- |
| [customer](#customer): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) | The current customer or null if this request is not associated with any customer. |
| [exports](#exports): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | References the [module.exports](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md#exports) property of the current module. |
| [globalThis](#globalthis): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Provides access to the global scope object containing all built-in functions and classes. |
| [module](#module): [Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md) | An object representing the current module. |
| [request](#request): [Request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md) | The current request. |
| [response](#response): [Response](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md) | The current response. |
| [session](#session): [Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md) | The current session. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [decodeURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#decodeuristring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Unescapes characters in a URI component. |
| static [decodeURIComponent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#decodeuricomponentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Unescapes characters in a URI component. |
| static [empty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#emptyobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method tests, whether the given object is empty. |
| static [encodeURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#encodeuristring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Escapes characters in a URI. |
| static [encodeURIComponent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#encodeuricomponentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Escapes characters in a URI component. |
| static [escape](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#escapestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Encodes a String. |
| ~~static [eval](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#evalstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Execute JavaScript code from a String. |
| static [importClass](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#importclassobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Import the specified class and make it  available at the top level. |
| static [importPackage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#importpackageobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Import all the classes in the specified package  available at the top level. |
| static [importScript](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#importscriptstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Imports all functions from the specified script. |
| static [isFinite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#isfinitenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns true if the specified Number is finite. |
| static [isNaN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#isnanobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Test the specified value to determine if it  is not a Number. |
| static [isXMLName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#isxmlnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Determines whether the specified string is a valid name for an  XML element or attribute. |
| static [parseFloat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#parsefloatstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parses a String into an float Number. |
| static [parseInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#parseintstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Parses a String into an integer Number using the  specified radix. |
| static [parseInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#parseintstring---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parses a String into an integer Number.  This function is a short form for the call to [parseInt(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#parseintstring-number) with automatic determination of the radix. |
| static [parseInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#parseintstring---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parses a String into an integer Number. |
| static [require](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#requirestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The require() function supports loading of modules in JavaScript. |
| static [trace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#tracestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Formats and prints the message using the specified params and returns  the formatted message. |
| static [unescape](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#unescapestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Decode an escaped String. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### Infinity

- Infinity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : representation for Infinity as an Integer


---

### NaN

- NaN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : representation for Not a Number as an Integer


---

### PIPELET_ERROR

- PIPELET_ERROR: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : represents an error during pipelet execution


---

### PIPELET_NEXT

- PIPELET_NEXT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : represents the next pipelet to fire


---

### slotcontent

- slotcontent: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Provides access to the SlotContent object.  Available only in ISML
      templates that are defined as the Slot's template.  For example,
      <isprint value="${slotcontent.callout}"> will print out the callout message
      of the active Slot.


    **See Also:**
    - [SlotContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md)


---

### undefined

- undefined: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : representation for undefined


---

### webreferences2

- webreferences2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Provides access to WSDL definition files in a Cartridge's webreferences2
      folder. For example, webreferences2.mywebservice loads the
      mywebservice.wsdl file and returns an instance of dw.ws.WebReference2.
      The WebReference2 instance enables you to access the actual web service
      via the WebReference2.getDefaultService() method.


    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)


---

## Property Details

### customer
- customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : The current customer or null if this request is not associated with any customer.


---

### exports
- exports: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : References the [module.exports](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md#exports) property of the current module. Available only in scripts that were loaded
      as CommonJS module using the [require(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#requirestring) function.


    **See Also:**
    - [Module.exports](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md#exports)


---

### globalThis
- globalThis: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Provides access to the global scope object containing all built-in functions and classes.


---

### module
- module: [Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md)
  - : An object representing the current module. Available only in scripts that were loaded
      as CommonJS module using the [require(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#requirestring) function.


    **See Also:**
    - [Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md)


---

### request
- request: [Request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md)
  - : The current request.


---

### response
- response: [Response](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md)
  - : The current response.


---

### session
- session: [Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md)
  - : The current session.


---

## Method Details

### decodeURI(String)
- static decodeURI(uri: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Unescapes characters in a URI component.

    **Parameters:**
    - uri - a string that contains an encoded URI or other text to be decoded.

    **Returns:**
    - A copy of _uri_ with any hexadecimal escape sequences replaced with the
      characters they represent



---

### decodeURIComponent(String)
- static decodeURIComponent(uriComponent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Unescapes characters in a URI component.

    **Parameters:**
    - uriComponent - a string that contains an encoded URI component or other text to be decoded.

    **Returns:**
    - A copy of _uriComponent_ with any hexadecimal escape sequences replaced with the
      characters they represent



---

### empty(Object)
- static empty(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method tests, whether the given object is empty. The interpretation
      of empty is the following.
      - null is always empty
      - undefined is always empty
      - a string with zero length is empty
      - an array with no elements is empty
      - a collection with no elements is empty


    **Parameters:**
    - obj - the object to be thested

    **Returns:**
    - true if the object is interpreted as being empty


---

### encodeURI(String)
- static encodeURI(uri: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Escapes characters in a URI.

    **Parameters:**
    - uri - a String that contains the URI or other text to be encoded.

    **Returns:**
    - a copy of _uri_ with certain characters replaced by
      hexadecimal escape sequences.



---

### encodeURIComponent(String)
- static encodeURIComponent(uriComponent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Escapes characters in a URI component.

    **Parameters:**
    - uriComponent - a String that contains a portion of a URI or other text to be encoded.

    **Returns:**
    - a copy of _uriComponent_ with certain characters replaced by
      hexadecimal escape sequences.



---

### escape(String)
- static escape(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encodes a String.

    **Parameters:**
    - s - the String to be encoded.

    **Returns:**
    - a copy of _s_ where characters have been replace by
      hexadecimal escape sequences.



---

### eval(String)
- ~~static eval(code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)~~
  - : Execute JavaScript code from a String.

    **Parameters:**
    - code - a String that contains the JavaScript expression to be  evaluated or the statements to be executed.

    **Returns:**
    - the value of the executed call or null.

    **Deprecated:**
**warning:** The eval() function is deprecated, because it's potential security risk for server side code injection.

---

### importClass(Object)
- static importClass(classPath: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Import the specified class and make it
      available at the top level. It's equivalent in effect to the
      Java import declaration.


    **Parameters:**
    - classPath - the fully qualified class path.


---

### importPackage(Object)
- static importPackage(packagePath: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Import all the classes in the specified package
      available at the top level. It's equivalent in effect to the
      Java import declaration.


    **Parameters:**
    - packagePath - the fully qualified package path.


---

### importScript(String)
- static importScript(scriptPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Imports all functions from the specified script. Variables are not imported
      from the script and must be accessed through helper functions.
      
      The script path has the following syntax: \[cartridgename:\]scriptname, where
      cartridgename identifies a cartridge where the script file is located. If
      cartridgename is omitted the script file is loaded from the same cartridge
      in which the importing component is located.
      
      Examples:
      importScript( 'example.ds' ) imports the script file example.ds from the same cartridge
      importScript( 'abc:example.ds' ) imports the script file example.ds from the cartridge 'abc'


    **Parameters:**
    - scriptPath - the path to the script.


---

### isFinite(Number)
- static isFinite(number: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the specified Number is finite.

    **Parameters:**
    - number - the Number to test.

    **Returns:**
    - true if the specified Number is finite,
      false otherwise.



---

### isNaN(Object)
- static isNaN(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Test the specified value to determine if it
      is not a Number.


    **Parameters:**
    - object - the Object to be tested as a number

    **Returns:**
    - True if the object is not a number


---

### isXMLName(String)
- static isXMLName(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether the specified string is a valid name for an
      XML element or attribute.


    **Parameters:**
    - name - the String specified

    **Returns:**
    - True if the string is a valid name


---

### parseFloat(String)
- static parseFloat(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Parses a String into an float Number.

    **Parameters:**
    - s - the String to parse.

    **Returns:**
    - Returns the float as a Number.


---

### parseInt(String, Number)
- static parseInt(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), radix: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Parses a String into an integer Number using the
      specified radix.


    **Parameters:**
    - s - the String to parse.
    - radix - the radix to use.

    **Returns:**
    - Returns the integer as a Number.


---

### parseInt(String) - Variant 1
- static parseInt(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Parses a String into an integer Number.
      
      This function is a short form for the call to [parseInt(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#parseintstring-number) with automatic determination of the radix.
      If the string starts with "0x" or "0X" then the radix is 16. If the string starts with "0" the the radix is 8. In all other cases the radix is 10.


    **Parameters:**
    - s - the String to parse.

    **Returns:**
    - Returns the integer as a Number.

    **API Version:**
**note:** No longer available as of version 16.1.

---

### parseInt(String) - Variant 2
- static parseInt(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Parses a String into an integer Number.
      This function is a short form for the call to [parseInt(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#parseintstring-number) with automatic determination of the radix.
      If the string starts with "0x" or "0X" then the radix is 16. In all other cases the radix is 10.


    **Parameters:**
    - s - the String to parse.

    **Returns:**
    - Returns the integer as a Number.

    **API Version:**
**note:** Available from version 16.1.
ECMAScript 5 compliance: removed support for octal numbers.

---

### require(String)
- static require(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md)
  - : The require() function supports loading of modules in JavaScript. The function works similar to the require() function
      in CommonJS. The general module loading works the same way, but the exact path lookup is slightly different
      and better fits into Demandware concepts. Here are the details for the lookup:
      
      - If the module name starts with "./" or "../" then load it relative to the current module. The module can be a file or a directory. A file  extension is acknowledged, but not required. If it's a directory a 'package.json' or a 'main' file is expected.  If the 'package.json' does not contain a main entry, then default to main file in the directory.  Access to parent files can't go beyond the cartridges directory. Access to other cartridges is explicitly allowed.
      - If the module name starts with "~/" it's a path relative to the current cartridge.
      - If the module name starts with "&#42;/" try to find the module in all cartridges that are assigned to the current site.
      - A module with the name "dw" or which starts with "dw/" references Demandware built-in functions and classes.  For example `var u = require( 'dw/util' );`loads the classes in the util package, which can be then used like  `var h = new u.HashMap();`
      - A module, which doesn't start with "./" or "../" is resolved as top level module.  
        - The module name is used to find a folder in the top cartridge directory, typically a cartridge itself, but it can also be a simple folder.
        - If nothing is found, the module name is used to look into a special folder called "modules" in the top cartridge directory. That folder    can be used by a developer to manage different modules. For example a developer could drop a module like "less.js" just into that folder.
      
      If the require function is used to reference a file then an optional file extension is used to determine the content of the file. Currently
      supported are the extensions ordered by priority:
      
        - js - JavaScript file
        - ds - Demandware Script file
        - json - JSON file


    **Parameters:**
    - path - the path to the JavaScript module.

    **Returns:**
    - an object with the exported functions and properties.


---

### trace(String, Object...)
- static trace(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), params: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Formats and prints the message using the specified params and returns
      the formatted message. The format message is a Java MessageFormat
      expression. Printing happens in the script log output.


    **Parameters:**
    - msg - the message to format.
    - params - one, or multiple parameters that are used  to format the message.


---

### unescape(String)
- static unescape(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decode an escaped String.

    **Parameters:**
    - string - the String to decode.

    **Returns:**
    - a copy of the String where hexadecimal character sequences
      are replace by Unicode characters.



---

<!-- prettier-ignore-end -->

<!-- document id=4051e300427adb9b16b647fff6952d75b7bd49458f332b33ac9bb7a2e94f8b41 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.HashMap.md -->

<!-- prettier-ignore-start -->
# Class HashMap

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
    - [dw.util.HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)

Represents a hash map of objects.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [HashMap](#hashmap)() | Constructs a new HashMap. |

## Method Summary

| Method | Description |
| --- | --- |
| [clone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md#clone)() | Returns a shallow copy of this map. |

### Methods inherited from class Map

[clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#clear), [containsKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containskeyobject), [containsValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containsvalueobject), [entrySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#entryset), [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getobject), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#isempty), [keySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#keyset), [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putobject-object), [putAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putallmap), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#removeobject), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#size), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-1), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-2)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### HashMap()
- HashMap()
  - : Constructs a new HashMap.


---

## Method Details

### clone()
- clone(): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)
  - : Returns a shallow copy of this map.

    **Returns:**
    - a shallow copy of this map.


---

<!-- prettier-ignore-end -->

<!-- document id=4ac5275d429a890c776769c7738387faefd75bdd1ab01aed93f53bbbefe747de url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.HashSet.md -->

<!-- prettier-ignore-start -->
# Class HashSet

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
    - [dw.util.Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
      - [dw.util.HashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashSet.md)

Represents a HashSet


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [HashSet](#hashset)() | Constructs a new HashMap. |
| [HashSet](#hashsetcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Construct a new HashSet by  initializing the HashSet with the elements of the  given collection. |

## Method Summary

| Method | Description |
| --- | --- |
| [clone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashSet.md#clone)() | Returns a shallow copy of this set. |

### Methods inherited from class Collection

[add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject), [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object), [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection), [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear), [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject), [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty), [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject), [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection), [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### HashSet()
- HashSet()
  - : Constructs a new HashMap.


---

### HashSet(Collection)
- HashSet(collection: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))
  - : Construct a new HashSet by
      initializing the HashSet with the elements of the
      given collection.


    **Parameters:**
    - collection - the collection to add to the set.


---

## Method Details

### clone()
- clone(): [HashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashSet.md)
  - : Returns a shallow copy of this set.

    **Returns:**
    - a shallow copy of this set.


---

<!-- prettier-ignore-end -->

<!-- document id=60b8601ec994848d2686e942e41a7f1313839c1266869696a156aab41c09772b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.HookMgr.md -->

<!-- prettier-ignore-start -->
# Class HookMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.HookMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.HookMgr.md)

This class provides functionality to call hooks. A hook is an extension point in the business logic,
where you can register scripts to customize functionality.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [callHook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.HookMgr.md#callhookstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Calls a hook on base of the specified extensionPoint and function. |
| static [hasHook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.HookMgr.md#hashookstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Checks whether a hook is registered or a system default implementation exists for this extension point. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### callHook(String, String, Object...)
- static callHook(extensionPoint: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), function: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Calls a hook on base of the specified extensionPoint and function. If a hook throws an exception, then
      this method will also throw an exception. If no hook and no system default implementation is provided,
      then this method will return undefined.
      
      
      Sample:
      
      ```
      dw.system.HookMgr.callHook( "dw.order.calculate", "calculate", basket );
      ```


    **Parameters:**
    - extensionPoint - the extension point to call
    - function - the script function to call
    - args - the Array of function parameters

    **Returns:**
    - the object returned by the hook or undefined


---

### hasHook(String)
- static hasHook(extensionPoint: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks whether a hook is registered or a system default implementation exists for this extension point.
      
      _extensionPoint_ refers to the same name used to register a script as implementation. With this method it's only
      possible to check for a whole script registered but it is not possible to check, whether an individual function
      is implemented.
      
      
      
      Sample:
      
      ```
      dw.system.HookMgr.hasHook( "dw.order.calculate" );
      ```


    **Parameters:**
    - extensionPoint - the extension point

    **Returns:**
    - true, if a hook is registered or a default implementation exists, otherwise false


---

<!-- prettier-ignore-end -->

<!-- document id=30d531d6a427716b00f5f5cbe89ca020fc8b9055ff8333f235ee0d992a3e2ba2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.HTTPClient.md -->

<!-- prettier-ignore-start -->
# Class HTTPClient

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md)

The HTTPClient class supports the HTTP methods GET, POST, HEAD, PUT, PATCH, OPTIONS, and DELETE.
If a secure connection via HTTPS is
established the used server certificate or the signing CAs certificate needs to be imported into the customer key
store via Business Manager. **Note:** when this class is used with sensitive data, be careful in persisting
sensitive information.

Key selection for mutual TLS:

1. Check if there is an explicit identity requested [setIdentity(KeyRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#setidentitykeyref)
2. Else, Check if there is a mapping for hostname in the keystore
3. Deprecated: Select an arbitrary private key from the keystore




```

var httpClient = new HTTPClient();
var message;
httpClient.open('GET', 'http://www.myinstance.com/feed.xml');
httpClient.setTimeout(3000);
httpClient.send();
if (httpClient.statusCode == 200)
{
     message = httpClient.text;
}
else
{
    // error handling
    message = "An error occurred with status code "+httpClient.statusCode;
}
```



## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[DEFAULT_GET_FILE_SIZE](#default_get_file_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5242880~~ | The default size for `sendAndReceiveToFile()` returning a File is 5MB deprecated in favor of  MAX\_GET\_FILE\_SIZE |
| [MAX_GET_FILE_SIZE](#max_get_file_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200 | The maximum permitted size (in bytes) of an HTTP response when calling operations which write the response to  file. |
| [MAX_GET_MEM_SIZE](#max_get_mem_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760 | The maximum permitted size (in bytes) of an HTTP response when calling operations which store the response in  memory. |

## Property Summary

| Property | Description |
| --- | --- |
| ~~[allResponseHeaders](#allresponseheaders): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)~~ `(read-only)` | Returns all response headers as a map containing the name and value of the response header. |
| [allowRedirect](#allowredirect): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Determines whether redirect handling is enabled. |
| [bytes](#bytes): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md) `(read-only)` | Returns the bytes in the message body for HTTP status codes between 200 and 299. |
| [errorBytes](#errorbytes): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md) `(read-only)` | Returns the returned message body as bytes for HTTP status code greater or equal to 400. |
| [errorText](#errortext): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the returned message body as text for HTTP status code greater or equal to 400. |
| [hostNameVerification](#hostnameverification): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Determines whether host name verification is enabled. |
| [identity](#identity): [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md) | Gets the identity used for mutual TLS (mTLS). |
| [loggingConfig](#loggingconfig): [HTTPClientLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md) | Gets the logging configuration for this HTTP client. |
| [responseHeaders](#responseheaders): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns all response headers as a map in which each entry represents an individual header. |
| [statusCode](#statuscode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the status code of the last HTTP operation. |
| [statusMessage](#statusmessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the message text of the last HTTP operation. |
| [text](#text): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the returned message body as text for HTTP status codes between 200 and 299. |
| [timeout](#timeout): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the timeout for this client, in milliseconds. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [HTTPClient](#httpclient)() | Constructs the HTTPClient instance with the default configuration. |
| [HTTPClient](#httpclientobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs the HTTPClient instance with the given configuration. |

## Method Summary

| Method | Description |
| --- | --- |
| [enableCaching](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#enablecachingnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Calling this method enables caching for GET requests. |
| ~~[getAllResponseHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getallresponseheaders)()~~ | Returns all response headers as a map containing the name and value of the response header. |
| [getAllowRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getallowredirect)() | Determines whether redirect handling is enabled. |
| [getBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getbytes)() | Returns the bytes in the message body for HTTP status codes between 200 and 299. |
| [getErrorBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#geterrorbytes)() | Returns the returned message body as bytes for HTTP status code greater or equal to 400. |
| [getErrorText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#geterrortext)() | Returns the returned message body as text for HTTP status code greater or equal to 400. |
| [getHostNameVerification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#gethostnameverification)() | Determines whether host name verification is enabled. |
| [getIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getidentity)() | Gets the identity used for mutual TLS (mTLS). |
| [getLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getloggingconfig)() | Gets the logging configuration for this HTTP client. |
| [getResponseHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getresponseheaderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a specific response header from the last HTTP operation. |
| [getResponseHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getresponseheaders)() | Returns all response headers as a map in which each entry represents an individual header. |
| [getResponseHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getresponseheadersstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all the values of a response header from the last HTTP operation as a list of strings. |
| [getStatusCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getstatuscode)() | Returns the status code of the last HTTP operation. |
| [getStatusMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getstatusmessage)() | Returns the message text of the last HTTP operation. |
| [getText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#gettext)() | Returns the returned message body as text for HTTP status codes between 200 and 299. |
| [getText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#gettextstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the returned message body as text for HTTP status codes between 200 and 299. |
| [getTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#gettimeout)() | Returns the timeout for this client, in milliseconds. |
| [open](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#openstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Opens the specified URL using the specified method. |
| ~~[open](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#openstring-string-boolean-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Deprecated method. |
| [open](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#openstring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Opens the specified URL with the in parameter method specified Http method with given credentials \[user,  password\] using HTTP basic authentication. |
| [send](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#send)() | Sends an HTTP request. |
| [send](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | This method performs the actual HTTP communication. |
| [send](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method performs the actual HTTP communication. |
| [send](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method performs the actual HTTP communication. |
| [sendAndReceiveToFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendandreceivetofilefile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | This method performs the actual HTTP communication. |
| [sendAndReceiveToFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendandreceivetofilestring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | This method performs the actual HTTP communication. |
| [sendAndReceiveToFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendandreceivetofilestring-string-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | This method performs the actual HTTP communication. |
| [sendBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendbytesbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | This method performs the actual HTTP communication. |
| [sendBytesAndReceiveToFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendbytesandreceivetofilebytes-file)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | This method performs the actual HTTP communication. |
| [sendMultiPart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sendmultiparthttprequestpart)([HTTPRequestPart\[\]](dw.net.HTTPRequestPart.md)) | Sends a multipart HTTP request. |
| [setAllowRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#setallowredirectboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets whether automatic HTTP redirect handling is enabled. |
| [setHostNameVerification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#sethostnameverificationboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets whether certificate host name verification is enabled. |
| [setIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#setidentitykeyref)([KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)) | Sets the identity (private key) to use when mutual TLS (mTLS) is configured. |
| [setLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#setloggingconfighttpclientloggingconfig)([HTTPClientLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md)) | Sets the logging configuration for this HTTP client. |
| [setRequestHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#setrequestheaderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets a request header for the next HTTP operation. |
| [setTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#settimeoutnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the timeout for connections made with this client to the given number of milliseconds. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DEFAULT_GET_FILE_SIZE

- ~~DEFAULT_GET_FILE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5242880~~
  - : The default size for `sendAndReceiveToFile()` returning a File is 5MB deprecated in favor of
      MAX\_GET\_FILE\_SIZE


    **Deprecated:**
**warning:** Use [MAX_GET_FILE_SIZE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#max_get_file_size) instead.

---

### MAX_GET_FILE_SIZE

- MAX_GET_FILE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200
  - : The maximum permitted size (in bytes) of an HTTP response when calling operations which write the response to
      file. (200MB)



---

### MAX_GET_MEM_SIZE

- MAX_GET_MEM_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760
  - : The maximum permitted size (in bytes) of an HTTP response when calling operations which store the response in
      memory. (10MB)



---

## Property Details

### allResponseHeaders
- ~~allResponseHeaders: [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)~~ `(read-only)`
  - : Returns all response headers as a map containing the name and value of the response header.

    **Deprecated:**
**warning:** Use [getResponseHeaders()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getresponseheaders) instead.

---

### allowRedirect
- allowRedirect: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether redirect handling is enabled.


---

### bytes
- bytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md) `(read-only)`
  - : Returns the bytes in the message body for HTTP status codes between 200 and 299.


---

### errorBytes
- errorBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md) `(read-only)`
  - : Returns the returned message body as bytes for HTTP status code greater or equal to 400. Error messages are not
      written to the response file.



---

### errorText
- errorText: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the returned message body as text for HTTP status code greater or equal to 400. Error messages are not
      written to the response file.



---

### hostNameVerification
- hostNameVerification: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether host name verification is enabled.


---

### identity
- identity: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)
  - : Gets the identity used for mutual TLS (mTLS).


---

### loggingConfig
- loggingConfig: [HTTPClientLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md)
  - : Gets the logging configuration for this HTTP client.


---

### responseHeaders
- responseHeaders: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns all response headers as a map in which each entry represents an individual header. The key of the entry
      holds the header name and the entry value holds a list of all header values.



---

### statusCode
- statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the status code of the last HTTP operation.


---

### statusMessage
- statusMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the message text of the last HTTP operation.


---

### text
- text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the returned message body as text for HTTP status codes between 200 and 299.


---

### timeout
- timeout: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the timeout for this client, in milliseconds.


---

## Constructor Details

### HTTPClient()
- HTTPClient()
  - : Constructs the HTTPClient instance with the default configuration.


---

### HTTPClient(Object)
- HTTPClient(configMap: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructs the HTTPClient instance with the given configuration.
      
      
      There is one supported configuration option. Unknown options are ignored.
      | Name | Type | Description |
      | --- |--- |--- |
      | `allowHTTP2` | `boolean` | Allow connections over HTTP/2. This will still allow HTTP/1.1 if that is what the remote server          supports. It will also cause all request and response headers to be case-insensitive.          The default value is `false`. |
      
      
      
      
      Sample usage:
      
      ```
      var httpClient = new HTTPClient( { allowHTTP2: true } )
      ```


    **Parameters:**
    - configMap - A Map containing configuration options.


---

## Method Details

### enableCaching(Number)
- enableCaching(ttl: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Calling this method enables caching for GET requests.
      
      
      It basically means that a response is cached, and before making a request the HTTP client looks into the cache to
      determine whether the response is already available. Only responses with a status code of 2xx, with a content
      length, with a size less than 50k, and which are not intended to be immediately written to a file are cached.
      
      
      The provided parameter defines the TTL (time to live) for the cached content. A value of 0 disables caching. The
      URL and the username are used as cache keys. The total size of the cacheable content and the number of cached
      items is limited and automatically managed by the system. Cache control information send by the remote server is
      ignored. Caching HTTP responses should be done very carefully. It is important to ensure that the response really
      depends only on the URL and doesn't contain any remote state information or time information which is independent
      of the URL. It is also important to verify that the application sends exactly the same URL multiple times.


    **Parameters:**
    - ttl - the TTL for the cached content in secs


---

### getAllResponseHeaders()
- ~~getAllResponseHeaders(): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)~~
  - : Returns all response headers as a map containing the name and value of the response header.

    **Returns:**
    - a map containing the names and corresponding values of the response headers.

    **Deprecated:**
**warning:** Use [getResponseHeaders()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#getresponseheaders) instead.

---

### getAllowRedirect()
- getAllowRedirect(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether redirect handling is enabled.

    **Returns:**
    - true if redirect handling is enabled, false otherwise.


---

### getBytes()
- getBytes(): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Returns the bytes in the message body for HTTP status codes between 200 and 299.

    **Returns:**
    - the returned message body as bytes.


---

### getErrorBytes()
- getErrorBytes(): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Returns the returned message body as bytes for HTTP status code greater or equal to 400. Error messages are not
      written to the response file.


    **Returns:**
    - the returned message body as bytes.


---

### getErrorText()
- getErrorText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the returned message body as text for HTTP status code greater or equal to 400. Error messages are not
      written to the response file.


    **Returns:**
    - the returned message body as text.


---

### getHostNameVerification()
- getHostNameVerification(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether host name verification is enabled.

    **Returns:**
    - true if verification is enabled, false otherwise


---

### getIdentity()
- getIdentity(): [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)
  - : Gets the identity used for mutual TLS (mTLS).

    **Returns:**
    - Reference to the private key, or null if not configured


---

### getLoggingConfig()
- getLoggingConfig(): [HTTPClientLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md)
  - : Gets the logging configuration for this HTTP client.

    **Returns:**
    - the current logging configuration


---

### getResponseHeader(String)
- getResponseHeader(header: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a specific response header from the last HTTP operation. The method returns null if the specific header
      was not returned.


    **Parameters:**
    - header - the name of the response header to locate.

    **Returns:**
    - the value of the specified header or null if the header cannot be found.


---

### getResponseHeaders()
- getResponseHeaders(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns all response headers as a map in which each entry represents an individual header. The key of the entry
      holds the header name and the entry value holds a list of all header values.


    **Returns:**
    - A map containing the names and corresponding values of the response headers.


---

### getResponseHeaders(String)
- getResponseHeaders(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns all the values of a response header from the last HTTP operation as a list of strings. This reflects the
      fact that a specific header, e.g. `"Set-Cookie"`, may be set multiple times. In case there is no such
      header, the method returns an empty list.


    **Parameters:**
    - name - The name of the response header to locate.

    **Returns:**
    - The values of the specified header as a list of strings or an empty list if the header cannot be found.


---

### getStatusCode()
- getStatusCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status code of the last HTTP operation.

    **Returns:**
    - the status code of the last HTTP operation.


---

### getStatusMessage()
- getStatusMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message text of the last HTTP operation.

    **Returns:**
    - the message text of the last HTTP operation.


---

### getText()
- getText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the returned message body as text for HTTP status codes between 200 and 299.

    **Returns:**
    - the returned message body as text.


---

### getText(String)
- getText(encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the returned message body as text for HTTP status codes between 200 and 299.

    **Parameters:**
    - encoding - the character encoding to use.

    **Returns:**
    - String the encoded String.


---

### getTimeout()
- getTimeout(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the timeout for this client, in milliseconds.

    **Returns:**
    - the timeout in milliseconds


---

### open(String, String)
- open(method: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), url: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Opens the specified URL using the specified method. The following methods are supported: GET, POST, HEAD, PUT,
      PATCH, OPTIONS, and DELETE


    **Parameters:**
    - method - the method to use for opening the URL.
    - url - the url to open.


---

### open(String, String, Boolean, String, String)
- ~~open(method: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), url: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), async: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), user: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Deprecated method.

    **Parameters:**
    - method - the method to use for opening the URL.
    - url - the url to open.
    - async - true if asynchronous.
    - user - name of the user.
    - password - password.

    **Deprecated:**
**warning:** Use [open(String, String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#openstring-string-string-string) instead.

---

### open(String, String, String, String)
- open(method: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), url: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), user: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Opens the specified URL with the in parameter method specified Http method with given credentials \[user,
      password\] using HTTP basic authentication. The following methods are supported: GET, POST, HEAD, PUT,
      PATCH, OPTIONS, and DELETE


    **Parameters:**
    - method - HTTP method
    - url - the url
    - user - name of the user
    - password - password


---

### send()
- send(): void
  - : Sends an HTTP request.


---

### send(File)
- send(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): void
  - : This method performs the actual HTTP communication. Sends the file to the HTTP server. The file content is sent
      as a request body and is sent "as-is" (text or binary).


    **Parameters:**
    - file - File to be sent.


---

### send(String)
- send(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : This method performs the actual HTTP communication. The text is sent as a request body. If the text is null no
      data will be sent to the HTTP server.


    **Parameters:**
    - text - text String to be sent as request body.


---

### send(String, String)
- send(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : This method performs the actual HTTP communication. The text is sent as a request body. If the text is null no
      data will be sent to the HTTP server.


    **Parameters:**
    - text - text String to be sent as request body.
    - encoding - character encoding name.


---

### sendAndReceiveToFile(File)
- sendAndReceiveToFile(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method performs the actual HTTP communication. If the file is null no data will be sent to the HTTP server.
      If this method is used with a GET then the file parameter will contain the contents retrieved. When using this
      method with a PUT/POST then the contents of the file parameter will be sent to the server.


    **Parameters:**
    - file - local file used to read from or write to, depending on the method used.

    **Returns:**
    - true if the returned code was a positive status code


---

### sendAndReceiveToFile(String, File)
- sendAndReceiveToFile(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), outFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method performs the actual HTTP communication. If the text is null no data will be sent to the HTTP server.

    **Parameters:**
    - text - text String to be sent.
    - outFile - local file to write to.

    **Returns:**
    - true if the returned code was a positive status code


---

### sendAndReceiveToFile(String, String, File)
- sendAndReceiveToFile(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), outFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method performs the actual HTTP communication. If the text is null no data will be sent to the HTTP server.

    **Parameters:**
    - text - text String to be sent.
    - encoding - character encoding name.
    - outFile - local file to write to.

    **Returns:**
    - true if the returned code was a positive status code


---

### sendBytes(Bytes)
- sendBytes(body: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): void
  - : This method performs the actual HTTP communication. The bytes are sent as a request body. If the bytes are null no
      data will be sent to the HTTP server.


    **Parameters:**
    - body - Bytes to be sent as request body.


---

### sendBytesAndReceiveToFile(Bytes, File)
- sendBytesAndReceiveToFile(body: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), outFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method performs the actual HTTP communication. If the body is null no data will be sent to the HTTP server.

    **Parameters:**
    - body - Bytes to be sent.
    - outFile - local file to write to.

    **Returns:**
    - true if the returned code was a positive status code

    **Throws:**
    - IOException - 


---

### sendMultiPart(HTTPRequestPart[])
- sendMultiPart(parts: [HTTPRequestPart\[\]](dw.net.HTTPRequestPart.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Sends a multipart HTTP request. This method should only be called if the connection to the remote URL was opened
      with a POST or PATCH method. All other methods will result in an exception being thrown. The request is constructed
      from the passed array of parts.


    **Parameters:**
    - parts - List of part objects representing either string or file parts.

    **Returns:**
    - true if the returned code was a positive status code.


---

### setAllowRedirect(Boolean)
- setAllowRedirect(allowRedirect: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets whether automatic HTTP redirect handling is enabled.
      The default value is true. Set it to false to disable all redirects.


    **Parameters:**
    - allowRedirect - true or false for enabling or disabling automatic HTTP redirect


---

### setHostNameVerification(Boolean)
- setHostNameVerification(enable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets whether certificate host name verification is enabled.
      The default value is true. Set it to false to disable host name verification.


    **Parameters:**
    - enable - true to enable host name verification or false to disable it.


---

### setIdentity(KeyRef)
- setIdentity(keyRef: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)): void
  - : Sets the identity (private key) to use when mutual TLS (mTLS) is configured.
      
      
      If this is not set and mTLS is used then the private key will be chosen from the key store based on the host
      name.
      If this is set to a reference named "\_\_NONE\_\_" then no private key will be used even if one is requested by the remote server.


    **Parameters:**
    - keyRef - Reference to the private key


---

### setLoggingConfig(HTTPClientLoggingConfig)
- setLoggingConfig(config: [HTTPClientLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md)): void
  - : Sets the logging configuration for this HTTP client.

    **Parameters:**
    - config - the logging configuration to use


---

### setRequestHeader(String, String)
- setRequestHeader(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets a request header for the next HTTP operation.

    **Parameters:**
    - key - the request header.
    - value - the request headers' value.


---

### setTimeout(Number)
- setTimeout(timeoutMillis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the timeout for connections made with this client to the given number of milliseconds. If the given timeout
      is less than or equal to zero, the timeout is set to a maximum value of 2 or 15 minutes, depending on the
      context.
      
      
      This timeout value controls both the "connection timeout" (how long it takes to connect to the remote host) and
      the "socket timeout" (how long, after connecting, it will wait without any data being read). Therefore, in the
      worst case scenario, the total time of inactivity could be twice as long as the specified value.
      
      
      The maximum timeout is 15 minutes when the client is used in a job, and 2 minutes otherwise. The default timeout
      for a new client is the maximum timeout value.
      
      
      This method can be called at any time, and will affect the next connection made with this client. It is not
      possible to set the timeout for an open connection.
      
      
      You should always set a reasonable timeout (e.g., a few seconds). Allowing connections to run long can result
      in thread exhaustion.


    **Parameters:**
    - timeoutMillis - timeout, in milliseconds, up to a maximum of 2 or 15 minutes, depending on the context.


---

<!-- prettier-ignore-end -->

<!-- document id=0715c5897923adb076c679b6826d97b198f71ed2512cfc7509193dbfcdb1f582 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.HTTPClientLoggingConfig.md -->

<!-- prettier-ignore-start -->
# Class HTTPClientLoggingConfig

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.HTTPClientLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md)

Script API for configuring HTTP client logging and sensitive data redaction.


This class provides a customer-facing interface for configuring HTTP client logging behavior, including
enabling/disabling logging, setting log levels, and defining sensitive fields that should be redacted from HTTP
request and response bodies.


**Security Note:** This class handles sensitive security-related data and logging
configuration. Pay special attention to PCI DSS requirements when configuring sensitive field redaction to ensure
proper data protection.
Sensitive Fields of appropriate types MUST be set else logging will be skipped.


**Usage Example:**

```
var config = new dw.net.HTTPClientLoggingConfig();
// Enable logging and set level
config.setEnabled(true);
config.setLevel("INFO");
// Configure sensitive JSON fields
config.setSensitiveJsonFields(["password", "creditCard", "ssn"]);
// Configure sensitive XML fields
config.setSensitiveXmlFields(["password", "creditCard", "ssn"]);
// Configure sensitive headers
config.setSensitiveHeaders(["authorization", "x-api-key", "cookie"]);
// Configure sensitive body fields (for form data)
config.setSensitiveBodyFields(["password", "creditCard", "ssn"]);
// Configure text patterns for plain text/HTML content
config.setSensitiveTextPatterns([["password\\s*=\\s*[^\\s&]+"]]);
```



**Content Type Support:**

- **JSON:**Use setSensitiveJsonFields() to specify field names to redact
- **XML:**Use setSensitiveXmlFields() to specify element/attribute names to redact
- **Form Data:**Use setSensitiveBodyFields() to specify parameter names to redact
- **Plain Text/HTML:**Use setSensitiveTextPatterns() to specify regex patterns
- **Binary/Multipart:**Entire body is automatically treated as sensitive



## Property Summary

| Property | Description |
| --- | --- |
| [enabled](#enabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Gets whether HTTP client logging is enabled. |
| [level](#level): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Gets the current log level for HTTP client logging. |
| [sensitiveBodyFields](#sensitivebodyfields): [String\[\]](TopLevel.String.md) | Gets the sensitive body fields configured for form data redaction. |
| [sensitiveHeaders](#sensitiveheaders): [String\[\]](TopLevel.String.md) | Gets the sensitive headers configured for redaction. |
| [sensitiveJsonFields](#sensitivejsonfields): [String\[\]](TopLevel.String.md) | Gets the sensitive JSON fields configured for redaction. |
| [sensitiveXmlFields](#sensitivexmlfields): [String\[\]](TopLevel.String.md) | Gets the sensitive XML fields configured for redaction. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [HTTPClientLoggingConfig](#httpclientloggingconfig)() | Creates a new HTTPClientLoggingConfig instance. |

## Method Summary

| Method | Description |
| --- | --- |
| [getLevel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#getlevel)() | Gets the current log level for HTTP client logging. |
| [getSensitiveBodyFields](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#getsensitivebodyfields)() | Gets the sensitive body fields configured for form data redaction. |
| [getSensitiveHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#getsensitiveheaders)() | Gets the sensitive headers configured for redaction. |
| [getSensitiveJsonFields](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#getsensitivejsonfields)() | Gets the sensitive JSON fields configured for redaction. |
| [getSensitiveXmlFields](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#getsensitivexmlfields)() | Gets the sensitive XML fields configured for redaction. |
| [isEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#isenabled)() | Gets whether HTTP client logging is enabled. |
| [setEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#setenabledboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets whether HTTP client logging is enabled. |
| [setLevel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#setlevelstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the log level for HTTP client logging. |
| [setSensitiveBodyFields](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#setsensitivebodyfieldsstring)([String\[\]](TopLevel.String.md)) | Sets the sensitive body fields that should be redacted from HTTP form data. |
| [setSensitiveHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#setsensitiveheadersstring)([String\[\]](TopLevel.String.md)) | Sets the sensitive headers that should be redacted from HTTP requests/responses. |
| [setSensitiveJsonFields](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#setsensitivejsonfieldsstring)([String\[\]](TopLevel.String.md)) | Sets the sensitive JSON fields that should be redacted from HTTP request/response bodies. |
| [setSensitiveTextPatterns](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#setsensitivetextpatternsstring)([String\[\]](TopLevel.String.md)) | Sets the sensitive text patterns that should be redacted from HTTP request/response bodies. |
| [setSensitiveXmlFields](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md#setsensitivexmlfieldsstring)([String\[\]](TopLevel.String.md)) | Sets the sensitive XML fields that should be redacted from HTTP request/response bodies. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### enabled
- enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Gets whether HTTP client logging is enabled.


---

### level
- level: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the current log level for HTTP client logging.


---

### sensitiveBodyFields
- sensitiveBodyFields: [String\[\]](TopLevel.String.md)
  - : Gets the sensitive body fields configured for form data redaction.


---

### sensitiveHeaders
- sensitiveHeaders: [String\[\]](TopLevel.String.md)
  - : Gets the sensitive headers configured for redaction.


---

### sensitiveJsonFields
- sensitiveJsonFields: [String\[\]](TopLevel.String.md)
  - : Gets the sensitive JSON fields configured for redaction.


---

### sensitiveXmlFields
- sensitiveXmlFields: [String\[\]](TopLevel.String.md)
  - : Gets the sensitive XML fields configured for redaction.


---

## Constructor Details

### HTTPClientLoggingConfig()
- HTTPClientLoggingConfig()
  - : Creates a new HTTPClientLoggingConfig instance.
      
      
      The public constructor should only be called from JavaScript, but cfgAPI uses this constructor for creating the
      Service instance -> so fill the factory here



---

## Method Details

### getLevel()
- getLevel(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the current log level for HTTP client logging.

    **Returns:**
    - the log level as a string (DEBUG, INFO, WARN, ERROR)


---

### getSensitiveBodyFields()
- getSensitiveBodyFields(): [String\[\]](TopLevel.String.md)
  - : Gets the sensitive body fields configured for form data redaction.

    **Returns:**
    - an array of field names that will be redacted from form data


---

### getSensitiveHeaders()
- getSensitiveHeaders(): [String\[\]](TopLevel.String.md)
  - : Gets the sensitive headers configured for redaction.

    **Returns:**
    - an array of header names that will be redacted


---

### getSensitiveJsonFields()
- getSensitiveJsonFields(): [String\[\]](TopLevel.String.md)
  - : Gets the sensitive JSON fields configured for redaction.

    **Returns:**
    - an array of field names that will be redacted from JSON content


---

### getSensitiveXmlFields()
- getSensitiveXmlFields(): [String\[\]](TopLevel.String.md)
  - : Gets the sensitive XML fields configured for redaction.

    **Returns:**
    - an array of field names that will be redacted from XML content


---

### isEnabled()
- isEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Gets whether HTTP client logging is enabled.

    **Returns:**
    - true if logging is enabled, false otherwise


---

### setEnabled(Boolean)
- setEnabled(enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets whether HTTP client logging is enabled.
      
      
      When enabled, HTTP requests and responses will be logged according to the configured log level and sensitive
      field redaction settings. When disabled, no HTTP logging will occur.


    **Parameters:**
    - enabled - true to enable logging, false to disable


---

### setLevel(String)
- setLevel(level: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the log level for HTTP client logging.
      
      
      The log level determines the verbosity of HTTP logging output. Available levels:
      
      - **DEBUG:**Most verbose, includes detailed request/response information
      - **INFO:**Standard level, includes basic request/response details
      - **WARN:**Only logs warnings and errors
      - **ERROR:**Only logs errors


    **Parameters:**
    - level - the log level (DEBUG, INFO, WARN, ERROR). Case-insensitive.


---

### setSensitiveBodyFields(String[])
- setSensitiveBodyFields(fields: [String\[\]](TopLevel.String.md)): void
  - : Sets the sensitive body fields that should be redacted from HTTP form data.
      
      
      When HTTP requests or responses contain form data (application/x-www-form-urlencoded), any parameters matching
      the specified field names will be redacted with "\*\*\*\*FILTERED\*\*\*\*" in the logs.
      Sensitive Field MUST be set else logging will be skipped for form body type
      Setting with empty array will use default values \["name", "email", "email\_address", "ssn", "first\_name", "last\_name"\]
      
      
      **Example:**
      
      ```
      config.setSensitiveBodyFields(["fname", "creditCard", "ssn_last_4"]);
      ```


    **Parameters:**
    - fields - an array of field names to redact from form data


---

### setSensitiveHeaders(String[])
- setSensitiveHeaders(headers: [String\[\]](TopLevel.String.md)): void
  - : Sets the sensitive headers that should be redacted from HTTP requests/responses.
      
      
      Any HTTP headers matching the specified names will be redacted with "\*\*\*\*FILTERED\*\*\*\*" in the logs. This is useful for
      protecting sensitive authentication tokens, API keys, and session information.
      Sensitive Headers MUST be set else logging will be skipped for headers
      Setting the sensitive headers with empty array will use default values \["authorization", "cookie"\]
      
      
      **Example:**
      
      ```
      config.setSensitiveHeaders([ "x-api-key", "x-auth-token"]);
      config.setSensiviteHeaders([]);
      ```


    **Parameters:**
    - headers - an array of header names to redact


---

### setSensitiveJsonFields(String[])
- setSensitiveJsonFields(fields: [String\[\]](TopLevel.String.md)): void
  - : Sets the sensitive JSON fields that should be redacted from HTTP request/response bodies.
      
      
      When HTTP requests or responses contain JSON content, any fields matching the specified names will be redacted
      with "\*\*\*\*FILTERED\*\*\*\*" in the logs.
      Sensitive Field MUST be set else logging will be skipped for JSON body type
      Setting with empty array will use default values \["name", "email", "email\_address", "ssn", "first\_name", "last\_name", "password"\]
      
      
      **Example:**
      
      ```
      config.setSensitiveJsonFields(["password", "creditCard", "ssn"]);
      ```


    **Parameters:**
    - fields - an array of field names to redact from JSON content


---

### setSensitiveTextPatterns(String[])
- setSensitiveTextPatterns(patterns: [String\[\]](TopLevel.String.md)): void
  - : Sets the sensitive text patterns that should be redacted from HTTP request/response bodies.
      
      
      When HTTP requests or responses contain text content, any text matching the specified regex patterns will be
      redacted with "\*\*\*\*FILTERED\*\*\*\*" in the logs.
      
      
      **Example:**
      
      ```
      config.setSensitiveTextPatterns(["password", "credit.*card", "\\d{3}-\\d{2}-\\d{4}"]);
      ```


    **Parameters:**
    - patterns - an array of regex patterns to match and redact from text content


---

### setSensitiveXmlFields(String[])
- setSensitiveXmlFields(fields: [String\[\]](TopLevel.String.md)): void
  - : Sets the sensitive XML fields that should be redacted from HTTP request/response bodies.
      
      
      When HTTP requests or responses contain XML content, any elements or attributes matching the specified names will
      be redacted with "\*\*\*\*FILTERED\*\*\*\*" in the logs.
      Sensitive Field MUST be set else logging will be skipped for XML body type
      Setting with empty array will use default values \["name", "email", "email\_address", "ssn", "first\_name", "last\_name", "password"\]
      
      
      **Example:**
      
      ```
      config.setSensitiveXmlFields(["password", "creditCard", "ssn"]);
      ```


    **Parameters:**
    - fields - an array of element/attribute names to redact from XML content


---

<!-- prettier-ignore-end -->

<!-- document id=28d3f329d1b8a2fd4cb410f2176e0e172355ed57e038a1f52369451768e89b33 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.HTTPFormService.md -->

<!-- prettier-ignore-start -->
# Class HTTPFormService

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
    - [dw.svc.HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
      - [dw.svc.HTTPFormService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormService.md)

Represents an HTTP Form POST Service.


All arguments passed to the [call](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject) method will be URL-encoded and set as name/value
pairs in the HTTP request body. The HTTP request will be a POST with a content-type of
`application/x-www-form-urlencoded`.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class HTTPService

[addHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#addheaderstring-string), [addParam](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#addparamstring-string), [getAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getauthentication), [getCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getcachingttl), [getClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getclient), [getEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getencoding), [getHostNameVerification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#gethostnameverification), [getIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getidentity), [getOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getoutfile), [getRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getrequestmethod), [setAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setauthenticationstring), [setCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setcachingttlnumber), [setEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setencodingstring), [setHostNameVerification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#sethostnameverificationboolean), [setIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setidentitykeyref), [setOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setoutfilefile), [setRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setrequestmethodstring)
### Methods inherited from class Service

[call](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getconfiguration), [getCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getcredentialid), [getRequestData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getrequestdata), [getResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getresponse), [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#geturl), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#isthrowonerror), [setCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setcredentialidstring), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setthrowonerror), [setURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#seturlstring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=c53f50061060867807274f2ac2f68ee1d272e5dd253baa16eb60feb1e88bb58e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.HTTPFormServiceDefinition.md -->

<!-- prettier-ignore-start -->
# Class HTTPFormServiceDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
    - [dw.svc.HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
      - [dw.svc.HTTPFormServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormServiceDefinition.md)

Represents an HTTP Form POST Service Definition.

**Deprecated:**
**warning:** This class is only used with the deprecated [ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md). Use the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)
            instead, which allows configuration on the [HTTPFormService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormService.md) directly.
**API Version:**
**note:** No longer available as of version 19.10.

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class HTTPServiceDefinition

[addHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#addheaderstring-string), [addParam](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#addparamstring-string), [getAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getauthentication), [getCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getcachingttl), [getEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getencoding), [getOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getoutfile), [getRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getrequestmethod), [setAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setauthenticationstring), [setCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setcachingttlnumber), [setEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setencodingstring), [setOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setoutfilefile), [setRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setrequestmethodstring)
### Methods inherited from class ServiceDefinition

[configure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#configureobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getconfiguration), [getServiceName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getservicename), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#isthrowonerror), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setthrowonerror)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=36f17f3ccba630a2af9f22aba07f5dc56d667004ade6e7720e893ced0ff5b17a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.HttpParameter.md -->

<!-- prettier-ignore-start -->
# Class HttpParameter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.HttpParameter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md)

Represents an HTTP parameter.


## Property Summary

| Property | Description |
| --- | --- |
| [booleanValue](#booleanvalue): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the value of the current HttpParameter attribute as a boolean. |
| [dateValue](#datevalue): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the value of the current HttpParameter attribute as a date. |
| [doubleValue](#doublevalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the value of the current HttpParameter attribute as a number. |
| [empty](#empty): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if there is a value for the http parameter attribute  and whether the value is empty. |
| [intValue](#intvalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the value of the current HttpParameter attribute as int. |
| [rawValue](#rawvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the raw value for this HttpParameter instance. |
| [rawValues](#rawvalues): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a Collection of all raw values for this HTTP parameter. |
| [stringValue](#stringvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value of the current HttpParameter attribute. |
| [stringValues](#stringvalues): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a Collection of all defined values for this HTTP parameter. |
| [submitted](#submitted): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the parameter was submitted. |
| [value](#value): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value of the current HttpParameter attribute. |
| [values](#values): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a Collection of all defined values for this current HTTP parameter. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [containsStringValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#containsstringvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if the given value is part of the actual values. |
| [getBooleanValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getbooleanvalue)() | Returns the value of the current HttpParameter attribute as a boolean. |
| [getBooleanValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getbooleanvalueboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the value of the current HttpParameter attribute as a boolean. |
| [getDateValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getdatevalue)() | Returns the value of the current HttpParameter attribute as a date. |
| [getDateValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getdatevaluedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Returns the value of the current HttpParameter attribute as a date. |
| [getDoubleValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getdoublevalue)() | Returns the value of the current HttpParameter attribute as a number. |
| [getDoubleValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getdoublevaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value of the current HttpParameter attribute as a number. |
| [getIntValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getintvalue)() | Returns the value of the current HttpParameter attribute as int. |
| [getIntValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getintvaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value of the current HttpParameter attribute as an integer. |
| [getRawValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getrawvalue)() | Returns the raw value for this HttpParameter instance. |
| [getRawValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getrawvalues)() | Returns a Collection of all raw values for this HTTP parameter. |
| [getStringValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalue)() | Returns the value of the current HttpParameter attribute. |
| [getStringValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the value of the current HttpParameter attribute. |
| [getStringValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalues)() | Returns a Collection of all defined values for this HTTP parameter. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getvalue)() | Returns the value of the current HttpParameter attribute. |
| [getValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getvalues)() | Returns a Collection of all defined values for this current HTTP parameter. |
| [isChecked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#ischeckedstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if the given String is an actual value of this http parameter. |
| [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#isempty)() | Identifies if there is a value for the http parameter attribute  and whether the value is empty. |
| [isSubmitted](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#issubmitted)() | Identifies if the parameter was submitted. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#tostring)() | Returns the value of the current HttpParameter attribute. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### booleanValue
- booleanValue: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the value of the current HttpParameter attribute as a boolean. If
      there is more than one value defined, only the first one is returned. For an
      undefined attribute it returns null.



---

### dateValue
- dateValue: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the value of the current HttpParameter attribute as a date. If
      there is more than one value defined, only the first one is returned. For
      an undefined attribute and if attribute is not a date it return null.



---

### doubleValue
- doubleValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the value of the current HttpParameter attribute as a number. If
      there is more than one value defined, only the first one is returned. For
      an undefined attribute it returns 0.0.



---

### empty
- empty: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if there is a value for the http parameter attribute
      and whether the value is empty.
      A value is treated as empty if it's not blank.



---

### intValue
- intValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the value of the current HttpParameter attribute as int. If there
      is more than one value defined, only the first one is returned. For an
      undefined attribute it returns null.



---

### rawValue
- rawValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the raw value for this HttpParameter instance.
      The raw value is the not trimmed String value of this HTTP parameter.
      If there is more than one value defined, only the first one is returned. For an
      undefined attribute the method returns a null.


    **See Also:**
    - [getStringValue()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalue)


---

### rawValues
- rawValues: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a Collection of all raw values for this HTTP parameter.
      The raw value is the not trimmed String value of this HTTP parameter.


    **See Also:**
    - [getStringValues()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalues)


---

### stringValue
- stringValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value of the current HttpParameter attribute. If there is
      more than one value defined, only the first one is returned. For an
      undefined attribute the method returns a null.



---

### stringValues
- stringValues: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a Collection of all defined values for this HTTP parameter.


---

### submitted
- submitted: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the parameter was submitted. This is equivalent to the
      check, whether the parameter has a value.



---

### value
- value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value of the current HttpParameter attribute. If there is
      more than one value defined, only the first one is returned. For an
      undefined attribute the method returns null.



---

### values
- values: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a Collection of all defined values for this current HTTP parameter.

    **See Also:**
    - [getStringValues()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalues)


---

## Method Details

### containsStringValue(String)
- containsStringValue(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the given value is part of the actual values.

    **Parameters:**
    - value - the value to check.

    **Returns:**
    - true if the value is among the actual values, false otherwise.


---

### getBooleanValue()
- getBooleanValue(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the value of the current HttpParameter attribute as a boolean. If
      there is more than one value defined, only the first one is returned. For an
      undefined attribute it returns null.


    **Returns:**
    - the actual value as a boolean or null of no value is available.


---

### getBooleanValue(Boolean)
- getBooleanValue(defaultValue: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the value of the current HttpParameter attribute as a boolean. If there
      is more than one value defined, only the first one is returned. For an
      undefined attribute it returns the given default value.


    **Parameters:**
    - defaultValue - the default value to use.

    **Returns:**
    - the value of the parameter or the default value if empty.


---

### getDateValue()
- getDateValue(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the value of the current HttpParameter attribute as a date. If
      there is more than one value defined, only the first one is returned. For
      an undefined attribute and if attribute is not a date it return null.


    **Returns:**
    - the actual value as date or null if empty.


---

### getDateValue(Date)
- getDateValue(defaultValue: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the value of the current HttpParameter attribute as a date. If
      there is more than one value defined, only the first one is returned. For
      an undefined attribute it returns the given default value and if
      the attributes is not a date it returns null.


    **Parameters:**
    - defaultValue - the default value to use.

    **Returns:**
    - the data value of the attribute or the default value if empty


---

### getDoubleValue()
- getDoubleValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the current HttpParameter attribute as a number. If
      there is more than one value defined, only the first one is returned. For
      an undefined attribute it returns 0.0.


    **Returns:**
    - the actual value as double or null if the parameter has no value.


---

### getDoubleValue(Number)
- getDoubleValue(defaultValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the current HttpParameter attribute as a number. If
      there is more than one value defined, only the first one is returned. For
      an undefined attribute it returns the given default value.


    **Parameters:**
    - defaultValue - the default value to use.

    **Returns:**
    - the actual value as double or the default value if empty.


---

### getIntValue()
- getIntValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the current HttpParameter attribute as int. If there
      is more than one value defined, only the first one is returned. For an
      undefined attribute it returns null.


    **Returns:**
    - the actual value as an integer or null of no value is available.


---

### getIntValue(Number)
- getIntValue(defaultValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the current HttpParameter attribute as an integer. If there
      is more than one value defined, only the first one is returned. For an
      undefined attribute it returns the given default value.


    **Parameters:**
    - defaultValue - the default value to use.

    **Returns:**
    - the value of the parameter or the default value if empty.


---

### getRawValue()
- getRawValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the raw value for this HttpParameter instance.
      The raw value is the not trimmed String value of this HTTP parameter.
      If there is more than one value defined, only the first one is returned. For an
      undefined attribute the method returns a null.


    **Returns:**
    - the actual value or null.

    **See Also:**
    - [getStringValue()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalue)


---

### getRawValues()
- getRawValues(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a Collection of all raw values for this HTTP parameter.
      The raw value is the not trimmed String value of this HTTP parameter.


    **Returns:**
    - the raw values as a Collection of String, might be empty

    **See Also:**
    - [getStringValues()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalues)


---

### getStringValue()
- getStringValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the current HttpParameter attribute. If there is
      more than one value defined, only the first one is returned. For an
      undefined attribute the method returns a null.


    **Returns:**
    - the actual value or null.


---

### getStringValue(String)
- getStringValue(defaultValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the current HttpParameter attribute. If there is
      more than one value defined, only the first one is returned. For an
      undefined attribute the method returns the given default value.


    **Parameters:**
    - defaultValue - the default value to use.

    **Returns:**
    - the actual value or the default value.


---

### getStringValues()
- getStringValues(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a Collection of all defined values for this HTTP parameter.

    **Returns:**
    - the actual values as Collection.


---

### getValue()
- getValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the current HttpParameter attribute. If there is
      more than one value defined, only the first one is returned. For an
      undefined attribute the method returns null.


    **Returns:**
    - the actual value or null.


---

### getValues()
- getValues(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a Collection of all defined values for this current HTTP parameter.

    **Returns:**
    - the actual values as Collection.

    **See Also:**
    - [getStringValues()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md#getstringvalues)


---

### isChecked(String)
- isChecked(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the given String is an actual value of this http parameter.

    **Parameters:**
    - value - the value to check.

    **Returns:**
    - true if the value is among the actual values, false otherwise.


---

### isEmpty()
- isEmpty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if there is a value for the http parameter attribute
      and whether the value is empty.
      A value is treated as empty if it's not blank.


    **Returns:**
    - true if a value is empty, false otherwise.


---

### isSubmitted()
- isSubmitted(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the parameter was submitted. This is equivalent to the
      check, whether the parameter has a value.


    **Returns:**
    - true if a value is there, false otherwise.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the current HttpParameter attribute. If there is
      more than one value defined, only the first one is returned. For an
      undefined attribute the method returns an empty string.


    **Returns:**
    - the actual value or an empty String.


---

<!-- prettier-ignore-end -->

<!-- document id=0b6045b3522d931e4406d8d50e7e4a8f7089cdb7b4dea9d867eb4db81bb46a2c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.HttpParameterMap.md -->

<!-- prettier-ignore-start -->
# Class HttpParameterMap

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.HttpParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md)

A map of HTTP parameters.


## Property Summary

| Property | Description |
| --- | --- |
| [parameterCount](#parametercount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of paramters in this http parameter map. |
| [parameterNames](#parameternames): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) `(read-only)` | Returns a collection of all parameter names. |
| [requestBodyAsString](#requestbodyasstring): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the HTTP request body as string (e.g. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#getobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the http parameter for the given key or an empty http parameter,  if no parameter is defined for that key. |
| [getParameterCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#getparametercount)() | Returns the number of paramters in this http parameter map. |
| [getParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#getparametermapstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a sub-map containing all parameters that start with the given  prefix. |
| [getParameterNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#getparameternames)() | Returns a collection of all parameter names. |
| [getRequestBodyAsString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#getrequestbodyasstring)() | Returns the HTTP request body as string (e.g. |
| [isParameterSubmitted](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#isparametersubmittedstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if the parameter has been submitted. |
| [processMultipart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#processmultipartfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | This method can be called to process a form submission for an HTML form  with encoding type "multipart/form-data". |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### parameterCount
- parameterCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of paramters in this http parameter map.


---

### parameterNames
- parameterNames: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) `(read-only)`
  - : Returns a collection of all parameter names.


---

### requestBodyAsString
- requestBodyAsString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the HTTP request body as string (e.g. useful for XML posts). A body
      is only returned if the request is a POST or PUT request and was not send
      with "application/x-www-form-urlencoded" encoding. If the request was send
      with that encoding it is interpreted as form data and the body will be empty.



---

## Method Details

### get(Object)
- get(name: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [HttpParameter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md)
  - : Returns the http parameter for the given key or an empty http parameter,
      if no parameter is defined for that key. An empty parameter returns
      false for the method isDefined().


    **Parameters:**
    - name - the key whose associated http parameter is to be returned.

    **Returns:**
    - the http parameter or an empty http parameter.


---

### getParameterCount()
- getParameterCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of paramters in this http parameter map.

    **Returns:**
    - the number parameters.


---

### getParameterMap(String)
- getParameterMap(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HttpParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md)
  - : Returns a sub-map containing all parameters that start with the given
      prefix. The prefix will be removed from the parameter names in the returned
      sub-map. For example with the parameters "pre\_P1" and "pre\_p2" a call with
      "pre\_" as parameter will return a HttpParameterMap containing "P1" and "P2".


    **Parameters:**
    - prefix - the prefix to use when creating the sub-map.

    **Returns:**
    - the sub-map containing the target parameters.


---

### getParameterNames()
- getParameterNames(): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Returns a collection of all parameter names.

    **Returns:**
    - a set of all parameter names


---

### getRequestBodyAsString()
- getRequestBodyAsString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the HTTP request body as string (e.g. useful for XML posts). A body
      is only returned if the request is a POST or PUT request and was not send
      with "application/x-www-form-urlencoded" encoding. If the request was send
      with that encoding it is interpreted as form data and the body will be empty.


    **Returns:**
    - the http request body


---

### isParameterSubmitted(String)
- isParameterSubmitted(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the parameter has been submitted.

    **Parameters:**
    - key - the parameter to check.

    **Returns:**
    - true if the parameter has been submitted, false otherwise.


---

### processMultipart(Function)
- processMultipart(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)
  - : This method can be called to process a form submission for an HTML form
      with encoding type "multipart/form-data". Such a form can have a mixture
      of "regular" HTML form fields and also file uploads.
      
      
      Form fields are available via [get(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md#getobject) without calling this method.
      Uploaded files still need to be processed via the passed callback function.
      
      
      This callback function is called for each file upload part in the request.
      The parameters are the field name, the content type and the original file
      name. The function can return either a null, which means that the upload
      of this part should be skipped, or return a dw.io.File instance. If the
      file is an existing directory the system will automatically generate a
      unique file name. If the file is not an existing directory the uploaded
      content will be directly stored into that file. An existing file with the
      same name will be deleted. If the file can't be deleted for whatever reason,
      the upload is stored with a generated unique file name in the indicated directory.
      
      
      An automatically generated file name consists of the the prefix "upload",
      a time stamp, a unique id and the extension tmp. For example:
      "upload\_20070114221535\_bc7H1aOadI9qYaaacovPd3lqna.tmp".
      
      
      ```
      var params : HttpParameterMap = pdict.CurrentHttpParameterMap;
      
      // Get the file name from the first field. This is works because the
      // parameter map is updated before the file part is parsed.
      var files : LinkedHashMap = params.processMultipart( (function( field, ct, oname ){
          return new File( File.IMPEX + "/" + params.firstField );
      }) );
      ```


    **Parameters:**
    - callback - a callback function, which takes the field name, content type and             original file name as input

    **Returns:**
    - a LinkedHashMap where the keys are the actual file names and the values are references to the [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md),
              _or_ `null` if this is not a multipart request



---

<!-- prettier-ignore-end -->

<!-- document id=7fd45049c69d3357d2dbd1b0683d95a07c678d6872982efc7eb6e2c348e176ce url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.HTTPRequestPart.md -->

<!-- prettier-ignore-start -->
# Class HTTPRequestPart

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.HTTPRequestPart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md)

This represents a part in a multi-part HTTP POST request.


A part always has a name and value. The value may be a String, Bytes, or the contents of a File.


A character encoding may be specified for any of these, and the content type and a file name may additionally be
specified for the Bytes and File types.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information.



## Property Summary

| Property | Description |
| --- | --- |
| [bytesValue](#bytesvalue): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md) `(read-only)` | Get the Bytes value of the part. |
| [contentType](#contenttype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the content type of this part. |
| [encoding](#encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the charset to be used to encode the string. |
| [fileName](#filename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the file name to use when sending a file part. |
| [fileValue](#filevalue): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) `(read-only)` | Get the file value of the part. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the name of the part. |
| [stringValue](#stringvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the string value of the part. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [HTTPRequestPart](#httprequestpartstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a part representing a simple string name/value pair. |
| [HTTPRequestPart](#httprequestpartstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a part representing a simple string name/value pair. |
| [HTTPRequestPart](#httprequestpartstring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Construct a part representing a name/File pair. |
| [HTTPRequestPart](#httprequestpartstring-bytes)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Construct a part representing a name/bytes pair. |
| [HTTPRequestPart](#httprequestpartstring-bytes-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a part representing a name/File pair. |
| [HTTPRequestPart](#httprequestpartstring-file-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a part representing a name/File pair. |
| [HTTPRequestPart](#httprequestpartstring-file-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a part representing a name/File pair. |

## Method Summary

| Method | Description |
| --- | --- |
| [getBytesValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md#getbytesvalue)() | Get the Bytes value of the part. |
| [getContentType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md#getcontenttype)() | Returns the content type of this part. |
| [getEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md#getencoding)() | Get the charset to be used to encode the string. |
| [getFileName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md#getfilename)() | Get the file name to use when sending a file part. |
| [getFileValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md#getfilevalue)() | Get the file value of the part. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md#getname)() | Get the name of the part. |
| [getStringValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md#getstringvalue)() | Get the string value of the part. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bytesValue
- bytesValue: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md) `(read-only)`
  - : Get the Bytes value of the part.


---

### contentType
- contentType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the content type of this part.


---

### encoding
- encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the charset to be used to encode the string.


---

### fileName
- fileName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the file name to use when sending a file part.


---

### fileValue
- fileValue: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) `(read-only)`
  - : Get the file value of the part.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the name of the part.


---

### stringValue
- stringValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the string value of the part.


---

## Constructor Details

### HTTPRequestPart(String, String)
- HTTPRequestPart(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a part representing a simple string name/value pair. The HTTP
      message uses "US-ASCII" as the default character set for the part.


    **Parameters:**
    - name - The name of the part.
    - value - The string to post.


---

### HTTPRequestPart(String, String, String)
- HTTPRequestPart(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a part representing a simple string name/value pair. The HTTP
      message uses the specified encoding or "US-ASCII" if null is passed
      for the part.


    **Parameters:**
    - name - The name of the part.
    - value - The string to post.
    - encoding - The charset to be used to encode the string, if null the             default is used.


---

### HTTPRequestPart(String, File)
- HTTPRequestPart(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md))
  - : Construct a part representing a name/File pair. The HTTP message will use
      "application/octet-stream" as the content type and "ISO-8859-1" as the character
      set for the part.


    **Parameters:**
    - name - The name of the file part
    - file - The file to post


---

### HTTPRequestPart(String, Bytes)
- HTTPRequestPart(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), data: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md))
  - : Construct a part representing a name/bytes pair. The HTTP message will use
      "application/octet-stream" as the content type without a character set.


    **Parameters:**
    - name - The name of the file part
    - data - The bytes to post


---

### HTTPRequestPart(String, Bytes, String, String, String)
- HTTPRequestPart(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), data: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), contentType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), fileName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a part representing a name/File pair.
      
      
      
      - If both contentType and encoding are null, then the part will be defaulted to use "application/octet-stream"  as the content-type without an encoding.    - If only the encoding is null, then the contentType will be used without an encoding.        - If only the contentType is null, then it will be defaulted to "text/plain".      


    **Parameters:**
    - name - The name of the file part
    - data - The bytes to post
    - contentType - The content type for this part, if null or blank the default is used.
    - encoding - the charset encoding for this part, if null or blank the default is used.
    - fileName - The file name to use in the Mime header, or null to not use one.


---

### HTTPRequestPart(String, File, String, String)
- HTTPRequestPart(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), contentType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a part representing a name/File pair.
      
      
      
      - If both contentType and encoding are null, then the part will be defaulted to use "application/octet-stream"  as the content-type and "ISO-8859-1" as the encoding.    - If only the encoding is null, then the contentType will be used without an encoding.        - If only the contentType is null, then it will be defaulted to "text/plain".      


    **Parameters:**
    - name - The name of the file part
    - file - The file to post
    - contentType - The content type for this part, if null or blank the default is used.
    - encoding - the charset encoding for this part, if null or blank the default is used


---

### HTTPRequestPart(String, File, String, String, String)
- HTTPRequestPart(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), contentType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), fileName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a part representing a name/File pair.
      
      
      
      - If both contentType and encoding are null, then the part will be defaulted to use "application/octet-stream"  as the content-type and "ISO-8859-1" as the encoding.    - If only the encoding is null, then the contentType will be used without an encoding.        - If only the contentType is null, then it will be defaulted to "text/plain".      


    **Parameters:**
    - name - The name of the file part
    - file - The file to post
    - contentType - The content type for this part, if null or blank the default is used.
    - encoding - the charset encoding for this part, if null or blank the default is used
    - fileName - The file name to use in the Mime header, or null to use the name of the given file.


---

## Method Details

### getBytesValue()
- getBytesValue(): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Get the Bytes value of the part.

    **Returns:**
    - The Bytes value, or null if this part is not a Bytes part.


---

### getContentType()
- getContentType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the content type of this part.

    **Returns:**
    - The content type, or null if content type was not specified.


---

### getEncoding()
- getEncoding(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the charset to be used to encode the string.

    **Returns:**
    - The charset, or null if charset was not specified.


---

### getFileName()
- getFileName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the file name to use when sending a file part.

    **Returns:**
    - File name to use in the Mime header, or null for default behavior.


---

### getFileValue()
- getFileValue(): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)
  - : Get the file value of the part.

    **Returns:**
    - The file value, or null if this part is not a file part.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the name of the part.

    **Returns:**
    - The part name, never null.


---

### getStringValue()
- getStringValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the string value of the part.

    **Returns:**
    - The string value, or null if this part is not a string part.


---

<!-- prettier-ignore-end -->

<!-- document id=b44d7abc632272e34bb1812ee7710789b15a7d757b58417811e35a38d0d4f3d7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.HTTPService.md -->

<!-- prettier-ignore-start -->
# Class HTTPService

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
    - [dw.svc.HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)

Represents an HTTP Service.


The HTTP Service will use the return value of the createRequest callback as the request body (if supported by the
HTTP method). If this is an array of non-null [HTTPRequestPart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md) objects, then a multi-part request will
be formed. Otherwise the object is converted to a String and used.


See also [XML.toXMLString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#toxmlstring) and [JSON.stringify(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#stringifyobject), which must be
explicitly called if needed.



## All Known Subclasses
[HTTPFormService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormService.md)
## Property Summary

| Property | Description |
| --- | --- |
| [authentication](#authentication): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the authentication type. |
| [cachingTTL](#cachingttl): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the caching time to live value. |
| [client](#client): [HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md) `(read-only)` | Returns the underlying HTTP client object. |
| [encoding](#encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the request body encoding to declare. |
| [hostNameVerification](#hostnameverification): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Determines whether host name verification is enabled. |
| [identity](#identity): [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md) | Gets the identity used for mutual TLS (mTLS). |
| [outFile](#outfile): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) | Returns the output file, or null if there is none. |
| [requestMethod](#requestmethod): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the request method. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#addheaderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds an HTTP Header. |
| [addParam](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#addparamstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a query parameter that will be appended to the URL. |
| [getAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getauthentication)() | Returns the authentication type. |
| [getCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getcachingttl)() | Returns the caching time to live value. |
| [getClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getclient)() | Returns the underlying HTTP client object. |
| [getEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getencoding)() | Returns the request body encoding to declare. |
| [getHostNameVerification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#gethostnameverification)() | Determines whether host name verification is enabled. |
| [getIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getidentity)() | Gets the identity used for mutual TLS (mTLS). |
| [getOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getoutfile)() | Returns the output file, or null if there is none. |
| [getRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#getrequestmethod)() | Returns the request method. |
| [setAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setauthenticationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the type of authentication. |
| [setCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setcachingttlnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Enables caching for GET requests. |
| [setEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setencodingstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the encoding of the request body (if any). |
| [setHostNameVerification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#sethostnameverificationboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets whether certificate host name verification is enabled. |
| [setIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setidentitykeyref)([KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)) | Sets the identity (private key) to use when mutual TLS (mTLS) is configured. |
| [setOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setoutfilefile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Sets the output file in which to write the HTTP response body. |
| [setRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setrequestmethodstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the HTTP request method. |

### Methods inherited from class Service

[call](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getconfiguration), [getCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getcredentialid), [getRequestData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getrequestdata), [getResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getresponse), [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#geturl), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#isthrowonerror), [setCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setcredentialidstring), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setthrowonerror), [setURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#seturlstring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### authentication
- authentication: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the authentication type.


---

### cachingTTL
- cachingTTL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the caching time to live value.

    **See Also:**
    - [setCachingTTL(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setcachingttlnumber)


---

### client
- client: [HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md) `(read-only)`
  - : Returns the underlying HTTP client object.


---

### encoding
- encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request body encoding to declare.


---

### hostNameVerification
- hostNameVerification: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether host name verification is enabled.


---

### identity
- identity: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)
  - : Gets the identity used for mutual TLS (mTLS).


---

### outFile
- outFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)
  - : Returns the output file, or null if there is none.


---

### requestMethod
- requestMethod: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request method.


---

## Method Details

### addHeader(String, String)
- addHeader(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), val: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Adds an HTTP Header.

    **Parameters:**
    - name - Header name.
    - val - Header value.

    **Returns:**
    - this HTTP Service.


---

### addParam(String, String)
- addParam(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), val: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Adds a query parameter that will be appended to the URL.

    **Parameters:**
    - name - Parameter name.
    - val - Parameter value.

    **Returns:**
    - this HTTP Service.


---

### getAuthentication()
- getAuthentication(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the authentication type.

    **Returns:**
    - Authentication type.


---

### getCachingTTL()
- getCachingTTL(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the caching time to live value.

    **Returns:**
    - The caching time to live value in seconds.

    **See Also:**
    - [setCachingTTL(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md#setcachingttlnumber)


---

### getClient()
- getClient(): [HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md)
  - : Returns the underlying HTTP client object.

    **Returns:**
    - HTTP client object.


---

### getEncoding()
- getEncoding(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request body encoding to declare.

    **Returns:**
    - Request encoding.


---

### getHostNameVerification()
- getHostNameVerification(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether host name verification is enabled.

    **Returns:**
    - true if verification is enabled, false otherwise


---

### getIdentity()
- getIdentity(): [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)
  - : Gets the identity used for mutual TLS (mTLS).

    **Returns:**
    - Reference to the private key, or null if not configured


---

### getOutFile()
- getOutFile(): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)
  - : Returns the output file, or null if there is none.

    **Returns:**
    - Output file or null.


---

### getRequestMethod()
- getRequestMethod(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request method.

    **Returns:**
    - HTTP Request method.


---

### setAuthentication(String)
- setAuthentication(authentication: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Sets the type of authentication. Valid values include "BASIC" and "NONE".
      
      
      The default value is BASIC.


    **Parameters:**
    - authentication - Type of authentication.

    **Returns:**
    - this HTTP Service.


---

### setCachingTTL(Number)
- setCachingTTL(ttl: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Enables caching for GET requests.
      
      
      This only caches status codes 2xx with a content length and size of less than 50k that are not immediately
      written to file. The URL and the user name are used as cache keys. The total size of cacheable content and the
      number of cached items is limited and automatically managed by the system.
      
      
      Cache control information sent by the remote server is ignored.
      
      
      Caching HTTP responses should be done very carefully. It is important to ensure that the response really depends
      only on the URL and doesn't contain any remote state information or time information which is independent of the
      URL. It is also important to verify that the application sends exactly the same URL multiple times.


    **Parameters:**
    - ttl - The time to live for the cached content in seconds. A value of 0 disables caching.

    **See Also:**
    - [HTTPClient.enableCaching(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#enablecachingnumber)


---

### setEncoding(String)
- setEncoding(encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Sets the encoding of the request body (if any).
      
      
      The default value is UTF-8.


    **Parameters:**
    - encoding - Encoding of the request body.

    **Returns:**
    - this HTTP Service.


---

### setHostNameVerification(Boolean)
- setHostNameVerification(enable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Sets whether certificate host name verification is enabled.
      The default value is true. Set it to false to disable host name verification.


    **Parameters:**
    - enable - true to enable host name verification or false to disable it.

    **Returns:**
    - this HTTP Service.


---

### setIdentity(KeyRef)
- setIdentity(keyRef: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Sets the identity (private key) to use when mutual TLS (mTLS) is configured.
      
      
      If this is not set and mTLS is used then the private key will be chosen from the key store based on the host
      name.
      If this is set to a reference named "\_\_NONE\_\_" then no private key will be used even if one is requested by the remote server.


    **Parameters:**
    - keyRef - Reference to the private key


---

### setOutFile(File)
- setOutFile(outFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Sets the output file in which to write the HTTP response body.
      
      
      The default behavior is to not write a file.


    **Parameters:**
    - outFile - Output file, or null to disable.

    **Returns:**
    - this HTTP Service.


---

### setRequestMethod(String)
- setRequestMethod(requestMethod: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)
  - : Sets the HTTP request method.
      
      
      Valid values include GET, PUT, POST, and DELETE.
      
      
      The default value is POST.


    **Parameters:**
    - requestMethod - HTTP request method.

    **Returns:**
    - this HTTP Service.


---

<!-- prettier-ignore-end -->

<!-- document id=cc9e9e0ba6274567838d2141900432b432a333e37161baa6b663c349cc1ac3b5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.HTTPServiceDefinition.md -->

<!-- prettier-ignore-start -->
# Class HTTPServiceDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
    - [dw.svc.HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)

Represents an HTTP Service Definition.


The HTTP Service will use the return value of the createRequest callback as the request body (if supported by the
HTTP method). If this is an array of non-null [HTTPRequestPart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md) objects, then a multi-part request will
be formed. Otherwise the object is converted to a String and used.


See also [XML.toXMLString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#toxmlstring) and [JSON.stringify(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#stringifyobject), which must be
explicitly called if needed.


**Deprecated:**
**warning:** This class is only used with the deprecated [ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md). Use the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)
            instead, which allows configuration on the [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md) directly.
**API Version:**
**note:** No longer available as of version 19.10.

## All Known Subclasses
[HTTPFormServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormServiceDefinition.md)
## Property Summary

| Property | Description |
| --- | --- |
| [authentication](#authentication): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the authentication type. |
| [cachingTTL](#cachingttl): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the caching time to live value. |
| [encoding](#encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the request body encoding to declare. |
| [outFile](#outfile): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) | Returns the output file, or null if there is none. |
| [requestMethod](#requestmethod): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the request method. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#addheaderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds an HTTP Header. |
| [addParam](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#addparamstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a query parameter that will be appended to the URL. |
| [getAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getauthentication)() | Returns the authentication type. |
| [getCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getcachingttl)() | Returns the caching time to live value. |
| [getEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getencoding)() | Returns the request body encoding to declare. |
| [getOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getoutfile)() | Returns the output file, or null if there is none. |
| [getRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#getrequestmethod)() | Returns the request method. |
| [setAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setauthenticationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the type of authentication. |
| [setCachingTTL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setcachingttlnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Enables caching for GET requests. |
| [setEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setencodingstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the encoding of the request body (if any). |
| [setOutFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setoutfilefile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Sets the output file in which to write the HTTP response body. |
| [setRequestMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setrequestmethodstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the HTTP request method. |

### Methods inherited from class ServiceDefinition

[configure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#configureobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getconfiguration), [getServiceName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getservicename), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#isthrowonerror), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setthrowonerror)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### authentication
- authentication: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the authentication type.


---

### cachingTTL
- cachingTTL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the caching time to live value.

    **See Also:**
    - [setCachingTTL(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setcachingttlnumber)


---

### encoding
- encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request body encoding to declare.


---

### outFile
- outFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)
  - : Returns the output file, or null if there is none.


---

### requestMethod
- requestMethod: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request method.


---

## Method Details

### addHeader(String, String)
- addHeader(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), val: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
  - : Adds an HTTP Header.

    **Parameters:**
    - name - Header name.
    - val - Header value.

    **Returns:**
    - this HTTP Service Definition.


---

### addParam(String, String)
- addParam(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), val: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
  - : Adds a query parameter that will be appended to the URL.

    **Parameters:**
    - name - Parameter name.
    - val - Parameter value.

    **Returns:**
    - this HTTP Service Definition.


---

### getAuthentication()
- getAuthentication(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the authentication type.

    **Returns:**
    - Authentication type.


---

### getCachingTTL()
- getCachingTTL(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the caching time to live value.

    **Returns:**
    - The caching time to live value in seconds.

    **See Also:**
    - [setCachingTTL(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md#setcachingttlnumber)


---

### getEncoding()
- getEncoding(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request body encoding to declare.

    **Returns:**
    - Request encoding.


---

### getOutFile()
- getOutFile(): [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)
  - : Returns the output file, or null if there is none.

    **Returns:**
    - Output file or null.


---

### getRequestMethod()
- getRequestMethod(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the request method.

    **Returns:**
    - HTTP Request method.


---

### setAuthentication(String)
- setAuthentication(authentication: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
  - : Sets the type of authentication. Valid values include "BASIC" and "NONE".
      
      
      The default value is BASIC.


    **Parameters:**
    - authentication - Type of authentication.

    **Returns:**
    - this HTTP Service Definition.


---

### setCachingTTL(Number)
- setCachingTTL(ttl: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
  - : Enables caching for GET requests.
      
      
      This only caches status codes 2xx with a content length and size of less than 50k that are not immediately
      written to file. The URL and the user name are used as cache keys. The total size of cacheable content and the
      number of cached items is limited and automatically managed by the system.
      
      
      Cache control information sent by the remote server is ignored.
      
      
      Caching HTTP responses should be done very carefully. It is important to ensure that the response really depends
      only on the URL and doesn't contain any remote state information or time information which is independent of the
      URL. It is also important to verify that the application sends exactly the same URL multiple times.


    **Parameters:**
    - ttl - The time to live for the cached content in seconds. A value of 0 or less disables caching.

    **See Also:**
    - [HTTPClient.enableCaching(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#enablecachingnumber)


---

### setEncoding(String)
- setEncoding(encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
  - : Sets the encoding of the request body (if any).
      
      
      The default value is UTF-8.


    **Parameters:**
    - encoding - Encoding of the request body.

    **Returns:**
    - this HTTP Service Definition.


---

### setOutFile(File)
- setOutFile(outFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
  - : Sets the output file in which to write the HTTP response body.
      
      
      The default behavior is to not write a file.


    **Parameters:**
    - outFile - Output file, or null to disable.

    **Returns:**
    - this HTTP Service Definition.


---

### setRequestMethod(String)
- setRequestMethod(requestMethod: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)
  - : Sets the HTTP request method.
      
      
      Valid values include GET, PUT, POST, and DELETE.
      
      
      The default value is POST.


    **Parameters:**
    - requestMethod - HTTP request method.

    **Returns:**
    - this HTTP Service Definition.


---

<!-- prettier-ignore-end -->

<!-- document id=5de46633349123fd933b5bfe52676e15eb8cd92c1d01d576ec33c26fb08fdfa8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.image.Image.md -->

<!-- prettier-ignore-start -->
# Class Image

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.image.Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)

This class represents an image with additional configuration capabilities (e.g. optional focal point).
Furthermore it provides access to meta data of the referenced image file.


**See Also:**
- [FocalPoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md)
- [ImageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md)


## Property Summary

| Property | Description |
| --- | --- |
| [file](#file): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the image media file from the current site's library. |
| [focalPoint](#focalpoint): [FocalPoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md) `(read-only)` | Returns the focal point of the image. |
| [metaData](#metadata): [ImageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md) `(read-only)` | Returns the meta data of the physical image file. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md#getfile)() | Returns the image media file from the current site's library. |
| [getFocalPoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md#getfocalpoint)() | Returns the focal point of the image. |
| [getMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md#getmetadata)() | Returns the meta data of the physical image file. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### file
- file: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the image media file from the current site's library.


---

### focalPoint
- focalPoint: [FocalPoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md) `(read-only)`
  - : Returns the focal point of the image.


---

### metaData
- metaData: [ImageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md) `(read-only)`
  - : Returns the meta data of the physical image file. This meta data is obtained when
      the respective component attribute was saved from Page Designer, i.e. the underlying
      image is not queried for the meta data every time [getMetaData()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md#getmetadata) is called
      but only on store of the related component attribute.



---

## Method Details

### getFile()
- getFile(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the image media file from the current site's library.

    **Returns:**
    - the image media file, or null if not found


---

### getFocalPoint()
- getFocalPoint(): [FocalPoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md)
  - : Returns the focal point of the image.

    **Returns:**
    - the focal point, or null if not found


---

### getMetaData()
- getMetaData(): [ImageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md)
  - : Returns the meta data of the physical image file. This meta data is obtained when
      the respective component attribute was saved from Page Designer, i.e. the underlying
      image is not queried for the meta data every time [getMetaData()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md#getmetadata) is called
      but only on store of the related component attribute.


    **Returns:**
    - the meta data of the image, or null if no meta data was provided with the respective component attribute


---

<!-- prettier-ignore-end -->

<!-- document id=700461b42308cbd8fcde1c6cd82f98d84170f792eedbe8f9ee9683244bdaf8b4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.image.ImageMetaData.md -->

<!-- prettier-ignore-start -->
# Class ImageMetaData

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.image.ImageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md)

This class represents the image meta data, e.g. width and height.

**See Also:**
- [Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)


## Property Summary

| Property | Description |
| --- | --- |
| [height](#height): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the image height. |
| [width](#width): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the image width. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getHeight](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md#getheight)() | Returns the image height. |
| [getWidth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md#getwidth)() | Returns the image width. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### height
- height: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the image height.


---

### width
- width: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the image width.


---

## Method Details

### getHeight()
- getHeight(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the image height.

    **Returns:**
    - the image height in pixel


---

### getWidth()
- getWidth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the image width.

    **Returns:**
    - the image width in pixel


---

<!-- prettier-ignore-end -->

<!-- document id=5b3b3b1ee63282b9a6b813c4e6064e2423dce9b5c6041d0c0088ee5cc250aa1d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.InputStream.md -->

<!-- prettier-ignore-start -->
# Class InputStream

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.InputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.InputStream.md)

The class represent a stream of bytes that can be read from the
application. The InputStream itself doesn't provide any methods
to read the data. Instead the InputStream can be chained with
other classes like a XMLStreamReader to read data.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.InputStream.md#close)() | Closes the input stream. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### close()
- close(): void
  - : Closes the input stream.


---

<!-- prettier-ignore-end -->

<!-- document id=1a00c61f8e4640c707ead3c1e5a84119d5113d8f60a8f95b65076bb7289662dd url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Int16Array.md -->

<!-- prettier-ignore-start -->
# Class Int16Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Int16Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int16Array.md)

An optimized array to store 16-bit signed integer numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Int16Array](#int16array)() | Creates an empty array. |
| [Int16Array](#int16arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Int16Array](#int16arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Int16Array](#int16arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Int16Array](#int16arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int16Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int16Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int16Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Int16Array()
- Int16Array()
  - : Creates an empty array.


---

### Int16Array(Number)
- Int16Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Int16Array(Object)
- Int16Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Int16Array(Array)
- Int16Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Int16Array(ArrayBuffer, Number, Number)
- Int16Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Int16Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int16Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=43a3161b6453d6ff85a181c8ed422e1f92889319a6a8b22a6ee713de14f903e1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Int32Array.md -->

<!-- prettier-ignore-start -->
# Class Int32Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Int32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int32Array.md)

An optimized array to store 32-bit signed integer numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Int32Array](#int32array)() | Creates an empty array. |
| [Int32Array](#int32arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Int32Array](#int32arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Int32Array](#int32arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Int32Array](#int32arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int32Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int32Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int32Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Int32Array()
- Int32Array()
  - : Creates an empty array.


---

### Int32Array(Number)
- Int32Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Int32Array(Object)
- Int32Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Int32Array(Array)
- Int32Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Int32Array(ArrayBuffer, Number, Number)
- Int32Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Int32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int32Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=5efda85a09326163543f6ff8a45ec7fd36934965fc336fa740f9da5d252c5907 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Int8Array.md -->

<!-- prettier-ignore-start -->
# Class Int8Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Int8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int8Array.md)

An optimized array to store 8-bit signed integer numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Int8Array](#int8array)() | Creates an empty array. |
| [Int8Array](#int8arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Int8Array](#int8arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Int8Array](#int8arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Int8Array](#int8arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int8Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int8Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int8Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Int8Array()
- Int8Array()
  - : Creates an empty array.


---

### Int8Array(Number)
- Int8Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Int8Array(Object)
- Int8Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Int8Array(Array)
- Int8Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Int8Array(ArrayBuffer, Number, Number)
- Int8Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Int8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int8Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=9525ed16cf110b6f99df9656497b514132360e1417725722c1f5fa926ec1c245 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.InternalError.md -->

<!-- prettier-ignore-start -->
# Class InternalError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.InternalError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.InternalError.md)

Represents the an internal error.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [InternalError](#internalerror)() | Constructs the error. |
| [InternalError](#internalerrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the   specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### InternalError()
- InternalError()
  - : Constructs the error.


---

### InternalError(String)
- InternalError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the 
      specified message.


    **Parameters:**
    - msg - the internal error message.


---

<!-- prettier-ignore-end -->

<!-- document id=57592b77c123e2e9da6e6f6a5feb2e62465267cc7b4031be7d2e6511726bd611 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.InternalObject.md -->

<!-- prettier-ignore-start -->
# Class InternalObject

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.InternalObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.InternalObject.md)

Class used to wrap internal objects to hide them from
B2C Commerce Script code.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.InternalObject.md#tostring)() | Returns a string representation of this object. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.InternalObject.md#valueof)() | Returns a string representation of this object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this object.

    **Returns:**
    - a string representation of this object.


---

### valueOf()
- valueOf(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this object.

    **Returns:**
    - a string representation of this object.


---

<!-- prettier-ignore-end -->

<!-- document id=e5487ea521188ae66836bbd829a62a278a8580395542b40d4fee8db810597db4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.Invoice.md -->

<!-- prettier-ignore-start -->
# Class Invoice

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md)
      - [dw.order.Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)

The Invoice can be a debit or credit invoice, and is created
from custom scripts using one of the methods
[ShippingOrder.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoicestring),
[Appeasement.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoicestring),
[ReturnCase.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring) or
[Return.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring).


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [ORDERBY_CREATION_DATE](#orderby_creation_date): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by creation date. |
| [ORDERBY_ITEMID](#orderby_itemid): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by item id. |
| [ORDERBY_ITEMPOSITION](#orderby_itemposition): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by the position of the related oder item. |
| [ORDERBY_REVERSE](#orderby_reverse): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Reverse orders. |
| [ORDERBY_UNSORTED](#orderby_unsorted): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Unsorted , as it is. |
| [QUALIFIER_CAPTURE](#qualifier_capture): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the capture transactions. |
| [QUALIFIER_PRODUCTITEMS](#qualifier_productitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the product items. |
| [QUALIFIER_REFUND](#qualifier_refund): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the refund transactions. |
| [QUALIFIER_SERVICEITEMS](#qualifier_serviceitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects for the service items. |
| [STATUS_FAILED](#status_failed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FAILED" | Constant for Invoice Status Failed.  The invoice handling failed. |
| [STATUS_MANUAL](#status_manual): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MANUAL" | Constant for Invoice Status Manual.  The invoice is not paid but will **not** be handled automatically.  A manual invoice handling (capture or refund) is necessary. |
| [STATUS_NOT_PAID](#status_not_paid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NOT_PAID" | Constant for Invoice Status Not Paid.  The invoice is not paid and will be handled automatically. |
| [STATUS_PAID](#status_paid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PAID" | Constant for Invoice Status Paid.  The invoice was successfully paid. |
| [TYPE_APPEASEMENT](#type_appeasement): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "APPEASEMENT" | Constant for Invoice Type Appeasement.  The invoice was created for an appeasement.  The invoice amount needs to be refunded. |
| [TYPE_RETURN](#type_return): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURN" | Constant for Invoice Type Return.  The invoice was created for a return.  The invoice amount needs to be refunded. |
| [TYPE_RETURN_CASE](#type_return_case): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURN_CASE" | Constant for Invoice Type Return Case.  The invoice was created for a return case.  The invoice amount needs to be refunded. |
| [TYPE_SHIPPING](#type_shipping): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPING" | Constant for Invoice Type Shipping.  The invoice was created for a shipping order.  The invoice amount needs to be captured. |

## Property Summary

| Property | Description |
| --- | --- |
| [capturedAmount](#capturedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of the captured amounts. |
| [invoiceNumber](#invoicenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the invoice number. |
| [items](#items): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Access the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s. |
| [paymentTransactions](#paymenttransactions): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the payment transactions belonging to this Invoice. |
| [refundedAmount](#refundedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of the refunded amounts. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the invoice status.  The possible values are [STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), [STATUS_MANUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_manual),  [STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid), [STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed). |
| [type](#type): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | Returns the invoice type.  The possible values are [TYPE_SHIPPING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_shipping), [TYPE_RETURN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return),  [TYPE_RETURN_CASE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return_case), [TYPE_APPEASEMENT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_appeasement). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [account](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#account)() | <p>  The invoice will be accounted. |
| [addCaptureTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addcapturetransactionorderpaymentinstrument-money)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Calling this method registers an amount captured for a given  order payment instrument. |
| [addRefundTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addrefundtransactionorderpaymentinstrument-money)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Calling this method registers an amount refunded for a given  order payment instrument. |
| [getCapturedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getcapturedamount)() | Returns the sum of the captured amounts. |
| [getInvoiceNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getinvoicenumber)() | Returns the invoice number. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getitems)() | Access the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s. |
| [getPaymentTransactions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getpaymenttransactions)() | Returns the payment transactions belonging to this Invoice. |
| [getRefundedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getrefundedamount)() | Returns the sum of the refunded amounts. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getstatus)() | Returns the invoice status.  The possible values are [STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), [STATUS_MANUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_manual),  [STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid), [STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed). |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#gettype)() | Returns the invoice type.  The possible values are [TYPE_SHIPPING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_shipping), [TYPE_RETURN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return),  [TYPE_RETURN_CASE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return_case), [TYPE_APPEASEMENT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_appeasement). |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#setstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the invoice status.  The possible values are [STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), [STATUS_MANUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_manual),  [STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid), [STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed). |

### Methods inherited from class AbstractItemCtnr

[getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreatedby), [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreationdate), [getGrandTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getgrandtotal), [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getlastmodified), [getModifiedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getmodifiedby), [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder), [getProductSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getproductsubtotal), [getServiceSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getservicesubtotal)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ORDERBY_CREATION_DATE

- ORDERBY_CREATION_DATE: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by creation date. Use with method [getPaymentTransactions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getpaymenttransactions) as an argument to
      method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### ORDERBY_ITEMID

- ORDERBY_ITEMID: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by item id. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getitems) as an argument to
      method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### ORDERBY_ITEMPOSITION

- ORDERBY_ITEMPOSITION: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by the position of the related oder item. Use with method
      [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getitems) as an argument to method
      [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### ORDERBY_REVERSE

- ORDERBY_REVERSE: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Reverse orders. Use as an argument
      to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### ORDERBY_UNSORTED

- ORDERBY_UNSORTED: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Unsorted , as it is. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getitems) as an argument
      to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### QUALIFIER_CAPTURE

- QUALIFIER_CAPTURE: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the capture transactions. Use with method [getPaymentTransactions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getpaymenttransactions) as an
      argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).



---

### QUALIFIER_PRODUCTITEMS

- QUALIFIER_PRODUCTITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the product items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getitems) as an
      argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).



---

### QUALIFIER_REFUND

- QUALIFIER_REFUND: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the refund transactions. Use with method [getPaymentTransactions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getpaymenttransactions) as an
      argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).



---

### QUALIFIER_SERVICEITEMS

- QUALIFIER_SERVICEITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects for the service items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#getitems) as an
      argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).



---

### STATUS_FAILED

- STATUS_FAILED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FAILED"
  - : Constant for Invoice Status Failed.
      
      The invoice handling failed.



---

### STATUS_MANUAL

- STATUS_MANUAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MANUAL"
  - : Constant for Invoice Status Manual.
      
      The invoice is not paid but will **not** be handled automatically.
      
      A manual invoice handling (capture or refund) is necessary.



---

### STATUS_NOT_PAID

- STATUS_NOT_PAID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NOT_PAID"
  - : Constant for Invoice Status Not Paid.
      
      The invoice is not paid and will be handled automatically.



---

### STATUS_PAID

- STATUS_PAID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PAID"
  - : Constant for Invoice Status Paid.
      
      The invoice was successfully paid.



---

### TYPE_APPEASEMENT

- TYPE_APPEASEMENT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "APPEASEMENT"
  - : Constant for Invoice Type Appeasement.
      
      The invoice was created for an appeasement.
      
      The invoice amount needs to be refunded.



---

### TYPE_RETURN

- TYPE_RETURN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURN"
  - : Constant for Invoice Type Return.
      
      The invoice was created for a return.
      
      The invoice amount needs to be refunded.



---

### TYPE_RETURN_CASE

- TYPE_RETURN_CASE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURN_CASE"
  - : Constant for Invoice Type Return Case.
      
      The invoice was created for a return case.
      
      The invoice amount needs to be refunded.



---

### TYPE_SHIPPING

- TYPE_SHIPPING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPING"
  - : Constant for Invoice Type Shipping.
      
      The invoice was created for a shipping order.
      
      The invoice amount needs to be captured.



---

## Property Details

### capturedAmount
- capturedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of the captured amounts. The captured amounts are
      calculated on the fly.
      
      Associate a payment capture for a [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
      with an Invoice using
      [addCaptureTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addcapturetransactionorderpaymentinstrument-money).



---

### invoiceNumber
- invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the invoice number.


---

### items
- items: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Access the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with  [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with      [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with        [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with          [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_serviceitems)



---

### paymentTransactions
- paymentTransactions: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the payment transactions belonging to this Invoice.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with  [ORDERBY_CREATION_DATE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_creation_date)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_unsorted)    - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with      [QUALIFIER_CAPTURE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_capture)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with        [QUALIFIER_REFUND](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_refund)


    **See Also:**
    - [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)


---

### refundedAmount
- refundedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of the refunded amounts. The refunded amounts are
      calculated on the fly.
      
      Associate a payment capture for a [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
      with an Invoice using
      [addRefundTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addrefundtransactionorderpaymentinstrument-money).



---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the invoice status.
      
      The possible values are [STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), [STATUS_MANUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_manual),
      [STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid), [STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed).



---

### type
- type: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : Returns the invoice type.
      
      The possible values are [TYPE_SHIPPING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_shipping), [TYPE_RETURN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return),
      [TYPE_RETURN_CASE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return_case), [TYPE_APPEASEMENT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_appeasement).



---

## Method Details

### account()
- account(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : 
      
      The invoice will be accounted.
      
      
      
      
      It will be captured in case of a shipping invoice and it will be refunded in
      case of an appeasement, return case or return invoice.
      
      
      
      
      
      The accounting will be handled in the payment hooks
      [PaymentHooks.capture(Invoice)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#captureinvoice) or
      [PaymentHooks.refund(Invoice)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#refundinvoice). The implementing script could add
      payment transactions to the invoice. The accompanying business logic will
      set the status to `PAID` or `FAILED`.
      
      
      
      
      The accounting will fail when the invoice state is different to
      [STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid) or [STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed).
      
      
      
      
      The method implements its own transaction handling. The method must not
      be called inside a transaction.


    **Returns:**
    - `true` when the accounting was successful, otherwise
              `false`.



---

### addCaptureTransaction(OrderPaymentInstrument, Money)
- addCaptureTransaction(instrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), capturedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)
  - : Calling this method registers an amount captured for a given
      order payment instrument. The authorization for the
      capture is associated with the payment transaction belonging to the
      instrument. Calling this method allows the Invoice, the
      [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md) and the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) to
      return their captured amount as a sum calculated on the fly. The method
      may be called multiple times for the same instrument (multiple capture
      for one authorization) or for different instruments (invoice settlement
      using multiple payments).


    **Parameters:**
    - instrument - the order payment instrument
    - capturedAmount - amount to register as captured

    **Returns:**
    - the created capture transaction


---

### addRefundTransaction(OrderPaymentInstrument, Money)
- addRefundTransaction(instrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), refundedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)
  - : Calling this method registers an amount refunded for a given
      order payment instrument. Calling this method allows the
      Invoice, the [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md) and
      the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) to return their refunded amount as a sum
      calculated on the fly. The method may be called multiple times for the
      same instrument (multiple refunds of one payment) or for different
      instruments (invoice settlement using multiple payments).


    **Parameters:**
    - instrument - the order payment instrument
    - refundedAmount - amount to register as refunded

    **Returns:**
    - the created refund transaction


---

### getCapturedAmount()
- getCapturedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of the captured amounts. The captured amounts are
      calculated on the fly.
      
      Associate a payment capture for a [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
      with an Invoice using
      [addCaptureTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addcapturetransactionorderpaymentinstrument-money).


    **Returns:**
    - sum of captured amounts


---

### getInvoiceNumber()
- getInvoiceNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the invoice number.

    **Returns:**
    - the invoice number


---

### getItems()
- getItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Access the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with  [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with      [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with        [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with          [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_serviceitems)


    **Returns:**
    - the invoice items


---

### getPaymentTransactions()
- getPaymentTransactions(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the payment transactions belonging to this Invoice.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with  [ORDERBY_CREATION_DATE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_creation_date)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#orderby_unsorted)    - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with      [QUALIFIER_CAPTURE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_capture)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with        [QUALIFIER_REFUND](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#qualifier_refund)


    **Returns:**
    - the payment transactions.

    **See Also:**
    - [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)


---

### getRefundedAmount()
- getRefundedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of the refunded amounts. The refunded amounts are
      calculated on the fly.
      
      Associate a payment capture for a [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
      with an Invoice using
      [addRefundTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addrefundtransactionorderpaymentinstrument-money).


    **Returns:**
    - sum of refunded amounts


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the invoice status.
      
      The possible values are [STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), [STATUS_MANUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_manual),
      [STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid), [STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed).


    **Returns:**
    - the invoice status


---

### getType()
- getType(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the invoice type.
      
      The possible values are [TYPE_SHIPPING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_shipping), [TYPE_RETURN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return),
      [TYPE_RETURN_CASE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_return_case), [TYPE_APPEASEMENT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#type_appeasement).


    **Returns:**
    - the invoice type


---

### setStatus(String)
- setStatus(status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the invoice status.
      
      The possible values are [STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), [STATUS_MANUAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_manual),
      [STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid), [STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed).


    **Parameters:**
    - status - the invoice status to set


---

<!-- prettier-ignore-end -->

<!-- document id=d7d8b8208bf589146975e103ad4ec1366a96715bf9da3861ee9ffcc772bdd682 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.InvoiceItem.md -->

<!-- prettier-ignore-start -->
# Class InvoiceItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md)
      - [dw.order.InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)

Represents a specific item in an [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). Invoice items are added to the invoice
on its creation, each item references exactly one order-item.


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Property Summary

| Property | Description |
| --- | --- |
| [basePrice](#baseprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Price of a single unit before discount application. |
| [capturedAmount](#capturedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the captured amount for this item. |
| [invoiceNumber](#invoicenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the number of the invoice to which this item belongs. |
| [parentItem](#parentitem): [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md) | Returns null or the parent item. |
| [quantity](#quantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity of this item. |
| [refundedAmount](#refundedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the refunded amount for this item. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#getbaseprice)() | Price of a single unit before discount application. |
| [getCapturedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#getcapturedamount)() | Returns the captured amount for this item. |
| [getInvoiceNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#getinvoicenumber)() | Returns the number of the invoice to which this item belongs. |
| [getParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#getparentitem)() | Returns null or the parent item. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#getquantity)() | Returns the quantity of this item. |
| [getRefundedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#getrefundedamount)() | Returns the refunded amount for this item. |
| [setCapturedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#setcapturedamountmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Updates the captured amount for this item. |
| [setParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#setparentiteminvoiceitem)([InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)) | Set a parent item. |
| [setRefundedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md#setrefundedamountmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Updates the refunded amount for this item. |

### Methods inherited from class AbstractItem

[getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice), [getItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getitemid), [getLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getlineitem), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice), [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitem), [getOrderItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitemid), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis), [getTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxitems)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### basePrice
- basePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Price of a single unit before discount application.


---

### capturedAmount
- capturedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the captured amount for this item.


---

### invoiceNumber
- invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the number of the invoice to which this item belongs.


---

### parentItem
- parentItem: [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)
  - : Returns null or the parent item.


---

### quantity
- quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity of this item.


---

### refundedAmount
- refundedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the refunded amount for this item.


---

## Method Details

### getBasePrice()
- getBasePrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Price of a single unit before discount application.

    **Returns:**
    - Price of a single unit before discount application.


---

### getCapturedAmount()
- getCapturedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the captured amount for this item.

    **Returns:**
    - the captured amount for this item


---

### getInvoiceNumber()
- getInvoiceNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the number of the invoice to which this item belongs.

    **Returns:**
    - the number of the invoice to which this item belongs


---

### getParentItem()
- getParentItem(): [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)
  - : Returns null or the parent item.

    **Returns:**
    - null or the parent item.


---

### getQuantity()
- getQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of this item.

    **Returns:**
    - quantity of this item


---

### getRefundedAmount()
- getRefundedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the refunded amount for this item.

    **Returns:**
    - the refunded amount for this item


---

### setCapturedAmount(Money)
- setCapturedAmount(capturedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Updates the captured amount for this item.

    **Parameters:**
    - capturedAmount - the captured amount for this item


---

### setParentItem(InvoiceItem)
- setParentItem(parentItem: [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)): void
  - : Set a parent item. The parent item must belong to the same
      [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). An infinite parent-child loop is disallowed
      as is a parent-child depth greater than 10. Setting a parent item
      indicates a dependency of the child item on the parent item, and can be
      used to form a parallel structure to that accessed using
      [ProductLineItem.getParent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getparent).


    **Parameters:**
    - parentItem - The parent item, null is allowed


---

### setRefundedAmount(Money)
- setRefundedAmount(refundedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Updates the refunded amount for this item.

    **Parameters:**
    - refundedAmount - the refunded amount for this item


---

<!-- prettier-ignore-end -->

<!-- document id=9165e4d813802365045212fc8650eee8f188ccc1f37fa114383084102016004e url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.IOError.md -->

<!-- prettier-ignore-start -->
# Class IOError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.IOError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.IOError.md)

This error indicates an I/O related error in the system. The IOError
is always related to a systems internal Java exception. The class provides
access to some more details about this internal Java exception.



## Property Summary

| Property | Description |
| --- | --- |
| [causeFullName](#causefullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the full name of the associated Java exception. |
| [causeMessage](#causemessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the message of the associated Java exception. |
| [causeName](#causename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the simplified name of the associated Java exception. |
| [javaFullName](#javafullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The full name of the underlying Java exception. |
| [javaMessage](#javamessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The message of the underlying Java exception. |
| [javaName](#javaname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The simplified name of the underlying Java exception. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [IOError](#ioerror)() |  |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### causeFullName
- causeFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the full name of the associated Java exception.



---

### causeMessage
- causeMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the message of the associated Java exception.



---

### causeName
- causeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the simplified name of the associated Java exception.



---

### javaFullName
- javaFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The full name of the underlying Java exception.


---

### javaMessage
- javaMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The message of the underlying Java exception.


---

### javaName
- javaName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The simplified name of the underlying Java exception.


---

## Constructor Details

### IOError()
- IOError()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=9e2c3e84d09687df7b67f653648dc8c0cbf2f0aeb4160d5973a3dadfe34ab5cf url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.template.ISML.md -->

<!-- prettier-ignore-start -->
# Class ISML

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.template.ISML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.ISML.md)

This class provides support for rendering ISML templates. For more details about the ISML syntax, refer to the
Commerce Cloud Digital developer documentation. Templates are stored as \*.isml files. They are located in a
locale-specific folder under the '/cartridge/templates' folder, with '/cartridge/template/default' being the default
locale. The template name arguments of the various render methods represent the template path (without file ending)
within this folder structure.


Example for rendering a template with arguments from JavaScript code:


```
let isml = require('dw/template/ISML');
isml.renderTemplate('helloworld', {
    Message: 'Hello, World!'
});
```


Example code for accessing the template arguments in the 'helloworld.isml' template from the above code snippet:


```
The message is: <isprint value="${pdict.Message}" />
```



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.ISML.md#rendertemplatestring---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Renders an ISML template and writes the output to the current response. |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.ISML.md#rendertemplatestring-object---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Renders an ISML template and writes the output to the current response. |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.ISML.md#rendertemplatestring---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Renders an ISML template and writes the output to the current response. |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.ISML.md#rendertemplatestring-object---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Renders an ISML template and writes the output to the current response. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### renderTemplate(String) - Variant 1
- static renderTemplate(template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Renders an ISML template and writes the output to the current response. The template may contain ISML tags which
      control the character encoding, content type, caching behavior and so on of the response (see ISML
      documentation).


    **Parameters:**
    - template - the template path

    **API Version:**
**note:** No longer available as of version 17.7.
Puts template arguments into the global pipeline dictionary.

---

### renderTemplate(String, Object) - Variant 1
- static renderTemplate(template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), templateArgs: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Renders an ISML template and writes the output to the current response. The template may contain ISML tags which
      control the character encoding, content type, caching behavior and so on of the response (see ISML
      documentation). This method takes an additional JavaScript object as argument. Its properties are accessible for
      script expressions in the template under the "pdict.\*" variable.


    **Parameters:**
    - template - the template path
    - templateArgs - the template arguments object

    **API Version:**
**note:** No longer available as of version 17.7.
Puts template arguments into the global pipeline dictionary.

---

### renderTemplate(String) - Variant 2
- static renderTemplate(template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Renders an ISML template and writes the output to the current response. The template may contain ISML tags which
      control the character encoding, content type, caching behavior and so on of the response (see ISML
      documentation).


    **Parameters:**
    - template - the template path

    **API Version:**
**note:** Available from version 17.7.
Keeps template arguments in a local pipeline dictionary scope. This avoids side-effects on other templates.

---

### renderTemplate(String, Object) - Variant 2
- static renderTemplate(template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), templateArgs: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Renders an ISML template and writes the output to the current response. The template may contain ISML tags which
      control the character encoding, content type, caching behavior and so on of the response (see ISML
      documentation). This method takes an additional JavaScript object as argument. Its properties are accessible for
      script expressions in the template under the "pdict.\*" variable.


    **Parameters:**
    - template - the template path
    - templateArgs - the template arguments object

    **API Version:**
**note:** Available from version 17.7.
Keeps template arguments in a local pipeline dictionary scope. This avoids side-effects on other templates.

---

<!-- prettier-ignore-end -->

<!-- document id=338600ad8a9fcdb1c2dd00a8c60043ee38abdd91691dd78bf9991bf5e93d46ec url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Iterable.md -->

<!-- prettier-ignore-start -->
# Class Iterable

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)

All objects containing the property @@iterator with a function returning an [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md) are said to be an Iterable.

**API Version:**
**note:** Available from version 21.2.

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md#iterator)() | Returns an iterator to be used for iterating this object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### iterator()
- iterator(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator to be used for iterating this object. Typically returns a new iterator instance.
      For iterators returns typically the iterator itself.


    **Returns:**
    - The iterator to be used for iterating this object.

    **API Version:**
**note:** Available from version 21.2.

---

<!-- prettier-ignore-end -->

<!-- document id=262b0062cbd1b5997ec2b022c679225c4abc5c9a08fcbfeddf6348425eda366c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Iterator.md -->

<!-- prettier-ignore-start -->
# Class Iterator

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)

The Iterator class allows you to access items in a collection.


## All Known Subclasses
[LoopIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md), [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [asList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#aslist)() | Convert the iterator into a list. |
| [asList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#aslistnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Converts a sub-sequence within the iterator into a list. |
| [hasNext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#hasnext)() | Indicates if there are more elements. |
| [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#next)() | Returns the next element from the Iterator. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### asList()
- asList(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Convert the iterator into a list. After this conversion the
      iterator is empty and hasNext() will always return false.
      
      Note: This method should be used with care. For example a large database
      result is pulled into memory completely with this method and can cause
      an OutOfMemory situation.


    **Returns:**
    - the iterator as a list.


---

### asList(Number, Number)
- asList(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Converts a sub-sequence within the iterator into a list.
      
      Note: This method should be used with care. For example a large database
      result is pulled into memory completely with this method and can cause
      an OutOfMemory situation.


    **Parameters:**
    - start - the number of elements to iterate before adding elements to             the sublist. Negative values are treated as 0.
    - size - the maximum number of elements to add to the sublist.             Nonpositive values always result in empty list.

    **Returns:**
    - a sub-sequence within the iterator into a list.


---

### hasNext()
- hasNext(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if there are more elements.

    **Returns:**
    - true if there are more elements,
      false otherwise.



---

### next()
- next(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the next element from the Iterator.

    **Returns:**
    - the next element from the Iterator.


---

<!-- prettier-ignore-end -->

<!-- document id=06ba4f400a2c1542ff93301b527be2b98521abfee7603a001b86001f7948ad04 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Iterator.md -->

<!-- prettier-ignore-start -->
# Class Iterator

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterator.md)

An Iterator is a special object that lets you access items from a 
collection one at a time, while keeping track of its current position 
within that sequence.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Iterator](#iteratorobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an Iterator instance for the specified object. |
| [Iterator](#iteratorobject-boolean)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Creates an Iterator instance for the specified object's keys. |

## Method Summary

| Method | Description |
| --- | --- |
| [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterator.md#next)() | Returns the next item in the iterator. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### Iterator(Object)
- Iterator(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an Iterator instance for the specified object.
      The Iterator for the object is created by calling the 
      object's \_\_iterator\_\_ method. If there is no \_\_iterator\_\_ method, 
      a default iterator is created. The default iterator provides access to 
      the object's properties, according to the usual for...in and for 
      each...in model. 
      
      If you want to provide a custom iterator, you should override 
      the \_\_iterator\_\_ method to return an instance of your custom iterator.


    **Parameters:**
    - object - the object whose values will be accessible via the   Iterator.


---

### Iterator(Object, Boolean)
- Iterator(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), keysOnly: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))
  - : Creates an Iterator instance for the specified object's keys.
      The Iterator for the object is created by calling the 
      object's \_\_iterator\_\_ method. If there is no \_\_iterator\_\_ method, 
      a default iterator is created. The default iterator provides access to 
      the object's properties, according to the usual for...in and for 
      each...in model. 
      
      If you want to provide a custom iterator, you should override 
      the \_\_iterator\_\_ method to return an instance of your custom iterator.


    **Parameters:**
    - object - the object whose keys or values will be accessible   via the Iterator.
    - keysOnly - if true, provides access to the object's keys. If false,   provides access to the object's values.


---

## Method Details

### next()
- next(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the next item in the iterator. If there are no items left, 
      the StopIteration exception is thrown. You should generally use this method 
      in the context of a try...catch block to handle the StopIteration case.
      There is no guaranteed ordering of the data.


    **Returns:**
    - the next item in the iterator.

    **See Also:**
    - [StopIteration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.StopIteration.md)


---

<!-- prettier-ignore-end -->

<!-- document id=322492620bc1b778a9de2f8e23643519266b0728bcf6a480e7c6ecea87bd32fc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.job.JobExecution.md -->

<!-- prettier-ignore-start -->
# Class JobExecution

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.job.JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md)

Represents an execution of a job. The job execution can be accessed from a [JobStepExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md) via
[JobStepExecution.getJobExecution()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md#getjobexecution). If a pipeline is used to implement a step the step execution is available
in the pipeline dictionary under the key 'JobStepExecution'. If a script module is used to implement a step the step
execution is available as the second parameter of the module's function that is used to execute the step, e.g.:


```
...
exports.execute( parameters, stepExecution)
{
     ...
     var jobExecution = stepExecution.getJobExecution();
     ...
}
...
```



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of this job execution. |
| [context](#context): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the job context which can be used to share data between steps. |
| [jobID](#jobid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the job this job execution belongs to. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md#getcontext)() | Returns the job context which can be used to share data between steps. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md#getid)() | Returns the ID of this job execution. |
| [getJobID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md#getjobid)() | Returns the ID of the job this job execution belongs to. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of this job execution.


---

### context
- context: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the job context which can be used to share data between steps. NOTE: Steps should be self-contained, the
      job context should only be used when necessary and with caution. If two steps which are running in parallel in
      the same job store data in the job context using the same key the result is undefined. Don't add any complex data
      to the job context since only simple data types are supported (for example, String and Integer).



---

### jobID
- jobID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the job this job execution belongs to.


---

## Method Details

### getContext()
- getContext(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the job context which can be used to share data between steps. NOTE: Steps should be self-contained, the
      job context should only be used when necessary and with caution. If two steps which are running in parallel in
      the same job store data in the job context using the same key the result is undefined. Don't add any complex data
      to the job context since only simple data types are supported (for example, String and Integer).


    **Returns:**
    - the map that represents the job context.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of this job execution.

    **Returns:**
    - the ID of this job execution.


---

### getJobID()
- getJobID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the job this job execution belongs to.

    **Returns:**
    - the ID of the job this job execution belongs to.


---

<!-- prettier-ignore-end -->

<!-- document id=f63b0a9bc78acb875495ef3a9197ac99ba6113075ad887b8c6f3aa9816990295 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.JobProcessMonitor.md -->

<!-- prettier-ignore-start -->
# Class JobProcessMonitor

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.JobProcessMonitor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.JobProcessMonitor.md)

**_Reserved for future use_**.


## Property Summary

| Property | Description |
| --- | --- |
| [totalWork](#totalwork): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | **_Reserved for future use_**. |
| [workMessage](#workmessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | **_Reserved for future use_**. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getTotalWork](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.JobProcessMonitor.md#gettotalwork)() | **_Reserved for future use_**. |
| [getWorkMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.JobProcessMonitor.md#getworkmessage)() | **_Reserved for future use_**. |
| [setTotalWork](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.JobProcessMonitor.md#settotalworknumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | **_Reserved for future use_**. |
| [setWorkMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.JobProcessMonitor.md#setworkmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | **_Reserved for future use_**. |
| [worked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.JobProcessMonitor.md#workednumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | **_Reserved for future use_**. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### totalWork
- totalWork: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : **_Reserved for future use_**. Gets the total work count.


---

### workMessage
- workMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : **_Reserved for future use_**. Gets the work message.


---

## Method Details

### getTotalWork()
- getTotalWork(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : **_Reserved for future use_**. Gets the total work count.

    **Returns:**
    - the total work count.


---

### getWorkMessage()
- getWorkMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : **_Reserved for future use_**. Gets the work message.

    **Returns:**
    - the work message.


---

### setTotalWork(Number)
- setTotalWork(totalWork: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : **_Reserved for future use_**. Sets the total work count.

    **Parameters:**
    - totalWork - the total work count.


---

### setWorkMessage(String)
- setWorkMessage(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : **_Reserved for future use_**. Sets the work message.

    **Parameters:**
    - msg - the messageto use. If msg is null, then an empty string will  be used.


---

### worked(Number)
- worked(worked: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : **_Reserved for future use_**. Increments the count of work items by the value of the specified
      parameter.


    **Parameters:**
    - worked - the number of items worked.


---

<!-- prettier-ignore-end -->

<!-- document id=656de6b56618c81fb05a2066aa2995febaaf00f6fe0abef242d9f268e5a780db url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.job.JobStepExecution.md -->

<!-- prettier-ignore-start -->
# Class JobStepExecution

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.job.JobStepExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md)

Represents an execution of a step that belongs to a job. The job execution this step execution belongs to can be
accessed via [getJobExecution()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md#getjobexecution). If a pipeline is used to implement a step this step execution is available
in the pipeline dictionary under the key 'JobStepExecution'. If a script module is used to implement a step this step
execution is available as the second parameter of the module's function that is used to execute the step, e.g.:


```
...
exports.execute( parameters, stepExecution)
{
     ...
     var jobExecution = stepExecution.getJobExecution();
     ...
}
...
```



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of this step execution. |
| [jobExecution](#jobexecution): [JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md) `(read-only)` | Returns the job execution this step execution belongs to. |
| [stepID](#stepid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the step this step execution belongs to. |
| [stepTypeID](#steptypeid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the step type of the step this step execution belongs to. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md#getid)() | Returns the ID of this step execution. |
| [getJobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md#getjobexecution)() | Returns the job execution this step execution belongs to. |
| [getParameterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md#getparametervaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the value of the parameter of the step this step execution belongs to. |
| [getStepID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md#getstepid)() | Returns the ID of the step this step execution belongs to. |
| [getStepTypeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md#getsteptypeid)() | Returns the ID of the step type of the step this step execution belongs to. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of this step execution.


---

### jobExecution
- jobExecution: [JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md) `(read-only)`
  - : Returns the job execution this step execution belongs to.


---

### stepID
- stepID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the step this step execution belongs to.


---

### stepTypeID
- stepTypeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the step type of the step this step execution belongs to.


---

## Method Details

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of this step execution.

    **Returns:**
    - the ID of this step execution.


---

### getJobExecution()
- getJobExecution(): [JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md)
  - : Returns the job execution this step execution belongs to.

    **Returns:**
    - the job execution this step execution belongs to.


---

### getParameterValue(String)
- getParameterValue(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value of the parameter of the step this step execution belongs to.

    **Parameters:**
    - name - The name of the parameter.

    **Returns:**
    - the value of the parameter of the step this step execution belongs to.


---

### getStepID()
- getStepID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the step this step execution belongs to.

    **Returns:**
    - the ID of the step this step execution belongs to.


---

### getStepTypeID()
- getStepTypeID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the step type of the step this step execution belongs to.

    **Returns:**
    - the ID of the step type of the step this step execution belongs to.


---

<!-- prettier-ignore-end -->

<!-- document id=2a78d94332f7358a44e729d6894670b2d186d1654e7f149cddb30c36b3c67370 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.JSON.md -->

<!-- prettier-ignore-start -->
# Class JSON

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.JSON](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md)

The JSON object is a single object that contains two functions, parse and stringify,
that are used to parse and construct JSON texts. The JSON Data Interchange Format is
described in RFC 4627.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [JSON](#json)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#parsestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The parse function parses a JSON text (a JSON formatted string) and produces an ECMAScript  value. |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#parsestring-function)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | The parse function parses a JSON text (a JSON formatted string) and produces an ECMAScript  value. |
| static [stringify](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#stringifyobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The stringify function produces a JSON formatted string that captures information  from a JavaScript value. |
| static [stringify](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#stringifyobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The stringify function produces a JSON formatted string that captures information  from a JavaScript value. |
| static [stringify](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#stringifyobject-object-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The stringify function produces a JSON formatted string that captures information  from a JavaScript value. |
| static [stringify](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#stringifyobject-object-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | The stringify function produces a JSON formatted string that captures information  from a JavaScript value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### JSON()
- JSON()
  - : 


---

## Method Details

### parse(String)
- static parse(json: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : The parse function parses a JSON text (a JSON formatted string) and produces an ECMAScript
      value. The JSON format is a restricted form of ECMAScript literal. JSON objects are realized
      as ECMAScript objects. JSON Arrays are realized as ECMAScript arrays. JSON strings, numbers,
      booleans, and null are realized as ECMAScript strings, numbers, booleans, and null.


    **Parameters:**
    - json - a JSON formatted string

    **Returns:**
    - the object produced from the JSON string


---

### parse(String, Function)
- static parse(json: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), reviver: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : The parse function parses a JSON text (a JSON formatted string) and produces an ECMAScript
      value. The JSON format is a restricted form of ECMAScript literal. JSON objects are realized
      as ECMAScript objects. JSON Arrays are realized as ECMAScript arrays. JSON strings, numbers,
      booleans, and null are realized as ECMAScript strings, numbers, booleans, and null.
      
      The optional reviver parameter is a function that takes two parameters, (key, value). It can
      filter and transform the results. It is called with each of the key/value pairs produced by the
      parse, and its return value is used instead of the original value. If it returns what it
      received, the structure is not modified. If it returns undefined then the member is deleted
      from the result.


    **Parameters:**
    - json - a JSON formatted string
    - reviver - a function, which is called with each key, value pair during parsing

    **Returns:**
    - the object produced from the JSON string


---

### stringify(Object)
- static stringify(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The stringify function produces a JSON formatted string that captures information
      from a JavaScript value. The value parameter is a JavaScript value is usually an
      object or array, although it can also be a string, boolean, number or null.
      
      Note: Stringifying API objects is not supported.


    **Parameters:**
    - value - the value which is stringified

    **Returns:**
    - the JSON string


---

### stringify(Object, Object)
- static stringify(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), replacer: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The stringify function produces a JSON formatted string that captures information
      from a JavaScript value. The value parameter is a JavaScript value is usually an
      object or array, although it can also be a string, boolean, number or null. The
      optional replacer parameter is either a function that alters the way objects and
      arrays are stringified, or an array of strings that acts as an allowlist for selecting
      the keys that will be stringified.
      
      Note: Stringifying API objects is not supported.


    **Parameters:**
    - value - the value which is stringified
    - replacer - either a function, which is called with a key and value as parameter, or an array with an allowlist

    **Returns:**
    - the JSON string


---

### stringify(Object, Object, String)
- static stringify(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), replacer: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), space: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The stringify function produces a JSON formatted string that captures information
      from a JavaScript value. The value parameter is a JavaScript value is usually an
      object or array, although it can also be a string, boolean, number or null. The
      optional replacer parameter is either a function that alters the way objects and
      arrays are stringified, or an array of strings that acts as an allowlist for selecting
      the keys that will be stringified. The optional space parameter is a string or number
      that allows the result to have white space injected into it to improve human readability.
      
      Note: Stringifying API objects is not supported.


    **Parameters:**
    - value - the value which is stringified
    - replacer - either a function, which is called with a key and value as parameter, or an array with an allowlist
    - space - a string for indentation

    **Returns:**
    - the JSON string


---

### stringify(Object, Object, Number)
- static stringify(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), replacer: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), space: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The stringify function produces a JSON formatted string that captures information
      from a JavaScript value. The value parameter is a JavaScript value is usually an
      object or array, although it can also be a string, boolean, number or null. The
      optional replacer parameter is either a function that alters the way objects and
      arrays are stringified, or an array of strings that acts as an allowlist for selecting
      the keys that will be stringified. The optional space parameter is a string or number
      that allows the result to have white space injected into it to improve human readability.
      
      Note: Stringifying API objects is not supported.


    **Parameters:**
    - value - the value which is stringified
    - replacer - either a function, which is called with a key and value as parameter, or an array with an allowlist
    - space - the number of space for indenting

    **Returns:**
    - the JSON string


---

<!-- prettier-ignore-end -->

<!-- document id=212306918c900b86ca8da4cd0cf5b8d3e0c355761054a82ed1da57489d5c0157 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.JWE.md -->

<!-- prettier-ignore-start -->
# Class JWE

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.JWE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md)

This class represents a JSON Web Encryption (JWE) object.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3 requirements 2, 4, and 12.



## Property Summary

| Property | Description |
| --- | --- |
| [algorithm](#algorithm): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the algorithm (`alg`) from the header. |
| [encryptionMethod](#encryptionmethod): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the encryption method (`enc`) from the header. |
| [headerMap](#headermap): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Get a copy of the JWE headers as a Map. |
| [keyID](#keyid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the key id (`kid`) from the header. |
| [payload](#payload): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the decrypted payload. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [JWE](#jwejweheader-string)([JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a new JWE for encryption. |
| [JWE](#jwejweheader-bytes)([JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Construct a new JWE for encryption. |

## Method Summary

| Method | Description |
| --- | --- |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#decryptkeyref)([KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)) | Decrypt the payload of this JWE object. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#encryptcertificateref)([CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)) | Encrypt the payload of this JWE object. |
| [getAlgorithm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#getalgorithm)() | Get the algorithm (`alg`) from the header. |
| [getEncryptionMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#getencryptionmethod)() | Get the encryption method (`enc`) from the header. |
| [getHeaderMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#getheadermap)() | Get a copy of the JWE headers as a Map. |
| [getKeyID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#getkeyid)() | Get the key id (`kid`) from the header. |
| [getPayload](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#getpayload)() | Get the decrypted payload. |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#parsestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse a JSON Web Encryption (JWE) object from its compact serialization format. |
| [serialize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#serialize)() | Get this JWE in compact serialization form. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### algorithm
- algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the algorithm (`alg`) from the header.


---

### encryptionMethod
- encryptionMethod: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the encryption method (`enc`) from the header.


---

### headerMap
- headerMap: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Get a copy of the JWE headers as a Map.


---

### keyID
- keyID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the key id (`kid`) from the header.


---

### payload
- payload: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the decrypted payload.


---

## Constructor Details

### JWE(JWEHeader, String)
- JWE(header: [JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md), payload: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a new JWE for encryption.

    **Parameters:**
    - header - JWE header. This must include a valid algorithm (`alg`) and encryption method (`enc`). See      [decrypt(KeyRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#decryptkeyref) for a list of supported algorithms.
    - payload - Content that will be encrypted.


---

### JWE(JWEHeader, Bytes)
- JWE(header: [JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md), payload: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md))
  - : Construct a new JWE for encryption.

    **Parameters:**
    - header - JWE header. This must include a valid algorithm (`alg`) and encryption method      (`enc`). See [decrypt(KeyRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#decryptkeyref) for a list of supported algorithms.
    - payload - Content that will be encrypted.


---

## Method Details

### decrypt(KeyRef)
- decrypt(privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)): void
  - : Decrypt the payload of this JWE object.
      
      
      Elliptic Curve (EC) and RSA keys are both supported.
      
      
      Supported EC key management algorithms:
      
      - ECDH-ES
      - ECDH-ES+A128KW
      - ECDH-ES+A192KW
      - ECDH-ES+A256KW
      
      Supported EC curves:
      
      - P-256
      - P-384
      - P-521
      
      Supported RSA key management algorithms:
      
      - RSA-OAEP-256
      - RSA-OAEP-384
      - RSA-OAEP-512
      
      Supported content encryption algorithms:
      
      - A128CBC-HS256
      - A128CBC-HS384
      - A128CBC-HS512
      - A128GCM
      - A192GCM
      - A256GCM


    **Parameters:**
    - privateKey - Reference to private `RSA` or `EC` key to use for decryption.


---

### encrypt(CertificateRef)
- encrypt(publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)): void
  - : Encrypt the payload of this JWE object.
      
      
      Elliptic Curve (EC) and RSA keys are both supported.
      
      
      See [decrypt(KeyRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#decryptkeyref) for the list of supported algorithms and encryption methods.


    **Parameters:**
    - publicKey - Reference to public `RSA` or `EC` key to use for decryption.


---

### getAlgorithm()
- getAlgorithm(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the algorithm (`alg`) from the header.

    **Returns:**
    - Value of the algorithm or null if missing.


---

### getEncryptionMethod()
- getEncryptionMethod(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the encryption method (`enc`) from the header.

    **Returns:**
    - Value of the encryption method or null if missing.


---

### getHeaderMap()
- getHeaderMap(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Get a copy of the JWE headers as a Map.

    **Returns:**
    - Copy of the JWE headers.


---

### getKeyID()
- getKeyID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the key id (`kid`) from the header.

    **Returns:**
    - Value of the key id or null if missing.


---

### getPayload()
- getPayload(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the decrypted payload.

    **Returns:**
    - Payload or null if the payload is encrypted.


---

### parse(String)
- static parse(jwe: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [JWE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md)
  - : Parse a JSON Web Encryption (JWE) object from its compact serialization format.

    **Parameters:**
    - jwe - JWE in compact serialization format.

    **Returns:**
    - JWE object.


---

### serialize()
- serialize(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get this JWE in compact serialization form.

    **Returns:**
    - Compact serialized object.


---

<!-- prettier-ignore-end -->

<!-- document id=3723e72e2d80598a42e65c18257f2e979e347b51cddca2bbbbf3f95c2da91a3e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.JWEHeader.md -->

<!-- prettier-ignore-start -->
# Class JWEHeader

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md)

This class represents an immutable header of a JWE (JSON Web Encryption) object.


## Property Summary

| Property | Description |
| --- | --- |
| [algorithm](#algorithm): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the value of the algorithm parameter (`alg`). |
| [encryptionAlgorithm](#encryptionalgorithm): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the value of the encryption algorithm parameter (`enc`). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAlgorithm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md#getalgorithm)() | Get the value of the algorithm parameter (`alg`). |
| [getEncryptionAlgorithm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md#getencryptionalgorithm)() | Get the value of the encryption algorithm parameter (`enc`). |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md#parseobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Convert the given Map or JavaScript object into a JWE header. |
| static [parseEncoded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md#parseencodedstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse the given string as a Base64URL-encoded JWE header. |
| static [parseJSON](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md#parsejsonstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse the given string as a JWE header. |
| [toMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md#tomap)() | Get a copy of these headers as a Map. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md#tostring)() | Get the content of the headers as a JSON String. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### algorithm
- algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the value of the algorithm parameter (`alg`).


---

### encryptionAlgorithm
- encryptionAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the value of the encryption algorithm parameter (`enc`).


---

## Method Details

### getAlgorithm()
- getAlgorithm(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the value of the algorithm parameter (`alg`).

    **Returns:**
    - Algorithm parameter from this header.


---

### getEncryptionAlgorithm()
- getEncryptionAlgorithm(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the value of the encryption algorithm parameter (`enc`).

    **Returns:**
    - Encryption algorithm parameter from this header.


---

### parse(Object)
- static parse(map: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md)
  - : Convert the given Map or JavaScript object into a JWE header.
      
      
      All keys correspond to JWE parameters. The algorithm (`alg`) and encryption method
      (`enc`) parameters are required. See [JWE.decrypt(KeyRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#decryptkeyref) for supported values.


    **Parameters:**
    - map - Map or object data to convert.

    **Returns:**
    - JWE Header.


---

### parseEncoded(String)
- static parseEncoded(base64encoded: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md)
  - : Parse the given string as a Base64URL-encoded JWE header.
      
      
      The algorithm (`alg`) and encryption method (`enc`) parameters are required. See
      [JWE.decrypt(KeyRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#decryptkeyref) for supported values.


    **Parameters:**
    - base64encoded - Base64URL string to parse.

    **Returns:**
    - JWE Header.


---

### parseJSON(String)
- static parseJSON(json: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md)
  - : Parse the given string as a JWE header.
      
      
      The algorithm (`alg`) and encryption method (`enc`) parameters are required. See
      [JWE.decrypt(KeyRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md#decryptkeyref) for supported values.


    **Parameters:**
    - json - JSON string to parse.

    **Returns:**
    - JWE Header.


---

### toMap()
- toMap(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Get a copy of these headers as a Map.

    **Returns:**
    - Copy of the JWE headers.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the content of the headers as a JSON String.

    **Returns:**
    - JSON String.


---

<!-- prettier-ignore-end -->

<!-- document id=8872b46d4dfe2473d95e3434115b0d4923201958e66ae64cff675f22546be003 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.JWS.md -->

<!-- prettier-ignore-start -->
# Class JWS

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.JWS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md)

This class represents a JSON Web Signature (JWS) object.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3 requirements 2, 4, and 12.



## Property Summary

| Property | Description |
| --- | --- |
| [algorithm](#algorithm): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the algorithm (`alg`) from the header. |
| [header](#header): [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md) `(read-only)` | Get a copy of the JWS header. |
| [headerMap](#headermap): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Get a copy of the JWS header as a Map. |
| [payload](#payload): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the payload from this object. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [JWS](#jwsjwsheader-string)([JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a new JWS for signing. |
| [JWS](#jwsjwsheader-bytes)([JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Construct a new JWS for signing. |

## Method Summary

| Method | Description |
| --- | --- |
| [getAlgorithm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#getalgorithm)() | Get the algorithm (`alg`) from the header. |
| [getHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#getheader)() | Get a copy of the JWS header. |
| [getHeaderMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#getheadermap)() | Get a copy of the JWS header as a Map. |
| [getPayload](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#getpayload)() | Get the payload from this object. |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#parsestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse a JSON Web Signature (JWS) object from its compact serialization format. |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#parsestring-bytes)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Parse a JSON Web Signature (JWS) object from its compact serialization format. |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#parsestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse a JSON Web Signature (JWS) object from its compact serialization format. |
| [serialize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#serializeboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Get this JWS in compact serialization form. |
| [sign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#signkeyref)([KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)) | Sign the payload using the given private key. |
| [verify](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#verifycertificateref)([CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)) | Verifies the signature of the payload. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### algorithm
- algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the algorithm (`alg`) from the header.


---

### header
- header: [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md) `(read-only)`
  - : Get a copy of the JWS header.


---

### headerMap
- headerMap: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Get a copy of the JWS header as a Map.


---

### payload
- payload: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the payload from this object.
      
      
      This is available even if the signature has not been verified.



---

## Constructor Details

### JWS(JWSHeader, String)
- JWS(header: [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md), payload: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a new JWS for signing.

    **Parameters:**
    - header - JWS header. This must include a valid algorithm (`alg`). See      [verify(CertificateRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#verifycertificateref) for a list of supported algorithms.
    - payload - Content that will be signed.


---

### JWS(JWSHeader, Bytes)
- JWS(header: [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md), payload: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md))
  - : Construct a new JWS for signing.

    **Parameters:**
    - header - JWS header. This must include a valid algorithm (`alg`). See      [verify(CertificateRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#verifycertificateref) for a list of supported algorithms.
    - payload - Content that will be signed.


---

## Method Details

### getAlgorithm()
- getAlgorithm(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the algorithm (`alg`) from the header.

    **Returns:**
    - Value of the algorithm or null if missing.


---

### getHeader()
- getHeader(): [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md)
  - : Get a copy of the JWS header.

    **Returns:**
    - Copy of the JWS header.


---

### getHeaderMap()
- getHeaderMap(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Get a copy of the JWS header as a Map.

    **Returns:**
    - Copy of the JWS header.


---

### getPayload()
- getPayload(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the payload from this object.
      
      
      This is available even if the signature has not been verified.


    **Returns:**
    - UTF-8 encoded payload.


---

### parse(String)
- static parse(jws: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [JWS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md)
  - : Parse a JSON Web Signature (JWS) object from its compact serialization format.

    **Parameters:**
    - jws - JWS in compact serialization format.

    **Returns:**
    - JWS object.


---

### parse(String, Bytes)
- static parse(jws: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), payload: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [JWS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md)
  - : Parse a JSON Web Signature (JWS) object from its compact serialization format.

    **Parameters:**
    - jws - JWS without a payload in compact serialization format.
    - payload - Detached payload

    **Returns:**
    - JWS object.


---

### parse(String, String)
- static parse(jws: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), payload: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [JWS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md)
  - : Parse a JSON Web Signature (JWS) object from its compact serialization format.

    **Parameters:**
    - jws - JWS without a payload in compact serialization format.
    - payload - Detached payload

    **Returns:**
    - JWS object.


---

### serialize(Boolean)
- serialize(detachPayload: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get this JWS in compact serialization form.

    **Parameters:**
    - detachPayload - true for a detached payload compliant with RFC-7797, or false to serialize the payload      too.

    **Returns:**
    - Compact serialized object.


---

### sign(KeyRef)
- sign(keyRef: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)): void
  - : Sign the payload using the given private key.
      
      
      The key type and size must match the algorithm given in the JWS header.


    **Parameters:**
    - keyRef - Reference to the private key.

    **Throws:**
    - Exception - if there is an error while signing the payload.


---

### verify(CertificateRef)
- verify(certificateRef: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies the signature of the payload.
      
      
      If the `x5c` header parameter is present, then that certificate chain will be used to verify the
      signature and the given `certificateRef` must be its root certificate. If this parameter is not
      present then the given `certificateRef` will be used to directly verify the signature.
      
      
      The following algorithms are supported:
      
      - ES256
      - ES256K
      - ES384
      - ES512
      - RS256
      - RS384
      - RS512
      - PS256
      - PS384
      - PS512


    **Parameters:**
    - certificateRef - Reference to the certificate to use for verification.

    **Returns:**
    - a boolean indicating success (true) or failure (false).

    **Throws:**
    - Exception - if there is an error while processing the certificate (for example if the `x5c`      is not signed by the given certificate) or the algorithm is unsupported.


---

<!-- prettier-ignore-end -->

<!-- document id=27e38bf2035e7c17e91f5966f5e54966e6c9ae267746ddc0ef3f2d0636cc0592 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.JWSHeader.md -->

<!-- prettier-ignore-start -->
# Class JWSHeader

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md)

This class represents an immutable header of a JWS (JSON Web Signature) object.


## Property Summary

| Property | Description |
| --- | --- |
| [algorithm](#algorithm): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the value of the algorithm parameter (`alg`). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAlgorithm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md#getalgorithm)() | Get the value of the algorithm parameter (`alg`). |
| static [parse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md#parseobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Convert the given Map or JavaScript object into a JWS header. |
| static [parseEncoded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md#parseencodedstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse the given string as a Base64URL-encoded JWS header. |
| static [parseJSON](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md#parsejsonstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parse the given string as a JWS header. |
| [toMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md#tomap)() | Get a copy of these headers as a Map. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md#tostring)() | Get the content of the headers as a JSON String. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### algorithm
- algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the value of the algorithm parameter (`alg`).


---

## Method Details

### getAlgorithm()
- getAlgorithm(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the value of the algorithm parameter (`alg`).

    **Returns:**
    - Algorithm parameter from this header.


---

### parse(Object)
- static parse(map: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md)
  - : Convert the given Map or JavaScript object into a JWS header.
      
      
      All keys correspond to JWS parameters. The algorithm parameter (`alg`) is required. See
      [JWS.verify(CertificateRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#verifycertificateref) for supported values.


    **Parameters:**
    - map - Map or object data to convert.

    **Returns:**
    - JWS Header.


---

### parseEncoded(String)
- static parseEncoded(base64encoded: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md)
  - : Parse the given string as a Base64URL-encoded JWS header.
      
      
      The algorithm parameter (`alg`) is required. See [JWS.verify(CertificateRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#verifycertificateref) for supported
      values.


    **Parameters:**
    - base64encoded - Base64URL string to parse.

    **Returns:**
    - JWS Header.


---

### parseJSON(String)
- static parseJSON(json: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md)
  - : Parse the given string as a JWS header.
      
      
      The algorithm parameter (`alg`) is required. See [JWS.verify(CertificateRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md#verifycertificateref) for supported
      values.


    **Parameters:**
    - json - JSON string to parse.

    **Returns:**
    - JWS Header.


---

### toMap()
- toMap(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Get a copy of these headers as a Map.

    **Returns:**
    - Copy of the JWS headers.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the content of the headers as a JSON String.

    **Returns:**
    - JSON String.


---

<!-- prettier-ignore-end -->

<!-- document id=cd382fa0adb0984dbb55431e340d4facabe1d13e2417822f024239d8669620af url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.KeyRef.md -->

<!-- prettier-ignore-start -->
# Class KeyRef

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)

This class is used as a reference to a private key in the keystore
which can be managed in the Business Manager.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [KeyRef](#keyrefstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a `KeyRef` from the passed alias. |
| ~~[KeyRef](#keyrefstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Creates a `KeyRef` from the passed alias. |

## Method Summary

| Method | Description |
| --- | --- |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md#tostring)() | Returns the string representation of this KeyRef. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### KeyRef(String)
- KeyRef(alias: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a `KeyRef` from the passed alias. No check
      is made whether the alias is actually referring to a key in the keystore,
      this check is made when the `KeyRef` is used.


    **Parameters:**
    - alias - an alias that should refer to a key in the keystore.


---

### KeyRef(String, String)
- ~~KeyRef(alias: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~
  - : Creates a `KeyRef` from the passed alias. No check
      is made whether the alias is actually referring to a key in the keystore,
      this check is made when the `KeyRef` is used.


    **Parameters:**
    - alias - an alias that should refer to a key in the keystore.
    - password - the password that should be used to get the key from the keystore.

    **Deprecated:**
**warning:** use [KeyRef(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md#keyrefstring) instead

---

## Method Details

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string representation of this KeyRef.

    **Returns:**
    - The string representation of this KeyRef.


---

<!-- prettier-ignore-end -->

<!-- document id=6be647db06f3f7bc51b1eb33046833a2ed516260e03931b2e2964a6804f6f69e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.Library.md -->

<!-- prettier-ignore-start -->
# Class Library

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.content.Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md)

Class representing a collection of [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) assets, and a
[Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) hierarchy organizing these content assets.
Currently only one library is allowed per site. An instance of this library
can be obtained by calling [ContentMgr.getSiteLibrary()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md#getsitelibrary).



## Property Summary

| Property | Description |
| --- | --- |
| [CMSChannelID](#cmschannelid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the CMS channel of the library. |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of this library. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name for the library as known in the current  locale or null if it cannot be found. |
| [root](#root): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)` | Returns the root folder for this library. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCMSChannelID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md#getcmschannelid)() | Returns the CMS channel of the library. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md#getdisplayname)() | Returns the display name for the library as known in the current  locale or null if it cannot be found. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md#getid)() | Returns the ID of this library. |
| [getRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md#getroot)() | Returns the root folder for this library. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### CMSChannelID
- CMSChannelID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the CMS channel of the library.


---

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of this library.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name for the library as known in the current
      locale or null if it cannot be found.



---

### root
- root: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)`
  - : Returns the root folder for this library.


---

## Method Details

### getCMSChannelID()
- getCMSChannelID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the CMS channel of the library.

    **Returns:**
    - the CMS channel of the library


---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name for the library as known in the current
      locale or null if it cannot be found.


    **Returns:**
    - the display name for the library as known in the current
      locale or null if it cannot be found.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of this library.

    **Returns:**
    - the ID of this library.


---

### getRoot()
- getRoot(): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the root folder for this library.

    **Returns:**
    - the root Folder for this library.


---

<!-- prettier-ignore-end -->

<!-- document id=fa64bf84e231b7ea2000255de85d434ec5645807ac3fa1a9b00e22834eb94195 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.LineItem.md -->

<!-- prettier-ignore-start -->
# Class LineItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)

Common line item base class.


## All Known Subclasses
[GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md), [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md), [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md), [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md), [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
## Property Summary

| Property | Description |
| --- | --- |
| [basePrice](#baseprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the base price for the line item, which is the price of the unit before applying adjustments, in the  purchase currency. |
| [grossPrice](#grossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the gross price for the line item, which is the price of the unit before applying adjustments, in the  purchase currency, including tax. |
| [lineItemCtnr](#lineitemctnr): [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md) `(read-only)` | Returns the line item ctnr of the line item. |
| [lineItemText](#lineitemtext): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the display text for the line item. |
| [netPrice](#netprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the net price for the line item, which is the price of the unit before applying adjustments, in the  purchase currency, excluding tax. |
| [price](#price): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Get the price of the line item. |
| [priceValue](#pricevalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Return the price amount for the line item. |
| [tax](#tax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the tax for the line item, which is the tax of the unit before applying adjustments, in the purchase  currency. |
| [taxBasis](#taxbasis): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Get the price used to calculate the tax for this line item. |
| [taxClassID](#taxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the tax class ID for the line item or null if no tax class ID is associated with the line item. |
| [taxRate](#taxrate): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the tax rate, which is the decimal tax rate to be applied to the product represented by this line item. |
| [taxes](#taxes): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) | Returns the tax items for this line item. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getbaseprice)() | Returns the base price for the line item, which is the price of the unit before applying adjustments, in the  purchase currency. |
| [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getgrossprice)() | Returns the gross price for the line item, which is the price of the unit before applying adjustments, in the  purchase currency, including tax. |
| [getLineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemctnr)() | Returns the line item ctnr of the line item. |
| [getLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemtext)() | Returns the display text for the line item. |
| [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getnetprice)() | Returns the net price for the line item, which is the price of the unit before applying adjustments, in the  purchase currency, excluding tax. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice)() | Get the price of the line item. |
| [getPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getpricevalue)() | Return the price amount for the line item. |
| [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettax)() | Returns the tax for the line item, which is the tax of the unit before applying adjustments, in the purchase  currency. |
| [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxbasis)() | Get the price used to calculate the tax for this line item. |
| [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxclassid)() | Returns the tax class ID for the line item or null if no tax class ID is associated with the line item. |
| [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxrate)() | Returns the tax rate, which is the decimal tax rate to be applied to the product represented by this line item. |
| [getTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes)() | Returns the tax items for this line item. |
| ~~[setBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setbasepricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md))~~ | Sets the base price for the line item, which is the price of the unit before applying adjustments, in the  purchase currency. |
| ~~[setGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setgrosspricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md))~~ | Sets the gross price for the line item, which is the Price of the unit before applying adjustments, in the  purchase currency, including tax. |
| [setLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setlineitemtextstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the display text for the line item. |
| ~~[setNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setnetpricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md))~~ | Sets the value for the net price, which is the price of the unit before applying adjustments, in the purchase  currency, excluding tax. |
| [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setpricevaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets price attributes of the line item based on the current purchase currency and taxation policy. |
| [setTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Sets the value for the tax of the line item, which is the the tax of the unit before applying adjustments, in the  purchase currency. |
| [setTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxclassidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the tax class ID for the line item. |
| [setTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxratenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the tax rate, which is the decimal tax rate to be applied to the product represented by this line item. |
| [setTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Sets the tax items for this line item. |
| ~~[updatePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md))~~ | Updates the price attributes of the line item based on the specified price. |
| [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Updates the tax-related attributes of the line item based on the specified tax rate, a tax basis determined by  the system and the "Tax Rounding Mode" order preference. |
| [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber-money)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Updates the tax-related attributes of the line item based on the specified tax rate, the passed tax basis and the  "Tax Rounding Mode" order preference. |
| [updateTaxAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxamountmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Updates tax amount of the line item setting the provided value. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### basePrice
- basePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the base price for the line item, which is the price of the unit before applying adjustments, in the
      purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.



---

### grossPrice
- grossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the gross price for the line item, which is the price of the unit before applying adjustments, in the
      purchase currency, including tax.



---

### lineItemCtnr
- lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md) `(read-only)`
  - : Returns the line item ctnr of the line item.


---

### lineItemText
- lineItemText: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display text for the line item.


---

### netPrice
- netPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the net price for the line item, which is the price of the unit before applying adjustments, in the
      purchase currency, excluding tax.



---

### price
- price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Get the price of the line item. If the line item is based on net pricing then the net price is returned. If the
      line item is based on gross pricing then the gross price is returned.



---

### priceValue
- priceValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the price amount for the line item. Same as getPrice().getValue().


---

### tax
- tax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax for the line item, which is the tax of the unit before applying adjustments, in the purchase
      currency.



---

### taxBasis
- taxBasis: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Get the price used to calculate the tax for this line item.


---

### taxClassID
- taxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tax class ID for the line item or null if no tax class ID is associated with the line item. In the
      case where the tax class ID is null, you should use the default tax class ID.


    **See Also:**
    - [TaxMgr.getDefaultTaxClassID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#getdefaulttaxclassid)


---

### taxRate
- taxRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the tax rate, which is the decimal tax rate to be applied to the product represented by this line item. A
      value of 0.175 represents a percentage of 17.5%.



---

### taxes
- taxes: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the tax items for this line item. When taxes are set via [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection), the line item's
      tax amount and tax rate are updated as the sum and combined rate of all tax items. The tax items are preserved
      after order creation and can be retrieved on both baskets and orders.


    **See Also:**
    - [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)
    - [LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md)


---

## Method Details

### getBasePrice()
- getBasePrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the base price for the line item, which is the price of the unit before applying adjustments, in the
      purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.


    **Returns:**
    - the base price for the line item.


---

### getGrossPrice()
- getGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the gross price for the line item, which is the price of the unit before applying adjustments, in the
      purchase currency, including tax.


    **Returns:**
    - the value of the gross price.


---

### getLineItemCtnr()
- getLineItemCtnr(): [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)
  - : Returns the line item ctnr of the line item.

    **Returns:**
    - Line item ctnr of the line item


---

### getLineItemText()
- getLineItemText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display text for the line item.

    **Returns:**
    - the display text.


---

### getNetPrice()
- getNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the net price for the line item, which is the price of the unit before applying adjustments, in the
      purchase currency, excluding tax.


    **Returns:**
    - the value for the net price.


---

### getPrice()
- getPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Get the price of the line item. If the line item is based on net pricing then the net price is returned. If the
      line item is based on gross pricing then the gross price is returned.


    **Returns:**
    - either the net or the gross price


---

### getPriceValue()
- getPriceValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the price amount for the line item. Same as getPrice().getValue().

    **Returns:**
    - the price for the line item


---

### getTax()
- getTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax for the line item, which is the tax of the unit before applying adjustments, in the purchase
      currency.


    **Returns:**
    - the tax for the line item.


---

### getTaxBasis()
- getTaxBasis(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Get the price used to calculate the tax for this line item.

    **Returns:**
    - The tax basis used to calculate tax for this line item, or Money.NOT\_AVAILABLE if tax has not been set
              for this line item yet.



---

### getTaxClassID()
- getTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tax class ID for the line item or null if no tax class ID is associated with the line item. In the
      case where the tax class ID is null, you should use the default tax class ID.


    **Returns:**
    - the tax class ID for the line item or null if no tax class ID is associated with the line item.

    **See Also:**
    - [TaxMgr.getDefaultTaxClassID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#getdefaulttaxclassid)


---

### getTaxRate()
- getTaxRate(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the tax rate, which is the decimal tax rate to be applied to the product represented by this line item. A
      value of 0.175 represents a percentage of 17.5%.


    **Returns:**
    - the value of the tax rate.


---

### getTaxes()
- getTaxes(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the tax items for this line item. When taxes are set via [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection), the line item's
      tax amount and tax rate are updated as the sum and combined rate of all tax items. The tax items are preserved
      after order creation and can be retrieved on both baskets and orders.


    **Returns:**
    - collection of [LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md); empty when no tax items are set

    **See Also:**
    - [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)
    - [LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md)


---

### setBasePrice(Money)
- ~~setBasePrice(aValue: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void~~
  - : Sets the base price for the line item, which is the price of the unit before applying adjustments, in the
      purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.


    **Parameters:**
    - aValue - the new value of the base price.

    **Deprecated:**
**warning:** Use [updatePrice(Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney) instead.

---

### setGrossPrice(Money)
- ~~setGrossPrice(aValue: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void~~
  - : Sets the gross price for the line item, which is the Price of the unit before applying adjustments, in the
      purchase currency, including tax.


    **Parameters:**
    - aValue - the new value of the attribute

    **Deprecated:**
**warning:** Use [updatePrice(Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney) which sets the base price and also the gross price if the line item
            is based on gross pricing.

---

### setLineItemText(String)
- setLineItemText(aText: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the display text for the line item.

    **Parameters:**
    - aText - line item text.


---

### setNetPrice(Money)
- ~~setNetPrice(aValue: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void~~
  - : Sets the value for the net price, which is the price of the unit before applying adjustments, in the purchase
      currency, excluding tax.


    **Parameters:**
    - aValue - the new value for the net price

    **Deprecated:**
**warning:** Use [updatePrice(Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney) which sets the base price and also the net price if the line item is
            based on net pricing.

---

### setPriceValue(Number)
- setPriceValue(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets price attributes of the line item based on the current purchase currency and taxation policy. 
      
      The methods sets the 'basePrice' attribute of the line item. Additionally, it sets the 'netPrice' attribute of
      the line item if the current taxation policy is 'net', and the 'grossPrice' attribute, if the current taxation
      policy is 'gross'. 
      
      If null is specified as value, the price attributes are reset to Money.NOT\_AVAILABLE.


    **Parameters:**
    - value - Price value or null


---

### setTax(Money)
- setTax(aValue: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Sets the value for the tax of the line item, which is the the tax of the unit before applying adjustments, in the
      purchase currency.
      
      
      If tax items are already set (e.g. via [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)), calling this will clear them.


    **Parameters:**
    - aValue - the new value for the tax.


---

### setTaxClassID(String)
- setTaxClassID(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the tax class ID for the line item.

    **Parameters:**
    - aValue - the tax class ID for the line item.


---

### setTaxRate(Number)
- setTaxRate(taxRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the tax rate, which is the decimal tax rate to be applied to the product represented by this line item. A
      value of 0.175 represents a percentage of 17.5%.
      
      
      If tax items are already set (e.g. via [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)), calling this will clear them.


    **Parameters:**
    - taxRate - the new value for the tax rate.


---

### setTaxes(Collection)
- setTaxes(taxItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): void
  - : Sets the tax items for this line item. The container must be a basket. Persists the given items, then aggregates
      them (sum of tax values, combined tax rate) and updates this line item's tax amount and tax rate accordingly.
      
      
      Each element in the collection must be a [LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md), for example created via
      [new LineItemTax(taxId, taxRate, taxValue)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md#lineitemtaxstring-number-money).
      
      
      Use either multilevel tax items via [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection) or
      [setTax(Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxmoney)/[setTaxRate(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxratenumber)/[updateTax(Number, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber-money)/[updateTaxAmount(Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxamountmoney),
      not both.
      
      
      The maximum number of tax items allowed per line item is 10.


    **Parameters:**
    - taxItems - the tax items to set; each element must be a [LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md). Maximum 10 items allowed.

    **Throws:**
    - IllegalArgumentException - if the container is not a basket, or if more than 10 tax items are provided

    **See Also:**
    - [getTaxes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes)
    - [LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md)


---

### updatePrice(Money)
- ~~updatePrice(price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void~~
  - : Updates the price attributes of the line item based on the specified price. The base price is set to the
      specified value. If the line item is based on net pricing then the net price attribute is set. If the line item
      is based on gross pricing then the gross price attribute is set. Whether or not a line item is based on net or
      gross pricing is a site-wide configuration parameter.


    **Parameters:**
    - price - The price to use when performing the update. This price must not be null and must either be equal to             NOT\_AVAIALBLE or must have a currency code equal to that of the parent container.

    **Deprecated:**
**warning:** Use [setPriceValue(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setpricevaluenumber) instead.

---

### updateTax(Number)
- updateTax(taxRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Updates the tax-related attributes of the line item based on the specified tax rate, a tax basis determined by
      the system and the "Tax Rounding Mode" order preference. This method sets the tax basis as an attribute, and is
      not affected by the previous value of this attribute.
      
      
      The value used as a basis depends on the type of line item this is and on the promotion preferences for the
      current site. If you tax products, shipping, and discounts based on price (default), then the tax basis will
      simply be equal to [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice). If you tax products and shipping only based on adjusted price, then the
      tax basis depends upon line item type as follows:
      
      - **ProductLineItem:**basis equals [ProductLineItem.getProratedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproratedprice).
      - **ShippingLineItem:**basis equals [ShippingLineItem.getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getadjustedprice).
      - **ProductShippingLineItem:**basis equals  [ProductShippingLineItem.getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedprice).
      - **PriceAdjustment:**basis equals 0.00.
      - All other line item types: basis equals [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice).
      
      If null is passed as tax rate, tax-related attribute fields are set to N/A.


    **Parameters:**
    - taxRate - taxRate the tax rate to use or null.


---

### updateTax(Number, Money)
- updateTax(taxRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), taxBasis: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Updates the tax-related attributes of the line item based on the specified tax rate, the passed tax basis and the
      "Tax Rounding Mode" order preference. If null is passed as tax rate or tax basis, tax-related attribute fields
      are set to N/A.
      
      
      If tax items are already set (e.g. via [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)), calling this will clear them.


    **Parameters:**
    - taxRate - the tax rate to use or null.
    - taxBasis - the tax basis to use or null.


---

### updateTaxAmount(Money)
- updateTaxAmount(tax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Updates tax amount of the line item setting the provided value. Depending on the way how the tax is calculated
      (based on net or gross price), the corresponding gross or net price is updated accordingly. For tax calculation
      based on net price, the gross price is calculated by adding the tax to the net price. For tax calculation based
      on gross price, the net price is calculated by subtracting the tax from the gross price.
      
      
      If null is passed as tax amount, the item tax and resulting net or gross price are set to N/A.
      
      
      Note that tax rate is not calculated and it is not updated.
      
      
      If tax items are already set (e.g. via [setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)), calling this will clear them.


    **Parameters:**
    - tax - the tax amount of the line item to set


---

<!-- prettier-ignore-end -->

<!-- document id=36a5363807f41a6c1798d822a88128d0ab887b7545758282d9bf88977d8789f7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.LineItemCtnr.md -->

<!-- prettier-ignore-start -->
# Class LineItemCtnr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)

A container for line items, such as ProductLineItems, CouponLineItems, GiftCertificateLineItems. This container also
provides access to shipments, shipping adjustments (promotions), and payment instruments (credit cards).


LineItemCtnr also contains a set of methods for creating line items and adjustments, and for accessing various price
values. There are three types of price-related methods:



- _Net-based_methods represent the amount of a category **before tax has been calculated**. For example,  the getMerchandizeTotalNetPrice() returns the price of all merchandise in the container whereas  getShippingTotalNetPrice() returns the price of all shipments in the container.
- _Tax-based_methods return the amount of tax on a category. For example, the getMerchandizeTotalTax()  returns the total tax for all merchandise and the getShippingTotalTax() returns the tax applied to all  shipments.
- _Gross-based_methods represent the amount of a category **after tax has been calculated**. For example,  the getMerchandizeTotalGrossPrice() returns the price of all merchandise in the container, including tax on the  merchandise, whereas getShippingTotalGrossPrice() returns the price of all shipments in the container, including tax  on the shipments in the container.

There are also a set of methods that provide access to 'adjusted' values. The adjusted-based methods return values
where promotions have been applied. For example, the getAdjustedMerchandizeTotalNetPrice() method returns the net
price of all merchandise after product-level and order-level promotions have been applied. Whereas the
getAdjustedMerchandizeTotalGrossPrice() method returns the price of all merchandise after product-level and
order-level promotions have been applied and includes the amount of merchandise-related tax.


Finally, there are a set of methods that return the aggregate values representing the line items in the container.
These are the total-based methods getTotalNetPrice(), getTotalTax() and getTotalGrossPrice(). These methods return
the totals of all items in the container and include any order-level promotions.


Note that all merchandise-related methods do not include 'gift certificates' values in the values they return. Gift
certificates are not considered merchandise as they do not represent a product.



## All Known Subclasses
[Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
## Constant Summary

| Constant | Description |
| --- | --- |
| [BUSINESS_TYPE_B2B](#business_type_b2b): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | constant for Business Type B2B |
| [BUSINESS_TYPE_B2C](#business_type_b2c): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | constant for Business Type B2C |
| [CHANNEL_TYPE_CALLCENTER](#channel_type_callcenter): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | constant for Channel Type CallCenter |
| [CHANNEL_TYPE_CHATGPT](#channel_type_chatgpt): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 18 | constant for Channel Type ChatGPT |
| [CHANNEL_TYPE_CUSTOMERSERVICECENTER](#channel_type_customerservicecenter): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11 | constant for Channel Type Customer Service Center |
| [CHANNEL_TYPE_DSS](#channel_type_dss): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | constant for Channel Type DSS |
| [CHANNEL_TYPE_FACEBOOKADS](#channel_type_facebookads): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | constant for Channel Type Facebook Ads |
| [CHANNEL_TYPE_GEMINI](#channel_type_gemini): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 19 | constant for Channel Type Gemini |
| [CHANNEL_TYPE_GOOGLE](#channel_type_google): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13 | constant for Channel Type Google |
| [CHANNEL_TYPE_INSTAGRAMCOMMERCE](#channel_type_instagramcommerce): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12 | constant for Channel Type Instagram Commerce |
| [CHANNEL_TYPE_MARKETPLACE](#channel_type_marketplace): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | constant for Channel Type Marketplace |
| [CHANNEL_TYPE_ONLINERESERVATION](#channel_type_onlinereservation): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | constant for Channel Type Online Reservation |
| [CHANNEL_TYPE_PINTEREST](#channel_type_pinterest): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | constant for Channel Type Pinterest |
| [CHANNEL_TYPE_SNAPCHAT](#channel_type_snapchat): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 15 | constant for Channel Type Snapchat |
| [CHANNEL_TYPE_STORE](#channel_type_store): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | constant for Channel Type Store |
| [CHANNEL_TYPE_STOREFRONT](#channel_type_storefront): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | constant for Channel Type Storefront |
| [CHANNEL_TYPE_SUBSCRIPTIONS](#channel_type_subscriptions): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9 | constant for Channel Type Subscriptions |
| [CHANNEL_TYPE_TIKTOK](#channel_type_tiktok): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 14 | constant for Channel Type TikTok |
| [CHANNEL_TYPE_TWITTER](#channel_type_twitter): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | constant for Channel Type Twitter |
| [CHANNEL_TYPE_WHATSAPP](#channel_type_whatsapp): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 16 | constant for Channel Type WhatsApp |
| [CHANNEL_TYPE_YOUTUBE](#channel_type_youtube): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 17 | constant for Channel Type YouTube |

## Property Summary

| Property | Description |
| --- | --- |
| [adjustedMerchandizeTotalGrossPrice](#adjustedmerchandizetotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted total gross price (including tax) in purchase currency. |
| [adjustedMerchandizeTotalNetPrice](#adjustedmerchandizetotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total net price (excluding tax) in purchase currency. |
| [adjustedMerchandizeTotalPrice](#adjustedmerchandizetotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted merchandize total price including product-level and order-level adjustments. |
| [adjustedMerchandizeTotalTax](#adjustedmerchandizetotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the subtotal tax in purchase currency. |
| [adjustedShippingTotalGrossPrice](#adjustedshippingtotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted sum of all shipping line items of the line item container, including tax after shipping  adjustments have been applied. |
| [adjustedShippingTotalNetPrice](#adjustedshippingtotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of all shipping line items of the line item container, excluding tax after shipping adjustments  have been applied. |
| [adjustedShippingTotalPrice](#adjustedshippingtotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted shipping total price. |
| [adjustedShippingTotalTax](#adjustedshippingtotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the tax of all shipping line items of the line item container after shipping adjustments have been  applied. |
| ~~[allGiftCertificateLineItems](#allgiftcertificatelineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)` | Returns all gift certificate line items of the container. |
| [allLineItems](#alllineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all product, shipping, price adjustment, and gift certificate line items of the line item container. |
| [allProductLineItems](#allproductlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all product line items of the container, no matter if they are dependent or independent. |
| [allProductQuantities](#allproductquantities): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) `(read-only)` | Returns a hash mapping all products in the line item container to their total quantities. |
| [allShippingPriceAdjustments](#allshippingpriceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of all shipping price adjustments applied somewhere in the container. |
| [billingAddress](#billingaddress): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md) `(read-only)` | Returns the billing address defined for the container. |
| [bonusDiscountLineItems](#bonusdiscountlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns an unsorted collection of the the bonus discount line items associated with this container. |
| [bonusLineItems](#bonuslineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of product line items that are bonus items (where  [ProductLineItem.isBonusProductLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isbonusproductlineitem) is true). |
| [businessType](#businesstype): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | Returns the type of the business this order has been placed in.<br/>  Possible values are [BUSINESS_TYPE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2c) or [BUSINESS_TYPE_B2B](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2b). |
| [channelType](#channeltype): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | The channel type defines in which sales channel this order has been created. |
| [couponLineItems](#couponlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a sorted collection of the coupon line items in the container. |
| [currencyCode](#currencycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the currency code for this line item container. |
| [customer](#customer): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)` | Returns the customer associated with this container. |
| [customerEmail](#customeremail): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the email of the customer associated with this container. |
| [customerName](#customername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the customer associated with this container. |
| [customerNo](#customerno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the customer number of the customer associated with this container. |
| [defaultShipment](#defaultshipment): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md) `(read-only)` | Returns the default shipment of the line item container. |
| [etag](#etag): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Etag of the line item container. |
| [externallyTaxed](#externallytaxed): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Use this method to check whether the LineItemCtnr is calculated based on external tax tables. |
| [giftCertificateLineItems](#giftcertificatelineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all gift certificate line items of the container. |
| [giftCertificatePaymentInstruments](#giftcertificatepaymentinstruments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns an unsorted collection of the PaymentInstrument instances that represent GiftCertificates in this  container. |
| [giftCertificateTotalGrossPrice](#giftcertificatetotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total gross price of all gift certificates in the cart. |
| [giftCertificateTotalNetPrice](#giftcertificatetotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total net price (excluding tax) of all gift certificates in the cart. |
| [giftCertificateTotalPrice](#giftcertificatetotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the gift certificate total price. |
| [giftCertificateTotalTax](#giftcertificatetotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total tax of all gift certificates in the cart. |
| [merchandizeTotalGrossPrice](#merchandizetotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total gross price (including tax) in purchase currency. |
| [merchandizeTotalNetPrice](#merchandizetotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total net price (excluding tax) in purchase currency. |
| [merchandizeTotalPrice](#merchandizetotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the merchandize total price. |
| [merchandizeTotalTax](#merchandizetotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total tax in purchase currency. |
| [notes](#notes): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns the list of notes for this object, ordered by creation time from oldest to newest. |
| ~~[paymentInstrument](#paymentinstrument): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)~~ `(read-only)` | Returns the payment instrument of the line item container or null. |
| [paymentInstruments](#paymentinstruments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns an unsorted collection of the payment instruments in this container. |
| [priceAdjustments](#priceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of price adjustments that have been applied to the totals such as promotion on the  purchase value (i.e. |
| [productLineItems](#productlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the product line items of the container that are not dependent on other product line items. |
| [productQuantities](#productquantities): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) `(read-only)` | Returns a hash map of all products in the line item container and their total quantities. |
| [productQuantityTotal](#productquantitytotal): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the total quantity of all product line items. |
| [shipments](#shipments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all shipments of the line item container.<br/>  The first shipment in the returned collection is the default shipment (shipment ID always set to "me"). |
| [shippingPriceAdjustments](#shippingpriceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the of shipping price adjustments applied to the shipping total of the container. |
| [shippingTotalGrossPrice](#shippingtotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of all shipping line items of the line item container, including tax before shipping adjustments  have been applied. |
| [shippingTotalNetPrice](#shippingtotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of all shipping line items of the line item container, excluding tax before shipping adjustments  have been applied. |
| [shippingTotalPrice](#shippingtotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the shipping total price. |
| [shippingTotalTax](#shippingtotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the tax of all shipping line items of the line item container before shipping adjustments have been  applied. |
| [taxRoundedAtGroup](#taxroundedatgroup): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Use this method to check if the LineItemCtnr was calculated with grouped taxation calculation. |
| [taxTotalsPerTaxRate](#taxtotalspertaxrate): [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md) `(read-only)` | This method returns a [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md) in which the keys are [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) tax rates and the values  are [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) total tax for the tax rate. |
| [totalGrossPrice](#totalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the grand total price gross of tax for LineItemCtnr, in purchase currency. |
| [totalNetPrice](#totalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the grand total price for LineItemCtnr net of tax, in purchase currency. |
| [totalTax](#totaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the grand total tax for LineItemCtnr, in purchase currency. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#addnotestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a note to the object. |
| [createBillingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbillingaddress)() | Create a billing address for the LineItemCtnr. |
| [createBonusProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbonusproductlineitembonusdiscountlineitem-product-productoptionmodel-shipment)([BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md), [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Creates a product line item in the container based on the passed Product and BonusDiscountLineItem. |
| [createCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a coupon line item that is not based on the B2C Commerce campaign system and associates it with the  specified coupon code. |
| [createCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Creates a new CouponLineItem for this container based on the supplied coupon code. |
| [createGiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#creategiftcertificatelineitemnumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a gift certificate line item. |
| [createGiftCertificatePaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#creategiftcertificatepaymentinstrumentstring-money)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Creates an OrderPaymentInstrument representing a Gift Certificate. |
| [createPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpaymentinstrumentstring-money)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Creates a payment instrument using the specified payment method id and amount. |
| [createPaymentInstrumentFromWallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpaymentinstrumentfromwalletcustomerpaymentinstrument-money)([CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Creates a payment instrument using the specified wallet payment instrument and amount. |
| [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates an order price adjustment.<br/>  The promotion id is mandatory and must not be the ID of any actual promotion defined in B2C Commerce; otherwise  an exception is thrown. |
| [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring-discount)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)) | Creates an order level price adjustment for a specific discount.<br/>  The promotion id is mandatory and must not be the ID of any actual promotion defined in B2C Commerce; otherwise  an exception is thrown. |
| [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemproduct-productoptionmodel-shipment)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Creates a new product line item in the container and assigns it to the specified shipment. |
| [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemproductlistitem-shipment)([ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Creates a new product line item in the basket and assigns it to the specified shipment. |
| [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-shipment)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Creates a new product line item in the container and assigns it to the specified shipment. |
| ~~[createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-quantity-shipment)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md))~~ | Creates a new product line item in the container and assigns it to the specified shipment. |
| [createShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createshipmentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a standard shipment for the line item container. |
| [createShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createshippingpriceadjustmentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a shipping price adjustment to be applied to the container. |
| [getAdjustedMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalgrossprice)() | Returns the adjusted total gross price (including tax) in purchase currency. |
| [getAdjustedMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalnetprice)() | Returns the total net price (excluding tax) in purchase currency. |
| [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalprice)() | Returns the adjusted merchandize total price including product-level and order-level adjustments. |
| [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalpriceboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the adjusted merchandize total price including order-level adjustments if requested. |
| [getAdjustedMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotaltax)() | Returns the subtotal tax in purchase currency. |
| [getAdjustedShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalgrossprice)() | Returns the adjusted sum of all shipping line items of the line item container, including tax after shipping  adjustments have been applied. |
| [getAdjustedShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalnetprice)() | Returns the sum of all shipping line items of the line item container, excluding tax after shipping adjustments  have been applied. |
| [getAdjustedShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalprice)() | Returns the adjusted shipping total price. |
| [getAdjustedShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotaltax)() | Returns the tax of all shipping line items of the line item container after shipping adjustments have been  applied. |
| ~~[getAllGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallgiftcertificatelineitems)()~~ | Returns all gift certificate line items of the container. |
| [getAllLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getalllineitems)() | Returns all product, shipping, price adjustment, and gift certificate line items of the line item container. |
| [getAllProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductlineitems)() | Returns all product line items of the container, no matter if they are dependent or independent. |
| [getAllProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductlineitemsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all product line items of the container that have a product ID equal to the specified product ID, no  matter if they are dependent or independent. |
| [getAllProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductquantities)() | Returns a hash mapping all products in the line item container to their total quantities. |
| [getAllShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallshippingpriceadjustments)() | Returns the collection of all shipping price adjustments applied somewhere in the container. |
| [getBillingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbillingaddress)() | Returns the billing address defined for the container. |
| [getBonusDiscountLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbonusdiscountlineitems)() | Returns an unsorted collection of the the bonus discount line items associated with this container. |
| [getBonusLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbonuslineitems)() | Returns the collection of product line items that are bonus items (where  [ProductLineItem.isBonusProductLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isbonusproductlineitem) is true). |
| [getBusinessType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbusinesstype)() | Returns the type of the business this order has been placed in.<br/>  Possible values are [BUSINESS_TYPE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2c) or [BUSINESS_TYPE_B2B](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2b). |
| [getChannelType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getchanneltype)() | The channel type defines in which sales channel this order has been created. |
| [getCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcouponlineitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the coupon line item representing the specified coupon code. |
| [getCouponLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcouponlineitems)() | Returns a sorted collection of the coupon line items in the container. |
| [getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcurrencycode)() | Returns the currency code for this line item container. |
| [getCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomer)() | Returns the customer associated with this container. |
| [getCustomerEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomeremail)() | Returns the email of the customer associated with this container. |
| [getCustomerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomername)() | Returns the name of the customer associated with this container. |
| [getCustomerNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomerno)() | Returns the customer number of the customer associated with this container. |
| [getDefaultShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getdefaultshipment)() | Returns the default shipment of the line item container. |
| [getEtag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getetag)() | Returns the Etag of the line item container. |
| [getGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitems)() | Returns all gift certificate line items of the container. |
| [getGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitemsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all gift certificate line items of the container, no matter if they are dependent or independent. |
| [getGiftCertificatePaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstruments)() | Returns an unsorted collection of the PaymentInstrument instances that represent GiftCertificates in this  container. |
| [getGiftCertificatePaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstrumentsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an unsorted collection containing all PaymentInstruments of type  PaymentInstrument.METHOD\_GIFT\_CERTIFICATE where the specified code is the same code on the payment instrument. |
| [getGiftCertificateTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalgrossprice)() | Returns the total gross price of all gift certificates in the cart. |
| [getGiftCertificateTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalnetprice)() | Returns the total net price (excluding tax) of all gift certificates in the cart. |
| [getGiftCertificateTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalprice)() | Returns the gift certificate total price. |
| [getGiftCertificateTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotaltax)() | Returns the total tax of all gift certificates in the cart. |
| [getMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalgrossprice)() | Returns the total gross price (including tax) in purchase currency. |
| [getMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalnetprice)() | Returns the total net price (excluding tax) in purchase currency. |
| [getMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalprice)() | Returns the merchandize total price. |
| [getMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotaltax)() | Returns the total tax in purchase currency. |
| [getNotes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getnotes)() | Returns the list of notes for this object, ordered by creation time from oldest to newest. |
| ~~[getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstrument)()~~ | Returns the payment instrument of the line item container or null. |
| [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstruments)() | Returns an unsorted collection of the payment instruments in this container. |
| [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstrumentsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an unsorted collection of PaymentInstrument instances based on the specified payment method ID. |
| [getPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpriceadjustmentbypromotionidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the price adjustment associated to the specified promotion ID. |
| [getPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpriceadjustments)() | Returns the collection of price adjustments that have been applied to the totals such as promotion on the  purchase value (i.e. |
| [getProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductlineitems)() | Returns the product line items of the container that are not dependent on other product line items. |
| [getProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductlineitemsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the product line items of the container that have a product ID equal to the specified product ID and that  are not dependent on other product line items. |
| [getProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantities)() | Returns a hash map of all products in the line item container and their total quantities. |
| [getProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitiesboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns a hash map of all products in the line item container and their total quantities. |
| [getProductQuantityTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitytotal)() | Returns the total quantity of all product line items. |
| [getShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshipmentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the shipment for the specified ID or `null` if no shipment with this ID exists in the line  item container. |
| [getShipments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshipments)() | Returns all shipments of the line item container.<br/>  The first shipment in the returned collection is the default shipment (shipment ID always set to "me"). |
| [getShippingPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustmentbypromotionidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the shipping price adjustment associated with the specified promotion ID. |
| [getShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustments)() | Returns the of shipping price adjustments applied to the shipping total of the container. |
| [getShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalgrossprice)() | Returns the sum of all shipping line items of the line item container, including tax before shipping adjustments  have been applied. |
| [getShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalnetprice)() | Returns the sum of all shipping line items of the line item container, excluding tax before shipping adjustments  have been applied. |
| [getShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalprice)() | Returns the shipping total price. |
| [getShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotaltax)() | Returns the tax of all shipping line items of the line item container before shipping adjustments have been  applied. |
| [getTaxTotalsPerTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettaxtotalspertaxrate)() | This method returns a [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md) in which the keys are [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) tax rates and the values  are [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) total tax for the tax rate. |
| [getTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotalgrossprice)() | Returns the grand total price gross of tax for LineItemCtnr, in purchase currency. |
| [getTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotalnetprice)() | Returns the grand total price for LineItemCtnr net of tax, in purchase currency. |
| [getTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotaltax)() | Returns the grand total tax for LineItemCtnr, in purchase currency. |
| [isExternallyTaxed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#isexternallytaxed)() | Use this method to check whether the LineItemCtnr is calculated based on external tax tables. |
| [isTaxRoundedAtGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#istaxroundedatgroup)() | Use this method to check if the LineItemCtnr was calculated with grouped taxation calculation. |
| [removeAllPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeallpaymentinstruments)() | Removes the all Payment Instruments from this container and deletes the Payment Instruments. |
| [removeBonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removebonusdiscountlineitembonusdiscountlineitem)([BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md)) | Removes the specified bonus discount line item from the line item container. |
| [removeCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removecouponlineitemcouponlineitem)([CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)) | Removes the specified coupon line item from the line item container. |
| [removeGiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removegiftcertificatelineitemgiftcertificatelineitem)([GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md)) | Removes the specified gift certificate line item from the line item container. |
| [removeNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removenotenote)([Note](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md)) | Removes a note from this line item container and deletes it. |
| [removePaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removepaymentinstrumentpaymentinstrument)([PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md)) | Removes the specified Payment Instrument from this container and deletes the Payment Instrument. |
| [removePriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removepriceadjustmentpriceadjustment)([PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)) | Removes the specified price adjustment line item from the line item container. |
| [removeProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeproductlineitemproductlineitem)([ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)) | Removes the specified product line item from the line item container. |
| [removeShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshipmentshipment)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Removes the specified shipment and all associated product, gift certificate, shipping and price adjustment line  items from the line item container. |
| [removeShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshippingpriceadjustmentpriceadjustment)([PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)) | Removes the specified shipping price adjustment line item from the line item container. |
| [setCustomerEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#setcustomeremailstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the email address of the customer associated with this container. |
| [setCustomerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#setcustomernamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the customer associated with this container. |
| [updateOrderLevelPriceAdjustmentTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#updateorderlevelpriceadjustmenttax)() | Calculates the tax for all shipping and order-level merchandise price adjustments in this LineItemCtnr. |
| [updateTotals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#updatetotals)() | Recalculates the totals of the line item container. |
| [verifyPriceAdjustmentLimits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#verifypriceadjustmentlimits)() | Verifies whether the manual price adjustments made for the line item container exceed the corresponding limits  for the current user and the current site. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BUSINESS_TYPE_B2B

- BUSINESS_TYPE_B2B: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : constant for Business Type B2B


---

### BUSINESS_TYPE_B2C

- BUSINESS_TYPE_B2C: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : constant for Business Type B2C


---

### CHANNEL_TYPE_CALLCENTER

- CHANNEL_TYPE_CALLCENTER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : constant for Channel Type CallCenter


---

### CHANNEL_TYPE_CHATGPT

- CHANNEL_TYPE_CHATGPT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 18
  - : constant for Channel Type ChatGPT


---

### CHANNEL_TYPE_CUSTOMERSERVICECENTER

- CHANNEL_TYPE_CUSTOMERSERVICECENTER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11
  - : constant for Channel Type Customer Service Center


---

### CHANNEL_TYPE_DSS

- CHANNEL_TYPE_DSS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : constant for Channel Type DSS


---

### CHANNEL_TYPE_FACEBOOKADS

- CHANNEL_TYPE_FACEBOOKADS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : constant for Channel Type Facebook Ads


---

### CHANNEL_TYPE_GEMINI

- CHANNEL_TYPE_GEMINI: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 19
  - : constant for Channel Type Gemini


---

### CHANNEL_TYPE_GOOGLE

- CHANNEL_TYPE_GOOGLE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13
  - : constant for Channel Type Google


---

### CHANNEL_TYPE_INSTAGRAMCOMMERCE

- CHANNEL_TYPE_INSTAGRAMCOMMERCE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12
  - : constant for Channel Type Instagram Commerce


---

### CHANNEL_TYPE_MARKETPLACE

- CHANNEL_TYPE_MARKETPLACE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : constant for Channel Type Marketplace


---

### CHANNEL_TYPE_ONLINERESERVATION

- CHANNEL_TYPE_ONLINERESERVATION: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : constant for Channel Type Online Reservation


---

### CHANNEL_TYPE_PINTEREST

- CHANNEL_TYPE_PINTEREST: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : constant for Channel Type Pinterest


---

### CHANNEL_TYPE_SNAPCHAT

- CHANNEL_TYPE_SNAPCHAT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 15
  - : constant for Channel Type Snapchat


---

### CHANNEL_TYPE_STORE

- CHANNEL_TYPE_STORE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : constant for Channel Type Store


---

### CHANNEL_TYPE_STOREFRONT

- CHANNEL_TYPE_STOREFRONT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : constant for Channel Type Storefront


---

### CHANNEL_TYPE_SUBSCRIPTIONS

- CHANNEL_TYPE_SUBSCRIPTIONS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9
  - : constant for Channel Type Subscriptions


---

### CHANNEL_TYPE_TIKTOK

- CHANNEL_TYPE_TIKTOK: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 14
  - : constant for Channel Type TikTok


---

### CHANNEL_TYPE_TWITTER

- CHANNEL_TYPE_TWITTER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : constant for Channel Type Twitter


---

### CHANNEL_TYPE_WHATSAPP

- CHANNEL_TYPE_WHATSAPP: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 16
  - : constant for Channel Type WhatsApp


---

### CHANNEL_TYPE_YOUTUBE

- CHANNEL_TYPE_YOUTUBE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 17
  - : constant for Channel Type YouTube


---

## Property Details

### adjustedMerchandizeTotalGrossPrice
- adjustedMerchandizeTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted total gross price (including tax) in purchase currency. Adjusted merchandize prices
      represent the sum of product prices before services such as shipping, but after product-level and order-level
      adjustments.



---

### adjustedMerchandizeTotalNetPrice
- adjustedMerchandizeTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total net price (excluding tax) in purchase currency. Adjusted merchandize prices represent the sum
      of product prices before services such as shipping, but after product-level and order-level adjustments.



---

### adjustedMerchandizeTotalPrice
- adjustedMerchandizeTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted merchandize total price including product-level and order-level adjustments. If the line
      item container is based on net pricing the adjusted merchandize total net price is returned. If the line item
      container is based on gross pricing the adjusted merchandize total gross price is returned.



---

### adjustedMerchandizeTotalTax
- adjustedMerchandizeTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the subtotal tax in purchase currency. Adjusted merchandize prices represent the sum of product prices
      before services such as shipping have been added, but after adjustment from promotions have been added.



---

### adjustedShippingTotalGrossPrice
- adjustedShippingTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted sum of all shipping line items of the line item container, including tax after shipping
      adjustments have been applied.



---

### adjustedShippingTotalNetPrice
- adjustedShippingTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of all shipping line items of the line item container, excluding tax after shipping adjustments
      have been applied.



---

### adjustedShippingTotalPrice
- adjustedShippingTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted shipping total price. If the line item container is based on net pricing the adjusted
      shipping total net price is returned. If the line item container is based on gross pricing the adjusted shipping
      total gross price is returned.



---

### adjustedShippingTotalTax
- adjustedShippingTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the tax of all shipping line items of the line item container after shipping adjustments have been
      applied.



---

### allGiftCertificateLineItems
- ~~allGiftCertificateLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)`
  - : Returns all gift certificate line items of the container.

    **Deprecated:**
**warning:** Use [getGiftCertificateLineItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitems) to get the collection instead.

---

### allLineItems
- allLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all product, shipping, price adjustment, and gift certificate line items of the line item container.


---

### allProductLineItems
- allProductLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all product line items of the container, no matter if they are dependent or independent. This includes
      option, bundled and bonus line items.



---

### allProductQuantities
- allProductQuantities: [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) `(read-only)`
  - : Returns a hash mapping all products in the line item container to their total quantities. The total product
      quantity is used chiefly to validate the availability of the items in the cart. This method is not appropriate to
      look up prices because it returns products such as bundled line items which are included in the price of their
      parent and therefore have no corresponding price.
      
      
      The method counts all direct product line items, plus dependent product line items that are not option line
      items. It also excludes product line items that are not associated to any catalog product.



---

### allShippingPriceAdjustments
- allShippingPriceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of all shipping price adjustments applied somewhere in the container. This can be
      adjustments applied to individual shipments or to the container itself. Note that the promotions engine only
      applies shipping price adjustments to the the default shipping line item of shipments, and never to the
      container.


    **See Also:**
    - [getShippingPriceAdjustments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustments)


---

### billingAddress
- billingAddress: [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md) `(read-only)`
  - : Returns the billing address defined for the container. Returns null if no billing address has been created yet.


---

### bonusDiscountLineItems
- bonusDiscountLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns an unsorted collection of the the bonus discount line items associated with this container.


---

### bonusLineItems
- bonusLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of product line items that are bonus items (where
      [ProductLineItem.isBonusProductLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isbonusproductlineitem) is true).



---

### businessType
- businessType: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : Returns the type of the business this order has been placed in.
      
      Possible values are [BUSINESS_TYPE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2c) or [BUSINESS_TYPE_B2B](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2b).



---

### channelType
- channelType: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : The channel type defines in which sales channel this order has been created. This can be used to distinguish
      order placed through Storefront, Call Center or Marketplace.
      
      Possible values are [CHANNEL_TYPE_STOREFRONT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_storefront), [CHANNEL_TYPE_CALLCENTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_callcenter),
      [CHANNEL_TYPE_MARKETPLACE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_marketplace), [CHANNEL_TYPE_DSS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_dss), [CHANNEL_TYPE_STORE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_store),
      [CHANNEL_TYPE_PINTEREST](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_pinterest), [CHANNEL_TYPE_TWITTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_twitter), [CHANNEL_TYPE_FACEBOOKADS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_facebookads),
      [CHANNEL_TYPE_SUBSCRIPTIONS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_subscriptions), [CHANNEL_TYPE_ONLINERESERVATION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_onlinereservation),
      [CHANNEL_TYPE_CUSTOMERSERVICECENTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_customerservicecenter), [CHANNEL_TYPE_INSTAGRAMCOMMERCE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_instagramcommerce),
      [CHANNEL_TYPE_GOOGLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_google), [CHANNEL_TYPE_YOUTUBE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_youtube), [CHANNEL_TYPE_TIKTOK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_tiktok),
      [CHANNEL_TYPE_SNAPCHAT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_snapchat), [CHANNEL_TYPE_WHATSAPP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_whatsapp), [CHANNEL_TYPE_CHATGPT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_chatgpt),
      [CHANNEL_TYPE_GEMINI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_gemini)



---

### couponLineItems
- couponLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a sorted collection of the coupon line items in the container. The coupon line items are returned in the
      order they were added to container.



---

### currencyCode
- currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the currency code for this line item container. The currency code is a 3-character currency mnemonic such
      as 'USD' or 'EUR'. The currency code represents the currency in which the calculation is made, and in which the
      buyer sees all prices in the store front.



---

### customer
- customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)`
  - : Returns the customer associated with this container.


---

### customerEmail
- customerEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email of the customer associated with this container.


---

### customerName
- customerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the customer associated with this container.


---

### customerNo
- customerNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the customer number of the customer associated with this container.


---

### defaultShipment
- defaultShipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md) `(read-only)`
  - : Returns the default shipment of the line item container. Baskets always have a default shipment with ID "me".
      For orders, this can differ, for example: [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) removes empty
      shipments, so if the basket's "me" shipment was empty at order creation, the order has no "me" shipment. In
      that case, the shipment with the lowest ID is returned as the fallback, or `null` if the order has
      no shipments. See [Shipment.isDefault()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#isdefault) for the matching logic.
      
      
      Processes that access a shipment use the default shipment when none is specified. The default shipment can't be
      removed. Calling [removeShipment(Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshipmentshipment) on it throws an exception.



---

### etag
- etag: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Etag of the line item container. The Etag is a hash that represents the overall container state
      including any associated objects like line items.



---

### externallyTaxed
- externallyTaxed: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Use this method to check whether the LineItemCtnr is calculated based on external tax tables.
      
      Note: a basket can only be created in EXTERNAL tax mode using SCAPI.



---

### giftCertificateLineItems
- giftCertificateLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all gift certificate line items of the container.


---

### giftCertificatePaymentInstruments
- giftCertificatePaymentInstruments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns an unsorted collection of the PaymentInstrument instances that represent GiftCertificates in this
      container.



---

### giftCertificateTotalGrossPrice
- giftCertificateTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total gross price of all gift certificates in the cart. Should usually be equal to total net price.


---

### giftCertificateTotalNetPrice
- giftCertificateTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total net price (excluding tax) of all gift certificates in the cart. Should usually be equal to
      total gross price.



---

### giftCertificateTotalPrice
- giftCertificateTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the gift certificate total price. If the line item container is based on net pricing the gift certificate
      total net price is returned. If the line item container is based on gross pricing the gift certificate total
      gross price is returned.



---

### giftCertificateTotalTax
- giftCertificateTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total tax of all gift certificates in the cart. Should usually be 0.0.


---

### merchandizeTotalGrossPrice
- merchandizeTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total gross price (including tax) in purchase currency. Merchandize total prices represent the sum of
      product prices before services such as shipping or adjustment from promotions have been added.



---

### merchandizeTotalNetPrice
- merchandizeTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total net price (excluding tax) in purchase currency. Merchandize total prices represent the sum of
      product prices before services such as shipping or adjustment from promotion have been added.



---

### merchandizeTotalPrice
- merchandizeTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the merchandize total price. If the line item container is based on net pricing the merchandize total net
      price is returned. If the line item container is based on gross pricing the merchandize total gross price is
      returned.



---

### merchandizeTotalTax
- merchandizeTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total tax in purchase currency. Merchandize total prices represent the sum of product prices before
      services such as shipping or adjustment from promotions have been added.



---

### notes
- notes: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns the list of notes for this object, ordered by creation time from oldest to newest.


---

### paymentInstrument
- ~~paymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)~~ `(read-only)`
  - : Returns the payment instrument of the line item container or null. This method is deprecated. You should use
      getPaymentInstruments() or getGiftCertificatePaymentInstruments() instead.


    **Deprecated:**
**warning:** Use [getPaymentInstruments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstruments) or [getGiftCertificatePaymentInstruments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstruments) to get the
            set of payment instruments.

---

### paymentInstruments
- paymentInstruments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns an unsorted collection of the payment instruments in this container.


---

### priceAdjustments
- priceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of price adjustments that have been applied to the totals such as promotion on the
      purchase value (i.e. $10 Off or 10% Off). The price adjustments are sorted by the order in which they were
      applied to the order by the promotions engine.



---

### productLineItems
- productLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the product line items of the container that are not dependent on other product line items. This includes
      line items representing bonus products in the container but excludes option, bundled, and bonus line items. The
      returned collection is sorted by the position attribute of the product line items.



---

### productQuantities
- productQuantities: [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) `(read-only)`
  - : Returns a hash map of all products in the line item container and their total quantities. The total product
      quantity is for example used to lookup the product price.
      
      
      The method counts all direct product line items, plus dependent product line items that are not bundled line
      items and no option line items. It also excludes product line items that are not associated to any catalog
      product, and bonus product line items.


    **See Also:**
    - [getProductQuantities(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitiesboolean)


---

### productQuantityTotal
- productQuantityTotal: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the total quantity of all product line items. Not included are bundled line items and option line items.


---

### shipments
- shipments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all shipments of the line item container.
      
      The first shipment in the returned collection is the default shipment (shipment ID always set to "me"). All other
      shipments are sorted ascending by shipment ID.



---

### shippingPriceAdjustments
- shippingPriceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the of shipping price adjustments applied to the shipping total of the container. Note that the
      promotions engine only applies shipping price adjustments to the the default shipping line item of shipments, and
      never to the container.


    **See Also:**
    - [getAllShippingPriceAdjustments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallshippingpriceadjustments)


---

### shippingTotalGrossPrice
- shippingTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of all shipping line items of the line item container, including tax before shipping adjustments
      have been applied.



---

### shippingTotalNetPrice
- shippingTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of all shipping line items of the line item container, excluding tax before shipping adjustments
      have been applied.



---

### shippingTotalPrice
- shippingTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the shipping total price. If the line item container is based on net pricing the shipping total net price
      is returned. If the line item container is based on gross pricing the shipping total gross price is returned.



---

### shippingTotalTax
- shippingTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the tax of all shipping line items of the line item container before shipping adjustments have been
      applied.



---

### taxRoundedAtGroup
- taxRoundedAtGroup: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Use this method to check if the LineItemCtnr was calculated with grouped taxation calculation.
      
      
      If the tax is rounded on group level, the tax is applied to the summed-up tax basis for each tax rate.



---

### taxTotalsPerTaxRate
- taxTotalsPerTaxRate: [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md) `(read-only)`
  - : This method returns a [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md) in which the keys are [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) tax rates and the values
      are [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) total tax for the tax rate. The map is unmodifiable.



---

### totalGrossPrice
- totalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the grand total price gross of tax for LineItemCtnr, in purchase currency. Total prices represent the sum
      of product prices, services prices and adjustments.



---

### totalNetPrice
- totalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the grand total price for LineItemCtnr net of tax, in purchase currency. Total prices represent the sum
      of product prices, services prices and adjustments.



---

### totalTax
- totalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the grand total tax for LineItemCtnr, in purchase currency. Total prices represent the sum of product
      prices, services prices and adjustments.



---

## Method Details

### addNote(String, String)
- addNote(subject: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Note](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md)
  - : Adds a note to the object.

    **Parameters:**
    - subject - The subject of the note.
    - text - The text of the note. Must be no more than 4000 characters or an exception is thrown.

    **Returns:**
    - the added note.


---

### createBillingAddress()
- createBillingAddress(): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)
  - : Create a billing address for the LineItemCtnr. A LineItemCtnr (e.g. basket) initially has no billing address.
      This method creates a billing address for the LineItemCtnr and replaces an existing billing address.


    **Returns:**
    - The new billing address of the LineItemCtnr.


---

### createBonusProductLineItem(BonusDiscountLineItem, Product, ProductOptionModel, Shipment)
- createBonusProductLineItem(bonusDiscountLineItem: [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md), product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), optionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
  - : Creates a product line item in the container based on the passed Product and BonusDiscountLineItem. The product
      must be assigned to the current site catalog and must also be a bonus product of the specified
      BonusDiscountLineItem or an exception is thrown. The line item is always created in the default shipment. If
      successful, the operation always creates a new ProductLineItem and never simply increments the quantity of an
      existing ProductLineItem. An option model can optionally be specified.


    **Parameters:**
    - bonusDiscountLineItem - Line item representing an applied BonusChoiceDiscount in the LineItemCtnr, must not             be null.
    - product - Product The product to add to the LineItemCtnr. Must not be null and must be a bonus product of             bonusDiscountLineItem.
    - optionModel - ProductOptionModel or null.
    - shipment - The shipment to add the bonus product to. If null, the product is added to the default shipment.


---

### createCouponLineItem(String)
- createCouponLineItem(couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)
  - : Creates a coupon line item that is not based on the B2C Commerce campaign system and associates it with the
      specified coupon code.
      
      
      There may not be any other coupon line item in the container with the specific coupon code, otherwise an
      exception is thrown.
      
      
      If you want to create a coupon line item based on the B2C Commerce campaign system, you must use
      [createCouponLineItem(String, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring-boolean) with campaignBased = true.


    **Parameters:**
    - couponCode - couponCode represented by the coupon line item.

    **Returns:**
    - New coupon line item.


---

### createCouponLineItem(String, Boolean)
- createCouponLineItem(couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), campaignBased: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)
  - : Creates a new CouponLineItem for this container based on the supplied coupon code.
      
      
      The created coupon line item is based on the B2C Commerce campaign system if campaignBased parameter is true. In
      that case, if the supplied coupon code is not valid, APIException with type 'CreateCouponLineItemException' is
      thrown.
      
      
      If you want to create a custom coupon line item, you must call this method with campaignBased = false or to use
      [createCouponLineItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring).
      
      
      
      
      Example:
      
      
      
      
      ```
      try {
          var cli : CouponLineItem = basket.createCouponLineItem(couponCode, true);
      } catch (e if e instanceof APIException && e.type === 'CreateCouponLineItemException')
          if (e.errorCode == CouponStatusCodes.COUPON_CODE_ALREADY_IN_BASKET) {
              ...
          }
      }
      ```
      
      
      An dw.order.CreateCouponLineItemException is thrown in case of campaignBased = true only. Indicates that the
      provided coupon code is not a valid coupon code to create a coupon line item based on the B2C Commerce campaign
      system. The error code property (CreateCouponLineItemException.errorCode) will be set to one of the following
      values:
      
      - [CouponStatusCodes.COUPON_CODE_ALREADY_IN_BASKET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_already_in_basket)= Indicates that coupon code has already  been added to basket.
      - [CouponStatusCodes.COUPON_ALREADY_IN_BASKET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_already_in_basket)= Indicates that another code of the same  MultiCode/System coupon has already been added to basket.
      - [CouponStatusCodes.COUPON_CODE_ALREADY_REDEEMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_already_redeemed)= Indicates that code of MultiCode/System  coupon has already been redeemed.
      - [CouponStatusCodes.COUPON_CODE_UNKNOWN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_code_unknown)= Indicates that coupon not found for given coupon  code or that the code itself was not found.
      - [CouponStatusCodes.COUPON_DISABLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#coupon_disabled)= Indicates that coupon is not enabled.
      - [CouponStatusCodes.REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#redemption_limit_exceeded)= Indicates that number of redemptions per  code exceeded.
      - [CouponStatusCodes.CUSTOMER_REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#customer_redemption_limit_exceeded)= Indicates that number of  redemptions per code and customer exceeded.
      - [CouponStatusCodes.TIMEFRAME_REDEMPTION_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#timeframe_redemption_limit_exceeded)= Indicates that number of  redemptions per code, customer and time exceeded.
      - [CouponStatusCodes.NO_ACTIVE_PROMOTION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md#no_active_promotion)= Indicates that coupon is not assigned to an  active promotion.


    **Parameters:**
    - couponCode - the coupon code to be represented by the coupon line item
    - campaignBased - the flag if the created coupon line item should be based on the B2C Commerce campaign system

    **Returns:**
    - the created coupon line item


---

### createGiftCertificateLineItem(Number, String)
- createGiftCertificateLineItem(amount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), recipientEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md)
  - : Creates a gift certificate line item.

    **Parameters:**
    - amount - the amount of the gift certificate - mandatory
    - recipientEmail - the recipient's email address - mandatory

    **Returns:**
    - The new gift certificate line item


---

### createGiftCertificatePaymentInstrument(String, Money)
- createGiftCertificatePaymentInstrument(giftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Creates an OrderPaymentInstrument representing a Gift Certificate. The amount is set on a PaymentTransaction that
      is accessible via the OrderPaymentInstrument. By default, the status of the PaymentTransaction is set to CREATE.
      The PaymentTransaction must be processed at a later time.


    **Parameters:**
    - giftCertificateCode - the redemption code of the Gift Certificate.
    - amount - the amount to set on the PaymentTransaction. If the OrderPaymentInstrument is actually redeemed,             this is the amount that will be deducted from the Gift Certificate.

    **Returns:**
    - the OrderPaymentInstrument.


---

### createPaymentInstrument(String, Money)
- createPaymentInstrument(paymentMethodId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Creates a payment instrument using the specified payment method id and amount. The amount is set on the
      [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md) that is attached to the payment instrument.


    **Parameters:**
    - paymentMethodId - The payment method id. See the [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md) class for payment method             types
    - amount - The payment amount or null

    **Returns:**
    - The new payment instrument


---

### createPaymentInstrumentFromWallet(CustomerPaymentInstrument, Money)
- createPaymentInstrumentFromWallet(walletPaymentInstrument: [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Creates a payment instrument using the specified wallet payment instrument and amount. The amount is set on the
      [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md) that is attached to the payment instrument. All data from the wallet payment
      instrument will be copied over to the created payment instrument.


    **Parameters:**
    - walletPaymentInstrument - The payment instrument from the customer's walled.
    - amount - The payment amount or null

    **Returns:**
    - The new payment instrument


---

### createPriceAdjustment(String)
- createPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Creates an order price adjustment.
      
      The promotion id is mandatory and must not be the ID of any actual promotion defined in B2C Commerce; otherwise
      an exception is thrown. 


    **Parameters:**
    - promotionID - Promotion ID

    **Returns:**
    - The new price adjustment


---

### createPriceAdjustment(String, Discount)
- createPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), discount: [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Creates an order level price adjustment for a specific discount.
      
      The promotion id is mandatory and must not be the ID of any actual promotion defined in B2C Commerce; otherwise
      an exception is thrown. 
      
      The possible discount types are supported: [PercentageDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageDiscount.md) and
      [AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md). 
      
      Examples:
      
      
      `
       var myOrder : dw.order.Order; // assume known
      
       var paTenPercent : dw.order.PriceAdjustment = myOrder.createPriceAdjustment("myPromotionID1", new dw.campaign.PercentageDiscount(10));
      
       var paReduceBy20 : dw.order.PriceAdjustment = myOrder.createPriceAdjustment("myPromotionID2", new dw.campaign.AmountDiscount(20);
      
       `


    **Parameters:**
    - promotionID - Promotion ID
    - discount - The discount

    **Returns:**
    - The new price adjustment


---

### createProductLineItem(Product, ProductOptionModel, Shipment)
- createProductLineItem(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), optionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
  - : Creates a new product line item in the container and assigns it to the specified shipment. An option model can be
      specified. 
      
      Please note that the product must be assigned to the current site catalog.


    **Parameters:**
    - product - Product
    - optionModel - ProductOptionModel or null
    - shipment - Shipment


---

### createProductLineItem(ProductListItem, Shipment)
- createProductLineItem(productListItem: [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
  - : Creates a new product line item in the basket and assigns it to the specified shipment.
      
      
      If the product list item references a product in the site catalog, the method will associate the product line
      item with that catalog product and will copy all order-relevant information, like the quantity unit, from the
      catalog product. The quantity of the product line item is initialized with 1.0 or - if defined - the minimum
      order quantity of the product.
      
      
      If the product list item references an option product, the option values are copied from the product list item.
      
      
      If the product list item is associated with an existing product line item, and the BasketAddProductBehaviour
      setting is MergeQuantities, then the product line item quantity is increased by 1.0 or, if defined, the minimum
      order quantity of the product.
      
      
      An exception is thrown if
      
      - the line item container is no basket.
      - the type of the product list item is not PRODUCT.
      - the product list item references a product which is not assigned to the site catalog.


    **Parameters:**
    - productListItem - the product list item
    - shipment - the shipment the created product line item will be assigned to

    **Returns:**
    - The new product line item


---

### createProductLineItem(String, Shipment)
- createProductLineItem(productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
  - : Creates a new product line item in the container and assigns it to the specified shipment. 
      
      If the specified productID represents a product in the site catalog, the method will associate the product line
      item with that catalog product and will copy all order-relevant information, like the quantity unit, from the
      catalog product. The quantity of the product line item is initialized with 1.0 or - if defined - the minimum
      order quantity of the product.
      
      If the product represents a product in the site catalog and is an option product, the product is added with it's
      default option values. 
      
      If the specified productID does not represent a product of the site catalog, the method creates a new product
      line item and initializes it with the specified product ID and with a quantity, minimum order quantity, and step
      quantity value of 1.0.
      
      If the provided SKU references a product that is not available as described in method [ProductLineItem.isCatalogProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#iscatalogproduct), the new product line item is considered a non-catalog product line item without a connection to a product. Such product line items are not included in reservation requests in either OCI-based inventory or eCom-based inventory when calling [Basket.reserveInventory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventory) or [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket).


    **Parameters:**
    - productID - The product ID.
    - shipment - Shipment

    **Returns:**
    - The new product line item


---

### createProductLineItem(String, Quantity, Shipment)
- ~~createProductLineItem(productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)~~
  - : Creates a new product line item in the container and assigns it to the specified shipment. 
      
      If the specified productID represents a product in the site catalog, the method will associate the product line
      item with that catalog product and will copy all order-relevant information, like the quantity unit, from the
      catalog product. 
      
      If the specified productID does not represent a product of the site catalog, the method creates a new product
      line item and initializes it with the specified product ID and quantity. If the passed in quantity value is not a
      positive integer, it will be rounded to the nearest positive integer. The minimum order quantity and step
      quantity will be set to 1.0. 
      
      For catalog products, the method follows the configured 'Add2Basket' strategy to either increment the quantity of
      an existing product line item or create a new product line item for the same product. For non-catalog products,
      the method creates a new product line item no matter if the same product is already in the line item container.
      If a negative quantity is specified, it is automatically changed to 1.0. 


    **Parameters:**
    - productID - The product ID.
    - quantity - The quantity of the product.
    - shipment - Shipment

    **Returns:**
    - the product line item

    **Deprecated:**
**warning:** Use [createProductLineItem(String, Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-shipment) or
            [ProductLineItem.updateQuantity(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#updatequantitynumber) instead.

---

### createShipment(String)
- createShipment(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Creates a standard shipment for the line item container. The specified ID must not yet be in use for another
      shipment of this line item container.


    **Parameters:**
    - id - ID of the shipment.


---

### createShippingPriceAdjustment(String)
- createShippingPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Creates a shipping price adjustment to be applied to the container. 
      
      The promotion ID is mandatory and must not be the ID of any actual promotion defined in B2C Commerce; otherwise
      the method will throw an exception. 
      
      If there already exists a shipping price adjustment referring to the specified promotion ID, an exception is
      thrown.


    **Parameters:**
    - promotionID - Promotion ID

    **Returns:**
    - The new price adjustment


---

### getAdjustedMerchandizeTotalGrossPrice()
- getAdjustedMerchandizeTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted total gross price (including tax) in purchase currency. Adjusted merchandize prices
      represent the sum of product prices before services such as shipping, but after product-level and order-level
      adjustments.


    **Returns:**
    - the adjusted total gross price (including tax) in purchase currency.


---

### getAdjustedMerchandizeTotalNetPrice()
- getAdjustedMerchandizeTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total net price (excluding tax) in purchase currency. Adjusted merchandize prices represent the sum
      of product prices before services such as shipping, but after product-level and order-level adjustments.


    **Returns:**
    - the total net price (excluding tax) in purchase currency.


---

### getAdjustedMerchandizeTotalPrice()
- getAdjustedMerchandizeTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted merchandize total price including product-level and order-level adjustments. If the line
      item container is based on net pricing the adjusted merchandize total net price is returned. If the line item
      container is based on gross pricing the adjusted merchandize total gross price is returned.


    **Returns:**
    - either the adjusted merchandize total net or gross price


---

### getAdjustedMerchandizeTotalPrice(Boolean)
- getAdjustedMerchandizeTotalPrice(applyOrderLevelAdjustments: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted merchandize total price including order-level adjustments if requested. If the line item
      container is based on net pricing the adjusted merchandize total net price is returned. If the line item
      container is based on gross pricing the adjusted merchandize total gross price is returned.


    **Parameters:**
    - applyOrderLevelAdjustments - controls if order-level price adjustements are applied. If true, the price that             is returned includes order-level price adjustments. If false, only product-level price adjustments are             applied.

    **Returns:**
    - a price representing the adjusted merchandize total controlled by the applyOrderLevelAdjustments
              parameter.



---

### getAdjustedMerchandizeTotalTax()
- getAdjustedMerchandizeTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the subtotal tax in purchase currency. Adjusted merchandize prices represent the sum of product prices
      before services such as shipping have been added, but after adjustment from promotions have been added.


    **Returns:**
    - the subtotal tax in purchase currency.


---

### getAdjustedShippingTotalGrossPrice()
- getAdjustedShippingTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted sum of all shipping line items of the line item container, including tax after shipping
      adjustments have been applied.


    **Returns:**
    - the adjusted sum of all shipping line items of the line item container, including tax after shipping
              adjustments have been applied.



---

### getAdjustedShippingTotalNetPrice()
- getAdjustedShippingTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of all shipping line items of the line item container, excluding tax after shipping adjustments
      have been applied.


    **Returns:**
    - the sum of all shipping line items of the line item container, excluding tax after shipping adjustments
              have been applied.



---

### getAdjustedShippingTotalPrice()
- getAdjustedShippingTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted shipping total price. If the line item container is based on net pricing the adjusted
      shipping total net price is returned. If the line item container is based on gross pricing the adjusted shipping
      total gross price is returned.


    **Returns:**
    - either the adjusted shipping total net or gross price


---

### getAdjustedShippingTotalTax()
- getAdjustedShippingTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax of all shipping line items of the line item container after shipping adjustments have been
      applied.


    **Returns:**
    - the tax of all shipping line items of the line item container after shipping adjustments have been
              applied.



---

### getAllGiftCertificateLineItems()
- ~~getAllGiftCertificateLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns all gift certificate line items of the container.

    **Returns:**
    - A collection of all GiftCertificateLineItems of the container.

    **Deprecated:**
**warning:** Use [getGiftCertificateLineItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitems) to get the collection instead.

---

### getAllLineItems()
- getAllLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product, shipping, price adjustment, and gift certificate line items of the line item container.

    **Returns:**
    - A collection of all product, shipping, price adjustment, and gift certificate line items of the
              container, in that order.



---

### getAllProductLineItems()
- getAllProductLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product line items of the container, no matter if they are dependent or independent. This includes
      option, bundled and bonus line items.


    **Returns:**
    - An unsorted collection of all ProductLineItem instances of the container.


---

### getAllProductLineItems(String)
- getAllProductLineItems(productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product line items of the container that have a product ID equal to the specified product ID, no
      matter if they are dependent or independent. This includes option, bundled and bonus line items.


    **Parameters:**
    - productID - The product ID used to filter the product line items.

    **Returns:**
    - An unsorted collection of all ProductLineItem instances which have the specified product ID.


---

### getAllProductQuantities()
- getAllProductQuantities(): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)
  - : Returns a hash mapping all products in the line item container to their total quantities. The total product
      quantity is used chiefly to validate the availability of the items in the cart. This method is not appropriate to
      look up prices because it returns products such as bundled line items which are included in the price of their
      parent and therefore have no corresponding price.
      
      
      The method counts all direct product line items, plus dependent product line items that are not option line
      items. It also excludes product line items that are not associated to any catalog product.


    **Returns:**
    - A map of products and their total quantities.


---

### getAllShippingPriceAdjustments()
- getAllShippingPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of all shipping price adjustments applied somewhere in the container. This can be
      adjustments applied to individual shipments or to the container itself. Note that the promotions engine only
      applies shipping price adjustments to the the default shipping line item of shipments, and never to the
      container.


    **Returns:**
    - an unsorted collection of the shipping PriceAdjustment instances associated with this container.

    **See Also:**
    - [getShippingPriceAdjustments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustments)


---

### getBillingAddress()
- getBillingAddress(): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)
  - : Returns the billing address defined for the container. Returns null if no billing address has been created yet.

    **Returns:**
    - the billing address or null.


---

### getBonusDiscountLineItems()
- getBonusDiscountLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an unsorted collection of the the bonus discount line items associated with this container.

    **Returns:**
    - An unsorted collection of BonusDiscountLine instances in the container.


---

### getBonusLineItems()
- getBonusLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of product line items that are bonus items (where
      [ProductLineItem.isBonusProductLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isbonusproductlineitem) is true).


    **Returns:**
    - the collection of product line items that are bonus items.


---

### getBusinessType()
- getBusinessType(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the type of the business this order has been placed in.
      
      Possible values are [BUSINESS_TYPE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2c) or [BUSINESS_TYPE_B2B](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#business_type_b2b).


    **Returns:**
    - the type of the business this order has been placed in. or null, if the business type is not set


---

### getChannelType()
- getChannelType(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : The channel type defines in which sales channel this order has been created. This can be used to distinguish
      order placed through Storefront, Call Center or Marketplace.
      
      Possible values are [CHANNEL_TYPE_STOREFRONT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_storefront), [CHANNEL_TYPE_CALLCENTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_callcenter),
      [CHANNEL_TYPE_MARKETPLACE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_marketplace), [CHANNEL_TYPE_DSS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_dss), [CHANNEL_TYPE_STORE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_store),
      [CHANNEL_TYPE_PINTEREST](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_pinterest), [CHANNEL_TYPE_TWITTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_twitter), [CHANNEL_TYPE_FACEBOOKADS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_facebookads),
      [CHANNEL_TYPE_SUBSCRIPTIONS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_subscriptions), [CHANNEL_TYPE_ONLINERESERVATION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_onlinereservation),
      [CHANNEL_TYPE_CUSTOMERSERVICECENTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_customerservicecenter), [CHANNEL_TYPE_INSTAGRAMCOMMERCE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_instagramcommerce),
      [CHANNEL_TYPE_GOOGLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_google), [CHANNEL_TYPE_YOUTUBE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_youtube), [CHANNEL_TYPE_TIKTOK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_tiktok),
      [CHANNEL_TYPE_SNAPCHAT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_snapchat), [CHANNEL_TYPE_WHATSAPP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_whatsapp), [CHANNEL_TYPE_CHATGPT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_chatgpt),
      [CHANNEL_TYPE_GEMINI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#channel_type_gemini)


    **Returns:**
    - the sales channel this order has been placed in or null, if the order channel is not set


---

### getCouponLineItem(String)
- getCouponLineItem(couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)
  - : Returns the coupon line item representing the specified coupon code.

    **Parameters:**
    - couponCode - the coupon code.

    **Returns:**
    - coupon line item or null.


---

### getCouponLineItems()
- getCouponLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of the coupon line items in the container. The coupon line items are returned in the
      order they were added to container.


    **Returns:**
    - A sorted list of the CouponLineItem instances in the container.


---

### getCurrencyCode()
- getCurrencyCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the currency code for this line item container. The currency code is a 3-character currency mnemonic such
      as 'USD' or 'EUR'. The currency code represents the currency in which the calculation is made, and in which the
      buyer sees all prices in the store front.


    **Returns:**
    - the currency code for this line item container.


---

### getCustomer()
- getCustomer(): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer associated with this container.

    **Returns:**
    - the customer associated with this container.


---

### getCustomerEmail()
- getCustomerEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email of the customer associated with this container.

    **Returns:**
    - the email of the customer associated with this container.


---

### getCustomerName()
- getCustomerName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the customer associated with this container.

    **Returns:**
    - the name of the customer associated with this container.


---

### getCustomerNo()
- getCustomerNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer number of the customer associated with this container.

    **Returns:**
    - the customer number of the customer associated with this container.


---

### getDefaultShipment()
- getDefaultShipment(): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Returns the default shipment of the line item container. Baskets always have a default shipment with ID "me".
      For orders, this can differ, for example: [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) removes empty
      shipments, so if the basket's "me" shipment was empty at order creation, the order has no "me" shipment. In
      that case, the shipment with the lowest ID is returned as the fallback, or `null` if the order has
      no shipments. See [Shipment.isDefault()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#isdefault) for the matching logic.
      
      
      Processes that access a shipment use the default shipment when none is specified. The default shipment can't be
      removed. Calling [removeShipment(Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshipmentshipment) on it throws an exception.


    **Returns:**
    - the default shipment of the container, or `null` if the order has no shipments


---

### getEtag()
- getEtag(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Etag of the line item container. The Etag is a hash that represents the overall container state
      including any associated objects like line items.


    **Returns:**
    - the Etag value


---

### getGiftCertificateLineItems()
- getGiftCertificateLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all gift certificate line items of the container.

    **Returns:**
    - A collection of all GiftCertificateLineItems of the container.


---

### getGiftCertificateLineItems(String)
- getGiftCertificateLineItems(giftCertificateId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all gift certificate line items of the container, no matter if they are dependent or independent.

    **Parameters:**
    - giftCertificateId - the gift certificate identifier.

    **Returns:**
    - A collection of all GiftCertificateLineItems of the container.


---

### getGiftCertificatePaymentInstruments()
- getGiftCertificatePaymentInstruments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an unsorted collection of the PaymentInstrument instances that represent GiftCertificates in this
      container.


    **Returns:**
    - an unsorted collection containing the set of PaymentInstrument instances that represent GiftCertificates.


---

### getGiftCertificatePaymentInstruments(String)
- getGiftCertificatePaymentInstruments(giftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an unsorted collection containing all PaymentInstruments of type
      PaymentInstrument.METHOD\_GIFT\_CERTIFICATE where the specified code is the same code on the payment instrument.


    **Parameters:**
    - giftCertificateCode - the gift certificate code.

    **Returns:**
    - an unsorted collection containing all PaymentInstruments of type
              PaymentInstrument.METHOD\_GIFT\_CERTIFICATE where the specified code is the same code on the payment
              instrument.



---

### getGiftCertificateTotalGrossPrice()
- getGiftCertificateTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total gross price of all gift certificates in the cart. Should usually be equal to total net price.

    **Returns:**
    - the total gross price of all gift certificate line items


---

### getGiftCertificateTotalNetPrice()
- getGiftCertificateTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total net price (excluding tax) of all gift certificates in the cart. Should usually be equal to
      total gross price.


    **Returns:**
    - the total net price of all gift certificate line items


---

### getGiftCertificateTotalPrice()
- getGiftCertificateTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the gift certificate total price. If the line item container is based on net pricing the gift certificate
      total net price is returned. If the line item container is based on gross pricing the gift certificate total
      gross price is returned.


    **Returns:**
    - either the gift certificate total net or gross price


---

### getGiftCertificateTotalTax()
- getGiftCertificateTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total tax of all gift certificates in the cart. Should usually be 0.0.

    **Returns:**
    - the total tax of all gift certificate line items


---

### getMerchandizeTotalGrossPrice()
- getMerchandizeTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total gross price (including tax) in purchase currency. Merchandize total prices represent the sum of
      product prices before services such as shipping or adjustment from promotions have been added.


    **Returns:**
    - the total gross price (including tax) in purchase currency.


---

### getMerchandizeTotalNetPrice()
- getMerchandizeTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total net price (excluding tax) in purchase currency. Merchandize total prices represent the sum of
      product prices before services such as shipping or adjustment from promotion have been added.


    **Returns:**
    - the total net price (excluding tax) in purchase currency.


---

### getMerchandizeTotalPrice()
- getMerchandizeTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the merchandize total price. If the line item container is based on net pricing the merchandize total net
      price is returned. If the line item container is based on gross pricing the merchandize total gross price is
      returned.


    **Returns:**
    - either the merchandize total net or gross price


---

### getMerchandizeTotalTax()
- getMerchandizeTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total tax in purchase currency. Merchandize total prices represent the sum of product prices before
      services such as shipping or adjustment from promotions have been added.


    **Returns:**
    - the total tax in purchase currency.


---

### getNotes()
- getNotes(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the list of notes for this object, ordered by creation time from oldest to newest.

    **Returns:**
    - the list of notes for this object, ordered by creation time from oldest to newest.


---

### getPaymentInstrument()
- ~~getPaymentInstrument(): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)~~
  - : Returns the payment instrument of the line item container or null. This method is deprecated. You should use
      getPaymentInstruments() or getGiftCertificatePaymentInstruments() instead.


    **Returns:**
    - the order payment instrument of the line item container or null.

    **Deprecated:**
**warning:** Use [getPaymentInstruments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstruments) or [getGiftCertificatePaymentInstruments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstruments) to get the
            set of payment instruments.

---

### getPaymentInstruments()
- getPaymentInstruments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an unsorted collection of the payment instruments in this container.

    **Returns:**
    - an unsorted collection containing the set of PaymentInstrument instances associated with this container.


---

### getPaymentInstruments(String)
- getPaymentInstruments(paymentMethodID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an unsorted collection of PaymentInstrument instances based on the specified payment method ID.

    **Parameters:**
    - paymentMethodID - the ID of the payment method used.

    **Returns:**
    - an unsorted collection of OrderPaymentInstrument instances based on the payment method.


---

### getPriceAdjustmentByPromotionID(String)
- getPriceAdjustmentByPromotionID(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Returns the price adjustment associated to the specified promotion ID.

    **Parameters:**
    - promotionID - Promotion id

    **Returns:**
    - The price adjustment associated with the specified promotion ID or null if none was found.


---

### getPriceAdjustments()
- getPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of price adjustments that have been applied to the totals such as promotion on the
      purchase value (i.e. $10 Off or 10% Off). The price adjustments are sorted by the order in which they were
      applied to the order by the promotions engine.


    **Returns:**
    - the sorted collection of PriceAdjustment instances.


---

### getProductLineItems()
- getProductLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the product line items of the container that are not dependent on other product line items. This includes
      line items representing bonus products in the container but excludes option, bundled, and bonus line items. The
      returned collection is sorted by the position attribute of the product line items.


    **Returns:**
    - A sorted collection of ProductLineItem instances which are not dependent on other product line items.


---

### getProductLineItems(String)
- getProductLineItems(productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the product line items of the container that have a product ID equal to the specified product ID and that
      are not dependent on other product line items. This includes line items representing bonus products in the
      container, but excludes option, bundled and bonus line items. The returned collection is sorted by the position
      attribute of the product line items.


    **Parameters:**
    - productID - The Product ID used to filter the product line items.

    **Returns:**
    - A sorted collection of ProductLineItem instances which have the specified product ID and are not
              dependent on other product line items.



---

### getProductQuantities()
- getProductQuantities(): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)
  - : Returns a hash map of all products in the line item container and their total quantities. The total product
      quantity is for example used to lookup the product price.
      
      
      The method counts all direct product line items, plus dependent product line items that are not bundled line
      items and no option line items. It also excludes product line items that are not associated to any catalog
      product, and bonus product line items.


    **Returns:**
    - a map of products and their total quantities.

    **See Also:**
    - [getProductQuantities(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitiesboolean)


---

### getProductQuantities(Boolean)
- getProductQuantities(includeBonusProducts: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)
  - : Returns a hash map of all products in the line item container and their total quantities. The total product
      quantity is for example used to lookup the product price in the cart.
      
      
      The method counts all direct product line items, plus dependent product line items that are not bundled line
      items and no option line items. It also excludes product line items that are not associated to any catalog
      product.
      
      
      If the parameter 'includeBonusProducts' is set to true, the method also counts bonus product line items.


    **Parameters:**
    - includeBonusProducts - if true also bonus product line item are counted

    **Returns:**
    - A map of products and their total quantities.


---

### getProductQuantityTotal()
- getProductQuantityTotal(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the total quantity of all product line items. Not included are bundled line items and option line items.

    **Returns:**
    - The total quantity of all line items of the container.


---

### getShipment(String)
- getShipment(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Returns the shipment for the specified ID or `null` if no shipment with this ID exists in the line
      item container. Using "me" always returns the default shipment.


    **Parameters:**
    - id - the shipment identifier

    **Returns:**
    - the shipment or `null`


---

### getShipments()
- getShipments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all shipments of the line item container.
      
      The first shipment in the returned collection is the default shipment (shipment ID always set to "me"). All other
      shipments are sorted ascending by shipment ID.


    **Returns:**
    - all shipments of the line item container


---

### getShippingPriceAdjustmentByPromotionID(String)
- getShippingPriceAdjustmentByPromotionID(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Returns the shipping price adjustment associated with the specified promotion ID.

    **Parameters:**
    - promotionID - Promotion id

    **Returns:**
    - The price adjustment associated with the specified promotion ID or null if none was found.


---

### getShippingPriceAdjustments()
- getShippingPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the of shipping price adjustments applied to the shipping total of the container. Note that the
      promotions engine only applies shipping price adjustments to the the default shipping line item of shipments, and
      never to the container.


    **Returns:**
    - a collection of shipping price adjustments.

    **See Also:**
    - [getAllShippingPriceAdjustments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallshippingpriceadjustments)


---

### getShippingTotalGrossPrice()
- getShippingTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of all shipping line items of the line item container, including tax before shipping adjustments
      have been applied.


    **Returns:**
    - the sum of all shipping line items of the line item container, including tax before shipping adjustments
              have been applied.



---

### getShippingTotalNetPrice()
- getShippingTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of all shipping line items of the line item container, excluding tax before shipping adjustments
      have been applied.


    **Returns:**
    - the sum of all shipping line items of the line item container, excluding tax before shipping adjustments
              have been applied.



---

### getShippingTotalPrice()
- getShippingTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the shipping total price. If the line item container is based on net pricing the shipping total net price
      is returned. If the line item container is based on gross pricing the shipping total gross price is returned.


    **Returns:**
    - either the shipping total net or gross price


---

### getShippingTotalTax()
- getShippingTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax of all shipping line items of the line item container before shipping adjustments have been
      applied.


    **Returns:**
    - the tax of all shipping line items of the line item container before shipping adjustments have been
              applied.



---

### getTaxTotalsPerTaxRate()
- getTaxTotalsPerTaxRate(): [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)
  - : This method returns a [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md) in which the keys are [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) tax rates and the values
      are [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) total tax for the tax rate. The map is unmodifiable.


    **Returns:**
    - sorted map of tax rate against total tax


---

### getTotalGrossPrice()
- getTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the grand total price gross of tax for LineItemCtnr, in purchase currency. Total prices represent the sum
      of product prices, services prices and adjustments.


    **Returns:**
    - the grand total price.


---

### getTotalNetPrice()
- getTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the grand total price for LineItemCtnr net of tax, in purchase currency. Total prices represent the sum
      of product prices, services prices and adjustments.


    **Returns:**
    - the grand total price.


---

### getTotalTax()
- getTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the grand total tax for LineItemCtnr, in purchase currency. Total prices represent the sum of product
      prices, services prices and adjustments.


    **Returns:**
    - the grand total tax.


---

### isExternallyTaxed()
- isExternallyTaxed(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Use this method to check whether the LineItemCtnr is calculated based on external tax tables.
      
      Note: a basket can only be created in EXTERNAL tax mode using SCAPI.


    **Returns:**
    - `true` if the LineItemCtnr was calculated based on external tax tables.


---

### isTaxRoundedAtGroup()
- isTaxRoundedAtGroup(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Use this method to check if the LineItemCtnr was calculated with grouped taxation calculation.
      
      
      If the tax is rounded on group level, the tax is applied to the summed-up tax basis for each tax rate.


    **Returns:**
    - `true` if the LineItemCtnr was calculated with grouped taxation


---

### removeAllPaymentInstruments()
- removeAllPaymentInstruments(): void
  - : Removes the all Payment Instruments from this container and deletes the Payment Instruments.


---

### removeBonusDiscountLineItem(BonusDiscountLineItem)
- removeBonusDiscountLineItem(bonusDiscountLineItem: [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md)): void
  - : Removes the specified bonus discount line item from the line item container.

    **Parameters:**
    - bonusDiscountLineItem - The bonus discount line item to remove, must not be null.


---

### removeCouponLineItem(CouponLineItem)
- removeCouponLineItem(couponLineItem: [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)): void
  - : Removes the specified coupon line item from the line item container.

    **Parameters:**
    - couponLineItem - The coupon line item to remove


---

### removeGiftCertificateLineItem(GiftCertificateLineItem)
- removeGiftCertificateLineItem(giftCertificateLineItem: [GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md)): void
  - : Removes the specified gift certificate line item from the line item container.

    **Parameters:**
    - giftCertificateLineItem - The gift certificate line item to remove


---

### removeNote(Note)
- removeNote(note: [Note](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md)): void
  - : Removes a note from this line item container and deletes it.

    **Parameters:**
    - note - The note to remove. Must not be null. Must belong to this line item container.


---

### removePaymentInstrument(PaymentInstrument)
- removePaymentInstrument(pi: [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md)): void
  - : Removes the specified Payment Instrument from this container and deletes the Payment Instrument.

    **Parameters:**
    - pi - the Payment Instrument to remove.


---

### removePriceAdjustment(PriceAdjustment)
- removePriceAdjustment(priceAdjustment: [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)): void
  - : Removes the specified price adjustment line item from the line item container.

    **Parameters:**
    - priceAdjustment - The price adjustment line item to remove, must not be null.


---

### removeProductLineItem(ProductLineItem)
- removeProductLineItem(productLineItem: [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)): void
  - : Removes the specified product line item from the line item container.

    **Parameters:**
    - productLineItem - The product line item to remove, must not be null.


---

### removeShipment(Shipment)
- removeShipment(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): void
  - : Removes the specified shipment and all associated product, gift certificate, shipping and price adjustment line
      items from the line item container. It is not permissible to remove the default shipment.


    **Parameters:**
    - shipment - Shipment to be removed, must not be null.


---

### removeShippingPriceAdjustment(PriceAdjustment)
- removeShippingPriceAdjustment(priceAdjustment: [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)): void
  - : Removes the specified shipping price adjustment line item from the line item container.

    **Parameters:**
    - priceAdjustment - The price adjustment line item to remove, must not be null.


---

### setCustomerEmail(String)
- setCustomerEmail(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the email address of the customer associated with this container.

    **Parameters:**
    - aValue - the email address of the customer associated with this container.


---

### setCustomerName(String)
- setCustomerName(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the customer associated with this container.

    **Parameters:**
    - aValue - the name of the customer associated with this container.


---

### updateOrderLevelPriceAdjustmentTax()
- updateOrderLevelPriceAdjustmentTax(): void
  - : Calculates the tax for all shipping and order-level merchandise price adjustments in this LineItemCtnr.
      
      
      The tax on each adjustment is calculated from the taxes of the line items the adjustment applies across.
      
      
      **This method must be invoked at the end of tax calculation of a basket or an order.**



---

### updateTotals()
- updateTotals(): void
  - : Recalculates the totals of the line item container. It is necessary to call this method after any type of
      modification to the basket.



---

### verifyPriceAdjustmentLimits()
- verifyPriceAdjustmentLimits(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Verifies whether the manual price adjustments made for the line item container exceed the corresponding limits
      for the current user and the current site.
      
      
      The results of this method are based on the current values held in the [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), such as the
      base price of manual price adjustments. It is important the method is only called after the calculation process
      has completed.
      
      
      
      
      Status.OK is returned if NONE of the manual price adjustments exceed the correspondent limits.
      
      
      Status.ERROR is returned if ANY of the manual price adjustments exceed the correspondent limits. If this case
      [Status.getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getitems) returns all price adjustment limit violations. The code of each
      [StatusItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md) represents the violated price adjustment type (see
      [PriceAdjustmentLimitTypes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustmentLimitTypes.md)). [StatusItem.getDetails()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getdetails) returns a
      [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) with the max amount and (where relevant) the item to which the violation applies.
      
      
      Usage:
      
      
      ```
      var order : Order; // known
      
      var status : Status = order.verifyPriceAdjustmentLimits();
      if (status.status == Status.ERROR)
      {
        for each (var statusItem : StatusItem in status.items)
        {
            var statusDetail : MapEntry = statusItem.details.entrySet().iterator().next();
            var maxAllowedLimit : Number = (Number) (statusDetail.key);
      
            if (statusItem.code == PriceAdjustmentLimitTypes.TYPE_ORDER)
            {
                // fix order price adjustment considering maxAllowedLimit
            }
            else if (statusItem.code == PriceAdjustmentLimitTypes.TYPE_ITEM)
            {
                var pli : ProductLineItem = (ProductLineItem) (statusDetail.value);
                // fix pli price adjustment considering maxAllowedLimit
            }
            else if (statusItem.code == PriceAdjustmentLimitTypes.TYPE_SHIPPING)
            {
                if (statusDetail.value == null)
                {
                    // fix order level shipping price adjustment considering maxAllowedLimit
                }
                else
                {
                    var sli : ShippingLineItem = (ShippingLineItem) (statusDetail.value);
                    // fix sli price adjustment considering maxAllowedLimit
                }
            }
        }
      }
      ```


    **Returns:**
    - a Status instance with - Status.OK if all manual price adjustments do not exceed the correspondent
              limits, otherwise Status.ERROR



---

<!-- prettier-ignore-end -->

<!-- document id=bc2cf5a4f648e979fa852b354766328fb6e167dbffb08e7d46e2ddf313a0e3a1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.LineItemTax.md -->

<!-- prettier-ignore-start -->
# Class LineItemTax

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md)

A tax on a line item: tax identifier, rate, and optional amount. Use with [LineItem.setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)
and [LineItem.getTaxes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes).


Create instances via [new LineItemTax(taxId, taxRate)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md#lineitemtaxstring-number) to have the
server compute the tax value, or via [new LineItemTax(taxId, taxRate, taxValue)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md#lineitemtaxstring-number-money)
to provide a pre-computed tax value.


**See Also:**
- [LineItem.getTaxes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes)
- [LineItem.setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection)


## Property Summary

| Property | Description |
| --- | --- |
| [taxId](#taxid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the tax identifier (for example, |
| [taxRate](#taxrate): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Gets the tax rate as a decimal (for example, |
| [taxValue](#taxvalue): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Gets the tax value (amount) in purchase currency, or null if computed from rate and tax basis. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [LineItemTax](#lineitemtaxstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a tax item for use with [LineItem.setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection). |
| [LineItemTax](#lineitemtaxstring-number-money)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Creates a tax item for use with [LineItem.setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection). |

## Method Summary

| Method | Description |
| --- | --- |
| [getTaxId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md#gettaxid)() | Gets the tax identifier (for example, |
| [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md#gettaxrate)() | Gets the tax rate as a decimal (for example, |
| [getTaxValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md#gettaxvalue)() | Gets the tax value (amount) in purchase currency, or null if computed from rate and tax basis. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### taxId
- taxId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the tax identifier (for example, "DE\_7").


---

### taxRate
- taxRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Gets the tax rate as a decimal (for example, 0.07 for 7%).


---

### taxValue
- taxValue: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Gets the tax value (amount) in purchase currency, or null if computed from rate and tax basis.


---

## Constructor Details

### LineItemTax(String, Number)
- LineItemTax(taxId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), taxRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a tax item for use with [LineItem.setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection). The tax value will be computed
      server-side from the tax rate and the line item's tax basis.


    **Parameters:**
    - taxId - tax identifier (for example, "DE\_7"), must not be null or blank
    - taxRate - tax rate as decimal (for example, 0.07 for 7%), must not be null


---

### LineItemTax(String, Number, Money)
- LineItemTax(taxId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), taxRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), taxValue: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md))
  - : Creates a tax item for use with [LineItem.setTaxes(Collection)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection).


    **Parameters:**
    - taxId - tax identifier (for example, "DE\_7"), must not be null or blank
    - taxRate - tax rate as decimal (for example, 0.07 for 7%), must not be null
    - taxValue - tax amount in purchase currency, or null to compute from rate and tax basis


---

## Method Details

### getTaxId()
- getTaxId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the tax identifier (for example, "DE\_7").

    **Returns:**
    - the tax id


---

### getTaxRate()
- getTaxRate(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Gets the tax rate as a decimal (for example, 0.07 for 7%).

    **Returns:**
    - the tax rate


---

### getTaxValue()
- getTaxValue(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Gets the tax value (amount) in purchase currency, or null if computed from rate and tax basis.

    **Returns:**
    - the tax value as Money, or null


---

<!-- prettier-ignore-end -->

<!-- document id=a7502913660f8c2f2f83548d9e3b5a9bd18b17d47f08d3d6383a37ff9a2a00a9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.LinkedHashMap.md -->

<!-- prettier-ignore-start -->
# Class LinkedHashMap

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
    - [dw.util.LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)

This class implements a HashMap, which guarantees a iteration order
according the put-order of the elements in the map.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [LinkedHashMap](#linkedhashmap)() | Constructs a new LinkedHashMap. |

## Method Summary

| Method | Description |
| --- | --- |
| [clone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md#clone)() | Returns a shallow copy of this map. |

### Methods inherited from class Map

[clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#clear), [containsKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containskeyobject), [containsValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containsvalueobject), [entrySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#entryset), [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getobject), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#isempty), [keySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#keyset), [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putobject-object), [putAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putallmap), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#removeobject), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#size), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-1), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-2)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### LinkedHashMap()
- LinkedHashMap()
  - : Constructs a new LinkedHashMap.


---

## Method Details

### clone()
- clone(): [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)
  - : Returns a shallow copy of this map.

    **Returns:**
    - a shallow copy of this map.


---

<!-- prettier-ignore-end -->

<!-- document id=dab4bd4f02848cb28a404d520da1c2f22a3b35aa5d607b919b6b67c426b42e23 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.LinkedHashSet.md -->

<!-- prettier-ignore-start -->
# Class LinkedHashSet

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
    - [dw.util.Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
      - [dw.util.LinkedHashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashSet.md)

The class LinkedHashSet implements a hash set with a guaranteed iteration
order. The elements are iterated in the order they have been added to the
HashSet.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [LinkedHashSet](#linkedhashset)() | Constructs a new LinkHashSet. |
| [LinkedHashSet](#linkedhashsetcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Constructor for a new LinkedHashSet. |

## Method Summary

| Method | Description |
| --- | --- |
| [clone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashSet.md#clone)() | Returns a shallow copy of this set. |

### Methods inherited from class Collection

[add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject), [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object), [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection), [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear), [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject), [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty), [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject), [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection), [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### LinkedHashSet()
- LinkedHashSet()
  - : Constructs a new LinkHashSet.


---

### LinkedHashSet(Collection)
- LinkedHashSet(collection: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))
  - : Constructor for a new LinkedHashSet. The constructor
      initializes the LinkedHashSet with the elements of the
      given collection.


    **Parameters:**
    - collection - the collection of items to insert into this set.


---

## Method Details

### clone()
- clone(): [LinkedHashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashSet.md)
  - : Returns a shallow copy of this set.

    **Returns:**
    - a shallow copy of this set.


---

<!-- prettier-ignore-end -->

<!-- document id=a6f2a1c4e7efd5c60ee724181e7c35f5792d116fe472d8936cef0210d9c4648d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.List.md -->

<!-- prettier-ignore-start -->
# Class List

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
    - [dw.util.List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)

An ordered collection of objects. The user of a List has precise control over
where in the list each element is inserted. The user can access elements by
their integer index (position in the list), and search for elements in the
list. Lists are zero based similar to arrays. Unlike sets, lists allow
duplicate elements.



## All Known Subclasses
[ArrayList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.ArrayList.md)
## Property Summary

| Property | Description |
| --- | --- |
| [EMPTY_LIST](#empty_list): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Convenience variable, for an empty and immutable list. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#addatnumber-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds the specified object into the list at the specified index. |
| [concat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#concatobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates and returns a new List that is the result of concatenating this  list with each of the specified values. |
| [fill](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#fillobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Replaces all of the elements in the list with the given object. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the object at the specified index. |
| [indexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#indexofobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the index of the first occurrence of the specified element in  this list, or -1 if this list does not contain the element. |
| [join](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#join)() | Converts all elements of the list to a string by calling the toString()  method and then concatenates them together, with a comma between  elements. |
| [join](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#joinstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Converts all elements of the list to a string by calling the toString()  method and then concatenates them together, with the separator string  between elements. |
| [lastIndexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#lastindexofobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the index of the last occurrence of the specified element in this  list, or -1 if this list does not contain the element. |
| [pop](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#pop)() | Removes and returns the last element from the list. |
| [push](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#pushobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Appends the specified values to the end of the list in order. |
| [removeAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#removeatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Removes the object at the specified index. |
| [replaceAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#replaceallobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Replaces all occurrences of oldValue with newValue. |
| [reverse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#reverse)() | Reverses the order of the elements in the list. |
| [rotate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#rotatenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Rotates the elements in the list by the specified distance. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#setnumber-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Replaces the object at the specified index in this list with the specified object. |
| [shift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#shift)() | Removes and returns the first element of the list. |
| [shuffle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#shuffle)() | Randomly permutes the elements in the list. |
| [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#size)() | Returns the size of this list. |
| [slice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#slicenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a slice, or sublist, of this list. |
| [slice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#slicenumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a slice, or sublist, of this list. |
| [sort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#sort)() | Sorts the elements of the list based on their natural  order. |
| [sort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#sortobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sorts the elements of a list. |
| [subList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#sublistnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a list containing the elements in this list identified  by the specified arguments. |
| [swap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#swapnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Swaps the elements at the specified positions in the list. |
| [unshift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md#unshiftobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Inserts values at the beginning of the list. |

### Methods inherited from class Collection

[add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject), [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object), [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection), [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear), [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject), [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty), [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject), [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection), [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### EMPTY_LIST
- EMPTY_LIST: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Convenience variable, for an empty and immutable list.


---

## Method Details

### addAt(Number, Object)
- addAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Adds the specified object into the list at the specified index.

    **Parameters:**
    - index - the index to use.
    - value - the object to insert.


---

### concat(Object...)
- concat(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Creates and returns a new List that is the result of concatenating this
      list with each of the specified values. This list itself is unmodified.
      If any of the specified values is itself an array or a Collection, then
      the elements of that Collection or array are appended to the new list
      rather than the object itself.


    **Parameters:**
    - values - one or more objects to concatenate.

    **Returns:**
    - a new List that is the result of concatenating this
      list with each of the specified values.



---

### fill(Object)
- fill(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Replaces all of the elements in the list with the given object.

    **Parameters:**
    - obj - the object to use during replacement.


---

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the object at the specified index.

    **Parameters:**
    - index - the index to use.

    **Returns:**
    - the object at the specified index.


---

### indexOf(Object)
- indexOf(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index of the first occurrence of the specified element in
      this list, or -1 if this list does not contain the element.


    **Parameters:**
    - value - the element to use.

    **Returns:**
    - the index of the specified object or -1 if the passed object is
              not found in the list.



---

### join()
- join(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts all elements of the list to a string by calling the toString()
      method and then concatenates them together, with a comma between
      elements.


    **Returns:**
    - The string that results from converting each element of the list
              to a string and then concatenating them together, with a comma
              between elements.



---

### join(String)
- join(separator: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts all elements of the list to a string by calling the toString()
      method and then concatenates them together, with the separator string
      between elements. If null is passed, then the comma character is used as
      a separator.


    **Parameters:**
    - separator - The separator string. May be null in which case the             comma character is used.

    **Returns:**
    - The string that results from converting each element of the list
              to a string and then concatenating them together, with the
              separator string between elements.



---

### lastIndexOf(Object)
- lastIndexOf(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index of the last occurrence of the specified element in this
      list, or -1 if this list does not contain the element.


    **Parameters:**
    - value - the element to use.

    **Returns:**
    - the last index of the specified object or -1 if the passed object
              is not found in the list.



---

### pop()
- pop(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Removes and returns the last element from the list.

    **Returns:**
    - The last element of the list or null if the list is already
              empty.



---

### push(Object...)
- push(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Appends the specified values to the end of the list in order.

    **Parameters:**
    - values - One or more values to be appended to the end of the list.

    **Returns:**
    - The new length of the list, after the specified values are
              appended to it.



---

### removeAt(Number)
- removeAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Removes the object at the specified index.

    **Parameters:**
    - index - the index to use.

    **Returns:**
    - the object that was removed.


---

### replaceAll(Object, Object)
- replaceAll(oldValue: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), newValue: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Replaces all occurrences of oldValue with newValue.

    **Parameters:**
    - oldValue - the old object.
    - newValue - the new object.

    **Returns:**
    - true if one or more elements were replaced, false otherwise.


---

### reverse()
- reverse(): void
  - : Reverses the order of the elements in the list.


---

### rotate(Number)
- rotate(distance: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Rotates the elements in the list by the specified distance.

    **Parameters:**
    - distance - the distance to use.


---

### set(Number, Object)
- set(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Replaces the object at the specified index in this list with the specified object.

    **Parameters:**
    - index - the index to use.
    - value - the object to use when replacing the existing object.

    **Returns:**
    - the replaced object.


---

### shift()
- shift(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Removes and returns the first element of the list. If the list is already
      empty, this method simply returns null.


    **Returns:**
    - The former first element of the list, or null is list is already
              empty.



---

### shuffle()
- shuffle(): void
  - : Randomly permutes the elements in the list.


---

### size()
- size(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of this list.

    **Returns:**
    - the size of this list.


---

### slice(Number)
- slice(from: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a slice, or sublist, of this list. The returned list contains the
      element specified by `from` and all subsequent elements up to
      the end of this list.


    **Parameters:**
    - from - The index at which the slice is to begin. If negative, this             argument specifies a position measured from the end of this             list. That, -1 indicates the last element, -2 indicates the             next from the last element, and so on.

    **Returns:**
    - A new List that contains the elements of this list from the
              element specified by `from` up to the end of this
              list.



---

### slice(Number, Number)
- slice(from: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), to: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a slice, or sublist, of this list. The returned list contains the
      element specified by `from` and all subsequent elements up to,
      but not including, the element specified by `to`.


    **Parameters:**
    - from - The index at which the slice is to begin. If negative, this             argument specifies a position measured from the end of this             list. That, -1 indicates the last element, -2 indicates the             next from the last element, and so on.
    - to - The index immediately after the end of the slice. If this             argument is negative, it specifies an element measured from             the end of this list.

    **Returns:**
    - A new List that contains the elements of this list from the
              element specified by `from` up to, but not including,
              the element specified by `to`.



---

### sort()
- sort(): void
  - : Sorts the elements of the list based on their natural
      order.
      
      
      This sort is guaranteed to be _stable_:  equal elements will
      not be reordered as a result of the sort.



---

### sort(Object)
- sort(comparator: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sorts the elements of a list. The order of the elements is
      determined with a comparator (see PropertyComparator) or with the help
      of the given function. The function must take two parameters and return
      a value <0 if the first parameter is smaller than the second, a value
      of 0 if both are equal and a value if >0 if the first one is greater
      than the second parameter.
      
      
      This sort is guaranteed to be _stable_:  equal elements will
      not be reordered as a result of the sort.


    **Parameters:**
    - comparator - an instance of a PropertyComparator or a comparison function


---

### subList(Number, Number)
- subList(from: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), to: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list containing the elements in this list identified
      by the specified arguments.


    **Parameters:**
    - from - the beginning index of the elements to move to the new list.
    - to - the ending index of the elements to move to the new list.

    **Returns:**
    - the new list containing the elements.


---

### swap(Number, Number)
- swap(i: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), j: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Swaps the elements at the specified positions in the list.

    **Parameters:**
    - i - the first element to swap.
    - j - the second element to swap.


---

### unshift(Object...)
- unshift(values: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Inserts values at the beginning of the list.  The first argument
      becomes the new element 0;  the second argument becomes element 1;
      and so on.


    **Parameters:**
    - values - The values to insert into the list.

    **Returns:**
    - The new length of the lest.


---

<!-- prettier-ignore-end -->

<!-- document id=c06d67ecbf0dba66c4d2af4088da965df14978afa31d32d43850bc2f28ab4965 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Locale.md -->

<!-- prettier-ignore-start -->
# Class Locale

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Locale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md)

Represents a Locale supported by the system.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the String representation of the localeID. |
| [ISO3Country](#iso3country): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the uppercase ISO 3166 3-letter country/region code for this Locale. |
| [ISO3Language](#iso3language): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the 3-letter ISO 639 language code for this Locale. |
| [country](#country): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the uppercase ISO 3166 2-letter country/region code for this Locale. |
| [displayCountry](#displaycountry): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of this Locale's country, in this Locale's language,  not in the session locale's language. |
| [displayLanguage](#displaylanguage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of this Locale's language, in this Locale's language,  not in the session locale's language. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of this Locale, in this Locale's language,  not in the session locale's language. |
| [language](#language): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the lowercase ISO 639 language code for this Locale. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCountry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getcountry)() | Returns the uppercase ISO 3166 2-letter country/region code for this Locale. |
| [getDisplayCountry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getdisplaycountry)() | Returns the display name of this Locale's country, in this Locale's language,  not in the session locale's language. |
| [getDisplayLanguage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getdisplaylanguage)() | Returns the display name of this Locale's language, in this Locale's language,  not in the session locale's language. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getdisplayname)() | Returns the display name of this Locale, in this Locale's language,  not in the session locale's language. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getid)() | Returns the String representation of the localeID. |
| [getISO3Country](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getiso3country)() | Returns the uppercase ISO 3166 3-letter country/region code for this Locale. |
| [getISO3Language](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getiso3language)() | Returns the 3-letter ISO 639 language code for this Locale. |
| [getLanguage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getlanguage)() | Returns the lowercase ISO 639 language code for this Locale. |
| static [getLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#getlocalestring---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a Locale instance for the given localeId, or  `null` if no such Locale could be found. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md#tostring)() | Returns the String representation of the localeID. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the String representation of the localeID.
      
      
      Combines the language and the country key, concatenated with "\_". 
      For example: "en\_US". This attribute is the primary key of the class.



---

### ISO3Country
- ISO3Country: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the uppercase ISO 3166 3-letter country/region code for this Locale.
      If no country has been specified for this Locale, this value is an empty string.



---

### ISO3Language
- ISO3Language: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the 3-letter ISO 639 language code for this Locale.
      If no language has been specified for this Locale, this value is an empty string.



---

### country
- country: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the uppercase ISO 3166 2-letter country/region code for this Locale.
      If no country has been specified for this Locale, this value is an empty string.



---

### displayCountry
- displayCountry: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of this Locale's country, in this Locale's language,
      not in the session locale's language.
      If no country has been specified for this Locale, this value is an empty string.



---

### displayLanguage
- displayLanguage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of this Locale's language, in this Locale's language,
      not in the session locale's language.
      If no country has been specified for this Locale, this value is an empty string.



---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of this Locale, in this Locale's language,
      not in the session locale's language.
      If no display name has been specified for this Locale, this value is an empty string.



---

### language
- language: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the lowercase ISO 639 language code for this Locale.
      If no language has been specified for this Locale, this value is an empty string.



---

## Method Details

### getCountry()
- getCountry(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the uppercase ISO 3166 2-letter country/region code for this Locale.
      If no country has been specified for this Locale, this value is an empty string.


    **Returns:**
    - the uppercase ISO 3166 2-letter country/region code for this Locale.
              If no country has been specified for this Locale, this value is an empty string.



---

### getDisplayCountry()
- getDisplayCountry(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of this Locale's country, in this Locale's language,
      not in the session locale's language.
      If no country has been specified for this Locale, this value is an empty string.


    **Returns:**
    - the display name of this Locale's country, in this Locale's language.
              If no country has been specified for this Locale, this value is an empty string.



---

### getDisplayLanguage()
- getDisplayLanguage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of this Locale's language, in this Locale's language,
      not in the session locale's language.
      If no country has been specified for this Locale, this value is an empty string.


    **Returns:**
    - the display name of this Locale's language, in this Locale's language.
              If no language has been specified for this Locale, this value is an empty string.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of this Locale, in this Locale's language,
      not in the session locale's language.
      If no display name has been specified for this Locale, this value is an empty string.


    **Returns:**
    - the display name of this Locale, in this Locale's language.
              If no display name has been specified for this Locale, this value is an empty string.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the String representation of the localeID.
      
      
      Combines the language and the country key, concatenated with "\_". 
      For example: "en\_US". This attribute is the primary key of the class.


    **Returns:**
    - the String representation of the localeID.


---

### getISO3Country()
- getISO3Country(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the uppercase ISO 3166 3-letter country/region code for this Locale.
      If no country has been specified for this Locale, this value is an empty string.


    **Returns:**
    - the uppercase ISO 3166 3-letter country/region code for this Locale.
              If no country has been specified for this Locale, this value is an empty string.



---

### getISO3Language()
- getISO3Language(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the 3-letter ISO 639 language code for this Locale.
      If no language has been specified for this Locale, this value is an empty string.


    **Returns:**
    - the 3-letter ISO 639 language code for this Locale.
              If no language has been specified for this Locale, this value is an empty string.



---

### getLanguage()
- getLanguage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the lowercase ISO 639 language code for this Locale.
      If no language has been specified for this Locale, this value is an empty string.


    **Returns:**
    - the lowercase ISO 639 language code for this Locale.
              If no language has been specified for this Locale, this value is an empty string.



---

### getLocale(String) - Variant 1
- static getLocale(localeId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Locale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md)
  - : Returns a Locale instance for the given localeId, or
      `null` if no such Locale could be found.


    **Parameters:**
    - localeId - the localeID of the desired Locale

    **Returns:**
    - the Locale instance for the given localeId, or
              `null` if no such Locale could be found.


    **API Version:**
:::note
:::

---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the String representation of the localeID.
      
      
      Combines the language and the country key, concatenated with "\_". 
      For example: "en\_US". This attribute is the primary key of the class.


    **Returns:**
    - the String representation of the localeID.


---

<!-- prettier-ignore-end -->

<!-- document id=ad1a1a4a0264f2c728b0ff4a8056817a54024fd173eee5312d01ba7decbdf07c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.LocalServiceRegistry.md -->

<!-- prettier-ignore-start -->
# Class LocalServiceRegistry

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)

The LocalServiceRegistry is responsible for managing Service instances.


Typical usage involves several steps:

1. The service is defined in the Business Manager and configured with necessary credentials.
2. An instance of the service is created and configured in a script:      
   ```
   var myFTPService = LocalServiceRegistry.createService("MyFTPService", {    mockExec : function(svc:FTPService, params) {        return [            { "name": "file1", "timestamp": new Date(2011, 02, 21)},            { "name": "file2", "timestamp": new Date(2012, 02, 21)},            { "name": "file3", "timestamp": new Date(2013, 02, 21)}        ];    },    createRequest: function(svc:FTPService, params) {        svc.setOperation("list", "/");    },    parseResponse : function(svc:FTPService, listOutput) {        var x : Array = [];        var resp : Array = listOutput;        for(var i = 0; i <resp.length; i++) {            var f = resp[i];            x.push( { "name": f['name'], "timestamp": f['timestamp'] } );        }        return x;    }});
   ```

3. The service is called in order to perform the operation:      
   ```
   var result : Result = myFTPService.call();if(result.status == 'OK') {    // The result.object is the object returned by the 'after' callback.} else {    // Handle the error. See result.error for more information.}
   ```



Unlike [ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md), the configured service is local to the current script call,
so this deals directly with [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md) instances rather than the intermediate [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md).
This means that a cartridge-level initialization script (and the package.json) is no longer needed.


See [ServiceCallback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md) for all the callback options, and individual [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
classes for customization specific to a service type.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [createService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md#createservicestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs and configures a service with a callback. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### createService(String, Object)
- static createService(serviceID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), configObj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
  - : Constructs and configures a service with a callback.

    **Parameters:**
    - serviceID - Unique Service ID.
    - configObj - Configuration callback. See [ServiceCallback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md) for a description of available callback methods.

    **Returns:**
    - Associated [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), which can be used for further protocol-specific configuration.


---

<!-- prettier-ignore-end -->

<!-- document id=6e8fad0f3c4c2049df7eda25ea18e189c275eaaa3f727c03c87e10469b9dc7ef url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Log.md -->

<!-- prettier-ignore-start -->
# Class Log

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md)

A log4j like logger instance. To obtain such an instance, use the [Logger.getRootLogger()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#getrootlogger) or
[Logger.getLogger(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#getloggerstring) or [Logger.getLogger(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#getloggerstring-string) methods.



## Property Summary

| Property | Description |
| --- | --- |
| [NDC](#ndc): [LogNDC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md) `(read-only)` | Returns the Nested Diagnostic Context for this script call. |
| [debugEnabled](#debugenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if debug logging is enabled for this logging instance. |
| [errorEnabled](#errorenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if error logging is enabled for this logging instance. |
| [infoEnabled](#infoenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if information logging is enabled for this logging instance. |
| [warnEnabled](#warnenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if warning logging is enabled for this logging instance. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [debug](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#debugstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an debug level message. |
| [error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#errorstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an error level message. |
| [fatal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#fatalstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an warning level message. |
| static [getNDC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#getndc)() | Returns the Nested Diagnostic Context for this script call. |
| [info](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#infostring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an information level message. |
| [isDebugEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#isdebugenabled)() | This method returns true if debug logging is enabled for this logging instance. |
| [isErrorEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#iserrorenabled)() | This method returns true if error logging is enabled for this logging instance. |
| [isInfoEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#isinfoenabled)() | This method returns true if information logging is enabled for this logging instance. |
| [isWarnEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#iswarnenabled)() | This method returns true if warning logging is enabled for this logging instance. |
| [warn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md#warnstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an warning level message. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### NDC
- NDC: [LogNDC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md) `(read-only)`
  - : Returns the Nested Diagnostic Context for this script call.


---

### debugEnabled
- debugEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if debug logging is enabled for this logging instance.


---

### errorEnabled
- errorEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if error logging is enabled for this logging instance.


---

### infoEnabled
- infoEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if information logging is enabled for this logging instance.


---

### warnEnabled
- warnEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if warning logging is enabled for this logging instance.


---

## Method Details

### debug(String, Object...)
- debug(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an debug level message. Arguments can be embedded into the message, e.g. like "Failure {0} in
      {1}". The method implements the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

### error(String, Object...)
- error(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an error level message. Arguments can be embedded into the message, e.g. like "Failure {0} in
      {1}". The method implements the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

### fatal(String, Object...)
- fatal(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an warning level message. Arguments can be embedded into the message, e.g. like "Failure {0}
      in {1}". The method implements the Java MessageFormat.format() syntax. Note: Fatal log messages are always
      enabled and optionally send via E-Mail.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

### getNDC()
- static getNDC(): [LogNDC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md)
  - : Returns the Nested Diagnostic Context for this script call.

    **Returns:**
    - the nested diagnostic context


---

### info(String, Object...)
- info(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an information level message. Arguments can be embedded into the message, e.g. like "Failure
      {0} in {1}". The method implements the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

### isDebugEnabled()
- isDebugEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if debug logging is enabled for this logging instance.

    **Returns:**
    - true if logging of debug messages is enabled, false otherwise.


---

### isErrorEnabled()
- isErrorEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if error logging is enabled for this logging instance.

    **Returns:**
    - true if logging of error messages is enabled, false otherwise.


---

### isInfoEnabled()
- isInfoEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if information logging is enabled for this logging instance.

    **Returns:**
    - true if logging of information messages is enabled, false otherwise.


---

### isWarnEnabled()
- isWarnEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if warning logging is enabled for this logging instance.

    **Returns:**
    - true if logging of warning messages is enabled, false otherwise.


---

### warn(String, Object...)
- warn(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an warning level message. Arguments can be embedded into the message, e.g. like "Failure {0}
      in {1}". The method implements the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

<!-- prettier-ignore-end -->

<!-- document id=014d2237349c7b80adb1ff727ce117e70cff9165c4de66d0bbfb0e942ea9c1df url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Logger.md -->

<!-- prettier-ignore-start -->
# Class Logger

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Logger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md)

The Logger class provides logging utility methods.


## Property Summary

| Property | Description |
| --- | --- |
| [debugEnabled](#debugenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if debug logging is enabled. |
| [errorEnabled](#errorenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if error logging is enabled. |
| [infoEnabled](#infoenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if info logging is enabled. |
| [rootLogger](#rootlogger): [Log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md) `(read-only)` | Returns the root logger object. |
| [warnEnabled](#warnenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns true if warning logging is enabled. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [debug](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#debugstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an debug level message. |
| static [error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#errorstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an error level message. |
| static [getLogger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#getloggerstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the logger object for the given category. |
| static [getLogger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#getloggerstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the logger object for the given file name prefix and category. |
| static [getRootLogger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#getrootlogger)() | Returns the root logger object. |
| static [info](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#infostring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an information level message. |
| static [isDebugEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#isdebugenabled)() | This method returns true if debug logging is enabled. |
| static [isErrorEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#iserrorenabled)() | This method returns true if error logging is enabled. |
| static [isInfoEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#isinfoenabled)() | This method returns true if info logging is enabled. |
| static [isWarnEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#iswarnenabled)() | This method returns true if warning logging is enabled. |
| static [warn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md#warnstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method reports an warning level message. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### debugEnabled
- debugEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if debug logging is enabled.


---

### errorEnabled
- errorEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if error logging is enabled.


---

### infoEnabled
- infoEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if info logging is enabled.


---

### rootLogger
- rootLogger: [Log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md) `(read-only)`
  - : Returns the root logger object.


---

### warnEnabled
- warnEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns true if warning logging is enabled.


---

## Method Details

### debug(String, Object...)
- static debug(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an debug level message. Arguments can be embedded
      into the message, e.g. like "Failure {0} in {1}". The method implements
      the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

### error(String, Object...)
- static error(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an error level message. Arguments can be embedded
      into the message, e.g. like "Failure {0} in {1}". The method implements
      the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

### getLogger(String)
- static getLogger(category: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md)
  - : Returns the logger object for the given category.

    **Parameters:**
    - category - - the category to get the logger for

    **Returns:**
    - the logger object for the given category.


---

### getLogger(String, String)
- static getLogger(fileNamePrefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), category: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md)
  - : Returns the logger object for the given file name prefix and category.
      Throws an exception if maximum number of custom log files per day has already been obtained.


    **Parameters:**
    - fileNamePrefix - - the file name prefix to identify the logger  must not be null or an empty string,  must be at least 3 characters long,  can contain characters a-z A-Z 0-9 '-' '\_' only,  can have up to 25 characters  must not start or end with '-' or '\_'  can only start or end with a-z A-Z 0-9
    - category - - the category to get the logger for, must not be null

    **Returns:**
    - the logger object for the given category.


---

### getRootLogger()
- static getRootLogger(): [Log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md)
  - : Returns the root logger object.

    **Returns:**
    - the root logger object.


---

### info(String, Object...)
- static info(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an information level message. Arguments can be embedded
      into the message, e.g. like "Failure {0} in {1}". The method implements
      the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

### isDebugEnabled()
- static isDebugEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if debug logging is enabled.

    **Returns:**
    - true if logging of debug messages is enabled, false otherwise.


---

### isErrorEnabled()
- static isErrorEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if error logging is enabled.

    **Returns:**
    - true if logging of error messages is enabled, false otherwise.


---

### isInfoEnabled()
- static isInfoEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if info logging is enabled.

    **Returns:**
    - true if logging of info messages is enabled, false otherwise.


---

### isWarnEnabled()
- static isWarnEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns true if warning logging is enabled.

    **Returns:**
    - true if logging of warn messages is enabled, false otherwise.


---

### warn(String, Object...)
- static warn(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method reports an warning level message. Arguments can be embedded
      into the message, e.g. like "Failure {0} in {1}". The method implements
      the Java MessageFormat.format() syntax.


    **Parameters:**
    - msg - the message to log.
    - args - the arguments to insert into the message.


---

<!-- prettier-ignore-end -->

<!-- document id=f96a92e6dcc3dee07fa837fba47f50a049ce20080aa87793451697d2be92a74a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.LogNDC.md -->

<!-- prettier-ignore-start -->
# Class LogNDC

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.LogNDC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md)

A Nested Diagnostic Context, or NDC in short, is an instrument to distinguish 
interleaved log output from different sources. Log output is typically 
interleaved when a server handles multiple script calls near-simultaneously.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [peek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md#peek)() | Looks at the last diagnostic context at the top of this NDC without   removing it. |
| [pop](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md#pop)() | Clients should call this method before leaving a diagnostic context. |
| [push](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md#pushstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Push new diagnostic context information for the current script execution. |
| [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md#remove)() | Remove the diagnostic context for this script call. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### peek()
- peek(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Looks at the last diagnostic context at the top of this NDC without 
      removing it.
      The returned value is the value that was pushed last. If no context is 
      available, then the empty string "" is returned.


    **Returns:**
    - String The innermost diagnostic context.


---

### pop()
- pop(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Clients should call this method before leaving a diagnostic context.
      The returned value is the value that was pushed last. 
      If no context is available, then the empty string "" is returned.
      NOTE: The NDC is removed after every script execution.


    **Returns:**
    - String The innermost diagnostic context.


---

### push(String)
- push(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Push new diagnostic context information for the current script execution.

    **Parameters:**
    - message - - The new diagnostic context information.


---

### remove()
- remove(): void
  - : Remove the diagnostic context for this script call.


---

<!-- prettier-ignore-end -->

<!-- document id=d129308188f6ab1f02e189566fc1418641a8eba4948df48e3dc341cee228900a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.LoopIterator.md -->

<!-- prettier-ignore-start -->
# Class LoopIterator

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
    - [dw.web.LoopIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md)

Iterator used in <ISLOOP> implementation. It defines properties used to determine loop status.
LoopIterator object is assigned to variable declared in "status" attribute of the <ISLOOP> tag.



## Property Summary

| Property | Description |
| --- | --- |
| [begin](#begin): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Return begin iteration index. |
| [count](#count): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Return iteration count, starting with 1. |
| [end](#end): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Return end iteration index. |
| [even](#even): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if count is an even value. |
| [first](#first): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the iterator is positioned at first iteratable item. |
| [index](#index): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Return iteration index, which is the position of the iterator in the underlying iteratable object. |
| [last](#last): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the iterator is positioned at last iteratable item. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Return the length of the object. |
| [odd](#odd): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if count is an odd value. |
| [step](#step): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Return iterator step. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBegin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#getbegin)() | Return begin iteration index. |
| [getCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#getcount)() | Return iteration count, starting with 1. |
| [getEnd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#getend)() | Return end iteration index. |
| [getIndex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#getindex)() | Return iteration index, which is the position of the iterator in the underlying iteratable object. |
| [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#getlength)() | Return the length of the object. |
| [getStep](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#getstep)() | Return iterator step. |
| [isEven](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#iseven)() | Identifies if count is an even value. |
| [isFirst](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#isfirst)() | Identifies if the iterator is positioned at first iteratable item. |
| [isLast](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#islast)() | Identifies if the iterator is positioned at last iteratable item. |
| [isOdd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md#isodd)() | Identifies if count is an odd value. |

### Methods inherited from class Iterator

[asList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#aslist), [asList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#aslistnumber-number), [hasNext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#hasnext), [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#next)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### begin
- begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Return begin iteration index. By default begin index is 0.


---

### count
- count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Return iteration count, starting with 1.


---

### end
- end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Return end iteration index. By default end index equals 'length - 1', provided that length is determined.
      If length cannot be determined end index is -1.



---

### even
- even: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if count is an even value.


---

### first
- first: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the iterator is positioned at first iteratable item.


---

### index
- index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Return iteration index, which is the position of the iterator in the underlying iteratable object.
      Index is 0-based and is calculated according the following formula: Index = (Count - 1) \* Step.



---

### last
- last: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the iterator is positioned at last iteratable item.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Return the length of the object. If length cannot be determined, -1 is returned.


---

### odd
- odd: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if count is an odd value.


---

### step
- step: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Return iterator step.


---

## Method Details

### getBegin()
- getBegin(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return begin iteration index. By default begin index is 0.

    **Returns:**
    - the begin iteration index.


---

### getCount()
- getCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return iteration count, starting with 1.

    **Returns:**
    - the iteration count.


---

### getEnd()
- getEnd(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return end iteration index. By default end index equals 'length - 1', provided that length is determined.
      If length cannot be determined end index is -1.



---

### getIndex()
- getIndex(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return iteration index, which is the position of the iterator in the underlying iteratable object.
      Index is 0-based and is calculated according the following formula: Index = (Count - 1) \* Step.


    **Returns:**
    - the iteration index.


---

### getLength()
- getLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the length of the object. If length cannot be determined, -1 is returned.

    **Returns:**
    - the length of the object


---

### getStep()
- getStep(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return iterator step.

    **Returns:**
    - the iterator step.


---

### isEven()
- isEven(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if count is an even value.

    **Returns:**
    - true if count is even, false otherwise.


---

### isFirst()
- isFirst(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the iterator is positioned at first iteratable item.

    **Returns:**
    - true if the iterator is at first item, false otherwise.


---

### isLast()
- isLast(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the iterator is positioned at last iteratable item.

    **Returns:**
    - true if iterator is at last item, false otherwise.


---

### isOdd()
- isOdd(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if count is an odd value.

    **Returns:**
    - true if count is odd, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=9eb44a1657d1d6565029e58c47a38c60393ec95e1470a63eeadc0beadc3a247a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.Mac.md -->

<!-- prettier-ignore-start -->
# Class Mac

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.Mac](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Mac.md)

This class provides the functionality of a "Message Authentication Code" (MAC) algorithm.
A MAC provides a way to check the integrity of information transmitted over or
stored in an unreliable medium, based on a secret key.
Typically, message authentication codes are used between two parties
that share a secret key in order to validate information transmitted between these parties.
A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC.
HMAC can be used with any cryptographic hash function, e.g., SHA256,
in combination with a secret shared key. HMAC is specified in RFC 2104.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[HMAC_MD5](#hmac_md5): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacMD5"~~ | Constant representing the HMAC-MD5 keyed-hashing algorithm as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997). |
| ~~[HMAC_SHA_1](#hmac_sha_1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA1"~~ | Constant representing the HmacSHA1 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)  with SHA-1 as the message digest algorithm. |
| [HMAC_SHA_256](#hmac_sha_256): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA256" | Constant representing the HmacSHA256 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)  with SHA-256 as the message digest algorithm. |
| [HMAC_SHA_384](#hmac_sha_384): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA384" | Constant representing the HmacSHA384 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)  with SHA-384 as the message digest algorithm. |
| [HMAC_SHA_512](#hmac_sha_512): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA512" | Constant representing the HmacSHA512 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)  with SHA-512 as the message digest algorithm. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Mac](#macstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a Mac encryption instance with the specified algorithm name. |

## Method Summary

| Method | Description |
| --- | --- |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Mac.md#digestbytes-bytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Computes the hash value for the passed bytes input using the passed secret key. |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Mac.md#digeststring-bytes)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Computes the hash value for the passed string input using the passed secret key. |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Mac.md#digeststring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Computes the hash value for the passed string input using the passed secret key. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### HMAC_MD5

- ~~HMAC_MD5: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacMD5"~~
  - : Constant representing the HMAC-MD5 keyed-hashing algorithm as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997).
      This algorithm uses as MD5 cryptographic hash function.


    **Deprecated:**
**warning:** This algorithm is obsolete and and has been deprecated. Please use HmacSHA256, HmacSHA384 or HmacSHA512.

---

### HMAC_SHA_1

- ~~HMAC_SHA_1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA1"~~
  - : Constant representing the HmacSHA1 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)
      with SHA-1 as the message digest algorithm.


    **Deprecated:**
**warning:** This algorithm is obsolete and and has been deprecated. Please use HmacSHA256, HmacSHA384 or HmacSHA512.

---

### HMAC_SHA_256

- HMAC_SHA_256: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA256"
  - : Constant representing the HmacSHA256 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)
      with SHA-256 as the message digest algorithm.



---

### HMAC_SHA_384

- HMAC_SHA_384: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA384"
  - : Constant representing the HmacSHA384 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)
      with SHA-384 as the message digest algorithm.



---

### HMAC_SHA_512

- HMAC_SHA_512: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA512"
  - : Constant representing the HmacSHA512 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)
      with SHA-512 as the message digest algorithm.



---

## Constructor Details

### Mac(String)
- Mac(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a Mac encryption instance with the specified algorithm name. The
      supported algorithms are:
      
      
      - SHA 256
      - SHA 384
      - SHA 512


    **Parameters:**
    - algorithm - the standard name of the digest algorithm, must not be             null.

    **Throws:**
    - NullArgumentException - if algorithm is null.
    - IllegalArgumentException - if the specified algorithm name is not              supported.


---

## Method Details

### digest(Bytes, Bytes)
- digest(input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed bytes input using the passed secret key.

    **Parameters:**
    - input - The bytes to calculate a RFC 2104 compliant HMAC hash value.
    - key - The secret key as byte array ready for use with the algorithm.           The key's format depends on the chosen algorithm and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.           Only such keys that have no key parameters associated with them.

    **Returns:**
    - The resulting hash value as bytes.

    **Throws:**
    - IllegalArgumentException - if algorithm is not null and the              specified algorithm name is not supported.


---

### digest(String, Bytes)
- digest(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed string input using the passed secret key.
      Given input will be first converted with UTF-8 encoding into a byte array.
      The resulting hash is typically converted with base64 back into a string.


    **Parameters:**
    - input - A string to calculate a RFC 2104 compliant HMAC hash value for.
    - key - The secret key as bytes ready for use with the algorithm.           The key's format depends on the chosen algorithm and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.           Only such keys that have no key parameters associated with them.

    **Returns:**
    - The resulting hash value as bytes.

    **Throws:**
    - IllegalArgumentException - if algorithm is not null and the              specified algorithm name is not supported.


---

### digest(String, String)
- digest(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed string input using the passed secret key.
      Given input and the given key will be first converted with UTF-8 encoding into a byte array.
      The resulting hash is typically converted with base64 back into a string.


    **Parameters:**
    - input - A string to calculate a RFC 2104 compliant HMAC hash value for.
    - key - The secret key ready for use with the algorithm.           The key's format depends on the chosen algorithm and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.           Only such keys that have no key parameters associated with them.

    **Returns:**
    - The resulting hash value as bytes.

    **Throws:**
    - IllegalArgumentException - if algorithm is not null and the              specified algorithm name is not supported.


---

<!-- prettier-ignore-end -->

<!-- document id=378b08a4ab1adc84e4e82dbba57293a6a13232762137b642b905e97158e6f830 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.Mail.md -->

<!-- prettier-ignore-start -->
# Class Mail

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)

This class is used to send an email with either plain text or MimeEncodedText content.
Recipient data (from, to, cc, bcc) and subject are specified
using setter methods. When the [send()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#send) method is invoked,
the email is put into an internal queue and sent asynchronously.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.


The following example script sends an email with MimeEncodedText content:


```

function sendMail() {
 var template: Template = new dw.util.Template("myTemplate.isml");

 var o: Map = new dw.util.HashMap();
 o.put("customer","customer");
 o.put("product","product");

 var content: MimeEncodedText = template.render(o);
 var mail: Mail = new dw.net.Mail();
 mail.addTo("to@example.org");
 mail.setFrom("from@example.org");
 mail.setSubject("Example Email");
 mail.setContent(content);

 mail.send();//returns either Status.ERROR or Status.OK, mail might not be sent yet, when this method returns
 }
```



 See **Sending email via scripts or hooks** in the documentation for additional examples.



## Property Summary

| Property | Description |
| --- | --- |
| [bcc](#bcc): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Gets the `bcc` address List. |
| [cc](#cc): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Gets the `cc` address List. |
| [from](#from): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Gets the email address to use as the `from` address for the  email. |
| [replyTo](#replyto): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Gets the `replyTo` address List. |
| [subject](#subject): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Gets the `subject` of the email. |
| [to](#to): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Gets the `to` address List where the email is sent. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Mail](#mail)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| [addAttachment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#addattachmentfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Adds a file attachment to the email. |
| [addBcc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#addbccstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds an address to the `bcc` List. |
| [addCc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#addccstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds an address to the `cc` List. |
| [addReplyTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#addreplytostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds an address to the `replyTo` List. |
| [addTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#addtostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds an address to the `to` address List. |
| [getBcc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#getbcc)() | Gets the `bcc` address List. |
| [getCc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#getcc)() | Gets the `cc` address List. |
| [getFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#getfrom)() | Gets the email address to use as the `from` address for the  email. |
| [getReplyTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#getreplyto)() | Gets the `replyTo` address List. |
| [getSubject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#getsubject)() | Gets the `subject` of the email. |
| [getTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#getto)() | Gets the `to` address List where the email is sent. |
| [send](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#send)() | prepares an email that is queued to the internal mail system for  delivery. |
| [setBcc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setbcclist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Sets the `bcc` address List. |
| [setCc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setcclist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Sets the `cc` address List where the email is sent. |
| [setContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setcontentmimeencodedtext)([MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md)) | **Mandatory** Uses [MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md) to set the  content, MIME type and encoding. |
| [setContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | **Mandatory** Sets the email content. |
| [setContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setcontentstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | **Mandatory** Sets the email content, MIME type, and encoding. |
| [setFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setfromstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | **Mandatory** Sets the sender address for this email. |
| [setListUnsubscribe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setlistunsubscribestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the List-Unsubscribe header value to work with List-Unsubscribe-Post to allow integration with an  externally-managed mailing list. |
| [setListUnsubscribePost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setlistunsubscribepoststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the List-Unsubscribe-Post header value. |
| [setSubject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#setsubjectstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | **Mandatory** sets the `subject` for the email. |
| [setTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#settolist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Sets the `to` address List where the email is sent. |
| static [validateAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#validateaddressstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Validates the address that is sent as parameter. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bcc
- bcc: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Gets the `bcc` address List.


---

### cc
- cc: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Gets the `cc` address List.


---

### from
- from: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the email address to use as the `from` address for the
      email.



---

### replyTo
- replyTo: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Gets the `replyTo` address List.


---

### subject
- subject: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the `subject` of the email.


---

### to
- to: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Gets the `to` address List where the email is sent.


---

## Constructor Details

### Mail()
- Mail()
  - : 


---

## Method Details

### addAttachment(File)
- addAttachment(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Adds a file attachment to the email. This method is restricted to Job context only.

    **Parameters:**
    - file - The file to be attached to the email. Must not be null and must exist.

    **Returns:**
    - this Mail object

    **Throws:**
    - IllegalArgumentException - if the file is null, doesn't exist, or is not a file


---

### addBcc(String)
- addBcc(bcc: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Adds an address to the `bcc` List. Address must conform to the RFC822 standard.

    **Parameters:**
    - bcc - new bcc address to add to `bcc` address List.

    **Returns:**
    - this Mail object.


---

### addCc(String)
- addCc(cc: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Adds an address to the `cc` List. The address must conform to RFC822 standard.

    **Parameters:**
    - cc - new cc address to be added to `cc` address List.

    **Returns:**
    - this Mail object.


---

### addReplyTo(String)
- addReplyTo(replyTo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Adds an address to the `replyTo` List. Address must conform to the RFC822 standard.

    **Parameters:**
    - replyTo - new replyTo address to add to `replyTo` address List.

    **Returns:**
    - this Mail object.

    **Throws:**
    - IllegalArgumentException - if the email address is invalid


---

### addTo(String)
- addTo(to: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Adds an address to the `to` address List. The address must conform to the RFC822 standard.

    **Parameters:**
    - to - email address to add to the `to` address List.

    **Returns:**
    - this Mail object.


---

### getBcc()
- getBcc(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Gets the `bcc` address List.

    **Returns:**
    - `bcc` address List or empty List if no `bcc`
              addresses are set.



---

### getCc()
- getCc(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Gets the `cc` address List.

    **Returns:**
    - `cc` address List or empty List if no `cc`
              addresses are set.



---

### getFrom()
- getFrom(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the email address to use as the `from` address for the
      email.


    **Returns:**
    - the `from` address for this mail or null if no `from`
              address is set yet.



---

### getReplyTo()
- getReplyTo(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Gets the `replyTo` address List.

    **Returns:**
    - `replyTo` address List or empty List if no `replyTo`
              addresses are set.



---

### getSubject()
- getSubject(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the `subject` of the email.

    **Returns:**
    - `subject` or null if no `subject` is set yet.


---

### getTo()
- getTo(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Gets the `to` address List where the email is sent.

    **Returns:**
    - `to` address List or empty List if no `to`
              addresses are set.



---

### send()
- send(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : prepares an email that is queued to the internal mail system for
      delivery.


    **Returns:**
    - [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) which tells if the mail could be
              successfully queued ( [Status.OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#ok)) or not (
              [Status.ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#error)). If an error is raised, more
              information about the reason for the failure can be found within the
              log files. If the mandatory fields `from`,
              `content`, and `subject` are
              empty an IllegalArgumentException is raised. An
              IllegalArgumentException is raised if neither `to`, `cc`
              nor `bcc` are set.



---

### setBcc(List)
- setBcc(bcc: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Sets the `bcc` address List. If there
      are already `bcc` addresses they are overwritten.


    **Parameters:**
    - bcc - list of Strings representing RFC822 compliant email             addresses. List replaces any previously set list of             addresses. Throws an exception if the given list is null.

    **Returns:**
    - this Mail object.


---

### setCc(List)
- setCc(cc: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Sets the `cc` address List where the email is sent. If there are
      already `cc` addresses set, they are overwritten. The address(es) must
      conform to the RFC822 standard.


    **Parameters:**
    - cc - List of Strings representing RFC822 compliant email             addresses. This List replaces any previously set List of             addresses. Throws an exception if the given List is null.

    **Returns:**
    - this Mail object


---

### setContent(MimeEncodedText)
- setContent(mimeEncodedText: [MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : **Mandatory** Uses [MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md) to set the
      content, MIME type and encoding.


    **Parameters:**
    - mimeEncodedText - MimeEncodedText from which the content, MIME type, and encoding             information is extracted.

    **Returns:**
    - this Mail object.


---

### setContent(String)
- setContent(content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : **Mandatory** Sets the email content. The MIME type is set to
      "text/plain;charset=UTF-8" and encoding set to "UTF-8".


    **Parameters:**
    - content - String containing the content of the email.

    **Returns:**
    - this Mail object.


---

### setContent(String, String, String)
- setContent(content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), mimeType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : **Mandatory** Sets the email content, MIME type, and encoding. No
      validation of MIME type and encoding is done. It is the responsibility of
      the caller to specify a valid MIME type and encoding.


    **Parameters:**
    - content - String containing the content of the mail
    - mimeType - mime type of the content. For example             "text/plain;charset=UTF-8" or "text/html"
    - encoding - character encoding of the email content. For example UTF-8-8

    **Returns:**
    - this Mail object.


---

### setFrom(String)
- setFrom(from: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : **Mandatory** Sets the sender address for this email. The address must
      conform to the RFC822 standard.


    **Parameters:**
    - from - String containing a RFC822 compliant email address

    **Returns:**
    - this Mail object.


---

### setListUnsubscribe(String)
- setListUnsubscribe(listUnsubscribe: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Sets the List-Unsubscribe header value to work with List-Unsubscribe-Post to allow integration with an
      externally-managed mailing list.


    **Parameters:**
    - listUnsubscribe - The List-Unsubscribe header value, e.g., "<https://example.com/unsubscribe>"

    **Returns:**
    - this Mail object


---

### setListUnsubscribePost(String)
- setListUnsubscribePost(listUnsubscribePost: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Sets the List-Unsubscribe-Post header value. This header supports one-click unsubscribe functionality.

    **Parameters:**
    - listUnsubscribePost - The List-Unsubscribe-Post header value, typically "List-Unsubscribe=One-Click"

    **Returns:**
    - this Mail object


---

### setSubject(String)
- setSubject(subject: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : **Mandatory** sets the `subject` for the email. If the `subject` is not set
      or set to null at the time [send()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md#send) is invoked and
      IllegalArgumentException is thrown.


    **Parameters:**
    - subject - `subject` of the mail to send.

    **Returns:**
    - this Mail object.


---

### setTo(List)
- setTo(to: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)
  - : Sets the `to` address List where the email is sent. If there are
      already `to` addresses, they are overwritten.


    **Parameters:**
    - to - list of Strings representing RFC822 compliant email addresses.             List replaces any previously set List of addresses. Throws             an exception if the given List is null.

    **Returns:**
    - this Mail object


---

### validateAddress(String)
- static validateAddress(address: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Validates the address that is sent as parameter.
      This validation includes:
      
      - The format must match RFC822
      - The address must be 7-bit ASCII
      - The top-level domain must be IANA-registered
      - Sample domains such as example.com are not allowed


    **Parameters:**
    - address - Email address to be validated

    **Returns:**
    - true if valid, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=e32468bff8c063b1b5e12caee3e2ef0dc603a4d967929e45beaedf5d02c1207a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Map.md -->

<!-- prettier-ignore-start -->
# Class Map

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)

Represents a Map of objects.


## All Known Subclasses
[HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md), [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md), [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)
## Property Summary

| Property | Description |
| --- | --- |
| [EMPTY_MAP](#empty_map): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) | Convenience variable, for an empty and immutable list. |
| [empty](#empty): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this map is empty. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | REturns the size of the map. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#clear)() | Clears the map of all objects. |
| [containsKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containskeyobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Identifies if this map contains an element identfied  by the specified key. |
| [containsValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containsvalueobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Identifies if this map contains an element identfied  by the specified value. |
| [entrySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#entryset)() | Returns a set of the map's entries. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the object associated with the key or null. |
| [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getlength)() | REturns the size of the map. |
| [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#isempty)() | Identifies if this map is empty. |
| [keySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#keyset)() | Returns a set of the map's keys. |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Puts the specified value into the map using the  specified key to identify it. |
| [putAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putallmap)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)) | Copies all of the objects inside the specified map  into this map. |
| [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#removeobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Removes the object from the map that is identified by the key. |
| [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#size)() | Returns the size of the map. |
| [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-1)() | Returns a collection of the values contained in this map. |
| [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-2)() | Returns a collection of the values contained in this map. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### EMPTY_MAP
- EMPTY_MAP: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Convenience variable, for an empty and immutable list.


---

### empty
- empty: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this map is empty.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : REturns the size of the map. This is a bean attribute method and
      supports the access to the collections
      length similar to a ECMA array, such as 'products.length'.



---

## Method Details

### clear()
- clear(): void
  - : Clears the map of all objects.


---

### containsKey(Object)
- containsKey(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this map contains an element identfied
      by the specified key.


    **Parameters:**
    - key - the key to use.

    **Returns:**
    - true if this map contains an element whose key is
      equal to the specified key.



---

### containsValue(Object)
- containsValue(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this map contains an element identfied
      by the specified value.


    **Parameters:**
    - value - the value to use.

    **Returns:**
    - true if this map contains an element whose value is
      equal to the specified value.



---

### entrySet()
- entrySet(): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Returns a set of the map's entries. The returned set is actually a view to the entries of this map.

    **Returns:**
    - a set of the map's entries.


---

### get(Object)
- get(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the object associated with the key or null.

    **Parameters:**
    - key - the key to use.

    **Returns:**
    - the object associated with the key or null.


---

### getLength()
- getLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : REturns the size of the map. This is a bean attribute method and
      supports the access to the collections
      length similar to a ECMA array, such as 'products.length'.


    **Returns:**
    - the number of objects in the map.


---

### isEmpty()
- isEmpty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this map is empty.

    **Returns:**
    - true if the map is empty, false otherwise.


---

### keySet()
- keySet(): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Returns a set of the map's keys. The returned set is actually a view to the keys of this map.

    **Returns:**
    - a set of the map's keys.


---

### put(Object, Object)
- put(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Puts the specified value into the map using the
      specified key to identify it.


    **Parameters:**
    - key - the key to use to identify the value.
    - value - the object to put into the map.

    **Returns:**
    - previous value associated with specified key, or null if there was no mapping for key.


---

### putAll(Map)
- putAll(other: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)): void
  - : Copies all of the objects inside the specified map
      into this map.


    **Parameters:**
    - other - the map whose contents are copied into this map.


---

### remove(Object)
- remove(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Removes the object from the map that is identified by the key.

    **Parameters:**
    - key - the key that identifies the object to remove.

    **Returns:**
    - the removed object or null.


---

### size()
- size(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the map.

    **Returns:**
    - the number of objects in the map.


---

### values() - Variant 1
- values(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of the values contained in this map.

    **Returns:**
    - a collection of the values contained in this map

    **API Version:**
**note:** No longer available as of version 16.1.
Returns an independent modifiable collection holding all values.

---

### values() - Variant 2
- values(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of the values contained in this map.

    **Returns:**
    - a collection of the values contained in this map

    **API Version:**
**note:** Available from version 16.1.
Returns a view on the values of this map like keySet() and entrySet() do. Former version returned a shallow copy of this.

---

<!-- prettier-ignore-end -->

<!-- document id=446569b90634464780d80cb1b5e35ab1db499b6861dec00272710c75b7ee286f url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Map.md -->

<!-- prettier-ignore-start -->
# Class Map

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md)

Map objects are collections of key/value pairs where both the keys and values may be arbitrary ECMAScript language
values. A distinct key value may only occur in one key/value pair within the Map's collection. Key/value pairs are stored
and iterated in insertion order.


**API Version:**
**note:** Available from version 21.2.

## Property Summary

| Property | Description |
| --- | --- |
| [size](#size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Number of key/value pairs stored in this map. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Map](#map)() | Creates an empty map. |
| [Map](#mapiterable)([Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)) | If the passed value is null or undefined then an empty map is constructed. |

## Method Summary

| Method | Description |
| --- | --- |
| [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#clear)() | Removes all key/value pairs from this map. |
| [delete](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#deleteobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Removes the entry for the given key. |
| [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#entries)() | Returns an iterator containing all key/value pairs of this map. |
| [forEach](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#foreachfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Runs the provided callback function once for each key/value pair present in this map. |
| [forEach](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#foreachfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Runs the provided callback function once for each key/value pair present in this map. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#getobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the value associated with the given key. |
| [has](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#hasobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if this map has value associated with the given key. |
| [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#keys)() | Returns an iterator containing all keys of this map. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#setobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds or updates a key/value pair to the map. |
| [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md#values)() | Returns an iterator containing all values of this map. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### size
- size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Number of key/value pairs stored in this map.


---

## Constructor Details

### Map()
- Map()
  - : Creates an empty map.


---

### Map(Iterable)
- Map(values: [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md))
  - : If the passed value is null or undefined then an empty map is constructed. Else an iterator object is expected
      that produces a two element array-like object whose first element is a value that will be used as a Map key and
      whose second element is the value to associate with that key.


    **Parameters:**
    - values - The initial map values


---

## Method Details

### clear()
- clear(): void
  - : Removes all key/value pairs from this map.


---

### delete(Object)
- delete(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Removes the entry for the given key.

    **Parameters:**
    - key - The key of the key/value pair to be removed from the map.

    **Returns:**
    - `true` if the map contained an entry for the passed key that was removed. Else `false` is returned.


---

### entries()
- entries(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator containing all key/value pairs of this map.
      The iterator produces a series of two-element arrays with the first element as the key and the second element as the value.



---

### forEach(Function)
- forEach(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): void
  - : Runs the provided callback function once for each key/value pair present in this map.

    **Parameters:**
    - callback - The function to call, which is invoked with three  arguments: the value of the element, the key of the element, and the  Map object being iterated.


---

### forEach(Function, Object)
- forEach(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Runs the provided callback function once for each key/value pair present in this map.

    **Parameters:**
    - callback - The function to call, which is invoked with three  arguments: the value of the element, the key of the element, and the  Map object being iterated.
    - thisObject - The Object to use as 'this' when executing callback.


---

### get(Object)
- get(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value associated with the given key.

    **Parameters:**
    - key - The key to look for.

    **Returns:**
    - The value associated with the given key if an entry with the key exists else `undefined` is returned.


---

### has(Object)
- has(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if this map has value associated with the given key.

    **Parameters:**
    - key - The key to look for.

    **Returns:**
    - `true` if an entry with the key exists else `false` is returned.


---

### keys()
- keys(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator containing all keys of this map.


---

### set(Object, Object)
- set(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md)
  - : Adds or updates a key/value pair to the map. 
      
      You can't use JavaScript bracket notation to access map entries. JavaScript bracket notation accesses only
      properties for Map objects, not map entries.


    **Parameters:**
    - key - The key object.
    - value - The value to be associated with the key.

    **Returns:**
    - This map object.


---

### values()
- values(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator containing all values of this map.


---

<!-- prettier-ignore-end -->

<!-- document id=b23611f5f2816e79bb3ffff4a54b167e4f9f4b8e6fdc8066e88701db46ee8143 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.MapEntry.md -->

<!-- prettier-ignore-start -->
# Class MapEntry

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.MapEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MapEntry.md)

The class represent an entry within a Map.


## Property Summary

| Property | Description |
| --- | --- |
| [key](#key): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the entry's key. |
| [value](#value): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the entry's value. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MapEntry.md#getkey)() | Returns the entry's key. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MapEntry.md#getvalue)() | Returns the entry's value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### key
- key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the entry's key.


---

### value
- value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the entry's value.


---

## Method Details

### getKey()
- getKey(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the entry's key.

    **Returns:**
    - the entry's key.


---

### getValue()
- getValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the entry's value.

    **Returns:**
    - the entry's value.


---

<!-- prettier-ignore-end -->

<!-- document id=a212b8b1777d348f6393b1897d18aba78a17233b9abf872a85183aec21fa488c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.MappingKey.md -->

<!-- prettier-ignore-start -->
# Class MappingKey

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.MappingKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md)

Encapsulates the key for a mapping read in with the ImportKeyValueMapping job step. Can be either single or compound keys. For example, a
single string (e.g. product id) or multiple string components (e.g. product id and site).



## Property Summary

| Property | Description |
| --- | --- |
| [keyComponents](#keycomponents): [String\[\]](TopLevel.String.md) `(read-only)` | Gets the (possible compound) key. |
| [singleComponentKey](#singlecomponentkey): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets a key that contains only a single key component (i.e. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [MappingKey](#mappingkeystring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Instantiates a new key using compound key components. |

## Method Summary

| Method | Description |
| --- | --- |
| [getKeyComponents](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md#getkeycomponents)() | Gets the (possible compound) key. |
| [getSingleComponentKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md#getsinglecomponentkey)() | Gets a key that contains only a single key component (i.e. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### keyComponents
- keyComponents: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Gets the (possible compound) key. If the key consists of only of a single value, the string array
      will simply contain a single element.



---

### singleComponentKey
- singleComponentKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets a key that contains only a single key component (i.e. that is not a compound key). Returns null if this is
      not a single component key.



---

## Constructor Details

### MappingKey(String...)
- MappingKey(keyComponents: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Instantiates a new key using compound key components. A key can consist of a single string (e.g. product id) or
      multiple string components (e.g. product id and site). Ctor accepts single string or multiple components for a
      compound key.


    **Parameters:**
    - keyComponents - the key components


---

## Method Details

### getKeyComponents()
- getKeyComponents(): [String\[\]](TopLevel.String.md)
  - : Gets the (possible compound) key. If the key consists of only of a single value, the string array
      will simply contain a single element.


    **Returns:**
    - the key


---

### getSingleComponentKey()
- getSingleComponentKey(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets a key that contains only a single key component (i.e. that is not a compound key). Returns null if this is
      not a single component key.


    **Returns:**
    - the single key


---

<!-- prettier-ignore-end -->

<!-- document id=868d568113e8066017845a5134592174d7c5647737bb8d259e173fa23b029b95 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.MappingMgr.md -->

<!-- prettier-ignore-start -->
# Class MappingMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.MappingMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingMgr.md)

Used to manage and interface with mappings loaded into the system via the ImportKeyValueMapping job step. Class can be
used to retrieve values for known keys, iterate over all keys known in a mapping or list all known mappings.


Mappings are read into the system using the ImportKeyValueMapping job step.


Generic mapping capability enables you to map keys to values, with the mapping stored in a high-performance data
store that is independent of the database. This supports large datasets, with high performance for lookup. An example
of using this feature is to map SKUs from a backend system to Commerce Cloud Digital SKUs on-the-fly in Digital script, so
that interaction with the backend system is transparent and does not require adding Digital SKUs to the third
party system.



## Property Summary

| Property | Description |
| --- | --- |
| [mappingNames](#mappingnames): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | List all known mappings. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingMgr.md#getstring-mappingkey)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [MappingKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md)) | Returns a map containing value(s) associated to the specified key for the specified mapping. |
| static [getFirst](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingMgr.md#getfirststring-mappingkey)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [MappingKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md)) | Gets the first string value of a mapping by name and key. |
| static [getMappingNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingMgr.md#getmappingnames)() | List all known mappings. |
| static [keyIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingMgr.md#keyiteratorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Key iterator over known mapping keys by mapping name. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### mappingNames
- mappingNames: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : List all known mappings.


---

## Method Details

### get(String, MappingKey)
- static get(mappingName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [MappingKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md)): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a map containing value(s) associated to the specified key for the specified mapping.

    **Parameters:**
    - mappingName - the mapping name
    - key - the key

    **Throws:**
    - IllegalArgumentException - if mappingName is unknown


---

### getFirst(String, MappingKey)
- static getFirst(mappingName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [MappingKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the first string value of a mapping by name and key. Ordering is determined by the input CSV file. Throws an
      exception if mappingName does not exist.


    **Parameters:**
    - mappingName - the mapping name
    - key - the key

    **Returns:**
    - the value if a single value. The first value sequentially if a compound value.

    **Throws:**
    - IllegalArgumentException - if mappingName is unknown


---

### getMappingNames()
- static getMappingNames(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : List all known mappings.

    **Returns:**
    - the collection of mapping names


---

### keyIterator(String)
- static keyIterator(mappingName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Key iterator over known mapping keys by mapping name. Throws an exception if mappingName does not exist.

    **Parameters:**
    - mappingName - the mapping name

    **Returns:**
    - the seekable iterator

    **Throws:**
    - IllegalArgumentException - if mappingName is unknown


---

<!-- prettier-ignore-end -->

<!-- document id=833e8bc702631b9e760d37f85eb2aa4a2f3d11746232a777f180779b1ba3ca9e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.consent.MarketingConsentSubscription.md -->

<!-- prettier-ignore-start -->
# Class MarketingConsentSubscription

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.consent.MarketingConsentSubscription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md)

Represents a marketing consent subscription for a shopper.


A marketing consent subscription defines a communication preference category (e.g., "Newsletter", "Product Updates")
with associated channels (EMAIL, SMS, WHATSAPP) through which the shopper can receive marketing communications.




Example usage:


```

var subscriptions = dw.customer.consent.ShopperConsentMgr.getSubscriptions();
for each (var sub in subscriptions) {
    trace('Subscription: ' + sub.subscriptionId + ' - ' + sub.title);
    trace('Channels: ' + sub.channels);
}
```



## Property Summary

| Property | Description |
| --- | --- |
| [channels](#channels): [String\[\]](TopLevel.String.md) `(read-only)` | Returns the available channels for this subscription. |
| [consentRequired](#consentrequired): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether consent is required for this subscription. |
| [consentStatus](#consentstatus): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the consent status entries for this subscription. |
| [consentType](#consenttype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the consent type for this subscription. |
| [defaultStatus](#defaultstatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the default consent status for this subscription. |
| [subscriptionId](#subscriptionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique identifier for this subscription. |
| [subtitle](#subtitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the localized subtitle of this subscription. |
| [tags](#tags): [String\[\]](TopLevel.String.md) `(read-only)` | Returns the tags associated with this subscription. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the localized title of this subscription. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getChannels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#getchannels)() | Returns the available channels for this subscription. |
| [getConsentRequired](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#getconsentrequired)() | Returns whether consent is required for this subscription. |
| [getConsentStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#getconsentstatus)() | Returns the consent status entries for this subscription. |
| [getConsentType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#getconsenttype)() | Returns the consent type for this subscription. |
| [getDefaultStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#getdefaultstatus)() | Returns the default consent status for this subscription. |
| [getSubscriptionId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#getsubscriptionid)() | Returns the unique identifier for this subscription. |
| [getSubtitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#getsubtitle)() | Returns the localized subtitle of this subscription. |
| [getTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#gettags)() | Returns the tags associated with this subscription. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md#gettitle)() | Returns the localized title of this subscription. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### channels
- channels: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns the available channels for this subscription.
      
      
      Channels represent the communication methods (EMAIL, SMS, WHATSAPP) available for this subscription.



---

### consentRequired
- consentRequired: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether consent is required for this subscription.


---

### consentStatus
- consentStatus: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the consent status entries for this subscription.
      
      
      This is only populated when the 'includeConsentStatus' parameter is true in the getSubscriptions call, and the
      customer is authenticated.



---

### consentType
- consentType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the consent type for this subscription.


---

### defaultStatus
- defaultStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the default consent status for this subscription.


---

### subscriptionId
- subscriptionId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique identifier for this subscription.


---

### subtitle
- subtitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the localized subtitle of this subscription.


---

### tags
- tags: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns the tags associated with this subscription.
      
      
      Tags can be used to categorize and filter subscriptions.



---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the localized title of this subscription.


---

## Method Details

### getChannels()
- getChannels(): [String\[\]](TopLevel.String.md)
  - : Returns the available channels for this subscription.
      
      
      Channels represent the communication methods (EMAIL, SMS, WHATSAPP) available for this subscription.


    **Returns:**
    - A list of channel strings (lowercase).


---

### getConsentRequired()
- getConsentRequired(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether consent is required for this subscription.

    **Returns:**
    - True if consent is required, false otherwise.


---

### getConsentStatus()
- getConsentStatus(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the consent status entries for this subscription.
      
      
      This is only populated when the 'includeConsentStatus' parameter is true in the getSubscriptions call, and the
      customer is authenticated.


    **Returns:**
    - A collection of ConsentStatusEntry objects, or null if not requested.


---

### getConsentType()
- getConsentType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the consent type for this subscription.

    **Returns:**
    - The consent type (e.g., "SINGLE\_OPT\_IN", "DOUBLE\_OPT\_IN").


---

### getDefaultStatus()
- getDefaultStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the default consent status for this subscription.

    **Returns:**
    - The default status (e.g., "OPT\_IN", "OPT\_OUT").


---

### getSubscriptionId()
- getSubscriptionId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique identifier for this subscription.

    **Returns:**
    - The subscription ID.


---

### getSubtitle()
- getSubtitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the localized subtitle of this subscription.

    **Returns:**
    - The subscription subtitle.


---

### getTags()
- getTags(): [String\[\]](TopLevel.String.md)
  - : Returns the tags associated with this subscription.
      
      
      Tags can be used to categorize and filter subscriptions.


    **Returns:**
    - A list of tag strings.


---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the localized title of this subscription.

    **Returns:**
    - The subscription title.


---

<!-- prettier-ignore-end -->

<!-- document id=4c89cae6f7d85ee9786b947bb1a090ada2320dbe0fef531797d5d52d1fddd85e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.MarkupText.md -->

<!-- prettier-ignore-start -->
# Class MarkupText

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.content.MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)

The class represents a content snippet with markup. This is typically a
HTML content snippet. The class also processes the special links from
Commerce Cloud Digital content management and automatically rewrites them into
links for use in the storefront.


The following special links can be used inside of a MarkupText:



- `**$url('<pipeline>' [, '<key1>', '<value1>', '<key2>', '<value2>', ...])$**`

_Description:_
The`$url()$`function creates and absolute URL and retains the protocol incoming
request.
_Example:_
MarkupText:
&nbsp;&nbsp;&nbsp;`$url('MyLinkPipeline-Start', 'key1', 'value1', 'key2', 'value2')$`
is rewritten to:
&nbsp;&nbsp;&nbsp;`http://<host>:<port>/on/demandware.store/<current site>/default/MyLinkPipeline-Start?key1=value1&key2=value2`
Note that the incoming protocol was http in the example above.
- `**$httpUrl('<pipeline>' [, '<key1>', '<value1>', '<key2>', '<value2>', ...])$**`

_Description:_
The`$httpUrl()$`function creates an absolute URL but always with the fix protocol
"http". The protocol type of the incomming request is ignored.

_Example:_
MarkupText:
&nbsp;&nbsp;&nbsp;`$httpUrl('MyLinkPipeline-Start', 'key1', 'value1', 'key2', 'value2')$`
is rewritten to:
&nbsp;&nbsp;&nbsp;`http://<host>:'<port>/on/demandware.store/<current site>/default/MyLinkPipeline-Start?key1=value1&key2=value2`
- `**$httpsUrl('<pipeline>' [, '<key1>', '<value1>', '<key2>', '<value2>', ...])$**`

_Description:_
The`$httpsUrl()$`function creates an absolute URL but always with the fix protocol
"https". The protocol type of the incomming request is ignored.
_Example:_
MarkupText:
&nbsp;&nbsp;&nbsp;`$httpsUrl('MyLinkPipeline-Start', 'key1', 'value1', 'key2', 'value2')$`
is rewritten to:
&nbsp;&nbsp;&nbsp;`https://<host>:<port>/on/demandware.store/<current site>/default/MyLinkPipeline-Start?key1=value1&key2=value2`

- `**$include('<pipeline>' [, '<key1>', '<value1>', '<key2>', '<value2>', ...])$**`

_Description:_
The`$include()$`function creates a relative URL which is post processed by the
Commerce Cloud Digital Webadapter. The result is the content generated by the given pipeline call.
_Example:_
MarkupText:
&nbsp;&nbsp;&nbsp;`$include('MyIncludePipeline-Start','key1', 'value1', 'key2' ,'value2')$`
results in the content delivered by the 'MyIncludePipeline-Start' pipeline.
- `**...?$staticlink$**`

_Description:_
The`$staticlink$`function can be used to create a URL to a static resource
(such as an image). The URL being generated depends on the owner of the MarkupText instance.
For example, a product's long description (which is a MarkupText) will generate
links to static resources within the catalog. Possible URL targets are catalogs
(for catalog related objects like products and categories), the content library
(for library related objects like folders and assets) or the organization
(for all objects that are not catalog or library related).
_Example:_
MarkupText: (owned by a content asset)
&nbsp;&nbsp;&nbsp;`<img src="https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/demo/content/bullet.gif?$staticlink$">`
is rewritten to:
&nbsp;&nbsp;&nbsp;`<img src="/on/demandware.static/<current site>/<library>/default/v1178201405900/demo/content/bullet.gif">`



Note: The comma symbol `,` is not supported in parameter values for the link functions.



## Property Summary

| Property | Description |
| --- | --- |
| [markup](#markup): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the content with all links rewritten for storefront use. |
| [source](#source): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the original content source, without any links re-written. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getMarkup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md#getmarkup)() | Returns the content with all links rewritten for storefront use. |
| [getSource](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md#getsource)() | Returns the original content source, without any links re-written. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md#tostring)() | Returns a string representation of this class, the same as getMarkup(). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### markup
- markup: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the content with all links rewritten for storefront use.


---

### source
- source: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the original content source, without any links re-written.


---

## Method Details

### getMarkup()
- getMarkup(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the content with all links rewritten for storefront use.

    **Returns:**
    - the content with all links rewritten for storefront use.


---

### getSource()
- getSource(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the original content source, without any links re-written.

    **Returns:**
    - the original content source, without any links re-written.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this class, the same as getMarkup().

    **Returns:**
    - a string representation of this class, the same as getMarkup().


---

<!-- prettier-ignore-end -->

<!-- document id=ceaa8f341cedb94a878f04b3e2405e40ebe3f43464e80081eba15520770d35c1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Math.md -->

<!-- prettier-ignore-start -->
# Class Math

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Math](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md)

Mathematical functions and constants.


## Constant Summary

| Constant | Description |
| --- | --- |
| [E](#e): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The constant _e_, which is the base of natural logarithms. |
| [LN10](#ln10): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The natural logarithm of 10. |
| [LN2](#ln2): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The natural logarithm of 2. |
| [LOG10E](#log10e): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The base-10 logarithm of _e_. |
| [LOG2E](#log2e): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The base-2 logarithm of _e_. |
| [PI](#pi): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The constant for PI. |
| [SQRT1_2](#sqrt1_2): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | 1 divided by the square root of 2. |
| [SQRT2](#sqrt2): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The square root of 2. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Math](#math)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| static [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#absnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the absolute value of _x_. |
| static [acos](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#acosnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the arc cosine of _x_. |
| static [acosh](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#acoshnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the inverse hyperbolic cosine of _x_. |
| static [asin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#asinnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the arc sine of _x_. |
| static [asinh](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#asinhnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the inverse hyperbolic sine of _x_. |
| static [atan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#atannumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the arc tangent of _x_. |
| static [atan2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#atan2number-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the arc tangent of the quotient y/x of the arguments _y_ and _x_, where the  signs of _y_ and _x_ are used to determine the quadrant of the result. |
| static [atanh](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#atanhnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the inverse hyperbolic tangent of _x_. |
| static [cbrt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#cbrtnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the cube root of _x_. |
| static [ceil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#ceilnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the smallest (closest to -&#8734;) number value that is not less than _x_ and is equal to a  mathematical integer. |
| static [clz32](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#clz32number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the number of leading zero bits in the 32-bit binary representation of _x_. |
| static [cos](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#cosnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the cosine of _x_. |
| static [cosh](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#coshnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the hyperbolic cosine of _x_. |
| static [exp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#expnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the exponential function of _x_ (e raised to the power  of x, where e is the base of the natural logarithms). |
| static [expm1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#expm1number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to subtracting 1 from the exponential function of _x_ (e raised to the power of _x_, where e  is the base of the natural logarithms). |
| static [floor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#floornumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the greatest (closest to +&#8734;) number value that is not greater than _x_ and is equal to a  mathematical integer. |
| static [fround](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#froundnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the nearest 32-bit single precision float representation of _x_. |
| static [hypot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#hypotnumber)([Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation of the square root of the sum of squares of the arguments. |
| static [imul](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#imulnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Performs a 32 bit integer multiplication, where the result is always a 32 bit integer value, ignoring any overflows. |
| static [log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#lognumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the natural logarithm of _x_. |
| static [log10](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#log10number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the base 10 logarithm of _x_. |
| static [log1p](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#log1pnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the natural logarithm of of 1 + _x_. |
| static [log2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#log2number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the base 2 logarithm of _x_. |
| static [max](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#maxnumber)([Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the largest specified values. |
| static [min](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#minnumber)([Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the smallest of the specified values. |
| static [pow](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#pownumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the result of raising _x_ to the power _y_. |
| static [random](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#random)() | Returns a number value with positive sign, greater than or equal to 0 but less than 1, chosen randomly or pseudo  randomly with approximately uniform distribution over that range, using an implementation-dependent algorithm or  strategy. |
| static [round](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#roundnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the number value that is closest to _x_ and is equal to a mathematical integer. |
| static [sign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#signnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the sign of _x_, indicating whether _x_ is positive, negative, or zero. |
| static [sin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#sinnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the sine of _x_. |
| static [sinh](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#sinhnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the hyperbolic sine of _x_. |
| static [sqrt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#sqrtnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the square root of _x_. |
| static [tan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#tannumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the tangent of _x_. |
| static [tanh](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#tanhnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an approximation to the hyperbolic tangent of _x_. |
| static [trunc](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md#truncnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the integral part of the number _x_, removing any fractional digits. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### E

- E: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The constant _e_, which is the base of natural logarithms.


---

### LN10

- LN10: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The natural logarithm of 10.


---

### LN2

- LN2: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The natural logarithm of 2.


---

### LOG10E

- LOG10E: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The base-10 logarithm of _e_.


---

### LOG2E

- LOG2E: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The base-2 logarithm of _e_.


---

### PI

- PI: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The constant for PI.


---

### SQRT1_2

- SQRT1_2: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : 1 divided by the square root of 2.


---

### SQRT2

- SQRT2: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The square root of 2.


---

## Constructor Details

### Math()
- Math()
  - : 


---

## Method Details

### abs(Number)
- static abs(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the absolute value of _x_. The result has the same magnitude as _x_ but has positive sign.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is -0, the result is +0.
      - If _x_is -&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the absolute value of _x_.


---

### acos(Number)
- static acos(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the arc cosine of _x_. The result is expressed in radians and ranges from +0 to
      +p.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is greater than 1, the result is NaN.
      - If _x_is less than -1, the result is NaN.
      - If _x_is exactly 1, the result is +0.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the arc cosine of _x_.


---

### acosh(Number)
- static acosh(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the inverse hyperbolic cosine of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is less than 1, the result is NaN.
      - If _x_is exactly 1, the result is +0.
      - If _x_is +&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the inverse hyperbolic cosine of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### asin(Number)
- static asin(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the arc sine of _x_. The result is expressed in radians and ranges from -p/2 to
      +p/2.
      
      - If _x_is NaN, the result is NaN
      - If _x_is greater than 1, the result is NaN.
      - If _x_is less than -1, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the arc sine of _x_.


---

### asinh(Number)
- static asinh(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the inverse hyperbolic sine of _x_.
      
      - If _x_is NaN, the result is NaN
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is -&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the inverse hyperbolic sine of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### atan(Number)
- static atan(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the arc tangent of _x_. The result is expressed in radians and ranges from -p/2
      to +p/2.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is an approximation to +p/2.
      - If _x_is -&#8734;, the result is an approximation to -p/2.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the arc tangent of _x_.


---

### atan2(Number, Number)
- static atan2(y: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the arc tangent of the quotient y/x of the arguments _y_ and _x_, where the
      signs of _y_ and _x_ are used to determine the quadrant of the result. Note that it is intentional and
      traditional for the two-argument arc tangent function that the argument named _y_ be first and the argument
      named _x_ be second. The result is expressed in radians and ranges from -p to +p.
      
      - If either _x_or _y_is NaN, the result is NaN.
      - If _y_>0 and _x_is +0, the result is an implementation-dependent approximation to +p/2.
      - If _y_>0 and _x_is -0, the result is an implementation-dependent approximation to +p/2.
      - If _y_is +0 and _x_>0, the result is +0.
      - If _y_is +0 and _x_is +0, the result is +0.
      - If _y_is +0 and _x_is -0, the result is an implementation-dependent approximation to +p.
      - If _y_is +0 and _X_<0, the result is an implementation-dependent approximation to +p.
      - If _y_is -0 and _x_>0, the result is -0.
      - If _y_is -0 and _x_is +0, the result is -0.
      - If _y_is -0 and _x_is -0, the result is an implementation-dependent approximation to -p.
      - If _y_is -0 and _X_<0, the result is an implementation-dependent approximation to -p.
      - If _y_<0 and _x_is +0, the result is an implementation-dependent approximation to -p/2.
      - If _y_<0 and _x_is -0, the result is an implementation-dependent approximation to -p/2.
      - If _y_>0 and _y_is finite and _x_is +&#8734;, the result is +0.
      - If _y_>0 and _y_is finite and _x_is -&#8734;, the result if an implementation-dependent  approximation to +p.
      - If _y_<0 and _y_is finite and _x_is +&#8734;, the result is -0.
      - If _y_<0 and _y_is finite and _x_is -&#8734;, the result is an implementation-dependent  approximation to -p.
      - If _y_is +&#8734;and _x_is finite, the result is an implementation-dependent approximation to  +p/2.
      - If _y_is -&#8734;and _x_is finite, the result is an implementation-dependent approximation to  -p/2.
      - If _y_is +&#8734;and _x_is +&#8734;, the result is an implementation-dependent approximation to  +p/4.
      - If _y_is +&#8734;and _x_is -&#8734;, the result is an implementation-dependent approximation to  +3p/4.
      - If _y_is -&#8734;and _x_is +&#8734;, the result is an implementation-dependent approximation to  -p/4.
      - If _y_is -&#8734;and _x_is -&#8734;, the result is an implementation-dependent approximation to  -3p/4.


    **Parameters:**
    - y - the first argument.
    - x - the second argument.

    **Returns:**
    - approximation to the arc tangent of the quotient _y/x_ of the arguments _y_ and x, where the
              signs of _y_ and _x_ are used to determine the quadrant of the result.



---

### atanh(Number)
- static atanh(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the inverse hyperbolic tangent of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is less than -1, the result is NaN.
      - If _x_is greater than 1, the result is NaN.
      - If _x_is exactly -1, the result is -&#8734;.
      - If _x_is exactly +1, the result is +&#8734;.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the inverse hyperbolic tangent of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### cbrt(Number)
- static cbrt(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the cube root of _x_.
      
      - If _x_is NaN, the result is NaN
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is -&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the cube root of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### ceil(Number)
- static ceil(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the smallest (closest to -&#8734;) number value that is not less than _x_ and is equal to a
      mathematical integer. If _x_ is already an integer, the result is _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is -&#8734;.
      - If _x_is less than 0 but greater than -1, the result is -0.
      
      The value of Math.ceil(x) is the same as the value of -Math.floor(-x).


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the smallest (closest to -&#8734;) number value that is not less than _x_ and is equal to a
              mathematical integer.



---

### clz32(Number)
- static clz32(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of leading zero bits in the 32-bit binary representation of _x_.

    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the number of leading zero bits in the 32-bit binary representation of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### cos(Number)
- static cos(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the cosine of _x_. The argument is expressed in radians.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is 1.
      - If _x_is -0, the result is 1.
      - If _x_is +&#8734;, the result is NaN.
      - If _x_is -&#8734;, the result is NaN.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the cosine of _x_.


---

### cosh(Number)
- static cosh(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the hyperbolic cosine of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is 1.
      - If _x_is -0, the result is 1.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the hyperbolic cosine of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### exp(Number)
- static exp(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the exponential function of _x_ (e raised to the power
      of x, where e is the base of the natural logarithms).
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is 1.
      - If _x_is -0, the result is 1.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is +0.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the exponential function of _x_.


---

### expm1(Number)
- static expm1(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to subtracting 1 from the exponential function of _x_ (e raised to the power of _x_, where e
      is the base of the natural logarithms). The result is computed in a way that is accurate even when the value of _x_
      is close 0.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is -1.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an  approximation to subtracting 1 from the exponential function of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### floor(Number)
- static floor(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the greatest (closest to +&#8734;) number value that is not greater than _x_ and is equal to a
      mathematical integer. If _x_ is already an integer, the result is _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is -&#8734;.
      - If _x_is greater than 0 but less than 1, the result is +0.
      
      The value of Math.floor(_x_) is the same as the value of -Math.ceil(_-x_).


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the greatest (closest to +&#8734;) number value that is not greater than _x_ and is equal to a
              mathematical integer.



---

### fround(Number)
- static fround(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the nearest 32-bit single precision float representation of _x_.

    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the nearest 32-bit single precision float representation of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### hypot(Number...)
- static hypot(values: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation of the square root of the sum of squares of the arguments.
      
      - If no arguments are passed, the result is +0.
      - If any argument is +&#8734;, the result is +&#8734;.
      - If any argument is -&#8734;, the result is +&#8734;.
      - If no argument is +&#8734;or -&#8734;and any argument is NaN, the result is NaN.
      - If all arguments are either +0 or -0, the result is +0.


    **Parameters:**
    - values - the Number values to operate on.

    **Returns:**
    - an approximation of the square root of the sum of squares of the arguments.

    **API Version:**
**note:** Available from version 21.2.

---

### imul(Number, Number)
- static imul(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), y: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Performs a 32 bit integer multiplication, where the result is always a 32 bit integer value, ignoring any overflows.

    **Parameters:**
    - x - The first operand.
    - y - The second operand.

    **Returns:**
    - Returns the result of the 32 bit multiplication. The result is a 32 bit signed integer value.

    **API Version:**
**note:** Available from version 21.2.

---

### log(Number)
- static log(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the natural logarithm of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is less than 0, the result is NaN.
      - If _x_is +0 or -0, the result is -&#8734;.
      - If _x_is 1, the result is +0.
      - If _x_is +&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the natural logarithm of _x_.


---

### log10(Number)
- static log10(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the base 10 logarithm of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is less than 0, the result is NaN.
      - If _x_is +0 or -0, the result is -&#8734;.
      - If _x_is 1, the result is +0.
      - If _x_is +&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the base 10 logarithm of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### log1p(Number)
- static log1p(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the natural logarithm of of 1 + _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is less than -1, the result is NaN.
      - If _x_is -1, the result is -&#8734;.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the natural logarithm of of 1 + _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### log2(Number)
- static log2(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the base 2 logarithm of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is less than 0, the result is NaN.
      - If _x_is +0 or -0, the result is -&#8734;.
      - If _x_is 1, the result is +0.
      - If _x_is +&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the base 2 logarithm of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### max(Number...)
- static max(values: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the largest specified values. If no arguments are given, the result is -&#8734;. If any value is NaN, the
      result is NaN.


    **Parameters:**
    - values - zero or more values.

    **Returns:**
    - the largest of the specified values.


---

### min(Number...)
- static min(values: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the smallest of the specified values. If no arguments are given, the result is +&#8734;. If any value is
      NaN, the result is NaN.


    **Parameters:**
    - values - zero or more values.

    **Returns:**
    - the smallest of the specified values.


---

### pow(Number, Number)
- static pow(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), y: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the result of raising _x_ to the power _y_.
      
      - If _y_is NaN, the result is NaN.
      - If _y_is +0, the result is 1, even if _x_is NaN.
      - If _y_is -0, the result is 1, even if _x_is NaN.
      - If _x_is NaN and _y_is nonzero, the result is NaN.
      - If abs(_x_)>1 and _y_is +&#8734;, the result is +&#8734;.
      - If abs(_x_)>1 and _y_is -&#8734;, the result is +0.
      - If abs(_x_)==1 and _y_is +&#8734;, the result is NaN.
      - If abs(_x_)==1 and _y_is -&#8734;, the result is NaN.
      - If abs(_x_)<1 and _y_is +&#8734;, the result is +0.
      - If abs(_x_)<1 and _y_is -&#8734;, the result is +&#8734;.
      - If _x_is +&#8734;and _y_>0, the result is +&#8734;.
      - If _x_is +&#8734;and _y_<0, the result is +0.
      - If _x_is -&#8734;and _y_>0 and _y_is an odd integer, the result is -&#8734;.
      - If _x_is -&#8734;and _y_>0 and _y_is not an odd integer, the result is +&#8734;.
      - If _x_is -&#8734;and _y_<0 and _y_is an odd integer, the result is -0.
      - If _x_is -&#8734;and _y_<0 and _y_is not an odd integer, the result is +0.
      - If _x_is +0 and _y_>0, the result is +0.
      - If _x_is +0 and _y_<0, the result is +&#8734;.
      - If _x_is -0 and _y_>0 and _y_is an odd integer, the result is -0.
      - If _x_is -0 and _y_>0 and _y_is not an odd integer, the result is +0.
      - If _x_is -0 and _y_<0 and _y_is an odd integer, the result is -&#8734;.
      - If _x_is -0 and _y_<0 and _y_is not an odd integer, the result is +&#8734;.
      - If _X_<0 and _x_is finite and _y_is finite and _y_is not an integer, the result is  NaN.


    **Parameters:**
    - x - a Number that will be raised to the power of _y_.
    - y - the power by which _x_ will be raised.

    **Returns:**
    - an approximation to the result of raising _x_ to the power _y_.


---

### random()
- static random(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns a number value with positive sign, greater than or equal to 0 but less than 1, chosen randomly or pseudo
      randomly with approximately uniform distribution over that range, using an implementation-dependent algorithm or
      strategy.


    **Returns:**
    - a Number greater than or equal to 0 but less than 1.


---

### round(Number)
- static round(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number value that is closest to _x_ and is equal to a mathematical integer. If two integer
      number values are equally close to x, then the result is the number value that is closer to +&#8734;. If _x_
      is already an integer, the result is _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is -&#8734;.
      - If _x_is greater than 0 but less than 0.5, the result is +0.
      - If _x_is less than 0 but greater than or equal to -0.5, the result is -0.
      
      Math.round(3.5) returns 4, but Math.round(-3.5) returns -3. The value of Math.round(_x_) is the same as the
      value of Math.floor(_x_+0.5), except when _x_ is -0 or is less than 0 but greater than or equal to
      -0.5; for these cases Math.round(_x_) returns -0, but Math.floor(_x_+0.5) returns +0.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the number value that is closest to _x_ and is equal to a mathematical integer.


---

### sign(Number)
- static sign(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the sign of _x_, indicating whether _x_ is positive, negative, or zero.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is -0, the result is -0.
      - If _x_is +0, the result is +0.
      - If _x_is negative and not -0, the result is -1.
      - If _x_is positive and not +0, the result is +1.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the sign of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### sin(Number)
- static sin(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the sine of _x_. The argument is expressed in radians.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;or -&#8734;, the result is NaN.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the sine of _x_.


---

### sinh(Number)
- static sinh(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the hyperbolic sine of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is -&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the hyperbolic sine of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### sqrt(Number)
- static sqrt(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the square root of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_isless than 0, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +&#8734;.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the square root of _x_.


---

### tan(Number)
- static tan(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the tangent of _x_. The argument is expressed in radians.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;or -&#8734;, the result is NaN.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the tangent of _x_.


---

### tanh(Number)
- static tanh(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an approximation to the hyperbolic tangent of _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is +0, the result is +0.
      - If _x_is -0, the result is -0.
      - If _x_is +&#8734;, the result is +1.
      - If _x_is -&#8734;, the result is -1.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - an approximation to the hyperbolic tangent of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

### trunc(Number)
- static trunc(x: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the integral part of the number _x_, removing any fractional digits. If _x_ is already an integer, the result is _x_.
      
      - If _x_is NaN, the result is NaN.
      - If _x_is -0, the result is -0.
      - If _x_is +0, the result is +0.
      - If _x_is -&#8734;, the result is -&#8734;.
      - If _x_is +&#8734;, the result is +&#8734;.
      - If _x_is greater than 0 but less than 1, the result is +0.
      - If _x_is less than 0 but greater than -1, the result is -0.


    **Parameters:**
    - x - the Number to operate on.

    **Returns:**
    - the integral part of the number of _x_.

    **API Version:**
**note:** Available from version 21.2.

---

<!-- prettier-ignore-end -->

<!-- document id=797adb9e318098ed86df14f117621112562b303e1a802af6ddc536b5cba41734 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.MediaFile.md -->

<!-- prettier-ignore-start -->
# Class MediaFile

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.content.MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)

This class represents references to media content (such as images)
located within Commerce Cloud Digital or on external systems.


Parameter `transform`:


Some methods allow the specification of image transformation parameters. Image
transformation is only performed if the Dynamic Imaging Service (DIS) is available
for the Commerce Cloud Digital instance, otherwise a standard static content URL
is returned. The to-be-transformed image needs to be hosted on Commerce Cloud
Digital.


Image transformation parameters are specified as JavaScript object literal. They
are translated into URL parameters. See [Create Image Transformation URLs.](https://help.salesforce.com/s/articleView?id=cc.b2c\_creating\_image\_transformation\_urls.htm)


| Type of transformation | Parameters | Description |
| --- |--- |--- |
| Scale an image |           `scaleWidth`<br/>          `scaleHeight`<br/>          `scaleMode`       |           The `scaleWidth` and `scaleHeight` parameters          are both integers; setting one of these parameters triggers a          scaling operation. If both are provided, the one that scales the          image less is used to calculate the scale factor. The image is then          automatically cropped accord to the second dimension, with a          centered position of the cropped area. If the parameter would scale          the image larger, only this operation is applied, if the image          remains within acceptable pixel dimensions.<p/>           Note: `scaleMode` can only be used in combination with `scaleHeight` and `scaleWidth`.<p/>           The `scaleMode` parameter can be set to `cut`          or `fit`. The default `scaleMode` is          `cut`, the behavior of which is explained above. If you          specify `fit` as the `scaleMode`, the system          scales the image into the given box of dimensions while keeping the          aspect ratio (possibly resulting in a smaller image in one          dimension).       |
| Overlay an image |           `imageX`<br/>          `imageY`<br/>          `imageURI`       |           The `imageX` and `imageY` parameters are both          integers. Valid values for these parameters are 0 or greater.<p/>           Supported formats are `png`, `jpg`, `jp2`, and          `gif`.<p/>           The `imageURI` parameter can be set to the absolute path          of the overlaid image. The value of the `imageURI`          parameter must be given in proper URL encoding, and it cannot exceed          400 characters in length. The path may include query string          parameters, which supports dynamically generating the overlaid image          itself through this service; that is, the overlaid image can itself          be a transformed image.<p/>           If the overlaid image extends over the primary image's boundaries,          the overlaid image is cropped so that it fits directly over the          primary image.       |
| Crop an image |           `cropX`<br/>          `cropY`<br/>          `cropWidth`<br/>          `cropHeight`       |           The `cropX`, `cropY`, `cropWidth`,          `cropHeight` parameters are integers. All four parameters          must be specified to trigger a cropping operation.<p/>           Valid values for the `cropX` and `cropY`          parameters are 0 or greater. If the crop location defined by          `cropX` and `cropY` is outside the image area,          nothing is cropped.<p/>           Valid values for the `cropWidth` and          `cropHeight` parameters are 10 or greater. If the          `cropWidth` and `cropHeight` parameters          specify a size that is greater than the original image, the crop          area is reduced to the actual image area. If `cropWidth`          and `cropHeight` are 0 or less, no transformation is          applied.       |
| Format an image | `format` |           The `format` parameter specifies the target format of          image. Supported formats are `png`, `jpg`, `jp2`, and          `gif`. If no target format is specified, no format          conversion is performed.<p/>           The attribute value must reference the source image. Source image's          format is recognized by the file extension which must be          `tif`, `tiff`, `jpg`,          `jpeg`, `png`, or `gif`.<p/>           In the generated URL the file extension of the target format is used          in the URL path. This is to make sure the image is loaded from an          URL with a matching file extension. The source format is provided as          URL parameter.       |
| Adjust image compression quality | `quality` |           The `quality` parameter specifies a quality setting for `jpg` and `jp2` images,          and specifies the compression level for `png` images.<p/>           For `jpg` and `jp2` images, you can set values from 1–100 for the highest quality.          The default quality is 80. If you're not changing the default quality, you don't need to pass in a value.<p/>           For `png` images, the quality setting has no effect on the appearance of the `png`, since the compression is always lossless.          Instead you can use the quality setting to set the zlib compression level and filter-type for PNG images.          The tens digit sets the zlib compression level(1-9). The ones digit sets the filter type.<p/>           If the `png` setting is not present or set to 0, it uses a default value of 75.          If this setting is set to 100, it actually equals the quality setting 90.       |
| Adjust Metadata stripping | `strip` |           The `strip` parameter specifies if metadata like EXIF and color profiles is          stripped from the image during transformation.<p/>           Valid values for the `strip` parameter are between `true` and `false`.          The default is `true`       |
| Change background color | `bgcolor(color) or bgcolor(color+alpha)` |           The `bgcolor` parameter specifies the background color for images that support transparency          as well as JPEG images when being converted from a format that supports transparency.          Optionally, alpha setting for PNG images are also supported.<p/>           `bgcolor` expects a 6 digit hexadecimal value of RGB with an optional          two hexadecimal characters representing alpha value that determines transparency.<p/>           FF0000 = Red<p/>           FF000077 = Red with 50% transparency<p/>           Alpha values are optional. When the alpha value is omitted, the resulting color is opaque.          Alpha values are only valid when the image output format is PNG.       |


Example:

   The following code

   `var url = product.getImage('thumbnail', 0).getImageURL({scaleWidth: 100, format: 'jpg'});`

   will produce an image transformation URL like

   `http://<image server host name>/.../on/demandware.static/.../<path to image>/image.jpg?sw=100&sfrm=png`.



## Property Summary

| Property | Description |
| --- | --- |
| [URL](#url): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)` | Returns an URL to the referenced media file. |
| [absURL](#absurl): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)` | Returns an absolute URL to the referenced media file. |
| [alt](#alt): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the alternative text assigned to the media file in current  requests locale. |
| [httpURL](#httpurl): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)` | Returns an absolute URL to the referenced media file. |
| [httpsURL](#httpsurl): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)` | Returns an absolute URL to the referenced media file. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the title assigned to the media file in current requests locale. |
| ~~[url](#url): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~ `(read-only)` | Returns an URL to the referenced media file. |
| [viewType](#viewtype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the view type annotation for the media file. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAbsImageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#getabsimageurlobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns an URL to the referenced image file. |
| [getAbsURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#getabsurl)() | Returns an absolute URL to the referenced media file. |
| [getAlt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#getalt)() | Returns the alternative text assigned to the media file in current  requests locale. |
| [getHttpImageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#gethttpimageurlobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns an URL to the referenced image file. |
| [getHttpURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#gethttpurl)() | Returns an absolute URL to the referenced media file. |
| [getHttpsImageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#gethttpsimageurlobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns an URL to the referenced image file. |
| [getHttpsURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#gethttpsurl)() | Returns an absolute URL to the referenced media file. |
| [getImageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#getimageurlobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns an URL to the referenced image file. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#gettitle)() | Returns the title assigned to the media file in current requests locale. |
| [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#geturl)() | Returns an URL to the referenced media file. |
| ~~[getUrl](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#geturl)()~~ | Returns an URL to the referenced media file. |
| [getViewType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#getviewtype)() | Returns the view type annotation for the media file. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### URL
- URL: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)`
  - : Returns an URL to the referenced media file. The
      returned URL is a relative URL.



---

### absURL
- absURL: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)`
  - : Returns an absolute URL to the referenced media file. The
      protocol for the reference is the current protocol of the current
      HTTP request.



---

### alt
- alt: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the alternative text assigned to the media file in current
      requests locale. If no alternative text was assigned or if no defaulting
      rule was defined, the method returns null.



---

### httpURL
- httpURL: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)`
  - : Returns an absolute URL to the referenced media file. The
      protocol is http.



---

### httpsURL
- httpsURL: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)`
  - : Returns an absolute URL to the referenced media file. The
      protocol is https.



---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the title assigned to the media file in current requests locale.
      If no title was assigned or if no defaulting rule was defined, the
      method returns null.



---

### url
- ~~url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~ `(read-only)`
  - : Returns an URL to the referenced media file. The
      returned URL is a relative URL.


    **Deprecated:**
**warning:** Use [getURL()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#geturl) instead.

---

### viewType
- viewType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the view type annotation for the media file. The method returns
      null, if the media file has no view type annotation.



---

## Method Details

### getAbsImageURL(Object)
- getAbsImageURL(transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL to the referenced image file. Image transformation
      can be applied to the image. The protocol for the reference is the
      current protocol of the current HTTP request.
      
      Image transformation can only be applied to images that are hosted on
      Commerce Cloud Digital.


    **Parameters:**
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - an absolute URL to the referenced media file. The
      protocol for the reference is the current protocol of the current
      HTTP request. If the referenced media file is hosted externally,
      an URL to the external file is returned.



---

### getAbsURL()
- getAbsURL(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an absolute URL to the referenced media file. The
      protocol for the reference is the current protocol of the current
      HTTP request.


    **Returns:**
    - an absolute URL to the referenced media file. The
      protocol for the reference is the current protocol of the current
      HTTP request.



---

### getAlt()
- getAlt(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the alternative text assigned to the media file in current
      requests locale. If no alternative text was assigned or if no defaulting
      rule was defined, the method returns null.


    **Returns:**
    - the alternative text annotated to this media file or null


---

### getHttpImageURL(Object)
- getHttpImageURL(transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL to the referenced image file. Image transformation
      can be applied to the image. The protocol is http.
      
      Image transformation can only be applied to images that are hosted on
      Commerce Cloud Digital.


    **Parameters:**
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - an absolute URL to the referenced media file. The
      protocol is http. If the referenced media file is hosted externally,
      an URL to the external file is returned.



---

### getHttpURL()
- getHttpURL(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an absolute URL to the referenced media file. The
      protocol is http.


    **Returns:**
    - an absolute URL to the referenced media file. The
      protocol is http.



---

### getHttpsImageURL(Object)
- getHttpsImageURL(transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL to the referenced image file. Image transformation
      can be applied to the image. The protocol is https.
      
      Image transformation can only be applied to images that are hosted on
      Commerce Cloud Digital.


    **Parameters:**
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - an absolute URL to the referenced media file. The
      protocol is https. If the referenced media file is hosted externally,
      an URL to the external file is returned.



---

### getHttpsURL()
- getHttpsURL(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an absolute URL to the referenced media file. The
      protocol is https.


    **Returns:**
    - an absolute URL to the referenced media file. The
      protocol is https.



---

### getImageURL(Object)
- getImageURL(transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL to the referenced image file. Image transformation
      can be applied to the image.
      
      Image transformation can only be applied to images that are hosted on
      Commerce Cloud Digital.


    **Parameters:**
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - an URL to the referenced media file. The
      returned URL is a relative URL. If the referenced media file is hosted
      externally, an URL to the external file is returned.



---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the title assigned to the media file in current requests locale.
      If no title was assigned or if no defaulting rule was defined, the
      method returns null.


    **Returns:**
    - the title annotated to this media file or null


---

### getURL()
- getURL(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL to the referenced media file. The
      returned URL is a relative URL.


    **Returns:**
    - an URL to the referenced media file. The
      returned URL is a relative URL.



---

### getUrl()
- ~~getUrl(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Returns an URL to the referenced media file. The
      returned URL is a relative URL.


    **Returns:**
    - an URL to the referenced media file. The
      returned URL is a relative URL.


    **Deprecated:**
**warning:** Use [getURL()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md#geturl) instead.

---

### getViewType()
- getViewType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the view type annotation for the media file. The method returns
      null, if the media file has no view type annotation.


    **Returns:**
    - the view type annotated to this media file or null


---

<!-- prettier-ignore-end -->

<!-- document id=e807bbead380ee079ddaa469488fc6cc09d05d3e83f1213a35ac5185e3336018 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.MessageDigest.md -->

<!-- prettier-ignore-start -->
# Class MessageDigest

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.MessageDigest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md)

This class provides the functionality of a message digest algorithm, such as
MD5 or SHA. Message digests are secure one-way hash functions that take
arbitrary-sized data and output a fixed-length hash value. This
implementation offers only stateless digest() methods. A Bytes object or
String is passed to a digest() method and the computed hash is returned.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[DIGEST_MD2](#digest_md2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD2"~~ | Constant representing the MD2 algorithm. |
| ~~[DIGEST_MD5](#digest_md5): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD5"~~ | Constant representing the MD5 algorithm. |
| ~~[DIGEST_SHA](#digest_sha): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA"~~ | Constant representing the SHA algorithm. |
| ~~[DIGEST_SHA_1](#digest_sha_1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-1"~~ | Constant representing the SHA 1 algorithm. |
| [DIGEST_SHA_256](#digest_sha_256): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-256" | Constant representing the SHA 256 algorithm |
| [DIGEST_SHA_512](#digest_sha_512): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-512" | Constant representing the SHA 512 algorithm |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [MessageDigest](#messagedigeststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a MessageDigest with the specified algorithm name. |

## Method Summary

| Method | Description |
| --- | --- |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md#digest)() | Completes the hash computation by performing final operations such as  padding. |
| ~~[digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md#digeststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Digests the passed string and returns a computed hash value as a string. |
| ~~[digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md#digeststring-bytes)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md))~~ | Computes the hash value for the passed array of bytes. |
| [digestBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md#digestbytesbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Computes the hash value for the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md). |
| [updateBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md#updatebytesbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Updates the digest using the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DIGEST_MD2

- ~~DIGEST_MD2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD2"~~
  - : Constant representing the MD2 algorithm.

    **Deprecated:**
**warning:** This algorithm is obsolete and and has been deprecated. Please use SHA-256 or SHA-512.

---

### DIGEST_MD5

- ~~DIGEST_MD5: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD5"~~
  - : Constant representing the MD5 algorithm.

    **Deprecated:**
**warning:** This algorithm is obsolete and and has been deprecated. Please use SHA-256 or SHA-512.

---

### DIGEST_SHA

- ~~DIGEST_SHA: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA"~~
  - : Constant representing the SHA algorithm.

    **Deprecated:**
**warning:** This algorithm is obsolete and and has been deprecated. Please use SHA-256 or SHA-512.

---

### DIGEST_SHA_1

- ~~DIGEST_SHA_1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-1"~~
  - : Constant representing the SHA 1 algorithm.

    **Deprecated:**
**warning:** This algorithm is obsolete and and has been deprecated. Please use SHA-256 or SHA-512.

---

### DIGEST_SHA_256

- DIGEST_SHA_256: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-256"
  - : Constant representing the SHA 256 algorithm


---

### DIGEST_SHA_512

- DIGEST_SHA_512: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-512"
  - : Constant representing the SHA 512 algorithm


---

## Constructor Details

### MessageDigest(String)
- MessageDigest(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a MessageDigest with the specified algorithm name. The
      supported algorithms are:
      
      
      - SHA-256
      - SHA-512


    **Parameters:**
    - algorithm - The standard name of the digest algorithm, must not be         null and must be a supported algorithm.


---

## Method Details

### digest()
- digest(): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Completes the hash computation by performing final operations such as
      padding.
      
      The binary representation of the message is typically derived from a
      string and the resulting hash is typically converted with base64 back
      into a string. Example:
      
      `
       Encoding.toBase64( digest() );
       `


    **Returns:**
    - The resulting hash value.


---

### digest(String)
- ~~digest(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Digests the passed string and returns a computed hash value as a string.
      The passed String is first encoded into a sequence of bytes using the
      platform's default encoding. The digest then performs any prerequisite
      padding, before computing the hash value. The hash is then converted into
      a string by converting all digits to hexadecimal.


    **Parameters:**
    - input - The value to hash as String, must not be null.

    **Returns:**
    - The resulting hash value as hex-encoded string.

    **Deprecated:**
**warning:** Deprecated because the conversion of the input to bytes using
            the default platform encoding and the hex-encoded return
            value are not generally appropriate.

---

### digest(String, Bytes)
- ~~digest(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)~~
  - : Computes the hash value for the passed array of bytes. The algorithm
      argument is optional. If null, then the algorithm established at
      construction time is used.
      
      The binary representation of the message is typically derived from a
      string and the resulting hash is typically converted with base64 back
      into a string. Example:
      
      `
       Encoding.toBase64( digest( "MD5", new Bytes( "my password", "UTF-8" ) ) );
       `


    **Parameters:**
    - algorithm - The standard name of the digest algorithm, or null if             the algorithm passed at construction time is to be used.             The algorithm must be a supported algorithm.
    - input - The value to hash, must not be null.

    **Returns:**
    - The resulting hash value.

    **Deprecated:**
**warning:** Deprecated because the digest algorithm should be the one
            set in the constructor.

---

### digestBytes(Bytes)
- digestBytes(input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md).
      
      The binary representation of the message is typically derived from a
      string and the resulting hash is typically converted with base64 back
      into a string. Example:
      
      `
       Encoding.toBase64( digest( new Bytes( "my password", "UTF-8" ) ) );
       `


    **Parameters:**
    - input - The value to hash, must not be null.

    **Returns:**
    - The resulting hash value.


---

### updateBytes(Bytes)
- updateBytes(input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): void
  - : Updates the digest using the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md).

    **Parameters:**
    - input - The value to hash, must not be null.


---

<!-- prettier-ignore-end -->

<!-- document id=26d6041a5b91068e22603d275535a78d1cf814a4e9d5c8542a201aff6135560c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.value.MimeEncodedText.md -->

<!-- prettier-ignore-start -->
# Class MimeEncodedText

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.value.MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md)

Container for an arbitrary text string its mime type, and encoding


## Property Summary

| Property | Description |
| --- | --- |
| [encoding](#encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the encoding of the text. |
| [mimeType](#mimetype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the mime type of the text. |
| [text](#text): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the text. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [MimeEncodedText](#mimeencodedtextstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new MimeEncodedText with explicit values for mime type and  encoding. |
| [MimeEncodedText](#mimeencodedtextstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new MimeEncodedText with the given String as text, mime type of  "text/plain;charset=UTF-8" and encoding of "UTF-8" |

## Method Summary

| Method | Description |
| --- | --- |
| [getEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md#getencoding)() | Returns the encoding of the text. |
| [getMimeType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md#getmimetype)() | Returns the mime type of the text. |
| [getText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md#gettext)() | Returns the text. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### encoding
- encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the encoding of the text. Encoding is set at creation time and
      can't be changed afterwards



---

### mimeType
- mimeType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the mime type of the text. Mime type is set at creation time and
      can't be changed afterwards.



---

### text
- text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the text. Text is set at creation time and can't be changed
      afterwards.



---

## Constructor Details

### MimeEncodedText(String, String, String)
- MimeEncodedText(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), mimeType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new MimeEncodedText with explicit values for mime type and
      encoding.


    **Parameters:**
    - text - text to be stored
    - mimeType - mime type of the text. For example, "text/plain" or             "text/html"
    - encoding - Encoding of the text. For example, "UTF-8" or "ISO-8859-1"


---

### MimeEncodedText(String)
- MimeEncodedText(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new MimeEncodedText with the given String as text, mime type of
      "text/plain;charset=UTF-8" and encoding of "UTF-8"


    **Parameters:**
    - text - text to be stored


---

## Method Details

### getEncoding()
- getEncoding(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the encoding of the text. Encoding is set at creation time and
      can't be changed afterwards


    **Returns:**
    - encoding of the text


---

### getMimeType()
- getMimeType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the mime type of the text. Mime type is set at creation time and
      can't be changed afterwards.


    **Returns:**
    - the MimeType of the text


---

### getText()
- getText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the text. Text is set at creation time and can't be changed
      afterwards.


    **Returns:**
    - text stored


---

<!-- prettier-ignore-end -->

<!-- document id=9d69d2c7038b9231df2a7f0980abff8746caa590bbf83f3bbcca4f09d353b70c url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Module.md -->

<!-- prettier-ignore-start -->
# Class Module

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md)

CommonJS modules are JavaScript files that are loaded using the [require(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#requirestring)
function. This function returns a module object, which wraps the script code from the file. Within a module
implementation, the module object can be accessed via the [module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#module) variable.


A module has a unique absolute id. The same module may be resolved by [require(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#requirestring)
for different path arguments, like relative paths (starting with "./" or "../"), or absolute paths. See the
documentation of require for more details about the lookup procedure.


Every module object has an [exports](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md#exports) property which can be used by the module implementation to expose its
public functions or properties. Only functions and properties that are explicitly exported are accessible from other
modules, all others are private and not visible. For convenience, the global [exports](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#exports) variable
is by default also initialized with the [module.exports](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md#exports) property of the current module.
In the most simple case, module elements can be exposed by adding them to the exports object, like:


```
// Greeting.js
exports.sayHello = function() {
    return 'Hello World!';
};
```


This is equivalent to:


```
// Greeting.js
module.exports.sayHello = function() {
    return 'Hello World!';
};
```


With the above implementation, a caller (for example another module in the same directory) could call the module
function like this:


```
var message = require('./Greeting').sayHello();
```


It is also possible to replace the whole module exports object with a completely different value, for example with a
function:


```
// Greeting.js
module.exports = function sayHello() {
    return 'Hi!';
}
```


Now the result of require would be a function, which can be invoked directly like:


```
var message = require('./Greeting')();
```


This construction can be used for exporting constructor functions, so that a module becomes something like a class:


```
// Greeting.js
function Greeting()
{
    this.message = 'Hi!';
}

Greeting.prototype.getMessage = function() {
    return this.message;
}

module.exports = Greeting;
```


which would be used like:


```
var Greeting = require('./Greeting');
var m = new Greeting().getMessage();
```



## Property Summary

| Property | Description |
| --- | --- |
| [cartridge](#cartridge): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The name of the cartridge which contains the module. |
| [exports](#exports): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | The exports of the module. |
| [id](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The absolute, normalized id of the module, which uniquely identifies it. |
| [superModule](#supermodule): [Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md) | The module (if exists) that is overridden by this module. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### cartridge
- cartridge: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The name of the cartridge which contains the module.


---

### exports
- exports: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : The exports of the module.


---

### id
- id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The absolute, normalized id of the module, which uniquely identifies it. A call to the
      [global.require(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#requirestring) function with this id would resolve this module.



---

### superModule
- superModule: [Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md)
  - : The module (if exists) that is overridden by this module. The super module would have the same path as the
      current module but its code location would be checked later in the lookup sequence. This property is useful to
      reuse functionality implemented in overridden modules.



---

<!-- prettier-ignore-end -->

<!-- document id=ddca810a5469d419f6ad18d3df3487834a95d696db23f6eaad9e37a4100b73f2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.value.Money.md -->

<!-- prettier-ignore-start -->
# Class Money

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.value.Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)

Represents money in Commerce Cloud Digital.


## Constant Summary

| Constant | Description |
| --- | --- |
| [NOT_AVAILABLE](#not_available): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Represents that there is no money available. |

## Property Summary

| Property | Description |
| --- | --- |
| [available](#available): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the instance contains settings for value and currency. |
| [currencyCode](#currencycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ISO 4217 currency mnemonic (such as 'USD', 'EUR') of the currency the  money value relates to. |
| [decimalValue](#decimalvalue): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) `(read-only)` | Returns the money as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the money is not available. |
| [value](#value): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the value of the money instance. |
| [valueOrNull](#valueornull): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Return the value of the money instance or null if the  Money instance is NOT\_AVAILABLE. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Money](#moneynumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new money instance with the specified amount for the specified  currency. |

## Method Summary

| Method | Description |
| --- | --- |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#addmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Returns a Money instance by adding  the specified Money object to the current object. |
| [addPercent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#addpercentnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Adds a certain percentage to the money object. |
| [addRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#addratenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Adds a rate (e.g. |
| [compareTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#comparetomoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Compares two Money values. |
| [divide](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#dividenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Divide Money object by specified divisor. |
| [equals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#equalsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Compares two money values whether they are equivalent. |
| [getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#getcurrencycode)() | Returns the ISO 4217 currency mnemonic (such as 'USD', 'EUR') of the currency the  money value relates to. |
| [getDecimalValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#getdecimalvalue)() | Returns the money as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the money is not available. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#getvalue)() | Returns the value of the money instance. |
| [getValueOrNull](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#getvalueornull)() | Return the value of the money instance or null if the  Money instance is NOT\_AVAILABLE. |
| [hashCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#hashcode)() | Calculates the hash code for a money; |
| [isAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#isavailable)() | Identifies if the instance contains settings for value and currency. |
| [isOfSameCurrency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#isofsamecurrencymoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Identifies if two Money value have the same currency. |
| [multiply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#multiplynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Multiply Money object by specified factor. |
| [multiply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#multiplyquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Multiplies the Money object with the given quantity. |
| [newMoney](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#newmoneydecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Method returns a new instance of Money with the same currency but  different value. |
| [percentLessThan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#percentlessthanmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Convenience method. |
| [percentOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#percentofmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Convenience method. |
| static [prorate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#proratemoney-money)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Money\[\]](dw.value.Money.md)) | Prorates the specified values using the specified discount. |
| [subtract](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#subtractmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Returns a new Money instance by substracting the specified Money object  from the current object. |
| [subtractPercent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#subtractpercentnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Subtracts a certain percentage from the money object. |
| [subtractRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#subtractratenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Subtracts a rate (e.g. |
| [toFormattedString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#toformattedstring)() | Returns a string representation of Money according to the regional settings configured for current request  locale, for example '$59.00' or 'USD 59.00'. |
| [toNumberString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#tonumberstring)() | Returns a string representation for the numeric value of this money. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#tostring)() | Returns a string representation of this Money object. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#valueof)() | According to the ECMA spec returns the "natural" primitve value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### NOT_AVAILABLE

- NOT_AVAILABLE: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Represents that there is no money available.


---

## Property Details

### available
- available: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the instance contains settings for value and currency.


---

### currencyCode
- currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ISO 4217 currency mnemonic (such as 'USD', 'EUR') of the currency the
      money value relates to.
      
      Note a money instance may also describe a price that is 'not available'.
      In this case the value of this attribute is `N/A`.



---

### decimalValue
- decimalValue: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) `(read-only)`
  - : Returns the money as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the money is not available.


---

### value
- value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the value of the money instance.

    **See Also:**
    - [getDecimalValue()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#getdecimalvalue)


---

### valueOrNull
- valueOrNull: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Return the value of the money instance or null if the
      Money instance is NOT\_AVAILABLE.



---

## Constructor Details

### Money(Number, String)
- Money(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a new money instance with the specified amount for the specified
      currency. Note that each currency has a precision (number of digits after the
      decimal point) and that values beyond the precision are "rounded up" to their
      "nearest neighbor" following the rules of `java.math.RoundingMode.HALF_UP`.


    **Parameters:**
    - value - The value of the money instance. Must not be `null`.
    - currencyCode - The ISO 4217 mnemonic of currency the amount                      is specified in.  Must not be `null`.


---

## Method Details

### add(Money)
- add(value: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns a Money instance by adding
      the specified Money object to the current object. Only objects representing the
      same currency can be added. If one of the Money values is N/A, the
      result is N/A.


    **Parameters:**
    - value - the Money object to add to this Money instance.

    **Returns:**
    - the Money object representing the sum of the operands.


---

### addPercent(Number)
- addPercent(percent: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Adds a certain percentage to the money object. The percent value is given
      as true percent value, so for example 10 represent 10%. If this Money is
      N/A the result is also N/A.


    **Parameters:**
    - percent - the percent value

    **Returns:**
    - new Money object with the result of the calculation


---

### addRate(Number)
- addRate(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Adds a rate (e.g. 0.05) to the money object. This is typically for example
      to add a tax rate.


    **Parameters:**
    - value - the rate to add.

    **Returns:**
    - a new Money object with rate added.


---

### compareTo(Money)
- compareTo(other: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Compares two Money values. An exception is thrown if the two Money values
      are of different currency. If one of the Money values represents the N/A value
      it is treated as 0.0.


    **Parameters:**
    - other - the money instance to comare against this money instance.

    **Returns:**
    - the comparison of 0 if the money instances are equal or non-0 if they are different.


---

### divide(Number)
- divide(divisor: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Divide Money object by specified divisor. If this Money is
      N/A the result is also N/A.


    **Parameters:**
    - divisor - the divisor.

    **Returns:**
    - Money object representing division result


---

### equals(Object)
- equals(other: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Compares two money values whether they are equivalent.

    **Parameters:**
    - other - the object to compare against this money instance.

    **Returns:**
    - true if equal, false otherwise.


---

### getCurrencyCode()
- getCurrencyCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ISO 4217 currency mnemonic (such as 'USD', 'EUR') of the currency the
      money value relates to.
      
      Note a money instance may also describe a price that is 'not available'.
      In this case the value of this attribute is `N/A`.


    **Returns:**
    - the value of the currency code.


---

### getDecimalValue()
- getDecimalValue(): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Returns the money as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the money is not available.

    **Returns:**
    - the money as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)


---

### getValue()
- getValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the money instance.

    **Returns:**
    - the value of the money instance.

    **See Also:**
    - [getDecimalValue()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#getdecimalvalue)


---

### getValueOrNull()
- getValueOrNull(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the value of the money instance or null if the
      Money instance is NOT\_AVAILABLE.


    **Returns:**
    - Value of money instance or null.


---

### hashCode()
- hashCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Calculates the hash code for a money;


---

### isAvailable()
- isAvailable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the instance contains settings for value and currency.

    **Returns:**
    - true if the instance is initialized with value and
              currency, false if the state is 'not available'.



---

### isOfSameCurrency(Money)
- isOfSameCurrency(value: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if two Money value have the same currency.

    **Parameters:**
    - value - the Money value passed to be tested

    **Returns:**
    - true if both instances have the same currency, false otherwise.


---

### multiply(Number)
- multiply(factor: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Multiply Money object by specified factor. If this Money is
      N/A the result is also N/A.


    **Parameters:**
    - factor - multiplication factor

    **Returns:**
    - Money object representing multiplication result.


---

### multiply(Quantity)
- multiply(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Multiplies the Money object with the given quantity. If this Money is
      N/A the result is also N/A.


    **Parameters:**
    - quantity - the quantity to multiply the value by

    **Returns:**
    - a new Money representing the multiplication result.


---

### newMoney(Decimal)
- newMoney(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Method returns a new instance of Money with the same currency but
      different value. An N/A instance is returned if value is null.


    **Parameters:**
    - value - as a decimal

    **Returns:**
    - new Money instance with same currency


---

### percentLessThan(Money)
- percentLessThan(value: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Convenience method.
      Calculates and returns the percentage off this price represents in
      relation to the passed base price.  The result is generally equal to
      `100.0 - this.percentOf(value)`.  For example, if this value
      is $30 and the passed value is $50, then the return
      value will be 40.0, representing a 40% discount.
      
      
      This method will return null if the compare value is null, this value or
      the compare value is unavailable, or the compare value equals 0.0.


    **Parameters:**
    - value - The price to compare to this price

    **Returns:**
    - The percentage discount this price represents in relation to the
      passed base price.


    **Throws:**
    - IllegalArgumentException - If the currencies are not comparable.

    **See Also:**
    - [percentOf(Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#percentofmoney)


---

### percentOf(Money)
- percentOf(value: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Convenience method.
      Calculates and returns the percentage of the passed value this
      price represents.  For example, if this value is $30 and
      the passed value is $50, then the return value will be 60.0 (i.e. 60%).
      
      
      This method will return null if the compare value is null, this value or
      the compare value is unavailable, or the compare value equals 0.0.


    **Parameters:**
    - value - The price to compare to this price

    **Returns:**
    - The percentage of the compare price this price represents, or
      null.


    **Throws:**
    - IllegalArgumentException - If the currencies are not comparable.


---

### prorate(Money, Money[])
- static prorate(dist: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), values: [Money\[\]](dw.value.Money.md)): [Money\[\]](dw.value.Money.md)
  - : Prorates the specified values using the specified discount.

    **Parameters:**
    - dist - the proration discount.
    - values - the values to prorate.

    **Returns:**
    - the prorated values.


---

### subtract(Money)
- subtract(value: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns a new Money instance by substracting the specified Money object
      from the current object. Only objects representing the
      same currency can be subtracted. If one of the Money values is N/A, the
      result is N/A.


    **Parameters:**
    - value - the Money object to subtract

    **Returns:**
    - the Money object representing the result of subtraction.


---

### subtractPercent(Number)
- subtractPercent(percent: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Subtracts a certain percentage from the money object. The percent value is given
      as true percent value, so for example 10 represent 10%. If this Money is
      N/A the result is also N/A.


    **Parameters:**
    - percent - the percent value

    **Returns:**
    - new Money object with the result of the calculation


---

### subtractRate(Number)
- subtractRate(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Subtracts a rate (e.g. 0.05) from the money object. This is typically for example
      to subtract a tax rates.


    **Parameters:**
    - value - the rate to subtract.

    **Returns:**
    - a new Money object with rate subtracted.


---

### toFormattedString()
- toFormattedString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of Money according to the regional settings configured for current request
      locale, for example '$59.00' or 'USD 59.00'.


    **Returns:**
    - The formatted String representation of the passed money. In case of an error the string 'N/A' is
              returned.



---

### toNumberString()
- toNumberString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation for the numeric value of this money.
      The number is formatted with the decimal symbols of the platforms
      default locale.


    **Returns:**
    - a string representation for the numeric value of this money.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this Money object.

    **Returns:**
    - a string representation of this Money object.


---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : According to the ECMA spec returns the "natural" primitve value. Here
      the value portion of the Money is returned.



---

<!-- prettier-ignore-end -->

<!-- document id=3faa0779a3cac305841d35499cc61da86cb49072d73ccbb4c16cb8ed7e8ea17c url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Namespace.md -->

<!-- prettier-ignore-start -->
# Class Namespace

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md)

Namespace objects represent XML namespaces and provide an
association between a namespace prefix and a Unique Resource
Identifier (URI). The prefix is either the undefined value
or a string value that may be used to reference the namespace
within the lexical representation of an XML value. When an
XML object containing a namespace with an undefined prefix is
encoded as XML by the method toXMLString(), the implementation
will automatically generate a prefix.
The URI is a string value used to uniquely identify the namespace.



## Property Summary

| Property | Description |
| --- | --- |
| [prefix](#prefix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the prefix of the Namespace object. |
| [uri](#uri): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Uniform Resource Identifier (URI) of the Namespace object. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Namespace](#namespace)() | Constructs a simple namespace where the  _uri_ and _prefix_ properties are set to an empty string. |
| [Namespace](#namespaceobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs a Namespace object and assigns values to the  _uri_ and _prefix_ properties based on the type  of _uriValue_. |
| [Namespace](#namespaceobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs a Namespace object and assigns values to the  _uri_ and _prefix_ properties. |

## Method Summary

| Method | Description |
| --- | --- |
| [getPrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md#getprefix)() | Returns the prefix of the Namespace object. |
| [getUri](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md#geturi)() | Returns the Uniform Resource Identifier (URI) of the Namespace object. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md#tostring)() | Returns a string representation of this Namespace object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### prefix
- prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the prefix of the Namespace object.


---

### uri
- uri: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Uniform Resource Identifier (URI) of the Namespace object.


---

## Constructor Details

### Namespace()
- Namespace()
  - : Constructs a simple namespace where the
      _uri_ and _prefix_ properties are set to an empty string.
      A namespace with URI set to the empty string represents no namespace.
      No namespace is used in XML objects to explicitly specify
      that a name is not inside a namespace and may never be
      associated with a prefix other than the empty string.



---

### Namespace(Object)
- Namespace(uriValue: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructs a Namespace object and assigns values to the
      _uri_ and _prefix_ properties based on the type
      of _uriValue_. If _uriValue_ is a
      Namespace object, a copy of the Namespace is constructed.
      If _uriValue_ is a QName object, the _uri_ property is
      set to the QName object's _uri_ property.
      Otherwise, _uriValue_ is converted into a string and
      assigned to the _uri_ property.


    **Parameters:**
    - uriValue - the value to use when constructing the Namespace.


---

### Namespace(Object, Object)
- Namespace(prefixValue: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), uriValue: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructs a Namespace object and assigns values to the
      _uri_ and _prefix_ properties.
      
      The value of the _prefixValue_ parameter is assigned to the
      _prefix_ property in the following manner:
      
      1. If undefined is passed, prefix is set to undefined.
      2. If the argument is a valid XML name, it is converted   to a string and assigned to the prefix property.
      3. If the argument is not a valid XML name, the prefix   property is set to undefined.
      
      The value of the _uriValue_ parameter is assigned
      to the _uri_ property in the following manner:
      
      1. If a QName object is passed for the uriValue parameter,   the uri property is set to the value of the QName object's uri property.
      2. If a QName object is not passed for the uriValue parameter,   the uriValue parameter is converted to a string and assigned to the uri property. 


    **Parameters:**
    - prefixValue - the prefix value to use when constructing the Namespace.
    - uriValue - the value to use when constructing the Namespace.


---

## Method Details

### getPrefix()
- getPrefix(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the prefix of the Namespace object.

    **Returns:**
    - the prefix of the Namespace object.


---

### getUri()
- getUri(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Uniform Resource Identifier (URI) of the Namespace object.

    **Returns:**
    - the Uniform Resource Identifier (URI) of the Namespace object.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this Namespace object.

    **Returns:**
    - a string representation of this Namespace object.


---

<!-- prettier-ignore-end -->

<!-- document id=2fea196ec00c9caf526fde042f20a0ef5c79ecef2b5a0d1654c399a6fb21cc30 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.Note.md -->

<!-- prettier-ignore-start -->
# Class Note

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Note](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md)

Represents a note that can be attached to any persistent object
that supports this feature.



## Property Summary

| Property | Description |
| --- | --- |
| [createdBy](#createdby): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the login ID of user that is stored in the session at the time  the note is created. |
| [creationDate](#creationdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Return the date and time that the note was created. |
| [subject](#subject): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the subject of the note. |
| [text](#text): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the text of the note. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md#getcreatedby)() | Return the login ID of user that is stored in the session at the time  the note is created. |
| [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md#getcreationdate)() | Return the date and time that the note was created. |
| [getSubject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md#getsubject)() | Return the subject of the note. |
| [getText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md#gettext)() | Return the text of the note. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### createdBy
- createdBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the login ID of user that is stored in the session at the time
      the note is created.



---

### creationDate
- creationDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Return the date and time that the note was created.  This is usually
      set by the system, but may be specified if the note is generated
      via an import.



---

### subject
- subject: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the subject of the note.


---

### text
- text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the text of the note.


---

## Method Details

### getCreatedBy()
- getCreatedBy(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the login ID of user that is stored in the session at the time
      the note is created.


    **Returns:**
    - the username.


---

### getCreationDate()
- getCreationDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Return the date and time that the note was created.  This is usually
      set by the system, but may be specified if the note is generated
      via an import.


    **Returns:**
    - the creation date.


---

### getSubject()
- getSubject(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the subject of the note.

    **Returns:**
    - the subject.


---

### getText()
- getText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the text of the note.

    **Returns:**
    - the text.


---

<!-- prettier-ignore-end -->

<!-- document id=3b4ef94366499179b107a9ddb8e6af2f84816a47cb2d06891226b4e1b42986f0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Number.md -->

<!-- prettier-ignore-start -->
# Class Number

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)

A Number object represents any numerical value, whether it is an integer
or floating-point number. Generally, you do not need to worry about a Number
object because a numerical value automatically becomes a Number object instance
when you use a numerical value or assign it to a variable.



## Constant Summary

| Constant | Description |
| --- | --- |
| [EPSILON](#epsilon): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | EPSILON is the Number value for the magnitude of the difference between 1 and the smallest  value greater than 1 that is representable as a Number value, which is approximately  2.2204460492503130808472633361816 × 10-16. |
| [MAX_SAFE_INTEGER](#max_safe_integer): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The maximum safe integer in JavaScript. |
| [MAX_VALUE](#max_value): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The largest representable Number. |
| [MIN_SAFE_INTEGER](#min_safe_integer): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The minimum safe integer in JavaScript. |
| [MIN_VALUE](#min_value): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The smallest representable Number. |
| [NEGATIVE_INFINITY](#negative_infinity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Negative infinite value; returned on overflow; |
| [NaN](#nan): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Not a Number. |
| [POSITIVE_INFINITY](#positive_infinity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Negative infinite value; returned on overflow; |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Number](#number)() | Constructs a Number with value 0 |
| [Number](#numbernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a new Number using the specified Number. |
| [Number](#numberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a Number using the specified value. |

## Method Summary

| Method | Description |
| --- | --- |
| static [isFinite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#isfiniteobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Determines whether the passed value is a finite number. |
| static [isInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#isintegerobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Determines whether the passed value is an integer number. |
| static [isNaN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#isnanobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Determines whether the passed value is `NaN`. |
| static [isSafeInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#issafeintegerobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Determines whether the passed value is a safe integer number. |
| static [parseFloat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#parsefloatstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parses a String into an float Number. |
| static [parseInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#parseintstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Parses a String into an integer Number. |
| static [parseInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#parseintstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Parses a String into an integer Number using the  specified radix. |
| [toExponential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#toexponential)() | Converts this Number to a String using exponential notation. |
| [toExponential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#toexponentialnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Converts this Number to a String using exponential notation with  the specified number of digits after the decimal place. |
| [toFixed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#tofixed)() | Converts a Number to a String that contains a no fractional part. |
| [toFixed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#tofixednumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Converts a Number to a String that contains a specified number  of digits after the decimal place. |
| [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#tolocalestring)() | Converts this Number to a String using local number formatting conventions. |
| [toPrecision](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#toprecisionnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Converts a Number to a String using the specified number  of significant digits. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#tostring)() | A String representation of this Number. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#tostringnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Converts the number into a string using the specified radix (base). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### EPSILON

- EPSILON: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : EPSILON is the Number value for the magnitude of the difference between 1 and the smallest
      value greater than 1 that is representable as a Number value, which is approximately
      2.2204460492503130808472633361816 × 10-16.


    **API Version:**
**note:** Available from version 22.7.

---

### MAX_SAFE_INTEGER

- MAX_SAFE_INTEGER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The maximum safe integer in JavaScript.

    **API Version:**
**note:** Available from version 21.2.

---

### MAX_VALUE

- MAX_VALUE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The largest representable Number.


---

### MIN_SAFE_INTEGER

- MIN_SAFE_INTEGER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The minimum safe integer in JavaScript.

    **API Version:**
**note:** Available from version 21.2.

---

### MIN_VALUE

- MIN_VALUE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The smallest representable Number.


---

### NEGATIVE_INFINITY

- NEGATIVE_INFINITY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Negative infinite value; returned on overflow;


---

### NaN

- NaN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Not a Number.


---

### POSITIVE_INFINITY

- POSITIVE_INFINITY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Negative infinite value; returned on overflow;


---

## Constructor Details

### Number()
- Number()
  - : Constructs a Number with value 0


---

### Number(Number)
- Number(num: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs a new Number using the specified Number.

    **Parameters:**
    - num - the Number to use.


---

### Number(String)
- Number(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a Number using the specified value.

    **Parameters:**
    - value - the value to use when creating the Number.


---

## Method Details

### isFinite(Object)
- static isFinite(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether the passed value is a finite number.

    **Parameters:**
    - value - The value to check.

    **Returns:**
    - `true` if the passed value is a finite number, else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### isInteger(Object)
- static isInteger(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether the passed value is an integer number.

    **Parameters:**
    - value - The value to check.

    **Returns:**
    - `true` if the passed value is a finite integer number, else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### isNaN(Object)
- static isNaN(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether the passed value is `NaN`. Unlike the global function, the passed parameter is not converted to number before doing the check.

    **Parameters:**
    - value - The value to check.

    **Returns:**
    - `true` if the passed value is the `NaN` number value, else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### isSafeInteger(Object)
- static isSafeInteger(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines whether the passed value is a safe integer number.

    **Parameters:**
    - value - The value to check.

    **Returns:**
    - `true` if the passed value is a safe integer number, else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### parseFloat(String)
- static parseFloat(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Parses a String into an float Number.

    **Parameters:**
    - s - the String to parse.

    **Returns:**
    - Returns the float as a Number.

    **API Version:**
**note:** Available from version 21.2.

---

### parseInt(String)
- static parseInt(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Parses a String into an integer Number.
      This function is a short form for the call to [parseInt(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#parseintstring-number) with automatic determination of the radix.
      If the string starts with "0x" or "0X" then the radix is 16. In all other cases the radix is 10.


    **Parameters:**
    - s - the String to parse.

    **Returns:**
    - Returns the integer as a Number.

    **API Version:**
**note:** Available from version 21.2.

---

### parseInt(String, Number)
- static parseInt(s: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), radix: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Parses a String into an integer Number using the
      specified radix.


    **Parameters:**
    - s - the String to parse.
    - radix - the radix to use.

    **Returns:**
    - Returns the integer as a Number.

    **API Version:**
**note:** Available from version 21.2.

---

### toExponential()
- toExponential(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts this Number to a String using exponential notation.

    **Returns:**
    - a String using exponential notation.


---

### toExponential(Number)
- toExponential(digits: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts this Number to a String using exponential notation with
      the specified number of digits after the decimal place.


    **Parameters:**
    - digits - the number of digits after the decimal place.

    **Returns:**
    - a String using exponential notation with
      the specified number of digits after the decimal place.



---

### toFixed()
- toFixed(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts a Number to a String that contains a no fractional part.

    **Returns:**
    - a String representation of the number


---

### toFixed(Number)
- toFixed(digits: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts a Number to a String that contains a specified number
      of digits after the decimal place.


    **Parameters:**
    - digits - the number of digits after the decimal place.

    **Returns:**
    - a String that contains a specified number
      of digits after the decimal place.



---

### toLocaleString()
- toLocaleString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts this Number to a String using local number formatting conventions. 
      
      The current implementation actually only returns the same as [toString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md#tostring).


    **Returns:**
    - a String using local number formatting conventions.


---

### toPrecision(Number)
- toPrecision(precision: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts a Number to a String using the specified number
      of significant digits. Uses exponential or fixed point
      notation depending on the size of the number and the number of
      significant digits specified.


    **Parameters:**
    - precision - the precision to use when converting the Number  to a String.

    **Returns:**
    - a String using the specified number
      of significant digits.



---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : A String representation of this Number.

    **Returns:**
    - a String representation of this Number.


---

### toString(Number)
- toString(radix: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts the number into a string using the specified radix (base).

    **Parameters:**
    - radix - the radix to use.

    **Returns:**
    - a String representation of this Number.


---

<!-- prettier-ignore-end -->

<!-- document id=88353ef277e8334541a04e1370bc54e2b418ba7adeca078c9915447619737435 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.oauth.OAuthAccessTokenResponse.md -->

<!-- prettier-ignore-start -->
# Class OAuthAccessTokenResponse

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.oauth.OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md)

Contains OAuth-related artifacts from the HTTP response from the third-party
OAuth server when requesting an access token



## Property Summary

| Property | Description |
| --- | --- |
| [IDToken](#idtoken): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID token, if available |
| [accessToken](#accesstoken): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the access token |
| [accessTokenExpiry](#accesstokenexpiry): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the access token expiration |
| [errorStatus](#errorstatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the error status. |
| [extraTokens](#extratokens): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns a map of additional tokens found in the response. |
| [oauthProviderId](#oauthproviderid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the OAuth provider id |
| [refreshToken](#refreshtoken): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the refresh token |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAccessToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md#getaccesstoken)() | Returns the access token |
| [getAccessTokenExpiry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md#getaccesstokenexpiry)() | Returns the access token expiration |
| [getErrorStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md#geterrorstatus)() | Returns the error status. |
| [getExtraTokens](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md#getextratokens)() | Returns a map of additional tokens found in the response. |
| [getIDToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md#getidtoken)() | Returns the ID token, if available |
| [getOauthProviderId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md#getoauthproviderid)() | Returns the OAuth provider id |
| [getRefreshToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md#getrefreshtoken)() | Returns the refresh token |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### IDToken
- IDToken: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID token, if available


---

### accessToken
- accessToken: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the access token


---

### accessTokenExpiry
- accessTokenExpiry: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the access token expiration


---

### errorStatus
- errorStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the error status.
      In cases of errors - more detailed error information
      can be seen in the error log files (specifity of error details vary by OAuth provider).



---

### extraTokens
- extraTokens: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns a map of additional tokens found in the response.


---

### oauthProviderId
- oauthProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the OAuth provider id


---

### refreshToken
- refreshToken: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the refresh token


---

## Method Details

### getAccessToken()
- getAccessToken(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the access token

    **Returns:**
    - the access token, if available, null otherwise


---

### getAccessTokenExpiry()
- getAccessTokenExpiry(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the access token expiration

    **Returns:**
    - the access token expiration


---

### getErrorStatus()
- getErrorStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the error status.
      In cases of errors - more detailed error information
      can be seen in the error log files (specifity of error details vary by OAuth provider).


    **Returns:**
    - the error status, if available, null otherwise


---

### getExtraTokens()
- getExtraTokens(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a map of additional tokens found in the response.

    **Returns:**
    - Additional tokens provided by the token end-point.  May be null or empty.


---

### getIDToken()
- getIDToken(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID token, if available

    **Returns:**
    - the ID token, if available, null otherwise


---

### getOauthProviderId()
- getOauthProviderId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the OAuth provider id

    **Returns:**
    - the OAuth provider id


---

### getRefreshToken()
- getRefreshToken(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the refresh token

    **Returns:**
    - the refresh token, if available, null otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=43352145f857a247d8357da879015d4e0a15cc588a2bfab3df53d0f2f0b33481 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.oauth.OAuthFinalizedResponse.md -->

<!-- prettier-ignore-start -->
# Class OAuthFinalizedResponse

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.oauth.OAuthFinalizedResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthFinalizedResponse.md)

Contains the combined responses from the third-party OAuth server when
finalizing the authentication.


Contains both the [OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md) 

and the [OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md)



## Property Summary

| Property | Description |
| --- | --- |
| [accessTokenResponse](#accesstokenresponse): [OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md) `(read-only)` | Returns the access token response |
| [userInfoResponse](#userinforesponse): [OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md) `(read-only)` | Returns the user info response |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthFinalizedResponse.md#getaccesstokenresponse)() | Returns the access token response |
| [getUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthFinalizedResponse.md#getuserinforesponse)() | Returns the user info response |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### accessTokenResponse
- accessTokenResponse: [OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md) `(read-only)`
  - : Returns the access token response


---

### userInfoResponse
- userInfoResponse: [OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md) `(read-only)`
  - : Returns the user info response


---

## Method Details

### getAccessTokenResponse()
- getAccessTokenResponse(): [OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md)
  - : Returns the access token response

    **Returns:**
    - the access token response


---

### getUserInfoResponse()
- getUserInfoResponse(): [OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md)
  - : Returns the user info response

    **Returns:**
    - the user info response


---

<!-- prettier-ignore-end -->

<!-- document id=acc7265b827d56c938db74480e73be4bde8ea67228a483a73bbe9169c2df06fa url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.oauth.OAuthLoginFlowMgr.md -->

<!-- prettier-ignore-start -->
# Class OAuthLoginFlowMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.oauth.OAuthLoginFlowMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md)

The OAuthLoginFlowMgr encapsulates interactions with third party
OAuth providers to support the Authorization Code Flow.

The way to use is:

- call [initiateOAuthLogin(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#initiateoauthloginstring)
- redirect the user to the returned link
- when the user authenticates there the server will call back to  a URL configured on the provider's web site
- when processing the request made from the provider's web site  you have two choices - either call the [obtainAccessToken()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainaccesstoken)and [obtainUserInfo(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainuserinfostring-string)methods one after another separately (gives you more flexibility),  or call the [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin)method which internally  calls the other two (simpler to use).

Sample code for using it:

```
var finalizedResponse : OAuthFinalizedResponse = OAuthLoginFlowMgr.finalizeOAuthLogin();
var userInfo = finalizedResponse.userInfoResponse.userInfo;
```

or:

```
var accessTokenResponse : OAuthAccessTokenResponse = OAuthLoginFlowMgr.obtainAccessToken();
var userInfoResponse : OAuthUserInfoResponse = OAuthLoginFlowMgr.obtainUserInfo(
    accessTokenResponse.oauthProviderId, accessTokenResponse.accessToken);
var userInfo = userInfoResponse.userInfo;
```



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [OAuthLoginFlowMgr](#oauthloginflowmgr)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| static [finalizeOAuthLogin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin)() | This method works in tandem with the [initiateOAuthLogin(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#initiateoauthloginstring) method. |
| static [initiateOAuthLogin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#initiateoauthloginstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method works in tandem with another method - [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin). |
| static [obtainAccessToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainaccesstoken)() | This method is called internally by [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin). |
| static [obtainUserInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainuserinfostring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method is called internally by [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### OAuthLoginFlowMgr()
- OAuthLoginFlowMgr()
  - : 


---

## Method Details

### finalizeOAuthLogin()
- static finalizeOAuthLogin(): [OAuthFinalizedResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthFinalizedResponse.md)
  - : This method works in tandem with the [initiateOAuthLogin(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#initiateoauthloginstring) method.
      After the user has been redirected to the URL returned by that method
      to the external OAuth2 provider and the user has interacted with the provider's
      site, the browser is redirected to a URL configured on the provider's web
      site. This URL should be that of a pipeline that contains
      a script invoking the finalizeOAuthLogin method.
      
      
      At this point the user has either been authenticated by the external provider
      or not (forgot password, or simply refused to provide credentials). If the user
      has been authenticated by the external provider and the provider returns an
      authentication code, this method exchanges the code for a token and with that
      token it requests from the provider the user information specified by the
      configured scope (id, first/last name, email, etc.).
      
      
      
      The method is aggregation of two other methods - [obtainAccessToken()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainaccesstoken)
      and [obtainUserInfo(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainuserinfostring-string)
      and is provided for convenience. You may want to
      use the two individual methods instead if you need more flexibility.
      
      
      
      This supports the Authorization Code Flow.


    **Returns:**
    - the user info on success, null otherwise


---

### initiateOAuthLogin(String)
- static initiateOAuthLogin(oauthProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)
  - : This method works in tandem with another method - [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin).
      It starts the process of authentication via an external OAuth2 provider. It
      takes one parameter - OAuthProviderId (as configured in the system). Outputs
      an URL pointing to the OAuth2 provider's web page to which the browser should
      redirect to initiate the actual user authentication or NULL if there is an
      invalid configuration or an error occurs.
      The method stores a few key/values in the session
      ([Session.getPrivacy()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getprivacy), implementation specific parameters and may change at any time)
      to be picked up by the [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin) method  when the provider redirects back.
      
      
      
      This supports the Authorization Code Flow.


    **Parameters:**
    - oauthProviderId - the OAuth provider id

    **Returns:**
    - URL to redirect to


---

### obtainAccessToken()
- static obtainAccessToken(): [OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md)
  - : This method is called internally by [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin).
      There are customer requests to expose a more granular way of
      doing the interactions that finalizeOAuthLogin is currently doing
      with the third party OAuth server to accommodate certain providers.
      
      
      
      This supports the Authorization Code Flow.


    **Returns:**
    - the access token response


---

### obtainUserInfo(String, String)
- static obtainUserInfo(oauthProviderId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), accessToken: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md)
  - : This method is called internally by [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin).
      There are customer requests to expose a more granular way of
      doing the interactions that finalizeOAuthLogin is currently doing
      with the third party OAuth server to accommodate certain providers.
      
      
      
      This supports the Authorization Code Flow.


    **Parameters:**
    - oauthProviderId - the OAuth provider id
    - accessToken - the OAuth provider's access token

    **Returns:**
    - the user info response


---

<!-- prettier-ignore-end -->

<!-- document id=33d9ad1fc03fed44aadf7e4cf59713d3ebaa75da8dac7261cd9b84aaa93afb07 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.oauth.OAuthUserInfoResponse.md -->

<!-- prettier-ignore-start -->
# Class OAuthUserInfoResponse

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.oauth.OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md)

Contains the response from the third-party OAuth server when
requesting user info. Refer to the corresponding OAuth provider documentation
regarding what the format might be (in most cases it would be JSON).
The data returned would also vary depending on the scope.



## Property Summary

| Property | Description |
| --- | --- |
| [errorStatus](#errorstatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the error status  In cases of errors - more detailed error information  can be seen in the error log files (specificity of error details vary by OAuth provider). |
| [userInfo](#userinfo): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the user info as a String. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getErrorStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md#geterrorstatus)() | Returns the error status  In cases of errors - more detailed error information  can be seen in the error log files (specificity of error details vary by OAuth provider). |
| [getUserInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md#getuserinfo)() | Returns the user info as a String. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### errorStatus
- errorStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the error status
      In cases of errors - more detailed error information
      can be seen in the error log files (specificity of error details vary by OAuth provider).



---

### userInfo
- userInfo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the user info as a String. Refer to the corresponding OAuth provider documentation
      regarding what the format might be (in most cases it would be JSON).
      The data returned would also vary depending on the configured 'scope'.



---

## Method Details

### getErrorStatus()
- getErrorStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the error status
      In cases of errors - more detailed error information
      can be seen in the error log files (specificity of error details vary by OAuth provider).


    **Returns:**
    - the error status


---

### getUserInfo()
- getUserInfo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the user info as a String. Refer to the corresponding OAuth provider documentation
      regarding what the format might be (in most cases it would be JSON).
      The data returned would also vary depending on the configured 'scope'.


    **Returns:**
    - the user info


---

<!-- prettier-ignore-end -->

<!-- document id=9e1398e9c01121657270164359d28aa719d2a735fd2a705cae84e317a3335d15 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Object.md -->

<!-- prettier-ignore-start -->
# Class Object

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)

The _Object_ object is the foundation of all native JavaScript objects. Also,
the _Object_ object can be used to generate items in your scripts with behaviors
that are defined by custom properties and/or methods. You generally start by creating
a blank object with the constructor function and then assign values to new properties
of that object.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Object](#object)() | Object constructor. |

## Method Summary

| Method | Description |
| --- | --- |
| static [assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Copies the values of all of the enumerable own properties from one or more source objects to a target object. |
| static [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a new object based on a prototype object. |
| static [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a new object based on a prototype object and additional property definitions. |
| static [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Defines or modifies properties of the passed object. |
| static [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Defines or modifies a single property of the passed object. |
| static [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the enumerable property names and their values of the passed object. |
| static [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Freezes the passed object. |
| static [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable)([Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)) | Creates a new object with defined properties. |
| static [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the descriptor for a single property of the passed object. |
| static [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns an arrays containing the names of all enumerable and non-enumerable properties owned by the passed object. |
| static [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns an array containing the symbol of all symbol properties owned by the passed object. |
| static [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the prototype of the passed object. |
| [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns Boolean true if at the time the current object's instance was created  its constructor (or literal assignment) contained a property with a name that  matches the parameter value. |
| static [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Checks if the two values are equal in terms of being the same value. |
| static [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if new properties can be added to an object. |
| static [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if the object is frozen. |
| [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if the current object and the object passed as a prameter conincide  at some point along each object's prototype inheritance chain. |
| static [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if the object is sealed. |
| static [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the enumerable property names of the passed object. |
| static [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Makes the passed object non-extensible. |
| [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Return true if the specified property exposes itself to for/in property  inspection through the object. |
| static [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Seals the passed object. |
| static [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Changes the prototype of the passed object. |
| [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring)() | Converts the object to a localized String. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring)() | Converts the object to a String. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof)() | Returns the object's value. |
| static [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the enumerable property values of the passed object. |

## Constructor Details

### Object()
- Object()
  - : Object constructor.


---

## Method Details

### assign(Object, Object...)
- static assign(target: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), sources: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Copies the values of all of the enumerable own properties from one or more source objects to a target object.

    **Parameters:**
    - target - The target object.
    - sources - The source objects.

    **Returns:**
    - The target object.

    **API Version:**
**note:** Available from version 21.2.

---

### create(Object)
- static create(prototype: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Creates a new object based on a prototype object.

    **Parameters:**
    - prototype - The prototype for the new object.

    **Returns:**
    - The newly created object.


---

### create(Object, Object)
- static create(prototype: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), properties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Creates a new object based on a prototype object and additional property definitions.
      The properties are given in the same format as described for [defineProperties(Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object).


    **Parameters:**
    - prototype - The prototype for the new object.
    - properties - The property definitions.

    **Returns:**
    - The newly created object.


---

### defineProperties(Object, Object)
- static defineProperties(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), properties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Defines or modifies properties of the passed object.
      A descriptor for a property supports these properties: configurable, enumerable, value, writable, set and get.


    **Parameters:**
    - object - The object to change.
    - properties - The new property definitions.

    **Returns:**
    - The modified object.


---

### defineProperty(Object, Object, Object)
- static defineProperty(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), propertyKey: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), descriptor: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Defines or modifies a single property of the passed object.
      A descriptor for a property supports these properties: configurable, enumerable, value, writable, set and get.


    **Parameters:**
    - object - The object to change.
    - propertyKey - The property name.
    - descriptor - The property descriptor object.

    **Returns:**
    - The modified object.


---

### entries(Object)
- static entries(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns the enumerable property names and their values of the passed object.

    **Parameters:**
    - object - The object to get the enumerable property names from.

    **Returns:**
    - An array of key/value pairs ( as two element arrays ) that holds all the enumerable properties of the given object.

    **API Version:**
**note:** Available from version 22.7.

---

### freeze(Object)
- static freeze(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Freezes the passed object. Properties can't be added or removed from the frozen object. Also, definitions of
      existing object properties can't be changed. Although property values are immutable, setters and getters can be
      called.


    **Parameters:**
    - object - The object to be frozen.

    **Returns:**
    - The frozen object.


---

### fromEntries(Iterable)
- static fromEntries(properties: [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Creates a new object with defined properties. The properties are defined by an iterable that produces two element array like objects, which are the key-value pairs.
      Iterables are e.g. [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md), [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md) or any other [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md).


    **Parameters:**
    - properties - The properties.

    **Returns:**
    - The newly created object.

    **API Version:**
**note:** Available from version 22.7.

---

### getOwnPropertyDescriptor(Object, Object)
- static getOwnPropertyDescriptor(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), propertyKey: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the descriptor for a single property of the passed object.

    **Parameters:**
    - object - The property owning object.
    - propertyKey - The property to look for.

    **Returns:**
    - The descriptor object for the property or `undefined` if the property does not exist.


---

### getOwnPropertyNames(Object)
- static getOwnPropertyNames(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns an arrays containing the names of all enumerable and non-enumerable properties owned by the passed object.

    **Parameters:**
    - object - The object owning properties.

    **Returns:**
    - An array of strings that are the properties found directly in the passed object.


---

### getOwnPropertySymbols(Object)
- static getOwnPropertySymbols(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns an array containing the symbol of all symbol properties owned by the passed object.

    **Parameters:**
    - object - The object owning properties.

    **Returns:**
    - An array of symbol properties found directly in the passed object.

    **API Version:**
**note:** Available from version 21.2.

---

### getPrototypeOf(Object)
- static getPrototypeOf(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the prototype of the passed object.

    **Parameters:**
    - object - The object to get the prototype from.

    **Returns:**
    - The prototype object or `null` if there is none.


---

### hasOwnProperty(String)
- hasOwnProperty(propName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns Boolean true if at the time the current object's instance was created
      its constructor (or literal assignment) contained a property with a name that
      matches the parameter value.


    **Parameters:**
    - propName - the property name of the object's property.

    **Returns:**
    - true if at the object contains a property that matches the parameter,
      false otherwise.



---

### is(Object, Object)
- static is(value1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), value2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks if the two values are equal in terms of being the same value. No coercion is performed, thus -0 and
      +0 is not equal and NaN is equal to NaN.


    **Parameters:**
    - value1 - The first value.
    - value2 - The second value.

    **Returns:**
    - `true` if both values are the same value else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### isExtensible(Object)
- static isExtensible(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if new properties can be added to an object. By default new objects are extensible. The methods
      [freeze(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [seal(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject) and [preventExtensions(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject) make objects
      non-extensible.


    **Parameters:**
    - object - The object to check.

    **Returns:**
    - `true` if new properties can be added else `false`.


---

### isFrozen(Object)
- static isFrozen(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the object is frozen.

    **Parameters:**
    - object - The object to check.

    **Returns:**
    - `true` if the object is frozen else `false`.


---

### isPrototypeOf(Object)
- isPrototypeOf(prototype: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the current object and the object passed as a prameter conincide
      at some point along each object's prototype inheritance chain.


    **Parameters:**
    - prototype - the object to test.

    **Returns:**
    - true if the current object and the object passed as a prameter conincide
      at some point, false otherwise.



---

### isSealed(Object)
- static isSealed(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the object is sealed.

    **Parameters:**
    - object - The object to check.

    **Returns:**
    - `true` if the object is sealed else `false`.


---

### keys(Object)
- static keys(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns the enumerable property names of the passed object.

    **Parameters:**
    - object - The object to get the enumerable property names from.

    **Returns:**
    - An array of strings that holds all the enumerable properties of the given object.


---

### preventExtensions(Object)
- static preventExtensions(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Makes the passed object non-extensible. This means that no new properties can be added to this object.

    **Parameters:**
    - object - The object to make non-extensible.

    **Returns:**
    - The passed object.


---

### propertyIsEnumerable(String)
- propertyIsEnumerable(propName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Return true if the specified property exposes itself to for/in property
      inspection through the object.


    **Parameters:**
    - propName - the property to test.

    **Returns:**
    - true if the specified property exposes itself to for/in property
      inspection through the object, false otherwise.



---

### seal(Object)
- static seal(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Seals the passed object. This means properties can't be added or removed. Also, property definitions of
      existing properties can't be changed.


    **Parameters:**
    - object - The object to be frozen.

    **Returns:**
    - The sealed object.


---

### setPrototypeOf(Object, Object)
- static setPrototypeOf(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), prototype: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Changes the prototype of the passed object.

    **Parameters:**
    - object - The object whose prototype should change.
    - prototype - The object to set as the new prototype.

    **Returns:**
    - The object with the changed prototype.

    **API Version:**
**note:** Available from version 21.2.

---

### toLocaleString()
- toLocaleString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts the object to a localized String.

    **Returns:**
    - a localized version of the object.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts the object to a String.

    **Returns:**
    - the String representation of the object.


---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the object's value.

    **Returns:**
    - the object's value.


---

### values(Object)
- static values(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns the enumerable property values of the passed object.

    **Parameters:**
    - object - The object to get the enumerable property values from.

    **Returns:**
    - An array of values that holds all the enumerable properties of the given object.

    **API Version:**
**note:** Available from version 22.7.

---

<!-- prettier-ignore-end -->

<!-- document id=796e1874d33a3e7731330b418cd975189446e4ec5fb884d01b7975f3b17637ce url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.ObjectAttributeDefinition.md -->

<!-- prettier-ignore-start -->
# Class ObjectAttributeDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)

Represents the definition of an object's attribute.


## Constant Summary

| Constant | Description |
| --- | --- |
| [VALUE_TYPE_BOOLEAN](#value_type_boolean): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | Boolean value type. |
| [VALUE_TYPE_DATE](#value_type_date): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | Date value type. |
| [VALUE_TYPE_DATETIME](#value_type_datetime): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11 | Date and Time value type. |
| [VALUE_TYPE_EMAIL](#value_type_email): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12 | Email value type. |
| [VALUE_TYPE_ENUM_OF_INT](#value_type_enum_of_int): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 31 | Enum of int value type. |
| [VALUE_TYPE_ENUM_OF_STRING](#value_type_enum_of_string): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 33 | Enum of String value type. |
| [VALUE_TYPE_HTML](#value_type_html): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | HTML value type. |
| [VALUE_TYPE_IMAGE](#value_type_image): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | Image value type. |
| [VALUE_TYPE_INT](#value_type_int): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | int value type. |
| [VALUE_TYPE_MONEY](#value_type_money): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9 | Money value type. |
| [VALUE_TYPE_NUMBER](#value_type_number): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Number value type. |
| [VALUE_TYPE_PASSWORD](#value_type_password): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13 | Password value type. |
| [VALUE_TYPE_QUANTITY](#value_type_quantity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | Quantity value type. |
| [VALUE_TYPE_SET_OF_INT](#value_type_set_of_int): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 21 | Set of int value type. |
| [VALUE_TYPE_SET_OF_NUMBER](#value_type_set_of_number): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 22 | Set of Number value type. |
| [VALUE_TYPE_SET_OF_STRING](#value_type_set_of_string): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 23 | Set of String value type. |
| [VALUE_TYPE_STRING](#value_type_string): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | String value type. |
| [VALUE_TYPE_TEXT](#value_type_text): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Text value type. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the attribute definition. |
| [attributeGroups](#attributegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all attribute groups the attribute is assigned to. |
| [defaultValue](#defaultvalue): [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md) `(read-only)` | Return the default value for the attribute or null if none is defined. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name for the attribute, which can be used in the  user interface. |
| [key](#key): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the attribute represents the primary key of the object. |
| [mandatory](#mandatory): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Checks if this attribute is mandatory. |
| [multiValueType](#multivaluetype): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | <p>Returns `true` if the attribute can have multiple values. |
| [objectTypeDefinition](#objecttypedefinition): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md) `(read-only)` | Returns the object type definition in which this attribute is defined. |
| ~~[setValueType](#setvaluetype): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Returns `true` if the attribute is of type 'Set of'. |
| [system](#system): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates if the attribute is a pre-defined system attribute  or a custom attribute. |
| [unit](#unit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the attribute's unit representation such as  inches for length or pounds for weight. |
| [valueTypeCode](#valuetypecode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns a code for the data type stored in the attribute. |
| [values](#values): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the list of attribute values. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAttributeGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getattributegroups)() | Returns all attribute groups the attribute is assigned to. |
| [getDefaultValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getdefaultvalue)() | Return the default value for the attribute or null if none is defined. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getdisplayname)() | Returns the display name for the attribute, which can be used in the  user interface. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getid)() | Returns the ID of the attribute definition. |
| [getObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getobjecttypedefinition)() | Returns the object type definition in which this attribute is defined. |
| [getUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getunit)() | Returns the attribute's unit representation such as  inches for length or pounds for weight. |
| [getValueTypeCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getvaluetypecode)() | Returns a code for the data type stored in the attribute. |
| [getValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getvalues)() | Returns the list of attribute values. |
| [isKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#iskey)() | Identifies if the attribute represents the primary key of the object. |
| [isMandatory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#ismandatory)() | Checks if this attribute is mandatory. |
| [isMultiValueType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#ismultivaluetype)() | <p>Returns `true` if the attribute can have multiple values. |
| ~~[isSetValueType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#issetvaluetype)()~~ | Returns `true` if the attribute is of type 'Set of'. |
| [isSystem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#issystem)() | Indicates if the attribute is a pre-defined system attribute  or a custom attribute. |
| [requiresEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#requiresencoding)() | Returns a boolean flag indicating whether or not values of this attribute  definition should be encoded using the encoding="off" flag in ISML  templates. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### VALUE_TYPE_BOOLEAN

- VALUE_TYPE_BOOLEAN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : Boolean value type.


---

### VALUE_TYPE_DATE

- VALUE_TYPE_DATE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : Date value type.


---

### VALUE_TYPE_DATETIME

- VALUE_TYPE_DATETIME: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11
  - : Date and Time value type.


---

### VALUE_TYPE_EMAIL

- VALUE_TYPE_EMAIL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12
  - : Email value type.


---

### VALUE_TYPE_ENUM_OF_INT

- VALUE_TYPE_ENUM_OF_INT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 31
  - : Enum of int value type.


---

### VALUE_TYPE_ENUM_OF_STRING

- VALUE_TYPE_ENUM_OF_STRING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 33
  - : Enum of String value type.


---

### VALUE_TYPE_HTML

- VALUE_TYPE_HTML: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : HTML value type.


---

### VALUE_TYPE_IMAGE

- VALUE_TYPE_IMAGE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : Image value type.


---

### VALUE_TYPE_INT

- VALUE_TYPE_INT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : int value type.


---

### VALUE_TYPE_MONEY

- VALUE_TYPE_MONEY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9
  - : Money value type.


---

### VALUE_TYPE_NUMBER

- VALUE_TYPE_NUMBER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Number value type.


---

### VALUE_TYPE_PASSWORD

- VALUE_TYPE_PASSWORD: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13
  - : Password value type.


---

### VALUE_TYPE_QUANTITY

- VALUE_TYPE_QUANTITY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : Quantity value type.


---

### VALUE_TYPE_SET_OF_INT

- VALUE_TYPE_SET_OF_INT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 21
  - : Set of int value type.


---

### VALUE_TYPE_SET_OF_NUMBER

- VALUE_TYPE_SET_OF_NUMBER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 22
  - : Set of Number value type.


---

### VALUE_TYPE_SET_OF_STRING

- VALUE_TYPE_SET_OF_STRING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 23
  - : Set of String value type.


---

### VALUE_TYPE_STRING

- VALUE_TYPE_STRING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : String value type.


---

### VALUE_TYPE_TEXT

- VALUE_TYPE_TEXT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Text value type.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the attribute definition.


---

### attributeGroups
- attributeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all attribute groups the attribute is assigned to.


---

### defaultValue
- defaultValue: [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md) `(read-only)`
  - : Return the default value for the attribute or null if none is defined.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name for the attribute, which can be used in the
      user interface.



---

### key
- key: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the attribute represents the primary key of the object.


---

### mandatory
- mandatory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Checks if this attribute is mandatory.


---

### multiValueType
- multiValueType: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : 
      Returns `true` if the attribute can have multiple values.
      
      
      Attributes of the following types are multi-value capable:
      
      
      - [VALUE_TYPE_SET_OF_INT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_set_of_int)
      - [VALUE_TYPE_SET_OF_NUMBER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_set_of_number)
      - [VALUE_TYPE_SET_OF_STRING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_set_of_string)
      
      
      Additionally, attributes of the following types can be multi-value
      enabled:
      
      
      - [VALUE_TYPE_ENUM_OF_INT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_enum_of_int)
      - [VALUE_TYPE_ENUM_OF_STRING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_enum_of_string)



---

### objectTypeDefinition
- objectTypeDefinition: [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md) `(read-only)`
  - : Returns the object type definition in which this attribute is defined.


---

### setValueType
- ~~setValueType: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Returns `true` if the attribute is of type 'Set of'.

    **Deprecated:**
**warning:** Use [isMultiValueType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#ismultivaluetype) instead.

---

### system
- system: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates if the attribute is a pre-defined system attribute
      or a custom attribute.



---

### unit
- unit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the attribute's unit representation such as
      inches for length or pounds for weight. The value returned by
      this method is based on the attribute itself.



---

### valueTypeCode
- valueTypeCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns a code for the data type stored in the attribute. See constants
      defined in this class.



---

### values
- values: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the list of attribute values. In the user interface only the
      values specified in this list should be offered as valid input values.
      
      The collection contains instances of ObjectAttributeValueDefinition.



---

## Method Details

### getAttributeGroups()
- getAttributeGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all attribute groups the attribute is assigned to.

    **Returns:**
    - all attribute groups the attribute is assigned to.


---

### getDefaultValue()
- getDefaultValue(): [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md)
  - : Return the default value for the attribute or null if none is defined.

    **Returns:**
    - the default value for the attribute or null if none is defined.


---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name for the attribute, which can be used in the
      user interface.


    **Returns:**
    - the display name for the attribute, which can be used in the
      user interface.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the attribute definition.

    **Returns:**
    - the ID of the attribute definition.


---

### getObjectTypeDefinition()
- getObjectTypeDefinition(): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the object type definition in which this attribute is defined.

    **Returns:**
    - the object type definition in which this attribute is defined.


---

### getUnit()
- getUnit(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the attribute's unit representation such as
      inches for length or pounds for weight. The value returned by
      this method is based on the attribute itself.


    **Returns:**
    - the attribute's unit representation such as
      inches for length or pounds for weight.



---

### getValueTypeCode()
- getValueTypeCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns a code for the data type stored in the attribute. See constants
      defined in this class.


    **Returns:**
    - a code for the data type stored in the attribute. See constants
      defined in this class.



---

### getValues()
- getValues(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the list of attribute values. In the user interface only the
      values specified in this list should be offered as valid input values.
      
      The collection contains instances of ObjectAttributeValueDefinition.


    **Returns:**
    - a collection of ObjectAttributeValueDefinition instances representing
      the list of attribute values, or null if no values are specified.



---

### isKey()
- isKey(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the attribute represents the primary key of the object.

    **Returns:**
    - true if the attribute represents the primary key, false otherwise.


---

### isMandatory()
- isMandatory(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks if this attribute is mandatory.

    **Returns:**
    - true, if this attribute is mandatory


---

### isMultiValueType()
- isMultiValueType(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : 
      Returns `true` if the attribute can have multiple values.
      
      
      Attributes of the following types are multi-value capable:
      
      
      - [VALUE_TYPE_SET_OF_INT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_set_of_int)
      - [VALUE_TYPE_SET_OF_NUMBER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_set_of_number)
      - [VALUE_TYPE_SET_OF_STRING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_set_of_string)
      
      
      Additionally, attributes of the following types can be multi-value
      enabled:
      
      
      - [VALUE_TYPE_ENUM_OF_INT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_enum_of_int)
      - [VALUE_TYPE_ENUM_OF_STRING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#value_type_enum_of_string)


    **Returns:**
    - `true` if attributes can have multiple values,
      otherwise `false`



---

### isSetValueType()
- ~~isSetValueType(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Returns `true` if the attribute is of type 'Set of'.

    **Deprecated:**
**warning:** Use [isMultiValueType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#ismultivaluetype) instead.

---

### isSystem()
- isSystem(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if the attribute is a pre-defined system attribute
      or a custom attribute.


    **Returns:**
    - true if the the attribute is a pre-defined system attribute,
      false if it is a custom attribute.



---

### requiresEncoding()
- requiresEncoding(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a boolean flag indicating whether or not values of this attribute
      definition should be encoded using the encoding="off" flag in ISML
      templates.


    **Returns:**
    - a boolean flag indicating whether or not values of this attribute
      definition should be encoded using the encoding="off" flag in ISML
      templates.



---

<!-- prettier-ignore-end -->

<!-- document id=51ddf9e546f417f79122c8f28fb0123ec31599d2d2f6484f2b97fbe0f62f88cf url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.ObjectAttributeGroup.md -->

<!-- prettier-ignore-start -->
# Class ObjectAttributeGroup

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)

Represents a group of object attributes.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of this group. |
| [attributeDefinitions](#attributedefinitions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all attribute definitions for this group. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of this group in the current locale. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of this group. |
| [objectTypeDefinition](#objecttypedefinition): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md) `(read-only)` | Returns the object type definition to which this attribute group  belongs. |
| [system](#system): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is an sytem or a custom attribute group. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAttributeDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md#getattributedefinitions)() | Returns all attribute definitions for this group. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md#getdescription)() | Returns the description of this group in the current locale. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md#getdisplayname)() | Returns the display name of this group. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md#getid)() | Returns the ID of this group. |
| [getObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md#getobjecttypedefinition)() | Returns the object type definition to which this attribute group  belongs. |
| [isSystem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md#issystem)() | Identifies if this is an sytem or a custom attribute group. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of this group.


---

### attributeDefinitions
- attributeDefinitions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all attribute definitions for this group. The collection
      may contain both system attribute definition as well as custom
      attribute definitions.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of this group in the current locale.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of this group.


---

### objectTypeDefinition
- objectTypeDefinition: [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md) `(read-only)`
  - : Returns the object type definition to which this attribute group
      belongs.



---

### system
- system: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is an sytem or a custom attribute group. A system
      attribute group is pre-defined and can not be deleted.



---

## Method Details

### getAttributeDefinitions()
- getAttributeDefinitions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all attribute definitions for this group. The collection
      may contain both system attribute definition as well as custom
      attribute definitions.


    **Returns:**
    - all attribute definitions for this group.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of this group in the current locale.

    **Returns:**
    - the display name of this group.


---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of this group.

    **Returns:**
    - the display name of this group.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of this group.

    **Returns:**
    - the ID of this group.


---

### getObjectTypeDefinition()
- getObjectTypeDefinition(): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the object type definition to which this attribute group
      belongs.


    **Returns:**
    - the object type definition to which this attribute group
      belongs.



---

### isSystem()
- isSystem(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is an sytem or a custom attribute group. A system
      attribute group is pre-defined and can not be deleted.


    **Returns:**
    - true if this is a system attribute group, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=80dbaf1b53c1422430e5322cacbebd6a3b31bb8561adff1ab8a7c84d7142929f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.ObjectAttributeValueDefinition.md -->

<!-- prettier-ignore-start -->
# Class ObjectAttributeValueDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md)

Represents the value definition associated with an
object attribute.



## Property Summary

| Property | Description |
| --- | --- |
| [displayValue](#displayvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns a display name that can be used to present this value in  the user interface. |
| [value](#value): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the actual value for the attribute. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md#getdisplayvalue)() | Returns a display name that can be used to present this value in  the user interface. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md#getvalue)() | Returns the actual value for the attribute. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### displayValue
- displayValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns a display name that can be used to present this value in
      the user interface. For example, the value might be '1' but the display
      name might be 'Order Exported'.



---

### value
- value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the actual value for the attribute.


---

## Method Details

### getDisplayValue()
- getDisplayValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a display name that can be used to present this value in
      the user interface. For example, the value might be '1' but the display
      name might be 'Order Exported'.


    **Returns:**
    - a display name that can be used to present this value in
      the user interface.



---

### getValue()
- getValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the actual value for the attribute.

    **Returns:**
    - the actual value for the attribute.


---

<!-- prettier-ignore-end -->

<!-- document id=3b69ba63fdb47bf24bbf8d13c62efa3753a71ce5b736f2ef3591ffa176b7eac3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.ObjectTypeDefinition.md -->

<!-- prettier-ignore-start -->
# Class ObjectTypeDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)

The class provides access to the meta data of a system object or custom
object.  A short example should suffice to demonstrate how this metadata can
be used in a script:


```
var co : CustomObject = CustomObjectMgr.getCustomObject("sample", "MyCustomObject");

// get the object type definition
var typeDef : ObjectTypeDefinition = co.describe();
// get the custom object attribute definition for name "enumIntValue"
var attrDef : ObjectAttributeDefinition = typeDef.getCustomAttributeDefinition( "enumIntValue" );
// get the collection of object attribute value definitions
var valueDefs : Collection = attrDef.getValues();

// return function if there are no object attribute value definitions
if(valueDefs.isEmpty())
{
    return;
}

var displayValue : String;
// loop over object attribute value definitions collection
for each ( var valueDef : ObjectAttributeValueDefinition in valueDefs )
{
    if( valueDef.getValue() == co.custom.intValue )
    {
        displayValue = valueDef.getDisplayValue();
        break;
    }
}
```



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type id of the business objects. |
| [attributeDefinitions](#attributedefinitions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all declared attributes for the object. |
| [attributeGroups](#attributegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all declared attribute groups. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of the definition, which can be used in the  user interface. |
| [system](#system): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this object definition is for a system type or a custom  type. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAttributeDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#getattributedefinitions)() | Returns a collection of all declared attributes for the object. |
| [getAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#getattributegroupstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the attribute group with the given name within this object  type definition. |
| [getAttributeGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#getattributegroups)() | Returns a collection of all declared attribute groups. |
| [getCustomAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#getcustomattributedefinitionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the custom attribute definition with the given name. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#getdisplayname)() | Returns the display name of the definition, which can be used in the  user interface. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#getid)() | Returns the type id of the business objects. |
| [getSystemAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#getsystemattributedefinitionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the system attribute definition with the given name. |
| [isSystem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md#issystem)() | Identifies if this object definition is for a system type or a custom  type. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type id of the business objects.


---

### attributeDefinitions
- attributeDefinitions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all declared attributes for the object.
      The collection contains both system and custom attributes. There might
      be system and custom attribute with identical names. So the name of the
      attribute is not a uniqueness criteria. Additional the isCustom() flag
      must be checked.



---

### attributeGroups
- attributeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all declared attribute groups. A attribute group
      is a collection of attribute, which are typically displayed together as
      a visual group.



---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of the definition, which can be used in the
      user interface.



---

### system
- system: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this object definition is for a system type or a custom
      type.



---

## Method Details

### getAttributeDefinitions()
- getAttributeDefinitions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all declared attributes for the object.
      The collection contains both system and custom attributes. There might
      be system and custom attribute with identical names. So the name of the
      attribute is not a uniqueness criteria. Additional the isCustom() flag
      must be checked.


    **Returns:**
    - a collection of all declared attributes for the object.


---

### getAttributeGroup(String)
- getAttributeGroup(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)
  - : Returns the attribute group with the given name within this object
      type definition.


    **Parameters:**
    - name - The name of the attribute scope to return.

    **Returns:**
    - The matching attribute scope or `null` if no such
      scope exists.



---

### getAttributeGroups()
- getAttributeGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all declared attribute groups. A attribute group
      is a collection of attribute, which are typically displayed together as
      a visual group.


    **Returns:**
    - a collection of all declared attribute groups.


---

### getCustomAttributeDefinition(String)
- getCustomAttributeDefinition(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)
  - : Returns the custom attribute definition with the given name. The method
      returns null if no custom attribute is defined with that name.


    **Parameters:**
    - name - The unique name of the custom attribute definition within the  object type.

    **Returns:**
    - The matching attribute definition or `null` in
      case no such definition exists.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of the definition, which can be used in the
      user interface.


    **Returns:**
    - the display name of the definition, which can be used in the
      user interface.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type id of the business objects.

    **Returns:**
    - the type id of the business objects.


---

### getSystemAttributeDefinition(String)
- getSystemAttributeDefinition(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)
  - : Returns the system attribute definition with the given name. The method
      returns null if no system attribute is defined with that name. Only
      system objects have system attributes. A CustomObject has no system attributes
      and so the method will always return null for a CustomObject.


    **Parameters:**
    - name - The unique name of the custom attribute definition within the  object type.

    **Returns:**
    - The matching attribute definition or `null` in
      case no such definition exists.



---

### isSystem()
- isSystem(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this object definition is for a system type or a custom
      type.


    **Returns:**
    - true if this object definition is for a system type, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=4e41b94c1b28e46a84d4039b8cba8459f10783463ec4256fbee2506a8c1db0b4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.Order.md -->

<!-- prettier-ignore-start -->
# Class Order

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)
        - [dw.order.Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)

The Order class represents an order. The correct way to retrieve an order is described in [OrderMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md).


## Constant Summary

| Constant | Description |
| --- | --- |
| [CONFIRMATION_STATUS_CONFIRMED](#confirmation_status_confirmed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | constant for when Confirmation Status is Confirmed |
| [CONFIRMATION_STATUS_NOTCONFIRMED](#confirmation_status_notconfirmed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | constant for when Confirmation Status is Not Confirmed |
| [ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding" | The encryption algorithm "RSA/ECB/OAEPWithSHA-256AndMGF1Padding". |
| ~~[ENCRYPTION_ALGORITHM_RSA_ECB_PKCS1PADDING](#encryption_algorithm_rsa_ecb_pkcs1padding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA/ECB/PKCS1Padding"~~ | The outdated encryption algorithm "RSA/ECB/PKCS1Padding". |
| [EXPORT_STATUS_EXPORTED](#export_status_exported): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | constant for when Export Status is Exported |
| [EXPORT_STATUS_FAILED](#export_status_failed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | constant for when Export Status is Failed |
| [EXPORT_STATUS_NOTEXPORTED](#export_status_notexported): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | constant for when Export Status is Not Exported |
| [EXPORT_STATUS_READY](#export_status_ready): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | constant for when Export Status is ready to be exported. |
| [ORDER_STATUS_CANCELLED](#order_status_cancelled): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | constant for when Order Status is Cancelled |
| [ORDER_STATUS_COMPLETED](#order_status_completed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | constant for when Order Status is Completed |
| [ORDER_STATUS_CREATED](#order_status_created): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | constant for when Order Status is Created |
| [ORDER_STATUS_FAILED](#order_status_failed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | constant for when Order Status is Failed |
| [ORDER_STATUS_NEW](#order_status_new): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | constant for when Order Status is New |
| [ORDER_STATUS_OPEN](#order_status_open): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | constant for when Order Status is Open |
| [ORDER_STATUS_REPLACED](#order_status_replaced): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | constant for when Order Status is Replaced |
| [PAYMENT_STATUS_NOTPAID](#payment_status_notpaid): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | constant for when Payment Status is Not Paid |
| [PAYMENT_STATUS_PAID](#payment_status_paid): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | constant for when Payment Status is Paid |
| [PAYMENT_STATUS_PARTPAID](#payment_status_partpaid): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | constant for when Payment Status is Part Paid |
| [SHIPPING_STATUS_NOTSHIPPED](#shipping_status_notshipped): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | constant for when Shipping Status is Not shipped |
| [SHIPPING_STATUS_PARTSHIPPED](#shipping_status_partshipped): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | constant for when Shipping Status is Part Shipped |
| [SHIPPING_STATUS_SHIPPED](#shipping_status_shipped): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | constant for when Shipping Status is Shipped |

## Property Summary

| Property | Description |
| --- | --- |
| [affiliatePartnerID](#affiliatepartnerid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the affiliate partner ID value, or null. |
| [affiliatePartnerName](#affiliatepartnername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the affiliate partner name value, or null. |
| [appeasementItems](#appeasementitems): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)s associated with this order. |
| [appeasements](#appeasements): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)s associated with this order. |
| [cancelCode](#cancelcode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | If this order was cancelled, returns the value of the  cancel code or null. |
| [cancelDescription](#canceldescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If this order was cancelled, returns the text describing why  the order was cancelled or null. |
| [capturedAmount](#capturedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of the captured amounts. |
| [confirmationStatus](#confirmationstatus): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the confirmation status of the order.<br/>  Possible values are [CONFIRMATION_STATUS_NOTCONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_notconfirmed) and  [CONFIRMATION_STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_confirmed). |
| [createdBy](#createdby): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the user who has created the order. |
| [currentOrder](#currentorder): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)` | Returns the current order. |
| [currentOrderNo](#currentorderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the order number of the current order. |
| [customerLocaleID](#customerlocaleid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the locale that was in effect when the order  was placed. |
| [customerOrderReference](#customerorderreference): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer-specific reference information for the order, or null. |
| [exportAfter](#exportafter): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns a date after which an order can be exported. |
| [exportStatus](#exportstatus): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the export status of the order.<br/>  Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_notexported),  [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_exported), [EXPORT_STATUS_READY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_ready),  and [EXPORT_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_failed). |
| [externalOrderNo](#externalorderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the value of an external order number associated  with this order, or null. |
| [externalOrderStatus](#externalorderstatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the status of an external order associated  with this order, or null. |
| [externalOrderText](#externalordertext): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the text describing the external order, or null. |
| [globalPartyID](#globalpartyid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The Global Party ID reconciles customer identity across multiple systems. |
| [imported](#imported): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true`, if the order is imported and `false`  otherwise. |
| [invoiceItems](#invoiceitems): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s associated with this order. |
| [invoiceNo](#invoiceno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the invoice number for this Order. |
| [invoices](#invoices): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)s associated with this order. |
| [orderExportXML](#orderexportxml): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the order export XML as String object. |
| [orderNo](#orderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the order number for this order. |
| [orderToken](#ordertoken): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the token for this order. |
| [originalOrder](#originalorder): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)` | Returns the original order associated with  this order. |
| [originalOrderNo](#originalorderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the order number of the original order associated with  this order. |
| [paymentStatus](#paymentstatus): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the order payment status value.<br/>  Possible values are [PAYMENT_STATUS_NOTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_notpaid), [PAYMENT_STATUS_PARTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_partpaid)  or [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_paid). |
| ~~[paymentTransaction](#paymenttransaction): [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)~~ `(read-only)` | Returns the payment transaction associated with this order. |
| [refundedAmount](#refundedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of the refunded amounts. |
| [remoteHost](#remotehost): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the IP address of the remote host from which the order was created. |
| [replaceCode](#replacecode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | If this order was replaced by another order,  returns the value of the replace code. |
| [replaceDescription](#replacedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If this order was replaced by another order,  returns the value of the replace description. |
| [replacedOrder](#replacedorder): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)` | Returns the order that this order replaced or null. |
| [replacedOrderNo](#replacedorderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the order number that this order replaced or null if this order  did not replace an order. |
| [replacementOrder](#replacementorder): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)` | Returns the order that replaced this order, or null. |
| [replacementOrderNo](#replacementorderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | If this order was replaced by another order,  returns the order number that replaced this order. |
| [returnCaseItems](#returncaseitems): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s associated with this order. |
| [returnCases](#returncases): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)s associated with this order. |
| [returnItems](#returnitems): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this order. |
| [returns](#returns): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this order. |
| [shippingOrderItems](#shippingorderitems): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s associated with this order. |
| [shippingOrders](#shippingorders): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the collection of [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)s associated with this order. |
| [shippingStatus](#shippingstatus): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the order shipping status.<br/>  Possible values are [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_notshipped),  [SHIPPING_STATUS_PARTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_partshipped) or [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_shipped). |
| [sourceCode](#sourcecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the source code stored with the order or `null` if no source code is attached to the order. |
| [sourceCodeGroup](#sourcecodegroup): [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md) `(read-only)` | Returns the source code group attached to the order or `null` if no source code group is attached to  the order. |
| [sourceCodeGroupID](#sourcecodegroupid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the source code group id stored with the order or `null` if no source code group is attached  to the order. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the status of the order.<br/>  Possible values are:  <ul>  <li>[ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created)</li>  <li>[ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new)</li>  <li>[ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open)</li>  <li>[ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed)</li>  <li>[ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)</li>  <li>[ORDER_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_failed)</li>  <li>[ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced)</li>  </ul> |
| [taxRoundedAtGroup](#taxroundedatgroup): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Use this method to check if the Order was created with grouped taxation calculation. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createAppeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createappeasement)() | Creates a new [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) associated with this order. |
| [createAppeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createappeasementstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) associated with this order. |
| [createReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createreturncaseboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Creates a new [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) associated with this order  specifying whether the ReturnCase is an RMA (return merchandise authorization). |
| [createReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createreturncasestring-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Creates a new [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) associated with this order  specifying whether the ReturnCase is an RMA (return merchandise authorization). |
| [createServiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createserviceitemstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [order item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) with the given status which wraps a new  [service item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md) which is created and added to the order. |
| [createShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createshippingorder)() | Creates a new [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) for this order. |
| [createShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createshippingorderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) for this order. |
| [getAffiliatePartnerID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getaffiliatepartnerid)() | Returns the affiliate partner ID value, or null. |
| [getAffiliatePartnerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getaffiliatepartnername)() | Returns the affiliate partner name value, or null. |
| [getAppeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getappeasementstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) associated with this order with the given appeasementNumber. |
| [getAppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getappeasementitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md) associated with this Order with the given appeasementItemID. |
| [getAppeasementItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getappeasementitems)() | Returns the collection of [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)s associated with this order. |
| [getAppeasements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getappeasements)() | Returns the collection of [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)s associated with this order. |
| [getCancelCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcancelcode)() | If this order was cancelled, returns the value of the  cancel code or null. |
| [getCancelDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcanceldescription)() | If this order was cancelled, returns the text describing why  the order was cancelled or null. |
| [getCapturedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcapturedamount)() | Returns the sum of the captured amounts. |
| [getConfirmationStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getconfirmationstatus)() | Returns the confirmation status of the order.<br/>  Possible values are [CONFIRMATION_STATUS_NOTCONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_notconfirmed) and  [CONFIRMATION_STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_confirmed). |
| [getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcreatedby)() | Returns the name of the user who has created the order. |
| [getCurrentOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)() | Returns the current order. |
| [getCurrentOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)() | Returns the order number of the current order. |
| [getCustomerLocaleID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcustomerlocaleid)() | Returns the ID of the locale that was in effect when the order  was placed. |
| [getCustomerOrderReference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcustomerorderreference)() | Returns the customer-specific reference information for the order, or null. |
| [getExportAfter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getexportafter)() | Returns a date after which an order can be exported. |
| [getExportStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getexportstatus)() | Returns the export status of the order.<br/>  Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_notexported),  [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_exported), [EXPORT_STATUS_READY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_ready),  and [EXPORT_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_failed). |
| [getExternalOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getexternalorderno)() | Returns the value of an external order number associated  with this order, or null. |
| [getExternalOrderStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getexternalorderstatus)() | Returns the status of an external order associated  with this order, or null. |
| [getExternalOrderText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getexternalordertext)() | Returns the text describing the external order, or null. |
| [getGlobalPartyID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getglobalpartyid)() | The Global Party ID reconciles customer identity across multiple systems. |
| [getInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoicestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) associated with this order with the given invoiceNumber. |
| [getInvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoiceitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md) associated with this order with the given ID. |
| [getInvoiceItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoiceitems)() | Returns the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s associated with this order. |
| [getInvoiceNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoiceno)() | Returns the invoice number for this Order. |
| [getInvoices](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoices)() | Returns the collection of [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)s associated with this order. |
| [getOrderExportXML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxml)() | Returns the order export XML as String object. |
| [getOrderExportXML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxmlstring-string---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the order export XML as String object, with payment instrument data re-encrypted using the given  encryption algorithm and key. |
| ~~[getOrderExportXML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxmlstring-string-boolean---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))~~ | Returns the order export XML as String object, with payment instrument data re-encrypted using the given  encryption algorithm and key. |
| [getOrderExportXML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxmlstring-string---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the order export XML as String object, with payment instrument data re-encrypted using the given  encryption algorithm and key. |
| [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for the itemID. |
| [getOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderno)() | Returns the order number for this order. |
| [getOrderToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getordertoken)() | Returns the token for this order. |
| [getOriginalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)() | Returns the original order associated with  this order. |
| [getOriginalOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)() | Returns the order number of the original order associated with  this order. |
| [getPaymentStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getpaymentstatus)() | Returns the order payment status value.<br/>  Possible values are [PAYMENT_STATUS_NOTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_notpaid), [PAYMENT_STATUS_PARTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_partpaid)  or [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_paid). |
| ~~[getPaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getpaymenttransaction)()~~ | Returns the payment transaction associated with this order. |
| [getRefundedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getrefundedamount)() | Returns the sum of the refunded amounts. |
| [getRemoteHost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getremotehost)() | Returns the IP address of the remote host from which the order was created. |
| [getReplaceCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacecode)() | If this order was replaced by another order,  returns the value of the replace code. |
| [getReplaceDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedescription)() | If this order was replaced by another order,  returns the value of the replace description. |
| [getReplacedOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)() | Returns the order that this order replaced or null. |
| [getReplacedOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)() | Returns the order number that this order replaced or null if this order  did not replace an order. |
| [getReplacementOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)() | Returns the order that replaced this order, or null. |
| [getReplacementOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)() | If this order was replaced by another order,  returns the order number that replaced this order. |
| [getReturn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturnstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) associated with this order with the given returnNumber. |
| [getReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncasestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) associated with this order with the given returnCaseNumber. |
| [getReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncaseitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) associated with this order with the given returnCaseItemID. |
| [getReturnCaseItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncaseitems)() | Returns the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s associated with this order. |
| [getReturnCases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncases)() | Returns the collection of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)s associated with this order. |
| [getReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturnitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) associated with this order with the given ID. |
| [getReturnItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturnitems)() | Returns the collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this order. |
| [getReturns](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturns)() | Returns the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this order. |
| [getShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getshippingorderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) associated with this order with the given shippingOrderNumber. |
| [getShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getshippingorderitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) associated with this order with the given shippingOrderItemID. |
| [getShippingOrderItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getshippingorderitems)() | Returns the collection of [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s associated with this order. |
| [getShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getshippingorders)() | Returns the collection of [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)s associated with this order. |
| [getShippingStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getshippingstatus)() | Returns the order shipping status.<br/>  Possible values are [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_notshipped),  [SHIPPING_STATUS_PARTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_partshipped) or [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_shipped). |
| [getSourceCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getsourcecode)() | Returns the source code stored with the order or `null` if no source code is attached to the order. |
| [getSourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getsourcecodegroup)() | Returns the source code group attached to the order or `null` if no source code group is attached to  the order. |
| [getSourceCodeGroupID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getsourcecodegroupid)() | Returns the source code group id stored with the order or `null` if no source code group is attached  to the order. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getstatus)() | Returns the status of the order.<br/>  Possible values are:  <ul>  <li>[ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created)</li>  <li>[ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new)</li>  <li>[ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open)</li>  <li>[ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed)</li>  <li>[ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)</li>  <li>[ORDER_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_failed)</li>  <li>[ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced)</li>  </ul> |
| [isImported](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#isimported)() | Returns `true`, if the order is imported and `false`  otherwise. |
| [isTaxRoundedAtGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#istaxroundedatgroup)() | Use this method to check if the Order was created with grouped taxation calculation. |
| [reauthorize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#reauthorize)() | Ensures that the order is authorized. |
| [removeRemoteHost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#removeremotehost)() | Removes the IP address of the remote host if stored. |
| [setAffiliatePartnerID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setaffiliatepartneridstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the affiliate partner ID value. |
| [setAffiliatePartnerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setaffiliatepartnernamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the affiliate partner name value. |
| [setCancelCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcancelcodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the cancel code value. |
| [setCancelDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcanceldescriptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the description as to why the order was cancelled. |
| [setConfirmationStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setconfirmationstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the confirmation status value.<br/>  Possible values are [CONFIRMATION_STATUS_NOTCONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_notconfirmed) or  [CONFIRMATION_STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_confirmed). |
| [setCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcustomercustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | This method is used to associate the order object with the specified customer object. |
| [setCustomerNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcustomernostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer number associated with this order. |
| [setCustomerOrderReference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcustomerorderreferencestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer-specific reference information for the order. |
| [setExportAfter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setexportafterdate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the date after which an order can be exported. |
| [setExportStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setexportstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the export status of the order.<br/>  Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_notexported), [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_exported),  [EXPORT_STATUS_READY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_ready), and [EXPORT_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_failed). |
| [setExternalOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setexternalordernostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value of an external order number associated  with this order |
| [setExternalOrderStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setexternalorderstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the status of an external order associated  with this order |
| [setExternalOrderText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setexternalordertextstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the text describing the external order. |
| [setInvoiceNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setinvoicenostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the invoice number for this Order. |
| ~~[setOrderStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setorderstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Sets the order status. |
| [setPaymentStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setpaymentstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the order payment status.<br/>  Possible values are [PAYMENT_STATUS_NOTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_notpaid), [PAYMENT_STATUS_PARTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_partpaid)  or [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_paid). |
| [setReplaceCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setreplacecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value of the replace code. |
| [setReplaceDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setreplacedescriptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value of the replace description. |
| [setShippingStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setshippingstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the order shipping status value.<br/>  Possible values are [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_notshipped),  [SHIPPING_STATUS_PARTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_partshipped) or [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_shipped). |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the status of the order. |
| [trackOrderChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#trackorderchangestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Tracks an order change. |

### Methods inherited from class LineItemCtnr

[addNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#addnotestring-string), [createBillingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbillingaddress), [createBonusProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createbonusproductlineitembonusdiscountlineitem-product-productoptionmodel-shipment), [createCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring), [createCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring-boolean), [createGiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#creategiftcertificatelineitemnumber-string), [createGiftCertificatePaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#creategiftcertificatepaymentinstrumentstring-money), [createPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpaymentinstrumentstring-money), [createPaymentInstrumentFromWallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpaymentinstrumentfromwalletcustomerpaymentinstrument-money), [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring), [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring-discount), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemproduct-productoptionmodel-shipment), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemproductlistitem-shipment), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-shipment), [createProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-quantity-shipment), [createShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createshipmentstring), [createShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createshippingpriceadjustmentstring), [getAdjustedMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalgrossprice), [getAdjustedMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalnetprice), [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalprice), [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotalpriceboolean), [getAdjustedMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedmerchandizetotaltax), [getAdjustedShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalgrossprice), [getAdjustedShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalnetprice), [getAdjustedShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotalprice), [getAdjustedShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getadjustedshippingtotaltax), [getAllGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallgiftcertificatelineitems), [getAllLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getalllineitems), [getAllProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductlineitems), [getAllProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductlineitemsstring), [getAllProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallproductquantities), [getAllShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getallshippingpriceadjustments), [getBillingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbillingaddress), [getBonusDiscountLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbonusdiscountlineitems), [getBonusLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbonuslineitems), [getBusinessType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getbusinesstype), [getChannelType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getchanneltype), [getCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcouponlineitemstring), [getCouponLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcouponlineitems), [getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcurrencycode), [getCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomer), [getCustomerEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomeremail), [getCustomerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomername), [getCustomerNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomerno), [getDefaultShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getdefaultshipment), [getEtag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getetag), [getGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitems), [getGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatelineitemsstring), [getGiftCertificatePaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstruments), [getGiftCertificatePaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatepaymentinstrumentsstring), [getGiftCertificateTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalgrossprice), [getGiftCertificateTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalnetprice), [getGiftCertificateTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotalprice), [getGiftCertificateTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getgiftcertificatetotaltax), [getMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalgrossprice), [getMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalnetprice), [getMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotalprice), [getMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getmerchandizetotaltax), [getNotes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getnotes), [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstrument), [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstruments), [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstrumentsstring), [getPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpriceadjustmentbypromotionidstring), [getPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpriceadjustments), [getProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductlineitems), [getProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductlineitemsstring), [getProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantities), [getProductQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitiesboolean), [getProductQuantityTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getproductquantitytotal), [getShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshipmentstring), [getShipments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshipments), [getShippingPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustmentbypromotionidstring), [getShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingpriceadjustments), [getShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalgrossprice), [getShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalnetprice), [getShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotalprice), [getShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getshippingtotaltax), [getTaxTotalsPerTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettaxtotalspertaxrate), [getTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotalgrossprice), [getTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotalnetprice), [getTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#gettotaltax), [isExternallyTaxed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#isexternallytaxed), [isTaxRoundedAtGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#istaxroundedatgroup), [removeAllPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeallpaymentinstruments), [removeBonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removebonusdiscountlineitembonusdiscountlineitem), [removeCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removecouponlineitemcouponlineitem), [removeGiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removegiftcertificatelineitemgiftcertificatelineitem), [removeNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removenotenote), [removePaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removepaymentinstrumentpaymentinstrument), [removePriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removepriceadjustmentpriceadjustment), [removeProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeproductlineitemproductlineitem), [removeShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshipmentshipment), [removeShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#removeshippingpriceadjustmentpriceadjustment), [setCustomerEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#setcustomeremailstring), [setCustomerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#setcustomernamestring), [updateOrderLevelPriceAdjustmentTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#updateorderlevelpriceadjustmenttax), [updateTotals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#updatetotals), [verifyPriceAdjustmentLimits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#verifypriceadjustmentlimits)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CONFIRMATION_STATUS_CONFIRMED

- CONFIRMATION_STATUS_CONFIRMED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : constant for when Confirmation Status is Confirmed


---

### CONFIRMATION_STATUS_NOTCONFIRMED

- CONFIRMATION_STATUS_NOTCONFIRMED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : constant for when Confirmation Status is Not Confirmed


---

### ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING

- ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding"
  - : The encryption algorithm "RSA/ECB/OAEPWithSHA-256AndMGF1Padding".


---

### ENCRYPTION_ALGORITHM_RSA_ECB_PKCS1PADDING

- ~~ENCRYPTION_ALGORITHM_RSA_ECB_PKCS1PADDING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA/ECB/PKCS1Padding"~~
  - : The outdated encryption algorithm "RSA/ECB/PKCS1Padding". Please do not use anymore!

    **Deprecated:**
**warning:** Support for this algorithm will be removed in a future release. Please use
            [ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) instead.

---

### EXPORT_STATUS_EXPORTED

- EXPORT_STATUS_EXPORTED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : constant for when Export Status is Exported


---

### EXPORT_STATUS_FAILED

- EXPORT_STATUS_FAILED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : constant for when Export Status is Failed


---

### EXPORT_STATUS_NOTEXPORTED

- EXPORT_STATUS_NOTEXPORTED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : constant for when Export Status is Not Exported


---

### EXPORT_STATUS_READY

- EXPORT_STATUS_READY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : constant for when Export Status is ready to be exported.


---

### ORDER_STATUS_CANCELLED

- ORDER_STATUS_CANCELLED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : constant for when Order Status is Cancelled


---

### ORDER_STATUS_COMPLETED

- ORDER_STATUS_COMPLETED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : constant for when Order Status is Completed


---

### ORDER_STATUS_CREATED

- ORDER_STATUS_CREATED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : constant for when Order Status is Created


---

### ORDER_STATUS_FAILED

- ORDER_STATUS_FAILED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : constant for when Order Status is Failed


---

### ORDER_STATUS_NEW

- ORDER_STATUS_NEW: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : constant for when Order Status is New


---

### ORDER_STATUS_OPEN

- ORDER_STATUS_OPEN: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : constant for when Order Status is Open


---

### ORDER_STATUS_REPLACED

- ORDER_STATUS_REPLACED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : constant for when Order Status is Replaced


---

### PAYMENT_STATUS_NOTPAID

- PAYMENT_STATUS_NOTPAID: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : constant for when Payment Status is Not Paid


---

### PAYMENT_STATUS_PAID

- PAYMENT_STATUS_PAID: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : constant for when Payment Status is Paid


---

### PAYMENT_STATUS_PARTPAID

- PAYMENT_STATUS_PARTPAID: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : constant for when Payment Status is Part Paid


---

### SHIPPING_STATUS_NOTSHIPPED

- SHIPPING_STATUS_NOTSHIPPED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : constant for when Shipping Status is Not shipped


---

### SHIPPING_STATUS_PARTSHIPPED

- SHIPPING_STATUS_PARTSHIPPED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : constant for when Shipping Status is Part Shipped


---

### SHIPPING_STATUS_SHIPPED

- SHIPPING_STATUS_SHIPPED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : constant for when Shipping Status is Shipped


---

## Property Details

### affiliatePartnerID
- affiliatePartnerID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the affiliate partner ID value, or null.


---

### affiliatePartnerName
- affiliatePartnerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the affiliate partner name value, or null.


---

### appeasementItems
- appeasementItems: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)s associated with this order.


---

### appeasements
- appeasements: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)s associated with this order.


---

### cancelCode
- cancelCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : If this order was cancelled, returns the value of the
      cancel code or null.



---

### cancelDescription
- cancelDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If this order was cancelled, returns the text describing why
      the order was cancelled or null.



---

### capturedAmount
- capturedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of the captured amounts. The captured amounts
      are calculated on the fly. Associate a payment capture for an [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md) with an [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
      using [Invoice.addCaptureTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addcapturetransactionorderpaymentinstrument-money).



---

### confirmationStatus
- confirmationStatus: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the confirmation status of the order.
      
      Possible values are [CONFIRMATION_STATUS_NOTCONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_notconfirmed) and
      [CONFIRMATION_STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_confirmed).



---

### createdBy
- createdBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the user who has created the order.
      If an agent user has created the order, the agent user's name
      is returned. Otherwise "Customer" is returned.



---

### currentOrder
- currentOrder: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)`
  - : Returns the current order. The current order
      represents the most recent order in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order 3 is now the
      current order and Order1 is still the original representation of the
      order. If this order has not been replaced, this method returns this
      order because this order is the current order.


    **See Also:**
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### currentOrderNo
- currentOrderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the order number of the current order. The current order
      represents the most recent order in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order 3 is now the
      current order and Order1 is still the original representation of the
      order. If this order has not been replaced, calling this method returns the
      same value as the [getOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderno) method because this order is the
      current order.


    **See Also:**
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### customerLocaleID
- customerLocaleID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the locale that was in effect when the order
      was placed. This is the customer's locale.



---

### customerOrderReference
- customerOrderReference: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer-specific reference information for the order, or null.


---

### exportAfter
- exportAfter: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns a date after which an order can be exported.


---

### exportStatus
- exportStatus: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the export status of the order.
      
      Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_notexported),
      [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_exported), [EXPORT_STATUS_READY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_ready),
      and [EXPORT_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_failed).



---

### externalOrderNo
- externalOrderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of an external order number associated
      with this order, or null.



---

### externalOrderStatus
- externalOrderStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status of an external order associated
      with this order, or null.



---

### externalOrderText
- externalOrderText: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the text describing the external order, or null.


---

### globalPartyID
- globalPartyID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The Global Party ID reconciles customer identity across multiple systems. For example, as part of the Service for
      Commerce experience, service agents can find information for customers who have never called into the call
      center, but have created a profile on the website. Service agents can find guest order data from B2C Commerce and
      easily create accounts for customers. Customer 360 Data Manager matches records from multiple data sources to
      determine all the records associated with a specific customer.



---

### imported
- imported: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true`, if the order is imported and `false`
      otherwise.



---

### invoiceItems
- invoiceItems: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### invoiceNo
- invoiceNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the invoice number for this Order.
      
      
      When an order is placed (e.g. with [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder)) invoice number will be filled
      using a sequence. Before order was placed `null` will be returned unless it was set with
      [setInvoiceNo(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setinvoicenostring).



---

### invoices
- invoices: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### orderExportXML
- orderExportXML: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the order export XML as String object.
      
      
      NOTE: This method will return payment instrument data masked. If payment instrument re-encryption is needed
      please use [getOrderExportXML(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxmlstring-string---variant-2) instead.
      
      
      Example:
      
      
      ```
      var orderXMLAsString : String = order.getOrderExportXML();
      var orderXML : XML = new XML(orderXMLAsString);
      ```



---

### orderNo
- orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the order number for this order.


---

### orderToken
- orderToken: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the token for this order. The order token is a string (length 32 bytes) associated
      with this one order. The order token is random. It reduces the capability of malicious
      users to access an order through guessing. Order token can be used to **further** validate order
      ownership, but should never be used to solely validate ownership. In addition, the storefront
      should ensure authentication and authorization. See the [Security Best Practices for Developers](https://help.salesforce.com/s/articleView?id=cc.b2c\_developer\_authentication\_and\_authorization.htm) for details.



---

### originalOrder
- originalOrder: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)`
  - : Returns the original order associated with
      this order. The original order represents an order that was the
      first ancestor in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order1 is still the
      original representation of the order. If this order is the first
      ancestor, this method returns this order.


    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### originalOrderNo
- originalOrderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the order number of the original order associated with
      this order. The original order represents an order that was the
      first ancestor in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order1 is still the
      original representation of the order. If this order is the first
      ancestor, this method returns the value of getOrderNo().


    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### paymentStatus
- paymentStatus: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the order payment status value.
      
      Possible values are [PAYMENT_STATUS_NOTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_notpaid), [PAYMENT_STATUS_PARTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_partpaid)
      or [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_paid).



---

### paymentTransaction
- ~~paymentTransaction: [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)~~ `(read-only)`
  - : Returns the payment transaction associated with this order.
      It is possible that there are multiple payment transactions
      associated with the order.  In this case, this method returns
      the transaction associated with the first PaymentInstrument
      returned by `getPaymentInstruments()`.


    **Deprecated:**
**warning:** Use [LineItemCtnr.getPaymentInstruments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstruments)
to get the list of PaymentInstrument instances and then use
getPaymentTransaction() method on each PaymentInstrument to access
the individual transactions.

---

### refundedAmount
- refundedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of the refunded amounts. The refunded amounts are
      calculated on the fly. Associate a payment refund for an [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md) with an [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
      using [Invoice.addRefundTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addrefundtransactionorderpaymentinstrument-money).



---

### remoteHost
- remoteHost: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the IP address of the remote host from which the order was created.
      
      
      If the IP address was not captured for the order because order IP logging
      was disabled at the time the order was created, null will be returned.



---

### replaceCode
- replaceCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : If this order was replaced by another order,
      returns the value of the replace code. Otherwise.
      returns null.



---

### replaceDescription
- replaceDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If this order was replaced by another order,
      returns the value of the replace description. Otherwise
      returns null.



---

### replacedOrder
- replacedOrder: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)`
  - : Returns the order that this order replaced or null. For example, if you
      have three orders where Order1 was replaced by Order2 and Order2 was
      replaced by Order3, calling this method on Order3 will return Order2.
      Similarly, calling this method on Order1 will return null as Order1 was
      the original order.


    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### replacedOrderNo
- replacedOrderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the order number that this order replaced or null if this order
      did not replace an order. For example, if you have three orders
      where Order1 was replaced by Order2 and Order2 was replaced by Order3,
      calling this method on Order3 will return the order number for
      Order2. Similarly, calling this method on Order1 will return null as
      Order1 was the original order.


    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### replacementOrder
- replacementOrder: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) `(read-only)`
  - : Returns the order that replaced this order, or null.

    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)


---

### replacementOrderNo
- replacementOrderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : If this order was replaced by another order,
      returns the order number that replaced this order. Otherwise
      returns null.


    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)


---

### returnCaseItems
- returnCaseItems: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### returnCases
- returnCases: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### returnItems
- returnItems: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### returns
- returns: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### shippingOrderItems
- shippingOrderItems: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### shippingOrders
- shippingOrders: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the collection of [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### shippingStatus
- shippingStatus: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the order shipping status.
      
      Possible values are [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_notshipped),
      [SHIPPING_STATUS_PARTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_partshipped) or [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_shipped).



---

### sourceCode
- sourceCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the source code stored with the order or `null` if no source code is attached to the order.


---

### sourceCodeGroup
- sourceCodeGroup: [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md) `(read-only)`
  - : Returns the source code group attached to the order or `null` if no source code group is attached to
      the order.



---

### sourceCodeGroupID
- sourceCodeGroupID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the source code group id stored with the order or `null` if no source code group is attached
      to the order.



---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the status of the order.
      
      Possible values are:
      
      - [ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created)
      - [ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new)
      - [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open)
      - [ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed)
      - [ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)
      - [ORDER_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_failed)
      - [ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced)
      
      
      
      The order status usually changes when a process action is initiated. Most status changes have an action which
      needs to executed in order to end having the order in a specific order status. When an order is created with e.g.
      [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) the order status will be [ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created). The usual
      flow is that payment authorization will be added to the order. Once the order is considered as valid (payed,
      fraud checked, ...) the order gets placed. This can be done by calling
      [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder). The result of placing an order will be status
      [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open) (from a process standpoint [ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new) which has the same meaning).
      Status [ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced) is related to functionality
      [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder). [ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed) has no meaning by
      default but can be used by custom implementations but is a synonym for NEW/OPEN. Below you will find the most important status changes:
      
      
      
      | Status before | Action | Status after | Business meaning |
      | --- |--- |--- |--- |
      | - | [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) | CREATED | Order was created from a basket. |
      | CREATED | [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder) | OPEN/NEW | Order was considered as valid. Order can now be exported to 3rd party systems. |
      | CREATED | [OrderMgr.failOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder) | FAILED | Order was considered not valid. E.g. payment authorization was wrong or fraud check was not successful. |
      | OPEN/NEW | [OrderMgr.cancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#cancelorderorder) | CANCELLED | Order was cancelled. |
      | CANCELLED | [OrderMgr.undoCancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undocancelorderorder) | OPEN/NEW | Order was cancelled by mistake and this needs to be undone. |
      | FAILED | [OrderMgr.undoFailOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undofailorderorder) | CREATED | Order was failed by mistake and this needs to be undone. |
      
      
      Every status change will trigger a change in the order journal which is the base for GMV calculations.


    **See Also:**
    - [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)


---

### taxRoundedAtGroup
- taxRoundedAtGroup: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Use this method to check if the Order was created with grouped taxation calculation.
      
      
      If the tax is rounded on group level, the tax is applied to the summed-up tax basis for each tax rate.



---

## Method Details

### createAppeasement()
- createAppeasement(): [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)
  - : Creates a new [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) associated with this order.
      
      The new Appeasement
      will have an appeasementNumber based on the [getOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderno).
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - the created appeasement


---

### createAppeasement(String)
- createAppeasement(appeasementNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)
  - : Creates a new [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) associated with this order.
      
      
      An appeasementNumber must be specified.
      
      
      If an Appeasement already exists for the appeasementNumber, the method fails with an
      exception.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - appeasementNumber - the appeasementNumber to be assigned to the newly created appeasement

    **Returns:**
    - the created appeasement

    **Throws:**
    - IllegalArgumentException - if an Appeasement already exists with the number.


---

### createReturnCase(Boolean)
- createReturnCase(isRMA: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)
  - : Creates a new [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) associated with this order
      specifying whether the ReturnCase is an RMA (return merchandise authorization).
      
      
      The new ReturnCase
      will have a returnCaseNumber based on the [getOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderno), e.g. for an order-no 1234 the
      return cases will have the numbers 1234\#RC1, 1234\#RC2, 1234\#RC3...
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - isRMA - whether the new ReturnCase is an RMA (return merchandise authorization)

    **Returns:**
    - the created ReturnCase


---

### createReturnCase(String, Boolean)
- createReturnCase(returnCaseNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), isRMA: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)
  - : Creates a new [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) associated with this order
      specifying whether the ReturnCase is an RMA (return merchandise authorization).
      
      
      A returnCaseNumber must be specified.
      
      
      If a ReturnCase already exists for the returnCaseNumber, the method fails with an
      exception.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - returnCaseNumber - returnCaseNumber to use
    - isRMA - whether the new ReturnCase is an RMA (return merchandise authorization)

    **Returns:**
    - null or the ReturnCase associated with the given returnCaseNumber

    **Throws:**
    - IllegalArgumentException - if a ReturnCase already exists with the number.


---

### createServiceItem(String, String)
- createServiceItem(ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)
  - : Returns the [order item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) with the given status which wraps a new
      [service item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md) which is created and added to the order.


    **Parameters:**
    - ID - the ID of the new service item.             This ID will be returned when [ShippingLineItem.getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getid)             is called.
    - status - the status of the order item, use one of   <li>[OrderItem.STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_new)</li>  <li>[OrderItem.STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_open)</li>  <li>[OrderItem.STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_shipped)</li>  </ul>    Order post-processing APIs (gillian) are now inactive by default and will throw  an exception if accessed. Activation needs preliminary approval by Product Management.  Please contact support in this case. Existing customers using these APIs are not  affected by this change and can use the APIs until further notice.

    **Returns:**
    - the created order item


---

### createShippingOrder()
- createShippingOrder(): [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)
  - : Creates a new [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) for this order.
      
      
      Generates a default shipping order number. Use
      [createShippingOrder(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createshippingorderstring) for a defined shipping order number.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - the created shipping order

    **See Also:**
    - [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)


---

### createShippingOrder(String)
- createShippingOrder(shippingOrderNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)
  - : Creates a new [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) for this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - shippingOrderNumber - the document number to be used

    **Returns:**
    - the created shipping order

    **See Also:**
    - [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)


---

### getAffiliatePartnerID()
- getAffiliatePartnerID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the affiliate partner ID value, or null.

    **Returns:**
    - the affiliate partner ID value, or null.


---

### getAffiliatePartnerName()
- getAffiliatePartnerName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the affiliate partner name value, or null.

    **Returns:**
    - the affiliate partner name value, or null.


---

### getAppeasement(String)
- getAppeasement(appeasementNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)
  - : Returns the [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) associated with this order with the given appeasementNumber.
      The method returns `null` if no instance can be found.


    **Parameters:**
    - appeasementNumber - the appeasement number

    **Returns:**
    - the Appeasement associated with the given appeasementNumber


---

### getAppeasementItem(String)
- getAppeasementItem(appeasementItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)
  - : Returns the [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md) associated with this Order with the given appeasementItemID.
      The method returns `null` if no instance can be found.


    **Parameters:**
    - appeasementItemID - the ID

    **Returns:**
    - the AppeasementItem associated with the given appeasementItemID.


---

### getAppeasementItems()
- getAppeasementItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)s associated with this order.

    **Returns:**
    - the appeasement items belonging to this order


---

### getAppeasements()
- getAppeasements(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)s associated with this order.

    **Returns:**
    - the appeasements associated with this order


---

### getCancelCode()
- getCancelCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : If this order was cancelled, returns the value of the
      cancel code or null.


    **Returns:**
    - the value of the cancel code.


---

### getCancelDescription()
- getCancelDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If this order was cancelled, returns the text describing why
      the order was cancelled or null.


    **Returns:**
    - the description as to why the order was cancelled or null.


---

### getCapturedAmount()
- getCapturedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of the captured amounts. The captured amounts
      are calculated on the fly. Associate a payment capture for an [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md) with an [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
      using [Invoice.addCaptureTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addcapturetransactionorderpaymentinstrument-money).


    **Returns:**
    - sum of captured amounts


---

### getConfirmationStatus()
- getConfirmationStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the confirmation status of the order.
      
      Possible values are [CONFIRMATION_STATUS_NOTCONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_notconfirmed) and
      [CONFIRMATION_STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_confirmed).


    **Returns:**
    - Order confirmation status


---

### getCreatedBy()
- getCreatedBy(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the user who has created the order.
      If an agent user has created the order, the agent user's name
      is returned. Otherwise "Customer" is returned.


    **Returns:**
    - the name of the user who created the order.


---

### getCurrentOrder()
- getCurrentOrder(): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Returns the current order. The current order
      represents the most recent order in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order 3 is now the
      current order and Order1 is still the original representation of the
      order. If this order has not been replaced, this method returns this
      order because this order is the current order.


    **Returns:**
    - the current order.

    **See Also:**
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### getCurrentOrderNo()
- getCurrentOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order number of the current order. The current order
      represents the most recent order in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order 3 is now the
      current order and Order1 is still the original representation of the
      order. If this order has not been replaced, calling this method returns the
      same value as the [getOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderno) method because this order is the
      current order.


    **Returns:**
    - the order number of the current order

    **See Also:**
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### getCustomerLocaleID()
- getCustomerLocaleID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the locale that was in effect when the order
      was placed. This is the customer's locale.


    **Returns:**
    - the ID of the locale associated with this order, or null.


---

### getCustomerOrderReference()
- getCustomerOrderReference(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer-specific reference information for the order, or null.

    **Returns:**
    - the customer-specific reference information for the order, or null.


---

### getExportAfter()
- getExportAfter(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns a date after which an order can be exported.

    **Returns:**
    - a date after which an order can be exported.


---

### getExportStatus()
- getExportStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the export status of the order.
      
      Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_notexported),
      [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_exported), [EXPORT_STATUS_READY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_ready),
      and [EXPORT_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_failed).


    **Returns:**
    - Order export status


---

### getExternalOrderNo()
- getExternalOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of an external order number associated
      with this order, or null.


    **Returns:**
    - the value of an external order number associated
      with this order, or null.



---

### getExternalOrderStatus()
- getExternalOrderStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status of an external order associated
      with this order, or null.


    **Returns:**
    - the status of an external order associated
      with this order, or null.



---

### getExternalOrderText()
- getExternalOrderText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the text describing the external order, or null.

    **Returns:**
    - the text describing the external order, or null.


---

### getGlobalPartyID()
- getGlobalPartyID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The Global Party ID reconciles customer identity across multiple systems. For example, as part of the Service for
      Commerce experience, service agents can find information for customers who have never called into the call
      center, but have created a profile on the website. Service agents can find guest order data from B2C Commerce and
      easily create accounts for customers. Customer 360 Data Manager matches records from multiple data sources to
      determine all the records associated with a specific customer.


    **Returns:**
    - the Global Party ID associated with this order, or null.


---

### getInvoice(String)
- getInvoice(invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Returns the [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) associated with this order with the given invoiceNumber.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - invoiceNumber - the invoice number

    **Returns:**
    - the invoice associated with the given invoiceNumber


---

### getInvoiceItem(String)
- getInvoiceItem(invoiceItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)
  - : Returns the [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md) associated with this order with the given ID.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - invoiceItemID - the item ID

    **Returns:**
    - the invoice item associated with the given ID


---

### getInvoiceItems()
- getInvoiceItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - invoice items belonging to this order


---

### getInvoiceNo()
- getInvoiceNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the invoice number for this Order.
      
      
      When an order is placed (e.g. with [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder)) invoice number will be filled
      using a sequence. Before order was placed `null` will be returned unless it was set with
      [setInvoiceNo(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setinvoicenostring).


    **Returns:**
    - the invoice number for this Order.


---

### getInvoices()
- getInvoices(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - invoices belonging to this order


---

### getOrderExportXML()
- getOrderExportXML(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order export XML as String object.
      
      
      NOTE: This method will return payment instrument data masked. If payment instrument re-encryption is needed
      please use [getOrderExportXML(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxmlstring-string---variant-2) instead.
      
      
      Example:
      
      
      ```
      var orderXMLAsString : String = order.getOrderExportXML();
      var orderXML : XML = new XML(orderXMLAsString);
      ```


    **Returns:**
    - the order export XML

    **Throws:**
    - IllegalStateException - If the method is called in a transaction with changes.
    - IllegalStateException - If the order is not placed. This method can be called for placed orders only.
    - IllegalStateException - If the order export XML could not be generated.


---

### getOrderExportXML(String, String) - Variant 1
- getOrderExportXML(encryptionAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encryptionKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order export XML as String object, with payment instrument data re-encrypted using the given
      encryption algorithm and key.
      
      
      NOTE: If no encryption is needed or desired please always use [getOrderExportXML()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxml) instead, which returns
      the payment instrument data masked. Do **not** pass in any null arguments!
      
      
      Example:
      
      
      ```
      var orderXMLAsString : String = order.getOrderExportXML( "RSA/ECB/PKCS1Padding", "[key]" );
      var orderXML : XML = new XML( orderXMLAsString );
      ```


    **Parameters:**
    - encryptionAlgorithm - The encryption algorithm to be used for the re-encryption of the payment instrument             data (credit card number, bank account number, bank account driver's license number). Must be a valid,             non-null algorithm. Currently, only [ENCRYPTION_ALGORITHM_RSA_ECB_PKCS1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#encryption_algorithm_rsa_ecb_pkcs1padding) is supported,             but this will be fixed and support for             [ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) will be added soon.
    - encryptionKey - The Base64 encoded form of the public key to be used for the re-encryption of the payment             instrument data. Must be a valid, non-blank key.

    **Returns:**
    - the order export XML

    **Throws:**
    - IllegalStateException - If the method is called in a transaction with changes.
    - IllegalStateException - If the order is not placed. This method can be called for placed orders only.
    - IllegalStateException - If the order export XML could not be generated.

    **API Version:**
**note:** No longer available as of version 22.7.
undefined behaviour for invalid arguments (e.g. null)

---

### getOrderExportXML(String, String, Boolean) - Variant 1
- ~~getOrderExportXML(encryptionAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encryptionKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encryptUsingEKID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the order export XML as String object, with payment instrument data re-encrypted using the given
      encryption algorithm and key.
      
      
      NOTE: If no encryption is needed or desired please always use [getOrderExportXML()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxml) instead, which returns
      the payment instrument data masked. Do **not** pass in any null arguments!
      
      
      Example:
      
      
      ```
      var orderXMLAsString : String = order.getOrderExportXML( "RSA/ECB/PKCS1Padding", "[key]", false );
      var orderXML : XML = new XML( orderXMLAsString );
      ```


    **Parameters:**
    - encryptionAlgorithm - The encryption algorithm to be used for the re-encryption of the payment instrument             data (credit card number, bank account number, bank account driver's license number). Must be a valid,             non-null algorithm. Currently, only [ENCRYPTION_ALGORITHM_RSA_ECB_PKCS1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#encryption_algorithm_rsa_ecb_pkcs1padding) is supported,             but this will be fixed and support for             [ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) will be added soon.
    - encryptionKey - The Base64 encoded form of the public key to be used for the re-encryption of the payment             instrument data. Must be a valid, non-blank key.
    - encryptUsingEKID - ignored

    **Returns:**
    - the order export XML

    **Throws:**
    - IllegalStateException - If the method is called in a transaction with changes.
    - IllegalStateException - If the order is not placed. This method can be called for placed orders only.
    - IllegalStateException - If the order export XML could not be generated.

    **Deprecated:**
**warning:** This method will be removed soon. Please use the following methods instead:
            
- [getOrderExportXML()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxml)– if payment instrument data should be masked                - [getOrderExportXML(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxmlstring-string---variant-1)– if payment instrument data should be re-encrypted
    **API Version:**
**note:** No longer available as of version 22.7.
undefined behaviour for invalid arguments (e.g. null)

---

### getOrderExportXML(String, String) - Variant 2
- getOrderExportXML(encryptionAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encryptionKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order export XML as String object, with payment instrument data re-encrypted using the given
      encryption algorithm and key.
      
      
      NOTE: If no encryption is needed or desired please always use [getOrderExportXML()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderexportxml) instead, which returns
      the payment instrument data masked.
      
      
      Example:
      
      
      ```
      var orderXMLAsString : String = order.getOrderExportXML( "RSA/ECB/PKCS1Padding", "[key]" );
      var orderXML : XML = new XML( orderXMLAsString );
      ```


    **Parameters:**
    - encryptionAlgorithm - The encryption algorithm used for the re-encryption of the payment instrument data             (credit card number, bank account number, bank account driver's license number). Must be one of the             following:                          <li>[ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) – The current and preferred             algorithm.             <li>[ENCRYPTION_ALGORITHM_RSA_ECB_PKCS1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#encryption_algorithm_rsa_ecb_pkcs1padding) – This algorithm is outdated/deprecated and             will be removed in a future release. Please do **not** use anymore.             </ul>
    - encryptionKey - The Base64 encoded form of the public key used for the re-encryption of the payment             instrument data. Must be a valid, non-blank key.

    **Returns:**
    - the order export XML

    **Throws:**
    - IllegalArgumentException - If `encryptionAlgorithm` is not a valid known algorithm.
    - IllegalArgumentException - If `encryptionKey` is a blank string.
    - IllegalStateException - If the method is called in a transaction with changes.
    - IllegalStateException - If the order is not placed. This method can be called for placed orders only.
    - IllegalStateException - If the order export XML could not be generated.

    **API Version:**
**note:** Available from version 22.7.
strict encryption argument checks; no null or otherwise invalid values allowed

---

### getOrderItem(String)
- getOrderItem(itemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)
  - : Returns the [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for the itemID.
      An OrderItem will only exist for [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)s or
      [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)s which belong to the order.
      The method fails with an exception if no instance can be found.


    **Parameters:**
    - itemID - the itemID

    **Returns:**
    - the order item for itemID

    **Throws:**
    - IllegalArgumentException - if no instance is found

    **See Also:**
    - [ProductLineItem.getOrderItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getorderitem)
    - [ShippingLineItem.getOrderItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getorderitem)


---

### getOrderNo()
- getOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order number for this order.

    **Returns:**
    - the order number for this order.


---

### getOrderToken()
- getOrderToken(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the token for this order. The order token is a string (length 32 bytes) associated
      with this one order. The order token is random. It reduces the capability of malicious
      users to access an order through guessing. Order token can be used to **further** validate order
      ownership, but should never be used to solely validate ownership. In addition, the storefront
      should ensure authentication and authorization. See the [Security Best Practices for Developers](https://help.salesforce.com/s/articleView?id=cc.b2c\_developer\_authentication\_and\_authorization.htm) for details.


    **Returns:**
    - the token for this order.


---

### getOriginalOrder()
- getOriginalOrder(): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Returns the original order associated with
      this order. The original order represents an order that was the
      first ancestor in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order1 is still the
      original representation of the order. If this order is the first
      ancestor, this method returns this order.


    **Returns:**
    - the order number of the original order associated with
      this order.


    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### getOriginalOrderNo()
- getOriginalOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order number of the original order associated with
      this order. The original order represents an order that was the
      first ancestor in a chain of orders.
      For example, if Order1 was replaced by Order2, Order2 is the current
      representation of the order and Order1 is the original representation
      of the order. If you replace Order2 with Order3, Order1 is still the
      original representation of the order. If this order is the first
      ancestor, this method returns the value of getOrderNo().


    **Returns:**
    - the order number of the original order associated with
      this order.


    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### getPaymentStatus()
- getPaymentStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the order payment status value.
      
      Possible values are [PAYMENT_STATUS_NOTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_notpaid), [PAYMENT_STATUS_PARTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_partpaid)
      or [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_paid).


    **Returns:**
    - Order payment status


---

### getPaymentTransaction()
- ~~getPaymentTransaction(): [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)~~
  - : Returns the payment transaction associated with this order.
      It is possible that there are multiple payment transactions
      associated with the order.  In this case, this method returns
      the transaction associated with the first PaymentInstrument
      returned by `getPaymentInstruments()`.


    **Returns:**
    - the payment transaction or null if there is no transaction.

    **Deprecated:**
**warning:** Use [LineItemCtnr.getPaymentInstruments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getpaymentinstruments)
to get the list of PaymentInstrument instances and then use
getPaymentTransaction() method on each PaymentInstrument to access
the individual transactions.

---

### getRefundedAmount()
- getRefundedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of the refunded amounts. The refunded amounts are
      calculated on the fly. Associate a payment refund for an [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md) with an [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
      using [Invoice.addRefundTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addrefundtransactionorderpaymentinstrument-money).


    **Returns:**
    - sum of refunded amounts


---

### getRemoteHost()
- getRemoteHost(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the IP address of the remote host from which the order was created.
      
      
      If the IP address was not captured for the order because order IP logging
      was disabled at the time the order was created, null will be returned.


    **Returns:**
    - The IP address of the remote host captured for the order or null


---

### getReplaceCode()
- getReplaceCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : If this order was replaced by another order,
      returns the value of the replace code. Otherwise.
      returns null.


    **Returns:**
    - the replace code


---

### getReplaceDescription()
- getReplaceDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If this order was replaced by another order,
      returns the value of the replace description. Otherwise
      returns null.


    **Returns:**
    - the value of the replace code or null.


---

### getReplacedOrder()
- getReplacedOrder(): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Returns the order that this order replaced or null. For example, if you
      have three orders where Order1 was replaced by Order2 and Order2 was
      replaced by Order3, calling this method on Order3 will return Order2.
      Similarly, calling this method on Order1 will return null as Order1 was
      the original order.


    **Returns:**
    - the order that replaced this order, or null.

    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### getReplacedOrderNo()
- getReplacedOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order number that this order replaced or null if this order
      did not replace an order. For example, if you have three orders
      where Order1 was replaced by Order2 and Order2 was replaced by Order3,
      calling this method on Order3 will return the order number for
      Order2. Similarly, calling this method on Order1 will return null as
      Order1 was the original order.


    **Returns:**
    - the order number of the order that this order replaced or null.

    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacementOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorderno)
    - [getReplacementOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacementorder)


---

### getReplacementOrder()
- getReplacementOrder(): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Returns the order that replaced this order, or null.

    **Returns:**
    - the order that replaced this order, or null.

    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)


---

### getReplacementOrderNo()
- getReplacementOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If this order was replaced by another order,
      returns the order number that replaced this order. Otherwise
      returns null.


    **Returns:**
    - the order that replaced this order, or null.

    **See Also:**
    - [getCurrentOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorderno)
    - [getCurrentOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getcurrentorder)
    - [getOriginalOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorderno)
    - [getOriginalOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getoriginalorder)
    - [getReplacedOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorderno)
    - [getReplacedOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreplacedorder)


---

### getReturn(String)
- getReturn(returnNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)
  - : Returns the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) associated with this order with the given returnNumber.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - returnNumber - the return number

    **Returns:**
    - the return associated with the given returnNumber


---

### getReturnCase(String)
- getReturnCase(returnCaseNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)
  - : Returns the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) associated with this order with the given returnCaseNumber.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - returnCaseNumber - the return case number

    **Returns:**
    - the return case associated with the given returnCaseNumber


---

### getReturnCaseItem(String)
- getReturnCaseItem(returnCaseItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
  - : Returns the [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) associated with this order with the given returnCaseItemID.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - returnCaseItemID - the ID

    **Returns:**
    - the return case item associated with the given returnCaseItemID


---

### getReturnCaseItems()
- getReturnCaseItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - return case items belonging to this order


---

### getReturnCases()
- getReturnCases(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - return cases belonging to this order


---

### getReturnItem(String)
- getReturnItem(returnItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)
  - : Returns the [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) associated with this order with the given ID.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - returnItemID - the ID

    **Returns:**
    - the return item associated with the given returnItemID


---

### getReturnItems()
- getReturnItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - return items belonging to this order


---

### getReturns()
- getReturns(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - returns belonging to this order


---

### getShippingOrder(String)
- getShippingOrder(shippingOrderNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)
  - : Returns the [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) associated with this order with the given shippingOrderNumber.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - shippingOrderNumber - the shipping order number

    **Returns:**
    - the shipping order associated with the given shippingOrderNumber


---

### getShippingOrderItem(String)
- getShippingOrderItem(shippingOrderItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Returns the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) associated with this order with the given shippingOrderItemID.
      The method returns `null` if no instance can be found.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - shippingOrderItemID - the ID

    **Returns:**
    - the shipping order item associated with the given shippingOrderItemID


---

### getShippingOrderItems()
- getShippingOrderItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - shipping order items belonging to this order


---

### getShippingOrders()
- getShippingOrders(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the collection of [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)s associated with this order.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - shipping orders belonging to this order


---

### getShippingStatus()
- getShippingStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the order shipping status.
      
      Possible values are [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_notshipped),
      [SHIPPING_STATUS_PARTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_partshipped) or [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_shipped).


    **Returns:**
    - Order shipping status


---

### getSourceCode()
- getSourceCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the source code stored with the order or `null` if no source code is attached to the order.

    **Returns:**
    - the source code stored with the order or `null` if no source code is attached to the order.


---

### getSourceCodeGroup()
- getSourceCodeGroup(): [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md)
  - : Returns the source code group attached to the order or `null` if no source code group is attached to
      the order.


    **Returns:**
    - the source code group attached to the order or `null` if no source code group is attached to
              the order.



---

### getSourceCodeGroupID()
- getSourceCodeGroupID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the source code group id stored with the order or `null` if no source code group is attached
      to the order.


    **Returns:**
    - the source code group id stored with the order or `null` if no source code group is attached
              to the order.



---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the status of the order.
      
      Possible values are:
      
      - [ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created)
      - [ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new)
      - [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open)
      - [ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed)
      - [ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)
      - [ORDER_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_failed)
      - [ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced)
      
      
      
      The order status usually changes when a process action is initiated. Most status changes have an action which
      needs to executed in order to end having the order in a specific order status. When an order is created with e.g.
      [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) the order status will be [ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created). The usual
      flow is that payment authorization will be added to the order. Once the order is considered as valid (payed,
      fraud checked, ...) the order gets placed. This can be done by calling
      [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder). The result of placing an order will be status
      [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open) (from a process standpoint [ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new) which has the same meaning).
      Status [ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced) is related to functionality
      [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder). [ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed) has no meaning by
      default but can be used by custom implementations but is a synonym for NEW/OPEN. Below you will find the most important status changes:
      
      
      
      | Status before | Action | Status after | Business meaning |
      | --- |--- |--- |--- |
      | - | [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) | CREATED | Order was created from a basket. |
      | CREATED | [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder) | OPEN/NEW | Order was considered as valid. Order can now be exported to 3rd party systems. |
      | CREATED | [OrderMgr.failOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder) | FAILED | Order was considered not valid. E.g. payment authorization was wrong or fraud check was not successful. |
      | OPEN/NEW | [OrderMgr.cancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#cancelorderorder) | CANCELLED | Order was cancelled. |
      | CANCELLED | [OrderMgr.undoCancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undocancelorderorder) | OPEN/NEW | Order was cancelled by mistake and this needs to be undone. |
      | FAILED | [OrderMgr.undoFailOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undofailorderorder) | CREATED | Order was failed by mistake and this needs to be undone. |
      
      
      Every status change will trigger a change in the order journal which is the base for GMV calculations.


    **Returns:**
    - Status of the order.

    **See Also:**
    - [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)


---

### isImported()
- isImported(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true`, if the order is imported and `false`
      otherwise.


    **Returns:**
    - true, if the order was imported, false otherwise.


---

### isTaxRoundedAtGroup()
- isTaxRoundedAtGroup(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Use this method to check if the Order was created with grouped taxation calculation.
      
      
      If the tax is rounded on group level, the tax is applied to the summed-up tax basis for each tax rate.


    **Returns:**
    - `true` if the Order was created with grouped taxation


---

### reauthorize()
- reauthorize(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Ensures that the order is authorized.
      
      
      Checks if the order is authorized by calling the hook
      [PaymentHooks.validateAuthorization(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#validateauthorizationorder). If the authorization
      is not valid it reauthorizes the order by calling the
      [PaymentHooks.reauthorize(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#reauthorizeorder).


    **Returns:**
    - the status of the operation, will be Status.OK if the order is
              authorized after this call



---

### removeRemoteHost()
- removeRemoteHost(): void
  - : Removes the IP address of the remote host if stored.
      
      
      If IP logging was enabled during order creation the IP address of the customer will be stored and can be
      retrieved using [getRemoteHost()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getremotehost).


    **See Also:**
    - [getRemoteHost()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getremotehost)


---

### setAffiliatePartnerID(String)
- setAffiliatePartnerID(affiliatePartnerID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the affiliate partner ID value.

    **Parameters:**
    - affiliatePartnerID - the affiliate partner ID value.


---

### setAffiliatePartnerName(String)
- setAffiliatePartnerName(affiliatePartnerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the affiliate partner name value.

    **Parameters:**
    - affiliatePartnerName - the affiliate partner name value.


---

### setCancelCode(String)
- setCancelCode(cancelCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the cancel code value.

    **Parameters:**
    - cancelCode - the cancel code value.


---

### setCancelDescription(String)
- setCancelDescription(cancelDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the description as to why the order was cancelled.

    **Parameters:**
    - cancelDescription - the description for why the order was cancelled.


---

### setConfirmationStatus(Number)
- setConfirmationStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the confirmation status value.
      
      Possible values are [CONFIRMATION_STATUS_NOTCONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_notconfirmed) or
      [CONFIRMATION_STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_confirmed).


    **Parameters:**
    - status - Order confirmation status


---

### setCustomer(Customer)
- setCustomer(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): void
  - : This method is used to associate the order object with the specified customer object.
      
      
      If the customer object represents a registered customer, the order will be assigned
      to this registered customer and the order's customer number
      ([LineItemCtnr.getCustomerNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getcustomerno)) will be updated.
      
      
      If the customer object represents an unregistered (anonymous) customer, the
      order will become an anonymous order and the order's customer number
      will be set to null.


    **Parameters:**
    - customer - The customer to be associated with the order.

    **Throws:**
    - NullArgumentException - If specified customer is null.


---

### setCustomerNo(String)
- setCustomerNo(customerNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer number associated with this order.
      
      
      Note it is recommended to use ([setCustomer(Customer)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcustomercustomer)) instead of this method. This method
      only sets the customer number and should be used with care as it does _not re-link the order with a customer
       profile</> object which can lead to an inconsistency! Ensure that the customer number used is not already taken
       by a different customer profile.


    **Parameters:**
    - customerNo - the customer number associated with this order.


---

### setCustomerOrderReference(String)
- setCustomerOrderReference(reference: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer-specific reference information for the order.

    **Parameters:**
    - reference - the customer-specific reference information for the order.


---

### setExportAfter(Date)
- setExportAfter(date: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the date after which an order can be exported.

    **Parameters:**
    - date - the date after which an order can be exported.


---

### setExportStatus(Number)
- setExportStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the export status of the order.
      
      Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_notexported), [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_exported),
      [EXPORT_STATUS_READY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_ready), and [EXPORT_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_failed).
      
      
      Setting the status to [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#export_status_exported) will also trigger the finalization of on order inventory
      transactions for this order meaning that all inventory transactions with type on order will be moved into final
      inventory transactions. This is only relevant when On Order Inventory is turned on for the inventory list ordered
      products are in.
      
      
      
      
      In case of an exception the current transaction is marked as rollback only.


    **Parameters:**
    - status - Order export status


---

### setExternalOrderNo(String)
- setExternalOrderNo(externalOrderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value of an external order number associated
      with this order


    **Parameters:**
    - externalOrderNo - the value of an external order number associated  with this order.


---

### setExternalOrderStatus(String)
- setExternalOrderStatus(status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the status of an external order associated
      with this order


    **Parameters:**
    - status - the status of the external order.


---

### setExternalOrderText(String)
- setExternalOrderText(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the text describing the external order.

    **Parameters:**
    - text - the text describing the external order.


---

### setInvoiceNo(String)
- setInvoiceNo(invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the invoice number for this Order.
      
      
      Notice that this value might be overwritten during order placement (e.g. with [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder)).


    **Parameters:**
    - invoiceNumber - the invoice number for this Order.

    **See Also:**
    - [getInvoiceNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoiceno)


---

### setOrderStatus(Number)
- ~~setOrderStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void~~
  - : Sets the order status.
      
      
      Use this method when using Order Post Processing such as the creation of [shipping  orders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md). The only supported values are [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open), [ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled). Setting the
      status will adjust the order item status when applicable (item status not SHIPPED or CANCELLED). Note that the
      order status and the status of the items are directly related and dependent on one another.
      
      
      See [OrderItem.setStatus(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#setstatusstring) for more information about possible status transitions.
      
      
      Warning: This method will _not_ undo coupon redemptions upon cancellation of an order. Re-opening such an
      order later with [OrderMgr.undoCancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undocancelorderorder) or [OrderItem.setStatus(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#setstatusstring)
      with [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open) will result in an additional application of the same coupon code which in turn
      might fail.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Parameters:**
    - status - the status to be set, use one of:                          <li>[ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open)</li>             <li>[ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)</li>             </ul>

    **Throws:**
    - IllegalArgumentException - on attempt to set an unsupported status value

    **Deprecated:**
**warning:** use [setStatus(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setstatusnumber) instead

---

### setPaymentStatus(Number)
- setPaymentStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the order payment status.
      
      Possible values are [PAYMENT_STATUS_NOTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_notpaid), [PAYMENT_STATUS_PARTPAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_partpaid)
      or [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#payment_status_paid).


    **Parameters:**
    - status - Order payment status


---

### setReplaceCode(String)
- setReplaceCode(replaceCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value of the replace code.

    **Parameters:**
    - replaceCode - the value of the replace code.


---

### setReplaceDescription(String)
- setReplaceDescription(replaceDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value of the replace description.

    **Parameters:**
    - replaceDescription - the value of the replace description.


---

### setShippingStatus(Number)
- setShippingStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the order shipping status value.
      
      Possible values are [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_notshipped),
      [SHIPPING_STATUS_PARTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_partshipped) or [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#shipping_status_shipped).


    **Parameters:**
    - status - Order shipping status


---

### setStatus(Number)
- setStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the status of the order.
      
      
      Possible values are:
      
      - [ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new)
      - [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open)
      - [ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed)
      - [ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)
      - [ORDER_STATUS_REPLACED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_replaced)
      
      This method does not support order statuses [ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created) or [ORDER_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_failed). Please
      use [OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder) or [OrderMgr.failOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder).
      
      
      Setting the order status to [ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled) will have the same effect as calling
      [OrderMgr.cancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#cancelorderorder). Setting a canceled order to [ORDER_STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_new),
      [ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open) or [ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed) will have the same effect as calling
      [OrderMgr.undoCancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undocancelorderorder). It is recommended to use the methods in
      [OrderMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md) directly to be able to do error processing with the return code.


    **Parameters:**
    - status - Order status

    **Throws:**
    - IllegalArgumentException - on attempt to set status CREATED or FAILED, or status transition while cancel              order or undo cancel order returns with an error code.


---

### trackOrderChange(String)
- trackOrderChange(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Note](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md)
  - : Tracks an order change.
      
      
      This adds a history entry to the order. Focus of history entries are changes through business logic, both custom
      and internal logic. Tracked order changes are read-only and can be accessed in the Business Manager order
      history. The following attributes of the created [history entry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md) are initialized:
      
      - [Note.getCreatedBy()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md#getcreatedby)gets the current user assigned
      - [Note.getCreationDate()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md#getcreationdate)gets the current date assigned
      
      
      
      
      
      This feature is intended to track important changes in custom order flow which should become visible in Business
      Manager's history tab. It is NOT intended as auditing feature for every change to an order. A warning will be
      produced after 600 notes are added to an order. The warning can be reviewed in Business Manager's Quota Status
      screen. Attempting to add a note to an order which already has 1000 notes results in an exception. Please bear in
      mind that internal changes, such as order status changes, also track changes. Avoid using this feature in
      recurring jobs which may re-process orders multiple times as the limit needs to be considered each time a change
      is tracked. The same limit on the number of notes added also applies when using method
      [LineItemCtnr.addNote(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#addnotestring-string) to add notes.


    **Parameters:**
    - text - the text of the history entry

    **Returns:**
    - the created history entry


---

<!-- prettier-ignore-end -->

<!-- document id=1b8bf437839500569b19335097a2fe89a02b864781bd44eb93b728e1cfda4737 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.OrderAddress.md -->

<!-- prettier-ignore-start -->
# Class OrderAddress

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)

The Address class represents a customer's address.


**Note:** this class allows access to sensitive personal and private information.
Pay attention to appropriate legal and regulatory requirements.



## Property Summary

| Property | Description |
| --- | --- |
| [address1](#address1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's first address. |
| [address2](#address2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's second address. |
| [city](#city): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Customer's City. |
| [companyName](#companyname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Customer's company name. |
| [countryCode](#countrycode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the customer's country code. |
| [firstName](#firstname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Customer's first name. |
| [fullName](#fullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns a concatenation of the Customer's first, middle,  and last names and it' suffix. |
| [jobTitle](#jobtitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's job title. |
| [lastName](#lastname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's last name. |
| [phone](#phone): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's phone number. |
| [postBox](#postbox): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's post box. |
| [postalCode](#postalcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's postal code. |
| [salutation](#salutation): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's salutation. |
| [secondName](#secondname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's second name. |
| [stateCode](#statecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's state. |
| [suffix](#suffix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's suffix. |
| [suite](#suite): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's suite. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's title. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAddress1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getaddress1)() | Returns the customer's first address. |
| [getAddress2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getaddress2)() | Returns the customer's second address. |
| [getCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getcity)() | Returns the Customer's City. |
| [getCompanyName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getcompanyname)() | Returns the Customer's company name. |
| [getCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getcountrycode)() | Returns the customer's country code. |
| [getFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getfirstname)() | Returns the Customer's first name. |
| [getFullName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getfullname)() | Returns a concatenation of the Customer's first, middle,  and last names and it' suffix. |
| [getJobTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getjobtitle)() | Returns the customer's job title. |
| [getLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getlastname)() | Returns the customer's last name. |
| [getPhone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getphone)() | Returns the customer's phone number. |
| [getPostBox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getpostbox)() | Returns the customer's post box. |
| [getPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getpostalcode)() | Returns the customer's postal code. |
| [getSalutation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getsalutation)() | Returns the customer's salutation. |
| [getSecondName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getsecondname)() | Returns the customer's second name. |
| [getStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getstatecode)() | Returns the customer's state. |
| [getSuffix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getsuffix)() | Returns the customer's suffix. |
| [getSuite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#getsuite)() | Returns the customer's suite. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#gettitle)() | Returns the customer's title. |
| [isEquivalentAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#isequivalentaddressobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if the specified address is equivalent to  this address. |
| [setAddress1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setaddress1string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's first address. |
| [setAddress2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setaddress2string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's second address. |
| [setCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setcitystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Customer's City. |
| [setCompanyName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setcompanynamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Customer's company name. |
| [setCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setcountrycodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Customer's country code. |
| [setFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setfirstnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Customer's first name. |
| [setJobTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setjobtitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's job title. |
| [setLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setlastnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's last name. |
| [setPhone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setphonestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's phone number. |
| [setPostBox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setpostboxstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's post box. |
| [setPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setpostalcodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's postal code. |
| ~~[setSaluation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setsaluationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the customer's salutation. |
| [setSalutation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setsalutationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's salutation. |
| [setSecondName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setsecondnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's second name. |
| [setStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setstatecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's state. |
| [setSuffix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setsuffixstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's suffix. |
| [setSuite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setsuitestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's suite. |
| [setTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#settitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's title. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### address1
- address1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first address.


---

### address2
- address2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second address.


---

### city
- city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Customer's City.


---

### companyName
- companyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Customer's company name.


---

### countryCode
- countryCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the customer's country code.


---

### firstName
- firstName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Customer's first name.


---

### fullName
- fullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns a concatenation of the Customer's first, middle,
      and last names and it' suffix.



---

### jobTitle
- jobTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's job title.


---

### lastName
- lastName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's last name.


---

### phone
- phone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's phone number.


---

### postBox
- postBox: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's post box.


---

### postalCode
- postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's postal code.


---

### salutation
- salutation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's salutation.


---

### secondName
- secondName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second name.


---

### stateCode
- stateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's state.


---

### suffix
- suffix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suffix.


---

### suite
- suite: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suite.


---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's title.


---

## Method Details

### getAddress1()
- getAddress1(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first address.

    **Returns:**
    - the first address value.


---

### getAddress2()
- getAddress2(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second address.

    **Returns:**
    - the second address value.


---

### getCity()
- getCity(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Customer's City.

    **Returns:**
    - the Customer's city.


---

### getCompanyName()
- getCompanyName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Customer's company name.

    **Returns:**
    - the company name.


---

### getCountryCode()
- getCountryCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the customer's country code.

    **Returns:**
    - the country code.


---

### getFirstName()
- getFirstName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Customer's first name.

    **Returns:**
    - the Customer first name.


---

### getFullName()
- getFullName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a concatenation of the Customer's first, middle,
      and last names and it' suffix.


    **Returns:**
    - a concatenation of the Customer's first, middle,
      and last names and it' suffix.



---

### getJobTitle()
- getJobTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's job title.

    **Returns:**
    - the job title.


---

### getLastName()
- getLastName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's last name.

    **Returns:**
    - the last name.


---

### getPhone()
- getPhone(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's phone number.

    **Returns:**
    - the phone number.


---

### getPostBox()
- getPostBox(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's post box.

    **Returns:**
    - the postBox.


---

### getPostalCode()
- getPostalCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's postal code.

    **Returns:**
    - the postal code.


---

### getSalutation()
- getSalutation(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's salutation.

    **Returns:**
    - the customer's salutation.


---

### getSecondName()
- getSecondName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second name.

    **Returns:**
    - the second name.


---

### getStateCode()
- getStateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's state.

    **Returns:**
    - the state.


---

### getSuffix()
- getSuffix(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suffix.

    **Returns:**
    - the suffix.


---

### getSuite()
- getSuite(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suite.

    **Returns:**
    - the customer's suite.


---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's title.

    **Returns:**
    - the title.


---

### isEquivalentAddress(Object)
- isEquivalentAddress(address: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the specified address is equivalent to
      this address. An equivalent address is an address whose
      core attributes contain the same values. The core attributes
      are:
      
      - address1
      - address2
      - city
      - companyName
      - countryCode
      - firstName
      - lastName
      - postalCode
      - postBox
      - stateCode


    **Parameters:**
    - address - the address to test.

    **Returns:**
    - true if the specified address is equivalent to
      this address, false otherwise.



---

### setAddress1(String)
- setAddress1(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's first address.

    **Parameters:**
    - value - The value to set.


---

### setAddress2(String)
- setAddress2(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's second address.

    **Parameters:**
    - value - The value to set.


---

### setCity(String)
- setCity(city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Customer's City.

    **Parameters:**
    - city - the Customer's city to set.


---

### setCompanyName(String)
- setCompanyName(companyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Customer's company name.

    **Parameters:**
    - companyName - the name of the company.


---

### setCountryCode(String)
- setCountryCode(countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Customer's country code.

    **Parameters:**
    - countryCode - the country code.


---

### setFirstName(String)
- setFirstName(firstName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Customer's first name.

    **Parameters:**
    - firstName - the customer's first  name to set.


---

### setJobTitle(String)
- setJobTitle(jobTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's job title.

    **Parameters:**
    - jobTitle - The job title to set.


---

### setLastName(String)
- setLastName(lastName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's last name.

    **Parameters:**
    - lastName - The last name to set.


---

### setPhone(String)
- setPhone(phoneNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's phone number. The length is restricted to 256 characters.

    **Parameters:**
    - phoneNumber - The phone number to set.


---

### setPostBox(String)
- setPostBox(postBox: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's post box.

    **Parameters:**
    - postBox - The post box to set.


---

### setPostalCode(String)
- setPostalCode(postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's postal code.

    **Parameters:**
    - postalCode - The postal code to set.


---

### setSaluation(String)
- ~~setSaluation(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the customer's salutation.

    **Parameters:**
    - value - the customer's salutation.

    **Deprecated:**
**warning:** Use [setSalutation(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md#setsalutationstring)

---

### setSalutation(String)
- setSalutation(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's salutation.

    **Parameters:**
    - value - the customer's salutation.


---

### setSecondName(String)
- setSecondName(secondName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's second name.

    **Parameters:**
    - secondName - The second name to set.


---

### setStateCode(String)
- setStateCode(state: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's state.

    **Parameters:**
    - state - The state to set.


---

### setSuffix(String)
- setSuffix(suffix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's suffix.

    **Parameters:**
    - suffix - The suffix to set.


---

### setSuite(String)
- setSuite(value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's suite. The length is restricted to 256 characters.

    **Parameters:**
    - value - the customer's suite.


---

### setTitle(String)
- setTitle(title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's title.

    **Parameters:**
    - title - The title to set.


---

<!-- prettier-ignore-end -->

<!-- document id=2b33e02d50da3dec9d1ddcfeff88b8804a24510c8958d1e0cafff2c2e7024697 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.OrderHistory.md -->

<!-- prettier-ignore-start -->
# Class OrderHistory

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.OrderHistory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md)

The class provides access to past orders of the customer.


**Note:** This class allows access to sensitive financial and cardholder data. Pay special attention to PCI DSS
v3. requirements 1, 3, 7, and 9. It also allows access to sensitive personal and private information. Pay attention
to appropriate legal and regulatory requirements related to this data.
**Note:** The following methods do not work with Salesforce Order Management orders.



## Property Summary

| Property | Description |
| --- | --- |
| [orderCount](#ordercount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of orders the customer has placed in the store. |
| [orders](#orders): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md) `(read-only)` | Retrieves the order history for the customer in the current storefront site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getOrderCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordercount)() | Returns the number of orders the customer has placed in the store. |
| [getOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getorders)() | Retrieves the order history for the customer in the current storefront site. |
| [getOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordersstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Retrieves the order history for the customer in the current storefront site. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### orderCount
- orderCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of orders the customer has placed in the store.
      
      
      If the customer is anonymous, this method always returns zero. If an active data record is available for this
      customer, the orders count is retrieved from that record, otherwise a real-time query is used to get the count.



---

### orders
- orders: [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md) `(read-only)`
  - : Retrieves the order history for the customer in the current storefront site.
      
      
      If the result exceeds 1000 orders, only the first 1000 orders are retrieved. Same as
      
      
      ```
      orderHistory.getOrders( null, "creationDate DESC" )
      ```
      
      
      
      
      
      It is strongly recommended to call `[SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)` on the returned
      SeekableIterator if not all of its elements are being retrieved. This will ensure the proper cleanup of system
      resources.


    **See Also:**
    - [getOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordersstring-string-object)


---

## Method Details

### getOrderCount()
- getOrderCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of orders the customer has placed in the store.
      
      
      If the customer is anonymous, this method always returns zero. If an active data record is available for this
      customer, the orders count is retrieved from that record, otherwise a real-time query is used to get the count.


    **Returns:**
    - the number of orders the customer has placed in the store.


---

### getOrders()
- getOrders(): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Retrieves the order history for the customer in the current storefront site.
      
      
      If the result exceeds 1000 orders, only the first 1000 orders are retrieved. Same as
      
      
      ```
      orderHistory.getOrders( null, "creationDate DESC" )
      ```
      
      
      
      
      
      It is strongly recommended to call `[SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)` on the returned
      SeekableIterator if not all of its elements are being retrieved. This will ensure the proper cleanup of system
      resources.


    **Returns:**
    - the orders

    **See Also:**
    - [getOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordersstring-string-object)


---

### getOrders(String, String, Object...)
- getOrders(query: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), params: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Retrieves the order history for the customer in the current storefront site.
      
      
      If the result exceeds 1000 orders, only the first 1000 orders are retrieved. Optionally, you can retrieve a subset
      of the orders by specifying a query. At maximum 3 expressions are allowed to be specified and no custom attribute
      expressions are allowed.
      
      
      
      
      It is strongly recommended to call `[SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)` on the returned
      SeekableIterator if not all of its elements are being retrieved. This will ensure the proper cleanup of system
      resources.
      
      
      Example:
      
      
      ```
                 var orderHistory : dw.customer.OrderHistory = customer.getOrderHistory();
                 var orders = orderHistory.getOrders("status = {0}", "creationDate DESC", dw.order.Order.ORDER_STATUS_NEW);
                 for each (var order : dw.order.Order in orders) {
                     // ... process orders
                 }
                 orders.close();
      ```


    **Parameters:**
    - query - optional query
    - sortString - optional sort string
    - params - optional parameters for the query

    **Returns:**
    - the orders


---

<!-- prettier-ignore-end -->

<!-- document id=4f0a31d11a836159dee65884b46b02e8644ec8fafd7285f1b229818834a14e04 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.OrderHooks.md -->

<!-- prettier-ignore-start -->
# Class OrderHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.OrderHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.OrderHooks.md)

This interface represents all script hooks that can be registered to customize the order logic. It contains the
extension points (hook names), and the functions that are called by each extension point. A function must be defined
inside a JavaScript source and must be exported. The script with the exported hook function must be located inside a
site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.


"hooks": "./hooks.json"


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
   {"name": "dw.order.createOrderNo", "script": "./orders.ds"},
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointCreateOrderNo](#extensionpointcreateorderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.createOrderNo" | The extension point name dw.order.createOrderNo. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.OrderHooks.md#createorderno)() | This hook is responsible for creating a new order number. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointCreateOrderNo

- extensionPointCreateOrderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.createOrderNo"
  - : The extension point name dw.order.createOrderNo.


---

## Method Details

### createOrderNo()
- createOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : This hook is responsible for creating a new order number.
      
      
      By default order numbers are generated by using [OrderMgr.createOrderSequenceNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createordersequenceno). Use this hook
      to customize the order number generation. E.g. a prefix or suffix could be added.
      
      ```
      exports.createOrderNo = function(){
          var orderSeqNo = OrderMgr.createOrderSequenceNo();
          var prefix = Site.getCurrent().getSiteId();
          return prefix + "_"+orderSeqNo;
      };
      ```
      
      If the method returns `null` or an blank string order number generation will fall
      back to [OrderMgr.createOrderSequenceNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createordersequenceno).
      
      
      The maximum length of the order number is 50 characters.


    **Returns:**
    - the order number


---

<!-- prettier-ignore-end -->

<!-- document id=54e430517edb18854786ffb771c5a1ba78a763d89b4a09f98b38e498a7398825 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.OrderItem.md -->

<!-- prettier-ignore-start -->
# Class OrderItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)

Defines _extensions_ to [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)s and
[ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)s belonging to an [order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).



The order-item can be accessed using
[ProductLineItem.getOrderItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getorderitem) or
[ShippingLineItem.getOrderItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getorderitem) - these methods return null
if the item is associated with a [basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) rather than
an [order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md). Alternative access is available using
[Order.getOrderItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderitemstring) by passing the
[itemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getitemid) used to identify the
order-item in for example export files. The
associated order-item can also be accessed from
[invoice-items](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md),
[shipping-order-items](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md),
[return-items](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) and [return-case-items](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
using [AbstractItem.getOrderItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitem).



The order-item provides an item-level [status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getstatus) and
[type](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#gettype), methods for accessing and creating associated items,
and methods used to [allocate  inventory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#allocateinventoryboolean) for [shipping-order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) creation.


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [STATUS_BACKORDER](#status_backorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BACKORDER" | Constant for Order Item Status BACKORDER |
| [STATUS_CANCELLED](#status_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED" | Constant for Order Item Status CANCELLED |
| [STATUS_CONFIRMED](#status_confirmed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED" | Constant for Order Item Status CONFIRMED |
| [STATUS_CREATED](#status_created): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREATED" | Constant for Order Item Status CREATED |
| [STATUS_NEW](#status_new): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW" | Constant for Order Item Status NEW |
| [STATUS_OPEN](#status_open): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OPEN" | Constant for Order Item Status OPEN |
| [STATUS_SHIPPED](#status_shipped): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED" | Constant for Order Item Status SHIPPED |
| [STATUS_WAREHOUSE](#status_warehouse): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WAREHOUSE" | Constant for Order Item Status WAREHOUSE |
| [TYPE_PRODUCT](#type_product): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRODUCT" | Constant for Order Item Type PRODUCT |
| [TYPE_SERVICE](#type_service): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SERVICE" | Constant for Order Item Type SERVICE |

## Property Summary

| Property | Description |
| --- | --- |
| [appeasedAmount](#appeasedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Sum of amounts appeased for this item, calculated by iterating over  invoice items associated with the item. |
| [capturedAmount](#capturedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Sum of amounts captured for this item, calculated by iterating over  invoice items associated with the item. |
| [invoiceItems](#invoiceitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all invoice items associated with this item, each  [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md) will belong to a different  [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md), which can also be accessed using  [Order.getInvoices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoices) or [Order.getInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoicestring). |
| [itemID](#itemid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The itemID used to identify the OrderItem. |
| [lineItem](#lineitem): [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md) `(read-only)` | Returns the line item which is being extended by this instance. |
| [refundedAmount](#refundedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Sum of amounts refunded for this item, calculated by iterating over  invoice items associated with the item. |
| [returnCaseItems](#returncaseitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all return case items associated with this item,  each [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) will belong to a different  [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), which can also be accessed using  [Order.getReturnCases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncases) or [Order.getReturnCase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncasestring). |
| [returnedQuantity](#returnedquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | The quantity returned, dynamically sum of quantities held by associated  ReturnItems. |
| ~~[shippingOrderItem](#shippingorderitem): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)~~ `(read-only)` | The last added non-cancelled shipping order item if one exists, otherwise `null`. |
| [shippingOrderItems](#shippingorderitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s created for this item. |
| [splitItems](#splititems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all split [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)s associated with this item. |
| [splitSourceItem](#splitsourceitem): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)` | Returns the split source item associated with this item, if existing. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Gets the order item status.<br/>  The possible values are:  <ul>  <li>[STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_new)</li>  <li>[STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_open)</li>  <li>[STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_backorder)</li>  <li>[STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_confirmed)</li>  <li>[STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_warehouse)</li>  <li>[STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_shipped)</li>  <li>[STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_cancelled)</li>  <ul> |
| [type](#type): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | Returns the type of line item with which this instance is associated, one  of  <ul>  <li>SERVICE (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem) returns a  [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)</li>  <li>PRODUCT (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem) returns a  [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)</li>  </ul> |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [allocateInventory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#allocateinventoryboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Please note that this method is disabled by default. |
| [getAppeasedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getappeasedamount)() | Sum of amounts appeased for this item, calculated by iterating over  invoice items associated with the item. |
| [getCapturedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getcapturedamount)() | Sum of amounts captured for this item, calculated by iterating over  invoice items associated with the item. |
| [getInvoiceItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getinvoiceitems)() | Returns all invoice items associated with this item, each  [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md) will belong to a different  [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md), which can also be accessed using  [Order.getInvoices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoices) or [Order.getInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoicestring). |
| [getItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getitemid)() | The itemID used to identify the OrderItem. |
| [getLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem)() | Returns the line item which is being extended by this instance. |
| [getRefundedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getrefundedamount)() | Sum of amounts refunded for this item, calculated by iterating over  invoice items associated with the item. |
| [getReturnCaseItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getreturncaseitems)() | Returns all return case items associated with this item,  each [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) will belong to a different  [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), which can also be accessed using  [Order.getReturnCases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncases) or [Order.getReturnCase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncasestring). |
| [getReturnedQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getreturnedquantity)() | The quantity returned, dynamically sum of quantities held by associated  ReturnItems. |
| ~~[getShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getshippingorderitem)()~~ | The last added non-cancelled shipping order item if one exists, otherwise `null`. |
| [getShippingOrderItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getshippingorderitems)() | Returns a collection of the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s created for this item. |
| [getShippingOrderItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getshippingorderitemsboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns a collection of the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s created for this item. |
| [getSplitItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplititems)() | Returns a collection of all split [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)s associated with this item. |
| [getSplitSourceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplitsourceitem)() | Returns the split source item associated with this item, if existing. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getstatus)() | Gets the order item status.<br/>  The possible values are:  <ul>  <li>[STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_new)</li>  <li>[STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_open)</li>  <li>[STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_backorder)</li>  <li>[STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_confirmed)</li>  <li>[STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_warehouse)</li>  <li>[STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_shipped)</li>  <li>[STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_cancelled)</li>  <ul> |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#gettype)() | Returns the type of line item with which this instance is associated, one  of  <ul>  <li>SERVICE (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem) returns a  [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)</li>  <li>PRODUCT (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem) returns a  [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)</li>  </ul> |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#setstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the status of the order item, use one of the values documented in [getStatus()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getstatus). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### STATUS_BACKORDER

- STATUS_BACKORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BACKORDER"
  - : Constant for Order Item Status BACKORDER


---

### STATUS_CANCELLED

- STATUS_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED"
  - : Constant for Order Item Status CANCELLED


---

### STATUS_CONFIRMED

- STATUS_CONFIRMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED"
  - : Constant for Order Item Status CONFIRMED


---

### STATUS_CREATED

- STATUS_CREATED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREATED"
  - : Constant for Order Item Status CREATED


---

### STATUS_NEW

- STATUS_NEW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW"
  - : Constant for Order Item Status NEW


---

### STATUS_OPEN

- STATUS_OPEN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OPEN"
  - : Constant for Order Item Status OPEN


---

### STATUS_SHIPPED

- STATUS_SHIPPED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED"
  - : Constant for Order Item Status SHIPPED


---

### STATUS_WAREHOUSE

- STATUS_WAREHOUSE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WAREHOUSE"
  - : Constant for Order Item Status WAREHOUSE


---

### TYPE_PRODUCT

- TYPE_PRODUCT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRODUCT"
  - : Constant for Order Item Type PRODUCT


---

### TYPE_SERVICE

- TYPE_SERVICE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SERVICE"
  - : Constant for Order Item Type SERVICE


---

## Property Details

### appeasedAmount
- appeasedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Sum of amounts appeased for this item, calculated by iterating over
      invoice items associated with the item.



---

### capturedAmount
- capturedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Sum of amounts captured for this item, calculated by iterating over
      invoice items associated with the item.



---

### invoiceItems
- invoiceItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all invoice items associated with this item, each
      [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md) will belong to a different
      [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md), which can also be accessed using
      [Order.getInvoices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoices) or [Order.getInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoicestring).



---

### itemID
- itemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The itemID used to identify the OrderItem. Note this is
      not a UUID, it is created internally when the OrderItem
      instance is created, and is typically used within export files to
      identify the item.



---

### lineItem
- lineItem: [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md) `(read-only)`
  - : Returns the line item which is being extended by this instance.


---

### refundedAmount
- refundedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Sum of amounts refunded for this item, calculated by iterating over
      invoice items associated with the item.



---

### returnCaseItems
- returnCaseItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all return case items associated with this item,
      each [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) will belong to a different
      [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), which can also be accessed using
      [Order.getReturnCases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncases) or [Order.getReturnCase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncasestring).



---

### returnedQuantity
- returnedQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : The quantity returned, dynamically sum of quantities held by associated
      ReturnItems.



---

### shippingOrderItem
- ~~shippingOrderItem: [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)~~ `(read-only)`
  - : The last added non-cancelled shipping order item if one exists, otherwise `null`.
      
      
      Multiple shipping order items that are not in status [ShippingOrderItem.STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_cancelled)
      can exist for one OrderItem, for example if the OrderItem has been split for shipping purposes.
      The method returns `null` if no non-cancelled shipping order item exists.



---

### shippingOrderItems
- shippingOrderItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s created for this item.
      ShippingOrder items represents the whole or part of this item which could
      be delivered, and belong to a shipping order.
      Note that the cancelled shipping order items are returned too.
      This method is equivalent to [getShippingOrderItems(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getshippingorderitemsboolean)
      called with parameter `true`.



---

### splitItems
- splitItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all split [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)s associated with this item. Inverse relation to [getSplitSourceItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplitsourceitem).
      
      
      Split order items are created when
      
      - creating a [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)for a [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), see [ShippingOrder.createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity)  - splitting an existing [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md), see [ShippingOrderItem.split(Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#splitquantity)with a specified quantity less than the existing quantity of the associated [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md). In this case the associated [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)is split by creating a new [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)and associating a new [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)with this item. The new [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)receives the specified quantity and the quantity of the item is set to the remaining quantity. All split items are associated to their originating item via    the "split source item" association.



---

### splitSourceItem
- splitSourceItem: [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)`
  - : Returns the split source item associated with this item, if existing. Inverse relation to [getSplitItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplititems).
      
      
      A split source item is associated after the successful creation of a split item with a quantity less than the existing quantity of the item to split.
      For details see [getSplitItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplititems).



---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the order item status.
      
      The possible values are:
      
      - [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_new)
      - [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_open)
      - [STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_backorder)
      - [STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_confirmed)
      - [STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_warehouse)
      - [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_shipped)
      - [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_cancelled)



---

### type
- type: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : Returns the type of line item with which this instance is associated, one
      of
      
      - SERVICE (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem)returns a  [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
      - PRODUCT (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem)returns a  [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)



---

## Method Details

### allocateInventory(Boolean)
- allocateInventory(partialAllocation: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Please note that this method is disabled by default. Please contact support for enabling it.
      
      
      Attempts to allocate inventory for the item and returns the quantity that could be allocated or `null`
      if no allocation was possible.
      
      
      All [option product line items](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getoptionproductlineitems) are allocated with
      their parent. Note that for items with option product line items no partial allocation is possible. That means
      the partialAllocation parameter will in this case always be considered as `false`


    **Parameters:**
    - partialAllocation -              <li>`true` accept a partial allocation as a result. Partial allocation is only possible             when no option product line items are included,</li>             <li>`false` only full allocation will be used, partial allocation will be released             automatically</li>             </ul>

    **Returns:**
    - 
      - successful: the newly allocated quantity
      - failed: `null`



---

### getAppeasedAmount()
- getAppeasedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Sum of amounts appeased for this item, calculated by iterating over
      invoice items associated with the item.


    **Returns:**
    - Sum of amounts refunded for this item


---

### getCapturedAmount()
- getCapturedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Sum of amounts captured for this item, calculated by iterating over
      invoice items associated with the item.


    **Returns:**
    - Sum of amounts captured for this item


---

### getInvoiceItems()
- getInvoiceItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all invoice items associated with this item, each
      [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md) will belong to a different
      [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md), which can also be accessed using
      [Order.getInvoices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoices) or [Order.getInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoicestring).


    **Returns:**
    - invoice items associated with this item


---

### getItemID()
- getItemID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The itemID used to identify the OrderItem. Note this is
      not a UUID, it is created internally when the OrderItem
      instance is created, and is typically used within export files to
      identify the item.


    **Returns:**
    - the itemID of the OrderItem


---

### getLineItem()
- getLineItem(): [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
  - : Returns the line item which is being extended by this instance.

    **Returns:**
    - the line item associated with this instance


---

### getRefundedAmount()
- getRefundedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Sum of amounts refunded for this item, calculated by iterating over
      invoice items associated with the item.


    **Returns:**
    - Sum of amounts refunded for this item


---

### getReturnCaseItems()
- getReturnCaseItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all return case items associated with this item,
      each [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) will belong to a different
      [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), which can also be accessed using
      [Order.getReturnCases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncases) or [Order.getReturnCase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncasestring).


    **Returns:**
    - return case items associated with this item


---

### getReturnedQuantity()
- getReturnedQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : The quantity returned, dynamically sum of quantities held by associated
      ReturnItems.


    **Returns:**
    - quantity returned, the sum of quantities held by associated
              ReturnItems



---

### getShippingOrderItem()
- ~~getShippingOrderItem(): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)~~
  - : The last added non-cancelled shipping order item if one exists, otherwise `null`.
      
      
      Multiple shipping order items that are not in status [ShippingOrderItem.STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_cancelled)
      can exist for one OrderItem, for example if the OrderItem has been split for shipping purposes.
      The method returns `null` if no non-cancelled shipping order item exists.


    **Returns:**
    - the last not cancelled shipping order item or `null`


---

### getShippingOrderItems()
- getShippingOrderItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s created for this item.
      ShippingOrder items represents the whole or part of this item which could
      be delivered, and belong to a shipping order.
      Note that the cancelled shipping order items are returned too.
      This method is equivalent to [getShippingOrderItems(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getshippingorderitemsboolean)
      called with parameter `true`.


    **Returns:**
    - collection of the shipping order items created for this item


---

### getShippingOrderItems(Boolean)
- getShippingOrderItems(includeCancelled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of the [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)s created for this item.
      ShippingOrder items represent the whole or part of this item which could
      be delivered, and belong to a shipping order.
      Depending on the `includeCancelled` parameter the cancelled shipping order
      items will be returned or not.


    **Parameters:**
    - includeCancelled -              <li>`true` all shipping order items, including the             cancelled, created for this item will be returned</li>             <li>`false` only non-cancelled shipping order items             created for this item will be returned</li>             </ul>

    **Returns:**
    - collection of the shipping order items created for this item


---

### getSplitItems()
- getSplitItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all split [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)s associated with this item. Inverse relation to [getSplitSourceItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplitsourceitem).
      
      
      Split order items are created when
      
      - creating a [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)for a [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), see [ShippingOrder.createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity)  - splitting an existing [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md), see [ShippingOrderItem.split(Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#splitquantity)with a specified quantity less than the existing quantity of the associated [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md). In this case the associated [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)is split by creating a new [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)and associating a new [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)with this item. The new [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)receives the specified quantity and the quantity of the item is set to the remaining quantity. All split items are associated to their originating item via    the "split source item" association.


    **Returns:**
    - the split order items associated with this item


---

### getSplitSourceItem()
- getSplitSourceItem(): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)
  - : Returns the split source item associated with this item, if existing. Inverse relation to [getSplitItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplititems).
      
      
      A split source item is associated after the successful creation of a split item with a quantity less than the existing quantity of the item to split.
      For details see [getSplitItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getsplititems).


    **Returns:**
    - the split source item or `null`


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the order item status.
      
      The possible values are:
      
      - [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_new)
      - [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_open)
      - [STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_backorder)
      - [STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_confirmed)
      - [STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_warehouse)
      - [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_shipped)
      - [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_cancelled)


    **Returns:**
    - the status


---

### getType()
- getType(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the type of line item with which this instance is associated, one
      of
      
      - SERVICE (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem)returns a  [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
      - PRODUCT (method [getLineItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getlineitem)returns a  [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)


    **Returns:**
    - the type of order item, one of [TYPE_PRODUCT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#type_product) or
              [TYPE_SERVICE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#type_service).



---

### setStatus(String)
- setStatus(status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the status of the order item, use one of the values documented in [getStatus()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getstatus).
      
      
      If the order item has a related shipping order item (see [getShippingOrderItem()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getshippingorderitem)) the status of the
      shipping order item will be adjusted to the same status. Setting the status of an order item might also change
      the status of the related order. The following rules apply in top-down order:
      
      - all items [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_cancelled)- order status is [Order.ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)
      - at least one item in status [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_shipped)and all other items are [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_cancelled)order  status is [Order.ORDER_STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_completed)
      - at least one item in status [STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_created), [STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_open), [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_new), [STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_backorder)- order status is [Order.ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open), order confirmation status  is [Order.CONFIRMATION_STATUS_NOTCONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_notconfirmed)
      - other combinations will have only items in [STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_confirmed), [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_cancelled)and  [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#status_shipped)- order status is [Order.ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open), order confirmation status is  [Order.CONFIRMATION_STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#confirmation_status_confirmed)


    **Parameters:**
    - status - status string matching one of the values for status


---

<!-- prettier-ignore-end -->

<!-- document id=c444959311f8dd0602c861b335e4417dae4654b8d07a0e3874970672589652d4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.OrderMgr.md -->

<!-- prettier-ignore-start -->
# Class OrderMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.OrderMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md)



Provides static helper methods for managing orders.




Pipelet GetOrder and methods provided to access orders such as [getOrder(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#getorderstring) and
[searchOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersstring-string-object) can be limited by the site preference 'Limit Storefront Order
Access'. An insecure order access occurs in a storefront session when all of the following are true:

- The current storefront session isn’t the session in which the order was created.
- The session customer doesn’t match the order customer.
- The order status isn’t CREATED.

When an order is accessed in an insecure manner:

- If the preference is ACTIVE, the action is disallowed and a SecurityException with a message  beginning 'Unauthorized access to order' is thrown.
- If the preference is NOT ACTIVE, a SecurityException with a message beginning 'Unauthorized  access to order' is logged as an error.

In addition, the storefront should ensure the shopper is properly authenticated and authorized to read
or modify the content of an order object. For more information, see [Access Control](https://help.salesforce.com/s/articleView?id=cc.b2c\_developer\_authentication\_and\_authorization.htm).


Don’t use dw.order.OrderMgr.searchOrder methods or [processOrders(Function, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#processordersfunction-string-object)
immediately after creating or updating an order. The order search index updates asynchronously, typically within seconds but occasionally longer depending on search service load, so it
might not include very recent changes. Instead, do one of the following:

- In the same request, pass the dw.order.Order object reference to the followup logic.
- For storefront use cases, especially when passing the order reference to a third party, use the  order token for security by using [getOrder(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#getorderstring-string).

When implementing order history functionality, don't use the search or query methods in this class. Instead, use
[OrderHistory.getOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordersstring-string-object).



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [cancelOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#cancelorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  This method cancels an order. |
| static [createOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | <p>  This method creates an order based on a basket. |
| static [createOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket-string)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  This method functions the same as [createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket), but allows the optional specification of  an `orderNo`. |
| static [createOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderno)() | <p>  Creates an order number. |
| static [createOrderSequenceNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createordersequenceno)() | <p>  Creates an order number. |
| static [createShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createshippingordersorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  Triggers the shipping order creation for an order. |
| static [describeOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#describeorder)() | <p>  Returns the meta data for Orders. |
| ~~static [failOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md))~~ | <p>  This method fails an unplaced order and is usually called if payment could not be authorized. |
| static [failOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | <p>  This method fails an unplaced order and is usually called if payment could not be authorized. |
| static [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#getorderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Returns the order with the specified order number. |
| static [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#getorderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Resolves an order using the orderNumber and orderToken. |
| static [placeOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  This method places an order and is usually called after payment has been authorized. |
| static [processOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#processordersfunction-string-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Executes a user-definable function on a set of orders. |
| ~~static [queryOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#queryorderstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | <p>  Searches for a single order instance. |
| ~~static [queryOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#queryordersmap-string)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | <p>  Searches for order instances. |
| ~~static [queryOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#queryordersstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | <p>  Searches for order instances. |
| static [searchOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchorderstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Searches for a single order instance. |
| static [searchOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersmap-string)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Searches for order instances. |
| static [searchOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Searches for order instances. |
| static [undoCancelOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undocancelorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  This method is used to turn a CANCELLED order into an OPEN order. |
| static [undoFailOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#undofailorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  This method is used to turn a FAILED order into a CREATED order. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### cancelOrder(Order)
- static cancelOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      This method cancels an order. Only orders in status OPEN, NEW, or COMPLETED can be cancelled.
      
      
      
      
      Setting of cancel code and cancel description can be done by calling
      `[Order.setCancelCode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcancelcodestring)` and `[Order.setCancelDescription(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setcanceldescriptionstring)`. \*
      If the order contains product or gift certificate line items associated with product list items, records of the
      purchase of the product list items will be removed.
      
      
      
      
      Inventory transactions and coupon redemptions associated with the order will be rolled back.
      
      
      
      
      It is important to consider that this method will cancel orders with gift certificate line items.
      
      
      
      
      If an order has any active post-processing objects (e.g. shipping orders, returns, appeasements), then it cannot
      be cancelled directly. Its status is set automatically, based on the statuses of its post-processing objects. To
      cancel such an order, you must cancel all related post-processing objects.
      
      
      
      
      If your B2C Commerce instance is integrated with Order Management, then you manage order statuses in Order
      Management. Use Order Management API endpoints.


    **Parameters:**
    - order - the order to be cancelled

    **Returns:**
    - Status 'OK' or 'ERROR'


---

### createOrder(Basket)
- static createOrder(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : 
      
      This method creates an order based on a basket. If successful, the new order will be in status
      [Order.ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created). The basket will be removed from the session and marked for removal.
      
      
      
      
      This method throws an APIException with type 'CreateOrderException' if any of the following conditions are
      encountered:
      
      - any of the totals (net, gross, tax) of the basket is N/A
      - any of the product items is not available (this takes previously reserved items into account)
      - any campaign-based coupon in the basket is invalid (see [CouponLineItem.isValid()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md#isvalid)
      - the basket represents an order being edited, but the order has already been replaced by another order
      - the basket represents an order being edited, but the customer associated with the original order is not the  same as the current customer
      
      
      
      
      
      The method removes all empty shipments from the basket before creating the order. A shipment is said to be empty
      if all of the following are true:
      
      - it contains no product or gift certificate line items
      - all total prices (net, gross, tax) are 0.0
      
      
      
      
      
      This method decrements inventory for all products contained in the order. A previous call to
      [Basket.reserveInventory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventory) is unnecessary and discouraged within the same request. The method
      takes any items with reserved inventory into account, allowing an early reservation of items, e.g. at the
      beginning of the checkout process. As described above, an APIException is thrown if any item is not available.
      
      
      
      
      If the basket contains product or gift certificate line items associated with product list items, the method
      updates the purchased quantity of the product list items; see
      [ProductListItem.getPurchasedQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getpurchasedquantity).
      
      
      
      
      The system generates an order number via hook [OrderHooks.createOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.OrderHooks.md#createorderno). If no hook is
      registered for the endpoint, the number is generated by calling [createOrderSequenceNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createordersequenceno). The format of
      the number is based on the Order Number scheme defined in the Sequence Numbers preference configured for the site
      or organization. The number is guaranteed to be unique, but is not guaranteed to be sequential. It can be higher
      or lower than a previously created number. As a result, sorting orders by order number is not guaranteed to sort
      them in their order of creation.
      
      
      
      
      This method must not be used with the **ReserveInventoryForOrder** pipelet or
      [Basket.reserveInventory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventory) in the same request.
      
      
      
      
      When an order is created, search results don't include it until the next asynchronous update of the order search
      index. See [OrderMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md).
      
      
      
      
      Please note that this method might result in an order with a different customer ID than the originating
      registered customer attached to the session. This happens if a registered customer logs in with the "RememberMe"
      flag set to `true`, but is later logged out (either explicitly, or automatically via session
      expiration) before calling this method. This is due to the internal order creation logic, which creates a new
      guest customer and attaches it to the order in such cases. To avoid this situation, have your custom code verify
      that the customer is authenticated before it calls this method.
      
      
      
      
      Usage:
      
      
      
      
      
      
      ```
      var basket : Basket; // known
      try
      {
        var order : Order = OrderMgr.createOrder(basket);
      }
      catch (e if e instanceof APIException && e.type === 'CreateOrderException')
      {
        // handle e
      }
      ```


    **Parameters:**
    - basket - basket to create an order for

    **Returns:**
    - a new order

    **Throws:**
    - dw.order.CreateOrderException - indicates the order could not be created


---

### createOrder(Basket, String)
- static createOrder(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : 
      
      This method functions the same as [createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket), but allows the optional specification of
      an `orderNo`. The `orderNo` must be unique within the context of a site.
      
      
      
      
      If the `orderNo` is not specified, the behavior is the same as that of
      [createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket). In that case, the system generates an order number via hook
      [OrderHooks.createOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.OrderHooks.md#createorderno). If no hook is registered for the endpoint, the number is
      generated by calling [createOrderSequenceNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createordersequenceno). The format of the number is based on the Order Number
      scheme defined in the Sequence Numbers preference configured for the site or organization. The number is
      guaranteed to be unique, but is not guaranteed to be sequential. It can be higher or lower than a previously
      created number. As a result, sorting orders by order number is not guaranteed to sort them in their order of
      creation.
      
      
      
      
      This method must not be used with the **ReserveInventoryForOrder** pipelet or
      [Basket.reserveInventory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventory) in the same request.
      
      
      
      
      When an order is created, search results don't include it until the next asynchronous update of the order search
      index. See [OrderMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md).
      
      
      
      
      Please note that this method might result in an order with a different customer ID than the originating
      registered customer attached to the session. This happens if a registered customer logs in with the "RememberMe"
      flag set to `true`, but is later logged out (either explicitly, or automatically via session
      expiration) before calling this method. This is due to the internal order creation logic, which creates a new
      guest customer and attaches it to the order in such cases. To avoid this situation, have your custom code verify
      that the customer is authenticated before it calls this method.
      
      
      
      
      Usage:
      
      
      
      
      
      
      ```
      var basket : Basket; // known
      var orderNo : String; // known
      try
      {
        var order : Order = OrderMgr.createOrder(basket, orderNo);
      }
      catch (e if e instanceof APIException && e.type === 'CreateOrderException')
      {
        // handle e
      }
      ```


    **Parameters:**
    - basket - basket to create an order for
    - orderNo - optional order number; if `null` is specified, an order number is generated

    **Returns:**
    - a new order

    **Throws:**
    - dw.order.CreateOrderException - indicates the order could not be created


---

### createOrderNo()
- static createOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Creates an order number.
      
      
      
      
      The order number is created via hook [OrderHooks.createOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.OrderHooks.md#createorderno). If no hook is registered
      for the endpoint, the number is generated by calling [createOrderSequenceNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createordersequenceno). The format of the number
      is based on the Order Number scheme defined in the Sequence Numbers preference configured for the site or
      organization.
      
      
      
      
      The number is guaranteed to be unique, but is not guaranteed to be sequential. It can be higher or lower than a
      previously created number. As a result, sorting orders by order number is not guaranteed to sort them in their
      order of creation.


    **Returns:**
    - an available order number

    **Throws:**
    - CreateException - if order number creation failed


---

### createOrderSequenceNo()
- static createOrderSequenceNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Creates an order number.
      
      
      
      
      The format of the number is based on the Order Number scheme defined in the Sequence Numbers preference
      configured for the site or organization.
      
      
      
      
      The number is guaranteed to be unique, but is not guaranteed to be sequential. It can be higher or lower than a
      previously created number. As a result, sorting orders by order number is not guaranteed to sort them in their
      order of creation.


    **Returns:**
    - an available order number

    **Throws:**
    - CreateException - if order number creation failed


---

### createShippingOrders(Order)
- static createShippingOrders(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Triggers the shipping order creation for an order.
      
      
      
      
      Must be run outside of a transaction. Will call hooks of the shipping order creation process, which are:
      
      - [ShippingOrderHooks.extensionPointPrepareCreateShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointpreparecreateshippingorders)
      - [ShippingOrderHooks.extensionPointCreateShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointcreateshippingorders)
      - [ShippingOrderHooks.extensionPointAfterStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointafterstatuschange)
      - [ShippingOrderHooks.extensionPointNotifyStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointnotifystatuschange)
      
      
      
      
      
      As a result, zero, one, or multiple [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)s are created.
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw an exception if accessed.
      Activation needs preliminary approval by Product Management. Please contact support in this case. Existing
      customers using these APIs are not affected by this change and can use the APIs until further notice.


    **Parameters:**
    - order - the order to run the shipping order creation for

    **Returns:**
    - Status 'OK' or 'ERROR' with an error message


---

### describeOrder()
- static describeOrder(): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : 
      
      Returns the meta data for Orders.


    **Returns:**
    - the meta data for Orders.


---

### failOrder(Order)
- ~~static failOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)~~
  - : 
      
      This method fails an unplaced order and is usually called if payment could not be authorized. The specified Order
      must be in status CREATED, and will be set to status FAILED.
      
      
      
      
      Inventory transactions and coupon redemptions associated with the Order will be rolled back.
      
      
      
      
      If the order is failed in the same session in which it was created, the basket will be reopened such that it can
      be used for a subsequent order.


    **Parameters:**
    - order - the order to be placed

    **Returns:**
    - Status 'OK' or 'ERROR' with an error message

    **Deprecated:**
**warning:** Please use [failOrder(Order, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean) instead.

---

### failOrder(Order, Boolean)
- static failOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), reopenBasketIfPossible: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      This method fails an unplaced order and is usually called if payment could not be authorized. The specified Order
      must be in status CREATED, and will be set to status FAILED.
      
      
      
      
      Inventory transactions and coupon redemptions associated with the Order will be rolled back.
      
      
      
      
      This method does not alter shipments. Note that [createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) removes empty shipments
      before creating the order, so a reopened basket might be missing shipments that existed before. If the removed
      shipment was the default ("me"), the fallback default is the shipment with the lowest ID. See
      [LineItemCtnr.getDefaultShipment()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#getdefaultshipment) and [Shipment.isDefault()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#isdefault).
      
      
      
      
      A basket can only be reopened if no other basket for the customer exists at the moment of the call to
      `failOrder`, since a customer is limited to 1 storefront basket at a time. If, after order creation, a
      call was made to [BasketMgr.getCurrentOrNewBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#getcurrentornewbasket) or pipelet GetBasket with parameter Create=true, then
      a new basket has been created, and `failOrder` cannot reopen the basket the order was created with. If
      a basket is reopened, it always masks sensitive information (e.g., credit card number), because during order
      creation, basket payment information is permanently masked.


    **Parameters:**
    - order - the order to be placed
    - reopenBasketIfPossible - reopen the basket if it still exists and limit for number of baskets is not reached

    **Returns:**
    - Status 'OK' or 'ERROR' with an error message. Status detail basket contains the reopened basket, if it
              has been reopened successfully.



---

### getOrder(String)
- static getOrder(orderNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : 
      
      Returns the order with the specified order number. Order access in the storefront can be limited; see
      the class description. Use [getOrder(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#getorderstring-string) instead for secure access in a storefront session.
      
      
      
      
      If Limit Storefront Order Access site preference is enabled, this method throws an exception when an
      insecure access is attempted (refer to the conditions of insecure access in the description of OrderMgr
      class). Use [getOrder(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#getorderstring-string) instead.


    **Parameters:**
    - orderNumber - the order number of the order to retrieve

    **Returns:**
    - Order for the specified order number

    **Throws:**
    - SecurityException - thrown when the Limit Storefront Order Access preference is enabled and the order is insecurely accessed

    **See Also:**
    - [getOrder(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#getorderstring-string)


---

### getOrder(String, String)
- static getOrder(orderNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), orderToken: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : 
      
      Resolves an order using the orderNumber and orderToken.
      
      
      
      
      The order token is generated during order creation in a secure way that is designed to reduce the
      possibility of unauthorized access. You can retrieve the token via ([Order.getOrderToken()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getordertoken).
      
      
      
      
      This version of the getOrder method doesn’t return an exception when the Limit Storefront Order
      Access site preference is enabled. Best security practice is to always enable this preference, and to use
      this method when appropriate.
      
      
      
      
      You should always use this method in the following cases.
      
      - Integration use cases (such as asynchronous payment processing)
      - When resolving orders from links (for example, order confirmation)
      - Storefront use cases


    **Parameters:**
    - orderNumber - the order number of the order to retrieve
    - orderToken - the order token of the order to retrieve

    **Returns:**
    - Order for the specified order number. null is returned if order is not found by number or token
              doesn’t correspond to the order found



---

### placeOrder(Order)
- static placeOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      This method places an order and is usually called after payment has been authorized. The specified order must be
      in status CREATED, and will be set to status NEW.
      
      
      
      
      If the order contains product or gift certificate line items associated with product list items, records of the
      purchase of the product list items will be made. For example, if the basket contains an item added from a gift
      registry, the purchase history of the respective gift registry item is updated.
      
      
      
      
      The order will count toward product and customer active data.
      
      
      
      
      Placing an order leads to the generation of shipment numbers for all shipments and the invoice number of the
      order. See [Shipment.getShipmentNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshipmentno) and [Order.getInvoiceNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getinvoiceno). This is done
      using sequences.


    **Parameters:**
    - order - the order to be placed

    **Returns:**
    - Status 'OK' or 'ERROR' with an error message


---

### processOrders(Function, String, Object...)
- static processOrders(processFunction: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : 
      
      Executes a user-definable function on a set of orders. This method is intended to be used in batch processes and
      jobs, since it allows efficient processing of large result sets (which might take a while to process). First, a
      search with the given parameters is executed. Then the given function is executed once for each order of the
      search result. The order is handed over as the only parameter to this function.
      
      
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality. The callback function will be supplied with a single argument of type 'Order'. When the function
      defines additional arguments, they will be undefined when called. When the method doesn't define any argument, it
      will be called anyway. Error during execution of the callback will be logged, and execution will continue with
      the next element from the result set. This method can be used as in this example (which counts the number of
      orders):
      
      
      
      
      
      
      ```
              var count=0;
              function callback(order: Order)
              {
                  count++;
                  dw.system.Logger.debug("order found: "+order.documentNo)
              }
             OrderMgr.processOrders(callback, "buyerno=1");
             dw.system.Logger.debug("found "+count+" orders for buyerno 1");
      ```


    **Parameters:**
    - processFunction - the function to execute for each order
    - queryString - the query string to use when searching for an order.
    - args - the query string arguments.


---

### queryOrder(String, Object...)
- ~~static queryOrder(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)~~
  - : 
      
      Searches for a single order instance. Order access in the storefront can be limited; see the class description.
      
      
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality.
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom-defined attributes, the prefix 'custom' is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      
      
      Note that some system attributes are not queryable by default, regardless of the actual value type code.
      
      
      
      
      The following **operators** are supported in a condition:
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number, and Date types only
      - `>`Greater than - Integer, Number, and Date types only
      - `<=`Less or equals than - Integer, Number, and Date types only
      - `>=`Greater or equals than - Integer, Number, and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search (e.g. `custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only; use to support case-insensitive  queries (e.g. `custom.country ILIKE 'usa'`); also supports wildcards for substring matching
      
      
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR', and 'NOT', and nested using parentheses, e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1', and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      
      
      If there is more than one object matching the specified query criteria, the result is not deterministic. In order
      to retrieve a single object from a sorted result set, it is recommended to use the following code:
      `queryOrders("", "custom.myAttr asc", null).first()`. The method `first()` returns only the
      next element and closes the iterator. **
       
      
       
      
       **This method is deprecated and will be removed in a future release.**
      One of the following methods should be used instead:
      [searchOrder(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchorderstring-object), [searchOrders(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersmap-string), and
      [searchOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersstring-string-object) to search for orders and
      [processOrders(Function, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#processordersfunction-string-object) to search for and process orders in jobs.


    **Parameters:**
    - queryString - the query string that is used to locate the order.
    - args - one or more arguments to apply.

    **Returns:**
    - the order that was found when executing the `queryString`.

    **Deprecated:**
**warning:** Please use [searchOrder(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchorderstring-object) instead.

---

### queryOrders(Map, String)
- ~~static queryOrders(queryAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)~~
  - : 
      
      Searches for order instances. Order access in the storefront can be limited; see the class description.
      
      
      
      
      The search can be configured with a map, which converts key-value pairs into a query expression. The key-value
      pairs are turned into a sequence of '=' or 'like' conditions, which are combined with AND statements. When
      implementing order history functionality, don't use the search or query methods in this class. Instead, use
      [OrderHistory.getOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordersstring-string-object).
      
      
      
      
      Example:
      
      
      
      
      A map with the key/value pairs: _'name'/'tom\*', 'age'/66_ will be converted as follows:
      `"name like 'tom*' and age = 66"`
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom-defined attributes, the prefix 'custom' is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      
      
      Note that some system attributes are not queryable by default, regardless of the actual value type code.
      
      
      
      
      The **sorting** parameter is optional and may contain a comma-separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). The default
      sorting direction is ascending, if no direction was specified.
      
      
      
      
      Example: `age desc, name`
      
      
      
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      
      
      It is strongly recommended to call the `[SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)` on the returned
      SeekableIterator if not all of its elements are being retrieved. This will ensure the proper cleanup of system
      resources.
      
      
      
      
      **This method is deprecated and will be removed in a future release.**
      One of the following methods should be used instead:
      [searchOrder(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchorderstring-object), [searchOrders(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersmap-string), and
      [searchOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersstring-string-object) to search for orders and
      [processOrders(Function, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#processordersfunction-string-object) to search for and process orders in jobs.


    **Parameters:**
    - queryAttributes - a set of key-value pairs that define the query.
    - sortString - an optional sorting, or null if no sorting is necessary.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)

    **Deprecated:**
**warning:** Please use [searchOrders(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersmap-string) instead.

---

### queryOrders(String, String, Object...)
- ~~static queryOrders(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)~~
  - : 
      
      Searches for order instances. Order access in the storefront can be limited; see the class description.
      
      
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality. When implementing order history functionality, don't use the search or query methods in this
      class. Instead, use [OrderHistory.getOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordersstring-string-object).
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom-defined attributes, the prefix 'custom' is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      
      
      Note that some system attributes are not queryable by default, regardless of the actual value type code.
      
      
      
      
      The following **operators** are supported in a condition:
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number, and Date types only
      - `>`Greater than - Integer, Number, and Date types only
      - `<=`Less or equals than - Integer, Number, and Date types only
      - `>=`Greater or equals than - Integer, Number, and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search (e.g. `custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only; use to support case-insensitive  queries (e.g. `custom.country ILIKE 'usa'`); also supports wildcards for substring matching
      
      
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR', and 'NOT', and nested using parentheses, e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1', and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      
      
      The **sorting** parameter is optional and may contain a comma-separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). The default
      sorting direction is ascending, if no direction was specified.
      
      
      
      
      Example: `age desc, name`
      
      
      
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      
      
      Sometimes it is desired to get all instances of a specified type with a special sorting condition. This can be
      easily done by providing the 'type' of the custom object and the 'sortString' in combination with an empty
      'queryString', e.g. `queryOrders("sample", "", "custom.myAttr asc")`.
      
      
      
      
      It is strongly recommended to call `[SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)` on the returned
      SeekableIterator if not all of its elements are being retrieved. This will ensure the proper cleanup of system
      resources.
      
      
      
      
      **This method is deprecated and will be removed in a future release.**
      One of the following methods should be used instead:
      [searchOrder(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchorderstring-object), [searchOrders(Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersmap-string), and
      [searchOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersstring-string-object) to search for orders, and
      [processOrders(Function, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#processordersfunction-string-object) to search for and process orders in jobs.


    **Parameters:**
    - queryString - the actual query.
    - sortString - an optional sorting, or null if no sorting is necessary.
    - args - one or more arguments for the query string.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)

    **Deprecated:**
**warning:** Please use [searchOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#searchordersstring-string-object) instead.

---

### searchOrder(String, Object...)
- static searchOrder(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : 
      
      Searches for a single order instance. Order access in the storefront can be limited; see the class description.
      
      
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality.
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom-defined attributes the prefix 'custom' is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      
      
      Note that some system attributes are not queryable by default, regardless of the actual value type code.
      
      
      
      
      The following **operators** are supported in a condition:
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number, and Date types only
      - `>`Greater than - Integer, Number, and Date types only
      - `<=`Less or equals than - Integer, Number, and Date types only
      - `>=`Greater or equals than - Integer, Number, and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search (e.g. `custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only; use to support case-insensitive  queries (e.g. `custom.country ILIKE 'usa'`), also supports wildcards for substring matching
      
      
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR', and 'NOT', and nested using parentheses, e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1', and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`.
      
      
      
      
      If there is more than one object matching the specified query criteria, the result is not deterministic. In order
      to retrieve a single object from a sorted result set, it is recommended to use the following code:
      `queryOrders("", "custom.myAttr asc", null).first()`. The method `first()` returns only the
      next element and closes the iterator.
      
      
      
      
      If the order search API is configured to use the new Search Service, these differences apply:
      
      - Search may match and return documents with missing (NULL) values in search fields, depending on  how the query is structured, potentially leading to broader result sets. For example, a query like  `custom.searchField != "some value"`also returns documents where `custom.searchField`is NULL — whereas in relational databases, such documents are excluded.
      - Wildcards are filtered from the query (\*, %, +) and replaced by spaces
      - LIKE and ILIKE queries are executed as fulltext queries (working on whole words), not as substring  searches
      - LIKE queries are always case-insensitive
      - Using logical operators may change the execution of LIKE/ILIKE clauses to exact string comparison, depending  on how they are combined
      - Using logical operators may result in degraded performance, depending on how they are combined
           
      
      
      
      
      Order search index updates are asynchronous, triggered only by committing changes to the underlying system.


    **Parameters:**
    - queryString - the query string that is used to locate the order.
    - args - one or more arguments to apply.

    **Returns:**
    - the order that was found when executing the `queryString`.


---

### searchOrders(Map, String)
- static searchOrders(queryAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      
      Searches for order instances. Order access in the storefront can be limited; see the class description.
      
      
      
      
      The search can be configured with a map, which converts key-value pairs into a query expression. The key-value
      pairs are turned into a sequence of '=' or 'like' conditions, which are combined with AND statements.
      
      
      
      
      Example:
      
      
      
      
      A map with the key/value pairs: _'name'/'tom\*', 'age'/66_ will be converted as follows:
      `"name like 'tom*' and age = 66"` Note that wildcards are not supported by Search Service.
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom-defined attributes, the prefix 'custom' is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      
      
      Note that some system attributes are not queryable by default, regardless of the actual value type code.
      
      
      
      
      The **sorting** parameter is optional and may contain a comma-separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). The default
      sorting direction is ascending, if no direction was specified.
      
      
      
      
      Example: `age desc, name`
      
      
      
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      
      
      It is strongly recommended to call `[SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)` on the returned
      SeekableIterator if not all of its elements are being retrieved. This will ensure the proper cleanup of system
      resources.
      
      
      
      
      If the order search API is configured to use the new Search Service, these differences apply:
      
      - Search may match and return documents with missing (NULL) values in search fields, depending on  how the query is structured, potentially leading to broader result sets. For example, a query like  `custom.searchField != "some value"`also returns documents where `custom.searchField`is NULL — whereas in relational databases, such documents are excluded.
      - Wildcards are filtered from the query (\*, %, +) and replaced by spaces
      - LIKE and ILIKE queries are executed as fulltext queries (working on whole words), not as substring  searches
      - LIKE queries are always case-insensitive
      - Using logical operators may change the execution of LIKE/ILIKE clauses to exact string comparison, depending  on how they are combined
      - Using logical operators may result in degraded performance, depending on how they are combined
      - The result is limited to a maximum of 1000 orders
      
      
      
      
      
      Order search index updates are asynchronous, triggered only by committing changes to the underlying system.


    **Parameters:**
    - queryAttributes - a set of key-value pairs that define the query.
    - sortString - an optional sorting or null if no sorting is necessary.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### searchOrders(String, String, Object...)
- static searchOrders(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      
      Searches for order instances. Order access in the storefront can be limited; see the class description.
      
      
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality. When implementing order history functionality, don't use the search or query methods in this
      class. Instead, use [OrderHistory.getOrders(String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md#getordersstring-string-object).
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom-defined attributes the prefix 'custom' is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      
      
      Note that some system attributes are not queryable by default, regardless of the actual value type code.
      
      
      
      
      The following **operators** are supported in a condition:
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number, and Date types only
      - `>`Greater than - Integer, Number, and Date types only
      - `<=`Less or equals than - Integer, Number, and Date types only
      - `>=`Greater or equals than - Integer, Number, and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search (e.g. `custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only; use to support case-insensitive  queries (e.g. `custom.country ILIKE 'usa'`); also supports wildcards for substring matching
      
      Note that wildcards are not supported by Search Service.
      
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR', and 'NOT', and nested using parentheses, e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1', and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`.
      
      
      
      
      The **sorting** parameter is optional and may contain a comma-separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). The default
      sorting direction is ascending, if no direction was specified.
      
      
      
      
      Example: `age desc, name`
      
      
      
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      
      
      Sometimes it is desired to get all instances of a specified type with a special sorting condition. This can be
      easily done by providing the 'type' of the custom object and the 'sortString' in combination with an empty
      'queryString', e.g. `queryOrders("sample", "", "custom.myAttr asc")`.
      
      
      
      
      It is strongly recommended to call `[SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)` on the returned
      SeekableIterator if not all of its elements are being retrieved. This will ensure the proper cleanup of system
      resources.
      
      
      
      
      If the order search API is configured to use the new Search Service, these differences apply:
      
      - Search may match and return documents with missing (NULL) values in search fields, depending on  how the query is structured, potentially leading to broader result sets. For example, a query like  `custom.searchField != "some value"`also returns documents where `custom.searchField`is NULL — whereas in relational databases, such documents are excluded.
      - Wildcards are filtered from the query (\*, %, +) and replaced by spaces
      - LIKE and ILIKE queries are executed as fulltext queries (working on whole words), not as substring  searches
      - LIKE queries are always case-insensitive
      - Using logical operators may change the execution of LIKE/ILIKE clauses to exact string comparison, depending  on how they are combined
      - Using logical operators may result in degraded performance, depending on how they are combined
      - The result is limited to a maximum of 1000 orders
      
      
      
      
      
      Order search index updates are asynchronous, triggered only by committing changes to the underlying system.


    **Parameters:**
    - queryString - the actual query.
    - sortString - an optional sorting or null if no sorting is necessary.
    - args - one or more arguments for the query string.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### undoCancelOrder(Order)
- static undoCancelOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      This method is used to turn a CANCELLED order into an OPEN order.
      
      
      
      
      The specified order must be a cancelled order ([Order.ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)). The method will
      reserve inventory for all product line items, and create redemptions for all coupons. If successful, the status
      of the order will be changed to [Order.ORDER_STATUS_OPEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_open). If the order contains product or gift
      certificate line items associated with product list items, records of the purchase of the product list items will
      be recreated.
      
      
      
      
      If the undoCancelOrder call fails, the transaction is marked as ‘rollback only’ – all changes in the associated
      transaction will no longer be committed.
      
      
      
      
      Possible error status codes are:
      
      - [OrderProcessStatusCodes.COUPON_INVALID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#coupon_invalid)- coupon is not active anymore or maximum amount of  redemptions is reached
      - [OrderProcessStatusCodes.ORDER_NOT_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#order_not_cancelled)- order is not in status  [Order.ORDER_STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_cancelled)
      - [OrderProcessStatusCodes.INVENTORY_RESERVATION_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#inventory_reservation_failed)- Inventory reservation for the order failed. In  cases when availability is too low then undoCancel or undoFail results in a reservation failure. This can be  avoided using the order site preferences to specifically allow overselling. See order site preferences under  "Constraints for Undoing Failed/Cancelled Orders".


    **Parameters:**
    - order - the order on which to undo the cancel [cancelOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#cancelorderorder)

    **Returns:**
    - Status 'OK' or 'ERROR' with one of the error codes described above


---

### undoFailOrder(Order)
- static undoFailOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      This method is used to turn a FAILED order into a CREATED order.
      
      
      
      
      The specified order must be a failed order ([Order.ORDER_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_failed)). The method will reserve
      inventory for all product line items, and create redemptions for all coupons. If successful, the status of the
      order will be changed to [Order.ORDER_STATUS_CREATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_created).
      
      
      
      
      If the undoFailOrder call fails, the transaction is marked as ‘rollback only’ – all changes in the associated
      transaction will no longer be committed.
      
      
      
      
      Possible error status codes are:
      
      - [OrderProcessStatusCodes.COUPON_INVALID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#coupon_invalid)- coupon is not active anymore or maximum amount of  redemptions is reached
      - [OrderProcessStatusCodes.ORDER_NOT_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#order_not_failed)- order is not in status  [Order.ORDER_STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#order_status_failed)
      - [OrderProcessStatusCodes.INVENTORY_RESERVATION_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md#inventory_reservation_failed)- Inventory reservation for the order failed. In  cases when availability is too low then undoCancel or undoFail results in a reservation failure. This can be  avoided using the order site preferences to specifically allow overselling. See order site preferences under  "Constraints for Undoing Failed/Cancelled Orders".


    **Parameters:**
    - order - the order on which to undo the fail [failOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder)

    **Returns:**
    - Status 'OK' or 'ERROR' with one of the error codes described above


---

<!-- prettier-ignore-end -->

<!-- document id=0d726b533b34a1af50dc56490691bebcdfc0e76fd0a260b76aaefea8c7140302 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.OrderPaymentInstrument.md -->

<!-- prettier-ignore-start -->
# Class OrderPaymentInstrument

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md)
        - [dw.order.PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md)
          - [dw.order.OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)

Represents any payment instrument used to pay orders, such as credit card
or bank transfer. The object defines standard methods for credit card
payment, and can be extended by attributes appropriate for other
payment methods.



## Property Summary

| Property | Description |
| --- | --- |
| [bankAccountDriversLicense](#bankaccountdriverslicense): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the driver's license associated with a bank account if the calling  context meets the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS. |
| [bankAccountNumber](#bankaccountnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the account number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS. |
| [capturedAmount](#capturedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of the captured amounts. |
| [creditCardNumber](#creditcardnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the de-crypted creditcard number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current authenticated customer is referenced by the basket or order, and the current protocol is HTTPS. |
| [paymentTransaction](#paymenttransaction): [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md) `(read-only)` | Returns the Payment Transaction for this Payment Instrument or null. |
| [refundedAmount](#refundedamount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of the refunded amounts. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md#getbankaccountdriverslicense)() | Returns the driver's license associated with a bank account if the calling  context meets the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS. |
| [getBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md#getbankaccountnumber)() | Returns the account number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS. |
| [getCapturedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md#getcapturedamount)() | Returns the sum of the captured amounts. |
| [getCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md#getcreditcardnumber)() | Returns the de-crypted creditcard number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the method call happens in the context of a storefront request and  the current authenticated customer is referenced by the basket or order, and the current protocol is HTTPS. |
| [getPaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md#getpaymenttransaction)() | Returns the Payment Transaction for this Payment Instrument or null. |
| [getRefundedAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md#getrefundedamount)() | Returns the sum of the refunded amounts. |

### Methods inherited from class PaymentInstrument

[getBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicense), [getBankAccountDriversLicenseLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicenselastdigits), [getBankAccountDriversLicenseLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicenselastdigitsnumber), [getBankAccountDriversLicenseStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicensestatecode), [getBankAccountHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountholder), [getBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumber), [getBankAccountNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumberlastdigits), [getBankAccountNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumberlastdigitsnumber), [getBankRoutingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankroutingnumber), [getCreditCardExpirationMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardexpirationmonth), [getCreditCardExpirationYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardexpirationyear), [getCreditCardHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardholder), [getCreditCardIssueNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardissuenumber), [getCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumber), [getCreditCardNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumberlastdigits), [getCreditCardNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumberlastdigitsnumber), [getCreditCardToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardtoken), [getCreditCardType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardtype), [getCreditCardValidFromMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardvalidfrommonth), [getCreditCardValidFromYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardvalidfromyear), [getEncryptedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedbankaccountdriverslicensestring-string), [getEncryptedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedbankaccountnumberstring-string), [getEncryptedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedcreditcardnumberstring-certificateref), [getEncryptedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedcreditcardnumberstring-string), [getGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificatecode), [getGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificateid), [getMaskedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountdriverslicense), [getMaskedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountdriverslicensenumber), [getMaskedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountnumber), [getMaskedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountnumbernumber), [getMaskedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedcreditcardnumber), [getMaskedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedcreditcardnumbernumber), [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedgiftcertificatecode), [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedgiftcertificatecodenumber), [getPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getpaymentmethod), [isCreditCardExpired](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#iscreditcardexpired), [isPermanentlyMasked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked), [setBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountdriverslicensestring), [setBankAccountDriversLicenseStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountdriverslicensestatecodestring), [setBankAccountHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountholderstring), [setBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountnumberstring), [setBankRoutingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankroutingnumberstring), [setCreditCardExpirationMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardexpirationmonthnumber), [setCreditCardExpirationYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardexpirationyearnumber), [setCreditCardHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardholderstring), [setCreditCardIssueNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardissuenumberstring), [setCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardnumberstring), [setCreditCardToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardtokenstring), [setCreditCardType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardtypestring), [setCreditCardValidFromMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardvalidfrommonthnumber), [setCreditCardValidFromYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardvalidfromyearnumber), [setGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setgiftcertificatecodestring), [setGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setgiftcertificateidstring)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bankAccountDriversLicense
- bankAccountDriversLicense: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the driver's license associated with a bank account if the calling
      context meets the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS.  
      - If the method call happens in the context of the business manager and the  current user has permission to the Orders module.  
      
      Otherwise, the method throws an exception.



---

### bankAccountNumber
- bankAccountNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the account number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS.  
      - If the method call happens in the context of the business manager and the  current user has permissions to the Orders module.  
      
      Otherwise, the method throws an exception.



---

### capturedAmount
- capturedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of the captured amounts. The captured amounts
      are calculated on the fly. Associate a payment capture for an Payment Instrument with an Invoice
      using Invoice method addCaptureTransaction.



---

### creditCardNumber
- creditCardNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the de-crypted creditcard number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current authenticated customer is referenced by the basket or order, and the current protocol is HTTPS.  
      - If the customer is anonymous, and the order references this customer, and the protocol is secure and  the order status is CREATED.  
      - If the method call happens in the context of the business manager and the  current user has the permission to manage orders.  
      - If the payment information has not been masked as a result of the data retention security policy  for the site.  
      
      Otherwise, the method returns the masked credit card number.



---

### paymentTransaction
- paymentTransaction: [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md) `(read-only)`
  - : Returns the Payment Transaction for this Payment Instrument or null.


---

### refundedAmount
- refundedAmount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of the refunded amounts. The refunded amounts
      are calculated on the fly. Associate a payment refund for an Payment Instrument with an Invoice
      using Invoice method addRefundTransaction.



---

## Method Details

### getBankAccountDriversLicense()
- getBankAccountDriversLicense(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the driver's license associated with a bank account if the calling
      context meets the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS.  
      - If the method call happens in the context of the business manager and the  current user has permission to the Orders module.  
      
      Otherwise, the method throws an exception.


    **Returns:**
    - the driver's license number if the calling context meets the
      necessary criteria.



---

### getBankAccountNumber()
- getBankAccountNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the account number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current customer is identical to the customer related to the basket  or order, and the current protocol is HTTPS.  
      - If the method call happens in the context of the business manager and the  current user has permissions to the Orders module.  
      
      Otherwise, the method throws an exception.


    **Returns:**
    - the account number if the calling context meets the
      necessary criteria.



---

### getCapturedAmount()
- getCapturedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of the captured amounts. The captured amounts
      are calculated on the fly. Associate a payment capture for an Payment Instrument with an Invoice
      using Invoice method addCaptureTransaction.


    **Returns:**
    - sum of captured amounts


---

### getCreditCardNumber()
- getCreditCardNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the de-crypted creditcard number if the calling context meets
      the following criteria: 
      
      
      - If the method call happens in the context of a storefront request and  the current authenticated customer is referenced by the basket or order, and the current protocol is HTTPS.  
      - If the customer is anonymous, and the order references this customer, and the protocol is secure and  the order status is CREATED.  
      - If the method call happens in the context of the business manager and the  current user has the permission to manage orders.  
      - If the payment information has not been masked as a result of the data retention security policy  for the site.  
      
      Otherwise, the method returns the masked credit card number.


    **Returns:**
    - the de-crypted creditcard number if the calling context meets the
      necessary criteria.



---

### getPaymentTransaction()
- getPaymentTransaction(): [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)
  - : Returns the Payment Transaction for this Payment Instrument or null.

    **Returns:**
    - the Payment Transaction for this Payment Instrument or null.


---

### getRefundedAmount()
- getRefundedAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of the refunded amounts. The refunded amounts
      are calculated on the fly. Associate a payment refund for an Payment Instrument with an Invoice
      using Invoice method addRefundTransaction.


    **Returns:**
    - sum of refunded amounts


---

<!-- prettier-ignore-end -->

<!-- document id=98ebcffc85e9c24ebe45148a89284febe310ea85ac8468318b4451f52aa341e9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.OrderProcessStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class OrderProcessStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.OrderProcessStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md)

Contains constants representing different status codes
for interacting with an order, such as cancelling
or editing an order.



## Constant Summary

| Constant | Description |
| --- | --- |
| [COUPON_INVALID](#coupon_invalid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_INVALID" | Indicates that a coupon in the order is not valid. |
| [INVENTORY_RESERVATION_FAILED](#inventory_reservation_failed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INVENTORY_RESERVATION_FAILED" | Indicates that no inventory could be reserved for the order. |
| [ORDER_ALREADY_CANCELLED](#order_already_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_CANCELLED" | Indicates that the order could not be used because  it has already been cancelled. |
| [ORDER_ALREADY_EXPORTED](#order_already_exported): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_EXPORTED" | Indicates that the order could not be used because it  has already been exported. |
| [ORDER_ALREADY_FAILED](#order_already_failed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_FAILED" | Indicates that the order could not be used because  it has already been failed. |
| [ORDER_ALREADY_REPLACED](#order_already_replaced): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_REPLACED" | Indicates that the order could not be used because  it has already been replaced. |
| [ORDER_CONTAINS_GC](#order_contains_gc): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCEL_ORDER_GC" | Indicates that the order could not be used because it  contains gift certificates. |
| [ORDER_NOT_CANCELLED](#order_not_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_NOT_CANCELLED" | Indicates that the order could not be used because  it is not cancelled. |
| [ORDER_NOT_FAILED](#order_not_failed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_NOT_FAILED" | Indicates that the order could not be used because  it has not been failed. |
| [ORDER_NOT_PLACED](#order_not_placed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_NOT_PLACED" | Indicates that the order could not be used because  it has not been placed. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [OrderProcessStatusCodes](#orderprocessstatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### COUPON_INVALID

- COUPON_INVALID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_INVALID"
  - : Indicates that a coupon in the order is not valid.


---

### INVENTORY_RESERVATION_FAILED

- INVENTORY_RESERVATION_FAILED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INVENTORY_RESERVATION_FAILED"
  - : Indicates that no inventory could be reserved for the order.


---

### ORDER_ALREADY_CANCELLED

- ORDER_ALREADY_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_CANCELLED"
  - : Indicates that the order could not be used because
      it has already been cancelled.



---

### ORDER_ALREADY_EXPORTED

- ORDER_ALREADY_EXPORTED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_EXPORTED"
  - : Indicates that the order could not be used because it
      has already been exported.



---

### ORDER_ALREADY_FAILED

- ORDER_ALREADY_FAILED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_FAILED"
  - : Indicates that the order could not be used because
      it has already been failed.



---

### ORDER_ALREADY_REPLACED

- ORDER_ALREADY_REPLACED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_REPLACED"
  - : Indicates that the order could not be used because
      it has already been replaced.



---

### ORDER_CONTAINS_GC

- ORDER_CONTAINS_GC: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCEL_ORDER_GC"
  - : Indicates that the order could not be used because it
      contains gift certificates.



---

### ORDER_NOT_CANCELLED

- ORDER_NOT_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_NOT_CANCELLED"
  - : Indicates that the order could not be used because
      it is not cancelled.



---

### ORDER_NOT_FAILED

- ORDER_NOT_FAILED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_NOT_FAILED"
  - : Indicates that the order could not be used because
      it has not been failed.



---

### ORDER_NOT_PLACED

- ORDER_NOT_PLACED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER_NOT_PLACED"
  - : Indicates that the order could not be used because
      it has not been placed.



---

## Constructor Details

### OrderProcessStatusCodes()
- OrderProcessStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=8e8c35c8a2e1690978ba76fe53346d42037f8f294fb8e2883c2eee188f082882 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.OrganizationPreferences.md -->

<!-- prettier-ignore-start -->
# Class OrganizationPreferences

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.system.OrganizationPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.OrganizationPreferences.md)

OrganizationPreferences is a container for custom global (i.e.
organization-level) attributes. The object corresponds with system object
definition "OrganizationPreferences". It has no system attributes and exists
only as a place for merchants to define custom attributes which need to be
available to all of their sites.


An instance is obtained by calling [System.getPreferences()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getpreferences).
Once an instance of the container is obtained, it is possible to read/write
organization preference values by using the usual syntax for
[ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md) instances. For example:

```
var orgPrefs : OrganizationPreferences = dw.system.System.getPreferences();
var myOrgPrefValue : String = orgPrefs.getCustom()["myOrgPref"];
```



**Note:** this class allows access to sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.


Commerce Cloud Digital defines many organization-level preferences, relating to
locale, timezone, geolocations, etc, which can be managed within the
"Global Preferences" module of the Business Manager, but these preferences
are not accessible through this object.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=d472ff5d520f9e07c63e1cff63309aa4baf54c80be31ef9fcea36067eb7890c9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.OutputStream.md -->

<!-- prettier-ignore-start -->
# Class OutputStream

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.OutputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.OutputStream.md)

The class represent a stream of bytes that can be written from the
application. The OutputStream itself doesn't provide any methods
to write the data. Instead the OutputStream can be chained with
other classes like a XMLStreamWriter to write data.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.OutputStream.md#close)() | Closes the output stream. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### close()
- close(): void
  - : Closes the output stream.


---

<!-- prettier-ignore-end -->

<!-- document id=bb15ec5f7fec09ebea8913e2faa744ca9aedc35fec87eda23c2c8707b810eb02 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.Page.md -->

<!-- prettier-ignore-start -->
# Class Page

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)



This class represents a page designer managed page. A page comprises of
multiple regions that hold components, which themselves again can have
regions holding components, i.e. spanning a hierarchical tree of components.




Using

- [PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)
- [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)

a page can be rendered. As such page implements a render function for creating
render output the render function of the page itself will also want to access
its various properties like the SEO title etc.




Apart from rendering to markup a page can also be serialized, i.e. transformed
into a json string using

- [PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)
- [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)


**See Also:**
- [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)
- [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)
- [PageMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md)


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the id of this page. |
| [aspectTypeID](#aspecttypeid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the aspect type of the page. |
| [classificationFolder](#classificationfolder): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)` | Returns the classification [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) associated with this page. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of this page. |
| [folders](#folders): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all folders to which this page is assigned. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of this page. |
| [pageDescription](#pagedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the SEO description of this page. |
| [pageKeywords](#pagekeywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the SEO keywords of this page. |
| [pageTitle](#pagetitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the SEO title of this page. |
| [searchWords](#searchwords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the search words of the page used for the search index. |
| [typeID](#typeid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type id of this page. |
| [visible](#visible): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if the page is currently visible which is the case if:  <ul>   <li>page is published</li>   <li>the page is set to visible in the current locale</li>   <li>all visibility rules apply, requiring that    <ul>     <li>schedule matches</li>     <li>customer group matches</li>     <li>aspect attribute qualifiers match</li>     <li>campaign and promotion qualifiers match</li>    </ul>   </li>  </ul>  If any of these is not the case then `false` will be returned. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAspectTypeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getaspecttypeid)() | Get the aspect type of the page. |
| [getAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>Returns the raw attribute value identified by the specified attribute id. |
| [getClassificationFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getclassificationfolder)() | Returns the classification [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) associated with this page. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getdescription)() | Returns the description of this page. |
| [getFolders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getfolders)() | Returns all folders to which this page is assigned. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getid)() | Returns the id of this page. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getname)() | Returns the name of this page. |
| [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getpagedescription)() | Returns the SEO description of this page. |
| [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getpagekeywords)() | Returns the SEO keywords of this page. |
| [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getpagetitle)() | Returns the SEO title of this page. |
| [getRegion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getregionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the page region that matches the given id. |
| [getSearchWords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getsearchwords)() | Returns the search words of the page used for the search index. |
| [getTypeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#gettypeid)() | Returns the type id of this page. |
| [hasVisibilityRules](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#hasvisibilityrules)() | Returns `true` if the page has visibility rules (scheduling, customer groups, aspect attribute qualifiers,  campaign and promotion qualifiers) applied, otherwise `false`. |
| [isVisible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible)() | Returns `true` if the page is currently visible which is the case if:  <ul>   <li>page is published</li>   <li>the page is set to visible in the current locale</li>   <li>all visibility rules apply, requiring that    <ul>     <li>schedule matches</li>     <li>customer group matches</li>     <li>aspect attribute qualifiers match</li>     <li>campaign and promotion qualifiers match</li>    </ul>   </li>  </ul>  If any of these is not the case then `false` will be returned. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the id of this page.


---

### aspectTypeID
- aspectTypeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the aspect type of the page.
      If an aspect type is set for this page (and is found in the deployed code version), then the page is treated as dynamic page during
      rendering and serialization.


    **See Also:**
    - [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)
    - [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)


---

### classificationFolder
- classificationFolder: [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) `(read-only)`
  - : Returns the classification [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) associated with this page.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of this page.


---

### folders
- folders: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all folders to which this page is assigned.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of this page.


---

### pageDescription
- pageDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the SEO description of this page.


---

### pageKeywords
- pageKeywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the SEO keywords of this page.


---

### pageTitle
- pageTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the SEO title of this page.


---

### searchWords
- searchWords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the search words of the page used for the search index.


---

### typeID
- typeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type id of this page.


---

### visible
- visible: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if the page is currently visible which is the case if:
      
      - page is published
      - the page is set to visible in the current locale
      - all visibility rules apply, requiring that    
        - schedule matches
        - customer group matches
        - aspect attribute qualifiers match
        - campaign and promotion qualifiers match
      
      
      If any of these is not the case then `false` will be returned.
      
      
      As visibility is driven by the merchant configured dynamic visibility rules, e.g. scheduling and custom segmentation, this
      call should NOT happen in a pagecached context outside of the processing induced by rendering/serialization (see the corresponding
      methods in [PageMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md)). 
      
      Use [hasVisibilityRules()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#hasvisibilityrules) prior to calling this method in order to check for the existence of visibility rules. If there are
      visibility rules then do not apply pagecaching. Otherwise the visibility decision making would end up in the pagecache and any subsequent
      call would just return from the pagecache instead of performing the [isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible) check again as desired.
      
      ```
      ...
      var page = PageMgr.getPage(pageID);
      if (page.hasVisibilityRules())
      {
          // pagecaching is NOT ok here
          if (page.isVisible())
          {
              response.writer.print(PageMgr.renderPage(pageID, {});
          }
      }
      else
      {
          // pagecaching is ok here, but requires a pagecache refresh if merchants start adding visibility rules to the page
      }
      ...
      ```


    **See Also:**
    - [isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible)


---

## Method Details

### getAspectTypeID()
- getAspectTypeID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the aspect type of the page.
      If an aspect type is set for this page (and is found in the deployed code version), then the page is treated as dynamic page during
      rendering and serialization.


    **Returns:**
    - the ID of the page's aspect type

    **See Also:**
    - [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)
    - [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)


---

### getAttribute(String)
- getAttribute(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : 
      Returns the raw attribute value identified by the specified attribute id.
      By raw attribute value we denote the unprocessed value as provided for the attribute
      driven by the type of the respective attribute definition:
      
      - `boolean`-> boolean
      - `category`-> string representing a catalog category ID
      - `custom`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)that originates from a stringified curly brackets {} JSON object
      - `cms_record`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)that originates from a stringified curly brackets {} JSON object whose entries must adhere to the `cmsrecord.json`schema
      - `enum`-> either string or integer
      - `file`-> string representing a file path within a library
      - `image`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)that originates from a stringified curly brackets {} JSON object whose entries must adhere to the `content/schema/image.json`schema
      - `integer`-> integer
      - `markup`-> string representing HTML markup
      - `page`-> string representing a page ID
      - `product`-> string representing a product SKU
      - `string`-> string
      - `text`-> string
      - `url`-> string representing a URL
      
      
      
      
      
      There is two places an attribute value can come from - either it was persisted at design time (e.g.
      by the merchant by editing a component in Page Designer) or it was injected in shape of an aspect attribute at rendering time
      through the execution of code. The persistent value, if existing, takes precedence over the injected aspect
      attribute one. Injection of a value through an aspect attribute will only occur if the page attribute's
      attribute definition was declared using the `"dynamic_lookup"` property and its aspect attribute alias matches
      the ID of the respective aspect attribute.
      
      
      
      Accessing the raw value can be helpful if render and serialization logic of the
      page needs to operate on these unprocessed values. An unprocessed value
      might be fundamentally different from its processed counterpart, the latter being
      provided through the content dictionary (see [PageScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getcontent))
      when the render/serialize function of the page is invoked.


    **Parameters:**
    - attributeID - the id of the desired attribute

    **Returns:**
    - the unprocessed raw value of the desired attribute, or null if not found


---

### getClassificationFolder()
- getClassificationFolder(): [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)
  - : Returns the classification [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) associated with this page.

    **Returns:**
    - the classification [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) if one is assigned, `null` otherwise.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of this page.

    **Returns:**
    - the page description


---

### getFolders()
- getFolders(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all folders to which this page is assigned.

    **Returns:**
    - Collection of [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) objects.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the id of this page.

    **Returns:**
    - the page id


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of this page.

    **Returns:**
    - the page name


---

### getPageDescription()
- getPageDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the SEO description of this page.

    **Returns:**
    - the page SEO description


---

### getPageKeywords()
- getPageKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the SEO keywords of this page.

    **Returns:**
    - the page SEO keywords


---

### getPageTitle()
- getPageTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the SEO title of this page.

    **Returns:**
    - the page SEO title


---

### getRegion(String)
- getRegion(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)
  - : Returns the page region that matches the given id.

    **Parameters:**
    - id - the id of the desired page region

    **Returns:**
    - the region, or null if not found.


---

### getSearchWords()
- getSearchWords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the search words of the page used for the search index.

    **Returns:**
    - the page search words


---

### getTypeID()
- getTypeID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type id of this page.

    **Returns:**
    - the page type id


---

### hasVisibilityRules()
- hasVisibilityRules(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the page has visibility rules (scheduling, customer groups, aspect attribute qualifiers,
      campaign and promotion qualifiers) applied, otherwise `false`. Use this
      method prior to [isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible), so you do not call the latter in a pagecached context.


    **Returns:**
    - `true` if the page has visibility rules applied, otherwise `false`.


---

### isVisible()
- isVisible(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the page is currently visible which is the case if:
      
      - page is published
      - the page is set to visible in the current locale
      - all visibility rules apply, requiring that    
        - schedule matches
        - customer group matches
        - aspect attribute qualifiers match
        - campaign and promotion qualifiers match
      
      
      If any of these is not the case then `false` will be returned.
      
      
      As visibility is driven by the merchant configured dynamic visibility rules, e.g. scheduling and custom segmentation, this
      call should NOT happen in a pagecached context outside of the processing induced by rendering/serialization (see the corresponding
      methods in [PageMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md)). 
      
      Use [hasVisibilityRules()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#hasvisibilityrules) prior to calling this method in order to check for the existence of visibility rules. If there are
      visibility rules then do not apply pagecaching. Otherwise the visibility decision making would end up in the pagecache and any subsequent
      call would just return from the pagecache instead of performing the [isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible) check again as desired.
      
      ```
      ...
      var page = PageMgr.getPage(pageID);
      if (page.hasVisibilityRules())
      {
          // pagecaching is NOT ok here
          if (page.isVisible())
          {
              response.writer.print(PageMgr.renderPage(pageID, {});
          }
      }
      else
      {
          // pagecaching is ok here, but requires a pagecache refresh if merchants start adding visibility rules to the page
      }
      ...
      ```


    **Returns:**
    - `true` if the page is currently visible (published, visible in the current locale, and visibility rules apply), otherwise `false` (unpublished and/or visibility rules don't apply)

    **See Also:**
    - [isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible)


---

<!-- prettier-ignore-end -->

<!-- document id=3bbb70cee80e919f3f47be6fe8d5a32112ed497aeee32bd11ce33126a6378403 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.PageMetaData.md -->

<!-- prettier-ignore-start -->
# Class PageMetaData

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.PageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md)

Contains meta data about the page.

For each request an instance of this class will be placed in the pipeline
dictionary under the key "CurrentPageMetaData".
The information stored in CurrentPageMetaData can be referenced in templates
and rendered in an HTML head section:
for example:

```

<head>
<title>${pdict.CurrentPageMetaData.title}</title>
<meta name="description" content="${pdict.CurrentPageMetaData.description}"/>
.
.
.
</head>
```


To update the CurrentPageMetaData there is the pipelet UpdatePageMetaData
provided.



## Property Summary

| Property | Description |
| --- | --- |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the page's description. |
| [keywords](#keywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the page's key words. |
| [pageMetaTags](#pagemetatags): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)` | Returns all page meta tags added to this container. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the page's title. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#addpagemetatagpagemetatag)([PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)) | Adds a page meta tag to this container. |
| [addPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#addpagemetatagsarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Adds a page meta tags list to this container. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#getdescription)() | Returns the page's description. |
| [getKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#getkeywords)() | Returns the page's key words. |
| [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#getpagemetatags)() | Returns all page meta tags added to this container. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#gettitle)() | Returns the page's title. |
| [isPageMetaTagSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#ispagemetatagsetstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns true if a page meta tag with the given ID is set, false otherwise. |
| [setDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#setdescriptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the page's description. |
| [setKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#setkeywordsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the page's key words. |
| [setTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md#settitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the page's title. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page's description.


---

### keywords
- keywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page's key words.


---

### pageMetaTags
- pageMetaTags: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)`
  - : Returns all page meta tags added to this container.


---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page's title.


---

## Method Details

### addPageMetaTag(PageMetaTag)
- addPageMetaTag(pageMetaTag: [PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)): void
  - : Adds a page meta tag to this container.

    **Parameters:**
    - pageMetaTag - the page meta tag to be added


---

### addPageMetaTags(Array)
- addPageMetaTags(pageMetaTags: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)): void
  - : Adds a page meta tags list to this container.

    **Parameters:**
    - pageMetaTags - the page meta tags list to be added


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page's description.

    **Returns:**
    - the page's description.


---

### getKeywords()
- getKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page's key words.

    **Returns:**
    - the page's key words.


---

### getPageMetaTags()
- getPageMetaTags(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns all page meta tags added to this container.

    **Returns:**
    - page meta tags


---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page's title.

    **Returns:**
    - the page's title.


---

### isPageMetaTagSet(String)
- isPageMetaTagSet(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if a page meta tag with the given ID is set, false otherwise.

    **Parameters:**
    - id - the ID to be check if a page meta tag is set

    **Returns:**
    - true if a page meta tag with the given ID is set, false otherwise


---

### setDescription(String)
- setDescription(description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the page's description.

    **Parameters:**
    - description - the page's description.


---

### setKeywords(String)
- setKeywords(keywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the page's key words.

    **Parameters:**
    - keywords - the page's key words.


---

### setTitle(String)
- setTitle(title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the page's title.

    **Parameters:**
    - title - the page's title.


---

<!-- prettier-ignore-end -->

<!-- document id=9b6c17fd4d34b25aadf681f22d24986927d01ee562e0116d3c50b471e00d9960 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.PageMetaTag.md -->

<!-- prettier-ignore-start -->
# Class PageMetaTag

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)

Page meta tags are used in HTML documents to provide structured data about a web
page. They are usually part of the head section. Common tags are for example robots,
description or social tags like open graph (e.g. 'og:title'), or additionally
adding json-ld (JSON for linked data) and provides structured data that is easily crawlable. 


Page meta tags can be obtained within:


- home page context

- [Site](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md)
- detail page context

- [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
- [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md)
- listing page context

- [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md)
- [ContentSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md)


and can be set at [PageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md) container object, which is always available
in the pipeline dictionary and is used as transfer object to fill the head area with meaningful
page meta tag elements.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page meta tag ID. |
| [content](#content): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the page meta tag content. |
| [jsonLd](#jsonld): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the page meta tag type is json-ld (JSON for linked data) and provides  structured data about the page for crawlers, false otherwise. |
| [name](#name): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the page meta tag type is name, false otherwise. |
| [property](#property): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the page meta tag type is property, false otherwise. |
| [title](#title): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the page meta tag type is title, false otherwise. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md#getcontent)() | Returns the page meta tag content. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md#getid)() | Returns the page meta tag ID. |
| [isJsonLd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md#isjsonld)() | Returns true if the page meta tag type is json-ld (JSON for linked data) and provides  structured data about the page for crawlers, false otherwise. |
| [isName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md#isname)() | Returns true if the page meta tag type is name, false otherwise. |
| [isProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md#isproperty)() | Returns true if the page meta tag type is property, false otherwise. |
| [isTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md#istitle)() | Returns true if the page meta tag type is title, false otherwise. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page meta tag ID.


---

### content
- content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the page meta tag content.


---

### jsonLd
- jsonLd: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the page meta tag type is json-ld (JSON for linked data) and provides
      structured data about the page for crawlers, false otherwise.



---

### name
- name: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the page meta tag type is name, false otherwise.


---

### property
- property: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the page meta tag type is property, false otherwise.


---

### title
- title: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the page meta tag type is title, false otherwise.


---

## Method Details

### getContent()
- getContent(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page meta tag content.

    **Returns:**
    - page meta tag content


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the page meta tag ID.

    **Returns:**
    - page meta tag ID


---

### isJsonLd()
- isJsonLd(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the page meta tag type is json-ld (JSON for linked data) and provides
      structured data about the page for crawlers, false otherwise.


    **Returns:**
    - true if the page meta tag type is json-ld, false otherwise


---

### isName()
- isName(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the page meta tag type is name, false otherwise.

    **Returns:**
    - true if the page meta tag type is name, false otherwise


---

### isProperty()
- isProperty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the page meta tag type is property, false otherwise.

    **Returns:**
    - true if the page meta tag type is property, false otherwise


---

### isTitle()
- isTitle(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the page meta tag type is title, false otherwise.

    **Returns:**
    - true if the page meta tag type is title, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=151692bcb81ce3940c9719573b14309c64f73bc9d5f12432dd958dc2abc9f66e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.PageMgr.md -->

<!-- prettier-ignore-start -->
# Class PageMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.PageMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md)

Provides functionality for getting, rendering and serializing page designer managed pages.


The basic flow is to determine a page by either id, category or product

- [getPage(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagestring)
- [getPageByCategory(Category, Boolean, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagebycategorycategory-boolean-string)
- [getPageByProduct(Product, Boolean, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagebyproductproduct-boolean-string)

and then to initiate rendering of this page via

- [renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)
- [renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)

This will trigger page rendering from a top level perspective, i.e. the page serves as entry point and root container of components.



As a related page or component template will likely want to trigger rendering of nested components
within its regions it can do this by first fetching the desired region by ID via
[Page.getRegion(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getregionstring) or [Component.getRegion(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getregionstring) and then call to [renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings)
with the recently retrieved region (and optionally provide [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md) for customized
rendering of region and component wrapper elements).




Similar to the rendering you can also serialize such page to json via

- [serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)
- [serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)

This will trigger page serialization from a top level perspective, i.e. the page serves as entry point and root container of components,
which will automatically traverse all visible components and attach their serialization result to the emitted json.




Various attributes required for rendering and serialization in the corresponding template can be accessed with the
accordant methods of [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) and [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md).


**See Also:**
- [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
- [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)
- [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)


## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getCustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getcustomeditorstring-map)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)) | <p>  Initialize the custom editor of given type id using the passed configuration. |
| ~~static [getPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagecategory-boolean-string)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Get the dynamic page for the given category (including bottom up traversal of the category tree) and aspect type. |
| static [getPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the page identified by the specified id. |
| static [getPageByCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagebycategorycategory-boolean-string)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Get the dynamic page for the given category (including bottom up traversal of the category tree) and aspect type. |
| static [getPageByProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagebyproductproduct-boolean-string)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Get the dynamic page for the given product and aspect type. |
| static [renderPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Render a page. |
| static [renderPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Render a page. |
| static [renderRegion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion)([Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)) | <p>Renders a region by triggering rendering of all visible components within  this region. |
| static [renderRegion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings)([Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md), [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)) | <p>Renders a region by triggering rendering of all visible components within  this region. |
| static [serializePage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Serialize a page as json string. |
| static [serializePage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Serialize a page as json string with the following properties:  <ul>      <li>`String id` - the id of the page</li>      <li>`String type_id` - the id of the page type</li>      <li>`Map<String, Object> data` - the content attribute key value pairs</li>      <li>`Map<String, Object> custom` - the custom key value pairs as produced by the optional page type `serialize` function</li>      <li>`List<Region> regions` - the regions of this page. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### getCustomEditor(String, Map)
- static getCustomEditor(customEditorTypeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), configuration: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)): [CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md)
  - : 
      
      Initialize the custom editor of given type id using the passed configuration. The initialization
      will trigger the `init` function of the respective custom editor type for which the passed
      custom editor object is being preinitialized with the given configuration (similar to what would
      happen through the `editor_definition` reference by any component type attribute definition).
      
      
      
      
      This method is useful to obtain any custom editor instance you want to reuse within the `init`
      method of another custom editor, e.g. as dependent breakout element.


    **Parameters:**
    - customEditorTypeID - the reference to a custom editor type, e.g. 'com.foo.bar'
    - configuration - the data structure used for preinitialization of the custom editor (also see [CustomEditor.getConfiguration()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md#getconfiguration)).                            Be aware that this configuration will have to be serializable to JSON itself as it will be passed to Page Designer                            for processing in the UI. So you must not add any values in this map that are not properly serializable. Do not use                            complex DWScript classes that do not support JSON serialization like for instance [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md).

    **Returns:**
    - the initialized custom editor instance


---

### getPage(Category, Boolean, String)
- ~~static getPage(category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), pageMustBeVisible: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), aspectTypeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)~~
  - : Get the dynamic page for the given category (including bottom up traversal of the category tree) and aspect type.

    **Parameters:**
    - category - category to find the page for, i.e. starting point (inclusive) for the bottom up traversal
    - pageMustBeVisible - while doing the bottom up traversal any attached page whose [Page.isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible) does not yield true will be bypassed in the search
    - aspectTypeID - id of the page-category-assignment aspect type

    **Returns:**
    - the page assigned to the given category. If none is found then the path upwards in the
              category tree is traversed until a category is found that has an implicit (but not explicit) page assignment.
              If category assignments are not supported by the given aspect type or none is found within the
              aforementioned path of categories then `null` is returned.


    **Deprecated:**
**warning:** Please use [getPageByCategory(Category, Boolean, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagebycategorycategory-boolean-string) instead.

---

### getPage(String)
- static getPage(pageID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
  - : Returns the page identified by the specified id.

    **Parameters:**
    - pageID - the id of the page

    **Returns:**
    - the page, or null if not found.


---

### getPageByCategory(Category, Boolean, String)
- static getPageByCategory(category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), pageMustBeVisible: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), aspectTypeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
  - : Get the dynamic page for the given category (including bottom up traversal of the category tree) and aspect type.

    **Parameters:**
    - category - category to find the page for, i.e. starting point (inclusive) for the bottom up traversal
    - pageMustBeVisible - while doing the bottom up traversal any attached page whose [Page.isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible) does not yield true will be bypassed in the search
    - aspectTypeID - id of the page-category-assignment aspect type

    **Returns:**
    - the page assigned to the given category. If none is found then the path upwards in the
              category tree is traversed until a category is found that has an implicit (but not explicit) page assignment.
              If category assignments are not supported by the given aspect type or none is found within the
              aforementioned path of categories then `null` is returned.



---

### getPageByProduct(Product, Boolean, String)
- static getPageByProduct(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), pageMustBeVisible: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), aspectTypeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
  - : Get the dynamic page for the given product and aspect type.
      
      
      No bottom up traversal of the product's category tree is performed. If you require this then  a
      separate call to [getPageByCategory(Category, Boolean, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#getpagebycategorycategory-boolean-string) (with the category of your choice, e.g. the default
      category of the product) needs to be made.


    **Parameters:**
    - product - product to find the page for
    - pageMustBeVisible - an attached page whose [Page.isVisible()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#isvisible) does not yield true will be bypassed in the search
    - aspectTypeID - id of the page-product-assignment aspect type

    **Returns:**
    - the page assigned to the given product. If product assignments are not supported by the given
               aspect type then `null` is returned.



---

### renderPage(String, Map, String)
- static renderPage(pageID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), aspectAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), parameters: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Render a page. This is an extension of [renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string) for the purpose of rendering a
      page that needs to determine pieces of its content at rendering time instead of design time only. Therefore it
      is possible to pass aspect attributes in case the given page is subject to an aspect type. The latter specifies the
      eligible aspect attribute definitions which the passed in aspect attributes will be validated against.
      If the validation fails for any of the following reasons an [AspectAttributeValidationException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.AspectAttributeValidationException.md)
      will be thrown:
      
      - any aspect attribute value violates the value domain of the corresponding attribute definition
      - any required aspect attribute value is `null`
      
      Aspect attributes without corresponding attribute definition will be omitted. Once they made it into the rendering
      they will apply if no persistent attribute value exists (taking precedence over default attribute values
      as coming from the attribute definition json) and the attribute has the `dynamic_lookup`
      property defined which contains the aspect attribute alias. The aspect attribute value lookup then happens by taking
      this aspect attribute alias and using it as attribute identifier within the given map of aspect attributes.
      
      
      Due to the nature of using remote includes, also see [renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string), this comes with the url length
      restriction as you already know it from remote includes you implement by hand within your templates. Thus the size of both the
      `aspectAttributes` (keys and values) as well as the `parameters` parameter of this method
      are subject to a length limitation accordingly because they just translate into url parameters of the aforementioned remote includes.
      As a best practice refrain from passing complex objects (e.g. full blown product models) but keep it rather slim (e.g. only product IDs).


    **Parameters:**
    - pageID - the aspect driven page that will be rendered
    - aspectAttributes - the values for the aspect attributes, with the key being the id of the respective attribute definition and                          the value adhering to the type of this attribute definition
    - parameters - the optional parameters passed to page rendering

    **Returns:**
    - the remote include that will yield the markup as produced by page rendering

    **Throws:**
    - dw.experience.AspectAttributeValidationException - if any given aspect attribute value does fulfill its respective attribute definition

    **See Also:**
    - [renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)


---

### renderPage(String, String)
- static renderPage(pageID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), parameters: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Render a page. All of this is going to happen in two layers of remote includes, therefore pagecaching of page rendering
      is separated from the pagecache lifecycle of the caller. The first one is going to be returned by this method.
      
      - layer 1 - determines visibility fingerprint for the page and all its nested components driven by its visibility rules. This remote include will only be pagecached for a fixed duration if neither the page nor any of its                       nested components carries a visibility rule (configurable in Business Manager via the site's page caching settings). It will then delegate to layer 2.
      - layer 2 - does the actual rendering of the page by invoking its render function. This remote include will factor the previously determined visibility fingerprint in to the pagecache key, in case you decide to use pagecaching.
      
      
      
      The layer 1 remote include is what is returned when calling this method.
      
      
      
      
      The provided `parameters` argument is passed through till the layer 2 remote include which does the actual rendering so that it will be available
      for the `render` function of the invoked page as part of [PageScriptContext.getRuntimeParameters()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getruntimeparameters). You probably want to
      provide caller parameters from the outside in shape of a json String to the inside of the page rendering, e.g. to loop through query parameters.
      
      
      
      
      The layer 2 remote include performs the rendering of the page and all its nested components within one request. Thus data sharing between
      the page and its nested components can happen in scope of this request.
      
      
      
      
      The rendering of a page invokes the `render` function of the respective page type.
      
      ```
          String : render( PageScriptContext context)
      ```
      
      The return value of the `render` function finally represents the markup produced by this page type.
      
      
      
      
      
      Nested page rendering, i.e. rendering a page within a page (or respectively its components), is not a supported use case.
      
      
      
      
      Due to the nature of the remote includes mentioned above this comes with the url length restriction as you already know it from
      remote includes you implement by hand within your templates. Thus the size of the `parameters` parameter of this
      method has a length limitation accordingly because it just translates into a url parameter of the aforementioned remote includes.
      As a best practice refrain from passing complex objects (e.g. full blown product models) but keep it rather slim (e.g. only product IDs).


    **Parameters:**
    - pageID - the ID of the page that will be rendered
    - parameters - the optional parameters passed to page rendering

    **Returns:**
    - the remote include that will yield the markup as produced by page rendering

    **See Also:**
    - [renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)


---

### renderRegion(Region)
- static renderRegion(region: [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      Renders a region by triggering rendering of all visible components within
      this region. For each of these components the render function  of the respective component
      type is invoked.
      
      ```
          String : render( ComponentScriptContext params)
      ```
      
      The return value of the `render` function will be wrapped by an HTML element - this
      finally represents the markup produced by this component type. The markup of the region
      accordingly represents the concatenation of all the components markup within an
      own wrapper element.
      
      The following sample shows how this would look like for a 'pictures' region
      that contains two components of type 'assets.image'. 
      
      
      ```
      <div class="experience-region experience-pictures">
          <div class="experience-component experience-assets-image">
              ...
          </div>
          <div class="experience-component experience-assets-image">
              ..
          </div>
      </div>
      ```
      
      
      
      The system default for region render settings are:
      
      - tag\_name : div
      - attributes : {"class":"experience-region experience-\[REGION\_ID\]"}
      
      
      
      
      
      The system default for component render settings are:
      
      - tag name : div
      - attributes : {"class":"experience-component experience-\[COMPONENT\_TYPE\_ID\]"}
      
      As the \[COMPONENT\_TYPE\_ID\] can contain dots due to its package like naming scheme (e.g. assets.image)
      any occurrences of these dots will be replaced by dashes (e.g. assets-image) so that CSS selectors
      do not have to be escaped.
      
      
      
      
      In order to provide your own settings for the wrapper elements see
      [renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings).
      
      
      
      You must NOT call this method outside of the processing induced by [renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string).


    **Parameters:**
    - region - the region that will be rendered

    **Returns:**
    - the markup as produced by region rendering


---

### renderRegion(Region, RegionRenderSettings)
- static renderRegion(region: [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md), regionRenderSettings: [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      Renders a region by triggering rendering of all visible components within
      this region. For each of these components the render function of the respective component
      type is invoked.
      
      ```
          String : render( ComponentScriptContext context)
      ```
      
      The return value of the `render` function will be wrapped by an HTML element - this
      finally represents the markup produced by this component type. The markup of the region
      accordingly represents the concatenation of all the components markup within an
      own wrapper element.
      
      In order to provide styling for these wrapper
      elements of the components and the region some render settings can optionally be provided,
      which basically allows to configure which kind of tag is used for the wrapper element and
      which attributes the wrapper element contains. A sample output could look like this if
      [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md) are applied with customized tag names and attributes
      for the region and component wrapper elements.
      
      
      ```
      <p class="myRegionCssClass">
          <span class="myComponentCssClass myComponentCssClass1" data-foo="bar">
              ...
          </span>
          <span class="myComponentCssClass myComponentCssClass2">
              ...
          </span>
      </p>
      ```
      
      
      
      In order to go with the default settings for the wrapper elements see
      [renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion).
      
      
      
      
      You must NOT call this method outside of the processing induced by [renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string).


    **Parameters:**
    - region - the region that will be rendered
    - regionRenderSettings - the render settings that drive how the region and its components is rendered

    **Returns:**
    - the markup as produced by region rendering

    **See Also:**
    - [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)


---

### serializePage(String, Map, String)
- static serializePage(pageID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), aspectAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), parameters: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Serialize a page as json string. This is an extension of [serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string) for the purpose of serializing a
      page that needs to determine pieces of its content at serialization time instead of design time only. Therefore it
      is possible to pass aspect attributes in case the given page is subject to an aspect type. The latter specifies the
      eligible aspect attribute definitions which the passed in aspect attributes will be validated against.
      If the validation fails for any of the following reasons an [AspectAttributeValidationException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.AspectAttributeValidationException.md)
      will be thrown:
      
      - any aspect attribute value violates the value domain of the corresponding attribute definition
      - any required aspect attribute value is `null`
      
      Aspect attributes without corresponding attribute definition will be omitted. Once they made it into the serialization
      they will apply if no persistent attribute value exists (taking precedence over default attribute values
      as coming from the attribute definition json) and the attribute has the `dynamic_lookup`
      property defined which contains the aspect attribute alias. The aspect attribute value lookup then happens by taking
      this aspect attribute alias and using it as attribute identifier within the given map of aspect attributes.
      
      
      Due to the nature of using remote includes, also see [serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string), this comes with the url length
      restriction as you already know it from remote includes you implement by hand within your templates. Thus the size of both the
      `aspectAttributes` (keys and values) as well as the `parameters` parameter of this method
      are subject to a length limitation accordingly because they just translate into url parameters of the aforementioned remote includes.
      As a best practice refrain from passing complex objects (e.g. full blown product models) but keep it rather slim (e.g. only product IDs).


    **Parameters:**
    - pageID - the aspect driven page that will be serialized
    - aspectAttributes - the values for the aspect attributes, with the key being the id of the respective attribute definition and                          the value adhering to the type of this attribute definition
    - parameters - the optional parameters passed to page serialization

    **Returns:**
    - the remote include that will yield the json string as produced by page serialization

    **Throws:**
    - dw.experience.AspectAttributeValidationException - if any given aspect attribute value doesn't fulfill its respective attribute definition

    **See Also:**
    - [serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)


---

### serializePage(String, String)
- static serializePage(pageID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), parameters: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Serialize a page as json string with the following properties:
      
      - `String id`- the id of the page
      - `String type_id`- the id of the page type
      - `Map<String, Object>data`- the content attribute key value pairs
      - `Map<String, Object>custom`- the custom key value pairs as produced by the optional page type `serialize`function
      - `List<Region>regions`- the regions of this page. A region consists of the following properties           
        - `String id`- the id of the region
        - `List<Component>components`- the components of this region. A component consists of the following properties                  
          - `String id`- the id of the component
          - `String type_id`- the id of the component type
          - `Map<String, Object>data`- the content attribute key value pairs
          - `Map<String, Object>custom`- the custom key value pairs as produced by the optional component type `serialize`function
          - `List<Region>regions`- the regions of this component
      
      
      
      
      
      All of this is going to happen in two layers of remote includes, therefore pagecaching of page serialization
      is separated from the pagecache lifecycle of the caller. The first one is going to be returned by this method.
      
      - layer 1 - determines visibility fingerprint for the page and all its nested components driven by its visibility rules. This remote include will only be pagecached for a fixed duration if neither the page nor any of its                       nested components carries a visibility rule (configurable in Business Manager via the site's page caching settings). It will then delegate to layer 2.
      - layer 2 - does the actual rendering of the page by invoking its render function. This remote include will factor the previously determined visibility fingerprint in to the pagecache key, in case you decide to use pagecaching.
      
      
      
      
      
      The layer 1 remote include is what is returned when calling this method.
      
      
      
      
      The provided `parameters` argument is passed through till the layer 2 remote include which does the actual serialization so that it will be available
      for the `serialize` function of the invoked page as part of [PageScriptContext.getRuntimeParameters()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getruntimeparameters). You probably want to
      provide caller parameters from the outside in shape of a json String to the inside of the page serialization, e.g. to loop through query parameters.
      
      
      
      
      The layer 2 remote include performs the serialization of the page and all its nested components within one request. Thus data sharing between
      the page and its nested components can happen in scope of this request.
      
      
      
      
      The serialization of a page also invokes the `serialize` function of the respective page type.
      
      ```
          Object : serialize( PageScriptContext context)
      ```
      
      The return value of the `serialize` function will be injected as property `custom`
      into the json string produced as serialization result for this page type.
      
      
      
      
      
      Nested page serialization, i.e. serializing a page within a page (or respectively its components), is not a supported use case.
      
      
      
      
      Due to the nature of the remote includes mentioned above this comes with the url length restriction as you already know it from
      remote includes you implement by hand within your templates. Thus the size of the `parameters` parameter of this
      method has a length limitation accordingly because it just translates into a url parameter of the aforementioned remote includes.
      As a best practice refrain from passing complex objects (e.g. full blown product models) but keep it rather slim (e.g. only product IDs).


    **Parameters:**
    - pageID - the ID of the page that will be serialized
    - parameters - the optional parameters passed to page serialization

    **Returns:**
    - the remote include that will yield the json string as produced by page serialization

    **See Also:**
    - [serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)


---

<!-- prettier-ignore-end -->

<!-- document id=09ef556dd74a5da0e38d8d25e0cf589af0b997d6f18d60eff584412c131ff451 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.PageScriptContext.md -->

<!-- prettier-ignore-start -->
# Class PageScriptContext

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.PageScriptContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md)

This is the context that is handed over to the `render` and `serialize` function of the respective page type
script.


```
    String : render( [PageScriptContext](dw.experience.PageScriptContext.md) context)
    Object : serialize( [PageScriptContext](dw.experience.PageScriptContext.md) context)
```



## Property Summary

| Property | Description |
| --- | --- |
| [content](#content): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the processed version of the underlying unprocessed raw values (also see [Page.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getattributestring))  of this page's attributes which you can use in your respective page type `render` and `serialize` function  implementing your business and rendering/serialization functionality. |
| [page](#page): [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) `(read-only)` | Returns the page for which the corresponding page type script is currently executed. |
| ~~[renderParameters](#renderparameters): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | Returns the `parameters` argument as passed when kicking off page rendering via  <ul>   <li>[PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)</li>   <li>[PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)</li>  </ul>  and serialization  <ul>   <li>[PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)</li>   <li>[PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)</li>  </ul> |
| [runtimeParameters](#runtimeparameters): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the `parameters` argument as passed when kicking off page rendering via  <ul>   <li>[PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)</li>   <li>[PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)</li>  </ul>  and page serialization via  <ul>   <li>[PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)</li>   <li>[PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)</li>  </ul> |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getcontent)() | Returns the processed version of the underlying unprocessed raw values (also see [Page.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getattributestring))  of this page's attributes which you can use in your respective page type `render` and `serialize` function  implementing your business and rendering/serialization functionality. |
| [getPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getpage)() | Returns the page for which the corresponding page type script is currently executed. |
| ~~[getRenderParameters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getrenderparameters)()~~ | Returns the `parameters` argument as passed when kicking off page rendering via  <ul>   <li>[PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)</li>   <li>[PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)</li>  </ul>  and serialization  <ul>   <li>[PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)</li>   <li>[PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)</li>  </ul> |
| [getRuntimeParameters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getruntimeparameters)() | Returns the `parameters` argument as passed when kicking off page rendering via  <ul>   <li>[PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)</li>   <li>[PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)</li>  </ul>  and page serialization via  <ul>   <li>[PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)</li>   <li>[PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)</li>  </ul> |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### content
- content: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the processed version of the underlying unprocessed raw values (also see [Page.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getattributestring))
      of this page's attributes which you can use in your respective page type `render` and `serialize` function
      implementing your business and rendering/serialization functionality. Processing the raw value is comprised of **expansion**
      and **conversion**, in this order.
      
      1. **expansion**- dynamic placeholders are transformed into actual values, for example url/link placeholders in       markup text are resolved to real URLs
      2. **conversion**- the raw value (see [Page.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getattributestring)) is resolved into an actual       DWScript object depending on the type of the attribute as specified in its respective attribute definition        
         - `boolean`-> boolean
         - `category`-> [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
         - `custom`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
         - `cms_record`-> [CMSRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md)
         - `enum`-> either string or integer 
         - `file`-> [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
         - `image`-> [Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)
         - `integer`-> integer
         - `markup`-> string
         - `page`-> string
         - `product`-> [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
         - `string`-> string
         - `text`-> string
         - `url`-> string



---

### page
- page: [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md) `(read-only)`
  - : Returns the page for which the corresponding page type script is currently executed.


---

### renderParameters
- ~~renderParameters: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : Returns the `parameters` argument as passed when kicking off page rendering via
      
      - [PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)
      - [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)
      
      and serialization
      
      - [PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)
      - [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)


    **Deprecated:**
**warning:** Please use [getRuntimeParameters()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getruntimeparameters) instead.

---

### runtimeParameters
- runtimeParameters: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the `parameters` argument as passed when kicking off page rendering via
      
      - [PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)
      - [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)
      
      and page serialization via
      
      - [PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)
      - [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)



---

## Method Details

### getContent()
- getContent(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the processed version of the underlying unprocessed raw values (also see [Page.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getattributestring))
      of this page's attributes which you can use in your respective page type `render` and `serialize` function
      implementing your business and rendering/serialization functionality. Processing the raw value is comprised of **expansion**
      and **conversion**, in this order.
      
      1. **expansion**- dynamic placeholders are transformed into actual values, for example url/link placeholders in       markup text are resolved to real URLs
      2. **conversion**- the raw value (see [Page.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md#getattributestring)) is resolved into an actual       DWScript object depending on the type of the attribute as specified in its respective attribute definition        
         - `boolean`-> boolean
         - `category`-> [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
         - `custom`-> [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
         - `cms_record`-> [CMSRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md)
         - `enum`-> either string or integer 
         - `file`-> [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
         - `image`-> [Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)
         - `integer`-> integer
         - `markup`-> string
         - `page`-> string
         - `product`-> [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
         - `string`-> string
         - `text`-> string
         - `url`-> string


    **Returns:**
    - processed content attributes of the page


---

### getPage()
- getPage(): [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
  - : Returns the page for which the corresponding page type script is currently executed.

    **Returns:**
    - the currently rendered page


---

### getRenderParameters()
- ~~getRenderParameters(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the `parameters` argument as passed when kicking off page rendering via
      
      - [PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)
      - [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)
      
      and serialization
      
      - [PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)
      - [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)


    **Returns:**
    - the parameters passed to page rendering and serialization

    **Deprecated:**
**warning:** Please use [getRuntimeParameters()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md#getruntimeparameters) instead.

---

### getRuntimeParameters()
- getRuntimeParameters(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the `parameters` argument as passed when kicking off page rendering via
      
      - [PageMgr.renderPage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-string)
      - [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string)
      
      and page serialization via
      
      - [PageMgr.serializePage(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-string)
      - [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string)


    **Returns:**
    - the parameters passed to page rendering and serialization


---

<!-- prettier-ignore-end -->

<!-- document id=13dfe9441cdf4fb1f415dc8310129dc7018fa17103cb9de20dae73341540e31e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.PagingModel.md -->

<!-- prettier-ignore-start -->
# Class PagingModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.PagingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md)

A page model is a helper class to apply a pages to a collection of
elements or an iterator of elements and supports creating URLs for
continued paging through the elements.

The page model is intended to be initialized with the collection or
iterator, than the paging position is applyed and than the elements are
extracted with getPageElements().

In case the page model is initialized with a collection the page model
can be reused multiple times.



## Constant Summary

| Constant | Description |
| --- | --- |
| [DEFAULT_PAGE_SIZE](#default_page_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | The default page size. |
| [MAX_PAGE_SIZE](#max_page_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2000 | The maximum supported page size. |
| [PAGING_SIZE_PARAMETER](#paging_size_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sz" | The URL Parameter used for the page size. |
| [PAGING_START_PARAMETER](#paging_start_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "start" | The URL parameter used for the start position. |

## Property Summary

| Property | Description |
| --- | --- |
| [count](#count): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the count of the number of items in the model. |
| [currentPage](#currentpage): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the index number of the current page. |
| [empty](#empty): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the model is empty. |
| [end](#end): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the index of the last element on the current page. |
| [maxPage](#maxpage): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the maximum possible page number. |
| [pageCount](#pagecount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the total page count. |
| [pageElements](#pageelements): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Returns an iterator that can be used to iterate through the elements of  the current page. |
| [pageSize](#pagesize): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the size of the page. |
| [start](#start): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the current start position from which iteration will start. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [PagingModel](#pagingmodeliterator-number)([Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs the PagingModel using the specified iterator and count value. |
| [PagingModel](#pagingmodelcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Constructs the PagingModel using the specified collection. |

## Method Summary

| Method | Description |
| --- | --- |
| static [appendPageSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#appendpagesizeurl-number)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an URL containing the page size parameter appended to the  specified url. |
| [appendPaging](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#appendpagingurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Returns an URL by appending the current page start position and the  current page size to the URL. |
| [appendPaging](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#appendpagingurl-number)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an URL by appending the paging parameters for a desired  page start position and the current page size to the specified url. |
| [getCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getcount)() | Returns the count of the number of items in the model. |
| [getCurrentPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getcurrentpage)() | Returns the index number of the current page. |
| [getEnd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getend)() | Returns the index of the last element on the current page. |
| [getMaxPage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getmaxpage)() | Returns the maximum possible page number. |
| [getPageCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getpagecount)() | Returns the total page count. |
| [getPageElements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getpageelements)() | Returns an iterator that can be used to iterate through the elements of  the current page. |
| [getPageSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getpagesize)() | Returns the size of the page. |
| [getStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#getstart)() | Returns the current start position from which iteration will start. |
| [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#isempty)() | Identifies if the model is empty. |
| [setPageSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#setpagesizenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the size of the page. |
| [setStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md#setstartnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the current start position from which iteration will start. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DEFAULT_PAGE_SIZE

- DEFAULT_PAGE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : The default page size.


---

### MAX_PAGE_SIZE

- MAX_PAGE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2000
  - : The maximum supported page size.


---

### PAGING_SIZE_PARAMETER

- PAGING_SIZE_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sz"
  - : The URL Parameter used for the page size.


---

### PAGING_START_PARAMETER

- PAGING_START_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "start"
  - : The URL parameter used for the start position.


---

## Property Details

### count
- count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the count of the number of items in the model.


---

### currentPage
- currentPage: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the index number of the current page. The page
      counting starts with 0. The method also works with a miss-aligned
      start. In that case the start is always treated as the start of
      a page.



---

### empty
- empty: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the model is empty.


---

### end
- end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the index of the last element on the current page.


---

### maxPage
- maxPage: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the maximum possible page number. Counting for pages starts
      with 0.  The method also works with a miss-aligned start. In that case
      the returned number might be higher than ((count-1) / pageSize).



---

### pageCount
- pageCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the total page count. The method also works
      with a miss-aligned start. In that case the returned number might
      be higher than (count / pageSize).



---

### pageElements
- pageElements: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Returns an iterator that can be used to iterate through the elements of
      the current page.
      
      In case of a collection as the page models source, the method can be
      called multiple times. Each time a fresh iterator is returned.
      
      In case of an iterator as the page models source, the method must be
      called only once. The method will always return the same iterator,
      which means the method amy return an exhausted iterator.



---

### pageSize
- pageSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the page.


---

### start
- start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the current start position from which iteration will start.


---

## Constructor Details

### PagingModel(Iterator, Number)
- PagingModel(elements: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md), count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs the PagingModel using the specified iterator and count value.
      Count must not be negative.
      
      Note: A valid count must be provided. The PageModel class can not be used
      if the number of elements is unknown. Without knowning the number of
      elements it still would be possible to return the elements of a particular
      page, but it would be not possible to calculate data like the total number
      of pages or to construct an URL to jump to a particular page.


    **Parameters:**
    - elements - the iterator containing the model elements.
    - count - the count of elements.


---

### PagingModel(Collection)
- PagingModel(elements: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))
  - : Constructs the PagingModel using the specified collection.

    **Parameters:**
    - elements - the collection containing the model elements.


---

## Method Details

### appendPageSize(URL, Number)
- static appendPageSize(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), pageSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL containing the page size parameter appended to the
      specified url. The name of the page size parameter is 'sz' (see
      PAGE\_SIZE\_PARAMETER). The start position parameter is not appended to the
      returned URL.


    **Parameters:**
    - url - the URL to append the page size parameter to.
    - pageSize - the page size

    **Returns:**
    - an URL that contains the page size parameter.


---

### appendPaging(URL)
- appendPaging(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL by appending the current page start position and the
      current page size to the URL.


    **Parameters:**
    - url - the URL to append the current paging position to.

    **Returns:**
    - an URL containing the current paging position.


---

### appendPaging(URL, Number)
- appendPaging(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), position: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns an URL by appending the paging parameters for a desired
      page start position and the current page size to the specified url. The name of
      the page start position parameter is 'start' (see PAGING\_START\_PARAMETER)
      and the page size parameter is 'sz' (see PAGE\_SIZE\_PARAMETER).


    **Parameters:**
    - url - the URL to append the paging parameter to.
    - position - the start position.

    **Returns:**
    - an URL that contains the paging parameters.


---

### getCount()
- getCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the count of the number of items in the model.

    **Returns:**
    - the count of the number of items in the model.


---

### getCurrentPage()
- getCurrentPage(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index number of the current page. The page
      counting starts with 0. The method also works with a miss-aligned
      start. In that case the start is always treated as the start of
      a page.


    **Returns:**
    - the index number of the current page.


---

### getEnd()
- getEnd(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index of the last element on the current page.

    **Returns:**
    - the index of the last element on the current page.


---

### getMaxPage()
- getMaxPage(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum possible page number. Counting for pages starts
      with 0.  The method also works with a miss-aligned start. In that case
      the returned number might be higher than ((count-1) / pageSize).


    **Returns:**
    - the maximum possible page number.


---

### getPageCount()
- getPageCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the total page count. The method also works
      with a miss-aligned start. In that case the returned number might
      be higher than (count / pageSize).


    **Returns:**
    - the total page count.


---

### getPageElements()
- getPageElements(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Returns an iterator that can be used to iterate through the elements of
      the current page.
      
      In case of a collection as the page models source, the method can be
      called multiple times. Each time a fresh iterator is returned.
      
      In case of an iterator as the page models source, the method must be
      called only once. The method will always return the same iterator,
      which means the method amy return an exhausted iterator.


    **Returns:**
    - an iterator that you use to iterate through
      the elements of the current page.



---

### getPageSize()
- getPageSize(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the page.

    **Returns:**
    - the size of the page.


---

### getStart()
- getStart(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the current start position from which iteration will start.

    **Returns:**
    - the current start position from which iteration will start.


---

### isEmpty()
- isEmpty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the model is empty.

    **Returns:**
    - true if the model is empty, false otherwise.


---

### setPageSize(Number)
- setPageSize(pageSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the size of the page. The page size must be greater or
      equal to 1.


    **Parameters:**
    - pageSize - the size of the page.


---

### setStart(Number)
- setStart(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the current start position from which iteration will start.

    **Parameters:**
    - start - the current start position from which iteration will start.


---

<!-- prettier-ignore-end -->

<!-- document id=d0a8e60fe7c3c78822599de67565fa2b1db285fd18f9b2fec685627d0072aeb1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.paymentapi.PaymentApiHooks.md -->

<!-- prettier-ignore-start -->
# Class PaymentApiHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.paymentapi.PaymentApiHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentapi.PaymentApiHooks.md)

PaymentApiHooks interface containing extension points for customizing Payment API requests for authorization,
and their responses.


These hooks are executed in a transaction.


The extension points (hook names), and the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the exported hook function must be located
inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.




```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
     {"name": "dw.extensions.paymentapi.beforeAuthorization", "script": "./payment.ds"}
     {"name": "dw.extensions.paymentapi.afterAuthorization", "script": "./payment.ds"}
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointAfterAuthorization](#extensionpointafterauthorization): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentapi.afterAuthorization" | The extension point name dw.extensions.paymentapi.afterAuthorization. |
| [extensionPointBeforeAuthorization](#extensionpointbeforeauthorization): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentapi.beforeAuthorization" | The extension point name dw.extensions.paymentapi.beforeAuthorization. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [afterAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentapi.PaymentApiHooks.md#afterauthorizationorder-orderpaymentinstrument-object-status)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)) | <p>  Called after the response has been handled for a request to authorize payment for the given order. |
| [beforeAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentapi.PaymentApiHooks.md#beforeauthorizationorder-orderpaymentinstrument-object)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called when a request is to be made to authorize payment for the given order. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointAfterAuthorization

- extensionPointAfterAuthorization: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentapi.afterAuthorization"
  - : The extension point name dw.extensions.paymentapi.afterAuthorization.


---

### extensionPointBeforeAuthorization

- extensionPointBeforeAuthorization: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentapi.beforeAuthorization"
  - : The extension point name dw.extensions.paymentapi.beforeAuthorization.


---

## Method Details

### afterAuthorization(Order, OrderPaymentInstrument, Object, Status)
- afterAuthorization(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), payment: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), custom: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), status: [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Called after the response has been handled for a request to authorize payment for the given order.
      
      
      
      
      The given status is the result of handling the response without customization. That status will be
      used unless an implementation of this hook returns an alternative status.


    **Parameters:**
    - order - the order whose payment to authorize
    - payment - the payment instrument to authorize
    - custom - container of custom properties included in the PSP response
    - status - the result of handling the response without customization

    **Returns:**
    - a non-null result ends the hook execution


---

### beforeAuthorization(Order, OrderPaymentInstrument, Object)
- beforeAuthorization(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), payment: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), custom: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Called when a request is to be made to authorize payment for the given order.
      
      
      
      
      Return an error status to indicate a problem. The request will not be made to the payment provider.


    **Parameters:**
    - order - the order whose payment to authorize
    - payment - the payment instrument to authorize
    - custom - container for custom properties to include in request

    **Returns:**
    - a non-null result ends the hook execution


---

<!-- prettier-ignore-end -->

<!-- document id=dd436808c65b56f50eec0d9c28a88233f7be678ce9cc8735a8734f9fd487cc60 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PaymentCard.md -->

<!-- prettier-ignore-start -->
# Class PaymentCard

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.PaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md)

Represents payment cards and provides methods to access the payment card
attributes and status.


**Note:** this class handles sensitive financial and card holder data.
Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



## Property Summary

| Property | Description |
| --- | --- |
| [active](#active): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if payment card is active (enabled), otherwise 'false' is returned. |
| [cardType](#cardtype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique card type of the payment card. |
| [description](#description): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the description of the payment card. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the reference to the payment card image. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the payment card. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCardType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#getcardtype)() | Returns the unique card type of the payment card. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#getdescription)() | Returns the description of the payment card. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#getimage)() | Returns the reference to the payment card image. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#getname)() | Returns the name of the payment card. |
| [isActive](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#isactive)() | Returns 'true' if payment card is active (enabled), otherwise 'false' is returned. |
| [isApplicable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#isapplicablecustomer-string-number)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns 'true' if this payment card is applicable for the specified  customer, country and payment amount and the session currency. |
| [verify](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#verifynumber-number-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verify the card against the provided values. |
| [verify](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#verifynumber-number-string-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verify the card against the provided values. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### active
- active: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if payment card is active (enabled), otherwise 'false' is returned.


---

### cardType
- cardType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique card type of the payment card.


---

### description
- description: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the description of the payment card.


---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the reference to the payment card image.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the payment card.


---

## Method Details

### getCardType()
- getCardType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique card type of the payment card.

    **Returns:**
    - cardType of the payment card.


---

### getDescription()
- getDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the description of the payment card.

    **Returns:**
    - Description of the payment card.


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the reference to the payment card image.

    **Returns:**
    - Image of the payment card.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the payment card.

    **Returns:**
    - Name of the payment card.


---

### isActive()
- isActive(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if payment card is active (enabled), otherwise 'false' is returned.

    **Returns:**
    - true if payment card is active, otherwise false.


---

### isApplicable(Customer, String, Number)
- isApplicable(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), paymentAmount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if this payment card is applicable for the specified
      customer, country and payment amount and the session currency.
      
      
      
      The payment card is applicable if
      
      - the card is restricted by customer group, and at least one of the  groups of the specified customer is assigned to the card
      - the card is restricted by billing country, and the specified country  code is assigned to the card
      - the method is restricted by payment amount for the session currency,  and the specified payment amount is within the limits of the min/max  payment amount defined for the method and the session currency
      - the method is restricted by session currency, and the session  currency code is assigned to the method
      
      
      All parameters are optional, and if not specified, the respective
      restriction won't be validated. For example, if a card is restricted by
      billing country, but no country code is specified, this card will be
      returned, unless it is filtered out by customer group or payment amount.


    **Parameters:**
    - customer - Customer or null
    - countryCode - Billing country code or null
    - paymentAmount - Payment amount or null

    **Returns:**
    - true if payment card is applicable, false otherwise


---

### verify(Number, Number, String)
- verify(expiresMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), expiresYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), cardNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Verify the card against the provided values. This method is equivalent to
      [verify(Number, Number, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#verifynumber-number-string-string) but omits verification of the
      card security code. If the verification fails the resulting
      [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) will hold up to 2 error items each with a code:
      
      
      - [PaymentStatusCodes.CREDITCARD_INVALID_EXPIRATION_DATE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentStatusCodes.md#creditcard_invalid_expiration_date)- the expiresMonth and expiresYear do not describe a  month in the future, or describe an invalid month outside the range 1-12.
      - [PaymentStatusCodes.CREDITCARD_INVALID_CARD_NUMBER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentStatusCodes.md#creditcard_invalid_card_number)- the cardNumber does not verify against one or more configured  checks, which may include the Luhn checksum, accepted number lengths, or accepted number prefixes.


    **Parameters:**
    - expiresMonth - expiration month as integer, 1 (January) to 12 (December)
    - expiresYear - expiration year as integer, e.g. 2025
    - cardNumber - card number, a string containing digital characters

    **Returns:**
    - status indicating result


---

### verify(Number, Number, String, String)
- verify(expiresMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), expiresYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), cardNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), csc: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Verify the card against the provided values. If the verification fails the resulting
      [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) will hold up to 3 error items with these codes:
      
      
      - [PaymentStatusCodes.CREDITCARD_INVALID_EXPIRATION_DATE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentStatusCodes.md#creditcard_invalid_expiration_date)- the expiresMonth and expiresYear do not describe a  month in the future, or describe an invalid month outside the range 1-12.
      - [PaymentStatusCodes.CREDITCARD_INVALID_CARD_NUMBER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentStatusCodes.md#creditcard_invalid_card_number)- the cardNumber does not verify against one or more configured  checks, which may include the Luhn checksum, accepted number lengths, or accepted number prefixes.
      - [PaymentStatusCodes.CREDITCARD_INVALID_SECURITY_CODE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentStatusCodes.md#creditcard_invalid_security_code)- the card security code does not verify against the configured  accepted length.


    **Parameters:**
    - expiresMonth - expiration month as integer, 1 (January) to 12 (December)
    - expiresYear - expiration year as integer, e.g. 2025
    - cardNumber - card number, a string containing digital characters
    - csc - card security code, a string containing digital characters

    **Returns:**
    - status indicating result


---

<!-- prettier-ignore-end -->

<!-- document id=bb5e31c585ee1be74084c42e37b51a337eabdc89ec58f6cd77e9d5dd53874ad2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.PaymentHooks.md -->

<!-- prettier-ignore-start -->
# Class PaymentHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.PaymentHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md)

This interface represents all script hooks that can be registered to
customize the order center payment functionality. It contains the extension
points (hook names), and the functions that are called by each extension
point. A function must be defined inside a JavaScript source and must be
exported. The script with the exported hook function must be located inside a
site cartridge. Inside the site cartridge a 'package.json' file with a
'hooks' entry must exist.


"hooks": "./hooks.json"


The hooks entry links to a json file, relative to the 'package.json' file.
This file lists all registered hooks inside the hooks property:




```
"hooks": [
     {"name": "dw.order.payment.authorize", "script": "./authorize.js"},
     {"name": "dw.order.payment.validateAuthorization", "script": "./validateAuthorization.js"},
]
```




A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the  exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointAuthorize](#extensionpointauthorize): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.authorize" | The extension point name dw.order.payment.authorize. |
| [extensionPointAuthorizeCreditCard](#extensionpointauthorizecreditcard): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.authorizeCreditCard" | The extension point name dw.order.payment.authorizeCreditCard. |
| [extensionPointCapture](#extensionpointcapture): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.capture" | The extension point name dw.order.payment.capture. |
| [extensionPointReauthorize](#extensionpointreauthorize): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.reauthorize" | The extension point name dw.order.payment.reauthorize. |
| [extensionPointRefund](#extensionpointrefund): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.refund" | The extension point name dw.order.payment.refund. |
| [extensionPointReleaseAuthorization](#extensionpointreleaseauthorization): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.releaseAuthorization" | The extension point name dw.order.payment.releaseAuthorization. |
| [extensionPointValidateAuthorization](#extensionpointvalidateauthorization): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.validateAuthorization" | The extension point name dw.order.payment.validateAuthorization. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [authorize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#authorizeorder-orderpaymentinstrument)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)) | The function is called by extension point [extensionPointAuthorize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointauthorize). |
| [authorizeCreditCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#authorizecreditcardorder-orderpaymentinstrument-string)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The function is called by extension point  [extensionPointAuthorizeCreditCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointauthorizecreditcard). |
| [capture](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#captureinvoice)([Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)) | The function is called by extension point [extensionPointCapture](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointcapture). |
| [reauthorize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#reauthorizeorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | The function is called by extension point [extensionPointReauthorize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointreauthorize). |
| [refund](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#refundinvoice)([Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)) | The function is called by extension point [extensionPointRefund](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointrefund). |
| [releaseAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#releaseauthorizationorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | The function is called by extension point [extensionPointReleaseAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointreleaseauthorization). |
| [validateAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#validateauthorizationorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | The function is called by extension point [extensionPointValidateAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointvalidateauthorization). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointAuthorize

- extensionPointAuthorize: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.authorize"
  - : The extension point name dw.order.payment.authorize.
      
       This hook is optional.



---

### extensionPointAuthorizeCreditCard

- extensionPointAuthorizeCreditCard: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.authorizeCreditCard"
  - : The extension point name dw.order.payment.authorizeCreditCard.
      
       This hook is optional.



---

### extensionPointCapture

- extensionPointCapture: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.capture"
  - : The extension point name dw.order.payment.capture.


---

### extensionPointReauthorize

- extensionPointReauthorize: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.reauthorize"
  - : The extension point name dw.order.payment.reauthorize.


---

### extensionPointRefund

- extensionPointRefund: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.refund"
  - : The extension point name dw.order.payment.refund.


---

### extensionPointReleaseAuthorization

- extensionPointReleaseAuthorization: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.releaseAuthorization"
  - : The extension point name dw.order.payment.releaseAuthorization.


---

### extensionPointValidateAuthorization

- extensionPointValidateAuthorization: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.payment.validateAuthorization"
  - : The extension point name dw.order.payment.validateAuthorization.


---

## Method Details

### authorize(Order, OrderPaymentInstrument)
- authorize(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), paymentDetails: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointAuthorize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointauthorize). Custom payment authorization - modify the
      order as needed.
      
      
      - Prerequisite: An order has been created using the data api or via the storefront.
      - Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).
      - Return Status.ERROR: Order is held, authorization needs to be repeated.


    **Parameters:**
    - order - the order
    - paymentDetails - specified payment details

    **Returns:**
    - 
      - Status.OK successful authorization.
      - Status.ERROR authorization failed.



---

### authorizeCreditCard(Order, OrderPaymentInstrument, String)
- authorizeCreditCard(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), paymentDetails: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), cvn: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point
      [extensionPointAuthorizeCreditCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointauthorizecreditcard). Custom payment authorization
      of a credit card - modify the order as needed.
      
      
      
      - Prerequisite: An order has been created using the data api or via the  storefront.
      - Return Status.OK: Corresponding payment transaction is marked as  authorized (usually a custom property is used for this).
      - Return Status.ERROR: Order is held, authorization needs to be  repeated.


    **Parameters:**
    - order - the order
    - paymentDetails - specified payment details
    - cvn - the credit card verification number

    **Returns:**
    - 
      - Status.OK successful authorization.
      - Status.ERROR          authorization failed.



---

### capture(Invoice)
- capture(invoice: [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointCapture](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointcapture). Custom payment capture - modify the order as needed.
      
      
      
      - Prerequisite:  
      \[ either \] As a result of shipping (or part-shipping) a shipping -order the warehouse updates the status of the shipping-order  resulting in the creation of an unpaid debit invoice (the creation of the invoice is usually handled in  [ShippingOrderHooks.changeStatus(ShippingOrder, ShippingOrderWO)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#changestatusshippingorder-shippingorderwo)).  
      \[ or \] A unpaid debit invoice has been created using the data api. 
      - Context: An unpaid debit invoice is passed to the payment system for capture. The capture attempt can either succeed (complete  invoice amount captured) or fail. As a result the invoice status is updated by ordercenter for further processing. See [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).
      - Hook responsibility: The hook should attempt to capture the amount located in invoice.grandTotal.grossPrice. When successful,  the capture hook should also update the invoice by calling  [Invoice.addCaptureTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addcapturetransactionorderpaymentinstrument-money)which serves to record the capturedAmount and associate the invoice with the payment-transaction.
      - Return Status.OK: Indicates capture succeeded: Order Center sets the Invoice status to [Invoice.STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid).
      - Return Status.ERROR: Indicates capture failed: Order Center sets the Invoice status to [Invoice.STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed)for  further processing.
      - Post processing:  When the capture hook returns with success, order center not only sets the relevant invoice status, but also  sets the relevant capturedAmount values on the invoice item. Returning success means the entire invoice total has been captured, so each item  within the invoice can also be marked as completely captured. Note the script implementing the hook can take responsibility for this if desired  order center will not overwrite existing values, but normally the standard implementation fits. As a result each invoice item and the related  order item can return a capturedAmount, useful for calculating possible refunds. 


    **Parameters:**
    - invoice - the invoice

    **Returns:**
    - 
      - Status.OK for successful capture of entire invoice amount.
      - Status.ERROR capture failed



---

### reauthorize(Order)
- reauthorize(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointReauthorize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointreauthorize). Custom payment authorization - modify the
      order as needed.
      
      
      - Prerequisite:  
      \[ either \] Based on a selected [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), a [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)(which represents the whole or part of the order which can be shipped)  is to be created ready for export to the warehouse system.  
      \[ or \] A [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)is to be directly created using the data api.
      - Context: The related order is passed to the payment hook to check its authorization has not become invalid. Two hooks are called:  
      a. [validateAuthorization(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#validateauthorizationorder)is used to check the orders authorization is still valid  
      b. [reauthorize(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#reauthorizeorder)is called if step a. returns Error  
      - Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).  If the order had been previously authorized, the custom property values may be overwritten during reauthorization.
      - Return Status.ERROR: Order is held, authorization needs to be repeated.


    **Parameters:**
    - order - the order

    **Returns:**
    - 
      - Status.OK successful authorization.
      - Status.ERROR authorization failed



---

### refund(Invoice)
- refund(invoice: [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointRefund](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointrefund). Custom payment refund - modify the order as needed.
      
      
      
      - Prerequisite:  
      \[ either \] Goods returned by the customer result in the creation of one or more return documents, resulting in the creation of an  unpaid customer credit invoice (the creation of the invoice is usually handled in [ReturnHooks.changeStatus(Return, ReturnWO)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#changestatusreturn-returnwo)).  
      \[ or \] An unpaid customer credit invoice is created using the data api (perhaps as a result of the creation of a customer appeasement).
      - Context: An unpaid credit invoice is passed to the payment system for refund. The refund attempt can either succeed (complete  invoice amount refunded) or fail. As a result the invoice status is updated by ordercenter for further processing. See [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).
      - Hook responsibility: The hook should attempt to refund the amount located in invoice.grandTotal.grossPrice. When successful,  the refund hook should also update the invoice by calling  [Invoice.addRefundTransaction(OrderPaymentInstrument, Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#addrefundtransactionorderpaymentinstrument-money)which serves to record the refundedAmount and associate the invoice with the payment-transaction.
      - Return Status.OK: Indicates refund succeeded: Order Center sets the Invoice status to [Invoice.STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_paid).
      - Return Status.ERROR: Indicates refund failed: Order Center sets the Invoice status to [Invoice.STATUS_FAILED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_failed)for  further processing.
      - Post processing:  When the refund hook returns with success, order center not only sets the relevant invoice status, but also  sets the relevant refundAmount values on the invoice item. Returning success means the entire invoice total has been refunded, so each item  within the invoice can also be marked as completely refunded. Note the script implementing the hook can take responsibility for this if desired  order center will not overwrite existing values, but normally the standard implementation fits. As a result each invoice item and the related  order item can return a refundedAmount, useful for calculating further possible refunds. 


    **Parameters:**
    - invoice - the invoice

    **Returns:**
    - 
      - Status.OK for successful refund of entire invoice amount.
      - Status.ERROR refund failed



---

### releaseAuthorization(Order)
- releaseAuthorization(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointReleaseAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointreleaseauthorization).
      Custom payment release authorization - modify the order as needed.
      
      
      
      - Prerequisite: an authorized order is updated resulting in a need to release the remaining authorization. This happens when:  
      - order is cancelled  
      - order is complete after remaining order items are cancelled.
      - Return Status.OK - successful release authorization 
      - Return Status.ERROR - failed release authorization 


    **Parameters:**
    - order - the order

    **Returns:**
    - 
      - Status.OK for successful release authorization.
      - Status.ERROR failed release authorization



---

### validateAuthorization(Order)
- validateAuthorization(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointValidateAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#extensionpointvalidateauthorization). Custom payment authorization - modify the
      order as needed.
      
      
      - Context: This hook is called to validate whether a payment authorization exists for the order. It should usually check:  
      - Whether the authorize or reauthorize hook was previously successfully executed for the order, e.g. by checking whether custom property has been previously set.  
      - Whether an existing authorization has expired e.g. by comparing a timestamp set on authorization with the current time.
      - Return Status.OK: indicates the order has a valid payment authorization.
      - Return Status.ERROR: indicates [reauthorize(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#reauthorizeorder)should be called.
      See [reauthorize(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#reauthorizeorder) for more details.


    **Parameters:**
    - order - the order

    **Returns:**
    - 
      - Status.OK order has a valid payment authorization.
      - Status.ERROR order has no valid payment authorization, [reauthorize(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md#reauthorizeorder)should be called



---

<!-- prettier-ignore-end -->

<!-- document id=cdc8f987955c7441715a9366f606976f1517659e2ee597dd794e5292bba71093 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PaymentInstrument.md -->

<!-- prettier-ignore-start -->
# Class PaymentInstrument

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md)
        - [dw.order.PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md)

Base class for payment instrument either stored in the customers profile
or related to an order. A payment instrument can be credit card
or bank transfer. The object defines standard methods for credit card
payment, and can be extended by attributes appropriate for other
payment methods.


**Note:** this class handles sensitive financial and card holder data.
Pay special attention to PCI DSS v3. requirements 1, 3, 7, and 9.



## All Known Subclasses
[CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[ENCRYPTION_ALGORITHM_RSA](#encryption_algorithm_rsa): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA"~~ | The outdated encryption algorithm "RSA/ECB/PKCS1Padding". |
| [ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding" | The encryption algorithm "RSA/ECB/OAEPWithSHA-256AndMGF1Padding". |
| [METHOD_BANK_TRANSFER](#method_bank_transfer): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BANK_TRANSFER" | Represents a bank transfer type of payment. |
| [METHOD_BML](#method_bml): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BML" | Represents a 'bill me later' type of payment. |
| [METHOD_CREDIT_CARD](#method_credit_card): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDIT_CARD" | Represents a credit card type of payment. |
| [METHOD_DW_ANDROID_PAY](#method_dw_android_pay): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DW_ANDROID_PAY" | Represents an Android Pay payment. |
| [METHOD_DW_APPLE_PAY](#method_dw_apple_pay): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DW_APPLE_PAY" | Represents an Apple Pay payment. |
| [METHOD_GIFT_CERTIFICATE](#method_gift_certificate): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFT_CERTIFICATE" | Represents a gift certificate. |

## Property Summary

| Property | Description |
| --- | --- |
| [bankAccountDriversLicense](#bankaccountdriverslicense): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the driver's license number associated with the bank account if the  calling context meets the following criteria: <br/>  <ul>  <li>  If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  </li>  </ul> |
| [bankAccountDriversLicenseLastDigits](#bankaccountdriverslicenselastdigits): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 characters of the decrypted driver's license number of  the bank account associated with this PaymentInstrument. |
| [bankAccountDriversLicenseStateCode](#bankaccountdriverslicensestatecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the driver's license state code associated with a bank account payment instrument. |
| [bankAccountHolder](#bankaccountholder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the full name of the holder of a bank account payment instrument. |
| [bankAccountNumber](#bankaccountnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the bank account number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  </li>  </ul> |
| [bankAccountNumberLastDigits](#bankaccountnumberlastdigits): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 characters of the decrypted bank account number. |
| [bankRoutingNumber](#bankroutingnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the bank routing number of a bank account payment instrument. |
| [creditCardExpirationMonth](#creditcardexpirationmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the month of the year in which the credit card  expires (1-12). |
| [creditCardExpirationYear](#creditcardexpirationyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the year in which the credit card  expires, such as '2004'. |
| [creditCardExpired](#creditcardexpired): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this payment instrument represents an expired credit  card. |
| [creditCardHolder](#creditcardholder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the credit card owner. |
| [creditCardIssueNumber](#creditcardissuenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the credit card issue number. |
| [creditCardNumber](#creditcardnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the decrypted credit card number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrument in the context of a storefront request, and  the current authenticated customer is referenced by the basket or order, and  the current protocol is HTTPS. |
| [creditCardNumberLastDigits](#creditcardnumberlastdigits): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 characters of the decrypted credit card number. |
| [creditCardToken](#creditcardtoken): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Secure credit card data can be replaced by a token by utilizing a  tokenization provider, which securely stores the credit card data using  the token as a key. |
| [creditCardType](#creditcardtype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the type of the credit card. |
| [creditCardValidFromMonth](#creditcardvalidfrommonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the month of the year in which the credit card became  valid (1-12). |
| [creditCardValidFromYear](#creditcardvalidfromyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the year in which the credit card became valid, such as '2001'. |
| [giftCertificateCode](#giftcertificatecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Gift Certificate code for this Payment Instrument. |
| ~~[giftCertificateID](#giftcertificateid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Returns the Gift Certificate ID for this Payment Instrument. |
| [maskedBankAccountDriversLicense](#maskedbankaccountdriverslicense): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the decrypted driver's license number of the bank account with  all but the last 4 characters replaced with a '\*' character. |
| [maskedBankAccountNumber](#maskedbankaccountnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the decrypted bank account number with  all but the last 4 characters replaced with a '\*' character. |
| [maskedCreditCardNumber](#maskedcreditcardnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the decrypted credit card number with  all but the last 4 characters replaced with a '\*' character. |
| [maskedGiftCertificateCode](#maskedgiftcertificatecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the masked gift certificate code with  all but the last 4 characters replaced with a '\*' character. |
| [paymentMethod](#paymentmethod): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the identifier of the payment method represented by this  payment instrument. |
| [permanentlyMasked](#permanentlymasked): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if the account information for this Payment Instrument  has been permanently masked as a result of the data retention security policy  for the site or a creditcard tokenization, and `false` otherwise. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicense)() | Returns the driver's license number associated with the bank account if the  calling context meets the following criteria: <br/>  <ul>  <li>  If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  </li>  </ul> |
| [getBankAccountDriversLicenseLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicenselastdigits)() | Returns the last 4 characters of the decrypted driver's license number of  the bank account associated with this PaymentInstrument. |
| [getBankAccountDriversLicenseLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicenselastdigitsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the last specified number of characters of the decrypted driver's license number of  the bank account associated with this PaymentInstrument. |
| [getBankAccountDriversLicenseStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountdriverslicensestatecode)() | Returns the driver's license state code associated with a bank account payment instrument. |
| [getBankAccountHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountholder)() | Returns the full name of the holder of a bank account payment instrument. |
| [getBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumber)() | Returns the bank account number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  </li>  <li>  If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  </li>  </ul> |
| [getBankAccountNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumberlastdigits)() | Returns the last 4 characters of the decrypted bank account number. |
| [getBankAccountNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankaccountnumberlastdigitsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the last specified number of characters of the decrypted bank account card number. |
| [getBankRoutingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getbankroutingnumber)() | Returns the bank routing number of a bank account payment instrument. |
| [getCreditCardExpirationMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardexpirationmonth)() | Returns the month of the year in which the credit card  expires (1-12). |
| [getCreditCardExpirationYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardexpirationyear)() | Returns the year in which the credit card  expires, such as '2004'. |
| [getCreditCardHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardholder)() | Returns the name of the credit card owner. |
| [getCreditCardIssueNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardissuenumber)() | Returns the credit card issue number. |
| [getCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumber)() | Returns the decrypted credit card number if the calling context meets  the following criteria: <br/>  <ul>  <li>  If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  </li>  <li>  If the instance is a OrderPaymentInstrument in the context of a storefront request, and  the current authenticated customer is referenced by the basket or order, and  the current protocol is HTTPS. |
| [getCreditCardNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumberlastdigits)() | Returns the last 4 characters of the decrypted credit card number. |
| [getCreditCardNumberLastDigits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardnumberlastdigitsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the last specified number of characters of the decrypted credit card number. |
| [getCreditCardToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardtoken)() | Secure credit card data can be replaced by a token by utilizing a  tokenization provider, which securely stores the credit card data using  the token as a key. |
| [getCreditCardType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardtype)() | Returns the type of the credit card. |
| [getCreditCardValidFromMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardvalidfrommonth)() | Returns the month of the year in which the credit card became  valid (1-12). |
| [getCreditCardValidFromYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getcreditcardvalidfromyear)() | Returns the year in which the credit card became valid, such as '2001'. |
| [getEncryptedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedbankaccountdriverslicensestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Encrypts the driver's license number of the bank account of this object with the given algorithm and the given  public key. |
| [getEncryptedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedbankaccountnumberstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Encrypts the bank account number of this object with the given algorithm and the given public key. |
| [getEncryptedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedcreditcardnumberstring-certificateref)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)) | Encrypts the credit card number of this object with the given algorithm and the public key taken from a  certificate in the keystore. |
| ~~[getEncryptedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedcreditcardnumberstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Encrypts the credit card number of this object with the given algorithm and the given public key. |
| [getGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificatecode)() | Returns the Gift Certificate code for this Payment Instrument. |
| ~~[getGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificateid)()~~ | Returns the Gift Certificate ID for this Payment Instrument. |
| [getMaskedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountdriverslicense)() | Returns the decrypted driver's license number of the bank account with  all but the last 4 characters replaced with a '\*' character. |
| [getMaskedBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountdriverslicensenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the decrypted driver's license number of the bank account with  all but the specified number characters replaced with a '\*' character. |
| [getMaskedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountnumber)() | Returns the decrypted bank account number with  all but the last 4 characters replaced with a '\*' character. |
| [getMaskedBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedbankaccountnumbernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the decrypted bank account number with  all but the specified number characters replaced with a '\*' character. |
| [getMaskedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedcreditcardnumber)() | Returns the decrypted credit card number with  all but the last 4 characters replaced with a '\*' character. |
| [getMaskedCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedcreditcardnumbernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the decrypted credit card number with  all but the specified number characters replaced with a '\*' character. |
| [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedgiftcertificatecode)() | Returns the masked gift certificate code with  all but the last 4 characters replaced with a '\*' character. |
| [getMaskedGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getmaskedgiftcertificatecodenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the masked gift certificate code with  all but the specified number of characters replaced with a '\*' character. |
| [getPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getpaymentmethod)() | Returns the identifier of the payment method represented by this  payment instrument. |
| [isCreditCardExpired](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#iscreditcardexpired)() | Returns true if this payment instrument represents an expired credit  card. |
| [isPermanentlyMasked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)() | Returns `true` if the account information for this Payment Instrument  has been permanently masked as a result of the data retention security policy  for the site or a creditcard tokenization, and `false` otherwise. |
| [setBankAccountDriversLicense](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountdriverslicensestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the driver's license number associated with a bank account payment instrument. |
| [setBankAccountDriversLicenseStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountdriverslicensestatecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the driver's license state code associated with a bank account payment instrument. |
| [setBankAccountHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountholderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the full name of the holder of a bank account payment instrument. |
| [setBankAccountNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankaccountnumberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the bank account number of a bank account payment instrument. |
| [setBankRoutingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setbankroutingnumberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the bank routing number of a bank account payment instrument. |
| [setCreditCardExpirationMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardexpirationmonthnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the month of the year in which the credit card  expires. |
| [setCreditCardExpirationYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardexpirationyearnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the year in which the credit card  expires, such as '2004'. |
| [setCreditCardHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardholderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the credit card owner. |
| [setCreditCardIssueNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardissuenumberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the credit card issue number. |
| [setCreditCardNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardnumberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the credit card number for this payment. |
| [setCreditCardToken](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardtokenstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Secure credit card data can be replaced by a token by utilizing a  tokenization provider, which securely stores the credit card data using  the token as a key. |
| [setCreditCardType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardtypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the type of the credit card. |
| [setCreditCardValidFromMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardvalidfrommonthnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the month of the year in which the credit card became valid (1-12). |
| [setCreditCardValidFromYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setcreditcardvalidfromyearnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the year in which the credit card became valid, such as '2001'. |
| [setGiftCertificateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setgiftcertificatecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Gift Certificate code for this Payment Instrument. |
| ~~[setGiftCertificateID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setgiftcertificateidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the Gift Certificate ID for this Payment Instrument. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ENCRYPTION_ALGORITHM_RSA

- ~~ENCRYPTION_ALGORITHM_RSA: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA"~~
  - : The outdated encryption algorithm "RSA/ECB/PKCS1Padding". Please do not use anymore!

    **Deprecated:**
**warning:** Support for this algorithm will be removed in a future release. Please use
            [ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) instead.

---

### ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING

- ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA/ECB/OAEPWithSHA-256AndMGF1Padding"
  - : The encryption algorithm "RSA/ECB/OAEPWithSHA-256AndMGF1Padding".


---

### METHOD_BANK_TRANSFER

- METHOD_BANK_TRANSFER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BANK_TRANSFER"
  - : Represents a bank transfer type of payment.


---

### METHOD_BML

- METHOD_BML: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BML"
  - : Represents a 'bill me later' type of payment.


---

### METHOD_CREDIT_CARD

- METHOD_CREDIT_CARD: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDIT_CARD"
  - : Represents a credit card type of payment.


---

### METHOD_DW_ANDROID_PAY

- METHOD_DW_ANDROID_PAY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DW_ANDROID_PAY"
  - : Represents an Android Pay payment.


---

### METHOD_DW_APPLE_PAY

- METHOD_DW_APPLE_PAY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DW_APPLE_PAY"
  - : Represents an Apple Pay payment.


---

### METHOD_GIFT_CERTIFICATE

- METHOD_GIFT_CERTIFICATE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GIFT_CERTIFICATE"
  - : Represents a gift certificate.


---

## Property Details

### bankAccountDriversLicense
- bankAccountDriversLicense: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the driver's license number associated with the bank account if the
      calling context meets the following criteria: 
      
      
      - If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  
      - If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  
      
      
      
      Otherwise, the method returns the masked driver's license number. If a basket is reopened with
      [OrderMgr.failOrder(Order, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean), it always masks sensitive information
      because during order creation, basket payment information is permanently masked.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### bankAccountDriversLicenseLastDigits
- bankAccountDriversLicenseLastDigits: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 characters of the decrypted driver's license number of
      the bank account associated with this PaymentInstrument.
      
      If the number is empty or null
      it will be returned without an exception.



---

### bankAccountDriversLicenseStateCode
- bankAccountDriversLicenseStateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the driver's license state code associated with a bank account payment instrument.
      Returns null for other payment methods.



---

### bankAccountHolder
- bankAccountHolder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the full name of the holder of a bank account payment instrument.
      Returns null for other payment methods.



---

### bankAccountNumber
- bankAccountNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank account number if the calling context meets
      the following criteria: 
      
      
      - If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  
      - If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  
      
      
      
      Otherwise, the method returns the masked bank account number. If a basket is reopened with
      [OrderMgr.failOrder(Order, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean), it always masks sensitive information
      because during order creation, basket payment information is permanently masked.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### bankAccountNumberLastDigits
- bankAccountNumberLastDigits: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 characters of the decrypted bank account number.
      
      If the number is empty or null,
      it will be returned without an exception.



---

### bankRoutingNumber
- bankRoutingNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank routing number of a bank account payment instrument.
      Returns null for other payment methods.
      
      If account information has been masked due to the data retention security
      policy for the site, the return value is fully masked.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### creditCardExpirationMonth
- creditCardExpirationMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the month of the year in which the credit card
      expires (1-12).



---

### creditCardExpirationYear
- creditCardExpirationYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the year in which the credit card
      expires, such as '2004'.



---

### creditCardExpired
- creditCardExpired: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this payment instrument represents an expired credit
      card. This check is only logical if the credit card expiration month and
      year are set. If either of these attributes are not set, then this method
      always returns false.



---

### creditCardHolder
- creditCardHolder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the credit card owner.


---

### creditCardIssueNumber
- creditCardIssueNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the credit card issue number.  This attribute is only used by
      specific credit/debit card processors such as Solo and Switch in the UK.



---

### creditCardNumber
- creditCardNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted credit card number if the calling context meets
      the following criteria: 
      
      
      - If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrument in the context of a storefront request, and  the current authenticated customer is referenced by the basket or order, and  the current protocol is HTTPS.  
      - If the customer is anonymous, and the customer is referenced by the order, and the protocol is secure and  the order status is CREATED.  
      - If the instance is a OrderPaymentInstrument, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  
      - If the instance is a OrderPaymentInstrument, and the account information  has not been masked as a result of the data retention security policy  for the site  
      
      
      
      Otherwise, the method returns the masked credit card number. If a basket is reopened with
      [OrderMgr.failOrder(Order, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean), it always masks sensitive information
      because during order creation, basket payment information is permanently masked.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### creditCardNumberLastDigits
- creditCardNumberLastDigits: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 characters of the decrypted credit card number.
      
      If the number is empty or null
      it will be returned without an exception.



---

### creditCardToken
- creditCardToken: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Secure credit card data can be replaced by a token by utilizing a
      tokenization provider, which securely stores the credit card data using
      the token as a key. The stored data can later reused by including the
      token in a request. In this way credit card processes such as
      authorization and capture can be implemented without being responsible
      for persisting the credit card data.



---

### creditCardType
- creditCardType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the credit card.


---

### creditCardValidFromMonth
- creditCardValidFromMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the month of the year in which the credit card became
      valid (1-12).  This attribute is not used by all credit card types.



---

### creditCardValidFromYear
- creditCardValidFromYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the year in which the credit card became valid, such as '2001'.
      This attribute is not used by all credit card types.



---

### giftCertificateCode
- giftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Gift Certificate code for this Payment Instrument.


---

### giftCertificateID
- ~~giftCertificateID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the Gift Certificate ID for this Payment Instrument.

    **Deprecated:**
**warning:** Use [getGiftCertificateCode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificatecode)

---

### maskedBankAccountDriversLicense
- maskedBankAccountDriversLicense: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the decrypted driver's license number of the bank account with
      all but the last 4 characters replaced with a '\*' character.
      
      If the driver's license number is empty,
      it will be returned without an exception.



---

### maskedBankAccountNumber
- maskedBankAccountNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the decrypted bank account number with
      all but the last 4 characters replaced with a '\*' character.
      
      If the number is empty (i.e. "" or null),
      it will be returned without an exception.



---

### maskedCreditCardNumber
- maskedCreditCardNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the decrypted credit card number with
      all but the last 4 characters replaced with a '\*' character.
      
      If the number is empty,
      it will be returned without an exception.



---

### maskedGiftCertificateCode
- maskedGiftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the masked gift certificate code with
      all but the last 4 characters replaced with a '\*' character.



---

### paymentMethod
- paymentMethod: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the identifier of the payment method represented by this
      payment instrument.



---

### permanentlyMasked
- permanentlyMasked: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if the account information for this Payment Instrument
      has been permanently masked as a result of the data retention security policy
      for the site or a creditcard tokenization, and `false` otherwise.
      
      When account information is masked only the last 4 digits of the credit card
      or bank account number are recoverable.  The bank account driver's license number
      and bank routing number are completely masked.



---

## Method Details

### getBankAccountDriversLicense()
- getBankAccountDriversLicense(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the driver's license number associated with the bank account if the
      calling context meets the following criteria: 
      
      
      - If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  
      - If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  
      
      
      
      Otherwise, the method returns the masked driver's license number. If a basket is reopened with
      [OrderMgr.failOrder(Order, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean), it always masks sensitive information
      because during order creation, basket payment information is permanently masked.


    **Returns:**
    - the driver's license number if the calling context meets
      the necessary criteria.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getBankAccountDriversLicenseLastDigits()
- getBankAccountDriversLicenseLastDigits(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 characters of the decrypted driver's license number of
      the bank account associated with this PaymentInstrument.
      
      If the number is empty or null
      it will be returned without an exception.


    **Returns:**
    - the last 4 characters of the de-crypted driver's license number.


---

### getBankAccountDriversLicenseLastDigits(Number)
- getBankAccountDriversLicenseLastDigits(count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last specified number of characters of the decrypted driver's license number of
      the bank account associated with this PaymentInstrument.
      
      If the number is empty (i.e. "" or null),
      it will be returned without an exception.
      
      Note that `count` is limited to 4 in an unsecure environment,
      and if account information for this payment instrument has been masked
      due to the data retention security policy for the site.


    **Parameters:**
    - count - number of characters to be returned.

    **Returns:**
    - the last specified number of characters of the decrypted driver's license number.

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getBankAccountDriversLicenseStateCode()
- getBankAccountDriversLicenseStateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the driver's license state code associated with a bank account payment instrument.
      Returns null for other payment methods.


    **Returns:**
    - the state in which the bank account driver's license was issued.


---

### getBankAccountHolder()
- getBankAccountHolder(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the full name of the holder of a bank account payment instrument.
      Returns null for other payment methods.


    **Returns:**
    - the bank account holder's full name.


---

### getBankAccountNumber()
- getBankAccountNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank account number if the calling context meets
      the following criteria: 
      
      
      - If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a storefront request, and the current customer is identical  to the customer related to the basket, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrumentInfo, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  
      - If the instance is a OrderPaymentInstrumentInfo, and the account information  has not been masked as a result of the data retention security policy  for the site  
      
      
      
      Otherwise, the method returns the masked bank account number. If a basket is reopened with
      [OrderMgr.failOrder(Order, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean), it always masks sensitive information
      because during order creation, basket payment information is permanently masked.


    **Returns:**
    - the bank account number if the calling context meets
      the necessary criteria.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getBankAccountNumberLastDigits()
- getBankAccountNumberLastDigits(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 characters of the decrypted bank account number.
      
      If the number is empty or null,
      it will be returned without an exception.


    **Returns:**
    - the last 4 characters of the decrypted bank account number.


---

### getBankAccountNumberLastDigits(Number)
- getBankAccountNumberLastDigits(count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last specified number of characters of the decrypted bank account card number.
      
      If the number is empty (i.e. "" or null),
      it will be returned without an exception.
      
      Note that `count` is limited to 4 in an unsecure environment,
      and if account information for this payment instrument has been masked
      due to the data retention security policy for the site.


    **Parameters:**
    - count - number of characters to be returned.

    **Returns:**
    - the last specified characters of the decrypted bank account number.

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getBankRoutingNumber()
- getBankRoutingNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank routing number of a bank account payment instrument.
      Returns null for other payment methods.
      
      If account information has been masked due to the data retention security
      policy for the site, the return value is fully masked.


    **Returns:**
    - the bank account rounting number.

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getCreditCardExpirationMonth()
- getCreditCardExpirationMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the month of the year in which the credit card
      expires (1-12).


    **Returns:**
    - the month of the year in which the credit card
      expires (1-12).



---

### getCreditCardExpirationYear()
- getCreditCardExpirationYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the year in which the credit card
      expires, such as '2004'.


    **Returns:**
    - the year in which the credit card
      expires.



---

### getCreditCardHolder()
- getCreditCardHolder(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the credit card owner.

    **Returns:**
    - the name of the credit card owner.


---

### getCreditCardIssueNumber()
- getCreditCardIssueNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the credit card issue number.  This attribute is only used by
      specific credit/debit card processors such as Solo and Switch in the UK.


    **Returns:**
    - the credit card issue number


---

### getCreditCardNumber()
- getCreditCardNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted credit card number if the calling context meets
      the following criteria: 
      
      
      - If the instance is a CustomerPaymentInstrument, and  we are in the context of a storefront request, and the current customer  is registered and authenticated, and the payment instrument is associated  to the profile of the current customer, and the current protocol is HTTPS  
      - If the instance is a OrderPaymentInstrument in the context of a storefront request, and  the current authenticated customer is referenced by the basket or order, and  the current protocol is HTTPS.  
      - If the customer is anonymous, and the customer is referenced by the order, and the protocol is secure and  the order status is CREATED.  
      - If the instance is a OrderPaymentInstrument, and we are in  the context of a business manager request, and the current user has the  permission MANAGE\_ORDERS  
      - If the instance is a OrderPaymentInstrument, and the account information  has not been masked as a result of the data retention security policy  for the site  
      
      
      
      Otherwise, the method returns the masked credit card number. If a basket is reopened with
      [OrderMgr.failOrder(Order, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#failorderorder-boolean), it always masks sensitive information
      because during order creation, basket payment information is permanently masked.


    **Returns:**
    - the decrypted credit card number if the calling context meets
      the necessary criteria.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getCreditCardNumberLastDigits()
- getCreditCardNumberLastDigits(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 characters of the decrypted credit card number.
      
      If the number is empty or null
      it will be returned without an exception.


    **Returns:**
    - the last 4 characters of the de-crypted credit card number.


---

### getCreditCardNumberLastDigits(Number)
- getCreditCardNumberLastDigits(count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last specified number of characters of the decrypted credit card number.
      
      If the number is empty (i.e. "" or null),
      it will be returned without an exception.
      
      Note that `count` is limited to 4 in an unsecure environment,
      and if account information for this payment instrument has been masked
      due to the data retention security policy for the site.


    **Parameters:**
    - count - number of characters to be returned.

    **Returns:**
    - the last specified number of characters of the decrypted credit card number.

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getCreditCardToken()
- getCreditCardToken(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Secure credit card data can be replaced by a token by utilizing a
      tokenization provider, which securely stores the credit card data using
      the token as a key. The stored data can later reused by including the
      token in a request. In this way credit card processes such as
      authorization and capture can be implemented without being responsible
      for persisting the credit card data.


    **Returns:**
    - the token


---

### getCreditCardType()
- getCreditCardType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the credit card.

    **Returns:**
    - the type of the credit card.


---

### getCreditCardValidFromMonth()
- getCreditCardValidFromMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the month of the year in which the credit card became
      valid (1-12).  This attribute is not used by all credit card types.


    **Returns:**
    - the month of the year in which the credit card became
      valid (1-12).



---

### getCreditCardValidFromYear()
- getCreditCardValidFromYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the year in which the credit card became valid, such as '2001'.
      This attribute is not used by all credit card types.


    **Returns:**
    - the year in which the credit card became valid


---

### getEncryptedBankAccountDriversLicense(String, String)
- getEncryptedBankAccountDriversLicense(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypts the driver's license number of the bank account of this object with the given algorithm and the given
      public key. Returned is the Base64 encoded representation of the result.
      
      
      See also [Cipher.encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2) on how to generate RSA key
      pairs.
      
      
      If account information has been masked due to the data retention security policy for the site, the returned value
      is the Base64 encoded representation of the encrypted form of the masked number.


    **Parameters:**
    - algorithm - The algorithm to be used for the encryption of this credit card number. Must be a valid,             non-null algorithm. Currently, only the following algorithms are supported:                          <li>[ENCRYPTION_ALGORITHM_RSA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa) – outdated, please do not use anymore             <li>[ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) – the current algorithm             </ul>
    - publicKey - A Base64 encoded form of the public key to be used to encrypt this bank account driver's license             number. Must be a valid, non-blank key.

    **Returns:**
    - the Base64 encoded representation of the bank account driver's license.

    **Throws:**
    - IllegalArgumentException - If `algorithm` is not a valid known algorithm.
    - IllegalArgumentException - If `publicKey` is a null, empty or blank string.


---

### getEncryptedBankAccountNumber(String, String)
- getEncryptedBankAccountNumber(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypts the bank account number of this object with the given algorithm and the given public key. Returned is
      the Base64 encoded representation of the result.
      
      
      If account information has been masked due to the data retention security policy for the site, the returned value
      is the Base64 encoded representation of the encrypted form of the masked number.


    **Parameters:**
    - algorithm - The algorithm to be used for the encryption of this credit card number. Must be a valid,             non-null algorithm. Currently, only the following algorithms are supported:                          <li>[ENCRYPTION_ALGORITHM_RSA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa) – outdated, please do not use anymore             <li>[ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) – the current algorithm             </ul>
    - publicKey - A Base64 encoded form of the public key to be used to encrypt this credit card number. Must be a             valid, non-blank key.

    **Returns:**
    - the Base64 encoded representation of the bank account number.

    **Throws:**
    - IllegalArgumentException - If `algorithm` is not a valid known algorithm.
    - IllegalArgumentException - If `publicKey` is a null, empty or blank string.

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getEncryptedCreditCardNumber(String, CertificateRef)
- getEncryptedCreditCardNumber(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), certificateRef: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypts the credit card number of this object with the given algorithm and the public key taken from a
      certificate in the keystore. Returned is the Base64 encoded representation of the result.
      
      
      See also [Cipher.encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-2) on how to generate RSA
      key pairs.
      
      
      If account information has been masked due to the data retention security policy for the site, the returned value
      is the Base64 encoded representation of the encrypted form of the masked number.


    **Parameters:**
    - algorithm - The algorithm to be used for the encryption of this credit card number. Must be a valid,             non-null algorithm. Currently, only the following algorithms are supported:                          <li>[ENCRYPTION_ALGORITHM_RSA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa) – outdated, please do not use anymore             <li>[ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) – the current algorithm             </ul>
    - certificateRef - A reference to a trusted certificate entry containing the public key in the             keystore. Must be non-null.

    **Returns:**
    - the Base64 encoded representation of the credit card number.

    **Throws:**
    - IllegalArgumentException - If `algorithm` is not a valid known algorithm.
    - IllegalArgumentException - If `certificateRef` is `null` or could not be found.

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getEncryptedCreditCardNumber(String, String)
- ~~getEncryptedCreditCardNumber(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Encrypts the credit card number of this object with the given algorithm and the given public key. Returned is the
      Base64 encoded representation of the result.
      
      
      See also [Cipher.encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2) on how to generate RSA key
      pairs.
      
      
      If account information has been masked due to the data retention security policy for the site, the returned value
      is the Base64 encoded representation of the encrypted form of the masked number.


    **Parameters:**
    - algorithm - The algorithm to be used for the encryption of this credit card number. Must be a valid,             non-null algorithm. Currently, only the following algorithms are supported:                          <li>[ENCRYPTION_ALGORITHM_RSA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa) – outdated, please do not use anymore             <li>[ENCRYPTION_ALGORITHM_RSA_ECB_OAEPWITHSHA_256ANDMGF1PADDING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#encryption_algorithm_rsa_ecb_oaepwithsha_256andmgf1padding) – the current algorithm             </ul>
    - publicKey - A Base64 encoded form of the public key to be used to encrypt this credit card number. Must be a             valid, non-blank key.

    **Returns:**
    - the Base64 encoded representation of the credit card number.

    **Throws:**
    - IllegalArgumentException - If `algorithm` is not a valid known algorithm.
    - IllegalArgumentException - If `publicKey` is a null, empty or blank string.

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)

    **Deprecated:**
**warning:** Please use [getEncryptedCreditCardNumber(String, CertificateRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getencryptedcreditcardnumberstring-certificateref) instead.

---

### getGiftCertificateCode()
- getGiftCertificateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Gift Certificate code for this Payment Instrument.

    **Returns:**
    - the Gift Certificate code or null if not set.


---

### getGiftCertificateID()
- ~~getGiftCertificateID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the Gift Certificate ID for this Payment Instrument.

    **Returns:**
    - the Gift Certificate ID or null if not set.

    **Deprecated:**
**warning:** Use [getGiftCertificateCode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#getgiftcertificatecode)

---

### getMaskedBankAccountDriversLicense()
- getMaskedBankAccountDriversLicense(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted driver's license number of the bank account with
      all but the last 4 characters replaced with a '\*' character.
      
      If the driver's license number is empty,
      it will be returned without an exception.


    **Returns:**
    - the decrypted driver's license number with
      all but the last 4 characters replaced with a '\*' character.



---

### getMaskedBankAccountDriversLicense(Number)
- getMaskedBankAccountDriversLicense(ignore: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted driver's license number of the bank account with
      all but the specified number characters replaced with a '\*' character.
      
      If the driver's license number is empty (i.e. "" or null),
      it will be returned without an exception.
      
      Note that `ignore` is limited to 4 in an unsecure environment,
      and if account information for this payment instrument has been masked
      due to the data retention security policy for the site.


    **Parameters:**
    - ignore - the number of characters to leave unmasked.

    **Returns:**
    - the decrypted driver's license number with
      all but the specified number characters replaced with a '\*' character.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getMaskedBankAccountNumber()
- getMaskedBankAccountNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted bank account number with
      all but the last 4 characters replaced with a '\*' character.
      
      If the number is empty (i.e. "" or null),
      it will be returned without an exception.


    **Returns:**
    - the decrypted bank account number with
      all but the last 4 characters replaced with a '\*' character.



---

### getMaskedBankAccountNumber(Number)
- getMaskedBankAccountNumber(ignore: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted bank account number with
      all but the specified number characters replaced with a '\*' character.
      
      If the card number is empty (i.e. "" or null),
      it will be returned without an exception.
      
      Note that `ignore` is limited to 4 in an unsecure environment,
      and if account information for this payment instrument has been masked
      due to the data retention security policy for the site.


    **Parameters:**
    - ignore - the number of characters to leave unmasked

    **Returns:**
    - the decrypted bank account number with
      all but the specified number of characters replaced with a '\*' character.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getMaskedCreditCardNumber()
- getMaskedCreditCardNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted credit card number with
      all but the last 4 characters replaced with a '\*' character.
      
      If the number is empty,
      it will be returned without an exception.


    **Returns:**
    - the decrypted credit card number with
      all but the last 4 characters replaced with a '\*' character.



---

### getMaskedCreditCardNumber(Number)
- getMaskedCreditCardNumber(ignore: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the decrypted credit card number with
      all but the specified number characters replaced with a '\*' character.
      
      If the card number is empty (i.e. "" or null),
      it will be returned without an exception.
      
      Note that `ignore` is limited to 4 in an unsecure environment,
      and if account information for this payment instrument has been masked
      due to the data retention security policy for the site.


    **Parameters:**
    - ignore - the number of characters to leave unmasked.

    **Returns:**
    - the decrypted credit card number with
      all but the specified number characters replaced with a '\*' character.


    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### getMaskedGiftCertificateCode()
- getMaskedGiftCertificateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the masked gift certificate code with
      all but the last 4 characters replaced with a '\*' character.


    **Returns:**
    - the masked gift certificate code.


---

### getMaskedGiftCertificateCode(Number)
- getMaskedGiftCertificateCode(ignore: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the masked gift certificate code with
      all but the specified number of characters replaced with a '\*' character.


    **Parameters:**
    - ignore - the number of characters to leave unmasked.

    **Returns:**
    - the masked gift certificate code.

    **Throws:**
    - IllegalArgumentException - if ignore is negative.


---

### getPaymentMethod()
- getPaymentMethod(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the identifier of the payment method represented by this
      payment instrument.


    **Returns:**
    - the identifier of the payment method represented by this
      payment instrument.



---

### isCreditCardExpired()
- isCreditCardExpired(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this payment instrument represents an expired credit
      card. This check is only logical if the credit card expiration month and
      year are set. If either of these attributes are not set, then this method
      always returns false.


    **Returns:**
    - true if this payment instrument represents an expired credit
              card, false otherwise



---

### isPermanentlyMasked()
- isPermanentlyMasked(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the account information for this Payment Instrument
      has been permanently masked as a result of the data retention security policy
      for the site or a creditcard tokenization, and `false` otherwise.
      
      When account information is masked only the last 4 digits of the credit card
      or bank account number are recoverable.  The bank account driver's license number
      and bank routing number are completely masked.


    **Returns:**
    - whether or not the account information has been masked


---

### setBankAccountDriversLicense(String)
- setBankAccountDriversLicense(license: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the driver's license number associated with a bank account payment instrument.

    **Parameters:**
    - license - the bank account holder driver's license.


---

### setBankAccountDriversLicenseStateCode(String)
- setBankAccountDriversLicenseStateCode(stateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the driver's license state code associated with a bank account payment instrument.

    **Parameters:**
    - stateCode - the state in which the bank account driver's license was issued.


---

### setBankAccountHolder(String)
- setBankAccountHolder(holder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the full name of the holder of a bank account payment instrument.

    **Parameters:**
    - holder - the bank account holder's full name.


---

### setBankAccountNumber(String)
- setBankAccountNumber(accountNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the bank account number of a bank account payment instrument.

    **Parameters:**
    - accountNumber - the bank account number.


---

### setBankRoutingNumber(String)
- setBankRoutingNumber(routingNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the bank routing number of a bank account payment instrument.

    **Parameters:**
    - routingNumber - the bank account rounting number.


---

### setCreditCardExpirationMonth(Number)
- setCreditCardExpirationMonth(aValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the month of the year in which the credit card
      expires. Permissible values are from 1 to 12.


    **Parameters:**
    - aValue - the month of the year in which the credit card  expires. Permissible values are from 1 to 12.


---

### setCreditCardExpirationYear(Number)
- setCreditCardExpirationYear(aValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the year in which the credit card
      expires, such as '2004'.


    **Parameters:**
    - aValue - the year in which the credit card  expires.


---

### setCreditCardHolder(String)
- setCreditCardHolder(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the credit card owner.

    **Parameters:**
    - aValue - the name of the credit card owner.


---

### setCreditCardIssueNumber(String)
- setCreditCardIssueNumber(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the credit card issue number.  This attribute is only used by
      specific credit/debit card processors such as Solo and Switch in the UK.


    **Parameters:**
    - aValue - the credit card issue number


---

### setCreditCardNumber(String)
- setCreditCardNumber(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the credit card number for this payment.

    **Parameters:**
    - aValue - the new value of the credit card number.


---

### setCreditCardToken(String)
- setCreditCardToken(token: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Secure credit card data can be replaced by a token by utilizing a
      tokenization provider, which securely stores the credit card data using
      the token as a key. The stored data can later reused by including the
      token in a request. In this way credit card processes such as
      authorization and capture can be implemented without being responsible
      for persisting the credit card data.
      
      
      An Exception will be thrown when the token is null or blank.
      
      
      When setting a credit card token, the account information (including the
      creditcard number) is masked and all creditcard attributes are frozen and
      an attempt to change will be result in an exception.


    **Parameters:**
    - token - the token

    **See Also:**
    - [isPermanentlyMasked()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#ispermanentlymasked)


---

### setCreditCardType(String)
- setCreditCardType(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the type of the credit card.

    **Parameters:**
    - aValue - the type of the credit card.


---

### setCreditCardValidFromMonth(Number)
- setCreditCardValidFromMonth(aValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the month of the year in which the credit card became valid (1-12).
      This attribute is not used by all credit card types


    **Parameters:**
    - aValue - the month of the year in which the credit card  became valid (1-12).


---

### setCreditCardValidFromYear(Number)
- setCreditCardValidFromYear(aValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the year in which the credit card became valid, such as '2001'.
      This attribute is not used by all credit card types.


    **Parameters:**
    - aValue - the year in which the credit card became valid


---

### setGiftCertificateCode(String)
- setGiftCertificateCode(giftCertificateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Gift Certificate code for this Payment Instrument.

    **Parameters:**
    - giftCertificateCode - the Gift Certificate code.


---

### setGiftCertificateID(String)
- ~~setGiftCertificateID(giftCertificateID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the Gift Certificate ID for this Payment Instrument.

    **Parameters:**
    - giftCertificateID - the Gift Certificate ID.

    **Deprecated:**
**warning:** Use [setGiftCertificateCode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md#setgiftcertificatecodestring)

---

<!-- prettier-ignore-end -->

<!-- document id=75169ed55da0bd4f3109f005d0ac0a071296c77fa4f15c7f450635d8ac0f11bf url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PaymentMethod.md -->

<!-- prettier-ignore-start -->
# Class PaymentMethod

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md)

The PaymentMethod class represents a logical type of payment a customer can
make in the storefront. This class provides methods to access the payment
method attributes, status, and (for card-based payment methods) the related
payment cards.


A typical storefront presents the customer a list of payment methods that a
customer can choose from after he has entered his billing address during the
checkout.
[PaymentMgr.getApplicablePaymentMethods(Customer, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getapplicablepaymentmethodscustomer-string-number)
is used to determine the PaymentMethods that are relevant for the customer
based on the amount of his order, his customer groups, and his shipping
address.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique ID of the payment method. |
| [active](#active): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if payment method is active (enabled), otherwise 'false' is returned. |
| [activePaymentCards](#activepaymentcards): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns enabled payment cards that are assigned to this payment method, regardless  of current customer, country or payment amount restrictions. |
| [description](#description): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the description of the payment method. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the reference to the payment method image. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the payment method. |
| [paymentProcessor](#paymentprocessor): [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md) `(read-only)` | Returns the payment processor associated to this payment method. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getActivePaymentCards](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#getactivepaymentcards)() | Returns enabled payment cards that are assigned to this payment method, regardless  of current customer, country or payment amount restrictions. |
| [getApplicablePaymentCards](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#getapplicablepaymentcardscustomer-string-number)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the sorted list of all enabled payment cards of this payment  method applicable for the specified customer, country, payment amount and the session currency  The payment cards are sorted as defined in the Business Manager. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#getdescription)() | Returns the description of the payment method. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#getid)() | Returns the unique ID of the payment method. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#getimage)() | Returns the reference to the payment method image. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#getname)() | Returns the name of the payment method. |
| [getPaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#getpaymentprocessor)() | Returns the payment processor associated to this payment method. |
| [isActive](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#isactive)() | Returns 'true' if payment method is active (enabled), otherwise 'false' is returned. |
| [isApplicable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md#isapplicablecustomer-string-number)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns 'true' if this payment method is applicable for the specified  customer, country and payment amount and the session currency. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique ID of the payment method.


---

### active
- active: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if payment method is active (enabled), otherwise 'false' is returned.


---

### activePaymentCards
- activePaymentCards: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns enabled payment cards that are assigned to this payment method, regardless
      of current customer, country or payment amount restrictions.
      The payment cards are sorted as defined in the Business Manager.



---

### description
- description: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the description of the payment method.


---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the reference to the payment method image.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the payment method.


---

### paymentProcessor
- paymentProcessor: [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md) `(read-only)`
  - : Returns the payment processor associated to this payment method.


---

## Method Details

### getActivePaymentCards()
- getActivePaymentCards(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns enabled payment cards that are assigned to this payment method, regardless
      of current customer, country or payment amount restrictions.
      The payment cards are sorted as defined in the Business Manager.


    **Returns:**
    - List of enabled payment cards of current site


---

### getApplicablePaymentCards(Customer, String, Number)
- getApplicablePaymentCards(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), paymentAmount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the sorted list of all enabled payment cards of this payment
      method applicable for the specified customer, country, payment amount and the session currency
      The payment cards are sorted as defined in the Business Manager. 
      
      
      A payment card is applicable if
      
      - the card is restricted by customer group, and at least one of  the groups of the specified customer is assigned to the card
      - the card is restricted by billing country, and the specified  country code is assigned to the card
      - the card is restricted by payment amount for the session currency,  and the specified payment amount is within the limits of the min/max  payment amount defined for the method and the session currency
      - the card is restricted by currency code, and the specified  currency code matches session currency.
      
      
      All parameters are optional, and if not specified, the respective
      restriction won't be validated. For example, if a card is restricted
      by billing country, but no country code is specified, this card will
      be returned, unless it is filtered out by customer group or payment
      amount.


    **Parameters:**
    - customer - Customer or null
    - countryCode - Billing country code or null
    - paymentAmount - Payment amount or null

    **Returns:**
    - List of applicable payment cards of this payment method


---

### getDescription()
- getDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the description of the payment method.

    **Returns:**
    - Description of the payment method.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique ID of the payment method.

    **Returns:**
    - ID of the payment method.


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the reference to the payment method image.

    **Returns:**
    - Image of the payment method.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the payment method.

    **Returns:**
    - Name of the payment method.


---

### getPaymentProcessor()
- getPaymentProcessor(): [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md)
  - : Returns the payment processor associated to this payment method.

    **Returns:**
    - the payment processor associated to this payment method.


---

### isActive()
- isActive(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if payment method is active (enabled), otherwise 'false' is returned.

    **Returns:**
    - true if payment method is active, otherwise false.


---

### isApplicable(Customer, String, Number)
- isApplicable(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), paymentAmount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if this payment method is applicable for the specified
      customer, country and payment amount and the session currency.
      
      
      
      The payment method is applicable if
      
      - the method is restricted by customer group, and at least one of the  groups of the specified customer is assigned to the method
      - the method is restricted by billing country, and the specified  country code is assigned to the method
      - the method is restricted by payment amount for the session currency,  and the specified payment amount is within the limits of the min/max  payment amount defined for the method and the session currency
      - the method is restricted by currency code, and the specified  currency code matches session currency.
      
      
      All parameters are optional, and if not specified, the respective
      restriction won't be validated. For example, if a method is restricted by
      billing country, but no country code is specified, this method will be
      returned, unless it is filtered out by customer group or payment amount.


    **Parameters:**
    - customer - Customer or null
    - countryCode - Billing country code or null
    - paymentAmount - Payment amount or null

    **Returns:**
    - true if payment method is applicable, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=6de1702fd28e1c31c560c6e29b558bee3676e0c3f6bc4f4a0e9eb021532e9d16 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PaymentMgr.md -->

<!-- prettier-ignore-start -->
# Class PaymentMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.PaymentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md)

[PaymentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md) is used to access payment methods and payment
cards of the current site.


To access payment methods and payment cards explicitly, use methods
[getPaymentMethod(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getpaymentmethodstring) and [getPaymentCard(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getpaymentcardstring).



To access active payment methods use method [getActivePaymentMethods()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getactivepaymentmethods).



To access applicable payment methods for a customer, country and/or payment
amount use method [getApplicablePaymentMethods(Customer, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getapplicablepaymentmethodscustomer-string-number).



## Property Summary

| Property | Description |
| --- | --- |
| [activePaymentMethods](#activepaymentmethods): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns the sorted list of all enabled payment methods of the current  site, regardless of any customer group, country, payment amount or currency  restrictions. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getActivePaymentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getactivepaymentmethods)() | Returns the sorted list of all enabled payment methods of the current  site, regardless of any customer group, country, payment amount or currency  restrictions. |
| static [getApplicablePaymentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getapplicablepaymentmethodscustomer-string-number)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the sorted list of all enabled payment methods of the current  site applicable for the session currency, specified customer, country and payment amount. |
| static [getPaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getpaymentcardstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the payment card for the specified cardType or null if no such  card exists in the current site. |
| static [getPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md#getpaymentmethodstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the payment method for the specified ID or null if no such method  exists in the current site. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### activePaymentMethods
- activePaymentMethods: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns the sorted list of all enabled payment methods of the current
      site, regardless of any customer group, country, payment amount or currency
      restrictions. The payment methods are sorted as defined in the Business
      Manager.



---

## Method Details

### getActivePaymentMethods()
- static getActivePaymentMethods(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the sorted list of all enabled payment methods of the current
      site, regardless of any customer group, country, payment amount or currency
      restrictions. The payment methods are sorted as defined in the Business
      Manager.


    **Returns:**
    - List of enabled payment methods of current site


---

### getApplicablePaymentMethods(Customer, String, Number)
- static getApplicablePaymentMethods(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), paymentAmount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the sorted list of all enabled payment methods of the current
      site applicable for the session currency, specified customer, country and payment amount.
      The payment methods are sorted as defined in the Business Manager. 
      
      
      A payment method is applicable if
      
      - the method is restricted by customer group, and at least one of  the groups of the specified customer is assigned to the method
      - the method is restricted by billing country, and the specified  country code is assigned to the method
      - the method is restricted by payment amount for the session currency,  and the specified payment amount is within the limits of the min/max  payment amount defined for the method and the session currency
      - the method is restricted by currency code, and the specified  currency code matches session currency.
      
      
      All parameters are optional, and if not specified, the respective
      restriction won't be validated. For example, if a method is restricted
      by billing country, but no country code is specified, this method will
      be returned, unless it is filtered out by customer group or payment
      amount.


    **Parameters:**
    - customer - Customer or null
    - countryCode - Billing country code or null
    - paymentAmount - Payment amount or null

    **Returns:**
    - List of applicable payment methods of current site


---

### getPaymentCard(String)
- static getPaymentCard(cardType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md)
  - : Returns the payment card for the specified cardType or null if no such
      card exists in the current site.


    **Parameters:**
    - cardType - PaymentCard type

    **Returns:**
    - PaymentCard or null


---

### getPaymentMethod(String)
- static getPaymentMethod(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md)
  - : Returns the payment method for the specified ID or null if no such method
      exists in the current site.


    **Parameters:**
    - id - PaymentMethod ID

    **Returns:**
    - PaymentMethod or null


---

<!-- prettier-ignore-end -->

<!-- document id=0586ff6a76fcef9574c00d189771a8f26276caba11de5341f42915dc9427ed2f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PaymentProcessor.md -->

<!-- prettier-ignore-start -->
# Class PaymentProcessor

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md)

A PaymentProcessor represents an entity that processes payments of one or more types. In the B2C Commerce system, a
payment processor is just a container for configuration values, which describe, for example, the parameters (URL,
merchant ID, password, etc) required for connecting to a payment gateway.


The system has several built in PaymentProcessors. These are:

- BASIC\_CREDIT
- BASIC\_GIFT\_CERTIFICATE
- CYBERSOURCE\_CREDIT
- CYBERSOURCE\_BML
- PAYPAL\_CREDIT
- PAYPAL\_EXPRESS
- VERISIGN\_CREDIT

The first two of these are merely placeholders with no associated preference values. The remaining system payment
processors define preference values which are maintained in the Business Manager and are used in conjunction with
built-in B2C Commerce payment integrations. Preferences of system PaymentProcessors are not intended to be read
programmatically.


Merchants may also define custom payment processors. This is done by defining a payment processor with an arbitrary
ID in the Business Manager, and then configuring an attribute group with the same ID on the
[SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md) system object. Attributes added to the group will be considered preferences of the
payment processor and will be readable through [getPreferenceValue(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md#getpreferencevaluestring). Merchants can design their
checkout process to read these preferences at run time for connecting to their payment gateways.


Every [PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md) in the system is associated with at most one PaymentProcessor. This basically
represents the physical payment gateway which processes the (logical) payment method. Each payment processor may be
associated with an arbitrary number of payment methods. Also, each payment transaction has one PaymentProcessor which
is set by custom code during the checkout process.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the 'ID' of this processor. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md#getid)() | Returns the 'ID' of this processor. |
| [getPreferenceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md#getpreferencevaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the value of the specified preference for this payment processor. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the 'ID' of this processor.


---

## Method Details

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the 'ID' of this processor.

    **Returns:**
    - the 'ID' of this processor, e.g. "BASIC\_CREDIT".


---

### getPreferenceValue(String)
- getPreferenceValue(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value of the specified preference for this payment processor.
      If the preference name is invalid (or null) or no preference value is
      defined for this payment processor, null is returned.


    **Parameters:**
    - name - preference name. Typically an attribute defined on             SitePreferences contained in an attribute group whose name is             the same as this.ID.

    **Returns:**
    - preference value, or null.


---

<!-- prettier-ignore-end -->

<!-- document id=31abcff140808a492829c9e6399d1830dd0d208e0442606f50f0f0f6f4289e85 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.paymentrequest.PaymentRequestHookResult.md -->

<!-- prettier-ignore-start -->
# Class PaymentRequestHookResult

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.paymentrequest.PaymentRequestHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md)

Result of a hook handling a Payment Request request

**Deprecated:**
**warning:** Salesforce Payments includes support for Google Pay

## Property Summary

| Property | Description |
| --- | --- |
| [eventDetail](#eventdetail): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Detail to the JS custom event to dispatch in response to this result. |
| [eventName](#eventname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Name of the JS custom event to dispatch in response to this result. |
| [redirect](#redirect): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)` | URL to navigate to in response to this result. |
| [status](#status): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) `(read-only)` | Status describing the outcome of this result. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [PaymentRequestHookResult](#paymentrequesthookresultstatus-url)([Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md), [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Constructs a result with the given outcome information. |

## Method Summary

| Method | Description |
| --- | --- |
| [getEventDetail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md#geteventdetail)() | Detail to the JS custom event to dispatch in response to this result. |
| [getEventName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md#geteventname)() | Name of the JS custom event to dispatch in response to this result. |
| [getRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md#getredirect)() | URL to navigate to in response to this result. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md#getstatus)() | Status describing the outcome of this result. |
| [setEvent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md#seteventstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the JS custom event to dispatch in response to this result. |
| [setEvent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md#seteventstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the name and detail of the JS custom event to dispatch in response to this result. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### eventDetail
- eventDetail: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Detail to the JS custom event to dispatch in response to this result.


---

### eventName
- eventName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Name of the JS custom event to dispatch in response to this result.


---

### redirect
- redirect: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)`
  - : URL to navigate to in response to this result.


---

### status
- status: [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) `(read-only)`
  - : Status describing the outcome of this result.


---

## Constructor Details

### PaymentRequestHookResult(Status, URL)
- PaymentRequestHookResult(status: [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md), redirect: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md))
  - : Constructs a result with the given outcome information.

    **Parameters:**
    - status - status of the result
    - redirect - optional URL to which to navigate to in response to this outcome


---

## Method Details

### getEventDetail()
- getEventDetail(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Detail to the JS custom event to dispatch in response to this result.

    **Returns:**
    - event detail


---

### getEventName()
- getEventName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Name of the JS custom event to dispatch in response to this result.

    **Returns:**
    - event name


---

### getRedirect()
- getRedirect(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : URL to navigate to in response to this result.

    **Returns:**
    - redirect URL


---

### getStatus()
- getStatus(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Status describing the outcome of this result.

    **Returns:**
    - status of this result


---

### setEvent(String)
- setEvent(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the JS custom event to dispatch in response to this result.

    **Parameters:**
    - name - JS custom event name


---

### setEvent(String, Object)
- setEvent(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), detail: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the name and detail of the JS custom event to dispatch in response to this result.

    **Parameters:**
    - name - JS custom event name
    - detail - JS custom event detail


---

<!-- prettier-ignore-end -->

<!-- document id=4aca16080c2474733ce0457b5e55c8b36045f20ad1b069ca028f85aabe0ac617 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.paymentrequest.PaymentRequestHooks.md -->

<!-- prettier-ignore-start -->
# Class PaymentRequestHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.paymentrequest.PaymentRequestHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md)

PaymentRequestHooks interface containing extension points for customizing Payment Requests.


These hooks are executed in a transaction.


The extension points (hook names), and the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the exported hook function must be located
inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.




```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
     {"name": "dw.extensions.paymentrequest.getPaymentRequest", "script": "./paymentrequest.ds"}
     {"name": "dw.extensions.paymentrequest.shippingAddressChange", "script": "./paymentrequest.ds"}
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.


**Deprecated:**
**warning:** Salesforce Payments includes support for Google Pay

## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointAbort](#extensionpointabort): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.abort" | The extension point name dw.extensions.paymentrequest.abort. |
| [extensionPointGetPaymentRequest](#extensionpointgetpaymentrequest): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.getPaymentRequest" | The extension point name dw.extensions.paymentrequest.getPaymentRequest. |
| [extensionPointPaymentAcceptedAuthorizeOrderPayment](#extensionpointpaymentacceptedauthorizeorderpayment): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.paymentAccepted.authorizeOrderPayment" | The extension point name dw.extensions.paymentrequest.paymentAccepted.authorizeOrderPayment. |
| [extensionPointPaymentAcceptedPlaceOrder](#extensionpointpaymentacceptedplaceorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.paymentAccepted.placeOrder" | The extension point name dw.extensions.paymentrequest.paymentAccepted.placeOrder. |
| [extensionPointShippingAddressChange](#extensionpointshippingaddresschange): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.shippingAddressChange" | The extension point name dw.extensions.paymentrequest.shippingAddressChange. |
| [extensionPointShippingOptionChange](#extensionpointshippingoptionchange): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.shippingOptionChange" | The extension point name dw.extensions.paymentrequest.shippingOptionChange. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [abort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md#abortbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | <p>  Called after the Payment Request user interface was canceled. |
| [authorizeOrderPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md#authorizeorderpaymentorder-object)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called after the shopper accepts the Payment Request payment for the given order. |
| [getPaymentRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md#getpaymentrequestbasket-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called to get the `PaymentRequest` constructor parameters for the given basket. |
| [placeOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md#placeorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | <p>  Called after payment has been authorized and the given Payment Request order is ready to be placed. |
| [shippingAddressChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md#shippingaddresschangebasket-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called after handling the Payment Request `shippingaddresschange` event for the given basket. |
| [shippingOptionChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md#shippingoptionchangebasket-shippingmethod-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Called after handling the Payment Request `shippingoptionchange` event for the given basket. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointAbort

- extensionPointAbort: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.abort"
  - : The extension point name dw.extensions.paymentrequest.abort.


---

### extensionPointGetPaymentRequest

- extensionPointGetPaymentRequest: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.getPaymentRequest"
  - : The extension point name dw.extensions.paymentrequest.getPaymentRequest.


---

### extensionPointPaymentAcceptedAuthorizeOrderPayment

- extensionPointPaymentAcceptedAuthorizeOrderPayment: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.paymentAccepted.authorizeOrderPayment"
  - : The extension point name dw.extensions.paymentrequest.paymentAccepted.authorizeOrderPayment.


---

### extensionPointPaymentAcceptedPlaceOrder

- extensionPointPaymentAcceptedPlaceOrder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.paymentAccepted.placeOrder"
  - : The extension point name dw.extensions.paymentrequest.paymentAccepted.placeOrder.


---

### extensionPointShippingAddressChange

- extensionPointShippingAddressChange: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.shippingAddressChange"
  - : The extension point name dw.extensions.paymentrequest.shippingAddressChange.


---

### extensionPointShippingOptionChange

- extensionPointShippingOptionChange: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.paymentrequest.shippingOptionChange"
  - : The extension point name dw.extensions.paymentrequest.shippingOptionChange.


---

## Method Details

### abort(Basket)
- abort(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [PaymentRequestHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md)
  - : 
      
      Called after the Payment Request user interface was canceled. The given basket is the one that was passed to other
      hooks earlier in the Payment Request checkout process.
      
      
      
      
      It is not guaranteed that this hook will be executed for all Payment Request user interfaces canceled by shoppers or
      otherwise ended without a successful order. Calls to this hook are provided on a best-effort basis.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if possible. It
      is not guaranteed that the response with the hook result will be handled in the shopper browser in all cases.


    **Parameters:**
    - basket - the basket that was being checked out using Payment Request

    **Returns:**
    - a non-null result ends the hook execution


---

### authorizeOrderPayment(Order, Object)
- authorizeOrderPayment(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), response: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Called after the shopper accepts the Payment Request payment for the given order. Basket customer information,
      billing address, and/or shipping address for the default shipment will have already been updated to reflect the
      available contact information provided by Payment Request. Any preexisting payment instruments on the basket will
      have been removed, and a single `DW_ANDROID_PAY` payment instrument added for the total amount. The
      given order will have been created from this updated basket.
      
      
      
      
      The purpose of this hook is to authorize the Payment Request payment for the order. If a non-error status is returned
      that means that you have successfully authorized the payment with your payment service provider. Your hook
      implementation must set the necessary payment status and transaction identifier data on the order as returned by
      the provider.
      
      
      
      
      Return an error status to indicate a problem, including unsuccessful authorization.
      
      
      
      
      See the [Payment Request API](https://www.w3.org/TR/payment-request) for more information.


    **Parameters:**
    - order - the order paid using Payment Request
    - response - response to the accepted `PaymentRequest`

    **Returns:**
    - a non-null status ends the hook execution


---

### getPaymentRequest(Basket, Object)
- getPaymentRequest(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), parameters: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [PaymentRequestHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md)
  - : 
      
      Called to get the `PaymentRequest` constructor parameters for the given basket. You can
      set properties in the given `parameters` object to extend or override default properties set
      automatically based on the Google Pay configuration for your site.
      
      
      
      
      The `parameters` object will contain the following properties by default:
      
      - `methodData`- array containing payment methods the web site accepts
      - `details`- information about the transaction that the user is being asked to complete
      - `options`- information about what options the web page wishes to use from the payment request system
      
      
      
      
      
      Return a result with an error status to indicate a problem.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if the Payment
      Request user interaction is canceled.
      
      
      
      
      See the [Payment Request API](https://www.w3.org/TR/payment-request) for more information.


    **Parameters:**
    - basket - the basket for the Payment Request request
    - parameters - object containing `PaymentRequest` constructor parameters

    **Returns:**
    - a non-null result ends the hook execution


---

### placeOrder(Order)
- placeOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [PaymentRequestHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md)
  - : 
      
      Called after payment has been authorized and the given Payment Request order is ready to be placed. The purpose of
      this hook is to place the order, or return a redirect URL that results in the order being placed when the shopper
      browser is navigated to it.
      
      
      
      
      The default implementation of this hook returns a redirect to `COPlaceOrder-Submit` with URL
      parameters `order_id` set to [Order.getOrderNo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getorderno) and `order_token` set to
      [Order.getOrderToken()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getordertoken) which corresponds to SiteGenesis-based implementations. Your hook
      implementation should return a result with a different redirect URL as necessary to place the order and show an
      order confirmation.
      
      
      
      
      Alternatively, your hook implementation itself can place the order and return a result with a redirect URL to an
      order confirmation page that does not place the order. This is inconsistent with SiteGenesis-based
      implementations so is not the default.
      
      
      
      
      Return an error status to indicate a problem. If the returned result includes a redirect URL, the shopper browser
      will be navigated to that URL if the Payment Request user interface is canceled.


    **Parameters:**
    - order - the order paid using PaymentRequest

    **Returns:**
    - a non-null result ends the hook execution


---

### shippingAddressChange(Basket, Object)
- shippingAddressChange(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), details: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [PaymentRequestHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md)
  - : 
      
      Called after handling the Payment Request `shippingaddresschange` event for the given basket. Basket
      customer information and/or shipping address for the default shipment will have already been updated to reflect
      the available shipping address information provided by Payment Request. The basket will have already been
      calculated before this hook is called.
      
      
      
      
      Return a result with an error status to indicate a problem.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if the Payment
      Request user interface is canceled.
      
      
      
      
      See the [Payment Request API](https://www.w3.org/TR/payment-request) for more information.


    **Parameters:**
    - basket - the basket being checked out using Payment Request
    - details - updated `PaymentRequest` object details

    **Returns:**
    - a non-null result ends the hook execution


---

### shippingOptionChange(Basket, ShippingMethod, Object)
- shippingOptionChange(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), details: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [PaymentRequestHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md)
  - : 
      
      Called after handling the Payment Request `shippingoptionchange` event for the given basket. The given
      shipping method will have already been set on the basket. The basket will have already been calculated before
      this hook is called.
      
      
      
      
      Return a result with an error status to indicate a problem.
      
      
      
      
      If the returned result includes a redirect URL, the shopper browser will be navigated to that URL if the
      Payment Request user interface is canceled.
      
      
      
      
      See the [Payment Request API](https://www.w3.org/TR/payment-request) for more information.


    **Parameters:**
    - basket - the basket being checked out using Payment Request
    - shippingMethod - the shipping method that was selected
    - details - updated `PaymentRequest` object details

    **Returns:**
    - a non-null result ends the hook execution


---

<!-- prettier-ignore-end -->

<!-- document id=e97113a44a19c32ad32fdfd7b1cd8a33740d06b7bb3d65e5330d1004ff413811 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PaymentStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class PaymentStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.PaymentStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentStatusCodes.md)

Helper class containing status codes for the various errors that can occur
when validating a payment card. One of these codes is returned as part of a
Status object when a unsuccessful call to the `VerifyPaymentCard`
or `VerifyCreditCard` pipelet is made. The same codes are used
when calling [PaymentCard.verify(Number, Number, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#verifynumber-number-string) or
[PaymentCard.verify(Number, Number, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md#verifynumber-number-string-string).



## Constant Summary

| Constant | Description |
| --- | --- |
| [CREDITCARD_INVALID_CARD_NUMBER](#creditcard_invalid_card_number): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDITCARD_INVALID_CARD_NUMBER" | The code indicates that the credit card number is incorrect. |
| [CREDITCARD_INVALID_EXPIRATION_DATE](#creditcard_invalid_expiration_date): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDITCARD_INVALID_EXPIRATION_DATE" | The code indicates that the credit card is expired. |
| [CREDITCARD_INVALID_SECURITY_CODE](#creditcard_invalid_security_code): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDITCARD_INVALID_SECURITY_CODE" | The code indicates that the credit card security code length is invalid. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [PaymentStatusCodes](#paymentstatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CREDITCARD_INVALID_CARD_NUMBER

- CREDITCARD_INVALID_CARD_NUMBER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDITCARD_INVALID_CARD_NUMBER"
  - : The code indicates that the credit card number is incorrect.


---

### CREDITCARD_INVALID_EXPIRATION_DATE

- CREDITCARD_INVALID_EXPIRATION_DATE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDITCARD_INVALID_EXPIRATION_DATE"
  - : The code indicates that the credit card is expired.


---

### CREDITCARD_INVALID_SECURITY_CODE

- CREDITCARD_INVALID_SECURITY_CODE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDITCARD_INVALID_SECURITY_CODE"
  - : The code indicates that the credit card security code length is invalid.


---

## Constructor Details

### PaymentStatusCodes()
- PaymentStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=4fe0b7b30ad4d34b4f049c967a6b8275f9a76524fda75f261109d877c925ff8f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PaymentTransaction.md -->

<!-- prettier-ignore-start -->
# Class PaymentTransaction

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)

The PaymentTransaction class represents a payment transaction.


## Constant Summary

| Constant | Description |
| --- | --- |
| [TYPE_AUTH](#type_auth): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTH" | Constant representing the authorization type of payment transaction. |
| [TYPE_AUTH_REVERSAL](#type_auth_reversal): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTH_REVERSAL" | Constant representing the authorization reversal type of payment transaction. |
| [TYPE_CAPTURE](#type_capture): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CAPTURE" | Constant representing the capture type of payment transaction. |
| [TYPE_CREDIT](#type_credit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDIT" | Constant representing the credit type of payment transaction. |

## Property Summary

| Property | Description |
| --- | --- |
| [accountID](#accountid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the payment service-specific account id. |
| [accountType](#accounttype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the payment service-specific account type. |
| [amount](#amount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the amount of the transaction. |
| [paymentInstrument](#paymentinstrument): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md) `(read-only)` | Returns the payment instrument related to this payment transaction. |
| [paymentProcessor](#paymentprocessor): [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md) | Returns the payment processor related to this payment transaction. |
| [transactionID](#transactionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the payment service-specific transaction id. |
| [type](#type): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the value of the transaction type where the  value is one of TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE  or TYPE\_CREDIT. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAccountID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getaccountid)() | Returns the payment service-specific account id. |
| [getAccountType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getaccounttype)() | Returns the payment service-specific account type. |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getamount)() | Returns the amount of the transaction. |
| [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getpaymentinstrument)() | Returns the payment instrument related to this payment transaction. |
| [getPaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getpaymentprocessor)() | Returns the payment processor related to this payment transaction. |
| [getTransactionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#gettransactionid)() | Returns the payment service-specific transaction id. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#gettype)() | Returns the value of the transaction type where the  value is one of TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE  or TYPE\_CREDIT. |
| [setAccountID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setaccountidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the payment service-specific account id. |
| [setAccountType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setaccounttypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the payment service-specific account type. |
| [setAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setamountmoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Sets the amount of the transaction. |
| [setPaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setpaymentprocessorpaymentprocessor)([PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md)) | Sets the payment processor related to this payment transaction. |
| [setTransactionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#settransactionidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the payment service-specific transaction id. |
| [setType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#settypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value of the transaction type where permissible  values are TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE or TYPE\_CREDIT. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TYPE_AUTH

- TYPE_AUTH: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTH"
  - : Constant representing the authorization type of payment transaction.


---

### TYPE_AUTH_REVERSAL

- TYPE_AUTH_REVERSAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTH_REVERSAL"
  - : Constant representing the authorization reversal type of payment transaction.


---

### TYPE_CAPTURE

- TYPE_CAPTURE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CAPTURE"
  - : Constant representing the capture type of payment transaction.


---

### TYPE_CREDIT

- TYPE_CREDIT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CREDIT"
  - : Constant representing the credit type of payment transaction.


---

## Property Details

### accountID
- accountID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment service-specific account id.


---

### accountType
- accountType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment service-specific account type.


---

### amount
- amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the amount of the transaction.


---

### paymentInstrument
- paymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md) `(read-only)`
  - : Returns the payment instrument related to this payment transaction.


---

### paymentProcessor
- paymentProcessor: [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md)
  - : Returns the payment processor related to this payment transaction.


---

### transactionID
- transactionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment service-specific transaction id.


---

### type
- type: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the value of the transaction type where the
      value is one of TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE
      or TYPE\_CREDIT.



---

## Method Details

### getAccountID()
- getAccountID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment service-specific account id.

    **Returns:**
    - the payment service-specific account id.


---

### getAccountType()
- getAccountType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment service-specific account type.

    **Returns:**
    - the payment service-specific account type.


---

### getAmount()
- getAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the amount of the transaction.

    **Returns:**
    - the amount of the transaction.


---

### getPaymentInstrument()
- getPaymentInstrument(): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Returns the payment instrument related to this payment transaction.

    **Returns:**
    - the order payment instrument related to this payment transaction.


---

### getPaymentProcessor()
- getPaymentProcessor(): [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md)
  - : Returns the payment processor related to this payment transaction.

    **Returns:**
    - the payment processor related to this payment transaction.


---

### getTransactionID()
- getTransactionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment service-specific transaction id.

    **Returns:**
    - the payment service-specific transaction id.


---

### getType()
- getType(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the value of the transaction type where the
      value is one of TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE
      or TYPE\_CREDIT.


    **Returns:**
    - the value of the transaction type where the
      value is one of TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE
      or TYPE\_CREDIT.



---

### setAccountID(String)
- setAccountID(accountID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the payment service-specific account id.

    **Parameters:**
    - accountID - the payment service-specific account id.


---

### setAccountType(String)
- setAccountType(accountType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the payment service-specific account type.

    **Parameters:**
    - accountType - the payment service-specific account type.


---

### setAmount(Money)
- setAmount(amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Sets the amount of the transaction.

    **Parameters:**
    - amount - the amount of the transaction.


---

### setPaymentProcessor(PaymentProcessor)
- setPaymentProcessor(paymentProcessor: [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md)): void
  - : Sets the payment processor related to this payment transaction.

    **Parameters:**
    - paymentProcessor - the payment processor related to this payment transaction.


---

### setTransactionID(String)
- setTransactionID(transactionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the payment service-specific transaction id.

    **Parameters:**
    - transactionID - the payment service-specific transaction id.


---

### setType(String)
- setType(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value of the transaction type where permissible
      values are TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE or TYPE\_CREDIT.


    **Parameters:**
    - type - the value of the transaction type where the  value is one of TYPE\_AUTH, TYPE\_AUTH\_REVERSAL, TYPE\_CAPTURE or TYPE\_CREDIT.


---

<!-- prettier-ignore-end -->

<!-- document id=aa312c9592e619a7acbd508f1137318425555bb055be7d9750034536d0a858aa url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.PercentageDiscount.md -->

<!-- prettier-ignore-start -->
# Class PercentageDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.PercentageDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageDiscount.md)

Represents a _percentage-off_ discount in the discount plan, for example
"10% off all T-Shirts".



## Property Summary

| Property | Description |
| --- | --- |
| [percentage](#percentage): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the percentage discount value, for example 10.00 for a "10% off"  discount. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [PercentageDiscount](#percentagediscountnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Create a percentage-discount on the fly. |

## Method Summary

| Method | Description |
| --- | --- |
| [getPercentage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageDiscount.md#getpercentage)() | Returns the percentage discount value, for example 10.00 for a "10% off"  discount. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### percentage
- percentage: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the percentage discount value, for example 10.00 for a "10% off"
      discount.



---

## Constructor Details

### PercentageDiscount(Number)
- PercentageDiscount(percentage: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Create a percentage-discount on the fly. Can be used to create a custom price adjustment.

    **Parameters:**
    - percentage - percentage value, e.g. 15.00 for 15%


---

## Method Details

### getPercentage()
- getPercentage(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the percentage discount value, for example 10.00 for a "10% off"
      discount.


    **Returns:**
    - Discount percentage value


---

<!-- prettier-ignore-end -->

<!-- document id=cae52d6136bb679a581dbaea5a5362fae6c708626ea359ee27f2bfb263dca2f5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.PercentageOptionDiscount.md -->

<!-- prettier-ignore-start -->
# Class PercentageOptionDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.PercentageOptionDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageOptionDiscount.md)

Represents a _percentage-off options_ discount in the discount plan, for
example "50% off monogramming on shirts".



## Property Summary

| Property | Description |
| --- | --- |
| [percentage](#percentage): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the percentage discount value, for example 10.00 for a "10% off"  discount. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getPercentage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageOptionDiscount.md#getpercentage)() | Returns the percentage discount value, for example 10.00 for a "10% off"  discount. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### percentage
- percentage: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the percentage discount value, for example 10.00 for a "10% off"
      discount.



---

## Method Details

### getPercentage()
- getPercentage(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the percentage discount value, for example 10.00 for a "10% off"
      discount.


    **Returns:**
    - Discount percentage value


---

<!-- prettier-ignore-end -->

<!-- document id=000e33cf7484c69d6d6ecbecd5705da41d21de6a9e35c9b6630555411d2b7712 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.PersistentObject.md -->

<!-- prettier-ignore-start -->
# Class PersistentObject

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)

Common base class for all objects in Commerce Cloud Digital that have an
identity and can be stored and retrieved.  Each entity is identified by
a unique universal identifier (a UUID).



## All Known Subclasses
[ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md), [ABTestSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md), [ActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md), [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md), [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md), [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md), [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), [CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md), [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md), [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md), [Coupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md), [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md), [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md), [CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md), [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md), [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md), [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md), [EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md), [ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md), [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md), [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md), [GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md), [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md), [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md), [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md), [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [OrganizationPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.OrganizationPreferences.md), [PaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md), [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md), [PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md), [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md), [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md), [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md), [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md), [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md), [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md), [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md), [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md), [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md), [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md), [ProductListItemPurchase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md), [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md), [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md), [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md), [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md), [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md), [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md), [Recommendation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md), [SearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md), [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md), [ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md), [ServiceProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md), [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), [SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md), [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md), [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md), [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md), [Store](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md), [StoreGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md), [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md), [VariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md)
## Property Summary

| Property | Description |
| --- | --- |
| [UUID](#uuid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique universal identifier for this object. |
| [creationDate](#creationdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date that this object was created. |
| [lastModified](#lastmodified): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date that this object was last modified. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate)() | Returns the date that this object was created. |
| [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified)() | Returns the date that this object was last modified. |
| [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)() | Returns the unique universal identifier for this object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### UUID
- UUID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique universal identifier for this object.


---

### creationDate
- creationDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date that this object was created.


---

### lastModified
- lastModified: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date that this object was last modified.


---

## Method Details

### getCreationDate()
- getCreationDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date that this object was created.

    **Returns:**
    - the date that this object was created.


---

### getLastModified()
- getLastModified(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date that this object was last modified.

    **Returns:**
    - the date that this object was last modified.


---

### getUUID()
- getUUID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique universal identifier for this object.

    **Returns:**
    - the unique universal identifier for this object.


---

<!-- prettier-ignore-end -->

<!-- document id=d72e329993751417dcb6c53dc76b16e7cbfe4e8797c9be03f299767a74c8e8d0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.pinterest.PinterestAvailability.md -->

<!-- prettier-ignore-start -->
# Class PinterestAvailability

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.pinterest.PinterestAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestAvailability.md)

Represents a row in the Pinterest availability feed export file.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the Pinterest product. |
| [availability](#availability): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the availability of the Pinterest product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestAvailability.md#getavailability)() | Returns the availability of the Pinterest product. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestAvailability.md#getid)() | Returns the ID of the Pinterest product. |
| [setAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestAvailability.md#setavailabilitystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the availability of the Pinterest product. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the Pinterest product. This is the same as the ID of the Demandware product.


---

### availability
- availability: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the availability of the Pinterest product. Possible values are
      [PinterestProduct.AVAILABILITY_IN_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_in_stock) or
      [PinterestProduct.AVAILABILITY_OUT_OF_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_out_of_stock).



---

## Method Details

### getAvailability()
- getAvailability(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the availability of the Pinterest product. Possible values are
      [PinterestProduct.AVAILABILITY_IN_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_in_stock) or
      [PinterestProduct.AVAILABILITY_OUT_OF_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_out_of_stock).



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Pinterest product. This is the same as the ID of the Demandware product.

    **Returns:**
    - product ID


---

### setAvailability(String)
- setAvailability(availability: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the availability of the Pinterest product. Possible values are
      [PinterestProduct.AVAILABILITY_IN_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_in_stock) or
      [PinterestProduct.AVAILABILITY_OUT_OF_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_out_of_stock).


    **Parameters:**
    - availability - the availability status to set for this product


---

<!-- prettier-ignore-end -->

<!-- document id=68d4c4c8b7c569bb982530dd283cf12c3edc1cd0d3f744f7892ccad1c6df5198 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.pinterest.PinterestFeedHooks.md -->

<!-- prettier-ignore-start -->
# Class PinterestFeedHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.pinterest.PinterestFeedHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestFeedHooks.md)

PinterestFeedHooks interface containing extension points for customizing Pinterest export feeds.


These hooks are not executed in a transaction.


The extension points (hook names), and the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the exported hook function must be located
inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.




```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
     {"name": "dw.extensions.pinterest.feed.transformProduct", "script": "./hooks.ds"}
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointTransformAvailability](#extensionpointtransformavailability): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.pinterest.feed.transformAvailability" | The extension point name dw.extensions.pinterest.feed.transformAvailability. |
| [extensionPointTransformProduct](#extensionpointtransformproduct): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.pinterest.feed.transformProduct" | The extension point name dw.extensions.pinterest.feed.transformProduct. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [transformAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestFeedHooks.md#transformavailabilityproduct-pinterestavailability)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [PinterestAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestAvailability.md)) | Called after default transformation of given Demandware product to Pinterest availability as part of the  availability feed export. |
| [transformProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestFeedHooks.md#transformproductproduct-pinterestproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [PinterestProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md)) | Called after default transformation of given Demandware product to Pinterest product as part of the catalog feed  export. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointTransformAvailability

- extensionPointTransformAvailability: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.pinterest.feed.transformAvailability"
  - : The extension point name dw.extensions.pinterest.feed.transformAvailability.


---

### extensionPointTransformProduct

- extensionPointTransformProduct: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.pinterest.feed.transformProduct"
  - : The extension point name dw.extensions.pinterest.feed.transformProduct.


---

## Method Details

### transformAvailability(Product, PinterestAvailability)
- transformAvailability(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), pinterestAvailability: [PinterestAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestAvailability.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called after default transformation of given Demandware product to Pinterest availability as part of the
      availability feed export.


    **Parameters:**
    - product - the Demandware product
    - pinterestAvailability - the Pinterest representation of the product availability

    **Returns:**
    - a non-null Status ends the hook execution


---

### transformProduct(Product, PinterestProduct)
- transformProduct(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), pinterestProduct: [PinterestProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called after default transformation of given Demandware product to Pinterest product as part of the catalog feed
      export.


    **Parameters:**
    - product - the Demandware product
    - pinterestProduct - the Pinterest representation of the product

    **Returns:**
    - a non-null Status ends the hook execution


---

<!-- prettier-ignore-end -->

<!-- document id=c82f7716ec1215de571d61d160d78f98a4197a63251699f7a2ccb34f16ba0aa7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.pinterest.PinterestOrder.md -->

<!-- prettier-ignore-start -->
# Class PinterestOrder

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.pinterest.PinterestOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md)

An order that was placed through Pinterest.


## Constant Summary

| Constant | Description |
| --- | --- |
| [PAYMENT_STATUS_NOT_PAID](#payment_status_not_paid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NOT_PAID" | Indicates that payment has not been made. |
| [PAYMENT_STATUS_PAID](#payment_status_paid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PAID" | Indicates that payment is complete. |
| [PAYMENT_STATUS_PART_PAID](#payment_status_part_paid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PART_PAID" | Indicates that payment is incomplete. |
| [STATUS_BACKORDER](#status_backorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BACKORDER" | Indicates an order on backorder. |
| [STATUS_CANCELLED](#status_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED" | Indicates an order that has been canceled. |
| [STATUS_DELIVERED](#status_delivered): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DELIVERED" | Indicates an order that has been delivered. |
| [STATUS_IN_PROGRESS](#status_in_progress): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IN_PROGRESS" | Indicates an order in progress. |
| [STATUS_NEW](#status_new): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW" | Indicates a new order. |
| [STATUS_RETURNED](#status_returned): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURNED" | Indicates an order that has been returned. |
| [STATUS_SHIPPED](#status_shipped): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED" | Indicates an order that has shipped. |

## Property Summary

| Property | Description |
| --- | --- |
| [itemId](#itemid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the item ID for this Pinterest order. |
| [orderNo](#orderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the order number for this Pinterest order. |
| [paymentStatus](#paymentstatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the status of this Pinterest order. |
| [status](#status): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the status of this Pinterest order. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getItemId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#getitemid)() | Returns the item ID for this Pinterest order. |
| [getOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#getorderno)() | Returns the order number for this Pinterest order. |
| [getPaymentStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#getpaymentstatus)() | Returns the status of this Pinterest order. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#getstatus)() | Returns the status of this Pinterest order. |
| [setItemId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#setitemidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the item ID for this Pinterest order. |
| [setPaymentStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#setpaymentstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the status of this Pinterest order. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#setstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the status of this Pinterest order. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### PAYMENT_STATUS_NOT_PAID

- PAYMENT_STATUS_NOT_PAID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NOT_PAID"
  - : Indicates that payment has not been made.


---

### PAYMENT_STATUS_PAID

- PAYMENT_STATUS_PAID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PAID"
  - : Indicates that payment is complete.


---

### PAYMENT_STATUS_PART_PAID

- PAYMENT_STATUS_PART_PAID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PART_PAID"
  - : Indicates that payment is incomplete.


---

### STATUS_BACKORDER

- STATUS_BACKORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BACKORDER"
  - : Indicates an order on backorder.


---

### STATUS_CANCELLED

- STATUS_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED"
  - : Indicates an order that has been canceled.


---

### STATUS_DELIVERED

- STATUS_DELIVERED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DELIVERED"
  - : Indicates an order that has been delivered.


---

### STATUS_IN_PROGRESS

- STATUS_IN_PROGRESS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IN_PROGRESS"
  - : Indicates an order in progress.


---

### STATUS_NEW

- STATUS_NEW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW"
  - : Indicates a new order.


---

### STATUS_RETURNED

- STATUS_RETURNED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURNED"
  - : Indicates an order that has been returned.


---

### STATUS_SHIPPED

- STATUS_SHIPPED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED"
  - : Indicates an order that has shipped.


---

## Property Details

### itemId
- itemId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the item ID for this Pinterest order.


---

### orderNo
- orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the order number for this Pinterest order. This is the same as the order number of the Demandware order.


---

### paymentStatus
- paymentStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status of this Pinterest order. Possible values are
      [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_paid),
      [PAYMENT_STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_not_paid),
      or [PAYMENT_STATUS_PART_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_part_paid).



---

### status
- status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status of this Pinterest order. Possible values are
      [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_new),
      [STATUS_IN_PROGRESS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_in_progress),
      [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_shipped),
      [STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_backorder),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_cancelled),
      [STATUS_DELIVERED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_delivered),
      or [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_returned).



---

## Method Details

### getItemId()
- getItemId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the item ID for this Pinterest order.


---

### getOrderNo()
- getOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the order number for this Pinterest order. This is the same as the order number of the Demandware order.

    **Returns:**
    - order number


---

### getPaymentStatus()
- getPaymentStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status of this Pinterest order. Possible values are
      [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_paid),
      [PAYMENT_STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_not_paid),
      or [PAYMENT_STATUS_PART_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_part_paid).



---

### getStatus()
- getStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status of this Pinterest order. Possible values are
      [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_new),
      [STATUS_IN_PROGRESS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_in_progress),
      [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_shipped),
      [STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_backorder),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_cancelled),
      [STATUS_DELIVERED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_delivered),
      or [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_returned).



---

### setItemId(String)
- setItemId(itemId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the item ID for this Pinterest order.

    **Parameters:**
    - itemId - item ID


---

### setPaymentStatus(String)
- setPaymentStatus(status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the status of this Pinterest order. Possible values are
      [PAYMENT_STATUS_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_paid),
      [PAYMENT_STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_not_paid),
      or [PAYMENT_STATUS_PART_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#payment_status_part_paid).


    **Parameters:**
    - status - the status to set for this order


---

### setStatus(String)
- setStatus(status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the status of this Pinterest order. Possible values are
      [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_new),
      [STATUS_IN_PROGRESS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_in_progress),
      [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_shipped),
      [STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_backorder),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_cancelled),
      [STATUS_DELIVERED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_delivered),
      or [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md#status_returned).


    **Parameters:**
    - status - the status to set for this order


---

<!-- prettier-ignore-end -->

<!-- document id=e6db95bc915ae693a31eb654f6184a7c398305d0a9e43e0f17fd25a89717272c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.pinterest.PinterestOrderHooks.md -->

<!-- prettier-ignore-start -->
# Class PinterestOrderHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.pinterest.PinterestOrderHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrderHooks.md)

PinterestOrderHooks interface containing extension points for customizing Pinterest order status.


These hooks are not executed in a transaction.


The extension points (hook names), and the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the exported hook function must be located
inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.




```
"hooks": "./hooks.json"
```


The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
     {"name": "dw.extensions.pinterest.order.getStatus", "script": "./hooks.ds"}
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointGetStatus](#extensionpointgetstatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.pinterest.order.getStatus" | The extension point name dw.extensions.pinterest.order.getStatus. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrderHooks.md#getstatuspinterestorder)([PinterestOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md)) | Called to retrieve status for the given order. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointGetStatus

- extensionPointGetStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.pinterest.order.getStatus"
  - : The extension point name dw.extensions.pinterest.order.getStatus.


---

## Method Details

### getStatus(PinterestOrder)
- getStatus(order: [PinterestOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called to retrieve status for the given order. Return a `null` status for unknown orders.

    **Parameters:**
    - order - the Pinterest order

    **Returns:**
    - a non-null Status ends the hook execution


---

<!-- prettier-ignore-end -->

<!-- document id=d31274ae3b9875c1779d21b48fb141f21fd4b9cafb85349a637803d875366306 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.pinterest.PinterestProduct.md -->

<!-- prettier-ignore-start -->
# Class PinterestProduct

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.pinterest.PinterestProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md)

Represents a row in the Pinterest catalog feed export.


## Constant Summary

| Constant | Description |
| --- | --- |
| [AVAILABILITY_IN_STOCK](#availability_in_stock): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "in stock" | Indicates that the product is in stock. |
| [AVAILABILITY_OUT_OF_STOCK](#availability_out_of_stock): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "out of stock" | Indicates that the product is not in stock. |
| [AVAILABILITY_PREORDER](#availability_preorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "preorder" | Indicates that the product is availabile in preorder. |
| [CONDITION_NEW](#condition_new): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "new" | Indicates that the product has never been used. |
| [CONDITION_REFURBISHED](#condition_refurbished): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "refurbished" | Indicates that the product has been used but refurbished. |
| [CONDITION_USED](#condition_used): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "used" | Indicates that the product has been used. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the Pinterest product. |
| [availability](#availability): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the availability of the Pinterest product. |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest brand of the product. |
| [color](#color): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest color value label of the product. |
| [colorHex](#colorhex): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest color hex value of the product. |
| [colorImage](#colorimage): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) | Returns the URL of the image to show in Pinterest for the product color (swatch). |
| [condition](#condition): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the condition of the Pinterest product. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest description of the product. |
| [googleProductCategory](#googleproductcategory): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the category of this product in the Google category taxonomy. |
| [gtin](#gtin): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest GTIN of the product. |
| [imageLinks](#imagelinks): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Returns a list containing the URLs of the image to show in Pinterest for the product. |
| [itemGroupID](#itemgroupid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the ID of the Pinterest item group for the product, that is, its master product. |
| [itemGroupLink](#itemgrouplink): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) | Returns the URL of the Pinterest item group for the product, that is, the link to its master product in the  Demandware storefront. |
| [link](#link): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) | Returns the URL of the Demandware storefront link to the product. |
| [maxPrice](#maxprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the maximum price to show in Pinterest for the product. |
| [minPrice](#minprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the minimum price to show in Pinterest for the product. |
| [price](#price): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) | Returns the price to show in Pinterest for the product. |
| [productCategory](#productcategory): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest category path of the product. |
| [returnPolicy](#returnpolicy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest return policy of the product. |
| [size](#size): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest size value label of the product. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the Pinterest title of the product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getavailability)() | Returns the availability of the Pinterest product. |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getbrand)() | Returns the Pinterest brand of the product. |
| [getColor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getcolor)() | Returns the Pinterest color value label of the product. |
| [getColorHex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getcolorhex)() | Returns the Pinterest color hex value of the product. |
| [getColorImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getcolorimage)() | Returns the URL of the image to show in Pinterest for the product color (swatch). |
| [getCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getcondition)() | Returns the condition of the Pinterest product. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getdescription)() | Returns the Pinterest description of the product. |
| [getGoogleProductCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getgoogleproductcategory)() | Returns the category of this product in the Google category taxonomy. |
| [getGtin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getgtin)() | Returns the Pinterest GTIN of the product. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getid)() | Returns the ID of the Pinterest product. |
| [getImageLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getimagelinks)() | Returns a list containing the URLs of the image to show in Pinterest for the product. |
| [getItemGroupID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getitemgroupid)() | Returns the ID of the Pinterest item group for the product, that is, its master product. |
| [getItemGroupLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getitemgrouplink)() | Returns the URL of the Pinterest item group for the product, that is, the link to its master product in the  Demandware storefront. |
| [getLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getlink)() | Returns the URL of the Demandware storefront link to the product. |
| [getMaxPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getmaxprice)() | Returns the maximum price to show in Pinterest for the product. |
| [getMinPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getminprice)() | Returns the minimum price to show in Pinterest for the product. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getprice)() | Returns the price to show in Pinterest for the product. |
| [getProductCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getproductcategory)() | Returns the Pinterest category path of the product. |
| [getReturnPolicy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getreturnpolicy)() | Returns the Pinterest return policy of the product. |
| [getSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#getsize)() | Returns the Pinterest size value label of the product. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#gettitle)() | Returns the Pinterest title of the product. |
| [setAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setavailabilitystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the availability of the Pinterest product. |
| [setBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setbrandstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest brand of the product. |
| [setColor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setcolorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest color value label of the product. |
| [setColorHex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setcolorhexstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest color hex value of the product. |
| [setColorImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setcolorimageurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Sets the URL of the image to show in Pinterest for the product color (swatch). |
| [setCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setconditionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the condition of the Pinterest product. |
| [setDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setdescriptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest description of the product. |
| [setGoogleProductCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setgoogleproductcategorystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the category of this product in the Google category taxonomy. |
| [setGtin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setgtinstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest GTIN of the product. |
| [setImageLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setimagelinkslist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Sets the list of URLs of images to show in Pinterest for the product. |
| [setItemGroupID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setitemgroupidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the ID of the Pinterest item group for the product, that is, its master product. |
| [setItemGroupLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setitemgrouplinkurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Sets the URL of the Pinterest item group for the product, that is, the link to its master product in the  Demandware storefront. |
| [setLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setlinkurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Sets the URL of the Demandware storefront link to the product. |
| [setMaxPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setmaxpricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Sets the maximum price to show in Pinterest for the product. |
| [setMinPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setminpricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Sets the minimum price to show in Pinterest for the product. |
| [setPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setpricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Sets the price to show in Pinterest for the product. |
| [setProductCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setproductcategorystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest category path of the product. |
| [setReturnPolicy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setreturnpolicystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest return policy of the product. |
| [setSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#setsizestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest size value label of the product. |
| [setTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#settitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the Pinterest title of the product. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### AVAILABILITY_IN_STOCK

- AVAILABILITY_IN_STOCK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "in stock"
  - : Indicates that the product is in stock.


---

### AVAILABILITY_OUT_OF_STOCK

- AVAILABILITY_OUT_OF_STOCK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "out of stock"
  - : Indicates that the product is not in stock.


---

### AVAILABILITY_PREORDER

- AVAILABILITY_PREORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "preorder"
  - : Indicates that the product is availabile in preorder.


---

### CONDITION_NEW

- CONDITION_NEW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "new"
  - : Indicates that the product has never been used.


---

### CONDITION_REFURBISHED

- CONDITION_REFURBISHED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "refurbished"
  - : Indicates that the product has been used but refurbished.


---

### CONDITION_USED

- CONDITION_USED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "used"
  - : Indicates that the product has been used.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the Pinterest product. This is the same as the ID of the Demandware product.


---

### availability
- availability: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the availability of the Pinterest product. Possible values are
      [AVAILABILITY_IN_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_in_stock) or
      [AVAILABILITY_OUT_OF_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_out_of_stock).



---

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest brand of the product.


---

### color
- color: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest color value label of the product.


---

### colorHex
- colorHex: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest color hex value of the product.


---

### colorImage
- colorImage: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the image to show in Pinterest for the product color (swatch).


---

### condition
- condition: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the condition of the Pinterest product. Possible values are
      [CONDITION_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_new),
      [CONDITION_REFURBISHED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_refurbished), or
      [CONDITION_USED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_used).



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest description of the product.


---

### googleProductCategory
- googleProductCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the category of this product in the Google category taxonomy.


---

### gtin
- gtin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest GTIN of the product.


---

### imageLinks
- imageLinks: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list containing the URLs of the image to show in Pinterest for the product.


---

### itemGroupID
- itemGroupID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Pinterest item group for the product, that is, its master product.


---

### itemGroupLink
- itemGroupLink: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the Pinterest item group for the product, that is, the link to its master product in the
      Demandware storefront.



---

### link
- link: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the Demandware storefront link to the product.


---

### maxPrice
- maxPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the maximum price to show in Pinterest for the product.


---

### minPrice
- minPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the minimum price to show in Pinterest for the product.


---

### price
- price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price to show in Pinterest for the product.


---

### productCategory
- productCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest category path of the product.


---

### returnPolicy
- returnPolicy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest return policy of the product.


---

### size
- size: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest size value label of the product.


---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest title of the product.


---

## Method Details

### getAvailability()
- getAvailability(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the availability of the Pinterest product. Possible values are
      [AVAILABILITY_IN_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_in_stock) or
      [AVAILABILITY_OUT_OF_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_out_of_stock).



---

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest brand of the product.


---

### getColor()
- getColor(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest color value label of the product.


---

### getColorHex()
- getColorHex(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest color hex value of the product.


---

### getColorImage()
- getColorImage(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the image to show in Pinterest for the product color (swatch).


---

### getCondition()
- getCondition(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the condition of the Pinterest product. Possible values are
      [CONDITION_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_new),
      [CONDITION_REFURBISHED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_refurbished), or
      [CONDITION_USED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_used).



---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest description of the product.


---

### getGoogleProductCategory()
- getGoogleProductCategory(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the category of this product in the Google category taxonomy.


---

### getGtin()
- getGtin(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest GTIN of the product.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Pinterest product. This is the same as the ID of the Demandware product.

    **Returns:**
    - product ID


---

### getImageLinks()
- getImageLinks(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list containing the URLs of the image to show in Pinterest for the product.


---

### getItemGroupID()
- getItemGroupID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Pinterest item group for the product, that is, its master product.


---

### getItemGroupLink()
- getItemGroupLink(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the Pinterest item group for the product, that is, the link to its master product in the
      Demandware storefront.



---

### getLink()
- getLink(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the URL of the Demandware storefront link to the product.


---

### getMaxPrice()
- getMaxPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the maximum price to show in Pinterest for the product.


---

### getMinPrice()
- getMinPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the minimum price to show in Pinterest for the product.


---

### getPrice()
- getPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price to show in Pinterest for the product.


---

### getProductCategory()
- getProductCategory(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest category path of the product.


---

### getReturnPolicy()
- getReturnPolicy(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest return policy of the product.


---

### getSize()
- getSize(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest size value label of the product.


---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Pinterest title of the product.


---

### setAvailability(String)
- setAvailability(availability: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the availability of the Pinterest product. Possible values are
      [AVAILABILITY_IN_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_in_stock) or
      [AVAILABILITY_OUT_OF_STOCK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#availability_out_of_stock).


    **Parameters:**
    - availability - the availability status to set for this product


---

### setBrand(String)
- setBrand(brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest brand of the product.

    **Parameters:**
    - brand - Pinterest brand


---

### setColor(String)
- setColor(color: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest color value label of the product.

    **Parameters:**
    - color - Pinterest color value label


---

### setColorHex(String)
- setColorHex(colorHex: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest color hex value of the product.

    **Parameters:**
    - colorHex - Pinterest color hex value


---

### setColorImage(URL)
- setColorImage(colorImage: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): void
  - : Sets the URL of the image to show in Pinterest for the product color (swatch).

    **Parameters:**
    - colorImage - link to Pinterest color image


---

### setCondition(String)
- setCondition(condition: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the condition of the Pinterest product. Possible values are
      [CONDITION_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_new),
      [CONDITION_REFURBISHED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_refurbished), or
      [CONDITION_USED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md#condition_used).


    **Parameters:**
    - condition - the condition status to set for this product


---

### setDescription(String)
- setDescription(description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest description of the product.

    **Parameters:**
    - description - Pinterest description


---

### setGoogleProductCategory(String)
- setGoogleProductCategory(googleProductCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the category of this product in the Google category taxonomy.

    **Parameters:**
    - googleProductCategory - Google product category


---

### setGtin(String)
- setGtin(gtin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest GTIN of the product.

    **Parameters:**
    - gtin - Pinterest GTIN


---

### setImageLinks(List)
- setImageLinks(imageLinks: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): void
  - : Sets the list of URLs of images to show in Pinterest for the product.

    **Parameters:**
    - imageLinks - links to the product images


---

### setItemGroupID(String)
- setItemGroupID(itemGroupID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the ID of the Pinterest item group for the product, that is, its master product.

    **Parameters:**
    - itemGroupID - ID of Pinterest item group


---

### setItemGroupLink(URL)
- setItemGroupLink(itemGroupLink: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): void
  - : Sets the URL of the Pinterest item group for the product, that is, the link to its master product in the
      Demandware storefront.


    **Parameters:**
    - itemGroupLink - link to the Pinterest item group


---

### setLink(URL)
- setLink(link: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): void
  - : Sets the URL of the Demandware storefront link to the product.

    **Parameters:**
    - link - Demandware storefront link to the product


---

### setMaxPrice(Money)
- setMaxPrice(maxPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Sets the maximum price to show in Pinterest for the product.

    **Parameters:**
    - maxPrice - Pinterest maximum price


---

### setMinPrice(Money)
- setMinPrice(minPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Sets the minimum price to show in Pinterest for the product.

    **Parameters:**
    - minPrice - Pinterest minimum price


---

### setPrice(Money)
- setPrice(price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Sets the price to show in Pinterest for the product.

    **Parameters:**
    - price - Pinterest price


---

### setProductCategory(String)
- setProductCategory(productCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest category path of the product.

    **Parameters:**
    - productCategory - Pinterest category path


---

### setReturnPolicy(String)
- setReturnPolicy(returnPolicy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest return policy of the product.

    **Parameters:**
    - returnPolicy - Pinterest return policy


---

### setSize(String)
- setSize(size: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest size value label of the product.

    **Parameters:**
    - size - Pinterest size value label


---

### setTitle(String)
- setTitle(title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the Pinterest title of the product.

    **Parameters:**
    - title - Pinterest title


---

<!-- prettier-ignore-end -->

<!-- document id=e4fd41d1fbf95deb97332ec6936a7c9c9816455919c1983fdf1baf05b44ee403 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Pipeline.md -->

<!-- prettier-ignore-start -->
# Class Pipeline

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Pipeline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Pipeline.md)

A helper for executing pipelines from JavaScript. The main purpose for this API is to invoke process pipelines from
JavaScript controllers, e.g. pipelines that return with an end node and that do not perform user interactions.
Pipelines that span across multiple requests (e.g. that contain Interaction-Continue-Nodes) are not supported and may
not work as expected. The pipeline will be executed within the current request and not by a remote call, so this API
works roughly like a Call node in a pipeline. The called pipeline will get its own local pipeline dictionary. The
dictionary can be populated with initial values from an argument object. Any results from the pipeline can be read
from the pipeline dictionary that is returned by the [execute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Pipeline.md#executestring) methods.


If an exception occurs during the pipeline processing, the Error-branch of the pipeline will be called. If no error
handling exists for the pipeline, the exception will be propagated and can be handled by the script code.


If the pipeline finishes with an End node, the name of the end node can be obtained from the returned pipeline
dictionary under the key 'EndNodeName'.


Example:


```
let Pipeline = require('dw/system/Pipeline');
let pdict = Pipeline.execute('MyPipeline-Start', {
    MyArgString:     'someStringValue',
    MyArgNumber:     12345,
    MyArgBoolean:    true
});
let result = pdict.MyReturnValue;
```


This feature requires an API version >=15.5.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [execute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Pipeline.md#executestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Executes a pipeline. |
| static [execute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Pipeline.md#executestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Executes a pipeline. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### execute(String)
- static execute(pipeline: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PipelineDictionary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.PipelineDictionary.md)
  - : Executes a pipeline.

    **Parameters:**
    - pipeline - the pipeline identifier, must consist of the pipeline name and the start node name, like             'PipelineName-StartNodeName'

    **Returns:**
    - the pipeline dictionary with the pipeline results

    **API Version:**
**note:** Available from version 15.5.
New convenience method for easier migration of pipeline-based systems to JavaScript controllers.

---

### execute(String, Object)
- static execute(pipeline: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [PipelineDictionary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.PipelineDictionary.md)
  - : Executes a pipeline. The pipeline dictionary will be initialized with the provided arguments.

    **Parameters:**
    - pipeline - the pipeline identifier, must consist of a pipeline name and a start node name, like             'PipelineName-StartNodeName'
    - args - an object whose properties represent the initial values of the pipeline dictionary

    **Returns:**
    - the pipeline dictionary with the pipeline results

    **API Version:**
**note:** Available from version 15.5.
New convenience method for easier migration of pipeline-based systems to JavaScript controllers.

---

<!-- prettier-ignore-end -->

<!-- document id=6a676e085348046f8be5664c1f855f7531b131a13e2970c93961190c30c3a77e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.PipelineDictionary.md -->

<!-- prettier-ignore-start -->
# Class PipelineDictionary

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.PipelineDictionary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.PipelineDictionary.md)

The class provides access to the values in the pipeline dictionary. You use
dynamic properties to access values, such as pdict.myvalue or
pdict\['myvalue'\];


The class is used in two different contexts, one where access is limited to
the declared input/output values and second to a context with full access.
Inside scripts, the PipelineDictionary allows you to access declared in/out
values (regardless of the alias used in the pipeline and the actual key under
which the value is stored). In templates and pipelines, all values can be
accessed. In templates the pipeline dictionary is exposed as variable pdict
(e.g. ${pdict.Product.ID}).


There are several values that are automatically stored in the
PipelineDictionary with each request. These include but are not limited to:


- CurrentSession
- CurrentRequest
- CurrentHttpParameterMap
- CurrentForms
- CurrentCustomer
- etc.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=7f5b6c9fbf29fc045b88ac6824db44b980ee4192dc4f13d1c8896504caf65aa1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.ws.Port.md -->

<!-- prettier-ignore-start -->
# Class Port

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.ws.Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)

This class represents a port to a Service Endpoint Interface. This
class provides access to operations the service provides. Use the
WSUtil class to perform operations on the port such as setting
timeout values and configuring security.


Developers should set a low timeout to ensure responsiveness
of the site and avoid thread exhaustion (see [WSUtil.setRequestTimeout(Number, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setrequesttimeoutnumber-object)).
The default request timeout is 15 minutes when the web reference is used in a job,
and 2 minutes otherwise. If the timeout of the calling script is lower,
the script timeout is used.


**See Also:**
- [WSUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md)


## Constant Summary

| Constant | Description |
| --- | --- |
| [ENCODING](#encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Property constant for controlling the content type encoding of an outgoing message. |
| [ENDPOINT_ADDRESS_PROPERTY](#endpoint_address_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The target service endpoint address. |
| [PASSWORD_PROPERTY](#password_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Password for authentication. |
| [SESSION_MAINTAIN_PROPERTY](#session_maintain_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | This boolean property is used by a service client to indicate whether or not it wants to  participate in a session with a service endpoint. |
| [USERNAME_PROPERTY](#username_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | User name for authentication. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Port](#port)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ENCODING

- ENCODING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Property constant for controlling the content type encoding of an outgoing message.

    **See Also:**
    - [WSUtil.setProperty(String, Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setpropertystring-object-object)


---

### ENDPOINT_ADDRESS_PROPERTY

- ENDPOINT_ADDRESS_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The target service endpoint address. When using this property, the URI
      scheme for the endpoint address specification must correspond to the
      protocol/transport binding for the binding in use.


    **See Also:**
    - [WSUtil.setProperty(String, Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setpropertystring-object-object)


---

### PASSWORD_PROPERTY

- PASSWORD_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Password for authentication. This property is used with the USERNAME\_PROPERTY.
      You can also use the  [WSUtil.setUserNamePassword(String, String, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setusernamepasswordstring-string-object) method instead of using these
      properties.


    **See Also:**
    - [WSUtil.setUserNamePassword(String, String, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setusernamepasswordstring-string-object)
    - [WSUtil.setProperty(String, Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setpropertystring-object-object)


---

### SESSION_MAINTAIN_PROPERTY

- SESSION_MAINTAIN_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : This boolean property is used by a service client to indicate whether or not it wants to
      participate in a session with a service endpoint. If this property is set to true, the service client indicates
      that it wants the session to be maintained. If set to false, the session is not maintained. The default value
      for this property is false.


    **See Also:**
    - [WSUtil.setProperty(String, Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setpropertystring-object-object)


---

### USERNAME_PROPERTY

- USERNAME_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : User name for authentication. This property is used with the PASSWORD\_PROPERTY.
      You can also use the [WSUtil.setUserNamePassword(String, String, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setusernamepasswordstring-string-object) method instead of using these
      properties.


    **See Also:**
    - [WSUtil.setUserNamePassword(String, String, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setusernamepasswordstring-string-object)
    - [WSUtil.setProperty(String, Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setpropertystring-object-object)


---

## Constructor Details

### Port()
- Port()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=5768d29310d78448a6843ceeb2d478e0ad44e5f585b11b9d8b85849d94bc1efd url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PriceAdjustment.md -->

<!-- prettier-ignore-start -->
# Class PriceAdjustment

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
        - [dw.order.PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)

The PriceAdjustment class represents an adjustment to the price of an order. A PriceAdjustment can apply to a
ProductLineItem, ShippingLineItem, ProductShippingLineItem, or a LineItemCtnr, and are generally categorized as
product-level, shipping-level, or order-level. PriceAdjustments are generated by the B2C Commerce promotions engine
when applying discounts. See [PromotionMgr.applyDiscounts(DiscountPlan)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#applydiscountsdiscountplan). They may also be
generated by custom code through the API. See for example
[ProductLineItem.createPriceAdjustment(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createpriceadjustmentstring). In the latter case, the PriceAdjustment is called
"custom"; in the former case, it is called "system". System price adjustments are associated with the promotion that
triggered their creation. If the promotion was coupon-based, then the price adjustment will additionally be
associated with a coupon line item in the LineItemCtnr.



## Property Summary

| Property | Description |
| --- | --- |
| [ABTest](#abtest): [ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md) `(read-only)` | Returns the B2C Commerce AB-test this price adjustment is associated with. |
| [ABTestID](#abtestid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the AB-test related to this price adjustment. |
| [ABTestSegment](#abtestsegment): [ABTestSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md) `(read-only)` | Returns the B2C Commerce AB-test segment this price adjustment is associated with. |
| [ABTestSegmentID](#abtestsegmentid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the AB-test segment related to this price adjustment. |
| [appliedDiscount](#applieddiscount): [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) `(read-only)` | A `Discount` instance describing the discount applied to  obtain this price-adjustment. |
| [basedOnABTest](#basedonabtest): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a  promotion assigned to an AB-test. |
| ~~[basedOnCampaign](#basedoncampaign): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a  promotion assigned to a Campaign or an AB-test. |
| [basedOnCoupon](#basedoncoupon): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the promotion line item results from a coupon. |
| [campaign](#campaign): [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md) `(read-only)` | Returns the B2C Commerce campaign this price adjustment is associated with. |
| [campaignID](#campaignid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the campaign the price adjustment was based on. |
| [couponLineItem](#couponlineitem): [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md) `(read-only)` | Returns the coupon line item related to this price adjustment. |
| [createdBy](#createdby): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the user who created the price adjustment. |
| [custom](#custom): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this PriceAdjustment was created by custom script code. |
| [manual](#manual): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns true if this PriceAdjustment was added manually by a user. |
| [promotion](#promotion): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) `(read-only)` | Returns the promotion associated with this price adjustment. |
| [promotionID](#promotionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the promotion related to this price adjustment. |
| [proratedPrices](#proratedprices): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns a map representing the product line items to which this price  adjustment is "related" (in the sense defined below) and the portion of  this adjustment's price which applies to each after discount prorating is  performed. |
| [quantity](#quantity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of items this price adjustment applies to. |
| [reasonCode](#reasoncode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the reason code of the price adjustment. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getabtest)() | Returns the B2C Commerce AB-test this price adjustment is associated with. |
| [getABTestID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getabtestid)() | Returns the ID of the AB-test related to this price adjustment. |
| [getABTestSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getabtestsegment)() | Returns the B2C Commerce AB-test segment this price adjustment is associated with. |
| [getABTestSegmentID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getabtestsegmentid)() | Returns the ID of the AB-test segment related to this price adjustment. |
| [getAppliedDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getapplieddiscount)() | A `Discount` instance describing the discount applied to  obtain this price-adjustment. |
| [getCampaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getcampaign)() | Returns the B2C Commerce campaign this price adjustment is associated with. |
| [getCampaignID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getcampaignid)() | Returns the ID of the campaign the price adjustment was based on. |
| [getCouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getcouponlineitem)() | Returns the coupon line item related to this price adjustment. |
| [getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getcreatedby)() | Returns the name of the user who created the price adjustment. |
| [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getpromotion)() | Returns the promotion associated with this price adjustment. |
| [getPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getpromotionid)() | Returns the ID of the promotion related to this price adjustment. |
| [getProratedPrices](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices)() | Returns a map representing the product line items to which this price  adjustment is "related" (in the sense defined below) and the portion of  this adjustment's price which applies to each after discount prorating is  performed. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getquantity)() | Returns the number of items this price adjustment applies to. |
| [getReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getreasoncode)() | Returns the reason code of the price adjustment. |
| [isBasedOnABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#isbasedonabtest)() | Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a  promotion assigned to an AB-test. |
| ~~[isBasedOnCampaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#isbasedoncampaign)()~~ | Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a  promotion assigned to a Campaign or an AB-test. |
| [isBasedOnCoupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#isbasedoncoupon)() | Identifies if the promotion line item results from a coupon. |
| [isCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#iscustom)() | Returns true if this PriceAdjustment was created by custom script code. |
| [isManual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#ismanual)() | Returns true if this PriceAdjustment was added manually by a user. |
| [setManual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#setmanualboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Marks the current PriceAdjustment as manual/non-manual. |
| [setReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#setreasoncodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the reason code, using the internal non-localizable value. |

### Methods inherited from class LineItem

[getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getbaseprice), [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getgrossprice), [getLineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemctnr), [getLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemtext), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getnetprice), [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice), [getPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getpricevalue), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxbasis), [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxclassid), [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxrate), [getTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes), [setBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setbasepricemoney), [setGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setgrosspricemoney), [setLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setlineitemtextstring), [setNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setnetpricemoney), [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setpricevaluenumber), [setTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxmoney), [setTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxclassidstring), [setTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxratenumber), [setTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection), [updatePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber-money), [updateTaxAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxamountmoney)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ABTest
- ABTest: [ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md) `(read-only)`
  - : Returns the B2C Commerce AB-test this price adjustment is associated with. The associated AB-test is determined
      from the ABTestID attribute which is set by the promotions engine when applying discounts.
      
      
      If the AB-test has been removed from the system since this price adjustment was created, this method returns
      null. This method always returns null for custom price adjustments.



---

### ABTestID
- ABTestID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the AB-test related to this price adjustment.


---

### ABTestSegment
- ABTestSegment: [ABTestSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md) `(read-only)`
  - : Returns the B2C Commerce AB-test segment this price adjustment is associated with. The associated AB-test segment
      is determined from the ABTestSegmentID attribute which is set by the promotions engine when applying discounts.
      
      
      If the AB-test, or this segment, has been removed from the system since this price adjustment was created, this
      method returns null. This method always returns null for custom price adjustments.



---

### ABTestSegmentID
- ABTestSegmentID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the AB-test segment related to this price adjustment.


---

### appliedDiscount
- appliedDiscount: [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) `(read-only)`
  - : A `Discount` instance describing the discount applied to
      obtain this price-adjustment. This method only returns a non-null value
      if the price-adjustment was created
      
      - when a discount-plan was applied to a basket, or
      - as a _custom_price-adjustment using one of the methods  [ProductLineItem.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createpriceadjustmentstring-discount),  [ShippingLineItem.createShippingPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#createshippingpriceadjustmentstring-discount)or [LineItemCtnr.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring-discount).  
      
      
       Note an instance of the [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) subclasses is
      returned, such as [AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md) or
      [PriceBookPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PriceBookPriceDiscount.md), use
      [Discount.getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype) and the constants in
      [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) to distinguish between types. Each subclass
      provides access to specific properties.



---

### basedOnABTest
- basedOnABTest: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a
      promotion assigned to an AB-test.



---

### basedOnCampaign
- ~~basedOnCampaign: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a
      promotion assigned to a Campaign or an AB-test.


    **Deprecated:**
**warning:** The method has been deprecated since the name implies that there is a related Campaign, which may not
            be true. Use `!isCustom()` instead.

---

### basedOnCoupon
- basedOnCoupon: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the promotion line item results from a coupon.


---

### campaign
- campaign: [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md) `(read-only)`
  - : Returns the B2C Commerce campaign this price adjustment is associated with. The associated campaign is determined
      from the campaignID attribute which is set by the promotions engine when applying discounts.
      
      
      If the campaign has been removed from the system since this price adjustment was created, this method returns
      null. This method always returns null for custom price adjustments.
      
      
      Note: If the price adjustment was generated by a B2C Commerce promotion as part of an AB-test, then a Campaign
      object will be returned, but it is a mock implementation, and not a true Campaign. This behavior is required for
      backwards compatibility and should not be relied upon as it may change in future releases.



---

### campaignID
- campaignID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the campaign the price adjustment was based on.
      
      
      Note:If the price adjustment was generated by a B2C Commerce promotion as part of an AB-test, then an ID will be
      returned but it is not the ID of a true campaign. This behavior is required for backwards compatibility and
      should not be relied upon as it may change in future releases.



---

### couponLineItem
- couponLineItem: [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md) `(read-only)`
  - : Returns the coupon line item related to this price adjustment.
      If the price adjustment is not based on a coupon, null is returned.



---

### createdBy
- createdBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the user who created the price adjustment.
      This method returns a value if the price-adjustment was
      created as a _custom_ price-adjustment using one of the methods
      [ProductLineItem.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createpriceadjustmentstring-discount),
      [ShippingLineItem.createShippingPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#createshippingpriceadjustmentstring-discount)
      or [LineItemCtnr.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring-discount).
      
      
      If an agent user has created the price adjustment, the agent user's name
      is returned. Otherwise "Customer" is returned.



---

### custom
- custom: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this PriceAdjustment was created by custom script code.


---

### manual
- manual: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this PriceAdjustment was added manually by a user.
      
      
      A manual PriceAdjustment is one which has been added as a result of
      a user interaction e.g. by a user editing an order.
      
      
      A non-manual PriceAdjustment is one which has been added for a different
      reason, e.g. by custom logic which automatically adjusts the price of
      particular products when certain conditions are met.



---

### promotion
- promotion: [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) `(read-only)`
  - : Returns the promotion associated with this price adjustment. The
      associated promotion is determined from the promotionID and campaignID
      attributes which are set by the promotions engine when applying
      discounts. Alternatively if the promotion applied as part of an AB-test,
      then the associated promotion is determined from the promotionID
      attribute and the hidden attributes, abTestID and abTestGroupID.
      
      
      If the promotion has been removed from the system since this price
      adjustment was created, or if the promotion still exists but is not
      assigned to any campaign or AB-test, this method returns null. If the
      promotion has been reassigned to a different campaign or AB-test since
      this price adjustment was created, then the system will return an
      appropriate Promotion instance. This method always returns null for
      custom price adjustments.



---

### promotionID
- promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the promotion related to this price adjustment.


---

### proratedPrices
- proratedPrices: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns a map representing the product line items to which this price
      adjustment is "related" (in the sense defined below) and the portion of
      this adjustment's price which applies to each after discount prorating is
      performed. This information is sometimes useful to display in the
      storefront but is more often useful for integrating with backend
      order-management and accounting systems which require all discounts to be
      itemized.
      
      
      The definition of "related" product line items depends on the type of
      promotion which generated this price adjustment:
      
      
      - For order promotions, price adjustments are prorated across all  product line items which are not explicitly excluded by the promotion.  Custom order price adjustments apply to all items in the LineItemCtnr.
      - For Buy-X-Get-Y product promotions, price adjustments are prorated  across all items all product line items that are involved in the  promotion, meaning that the PLI has one or more items contributing to the  qualifying product count (i.e. the item is one of the X) or receiving the  discount (i.e. the item is one of the Y).
      - Other product promotions are not prorated and simply adjust the  parent product line item, and so the returned map is of size 1.
      - For shipping promotions, this method returns an empty map.
      
      
      Buy-X-Get-Y product promotions are prorated as follows: Each price
      adjustment generated by the promotion is sequentially prorated upon the
      related items according to the items' adjusted prices after all non-BOGO
      product promotions are considered, but before order promotions are
      considered.
      
      
      Order promotions are prorated sequentially upon non-excluded items
      according to the order in which they applied during promotion processing.
      
      
      The values in the map are inclusive of tax if this price adjustment is
      based on gross pricing, and exclusive of tax otherwise. The sum of the
      prorated prices always equals the price of this price adjustment.



---

### quantity
- quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of items this price adjustment applies to. This value
      is always equal to 1 for price adjustments generated by order or shipping
      promotions. For price adjustments generated by product promotions, this
      value represents the number of units of the parent product line item to
      which the adjustment applies. Because promotions may have a maximum
      number of applications this value may be less than the product line item
      quantity.
      
      
      For custom price adjustments, not generated by the promotions engine,
      this method always returns 0.



---

### reasonCode
- reasonCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code of the price adjustment. The list of available
      reason codes is editable system meta-data. An example for using the
      reason code is that in a call center application the CSR will explain
      why he gave a discount to the customer.



---

## Method Details

### getABTest()
- getABTest(): [ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md)
  - : Returns the B2C Commerce AB-test this price adjustment is associated with. The associated AB-test is determined
      from the ABTestID attribute which is set by the promotions engine when applying discounts.
      
      
      If the AB-test has been removed from the system since this price adjustment was created, this method returns
      null. This method always returns null for custom price adjustments.


    **Returns:**
    - the B2C Commerce AB-test the price adjustment was based on, or `null` if it was not based on
              an AB-test.



---

### getABTestID()
- getABTestID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the AB-test related to this price adjustment.

    **Returns:**
    - ID of related AB-test, or null.


---

### getABTestSegment()
- getABTestSegment(): [ABTestSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md)
  - : Returns the B2C Commerce AB-test segment this price adjustment is associated with. The associated AB-test segment
      is determined from the ABTestSegmentID attribute which is set by the promotions engine when applying discounts.
      
      
      If the AB-test, or this segment, has been removed from the system since this price adjustment was created, this
      method returns null. This method always returns null for custom price adjustments.


    **Returns:**
    - the B2C Commerce AB-test segment the price adjustment was based on, or `null` if it was not
              based on an AB-test.



---

### getABTestSegmentID()
- getABTestSegmentID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the AB-test segment related to this price adjustment.

    **Returns:**
    - ID of related AB-test segment, or null.


---

### getAppliedDiscount()
- getAppliedDiscount(): [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
  - : A `Discount` instance describing the discount applied to
      obtain this price-adjustment. This method only returns a non-null value
      if the price-adjustment was created
      
      - when a discount-plan was applied to a basket, or
      - as a _custom_price-adjustment using one of the methods  [ProductLineItem.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createpriceadjustmentstring-discount),  [ShippingLineItem.createShippingPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#createshippingpriceadjustmentstring-discount)or [LineItemCtnr.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring-discount).  
      
      
       Note an instance of the [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) subclasses is
      returned, such as [AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md) or
      [PriceBookPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PriceBookPriceDiscount.md), use
      [Discount.getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype) and the constants in
      [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md) to distinguish between types. Each subclass
      provides access to specific properties.


    **Returns:**
    - null or the discount applied


---

### getCampaign()
- getCampaign(): [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md)
  - : Returns the B2C Commerce campaign this price adjustment is associated with. The associated campaign is determined
      from the campaignID attribute which is set by the promotions engine when applying discounts.
      
      
      If the campaign has been removed from the system since this price adjustment was created, this method returns
      null. This method always returns null for custom price adjustments.
      
      
      Note: If the price adjustment was generated by a B2C Commerce promotion as part of an AB-test, then a Campaign
      object will be returned, but it is a mock implementation, and not a true Campaign. This behavior is required for
      backwards compatibility and should not be relied upon as it may change in future releases.


    **Returns:**
    - the B2C Commerce campaign the price adjustment was based on, or `null` if it was not based on
              a campaign.



---

### getCampaignID()
- getCampaignID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the campaign the price adjustment was based on.
      
      
      Note:If the price adjustment was generated by a B2C Commerce promotion as part of an AB-test, then an ID will be
      returned but it is not the ID of a true campaign. This behavior is required for backwards compatibility and
      should not be relied upon as it may change in future releases.


    **Returns:**
    - the ID of the B2C Commerce campaign the price adjustment was based on, or `null` if it was not
              based on a campaign.



---

### getCouponLineItem()
- getCouponLineItem(): [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)
  - : Returns the coupon line item related to this price adjustment.
      If the price adjustment is not based on a coupon, null is returned.


    **Returns:**
    - Coupon line item or null.


---

### getCreatedBy()
- getCreatedBy(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the user who created the price adjustment.
      This method returns a value if the price-adjustment was
      created as a _custom_ price-adjustment using one of the methods
      [ProductLineItem.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createpriceadjustmentstring-discount),
      [ShippingLineItem.createShippingPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#createshippingpriceadjustmentstring-discount)
      or [LineItemCtnr.createPriceAdjustment(String, Discount)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createpriceadjustmentstring-discount).
      
      
      If an agent user has created the price adjustment, the agent user's name
      is returned. Otherwise "Customer" is returned.


    **Returns:**
    - the name of the user who created the price adjustment


---

### getPromotion()
- getPromotion(): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)
  - : Returns the promotion associated with this price adjustment. The
      associated promotion is determined from the promotionID and campaignID
      attributes which are set by the promotions engine when applying
      discounts. Alternatively if the promotion applied as part of an AB-test,
      then the associated promotion is determined from the promotionID
      attribute and the hidden attributes, abTestID and abTestGroupID.
      
      
      If the promotion has been removed from the system since this price
      adjustment was created, or if the promotion still exists but is not
      assigned to any campaign or AB-test, this method returns null. If the
      promotion has been reassigned to a different campaign or AB-test since
      this price adjustment was created, then the system will return an
      appropriate Promotion instance. This method always returns null for
      custom price adjustments.


    **Returns:**
    - the associated promotion, or null.


---

### getPromotionID()
- getPromotionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the promotion related to this price adjustment.

    **Returns:**
    - ID of related promotion.


---

### getProratedPrices()
- getProratedPrices(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a map representing the product line items to which this price
      adjustment is "related" (in the sense defined below) and the portion of
      this adjustment's price which applies to each after discount prorating is
      performed. This information is sometimes useful to display in the
      storefront but is more often useful for integrating with backend
      order-management and accounting systems which require all discounts to be
      itemized.
      
      
      The definition of "related" product line items depends on the type of
      promotion which generated this price adjustment:
      
      
      - For order promotions, price adjustments are prorated across all  product line items which are not explicitly excluded by the promotion.  Custom order price adjustments apply to all items in the LineItemCtnr.
      - For Buy-X-Get-Y product promotions, price adjustments are prorated  across all items all product line items that are involved in the  promotion, meaning that the PLI has one or more items contributing to the  qualifying product count (i.e. the item is one of the X) or receiving the  discount (i.e. the item is one of the Y).
      - Other product promotions are not prorated and simply adjust the  parent product line item, and so the returned map is of size 1.
      - For shipping promotions, this method returns an empty map.
      
      
      Buy-X-Get-Y product promotions are prorated as follows: Each price
      adjustment generated by the promotion is sequentially prorated upon the
      related items according to the items' adjusted prices after all non-BOGO
      product promotions are considered, but before order promotions are
      considered.
      
      
      Order promotions are prorated sequentially upon non-excluded items
      according to the order in which they applied during promotion processing.
      
      
      The values in the map are inclusive of tax if this price adjustment is
      based on gross pricing, and exclusive of tax otherwise. The sum of the
      prorated prices always equals the price of this price adjustment.


    **Returns:**
    - map of ProductLineItems to Money instances representing the
              product line items across which this price adjustment is prorated
              and the portion of this adjustment which applies towards each.



---

### getQuantity()
- getQuantity(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of items this price adjustment applies to. This value
      is always equal to 1 for price adjustments generated by order or shipping
      promotions. For price adjustments generated by product promotions, this
      value represents the number of units of the parent product line item to
      which the adjustment applies. Because promotions may have a maximum
      number of applications this value may be less than the product line item
      quantity.
      
      
      For custom price adjustments, not generated by the promotions engine,
      this method always returns 0.


    **Returns:**
    - The number of items this price adjustment applies to.


---

### getReasonCode()
- getReasonCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code of the price adjustment. The list of available
      reason codes is editable system meta-data. An example for using the
      reason code is that in a call center application the CSR will explain
      why he gave a discount to the customer.


    **Returns:**
    - reason code of the price adjustment


---

### isBasedOnABTest()
- isBasedOnABTest(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a
      promotion assigned to an AB-test.


    **Returns:**
    - true if the price adjustment was generated by the B2C Commerce promotions engine when applying a
              promotion assigned to an AB-test, false otherwise.



---

### isBasedOnCampaign()
- ~~isBasedOnCampaign(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Returns true if the price adjustment was generated by the B2C Commerce promotions engine when applying a
      promotion assigned to a Campaign or an AB-test.


    **Returns:**
    - true if the price adjustment was generated by the B2C Commerce promotions engine, false otherwise.

    **Deprecated:**
**warning:** The method has been deprecated since the name implies that there is a related Campaign, which may not
            be true. Use `!isCustom()` instead.

---

### isBasedOnCoupon()
- isBasedOnCoupon(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the promotion line item results from a coupon.

    **Returns:**
    - true if the promotion line item results from a coupon, false otherwise.


---

### isCustom()
- isCustom(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this PriceAdjustment was created by custom script code.

    **Returns:**
    - true if this PriceAdjustment was created by custom script code, or false if it was created by B2C
              Commerce promotions engine.



---

### isManual()
- isManual(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this PriceAdjustment was added manually by a user.
      
      
      A manual PriceAdjustment is one which has been added as a result of
      a user interaction e.g. by a user editing an order.
      
      
      A non-manual PriceAdjustment is one which has been added for a different
      reason, e.g. by custom logic which automatically adjusts the price of
      particular products when certain conditions are met.


    **Returns:**
    - true if this PriceAdjustment was added manually by a user,
              otherwise - false



---

### setManual(Boolean)
- setManual(aFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Marks the current PriceAdjustment as manual/non-manual.
      
      
      Note that only custom PriceAdjustment can be marked as manual/non-manual.
      
      
      A manual PriceAdjustment is one which has been added as a result of
      a user interaction e.g. by a user editing an order.
      
      
      A non-manual PriceAdjustment is one which has been added for a different
      reason, e.g. by custom logic which automatically adjusts the price of
      particular products when certain conditions are met.


    **Parameters:**
    - aFlag - the manual flag to set

    **Throws:**
    - IllegalArgumentException - if the adjustment is not custom


---

### setReasonCode(String)
- setReasonCode(reasonCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the reason code, using the internal non-localizable value. Standard values are 'PRICE\_MATCH',
      'BACKORDER' and 'EVEN\_EXCHANGE', but the available list is editable system meta-data.


    **Parameters:**
    - reasonCode - reason code


---

<!-- prettier-ignore-end -->

<!-- document id=d32d98650aa29e55a796708cdd0c5e1582f322654e4304a1e1779d23ee4a99bb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.PriceAdjustmentLimitTypes.md -->

<!-- prettier-ignore-start -->
# Class PriceAdjustmentLimitTypes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.PriceAdjustmentLimitTypes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustmentLimitTypes.md)

Helper class containing price adjustment limit types.


## Constant Summary

| Constant | Description |
| --- | --- |
| [TYPE_ITEM](#type_item): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ITEM" | Constant for Price Adjustment Limit Type Item.  The price adjustment limit was created at the item level. |
| [TYPE_ORDER](#type_order): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER" | Constant for Price Adjustment Limit Type Order.  The price adjustment limit was created at the order level. |
| [TYPE_SHIPPING](#type_shipping): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPING" | Constant for Price Adjustment Limit Type Shipping.  The price adjustment limit was created at the shipping item level. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TYPE_ITEM

- TYPE_ITEM: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ITEM"
  - : Constant for Price Adjustment Limit Type Item.
      
      The price adjustment limit was created at the item level.



---

### TYPE_ORDER

- TYPE_ORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER"
  - : Constant for Price Adjustment Limit Type Order.
      
      The price adjustment limit was created at the order level.



---

### TYPE_SHIPPING

- TYPE_SHIPPING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPING"
  - : Constant for Price Adjustment Limit Type Shipping.
      
      The price adjustment limit was created at the shipping item level.



---

<!-- prettier-ignore-end -->

<!-- document id=b662a6374cb7bb1015e5565aeec57aec1110bb2a48028c496f0a0a698fdb6eaa url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.PriceBook.md -->

<!-- prettier-ignore-start -->
# Class PriceBook

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)

Represents a price book.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the price book. |
| [currencyCode](#currencycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the currency code of the price book. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of the price book. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of the price book. |
| [online](#online): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status of the price book. |
| [onlineFlag](#onlineflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status flag of the price book. |
| [onlineFrom](#onlinefrom): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date from which the price book is online or valid. |
| [onlineTo](#onlineto): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date until which the price book is online or valid. |
| [parentPriceBook](#parentpricebook): [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md) `(read-only)` | Returns the parent price book. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getcurrencycode)() | Returns the currency code of the price book. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getdescription)() | Returns the description of the price book. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getdisplayname)() | Returns the display name of the price book. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getid)() | Returns the ID of the price book. |
| [getOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getonlineflag)() | Returns the online status flag of the price book. |
| [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getonlinefrom)() | Returns the date from which the price book is online or valid. |
| [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getonlineto)() | Returns the date until which the price book is online or valid. |
| [getParentPriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#getparentpricebook)() | Returns the parent price book. |
| [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md#isonline)() | Returns the online status of the price book. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the price book.


---

### currencyCode
- currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the currency code of the price book.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of the price book.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of the price book.


---

### online
- online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status of the price book. The online status
      is calculated from the online status flag and the onlineFrom
      onlineTo dates defined for the price book.



---

### onlineFlag
- onlineFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status flag of the price book.


---

### onlineFrom
- onlineFrom: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date from which the price book is online or valid.


---

### onlineTo
- onlineTo: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date until which the price book is online or valid.


---

### parentPriceBook
- parentPriceBook: [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md) `(read-only)`
  - : Returns the parent price book.


---

## Method Details

### getCurrencyCode()
- getCurrencyCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the currency code of the price book.

    **Returns:**
    - Currency code of the price book


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the price book.

    **Returns:**
    - Currency code of the price book


---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of the price book.

    **Returns:**
    - Display name of the price book


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the price book.

    **Returns:**
    - ID of the price book


---

### getOnlineFlag()
- getOnlineFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status flag of the price book.

    **Returns:**
    - the online status flag of the price book.


---

### getOnlineFrom()
- getOnlineFrom(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date from which the price book is online or valid.

    **Returns:**
    - the date from which the price book is online or valid.


---

### getOnlineTo()
- getOnlineTo(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date until which the price book is online or valid.

    **Returns:**
    - the date until which the price book is online or valid.


---

### getParentPriceBook()
- getParentPriceBook(): [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)
  - : Returns the parent price book.

    **Returns:**
    - Parent price book


---

### isOnline()
- isOnline(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status of the price book. The online status
      is calculated from the online status flag and the onlineFrom
      onlineTo dates defined for the price book.


    **Returns:**
    - The online status of the price book.


---

<!-- prettier-ignore-end -->

<!-- document id=af74434c80f0c318bf66799187b5e33a2909ec86292f45f6d5522b428074b2d4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.PriceBookMgr.md -->

<!-- prettier-ignore-start -->
# Class PriceBookMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.PriceBookMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md)

Price book manager provides methods to access price books.


## Property Summary

| Property | Description |
| --- | --- |
| [allPriceBooks](#allpricebooks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all price books defined for the organization. |
| [applicablePriceBooks](#applicablepricebooks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) | Returns a collection of price books that are set in the user session. |
| [sitePriceBooks](#sitepricebooks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all price books assigned to the current site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [assignPriceBookToSite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#assignpricebooktositepricebook-string)([PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Assign a price book to a site. |
| static [getAllPriceBooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#getallpricebooks)() | Returns all price books defined for the organization. |
| static [getApplicablePriceBooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#getapplicablepricebooks)() | Returns a collection of price books that are set in the user session. |
| static [getPriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#getpricebookstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the price book of the current organization matching the specified ID. |
| static [getSitePriceBooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#getsitepricebooks)() | Returns all price books assigned to the current site. |
| static [setApplicablePriceBooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#setapplicablepricebookspricebook)([PriceBook...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)) | Sets one or more price books to be considered by the product price lookup. |
| static [unassignPriceBookFromAllSites](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#unassignpricebookfromallsitespricebook)([PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)) | Unassign a price book from all sites. |
| static [unassignPriceBookFromSite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md#unassignpricebookfromsitepricebook-string)([PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Unassign a price book from a site. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### allPriceBooks
- allPriceBooks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all price books defined for the organization.


---

### applicablePriceBooks
- applicablePriceBooks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of price books that are set in the user session.


---

### sitePriceBooks
- sitePriceBooks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all price books assigned to the current site. 
      
      Please note that this doesn't include parent price books not assigned to the site, but considered by the price
      lookup.



---

## Method Details

### assignPriceBookToSite(PriceBook, String)
- static assignPriceBookToSite(priceBook: [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md), siteId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Assign a price book to a site. This requires a transaction, see [Transaction.wrap(Function)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#wrapfunction)

    **Parameters:**
    - priceBook - price book to be assigned
    - siteId - id of the site to be assigned to, such as 'SiteGenesis'. The site has to be a storefront site.

    **Returns:**
    - true if price book is assigned to site. Throws an exception if price book doesn't exist or site doesn't
              exist or site is not a storefront site.



---

### getAllPriceBooks()
- static getAllPriceBooks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all price books defined for the organization.

    **Returns:**
    - All price books of the organization.


---

### getApplicablePriceBooks()
- static getApplicablePriceBooks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of price books that are set in the user session.

    **Returns:**
    - Collection of applicable price books set in the session.


---

### getPriceBook(String)
- static getPriceBook(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)
  - : Returns the price book of the current organization matching the specified ID.

    **Parameters:**
    - priceBookID - The price book id.

    **Returns:**
    - Price book or null of not found


---

### getSitePriceBooks()
- static getSitePriceBooks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all price books assigned to the current site. 
      
      Please note that this doesn't include parent price books not assigned to the site, but considered by the price
      lookup.


    **Returns:**
    - All price books assigned to the current site.


---

### setApplicablePriceBooks(PriceBook...)
- static setApplicablePriceBooks(priceBooks: [PriceBook...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)): void
  - : Sets one or more price books to be considered by the product price lookup. The information is stored in the user
      session. If no price book is set in the user session, all active and valid price books assigned to the site are
      used for the price lookup. If price books are set, only those price books are considered by the price lookup.
      Note that the system does not assure that a price book set by this API is assigned to the current site.


    **Parameters:**
    - priceBooks - The price books that are set in the session as applicable price books.


---

### unassignPriceBookFromAllSites(PriceBook)
- static unassignPriceBookFromAllSites(priceBook: [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Unassign a price book from all sites. This requires a transaction, see
      [Transaction.wrap(Function)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#wrapfunction)


    **Parameters:**
    - priceBook - price book to be unassigned

    **Returns:**
    - true if price book is unassigned from all sites. Throws an exception if price book doesn't exist


---

### unassignPriceBookFromSite(PriceBook, String)
- static unassignPriceBookFromSite(priceBook: [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md), siteId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Unassign a price book from a site. This requires a transaction, see
      [Transaction.wrap(Function)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#wrapfunction)


    **Parameters:**
    - priceBook - price book to be unassigned
    - siteId - id of the site to be unassigned from, such as 'SiteGenesis'. The site has to be a storefront site.

    **Returns:**
    - true if price book is unassigned from site. Throws an exception if price book doesn't exist or site
              doesn't exist or site is not a storefront site.



---

<!-- prettier-ignore-end -->

<!-- document id=ed441a5ebcdfdec8befd0ba5aa1d191a8e077e9d77ed7901134a5598b34c0b50 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.PriceBookPriceDiscount.md -->

<!-- prettier-ignore-start -->
# Class PriceBookPriceDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.PriceBookPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PriceBookPriceDiscount.md)

Discount representing that a product's price has been calculated from a
separate sales price book other than the standard price book assigned to the
site.



## Property Summary

| Property | Description |
| --- | --- |
| [priceBookID](#pricebookid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the price book identifier. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getPriceBookID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PriceBookPriceDiscount.md#getpricebookid)() | Returns the price book identifier. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### priceBookID
- priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the price book identifier.


---

## Method Details

### getPriceBookID()
- getPriceBookID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the price book identifier.

    **Returns:**
    - the price book identifier.


---

<!-- prettier-ignore-end -->

<!-- document id=19cb4baa45930d908b4d32daa021e47c6ad2c4a3545966156381e2951701da20 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.PrintWriter.md -->

<!-- prettier-ignore-start -->
# Class PrintWriter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)
    - [dw.io.PrintWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md)

Template output stream writer.

Printwriter is available in the template scripting context and is used
to write data into the template output stream. You cannot instantiate this class
directly. Instead, the system assigns the object to variable named 'out' in the script context
to be used by the template scripts.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [print](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md#printstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Prints the given string into the output stream. |
| [println](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md#println)() | Prints a line break into the output stream. |
| [println](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md#printlnstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Print the given string followed by a line break into the output stream. |

### Methods inherited from class Writer

[close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#close), [flush](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#flush), [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring), [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring-number-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### print(String)
- print(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Prints the given string into the output stream.

    **Parameters:**
    - str - the String object


---

### println()
- println(): void
  - : Prints a line break into the output stream.


---

### println(String)
- println(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Print the given string followed by a line break into the output stream.

    **Parameters:**
    - str - the String object


---

<!-- prettier-ignore-end -->

<!-- document id=979cb88ede179e4f522645e24552718ac6a1822785ea8c6cdfe763fad43d6b33 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.Product.md -->

<!-- prettier-ignore-start -->
# Class Product

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)

Represents a product in Commerce Cloud Digital. Products are identified by
a unique product ID, sometimes called the SKU. There are several different
types of product:


- **Simple product**
- **Master products:**This type of product defines a template for a set  of related products which differ only by a set of defined  "variation attributes", such as size or color. Master products are not  orderable themselves. The variation information for a master product is  available through its [ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md).
- **Variant:**Variants are the actual orderable products that are  related to a master product. Each variant of a master product has a unique  set of values for the defined variation attributes. Variants are said to be  "mastered" by the corresponding master product.
- **Option products:**Option products define additional options, such  as a warranty, which can be purchased for a defined price at the time the  product is purchased. The option information for an option product is  available through its [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md).
- **Product-sets:**A product-set is a set of products which the  merchant can sell as a collection in the storefront, for example an outfit of  clothes. Product-sets are not orderable and therefore do not define prices.  They exist only to group the products together in the storefront UI. Members  of the set are called "product-set-products".
- **Products bundles:**A collection of products which can be ordered as  a single unit and therefore can define its own price and inventory record.




Product price and availability information are retrievable through
[getPriceModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodel) and [getAvailabilityModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel) respectively.
Attribute information is retrievable through [getAttributeModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel).
Products may reference other products, either as recommendations or product
links. This class provides the methods for retrieving these referenced
products.


Products belong to a catalog (the "owning" catalog) and are assigned to
categories in other catalogs. Products assigned to categories in the site
catalog are typically orderable on the site.


Any API method which returns products will return an instance of a
[Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md) for variant products. This subclass contains
methods which are specific to this type of product.



## All Known Subclasses
[Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md), [VariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md)
## Property Summary

| Property | Description |
| --- | --- |
| [EAN](#ean): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the European Article Number of the product. |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product. |
| [UPC](#upc): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Universal Product Code of the product. |
| [activeData](#activedata): [ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md) `(read-only)` | Returns the active data for this product, for the current site. |
| [allCategories](#allcategories): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all categories to which this product is assigned. |
| [allCategoryAssignments](#allcategoryassignments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all category assignments for this product in any catalog. |
| [allIncomingProductLinks](#allincomingproductlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all incoming ProductLinks. |
| [allProductLinks](#allproductlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all outgoing ProductLinks. |
| [assignedToSiteCatalog](#assignedtositecatalog): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if the product is assigned to the current site (via the site catalog), otherwise  `false` is returned. |
| [attributeModel](#attributemodel): [ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md) `(read-only)` | Returns this product's ProductAttributeModel, which makes access to the  product attribute information convenient. |
| [availabilityModel](#availabilitymodel): [ProductAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md) `(read-only)` | Returns the availability model, which can be used to determine availability  information for a product. |
| ~~[available](#available): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Identifies if the product is available. |
| ~~[availableFlag](#availableflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ | Identifies if the product is available. |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Brand of the product. |
| [bundle](#bundle): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this product instance is a product bundle. |
| [bundled](#bundled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this product instance is bundled within at least one  product bundle. |
| [bundledProducts](#bundledproducts): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing all products that participate in the  product bundle. |
| [bundles](#bundles): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all bundles in which this product is included. |
| [categories](#categories): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all categories to which this product is assigned  and which are also available through the current site. |
| [categorized](#categorized): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this product is bound to at least one catalog category. |
| [categoryAssignments](#categoryassignments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of category assignments for this product in  the current site catalog. |
| [classificationCategory](#classificationcategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the classification category associated with this Product. |
| [facebookEnabled](#facebookenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the product is Facebook enabled. |
| ~~[image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)~~ `(read-only)` | Returns the product's image. |
| [incomingProductLinks](#incomingproductlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns incoming ProductLinks, where the source product is a site product. |
| [longDescription](#longdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the product's long description in the current locale. |
| [manufacturerName](#manufacturername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the product manufacturer. |
| [manufacturerSKU](#manufacturersku): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value of the manufacturer's stock keeping unit. |
| [master](#master): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this product instance is a product master. |
| [minOrderQuantity](#minorderquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the minimum order quantity for this product. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the product in the current locale. |
| [online](#online): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status of the product. |
| [onlineCategories](#onlinecategories): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all currently online categories to which this  product is assigned and which are also available through the current  site. |
| [onlineFlag](#onlineflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the online status flag of the product. |
| [onlineFrom](#onlinefrom): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date from which the product is online or valid. |
| [onlineTo](#onlineto): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date until which the product is online or valid. |
| [optionModel](#optionmodel): [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md) `(read-only)` | Returns the product's option model. |
| [optionProduct](#optionproduct): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the product has options. |
| [orderableRecommendations](#orderablerecommendations): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a list of outgoing recommendations for this product. |
| [pageDescription](#pagedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns product's page description in the default locale. |
| [pageKeywords](#pagekeywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product's page keywords in the default locale. |
| [pageMetaTags](#pagemetatags): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)` | Returns all page meta tags, defined for this instance for which content can be generated. |
| [pageTitle](#pagetitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product's page title in the default locale. |
| [pageURL](#pageurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product's page URL in the default locale. |
| [pinterestEnabled](#pinterestenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the product is Pinterest enabled. |
| [priceModel](#pricemodel): [ProductPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md) `(read-only)` | Returns the price model, which can be used to retrieve a price  for this product. |
| [primaryCategory](#primarycategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the primary category of the product within the current site catalog. |
| [primaryCategoryAssignment](#primarycategoryassignment): [CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md) `(read-only)` | Returns the category assignment to the primary category in the current site  catalog or null if no primary category is defined within the current site  catalog. |
| [product](#product): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the instance represents a product. |
| [productLinks](#productlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all outgoing ProductLinks, where the target product is also  available in the current site. |
| [productSet](#productset): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the instance represents a product set, otherwise 'false'. |
| [productSetProduct](#productsetproduct): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this product is part of any product set, otherwise false. |
| [productSetProducts](#productsetproducts): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all products which are assigned to this product  and which are also available through the current site. |
| [productSets](#productsets): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all product sets in which this product is included. |
| [recommendations](#recommendations): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the outgoing recommendations for this product which  belong to the site catalog. |
| ~~[retailSet](#retailset): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Identifies if this product instance is part of a retail set. |
| [searchPlacement](#searchplacement): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the product's search placement classification. |
| [searchRank](#searchrank): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the product's search rank. |
| [searchable](#searchable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the product is searchable. |
| [searchableFlag](#searchableflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns, whether the product is currently searchable. |
| [searchableIfUnavailableFlag](#searchableifunavailableflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the searchable status of the [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) if unavailable. |
| [shortDescription](#shortdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the product's short description in the current locale. |
| [siteMapChangeFrequency](#sitemapchangefrequency): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product's change frequency needed for the sitemap creation. |
| [siteMapIncluded](#sitemapincluded): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the status if the product is included into the sitemap. |
| [siteMapPriority](#sitemappriority): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the product's priority needed for the sitemap creation. |
| ~~[siteProduct](#siteproduct): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Returns 'true' if the product is assigned to the current site (via the  site catalog), otherwise 'false' is returned. |
| [stepQuantity](#stepquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the steps in which the order amount of the product can be  increased. |
| [storeReceiptName](#storereceiptname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the store receipt name of the product in the current locale. |
| [storeTaxClass](#storetaxclass): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the store tax class ID. |
| [taxClassID](#taxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product's tax class, by resolving  the Global Preference setting selected. |
| [template](#template): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the product's rendering template. |
| ~~[thumbnail](#thumbnail): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)~~ `(read-only)` | Returns the product's thumbnail image. |
| [unit](#unit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product's sales unit. |
| [unitQuantity](#unitquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the product's unit quantity. |
| [variant](#variant): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this product instance is mastered by a product master. |
| [variants](#variants): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all variants assigned to this variation master  or variation group product. |
| [variationGroup](#variationgroup): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this product instance is a variation group product. |
| [variationGroups](#variationgroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all variation groups assigned to this variation  master product. |
| [variationModel](#variationmodel): [ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md) `(read-only)` | Returns the variation model of this product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| ~~[assignedToCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#assignedtocategorycategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md))~~ | Identifies if this product is bound to the specified catalog category. |
| [getActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getactivedata)() | Returns the active data for this product, for the current site. |
| [getAllCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallcategories)() | Returns a collection of all categories to which this product is assigned. |
| [getAllCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallcategoryassignments)() | Returns all category assignments for this product in any catalog. |
| [getAllIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallincomingproductlinks)() | Returns all incoming ProductLinks. |
| [getAllIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallincomingproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all incoming ProductLinks of a specific type. |
| [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallproductlinks)() | Returns all outgoing ProductLinks. |
| [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all outgoing ProductLinks of a specific type. |
| [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallrecommendationscatalog)([Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)) | Returns the outgoing recommendations for this product which belong to the  specified catalog. |
| [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallrecommendationscatalog-number)([Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the outgoing recommendations for this product which are of the  specified type and which belong to the specified catalog. |
| [getAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel)() | Returns this product's ProductAttributeModel, which makes access to the  product attribute information convenient. |
| [getAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel)() | Returns the availability model, which can be used to determine availability  information for a product. |
| [getAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodelproductinventorylist)([ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)) | Returns the availability model of the given inventory list, which can be  used to determine availability information for a product. |
| ~~[getAvailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailableflag)()~~ | Identifies if the product is available. |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbrand)() | Returns the Brand of the product. |
| [getBundledProductQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundledproductquantityproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the quantity of the specified product within the bundle. |
| [getBundledProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundledproducts)() | Returns a collection containing all products that participate in the  product bundle. |
| [getBundles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundles)() | Returns a collection of all bundles in which this product is included. |
| [getCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategories)() | Returns a collection of all categories to which this product is assigned  and which are also available through the current site. |
| [getCategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategoryassignmentcategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)) | Returns the category assignment for a specific category. |
| [getCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategoryassignments)() | Returns a collection of category assignments for this product in  the current site catalog. |
| [getClassificationCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getclassificationcategory)() | Returns the classification category associated with this Product. |
| [getEAN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getean)() | Returns the European Article Number of the product. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getid)() | Returns the ID of the product. |
| ~~[getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimage)()~~ | Returns the product's image. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and returns the first image. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and returns the image at  the specific index. |
| [getImages](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all images assigned to this product for a specific view type,  e.g. |
| [getIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getincomingproductlinks)() | Returns incoming ProductLinks, where the source product is a site product. |
| [getIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getincomingproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns incoming ProductLinks, where the source product is a site product  of a specific type. |
| [getLongDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getlongdescription)() | Returns the product's long description in the current locale. |
| [getManufacturerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getmanufacturername)() | Returns the name of the product manufacturer. |
| [getManufacturerSKU](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getmanufacturersku)() | Returns the value of the manufacturer's stock keeping unit. |
| [getMinOrderQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getminorderquantity)() | Returns the minimum order quantity for this product. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getname)() | Returns the name of the product in the current locale. |
| [getOnlineCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlinecategories)() | Returns a collection of all currently online categories to which this  product is assigned and which are also available through the current  site. |
| [getOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlineflag)() | Returns the online status flag of the product. |
| [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlinefrom)() | Returns the date from which the product is online or valid. |
| [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlineto)() | Returns the date until which the product is online or valid. |
| [getOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getoptionmodel)() | Returns the product's option model. |
| [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getorderablerecommendations)() | Returns a list of outgoing recommendations for this product. |
| [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getorderablerecommendationsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a list of outgoing recommendations for this product. |
| [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagedescription)() | Returns product's page description in the default locale. |
| [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagekeywords)() | Returns the product's page keywords in the default locale. |
| [getPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagemetatagstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the page meta tag for the specified id. |
| [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagemetatags)() | Returns all page meta tags, defined for this instance for which content can be generated. |
| [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagetitle)() | Returns the product's page title in the default locale. |
| [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpageurl)() | Returns the product's page URL in the default locale. |
| [getPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodel)() | Returns the price model, which can be used to retrieve a price  for this product. |
| [getPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodelproductoptionmodel)([ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)) | Returns the price model based on the specified optionModel. |
| [getPrimaryCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getprimarycategory)() | Returns the primary category of the product within the current site catalog. |
| [getPrimaryCategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getprimarycategoryassignment)() | Returns the category assignment to the primary category in the current site  catalog or null if no primary category is defined within the current site  catalog. |
| [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductlinks)() | Returns all outgoing ProductLinks, where the target product is also  available in the current site. |
| [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all outgoing ProductLinks of a specific type, where the target  product is also available in the current site. |
| [getProductSetProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductsetproducts)() | Returns a collection of all products which are assigned to this product  and which are also available through the current site. |
| [getProductSets](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductsets)() | Returns a collection of all product sets in which this product is included. |
| [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendations)() | Returns the outgoing recommendations for this product which  belong to the site catalog. |
| [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendationsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the outgoing recommendations for this product which are of the  specified type and which belong to the site catalog. |
| [getSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchplacement)() | Returns the product's search placement classification. |
| [getSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchrank)() | Returns the product's search rank. |
| [getSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchableflag)() | Returns, whether the product is currently searchable. |
| [getSearchableIfUnavailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchableifunavailableflag)() | Returns the searchable status of the [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) if unavailable. |
| [getShortDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getshortdescription)() | Returns the product's short description in the current locale. |
| [getSiteMapChangeFrequency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemapchangefrequency)() | Returns the product's change frequency needed for the sitemap creation. |
| [getSiteMapIncluded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemapincluded)() | Returns the status if the product is included into the sitemap. |
| [getSiteMapPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemappriority)() | Returns the product's priority needed for the sitemap creation. |
| [getStepQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstepquantity)() | Returns the steps in which the order amount of the product can be  increased. |
| [getStoreReceiptName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstorereceiptname)() | Returns the store receipt name of the product in the current locale. |
| [getStoreTaxClass](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstoretaxclass)() | Returns the store tax class ID. |
| [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#gettaxclassid)() | Returns the ID of the product's tax class, by resolving  the Global Preference setting selected. |
| [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#gettemplate)() | Returns the name of the product's rendering template. |
| ~~[getThumbnail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getthumbnail)()~~ | Returns the product's thumbnail image. |
| [getUPC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getupc)() | Returns the Universal Product Code of the product. |
| [getUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getunit)() | Returns the product's sales unit. |
| [getUnitQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getunitquantity)() | Returns the product's unit quantity. |
| [getVariants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariants)() | Returns a collection of all variants assigned to this variation master  or variation group product. |
| [getVariationGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationgroups)() | Returns a collection of all variation groups assigned to this variation  master product. |
| [getVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationmodel)() | Returns the variation model of this product. |
| [includedInBundle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#includedinbundleproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Identifies if the specified product participates in this product bundle. |
| [isAssignedToCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtocategorycategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)) | Returns 'true' if item is assigned to the specified  category. |
| [isAssignedToSiteCatalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtositecatalog)() | Returns `true` if the product is assigned to the current site (via the site catalog), otherwise  `false` is returned. |
| ~~[isAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isavailable)()~~ | Identifies if the product is available. |
| [isBundle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isbundle)() | Identifies if this product instance is a product bundle. |
| [isBundled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isbundled)() | Identifies if this product instance is bundled within at least one  product bundle. |
| [isCategorized](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#iscategorized)() | Identifies if this product is bound to at least one catalog category. |
| [isFacebookEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isfacebookenabled)() | Identifies if the product is Facebook enabled. |
| [isMaster](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#ismaster)() | Identifies if this product instance is a product master. |
| [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isonline)() | Returns the online status of the product. |
| [isOptionProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isoptionproduct)() | Identifies if the product has options. |
| [isPinterestEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#ispinterestenabled)() | Identifies if the product is Pinterest enabled. |
| [isProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproduct)() | Returns 'true' if the instance represents a product. |
| [isProductSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductset)() | Returns 'true' if the instance represents a product set, otherwise 'false'. |
| [isProductSetProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductsetproduct)() | Returns true if this product is part of any product set, otherwise false. |
| ~~[isRetailSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isretailset)()~~ | Identifies if this product instance is part of a retail set. |
| [isSearchable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#issearchable)() | Identifies if the product is searchable. |
| ~~[isSiteProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#issiteproduct)()~~ | Returns 'true' if the product is assigned to the current site (via the  site catalog), otherwise 'false' is returned. |
| [isVariant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isvariant)() | Identifies if this product instance is mastered by a product master. |
| [isVariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isvariationgroup)() | Identifies if this product instance is a variation group product. |
| ~~[setAvailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setavailableflagboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))~~ | Set the availability status flag of the product. |
| [setOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setonlineflagboolean---variant-1)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set the online status flag of the product. |
| [setOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setonlineflagboolean---variant-2)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set the online status flag of the product for the current site. |
| [setSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchplacementnumber---variant-1)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the product's search placement. |
| [setSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchplacementnumber---variant-2)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the product's search placement classification in context of the current site. |
| [setSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchranknumber---variant-1)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the product's search rank. |
| [setSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchranknumber---variant-2)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the product's search rank in context of the current site. |
| [setSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchableflagboolean---variant-1)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set the flag indicating whether the product is searchable or not. |
| [setSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchableflagboolean---variant-2)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set the flag indicating whether the product is searchable or not in context of the current site. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### EAN
- EAN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the European Article Number of the product.


---

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product.


---

### UPC
- UPC: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Universal Product Code of the product.


---

### activeData
- activeData: [ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md) `(read-only)`
  - : Returns the active data for this product, for the current site.


---

### allCategories
- allCategories: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all categories to which this product is assigned.


---

### allCategoryAssignments
- allCategoryAssignments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all category assignments for this product in any catalog.


---

### allIncomingProductLinks
- allIncomingProductLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all incoming ProductLinks.


---

### allProductLinks
- allProductLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all outgoing ProductLinks.


---

### assignedToSiteCatalog
- assignedToSiteCatalog: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if the product is assigned to the current site (via the site catalog), otherwise
      `false` is returned.
      
      
      In case of the product being a variant, the variant will be considered as assigned if its master, one of the
      variation groups it is in or itself is assigned to the site catalog. In case this is triggered for a variation
      group the variation group is considered as assigned if its master or itself is assigned.



---

### attributeModel
- attributeModel: [ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md) `(read-only)`
  - : Returns this product's ProductAttributeModel, which makes access to the
      product attribute information convenient. The model is calculated based
      on the product attributes assigned to this product's classification
      category (or any of it's ancestors) and the global attribute definitions
      for the system object type 'Product'. If this product has no
      classification category, the attribute model is calculated on the global
      attribute definitions only. If this product is a variant, then the
      attribute model is calculated based on the classification category of its
      corresponding master product.



---

### availabilityModel
- availabilityModel: [ProductAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md) `(read-only)`
  - : Returns the availability model, which can be used to determine availability
      information for a product.



---

### available
- ~~available: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Identifies if the product is available.

    **Deprecated:**
**warning:** Use [getAvailabilityModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel).isInStock() instead

---

### availableFlag
- ~~availableFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Identifies if the product is available.

    **Deprecated:**
**warning:** Use [getAvailabilityModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel) instead.

---

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Brand of the product.


---

### bundle
- bundle: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this product instance is a product bundle.


---

### bundled
- bundled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this product instance is bundled within at least one
      product bundle.



---

### bundledProducts
- bundledProducts: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing all products that participate in the
      product bundle.



---

### bundles
- bundles: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all bundles in which this product is included.
      The method only returns bundles assigned to the current site.



---

### categories
- categories: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all categories to which this product is assigned
      and which are also available through the current site.



---

### categorized
- categorized: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this product is bound to at least one catalog category.


---

### categoryAssignments
- categoryAssignments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of category assignments for this product in
      the current site catalog.



---

### classificationCategory
- classificationCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the classification category associated with this Product. A
      product has a single classification category which may or may not be in
      the site catalog. The classification category defines the attribute set
      of the product. See [getAttributeModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel) for
      how the classification category is used.



---

### facebookEnabled
- facebookEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the product is Facebook enabled.


---

### image
- ~~image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)~~ `(read-only)`
  - : Returns the product's image.

    **Deprecated:**
**warning:** Commerce Cloud Digital introduces a new more powerful product
image management. It allows to group product images by self-defined view types
(e.g. 'large', 'thumbnail', 'swatch') and variation values (e.g. for attribute
color 'red', 'blue'). Images can be annotated with pattern based title and
alt. Product images can be accessed from Digital locations or external storage
locations.


Please use the new product image management. Therefore you have to set
up the common product image settings like view types, image location,
default image alt and title for your catalogs first. After that you can
group your product images by the previously defined view types in context
of a product. Finally use [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and
[getImage(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring-number) to access your images.

---

### incomingProductLinks
- incomingProductLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns incoming ProductLinks, where the source product is a site product.


---

### longDescription
- longDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the product's long description in the current locale.


---

### manufacturerName
- manufacturerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the product manufacturer.


---

### manufacturerSKU
- manufacturerSKU: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value of the manufacturer's stock keeping unit.


---

### master
- master: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this product instance is a product master.


---

### minOrderQuantity
- minOrderQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the minimum order quantity for this product.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the product in the current locale.


---

### online
- online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status of the product. The online status
      is calculated from the online status flag and the onlineFrom
      onlineTo dates defined for the product.



---

### onlineCategories
- onlineCategories: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all currently online categories to which this
      product is assigned and which are also available through the current
      site. A category is currently online if its online flag equals true and
      the current site date is within the date range defined by the onlineFrom
      and onlineTo attributes.



---

### onlineFlag
- onlineFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the online status flag of the product.


---

### onlineFrom
- onlineFrom: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date from which the product is online or valid.


---

### onlineTo
- onlineTo: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date until which the product is online or valid.


---

### optionModel
- optionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md) `(read-only)`
  - : Returns the product's option model. The option values selections are
      initialized with the values defined for the product, or the default values
      defined for the option.



---

### optionProduct
- optionProduct: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the product has options.


---

### orderableRecommendations
- orderableRecommendations: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a list of outgoing recommendations for this product. This method
      behaves similarly to [getRecommendations()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendations) but additionally filters out
      recommendations for which the target product is unorderable according to
      its product availability model.


    **See Also:**
    - [ProductAvailabilityModel.isOrderable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderable)


---

### pageDescription
- pageDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns product's page description in the default locale.


---

### pageKeywords
- pageKeywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product's page keywords in the default locale.


---

### pageMetaTags
- pageMetaTags: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)`
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the product detail page meta tag context and rules. The rules are
      obtained from the current product context or inherited from variation groups, master product, the primary
      category, up to the root category.



---

### pageTitle
- pageTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product's page title in the default locale.


---

### pageURL
- pageURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product's page URL in the default locale.


---

### pinterestEnabled
- pinterestEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the product is Pinterest enabled.


---

### priceModel
- priceModel: [ProductPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md) `(read-only)`
  - : Returns the price model, which can be used to retrieve a price
      for this product.



---

### primaryCategory
- primaryCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the primary category of the product within the current site catalog.


---

### primaryCategoryAssignment
- primaryCategoryAssignment: [CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md) `(read-only)`
  - : Returns the category assignment to the primary category in the current site
      catalog or null if no primary category is defined within the current site
      catalog.



---

### product
- product: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the instance represents a product. Returns 'false' if
      the instance represents a product set.


    **See Also:**
    - [isProductSet()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductset)


---

### productLinks
- productLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all outgoing ProductLinks, where the target product is also
      available in the current site. The ProductLinks are unsorted.



---

### productSet
- productSet: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the instance represents a product set, otherwise 'false'.

    **See Also:**
    - [isProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproduct)


---

### productSetProduct
- productSetProduct: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this product is part of any product set, otherwise false.


---

### productSetProducts
- productSetProducts: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all products which are assigned to this product
      and which are also available through the current site.  If this product
      does not represent a product set then an empty collection will be
      returned.



---

### productSets
- productSets: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all product sets in which this product is included.
      The method only returns product sets assigned to the current site.



---

### recommendations
- recommendations: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the outgoing recommendations for this product which
      belong to the site catalog.  If this product is not assigned to the site
      catalog, or there is no site catalog, an empty collection is returned.
      Only recommendations for which the target product exists and is assigned
      to the site catalog are returned.  The recommendations are sorted by
      their explicitly set order.



---

### retailSet
- ~~retailSet: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Identifies if this product instance is part of a retail set.

    **Deprecated:**
**warning:** Use [isProductSet()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductset) instead

---

### searchPlacement
- searchPlacement: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the product's search placement classification. The higher the
      numeric product placement value, the more relevant is the product when
      sorting search results. The range of numeric placement values is
      defined in the meta data of object type 'Product' and can therefore be
      customized.



---

### searchRank
- searchRank: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the product's search rank. The higher the numeric product rank,
      the more relevant is the product when sorting search results. The range of
      numeric rank values is defined in the meta data of object type 'Product'
      and can therefore be customized.



---

### searchable
- searchable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the product is searchable.


---

### searchableFlag
- searchableFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns, whether the product is currently searchable.


---

### searchableIfUnavailableFlag
- searchableIfUnavailableFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the searchable status of the [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) if unavailable.
      
      Besides `true` or `false`, the return value `null` indicates that the value is not set.



---

### shortDescription
- shortDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the product's short description in the current locale.


---

### siteMapChangeFrequency
- siteMapChangeFrequency: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product's change frequency needed for the sitemap creation.


---

### siteMapIncluded
- siteMapIncluded: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the status if the product is included into the sitemap.


---

### siteMapPriority
- siteMapPriority: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the product's priority needed for the sitemap creation.


---

### siteProduct
- ~~siteProduct: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Returns 'true' if the product is assigned to the current site (via the
      site catalog), otherwise 'false' is returned.


    **Deprecated:**
**warning:** Use [isAssignedToSiteCatalog()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtositecatalog) instead

---

### stepQuantity
- stepQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the steps in which the order amount of the product can be
      increased.



---

### storeReceiptName
- storeReceiptName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the store receipt name of the product in the current locale.


---

### storeTaxClass
- storeTaxClass: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the store tax class ID.
      
      This is an optional override for in-store tax calculation.



---

### taxClassID
- taxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product's tax class, by resolving
      the Global Preference setting selected. If the Localized
      Tax Class setting under Global Preferences -> Products is
      selected, the localizedTaxClassID attribute value will be
      returned, else the legacy taxClassID attribute value will
      be returned.



---

### template
- template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the product's rendering template.


---

### thumbnail
- ~~thumbnail: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)~~ `(read-only)`
  - : Returns the product's thumbnail image.

    **Deprecated:**
**warning:** Commerce Cloud Digital introduces a new more powerful product
image management. It allows to group product images by self-defined view types
(e.g. 'large', 'thumbnail', 'swatch') and variation values (e.g. for attribute
color 'red', 'blue'). Images can be annotated with pattern based title and
alt. Product images can be accessed from Digital locations or external storage
locations.


Please use the new product image management. Therefore you have to set
up the common product image settings like view types, image location,
default image alt and title for your catalogs first. After that you can
group your product images by the previously defined view types in context
of a product. Finally use [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and
[getImage(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring-number) to access your images.

---

### unit
- unit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product's sales unit.


---

### unitQuantity
- unitQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the product's unit quantity.


---

### variant
- variant: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this product instance is mastered by a product master.


---

### variants
- variants: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all variants assigned to this variation master
      or variation group product. All variants are returned regardless of whether
      they are online or offline.
      
      If this product does not represent a variation master or variation group
      product then an empty collection is returned.



---

### variationGroup
- variationGroup: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this product instance is a variation group product.


---

### variationGroups
- variationGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all variation groups assigned to this variation
      master product. All variation groups are returned regardless of whether
      they are online or offline.
      
      If this product does not represent a variation master product then an
      empty collection is returned.



---

### variationModel
- variationModel: [ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md) `(read-only)`
  - : Returns the variation model of this product. If this product is a master
      product, then the returned model will encapsulate all the information
      about its variation attributes and variants. If this product is a variant
      product, then the returned model will encapsulate all the same
      information, but additionally pre-select all the variation attribute
      values of this variant. (See [ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md) for
      details on what "selected" means.) If this product is neither a master
      product or a variation product, then a model will be returned but will be
      essentially empty and not useful for any particular purpose.



---

## Method Details

### assignedToCategory(Category)
- ~~assignedToCategory(category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Identifies if this product is bound to the specified catalog category.

    **Parameters:**
    - category - the CatalogCategory to check.

    **Returns:**
    - true if the product is bound to the CatalogCategory, false
              otherwise.


    **Deprecated:**
**warning:** Use [isAssignedToCategory(Category)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtocategorycategory)

---

### getActiveData()
- getActiveData(): [ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md)
  - : Returns the active data for this product, for the current site.

    **Returns:**
    - the active data for this product for the current site.


---

### getAllCategories()
- getAllCategories(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all categories to which this product is assigned.

    **Returns:**
    - Collection of categories.


---

### getAllCategoryAssignments()
- getAllCategoryAssignments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all category assignments for this product in any catalog.

    **Returns:**
    - Collection of category assignments of the product in any catalog.


---

### getAllIncomingProductLinks()
- getAllIncomingProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all incoming ProductLinks.

    **Returns:**
    - a collection of all incoming ProductLinks.


---

### getAllIncomingProductLinks(Number)
- getAllIncomingProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all incoming ProductLinks of a specific type.

    **Parameters:**
    - type - the type of ProductLinks to use.

    **Returns:**
    - a collection of all incoming ProductLinks of a specific type.


---

### getAllProductLinks()
- getAllProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all outgoing ProductLinks.

    **Returns:**
    - a collection of all outgoing ProductLinks.


---

### getAllProductLinks(Number)
- getAllProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all outgoing ProductLinks of a specific type.

    **Parameters:**
    - type - the type of ProductLinks to fetch.

    **Returns:**
    - a collection of all outgoing ProductLinks of a specific type.


---

### getAllRecommendations(Catalog)
- getAllRecommendations(catalog: [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the outgoing recommendations for this product which belong to the
      specified catalog. The recommendations are sorted by their explicitly set
      order.


    **Parameters:**
    - catalog - the catalog containing the recommendations.

    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getAllRecommendations(Catalog, Number)
- getAllRecommendations(catalog: [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md), type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the outgoing recommendations for this product which are of the
      specified type and which belong to the specified catalog.
      The recommendations are sorted by their explicitly set order.


    **Parameters:**
    - catalog - the catalog containing the recommendations.
    - type - the recommendation type.

    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getAttributeModel()
- getAttributeModel(): [ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md)
  - : Returns this product's ProductAttributeModel, which makes access to the
      product attribute information convenient. The model is calculated based
      on the product attributes assigned to this product's classification
      category (or any of it's ancestors) and the global attribute definitions
      for the system object type 'Product'. If this product has no
      classification category, the attribute model is calculated on the global
      attribute definitions only. If this product is a variant, then the
      attribute model is calculated based on the classification category of its
      corresponding master product.


    **Returns:**
    - the ProductAttributeModel for this product.


---

### getAvailabilityModel()
- getAvailabilityModel(): [ProductAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md)
  - : Returns the availability model, which can be used to determine availability
      information for a product.


    **Returns:**
    - the availability model for a product.


---

### getAvailabilityModel(ProductInventoryList)
- getAvailabilityModel(list: [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)): [ProductAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md)
  - : Returns the availability model of the given inventory list, which can be
      used to determine availability information for a product.


    **Parameters:**
    - list - The inventory list to get the availability model for. Must             not be null or an exception will be raised.

    **Returns:**
    - the availability model of the given inventory list for a product.


---

### getAvailableFlag()
- ~~getAvailableFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Identifies if the product is available.

    **Returns:**
    - the availability status flag of the product.

    **Deprecated:**
**warning:** Use [getAvailabilityModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel) instead.

---

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Brand of the product.

    **Returns:**
    - the Brand of the product.


---

### getBundledProductQuantity(Product)
- getBundledProductQuantity(aProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of the specified product within the bundle. If the
      specified product is not part of the bundle, a 0 quantity is returned.


    **Parameters:**
    - aProduct - The product to determine the quantity for.

    **Returns:**
    - The quantity of the product within the bundle or 0 if the product
              is not part of the bundle.



---

### getBundledProducts()
- getBundledProducts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing all products that participate in the
      product bundle.


    **Returns:**
    - A collection containing all products of the product bundle.


---

### getBundles()
- getBundles(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all bundles in which this product is included.
      The method only returns bundles assigned to the current site.


    **Returns:**
    - Collection of bundles in which this product is included, possibly empty.


---

### getCategories()
- getCategories(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all categories to which this product is assigned
      and which are also available through the current site.


    **Returns:**
    - Collection of categories to which this product is assigned
      and which are also available through the current site.



---

### getCategoryAssignment(Category)
- getCategoryAssignment(category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): [CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md)
  - : Returns the category assignment for a specific category.

    **Parameters:**
    - category - the category to use when fetching assignments.

    **Returns:**
    - The category assignment for a specific category.


---

### getCategoryAssignments()
- getCategoryAssignments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of category assignments for this product in
      the current site catalog.


    **Returns:**
    - Collection of category assignments.


---

### getClassificationCategory()
- getClassificationCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the classification category associated with this Product. A
      product has a single classification category which may or may not be in
      the site catalog. The classification category defines the attribute set
      of the product. See [getAttributeModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel) for
      how the classification category is used.


    **Returns:**
    - the associated classification Category, or null if none is
              associated.



---

### getEAN()
- getEAN(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the European Article Number of the product.

    **Returns:**
    - the European Article Number of the product.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product.

    **Returns:**
    - ID of the product.


---

### getImage()
- ~~getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)~~
  - : Returns the product's image.

    **Returns:**
    - the product's image.

    **Deprecated:**
**warning:** Commerce Cloud Digital introduces a new more powerful product
image management. It allows to group product images by self-defined view types
(e.g. 'large', 'thumbnail', 'swatch') and variation values (e.g. for attribute
color 'red', 'blue'). Images can be annotated with pattern based title and
alt. Product images can be accessed from Digital locations or external storage
locations.


Please use the new product image management. Therefore you have to set
up the common product image settings like view types, image location,
default image alt and title for your catalogs first. After that you can
group your product images by the previously defined view types in context
of a product. Finally use [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and
[getImage(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring-number) to access your images.

---

### getImage(String)
- getImage(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and returns the first image.
      If no image is available the method returns null.
      
      When called for a variant with defined images for specified view type the
      method returns the first image.
      
      When called for a variant without defined images for specified view type
      the method returns the first master product image. If no master product
      images are defined, the method returns null.


    **Parameters:**
    - viewtype - the view type annotated to image

    **Returns:**
    - the MediaFile or null

    **Throws:**
    - NullArgumentException - if viewtype is null


---

### getImage(String, Number)
- getImage(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and returns the image at
      the specific index. If no image for specified index is available the
      method returns null.


    **Parameters:**
    - viewtype - the view type annotated to image
    - index - the index number of the image within image list

    **Returns:**
    - the MediaFile or null

    **Throws:**
    - NullArgumentException - if viewtype is null


---

### getImages(String)
- getImages(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns all images assigned to this product for a specific view type,
      e.g. all 'thumbnail' images. The images are returned in the order of
      their index number ascending.
      
      When called for a master the method returns the images specific to the
      master, which are typically the fall back images.


    **Parameters:**
    - viewtype - the view type annotated to images

    **Returns:**
    - a list of MediaFile objects, possibly empty

    **Throws:**
    - NullArgumentException - if viewtype is null


---

### getIncomingProductLinks()
- getIncomingProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns incoming ProductLinks, where the source product is a site product.

    **Returns:**
    - a collection of incoming ProductLinks, where the source product is
              a site product.



---

### getIncomingProductLinks(Number)
- getIncomingProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns incoming ProductLinks, where the source product is a site product
      of a specific type.


    **Parameters:**
    - type - the type of ProductLinks to fetch.

    **Returns:**
    - a collection of incoming ProductLinks, where the source product is
              a site product of a specific type.



---

### getLongDescription()
- getLongDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the product's long description in the current locale.

    **Returns:**
    - The product's long description in the current locale, or null if it
              wasn't found.



---

### getManufacturerName()
- getManufacturerName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the product manufacturer.

    **Returns:**
    - the name of the product manufacturer.


---

### getManufacturerSKU()
- getManufacturerSKU(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the manufacturer's stock keeping unit.

    **Returns:**
    - the value of the manufacturer's stock keeping unit.


---

### getMinOrderQuantity()
- getMinOrderQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the minimum order quantity for this product.

    **Returns:**
    - the minimum order quantity of the product.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the product in the current locale.

    **Returns:**
    - The name of the product for the current locale, or null if it
              wasn't found.



---

### getOnlineCategories()
- getOnlineCategories(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all currently online categories to which this
      product is assigned and which are also available through the current
      site. A category is currently online if its online flag equals true and
      the current site date is within the date range defined by the onlineFrom
      and onlineTo attributes.


    **Returns:**
    - Collection of currently online categories to which this product
              is assigned and which are also available through the current
              site.



---

### getOnlineFlag()
- getOnlineFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status flag of the product.

    **Returns:**
    - the online status flag of the product.


---

### getOnlineFrom()
- getOnlineFrom(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date from which the product is online or valid.

    **Returns:**
    - the date from which the product is online or valid.


---

### getOnlineTo()
- getOnlineTo(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date until which the product is online or valid.

    **Returns:**
    - the date until which the product is online or valid.


---

### getOptionModel()
- getOptionModel(): [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)
  - : Returns the product's option model. The option values selections are
      initialized with the values defined for the product, or the default values
      defined for the option.


    **Returns:**
    - the products option model.


---

### getOrderableRecommendations()
- getOrderableRecommendations(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a list of outgoing recommendations for this product. This method
      behaves similarly to [getRecommendations()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendations) but additionally filters out
      recommendations for which the target product is unorderable according to
      its product availability model.


    **Returns:**
    - the sorted collection of recommendations, never null but possibly
              empty.


    **See Also:**
    - [ProductAvailabilityModel.isOrderable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderable)


---

### getOrderableRecommendations(Number)
- getOrderableRecommendations(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a list of outgoing recommendations for this product. This method
      behaves similarly to [getRecommendations(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendationsnumber) but additionally
      filters out recommendations for which the target product is unorderable
      according to its product availability model.


    **Parameters:**
    - type - the recommendation type.

    **Returns:**
    - the sorted collection of recommendations, never null but possibly
              empty.


    **See Also:**
    - [ProductAvailabilityModel.isOrderable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderable)


---

### getPageDescription()
- getPageDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns product's page description in the default locale.

    **Returns:**
    - The product's page description in the default locale,
                   or null if it wasn't found.



---

### getPageKeywords()
- getPageKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product's page keywords in the default locale.

    **Returns:**
    - The product's page keywords in the default locale,
                   or null if it wasn't found.



---

### getPageMetaTag(String)
- getPageMetaTag(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)
  - : Returns the page meta tag for the specified id.
      
      
      The meta tag content is generated based on the product detail page meta tag context and rule. The rule is
      obtained from the current product context or inherited from variation groups, master product, the primary
      category, up to the root category.
      
      
      Null will be returned if the meta tag is undefined on the current instance, or if no rule can be found for the
      current context, or if the rule resolves to an empty string.


    **Parameters:**
    - id - the ID to get the page meta tag for

    **Returns:**
    - page meta tag containing content generated based on rules


---

### getPageMetaTags()
- getPageMetaTags(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the product detail page meta tag context and rules. The rules are
      obtained from the current product context or inherited from variation groups, master product, the primary
      category, up to the root category.


    **Returns:**
    - page meta tags defined for this instance, containing content generated based on rules


---

### getPageTitle()
- getPageTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product's page title in the default locale.

    **Returns:**
    - The product's page title in the default locale,
                   or null if it wasn't found.



---

### getPageURL()
- getPageURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product's page URL in the default locale.

    **Returns:**
    - The product's page URL in the default locale,
                   or null if it wasn't found.



---

### getPriceModel()
- getPriceModel(): [ProductPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md)
  - : Returns the price model, which can be used to retrieve a price
      for this product.


    **Returns:**
    - the price model, which can be used to retrieve a price
      for this product.



---

### getPriceModel(ProductOptionModel)
- getPriceModel(optionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)): [ProductPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md)
  - : Returns the price model based on the specified optionModel. The
      price model can be used to retrieve a price
      for this product. Prices are calculated based on the option values
      selected in the specified option model.


    **Parameters:**
    - optionModel - the option model to use when fetching the  price model.

    **Returns:**
    - the price model based on the specified optionModel.


---

### getPrimaryCategory()
- getPrimaryCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the primary category of the product within the current site catalog.

    **Returns:**
    - The product's primary category or null.


---

### getPrimaryCategoryAssignment()
- getPrimaryCategoryAssignment(): [CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md)
  - : Returns the category assignment to the primary category in the current site
      catalog or null if no primary category is defined within the current site
      catalog.


    **Returns:**
    - The category assignment to the primary category or null.


---

### getProductLinks()
- getProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all outgoing ProductLinks, where the target product is also
      available in the current site. The ProductLinks are unsorted.


    **Returns:**
    - a collection of outgoing ProductLinks where the target product is also
      available in the current site.



---

### getProductLinks(Number)
- getProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all outgoing ProductLinks of a specific type, where the target
      product is also available in the current site. The ProductLinks are
      sorted.


    **Parameters:**
    - type - the type of ProductLinks to fetch.

    **Returns:**
    - a collection of outgoing ProductLinks where the target product is also
      available in the current site.



---

### getProductSetProducts()
- getProductSetProducts(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all products which are assigned to this product
      and which are also available through the current site.  If this product
      does not represent a product set then an empty collection will be
      returned.


    **Returns:**
    - Collection of products which are assigned to this product
      and which are also available through the current site.



---

### getProductSets()
- getProductSets(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all product sets in which this product is included.
      The method only returns product sets assigned to the current site.


    **Returns:**
    - Collection of product sets in which this product is included, possibly empty.


---

### getRecommendations()
- getRecommendations(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the outgoing recommendations for this product which
      belong to the site catalog.  If this product is not assigned to the site
      catalog, or there is no site catalog, an empty collection is returned.
      Only recommendations for which the target product exists and is assigned
      to the site catalog are returned.  The recommendations are sorted by
      their explicitly set order.


    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getRecommendations(Number)
- getRecommendations(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the outgoing recommendations for this product which are of the
      specified type and which belong to the site catalog.  Behaves the same as
      [getRecommendations()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendations) but additionally filters by recommendation
      type.


    **Parameters:**
    - type - the recommendation type.

    **Returns:**
    - the sorted collection of recommendations, never null but possibly empty.


---

### getSearchPlacement()
- getSearchPlacement(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the product's search placement classification. The higher the
      numeric product placement value, the more relevant is the product when
      sorting search results. The range of numeric placement values is
      defined in the meta data of object type 'Product' and can therefore be
      customized.


    **Returns:**
    - The product's search placement classification.


---

### getSearchRank()
- getSearchRank(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the product's search rank. The higher the numeric product rank,
      the more relevant is the product when sorting search results. The range of
      numeric rank values is defined in the meta data of object type 'Product'
      and can therefore be customized.


    **Returns:**
    - The product's search rank.


---

### getSearchableFlag()
- getSearchableFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns, whether the product is currently searchable.

    **Returns:**
    - the searchable status flag of the product.


---

### getSearchableIfUnavailableFlag()
- getSearchableIfUnavailableFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the searchable status of the [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) if unavailable.
      
      Besides `true` or `false`, the return value `null` indicates that the value is not set.


    **Returns:**
    - The searchable status of the product if unavailable or `null` if not set.


---

### getShortDescription()
- getShortDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the product's short description in the current locale.

    **Returns:**
    - the product's short description in the current locale, or null if it
              wasn't found.



---

### getSiteMapChangeFrequency()
- getSiteMapChangeFrequency(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product's change frequency needed for the sitemap creation.

    **Returns:**
    - The product's sitemap change frequency.


---

### getSiteMapIncluded()
- getSiteMapIncluded(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status if the product is included into the sitemap.

    **Returns:**
    - the value of the attribute 'siteMapIncluded'.


---

### getSiteMapPriority()
- getSiteMapPriority(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the product's priority needed for the sitemap creation.

    **Returns:**
    - The product's sitemap priority.


---

### getStepQuantity()
- getStepQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the steps in which the order amount of the product can be
      increased.


    **Returns:**
    - the order amount by which the product can be increased.


---

### getStoreReceiptName()
- getStoreReceiptName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the store receipt name of the product in the current locale.

    **Returns:**
    - The store receipt name of the product for the current locale, or null if it
              wasn't found.



---

### getStoreTaxClass()
- getStoreTaxClass(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the store tax class ID.
      
      This is an optional override for in-store tax calculation.


    **Returns:**
    - the store tax class id.


---

### getTaxClassID()
- getTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product's tax class, by resolving
      the Global Preference setting selected. If the Localized
      Tax Class setting under Global Preferences -> Products is
      selected, the localizedTaxClassID attribute value will be
      returned, else the legacy taxClassID attribute value will
      be returned.


    **Returns:**
    - the ID of the product's tax class depending on the Global Preference setting selected for Products.


---

### getTemplate()
- getTemplate(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the product's rendering template.

    **Returns:**
    - the name of the product's rendering template.


---

### getThumbnail()
- ~~getThumbnail(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)~~
  - : Returns the product's thumbnail image.

    **Returns:**
    - the product's thumbnail image.

    **Deprecated:**
**warning:** Commerce Cloud Digital introduces a new more powerful product
image management. It allows to group product images by self-defined view types
(e.g. 'large', 'thumbnail', 'swatch') and variation values (e.g. for attribute
color 'red', 'blue'). Images can be annotated with pattern based title and
alt. Product images can be accessed from Digital locations or external storage
locations.


Please use the new product image management. Therefore you have to set
up the common product image settings like view types, image location,
default image alt and title for your catalogs first. After that you can
group your product images by the previously defined view types in context
of a product. Finally use [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring) and
[getImage(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring-number) to access your images.

---

### getUPC()
- getUPC(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Universal Product Code of the product.

    **Returns:**
    - the Universal Product Code of the product.


---

### getUnit()
- getUnit(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product's sales unit.

    **Returns:**
    - the products sales unit.


---

### getUnitQuantity()
- getUnitQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the product's unit quantity.

    **Returns:**
    - the products unit quantity.


---

### getVariants()
- getVariants(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all variants assigned to this variation master
      or variation group product. All variants are returned regardless of whether
      they are online or offline.
      
      If this product does not represent a variation master or variation group
      product then an empty collection is returned.


    **Returns:**
    - Collection of variants associated with this variation master or
              variation group product.



---

### getVariationGroups()
- getVariationGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all variation groups assigned to this variation
      master product. All variation groups are returned regardless of whether
      they are online or offline.
      
      If this product does not represent a variation master product then an
      empty collection is returned.


    **Returns:**
    - Collection of variation groups associated with this variation
      master product.



---

### getVariationModel()
- getVariationModel(): [ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md)
  - : Returns the variation model of this product. If this product is a master
      product, then the returned model will encapsulate all the information
      about its variation attributes and variants. If this product is a variant
      product, then the returned model will encapsulate all the same
      information, but additionally pre-select all the variation attribute
      values of this variant. (See [ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md) for
      details on what "selected" means.) If this product is neither a master
      product or a variation product, then a model will be returned but will be
      essentially empty and not useful for any particular purpose.


    **Returns:**
    - the variation model of the product.


---

### includedInBundle(Product)
- includedInBundle(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the specified product participates in this product bundle.
      If this product does not represent a bundle at all, then false will
      always be returned.


    **Parameters:**
    - product - the product to check for participation.

    **Returns:**
    - true if the product participates in the bundle, false otherwise.


---

### isAssignedToCategory(Category)
- isAssignedToCategory(category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if item is assigned to the specified
      category.


    **Parameters:**
    - category - the category to check.

    **Returns:**
    - true if item is assigned to category.


---

### isAssignedToSiteCatalog()
- isAssignedToSiteCatalog(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the product is assigned to the current site (via the site catalog), otherwise
      `false` is returned.
      
      
      In case of the product being a variant, the variant will be considered as assigned if its master, one of the
      variation groups it is in or itself is assigned to the site catalog. In case this is triggered for a variation
      group the variation group is considered as assigned if its master or itself is assigned.


    **Returns:**
    - 'true' if product assigned to the site catalog


---

### isAvailable()
- ~~isAvailable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Identifies if the product is available.

    **Returns:**
    - the value of the attribute 'available'.

    **Deprecated:**
**warning:** Use [getAvailabilityModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel).isInStock() instead

---

### isBundle()
- isBundle(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this product instance is a product bundle.

    **Returns:**
    - true if the product is a bundle, false otherwise.


---

### isBundled()
- isBundled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this product instance is bundled within at least one
      product bundle.


    **Returns:**
    - true if the product is bundled, false otherwise.


---

### isCategorized()
- isCategorized(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this product is bound to at least one catalog category.

    **Returns:**
    - true if the product is bound to at least one catalog category,
              false otherwise.



---

### isFacebookEnabled()
- isFacebookEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the product is Facebook enabled.

    **Returns:**
    - the value of the attribute 'facebookEnabled'.


---

### isMaster()
- isMaster(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this product instance is a product master.

    **Returns:**
    - true if the product is a master, false otherwise.


---

### isOnline()
- isOnline(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the online status of the product. The online status
      is calculated from the online status flag and the onlineFrom
      onlineTo dates defined for the product.


    **Returns:**
    - the online status of the product.


---

### isOptionProduct()
- isOptionProduct(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the product has options.

    **Returns:**
    - true if product has options, false otherwise.


---

### isPinterestEnabled()
- isPinterestEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the product is Pinterest enabled.

    **Returns:**
    - the value of the attribute 'pinterestEnabled'.


---

### isProduct()
- isProduct(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the instance represents a product. Returns 'false' if
      the instance represents a product set.


    **Returns:**
    - true if the instance is a product, false otherwise.

    **See Also:**
    - [isProductSet()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductset)


---

### isProductSet()
- isProductSet(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the instance represents a product set, otherwise 'false'.

    **Returns:**
    - true if the instance is a product set, false otherwise.

    **See Also:**
    - [isProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproduct)


---

### isProductSetProduct()
- isProductSetProduct(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this product is part of any product set, otherwise false.

    **Returns:**
    - true if the product is part of any product set, false otherwise.


---

### isRetailSet()
- ~~isRetailSet(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Identifies if this product instance is part of a retail set.

    **Returns:**
    - true if the product is part of a retail set, false otherwise.

    **Deprecated:**
**warning:** Use [isProductSet()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductset) instead

---

### isSearchable()
- isSearchable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the product is searchable.

    **Returns:**
    - the value of the attribute 'searchable'.


---

### isSiteProduct()
- ~~isSiteProduct(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Returns 'true' if the product is assigned to the current site (via the
      site catalog), otherwise 'false' is returned.


    **Returns:**
    - 'true' if product assigned to site.

    **Deprecated:**
**warning:** Use [isAssignedToSiteCatalog()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtositecatalog) instead

---

### isVariant()
- isVariant(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this product instance is mastered by a product master.

    **Returns:**
    - true if the product is mastered, false otherwise.


---

### isVariationGroup()
- isVariationGroup(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this product instance is a variation group product.

    **Returns:**
    - true if the product is a variation group, false otherwise.


---

### setAvailableFlag(Boolean)
- ~~setAvailableFlag(available: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void~~
  - : Set the availability status flag of the product.

    **Parameters:**
    - available - Availability status flag.

    **Deprecated:**
**warning:** Don't use this method anymore.

---

### setOnlineFlag(Boolean) - Variant 1
- setOnlineFlag(online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set the online status flag of the product.

    **Parameters:**
    - online - Online status flag.

    **API Version:**
**note:** No longer available as of version 10.6.

---

### setOnlineFlag(Boolean) - Variant 2
- setOnlineFlag(online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set the online status flag of the product for the current site. If current site is not available (i.e.
      in case this method is called by a job that runs on organization level) the online status flag is set global,
      which can affect all sites.
      
      In previous versions this method set the online status flag global, instead of site specific.


    **Parameters:**
    - online - Online status flag.

    **API Version:**
**note:** Available from version 10.6.
In prior versions this method set the online status flag global, instead of site specific.

---

### setSearchPlacement(Number) - Variant 1
- setSearchPlacement(placement: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the product's search placement.

    **Parameters:**
    - placement - The product's search placement classification.

    **API Version:**
**note:** No longer available as of version 10.6.

---

### setSearchPlacement(Number) - Variant 2
- setSearchPlacement(placement: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the product's search placement classification in context of the current site. If current site is not
      available (i.e. in case this method is called by a job that runs on organization level) the search placement is
      set global, which can affect all sites.
      
      In previous versions this method set the search placement classification global, instead of site specific.


    **Parameters:**
    - placement - The product's search placement classification.

    **API Version:**
**note:** Available from version 10.6.
In prior versions this method set the search placement classification global, instead of site specific.

---

### setSearchRank(Number) - Variant 1
- setSearchRank(rank: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the product's search rank.

    **Parameters:**
    - rank - The product's search rank.

    **API Version:**
**note:** No longer available as of version 10.6.

---

### setSearchRank(Number) - Variant 2
- setSearchRank(rank: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the product's search rank in context of the current site. If current site is not available (i.e. in case this
      method is called by a job that runs on organization level) the search rank is set global, which can affect all
      sites.
      
      In previous versions this method set the search rank global, instead of site specific.


    **Parameters:**
    - rank - The product's search rank.

    **API Version:**
**note:** Available from version 10.6.
In prior versions this method set the search rank global, instead of site specific.

---

### setSearchableFlag(Boolean) - Variant 1
- setSearchableFlag(searchable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set the flag indicating whether the product is searchable or not.

    **Parameters:**
    - searchable - The value of the attribute 'searchable'.

    **API Version:**
**note:** No longer available as of version 10.6.

---

### setSearchableFlag(Boolean) - Variant 2
- setSearchableFlag(searchable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set the flag indicating whether the product is searchable or not in context of the current site. If current site
      is not available (i.e. in case this method is called by a job that runs on organization level) the searchable
      flag is set global, which can affect all sites.
      
      In previous versions this method set the searchable flag global, instead of site specific.


    **Parameters:**
    - searchable - The value of the attribute 'searchable'.

    **API Version:**
**note:** Available from version 10.6.
In prior versions this method set the searchable flag global, instead of site specific.

---

<!-- prettier-ignore-end -->

<!-- document id=fd8a9a713ab6bca146321f39b80f5cc048f6ae418c1f16a4cce857026ad7e0f9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductActiveData.md -->

<!-- prettier-ignore-start -->
# Class ProductActiveData

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.object.ActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md)
        - [dw.catalog.ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md)

Represents the active data for a [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) in Commerce Cloud Digital.


## Property Summary

| Property | Description |
| --- | --- |
| [availableDate](#availabledate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date the product became available on the site, or  `null` if none has been set. |
| [avgGrossMarginPercentDay](#avggrossmarginpercentday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin percentage of the product,  over the most recent day for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgGrossMarginPercentMonth](#avggrossmarginpercentmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin percentage of the product,  over the most recent 30 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgGrossMarginPercentWeek](#avggrossmarginpercentweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin percentage of the product,  over the most recent 7 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgGrossMarginPercentYear](#avggrossmarginpercentyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin percentage of the product,  over the most recent 365 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgGrossMarginValueDay](#avggrossmarginvalueday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin value of the product,  over the most recent day for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgGrossMarginValueMonth](#avggrossmarginvaluemonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin value of the product,  over the most recent 30 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgGrossMarginValueWeek](#avggrossmarginvalueweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin value of the product,  over the most recent 7 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgGrossMarginValueYear](#avggrossmarginvalueyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average gross margin value of the product,  over the most recent 365 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [avgSalesPriceDay](#avgsalespriceday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average sales price for the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [avgSalesPriceMonth](#avgsalespricemonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average sales price for the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [avgSalesPriceWeek](#avgsalespriceweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average sales price for the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [avgSalesPriceYear](#avgsalespriceyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the average sales price for the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [conversionDay](#conversionday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the conversion rate of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [conversionMonth](#conversionmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the conversion rate of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [conversionWeek](#conversionweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the conversion rate of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [conversionYear](#conversionyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the conversion rate of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [costPrice](#costprice): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the cost price for the product for the site,  or `null` if none has been set or the value is no longer valid. |
| [daysAvailable](#daysavailable): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of days the product has been available on the site. |
| [impressionsDay](#impressionsday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the impressions of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [impressionsMonth](#impressionsmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the impressions of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [impressionsWeek](#impressionsweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the impressions of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [impressionsYear](#impressionsyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the impressions of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [lookToBookRatioDay](#looktobookratioday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the look to book ratio of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [lookToBookRatioMonth](#looktobookratiomonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the look to book ratio of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [lookToBookRatioWeek](#looktobookratioweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the look to book ratio of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [lookToBookRatioYear](#looktobookratioyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the look to book ratio of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [ordersDay](#ordersday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of orders containing the product, over the most  recent day for the site, or `null` if none has been set  or the value is no longer valid. |
| [ordersMonth](#ordersmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of orders containing the product, over the most  recent 30 days for the site, or `null` if none has been set  or the value is no longer valid. |
| [ordersWeek](#ordersweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of orders containing the product, over the most  recent 7 days for the site, or `null` if none has been set  or the value is no longer valid. |
| [ordersYear](#ordersyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of orders containing the product, over the most  recent 365 days for the site, or `null` if none has been set  or the value is no longer valid. |
| [returnRate](#returnrate): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the return rate for the product for the site,  or `null` if none has been set or the value is no longer valid. |
| [revenueDay](#revenueday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the revenue of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [revenueMonth](#revenuemonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the revenue of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [revenueWeek](#revenueweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the revenue of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [revenueYear](#revenueyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the revenue of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [salesVelocityDay](#salesvelocityday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the sales velocity of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [salesVelocityMonth](#salesvelocitymonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the sales velocity of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [salesVelocityWeek](#salesvelocityweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the sales velocity of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [salesVelocityYear](#salesvelocityyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the sales velocity of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [unitsDay](#unitsday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the units of the product ordered over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [unitsMonth](#unitsmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the units of the product ordered over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [unitsWeek](#unitsweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the units of the product ordered over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [unitsYear](#unitsyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the units of the product ordered over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [viewsDay](#viewsday): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the views of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [viewsMonth](#viewsmonth): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the views of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [viewsWeek](#viewsweek): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the views of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [viewsYear](#viewsyear): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the views of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAvailableDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavailabledate)() | Returns the date the product became available on the site, or  `null` if none has been set. |
| [getAvgGrossMarginPercentDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginpercentday)() | Returns the average gross margin percentage of the product,  over the most recent day for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgGrossMarginPercentMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginpercentmonth)() | Returns the average gross margin percentage of the product,  over the most recent 30 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgGrossMarginPercentWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginpercentweek)() | Returns the average gross margin percentage of the product,  over the most recent 7 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgGrossMarginPercentYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginpercentyear)() | Returns the average gross margin percentage of the product,  over the most recent 365 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgGrossMarginValueDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginvalueday)() | Returns the average gross margin value of the product,  over the most recent day for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgGrossMarginValueMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginvaluemonth)() | Returns the average gross margin value of the product,  over the most recent 30 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgGrossMarginValueWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginvalueweek)() | Returns the average gross margin value of the product,  over the most recent 7 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgGrossMarginValueYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavggrossmarginvalueyear)() | Returns the average gross margin value of the product,  over the most recent 365 days for the site, or `null`  if none has been set or the value is no longer valid. |
| [getAvgSalesPriceDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavgsalespriceday)() | Returns the average sales price for the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getAvgSalesPriceMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavgsalespricemonth)() | Returns the average sales price for the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getAvgSalesPriceWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavgsalespriceweek)() | Returns the average sales price for the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getAvgSalesPriceYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavgsalespriceyear)() | Returns the average sales price for the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getConversionDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getconversionday)() | Returns the conversion rate of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getConversionMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getconversionmonth)() | Returns the conversion rate of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getConversionWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getconversionweek)() | Returns the conversion rate of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getConversionYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getconversionyear)() | Returns the conversion rate of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getCostPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getcostprice)() | Returns the cost price for the product for the site,  or `null` if none has been set or the value is no longer valid. |
| [getDaysAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getdaysavailable)() | Returns the number of days the product has been available on the site. |
| [getImpressionsDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getimpressionsday)() | Returns the impressions of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getImpressionsMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getimpressionsmonth)() | Returns the impressions of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getImpressionsWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getimpressionsweek)() | Returns the impressions of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getImpressionsYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getimpressionsyear)() | Returns the impressions of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getLookToBookRatioDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getlooktobookratioday)() | Returns the look to book ratio of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getLookToBookRatioMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getlooktobookratiomonth)() | Returns the look to book ratio of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getLookToBookRatioWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getlooktobookratioweek)() | Returns the look to book ratio of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getLookToBookRatioYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getlooktobookratioyear)() | Returns the look to book ratio of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getOrdersDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getordersday)() | Returns the number of orders containing the product, over the most  recent day for the site, or `null` if none has been set  or the value is no longer valid. |
| [getOrdersMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getordersmonth)() | Returns the number of orders containing the product, over the most  recent 30 days for the site, or `null` if none has been set  or the value is no longer valid. |
| [getOrdersWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getordersweek)() | Returns the number of orders containing the product, over the most  recent 7 days for the site, or `null` if none has been set  or the value is no longer valid. |
| [getOrdersYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getordersyear)() | Returns the number of orders containing the product, over the most  recent 365 days for the site, or `null` if none has been set  or the value is no longer valid. |
| [getReturnRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getreturnrate)() | Returns the return rate for the product for the site,  or `null` if none has been set or the value is no longer valid. |
| [getRevenueDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getrevenueday)() | Returns the revenue of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getRevenueMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getrevenuemonth)() | Returns the revenue of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getRevenueWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getrevenueweek)() | Returns the revenue of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getRevenueYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getrevenueyear)() | Returns the revenue of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getSalesVelocityDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getsalesvelocityday)() | Returns the sales velocity of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getSalesVelocityMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getsalesvelocitymonth)() | Returns the sales velocity of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getSalesVelocityWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getsalesvelocityweek)() | Returns the sales velocity of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getSalesVelocityYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getsalesvelocityyear)() | Returns the sales velocity of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getUnitsDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getunitsday)() | Returns the units of the product ordered over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getUnitsMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getunitsmonth)() | Returns the units of the product ordered over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getUnitsWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getunitsweek)() | Returns the units of the product ordered over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getUnitsYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getunitsyear)() | Returns the units of the product ordered over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getViewsDay](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getviewsday)() | Returns the views of the product, over the most recent day  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getViewsMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getviewsmonth)() | Returns the views of the product, over the most recent 30 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getViewsWeek](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getviewsweek)() | Returns the views of the product, over the most recent 7 days  for the site, or `null` if none has been set or the value  is no longer valid. |
| [getViewsYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getviewsyear)() | Returns the views of the product, over the most recent 365 days  for the site, or `null` if none has been set or the value  is no longer valid. |

### Methods inherited from class ActiveData

[getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md#getcustom), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md#isempty)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### availableDate
- availableDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date the product became available on the site, or
      `null` if none has been set.



---

### avgGrossMarginPercentDay
- avgGrossMarginPercentDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin percentage of the product,
      over the most recent day for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgGrossMarginPercentMonth
- avgGrossMarginPercentMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin percentage of the product,
      over the most recent 30 days for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgGrossMarginPercentWeek
- avgGrossMarginPercentWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin percentage of the product,
      over the most recent 7 days for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgGrossMarginPercentYear
- avgGrossMarginPercentYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin percentage of the product,
      over the most recent 365 days for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgGrossMarginValueDay
- avgGrossMarginValueDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin value of the product,
      over the most recent day for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgGrossMarginValueMonth
- avgGrossMarginValueMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin value of the product,
      over the most recent 30 days for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgGrossMarginValueWeek
- avgGrossMarginValueWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin value of the product,
      over the most recent 7 days for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgGrossMarginValueYear
- avgGrossMarginValueYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average gross margin value of the product,
      over the most recent 365 days for the site, or `null`
      if none has been set or the value is no longer valid.



---

### avgSalesPriceDay
- avgSalesPriceDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average sales price for the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### avgSalesPriceMonth
- avgSalesPriceMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average sales price for the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### avgSalesPriceWeek
- avgSalesPriceWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average sales price for the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### avgSalesPriceYear
- avgSalesPriceYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the average sales price for the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### conversionDay
- conversionDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the conversion rate of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### conversionMonth
- conversionMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the conversion rate of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### conversionWeek
- conversionWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the conversion rate of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### conversionYear
- conversionYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the conversion rate of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### costPrice
- costPrice: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the cost price for the product for the site,
      or `null` if none has been set or the value is no longer valid.



---

### daysAvailable
- daysAvailable: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of days the product has been available on the site.
      The number is calculated based on the current date and the date the
      product became available on the site, or if that date has not been set,
      the date the product was created in the system.


    **See Also:**
    - [getAvailableDate()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavailabledate)


---

### impressionsDay
- impressionsDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the impressions of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### impressionsMonth
- impressionsMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the impressions of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### impressionsWeek
- impressionsWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the impressions of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### impressionsYear
- impressionsYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the impressions of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### lookToBookRatioDay
- lookToBookRatioDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the look to book ratio of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### lookToBookRatioMonth
- lookToBookRatioMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the look to book ratio of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### lookToBookRatioWeek
- lookToBookRatioWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the look to book ratio of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### lookToBookRatioYear
- lookToBookRatioYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the look to book ratio of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### ordersDay
- ordersDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of orders containing the product, over the most
      recent day for the site, or `null` if none has been set
      or the value is no longer valid.



---

### ordersMonth
- ordersMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of orders containing the product, over the most
      recent 30 days for the site, or `null` if none has been set
      or the value is no longer valid.



---

### ordersWeek
- ordersWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of orders containing the product, over the most
      recent 7 days for the site, or `null` if none has been set
      or the value is no longer valid.



---

### ordersYear
- ordersYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of orders containing the product, over the most
      recent 365 days for the site, or `null` if none has been set
      or the value is no longer valid.



---

### returnRate
- returnRate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the return rate for the product for the site,
      or `null` if none has been set or the value is no longer valid.



---

### revenueDay
- revenueDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the revenue of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### revenueMonth
- revenueMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the revenue of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### revenueWeek
- revenueWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the revenue of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### revenueYear
- revenueYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the revenue of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### salesVelocityDay
- salesVelocityDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the sales velocity of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### salesVelocityMonth
- salesVelocityMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the sales velocity of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### salesVelocityWeek
- salesVelocityWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the sales velocity of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### salesVelocityYear
- salesVelocityYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the sales velocity of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### unitsDay
- unitsDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the units of the product ordered over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### unitsMonth
- unitsMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the units of the product ordered over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### unitsWeek
- unitsWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the units of the product ordered over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### unitsYear
- unitsYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the units of the product ordered over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### viewsDay
- viewsDay: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the views of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### viewsMonth
- viewsMonth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the views of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### viewsWeek
- viewsWeek: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the views of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

### viewsYear
- viewsYear: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the views of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.



---

## Method Details

### getAvailableDate()
- getAvailableDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date the product became available on the site, or
      `null` if none has been set.


    **Returns:**
    - the date the product became available.


---

### getAvgGrossMarginPercentDay()
- getAvgGrossMarginPercentDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin percentage of the product,
      over the most recent day for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin percentage over the last day.


---

### getAvgGrossMarginPercentMonth()
- getAvgGrossMarginPercentMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin percentage of the product,
      over the most recent 30 days for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin percentage over the last 30 days.


---

### getAvgGrossMarginPercentWeek()
- getAvgGrossMarginPercentWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin percentage of the product,
      over the most recent 7 days for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin percentage over the last 7 days.


---

### getAvgGrossMarginPercentYear()
- getAvgGrossMarginPercentYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin percentage of the product,
      over the most recent 365 days for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin percentage over the last 365 days.


---

### getAvgGrossMarginValueDay()
- getAvgGrossMarginValueDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin value of the product,
      over the most recent day for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin value over the last day.


---

### getAvgGrossMarginValueMonth()
- getAvgGrossMarginValueMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin value of the product,
      over the most recent 30 days for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin value over the last 30 days.


---

### getAvgGrossMarginValueWeek()
- getAvgGrossMarginValueWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin value of the product,
      over the most recent 7 days for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin value over the last 7 days.


---

### getAvgGrossMarginValueYear()
- getAvgGrossMarginValueYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average gross margin value of the product,
      over the most recent 365 days for the site, or `null`
      if none has been set or the value is no longer valid.


    **Returns:**
    - the average gross margin value over the last 365 days.


---

### getAvgSalesPriceDay()
- getAvgSalesPriceDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average sales price for the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the average sales price over the last day.


---

### getAvgSalesPriceMonth()
- getAvgSalesPriceMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average sales price for the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the average sales price over the last 30 days.


---

### getAvgSalesPriceWeek()
- getAvgSalesPriceWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average sales price for the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the average sales price over the last 7 days.


---

### getAvgSalesPriceYear()
- getAvgSalesPriceYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the average sales price for the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the average sales price over the last 365 days.


---

### getConversionDay()
- getConversionDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the conversion rate of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the conversion over the last day.


---

### getConversionMonth()
- getConversionMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the conversion rate of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the conversion over the last 30 days.


---

### getConversionWeek()
- getConversionWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the conversion rate of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the conversion over the last 7 days.


---

### getConversionYear()
- getConversionYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the conversion rate of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the conversion over the last 365 days.


---

### getCostPrice()
- getCostPrice(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the cost price for the product for the site,
      or `null` if none has been set or the value is no longer valid.


    **Returns:**
    - the cost price.


---

### getDaysAvailable()
- getDaysAvailable(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of days the product has been available on the site.
      The number is calculated based on the current date and the date the
      product became available on the site, or if that date has not been set,
      the date the product was created in the system.


    **Returns:**
    - the age in days.

    **See Also:**
    - [getAvailableDate()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md#getavailabledate)


---

### getImpressionsDay()
- getImpressionsDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the impressions of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the impressions over the last day.


---

### getImpressionsMonth()
- getImpressionsMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the impressions of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the impressions over the last 30 days.


---

### getImpressionsWeek()
- getImpressionsWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the impressions of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the impressions over the last 7 days.


---

### getImpressionsYear()
- getImpressionsYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the impressions of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the impressions over the last 365 days.


---

### getLookToBookRatioDay()
- getLookToBookRatioDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the look to book ratio of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the look to book ratio over the last day.


---

### getLookToBookRatioMonth()
- getLookToBookRatioMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the look to book ratio of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the look to book ratio over the last 30 days.


---

### getLookToBookRatioWeek()
- getLookToBookRatioWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the look to book ratio of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the look to book ratio over the last 7 days.


---

### getLookToBookRatioYear()
- getLookToBookRatioYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the look to book ratio of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the look to book ratio over the last 365 days.


---

### getOrdersDay()
- getOrdersDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of orders containing the product, over the most
      recent day for the site, or `null` if none has been set
      or the value is no longer valid.


    **Returns:**
    - the orders over the last day.


---

### getOrdersMonth()
- getOrdersMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of orders containing the product, over the most
      recent 30 days for the site, or `null` if none has been set
      or the value is no longer valid.


    **Returns:**
    - the orders over the last 30 days.


---

### getOrdersWeek()
- getOrdersWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of orders containing the product, over the most
      recent 7 days for the site, or `null` if none has been set
      or the value is no longer valid.


    **Returns:**
    - the orders over the last 7 days.


---

### getOrdersYear()
- getOrdersYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of orders containing the product, over the most
      recent 365 days for the site, or `null` if none has been set
      or the value is no longer valid.


    **Returns:**
    - the orders over the last 365 days.


---

### getReturnRate()
- getReturnRate(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the return rate for the product for the site,
      or `null` if none has been set or the value is no longer valid.


    **Returns:**
    - the return rate.


---

### getRevenueDay()
- getRevenueDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the revenue of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the revenue over the last day.


---

### getRevenueMonth()
- getRevenueMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the revenue of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the revenue over the last 30 days.


---

### getRevenueWeek()
- getRevenueWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the revenue of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the revenue over the last 7 days.


---

### getRevenueYear()
- getRevenueYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the revenue of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the revenue over the last 365 days.


---

### getSalesVelocityDay()
- getSalesVelocityDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the sales velocity of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the sales velocity over the last day.


---

### getSalesVelocityMonth()
- getSalesVelocityMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the sales velocity of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the sales velocity over the last 30 days.


---

### getSalesVelocityWeek()
- getSalesVelocityWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the sales velocity of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the sales velocity over the last 7 days.


---

### getSalesVelocityYear()
- getSalesVelocityYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the sales velocity of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the sales velocity over the last 365 days.


---

### getUnitsDay()
- getUnitsDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the units of the product ordered over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the units over the last day.


---

### getUnitsMonth()
- getUnitsMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the units of the product ordered over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the units over the last 30 days.


---

### getUnitsWeek()
- getUnitsWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the units of the product ordered over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the units over the last 7 days.


---

### getUnitsYear()
- getUnitsYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the units of the product ordered over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the units over the last 365 days.


---

### getViewsDay()
- getViewsDay(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the views of the product, over the most recent day
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the views over the last day.


---

### getViewsMonth()
- getViewsMonth(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the views of the product, over the most recent 30 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the views over the last 30 days.


---

### getViewsWeek()
- getViewsWeek(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the views of the product, over the most recent 7 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the views over the last 7 days.


---

### getViewsYear()
- getViewsYear(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the views of the product, over the most recent 365 days
      for the site, or `null` if none has been set or the value
      is no longer valid.


    **Returns:**
    - the views over the last 365 days.


---

<!-- prettier-ignore-end -->

<!-- document id=48cfaa907e2f218efbb50bf25f0a2bc5288ce17968e2342f5fa68cc1db3d3e89 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductAttributeModel.md -->

<!-- prettier-ignore-start -->
# Class ProductAttributeModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md)

Class representing the complete attribute model for products in the system.
An instance of this class provides methods to access the attribute
definitions and groups for the system object type 'Product' and perhaps
additional information depending on how the instance is obtained.
A ProductAttributeModel can be obtained in one of three ways:


- **[ProductAttributeModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#productattributemodel):**When the no-arg constructor is  used the model represents:     
  - the attribute groups of the system object type 'Product' (i.e. the       global product attribute groups) and their bound attributes

- **[Category.getProductAttributeModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md#getproductattributemodel):**When the  attribute model for a Category is retrieved, the model represents:     
  - the global product attribute groups
  - product attribute groups of the calling category
  - product attribute groups of any parent categories of the calling category

- **[Product.getAttributeModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel):**When the attribute  model for a Product is retrieved, the model represents:     
  - the global product attribute groups
  - product attribute groups of the product's classification category
  - product attribute groups of any parent categories of the product's classification category
In this case, the model additionally provides access to the attribute values
of the product.  If the product lacks a classification category, then only
the global product attribute group is considered by the model.


The ProductAttributeModel provides a generic way to display the attribute
values of a product on a product detail page organized into appropriate
visual groups.  This is typically done as follows:


- On the product detail page, call  [Product.getAttributeModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel)to get the attribute model for  the product.
- Call [getVisibleAttributeGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvisibleattributegroups)to get the groups that are  appropriate for this product and all other products assigned to the same  classification category.
- Iterate the groups, and display each as a "group" in the UI.
- Call [getVisibleAttributeDefinitions(ObjectAttributeGroup)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvisibleattributedefinitionsobjectattributegroup)for  each group. Iterate and display the attribute names using  [ObjectAttributeDefinition.getDisplayName()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getdisplayname).
- For each attribute, get the product's display value(s) for that  attribute, using `getDisplayValue()`. This might require custom  display logic based on the type of attribute (strings, dates, multi-value  attributes, etc).



## Property Summary

| Property | Description |
| --- | --- |
| [attributeGroups](#attributegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a sorted collection of attribute groups of this model. |
| [orderRequiredAttributeDefinitions](#orderrequiredattributedefinitions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns an unsorted collection of attribute definitions marked as  order-required. |
| [visibleAttributeGroups](#visibleattributegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a sorted collection of visible attribute groups of this model. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ProductAttributeModel](#productattributemodel)() | Constructs a product attribute model that is not based on a product nor  a category. |

## Method Summary

| Method | Description |
| --- | --- |
| [getAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getattributedefinitionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the attribute definition with the given id from the product attribute  model. |
| [getAttributeDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getattributedefinitionsobjectattributegroup)([ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)) | Returns a sorted collection of attribute definitions for the given attribute  group. |
| [getAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getattributegroupstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the attribute group with the given id from the product attribute  model. |
| [getAttributeGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getattributegroups)() | Returns a sorted collection of attribute groups of this model. |
| [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getdisplayvalueobjectattributedefinition---variant-1)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)) | Returns the value that the underlying product defines for the given  attribute definition in the current locale. |
| [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getdisplayvalueobjectattributedefinition---variant-2)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)) | Returns the value that the underlying product defines for the given  attribute definition in the current locale. |
| [getOrderRequiredAttributeDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getorderrequiredattributedefinitions)() | Returns an unsorted collection of attribute definitions marked as  order-required. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvalueobjectattributedefinition---variant-1)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)) | Returns the attribute value for the specified attribute  definition. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvalueobjectattributedefinition---variant-2)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)) | Returns the attribute value for the specified attribute definition. |
| [getVisibleAttributeDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvisibleattributedefinitionsobjectattributegroup)([ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)) | Returns a sorted collection of all visible attribute definitions for the  given attribute group. |
| [getVisibleAttributeGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvisibleattributegroups)() | Returns a sorted collection of visible attribute groups of this model. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### attributeGroups
- attributeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a sorted collection of attribute groups of this model. The groups
      returned depends on how this model is constructed and what it represents.
      (See class-level documentation for details).
      
      
      The collection of returned groups is sorted first by scope and secondly
      by explicit sort order. Global groups always appear before
      category-specific groups in the list. Groups of parent categories always
      appear before groups belonging to subcategories. At each scope, groups
      have an explicit sort order which can be managed within the Business
      Manager.
      
      
      When there are multiple attribute groups with the same ID, the following
      rules apply:
      
      
      - If this model represents the global product attribute group only  (e.g. the no-arg constructor was used), duplicates cannot occur since  only one group can be defined with a given ID at that scope.
      - If this model is associated with specific categories (e.g. it is  constructed from a product with a classification category), then a  category product attribute group might have the same ID as a global  product attribute group. In this case, the category group overrides the  global one.
      - If a category and one of its ancestor categories both define a  product attribute group with the same ID, the sub-category group  overrides the parent group.
      
      
      As a result of these rules, this method will never return two attribute
      groups with the same ID.



---

### orderRequiredAttributeDefinitions
- orderRequiredAttributeDefinitions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns an unsorted collection of attribute definitions marked as
      order-required. Order-required attributes are usually copied into order
      line items.
      
      
      The returned attribute definitions are sorted according to the explicit
      sort order defined for the attributes in the group. This is managed by
      merchant in the Business Manager.



---

### visibleAttributeGroups
- visibleAttributeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a sorted collection of visible attribute groups of this model.
      This method is similar to [getAttributeGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getattributegroups) but only includes
      attribute groups containing at least one attribute definition that is
      visible. See
      [getVisibleAttributeDefinitions(ObjectAttributeGroup)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvisibleattributedefinitionsobjectattributegroup).



---

## Constructor Details

### ProductAttributeModel()
- ProductAttributeModel()
  - : Constructs a product attribute model that is not based on a product nor
      a category. Therefore, the model only describes the product attributes
      globally defined for the system object type 'Product'.



---

## Method Details

### getAttributeDefinition(String)
- getAttributeDefinition(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)
  - : Returns the attribute definition with the given id from the product attribute
      model. If attribute definition does not exist, null is returned.


    **Parameters:**
    - id - the identifier of the attribute definition.

    **Returns:**
    - attribute definition or null if not exist


---

### getAttributeDefinitions(ObjectAttributeGroup)
- getAttributeDefinitions(group: [ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of attribute definitions for the given attribute
      group. If no attribute definition exist for the group, an empty collection
      is returned.
      
      
      The returned attribute definitions are sorted according to the explicit
      sort order defined for the attributes in the group.  This is managed
      by merchant in the Business Manager.


    **Parameters:**
    - group - the group whose attribute definitions are returned.

    **Returns:**
    - a sorted collection of ObjectAttributeDefinition instances.


---

### getAttributeGroup(String)
- getAttributeGroup(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)
  - : Returns the attribute group with the given id from the product attribute
      model. If attribute group does not exist, null is returned.


    **Parameters:**
    - id - the attribute group identifier.

    **Returns:**
    - the attribute group or null if not exist


---

### getAttributeGroups()
- getAttributeGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of attribute groups of this model. The groups
      returned depends on how this model is constructed and what it represents.
      (See class-level documentation for details).
      
      
      The collection of returned groups is sorted first by scope and secondly
      by explicit sort order. Global groups always appear before
      category-specific groups in the list. Groups of parent categories always
      appear before groups belonging to subcategories. At each scope, groups
      have an explicit sort order which can be managed within the Business
      Manager.
      
      
      When there are multiple attribute groups with the same ID, the following
      rules apply:
      
      
      - If this model represents the global product attribute group only  (e.g. the no-arg constructor was used), duplicates cannot occur since  only one group can be defined with a given ID at that scope.
      - If this model is associated with specific categories (e.g. it is  constructed from a product with a classification category), then a  category product attribute group might have the same ID as a global  product attribute group. In this case, the category group overrides the  global one.
      - If a category and one of its ancestor categories both define a  product attribute group with the same ID, the sub-category group  overrides the parent group.
      
      
      As a result of these rules, this method will never return two attribute
      groups with the same ID.


    **Returns:**
    - collection of all attribute groups.


---

### getDisplayValue(ObjectAttributeDefinition) - Variant 1
- getDisplayValue(definition: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value that the underlying product defines for the given
      attribute definition in the current locale. In case the attribute
      definition defines localized attribute values, the product's value is
      used as an id to find the localized display value.


    **Parameters:**
    - definition - the definition to use.

    **Returns:**
    - The localized product attribute display value.

    **API Version:**
**note:** No longer available as of version 10.6.

---

### getDisplayValue(ObjectAttributeDefinition) - Variant 2
- getDisplayValue(definition: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value that the underlying product defines for the given
      attribute definition in the current locale. In case the attribute definition
      defines localized attribute values, the product's value is used as an id
      to find the localized display value.
      
      In case of an Image attribute this method returns a MediaFile instance.
      In previous versions this method returned a String with the image path.
      In case of an HTML attribute this method returns a MarkupText instance.
      In previous versions this method returned a String with the HTML source.


    **Parameters:**
    - definition - the definition to use.

    **Returns:**
    - The localized product attribute display value.

    **API Version:**
**note:** Available from version 10.6.
In prior versions this method returned a String with the image path or a String with the HTML source

---

### getOrderRequiredAttributeDefinitions()
- getOrderRequiredAttributeDefinitions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an unsorted collection of attribute definitions marked as
      order-required. Order-required attributes are usually copied into order
      line items.
      
      
      The returned attribute definitions are sorted according to the explicit
      sort order defined for the attributes in the group. This is managed by
      merchant in the Business Manager.


    **Returns:**
    - a collection of order-required ObjectAttributeDefinition
              instances.



---

### getValue(ObjectAttributeDefinition) - Variant 1
- getValue(definition: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the attribute value for the specified attribute
      definition. If the product does not define a value, null is returned.
      
      
      Note: this method may only be used where the attribute model was created for
      a specific product; otherwise it will always return null.
      
      
      If the attribute is localized, the value for the current session locale
      is returned.


    **Parameters:**
    - definition - the attribute definition to use when locating  and returning the value.

    **Returns:**
    - value the value associated with the object attribute definition.

    **API Version:**
**note:** No longer available as of version 10.6.

---

### getValue(ObjectAttributeDefinition) - Variant 2
- getValue(definition: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the attribute value for the specified attribute definition. If
      the product does not define a value, null is returned.
      
      
      Note: this method may only be used where the attribute model was created
      for a specific product; otherwise it will always return null.
      
      
      If the attribute is localized, the value for the current session locale
      is returned.
      
      
      In case of an Image attribute this method returns a MediaFile instance.
      In previous versions this method returned a String with the image path.
      In case of an HTML attribute this method returns a MarkupText instance.
      In previous versions this method returned a String with the HTML source.


    **Parameters:**
    - definition - the attribute definition to use when locating and             returning the value.

    **Returns:**
    - value the value associated with the object attribute definition.

    **API Version:**
**note:** Available from version 10.6.
In prior versions this method returned a String with the image path or a String with the HTML source.

---

### getVisibleAttributeDefinitions(ObjectAttributeGroup)
- getVisibleAttributeDefinitions(group: [ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of all visible attribute definitions for the
      given attribute group. If no visible attribute definition exist for the
      group, an empty collection is returned.
      
      
      An attribute definition is considered visible if is marked as visible. If
      the product attribute model is created for a specific product, the
      product must also define a value for the attribute definition; else the
      attribute definition is considered as invisible.
      
      
      The returned attribute definitions are sorted according to the explicit
      sort order defined for the attributes in the group. This is managed by
      merchant in the Business Manager.


    **Parameters:**
    - group - the group whose visible attribute definitions are returned.

    **Returns:**
    - a sorted collection of visible ObjectAttributeDefinition
              instances.



---

### getVisibleAttributeGroups()
- getVisibleAttributeGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of visible attribute groups of this model.
      This method is similar to [getAttributeGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getattributegroups) but only includes
      attribute groups containing at least one attribute definition that is
      visible. See
      [getVisibleAttributeDefinitions(ObjectAttributeGroup)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md#getvisibleattributedefinitionsobjectattributegroup).


    **Returns:**
    - sorted collection of visible ObjectAttributeGroup instances.


---

<!-- prettier-ignore-end -->

<!-- document id=f439006c48990d1f061a579eb8a3a54bc54ce334dd7b781349bc4c0a4ba5c4c6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductAvailabilityLevels.md -->

<!-- prettier-ignore-start -->
# Class ProductAvailabilityLevels

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductAvailabilityLevels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md)

Encapsulates the quantity of items available for each availability status.


## Property Summary

| Property | Description |
| --- | --- |
| [backorder](#backorder): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the backorder quantity. |
| [count](#count): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of attributes that contain non-zero quantities. |
| [inStock](#instock): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity in stock. |
| [notAvailable](#notavailable): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity that is not available. |
| [preorder](#preorder): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the pre-order quantity. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBackorder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getbackorder)() | Returns the backorder quantity. |
| [getCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getcount)() | Returns the number of attributes that contain non-zero quantities. |
| [getInStock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getinstock)() | Returns the quantity in stock. |
| [getNotAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getnotavailable)() | Returns the quantity that is not available. |
| [getPreorder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getpreorder)() | Returns the pre-order quantity. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### backorder
- backorder: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the backorder quantity.


---

### count
- count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of attributes that contain non-zero quantities.


---

### inStock
- inStock: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity in stock.


---

### notAvailable
- notAvailable: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity that is not available.


---

### preorder
- preorder: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the pre-order quantity.


---

## Method Details

### getBackorder()
- getBackorder(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the backorder quantity.

    **Returns:**
    - the backorder quantity.


---

### getCount()
- getCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of attributes that contain non-zero quantities.

    **Returns:**
    - the number of attributes that contain non-zero quantities.


---

### getInStock()
- getInStock(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity in stock.

    **Returns:**
    - the quantity in stock.


---

### getNotAvailable()
- getNotAvailable(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity that is not available.

    **Returns:**
    - the quantity that is not available.


---

### getPreorder()
- getPreorder(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the pre-order quantity.

    **Returns:**
    - the pre-order quantity.


---

<!-- prettier-ignore-end -->

<!-- document id=6258046a3e8262908dcabd10d244277144c718bf8939bd9d90d6721eaf182251 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductAvailabilityModel.md -->

<!-- prettier-ignore-start -->
# Class ProductAvailabilityModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md)

The ProductAvailabilityModel provides methods for retrieving all information
on availability of a single product.



When using Omnichannel Inventory (OCI):

- OCI supports backorders, but does not support preorders or perpetual availability. OCI refers to expected  restocks as Future inventory.
- OCI uses an eventual consistency model with asynchronous inventory data updates. Your code must not assume that  inventory-affecting actions, such as placing orders, will immediately change inventory levels.



## Constant Summary

| Constant | Description |
| --- | --- |
| [AVAILABILITY_STATUS_BACKORDER](#availability_status_backorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BACKORDER" | Indicates that the product stock has run out, but will be replenished, and is therefore available for ordering. |
| [AVAILABILITY_STATUS_IN_STOCK](#availability_status_in_stock): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IN_STOCK" | Indicates that the product is in stock and available for ordering. |
| [AVAILABILITY_STATUS_NOT_AVAILABLE](#availability_status_not_available): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NOT_AVAILABLE" | Indicates that the product is not currently available for ordering. |
| [AVAILABILITY_STATUS_PREORDER](#availability_status_preorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PREORDER" | Indicates that the product is not yet in stock but is available for ordering. |

## Property Summary

| Property | Description |
| --- | --- |
| [SKUCoverage](#skucoverage): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the SKU coverage of the product. |
| [availability](#availability): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the availability of the product, which roughly defined is the  ratio of the original stock that is still available to sell. |
| [availabilityStatus](#availabilitystatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the availability-status for the minimum-orderable-quantity (MOQ) of  the product. |
| [inStock](#instock): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Convenience method for [isInStock(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isinstocknumber). |
| [inventoryRecord](#inventoryrecord): [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md) `(read-only)` | Returns the ProductInventoryRecord for the Product associated  with this model. |
| [orderable](#orderable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Convenience method for [isOrderable(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderablenumber). |
| [timeToOutOfStock](#timetooutofstock): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of hours before the product is expected to go out  of stock. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#getavailability)() | Returns the availability of the product, which roughly defined is the  ratio of the original stock that is still available to sell. |
| [getAvailabilityLevels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#getavailabilitylevelsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | <p>Returns an instance of [ProductAvailabilityLevels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md),  where each available quantity represents a part of the input quantity. |
| [getAvailabilityStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#getavailabilitystatus)() | Returns the availability-status for the minimum-orderable-quantity (MOQ) of  the product. |
| [getInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#getinventoryrecord)() | Returns the ProductInventoryRecord for the Product associated  with this model. |
| [getSKUCoverage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#getskucoverage)() | Returns the SKU coverage of the product. |
| [getTimeToOutOfStock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#gettimetooutofstock)() | Returns the number of hours before the product is expected to go out  of stock. |
| [isInStock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isinstock)() | Convenience method for [isInStock(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isinstocknumber). |
| [isInStock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isinstocknumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns true if the Product is in-stock in the given quantity. |
| [isOrderable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderable)() | Convenience method for [isOrderable(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderablenumber). |
| [isOrderable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderablenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns true if the Product is currently online (based on its online flag  and online dates) and the specified quantity does not exceed the quantity  available for sale, and returns false otherwise. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### AVAILABILITY_STATUS_BACKORDER

- AVAILABILITY_STATUS_BACKORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "BACKORDER"
  - : Indicates that the product stock has run out, but will be replenished, and is therefore available for ordering.


---

### AVAILABILITY_STATUS_IN_STOCK

- AVAILABILITY_STATUS_IN_STOCK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IN_STOCK"
  - : Indicates that the product is in stock and available for ordering.


---

### AVAILABILITY_STATUS_NOT_AVAILABLE

- AVAILABILITY_STATUS_NOT_AVAILABLE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NOT_AVAILABLE"
  - : Indicates that the product is not currently available for ordering.


---

### AVAILABILITY_STATUS_PREORDER

- AVAILABILITY_STATUS_PREORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PREORDER"
  - : Indicates that the product is not yet in stock but is available for ordering.


---

## Property Details

### SKUCoverage
- SKUCoverage: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the SKU coverage of the product.  The basic formula for a
      master product is the ratio of online variations that are in stock
      to the total number of online variations.  The following specific rules
      apply for standard products:
      
      - If the product is in stock this method returns the availability of the product.
      - If the product is out of stock this method returns 0.
      
      The following rules apply for special product types:
      
      - For a master product this method returns the average SKU coverage  of its online variations.
      - For a master product with no online variations this method returns 0.
      - For a product set this method returns the ratio of orderable SKUs in the product set  over the total number of online SKUs in the product set. 
      - For a product set with no online products this method returns 0.
      - For a product bundle this method returns 1 if all of the bundled  products are online, and 0 otherwise.
      - For a product bundle with no online bundled products this method  returns 0.



---

### availability
- availability: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the availability of the product, which roughly defined is the
      ratio of the original stock that is still available to sell.  The basic
      formula, if the current site uses an
      inventory list, is the ATS quantity divided by allocation
      amount. If the product is not orderable at all this method returns 0.
      The following specific rules apply for standard products:
      
      - If inventory lists are in use:      
        - If no inventory record exists and the inventory list default-in-stock flag is true this method returns 1.
        - If no inventory record exists the inventory list default-in-stock flag is false this method returns 0.
        - If the product is not available this method returns 0.
        - If the product is perpetually available this method returns 1.
        - Otherwise, this method returns ATS / (allocation + preorderBackorderAllocation). (Values from [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md).)
      
      
      If inventory lists are not in use the method returns 0.
      
      The following rules apply for special product types:
      
      - For a master product this method returns the average availability  of its online variations.
      - For a master product with no online variations this method returns 0.
      - For a master product with own inventory record the rules of the standard  products apply. Note: In this case the availability of the variations is not considered.
      - For a product set this method returns the greatest availability of  the online products in the set.
      - For a product set with no online products this method returns 0.
      - For a product set with an inventory record the rules of the standard  products apply. Note: In this case the availability of the set products is not considered.
      - For a bundle, this method returns the least availability of the bundled  products according to their bundled quantity and if it exist also from  the bundle inventory record.



---

### availabilityStatus
- availabilityStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the availability-status for the minimum-orderable-quantity (MOQ) of
      the product.  The MOQ essentially represents a single orderable unit, and
      therefore can be represented by a single availability-status.  This
      method is essentially a convenience method.  The same information
      can be retrieved by calling [getAvailabilityLevels(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#getavailabilitylevelsnumber)
      with the MOQ of the product as the parameter and then retrieving the
      single status from the returned map.
      
      This method is typically used to display a product's availability in
      the catalog when the order quantity is not known.



---

### inStock
- inStock: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Convenience method for [isInStock(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isinstocknumber). Returns true, if the
      Product is available in the minimum-order-quantity. If the product does
      not have a minimum-order-quantity defined, in-stock is checked for a
      quantity value 1.



---

### inventoryRecord
- inventoryRecord: [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md) `(read-only)`
  - : Returns the ProductInventoryRecord for the Product associated
      with this model.



---

### orderable
- orderable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Convenience method for [isOrderable(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderablenumber). Returns true if the
      Product is currently online (based on its online flag and online dates)
      and is orderable in its minimum-order-quantity. If the product does not
      have a minimum-order-quantity specified, then 1 is used. The method
      returns false otherwise.
      
      
      Note: Orderable status is more general than in-stock status. A product
      may be out-of-stock but orderable because it is back-orderable or
      pre-orderable.



---

### timeToOutOfStock
- timeToOutOfStock: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of hours before the product is expected to go out
      of stock.  The basic formula is the ATS quantity divided by the
      sales velocity for the most recent day.  The following specific rules
      apply for standard products:
      
      - If the product is out of stock this method returns 0.
      - If the product is perpetually available this method returns 1.
      - If the sales velocity or ATS is not available this method returns 0.
      - Otherwise this method returns ATS / sales velocity.
      
      The following rules apply for special product types:
      
      - For a master product this method returns the greatest time to out  of stock of its online variations.
      - For a master product with no online variations this method returns 0.
      - For a product set this method returns the greatest time to out  of stock of the online products in the set.
      - For a product set with no online products this method returns 0.
      - For a bundle with no product inventory record, this method returns  the least time to out of stock of the online bundled products.
      - For a bundle with no product inventory record, and no online  bundled products, this method returns 0.



---

## Method Details

### getAvailability()
- getAvailability(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the availability of the product, which roughly defined is the
      ratio of the original stock that is still available to sell.  The basic
      formula, if the current site uses an
      inventory list, is the ATS quantity divided by allocation
      amount. If the product is not orderable at all this method returns 0.
      The following specific rules apply for standard products:
      
      - If inventory lists are in use:      
        - If no inventory record exists and the inventory list default-in-stock flag is true this method returns 1.
        - If no inventory record exists the inventory list default-in-stock flag is false this method returns 0.
        - If the product is not available this method returns 0.
        - If the product is perpetually available this method returns 1.
        - Otherwise, this method returns ATS / (allocation + preorderBackorderAllocation). (Values from [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md).)
      
      
      If inventory lists are not in use the method returns 0.
      
      The following rules apply for special product types:
      
      - For a master product this method returns the average availability  of its online variations.
      - For a master product with no online variations this method returns 0.
      - For a master product with own inventory record the rules of the standard  products apply. Note: In this case the availability of the variations is not considered.
      - For a product set this method returns the greatest availability of  the online products in the set.
      - For a product set with no online products this method returns 0.
      - For a product set with an inventory record the rules of the standard  products apply. Note: In this case the availability of the set products is not considered.
      - For a bundle, this method returns the least availability of the bundled  products according to their bundled quantity and if it exist also from  the bundle inventory record.



---

### getAvailabilityLevels(Number)
- getAvailabilityLevels(quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [ProductAvailabilityLevels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md)
  - : 
      Returns an instance of [ProductAvailabilityLevels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md),
      where each available quantity represents a part of the input quantity.
      This method is typically used to display availability information in
      the context of a known order quantity, e.g. a shopping cart.
      
      
      
      For example, if for a given product
      there are 3 pieces in stock with no pre/backorder handling specified,
      and the order quantity is 10, then the return instance would have the
      following state:
      
      - [ProductAvailabilityLevels.getInStock()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getinstock)- 3
      - [ProductAvailabilityLevels.getPreorder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getpreorder)- 0
      - [ProductAvailabilityLevels.getBackorder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getbackorder)- 0
      - [ProductAvailabilityLevels.getNotAvailable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getnotavailable)- 7
      
      
      The following assertions can be made about the state of the returned instance.
      
      - Between 1 and 3 levels are non-zero.
      - The sum of the levels equals the input quantity.
      - [ProductAvailabilityLevels.getPreorder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getpreorder)or [ProductAvailabilityLevels.getBackorder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md#getbackorder)may be available, but not both.
      
      
      
      
      
      Product bundles are handled specially:  The availability of product
      bundles is calculated based on the availability of the bundled products.
      Therefore, if a bundle contains products that are not in stock, then
      the bundle itself is not in stock.  If all the products in the bundle
      are on backorder, then the bundle itself is backordered.  If a product
      bundle has its own inventory record, then this record may
      further limit the availability.  If a bundle has no record, then
      only the records of the bundled products are considered.
      
      
      
      Product masters and product sets without an own inventory record are
      handled specially too:   The availability is calculated based on the
      availability of the variants or set products. A product master or product
      set is in stock as soon as one of its variants or set products is in stock.
      Each product master or product set availability level reflects the sum of
      the variant or set product availability levels up to the specified quantity.
      
      
      
      Product masters or product sets with own inventory record are handled like
      standard products. The availability of the variants or set products is not
      considered. (Such an inventory scenario should be avoided.)
      
      
      
      Offline products are always unavailable and will result in returned
      levels that are all unavailable.
      
      
      When using Omnichannel Inventory (OCI), future restocks provided by OCI are mapped to
      [AVAILABILITY_STATUS_BACKORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#availability_status_backorder). For more information, see the comments for
      [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md).


    **Parameters:**
    - quantity - The quantity to evaluate.

    **Returns:**
    - an instance of ProductAvailabilityLevels, which encapsulates the number
      of items for each relevant availability-status.


    **Throws:**
    - IllegalArgumentException - if the specified quantity is less or equal than zero

    **See Also:**
    - [ProductAvailabilityLevels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md)


---

### getAvailabilityStatus()
- getAvailabilityStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the availability-status for the minimum-orderable-quantity (MOQ) of
      the product.  The MOQ essentially represents a single orderable unit, and
      therefore can be represented by a single availability-status.  This
      method is essentially a convenience method.  The same information
      can be retrieved by calling [getAvailabilityLevels(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#getavailabilitylevelsnumber)
      with the MOQ of the product as the parameter and then retrieving the
      single status from the returned map.
      
      This method is typically used to display a product's availability in
      the catalog when the order quantity is not known.


    **Returns:**
    - the availability-status.


---

### getInventoryRecord()
- getInventoryRecord(): [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md)
  - : Returns the ProductInventoryRecord for the Product associated
      with this model.


    **Returns:**
    - the ProductInventoryRecord or null if there is none.


---

### getSKUCoverage()
- getSKUCoverage(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the SKU coverage of the product.  The basic formula for a
      master product is the ratio of online variations that are in stock
      to the total number of online variations.  The following specific rules
      apply for standard products:
      
      - If the product is in stock this method returns the availability of the product.
      - If the product is out of stock this method returns 0.
      
      The following rules apply for special product types:
      
      - For a master product this method returns the average SKU coverage  of its online variations.
      - For a master product with no online variations this method returns 0.
      - For a product set this method returns the ratio of orderable SKUs in the product set  over the total number of online SKUs in the product set. 
      - For a product set with no online products this method returns 0.
      - For a product bundle this method returns 1 if all of the bundled  products are online, and 0 otherwise.
      - For a product bundle with no online bundled products this method  returns 0.



---

### getTimeToOutOfStock()
- getTimeToOutOfStock(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of hours before the product is expected to go out
      of stock.  The basic formula is the ATS quantity divided by the
      sales velocity for the most recent day.  The following specific rules
      apply for standard products:
      
      - If the product is out of stock this method returns 0.
      - If the product is perpetually available this method returns 1.
      - If the sales velocity or ATS is not available this method returns 0.
      - Otherwise this method returns ATS / sales velocity.
      
      The following rules apply for special product types:
      
      - For a master product this method returns the greatest time to out  of stock of its online variations.
      - For a master product with no online variations this method returns 0.
      - For a product set this method returns the greatest time to out  of stock of the online products in the set.
      - For a product set with no online products this method returns 0.
      - For a bundle with no product inventory record, this method returns  the least time to out of stock of the online bundled products.
      - For a bundle with no product inventory record, and no online  bundled products, this method returns 0.



---

### isInStock()
- isInStock(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Convenience method for [isInStock(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isinstocknumber). Returns true, if the
      Product is available in the minimum-order-quantity. If the product does
      not have a minimum-order-quantity defined, in-stock is checked for a
      quantity value 1.


    **Returns:**
    - true if the Product is in stock, otherwise false.


---

### isInStock(Number)
- isInStock(quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the Product is in-stock in the given quantity. This is
      determined as follows:
      
      1. If the product is not currently online (based on its online flag and   online dates), then return false.
      2. If there is no inventory-list for the current site, then return   false.
      3. If there is no inventory-record for the product, then return the   default setting on the inventory-list.
      4. If there is no allocation-amount on the inventory-record, then return   the value of the perpetual-flag.
      5. If there is an allocation-amount, but the perpetual-flag is true,   then return true.
      6. If the quantity is less than or equal to the stock-level, then return   true.
      7. Otherwise return false.


    **Parameters:**
    - quantity - the quantity that is requested

    **Returns:**
    - true if the Product is in-stock.

    **Throws:**
    - Exception - if the specified quantity is less or equal than zero


---

### isOrderable()
- isOrderable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Convenience method for [isOrderable(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md#isorderablenumber). Returns true if the
      Product is currently online (based on its online flag and online dates)
      and is orderable in its minimum-order-quantity. If the product does not
      have a minimum-order-quantity specified, then 1 is used. The method
      returns false otherwise.
      
      
      Note: Orderable status is more general than in-stock status. A product
      may be out-of-stock but orderable because it is back-orderable or
      pre-orderable.


    **Returns:**
    - true if the Product is orderable for the minimum-order-quantity
              of the product.



---

### isOrderable(Number)
- isOrderable(quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the Product is currently online (based on its online flag
      and online dates) and the specified quantity does not exceed the quantity
      available for sale, and returns false otherwise.
      
      
      Note: Orderable status is more general than in-stock status. A product
      may be out-of-stock but orderable because it is back-orderable or
      pre-orderable.


    **Parameters:**
    - quantity - the quantity to test against.

    **Returns:**
    - true if the item can be ordered in the specified quantity.

    **Throws:**
    - Exception - if the specified quantity is less or equal than zero


---

<!-- prettier-ignore-end -->

<!-- document id=30b135e7d933ce8e56655120a805faf2d572f5e95cb48bf59bba0b391a83fac6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductInventoryList.md -->

<!-- prettier-ignore-start -->
# Class ProductInventoryList

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)

The ProductInventoryList provides access to ID, description and defaultInStockFlag of the list. Furthermore inventory
records can be accessed by product or product ID.


When using Omnichannel Inventory (OCI):

- B2C Commerce uses ProductInventoryLists to reference and expose OCI Locations and Location Groups. They're  required for synchronizing availability data and creating reservations.
- Create a ProductInventoryList in B2C Commerce for each OCI Location and Location Group that B2C Commerce will  access. The ProductInventoryList ID must match the External Reference field on the corresponding Location or Location  Group.
- A ProductInventoryList ID/External Reference must have between 2 and 128 characters (inclusive). It can include  only lowercase letters, uppercase letters, digits, hyphens, and underscores.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the inventory list. |
| [defaultInStockFlag](#defaultinstockflag): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the default in-stock flag of the inventory list. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of the inventory list. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDefaultInStockFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md#getdefaultinstockflag)() | Returns the default in-stock flag of the inventory list. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md#getdescription)() | Returns the description of the inventory list. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md#getid)() | Returns the ID of the inventory list. |
| [getRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md#getrecordproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the inventory record for the specified product or null  if there is no record for the product in this list. |
| [getRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md#getrecordstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the inventory record for the specified product ID or null  if there is no record for the product id in this list. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the inventory list.


---

### defaultInStockFlag
- defaultInStockFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the default in-stock flag of the inventory list.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of the inventory list.


---

## Method Details

### getDefaultInStockFlag()
- getDefaultInStockFlag(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the default in-stock flag of the inventory list.

    **Returns:**
    - Default in-stock flag of inventory list.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the inventory list.

    **Returns:**
    - Description of inventory list.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the inventory list.

    **Returns:**
    - ID of inventory list.


---

### getRecord(Product)
- getRecord(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md)
  - : Returns the inventory record for the specified product or null
      if there is no record for the product in this list.


    **Parameters:**
    - product - The product to lookup inventory record.

    **Returns:**
    - Inventory record or `null` if not found.


---

### getRecord(String)
- getRecord(productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md)
  - : Returns the inventory record for the specified product ID or null
      if there is no record for the product id in this list.


    **Parameters:**
    - productID - The product ID to lookup inventory record.

    **Returns:**
    - Inventory record or `null` if not found.


---

<!-- prettier-ignore-end -->

<!-- document id=7bb16e0532907b31611ace4fc6d03a0fd32f2e8fefc901bff6ee12b632f7d307 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductInventoryMgr.md -->

<!-- prettier-ignore-start -->
# Class ProductInventoryMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductInventoryMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md)

This manager provides access to inventory-related objects.


## Constant Summary

| Constant | Description |
| --- | --- |
| [INTEGRATIONMODE_B2C](#integrationmode_b2c): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "B2C" | Integration mode 'B2C' - using B2C inventory, no integration with Omnichannel Inventory |
| [INTEGRATIONMODE_OCI](#integrationmode_oci): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OCI" | Integration mode 'OCI' - integration with Omnichannel Inventory enabled |
| [INTEGRATIONMODE_OCI_CACHE](#integrationmode_oci_cache): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OCI_CACHE" | Integration mode 'OCI\_CACHE' - using B2C inventory, initializing cache as preparation for integration with  Omnichannel Inventory |

## Property Summary

| Property | Description |
| --- | --- |
| [inventoryIntegrationMode](#inventoryintegrationmode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the current inventory integration mode as one of  <ul>  <li>[INTEGRATIONMODE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_b2c)</li>  <li>[INTEGRATIONMODE_OCI_CACHE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci_cache)</li>  <li>[INTEGRATIONMODE_OCI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci)</li>  </ul> |
| [inventoryList](#inventorylist): [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md) `(read-only)` | Returns the inventory list assigned to the current site or null if no inventory list is assigned to the current  site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getInventoryIntegrationMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#getinventoryintegrationmode)() | Returns the current inventory integration mode as one of  <ul>  <li>[INTEGRATIONMODE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_b2c)</li>  <li>[INTEGRATIONMODE_OCI_CACHE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci_cache)</li>  <li>[INTEGRATIONMODE_OCI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci)</li>  </ul> |
| static [getInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#getinventorylist)() | Returns the inventory list assigned to the current site or null if no inventory list is assigned to the current  site. |
| static [getInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#getinventoryliststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the inventory list with the passed ID or null if no inventory list exists with that ID. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### INTEGRATIONMODE_B2C

- INTEGRATIONMODE_B2C: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "B2C"
  - : Integration mode 'B2C' - using B2C inventory, no integration with Omnichannel Inventory


---

### INTEGRATIONMODE_OCI

- INTEGRATIONMODE_OCI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OCI"
  - : Integration mode 'OCI' - integration with Omnichannel Inventory enabled


---

### INTEGRATIONMODE_OCI_CACHE

- INTEGRATIONMODE_OCI_CACHE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OCI_CACHE"
  - : Integration mode 'OCI\_CACHE' - using B2C inventory, initializing cache as preparation for integration with
      Omnichannel Inventory



---

## Property Details

### inventoryIntegrationMode
- inventoryIntegrationMode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the current inventory integration mode as one of
      
      - [INTEGRATIONMODE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_b2c)
      - [INTEGRATIONMODE_OCI_CACHE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci_cache)
      - [INTEGRATIONMODE_OCI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci)



---

### inventoryList
- inventoryList: [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md) `(read-only)`
  - : Returns the inventory list assigned to the current site or null if no inventory list is assigned to the current
      site.



---

## Method Details

### getInventoryIntegrationMode()
- static getInventoryIntegrationMode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current inventory integration mode as one of
      
      - [INTEGRATIONMODE_B2C](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_b2c)
      - [INTEGRATIONMODE_OCI_CACHE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci_cache)
      - [INTEGRATIONMODE_OCI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md#integrationmode_oci)


    **Returns:**
    - The current inventory integration mode as a constant String.


---

### getInventoryList()
- static getInventoryList(): [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)
  - : Returns the inventory list assigned to the current site or null if no inventory list is assigned to the current
      site.


    **Returns:**
    - The ProductInventoryList assigned to the current site, or null.


---

### getInventoryList(String)
- static getInventoryList(listID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)
  - : Returns the inventory list with the passed ID or null if no inventory list exists with that ID.

    **Parameters:**
    - listID - The ID of the inventory list to retrieve.

    **Returns:**
    - The ProductInventoryList identified by listID, or null.


---

<!-- prettier-ignore-end -->

<!-- document id=e01947a49fe9da90271869e8ab359e9336c868951c35dbbcd6cdaf1ed4aabee1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductInventoryRecord.md -->

<!-- prettier-ignore-start -->
# Class ProductInventoryRecord

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md)

The ProductInventoryRecord holds information about a Product's inventory, and availability.


When using Omnichannel Inventory (OCI):

- All ProductInventoryRecord properties are read-only. Calling any setter method throws an  IllegalStateException.
- The ProductInventoryRecord class does not support custom properties.
- [isPerpetual()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#isperpetual)and [isPreorderable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#ispreorderable)always return false.



## Property Summary

| Property | Description |
| --- | --- |
| [ATS](#ats): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity of items available to sell (ATS). |
| [allocation](#allocation): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | Returns the allocation quantity that is currently set. |
| [allocationResetDate](#allocationresetdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date the allocation quantity was initialized or reset. |
| [backorderable](#backorderable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Determines if the product is backorderable. |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes for this object. |
| [inStockDate](#instockdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns the date that the item is expected to be in stock. |
| ~~[onHand](#onhand): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)~~ `(read-only)` | Returns the on-hand quantity, the actual quantity of available (on-hand) items. |
| [onOrder](#onorder): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity that is currently on order. |
| [perpetual](#perpetual): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Determines if the product is perpetually in stock. |
| [preorderBackorderAllocation](#preorderbackorderallocation): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | Returns the quantity of items that are allocated for sale, beyond the initial stock allocation. |
| [preorderable](#preorderable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Determines if the product is preorderable. |
| [reserved](#reserved): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity of items that are reserved. |
| [stockLevel](#stocklevel): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the current stock level. |
| [turnover](#turnover): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the sum of all inventory transactions (decrements and increments) recorded after the allocation reset  date. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#describe)() | Returns the meta data of this object. |
| [getATS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getats)() | Returns the quantity of items available to sell (ATS). |
| [getAllocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getallocation)() | Returns the allocation quantity that is currently set. |
| [getAllocationResetDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getallocationresetdate)() | Returns the date the allocation quantity was initialized or reset. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getcustom)() | Returns the custom attributes for this object. |
| [getInStockDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getinstockdate)() | Returns the date that the item is expected to be in stock. |
| ~~[getOnHand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getonhand)()~~ | Returns the on-hand quantity, the actual quantity of available (on-hand) items. |
| [getOnOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getonorder)() | Returns the quantity that is currently on order. |
| [getPreorderBackorderAllocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getpreorderbackorderallocation)() | Returns the quantity of items that are allocated for sale, beyond the initial stock allocation. |
| [getReserved](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getreserved)() | Returns the quantity of items that are reserved. |
| [getStockLevel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getstocklevel)() | Returns the current stock level. |
| [getTurnover](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getturnover)() | Returns the sum of all inventory transactions (decrements and increments) recorded after the allocation reset  date. |
| [isBackorderable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#isbackorderable)() | Determines if the product is backorderable. |
| [isPerpetual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#isperpetual)() | Determines if the product is perpetually in stock. |
| [isPreorderable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#ispreorderable)() | Determines if the product is preorderable. |
| [setAllocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#setallocationnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the allocation quantity. |
| [setAllocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#setallocationnumber-date)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the allocation quantity. |
| [setBackorderable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#setbackorderableboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | The method is used to set whether the product is backorderable. |
| [setInStockDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#setinstockdatedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the date that the item is expected to be in stock. |
| [setPerpetual](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#setperpetualboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets if the product is perpetually in stock. |
| [setPreorderBackorderAllocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#setpreorderbackorderallocationnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the quantity of items that are allocated for sale, beyond the initial stock allocation. |
| [setPreorderable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#setpreorderableboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | The method is used to set whether the product is preorderable. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ATS
- ATS: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity of items available to sell (ATS). This is calculated as the allocation
      ([getAllocation()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getallocation)) plus the preorderBackorderAllocation ([getPreorderBackorderAllocation()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getpreorderbackorderallocation)) minus
      the turnover ([getTurnover()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getturnover)) minus the on order quantity ([getOnOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getonorder)).
      
      
      When using OCI, corresponds to the ATO (Available To Order) quantity in OCI.



---

### allocation
- allocation: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the allocation quantity that is currently set. The quantity unit is the same unit as the product itself.
      
      
      When using OCI, returns the physically available quantity. Corresponds to the On Hand quantity in OCI.



---

### allocationResetDate
- allocationResetDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date the allocation quantity was initialized or reset.
      
      
      When using OCI, corresponds to the Effective Date in OCI. The value can be null.



---

### backorderable
- backorderable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines if the product is backorderable.
      
      
      When using OCI, returns true if the product has at least one Future quantity in OCI.



---

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes for this object. The returned object is used for retrieving and storing attribute
      values. See [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) for a detailed example of the syntax for working with custom
      attributes.
      
      
      When using Omnichannel Inventory (OCI), this class doesn't support custom attributes. If OCI is enabled, then
      attempting to set or modify a custom attribute value throws an UnsupportedOperationException.



---

### inStockDate
- inStockDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date that the item is expected to be in stock.
      
      
      When using OCI, returns the date of the earliest Future quantity. If the product has no Future quantities, it
      returns null.



---

### onHand
- ~~onHand: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)~~ `(read-only)`
  - : Returns the on-hand quantity, the actual quantity of available (on-hand) items.

    **Deprecated:**
**warning:** Use [getStockLevel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getstocklevel) instead.
    **API Version:**
**note:** No longer available as of version 21.7.

---

### onOrder
- onOrder: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity that is currently on order.
      
      
      This is only relevant when On Order Inventory is turned on for the related inventory list. On Order is a bucket
      of inventory used for the time between order creation and order export to external (warehouse) systems. On Order
      value is increased when an order is created. It will be decreased and with that turnover will be increased when
      the order is exported, see [getTurnover()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getturnover). Notice that [Order.setExportStatus(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setexportstatusnumber) and
      [OrderItem.allocateInventory(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#allocateinventoryboolean) will decrease the On Order value. On order will be included
      in the ATS calculation, see [getATS()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getats).
      
      
      
      
      When using OCI, always returns zero. OCI doesn't support On Order inventory.



---

### perpetual
- perpetual: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines if the product is perpetually in stock.
      
      
      When using OCI, always returns false.



---

### preorderBackorderAllocation
- preorderBackorderAllocation: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of items that are allocated for sale, beyond the initial stock allocation.
      
      
      When using OCI, returns the sum of all Future quantities. If the product has no Future quantities, it returns
      zero.



---

### preorderable
- preorderable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines if the product is preorderable.
      
      
      When using OCI, always returns false.



---

### reserved
- reserved: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity of items that are reserved.
      
      
      Note that for products with high velocity and concurrency, the return value is extremely volatile and the
      retrieval will be expensive.
      
      
      When using OCI, always returns zero.



---

### stockLevel
- stockLevel: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the current stock level. This is calculated as the allocation minus the turnover.
      
      
      When using OCI, corresponds to the ATF (Available To Fulfill) quantity in OCI.



---

### turnover
- turnover: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the sum of all inventory transactions (decrements and increments) recorded after the allocation reset
      date. If the total decremented quantity is greater than the total incremented quantity, then this value is
      negative.
      
      
      When using OCI, returns the total reserved quantity, including order, basket, and temporary reservations.



---

## Method Details

### describe()
- describe(): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the meta data of this object. If no meta data is available the method returns null. The returned
      ObjectTypeDefinition can be used to retrieve the metadata for any of the custom attributes.
      
      
      When using Omnichannel Inventory (OCI), this class doesn't support custom attributes. If OCI is enabled, then
      attempting to set or modify a custom attribute value throws an UnsupportedOperationException.


    **Returns:**
    - the meta data of this object. If no meta data is available the method returns null.


---

### getATS()
- getATS(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of items available to sell (ATS). This is calculated as the allocation
      ([getAllocation()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getallocation)) plus the preorderBackorderAllocation ([getPreorderBackorderAllocation()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getpreorderbackorderallocation)) minus
      the turnover ([getTurnover()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getturnover)) minus the on order quantity ([getOnOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getonorder)).
      
      
      When using OCI, corresponds to the ATO (Available To Order) quantity in OCI.


    **Returns:**
    - the quantity or quantity N/A if not available.


---

### getAllocation()
- getAllocation(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the allocation quantity that is currently set. The quantity unit is the same unit as the product itself.
      
      
      When using OCI, returns the physically available quantity. Corresponds to the On Hand quantity in OCI.


    **Returns:**
    - the allocation quantity or quantity N/A if not available.


---

### getAllocationResetDate()
- getAllocationResetDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date the allocation quantity was initialized or reset.
      
      
      When using OCI, corresponds to the Effective Date in OCI. The value can be null.


    **Returns:**
    - the allocation reset date.


---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes for this object. The returned object is used for retrieving and storing attribute
      values. See [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) for a detailed example of the syntax for working with custom
      attributes.
      
      
      When using Omnichannel Inventory (OCI), this class doesn't support custom attributes. If OCI is enabled, then
      attempting to set or modify a custom attribute value throws an UnsupportedOperationException.


    **Returns:**
    - the custom attributes for this object.


---

### getInStockDate()
- getInStockDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date that the item is expected to be in stock.
      
      
      When using OCI, returns the date of the earliest Future quantity. If the product has no Future quantities, it
      returns null.


    **Returns:**
    - the date that the item is expected to be in stock.


---

### getOnHand()
- ~~getOnHand(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)~~
  - : Returns the on-hand quantity, the actual quantity of available (on-hand) items.

    **Returns:**
    - the on-hand quantity or quantity N/A if not available.

    **Deprecated:**
**warning:** Use [getStockLevel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getstocklevel) instead.
    **API Version:**
**note:** No longer available as of version 21.7.

---

### getOnOrder()
- getOnOrder(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity that is currently on order.
      
      
      This is only relevant when On Order Inventory is turned on for the related inventory list. On Order is a bucket
      of inventory used for the time between order creation and order export to external (warehouse) systems. On Order
      value is increased when an order is created. It will be decreased and with that turnover will be increased when
      the order is exported, see [getTurnover()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getturnover). Notice that [Order.setExportStatus(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#setexportstatusnumber) and
      [OrderItem.allocateInventory(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#allocateinventoryboolean) will decrease the On Order value. On order will be included
      in the ATS calculation, see [getATS()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getats).
      
      
      
      
      When using OCI, always returns zero. OCI doesn't support On Order inventory.


    **Returns:**
    - the quantity or quantity N/A if not available.


---

### getPreorderBackorderAllocation()
- getPreorderBackorderAllocation(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of items that are allocated for sale, beyond the initial stock allocation.
      
      
      When using OCI, returns the sum of all Future quantities. If the product has no Future quantities, it returns
      zero.


    **Returns:**
    - the quantity or quantity N/A if not available.


---

### getReserved()
- getReserved(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of items that are reserved.
      
      
      Note that for products with high velocity and concurrency, the return value is extremely volatile and the
      retrieval will be expensive.
      
      
      When using OCI, always returns zero.


    **Returns:**
    - the quantity of items reserved for this product.


---

### getStockLevel()
- getStockLevel(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the current stock level. This is calculated as the allocation minus the turnover.
      
      
      When using OCI, corresponds to the ATF (Available To Fulfill) quantity in OCI.


    **Returns:**
    - the stock level or quantity N/A if not available.


---

### getTurnover()
- getTurnover(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the sum of all inventory transactions (decrements and increments) recorded after the allocation reset
      date. If the total decremented quantity is greater than the total incremented quantity, then this value is
      negative.
      
      
      When using OCI, returns the total reserved quantity, including order, basket, and temporary reservations.


    **Returns:**
    - the turnover or quantity N/A if not available.


---

### isBackorderable()
- isBackorderable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines if the product is backorderable.
      
      
      When using OCI, returns true if the product has at least one Future quantity in OCI.


    **Returns:**
    - true if the product is backorderable.


---

### isPerpetual()
- isPerpetual(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines if the product is perpetually in stock.
      
      
      When using OCI, always returns false.


    **Returns:**
    - true if the product is perpetually in stock.


---

### isPreorderable()
- isPreorderable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Determines if the product is preorderable.
      
      
      When using OCI, always returns false.


    **Returns:**
    - true if the product is preorderable.


---

### setAllocation(Number)
- setAllocation(quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the allocation quantity. This also updates the allocation reset date. 
      
      All final reservations will be considered as expired and will therefore no longer be considered for ATS.
      
      
      When using OCI, throws an IllegalStateException.
      
      This method should **not** be called within a storefront request.


    **Parameters:**
    - quantity - the allocation quantity to set (must be greater than or equal to zero).

    **API Version:**
**note:** No longer available as of version 21.7.

---

### setAllocation(Number, Date)
- setAllocation(quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), allocationResetDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the allocation quantity. This also updates the allocation reset date.
      
      Any final reservations made prior to the allocation reset date will be considered as expired and will therefore
      no longer be considered for ATS.
      
      
      When using OCI, throws an IllegalStateException.
      
      This method must **not** be called within a storefront request.


    **Parameters:**
    - quantity - the allocation quantity to set (must be greater than or equal to zero).
    - allocationResetDate - the date allocation quantity was effectively calculated                          <li>the reset date must not be older than 48 hours</li>             <li>the reset date must not be older than the prior reset date. see             [getAllocationResetDate()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md#getallocationresetdate)</li>             </ul>


---

### setBackorderable(Boolean)
- setBackorderable(backorderableFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : The method is used to set whether the product is backorderable. Setting the backorderable flag to true will clear
      the preorderable flag. If the record's preorderable flag is set to true, calling this method with
      backorderableFlag==false will have no effect.
      
      
      When using OCI, throws an IllegalStateException. 
      
      This method should **not** be called within a storefront request.
      
      This method must **not** be called within a storefront request when the API version is 21.7 or later.


    **Parameters:**
    - backorderableFlag - the flag to set backorderable status.


---

### setInStockDate(Date)
- setInStockDate(inStockDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the date that the item is expected to be in stock.
      
      
      When using OCI, throws an IllegalStateException. 
      
      This method should **not** be called within a storefront request.
      
      This method must **not** be called within a storefront request when the API version is 21.7 or later.


    **Parameters:**
    - inStockDate - the date that the item is expected to be in stock.


---

### setPerpetual(Boolean)
- setPerpetual(perpetualFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets if the product is perpetually in stock.
      
      
      When using OCI, throws an IllegalStateException. 
      
      This method should **not** be called within a storefront request.
      
      This method must **not** be called within a storefront request when the API version is 21.7 or later.


    **Parameters:**
    - perpetualFlag - true to set the product perpetually in stock.


---

### setPreorderBackorderAllocation(Number)
- setPreorderBackorderAllocation(quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the quantity of items that are allocated for sale, beyond the initial stock allocation.
      
      
      When using OCI, throws an IllegalStateException.
      
      This method should **not** be called within a storefront request.
      
      This method must **not** be called within a storefront request when the API version is 21.7 or later.


    **Parameters:**
    - quantity - the quantity to set.


---

### setPreorderable(Boolean)
- setPreorderable(preorderableFlag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : The method is used to set whether the product is preorderable. Setting the preorderable flag to true will clear
      the backorderable flag. If the record's backorderable flag is set to true, calling this method with
      preorderableFlag==false will have no effect.
      
      
      When using OCI, throws an IllegalStateException. 
      
      This method should **not** be called within a storefront request.
      
      This method must **not** be called within a storefront request when the API version is 21.7 or later.


    **Parameters:**
    - preorderableFlag - the flag to set preorderable status.


---

<!-- prettier-ignore-end -->

<!-- document id=974f8f73ab1e4e58d22a54ec00a1314a7a37a855b6cfdf5c1f4c3839cfe469e6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ProductLineItem.md -->

<!-- prettier-ignore-start -->
# Class ProductLineItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
        - [dw.order.ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)

Represents a specific product line item.


## Property Summary

| Property | Description |
| --- | --- |
| [adjustedGrossPrice](#adjustedgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the gross price of the product line item after applying all product-level  adjustments. |
| [adjustedNetPrice](#adjustednetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the net price of the product line item after applying all product-level  adjustments. |
| [adjustedPrice](#adjustedprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the price of the product line item after applying all product-level  adjustments. |
| [adjustedTax](#adjustedtax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the tax of the unit after applying adjustments, in the purchase currency. |
| [bonusDiscountLineItem](#bonusdiscountlineitem): [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md) `(read-only)` | Returns the parent bonus discount line item of this line item. |
| [bonusProductLineItem](#bonusproductlineitem): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the product line item represents a bonus line item. |
| [bundledProductLineItem](#bundledproductlineitem): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the product line item represents a bundled line item. |
| [bundledProductLineItems](#bundledproductlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing the bundled product line items. |
| [catalogProduct](#catalogproduct): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the product line item represents a catalog product. |
| [category](#category): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) | Returns the category the product line item is associated with. |
| [categoryID](#categoryid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the ID of the category the product line item is associated with. |
| [externalLineItemStatus](#externallineitemstatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the value set for the external line item status  or null if no value set. |
| [externalLineItemText](#externallineitemtext): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the value set for the external line item text  or null if no value set. |
| [gift](#gift): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns true if this line item represents a gift, false otherwise. |
| [giftMessage](#giftmessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the value set for gift message or null if no value set. |
| [manufacturerName](#manufacturername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the manfacturer of the product. |
| [manufacturerSKU](#manufacturersku): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the manfacturer's SKU of this product line item. |
| [minOrderQuantity](#minorderquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the minimal order quantity allowed for the product represented by the  ProductLineItem (copied from product on initialization). |
| [minOrderQuantityValue](#minorderquantityvalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Return the value portion of getMinOrderQuantity(). |
| [optionID](#optionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product option this product line item  represents. |
| [optionModel](#optionmodel): [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md) `(read-only)` | Returns the product option model for a product line item representing an option product. |
| [optionProductLineItem](#optionproductlineitem): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the product line item represents an option line item. |
| [optionProductLineItems](#optionproductlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing option product line items. |
| [optionValueID](#optionvalueid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product option value this product line item  represents. |
| [orderItem](#orderitem): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)` | Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or null. |
| [parent](#parent): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) `(read-only)` | Returns the parent line item of this line item or null if the line item  is independent. |
| [position](#position): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the position within the line item container assigned to the ProductLineItem upon its creation, may be  used as a sort-order. |
| [priceAdjustments](#priceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns an iterator of price adjustments that have been applied to this  product line item such as promotions on the purchase price  (i.e. |
| [product](#product): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the product associated with the product line item. |
| [productID](#productid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the related product. |
| [productInventoryList](#productinventorylist): [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md) | Returns the inventory list the product line item is associated with. |
| [productInventoryListID](#productinventorylistid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the ID of the inventory list the product line item is associated with. |
| [productListItem](#productlistitem): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md) `(read-only)` | Returns the associated ProductListItem. |
| [productName](#productname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of the product that was copied when  product was added to line item container. |
| [proratedPrice](#proratedprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the price of this product line item after considering all  dependent price adjustments and prorating all Buy-X-Get-Y  and order-level discounts, according to the scheme described in  [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). |
| [proratedPriceAdjustmentPrices](#proratedpriceadjustmentprices): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns a Map of PriceAdjustment to Money instances. |
| [qualifyingProductLineItemForBonusProduct](#qualifyingproductlineitemforbonusproduct): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) `(read-only)` | Returns the ProductLineItem that qualified the basket for this bonus product. |
| [quantity](#quantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity of the product represented by this ProductLineItem. |
| [quantityValue](#quantityvalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the value of the quantity of this ProductLineItem. |
| [relatedBonusProductLineItems](#relatedbonusproductlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all bonus product line items for which this line item is a  qualifying product line item. |
| [reserved](#reserved): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns if the product line item is reserved. |
| [shipment](#shipment): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md) | Returns the associated Shipment. |
| [shippingLineItem](#shippinglineitem): [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md) `(read-only)` | Returns the dependent shipping line item of this line item. |
| [stepQuantity](#stepquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns step quantity allowed for the product represented by the ProductLineItem  (copied from product on initialization). |
| [stepQuantityValue](#stepquantityvalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Return the value portion of getStepQuantity(). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createpriceadjustmentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a product price adjustment. |
| [createPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createpriceadjustmentstring-discount)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)) | Creates a product price adjustment representing a specific discount. |
| [createShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#createshippinglineitem)() | Creates the dependent shipping line item for this line item. |
| [getAdjustedGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedgrossprice)() | Returns the gross price of the product line item after applying all product-level  adjustments. |
| [getAdjustedNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustednetprice)() | Returns the net price of the product line item after applying all product-level  adjustments. |
| [getAdjustedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedprice)() | Returns the price of the product line item after applying all product-level  adjustments. |
| [getAdjustedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedpriceboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the price of this product line item after considering all  dependent price adjustments and optionally prorating all order-level  price adjustments. |
| [getAdjustedTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedtax)() | Returns the tax of the unit after applying adjustments, in the purchase currency. |
| [getBonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getbonusdiscountlineitem)() | Returns the parent bonus discount line item of this line item. |
| [getBundledProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getbundledproductlineitems)() | Returns a collection containing the bundled product line items. |
| [getCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getcategory)() | Returns the category the product line item is associated with. |
| [getCategoryID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getcategoryid)() | Returns the ID of the category the product line item is associated with. |
| [getExternalLineItemStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getexternallineitemstatus)() | Returns the value set for the external line item status  or null if no value set. |
| [getExternalLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getexternallineitemtext)() | Returns the value set for the external line item text  or null if no value set. |
| [getGiftMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getgiftmessage)() | Returns the value set for gift message or null if no value set. |
| [getManufacturerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getmanufacturername)() | Returns the name of the manfacturer of the product. |
| [getManufacturerSKU](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getmanufacturersku)() | Returns the name of the manfacturer's SKU of this product line item. |
| [getMinOrderQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getminorderquantity)() | Returns the minimal order quantity allowed for the product represented by the  ProductLineItem (copied from product on initialization). |
| [getMinOrderQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getminorderquantityvalue)() | Return the value portion of getMinOrderQuantity(). |
| [getOptionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getoptionid)() | Returns the ID of the product option this product line item  represents. |
| [getOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getoptionmodel)() | Returns the product option model for a product line item representing an option product. |
| [getOptionProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getoptionproductlineitems)() | Returns a collection containing option product line items. |
| [getOptionValueID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getoptionvalueid)() | Returns the ID of the product option value this product line item  represents. |
| [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getorderitem)() | Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or null. |
| [getParent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getparent)() | Returns the parent line item of this line item or null if the line item  is independent. |
| [getPosition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getposition)() | Returns the position within the line item container assigned to the ProductLineItem upon its creation, may be  used as a sort-order. |
| [getPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getpriceadjustmentbypromotionidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the first price adjustment associated to the specified promotion ID. |
| [getPriceAdjustmentByPromotionIDAndCouponCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getpriceadjustmentbypromotionidandcouponcodestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the price adjustment associated to the specified promotion ID and coupon code combination. |
| [getPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getpriceadjustments)() | Returns an iterator of price adjustments that have been applied to this  product line item such as promotions on the purchase price  (i.e. |
| [getPriceAdjustmentsByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getpriceadjustmentsbypromotionidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the collection of price adjustments associated to the specified promotion ID. |
| [getProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproduct)() | Returns the product associated with the product line item. |
| [getProductID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproductid)() | Returns the ID of the related product. |
| [getProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproductinventorylist)() | Returns the inventory list the product line item is associated with. |
| [getProductInventoryListID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproductinventorylistid)() | Returns the ID of the inventory list the product line item is associated with. |
| [getProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproductlistitem)() | Returns the associated ProductListItem. |
| [getProductName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproductname)() | Returns the name of the product that was copied when  product was added to line item container. |
| [getProratedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproratedprice)() | Returns the price of this product line item after considering all  dependent price adjustments and prorating all Buy-X-Get-Y  and order-level discounts, according to the scheme described in  [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). |
| [getProratedPriceAdjustmentPrices](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproratedpriceadjustmentprices)() | Returns a Map of PriceAdjustment to Money instances. |
| [getQualifyingProductLineItemForBonusProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getqualifyingproductlineitemforbonusproduct)() | Returns the ProductLineItem that qualified the basket for this bonus product. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getquantity)() | Returns the quantity of the product represented by this ProductLineItem. |
| [getQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getquantityvalue)() | Returns the value of the quantity of this ProductLineItem. |
| [getRelatedBonusProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getrelatedbonusproductlineitems)() | Returns all bonus product line items for which this line item is a  qualifying product line item. |
| [getShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getshipment)() | Returns the associated Shipment. |
| [getShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getshippinglineitem)() | Returns the dependent shipping line item of this line item. |
| [getStepQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getstepquantity)() | Returns step quantity allowed for the product represented by the ProductLineItem  (copied from product on initialization). |
| [getStepQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getstepquantityvalue)() | Return the value portion of getStepQuantity(). |
| [isBonusProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isbonusproductlineitem)() | Identifies if the product line item represents a bonus line item. |
| [isBundledProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isbundledproductlineitem)() | Identifies if the product line item represents a bundled line item. |
| [isCatalogProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#iscatalogproduct)() | Returns true if the product line item represents a catalog product. |
| [isGift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isgift)() | Returns true if this line item represents a gift, false otherwise. |
| [isOptionProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isoptionproductlineitem)() | Identifies if the product line item represents an option line item. |
| [isReserved](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#isreserved)() | Returns if the product line item is reserved. |
| [removePriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#removepriceadjustmentpriceadjustment)([PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)) | Removes the specified price adjustment from the product line item. |
| [removeShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#removeshippinglineitem)() | Removes the dependent shipping line item for this line item. |
| [replaceProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#replaceproductproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Replaces the current product of the product line item with the product specified in parameter _newProduct_. |
| [setCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setcategorycategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)) | Sets the specified category as the product line item category context. |
| [setCategoryID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setcategoryidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the ID of the category the product line item is associated with. |
| [setExternalLineItemStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setexternallineitemstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value to set for the external line item status. |
| [setExternalLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setexternallineitemtextstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value to set for the external line item text. |
| [setGift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setgiftboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Controls if this line item is a gift or not. |
| [setGiftMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setgiftmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value to set for the gift message. |
| [setManufacturerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setmanufacturernamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the manufacturer of this product. |
| [setManufacturerSKU](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setmanufacturerskustring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the SKU of the manufacturer of this product. |
| [setMinOrderQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setminorderquantityvaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the minimum order quantity value for this object. |
| [setPosition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setpositionnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the position within the line item container. |
| [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setpricevaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets price attributes of the line item based on the current  purchase currency, taxation policy and line item quantity. |
| [setProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setproductinventorylistproductinventorylist)([ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)) | Sets the specified inventory list as the product line item inventory context. |
| [setProductInventoryListID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setproductinventorylistidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the ID of the inventory list the product line item is associated with. |
| [setProductName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setproductnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the name of the product. |
| [setQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setquantityvaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Updates the quantity value of the product line item. |
| [setShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setshipmentshipment)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Associates the specified product line item with the specified shipment. |
| [setStepQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setstepquantityvaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the step quantity value for this object. |
| [updateOptionPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#updateoptionprice)() | Determines and sets the price of a option line item based on the selected option value this line item represents. |
| [updateOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#updateoptionvalueproductoptionvalue)([ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)) | Updates an option line item with a new option value. |
| ~~[updatePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#updatepricemoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md))~~ | Updates the price attributes of the line item based  on the specified price. |
| ~~[updateQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#updatequantitynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Updates the quantity value of the product line item and all its dependent product line items. |

### Methods inherited from class LineItem

[getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getbaseprice), [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getgrossprice), [getLineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemctnr), [getLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemtext), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getnetprice), [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice), [getPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getpricevalue), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxbasis), [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxclassid), [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxrate), [getTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes), [setBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setbasepricemoney), [setGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setgrosspricemoney), [setLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setlineitemtextstring), [setNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setnetpricemoney), [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setpricevaluenumber), [setTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxmoney), [setTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxclassidstring), [setTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxratenumber), [setTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection), [updatePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber-money), [updateTaxAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxamountmoney)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### adjustedGrossPrice
- adjustedGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the gross price of the product line item after applying all product-level
      adjustments.


    **See Also:**
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustednetprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedprice)


---

### adjustedNetPrice
- adjustedNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the net price of the product line item after applying all product-level
      adjustments.


    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedgrossprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedprice)


---

### adjustedPrice
- adjustedPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the price of the product line item after applying all product-level
      adjustments. For net pricing the adjusted net price is returned
      (see [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustednetprice)). For gross pricing, the adjusted
      gross price is returned (see [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedgrossprice)).


    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedgrossprice)
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustednetprice)


---

### adjustedTax
- adjustedTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the tax of the unit after applying adjustments, in the purchase currency.


---

### bonusDiscountLineItem
- bonusDiscountLineItem: [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md) `(read-only)`
  - : Returns the parent bonus discount line item of this line item.  Only
      bonus product line items that have been selected by the customer as
      part of a BONUS\_CHOICE discount have one of these.



---

### bonusProductLineItem
- bonusProductLineItem: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the product line item represents a bonus line item.


---

### bundledProductLineItem
- bundledProductLineItem: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the product line item represents a bundled line item.


---

### bundledProductLineItems
- bundledProductLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing the bundled product line items.


---

### catalogProduct
- catalogProduct: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the product line item represents a catalog product.
      
      
      That flag is determined during product line item creation with
      [LineItemCtnr.createProductLineItem(String, Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-shipment), stored at the line item container and can
      be accessed as productLineItem.catalogProduct. It represents what can be evaluated with
      
      
      ```
      dw.catalog.ProductMgr.getProduct( productID ) != null
          && dw.catalog.ProductMgr.getProduct( productID ).isAssignedToSiteCatalog()
      ```
      
      
      If the product is not available during product line item creation it is considered a non catalog product line item without
      connection to a product.


    **See Also:**
    - [getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproduct)


---

### category
- category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the category the product line item is associated with. If the
      line item is not associated with a category, or the category does not
      exist in the site catalog, the method returns null.



---

### categoryID
- categoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the category the product line item is associated with.


---

### externalLineItemStatus
- externalLineItemStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for the external line item status
      or null if no value set.



---

### externalLineItemText
- externalLineItemText: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for the external line item text
      or null if no value set.



---

### gift
- gift: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this line item represents a gift, false otherwise.


---

### giftMessage
- giftMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for gift message or null if no value set.


---

### manufacturerName
- manufacturerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the manfacturer of the product.


---

### manufacturerSKU
- manufacturerSKU: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the manfacturer's SKU of this product line item.


---

### minOrderQuantity
- minOrderQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the minimal order quantity allowed for the product represented by the
      ProductLineItem (copied from product on initialization).
      Note: the quantity of a ProductLineItem must obey the limits set by the
      ProductLineItem's attributes 'MinOrderQuantity' and 'StepQuantity', i.e.
      for a 'MinOrderQuantity' of 2.0 and a 'StepQuantity' of 2.5 then values
      2.0, 4.5, 7.0... are allowed values.



---

### minOrderQuantityValue
- minOrderQuantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the value portion of getMinOrderQuantity().


---

### optionID
- optionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product option this product line item
      represents. If the product line item does not represent an option,
      null is returned.



---

### optionModel
- optionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md) `(read-only)`
  - : Returns the product option model for a product line item representing an option product.
      
      
      The returned option model has preselected values based on the dependent option line items of this product line
      item. Null is returned if this line item does not represent an option product.



---

### optionProductLineItem
- optionProductLineItem: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the product line item represents an option line item.
      Option line items do not represent true products but rather options of
      products.  An option line item always has a parent product line item
      representing a true product.



---

### optionProductLineItems
- optionProductLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing option product line items.


---

### optionValueID
- optionValueID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product option value this product line item
      represents. If the product line item does not represent an option,
      null is returned.



---

### orderItem
- orderItem: [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)`
  - : Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or null. An order-item
      extension will only exist for a ProductLineItem which belongs to an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### parent
- parent: [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) `(read-only)`
  - : Returns the parent line item of this line item or null if the line item
      is independent.



---

### position
- position: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the position within the line item container assigned to the ProductLineItem upon its creation, may be
      used as a sort-order.
      
      
      The position is updated in the following way:
      
      - When a ProductLineItem is added to the LineItemCtnr, it is assigned the next available position, based on the  current count
      - When a ProductLineItem is removed from the LineItemCtnr then LineItemCtnr method reassignPositions is called,  so that the 'gap' left by the removed line-item is refilled. This method is dependent on no 2 ProductLineItem  having the same position.
      - When a LineItemCtnr is copied (e.g. when a PlacedOrder is created from a Basket), no special position  handling is necessary as the ProductLineItems are added according to their current position ordering in the  source LineItemCtnr.



---

### priceAdjustments
- priceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns an iterator of price adjustments that have been applied to this
      product line item such as promotions on the purchase price
      (i.e. $10 Off or 10% Off).



---

### product
- product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the product associated with the product line item.
      
      
      The product line item might not be related to an actual catalog product, for example if it represents an option,
      or was not created from a catalog product, or if the product does not exist in the catalog anymore. In these
      cases, the method returns null.


    **See Also:**
    - [isCatalogProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#iscatalogproduct)


---

### productID
- productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the related product.
      
      
      Returns empty if no product is related.


    **See Also:**
    - [isCatalogProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#iscatalogproduct)
    - [getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproduct)


---

### productInventoryList
- productInventoryList: [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)
  - : Returns the inventory list the product line item is associated with. If the
      line item is not associated with a inventory list, or the inventory list does not
      exist, the method returns null.



---

### productInventoryListID
- productInventoryListID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the inventory list the product line item is associated with.


---

### productListItem
- productListItem: [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md) `(read-only)`
  - : Returns the associated ProductListItem.


---

### productName
- productName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the product that was copied when
      product was added to line item container.



---

### proratedPrice
- proratedPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the price of this product line item after considering all
      dependent price adjustments and prorating all Buy-X-Get-Y
      and order-level discounts, according to the scheme described in
      [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). For net pricing the
      net price is returned. For gross pricing, the gross price is returned.



---

### proratedPriceAdjustmentPrices
- proratedPriceAdjustmentPrices: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns a Map of PriceAdjustment to Money instances. They keys to this
      map are the price adjustments that apply to this ProductLineItem either
      directly or indirectly when discounts are prorated according to the
      scheme described in [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices).
      The values in the map are the portion of the adjustment which applies to
      this particular product line item.



---

### qualifyingProductLineItemForBonusProduct
- qualifyingProductLineItemForBonusProduct: [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) `(read-only)`
  - : Returns the ProductLineItem that qualified the basket for this bonus product.
      
      
      This method is only applicable if the product line item is a bonus product line item, and if the promotion is a
      product promotion with number of qualifying products granting a bonus-product discount. If these conditions
      aren't met, the method returns null. If there are multiple product line items that triggered this bonus product,
      this method returns the last one by position within the order.



---

### quantity
- quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity of the product represented by this ProductLineItem.


---

### quantityValue
- quantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the quantity of this ProductLineItem.


---

### relatedBonusProductLineItems
- relatedBonusProductLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all bonus product line items for which this line item is a
      qualifying product line item. This method is usually called when
      rendering the cart so that bonus products can be shown next to the
      products that triggered their creation.



---

### reserved
- reserved: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns if the product line item is reserved.
      
      
      Reservations for the basket can be created with e.g. [Basket.reserveInventory(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventorynumber).
      
      
      Method must only be called for basket product line items. Exception is thrown if called for order product line
      item.



---

### shipment
- shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Returns the associated Shipment.


---

### shippingLineItem
- shippingLineItem: [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md) `(read-only)`
  - : Returns the dependent shipping line item of this line item.
      The shipping line item can define product-specific shipping
      costs for this product line item.



---

### stepQuantity
- stepQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns step quantity allowed for the product represented by the ProductLineItem
      (copied from product on initialization).
      Note: the quantity of a ProductLineItem must obey the limits set by the
      ProductLineItem's attributes 'MinOrderQuantity' and 'StepQuantity', i.e.
      for a 'MinOrderQuantity' of 2.0 and a 'StepQuantity' of 2.5 then values
      2.0, 4.5, 7.0... are allowed values.



---

### stepQuantityValue
- stepQuantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the value portion of getStepQuantity().


---

## Method Details

### createPriceAdjustment(String)
- createPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Creates a product price adjustment.
      
      
      The price adjustment line item is being initialized with the tax class code and tax rate of the product line
      item. The promotion ID is mandatory and must not be the ID of any actual promotion defined in B2C Commerce. If
      there already exists a price adjustment for the same promotionID, an exception is thrown.


    **Parameters:**
    - promotionID - Promotion ID

    **Returns:**
    - The new price adjustment


---

### createPriceAdjustment(String, Discount)
- createPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), discount: [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Creates a product price adjustment representing a specific discount. The price adjustment line item is
      initialized with the tax class code and tax rate of the product line item.
      
      
      The promotion ID is mandatory and must not be the ID of any actual promotion defined in B2C Commerce. If a price
      adjustment already exists for the same promotionID, an exception is thrown.
      
      
      
      
      The possible discounts are [FixedPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceDiscount.md), [AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md),
      [PercentageDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageDiscount.md). Example:
      
      
      
      
      ```
      var myProductItem : dw.order.ProductLineItem; // assume known
      var paFixedUnitPrice100 : dw.order.PriceAdjustment = myProductItem.createPriceAdjustment("myPromotionID1", new FixedPriceDiscount(100.00));
      var paTenPercent : dw.order.PriceAdjustment = myProductItem.createPriceAdjustment("myPromotionID2", new PercentageDiscount(10));
      var paReduceBy20 : dw.order.PriceAdjustment = myProductItem.createPriceAdjustment("myPromotionID3", new AmountDiscount(20.00);
      ```


    **Parameters:**
    - promotionID - Unique custom promotion ID, not null
    - discount - The desired discount, not null

    **Returns:**
    - The new custom price adjustment


---

### createShippingLineItem()
- createShippingLineItem(): [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md)
  - : Creates the dependent shipping line item for this line item.
      The shipping line item can define product-specific shipping
      costs for this product line item.
      This method has replace semantics: If there is an existing
      shipping line item it will be replaced
      with a new shipping line item.


    **Returns:**
    - the created shipping line item


---

### getAdjustedGrossPrice()
- getAdjustedGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the gross price of the product line item after applying all product-level
      adjustments.


    **Returns:**
    - gross price after applying product-level adjustments

    **See Also:**
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustednetprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedprice)


---

### getAdjustedNetPrice()
- getAdjustedNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the net price of the product line item after applying all product-level
      adjustments.


    **Returns:**
    - net price after applying product-level adjustments

    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedgrossprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedprice)


---

### getAdjustedPrice()
- getAdjustedPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price of the product line item after applying all product-level
      adjustments. For net pricing the adjusted net price is returned
      (see [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustednetprice)). For gross pricing, the adjusted
      gross price is returned (see [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedgrossprice)).


    **Returns:**
    - Adjusted net or gross price

    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedgrossprice)
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustednetprice)


---

### getAdjustedPrice(Boolean)
- getAdjustedPrice(applyOrderLevelAdjustments: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price of this product line item after considering all
      dependent price adjustments and optionally prorating all order-level
      price adjustments. For net pricing the net price is returned. For gross
      pricing, the gross price is returned.


    **Parameters:**
    - applyOrderLevelAdjustments - If true, order-level adjustments will             be applied to line item price.

    **Returns:**
    - Adjusted net or gross price

    **See Also:**
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getadjustedprice)


---

### getAdjustedTax()
- getAdjustedTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax of the unit after applying adjustments, in the purchase currency.

    **Returns:**
    - the tax of the unit after applying adjustments, in the purchase currency.


---

### getBonusDiscountLineItem()
- getBonusDiscountLineItem(): [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md)
  - : Returns the parent bonus discount line item of this line item.  Only
      bonus product line items that have been selected by the customer as
      part of a BONUS\_CHOICE discount have one of these.


    **Returns:**
    - the bonus discount line item of this line item or null


---

### getBundledProductLineItems()
- getBundledProductLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing the bundled product line items.

    **Returns:**
    - a collection containing the bundled product line items.


---

### getCategory()
- getCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the category the product line item is associated with. If the
      line item is not associated with a category, or the category does not
      exist in the site catalog, the method returns null.


    **Returns:**
    - Category or null


---

### getCategoryID()
- getCategoryID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the category the product line item is associated with.

    **Returns:**
    - Category ID or null.


---

### getExternalLineItemStatus()
- getExternalLineItemStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for the external line item status
      or null if no value set.


    **Returns:**
    - the value set for the external line item status
      or null if no value set.



---

### getExternalLineItemText()
- getExternalLineItemText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for the external line item text
      or null if no value set.


    **Returns:**
    - the value set for the external line item text
      or null if no value set.



---

### getGiftMessage()
- getGiftMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for gift message or null if no value set.

    **Returns:**
    - the value set for gift message or null if no value set.


---

### getManufacturerName()
- getManufacturerName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the manfacturer of the product.

    **Returns:**
    - The name of the manfacturer of the product.


---

### getManufacturerSKU()
- getManufacturerSKU(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the manfacturer's SKU of this product line item.

    **Returns:**
    - the name of the manfacturer's SKU of this product line item.


---

### getMinOrderQuantity()
- getMinOrderQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the minimal order quantity allowed for the product represented by the
      ProductLineItem (copied from product on initialization).
      Note: the quantity of a ProductLineItem must obey the limits set by the
      ProductLineItem's attributes 'MinOrderQuantity' and 'StepQuantity', i.e.
      for a 'MinOrderQuantity' of 2.0 and a 'StepQuantity' of 2.5 then values
      2.0, 4.5, 7.0... are allowed values.


    **Returns:**
    - the minimal order quantity allowed for the product.


---

### getMinOrderQuantityValue()
- getMinOrderQuantityValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the value portion of getMinOrderQuantity().

    **Returns:**
    - the minimal order quantity value allowed for the product.


---

### getOptionID()
- getOptionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product option this product line item
      represents. If the product line item does not represent an option,
      null is returned.


    **Returns:**
    - the ID of the product option this product line item represents.


---

### getOptionModel()
- getOptionModel(): [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)
  - : Returns the product option model for a product line item representing an option product.
      
      
      The returned option model has preselected values based on the dependent option line items of this product line
      item. Null is returned if this line item does not represent an option product.


    **Returns:**
    - the product option model for a product line item representing an option product.


---

### getOptionProductLineItems()
- getOptionProductLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing option product line items.

    **Returns:**
    - a collection containing option product line items.


---

### getOptionValueID()
- getOptionValueID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product option value this product line item
      represents. If the product line item does not represent an option,
      null is returned.


    **Returns:**
    - the ID of the product option value this product line item represents.


---

### getOrderItem()
- getOrderItem(): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)
  - : Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or null. An order-item
      extension will only exist for a ProductLineItem which belongs to an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - null or the order-item extension


---

### getParent()
- getParent(): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
  - : Returns the parent line item of this line item or null if the line item
      is independent.


    **Returns:**
    - the parent line item of this line item or null if the line item
      is independent.



---

### getPosition()
- getPosition(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the position within the line item container assigned to the ProductLineItem upon its creation, may be
      used as a sort-order.
      
      
      The position is updated in the following way:
      
      - When a ProductLineItem is added to the LineItemCtnr, it is assigned the next available position, based on the  current count
      - When a ProductLineItem is removed from the LineItemCtnr then LineItemCtnr method reassignPositions is called,  so that the 'gap' left by the removed line-item is refilled. This method is dependent on no 2 ProductLineItem  having the same position.
      - When a LineItemCtnr is copied (e.g. when a PlacedOrder is created from a Basket), no special position  handling is necessary as the ProductLineItems are added according to their current position ordering in the  source LineItemCtnr.


    **Returns:**
    - the position within the line item container assigned to the ProductLineItem upon its creation.


---

### getPriceAdjustmentByPromotionID(String)
- getPriceAdjustmentByPromotionID(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Returns the first price adjustment associated to the specified promotion ID. It is highly recommended to use
      [getPriceAdjustmentsByPromotionID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getpriceadjustmentsbypromotionidstring) instead. If there are multiple price adjustments for the same
      promotion, this method will return the first found. Alternatively, to uniquely identify a price adjustment using
      its promotion id and coupon code, use [getPriceAdjustmentByPromotionIDAndCouponCode(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getpriceadjustmentbypromotionidandcouponcodestring-string)


    **Parameters:**
    - promotionID - Promotion id

    **Returns:**
    - The price adjustment associated with the promotion ID or null


---

### getPriceAdjustmentByPromotionIDAndCouponCode(String, String)
- getPriceAdjustmentByPromotionIDAndCouponCode(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), couponCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Returns the price adjustment associated to the specified promotion ID and coupon code combination.

    **Parameters:**
    - promotionID - Promotion id
    - couponCode - the code of the coupon used to apply the promotion, or null if the promotion is not coupon             based.

    **Returns:**
    - The price adjustment associated with the promotion ID and coupon code combination, or null


---

### getPriceAdjustments()
- getPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an iterator of price adjustments that have been applied to this
      product line item such as promotions on the purchase price
      (i.e. $10 Off or 10% Off).


    **Returns:**
    - a collection of price adjustments that have been applied to this
      product line item.



---

### getPriceAdjustmentsByPromotionID(String)
- getPriceAdjustmentsByPromotionID(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of price adjustments associated to the specified promotion ID. If only one coupon code is
      allowed per order, then the collection should only ever have a single entry in it. The multiple coupon code
      feature can cause multiple price adjustments to be returned.


    **Parameters:**
    - promotionID - Promotion id

    **Returns:**
    - The collection of price adjustments associated with the promotion ID or null if the promotionID was null.
              If there are no price adjustments for the passed promotion, the collection will be empty.



---

### getProduct()
- getProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the product associated with the product line item.
      
      
      The product line item might not be related to an actual catalog product, for example if it represents an option,
      or was not created from a catalog product, or if the product does not exist in the catalog anymore. In these
      cases, the method returns null.


    **Returns:**
    - the product of the line item, or null

    **See Also:**
    - [isCatalogProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#iscatalogproduct)


---

### getProductID()
- getProductID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the related product.
      
      
      Returns empty if no product is related.


    **Returns:**
    - the ID of the related product.

    **See Also:**
    - [isCatalogProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#iscatalogproduct)
    - [getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproduct)


---

### getProductInventoryList()
- getProductInventoryList(): [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)
  - : Returns the inventory list the product line item is associated with. If the
      line item is not associated with a inventory list, or the inventory list does not
      exist, the method returns null.


    **Returns:**
    - ProductInventoryList or null


---

### getProductInventoryListID()
- getProductInventoryListID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the inventory list the product line item is associated with.

    **Returns:**
    - ProductInventoryList ID or null.


---

### getProductListItem()
- getProductListItem(): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Returns the associated ProductListItem.

    **Returns:**
    - item or null.


---

### getProductName()
- getProductName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the product that was copied when
      product was added to line item container.


    **Returns:**
    - the name of the product.


---

### getProratedPrice()
- getProratedPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price of this product line item after considering all
      dependent price adjustments and prorating all Buy-X-Get-Y
      and order-level discounts, according to the scheme described in
      [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). For net pricing the
      net price is returned. For gross pricing, the gross price is returned.


    **Returns:**
    - Adjusted and prorated net or gross price


---

### getProratedPriceAdjustmentPrices()
- getProratedPriceAdjustmentPrices(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a Map of PriceAdjustment to Money instances. They keys to this
      map are the price adjustments that apply to this ProductLineItem either
      directly or indirectly when discounts are prorated according to the
      scheme described in [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices).
      The values in the map are the portion of the adjustment which applies to
      this particular product line item.


    **Returns:**
    - Map of PriceAdjustment to Money instances, representing the
              prorated adjustments applied to this ProductLineItem.



---

### getQualifyingProductLineItemForBonusProduct()
- getQualifyingProductLineItemForBonusProduct(): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
  - : Returns the ProductLineItem that qualified the basket for this bonus product.
      
      
      This method is only applicable if the product line item is a bonus product line item, and if the promotion is a
      product promotion with number of qualifying products granting a bonus-product discount. If these conditions
      aren't met, the method returns null. If there are multiple product line items that triggered this bonus product,
      this method returns the last one by position within the order.


    **Returns:**
    - the ProductLineItem that qualified the basket for this bonus product. Returns null if this is not a bonus
              product, or if there was no distinct qualifying product.



---

### getQuantity()
- getQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of the product represented by this ProductLineItem.

    **Returns:**
    - the quantity of the product.


---

### getQuantityValue()
- getQuantityValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value of the quantity of this ProductLineItem.

    **Returns:**
    - quantity value of product line item


---

### getRelatedBonusProductLineItems()
- getRelatedBonusProductLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all bonus product line items for which this line item is a
      qualifying product line item. This method is usually called when
      rendering the cart so that bonus products can be shown next to the
      products that triggered their creation.


    **Returns:**
    - the bonus product line items triggered by the addition of this
              product to the cart.



---

### getShipment()
- getShipment(): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Returns the associated Shipment.

    **Returns:**
    - The shipment of the product line item


---

### getShippingLineItem()
- getShippingLineItem(): [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md)
  - : Returns the dependent shipping line item of this line item.
      The shipping line item can define product-specific shipping
      costs for this product line item.


    **Returns:**
    - the shipping line item of this line item or null


---

### getStepQuantity()
- getStepQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns step quantity allowed for the product represented by the ProductLineItem
      (copied from product on initialization).
      Note: the quantity of a ProductLineItem must obey the limits set by the
      ProductLineItem's attributes 'MinOrderQuantity' and 'StepQuantity', i.e.
      for a 'MinOrderQuantity' of 2.0 and a 'StepQuantity' of 2.5 then values
      2.0, 4.5, 7.0... are allowed values.


    **Returns:**
    - step quantity allowed for the product.


---

### getStepQuantityValue()
- getStepQuantityValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Return the value portion of getStepQuantity().

    **Returns:**
    - step quantity value allowed for the product.


---

### isBonusProductLineItem()
- isBonusProductLineItem(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the product line item represents a bonus line item.

    **Returns:**
    - true if the product line item represents a bonus
      line item, false otherwise.



---

### isBundledProductLineItem()
- isBundledProductLineItem(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the product line item represents a bundled line item.

    **Returns:**
    - true if the product line item represents a bundled line item.


---

### isCatalogProduct()
- isCatalogProduct(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the product line item represents a catalog product.
      
      
      That flag is determined during product line item creation with
      [LineItemCtnr.createProductLineItem(String, Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createproductlineitemstring-shipment), stored at the line item container and can
      be accessed as productLineItem.catalogProduct. It represents what can be evaluated with
      
      
      ```
      dw.catalog.ProductMgr.getProduct( productID ) != null
          && dw.catalog.ProductMgr.getProduct( productID ).isAssignedToSiteCatalog()
      ```
      
      
      If the product is not available during product line item creation it is considered a non catalog product line item without
      connection to a product.


    **Returns:**
    - true if product line item represents catalog product, otherwise false

    **See Also:**
    - [getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getproduct)


---

### isGift()
- isGift(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this line item represents a gift, false otherwise.

    **Returns:**
    - true if this line item represents a gift, false otherwise.


---

### isOptionProductLineItem()
- isOptionProductLineItem(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the product line item represents an option line item.
      Option line items do not represent true products but rather options of
      products.  An option line item always has a parent product line item
      representing a true product.


    **Returns:**
    - true if the product line item represents an option
      line item, false otherwise.



---

### isReserved()
- isReserved(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if the product line item is reserved.
      
      
      Reservations for the basket can be created with e.g. [Basket.reserveInventory(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md#reserveinventorynumber).
      
      
      Method must only be called for basket product line items. Exception is thrown if called for order product line
      item.


    **Returns:**
    - true if line item is reserved, false otherwise.


---

### removePriceAdjustment(PriceAdjustment)
- removePriceAdjustment(priceAdjustmentLineItem: [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)): void
  - : Removes the specified price adjustment from the product line item.

    **Parameters:**
    - priceAdjustmentLineItem - The price adjustment to remove


---

### removeShippingLineItem()
- removeShippingLineItem(): void
  - : Removes the dependent shipping line item for this line item.


---

### replaceProduct(Product)
- replaceProduct(newProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): void
  - : Replaces the current product of the product line item with the product specified in parameter _newProduct_.
      
      
      The following rules apply:
      
      - Preserve line item attributes UUID, Quantity, CategoryID, ExternalLineItemStatus, ExternalLineItemText,  isGift, GiftMessage, Position, Parent, Shipment
      - Replace product-specific attributes ProductID, ProductName, MinOrderQuantity, StepQuantity, ManufacturerName,  ManufacturerSKU
      - Remove all price adjustments related to the product line item
      - Remove the shipping line item related to the product line item
      - Remove all bundled line items of current product, and add bundled line items if new product is a bundle
      - Remove all option line items of current product, and add option line items if new product is an option  product; use default option selections
      - Set all price attributes to N/A
      - Preserve all custom attributes of line item, but override order-required attributes with values from new  product
      
      
      
      
      
      The primary use is to replace one variation product with another, without having to both create a new line item
      for the replacement and remove the line item for the replaced product.


    **Parameters:**
    - newProduct - The new product of the product line item


---

### setCategory(Category)
- setCategory(category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): void
  - : Sets the specified category as the product line item category context.

    **Parameters:**
    - category - Category instance or null


---

### setCategoryID(String)
- setCategoryID(categoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the ID of the category the product line item is associated with.

    **Parameters:**
    - categoryID - the Category ID or null.


---

### setExternalLineItemStatus(String)
- setExternalLineItemStatus(status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value to set for the external line item status.

    **Parameters:**
    - status - the value to set for the external line item status.


---

### setExternalLineItemText(String)
- setExternalLineItemText(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value to set for the external line item text.

    **Parameters:**
    - text - the value to set for the external line item text.


---

### setGift(Boolean)
- setGift(isGift: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Controls if this line item is a gift or not.

    **Parameters:**
    - isGift - set to true if you want this line item to  represent a gift.


---

### setGiftMessage(String)
- setGiftMessage(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value to set for the gift message.

    **Parameters:**
    - message - the value to set for the gift message.


---

### setManufacturerName(String)
- setManufacturerName(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the manufacturer of this product.

    **Parameters:**
    - name - The name of the manfacturer of this product


---

### setManufacturerSKU(String)
- setManufacturerSKU(sku: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the SKU of the manufacturer of this product.

    **Parameters:**
    - sku - The SKU of the manfacturer of this product


---

### setMinOrderQuantityValue(Number)
- setMinOrderQuantityValue(quantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the minimum order quantity value for this object.
      
      
      This will be used to validate and adjust quantities when setQuantityValue() is called. For typical catalog
      product line items, it is usually desirable to have this value inherited from the product attributes, but for
      non-catalog products, it is sometimes desirable to set this value programmatically.
      
      
      
      
      Null is accepted and represents Quantity.NA. Otherwise, the quantity value must be > 0.


    **Parameters:**
    - quantityValue - The minimal order quantity allowed for the product or null.


---

### setPosition(Number)
- setPosition(aValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the position within the line item container. This value may be used as a sort-order.
      
      
      The position is updated in the following way:
      
      - When a ProductLineItem is added to the LineItemCtnr, it is assigned the next available position, based on the  current count
      - When a ProductLineItem is removed from the LineItemCtnr then LineItemCtnr method reassignPositions is called,  so that the 'gap' left by the removed line-item is refilled. This method is dependent on no 2 ProductLineItem  having the same position.
      - When a LineItemCtnr is copied (e.g. when an Order is created from a Basket), no special position handling is  necessary as the ProductLineItems are added according to their current position ordering in the source  LineItemCtnr.


    **Parameters:**
    - aValue - the position within the line item container.


---

### setPriceValue(Number)
- setPriceValue(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets price attributes of the line item based on the current
      purchase currency, taxation policy and line item quantity.
      
      
      The method sets the 'basePrice' attribute of the line item.
      Additionally, it sets the 'netPrice' attribute of the line item
      if the current taxation policy is 'net', and the 'grossPrice'
      attribute, if the current taxation policy is 'gross'. The
      'netPrice'/'grossPrice' attributes are set by multiplying the
      specified price value with the line item quantity.
      
      
      
      
      If null is specified as value, the price attributes are reset to
      Money.NA.


    **Parameters:**
    - value - Price value or null


---

### setProductInventoryList(ProductInventoryList)
- setProductInventoryList(productInventoryList: [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)): void
  - : Sets the specified inventory list as the product line item inventory context.

    **Parameters:**
    - productInventoryList - ProductInventoryList instance or null


---

### setProductInventoryListID(String)
- setProductInventoryListID(productInventoryListID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the ID of the inventory list the product line item is associated with.

    **Parameters:**
    - productInventoryListID - the ProductInventoryList ID or null.


---

### setProductName(String)
- setProductName(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the name of the product.

    **Parameters:**
    - aValue - the name of the product.


---

### setQuantityValue(Number)
- setQuantityValue(quantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Updates the quantity value of the product line item.
      
      
      Validates the specified quantity value against the line item's min order and step quantity and adjusts it if
      necessary. In particular, if 0 is passed, then the value will be adjusted to the min order quantity, not removed
      from the line item container.
      
      
      
      
      Null values or values < 0.0 are not accepted.


    **Parameters:**
    - quantityValue - Quantity value.


---

### setShipment(Shipment)
- setShipment(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): void
  - : Associates the specified product line item with the specified shipment.
      
      
      The method is only applicable for independent product line items. If called for any dependent line item (option
      or bundled line item), the method will throw an exception. The shipment for all dependent line items will be
      updated automatically by the method. Product line item and shipment must belong to the same line item ctnr.


    **Parameters:**
    - shipment - The new shipment of the product line item


---

### setStepQuantityValue(Number)
- setStepQuantityValue(quantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the step quantity value for this object.
      
      
      This will be used to validate and adjust quantities when updateQuantity() is called. For typical catalog product
      line items, it is usually desirable to have this value inherited from the product attributes, but for non-catalog
      products, it is sometimes desirable to set this value programmatically.
      
      
      
      
      Null is accepted and represents Quantity.NA. Otherwise, the quantity value must be > 0.


    **Parameters:**
    - quantityValue - The minimal order quantity allowed for the product or null.


---

### updateOptionPrice()
- updateOptionPrice(): void
  - : Determines and sets the price of a option line item based on the selected option value this line item represents.


---

### updateOptionValue(ProductOptionValue)
- updateOptionValue(optionValue: [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)): void
  - : Updates an option line item with a new option value.
      
      This method will not do anything if the current line item is no
      option line item, if the specified value does not exist for the
      current option or if this value is already selected.
      
      Note, that this method will update the attributes optionValueID,
      productID, productName and lineItemText. It will not update the price
      attributes of the line item. To update the price of the line item you
      need to call [updateOptionPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#updateoptionprice) in addition. This is
      usually done during calculation in the calculate hook.


    **Parameters:**
    - optionValue - The value to update the option line item with


---

### updatePrice(Money)
- ~~updatePrice(price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void~~
  - : Updates the price attributes of the line item based
      on the specified price.  The base price is set to the specified
      value.  If the line item is based on net pricing then the net price
      attribute is set.  If the line item is based on  gross pricing then the
      gross price attribute is set.  Whether or not a line item is based
      on net or gross pricing is a site-wide configuration parameter.
      In either case, this price is equal to the product of the base price
      and the quantity of this line item in its container.


    **Parameters:**
    - price - The price to use when performing the update.  This price               must not be null and must either be equal to NOT\_AVAIALBLE               or must have a currency code equal to that of the parent               container.

    **Deprecated:**
**warning:** Use [setPriceValue(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setpricevaluenumber)

---

### updateQuantity(Number)
- ~~updateQuantity(quantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~
  - : Updates the quantity value of the product line item and all its dependent product line items.
      
      
      Validates the specified quantity value against the line item's min order and step quantity and adjusts it if
      necessary. The adjusted quantity value is returned.
      
      
      
      
      In general, quantity values < 0.0 are not accepted.


    **Parameters:**
    - quantityValue - Numeric quantity value.

    **Returns:**
    - Adjusted quantity value

    **Deprecated:**
**warning:** Use [setQuantityValue(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#setquantityvaluenumber) followed by [getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getquantity) instead.

---

<!-- prettier-ignore-end -->

<!-- document id=14bca63e9d8f99a25dfafbe99cf6814ea0bb0e02f4575ed9c5dc92d1e9f0f6ea url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductLink.md -->

<!-- prettier-ignore-start -->
# Class ProductLink

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductLink.md)

The class represents a link between two products.


## Constant Summary

| Constant | Description |
| --- | --- |
| [LINKTYPE_ACCESSORY](#linktype_accessory): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Represents an accessory product link. |
| [LINKTYPE_ALT_ORDERUNIT](#linktype_alt_orderunit): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | Represents an alternative order unit product link. |
| [LINKTYPE_CROSS_SELL](#linktype_cross_sell): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Represents a cross-sell product link. |
| [LINKTYPE_NEWER_VERSION](#linktype_newer_version): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Represents a newer verion link. |
| [LINKTYPE_OTHER](#linktype_other): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | Represents a miscellaneous product link. |
| [LINKTYPE_REPLACEMENT](#linktype_replacement): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Represents a replacement product link. |
| [LINKTYPE_SPARE_PART](#linktype_spare_part): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | Represents a spare part product link. |
| [LINKTYPE_UP_SELL](#linktype_up_sell): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | Represents an up-sell product link. |

## Property Summary

| Property | Description |
| --- | --- |
| [sourceProduct](#sourceproduct): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the source product for this link. |
| [targetProduct](#targetproduct): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the target product for this link. |
| [typeCode](#typecode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the type of this link (see constants). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSourceProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductLink.md#getsourceproduct)() | Returns the source product for this link. |
| [getTargetProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductLink.md#gettargetproduct)() | Returns the target product for this link. |
| [getTypeCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductLink.md#gettypecode)() | Returns the type of this link (see constants). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### LINKTYPE_ACCESSORY

- LINKTYPE_ACCESSORY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Represents an accessory product link.


---

### LINKTYPE_ALT_ORDERUNIT

- LINKTYPE_ALT_ORDERUNIT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : Represents an alternative order unit product link.


---

### LINKTYPE_CROSS_SELL

- LINKTYPE_CROSS_SELL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Represents a cross-sell product link.


---

### LINKTYPE_NEWER_VERSION

- LINKTYPE_NEWER_VERSION: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Represents a newer verion link.


---

### LINKTYPE_OTHER

- LINKTYPE_OTHER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : Represents a miscellaneous product link.


---

### LINKTYPE_REPLACEMENT

- LINKTYPE_REPLACEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Represents a replacement product link.


---

### LINKTYPE_SPARE_PART

- LINKTYPE_SPARE_PART: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : Represents a spare part product link.


---

### LINKTYPE_UP_SELL

- LINKTYPE_UP_SELL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : Represents an up-sell product link.


---

## Property Details

### sourceProduct
- sourceProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the source product for this link.


---

### targetProduct
- targetProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the target product for this link.


---

### typeCode
- typeCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the type of this link (see constants).


---

## Method Details

### getSourceProduct()
- getSourceProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the source product for this link.

    **Returns:**
    - the source product for this link.


---

### getTargetProduct()
- getTargetProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the target product for this link.

    **Returns:**
    - the target product for this link.


---

### getTypeCode()
- getTypeCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the type of this link (see constants).

    **Returns:**
    - the type of the link.


---

<!-- prettier-ignore-end -->

<!-- document id=36e06d87404d20903fd76ea53db7055e31c54f0e2d459d24c8ea503ec3dd6a68 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.ProductList.md -->

<!-- prettier-ignore-start -->
# Class ProductList

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)

Represents a list of products (and optionally a gift certificate) that is
typically maintained by a customer.  This class can be used to implement
a number of different storefront features, e.g. shopping list, wish list and gift registry.
A product list is always owned by a customer. The owner can be anonymous or a registered customer.
The owner can be the person for which items from that list will be purchased (wish list).
Or it can be a person who maintains the list, for example a gift registry, on behalf of the bridal couple.
Each product list can have a registrant and a co-registrant. A registrant is typically associated with an event related product list
such as a gift registry. It holds information about a person associated with the
event such as a bride or groom.
A shipping address can be associated with this product list to ship the items,
e.g. to an event location. A post-event shipping address can be associated to
ship items to which could not be delivered on event date.
The product list can also hold information about the event date and event location.



## Constant Summary

| Constant | Description |
| --- | --- |
| [EXPORT_STATUS_EXPORTED](#export_status_exported): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Constant for when Export Status is Exported |
| [EXPORT_STATUS_NOTEXPORTED](#export_status_notexported): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Constant for when Export Status is Not Exported |
| [TYPE_CUSTOM_1](#type_custom_1): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 100 | Constant representing a custom list type attribute. |
| [TYPE_CUSTOM_2](#type_custom_2): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 101 | Constant representing a custom list type attribute. |
| [TYPE_CUSTOM_3](#type_custom_3): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 102 | Constant representing a custom list type attribute. |
| [TYPE_GIFT_REGISTRY](#type_gift_registry): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11 | Constant representing the gift registry type attribute. |
| [TYPE_SHOPPING_LIST](#type_shopping_list): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12 | Constant representing the shopping list type attribute. |
| [TYPE_WISH_LIST](#type_wish_list): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | Constant representing the wish list registry type attribute. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique system generated ID of the object. |
| [anonymous](#anonymous): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this product list is owned by an anonymous customer. |
| [coRegistrant](#coregistrant): [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md) `(read-only)` | Returns the ProductListRegistrant assigned to the coRegistrant attribute or null  if this list has no co-registrant. |
| [currentShippingAddress](#currentshippingaddress): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md) `(read-only)` | This is a helper method typically used with an event related list. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns a description text that, for example, explains the purpose of this product list. |
| [eventCity](#eventcity): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | For event related uses (e.g. |
| [eventCountry](#eventcountry): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | For event related uses (e.g. |
| [eventDate](#eventdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | For event related uses (e.g. |
| [eventState](#eventstate): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | For event related uses (e.g. |
| [eventType](#eventtype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | For event related uses (e.g. |
| [exportStatus](#exportstatus): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | Returns the export status of the product list.<br/>  Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_notexported),  [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_exported). |
| [giftCertificateItem](#giftcertificateitem): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md) `(read-only)` | Returns the item in the list that represents a gift certificate. |
| [items](#items): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing all items in the list. |
| [lastExportTime](#lastexporttime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date where this product list has been exported successfully  the last time. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the name of this product list given by its owner. |
| [owner](#owner): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)` | Returns the customer that created and owns the product list. |
| [postEventShippingAddress](#posteventshippingaddress): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md) | Returns the shipping address for purchases made after the event date. |
| [productItems](#productitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing all items in the list that reference products. |
| [public](#public): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | A flag, typically used to determine if the object is searchable  by other customers. |
| [publicItems](#publicitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing all items in the list that are flagged as public. |
| [purchases](#purchases): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the aggregated purchases from all the individual items. |
| [registrant](#registrant): [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md) `(read-only)` | Returns the ProductListRegistrant assigned to the registrant attribute or null  if this list has no registrant. |
| [shippingAddress](#shippingaddress): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md) | Return the address that should be used as the shipping address for purchases  made from the list. |
| [type](#type): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns an int representing the type of object (e.g. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createCoRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#createcoregistrant)() | Create a ProductListRegistrant and assign it to the coRegistrant attribute  of the list. |
| [createGiftCertificateItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#creategiftcertificateitem)() | Create an item in the list that represents a gift certificate. |
| [createProductItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#createproductitemproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Create an item in the list that references the specified product. |
| [createRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#createregistrant)() | Create a ProductListRegistrant and assign it to the registrant attribute  of the list. |
| [getCoRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getcoregistrant)() | Returns the ProductListRegistrant assigned to the coRegistrant attribute or null  if this list has no co-registrant. |
| [getCurrentShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getcurrentshippingaddress)() | This is a helper method typically used with an event related list. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getdescription)() | Returns a description text that, for example, explains the purpose of this product list. |
| [getEventCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#geteventcity)() | For event related uses (e.g. |
| [getEventCountry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#geteventcountry)() | For event related uses (e.g. |
| [getEventDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#geteventdate)() | For event related uses (e.g. |
| [getEventState](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#geteventstate)() | For event related uses (e.g. |
| [getEventType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#geteventtype)() | For event related uses (e.g. |
| [getExportStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getexportstatus)() | Returns the export status of the product list.<br/>  Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_notexported),  [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_exported). |
| [getGiftCertificateItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getgiftcertificateitem)() | Returns the item in the list that represents a gift certificate. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getid)() | Returns the unique system generated ID of the object. |
| [getItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the item from the list that has the specified ID. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getitems)() | Returns a collection containing all items in the list. |
| [getLastExportTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getlastexporttime)() | Returns the date where this product list has been exported successfully  the last time. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getname)() | Returns the name of this product list given by its owner. |
| [getOwner](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getowner)() | Returns the customer that created and owns the product list. |
| [getPostEventShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getposteventshippingaddress)() | Returns the shipping address for purchases made after the event date. |
| [getProductItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getproductitems)() | Returns a collection containing all items in the list that reference products. |
| [getPublicItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getpublicitems)() | Returns a collection containing all items in the list that are flagged as public. |
| [getPurchases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getpurchases)() | Returns the aggregated purchases from all the individual items. |
| [getRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getregistrant)() | Returns the ProductListRegistrant assigned to the registrant attribute or null  if this list has no registrant. |
| [getShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#getshippingaddress)() | Return the address that should be used as the shipping address for purchases  made from the list. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#gettype)() | Returns an int representing the type of object (e.g. |
| [isAnonymous](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#isanonymous)() | Returns true if this product list is owned by an anonymous customer. |
| [isPublic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#ispublic)() | A flag, typically used to determine if the object is searchable  by other customers. |
| [removeCoRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#removecoregistrant)() | Removes the ProductListRegistrant assigned to the coRegistrant attribute. |
| [removeItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#removeitemproductlistitem)([ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)) | Removes the specified item from the list. |
| [removeRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#removeregistrant)() | Removes the ProductListRegistrant assigned to the registrant attribute. |
| [setDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#setdescriptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the description of this product list. |
| [setEventCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#seteventcitystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the event city to which this product list is related. |
| [setEventCountry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#seteventcountrystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the event country to which this product list is related. |
| [setEventDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#seteventdatedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Set the date of the event to which this product list is related. |
| [setEventState](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#seteventstatestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the event state to which this product list is related. |
| [setEventType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#seteventtypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the event type for which this product list was created by the owner. |
| [setName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#setnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the name of this product list. |
| [setPostEventShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#setposteventshippingaddresscustomeraddress)([CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)) | This is typically used by an event related list (e.g. |
| [setPublic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#setpublicboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Makes this product list visible to other customers or hides it. |
| [setShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#setshippingaddresscustomeraddress)([CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)) | Associate an address, used as the shipping address for purchases  made from the list. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### EXPORT_STATUS_EXPORTED

- EXPORT_STATUS_EXPORTED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Constant for when Export Status is Exported


---

### EXPORT_STATUS_NOTEXPORTED

- EXPORT_STATUS_NOTEXPORTED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Constant for when Export Status is Not Exported


---

### TYPE_CUSTOM_1

- TYPE_CUSTOM_1: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 100
  - : Constant representing a custom list type attribute.


---

### TYPE_CUSTOM_2

- TYPE_CUSTOM_2: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 101
  - : Constant representing a custom list type attribute.


---

### TYPE_CUSTOM_3

- TYPE_CUSTOM_3: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 102
  - : Constant representing a custom list type attribute.


---

### TYPE_GIFT_REGISTRY

- TYPE_GIFT_REGISTRY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11
  - : Constant representing the gift registry type attribute.


---

### TYPE_SHOPPING_LIST

- TYPE_SHOPPING_LIST: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12
  - : Constant representing the shopping list type attribute.


---

### TYPE_WISH_LIST

- TYPE_WISH_LIST: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : Constant representing the wish list registry type attribute.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique system generated ID of the object.


---

### anonymous
- anonymous: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this product list is owned by an anonymous customer.


---

### coRegistrant
- coRegistrant: [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md) `(read-only)`
  - : Returns the ProductListRegistrant assigned to the coRegistrant attribute or null
      if this list has no co-registrant.



---

### currentShippingAddress
- currentShippingAddress: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md) `(read-only)`
  - : This is a helper method typically used with an event related list.
      It provides the appropriate shipping address based on the eventDate.
      If the current date is after the eventDate, then the postEventShippingAddress
      is returned, otherwise the shippingAddress is returned.  If the eventDate
      is null, then null is returned.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a description text that, for example, explains the purpose of this product list.


---

### eventCity
- eventCity: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the event city.


---

### eventCountry
- eventCountry: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the event country.


---

### eventDate
- eventDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : For event related uses (e.g. gift registry), this holds the date
      of the event.



---

### eventState
- eventState: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the event state.


---

### eventType
- eventType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the type
      of event, e.g. Wedding, Baby Shower.



---

### exportStatus
- exportStatus: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : Returns the export status of the product list.
      
      Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_notexported),
      [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_exported).



---

### giftCertificateItem
- giftCertificateItem: [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md) `(read-only)`
  - : Returns the item in the list that represents a gift certificate.


---

### items
- items: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing all items in the list.


---

### lastExportTime
- lastExportTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date where this product list has been exported successfully
      the last time.



---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of this product list given by its owner.


---

### owner
- owner: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)`
  - : Returns the customer that created and owns the product list.


---

### postEventShippingAddress
- postEventShippingAddress: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Returns the shipping address for purchases made after the event date.


---

### productItems
- productItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing all items in the list that reference products.


---

### public
- public: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : A flag, typically used to determine if the object is searchable
      by other customers.



---

### publicItems
- publicItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing all items in the list that are flagged as public.


---

### purchases
- purchases: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the aggregated purchases from all the individual items.


---

### registrant
- registrant: [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md) `(read-only)`
  - : Returns the ProductListRegistrant assigned to the registrant attribute or null
      if this list has no registrant.



---

### shippingAddress
- shippingAddress: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Return the address that should be used as the shipping address for purchases
      made from the list.



---

### type
- type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns an int representing the type of object (e.g. wish list,
      gift registry). This is set at object creation time.



---

## Method Details

### createCoRegistrant()
- createCoRegistrant(): [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md)
  - : Create a ProductListRegistrant and assign it to the coRegistrant attribute
      of the list.  An exception is thrown if the list already has a coRegistrant
      assigned to it.


    **Returns:**
    - the created ProductListRegistrant instance.

    **Throws:**
    - CreateException - if one already exists


---

### createGiftCertificateItem()
- createGiftCertificateItem(): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Create an item in the list that represents a gift certificate.
      A list may only contain a single gift certificate, so an exception
      is thrown if one already exists in the list.


    **Returns:**
    - the created item.

    **Throws:**
    - CreateException - if a gift certificate item already exists in the list.


---

### createProductItem(Product)
- createProductItem(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Create an item in the list that references the specified product.

    **Parameters:**
    - product - the product to use to create the list item.

    **Returns:**
    - the created item.


---

### createRegistrant()
- createRegistrant(): [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md)
  - : Create a ProductListRegistrant and assign it to the registrant attribute
      of the list.  An exception is thrown if the list already has a registrant
      assigned to it.


    **Returns:**
    - the created ProductListRegistrant instance.

    **Throws:**
    - CreateException - if one already exists


---

### getCoRegistrant()
- getCoRegistrant(): [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md)
  - : Returns the ProductListRegistrant assigned to the coRegistrant attribute or null
      if this list has no co-registrant.


    **Returns:**
    - the ProductListRegistrant assigned to the coRegistrant attribute or null
      if this list has no co-registrant.



---

### getCurrentShippingAddress()
- getCurrentShippingAddress(): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : This is a helper method typically used with an event related list.
      It provides the appropriate shipping address based on the eventDate.
      If the current date is after the eventDate, then the postEventShippingAddress
      is returned, otherwise the shippingAddress is returned.  If the eventDate
      is null, then null is returned.


    **Returns:**
    - the appropriate address, as described above.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a description text that, for example, explains the purpose of this product list.

    **Returns:**
    - a description text explaining the purpose of this product list.
      Returns an empty string if the description is not set.



---

### getEventCity()
- getEventCity(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the event city.

    **Returns:**
    - the event city. The event city or an empty string if no event city is set.


---

### getEventCountry()
- getEventCountry(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the event country.

    **Returns:**
    - the event country. The event country or an empty string if no event country is set.


---

### getEventDate()
- getEventDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : For event related uses (e.g. gift registry), this holds the date
      of the event.


    **Returns:**
    - the date of the event.


---

### getEventState()
- getEventState(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the event state.

    **Returns:**
    - the event state. The event state or an empty string if no event state is set.


---

### getEventType()
- getEventType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : For event related uses (e.g. gift registry), this holds the type
      of event, e.g. Wedding, Baby Shower.


    **Returns:**
    - the type of event. Returns an empty string, if not set.


---

### getExportStatus()
- getExportStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the export status of the product list.
      
      Possible values are: [EXPORT_STATUS_NOTEXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_notexported),
      [EXPORT_STATUS_EXPORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#export_status_exported).


    **Returns:**
    - Product list export status


---

### getGiftCertificateItem()
- getGiftCertificateItem(): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Returns the item in the list that represents a gift certificate.

    **Returns:**
    - the gift certificate item, or null if it doesn't exist.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique system generated ID of the object.

    **Returns:**
    - the ID of object.


---

### getItem(String)
- getItem(ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Returns the item from the list that has the specified ID.

    **Parameters:**
    - ID - the product list item identifier.

    **Returns:**
    - the specified item, or null if it's not found in the list.


---

### getItems()
- getItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing all items in the list.

    **Returns:**
    - all items.


---

### getLastExportTime()
- getLastExportTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date where this product list has been exported successfully
      the last time.


    **Returns:**
    - The time of the last successful export or null if this product list
      was not exported yet.



---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of this product list given by its owner.

    **Returns:**
    - the name of this product list. Returns an empty string if the name is not set.


---

### getOwner()
- getOwner(): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer that created and owns the product list.

    **Returns:**
    - Owning customer


---

### getPostEventShippingAddress()
- getPostEventShippingAddress(): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Returns the shipping address for purchases made after the event date.

    **Returns:**
    - the shipping address for purchases made after the event date.
      Returns null if no post-event shipping address is associated.



---

### getProductItems()
- getProductItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing all items in the list that reference products.

    **Returns:**
    - all product items.


---

### getPublicItems()
- getPublicItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing all items in the list that are flagged as public.

    **Returns:**
    - all public items.


---

### getPurchases()
- getPurchases(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the aggregated purchases from all the individual items.

    **Returns:**
    - purchases


---

### getRegistrant()
- getRegistrant(): [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md)
  - : Returns the ProductListRegistrant assigned to the registrant attribute or null
      if this list has no registrant.


    **Returns:**
    - the ProductListRegistrant assigned to the registrant attribute or null
      if this list has no registrant.



---

### getShippingAddress()
- getShippingAddress(): [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)
  - : Return the address that should be used as the shipping address for purchases
      made from the list.


    **Returns:**
    - the shipping address. The shipping address of this list or null
      if no address is associated.



---

### getType()
- getType(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an int representing the type of object (e.g. wish list,
      gift registry). This is set at object creation time.


    **Returns:**
    - the type of object.


---

### isAnonymous()
- isAnonymous(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this product list is owned by an anonymous customer.

    **Returns:**
    - true if the owner of this product list is anonymous, false otherwise.


---

### isPublic()
- isPublic(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : A flag, typically used to determine if the object is searchable
      by other customers.


    **Returns:**
    - true if the product list is public. False otherwise.


---

### removeCoRegistrant()
- removeCoRegistrant(): void
  - : Removes the ProductListRegistrant assigned to the coRegistrant attribute.


---

### removeItem(ProductListItem)
- removeItem(item: [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)): void
  - : Removes the specified item from the list.  This will also cause
      all purchase information associated with that item to be removed.


    **Parameters:**
    - item - The item to remove.


---

### removeRegistrant()
- removeRegistrant(): void
  - : Removes the ProductListRegistrant assigned to the registrant attribute.


---

### setDescription(String)
- setDescription(description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the description of this product list.

    **Parameters:**
    - description - The description of this product list.  The description can have up to 256 characters, longer descriptions get truncated.  If an empty string is provided, the description gets set to null.


---

### setEventCity(String)
- setEventCity(eventCity: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the event city to which this product list is related.

    **Parameters:**
    - eventCity - The event city can have up to 256 characters, longer event city get truncated.  If an empty string is provided, the event city gets set to null.


---

### setEventCountry(String)
- setEventCountry(eventCountry: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the event country to which this product list is related.

    **Parameters:**
    - eventCountry - The event country can have up to 256 characters, longer event country get truncated.  If an empty string is provided, the event country gets set to null.


---

### setEventDate(Date)
- setEventDate(eventDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Set the date of the event to which this product list is related.

    **Parameters:**
    - eventDate - The event date or null if no event date should be available.


---

### setEventState(String)
- setEventState(eventState: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the event state to which this product list is related.

    **Parameters:**
    - eventState - The event state can have up to 256 characters, longer event state get truncated.  If an empty string is provided, the event state gets set to null.


---

### setEventType(String)
- setEventType(eventType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the event type for which this product list was created by the owner.

    **Parameters:**
    - eventType - The event type can have up to 256 characters, longer event type get truncated.  If an empty string is provided, the event type gets set to null.


---

### setName(String)
- setName(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the name of this product list.

    **Parameters:**
    - name - The name of this product list.  The name can have up to 256 characters, longer names get truncated.  If an empty string is provided, the name gets set to null.


---

### setPostEventShippingAddress(CustomerAddress)
- setPostEventShippingAddress(address: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)): void
  - : This is typically used by an event related list (e.g. gift registry) to
      specify a shipping address for purchases made after the event date.


    **Parameters:**
    - address - The shipping address.


---

### setPublic(Boolean)
- setPublic(flag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Makes this product list visible to other customers or hides it.

    **Parameters:**
    - flag - If true, this product list becomes visible to other customers.  If false, this product list can only be seen and searched by its owner.


---

### setShippingAddress(CustomerAddress)
- setShippingAddress(address: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)): void
  - : Associate an address, used as the shipping address for purchases
      made from the list.


    **Parameters:**
    - address - The shipping address.


---

<!-- prettier-ignore-end -->

<!-- document id=391f405af8675474b927ad9d05a04ecda1d526d37f2e902f00202dd8cd189674 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.ProductListItem.md -->

<!-- prettier-ignore-start -->
# Class ProductListItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)

An item in a product list.  Types of items are:


- An item that references a product via the product's SKU.
- An item that represents a gift certificate.



## Constant Summary

| Constant | Description |
| --- | --- |
| [TYPE_GIFT_CERTIFICATE](#type_gift_certificate): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Constant representing a gift certificate list item type. |
| [TYPE_PRODUCT](#type_product): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Constant representing a product list item type. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique system generated ID of the object. |
| [list](#list): [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md) `(read-only)` | Returns the product list that this item belongs to. |
| [priority](#priority): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Specify the priority level for the item. |
| [product](#product): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) | Returns the referenced product for this item. |
| [productID](#productid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product referenced by this item. |
| [productOptionModel](#productoptionmodel): [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md) | Returns the ProductOptionModel for the product associated with this item,  or null if there is no valid product associated with this item. |
| [public](#public): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | A flag, typically used to determine whether the item should display  in a customer's view of the list (as opposed to the list owner's view). |
| [purchasedQuantity](#purchasedquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the sum of the quantities of all the individual purchase records  for this item. |
| [purchasedQuantityValue](#purchasedquantityvalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the value part of the underlying purchased quantity object, as distinct  from the unit. |
| [purchases](#purchases): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all purchases made for this item. |
| [quantity](#quantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | Returns the quantity of the item. |
| [quantityValue](#quantityvalue): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the value part of the underlying quantity object, as distinct  from the unit. |
| [type](#type): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the type of this product list item. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createPurchase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#createpurchasenumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Create a purchase record for this item. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getid)() | Returns the unique system generated ID of the object. |
| [getList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getlist)() | Returns the product list that this item belongs to. |
| [getPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getpriority)() | Specify the priority level for the item. |
| [getProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getproduct)() | Returns the referenced product for this item. |
| [getProductID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getproductid)() | Returns the ID of the product referenced by this item. |
| [getProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getproductoptionmodel)() | Returns the ProductOptionModel for the product associated with this item,  or null if there is no valid product associated with this item. |
| [getPurchasedQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getpurchasedquantity)() | Returns the sum of the quantities of all the individual purchase records  for this item. |
| [getPurchasedQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getpurchasedquantityvalue)() | Returns the value part of the underlying purchased quantity object, as distinct  from the unit. |
| [getPurchases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getpurchases)() | Returns all purchases made for this item. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getquantity)() | Returns the quantity of the item. |
| [getQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#getquantityvalue)() | Returns the value part of the underlying quantity object, as distinct  from the unit. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#gettype)() | Returns the type of this product list item. |
| [isPublic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#ispublic)() | A flag, typically used to determine whether the item should display  in a customer's view of the list (as opposed to the list owner's view). |
| [setPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#setprioritynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Specify the priority level for the item. |
| ~~[setProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#setproductproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md))~~ | Sets the referenced product for this item by storing the product's id. |
| [setProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#setproductoptionmodelproductoptionmodel)([ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)) | Store a product option model with this object. |
| [setPublic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#setpublicboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Typically used to determine if the item is visible to other customers. |
| ~~[setQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#setquantityquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md))~~ | Sets the quantity of the item. |
| [setQuantityValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#setquantityvaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the value part of the underlying quantity object, as distinct from  the unit. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TYPE_GIFT_CERTIFICATE

- TYPE_GIFT_CERTIFICATE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Constant representing a gift certificate list item type.


---

### TYPE_PRODUCT

- TYPE_PRODUCT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Constant representing a product list item type.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique system generated ID of the object.


---

### list
- list: [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md) `(read-only)`
  - : Returns the product list that this item belongs to.


---

### priority
- priority: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Specify the priority level for the item.  Typically the lower the
      number, the higher the priority. This can be used by the owner of the product list
      to express which items he/she likes to get purchased first.



---

### product
- product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the referenced product for this item.  The reference is made
      via the product ID attribute.  This method returns null if there is
      no such product in the system or if the product exists but is not
      assigned to the site catalog.



---

### productID
- productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product referenced by this item.
      This attribute is set when a product is assigned via setProduct().
      It is possible for the ID to reference a product that doesn't exist
      anymore.  In this case getProduct() would return null.



---

### productOptionModel
- productOptionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)
  - : Returns the ProductOptionModel for the product associated with this item,
      or null if there is no valid product associated with this item.



---

### public
- public: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : A flag, typically used to determine whether the item should display
      in a customer's view of the list (as opposed to the list owner's view).



---

### purchasedQuantity
- purchasedQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the sum of the quantities of all the individual purchase records
      for this item.



---

### purchasedQuantityValue
- purchasedQuantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the value part of the underlying purchased quantity object, as distinct
      from the unit.



---

### purchases
- purchases: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all purchases made for this item.


---

### quantity
- quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of the item.
      The quantity is the number of products or gift certificates
      that get shipped when purchasing this product list item.



---

### quantityValue
- quantityValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value part of the underlying quantity object, as distinct
      from the unit.



---

### type
- type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the type of this product list item.


---

## Method Details

### createPurchase(Number, String)
- createPurchase(quantity: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), purchaserName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductListItemPurchase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md)
  - : Create a purchase record for this item.

    **Parameters:**
    - quantity - The number of items purchased.
    - purchaserName - The name of the purchaser.

    **Returns:**
    - the purchase record.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique system generated ID of the object.

    **Returns:**
    - the ID of object.


---

### getList()
- getList(): [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)
  - : Returns the product list that this item belongs to.

    **Returns:**
    - the list.


---

### getPriority()
- getPriority(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Specify the priority level for the item.  Typically the lower the
      number, the higher the priority. This can be used by the owner of the product list
      to express which items he/she likes to get purchased first.


    **Returns:**
    - the specified priority level.


---

### getProduct()
- getProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the referenced product for this item.  The reference is made
      via the product ID attribute.  This method returns null if there is
      no such product in the system or if the product exists but is not
      assigned to the site catalog.


    **Returns:**
    - the product referenced by this item, or null.


---

### getProductID()
- getProductID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product referenced by this item.
      This attribute is set when a product is assigned via setProduct().
      It is possible for the ID to reference a product that doesn't exist
      anymore.  In this case getProduct() would return null.


    **Returns:**
    - the product ID, or null if none exists.


---

### getProductOptionModel()
- getProductOptionModel(): [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)
  - : Returns the ProductOptionModel for the product associated with this item,
      or null if there is no valid product associated with this item.


    **Returns:**
    - the associated ProductOptionModel or null.


---

### getPurchasedQuantity()
- getPurchasedQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the sum of the quantities of all the individual purchase records
      for this item.


    **Returns:**
    - the sum of the quantities of all the individual purchase records
      for this item.



---

### getPurchasedQuantityValue()
- getPurchasedQuantityValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value part of the underlying purchased quantity object, as distinct
      from the unit.


    **Returns:**
    - the value part of the underlying purchased quantity object, as distinct
      from the unit.



---

### getPurchases()
- getPurchases(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all purchases made for this item.

    **Returns:**
    - the collection of purchase records for this item. Returns an empty list
      if this item has not been purchased yet.



---

### getQuantity()
- getQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of the item.
      The quantity is the number of products or gift certificates
      that get shipped when purchasing this product list item.


    **Returns:**
    - the quantity of the item.


---

### getQuantityValue()
- getQuantityValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value part of the underlying quantity object, as distinct
      from the unit.


    **Returns:**
    - the value part of the underlying quantity object, as distinct
      from the unit.



---

### getType()
- getType(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the type of this product list item.

    **Returns:**
    - a code that specifies the type of item (i.e. product or gift certificate).


---

### isPublic()
- isPublic(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : A flag, typically used to determine whether the item should display
      in a customer's view of the list (as opposed to the list owner's view).


    **Returns:**
    - true if the item is public.


---

### setPriority(Number)
- setPriority(priority: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Specify the priority level for the item.  Typically the lower the
      number, the higher the priority. This can be used by the owner of the product list
      to express which items he/she likes to get purchased first.


    **Parameters:**
    - priority - The new priority level.


---

### setProduct(Product)
- ~~setProduct(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): void~~
  - : Sets the referenced product for this item by storing the product's id.
      If null is specified, then the id is set to null.


    **Parameters:**
    - product - The referenced product for this item.

    **Deprecated:**
**warning:** Use [ProductList.createProductItem(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md#createproductitemproduct) instead.

---

### setProductOptionModel(ProductOptionModel)
- setProductOptionModel(productOptionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)): void
  - : Store a product option model with this object.  This stores a copy
      of the specified model, rather than an assocation to the same instance.


    **Parameters:**
    - productOptionModel - The object to store.


---

### setPublic(Boolean)
- setPublic(flag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Typically used to determine if the item is visible to other customers.

    **Parameters:**
    - flag - If true, this product list becomes visible to other customers.  If false, this product list can only be seen by the owner of the product list.


---

### setQuantity(Quantity)
- ~~setQuantity(value: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): void~~
  - : Sets the quantity of the item.

    **Parameters:**
    - value - the new quantity of the item.

    **Deprecated:**
**warning:** Use [setQuantityValue(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md#setquantityvaluenumber) instead.

---

### setQuantityValue(Number)
- setQuantityValue(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the value part of the underlying quantity object, as distinct from
      the unit.


    **Parameters:**
    - value - the value to use.


---

<!-- prettier-ignore-end -->

<!-- document id=18b22c6b6cb400f4d8626b30267483131ea4008b1401972eab016eb81d94dc92 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.ProductListItemPurchase.md -->

<!-- prettier-ignore-start -->
# Class ProductListItemPurchase

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.ProductListItemPurchase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md)

A record of the purchase of an item contained in a product list.


## Property Summary

| Property | Description |
| --- | --- |
| [item](#item): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md) `(read-only)` | Returns the item that was purchased. |
| [orderNo](#orderno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the number of the order in which the  product list item was purchased. |
| [purchaseDate](#purchasedate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date on which the product list item was purchased. |
| [purchaserName](#purchasername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the purchaser of the product list item. |
| [quantity](#quantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity of the product list item that was purchased. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md#getitem)() | Returns the item that was purchased. |
| [getOrderNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md#getorderno)() | Returns the number of the order in which the  product list item was purchased. |
| [getPurchaseDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md#getpurchasedate)() | Returns the date on which the product list item was purchased. |
| [getPurchaserName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md#getpurchasername)() | Returns the name of the purchaser of the product list item. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md#getquantity)() | Returns the quantity of the product list item that was purchased. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### item
- item: [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md) `(read-only)`
  - : Returns the item that was purchased.


---

### orderNo
- orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the number of the order in which the
      product list item was purchased.



---

### purchaseDate
- purchaseDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date on which the product list item was purchased.


---

### purchaserName
- purchaserName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the purchaser of the product list item.


---

### quantity
- quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity of the product list item that was purchased.


---

## Method Details

### getItem()
- getItem(): [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)
  - : Returns the item that was purchased.

    **Returns:**
    - the item that was purchased.


---

### getOrderNo()
- getOrderNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the number of the order in which the
      product list item was purchased.


    **Returns:**
    - the number of the order in which the
      product list item was purchased.



---

### getPurchaseDate()
- getPurchaseDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date on which the product list item was purchased.

    **Returns:**
    - the date on which the product list item was purchased.


---

### getPurchaserName()
- getPurchaserName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the purchaser of the product list item.

    **Returns:**
    - the name of the purchaser of the product list item.


---

### getQuantity()
- getQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of the product list item that was purchased.

    **Returns:**
    - the quantity of the product list item that was purchased.


---

<!-- prettier-ignore-end -->

<!-- document id=0dbca0bc4aa0ca3b3b11bd5400a4a0d973f5ec382b679888af12bf1547569d8a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.ProductListMgr.md -->

<!-- prettier-ignore-start -->
# Class ProductListMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.ProductListMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md)

ProductListMgr provides methods for retrieving, creating, searching for, and
removing product lists.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [createProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#createproductlistcustomer-number)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a new instance of a product list, of the specified type. |
| ~~static [getProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#getproductlistprofile-number)([Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Returns the first product list belonging to the customer with the  specified profile. |
| static [getProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#getproductliststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Gets the product list by its ID. |
| static [getProductLists](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#getproductlistscustomer-number)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Retrieve all product lists of the specified type owned by the  specified customer. |
| static [getProductLists](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#getproductlistscustomer-number-string)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Retrieve all the product lists of the specified type and event type  belonging to the specified customer. |
| static [getProductLists](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#getproductlistscustomeraddress)([CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)) | Returns the collection of product lists that have the specified address  as the shipping address. |
| static [queryProductLists](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#queryproductlistsmap-string)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>Searches for product list instances. |
| static [queryProductLists](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#queryproductlistsstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>Searches for product list instances. |
| static [removeProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#removeproductlistproductlist)([ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)) | Removes the specified product list from the system. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### createProductList(Customer, Number)
- static createProductList(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)
  - : Creates a new instance of a product list, of the specified type.

    **Parameters:**
    - customer - The customer owning the product list, must not be null.
    - type - The type of list (e.g. wish list, gift registry). The types             are defined as constants within             [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md).

    **Returns:**
    - the new list instance.


---

### getProductList(Profile, Number)
- ~~static getProductList(profile: [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md), type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)~~
  - : Returns the first product list belonging to the customer with the
      specified profile.


    **Parameters:**
    - profile - The profile of the customer whose product list is to be retrieved.
    - type - The type of list (e.g. wish list, gift registry). The types             are defined as constants within             [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md).

    **Returns:**
    - the product list, or null if none exists.

    **Deprecated:**
**warning:** Use [getProductLists(Customer, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#getproductlistscustomer-number) or [getProductLists(Customer, Number, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md#getproductlistscustomer-number-string) instead.

---

### getProductList(String)
- static getProductList(ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)
  - : Gets the product list by its ID.

    **Parameters:**
    - ID - The product list ID.

    **Returns:**
    - the ProductList instance, or null if a list with the specified
              UUID doesn't exist.



---

### getProductLists(Customer, Number)
- static getProductLists(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Retrieve all product lists of the specified type owned by the
      specified customer.


    **Parameters:**
    - customer - The customer used for the query, must not be null.
    - type - The type of list used for the query. The types are defined as             constants within [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md).

    **Returns:**
    - the unsorted collection of ProductList instances of the specified
              type belonging to the specified customer.



---

### getProductLists(Customer, Number, String)
- static getProductLists(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), eventType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Retrieve all the product lists of the specified type and event type
      belonging to the specified customer.


    **Parameters:**
    - customer - The customer used for the query, must not be null.
    - type - The type of list used for the query. The types are defined as             constants within [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md).
    - eventType - The event type used for the query, must not be null.

    **Returns:**
    - the unsorted collection of ProductList instances of the specified
              type and event type belonging to the specified customer.



---

### getProductLists(CustomerAddress)
- static getProductLists(customerAddress: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of product lists that have the specified address
      as the shipping address.


    **Parameters:**
    - customerAddress - the address to test, must not be null.

    **Returns:**
    - the unsorted collection of ProductList instances using this
              address.



---

### queryProductLists(Map, String)
- static queryProductLists(queryAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      Searches for product list instances.
      
      
      
      The search can be configured with a map, which key-value pairs are
      converted into a query expression. The key-value pairs are turned into a
      sequence of '=' or 'like' conditions, which are combined with AND
      statements.
      
      
      
      Example:
      
      A map with the key/value pairs: _'name'/'tom\*', 'age'/66_
      will be converted as follows: `"name like 'tom*' and age = 66"`
      
      
      
      The identifier for an **attribute**  to use in a query condition is always the
      ID of the  attribute as defined in the type definition. For custom defined attributes
      the prefix custom is required in the search term (e.g. `custom.color = {1}`),
      while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      Supported attribute value **types** with sample expression values:
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      Note, that some system attributes are not queryable by default regardless of the
      actual value type code.
      
      
      
      
      The **sorting** parameter is optional and may contain a comma separated list of
      attribute names to sort by. Each sort attribute name may be followed by an
      optional sort direction specifier ('asc' | 'desc'). Default sorting directions is
      ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is
      currently not supported.
      
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Parameters:**
    - queryAttributes - key-value pairs, which define the query.
    - sortString - an optional sorting or null if no sorting is necessary.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### queryProductLists(String, String, Object...)
- static queryProductLists(queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      Searches for product list instances.
      
      
      
      The search can be configured using a simple query language, which
      provides most common filter and operator functionality.
      
      
      
      The identifier for an **attribute**  to use in a query condition is always the
      ID of the  attribute as defined in the type definition. For custom defined attributes
      the prefix custom is required in the search term (e.g. `custom.color = {1}`),
      while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      Supported attribute value **types** with sample expression values:
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      The following types of attributes are not queryable:
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      Note, that some system attributes are not queryable by default regardless of the
      actual value type code.
      
      
      
      
      The following **operators** are supported in a condition:
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than  - Integer, Number and Date types only
      - `>`Greater than - Integer, Number and Date types only
      - `<=`Less or equals than - Integer, Number and Date types only
      - `>=`Greater or equals than  - Integer, Number and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing  wildcards will be used to support substring search(`custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only, use to support  case insensitive query (`custom.country ILIKE 'usa'`), does also support wildcards for  substring matching
      
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT'
      and nested using parenthesis e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      
      The query language provides a placeholder syntax to pass objects as
      additional search parameters. Each passed object is related to a
      placeholder in the query string. The placeholder must be an Integer that
      is surrounded by braces. The first Integer value must be '0', the second
      '1' and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      
      
      The **sorting** parameter is optional and may contain a comma separated list of
      attribute names to sort by. Each sort attribute name may be followed by an
      optional sort direction specifier ('asc' | 'desc'). Default sorting directions is
      ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is
      currently not supported.
      
      
      
      Sometimes it is desired to get all instances with a special sorting condition.
      This can be easily done by providing the 'sortString' in combination with
      an empty 'queryString', e.g. `querySystemObjects("sample", "", "ID asc")`
      
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Parameters:**
    - queryString - the actual query.
    - sortString - an optional sorting or null if no sorting is necessary.
    - args - optional parameters for the queryString.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### removeProductList(ProductList)
- static removeProductList(productList: [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)): void
  - : Removes the specified product list from the system.

    **Parameters:**
    - productList - The list to remove, must not be null.


---

<!-- prettier-ignore-end -->

<!-- document id=8516d87385461cd807197f2ee65bf4a39bf7627299b5989e35fcf2b011c53715 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.ProductListRegistrant.md -->

<!-- prettier-ignore-start -->
# Class ProductListRegistrant

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md)

A ProductListRegistrant is typically associated with an event related product list
such as a gift registry. It holds information about a person associated with the
event such as a bride or groom.



## Property Summary

| Property | Description |
| --- | --- |
| [email](#email): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the email address of the registrant or null. |
| [firstName](#firstname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the first name of the registrant or null. |
| [lastName](#lastname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the last name of the registrant or null. |
| [role](#role): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the role of the registrant or null. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#getemail)() | Returns the email address of the registrant or null. |
| [getFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#getfirstname)() | Returns the first name of the registrant or null. |
| [getLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#getlastname)() | Returns the last name of the registrant or null. |
| [getRole](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#getrole)() | Returns the role of the registrant or null. |
| [setEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#setemailstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the email address of the registrant. |
| [setFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#setfirstnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the first name of the registrant. |
| [setLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#setlastnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the last name of the registrant. |
| [setRole](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md#setrolestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the role of the registrant. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### email
- email: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the registrant or null.


---

### firstName
- firstName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the first name of the registrant or null.


---

### lastName
- lastName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last name of the registrant or null.


---

### role
- role: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the role of the registrant or null. The role of a registrant
      can be for example the bride of a bridal couple.



---

## Method Details

### getEmail()
- getEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the registrant or null.

    **Returns:**
    - the email address of the registrant or null.


---

### getFirstName()
- getFirstName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the first name of the registrant or null.

    **Returns:**
    - the first name of the registrant or null.


---

### getLastName()
- getLastName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last name of the registrant or null.

    **Returns:**
    - the last name of the registrant or null.


---

### getRole()
- getRole(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the role of the registrant or null. The role of a registrant
      can be for example the bride of a bridal couple.


    **Returns:**
    - the role name of the registrant or null.


---

### setEmail(String)
- setEmail(email: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the email address of the registrant.

    **Parameters:**
    - email - the email address of the registrant.


---

### setFirstName(String)
- setFirstName(firstName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the first name of the registrant.

    **Parameters:**
    - firstName - the first name of the registrant.


---

### setLastName(String)
- setLastName(lastName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the last name of the registrant.

    **Parameters:**
    - lastName - the last name of the registrant.


---

### setRole(String)
- setRole(role: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the role of the registrant.

    **Parameters:**
    - role - the role of the registrant.


---

<!-- prettier-ignore-end -->

<!-- document id=702f2b7000fc882b7e99a6b423cddd94939a62295a3405209547d79cbfb6dfbf url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductMgr.md -->

<!-- prettier-ignore-start -->
# Class ProductMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md)

Provides helper methods for getting products based on Product ID or [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md).


## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md#getproductstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the product with the specified id. |
| static [queryAllSiteProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md#queryallsiteproducts)() | Returns all products assigned to the current site. |
| static [queryAllSiteProductsSorted](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md#queryallsiteproductssorted)() | Returns all products assigned to the current site. |
| static [queryProductsInCatalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md#queryproductsincatalogcatalog)([Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)) | Returns all products assigned to the the specified catalog, where  assignment has the same meaning as it does for queryAllSiteProducts(). |
| static [queryProductsInCatalogSorted](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md#queryproductsincatalogsortedcatalog)([Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)) | Returns all products assigned to the the specified catalog. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### getProduct(String)
- static getProduct(productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the product with the specified id.

    **Parameters:**
    - productID - the product identifier.

    **Returns:**
    - Product for specified id or null


---

### queryAllSiteProducts()
- static queryAllSiteProducts(): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Returns all products assigned to the current site.
      
      
      A product is assigned to a site if 
      
      
      - it is assigned to at least one category of the site catalog or
      - it is a variant and it's master product is assigned to the current site
      
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Returns:**
    - Iterator of all site products

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### queryAllSiteProductsSorted()
- static queryAllSiteProductsSorted(): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Returns all products assigned to the current site.
      
      
      Works like queryAllSiteProducts(), but additionally sorts the result set
      by product ID.
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Returns:**
    - Iterator of all site products sorted by product ID.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### queryProductsInCatalog(Catalog)
- static queryProductsInCatalog(catalog: [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Returns all products assigned to the the specified catalog, where
      assignment has the same meaning as it does for queryAllSiteProducts().
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Parameters:**
    - catalog - The catalog whose assigned products should be returned.

    **Returns:**
    - Iterator of all products assigned to specified catalog.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### queryProductsInCatalogSorted(Catalog)
- static queryProductsInCatalogSorted(catalog: [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Returns all products assigned to the the specified catalog.
      Works like queryProductsInCatalog(), but additionally sorts the result
      set by product ID.
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Parameters:**
    - catalog - The catalog whose assigned products should be returned.

    **Returns:**
    - Iterator of all products assigned to specified catalog sorted by
              product ID.


    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

<!-- prettier-ignore-end -->

<!-- document id=97b6ebd4aa60032e553ce4c7b641ebec1da8e3e69fa256c2c59a0d2c3f82b46b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductOption.md -->

<!-- prettier-ignore-start -->
# Class ProductOption

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md)

Represents a product option.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product option ID. |
| [defaultValue](#defaultvalue): [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md) `(read-only)` | Returns the default value for the product option. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product option's short description in the current locale. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product option's display name in the current locale. |
| [htmlName](#htmlname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns an HTML representation of the option id. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the product option's image. |
| [optionValues](#optionvalues): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing the product option values. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDefaultValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#getdefaultvalue)() | Returns the default value for the product option. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#getdescription)() | Returns the product option's short description in the current locale. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#getdisplayname)() | Returns the product option's display name in the current locale. |
| [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#gethtmlname)() | Returns an HTML representation of the option id. |
| [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#gethtmlnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an HTML representation of the option id with the custom prefix. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#getid)() | Returns the product option ID. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#getimage)() | Returns the product option's image. |
| [getOptionValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md#getoptionvalues)() | Returns a collection containing the product option values. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product option ID.


---

### defaultValue
- defaultValue: [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md) `(read-only)`
  - : Returns the default value for the product option.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product option's short description in the current locale.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product option's display name in the current locale.


---

### htmlName
- htmlName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns an HTML representation of the option id.


---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the product option's image.


---

### optionValues
- optionValues: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing the product option values.


---

## Method Details

### getDefaultValue()
- getDefaultValue(): [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)
  - : Returns the default value for the product option.

    **Returns:**
    - the object for the relation 'defaultValue'


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product option's short description in the current locale.

    **Returns:**
    - The value of the short description in the current locale,
                   or null if it wasn't found.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product option's display name in the current locale.

    **Returns:**
    - The value of the display name in the current locale,
                   or null if it wasn't found.



---

### getHtmlName()
- getHtmlName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an HTML representation of the option id.

    **Returns:**
    - an HTML representation of the option id.


---

### getHtmlName(String)
- getHtmlName(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an HTML representation of the option id with the custom prefix.

    **Parameters:**
    - prefix - a custom prefix for the html name.

    **Returns:**
    - an HTML representation of the option id.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product option ID.

    **Returns:**
    - the product option identifier.


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the product option's image.

    **Returns:**
    - the product option's image.


---

### getOptionValues()
- getOptionValues(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing the product option values.

    **Returns:**
    - a collection containing the product option values.


---

<!-- prettier-ignore-end -->

<!-- document id=ec1543a1593d60458d2cea4b6d76962b5c22ebee9e2878dbc5e4de351d337add url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductOptionModel.md -->

<!-- prettier-ignore-start -->
# Class ProductOptionModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)

This class represents the option model of a specific product and
for a specific currency. It provides accessor methods to the configured
options and the values of those options. It has also methods to set a
specific selection of option values.



## Property Summary

| Property | Description |
| --- | --- |
| [options](#options): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of product options. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#getoptionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the product option for the specified ID. |
| [getOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#getoptionvalueproductoption-string)([ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the product option value object for the passed value id and in  the context of the passed option. |
| [getOptionValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#getoptionvaluesproductoption)([ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md)) | Returns a collection of product option values for the  specified product option. |
| [getOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#getoptions)() | Returns the collection of product options. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#getpriceproductoptionvalue)([ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)) | Returns the effective price of the specified option value. |
| [getSelectedOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#getselectedoptionvalueproductoption)([ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md)) | Returns the selected value for the specified product option. |
| [isSelectedOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#isselectedoptionvalueproductoption-productoptionvalue)([ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)) | Returns true if the specified option value is the one currently selected,  false otherwise. |
| [setSelectedOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#setselectedoptionvalueproductoption-productoptionvalue)([ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)) | Updates the selection of the specified option based on the specified value. |
| [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#urlstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a URL that can be used to select one or more option values. |
| [urlSelectOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md#urlselectoptionvaluestring-productoption-productoptionvalue)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)) | Returns an URL that can be used to select a specific value of a specific  option. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### options
- options: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of product options.


---

## Method Details

### getOption(String)
- getOption(optionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md)
  - : Returns the product option for the specified ID.

    **Parameters:**
    - optionID - the product option identifier.

    **Returns:**
    - the product option for the specified ID.


---

### getOptionValue(ProductOption, String)
- getOptionValue(option: [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), valueID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)
  - : Returns the product option value object for the passed value id and in
      the context of the passed option.


    **Parameters:**
    - option - The option to get the specified value for.
    - valueID - The id of the value to retrieve

    **Returns:**
    - a value for the specified product option and value id


---

### getOptionValues(ProductOption)
- getOptionValues(option: [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of product option values for the
      specified product option.


    **Parameters:**
    - option - the option for which we want to extract  the collection of product option values.

    **Returns:**
    - a collection of product option values for the
      specified product option.



---

### getOptions()
- getOptions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of product options.

    **Returns:**
    - Collection of Product Options.


---

### getPrice(ProductOptionValue)
- getPrice(optionValue: [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the effective price of the specified option value.

    **Parameters:**
    - optionValue - the product option value to use.

    **Returns:**
    - the effective price of the specified option value.


---

### getSelectedOptionValue(ProductOption)
- getSelectedOptionValue(option: [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md)): [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)
  - : Returns the selected value for the specified product option. If no
      option values was set as selected option explicitly, the method
      returns the default option value for this option.


    **Parameters:**
    - option - The option to get the selected value for.

    **Returns:**
    - a selected value for the specified product option.


---

### isSelectedOptionValue(ProductOption, ProductOptionValue)
- isSelectedOptionValue(option: [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), value: [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the specified option value is the one currently selected,
      false otherwise.


    **Parameters:**
    - option - the product option.
    - value - the product option value.

    **Returns:**
    - true if the specified option value is the one currently selected,
      false otherwise.



---

### setSelectedOptionValue(ProductOption, ProductOptionValue)
- setSelectedOptionValue(option: [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), value: [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)): void
  - : Updates the selection of the specified option based on the specified value.

    **Parameters:**
    - option - the option to update.
    - value - the value to use when updating the product option.


---

### url(String, Object...)
- url(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), varOptionAndValues: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns a URL that can be used to select one or more option values. The
      optional `varOptionAndValues` argument can be empty, or can
      contain one or more option / value pairs. This variable list must be even
      in length, with options and values alternating. If the list is odd in
      length, the last argument will be ignored. Options can be specified as
      instances of ProductOption, or String option ID. Values can be specified
      as instances of ProductOptionValue or as strings representing the value
      ID. If a parameter is invalid, then the parameter pair is not included in
      the generated URL. The returned URL will contain options and values
      already selected in the product option model, as well as options and
      values specified as method parameters. This includes option values
      explicitly selected and implicitly selected by default.


    **Parameters:**
    - action - The pipeline action, must not be null.
    - varOptionAndValues - Variable length list of options and values.

    **Returns:**
    - The constructed URL.


---

### urlSelectOptionValue(String, ProductOption, ProductOptionValue)
- urlSelectOptionValue(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), option: [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md), value: [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an URL that can be used to select a specific value of a specific
      option.


    **Parameters:**
    - action - the action to use.
    - option - the option to use when constructing the URL.
    - value - the value to use when constructing the URL.

    **Returns:**
    - The constructed URL as string.


---

<!-- prettier-ignore-end -->

<!-- document id=aafb824f52ab7de4f8d5f099857e4939061a484438084f4458409bface28e4c9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductOptionValue.md -->

<!-- prettier-ignore-start -->
# Class ProductOptionValue

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)

Represents the value of a product option.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product option value's ID. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the the product option value's description  in the current locale. |
| [displayValue](#displayvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the the product option value's display name  in the current locale. |
| [productIDModifier](#productidmodifier): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the product option value's product ID modifier which  can be used to build the SKU for the actual product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md#getdescription)() | Returns the the product option value's description  in the current locale. |
| [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md#getdisplayvalue)() | Returns the the product option value's display name  in the current locale. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md#getid)() | Returns the product option value's ID. |
| [getProductIDModifier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md#getproductidmodifier)() | Returns the product option value's product ID modifier which  can be used to build the SKU for the actual product. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product option value's ID.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the the product option value's description
      in the current locale.



---

### displayValue
- displayValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the the product option value's display name
      in the current locale.



---

### productIDModifier
- productIDModifier: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the product option value's product ID modifier which
      can be used to build the SKU for the actual product.



---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the the product option value's description
      in the current locale.


    **Returns:**
    - The value of the product option value's description
      in the current locale, or null if it wasn't found.



---

### getDisplayValue()
- getDisplayValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the the product option value's display name
      in the current locale.


    **Returns:**
    - The value of the product option value's display name
      in the current locale, or null if it wasn't found.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product option value's ID.

    **Returns:**
    - the product option value's ID.


---

### getProductIDModifier()
- getProductIDModifier(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the product option value's product ID modifier which
      can be used to build the SKU for the actual product.


    **Returns:**
    - the product option value's product ID modifier which
      can be used to build the SKU for the actual product.



---

<!-- prettier-ignore-end -->

<!-- document id=2d2044a0b0a61e9cb8f139285a7c9887842c69d08bfb5bbcd5ae483e75d9bca5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductPriceInfo.md -->

<!-- prettier-ignore-start -->
# Class ProductPriceInfo

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md)

Simple class representing a product price point.  This class is useful
because it provides additional information beyond just the price.  Since the
system calculates sales prices based on applicable price books, it is
sometimes useful to know additional information such as which price book
defined a price point, what percentage discount off the base price
this value represents, and the date range for which this price point is active.



## Property Summary

| Property | Description |
| --- | --- |
| [onlineFrom](#onlinefrom): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date from which the associated price point is valid. |
| [onlineTo](#onlineto): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date until which the associated price point is valid. |
| [percentage](#percentage): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the percentage off value of this price point related to the base  price for the product's minimum order quantity. |
| [price](#price): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the monetary price for this price point. |
| [priceBook](#pricebook): [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md) `(read-only)` | Returns the price book which defined this price point. |
| [priceInfo](#priceinfo): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the price info associated with this price point. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md#getonlinefrom)() | Returns the date from which the associated price point is valid. |
| [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md#getonlineto)() | Returns the date until which the associated price point is valid. |
| [getPercentage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md#getpercentage)() | Returns the percentage off value of this price point related to the base  price for the product's minimum order quantity. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md#getprice)() | Returns the monetary price for this price point. |
| [getPriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md#getpricebook)() | Returns the price book which defined this price point. |
| [getPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md#getpriceinfo)() | Returns the price info associated with this price point. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### onlineFrom
- onlineFrom: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date from which the associated price point is valid. If such a date doesn't exist, e.g. as in the
      case of a continuous price point, null will be returned.



---

### onlineTo
- onlineTo: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date until which the associated price point is valid. If such a date doesn't exist, e.g. as in the case
      of a continuous price point, null will be returned.



---

### percentage
- percentage: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the percentage off value of this price point related to the base
      price for the product's minimum order quantity.



---

### price
- price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the monetary price for this price point.


---

### priceBook
- priceBook: [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md) `(read-only)`
  - : Returns the price book which defined this price point.


---

### priceInfo
- priceInfo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the price info associated with this price point. This is an
      arbitrary string which a merchant can associate with a price entry. This
      can be used for example, to track which back-end system the price is
      derived from.



---

## Method Details

### getOnlineFrom()
- getOnlineFrom(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date from which the associated price point is valid. If such a date doesn't exist, e.g. as in the
      case of a continuous price point, null will be returned.


    **Returns:**
    - the date from which the associated price point is valid


---

### getOnlineTo()
- getOnlineTo(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date until which the associated price point is valid. If such a date doesn't exist, e.g. as in the case
      of a continuous price point, null will be returned.


    **Returns:**
    - the date to which the associated price point is valid


---

### getPercentage()
- getPercentage(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the percentage off value of this price point related to the base
      price for the product's minimum order quantity.


    **Returns:**
    - the percentage off value of this price point


---

### getPrice()
- getPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the monetary price for this price point.

    **Returns:**
    - the price amount


---

### getPriceBook()
- getPriceBook(): [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)
  - : Returns the price book which defined this price point.

    **Returns:**
    - the price book defining this price


---

### getPriceInfo()
- getPriceInfo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the price info associated with this price point. This is an
      arbitrary string which a merchant can associate with a price entry. This
      can be used for example, to track which back-end system the price is
      derived from.


    **Returns:**
    - the price info associated with this price point.


---

<!-- prettier-ignore-end -->

<!-- document id=87371c00b1c60d4031bd5424af19742cde0731b4baaacc748731f110f0dd95e2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductPriceModel.md -->

<!-- prettier-ignore-start -->
# Class ProductPriceModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md)

ProductPriceModel provides methods to access all the
[PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md) information of a product. A ProductPriceModel
instance is retrieved by calling [Product.getPriceModel()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodel)
or [Product.getPriceModel(ProductOptionModel)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodelproductoptionmodel) for a
specific product. The latter method will return a model which also includes
the additional option prices of an option product.


When the current price of a product is accessed in the storefront via its
price model, a price lookup is performed. The high-level steps of this price
lookup are:


- Get all price books applicable in the context of the current site, time,  session, customer, source code.
- Identify all prices in the applicable price books and for a requested  quantity.
- Calculate the best-price of all identified prices. The best-price is the  lowest price.


In more detail:



**Identify applicable price books**


- If any price books are explicitly registered in the session (see pipelet  SetApplicablePriceBooks), use these price books and their direct parents for  price lookup. Ignore all inactive price books, price books not valid at the  current time, and price books with a currency other than the session currency.


**Otherwise:**


- If a valid source code is registered with the current session, get all  price books assigned to the source code and their parent price books. Ignore  all inactive price books, price books not valid at the current time, and  price books with a currency other than the session currency.
- Get all price books assigned to site and their parent price books. Ignore  all inactive price books, price books not valid at the current time, and  price books with a currency other than the session currency.


**Identify all prices:**


- Get all price definitions for the product from all applicable price  books. Ignore price definitions not valid at the current time.
- Convert any percentage price definition into a monetary amount. As the  base price for this calculation, the minimum product price for the minimum  order quantity of the product, including product options, is used.
- Compare all prices and identify the lowest (= best) price.
- Calculate best price for each defined price cut in the price table and  return price table.


**Variation Price Fallback:**


- If no applicable pricebooks for a variant is found, the price lookup gets  the price books from the variant's master product
- A price books is also not applicable of the price definition for the  variant in the price book is not valid at the current time.





Typically, in order to do a standard price lookup, it is only necessary to
call `Product.getPriceModel().getPrice()`. However, Commerce Cloud
Digital also supports tiered prices, meaning that higher quantities receive
a lower price. In this case, the merchant typically wants to display a table
of price points on product detail pages. Therefore, the ProductPriceModel
provides the method [getPriceTable()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricetable) to retrieve a table of these prices.




If a merchant wants to know not only what the price of a given product is,
but what price book the price was derived from, this class provides the
method [getPriceInfo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfo). This class also provides methods to lookup
product prices in specific price books by name and quantity. See
[getPriceBookPrice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring).



## Property Summary

| Property | Description |
| --- | --- |
| [basePriceQuantity](#basepricequantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the quantity for which the base price is defined. |
| [maxPrice](#maxprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Calculates and returns the maximum price-book price of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [maxPricePerUnit](#maxpriceperunit): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Calculates and returns the maximum price-book price per unit of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [minPrice](#minprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Calculates and returns the minimum price-book price of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [minPricePerUnit](#minpriceperunit): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Calculates and returns the minimum price-book price per unit of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [price](#price): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the active price of a product, calculated based on base price quantity  1.00. |
| [priceInfo](#priceinfo): [ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md) `(read-only)` | Returns the active price info of a product, calculated based on base price  quantity 1.00. |
| [priceInfos](#priceinfos): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all the eligible `</>ProductPriceInfo`</>(s), calculated based  on base price quantity 1.00. |
| [pricePerUnit](#priceperunit): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sales price per unit of a product, calculated based on base price  quantity 1.00. |
| [priceRange](#pricerange): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this product is a master product (or product set) and the  collection of online variants (or set products respectively) contains  products of different prices. |
| [priceTable](#pricetable): [ProductPriceTable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md) `(read-only)` | Returns the product price table object. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBasePriceQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getbasepricequantity)() | Returns the quantity for which the base price is defined. |
| [getMaxPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getmaxprice)() | Calculates and returns the maximum price-book price of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [getMaxPriceBookPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getmaxpricebookpricestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Calculates and returns the maximum price in a given price book of all  variants (for master products) or set-products (for product sets) for  base quantity 1.00. |
| [getMaxPriceBookPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getmaxpricebookpriceperunitstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Calculates and returns the maximum price per unit in a given price book of all  variants (for master products) or set-products (for product sets) for  base quantity 1.00. |
| [getMaxPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getmaxpriceperunit)() | Calculates and returns the maximum price-book price per unit of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [getMinPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getminprice)() | Calculates and returns the minimum price-book price of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [getMinPriceBookPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getminpricebookpricestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Calculates and returns the minimum price in a given price book of all  variants (for master products) or set-products (for product sets) for  base quantity 1.00. |
| [getMinPriceBookPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getminpricebookpriceperunitstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Calculates and returns the minimum price per unit in a given price book of all  variants (for master products) or set-products (for product sets) for  base quantity 1.00. |
| [getMinPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getminpriceperunit)() | Calculates and returns the minimum price-book price per unit of all variants (for  master products) or set-products (for product sets) for base quantity  1.00. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getprice)() | Returns the active price of a product, calculated based on base price quantity  1.00. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricequantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the active price of a product, calculated based on the passed order  quantity. |
| [getPriceBookPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the active price of the product in the specified price book for  quantity 1.00. |
| [getPriceBookPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring-quantity)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the active price of the product in the specified price book for  the specified quantity. |
| [getPriceBookPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceinfostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | This method acts similarly to [getPriceBookPrice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring) but  returns a ProductPriceInfo object wrapping the actual price with  additional information. |
| [getPriceBookPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceinfostring-quantity)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | This method acts similarly to  [getPriceBookPrice(String, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring-quantity) but returns a  ProductPriceInfo object wrapping the actual price with additional  information. |
| [getPriceBookPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceperunitstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the active price per unit of the product in the specified price book for  quantity 1.00. |
| [getPriceBookPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceperunitstring-quantity)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the active price per unit of the product in the specified price book for  the specified quantity. |
| [getPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfo)() | Returns the active price info of a product, calculated based on base price  quantity 1.00. |
| [getPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfoquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the active price info of a product, calculated based on the passed order  quantity. |
| [getPriceInfos](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfos)() | Returns all the eligible `</>ProductPriceInfo`</>(s), calculated based  on base price quantity 1.00. |
| [getPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceperunit)() | Returns the sales price per unit of a product, calculated based on base price  quantity 1.00. |
| [getPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceperunitquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the sales price per unit of a product, calculated based on the passed  order quantity. |
| ~~[getPricePercentage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricepercentagemoney-money)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md))~~ | Calculates and returns the percentage off amount of the passed  comparePrice to the passed basePrice. |
| [getPriceTable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricetable)() | Returns the product price table object. |
| [isPriceRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#ispricerange)() | Returns true if this product is a master product (or product set) and the  collection of online variants (or set products respectively) contains  products of different prices. |
| [isPriceRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#ispricerangestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns true if this product is a master product (or product set) and the  collection of online variants (or set products respectively) contains  products of different prices in the specified price book. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### basePriceQuantity
- basePriceQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the quantity for which the base price is defined. This
      is typically 1.0.



---

### maxPrice
- maxPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Calculates and returns the maximum price-book price of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getprice).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      
      **Warning:**  If the product represented by this model is a master
      product with numerous variants, this method can be very expensive and
      should be avoided.



---

### maxPricePerUnit
- maxPricePerUnit: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Calculates and returns the maximum price-book price per unit of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPricePerUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceperunit).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      e.g.
      suppose one master product mp (price = $6, unitQuantity = 2), it has 2 variants:
      v1(price = $5, unitQuantity = 5), v2(price = $10, unitQuantity = 20).
      The max price per unit of mp will be max($6/2, $5/5, $10/20) = $3



---

### minPrice
- minPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Calculates and returns the minimum price-book price of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getprice).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      
      **Warning:**  If the product represented by this model is a master
      product with numerous variants, this method can be very expensive and
      should be avoided.



---

### minPricePerUnit
- minPricePerUnit: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Calculates and returns the minimum price-book price per unit of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPricePerUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceperunit).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      e.g.
      suppose one master product mp (price = $6, unitQuantity = 2), it has 2 variants:
      v1(price = $5, unitQuantity = 5), v2(price = $10, unitQuantity = 20).
      The min price per unit of mp will be min($6/2, $5/5, $10/20) = $0.5



---

### price
- price: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the active price of a product, calculated based on base price quantity
      1.00. The price is returned for the currency of the current session.
      
      
      The price lookup is based on the configuration of price books. It depends
      on various settings, such as which price books are active, or explicitly
      set as applicable in the current session.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      If no price could be found, MONEY.NOT\_AVAILABLE is returned.



---

### priceInfo
- priceInfo: [ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md) `(read-only)`
  - : Returns the active price info of a product, calculated based on base price
      quantity 1.00. The price is returned for the currency of the current
      session.
      
      
      This method is similar to `getPrice()` but instead of just
      returning the price value, it returns a `ProductPriceInfo`
      which contains additional information such as the PriceBook which defined
      the price and the percentage discount this price point represents.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      If no price info could be found, null is returned.


    **See Also:**
    - [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getprice)
    - [getPriceInfo(Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfoquantity)


---

### priceInfos
- priceInfos: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all the eligible `</>ProductPriceInfo`</>(s), calculated based
      on base price quantity 1.00. This will return an empty list if getPriceInfo() would return null, and if there is
      only one price info in the collection it will be the same price info as getPriceInfo(). Two or more price infos
      indicate that there are that many price books that meet the criteria for returning the price shown in the
      storefront.


    **See Also:**
    - [getPriceInfo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfo)


---

### pricePerUnit
- pricePerUnit: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sales price per unit of a product, calculated based on base price
      quantity 1.00.
      
      
      The product sales price per unit is returned for the current session currency.
      Hence, the using this method is only useful in storefront processes.
      
      
      The price lookup is based on the configuration of price books. It depends
      on various settings, such as which price books are active, or explicitly
      set as applicable in the current session.
      
      
      If no price could be found, MONEY.N\_A is returned.



---

### priceRange
- priceRange: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this product is a master product (or product set) and the
      collection of online variants (or set products respectively) contains
      products of different prices.
      
      
      **Warning:**  If the product represented by this model is a master
      product with numerous variants, this method can be very expensive and
      should be avoided.



---

### priceTable
- priceTable: [ProductPriceTable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md) `(read-only)`
  - : Returns the product price table object. The price table represents a map
      between order quantities and prices, and also provides % off information
      to be shown to storefront customers. The price is returned for the
      currency of the current session.
      
      
      Usually, the product price table is printed on product detail pages in
      the storefront.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      All other methods of this class are based on the information in the
      product price table.



---

## Method Details

### getBasePriceQuantity()
- getBasePriceQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity for which the base price is defined. This
      is typically 1.0.


    **Returns:**
    - the quantity for which the base price is defined.


---

### getMaxPrice()
- getMaxPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the maximum price-book price of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getprice).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      
      **Warning:**  If the product represented by this model is a master
      product with numerous variants, this method can be very expensive and
      should be avoided.


    **Returns:**
    - Maximum price of all online variants or set-products.


---

### getMaxPriceBookPrice(String)
- getMaxPriceBookPrice(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the maximum price in a given price book of all
      variants (for master products) or set-products (for product sets) for
      base quantity 1.00. This value can be used to display a range of prices
      in storefront.
      
      This method follows the same rules as
      [getPriceBookPrice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring) in determining the price book
      price for each variant or set-product. If the product represented by this
      model is not a master product or product set, then this method behaves
      the same as [getPriceBookPrice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring).


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not             be null.

    **Returns:**
    - The maximum price across all subproducts in the specified price
              book.



---

### getMaxPriceBookPricePerUnit(String)
- getMaxPriceBookPricePerUnit(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the maximum price per unit in a given price book of all
      variants (for master products) or set-products (for product sets) for
      base quantity 1.00. This value can be used to display a range of price per units
      in storefront.
      
      This method follows the same rules as
      [getPriceBookPricePerUnit(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceperunitstring) in determining the price book
      price for each variant or set-product. If the product represented by this
      model is not a master product or product set, then this method behaves
      the same as [getPriceBookPricePerUnit(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceperunitstring).


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not             be null.

    **Returns:**
    - The maximum price per unit across all sub-products in the specified price
              book.



---

### getMaxPricePerUnit()
- getMaxPricePerUnit(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the maximum price-book price per unit of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPricePerUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceperunit).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      e.g.
      suppose one master product mp (price = $6, unitQuantity = 2), it has 2 variants:
      v1(price = $5, unitQuantity = 5), v2(price = $10, unitQuantity = 20).
      The max price per unit of mp will be max($6/2, $5/5, $10/20) = $3


    **Returns:**
    - Maximum price per unit of all online variants or set-products.


---

### getMinPrice()
- getMinPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the minimum price-book price of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getprice).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      
      **Warning:**  If the product represented by this model is a master
      product with numerous variants, this method can be very expensive and
      should be avoided.


    **Returns:**
    - Minimum price of all online variants or set-products.


---

### getMinPriceBookPrice(String)
- getMinPriceBookPrice(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the minimum price in a given price book of all
      variants (for master products) or set-products (for product sets) for
      base quantity 1.00. This value can be used to display a range of prices
      in storefront.
      
      This method follows the same rules as
      [getPriceBookPrice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring) in determining the price book
      price for each variant or set-product. If the product represented by this
      model is not a master product or product set, then this method behaves
      the same as [getPriceBookPrice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring).


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not             be null.

    **Returns:**
    - The minimum price across all subproducts in the specified price
              book.



---

### getMinPriceBookPricePerUnit(String)
- getMinPriceBookPricePerUnit(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the minimum price per unit in a given price book of all
      variants (for master products) or set-products (for product sets) for
      base quantity 1.00. This value can be used to display a range of price per units
      in storefront.
      
      This method follows the same rules as
      [getPriceBookPricePerUnit(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceperunitstring) in determining the price book
      price for each variant or set-product. If the product represented by this
      model is not a master product or product set, then this method behaves
      the same as [getPriceBookPricePerUnit(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpriceperunitstring).


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not             be null.

    **Returns:**
    - The minimum price per unit across all sub-products in the specified price
              book.



---

### getMinPricePerUnit()
- getMinPricePerUnit(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Calculates and returns the minimum price-book price per unit of all variants (for
      master products) or set-products (for product sets) for base quantity
      1.00. This value can be used to display a range of prices in storefront.
      If the product represented by this model is not a master product or
      product set, then this method behaves the same as [getPricePerUnit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceperunit).
      Only online products are considered. If the "orderable products only"
      search preference is enabled for the current site, then only orderable
      products are considered. For master products, only variants with all
      variation attributes configured are considered.
      
      e.g.
      suppose one master product mp (price = $6, unitQuantity = 2), it has 2 variants:
      v1(price = $5, unitQuantity = 5), v2(price = $10, unitQuantity = 20).
      The min price per unit of mp will be min($6/2, $5/5, $10/20) = $0.5


    **Returns:**
    - Minimum price of all online variants or set-products.


---

### getPrice()
- getPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the active price of a product, calculated based on base price quantity
      1.00. The price is returned for the currency of the current session.
      
      
      The price lookup is based on the configuration of price books. It depends
      on various settings, such as which price books are active, or explicitly
      set as applicable in the current session.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      If no price could be found, MONEY.NOT\_AVAILABLE is returned.


    **Returns:**
    - the product price.


---

### getPrice(Quantity)
- getPrice(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the active price of a product, calculated based on the passed order
      quantity. The price is returned for the currency of the current session.
      
      
      The price lookup is based on the configuration of price books. It depends
      on various settings, such as which price books are active, or explicitly
      set as applicable in the current session.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      If passed order quantity < 1 (and greater than zero), price for quantity
      1 is returned.
      
      
      If no price could be found, MONEY.NOT\_AVAILABLE is returned.


    **Parameters:**
    - quantity - Quantity price is requested for

    **Returns:**
    - the product price.


---

### getPriceBookPrice(String)
- getPriceBookPrice(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the active price of the product in the specified price book for
      quantity 1.00.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      Money.NOT\_AVAILABLE will be returned in any of the following cases:
      
      
      - priceBookID is null or does not identify a valid price book.
      - The price book has no price for the product.
      - None of the prices for the product in the price book is currently  active.
      - The currently active price entry is a percentage.


    **Parameters:**
    - priceBookID - ID of price book the price is requested for.

    **Returns:**
    - the price of the product in the specified price book.


---

### getPriceBookPrice(String, Quantity)
- getPriceBookPrice(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the active price of the product in the specified price book for
      the specified quantity.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      Money.NOT\_AVAILABLE will be returned in any of the following cases:
      
      
      - priceBookID is null or does not identify a valid price book.
      - quantity is null.
      - The price book has no price for the product.
      - None of the prices for the product in the price book is currently  active.
      - The currently active price entry is a percentage.


    **Parameters:**
    - priceBookID - ID of price book the price is requested for.
    - quantity - the specified quantity to find the price for.

    **Returns:**
    - the price of the product in the specified price book.


---

### getPriceBookPriceInfo(String)
- getPriceBookPriceInfo(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md)
  - : This method acts similarly to [getPriceBookPrice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring) but
      returns a ProductPriceInfo object wrapping the actual price with
      additional information.


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not             be null.

    **Returns:**
    - the product price info, or null if not found.


---

### getPriceBookPriceInfo(String, Quantity)
- getPriceBookPriceInfo(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md)
  - : This method acts similarly to
      [getPriceBookPrice(String, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricebookpricestring-quantity) but returns a
      ProductPriceInfo object wrapping the actual price with additional
      information.


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not             be null.
    - quantity - Quantity price is requested for.

    **Returns:**
    - the product price info, or null if not found.


---

### getPriceBookPricePerUnit(String)
- getPriceBookPricePerUnit(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the active price per unit of the product in the specified price book for
      quantity 1.00.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      Money.NOT\_AVAILABLE will be returned in any of the following cases:
      
      
      - The priceBookID does not identify a valid price book.
      - The price book has no price for the product.
      - None of the prices for the product in the price book is currently  active.
      - The currently active price entry is a percentage.


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not be null.

    **Returns:**
    - the price per unit of the product in the specified price book.


---

### getPriceBookPricePerUnit(String, Quantity)
- getPriceBookPricePerUnit(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the active price per unit of the product in the specified price book for
      the specified quantity.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      Money.NOT\_AVAILABLE will be returned in any of the following cases:
      
      
      - The priceBookID does not identify a valid price book.
      - The price book has no price for the product.
      - None of the prices for the product in the price book is currently  active.
      - The currently active price entry is a percentage.


    **Parameters:**
    - priceBookID - ID of price book the price is requested for, must not be null.
    - quantity - the specified quantity to find the price for, must not be null.

    **Returns:**
    - the price per unit of the product in the specified price book for the specific quantity.


---

### getPriceInfo()
- getPriceInfo(): [ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md)
  - : Returns the active price info of a product, calculated based on base price
      quantity 1.00. The price is returned for the currency of the current
      session.
      
      
      This method is similar to `getPrice()` but instead of just
      returning the price value, it returns a `ProductPriceInfo`
      which contains additional information such as the PriceBook which defined
      the price and the percentage discount this price point represents.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      If no price info could be found, null is returned.


    **Returns:**
    - the product price info, or null if not found.

    **See Also:**
    - [getPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getprice)
    - [getPriceInfo(Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfoquantity)


---

### getPriceInfo(Quantity)
- getPriceInfo(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md)
  - : Returns the active price info of a product, calculated based on the passed order
      quantity. The price is returned for the currency of the current session.
      
      
      This method is similar to `getPrice(Quantity)` but instead of
      just returning the price value, it returns a
      `ProductPriceInfo` which contains additional information such
      as the PriceBook which defined the price and the percentage discount this
      price point represents.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      If no price info could be found, null is returned.


    **Parameters:**
    - quantity - the quantity to use.

    **Returns:**
    - the product price info, or null if not found.

    **See Also:**
    - [getPrice(Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpricequantity)


---

### getPriceInfos()
- getPriceInfos(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all the eligible `</>ProductPriceInfo`</>(s), calculated based
      on base price quantity 1.00. This will return an empty list if getPriceInfo() would return null, and if there is
      only one price info in the collection it will be the same price info as getPriceInfo(). Two or more price infos
      indicate that there are that many price books that meet the criteria for returning the price shown in the
      storefront.


    **Returns:**
    - any product price info that could be responsible for the storefront price, or empty collection if there
              were no product price infos this price model.


    **See Also:**
    - [getPriceInfo()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md#getpriceinfo)


---

### getPricePerUnit()
- getPricePerUnit(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sales price per unit of a product, calculated based on base price
      quantity 1.00.
      
      
      The product sales price per unit is returned for the current session currency.
      Hence, the using this method is only useful in storefront processes.
      
      
      The price lookup is based on the configuration of price books. It depends
      on various settings, such as which price books are active, or explicitly
      set as applicable in the current session.
      
      
      If no price could be found, MONEY.N\_A is returned.


    **Returns:**
    - product sales price per unit


---

### getPricePerUnit(Quantity)
- getPricePerUnit(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sales price per unit of a product, calculated based on the passed
      order quantity.
      
      
      The product sales price per unit is returned for the current session currency.
      Hence, the using this method is only useful in storefront processes.
      
      
      The price lookup is based on the configuration of price books. It depends
      on various settings, such as which price books are active, or explicitely
      set as applicable in the current session.
      
      
      If no price could be found, MONEY.N\_A is returned.


    **Parameters:**
    - quantity - Quantity price is requested for

    **Returns:**
    - product sales price per unit


---

### getPricePercentage(Money, Money)
- ~~getPricePercentage(basePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), comparePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~
  - : Calculates and returns the percentage off amount of the passed
      comparePrice to the passed basePrice.


    **Parameters:**
    - basePrice - The assumed 100% price amount
    - comparePrice - The price to compare to the basePrice

    **Returns:**
    - The percentage between comparePrice and basePrice (e.g. 90%).

    **Deprecated:**
**warning:** Use [Money.percentLessThan(Money)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md#percentlessthanmoney)

---

### getPriceTable()
- getPriceTable(): [ProductPriceTable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md)
  - : Returns the product price table object. The price table represents a map
      between order quantities and prices, and also provides % off information
      to be shown to storefront customers. The price is returned for the
      currency of the current session.
      
      
      Usually, the product price table is printed on product detail pages in
      the storefront.
      
      
      If the product represented by this model is an option product, option
      prices will be added to the price book price if the price model was
      initialized with an option model.
      
      
      All other methods of this class are based on the information in the
      product price table.


    **Returns:**
    - the Product price table.


---

### isPriceRange()
- isPriceRange(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this product is a master product (or product set) and the
      collection of online variants (or set products respectively) contains
      products of different prices.
      
      
      **Warning:**  If the product represented by this model is a master
      product with numerous variants, this method can be very expensive and
      should be avoided.


    **Returns:**
    - True if this product has a range of prices, false otherwise.


---

### isPriceRange(String)
- isPriceRange(priceBookID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this product is a master product (or product set) and the
      collection of online variants (or set products respectively) contains
      products of different prices in the specified price book.


    **Parameters:**
    - priceBookID - The ID of the price book.

    **Returns:**
    - True if this product has a range of prices, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=1ca3d56e8041c41133ecbe6ae3543d204465aa03be525dc6ebc26ffd13146939 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductPriceTable.md -->

<!-- prettier-ignore-start -->
# Class ProductPriceTable

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductPriceTable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md)

A ProductPriceTable is a map of quantities to prices representing the
potentially tiered prices of a product in Commerce Cloud Digital. The price
of a product is the price associated with the largest quantity in
the ProductPriceTable which does not exceed the purchase quantity.



## Property Summary

| Property | Description |
| --- | --- |
| [quantities](#quantities): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all quantities stored in the price table. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getNextQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md#getnextquantityquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the quantity following the passed quantity in the price table. |
| [getPercentage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md#getpercentagequantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the percentage off value of the price related to the passed quantity,  calculated based on the price of the products minimum order quantity. |
| [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md#getpricequantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the monetary price for the passed order quantity. |
| [getPriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md#getpricebookquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Returns the price book which defined the monetary price for the passed  order quantity. |
| [getQuantities](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md#getquantities)() | Returns all quantities stored in the price table. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### quantities
- quantities: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all quantities stored in the price table.


---

## Method Details

### getNextQuantity(Quantity)
- getNextQuantity(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity following the passed quantity in the price table.
      If the passed quantity is the last entry in the price table, null is
      returned.


    **Parameters:**
    - quantity - the quantity to use to locate the next quantity in the price table.

    **Returns:**
    - the next quantity or null.


---

### getPercentage(Quantity)
- getPercentage(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the percentage off value of the price related to the passed quantity,
      calculated based on the price of the products minimum order quantity.


    **Parameters:**
    - quantity - the price quantity to compute the percentage off.

    **Returns:**
    - the percentage off value of the price related to the passed quantity.


---

### getPrice(Quantity)
- getPrice(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the monetary price for the passed order quantity. If
      no price is defined for the passed quantity, null is returned. This
      can happen if for example no price is defined for a single item.


    **Parameters:**
    - quantity - the quantity to use to determine price.

    **Returns:**
    - price amount for the passed quantity


---

### getPriceBook(Quantity)
- getPriceBook(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)
  - : Returns the price book which defined the monetary price for the passed
      order quantity. If no price is defined for the passed quantity, null is
      returned. This can happen if for example no price is defined for a single
      item.


    **Parameters:**
    - quantity - the quantity to use to determine price.

    **Returns:**
    - the price book defining this price, or null


---

### getQuantities()
- getQuantities(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all quantities stored in the price table.

    **Returns:**
    - all price table quantities.


---

<!-- prettier-ignore-end -->

<!-- document id=a802fef9909a631759ddb438bca813e332d9a556a61cb4bf590a31769d760c07 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductSearchHit.md -->

<!-- prettier-ignore-start -->
# Class ProductSearchHit

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md)

ProductSearchHit is the result of a executed search query and wraps the actual product found by the search.

The method [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) returns the actual products that is conforming the query and is represented by the search hit.
Depending on the hit typ, [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) returns:
 
- [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
- [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation product
- [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product part of set
- [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product part of a bundle
- [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)-> a variation product


The ProductSearchHit type can be retrieved by method [getHitType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#gethittype) and contains the following types:

- [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)
- [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)
- [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)
- [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)
- [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)


The method [getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getproduct) returns the presentation product corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type.

- [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
- [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation master product
- [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product set
- [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product bundle
- [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation group


Example:

Given a product master P1 called "Sweater" with attributes color and size that has the following variants:

- V1 - color: red, size: small
- V2 - color: red, size: large
- V3 - color: blue, size: small
- V4 - color: blue, size: large
- V5 - color: yellow, size: small
- V6 - color: yellow, size: large


A search for "red sweater" should hit the first two variants, V1 and V2
that are both red. The ProductSearchHit for this result encompass the master and the red variants but not the other
non-relevant variants.

The variants hit by the query can be retrieved by [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts), returning a list that contains the two red sweater variants.

The master product "Sweater" is returned by [getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getproduct).

Furthermore, to get the first or last of that list of variants hit by the query we can call
[getFirstRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproduct) or [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct). The product with the highest
sort rank is returned first, and the product with the lowest sort rank is
returned last. The product sort rank depends on the sorting conditions
used for the search query.



## Constant Summary

| Constant | Description |
| --- | --- |
| [HIT_TYPE_PRODUCT_BUNDLE](#hit_type_product_bundle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bundle" | Constant representing a product search hit type based on the presentation product of a hit. |
| [HIT_TYPE_PRODUCT_MASTER](#hit_type_product_master): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "master" | Constant representing a product search hit type based on the presentation product of a hit. |
| [HIT_TYPE_PRODUCT_SET](#hit_type_product_set): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "set" | Constant representing a product search hit type based on the presentation product of a hit. |
| [HIT_TYPE_SIMPLE](#hit_type_simple): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "product" | Constant representing a product search hit type based on the presentation product of a hit. |
| ~~[HIT_TYPE_SLICING_GROUP](#hit_type_slicing_group): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "slicing_group"~~ | Constant representing a product search hit type based on the presentation product of a hit. |
| [HIT_TYPE_VARIATION_GROUP](#hit_type_variation_group): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "variation_group" | Constant representing a product search hit type based on the presentation product of a hit. |

## Property Summary

| Property | Description |
| --- | --- |
| [firstRepresentedProduct](#firstrepresentedproduct): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the product that is actually hit by the search and has the highest  sort rank according to the sorting conditions used for the search query. |
| [firstRepresentedProductID](#firstrepresentedproductid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product that is actually hit by the search and has the highest  sort rank according to the sorting conditions used for the search query. |
| [hitType](#hittype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of the product wrapped by this search hit. |
| [lastRepresentedProduct](#lastrepresentedproduct): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the product that is actually hit by the search and has the lowest  sort rank according to the sorting conditions used for the search query. |
| [lastRepresentedProductID](#lastrepresentedproductid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product that is actually hit by the search and has the lowest  sort rank according to the sorting conditions used for the search query. |
| [maxPrice](#maxprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the maximum price of all products represented by the  product hit. |
| [maxPricePerUnit](#maxpriceperunit): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the maximum price per unit of all products represented by the  product hit. |
| [minPrice](#minprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the minimum price of all products represented by the  product hit. |
| [minPricePerUnit](#minpriceperunit): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the minimum price per unit of all products represented by the  product hit. |
| [priceRange](#pricerange): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Convenience method to check whether this ProductSearchHit represents  multiple products (see [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)) that have  different prices. |
| [product](#product): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type. |
| [productID](#productid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type. |
| [representedProductIDs](#representedproductids): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | The method returns the actual ID of the product that is conforming the query and is represented by the search hit. |
| [representedProducts](#representedproducts): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | The method returns the actual product that is conforming the query and is represented by the search hit. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getFirstRepresentedProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproduct)() | Returns the product that is actually hit by the search and has the highest  sort rank according to the sorting conditions used for the search query. |
| [getFirstRepresentedProductID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproductid)() | Returns the ID of the product that is actually hit by the search and has the highest  sort rank according to the sorting conditions used for the search query. |
| [getHitType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#gethittype)() | Returns the type of the product wrapped by this search hit. |
| [getLastRepresentedProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)() | Returns the product that is actually hit by the search and has the lowest  sort rank according to the sorting conditions used for the search query. |
| [getLastRepresentedProductID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproductid)() | Returns the ID of the product that is actually hit by the search and has the lowest  sort rank according to the sorting conditions used for the search query. |
| [getMaxPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getmaxprice)() | Returns the maximum price of all products represented by the  product hit. |
| [getMaxPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getmaxpriceperunit)() | Returns the maximum price per unit of all products represented by the  product hit. |
| [getMinPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getminprice)() | Returns the minimum price of all products represented by the  product hit. |
| [getMinPricePerUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getminpriceperunit)() | Returns the minimum price per unit of all products represented by the  product hit. |
| [getProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getproduct)() | Returns the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type. |
| [getProductID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getproductid)() | Returns the ID of the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type. |
| [getRepresentedProductIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproductids)() | The method returns the actual ID of the product that is conforming the query and is represented by the search hit. |
| [getRepresentedProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)() | The method returns the actual product that is conforming the query and is represented by the search hit. |
| [getRepresentedVariationValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedvariationvaluesobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | This method is only applicable if this ProductSearchHit represents a  product variation (see [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)). |
| [isPriceRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#ispricerange)() | Convenience method to check whether this ProductSearchHit represents  multiple products (see [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)) that have  different prices. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### HIT_TYPE_PRODUCT_BUNDLE

- HIT_TYPE_PRODUCT_BUNDLE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bundle"
  - : Constant representing a product search hit type based on the presentation product of a hit. This hit type is used with product bundles.


---

### HIT_TYPE_PRODUCT_MASTER

- HIT_TYPE_PRODUCT_MASTER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "master"
  - : Constant representing a product search hit type based on the presentation product of a hit. This hit type is used with master products.


---

### HIT_TYPE_PRODUCT_SET

- HIT_TYPE_PRODUCT_SET: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "set"
  - : Constant representing a product search hit type based on the presentation product of a hit. This hit type is used with product sets.


---

### HIT_TYPE_SIMPLE

- HIT_TYPE_SIMPLE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "product"
  - : Constant representing a product search hit type based on the presentation product of a hit. This hit type is used with single, non-complex products, including product variants that
      are assigned to a category and are returned as the presentation product.



---

### HIT_TYPE_SLICING_GROUP

- ~~HIT_TYPE_SLICING_GROUP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "slicing_group"~~
  - : Constant representing a product search hit type based on the presentation product of a hit. This hit type is used with slicing groups.

    **Deprecated:**
**warning:** Please use [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group) instead.

---

### HIT_TYPE_VARIATION_GROUP

- HIT_TYPE_VARIATION_GROUP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "variation_group"
  - : Constant representing a product search hit type based on the presentation product of a hit. This hit type is used with variation groups.


---

## Property Details

### firstRepresentedProduct
- firstRepresentedProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the product that is actually hit by the search and has the highest
      sort rank according to the sorting conditions used for the search query.


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### firstRepresentedProductID
- firstRepresentedProductID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product that is actually hit by the search and has the highest
      sort rank according to the sorting conditions used for the search query.


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### hitType
- hitType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of the product wrapped by this search hit. The product type returned will be one of the hit types: 
      
      
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)  - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)    - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)        - [HIT_TYPE_SLICING_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_slicing_group)          - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)



---

### lastRepresentedProduct
- lastRepresentedProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the product that is actually hit by the search and has the lowest
      sort rank according to the sorting conditions used for the search query.


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### lastRepresentedProductID
- lastRepresentedProductID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product that is actually hit by the search and has the lowest
      sort rank according to the sorting conditions used for the search query.


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### maxPrice
- maxPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the maximum price of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the maximum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: The method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.



---

### maxPricePerUnit
- maxPricePerUnit: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the maximum price per unit of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the maximum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: The method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.



---

### minPrice
- minPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the minimum price of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the minimum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: the method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.



---

### minPricePerUnit
- minPricePerUnit: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the minimum price per unit of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the minimum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: the method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.



---

### priceRange
- priceRange: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Convenience method to check whether this ProductSearchHit represents
      multiple products (see [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)) that have
      different prices.



---

### product
- product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type.
      
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation master product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation group
      
      
      To retrieve the product(s) actually hit by the search use [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts).


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)


---

### productID
- productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type.
      
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation master product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation group
      
      
      To retrieve the ID of the product actually hit by the search use [getFirstRepresentedProductID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproductid) or [getLastRepresentedProductID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproductid).


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)


---

### representedProductIDs
- representedProductIDs: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : The method returns the actual ID of the product that is conforming the query and is represented by the search hit.
      Depending on the hit typ, it returns the ID of:
       
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product part of set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product part of a bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation product
      
      
      If the method returns multiple products, the product with the highest
      sort rank is returned first, and the product with the lowest sort rank is
      returned last. The product sort rank depends on the sorting conditions
      used for the search query.


    **See Also:**
    - [getFirstRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproduct)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### representedProducts
- representedProducts: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : The method returns the actual product that is conforming the query and is represented by the search hit.
      Depending on the hit typ, [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) returns:
       
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product part of set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product part of a bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation product
      
      
      If the method returns multiple products, the product with the highest
      sort rank is returned first, and the product with the lowest sort rank is
      returned last. The product sort rank depends on the sorting conditions
      used for the search query.


    **See Also:**
    - [getFirstRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproduct)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

## Method Details

### getFirstRepresentedProduct()
- getFirstRepresentedProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the product that is actually hit by the search and has the highest
      sort rank according to the sorting conditions used for the search query.


    **Returns:**
    - the first product that is actually hit by the search

    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### getFirstRepresentedProductID()
- getFirstRepresentedProductID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product that is actually hit by the search and has the highest
      sort rank according to the sorting conditions used for the search query.


    **Returns:**
    - the ID of the first product that is actually hit by the search

    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### getHitType()
- getHitType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the product wrapped by this search hit. The product type returned will be one of the hit types: 
      
      
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)  - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)    - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)        - [HIT_TYPE_SLICING_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_slicing_group)          - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)


    **Returns:**
    - search hit type


---

### getLastRepresentedProduct()
- getLastRepresentedProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the product that is actually hit by the search and has the lowest
      sort rank according to the sorting conditions used for the search query.


    **Returns:**
    - the last product that is actually hit by the search

    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### getLastRepresentedProductID()
- getLastRepresentedProductID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product that is actually hit by the search and has the lowest
      sort rank according to the sorting conditions used for the search query.


    **Returns:**
    - the ID of the last product that is actually hit by the search

    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### getMaxPrice()
- getMaxPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the maximum price of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the maximum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: The method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.


    **Returns:**
    - the maximum price of all products represented by the product hit.


---

### getMaxPricePerUnit()
- getMaxPricePerUnit(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the maximum price per unit of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the maximum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: The method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.


    **Returns:**
    - the maximum price per unit of all products represented by the product hit.


---

### getMinPrice()
- getMinPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the minimum price of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the minimum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: the method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.


    **Returns:**
    - the minimum price of all products represented by the product hit.


---

### getMinPricePerUnit()
- getMinPricePerUnit(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the minimum price per unit of all products represented by the
      product hit. See [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) for details on
      the set of products used for finding the minimum. The method returns
      `N/A` in case no price information can be found.
      
      
      Note: the method uses price information of the search index and therefore
      might return different prices than the ProductPriceModel.


    **Returns:**
    - the minimum price per unit of all products represented by the product hit.


---

### getProduct()
- getProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type.
      
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation master product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation group
      
      
      To retrieve the product(s) actually hit by the search use [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts).


    **Returns:**
    - the presentation product of this ProductSearchHit, which is possibly a
              representative of other related products actually hit by the
              search.


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)


---

### getProductID()
- getProductID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the presentation product of this ProductSearchHit corresponding to the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) type.
      
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation master product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation group
      
      
      To retrieve the ID of the product actually hit by the search use [getFirstRepresentedProductID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproductid) or [getLastRepresentedProductID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproductid).


    **Returns:**
    - the ID of the presentation product of this ProductSearchHit, that possibly represents
              a set of related products actually hit by the search.


    **See Also:**
    - [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)


---

### getRepresentedProductIDs()
- getRepresentedProductIDs(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : The method returns the actual ID of the product that is conforming the query and is represented by the search hit.
      Depending on the hit typ, it returns the ID of:
       
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product part of set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product part of a bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation product
      
      
      If the method returns multiple products, the product with the highest
      sort rank is returned first, and the product with the lowest sort rank is
      returned last. The product sort rank depends on the sorting conditions
      used for the search query.


    **Returns:**
    - a sorted list of products represented by the wrapped product.

    **See Also:**
    - [getFirstRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproduct)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### getRepresentedProducts()
- getRepresentedProducts(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : The method returns the actual product that is conforming the query and is represented by the search hit.
      Depending on the hit typ, [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts) returns:
       
      - [HIT_TYPE_SIMPLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_simple)-> a simple product 
      - [HIT_TYPE_PRODUCT_MASTER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_master)-> a variation product
      - [HIT_TYPE_PRODUCT_SET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_set)-> a product part of set
      - [HIT_TYPE_PRODUCT_BUNDLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_product_bundle)-> a product part of a bundle
      - [HIT_TYPE_VARIATION_GROUP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#hit_type_variation_group)->a variation product
      
      
      If the method returns multiple products, the product with the highest
      sort rank is returned first, and the product with the lowest sort rank is
      returned last. The product sort rank depends on the sorting conditions
      used for the search query.


    **Returns:**
    - a sorted list of products represented by the wrapped product.

    **See Also:**
    - [getFirstRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getfirstrepresentedproduct)
    - [getLastRepresentedProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getlastrepresentedproduct)


---

### getRepresentedVariationValues(Object)
- getRepresentedVariationValues(va: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : This method is only applicable if this ProductSearchHit represents a
      product variation (see [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)). It returns the
      distinct value set for the specified variation attribute for all variants
      represented by this ProductSearchHit. The values are returned in the same
      order as they are defined for the variation.
      
      
      This method will accept a ProductVariationAttribute parameter or a String
      which is the ID of a variation attribute. If any other object type is
      passed, or null is passed, an exception will be thrown. If this
      ProductSearchHit does not represent a product variation, or the passed
      variation attribute is not associated with this product, the method
      returns an empty list.


    **Parameters:**
    - va - the product variation attribute, specified as either a             ProductVariationAttribute or a String which is the ID of a             variation attribute associated with this product.

    **Returns:**
    - a list containing all distinct ProductVariationAttributeValues.


---

### isPriceRange()
- isPriceRange(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Convenience method to check whether this ProductSearchHit represents
      multiple products (see [getRepresentedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getrepresentedproducts)) that have
      different prices.


    **Returns:**
    - `true` if the represented products form a price range
              `false` otherwise.



---

<!-- prettier-ignore-end -->

<!-- document id=815e41fd4116c428a7505a74679500529ed4946691e60e5e8040c3dac68503f8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductSearchModel.md -->

<!-- prettier-ignore-start -->
# Class ProductSearchModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md)
    - [dw.catalog.ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md)

The class is the central interface to a product search result and a product
search refinement. It also provides utility methods to generate a search URL.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CATEGORYID_PARAMETER](#categoryid_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cgid" | URL Parameter for the category ID |
| [INVENTORY_LIST_IDS_PARAMETER](#inventory_list_ids_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ilids" | URL Parameter for the inventory list IDs |
| [MAXIMUM_INVENTORY_LIST_IDS](#maximum_inventory_list_ids): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | The maximum number of inventory list IDs that can be passed to [setInventoryListIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setinventorylistidslist) |
| [MAXIMUM_PRODUCT_IDS](#maximum_product_ids): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 30 | The maximum number of product IDs that can be passed to [setProductIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setproductidslist) |
| [MAXIMUM_STORE_INVENTORY_FILTER_VALUES](#maximum_store_inventory_filter_values): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | The maximum number of store inventory values for a store inventory filter that can be passed to  [setStoreInventoryFilter(StoreInventoryFilter)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setstoreinventoryfilterstoreinventoryfilter) |
| [PRICE_MAX_PARAMETER](#price_max_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmax" | URL Parameter for the maximum price |
| [PRICE_MIN_PARAMETER](#price_min_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmin" | URL Parameter for the minimum price |
| [PRODUCTID_PARAMETER](#productid_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pid" | URL Parameter for the product ID |
| [PROMOTIONID_PARAMETER](#promotionid_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmid" | URL Parameter for the promotion ID |
| [PROMOTION_PRODUCT_TYPE_ALL](#promotion_product_type_all): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "all" | constant indicating that all related products should be returned for the next product search by promotion ID |
| [PROMOTION_PRODUCT_TYPE_BONUS](#promotion_product_type_bonus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bonus" | constant indicating that only bonus products should be returned for the next product search by promotion ID. |
| [PROMOTION_PRODUCT_TYPE_DISCOUNTED](#promotion_product_type_discounted): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "discounted" | constant indicating that only discounted products should be returned for the next product search by promotion ID |
| [PROMOTION_PRODUCT_TYPE_PARAMETER](#promotion_product_type_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmpt" | URL Parameter for the promotion product type |
| [PROMOTION_PRODUCT_TYPE_QUALIFYING](#promotion_product_type_qualifying): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "qualifying" | constant indicating that only qualifying products should be returned for the next product search by promotion ID |
| [REFINE_NAME_PARAMETER_PREFIX](#refine_name_parameter_prefix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "prefn" | URL Parameter prefix for a refinement name |
| [REFINE_VALUE_PARAMETER_PREFIX](#refine_value_parameter_prefix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "prefv" | URL Parameter prefix for a refinement value |
| [SORTING_OPTION_PARAMETER](#sorting_option_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sopt" | URL Parameter prefix for a sorting option |
| [SORTING_RULE_PARAMETER](#sorting_rule_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "srule" | URL Parameter prefix for a sorting rule |
| [SORT_BY_PARAMETER_PREFIX](#sort_by_parameter_prefix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "psortb" | URL Parameter prefix for a refinement value |
| [SORT_DIRECTION_PARAMETER_PREFIX](#sort_direction_parameter_prefix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "psortd" | URL Parameter prefix for a refinement value |

## Property Summary

| Property | Description |
| --- | --- |
| [category](#category): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the category object for the category id specified in the query. |
| [categoryID](#categoryid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the category id that was specified in the search query. |
| [categorySearch](#categorysearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method returns true, if this is a pure search for a category. |
| [deepestCommonCategory](#deepestcommoncategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the deepest common category of all products in the search result. |
| [effectiveSearchMode](#effectivesearchmode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the effective search mode that was used for the last search execution. |
| [effectiveSortingRule](#effectivesortingrule): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md) `(read-only)` | Returns the sorting rule used to order the products in the results of this query,  or `null` if no search has been executed yet. |
| [inventoryIDs](#inventoryids): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | <p>  Returns a list of inventory IDs that were specified in the search query or an empty list if no inventory ID set. |
| [orderableProductsOnly](#orderableproductsonly): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Get the flag indicating whether unorderable products should be excluded  when the next call to getProducts() is made. |
| [pageMetaTags](#pagemetatags): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)` | Returns all page meta tags, defined for this instance for which content can be generated. |
| [personalizedSort](#personalizedsort): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method indicates if the search result is ordered by a personalized sorting rule. |
| [priceMax](#pricemax): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the maximum price by which the search result is refined. |
| [priceMin](#pricemin): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the minimum price by which the search result is refined. |
| ~~[productID](#productid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Returns the product id that was specified in the search query. |
| [productIDs](#productids): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Returns a list of product IDs that were specified in the search query or an empty list if no product ID set. |
| [productSearchHits](#productsearchhits): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Returns the product search hits in the search result. |
| ~~[products](#products): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~ `(read-only)` | Returns all products in the search result. |
| [promotionID](#promotionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the promotion id that was specified in the search query or null if no promotion id set. |
| [promotionIDs](#promotionids): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Returns a list of promotion id's that were specified in the search query or an empty list if no promotion id set. |
| [promotionProductType](#promotionproducttype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the promotion product type specified in the search query. |
| [recursiveCategorySearch](#recursivecategorysearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Get the flag that determines if the category search will  be recursive. |
| [refinedByCategory](#refinedbycategory): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method returns true, if the search is refined by a category. |
| [refinedByPrice](#refinedbyprice): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this search has been refined by price. |
| [refinedByPromotion](#refinedbypromotion): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this search has been refined by promotion. |
| [refinedCategorySearch](#refinedcategorysearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is a category search and is refined with further  criteria, like a brand refinement or an attribute refinement. |
| [refinementCategory](#refinementcategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) | Returns the category used to determine possible refinements for the search. |
| [refinements](#refinements): [ProductSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md) `(read-only)` | Returns the ProductSearchRefinements associated with this search and filtered by session currency. |
| [searchMode](#searchmode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the search mode that was requested for the next search execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsearchmodestring), or  `null` if no mode was explicitly requested. |
| [searchPhraseSuggestions](#searchphrasesuggestions): [SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md) `(read-only)` | Returns search phrase suggestions for the current search phrase. |
| [searchableImageUploadURL](#searchableimageuploadurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | This method returns the URL of the endpoint where the merchants should upload their image for visual search. |
| [sortingRule](#sortingrule): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md) | Returns the sorting rule explicitly set on this model to be used  to order the products in the results of this query, or `null`  if no rule has been explicitly set. |
| [storeInventoryFilter](#storeinventoryfilter): [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md) | <p>  Returns the [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md), which was specified for this search. |
| ~~[suggestedSearchPhrase](#suggestedsearchphrase): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | Returns the suggested search phrase with the highest accuracy provided  for the current search phrase. |
| ~~[suggestedSearchPhrases](#suggestedsearchphrases): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)~~ `(read-only)` | Returns a list with up to 5 suggested search phrases provided for the  current search phrase. |
| [trackingEmptySearchesEnabled](#trackingemptysearchesenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method indicates if no-hits search should be tracked for predictive intelligence use. |
| [visualSearch](#visualsearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method returns true, if this is a visual search. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ProductSearchModel](#productsearchmodel)() | Constructs a new ProductSearchModel. |

## Method Summary

| Method | Description |
| --- | --- |
| [addHitTypeRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#addhittyperefinementstring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the only search hit types to be included from the search. |
| [excludeHitType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#excludehittypestring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the search hit types to be excluded from the search. |
| [getCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getcategory)() | Returns the category object for the category id specified in the query. |
| [getCategoryID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getcategoryid)() | Returns the category id that was specified in the search query. |
| [getDeepestCommonCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getdeepestcommoncategory)() | Returns the deepest common category of all products in the search result. |
| [getEffectiveSearchMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#geteffectivesearchmode)() | Returns the effective search mode that was used for the last search execution. |
| [getEffectiveSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#geteffectivesortingrule)() | Returns the sorting rule used to order the products in the results of this query,  or `null` if no search has been executed yet. |
| [getInventoryIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getinventoryids)() | <p>  Returns a list of inventory IDs that were specified in the search query or an empty list if no inventory ID set. |
| [getOrderableProductsOnly](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getorderableproductsonly)() | Get the flag indicating whether unorderable products should be excluded  when the next call to getProducts() is made. |
| [getPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpagemetatagstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the page meta tag for the specified id. |
| [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpagemetatags)() | Returns all page meta tags, defined for this instance for which content can be generated. |
| [getPriceMax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpricemax)() | Returns the maximum price by which the search result is refined. |
| [getPriceMin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpricemin)() | Returns the minimum price by which the search result is refined. |
| ~~[getProductID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductid)()~~ | Returns the product id that was specified in the search query. |
| [getProductIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductids)() | Returns a list of product IDs that were specified in the search query or an empty list if no product ID set. |
| [getProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductsearchhitproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the underlying ProductSearchHit for a product, or null if no  ProductSearchHit found for this product. |
| [getProductSearchHits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductsearchhits)() | Returns the product search hits in the search result. |
| ~~[getProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproducts)()~~ | Returns all products in the search result. |
| [getPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpromotionid)() | Returns the promotion id that was specified in the search query or null if no promotion id set. |
| [getPromotionIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpromotionids)() | Returns a list of promotion id's that were specified in the search query or an empty list if no promotion id set. |
| [getPromotionProductType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpromotionproducttype)() | Returns the promotion product type specified in the search query. |
| [getRefinementCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getrefinementcategory)() | Returns the category used to determine possible refinements for the search. |
| [getRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getrefinements)() | Returns the ProductSearchRefinements associated with this search and filtered by session currency. |
| [getSearchMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsearchmode)() | Returns the search mode that was requested for the next search execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsearchmodestring), or  `null` if no mode was explicitly requested. |
| [getSearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsearchphrasesuggestions)() | Returns search phrase suggestions for the current search phrase. |
| [getSearchableImageUploadURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsearchableimageuploadurl)() | This method returns the URL of the endpoint where the merchants should upload their image for visual search. |
| [getSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsortingrule)() | Returns the sorting rule explicitly set on this model to be used  to order the products in the results of this query, or `null`  if no rule has been explicitly set. |
| [getStoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getstoreinventoryfilter)() | <p>  Returns the [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md), which was specified for this search. |
| ~~[getSuggestedSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsuggestedsearchphrase)()~~ | Returns the suggested search phrase with the highest accuracy provided  for the current search phrase. |
| ~~[getSuggestedSearchPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsuggestedsearchphrases)()~~ | Returns a list with up to 5 suggested search phrases provided for the  current search phrase. |
| [isCategorySearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#iscategorysearch)() | The method returns true, if this is a pure search for a category. |
| [isPersonalizedSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#ispersonalizedsort)() | The method indicates if the search result is ordered by a personalized sorting rule. |
| [isRecursiveCategorySearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isrecursivecategorysearch)() | Get the flag that determines if the category search will  be recursive. |
| [isRefinedByCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isrefinedbycategory)() | The method returns true, if the search is refined by a category. |
| [isRefinedByPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isrefinedbyprice)() | Identifies if this search has been refined by price. |
| [isRefinedByPriceRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isrefinedbypricerangenumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Identifies if this search has been refined by the given price range. |
| [isRefinedByPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isrefinedbypromotion)() | Identifies if this search has been refined by promotion. |
| [isRefinedByPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isrefinedbypromotionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if this search has been refined by a given promotion. |
| [isRefinedCategorySearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isrefinedcategorysearch)() | Identifies if this is a category search and is refined with further  criteria, like a brand refinement or an attribute refinement. |
| [isTrackingEmptySearchesEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#istrackingemptysearchesenabled)() | The method indicates if no-hits search should be tracked for predictive intelligence use. |
| [isVisualSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#isvisualsearch)() | The method returns true, if this is a visual search. |
| [search](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#search)() | Execute the search based on the configured search term, category and filter conditions (price, attribute,  promotion, product type) and return the execution status. |
| [setCategoryID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setcategoryidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Specifies the category id used for the search query. |
| [setEnableTrackingEmptySearches](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setenabletrackingemptysearchesboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set a flag indicating whether no-hits search should be tracked for predictive intelligence use. |
| [setInventoryListIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setinventorylistidslist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | <p>  Specifies multiple inventory list IDs used for the search query. |
| [setOrderableProductsOnly](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setorderableproductsonlyboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set a flag indicating whether unorderable products should be excluded  when the next call to getProducts() is made. |
| [setPriceMax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpricemaxnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the maximum price by which the search result is to be refined. |
| [setPriceMin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpriceminnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the minimum price by which the search result is to be refined. |
| ~~[setProductID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setproductidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Specifies the product id used for the search query. |
| [setProductIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setproductidslist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Specifies multiple product IDs used for the search query. |
| [setPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Specifies the promotion id used for the search query. |
| [setPromotionIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidslist)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Specifies multiple promotion id's used for the search query. |
| [setPromotionProductType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionproducttypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Specifies the promotion product type used for the search query. |
| [setRecursiveCategorySearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrecursivecategorysearchboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set a flag to indicate if the search in category should be recursive. |
| [setRefinementCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrefinementcategorycategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)) | Sets an explicit category to be used when determining refinements. |
| [setSearchMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsearchmodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the search mode for the next search execution. |
| [setSearchableImageID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsearchableimageidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | An image ID can be retrieved by uploading an image with a multipart/form-data POST  request to 'https://api.cquotient.com/v3/image/search/upload/{siteID}'. |
| ~~[setSortingCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsortingconditionstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Sets or removes a sorting condition for the specified attribute. |
| [setSortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsortingoptionsortingoption)([SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)) | Sets the sorting option to be used to order the products in the results of this query. |
| [setSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsortingrulesortingrule)([SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)) | Sets the sorting rule to be used to order the products in the  results of this query. |
| [setStoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setstoreinventoryfilterstoreinventoryfilter)([StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)) | <p>  Filters the search result by one or more inventory list IDs provided by the class [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)  which supports a semantic URL parameter like zip, city, store ... |
| static [urlForCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlforcategoryurl-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to execute a query for a specific  Category. |
| static [urlForCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlforcategorystring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to execute a query for a specific  Category. |
| static [urlForProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlforproducturl-string-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to execute a query for a specific  Product. |
| static [urlForProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlforproductstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to execute a query for a specific  Product. |
| static [urlForRefine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlforrefineurl-string-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to execute a query for a specific  attribute name-value pair. |
| static [urlForRefine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlforrefinestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to execute a query for a specific  attribute name-value pair. |
| [urlRefineCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinecategoryurl-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to re-execute the query with a  category refinement. |
| [urlRefineCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinecategorystring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to re-execute the query with a  category refinement. |
| [urlRefinePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinepriceurl-number-number)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a URL that you can use to re-execute the query with an  additional price filter. |
| [urlRefinePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinepricestring-number-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a URL that you can use to re-execute the query with an  additional price filter. |
| [urlRefinePromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinepromotionurl-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to re-execute the query with a promotion refinement. |
| [urlRefinePromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinepromotionstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to re-execute the query with a promotion refinement. |
| [urlRelaxCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxcategoryurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Constructs a URL that you can use to re-execute the query without any  category refinement. |
| [urlRelaxCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxcategorystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to re-execute the query without any  category refinement. |
| [urlRelaxPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxpriceurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Constructs a URL that you can use to would re-execute the query with no  price filter. |
| [urlRelaxPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxpricestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to re-execute the query with no price  filter. |
| [urlRelaxPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxpromotionurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Constructs a URL that you can use to re-execute the query without any promotion refinement. |
| [urlRelaxPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxpromotionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a URL that you can use to re-execute the query without any promotion refinement. |
| [urlSortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlsortingoptionurl-sortingoption)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)) | Constructs a URL that you can use to re-execute the query but sort  the results by the given storefront sorting option. |
| [urlSortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlsortingoptionstring-sortingoption)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)) | Constructs a URL that you can use to re-execute the query but sort the  results by the given storefront sorting option. |
| [urlSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlsortingruleurl-sortingrule)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)) | Constructs a URL that you can use to re-execute the query but sort  the results by the given rule. |
| [urlSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlsortingrulestring-sortingrule)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)) | Constructs a URL that you can use to re-execute the query but sort the  results by the given rule. |

### Methods inherited from class SearchModel

[addRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#addrefinementvaluesstring-string), [canRelax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#canrelax), [getCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getcount), [getRefinementMaxValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementmaxvaluestring), [getRefinementMinValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementminvaluestring), [getRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluestring), [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluesstring), [getSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsearchphrase), [getSearchRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsearchredirectstring), [getSortingCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsortingconditionstring), [isEmptyQuery](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isemptyquery), [isRefinedByAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattribute), [isRefinedByAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattributestring), [isRefinedByAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattributevaluestring-string), [isRefinedSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedsearch), [isRefinementByValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinementbyvaluerangestring), [isRefinementByValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinementbyvaluerangestring-string-string), [removeRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#removerefinementvaluesstring-string), [search](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#search), [setRefinementValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setrefinementvaluerangestring-string-string), [setRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setrefinementvaluesstring-string), [setSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setsearchphrasestring), [setSortingCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setsortingconditionstring-number), [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlurl), [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlstring), [urlDefaultSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urldefaultsorturl), [urlDefaultSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urldefaultsortstring), [urlRefineAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributeurl-string-string), [urlRefineAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributestring-string-string), [urlRefineAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevalueurl-string-string), [urlRefineAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevaluestring-string-string), [urlRefineAttributeValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevaluerangestring-string-string-string), [urlRelaxAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributeurl-string), [urlRelaxAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributestring-string), [urlRelaxAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributevalueurl-string-string), [urlRelaxAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributevaluestring-string-string), [urlSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlsorturl-string-number), [urlSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlsortstring-string-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CATEGORYID_PARAMETER

- CATEGORYID_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cgid"
  - : URL Parameter for the category ID


---

### INVENTORY_LIST_IDS_PARAMETER

- INVENTORY_LIST_IDS_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ilids"
  - : URL Parameter for the inventory list IDs


---

### MAXIMUM_INVENTORY_LIST_IDS

- MAXIMUM_INVENTORY_LIST_IDS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : The maximum number of inventory list IDs that can be passed to [setInventoryListIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setinventorylistidslist)


---

### MAXIMUM_PRODUCT_IDS

- MAXIMUM_PRODUCT_IDS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 30
  - : The maximum number of product IDs that can be passed to [setProductIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setproductidslist)


---

### MAXIMUM_STORE_INVENTORY_FILTER_VALUES

- MAXIMUM_STORE_INVENTORY_FILTER_VALUES: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : The maximum number of store inventory values for a store inventory filter that can be passed to
      [setStoreInventoryFilter(StoreInventoryFilter)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setstoreinventoryfilterstoreinventoryfilter)



---

### PRICE_MAX_PARAMETER

- PRICE_MAX_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmax"
  - : URL Parameter for the maximum price


---

### PRICE_MIN_PARAMETER

- PRICE_MIN_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmin"
  - : URL Parameter for the minimum price


---

### PRODUCTID_PARAMETER

- PRODUCTID_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pid"
  - : URL Parameter for the product ID


---

### PROMOTIONID_PARAMETER

- PROMOTIONID_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmid"
  - : URL Parameter for the promotion ID


---

### PROMOTION_PRODUCT_TYPE_ALL

- PROMOTION_PRODUCT_TYPE_ALL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "all"
  - : constant indicating that all related products should be returned for the next product search by promotion ID


---

### PROMOTION_PRODUCT_TYPE_BONUS

- PROMOTION_PRODUCT_TYPE_BONUS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bonus"
  - : constant indicating that only bonus products should be returned for the next product search by promotion ID. This
      constant should be set using [setPromotionProductType(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionproducttypestring) when using the search model to find the
      available list of bonus products for a Choice of Bonus Product (Rule) promotion, along with
      [setPromotionID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidstring).



---

### PROMOTION_PRODUCT_TYPE_DISCOUNTED

- PROMOTION_PRODUCT_TYPE_DISCOUNTED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "discounted"
  - : constant indicating that only discounted products should be returned for the next product search by promotion ID


---

### PROMOTION_PRODUCT_TYPE_PARAMETER

- PROMOTION_PRODUCT_TYPE_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "pmpt"
  - : URL Parameter for the promotion product type


---

### PROMOTION_PRODUCT_TYPE_QUALIFYING

- PROMOTION_PRODUCT_TYPE_QUALIFYING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "qualifying"
  - : constant indicating that only qualifying products should be returned for the next product search by promotion ID


---

### REFINE_NAME_PARAMETER_PREFIX

- REFINE_NAME_PARAMETER_PREFIX: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "prefn"
  - : URL Parameter prefix for a refinement name


---

### REFINE_VALUE_PARAMETER_PREFIX

- REFINE_VALUE_PARAMETER_PREFIX: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "prefv"
  - : URL Parameter prefix for a refinement value


---

### SORTING_OPTION_PARAMETER

- SORTING_OPTION_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sopt"
  - : URL Parameter prefix for a sorting option


---

### SORTING_RULE_PARAMETER

- SORTING_RULE_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "srule"
  - : URL Parameter prefix for a sorting rule


---

### SORT_BY_PARAMETER_PREFIX

- SORT_BY_PARAMETER_PREFIX: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "psortb"
  - : URL Parameter prefix for a refinement value


---

### SORT_DIRECTION_PARAMETER_PREFIX

- SORT_DIRECTION_PARAMETER_PREFIX: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "psortd"
  - : URL Parameter prefix for a refinement value


---

## Property Details

### category
- category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the category object for the category id specified in the query.
      If a category with that id doesn't exist or if the category is offline
      this method returns null.



---

### categoryID
- categoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the category id that was specified in the search query.


---

### categorySearch
- categorySearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method returns true, if this is a pure search for a category. The
      method checks, that a category ID is specified and no search phrase is
      specified.



---

### deepestCommonCategory
- deepestCommonCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the deepest common category of all products in the search result.
      In case of an empty search result the method returns the root category.



---

### effectiveSearchMode
- effectiveSearchMode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the effective search mode that was used for the last search execution. This reflects the actual matching
      approach that ran, which may differ from the requested mode if a fallback occurred. Returns `null` before
      [search()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#search) has been called.



---

### effectiveSortingRule
- effectiveSortingRule: [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md) `(read-only)`
  - : Returns the sorting rule used to order the products in the results of this query,
      or `null` if no search has been executed yet.
      
      In contrast to [getSortingRule()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsortingrule), this method respects explicit sorting rules and sorting options and rules determined implicitly
      based on the refinement category, keyword sorting rule assignment, etc.



---

### inventoryIDs
- inventoryIDs: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : 
      
      Returns a list of inventory IDs that were specified in the search query or an empty list if no inventory ID set.



---

### orderableProductsOnly
- orderableProductsOnly: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Get the flag indicating whether unorderable products should be excluded
      when the next call to getProducts() is made. If this value has not been
      previously set, then the value returned will be based on the value of the
      search preference.



---

### pageMetaTags
- pageMetaTags: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)`
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the product listing page meta tag context and rules.
      The rules are obtained from the current category context or inherited from the parent category,
      up to the root category.



---

### personalizedSort
- personalizedSort: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method indicates if the search result is ordered by a personalized sorting rule.


---

### priceMax
- priceMax: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum price by which the search result is refined.


---

### priceMin
- priceMin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the minimum price by which the search result is refined.


---

### productID
- ~~productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the product id that was specified in the search query.

    **Deprecated:**
**warning:** Please use [getProductIDs()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductids) instead

---

### productIDs
- productIDs: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list of product IDs that were specified in the search query or an empty list if no product ID set.


---

### productSearchHits
- productSearchHits: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Returns the product search hits in the search result. 
      
      Note that method does also return search hits representing products that
      were removed or went offline since the last index update, i.e. you must
      implement appropriate checks before accessing the product related to the
      search hit instance (see [ProductSearchHit.getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getproduct))


    **See Also:**
    - [getProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproducts)


---

### products
- ~~products: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~ `(read-only)`
  - : Returns all products in the search result. 
      
      Note that products that were removed or went offline since the last index
      update are not included in the returned set.


    **See Also:**
    - [getProductSearchHits()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductsearchhits)

    **Deprecated:**
**warning:** This method should not be used because loading Products for each result of a product search is
            extremely expensive performance-wise. Please use [getProductSearchHits()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductsearchhits) to iterate
            ProductSearchHits instead.

---

### promotionID
- promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the promotion id that was specified in the search query or null if no promotion id set. If multiple
      promotion id's specified the method returns only the first id. See [setPromotionIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidslist) and
      [getPromotionIDs()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpromotionids).



---

### promotionIDs
- promotionIDs: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list of promotion id's that were specified in the search query or an empty list if no promotion id set.


---

### promotionProductType
- promotionProductType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the promotion product type specified in the search query.


---

### recursiveCategorySearch
- recursiveCategorySearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Get the flag that determines if the category search will
      be recursive.



---

### refinedByCategory
- refinedByCategory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method returns true, if the search is refined by a category.
      The method checks, that a category ID is specified.



---

### refinedByPrice
- refinedByPrice: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this search has been refined by price.


---

### refinedByPromotion
- refinedByPromotion: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this search has been refined by promotion.


---

### refinedCategorySearch
- refinedCategorySearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is a category search and is refined with further
      criteria, like a brand refinement or an attribute refinement.



---

### refinementCategory
- refinementCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the category used to determine possible refinements for the search.
      If an explicit category was set for this purpose using [setRefinementCategory(Category)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrefinementcategorycategory), it is returned.
      Otherwise, the deepest common category of all search results will be returned.



---

### refinements
- refinements: [ProductSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md) `(read-only)`
  - : Returns the ProductSearchRefinements associated with this search and filtered by session currency.
      If an explicit category was set for this purpose using [setRefinementCategory(Category)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrefinementcategorycategory), it will be used to determine the refinements.
      Otherwise, the refinements are determined based on the deepest common category of all products in the search result.
      Hint: If you want to use the same refinements for all searches, consider defining them in one category (usually root) and using [setRefinementCategory(Category)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrefinementcategorycategory) to avoid unnecessary calculation of the deepest common category.



---

### searchMode
- searchMode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the search mode that was requested for the next search execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsearchmodestring), or
      `null` if no mode was explicitly requested. This reflects the caller's requested preference, not the mode
      that actually ran — the requested mode is non-authoritative and `"semantic"` may still be demoted to
      `"lexical"` by the search router. Use [getEffectiveSearchMode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#geteffectivesearchmode) to obtain the mode that was
      actually used after [search()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#search).



---

### searchPhraseSuggestions
- searchPhraseSuggestions: [SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md) `(read-only)`
  - : Returns search phrase suggestions for the current search phrase.
      Search phrase suggestions may contain alternative search phrases as well
      as lists of corrected and completed search terms.



---

### searchableImageUploadURL
- searchableImageUploadURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : This method returns the URL of the endpoint where the merchants should upload their image for visual search.


---

### sortingRule
- sortingRule: [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)
  - : Returns the sorting rule explicitly set on this model to be used
      to order the products in the results of this query, or `null`
      if no rule has been explicitly set.
      
      This method does not return the sorting rule that will be used implicitly
      based on the context of the search, such as the refinement category.



---

### storeInventoryFilter
- storeInventoryFilter: [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)
  - : 
      
      Returns the [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md), which was specified for this search.



---

### suggestedSearchPhrase
- ~~suggestedSearchPhrase: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : Returns the suggested search phrase with the highest accuracy provided
      for the current search phrase.


    **Deprecated:**
**warning:** Please use [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsearchphrasesuggestions) instead

---

### suggestedSearchPhrases
- ~~suggestedSearchPhrases: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)~~ `(read-only)`
  - : Returns a list with up to 5 suggested search phrases provided for the
      current search phrase. It is possible that less than 5 suggestions
      or even no suggestions are returned.


    **Deprecated:**
**warning:** Please use [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsearchphrasesuggestions) instead

---

### trackingEmptySearchesEnabled
- trackingEmptySearchesEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method indicates if no-hits search should be tracked for predictive intelligence use.


---

### visualSearch
- visualSearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method returns true, if this is a visual search. The
      method checks that a image UUID is specified.



---

## Constructor Details

### ProductSearchModel()
- ProductSearchModel()
  - : Constructs a new ProductSearchModel.


---

## Method Details

### addHitTypeRefinement(String...)
- addHitTypeRefinement(types: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the only search hit types to be included from the search. Values accepted are the 'hit type' constants
      exposed in the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) class. Overwrites any hit type refinements set from prior calls to
      addHitTypeRefinement(String...) or excludeHitType(String...).


    **Parameters:**
    - types - to be included.


---

### excludeHitType(String...)
- excludeHitType(types: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the search hit types to be excluded from the search. Values accepted are the 'hit type' constants exposed in
      the [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) class. Overwrites any hit type refinements set from prior calls to
      addHitTypeRefinement(String...) or excludeHitType(String...).


    **Parameters:**
    - types - to be excluded.


---

### getCategory()
- getCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the category object for the category id specified in the query.
      If a category with that id doesn't exist or if the category is offline
      this method returns null.


    **Returns:**
    - the category object for the category id specified in the query.


---

### getCategoryID()
- getCategoryID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the category id that was specified in the search query.

    **Returns:**
    - the category id that was specified in the search query.


---

### getDeepestCommonCategory()
- getDeepestCommonCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the deepest common category of all products in the search result.
      In case of an empty search result the method returns the root category.


    **Returns:**
    - the deepest common category of all products in the search result of this search model or root for an empty search result.


---

### getEffectiveSearchMode()
- getEffectiveSearchMode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the effective search mode that was used for the last search execution. This reflects the actual matching
      approach that ran, which may differ from the requested mode if a fallback occurred. Returns `null` before
      [search()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#search) has been called.


    **Returns:**
    - `"semantic"` if the query ran against the external search provider, `"lexical"` if it ran
              against the native search, or `null` if no search has been executed yet



---

### getEffectiveSortingRule()
- getEffectiveSortingRule(): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)
  - : Returns the sorting rule used to order the products in the results of this query,
      or `null` if no search has been executed yet.
      
      In contrast to [getSortingRule()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsortingrule), this method respects explicit sorting rules and sorting options and rules determined implicitly
      based on the refinement category, keyword sorting rule assignment, etc.


    **Returns:**
    - a SortingRule or null.


---

### getInventoryIDs()
- getInventoryIDs(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : 
      
      Returns a list of inventory IDs that were specified in the search query or an empty list if no inventory ID set.


    **Returns:**
    - the list of inventory IDs that were specified in the search query or an empty list if no
                      inventory ID set.



---

### getOrderableProductsOnly()
- getOrderableProductsOnly(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Get the flag indicating whether unorderable products should be excluded
      when the next call to getProducts() is made. If this value has not been
      previously set, then the value returned will be based on the value of the
      search preference.


    **Returns:**
    - true if unorderable products should be excluded from product
              search results, false otherwise.



---

### getPageMetaTag(String)
- getPageMetaTag(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)
  - : Returns the page meta tag for the specified id.
      
      
      The meta tag content is generated based on the product listing page meta tag context and rule.
      The rule is obtained from the current category context or inherited from the parent category,
      up to the root category.
      
      
      Null will be returned if the meta tag is undefined on the current instance, or if no rule can be found for the
      current context, or if the rule resolves to an empty string.


    **Parameters:**
    - id - the ID to get the page meta tag for

    **Returns:**
    - page meta tag containing content generated based on rules


---

### getPageMetaTags()
- getPageMetaTags(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the product listing page meta tag context and rules.
      The rules are obtained from the current category context or inherited from the parent category,
      up to the root category.


    **Returns:**
    - page meta tags defined for this instance, containing content generated based on rules


---

### getPriceMax()
- getPriceMax(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum price by which the search result is refined.

    **Returns:**
    - the maximum price by which the search result is refined.


---

### getPriceMin()
- getPriceMin(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the minimum price by which the search result is refined.

    **Returns:**
    - the minimum price by which the search result is refined.


---

### getProductID()
- ~~getProductID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the product id that was specified in the search query.

    **Returns:**
    - the product id that was specified in the search.

    **Deprecated:**
**warning:** Please use [getProductIDs()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductids) instead

---

### getProductIDs()
- getProductIDs(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list of product IDs that were specified in the search query or an empty list if no product ID set.

    **Returns:**
    - the list of product IDs that were specified in the search query or an empty list if no product ID set.


---

### getProductSearchHit(Product)
- getProductSearchHit(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md)
  - : Returns the underlying ProductSearchHit for a product, or null if no
      ProductSearchHit found for this product.


    **Parameters:**
    - product - the product to find the underlying ProductSearchHit

    **Returns:**
    - the underlying ProductSearchHit for a product, or null if no
              ProductSearchHit found for this product.



---

### getProductSearchHits()
- getProductSearchHits(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Returns the product search hits in the search result. 
      
      Note that method does also return search hits representing products that
      were removed or went offline since the last index update, i.e. you must
      implement appropriate checks before accessing the product related to the
      search hit instance (see [ProductSearchHit.getProduct()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md#getproduct))


    **Returns:**
    - Products hits in search result

    **See Also:**
    - [getProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproducts)


---

### getProducts()
- ~~getProducts(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~
  - : Returns all products in the search result. 
      
      Note that products that were removed or went offline since the last index
      update are not included in the returned set.


    **Returns:**
    - Products in search result

    **See Also:**
    - [getProductSearchHits()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductsearchhits)

    **Deprecated:**
**warning:** This method should not be used because loading Products for each result of a product search is
            extremely expensive performance-wise. Please use [getProductSearchHits()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductsearchhits) to iterate
            ProductSearchHits instead.

---

### getPromotionID()
- getPromotionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the promotion id that was specified in the search query or null if no promotion id set. If multiple
      promotion id's specified the method returns only the first id. See [setPromotionIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setpromotionidslist) and
      [getPromotionIDs()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getpromotionids).


    **Returns:**
    - the promotion id that was specified in the search query or null if no promotion id set.


---

### getPromotionIDs()
- getPromotionIDs(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list of promotion id's that were specified in the search query or an empty list if no promotion id set.

    **Returns:**
    - the list of promotion id's that was specified in the search query or an empty list if no promotion id set.


---

### getPromotionProductType()
- getPromotionProductType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the promotion product type specified in the search query.

    **Returns:**
    - the promotion product type that was specified in the search
              query.



---

### getRefinementCategory()
- getRefinementCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the category used to determine possible refinements for the search.
      If an explicit category was set for this purpose using [setRefinementCategory(Category)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrefinementcategorycategory), it is returned.
      Otherwise, the deepest common category of all search results will be returned.


    **Returns:**
    - the category used to determine refinements.


---

### getRefinements()
- getRefinements(): [ProductSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md)
  - : Returns the ProductSearchRefinements associated with this search and filtered by session currency.
      If an explicit category was set for this purpose using [setRefinementCategory(Category)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrefinementcategorycategory), it will be used to determine the refinements.
      Otherwise, the refinements are determined based on the deepest common category of all products in the search result.
      Hint: If you want to use the same refinements for all searches, consider defining them in one category (usually root) and using [setRefinementCategory(Category)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setrefinementcategorycategory) to avoid unnecessary calculation of the deepest common category.


    **Returns:**
    - the ProductSearchRefinements associated with this search.


---

### getSearchMode()
- getSearchMode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the search mode that was requested for the next search execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsearchmodestring), or
      `null` if no mode was explicitly requested. This reflects the caller's requested preference, not the mode
      that actually ran — the requested mode is non-authoritative and `"semantic"` may still be demoted to
      `"lexical"` by the search router. Use [getEffectiveSearchMode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#geteffectivesearchmode) to obtain the mode that was
      actually used after [search()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#search).


    **Returns:**
    - `"semantic"` or `"lexical"` if a mode was requested, or `null` if no mode was requested


---

### getSearchPhraseSuggestions()
- getSearchPhraseSuggestions(): [SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md)
  - : Returns search phrase suggestions for the current search phrase.
      Search phrase suggestions may contain alternative search phrases as well
      as lists of corrected and completed search terms.


    **Returns:**
    - search phrase suggestions for the current search phrase


---

### getSearchableImageUploadURL()
- getSearchableImageUploadURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : This method returns the URL of the endpoint where the merchants should upload their image for visual search.

    **Returns:**
    - returns the URL where the merchants should upload their image.

    **Throws:**
    - RuntimeException - 


---

### getSortingRule()
- getSortingRule(): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)
  - : Returns the sorting rule explicitly set on this model to be used
      to order the products in the results of this query, or `null`
      if no rule has been explicitly set.
      
      This method does not return the sorting rule that will be used implicitly
      based on the context of the search, such as the refinement category.


    **Returns:**
    - a SortingRule or null.


---

### getStoreInventoryFilter()
- getStoreInventoryFilter(): [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)
  - : 
      
      Returns the [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md), which was specified for this search.


    **Returns:**
    - the [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md), which was specified for this search.


---

### getSuggestedSearchPhrase()
- ~~getSuggestedSearchPhrase(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the suggested search phrase with the highest accuracy provided
      for the current search phrase.


    **Returns:**
    - the suggested search phrase.

    **Deprecated:**
**warning:** Please use [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsearchphrasesuggestions) instead

---

### getSuggestedSearchPhrases()
- ~~getSuggestedSearchPhrases(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)~~
  - : Returns a list with up to 5 suggested search phrases provided for the
      current search phrase. It is possible that less than 5 suggestions
      or even no suggestions are returned.


    **Returns:**
    - a list containing the suggested search phrases.

    **Deprecated:**
**warning:** Please use [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getsearchphrasesuggestions) instead

---

### isCategorySearch()
- isCategorySearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if this is a pure search for a category. The
      method checks, that a category ID is specified and no search phrase is
      specified.


    **Returns:**
    - True if this is a category search


---

### isPersonalizedSort()
- isPersonalizedSort(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method indicates if the search result is ordered by a personalized sorting rule.

    **Returns:**
    - true if search result is ordered by a personalized sorting rule, otherwise false.


---

### isRecursiveCategorySearch()
- isRecursiveCategorySearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Get the flag that determines if the category search will
      be recursive.


    **Returns:**
    - true if the category search will be recursive, false otherwise


---

### isRefinedByCategory()
- isRefinedByCategory(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if the search is refined by a category.
      The method checks, that a category ID is specified.


    **Returns:**
    - true, if the search is refined by a category, false otherwise.


---

### isRefinedByPrice()
- isRefinedByPrice(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined by price.

    **Returns:**
    - True if the search is refined by price, false otherwise.


---

### isRefinedByPriceRange(Number, Number)
- isRefinedByPriceRange(priceMin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), priceMax: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined by the given price range.
      Either range parameters may be null to represent open ranges.


    **Parameters:**
    - priceMin - The lower bound of the price range.
    - priceMax - The upper bound of the price range.

    **Returns:**
    - True if the search is refinemd on the given price range, false
              otherwise.



---

### isRefinedByPromotion()
- isRefinedByPromotion(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined by promotion.

    **Returns:**
    - True if the search is refined by promotion, false otherwise.


---

### isRefinedByPromotion(String)
- isRefinedByPromotion(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined by a given promotion.

    **Parameters:**
    - promotionID - the ID of the promotion to check

    **Returns:**
    - True if the search is refined by the given promotionID, false otherwise.


---

### isRefinedCategorySearch()
- isRefinedCategorySearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is a category search and is refined with further
      criteria, like a brand refinement or an attribute refinement.


    **Returns:**
    - true if this is a category search and is refined with further
              criteria, false otherwise.



---

### isTrackingEmptySearchesEnabled()
- isTrackingEmptySearchesEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method indicates if no-hits search should be tracked for predictive intelligence use.

    **Returns:**
    - true, if no-hits search should be tracked, otherwise false.


---

### isVisualSearch()
- isVisualSearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if this is a visual search. The
      method checks that a image UUID is specified.


    **Returns:**
    - True if this is a visual search


---

### search()
- search(): [SearchStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md)
  - : Execute the search based on the configured search term, category and filter conditions (price, attribute,
      promotion, product type) and return the execution status. The execution of an empty ProductSearchModel without
      any search term or filter criteria will not be supported and the search status [SearchStatus.EMPTY_QUERY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md#empty_query)
      will be returned. A usage of the internal category id 'root' as category filter is not recommended, could cause
      performance issues and will be potentially deprecated in a future release. A successful execution will be
      indicated by [SearchStatus.SUCCESSFUL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md#successful) or [SearchStatus.LIMITED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md#limited). For other possible search
      statuses see [SearchStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md). The sorted and grouped search result of a successful execution can be fetched
      via [getProductSearchHits()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getproductsearchhits) and the refinement options based on the search result can be obtained via
      [getRefinements()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#getrefinements) and [SearchModel.getRefinementValues(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluesstring).


    **Returns:**
    - the searchStatus object with search status code and description of search result.


---

### setCategoryID(String)
- setCategoryID(categoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Specifies the category id used for the search query.

    **Parameters:**
    - categoryID - the category id for the search query.


---

### setEnableTrackingEmptySearches(Boolean)
- setEnableTrackingEmptySearches(trackingEmptySearches: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set a flag indicating whether no-hits search should be tracked for predictive intelligence use.

    **Parameters:**
    - trackingEmptySearches - true, no-hits search should be tracked, false, otherwise.


---

### setInventoryListIDs(List)
- setInventoryListIDs(inventoryListIDs: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): void
  - : 
      
      Specifies multiple inventory list IDs used for the search query. The method supports up to
      [MAXIMUM_INVENTORY_LIST_IDS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#maximum_inventory_list_ids) inventory IDs. If more than [MAXIMUM_INVENTORY_LIST_IDS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#maximum_inventory_list_ids) inventory IDs
      used the method throws an IllegalArgumentException.


    **Parameters:**
    - inventoryListIDs - the inventory IDs for the search query.

    **Throws:**
    - IllegalArgumentException - if more than [MAXIMUM_INVENTORY_LIST_IDS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#maximum_inventory_list_ids) inventory IDs used


---

### setOrderableProductsOnly(Boolean)
- setOrderableProductsOnly(orderableOnly: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set a flag indicating whether unorderable products should be excluded
      when the next call to getProducts() is made. This method overrides the
      default behavior which is controlled by the search preference.


    **Parameters:**
    - orderableOnly - true if unorderable products should be excluded from             product search results, false otherwise.


---

### setPriceMax(Number)
- setPriceMax(priceMax: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the maximum price by which the search result is to be refined.

    **Parameters:**
    - priceMax - sets the maximum price by which the search result is to be refined.


---

### setPriceMin(Number)
- setPriceMin(priceMin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the minimum price by which the search result is to be refined.

    **Parameters:**
    - priceMin - the minimum price by which the search result is to be refined.


---

### setProductID(String)
- ~~setProductID(productID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Specifies the product id used for the search query.

    **Parameters:**
    - productID - the product id for the search query.

    **Deprecated:**
**warning:** Please use [setProductIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setproductidslist) instead

---

### setProductIDs(List)
- setProductIDs(productIDs: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): void
  - : Specifies multiple product IDs used for the search query. The specified product IDs include, but not limited to,
      variant product IDs, product master IDs, variation group IDs, product set IDs, or product bundle IDs. For
      example, this API could be used in high-traffic pages where developers need to be able to filter quickly for only
      available child products of a specified master product, instead of looping through all variants of a set products
      and checking their availabilities. The method supports up to [MAXIMUM_PRODUCT_IDS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#maximum_product_ids) product IDs. If more
      than [MAXIMUM_PRODUCT_IDS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#maximum_product_ids) products IDs are passed, the method throws an IllegalArgumentException.


    **Parameters:**
    - productIDs - the product IDs for the search query.

    **Throws:**
    - IllegalArgumentException - if more than [MAXIMUM_PRODUCT_IDS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#maximum_product_ids) product IDs used


---

### setPromotionID(String)
- setPromotionID(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Specifies the promotion id used for the search query.

    **Parameters:**
    - promotionID - the promotion id for the search query.


---

### setPromotionIDs(List)
- setPromotionIDs(promotionIDs: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)): void
  - : Specifies multiple promotion id's used for the search query. The method supports up to 30 promotion id's. If more
      than 30 promotion id's used the method throws an IllegalArgumentException.


    **Parameters:**
    - promotionIDs - the promotion ids for the search query.

    **Throws:**
    - IllegalArgumentException - if more than 30 promotion id's used


---

### setPromotionProductType(String)
- setPromotionProductType(promotionProductType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Specifies the promotion product type used for the search query. This
      value is only relevant for searches by promotion ID.


    **Parameters:**
    - promotionProductType - The type of product to filter by when             searching by promotion ID. Allowed values are             PROMOTION\_PRODUCT\_TYPE\_ALL, PROMOTION\_PRODUCT\_TYPE\_BONUS,             PROMOTION\_PRODUCT\_TYPE\_QUALIFYING, and             PROMOTION\_PRODUCT\_TYPE\_DISCOUNTED. If null is passed, or             an invalid value is passed, the search will use             PROMOTION\_PRODUCT\_TYPE\_ALL.


---

### setRecursiveCategorySearch(Boolean)
- setRecursiveCategorySearch(recurse: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set a flag to indicate if the search in category should be recursive.

    **Parameters:**
    - recurse - recurse the category in the search


---

### setRefinementCategory(Category)
- setRefinementCategory(refinementCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): void
  - : Sets an explicit category to be used when determining refinements. If this is not done, they will be determined based on the deepest common category of all search results.
      The explicit category must be in the site's storefront catalog, otherwise the method fails with an IllegalArgumentException.


    **Parameters:**
    - refinementCategory - the category used to determine the applicable refinements.

    **Throws:**
    - IllegalArgumentException - if the refinement category does not reside in the storefront catalog


---

### setSearchMode(String)
- setSearchMode(mode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the search mode for the next search execution. The mode influences the routing decision made by the search
      router, but is non-authoritative — `"semantic"` still runs the full routing cascade and may be demoted to
      `"lexical"` based on availability and query characteristics.


    **Parameters:**
    - mode - the search mode to request, either `"semantic"` or `"lexical"`

    **Throws:**
    - IllegalArgumentException - if the mode is not one of the allowed values


---

### setSearchableImageID(String)
- setSearchableImageID(imageID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : An image ID can be retrieved by uploading an image with a multipart/form-data POST
      request to 'https://api.cquotient.com/v3/image/search/upload/{siteID}'. This method sets product IDs retrieved
      from the image ID to the ProductSearchModel. If using [setProductIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setproductidslist) in addition to this method,
      the ProductSearchModel will take the intersection of these sets of product IDs. If the image ID provided is
      invalid or expired, product IDs will not be set onto the product search model.


    **Parameters:**
    - imageID - the image ID for the visual search query.

    **Throws:**
    - RuntimeException - if product IDs for the provided image could not be set.


---

### setSortingCondition(String, Number)
- ~~setSortingCondition(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), direction: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void~~
  - : Sets or removes a sorting condition for the specified attribute. Specify
      either SORT\_DIRECTION\_ASCENDING or SORT\_DIRECTION\_DESCENDING to set a
      sorting condition. Specify SORT\_DIRECTION\_NONE to remove a sorting
      condition from the attribute.


    **Parameters:**
    - attributeID - the attribute ID
    - direction - SORT\_DIRECTION\_ASCENDING, SORT\_DIRECTION\_DESCENDING or             SORT\_DIRECTION\_NONE

    **Deprecated:**
**warning:** This method is subject to removal. Use [setSortingRule(SortingRule)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setsortingrulesortingrule) instead.

---

### setSortingOption(SortingOption)
- setSortingOption(option: [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)): void
  - : Sets the sorting option to be used to order the products in the results of this query.
      If a sorting rule is also set, the sorting option is ignored.


    **Parameters:**
    - option - the SortingOption to use to sort the products


---

### setSortingRule(SortingRule)
- setSortingRule(rule: [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)): void
  - : Sets the sorting rule to be used to order the products in the
      results of this query.  Setting the rule in this way overrides the
      default behavior of choosing the sorting rule based on the context of the
      search, such as the refinement category.


    **Parameters:**
    - rule - the SortingRule to use to sort the products


---

### setStoreInventoryFilter(StoreInventoryFilter)
- setStoreInventoryFilter(storeInventoryFilter: [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)): void
  - : 
      
      Filters the search result by one or more inventory list IDs provided by the class [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)
      which supports a semantic URL parameter like zip, city, store ... and a list of [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md)
      which maps the semantic inventory list id value like Burlington, Boston, ... to a real inventory list id like
      'Burlington -> inventory1', 'Boston -> inventory2'. The search will filter the result by the real inventory list
      id(s) but will use the semantic URL parameter and semantic inventory list id values for URL generation via all
      URLRefine and URLRelax methods e.g. for [urlRefineCategory(URL, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinecategoryurl-string), [urlRelaxPrice(URL)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxpriceurl),
      [SearchModel.urlRefineAttribute(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributestring-string-string).
      
      
      Example custom URL: city=Burlington|Boston
      
      
      
      ```
      var storeFilter = new dw.catalog.StoreInventoryFilter("city",
          new dw.util.ArrayList(
              new dw.catalog.StoreInventoryFilterValue("Burlington","inventory_store_store9"),
              new dw.catalog.StoreInventoryFilterValue("Boston","inventory_store_store8")
      ));
      searchModel.setStoreInventoryFilter(filter)
      ```


    **Parameters:**
    - storeInventoryFilter - The [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md) instance to filter the search result by one or more                              inventory IDs with semantic key and semantic value support.

    **Throws:**
    - IllegalArgumentException - if more than [MAXIMUM_STORE_INVENTORY_FILTER_VALUES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#maximum_store_inventory_filter_values) filter values                                        used


---

### urlForCategory(URL, String)
- static urlForCategory(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), cgid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to execute a query for a specific
      Category. The search specific parameters are appended to the provided
      URL. The URL is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - the URL to use to generate the new URL.
    - cgid - the category ID.

    **Returns:**
    - the new URL.


---

### urlForCategory(String, String)
- static urlForCategory(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), cgid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to execute a query for a specific
      Category.
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - pipeline action, e.g. 'Search-Show'.
    - cgid - the category ID.

    **Returns:**
    - the new URL.


---

### urlForProduct(URL, String, String)
- static urlForProduct(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), cgid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), pid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to execute a query for a specific
      Product. The passed url can be either a full url or just the name for a
      pipeline. In the later case a relative URL is created.


    **Parameters:**
    - url - the URL to use to generate the new URL.
    - cgid - the category id or null if product is not in category             context.
    - pid - the product id.

    **Returns:**
    - the new URL.


---

### urlForProduct(String, String, String)
- static urlForProduct(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), cgid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), pid: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to execute a query for a specific
      Product. The passed action is used to build an initial url. All search
      specific attributes are appended.
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - pipeline action, e.g. 'Search-Show'.
    - cgid - the category id or null if product is not in category             context.
    - pid - the product id.

    **Returns:**
    - the new URL.


---

### urlForRefine(URL, String, String)
- static urlForRefine(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to execute a query for a specific
      attribute name-value pair. The search specific parameters are appended to
      the provided URL. The URL is typically generated with one of the URLUtils
      methods.


    **Parameters:**
    - url - the URL to use to generate the new URL.
    - attributeID - the attribute ID for the refinement.
    - value - the attribute value for the refinement.

    **Returns:**
    - the new URL.


---

### urlForRefine(String, String, String)
- static urlForRefine(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to execute a query for a specific
      attribute name-value pair.
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - pipeline action, e.g. 'Search-Show'.
    - attributeID - the attribute ID for the refinement.
    - value - the attribute value for the refinement.

    **Returns:**
    - the new URL.


---

### urlRefineCategory(URL, String)
- urlRefineCategory(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), refineCategoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query with a
      category refinement. The search specific parameters are appended to the
      provided URL. The URL is typically generated with one of the URLUtils
      methods.


    **Parameters:**
    - url - the existing URL to use to create the new URL.
    - refineCategoryID - the ID of the category.

    **Returns:**
    - the new URL.


---

### urlRefineCategory(String, String)
- urlRefineCategory(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), refineCategoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query with a
      category refinement.
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'
    - refineCategoryID - the ID of the category.

    **Returns:**
    - the new URL.


---

### urlRefinePrice(URL, Number, Number)
- urlRefinePrice(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), min: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), max: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query with an
      additional price filter. The search specific parameters are appended to
      the provided URL. The URL is typically generated with one of the URLUtils
      methods.


    **Parameters:**
    - url - the URL to use to generate the new URL.
    - min - the minimum price.
    - max - the maximum price.

    **Returns:**
    - the new URL.


---

### urlRefinePrice(String, Number, Number)
- urlRefinePrice(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), min: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), max: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query with an
      additional price filter.
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'.
    - min - the minimum price.
    - max - the maximum price.

    **Returns:**
    - the new URL.


---

### urlRefinePromotion(URL, String)
- urlRefinePromotion(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), refinePromotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query with a promotion refinement. The search specific
      parameters are appended to the provided URL. The URL is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - the existing URL to use to create the new URL.
    - refinePromotionID - the ID of the promotion.

    **Returns:**
    - the new URL.


---

### urlRefinePromotion(String, String)
- urlRefinePromotion(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), refinePromotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query with a promotion refinement. The generated URL will be
      an absolute URL which uses the protocol of the current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'
    - refinePromotionID - the ID of the promotion.

    **Returns:**
    - the new URL.


---

### urlRelaxCategory(URL)
- urlRelaxCategory(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query without any
      category refinement. The search specific parameters are appended to the
      provided URL. The URL is typically generated with one of the URLUtils
      methods.


    **Parameters:**
    - url - the existing URL to use to create the new URL.

    **Returns:**
    - the new URL.


---

### urlRelaxCategory(String)
- urlRelaxCategory(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query without any
      category refinement.
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'.

    **Returns:**
    - the new URL.


---

### urlRelaxPrice(URL)
- urlRelaxPrice(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to would re-execute the query with no
      price filter. The search specific parameters are appended to the provided
      URL. The URL is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - the existing URL to use to create the new URL.

    **Returns:**
    - the new URL.


---

### urlRelaxPrice(String)
- urlRelaxPrice(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query with no price
      filter.
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'

    **Returns:**
    - the new URL.


---

### urlRelaxPromotion(URL)
- urlRelaxPromotion(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query without any promotion refinement. The search specific
      parameters are appended to the provided URL. The URL is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - the existing URL to use to create the new URL.

    **Returns:**
    - the new URL.


---

### urlRelaxPromotion(String)
- urlRelaxPromotion(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query without any promotion refinement. The generated URL
      will be an absolute URL which uses the protocol of the current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'.

    **Returns:**
    - the new URL.


---

### urlSortingOption(URL, SortingOption)
- urlSortingOption(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), option: [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query but sort
      the results by the given storefront sorting option. The search specific parameters are
      appended to the provided URL. The URL is typically generated with one of
      the URLUtils methods.


    **Parameters:**
    - url - the existing URL to use to create the new URL.
    - option - sorting option

    **Returns:**
    - the new URL.


---

### urlSortingOption(String, SortingOption)
- urlSortingOption(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), option: [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query but sort the
      results by the given storefront sorting option.
      
      The generated URL will be an absolute URL which uses the protocol of the
      current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'.
    - option - sorting option

    **Returns:**
    - the new URL.


---

### urlSortingRule(URL, SortingRule)
- urlSortingRule(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), rule: [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query but sort
      the results by the given rule. The search specific parameters are
      appended to the provided URL. The URL is typically generated with one of
      the URLUtils methods.


    **Parameters:**
    - url - the existing URL to use to create the new URL.
    - rule - sorting rule

    **Returns:**
    - the new URL.


---

### urlSortingRule(String, SortingRule)
- urlSortingRule(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), rule: [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL that you can use to re-execute the query but sort the
      results by the given rule.
      
      The generated URL will be an absolute URL which uses the protocol of the
      current request.


    **Parameters:**
    - action - the pipeline action, e.g. 'Search-Show'.
    - rule - sorting rule

    **Returns:**
    - the new URL.


---

<!-- prettier-ignore-end -->

<!-- document id=a3e5d60cb3b35403bf97880786ed1d8b64ee041e37df16acd6d2de8bf46967e0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductSearchRefinementDefinition.md -->

<!-- prettier-ignore-start -->
# Class ProductSearchRefinementDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.SearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md)
        - [dw.catalog.ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)

This class provides an interface to refinement options for the product search.


## Property Summary

| Property | Description |
| --- | --- |
| [categoryRefinement](#categoryrefinement): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is a category refinement. |
| [priceRefinement](#pricerefinement): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is a price refinement. |
| [promotionRefinement](#promotionrefinement): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is a promotion refinement. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [isCategoryRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md#iscategoryrefinement)() | Identifies if this is a category refinement. |
| [isPriceRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md#ispricerefinement)() | Identifies if this is a price refinement. |
| [isPromotionRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md#ispromotionrefinement)() | Identifies if this is a promotion refinement. |

### Methods inherited from class SearchRefinementDefinition

[getAttributeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getattributeid), [getCutoffThreshold](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getcutoffthreshold), [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getdisplayname), [getValueTypeCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getvaluetypecode), [isAttributeRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#isattributerefinement)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### categoryRefinement
- categoryRefinement: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is a category refinement.


---

### priceRefinement
- priceRefinement: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is a price refinement.


---

### promotionRefinement
- promotionRefinement: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is a promotion refinement.


---

## Method Details

### isCategoryRefinement()
- isCategoryRefinement(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is a category refinement.

    **Returns:**
    - true if this is a category refinement, false otherwise.


---

### isPriceRefinement()
- isPriceRefinement(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is a price refinement.

    **Returns:**
    - true if this is a price refinement, false otherwise.


---

### isPromotionRefinement()
- isPromotionRefinement(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is a promotion refinement.

    **Returns:**
    - true if this is a promotion refinement, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=e8e6b50a8b8a08cd2adfe5280dfe9ff7a1a06674decc8e497ae47c63dc53f11f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductSearchRefinements.md -->

<!-- prettier-ignore-start -->
# Class ProductSearchRefinements

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md)
    - [dw.catalog.ProductSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md)

This class provides an interface to refinement options for the product
search. In a typical usage, the client application UI displays the search
refinements along with the search results and allows customers to "refine"
the results (i.e. limit the results that are shown) by specifying additional
product criteria, or "relax" (i.e. broaden) the results after previously
refining. The four types of product search refinements are:


- **Refine By Category:**Limit the products to those assigned to  specific child/ancestor categories of the search category.
- **Refine By Attribute:**Limit the products to those with specific  values for a given attribute. Values may be grouped into "buckets" so that a  given set of values are represented as a single refinement option.
- **Refine By Price:**Limit the products to those whose prices fall in  a specific range.
- **Refine By Promotion:**Limit the products to those which are related  to a specific promotion.


Rendering a product search refinement UI typically begins with iterating the
refinement definitions for the search result. Call
[SearchRefinements.getRefinementDefinitions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementdefinitions) or
[SearchRefinements.getAllRefinementDefinitions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementdefinitions) to
retrieve the appropriate collection of refinement definitions. For each
definition, display the available refinement values by calling
[getAllRefinementValues(ProductSearchRefinementDefinition)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getallrefinementvaluesproductsearchrefinementdefinition). Depending
on the type of the refinement definition, the application must use slightly
different logic to display the refinement widgets. For all 4 types, methods
in [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md) are used to generate URLs to render
hyperlinks in the UI. When clicked, these links trigger a call to the Search
pipelet which in turn applies the appropriate filters to the native search
result.



## Property Summary

| Property | Description |
| --- | --- |
| [categoryRefinementDefinition](#categoryrefinementdefinition): [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md) `(read-only)` | Returns the appropriate category refinement definition based on the search  result. |
| [priceRefinementDefinition](#pricerefinementdefinition): [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md) `(read-only)` | Returns the appropriate price refinement definition based on the search  result. |
| [promotionRefinementDefinition](#promotionrefinementdefinition): [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md) `(read-only)` | Returns the appropriate promotion refinement definition based on the search  result. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getallrefinementvaluesproductsearchrefinementdefinition)([ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)) | Returns a sorted collection of refinement values for the passed  refinement definition. |
| [getCategoryRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getcategoryrefinementdefinition)() | Returns the appropriate category refinement definition based on the search  result. |
| [getNextLevelCategoryRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getnextlevelcategoryrefinementvaluescategory)([Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)) | Returns category refinement values based on the current search result  filtered such that only category refinements representing children of the  given category are present. |
| [getPriceRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getpricerefinementdefinition)() | Returns the appropriate price refinement definition based on the search  result. |
| [getPromotionRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getpromotionrefinementdefinition)() | Returns the appropriate promotion refinement definition based on the search  result. |
| [getRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getrefinementvalueproductsearchrefinementdefinition-string)([ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the refinement value (incl. |
| [getRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getrefinementvaluestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the refinement value (incl. |
| [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getrefinementvaluesproductsearchrefinementdefinition)([ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)) | Returns a collection of refinement values for the given refinement  definition. |

### Methods inherited from class SearchRefinements

[getAllRefinementDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementdefinitions), [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementvaluesstring), [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementvaluesstring-number-number), [getRefinementDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementdefinitions), [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementvaluesstring-number-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### categoryRefinementDefinition
- categoryRefinementDefinition: [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md) `(read-only)`
  - : Returns the appropriate category refinement definition based on the search
      result. The category refinement definition returned will be the first that
      can be found traversing the category tree upward starting at the deepest
      common category of the search result.



---

### priceRefinementDefinition
- priceRefinementDefinition: [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md) `(read-only)`
  - : Returns the appropriate price refinement definition based on the search
      result. The price refinement definition returned will be the first that
      can be found traversing the category tree upward starting at the deepest
      common category of the search result.



---

### promotionRefinementDefinition
- promotionRefinementDefinition: [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md) `(read-only)`
  - : Returns the appropriate promotion refinement definition based on the search
      result. The promotion refinement definition returned will be the first that
      can be found traversing the category tree upward starting at the deepest
      common category of the search result.



---

## Method Details

### getAllRefinementValues(ProductSearchRefinementDefinition)
- getAllRefinementValues(definition: [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of refinement values for the passed
      refinement definition. The returned collection includes all refinement
      values for which the hit count is greater than 0 within the search result
      when the passed refinement definition is excluded from filtering the
      search hits but all other refinement filters are still applied. This
      method is useful for rendering broadening options for definitions that
      the search is currently refined by. If the search is not currently
      restricted by the passed refinement definition, then this method will
      return the same result as
      [getRefinementValues(ProductSearchRefinementDefinition)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getrefinementvaluesproductsearchrefinementdefinition).
      
      
      For attribute-based refinement definitions, the returned collection
      depends upon how the "value set" property is configured. (Category and
      price refinement definitions do not have such a property.) If this
      property is set to "search result values", the behavior is as described
      above. If this property is set to "all values of category", then the
      returned collection will also include all refinement values for products
      in the category subtree rooted at the search definition's category. This
      setting is useful for refinements whose visualization is supposed to
      remain constant for a certain subtree of a catalog (e.g. color pickers or
      size charts). These additional values are independent of the search
      result and do not contribute towards the value hit counts. If the search
      result is further refined by one of these values, it is possible to get
      an empty search result. Except for this one case this method does NOT
      return refinement values independent of the search result.


    **Parameters:**
    - definition - The refinement definition to return refinement values             for. Must not be null.

    **Returns:**
    - The collection of ProductSearchRefinementValue instances, sorted
              according to the settings of the refinement definition.



---

### getCategoryRefinementDefinition()
- getCategoryRefinementDefinition(): [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)
  - : Returns the appropriate category refinement definition based on the search
      result. The category refinement definition returned will be the first that
      can be found traversing the category tree upward starting at the deepest
      common category of the search result.


    **Returns:**
    - The category refinement definition or `null` if none can
              be found.



---

### getNextLevelCategoryRefinementValues(Category)
- getNextLevelCategoryRefinementValues(category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns category refinement values based on the current search result
      filtered such that only category refinements representing children of the
      given category are present. If no category is given, the method uses the
      catalog's root category. The refinement value product counts represent
      all hits contained in the catalog tree starting at the corresponding
      child category.


    **Parameters:**
    - category - The category to return child category refinement values for.

    **Returns:**
    - The refinement values for all child categories of the given
              category.



---

### getPriceRefinementDefinition()
- getPriceRefinementDefinition(): [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)
  - : Returns the appropriate price refinement definition based on the search
      result. The price refinement definition returned will be the first that
      can be found traversing the category tree upward starting at the deepest
      common category of the search result.


    **Returns:**
    - The price refinement definition or `null` if none can
              be found.



---

### getPromotionRefinementDefinition()
- getPromotionRefinementDefinition(): [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)
  - : Returns the appropriate promotion refinement definition based on the search
      result. The promotion refinement definition returned will be the first that
      can be found traversing the category tree upward starting at the deepest
      common category of the search result.


    **Returns:**
    - The promotion refinement definition or `null` if none can
              be found.



---

### getRefinementValue(ProductSearchRefinementDefinition, String)
- getRefinementValue(definition: [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementValue.md)
  - : Returns the refinement value (incl. product hit count) for the given
      refinement definition and the given (selected) value.


    **Parameters:**
    - definition - The definition to return the refinement for.
    - value - The value to return the refinement for.

    **Returns:**
    - The refinement value.


---

### getRefinementValue(String, String)
- getRefinementValue(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementValue.md)
  - : Returns the refinement value (incl. product hit count) for the given
      refinement attribute and the given (selected) value.


    **Parameters:**
    - name - The name of the refinement attribute.
    - value - The value to return the refinement for.

    **Returns:**
    - The refinement value.


---

### getRefinementValues(ProductSearchRefinementDefinition)
- getRefinementValues(definition: [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of refinement values for the given refinement
      definition. The returned refinement values only include those that are
      part of the actual search result (i.e. hit count will always be > 0).


    **Parameters:**
    - definition - The refinement definition to return refinement values for.

    **Returns:**
    - The collection of refinement values sorted according to the
              settings of the definition.



---

<!-- prettier-ignore-end -->

<!-- document id=32c764d7ca2dc45e394dbfacdc6613bfdb578feb3a8729cd5afbaa1e19cac1f2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductSearchRefinementValue.md -->

<!-- prettier-ignore-start -->
# Class ProductSearchRefinementValue

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md)
    - [dw.catalog.ProductSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementValue.md)

Represents the value of a product search refinement.


## Property Summary

| Property | Description |
| --- | --- |
| [valueFrom](#valuefrom): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the lower bound for price refinements. |
| [valueTo](#valueto): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the upper bound for price refinements. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getValueFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementValue.md#getvaluefrom)() | Returns the lower bound for price refinements. |
| [getValueTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementValue.md#getvalueto)() | Returns the upper bound for price refinements. |

### Methods inherited from class SearchRefinementValue

[getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getdescription), [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getdisplayvalue), [getHitCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#gethitcount), [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getid), [getPresentationID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getpresentationid), [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getvalue)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### valueFrom
- valueFrom: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the lower bound for price refinements.  For example, 50.00
      for a range of $50.00 - $99.99.



---

### valueTo
- valueTo: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the upper bound for price refinements.  For example, 99.99
      for a range of $50.00 - $99.99.



---

## Method Details

### getValueFrom()
- getValueFrom(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the lower bound for price refinements.  For example, 50.00
      for a range of $50.00 - $99.99.


    **Returns:**
    - the lower bound for price refinements.


---

### getValueTo()
- getValueTo(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the upper bound for price refinements.  For example, 99.99
      for a range of $50.00 - $99.99.


    **Returns:**
    - the upper bound for price refinements.


---

<!-- prettier-ignore-end -->

<!-- document id=303988014468ace297f071ffb580af2a49312f504fefebfe1736ac7000c6b901 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ProductShippingCost.md -->

<!-- prettier-ignore-start -->
# Class ProductShippingCost

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.ProductShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingCost.md)

Instances of ProductShippingCost represent product specific shipping costs.



Use [ProductShippingModel.getShippingCost(ShippingMethod)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md#getshippingcostshippingmethod) to get
the shipping cost for a specific product.



## Property Summary

| Property | Description |
| --- | --- |
| [amount](#amount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the shipping amount. |
| [fixedPrice](#fixedprice): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if shipping cost is a fixed-price shipping cost,  and false if surcharge shipping cost. |
| [surcharge](#surcharge): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if shipping cost is a surcharge to the shipment  shipping cost, and false if fixed-price shipping cost. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingCost.md#getamount)() | Returns the shipping amount. |
| [isFixedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingCost.md#isfixedprice)() | Returns true if shipping cost is a fixed-price shipping cost,  and false if surcharge shipping cost. |
| [isSurcharge](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingCost.md#issurcharge)() | Returns true if shipping cost is a surcharge to the shipment  shipping cost, and false if fixed-price shipping cost. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### amount
- amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the shipping amount.


---

### fixedPrice
- fixedPrice: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if shipping cost is a fixed-price shipping cost,
      and false if surcharge shipping cost.



---

### surcharge
- surcharge: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if shipping cost is a surcharge to the shipment
      shipping cost, and false if fixed-price shipping cost.



---

## Method Details

### getAmount()
- getAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the shipping amount.

    **Returns:**
    - Shipping amount


---

### isFixedPrice()
- isFixedPrice(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if shipping cost is a fixed-price shipping cost,
      and false if surcharge shipping cost.


    **Returns:**
    - true of fixed-price shipping cost, else false


---

### isSurcharge()
- isSurcharge(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if shipping cost is a surcharge to the shipment
      shipping cost, and false if fixed-price shipping cost.


    **Returns:**
    - true of surcharge shipping cost, else false


---

<!-- prettier-ignore-end -->

<!-- document id=8aee2d91c37e40a34c1be33354922dd2ce10cf0d0c49d23bacc765e901dde56c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ProductShippingLineItem.md -->

<!-- prettier-ignore-start -->
# Class ProductShippingLineItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
        - [dw.order.ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md)

Represents a specific line item in a shipment. A ProductShippingLineItem defines
lineitem-specific shipping costs.



## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[PRODUCT_SHIPPING_ID](#product_shipping_id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRODUCT_SHIPPING"~~ | Reserved constant. |

## Property Summary

| Property | Description |
| --- | --- |
| [adjustedGrossPrice](#adjustedgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the gross price of the product shipping line item after applying  all product-shipping-level adjustments. |
| [adjustedNetPrice](#adjustednetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the net price of the product shipping line item after applying  all product-shipping-level adjustments. |
| [adjustedPrice](#adjustedprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the price of the product shipping line item after applying all  pproduct-shipping-level adjustments. |
| [adjustedTax](#adjustedtax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the tax of the unit after applying adjustments, in the purchase  currency. |
| [priceAdjustments](#priceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns an iterator of price adjustments that have been applied to this  product shipping line item. |
| [productLineItem](#productlineitem): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) `(read-only)` | Returns the parent product line item this shipping line item belongs to. |
| [quantity](#quantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | Returns the quantity of the shipping cost. |
| [shipment](#shipment): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md) `(read-only)` | Returns the shipment this shipping line item belongs to. |
| [surcharge](#surcharge): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns the 'surcharge' flag. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAdjustedGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedgrossprice)() | Returns the gross price of the product shipping line item after applying  all product-shipping-level adjustments. |
| [getAdjustedNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustednetprice)() | Returns the net price of the product shipping line item after applying  all product-shipping-level adjustments. |
| [getAdjustedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedprice)() | Returns the price of the product shipping line item after applying all  pproduct-shipping-level adjustments. |
| [getAdjustedTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedtax)() | Returns the tax of the unit after applying adjustments, in the purchase  currency. |
| [getPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getpriceadjustments)() | Returns an iterator of price adjustments that have been applied to this  product shipping line item. |
| [getProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getproductlineitem)() | Returns the parent product line item this shipping line item belongs to. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getquantity)() | Returns the quantity of the shipping cost. |
| [getShipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getshipment)() | Returns the shipment this shipping line item belongs to. |
| [isSurcharge](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#issurcharge)() | Returns the 'surcharge' flag. |
| [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#setpricevaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets price attributes of the line item based on the  purchase currency, taxation policy and line item quantity.<br/>   The method sets the 'basePrice' attribute of the line item. |
| [setQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#setquantityquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Sets the quantity of the shipping cost. |
| [setSurcharge](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#setsurchargeboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the 'surcharge' flag. |

### Methods inherited from class LineItem

[getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getbaseprice), [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getgrossprice), [getLineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemctnr), [getLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemtext), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getnetprice), [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice), [getPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getpricevalue), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxbasis), [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxclassid), [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxrate), [getTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes), [setBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setbasepricemoney), [setGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setgrosspricemoney), [setLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setlineitemtextstring), [setNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setnetpricemoney), [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setpricevaluenumber), [setTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxmoney), [setTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxclassidstring), [setTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxratenumber), [setTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection), [updatePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber-money), [updateTaxAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxamountmoney)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### PRODUCT_SHIPPING_ID

- ~~PRODUCT_SHIPPING_ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRODUCT_SHIPPING"~~
  - : Reserved constant.

    **Deprecated:**
**warning:** this reserved constant is deprecated.

---

## Property Details

### adjustedGrossPrice
- adjustedGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the gross price of the product shipping line item after applying
      all product-shipping-level adjustments.


    **See Also:**
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustednetprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedprice)


---

### adjustedNetPrice
- adjustedNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the net price of the product shipping line item after applying
      all product-shipping-level adjustments.


    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedgrossprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedprice)


---

### adjustedPrice
- adjustedPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the price of the product shipping line item after applying all
      pproduct-shipping-level adjustments. For net pricing the adjusted net
      price is returned (see [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustednetprice)). For gross
      pricing, the adjusted gross price is returned (see
      [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedgrossprice)).


    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedgrossprice)
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustednetprice)


---

### adjustedTax
- adjustedTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the tax of the unit after applying adjustments, in the purchase
      currency.



---

### priceAdjustments
- priceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns an iterator of price adjustments that have been applied to this
      product shipping line item.



---

### productLineItem
- productLineItem: [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) `(read-only)`
  - : Returns the parent product line item this shipping line item belongs to.


---

### quantity
- quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of the shipping cost.


---

### shipment
- shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md) `(read-only)`
  - : Returns the shipment this shipping line item belongs to.


---

### surcharge
- surcharge: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the 'surcharge' flag.


---

## Method Details

### getAdjustedGrossPrice()
- getAdjustedGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the gross price of the product shipping line item after applying
      all product-shipping-level adjustments.


    **Returns:**
    - gross price after applying product-shipping-level adjustments

    **See Also:**
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustednetprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedprice)


---

### getAdjustedNetPrice()
- getAdjustedNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the net price of the product shipping line item after applying
      all product-shipping-level adjustments.


    **Returns:**
    - net price after applying product-shipping-level adjustments

    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedgrossprice)
    - [getAdjustedPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedprice)


---

### getAdjustedPrice()
- getAdjustedPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price of the product shipping line item after applying all
      pproduct-shipping-level adjustments. For net pricing the adjusted net
      price is returned (see [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustednetprice)). For gross
      pricing, the adjusted gross price is returned (see
      [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedgrossprice)).


    **Returns:**
    - Adjusted net or gross price

    **See Also:**
    - [getAdjustedGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustedgrossprice)
    - [getAdjustedNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md#getadjustednetprice)


---

### getAdjustedTax()
- getAdjustedTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax of the unit after applying adjustments, in the purchase
      currency.


    **Returns:**
    - the tax of the unit after applying adjustments, in the purchase
              currency.



---

### getPriceAdjustments()
- getPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns an iterator of price adjustments that have been applied to this
      product shipping line item.


    **Returns:**
    - a collection of price adjustments that have been applied to this
      product shipping line item.



---

### getProductLineItem()
- getProductLineItem(): [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
  - : Returns the parent product line item this shipping line item belongs to.

    **Returns:**
    - the product line item


---

### getQuantity()
- getQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the quantity of the shipping cost.

    **Returns:**
    - the shipping quantity


---

### getShipment()
- getShipment(): [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)
  - : Returns the shipment this shipping line item belongs to.

    **Returns:**
    - the shipment


---

### isSurcharge()
- isSurcharge(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the 'surcharge' flag.

    **Returns:**
    - true if this is a surcharge shipping cost, false if fixed shipping cost


---

### setPriceValue(Number)
- setPriceValue(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets price attributes of the line item based on the
      purchase currency, taxation policy and line item quantity.
      
      
      The method sets the 'basePrice' attribute of the line item.
      Additionally, it sets the 'netPrice' attribute of the line item
      if the current taxation policy is 'net', and the 'grossPrice'
      attribute, if the current taxation policy is 'gross'. The
      'netPrice'/'grossPrice' attributes are set by multiplying the
      specified price value with the line item quantity. 
      
      
      If null is specified as value, the price attributes are reset to
      Money.NA.


    **Parameters:**
    - value - Price value or null


---

### setQuantity(Quantity)
- setQuantity(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): void
  - : Sets the quantity of the shipping cost.

    **Parameters:**
    - quantity - the shipping quantity


---

### setSurcharge(Boolean)
- setSurcharge(flag: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets the 'surcharge' flag.

    **Parameters:**
    - flag - true if this is a surcharge shipping cost,  false if this is a fixed shipping cost.


---

<!-- prettier-ignore-end -->

<!-- document id=fbd09d21e6f0d9d47223b2ec9ea1c55c4441c44148d6ae628cf7b64068665fda url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ProductShippingModel.md -->

<!-- prettier-ignore-start -->
# Class ProductShippingModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.ProductShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md)

Instances of ProductShippingModel provide access to product-level
shipping information, such as applicable or inapplicable shipping methods
and shipping cost defined for the product for a specified shipping
method. 


Use [ShippingMgr.getProductShippingModel(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#getproductshippingmodelproduct) to get
the shipping model for a specific product.



## Property Summary

| Property | Description |
| --- | --- |
| [applicableShippingMethods](#applicableshippingmethods): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the active applicable shipping methods for the product related  to this shipping model, i.e. |
| [inapplicableShippingMethods](#inapplicableshippingmethods): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the active inapplicable shipping methods for the product related  to this shipping model, i.e. |
| [shippingMethodsWithShippingCost](#shippingmethodswithshippingcost): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the active shipping methods for which either any fixed-price or  surcharge product-level shipping cost is defined for the specified product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getApplicableShippingMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md#getapplicableshippingmethods)() | Returns the active applicable shipping methods for the product related  to this shipping model, i.e. |
| [getInapplicableShippingMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md#getinapplicableshippingmethods)() | Returns the active inapplicable shipping methods for the product related  to this shipping model, i.e. |
| [getShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md#getshippingcostshippingmethod)([ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)) | Returns the shipping cost object for the related product and  the specified shipping method, or null if no product-level fixed-price or  surcharge shipping cost are defined for the specified product. |
| [getShippingMethodsWithShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md#getshippingmethodswithshippingcost)() | Returns the active shipping methods for which either any fixed-price or  surcharge product-level shipping cost is defined for the specified product. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### applicableShippingMethods
- applicableShippingMethods: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the active applicable shipping methods for the product related
      to this shipping model, i.e. shipping methods the product can be shipped
      with. A product can be shipping with a shipping methods if the shipping
      method is not explicitely marked as inapplicable for this product.



---

### inapplicableShippingMethods
- inapplicableShippingMethods: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the active inapplicable shipping methods for the product related
      to this shipping model, i.e. shipping methods the product cannot be
      shipped with. A product cannot be shipping with a shipping methods if the
      shipping method is explicitely marked as inapplicable for this product.



---

### shippingMethodsWithShippingCost
- shippingMethodsWithShippingCost: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the active shipping methods for which either any fixed-price or
      surcharge product-level shipping cost is defined for the specified product. 
      
      Note that this can include inapplicable shipping methods
      (see [getInapplicableShippingMethods()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md#getinapplicableshippingmethods)).



---

## Method Details

### getApplicableShippingMethods()
- getApplicableShippingMethods(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active applicable shipping methods for the product related
      to this shipping model, i.e. shipping methods the product can be shipped
      with. A product can be shipping with a shipping methods if the shipping
      method is not explicitely marked as inapplicable for this product.


    **Returns:**
    - Applicable shipping methods for the product


---

### getInapplicableShippingMethods()
- getInapplicableShippingMethods(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active inapplicable shipping methods for the product related
      to this shipping model, i.e. shipping methods the product cannot be
      shipped with. A product cannot be shipping with a shipping methods if the
      shipping method is explicitely marked as inapplicable for this product.


    **Returns:**
    - Inapplicable shipping methods for the product


---

### getShippingCost(ShippingMethod)
- getShippingCost(shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)): [ProductShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingCost.md)
  - : Returns the shipping cost object for the related product and
      the specified shipping method, or null if no product-level fixed-price or
      surcharge shipping cost are defined for the specified product. 
      
      The following rules apply:
      
      - if fixed and surcharge shipping cost is defined for a product, the fixed cost takes precedence
      - if a product is member of multiple shipping cost groups, the lowest shipping cost takes precedence


    **Parameters:**
    - shippingMethod - the shipping method to use.

    **Returns:**
    - Product shipping cost


---

### getShippingMethodsWithShippingCost()
- getShippingMethodsWithShippingCost(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active shipping methods for which either any fixed-price or
      surcharge product-level shipping cost is defined for the specified product. 
      
      Note that this can include inapplicable shipping methods
      (see [getInapplicableShippingMethods()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md#getinapplicableshippingmethods)).


    **Returns:**
    - Shipping methods with shipping cost


---

<!-- prettier-ignore-end -->

<!-- document id=582516ab186c735b9b48973a15583c97fb5301d305189652d800aa84702cad82 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.ProductSuggestions.md -->

<!-- prettier-ignore-start -->
# Class ProductSuggestions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md)
    - [dw.suggest.ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md)

The product suggestion container provides access to
products found using the suggested terms.
The method [getSuggestedProducts()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md#getsuggestedproducts) can be used to
get the list of found products.


Furthermore the list of suggested terms, after processing
the original user input search query, is accessible
through [SearchPhraseSuggestions.getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms) method.



## Property Summary

| Property | Description |
| --- | --- |
| [suggestedProducts](#suggestedproducts): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | This method returns a list of products which were found  using the suggested terms as search criteria. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSuggestedProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md#getsuggestedproducts)() | This method returns a list of products which were found  using the suggested terms as search criteria. |

### Methods inherited from class Suggestions

[getSearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions), [getSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedphrases), [getSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms), [hasSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases), [hasSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedterms), [hasSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### suggestedProducts
- suggestedProducts: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : This method returns a list of products which were found
      using the suggested terms as search criteria.
      The product lookup is being executed in the current catalog and locale.


    **See Also:**
    - [Suggestions.hasSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)


---

## Method Details

### getSuggestedProducts()
- getSuggestedProducts(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : This method returns a list of products which were found
      using the suggested terms as search criteria.
      The product lookup is being executed in the current catalog and locale.


    **Returns:**
    - a iterator containing a [SuggestedProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedProduct.md) instance for
               each found product, the iterator might be empty


    **See Also:**
    - [Suggestions.hasSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)


---

<!-- prettier-ignore-end -->

<!-- document id=07e6f2947b8a402d15761a0b6a9249ac1fb0db559c06120a6341814d9670d84d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductVariationAttribute.md -->

<!-- prettier-ignore-start -->
# Class ProductVariationAttribute

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)

Represents a product variation attribute


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product variation attribute. |
| [attributeID](#attributeid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product attribute defintion related to   this variation attribute. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name for the product variation attribute, which can be used in the  user interface. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAttributeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md#getattributeid)() | Returns the ID of the product attribute defintion related to   this variation attribute. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md#getdisplayname)() | Returns the display name for the product variation attribute, which can be used in the  user interface. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md#getid)() | Returns the ID of the product variation attribute. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product variation attribute.


---

### attributeID
- attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product attribute defintion related to 
      this variation attribute.  This ID matches the
      value returned by [ObjectAttributeDefinition.getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getid)  
      for the appropriate product attribute definition.
      This ID is generally different than the ID returned by 
      [getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md#getid).



---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name for the product variation attribute, which can be used in the
      user interface.



---

## Method Details

### getAttributeID()
- getAttributeID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product attribute defintion related to 
      this variation attribute.  This ID matches the
      value returned by [ObjectAttributeDefinition.getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md#getid)  
      for the appropriate product attribute definition.
      This ID is generally different than the ID returned by 
      [getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md#getid).


    **Returns:**
    - the ID of the product attribute definition of this variation
      attribute.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name for the product variation attribute, which can be used in the
      user interface.


    **Returns:**
    - the display name for the product variation attribute, which can be used in the
      user interface.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product variation attribute.

    **Returns:**
    - the ID of the product variation attribute.


---

<!-- prettier-ignore-end -->

<!-- document id=d3509a190fd140db18ec251cb26b99cd414a7520fea4700223e17ed4af754c0c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductVariationAttributeValue.md -->

<!-- prettier-ignore-start -->
# Class ProductVariationAttributeValue

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)

Represents a product variation attribute


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the product variation attribute value. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of the product variation attribute value in the current locale. |
| [displayValue](#displayvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display value for the product variation attribute value, which can be used in the  user interface. |
| [value](#value): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the value for the product variation attribute value. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [equals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#equalsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if the specified object is equal to this object. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getdescription)() | Returns the description of the product variation attribute value in the current locale. |
| [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getdisplayvalue)() | Returns the display value for the product variation attribute value, which can be used in the  user interface. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getid)() | Returns the ID of the product variation attribute value. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getimagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getimagesstring) and returns the first image  of the list. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getimagestring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getimagesstring) and returns the image at  the specific index. |
| [getImages](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getimagesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all images that match the given view type and have the variant  value of this value, which is typically the 'color' attribute. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getvalue)() | Returns the value for the product variation attribute value. |
| [hashCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#hashcode)() | Calculates the hash code for a product variation attribute value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the product variation attribute value.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of the product variation attribute value in the current locale.


---

### displayValue
- displayValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display value for the product variation attribute value, which can be used in the
      user interface.



---

### value
- value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the value for the product variation attribute value.


---

## Method Details

### equals(Object)
- equals(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the specified object is equal to this object.

    **Parameters:**
    - obj - the object to test.

    **Returns:**
    - true if the specified object is equal to this object.


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the product variation attribute value in the current locale.

    **Returns:**
    - the description of the product variation attribute value in the current locale,
              or null if it wasn't found.



---

### getDisplayValue()
- getDisplayValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display value for the product variation attribute value, which can be used in the
      user interface.


    **Returns:**
    - the display value for the product variation attribute value, which can be used in the
      user interface.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the product variation attribute value.

    **Returns:**
    - the ID of the product variation attribute value.


---

### getImage(String)
- getImage(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getimagesstring) and returns the first image
      of the list. The method is specifically built for handling color
      swatches in an apparel site.
      
      If no images are defined for this variant and specified view type, then
      the first image of the master product images for that view type is
      returned. If no master product images are defined, the method returns
      null.


    **Parameters:**
    - viewtype - the view type annotated to image

    **Returns:**
    - the MediaFile or null

    **Throws:**
    - NullArgumentException - if viewtype is null


---

### getImage(String, Number)
- getImage(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : The method calls [getImages(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md#getimagesstring) and returns the image at
      the specific index.
      
      If images are defined for this view type and variant, but not for
      specified index, the method returns null.
      
      If no images are defined for this variant and specified view type, the
      image at the specified index of the master product images is returned. If
      no master product image for specified index is defined, the method
      returns null.


    **Parameters:**
    - viewtype - the view type annotated to image
    - index - the index number of the image within image list

    **Returns:**
    - the MediaFile or null

    **Throws:**
    - NullArgumentException - if viewtype is null


---

### getImages(String)
- getImages(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns all images that match the given view type and have the variant
      value of this value, which is typically the 'color' attribute. The images
      are returned in the order of their index number ascending.
      
      If no images are defined for this variant, then the images of the master
      for that view type are returned.


    **Parameters:**
    - viewtype - the view type annotated to images

    **Returns:**
    - a list of MediaFile objects, possibly empty

    **Throws:**
    - NullArgumentException - if viewtype is null


---

### getValue()
- getValue(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value for the product variation attribute value.

    **Returns:**
    - the value for the product variation attribute value.


---

### hashCode()
- hashCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Calculates the hash code for a product variation attribute value.

    **Returns:**
    - the hash code for a product variation attribute value.


---

<!-- prettier-ignore-end -->

<!-- document id=ee38d70f7ce079cc019c9b9d065795a08d2c5898e1d19735e34dda99a8cb78a0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.ProductVariationModel.md -->

<!-- prettier-ignore-start -->
# Class ProductVariationModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md)

Class representing the complete variation information for a master product in
the system. An instance of this class provides methods to access the
following information:


- The variation attributes of the master product (e.g. size and color). Use  [getProductVariationAttributes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getproductvariationattributes).
- The variation attribute values (e.g. size=Small, Medium, Large and  color=Red, Blue). Use [getAllValues(ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getallvaluesproductvariationattribute).
- The variation groups which may represent a subset of variants by defining a  subset of the variation attribute values (e.g. color=Red, size=empty). Use  [getVariationGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariationgroups).
- The variants themselves (e.g. the products representing Small Red, Large  Red, Small Blue, Large Blue, etc). Use [getVariants()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariants).
- The variation attribute values of those variants. Use  [getVariationValue(Product, ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariationvalueproduct-productvariationattribute).


This model only considers variants which are complete (i.e. the variant has a
value for each variation attribute), and currently online. Incomplete or
offline variants will not be returned by any method that returns Variants,
and their attribute values will not be considered in any method that returns
values.


In addition to providing access to this meta information,
ProductVariationModel maintains a collection of selected variation attribute
values, representing the selections that a customer makes in the storefront.
If this model was constructed for a master product, then none of the
attributes will have pre-selected values. If this model was constructed for a
variant product, then all the attribute values of that variant will be
pre-selected.


It is possible to query the current selections by calling
[getSelectedValue(ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getselectedvalueproductvariationattribute) or
[isSelectedAttributeValue(ProductVariationAttribute, ProductVariationAttributeValue)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#isselectedattributevalueproductvariationattribute-productvariationattributevalue).


The method [setSelectedAttributeValue(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#setselectedattributevaluestring-string) can be used to modify
the selected values. Depending on the product type, it's possible to select or modify
variation attribute values:


- If this model was constructed for a master product, it's possible to select and modify all variation attributes.
- If this model was constructed for a variation group, it's possible to select and modify all variation attributes that are not defined by the variation group.
- If this model was constructed for a variation product, it's not possible to select or modify any of the variation attributes.




Furthermore, the model provides helper methods to generate URLs
for selecting and unselecting variation attribute values. See those methods
for details.


If this model was constructed for a product that is neither a
master nor a variant, then none of the methods will return useful values at
all.


The methods in this class which access the currently selected variation
attribute values can be used on product detail pages to render information
about which combinations are available or unavailable. The methods
[getFilteredValues(ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getfilteredvaluesproductvariationattribute) and
[hasOrderableVariants(ProductVariationAttribute, ProductVariationAttributeValue)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#hasorderablevariantsproductvariationattribute-productvariationattributevalue)
can be used to determine this type of situation and render the appropriate
message in the storefront.


NOTE: Several methods in this class have a version taking a
[ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md) parameter, and another
deprecated version accepting a [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)
parameter instead. The former should be strictly favored. The latter are
historical leftovers from when object attributes were used directly as the
basis for variation, and the value lists were stored directly on the
ObjectAttributeDefinition. Every ProductVariationAttribute corresponds with
exactly one ObjectAttributeDefinition, but values are now stored on the
ProductVariationAttribute and not the ObjectAttributeDefinition.



## Property Summary

| Property | Description |
| --- | --- |
| ~~[attributeDefinitions](#attributedefinitions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)` | Returns the object attribute definitions corresponding with the product  variation attributes of the master product. |
| [defaultVariant](#defaultvariant): [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md) `(read-only)` | Return the default variant of this model's master product. |
| [master](#master): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the master of the product variation. |
| [productVariationAttributes](#productvariationattributes): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of product variation attributes of the variation. |
| [selectedVariant](#selectedvariant): [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md) `(read-only)` | Returns the variant currently selected for this variation model. |
| [selectedVariants](#selectedvariants): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the variants currently selected for this variation model. |
| [variants](#variants): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of product variants of this variation model. |
| [variationGroups](#variationgroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of variation groups of this variation model. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAllValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getallvaluesproductvariationattribute)([ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)) | Returns the values for the specified attribute. |
| ~~[getAllValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getallvaluesobjectattributedefinition)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md))~~ | Returns the value definitions for the specified attribute. |
| ~~[getAttributeDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getattributedefinitions)()~~ | Returns the object attribute definitions corresponding with the product  variation attributes of the master product. |
| [getDefaultVariant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getdefaultvariant)() | Return the default variant of this model's master product. |
| [getFilteredValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getfilteredvaluesproductvariationattribute)([ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)) | Returns a collection of the value definitions defined for the specified  attribute, filtered based on currently selected values. |
| ~~[getFilteredValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getfilteredvaluesobjectattributedefinition)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md))~~ | Returns a collection of the value definitions defined for the specified  attribute, filtered based on currently selected values. |
| [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#gethtmlnameproductvariationattribute)([ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)) | Returns an HTML representation of the product variation attribute id. |
| ~~[getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#gethtmlnameobjectattributedefinition)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md))~~ | Returns an HTML representation of the variation attribute id. |
| [getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#gethtmlnamestring-productvariationattribute)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)) | Returns an HTML representation of the  product variation attribute id with the custom prefix. |
| ~~[getHtmlName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#gethtmlnamestring-objectattributedefinition)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md))~~ | Returns an HTML representation of the variation attribute id with the  custom prefix. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getimagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns the first image appropriate for the current selected variation values  with the specific index. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getimagestring-productvariationattribute-productvariationattributevalue)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)) | The method returns the first image appropriate for the currently selected attribute values. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getimagestring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | The method returns an image appropriate for the current selected variation values  with the specific index. |
| [getImages](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getimagesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns the image appropriate for the currently selected attribute values. |
| [getMaster](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getmaster)() | Returns the master of the product variation. |
| [getProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getproductvariationattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the product variation attribute for the specific id,  or null if there is no product variation attribute for that id. |
| [getProductVariationAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getproductvariationattributes)() | Returns a collection of product variation attributes of the variation. |
| [getSelectedValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getselectedvalueproductvariationattribute)([ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)) | Returns the selected value for the specified product variation attribute. |
| ~~[getSelectedValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getselectedvalueobjectattributedefinition)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md))~~ | Returns the selected value for the specified attribute. |
| [getSelectedVariant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getselectedvariant)() | Returns the variant currently selected for this variation model. |
| [getSelectedVariants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getselectedvariants)() | Returns the variants currently selected for this variation model. |
| [getVariants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariants)() | Returns the collection of product variants of this variation model. |
| [getVariants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariantshashmap)([HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)) | Returns the variants that match the specified filter conditions. |
| [getVariationGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariationgroups)() | Returns the collection of variation groups of this variation model. |
| [getVariationValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariationvalueproduct-productvariationattribute)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)) | Returns the value for the specified variant or variation group product and  variation attribute. |
| [hasOrderableVariants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#hasorderablevariantsproductvariationattribute-productvariationattributevalue)([ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)) | Returns true if any variant is available with the specified value of the  specified variation attribute. |
| [isSelectedAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#isselectedattributevalueproductvariationattribute-productvariationattributevalue)([ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)) | Identifies if the specified product variation attribute value is the one  currently selected. |
| ~~[isSelectedAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#isselectedattributevalueobjectattributedefinition-objectattributevaluedefinition)([ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md), [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md))~~ | Identifies if the specified variation value is the one currently  selected. |
| [setSelectedAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#setselectedattributevaluestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Applies a selected attribute value to this model instance. |
| [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs a URL to select a set of variation attribute values. |
| [urlSelectVariationValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlselectvariationvaluestring-productvariationattribute-productvariationattributevalue)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)) | Generates a URL for selecting a value for a given variation attribute. |
| ~~[urlSelectVariationValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlselectvariationvaluestring-objectattributedefinition-objectattributevaluedefinition)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md), [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md))~~ | Constructs an URL to select the specified value of the specified  variation attribute. |
| [urlUnselectVariationValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlunselectvariationvaluestring-productvariationattribute)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)) | Generates a URL for unselecting a value for a given variation attribute. |
| ~~[urlUnselectVariationValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlunselectvariationvaluestring-objectattributedefinition)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md))~~ | Constructs an URL to unselect the value of the specified variation  attribute. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### attributeDefinitions
- ~~attributeDefinitions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)`
  - : Returns the object attribute definitions corresponding with the product
      variation attributes of the master product.


    **Deprecated:**
**warning:** This method is deprecated since custom code should work with
            ProductVariationAttributes and not directly with their
            corresponding ObjectAttributeDefinitions. Use
            [getProductVariationAttributes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getproductvariationattributes) to get the
            product variation attributes.

---

### defaultVariant
- defaultVariant: [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md) `(read-only)`
  - : Return the default variant of this model's master product. If no default
      variant has been defined, return an arbitrary variant.



---

### master
- master: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the master of the product variation.


---

### productVariationAttributes
- productVariationAttributes: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of product variation attributes of the variation.


---

### selectedVariant
- selectedVariant: [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md) `(read-only)`
  - : Returns the variant currently selected for this variation model.
      Returns null if no variant is selected.



---

### selectedVariants
- selectedVariants: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the variants currently selected for this variation model.
      Returns an empty collection if no variant is selected.



---

### variants
- variants: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of product variants of this variation model.
      This collection only includes online variants. Offline variants are
      filtered out. If all variation products are required, consider using
      [Product.getVariants()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariants).
      
      The product variants are returned in no particular order.



---

### variationGroups
- variationGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of variation groups of this variation model.
      This collection only includes online variation groups. Offline variation
      groups are filtered out. If all variation group products are required,
      consider using [Product.getVariationGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationgroups).
      
      The variation groups are returned in no particular order.



---

## Method Details

### getAllValues(ProductVariationAttribute)
- getAllValues(attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the values for the specified attribute. Only values that actually
      exist for at least one of the master product's currently online and
      complete variants are returned.
      
      
      Returns an empty collection if the passed attribute is not even a
      variation attribute of the master product.


    **Parameters:**
    - attribute - the variation attribute whose values will be returned.

    **Returns:**
    - the sorted collection of ProductVariationAttributeValue instances
              representing the values defined for the specified attribute. The
              collection is sorted by the explicit sort order defined for the
              values.



---

### getAllValues(ObjectAttributeDefinition)
- ~~getAllValues(attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the value definitions for the specified attribute. Only values
      that actually exist for at least one of the master product's currently
      online and complete variants are returned.
      
      
      Returns an empty collection if the passed attribute is not even a
      variation attribute of the master product.


    **Parameters:**
    - attribute - the attribute whose values will be returned.

    **Returns:**
    - the sorted collection of ObjectAttributeValueDefinition instances
              representing the value definitions defined for the specified
              attribute. The collection is sorted by the explicit sort order
              defined for the values.


    **Deprecated:**
**warning:** This method is deprecated since custom code should work with
            ProductVariationAttributes and not directly with their
            corresponding ObjectAttributeDefinitions. Use
            [getAllValues(ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getallvaluesproductvariationattribute) to get the
            collection of ProductVariationAttributeValue instances
            instead.

---

### getAttributeDefinitions()
- ~~getAttributeDefinitions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the object attribute definitions corresponding with the product
      variation attributes of the master product.


    **Returns:**
    - the collection of ObjectAttributeDefinition instances
              corresponding with the variation attributes of the master
              product, sorted by explicit position.


    **Deprecated:**
**warning:** This method is deprecated since custom code should work with
            ProductVariationAttributes and not directly with their
            corresponding ObjectAttributeDefinitions. Use
            [getProductVariationAttributes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getproductvariationattributes) to get the
            product variation attributes.

---

### getDefaultVariant()
- getDefaultVariant(): [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md)
  - : Return the default variant of this model's master product. If no default
      variant has been defined, return an arbitrary variant.


    **Returns:**
    - the default value of this model's master product, an arbitrary
              variant if no default is defined, or null if this model does not
              represent a master product with variants.



---

### getFilteredValues(ProductVariationAttribute)
- getFilteredValues(attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of the value definitions defined for the specified
      attribute, filtered based on currently selected values.
      
      
      A value is only returned if it at least one variant has the value and
      also possesses the selected values for all previous attributes. It is
      important to know that the filter is applied in a certain order. The
      method looks at all ProductVariationAttribute instances that appear
      before the passed one in the sorted collection returned by
      [getProductVariationAttributes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getproductvariationattributes). If the passed attribute is the
      first in this collection, then this method simply returns all its values.
      If an earlier attribute does not have a selected value, this method
      returns an empty list. Otherwise, the filter looks at all variants
      matching the selected value for all previous attributes, and considers
      the range of values possessed by these variants for the passed attribute.
      
      
      The idea behind this method is that customers in the storefront select
      variation attribute values one by one in the order the variation
      attributes are defined and displayed. After each selection, customer only
      wants to see values that he can possibly order for the remaining
      attributes.
      
      
      Returns an empty collection if the passed attribute is not even a
      variation attribute of the master product.


    **Parameters:**
    - attribute - the product variation attribute whose values are to be             returned.

    **Returns:**
    - a sorted and filtered collection of product variation attribute
              values. The collection is sorted by the explicit sort order
              defined for the values.



---

### getFilteredValues(ObjectAttributeDefinition)
- ~~getFilteredValues(attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns a collection of the value definitions defined for the specified
      attribute, filtered based on currently selected values.
      
      
      A value is only returned if it at least one variant has the value and
      also possesses the selected values for all previous attributes. It is
      important to know that the filter is applied in a certain order. The
      method looks at all ObjectAttributeDefinition instances that appear
      before the passed one in the sorted collection returned by
      [getAttributeDefinitions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getattributedefinitions). If the passed attribute is the first
      in this collection, then this method simply returns all its values. If an
      earlier attribute does not have a selected value, this method returns an
      empty list. Otherwise, the filter looks at all variants matching the
      selected value for all previous attributes, and considers the range of
      values possessed by these variants for the passed attribute.
      
      
      The idea behind this method is that customers in the storefront select
      variation attribute values one by one in the order the variation
      attributes are defined and displayed. After each selection, customer only
      wants to see values that he can possibly order for the remaining
      attributes.
      
      
      Returns an empty collection if the passed attribute is not even a
      variation attribute of the master product.


    **Parameters:**
    - attribute - the attribute whose values are returned by this method.

    **Returns:**
    - a sorted collection of ObjectAttributeDefinitionValue instances
              calculated based on the currently selected variation values.


    **Deprecated:**
**warning:** Use [getFilteredValues(ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getfilteredvaluesproductvariationattribute) to
            get the sorted and calculated collection of product variation
            attribute values.

---

### getHtmlName(ProductVariationAttribute)
- getHtmlName(attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an HTML representation of the product variation attribute id.

    **Parameters:**
    - attribute - the  product variation attribute whose ID is returned.

    **Returns:**
    - an HTML representation of the product variation attribute id.


---

### getHtmlName(ObjectAttributeDefinition)
- ~~getHtmlName(attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns an HTML representation of the variation attribute id. This method
      is deprecated. You should use getHtmlName(ProductVariationAttribute)
      instead.


    **Parameters:**
    - attribute - the attribute whose ID is returned.

    **Returns:**
    - an HTML representation of the attribute id.

    **Deprecated:**
**warning:** Use [getHtmlName(ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#gethtmlnameproductvariationattribute) to get
            the HTML representation of the product variation attribute
            id.

---

### getHtmlName(String, ProductVariationAttribute)
- getHtmlName(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an HTML representation of the  product variation attribute id with the custom prefix.

    **Parameters:**
    - prefix - a custom prefix.
    - attribute - the product variation attribute whose ID is returned.

    **Returns:**
    - an HTML representation of the product variation attribute id.


---

### getHtmlName(String, ObjectAttributeDefinition)
- ~~getHtmlName(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns an HTML representation of the variation attribute id with the
      custom prefix. This method is deprecated. You should use
      [getHtmlName(String, ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#gethtmlnamestring-productvariationattribute) instead.


    **Parameters:**
    - prefix - a custom prefix.
    - attribute - the attribute whose ID is returned.

    **Returns:**
    - an HTML representation of the attribute id.

    **Deprecated:**
**warning:** Use [getHtmlName(String, ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#gethtmlnamestring-productvariationattribute)
            to get the HTML representation of the product variation
            attribute id with the custom prefix.

---

### getImage(String)
- getImage(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : The method returns the first image appropriate for the current selected variation values
      with the specific index.
      
      If images are defined for this view type and variants, but not for
      specified index, the method returns null.
      
      If no images are defined for all variants and specified view type, the
      image at the specified index of the master product images is returned. If
      no master product image for specified index is defined, the method
      returns null.
      
      The view type parameter is required, otherwise a exception is thrown.


    **Parameters:**
    - viewtype - the view type annotated to image

    **Returns:**
    - the MediaFile or null


---

### getImage(String, ProductVariationAttribute, ProductVariationAttributeValue)
- getImage(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), value: [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : The method returns the first image appropriate for the currently selected attribute values.
      
      The method first considers the most specific combination of attribute values (e.g
      "Red leather") and if that is not found, more general (e.g "Red").  If no image group
      is found for the attributes, returns null
      
      The view type parameter is required, otherwise a exception is thrown.


    **Parameters:**
    - viewtype - the view type annotated to image
    - attribute - the variation attribute
    - value - the the variation attribute value

    **Returns:**
    - the first image, or null if not found


---

### getImage(String, Number)
- getImage(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : The method returns an image appropriate for the current selected variation values
      with the specific index.
      
      If images are defined for this view type and variants, but not for
      specified index, the method returns null.
      
      If no images are defined for all variants and specified view type, the
      image at the specified index of the master product images is returned. If
      no master product image for specified index is defined, the method
      returns null.
      
      The view type parameter is required, otherwise a exception is thrown.


    **Parameters:**
    - viewtype - the view type annotated to image
    - index - the index number of the image within image list

    **Returns:**
    - the MediaFile or null


---

### getImages(String)
- getImages(viewtype: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : The method returns the image appropriate for the currently selected attribute values.
      
      The method first considers the most specific combination of attribute values (e.g
      "Red leather") and if that is not found, more general (e.g "Red").  If no image group
      is found for the attributes, returns null
      
      The view type parameter is required, otherwise a exception is thrown.


    **Parameters:**
    - viewtype - the view type annotated to image

    **Returns:**
    - an array of images


---

### getMaster()
- getMaster(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the master of the product variation.

    **Returns:**
    - the master of the product variation.


---

### getProductVariationAttribute(String)
- getProductVariationAttribute(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)
  - : Returns the product variation attribute for the specific id,
      or null if there is no product variation attribute for that id.


    **Parameters:**
    - id - the id of the product variation attribute

    **Returns:**
    - the product variation attribute, or null.


---

### getProductVariationAttributes()
- getProductVariationAttributes(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of product variation attributes of the variation.

    **Returns:**
    - a collection of product variation attributes  of the variation.


---

### getSelectedValue(ProductVariationAttribute)
- getSelectedValue(attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)): [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)
  - : Returns the selected value for the specified product variation attribute. If no value is
      selected, null is returned.


    **Parameters:**
    - attribute - the product variation attribute whose value will be returned.

    **Returns:**
    - the selected product variation attribute value for the specified attribute or null.


---

### getSelectedValue(ObjectAttributeDefinition)
- ~~getSelectedValue(attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md)~~
  - : Returns the selected value for the specified attribute. If no value is
      selected, null is returned.


    **Parameters:**
    - attribute - the attribute whose value will be returned.

    **Returns:**
    - the selected value for the specified attribute or null.

    **Deprecated:**
**warning:** Use [getSelectedValue(ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getselectedvalueproductvariationattribute) to
            get the selected product variation attribute value for the
            specified attribute.

---

### getSelectedVariant()
- getSelectedVariant(): [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md)
  - : Returns the variant currently selected for this variation model.
      Returns null if no variant is selected.


    **Returns:**
    - selected variant or null.


---

### getSelectedVariants()
- getSelectedVariants(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the variants currently selected for this variation model.
      Returns an empty collection if no variant is selected.


    **Returns:**
    - selected variants, might be empty if no valid variant was selected by the given attribute values


---

### getVariants()
- getVariants(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of product variants of this variation model.
      This collection only includes online variants. Offline variants are
      filtered out. If all variation products are required, consider using
      [Product.getVariants()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariants).
      
      The product variants are returned in no particular order.


    **Returns:**
    - a collection of all the product variants of the variation model.


---

### getVariants(HashMap)
- getVariants(filter: [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the variants that match the specified filter conditions. The
      filter conditions are specified as a hash map of <attribute\_id> -
      <value\_id>.  This method does not consider the currently selected
      attribute values.


    **Parameters:**
    - filter - the filters to apply when collecting the variants.

    **Returns:**
    - the collection of variants that match the specified filter
              conditions.



---

### getVariationGroups()
- getVariationGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of variation groups of this variation model.
      This collection only includes online variation groups. Offline variation
      groups are filtered out. If all variation group products are required,
      consider using [Product.getVariationGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationgroups).
      
      The variation groups are returned in no particular order.


    **Returns:**
    - a collection of all the variation groups of the variation model.


---

### getVariationValue(Product, ProductVariationAttribute)
- getVariationValue(variantOrVariationGroup: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)): [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)
  - : Returns the value for the specified variant or variation group product and
      variation attribute. The specified product should be a [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md)
      returned by [getVariants()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariants) or a [VariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md) returned by
      [getVariationGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getvariationgroups). The variation attribute should be one returned by
      [getProductVariationAttributes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#getproductvariationattributes). If an invalid product or attribute is passed,
      null is returned. If null is passed for either argument, an exception is thrown.


    **Parameters:**
    - variantOrVariationGroup - the variant or variation group product to retrieve a value for,         must not be null.
    - attribute - the product variation attribute to get the value for, must not be null.

    **Returns:**
    - the attribute value for the specified variant or variation group and attribute, or
              null if an invalid variant, variation group or attribute is passed or the variation
              group define no value for the variation attribute.



---

### hasOrderableVariants(ProductVariationAttribute, ProductVariationAttributeValue)
- hasOrderableVariants(attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), value: [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if any variant is available with the specified value of the
      specified variation attribute. Available means that the variant is
      orderable according to the variant's availability model. This method
      takes currently selected attribute values into consideration. The
      specific rules are as follows:
      
      - If no variation value is currently selected, the method returns true  if any variant with the specified value is available, else false.
      - if one or more variation values are selected, the method returns true  if any variant with a combination of the specified value and the selected  value is available, else false.
      - if all variation values are selected, the method returns true of the  variant that is represented by the current selection is available, else  false.


    **Parameters:**
    - attribute - The product variation attribute whose values are to be             tested for orderable variants.
    - value - The specific attribute value to test for orderable variants.

    **Returns:**
    - true if any variant is available with the specified value of the
              specified variation attribute based on the currently selected
              attribute values, false otherwise.



---

### isSelectedAttributeValue(ProductVariationAttribute, ProductVariationAttributeValue)
- isSelectedAttributeValue(attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), value: [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the specified product variation attribute value is the one
      currently selected.


    **Parameters:**
    - attribute - the attribute to check.
    - value - the value to check for selection.

    **Returns:**
    - true if the specified variation attribute value is currently
              selected, false otherwise.



---

### isSelectedAttributeValue(ObjectAttributeDefinition, ObjectAttributeValueDefinition)
- ~~isSelectedAttributeValue(attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md), value: [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Identifies if the specified variation value is the one currently
      selected.


    **Parameters:**
    - attribute - the attribute to check.
    - value - the value to check for selection.

    **Returns:**
    - true if the specified variation value is currently selected,
              false otherwise.


    **Deprecated:**
**warning:** Use
            [isSelectedAttributeValue(ProductVariationAttribute, ProductVariationAttributeValue)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#isselectedattributevalueproductvariationattribute-productvariationattributevalue)
            to identify if the specified product variation attribute
            value is the one currently selected.

---

### setSelectedAttributeValue(String, String)
- setSelectedAttributeValue(variationAttributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), variationAttributeValueID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Applies a selected attribute value to this model instance.
      Usually this method is used to set the model state corresponding to the variation attribute values
      specified by a URL. The URLs can be obtained by using one of the models URL methods, like
      [urlSelectVariationValue(String, ProductVariationAttribute, ProductVariationAttributeValue)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlselectvariationvaluestring-productvariationattribute-productvariationattributevalue) and
      [urlUnselectVariationValue(String, ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlunselectvariationvaluestring-productvariationattribute).
      
      Anyway, there are some limitations to keep in mind when selecting variation attribute values.
      A Variation Model created for a Variation Group or Variant Product is bound to an initial state.
      Example:
      
      - A Variation Model created for Variation Group A can't be switched to Variation Group B.
      - A Variation Model created for Variant A can't be switched to Variant B.
      - The state of a Variation Model for a Variation Group that defines color = red can't be changed to color = black.
      - The state of a Variation Model for a Variant that defines color = red / size = L can't be changed to color = black / size = S.  However, the state of a Variation Model created for a Variation Group that defines color = red  can be changed to a more specific state by adding another selected value, e.g. size = L.
      
      The state of a Variation Model created for a Variation Master can be changed in any possible way
      because the initial state involves all variation values and Variants.


    **Parameters:**
    - variationAttributeID - the ID of an product variation attribute, must not be `null`, otherwise a exception is thrown
    - variationAttributeValueID - the ID of the product variation attribute value to apply, this value must not be part of the initial model state (e.g. the variant or group that the model has been created for), otherwise a exception is thrown


---

### url(String, Object...)
- url(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), varAttrAndValues: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs a URL to select a set of variation attribute values. The
      optional `varAttrAndValues` argument can be empty, or can
      contain one or more variation attribute / value pairs. This variable list
      should be even in length, with attributes and values alternating.
      Attributes can be specified as instances of ProductVariationAttribute, or
      String variation attribute ID. (Note: ObjectAttributeDefinition IDs are
      not supported.) Values can be specified as instances of
      ProductVariationAttributeValue or String or Integer depending on the data
      type of the variation attribute. If a parameter type is invalid, or does
      not reference a valid ProductVariationAttribute or
      ProductVariationAttributeValue, then the parameter pair is not included
      in the generated URL. The returned URL will contain variation attributes
      and values already selected in the product variation model, as well as
      attributes and values specified as method parameters. 
      
      
      Sample usage: 
      
      
      
      ```
      master.variationModel.url("Product-Show", "color", "red", "size", "XL"); 
      
      master.variationModel.url("Product-Show", colorVarAttr, colorValue, sizeVarAttr, sizeValue); 
      
      // --> on/demandware.store/Sites-SiteGenesis-Site/default/Product-Show?pid=master_id&dwvar_color=red&dwvar_size=XL
      ```


    **Parameters:**
    - action - The pipeline action.
    - varAttrAndValues - Variable length list of attributes and             corresponding values to select.

    **Returns:**
    - The constructed URL.


---

### urlSelectVariationValue(String, ProductVariationAttribute, ProductVariationAttributeValue)
- urlSelectVariationValue(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md), value: [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Generates a URL for selecting a value for a given variation attribute.
      This URL is intended to be used on dynamic product detail pages. When a
      customer selects which value he wants for one of the variation
      attributes, the product detail page can issue a request to the passed URL
      which in turn can invoke the
      `UpdateProductVariationSelections` pipelet. That pipelet reads
      the querystring parameters and returns an updated variation model with
      the desired attribute value selected.
      
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - the pipeline action, e.g. "Product-Show".
    - attribute - the product variation attribute to select a value for.
    - value - the product variation attribute value to select.

    **Returns:**
    - the generated URL, an absolute URL which uses the protocol of the
              current request.



---

### urlSelectVariationValue(String, ObjectAttributeDefinition, ObjectAttributeValueDefinition)
- ~~urlSelectVariationValue(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md), value: [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Constructs an URL to select the specified value of the specified
      variation attribute.
      
      
      The generated URL will be an absolute URL which uses the protocol of the
      current request.


    **Parameters:**
    - action - the pipeline action, e.g. "Product-Show".
    - attribute - the attribute to select a value for.
    - value - the attribute definition value portion of the variation.

    **Returns:**
    - the generated URL, an absolute URL which uses the protocol of the
              current request.


    **Deprecated:**
**warning:** Use
            [urlSelectVariationValue(String, ProductVariationAttribute, ProductVariationAttributeValue)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlselectvariationvaluestring-productvariationattribute-productvariationattributevalue)
            to construct an URL to select the specified product variation
            attribute value of the specified product variation attribute.

---

### urlUnselectVariationValue(String, ProductVariationAttribute)
- urlUnselectVariationValue(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attribute: [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Generates a URL for unselecting a value for a given variation attribute.
      This URL is intended to be used on dynamic product detail pages. When a
      customer deselects a value for one of the variation attributes, the
      product detail page can issue a request to the passed URL which in turn
      can invoke the `UpdateProductVariationSelections` pipelet.
      That pipelet reads the querystring parameters and returns an updated
      variation model with the desired attribute value unselected.
      
      
      The generated URL will be an absolute URL which uses the protocol of
      the current request.


    **Parameters:**
    - action - the pipeline action, e.g. "Product-Show".
    - attribute - the product variation attribute to unselect.

    **Returns:**
    - the generated URL, an absolute URL which uses the protocol of the
              current request.



---

### urlUnselectVariationValue(String, ObjectAttributeDefinition)
- ~~urlUnselectVariationValue(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attribute: [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Constructs an URL to unselect the value of the specified variation
      attribute.
      
      
      The generated URL will be an absolute URL which uses the protocol of the
      current request.


    **Parameters:**
    - action - the pipeline action, e.g. "Product-Show".
    - attribute - the attribute to unselect.

    **Returns:**
    - the generated URL, an absolute URL which uses the protocol of the
              current request.


    **Deprecated:**
**warning:** Use
            [urlUnselectVariationValue(String, ProductVariationAttribute)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md#urlunselectvariationvaluestring-productvariationattribute)
            to unselect the product variation attribute value of the
            specified product variation attribute.

---

<!-- prettier-ignore-end -->

<!-- document id=1b7b66dbb67f043a1834ae0bd6df5b3d6f4ad395a81e27d3a51fa2821ed0860e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.Profile.md -->

<!-- prettier-ignore-start -->
# Class Profile

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md)
        - [dw.customer.Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md)

The class represents a customer profile. It also provides access to the
customers address book and credentials.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Property Summary

| Property | Description |
| --- | --- |
| [addressBook](#addressbook): [AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md) `(read-only)` | Returns the customer's address book. |
| [birthday](#birthday): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns the customer's birthday as a date. |
| [companyName](#companyname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's company name. |
| [credentials](#credentials): [Credentials](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md) `(read-only)` | Returns the customer's credentials. |
| [customer](#customer): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)` | Returns the customer object related to this profile. |
| [customerNo](#customerno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the customer's number, which is a number used to identify the Customer. |
| [email](#email): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's email address. |
| [emailVerified](#emailverified): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether the customer's email has been verified. |
| [fax](#fax): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the fax number to use for the customer. |
| [female](#female): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates that the customer is female when set to true. |
| [firstName](#firstname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's first name. |
| [gender](#gender): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the customer's gender. |
| [jobTitle](#jobtitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's job title. |
| [lastLoginTime](#lastlogintime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the last login time of the customer. |
| [lastName](#lastname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's last name. |
| [lastVisitTime](#lastvisittime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the last visit time of the customer. |
| [male](#male): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Indicates that the customer is male when set to true. |
| [nextBirthday](#nextbirthday): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the upcoming customer's birthday as a date. |
| [phoneBusiness](#phonebusiness): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the business phone number to use for the customer. |
| [phoneHome](#phonehome): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the phone number to use for the customer. |
| [phoneMobile](#phonemobile): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the mobile phone number to use for the customer. |
| [preferredLocale](#preferredlocale): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's preferred locale. |
| [previousLoginTime](#previouslogintime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the time the customer logged in prior to the current login. |
| [previousVisitTime](#previousvisittime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the time the customer visited the store prior to the current visit. |
| [salutation](#salutation): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the salutation to use for the customer. |
| [secondName](#secondname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's second name. |
| [suffix](#suffix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's suffix, such as "Jr." or "Sr.". |
| [taxID](#taxid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the tax ID value. |
| [taxIDMasked](#taxidmasked): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the masked value of the tax ID. |
| [taxIDType](#taxidtype): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the tax ID type. |
| [title](#title): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the customer's title, such as "Mrs" or "Mr". |
| [wallet](#wallet): [Wallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md) `(read-only)` | Returns the wallet of this customer. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getaddressbook)() | Returns the customer's address book. |
| [getBirthday](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getbirthday)() | Returns the customer's birthday as a date. |
| [getCompanyName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getcompanyname)() | Returns the customer's company name. |
| [getCredentials](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getcredentials)() | Returns the customer's credentials. |
| [getCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getcustomer)() | Returns the customer object related to this profile. |
| [getCustomerNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getcustomerno)() | Returns the customer's number, which is a number used to identify the Customer. |
| [getEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getemail)() | Returns the customer's email address. |
| [getFax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getfax)() | Returns the fax number to use for the customer. |
| [getFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getfirstname)() | Returns the customer's first name. |
| [getGender](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getgender)() | Returns the customer's gender. |
| [getJobTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getjobtitle)() | Returns the customer's job title. |
| [getLastLoginTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getlastlogintime)() | Returns the last login time of the customer. |
| [getLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getlastname)() | Returns the customer's last name. |
| [getLastVisitTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getlastvisittime)() | Returns the last visit time of the customer. |
| [getNextBirthday](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getnextbirthday)() | Returns the upcoming customer's birthday as a date. |
| [getPhoneBusiness](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getphonebusiness)() | Returns the business phone number to use for the customer. |
| [getPhoneHome](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getphonehome)() | Returns the phone number to use for the customer. |
| [getPhoneMobile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getphonemobile)() | Returns the mobile phone number to use for the customer. |
| [getPreferredLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getpreferredlocale)() | Returns the customer's preferred locale. |
| [getPreviousLoginTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getpreviouslogintime)() | Returns the time the customer logged in prior to the current login. |
| [getPreviousVisitTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getpreviousvisittime)() | Returns the time the customer visited the store prior to the current visit. |
| [getSalutation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getsalutation)() | Returns the salutation to use for the customer. |
| [getSecondName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getsecondname)() | Returns the customer's second name. |
| [getSuffix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getsuffix)() | Returns the customer's suffix, such as "Jr." or "Sr.". |
| [getTaxID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#gettaxid)() | Returns the tax ID value. |
| [getTaxIDMasked](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#gettaxidmasked)() | Returns the masked value of the tax ID. |
| [getTaxIDType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#gettaxidtype)() | Returns the tax ID type. |
| [getTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#gettitle)() | Returns the customer's title, such as "Mrs" or "Mr". |
| [getWallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#getwallet)() | Returns the wallet of this customer. |
| [isEmailVerified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#isemailverified)() | Returns whether the customer's email has been verified. |
| [isFemale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#isfemale)() | Indicates that the customer is female when set to true. |
| [isMale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#ismale)() | Indicates that the customer is male when set to true. |
| [setBirthday](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setbirthdaydate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the customer's birthday as a date. |
| [setCompanyName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setcompanynamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's company name. |
| [setEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setemailstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's email address. |
| [setFax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setfaxstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the fax number to use for the customer. |
| [setFirstName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setfirstnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's first name. |
| [setGender](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setgendernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the customer's gender. |
| [setJobTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setjobtitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's job title. |
| [setLastName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setlastnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's last name. |
| [setPhoneBusiness](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setphonebusinessstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the business phone number to use for the customer. |
| [setPhoneHome](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setphonehomestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the phone number to use for the customer. |
| [setPhoneMobile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setphonemobilestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the mobile phone number to use for the customer. |
| [setPreferredLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setpreferredlocalestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's preferred locale. |
| ~~[setSaluation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setsaluationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the salutation to use for the customer. |
| [setSalutation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setsalutationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the salutation to use for the customer. |
| [setSecondName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setsecondnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's second name. |
| [setSuffix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setsuffixstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the the customer's suffix. |
| [setTaxID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#settaxidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the tax ID value. |
| [setTaxIDType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#settaxidtypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the tax ID type. |
| [setTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#settitlestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the customer's title. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### addressBook
- addressBook: [AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md) `(read-only)`
  - : Returns the customer's address book.


---

### birthday
- birthday: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the customer's birthday as a date.


---

### companyName
- companyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's company name.


---

### credentials
- credentials: [Credentials](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md) `(read-only)`
  - : Returns the customer's credentials.


---

### customer
- customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)`
  - : Returns the customer object related to this profile.


---

### customerNo
- customerNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the customer's number, which is a number used to identify the Customer.


---

### email
- email: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's email address.


---

### emailVerified
- emailVerified: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether the customer's email has been verified.
      
      
      This is a read-only field. The field value cannot be set externally and will be set in platform based on
      following rules:
      
      
      
      - If the Email Verification Site Preference under LoginPreferences is disabled: the value for this field will  always be NULL;
      - If the Email Verification Site Preference under LoginPreferences is enabled:  
        - If the incoming email value is the same as existing email and email was previously verified, the value for    this field will remain unchanged as TRUE;
        - If the incoming email value is the same as existing email and email was not previously verified, the value    for this field will remain unchanged as FALSE;
        - If the incoming email value is not the same as existing email, the value for this field will be set to FALSE    no matter the previous state;



---

### fax
- fax: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the fax number to use for the customer.
      The length is restricted to 32 characters.



---

### female
- female: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates that the customer is female when set to true.


---

### firstName
- firstName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first name.


---

### gender
- gender: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the customer's gender.


---

### jobTitle
- jobTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's job title.


---

### lastLoginTime
- lastLoginTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the last login time of the customer.


---

### lastName
- lastName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's last name.


---

### lastVisitTime
- lastVisitTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the last visit time of the customer.


---

### male
- male: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Indicates that the customer is male when set to true.


---

### nextBirthday
- nextBirthday: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the upcoming customer's birthday as a date.
      If the customer already had birthday this year the method returns the birthday of the next year.
      Otherwise its birthday in this year.
      If the customer has not set a birthday this method returns null.



---

### phoneBusiness
- phoneBusiness: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the business phone number to use for the customer.


---

### phoneHome
- phoneHome: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the phone number to use for the customer.


---

### phoneMobile
- phoneMobile: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the mobile phone number to use for the customer.


---

### preferredLocale
- preferredLocale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's preferred locale.


---

### previousLoginTime
- previousLoginTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the time the customer logged in prior to the current login.


---

### previousVisitTime
- previousVisitTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the time the customer visited the store prior to the current visit.


---

### salutation
- salutation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the salutation to use for the customer.


---

### secondName
- secondName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second name.


---

### suffix
- suffix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suffix, such as "Jr." or "Sr.".


---

### taxID
- taxID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tax ID value. The value is returned either plain
      text if the current context allows plain text access, or
      if it's not allowed, the ID value will be returned masked.
      The following criteria must be met in order to have plain text access:
      
      
      
      - the method call must happen in the context of a storefront request;
      - the current customer must be registered and authenticated;
      - it is the profile of the current customer;
      - and the current protocol is HTTPS.



---

### taxIDMasked
- taxIDMasked: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the masked value of the tax ID.


---

### taxIDType
- taxIDType: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the tax ID type.


---

### title
- title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's title, such as "Mrs" or "Mr".


---

### wallet
- wallet: [Wallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md) `(read-only)`
  - : Returns the wallet of this customer.


---

## Method Details

### getAddressBook()
- getAddressBook(): [AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md)
  - : Returns the customer's address book.

    **Returns:**
    - the customer's address book.


---

### getBirthday()
- getBirthday(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the customer's birthday as a date.

    **Returns:**
    - the customer's birthday as a date.


---

### getCompanyName()
- getCompanyName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's company name.

    **Returns:**
    - the customer's company name.


---

### getCredentials()
- getCredentials(): [Credentials](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md)
  - : Returns the customer's credentials.

    **Returns:**
    - the customer's credentials.


---

### getCustomer()
- getCustomer(): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer object related to this profile.

    **Returns:**
    - customer object related to profile.


---

### getCustomerNo()
- getCustomerNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's number, which is a number used to identify the Customer.

    **Returns:**
    - the customer's number.


---

### getEmail()
- getEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's email address.

    **Returns:**
    - the customer's email address.


---

### getFax()
- getFax(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the fax number to use for the customer.
      The length is restricted to 32 characters.


    **Returns:**
    - the fax mobile phone number to use for the customer.


---

### getFirstName()
- getFirstName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's first name.

    **Returns:**
    - the customer's first name.


---

### getGender()
- getGender(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the customer's gender.

    **Returns:**
    - the customer's gender.


---

### getJobTitle()
- getJobTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's job title.

    **Returns:**
    - the customer's job title.


---

### getLastLoginTime()
- getLastLoginTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the last login time of the customer.

    **Returns:**
    - the time, when the customer was last logged in.


---

### getLastName()
- getLastName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's last name.

    **Returns:**
    - the customer's last name.


---

### getLastVisitTime()
- getLastVisitTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the last visit time of the customer.

    **Returns:**
    - the time, when the customer has visited the storefront the
              last time (with enabled remember me functionality).



---

### getNextBirthday()
- getNextBirthday(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the upcoming customer's birthday as a date.
      If the customer already had birthday this year the method returns the birthday of the next year.
      Otherwise its birthday in this year.
      If the customer has not set a birthday this method returns null.


    **Returns:**
    - the customer's next birthday as a date.


---

### getPhoneBusiness()
- getPhoneBusiness(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the business phone number to use for the customer.

    **Returns:**
    - the business phone number to use for the customer.


---

### getPhoneHome()
- getPhoneHome(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the phone number to use for the customer.

    **Returns:**
    - the phone number to use for the customer.


---

### getPhoneMobile()
- getPhoneMobile(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the mobile phone number to use for the customer.

    **Returns:**
    - the mobile phone number to use for the customer.


---

### getPreferredLocale()
- getPreferredLocale(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's preferred locale.

    **Returns:**
    - the customer's preferred locale.


---

### getPreviousLoginTime()
- getPreviousLoginTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the time the customer logged in prior to the current login.

    **Returns:**
    - the time the customer logged in prior to the current login.


---

### getPreviousVisitTime()
- getPreviousVisitTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the time the customer visited the store prior to the current visit.

    **Returns:**
    - the time the customer visited the store prior to the current visit.


---

### getSalutation()
- getSalutation(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the salutation to use for the customer.

    **Returns:**
    - the salutation to use for the customer.


---

### getSecondName()
- getSecondName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's second name.

    **Returns:**
    - the customer's second name.


---

### getSuffix()
- getSuffix(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's suffix, such as "Jr." or "Sr.".

    **Returns:**
    - the customer's suffix.


---

### getTaxID()
- getTaxID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tax ID value. The value is returned either plain
      text if the current context allows plain text access, or
      if it's not allowed, the ID value will be returned masked.
      The following criteria must be met in order to have plain text access:
      
      
      
      - the method call must happen in the context of a storefront request;
      - the current customer must be registered and authenticated;
      - it is the profile of the current customer;
      - and the current protocol is HTTPS.


    **Returns:**
    - the tax ID value


---

### getTaxIDMasked()
- getTaxIDMasked(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the masked value of the tax ID.

    **Returns:**
    - the masked value of the tax ID


---

### getTaxIDType()
- getTaxIDType(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the tax ID type.

    **Returns:**
    - the tax ID type


---

### getTitle()
- getTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the customer's title, such as "Mrs" or "Mr".

    **Returns:**
    - the customer's title.


---

### getWallet()
- getWallet(): [Wallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md)
  - : Returns the wallet of this customer.

    **Returns:**
    - the wallet of this customer.


---

### isEmailVerified()
- isEmailVerified(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether the customer's email has been verified.
      
      
      This is a read-only field. The field value cannot be set externally and will be set in platform based on
      following rules:
      
      
      
      - If the Email Verification Site Preference under LoginPreferences is disabled: the value for this field will  always be NULL;
      - If the Email Verification Site Preference under LoginPreferences is enabled:  
        - If the incoming email value is the same as existing email and email was previously verified, the value for    this field will remain unchanged as TRUE;
        - If the incoming email value is the same as existing email and email was not previously verified, the value    for this field will remain unchanged as FALSE;
        - If the incoming email value is not the same as existing email, the value for this field will be set to FALSE    no matter the previous state;


    **Returns:**
    - true if the email is verified, false if not verified, or null if the verification status has not been set.


---

### isFemale()
- isFemale(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates that the customer is female when set to true.

    **Returns:**
    - true if the customer is a female, false otherwise.


---

### isMale()
- isMale(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates that the customer is male when set to true.

    **Returns:**
    - true if the customer is a male, false otherwise.


---

### setBirthday(Date)
- setBirthday(aValue: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the customer's birthday as a date.

    **Parameters:**
    - aValue - the customer's birthday as a date.


---

### setCompanyName(String)
- setCompanyName(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's company name.

    **Parameters:**
    - aValue - the customer's company name.


---

### setEmail(String)
- setEmail(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's email address.

    **Parameters:**
    - aValue - the customer's email address.


---

### setFax(String)
- setFax(number: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the fax number to use for the customer.
      The length is restricted to 32 characters.


    **Parameters:**
    - number - the fax number to use for the customer.


---

### setFirstName(String)
- setFirstName(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's first name.

    **Parameters:**
    - aValue - the customer's first name.


---

### setGender(Number)
- setGender(aValue: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the customer's gender.

    **Parameters:**
    - aValue - the customer's gender.


---

### setJobTitle(String)
- setJobTitle(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's job title.

    **Parameters:**
    - aValue - the customer's job title.


---

### setLastName(String)
- setLastName(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's last name.

    **Parameters:**
    - aValue - the customer's last name.


---

### setPhoneBusiness(String)
- setPhoneBusiness(number: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the business phone number to use for the customer.
      The length is restricted to 32 characters.


    **Parameters:**
    - number - the business phone number to use for the customer.


---

### setPhoneHome(String)
- setPhoneHome(number: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the phone number to use for the customer.
      The length is restricted to 32 characters.


    **Parameters:**
    - number - the phone number to use for the customer.


---

### setPhoneMobile(String)
- setPhoneMobile(number: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the mobile phone number to use for the customer.
      The length is restricted to 32 characters.


    **Parameters:**
    - number - the mobile phone number to use for the customer.


---

### setPreferredLocale(String)
- setPreferredLocale(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's preferred locale.

    **Parameters:**
    - aValue - the customer's preferred locale.


---

### setSaluation(String)
- ~~setSaluation(salutation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the salutation to use for the customer.

    **Parameters:**
    - salutation - the salutation to use for the customer.

    **Deprecated:**
**warning:** Use [setSalutation(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md#setsalutationstring)

---

### setSalutation(String)
- setSalutation(salutation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the salutation to use for the customer.

    **Parameters:**
    - salutation - the salutation to use for the customer.


---

### setSecondName(String)
- setSecondName(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's second name.

    **Parameters:**
    - aValue - the customer's second name.


---

### setSuffix(String)
- setSuffix(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the the customer's suffix.

    **Parameters:**
    - aValue - the customer's suffix.


---

### setTaxID(String)
- setTaxID(taxID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the tax ID value. The value can be set if the current context
      allows write access.
      The current context allows write access if the currently
      logged in user owns this profile and the connection is secured.


    **Parameters:**
    - taxID - the tax ID value to set


---

### setTaxIDType(String)
- setTaxIDType(taxIdType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the tax ID type.

    **Parameters:**
    - taxIdType - the tax ID type to set


---

### setTitle(String)
- setTitle(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the customer's title.

    **Parameters:**
    - aValue - the customer's title.


---

<!-- prettier-ignore-end -->

<!-- document id=7c91ca4578a190ac717a6e6bca53ec19bfae3ca87cbff8ca87baa1050217c9d9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.Promotion.md -->

<!-- prettier-ignore-start -->
# Class Promotion

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.campaign.Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)

This class represents a promotion in Commerce Cloud Digital. Examples of
promotions include:


- "Get 20% off your order"
- "$15 off a given product"
- "free shipping for all orders over $50"
- Get a bonus product with purchase of another product


The Promotion class provides access to the basic attributes of the promotion
such as name, callout message, and description, but the details of the
promotion rules are not available in the API due to their complexity.


Commerce Cloud Digital allows merchants to create a single logical "promotion
rule" (e.g. "Get 20% off your order") and then assign it to one or more
"containers" where the supported container types are campaigns or AB-tests. A
Promotion represents a specific instance of a promotion rule assigned to a
container. Promotion rules themselves that are not assigned to any container
are inaccessible through the API. Each instance (i.e. assignment) can have
separate "qualifiers". Qualifiers are the customer groups, source code
groups, or coupons that trigger a given promotion for a customer.



## Constant Summary

| Constant | Description |
| --- | --- |
| [EXCLUSIVITY_CLASS](#exclusivity_class): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CLASS" | Constant representing promotion exclusivity of type _class_. |
| [EXCLUSIVITY_GLOBAL](#exclusivity_global): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GLOBAL" | Constant representing promotion exclusivity of type _global_. |
| [EXCLUSIVITY_NO](#exclusivity_no): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO" | Constant representing promotion exclusivity of type _no_. |
| [PROMOTION_CLASS_ORDER](#promotion_class_order): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER" | Constant representing promotion class of type _order_. |
| [PROMOTION_CLASS_PRODUCT](#promotion_class_product): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRODUCT" | Constant representing promotion class of type _product_. |
| [PROMOTION_CLASS_SHIPPING](#promotion_class_shipping): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPING" | Constant representing promotion class of type _shipping_. |
| [QUALIFIER_MATCH_MODE_ALL](#qualifier_match_mode_all): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "all" | Constant indicating that that all qualifier conditions must be met in  order for this promotion to apply for a given customer. |
| [QUALIFIER_MATCH_MODE_ANY](#qualifier_match_mode_any): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "any" | Constant indicating that that at least one qualifier condition must be  met in order for this promotion to apply for a given customer. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique ID of the promotion. |
| [active](#active): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if promotion is active, otherwise 'false'. |
| ~~[basedOnCoupon](#basedoncoupon): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Returns 'true' if the promotion is triggered by a coupon,  false otherwise. |
| [basedOnCoupons](#basedoncoupons): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the promotion is triggered by coupons,  false otherwise. |
| [basedOnCustomerGroups](#basedoncustomergroups): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the promotion is triggered by customer groups,  false otherwise. |
| [basedOnSourceCodes](#basedonsourcecodes): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the promotion is triggered by source codes,  false otherwise. |
| [calloutMsg](#calloutmsg): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the callout message of the promotion. |
| [campaign](#campaign): [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md) `(read-only)` | Returns the campaign this particular instance of the promotion is defined  in. |
| [combinablePromotions](#combinablepromotions): [String\[\]](TopLevel.String.md) `(read-only)` | Returns the promotion's combinable promotions. |
| ~~[conditionalDescription](#conditionaldescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)~~ `(read-only)` | Returns a description of the condition that must be met for this  promotion to be applicable. |
| [coupons](#coupons): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the coupons directly assigned to the promotion or assigned to the campaign of the promotion. |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes for this extensible object. |
| [customerGroups](#customergroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the customer groups directly assigned to the promotion or assigned to the campaign of the promotion. |
| ~~[description](#description): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)~~ `(read-only)` | Returns the description of the promotion. |
| [details](#details): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the detailed description of the promotion. |
| [enabled](#enabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if promotion is enabled, otherwise false. |
| [endDate](#enddate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the effective end date of this instance of the promotion. |
| [exclusivity](#exclusivity): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the promotion's exclusivity specifying how the promotion can be  combined with other promotions. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the reference to the promotion image. |
| [lastModified](#lastmodified): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the date that this object was last modified. |
| [mutuallyExclusivePromotions](#mutuallyexclusivepromotions): [String\[\]](TopLevel.String.md) `(read-only)` | Returns the promotion's mutually exclusive Promotions. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the promotion. |
| [promotionClass](#promotionclass): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the promotion class indicating the general type of the promotion. |
| [qualifierMatchMode](#qualifiermatchmode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the qualifier matching mode specified by this promotion. |
| [rank](#rank): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the promotion's rank. |
| [refinable](#refinable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if promotion is refinable, otherwise false. |
| [sourceCodeGroups](#sourcecodegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the source code groups directly assigned to the promotion or assigned to the campaign of the promotion. |
| [startDate](#startdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the effective start date of this instance of the promotion. |
| [tags](#tags): [String\[\]](TopLevel.String.md) `(read-only)` | Returns the promotion's tags. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCalloutMsg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcalloutmsg)() | Returns the callout message of the promotion. |
| [getCampaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcampaign)() | Returns the campaign this particular instance of the promotion is defined  in. |
| [getCombinablePromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcombinablepromotions)() | Returns the promotion's combinable promotions. |
| ~~[getConditionalDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getconditionaldescription)()~~ | Returns a description of the condition that must be met for this  promotion to be applicable. |
| [getCoupons](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcoupons)() | Returns the coupons directly assigned to the promotion or assigned to the campaign of the promotion. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcustom)() | Returns the custom attributes for this extensible object. |
| [getCustomerGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcustomergroups)() | Returns the customer groups directly assigned to the promotion or assigned to the campaign of the promotion. |
| ~~[getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getdescription)()~~ | Returns the description of the promotion. |
| [getDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getdetails)() | Returns the detailed description of the promotion. |
| [getEndDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getenddate)() | Returns the effective end date of this instance of the promotion. |
| [getExclusivity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getexclusivity)() | Returns the promotion's exclusivity specifying how the promotion can be  combined with other promotions. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getid)() | Returns the unique ID of the promotion. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getimage)() | Returns the reference to the promotion image. |
| [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getlastmodified)() | Returns the date that this object was last modified. |
| [getMutuallyExclusivePromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getmutuallyexclusivepromotions)() | Returns the promotion's mutually exclusive Promotions. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getname)() | Returns the name of the promotion. |
| [getPromotionClass](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getpromotionclass)() | Returns the promotion class indicating the general type of the promotion. |
| [getPromotionalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getpromotionalpriceproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the promotional price for the specified product. |
| [getPromotionalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getpromotionalpriceproduct-productoptionmodel)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)) | This method follows the same logic as  [getPromotionalPrice(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getpromotionalpriceproduct) but prices are calculated based  on the option values selected in the specified option model. |
| [getQualifierMatchMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getqualifiermatchmode)() | Returns the qualifier matching mode specified by this promotion. |
| [getRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getrank)() | Returns the promotion's rank. |
| [getSourceCodeGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getsourcecodegroups)() | Returns the source code groups directly assigned to the promotion or assigned to the campaign of the promotion. |
| [getStartDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getstartdate)() | Returns the effective start date of this instance of the promotion. |
| [getTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#gettags)() | Returns the promotion's tags. |
| [isActive](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isactive)() | Returns 'true' if promotion is active, otherwise 'false'. |
| ~~[isBasedOnCoupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncoupon)()~~ | Returns 'true' if the promotion is triggered by a coupon,  false otherwise. |
| [isBasedOnCoupons](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncoupons)() | Returns 'true' if the promotion is triggered by coupons,  false otherwise. |
| [isBasedOnCustomerGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncustomergroups)() | Returns 'true' if the promotion is triggered by customer groups,  false otherwise. |
| [isBasedOnSourceCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedonsourcecodes)() | Returns 'true' if the promotion is triggered by source codes,  false otherwise. |
| [isEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isenabled)() | Returns true if promotion is enabled, otherwise false. |
| [isRefinable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isrefinable)() | Returns true if promotion is refinable, otherwise false. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### EXCLUSIVITY_CLASS

- EXCLUSIVITY_CLASS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CLASS"
  - : Constant representing promotion exclusivity of type _class_.


---

### EXCLUSIVITY_GLOBAL

- EXCLUSIVITY_GLOBAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GLOBAL"
  - : Constant representing promotion exclusivity of type _global_.


---

### EXCLUSIVITY_NO

- EXCLUSIVITY_NO: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO"
  - : Constant representing promotion exclusivity of type _no_.


---

### PROMOTION_CLASS_ORDER

- PROMOTION_CLASS_ORDER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ORDER"
  - : Constant representing promotion class of type _order_.


---

### PROMOTION_CLASS_PRODUCT

- PROMOTION_CLASS_PRODUCT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PRODUCT"
  - : Constant representing promotion class of type _product_.


---

### PROMOTION_CLASS_SHIPPING

- PROMOTION_CLASS_SHIPPING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPING"
  - : Constant representing promotion class of type _shipping_.


---

### QUALIFIER_MATCH_MODE_ALL

- QUALIFIER_MATCH_MODE_ALL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "all"
  - : Constant indicating that that all qualifier conditions must be met in
      order for this promotion to apply for a given customer.



---

### QUALIFIER_MATCH_MODE_ANY

- QUALIFIER_MATCH_MODE_ANY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "any"
  - : Constant indicating that that at least one qualifier condition must be
      met in order for this promotion to apply for a given customer.



---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique ID of the promotion.


---

### active
- active: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if promotion is active, otherwise 'false'. 
      
      A promotion is active if its campaign is active, and the promotion
      is enabled, and it is scheduled for _now_.



---

### basedOnCoupon
- ~~basedOnCoupon: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Returns 'true' if the promotion is triggered by a coupon,
      false otherwise.


    **Deprecated:**
**warning:** Use [isBasedOnCoupons()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncoupons)

---

### basedOnCoupons
- basedOnCoupons: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the promotion is triggered by coupons,
      false otherwise.



---

### basedOnCustomerGroups
- basedOnCustomerGroups: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the promotion is triggered by customer groups,
      false otherwise.



---

### basedOnSourceCodes
- basedOnSourceCodes: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the promotion is triggered by source codes,
      false otherwise.



---

### calloutMsg
- calloutMsg: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the callout message of the promotion.


---

### campaign
- campaign: [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md) `(read-only)`
  - : Returns the campaign this particular instance of the promotion is defined
      in.
      
      
      Note: If this promotion is defined as part of an AB-test, then a Campaign
      object will be returned, but it is a mock implementation, and not a true
      Campaign. This behavior is required for backwards compatibility and
      should not be relied upon as it may change in future releases.



---

### combinablePromotions
- combinablePromotions: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns the promotion's combinable promotions. Combinable promotions is a set of promotions or groups this
      promotion can be combined with.



---

### conditionalDescription
- ~~conditionalDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)~~ `(read-only)`
  - : Returns a description of the condition that must be met for this
      promotion to be applicable.
      
      
      The method and the related attribute have been deprecated. Use the
      [getDetails()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getdetails) method instead.


    **Deprecated:**
**warning:** Use [getDetails()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getdetails)

---

### coupons
- coupons: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the coupons directly assigned to the promotion or assigned to the campaign of the promotion. 
      
      If the promotion is not based on coupons (see [isBasedOnCoupons()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncoupons)), or no coupons is assigned to the
      promotion or its campaign, an empty collection is returned.



---

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes for this extensible object.


---

### customerGroups
- customerGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the customer groups directly assigned to the promotion or assigned to the campaign of the promotion. 
      
      If the promotion is not based on customer groups (see [isBasedOnCustomerGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncustomergroups)), or no customer group is assigned to the
      promotion or its campaign, an empty collection is returned.



---

### description
- ~~description: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)~~ `(read-only)`
  - : Returns the description of the promotion.
      
      
      Method is deprecated and returns the same value as [getCalloutMsg()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcalloutmsg).


    **Deprecated:**
**warning:** Use [getCalloutMsg()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcalloutmsg)

---

### details
- details: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the detailed description of the promotion.


---

### enabled
- enabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if promotion is enabled, otherwise false.


---

### endDate
- endDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the effective end date of this instance of the promotion. If no
      explicit end date is defined for the promotion, the end date of the
      containing Campaign or AB-test is returned.



---

### exclusivity
- exclusivity: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the promotion's exclusivity specifying how the promotion can be
      combined with other promotions.
      Possible values are [EXCLUSIVITY_NO](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#exclusivity_no), [EXCLUSIVITY_CLASS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#exclusivity_class)
      and [EXCLUSIVITY_GLOBAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#exclusivity_global).



---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the reference to the promotion image.


---

### lastModified
- lastModified: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the date that this object was last modified.


---

### mutuallyExclusivePromotions
- mutuallyExclusivePromotions: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns the promotion's mutually exclusive Promotions. Mutually exclusive Promotions is a set of promotions or
      groups this promotion cannot be combined with.



---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the promotion.


---

### promotionClass
- promotionClass: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the promotion class indicating the general type of the promotion.
      Possible values are [PROMOTION_CLASS_PRODUCT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#promotion_class_product),
      [PROMOTION_CLASS_ORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#promotion_class_order), and [PROMOTION_CLASS_SHIPPING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#promotion_class_shipping).



---

### qualifierMatchMode
- qualifierMatchMode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the qualifier matching mode specified by this promotion. A
      promotion may have up to 3 qualifier conditions based on whether it is
      customer-group based, coupon based, and/or source-code based. A promotion
      may require for example that a customer belong to a certain customer
      group and also have a certain coupon in the cart in order for the
      promotion to apply. This method returns QUALIFIER\_MATCH\_MODE\_ALL if it is
      necessary that all the qualifier conditions are satisfied in order for
      this promotion to apply for a given customer. Otherwise, this method
      returns QUALIFIER\_MATCH\_MODE\_ANY indicating that at least of the
      qualifier conditions must be satisfied.
      
      
      Note: currently QUALIFIER\_MATCH\_MODE\_ALL is only supported for promotions
      assigned to campaigns, and not those assigned to AB-tests.



---

### rank
- rank: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the promotion's rank. Rank is a numeric attribute that you can specify.
      Promotions with a defined rank are calculated before promotions without a defined rank.
      If two promotions have a rank, the one with the lowest rank is calculated first.
      For example, a promotion with rank 10 is calculated before one with rank 30.



---

### refinable
- refinable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if promotion is refinable, otherwise false.


---

### sourceCodeGroups
- sourceCodeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the source code groups directly assigned to the promotion or assigned to the campaign of the promotion. 
      
      If the promotion is not based on source code groups (see [isBasedOnSourceCodes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedonsourcecodes)), or no source code group is assigned to the
      promotion or its campaign, an empty collection is returned.



---

### startDate
- startDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the effective start date of this instance of the promotion. If no
      explicit start date is defined for this instance, the start date of the
      containing Campaign or AB-test is returned.



---

### tags
- tags: [String\[\]](TopLevel.String.md) `(read-only)`
  - : Returns the promotion's tags. Tags are a way of categorizing and organizing promotions. A promotion can have many
      tags. Tags will be returned in alphabetical order.



---

## Method Details

### getCalloutMsg()
- getCalloutMsg(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the callout message of the promotion.

    **Returns:**
    - Callout message of the promotion.


---

### getCampaign()
- getCampaign(): [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md)
  - : Returns the campaign this particular instance of the promotion is defined
      in.
      
      
      Note: If this promotion is defined as part of an AB-test, then a Campaign
      object will be returned, but it is a mock implementation, and not a true
      Campaign. This behavior is required for backwards compatibility and
      should not be relied upon as it may change in future releases.


    **Returns:**
    - Campaign of the promotion.


---

### getCombinablePromotions()
- getCombinablePromotions(): [String\[\]](TopLevel.String.md)
  - : Returns the promotion's combinable promotions. Combinable promotions is a set of promotions or groups this
      promotion can be combined with.


    **Returns:**
    - The promotion's set of combinable promotions.


---

### getConditionalDescription()
- ~~getConditionalDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)~~
  - : Returns a description of the condition that must be met for this
      promotion to be applicable.
      
      
      The method and the related attribute have been deprecated. Use the
      [getDetails()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getdetails) method instead.


    **Returns:**
    - Condition promotion description.

    **Deprecated:**
**warning:** Use [getDetails()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getdetails)

---

### getCoupons()
- getCoupons(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the coupons directly assigned to the promotion or assigned to the campaign of the promotion. 
      
      If the promotion is not based on coupons (see [isBasedOnCoupons()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncoupons)), or no coupons is assigned to the
      promotion or its campaign, an empty collection is returned.


    **Returns:**
    - Coupons assigned to promotion in no particular order.


---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes for this extensible object.


---

### getCustomerGroups()
- getCustomerGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the customer groups directly assigned to the promotion or assigned to the campaign of the promotion. 
      
      If the promotion is not based on customer groups (see [isBasedOnCustomerGroups()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncustomergroups)), or no customer group is assigned to the
      promotion or its campaign, an empty collection is returned.


    **Returns:**
    - Customer groups assigned to promotion in no particular order.


---

### getDescription()
- ~~getDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)~~
  - : Returns the description of the promotion.
      
      
      Method is deprecated and returns the same value as [getCalloutMsg()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcalloutmsg).


    **Returns:**
    - Description of the promotion.

    **Deprecated:**
**warning:** Use [getCalloutMsg()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getcalloutmsg)

---

### getDetails()
- getDetails(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the detailed description of the promotion.

    **Returns:**
    - Detailed promotion description.


---

### getEndDate()
- getEndDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the effective end date of this instance of the promotion. If no
      explicit end date is defined for the promotion, the end date of the
      containing Campaign or AB-test is returned.


    **Returns:**
    - End date of the promotion, or null if no end date is defined.


---

### getExclusivity()
- getExclusivity(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the promotion's exclusivity specifying how the promotion can be
      combined with other promotions.
      Possible values are [EXCLUSIVITY_NO](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#exclusivity_no), [EXCLUSIVITY_CLASS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#exclusivity_class)
      and [EXCLUSIVITY_GLOBAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#exclusivity_global).


    **Returns:**
    - Promotion exclusivity


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique ID of the promotion.

    **Returns:**
    - ID of the promotion.


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the reference to the promotion image.

    **Returns:**
    - Image of the promotion.


---

### getLastModified()
- getLastModified(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the date that this object was last modified.

    **Returns:**
    - the date that this object was last modified.


---

### getMutuallyExclusivePromotions()
- getMutuallyExclusivePromotions(): [String\[\]](TopLevel.String.md)
  - : Returns the promotion's mutually exclusive Promotions. Mutually exclusive Promotions is a set of promotions or
      groups this promotion cannot be combined with.


    **Returns:**
    - The promotion's set of mutually exclusive Promotions.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the promotion.

    **Returns:**
    - Name of the promotion.


---

### getPromotionClass()
- getPromotionClass(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the promotion class indicating the general type of the promotion.
      Possible values are [PROMOTION_CLASS_PRODUCT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#promotion_class_product),
      [PROMOTION_CLASS_ORDER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#promotion_class_order), and [PROMOTION_CLASS_SHIPPING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#promotion_class_shipping).


    **Returns:**
    - Promotion class or null if the promotion rule has not been
              configured.



---

### getPromotionalPrice(Product)
- getPromotionalPrice(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the promotional price for the specified product. The promotional
      price is only returned if the following conditions are met:
      
      
      - this promotion is a product promotion without purchase conditions,  i.e. is of type 'Without qualifying products'.
      - this promotion's discount is Discount.TYPE\_AMOUNT,  Discount.TYPE\_PERCENTAGE, Discount.TYPE\_FIXED\_PRICE, or  Discount.TYPE\_PRICEBOOK\_PRICE.
      - specified product is one of the discounted products of the  promotion.
      - the product has a valid sales price for quantity 1.0.
      
      
      In all other cases, the method will return Money.NOT\_AVAILABLE. It is
      not required that this promotion be an active customer
      promotion.
      
      NOTE: the method might be extended in the future to support more
      promotion types.
      
      To calculate the promotional price, the method uses the current sales
      price of the product for quantity 1.0, and applies the discount
      associated with the promotion to this price. For example, if the product
      price is $14.99, and the promotion discount is 10%, the method will
      return $13.49. If the discount is $2 off, the method will return $12.99.
      If the discount is $10.00 fixed price, the method will return $10.00.


    **Parameters:**
    - product - the product to calculate the discount for

    **Returns:**
    - the price of the passed product after promotional discount is
              applied, or Money.NOT\_AVAILABLE if any of the restrictions on
              product or promotion are not met.



---

### getPromotionalPrice(Product, ProductOptionModel)
- getPromotionalPrice(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), optionModel: [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : This method follows the same logic as
      [getPromotionalPrice(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#getpromotionalpriceproduct) but prices are calculated based
      on the option values selected in the specified option model.


    **Parameters:**
    - product - the product to calculate the discount for
    - optionModel - the option model to use when calculating

    **Returns:**
    - the price of the passed product after promotional discount is
              applied, or Money.NOT\_AVAILABLE if any of the restrictions on
              product or promotion are not met.



---

### getQualifierMatchMode()
- getQualifierMatchMode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the qualifier matching mode specified by this promotion. A
      promotion may have up to 3 qualifier conditions based on whether it is
      customer-group based, coupon based, and/or source-code based. A promotion
      may require for example that a customer belong to a certain customer
      group and also have a certain coupon in the cart in order for the
      promotion to apply. This method returns QUALIFIER\_MATCH\_MODE\_ALL if it is
      necessary that all the qualifier conditions are satisfied in order for
      this promotion to apply for a given customer. Otherwise, this method
      returns QUALIFIER\_MATCH\_MODE\_ANY indicating that at least of the
      qualifier conditions must be satisfied.
      
      
      Note: currently QUALIFIER\_MATCH\_MODE\_ALL is only supported for promotions
      assigned to campaigns, and not those assigned to AB-tests.


    **Returns:**
    - the qualifier matching mode specified by this promotion, either
              QUALIFIER\_MATCH\_MODE\_ALL or QUALIFIER\_MATCH\_MODE\_ANY.



---

### getRank()
- getRank(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the promotion's rank. Rank is a numeric attribute that you can specify.
      Promotions with a defined rank are calculated before promotions without a defined rank.
      If two promotions have a rank, the one with the lowest rank is calculated first.
      For example, a promotion with rank 10 is calculated before one with rank 30.


    **Returns:**
    - The promotion's rank.


---

### getSourceCodeGroups()
- getSourceCodeGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the source code groups directly assigned to the promotion or assigned to the campaign of the promotion. 
      
      If the promotion is not based on source code groups (see [isBasedOnSourceCodes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedonsourcecodes)), or no source code group is assigned to the
      promotion or its campaign, an empty collection is returned.


    **Returns:**
    - Source code groups assigned to promotion in no particular order.


---

### getStartDate()
- getStartDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the effective start date of this instance of the promotion. If no
      explicit start date is defined for this instance, the start date of the
      containing Campaign or AB-test is returned.


    **Returns:**
    - Start date of the promotion, or null if no start date is defined.


---

### getTags()
- getTags(): [String\[\]](TopLevel.String.md)
  - : Returns the promotion's tags. Tags are a way of categorizing and organizing promotions. A promotion can have many
      tags. Tags will be returned in alphabetical order.


    **Returns:**
    - The promotion's set of tags.


---

### isActive()
- isActive(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if promotion is active, otherwise 'false'. 
      
      A promotion is active if its campaign is active, and the promotion
      is enabled, and it is scheduled for _now_.


    **Returns:**
    - true if promotion is active, otherwise false.


---

### isBasedOnCoupon()
- ~~isBasedOnCoupon(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Returns 'true' if the promotion is triggered by a coupon,
      false otherwise.


    **Returns:**
    - true if promotion is triggered by coupon, otherwise false.

    **Deprecated:**
**warning:** Use [isBasedOnCoupons()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md#isbasedoncoupons)

---

### isBasedOnCoupons()
- isBasedOnCoupons(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the promotion is triggered by coupons,
      false otherwise.


    **Returns:**
    - true if promotion is triggered by coupons, otherwise false.


---

### isBasedOnCustomerGroups()
- isBasedOnCustomerGroups(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the promotion is triggered by customer groups,
      false otherwise.


    **Returns:**
    - true if promotion is triggered by customer groups, otherwise false.


---

### isBasedOnSourceCodes()
- isBasedOnSourceCodes(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the promotion is triggered by source codes,
      false otherwise.


    **Returns:**
    - true if promotion is triggered by source codes, otherwise false.


---

### isEnabled()
- isEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if promotion is enabled, otherwise false.

    **Returns:**
    - true if promotion is enabled, otherwise false.


---

### isRefinable()
- isRefinable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if promotion is refinable, otherwise false.

    **Returns:**
    - true if promotion is refinable, otherwise false.


---

<!-- prettier-ignore-end -->

<!-- document id=afe2645cc118dfbe38a794514af763c5110aa0729c722603702f4881836d9e8b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.PromotionMgr.md -->

<!-- prettier-ignore-start -->
# Class PromotionMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md)

[PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) is used to access campaigns and promotion
definitions, display active or upcoming promotions in a storefront, and to
calculate and apply promotional discounts to line item containers.


To access campaign and promotion definitions, use methods
[getCampaigns()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getcampaigns), [getCampaign(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getcampaignstring),
[getPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getpromotions) and [getPromotion(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getpromotionstring).


To display active or upcoming promotions in the storefront, e.g. on product
pages, various methods are provided. [getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions) returns
a [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) with all enabled promotions scheduled for _now_.
[getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) returns a [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) with
all enabled promotions scheduled for _now_ and applicable for the
session currency, current customer and active source code.
[getUpcomingPromotions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getupcomingpromotionsnumber) returns a [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) with all
promotions that are enabled, not scheduled for _now_, but scheduled for
any time between _now_ and _now + previewTime(hours)_.


Applying promotions to line item containers is a 3-step process, and
[PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) provides methods supporting each of these steps.
Convenience methods can be used that execute all three steps at once,
or the steps can be executed individually if you need to customize
the output of the steps due to specific business rules. 


- Step 1 - calculate active customer promotions: Determine the active  promotions for the session currency, current customer, source code and redeemed coupons.
- Step 2 - calculate applicable discounts: Based on the active promotions  determined in step 1, applicable discounts are calculated.
- Step 3 - apply discounts: applicable discounts are applied to a line  item container by creating price adjustment line items.



The simpliest way to execute steps 1-3 is to use method
[applyDiscounts(LineItemCtnr)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#applydiscountslineitemctnr). The method identifies all active
customer promotions, calculates and applies applicable discounts.


Due to specific business rules it might be necessary to manipulate
the set of applicable discounts calculated by the promotion engine
before applying them to the line item container. To implement such a scenario,
you want to use method [getDiscounts(LineItemCtnr)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr), which
identifies all active customer promotions, and calculates and returns
applicable discounts in an instance of [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md). The discount
plan contains a description for all applicable discounts for the specified line
item container, and you can remove discounts from it if necessary.
The customized discount plan can then be passed on for application by
using method [applyDiscounts(DiscountPlan)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#applydiscountsdiscountplan).


Due to specific business rules it might be necessary to manipulate the
set of active customer promotions before calculating applicable discounts
from it. For example, you might want to add promotions to the
plan or remove promotions from it.
You want to use method [getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
[getActiveCustomerPromotions(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotionsboolean), which
identifies all active customer promotions and returns an instance of
[PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). You can add promotions to the promotion plan
or remove promotions from the plan. The customized promotion plan can then be
passed on to calculate applicable discounts by using method
[getDiscounts(LineItemCtnr, PromotionPlan)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr-promotionplan).



## Property Summary

| Property | Description |
| --- | --- |
| [activeCustomerPromotions](#activecustomerpromotions): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) `(read-only)` | Returns all promotions scheduled for _now_ and applicable for the  session currency, current customer, source code, or presented coupons.<br/>   The active promotions are returned in an instance of  [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). |
| [activePromotions](#activepromotions): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) `(read-only)` | Returns all promotions scheduled for _now_, and applicable for the  session currency but regardless of current customer or source code.<br/>  The active promotions are returned in an instance of [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). |
| [campaigns](#campaigns): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all campaigns of the current site in no specific order. |
| [promotions](#promotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all promotions of the current site in no specific order. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [applyDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#applydiscountsdiscountplan)([DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md)) | Applies the discounts contained in the specified discount plan  to the line item container associated with the discount  plan. |
| static [applyDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#applydiscountslineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | Identifies active promotions, calculates the applicable  discounts from these promotions and applies these discounts to the  specified line item container. |
| static [getActiveCustomerPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions)() | Returns all promotions scheduled for _now_ and applicable for the  session currency, current customer, source code, or presented coupons.<br/>   The active promotions are returned in an instance of  [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). |
| static [getActiveCustomerPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotionsboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns all promotions scheduled for _now_ and applicable for the  session currency, current customer, source code, or presented coupons. |
| static [getActiveCustomerPromotionsForCampaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotionsforcampaigncampaign-date-date)([Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md), [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Returns all promotions assigned to the passed campaign, which are active  at some point within the specified date range, and are applicable for the  current customer, source code, or presented coupons. |
| static [getActivePromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions)() | Returns all promotions scheduled for _now_, and applicable for the  session currency but regardless of current customer or source code.<br/>  The active promotions are returned in an instance of [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). |
| static [getActivePromotionsForCampaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotionsforcampaigncampaign-date-date)([Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md), [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Returns all promotions assigned to the passed campaign which are active  at some point within the specified date range. |
| static [getCampaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getcampaignstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the campaign identified by the specified ID. |
| static [getCampaigns](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getcampaigns)() | Returns all campaigns of the current site in no specific order. |
| static [getDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | Returns the discounts applicable for the current customer, active  source code and specified line item container. |
| static [getDiscounts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr-promotionplan)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)) | Returns the discounts applicable for the current customer, active  source code and specified line item container, based on the specified  promotion plan. |
| static [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getpromotionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the promotion identified by the specified ID. |
| static [getPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getpromotions)() | Returns all promotions of the current site in no specific order. |
| static [getUpcomingCustomerPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getupcomingcustomerpromotionsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all promotions currently inactive, but scheduled  for any time between _now_ and _now + previewTime(hours)_,  and which are applicable based on the current customer, source code, and  coupons in the current basket.<br/>  The parameter _previewTime_ specifies for how many hours promotions  should be previewed. |
| static [getUpcomingPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getupcomingpromotionsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all promotions currently inactive, but scheduled  for any time between _now_ and _now + previewTime(hours)_. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### activeCustomerPromotions
- activeCustomerPromotions: [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) `(read-only)`
  - : Returns all promotions scheduled for _now_ and applicable for the
      session currency, current customer, source code, or presented coupons.
      
      
      The active promotions are returned in an instance of
      [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). The promotion plan contains all
      promotions assigned to any customer group of the current customer, the
      current source code, or coupons in the current session basket.


    **See Also:**
    - [getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions)


---

### activePromotions
- activePromotions: [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) `(read-only)`
  - : Returns all promotions scheduled for _now_, and applicable for the
      session currency but regardless of current customer or source code.
      
      The active promotions are returned in an instance of [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md).


    **See Also:**
    - [getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions)


---

### campaigns
- campaigns: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all campaigns of the current site in no specific order.


---

### promotions
- promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all promotions of the current site in no specific order.


---

## Method Details

### applyDiscounts(DiscountPlan)
- static applyDiscounts(discountPlan: [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md)): void
  - : Applies the discounts contained in the specified discount plan
      to the line item container associated with the discount
      plan. 
      
      
      
      As a result of this method, the specified line item container
      contains price adjustments and/or bonus product line items for
      all discounts contained in the specified discount plan.
      The method also removes price adjustment and/or bonus product line items
      from the line item container if the specified discount plan does not
      contain the related discount.
      
      
      _Note that the method does not evaluate if the discounts in the specified
       discount plan are applicable nor that the promotions related to these
       discounts are active._


    **Parameters:**
    - discountPlan - Discount plan to apply to associated line item container

    **See Also:**
    - [getDiscounts(LineItemCtnr)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getdiscountslineitemctnr)
    - [applyDiscounts(LineItemCtnr)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#applydiscountslineitemctnr)


---

### applyDiscounts(LineItemCtnr)
- static applyDiscounts(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): void
  - : Identifies active promotions, calculates the applicable
      discounts from these promotions and applies these discounts to the
      specified line item container.
      
      
      As a result of this method, the specified line item container
      contains price adjustments and/or bonus product line items for
      all applicable discounts. The method also removes price
      adjustment and/or bonus product line items from the line item
      container if the related to promotions/discounts are no longer
      applicable.


    **Parameters:**
    - lineItemCtnr - Line item ctnr to apply promotions on


---

### getActiveCustomerPromotions()
- static getActiveCustomerPromotions(): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)
  - : Returns all promotions scheduled for _now_ and applicable for the
      session currency, current customer, source code, or presented coupons.
      
      
      The active promotions are returned in an instance of
      [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). The promotion plan contains all
      promotions assigned to any customer group of the current customer, the
      current source code, or coupons in the current session basket.


    **Returns:**
    - [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) with active customer promotions

    **See Also:**
    - [getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions)


---

### getActiveCustomerPromotions(Boolean)
- static getActiveCustomerPromotions(ignoreCouponCondition: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)
  - : Returns all promotions scheduled for _now_ and applicable for the
      session currency, current customer, source code, or presented coupons. 
      
      
      The active promotions are returned in an instance of
      [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md). The promotion plan contains all
      promotions assigned to any customer group of the current customer, the
      current source code, or coupons in the current session basket.


    **Parameters:**
    - ignoreCouponCondition - true if coupon condition will be ignored when get active promotions.

    **Returns:**
    - [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) with active customer promotions


---

### getActiveCustomerPromotionsForCampaign(Campaign, Date, Date)
- static getActiveCustomerPromotionsForCampaign(campaign: [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md), from: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), to: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)
  - : Returns all promotions assigned to the passed campaign, which are active
      at some point within the specified date range, and are applicable for the
      current customer, source code, or presented coupons. A promotion must be
      active for an actual time period within the passed date range, and not
      just a single point.
      
      
      The passed campaign and dates must not be null or an exception is thrown.
      It is valid for the from and to dates to be in the past. If an invalid
      time range is specified (i.e. from is after to), the returned
      PromotionPlan will be empty.


    **Parameters:**
    - campaign - The campaign, must not be null or an exception is thrown.
    - from - The start of the date range to consider. If null, this             signifies an open ended time period.
    - to - The end of the date range to consider. If null, this signifies             an open ended time period.

    **Returns:**
    - PromotionPlan with promotions matching all the criteria.


---

### getActivePromotions()
- static getActivePromotions(): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)
  - : Returns all promotions scheduled for _now_, and applicable for the
      session currency but regardless of current customer or source code.
      
      The active promotions are returned in an instance of [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md).


    **Returns:**
    - [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) with active promotions

    **See Also:**
    - [getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions)


---

### getActivePromotionsForCampaign(Campaign, Date, Date)
- static getActivePromotionsForCampaign(campaign: [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md), from: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), to: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)
  - : Returns all promotions assigned to the passed campaign which are active
      at some point within the specified date range. A promotion must be active
      for an actual time period within the passed date range, and not just a
      single point. A promotion must be applicable for the session currency.
      
      
      This method considers only the enabled flags and time conditions of the
      promotion and campaign. It does not consider whether the current customer
      satisfies the qualifiers of the promotion (customer group, source code,
      or coupon).
      
      
      The passed campaign and dates must not be null or an exception is thrown.
      It is valid for the from and/or to dates to be in the past. If an invalid
      time range is specified (i.e. from is after to), the returned
      PromotionPlan will be empty.


    **Parameters:**
    - campaign - The campaign. Must not be null.
    - from - The start of the date range to consider. Must not be null
    - to - The end of the date range to consider. Must not be null.

    **Returns:**
    - PromotionPlan with promotions matching all the criteria.


---

### getCampaign(String)
- static getCampaign(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md)
  - : Returns the campaign identified by the specified ID.

    **Parameters:**
    - id - Campaign ID

    **Returns:**
    - Campaign or null if not found


---

### getCampaigns()
- static getCampaigns(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all campaigns of the current site in no specific order.

    **Returns:**
    - All campaigns of current site


---

### getDiscounts(LineItemCtnr)
- static getDiscounts(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md)
  - : Returns the discounts applicable for the current customer, active
      source code and specified line item container. 
      
      
      This method identifies all active  promotions assigned to the customer
      groups of the current customer, the active source code and any coupon
      contained in the specified line item container, and calculates applicable
      discounts from these promotions.
      
      
      The applicable discounts are contained in the returned instance of
      [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md).


    **Parameters:**
    - lineItemCtnr - Line item container

    **Returns:**
    - Discount plan with applicable discounts


---

### getDiscounts(LineItemCtnr, PromotionPlan)
- static getDiscounts(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md), promotionPlan: [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)): [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md)
  - : Returns the discounts applicable for the current customer, active
      source code and specified line item container, based on the specified
      promotion plan. 
      
      
      This method calculates applicable discounts from the promotions in the
      specified promotion plan. Note that any promotion in the promotion
      plan that is inactive, or not applicable for the current customer
      or source code, is being ignored.
      
      
      The applicable discounts are contained in the returned instance of
      [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md).


    **Parameters:**
    - lineItemCtnr - Line item container
    - promotionPlan - Promotion plan with active promotions

    **Returns:**
    - Discount plan with applicable discounts


---

### getPromotion(String)
- static getPromotion(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)
  - : Returns the promotion identified by the specified ID. The same logical
      promotion may be assigned to multiple campaigns or AB-tests. In this
      case, the system returns the instance of highest rank. Some attributes of
      the returned Promotion may vary based on exactly which instance is
      returned. This method returns null if there is no promotion in the system
      with the given ID, or if a promotion with the given ID exists but it is
      not assigned to any campaign or AB-test.


    **Parameters:**
    - id - Promotion ID

    **Returns:**
    - Promotion or null if not found


---

### getPromotions()
- static getPromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all promotions of the current site in no specific order.

    **Returns:**
    - All promotions of current site


---

### getUpcomingCustomerPromotions(Number)
- static getUpcomingCustomerPromotions(previewTime: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)
  - : Returns all promotions currently inactive, but scheduled
      for any time between _now_ and _now + previewTime(hours)_,
      and which are applicable based on the current customer, source code, and
      coupons in the current basket.
      
      The parameter _previewTime_ specifies for how many hours promotions
      should be previewed.


    **Parameters:**
    - previewTime - Preview time in hours

    **Returns:**
    - PromotionPlan with active promotions

    **See Also:**
    - [getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions)


---

### getUpcomingPromotions(Number)
- static getUpcomingPromotions(previewTime: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)
  - : Returns all promotions currently inactive, but scheduled
      for any time between _now_ and _now + previewTime(hours)_. 
      
      The upcoming promotions are returned in an instance of
      [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md) and might not necessarily be applicable for
      the current customer or source code. 
      
      The parameter _previewTime_ specifies for how many hours promotions
      should be previewed.


    **Parameters:**
    - previewTime - Preview time in hours

    **Returns:**
    - PromotionPlan with active promotions

    **See Also:**
    - [getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions)


---

<!-- prettier-ignore-end -->

<!-- document id=8a936616cbac461e5e9c8ec59c0403db7720b35c7c2d970ca2d7b92fbdf3c509 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.PromotionPlan.md -->

<!-- prettier-ignore-start -->
# Class PromotionPlan

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)

PromotionPlan represents a set of [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) instances and
is used to display active or upcoming promotions on storefront pages, or to
pass it to the [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) to calculate a
[DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md) and subsequently apply discounts to a line
item container. Instances of the class are returned by the
[PromotionMgr.getActivePromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivepromotions),
[PromotionMgr.getActiveCustomerPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getactivecustomerpromotions) and
[PromotionMgr.getUpcomingPromotions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md#getupcomingpromotionsnumber).


PromotionPlan provides methods to access the promotions in the plan and to
remove promotions from the plan. All methods which return a collection of
promotions sort them by the following ordered criteria:




1. Exclusivity: GLOBAL exclusive promotions first, followed by CLASS   exclusive promotions, and NO exclusive promotions last.
2. Rank: sorted ascending
3. Promotion Class: PRODUCT promotions first, followed by ORDER promotions,   and SHIPPING promotions last.
4. Discount type: Fixed price promotions first, followed by free,   amount-off, percentage-off, and bonus product promotions last.
5. Best discount: Sorted descending. For example, 30% off comes before 20%   off.
6. ID: alphanumeric ascending.


**See Also:**
- [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md)


## Constant Summary

| Constant | Description |
| --- | --- |
| [SORT_BY_EXCLUSIVITY](#sort_by_exclusivity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Constant indicating that a collection of promotions should be sorted  first by exclusivity, then rank, promotion class, etc. |
| [SORT_BY_START_DATE](#sort_by_start_date): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Constant indicating that a collection of promotions should be sorted by  start date ascending. |

## Property Summary

| Property | Description |
| --- | --- |
| [orderPromotions](#orderpromotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all order promotions contained in this plan. |
| [productPromotions](#productpromotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all product promotions contained in this plan. |
| [promotions](#promotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all promotions contained in this plan sorted by exclusivity. |
| [shippingPromotions](#shippingpromotions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all shipping promotions contained in this plan. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getOrderPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getorderpromotions)() | Returns all order promotions contained in this plan. |
| [getPaymentCardPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getpaymentcardpromotionspaymentcard)([PaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md)) | Returns the order promotions explicitly associated to the specified  discounted payment card. |
| [getPaymentMethodPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getpaymentmethodpromotionspaymentmethod)([PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md)) | Returns the order promotions explicitly associated to the specified  discounted payment method. |
| [getProductPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotions)() | Returns all product promotions contained in this plan. |
| [getProductPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the promotions related to the specified product. |
| [getProductPromotionsForDiscountedProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsfordiscountedproductproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the product promotions for which the specified product is a  discounted (and possibly also a qualifying) product. |
| [getProductPromotionsForQualifyingProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsforqualifyingproductproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the product promotions for which the specified product is a  qualifying but NOT a discounted product. |
| [getPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getpromotions)() | Returns all promotions contained in this plan sorted by exclusivity. |
| ~~[getPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getpromotionsproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md))~~ | Returns the promotions related to the specified product. |
| [getPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getpromotionsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all promotions contained in this plan sorted according to the  specified sort order. |
| [getShippingPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getshippingpromotions)() | Returns all shipping promotions contained in this plan. |
| [getShippingPromotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getshippingpromotionsshippingmethod)([ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)) | Returns the shipping promotions related to the specified discounted  shipping method, i.e. |
| [removePromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#removepromotionpromotion)([Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)) | Remove promotion from promotion plan. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### SORT_BY_EXCLUSIVITY

- SORT_BY_EXCLUSIVITY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Constant indicating that a collection of promotions should be sorted
      first by exclusivity, then rank, promotion class, etc.  See class-level
      javadoc for details.  This is the default sort order for methods that
      return a collection of promotions.



---

### SORT_BY_START_DATE

- SORT_BY_START_DATE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Constant indicating that a collection of promotions should be sorted by
      start date ascending. If there is no explicit start date for a promotion
      the start date of its containing Campaign or AB-test is used instead.
      Promotions without a start date are sorted before promotions with a start
      date in the future and after promotions with a start date in the past. In
      case two promotion assignments have the same start date, they are sorted
      by their ID.



---

## Property Details

### orderPromotions
- orderPromotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all order promotions contained in this plan.


---

### productPromotions
- productPromotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all product promotions contained in this plan.


---

### promotions
- promotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all promotions contained in this plan sorted by exclusivity.


---

### shippingPromotions
- shippingPromotions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all shipping promotions contained in this plan.


---

## Method Details

### getOrderPromotions()
- getOrderPromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all order promotions contained in this plan.

    **Returns:**
    - The sorted collection of order promotions contained in the promotion plan.


---

### getPaymentCardPromotions(PaymentCard)
- getPaymentCardPromotions(paymentCard: [PaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the order promotions explicitly associated to the specified
      discounted payment card.
      
      
      This method is usually used to display order promotions along with
      payment card choices.


    **Parameters:**
    - paymentCard - Discounted payment card

    **Returns:**
    - The sorted collection of order promotions associated with the
              specified payment card.



---

### getPaymentMethodPromotions(PaymentMethod)
- getPaymentMethodPromotions(paymentMethod: [PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the order promotions explicitly associated to the specified
      discounted payment method.
      
      
      This method is usually used to display order promotions along with
      payment method choices.


    **Parameters:**
    - paymentMethod - Discounted payment method

    **Returns:**
    - The sorted collection of order promotions associated with the
              specified payment method.



---

### getProductPromotions()
- getProductPromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product promotions contained in this plan.

    **Returns:**
    - The sorted collection of product promotions contained in the promotion plan.


---

### getProductPromotions(Product)
- getProductPromotions(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the promotions related to the specified product. 
      
      The method returns all promotions where the product is either a
      qualifying product, or a discounted product, or both. It also returns
      promotions where the specified product is a bonus product.
      
      
      This method is usually used to display product promotions on a product
      details page.
      
      
      If a master product is passed, then this method will return promotions
      which are relevant for the master itself or at least one of its variants.


    **Parameters:**
    - product - Product associated with promotion

    **Returns:**
    - The sorted collection of promotions related to specified
              discounted product.



---

### getProductPromotionsForDiscountedProduct(Product)
- getProductPromotionsForDiscountedProduct(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the product promotions for which the specified product is a
      discounted (and possibly also a qualifying) product. It also returns
      promotions where the specified product is a bonus product.
      
      
      This method is usually used to display product promotions on a product
      details page when separate callout messages are defined depending on if
      the product is a qualifying or discounted product for the promotion.
      
      
      If a master product is passed, then this method will return promotions
      for which the master product itself or at least one of its product's
      variants is a discounted product.


    **Parameters:**
    - product - The discounted product.

    **Returns:**
    - Product promotions related to the specified discounted product.


---

### getProductPromotionsForQualifyingProduct(Product)
- getProductPromotionsForQualifyingProduct(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the product promotions for which the specified product is a
      qualifying but NOT a discounted product.
      
      
      This method is usually used to display product promotions on a product
      details page when separate callout messages are defined depending on if
      the product is a qualifying or discounted product for the promotion.
      
      
      If a master product is passed, then this method will return promotions
      for which the master product itself or at least one of its product's
      variants is a qualifying product.


    **Parameters:**
    - product - The qualifying product.

    **Returns:**
    - Product promotions related to the specified qualifying product.


---

### getPromotions()
- getPromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all promotions contained in this plan sorted by exclusivity.

    **Returns:**
    - The sorted collection of promotions contained in the promotion plan.


---

### getPromotions(Product)
- ~~getPromotions(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns the promotions related to the specified product. 
      
      The method returns all promotions where the product is either
      a qualifying product, or a discounted product, or both. It also
      returns promotions where the specified product is a bonus product.
      
      
      This method is usually used to display product promotions on a
      product details page.


    **Parameters:**
    - product - Product associated with promotion

    **Returns:**
    - The sorted collection of promotions related to the specified discounted product.

    **Deprecated:**
**warning:** Use [getProductPromotions(Product)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotionsproduct)

---

### getPromotions(Number)
- getPromotions(sortOrder: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all promotions contained in this plan sorted according to the
      specified sort order. If the passed sort order is invalid, then the
      returned promotions will be sorted by exclusivity.


    **Parameters:**
    - sortOrder - the sort order to use. Must be SORT\_BY\_EXCLUSIVITY or             SORT\_BY\_START\_DATE. If an invalid value is passed,             SORT\_BY\_EXCLUSIVITY is used.

    **Returns:**
    - The sorted collection of promotions contained in the promotion
              plan.



---

### getShippingPromotions()
- getShippingPromotions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all shipping promotions contained in this plan.

    **Returns:**
    - The sorted collection of shipping promotions contained in promotion plan.


---

### getShippingPromotions(ShippingMethod)
- getShippingPromotions(shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the shipping promotions related to the specified discounted
      shipping method, i.e. the returned promotions apply a discount on
      the specified shipping method.
      
      
      This method is usually used to display shipping promotions along with
      shipping methods.


    **Parameters:**
    - shippingMethod - Discounted shipping method

    **Returns:**
    - The sorted collection of shipping promotions with specified method as discounted method.


---

### removePromotion(Promotion)
- removePromotion(promotion: [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)): void
  - : Remove promotion from promotion plan. 
      
      Please note that this is the only way to remove promotions from the
      plan, i.e. removing promotions from the collections returned
      by methods such as [getProductPromotions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md#getproductpromotions) has no effect
      on the promotion plan.


    **Parameters:**
    - promotion - Promotion to remove from promotion plan


---

<!-- prettier-ignore-end -->

<!-- document id=7e72d141655fa521973a107c7530aa4322c055ca5ad5ac93d3f3605e0a78251d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.PropertyComparator.md -->

<!-- prettier-ignore-start -->
# Class PropertyComparator

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.PropertyComparator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.PropertyComparator.md)

This comparator can be used for the List sort() methods and for the SortSet
and SortedMap classes. The comparator can be used to make a comparison based
on a property of the contained objects. The Comparison is done based on the
natural order of the values. It is guaranteed to work for Numbers, Strings,
Dates, Money and Quantity values.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [PropertyComparator](#propertycomparatorstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the comparator from the variable length argument list. |
| [PropertyComparator](#propertycomparatorstring-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Constructs the comparator. |
| [PropertyComparator](#propertycomparatorstring-boolean-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Constructs the comparator. |

## Method Summary

| Method | Description |
| --- | --- |
| [compare](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.PropertyComparator.md#compareobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Compares its two arguments for order. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### PropertyComparator(String, String...)
- PropertyComparator(property: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), otherProperties: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the comparator from the variable length argument list. The
      parameters are property names that are to be used for the comparison.
      When comparing two objects, the comparator first compares them by the
      first property. If the two objects have equal values for the first
      property, the comparator then compares them by the second property,
      etc, until one object is determined to be less than the other or they are
      equal. Each parameter must be either a simple name like "totalSum" or can
      be a reference to a custom attribute like "custom.mytotal". Each
      parameter may also be prefixed with an optional '+' or '-' character to
      indicate that the objects should be sorted ascending or descending
      respectively by that property. If not specified for a given property then
      '+' (ascending sort) is assumed.
      
      For example: new PropertyComparator("+prop1", "-prop2", "prop3")
      constructs a Comparator which sorts by prop1 ascending, prop2 descending,
      and finally prop3 ascending.
      
      The comparator created with this constructor treats null values as
      greater than any other value.


    **Parameters:**
    - property - The property name to compare by first.
    - otherProperties - Additional property names to sort by if two             objects have the same values for the first property.


---

### PropertyComparator(String, Boolean)
- PropertyComparator(propertyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortOrder: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))
  - : Constructs the comparator. The specified parameter is the name of the
      property that is used for the comparison. The parameter must be either a
      simple name like "totalSum" or can be a reference to a custom attribute
      like "custom.mytotal".
      
      The comparator created with this constructor is setup with ascending or
      descending sort order depending on value of sortOrder and null values
      being greater than any other value.


    **Parameters:**
    - propertyName - the name of the property that is used for the             comparison.
    - sortOrder - the sort order to use where true means ascending and             false means descending.


---

### PropertyComparator(String, Boolean, Boolean)
- PropertyComparator(propertyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortOrder: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), nullGreater: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))
  - : Constructs the comparator. The specified parameter is the name of the
      property that is used for the comparison. The parameter must be either a
      simple name like "totalSum" or can be a reference to a custom attribute
      like "custom.mytotal".


    **Parameters:**
    - propertyName - the name of the property that is used for the             comparison.
    - sortOrder - the sort order to use where true means ascending and             false means descending.
    - nullGreater - true means null is greater than any other value


---

## Method Details

### compare(Object, Object)
- compare(arg1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), arg2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Compares its two arguments for order. Returns a negative integer, zero,
      or a positive integer as the first argument is less than, equal to, or
      greater than the second. By default a null value is treated always
      greater than any other value. In the constructor of a PropertyComparator
      this default behavior can be changed.


    **Parameters:**
    - arg1 - the first object to compare.
    - arg2 - the second object to compare.

    **Returns:**
    - a negative integer, zero, or a positive integer as the first
              argument is less than, equal to, or greater than the second.



---

<!-- prettier-ignore-end -->

<!-- document id=73f7a4a86ffc865fb91a14a7fcd60c9b8221d4be4218047a5a7730cabcd7b8bf url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.QName.md -->

<!-- prettier-ignore-start -->
# Class QName

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.QName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md)

QName objects are used to represent qualified names of XML 
elements and attributes. Each QName object has a local name 
of type string and a namespace URI of type string or null. 
When the namespace URI is null, this qualified name matches 
any namespace.

If the QName of an XML element is specified without identifying a 
namespace (i.e., as an unqualified identifier), the uri property 
of the associated QName will be set to the in-scope default 
namespace. If the QName of an XML attribute is 
specified without identifying a namespace, the uri property of 
the associated QName will be the empty string representing no namespace.



## Property Summary

| Property | Description |
| --- | --- |
| [localName](#localname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the local name of the QName object. |
| [uri](#uri): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Uniform Resource Identifier (URI) of the QName object. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [QName](#qname)() | Constructs a QName object where _localName_  is set to an empty String. |
| [QName](#qnameqname)([QName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md)) | Constructs a QName object that is a copy of the specified  _qname_. |
| [QName](#qnamenamespace-qname)([Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md), [QName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md)) | Creates a QName object with a uri from a Namespace object and  a localName from a QName object. |

## Method Summary

| Method | Description |
| --- | --- |
| [getLocalName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md#getlocalname)() | Returns the local name of the QName object. |
| [getUri](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md#geturi)() | Returns the Uniform Resource Identifier (URI) of the QName object. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md#tostring)() | Returns a string composed of the URI, and the local name for the QName   object, separated by "::". |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### localName
- localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the local name of the QName object.


---

### uri
- uri: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Uniform Resource Identifier (URI) of the QName object.


---

## Constructor Details

### QName()
- QName()
  - : Constructs a QName object where _localName_
      is set to an empty String.



---

### QName(QName)
- QName(qname: [QName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md))
  - : Constructs a QName object that is a copy of the specified
      _qname_. If the argument is not
      a QName object, the argument is converted to a string and assigned
      to the localName property of the new QName instance.


    **Parameters:**
    - qname - the QName from which this QName will   be constructed.


---

### QName(Namespace, QName)
- QName(uri: [Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md), localName: [QName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md))
  - : Creates a QName object with a uri from a Namespace object and
      a localName from a QName object. If either argument is not
      the expected data type, the argument is converted to a string
      and assigned to the corresponding property of the new QName object.


    **Parameters:**
    - uri - a Namespace object from which to copy the uri value.  An argument of any other type is converted to a string.
    - localName - a QName object from which to copy the  localName value. An argument of any other type is converted to a string.


---

## Method Details

### getLocalName()
- getLocalName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the local name of the QName object.

    **Returns:**
    - the local name of the QName object.


---

### getUri()
- getUri(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Uniform Resource Identifier (URI) of the QName object.

    **Returns:**
    - the Uniform Resource Identifier (URI) of the QName object.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string composed of the URI, and the local name for the QName 
      object, separated by "::". The format depends on the uri property of 
      the QName object:
      If uri == ""
            toString returns localName
      else if uri == null 
            toString returns \*::localName
      else
         toString returns uri::localNam


    **Returns:**
    - a string composed of the URI, and the local name for the QName 
      object, separated by "::".



---

<!-- prettier-ignore-end -->

<!-- document id=66df92004f479201a3e385741796d43376c89d20a0780b90589584a0873a2fdd url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.value.Quantity.md -->

<!-- prettier-ignore-start -->
# Class Quantity

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.value.Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)

Represents the quantity of an item.


## Property Summary

| Property | Description |
| --- | --- |
| [available](#available): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the instance contains settings for value and unit. |
| [decimalValue](#decimalvalue): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) `(read-only)` | Returns the quantity as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the quantity is not available. |
| [unit](#unit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the value for unit which identifies the  unit of measure for the quantity. |
| [value](#value): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the quantity value. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Quantity](#quantitynumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new quantity instance with the specified value and unit. |

## Method Summary

| Method | Description |
| --- | --- |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#addquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Add Quantity object to the current object. |
| [compareTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#comparetoquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Compares two Quantity values. |
| [divide](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#dividenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Divide Quantity object by specified divisor. |
| [equals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#equalsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Compares two decimal values whether they are equivalent. |
| [getDecimalValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#getdecimalvalue)() | Returns the quantity as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the quantity is not available. |
| [getUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#getunit)() | Returns the value for unit which identifies the  unit of measure for the quantity. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#getvalue)() | Returns the quantity value. |
| [hashCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#hashcode)() | Calculates the hash code for a decimal. |
| [isAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#isavailable)() | Identifies if the instance contains settings for value and unit. |
| [isOfSameUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#isofsameunitquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Identifies if two Quantities have the same unit. |
| [multiply](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#multiplynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Multiply Quantity object by specified factor. |
| [newQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#newquantitydecimal)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Method returns a new instance of Quantity with the same unit but  different value. |
| [round](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#roundnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Rounds the Quantity value to the number of specified decimal digits. |
| [subtract](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#subtractquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Subtract Quantity object from the current object. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#tostring)() | Returns a string representation of this quantity object. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#valueof)() | According to the ECMA spec returns the "natural" primitive value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### available
- available: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the instance contains settings for value and unit.


---

### decimalValue
- decimalValue: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md) `(read-only)`
  - : Returns the quantity as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the quantity is not available.


---

### unit
- unit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the value for unit which identifies the
      unit of measure for the quantity. Examples of unit
      are 'inches' or 'pounds'.



---

### value
- value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the quantity value.

    **See Also:**
    - [getDecimalValue()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#getdecimalvalue)


---

## Constructor Details

### Quantity(Number, String)
- Quantity(value: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), unit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new quantity instance with the specified value and unit.

    **Parameters:**
    - value - the actual quantity, must not be `null`
    - unit - the unit identifier for the quantity, must not be `null`


---

## Method Details

### add(Quantity)
- add(value: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Add Quantity object to the current object. Only objects representing the same unit can be added.

    **Parameters:**
    - value - Quantity object

    **Returns:**
    - Quantity object representing the sum of the operands


---

### compareTo(Quantity)
- compareTo(other: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Compares two Quantity values. An exception is thrown if the two Quantities values
      are of different unit. If one of the Quantity values represents the N/A value
      it is treated as 0.0.


    **Parameters:**
    - other - the other quantity to compare.

    **Returns:**
    - the comparison.


---

### divide(Number)
- divide(divisor: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Divide Quantity object by specified divisor.

    **Parameters:**
    - divisor - divisor

    **Returns:**
    - Quantity object representing division result


---

### equals(Object)
- equals(other: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Compares two decimal values whether they are equivalent.

    **Parameters:**
    - other - the object to compare against this quantity instance.

    **Returns:**
    - true if equal, false otherwise.


---

### getDecimalValue()
- getDecimalValue(): [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)
  - : Returns the quantity as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), `null` is returned when the quantity is not available.

    **Returns:**
    - the quantity as [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)


---

### getUnit()
- getUnit(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value for unit which identifies the
      unit of measure for the quantity. Examples of unit
      are 'inches' or 'pounds'.


    **Returns:**
    - the unit value.


---

### getValue()
- getValue(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the quantity value.

    **Returns:**
    - the quantity value.

    **See Also:**
    - [getDecimalValue()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md#getdecimalvalue)


---

### hashCode()
- hashCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Calculates the hash code for a decimal.

    **Returns:**
    - the hash code.


---

### isAvailable()
- isAvailable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the instance contains settings for value and unit.

    **Returns:**
    - true if the instance is initialized with value and
              unit, false if the state is 'not available'.



---

### isOfSameUnit(Quantity)
- isOfSameUnit(value: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if two Quantities have the same unit.

    **Parameters:**
    - value - the second quantity for the comparison.

    **Returns:**
    - true if both quantities have the same unit, false otherwise.


---

### multiply(Number)
- multiply(factor: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Multiply Quantity object by specified factor.

    **Parameters:**
    - factor - multiplication factor

    **Returns:**
    - Quantity object representing multiplication result


---

### newQuantity(Decimal)
- newQuantity(value: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Method returns a new instance of Quantity with the same unit but
      different value. An N/A instance is returned if value is null.


    **Parameters:**
    - value - as a decimal

    **Returns:**
    - new Quantity instance with same unit


---

### round(Number)
- round(precision: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Rounds the Quantity value to the number of specified decimal digits.

    **Parameters:**
    - precision - number of decimal digits after the decimal point

    **Returns:**
    - the new rounded Quantity value


---

### subtract(Quantity)
- subtract(value: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Subtract Quantity object from the current object. Only objects representing the same unit can be subtracted.

    **Parameters:**
    - value - Quantity object to subtract

    **Returns:**
    - Quantity object representing the result of subtraction


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this quantity object.

    **Returns:**
    - a string representation of this quantity object.


---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : According to the ECMA spec returns the "natural" primitive value. Here
      the value portion of the Quantity is returned.



---

<!-- prettier-ignore-end -->

<!-- document id=1caae9a8ae3d0e00afc32d98369f34bcde0da1d97635eaf43042839ddc43f1b5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.RandomAccessFileReader.md -->

<!-- prettier-ignore-start -->
# Class RandomAccessFileReader

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.RandomAccessFileReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md)

Instances of this class support reading from a random access file. A random
access file behaves like a large array of bytes stored in the file system.
There is a kind of cursor, or index into the implied array, called the file
pointer. Read operations read bytes starting at the file pointer and advance
the file pointer past the bytes read. The file pointer can be read by the
getPosition method and set by the setPosition method.



## Constant Summary

| Constant | Description |
| --- | --- |
| [MAX_READ_BYTES](#max_read_bytes): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10240 | The maximum number of bytes that a single call to [readBytes(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#readbytesnumber) can return == 10KB |

## Property Summary

| Property | Description |
| --- | --- |
| [position](#position): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the current offset in this file. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [RandomAccessFileReader](#randomaccessfilereaderfile)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Construct a reader for random read access to the provided file. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#close)() | Closes this random access file reader and releases any system resources  associated with the stream. |
| [getPosition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#getposition)() | Returns the current offset in this file. |
| [length](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#length)() | Returns the length of this file. |
| [readByte](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#readbyte)() | Reads a signed eight-bit value from the file starting from the current  file pointer. |
| [readBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#readbytesnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Reads up to n bytes from the file starting at the current file pointer. |
| [setPosition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#setpositionnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the file-pointer offset, measured from the beginning of this file,  at which the next read occurs. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### MAX_READ_BYTES

- MAX_READ_BYTES: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10240
  - : The maximum number of bytes that a single call to [readBytes(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#readbytesnumber) can return == 10KB


---

## Property Details

### position
- position: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the current offset in this file.


---

## Constructor Details

### RandomAccessFileReader(File)
- RandomAccessFileReader(file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md))
  - : Construct a reader for random read access to the provided file.
      
      
      To release system resources, close the reader by calling [close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#close).


    **Parameters:**
    - file - The file to be read. Must not be null.

    **Throws:**
    - IOException - If the given file object does not denote an existing              regular file


---

## Method Details

### close()
- close(): void
  - : Closes this random access file reader and releases any system resources
      associated with the stream.


    **Throws:**
    - IOException - if an I/O error occurs.


---

### getPosition()
- getPosition(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the current offset in this file.

    **Returns:**
    - the offset from the beginning of the file, in bytes, at which the
              next read occurs.


    **Throws:**
    - IOException - if an I/O error occurs.


---

### length()
- length(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the length of this file.

    **Returns:**
    - the length of this file, measured in bytes.

    **Throws:**
    - IOException - if an I/O error occurs.


---

### readByte()
- readByte(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Reads a signed eight-bit value from the file starting from the current
      file pointer. Since the byte is interpreted as signed, the value returned
      will always be between -128 and +127.


    **Returns:**
    - the next byte of this file as a signed eight-bit byte.

    **Throws:**
    - IOException - if an I/O error occurs or if this file has reached              the end.


---

### readBytes(Number)
- readBytes(numBytes: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Reads up to n bytes from the file starting at the current file pointer.
      If there are fewer than n bytes remaining in the file, then as many bytes
      as possible are read. If no bytes remain in the file, then null is
      returned.


    **Parameters:**
    - numBytes - The number of bytes to read. Must be non-negative and             smaller than [MAX_READ_BYTES](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md#max_read_bytes) or an exception             will be thrown.

    **Returns:**
    - A Bytes object representing the read bytes or null if no bytes
              were read.


    **Throws:**
    - IOException - if an I/O error occurs.
    - IllegalArgumentException - if numBytes< 0 or numBytes > MAX\_READ\_BYTES.


---

### setPosition(Number)
- setPosition(position: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the file-pointer offset, measured from the beginning of this file,
      at which the next read occurs. The offset may be set beyond the end of
      the file.


    **Parameters:**
    - position - the offset position, measured in bytes from the beginning             of the file, at which to set the file pointer

    **Throws:**
    - IOException - if position is less than 0 or if an I/O error occurs.


---

<!-- prettier-ignore-end -->

<!-- document id=d5047cf11a58e2ac30a02b48294aeab7bba16b9c4dc9a376f59f77fd2e753f35 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.RangeError.md -->

<!-- prettier-ignore-start -->
# Class RangeError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.RangeError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RangeError.md)

Represents a range error.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [RangeError](#rangeerror)() | Constructs the error. |
| [RangeError](#rangeerrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the   specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### RangeError()
- RangeError()
  - : Constructs the error.


---

### RangeError(String)
- RangeError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the 
      specified message.


    **Parameters:**
    - msg - the range error message.


---

<!-- prettier-ignore-end -->

<!-- document id=9ee66d0976bb901d8245a9665ddc71df58259830e38065d0e60c16ce77ce6795 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.Reader.md -->

<!-- prettier-ignore-start -->
# Class Reader

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md)

The class supports reading characters from a stream.


## All Known Subclasses
[FileReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileReader.md)
## Property Summary

| Property | Description |
| --- | --- |
| ~~[lines](#lines): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)~~ `(read-only)` | The method reads the whole input stream, parses it and returns a list of strings. |
| ~~[string](#string): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | The method reads the whole input stream as one string and returns it. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Reader](#readerstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a reader from a string. |
| [Reader](#readerinputstream)([InputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.InputStream.md)) | Create a reader from a stream using UTF-8 character encoding. |
| [Reader](#readerinputstream-string)([InputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.InputStream.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Create a reader from a stream using the specified character encoding. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#close)() | Closes the reader. |
| ~~[getLines](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#getlines)()~~ | The method reads the whole input stream, parses it and returns a list of strings. |
| ~~[getString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#getstring)()~~ | The method reads the whole input stream as one string and returns it. |
| [read](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#read)() | Reads a single character from the stream. |
| ~~[read](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Reads multiple characters from the stream as string. |
| [readLine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readline)() | Reads the next line. |
| [readLines](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readlines)() | The method reads the whole input stream, parses it and returns a list of strings. |
| [readN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Reads n characters from the stream as string. |
| [readString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readstring)() | The method reads the whole input stream as one string and returns it. |
| [ready](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#ready)() | Identifies if this stream is ready to be read. |
| [skip](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#skipnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Skips the specified number of characters in the stream. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### lines
- ~~lines: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)~~ `(read-only)`
  - : The method reads the whole input stream, parses it and returns a list of strings.
      
      
      Using this method on large feeds is inherently unsafe and may lead to an out-of-memory condition. Instead use
      method [readLine()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readline) and process one line at a time.


    **Deprecated:**
**warning:** Use [readLines()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readlines)

---

### string
- ~~string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : The method reads the whole input stream as one string and returns it.
      
      
      Using this method is unsafe if the length of the input stream is not known and may lead to an out-of-memory
      condition. Instead use method [readN(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnnumber).


    **Deprecated:**
**warning:** Use [readString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readstring)

---

## Constructor Details

### Reader(String)
- Reader(source: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a reader from a string.

    **Parameters:**
    - source - the source string.


---

### Reader(InputStream)
- Reader(stream: [InputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.InputStream.md))
  - : Create a reader from a stream using UTF-8 character encoding.

    **Parameters:**
    - stream - the input stream to use.


---

### Reader(InputStream, String)
- Reader(stream: [InputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.InputStream.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Create a reader from a stream using the specified character encoding.

    **Parameters:**
    - stream - the input stream to use.
    - encoding - the encoding to use.


---

## Method Details

### close()
- close(): void
  - : Closes the reader.


---

### getLines()
- ~~getLines(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)~~
  - : The method reads the whole input stream, parses it and returns a list of strings.
      
      
      Using this method on large feeds is inherently unsafe and may lead to an out-of-memory condition. Instead use
      method [readLine()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readline) and process one line at a time.


    **Returns:**
    - a list of strings

    **Deprecated:**
**warning:** Use [readLines()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readlines)

---

### getString()
- ~~getString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : The method reads the whole input stream as one string and returns it.
      
      
      Using this method is unsafe if the length of the input stream is not known and may lead to an out-of-memory
      condition. Instead use method [readN(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnnumber).


    **Returns:**
    - a string, which represents the whole content of the InputStream

    **Throws:**
    - IOException - if something went wrong while reading from the underlying stream

    **Deprecated:**
**warning:** Use [readString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readstring)

---

### read()
- read(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads a single character from the stream. The method returns null if the end of the stream is reached.

    **Returns:**
    - a single character in a string, or null if the end of the stream is reached


---

### read(Number)
- ~~read(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Reads multiple characters from the stream as string. The actual number of characters that were read can be
      determined from the length of the returned string. If the end of the stream is reached and no more characters can
      be read, the method exits with an exception.


    **Parameters:**
    - length - the number of characters to read.

    **Returns:**
    - a string whose length is controlled by the length parameter. The actual number of characters that were
              read can be determined from the length of the returned string.


    **Throws:**
    - an - exception if the stream is exhausted

    **Deprecated:**
**warning:** use [readN(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnnumber) instead which does not throw an exception if the stream is exhausted

---

### readLine()
- readLine(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the next line.

    **Returns:**
    - A String containing the contents of the line, not including any line termination characters, or null if
              the end of the stream has been reached.



---

### readLines()
- readLines(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : The method reads the whole input stream, parses it and returns a list of strings.
      
      
      Using this method on large feeds is inherently unsafe and may lead to an out-of-memory condition. Instead use
      method [readLine()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readline) and process one line at a time.


    **Returns:**
    - a list of strings


---

### readN(Number)
- readN(n: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads n characters from the stream as string. The actual number of characters that were read can be determined
      from the length of the returned string. If the end of the stream is reached and no more characters can be read,
      the method returns null.


    **Parameters:**
    - n - the number of characters to read

    **Returns:**
    - a string whose maximum length is controlled by the n parameter, or null if the end of the stream is
              reached and no more characters can be read



---

### readString()
- readString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The method reads the whole input stream as one string and returns it.
      
      
      Using this method is unsafe if the length of the input stream is not known and may lead to an out-of-memory
      condition. Instead use method [readN(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md#readnnumber).


    **Returns:**
    - a string, which represents the whole content of the InputStream

    **Throws:**
    - IOException - if something went wrong while reading from the underlying stream


---

### ready()
- ready(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this stream is ready to be read.

    **Returns:**
    - true guarantees that the stream is ready to read without waiting for input. A false
      response means that the stream may or may not block to wait for input. Note that returning
      false does not guarantee that the next read() will block.



---

### skip(Number)
- skip(n: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Skips the specified number of characters in the stream.

    **Parameters:**
    - n - the number of characters to skip.


---

<!-- prettier-ignore-end -->

<!-- document id=e89d80ffd16b41e94c99fa1e05dde7b5bce8a35e1a076ccfa73a54bf438f0fc2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.Recommendation.md -->

<!-- prettier-ignore-start -->
# Class Recommendation

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.Recommendation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md)

Represents a recommendation in Commerce Cloud Digital.


## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[RECOMMENDATION_TYPE_CROSS_SELL](#recommendation_type_cross_sell): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1~~ | Represents a cross-sell recommendation. |
| ~~[RECOMMENDATION_TYPE_OTHER](#recommendation_type_other): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3~~ | Represents a recommendation that is neither a cross-sell or an up-sell. |
| ~~[RECOMMENDATION_TYPE_UP_SELL](#recommendation_type_up_sell): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2~~ | Represents an up-sell recommendation. |

## Property Summary

| Property | Description |
| --- | --- |
| [calloutMsg](#calloutmsg): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the recommendation's callout message in the current locale. |
| [catalog](#catalog): [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md) `(read-only)` | Return the catalog containing the recommendation. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the recommendation's image. |
| [longDescription](#longdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the recommendation's long description in the current locale. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the recommended item in the current locale. |
| [recommendationType](#recommendationtype): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the type of the recommendation. |
| [recommendedItem](#recommendeditem): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Return a reference to the recommended item. |
| [recommendedItemID](#recommendeditemid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the ID of the recommended item. |
| [shortDescription](#shortdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the recommendation's short description in the current locale. |
| [sourceItem](#sourceitem): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Return a reference to the source item. |
| [sourceItemID](#sourceitemid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the ID of the recommendation source item. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCalloutMsg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getcalloutmsg)() | Returns the recommendation's callout message in the current locale. |
| [getCatalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getcatalog)() | Return the catalog containing the recommendation. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getimage)() | Returns the recommendation's image. |
| [getLongDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getlongdescription)() | Returns the recommendation's long description in the current locale. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getname)() | Returns the name of the recommended item in the current locale. |
| [getRecommendationType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getrecommendationtype)() | Returns the type of the recommendation. |
| [getRecommendedItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getrecommendeditem)() | Return a reference to the recommended item. |
| [getRecommendedItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getrecommendeditemid)() | Return the ID of the recommended item. |
| [getShortDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getshortdescription)() | Returns the recommendation's short description in the current locale. |
| [getSourceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getsourceitem)() | Return a reference to the source item. |
| [getSourceItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md#getsourceitemid)() | Return the ID of the recommendation source item. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### RECOMMENDATION_TYPE_CROSS_SELL

- ~~RECOMMENDATION_TYPE_CROSS_SELL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1~~
  - : Represents a cross-sell recommendation.

    **Deprecated:**
**warning:** Use the integer value instead.  The recommendation types
and their meanings are now configurable in the Business Manager.

---

### RECOMMENDATION_TYPE_OTHER

- ~~RECOMMENDATION_TYPE_OTHER: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3~~
  - : Represents a recommendation that is neither a cross-sell or an up-sell.

    **Deprecated:**
**warning:** Use the integer value instead.  The recommendation types
and their meanings are now configurable in the Business Manager.

---

### RECOMMENDATION_TYPE_UP_SELL

- ~~RECOMMENDATION_TYPE_UP_SELL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2~~
  - : Represents an up-sell recommendation.

    **Deprecated:**
**warning:** Use the integer value instead.  The recommendation types
and their meanings are now configurable in the Business Manager.

---

## Property Details

### calloutMsg
- calloutMsg: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the recommendation's callout message in the current locale.


---

### catalog
- catalog: [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md) `(read-only)`
  - : Return the catalog containing the recommendation.


---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the recommendation's image.


---

### longDescription
- longDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the recommendation's long description in the current locale.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the recommended item in the current locale.


---

### recommendationType
- recommendationType: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the type of the recommendation.


---

### recommendedItem
- recommendedItem: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Return a reference to the recommended item.  This will always be an
      object of type `dw.catalog.Product` since this is the only
      currently supported recommendation target type.



---

### recommendedItemID
- recommendedItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the ID of the recommended item.  This will always be a product
      ID since this is the only currently supported recommendation target
      type.



---

### shortDescription
- shortDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the recommendation's short description in the current locale.


---

### sourceItem
- sourceItem: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Return a reference to the source item.  This will be an object of type
      `dw.catalog.Product` or `dw.catalog.Category.`



---

### sourceItemID
- sourceItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the ID of the recommendation source item.  This will either be a
      product ID or category name.



---

## Method Details

### getCalloutMsg()
- getCalloutMsg(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the recommendation's callout message in the current locale.

    **Returns:**
    - the recommendation's callout message in the current locale, or
              null if it wasn't found.



---

### getCatalog()
- getCatalog(): [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)
  - : Return the catalog containing the recommendation.

    **Returns:**
    - the catalog containing the recommendation.


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the recommendation's image.

    **Returns:**
    - the recommendation's image.


---

### getLongDescription()
- getLongDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the recommendation's long description in the current locale.

    **Returns:**
    - The recommendation's long description in the current locale, or
              null if it wasn't found.



---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the recommended item in the current locale.

    **Returns:**
    - The name of the recommended item for the current locale, or null
              if it wasn't found.



---

### getRecommendationType()
- getRecommendationType(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the type of the recommendation.

    **Returns:**
    - the type of the recommendation expressed as an integer.


---

### getRecommendedItem()
- getRecommendedItem(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Return a reference to the recommended item.  This will always be an
      object of type `dw.catalog.Product` since this is the only
      currently supported recommendation target type.


    **Returns:**
    - the recommended item, possibly null if the item does not exist.


---

### getRecommendedItemID()
- getRecommendedItemID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the ID of the recommended item.  This will always be a product
      ID since this is the only currently supported recommendation target
      type.


    **Returns:**
    - the recommended item ID.


---

### getShortDescription()
- getShortDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the recommendation's short description in the current locale.

    **Returns:**
    - the recommendations's short description in the current locale, or
              null if it wasn't found.



---

### getSourceItem()
- getSourceItem(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Return a reference to the source item.  This will be an object of type
      `dw.catalog.Product` or `dw.catalog.Category.`


    **Returns:**
    - the source item.


---

### getSourceItemID()
- getSourceItemID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the ID of the recommendation source item.  This will either be a
      product ID or category name.


    **Returns:**
    - the source item ID.


---

<!-- prettier-ignore-end -->

<!-- document id=d2001b5a8bf71753c93fc8fca104a67158b62a4357bb0d7618b1282b7cfc2696 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.ReferenceError.md -->

<!-- prettier-ignore-start -->
# Class ReferenceError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.ReferenceError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ReferenceError.md)

Represents a reference error.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ReferenceError](#referenceerror)() | Constructs the error. |
| [ReferenceError](#referenceerrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the   specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### ReferenceError()
- ReferenceError()
  - : Constructs the error.


---

### ReferenceError(String)
- ReferenceError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the 
      specified message.


    **Parameters:**
    - msg - the reference error message.


---

<!-- prettier-ignore-end -->

<!-- document id=393efc769556cad54c3f9110bfa780b02c65ca314fc1ae7923b819d4fce17c38 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.RegExp.md -->

<!-- prettier-ignore-start -->
# Class RegExp

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)

The RegExp object is a static object that generates instances of a regular
expression for pattern matching and monitors all regular expressions in the
current window or frame. Consult ECMA standards for the format of the pattern
strings supported by these regular expressions.



## Property Summary

| Property | Description |
| --- | --- |
| [global](#global): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | If the regular expression instance has the _g_ modifier, then  this property is set to true. |
| [ignoreCase](#ignorecase): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | If the regular expression instance has the _i_ modifier, then  this property is set to true. |
| [lastIndex](#lastindex): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | This is the zero-based index value of the character within the  String where the next search for the pattern begins. |
| [multiline](#multiline): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | If a search extends across multiple lines of test, the _multiline_  property is set to true. |
| [source](#source): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | A String version of the characters used to create the regular  expression. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [RegExp](#regexpstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the regular expression using the specified  pattern. |
| [RegExp](#regexpstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the regular expression using the specified  pattern and attributes. |

## Method Summary

| Method | Description |
| --- | --- |
| [exec](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md#execstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Performs a search through the specified parameter for the  current regular expression and returns an array of match  information if successful. |
| [test](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md#teststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns true if there is a match of the regular expression anywhere in the  specified parameter. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### global
- global: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : If the regular expression instance has the _g_ modifier, then
      this property is set to true.



---

### ignoreCase
- ignoreCase: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : If the regular expression instance has the _i_ modifier, then
      this property is set to true.



---

### lastIndex
- lastIndex: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : This is the zero-based index value of the character within the
      String where the next search for the pattern begins. In a new
      search, the value is zero.



---

### multiline
- multiline: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : If a search extends across multiple lines of test, the _multiline_
      property is set to true.



---

### source
- source: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : A String version of the characters used to create the regular
      expression. The value does not include the forward slash delimiters that
      surround the expression.



---

## Constructor Details

### RegExp(String)
- RegExp(pattern: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the regular expression using the specified
      pattern.


    **Parameters:**
    - pattern - the regular expression pattern to use.


---

### RegExp(String, String)
- RegExp(pattern: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attributes: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the regular expression using the specified
      pattern and attributes. See the class documentation for more information
      on the pattern and attributes.


    **Parameters:**
    - pattern - the regular expression pattern to use.
    - attributes - one or more attributes that control  how the regular expression is executed.


---

## Method Details

### exec(String)
- exec(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Performs a search through the specified parameter for the
      current regular expression and returns an array of match
      information if successful. Returns null if the search produces
      no results.


    **Parameters:**
    - string - the String to apply the regular expression.

    **Returns:**
    - an array of match information if successful, null otherwise.


---

### test(String)
- test(string: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if there is a match of the regular expression anywhere in the
      specified parameter. No additional information is
      available about the results of the search.


    **Parameters:**
    - string - the String to apply the regular expression.

    **Returns:**
    - true if there is a match of the regular expression anywhere in the
      specified parameter, false otherwise.



---

<!-- prettier-ignore-end -->

<!-- document id=023b2aa1c2f942b32b2a2f1fcf257d594c5bee64765cf44c5c38921138cb9dd2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.Region.md -->

<!-- prettier-ignore-start -->
# Class Region

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)

This class represents a region which serves as container of components.
Using the [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings)
a region can be rendered.


**See Also:**
- [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)
- [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)
- [PageMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md)


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the id of this region. |
| [size](#size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of components that would be rendered by this region  when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings). |
| [visibleComponents](#visiblecomponents): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the components that would be rendered by this region  when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md#getid)() | Returns the id of this region. |
| [getSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md#getsize)() | Returns the number of components that would be rendered by this region  when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings). |
| [getVisibleComponents](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md#getvisiblecomponents)() | Returns the components that would be rendered by this region  when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the id of this region.


---

### size
- size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of components that would be rendered by this region
      when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings).
      
      
      Due to its time and customer group depending nature this call should NOT happen in a pagecached context
      outside of the processing induced by the above mentioned render methods.



---

### visibleComponents
- visibleComponents: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the components that would be rendered by this region
      when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings).
      
      
      As visibility is driven by the merchant configured dynamic visibility rules, e.g. scheduling and custom segmentation, this
      call should NOT happen in a pagecached context outside of the processing induced by the above mentioned render methods.



---

## Method Details

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the id of this region.

    **Returns:**
    - the region id


---

### getSize()
- getSize(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of components that would be rendered by this region
      when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings).
      
      
      Due to its time and customer group depending nature this call should NOT happen in a pagecached context
      outside of the processing induced by the above mentioned render methods.


    **Returns:**
    - the number of visible (i.e. renderable or serializable) components in this region


---

### getVisibleComponents()
- getVisibleComponents(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the components that would be rendered by this region
      when calling [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion) or [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings).
      
      
      As visibility is driven by the merchant configured dynamic visibility rules, e.g. scheduling and custom segmentation, this
      call should NOT happen in a pagecached context outside of the processing induced by the above mentioned render methods.


    **Returns:**
    - the visible (i.e. renderable or serializable) components in this region


---

<!-- prettier-ignore-end -->

<!-- document id=5481378c3dd366cdb0b8b84e6cf33ce38a40a263c0e2c7662105f08c9c6b4ff3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.RegionRenderSettings.md -->

<!-- prettier-ignore-start -->
# Class RegionRenderSettings

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.experience.RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)

A config that drives how the region is rendered. One can basically decide which kind of tag is used as wrapper
element (e.g. `<div>...</div>`) and which attributes are to be placed into this wrapper
element (e.g. `class="foo bar"`).


If no attributes are provided for the region render settings then the system default ones will apply. Also if no tag
name is provided then the system default one will apply.

- tag\_name : div
- attributes : {"class":"experience-region experience-\[REGION\_ID\]"}

Furthermore the render settings for components in this region can be specified - in case nothing is set per component
then the default component render setting will be applied during rendering. If also no default component render
setting is provided then the system default one will apply (see [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)).


**See Also:**
- [PageMgr.renderRegion(Region)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion)
- [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings)


## Property Summary

| Property | Description |
| --- | --- |
| [attributes](#attributes): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#setattributesobject). |
| [defaultComponentRenderSettings](#defaultcomponentrendersettings): [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md) | Returns the default component render settings. |
| [tagName](#tagname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the tag name of the region wrapper element. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [RegionRenderSettings](#regionrendersettings)() | Creates region render settings which can then be configured further. |

## Method Summary

| Method | Description |
| --- | --- |
| [getAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#getattributes)() | Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#setattributesobject). |
| [getComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#getcomponentrendersettingscomponent)([Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)) | Returns the component render settings for the given component. |
| [getDefaultComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#getdefaultcomponentrendersettings)() | Returns the default component render settings. |
| [getTagName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#gettagname)() | Returns the tag name of the region wrapper element. |
| [setAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#setattributesobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the to be configured <String,String> attributes of the wrapper element. |
| [setComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#setcomponentrendersettingscomponent-componentrendersettings)([Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md), [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)) | Sets the component render settings for the given component. |
| [setDefaultComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#setdefaultcomponentrendersettingscomponentrendersettings)([ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)) | Sets the default component render settings. |
| [setTagName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#settagnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the tag name of the region wrapper element. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### attributes
- attributes: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#setattributesobject).


---

### defaultComponentRenderSettings
- defaultComponentRenderSettings: [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)
  - : Returns the default component render settings. These will be used during rendering of the components contained in
      the region in case no dedicated component render settings were provided per component. If also no default is
      supplied then the system default will be used during rendering.



---

### tagName
- tagName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tag name of the region wrapper element. Defaults to 'div'.


---

## Constructor Details

### RegionRenderSettings()
- RegionRenderSettings()
  - : Creates region render settings which can then be configured further. They are to be used for
      [PageMgr.renderRegion(Region, RegionRenderSettings)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderregionregion-regionrendersettings) calls.


    **See Also:**
    - [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)


---

## Method Details

### getAttributes()
- getAttributes(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the configured attributes of the wrapper element as set by [setAttributes(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md#setattributesobject).

    **Returns:**
    - the configured attributes of the wrapper element


---

### getComponentRenderSettings(Component)
- getComponentRenderSettings(component: [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)): [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)
  - : Returns the component render settings for the given component. In case no explicitly specified settings are found
      for this component then the default one will be provided.


    **Parameters:**
    - component - the component to retrieve the render settings for

    **Returns:**
    - the component render settings or default component render settings if none were found for the given
              component



---

### getDefaultComponentRenderSettings()
- getDefaultComponentRenderSettings(): [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)
  - : Returns the default component render settings. These will be used during rendering of the components contained in
      the region in case no dedicated component render settings were provided per component. If also no default is
      supplied then the system default will be used during rendering.


    **Returns:**
    - the default component render settings


---

### getTagName()
- getTagName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tag name of the region wrapper element. Defaults to 'div'.

    **Returns:**
    - the tag name of the region wrapper element


---

### setAttributes(Object)
- setAttributes(attributes: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)
  - : Sets the to be configured <String,String> attributes of the wrapper element. Set to `null` in case you
      want to system defaults to be applied.


    **Parameters:**
    - attributes - the to be configured attributes of the wrapper element

    **Returns:**
    - this


---

### setComponentRenderSettings(Component, ComponentRenderSettings)
- setComponentRenderSettings(component: [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md), componentRenderSettings: [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)): [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)
  - : Sets the component render settings for the given component.

    **Parameters:**
    - component - the component to set the render settings for
    - componentRenderSettings - the desired render settings

    **Returns:**
    - this


---

### setDefaultComponentRenderSettings(ComponentRenderSettings)
- setDefaultComponentRenderSettings(defaultComponentRenderSettings: [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)): [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)
  - : Sets the default component render settings. These will be used during rendering of the components contained in
      the region in case no dedicated component render settings were provided per component.


    **Parameters:**
    - defaultComponentRenderSettings - the default component render settings

    **Returns:**
    - this


---

### setTagName(String)
- setTagName(tagName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)
  - : Sets the tag name of the region wrapper element. Must not be empty.

    **Parameters:**
    - tagName - the tag name of the region wrapper element

    **Returns:**
    - this


---

<!-- prettier-ignore-end -->

<!-- document id=08843065fdf08b1bee3e1aa7347355642a42c06de1f8c99ba5c8e0f7af172283 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.RemoteInclude.md -->

<!-- prettier-ignore-start -->
# Class RemoteInclude

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md)

The class represents a remote include value that can be assigned to JSON Object properties.


**Important notes:**

- Authentication and authorization checks are performed only for the top  level request, but NOT for remote include requests.
- The `RestResponseMgr`method `createScapiRemoteInclude()`allows only SCAPI URLs.
- The `RestResponseMgr`method `createStorefrontControllerRemoteInclude()`allows only Controller URLs.
- Correct rendering of RemoteInclude-containing objects is only performed  when processed by `dw.system.RESTSuccessResponse.render()`method. Please check the provided examples.





**Example 1. Specify remote include properties.**


```
function specifyRemoteIncludeProperties() {
   var includeValue0 = dw.system.RESTResponseMgr.createScapiRemoteInclude("custom", "sample", "v1", "resource/path/0", dw.web.URLParameter("siteId", "TestWapi"));
   var includeValue1 = dw.system.RESTResponseMgr.createScapiRemoteInclude("custom", "sample", "v1", "resource/path/1", dw.web.URLParameter("siteId", "TestWapi"));
   var greeting = { "hello": "world", "includeProperty0": includeValue0, "includeProperty1": includeValue1 };

   dw.system.RESTResponseMgr.createSuccess(greeting).render();
}
```





**Example 2. Specify array of remote include properties.**


```
function specifyArrayOfRemoteIncludes() {
  var includeValue0 = dw.system.RESTResponseMgr.createScapiRemoteInclude("custom", "sample", "v1", "resource/path/0", dw.web.URLParameter("siteId", "TestWapi"));
  var includeValue1 = dw.system.RESTResponseMgr.createScapiRemoteInclude("custom", "sample", "v1", "resource/path/1", dw.web.URLParameter("siteId", "TestWapi"));
  var greeting = { "hello": "world", "includeArray": [includeValue0, includeValue1] };

  dw.system.RESTResponseMgr.createSuccess(greeting).render();
}
```





**Example 3. Storefront controller remote include.**


```
function storefrontRemoteInclude()
{
    let remoteInclude = dw.system.RESTResponseMgr.createStorefrontControllerRemoteInclude(new URLAction("Category-Show", "Sites-MyShop-Site", dw.web.URLParameter("cid", "root")));
    let json = {
        status: "JSONOK",
        include: remoteInclude
    };
    dw.system.RESTResponseMgr.createSuccess(json).render();
}
```





**Error handling:**

**SCAPI:**


- In case of 404 response received on included resource, an empty JSON object '{}' will be supplied in final JSON.
- In case of 201..299, 3xx, 4xx (excluding 404), 5xx response from included resource, final response status will be 500 'Internal Server Error'

**Controllers:**


- In case of any non 200 response from the included resource an empty string will be included.
- Note: In case your response format is JSON be aware that this can result in invalid JSON.



## Property Summary

| Property | Description |
| --- | --- |
| [url](#url): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the URL string value specified for the current instance. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getUrl](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md#geturl)() | Returns the URL string value specified for the current instance. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md#tostring)() | Returns the URL string value specified for the current instance, same as  [getUrl()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md#geturl). |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md#valueof)() | Returns the URL string value specified for the current instance, same as  [getUrl()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md#geturl). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### url
- url: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the URL string value specified for the current instance.


---

## Method Details

### getUrl()
- getUrl(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the URL string value specified for the current instance.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the URL string value specified for the current instance, same as
      [getUrl()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md#geturl).



---

### valueOf()
- valueOf(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the URL string value specified for the current instance, same as
      [getUrl()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md#geturl).



---

<!-- prettier-ignore-end -->

<!-- document id=ce3ba9d0c52b1dcd068774f3de5fad4ddc57be1a44695f3fd8002f6af1f040b7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Request.md -->

<!-- prettier-ignore-start -->
# Class Request

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md)

Represents a request in Commerce Cloud Digital. Each pipeline dictionary contains a CurrentRequest object, which is of
type dw.system.Request. Most requests are HTTP requests, so you can use this object to get information about the HTTP
request, such as the HTTP headers. You can also get a list of cookies, if any, associated with the request. If the
request is issued from a job, the request is not an HTTP request, so HTTP-related methods return null.



## Property Summary

| Property | Description |
| --- | --- |
| [SCAPI](#scapi): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether the request originated in SCAPI. |
| [SCAPIPathParameters](#scapipathparameters): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns a map containing all path parameters of current SCAPI request in the following way:  <ul>  <li>keys: path parameter names from path pattern</li>  <li>values: corresponding path parameter values from current request</li>  </ul>   Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. |
| [SCAPIPathPattern](#scapipathpattern): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the SCAPI path pattern in the following way:   <ul>  <li>The first three segments `/api-family/api-name/version` with concrete values.</li>  <li>The /organizations part with the path parameter name `organizationId` in curly brackets.</li>  <li>The actual resource path additional path parameter names in curly brackets.</li>  </ul>   Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. |
| [clientId](#clientid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the client id of the current SCAPI or OCAPI request. |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns all of the custom attributes associated with the request. |
| [geolocation](#geolocation): [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) | Returns the physical location for the current request, if available. |
| [httpCookies](#httpcookies): [Cookies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookies.md) `(read-only)` | Returns the Cookies object, which can be used to read cookies sent by the client. |
| [httpHeaders](#httpheaders): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns a Map containing all HTTP header values. |
| [httpHost](#httphost): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the host name or null if there is no host name. |
| [httpLocale](#httplocale): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the locale or null if there is no associated locale. |
| [httpMethod](#httpmethod): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT. |
| [httpParameterMap](#httpparametermap): [HttpParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md) `(read-only)` | Returns the parameter map that contains the HTTP parameters for the current request. |
| [httpParameters](#httpparameters): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns a Map containing the raw HTTP parameters sent to the server. |
| [httpPath](#httppath): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the path. |
| [httpProtocol](#httpprotocol): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the HTTP protocol used for this request. |
| [httpQueryString](#httpquerystring): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the query string or null if there is no query string. |
| [httpReferer](#httpreferer): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the referer or null if there is no referer. |
| [httpRemoteAddress](#httpremoteaddress): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the remote address or null if no remote address is found. |
| ~~[httpRequest](#httprequest): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Identifies if this request is an HTTP request. |
| [httpSecure](#httpsecure): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether the HTTP communication is secure, which basically means that the communication happens via https. |
| [httpURL](#httpurl): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)` | Returns the complete URL of the request which was received at the server. |
| [httpUserAgent](#httpuseragent): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the HTTP user agent or null if there is no user agent. |
| [includeRequest](#includerequest): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the request represents a request for a remote include, false if it is a top-level request. |
| [locale](#locale): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the locale of the current request. |
| [ocapiVersion](#ocapiversion): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the OCAPI version of the current request. |
| [pageMetaData](#pagemetadata): [PageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md) `(read-only)` | Returns the page meta data that are associated with the current request. |
| [requestID](#requestid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique identifier of the current request. |
| [session](#session): [Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md) `(read-only)` | Returns the session associated with this request. |
| [triggeredForm](#triggeredform): [Form](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md) `(read-only)` | Returns the form that was submitted by the client if the request represents a form submission. |
| [triggeredFormAction](#triggeredformaction): [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md) `(read-only)` | Returns the form action that was triggered by the client if the request represents a form submission. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| ~~[addHttpCookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#addhttpcookiecookie)([Cookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md))~~ | Adds the specified cookie to the outgoing response. |
| [getClientId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getclientid)() | Returns the client id of the current SCAPI or OCAPI request. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getcustom)() | Returns all of the custom attributes associated with the request. |
| [getGeolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getgeolocation)() | Returns the physical location for the current request, if available. |
| [getHttpCookies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpcookies)() | Returns the Cookies object, which can be used to read cookies sent by the client. |
| [getHttpHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpheaders)() | Returns a Map containing all HTTP header values. |
| [getHttpHost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttphost)() | Returns the host name or null if there is no host name. |
| [getHttpLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttplocale)() | Returns the locale or null if there is no associated locale. |
| [getHttpMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpmethod)() | Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT. |
| [getHttpParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpparametermap)() | Returns the parameter map that contains the HTTP parameters for the current request. |
| [getHttpParameters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpparameters)() | Returns a Map containing the raw HTTP parameters sent to the server. |
| [getHttpPath](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttppath)() | Returns the path. |
| [getHttpProtocol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpprotocol)() | Returns the HTTP protocol used for this request. |
| [getHttpQueryString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpquerystring)() | Returns the query string or null if there is no query string. |
| [getHttpReferer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpreferer)() | Returns the referer or null if there is no referer. |
| [getHttpRemoteAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpremoteaddress)() | Returns the remote address or null if no remote address is found. |
| [getHttpURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpurl)() | Returns the complete URL of the request which was received at the server. |
| [getHttpUserAgent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttpuseragent)() | Returns the HTTP user agent or null if there is no user agent. |
| [getLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getlocale)() | Returns the locale of the current request. |
| [getOcapiVersion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getocapiversion)() | Returns the OCAPI version of the current request. |
| [getPageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getpagemetadata)() | Returns the page meta data that are associated with the current request. |
| [getRequestID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getrequestid)() | Returns the unique identifier of the current request. |
| [getSCAPIPathParameters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getscapipathparameters)() | Returns a map containing all path parameters of current SCAPI request in the following way:  <ul>  <li>keys: path parameter names from path pattern</li>  <li>values: corresponding path parameter values from current request</li>  </ul>   Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. |
| [getSCAPIPathPattern](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getscapipathpattern)() | Returns the SCAPI path pattern in the following way:   <ul>  <li>The first three segments `/api-family/api-name/version` with concrete values.</li>  <li>The /organizations part with the path parameter name `organizationId` in curly brackets.</li>  <li>The actual resource path additional path parameter names in curly brackets.</li>  </ul>   Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. |
| [getSession](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getsession)() | Returns the session associated with this request. |
| [getTriggeredForm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gettriggeredform)() | Returns the form that was submitted by the client if the request represents a form submission. |
| [getTriggeredFormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gettriggeredformaction)() | Returns the form action that was triggered by the client if the request represents a form submission. |
| ~~[isHttpRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#ishttprequest)()~~ | Identifies if this request is an HTTP request. |
| [isHttpSecure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#ishttpsecure)() | Returns whether the HTTP communication is secure, which basically means that the communication happens via https. |
| [isIncludeRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isincluderequest)() | Returns true if the request represents a request for a remote include, false if it is a top-level request. |
| [isSCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi)() | Returns whether the request originated in SCAPI. |
| [setGeolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#setgeolocationgeolocation)([Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)) | Sets the physical location for the current request and remembers the new  value for the duration of the user session. |
| [setLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#setlocalestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the given locale for the request. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### SCAPI
- SCAPI: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether the request originated in SCAPI.


---

### SCAPIPathParameters
- SCAPIPathParameters: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns a map containing all path parameters of current SCAPI request in the following way:
      
      - keys: path parameter names from path pattern
      - values: corresponding path parameter values from current request
      
      
      Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. if the request is not a SCAPI request.
      
      
      
      For example:
      
      - Current request: `/product/shopper-products/v1/organizations/sfcc_org/products/apple-ipod-shuffle`
      - Path pattern: `/product/shopper-products/v1/organizations/{organizationId}/products/{id}`
      - Result: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)with 2 key:value pairs: `organizationId:sfcc_org`and `id:apple-ipod-shuffle`.



---

### SCAPIPathPattern
- SCAPIPathPattern: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the SCAPI path pattern in the following way:
      
      
      - The first three segments `/api-family/api-name/version`with concrete values.
      - The /organizations part with the path parameter name `organizationId`in curly brackets.
      - The actual resource path additional path parameter names in curly brackets.
      
      
      Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. if the request is not a SCAPI request.
      
      
      
      For example, in the context of a request to get a single product from shopper-products API, this method would
      return `/product/shopper-products/v1/organizations/{organizationId}/products/{id}`



---

### clientId
- clientId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the client id of the current SCAPI or OCAPI request. If the request is not a SCAPI request or not an
      OCAPI request 'null' is returned. For client ids owned by Commerce Cloud Digital an alias is returned.



---

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns all of the custom attributes associated with the request. The attributes are stored for the life time of
      the request.



---

### geolocation
- geolocation: [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)
  - : Returns the physical location for the current request, if available. The
      location is calculated based on the IP address of the request. Note, if
      the geolocation tracking feature is not enabled, this method always
      returns null.



---

### httpCookies
- httpCookies: [Cookies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookies.md) `(read-only)`
  - : Returns the Cookies object, which can be used to read cookies sent by the client. Use the method
      `Response.addHttpCookie()` to add a cookie to the outgoing response.



---

### httpHeaders
- httpHeaders: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns a Map containing all HTTP header values.


---

### httpHost
- httpHost: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the host name or null if there is no host name.


---

### httpLocale
- httpLocale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the locale or null if there is no associated locale.


---

### httpMethod
- httpMethod: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.


---

### httpParameterMap
- httpParameterMap: [HttpParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md) `(read-only)`
  - : Returns the parameter map that contains the HTTP parameters for the current request.


---

### httpParameters
- httpParameters: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns a Map containing the raw HTTP parameters sent to the server. The Map contains name/value pairs. Each name
      is a String and each value is a String array.



---

### httpPath
- httpPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the path.


---

### httpProtocol
- httpProtocol: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the HTTP protocol used for this request. Possible values are "http" or "https". If the current activity
      is not related to an HTTP request, for example, when the request is part of a job, this method returns null.



---

### httpQueryString
- httpQueryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the query string or null if there is no query string.


---

### httpReferer
- httpReferer: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the referer or null if there is no referer.


---

### httpRemoteAddress
- httpRemoteAddress: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the remote address or null if no remote address is found.


---

### httpRequest
- ~~httpRequest: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Identifies if this request is an HTTP request. The method returns true, if the current processing is related to a
      HTTP request.


    **Deprecated:**
**warning:** Effectively always returns true.

---

### httpSecure
- httpSecure: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether the HTTP communication is secure, which basically means that the communication happens via https.
      If the current activity is not related to an HTTP request the method returns false.



---

### httpURL
- httpURL: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md) `(read-only)`
  - : Returns the complete URL of the request which was received at the server.
      This URL does not include SEO optimizations.



---

### httpUserAgent
- httpUserAgent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the HTTP user agent or null if there is no user agent.


---

### includeRequest
- includeRequest: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the request represents a request for a remote include, false if it is a top-level request.


---

### locale
- locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the locale of the current request. This locale is set by the system based on the information in the URL.
      It may be different from the locale returned by [getHttpLocale()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttplocale), which is the preferred locale sent by the user agent.



---

### ocapiVersion
- ocapiVersion: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the OCAPI version of the current request. If this is not
      an OCAPI request, 'null' is returned.



---

### pageMetaData
- pageMetaData: [PageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md) `(read-only)`
  - : Returns the page meta data that are associated with the current request.


---

### requestID
- requestID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique identifier of the current request. The unique id is helpful for debugging purpose, e.g. relate
      debug messages to a particular request.



---

### session
- session: [Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md) `(read-only)`
  - : Returns the session associated with this request.


---

### triggeredForm
- triggeredForm: [Form](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md) `(read-only)`
  - : Returns the form that was submitted by the client if the request represents a form submission.


---

### triggeredFormAction
- triggeredFormAction: [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md) `(read-only)`
  - : Returns the form action that was triggered by the client if the request represents a form submission.


---

## Method Details

### addHttpCookie(Cookie)
- ~~addHttpCookie(cookie: [Cookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md)): void~~
  - : Adds the specified cookie to the outgoing response. This method can be called multiple times to set more than one
      cookie. If a cookie with the same cookie name, domain and path is set multiple times for the same response, only
      the last set cookie with this name is send to the client. This method can be used to set, update or delete
      cookies at the client. If the cookie doesn't exist at the client, it is set initially. If a cookie with the same
      name, domain and path already exists at the client, it is updated. A cookie can be deleted at the client by
      submitting a cookie with the maxAge attribute set to 0 (see `Cookie.setMaxAge()
       ` for more information).
      
      
      ```
      _Example, how a cookie can be deleted at the client:_
      
      var cookie : Cookie = new Cookie("SomeName", "Simple Value");
      
      cookie.setMaxAge(0);
      
      request.addHttpCookie(cookie);
      ```


    **Parameters:**
    - cookie - a Cookie object

    **Deprecated:**
**warning:** Use [Response.addHttpCookie(Cookie)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#addhttpcookiecookie) instead.
    **API Version:**
**note:** This method is deprecated and will be removed in the next API version.

---

### getClientId()
- getClientId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the client id of the current SCAPI or OCAPI request. If the request is not a SCAPI request or not an
      OCAPI request 'null' is returned. For client ids owned by Commerce Cloud Digital an alias is returned.


    **Returns:**
    - a client id or alias in case of an OCAPI request, otherwise null.


---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns all of the custom attributes associated with the request. The attributes are stored for the life time of
      the request.


    **Returns:**
    - all of the custom attributes associated with the request.


---

### getGeolocation()
- getGeolocation(): [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)
  - : Returns the physical location for the current request, if available. The
      location is calculated based on the IP address of the request. Note, if
      the geolocation tracking feature is not enabled, this method always
      returns null.


    **Returns:**
    - The geolocation of the current request, or null if this is not
              available.



---

### getHttpCookies()
- getHttpCookies(): [Cookies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookies.md)
  - : Returns the Cookies object, which can be used to read cookies sent by the client. Use the method
      `Response.addHttpCookie()` to add a cookie to the outgoing response.


    **Returns:**
    - Cookies object or null if this is not an HTTP request


---

### getHttpHeaders()
- getHttpHeaders(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a Map containing all HTTP header values.

    **Returns:**
    - a Map containing all HTTP header values.


---

### getHttpHost()
- getHttpHost(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the host name or null if there is no host name.

    **Returns:**
    - the host name or null if there is no host name.


---

### getHttpLocale()
- getHttpLocale(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the locale or null if there is no associated locale.

    **Returns:**
    - the locale or null.


---

### getHttpMethod()
- getHttpMethod(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.

    **Returns:**
    - the HTTP method


---

### getHttpParameterMap()
- getHttpParameterMap(): [HttpParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md)
  - : Returns the parameter map that contains the HTTP parameters for the current request.

    **Returns:**
    - the HTTP parameter map


---

### getHttpParameters()
- getHttpParameters(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a Map containing the raw HTTP parameters sent to the server. The Map contains name/value pairs. Each name
      is a String and each value is a String array.


    **Returns:**
    - a Map containing all the raw HTTP parameters send to the server.


---

### getHttpPath()
- getHttpPath(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the path.

    **Returns:**
    - the path or null.


---

### getHttpProtocol()
- getHttpProtocol(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the HTTP protocol used for this request. Possible values are "http" or "https". If the current activity
      is not related to an HTTP request, for example, when the request is part of a job, this method returns null.


    **Returns:**
    - "http", "https" or null


---

### getHttpQueryString()
- getHttpQueryString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the query string or null if there is no query string.

    **Returns:**
    - the query string or null.


---

### getHttpReferer()
- getHttpReferer(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the referer or null if there is no referer.

    **Returns:**
    - the referer or null if there is no referer.


---

### getHttpRemoteAddress()
- getHttpRemoteAddress(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the remote address or null if no remote address is found.

    **Returns:**
    - the remote address or null if no remote address is found.


---

### getHttpURL()
- getHttpURL(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the complete URL of the request which was received at the server.
      This URL does not include SEO optimizations.


    **Returns:**
    - the URL as URL object


---

### getHttpUserAgent()
- getHttpUserAgent(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the HTTP user agent or null if there is no user agent.

    **Returns:**
    - the HTTP user agent or null if there is no user agent.


---

### getLocale()
- getLocale(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the locale of the current request. This locale is set by the system based on the information in the URL.
      It may be different from the locale returned by [getHttpLocale()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#gethttplocale), which is the preferred locale sent by the user agent.


    **Returns:**
    - the locale of the current request, like 'en\_US'


---

### getOcapiVersion()
- getOcapiVersion(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the OCAPI version of the current request. If this is not
      an OCAPI request, 'null' is returned.


    **Returns:**
    - OCAPI version of the current request


---

### getPageMetaData()
- getPageMetaData(): [PageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md)
  - : Returns the page meta data that are associated with the current request.

    **Returns:**
    - the page meta data object


---

### getRequestID()
- getRequestID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique identifier of the current request. The unique id is helpful for debugging purpose, e.g. relate
      debug messages to a particular request.


    **Returns:**
    - the unique identifier of the current request.


---

### getSCAPIPathParameters()
- getSCAPIPathParameters(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns a map containing all path parameters of current SCAPI request in the following way:
      
      - keys: path parameter names from path pattern
      - values: corresponding path parameter values from current request
      
      
      Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. if the request is not a SCAPI request.
      
      
      
      For example:
      
      - Current request: `/product/shopper-products/v1/organizations/sfcc_org/products/apple-ipod-shuffle`
      - Path pattern: `/product/shopper-products/v1/organizations/{organizationId}/products/{id}`
      - Result: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)with 2 key:value pairs: `organizationId:sfcc_org`and `id:apple-ipod-shuffle`.


    **Returns:**
    - the path parameter map or null


---

### getSCAPIPathPattern()
- getSCAPIPathPattern(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the SCAPI path pattern in the following way:
      
      
      - The first three segments `/api-family/api-name/version`with concrete values.
      - The /organizations part with the path parameter name `organizationId`in curly brackets.
      - The actual resource path additional path parameter names in curly brackets.
      
      
      Returns null if [isSCAPI()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#isscapi) returns false i.e. if the request is not a SCAPI request.
      
      
      
      For example, in the context of a request to get a single product from shopper-products API, this method would
      return `/product/shopper-products/v1/organizations/{organizationId}/products/{id}`


    **Returns:**
    - the path pattern or null.


---

### getSession()
- getSession(): [Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md)
  - : Returns the session associated with this request.

    **Returns:**
    - the session associated with this request.


---

### getTriggeredForm()
- getTriggeredForm(): [Form](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md)
  - : Returns the form that was submitted by the client if the request represents a form submission.

    **Returns:**
    - the form which was triggered


---

### getTriggeredFormAction()
- getTriggeredFormAction(): [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md)
  - : Returns the form action that was triggered by the client if the request represents a form submission.

    **Returns:**
    - the action of the form that was triggered


---

### isHttpRequest()
- ~~isHttpRequest(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Identifies if this request is an HTTP request. The method returns true, if the current processing is related to a
      HTTP request.


    **Returns:**
    - true if the current processing is related to a HTTP request, false otherwise.

    **Deprecated:**
**warning:** Effectively always returns true.

---

### isHttpSecure()
- isHttpSecure(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether the HTTP communication is secure, which basically means that the communication happens via https.
      If the current activity is not related to an HTTP request the method returns false.



---

### isIncludeRequest()
- isIncludeRequest(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the request represents a request for a remote include, false if it is a top-level request.


---

### isSCAPI()
- isSCAPI(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether the request originated in SCAPI.

    **Returns:**
    - true or false.


---

### setGeolocation(Geolocation)
- setGeolocation(geoLocation: [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)): void
  - : Sets the physical location for the current request and remembers the new
      value for the duration of the user session. So any subsequent calls to
      [getGeolocation()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md#getgeolocation) will return this value


    **Parameters:**
    - geoLocation - the geolocation object to use


---

### setLocale(String)
- setLocale(localeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Sets the given locale for the request. The locale is only set if it is valid, if it is active and if it is
      allowed for the current site.


    **Parameters:**
    - localeID - the locale ID to be set, like 'en\_US'

    **Returns:**
    - true, if the locale was successfully set, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=869e54d11a62844b01bd0ad6c95cf32c034a8ee65dc76685094f59eb1b2848cb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.RequestHooks.md -->

<!-- prettier-ignore-start -->
# Class RequestHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.RequestHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md)

This class represents all script hooks that can be registered to receive notifications about storefront requests.
It contains the extension points (hook names), and the functions that are called by each extension point.
A function must be defined inside a JavaScript source and must be exported.
The script with the exported hook function must be located inside a site cartridge.
Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.



```
"hooks": "./hooks.json"
```



The hooks entry links to a json file, relative to the 'package.json' file.
This file lists all registered hooks inside the hooks property:



```
"hooks": [
     {"name": "dw.system.request.onSession", "script": "./script.js"},
     {"name": "dw.system.request.onRequest", "script": "./script.js"},
]
```



A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointOnRequest](#extensionpointonrequest): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.system.request.onRequest" | The extension point name dw.system.request.onRequest. |
| [extensionPointOnSession](#extensionpointonsession): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.system.request.onSession" | The extension point name dw.system.request.onSession. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [onRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md#onrequest)() | The function is called by extension point [extensionPointOnRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md#extensionpointonrequest). |
| [onSession](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md#onsession)() | The function is called by extension point [extensionPointOnSession](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md#extensionpointonsession). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointOnRequest

- extensionPointOnRequest: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.system.request.onRequest"
  - : The extension point name dw.system.request.onRequest.


---

### extensionPointOnSession

- extensionPointOnSession: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.system.request.onSession"
  - : The extension point name dw.system.request.onSession.


---

## Method Details

### onRequest()
- onRequest(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointOnRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md#extensionpointonrequest).
      It is called when a storefront request was received from the client.


    **Returns:**
    - 
      - Status.OK for success.
      - Status.ERROR for error.



---

### onSession()
- onSession(): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointOnSession](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md#extensionpointonsession).
      It is called when a new storefront session was started.


    **Returns:**
    - 
      - Status.OK for success.
      - Status.ERROR for error.



---

<!-- prettier-ignore-end -->

<!-- document id=7d0b8401649bfe7bd78101233faa2fb8d465500c8912e30f0c398d5b12e05f36 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.Resource.md -->

<!-- prettier-ignore-start -->
# Class Resource

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.Resource](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md)

Library class which provides methods for retrieving messages from properties
resource bundles which contain locale-specific strings. When your program
needs a locale-specific String, it loads it from the resource bundle that is
appropriate for the user's current locale. In this way, the program code is
largely independent of the user's locale.


In Commerce Cloud Digital, resources are associated with the templates of a cartridge.
These bundles consist of properties files with a common name defined in the
template/resources directory of a site cartridge. For example:


- templates/resources/message.properties
- templates/resources/message\_en.properties
- templates/resources/message\_en\_US.properties
- templates/resources/message\_de\_DE.properties


Resource bundle lookup generally follows the same rules as the Java
ResourceBundle class, where the locale used for lookup is based on the
current request. See method javadoc for additional details.


Properties resource files are assumed to use the UTF-8 character
encoding. Unicode escape sequences are also supported.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [msg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md#msgstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the message from the default properties resource bundle (base  name "message") corresponding to the specified key and the request  locale. |
| static [msg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md#msgstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the message from the default properties resource bundle (base  name "message") corresponding to the specified key and the request  locale. |
| static [msg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md#msgstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the message from the specified properties resource bundle. |
| static [msgf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md#msgfstring-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the message from the specified properties resource bundle, with  the provided arguments substituted for the message argument placeholders  (specified using the Java MessageFormat approach). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### msg(String)
- static msg(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message from the default properties resource bundle (base
      name "message") corresponding to the specified key and the request
      locale.
      
      This method is equivalent to msg(String, null).


    **Parameters:**
    - key - resource bundle message key

    **Returns:**
    - the resource bundle message or the key itself if no message is
              defined.


    **See Also:**
    - [msg(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md#msgstring-string)


---

### msg(String, String)
- static msg(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), defaultMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message from the default properties resource bundle (base
      name "message") corresponding to the specified key and the request
      locale. If no message for the key is found, returns the default message
      if it is not null, otherwise returns the key itself.
      
      This method is equivalent to msg(key, null, defaultMessage).


    **Parameters:**
    - key - resource bundle message key
    - defaultMessage - default message to return if no message             corresponding to the key is found

    **Returns:**
    - the resource bundle message or default message

    **See Also:**
    - [msg(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md#msgstring-string-string)


---

### msg(String, String, String)
- static msg(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), bundleName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), defaultMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message from the specified properties resource bundle. The
      resource bundle is located by iterating the site cartridges and looking
      for a bundle with the specified name in the cartridge template/resources
      directory. If it finds a bundle, it tries to return a message from the
      bundle using standard Java ResourceBundle logic. If a message is found in
      that cartridge's bundle, it is returned, otherwise, the next cartridge is
      examined.
      
      The method throws an exception if the key is null.


    **Parameters:**
    - key - resource bundle message key
    - bundleName - base bundle name, if null, default bundle name,             "message", is used
    - defaultMessage - default message to return if no message             corresponding to the key is found and defaultMessage is not             null

    **Returns:**
    - the resource bundle message or default message


---

### msgf(String, String, String, Object...)
- static msgf(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), bundleName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), defaultMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message from the specified properties resource bundle, with
      the provided arguments substituted for the message argument placeholders
      (specified using the Java MessageFormat approach).
      
      If null is passed for the varargs argument, this method is equivalent to
      msg(key, bundleName, defaultMessage).


    **Parameters:**
    - key - resource bundle message key
    - bundleName - base bundle name, if null, default bundle name,             "message", is used
    - defaultMessage - default message to return if no message             corresponding to the key is found and defaultMessage is not             null
    - args - optional list of arguments or a collection, which are             included into the result string

    **Returns:**
    - the resource bundle message or default message

    **See Also:**
    - [msg(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md#msgstring-string-string)


---

<!-- prettier-ignore-end -->

<!-- document id=a3f3c01866d4e73b9b3ed1d6f58991a87065ad4d4706e4a05b7380fd5c956be3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Response.md -->

<!-- prettier-ignore-start -->
# Class Response

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Response](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md)

Represents an HTTP response in Commerce Cloud Digital. An instance of this class is implicitly available within
Digital script under the variable "response". The Response object can be used to set cookies and specific HTTP
headers, for directly accessing the output stream or for sending redirects.



## Constant Summary

| Constant | Description |
| --- | --- |
| [ACCESS_CONTROL_ALLOW_CREDENTIALS](#access_control_allow_credentials): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Credentials" | An allowed header name constant for Access-Control-Allow-Credentials |
| [ACCESS_CONTROL_ALLOW_HEADERS](#access_control_allow_headers): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Headers" | An allowed header name constant for Access-Control-Allow-Headers |
| [ACCESS_CONTROL_ALLOW_METHODS](#access_control_allow_methods): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Methods" | An allowed header name constant for Access-Control-Allow-Methods |
| [ACCESS_CONTROL_ALLOW_ORIGIN](#access_control_allow_origin): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Origin" | An allowed header name constant for Access-Control-Allow-Origin |
| [ACCESS_CONTROL_EXPOSE_HEADERS](#access_control_expose_headers): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Expose-Headers" | An allowed header name constant for Access-Control-Expose-Headers |
| [ALLOW](#allow): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Allow" | An allowed header name constant for Allow |
| [CONTENT_DISPOSITION](#content_disposition): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Disposition" | An allowed header name constant for Content-Disposition |
| [CONTENT_LANGUAGE](#content_language): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Language" | An allowed header name constant for Content-Language |
| [CONTENT_LOCATION](#content_location): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Location" | An allowed header name constant for Content-Location |
| [CONTENT_MD5](#content_md5): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-MD5" | An allowed header name constant for Content-MD5 |
| [CONTENT_SECURITY_POLICY](#content_security_policy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Security-Policy" | An allowed header name constant for Content-Security-Policy. |
| [CONTENT_SECURITY_POLICY_REPORT_ONLY](#content_security_policy_report_only): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Security-Policy-Report-Only" | An allowed header name constant for Content-Security-Policy-Report-Only. |
| [CONTENT_TYPE](#content_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Type" | An allowed header name constant for Content-Type |
| [CROSS_ORIGIN_EMBEDDER_POLICY](#cross_origin_embedder_policy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Embedder-Policy" | An allowed header name constant for Cross-Origin-Embedder-Policy |
| [CROSS_ORIGIN_EMBEDDER_POLICY_REPORT_ONLY](#cross_origin_embedder_policy_report_only): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Embedder-Policy-Report-Only" | An allowed header name constant for Cross-Origin-Embedder-Policy-Report-Only. |
| [CROSS_ORIGIN_OPENER_POLICY](#cross_origin_opener_policy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Opener-Policy" | An allowed header name constant for Cross-Origin-Opener-Policy |
| [CROSS_ORIGIN_OPENER_POLICY_REPORT_ONLY](#cross_origin_opener_policy_report_only): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Opener-Policy-Report-Only" | An allowed header name constant for Cross-Origin-Opener-Policy-Report-Only. |
| [CROSS_ORIGIN_RESOURCE_POLICY](#cross_origin_resource_policy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Resource-Policy" | An allowed header name constant for Cross-Origin-Resource-Policy |
| [LINK](#link): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Link" | An allowed header name constant for Link |
| [LOCATION](#location): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Location" | An allowed header name constant for Location |
| [PERMISSIONS_POLICY](#permissions_policy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Permissions-Policy" | An allowed header name constant for Permissions-Policy |
| [PLATFORM_FOR_PRIVACY_PREFERENCES_PROJECT](#platform_for_privacy_preferences_project): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "P3P" | An allowed header name constant for Platform for Privacy Preferences Project |
| [REFERRER_POLICY](#referrer_policy): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Referrer-Policy" | An allowed header name constant for Referrer-Policy |
| [REFRESH](#refresh): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Refresh" | An allowed header name constant for Refresh |
| [RETRY_AFTER](#retry_after): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Retry-After" | An allowed header name constant for Retry-After |
| [SERVICE_WORKER_ALLOWED](#service_worker_allowed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "service-worker-allowed" | An allowed header name constant for service-worker-allowed |
| [VARY](#vary): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Vary" | An allowed header name constant for Vary |
| [X_CONTENT_TYPE_OPTIONS](#x_content_type_options): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-Content-Type-Options" | An allowed header name constant for X-Content-Type-Options |
| [X_FRAME_OPTIONS](#x_frame_options): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-FRAME-OPTIONS" | An allowed header name constant for X-FRAME-OPTIONS. |
| [X_FRAME_OPTIONS_ALLOW_FROM](#x_frame_options_allow_from): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ALLOW-FROM" | An allowed value ALLOW-FROM for X-FRAME-OPTIONS |
| [X_FRAME_OPTIONS_DENY_VALUE](#x_frame_options_deny_value): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DENY" | An allowed value DENY for X-FRAME-OPTIONS |
| [X_FRAME_OPTIONS_SAMEORIGIN_VALUE](#x_frame_options_sameorigin_value): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SAMEORIGIN" | An allowed value SAME-ORIGIN value for X-FRAME-OPTIONS |
| [X_ROBOTS_TAG](#x_robots_tag): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-Robots-Tag" | An allowed header name constant for X-Robots-Tag |
| [X_XSS_PROTECTION](#x_xss_protection): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-XSS-Protection" | An allowed header name constant for X-XSS-Protection |

## Property Summary

| Property | Description |
| --- | --- |
| [writer](#writer): [PrintWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md) `(read-only)` | Returns a print writer which can be used to print content directly to the response. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addHttpCookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#addhttpcookiecookie)([Cookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md)) | Adds the specified cookie to the outgoing response. |
| [addHttpHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#addhttpheaderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a response header with the given name and value. |
| [containsHttpHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#containshttpheaderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Checks whether the response message header has a field with the specified name. |
| [getWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#getwriter)() | Returns a print writer which can be used to print content directly to the response. |
| [redirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#redirecturl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Sends a temporary redirect response (HTTP status 302) to the client for the specified redirect location URL. |
| [redirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#redirecturl-number)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sends a redirect response with the given status to the client for the specified redirect location URL. |
| [redirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#redirecturlredirect)([URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)) | Sends a redirect response with the given status to the client for the specified redirect location URL. |
| [redirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#redirectstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sends a temporary redirect response (HTTP status 302) to the client for the specified redirect location URL. |
| [redirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#redirectstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sends a redirect response with the given status to the client for the specified redirect location URL. |
| [setBuffered](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setbufferedboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets whether the output should be buffered or streamed directly to the client. |
| [setContentType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setcontenttypestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the content type for this response. |
| [setExpires](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setexpiresdate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Convenience method for [setExpires(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setexpiresnumber) which takes a Date object. |
| [setExpires](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setexpiresnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the cache expiration time for the response. |
| [setHttpHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#sethttpheaderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a response header with the given name and value. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the HTTP response code. |
| [setVaryBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setvarybystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Marks the response as personalized with the given variant identifier. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ACCESS_CONTROL_ALLOW_CREDENTIALS

- ACCESS_CONTROL_ALLOW_CREDENTIALS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Credentials"
  - : An allowed header name constant for Access-Control-Allow-Credentials


---

### ACCESS_CONTROL_ALLOW_HEADERS

- ACCESS_CONTROL_ALLOW_HEADERS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Headers"
  - : An allowed header name constant for Access-Control-Allow-Headers


---

### ACCESS_CONTROL_ALLOW_METHODS

- ACCESS_CONTROL_ALLOW_METHODS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Methods"
  - : An allowed header name constant for Access-Control-Allow-Methods


---

### ACCESS_CONTROL_ALLOW_ORIGIN

- ACCESS_CONTROL_ALLOW_ORIGIN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Allow-Origin"
  - : An allowed header name constant for Access-Control-Allow-Origin


---

### ACCESS_CONTROL_EXPOSE_HEADERS

- ACCESS_CONTROL_EXPOSE_HEADERS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Access-Control-Expose-Headers"
  - : An allowed header name constant for Access-Control-Expose-Headers


---

### ALLOW

- ALLOW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Allow"
  - : An allowed header name constant for Allow


---

### CONTENT_DISPOSITION

- CONTENT_DISPOSITION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Disposition"
  - : An allowed header name constant for Content-Disposition


---

### CONTENT_LANGUAGE

- CONTENT_LANGUAGE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Language"
  - : An allowed header name constant for Content-Language


---

### CONTENT_LOCATION

- CONTENT_LOCATION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Location"
  - : An allowed header name constant for Content-Location


---

### CONTENT_MD5

- CONTENT_MD5: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-MD5"
  - : An allowed header name constant for Content-MD5


---

### CONTENT_SECURITY_POLICY

- CONTENT_SECURITY_POLICY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Security-Policy"
  - : An allowed header name constant for Content-Security-Policy.
      
      
      Note: The Commerce Cloud platform can override this header for tools like the Storefront Toolkit.



---

### CONTENT_SECURITY_POLICY_REPORT_ONLY

- CONTENT_SECURITY_POLICY_REPORT_ONLY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Security-Policy-Report-Only"
  - : An allowed header name constant for Content-Security-Policy-Report-Only.
      
      
      You can set this response header only for storefront requests. Report recipient can't be a B2C Commerce system.



---

### CONTENT_TYPE

- CONTENT_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Content-Type"
  - : An allowed header name constant for Content-Type


---

### CROSS_ORIGIN_EMBEDDER_POLICY

- CROSS_ORIGIN_EMBEDDER_POLICY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Embedder-Policy"
  - : An allowed header name constant for Cross-Origin-Embedder-Policy


---

### CROSS_ORIGIN_EMBEDDER_POLICY_REPORT_ONLY

- CROSS_ORIGIN_EMBEDDER_POLICY_REPORT_ONLY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Embedder-Policy-Report-Only"
  - : An allowed header name constant for Cross-Origin-Embedder-Policy-Report-Only.
      
      
      You can set this response header only for storefront requests. Report recipient can't be a B2C Commerce system.



---

### CROSS_ORIGIN_OPENER_POLICY

- CROSS_ORIGIN_OPENER_POLICY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Opener-Policy"
  - : An allowed header name constant for Cross-Origin-Opener-Policy


---

### CROSS_ORIGIN_OPENER_POLICY_REPORT_ONLY

- CROSS_ORIGIN_OPENER_POLICY_REPORT_ONLY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Opener-Policy-Report-Only"
  - : An allowed header name constant for Cross-Origin-Opener-Policy-Report-Only.
      
      
      You can set this response header only for storefront requests. Report recipient can't be a B2C Commerce system.



---

### CROSS_ORIGIN_RESOURCE_POLICY

- CROSS_ORIGIN_RESOURCE_POLICY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Cross-Origin-Resource-Policy"
  - : An allowed header name constant for Cross-Origin-Resource-Policy


---

### LINK

- LINK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Link"
  - : An allowed header name constant for Link


---

### LOCATION

- LOCATION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Location"
  - : An allowed header name constant for Location


---

### PERMISSIONS_POLICY

- PERMISSIONS_POLICY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Permissions-Policy"
  - : An allowed header name constant for Permissions-Policy


---

### PLATFORM_FOR_PRIVACY_PREFERENCES_PROJECT

- PLATFORM_FOR_PRIVACY_PREFERENCES_PROJECT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "P3P"
  - : An allowed header name constant for Platform for Privacy Preferences Project


---

### REFERRER_POLICY

- REFERRER_POLICY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Referrer-Policy"
  - : An allowed header name constant for Referrer-Policy


---

### REFRESH

- REFRESH: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Refresh"
  - : An allowed header name constant for Refresh


---

### RETRY_AFTER

- RETRY_AFTER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Retry-After"
  - : An allowed header name constant for Retry-After


---

### SERVICE_WORKER_ALLOWED

- SERVICE_WORKER_ALLOWED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "service-worker-allowed"
  - : An allowed header name constant for service-worker-allowed


---

### VARY

- VARY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Vary"
  - : An allowed header name constant for Vary


---

### X_CONTENT_TYPE_OPTIONS

- X_CONTENT_TYPE_OPTIONS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-Content-Type-Options"
  - : An allowed header name constant for X-Content-Type-Options


---

### X_FRAME_OPTIONS

- X_FRAME_OPTIONS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-FRAME-OPTIONS"
  - : An allowed header name constant for X-FRAME-OPTIONS.
      
      
      Note: The Commerce Cloud platform can override this header for tools like the Storefront Toolkit.



---

### X_FRAME_OPTIONS_ALLOW_FROM

- X_FRAME_OPTIONS_ALLOW_FROM: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ALLOW-FROM"
  - : An allowed value ALLOW-FROM for X-FRAME-OPTIONS


---

### X_FRAME_OPTIONS_DENY_VALUE

- X_FRAME_OPTIONS_DENY_VALUE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DENY"
  - : An allowed value DENY for X-FRAME-OPTIONS


---

### X_FRAME_OPTIONS_SAMEORIGIN_VALUE

- X_FRAME_OPTIONS_SAMEORIGIN_VALUE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SAMEORIGIN"
  - : An allowed value SAME-ORIGIN value for X-FRAME-OPTIONS


---

### X_ROBOTS_TAG

- X_ROBOTS_TAG: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-Robots-Tag"
  - : An allowed header name constant for X-Robots-Tag


---

### X_XSS_PROTECTION

- X_XSS_PROTECTION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X-XSS-Protection"
  - : An allowed header name constant for X-XSS-Protection


---

## Property Details

### writer
- writer: [PrintWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md) `(read-only)`
  - : Returns a print writer which can be used to print content directly to the response.


---

## Method Details

### addHttpCookie(Cookie)
- addHttpCookie(cookie: [Cookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md)): void
  - : Adds the specified cookie to the outgoing response. This method can be called multiple times to set more than one
      cookie. If a cookie with the same cookie name, domain and path is set multiple times for the same response, only
      the last set cookie with this name is sent to the client. This method can be used to set, update or delete
      cookies at the client. If the cookie doesn't exist at the client, it is set initially. If a cookie with the same
      name, domain and path already exists at the client, it is updated. A cookie can be deleted at the client by
      submitting a cookie with the maxAge attribute set to 0 (see `Cookie.setMaxAge()
       ` for more information).
      
      
      ```
      _Example, how a cookie can be deleted at the client:_
      
      var cookie : Cookie = new Cookie("SomeName", "Simple Value");
      
      cookie.setMaxAge(0);
      
      response.addHttpCookie(cookie);
      ```
      
      
      You can't set a cookie's SameSite attribute using the API. The server sets SameSite to None if either the
      developer sets the cookie's Secure flag or the global security preference Enforce HTTPS is enabled, in which case
      the Secure flag is also set. Otherwise, the server doesn't set the SameSite attribute and the browser uses its
      own default SameSite setting. The SameSite attribute is not sent with a cookie if the server detects that the
      client doesn't correctly interpret the attribute.


    **Parameters:**
    - cookie - a Cookie object


---

### addHttpHeader(String, String)
- addHttpHeader(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a response header with the given name and value. This method allows response headers to have multiple
      values.
      
      
      For public headers, only the names listed in the "Constants" section are allowed. Custom header names must begin
      with the prefix "X-SF-CC-" and can contain only alphanumeric characters, dash, and underscore.


    **Parameters:**
    - name - the name to use for the response header.
    - value - the value to use.


---

### containsHttpHeader(String)
- containsHttpHeader(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks whether the response message header has a field with the specified name.

    **Parameters:**
    - name - the name to use.


---

### getWriter()
- getWriter(): [PrintWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md)
  - : Returns a print writer which can be used to print content directly to the response.


---

### redirect(URL)
- redirect(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): void
  - : Sends a temporary redirect response (HTTP status 302) to the client for the specified redirect location URL.

    **Parameters:**
    - url - the URL object for the target location, must be not null


---

### redirect(URL, Number)
- redirect(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sends a redirect response with the given status to the client for the specified redirect location URL.

    **Parameters:**
    - url - the URL object with the redirect location, must be not null
    - status - the status code for this redirect, must be 301, 302 or 307


---

### redirect(URLRedirect)
- redirect(redirect: [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)): void
  - : Sends a redirect response with the given status to the client for the specified redirect location URL.

    **Parameters:**
    - redirect - the URLRedirect object with the location and status, must be not null


---

### redirect(String)
- redirect(location: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sends a temporary redirect response (HTTP status 302) to the client for the specified redirect location URL. The
      target location must be a relative or an absolute URL.


    **Parameters:**
    - location - the target location as a string, must be not empty


---

### redirect(String, Number)
- redirect(location: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sends a redirect response with the given status to the client for the specified redirect location URL.

    **Parameters:**
    - location - the redirect location, must be not empty
    - status - the status code for this redirect, must be 301, 302 or 307


---

### setBuffered(Boolean)
- setBuffered(buffered: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets whether the output should be buffered or streamed directly to the client. By default, buffering is enabled.
      The mode can only be changed before anything has been written to the response. Switching buffering off and using
      streaming mode is recommended for sending large responses.


    **Parameters:**
    - buffered - if true, buffering is used, if false the response will be streamed


---

### setContentType(String)
- setContentType(contentType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the content type for this response. This method may only be called before any output is written to the
      response.


    **Parameters:**
    - contentType - the MIME type of the content, like "text/html", "application/json" etc.


---

### setExpires(Date)
- setExpires(expires: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Convenience method for [setExpires(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#setexpiresnumber) which takes a Date object.

    **Parameters:**
    - expires - a Date object.


---

### setExpires(Number)
- setExpires(expires: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the cache expiration time for the response. The response will only be cached if caching was not disabled
      previously. By default, responses are not cached. This method can be called multiple times during request
      processing. If caching is enabled, the lowest expiration time, resulting from the invocations of the method
      becomes the cache expiration time. This is only used for HTTP requests. Streamed responses cannot be cached. This
      method is an alternative for setting the cache time using the <iscache> tag in ISML templates.


    **Parameters:**
    - expires - the expiration time in milliseconds since January 1, 1970, 00:00:00 GMT


---

### setHttpHeader(String, String)
- setHttpHeader(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a response header with the given name and value. If one or more value(s) have already been set, the new
      value overwrites the previous one. The [containsHttpHeader(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md#containshttpheaderstring) method can be used to test for the
      presence of a header before setting its value.
      
      
      For public headers, only the names listed in the "Constants" section are allowed. Custom header names must begin
      with the prefix "X-SF-CC-" and can contain only alphanumeric characters, dash, and underscore.


    **Parameters:**
    - name - the name to use for the response header.
    - value - the value to use.


---

### setStatus(Number)
- setStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the HTTP response code.

    **Parameters:**
    - status - a standard-conform HTTP status code, for example 200 for "OK"


---

### setVaryBy(String)
- setVaryBy(varyBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Marks the response as personalized with the given variant identifier. Commerce Cloud Digital identifies unique
      pages based on a combination of pricebook, promotion, sorting rule and A/B test segments, caches the different
      variants of the page, and then delivers the correct version to the user. If a page is personalized by means other
      than pricebook, promotion, sorting rule and A/B test, the page must not be cached, because the wrong variants of
      the page would be delivered to the user. For performance reasons, a page should only be marked as personalized if
      it really is. Otherwise, the performance can unnecessarily degrade.
      
      
      This method has the same effect as using <iscache varyby="price\_promotion" /> tag in an ISML template. Once
      the vary-by value was set, either using this method or by the <iscache> tag in a template, the entire
      response is treated as personalized.


    **Parameters:**
    - varyBy - the variation criteria, currently only "price\_promotion" is supported, any other value has no             effect


---

<!-- prettier-ignore-end -->

<!-- document id=e82c842ebcc493fe994e385ae72054cee399bfd44c3c2634ecbb571c6ba97a46 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.RESTErrorResponse.md -->

<!-- prettier-ignore-start -->
# Class RESTErrorResponse

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md)

This class represents a REST error response that is compliant with
[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). It can only be instantiated using the
`createError` methods in [RESTResponseMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md).


Here is an example:


```

var error = RESTResponseMgr.createError(400);
error.custom.foo = "bar";
error.render();
```


The above script would result in an HTTP response with status code 400 and the following body:


```

{
    "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/bad-request",
    "c_foo": "bar"
}
```


NOTE:

- Custom attributes are rendered with "c\_" prefix as shown in the example above.
- Rendering works as described in [JSON.stringify(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md#stringifyobject).



## Property Summary

| Property | Description |
| --- | --- |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns all the custom attributes associated with the error response object. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md#getcustom)() | Returns all the custom attributes associated with the error response object. |
| [render](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md#render)() | Sends the [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object as an HTTP error response to the client, adhering to  [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns all the custom attributes associated with the error response object. The attributes are stored for the
      lifetime of the error response object.



---

## Method Details

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns all the custom attributes associated with the error response object. The attributes are stored for the
      lifetime of the error response object.


    **Returns:**
    - All the custom attributes associated with the error response object.


---

### render()
- render(): void
  - : Sends the [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object as an HTTP error response to the client, adhering to
      [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). This method sets the "Content-Type" header to
      "application/problem+json", HTTP Status Code to statusCode attribute and constructs the body from type, title,
      detail and custom attributes of the object. Custom attributes are rendered with "c\_" prefix to the attribute
      name.


    **Throws:**
    - IllegalStateException - If the RESTErrorResponse object is already rendered.
    - Exception - If there is an error while serializing the RESTErrorResponse object.


---

<!-- prettier-ignore-end -->

<!-- document id=ea8924e1f70ceed335e789171db5eeef58c477aaf3f6fa2737187d11d4c514a9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.RESTResponseMgr.md -->

<!-- prettier-ignore-start -->
# Class RESTResponseMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.RESTResponseMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md)

This class provides helper methods for creating REST error and success responses. It is mainly intended to be used to
build Custom REST APIs. But, any controller implementation planning to provide REST-like responses can use these
methods. If these methods are being used in the controllers, note that a few defaults like URL prefix for
`type` in `createError` methods will correspond to Custom REST APIs.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [RESTResponseMgr](#restresponsemgr)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| static [createEmptySuccess](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createemptysuccessnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object. |
| static [createError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createerrornumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. |
| static [createError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createerrornumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. |
| static [createError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createerrornumber-string-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. |
| static [createError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createerrornumber-string-string-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. |
| static [createScapiRemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createscapiremoteincludestring-string-string-string-urlparameter)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)) | Constructs a new [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md) object specific for the SCAPI include path. |
| static [createStorefrontControllerRemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createstorefrontcontrollerremoteincludeurlaction-urlparameter)([URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)) | Constructs a new [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md) object specific for the Storefront Controller include path. |
| static [createSuccess](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createsuccessobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs a new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object. |
| static [createSuccess](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md#createsuccessobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### RESTResponseMgr()
- RESTResponseMgr()
  - : 


---

## Method Details

### createEmptySuccess(Number)
- static createEmptySuccess(statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md)
  - : Constructs a new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object. This method is to be used in scenarios where response body
      is not expected (e.g. statusCode is 204).


    **Parameters:**
    - statusCode - The http status code of the response. The statusCode parameter should conform to RFC standards             for a success.

    **Returns:**
    - A new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object.

    **Throws:**
    - IllegalArgumentException - If the statusCode is not in the (100..299) range.


---

### createError(Number)
- static createError(statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md)
  - : Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. This method should be used when you have just the statusCode
      of the error and want the type of error to be inferred.
      
      
      'type' of the error is inferred from the status code as follows: 
      
      
      - `400`- `bad-request`
      - `401`- `unauthorized`
      - `403`- `forbidden`
      - `404`- `resource-not-found`
      - `409`- `conflict`
      - `412`- `precondition-failed`
      - `429`- `too-many-requests`
      - `500`- `internal-server-error`
      - `default`- `about:blank`


    **Parameters:**
    - statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an             error.

    **Returns:**
    - A new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object.

    **Throws:**
    - IllegalArgumentException - If the statusCode is not in the (400..599) range.


---

### createError(Number, String)
- static createError(statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md)
  - : Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. This method should be used when you want to omit 'title' and
      'detail' of the error. With this method, custom error codes and types apart from the standard ones can be
      constructed.


    **Parameters:**
    - statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an             error.
    - type - Type of the error according to RFC 9457. We enforce the following restrictions on top of the RFC:                          <li>If the provided type is not an absolute URL, it will be prepended with             `https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/`.</li>             <li>Custom error types are not allowed to have SYSTEM error type prefix:             `https://api.commercecloud.salesforce.com/documentation/error/v1/errors/`.</li>             </ul>

    **Returns:**
    - A new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object.

    **Throws:**
    - IllegalArgumentException - If the statusCode is not in the (400..599) range or if the error type is not a              valid URI or conflicts with the SYSTEM error type namespace.


---

### createError(Number, String, String)
- static createError(statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md)
  - : Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. This method should be used when you want to omit 'detail' of
      the error but want to have valid 'statusCode', 'type' and 'title'.


    **Parameters:**
    - statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an             error.
    - type - Type of the error according to RFC 9457. We enforce the following restrictions on top of the RFC:                          <li>If the provided type is not an absolute URL, it will be prepended with             `https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/`.</li>             <li>Custom error types are not allowed to have SYSTEM error type prefix:             `https://api.commercecloud.salesforce.com/documentation/error/v1/errors/`.</li>             </ul>
    - title - Human-readable summary of the error type.

    **Returns:**
    - A new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object.

    **Throws:**
    - IllegalArgumentException - If the statusCode is not in the (400..599) range or if the error type is not a              valid URI or conflicts with SYSTEM error type namespace.


---

### createError(Number, String, String, String)
- static createError(statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), title: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), detail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md)
  - : Constructs a new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object. This method can be used to construct error responses with
      valid 'statusCode', 'type', 'title' and 'detail'. If you want to omit title or detail, you can pass in
      `null`.


    **Parameters:**
    - statusCode - The error code of the response. The statusCode parameter should conform to RFC standards for an             error.
    - type - Type of the error according to RFC 9457. We enforce the following restrictions on top of the RFC:                          <li>If the provided type is not an absolute URL, it will be prepended with             `https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/`.</li>             <li>Custom error types are not allowed to have SYSTEM error type prefix:             `https://api.commercecloud.salesforce.com/documentation/error/v1/errors/`.</li>             </ul>
    - title - Human-readable summary of the error type.
    - detail - Human-readable explanation of the specific occurrence of the error.

    **Returns:**
    - A new [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md) object.

    **Throws:**
    - IllegalArgumentException - If the statusCode is not in the (400..599) range or if the error type is not a              valid URI or conflicts with SYSTEM error type namespace.


---

### createScapiRemoteInclude(String, String, String, String, URLParameter...)
- static createScapiRemoteInclude(apiFamily: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), apiName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), apiVersion: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), resourcePath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md)
  - : Constructs a new [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md) object specific for the SCAPI include path.
      Usage:
      SCAPI remote include URL have following form:
      
      ```
      BASE_PATH/{apiFamily}/{apiName}/{apiVersion}/organizations/ORG_ID/{resourcePath}[?params]
      ```
      
      For the given SCAPI resource path:
      
      ```
      BASE_PATH/product/shopper-products/v1/organizations/ORG_ID/categories/root?siteId=YourShopHere
      ```
      
      RemoteInclude object can be constructed in a script like following:
      
      ```
      let include = dw.system.RESTResponseMgr.createScapiRemoteInclude("product", "shopper-products", "v1", "categories/root",
          dw.web.URLParameter("siteId", "YourShopHere"));
      ```
      
      Please notice that **'BASE\_PATH'** and **'ORG\_ID'** are automatically resolved.


    **Parameters:**
    - apiFamily - an API Family name. **Example:** 'product'.
    - apiName - an API Name. **Example:** 'shopper-products'.
    - apiVersion - an API Version. **Example:** 'v1'.
    - resourcePath - a Resource path. **Example:** 'categories/root'
    - params - a query parameters _(optional)_

    **Returns:**
    - a new instance of [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md).


---

### createStorefrontControllerRemoteInclude(URLAction, URLParameter...)
- static createStorefrontControllerRemoteInclude(action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md)
  - : Constructs a new [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md) object specific for the Storefront Controller include path.

    **Parameters:**
    - action - a container to specify target controller. Hostnames in URL actions are ignored.
    - params - a query parameters _(optional)_.

    **Returns:**
    - a new instance of [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md).


---

### createSuccess(Object)
- static createSuccess(body: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md)
  - : Constructs a new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object. HTTP status code of the response will be defaulted to 200.

    **Parameters:**
    - body - The body of the successful response. This should always be a valid JavaScript JSON object.

    **Returns:**
    - A new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object.


---

### createSuccess(Object, Number)
- static createSuccess(body: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md)
  - : Constructs a new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object.

    **Parameters:**
    - body - The body of the successful response. This should always be a valid JavaScript JSON object.
    - statusCode - The http status code of the response. The statusCode parameter should conform to RFC standards             for a success.

    **Returns:**
    - A new [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object.

    **Throws:**
    - IllegalArgumentException - If the statusCode is not in the (100..299) range.


---

<!-- prettier-ignore-end -->

<!-- document id=2814d3a8a85b3c43bac9c736fb4c23f1e69a9a73af6061375dc8dbd6abfe630c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.RESTSuccessResponse.md -->

<!-- prettier-ignore-start -->
# Class RESTSuccessResponse

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md)

This class represents a REST success response that is compliant with the RFC standards. It can only be instantiated
using the `createSuccess` methods in [RESTResponseMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md).


Here is an example: 

`
 var body = {"hello": "world"} 

 var success = RESTResponseMgr.createSuccess(body); 

 success.render(); 

 ` 

The above script would result in an HTTP response with status code 200 and the following body:

`
 {

 &emsp;"hello": "world" 

 } 

 ` 



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [render](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md#render)() | Sends the [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object as an HTTP response to the client. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### render()
- render(): void
  - : Sends the [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md) object as an HTTP response to the client. This sets the "Content-Type"
      header to "application/json" and expects the body to be a valid JavaScript JSON object.


    **Throws:**
    - IllegalStateException - If the RESTSuccessResponse object is already rendered.
    - Exception - If there is an error while serializing the body.


---

<!-- prettier-ignore-end -->

<!-- document id=249cc2c92e3c712d984839d12a37db54dbffddb6be29e47cbb09fb74bb973320 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.Result.md -->

<!-- prettier-ignore-start -->
# Class Result

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.Result](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md)

Represents the result of a service call.


## Constant Summary

| Constant | Description |
| --- | --- |
| [ERROR](#error): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR" | Status indicating a general service error. |
| [OK](#ok): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OK" | Status indicating a successful service call. |
| [SERVICE_UNAVAILABLE](#service_unavailable): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SERVICE_UNAVAILABLE" | Status indicating the service is unavailable. |
| [UNAVAILABLE_CIRCUIT_BROKEN](#unavailable_circuit_broken): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CIRCUIT_BROKEN" | Unavailable reason: No call was made because the circuit breaker prevented it. |
| [UNAVAILABLE_CONFIG_PROBLEM](#unavailable_config_problem): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIG_PROBLEM" | Unavailable reason: No call was made because the service was not configured correctly. |
| [UNAVAILABLE_DISABLED](#unavailable_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DISABLED" | Unavailable reason: No call was made because the service is disabled. |
| [UNAVAILABLE_RATE_LIMITED](#unavailable_rate_limited): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RATE_LIMITED" | Unavailable reason: No call was made because the rate limit was hit. |
| [UNAVAILABLE_TIMEOUT](#unavailable_timeout): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TIMEOUT" | Unavailable reason: A real call was made but a timeout occurred. |

## Property Summary

| Property | Description |
| --- | --- |
| [error](#error): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns an error-specific code if applicable. |
| [errorMessage](#errormessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns an error message on a non-OK status. |
| [mockResult](#mockresult): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the status of whether the response is the result of a "mock" service call. |
| [msg](#msg): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns an extra error message on failure (if any). |
| [object](#object): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the actual object returned by the service when the status is OK. |
| [ok](#ok): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the status of whether the service call was successful. |
| [status](#status): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the status. |
| [unavailableReason](#unavailablereason): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the reason the status is SERVICE\_UNAVAILABLE. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Result](#result)() | Constructs a new result instance. |

## Method Summary

| Method | Description |
| --- | --- |
| [getError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#geterror)() | Returns an error-specific code if applicable. |
| [getErrorMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#geterrormessage)() | Returns an error message on a non-OK status. |
| [getMsg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#getmsg)() | Returns an extra error message on failure (if any). |
| [getObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#getobject)() | Returns the actual object returned by the service when the status is OK. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#getstatus)() | Returns the status. |
| [getUnavailableReason](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#getunavailablereason)() | Returns the reason the status is SERVICE\_UNAVAILABLE. |
| [isMockResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#ismockresult)() | Returns the status of whether the response is the result of a "mock" service call. |
| [isOk](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#isok)() | Returns the status of whether the service call was successful. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#tostring)() | Returns a string representation of the result. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ERROR

- ERROR: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ERROR"
  - : Status indicating a general service error.


---

### OK

- OK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "OK"
  - : Status indicating a successful service call.


---

### SERVICE_UNAVAILABLE

- SERVICE_UNAVAILABLE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SERVICE_UNAVAILABLE"
  - : Status indicating the service is unavailable. This includes timeouts, rate limits, and remote server issues.


---

### UNAVAILABLE_CIRCUIT_BROKEN

- UNAVAILABLE_CIRCUIT_BROKEN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CIRCUIT_BROKEN"
  - : Unavailable reason: No call was made because the circuit breaker prevented it.


---

### UNAVAILABLE_CONFIG_PROBLEM

- UNAVAILABLE_CONFIG_PROBLEM: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIG_PROBLEM"
  - : Unavailable reason: No call was made because the service was not configured correctly.


---

### UNAVAILABLE_DISABLED

- UNAVAILABLE_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DISABLED"
  - : Unavailable reason: No call was made because the service is disabled.


---

### UNAVAILABLE_RATE_LIMITED

- UNAVAILABLE_RATE_LIMITED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RATE_LIMITED"
  - : Unavailable reason: No call was made because the rate limit was hit.


---

### UNAVAILABLE_TIMEOUT

- UNAVAILABLE_TIMEOUT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "TIMEOUT"
  - : Unavailable reason: A real call was made but a timeout occurred.


---

## Property Details

### error
- error: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns an error-specific code if applicable. For example, this is the HTTP response code for an
      [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md).



---

### errorMessage
- errorMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns an error message on a non-OK status.


---

### mockResult
- mockResult: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the status of whether the response is the result of a "mock" service call.


---

### msg
- msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns an extra error message on failure (if any).


---

### object
- object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the actual object returned by the service when the status is OK.


---

### ok
- ok: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the status of whether the service call was successful.


---

### status
- status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the status. This is "OK" on success. Failure codes include "ERROR" and "SERVICE\_UNAVAILABLE".
      
      
      If the status is "SERVICE\_UNAVAILABLE", then the unavailableReason is guaranteed to be non-null.


    **See Also:**
    - [OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#ok)
    - [ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#error)
    - [SERVICE_UNAVAILABLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#service_unavailable)


---

### unavailableReason
- unavailableReason: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the reason the status is SERVICE\_UNAVAILABLE.

    **See Also:**
    - [UNAVAILABLE_TIMEOUT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_timeout)
    - [UNAVAILABLE_CIRCUIT_BROKEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_circuit_broken)
    - [UNAVAILABLE_RATE_LIMITED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_rate_limited)
    - [UNAVAILABLE_DISABLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_disabled)
    - [UNAVAILABLE_CONFIG_PROBLEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_config_problem)


---

## Constructor Details

### Result()
- Result()
  - : Constructs a new result instance.


---

## Method Details

### getError()
- getError(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an error-specific code if applicable. For example, this is the HTTP response code for an
      [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md).


    **Returns:**
    - Error-specific code (if applicable).


---

### getErrorMessage()
- getErrorMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an error message on a non-OK status.

    **Returns:**
    - Error message.


---

### getMsg()
- getMsg(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an extra error message on failure (if any).

    **Returns:**
    - Error message, or null.


---

### getObject()
- getObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the actual object returned by the service when the status is OK.

    **Returns:**
    - Object returned by the service.


---

### getStatus()
- getStatus(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status. This is "OK" on success. Failure codes include "ERROR" and "SERVICE\_UNAVAILABLE".
      
      
      If the status is "SERVICE\_UNAVAILABLE", then the unavailableReason is guaranteed to be non-null.


    **Returns:**
    - Status code.

    **See Also:**
    - [OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#ok)
    - [ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#error)
    - [SERVICE_UNAVAILABLE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#service_unavailable)


---

### getUnavailableReason()
- getUnavailableReason(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the reason the status is SERVICE\_UNAVAILABLE.

    **Returns:**
    - Unavailable reason code, or null if the status is not SERVICE\_UNAVAILABLE.

    **See Also:**
    - [UNAVAILABLE_TIMEOUT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_timeout)
    - [UNAVAILABLE_CIRCUIT_BROKEN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_circuit_broken)
    - [UNAVAILABLE_RATE_LIMITED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_rate_limited)
    - [UNAVAILABLE_DISABLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_disabled)
    - [UNAVAILABLE_CONFIG_PROBLEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md#unavailable_config_problem)


---

### isMockResult()
- isMockResult(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the response is the result of a "mock" service call.

    **Returns:**
    - true if this was a mock service call, false otherwise.


---

### isOk()
- isOk(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the service call was successful.

    **Returns:**
    - true on success, false otherwise.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of the result.

    **Returns:**
    - a string representation of the result.


---

<!-- prettier-ignore-end -->

<!-- document id=2f1841d09cef169fbfde82652cb50ed75d4be386dab8f21349b8ea1edd7f0f29 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.Return.md -->

<!-- prettier-ignore-start -->
# Class Return

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md)
      - [dw.order.Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)

The Return represents a physical customer return, and contains 1..n
[ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s. The Return is associated with one [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), and each
ReturnItem is associated with one [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) and (via the
ReturnCaseItem) a single [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) usually representing an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
[ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md). 

The ReturnItem records the quantity returned.

The Return can have one of these status values:

- NEW - the return is new, i.e. needs to undergo a check before it can be  marked as COMPLETED
- COMPLETED - the return is complete, this is a precondition for refunding the  customer for a return.



Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [ORDERBY_ITEMID](#orderby_itemid): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by item id. |
| [ORDERBY_ITEMPOSITION](#orderby_itemposition): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by the position of the related oder item. |
| [ORDERBY_UNSORTED](#orderby_unsorted): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Unsorted , as it is. |
| [QUALIFIER_PRODUCTITEMS](#qualifier_productitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the product items. |
| [QUALIFIER_SERVICEITEMS](#qualifier_serviceitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects for the service items. |
| [STATUS_COMPLETED](#status_completed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COMPLETED" | Constant for Return Status COMPLETED |
| [STATUS_NEW](#status_new): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW" | Constant for Return Status NEW |

## Property Summary

| Property | Description |
| --- | --- |
| [invoice](#invoice): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)` | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [invoiceNumber](#invoicenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns null or the invoice-number. |
| [items](#items): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Returns the [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s contained in the Return, created with method  [createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createitemstring). |
| [note](#note): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | A note for the return. |
| [returnCase](#returncase): [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) `(read-only)` | Returns the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) with which this Return is associated. |
| [returnNumber](#returnnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The return number identifying this return. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Gets the return status. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoice)() | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Return. |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Return. |
| [createItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Create a [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) based on a [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md). |
| [getInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getinvoice)() | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [getInvoiceNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getinvoicenumber)() | Returns null or the invoice-number. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getitems)() | Returns the [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s contained in the Return, created with method  [createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createitemstring). |
| [getNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getnote)() | A note for the return. |
| [getReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getreturncase)() | Returns the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) with which this Return is associated. |
| [getReturnNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getreturnnumber)() | The return number identifying this return. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getstatus)() | Gets the return status. |
| [setNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#setnotestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets a note for the return. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#setstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the return status. |

### Methods inherited from class AbstractItemCtnr

[getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreatedby), [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreationdate), [getGrandTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getgrandtotal), [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getlastmodified), [getModifiedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getmodifiedby), [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder), [getProductSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getproductsubtotal), [getServiceSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getservicesubtotal)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ORDERBY_ITEMID

- ORDERBY_ITEMID: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by item id. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### ORDERBY_ITEMPOSITION

- ORDERBY_ITEMPOSITION: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by the position of the related oder item. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### ORDERBY_UNSORTED

- ORDERBY_UNSORTED: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Unsorted , as it is. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### QUALIFIER_PRODUCTITEMS

- QUALIFIER_PRODUCTITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the product items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getitems) as an argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).


---

### QUALIFIER_SERVICEITEMS

- QUALIFIER_SERVICEITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects for the service items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getitems) as an argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).


---

### STATUS_COMPLETED

- STATUS_COMPLETED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COMPLETED"
  - : Constant for Return Status COMPLETED


---

### STATUS_NEW

- STATUS_NEW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW"
  - : Constant for Return Status NEW


---

## Property Details

### invoice
- invoice: [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)`
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring)


---

### invoiceNumber
- invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns null or the invoice-number.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring)


---

### items
- items: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Returns the [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s contained in the Return, created with method
      [createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createitemstring).
      
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#qualifier_serviceitems)


    **See Also:**
    - [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)


---

### note
- note: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : A note for the return.


---

### returnCase
- returnCase: [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) `(read-only)`
  - : Returns the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) with which this Return is associated. The ReturnCase
      may represent an RMA (return merchandise authorization).



---

### returnNumber
- returnNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The return number identifying this return.


---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the return status.
      
      
      Possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#status_new), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#status_completed).



---

## Method Details

### createInvoice()
- createInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Return.
      The return-number will be used as the invoice-number. The
      Invoice can then be accessed using [getInvoice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getinvoice) or its
      number using [getInvoiceNumber()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getinvoicenumber). The method must not be called
      more than once for a Return, nor may 2 Invoices exist
      with the same invoice-number.
      
      
      The new Invoice is a credit-invoice with a [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid) status, and
      will be passed to the refund payment-hook in a separate database
      transaction for processing.


    **Returns:**
    - new invoice


---

### createInvoice(String)
- createInvoice(invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this Return. The
      invoice-number must be specified as an argument. The
      Invoice can then be accessed using [getInvoice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getinvoice) or its
      number using [getInvoiceNumber()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#getinvoicenumber). The method must not be called
      more than once for a Return, nor may 2 Invoices exist
      with the same invoice-number.
      
      
      The new Invoice is a credit-invoice with a [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid) status, and
      will be passed to the refund payment-hook in a separate database
      transaction for processing.


    **Parameters:**
    - invoiceNumber - the invoice-number to use

    **Returns:**
    - the new invoice


---

### createItem(String)
- createItem(returnCaseItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)
  - : Create a [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) based on a [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md).

    **Parameters:**
    - returnCaseItemID - the id of the return case item

    **Returns:**
    - the created return item


---

### getInvoice()
- getInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **Returns:**
    - null or the previously created invoice.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring)


---

### getInvoiceNumber()
- getInvoiceNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns null or the invoice-number.

    **Returns:**
    - null or the previously created invoice.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring)


---

### getItems()
- getItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Returns the [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s contained in the Return, created with method
      [createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createitemstring).
      
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#qualifier_serviceitems)


    **Returns:**
    - the return items

    **See Also:**
    - [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)


---

### getNote()
- getNote(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : A note for the return.

    **Returns:**
    - the note or `null`


---

### getReturnCase()
- getReturnCase(): [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)
  - : Returns the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) with which this Return is associated. The ReturnCase
      may represent an RMA (return merchandise authorization).


    **Returns:**
    - the return case


---

### getReturnNumber()
- getReturnNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The return number identifying this return.

    **Returns:**
    - the return number


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the return status.
      
      
      Possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#status_new), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#status_completed).


    **Returns:**
    - the status


---

### setNote(String)
- setNote(note: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets a note for the return.

    **Parameters:**
    - note - the note


---

### setStatus(String)
- setStatus(statusName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the return status.
      
      
      Possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#status_new), [STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#status_completed)
      
      
      When set to status COMPLETED, only the the custom attributes of the return itself and its return items can be changed.


    **Parameters:**
    - statusName - the status


---

<!-- prettier-ignore-end -->

<!-- document id=9f0bda29a459446d9d2723f73a4730b455e6c50ad5afa6f1d77e459cf6123f7b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ReturnCase.md -->

<!-- prettier-ignore-start -->
# Class ReturnCase

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md)
      - [dw.order.ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)

All returns exist in the context of a ReturnCase, each [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
can have any number of ReturnCases. 

The ReturnCase has [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s, each of which is associated with an
[OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) (an extension to either a [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) or a [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)). 

Each ReturnCaseItem defines [ReturnCaseItem.getAuthorizedQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getauthorizedquantity) representing the maximum
quantity expected to be returned. The ReturnCaseItem may be associated with
0..n [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s - ReturnItems are added to the ReturnCaseItem when
[Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s are created.


_Either_ - a ReturnCase may be used as an RMA, in which case they are
created when a customer first shows a wish to return item(s). The customer
then includes the RMA number with the returned item(s). The Return created as
a result is then associated with the existing ReturnCase. 

_Or_ - a ReturnCase is automatically created as part of the return
creation, i.e. the customer returns some item(s) leading to a creation of
both a Return and an associated ReturnCase.




The scripting api allows access to the ReturnCases, whether the ReturnCase is an RMA or not,
and the ReturnCase status. Both the ReturnCaseItems and any Returns
associated with the ReturnCase can be accessed.


A ReturnCase has one of these status values:

- NEW - the ReturnCase has been created and can be edited previous to  its authorization
- CONFIRMED - the ReturnCase is CONFIRMED, can no longer be edited, no  Returns have been associated with it. Only a NEW- ReturnCase can be  CONFIRMED
- PARTIAL\_RETURNED - the ReturnCase has been associated with at least one Return,  but is not yet complete. Only a CONFIRMED- ReturnCase can be set to  PARTIAL\_RETURNED
- RETURNED - the ReturnCase has been associated with Returns which match  the expected authorized quantity. Only an CONFIRMED- or PARTIAL\_RETURNED- return-case  can be set to RETURNED
- CANCELLED - the ReturnCase has been cancelled (only a NEW- or  CONFIRMED- ReturnCase can be cancelled)



Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [ORDERBY_ITEMID](#orderby_itemid): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by item id. |
| [ORDERBY_ITEMPOSITION](#orderby_itemposition): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by the position of the related oder item. |
| [ORDERBY_UNSORTED](#orderby_unsorted): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Unsorted , as it is. |
| [QUALIFIER_PRODUCTITEMS](#qualifier_productitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the product items. |
| [QUALIFIER_SERVICEITEMS](#qualifier_serviceitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects for the service items. |
| [STATUS_CANCELLED](#status_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED" | constant for ReturnCase Status CANCELLED |
| [STATUS_CONFIRMED](#status_confirmed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED" | constant for ReturnCase Status CONFIRMED |
| [STATUS_NEW](#status_new): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW" | constant for ReturnCase Status NEW |
| [STATUS_PARTIAL_RETURNED](#status_partial_returned): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PARTIAL_RETURNED" | constant for ReturnCase Status PARTIAL RETURNED |
| [STATUS_RETURNED](#status_returned): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURNED" | constant for ReturnCase Status RETURNED |

## Property Summary

| Property | Description |
| --- | --- |
| [RMA](#rma): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Return whether this is an RMA. |
| [invoice](#invoice): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)` | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [invoiceNumber](#invoicenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns null or the invoice-number. |
| [items](#items): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Access the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s. |
| [returnCaseNumber](#returncasenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the mandatory return case number identifying this document. |
| [returns](#returns): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Return the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this ReturnCase. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | Gets the return case item status. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [confirm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#confirm)() | <p>Attempt to confirm the ReturnCase. |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoice)() | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this  ReturnCase. |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this  ReturnCase. |
| [createItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new item for a given order item. |
| [createReturn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createreturn)() | Creates a new [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) with a generated number and associates it with this ReturnCase. |
| [createReturn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createreturnstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) with the given number and associates it with this ReturnCase. |
| [getInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getinvoice)() | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [getInvoiceNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getinvoicenumber)() | Returns null or the invoice-number. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getitems)() | Access the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s. |
| [getReturnCaseNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getreturncasenumber)() | Returns the mandatory return case number identifying this document. |
| [getReturns](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getreturns)() | Return the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this ReturnCase. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getstatus)() | Gets the return case item status. |
| [isRMA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#isrma)() | Return whether this is an RMA. |

### Methods inherited from class AbstractItemCtnr

[getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreatedby), [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreationdate), [getGrandTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getgrandtotal), [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getlastmodified), [getModifiedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getmodifiedby), [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder), [getProductSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getproductsubtotal), [getServiceSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getservicesubtotal)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ORDERBY_ITEMID

- ORDERBY_ITEMID: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by item id. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### ORDERBY_ITEMPOSITION

- ORDERBY_ITEMPOSITION: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by the position of the related oder item. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### ORDERBY_UNSORTED

- ORDERBY_UNSORTED: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Unsorted , as it is. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getitems) as an argument to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).


---

### QUALIFIER_PRODUCTITEMS

- QUALIFIER_PRODUCTITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the product items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getitems) as an argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).


---

### QUALIFIER_SERVICEITEMS

- QUALIFIER_SERVICEITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects for the service items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getitems) as an argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).


---

### STATUS_CANCELLED

- STATUS_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED"
  - : constant for ReturnCase Status CANCELLED


---

### STATUS_CONFIRMED

- STATUS_CONFIRMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED"
  - : constant for ReturnCase Status CONFIRMED


---

### STATUS_NEW

- STATUS_NEW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW"
  - : constant for ReturnCase Status NEW


---

### STATUS_PARTIAL_RETURNED

- STATUS_PARTIAL_RETURNED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PARTIAL_RETURNED"
  - : constant for ReturnCase Status PARTIAL RETURNED


---

### STATUS_RETURNED

- STATUS_RETURNED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURNED"
  - : constant for ReturnCase Status RETURNED


---

## Property Details

### RMA
- RMA: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Return whether this is an RMA. This is specified when calling [Order.createReturnCase(String, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createreturncasestring-boolean).


---

### invoice
- invoice: [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)`
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring)


---

### invoiceNumber
- invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns null or the invoice-number.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring)


---

### items
- items: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Access the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#qualifier_serviceitems)



---

### returnCaseNumber
- returnCaseNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the mandatory return case number identifying this document.


---

### returns
- returns: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Return the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this ReturnCase.


---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : Gets the return case item status. The status of a ReturnCase is read-only and calculated from the status of
      the associated [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s.
      
      
      The possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_new),[STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_confirmed),
      [STATUS_PARTIAL_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_partial_returned), [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_returned),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_cancelled).



---

## Method Details

### confirm()
- confirm(): void
  - : 
      Attempt to confirm the ReturnCase.
      
      
      Without items the return case will be canceled
      
      
      When confirmed, only the the custom attributes of its return case items can be changed.


    **Throws:**
    - IllegalStateException - thrown if Status is not [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_new)


---

### createInvoice()
- createInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this
      ReturnCase. The return-case-number will
      be used as the invoice-number. The Invoice can then be
      accessed using [getInvoice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getinvoice) or its number using
      [getInvoiceNumber()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getinvoicenumber). The method must not be called more than once
      for a ReturnCase, nor may 2 Invoices
      exist with the same invoice-number.
      
      
      The new Invoice is a credit-invoice with a
      [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid) status, and will be passed to
      the refund payment-hook in a separate database transaction for
      processing.


    **Returns:**
    - new invoice


---

### createInvoice(String)
- createInvoice(invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this
      ReturnCase. The invoice-number must be specified as an
      argument. The Invoice can then be
      accessed using [getInvoice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getinvoice) or its number using
      [getInvoiceNumber()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#getinvoicenumber). The method must not be called more than once
      for a ReturnCase, nor may 2 Invoices
      exist with the same invoice-number.
      
      
      The new Invoice is a credit-invoice with a
      [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid) status, and will be passed to
      the refund payment-hook in a separate database transaction for
      processing.


    **Parameters:**
    - invoiceNumber - the invoice-number to be used for the invoice creation

    **Returns:**
    - new invoice


---

### createItem(String)
- createItem(orderItemID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
  - : Creates a new item for a given order item. Note: a ReturnCase may have
      only one item per order item.


    **Parameters:**
    - orderItemID - order item id

    **Returns:**
    - null or item for given order item

    **Throws:**
    - IllegalArgumentException - thrown if getItem(orderItem) returns non null


---

### createReturn()
- createReturn(): [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)
  - : Creates a new [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) with a generated number and associates it with this ReturnCase.

    **Returns:**
    - new Return instance


---

### createReturn(String)
- createReturn(returnNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)
  - : Creates a new [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) with the given number and associates it with this ReturnCase.

    **Parameters:**
    - returnNumber - return number to assign

    **Returns:**
    - new Return instance


---

### getInvoice()
- getInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **Returns:**
    - null or the previously created invoice.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring)


---

### getInvoiceNumber()
- getInvoiceNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns null or the invoice-number.

    **Returns:**
    - null or the previously created invoice.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring)


---

### getItems()
- getItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Access the collection of [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) can be sorted / filtered using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#qualifier_serviceitems)


    **Returns:**
    - the items


---

### getReturnCaseNumber()
- getReturnCaseNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the mandatory return case number identifying this document.

    **Returns:**
    - the return case number


---

### getReturns()
- getReturns(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Return the collection of [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with this ReturnCase.

    **Returns:**
    - the collection of Returns.


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the return case item status. The status of a ReturnCase is read-only and calculated from the status of
      the associated [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s.
      
      
      The possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_new),[STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_confirmed),
      [STATUS_PARTIAL_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_partial_returned), [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_returned),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#status_cancelled).


    **Returns:**
    - the status


---

### isRMA()
- isRMA(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Return whether this is an RMA. This is specified when calling [Order.createReturnCase(String, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createreturncasestring-boolean).

    **Returns:**
    - whether this is an RMA.


---

<!-- prettier-ignore-end -->

<!-- document id=d286a6ba8117de2c4aa45454888095e349caf79505449ef485bf20c67d8994fa url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ReturnCaseItem.md -->

<!-- prettier-ignore-start -->
# Class ReturnCaseItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md)
      - [dw.order.ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)

An item of a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), created using method
[ReturnCase.createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createitemstring). Initially the
ReturnCaseItem is NEW. No [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) can be
created at this point. From NEW the item transitions in CONFIRMED state.
Now Return can be created. Next transition is either to
PARTIAL\_RETURNED or to CANCELLED. At the end the item can be RETURNED (no other
Returns can be created.

The custom code implementing the ReturnHooks is
responsible to provide the logic for the transitions. Please refer to the
documentation of [ReturnHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md) for further
information.


When the related ReturnCase were confirmed, only the the custom attributes of the return case item can be changed.


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [STATUS_CANCELLED](#status_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED" | constant for ReturnCase Status CANCELLED |
| [STATUS_CONFIRMED](#status_confirmed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED" | constant for ReturnCase Status CONFIRMED |
| [STATUS_NEW](#status_new): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW" | constant for ReturnCase Status NEW |
| [STATUS_PARTIAL_RETURNED](#status_partial_returned): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PARTIAL_RETURNED" | constant for ReturnCase Status PARTIAL RETURNED |
| [STATUS_RETURNED](#status_returned): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURNED" | constant for ReturnCase Status RETURNED |

## Property Summary

| Property | Description |
| --- | --- |
| [authorizedQuantity](#authorizedquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | Return the [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) authorized for this ReturnCaseItem, may be N/A. |
| [basePrice](#baseprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Price of a single unit before discount application. |
| [note](#note): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Return the note for this return case item. |
| [parentItem](#parentitem): [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) | Returns null or the parent item. |
| [reasonCode](#reasoncode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the reason code for return case item. |
| [returnCaseNumber](#returncasenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Mandatory number of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) to which this item belongs |
| [returnItems](#returnitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Unsorted collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this ReturnCaseItem. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Gets the return case item status. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#createreturnitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Create a new [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) for this ReturnCaseItem and assign it to the  given [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md). |
| [getAuthorizedQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getauthorizedquantity)() | Return the [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) authorized for this ReturnCaseItem, may be N/A. |
| [getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getbaseprice)() | Price of a single unit before discount application. |
| [getNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getnote)() | Return the note for this return case item. |
| [getParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getparentitem)() | Returns null or the parent item. |
| [getReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getreasoncode)() | Returns the reason code for return case item. |
| [getReturnCaseNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getreturncasenumber)() | Mandatory number of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) to which this item belongs |
| [getReturnItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getreturnitems)() | Unsorted collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this ReturnCaseItem. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getstatus)() | Gets the return case item status. |
| [setAuthorizedQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#setauthorizedquantityquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Set the optional authorized [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) for this item. |
| [setNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#setnotestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets a note for this return case item. |
| [setParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#setparentitemreturncaseitem)([ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)) | Set a parent item. |
| [setReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#setreasoncodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Changes the reason code. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#setstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the status. |

### Methods inherited from class AbstractItem

[getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice), [getItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getitemid), [getLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getlineitem), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice), [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitem), [getOrderItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitemid), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis), [getTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxitems)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### STATUS_CANCELLED

- STATUS_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED"
  - : constant for ReturnCase Status CANCELLED


---

### STATUS_CONFIRMED

- STATUS_CONFIRMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED"
  - : constant for ReturnCase Status CONFIRMED


---

### STATUS_NEW

- STATUS_NEW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NEW"
  - : constant for ReturnCase Status NEW


---

### STATUS_PARTIAL_RETURNED

- STATUS_PARTIAL_RETURNED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PARTIAL_RETURNED"
  - : constant for ReturnCase Status PARTIAL RETURNED


---

### STATUS_RETURNED

- STATUS_RETURNED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETURNED"
  - : constant for ReturnCase Status RETURNED


---

## Property Details

### authorizedQuantity
- authorizedQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Return the [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) authorized for this ReturnCaseItem, may be N/A.


---

### basePrice
- basePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Price of a single unit before discount application.


---

### note
- note: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the note for this return case item.


---

### parentItem
- parentItem: [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
  - : Returns null or the parent item.


---

### reasonCode
- reasonCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code for return case item.


---

### returnCaseNumber
- returnCaseNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Mandatory number of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) to which this item belongs


---

### returnItems
- returnItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Unsorted collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this ReturnCaseItem.

    **See Also:**
    - [createReturnItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#createreturnitemstring)


---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the return case item status.
      
      
      The possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_new),[STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_confirmed),
      [STATUS_PARTIAL_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_partial_returned), [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_returned),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_cancelled).



---

## Method Details

### createReturnItem(String)
- createReturnItem(returnNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)
  - : Create a new [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) for this ReturnCaseItem and assign it to the
      given [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md).


    **Parameters:**
    - returnNumber - number of Return to which new item is assigned.

    **Returns:**
    - new ReturnItem


---

### getAuthorizedQuantity()
- getAuthorizedQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Return the [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) authorized for this ReturnCaseItem, may be N/A.

    **Returns:**
    - the authorized quantity or N/A


---

### getBasePrice()
- getBasePrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Price of a single unit before discount application.

    **Returns:**
    - Price of a single unit before discount application.


---

### getNote()
- getNote(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the note for this return case item.

    **Returns:**
    - the note or `null`


---

### getParentItem()
- getParentItem(): [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
  - : Returns null or the parent item.

    **Returns:**
    - null or the parent item.


---

### getReasonCode()
- getReasonCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code for return case item.

    **Returns:**
    - the return reason code


---

### getReturnCaseNumber()
- getReturnCaseNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Mandatory number of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) to which this item belongs

    **Returns:**
    - number of ReturnCase to which this item belongs


---

### getReturnItems()
- getReturnItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Unsorted collection of [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s associated with this ReturnCaseItem.

    **Returns:**
    - unsorted collection of ReturnItems associated with this ReturnCaseItem

    **See Also:**
    - [createReturnItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#createreturnitemstring)


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the return case item status.
      
      
      The possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_new),[STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_confirmed),
      [STATUS_PARTIAL_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_partial_returned), [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_returned),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_cancelled).


    **Returns:**
    - the status


---

### setAuthorizedQuantity(Quantity)
- setAuthorizedQuantity(authorizedQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): void
  - : Set the optional authorized [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) for this item. Passing null will result in an N/A Quantity
      being set.


    **Parameters:**
    - authorizedQuantity - null or the quantity


---

### setNote(String)
- setNote(note: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets a note for this return case item.

    **Parameters:**
    - note - the note for this return case item to set


---

### setParentItem(ReturnCaseItem)
- setParentItem(parentItem: [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)): void
  - : Set a parent item. The parent item must belong to the same
      [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md). An infinite parent-child loop is disallowed
      as is a parent-child depth greater than 10. Setting a parent item
      indicates a dependency of the child item on the parent item, and can be
      used to form a parallel structure to that accessed using
      [ProductLineItem.getParent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getparent).


    **Parameters:**
    - parentItem - The parent item, null is allowed


---

### setReasonCode(String)
- setReasonCode(reasonCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Changes the reason code. Initially the reason code is set on return case
      item creation.


    **Parameters:**
    - reasonCode - the reason code to set


---

### setStatus(String)
- setStatus(statusString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the status.
      
      
      The possible values are [STATUS_NEW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_new),[STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_confirmed),
      [STATUS_PARTIAL_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_partial_returned), [STATUS_RETURNED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_returned),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#status_cancelled).


    **Parameters:**
    - statusString - the status

    **Throws:**
    - NullPointerException - if status is `null`
    - IllegalArgumentException - if the status transition to the status is not allowed


---

<!-- prettier-ignore-end -->

<!-- document id=c8c92693cf653e9c2b433623d4c1781d7ddb3adf69f7a9ea22d2f6f9f84cb28e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.ReturnHooks.md -->

<!-- prettier-ignore-start -->
# Class ReturnHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.ReturnHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md)

This interface represents all script hooks that can be registered to
customizing the order center return resource. It contains the extension
points (hook names), and the functions that are called by each extension
point. A function must be defined inside a JavaScript source and must be
exported. The script with the exported hook function must be located inside a
site cartridge. Inside the site cartridge a 'package.json' file with a
'hooks' entry must exist.


"hooks": "./hooks.json"


The hooks entry links to a json file, relative to the 'package.json' file.
This file lists all registered hooks inside the hooks property:




```
"hooks": [
   {"name": "dw.order.return.createReturn",           "script": "./returns.ds"},
   {"name": "dw.order.return.addReturnItem",          "script": "./returns.ds"},
   {"name": "dw.order.return.changeStatus",           "script": "./returns.ds"},
]
```




A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the  exported hook function.


Overview Return Functionality Business objects 
[ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) All returns exist in the context of a
[ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), each [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) can have any number
of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)s. 

A [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) has [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s, each of
which is associated with an [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) (an extension to
either a [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) or a
[ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)). 

Each [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) defines an
[ReturnCaseItem.getAuthorizedQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#getauthorizedquantity) representing the
maximum quantity expected to be returned. A [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
may be associated with 0..n [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s -
[ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s are added to the [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
when [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s are created.


_Either_ - a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) may be used as an RMA, in which
case they are created when a customer first shows a wish to return item(s).
The customer then includes the RMA number with the returned item(s). The
[Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) created as a result is then associated with the
existing [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md). 

_Or_ - a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) is automatically created as part of
the return creation, i.e. the customer returns some item(s) leading to a
creation of both a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) and an associated
[ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md).




The scripting api allows access to the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)s, whether
the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) is an RMA or not, and the
[ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) status. Both the [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s
and any [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s associated with the
[ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) can be accessed.


A [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) has one of these status values:

- New - the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)has been created and can be edited  previous to its authorization
- CONFIRMED - the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)is CONFIRMED, can no longer  be edited, no [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s have been associated with it. Only an  New- [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)can be CONFIRMED
- PARTIAL\_RETURNED - the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)has been associated  with at least one [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), but is not yet complete. Only an  CONFIRMED- [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)can be set to PARTIAL\_RETURNED
- RETURNED - the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)has been associated with  [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s which match the expected authorized quantity. Only  an CONFIRMED- or PARTIAL\_RETURNED- return-case can be set to RETURNED
- Cancelled - the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)has been cancelled (only a  New- or CONFIRMED- [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)can be cancelled)


[Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)
A [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) represents a physical customer return, and contains
1..n [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s. A [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) is associated
with one [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), and each [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) is
associated with one [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) and (via the
[ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)) a single [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) usually
representing an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md). 

A [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) records the quantity returned. 

A [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) can have one of these status values:

- NEW - the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)is new, i.e. needs to undergo a check  before it can be marked as COMPLETED
- COMPLETED - the return is complete, this is a precondition for refunding  the customer for a return.

Credit Invoice
As a result of making a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), the customer may be
refunded. The refund amount is held in a credit [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
which may be associated _either_ with one [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)
_or_ with one [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md). The [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
is passed to the _refund_ payment hook allowing custom code to handle
the payment refund.

Process overview
Create [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)
The creation of [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)s is supported using the data-api.
The api supports, within the context of an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), the
specification of an (optional) RMA-number and addition of
[ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)s for a given order-item and quantity.
Authorize [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)
Following its creation, a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) needs to be CONFIRMED -
an CONFIRMED [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) cannot be modified.
Cancel [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)
Following its creation or authorization, a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) may be
cancelled.
Create [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)
[Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)s may be imported or created via the data-api. These
apis specify an (optional) RMA allowing a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) to be
associated with a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), and
[ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s with a quantity and a key allowing them to be
associated with an order-item. The process is delegated to custom scripts
which control the creation of the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) and the addition of
the [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s:

Hook [extensionPointCreateReturn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#extensionpointcreatereturn)
The creation of the new [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) is delegated to the custom
script when this hook is called, passing the order, and details of the
[Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) to be created to the script. Typically the script
accesses the [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) from the order and creates the
return with the provided return-number. It may also update the
[Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md) or
[Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) using custom values passed in the
[Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) details. 

`
   
exports.createReturn = function (order:Order, returnDetails) {
   
  var returnNumber=returnDetails.returnNumber;
   
  var returnCase = order.getReturnCase(returnDetails.returnCaseNumber);
   
  var newReturn = returnCase.createReturn(returnNumber);
   
 return newReturn;
   
}`

Hook [extensionPointAddReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#extensionpointaddreturnitem)
This call delegates the creation of individual [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s
to a custom script, passing the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), returnNumber,
returnCaseItemId and return-item-details. Typically the script will access
the [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) from the order and create a new
[ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) for it. 

`exports.addReturnItem = function (retrn:Return, returnItemDetails) {
   
 var returnCaseItem = order.getReturnCaseItem(returnCaseItemId);
   
 var item = returnCaseItem.createReturnItem(returnNr);
   
`

Hook [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#extensionpointchangestatus)
This call delegates the update of the return-status to a custom script,
passing the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), returnNumber and new status. The custom
script is responsible for setting the status and taking any other actions
necessary, including the possibility of creating a credit invoice: 

`changeStatus = function (retrn:Return, status) {
   
 retrn.status=status;
   
`

Hook [extensionPointAfterStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#extensionpointafterstatuschange)
This call delegates the update of the return-status to a custom script,
passing the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), returnNumber and new status. The custom
script is responsible for setting the status and taking any other actions
necessary, including the possibility of creating a credit invoice: 

`changeStatus = function (retrn:Return, status) {
   
 retrn.status=status;
   
`


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointAddReturnItem](#extensionpointaddreturnitem): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.addReturnItem" | The extension point name dw.order.return.addReturnItem. |
| [extensionPointAfterStatusChange](#extensionpointafterstatuschange): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.afterStatusChange" | The extension point name dw.order.return.afterStatusChange. |
| [extensionPointChangeStatus](#extensionpointchangestatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.changeStatus" | The extension point name dw.order.return.changeStatus. |
| [extensionPointCreateReturn](#extensionpointcreatereturn): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.createReturn" | The extension point name dw.order.return.createReturn. |
| [extensionPointNotifyStatusChange](#extensionpointnotifystatuschange): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.notifyStatusChange" | The extension point name dw.order.return.notifyStatusChange. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#addreturnitemreturn-returnitemwo)([Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), ReturnItemWO) | The hook provides customization in the process of assigning the returned  amount, quantity etc. |
| [afterStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#afterstatuschangereturn)([Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)) | Called after method [changeStatus(Return, ReturnWO)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#changestatusreturn-returnwo) returns  Status.OK. |
| [changeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#changestatusreturn-returnwo)([Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), ReturnWO) | Responsible to change the status of a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md): the custom  script is responsible for setting the new status using  [Return.setStatus(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#setstatusstring). |
| [createReturn](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#createreturnreturnwo)(ReturnWO) | This hook is responsible for creating a new [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md),  based on a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md). |
| [notifyStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#notifystatuschangereturn)([Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)) | Called after method [changeStatus(Return, ReturnWO)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#changestatusreturn-returnwo) returns  Status.OK (and after method [afterStatusChange(Return)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#afterstatuschangereturn))  to inform of a successful status change. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointAddReturnItem

- extensionPointAddReturnItem: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.addReturnItem"
  - : The extension point name dw.order.return.addReturnItem.


---

### extensionPointAfterStatusChange

- extensionPointAfterStatusChange: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.afterStatusChange"
  - : The extension point name dw.order.return.afterStatusChange.


---

### extensionPointChangeStatus

- extensionPointChangeStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.changeStatus"
  - : The extension point name dw.order.return.changeStatus.


---

### extensionPointCreateReturn

- extensionPointCreateReturn: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.createReturn"
  - : The extension point name dw.order.return.createReturn.


---

### extensionPointNotifyStatusChange

- extensionPointNotifyStatusChange: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.return.notifyStatusChange"
  - : The extension point name dw.order.return.notifyStatusChange.


---

## Method Details

### addReturnItem(Return, ReturnItemWO)
- addReturnItem(retrn: [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), inputData: ReturnItemWO): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The hook provides customization in the process of assigning the returned
      amount, quantity etc. Here it is possible to refund differently based on
      the return reason code for example. Also one could correct the inventory
      based on the return information. Utilize
      [ReturnCaseItem.createReturnItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md#createreturnitemstring) to create a new
      [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md).


    **Parameters:**
    - retrn - the return for which an return item should be created
    - returnCaseItemID - the return case item ID
    - inputData - the return item

    **Returns:**
    - 
      - Status.OK return item is successfully added
      - Status.ERROR return item addition failed.



---

### afterStatusChange(Return)
- afterStatusChange(retrn: [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called after method [changeStatus(Return, ReturnWO)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#changestatusreturn-returnwo) returns
      Status.OK. The call is made in a separate database transaction allowing
      the script implementation to make an independent remote call if desired.


    **Parameters:**
    - retrn - the return
    - fromStatus - status from which was changed. The new status can be accessed             from retrn directly

    **Returns:**
    - 
      - Status.OK status successful
      - Status.ERROR on failure



---

### changeStatus(Return, ReturnWO)
- changeStatus(retrn: [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), inputData: ReturnWO): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Responsible to change the status of a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md): the custom
      script is responsible for setting the new status using
      [Return.setStatus(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#setstatusstring).
      
      
      
      The invoice handling should be implemented here using
      [Return.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring) or
      [ReturnCase.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring). For example create an
      [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) for a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) moving to status
      [Return.STATUS_COMPLETED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#status_completed).


    **Parameters:**
    - retrn - the return which status should change
    - inputData - the data in which the new status is included

    **Returns:**
    - 
      - Status.OK status successfully changed
      - Status.ERROR          status not changed.



---

### createReturn(ReturnWO)
- createReturn(inputData: ReturnWO): [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)
  - : This hook is responsible for creating a new [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md),
      based on a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md). 2 basic workflows are supported:
      
      - On-the-fly return: create the parent [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)using  [Order.createReturnCase(String, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createreturncasestring-boolean).
      - Return-merchandise-authorization (RMA) workflow: resolve an existing  [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)using  [Order.getReturnCase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getreturncasestring).
      
      In both cases use [this  method](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createreturnstring) to create the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) based on the inputData.
      
      
      Additional functionality like creating history entry, handling the return
      fees or the shipping cost credit can be implemented in the hook after the
      [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) is created.


    **Parameters:**
    - inputData - the return

    **Returns:**
    - the created return


---

### notifyStatusChange(Return)
- notifyStatusChange(retrn: [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called after method [changeStatus(Return, ReturnWO)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#changestatusreturn-returnwo) returns
      Status.OK (and after method [afterStatusChange(Return)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md#afterstatuschangereturn))
      to inform of a successful status change. The call is made outside any
      database transaction. This is the best hook in which to send customer
      notifications as the status change has already been successfully written
      to the database


    **Parameters:**
    - retrn - the return
    - fromStatus - status from which was changed. The new status can be accessed             from retrn directly

    **Returns:**
    - 
      - Status.OK status successful
      - Status.ERROR on failure



---

<!-- prettier-ignore-end -->

<!-- document id=c5ec7866516914f48bb6fff01576d15202f3c73979e81aa7a8adfd0f7245d3c7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ReturnItem.md -->

<!-- prettier-ignore-start -->
# Class ReturnItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md)
      - [dw.order.ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)

An item of a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), created using [Return.createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createitemstring).
Represents a physically returned order line item. Please refer to the documentation of [ReturnHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md)
for further information.


When the related Return were set to status COMPLETED, only the the custom attributes of the return item can be changed.


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Property Summary

| Property | Description |
| --- | --- |
| [basePrice](#baseprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Price of a single unit before discount application. |
| [note](#note): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Return the note for this return item. |
| [parentItem](#parentitem): [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md) | Returns null or the parent item. |
| [reasonCode](#reasoncode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the reason code for return item. |
| [returnCaseItem](#returncaseitem): [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) `(read-only)` | Returns the return case item related to this item. |
| [returnNumber](#returnnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The mandatory returnNumber of the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) to which this item belongs. |
| [returnedQuantity](#returnedquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | The [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) returned. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addTaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#addtaxitemdecimal-taxgroup)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)) | Create a new [tax-item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md) and add to this item. |
| [applyPriceRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#applypriceratedecimal-decimal-boolean)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Apply a rate of (factor / divisor) to the prices in this item, with the option to half round up or half round down to the  nearest cent if necessary. |
| [getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#getbaseprice)() | Price of a single unit before discount application. |
| [getNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#getnote)() | Return the note for this return item. |
| [getParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#getparentitem)() | Returns null or the parent item. |
| [getReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#getreasoncode)() | Returns the reason code for return item. |
| [getReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#getreturncaseitem)() | Returns the return case item related to this item. |
| [getReturnNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#getreturnnumber)() | The mandatory returnNumber of the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) to which this item belongs. |
| [getReturnedQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#getreturnedquantity)() | The [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) returned. |
| [setNote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#setnotestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets a note for this return item. |
| [setParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#setparentitemreturnitem)([ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)) | Set a parent item. |
| [setReasonCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#setreasoncodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the reason code. |
| [setReturnedQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#setreturnedquantityquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Set the [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) returned. |
| [setTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#settaxbasismoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Set the tax-basis price for this item. |
| [setTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#settaxitemscollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Set the tax-items for this item. |

### Methods inherited from class AbstractItem

[getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice), [getItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getitemid), [getLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getlineitem), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice), [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitem), [getOrderItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitemid), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis), [getTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxitems)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### basePrice
- basePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Price of a single unit before discount application.


---

### note
- note: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the note for this return item.


---

### parentItem
- parentItem: [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)
  - : Returns null or the parent item.


---

### reasonCode
- reasonCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code for return item. The list of reason codes can be updated
      by updating meta-data for ReturnItem.



---

### returnCaseItem
- returnCaseItem: [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md) `(read-only)`
  - : Returns the return case item related to this item. Should never return null.


---

### returnNumber
- returnNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The mandatory returnNumber of the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) to which this item belongs.


---

### returnedQuantity
- returnedQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : The [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) returned. This may return an N/A quantity.


---

## Method Details

### addTaxItem(Decimal, TaxGroup)
- addTaxItem(amount: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), taxGroup: [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)): [TaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md)
  - : Create a new [tax-item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md) and add to this item.

    **Parameters:**
    - amount - amount to assign to the tax-item
    - taxGroup - the [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md) to which the item belongs

    **Returns:**
    - the new tax-item


---

### applyPriceRate(Decimal, Decimal, Boolean)
- applyPriceRate(factor: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), divisor: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), roundUp: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Apply a rate of (factor / divisor) to the prices in this item, with the option to half round up or half round down to the
      nearest cent if necessary.
      
      _Examples_:
      
      | TaxBasis before | factor | divisor | roundup | Calculation | TaxBasis after |
      | --- |--- |--- |--- |--- |--- |
      | $10.00 | 1 | 2 | true | 10\*1/2= | $5.00 |
      | $10.00 | 9 | 10 | true | 10\*9/10= | $9.00 |
      | $10.00 | 1 | 3 | true | 10\*1/3=3.3333= | $3.33 |
      |  $2.47 | 1 | 2 | true | 2.47\*1/2=1.235= | $1.24 |
      |  $2.47 | 1 | 2 | false | 2.47\*1/2=1.235= | $1.23 |
      
      
      _Which prices are updated?_:
      
      The rate described above is applied to tax-basis and tax then the net-price and gross-price are recalculated by adding / subtracting
      depending on whether the order is based on net price.
      
      _Example (order based on net price)_
      
      New TaxBasis:$10.00, Tax:$1.00, NetPrice=TaxBasis=$10.00, GrossPrice=TaxBasis+Tax=$11.00
      
      _Example (order based on gross price)_
      
      New TaxBasis:$10.00, Tax:$1.00, NetPrice=TaxBasis-tax=$9.00, GrossPrice=TaxBasis=$10.00


    **Parameters:**
    - factor - factor used to calculate rate
    - divisor - divisor used to calculate rate
    - roundUp - whether to round up or down on 0.5

    **See Also:**
    - [AbstractItem.getTaxBasis()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis)
    - [AbstractItem.getTax()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax)
    - [AbstractItem.getNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice)
    - [AbstractItem.getGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice)
    - [TaxMgr.getTaxationPolicy()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#gettaxationpolicy)


---

### getBasePrice()
- getBasePrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Price of a single unit before discount application.

    **Returns:**
    - Price of a single unit before discount application.


---

### getNote()
- getNote(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the note for this return item.

    **Returns:**
    - the note or `null`


---

### getParentItem()
- getParentItem(): [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)
  - : Returns null or the parent item.

    **Returns:**
    - null or the parent item.


---

### getReasonCode()
- getReasonCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the reason code for return item. The list of reason codes can be updated
      by updating meta-data for ReturnItem.


    **Returns:**
    - the return reason code


---

### getReturnCaseItem()
- getReturnCaseItem(): [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)
  - : Returns the return case item related to this item. Should never return null.

    **Returns:**
    - the return case item related to this item


---

### getReturnNumber()
- getReturnNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The mandatory returnNumber of the [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md) to which this item belongs.

    **Returns:**
    - the returnNumber of the Return to which this item belongs


---

### getReturnedQuantity()
- getReturnedQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : The [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) returned. This may return an N/A quantity.

    **Returns:**
    - the quantity returned, may be N/A


---

### setNote(String)
- setNote(note: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets a note for this return item.

    **Parameters:**
    - note - the note for this return item to set


---

### setParentItem(ReturnItem)
- setParentItem(parentItem: [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)): void
  - : Set a parent item. The parent item must belong to the same
      [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md). An infinite parent-child loop is disallowed
      as is a parent-child depth greater than 10. Setting a parent item
      indicates a dependency of the child item on the parent item, and can be
      used to form a parallel structure to that accessed using
      [ProductLineItem.getParent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getparent).


    **Parameters:**
    - parentItem - The parent item, null is allowed


---

### setReasonCode(String)
- setReasonCode(reasonCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the reason code. The list of reason codes can be updated by updating meta-data for ReturnItem.

    **Parameters:**
    - reasonCode - the reason code to set


---

### setReturnedQuantity(Quantity)
- setReturnedQuantity(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): void
  - : Set the [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) returned. Passing null results in an exception being thrown.
      The quantity must be higher than zero and not be higher than the remaining quantity to return.
      
      
      The item prices are recalculated in this method as described in [applyPriceRate(Decimal, Decimal, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#applypriceratedecimal-decimal-boolean)
      with the `quantity` argument as the factor, and ordered quantity as divisor
      and `true` as the roundup parameter.


    **Parameters:**
    - quantity - the quantity returned, null not allowed

    **See Also:**
    - [OrderItem.getReturnedQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md#getreturnedquantity)
    - [ProductLineItem.getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getquantity)


---

### setTaxBasis(Money)
- setTaxBasis(taxBasis: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): void
  - : Set the tax-basis price for this item.

    **Parameters:**
    - taxBasis - the tax basis value.


---

### setTaxItems(Collection)
- setTaxItems(taxItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)): void
  - : Set the tax-items for this item.

    **Parameters:**
    - taxItems - items

    **See Also:**
    - [addTaxItem(Decimal, TaxGroup)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#addtaxitemdecimal-taxgroup)
    - [TaxGroup.create(String, String, String, Decimal)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#createstring-string-string-decimal)


---

<!-- prettier-ignore-end -->

<!-- document id=69aed2922871dd4ee65e36cd7de86bd73654231af7c9373aae603a90e31822f7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceAdyenPaymentIntent.md -->

<!-- prettier-ignore-start -->
# Class SalesforceAdyenPaymentIntent

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforceAdyenPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md)



Salesforce Payments representation of an Adyen payment intent object. See Salesforce Payments documentation for how
to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the identifier of this payment intent. |
| [action](#action): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the payment action for this payment intent. |
| [resultCode](#resultcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Adyen result code for this payment intent. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md#getaction)() | Returns the payment action for this payment intent. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md#getid)() | Returns the identifier of this payment intent. |
| [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md#getpaymentinstrumentbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Returns the payment instrument for this payment intent in the given basket, or `null` if the given  basket has none. |
| [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md#getpaymentinstrumentorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Returns the payment instrument for this payment intent in the given order, or `null` if the given  order has none. |
| [getResultCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md#getresultcode)() | Returns the Adyen result code for this payment intent. |
| [hasAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md#hasaction)() | Returns `true` if this payment intent has an action, or `false` if not. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the identifier of this payment intent.


---

### action
- action: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the payment action for this payment intent.


---

### resultCode
- resultCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Adyen result code for this payment intent.


---

## Method Details

### getAction()
- getAction(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the payment action for this payment intent.

    **Returns:**
    - payment action


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the identifier of this payment intent.

    **Returns:**
    - payment intent identifier


---

### getPaymentInstrument(Basket)
- getPaymentInstrument(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Returns the payment instrument for this payment intent in the given basket, or `null` if the given
      basket has none.


    **Parameters:**
    - basket - basket

    **Returns:**
    - basket payment instrument


---

### getPaymentInstrument(Order)
- getPaymentInstrument(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Returns the payment instrument for this payment intent in the given order, or `null` if the given
      order has none.


    **Parameters:**
    - order - order

    **Returns:**
    - order payment instrument


---

### getResultCode()
- getResultCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Adyen result code for this payment intent.

    **Returns:**
    - Adyen result code


---

### hasAction()
- hasAction(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if this payment intent has an action, or `false` if not.

    **Returns:**
    - `true` if this payment intent has an action


---

<!-- prettier-ignore-end -->

<!-- document id=333e9bd032f321bb59be69203effc92e4172425d672f13f347665fc9a64fd799 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md -->

<!-- prettier-ignore-start -->
# Class SalesforceAdyenSavedPaymentMethod

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforceAdyenSavedPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md)



Salesforce Payments representation of an Adyen saved payment method object. See Salesforce Payments documentation for
how to gain access and configure it for use on your sites.




An Adyen saved payment method contains information about a credential used by a shopper to attempt payment, such as a
payment card or bank account. The available information differs for each type of payment method. It includes only
limited information that can be safely presented to a shopper to remind them what credential they used, and
specifically not complete card, account, or other numbers that could be used to make future payments.



## Constant Summary

| Constant | Description |
| --- | --- |
| [TYPE_BANCONTACT](#type_bancontact): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bancontact" | Represents the Bancontact payment method. |
| [TYPE_CARD](#type_card): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "card" | Represents a credit card type of payment method. |
| [TYPE_IDEAL](#type_ideal): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ideal" | Represents the iDEAL payment method. |
| [TYPE_SEPA_DEBIT](#type_sepa_debit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sepa_debit" | Represents the SEPA Debit payment method. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the identifier of this payment method. |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the brand of this payment method, or `null` if none is available. |
| [expiryMonth](#expirymonth): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the expiry month of the card for this payment method, or `null` if none is available. |
| [expiryYear](#expiryyear): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the expiry year of the card for this payment method, or `null` if none is available. |
| [holderName](#holdername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the cardholder name for this payment method, or `null` if none is available. |
| [last4](#last4): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 digits of the credential for this payment method, or `null` if none is available. |
| [ownerName](#ownername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the back account owner name for this payment method, or `null` if none is available. |
| [type](#type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of this payment method. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#getbrand)() | Returns the brand of this payment method, or `null` if none is available. |
| [getExpiryMonth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#getexpirymonth)() | Returns the expiry month of the card for this payment method, or `null` if none is available. |
| [getExpiryYear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#getexpiryyear)() | Returns the expiry year of the card for this payment method, or `null` if none is available. |
| [getHolderName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#getholdername)() | Returns the cardholder name for this payment method, or `null` if none is available. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#getid)() | Returns the identifier of this payment method. |
| [getLast4](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#getlast4)() | Returns the last 4 digits of the credential for this payment method, or `null` if none is available. |
| [getOwnerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#getownername)() | Returns the back account owner name for this payment method, or `null` if none is available. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#gettype)() | Returns the type of this payment method. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TYPE_BANCONTACT

- TYPE_BANCONTACT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bancontact"
  - : Represents the Bancontact payment method.


---

### TYPE_CARD

- TYPE_CARD: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "card"
  - : Represents a credit card type of payment method.


---

### TYPE_IDEAL

- TYPE_IDEAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ideal"
  - : Represents the iDEAL payment method.


---

### TYPE_SEPA_DEBIT

- TYPE_SEPA_DEBIT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sepa_debit"
  - : Represents the SEPA Debit payment method.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the identifier of this payment method.


---

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the brand of this payment method, or `null` if none is available. Available on
      [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) type methods.



---

### expiryMonth
- expiryMonth: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the expiry month of the card for this payment method, or `null` if none is available.
      Available on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact) type methods.



---

### expiryYear
- expiryYear: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the expiry year of the card for this payment method, or `null` if none is available. Available
      on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact) type methods.



---

### holderName
- holderName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the cardholder name for this payment method, or `null` if none is available. Available on
      [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact)
      type methods.



---

### last4
- last4: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 digits of the credential for this payment method, or `null` if none is available.
      Available on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact) type methods.



---

### ownerName
- ownerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the back account owner name for this payment method, or `null` if none is available. Available
      on [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_sepa_debit) and
      [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_ideal) type method.



---

### type
- type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of this payment method.

    **See Also:**
    - [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact)
    - [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card)
    - [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_ideal)
    - [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_sepa_debit)


---

## Method Details

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the brand of this payment method, or `null` if none is available. Available on
      [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) type methods.


    **Returns:**
    - payment method brand


---

### getExpiryMonth()
- getExpiryMonth(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the expiry month of the card for this payment method, or `null` if none is available.
      Available on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact) type methods.


    **Returns:**
    - payment method credential expiry month


---

### getExpiryYear()
- getExpiryYear(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the expiry year of the card for this payment method, or `null` if none is available. Available
      on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact) type methods.


    **Returns:**
    - payment method credential expiry year


---

### getHolderName()
- getHolderName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the cardholder name for this payment method, or `null` if none is available. Available on
      [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact)
      type methods.


    **Returns:**
    - payment method credential cardholder name


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the identifier of this payment method.

    **Returns:**
    - payment method identifier


---

### getLast4()
- getLast4(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 digits of the credential for this payment method, or `null` if none is available.
      Available on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card) and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact) type methods.


    **Returns:**
    - payment method credential last 4 digits


---

### getOwnerName()
- getOwnerName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the back account owner name for this payment method, or `null` if none is available. Available
      on [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_sepa_debit) and
      [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_ideal) type method.


    **Returns:**
    - payment method credential back account owner name


---

### getType()
- getType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of this payment method.

    **Returns:**
    - payment method type

    **See Also:**
    - [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_bancontact)
    - [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_card)
    - [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_ideal)
    - [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md#type_sepa_debit)


---

<!-- prettier-ignore-end -->

<!-- document id=a0101c74d317fd25735dc8a2d4a05a79ddb94d9c2d54d572f2f425153645f17b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceBancontactPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforceBancontactPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforceBancontactPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceBancontactPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [bankName](#bankname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank name, or `null` if not known. |
| [last4](#last4): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 digits of the account number, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBankName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceBancontactPaymentDetails.md#getbankname)() | Returns the bank name, or `null` if not known. |
| [getLast4](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceBancontactPaymentDetails.md#getlast4)() | Returns the last 4 digits of the account number, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bankName
- bankName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank name, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getBankName()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbankname)


---

### last4
- last4: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 digits of the account number, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getLast4()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getlast4)


---

## Method Details

### getBankName()
- getBankName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank name, or `null` if not known.

    **Returns:**
    - bank name

    **See Also:**
    - [SalesforcePaymentMethod.getBankName()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbankname)


---

### getLast4()
- getLast4(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 digits of the account number, or `null` if not known.

    **Returns:**
    - last 4 digits of the account number

    **See Also:**
    - [SalesforcePaymentMethod.getLast4()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getlast4)


---

<!-- prettier-ignore-end -->

<!-- document id=8dee04a91fb2ded5f612016f30b91bc84cfbf6821947b4ccaaf012b33af914d8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceCardPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforceCardPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforceCardPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceCardPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the card brand, or `null` if not known. |
| [last4](#last4): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 digits of the card number, or `null` if not known. |
| [walletType](#wallettype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of wallet used to make the card payment, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceCardPaymentDetails.md#getbrand)() | Returns the card brand, or `null` if not known. |
| [getLast4](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceCardPaymentDetails.md#getlast4)() | Returns the last 4 digits of the card number, or `null` if not known. |
| [getWalletType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceCardPaymentDetails.md#getwallettype)() | Returns the type of wallet used to make the card payment, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the card brand, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getBrand()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbrand)


---

### last4
- last4: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 digits of the card number, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getLast4()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getlast4)


---

### walletType
- walletType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of wallet used to make the card payment, or `null` if not known.


---

## Method Details

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the card brand, or `null` if not known.

    **Returns:**
    - card brand

    **See Also:**
    - [SalesforcePaymentMethod.getBrand()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbrand)


---

### getLast4()
- getLast4(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 digits of the card number, or `null` if not known.

    **Returns:**
    - last 4 digits of the card number

    **See Also:**
    - [SalesforcePaymentMethod.getLast4()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getlast4)


---

### getWalletType()
- getWalletType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of wallet used to make the card payment, or `null` if not known.

    **Returns:**
    - wallet type


---

<!-- prettier-ignore-end -->

<!-- document id=e3fb256ff11f7efef84b119e1601426a328cd452f9392eaab1d59645a492bcb2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceEpsPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforceEpsPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforceEpsPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceEpsPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [bank](#bank): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank used for the payment, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceEpsPaymentDetails.md#getbank)() | Returns the bank used for the payment, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bank
- bank: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank used for the payment, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getBank()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbank)


---

## Method Details

### getBank()
- getBank(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank used for the payment, or `null` if not known.

    **Returns:**
    - bank

    **See Also:**
    - [SalesforcePaymentMethod.getBank()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbank)


---

<!-- prettier-ignore-end -->

<!-- document id=01d8e16800d2b5d4d09e638f4088601a2d4bc194b29d5458cfcfee35979962f6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceIdealPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforceIdealPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforceIdealPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceIdealPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [bank](#bank): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank used for the payment, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceIdealPaymentDetails.md#getbank)() | Returns the bank used for the payment, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### bank
- bank: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank used for the payment, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getBank()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbank)


---

## Method Details

### getBank()
- getBank(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank used for the payment, or `null` if not known.

    **Returns:**
    - bank

    **See Also:**
    - [SalesforcePaymentMethod.getBank()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbank)


---

<!-- prettier-ignore-end -->

<!-- document id=8eb5c5984fd8fe47e548a36620648aa8ea9c6ac117c604163c70a866074261e8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceKlarnaPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforceKlarnaPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforceKlarnaPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceKlarnaPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_KLARNA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_klarna). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [paymentMethodCategory](#paymentmethodcategory): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the payment method category used for the payment, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getPaymentMethodCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceKlarnaPaymentDetails.md#getpaymentmethodcategory)() | Returns the payment method category used for the payment, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### paymentMethodCategory
- paymentMethodCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the payment method category used for the payment, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getPaymentMethodCategory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getpaymentmethodcategory)


---

## Method Details

### getPaymentMethodCategory()
- getPaymentMethodCategory(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment method category used for the payment, or `null` if not known.

    **Returns:**
    - payment method category

    **See Also:**
    - [SalesforcePaymentMethod.getPaymentMethodCategory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getpaymentmethodcategory)


---

<!-- prettier-ignore-end -->

<!-- document id=75abd0ba61164365ff93aa109eae65cb4d274c6e28f569debd51e4e92d8bbc83 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)



Base class details to a Salesforce Payments payment. See Salesforce Payments documentation for how to gain access and
configure it for use on your sites.




Some payment types like [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card) contain additional details like the card brand, or
the last 4 digits of the card number. Details to those payments will be of a specific subclass of this class like
[SalesforceCardPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceCardPaymentDetails.md). Other payment types have no additional information so their details are
represented by an object of this base type.



## All Known Subclasses
[SalesforceBancontactPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceBancontactPaymentDetails.md), [SalesforceCardPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceCardPaymentDetails.md), [SalesforceEpsPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceEpsPaymentDetails.md), [SalesforceIdealPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceIdealPaymentDetails.md), [SalesforceKlarnaPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceKlarnaPaymentDetails.md), [SalesforcePayPalPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalPaymentDetails.md), [SalesforceSepaDebitPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceSepaDebitPaymentDetails.md), [SalesforceVenmoPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceVenmoPaymentDetails.md)
## Property Summary

| Property | Description |
| --- | --- |
| [type](#type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the payment type. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)() | Returns the payment type. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### type
- type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the payment type.

    **See Also:**
    - [SalesforcePaymentMethod.TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact)
    - [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card)
    - [SalesforcePaymentMethod.TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps)
    - [SalesforcePaymentMethod.TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal)
    - [SalesforcePaymentMethod.TYPE_KLARNA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_klarna)
    - [SalesforcePaymentMethod.TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit)
    - [SalesforcePayPalOrder.TYPE_PAYPAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_paypal)
    - [SalesforcePayPalOrder.TYPE_VENMO](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_venmo)


---

## Method Details

### getType()
- getType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment type.

    **Returns:**
    - payment type

    **See Also:**
    - [SalesforcePaymentMethod.TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact)
    - [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card)
    - [SalesforcePaymentMethod.TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps)
    - [SalesforcePaymentMethod.TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal)
    - [SalesforcePaymentMethod.TYPE_KLARNA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_klarna)
    - [SalesforcePaymentMethod.TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit)
    - [SalesforcePayPalOrder.TYPE_PAYPAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_paypal)
    - [SalesforcePayPalOrder.TYPE_VENMO](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_venmo)


---

<!-- prettier-ignore-end -->

<!-- document id=a0f282c8c261efa6964549253c2f65c6001ffb113fe0f8980cc50e9176633f34 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentIntent.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentIntent

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md)



Salesforce Payments representation of a Stripe payment intent object. See Salesforce Payments documentation for how
to gain access and configure it for use on your sites.




A payment intent is automatically created when a shopper is ready to pay for items in their basket. It becomes
confirmed when the shopper provides information to the payment provider that is acceptable to authorize payment for a
given amount. Once that information has been provided it becomes available as the payment method associated with the
payment intent.



## Constant Summary

| Constant | Description |
| --- | --- |
| [SETUP_FUTURE_USAGE_OFF_SESSION](#setup_future_usage_off_session): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "off_session" | Represents the payment method setup future usage is off session. |
| [SETUP_FUTURE_USAGE_ON_SESSION](#setup_future_usage_on_session): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "on_session" | Represents the payment method setup future usage is on session. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the identifier of this payment intent. |
| [amount](#amount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the amount of this payment intent. |
| [cancelable](#cancelable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if this payment intent has a status which indicates it can be canceled,  or `false` if its status does not indicate it can be canceled. |
| [clientSecret](#clientsecret): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the client secret of this payment intent. |
| [confirmed](#confirmed): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if this payment intent has been confirmed, or `false` if not. |
| [paymentMethod](#paymentmethod): [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md) `(read-only)` | Returns the payment method for this payment intent, or `null` if none has been established. |
| [refundable](#refundable): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if this payment intent has a status and other state which indicate it can be refunded,  or `false` if it cannot be refunded. |
| [setupFutureUsage](#setupfutureusage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns [SETUP_FUTURE_USAGE_OFF_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_off_session) or [SETUP_FUTURE_USAGE_ON_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_on_session) to indicate how the payment  intent can be used in the future or returns `null` if future usage is not set up. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#getamount)() | Returns the amount of this payment intent. |
| [getClientSecret](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#getclientsecret)() | Returns the client secret of this payment intent. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#getid)() | Returns the identifier of this payment intent. |
| [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#getpaymentinstrumentbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Returns the payment instrument for this payment intent in the given basket, or `null` if the given  basket has none. |
| [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#getpaymentinstrumentorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Returns the payment instrument for this payment intent in the given order, or `null` if the given  order has none. |
| [getPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#getpaymentmethod)() | Returns the payment method for this payment intent, or `null` if none has been established. |
| [getSetupFutureUsage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#getsetupfutureusage)() | Returns [SETUP_FUTURE_USAGE_OFF_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_off_session) or [SETUP_FUTURE_USAGE_ON_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_on_session) to indicate how the payment  intent can be used in the future or returns `null` if future usage is not set up. |
| [isCancelable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#iscancelable)() | Returns `true` if this payment intent has a status which indicates it can be canceled,  or `false` if its status does not indicate it can be canceled. |
| [isConfirmed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#isconfirmed)() | Returns `true` if this payment intent has been confirmed, or `false` if not. |
| [isRefundable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#isrefundable)() | Returns `true` if this payment intent has a status and other state which indicate it can be refunded,  or `false` if it cannot be refunded. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### SETUP_FUTURE_USAGE_OFF_SESSION

- SETUP_FUTURE_USAGE_OFF_SESSION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "off_session"
  - : Represents the payment method setup future usage is off session.


---

### SETUP_FUTURE_USAGE_ON_SESSION

- SETUP_FUTURE_USAGE_ON_SESSION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "on_session"
  - : Represents the payment method setup future usage is on session.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the identifier of this payment intent.


---

### amount
- amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the amount of this payment intent.


---

### cancelable
- cancelable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if this payment intent has a status which indicates it can be canceled,
      or `false` if its status does not indicate it can be canceled.



---

### clientSecret
- clientSecret: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the client secret of this payment intent.


---

### confirmed
- confirmed: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if this payment intent has been confirmed, or `false` if not.


---

### paymentMethod
- paymentMethod: [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md) `(read-only)`
  - : Returns the payment method for this payment intent, or `null` if none has been established.


---

### refundable
- refundable: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if this payment intent has a status and other state which indicate it can be refunded,
      or `false` if it cannot be refunded.



---

### setupFutureUsage
- setupFutureUsage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns [SETUP_FUTURE_USAGE_OFF_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_off_session) or [SETUP_FUTURE_USAGE_ON_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_on_session) to indicate how the payment
      intent can be used in the future or returns `null` if future usage is not set up.


    **See Also:**
    - [SalesforcePaymentRequest.setSetupFutureUsage(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setsetupfutureusageboolean)
    - [SETUP_FUTURE_USAGE_OFF_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_off_session)
    - [SETUP_FUTURE_USAGE_ON_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_on_session)


---

## Method Details

### getAmount()
- getAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the amount of this payment intent.

    **Returns:**
    - payment intent amount


---

### getClientSecret()
- getClientSecret(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the client secret of this payment intent.

    **Returns:**
    - payment intent client secret


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the identifier of this payment intent.

    **Returns:**
    - payment intent identifier


---

### getPaymentInstrument(Basket)
- getPaymentInstrument(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Returns the payment instrument for this payment intent in the given basket, or `null` if the given
      basket has none.


    **Parameters:**
    - basket - basket

    **Returns:**
    - basket payment instrument


---

### getPaymentInstrument(Order)
- getPaymentInstrument(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Returns the payment instrument for this payment intent in the given order, or `null` if the given
      order has none.


    **Parameters:**
    - order - order

    **Returns:**
    - order payment instrument


---

### getPaymentMethod()
- getPaymentMethod(): [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)
  - : Returns the payment method for this payment intent, or `null` if none has been established.

    **Returns:**
    - payment method


---

### getSetupFutureUsage()
- getSetupFutureUsage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns [SETUP_FUTURE_USAGE_OFF_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_off_session) or [SETUP_FUTURE_USAGE_ON_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_on_session) to indicate how the payment
      intent can be used in the future or returns `null` if future usage is not set up.


    **Returns:**
    - setup future usage or `null` if future usage is not set up

    **See Also:**
    - [SalesforcePaymentRequest.setSetupFutureUsage(Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setsetupfutureusageboolean)
    - [SETUP_FUTURE_USAGE_OFF_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_off_session)
    - [SETUP_FUTURE_USAGE_ON_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_on_session)


---

### isCancelable()
- isCancelable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if this payment intent has a status which indicates it can be canceled,
      or `false` if its status does not indicate it can be canceled.


    **Returns:**
    - `true` if this payment intent has a status which indicates it can be canceled


---

### isConfirmed()
- isConfirmed(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if this payment intent has been confirmed, or `false` if not.

    **Returns:**
    - `true` if this payment intent has been confirmed


---

### isRefundable()
- isRefundable(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if this payment intent has a status and other state which indicate it can be refunded,
      or `false` if it cannot be refunded.


    **Returns:**
    - `true` if this payment intent has a status and other state which indicate it can be refunded


---

<!-- prettier-ignore-end -->

<!-- document id=5943d4ed03d1604d1deec008e871448111a44b5ada0ced2ea19dd4c0d9db9d14 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentMethod.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentMethod

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)



Salesforce Payments representation of a payment method object. See Salesforce Payments documentation for how
to gain access and configure it for use on your sites.




A payment method contains information about a credential used by a shopper to attempt payment, such as a payment card
or bank account. The available information differs for each type of payment method. It includes only limited
information that can be safely presented to a shopper to remind them what credential they used, and specifically not
complete card, account, or other numbers that could be used to make future payments.



## Constant Summary

| Constant | Description |
| --- | --- |
| [TYPE_AFTERPAY_CLEARPAY](#type_afterpay_clearpay): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpay_clearpay" | Represents the Afterpay Clearpay payment method. |
| [TYPE_BANCONTACT](#type_bancontact): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bancontact" | Represents the Bancontact payment method. |
| [TYPE_CARD](#type_card): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "card" | Represents a credit card type of payment method. |
| [TYPE_EPS](#type_eps): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "eps" | Represents the EPS (Electronic Payment Standard) payment method. |
| [TYPE_IDEAL](#type_ideal): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ideal" | Represents the iDEAL payment method. |
| [TYPE_KLARNA](#type_klarna): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "klarna" | Represents the Klarna payment method. |
| [TYPE_SEPA_DEBIT](#type_sepa_debit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sepa_debit" | Represents the SEPA Debit payment method. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the identifier of this payment method. |
| [bank](#bank): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank of this payment method, or `null` if none is available. |
| [bankCode](#bankcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank code of this payment method, or `null` if none is available. |
| [bankName](#bankname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank name of this payment method, or `null` if none is available. |
| [branchCode](#branchcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the bank branch code of this payment method, or `null` if none is available. |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the brand of this payment method, or `null` if none is available. |
| [country](#country): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the country of this payment method, or `null` if none is available. |
| [last4](#last4): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 digits of the credential for this payment method, or `null` if none is available. |
| [paymentMethodCategory](#paymentmethodcategory): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the payment method category of this payment method, or `null` if none is available. |
| [type](#type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of this payment method. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbank)() | Returns the bank of this payment method, or `null` if none is available. |
| [getBankCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbankcode)() | Returns the bank code of this payment method, or `null` if none is available. |
| [getBankName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbankname)() | Returns the bank name of this payment method, or `null` if none is available. |
| [getBranchCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbranchcode)() | Returns the bank branch code of this payment method, or `null` if none is available. |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getbrand)() | Returns the brand of this payment method, or `null` if none is available. |
| [getCountry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getcountry)() | Returns the country of this payment method, or `null` if none is available. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getid)() | Returns the identifier of this payment method. |
| [getLast4](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getlast4)() | Returns the last 4 digits of the credential for this payment method, or `null` if none is available. |
| [getPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getpaymentdetailsorderpaymentinstrument)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)) | Returns the details to the Salesforce Payments payment for this payment method, using the given payment  instrument. |
| [getPaymentMethodCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getpaymentmethodcategory)() | Returns the payment method category of this payment method, or `null` if none is available. |
| [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#gettype)() | Returns the type of this payment method. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TYPE_AFTERPAY_CLEARPAY

- TYPE_AFTERPAY_CLEARPAY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpay_clearpay"
  - : Represents the Afterpay Clearpay payment method.


---

### TYPE_BANCONTACT

- TYPE_BANCONTACT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bancontact"
  - : Represents the Bancontact payment method.


---

### TYPE_CARD

- TYPE_CARD: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "card"
  - : Represents a credit card type of payment method.


---

### TYPE_EPS

- TYPE_EPS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "eps"
  - : Represents the EPS (Electronic Payment Standard) payment method.


---

### TYPE_IDEAL

- TYPE_IDEAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ideal"
  - : Represents the iDEAL payment method.


---

### TYPE_KLARNA

- TYPE_KLARNA: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "klarna"
  - : Represents the Klarna payment method.


---

### TYPE_SEPA_DEBIT

- TYPE_SEPA_DEBIT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sepa_debit"
  - : Represents the SEPA Debit payment method.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the identifier of this payment method.


---

### bank
- bank: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank of this payment method, or `null` if none is available. Available on
      [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal) and [TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps) type methods.



---

### bankCode
- bankCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank code of this payment method, or `null` if none is available. Available on
      [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit) and [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact) type methods.



---

### bankName
- bankName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank name of this payment method, or `null` if none is available. Available on
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact) type methods.



---

### branchCode
- branchCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the bank branch code of this payment method, or `null` if none is available. Available on
      [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit) type methods.



---

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the brand of this payment method, or `null` if none is available. Available on
      [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card) type methods.



---

### country
- country: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the country of this payment method, or `null` if none is available. Available on
      [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit) type methods.



---

### last4
- last4: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 digits of the credential for this payment method, or `null` if none is available.
      Available on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card), [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit), and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact) type methods.



---

### paymentMethodCategory
- paymentMethodCategory: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the payment method category of this payment method, or `null` if none is available. Available
      on [TYPE_KLARNA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_klarna) type methods.



---

### type
- type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of this payment method.

    **See Also:**
    - [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact)
    - [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card)
    - [TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps)
    - [TYPE_AFTERPAY_CLEARPAY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_afterpay_clearpay)
    - [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal)
    - [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit)


---

## Method Details

### getBank()
- getBank(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank of this payment method, or `null` if none is available. Available on
      [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal) and [TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps) type methods.


    **Returns:**
    - payment method bank


---

### getBankCode()
- getBankCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank code of this payment method, or `null` if none is available. Available on
      [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit) and [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact) type methods.


    **Returns:**
    - payment method bank code


---

### getBankName()
- getBankName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank name of this payment method, or `null` if none is available. Available on
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact) type methods.


    **Returns:**
    - payment method bank name


---

### getBranchCode()
- getBranchCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the bank branch code of this payment method, or `null` if none is available. Available on
      [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit) type methods.


    **Returns:**
    - payment method bank branch code


---

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the brand of this payment method, or `null` if none is available. Available on
      [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card) type methods.


    **Returns:**
    - payment method brand


---

### getCountry()
- getCountry(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the country of this payment method, or `null` if none is available. Available on
      [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit) type methods.


    **Returns:**
    - payment method country


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the identifier of this payment method.

    **Returns:**
    - payment method identifier


---

### getLast4()
- getLast4(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 digits of the credential for this payment method, or `null` if none is available.
      Available on [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card), [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit), and
      [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact) type methods.


    **Returns:**
    - payment method credential last 4 digits


---

### getPaymentDetails(OrderPaymentInstrument)
- getPaymentDetails(paymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)): [SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
  - : Returns the details to the Salesforce Payments payment for this payment method, using the given payment
      instrument.


    **Parameters:**
    - paymentInstrument - payment instrument

    **Returns:**
    - The payment details


---

### getPaymentMethodCategory()
- getPaymentMethodCategory(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payment method category of this payment method, or `null` if none is available. Available
      on [TYPE_KLARNA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_klarna) type methods.


    **Returns:**
    - payment method category


---

### getType()
- getType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of this payment method.

    **Returns:**
    - payment method type

    **See Also:**
    - [TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact)
    - [TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card)
    - [TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps)
    - [TYPE_AFTERPAY_CLEARPAY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_afterpay_clearpay)
    - [TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal)
    - [TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit)


---

<!-- prettier-ignore-end -->

<!-- document id=5fb775ab37f5b2e6fec55aca3e76af39bb3904c45f9cdb5b361899252476e0e2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentRequest.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentRequest

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md)



Salesforce Payments request for a shopper to make payment. See Salesforce Payments documentation for how to
gain access and configure it for use on your sites.




A request is required to render payment methods and/or express checkout buttons using `<ispayment>`
or `<isbuynow>`. You can call methods on the payment request to configure which payment methods
and/or express checkout buttons may be presented, and customize their visual presentation.




When used with `<isbuynow>` you must provide the necessary data to prepare the shopper basket to buy
the product, and the necessary payment request options for the browser payment app.



## Constant Summary

| Constant | Description |
| --- | --- |
| [ELEMENT_AFTERPAY_CLEARPAY_MESSAGE](#element_afterpay_clearpay_message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpayClearpayMessage" | Element for the Stripe Afterpay/Clearpay message `"afterpayClearpayMessage"`. |
| [ELEMENT_CARD_CVC](#element_card_cvc): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cardCvc" | Element for the Stripe credit card CVC field `"cardCvc"`. |
| [ELEMENT_CARD_EXPIRY](#element_card_expiry): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cardExpiry" | Element for the Stripe credit card expiration date field `"cardExpiry"`. |
| [ELEMENT_CARD_NUMBER](#element_card_number): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cardNumber" | Element for the Stripe credit card number field `"cardNumber"`. |
| [ELEMENT_EPS_BANK](#element_eps_bank): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "epsBank" | Element for the Stripe EPS bank selection field `"epsBank"`. |
| [ELEMENT_IBAN](#element_iban): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "iban" | Element for the Stripe IBAN field `"iban"`. |
| [ELEMENT_IDEAL_BANK](#element_ideal_bank): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "idealBank" | Element for the Stripe iDEAL bank selection field `"idealBank"`. |
| [ELEMENT_PAYMENT_REQUEST_BUTTON](#element_payment_request_button): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paymentRequestButton" | Element for the Stripe payment request button `"paymentRequestButton"`. |
| [ELEMENT_TYPE_AFTERPAY_CLEARPAY](#element_type_afterpay_clearpay): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpay_clearpay" | Element type name for Afterpay. |
| [ELEMENT_TYPE_AFTERPAY_CLEARPAY_MESSAGE](#element_type_afterpay_clearpay_message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpayclearpaymessage" | Element type name for Afterpay/Clearpay message. |
| [ELEMENT_TYPE_APPLEPAY](#element_type_applepay): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "applepay" | Element type name for Apple Pay payment request buttons. |
| [ELEMENT_TYPE_BANCONTACT](#element_type_bancontact): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bancontact" | Element type name for Bancontact. |
| [ELEMENT_TYPE_CARD](#element_type_card): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "card" | Element type name for credit cards. |
| [ELEMENT_TYPE_EPS](#element_type_eps): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "eps" | Element type name for EPS. |
| [ELEMENT_TYPE_IDEAL](#element_type_ideal): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ideal" | Element type name for iDEAL. |
| [ELEMENT_TYPE_PAYMENTREQUEST](#element_type_paymentrequest): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paymentrequest" | Element type name for other payment request buttons besides Apple Pay, like Google Pay. |
| [ELEMENT_TYPE_PAYPAL](#element_type_paypal): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypal" | Element type name for PayPal in multi-step checkout. |
| [ELEMENT_TYPE_PAYPAL_EXPRESS](#element_type_paypal_express): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypalexpress" | Element type name for PayPal in express checkout. |
| [ELEMENT_TYPE_PAYPAL_MESSAGE](#element_type_paypal_message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypalmessage" | Element type name for the PayPal messages component. |
| [ELEMENT_TYPE_SEPA_DEBIT](#element_type_sepa_debit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sepa_debit" | Element type name for SEPA debit. |
| [ELEMENT_TYPE_VENMO](#element_type_venmo): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "venmo" | Element type name for Venmo in multi-step checkout. |
| [ELEMENT_TYPE_VENMO_EXPRESS](#element_type_venmo_express): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "venmoexpress" | Element type name for Venmo in express checkout. |
| [PAYPAL_SHIPPING_PREFERENCE_GET_FROM_FILE](#paypal_shipping_preference_get_from_file): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GET_FROM_FILE" | PayPal application context `shipping_preference` value `"GET_FROM_FILE"`, to use the  customer-provided shipping address on the PayPal site. |
| [PAYPAL_SHIPPING_PREFERENCE_NO_SHIPPING](#paypal_shipping_preference_no_shipping): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_SHIPPING" | PayPal application context `shipping_preference` value `"NO_SHIPPING"`, to redact the  shipping address from the PayPal site. |
| [PAYPAL_SHIPPING_PREFERENCE_SET_PROVIDED_ADDRESS](#paypal_shipping_preference_set_provided_address): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SET_PROVIDED_ADDRESS" | PayPal application context `shipping_preference` value `"SET_PROVIDED_ADDRESS"`, to use the  merchant-provided address. |
| [PAYPAL_USER_ACTION_CONTINUE](#paypal_user_action_continue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONTINUE" | PayPal application context `user_action` value `"CONTINUE"`. |
| [PAYPAL_USER_ACTION_PAY_NOW](#paypal_user_action_pay_now): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PAY_NOW" | PayPal application context `user_action` value `"PAY_NOW"`. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the identifier of this payment request. |
| [basketData](#basketdata): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Returns a JS object containing the data used to prepare the shopper basket when a Buy Now button is tapped. |
| [billingDetails](#billingdetails): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Returns a JS object containing the billing details to use when a Stripe PaymentMethod is created. |
| [cardCaptureAutomatic](#cardcaptureautomatic): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns `true` if the credit card payment should be automatically captured at the time of the sale, or  `false` if the credit card payment should be captured later. |
| [exclude](#exclude): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) `(read-only)` | <p>  Returns a set containing the element types to be explicitly excluded from mounted components. |
| [include](#include): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) `(read-only)` | <p>  Returns a set containing the specific element types to include in mounted components. |
| [selector](#selector): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the DOM element selector where to mount payment methods and/or express checkout buttons. |
| [setupFutureUsage](#setupfutureusage): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns `true` if the payment method should be always saved for future use off session, or  `false` if the payment method should be only saved for future use on session when appropriate. |
| [statementDescriptor](#statementdescriptor): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the complete description that appears on your customers' statements for payments made by this request, or  `null` if the default statement descriptor for your account will be used. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SalesforcePaymentRequest](#salesforcepaymentrequeststring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a payment request using the given identifiers. |

## Method Summary

| Method | Description |
| --- | --- |
| [addExclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#addexcludestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Adds the given element type to explicitly exclude from mounted components. |
| [addInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#addincludestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Adds the given element type to include in mounted components. |
| static [calculatePaymentRequestOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#calculatepaymentrequestoptionsbasket-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Returns a JS object containing the payment request options to use when a Pay Now button is tapped, in the  appropriate format for use in client side JavaScript, with data calculated from the given basket. |
| static [format](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#formatobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Returns a JS object containing the payment request options to use when a Buy Now button is tapped, in the  appropriate format for use in client side JavaScript. |
| [getBasketData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getbasketdata)() | Returns a JS object containing the data used to prepare the shopper basket when a Buy Now button is tapped. |
| [getBillingDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getbillingdetails)() | Returns a JS object containing the billing details to use when a Stripe PaymentMethod is created. |
| [getCardCaptureAutomatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getcardcaptureautomatic)() | Returns `true` if the credit card payment should be automatically captured at the time of the sale, or  `false` if the credit card payment should be captured later. |
| [getExclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getexclude)() | <p>  Returns a set containing the element types to be explicitly excluded from mounted components. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getid)() | Returns the identifier of this payment request. |
| [getInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getinclude)() | <p>  Returns a set containing the specific element types to include in mounted components. |
| [getSelector](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getselector)() | Returns the DOM element selector where to mount payment methods and/or express checkout buttons. |
| [getSetupFutureUsage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getsetupfutureusage)() | Returns `true` if the payment method should be always saved for future use off session, or  `false` if the payment method should be only saved for future use on session when appropriate. |
| [getStatementDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getstatementdescriptor)() | Returns the complete description that appears on your customers' statements for payments made by this request, or  `null` if the default statement descriptor for your account will be used. |
| [setBasketData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setbasketdataobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Sets the data used to prepare the shopper basket when a Buy Now button is tapped. |
| [setBillingDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setbillingdetailsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the billing details to use when a Stripe PaymentMethod is created. |
| [setCardCaptureAutomatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setcardcaptureautomaticboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets if the credit card payment should be automatically captured at the time of the sale. |
| [setOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setoptionsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Sets the payment request options to use when a Buy Now button is tapped. |
| [setPayPalButtonsOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setpaypalbuttonsoptionsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the the options to pass into the `paypal.Buttons` call. |
| [setPayPalShippingPreference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setpaypalshippingpreferencestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the PayPal order application context `shipping_preference` value. |
| [setPayPalUserAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setpaypaluseractionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the PayPal order application context `user_action` value. |
| [setReturnController](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setreturncontrollerstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the controller to which to redirect when the shopper returns from a 3rd party payment website. |
| [setSavePaymentMethodEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setsavepaymentmethodenabledboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets if mounted components may provide a control for the shopper to save their payment method for later use. |
| [setSetupFutureUsage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setsetupfutureusageboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets if the payment method should be always saved for future use off session. |
| [setStatementDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setstatementdescriptorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the complete description that appears on your customers' statements for payments made by this request. |
| [setStripeCreateElementOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setstripecreateelementoptionsstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the the options to pass into the Stripe `elements.create` call for the given element type. |
| [setStripeElementsOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setstripeelementsoptionsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the the options to pass into the `stripe.elements` call. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ELEMENT_AFTERPAY_CLEARPAY_MESSAGE

- ELEMENT_AFTERPAY_CLEARPAY_MESSAGE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpayClearpayMessage"
  - : Element for the Stripe Afterpay/Clearpay message `"afterpayClearpayMessage"`.


---

### ELEMENT_CARD_CVC

- ELEMENT_CARD_CVC: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cardCvc"
  - : Element for the Stripe credit card CVC field `"cardCvc"`.


---

### ELEMENT_CARD_EXPIRY

- ELEMENT_CARD_EXPIRY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cardExpiry"
  - : Element for the Stripe credit card expiration date field `"cardExpiry"`.


---

### ELEMENT_CARD_NUMBER

- ELEMENT_CARD_NUMBER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "cardNumber"
  - : Element for the Stripe credit card number field `"cardNumber"`.


---

### ELEMENT_EPS_BANK

- ELEMENT_EPS_BANK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "epsBank"
  - : Element for the Stripe EPS bank selection field `"epsBank"`.


---

### ELEMENT_IBAN

- ELEMENT_IBAN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "iban"
  - : Element for the Stripe IBAN field `"iban"`.


---

### ELEMENT_IDEAL_BANK

- ELEMENT_IDEAL_BANK: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "idealBank"
  - : Element for the Stripe iDEAL bank selection field `"idealBank"`.


---

### ELEMENT_PAYMENT_REQUEST_BUTTON

- ELEMENT_PAYMENT_REQUEST_BUTTON: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paymentRequestButton"
  - : Element for the Stripe payment request button `"paymentRequestButton"`.


---

### ELEMENT_TYPE_AFTERPAY_CLEARPAY

- ELEMENT_TYPE_AFTERPAY_CLEARPAY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpay_clearpay"
  - : Element type name for Afterpay.


---

### ELEMENT_TYPE_AFTERPAY_CLEARPAY_MESSAGE

- ELEMENT_TYPE_AFTERPAY_CLEARPAY_MESSAGE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "afterpayclearpaymessage"
  - : Element type name for Afterpay/Clearpay message.


---

### ELEMENT_TYPE_APPLEPAY

- ELEMENT_TYPE_APPLEPAY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "applepay"
  - : Element type name for Apple Pay payment request buttons.


---

### ELEMENT_TYPE_BANCONTACT

- ELEMENT_TYPE_BANCONTACT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "bancontact"
  - : Element type name for Bancontact.


---

### ELEMENT_TYPE_CARD

- ELEMENT_TYPE_CARD: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "card"
  - : Element type name for credit cards.


---

### ELEMENT_TYPE_EPS

- ELEMENT_TYPE_EPS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "eps"
  - : Element type name for EPS.


---

### ELEMENT_TYPE_IDEAL

- ELEMENT_TYPE_IDEAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ideal"
  - : Element type name for iDEAL.


---

### ELEMENT_TYPE_PAYMENTREQUEST

- ELEMENT_TYPE_PAYMENTREQUEST: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paymentrequest"
  - : Element type name for other payment request buttons besides Apple Pay, like Google Pay.


---

### ELEMENT_TYPE_PAYPAL

- ELEMENT_TYPE_PAYPAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypal"
  - : Element type name for PayPal in multi-step checkout.


---

### ELEMENT_TYPE_PAYPAL_EXPRESS

- ELEMENT_TYPE_PAYPAL_EXPRESS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypalexpress"
  - : Element type name for PayPal in express checkout.


---

### ELEMENT_TYPE_PAYPAL_MESSAGE

- ELEMENT_TYPE_PAYPAL_MESSAGE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypalmessage"
  - : Element type name for the PayPal messages component.


---

### ELEMENT_TYPE_SEPA_DEBIT

- ELEMENT_TYPE_SEPA_DEBIT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sepa_debit"
  - : Element type name for SEPA debit.


---

### ELEMENT_TYPE_VENMO

- ELEMENT_TYPE_VENMO: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "venmo"
  - : Element type name for Venmo in multi-step checkout.


---

### ELEMENT_TYPE_VENMO_EXPRESS

- ELEMENT_TYPE_VENMO_EXPRESS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "venmoexpress"
  - : Element type name for Venmo in express checkout.


---

### PAYPAL_SHIPPING_PREFERENCE_GET_FROM_FILE

- PAYPAL_SHIPPING_PREFERENCE_GET_FROM_FILE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "GET_FROM_FILE"
  - : PayPal application context `shipping_preference` value `"GET_FROM_FILE"`, to use the
      customer-provided shipping address on the PayPal site.



---

### PAYPAL_SHIPPING_PREFERENCE_NO_SHIPPING

- PAYPAL_SHIPPING_PREFERENCE_NO_SHIPPING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NO_SHIPPING"
  - : PayPal application context `shipping_preference` value `"NO_SHIPPING"`, to redact the
      shipping address from the PayPal site. Recommended for digital goods.



---

### PAYPAL_SHIPPING_PREFERENCE_SET_PROVIDED_ADDRESS

- PAYPAL_SHIPPING_PREFERENCE_SET_PROVIDED_ADDRESS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SET_PROVIDED_ADDRESS"
  - : PayPal application context `shipping_preference` value `"SET_PROVIDED_ADDRESS"`, to use the
      merchant-provided address. The customer cannot change this address on the PayPal site.



---

### PAYPAL_USER_ACTION_CONTINUE

- PAYPAL_USER_ACTION_CONTINUE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONTINUE"
  - : PayPal application context `user_action` value `"CONTINUE"`. Use this option when the final
      amount is not known when the checkout flow is initiated and you want to redirect the customer to the merchant
      page without processing the payment.



---

### PAYPAL_USER_ACTION_PAY_NOW

- PAYPAL_USER_ACTION_PAY_NOW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PAY_NOW"
  - : PayPal application context `user_action` value `"PAY_NOW"`. Use this option when the final
      amount is known when the checkout is initiated and you want to process the payment immediately when the customer
      clicks Pay Now.



---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the identifier of this payment request.


---

### basketData
- basketData: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns a JS object containing the data used to prepare the shopper basket when a Buy Now button is tapped.

    **See Also:**
    - [setBasketData(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setbasketdataobject)


---

### billingDetails
- billingDetails: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns a JS object containing the billing details to use when a Stripe PaymentMethod is created.

    **See Also:**
    - [setBillingDetails(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setbillingdetailsobject)


---

### cardCaptureAutomatic
- cardCaptureAutomatic: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the credit card payment should be automatically captured at the time of the sale, or
      `false` if the credit card payment should be captured later.



---

### exclude
- exclude: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) `(read-only)`
  - : 
      
      Returns a set containing the element types to be explicitly excluded from mounted components. See the element
      type constants in this class for the full list of supported element types.
      
      
      
      
      Note: if an element type is both explicitly included and excluded, it will not be presented.


    **See Also:**
    - [addExclude(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#addexcludestring)


---

### include
- include: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) `(read-only)`
  - : 
      
      Returns a set containing the specific element types to include in mounted components. If the set is
      empty then all applicable and enabled element types will be included by default. See the element type constants
      in this class for the full list of supported element types.
      
      
      
      
      Note: if an element type is both explicitly included and excluded, it will not be presented.


    **See Also:**
    - [addInclude(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#addincludestring)


---

### selector
- selector: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the DOM element selector where to mount payment methods and/or express checkout buttons.


---

### setupFutureUsage
- setupFutureUsage: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the payment method should be always saved for future use off session, or
      `false` if the payment method should be only saved for future use on session when appropriate.



---

### statementDescriptor
- statementDescriptor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the complete description that appears on your customers' statements for payments made by this request, or
      `null` if the default statement descriptor for your account will be used.



---

## Constructor Details

### SalesforcePaymentRequest(String, String)
- SalesforcePaymentRequest(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), selector: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a payment request using the given identifiers.

    **Parameters:**
    - id - identifier for payment request
    - selector - DOM element selector where to mount payment methods and/or express checkout buttons

    **Throws:**
    - Exception - if id or selector is null


---

## Method Details

### addExclude(String)
- addExclude(elementType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : 
      
      Adds the given element type to explicitly exclude from mounted components. It is not necessary to explicitly
      exclude element types that are not enabled for the site, or are not applicable for the current shopper and/or
      their basket. See the element type constants in this class for the full list of supported element types.
      
      
      
      
      Note: if an element type is both explicitly included and excluded, it will not be presented.


    **Parameters:**
    - elementType - element type

    **See Also:**
    - [getExclude()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getexclude)


---

### addInclude(String)
- addInclude(elementType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : 
      
      Adds the given element type to include in mounted components. Call this method to include only a specific list of
      element types to be presented when applicable and enabled for the site. See the element type constants in this
      class for the full list of supported element types.
      
      
      
      
      Note: if an element type is both explicitly included and excluded, it will not be presented.


    **Parameters:**
    - elementType - element type

    **See Also:**
    - [getInclude()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getinclude)


---

### calculatePaymentRequestOptions(Basket, Object)
- static calculatePaymentRequestOptions(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), options: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : 
      
      Returns a JS object containing the payment request options to use when a Pay Now button is tapped, in the
      appropriate format for use in client side JavaScript, with data calculated from the given basket. This method is
      provided as a convenience to calculate updated payment request options when the shopper basket has changed. Data
      in the given `options` object like `total`, `displayItems`, and
      `shippingOptions` will be replaced in the returned object by values recalculated from the given
      `basket` and applicable shipping methods.
      
      
      
      
      The following example shows the resulting output for a basket and sample options.
      
      
      
      ```
      SalesforcePaymentRequest.calculatePaymentRequestOptions(basket, {
         requestPayerName: true,
         requestPayerEmail: true,
         requestPayerPhone: false,
         requestShipping: true
      });
      ```
      
      
      
      returns
      
      
      
      ```
      {
         currency: 'gbp',
         total: {
             label: 'Total',
             amount: '2644'
         },
         displayItems: [{
             label: 'Subtotal',
             amount: '1919'
         }, {
             label: 'Tax',
             amount: '126'
         }, {
             label: 'Ground',
             amount: '599'
         }],
         requestPayerName: true,
         requestPayerEmail: true,
         requestPayerPhone: false,
         requestShipping: true,
         shippingOptions: [{
             id: 'GBP001',
             label: 'Ground',
             detail: 'Order received within 7-10 business days',
             amount: '599'
         },{
             id: 'GBP002',
             label: 'Express',
             detail: 'Order received within 2-4 business days',
             amount: '999'
         }]
      }
      ```


    **Parameters:**
    - options - JS object containing payment request options in B2C Commerce API standard format

    **Returns:**
    - JS object containing equivalent payment request options in Stripe JS API format


---

### format(Object)
- static format(options: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : 
      
      Returns a JS object containing the payment request options to use when a Buy Now button is tapped, in the
      appropriate format for use in client side JavaScript. This method is provided as a convenience to adjust values
      in B2C Commerce API standard formats to their equivalents as expected by Stripe JS APIs. The following example
      shows options set in B2C Commerce API format, and the resulting output.
      
      
      
      ```
      SalesforcePaymentRequest.format({
         currency: 'GBP',
         total: {
             label: 'Total',
             amount: '26.44'
         },
         displayItems: [{
             label: 'Subtotal',
             amount: '19.19'
         }, {
             label: 'Tax',
             amount: '1.26'
         }, {
             label: 'Ground',
             amount: '5.99'
         }],
         requestPayerPhone: false,
         shippingOptions: [{
             id: 'GBP001',
             label: 'Ground',
             detail: 'Order received within 7-10 business days',
             amount: '5.99'
         }]
      });
      ```
      
      
      
      returns
      
      
      
      ```
      {
         currency: 'gbp',
         total: {
             label: 'Total',
             amount: '2644'
         },
         displayItems: [{
             label: 'Subtotal',
             amount: '1919'
         }, {
             label: 'Tax',
             amount: '126'
         }, {
             label: 'Ground',
             amount: '599'
         }],
         requestPayerPhone: false,
         shippingOptions: [{
             id: 'GBP001',
             label: 'Ground',
             detail: 'Order received within 7-10 business days',
             amount: '599'
         }]
      }
      ```


    **Parameters:**
    - options - JS object containing payment request options in B2C Commerce API standard format

    **Returns:**
    - JS object containing equivalent payment request options in Stripe JS API format


---

### getBasketData()
- getBasketData(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns a JS object containing the data used to prepare the shopper basket when a Buy Now button is tapped.

    **Returns:**
    - JS object containing the basket data

    **See Also:**
    - [setBasketData(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setbasketdataobject)


---

### getBillingDetails()
- getBillingDetails(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns a JS object containing the billing details to use when a Stripe PaymentMethod is created.

    **Returns:**
    - JS object containing the billing details

    **See Also:**
    - [setBillingDetails(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setbillingdetailsobject)


---

### getCardCaptureAutomatic()
- getCardCaptureAutomatic(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the credit card payment should be automatically captured at the time of the sale, or
      `false` if the credit card payment should be captured later.


    **Returns:**
    - `true` if the credit card payment should be automatically captured at the time of the sale,
      `false` if the credit card payment should be captured later.



---

### getExclude()
- getExclude(): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : 
      
      Returns a set containing the element types to be explicitly excluded from mounted components. See the element
      type constants in this class for the full list of supported element types.
      
      
      
      
      Note: if an element type is both explicitly included and excluded, it will not be presented.


    **Returns:**
    - set of element types

    **See Also:**
    - [addExclude(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#addexcludestring)


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the identifier of this payment request.

    **Returns:**
    - payment request identifier


---

### getInclude()
- getInclude(): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : 
      
      Returns a set containing the specific element types to include in mounted components. If the set is
      empty then all applicable and enabled element types will be included by default. See the element type constants
      in this class for the full list of supported element types.
      
      
      
      
      Note: if an element type is both explicitly included and excluded, it will not be presented.


    **Returns:**
    - set of element types

    **See Also:**
    - [addInclude(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#addincludestring)


---

### getSelector()
- getSelector(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the DOM element selector where to mount payment methods and/or express checkout buttons.

    **Returns:**
    - DOM element selector


---

### getSetupFutureUsage()
- getSetupFutureUsage(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the payment method should be always saved for future use off session, or
      `false` if the payment method should be only saved for future use on session when appropriate.


    **Returns:**
    - `true` if the payment method should be always saved for future use off session,
      `false` if the payment method should be only saved for future use on session when appropriate.



---

### getStatementDescriptor()
- getStatementDescriptor(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the complete description that appears on your customers' statements for payments made by this request, or
      `null` if the default statement descriptor for your account will be used.


    **Returns:**
    - statement descriptor for payments made by this request, or `null` if the account default will
              be used



---

### setBasketData(Object)
- setBasketData(basketData: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : 
      
      Sets the data used to prepare the shopper basket when a Buy Now button is tapped. For convenience this method
      accepts a JS object to set all of the following properties at once:
      
      
      
      - `sku`- SKU of the product to add exclusively to the basket (required)
      - `quantity`- integer quantity of the product, default is 1
      - `shippingMethod`- ID of the shipping method to set on the shipment, default is the site default  shipping method for the basket currency
      - `options`- JS array containing one JS object per selected product option, default is no selected options  
        - `id`- product option ID
        - `valueId`- product option value ID
      
      
      
      The following example shows how to set all of the supported basket data.
      
      
      
        ```
        request.setBasketData({
           sku: 'tv-pdp-6010fdM',
           quantity: 1,
           shippingMethod: '001',
           options: [{
               id: 'tvWarranty',
               valueId: '000'
           }]
        });
        ```


    **Parameters:**
    - basketData - JS object containing the basket data

    **See Also:**
    - [getBasketData()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#getbasketdata)


---

### setBillingDetails(Object)
- setBillingDetails(billingDetails: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the billing details to use when a Stripe PaymentMethod is created. For convenience this method accepts a
      JS object to set all details at once. The following example shows how to set details including address.
      
      
      
      ```
      request.setBillingDetails({
         address: {
             city: 'Wien',
             country: 'AT',
             line1: 'Opernring 2',
             postal_code: '1010'
         },
         email: 'jhummel@salesforce.com',
         name: 'Johann Hummel'
      });
      ```
      
      
      
      For more information on the available billing details see the Stripe create PaymentMethod API
      documentation.


    **Parameters:**
    - billingDetails - JS object containing the billing details


---

### setCardCaptureAutomatic(Boolean)
- setCardCaptureAutomatic(cardCaptureAutomatic: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets if the credit card payment should be automatically captured at the time of the sale.

    **Parameters:**
    - cardCaptureAutomatic - `true` if the credit card payment should be automatically captured at the time of the sale,             or `false` if the credit card payment should be captured later.


---

### setOptions(Object)
- setOptions(options: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : 
      
      Sets the payment request options to use when a Buy Now button is tapped. For convenience this method accepts a
      JS object to set all options at once. The following example shows how to set options including currency,
      labels, and amounts, in B2C Commerce API format.
      
      
      
      ```
      request.setOptions({
         currency: 'GBP',
         total: {
             label: 'Total',
             amount: '26.44'
         },
         displayItems: [{
             label: 'Subtotal',
             amount: '19.19'
         }, {
             label: 'Tax',
             amount: '1.26'
         }, {
             label: 'Ground',
             amount: '5.99'
         }],
         requestPayerPhone: false,
         shippingOptions: [{
             id: 'GBP001',
             label: 'Ground',
             detail: 'Order received within 7-10 business days',
             amount: '5.99'
         }]
      });
      ```
      
      
      
      The `total` option must match the total that will result from preparing the shopper basket using the
      data provided to [setBasketData(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#setbasketdataobject) in this request. The `id` of each JS object in the
      `shippingOptions` array must equal the ID of the corresponding site shipping method that the shopper
      may select in the browser payment app.
      
      
      
      
      For more information on the available payment request options see the Stripe Payment Request object API
      documentation.
      
      
      
      
      Note: The Stripe Payment Request `country` option will be set automatically to the country of the
      Salesforce Payments account associated with the Commerce Cloud instance and is not included here.


    **Parameters:**
    - options - JS object containing the payment request options


---

### setPayPalButtonsOptions(Object)
- setPayPalButtonsOptions(options: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the the options to pass into the `paypal.Buttons` call. For more information see the PayPal
      Buttons API documentation.


    **Parameters:**
    - options - JS object containing the options


---

### setPayPalShippingPreference(String)
- setPayPalShippingPreference(shippingPreference: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the PayPal order application context `shipping_preference` value. For more information see the
      PayPal Orders API documentation.


    **Parameters:**
    - shippingPreference - constant indicating the shipping preference

    **See Also:**
    - [PAYPAL_SHIPPING_PREFERENCE_GET_FROM_FILE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#paypal_shipping_preference_get_from_file)
    - [PAYPAL_SHIPPING_PREFERENCE_NO_SHIPPING](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#paypal_shipping_preference_no_shipping)
    - [PAYPAL_SHIPPING_PREFERENCE_SET_PROVIDED_ADDRESS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#paypal_shipping_preference_set_provided_address)


---

### setPayPalUserAction(String)
- setPayPalUserAction(userAction: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the PayPal order application context `user_action` value. For more information see the PayPal
      Orders API documentation.


    **Parameters:**
    - userAction - constant indicating the user action

    **See Also:**
    - [PAYPAL_USER_ACTION_CONTINUE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#paypal_user_action_continue)
    - [PAYPAL_USER_ACTION_PAY_NOW](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#paypal_user_action_pay_now)


---

### setReturnController(String)
- setReturnController(returnController: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the controller to which to redirect when the shopper returns from a 3rd party payment website. Default is
      the controller for the current page.


    **Parameters:**
    - returnController - return controller, such as `"Cart-Show"`


---

### setSavePaymentMethodEnabled(Boolean)
- setSavePaymentMethodEnabled(savePaymentMethodEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets if mounted components may provide a control for the shopper to save their payment method for later use. When
      set to `false` no control will be provided. When set to `true` a control may be provided,
      if applicable for the shopper and presented payment method, but is not guaranteed.


    **Parameters:**
    - savePaymentMethodEnabled - if mounted components may provide a control for the shopper to save their payment             method


---

### setSetupFutureUsage(Boolean)
- setSetupFutureUsage(setupFutureUsage: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets if the payment method should be always saved for future use off session.

    **Parameters:**
    - setupFutureUsage - `true` if the payment method should be always saved for future use off             session, or `false` if the payment method should be only saved for future use on session             when appropriate.


---

### setStatementDescriptor(String)
- setStatementDescriptor(statementDescriptor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the complete description that appears on your customers' statements for payments made by this request. Set
      this to `null` to use the default statement descriptor for your account.


    **Parameters:**
    - statementDescriptor - statement descriptor for payments made by this request, or `null` to use             the account default


---

### setStripeCreateElementOptions(String, Object)
- setStripeCreateElementOptions(element: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), options: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the the options to pass into the Stripe `elements.create` call for the given element type. For
      more information see the Stripe Elements API documentation.


    **Parameters:**
    - element - name of the Stripe element whose creation to configure
    - options - JS object containing the options

    **See Also:**
    - [ELEMENT_AFTERPAY_CLEARPAY_MESSAGE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_afterpay_clearpay_message)
    - [ELEMENT_CARD_CVC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_card_cvc)
    - [ELEMENT_CARD_EXPIRY](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_card_expiry)
    - [ELEMENT_CARD_NUMBER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_card_number)
    - [ELEMENT_EPS_BANK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_eps_bank)
    - [ELEMENT_IBAN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_iban)
    - [ELEMENT_IDEAL_BANK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_ideal_bank)
    - [ELEMENT_PAYMENT_REQUEST_BUTTON](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md#element_payment_request_button)


---

### setStripeElementsOptions(Object)
- setStripeElementsOptions(options: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the the options to pass into the `stripe.elements` call. For more information see the Stripe
      Elements API documentation.


    **Parameters:**
    - options - JS object containing the options


---

<!-- prettier-ignore-end -->

<!-- document id=0122943b8c466d23bec096ba98a2e8614896bdc6f00f936be1b7e52e467db034 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentsHooks.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentsHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentsHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsHooks.md)



This interface represents all script hooks that can be registered to customize the Salesforce Payments functionality.
See Salesforce Payments documentation for how to gain access and configure it for use on your sites.




It contains the extension points (hook names), and the functions that are called by each extension point. A function
must be defined inside a JavaScript source and must be exported. The script with the exported hook function must be
located inside a site cartridge. Inside the site cartridge a 'package.json' file with a 'hooks' entry must exist.




```
"hooks": "./hooks.json"
```



The hooks entry links to a json file, relative to the 'package.json' file. This file lists all registered hooks
inside the hooks property:




```
"hooks": [
     {"name": "dw.extensions.payments.asyncPaymentSucceeded", "script": "./payments.js"},
     {"name": "dw.extensions.payments.adyenNotification", "script": "./payments.js"},
     {"name": "dw.extensions.payments.adyenFailureNotification", "script": "./payments.js"},
     {"name": "dw.extensions.payments.sendOrderConfirmationEmail", "script": "./emails.js"}
]
```



A hook entry has a 'name' and a 'script' property.



- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the exported hook function.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointAdyenFailureNotification](#extensionpointadyenfailurenotification): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.adyenFailureNotification" | The extension point name dw.extensions.payments.adyenFailureNotification. |
| [extensionPointAdyenNotification](#extensionpointadyennotification): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.adyenNotification" | The extension point name dw.extensions.payments.adyenNotification. |
| [extensionPointAsyncPaymentSucceeded](#extensionpointasyncpaymentsucceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.asyncPaymentSucceeded" | The extension point name dw.extensions.payments.asyncPaymentSucceeded. |
| [extensionPointSendOrderConfirmationEmail](#extensionpointsendorderconfirmationemail): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.sendOrderConfirmationEmail" | The extension point name dw.extensions.payments.sendOrderConfirmationEmail. |
| [extensionPointStripePaymentEvent](#extensionpointstripepaymentevent): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.stripePaymentEvent" | The extension point name dw.extensions.payments.stripePaymentEvent. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [adyenFailureNotification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsHooks.md#adyenfailurenotificationorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Called when an Adyen webhook notification with a failed payment is received for the given order. |
| [adyenNotification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsHooks.md#adyennotificationorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Called when an Adyen webhook notification is received for the given order. |
| [asyncPaymentSucceeded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsHooks.md#asyncpaymentsucceededorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Called when asynchronous payment succeeded for the given order. |
| [sendOrderConfirmationEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsHooks.md#sendorderconfirmationemailorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Called to send order confirmation email after successful payment processing. |
| [stripePaymentEvent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsHooks.md#stripepaymenteventstring-order)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Called when a Stripe payment event is received for the given order. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointAdyenFailureNotification

- extensionPointAdyenFailureNotification: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.adyenFailureNotification"
  - : The extension point name dw.extensions.payments.adyenFailureNotification.


---

### extensionPointAdyenNotification

- extensionPointAdyenNotification: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.adyenNotification"
  - : The extension point name dw.extensions.payments.adyenNotification.


---

### extensionPointAsyncPaymentSucceeded

- extensionPointAsyncPaymentSucceeded: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.asyncPaymentSucceeded"
  - : The extension point name dw.extensions.payments.asyncPaymentSucceeded.


---

### extensionPointSendOrderConfirmationEmail

- extensionPointSendOrderConfirmationEmail: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.sendOrderConfirmationEmail"
  - : The extension point name dw.extensions.payments.sendOrderConfirmationEmail.


---

### extensionPointStripePaymentEvent

- extensionPointStripePaymentEvent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.extensions.payments.stripePaymentEvent"
  - : The extension point name dw.extensions.payments.stripePaymentEvent.


---

## Method Details

### adyenFailureNotification(Order)
- adyenFailureNotification(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called when an Adyen webhook notification with a failed payment is received for the given order.

    **Parameters:**
    - order - the order for which the failure notification was received

    **Returns:**
    - a non-null result ends the hook execution, and is ignored


---

### adyenNotification(Order)
- adyenNotification(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called when an Adyen webhook notification is received for the given order.

    **Parameters:**
    - order - the order for which the notification was received

    **Returns:**
    - a non-null result ends the hook execution, and is ignored


---

### asyncPaymentSucceeded(Order)
- asyncPaymentSucceeded(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called when asynchronous payment succeeded for the given order.

    **Parameters:**
    - order - the order whose asynchronous payment succeeded

    **Returns:**
    - a non-null result ends the hook execution, and is ignored


---

### sendOrderConfirmationEmail(Order)
- sendOrderConfirmationEmail(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called to send order confirmation email after successful payment processing.

    **Parameters:**
    - order - the order for which to send confirmation email

    **Returns:**
    - a non-null result ends the hook execution


---

### stripePaymentEvent(String, Order)
- stripePaymentEvent(eventName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called when a Stripe payment event is received for the given order.

    **Parameters:**
    - eventName - the Stripe event name, such as `"payment_intent.succeeded"`
    - order - the order for which the event was received

    **Returns:**
    - a non-null result ends the hook execution, and is ignored


---

<!-- prettier-ignore-end -->

<!-- document id=f746ff6e39f4b34e5f63cb98ccf53377d7edf9841b2b7cea2cda96ec733eba2b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentsMerchantAccount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentsMerchantAccount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md)

Contains information about a merchant account configured for use with Salesforce Payments. See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [accountId](#accountid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the Salesforce Payments merchant account. |
| [accountType](#accounttype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of the Salesforce Payments merchant account and environment, such as `"STRIPE_TEST"`  or `"ADYEN_LIVE"`. |
| [config](#config): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns an opaque configuration object containing gateway-specific information. |
| [live](#live): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if the account takes live payments, or `false` if it takes test payments. |
| [vendor](#vendor): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the gateway vendor, such as `"Stripe"` or `"Adyen"`. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAccountId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md#getaccountid)() | Returns the ID of the Salesforce Payments merchant account. |
| [getAccountType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md#getaccounttype)() | Returns the type of the Salesforce Payments merchant account and environment, such as `"STRIPE_TEST"`  or `"ADYEN_LIVE"`. |
| [getConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md#getconfig)() | Returns an opaque configuration object containing gateway-specific information. |
| [getVendor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md#getvendor)() | Returns the name of the gateway vendor, such as `"Stripe"` or `"Adyen"`. |
| [isLive](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md#islive)() | Returns `true` if the account takes live payments, or `false` if it takes test payments. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### accountId
- accountId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the Salesforce Payments merchant account.

    **See Also:**
    - [PaymentTransaction.setAccountID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setaccountidstring)
    - [PaymentTransaction.getAccountID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getaccountid)


---

### accountType
- accountType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of the Salesforce Payments merchant account and environment, such as `"STRIPE_TEST"`
      or `"ADYEN_LIVE"`.


    **See Also:**
    - [PaymentTransaction.setAccountType(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setaccounttypestring)
    - [PaymentTransaction.getAccountType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getaccounttype)


---

### config
- config: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns an opaque configuration object containing gateway-specific information. Do not depend on the structure or
      contents of this object as they may change at any time.



---

### live
- live: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if the account takes live payments, or `false` if it takes test payments.


---

### vendor
- vendor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the gateway vendor, such as `"Stripe"` or `"Adyen"`.


---

## Method Details

### getAccountId()
- getAccountId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the Salesforce Payments merchant account.

    **Returns:**
    - merchant account ID

    **See Also:**
    - [PaymentTransaction.setAccountID(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setaccountidstring)
    - [PaymentTransaction.getAccountID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getaccountid)


---

### getAccountType()
- getAccountType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the Salesforce Payments merchant account and environment, such as `"STRIPE_TEST"`
      or `"ADYEN_LIVE"`.


    **Returns:**
    - merchant account type

    **See Also:**
    - [PaymentTransaction.setAccountType(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#setaccounttypestring)
    - [PaymentTransaction.getAccountType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md#getaccounttype)


---

### getConfig()
- getConfig(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns an opaque configuration object containing gateway-specific information. Do not depend on the structure or
      contents of this object as they may change at any time.


    **Returns:**
    - opaque configuration object


---

### getVendor()
- getVendor(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the gateway vendor, such as `"Stripe"` or `"Adyen"`.

    **Returns:**
    - gateway vendor name


---

### isLive()
- isLive(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if the account takes live payments, or `false` if it takes test payments.

    **Returns:**
    - `true` if the account takes live payments


---

<!-- prettier-ignore-end -->

<!-- document id=d5448b8173828fced17c3ec6fe44743f28133743c128af12ccee30d8c1a27c3a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentsMerchantAccountPaymentMethod.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentsMerchantAccountPaymentMethod

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentsMerchantAccountPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccountPaymentMethod.md)

Contains information about a payment method to be presented to a payer, as configured for a Salesforce Payments
merchant account. See Salesforce Payments documentation for how to gain access and configure it for use on your
sites.



## Property Summary

| Property | Description |
| --- | --- |
| [merchantAccount](#merchantaccount): [SalesforcePaymentsMerchantAccount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md) `(read-only)` | Returns the merchant account configured for this payment method. |
| [paymentMethodType](#paymentmethodtype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the constant indicating the type of payment method to be presented, such as  [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card). |
| [paymentModes](#paymentmodes): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection containing the payment modes for which this payment method is to be presented, such as  `"Express"`. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getMerchantAccount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccountPaymentMethod.md#getmerchantaccount)() | Returns the merchant account configured for this payment method. |
| [getPaymentMethodType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccountPaymentMethod.md#getpaymentmethodtype)() | Returns the constant indicating the type of payment method to be presented, such as  [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card). |
| [getPaymentModes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccountPaymentMethod.md#getpaymentmodes)() | Returns a collection containing the payment modes for which this payment method is to be presented, such as  `"Express"`. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### merchantAccount
- merchantAccount: [SalesforcePaymentsMerchantAccount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md) `(read-only)`
  - : Returns the merchant account configured for this payment method.


---

### paymentMethodType
- paymentMethodType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the constant indicating the type of payment method to be presented, such as
      [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card).



---

### paymentModes
- paymentModes: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection containing the payment modes for which this payment method is to be presented, such as
      `"Express"`.



---

## Method Details

### getMerchantAccount()
- getMerchantAccount(): [SalesforcePaymentsMerchantAccount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md)
  - : Returns the merchant account configured for this payment method.

    **Returns:**
    - merchant account


---

### getPaymentMethodType()
- getPaymentMethodType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the constant indicating the type of payment method to be presented, such as
      [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card).


    **Returns:**
    - payment method type


---

### getPaymentModes()
- getPaymentModes(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing the payment modes for which this payment method is to be presented, such as
      `"Express"`.


    **Returns:**
    - collection of payment modes


---

<!-- prettier-ignore-end -->

<!-- document id=3c8306113938b3847d616975f33b239dea9fb3ad5ea94b21654e7f551271c01f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentsMgr.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentsMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentsMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md)

Contains functionality for use with Salesforce Payments. See Salesforce Payments documentation for how to gain access
and configure it for use on your sites.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CANCELLATION_REASON_ABANDONED](#cancellation_reason_abandoned): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "abandoned" | Cancellation reason indicating customer abandoned payment. |
| [CANCELLATION_REASON_DUPLICATE](#cancellation_reason_duplicate): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "duplicate" | Cancellation reason indicating payment intent was a duplicate. |
| [CANCELLATION_REASON_FRAUDULENT](#cancellation_reason_fraudulent): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "fraudulent" | Cancellation reason indicating payment was fraudulent. |
| [CANCELLATION_REASON_REQUESTED_BY_CUSTOMER](#cancellation_reason_requested_by_customer): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "requested_by_customer" | Cancellation reason indicating customer action or request. |
| [REFUND_REASON_DUPLICATE](#refund_reason_duplicate): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "duplicate" | Refund reason indicating payment intent was a duplicate. |
| [REFUND_REASON_FRAUDULENT](#refund_reason_fraudulent): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "fraudulent" | Refund reason indicating payment was fraudulent. |
| [REFUND_REASON_REQUESTED_BY_CUSTOMER](#refund_reason_requested_by_customer): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "requested_by_customer" | Refund reason indicating customer action or request. |

## Property Summary

| Property | Description |
| --- | --- |
| [paymentsSiteConfig](#paymentssiteconfig): [SalesforcePaymentsSiteConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md) `(read-only)` | Returns a payments site configuration object for the current site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| ~~static [attachPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#attachpaymentmethodsalesforcepaymentmethod-customer)([SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md), [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md))~~ | Attaches the given payment method to the given customer. |
| static [authorizePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#authorizepaypalordersalesforcepaypalorder)([SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)) | Authorizes the given PayPal order. |
| static [cancelPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#cancelpaymentintentsalesforcepaymentintent-object)([SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Cancels the given payment intent. |
| static [captureAdyenPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#captureadyenpaymentorderpaymentinstrument-money-object)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Captures funds for the given order payment instrument. |
| static [capturePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#capturepaypalordersalesforcepaypalorder)([SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)) | Captures funds for the given PayPal order. |
| static [capturePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#capturepaymentintentsalesforcepaymentintent-money)([SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Captures funds for the given payment intent. |
| static [confirmPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#confirmpaymentintentorder-salesforcepaymentmethod-object)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Confirms a new payment intent using the given payment method, and associates it with the given order. |
| static [createAdyenPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#createadyenpaymentintentorder-shipment-string-money-boolean-object-object)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Creates an Adyen payment intent using the given information, and associates it with the given order. |
| static [createPayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#createpaypalorderbasket-shipment-string-money-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Creates a PayPal order using the given information, and associates it with the given basket. |
| static [createPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#createpaymentintentbasket-shipment-string-money-boolean-object)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Creates a payment intent using the given information, and associates it with the given basket. |
| ~~static [detachPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#detachpaymentmethodsalesforcepaymentmethod)([SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md))~~ | Detaches the given payment method from its associated customer. |
| static [getAdyenSavedPaymentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getadyensavedpaymentmethodscustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Returns a collection containing the Adyen payment methods saved to be presented to the given customer for reuse  in checkouts. |
| ~~static [getAttachedPaymentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getattachedpaymentmethodscustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md))~~ | Returns a collection containing the payment methods attached to the given customer. |
| static [getOffSessionPaymentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getoffsessionpaymentmethodscustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Returns a collection containing the payment methods for the given customer set up for future off session reuse. |
| static [getPayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getpaypalorderbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Returns the PayPal order for the given basket, or `null` if the given basket has none. |
| static [getPayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getpaypalorderorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Returns the PayPal order for the given order, or `null` if the given order has none. |
| static [getPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getpaymentdetailsorderpaymentinstrument)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)) | Returns the details to the Salesforce Payments payment associated with the given payment instrument, or  `null` if the given payment instrument has none. |
| static [getPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getpaymentintentbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Returns the payment intent for the given basket, or `null` if the given basket has none. |
| static [getPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getpaymentintentorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Returns the payment intent for the given order, or `null` if the given order has none. |
| static [getPaymentsSiteConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getpaymentssiteconfig)() | Returns a payments site configuration object for the current site. |
| static [getPaymentsZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getpaymentszonestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a payments zone object for the passed in payments zone ID. |
| static [getSavedPaymentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getsavedpaymentmethodscustomer)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)) | Returns a collection containing the payment methods saved to be presented to the given customer for reuse in  checkouts. |
| static [handleAdyenAdditionalDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#handleadyenadditionaldetailsorder-string-object)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Handles the given additional Adyen payment details and associates the associated payment with the given order, if  applicable. |
| static [onCustomerRegistered](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#oncustomerregisteredorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Handles the account registration of the shopper who placed the given order. |
| static [refundAdyenPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#refundadyenpaymentorderpaymentinstrument-money-object)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Refunds previously captured funds for the given order payment instrument. |
| static [refundPayPalOrderCapture](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#refundpaypalordercapturesalesforcepaypalorder)([SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)) | Refunds the capture for the given PayPal order. |
| static [refundPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#refundpaymentintentsalesforcepaymentintent-money-object)([SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Refunds previously captured funds for the given payment intent. |
| static [removeAdyenSavedPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#removeadyensavedpaymentmethodsalesforceadyensavedpaymentmethod)([SalesforceAdyenSavedPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md)) | Deletes an Adyen saved payment method. |
| static [removeSavedPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#removesavedpaymentmethodsalesforcepaymentmethod)([SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)) | Removes the given saved payment method so that it is no longer presented to the given customer for reuse in  checkouts. |
| static [resolvePaymentsZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#resolvepaymentszoneobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Resolves and returns the payments zone object for the passed in payments zone properties object. |
| static [reverseAdyenPayment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#reverseadyenpaymentorderpaymentinstrument-object)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Reverses the authorisation for the given order payment instrument. |
| static [savePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#savepaymentmethodcustomer-salesforcepaymentmethod)([Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)) | Saves the given payment method to be presented to the given customer for reuse in subsequent checkouts. |
| static [setPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#setpaymentdetailsorderpaymentinstrument-salesforcepaymentdetails)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), [SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)) | Sets the details to the Salesforce Payments payment associated with the given payment instrument. |
| static [updatePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#updatepaymentintentsalesforcepaymentintent-shipment-money-string-object)([SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Updates the provided information in the given payment intent. |
| static [voidPayPalOrderAuthorization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#voidpaypalorderauthorizationsalesforcepaypalorder)([SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)) | Voids the authorization for the given PayPal order. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CANCELLATION_REASON_ABANDONED

- CANCELLATION_REASON_ABANDONED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "abandoned"
  - : Cancellation reason indicating customer abandoned payment.


---

### CANCELLATION_REASON_DUPLICATE

- CANCELLATION_REASON_DUPLICATE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "duplicate"
  - : Cancellation reason indicating payment intent was a duplicate.


---

### CANCELLATION_REASON_FRAUDULENT

- CANCELLATION_REASON_FRAUDULENT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "fraudulent"
  - : Cancellation reason indicating payment was fraudulent.


---

### CANCELLATION_REASON_REQUESTED_BY_CUSTOMER

- CANCELLATION_REASON_REQUESTED_BY_CUSTOMER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "requested_by_customer"
  - : Cancellation reason indicating customer action or request.


---

### REFUND_REASON_DUPLICATE

- REFUND_REASON_DUPLICATE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "duplicate"
  - : Refund reason indicating payment intent was a duplicate.


---

### REFUND_REASON_FRAUDULENT

- REFUND_REASON_FRAUDULENT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "fraudulent"
  - : Refund reason indicating payment was fraudulent.


---

### REFUND_REASON_REQUESTED_BY_CUSTOMER

- REFUND_REASON_REQUESTED_BY_CUSTOMER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "requested_by_customer"
  - : Refund reason indicating customer action or request.


---

## Property Details

### paymentsSiteConfig
- paymentsSiteConfig: [SalesforcePaymentsSiteConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md) `(read-only)`
  - : Returns a payments site configuration object for the current site.


---

## Method Details

### attachPaymentMethod(SalesforcePaymentMethod, Customer)
- ~~static attachPaymentMethod(paymentMethod: [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md), customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): void~~
  - : Attaches the given payment method to the given customer. Use this method to attach a payment method of type
      [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card) to a shopper who registers as a customer after placing an order, and
      has affirmatively elected to save their card as part of the registration process. This method will throw an error
      if passed incompatible payment method and/or customer objects.


    **Parameters:**
    - paymentMethod - payment method to attach to customer
    - customer - customer whose payment method to attach

    **Throws:**
    - Exception - if there was an error attaching the payment method to the customer

    **Deprecated:**
**warning:** use [onCustomerRegistered(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#oncustomerregisteredorder) and
            [savePaymentMethod(Customer, SalesforcePaymentMethod)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#savepaymentmethodcustomer-salesforcepaymentmethod)

---

### authorizePayPalOrder(SalesforcePayPalOrder)
- static authorizePayPalOrder(paypalOrder: [SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Authorizes the given PayPal order.
      
      
      The PayPal order must be in a status that supports authorization. See the PayPal documentation for more details.


    **Parameters:**
    - paypalOrder - PayPal order to authorize

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'error'` contains the PayPal error information, if it
              is available in the response.


    **Throws:**
    - Exception - if there was an error authorizing the PayPal order


---

### cancelPaymentIntent(SalesforcePaymentIntent, Object)
- static cancelPaymentIntent(paymentIntent: [SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), paymentIntentProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Cancels the given payment intent. If a payment authorization has been made for the payment intent, the
      authorization is removed.
      
      
      The payment intent must be in a status that supports cancel. See the Stripe documentation for more details.
      
      
      
      
      The following Payment Intent property is supported:
      
      - `cancellationReason`- optional payment intent cancellation reason  


    **Parameters:**
    - paymentIntent - payment intent to capture
    - paymentIntentProperties - additional properties to pass to the create Payment Intent API

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'paymentintent'` contains the payment intent, if it is
              available in the Stripe response. Status detail `'error'` contains the Stripe error
              information, if it is available in the response.


    **Throws:**
    - Exception - if there was an error canceling the payment intent

    **See Also:**
    - [CANCELLATION_REASON_ABANDONED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#cancellation_reason_abandoned)
    - [CANCELLATION_REASON_DUPLICATE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#cancellation_reason_duplicate)
    - [CANCELLATION_REASON_FRAUDULENT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#cancellation_reason_fraudulent)
    - [CANCELLATION_REASON_REQUESTED_BY_CUSTOMER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#cancellation_reason_requested_by_customer)


---

### captureAdyenPayment(OrderPaymentInstrument, Money, Object)
- static captureAdyenPayment(orderPaymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), transactionProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Captures funds for the given order payment instrument.
      
      
      The order payment instrument must be in a state that supports capture.
      
      
      
      
      The `amount` must be less than or equal to the amount available to capture.
      
      
      
      
      The following Transaction properties are supported:
      
      - `reference`- optional reference for the transaction, for example order number  


    **Parameters:**
    - orderPaymentInstrument - payment instrument to capture
    - amount - amount to capture
    - transactionProperties - properties to pass to the capture Adyen Payment API

    **Returns:**
    - Status 'OK' or 'ERROR'.

    **Throws:**
    - Exception - if there was an error capturing the payment instrument


---

### capturePayPalOrder(SalesforcePayPalOrder)
- static capturePayPalOrder(paypalOrder: [SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Captures funds for the given PayPal order.
      
      
      The PayPal order must be in a status that supports capture. See the PayPal documentation for more details.


    **Parameters:**
    - paypalOrder - PayPal order to capture

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'error'` contains the PayPal error information, if it
              is available in the response.


    **Throws:**
    - Exception - if there was an error capturing the PayPal order


---

### capturePaymentIntent(SalesforcePaymentIntent, Money)
- static capturePaymentIntent(paymentIntent: [SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Captures funds for the given payment intent.
      
      
      The payment intent must be in a status that supports capture. See the Stripe documentation for more details.
      
      
      
      
      If `amount` is not specified, the default is the full amount available to capture. If specified, the
      amount must be less than or equal to the amount available to capture.


    **Parameters:**
    - paymentIntent - payment intent to capture
    - amount - optional amount to capture, defaults to amount available to capture

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'error'` contains the Stripe error information, if it
              is available in the response.


    **Throws:**
    - Exception - if there was an error capturing the payment intent


---

### confirmPaymentIntent(Order, SalesforcePaymentMethod, Object)
- static confirmPaymentIntent(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), paymentMethod: [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md), paymentIntentProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Confirms a new payment intent using the given payment method, and associates it with the given order.
      
      
      
      
      The order must be prepared to contain products, shipments, and any other necessary data, and must be calculated
      to reflect the correct total amounts. If the order is not for the same [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) as the given
      payment method, an error is thrown.
      
      
      
      
      The specified payment method must be set up for off session future use or an error is thrown. iDeal and
      Bancontact implement reuse differently than other payment methods, but they can't be reused themselves.
      
      
      
      
      The following Payment Intent properties are supported:
      
      - `statementDescriptor`- optional statement descriptor    - `cardCaptureAutomatic`- optional `true`if the credit card payment should be    automatically captured at the time of the sale, or `false`if the credit card payment should be    captured later    
      
      If `cardCaptureAutomatic`is provided it is used to determine card capture timing, and otherwise the    default card capture timing set for the site is used.    
      
      If `statementDescriptor`is provided it is used as the complete description that appears on your    customers' statements for the payment, and if not a default statement descriptor is used. If a default statement    descriptor is set for the site it is used as the default, and otherwise the default statement descriptor for the    account will apply.    


    **Parameters:**
    - order - order to pay using Salesforce Payments
    - paymentMethod - payment method to use to pay
    - paymentIntentProperties - additional properties to pass to the create Payment Intent API

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'paymentintent'` contains the payment intent, if it is
              available in the Stripe response. Status detail `'error'` contains the Stripe error
              information, if it is available in the response.


    **Throws:**
    - Exception - if the parameter validation failed or there's an error confirming the payment intent


---

### createAdyenPaymentIntent(Order, Shipment, String, Money, Boolean, Object, Object)
- static createAdyenPaymentIntent(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), zoneId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), customerRequired: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), paymentData: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), paymentIntentProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Creates an Adyen payment intent using the given information, and associates it with the given order.
      
      
      
      
      The following Payment Intent properties are supported:
      
      - `type`- required payment method type, such as [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card)  - `cardCaptureAutomatic`- optional `true`if the credit card payment should be    automatically captured at the time of the sale, or `false`if the credit card payment should be    captured later        - `storePaymentMethod`- optional `true`if the payment method should be stored for      future usage, or `false`if not      
      
      If `cardCaptureAutomatic`is provided it is used to determine card capture timing, and otherwise the      default card capture timing set for the site is used.      


    **Parameters:**
    - order - order to checkout and pay using Salesforce Payments
    - shipment - shipment to use for shipping information in the payment intent
    - zoneId - id of the payment zone
    - amount - payment amount
    - customerRequired - `true` if an Adyen shopper reference must be associated with the transaction             and needs to be created if it does not already exist for the given ecom customer or `false`             a shopper reference does not have to be associated with the transaction. A customer is required if             storing a payment method for future usage or using an existing stored payment method.
    - paymentData - Adyen specific payment data passed directly from the client as-is
    - paymentIntentProperties - properties to pass to the create Payment Intent API

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'paymentintent'` contains the payment intent, if it is
              available in the Adyen response. Status detail `'error'` contains the Adyen error information,
              if it is available in the response.



---

### createPayPalOrder(Basket, Shipment, String, Money, Object)
- static createPayPalOrder(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), zoneId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), paypalOrderProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Creates a PayPal order using the given information, and associates it with the given basket.
      
      
      
      
      The following PayPal order properties are supported:
      
      - `fundingSource`- required funding source, such as [SalesforcePayPalOrder.TYPE_PAYPAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_paypal)  - `intent`- optional order capture timing intent, such as    [SalesforcePayPalOrder.INTENT_AUTHORIZE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#intent_authorize)or [SalesforcePayPalOrder.INTENT_CAPTURE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#intent_capture)    - `shippingPreference`- optional shipping preference, such as `"GET_FROM_FILE"`      - `userAction`- optional user action, such as `"PAY_NOW"`
      
      If `intent`is provided it is used to determine manual or automatic capture, and otherwise the default        card capture timing set for the site is used.        


    **Parameters:**
    - basket - basket to checkout and pay using Salesforce Payments
    - shipment - shipment to use for shipping information in the payment intent
    - zoneId - id of the payment zone
    - amount - payment amount
    - paypalOrderProperties - properties to pass to the create PayPal order API

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'paypalorder'` contains the PayPal order, if it is
              available in the PayPal response. Status detail `'error'` contains the PayPal error
              information, if it is available in the response.



---

### createPaymentIntent(Basket, Shipment, String, Money, Boolean, Object)
- static createPaymentIntent(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), zoneId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), stripeCustomerRequired: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), paymentIntentProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Creates a payment intent using the given information, and associates it with the given basket.
      
      
      
      
      The following Payment Intent properties are supported:
      
      - `type`- required payment method type, such as [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card)  - `statementDescriptor`- optional statement descriptor        - `cardCaptureAutomatic`- optional `true`if the credit card payment should be      automatically captured at the time of the sale, or `false`if the credit card payment should be      captured later            - `setupFutureUsage`- optional future usage setup value, such as        [SalesforcePaymentIntent.SETUP_FUTURE_USAGE_ON_SESSION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md#setup_future_usage_on_session)
      
      The `stripeCustomerRequired`must be set to `true`if the payment will be set up for future        usage, whether on session or off session. If `true`then if a Stripe Customer is associated with the        shopper then it will be used, and otherwise a new Stripe Customer will be created. The new Stripe Customer will        be associated with the shopper if logged into a registered customer account for the site.        
      
      If `cardCaptureAutomatic`is provided it is used to determine card capture timing, and otherwise the        default card capture timing set for the site is used.        
      
      If `statementDescriptor`is provided it is used as the complete description that appears on your        customers' statements for the payment, and if not a default statement descriptor is used. If a default statement        descriptor is set for the site it is used as the default, and otherwise the default statement descriptor for the        account will apply.        
      
      If `setupFutureUsage`is provided it will be used to prepare the payment to be set up for future usage        at confirmation time. When set, this future usage setup value must match the value used at confirmation time.        


    **Parameters:**
    - basket - basket to checkout and pay using Salesforce Payments
    - shipment - shipment to use for shipping information in the payment intent
    - zoneId - id of the payment zone
    - amount - payment amount
    - stripeCustomerRequired - `true` if a Stripe Customer must be associated with the payment intent,             and would be created if it doesn't already exist, or `false` if a Stripe Customer does not             have to be associated with the payment intent
    - paymentIntentProperties - properties to pass to the create Payment Intent API

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'paymentintent'` contains the payment intent, if it is
              available in the Stripe response. Status detail `'error'` contains the Stripe error
              information, if it is available in the response.



---

### detachPaymentMethod(SalesforcePaymentMethod)
- ~~static detachPaymentMethod(paymentMethod: [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)): void~~
  - : Detaches the given payment method from its associated customer. Once detached the payment method remains
      associated with payment intents in the payment account, but is no longer saved for use by the customer in future
      orders.


    **Parameters:**
    - paymentMethod - payment method to detach from customer

    **Throws:**
    - Exception - if there was an error detaching the payment method from its customer

    **Deprecated:**
**warning:** use [removeSavedPaymentMethod(SalesforcePaymentMethod)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#removesavedpaymentmethodsalesforcepaymentmethod)

---

### getAdyenSavedPaymentMethods(Customer)
- static getAdyenSavedPaymentMethods(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing the Adyen payment methods saved to be presented to the given customer for reuse
      in checkouts. The collection will be empty if there are no payment methods saved for the customer, or there was
      an error retrieving the saved payment methods.


    **Parameters:**
    - customer - customer whose saved payment methods to get

    **Returns:**
    - collection of saved payment methods

    **Throws:**
    - Exception - if the given customer is `null` or `undefined`, or there is configuration              missing that is required to retrieve the saved payment methods


---

### getAttachedPaymentMethods(Customer)
- ~~static getAttachedPaymentMethods(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns a collection containing the payment methods attached to the given customer. The collection will be empty
      if there are no payment methods attached to the customer, or there was an error retrieving the attached payment
      methods.


    **Parameters:**
    - customer - customer whose payment methods to get

    **Returns:**
    - collection of attached payment methods

    **Throws:**
    - Exception - if the given customer is `null` or `undefined`

    **Deprecated:**
**warning:** use [getSavedPaymentMethods(Customer)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#getsavedpaymentmethodscustomer)

---

### getOffSessionPaymentMethods(Customer)
- static getOffSessionPaymentMethods(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing the payment methods for the given customer set up for future off session reuse.
      The collection will be empty if there are no off session payment methods for the customer, or there was an error
      retrieving the off session payment methods.


    **Parameters:**
    - customer - customer whose off session payment methods to get

    **Returns:**
    - collection of off session payment methods

    **Throws:**
    - Exception - if the given customer is `null` or `undefined`, or there is an error              getting the off session payment methods


---

### getPayPalOrder(Basket)
- static getPayPalOrder(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)
  - : Returns the PayPal order for the given basket, or `null` if the given basket has none.

    **Parameters:**
    - basket - basket to checkout and pay using Salesforce Payments

    **Returns:**
    - The PayPal order

    **Throws:**
    - Exception - if there was an error retrieving the PayPal order for the basket


---

### getPayPalOrder(Order)
- static getPayPalOrder(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)
  - : Returns the PayPal order for the given order, or `null` if the given order has none.

    **Parameters:**
    - order - order paid using Salesforce Payments

    **Returns:**
    - The PayPal order

    **Throws:**
    - Exception - if there was an error retrieving the PayPal order for the order


---

### getPaymentDetails(OrderPaymentInstrument)
- static getPaymentDetails(paymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)): [SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
  - : Returns the details to the Salesforce Payments payment associated with the given payment instrument, or
      `null` if the given payment instrument has none.


    **Parameters:**
    - paymentInstrument - payment instrument

    **Returns:**
    - The payment details

    **Throws:**
    - Exception - if paymentInstrument is null


---

### getPaymentIntent(Basket)
- static getPaymentIntent(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md)
  - : Returns the payment intent for the given basket, or `null` if the given basket has none.

    **Parameters:**
    - basket - basket to checkout and pay using Salesforce Payments

    **Returns:**
    - The payment intent

    **Throws:**
    - Exception - if there was an error retrieving the payment intent for the basket


---

### getPaymentIntent(Order)
- static getPaymentIntent(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md)
  - : Returns the payment intent for the given order, or `null` if the given order has none.

    **Parameters:**
    - order - order paid using Salesforce Payments

    **Returns:**
    - The payment intent

    **Throws:**
    - Exception - if there was an error retrieving the payment intent for the order


---

### getPaymentsSiteConfig()
- static getPaymentsSiteConfig(): [SalesforcePaymentsSiteConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md)
  - : Returns a payments site configuration object for the current site.

    **Returns:**
    - a payments site configuration or null if no payments site configuration found

    **Throws:**
    - Exception - if there is no current site


---

### getPaymentsZone(String)
- static getPaymentsZone(zoneId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SalesforcePaymentsZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md)
  - : Returns a payments zone object for the passed in payments zone ID.

    **Parameters:**
    - zoneId - ID of the payments zone to retrieve and use to checkout and pay using Salesforce Payments

    **Returns:**
    - a payments zone or null if no payments zone with the given ID exists


---

### getSavedPaymentMethods(Customer)
- static getSavedPaymentMethods(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing the payment methods saved to be presented to the given customer for reuse in
      checkouts. The collection will be empty if there are no payment methods saved for the customer, or there was an
      error retrieving the saved payment methods.


    **Parameters:**
    - customer - customer whose saved payment methods to get

    **Returns:**
    - collection of saved payment methods

    **Throws:**
    - Exception - if the given customer is `null` or `undefined`, or there is configuration              missing that is required to retrieve the saved payment methods


---

### handleAdyenAdditionalDetails(Order, String, Object)
- static handleAdyenAdditionalDetails(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), zoneId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), data: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : 
      
      Handles the given additional Adyen payment details and associates the associated payment with the given order, if
      applicable.
      
      
      
      
      Pass the state data from the Adyen `onAdditionalDetails` event as-is, without any encoding or other
      changes to the data or its structure. See the Adyen documentation for more information.


    **Parameters:**
    - order - order to checkout and pay using Salesforce Payments
    - zoneId - id of the payment zone
    - data - additional details state data

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'adyenpayment'` contains the payment details, if it is
              available in the Adyen response and the response resultCode is 'Authorised'. Status detail
              `'error'` contains the Adyen error information, if it is available in the response.



---

### onCustomerRegistered(Order)
- static onCustomerRegistered(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): void
  - : Handles the account registration of the shopper who placed the given order. Use this method to ensure the
      registered customer profile is associated with the order in Salesforce Payments.


    **Parameters:**
    - order - order paid using Salesforce Payments

    **Throws:**
    - Exception - if there was an error attaching the payment method to the customer


---

### refundAdyenPayment(OrderPaymentInstrument, Money, Object)
- static refundAdyenPayment(orderPaymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), transactionProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Refunds previously captured funds for the given order payment instrument.
      
      
      The order payment instrument must be in a state that supports refund.
      
      
      
      
      The `amount` must be less than or equal to the amount available to refund.
      
      
      
      
      The following Transaction properties are supported:
      
      - `reference`- optional reference for the transaction, for example order number  


    **Parameters:**
    - orderPaymentInstrument - payment instrument to refund
    - amount - amount to refund
    - transactionProperties - properties to pass to the refund Adyen Payment API

    **Returns:**
    - Status 'OK' or 'ERROR'.

    **Throws:**
    - Exception - if there was an error refunding the payment instrument


---

### refundPayPalOrderCapture(SalesforcePayPalOrder)
- static refundPayPalOrderCapture(paypalOrder: [SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Refunds the capture for the given PayPal order.
      
      
      The PayPal order must have a capture in a status that supports refund. See the PayPal documentation for more
      details.


    **Parameters:**
    - paypalOrder - PayPal order whose capture to refund

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'error'` contains the PayPal error information, if it
              is available in the response.


    **Throws:**
    - Exception - if there was an error refunding the capture for the PayPal order


---

### refundPaymentIntent(SalesforcePaymentIntent, Money, Object)
- static refundPaymentIntent(paymentIntent: [SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), refundProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Refunds previously captured funds for the given payment intent.
      
      
      The payment intent must be in a state that supports refund. This includes its status as well as any previous
      refunds. See the Stripe documentation for more details.
      
      
      
      
      The following Payment Intent property is supported:
      
      - `reason`- optional payment intent refund reason  
      
      If `amount`is not specified, the default is the full amount available to refund. If specified, the  amount must be less than or equal to the amount available to refund.  


    **Parameters:**
    - paymentIntent - payment intent to refund
    - amount - optional amount to refund, defaults to amount previously captured
    - refundProperties - additional properties to pass to the refund API

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'error'` contains the Stripe error information, if it
              is available in the response.


    **Throws:**
    - Exception - if there was an error refunding the payment intent

    **See Also:**
    - [REFUND_REASON_DUPLICATE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#refund_reason_duplicate)
    - [REFUND_REASON_FRAUDULENT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#refund_reason_fraudulent)
    - [REFUND_REASON_REQUESTED_BY_CUSTOMER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md#refund_reason_requested_by_customer)


---

### removeAdyenSavedPaymentMethod(SalesforceAdyenSavedPaymentMethod)
- static removeAdyenSavedPaymentMethod(savedPaymentMethod: [SalesforceAdyenSavedPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md)): void
  - : Deletes an Adyen saved payment method.

    **Parameters:**
    - savedPaymentMethod - the saved payment method to delete

    **Throws:**
    - Exception - if the saved payment method is `null` or `undefined`, or there is              configuration missing that is required to delete the saved payment method


---

### removeSavedPaymentMethod(SalesforcePaymentMethod)
- static removeSavedPaymentMethod(paymentMethod: [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)): void
  - : Removes the given saved payment method so that it is no longer presented to the given customer for reuse in
      checkouts. The payment method remains in the payment account, but is no longer saved for use by the customer.


    **Parameters:**
    - paymentMethod - payment method to detach from customer

    **Throws:**
    - Exception - if there was an error removing the saved payment method from its customer


---

### resolvePaymentsZone(Object)
- static resolvePaymentsZone(paymentsZoneProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SalesforcePaymentsZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md)
  - : Resolves and returns the payments zone object for the passed in payments zone properties object. If an empty
      object is provided, the default payments zone will be returned if it exists.
      
      
      The following payments zone properties are supported:
      
      - `countryCode`- optional country code of the shopper, or `null`if not known
      - `currency`- optional basket currency, or `null`if not known


    **Parameters:**
    - paymentsZoneProperties - properties to use to retrieve the payments zone for to use to checkout and pay             using Salesforce Payments

    **Returns:**
    - a payments zone

    **Throws:**
    - Exception - if no default payments zone exists


---

### reverseAdyenPayment(OrderPaymentInstrument, Object)
- static reverseAdyenPayment(orderPaymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), transactionProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Reverses the authorisation for the given order payment instrument.
      
      
      The order payment instrument must be in a state that supports reversal.
      
      
      
      
      The following Transaction properties are supported:
      
      - `reference`- optional reference for the transaction, for example order number  


    **Parameters:**
    - orderPaymentInstrument - payment instrument to reverse
    - transactionProperties - properties to pass to the reverse Adyen Payment API

    **Returns:**
    - Status 'OK' or 'ERROR'.

    **Throws:**
    - Exception - if there was an error reversing the payment instrument


---

### savePaymentMethod(Customer, SalesforcePaymentMethod)
- static savePaymentMethod(customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md), paymentMethod: [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)): void
  - : Saves the given payment method to be presented to the given customer for reuse in subsequent checkouts. This
      method will throw an error if passed incompatible payment method and/or customer objects.


    **Parameters:**
    - customer - customer for which to save the payment method
    - paymentMethod - payment method to save for the customer

    **Throws:**
    - Exception - if there was an error saving the payment method for the customer


---

### setPaymentDetails(OrderPaymentInstrument, SalesforcePaymentDetails)
- static setPaymentDetails(paymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md), paymentDetails: [SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)): void
  - : Sets the details to the Salesforce Payments payment associated with the given payment instrument.

    **Parameters:**
    - paymentInstrument - payment instrument
    - paymentDetails - payment details

    **Throws:**
    - Exception - if either paymentInstrument or paymentDetails is null

    **See Also:**
    - [SalesforcePaymentMethod.getPaymentDetails(OrderPaymentInstrument)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getpaymentdetailsorderpaymentinstrument)
    - [SalesforcePayPalOrder.getPaymentDetails(OrderPaymentInstrument)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getpaymentdetailsorderpaymentinstrument)


---

### updatePaymentIntent(SalesforcePaymentIntent, Shipment, Money, String, Object)
- static updatePaymentIntent(paymentIntent: [SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md), shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md), orderNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), paymentIntentProperties: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Updates the provided information in the given payment intent.
      
      
      The payment intent must be in a status that supports update. See the Stripe documentation for more details.
      
      
      
      
      The following Payment Intent properties are supported:
      
      - `statementDescriptor`- optional statement descriptor    - `cardCaptureAutomatic`- optional `true`if the credit card payment should be    automatically captured at the time of the sale, or `false`if the credit card payment should be    captured later    
      
      If `cardCaptureAutomatic`is provided it is used to determine card capture timing, and otherwise the    default card capture timing set for the site is used.    
      
      If `statementDescriptor`is provided it is used as the complete description that appears on your    customers' statements for the payment, and if not a default statement descriptor is used. If a default statement    descriptor is set for the site it is used as the default, and otherwise the default statement descriptor for the    account will apply.    


    **Parameters:**
    - paymentIntent - payment intent to update
    - shipment - optional shipment to use to update shipping information in the payment intent
    - amount - optional new payment amount
    - orderNo - optional order no of [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) to associate with the payment intent in metadata
    - paymentIntentProperties - optional additional properties to pass to the update Payment Intent API

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'paymentintent'` contains the payment intent, if it is
              available in the Stripe response. Status detail `'error'` contains the Stripe error
              information, if it is available in the response.


    **Throws:**
    - Exception - if the parameter validation failed or there's an error updating the payment intent


---

### voidPayPalOrderAuthorization(SalesforcePayPalOrder)
- static voidPayPalOrderAuthorization(paypalOrder: [SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Voids the authorization for the given PayPal order.
      
      
      The PayPal order must have an authorization in a status that supports voiding. See the PayPal documentation for
      more details.


    **Parameters:**
    - paypalOrder - PayPal order whose authorization to void

    **Returns:**
    - Status 'OK' or 'ERROR'. Status detail `'error'` contains the PayPal error information, if it
              is available in the response.


    **Throws:**
    - Exception - if there was an error voiding the authorization for the PayPal order


---

<!-- prettier-ignore-end -->

<!-- document id=2d16541dde25cf4f25382f5db2fc640e46464286fcc3f654e2a8835eae4b4291 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentsSiteConfiguration

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentsSiteConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md)



Salesforce Payments representation of a payment site configuration object. See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.




A payment site configuration contains information about the configuration of the site such as
whether the site is activated with Express Checkout, Multi-Step Checkout or both.



## Property Summary

| Property | Description |
| --- | --- |
| [cardCaptureAutomatic](#cardcaptureautomatic): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the capture method is set to automatic for credit card Payment Intents created for this site, or  false if the capture method is set to manual. |
| [expressCheckoutEnabled](#expresscheckoutenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if Express Checkout is enabled for the site. |
| [expressOnCartEnabled](#expressoncartenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if Express Checkout is enabled on the Cart page. |
| [expressOnCheckoutEnabled](#expressoncheckoutenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if Express Checkout is enabled on the Checkout page. |
| [expressOnMiniCartEnabled](#expressonminicartenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if Express Checkout is enabled on the Mini-Cart. |
| [expressOnPdpEnabled](#expressonpdpenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if Express Checkout is enabled on the Product Detail Page. |
| [futureUsageOffSession](#futureusageoffsession): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if the payment card credential storage is configured to set up all applicable payments for off  session reuse, or false if the credential storage is configured to set up for on session reuse only the payments  for which the shopper actively confirms use of saved credentials. |
| [multiStepCheckoutEnabled](#multistepcheckoutenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if Multi-Step Checkout is enabled for the site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [isCardCaptureAutomatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#iscardcaptureautomatic)() | Returns true if the capture method is set to automatic for credit card Payment Intents created for this site, or  false if the capture method is set to manual. |
| [isExpressCheckoutEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#isexpresscheckoutenabled)() | Returns true if Express Checkout is enabled for the site. |
| [isExpressOnCartEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#isexpressoncartenabled)() | Returns true if Express Checkout is enabled on the Cart page. |
| [isExpressOnCheckoutEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#isexpressoncheckoutenabled)() | Returns true if Express Checkout is enabled on the Checkout page. |
| [isExpressOnMiniCartEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#isexpressonminicartenabled)() | Returns true if Express Checkout is enabled on the Mini-Cart. |
| [isExpressOnPdpEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#isexpressonpdpenabled)() | Returns true if Express Checkout is enabled on the Product Detail Page. |
| [isFutureUsageOffSession](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#isfutureusageoffsession)() | Returns true if the payment card credential storage is configured to set up all applicable payments for off  session reuse, or false if the credential storage is configured to set up for on session reuse only the payments  for which the shopper actively confirms use of saved credentials. |
| [isMultiStepCheckoutEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md#ismultistepcheckoutenabled)() | Returns true if Multi-Step Checkout is enabled for the site. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### cardCaptureAutomatic
- cardCaptureAutomatic: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the capture method is set to automatic for credit card Payment Intents created for this site, or
      false if the capture method is set to manual.



---

### expressCheckoutEnabled
- expressCheckoutEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if Express Checkout is enabled for the site.


---

### expressOnCartEnabled
- expressOnCartEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if Express Checkout is enabled on the Cart page.


---

### expressOnCheckoutEnabled
- expressOnCheckoutEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if Express Checkout is enabled on the Checkout page.


---

### expressOnMiniCartEnabled
- expressOnMiniCartEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if Express Checkout is enabled on the Mini-Cart.


---

### expressOnPdpEnabled
- expressOnPdpEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if Express Checkout is enabled on the Product Detail Page.


---

### futureUsageOffSession
- futureUsageOffSession: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if the payment card credential storage is configured to set up all applicable payments for off
      session reuse, or false if the credential storage is configured to set up for on session reuse only the payments
      for which the shopper actively confirms use of saved credentials.



---

### multiStepCheckoutEnabled
- multiStepCheckoutEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if Multi-Step Checkout is enabled for the site.


---

## Method Details

### isCardCaptureAutomatic()
- isCardCaptureAutomatic(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the capture method is set to automatic for credit card Payment Intents created for this site, or
      false if the capture method is set to manual.


    **Returns:**
    - true if the credit card capture method is automatic, or false if it is manual


---

### isExpressCheckoutEnabled()
- isExpressCheckoutEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if Express Checkout is enabled for the site.

    **Returns:**
    - true if Express Checkout is enabled for the site, or false if not


---

### isExpressOnCartEnabled()
- isExpressOnCartEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if Express Checkout is enabled on the Cart page.

    **Returns:**
    - true if Express Checkout is enabled on Cart, or false if not


---

### isExpressOnCheckoutEnabled()
- isExpressOnCheckoutEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if Express Checkout is enabled on the Checkout page.

    **Returns:**
    - true if Express Checkout is enabled on Checkout, or false if not


---

### isExpressOnMiniCartEnabled()
- isExpressOnMiniCartEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if Express Checkout is enabled on the Mini-Cart.

    **Returns:**
    - true if Express Checkout is enabled on Mini-Cart, or false if not


---

### isExpressOnPdpEnabled()
- isExpressOnPdpEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if Express Checkout is enabled on the Product Detail Page.

    **Returns:**
    - true if Express Checkout is enabled on PDP, or false if not


---

### isFutureUsageOffSession()
- isFutureUsageOffSession(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the payment card credential storage is configured to set up all applicable payments for off
      session reuse, or false if the credential storage is configured to set up for on session reuse only the payments
      for which the shopper actively confirms use of saved credentials.


    **Returns:**
    - true if the future usage is off session, or false if on session


---

### isMultiStepCheckoutEnabled()
- isMultiStepCheckoutEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if Multi-Step Checkout is enabled for the site.

    **Returns:**
    - true if Multi-Step Checkout is enabled for the site, or false if not


---

<!-- prettier-ignore-end -->

<!-- document id=1dcc066404af6602180e44d1f8b0a13d2a4934e6d42c9dbd6adf7509c188f905 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePaymentsZone.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePaymentsZone

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentsZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md)



Salesforce Payments representation of a payments zone. See Salesforce Payments documentation for how to gain access
and configure payment zones and assign them to sites.




A payments zone contains information about the payment zone for a site and country.



## Property Summary

| Property | Description |
| --- | --- |
| [afterpayClearpayEnabled](#afterpayclearpayenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Afterpay Clearpay presentment is enabled, or `false` if not. |
| [applePayEnabled](#applepayenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Apple Pay presentment is enabled, or `false` if not. |
| [bancontactEnabled](#bancontactenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Bancontact presentment is enabled, or `false` if not. |
| [bancontactMobileEnabled](#bancontactmobileenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Bancontact Mobile presentment is enabled, or `false` if not. |
| [cardEnabled](#cardenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if credit card presentment is enabled, or `false` if not. |
| [epsEnabled](#epsenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if EPS presentment is enabled, or `false` if not. |
| [idealEnabled](#idealenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if iDEAL presentment is enabled, or `false` if not. |
| [klarnaEnabled](#klarnaenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Klarna presentment is enabled, or `false` if not. |
| [klarnaPayInInstallmentsEnabled](#klarnapayininstallmentsenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Klarna Pay in Installments presentment is enabled, or `false` if not. |
| [klarnaPayNowEnabled](#klarnapaynowenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Klarna Pay Now presentment is enabled, or `false` if not. |
| [payPalEnabled](#paypalenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if PayPal multi-step checkout presentment is enabled, or `false` if not. |
| [payPalExpressEnabled](#paypalexpressenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if PayPal express checkout presentment is enabled, or `false` if not. |
| [paymentRequestEnabled](#paymentrequestenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if W3C Payment Request API button presentment is enabled, or `false` if not. |
| [sepaDebitEnabled](#sepadebitenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if SEPA Debit presentment is enabled, or `false` if not. |
| [venmoEnabled](#venmoenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Venmo multi-step checkout presentment is enabled, or `false` if not. |
| [venmoExpressEnabled](#venmoexpressenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if Venmo express checkout presentment is enabled, or `false` if not. |
| [zoneId](#zoneid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the id of the payments zone. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getPaymentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#getpaymentmethodsstring-money)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Returns a collection containing the merchant account payment methods to be presented for this payments zone. |
| [getZoneId](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#getzoneid)() | Returns the id of the payments zone. |
| [isAfterpayClearpayEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isafterpayclearpayenabled)() | Returns `true` if Afterpay Clearpay presentment is enabled, or `false` if not. |
| [isApplePayEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isapplepayenabled)() | Returns `true` if Apple Pay presentment is enabled, or `false` if not. |
| [isBancontactEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isbancontactenabled)() | Returns `true` if Bancontact presentment is enabled, or `false` if not. |
| [isBancontactMobileEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isbancontactmobileenabled)() | Returns `true` if Bancontact Mobile presentment is enabled, or `false` if not. |
| [isCardEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#iscardenabled)() | Returns `true` if credit card presentment is enabled, or `false` if not. |
| [isEpsEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isepsenabled)() | Returns `true` if EPS presentment is enabled, or `false` if not. |
| [isIdealEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isidealenabled)() | Returns `true` if iDEAL presentment is enabled, or `false` if not. |
| [isKlarnaEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isklarnaenabled)() | Returns `true` if Klarna presentment is enabled, or `false` if not. |
| [isKlarnaPayInInstallmentsEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isklarnapayininstallmentsenabled)() | Returns `true` if Klarna Pay in Installments presentment is enabled, or `false` if not. |
| [isKlarnaPayNowEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isklarnapaynowenabled)() | Returns `true` if Klarna Pay Now presentment is enabled, or `false` if not. |
| [isPayPalEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#ispaypalenabled)() | Returns `true` if PayPal multi-step checkout presentment is enabled, or `false` if not. |
| [isPayPalExpressEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#ispaypalexpressenabled)() | Returns `true` if PayPal express checkout presentment is enabled, or `false` if not. |
| [isPaymentRequestEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#ispaymentrequestenabled)() | Returns `true` if W3C Payment Request API button presentment is enabled, or `false` if not. |
| [isSepaDebitEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#issepadebitenabled)() | Returns `true` if SEPA Debit presentment is enabled, or `false` if not. |
| [isVenmoEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isvenmoenabled)() | Returns `true` if Venmo multi-step checkout presentment is enabled, or `false` if not. |
| [isVenmoExpressEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md#isvenmoexpressenabled)() | Returns `true` if Venmo express checkout presentment is enabled, or `false` if not. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### afterpayClearpayEnabled
- afterpayClearpayEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Afterpay Clearpay presentment is enabled, or `false` if not.


---

### applePayEnabled
- applePayEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Apple Pay presentment is enabled, or `false` if not.


---

### bancontactEnabled
- bancontactEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Bancontact presentment is enabled, or `false` if not. Note: For Adyen
      merchant accounts, this setting refers to the "Bancontact Card" payment method.



---

### bancontactMobileEnabled
- bancontactMobileEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Bancontact Mobile presentment is enabled, or `false` if not. Note: This
      setting is only applicable for Adyen Merchant Accounts



---

### cardEnabled
- cardEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if credit card presentment is enabled, or `false` if not.


---

### epsEnabled
- epsEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if EPS presentment is enabled, or `false` if not.


---

### idealEnabled
- idealEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if iDEAL presentment is enabled, or `false` if not.


---

### klarnaEnabled
- klarnaEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Klarna presentment is enabled, or `false` if not. Note: For Adyen
      merchant accounts, this setting applies to the Klarna Pay Later payment method.



---

### klarnaPayInInstallmentsEnabled
- klarnaPayInInstallmentsEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Klarna Pay in Installments presentment is enabled, or `false` if not.
      Note: This setting is only applicable for Adyen Merchant Accounts.



---

### klarnaPayNowEnabled
- klarnaPayNowEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Klarna Pay Now presentment is enabled, or `false` if not. Note: This
      setting is only applicable for Adyen Merchant Accounts.



---

### payPalEnabled
- payPalEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if PayPal multi-step checkout presentment is enabled, or `false` if not.


---

### payPalExpressEnabled
- payPalExpressEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if PayPal express checkout presentment is enabled, or `false` if not.


---

### paymentRequestEnabled
- paymentRequestEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if W3C Payment Request API button presentment is enabled, or `false` if not.


---

### sepaDebitEnabled
- sepaDebitEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if SEPA Debit presentment is enabled, or `false` if not.


---

### venmoEnabled
- venmoEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Venmo multi-step checkout presentment is enabled, or `false` if not.


---

### venmoExpressEnabled
- venmoExpressEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if Venmo express checkout presentment is enabled, or `false` if not.


---

### zoneId
- zoneId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the id of the payments zone.


---

## Method Details

### getPaymentMethods(String, Money)
- getPaymentMethods(countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection containing the merchant account payment methods to be presented for this payments zone.

    **Returns:**
    - collection of merchant account payment methods


---

### getZoneId()
- getZoneId(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the id of the payments zone.

    **Returns:**
    - zone id


---

### isAfterpayClearpayEnabled()
- isAfterpayClearpayEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Afterpay Clearpay presentment is enabled, or `false` if not.

    **Returns:**
    - if Afterpay Clearpay presentment is enabled


---

### isApplePayEnabled()
- isApplePayEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Apple Pay presentment is enabled, or `false` if not.

    **Returns:**
    - if Apple Pay presentment is enabled


---

### isBancontactEnabled()
- isBancontactEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Bancontact presentment is enabled, or `false` if not. Note: For Adyen
      merchant accounts, this setting refers to the "Bancontact Card" payment method.


    **Returns:**
    - if Bancontact presentment is enabled


---

### isBancontactMobileEnabled()
- isBancontactMobileEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Bancontact Mobile presentment is enabled, or `false` if not. Note: This
      setting is only applicable for Adyen Merchant Accounts


    **Returns:**
    - if Bancontact Mobile presentment is enabled


---

### isCardEnabled()
- isCardEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if credit card presentment is enabled, or `false` if not.

    **Returns:**
    - if credit card presentment is enabled


---

### isEpsEnabled()
- isEpsEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if EPS presentment is enabled, or `false` if not.

    **Returns:**
    - if EPS presentment is enabled


---

### isIdealEnabled()
- isIdealEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if iDEAL presentment is enabled, or `false` if not.

    **Returns:**
    - if iDEAL presentment is enabled


---

### isKlarnaEnabled()
- isKlarnaEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Klarna presentment is enabled, or `false` if not. Note: For Adyen
      merchant accounts, this setting applies to the Klarna Pay Later payment method.


    **Returns:**
    - if Klarna presentment is enabled


---

### isKlarnaPayInInstallmentsEnabled()
- isKlarnaPayInInstallmentsEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Klarna Pay in Installments presentment is enabled, or `false` if not.
      Note: This setting is only applicable for Adyen Merchant Accounts.


    **Returns:**
    - if Klarna Pay in Installments presentment is enabled


---

### isKlarnaPayNowEnabled()
- isKlarnaPayNowEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Klarna Pay Now presentment is enabled, or `false` if not. Note: This
      setting is only applicable for Adyen Merchant Accounts.


    **Returns:**
    - if Klarna Pay Now presentment is enabled


---

### isPayPalEnabled()
- isPayPalEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if PayPal multi-step checkout presentment is enabled, or `false` if not.

    **Returns:**
    - if PayPal multi-step checkout presentment is enabled


---

### isPayPalExpressEnabled()
- isPayPalExpressEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if PayPal express checkout presentment is enabled, or `false` if not.

    **Returns:**
    - if PayPal express checkout presentment is enabled


---

### isPaymentRequestEnabled()
- isPaymentRequestEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if W3C Payment Request API button presentment is enabled, or `false` if not.

    **Returns:**
    - if W3C Payment Request API presentment is enabled


---

### isSepaDebitEnabled()
- isSepaDebitEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if SEPA Debit presentment is enabled, or `false` if not.

    **Returns:**
    - if SEPA Debit presentment is enabled


---

### isVenmoEnabled()
- isVenmoEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Venmo multi-step checkout presentment is enabled, or `false` if not.

    **Returns:**
    - if Venmo multi-step checkout presentment is enabled


---

### isVenmoExpressEnabled()
- isVenmoExpressEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if Venmo express checkout presentment is enabled, or `false` if not.

    **Returns:**
    - if Venmo express checkout presentment is enabled


---

<!-- prettier-ignore-end -->

<!-- document id=4a8eed64fb36e57602e8a9632cad4284fc6b7fc02c88b414b22ac3acd37d590d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePayPalOrder.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePayPalOrder

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)



Salesforce Payments representation of a PayPal order object. See Salesforce Payments documentation for how
to gain access and configure it for use on your sites.




A PayPal order is automatically created when a shopper is ready to pay for items in their basket. It becomes
completed when the shopper provides information to the payment provider that is acceptable to authorize payment for a
given amount.



## Constant Summary

| Constant | Description |
| --- | --- |
| [INTENT_AUTHORIZE](#intent_authorize): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTHORIZE" | Represents the `"AUTHORIZE"` intent, meaning manual capture. |
| [INTENT_CAPTURE](#intent_capture): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CAPTURE" | Represents the `"CAPTURE"` intent, meaning automatic capture. |
| [TYPE_PAYPAL](#type_paypal): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypal" | Represents the PayPal funding source. |
| [TYPE_VENMO](#type_venmo): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "venmo" | Represents the Venmo funding source. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the identifier of this PayPal order. |
| [amount](#amount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the amount of this PayPal order. |
| [authorizationID](#authorizationid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the authorization against this order, or `null` if not available. |
| [captureID](#captureid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the capture against this order, or `null` if not available. |
| [completed](#completed): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns `true` if this PayPal order has been completed, or `false` if not. |
| [payer](#payer): [SalesforcePayPalOrderPayer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md) `(read-only)` | Returns the payer information for this PayPal order, or `null` if not known. |
| [shipping](#shipping): [SalesforcePayPalOrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md) `(read-only)` | Returns the shipping address for this PayPal order, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getamount)() | Returns the amount of this PayPal order. |
| [getAuthorizationID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getauthorizationid)() | Returns the ID of the authorization against this order, or `null` if not available. |
| [getCaptureID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getcaptureid)() | Returns the ID of the capture against this order, or `null` if not available. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getid)() | Returns the identifier of this PayPal order. |
| [getPayer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getpayer)() | Returns the payer information for this PayPal order, or `null` if not known. |
| [getPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getpaymentdetailsorderpaymentinstrument)([OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)) | Returns the details to the Salesforce Payments payment for this PayPal order, using the given payment instrument. |
| [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getpaymentinstrumentbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Returns the payment instrument for this PayPal order in the given basket, or `null` if the given  basket has none. |
| [getPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getpaymentinstrumentorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Returns the payment instrument for this PayPal order in the given order, or `null` if the given  order has none. |
| [getShipping](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getshipping)() | Returns the shipping address for this PayPal order, or `null` if not known. |
| [isCompleted](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#iscompleted)() | Returns `true` if this PayPal order has been completed, or `false` if not. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### INTENT_AUTHORIZE

- INTENT_AUTHORIZE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "AUTHORIZE"
  - : Represents the `"AUTHORIZE"` intent, meaning manual capture.


---

### INTENT_CAPTURE

- INTENT_CAPTURE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CAPTURE"
  - : Represents the `"CAPTURE"` intent, meaning automatic capture.


---

### TYPE_PAYPAL

- TYPE_PAYPAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "paypal"
  - : Represents the PayPal funding source.


---

### TYPE_VENMO

- TYPE_VENMO: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "venmo"
  - : Represents the Venmo funding source.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the identifier of this PayPal order.


---

### amount
- amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the amount of this PayPal order.


---

### authorizationID
- authorizationID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the authorization against this order, or `null` if not available.


---

### captureID
- captureID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the capture against this order, or `null` if not available.


---

### completed
- completed: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns `true` if this PayPal order has been completed, or `false` if not.


---

### payer
- payer: [SalesforcePayPalOrderPayer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md) `(read-only)`
  - : Returns the payer information for this PayPal order, or `null` if not known.


---

### shipping
- shipping: [SalesforcePayPalOrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md) `(read-only)`
  - : Returns the shipping address for this PayPal order, or `null` if not known.


---

## Method Details

### getAmount()
- getAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the amount of this PayPal order.

    **Returns:**
    - PayPal order amount


---

### getAuthorizationID()
- getAuthorizationID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the authorization against this order, or `null` if not available.

    **Returns:**
    - PayPal order authorization identifier


---

### getCaptureID()
- getCaptureID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the capture against this order, or `null` if not available.

    **Returns:**
    - PayPal order capture identifier


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the identifier of this PayPal order.

    **Returns:**
    - PayPal order identifier


---

### getPayer()
- getPayer(): [SalesforcePayPalOrderPayer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md)
  - : Returns the payer information for this PayPal order, or `null` if not known.

    **Returns:**
    - order payer information


---

### getPaymentDetails(OrderPaymentInstrument)
- getPaymentDetails(paymentInstrument: [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)): [SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
  - : Returns the details to the Salesforce Payments payment for this PayPal order, using the given payment instrument.

    **Parameters:**
    - paymentInstrument - payment instrument

    **Returns:**
    - The payment details


---

### getPaymentInstrument(Basket)
- getPaymentInstrument(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Returns the payment instrument for this PayPal order in the given basket, or `null` if the given
      basket has none.


    **Parameters:**
    - basket - basket

    **Returns:**
    - basket payment instrument


---

### getPaymentInstrument(Order)
- getPaymentInstrument(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)
  - : Returns the payment instrument for this PayPal order in the given order, or `null` if the given
      order has none.


    **Parameters:**
    - order - order

    **Returns:**
    - order payment instrument


---

### getShipping()
- getShipping(): [SalesforcePayPalOrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md)
  - : Returns the shipping address for this PayPal order, or `null` if not known.

    **Returns:**
    - order shipping address


---

### isCompleted()
- isCompleted(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns `true` if this PayPal order has been completed, or `false` if not.

    **Returns:**
    - `true` if this PayPal order has been completed


---

<!-- prettier-ignore-end -->

<!-- document id=8bc4147c6b3612f944872c52c4ae8101d9434b7744a51a60ca1c0263e133e59a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePayPalOrderAddress.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePayPalOrderAddress

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePayPalOrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md)



Salesforce Payments representation of a PayPal order address object. See Salesforce Payments documentation
for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [addressLine1](#addressline1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address line 1. |
| [addressLine2](#addressline2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address line 2. |
| [adminArea1](#adminarea1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address highest level sub-division in a country, which is usually a province, state, or ISO-3166-2  subdivision. |
| [adminArea2](#adminarea2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address city, town, or village. |
| [countryCode](#countrycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address two-character ISO 3166-1 code that identifies the country or region. |
| [fullName](#fullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address full name. |
| [postalCode](#postalcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address postal code. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAddressLine1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md#getaddressline1)() | Returns the address line 1. |
| [getAddressLine2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md#getaddressline2)() | Returns the address line 2. |
| [getAdminArea1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md#getadminarea1)() | Returns the address highest level sub-division in a country, which is usually a province, state, or ISO-3166-2  subdivision. |
| [getAdminArea2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md#getadminarea2)() | Returns the address city, town, or village. |
| [getCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md#getcountrycode)() | Returns the address two-character ISO 3166-1 code that identifies the country or region. |
| [getFullName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md#getfullname)() | Returns the address full name. |
| [getPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md#getpostalcode)() | Returns the address postal code. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### addressLine1
- addressLine1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address line 1.


---

### addressLine2
- addressLine2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address line 2.


---

### adminArea1
- adminArea1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address highest level sub-division in a country, which is usually a province, state, or ISO-3166-2
      subdivision.



---

### adminArea2
- adminArea2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address city, town, or village.


---

### countryCode
- countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address two-character ISO 3166-1 code that identifies the country or region.


---

### fullName
- fullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address full name.


---

### postalCode
- postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address postal code.


---

## Method Details

### getAddressLine1()
- getAddressLine1(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address line 1.

    **Returns:**
    - address line 1


---

### getAddressLine2()
- getAddressLine2(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address line 2.

    **Returns:**
    - address line 2


---

### getAdminArea1()
- getAdminArea1(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address highest level sub-division in a country, which is usually a province, state, or ISO-3166-2
      subdivision.


    **Returns:**
    - address highest level sub-division in a country, such as a state


---

### getAdminArea2()
- getAdminArea2(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address city, town, or village.

    **Returns:**
    - address city, town, or village


---

### getCountryCode()
- getCountryCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address two-character ISO 3166-1 code that identifies the country or region.

    **Returns:**
    - address country code


---

### getFullName()
- getFullName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address full name.

    **Returns:**
    - address full name


---

### getPostalCode()
- getPostalCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address postal code.

    **Returns:**
    - address postal code


---

<!-- prettier-ignore-end -->

<!-- document id=80478ed35aa47676a219b66f4396e24725edbb96cec577ae274978165cfb745c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePayPalOrderPayer.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePayPalOrderPayer

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePayPalOrderPayer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md)



Salesforce Payments representation of a PayPal order's payer object. See Salesforce Payments documentation
for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [emailAddress](#emailaddress): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the payer's email address. |
| [givenName](#givenname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the payer's given name. |
| [phone](#phone): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the payer's national phone number. |
| [surname](#surname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the payer's surname. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getEmailAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getemailaddress)() | Returns the payer's email address. |
| [getGivenName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getgivenname)() | Returns the payer's given name. |
| [getPhone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getphone)() | Returns the payer's national phone number. |
| [getSurname](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getsurname)() | Returns the payer's surname. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### emailAddress
- emailAddress: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the payer's email address.


---

### givenName
- givenName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the payer's given name.


---

### phone
- phone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the payer's national phone number.


---

### surname
- surname: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the payer's surname.


---

## Method Details

### getEmailAddress()
- getEmailAddress(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payer's email address.

    **Returns:**
    - payer's email address


---

### getGivenName()
- getGivenName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payer's given name.

    **Returns:**
    - payer's given name


---

### getPhone()
- getPhone(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payer's national phone number.

    **Returns:**
    - payer's national phone number


---

### getSurname()
- getSurname(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the payer's surname.

    **Returns:**
    - payer's surname


---

<!-- prettier-ignore-end -->

<!-- document id=00eccdcc4ce46ba9a75bab11778ab29471d0572c28dc44b6ea1b61169300abb8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforcePayPalPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforcePayPalPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforcePayPalPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePayPalOrder.TYPE_PAYPAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_paypal). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [captureID](#captureid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the capture against the PayPal order, or `null` if not known. |
| [payerEmailAddress](#payeremailaddress): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the email address of the payer for the PayPal order, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCaptureID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalPaymentDetails.md#getcaptureid)() | Returns the ID of the capture against the PayPal order, or `null` if not known. |
| [getPayerEmailAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalPaymentDetails.md#getpayeremailaddress)() | Returns the email address of the payer for the PayPal order, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### captureID
- captureID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the capture against the PayPal order, or `null` if not known.

    **See Also:**
    - [SalesforcePayPalOrder.getCaptureID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getcaptureid)


---

### payerEmailAddress
- payerEmailAddress: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the email address of the payer for the PayPal order, or `null` if not known.

    **See Also:**
    - [SalesforcePayPalOrderPayer.getEmailAddress()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getemailaddress)


---

## Method Details

### getCaptureID()
- getCaptureID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the capture against the PayPal order, or `null` if not known.

    **Returns:**
    - PayPal order capture ID

    **See Also:**
    - [SalesforcePayPalOrder.getCaptureID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getcaptureid)


---

### getPayerEmailAddress()
- getPayerEmailAddress(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the payer for the PayPal order, or `null` if not known.

    **Returns:**
    - payer email address

    **See Also:**
    - [SalesforcePayPalOrderPayer.getEmailAddress()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getemailaddress)


---

<!-- prettier-ignore-end -->

<!-- document id=d6032ea8ec859190afbf7e8063e08d880e4cc42a8101999972fb3b815f2af10b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceSepaDebitPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforceSepaDebitPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforceSepaDebitPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceSepaDebitPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [last4](#last4): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the last 4 digits of the account number, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getLast4](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceSepaDebitPaymentDetails.md#getlast4)() | Returns the last 4 digits of the account number, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### last4
- last4: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the last 4 digits of the account number, or `null` if not known.

    **See Also:**
    - [SalesforcePaymentMethod.getLast4()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getlast4)


---

## Method Details

### getLast4()
- getLast4(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the last 4 digits of the account number, or `null` if not known.

    **Returns:**
    - last 4 digits of the account number

    **See Also:**
    - [SalesforcePaymentMethod.getLast4()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#getlast4)


---

<!-- prettier-ignore-end -->

<!-- document id=31506629cb44b9f5d7f3bb8fd6649bf06a5c3dd0f069db8bb625eda6fb0dd860 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.SalesforceVenmoPaymentDetails.md -->

<!-- prettier-ignore-start -->
# Class SalesforceVenmoPaymentDetails

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.extensions.payments.SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)
    - [dw.extensions.payments.SalesforceVenmoPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceVenmoPaymentDetails.md)



Details to a Salesforce Payments payment of type [SalesforcePayPalOrder.TYPE_VENMO](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_venmo). See Salesforce Payments
documentation for how to gain access and configure it for use on your sites.



## Property Summary

| Property | Description |
| --- | --- |
| [captureID](#captureid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the capture against the PayPal Venmo order, or `null` if not known. |
| [payerEmailAddress](#payeremailaddress): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the email address of the payer for the PayPal Venmo order, or `null` if not known. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCaptureID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceVenmoPaymentDetails.md#getcaptureid)() | Returns the ID of the capture against the PayPal Venmo order, or `null` if not known. |
| [getPayerEmailAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceVenmoPaymentDetails.md#getpayeremailaddress)() | Returns the email address of the payer for the PayPal Venmo order, or `null` if not known. |

### Methods inherited from class SalesforcePaymentDetails

[getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### captureID
- captureID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the capture against the PayPal Venmo order, or `null` if not known.

    **See Also:**
    - [SalesforcePayPalOrder.getCaptureID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getcaptureid)


---

### payerEmailAddress
- payerEmailAddress: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the email address of the payer for the PayPal Venmo order, or `null` if not known.

    **See Also:**
    - [SalesforcePayPalOrderPayer.getEmailAddress()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getemailaddress)


---

## Method Details

### getCaptureID()
- getCaptureID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the capture against the PayPal Venmo order, or `null` if not known.

    **Returns:**
    - PayPal order capture ID

    **See Also:**
    - [SalesforcePayPalOrder.getCaptureID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#getcaptureid)


---

### getPayerEmailAddress()
- getPayerEmailAddress(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email address of the payer for the PayPal Venmo order, or `null` if not known.

    **Returns:**
    - payer email address

    **See Also:**
    - [SalesforcePayPalOrderPayer.getEmailAddress()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md#getemailaddress)


---

<!-- prettier-ignore-end -->

<!-- document id=887f32693d85ec3d034a3e7a0c6649960b63bfc9a5c59004340215c472f16281 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.SearchModel.md -->

<!-- prettier-ignore-start -->
# Class SearchModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md)

Common search model base class.


## All Known Subclasses
[ContentSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md), [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md)
## Constant Summary

| Constant | Description |
| --- | --- |
| [SEARCH_PHRASE_PARAMETER](#search_phrase_parameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "q" | URL Parameter for the Search Phrase |
| [SORT_DIRECTION_ASCENDING](#sort_direction_ascending): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Sorting parameter ASCENDING |
| [SORT_DIRECTION_DESCENDING](#sort_direction_descending): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Sorting parameter DESCENDING |
| [SORT_DIRECTION_NONE](#sort_direction_none): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Sorting parameter NO\_SORT - will remove a sorting condition |

## Property Summary

| Property | Description |
| --- | --- |
| [count](#count): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the number of search results found by this search. |
| [emptyQuery](#emptyquery): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the query is emtpy when no search term, search parameter or  refinement was specified for the search. |
| [refinedByAttribute](#refinedbyattribute): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | The method returns true, if this search is refined by at least one  attribute. |
| [refinedSearch](#refinedsearch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this was a refined search. |
| [searchPhrase](#searchphrase): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the search phrase used in this search. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#addrefinementvaluesstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a refinement. |
| [canRelax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#canrelax)() | Identifies if the search can be relaxed without creating a search for all  searchable items. |
| [getCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getcount)() | Returns the number of search results found by this search. |
| [getRefinementMaxValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementmaxvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the maximum refinement value selected in the query for the specific  attribute, or null if there is no maximum refinement value or no refinement for that attribute. |
| [getRefinementMinValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementminvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the minimum refinement value selected in the query for the specific  attribute, or null if there is no minimum refinement value or no refinement for that attribute. |
| ~~[getRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns the refinement value selected in the query for the specific  attribute, or null if there is no refinement for that attribute. |
| [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the list of selected refinement values for the given attribute as  used in the search. |
| [getSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsearchphrase)() | Returns the search phrase used in this search. |
| static [getSearchRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsearchredirectstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an URLRedirect object for a search phrase. |
| [getSortingCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getsortingconditionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the sorting condition for a given attribute name. |
| [isEmptyQuery](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isemptyquery)() | Identifies if the query is emtpy when no search term, search parameter or  refinement was specified for the search. |
| [isRefinedByAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattribute)() | The method returns true, if this search is refined by at least one  attribute. |
| [isRefinedByAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if this search has been refined on the given attribute. |
| [isRefinedByAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedbyattributevaluestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if this search has been refined on the given attribute and  value. |
| [isRefinedSearch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinedsearch)() | Identifies if this was a refined search. |
| [isRefinementByValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinementbyvaluerangestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if this search has been refined on the given attribute. |
| [isRefinementByValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#isrefinementbyvaluerangestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Identifies if this search has been refined on the given attribute and range values. |
| [removeRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#removerefinementvaluesstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Removes a refinement. |
| [search](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#search)() | Execute the search. |
| [setRefinementValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setrefinementvaluerangestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets a refinement value range for an attribute. |
| [setRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setrefinementvaluesstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets refinement values for an attribute. |
| [setSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setsearchphrasestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the search phrase used in this search. |
| [setSortingCondition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#setsortingconditionstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets or removes a sorting condition for the specified attribute. |
| [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlurl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Constructs an URL that you can use to re-execute the exact same query. |
| [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the exact same query. |
| [urlDefaultSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urldefaultsorturl)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | Constructs an URL that you can use to re-execute the query with a default  sorting. |
| [urlDefaultSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urldefaultsortstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query with a default  sorting. |
| [urlRefineAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributeurl-string-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query with an  additional refinement. |
| [urlRefineAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query with an  additional refinement. |
| [urlRefineAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevalueurl-string-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query with an  additional refinement value for a given refinement attribute. |
| [urlRefineAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevaluestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query with an  additional refinement value for a given refinement attribute. |
| [urlRefineAttributeValueRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributevaluerangestring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query with an additional refinement value range for a given refinement attribute. |
| [urlRelaxAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributeurl-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query without the  specified refinement. |
| [urlRelaxAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query without the  specified refinement. |
| [urlRelaxAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributevalueurl-string-string)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query without the  specified refinement value. |
| [urlRelaxAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrelaxattributevaluestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL that you can use to re-execute the query without the  specified refinement. |
| [urlSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlsorturl-string-number)([URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs an URL that you can use to re-execute the query with a  specific sorting criteria. |
| [urlSort](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlsortstring-string-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs an URL that you can use to re-execute the query with a  specific sorting criteria. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### SEARCH_PHRASE_PARAMETER

- SEARCH_PHRASE_PARAMETER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "q"
  - : URL Parameter for the Search Phrase


---

### SORT_DIRECTION_ASCENDING

- SORT_DIRECTION_ASCENDING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Sorting parameter ASCENDING


---

### SORT_DIRECTION_DESCENDING

- SORT_DIRECTION_DESCENDING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Sorting parameter DESCENDING


---

### SORT_DIRECTION_NONE

- SORT_DIRECTION_NONE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Sorting parameter NO\_SORT - will remove a sorting condition


---

## Property Details

### count
- count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the number of search results found by this search.


---

### emptyQuery
- emptyQuery: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the query is emtpy when no search term, search parameter or
      refinement was specified for the search. In case also no result is
      returned. This "empty" is different to a query with a specified query and
      with an empty result.



---

### refinedByAttribute
- refinedByAttribute: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : The method returns true, if this search is refined by at least one
      attribute.



---

### refinedSearch
- refinedSearch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this was a refined search. A search is a refined search if
      at least one refinement is part of the query.



---

### searchPhrase
- searchPhrase: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the search phrase used in this search.


---

## Method Details

### addRefinementValues(String, String)
- addRefinementValues(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), values: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a refinement. The method can be called to add an additional query
      parameter specified as name-value pair. The values string may encode
      multiple values delimited by the pipe symbol ('|').


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - values - the refinement value to set


---

### canRelax()
- canRelax(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the search can be relaxed without creating a search for all
      searchable items.


    **Returns:**
    - true if the search can be relaxed without creating a search for
              all searchable items, false otherwise.



---

### getCount()
- getCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of search results found by this search.

    **Returns:**
    - the number of search results found by this search.


---

### getRefinementMaxValue(String)
- getRefinementMaxValue(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the maximum refinement value selected in the query for the specific
      attribute, or null if there is no maximum refinement value or no refinement for that attribute.


    **Parameters:**
    - attributeID - the attribute whose refinement value is returned.

    **Returns:**
    - the maximum refinement value selected in the query for the specific
              attribute.



---

### getRefinementMinValue(String)
- getRefinementMinValue(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the minimum refinement value selected in the query for the specific
      attribute, or null if there is no minimum refinement value or no refinement for that attribute.


    **Parameters:**
    - attributeID - the attribute whose refinement value is returned.

    **Returns:**
    - the minimum refinement value selected in the query for the specific
              attribute.



---

### getRefinementValue(String)
- ~~getRefinementValue(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the refinement value selected in the query for the specific
      attribute, or null if there is no refinement for that attribute.


    **Parameters:**
    - attributeID - the attribute whose refinement value is returned.

    **Returns:**
    - the refinement value selected in the query for the specific
              attribute.


    **Deprecated:**
**warning:** Use [getRefinementValues(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#getrefinementvaluesstring) to get the
            collection of refinement values.

---

### getRefinementValues(String)
- getRefinementValues(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the list of selected refinement values for the given attribute as
      used in the search.


    **Parameters:**
    - attributeID - The name of the refinement attribute.

    **Returns:**
    - A list of values currently selected for the refinement attribute.


---

### getSearchPhrase()
- getSearchPhrase(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the search phrase used in this search.

    **Returns:**
    - the search phrase used in this search.


---

### getSearchRedirect(String)
- static getSearchRedirect(searchPhrase: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)
  - : Returns an URLRedirect object for a search phrase.

    **Parameters:**
    - searchPhrase - a search phrase to lookup a URLRedirect for

    **Returns:**
    - URLRedirect containing the location and status code,
        null in case no redirect was found for the search phrase.



---

### getSortingCondition(String)
- getSortingCondition(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the sorting condition for a given attribute name. A value of 0
      indicates that no sorting condition is set.


    **Parameters:**
    - attributeID - the attribute name

    **Returns:**
    - zero if no sorting order set, or the sorting order


---

### isEmptyQuery()
- isEmptyQuery(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the query is emtpy when no search term, search parameter or
      refinement was specified for the search. In case also no result is
      returned. This "empty" is different to a query with a specified query and
      with an empty result.


    **Returns:**
    - true if the query is emtpy when no search term, search parameter
              or refinement was specified for the search.



---

### isRefinedByAttribute()
- isRefinedByAttribute(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if this search is refined by at least one
      attribute.


    **Returns:**
    - true, if the search is refined by at least one attribute, false
              otherwise.



---

### isRefinedByAttribute(String)
- isRefinedByAttribute(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined on the given attribute.

    **Parameters:**
    - attributeID - The ID of the refinement attribute.

    **Returns:**
    - True if the search is refined on the attribute, false otherwise.


---

### isRefinedByAttributeValue(String, String)
- isRefinedByAttributeValue(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined on the given attribute and
      value.


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - value - The value to be checked for inclusion in the refinement.

    **Returns:**
    - True if the search is refined on the attribute and value, false
              otherwise.



---

### isRefinedSearch()
- isRefinedSearch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this was a refined search. A search is a refined search if
      at least one refinement is part of the query.


    **Returns:**
    - true if this is a refined search, false otherwise.


---

### isRefinementByValueRange(String)
- isRefinementByValueRange(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined on the given attribute.

    **Parameters:**
    - attributeID - The ID of the refinement attribute.

    **Returns:**
    - True if the search is refined on the attribute, false otherwise.


---

### isRefinementByValueRange(String, String, String)
- isRefinementByValueRange(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), minValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this search has been refined on the given attribute and range values.

    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - minValue - The minimum value to be checked for inclusion in the refinement.
    - maxValue - The maximum value to be checked for inclusion in the refinement.

    **Returns:**
    - True if the search is refined on the attribute and range values, false otherwise.


---

### removeRefinementValues(String, String)
- removeRefinementValues(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), values: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Removes a refinement. The method can be called to remove previously added
      refinement values. The values string may encode multiple values delimited
      by the pipe symbol ('|').


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - values - the refinement value to remove or null to remove all values


---

### search()
- search(): [SearchStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md)
  - : Execute the search.

    **Returns:**
    - the searchStatus object with search status code and description of search result.


---

### setRefinementValueRange(String, String, String)
- setRefinementValueRange(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), minValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets a refinement value range for an attribute. The method can be called to set
      an additional range query parameter specified as name-range-value pair. The values
      string can contain only a range boundary.
      Existing refinement values for the attribute will be removed.


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - minValue - the minimum refinement boundary value to set or null to remove the minimum boundary
    - maxValue - the maximum refinement boundary value to set or null to remove the maximum boundary


---

### setRefinementValues(String, String)
- setRefinementValues(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), values: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets refinement values for an attribute. The method can be called to set
      an additional query parameter specified as name-value pair. The value
      string may encode multiple values delimited by the pipe symbol ('|').
      Existing refinement values for the attribute will be removed.


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - values - the refinement values to set (delimited by '|') or null to             remove all values


---

### setSearchPhrase(String)
- setSearchPhrase(phrase: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the search phrase used in this search. The search query parser uses
      the following operators:
      
      
      - PHRASE operator (""), e.g. "cream cheese", "John Lennon"
      - NOT operator (-), e.g. -cargo (will not return results containing  "cargo")
      - WILDCARD operator (\*), e.g. sho\* (will return results containing  "shoulder", "shoes" and "shoot")


    **Parameters:**
    - phrase - the search phrase used in this search.


---

### setSortingCondition(String, Number)
- setSortingCondition(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), direction: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets or removes a sorting condition for the specified attribute. Specify
      either SORT\_DIRECTION\_ASCENDING or SORT\_DIRECTION\_DESCENDING to set a
      sorting condition. Specify SORT\_DIRECTION\_NONE to remove a sorting
      condition from the attribute.


    **Parameters:**
    - attributeID - the attribute ID
    - direction - SORT\_DIRECTION\_ASCENDING, SORT\_DIRECTION\_DESCENDING or             SORT\_DIRECTION\_NONE


---

### url(URL)
- url(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the exact same query.
      The search specific parameter are appended to the provided URL. The URL
      is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - the url to use.

    **Returns:**
    - a new url URL that can be used to re-execute the exact same
              query.



---

### url(String)
- url(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the exact same query.
      The provided parameter must be an action, e.g. 'Search-Show'.


    **Parameters:**
    - action - the pipeline action.

    **Returns:**
    - an URL that can be used to re-execute the exact same query.


---

### urlDefaultSort(URL)
- urlDefaultSort(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with a default
      sorting. The search specific parameters are appended to the provided URL.
      The URL is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - url or pipeline name

    **Returns:**
    - the new URL.


---

### urlDefaultSort(String)
- urlDefaultSort(url: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with a default
      sorting. The provided parameter must be an action, e.g. 'Search-Show'.


    **Parameters:**
    - url - url or pipeline name

    **Returns:**
    - the new URL.


---

### urlRefineAttribute(URL, String, String)
- urlRefineAttribute(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with an
      additional refinement. The search specific parameters are appended to the
      provided URL. The URL is typically generated with one of the URLUtils
      methods.


    **Parameters:**
    - url - url
    - attributeID - the ID of the refinement attribute
    - value - value for the refinement attribute

    **Returns:**
    - the new URL.


---

### urlRefineAttribute(String, String, String)
- urlRefineAttribute(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with an
      additional refinement.


    **Parameters:**
    - action - the pipeline action.
    - attributeID - the ID of the refinement attribute.
    - value - the value for the refinement attribute.

    **Returns:**
    - the new URL.


---

### urlRefineAttributeValue(URL, String, String)
- urlRefineAttributeValue(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with an
      additional refinement value for a given refinement attribute. The
      provided value will be added to the set of allowed values for the
      refinement attribute. This basically broadens the search result.
      
      The search specific parameters are appended to the provided URL. The URL
      is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - url
    - attributeID - ID of the refinement attribute
    - value - the additional value for the refinement attribute

    **Returns:**
    - the new URL.


---

### urlRefineAttributeValue(String, String, String)
- urlRefineAttributeValue(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with an
      additional refinement value for a given refinement attribute. The
      provided value will be added to the set of allowed values for the
      refinement attribute. This basically broadens the search result.


    **Parameters:**
    - action - the pipeline action.
    - attributeID - the ID of the refinement attribute.
    - value - the additional value for the refinement attribute.

    **Returns:**
    - the new URL.


---

### urlRefineAttributeValueRange(String, String, String, String)
- urlRefineAttributeValueRange(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), minValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with an additional refinement value range for a given refinement attribute. The
      provided value range will be replace to the existing value range for the refinement attribute.
      
      The search specific parameters are appended to the provided URL. The URL is typically generated with one of the URLUtils methods.


    **Parameters:**
    - action - the pipeline action.
    - attributeID - ID of the refinement attribute
    - minValue - the min value for the refinement attribute
    - maxValue - the max value for the refinement attribute

    **Returns:**
    - the new URL.


---

### urlRelaxAttribute(URL, String)
- urlRelaxAttribute(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query without the
      specified refinement. The search specific parameters are appended to the
      provided URL. The URL is typically generated with one of the URLUtils
      methods.


    **Parameters:**
    - url - the url to use.
    - attributeID - the ID of the refinement attribute to be removed.

    **Returns:**
    - the new URL.


---

### urlRelaxAttribute(String, String)
- urlRelaxAttribute(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query without the
      specified refinement. The value for the action parameter must be a
      pipeline action, e.g. 'Search-Show'.


    **Parameters:**
    - action - the pipeline action.
    - attributeID - ID of the refinement attribute to be removed

    **Returns:**
    - the new URL.


---

### urlRelaxAttributeValue(URL, String, String)
- urlRelaxAttributeValue(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query without the
      specified refinement value. The search specific parameters are appended
      to the provided URL. The URL is typically generated with one of the
      URLUtils methods.


    **Parameters:**
    - url - the url to use.
    - attributeID - the ID of the refinement attribute to relax the value for.
    - value - the value that should be removed from the list of refinement             values.

    **Returns:**
    - the new URL.


---

### urlRelaxAttributeValue(String, String, String)
- urlRelaxAttributeValue(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query without the
      specified refinement. The value for the action parameter must be a
      pipeline action, e.g. 'Search-Show'.


    **Parameters:**
    - action - the pipeline action.
    - attributeID - ID of the refinement attribute to be removed
    - value - the value that should be removed from the list of refinement             values.

    **Returns:**
    - the new URL.


---

### urlSort(URL, String, Number)
- urlSort(url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md), sortBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortDir: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with a
      specific sorting criteria. This criteria will overwrite all previous sort
      critiria. The search specific parameters are appended to the provided
      URL. The URL is typically generated with one of the URLUtils methods.


    **Parameters:**
    - url - URL
    - sortBy - ID of the sort attribute
    - sortDir - Sort direction. 1 - ASCENDING (default), 2 - DESCENDING

    **Returns:**
    - The new URL.


---

### urlSort(String, String, Number)
- urlSort(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortBy: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortDir: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Constructs an URL that you can use to re-execute the query with a
      specific sorting criteria. This criteria will overwrite all previous sort
      critiria. The provided parameter must be an action, e.g. 'Search-Show'.


    **Parameters:**
    - action - Pipeline action
    - sortBy - ID of the sort attribute
    - sortDir - Sort direction. 1 - ASCENDING (default), 2 - DESCENDING

    **Returns:**
    - The new URL.


---

<!-- prettier-ignore-end -->

<!-- document id=84d13c35feb8af6d527ee122f56536cf556b9ec28530555290a66e746ae55fa3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SearchPhraseSuggestions.md -->

<!-- prettier-ignore-start -->
# Class SearchPhraseSuggestions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md)

The search phrase suggestions contain a list of suggested search phrases
(see [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md))
as well as, for each of the search phrase terms, a list with corrected and
completed alternative terms.



## Property Summary

| Property | Description |
| --- | --- |
| [suggestedPhrases](#suggestedphrases): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the  user input search phrase. |
| [suggestedTerms](#suggestedterms): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedphrases)() | Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the  user input search phrase. |
| [getSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms)() | Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. |
| [hasSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#hassuggestedphrases)() | Returns whether this suggestions container has any suggested phrases. |
| [hasSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#hassuggestedterms)() | Returns whether this suggestions container has any suggested terms. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### suggestedPhrases
- suggestedPhrases: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the
      user input search phrase.


    **See Also:**
    - [hasSuggestedPhrases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#hassuggestedphrases)


---

### suggestedTerms
- suggestedTerms: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. Each of the returned
      instances represents a set of terms suggested for a particular single term
      of the user input search phrase.


    **See Also:**
    - [hasSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#hassuggestedterms)


---

## Method Details

### getSuggestedPhrases()
- getSuggestedPhrases(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the
      user input search phrase.


    **Returns:**
    - a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md)s

    **See Also:**
    - [hasSuggestedPhrases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#hassuggestedphrases)


---

### getSuggestedTerms()
- getSuggestedTerms(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. Each of the returned
      instances represents a set of terms suggested for a particular single term
      of the user input search phrase.


    **Returns:**
    - a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) for each term of the user input search phrase

    **See Also:**
    - [hasSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#hassuggestedterms)


---

### hasSuggestedPhrases()
- hasSuggestedPhrases(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this suggestions container has any suggested phrases.
      
      
      Note that this method only looks for suggested phrases. It does not account
      for suggested terms.


    **Returns:**
    - true only if there are phrases available


---

### hasSuggestedTerms()
- hasSuggestedTerms(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this suggestions container has any suggested terms.
      
      
      Note that this method checks suggested terms only,
      but not suggested phrases.


    **Returns:**
    - true only if there are terms available


---

<!-- prettier-ignore-end -->

<!-- document id=ce7634c43014744f2bb6ff3f93fae2f8eae68c397eebee28dfd705ffc2748726 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.SearchRefinementDefinition.md -->

<!-- prettier-ignore-start -->
# Class SearchRefinementDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.SearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md)

Common search refinement definition base class.


## All Known Subclasses
[ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md), [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md)
## Property Summary

| Property | Description |
| --- | --- |
| [attributeID](#attributeid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the attribute ID. |
| [attributeRefinement](#attributerefinement): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if this is an attribute refinement. |
| [cutoffThreshold](#cutoffthreshold): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the cut-off threshold. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name. |
| [valueTypeCode](#valuetypecode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns a code for the data type used for this search refinement definition. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAttributeID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getattributeid)() | Returns the attribute ID. |
| [getCutoffThreshold](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getcutoffthreshold)() | Returns the cut-off threshold. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getdisplayname)() | Returns the display name. |
| [getValueTypeCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#getvaluetypecode)() | Returns a code for the data type used for this search refinement definition. |
| [isAttributeRefinement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md#isattributerefinement)() | Identifies if this is an attribute refinement. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### attributeID
- attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the attribute ID. If the refinement definition is not an
      attribute refinement, the method returns an empty string.



---

### attributeRefinement
- attributeRefinement: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if this is an attribute refinement.


---

### cutoffThreshold
- cutoffThreshold: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the cut-off threshold.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name.


---

### valueTypeCode
- valueTypeCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns a code for the data type used for this search refinement definition. See constants
      defined in ObjectAttributeDefinition.



---

## Method Details

### getAttributeID()
- getAttributeID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the attribute ID. If the refinement definition is not an
      attribute refinement, the method returns an empty string.


    **Returns:**
    - the attribute ID.


---

### getCutoffThreshold()
- getCutoffThreshold(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the cut-off threshold.

    **Returns:**
    - the cut-off threshold.


---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name.

    **Returns:**
    - the display name.


---

### getValueTypeCode()
- getValueTypeCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns a code for the data type used for this search refinement definition. See constants
      defined in ObjectAttributeDefinition.


    **Returns:**
    - a code for the data type used for this search refinement definition. See constants
      defined in ObjectAttributeDefinition.



---

### isAttributeRefinement()
- isAttributeRefinement(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this is an attribute refinement.

    **Returns:**
    - true if this is an attribute refinement, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=017de85a2c3a3884cd6f208ffc502b9cbbceec717102894bc2f8ff711b995a1e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.SearchRefinements.md -->

<!-- prettier-ignore-start -->
# Class SearchRefinements

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md)

Common search refinements base class.


## All Known Subclasses
[ContentSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md), [ProductSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md)
## Constant Summary

| Constant | Description |
| --- | --- |
| [ASCENDING](#ascending): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Flag for an ascending sort. |
| [DESCENDING](#descending): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Flag for a descending sort. |
| [SORT_VALUE_COUNT](#sort_value_count): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Flag for sorting on value count. |
| [SORT_VALUE_NAME](#sort_value_name): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Flag for sorting on value name. |

## Property Summary

| Property | Description |
| --- | --- |
| [allRefinementDefinitions](#allrefinementdefinitions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a sorted list of refinement definitions that are appropriate for  the deepest common category (or deepest common folder) of the search  result. |
| [refinementDefinitions](#refinementdefinitions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a sorted list of refinement definitions that are appropriate for  the deepest common category (or deepest common folder) of the search  result. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAllRefinementDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementdefinitions)() | Returns a sorted list of refinement definitions that are appropriate for  the deepest common category (or deepest common folder) of the search  result. |
| [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementvaluesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a sorted collection of refinement values for the given refinement  attribute. |
| [getAllRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getallrefinementvaluesstring-number-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a sorted collection of refinement values for the given refinement  attribute. |
| [getRefinementDefinitions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementdefinitions)() | Returns a sorted list of refinement definitions that are appropriate for  the deepest common category (or deepest common folder) of the search  result. |
| [getRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md#getrefinementvaluesstring-number-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a collection of refinement values for the given refinement  attribute, sorting mode and sorting direction. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ASCENDING

- ASCENDING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Flag for an ascending sort.


---

### DESCENDING

- DESCENDING: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Flag for a descending sort.


---

### SORT_VALUE_COUNT

- SORT_VALUE_COUNT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Flag for sorting on value count.


---

### SORT_VALUE_NAME

- SORT_VALUE_NAME: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Flag for sorting on value name.


---

## Property Details

### allRefinementDefinitions
- allRefinementDefinitions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a sorted list of refinement definitions that are appropriate for
      the deepest common category (or deepest common folder) of the search
      result. The method concatenates the sorted refinement definitions per
      category starting at the root category until reaching the deepest common
      category.
      
      The method does not filter out refinement definitions that do
      not provide values for the current search result and can therefore also
      be used on empty search results.



---

### refinementDefinitions
- refinementDefinitions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a sorted list of refinement definitions that are appropriate for
      the deepest common category (or deepest common folder) of the search
      result. The method concatenates the sorted refinement definitions per category
      starting at the root category until reaching the deepest common category.
      
      The method also filters out refinement definitions that do not provide
      any values for the current search result.



---

## Method Details

### getAllRefinementDefinitions()
- getAllRefinementDefinitions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted list of refinement definitions that are appropriate for
      the deepest common category (or deepest common folder) of the search
      result. The method concatenates the sorted refinement definitions per
      category starting at the root category until reaching the deepest common
      category.
      
      The method does not filter out refinement definitions that do
      not provide values for the current search result and can therefore also
      be used on empty search results.


    **Returns:**
    - A sorted list of refinement definitions appropriate for the
              search result (based on its deepest common category)



---

### getAllRefinementValues(String)
- getAllRefinementValues(attributeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of refinement values for the given refinement
      attribute. The returned collection includes all refinement values for
      which the hit count is greater than 0 within the search result when the
      passed attribute is excluded from filtering the search hits but all other
      refinement filters are still applied. This method is useful for rendering
      broadening options for attributes that the search is currently refined
      by. This method does NOT return refinement values independent of the
      search result.
      
      
      For product search refinements, this method may return slightly different
      results based on the "value set" property of the refinement definition.
      See
      [ProductSearchRefinements.getAllRefinementValues(ProductSearchRefinementDefinition)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getallrefinementvaluesproductsearchrefinementdefinition)
      for details.


    **Parameters:**
    - attributeName - The name of the attribute to return refinement values             for.

    **Returns:**
    - The collection of SearchRefinementValue instances, sorted
              according to the settings of the refinement definition, or null
              if there is no refinement definition for the passed attribute
              name.



---

### getAllRefinementValues(String, Number, Number)
- getAllRefinementValues(attributeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortMode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), sortDirection: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted collection of refinement values for the given refinement
      attribute. In general, the returned collection includes all refinement
      values for which hit count is greater than 0 within the search result
      assuming that:
      
      
      - The passed refinement attribute is NOT used to filter the search  hits.
      - All other refinements are still applied.
      
      
      This is useful for rendering broadening options for the refinement
      definitions that the search is already refined by. It is important to
      note that this method does NOT return refinement values independent of
      the search result.
      
      
      For product search refinements, this method may return slightly different
      results based on the "value set" of the refinement definition. See
      [ProductSearchRefinements.getAllRefinementValues(ProductSearchRefinementDefinition)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md#getallrefinementvaluesproductsearchrefinementdefinition)
      for details.


    **Parameters:**
    - attributeName - The name of the attribute to return refinement values             for.
    - sortMode - The sort mode to use to control how the collection is             sorted.
    - sortDirection - The sort direction to use.

    **Returns:**
    - The collection of SearchRefinementValue instances, sorted
              according to the passed parameters.



---

### getRefinementDefinitions()
- getRefinementDefinitions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a sorted list of refinement definitions that are appropriate for
      the deepest common category (or deepest common folder) of the search
      result. The method concatenates the sorted refinement definitions per category
      starting at the root category until reaching the deepest common category.
      
      The method also filters out refinement definitions that do not provide
      any values for the current search result.


    **Returns:**
    - A sorted list of refinement definitions appropriate for the
              search result (based on its deepest common category)



---

### getRefinementValues(String, Number, Number)
- getRefinementValues(attributeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortMode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), sortDirection: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of refinement values for the given refinement
      attribute, sorting mode and sorting direction.


    **Parameters:**
    - attributeName - The attribute name to use when collection refinement values.
    - sortMode - The sort mode to use to control how the collection is sorted.
    - sortDirection - The sort direction to use.

    **Returns:**
    - The collection of refinement values.


---

<!-- prettier-ignore-end -->

<!-- document id=e07e1627ec3252b772824fd73565fffddcf599a3f3172b54cd7f8b778d02f4ee url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.SearchRefinementValue.md -->

<!-- prettier-ignore-start -->
# Class SearchRefinementValue

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.SearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md)

Represents the value of a product or content search refinement.


## All Known Subclasses
[ContentSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementValue.md), [ProductSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementValue.md)
## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the refinement value's ID. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the optional refinement value description in the current locale. |
| [displayValue](#displayvalue): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the refinement display value. |
| [hitCount](#hitcount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the hit count value. |
| [presentationID](#presentationid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the optional presentation ID associated with this refinement  value. |
| [value](#value): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the refinement value. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getdescription)() | Returns the optional refinement value description in the current locale. |
| [getDisplayValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getdisplayvalue)() | Returns the refinement display value. |
| [getHitCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#gethitcount)() | Returns the hit count value. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getid)() | Returns the refinement value's ID. |
| [getPresentationID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getpresentationid)() | Returns the optional presentation ID associated with this refinement  value. |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md#getvalue)() | Returns the refinement value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the refinement value's ID. For attribute refinements, this will
      be the ID of the corresponding
      [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md). This ID is included in the
      querystring parameter names returned by the URL-generating methods of
      [SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md). For price and category refinements, this
      value will be empty.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the optional refinement value description in the current locale.


---

### displayValue
- displayValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the refinement display value. For attribute refinements, this is
      the appropriate display value based on optional value display names
      within the object attribute definition. If no display name is defined,
      the value itself is returned. For category refinements, this is the
      display name of the category in the current locale. For price
      refinements, this is a string representation of the range appropriate for
      display.



---

### hitCount
- hitCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the hit count value.


---

### presentationID
- presentationID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the optional presentation ID associated with this refinement
      value. The presentation ID can be used, for example, to associate an ID
      with an HTML widget.



---

### value
- value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the refinement value. For attribute refinements, this is the
      attribute value if the refinement values are unbucketed, or the bucket
      display name if the values are bucketed. This value is included in the
      querystring parameter values returned by the URL-generating methods of
      [SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md). For price refinements, the value will be
      a string representation of the price range lower bound. For category
      refinements, the value will be a category ID.



---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the optional refinement value description in the current locale.

    **Returns:**
    - the optional refinement value description in the current locale,
              or null if none is defined.



---

### getDisplayValue()
- getDisplayValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the refinement display value. For attribute refinements, this is
      the appropriate display value based on optional value display names
      within the object attribute definition. If no display name is defined,
      the value itself is returned. For category refinements, this is the
      display name of the category in the current locale. For price
      refinements, this is a string representation of the range appropriate for
      display.


    **Returns:**
    - the refinement display value in the current locale.


---

### getHitCount()
- getHitCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the hit count value.

    **Returns:**
    - the hit count value.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the refinement value's ID. For attribute refinements, this will
      be the ID of the corresponding
      [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md). This ID is included in the
      querystring parameter names returned by the URL-generating methods of
      [SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md). For price and category refinements, this
      value will be empty.


    **Returns:**
    - the refinement value's ID.


---

### getPresentationID()
- getPresentationID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the optional presentation ID associated with this refinement
      value. The presentation ID can be used, for example, to associate an ID
      with an HTML widget.


    **Returns:**
    - the presentation ID, or null if none is defined.


---

### getValue()
- getValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the refinement value. For attribute refinements, this is the
      attribute value if the refinement values are unbucketed, or the bucket
      display name if the values are bucketed. This value is included in the
      querystring parameter values returned by the URL-generating methods of
      [SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md). For price refinements, the value will be
      a string representation of the price range lower bound. For category
      refinements, the value will be a category ID.


    **Returns:**
    - the refinement value.


---

<!-- prettier-ignore-end -->

<!-- document id=5cc78ad885fcf89cf45c5a749455eb4d6ed55becc94efe205bb58c3f4e090a46 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.SearchStatus.md -->

<!-- prettier-ignore-start -->
# Class SearchStatus

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.SearchStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md)

A SearchStatus is used for communicating a Search API status back to a client. A status consists of status code and
description. More information about search API call can be fetched by using SearchStatus class method getStatusCode
and getDescription, which can be used by clients to perform different operations.



## Constant Summary

| Constant | Description |
| --- | --- |
| [EMPTY_QUERY](#empty_query): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | EMPTY\_QUERY search result status code 6, this indicates that search has been made with empty query. |
| [ERROR](#error): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9 | ERROR search result status code 9, this indicates that internal server error has been occurred. |
| [LIMITED](#limited): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | LIMITED search result status code 2, this indicates that limitations on search result have been applied and  full search result is not returned. |
| [NOT_EXECUTED](#not_executed): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | NOT\_EXECUTED search result status code 0, this indicates that search API call has not been made on SearchModel. |
| [NO_CATALOG](#no_catalog): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | NO\_CATALOG search result status code 4, this indicates that there is no catalog associated for search query. |
| [NO_CATEGORY](#no_category): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | NO\_CATEGORY search result status code 5, this indicates that there is no category associated for search query. |
| [NO_INDEX](#no_index): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | NO\_INDEX search result status code 8, this indicates that there is no active search index available. |
| [OFFLINE_CATEGORY](#offline_category): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | OFFLINE\_CATEGORY search result status code 7, this indicates that the category associated with search query  is offline. |
| [ROOT_SEARCH](#root_search): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | ROOT\_SEARCH search result status code 3, this indicates that search result is returned for ROOT search. |
| [SUCCESSFUL](#successful): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | SUCCESSFUL search result status code 1, this indicates that search API call is executed without any issue. |

## Property Summary

| Property | Description |
| --- | --- |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns status code description of search result, it provides more details about search API call status. |
| [statusCode](#statuscode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns status code of search result, by default it will return 0 which means that search has not been executed  on SearchModel. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md#getdescription)() | Returns status code description of search result, it provides more details about search API call status. |
| [getStatusCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md#getstatuscode)() | Returns status code of search result, by default it will return 0 which means that search has not been executed  on SearchModel. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md#tostring)() | Returns string values of status code and description. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### EMPTY_QUERY

- EMPTY_QUERY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : EMPTY\_QUERY search result status code 6, this indicates that search has been made with empty query.


---

### ERROR

- ERROR: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9
  - : ERROR search result status code 9, this indicates that internal server error has been occurred.


---

### LIMITED

- LIMITED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : LIMITED search result status code 2, this indicates that limitations on search result have been applied and
      full search result is not returned.



---

### NOT_EXECUTED

- NOT_EXECUTED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : NOT\_EXECUTED search result status code 0, this indicates that search API call has not been made on SearchModel.


---

### NO_CATALOG

- NO_CATALOG: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : NO\_CATALOG search result status code 4, this indicates that there is no catalog associated for search query.


---

### NO_CATEGORY

- NO_CATEGORY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : NO\_CATEGORY search result status code 5, this indicates that there is no category associated for search query.


---

### NO_INDEX

- NO_INDEX: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : NO\_INDEX search result status code 8, this indicates that there is no active search index available.


---

### OFFLINE_CATEGORY

- OFFLINE_CATEGORY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : OFFLINE\_CATEGORY search result status code 7, this indicates that the category associated with search query
      is offline.



---

### ROOT_SEARCH

- ROOT_SEARCH: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : ROOT\_SEARCH search result status code 3, this indicates that search result is returned for ROOT search.


---

### SUCCESSFUL

- SUCCESSFUL: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : SUCCESSFUL search result status code 1, this indicates that search API call is executed without any issue.


---

## Property Details

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns status code description of search result, it provides more details about search API call status.


---

### statusCode
- statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns status code of search result, by default it will return 0 which means that search has not been executed
      on SearchModel.



---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns status code description of search result, it provides more details about search API call status.

    **Returns:**
    - search status description


---

### getStatusCode()
- getStatusCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns status code of search result, by default it will return 0 which means that search has not been executed
      on SearchModel.


    **Returns:**
    - search status code


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns string values of status code and description.

    **Returns:**
    - search status string


---

<!-- prettier-ignore-end -->

<!-- document id=692c708e71fb14cbdb4247bd3df8fd1962f384f13f67a8ec146e76fad1cf0ce2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.SecureEncoder.md -->

<!-- prettier-ignore-start -->
# Class SecureEncoder

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.SecureEncoder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md)

SecureEncoder contains many methods for manipulating untrusted data Strings
into RFC-Compliant Strings for a given context by encoding "bad" data into
the proper format.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [forHtmlContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forhtmlcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in a general HTML context. |
| static [forHtmlInDoubleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forhtmlindoublequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in an HTML Attribute guarded by a double  quote. |
| static [forHtmlInSingleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forhtmlinsinglequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in an HTML Attribute guarded by a single  quote. |
| static [forHtmlUnquotedAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forhtmlunquotedattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in an HTML Attribute left unguarded. |
| static [forJSONValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forjsonvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in a JSON Object Value to prevent  escaping into a trusted context. |
| static [forJavaScriptInAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forjavascriptinattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in JavaScript inside an HTML attribute. |
| static [forJavaScriptInBlock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forjavascriptinblockstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in JavaScript inside an HTML block. |
| static [forJavaScriptInHTML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forjavascriptinhtmlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in JavaScript inside an HTML context. |
| static [forJavaScriptInSource](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forjavascriptinsourcestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in JavaScript inside a JavaScript source  file. |
| static [forUriComponent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#foruricomponentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use as a component of a URI. |
| static [forUriComponentStrict](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#foruricomponentstrictstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use as a component of a URI. |
| static [forXmlCommentContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forxmlcommentcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in an XML comments. |
| static [forXmlContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forxmlcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in a general XML context. |
| static [forXmlInDoubleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forxmlindoublequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in an XML attribute guarded by a double  quote. |
| static [forXmlInSingleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md#forxmlinsinglequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Encodes a given input for use in an XML attribute guarded by a single  quote. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### forHtmlContent(String)
- static forHtmlContent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in a general HTML context. E.g.
      text content and text attributes. This method takes the UNION of allowed
      characters between the two context, so may be more imprecise that the
      more specific contexts. Generally, this method is preferred unless you
      specifically understand the context in which untrusted data will be
      output.
      
      
      
      **Example Usage:**
      
      ```
      <div>${SecureEncoder.forHtmlContent(unsafeData)}</div>
      
      <input value="${SecureEncoder.forHtmlContent(unsafeData)}" />
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between 0x7F and 0x9F)  with &\#xfffd;, the Unicode Replacement Character
      - Replace special HTML characters with their HTML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forHtmlInDoubleQuoteAttribute(String)
- static forHtmlInDoubleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in an HTML Attribute guarded by a double
      quote. This method is preferred if you understand exactly how the output
      of this will be used in the HTML document.
      
      
      
      **Example Usage:**
      
      ```
      <div id="${SecureEncoder.forHtmlInDoubleQuoteAttribute(unsafeData)}"></div>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between 0x7F and 0x9F)  with &\#xfffd;, the Unicode Replacement Character
      - Replace special HTML characters with their HTML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forHtmlInSingleQuoteAttribute(String)
- static forHtmlInSingleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in an HTML Attribute guarded by a single
      quote. This method is preferred if you understand exactly how the output
      of this will be used in the HTML document.
      
      
      
      **Example Usage:**
      
      ```
      <div id='${SecureEncoder.forHtmlInSingleQuoteAttribute(unsafeData)}'></div>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between 0x7F and 0x9F)  with &\#xfffd;, the Unicode Replacement Character
      - Replace special HTML characters with their HTML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forHtmlUnquotedAttribute(String)
- static forHtmlUnquotedAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in an HTML Attribute left unguarded.
      This method is preferred if you understand exactly how the output
      of this will be used in the HTML document.
      
      
      
      **Example Usage:**
      
      ```
      <div id=${SecureEncoder.forHtmlUnquotedAttribute(unsafeData)}></div>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between 0x7F and 0x9F)  with &\#xfffd;, the Unicode Replacement Character
      - Replace special HTML characters with their HTML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forJSONValue(String)
- static forJSONValue(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in a JSON Object Value to prevent
      escaping into a trusted context.
      
      
      
      **Example Usage:**
      
      ```
      var json = {"trusted_data" : SecureEncoder.forJSONValue(unsafeData)};
      return JSON.stringify(json);
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics
      - Slash escape certain illegal characters
      - Replace all other characters with their Hex Encoded  equivalents prepended with \\u


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forJavaScriptInAttribute(String)
- static forJavaScriptInAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in JavaScript inside an HTML attribute.
      This method is preferred if you understand exactly how the output
      of the will be used in the page
      
      
      
      **Example Usage:**
      
      ```
      <button onclick="alert('${SecureEncoder.forJavaScriptInAttribute(unsafeData)}');">
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Slash escape certain illegal characters
      - Replace special JavaScript characters with their Hex Encoded  equivalents prepended with \\x for character codes under 128 and  \\u for character codes over 128


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forJavaScriptInBlock(String)
- static forJavaScriptInBlock(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in JavaScript inside an HTML block.
      This method is preferred if you understand exactly how the output
      of the will be used in the page
      
      
      
      **Example Usage:**
      
      ```
      <script type="text/javascript">
          var data = "${SecureEncoder.forJavaScriptInBlock(unsafeData)}";
      </script>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Slash escape certain illegal characters
      - Replace special JavaScript characters with their Hex Encoded  equivalents prepended with \\x for character codes under 128 and  \\u for character codes over 128


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forJavaScriptInHTML(String)
- static forJavaScriptInHTML(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in JavaScript inside an HTML context.
      This method takes the UNION of allowed characters among the other
      contexts, so may be more imprecise that the more specific contexts.
      Generally, this method is preferred unless you specifically understand
      the context in which untrusted data will be output.
      
      
      
      **Example Usage:**
      
      ```
      <script type="text/javascript">
          var data = "${SecureEncoder.forJavaScriptInHTML(unsafeData)}";
      </script>
      
      <button onclick="alert('${SecureEncoder.forJavaScriptInHTML(unsafeData)}');">
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Slash escape certain illegal characters
      - Replace special JavaScript characters with their Hex Encoded  equivalents prepended with \\x for character codes under 128 and  \\u for character codes over 128


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forJavaScriptInSource(String)
- static forJavaScriptInSource(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in JavaScript inside a JavaScript source
      file. This method is preferred if you understand exactly how the output
      of the will be used in the page
      
      
      
      **Example Usage:**
      
      ```
      <...inside foobar.js...>
      var data = "${SecureEncoder.forJavaScriptInSource(unsafeData)}";
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Slash escape certain illegal characters
      - Replace special JavaScript characters with their Hex Encoded  equivalents prepended with \\x for character codes under 128 and  \\u for character codes over 128


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forUriComponent(String)
- static forUriComponent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use as a component of a URI. This is
      equivalent to javascript's encodeURIComponent and does a realistic
      job of encoding.
      
      
      
      **Example Usage:**
      
      ```
      <a href="http://host.com?value=${SecureEncoder.forUriComponent(unsafeData)}"/>
      ```
      
      
      **Allows:**
      
      ```
      A-Z, a-z, 0-9, -, _, ., ~, !, *, ', (, )
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Percent encode all other characters


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forUriComponentStrict(String)
- static forUriComponentStrict(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use as a component of a URI. This is a strict
      encoder and fully complies with RFC3986.
      
      
      
      **Example Usage:**
      
      ```
      <a href="http://host.com?value=${SecureEncoder.forUriComponentStrict(unsafeData)}"/>
      ```
      
      
      **Allows:**
      
      ```
      A-Z, a-z, 0-9, -, _, ., ~
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Percent encode all other characters


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forXmlCommentContent(String)
- static forXmlCommentContent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in an XML comments.
      This method is preferred if you understand the context in which
      untrusted data will be output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <!-- ${SecureEncoder.forXmlCommentContent(unsafeData)} -->
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between  0x7F and 0x84 or between 0x86 and 0x9F or between 0xFDD0 and 0xFDDF)  with an empty string
      - Replace special XML characters with their default XML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forXmlContent(String)
- static forXmlContent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in a general XML context. E.g.
      text content and text attributes. This method takes the UNION of allowed
      characters between the other contexts, so may be more imprecise that the
      more specific contexts. Generally, this method is preferred unless you
      specifically understand the context in which untrusted data will be
      output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <foo>${SecureEncoder.forXmlContent(unsafeData)}</foo>
      
      <bar attr="${SecureEncoder.forXmlContent(unsafeData)}"></bar>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between  0x7F and 0x84 or between 0x86 and 0x9F or between 0xFDD0 and 0xFDDF)  with an empty string
      - Replace special XML characters with their default XML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forXmlInDoubleQuoteAttribute(String)
- static forXmlInDoubleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in an XML attribute guarded by a double
      quote. This method is preferred if you understand the context in which
      untrusted data will be output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <bar attr="${SecureEncoder.forXmlInDoubleQuoteAttribute(unsafeData)}"></bar>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between  0x7F and 0x84 or between 0x86 and 0x9F or between 0xFDD0 and 0xFDDF)  with an empty string
      - Replace special XML characters with their default XML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

### forXmlInSingleQuoteAttribute(String)
- static forXmlInSingleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Encodes a given input for use in an XML attribute guarded by a single
      quote. This method is preferred if you understand the context in which
      untrusted data will be output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <bar attr='${SecureEncoder.forXmlInSingleQuoteAttribute(unsafeData)}'></bar>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Replace Illegal Control Characters (Below 0x1F or between  0x7F and 0x84 or between 0x86 and 0x9F or between 0xFDD0 and 0xFDDF)  with an empty string
      - Replace special XML characters with their default XML Entity equivalents


    **Parameters:**
    - input - untrusted input to be encoded, if necessary

    **Returns:**
    - a properly encoded string for the given input


---

<!-- prettier-ignore-end -->

<!-- document id=c96c6e28973977e141f654f3033d84a16782e271bba89fb8a984561fa14af38c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.SecureFilter.md -->

<!-- prettier-ignore-start -->
# Class SecureFilter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.SecureFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md)

SecureFilter contains many methods for manipulating untrusted data Strings
into RFC-Compliant Strings for a given context by removing "bad" data from
the untrusted data.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [forHtmlContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forhtmlcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in a general HTML  context. |
| static [forHtmlInDoubleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forhtmlindoublequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in an HTML  Attribute guarded by a double quote. |
| static [forHtmlInSingleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forhtmlinsinglequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in an HTML  Attribute guarded by a single quote. |
| static [forHtmlUnquotedAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forhtmlunquotedattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in an HTML  Attribute left unguarded. |
| static [forJSONValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forjsonvaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in a JSON Object  Value to prevent escaping into a trusted context. |
| static [forJavaScriptInAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forjavascriptinattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in JavaScript  inside an HTML attribute. |
| static [forJavaScriptInBlock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forjavascriptinblockstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in JavaScript  inside an HTML block. |
| static [forJavaScriptInHTML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forjavascriptinhtmlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in JavaScript  inside an HTML context. |
| static [forJavaScriptInSource](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forjavascriptinsourcestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in JavaScript  inside a JavaScript source file. |
| static [forUriComponent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#foruricomponentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use as a component  of a URI. |
| static [forUriComponentStrict](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#foruricomponentstrictstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use as a component  of a URI. |
| static [forXmlCommentContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forxmlcommentcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in an XML  comments. |
| static [forXmlContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forxmlcontentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in a general XML  context. |
| static [forXmlInDoubleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forxmlindoublequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in an XML  attribute guarded by a double quote. |
| static [forXmlInSingleQuoteAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md#forxmlinsinglequoteattributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Filters illegal characters from a given input for use in an XML  attribute guarded by a single quote. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### forHtmlContent(String)
- static forHtmlContent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in a general HTML
      context. E.g. text content and text attributes. This method takes the
      UNION of allowed characters among all contexts, so may be more
      imprecise that the more specific contexts. Generally, this method is
      preferred unless you specifically understand the context in which
      untrusted data will be output.
      
      
      
      **Example Usage:**
      
      ```
      <div>${SecureFilter.forHtmlContent(unsafeData)}</div>
      
      <input value="${SecureFilter.forHtmlContent(unsafeData)}" />
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forHtmlInDoubleQuoteAttribute(String)
- static forHtmlInDoubleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in an HTML
      Attribute guarded by a double quote. This method is preferred if you
      understand exactly how the output of this will be used in the HTML
      document.
      
      
      
      **Example Usage:**
      
      ```
      <div id="${SecureFilter.forHtmlInDoubleQuoteAttribute(unsafeData)}"></div>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forHtmlInSingleQuoteAttribute(String)
- static forHtmlInSingleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in an HTML
      Attribute guarded by a single quote. This method is preferred if you
      understand exactly how the output of this will be used in the HTML
      document.
      
      
      
      **Example Usage:**
      
      ```
      <div id='${SecureFilter.forHtmlInSingleQuoteAttribute(unsafeData)}'></div>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filterd, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forHtmlUnquotedAttribute(String)
- static forHtmlUnquotedAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in an HTML
      Attribute left unguarded. This method is preferred if you understand
      exactly how the output of this will be used in the HTML document.
      
      
      
      **Example Usage:**
      
      ```
      <div id=${SecureFilter.forHtmlUnquotedAttribute(unsafeData)}></div>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forJSONValue(String)
- static forJSONValue(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in a JSON Object
      Value to prevent escaping into a trusted context.
      
      
      
      **Example Usage:**
      
      ```
      var json = {"trusted_data" : SecureFilter.forJSONValue(unsafeData)};
      return JSON.stringify(json);
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics
      - Remove all other characters


    **Parameters:**
    - input - ed input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forJavaScriptInAttribute(String)
- static forJavaScriptInAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in JavaScript
      inside an HTML attribute. This method is preferred if you understand
      exactly how the output of the will be used in the page
      
      
      
      **Example Usage:**
      
      ```
      <button onclick="alert('${SecureFilter.forJavaScriptInAttribute(unsafeData)}');">
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forJavaScriptInBlock(String)
- static forJavaScriptInBlock(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in JavaScript
      inside an HTML block. This method is preferred if you understand
      exactly how the output of the will be used in the page
      
      
      
      **Example Usage:**
      
      ```
      <script type="text/javascript">
          var data = "${SecureFilter.forJavaScriptInBlock(unsafeData)}";
      </script>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forJavaScriptInHTML(String)
- static forJavaScriptInHTML(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in JavaScript
      inside an HTML context. This method takes the UNION of allowed
      characters among the other contexts, so may be more imprecise that the
      more specific contexts. Generally, this method is preferred unless you
      specifically understand the context in which untrusted data will be
      output.
      
      
      
      **Example Usage:**
      
      ```
      <script type="text/javascript">
          var data = "${SecureFilter.forJavaScriptInHTML(unsafeData)}";
      </script>
      
      <button onclick="alert('${SecureFilter.forJavaScriptInHTML(unsafeData)}');">
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forJavaScriptInSource(String)
- static forJavaScriptInSource(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in JavaScript
      inside a JavaScript source file. This method is preferred if you
      understand exactly how the output of the will be used in the page
      
      
      
      **Example Usage:**
      
      ```
      <...inside foobar.js...>
      var data = "${SecureFilter.forJavaScriptInSource(unsafeData)}";
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forUriComponent(String)
- static forUriComponent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use as a component
      of a URI. This is equivalent to javascript's filterURIComponent and
      does a realistic job of encoding.
      
      
      
      **Example Usage:**
      
      ```
      <a href="http://host.com?value=${SecureFilter.forUriComponent(unsafeData)}"/>
      ```
      
      
      **Allows:**
      
      ```
      A-Z, a-z, 0-9, -, _, ., ~, !, *, ', (, )
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forUriComponentStrict(String)
- static forUriComponentStrict(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use as a component
      of a URI. This is a strict filter and fully complies with RFC3986.
      
      
      
      **Example Usage:**
      
      ```
      <a href="http://host.com?value=${SecureFilter.forUriComponentStrict(unsafeData)}"/>
      ```
      
      
      **Allows:**
      
      ```
      A-Z, a-z, 0-9, -, _, ., ~
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forXmlCommentContent(String)
- static forXmlCommentContent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in an XML
      comments. This method is preferred if you understand the context in
      which untrusted data will be output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <!-- ${SecureFilter.forXmlCommentContent(unsafeData)} -->
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forXmlContent(String)
- static forXmlContent(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in a general XML
      context. E.g. text content and text attributes. This method takes the
      UNION of allowed characters between the other contexts, so may be more
      imprecise that the more specific contexts. Generally, this method is
      preferred unless you specifically understand the context in which
      untrusted data will be output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <foo>${SecureFilter.forXmlContent(unsafeData)}</foo>
      
      <bar attr="${SecureFilter.forXmlContent(unsafeData)}"></bar>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forXmlInDoubleQuoteAttribute(String)
- static forXmlInDoubleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in an XML
      attribute guarded by a double quote. This method is preferred if you
      understand the context in which untrusted data will be output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <bar attr="${SecureFilter.forXmlInDoubleQuoteAttribute(unsafeData)}"></bar>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

### forXmlInSingleQuoteAttribute(String)
- static forXmlInSingleQuoteAttribute(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : 
      
      Filters illegal characters from a given input for use in an XML
      attribute guarded by a single quote. This method is preferred if you
      understand the context in which untrusted data will be output.
      
      
      
      **Note: It is recommended that you use a real parser, as this method
       can be misused, but is left here if a parser is unavailable to you**
      
      
      **Example Usage:**
      
      ```
      <bar attr='${SecureFilter.forXmlInSingleQuoteAttribute(unsafeData)}'></bar>
      ```
      
      
      **Flow:**
      
      - Allow AlphaNumerics and some Special characters
      - Remove all other characters


    **Parameters:**
    - input - untrusted input to be filtered, if necessary

    **Returns:**
    - a properly filtered string for the given input


---

<!-- prettier-ignore-end -->

<!-- document id=516b09038090f120bf3256e0ccf8fabe96039a169f0c8a030cd5c18b04b52bb7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.SecureRandom.md -->

<!-- prettier-ignore-start -->
# Class SecureRandom

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.SecureRandom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md)

The SecureRandom class provides a cryptographically strong random number generator (RNG).
See the Internet Engineering Task Force (IETF) RFC 1750: _Randomness Recommendations for
 Security_ for more information.]()


 Typical callers of SecureRandom invoke the following methods to retrieve random bytes:


```
     Bytes bytes...
     SecureRandom random = new SecureRandom();
     Bytes nextBytes = random.nextBytes(bytes);
```


or more convenient to get a Bytes with the demanded length


```
     int length = 32;
     SecureRandom random = new SecureRandom();
     Bytes nextBytes = random.nextBytes(length);
```


dw.crypto.SecureRandom is intentionally an adapter for generating cryptographic hard random numbers.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SecureRandom](#securerandom)() | Instantiates a new secure random. |

## Method Summary

| Method | Description |
| --- | --- |
| [generateSeed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md#generateseednumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the given number of seed bytes, computed using the seed  generation algorithm that this class uses to seed itself. |
| [nextBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md#nextbytesnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Generates a user-specified number of random bytes. |
| [nextInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md#nextint)() | Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. |
| [nextInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md#nextintnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a pseudorandom, uniformly distributed int value  between 0 (inclusive) and the specified value (exclusive), drawn from  this random number generator's sequence. |
| [nextNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md#nextnumber)() | Returns the next pseudorandom, uniformly distributed  Number value between 0.0 (inclusive) and 1.0 (exclusive) from this random number generator's sequence. |
| [setSeed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md#setseedbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Reseeds this random object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### SecureRandom()
- SecureRandom()
  - : Instantiates a new secure random.


---

## Method Details

### generateSeed(Number)
- generateSeed(numBytes: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Returns the given number of seed bytes, computed using the seed
      generation algorithm that this class uses to seed itself.  This
      call may be used to seed other random number generators.


    **Parameters:**
    - numBytes - the number of seed bytes to generate.

    **Returns:**
    - the seed bytes.


---

### nextBytes(Number)
- nextBytes(numBits: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Generates a user-specified number of random bytes.
      
      
       If a call to `setSeed` had not occurred previously,
      the first call to this method forces this SecureRandom object
      to seed itself.  This self-seeding will not occur if
      `setSeed` was previously called.


    **Parameters:**
    - numBits - the demanded number of bits

    **Returns:**
    - a randomly filled [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)


---

### nextInt()
- nextInt(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the next pseudorandom, uniformly distributed int value from this random number generator's sequence. The general
      contract of nextInt is that one int value is pseudorandomly generated and returned. All 2^32
      possible int values are produced with (approximately) equal probability.


    **Returns:**
    - the next pseudorandom, uniformly distributed int value from this random number generator's sequence


---

### nextInt(Number)
- nextInt(upperBound: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns a pseudorandom, uniformly distributed int value
      between 0 (inclusive) and the specified value (exclusive), drawn from
      this random number generator's sequence.


    **Parameters:**
    - upperBound - the bound on the random number to be returned.  Must be positive.

    **Returns:**
    - the next pseudorandom, uniformly distributed int value between 0 (inclusive) and upperBound (exclusive)
              from this random number generator's sequence


    **Throws:**
    - IllegalArgumentException - if n is not positive


---

### nextNumber()
- nextNumber(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the next pseudorandom, uniformly distributed
      Number value between 0.0 (inclusive) and 1.0 (exclusive) from this random number generator's sequence.


    **Returns:**
    - the next pseudorandom, uniformly distributed Number
              value between 0.0 and 1.0 from this random number generator's sequence



---

### setSeed(Bytes)
- setSeed(seed: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): void
  - : Reseeds this random object. The given seed supplements, rather than replaces, the existing seed. Thus, repeated calls are guaranteed never to reduce randomness.

    **Parameters:**
    - seed - the seed.


---

<!-- prettier-ignore-end -->

<!-- document id=2d71986b356caec1d00b00b28ef241d364695e8d636fd523be355f7fec93ce21 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.SeekableIterator.md -->

<!-- prettier-ignore-start -->
# Class SeekableIterator

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
    - [dw.util.SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)

A special Iterator, which is returned by the system to iterate through large
sets of data. The iterator supports seeking forward to a random position.
This is a typical action when paging forward in a result set. The Iterator is
primarily returned from search operations.


Starting with API version 10.6, these iterators can only
be iterated once to avoid possible memory problems for really large
result sets. Putting them into the pipeline dictionary and trying to loop them
multiple times is no longer possible because this would require buffering the
iterated elements internally.


Prior to 10.6, and for all customers still running API version 10.4
(compatibility mode), SeekableIterator instances stored in the pipeline
dictionary could be iterated multiple times (for example, by several loop
nodes).



## Property Summary

| Property | Description |
| --- | --- |
| [count](#count): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the total element count for this iterator. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [asList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#aslistnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a list representing a subsequence within the iterator. |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)() | Closes all system resources associated with this iterator. |
| [first](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#first)() | Returns the first element of this iterator and closes it. |
| [forward](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#forwardnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Seeks forward by the given number of elements. |
| [forward](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#forwardnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Seeks forward by the given number of elements and limits the  iteration to the given number of elements. |
| [getCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#getcount)() | Returns the total element count for this iterator. |
| [hasNext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#hasnext)() | Indicates if there are more elements. |
| [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#next)() | Returns the next element from the Iterator. |

### Methods inherited from class Iterator

[asList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#aslist), [asList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#aslistnumber-number), [hasNext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#hasnext), [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md#next)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### count
- count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the total element count for this iterator. The
      method returns -1, if the total count is not known.



---

## Method Details

### asList(Number, Number)
- asList(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list representing a subsequence within the iterator. The underlying
      system resources of the iterator will be closed at the end. The start
      position must be 0 or a positive number.


    **Parameters:**
    - start - the position from which to start the subsequence.
    - size - the number of items to collect.

    **Returns:**
    - the list containing the subsequence.


---

### close()
- close(): void
  - : Closes all system resources associated with this iterator.
      
      
      Calling this method is strongly recommended if not all elements of this iterator are
      retrieved. This will allow the system to release system resources immediately.
      The `SeekableIterator` is closed automatically if all elements are retrieved.
      Then calling method `close()` is optional.



---

### first()
- first(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the first element of this iterator and closes it.
      
      
      If the iterator does not contain another element `null` is returned.
      If any of the methods next(), forward(int) or forward(int,int) have been called before
      `null` is returned.
      This method is useful if only the first element of an iterator is needed.
      
      
      A possible example for the use of first() is:
      
      `OrderMgr.queryOrders("queryString", "sortString", args).first()`


    **Returns:**
    - the first element of an iterator and closes the iterator
      or returns `null` if the iterator doesn't have another element
      or the methods next(), forward(int) or forward(int,int) have already been called.



---

### forward(Number)
- forward(n: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Seeks forward by the given number of elements. The number of
      seek steps must be 0 or a positive number.


    **Parameters:**
    - n - the number of elements to seek forward.


---

### forward(Number, Number)
- forward(n: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Seeks forward by the given number of elements and limits the
      iteration to the given number of elements. The method is typically
      used to position and trim an iterator for paging. The getCount()
      method will still return the total count of the underlying data
      collection.


    **Parameters:**
    - n - the number of elements to seek forward.
    - size - the maximum number of elements return from the iterator


---

### getCount()
- getCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the total element count for this iterator. The
      method returns -1, if the total count is not known.


    **Returns:**
    - the total element count for this iterator or -1.


---

### hasNext()
- hasNext(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if there are more elements.

    **Returns:**
    - true if there are more elements,
      false otherwise.



---

### next()
- next(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the next element from the Iterator.

    **Returns:**
    - the next element from the Iterator.


---

<!-- prettier-ignore-end -->

<!-- document id=3186c7726f6b1ee8a57d2701f3b5dcfcba27505e19191e34e1e8547e655356e9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.Service.md -->

<!-- prettier-ignore-start -->
# Class Service

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)

Base class of Services.


A service represents a call-specific configuration. Any configuration set here is local to the currently executing
call.


**See Also:**
- [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)
- [ServiceCallback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md)


## All Known Subclasses
[FTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md), [HTTPFormService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormService.md), [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md), [SOAPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md)
## Property Summary

| Property | Description |
| --- | --- |
| [URL](#url): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the current URL, excluding any custom query parameters. |
| [configuration](#configuration): [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md) `(read-only)` | Returns the Service Configuration. |
| [credentialID](#credentialid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the ID of the currently associated Credential. |
| [mock](#mock): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns the status of whether this service is executing in mock mode. |
| [requestData](#requestdata): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the property that stores the object returned by createRequest. |
| [response](#response): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)` | Returns the property that stores the object returned by the service. |
| [throwOnError](#throwonerror): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns the status of whether this service will throw an error when encountering a problem. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [call](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject)([Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Invokes the service. |
| [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getconfiguration)() | Returns the Service Configuration. |
| [getCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getcredentialid)() | Returns the ID of the currently associated Credential. |
| [getRequestData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getrequestdata)() | Returns the property that stores the object returned by createRequest. |
| [getResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getresponse)() | Returns the property that stores the object returned by the service. |
| [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#geturl)() | Returns the current URL, excluding any custom query parameters. |
| [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#ismock)() | Returns the status of whether this service is executing in mock mode. |
| [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#isthrowonerror)() | Returns the status of whether this service will throw an error when encountering a problem. |
| [setCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setcredentialidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Override the Credential by the credential object with the given ID. |
| [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setmock)() | Forces the mock mode to be enabled. |
| [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setthrowonerror)() | Forces a Service to throw an error when there is a problem instead of returning a Result with non-OK status. |
| [setURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#seturlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Override the URL to the given value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### URL
- URL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current URL, excluding any custom query parameters.


---

### configuration
- configuration: [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md) `(read-only)`
  - : Returns the Service Configuration.


---

### credentialID
- credentialID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the currently associated Credential.


---

### mock
- mock: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether this service is executing in mock mode.


---

### requestData
- requestData: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the property that stores the object returned by createRequest.


---

### response
- response: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) `(read-only)`
  - : Returns the property that stores the object returned by the service.
      
      
      This property is only useful after the service [call(Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject) completes, and is the same as the object
      inside the [Result](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md).



---

### throwOnError
- throwOnError: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether this service will throw an error when encountering a problem.


---

## Method Details

### call(Object...)
- call(args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Result](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md)
  - : Invokes the service.

    **Parameters:**
    - args - Arguments to pass. If there is a single argument and that argument is an array, then each item in the             array will become a separate argument. For example, the following results in three separate arguments             to the service:              
```
            svc.call( [1,2,3] )
```
              and is functionally equivalent to              
```
            svc.call( 1, 2, 3 )
```
              This can be avoided by explicitly forming a [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md), enclosing the array in another             array, or by sending a second argument. The following will all send the array as a List in the first             argument.              
```
            svc.call( ArrayList([1,2,3]) )
```
              
```
            svc.call( [[1,2,3]] )
```
              
```
            svc.call( [1,2,3], "" )
```
              Another option is to change the definition of the associated             [ServiceCallback.createRequest(Service, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#createrequestservice-object) to accept an object instead, and pass the             array as a field of that object:              
```
            svc.call( { 'data': [1,2,3] } )
```


    **Returns:**
    - Result of the service.


---

### getConfiguration()
- getConfiguration(): [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md)
  - : Returns the Service Configuration.

    **Returns:**
    - Service Configuration.


---

### getCredentialID()
- getCredentialID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the currently associated Credential.

    **Returns:**
    - Credential Name.


---

### getRequestData()
- getRequestData(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the property that stores the object returned by createRequest.

    **Returns:**
    - Object returned by createRequest.


---

### getResponse()
- getResponse(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the property that stores the object returned by the service.
      
      
      This property is only useful after the service [call(Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject) completes, and is the same as the object
      inside the [Result](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md).


    **Returns:**
    - Object returned by the service.


---

### getURL()
- getURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current URL, excluding any custom query parameters.

    **Returns:**
    - URL.


---

### isMock()
- isMock(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether this service is executing in mock mode.

    **Returns:**
    - true for mock mode, false otherwise.


---

### isThrowOnError()
- isThrowOnError(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether this service will throw an error when encountering a problem.

    **Returns:**
    - true to throw an error, false otherwise.


---

### setCredentialID(String)
- setCredentialID(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
  - : Override the Credential by the credential object with the given ID.
      
      
      If the URL is also overridden, that URL will continue to override the URL in this credential.


    **Parameters:**
    - id - Credential ID. It must exist.

    **Returns:**
    - this Service.


---

### setMock()
- setMock(): [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
  - : Forces the mock mode to be enabled.

    **Returns:**
    - this Service.


---

### setThrowOnError()
- setThrowOnError(): [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
  - : Forces a Service to throw an error when there is a problem instead of returning a Result with non-OK status.

    **Returns:**
    - this Service.


---

### setURL(String)
- setURL(url: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
  - : Override the URL to the given value. Any query parameters (if applicable) will be appended to this URL.

    **Parameters:**
    - url - Force the URL to the given value.

    **Returns:**
    - this Service.


---

<!-- prettier-ignore-end -->

<!-- document id=1cf7c49fba126e53c9c4fec61c4e308df10960ba77b40a27b9c6b6834f59cf2f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.ServiceCallback.md -->

<!-- prettier-ignore-start -->
# Class ServiceCallback

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.ServiceCallback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md)

Defines callbacks for use with the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md).


Note this class itself is not used directly, and is present only for documentation of the available callback methods.


These methods are called in sequence when a service is called:

1. [initServiceClient(Service)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#initserviceclientservice)-- Creates the underlying client that will be used to make the call. This is   intended for SOAP Services and optionally for setting configuration options on the HTTP client. Other client types   will be created automatically.      2. [createRequest(Service, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#createrequestservice-object)-- Given arguments to the [Service.call(Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject), configure      the actual service request. This may include setting request headers, defining the message body, etc.            3. [execute(Service, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#executeservice-object)-- Perform the actual request. At this point the client has been configured         with the relevant credentials, so the call should be made. This is required for SOAP services.                  4. [parseResponse(Service, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#parseresponseservice-object)-- Convert the result of the call into an object to be returned from the            [Service.call(Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject)method.            If the service is mocked (see [Service.isMock()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#ismock)), then [mockFull(Service, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#mockfullservice-object)takes the place            of this entire sequence. If that is not implemented, then [mockCall(Service, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#mockcallservice-object)takes the place of just            the [execute(Service, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#executeservice-object)method.            
The URL, request, and response objects may be logged. To avoid logging sensitive data,            [filterLogMessage(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#filterlogmessagestring)and/or [getRequestLogMessage(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#getrequestlogmessageobject)and            [getResponseLogMessage(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#getresponselogmessageobject)must be implemented. If they are not implemented then this logging will not be            done on Production environments.            
There are some special considerations for the combination of service type and callback:             |     | Service Type | initServiceClient | createRequest | execute | parseResponse |
| --- |--- |--- |--- |--- |--- |
| HTTP | This is only required to use non-default options. It must return either a [HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md) or a Map  containing the [HTTPClient.HTTPClient(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md#httpclientobject) options. | Required unless execute is provided. The return value is expected to be either a String or array of  [HTTPRequestPart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md), which will be used as the request body | Not called unless a boolean "executeOverride:true" is set on the callback. This is a temporary limitation, a  future release will always call this callback if it is present | Required unless execute is provided. |
| HTTPForm | Not normally implemented. Must return a [HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md) | Not normally implemented. Default behavior constructs an "application/x-www-form-urlencoded" request based on a  Map given as an argument. | Not normally implemented. The same limitations as HTTP regarding the "executeOverride" flag apply here. | Optional. Default behavior is to return the response body as a String. |
| SOAP | Optional. This must return the Webservice stub or port | Required. If initServiceClient was not provided, then this function must call  [SOAPService.setServiceClient(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md#setserviceclientobject) with the stub or port | Required. A typical implementation will call the webservice via a method on the service client | Optional. Default behavior returns the output of execute |
| FTP | Not normally implemented. Must return a [FTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md) or [SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md) | Required unless execute is defined. If present, it should call  [FTPService.setOperation(String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md#setoperationstring-object) | Optional. An implementation may call any required methods on the given client. The default implementation calls  the Operation that was set up and returns the result. | Optional. Default behavior returns the output of execute |
| GENERIC | Optional. | Optional. | Required. The GENERIC type allows any code to be wrapped in the service framework layer, and it's up to this  execute method to define what that logic is. | Optional. |



## Property Summary

| Property | Description |
| --- | --- |
| [URL](#url): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Allows overriding the URL provided by the service configuration. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#createrequestservice-object)([Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a request object to be used when calling the service. |
| [execute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#executeservice-object)([Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Provides service-specific execution logic. |
| [filterLogMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#filterlogmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Allows filtering communication URL, request, and response log messages. |
| [getRequestLogMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#getrequestlogmessageobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a communication log message for the given request. |
| [getResponseLogMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#getresponselogmessageobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a response log message for the given request. |
| [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#geturl)() | Allows overriding the URL provided by the service configuration. |
| [initServiceClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#initserviceclientservice)([Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)) | Creates a protocol-specific client object. |
| [mockCall](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#mockcallservice-object)([Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Override this method to mock the remote portion of the service call. |
| [mockFull](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#mockfullservice-object)([Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Override this method to mock the entire service call, including the createRequest, execute, and parseResponse phases. |
| [parseResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#parseresponseservice-object)([Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a response object from a successful service call. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### URL
- URL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Allows overriding the URL provided by the service configuration.
      
      
      It is usually better to call [Service.setURL(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#seturlstring) within [createRequest(Service, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#createrequestservice-object)
      because that allows you to modify the existing URL based on call parameters.



---

## Method Details

### createRequest(Service, Object...)
- createRequest(service: [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), params: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Creates a request object to be used when calling the service.
      
      
      The type of the object expected is dependent on the service. For example, the [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md) expects the
      HTTP request body to be returned.
      
      
      This is required unless the execute method is implemented.
      
      
      It is not recommended to have a service accept a single array or list as a parameter, since doing so requires
      some extra work when actually calling the service. See [Service.call(Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject) for more details.


    **Parameters:**
    - service - Service being executed.
    - params - Parameters given to the call method.

    **Returns:**
    - Request object to give to the execute method.


---

### execute(Service, Object)
- execute(service: [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), request: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Provides service-specific execution logic.
      
      
      This can be overridden to execute a chain of FTP commands in the [FTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md), or perform the actual remote
      call on a webservice stub in the [SOAPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md).


    **Parameters:**
    - service - Service being executed.
    - request - Request object returned by [createRequest(Service, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#createrequestservice-object).

    **Returns:**
    - Response from the underlying call, to be sent to [parseResponse(Service, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#parseresponseservice-object).

    **Throws:**
    - Exception - 


---

### filterLogMessage(String)
- filterLogMessage(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Allows filtering communication URL, request, and response log messages.
      
      
      If not implemented, then no filtering will be performed and the message will be logged as-is.


    **Parameters:**
    - msg - Original log message.

    **Returns:**
    - Message to be logged.


---

### getRequestLogMessage(Object)
- getRequestLogMessage(request: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Creates a communication log message for the given request.
      
      
      If not implemented then the default logic will be used to convert the request into a log message.


    **Parameters:**
    - request - Request object.

    **Returns:**
    - Log message, or null to create and use the default message.


---

### getResponseLogMessage(Object)
- getResponseLogMessage(response: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Creates a response log message for the given request.
      
      
      If not implemented then the default logic will be used to convert the response into a log message.


    **Parameters:**
    - response - Response object.

    **Returns:**
    - Log message, or null to create and use the default message.


---

### getURL()
- getURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Allows overriding the URL provided by the service configuration.
      
      
      It is usually better to call [Service.setURL(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#seturlstring) within [createRequest(Service, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#createrequestservice-object)
      because that allows you to modify the existing URL based on call parameters.


    **Returns:**
    - URL to use. The default behavior is to use the URL from the service configuration.


---

### initServiceClient(Service)
- initServiceClient(service: [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Creates a protocol-specific client object.
      
      
      This does not normally need to be implemented, except in the case of SOAP services.
      
      
      It may also be used for HTTP services to override the default configuration.
      
      
      
      
      Example SOAP service:
      
      ```
      initServiceClient: function( svc ) {
          return webreferences2.MyWSDL.getDefaultService();
      }
      ```
      
      Example configuration override for an HTTP service:
      
      ```
      initServiceClient: function( svc ) {
          return { allowHTTP2: true };
      }
      ```


    **Parameters:**
    - service - the Service object.

    **Returns:**
    - Client object

    **Throws:**
    - Exception - 


---

### mockCall(Service, Object)
- mockCall(service: [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), requestObj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Override this method to mock the remote portion of the service call.
      
      
      Other callbacks like createRequest and parseResponse are still called.


    **Parameters:**
    - service - Service being executed.
    - requestObj - Request object returned by [createRequest(Service, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#createrequestservice-object).

    **Returns:**
    - Mock response, to be sent to [parseResponse(Service, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md#parseresponseservice-object).

    **Throws:**
    - Exception - 


---

### mockFull(Service, Object...)
- mockFull(service: [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Override this method to mock the entire service call, including the createRequest, execute, and parseResponse phases.

    **Parameters:**
    - service - Service being executed.
    - args - Arguments from the Service call method.

    **Returns:**
    - Object to return in the service call's [Result](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md).

    **Throws:**
    - Exception - 


---

### parseResponse(Service, Object)
- parseResponse(service: [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md), response: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Creates a response object from a successful service call.
      
      
      This response object will be the output object of the call method's Result.


    **Parameters:**
    - service - Service being executed.
    - response - Service-specific response object. For example, the [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md) service provides             the underlying [HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md) object that made the HTTP call.

    **Returns:**
    - Object to return in the service call's [Result](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md).


---

<!-- prettier-ignore-end -->

<!-- document id=3853d449624ddbd40f629e2a194e004e6eef43d0c3b0c21b8a9f7e76cef79ca7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.ServiceConfig.md -->

<!-- prettier-ignore-start -->
# Class ServiceConfig

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.svc.ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md)

Configuration object for Services.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique Service ID. |
| [credential](#credential): [ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md) `(read-only)` | Returns the related service credentials. |
| [profile](#profile): [ServiceProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md) `(read-only)` | Returns the related service profile. |
| [serviceType](#servicetype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the type of the service, such as HTTP or SOAP. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md#getcredential)() | Returns the related service credentials. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md#getid)() | Returns the unique Service ID. |
| [getProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md#getprofile)() | Returns the related service profile. |
| [getServiceType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md#getservicetype)() | Returns the type of the service, such as HTTP or SOAP. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique Service ID.


---

### credential
- credential: [ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md) `(read-only)`
  - : Returns the related service credentials.


---

### profile
- profile: [ServiceProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md) `(read-only)`
  - : Returns the related service profile.


---

### serviceType
- serviceType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the type of the service, such as HTTP or SOAP.


---

## Method Details

### getCredential()
- getCredential(): [ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md)
  - : Returns the related service credentials.

    **Returns:**
    - Related service credentials.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique Service ID.

    **Returns:**
    - unique Service ID.


---

### getProfile()
- getProfile(): [ServiceProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md)
  - : Returns the related service profile.

    **Returns:**
    - Related service profile.


---

### getServiceType()
- getServiceType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the service, such as HTTP or SOAP.

    **Returns:**
    - Type of the service, such as HTTP or SOAP.


---

<!-- prettier-ignore-end -->

<!-- document id=87baeef4164fe9d756f1ff21d5fbee23b89b50e6244420431462eba660b83cf8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.ServiceCredential.md -->

<!-- prettier-ignore-start -->
# Class ServiceCredential

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.customer.EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md)
        - [dw.svc.ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md)

Configuration object for Service Credentials.


## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[ENCRYPTION_ALGORITHM_RSA](#encryption_algorithm_rsa): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA"~~ | Constant for specification of the public key encryption algorithm RSA. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique Credential ID. |
| [URL](#url): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return the URL. |
| [password](#password): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Password in plain text. |
| [user](#user): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the User ID. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| ~~[getEncryptedPassword](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md#getencryptedpasswordstring-certificateref)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md))~~ | Encrypts the password from this object with the given algorithm  and the public key taken from a certificate in the keystore. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md#getid)() | Returns the unique Credential ID. |
| [getPassword](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md#getpassword)() | Returns the Password in plain text. |
| [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md#geturl)() | Return the URL. |
| [getUser](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md#getuser)() | Returns the User ID. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ENCRYPTION_ALGORITHM_RSA

- ~~ENCRYPTION_ALGORITHM_RSA: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RSA"~~
  - : Constant for specification of the public key encryption algorithm RSA.

    **See Also:**
    - [getEncryptedPassword(String, CertificateRef)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md#getencryptedpasswordstring-certificateref)

    **Deprecated:**
**warning:** Use [Cipher](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md) to encrypt data as needed.

---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique Credential ID.


---

### URL
- URL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return the URL.


---

### password
- password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Password in plain text.


---

### user
- user: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the User ID.


---

## Method Details

### getEncryptedPassword(String, CertificateRef)
- ~~getEncryptedPassword(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Encrypts the password from this object with the given algorithm
      and the public key taken from a certificate in the keystore.
      Returned is the base64-encoded representation of the result. 
      
      See also [Cipher.encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-2) on how to generate RSA key pairs.


    **Parameters:**
    - algorithm - The algorithm to be used for the encryption of this password.             Currently only "RSA" is supported.
    - publicKey - A reference to a trusted certificate entry containing             the public key in the keystore.

    **Returns:**
    - the base64-encoded representation of the password.

    **Deprecated:**
**warning:** Use [Cipher](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md) to encrypt data as needed.

---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique Credential ID.

    **Returns:**
    - unique Credential ID.


---

### getPassword()
- getPassword(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Password in plain text.

    **Returns:**
    - Password.


---

### getURL()
- getURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the URL.

    **Returns:**
    - URL.


---

### getUser()
- getUser(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the User ID.

    **Returns:**
    - User ID.


---

<!-- prettier-ignore-end -->

<!-- document id=aed9c33f194b80500a49687baa9403ca3e4d25a1ed6f600d6f9d314d419a7e60 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.ServiceDefinition.md -->

<!-- prettier-ignore-start -->
# Class ServiceDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)

Base class of Service Definitions.


A service definition represents configuration that is shared across all [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md) instances.


**Deprecated:**
**warning:** This class is only used with the deprecated [ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md). Use the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)
            instead, which allows configuration on the [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md) directly.
**API Version:**
**note:** No longer available as of version 19.10.

## All Known Subclasses
[FTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPServiceDefinition.md), [HTTPFormServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormServiceDefinition.md), [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md), [SOAPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPServiceDefinition.md)
## Property Summary

| Property | Description |
| --- | --- |
| [configuration](#configuration): [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md) `(read-only)` | Returns the Service Configuration stored in the database. |
| [mock](#mock): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns the status of whether mock mode is enabled for all instances of this definition. |
| [serviceName](#servicename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of this service. |
| [throwOnError](#throwonerror): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns the status of whether the shared throwOnError flag is set. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [configure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#configureobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Register a callback to handle custom portions of the service. |
| [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getconfiguration)() | Returns the Service Configuration stored in the database. |
| [getServiceName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getservicename)() | Returns the name of this service. |
| [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#ismock)() | Returns the status of whether mock mode is enabled for all instances of this definition. |
| [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#isthrowonerror)() | Returns the status of whether the shared throwOnError flag is set. |
| [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setmock)() | Sets the mock mode for all Service instances that use this definition. |
| [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setthrowonerror)() | Sets the throwOnError flag to true for all Service instances that use this definition. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### configuration
- configuration: [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md) `(read-only)`
  - : Returns the Service Configuration stored in the database.


---

### mock
- mock: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether mock mode is enabled for all instances of this definition.


---

### serviceName
- serviceName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of this service.


---

### throwOnError
- throwOnError: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the shared throwOnError flag is set.


---

## Method Details

### configure(Object)
- configure(config: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
  - : Register a callback to handle custom portions of the service.
      
      
      This callback may declare multiple methods:
      
      
      ```
      {
        initServiceClient: function() {
            // Create and return the internal service client object.
            // This is usually optional, except in the case of SOAP services.
        },
      
        // svc is the call-specific Service instance. For example, it may be an HTTPService or FTPService.
        // params are the arguments passed to the call method (if any).
        createRequest: function(svc:Service, params) {
             // Perform any required call-time configuration.
             // Optionally return a Service-specific object
        },
      
        // svc is the call-specific Service instance.
        // arg is the output of createRequest.
        execute: function(svc:Service, arg:Object) {
             // Execute the service call and return a result
             // This method is not used by default for HTTP-related services unless executeOverride is set.
        },
      
        // Use the execute function if it is present. This is only required to use the functionality with HTTP services.
        executeOverride: true,
      
        // svc is the call-specific Service instance.
        // response is the output of execute.
        parseResponse: function(svc:Service, response: Object) {
             // Process the response object as needed.
             // The return value of this method will be the return value of the outer call method.
        },
      
        // svc is the call-specific Service instance.
        // arg is the output of createRequest.
        mockCall: function(svc:Service, arg:Object) {
             // This method takes the place of the 'execute' phase when mocking is enabled.
             // Note initServiceClient, createRequest, and parseResponse still invoked.
        },
      
        // svc is the call-specific Service instance.
        // params are the arguments passed to the call method (if any).
        mockFull: function(svc:Service, params) {
             // This method takes the place of the entire service call when mocking is enabled.
             // No other callbacks are invoked. The output of this method becomes the output of call.
        }
      
      }
      ```


    **Parameters:**
    - config - Callback object.

    **Returns:**
    - this


---

### getConfiguration()
- getConfiguration(): [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md)
  - : Returns the Service Configuration stored in the database.

    **Returns:**
    - Service Configuration.


---

### getServiceName()
- getServiceName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of this service.

    **Returns:**
    - Service name.


---

### isMock()
- isMock(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether mock mode is enabled for all instances of this definition.

    **Returns:**
    - true for mock mode, false otherwise.


---

### isThrowOnError()
- isThrowOnError(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the shared throwOnError flag is set.

    **Returns:**
    - throwOnError flag.


---

### setMock()
- setMock(): [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
  - : Sets the mock mode for all Service instances that use this definition.

    **Returns:**
    - this Service Definition.


---

### setThrowOnError()
- setThrowOnError(): [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
  - : Sets the throwOnError flag to true for all Service instances that use this definition.

    **Returns:**
    - this Service Definition.


---

<!-- prettier-ignore-end -->

<!-- document id=d9a9eb5239e5f5582cf591c2612d1beb5a701a06bf621002cb7f823e67038b18 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.ServiceProfile.md -->

<!-- prettier-ignore-start -->
# Class ServiceProfile

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.svc.ServiceProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md)

Configuration object for Service Profiles.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique Service ID. |
| [cbCalls](#cbcalls): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the maximum number of errors in an interval allowed by the circuit breaker. |
| [cbMillis](#cbmillis): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the interval of the circuit breaker in milliseconds. |
| [rateLimitCalls](#ratelimitcalls): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the maximum number of calls in an interval allowed by the rate limiter. |
| [rateLimitMillis](#ratelimitmillis): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the interval of the rate limiter in milliseconds. |
| [timeoutMillis](#timeoutmillis): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the service call timeout in milliseconds. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCbCalls](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md#getcbcalls)() | Returns the maximum number of errors in an interval allowed by the circuit breaker. |
| [getCbMillis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md#getcbmillis)() | Returns the interval of the circuit breaker in milliseconds. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md#getid)() | Returns the unique Service ID. |
| [getRateLimitCalls](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md#getratelimitcalls)() | Returns the maximum number of calls in an interval allowed by the rate limiter. |
| [getRateLimitMillis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md#getratelimitmillis)() | Returns the interval of the rate limiter in milliseconds. |
| [getTimeoutMillis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md#gettimeoutmillis)() | Returns the service call timeout in milliseconds. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique Service ID.


---

### cbCalls
- cbCalls: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the maximum number of errors in an interval allowed by the circuit breaker.


---

### cbMillis
- cbMillis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the interval of the circuit breaker in milliseconds.


---

### rateLimitCalls
- rateLimitCalls: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the maximum number of calls in an interval allowed by the rate limiter.


---

### rateLimitMillis
- rateLimitMillis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the interval of the rate limiter in milliseconds.


---

### timeoutMillis
- timeoutMillis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the service call timeout in milliseconds.


---

## Method Details

### getCbCalls()
- getCbCalls(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum number of errors in an interval allowed by the circuit breaker.

    **Returns:**
    - Maximum number of errors in an interval allowed by the circuit breaker.


---

### getCbMillis()
- getCbMillis(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the interval of the circuit breaker in milliseconds.

    **Returns:**
    - Circuit breaker interval in milliseconds.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique Service ID.

    **Returns:**
    - unique Service ID


---

### getRateLimitCalls()
- getRateLimitCalls(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the maximum number of calls in an interval allowed by the rate limiter.

    **Returns:**
    - Maximum number of calls in an interval allowed by the rate limiter.


---

### getRateLimitMillis()
- getRateLimitMillis(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the interval of the rate limiter in milliseconds.

    **Returns:**
    - Interval of the rate limiter in milliseconds.


---

### getTimeoutMillis()
- getTimeoutMillis(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the service call timeout in milliseconds.

    **Returns:**
    - Service call timeout in milliseconds.


---

<!-- prettier-ignore-end -->

<!-- document id=32ae84df598e4e7c9718838279e819ae1828f5e29445d83c6d9d081d3faeba21 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.ServiceRegistry.md -->

<!-- prettier-ignore-start -->
# Class ServiceRegistry

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md)

The ServiceRegistry is responsible for managing Service definitions and their instances.


Typical usage involves several steps:

1. The service is defined in the Business Manager and configured with necessary credentials.
2. The service callback is configured once during cartridge initialization:      
   ```
   ServiceRegistry.configure("MyFTPService", {    mockExec : function(svc:FTPService, params) {        return [            { "name": "file1", "timestamp": new Date(2011, 02, 21)},            { "name": "file2", "timestamp": new Date(2012, 02, 21)},            { "name": "file3", "timestamp": new Date(2013, 02, 21)}        ];    },    createRequest: function(svc:FTPService, params) {        svc.setOperation("list", "/");    },    parseResponse : function(svc:FTPService, listOutput) {        var x : Array = [];        var resp : Array = listOutput;        for(var i = 0; i <resp.length; i++) {            var f = resp[i];            x.push( { "name": f['name'], "timestamp": f['timestamp'] } );        }        return x;    }});
   ```

3. A new service instance is created and called in order to perform the operation:      
   ```
   var result : Result = ServiceRegistry.get("MyFTPService").call();if(result.status == 'OK') {    // The result.object is the object returned by the 'after' callback.} else {    // Handle the error. See result.error for more information.}
   ```



See [ServiceCallback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md) for all the callback options, and individual [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
classes for customization specific to a service type.


**Deprecated:**
**warning:** It is recommended to use the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md) instead of this class.
**API Version:**
**note:** No longer available as of version 19.10.

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [configure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md#configurestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Configure the given serviceId with a callback. |
| static [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md#getstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new instance of the given service. |
| static [getDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md#getdefinitionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Gets a Service Definition. |
| static [isConfigured](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md#isconfiguredstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the status of whether the given service has been configured with a callback. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### configure(String, Object)
- static configure(serviceID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), configObj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
  - : Configure the given serviceId with a callback.
      
      
      If the service is already configured, the given callback will replace any existing one.


    **Parameters:**
    - serviceID - Unique Service ID.
    - configObj - Configuration callback. See [ServiceCallback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md) for a description of available callback methods.

    **Returns:**
    - Associated [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md), which can be used for further protocol-specific
              configuration.



---

### get(String)
- static get(serviceID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
  - : Constructs a new instance of the given service.

    **Parameters:**
    - serviceID - Unique Service ID.

    **Returns:**
    - Service instance.


---

### getDefinition(String)
- static getDefinition(serviceID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
  - : Gets a Service Definition.
      
      
      This Service Definition is shared across all Service instances returned by [get(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md#getstring).


    **Parameters:**
    - serviceID - Unique Service ID.

    **Returns:**
    - ServiceDefinition


---

### isConfigured(String)
- static isConfigured(serviceID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the status of whether the given service has been configured with a callback.

    **Parameters:**
    - serviceID - Unique Service ID.

    **Returns:**
    - true if configure has already been called, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=29c6d461c0632e7448bcce1c88812c8ca752ec5587e52cece06153f5bc21fc60 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Session.md -->

<!-- prettier-ignore-start -->
# Class Session

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md)

Represents a session in B2C Commerce. The session has some well-defined
attributes like the current authenticated customer or the click stream, but also
supports storing custom values in the session.

The Digital session handling works in the following way:

- A session is created in Digital on the first user click. This is guaranteed even if  B2C Commerce caches the HTML pages. It is not guaranteed when the pages are cached by a CDN.  
- A session is identified with a unique ID, called the session ID.  
- When a session is created, the application server calls the pipeline OnSession-Start. It can  be used to pre-initialize the session, before the actual request hits the server.  
- Digital uses session stickiness and always routes requests within a single session to the same  application server.  
- Session data is also stored in a persistent location.  
- In case of a fail-over situation, requests are re-routed to another application server, which then  loads the session data from the persistent storage.  
- There are two session timeouts. A soft timeout occurs 30 minutes after the last request has been made.  The soft timeout logs out and clears all privacy data, but it is still possible to use the session ID  to reopen the session. A hard timeout renders a session ID invalid after six hours, even if the session  is still in use. The hard timeout prevents a session from being reopened. For example, if the session ID  is pasted into a URL after the hard timeout, the session doesn't reopen.  


Certain rules apply for what and how much data can be stored in a session:

- All primitive types (boolean, number, string, Number, String, Boolean, Date) are supported.  
- All B2C Commerce value types (Money, Quantity, Decimal, Calendar) are supported.  
- Strings are limited to 2000 characters.  
- No other types can be stored in a session. In particular, persistent objects,  collections, and scripted objects cannot be stored in a session. B2C Commerce  will report unsupported values with a deprecation message in the log files.  An unsupported value will be stored in the session, but the results are undefined.  Since version compatibility mode 19.10 unsupported types will no longer be accepted,  and an exception will be thrown.  
- There is a 10 KB size limit for the overall serialized session.  



## Property Summary

| Property | Description |
| --- | --- |
| [clickStream](#clickstream): [ClickStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md) `(read-only)` | Returns the current click stream if this is an HTTP session, null otherwise. |
| [currency](#currency): [Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md) | Get the currency associated with the current session. |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the session's custom attributes. |
| [customer](#customer): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)` | Returns the customer associated with this storefront session. |
| [customerAuthenticated](#customerauthenticated): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies whether the customer associated with this session  is authenticated. |
| [customerExternallyAuthenticated](#customerexternallyauthenticated): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies whether the customer associated with this session  is externally authenticated. |
| [forms](#forms): [Forms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Forms.md) `(read-only)` | Returns the forms object that provides access to all current forms of a customer in the session. |
| [lastReceivedSourceCodeInfo](#lastreceivedsourcecodeinfo): [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md) `(read-only)` | Returns information on the last source code handled by the session. |
| [privacy](#privacy): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the session's custom privacy attributes. |
| [sessionID](#sessionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique session id. |
| [sourceCodeInfo](#sourcecodeinfo): [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md) `(read-only)` | Returns information on the session's active source-code. |
| [trackingAllowed](#trackingallowed): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns whether the tracking allowed flag is set in the session. |
| [userAuthenticated](#userauthenticated): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies whether the agent user associated with this session  is authenticated. |
| [userName](#username): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the current agent user name associated with this session. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [generateGuestSessionSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#generateguestsessionsignature)() | Generates a new guest session signature. |
| [generateRegisteredSessionSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#generateregisteredsessionsignature)() | Generates a new registered session signature. |
| [getClickStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getclickstream)() | Returns the current click stream if this is an HTTP session, null otherwise. |
| [getCurrency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getcurrency)() | Get the currency associated with the current session. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getcustom)() | Returns the session's custom attributes. |
| [getCustomer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getcustomer)() | Returns the customer associated with this storefront session. |
| [getForms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getforms)() | Returns the forms object that provides access to all current forms of a customer in the session. |
| [getLastReceivedSourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getlastreceivedsourcecodeinfo)() | Returns information on the last source code handled by the session. |
| [getPrivacy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getprivacy)() | Returns the session's custom privacy attributes. |
| [getSessionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getsessionid)() | Returns the unique session id. |
| [getSourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getsourcecodeinfo)() | Returns information on the session's active source-code. |
| [getUserName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#getusername)() | Returns the current agent user name associated with this session. |
| [isCustomerAuthenticated](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#iscustomerauthenticated)() | Identifies whether the customer associated with this session  is authenticated. |
| [isCustomerExternallyAuthenticated](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#iscustomerexternallyauthenticated)() | Identifies whether the customer associated with this session  is externally authenticated. |
| [isTrackingAllowed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#istrackingallowed)() | Returns whether the tracking allowed flag is set in the session. |
| [isUserAuthenticated](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#isuserauthenticated)() | Identifies whether the agent user associated with this session  is authenticated. |
| [setCurrency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#setcurrencycurrency)([Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md)) | Sets the session currency. |
| [setSourceCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#setsourcecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Applies the specified source code to the current session and basket. |
| [setTrackingAllowed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md#settrackingallowedboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Sets the tracking allowed flag for the session. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### clickStream
- clickStream: [ClickStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md) `(read-only)`
  - : Returns the current click stream if this is an HTTP session, null otherwise.


---

### currency
- currency: [Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md)
  - : Get the currency associated with the current session. The session
      currency is established at session construction time and is typically
      equal to the site default currency. In the case of a multi-currency site,
      the session currency may be different than the site default currency.



---

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the session's custom attributes. The
      attributes are stored for the lifetime of the session and are not
      cleared when the customer logs out.



---

### customer
- customer: [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) `(read-only)`
  - : Returns the customer associated with this storefront session. The method
      always returns `null` if called for a non-storefront session
      (e.g., within a job or within Business Manager). For a storefront
      session, the method always returns a customer. The returned customer
      may be anonymous if the customer could not be identified via the
      customer cookie.



---

### customerAuthenticated
- customerAuthenticated: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies whether the customer associated with this session
      is authenticated. This call is equivalent to customer.isAuthenticated().



---

### customerExternallyAuthenticated
- customerExternallyAuthenticated: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies whether the customer associated with this session
      is externally authenticated.



---

### forms
- forms: [Forms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Forms.md) `(read-only)`
  - : Returns the forms object that provides access to all current forms of a customer in the session.


---

### lastReceivedSourceCodeInfo
- lastReceivedSourceCodeInfo: [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md) `(read-only)`
  - : Returns information on the last source code handled by the session.
      This may or may not be the session's active source code, e.g., the
      last received source code was inactive and therefore was not
      set as the session's active source code.



---

### privacy
- privacy: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the session's custom privacy attributes.
      The attributes are stored for the lifetime of the session and are
      automatically cleared when the customer logs out.



---

### sessionID
- sessionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique session id. This can safely be used as an identifier
      against external systems.



---

### sourceCodeInfo
- sourceCodeInfo: [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md) `(read-only)`
  - : Returns information on the session's active source-code.


---

### trackingAllowed
- trackingAllowed: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether the tracking allowed flag is set in the session.
      The value for newly created sessions defaults to the Site Preference "TrackingAllowed" unless
      a cookie named "dw\_dnt" is found in which case the cookie value takes precedence.



---

### userAuthenticated
- userAuthenticated: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies whether the agent user associated with this session
      is authenticated.



---

### userName
- userName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the current agent user name associated with this session.
      
      
      **Note:** this class allows access to sensitive security-related data.
      Pay special attention to PCI DSS v3 requirements 2, 4, and 12.



---

## Method Details

### generateGuestSessionSignature()
- generateGuestSessionSignature(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Generates a new guest session signature.
      
      
      This is intended for guest authentication with the Shopper Login and API Access Service (SLAS).


    **Returns:**
    - A new signed session token.


---

### generateRegisteredSessionSignature()
- generateRegisteredSessionSignature(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Generates a new registered session signature.
      
      
      This is intended for use with registered session-bridge call of Shopper Login and API Access Service (SLAS).


    **Returns:**
    - A new signed session token for registered dwsid.


---

### getClickStream()
- getClickStream(): [ClickStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md)
  - : Returns the current click stream if this is an HTTP session, null otherwise.

    **Returns:**
    - the current click stream if this is an HTTP session, null otherwise.


---

### getCurrency()
- getCurrency(): [Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md)
  - : Get the currency associated with the current session. The session
      currency is established at session construction time and is typically
      equal to the site default currency. In the case of a multi-currency site,
      the session currency may be different than the site default currency.


    **Returns:**
    - the currency associated with this storefront session, never null.


---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the session's custom attributes. The
      attributes are stored for the lifetime of the session and are not
      cleared when the customer logs out.


    **Returns:**
    - the session's custom attributes.


---

### getCustomer()
- getCustomer(): [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)
  - : Returns the customer associated with this storefront session. The method
      always returns `null` if called for a non-storefront session
      (e.g., within a job or within Business Manager). For a storefront
      session, the method always returns a customer. The returned customer
      may be anonymous if the customer could not be identified via the
      customer cookie.


    **Returns:**
    - the customer associated with this storefront session.


---

### getForms()
- getForms(): [Forms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Forms.md)
  - : Returns the forms object that provides access to all current forms of a customer in the session.

    **Returns:**
    - the forms.


---

### getLastReceivedSourceCodeInfo()
- getLastReceivedSourceCodeInfo(): [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md)
  - : Returns information on the last source code handled by the session.
      This may or may not be the session's active source code, e.g., the
      last received source code was inactive and therefore was not
      set as the session's active source code.


    **Returns:**
    - source code information for the last received source code.


---

### getPrivacy()
- getPrivacy(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the session's custom privacy attributes.
      The attributes are stored for the lifetime of the session and are
      automatically cleared when the customer logs out.


    **Returns:**
    - the session's custom privacy attributes.


---

### getSessionID()
- getSessionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique session id. This can safely be used as an identifier
      against external systems.


    **Returns:**
    - the unique identifier for the session.


---

### getSourceCodeInfo()
- getSourceCodeInfo(): [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md)
  - : Returns information on the session's active source-code.

    **Returns:**
    - the session's source-code information.


---

### getUserName()
- getUserName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current agent user name associated with this session.
      
      
      **Note:** this class allows access to sensitive security-related data.
      Pay special attention to PCI DSS v3 requirements 2, 4, and 12.


    **Returns:**
    - the current agent user name associated with this session.


---

### isCustomerAuthenticated()
- isCustomerAuthenticated(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies whether the customer associated with this session
      is authenticated. This call is equivalent to customer.isAuthenticated().


    **Returns:**
    - true if the customer is authenticated, false otherwise.


---

### isCustomerExternallyAuthenticated()
- isCustomerExternallyAuthenticated(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies whether the customer associated with this session
      is externally authenticated.


    **Returns:**
    - true if the customer is authenticated, false otherwise.


---

### isTrackingAllowed()
- isTrackingAllowed(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether the tracking allowed flag is set in the session.
      The value for newly created sessions defaults to the Site Preference "TrackingAllowed" unless
      a cookie named "dw\_dnt" is found in which case the cookie value takes precedence.


    **Returns:**
    - true if the tracking allowed flag is set in the session, false otherwise.


---

### isUserAuthenticated()
- isUserAuthenticated(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies whether the agent user associated with this session
      is authenticated.


    **Returns:**
    - true if the agent user is authenticated, false otherwise.


---

### setCurrency(Currency)
- setCurrency(newCurrency: [Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md)): void
  - : Sets the session currency.

    **Parameters:**
    - newCurrency - the new currency to use. Must not be null. Method will             throw an exception if a currency not allowed by the current site             is passed.


---

### setSourceCode(String)
- setSourceCode(sourceCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Applies the specified source code to the current session and basket. This API processes the source code exactly as if it
      were supplied on the URL query string, with the additional benefit of returning error information. If no input
      parameter is passed, then the active source code in the session and basket is removed. If a basket exists, and the modification fails,
      then the session is not written to either. This method may open and commit a transaction, if none is currently active.


    **Parameters:**
    - sourceCode - the source code to set as active in the session and basket. If a null parameter is passed, then the active             source code in the session is removed.

    **Returns:**
    - an OK status if the source code was applied, otherwise an ERROR status. In the latter case, the possible
              error codes are: CODE\_INVALID and CODE\_INACTIVE. See documentation for
              [SourceCodeStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeStatusCodes.md) for further descriptions.



---

### setTrackingAllowed(Boolean)
- setTrackingAllowed(trackingAllowed: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Sets the tracking allowed flag for the session. If tracking is not allowed, multiple services
      depending on tracking will be restricted or disabled: Predictive Intelligence recommendations,
      Active Data, Analytics of the customer behavior in the storefront.
      Additionally, collected clicks in the session click stream will be cleared.
      Setting this property to either value also results in setting a session-scoped cookie named "dw\_dnt"
      (1=DoNotTrack; 0=Track)


    **Parameters:**
    - trackingAllowed - true if tracking is allowed, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=0f991e33ff4a64c2344e9a6a3b21d40940770ba0810d80c7c0f053c34b4d1056 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Set.md -->

<!-- prettier-ignore-start -->
# Class Set

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
    - [dw.util.Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)

Represents a set of objects.


## All Known Subclasses
[HashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashSet.md), [LinkedHashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashSet.md), [SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)
## Property Summary

| Property | Description |
| --- | --- |
| [EMPTY_SET](#empty_set): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) | Convenience variable, for an empty and immutable list. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Collection

[add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject), [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object), [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection), [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear), [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject), [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty), [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject), [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection), [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### EMPTY_SET
- EMPTY_SET: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Convenience variable, for an empty and immutable list.


---

<!-- prettier-ignore-end -->

<!-- document id=fed2c3750a03da4cf188fd622ede0e0345ec4815930c412c2b5f7e85e2e98303 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Set.md -->

<!-- prettier-ignore-start -->
# Class Set

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md)

A Set can store any kind of element and ensures that no duplicates exist.
Objects are stored and iterated in insertion order.


**API Version:**
**note:** Available from version 21.2.

## Property Summary

| Property | Description |
| --- | --- |
| [size](#size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Number of elements stored in this set. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Set](#set)() | Creates an empty Set. |
| [Set](#setiterable)([Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)) | If the passed value is null or undefined then an empty set is constructed. |

## Method Summary

| Method | Description |
| --- | --- |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md#addobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds an element to the set. |
| [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md#clear)() | Removes all elements from this set. |
| [delete](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md#deleteobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Removes the element from the set. |
| [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md#entries)() | Returns an iterator containing all elements of this set. |
| [forEach](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md#foreachfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Runs the provided callback function once for each element present in this set. |
| [forEach](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md#foreachfunction-object)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Runs the provided callback function once for each element present in this set. |
| [has](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md#hasobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if this set contains the given object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### size
- size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Number of elements stored in this set.


---

## Constructor Details

### Set()
- Set()
  - : Creates an empty Set.


---

### Set(Iterable)
- Set(values: [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md))
  - : If the passed value is null or undefined then an empty set is constructed. Else an iterable object is expected
      that delivers the initial set entries.


    **Parameters:**
    - values - The initial set entries.


---

## Method Details

### add(Object)
- add(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md)
  - : Adds an element to the set. Does nothing if the set already contains the element.

    **Parameters:**
    - object - The object to add.

    **Returns:**
    - This set object.


---

### clear()
- clear(): void
  - : Removes all elements from this set.


---

### delete(Object)
- delete(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Removes the element from the set.

    **Parameters:**
    - object - The object to be removed.

    **Returns:**
    - `true` if the set contained the object that was removed. Else `false` is returned.


---

### entries()
- entries(): [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)
  - : Returns an iterator containing all elements of this set.


---

### forEach(Function)
- forEach(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): void
  - : Runs the provided callback function once for each element present in this set.

    **Parameters:**
    - callback - The function to call, which is invoked with three  arguments: the element (as value), the element (as index), and the  Set object being iterated.


---

### forEach(Function, Object)
- forEach(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), thisObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Runs the provided callback function once for each element present in this set.

    **Parameters:**
    - callback - The function to call, which is invoked with three  arguments: the element (as value), the element (as index), and the  Set object being iterated.
    - thisObject - The Object to use as 'this' when executing callback.


---

### has(Object)
- has(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if this set contains the given object.

    **Parameters:**
    - object - The object to look for.

    **Returns:**
    - `true` if the set contains the object else `false` is returned.


---

<!-- prettier-ignore-end -->

<!-- document id=e20b32fac026f433753eff0f363be51dc90cf6e57ab7c2cf0e8038cd716ac888 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.SFTPClient.md -->

<!-- prettier-ignore-start -->
# Class SFTPClient

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md)

The SFTPClient class supports the SFTP commands GET, PUT, DEL, MKDIR, RENAME, and LIST. The transfer of files can be
text or binary.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information.


An example usage is as follows:




```

 var sftp : SFTPClient = new dw.net.SFTPClient();
 sftp.connect("my.sftp-server.com", "username", "password");
 var data : String = sftp.get("simple.txt");
 sftp.disconnect();
```



The default connection timeout depends on the script context timeout and will be set to a maximum of 30 seconds
(default script context timeout is 10 seconds within storefront requests and 15 minutes within jobs).


**IMPORTANT NOTE:** Before you can make an outbound SFTP connection to a port other than 22, the SFTP server IP address must be enabled
for outbound traffic at the Commerce Cloud Digital firewall for your POD. Please file a support request to request a new firewall
rule.


SSH Version 2 is supported with the following algorithms:
| Type | Algorithms |
| --- |--- |
| Host Key | ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521,                  rsa-sha2-512, rsa-sha2-256, ssh-rsa, ssh-dss |
| Key Exchange (KEX) | curve25519-sha256, curve25519-sha256@libssh.org, ecdh-sha2-nistp256,              ecdh-sha2-nistp384, ecdh-sha2-nistp521, diffie-hellman-group-exchange-sha256,              diffie-hellman-group16-sha512, diffie-hellman-group18-sha512, diffie-hellman-group14-sha256,              diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1, diffie-hellman-group1-sha1 |
| Cipher | aes128-ctr, aes192-ctr, aes256-ctr, aes128-gcm@openssh.com,              aes256-gcm@openssh.com, aes128-cbc, 3des-ctr, 3des-cbc, blowfish-cbc, aes192-cbc,              aes256-cbc |
| Message Authentication Code (MAC) | hmac-sha2-256-etm@openssh.com, hmac-sha2-512-etm@openssh.com,              hmac-sha1-etm@openssh.com, hmac-sha2-256, hmac-sha2-512, hmac-sha1, hmac-md5, hmac-sha1-96,              hmac-md5-96 |
| Public Key Authentication | rsa-sha2-512, rsa-sha2-256, ssh-rsa |



## Constant Summary

| Constant | Description |
| --- | --- |
| [MAX_GET_FILE_SIZE](#max_get_file_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200 | The maximum size for get() methods returning a File is 200 MB. |
| [MAX_GET_STRING_SIZE](#max_get_string_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760 | The maximum size for get() methods returning a String is 10 MB. |

## Property Summary

| Property | Description |
| --- | --- |
| [connected](#connected): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the SFTP client is currently connected to the SFTP server. |
| [errorMessage](#errormessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the error message from the last SFTP action. |
| [identity](#identity): [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md) | Gets the identity (private key) used for the connection. |
| [timeout](#timeout): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the timeout for this client, in milliseconds. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SFTPClient](#sftpclient)() | Constructor. |

## Method Summary

| Method | Description |
| --- | --- |
| [addKnownHostKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#addknownhostkeystring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a known public host key for the next connection attempt. |
| [cd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#cdstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Changes the current directory on the remote server to the given path. |
| [connect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#connectstring-number-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Connects and logs on to a SFTP server and returns a boolean indicating success or failure. |
| [connect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#connectstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Connects and logs on to a SFTP server and returns a boolean indicating success or failure. |
| [del](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#delstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Deletes the remote file on the server identified by the path parameter. |
| [disconnect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#disconnect)() | The method first logs the current user out from the server and then disconnects from the server. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#getstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Reads the content of a remote file and returns it as a string using "ISO-8859-1" encoding to read it. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#getstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Reads the content of a remote file and returns it as a string using the specified encoding. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#getstring-string-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Reads the content of a remote file and creates a local copy in the given file using the passed string encoding to  read the file content and using the system standard encoding "UTF-8" to write the file. |
| [getBinary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#getbinarystring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Reads the content of a remote file and creates a local copy in the given file. |
| [getConnected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#getconnected)() | Identifies if the SFTP client is currently connected to the SFTP server. |
| [getErrorMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#geterrormessage)() | Returns the error message from the last SFTP action. |
| [getFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#getfileinfostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a SFTPFileInfo objects containing information about the given file/directory path. |
| [getIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#getidentity)() | Gets the identity (private key) used for the connection. |
| [getTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#gettimeout)() | Returns the timeout for this client, in milliseconds. |
| [list](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#list)() | Returns a list of SFTPFileInfo objects containing information about the files in the current directory. |
| [list](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#liststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a list of SFTPFileInfo objects containing information about the files in the remote directory defined by  the given path. |
| [mkdir](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#mkdirstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a directory |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#putstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Puts the specified content to the specified path using "ISO-8859-1" encoding. |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#putstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Put the given content to a file on the given path on the SFTP server. |
| [putBinary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#putbinarystring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Put the content of the given file into a file on the remote SFTP server with the given absolute path. |
| [removeDirectory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#removedirectorystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Deletes the remote directory on the server identified by the path parameter. |
| [rename](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#renamestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Renames an existing file. |
| [setIdentity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#setidentitykeyref)([KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)) | Sets the identity (private key) to use for the next connection attempt. |
| [setTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#settimeoutnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the timeout for connections made with the SFTP client to the given number of milliseconds. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### MAX_GET_FILE_SIZE

- MAX_GET_FILE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200
  - : The maximum size for get() methods returning a File is 200 MB.


---

### MAX_GET_STRING_SIZE

- MAX_GET_STRING_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760
  - : The maximum size for get() methods returning a String is 10 MB.


---

## Property Details

### connected
- connected: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the SFTP client is currently connected to the SFTP server.


---

### errorMessage
- errorMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the error message from the last SFTP action.


---

### identity
- identity: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)
  - : Gets the identity (private key) used for the connection.
      
      
      The key is only associated to this instance of the SFTP client.



---

### timeout
- timeout: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the timeout for this client, in milliseconds.


---

## Constructor Details

### SFTPClient()
- SFTPClient()
  - : Constructor.


---

## Method Details

### addKnownHostKey(String, String)
- addKnownHostKey(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a known public host key for the next connection attempt.
      
      
      This method associates the key to the host used in the subsequent connect method, and must be called prior to connect.
      The key is not persisted, and is only associated to this instance of the SFTP client.
      
      
      Multiple keys may be added, and the validation will succeed if the remote host matches any of them.
      
      
      The default behavior is to persist and trust an unknown host key if there are no known host keys available.
      If addKnownHostKey is later used to trust specific a specific key or keys, then any previously persisted keys
      will be ignored.


    **Parameters:**
    - type - Type of the host key, such as ssh-rsa
    - key - Public host key, in the same format as OpenSSH.


---

### cd(String)
- cd(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Changes the current directory on the remote server to the given path.

    **Parameters:**
    - path - the new current directory

    **Returns:**
    - true if the directory change was okay


---

### connect(String, Number, String, String)
- connect(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), port: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), user: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Connects and logs on to a SFTP server and returns a boolean indicating success or failure.

    **Parameters:**
    - host - Name of the SFTP sever
    - port - Port for SFTP server
    - user - Username for the login
    - password - Password for the login

    **Returns:**
    - true when connection is successful, false otherwise.


---

### connect(String, String, String)
- connect(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), user: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Connects and logs on to a SFTP server and returns a boolean indicating success or failure.

    **Parameters:**
    - host - Name of the SFTP sever
    - user - Username for the login
    - password - Password for the login

    **Returns:**
    - true when connection is successful, false otherwise.


---

### del(String)
- del(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Deletes the remote file on the server identified by the path parameter.

    **Parameters:**
    - path - the path to the file.

    **Returns:**
    - true if the file was successfully deleted, false otherwise.


---

### disconnect()
- disconnect(): void
  - : The method first logs the current user out from the server and then disconnects from the server.


---

### get(String)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a remote file and returns it as a string using "ISO-8859-1" encoding to read it. Files with
      at most MAX\_GET\_STRING\_SIZE bytes are read.


    **Parameters:**
    - path - remote path of the file to be read.

    **Returns:**
    - the contents of the file or null if an error occurred while reading the file.


---

### get(String, String)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a remote file and returns it as a string using the specified encoding. Files with at most
      MAX\_GET\_STRING\_SIZE bytes are read.


    **Parameters:**
    - path - the remote path of the file to be read.
    - encoding - the encoding to use.

    **Returns:**
    - the contents of the file or null if an error occurred while reading the file.


---

### get(String, String, File)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote file and creates a local copy in the given file using the passed string encoding to
      read the file content and using the system standard encoding "UTF-8" to write the file. Copies at most
      MAX\_GET\_FILE\_SIZE bytes.


    **Parameters:**
    - path - the remote path of the file to be read.
    - encoding - the encoding to use.
    - file - the local file name

    **Returns:**
    - true if complete remote file is fetched and copied into local file. false, otherwise.


---

### getBinary(String, File)
- getBinary(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote file and creates a local copy in the given file. Copies at most MAX\_GET\_FILE\_SIZE
      bytes. The SFTP transfer is done in binary mode.


    **Parameters:**
    - path - the remote path of the file to be read.
    - file - the local file name

    **Returns:**
    - true if complete remote file is fetched and copied into local file. false otherwise


---

### getConnected()
- getConnected(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the SFTP client is currently connected to the SFTP server.

    **Returns:**
    - true if the client is currently connected.


---

### getErrorMessage()
- getErrorMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the error message from the last SFTP action.

    **Returns:**
    - the error message from the last SFTP action


---

### getFileInfo(String)
- getFileInfo(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SFTPFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPFileInfo.md)
  - : Returns a SFTPFileInfo objects containing information about the given file/directory path.

    **Parameters:**
    - path - the remote path from which the file info should be listed.

    **Returns:**
    - the remote file information or `null` if not present.


---

### getIdentity()
- getIdentity(): [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)
  - : Gets the identity (private key) used for the connection.
      
      
      The key is only associated to this instance of the SFTP client.


    **Returns:**
    - Reference to the private key, or null if not configured


---

### getTimeout()
- getTimeout(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the timeout for this client, in milliseconds.

    **Returns:**
    - the timeout in milliseconds


---

### list()
- list(): [SFTPFileInfo\[\]](dw.net.SFTPFileInfo.md)
  - : Returns a list of SFTPFileInfo objects containing information about the files in the current directory.

    **Returns:**
    - list of objects with remote file information or `null` if not present.


---

### list(String)
- list(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SFTPFileInfo\[\]](dw.net.SFTPFileInfo.md)
  - : Returns a list of SFTPFileInfo objects containing information about the files in the remote directory defined by
      the given path.


    **Parameters:**
    - path - the remote path from which the file info should be listed.

    **Returns:**
    - list of objects with remote file information or `null` if not present.


---

### mkdir(String)
- mkdir(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Creates a directory

    **Parameters:**
    - path - the path to the directory to create.

    **Returns:**
    - true if the directory was successfully created, false otherwise.


---

### put(String, String)
- put(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Puts the specified content to the specified path using "ISO-8859-1" encoding. If the content of a local file is
      to be uploaded, please use method putBinary(String,File) instead.
      
      
      NOTE: If the remote file already exists, it is overwritten.


    **Parameters:**
    - path - the path on the remote SFTP server, where the file will be stored.
    - content - the content to put.

    **Returns:**
    - true or false indicating success or failure.


---

### put(String, String, String)
- put(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Put the given content to a file on the given path on the SFTP server. The transformation from String into binary
      data is done via the encoding provided with the method call. If the content of a local file is to be uploaded,
      please use method putBinary(String,File) instead.
      
      
      NOTE: If the remote file already exists, it is overwritten.


    **Parameters:**
    - path - the path on the remote SFTP server, where the file will be stored.
    - content - the content to put.
    - encoding - the encoding to use.

    **Returns:**
    - true or false indicating success or failure.


---

### putBinary(String, File)
- putBinary(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Put the content of the given file into a file on the remote SFTP server with the given absolute path. NOTE: If
      the remote file already exists, it is overwritten.


    **Parameters:**
    - path - the path on the remote SFTP server where the file will be stored.
    - file - the file on the local system, which content is send to the remote SFTP server.

    **Returns:**
    - true or false indicating success or failure.


---

### removeDirectory(String)
- removeDirectory(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Deletes the remote directory on the server identified by the path parameter. In order to delete the directory
      successfully the directory needs to be empty, otherwise the removeDirectory() method will return false.


    **Parameters:**
    - path - the path to the directory.

    **Returns:**
    - true if the directory was successfully deleted, false otherwise.


---

### rename(String, String)
- rename(from: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), to: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Renames an existing file.

    **Parameters:**
    - from - the file that will be renamed.
    - to - the name of the new file.

    **Returns:**
    - true if the file was successfully renamed, false otherwise.


---

### setIdentity(KeyRef)
- setIdentity(keyRef: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)): void
  - : Sets the identity (private key) to use for the next connection attempt.
      
      
      The key is only associated to this instance of the SFTP client.


    **Parameters:**
    - keyRef - Reference to the private key


---

### setTimeout(Number)
- setTimeout(timeoutMillis: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the timeout for connections made with the SFTP client to the given number of milliseconds. If the given
      timeout is less than or equal to zero, the timeout is set to the same value as the script context timeout but
      will only be set to a maximum of 30 seconds.
      
      
      The maximum and default timeout depend on the script context timeout. The maximum timeout is set to a maximum of
      2 minutes. The default timeout for a new client is set to a maximum of 30 seconds.
      
      
      This method can be called at any time, and will affect the next connection made with this client. It is not
      possible to set the timeout for an open connection.


    **Parameters:**
    - timeoutMillis - timeout, in milliseconds, up to a maximum of 2 minutes.


---

<!-- prettier-ignore-end -->

<!-- document id=2405f3f148a2e04c62888eb0696f7030522e33ed56bba264b038a6f2c3115391 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.SFTPFileInfo.md -->

<!-- prettier-ignore-start -->
# Class SFTPFileInfo

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.SFTPFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPFileInfo.md)

The class is used to store information about a remote file.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## Property Summary

| Property | Description |
| --- | --- |
| [directory](#directory): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the file is a directory. |
| [modificationTime](#modificationtime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the last modification time of the file/directory. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the file/directory. |
| [size](#size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the size of the file/directory. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SFTPFileInfo](#sftpfileinfostring-number-boolean-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs the SFTPFileInfo instance. |

## Method Summary

| Method | Description |
| --- | --- |
| [getDirectory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPFileInfo.md#getdirectory)() | Identifies if the file is a directory. |
| [getModificationTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPFileInfo.md#getmodificationtime)() | Returns the last modification time of the file/directory. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPFileInfo.md#getname)() | Returns the name of the file/directory. |
| [getSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPFileInfo.md#getsize)() | Returns the size of the file/directory. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### directory
- directory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the file is a directory.


---

### modificationTime
- modificationTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the last modification time of the file/directory.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the file/directory.


---

### size
- size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the size of the file/directory.


---

## Constructor Details

### SFTPFileInfo(String, Number, Boolean, Number)
- SFTPFileInfo(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), directory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), mtime: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs the SFTPFileInfo instance.

    **Parameters:**
    - name - the name of the file.
    - size - the size of the file.
    - directory - controls if the file is a directory.
    - mtime - last modification time.


---

## Method Details

### getDirectory()
- getDirectory(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the file is a directory.

    **Returns:**
    - true if the file is a directory, false otherwise.


---

### getModificationTime()
- getModificationTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the last modification time of the file/directory.

    **Returns:**
    - the last modification time.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the file/directory.

    **Returns:**
    - the name.


---

### getSize()
- getSize(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the file/directory.

    **Returns:**
    - the size.


---

<!-- prettier-ignore-end -->

<!-- document id=d76e7e026801582f978d103f9a385644a5eb06c9a5bc1ca321c0490c31c619d6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.Shipment.md -->

<!-- prettier-ignore-start -->
# Class Shipment

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)

Represents an order shipment.


## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[SHIPMENT_NOTSHIPPED](#shipment_notshipped): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0~~ | Shipment shipping status representing 'Not shipped'. |
| ~~[SHIPMENT_SHIPPED](#shipment_shipped): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2~~ | Shipment shipping status representing 'Shipped'. |
| [SHIPPING_STATUS_NOTSHIPPED](#shipping_status_notshipped): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Shipment shipping status representing 'Not shipped'. |
| [SHIPPING_STATUS_SHIPPED](#shipping_status_shipped): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Shipment shipping status representing 'Shipped'. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of this shipment ("me" for the default shipment). |
| [adjustedMerchandizeTotalGrossPrice](#adjustedmerchandizetotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted total gross price, including tax, in the purchase currency. |
| [adjustedMerchandizeTotalNetPrice](#adjustedmerchandizetotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted net price, excluding tax, in the purchase currency. |
| [adjustedMerchandizeTotalPrice](#adjustedmerchandizetotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the product total price after all product discounts. |
| [adjustedMerchandizeTotalTax](#adjustedmerchandizetotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total adjusted product tax in the purchase currency. |
| [adjustedShippingTotalGrossPrice](#adjustedshippingtotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted sum of all shipping line items of the shipment, including shipping adjustuments and tax |
| [adjustedShippingTotalNetPrice](#adjustedshippingtotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of all shipping line items of the shipment, including shipping adjustments, excluding tax. |
| [adjustedShippingTotalPrice](#adjustedshippingtotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted shipping total price. |
| [adjustedShippingTotalTax](#adjustedshippingtotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the tax of all shipping line items of the shipment , including shipping adjustments. |
| [allLineItems](#alllineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all line items related to the shipment. |
| [default](#default): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this is the default shipment. |
| [gift](#gift): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | Returns true if this line item represents a gift, false otherwise. |
| [giftCertificateLineItems](#giftcertificatelineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all gift certificate line items of the shipment. |
| [giftMessage](#giftmessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the value set for gift message or null if no value set. |
| [merchandizeTotalGrossPrice](#merchandizetotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the gross product subtotal in the purchase currency. |
| [merchandizeTotalNetPrice](#merchandizetotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the net product subtotal, excluding tax, in the purchase currency. |
| [merchandizeTotalPrice](#merchandizetotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the product total price. |
| ~~[merchandizeTotalPriceAdjustments](#merchandizetotalpriceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)` | Returns a collection of price adjustments that have been applied to the totals, such as a promotion on the  purchase value (i.e. |
| [merchandizeTotalTax](#merchandizetotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total product tax in the purchase currency. |
| [productLineItems](#productlineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all product line items related to this shipment. |
| [proratedMerchandizeTotalPrice](#proratedmerchandizetotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total product price of the shipment, including product-level adjustments and prorating all  Buy-X-Get-Y and order-level adjustments, according to the scheme described in  [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). |
| [shipmentNo](#shipmentno): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the shipment number for this shipment. |
| [shippingAddress](#shippingaddress): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md) `(read-only)` | Returns the shipping address or null if none is set. |
| [shippingLineItems](#shippinglineitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all shipping line items of the shipment, excluding any product-level shipping costs that  are associated with [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)s of the shipment. |
| [shippingMethod](#shippingmethod): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md) | Returns the shipping method or null if none is set. |
| [shippingMethodID](#shippingmethodid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the shipping method ID or null if none is set. |
| [shippingPriceAdjustments](#shippingpriceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of price adjustments that have been applied to the shipping costs of the shipment, for  example by the promotions engine.<br/>  Note that this method returns all shipping price adjustments in this shipment, regardless of which shipping line  item they belong to. |
| [shippingStatus](#shippingstatus): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Returns the shipping status. |
| [shippingTotalGrossPrice](#shippingtotalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of all shipping line items of the shipment, including tax, excluding shipping adjustments. |
| [shippingTotalNetPrice](#shippingtotalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the sum of all shipping line items of the shipment, excluding tax and adjustments. |
| [shippingTotalPrice](#shippingtotalprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the shipping total price. |
| [shippingTotalTax](#shippingtotaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the tax of all shipping line items of the shipment before shipping adjustments have been applied. |
| [standardShippingLineItem](#standardshippinglineitem): [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md) `(read-only)` | Convenience method. |
| [totalGrossPrice](#totalgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total gross price of the shipment in the purchase currency. |
| [totalNetPrice](#totalnetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total net price of the shipment in the purchase currency. |
| [totalTax](#totaltax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the total tax for the shipment in the purchase currency. |
| [trackingNumber](#trackingnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the tracking number of this shipment. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#createshippingaddress)() | A shipment has initially no shipping address. |
| [createShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#createshippinglineitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new shipping line item for this shipment. |
| ~~[createShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#createshippingpriceadjustmentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Creates a shipping price adjustment to be applied to the shipment. |
| [getAdjustedMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedmerchandizetotalgrossprice)() | Returns the adjusted total gross price, including tax, in the purchase currency. |
| [getAdjustedMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedmerchandizetotalnetprice)() | Returns the adjusted net price, excluding tax, in the purchase currency. |
| [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedmerchandizetotalprice)() | Returns the product total price after all product discounts. |
| [getAdjustedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedmerchandizetotalpriceboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Returns the total product price including product-level adjustments and, optionally, prorated order-level  adjustments. |
| [getAdjustedMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedmerchandizetotaltax)() | Returns the total adjusted product tax in the purchase currency. |
| [getAdjustedShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedshippingtotalgrossprice)() | Returns the adjusted sum of all shipping line items of the shipment, including shipping adjustuments and tax |
| [getAdjustedShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedshippingtotalnetprice)() | Returns the sum of all shipping line items of the shipment, including shipping adjustments, excluding tax. |
| [getAdjustedShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedshippingtotalprice)() | Returns the adjusted shipping total price. |
| [getAdjustedShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedshippingtotaltax)() | Returns the tax of all shipping line items of the shipment , including shipping adjustments. |
| [getAllLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getalllineitems)() | Returns all line items related to the shipment. |
| [getGiftCertificateLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getgiftcertificatelineitems)() | Returns all gift certificate line items of the shipment. |
| [getGiftMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getgiftmessage)() | Returns the value set for gift message or null if no value set. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getid)() | Returns the ID of this shipment ("me" for the default shipment). |
| [getMerchandizeTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getmerchandizetotalgrossprice)() | Returns the gross product subtotal in the purchase currency. |
| [getMerchandizeTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getmerchandizetotalnetprice)() | Returns the net product subtotal, excluding tax, in the purchase currency. |
| [getMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getmerchandizetotalprice)() | Returns the product total price. |
| ~~[getMerchandizeTotalPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getmerchandizetotalpriceadjustments)()~~ | Returns a collection of price adjustments that have been applied to the totals, such as a promotion on the  purchase value (i.e. |
| [getMerchandizeTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getmerchandizetotaltax)() | Returns the total product tax in the purchase currency. |
| [getProductLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getproductlineitems)() | Returns a collection of all product line items related to this shipment. |
| [getProratedMerchandizeTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getproratedmerchandizetotalprice)() | Returns the total product price of the shipment, including product-level adjustments and prorating all  Buy-X-Get-Y and order-level adjustments, according to the scheme described in  [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). |
| [getShipmentNo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshipmentno)() | Returns the shipment number for this shipment. |
| [getShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingaddress)() | Returns the shipping address or null if none is set. |
| [getShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippinglineitemstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the shipping line item identified by the specified ID, or null if not found. |
| [getShippingLineItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippinglineitems)() | Returns a collection of all shipping line items of the shipment, excluding any product-level shipping costs that  are associated with [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)s of the shipment. |
| [getShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingmethod)() | Returns the shipping method or null if none is set. |
| [getShippingMethodID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingmethodid)() | Returns the shipping method ID or null if none is set. |
| ~~[getShippingPriceAdjustmentByPromotionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingpriceadjustmentbypromotionidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns the shipping price adjustment associated with the specified promotion ID. |
| [getShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingpriceadjustments)() | Returns a collection of price adjustments that have been applied to the shipping costs of the shipment, for  example by the promotions engine.<br/>  Note that this method returns all shipping price adjustments in this shipment, regardless of which shipping line  item they belong to. |
| [getShippingStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingstatus)() | Returns the shipping status. |
| [getShippingTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingtotalgrossprice)() | Returns the sum of all shipping line items of the shipment, including tax, excluding shipping adjustments. |
| [getShippingTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingtotalnetprice)() | Returns the sum of all shipping line items of the shipment, excluding tax and adjustments. |
| [getShippingTotalPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingtotalprice)() | Returns the shipping total price. |
| [getShippingTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getshippingtotaltax)() | Returns the tax of all shipping line items of the shipment before shipping adjustments have been applied. |
| [getStandardShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getstandardshippinglineitem)() | Convenience method. |
| [getTotalGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#gettotalgrossprice)() | Returns the total gross price of the shipment in the purchase currency. |
| [getTotalNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#gettotalnetprice)() | Returns the total net price of the shipment in the purchase currency. |
| [getTotalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#gettotaltax)() | Returns the total tax for the shipment in the purchase currency. |
| [getTrackingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#gettrackingnumber)() | Returns the tracking number of this shipment. |
| [isDefault](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#isdefault)() | Returns true if this is the default shipment. |
| [isGift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#isgift)() | Returns true if this line item represents a gift, false otherwise. |
| [removeShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#removeshippinglineitemshippinglineitem)([ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)) | Removes the specified shipping line item and any of its dependent shipping price adjustments. |
| ~~[removeShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#removeshippingpriceadjustmentpriceadjustment)([PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md))~~ | Removes the specified shipping price adjustment from the shipment. |
| [setGift](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#setgiftboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Controls if this line item is a gift or not. |
| [setGiftMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#setgiftmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the value to set for the gift message. |
| [setShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#setshippingmethodshippingmethod)([ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)) | Set the specified shipping method for the specified shipment. |
| [setShippingStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#setshippingstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Sets the shipping status of the shipment. |
| [setTrackingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#settrackingnumberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the tracking number of this shipment. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### SHIPMENT_NOTSHIPPED

- ~~SHIPMENT_NOTSHIPPED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0~~
  - : Shipment shipping status representing 'Not shipped'.

    **Deprecated:**
**warning:** Use [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#shipping_status_notshipped) instead.

---

### SHIPMENT_SHIPPED

- ~~SHIPMENT_SHIPPED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2~~
  - : Shipment shipping status representing 'Shipped'.

    **Deprecated:**
**warning:** Use [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#shipping_status_shipped) instead.

---

### SHIPPING_STATUS_NOTSHIPPED

- SHIPPING_STATUS_NOTSHIPPED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Shipment shipping status representing 'Not shipped'.


---

### SHIPPING_STATUS_SHIPPED

- SHIPPING_STATUS_SHIPPED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Shipment shipping status representing 'Shipped'.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of this shipment ("me" for the default shipment).


---

### adjustedMerchandizeTotalGrossPrice
- adjustedMerchandizeTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted total gross price, including tax, in the purchase currency. The adjusted total gross price
      represents the sum of product prices and adjustments including tax, excluding services.



---

### adjustedMerchandizeTotalNetPrice
- adjustedMerchandizeTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted net price, excluding tax, in the purchase currency. The adjusted net price represents the
      the sum of product prices and adjustments, excluding services and tax.



---

### adjustedMerchandizeTotalPrice
- adjustedMerchandizeTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the product total price after all product discounts. If the line item container is based on net pricing
      the adjusted product total net price is returned. If the line item container is based on gross pricing the
      adjusted product total gross price is returned.



---

### adjustedMerchandizeTotalTax
- adjustedMerchandizeTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total adjusted product tax in the purchase currency. The total adjusted product tax represents the
      tax on products and adjustments, excluding services.



---

### adjustedShippingTotalGrossPrice
- adjustedShippingTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted sum of all shipping line items of the shipment, including shipping adjustuments and tax


---

### adjustedShippingTotalNetPrice
- adjustedShippingTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of all shipping line items of the shipment, including shipping adjustments, excluding tax.


---

### adjustedShippingTotalPrice
- adjustedShippingTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted shipping total price. If the line item container is based on net pricing the adjusted
      shipping total net price is returned. If the line item container is based on gross pricing the adjusted shipping
      total gross price is returned.



---

### adjustedShippingTotalTax
- adjustedShippingTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the tax of all shipping line items of the shipment , including shipping adjustments.


---

### allLineItems
- allLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all line items related to the shipment.
      
      
      The returned collection may include line items of the following types:
      
      - [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
      - [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
      - [GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md)
      - [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
      
      Their common type is [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md).
      
      
      Each [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) in the collection may itself contain bundled or option product line items,
      as well as a product-level shipping line item.



---

### default
- default: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this is the default shipment. The default is the shipment with ID "me". If no shipment with
      ID "me" exists, the shipment with the lowest ID is used as the default. A "me" shipment can be absent if
      [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) removed it for being empty, in which case another
      shipment becomes the default.



---

### gift
- gift: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this line item represents a gift, false otherwise.


---

### giftCertificateLineItems
- giftCertificateLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all gift certificate line items of the shipment.


---

### giftMessage
- giftMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for gift message or null if no value set.


---

### merchandizeTotalGrossPrice
- merchandizeTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the gross product subtotal in the purchase currency. The gross product subtotal represents the sum of
      product prices including tax, excluding services and adjustments.



---

### merchandizeTotalNetPrice
- merchandizeTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the net product subtotal, excluding tax, in the purchase currency. The net product subtotal represents
      the sum of product prices, excluding services, adjustments, and tax.



---

### merchandizeTotalPrice
- merchandizeTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the product total price. If the line item container is based on net pricing the product total net
      price is returned. If the line item container is based on gross pricing the product total gross price is
      returned.



---

### merchandizeTotalPriceAdjustments
- ~~merchandizeTotalPriceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~ `(read-only)`
  - : Returns a collection of price adjustments that have been applied to the totals, such as a promotion on the
      purchase value (i.e. $10 Off or 10% Off).


    **Deprecated:**
**warning:** Shipments cannot have product price adjustments, therefore this method will always return an
            empty collection

---

### merchandizeTotalTax
- merchandizeTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total product tax in the purchase currency. The total product tax represents the tax on products,
      excluding services and adjustments.



---

### productLineItems
- productLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all product line items related to this shipment.


---

### proratedMerchandizeTotalPrice
- proratedMerchandizeTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total product price of the shipment, including product-level adjustments and prorating all
      Buy-X-Get-Y and order-level adjustments, according to the scheme described in
      [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). For net pricing the net price is returned. For gross
      pricing, the gross price is returned.



---

### shipmentNo
- shipmentNo: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the shipment number for this shipment.
      
      
      When an order is placed ([OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder)) shipment number will be filled using a
      sequence. Before order was placed `null` will be returned.



---

### shippingAddress
- shippingAddress: [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md) `(read-only)`
  - : Returns the shipping address or null if none is set.


---

### shippingLineItems
- shippingLineItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all shipping line items of the shipment, excluding any product-level shipping costs that
      are associated with [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)s of the shipment.



---

### shippingMethod
- shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)
  - : Returns the shipping method or null if none is set.


---

### shippingMethodID
- shippingMethodID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the shipping method ID or null if none is set.


---

### shippingPriceAdjustments
- shippingPriceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of price adjustments that have been applied to the shipping costs of the shipment, for
      example by the promotions engine.
      
      Note that this method returns all shipping price adjustments in this shipment, regardless of which shipping line
      item they belong to. Use [ShippingLineItem.getShippingPriceAdjustments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getshippingpriceadjustments) to retrieve the shipping
      price adjustments associated with a specific shipping line item.



---

### shippingStatus
- shippingStatus: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the shipping status. Possible values are SHIPMENT\_NOTSHIPPED or SHIPMENT\_SHIPPED.


---

### shippingTotalGrossPrice
- shippingTotalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of all shipping line items of the shipment, including tax, excluding shipping adjustments.


---

### shippingTotalNetPrice
- shippingTotalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the sum of all shipping line items of the shipment, excluding tax and adjustments.


---

### shippingTotalPrice
- shippingTotalPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the shipping total price. If the line item container is based on net pricing the shipping total net price
      is returned. If the line item container is based on gross pricing the shipping total gross price is returned.



---

### shippingTotalTax
- shippingTotalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the tax of all shipping line items of the shipment before shipping adjustments have been applied.


---

### standardShippingLineItem
- standardShippingLineItem: [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md) `(read-only)`
  - : Convenience method. Same as `getShippingLineItem(ShippingLineItem.STANDARD_SHIPPING_ID)`


---

### totalGrossPrice
- totalGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total gross price of the shipment in the purchase currency. The total gross price is the sum of
      product prices, service prices, adjustments, and tax.



---

### totalNetPrice
- totalNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total net price of the shipment in the purchase currency. The total net price is the sum of product
      prices, service prices, and adjustments, excluding tax.



---

### totalTax
- totalTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the total tax for the shipment in the purchase currency.


---

### trackingNumber
- trackingNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tracking number of this shipment.


---

## Method Details

### createShippingAddress()
- createShippingAddress(): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)
  - : A shipment has initially no shipping address. This method creates a shipping address for the shipment and
      replaces an existing shipping address.


    **Returns:**
    - The new shipping address of the shipment


---

### createShippingLineItem(String)
- createShippingLineItem(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
  - : Creates a new shipping line item for this shipment. If the specified ID is already assigned to any of the
      existing shipping line items of the shipment, the method throws an exception.


    **Parameters:**
    - id - The id to use to locate the new shipping line item.

    **Returns:**
    - The new shipping line item.


---

### createShippingPriceAdjustment(String)
- ~~createShippingPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)~~
  - : Creates a shipping price adjustment to be applied to the shipment. The price adjustment implicitly belongs to the
      standard shipping line item if this line item exists, otherwise it belongs to the shipment itself.
      
      The promotion ID is mandatory and must not be the ID of any actual promotion defined in Salesforce B2C
      Commerce.
      
      If there already exists a shipping price adjustment line item referring to the specified promotion ID, an
      exception is thrown.


    **Parameters:**
    - promotionID - Promotion ID

    **Returns:**
    - The new price adjustment line item.

    **Deprecated:**
**warning:** Deprecated in favor of [ShippingLineItem.createShippingPriceAdjustment(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#createshippingpriceadjustmentstring), which
            explicitly relates the price adjustment to a shipping line item.

---

### getAdjustedMerchandizeTotalGrossPrice()
- getAdjustedMerchandizeTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted total gross price, including tax, in the purchase currency. The adjusted total gross price
      represents the sum of product prices and adjustments including tax, excluding services.


    **Returns:**
    - the adjusted total gross price, including tax, in the purchase currency.


---

### getAdjustedMerchandizeTotalNetPrice()
- getAdjustedMerchandizeTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted net price, excluding tax, in the purchase currency. The adjusted net price represents the
      the sum of product prices and adjustments, excluding services and tax.


    **Returns:**
    - the adjusted net price, excluding tax, in the purchase currency.


---

### getAdjustedMerchandizeTotalPrice()
- getAdjustedMerchandizeTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the product total price after all product discounts. If the line item container is based on net pricing
      the adjusted product total net price is returned. If the line item container is based on gross pricing the
      adjusted product total gross price is returned.


    **Returns:**
    - either the adjusted product total net or gross price.


---

### getAdjustedMerchandizeTotalPrice(Boolean)
- getAdjustedMerchandizeTotalPrice(applyOrderLevelAdjustments: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total product price including product-level adjustments and, optionally, prorated order-level
      adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.


    **Parameters:**
    - applyOrderLevelAdjustments - If true, prorated order-level adjustments will be applied to total price

    **Returns:**
    - Adjusted net or gross product total price

    **See Also:**
    - [getAdjustedMerchandizeTotalPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#getadjustedmerchandizetotalprice)


---

### getAdjustedMerchandizeTotalTax()
- getAdjustedMerchandizeTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total adjusted product tax in the purchase currency. The total adjusted product tax represents the
      tax on products and adjustments, excluding services.


    **Returns:**
    - the total tax in purchase currency.


---

### getAdjustedShippingTotalGrossPrice()
- getAdjustedShippingTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted sum of all shipping line items of the shipment, including shipping adjustuments and tax

    **Returns:**
    - the adjusted sum of all shipping line items of the shipment, including shipping adjustuments and tax


---

### getAdjustedShippingTotalNetPrice()
- getAdjustedShippingTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of all shipping line items of the shipment, including shipping adjustments, excluding tax.

    **Returns:**
    - the sum of all shipping line items of the shipment, including shipping adjustments, excluding tax.


---

### getAdjustedShippingTotalPrice()
- getAdjustedShippingTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted shipping total price. If the line item container is based on net pricing the adjusted
      shipping total net price is returned. If the line item container is based on gross pricing the adjusted shipping
      total gross price is returned.


    **Returns:**
    - either the adjusted shipping total net or gross price


---

### getAdjustedShippingTotalTax()
- getAdjustedShippingTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax of all shipping line items of the shipment , including shipping adjustments.

    **Returns:**
    - the tax of all shipping line items of the shipment , including shipping adjustments.


---

### getAllLineItems()
- getAllLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all line items related to the shipment.
      
      
      The returned collection may include line items of the following types:
      
      - [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)
      - [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
      - [GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md)
      - [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
      
      Their common type is [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md).
      
      
      Each [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) in the collection may itself contain bundled or option product line items,
      as well as a product-level shipping line item.


    **Returns:**
    - all line items related to ths shipment.


---

### getGiftCertificateLineItems()
- getGiftCertificateLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all gift certificate line items of the shipment.

    **Returns:**
    - A collection of all GiftCertificateLineItems of the shipment.


---

### getGiftMessage()
- getGiftMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value set for gift message or null if no value set.

    **Returns:**
    - the value set for gift message or null if no value set.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of this shipment ("me" for the default shipment).

    **Returns:**
    - the ID of this shipment


---

### getMerchandizeTotalGrossPrice()
- getMerchandizeTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the gross product subtotal in the purchase currency. The gross product subtotal represents the sum of
      product prices including tax, excluding services and adjustments.


    **Returns:**
    - the total gross price, including tax, in the purchase currency.


---

### getMerchandizeTotalNetPrice()
- getMerchandizeTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the net product subtotal, excluding tax, in the purchase currency. The net product subtotal represents
      the sum of product prices, excluding services, adjustments, and tax.


    **Returns:**
    - the net price, excluding tax, in the purchase currency.


---

### getMerchandizeTotalPrice()
- getMerchandizeTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the product total price. If the line item container is based on net pricing the product total net
      price is returned. If the line item container is based on gross pricing the product total gross price is
      returned.


    **Returns:**
    - either the product total net or gross price


---

### getMerchandizeTotalPriceAdjustments()
- ~~getMerchandizeTotalPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)~~
  - : Returns a collection of price adjustments that have been applied to the totals, such as a promotion on the
      purchase value (i.e. $10 Off or 10% Off).


    **Returns:**
    - a collection of price adjustments that have been applied to the totals, such as a promotion on the
              purchase value (i.e. $10 Off or 10% Off).


    **Deprecated:**
**warning:** Shipments cannot have product price adjustments, therefore this method will always return an
            empty collection

---

### getMerchandizeTotalTax()
- getMerchandizeTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total product tax in the purchase currency. The total product tax represents the tax on products,
      excluding services and adjustments.


    **Returns:**
    - the total tax in purchase currency.


---

### getProductLineItems()
- getProductLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all product line items related to this shipment.

    **Returns:**
    - a collection of all product line items related to this shipment.


---

### getProratedMerchandizeTotalPrice()
- getProratedMerchandizeTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total product price of the shipment, including product-level adjustments and prorating all
      Buy-X-Get-Y and order-level adjustments, according to the scheme described in
      [PriceAdjustment.getProratedPrices()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md#getproratedprices). For net pricing the net price is returned. For gross
      pricing, the gross price is returned.


    **Returns:**
    - Adjusted and prorated net or gross product total price


---

### getShipmentNo()
- getShipmentNo(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipment number for this shipment.
      
      
      When an order is placed ([OrderMgr.placeOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#placeorderorder)) shipment number will be filled using a
      sequence. Before order was placed `null` will be returned.


    **Returns:**
    - the shipment number for this shipment.


---

### getShippingAddress()
- getShippingAddress(): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)
  - : Returns the shipping address or null if none is set.

    **Returns:**
    - the shipping address or null if none is set.


---

### getShippingLineItem(String)
- getShippingLineItem(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
  - : Returns the shipping line item identified by the specified ID, or null if not found.
      
      
      To get the standard shipping line item for this shipment, use the identifier
      [ShippingLineItem.STANDARD_SHIPPING_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#standard_shipping_id).


    **Parameters:**
    - id - the identifier to use to locate the shipping line item.

    **Returns:**
    - the shipping line item identified by the specified ID, or null if not found.


---

### getShippingLineItems()
- getShippingLineItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all shipping line items of the shipment, excluding any product-level shipping costs that
      are associated with [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)s of the shipment.


    **Returns:**
    - a collection of all shipping line items of the shipment, excluding any product-level shipping costs.


---

### getShippingMethod()
- getShippingMethod(): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)
  - : Returns the shipping method or null if none is set.

    **Returns:**
    - the shipping method or null if none is set.


---

### getShippingMethodID()
- getShippingMethodID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping method ID or null if none is set.

    **Returns:**
    - the shipping method ID or null if none is set.


---

### getShippingPriceAdjustmentByPromotionID(String)
- ~~getShippingPriceAdjustmentByPromotionID(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)~~
  - : Returns the shipping price adjustment associated with the specified promotion ID.

    **Parameters:**
    - promotionID - the promotion ID

    **Returns:**
    - The price adjustment associated with the given promotion ID


---

### getShippingPriceAdjustments()
- getShippingPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of price adjustments that have been applied to the shipping costs of the shipment, for
      example by the promotions engine.
      
      Note that this method returns all shipping price adjustments in this shipment, regardless of which shipping line
      item they belong to. Use [ShippingLineItem.getShippingPriceAdjustments()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getshippingpriceadjustments) to retrieve the shipping
      price adjustments associated with a specific shipping line item.


    **Returns:**
    - a collection of price adjustments that have been applied to the shipping costs of the shipment.


---

### getShippingStatus()
- getShippingStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the shipping status. Possible values are SHIPMENT\_NOTSHIPPED or SHIPMENT\_SHIPPED.

    **Returns:**
    - the shipping status. Possible values are SHIPMENT\_NOTSHIPPED or SHIPMENT\_SHIPPED.


---

### getShippingTotalGrossPrice()
- getShippingTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of all shipping line items of the shipment, including tax, excluding shipping adjustments.

    **Returns:**
    - the sum of all shipping line items of the shipment, including tax, excluding shipping adjustments.


---

### getShippingTotalNetPrice()
- getShippingTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the sum of all shipping line items of the shipment, excluding tax and adjustments.

    **Returns:**
    - the sum of all shipping line items of the shipment, excluding tax and adjustments.


---

### getShippingTotalPrice()
- getShippingTotalPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the shipping total price. If the line item container is based on net pricing the shipping total net price
      is returned. If the line item container is based on gross pricing the shipping total gross price is returned.


    **Returns:**
    - either the shipping total net or gross price


---

### getShippingTotalTax()
- getShippingTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax of all shipping line items of the shipment before shipping adjustments have been applied.

    **Returns:**
    - the tax of all shipping line items of the shipment before shipping adjustments have been applied.


---

### getStandardShippingLineItem()
- getStandardShippingLineItem(): [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)
  - : Convenience method. Same as `getShippingLineItem(ShippingLineItem.STANDARD_SHIPPING_ID)`

    **Returns:**
    - The standard shipping line item, or null if it does not exist.


---

### getTotalGrossPrice()
- getTotalGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total gross price of the shipment in the purchase currency. The total gross price is the sum of
      product prices, service prices, adjustments, and tax.


    **Returns:**
    - the grand total price gross of tax for the shipment, in purchase currency.


---

### getTotalNetPrice()
- getTotalNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total net price of the shipment in the purchase currency. The total net price is the sum of product
      prices, service prices, and adjustments, excluding tax.


    **Returns:**
    - the grand total price for the shipment net of tax, in purchase currency.


---

### getTotalTax()
- getTotalTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the total tax for the shipment in the purchase currency.

    **Returns:**
    - the total tax for the shipment, in purchase currency.


---

### getTrackingNumber()
- getTrackingNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tracking number of this shipment.

    **Returns:**
    - the tracking number of this shipment.


---

### isDefault()
- isDefault(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this is the default shipment. The default is the shipment with ID "me". If no shipment with
      ID "me" exists, the shipment with the lowest ID is used as the default. A "me" shipment can be absent if
      [OrderMgr.createOrder(Basket)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket) removed it for being empty, in which case another
      shipment becomes the default.


    **Returns:**
    - `true` if this shipment is the default shipment


---

### isGift()
- isGift(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this line item represents a gift, false otherwise.

    **Returns:**
    - true if this line item represents a gift, false otherwise.


---

### removeShippingLineItem(ShippingLineItem)
- removeShippingLineItem(shippingLineItem: [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)): void
  - : Removes the specified shipping line item and any of its dependent shipping price adjustments.

    **Parameters:**
    - shippingLineItem - The shipping line item to be removed.


---

### removeShippingPriceAdjustment(PriceAdjustment)
- ~~removeShippingPriceAdjustment(priceAdjustment: [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)): void~~
  - : Removes the specified shipping price adjustment from the shipment.

    **Parameters:**
    - priceAdjustment - The price adjustment line item to remove

    **Deprecated:**
**warning:** Deprecated in favor of
            [ShippingLineItem.removeShippingPriceAdjustment(PriceAdjustment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#removeshippingpriceadjustmentpriceadjustment) since shipping price
            adjustments belong to a specific shipping line item.

---

### setGift(Boolean)
- setGift(isGift: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Controls if this line item is a gift or not.

    **Parameters:**
    - isGift - set to true if you want this line item to represent a gift.


---

### setGiftMessage(String)
- setGiftMessage(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the value to set for the gift message.

    **Parameters:**
    - message - the value to set for the gift message.


---

### setShippingMethod(ShippingMethod)
- setShippingMethod(method: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)): void
  - : Set the specified shipping method for the specified shipment.

    **Parameters:**
    - method - the shipping method to use.


---

### setShippingStatus(Number)
- setShippingStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Sets the shipping status of the shipment. 
      
      Possible values are [SHIPPING_STATUS_NOTSHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#shipping_status_notshipped) or [SHIPPING_STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md#shipping_status_shipped).


    **Parameters:**
    - status - Shipment shipping status


---

### setTrackingNumber(String)
- setTrackingNumber(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the tracking number of this shipment.

    **Parameters:**
    - aValue - the tracking number of this shipment.


---

<!-- prettier-ignore-end -->

<!-- document id=4acb1d9c4753771fe99104996d915a55ed143bad95412366ea57f5e3937deaf2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShipmentShippingCost.md -->

<!-- prettier-ignore-start -->
# Class ShipmentShippingCost

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.ShipmentShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingCost.md)

Represents shipping cost applied to shipments. 


Returned by
[ShipmentShippingModel.getShippingCost(ShippingMethod)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md#getshippingcostshippingmethod).



## Property Summary

| Property | Description |
| --- | --- |
| [amount](#amount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the shipping amount. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingCost.md#getamount)() | Returns the shipping amount. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### amount
- amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the shipping amount.


---

## Method Details

### getAmount()
- getAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the shipping amount.

    **Returns:**
    - Shipping amount


---

<!-- prettier-ignore-end -->

<!-- document id=a3848eec63e795a01baf2385989ff6a889ee8f7af8ec8d5ff73d98237580241d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShipmentShippingModel.md -->

<!-- prettier-ignore-start -->
# Class ShipmentShippingModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.ShipmentShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md)

Instances of ShipmentShippingModel provide access to shipment-level
shipping information, such as applicable and inapplicable shipping methods
and shipping cost. 


Use [ShippingMgr.getShipmentShippingModel(Shipment)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#getshipmentshippingmodelshipment) to get
the shipping model for a specific shipment.



## Property Summary

| Property | Description |
| --- | --- |
| [applicableShippingMethods](#applicableshippingmethods): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the active applicable shipping methods for the shipment related  to this shipping model. |
| [inapplicableShippingMethods](#inapplicableshippingmethods): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the active inapplicable shipping methods for the shipment related  to this shipping model. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getApplicableShippingMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md#getapplicableshippingmethods)() | Returns the active applicable shipping methods for the shipment related  to this shipping model. |
| [getApplicableShippingMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md#getapplicableshippingmethodsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the active applicable shipping methods for the shipment related  to this shipping model and the specified shipping address. |
| [getInapplicableShippingMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md#getinapplicableshippingmethods)() | Returns the active inapplicable shipping methods for the shipment related  to this shipping model. |
| [getInapplicableShippingMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md#getinapplicableshippingmethodsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the active inapplicable shipping methods for the shipment related  to this shipping model and the specified shipping address. |
| [getShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md#getshippingcostshippingmethod)([ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)) | Returns the shipping cost object for the related shipment and  the specified shipping method. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### applicableShippingMethods
- applicableShippingMethods: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the active applicable shipping methods for the shipment related
      to this shipping model. A shipping method is applicable for a shipment
      if it does not exclude any of the products in the shipment, and does
      not exclude the shipment's shipping address, if this is set. Also checks
      that the the shipment customer belongs to an assigned customer group of the shipment
      (if any are assigned).



---

### inapplicableShippingMethods
- inapplicableShippingMethods: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the active inapplicable shipping methods for the shipment related
      to this shipping model. A shipping method is inapplicable for a shipment
      if it is inapplicable for at least one product contained in the
      shipment, or the shipping address is excluded by the shipping method, or the
      shipping method is restricted to customer groups that the shipment customer
      is not a part of.



---

## Method Details

### getApplicableShippingMethods()
- getApplicableShippingMethods(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active applicable shipping methods for the shipment related
      to this shipping model. A shipping method is applicable for a shipment
      if it does not exclude any of the products in the shipment, and does
      not exclude the shipment's shipping address, if this is set. Also checks
      that the the shipment customer belongs to an assigned customer group of the shipment
      (if any are assigned).


    **Returns:**
    - Applicable shipping methods for the shipment


---

### getApplicableShippingMethods(Object)
- getApplicableShippingMethods(shippingAddressObj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active applicable shipping methods for the shipment related
      to this shipping model and the specified shipping address. A shipping
      method is applicable if it does not exclude any of the products in the
      shipment, it does not exclude the specified shipping address, and the
      shipment customer belongs to an assigned customer group for the shipment (if
      any are assigned).
      
      
      The parameter shippingAddressObj must be a JavaScript literal with the
      same properties as an OrderAddress object, or alternatively a Map.
      For example:
      
      
      
      
      ```
      model.getApplicableShippingMethods (
         { countryCode: "US",
           stateCode: "MA,
           custom { POBox : true }
         }
      )
      ```
      
      
      This method is useful when it is needed to retrieve the list of
      applicable shipping methods for an address before the address is saved to
      the shipment.


    **Parameters:**
    - shippingAddressObj - A JavaScript object representing an order             address, must not be null.

    **Returns:**
    - Applicable shipping methods for the shipment


---

### getInapplicableShippingMethods()
- getInapplicableShippingMethods(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active inapplicable shipping methods for the shipment related
      to this shipping model. A shipping method is inapplicable for a shipment
      if it is inapplicable for at least one product contained in the
      shipment, or the shipping address is excluded by the shipping method, or the
      shipping method is restricted to customer groups that the shipment customer
      is not a part of.


    **Returns:**
    - Inapplicable shipping methods for the shipment


---

### getInapplicableShippingMethods(Object)
- getInapplicableShippingMethods(shippingAddressObj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active inapplicable shipping methods for the shipment related
      to this shipping model and the specified shipping address. A shipping
      method is inapplicable if it is inapplicable for at least one product
      contained in the shipment, or the specified shipping address is excluded
      by the shipping method, or the shipping method is restricted to customer
      groups that the shipment customer is not a part of.
      
      
      The parameter shippingAddressObj must be a JavaScript literal with the
      same properties as an OrderAddress object, or alternatively a Map.
      For example:
      
      
      
      
      ```
      model.getApplicableShippingMethods (
         { countryCode: "US",
           stateCode: "MA,
           custom { POBox : true }
         }
      )
      ```
      
      
      This method is useful when it is needed to retrieve the list of
      applicable shipping methods for an address before the address is saved to
      the shipment.


    **Parameters:**
    - shippingAddressObj - A JavaScript object representing an order             address.

    **Returns:**
    - Inapplicable shipping methods for the shipment


---

### getShippingCost(ShippingMethod)
- getShippingCost(shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)): [ShipmentShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingCost.md)
  - : Returns the shipping cost object for the related shipment and
      the specified shipping method. Shipping cost for shipments
      depended on the merchandise total of the shipment. The method
      uses the adjusted merchandise total after product and order discounts,
      and excluding products with product-level fixed-price shipping
      cost.


    **Parameters:**
    - shippingMethod - the shipping method to use.

    **Returns:**
    - Product shipping cost


---

<!-- prettier-ignore-end -->

<!-- document id=8f409195f26db293b2ca27e5644afc1fd2552dc1773434e4126baa799292c683 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.ShippingHooks.md -->

<!-- prettier-ignore-start -->
# Class ShippingHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.ShippingHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md)

This interface represents shipping extension points for Commerce App shipping providers.


These hooks provide integration points for external shipping rate / delivery-estimate services installed via the
Commerce App framework.


**IMPORTANT:** These hooks should **only** be implemented and registered by Commerce Apps
(applications installed via the Commerce App framework with a CAP file). They are not intended for custom merchant
cartridges or storefront implementations. Merchants who want custom shipping calculation logic should use the legacy
`dw.order.calculateShipping` extension point instead.


Hook Registration A function must be defined inside a JavaScript source and must be exported. The script
with the exported hook function must be located inside a site cartridge. Inside the site cartridge a
`package.json` file with a 'hooks' entry must exist:


```
"hooks": "./hooks.json"
```



The hooks entry links to a JSON file, relative to the `package.json` file. This file lists all registered
hooks inside the hooks property:




```
"hooks": [
   {"name": "sfcc.app.shipping.quote", "script": "./quote.js"},
   {"name": "sfcc.app.shipping.calculate", "script": "./calculate.js"}
]
```



A hook entry has a `name` and a `script` property:



- The `name`contains the extension point name (the hook name).
- The `script`contains the script path relative to the hooks file, with the exported hook  function.



**Function Naming Convention:** The exported JavaScript function name must match the last segment of the
extension point name, for example, `quote` or `calculate`.


Hook Lifecycle Each hook fires at a specific surface and lifecycle stage:

- **quote**(checkout): Fires on every invocation of  `GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`. Lets the Commerce App override native  shipping prices and add delivery information for the methods it can quote.
- **calculate**(basket calculation): Fires during basket calculation on every basket operation that  recomputes shipping. Applies provider-supplied shipping rates to the selected `ShippingLineItem`and may  persist provider metadata on the shipment.

Hook Precedence

- When `sfcc.app.shipping.calculate`is registered and the `ShippingAppHooksEnabled`toggle  is on, it takes precedence over the legacy `dw.order.calculateShipping`hook.
- If the Commerce App hook is not registered (or the toggle is off), the platform falls back to  `dw.order.calculateShipping`(if registered).
- If neither hook is available, the platform uses the native default  (`ShippingMgr.applyShippingCost`).



## Constant Summary

| Constant | Description |
| --- | --- |
| [SHIPPING_DOMAIN](#shipping_domain): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "shipping" | The shipping app domain segment used to compose extension-point names under the shared  `sfcc.app` prefix. |
| [extensionPointCalculate](#extensionpointcalculate): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.shipping.calculate" | The extension point name sfcc.app.shipping.calculate. |
| [extensionPointQuote](#extensionpointquote): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.shipping.quote" | The extension point name sfcc.app.shipping.quote. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [calculate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md#calculatelineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | The function is called by extension point [extensionPointCalculate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md#extensionpointcalculate) during basket calculation. |
| [quote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md#quoteshipment-shippingmethodresultwo)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), ShippingMethodResultWO) | The function is called by extension point [extensionPointQuote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md#extensionpointquote) on every invocation of  `GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### SHIPPING_DOMAIN

- SHIPPING_DOMAIN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "shipping"
  - : The shipping app domain segment used to compose extension-point names under the shared
      `sfcc.app` prefix.



---

### extensionPointCalculate

- extensionPointCalculate: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.shipping.calculate"
  - : The extension point name sfcc.app.shipping.calculate.


---

### extensionPointQuote

- extensionPointQuote: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.shipping.quote"
  - : The extension point name sfcc.app.shipping.quote.


---

## Method Details

### calculate(LineItemCtnr)
- calculate(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointCalculate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md#extensionpointcalculate) during basket calculation. It
      applies provider-supplied shipping rates to the selected `ShippingLineItem` and may persist
      provider metadata (for example, a rate id, carrier code, or delivery window) on the shipment via supported
      `custom.*` attributes. This hook fires on every basket operation that recomputes shipping, not only
      before order creation.
      
      
      The hook owns: native fallback (calling `ShippingMgr.applyShippingCost(lineItemCtnr)` if it wants to
      preserve product-level shipping, surcharges, cleanup, and tax-class setup), provider lookup / rate-cache reuse,
      selected-rate application onto the standard shipment shipping line item, and provider metadata persistence
      (custom attributes on the shipment, custom objects, etc.).
      
      
      
      
      **Note:** If the master `dw.order.calculate` hook (not the per-step
      `dw.order.calculateShipping`) is overridden, the entire basket calculation is replaced and the
      platform's automatic shipping hook selection is bypassed. You must manually invoke this hook from within your
      custom `dw.order.calculate` implementation if you want to use Commerce App shipping providers.
      
      
      
      
      **Error Handling:** Both returning a `Status.ERROR` and throwing an exception will
      prevent the basket calculation from completing successfully. The platform logs the error and halts the current
      basket operation. Since order creation requires a successful basket calculation, this also prevents orders from
      being created with incorrect shipping amounts.
      
      
      
      
      **Sample Implementation:**
      
      
      
      
      ```
      function calculate(lineItemCtnr) {
          var ShippingMgr = require('dw/order/ShippingMgr');
          var Status = require('dw/system/Status');
          var Transaction = require('dw/system/Transaction');
      
          // 1. Run native shipping defaults (product-level surcharges, tax classes)
          ShippingMgr.applyShippingCost(lineItemCtnr);
      
          // 2. Look up the provider rate that was selected on the shipment
          var shipment = lineItemCtnr.getDefaultShipment();
          var rateId = shipment.custom.providerRateId;
          if (!rateId) {
              return new Status(Status.OK);
          }
      
          // 3. Apply the provider rate to the shipping line item
          Transaction.wrap(function () {
              var sli = shipment.getStandardShippingLineItem();
              sli.setPriceValue(lookupRate(rateId).price);
          });
      
          return new Status(Status.OK);
      }
      
      exports.calculate = calculate;
      ```


    **Parameters:**
    - lineItemCtnr - the line item container (basket) for which shipping should be calculated.

    **Returns:**
    - `Status.OK` or `null` for success; `Status.ERROR` to block the basket
              calculation with details about the failure. Throwing an exception will also block the basket
              calculation.



---

### quote(Shipment, ShippingMethodResultWO)
- quote(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md), result: ShippingMethodResultWO): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointQuote](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md#extensionpointquote) on every invocation of
      `GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`. ECOM pre-populates a
      `ShippingMethodResultWO` with the applicable shipping methods, each carrying its native price. The
      hook implementation may override prices and delivery information on any methods it can quote. Methods the hook
      does not touch keep their native price.
      
      
      **Error Handling:** To signal a failure, return `new Status(Status.ERROR)`. The platform
      logs that an error status was returned for this hook and the `GET shipping-methods` request fails.
      Uncaught exceptions thrown from the hook are also treated as failures.
      
      
      
      
      **SCAPI Behavior:** When `ScapiHookExecutionEnabled` is disabled, SCAPI requests bypass
      this hook and use native shipping pricing.
      
      
      
      
      **Sample Implementation:**
      
      
      
      
      ```
      function quote(shipment, result) {
          var Status = require('dw/system/Status');
      
          var methods = result.applicableShippingMethods;
          for (var i = 0; i < methods.length; i++) {
              var method = methods[i];
              // ... call provider for this method, set price ...
              method.setPrice(providerPrice);
          }
          return new Status(Status.OK);
      }
      
      exports.quote = quote;
      ```


    **Parameters:**
    - shipment - the shipment for which shipping methods are being displayed.
    - result - the pre-populated result with native prices on each method. Mutated in place by the hook.

    **Returns:**
    - `Status.OK` or `null` for success; `Status.ERROR` to block the request.


---

<!-- prettier-ignore-end -->

<!-- document id=8dd4c6469d9dff66cdb09d5bbebd06cb655150482a5a6a52b127d1b5b11d5169 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShippingLineItem.md -->

<!-- prettier-ignore-start -->
# Class ShippingLineItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
        - [dw.order.ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)

Represents a specific line item in a shipment. The ShippingLineItem defines
the general shipping costs of a shipment.



## Constant Summary

| Constant | Description |
| --- | --- |
| [STANDARD_SHIPPING_ID](#standard_shipping_id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "STANDARD_SHIPPING" | Constant used to get the standard shipping line item. |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of this ShippingLineItem. |
| [adjustedGrossPrice](#adjustedgrossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the price of this shipping line item including tax after  shipping adjustments have been applied. |
| [adjustedNetPrice](#adjustednetprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the price of this shipping line item, excluding tax after  shipping adjustments have been applied. |
| [adjustedPrice](#adjustedprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the adjusted price of this shipping line item. |
| [adjustedTax](#adjustedtax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Returns the tax of this shipping line item after shipping adjustments  have been applied. |
| [orderItem](#orderitem): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)` | Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or `null`. |
| [shippingPriceAdjustments](#shippingpriceadjustments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the collection of shipping price adjustments that have been  applied to this shipping line item. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#createshippingpriceadjustmentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a shipping price adjustment to be applied to the shipping line item.<br/>  The promotion ID is mandatory and must not be the ID of any actual promotion defined in B2C Commerce.<br/>  If there already exists a shipping price adjustment on this shipping line item referring to the specified  promotion ID, an exception is thrown. |
| [createShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#createshippingpriceadjustmentstring-discount)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)) | Creates a shipping price adjustment to be applied to the shipping line item.<br/>  The promotion ID is mandatory and must not be the ID of any actual promotion defined in B2C Commerce. |
| [getAdjustedGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getadjustedgrossprice)() | Returns the price of this shipping line item including tax after  shipping adjustments have been applied. |
| [getAdjustedNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getadjustednetprice)() | Returns the price of this shipping line item, excluding tax after  shipping adjustments have been applied. |
| [getAdjustedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getadjustedprice)() | Returns the adjusted price of this shipping line item. |
| [getAdjustedTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getadjustedtax)() | Returns the tax of this shipping line item after shipping adjustments  have been applied. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getid)() | Returns the ID of this ShippingLineItem. |
| [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getorderitem)() | Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or `null`. |
| [getShippingPriceAdjustments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#getshippingpriceadjustments)() | Returns the collection of shipping price adjustments that have been  applied to this shipping line item. |
| [removeShippingPriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md#removeshippingpriceadjustmentpriceadjustment)([PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)) | Removes the specified shipping price adjustment from this shipping line  item. |

### Methods inherited from class LineItem

[getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getbaseprice), [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getgrossprice), [getLineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemctnr), [getLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getlineitemtext), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getnetprice), [getPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getprice), [getPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#getpricevalue), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxbasis), [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxclassid), [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxrate), [getTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#gettaxes), [setBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setbasepricemoney), [setGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setgrosspricemoney), [setLineItemText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setlineitemtextstring), [setNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setnetpricemoney), [setPriceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#setpricevaluenumber), [setTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxmoney), [setTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxclassidstring), [setTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxratenumber), [setTaxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#settaxescollection), [updatePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatepricemoney), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber), [updateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxnumber-money), [updateTaxAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md#updatetaxamountmoney)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### STANDARD_SHIPPING_ID

- STANDARD_SHIPPING_ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "STANDARD_SHIPPING"
  - : Constant used to get the standard shipping line item.


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of this ShippingLineItem.


---

### adjustedGrossPrice
- adjustedGrossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the price of this shipping line item including tax after
      shipping adjustments have been applied.



---

### adjustedNetPrice
- adjustedNetPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the price of this shipping line item, excluding tax after
      shipping adjustments have been applied.



---

### adjustedPrice
- adjustedPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the adjusted price of this shipping line item. If the line item
      container is based on net pricing, the adjusted net price is returned. If
      the line item container is based on gross pricing, the adjusted gross
      price is returned.



---

### adjustedTax
- adjustedTax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Returns the tax of this shipping line item after shipping adjustments
      have been applied.



---

### orderItem
- orderItem: [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) `(read-only)`
  - : Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or `null`.
      An order-item extension will only exist for a ShippingLineItem which
      belongs to an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.



---

### shippingPriceAdjustments
- shippingPriceAdjustments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the collection of shipping price adjustments that have been
      applied to this shipping line item.



---

## Method Details

### createShippingPriceAdjustment(String)
- createShippingPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Creates a shipping price adjustment to be applied to the shipping line item.
      
      The promotion ID is mandatory and must not be the ID of any actual promotion defined in B2C Commerce.
      
      If there already exists a shipping price adjustment on this shipping line item referring to the specified
      promotion ID, an exception is thrown.


    **Parameters:**
    - promotionID - Promotion ID

    **Returns:**
    - The new price adjustment line item.


---

### createShippingPriceAdjustment(String, Discount)
- createShippingPriceAdjustment(promotionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), discount: [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)): [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)
  - : Creates a shipping price adjustment to be applied to the shipping line item.
      
      The promotion ID is mandatory and must not be the ID of any actual promotion defined in B2C Commerce. If a
      shipping price adjustment on this shipping line item referring to the specified promotion ID already exists, an
      exception is thrown. 
      
      The possible values for discount are [PercentageDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageDiscount.md), [AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md),
      [FixedPriceShippingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceShippingDiscount.md). 
      
      Examples:
      
      
      `
       var myShippingItem : dw.order.ShippingLineItem; // assume known
      
       var paFixedShippingPrice12 : dw.order.PriceAdjustment = myShippingItem.createPriceAdjustment("myPromotionID1", new FixedPriceShippingDiscount(12));
      
       var paTenPercent : dw.order.PriceAdjustment = myShippingItem.createPriceAdjustment("myPromotionID2", new PercentageDiscount(10));
      
       var paReduceBy2 : dw.order.PriceAdjustment = myShippingItem.createPriceAdjustment("myPromotionID3", new AmountDiscount(2));
      
       `


    **Parameters:**
    - promotionID - Promotion ID
    - discount - The desired discount, not null

    **Returns:**
    - The new price adjustment line item.


---

### getAdjustedGrossPrice()
- getAdjustedGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price of this shipping line item including tax after
      shipping adjustments have been applied.


    **Returns:**
    - the price of this shipping line item, including tax
              after shipping adjustments have been applied.



---

### getAdjustedNetPrice()
- getAdjustedNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the price of this shipping line item, excluding tax after
      shipping adjustments have been applied.


    **Returns:**
    - the price of this shipping line item, excluding tax after
              shipping adjustments have been applied.



---

### getAdjustedPrice()
- getAdjustedPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the adjusted price of this shipping line item. If the line item
      container is based on net pricing, the adjusted net price is returned. If
      the line item container is based on gross pricing, the adjusted gross
      price is returned.


    **Returns:**
    - either the adjusted net or gross price of this shipping line
              item.



---

### getAdjustedTax()
- getAdjustedTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the tax of this shipping line item after shipping adjustments
      have been applied.


    **Returns:**
    - the tax of this shipping line item after shipping adjustments
              have been applied.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of this ShippingLineItem.

    **Returns:**
    - ID of this ShippingLineItem


---

### getOrderItem()
- getOrderItem(): [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)
  - : Returns the [order-item extension](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) for this item, or `null`.
      An order-item extension will only exist for a ShippingLineItem which
      belongs to an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).
      
      
      Order post-processing APIs (gillian) are now inactive by default and will throw
      an exception if accessed. Activation needs preliminary approval by Product Management.
      Please contact support in this case. Existing customers using these APIs are not
      affected by this change and can use the APIs until further notice.


    **Returns:**
    - null or the order-item


---

### getShippingPriceAdjustments()
- getShippingPriceAdjustments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the collection of shipping price adjustments that have been
      applied to this shipping line item.


    **Returns:**
    - the collection of shipping price adjustments that have been
              applied to this shipping line item.



---

### removeShippingPriceAdjustment(PriceAdjustment)
- removeShippingPriceAdjustment(priceAdjustment: [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)): void
  - : Removes the specified shipping price adjustment from this shipping line
      item.


    **Parameters:**
    - priceAdjustment - The price adjustment line item to remove


---

<!-- prettier-ignore-end -->

<!-- document id=42701d4a530ff3cf12bb236bc3b5146f31147653ce4b6cad3a536e3912d074ac url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShippingLocation.md -->

<!-- prettier-ignore-start -->
# Class ShippingLocation

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.ShippingLocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md)

Represents a specific location for a shipment.


**Note:** this class allows access to sensitive personal and private information.
Pay attention to appropriate legal and regulatory requirements related to this data.



## Property Summary

| Property | Description |
| --- | --- |
| [address1](#address1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's first address. |
| [address2](#address2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's second address. |
| [city](#city): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's city. |
| [countryCode](#countrycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's country code. |
| [postBox](#postbox): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's post box. |
| [postalCode](#postalcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's postal code. |
| [stateCode](#statecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's state code. |
| [suite](#suite): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the shipping location's suite. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ShippingLocation](#shippinglocation)() | Constructs a new shipping location. |
| [ShippingLocation](#shippinglocationcustomeraddress)([CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)) | Constructs a new shipping location and initializes it with the values of the  specified address object. |
| [ShippingLocation](#shippinglocationorderaddress)([OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)) | Constructs a new shipping location and initializes it with the values of the  specified address object. |

## Method Summary

| Method | Description |
| --- | --- |
| [getAddress1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getaddress1)() | Returns the shipping location's first address. |
| [getAddress2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getaddress2)() | Returns the shipping location's second address. |
| [getCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getcity)() | Returns the shipping location's city. |
| [getCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getcountrycode)() | Returns the shipping location's country code. |
| [getPostBox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getpostbox)() | Returns the shipping location's post box. |
| [getPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getpostalcode)() | Returns the shipping location's postal code. |
| [getStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getstatecode)() | Returns the shipping location's state code. |
| [getSuite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#getsuite)() | Returns the shipping location's suite. |
| [setAddress1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setaddress1string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's first address. |
| [setAddress2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setaddress2string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's second address. |
| [setCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setcitystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's city. |
| [setCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setcountrycodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's country code. |
| [setPostBox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setpostboxstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's post box. |
| [setPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setpostalcodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's postal code. |
| [setStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setstatecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's state code. |
| [setSuite](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md#setsuitestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the shipping location's suite. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### address1
- address1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's first address.


---

### address2
- address2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's second address.


---

### city
- city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's city.


---

### countryCode
- countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's country code.


---

### postBox
- postBox: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's post box.


---

### postalCode
- postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's postal code.


---

### stateCode
- stateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's state code.


---

### suite
- suite: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's suite.


---

## Constructor Details

### ShippingLocation()
- ShippingLocation()
  - : Constructs a new shipping location.


---

### ShippingLocation(CustomerAddress)
- ShippingLocation(address: [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md))
  - : Constructs a new shipping location and initializes it with the values of the
      specified address object.


    **Parameters:**
    - address - the address that the shipping location represents.


---

### ShippingLocation(OrderAddress)
- ShippingLocation(address: [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md))
  - : Constructs a new shipping location and initializes it with the values of the
      specified address object.


    **Parameters:**
    - address - the address that the shipping location represents.


---

## Method Details

### getAddress1()
- getAddress1(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's first address.

    **Returns:**
    - the shipping location's first address.


---

### getAddress2()
- getAddress2(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's second address.

    **Returns:**
    - the shipping location's second address.


---

### getCity()
- getCity(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's city.

    **Returns:**
    - the shipping location's city.


---

### getCountryCode()
- getCountryCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's country code.

    **Returns:**
    - the shipping location's country code.


---

### getPostBox()
- getPostBox(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's post box.

    **Returns:**
    - the shipping location's post box.


---

### getPostalCode()
- getPostalCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's postal code.

    **Returns:**
    - the shipping location's postal code.


---

### getStateCode()
- getStateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's state code.

    **Returns:**
    - the shipping location's state code.


---

### getSuite()
- getSuite(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the shipping location's suite.

    **Returns:**
    - the shipping location's suite.


---

### setAddress1(String)
- setAddress1(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's first address.

    **Parameters:**
    - aValue - the shipping location's first address.


---

### setAddress2(String)
- setAddress2(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's second address.

    **Parameters:**
    - aValue - the shipping location's second address.


---

### setCity(String)
- setCity(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's city.

    **Parameters:**
    - aValue - the shipping location's city.


---

### setCountryCode(String)
- setCountryCode(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's country code.

    **Parameters:**
    - aValue - the shipping location's country code.


---

### setPostBox(String)
- setPostBox(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's post box.

    **Parameters:**
    - aValue - the shipping location's post box.


---

### setPostalCode(String)
- setPostalCode(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's postal code.

    **Parameters:**
    - aValue - the shipping location's postal code.


---

### setStateCode(String)
- setStateCode(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's state code.

    **Parameters:**
    - aValue - the shipping location's state code.


---

### setSuite(String)
- setSuite(aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the shipping location's suite.

    **Parameters:**
    - aValue - the shipping location's suite.


---

<!-- prettier-ignore-end -->

<!-- document id=9ce1c8bc045b477e0ac5fc84ffa29596d82c3648b5f54c80ea9fb4b8f7c90d29 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShippingMethod.md -->

<!-- prettier-ignore-start -->
# Class ShippingMethod

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.order.ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)

ShippingMethod represents how the shipment will be shipped.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the shipping method. |
| [baseMethod](#basemethod): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md) `(read-only)` | Returns the base shipping method or null if undefined. |
| [currencyCode](#currencycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the currency code associated with the shipping method |
| [customerGroups](#customergroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the customer groups assigned to the shipping method. |
| [defaultMethod](#defaultmethod): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the shipping method is marked as 'default' for the current session's currency. |
| [dependentMethods](#dependentmethods): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the dependent shipping methods of this shipping method,  regardless of the online status of the methods. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of the shipping method as specified in the current locale or  null if it could not be found. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of the shipping method in the current locale or  null if it could not be found. |
| [online](#online): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if shipping method is online, false otherwise |
| [taxClassID](#taxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the tax class id of the shipping method. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getBaseMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getbasemethod)() | Returns the base shipping method or null if undefined. |
| [getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getcurrencycode)() | Returns the currency code associated with the shipping method |
| [getCustomerGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getcustomergroups)() | Returns the customer groups assigned to the shipping method. |
| [getDependentMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getdependentmethods)() | Returns the dependent shipping methods of this shipping method,  regardless of the online status of the methods. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getdescription)() | Returns the description of the shipping method as specified in the current locale or  null if it could not be found. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getdisplayname)() | Returns the display name of the shipping method in the current locale or  null if it could not be found. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getid)() | Returns the ID of the shipping method. |
| [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#gettaxclassid)() | Returns the tax class id of the shipping method. |
| [isDefaultMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#isdefaultmethod)() | Returns 'true' if the shipping method is marked as 'default' for the current session's currency. |
| [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#isonline)() | Returns true if shipping method is online, false otherwise |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the shipping method.


---

### baseMethod
- baseMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md) `(read-only)`
  - : Returns the base shipping method or null if undefined.


---

### currencyCode
- currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the currency code associated with the shipping method


---

### customerGroups
- customerGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the customer groups assigned to the shipping method.
      Assigned ids that do not belong to an existing customer group are ignored.



---

### defaultMethod
- defaultMethod: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the shipping method is marked as 'default' for the current session's currency.
      Otherwise 'false' is returned.



---

### dependentMethods
- dependentMethods: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the dependent shipping methods of this shipping method,
      regardless of the online status of the methods. 
      
      Dependent shipping methods have this method as their base method.



---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of the shipping method as specified in the current locale or
      null if it could not be found.



---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of the shipping method in the current locale or
      null if it could not be found.



---

### online
- online: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if shipping method is online, false otherwise


---

### taxClassID
- taxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the tax class id of the shipping method.


---

## Method Details

### getBaseMethod()
- getBaseMethod(): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)
  - : Returns the base shipping method or null if undefined.

    **Returns:**
    - Base shipping method


---

### getCurrencyCode()
- getCurrencyCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the currency code associated with the shipping method

    **Returns:**
    - currency code


---

### getCustomerGroups()
- getCustomerGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the customer groups assigned to the shipping method.
      Assigned ids that do not belong to an existing customer group are ignored.


    **Returns:**
    - customer groups


---

### getDependentMethods()
- getDependentMethods(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the dependent shipping methods of this shipping method,
      regardless of the online status of the methods. 
      
      Dependent shipping methods have this method as their base method.


    **Returns:**
    - Dependent shipping methods


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the shipping method as specified in the current locale or
      null if it could not be found.


    **Returns:**
    - he description of the shipping method as specified in the current locale or
      null if it could not be found.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of the shipping method in the current locale or
      null if it could not be found.


    **Returns:**
    - the display name of the shipping method or null if it could not be found.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the shipping method.

    **Returns:**
    - the ID of the shipping method.


---

### getTaxClassID()
- getTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tax class id of the shipping method.

    **Returns:**
    - the tax class id of the shipping method.


---

### isDefaultMethod()
- isDefaultMethod(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the shipping method is marked as 'default' for the current session's currency.
      Otherwise 'false' is returned.


    **Returns:**
    - 'true' if it is the default shipping method of the site


---

### isOnline()
- isOnline(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if shipping method is online, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=30320deb6b021d44efbe9716f99b75b9cc0ce83293ac383ec29cdd1358dab8f6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShippingMgr.md -->

<!-- prettier-ignore-start -->
# Class ShippingMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.ShippingMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md)

Provides methods to access the shipping information.


## Property Summary

| Property | Description |
| --- | --- |
| [allShippingMethods](#allshippingmethods): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns the active shipping methods of the current site applicable to the session currency and current customer group. |
| [defaultShippingMethod](#defaultshippingmethod): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md) `(read-only)` | Returns the default shipping method of the current site applicable to the session currency. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [applyShipping](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#applyshippingbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Applies shipping to the given [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) using the platform's shipping hook dispatch logic. |
| static [applyShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#applyshippingcostlineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | Applies product and shipment-level shipping cost to the specified line  item container. |
| static [getAllShippingMethods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#getallshippingmethods)() | Returns the active shipping methods of the current site applicable to the session currency and current customer group. |
| static [getDefaultShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#getdefaultshippingmethod)() | Returns the default shipping method of the current site applicable to the session currency. |
| static [getProductShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#getproductshippingmodelproduct)([Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)) | Returns the shipping model for the specified product. |
| static [getShipmentShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#getshipmentshippingmodelshipment)([Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)) | Returns the shipping model for the specified shipment. |
| static [getShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md#getshippingcostshippingmethod-money)([ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Returns the shipping cost amount for the specified shipping method and  the specified order value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### allShippingMethods
- allShippingMethods: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns the active shipping methods of the current site applicable to the session currency and current customer group.


---

### defaultShippingMethod
- defaultShippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md) `(read-only)`
  - : Returns the default shipping method of the current site applicable to the session currency.
      
      Does an additional check if there is a base method and if their currencies are
      the same. Returns NULL if the two currencies are different.



---

## Method Details

### applyShipping(Basket)
- static applyShipping(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): void
  - : Applies shipping to the given [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) using the platform's shipping hook dispatch logic.
      
      
      This method is intended for use in custom `dw.order.calculate` hook implementations (e.g., in SFRA or
      SiteGenesis) that override the default basket calculation. Calling this method instead of directly invoking
      `dw.order.calculateShipping` ensures that Commerce App shipping providers registered via
      `sfcc.app.shipping.calculate` are invoked when available, with automatic fallback to the legacy
      `dw.order.calculateShipping` hook or the platform default shipping calculation.
      
      
      
      
      **WARNING:** Do NOT call this method from within a `dw.order.calculateShipping` hook
      implementation, as this will cause infinite recursion. This method is designed to be called from
      `dw.order.calculate` hooks only.
      
      
      
      
      The dispatch precedence is:
      
      1. `sfcc.app.shipping.calculate`— if a Commerce App shipping provider is installed.
      2. `dw.order.calculateShipping`— if registered by the storefront.
      3. Platform default shipping calculation — using product and shipment shipping cost tables.
      
      
      
      
      
      **Typical usage in a custom `dw.order.calculate` hook:**
      
      
      
      
      ```
      var ShippingMgr = require('dw/order/ShippingMgr');
      
      exports.calculate = function (basket) {
          // ... product prices, promotions ...
          ShippingMgr.applyShipping(basket);
          // ... tax ...
          basket.updateTotals();
      };
      ```


    **Parameters:**
    - basket - the basket for which shipping should be calculated.

    **Throws:**
    - NullArgumentException - if `basket` is `null`.


---

### applyShippingCost(LineItemCtnr)
- static applyShippingCost(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): void
  - : Applies product and shipment-level shipping cost to the specified line
      item container.
      
      
      
      For each product line item in the specified line item container, a
      product shipping line item is created if product-level shipping cost is
      defined for the product. If no product-level shipping cost is defined for
      the product, an existing product shipping line item is removed. 
      
      
      For each shipment in the specified line item container, shipment-level
      shipping cost is calculated. This cost is determined based on the
      merchandise total of the shipment after all product and order discounts.
      Only products without or with surcharge product-specific shipping cost
      count towards this merchandise total. Products with fixed
      product-specific shipping cost don't count towards the merchandise total
      used to calculate shipment-level shipping cost. The calculated shipping
      cost is set at the standard shipping line item of the shipment. 
      
      
      If 'net' taxation is configured for the site, the merchandise total
      before tax is used. If 'gross' taxation is configured for the site, the
      merchandise total after tax is used.
      
      If no shipping method is set for a shipment, neither product nor
      shipment-level shipping cost can be calculated. In this case, the amount
      of the standard shipment shipping line item will be set to N/A, and
      shipping line items of product line items in this shipment will be
      removed from the line item container.
      
      Special cases for product-level shipping cost: 
      
      
      - if a product is member of multiple shipping cost groups, the lowest  shipping cost takes precedence
      - if fixed and surcharge shipping cost is defined for a product, the  fixed cost takes precedence
      - shipping cost defined for a master product is also defined for all  variants of this master
      - shipping cost is not applied to bundled product line items or options  line items


    **Parameters:**
    - lineItemCtnr - the line item container to use.


---

### getAllShippingMethods()
- static getAllShippingMethods(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns the active shipping methods of the current site applicable to the session currency and current customer group.

    **Returns:**
    - the active shipping methods of the current site applicable to the session currency and current customer group.


---

### getDefaultShippingMethod()
- static getDefaultShippingMethod(): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)
  - : Returns the default shipping method of the current site applicable to the session currency.
      
      Does an additional check if there is a base method and if their currencies are
      the same. Returns NULL if the two currencies are different.


    **Returns:**
    - the default shipping method of the current site applicable to the session currency or null.


---

### getProductShippingModel(Product)
- static getProductShippingModel(product: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)): [ProductShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md)
  - : Returns the shipping model for the specified product.

    **Parameters:**
    - product - Product

    **Returns:**
    - Shipping model for specified product


---

### getShipmentShippingModel(Shipment)
- static getShipmentShippingModel(shipment: [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)): [ShipmentShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md)
  - : Returns the shipping model for the specified shipment.

    **Parameters:**
    - shipment - the shipment to use.

    **Returns:**
    - Shipping model for specified product


---

### getShippingCost(ShippingMethod, Money)
- static getShippingCost(shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md), orderValue: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Returns the shipping cost amount for the specified shipping method and
      the specified order value. 
      
      If shipping cost cannot be calculated for any reason, Money.NA is
      returned.


    **Parameters:**
    - shippingMethod - Selected shipping method
    - orderValue - Order value

    **Returns:**
    - Shipping cost


---

<!-- prettier-ignore-end -->

<!-- document id=127bf15818991be177ae6b2843475ef5aaa1ce1d2acc03b7c0737418cc3bfe7a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShippingOrder.md -->

<!-- prettier-ignore-start -->
# Class ShippingOrder

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md)
      - [dw.order.ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)

A shipping order is used to specify items that should be shipped, and is
typically exported to, and updated by a back-office warehouse management
system.


An [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) can have n shipping orders expressing how the order
is to be shipped. The creation, export and update of shipping orders is
largely handled by custom logic in scripts by implementing
[ShippingOrderHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md). Use method
[Order.createShippingOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#createshippingorder) for creation and add items using
[createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity) - each item is related
to an order item which in turn represents a product- or shipping- line item
in the order.


A shipping order has a status calculated from its item status, one of

- CONFIRMED - shipping order not yet exported, with 0 items, or all items  in status CONFIRMED.
- WAREHOUSE - shipping order exported, with all items in status WAREHOUSE.
- SHIPPED - exported shipping order has been updated, with 1-n items in  status SHIPPED and 0-n CANCELLED.
- CANCELLED - exported shipping order has been updated, with all items in  status CANCELLED.



The following status transitions are supported. Every status transition is
documented by the addition of an order note such as 'Shipping order 123456
status changed to WAREHOUSE.':
| From | To | When | Use |
| --- |--- |--- |--- |
| CONFIRMED | WAREHOUSE | Shipping order exported | Call [setStatusWarehouse()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#setstatuswarehouse) - note this is the only way to set the  items to status WAREHOUSE |
| WAREHOUSE | SHIPPED | One or more items have been SHIPPED | Call [ShippingOrderItem.setStatus(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#setstatusstring) using  [ShippingOrderItem.STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_shipped) |
| WAREHOUSE | CANCELLED | All items have been CANCELLED | Call [ShippingOrderItem.setStatus(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#setstatusstring) using  [ShippingOrderItem.STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_cancelled) |



Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [ORDERBY_ITEMID](#orderby_itemid): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by item id. |
| [ORDERBY_ITEMPOSITION](#orderby_itemposition): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Sorting by the position of the related oder item. |
| [ORDERBY_UNSORTED](#orderby_unsorted): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Unsorted , as it is. |
| [QUALIFIER_PRODUCTITEMS](#qualifier_productitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects the product items. |
| [QUALIFIER_SERVICEITEMS](#qualifier_serviceitems): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Selects for the service items. |
| [STATUS_CANCELLED](#status_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED" | Constant for Shipping Order Status CANCELLED |
| [STATUS_CONFIRMED](#status_confirmed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED" | Constant for Shipping Order Status CONFIRMED |
| [STATUS_SHIPPED](#status_shipped): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED" | Constant for Shipping Order Status SHIPPED |
| [STATUS_WAREHOUSE](#status_warehouse): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WAREHOUSE" | Constant for Shipping Order Status WAREHOUSE |

## Property Summary

| Property | Description |
| --- | --- |
| [invoice](#invoice): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)` | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [invoiceNumber](#invoicenumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns `null` or the invoice-number. |
| [items](#items): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | A filtering collection of the shipping order items belonging to the  shipping order. |
| [shipDate](#shipdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Gets the shipping date. |
| [shippingAddress](#shippingaddress): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md) | Returns the shipping address (optional, can be null). |
| [shippingMethod](#shippingmethod): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md) `(read-only)` | Returns the shipping method of the shipping order. |
| [shippingOrderNumber](#shippingordernumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the shipping order number. |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | Gets the status of this shipping order. |
| [trackingInfos](#trackinginfos): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Gets all tracking informations for this shipping order. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addTrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#addtrackinginfostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a tracking info to this shipping order with the given ID. |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoice)() | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this  ShippingOrder. |
| [createInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoicestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this ShippingOrder. |
| [createShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity)([OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md), [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Create a [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) in the shipping order with  the number `shippingOrderNumber`. |
| [createShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity-boolean)([OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md), [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Create a [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) in the shipping order with  the number `shippingOrderNumber`. |
| [getInvoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getinvoice)() | Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md). |
| [getInvoiceNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getinvoicenumber)() | Returns `null` or the invoice-number. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems)() | A filtering collection of the shipping order items belonging to the  shipping order. |
| [getShipDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getshipdate)() | Gets the shipping date. |
| [getShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getshippingaddress)() | Returns the shipping address (optional, can be null). |
| [getShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getshippingmethod)() | Returns the shipping method of the shipping order. |
| [getShippingOrderNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getshippingordernumber)() | Gets the shipping order number. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getstatus)() | Gets the status of this shipping order. |
| [getTrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#gettrackinginfostring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Gets a tracking info for this shipping order. |
| [getTrackingInfos](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#gettrackinginfos)() | Gets all tracking informations for this shipping order. |
| [setShipDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#setshipdatedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the shipping date. |
| [setShippingAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#setshippingaddressorderaddress)([OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)) | Set a shipping address for the shipping order. |
| [setShippingMethodID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#setshippingmethodidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the id of shipping method. |
| [setStatusWarehouse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#setstatuswarehouse)() | Set a CONFIRMED shipping order (all items in status CONFIRMED) to status  WAREHOUSE (all items in status WAREHOUSE).<br/>  Note - this method is the only way to transition a shipping order from  CONFIRMED to WAREHOUSE. |

### Methods inherited from class AbstractItemCtnr

[getCreatedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreatedby), [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getcreationdate), [getGrandTotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getgrandtotal), [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getlastmodified), [getModifiedBy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getmodifiedby), [getOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder), [getProductSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getproductsubtotal), [getServiceSubtotal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getservicesubtotal)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ORDERBY_ITEMID

- ORDERBY_ITEMID: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by item id. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems) as an argument to
      method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### ORDERBY_ITEMPOSITION

- ORDERBY_ITEMPOSITION: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Sorting by the position of the related oder item. Use with method
      [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems) as an argument to method
      [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### ORDERBY_UNSORTED

- ORDERBY_UNSORTED: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Unsorted , as it is. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems) as an argument
      to method [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject).



---

### QUALIFIER_PRODUCTITEMS

- QUALIFIER_PRODUCTITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects the product items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems) as an
      argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).



---

### QUALIFIER_SERVICEITEMS

- QUALIFIER_SERVICEITEMS: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Selects for the service items. Use with method [getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems) as an
      argument to method [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject).



---

### STATUS_CANCELLED

- STATUS_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED"
  - : Constant for Shipping Order Status CANCELLED


---

### STATUS_CONFIRMED

- STATUS_CONFIRMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED"
  - : Constant for Shipping Order Status CONFIRMED


---

### STATUS_SHIPPED

- STATUS_SHIPPED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED"
  - : Constant for Shipping Order Status SHIPPED


---

### STATUS_WAREHOUSE

- STATUS_WAREHOUSE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WAREHOUSE"
  - : Constant for Shipping Order Status WAREHOUSE


---

## Property Details

### invoice
- invoice: [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) `(read-only)`
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoicestring)


---

### invoiceNumber
- invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns `null` or the invoice-number.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoicestring)


---

### items
- items: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : A filtering collection of the shipping order items belonging to the
      shipping order.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) could be sorted / filtered
      using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with  [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with      [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with        [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with          [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#qualifier_serviceitems)


    **See Also:**
    - [createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity)
    - [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)


---

### shipDate
- shipDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Gets the shipping date.
      
      
      Returns `null` if this shipping order is not yet shipped.



---

### shippingAddress
- shippingAddress: [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)
  - : Returns the shipping address (optional, can be null).
      
      
      
      Note: the shipping address is not copied into the
      ShippingOrder but is a link to a
      [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md) held in the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).



---

### shippingMethod
- shippingMethod: [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md) `(read-only)`
  - : Returns the shipping method of the shipping order.
      
      
      Can be `null`.



---

### shippingOrderNumber
- shippingOrderNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the shipping order number.


---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : Gets the status of this shipping order. The status is read-only and
      calculated from the item status. See class documentation for more
      details.
      
      The possible values are [STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_confirmed),
      [STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_warehouse), [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_shipped),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_cancelled).



---

### trackingInfos
- trackingInfos: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Gets all tracking informations for this shipping order.

    **See Also:**
    - [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)


---

## Method Details

### addTrackingInfo(String)
- addTrackingInfo(trackingInfoID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)
  - : Adds a tracking info to this shipping order with the given ID.

    **Parameters:**
    - trackingInfoID - the tracking info id

    **Returns:**
    - the new tracking info

    **See Also:**
    - [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)


---

### createInvoice()
- createInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this
      ShippingOrder.
      
      
      The shipping-order-number will be used as the
      invoice-number. The Invoice can then be accessed using
      [getInvoice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getinvoice) or [getInvoiceNumber()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getinvoicenumber) can be used.
      The method must not be called more than once for a ShippingOrder,
      nor may 2 Invoices exist with the same invoice-number.
      
      
      The new Invoice is a debit-invoice with a status
      [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), and will be passed to the
      capture payment-hook in a separate database transaction for processing.


    **Returns:**
    - new invoice


---

### createInvoice(String)
- createInvoice(invoiceNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Creates a new [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md) based on this ShippingOrder.
      
      
      The invoice-number must be specified as an argument.The Invoice can then be accessed using
      [getInvoice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getinvoice) or [getInvoiceNumber()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getinvoicenumber) can be used.
      The method must not be called more than once for a ShippingOrder,
      nor may 2 Invoices exist with the same invoice-number.
      
      
      The new Invoice is a debit-invoice with a status [Invoice.STATUS_NOT_PAID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md#status_not_paid), and
      will be passed to the capture payment-hook in a separate database
      transaction for processing.


    **Parameters:**
    - invoiceNumber - the invoice-number to use

    **Returns:**
    - new invoice


---

### createShippingOrderItem(OrderItem, Quantity)
- createShippingOrderItem(orderItem: [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md), quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Create a [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) in the shipping order with
      the number `shippingOrderNumber`.
      
      
      The quantity of the new item can be optionally specified. A quantity of
      `null` indicates the new item should be based on the entire order item and
      is recommended for [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)s. If a quantity is
      specified for a [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) which is less than
      [ProductLineItem.getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getquantity) the
      ProductLineItem will be split, creating a new
      ProductLineItem. The new
      ShippingOrderItem will be associated with the new
      ProductLineItem, which will receive the specified
      quantity.
      See also [createShippingOrderItem(OrderItem, Quantity, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity-boolean).


    **Parameters:**
    - quantity - the quantity for which the shipping order item will be created
    - orderItem - the order item for which the shipping order item is to be created

    **Returns:**
    - the created shipping order item


---

### createShippingOrderItem(OrderItem, Quantity, Boolean)
- createShippingOrderItem(orderItem: [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md), quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md), splitIfPartial: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Create a [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) in the shipping order with
      the number `shippingOrderNumber`.
      
      
      The quantity of the new item can be optionally specified. A quantity of
      `null` indicates the new item should be based on the entire order item and
      is recommended for [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)s.
      If the specified quantity is less than [ProductLineItem.getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getquantity) the
      ProductLineItem will be split or not depending on `splitIfPartial` parameter.
      When `split` is `true`, the method is equivalent to
      [createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity).


    **Parameters:**
    - quantity - the quantity for which the shipping order item will be created, not null
    - orderItem - the order item for which the shipping order item is to be created
    - splitIfPartial - the flag whether ProductLineItem should be split when requested             quantity is less than ProductLineItem's quantity

    **Returns:**
    - the created shipping order item


---

### getInvoice()
- getInvoice(): [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)
  - : Returns null or the previously created [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).

    **Returns:**
    - null or the previously created invoice.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoicestring)


---

### getInvoiceNumber()
- getInvoiceNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns `null` or the invoice-number.

    **Returns:**
    - `null` or the previously created invoice number.

    **See Also:**
    - [createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoicestring)


---

### getItems()
- getItems(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : A filtering collection of the shipping order items belonging to the
      shipping order.
      
      
      This [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) could be sorted / filtered
      using:
      
      - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with  [ORDERBY_ITEMID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_itemid)  - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with    [ORDERBY_ITEMPOSITION](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_itemposition)    - [FilteringCollection.sort(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#sortobject)with      [ORDERBY_UNSORTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#orderby_unsorted)      - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with        [QUALIFIER_PRODUCTITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#qualifier_productitems)        - [FilteringCollection.select(Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md#selectobject)with          [QUALIFIER_SERVICEITEMS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#qualifier_serviceitems)


    **Returns:**
    - the filtering collection of the shipping items.

    **See Also:**
    - [createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity)
    - [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)


---

### getShipDate()
- getShipDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Gets the shipping date.
      
      
      Returns `null` if this shipping order is not yet shipped.


    **Returns:**
    - the shipping date or `null`


---

### getShippingAddress()
- getShippingAddress(): [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)
  - : Returns the shipping address (optional, can be null).
      
      
      
      Note: the shipping address is not copied into the
      ShippingOrder but is a link to a
      [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md) held in the [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).


    **Returns:**
    - the shipping address or `null`


---

### getShippingMethod()
- getShippingMethod(): [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)
  - : Returns the shipping method of the shipping order.
      
      
      Can be `null`.


    **Returns:**
    - the shipping method or `null`


---

### getShippingOrderNumber()
- getShippingOrderNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the shipping order number.

    **Returns:**
    - the shipping order number


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the status of this shipping order. The status is read-only and
      calculated from the item status. See class documentation for more
      details.
      
      The possible values are [STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_confirmed),
      [STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_warehouse), [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_shipped),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#status_cancelled).


    **Returns:**
    - the status


---

### getTrackingInfo(String)
- getTrackingInfo(trackingInfoID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)
  - : Gets a tracking info for this shipping order.

    **Parameters:**
    - trackingInfoID - the tracking info id

    **Returns:**
    - the tracking info or `null`

    **See Also:**
    - [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)


---

### getTrackingInfos()
- getTrackingInfos(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Gets all tracking informations for this shipping order.

    **Returns:**
    - all tracking informations for this shipping order

    **See Also:**
    - [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)


---

### setShipDate(Date)
- setShipDate(date: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the shipping date.

    **Parameters:**
    - date - the ship date


---

### setShippingAddress(OrderAddress)
- setShippingAddress(address: [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)): void
  - : Set a shipping address for the shipping order.

    **Parameters:**
    - address - the shipping address

    **See Also:**
    - [getShippingAddress()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getshippingaddress)


---

### setShippingMethodID(String)
- setShippingMethodID(shippingMethodID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the id of shipping method.

    **Parameters:**
    - shippingMethodID - the id of the shipping method

    **See Also:**
    - [ShippingMethod.getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md#getid)


---

### setStatusWarehouse()
- setStatusWarehouse(): void
  - : Set a CONFIRMED shipping order (all items in status CONFIRMED) to status
      WAREHOUSE (all items in status WAREHOUSE).
      
      Note - this method is the only way to transition a shipping order from
      CONFIRMED to WAREHOUSE.


    **Throws:**
    - IllegalArgumentException - if the shipping order is in a status other than CONFIRMED.


---

<!-- prettier-ignore-end -->

<!-- document id=5a2ac101a027a7bc556d157d3752bda4a14e9e0b18cd330ed3c4f5701976ce95 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.ShippingOrderHooks.md -->

<!-- prettier-ignore-start -->
# Class ShippingOrderHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.ShippingOrderHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md)

This interface represents all script hooks that can be registered around
shipping order lifecycle. It contains the extension points (hook names), and
the functions that are called by each extension point. A function must be
defined inside a JavaScript source and must be exported. The script with the
exported hook function must be located inside a site cartridge. Inside the
site cartridge a 'package.json' file with a 'hooks' entry must exist.


"hooks": "./hooks.json"


The hooks entry links to a json file, relative to the 'package.json' file.
This file lists all registered hooks inside the hooks property:




```
"hooks": [
     {"name": "dw.order.shippingorder.updateShippingOrderItem", "script": "./shippingOrderUpdate.ds"},
]
```




A hook entry has a 'name' and a 'script' property.

- The 'name' contains the extension point, the hook name.
- The 'script' contains the script relative to the hooks file, with the  exported hook function.



Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointAfterStatusChange](#extensionpointafterstatuschange): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.afterStatusChange" | The extension point name dw.order.shippingorder.afterStatusChange. |
| [extensionPointChangeStatus](#extensionpointchangestatus): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.changeStatus" | The extension point name dw.order.shippingorder.changeStatus. |
| [extensionPointCreateShippingOrders](#extensionpointcreateshippingorders): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.createShippingOrders" | The extension point name dw.order.shippingorder.createShippingOrders. |
| [extensionPointNotifyStatusChange](#extensionpointnotifystatuschange): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.notifyStatusChange" | The extension point name dw.order.shippingorder.notifyStatusChange. |
| [extensionPointPrepareCreateShippingOrders](#extensionpointpreparecreateshippingorders): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.prepareCreateShippingOrders" | The extension point name  dw.order.shippingorder.prepareCreateShippingOrders. |
| [extensionPointResolveShippingOrder](#extensionpointresolveshippingorder): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.resolveShippingOrder" | The extension point name dw.order.shippingorder.resolveShippingOrder . |
| [extensionPointShippingOrderCancelled](#extensionpointshippingordercancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.setShippingOrderCancelled" | The extension point name dw.order.shippingorder.setShippingOrderCancelled. |
| [extensionPointShippingOrderShipped](#extensionpointshippingordershipped): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.setShippingOrderShipped" | The extension point name dw.order.shippingorder.setShippingOrderShipped. |
| [extensionPointShippingOrderWarehouse](#extensionpointshippingorderwarehouse): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.setShippingOrderWarehouse" | The extension point name dw.order.shippingorder.setShippingOrderWarehouse. |
| [extensionPointUpdateShippingOrderItem](#extensionpointupdateshippingorderitem): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.updateShippingOrderItem" | The extension point name dw.order.shippingorder.updateShippingOrderItem. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [afterStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#afterstatuschangeshippingorder)([ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)) | After Status change hook. |
| [changeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#changestatusshippingorder-shippingorderwo)([ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), ShippingOrderWO) | Change the status of a shipping order. |
| [createShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#createshippingordersorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Called during shipping order creation for an order. |
| [notifyStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#notifystatuschangeshippingorder)([ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)) | Notify Status change hook. |
| [prepareCreateShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#preparecreateshippingordersorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | Called before shipping order creation for an order takes place. |
| [resolveShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#resolveshippingordershippingorderwo)(ShippingOrderWO) | Resolve the shipping order. |
| [setShippingOrderCancelled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#setshippingordercancelledshippingorderwo)(ShippingOrderWO) | Change the status of a shipping order to cancelled. |
| [setShippingOrderShipped](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#setshippingordershippedshippingorderwo)(ShippingOrderWO) | Change the status of a shipping order to shipped. |
| [setShippingOrderWarehouse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#setshippingorderwarehouseshippingorderwo)(ShippingOrderWO) | Change the status of a shipping order to warehouse. |
| [updateShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#updateshippingorderitemshippingorder-shippingorderitemwo)([ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), ShippingOrderItemWO) | Updates the status of a shipping order item. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointAfterStatusChange

- extensionPointAfterStatusChange: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.afterStatusChange"
  - : The extension point name dw.order.shippingorder.afterStatusChange.


---

### extensionPointChangeStatus

- extensionPointChangeStatus: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.changeStatus"
  - : The extension point name dw.order.shippingorder.changeStatus.


---

### extensionPointCreateShippingOrders

- extensionPointCreateShippingOrders: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.createShippingOrders"
  - : The extension point name dw.order.shippingorder.createShippingOrders.


---

### extensionPointNotifyStatusChange

- extensionPointNotifyStatusChange: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.notifyStatusChange"
  - : The extension point name dw.order.shippingorder.notifyStatusChange.


---

### extensionPointPrepareCreateShippingOrders

- extensionPointPrepareCreateShippingOrders: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.prepareCreateShippingOrders"
  - : The extension point name
      dw.order.shippingorder.prepareCreateShippingOrders.



---

### extensionPointResolveShippingOrder

- extensionPointResolveShippingOrder: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.resolveShippingOrder"
  - : The extension point name dw.order.shippingorder.resolveShippingOrder .


---

### extensionPointShippingOrderCancelled

- extensionPointShippingOrderCancelled: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.setShippingOrderCancelled"
  - : The extension point name dw.order.shippingorder.setShippingOrderCancelled.


---

### extensionPointShippingOrderShipped

- extensionPointShippingOrderShipped: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.setShippingOrderShipped"
  - : The extension point name dw.order.shippingorder.setShippingOrderShipped.


---

### extensionPointShippingOrderWarehouse

- extensionPointShippingOrderWarehouse: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.setShippingOrderWarehouse"
  - : The extension point name dw.order.shippingorder.setShippingOrderWarehouse.


---

### extensionPointUpdateShippingOrderItem

- extensionPointUpdateShippingOrderItem: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "dw.order.shippingorder.updateShippingOrderItem"
  - : The extension point name dw.order.shippingorder.updateShippingOrderItem.


---

## Method Details

### afterStatusChange(ShippingOrder)
- afterStatusChange(shippingOrder: [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : After Status change hook.
      
      
      The function is called by extension point
      [extensionPointAfterStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointafterstatuschange).
      
      The implementation of this hook is optional. If defined the hook is
      called after [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointchangestatus) or respectively after
      [extensionPointShippingOrderShipped](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointshippingordershipped),
      [extensionPointShippingOrderCancelled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointshippingordercancelled) or
      [extensionPointShippingOrderWarehouse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointshippingorderwarehouse)
      
      Runs inside of a transaction.


    **Parameters:**
    - shippingOrder - the shipping order to be updated

    **Returns:**
    - the resulting status


---

### changeStatus(ShippingOrder, ShippingOrderWO)
- changeStatus(shippingOrder: [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), updateData: ShippingOrderWO): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Change the status of a shipping order.
      
      
      The function is called by extension point
      [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointchangestatus).
      
      Runs inside a transaction together with the hooks
      [extensionPointResolveShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointresolveshippingorder)
      [extensionPointUpdateShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointupdateshippingorderitem).
      
      
      Runs after the iteration over the input's items collection as the last
      step in this transaction. The implementation of this hook is mandatory.


    **Parameters:**
    - shippingOrder - the shipping order to be updated
    - updateData - the input data

    **Returns:**
    - the resulting status


---

### createShippingOrders(Order)
- createShippingOrders(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called during shipping order creation for an order.
      
      
      The function is called by extension point
      [extensionPointCreateShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointcreateshippingorders). It is responsible for
      creating shipping orders and its items for the order. Preparations for
      shipping order creation can be done before in hook
      [extensionPointPrepareCreateShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointpreparecreateshippingorders).
      
      Runs inside of a transaction. The implementation of this hook is
      mandatory.


    **Parameters:**
    - order - the order to create shipping orders for

    **Returns:**
    - the resulting status


---

### notifyStatusChange(ShippingOrder)
- notifyStatusChange(shippingOrder: [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Notify Status change hook.
      
      
      The function is called by extension point
      [extensionPointNotifyStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointnotifystatuschange).
      
      The implementation of this hook is optional. If defined the hook is
      called after [extensionPointAfterStatusChange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointafterstatuschange) as the last step
      in the shipping order update process.
      
      Runs outside of a transaction.


    **Parameters:**
    - shippingOrder - the shipping order to be updated

    **Returns:**
    - the resulting status


---

### prepareCreateShippingOrders(Order)
- prepareCreateShippingOrders(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Called before shipping order creation for an order takes place. Typically
      the hook is used to check the payment authorization status of the order.
      
      
      The function is called by extension point
      [extensionPointPrepareCreateShippingOrders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointpreparecreateshippingorders).
      
      Runs inside its own transaction. The value of the return status is used
      to control whether hook [createShippingOrders(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#createshippingordersorder) is called
      for the order or not. The implementation of this hook is mandatory.


    **Parameters:**
    - order - the order to create shipping orders for

    **Returns:**
    - 
      - Status.OK successful preparation - continue with shipping          order creation for this order.
      - Status.ERROR failed          preparation - skip shipping order creation for this order.



---

### resolveShippingOrder(ShippingOrderWO)
- resolveShippingOrder(updateData: ShippingOrderWO): [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)
  - : Resolve the shipping order. Will be called as first step of the update.
      
      
      The function is called by extension point
      [extensionPointResolveShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointresolveshippingorder).
      
      Runs inside a transaction together with the hooks
      
      [extensionPointUpdateShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointupdateshippingorderitem)
      [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointchangestatus). The implementation of this hook is
      mandatory.


    **Parameters:**
    - updateData - the input data

    **Returns:**
    - the shipping order to update


---

### setShippingOrderCancelled(ShippingOrderWO)
- setShippingOrderCancelled(updateData: ShippingOrderWO): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Change the status of a shipping order to cancelled.
      
      
      The function is called by extension point
      [extensionPointShippingOrderCancelled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointshippingordercancelled).
      
      This is an optional hook that can be implemented to have full control
      over status change to destination status Cancelled. The following hooks
      will be skipped if an implementation for this hook is registered:
      [extensionPointResolveShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointresolveshippingorder),
      [extensionPointUpdateShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointupdateshippingorderitem),
      [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointchangestatus).
      
      Runs inside of a transaction.


    **Parameters:**
    - updateData - the input data

    **Returns:**
    - the changed order or {code}null{code}


---

### setShippingOrderShipped(ShippingOrderWO)
- setShippingOrderShipped(updateData: ShippingOrderWO): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Change the status of a shipping order to shipped.
      
      
      The function is called by extension point
      [extensionPointShippingOrderShipped](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointshippingordershipped).
      
      This is an optional hook that can be implemented to have full control
      over status change to destination status Shipped. The following hooks
      will be skipped if an implementation for this hook is registered:
      [extensionPointResolveShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointresolveshippingorder)
      [extensionPointUpdateShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointupdateshippingorderitem),
      [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointchangestatus).
      
      Runs inside of a transaction.


    **Parameters:**
    - updateData - the input data

    **Returns:**
    - the changed order or {code}null{code}


---

### setShippingOrderWarehouse(ShippingOrderWO)
- setShippingOrderWarehouse(updateData: ShippingOrderWO): [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)
  - : Change the status of a shipping order to warehouse.
      
      
      The function is called by extension point
      [extensionPointShippingOrderWarehouse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointshippingorderwarehouse).
      
      This is an optional hook that can be implemented to have full control
      over status change to destination status Warehouse. The following hooks
      will be skipped if an implementation for this hook is registered:
      [extensionPointResolveShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointresolveshippingorder),
      [extensionPointUpdateShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointupdateshippingorderitem),
      [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointchangestatus).
      
      Runs inside of a transaction.


    **Parameters:**
    - updateData - the input data

    **Returns:**
    - the changed order or {code}null{code}


---

### updateShippingOrderItem(ShippingOrder, ShippingOrderItemWO)
- updateShippingOrderItem(shippingOrder: [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), updateItem: ShippingOrderItemWO): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : Updates the status of a shipping order item.
      
      
      The function is called by extension point
      [extensionPointUpdateShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointupdateshippingorderitem).
      
      Runs inside a transaction together with the hooks
      
      [extensionPointResolveShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointresolveshippingorder)
      [extensionPointChangeStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md#extensionpointchangestatus). The implementation of this hook is
      mandatory.


    **Parameters:**
    - shippingOrder - the shipping order
    - updateItem - the input data

    **Returns:**
    - the resulting status


---

<!-- prettier-ignore-end -->

<!-- document id=1dc33a42c4bc0a254acdc5d193af2589159aa28b01353384362154e389ecf044 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.ShippingOrderItem.md -->

<!-- prettier-ignore-start -->
# Class ShippingOrderItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md)
      - [dw.order.ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)

One or more ShippingOrderItems are contained in a
[ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), created using
[ShippingOrder.createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity)
and can be retrieved by
[ShippingOrder.getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems). A
ShippingOrderItem references a single
[OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) which in turn references a
[LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md) associated with an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).


Order post-processing APIs (gillian) are now inactive by default and will throw
an exception if accessed. Activation needs preliminary approval by Product Management.
Please contact support in this case. Existing customers using these APIs are not
affected by this change and can use the APIs until further notice.



## Constant Summary

| Constant | Description |
| --- | --- |
| [STATUS_CANCELLED](#status_cancelled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED" | Constant for Order Item Status CANCELLED |
| [STATUS_CONFIRMED](#status_confirmed): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED" | Constant for Order Item Status CONFIRMED |
| [STATUS_SHIPPED](#status_shipped): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED" | Constant for Order Item Status SHIPPED |
| [STATUS_WAREHOUSE](#status_warehouse): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WAREHOUSE" | Constant for Order Item Status WAREHOUSE |

## Property Summary

| Property | Description |
| --- | --- |
| [basePrice](#baseprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Price of a single unit before discount application. |
| [parentItem](#parentitem): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) | Returns null or the parent item. |
| [quantity](#quantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | The quantity of the shipping order item. |
| [shippingOrderNumber](#shippingordernumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The mandatory shipping order number of the related  [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md). |
| [status](#status): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) | Gets the order item status. |
| [trackingRefs](#trackingrefs): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)` | Gets the tracking refs (tracking infos) the shipping order item is  assigned to. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [addTrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#addtrackingrefstring-quantity)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | A shipping order item can be assigned  to one or many [tracking infos](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md) with  different quantities. |
| [applyPriceRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#applypriceratedecimal-decimal-boolean)([Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Apply a rate of (factor / divisor) to the prices in this item, with the option to half round up or half round down to the  nearest cent if necessary. |
| [getBasePrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getbaseprice)() | Price of a single unit before discount application. |
| [getParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getparentitem)() | Returns null or the parent item. |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getquantity)() | The quantity of the shipping order item. |
| [getShippingOrderNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getshippingordernumber)() | The mandatory shipping order number of the related  [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md). |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getstatus)() | Gets the order item status. |
| [getTrackingRefs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#gettrackingrefs)() | Gets the tracking refs (tracking infos) the shipping order item is  assigned to. |
| [setParentItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#setparentitemshippingorderitem)([ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)) | Set a parent item. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#setstatusstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the status. |
| [split](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#splitquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Split the shipping order item. |
| [split](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#splitquantity-boolean)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Split the shipping order item. |

### Methods inherited from class AbstractItem

[getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice), [getItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getitemid), [getLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getlineitem), [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice), [getOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitem), [getOrderItemID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getorderitemid), [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax), [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis), [getTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxitems)
### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### STATUS_CANCELLED

- STATUS_CANCELLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CANCELLED"
  - : Constant for Order Item Status CANCELLED


---

### STATUS_CONFIRMED

- STATUS_CONFIRMED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CONFIRMED"
  - : Constant for Order Item Status CONFIRMED


---

### STATUS_SHIPPED

- STATUS_SHIPPED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHIPPED"
  - : Constant for Order Item Status SHIPPED


---

### STATUS_WAREHOUSE

- STATUS_WAREHOUSE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "WAREHOUSE"
  - : Constant for Order Item Status WAREHOUSE


---

## Property Details

### basePrice
- basePrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Price of a single unit before discount application.


---

### parentItem
- parentItem: [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Returns null or the parent item.


---

### quantity
- quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : The quantity of the shipping order item.
      
      
      The [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) is equal to the related line item quantity.



---

### shippingOrderNumber
- shippingOrderNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The mandatory shipping order number of the related
      [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md).



---

### status
- status: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the order item status.
      
      
      The possible values are [STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_confirmed),
      [STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_warehouse), [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_shipped),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_cancelled).



---

### trackingRefs
- trackingRefs: [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) `(read-only)`
  - : Gets the tracking refs (tracking infos) the shipping order item is
      assigned to.


    **See Also:**
    - [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)


---

## Method Details

### addTrackingRef(String, Quantity)
- addTrackingRef(trackingInfoID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)
  - : A shipping order item can be assigned
      to one or many [tracking infos](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md) with
      different quantities. For example an item with quantity 3 may have been
      shipped in 2 packages, each represented by its own
      tracking info - 2
      [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)s would exist with quantities 1 and 2.
      
      
      This method creates and adds a new tracking
      reference to this shipping order item for a given
      tracking info and quantity. The new
      instance is returned.


    **Parameters:**
    - trackingInfoID - the id of the tracking info
    - quantity - the quantity the which is assigned to the tracking info for             this shipping order item. Optional (null is allowed).

    **Returns:**
    - the new tracking reference

    **See Also:**
    - [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)


---

### applyPriceRate(Decimal, Decimal, Boolean)
- applyPriceRate(factor: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), divisor: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md), roundUp: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Apply a rate of (factor / divisor) to the prices in this item, with the option to half round up or half round down to the
      nearest cent if necessary.
      
      _Examples_:
      
      | TaxBasis before | factor | divisor | roundup | Calculation | TaxBasis after |
      | --- |--- |--- |--- |--- |--- |
      | $10.00 | 1 | 2 | true | 10\*1/2= | $5.00 |
      | $10.00 | 9 | 10 | true | 10\*9/10= | $9.00 |
      | $10.00 | 1 | 3 | true | 10\*1/3=3.3333= | $3.33 |
      |  $2.47 | 1 | 2 | true | 2.47\*1/2=1.235= | $1.24 |
      |  $2.47 | 1 | 2 | false | 2.47\*1/2=1.235= | $1.23 |
      
      
      _Which prices are updated?_:
      
      The rate described above is applied to tax-basis and tax then the net-price and gross-price are recalculated by adding / subtracting
      depending on whether the order is based on net price.
      
      _Example (order based on net price)_
      
      New TaxBasis:$10.00, Tax:$1.00, NetPrice=TaxBasis=$10.00, GrossPrice=TaxBasis+Tax=$11.00
      
      _Example (order based on gross price)_
      
      New TaxBasis:$10.00, Tax:$1.00, NetPrice=TaxBasis-tax=$9.00, GrossPrice=TaxBasis=$10.00


    **Parameters:**
    - factor - factor used to calculate rate
    - divisor - divisor used to calculate rate
    - roundUp - whether to round up or down on 0.5

    **See Also:**
    - [AbstractItem.getTaxBasis()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettaxbasis)
    - [AbstractItem.getTax()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#gettax)
    - [AbstractItem.getNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getnetprice)
    - [AbstractItem.getGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md#getgrossprice)
    - [TaxMgr.getTaxationPolicy()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#gettaxationpolicy)


---

### getBasePrice()
- getBasePrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Price of a single unit before discount application.

    **Returns:**
    - Price of a single unit before discount application.


---

### getParentItem()
- getParentItem(): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Returns null or the parent item.

    **Returns:**
    - null or the parent item.


---

### getQuantity()
- getQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : The quantity of the shipping order item.
      
      
      The [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) is equal to the related line item quantity.


    **Returns:**
    - the quantity


---

### getShippingOrderNumber()
- getShippingOrderNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The mandatory shipping order number of the related
      [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md).


    **Returns:**
    - the shipping order number.


---

### getStatus()
- getStatus(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Gets the order item status.
      
      
      The possible values are [STATUS_CONFIRMED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_confirmed),
      [STATUS_WAREHOUSE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_warehouse), [STATUS_SHIPPED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_shipped),
      [STATUS_CANCELLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#status_cancelled).


    **Returns:**
    - the status


---

### getTrackingRefs()
- getTrackingRefs(): [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md)
  - : Gets the tracking refs (tracking infos) the shipping order item is
      assigned to.


    **Returns:**
    - the tracking refs ( tracking infos - [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)
              ) the shipping order item is assigned to.


    **See Also:**
    - [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)


---

### setParentItem(ShippingOrderItem)
- setParentItem(parentItem: [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)): void
  - : Set a parent item. The parent item must belong to the same
      [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md). An infinite parent-child loop is disallowed
      as is a parent-child depth greater than 10. Setting a parent item
      indicates a dependency of the child item on the parent item, and can be
      used to form a parallel structure to that accessed using
      [ProductLineItem.getParent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md#getparent).


    **Parameters:**
    - parentItem - The parent item, null is allowed


---

### setStatus(String)
- setStatus(status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the status. See [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) for details of
      shipping order status transitions. Do not use this method to set a
      shipping order to status WAREHOUSE, instead use
      [ShippingOrder.setStatusWarehouse()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#setstatuswarehouse)
      
      
      This also triggers the setting of the status of the
      [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md) when appropriate. Setting this status can also have an impact on
      the order status, accessed using [Order.getStatus()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md#getstatus) and the
      shipping order status, accessed using [ShippingOrder.getStatus()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getstatus).


    **Parameters:**
    - status - the status

    **Throws:**
    - NullPointerException - if status is `null`
    - IllegalArgumentException - if the status transition to the status is not allowed


---

### split(Quantity)
- split(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Split the shipping order item.
      
      
      This will also lead to a split of the related [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md).
      Split means that for the passed quantity a new item is created with this
      quantity as an exact copy of this item. The remaining amount will stay in
      this item.
      
      
      If quantity is equal to [getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getquantity) no split is done and this
      item is returned itself.
      
      
      This method is equivalent to [split(Quantity, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#splitquantity-boolean) called
      with `splitOrderItem` equals to `true`.


    **Parameters:**
    - quantity - the quantity for the newly created item

    **Returns:**
    - the newly created item or this item

    **Throws:**
    - IllegalArgumentException - if quantity is greater than [getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getquantity)


---

### split(Quantity, Boolean)
- split(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md), splitOrderItem: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Split the shipping order item.
      
      
      This will also lead to a split of the related [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)
      when `splitOrderItem` is `true`.
      Split means that for the passed quantity a new item is created with this
      quantity as an exact copy of this item. The remaining amount will stay in
      this item.
      
      
      If quantity is equal to [getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getquantity) no split is done and this
      item is returned itself.


    **Parameters:**
    - quantity - the quantity for the newly created item
    - splitOrderItem -              <li>`true` the related [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)             will be splitted too</li>             <li>`false` the related [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)             will not be splitted</li>             </ul>

    **Returns:**
    - the newly created item or this item

    **Throws:**
    - IllegalArgumentException - if quantity is greater than [getQuantity()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#getquantity)


---

<!-- prettier-ignore-end -->

<!-- document id=36a83671a5dbd7b51eb4d0b70cbb3b26f0638c921ed33d444f40e3b762a4c050 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.consent.ShopperConsentErrorCodes.md -->

<!-- prettier-ignore-start -->
# Class ShopperConsentErrorCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.consent.ShopperConsentErrorCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentErrorCodes.md)

Error codes for [ShopperConsentException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentException.md).


These error codes indicate the reason why a shopper consent operation failed.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CUSTOMER_NOT_AUTHENTICATED](#customer_not_authenticated): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_NOT_AUTHENTICATED" | Indicates that the customer is not authenticated. |
| [FEATURE_DISABLED](#feature_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FEATURE_DISABLED" | Indicates that the Marketing Consent feature is not enabled. |
| [INTERNAL_ERROR](#internal_error): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INTERNAL_ERROR" | Indicates that an internal error occurred. |
| [RETRIEVAL_ERROR](#retrieval_error): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETRIEVAL_ERROR" | Indicates that an error occurred while retrieving consent subscriptions. |
| [UPDATE_ERROR](#update_error): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UPDATE_ERROR" | Indicates that an error occurred while updating consent subscriptions. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CUSTOMER_NOT_AUTHENTICATED

- CUSTOMER_NOT_AUTHENTICATED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOMER_NOT_AUTHENTICATED"
  - : Indicates that the customer is not authenticated.


---

### FEATURE_DISABLED

- FEATURE_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FEATURE_DISABLED"
  - : Indicates that the Marketing Consent feature is not enabled.


---

### INTERNAL_ERROR

- INTERNAL_ERROR: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INTERNAL_ERROR"
  - : Indicates that an internal error occurred.


---

### RETRIEVAL_ERROR

- RETRIEVAL_ERROR: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "RETRIEVAL_ERROR"
  - : Indicates that an error occurred while retrieving consent subscriptions.


---

### UPDATE_ERROR

- UPDATE_ERROR: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UPDATE_ERROR"
  - : Indicates that an error occurred while updating consent subscriptions.


---

<!-- prettier-ignore-end -->

<!-- document id=3d0b03686b1819bf7f1955c3d38984a6652b2ffb23ea1b00b7f9251e06282076 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.consent.ShopperConsentException.md -->

<!-- prettier-ignore-start -->
# Class ShopperConsentException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.consent.ShopperConsentException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentException.md)

This exception is thrown by [ShopperConsentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentMgr.md) methods when an error occurs
during consent subscription operations.


The 'errorCode' property is set to one of the following values:

- [ShopperConsentErrorCodes.FEATURE_DISABLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentErrorCodes.md#feature_disabled)- Indicates that the Marketing Consent  feature is not enabled.
- [ShopperConsentErrorCodes.RETRIEVAL_ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentErrorCodes.md#retrieval_error)- Indicates that an error occurred while  retrieving consent subscriptions.
- [ShopperConsentErrorCodes.UPDATE_ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentErrorCodes.md#update_error)- Indicates that an error occurred while  updating consent subscriptions.
- [ShopperConsentErrorCodes.CUSTOMER_NOT_AUTHENTICATED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentErrorCodes.md#customer_not_authenticated)- Indicates that the customer  is not authenticated (required for consent status retrieval).
- [ShopperConsentErrorCodes.INTERNAL_ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentErrorCodes.md#internal_error)- Indicates that an internal error occurred.



## Property Summary

| Property | Description |
| --- | --- |
| [errorCode](#errorcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the error code indicating the reason for the failure. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getErrorCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentException.md#geterrorcode)() | Returns the error code indicating the reason for the failure. |

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### errorCode
- errorCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the error code indicating the reason for the failure.


---

## Method Details

### getErrorCode()
- getErrorCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the error code indicating the reason for the failure.

    **Returns:**
    - The error code.


---

<!-- prettier-ignore-end -->

<!-- document id=4d7e7f327a42d69bbf3bf27858a142d91fe0087c835f095fd9ab99354b2a9846 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.consent.ShopperConsentMgr.md -->

<!-- prettier-ignore-start -->
# Class ShopperConsentMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.consent.ShopperConsentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentMgr.md)

Provides static helper methods for managing shopper marketing consent subscriptions.


This API enables retrieving and updating marketing consent preferences.
Consent subscriptions define communication categories (e.g., "Newsletter", "Product Updates")
and the channels (EMAIL, SMS, WHATSAPP) through which marketing communications can be sent.




**Prerequisites:**

- The Marketing Consent feature must be enabled and configured
- For consent status retrieval, the current request must have a customer context





**Example usage:**

```
var ShopperConsentMgr = require('dw/customer/consent/ShopperConsentMgr');

// Get all subscriptions for the current site
var subscriptions = ShopperConsentMgr.getSubscriptions();

for each (var sub in subscriptions) {
    trace('Subscription: ' + sub.subscriptionId + ' - ' + sub.title);
    trace('Available channels: ' + sub.channels.join(', '));
}

// Get subscriptions with consent status (for authenticated customers)
var subsWithStatus = ShopperConsentMgr.getSubscriptions(null, true);

// Update consent for a specific subscription
ShopperConsentMgr.updateSubscription(
    'customer@example.com',
    'newsletter-subscription',
    'EMAIL',
    'OPT_IN'
);
```


**See Also:**
- [MarketingConsentSubscription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md)
- [ConsentStatusEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ConsentStatusEntry.md)


## Property Summary

| Property | Description |
| --- | --- |
| [subscriptions](#subscriptions): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Retrieves marketing consent subscriptions for the current site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getSubscriptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentMgr.md#getsubscriptions)() | Retrieves marketing consent subscriptions for the current site. |
| static [getSubscriptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentMgr.md#getsubscriptionslist-boolean)([List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Retrieves marketing consent subscriptions for the current site with optional filtering and status. |
| static [updateSubscription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentMgr.md#updatesubscriptionstring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Updates consent status for a subscription. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### subscriptions
- subscriptions: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Retrieves marketing consent subscriptions for the current site.
      
      
      This method returns all available consent subscriptions without consent status information.



---

## Method Details

### getSubscriptions()
- static getSubscriptions(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Retrieves marketing consent subscriptions for the current site.
      
      
      This method returns all available consent subscriptions without consent status information.


    **Returns:**
    - A collection of [MarketingConsentSubscription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md) objects.

    **Throws:**
    - ShopperConsentException - if the consent feature is not enabled or retrieval fails.


---

### getSubscriptions(List, Boolean)
- static getSubscriptions(tags: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md), includeConsentStatus: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Retrieves marketing consent subscriptions for the current site with optional filtering and status.
      
      
      Use this method to retrieve subscriptions filtered by tags and optionally include
      the current consent status for authenticated customers.


    **Parameters:**
    - tags - Optional list of tags to filter subscriptions. Pass null for all subscriptions.
    - includeConsentStatus - If true, includes the current consent status for each subscription.                              Requires a customer context.

    **Returns:**
    - A collection of [MarketingConsentSubscription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md) objects.

    **Throws:**
    - ShopperConsentException - if the consent feature is not enabled, retrieval fails,                                  or consent status retrieval fails.


---

### updateSubscription(String, String, String, String)
- static updateSubscription(contactPointValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), subscriptionId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), channel: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), status: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Updates consent status for a subscription.
      
      
      This method updates the consent status in Salesforce Core for the specified
      contact point and subscription channel combination.


    **Parameters:**
    - contactPointValue - The contact point value (email address or phone number).
    - subscriptionId - The subscription ID.
    - channel - The channel type ("EMAIL", "SMS", or "WHATSAPP").
    - status - The consent status ("OPT\_IN" or "OPT\_OUT").

    **Throws:**
    - ShopperConsentException - if the consent feature is not enabled or update fails.


---

<!-- prettier-ignore-end -->

<!-- document id=4bd68d27f842f084b37c978f9791b6aa061ba461724bfb5ec5c76f43f2c78d62 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.shoppercontext.ShopperContext.md -->

<!-- prettier-ignore-start -->
# Class ShopperContext

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.shoppercontext.ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md)

The class represents Shopper Context. It is used to manage personalized shopping experiences on your storefront.


Shopper Context is used to personalize shopper experiences with context values such as custom session attributes,
assignment qualifiers, geolocation, clientIP address, effective date time, source code, coupon code and customer
groups.




When Shopper Context is set for a shopper, the context is applied in the next request and can activate promotions or
price books assigned to customer groups, source codes, or stores (via assignments).
Also see: [ShopperContextMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md)



## Property Summary

| Property | Description |
| --- | --- |
| [assignmentQualifiers](#assignmentqualifiers): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) | Returns the assignment qualifiers from the Shopper Context. |
| [clientIP](#clientip): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the IP address of the client from the Shopper Context. |
| [couponCodes](#couponcodes): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) | Returns the Coupon codes from the Shopper Context. |
| [customQualifiers](#customqualifiers): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) | Returns the custom qualifiers from the Shopper Context. |
| [customerGroupIDs](#customergroupids): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md) | Returns customer group IDs from the Shopper Context to apply. |
| [effectiveDateTime](#effectivedatetime): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Returns the effective date time from the Shopper Context. |
| [geolocation](#geolocation): [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) | Returns the geographic location from the Shopper Context. |
| [sourceCode](#sourcecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the source code from the Shopper Context. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ShopperContext](#shoppercontext)() | Constructor for ShopperContext. |

## Method Summary

| Method | Description |
| --- | --- |
| [getAssignmentQualifiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#getassignmentqualifiers)() | Returns the assignment qualifiers from the Shopper Context. |
| [getClientIP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#getclientip)() | Returns the IP address of the client from the Shopper Context. |
| [getCouponCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#getcouponcodes)() | Returns the Coupon codes from the Shopper Context. |
| [getCustomQualifiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#getcustomqualifiers)() | Returns the custom qualifiers from the Shopper Context. |
| [getCustomerGroupIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#getcustomergroupids)() | Returns customer group IDs from the Shopper Context to apply. |
| [getEffectiveDateTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#geteffectivedatetime)() | Returns the effective date time from the Shopper Context. |
| [getGeolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#getgeolocation)() | Returns the geographic location from the Shopper Context. |
| [getSourceCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#getsourcecode)() | Returns the source code from the Shopper Context. |
| [setAssignmentQualifiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#setassignmentqualifiersmap)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)) | Sets the assignment qualifiers in the Shopper Context. |
| [setClientIP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#setclientipstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the IP address of the client in the Shopper Context. |
| [setCouponCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#setcouponcodesset)([Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)) | Sets the Coupon codes in the Shopper Context. |
| [setCustomQualifiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#setcustomqualifiersmap)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)) | Sets the session custom attributes as custom qualifiers in the Shopper Context. |
| [setCustomerGroupIDs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#setcustomergroupidsset)([Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)) | Sets the customer group IDs for the Shopper Context to apply. |
| [setEffectiveDateTime](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#seteffectivedatetimedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Sets the effective date time for the context to apply. |
| [setGeolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#setgeolocationgeolocation)([Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)) | Sets the geographic location of the client in the Shopper Context. |
| [setSourceCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md#setsourcecodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the source code for the Shopper Context to apply. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### assignmentQualifiers
- assignmentQualifiers: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the assignment qualifiers from the Shopper Context. Assignment qualifiers are set when using the
      assignment framework to trigger pricing and promotion experiences for Products, Product Search, Basket, Shipping
      methods etc.



---

### clientIP
- clientIP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the IP address of the client from the Shopper Context.


---

### couponCodes
- couponCodes: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Returns the Coupon codes from the Shopper Context.


---

### customQualifiers
- customQualifiers: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the custom qualifiers from the Shopper Context. Custom qualifiers contain the custom session attributes
      set in the Shopper Context.



---

### customerGroupIDs
- customerGroupIDs: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Returns customer group IDs from the Shopper Context to apply. The customer group IDs set in Shopper Context
      evaluate to customer groups that trigger the promotions (campaign assignment) assigned to the customer groups.



---

### effectiveDateTime
- effectiveDateTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the effective date time from the Shopper Context. With the effective date time you can retrieve
      promotions that are active at a particular time. For example, "Shop the Future" use cases.



---

### geolocation
- geolocation: [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)
  - : Returns the geographic location from the Shopper Context.


---

### sourceCode
- sourceCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the source code from the Shopper Context. The source code set in Shopper Context evaluates to source code
      group that triggers the promotion (campaign assignment) and Price books (assigned to Source code group).



---

## Constructor Details

### ShopperContext()
- ShopperContext()
  - : Constructor for ShopperContext.
      
      
      This constructor is used to create an empty object. The object will be empty and must be populated with the
      appropriate setter methods. For example:
      
      ```
      ShopperContext context = new ShopperContext();
      context.setSourceCode( "sourcecode" );
      ShopperContextMgr.setShopperContext( context, true );
      ```



---

## Method Details

### getAssignmentQualifiers()
- getAssignmentQualifiers(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the assignment qualifiers from the Shopper Context. Assignment qualifiers are set when using the
      assignment framework to trigger pricing and promotion experiences for Products, Product Search, Basket, Shipping
      methods etc.


    **Returns:**
    - A map of assignment qualifiers set in the Shopper Context.


---

### getClientIP()
- getClientIP(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the IP address of the client from the Shopper Context.

    **Returns:**
    - The IP address of the client set in the Shopper Context.


---

### getCouponCodes()
- getCouponCodes(): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Returns the Coupon codes from the Shopper Context.

    **Returns:**
    - The Coupon codes set in the Shopper Context.


---

### getCustomQualifiers()
- getCustomQualifiers(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the custom qualifiers from the Shopper Context. Custom qualifiers contain the custom session attributes
      set in the Shopper Context.


    **Returns:**
    - A map containing the custom qualifiers set in the Shopper Context.


---

### getCustomerGroupIDs()
- getCustomerGroupIDs(): [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
  - : Returns customer group IDs from the Shopper Context to apply. The customer group IDs set in Shopper Context
      evaluate to customer groups that trigger the promotions (campaign assignment) assigned to the customer groups.


    **Returns:**
    - The customer group IDs for the Shopper Context to apply.


---

### getEffectiveDateTime()
- getEffectiveDateTime(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the effective date time from the Shopper Context. With the effective date time you can retrieve
      promotions that are active at a particular time. For example, "Shop the Future" use cases.


    **Returns:**
    - The effective date time in UTC for the Shopper Context to apply.


---

### getGeolocation()
- getGeolocation(): [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)
  - : Returns the geographic location from the Shopper Context.

    **Returns:**
    - The geographic location set in the Shopper Context.


---

### getSourceCode()
- getSourceCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the source code from the Shopper Context. The source code set in Shopper Context evaluates to source code
      group that triggers the promotion (campaign assignment) and Price books (assigned to Source code group).


    **Returns:**
    - The source code for the Shopper Context to apply.


---

### setAssignmentQualifiers(Map)
- setAssignmentQualifiers(assignmentQualifiers: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)): void
  - : Sets the assignment qualifiers in the Shopper Context. Assignment qualifiers are set when using the assignment
      framework to trigger pricing and promotion experiences for Products, Product Search, Basket, Shipping methods
      etc.
      
      
      **Example: Assignment qualifier for store can be set as follows: **
      
      ```
       var assignmentQualifiers = new dw.util.HashMap();
       assignmentQualifiers.put( "storeId", "Boston" );
       ShopperContext context = new ShopperContext();
       context.setAssignmentQualifiers( customQualifiers );
       ShopperContextMgr.setShopperContext( context, true );
      ```


    **Parameters:**
    - assignmentQualifiers - A map which contains the assignment qualifiers to save in the Shopper Context.


---

### setClientIP(String)
- setClientIP(clientIP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the IP address of the client in the Shopper Context. The client IP evaluates to a geolocation. If the client
      IP address is not a valid IPv4/IPv6 address an error is thrown.


    **Parameters:**
    - clientIP - The IP Address of the client to set in the Shopper Context.


---

### setCouponCodes(Set)
- setCouponCodes(couponCodes: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)): void
  - : Sets the Coupon codes in the Shopper Context. When you set coupon codes, it is saved as context for subsequent
      requests and can then trigger promotions via the campaign which are tied to the coupon. A maximum of 5 coupon
      codes can be set in the ShopperContext.


    **Parameters:**
    - couponCodes - The set of coupon codes to set in the Shopper Context. A maximum of 5 coupon codes per             ShopperContext are allowed.


---

### setCustomQualifiers(Map)
- setCustomQualifiers(customQualifiers: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)): void
  - : Sets the session custom attributes as custom qualifiers in the Shopper Context. Custom qualifiers are set when
      you want to trigger pricing and promotion experiences using a dynamic session-based customer groups.
      
      
      **Example: A session custom attribute 'device\_type' can be saved as follows: **
      
      ```
       var customQualifiers = new dw.util.HashMap();
       customQualifiers.put( "deviceType", "iPad" );
       ShopperContext context = new ShopperContext();
       context.setCustomQualifiers( customQualifiers );
       ShopperContextMgr.setShopperContext( context, true );
      ```


    **Parameters:**
    - customQualifiers - A map which contains the custom session attributes to save in the Shopper Context.


---

### setCustomerGroupIDs(Set)
- setCustomerGroupIDs(customerGroupIDs: [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)): void
  - : Sets the customer group IDs for the Shopper Context to apply. Set the customer group IDs to evaluate customer
      groups that trigger the promotions (campaign assignment) assigned to the customer groups.


    **Parameters:**
    - customerGroupIDs - The customer group IDs for the Shopper Context to apply.


---

### setEffectiveDateTime(Date)
- setEffectiveDateTime(effectiveDateTime: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Sets the effective date time for the context to apply. With the effective date time you can retrieve promotions
      that are active at a particular time. For example, "Shop the Future" use cases.


    **Parameters:**
    - effectiveDateTime - The effective date time to set in the Shopper Context.


---

### setGeolocation(Geolocation)
- setGeolocation(geolocation: [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)): void
  - : Sets the geographic location of the client in the Shopper Context. When you set a geolocation, it is saved as
      context for subsequent requests. This overrides any context previously saved using clientIP in the Shopper
      Context.


    **Parameters:**
    - geolocation - The geographic location of the client to set in the Shopper Context.


---

### setSourceCode(String)
- setSourceCode(sourceCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the source code for the Shopper Context to apply. Set the source code to evaluate source code group that
      triggers the promotion (campaign assignment) and Price books (assigned to Source code group).


    **Parameters:**
    - sourceCode - The source code to set in the Shopper Context.


---

<!-- prettier-ignore-end -->

<!-- document id=bd5712455540b3d55aa7ded293c7e2ab23ca6af4d510590e888bf02b0474da6a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.shoppercontext.ShopperContextErrorCodes.md -->

<!-- prettier-ignore-start -->
# Class ShopperContextErrorCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.shoppercontext.ShopperContextErrorCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md)

Helper class containing error codes to indicate why a Shopper Context cannot be accessed, set or modified.


## Constant Summary

| Constant | Description |
| --- | --- |
| [ASSIGNMENT_QUALIFIERS_LIMIT_EXCEEDED](#assignment_qualifiers_limit_exceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ASSIGNMENT_QUALIFIERS_LIMIT_EXCEEDED" | Indicates that the assignment qualifiers limit exceeded |
| [COUPON_CODES_LIMIT_EXCEEDED](#coupon_codes_limit_exceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODES_LIMIT_EXCEEDED" | Indicates that the coupon codes limit exceeded |
| [CUSTOM_QUALIFIERS_LIMIT_EXCEEDED](#custom_qualifiers_limit_exceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOM_QUALIFIERS_LIMIT_EXCEEDED" | Indicates that the custom qualifiers limit exceeded |
| [FEATURE_DISABLED](#feature_disabled): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FEATURE_DISABLED" | Indicates that the feature toggle 'ShopperContextEnabled' is not enabled. |
| [INTERNAL_ERROR](#internal_error): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INTERNAL_ERROR" | Indicates that an internal error occurred while setting, retrieving or deleting the shopper context |
| [INVALID_ARGUMENT](#invalid_argument): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INVALID_ARGUMENT" | Indicates an invalid argument was provided |
| [INVALID_REQUEST_TYPE](#invalid_request_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INVALID_REQUEST_TYPE" | Indicates that the request type is invalid. |
| [QUOTA_LIMIT_EXCEEDED](#quota_limit_exceeded): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "QUOTA_LIMIT_EXCEEDED" | Indicates that the quota limit for the shopper context has been reached. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [ShopperContextErrorCodes](#shoppercontexterrorcodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ASSIGNMENT_QUALIFIERS_LIMIT_EXCEEDED

- ASSIGNMENT_QUALIFIERS_LIMIT_EXCEEDED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ASSIGNMENT_QUALIFIERS_LIMIT_EXCEEDED"
  - : Indicates that the assignment qualifiers limit exceeded


---

### COUPON_CODES_LIMIT_EXCEEDED

- COUPON_CODES_LIMIT_EXCEEDED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "COUPON_CODES_LIMIT_EXCEEDED"
  - : Indicates that the coupon codes limit exceeded


---

### CUSTOM_QUALIFIERS_LIMIT_EXCEEDED

- CUSTOM_QUALIFIERS_LIMIT_EXCEEDED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CUSTOM_QUALIFIERS_LIMIT_EXCEEDED"
  - : Indicates that the custom qualifiers limit exceeded


---

### FEATURE_DISABLED

- FEATURE_DISABLED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "FEATURE_DISABLED"
  - : Indicates that the feature toggle 'ShopperContextEnabled' is not enabled.


---

### INTERNAL_ERROR

- INTERNAL_ERROR: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INTERNAL_ERROR"
  - : Indicates that an internal error occurred while setting, retrieving or deleting the shopper context


---

### INVALID_ARGUMENT

- INVALID_ARGUMENT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INVALID_ARGUMENT"
  - : Indicates an invalid argument was provided


---

### INVALID_REQUEST_TYPE

- INVALID_REQUEST_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "INVALID_REQUEST_TYPE"
  - : Indicates that the request type is invalid. Request must be a SCAPI request, or a hybrid storefront request, or
      an ocapi request using a SLAS token.



---

### QUOTA_LIMIT_EXCEEDED

- QUOTA_LIMIT_EXCEEDED: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "QUOTA_LIMIT_EXCEEDED"
  - : Indicates that the quota limit for the shopper context has been reached.


---

## Constructor Details

### ShopperContextErrorCodes()
- ShopperContextErrorCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=583cd314914de64e2d8c1bf8eb9e0911769ce6a6d8937aafd73ead26caa907c7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.shoppercontext.ShopperContextException.md -->

<!-- prettier-ignore-start -->
# Class ShopperContextException

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.shoppercontext.ShopperContextException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextException.md)

This exception could be thrown by
[ShopperContextMgr.setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean),
[ShopperContextMgr.getShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext) and
[ShopperContextMgr.removeShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext) when an error occurs.


'errorCode' property is set to one of the following values:

- [ShopperContextErrorCodes.FEATURE_DISABLED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md#feature_disabled)= Indicates that the Shopper Context  Feature is not enabled.
- [ShopperContextErrorCodes.CUSTOM_QUALIFIERS_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md#custom_qualifiers_limit_exceeded)= Indicates that the  number of custom qualifiers in [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md)has exceeded the allowed limit.
- [ShopperContextErrorCodes.ASSIGNMENT_QUALIFIERS_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md#assignment_qualifiers_limit_exceeded)= Indicates that  the number of assignment qualifiers in [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md)has exceeded the allowed  limit.
- [ShopperContextErrorCodes.QUOTA_LIMIT_EXCEEDED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md#quota_limit_exceeded)= Indicates that the quota limit  for the Shopper Context has been reached.  
For more information on shopper context quota limits please refer to:  [Shopper Context Quota Limits](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html\#constraints)

- [ShopperContextErrorCodes.INTERNAL_ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md#internal_error)= Indicates that an error occurred  while setting, retrieving or deleting the shopper context.
- [ShopperContextErrorCodes.INVALID_ARGUMENT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md#invalid_argument)= Indicates that an invalid client  IP address was set in the Shopper Context.
- [ShopperContextErrorCodes.INVALID_REQUEST_TYPE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md#invalid_request_type)= Indicates that the request  type is invalid. Request must be a SCAPI request, or a hybrid storefront request, or an OCAPI request using a SLAS  token.



## Property Summary

| Property | Description |
| --- | --- |
| [errorCode](#errorcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Indicates reason why the following methods failed:  [ShopperContextMgr.setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean) or  [ShopperContextMgr.getShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext) or  [ShopperContextMgr.removeShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext) failed. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getErrorCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextException.md#geterrorcode)() | Indicates reason why the following methods failed:  [ShopperContextMgr.setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean) or  [ShopperContextMgr.getShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext) or  [ShopperContextMgr.removeShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext) failed. |

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### errorCode
- errorCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Indicates reason why the following methods failed:
      [ShopperContextMgr.setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean) or
      [ShopperContextMgr.getShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext) or
      [ShopperContextMgr.removeShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext) failed.



---

## Method Details

### getErrorCode()
- getErrorCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Indicates reason why the following methods failed:
      [ShopperContextMgr.setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean) or
      [ShopperContextMgr.getShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext) or
      [ShopperContextMgr.removeShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext) failed.


    **Returns:**
    - The error code.


---

<!-- prettier-ignore-end -->

<!-- document id=ffa5b82e0c12be570c7084c7e2e8efc545a0320517e5accae21c5b20fb2f4969 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.shoppercontext.ShopperContextMgr.md -->

<!-- prettier-ignore-start -->
# Class ShopperContextMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.shoppercontext.ShopperContextMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md)



Provides static helper methods for managing Shopper Context.




Shopper Context is used to personalize shopper experiences with context values such as custom session attributes,
assignment qualifiers, geolocation, effective datetime, source code and more. When Shopper Context is set for a
shopper, it can activate promotions or price books assigned to customer groups, source codes, or stores (via
assignments) in the subsequent requests, not the current request.




Shopper Context is used to personalize the shopper experience in case of Composable/Headless or Hybrid storefront
implementations that use Shopper Login and API Access Service (SLAS).




NOTE: This script API is not intended to be used for standard server-side storefront implementations. Only for
Composable/Headless or Hybrid storefront implementations.




Unlike [CustomerContextMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerContextMgr.md) which is used to set just Effective Time for which the customer is
shopping at, Shopper Context API provides a way to set many types of contexts such as custom session attributes,
assignment qualifiers, geolocation, effective datetime, source code etc.




The following feature toggles and site preferences must be enabled in order to use this script API:

- Enable Shopper Context Feature
- Hybrid Auth Settings' site preference - only in case of Hybrid storefront implementations





For more details on Shopper Context please refer to: [Shopper Context
API Overview](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary)




For more details on Hybrid Authentication for Hybrid storefronts please refer to:
[Hybrid
Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-auth.html)




[ShopperContextMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md) is used to create, access and delete Shopper Context.

- To add Shopper Context, use methods [setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean).    - To access Shopper Context, use method [getShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext).        - To delete Shopper Context, use methods [removeShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext).            - To fetch Geolocation based on clientIP already set in Shopper Context, use method [getGeolocation()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getgeolocation)

Typical usage:                
        ```
        // get the ShopperContext if it exists ShopperContext context = ShopperContextMgr.getShopperContext(); if (context == null) {     context = new ShopperContext(); } // set the values in the ShopperContext object context.setSourceCode( "sourcecode" ); var customQualifiers = new dw.util.HashMap(); customQualifiers.put( "deviceType", "iPad" ); context.setCustomQualifiers( customQualifiers ); // Save the ShopperContext ShopperContextMgr.setShopperContext( context, true );
        ```
NOTE: Ensure the ShopperContext object is saved using [setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean)after        setting or updating the context values.        



## Property Summary

| Property | Description |
| --- | --- |
| [geolocation](#geolocation): [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) `(read-only)` | Gets the [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) object for the clientIP set in  [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) or null if no shopperContext is found, or no clientIP was set  or Geolocation for the clientIP was not found. |
| [shopperContext](#shoppercontext): [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) | Returns the [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) if it exists for the customer. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getGeolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getgeolocation)() | Gets the [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) object for the clientIP set in  [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) or null if no shopperContext is found, or no clientIP was set  or Geolocation for the clientIP was not found. |
| static [getShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext)() | Returns the [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) if it exists for the customer. |
| static [removeShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext)() | Removes the [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) for the customer. |
| static [setShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean)([ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | <p>  Sets new [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) for the customer or overwrites the existing context. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### geolocation
- geolocation: [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) `(read-only)`
  - : Gets the [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) object for the clientIP set in
      [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) or null if no shopperContext is found, or no clientIP was set
      or Geolocation for the clientIP was not found.
      
      
      The method throws an exception if the call fails.



---

### shopperContext
- shopperContext: [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md)
  - : Returns the [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) if it exists for the customer. Returns null if it
      does not exist.



---

## Method Details

### getGeolocation()
- static getGeolocation(): [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)
  - : Gets the [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md) object for the clientIP set in
      [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) or null if no shopperContext is found, or no clientIP was set
      or Geolocation for the clientIP was not found.
      
      
      The method throws an exception if the call fails.


    **Throws:**
    - dw.customer.shoppercontext.ShopperContextException - This exception is thrown if error occurs while trying              to retrieve Geolocation string from the Shopper Context.


---

### getShopperContext()
- static getShopperContext(): [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md)
  - : Returns the [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) if it exists for the customer. Returns null if it
      does not exist.


    **Returns:**
    - The Shopper Context or null.

    **Throws:**
    - dw.customer.shoppercontext.ShopperContextException - This exception is thrown if an error occurs while              fetching the Shopper Context.


---

### removeShopperContext()
- static removeShopperContext(): void
  - : Removes the [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) for the customer.
      
      
      The method throws an exception if the deletion of Shopper Context fails.


    **Throws:**
    - dw.customer.shoppercontext.ShopperContextException - This exception is thrown if error occurs while              deleting the Shopper Context.


---

### setShopperContext(ShopperContext, Boolean)
- static setShopperContext(shopperContext: [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md), evaluateContextWithClientIP: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : 
      
      Sets new [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md) for the customer or overwrites the existing context.
      
      
      
      
      Note: This method does not save the attributes from the given Shopper Context such as - custom session
      attributes, source code, effective date time etc., - in the current session object. These attributes are read
      from Shopper Context and stored in the corresponding session attributes during subsequent requests and not in the
      current request. Hence, promotions, price books etc., are triggered in subsequent requests.
      
      
      If `clientIP` is set in [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md), the geolocation information
      is retrieved and set in `x-geolocation` header.
      
      
      And if the parameter `evaluateContextWithClientIP` is set to true, the `clientIP` will be
      saved to the Shopper Context.
      
      
      If parameter `evaluateContextWithClientIP` is set to false, the `clientIP` will not be
      saved to the Shopper Context.
      
      
      If the `geoLocation` attribute is set, it overrides any geolocation context set by
      `clientIP`.


    **Parameters:**
    - shopperContext - The new Shopper Context to set. See documentation for             [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md)
    - evaluateContextWithClientIP - The boolean to determine if Shopper Context should be evaluated with clientIP             address.

    **Throws:**
    - dw.customer.shoppercontext.ShopperContextException - This exception is thrown if the Shopper Context is not              saved or if validation fails.


---

<!-- prettier-ignore-end -->

<!-- document id=c9571500e692ccb81403013067e52cc23698526310189b763554571c8f8f5c96 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.Signature.md -->

<!-- prettier-ignore-start -->
# Class Signature

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.Signature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md)


This class allows access to signature services offered through the Java
Cryptography Architecture (JCA). At this time the signature/verification implementation of the
methods is based on the default RSA JCE provider of the JDK - sun.security.rsa.SunRsaSign



dw.crypto.Signature is an adapter to the security provider implementation
and covers several digest algorithms:

- SHA1withRSA (deprecated)
- SHA256withRSA
- SHA384withRSA
- SHA512withRSA
- SHA256withRSA/PSS
- SHA384withRSA/PSS
- SHA512withRSA/PSS
- SHA256withECDSA
- SHA384withECDSA
- SHA512withECDSA





Key size generally ranges between 512 and 65536 bits (the latter of which is unnecessarily large).

Default key size for RSA is 1024. SHA384withRSA and SHA512withRSA require a key with length of at least 1024 bits.

For ECDSA, the following key sizes are supported:

- SHA256withECDSA: 256-bit key (NIST P-256)
- SHA384withECDSA: 384-bit key (NIST P-384)
- SHA512withECDSA: 521-bit key (NIST P-521)

When choosing a key size - beware of the tradeoff between security and processing time:

The longer the key, the harder to break it but also it takes more time for the two sides to sign and verify the signature.

An exception will be thrown for keys shorter than 2048 bits in this version of the API.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, 12, and other relevant requirements.



## Constant Summary

| Constant | Description |
| --- | --- |
| [SUPPORTED_DIGEST_ALGORITHMS_AS_ARRAY](#supported_digest_algorithms_as_array): [String\[\]](TopLevel.String.md) | Supported digest algorithms exposed as a string array |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Signature](#signature)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| [isDigestAlgorithmSupported](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#isdigestalgorithmsupportedstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Checks to see if a digest algorithm is supported |
| [sign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#signstring-keyref-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs a string and returns a string |
| [sign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#signstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs a string and returns a string |
| [signBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#signbytesbytes-keyref-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs bytes and returns bytes |
| [signBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#signbytesbytes-string-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs bytes and returns bytes |
| [verifyBytesSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#verifybytessignaturebytes-bytes-certificateref-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as bytes |
| [verifyBytesSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#verifybytessignaturebytes-bytes-string-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as bytes |
| [verifySignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#verifysignaturestring-string-certificateref-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as string |
| [verifySignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md#verifysignaturestring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as string |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### SUPPORTED_DIGEST_ALGORITHMS_AS_ARRAY

- SUPPORTED_DIGEST_ALGORITHMS_AS_ARRAY: [String\[\]](TopLevel.String.md)
  - : Supported digest algorithms exposed as a string array


---

## Constructor Details

### Signature()
- Signature()
  - : 


---

## Method Details

### isDigestAlgorithmSupported(String)
- isDigestAlgorithmSupported(digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks to see if a digest algorithm is supported

    **Parameters:**
    - digestAlgorithm - the digest algorithm name

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### sign(String, KeyRef, String)
- sign(contentToSign: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Signs a string and returns a string

    **Parameters:**
    - contentToSign - base64 encoded content to sign
    - privateKey - a reference to a private key entry in the keystore
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - the base64 encoded signature


---

### sign(String, String, String)
- sign(contentToSign: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Signs a string and returns a string

    **Parameters:**
    - contentToSign - base64 encoded content to sign
    - privateKey - base64 encoded private key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - the base64 encoded signature


---

### signBytes(Bytes, KeyRef, String)
- signBytes(contentToSign: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Signs bytes and returns bytes

    **Parameters:**
    - contentToSign - transformed with UTF-8 encoding into a byte stream
    - privateKey - a reference to a private key entry in the keystore
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - signature


---

### signBytes(Bytes, String, String)
- signBytes(contentToSign: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Signs bytes and returns bytes

    **Parameters:**
    - contentToSign - transformed with UTF-8 encoding into a byte stream
    - privateKey - base64 encoded private key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - signature


---

### verifyBytesSignature(Bytes, Bytes, CertificateRef, String)
- verifyBytesSignature(signature: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), contentToVerify: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), certificate: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as bytes

    **Parameters:**
    - signature - signature to check as bytes
    - contentToVerify - as bytes
    - certificate - a reference to a trusted certificate
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### verifyBytesSignature(Bytes, Bytes, String, String)
- verifyBytesSignature(signature: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), contentToVerify: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as bytes

    **Parameters:**
    - signature - signature to check as bytes
    - contentToVerify - as bytes
    - publicKey - base64 encoded public key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### verifySignature(String, String, CertificateRef, String)
- verifySignature(signature: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contentToVerify: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), certificate: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as string

    **Parameters:**
    - signature - base64 encoded signature
    - contentToVerify - base64 encoded content to verify
    - certificate - a reference to a trusted certificate
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### verifySignature(String, String, String, String)
- verifySignature(signature: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contentToVerify: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as string

    **Parameters:**
    - signature - base64 encoded signature
    - contentToVerify - base64 encoded content to verify
    - publicKey - base64 encoded public key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

<!-- prettier-ignore-end -->

<!-- document id=f31c8ed11205c2b976a81ea723a65f344be1c0f5b7e279a27ebbe976e9ab78a0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.SimpleExtensible.md -->

<!-- prettier-ignore-start -->
# Class SimpleExtensible

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.SimpleExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SimpleExtensible.md)

Base class alternative to ExtensibleObject for customizable objects which do not rely on the metadata system.
Unlike Extensible any custom attributes can be set on the fly and are not checked against an available list.
Similar to Extensible method [getCustom()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SimpleExtensible.md#getcustom) is the central point to retrieve and store the objects attribute
values.



## Property Summary

| Property | Description |
| --- | --- |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes for this object. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SimpleExtensible.md#getcustom)() | Returns the custom attributes for this object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes for this object.


---

## Method Details

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes for this object.

    **Returns:**
    - the custom attributes for this object.


---

<!-- prettier-ignore-end -->

<!-- document id=34087655ccd3189f58ff28515b5f90176bfa409b44c8af293fd1b0929472ed93 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Site.md -->

<!-- prettier-ignore-start -->
# Class Site

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Site](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md)

This class represents a site in Commerce Cloud Digital and provides access to
several site-level configuration values which are managed from within the
Business Manager. It is only possible to get a reference to the current site
as determined by the current request. The static method
[getCurrent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getcurrent) returns a reference to the current site.



## Constant Summary

| Constant | Description |
| --- | --- |
| [SITE_STATUS_MAINTENANCE](#site_status_maintenance): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | Constant that represents the Site under maintenance/offline |
| [SITE_STATUS_ONLINE](#site_status_online): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Constant that represents the Site is Online |
| [SITE_STATUS_PROTECTED](#site_status_protected): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Constant that represents the Site is in preview mode or online/password (protected) |

## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the site. |
| ~~[OMSEnabled](#omsenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Whether oms is active in the current site. |
| [allSites](#allsites): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns all sites. |
| [allowedCurrencies](#allowedcurrencies): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns the allowed currencies of the current site as a collection of  currency codes. |
| [allowedLocales](#allowedlocales): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns the allowed locales of the current site as a collection of  locale ID's. |
| [calendar](#calendar): [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md) `(read-only)` | Returns a new Calendar object in the time zone of the  current site. |
| ~~[currencyCode](#currencycode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | Returns the default currency code for the current site. |
| [current](#current): [Site](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md) `(read-only)` | Returns the current site. |
| [defaultCurrency](#defaultcurrency): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the default currency code for the current site. |
| [defaultLocale](#defaultlocale): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return default locale for the site. |
| [einsteinSiteID](#einsteinsiteid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the Einstein site Id. |
| [httpHostName](#httphostname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the configured HTTP host name. |
| [httpsHostName](#httpshostname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the configured HTTPS host name. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns a descriptive name for the site. |
| [pageMetaTags](#pagemetatags): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)` | Returns all page meta tags, defined for this instance for which content can be generated. |
| [preferences](#preferences): [SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md) `(read-only)` | This method returns a container of all site preferences of this site. |
| [status](#status): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the status of this site. |
| [timezone](#timezone): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the code for the time zone in which the storefront is  running. |
| [timezoneOffset](#timezoneoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns time zone offset in which the storefront is running. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getAllSites](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getallsites)() | Returns all sites. |
| [getAllowedCurrencies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getallowedcurrencies)() | Returns the allowed currencies of the current site as a collection of  currency codes. |
| [getAllowedLocales](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getallowedlocales)() | Returns the allowed locales of the current site as a collection of  locale ID's. |
| static [getCalendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getcalendar)() | Returns a new Calendar object in the time zone of the  current site. |
| ~~[getCurrencyCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getcurrencycode)()~~ | Returns the default currency code for the current site. |
| static [getCurrent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getcurrent)() | Returns the current site. |
| [getCustomPreferenceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getcustompreferencevaluestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a custom preference value. |
| [getDefaultCurrency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getdefaultcurrency)() | Returns the default currency code for the current site. |
| [getDefaultLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getdefaultlocale)() | Return default locale for the site. |
| [getEinsteinSiteID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#geteinsteinsiteid)() | Returns the Einstein site Id. |
| [getHttpHostName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#gethttphostname)() | Returns the configured HTTP host name. |
| [getHttpsHostName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#gethttpshostname)() | Returns the configured HTTPS host name. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getid)() | Returns the ID of the site. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getname)() | Returns a descriptive name for the site. |
| [getPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getpagemetatagstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the page meta tag for the specified id. |
| [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getpagemetatags)() | Returns all page meta tags, defined for this instance for which content can be generated. |
| [getPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getpreferences)() | This method returns a container of all site preferences of this site. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getstatus)() | Returns the status of this site. |
| [getTimezone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#gettimezone)() | Returns the code for the time zone in which the storefront is  running. |
| [getTimezoneOffset](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#gettimezoneoffset)() | Returns time zone offset in which the storefront is running. |
| ~~[isOMSEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#isomsenabled)()~~ | Whether oms is active in the current site. |
| [setCustomPreferenceValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#setcustompreferencevaluestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | The method sets a value for a custom preference. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### SITE_STATUS_MAINTENANCE

- SITE_STATUS_MAINTENANCE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : Constant that represents the Site under maintenance/offline


---

### SITE_STATUS_ONLINE

- SITE_STATUS_ONLINE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Constant that represents the Site is Online


---

### SITE_STATUS_PROTECTED

- SITE_STATUS_PROTECTED: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Constant that represents the Site is in preview mode or online/password (protected)


---

## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the site.


---

### OMSEnabled
- ~~OMSEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Whether oms is active in the current site. This depends on a general
      property which states whether oms is active for the server,
      and a site-dependent preference whether oms is available for the current site.



---

### allSites
- allSites: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns all sites.


---

### allowedCurrencies
- allowedCurrencies: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns the allowed currencies of the current site as a collection of
      currency codes.



---

### allowedLocales
- allowedLocales: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns the allowed locales of the current site as a collection of
      locale ID's.



---

### calendar
- calendar: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md) `(read-only)`
  - : Returns a new Calendar object in the time zone of the
      current site.



---

### currencyCode
- ~~currencyCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : Returns the default currency code for the current site.

    **Deprecated:**
**warning:** Use [getDefaultCurrency()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getdefaultcurrency) method instead,

---

### current
- current: [Site](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md) `(read-only)`
  - : Returns the current site.


---

### defaultCurrency
- defaultCurrency: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the default currency code for the current site.


---

### defaultLocale
- defaultLocale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return default locale for the site.


---

### einsteinSiteID
- einsteinSiteID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the Einstein site Id. Typically this is a concatenation of the realm, underscore character and the site id.
      It can be overwritten by support users to help with realm moves to continue using the Einstein data from the old realm.
      Used when making calls to the Einstein APIs.



---

### httpHostName
- httpHostName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the configured HTTP host name. If no host name
      is configured the method returns the instance hostname.



---

### httpsHostName
- httpsHostName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the configured HTTPS host name. If no host name
      is configured the method returns the HTTP host name or the instance hostname, if
      that is not configured as well.



---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns a descriptive name for the site.


---

### pageMetaTags
- pageMetaTags: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md) `(read-only)`
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the home page meta tag context and rules.
      The rules are obtained from the current repository domain.



---

### preferences
- preferences: [SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md) `(read-only)`
  - : This method returns a container of all site preferences of this site.


---

### status
- status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the status of this site.
      
      
      Possible values are [SITE_STATUS_ONLINE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#site_status_online), [SITE_STATUS_MAINTENANCE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#site_status_maintenance), [SITE_STATUS_PROTECTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#site_status_protected)



---

### timezone
- timezone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the code for the time zone in which the storefront is
      running.



---

### timezoneOffset
- timezoneOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns time zone offset in which the storefront is running.


---

## Method Details

### getAllSites()
- static getAllSites(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns all sites.

    **Returns:**
    - all sites for the current instance


---

### getAllowedCurrencies()
- getAllowedCurrencies(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the allowed currencies of the current site as a collection of
      currency codes.


    **Returns:**
    - Collection of allowed site currencies


---

### getAllowedLocales()
- getAllowedLocales(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the allowed locales of the current site as a collection of
      locale ID's.


    **Returns:**
    - Collection if allowed site locales


---

### getCalendar()
- static getCalendar(): [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)
  - : Returns a new Calendar object in the time zone of the
      current site.


    **Returns:**
    - the Calendar object in the time zone of the
      current site.



---

### getCurrencyCode()
- ~~getCurrencyCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the default currency code for the current site.

    **Returns:**
    - the default currency code for the current site.

    **Deprecated:**
**warning:** Use [getDefaultCurrency()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getdefaultcurrency) method instead,

---

### getCurrent()
- static getCurrent(): [Site](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md)
  - : Returns the current site.

    **Returns:**
    - the current site.


---

### getCustomPreferenceValue(String)
- getCustomPreferenceValue(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns a custom preference value. If the preference does not exist the
      method returns null.  This method is simply a shortcut method for
      accessing the value for a custom attribute defined on the
      [SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md) object.
      
      
      ```
      // Method #1
      var mySitePrefValue1 : String =  dw.system.Site.getCurrent().
          getCustomPreferenceValue("mySitePref");
      
      // Method #2
      var sitePrefs : SitePreferences = dw.system.Site.getCurrent().getPreferences();
      var mySitePrefValue2 : String = sitePrefs.getCustom()["mySitePref"];
      ```


    **Parameters:**
    - name - preference name.

    **Returns:**
    - the preference value, or null if there is no preference with the
              given name.



---

### getDefaultCurrency()
- getDefaultCurrency(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the default currency code for the current site.

    **Returns:**
    - the default currency code for the current site.


---

### getDefaultLocale()
- getDefaultLocale(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return default locale for the site.

    **Returns:**
    - default locale for the site.


---

### getEinsteinSiteID()
- getEinsteinSiteID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the Einstein site Id. Typically this is a concatenation of the realm, underscore character and the site id.
      It can be overwritten by support users to help with realm moves to continue using the Einstein data from the old realm.
      Used when making calls to the Einstein APIs.


    **Returns:**
    - the Einstein site Id


---

### getHttpHostName()
- getHttpHostName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the configured HTTP host name. If no host name
      is configured the method returns the instance hostname.


    **Returns:**
    - the configured HTTP host name or if it is not
              set the instance hostname.



---

### getHttpsHostName()
- getHttpsHostName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the configured HTTPS host name. If no host name
      is configured the method returns the HTTP host name or the instance hostname, if
      that is not configured as well.


    **Returns:**
    - the configured HTTPS host name or HTTP host name or the instance hostname.


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the site.

    **Returns:**
    - the ID of the site.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a descriptive name for the site.

    **Returns:**
    - a descriptive name for the site.


---

### getPageMetaTag(String)
- getPageMetaTag(id: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)
  - : Returns the page meta tag for the specified id.
      
      
      The meta tag content is generated based on the home page meta tag context and rule.
      The rule is obtained from the current repository domain.
      
      
      Null will be returned if the meta tag is undefined on the current instance, or if no rule can be found for the
      current context, or if the rule resolves to an empty string.


    **Parameters:**
    - id - the ID to get the page meta tag for

    **Returns:**
    - page meta tag containing content generated based on rules


---

### getPageMetaTags()
- getPageMetaTags(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns all page meta tags, defined for this instance for which content can be generated.
      
      
      The meta tag content is generated based on the home page meta tag context and rules.
      The rules are obtained from the current repository domain.


    **Returns:**
    - page meta tags defined for this instance, containing content generated based on rules


---

### getPreferences()
- getPreferences(): [SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md)
  - : This method returns a container of all site preferences of this site.

    **Returns:**
    - a preferences object containing all system and custom site
              preferences of this site



---

### getStatus()
- getStatus(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status of this site.
      
      
      Possible values are [SITE_STATUS_ONLINE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#site_status_online), [SITE_STATUS_MAINTENANCE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#site_status_maintenance), [SITE_STATUS_PROTECTED](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#site_status_protected)


    **Returns:**
    - Status of the this site.


---

### getTimezone()
- getTimezone(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the code for the time zone in which the storefront is
      running.


    **Returns:**
    - time zone code in which the storefront is
      running.



---

### getTimezoneOffset()
- getTimezoneOffset(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns time zone offset in which the storefront is running.

    **Returns:**
    - time zone offset in which the storefront is running.


---

### isOMSEnabled()
- ~~isOMSEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Whether oms is active in the current site. This depends on a general
      property which states whether oms is active for the server,
      and a site-dependent preference whether oms is available for the current site.


    **Returns:**
    - whether oms is active in the site


---

### setCustomPreferenceValue(String, Object)
- setCustomPreferenceValue(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : The method sets a value for a custom preference. The type of the value
      must match with the declared type of the preference definition.


    **Parameters:**
    - name - name of the preference
    - value - new value for the preference


---

<!-- prettier-ignore-end -->

<!-- document id=13181a8aa70ae8fa7b8abf0cbd9638e5541bb5f2d944e6dc837f85bc5a76577c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.sitemap.SitemapFile.md -->

<!-- prettier-ignore-start -->
# Class SitemapFile

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.sitemap.SitemapFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md)

Instances of this class represent sitemap files located in the appservers shared file system. Methods are used to get
details of a sitemap file, such as the hostname it is associated with.



## Property Summary

| Property | Description |
| --- | --- |
| [fileName](#filename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the file e.g. |
| [fileSize](#filesize): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the size of the file in bytes. |
| [fileURL](#fileurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the URL used to access this file in a storefront request. |
| [hostName](#hostname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the host name this file is associated with. |
| [valid](#valid): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Checks if this instance of sitemap file is valid. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getFileName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md#getfilename)() | Returns the name of the file e.g. |
| [getFileSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md#getfilesize)() | Returns the size of the file in bytes. |
| [getFileURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md#getfileurl)() | Returns the URL used to access this file in a storefront request. |
| [getHostName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md#gethostname)() | Returns the host name this file is associated with. |
| [isValid](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md#isvalid)() | Checks if this instance of sitemap file is valid. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### fileName
- fileName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the file e.g. sitemap\_index.xml


---

### fileSize
- fileSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the size of the file in bytes.


---

### fileURL
- fileURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the URL used to access this file in a storefront request.


---

### hostName
- hostName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the host name this file is associated with.


---

### valid
- valid: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Checks if this instance of sitemap file is valid. Examples for invalid files are:
      
      - file size >10mb
      
      Additional violations might be added later.



---

## Method Details

### getFileName()
- getFileName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the file e.g. sitemap\_index.xml

    **Returns:**
    - The file's name, never `null`.


---

### getFileSize()
- getFileSize(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the file in bytes.

    **Returns:**
    - The fileSize in bytes.


---

### getFileURL()
- getFileURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the URL used to access this file in a storefront request.

    **Returns:**
    - The fileURL, never `null`.


---

### getHostName()
- getHostName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the host name this file is associated with.

    **Returns:**
    - The hostname, never `null`.


---

### isValid()
- isValid(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks if this instance of sitemap file is valid. Examples for invalid files are:
      
      - file size >10mb
      
      Additional violations might be added later.


    **Returns:**
    - `true` if the `SitemapFile` is valid, `false` otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=f99efe3b30921c98597e54887509fd3257a705d00784be558cf9a4549997a5ac url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.sitemap.SitemapMgr.md -->

<!-- prettier-ignore-start -->
# Class SitemapMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.sitemap.SitemapMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md)

[SitemapMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md) is used to access and modify custom sitemap files.


To access custom sitemap files, use methods [getCustomSitemapFiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#getcustomsitemapfiles).


To delete custom sitemap files, use methods [deleteCustomSitemapFile(SitemapFile)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#deletecustomsitemapfilesitemapfile),
[deleteCustomSitemapFiles(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#deletecustomsitemapfilesstring) and [deleteCustomSitemapFiles()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#deletecustomsitemapfiles).


To add custom sitemap files, use methods [addCustomSitemapFile(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#addcustomsitemapfilestring-file). The file will be copied from
WebDAV ([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) represent a file in WebDAV) to the appservers shared file system.


Please note that all provided methods are operating in appservers shared file system. These modifications are visible
via "Custom Sitemaps" tab under _Merchant Tools_ => _SEO_ => _Sitemaps - Custom Sitemaps_ in
Business Manager. To publish all changes, execute job under Merchant Tools => SEO => Sitemaps => Job.



## Property Summary

| Property | Description |
| --- | --- |
| [customSitemapFiles](#customsitemapfiles): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Reads all existing custom sitemap files from files system of the appservers custom sitemap directory into memory  and returns them in a Map containing mappings like  <ul>  <li>Hostname 1 => \[SitemapFile hostname1\_sitemapfile1, SitemapFile hostname1\_sitemapfile2\]</li>  <li>Hostname 2 => \[SitemapFile hostname2\_sitemapfile1\]</li>  </ul> |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [addCustomSitemapFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#addcustomsitemapfilestring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Adds the given [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) to the appservers custom sitemap directory. |
| static [deleteCustomSitemapFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#deletecustomsitemapfilesitemapfile)([SitemapFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md)) | Deletes the given custom sitemap file from the appservers shared file system. |
| static [deleteCustomSitemapFiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#deletecustomsitemapfiles)() | Deletes all custom sitemap files for all hostnames from the appservers shared file system. |
| static [deleteCustomSitemapFiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#deletecustomsitemapfilesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Deletes all custom sitemap files for the given hostname from the appservers shared file system. |
| static [getCustomSitemapFiles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#getcustomsitemapfiles)() | Reads all existing custom sitemap files from files system of the appservers custom sitemap directory into memory  and returns them in a Map containing mappings like  <ul>  <li>Hostname 1 => \[SitemapFile hostname1\_sitemapfile1, SitemapFile hostname1\_sitemapfile2\]</li>  <li>Hostname 2 => \[SitemapFile hostname2\_sitemapfile1\]</li>  </ul> |
| static [getSitemap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md#getsitemapstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Reads the content of the specified sitemap file and returns it as a String. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### customSitemapFiles
- customSitemapFiles: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Reads all existing custom sitemap files from files system of the appservers custom sitemap directory into memory
      and returns them in a Map containing mappings like
      
      - Hostname 1 =>\[SitemapFile hostname1\_sitemapfile1, SitemapFile hostname1\_sitemapfile2\]
      - Hostname 2 =>\[SitemapFile hostname2\_sitemapfile1\]



---

## Method Details

### addCustomSitemapFile(String, File)
- static addCustomSitemapFile(hostName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): void
  - : Adds the given [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) to the appservers custom sitemap directory. All content of the appservers
      custom sitemap directory is considered by the system job "Create Sitemap Schedule".
      
      
      The files are added to the directory which is accessible via "Custom Sitemaps" tab under _Merchant Tools_ =>
      _SEO_ => _Sitemaps - Custom Sitemaps_ in Business Manager. To publish that change, execute job under Merchant Tools => SEO => Sitemaps => Job.


    **Parameters:**
    - hostName - The hostName to copy the `File` to. The hostName must be configured in sites alias             file.
    - file - The `File` to copy.

    **Throws:**
    - Exception - 


---

### deleteCustomSitemapFile(SitemapFile)
- static deleteCustomSitemapFile(sitemapFile: [SitemapFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md)): void
  - : Deletes the given custom sitemap file from the appservers shared file system.
      
      
      The file is deleted from the directory which is accessible via "Custom Sitemaps" tab under _Merchant Tools_
      => _SEO_ => _Sitemaps - Custom Sitemaps_ in Business Manager. To publish that change, execute job under Merchant Tools => SEO => Sitemaps => Job.


    **Parameters:**
    - sitemapFile - - The sitemapFile to delete.


---

### deleteCustomSitemapFiles()
- static deleteCustomSitemapFiles(): void
  - : Deletes all custom sitemap files for all hostnames from the appservers shared file system.
      
      
      The files are deleted from the directory which is accessible via "Custom Sitemaps" tab under _Merchant
       Tools_ => _SEO_ => _Sitemaps - Custom Sitemaps_ in Business Manager. To publish that change, execute job under Merchant Tools => SEO => Sitemaps => Job.



---

### deleteCustomSitemapFiles(String)
- static deleteCustomSitemapFiles(hostName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Deletes all custom sitemap files for the given hostname from the appservers shared file system.
      
      
      The files are deleted from the directory which is accessible via "Custom Sitemaps" tab under _Merchant
       Tools_ => _SEO_ => _Sitemaps - Custom Sitemaps_ in Business Manager. To publish that change, execute job under Merchant Tools => SEO => Sitemaps => Job.


    **Parameters:**
    - hostName - The hostName to delete the custom sitemap files for.


---

### getCustomSitemapFiles()
- static getCustomSitemapFiles(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Reads all existing custom sitemap files from files system of the appservers custom sitemap directory into memory
      and returns them in a Map containing mappings like
      
      - Hostname 1 =>\[SitemapFile hostname1\_sitemapfile1, SitemapFile hostname1\_sitemapfile2\]
      - Hostname 2 =>\[SitemapFile hostname2\_sitemapfile1\]


    **Returns:**
    - The created map containing the list of SitemapFiles.


---

### getSitemap(String)
- static getSitemap(fileName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of the specified sitemap file and returns it as a String.
      
      
      The file is looked up in the shared sitemap directory for the current site,
      using the hostname from the current storefront request. If the file is not found
      in the new framework location (`.../sitemaps/<hostname>/`), the old
      location (`.../sitemaps/`) is used as a fallback.


    **Parameters:**
    - fileName - The name of the sitemap file to read (e.g. "sitemap\_index.xml").             Must not be `null`, empty, or contain path traversal sequences.

    **Returns:**
    - The sitemap file content as a String, or `null` if the fileName is
              invalid, the file does not exist, or the request context is unavailable.



---

<!-- prettier-ignore-end -->

<!-- document id=be8771616859468d2eee748e36e2b11aa2c0fc800a0a794645dc89591855c578 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.SitePreferences.md -->

<!-- prettier-ignore-start -->
# Class SitePreferences

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.system.SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md)

SitePreferences is a container for custom site-level attributes. The object
corresponds with system object type "SitePreferences". It has no system
attributes and exists only as a place for merchants to define custom
attributes which need to be available for each site.


Logically there is only one SitePreferences instance per site. The instance
is obtained by calling [Site.getPreferences()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md#getpreferences). Once an
instance of the container is obtained, it is possible to read/write site
preference values by using the usual syntax for
[ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md) instances. For example:


```
var sitePrefs : SitePreferences = dw.system.Site.getCurrent().getPreferences();
var mySitePrefValue : String = sitePrefs.getCustom()["mySitePref"];
```



**Note:** this class allows access to sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.


Commerce Cloud Digital defines many site-level preferences, relating to
baskets, timezone, locales, customers, etc, which can be managed within the
"Site Preferences" module of the Business Manager, but these preferences are
not accessible through this object. (SourceCodeURLParameterName is the one
exception to this rule.)



## Property Summary

| Property | Description |
| --- | --- |
| [sourceCodeURLParameterName](#sourcecodeurlparametername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the source code url paremeter configured for the  site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSourceCodeURLParameterName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md#getsourcecodeurlparametername)() | Returns the name of the source code url paremeter configured for the  site. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### sourceCodeURLParameterName
- sourceCodeURLParameterName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the source code url paremeter configured for the
      site.



---

## Method Details

### getSourceCodeURLParameterName()
- getSourceCodeURLParameterName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the source code url paremeter configured for the
      site.


    **Returns:**
    - source code url parameter name


---

<!-- prettier-ignore-end -->

<!-- document id=a1956e3d91501ac6628d6dca09990f51671119c77a4fd99cabf3f14a4d10dc66 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.SlotContent.md -->

<!-- prettier-ignore-start -->
# Class SlotContent

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.SlotContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md)

Represents content for a slot.


## Property Summary

| Property | Description |
| --- | --- |
| [calloutMsg](#calloutmsg): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the callout message for the slot. |
| [content](#content): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of content based on the content type  for the slot. |
| [custom](#custom): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the custom attributes for the slot. |
| [recommenderName](#recommendername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the recommender name for slot configurations of type 'Recommendation' |
| [slotID](#slotid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the unique slot ID. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCalloutMsg](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md#getcalloutmsg)() | Returns the callout message for the slot. |
| [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md#getcontent)() | Returns a collection of content based on the content type  for the slot. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md#getcustom)() | Returns the custom attributes for the slot. |
| [getRecommenderName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md#getrecommendername)() | Returns the recommender name for slot configurations of type 'Recommendation' |
| [getSlotID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md#getslotid)() | Returns the unique slot ID. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### calloutMsg
- calloutMsg: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the callout message for the slot.


---

### content
- content: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of content based on the content type
      for the slot. The collection will include one of the following
      types: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md), [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), or [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md).



---

### custom
- custom: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the custom attributes for the slot.


---

### recommenderName
- recommenderName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the recommender name for slot configurations of type 'Recommendation'


---

### slotID
- slotID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the unique slot ID.


---

## Method Details

### getCalloutMsg()
- getCalloutMsg(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the callout message for the slot.

    **Returns:**
    - Callout message of the slot.


---

### getContent()
- getContent(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of content based on the content type
      for the slot. The collection will include one of the following
      types: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md), [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md), [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md), or [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md).


    **Returns:**
    - All content of the slot.


---

### getCustom()
- getCustom(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the custom attributes for the slot.

    **Returns:**
    - Custom attributes of the slot.


---

### getRecommenderName()
- getRecommenderName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the recommender name for slot configurations of type 'Recommendation'

    **Returns:**
    - the recommender name for slot configurations of type 'Recommendation'


---

### getSlotID()
- getSlotID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the unique slot ID.

    **Returns:**
    - ID of the slot.


---

<!-- prettier-ignore-end -->

<!-- document id=1808fc09ebf48ff93ee2325ede27cf2e4e41c01e02511bea1360aa7a347aadc2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.SOAPService.md -->

<!-- prettier-ignore-start -->
# Class SOAPService

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)
    - [dw.svc.SOAPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md)

Represents a SOAP WebService.


## Property Summary

| Property | Description |
| --- | --- |
| [authentication](#authentication): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the authentication type. |
| [serviceClient](#serviceclient): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md) | Returns the serviceClient object. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md#getauthentication)() | Returns the authentication type. |
| [getServiceClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md#getserviceclient)() | Returns the serviceClient object. |
| [setAuthentication](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md#setauthenticationstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the type of authentication. |
| [setServiceClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md#setserviceclientobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the serviceClient object. |

### Methods inherited from class Service

[call](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#callobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getconfiguration), [getCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getcredentialid), [getRequestData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getrequestdata), [getResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#getresponse), [getURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#geturl), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#isthrowonerror), [setCredentialID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setcredentialidstring), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#setthrowonerror), [setURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md#seturlstring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### authentication
- authentication: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the authentication type.


---

### serviceClient
- serviceClient: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the serviceClient object.


---

## Method Details

### getAuthentication()
- getAuthentication(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the authentication type.

    **Returns:**
    - Authentication type.


---

### getServiceClient()
- getServiceClient(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the serviceClient object.

    **Returns:**
    - serviceClient object.


---

### setAuthentication(String)
- setAuthentication(authentication: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SOAPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md)
  - : Sets the type of authentication. Valid values include "BASIC" and "NONE".
      
      
      The default value is BASIC.


    **Parameters:**
    - authentication - Type of authentication.

    **Returns:**
    - this SOAP WebService.


---

### setServiceClient(Object)
- setServiceClient(o: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SOAPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md)
  - : Sets the serviceClient object. This must be set in the prepareCall method, prior to execute being called.

    **Parameters:**
    - o - serviceClient object.

    **Returns:**
    - this SOAP WebService.


---

<!-- prettier-ignore-end -->

<!-- document id=25e209227924908c28d32044f28aa94b7a01a749ae424070a724d8987edb80fd url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.SOAPServiceDefinition.md -->

<!-- prettier-ignore-start -->
# Class SOAPServiceDefinition

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.svc.ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)
    - [dw.svc.SOAPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPServiceDefinition.md)

Represents a SOAP WebService definition.

**Deprecated:**
**warning:** This class is only used with the deprecated [ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md). Use the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)
            instead, which allows configuration on the [SOAPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md) directly.
**API Version:**
**note:** No longer available as of version 19.10.

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

### Methods inherited from class ServiceDefinition

[configure](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#configureobject), [getConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getconfiguration), [getServiceName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#getservicename), [isMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#ismock), [isThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#isthrowonerror), [setMock](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setmock), [setThrowOnError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md#setthrowonerror)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
<!-- prettier-ignore-end -->

<!-- document id=1ee298e722f293ea7d523416d4bd945c0a6f943fb461f447c51ae959d4f13324 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.rpc.SOAPUtil.md -->

<!-- prettier-ignore-start -->
# Class SOAPUtil

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.rpc.SOAPUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md)

Utility class for working with SOAP web services.  This class provides
methods for setting SOAP headers and a set of constants representing the
supported header names.

If you want to use ws-security features, such as signing and encryption,
with your RPC-style SOAP web service, use this class to construct a HashMap with
security constants and values.

**Note:** this method handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.
The following example configures the ws-security actions taken for the request and response to a web service.
 

```
importPackage( dw.system );
importPackage( dw.util );
importPackage( dw.rpc );


function execute( args : PipelineDictionary ) : Number
{
    var WSU_NS : String = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";

    try
    {

    // define a map with all the secrets
    var secretsMap   : Map = new HashMap();
    secretsMap.put("myclientkey", "ckpass");
    secretsMap.put("myservicekey", "ckpass");
    secretsMap.put("username", "password");

    var requestCfg   : Map = new HashMap();

    // define the ws actions to be performed
    requestCfg.put(SOAPUtil.WS_ACTION, SOAPUtil.WS_USERNAME_TOKEN + " " +
                                       SOAPUtil.WS_TIMESTAMP + " " +
                                       SOAPUtil.WS_SIGNATURE + " " +
                                       SOAPUtil.WS_ENCRYPT);
    requestCfg.put(SOAPUtil.WS_USER, "username");
    requestCfg.put(SOAPUtil.WS_PASSWORD_TYPE, SOAPUtil.WS_PW_DIGEST );
    requestCfg.put(SOAPUtil.WS_SIG_DIGEST_ALGO, "http://www.w3.org/2001/04/xmlenc#sha256" );

    // define signature properties
    // the keystore file has the basename of the WSDL file and the
    // file extension based on the keystore type (e.g. HelloWorld.jks).
    // The keystore file has to be placed beside the WSDL file.
    requestCfg.put(SOAPUtil.WS_SIG_PROP_KEYSTORE_TYPE, "jks");
    requestCfg.put(SOAPUtil.WS_SIG_PROP_KEYSTORE_PW, "cspass");
    requestCfg.put(SOAPUtil.WS_SIG_PROP_KEYSTORE_ALIAS, "myclientkey");

    requestCfg.put(SOAPUtil.WS_SIGNATURE_USER, "myclientkey");

    // define enrcryption properties
    requestCfg.put(SOAPUtil.WS_ENC_PROP_KEYSTORE_TYPE, "jks");
    requestCfg.put(SOAPUtil.WS_ENC_PROP_KEYSTORE_PW, "cspass");
    requestCfg.put(SOAPUtil.WS_ENC_PROP_KEYSTORE_ALIAS, "myservicekey");

    requestCfg.put(SOAPUtil.WS_ENCRYPTION_USER, "myservicekey");
    requestCfg.put(SOAPUtil.WS_SIGNATURE_PARTS, "{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body");
    requestCfg.put(SOAPUtil.WS_ENCRYPTION_PARTS,"{Element}{" + WSU_NS + "}
     Timestamp;"+"{Content}{http://schemas.xmlsoap.org/soap/envelope/}Body");

    // set the secrets for the callback
    requestCfg.put(SOAPUtil.WS_SECRETS_MAP, secretsMap);

    var responseCfg : Map = new HashMap();

    // define the ws actions to be performed for the response
    responseCfg.put(SOAPUtil.WS_ACTION, SOAPUtil.WS_TIMESTAMP + " " +
                                        SOAPUtil.WS_SIGNATURE + " " +
                                        SOAPUtil.WS_ENCRYPT);

    // define signature properties
    responseCfg.put(SOAPUtil.WS_SIG_PROP_KEYSTORE_TYPE, "jks");
    responseCfg.put(SOAPUtil.WS_SIG_PROP_KEYSTORE_PW, "cspass");
    responseCfg.put(SOAPUtil.WS_SIG_PROP_KEYSTORE_ALIAS, "myservicekey");

    responseCfg.put(SOAPUtil.WS_SIGNATURE_USER, "myservicekey");

    // define decryption properties
    responseCfg.put(SOAPUtil.WS_ENC_PROP_KEYSTORE_TYPE, "jks");
    responseCfg.put(SOAPUtil.WS_ENC_PROP_KEYSTORE_PW, "cspass");
    responseCfg.put(SOAPUtil.WS_ENC_PROP_KEYSTORE_ALIAS, "myclientkey");

    responseCfg.put(SOAPUtil.WS_ENCRYPTION_USER, "myclientkey");

    // set the secrets for the callback
    responseCfg.put(SOAPUtil.WS_SECRETS_MAP, secretsMap);

    // get the service and stub
    var helloWorldService : WebReference = webreferences.HelloWorld;
    var stub : Stub = helloWorldService.defaultService;
    // set the security
    SOAPUtil.setWSSecurityConfig(stub, requestCfg, responseCfg);
        //var h : Hello = new helloWorldService.Hello();
        var h = new helloWorldService.com.support.ws.security.test.Hello2();

        h.setName('Send Text from client Axis ...');

        // call the web service
        var response  = stub.hello2(h);
        //var response = stub.hello(h);
        var result = response.getHello2Return();


    args.OutStr = result;
    Logger.error("Hello World We Are SIGNED old version Send Text from client ...", result);

    return PIPELET_NEXT;

    }
    catch (e)
    {
        Logger.error("Error in helloWorldRpc.ds is: " + e);
        return PIPELET_ERROR;
    }

}
```


**See Also:**
- [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)
- [WebReference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.WebReference.md)

**Deprecated:**
**warning:** This class is deprecated, please use webreferences2 instead (see also [WSUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md)).

## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[WS_ACTION](#ws_action): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "action"~~ | WS-Security action property name. |
| ~~[WS_ENCRYPT](#ws_encrypt): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Encrypt"~~ | WS-Security action: encrypt the message. |
| ~~[WS_ENCRYPTION_PARTS](#ws_encryption_parts): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionParts"~~ | WS-Security encryption: defines which parts of the request are encrypted. |
| ~~[WS_ENCRYPTION_USER](#ws_encryption_user): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionUser"~~ | WS-Security encryption: the user's name for encryption. |
| ~~[WS_ENC_PROP_KEYSTORE_ALIAS](#ws_enc_prop_keystore_alias): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreAlias"~~ | WS-Security encryption: the encryption/decryption keystore alias name |
| ~~[WS_ENC_PROP_KEYSTORE_PW](#ws_enc_prop_keystore_pw): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystorePassword"~~ | WS-Security encryption: the encryption/decryption keystore password |
| ~~[WS_ENC_PROP_KEYSTORE_TYPE](#ws_enc_prop_keystore_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreType"~~ | WS-Security encryption: the encryption/decryption keystore type ( jks or pkcs12 ),                          default is jks. |
| ~~[WS_NO_SECURITY](#ws_no_security): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NoSecurity"~~ | WS-Security action: no security |
| ~~[WS_PASSWORD_TYPE](#ws_password_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "passwordType"~~ | WS-Security password type: parameter for UsernameToken action to define the encoding  of the password. |
| ~~[WS_PW_DIGEST](#ws_pw_digest): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordDigest"~~ | WS-Security password of type digest: use a password digest to send the password information. |
| ~~[WS_PW_TEXT](#ws_pw_text): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordText"~~ | WS-Security password of type text: send the password information in clear text. |
| ~~[WS_SECRETS_MAP](#ws_secrets_map): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SecretsMap"~~ | A secrets map with the username/password entries is needed to create the password  callback object. |
| ~~[WS_SIGNATURE](#ws_signature): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Signature"~~ | WS-Security action: sign the message. |
| ~~[WS_SIGNATURE_PARTS](#ws_signature_parts): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureParts"~~ | WS-Security signature: defines which parts of the request are signed. |
| ~~[WS_SIGNATURE_USER](#ws_signature_user): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureUser"~~ | WS-Security signature: the user's name for signature. |
| ~~[WS_SIG_DIGEST_ALGO](#ws_sig_digest_algo): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureDigestAlgorithm"~~ | WS-Security signature: sets the signature digest algorithm to use. |
| ~~[WS_SIG_PROP_KEYSTORE_ALIAS](#ws_sig_prop_keystore_alias): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreAlias"~~ | WS-Security signature: the signature keystore alias name |
| ~~[WS_SIG_PROP_KEYSTORE_PW](#ws_sig_prop_keystore_pw): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystorePassword"~~ | WS-Security signature: the signature keystore password. |
| ~~[WS_SIG_PROP_KEYSTORE_TYPE](#ws_sig_prop_keystore_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreType"~~ | WS-Security: the signature keystore type ( jks or pkcs12 ). |
| ~~[WS_TIMESTAMP](#ws_timestamp): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Timestamp"~~ | WS-Security action: add a timestamp to the security header. |
| ~~[WS_USER](#ws_user): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "user"~~ | WS-Security user name. |
| ~~[WS_USERNAME_TOKEN](#ws_username_token): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UsernameToken"~~ | WS-Security action: add a UsernameToken identification. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SOAPUtil](#soaputil)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| ~~static [getHTTPRequestHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#gethttprequestheaderobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns an HTTP request header property value using the specified key. |
| ~~static [getHTTPResponseHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#gethttpresponseheaderobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns an HTTP response header property value using the specified key. |
| ~~static [setHTTPRequestHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#sethttprequestheaderobject-string-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets an HTTP request header property using the specified key and value. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets a new SOAPHeaderElement in the SOAP request with the namespace of  the XML content. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string-boolean)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))~~ | Sets a new SOAPHeaderElement in the SOAP request  with the namespace of  the XML content. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string-string-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | Creates a new SOAPHeaderElement with the name and namespace and places  the given XML into it. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string-string-object-boolean)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))~~ | Creates a new SOAPHeaderElement with the name and namespace and places  the given XML into it. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string-string-object-boolean-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Creates a new SOAPHeaderElement with the name and namespace and places  the given XML into it. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string-string-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Creates a new SOAPHeaderElement with the name and namespace and places  the given XML into it. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string-string-string-boolean)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))~~ | Creates a new SOAPHeaderElement with the name and namespace and places  the given XML into it. |
| ~~static [setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setheaderobject-string-string-string-boolean-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Creates a new SOAPHeaderElement with the name and namespace and places  the given XML into it. |
| ~~static [setWSSecurityConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md#setwssecurityconfigobject-object-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | Sets the WS-Security configuration for the request and response based on the  constants defined. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### WS_ACTION

- ~~WS_ACTION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "action"~~
  - : WS-Security action property name.
      Allowed property values are WS\_NO\_SECURITY, WS\_TIMESTAMP, WS\_ENCRYPT, WS\_SIGNATURE, WS\_USERNAME\_TOKEN or
      a space separated String with multiple values.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_ENCRYPT

- ~~WS_ENCRYPT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Encrypt"~~
  - : WS-Security action: encrypt the message.
      The encryption-specific parameters define how to encrypt, which keys
      to use, and other parameters.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_ENCRYPTION_PARTS

- ~~WS_ENCRYPTION_PARTS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionParts"~~
  - : WS-Security encryption: defines which parts of the request are encrypted.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_ENCRYPTION_USER

- ~~WS_ENCRYPTION_USER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionUser"~~
  - : WS-Security encryption: the user's name for encryption.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_ENC_PROP_KEYSTORE_ALIAS

- ~~WS_ENC_PROP_KEYSTORE_ALIAS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreAlias"~~
  - : WS-Security encryption: the encryption/decryption keystore alias name

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_ENC_PROP_KEYSTORE_PW

- ~~WS_ENC_PROP_KEYSTORE_PW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystorePassword"~~
  - : WS-Security encryption: the encryption/decryption keystore password

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_ENC_PROP_KEYSTORE_TYPE

- ~~WS_ENC_PROP_KEYSTORE_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreType"~~
  - : WS-Security encryption: the encryption/decryption keystore type ( jks or pkcs12 ),
                              default is jks.
      
      **Note:** the keystore file must have the basename of the WSDL file and the
      file extension based on the keystore type. For example: MyService.jks.
      The keystore file must be placed in the same cartridge directory
      as the WSDL file.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_NO_SECURITY

- ~~WS_NO_SECURITY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NoSecurity"~~
  - : WS-Security action: no security

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_PASSWORD_TYPE

- ~~WS_PASSWORD_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "passwordType"~~
  - : WS-Security password type: parameter for UsernameToken action to define the encoding
      of the password. Allowed values are PW\_DIGEST or PW\_TEXT.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_PW_DIGEST

- ~~WS_PW_DIGEST: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordDigest"~~
  - : WS-Security password of type digest: use a password digest to send the password information.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_PW_TEXT

- ~~WS_PW_TEXT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordText"~~
  - : WS-Security password of type text: send the password information in clear text.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SECRETS_MAP

- ~~WS_SECRETS_MAP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SecretsMap"~~
  - : A secrets map with the username/password entries is needed to create the password
      callback object.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SIGNATURE

- ~~WS_SIGNATURE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Signature"~~
  - : WS-Security action: sign the message.
      The signature-specific parameters define how to sign, which keys
      to use, and other parameters.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SIGNATURE_PARTS

- ~~WS_SIGNATURE_PARTS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureParts"~~
  - : WS-Security signature: defines which parts of the request are signed.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SIGNATURE_USER

- ~~WS_SIGNATURE_USER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureUser"~~
  - : WS-Security signature: the user's name for signature.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SIG_DIGEST_ALGO

- ~~WS_SIG_DIGEST_ALGO: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureDigestAlgorithm"~~
  - : WS-Security signature: sets the signature digest algorithm to use.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SIG_PROP_KEYSTORE_ALIAS

- ~~WS_SIG_PROP_KEYSTORE_ALIAS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreAlias"~~
  - : WS-Security signature: the signature keystore alias name

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SIG_PROP_KEYSTORE_PW

- ~~WS_SIG_PROP_KEYSTORE_PW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystorePassword"~~
  - : WS-Security signature: the signature keystore password.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_SIG_PROP_KEYSTORE_TYPE

- ~~WS_SIG_PROP_KEYSTORE_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreType"~~
  - : WS-Security: the signature keystore type ( jks or pkcs12 ). The default is jks.
      
      **Note:** The keystore file must have the basename of the WSDL file and the
      file extension of the keystore type. For example: MyService.jks.
      The keystore file must be placed in the same cartridge directory
      as the WSDL file.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_TIMESTAMP

- ~~WS_TIMESTAMP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Timestamp"~~
  - : WS-Security action: add a timestamp to the security header.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_USER

- ~~WS_USER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "user"~~
  - : WS-Security user name.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### WS_USERNAME_TOKEN

- ~~WS_USERNAME_TOKEN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UsernameToken"~~
  - : WS-Security action: add a UsernameToken identification.

    **Deprecated:**
**warning:** use webreferences2 instead

---

## Constructor Details

### SOAPUtil()
- SOAPUtil()
  - : 


---

## Method Details

### getHTTPRequestHeader(Object, String)
- ~~static getHTTPRequestHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns an HTTP request header property value using the specified key. Null is returned
      if the key does not represent an HTTP header property.


    **Parameters:**
    - svc - a service stub returned from getService().
    - key - the header property key.

    **Returns:**
    - an HTTP request header property value using the specified key or null.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### getHTTPResponseHeader(Object, String)
- ~~static getHTTPResponseHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns an HTTP response header property value using the specified key. Null is returned
      if the key does not represent an HTTP response header property.


    **Parameters:**
    - svc - a service stub returned from getService().
    - key - the header property key.

    **Returns:**
    - an HTTP response header property value using the specified key or null.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHTTPRequestHeader(Object, String, String)
- ~~static setHTTPRequestHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets an HTTP request header property using the specified key and value.

    **Parameters:**
    - svc - a service stub returned from getService().
    - key - the header property key.
    - value - the header property value. If the value is null, the property  identified by the key is removed from the HTTP request header.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), xml: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets a new SOAPHeaderElement in the SOAP request with the namespace of
      the XML content.


    **Parameters:**
    - svc - a service stub returned from getService()
    - xml - a string with arbitrary XML content

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String, Boolean)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), xml: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), mustUnderstand: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void~~
  - : Sets a new SOAPHeaderElement in the SOAP request  with the namespace of
      the XML content.


    **Parameters:**
    - svc - a service stub returned from getService()
    - xml - a string with arbitrary XML content
    - mustUnderstand - sets the SOAP header attribute 'mustUnderstand'

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String, String, Object)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), namespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), xml: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void~~
  - : Creates a new SOAPHeaderElement with the name and namespace and places
      the given XML into it.


    **Parameters:**
    - svc - a service stub returned from getService()
    - namespace - the namespace of the header element
    - name - the element name for the header element
    - xml - a E4X XML object

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String, String, Object, Boolean)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), namespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), xml: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), mustUnderstand: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void~~
  - : Creates a new SOAPHeaderElement with the name and namespace and places
      the given XML into it.


    **Parameters:**
    - svc - a service stub returned from getService()
    - namespace - the namespace of the header element
    - name - the element name for the header element
    - xml - a E4X XML object
    - mustUnderstand - sets the SOAP header attribute mustUnderstand

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String, String, Object, Boolean, String)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), namespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), xml: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), mustUnderstand: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), actor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Creates a new SOAPHeaderElement with the name and namespace and places
      the given XML into it.
      
      
      ```
      var usernameToken : XML =
        <wsse:UsernameToken xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:Username>{merchantID}</wsse:Username>
            <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">
                {merchantPassword}
            </wsse:Password>
        </wsse:UsernameToken>
      SOAPUtil.setHeader( service, "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd",
       "Security", usernameToken, true, null
      ```


    **Parameters:**
    - svc - a service stub returned from getService()
    - namespace - the namespace of the header element
    - name - the element name for the header element
    - xml - a E4X XML object
    - mustUnderstand - sets the SOAP header attribute 'mustUnderstand'
    - actor - the SOAP actor, which should be set for this header element. null removes any actor.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String, String, String)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), namespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), xml: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Creates a new SOAPHeaderElement with the name and namespace and places
      the given XML into it.


    **Parameters:**
    - svc - a service stub returned from getService()
    - namespace - the namespace of the header element
    - name - the element name for the header element
    - xml - a string with arbitrary XML content

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String, String, String, Boolean)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), namespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), xml: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), mustUnderstand: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void~~
  - : Creates a new SOAPHeaderElement with the name and namespace and places
      the given XML into it.


    **Parameters:**
    - svc - a service stub returned from getService()
    - namespace - the namespace of the header element
    - name - the element name for the header element
    - xml - a string with arbitrary XML content
    - mustUnderstand - sets the SOAP header attribute mustUnderstand

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(Object, String, String, String, Boolean, String)
- ~~static setHeader(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), namespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), xml: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), mustUnderstand: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), actor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Creates a new SOAPHeaderElement with the name and namespace and places
      the given XML into it.


    **Parameters:**
    - svc - a service stub returned from getService()
    - namespace - the namespace of the header element
    - name - the element name for the header element
    - xml - a string with arbitrary XML content
    - mustUnderstand - sets the SOAP header attribute mustUnderstand
    - actor - the SOAP actor, which should be set for this header element. null removes any actor.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setWSSecurityConfig(Object, Object, Object)
- ~~static setWSSecurityConfig(svc: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), requestConfigMap: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), responseConfigMap: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void~~
  - : Sets the WS-Security configuration for the request and response based on the
      constants defined.


    **Parameters:**
    - svc - a service stub returned from getService()
    - requestConfigMap - the WS-Security request config
    - responseConfigMap - the WS-Security response config

    **Deprecated:**
**warning:** use webreferences2 instead

---

<!-- prettier-ignore-end -->

<!-- document id=801b3500b1b6bf1b02c8dc2417371eb8abd8697a1d9b721b8cb29252b20859b2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.SortedMap.md -->

<!-- prettier-ignore-start -->
# Class SortedMap

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
    - [dw.util.SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)

A map that further guarantees that it will be in ascending key order,
sorted according to the natural ordering of its keys,
or by a comparator provided at sorted map creation time. This order is reflected
when iterating over the sorted map's collection views (returned by the entrySet,
keySet and values methods).
Note that sorting by natural order is only supported for Number,
String, Date, Money and Quantity as key.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SortedMap](#sortedmap)() | Constructor to create a new SortedMap. |
| [SortedMap](#sortedmapobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructor to create a new SortedMap. |

## Method Summary

| Method | Description |
| --- | --- |
| [clone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md#clone)() | Returns a shallow copy of this map. |
| [firstKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md#firstkey)() | Returns the first (lowest) key currently in this sorted map. |
| [headMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md#headmapobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a view of the portion of this map whose keys are strictly less than toKey. |
| [lastKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md#lastkey)() | Returns the last (highest) key currently in this sorted map. |
| [subMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md#submapobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a view of the portion of this map whose keys range from fromKey, inclusive,  to toKey, exclusive. |
| [tailMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md#tailmapobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a view of the portion of this map whose keys are greater than or equal  to fromKey. |

### Methods inherited from class Map

[clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#clear), [containsKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containskeyobject), [containsValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#containsvalueobject), [entrySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#entryset), [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getobject), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#isempty), [keySet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#keyset), [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putobject-object), [putAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#putallmap), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#removeobject), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#size), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-1), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md#values---variant-2)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### SortedMap()
- SortedMap()
  - : Constructor to create a new SortedMap.


---

### SortedMap(Object)
- SortedMap(comparator: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructor to create a new SortedMap.
      
      The constructor takes a compare function as additional parameter. This comparator
      determines identity and the order of the element keys for this map.
      The order of the elements is determined with a comparator (see [PropertyComparator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.PropertyComparator.md))
      or with the help of the given function. The function must take two parameters
      and return a value <=-1 if the first parameter is smaller than the second,
      a value if >=1 if the first one is greater than the second parameter
      and a value in between like 0 if both are equal.


    **Parameters:**
    - comparator - an instance of a PropertyComparator or a comparison function


---

## Method Details

### clone()
- clone(): [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)
  - : Returns a shallow copy of this map.

    **Returns:**
    - a shallow copy of this map.


---

### firstKey()
- firstKey(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the first (lowest) key currently in this sorted map.

    **Returns:**
    - the first (lowest) key currently in this sorted map.


---

### headMap(Object)
- headMap(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)
  - : Returns a view of the portion of this map whose keys are strictly less than toKey.

    **Parameters:**
    - key - high endpoint (exclusive) of the headMap.

    **Returns:**
    - a view of the portion of this map whose keys are strictly less than toKey.


---

### lastKey()
- lastKey(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the last (highest) key currently in this sorted map.

    **Returns:**
    - the last (highest) key currently in this sorted map.


---

### subMap(Object, Object)
- subMap(from: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), to: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)
  - : Returns a view of the portion of this map whose keys range from fromKey, inclusive,
      to toKey, exclusive. (If fromKey and toKey are equal, the returned sorted map is empty.)


    **Parameters:**
    - from - low endpoint (inclusive) of the subMap.
    - to - high endpoint (exclusive) of the subMap.

    **Returns:**
    - a view of the portion of this map whose keys range from fromKey, inclusive, to toKey, exclusive.


---

### tailMap(Object)
- tailMap(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)
  - : Returns a view of the portion of this map whose keys are greater than or equal
      to fromKey. The returned sorted map is backed by this map, so changes in the
      returned sorted map are reflected in this map, and vice-versa. The returned
      sorted map supports all optional map operations.


    **Parameters:**
    - key - low endpoint (inclusive) of the tailMap.

    **Returns:**
    - a view of the portion of this map whose keys are greater than or equal to fromKey.


---

<!-- prettier-ignore-end -->

<!-- document id=1c394065f30178474df0fab91e55bb4388e263a726cd85bc6839fcad23ecb6f2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.SortedSet.md -->

<!-- prettier-ignore-start -->
# Class SortedSet

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
    - [dw.util.Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)
      - [dw.util.SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)

A set that further guarantees that its iterator
will traverse the set in ascending element order,
sorted according to the natural ordering of its
elements (only supported for Number, String,
Date, Money and Quantity), or by a comparator
provided at sorted set creation time.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SortedSet](#sortedset)() | Constructor to create a new SortedSet. |
| [SortedSet](#sortedsetobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructor to create a new SortedSet. |
| [SortedSet](#sortedsetcollection)([Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)) | Constructor for a new SortedSet. |

## Method Summary

| Method | Description |
| --- | --- |
| [clone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md#clone)() | Returns a shallow copy of this set. |
| [first](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md#first)() | Returns the first (lowest) element currently in this sorted set. |
| [headSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md#headsetobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a view of the portion of this sorted set whose elements  are strictly less than toElement. |
| [last](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md#last)() | Returns the last (highest) element currently in this sorted set. |
| [subSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md#subsetobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a view of the portion of this sorted set whose elements  range from fromElement, inclusive, to toElement, exclusive. |
| [tailSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md#tailsetobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a view of the portion of this sorted set whose elements  are greater than or equal to fromElement. |

### Methods inherited from class Collection

[add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addobject), [add1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#add1object), [addAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#addallcollection), [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#clear), [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsobject), [containsAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#containsallcollection), [getLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#getlength), [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#isempty), [iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#iterator), [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeobject), [removeAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#removeallcollection), [retainAll](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#retainallcollection), [size](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#size), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarray), [toArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md#toarraynumber-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### SortedSet()
- SortedSet()
  - : Constructor to create a new SortedSet.


---

### SortedSet(Object)
- SortedSet(comparator: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructor to create a new SortedSet.
      
      The constructor takes a compare function as additional parameter. This comparator
      determines identity and the order of the elements for this set.
      The order of the elements is determined with a comparator (see [PropertyComparator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.PropertyComparator.md))
      or with the help of the given function. The function must take two parameters
      and return a value <=-1 if the first parameter is smaller than the second,
      a value if >=1 if the first one is greater than the second parameter
      and a value in between like 0 if both are equal.


    **Parameters:**
    - comparator - an instance of a PropertyComparator or a comparison function


---

### SortedSet(Collection)
- SortedSet(collection: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md))
  - : Constructor for a new SortedSet. The constructor
      initializes the SortedSet with the elements of the
      given collection.


    **Parameters:**
    - collection - the collection of objects that are  inserted into the set.


---

## Method Details

### clone()
- clone(): [SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)
  - : Returns a shallow copy of this set.

    **Returns:**
    - a shallow copy of this set.


---

### first()
- first(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the first (lowest) element currently in this sorted set.

    **Returns:**
    - the first (lowest) element currently in this sorted set.


---

### headSet(Object)
- headSet(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)
  - : Returns a view of the portion of this sorted set whose elements
      are strictly less than toElement. The returned sorted set is
      backed by this sorted set, so changes in the returned sorted
      set are reflected in this sorted set, and vice-versa. The returned
      sorted set supports all optional set operations.


    **Parameters:**
    - key - high endpoint (exclusive) of the headSet.

    **Returns:**
    - a view of the specified initial range of this sorted set.


---

### last()
- last(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the last (highest) element currently in this sorted set.

    **Returns:**
    - the last (highest) element currently in this sorted set.


---

### subSet(Object, Object)
- subSet(from: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), to: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)
  - : Returns a view of the portion of this sorted set whose elements
      range from fromElement, inclusive, to toElement, exclusive. (If
      fromElement and toElement are equal, the returned sorted set is empty.)
      The returned sorted set is backed by this sorted set, so changes in
      the returned sorted set are reflected in this sorted set, and vice-versa.
      The returned sorted set supports all optional set operations that this
      sorted set supports.


    **Parameters:**
    - from - low endpoint (inclusive) of the subSet.
    - to - high endpoint (exclusive) of the subSet.

    **Returns:**
    - a view of the specified range within this sorted set.


---

### tailSet(Object)
- tailSet(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)
  - : Returns a view of the portion of this sorted set whose elements
      are greater than or equal to fromElement. The returned sorted set
      is backed by this sorted set, so changes in the returned sorted
      set are reflected in this sorted set, and vice-versa. The returned
      sorted set supports all optional set operations.


    **Parameters:**
    - key - low endpoint (inclusive) of the tailSet.

    **Returns:**
    - a view of the specified final range of this sorted set.


---

<!-- prettier-ignore-end -->

<!-- document id=b84dd83c108c68a4065f953cafc7a9fb26bb341fd2a143af9e8e4bb5944da634 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.SortingOption.md -->

<!-- prettier-ignore-start -->
# Class SortingOption

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.catalog.SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)

Represents an option for how to sort products in storefront search results.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the sorting option. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the description of the sorting option for the current locale. |
| [displayName](#displayname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the display name of the of the sorting option for the current locale. |
| [sortingRule](#sortingrule): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md) `(read-only)` | Returns the sorting rule for this sorting option,  or `null` if there is no associated rule. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md#getdescription)() | Returns the description of the sorting option for the current locale. |
| [getDisplayName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md#getdisplayname)() | Returns the display name of the of the sorting option for the current locale. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md#getid)() | Returns the ID of the sorting option. |
| [getSortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md#getsortingrule)() | Returns the sorting rule for this sorting option,  or `null` if there is no associated rule. |

### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the sorting option.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the description of the sorting option for the current locale.


---

### displayName
- displayName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the display name of the of the sorting option for the current locale.


---

### sortingRule
- sortingRule: [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md) `(read-only)`
  - : Returns the sorting rule for this sorting option,
      or `null` if there is no associated rule.



---

## Method Details

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the description of the sorting option for the current locale.

    **Returns:**
    - The value of the property for the current locale, or null if it
              wasn't found.



---

### getDisplayName()
- getDisplayName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the display name of the of the sorting option for the current locale.

    **Returns:**
    - The value of the property for the current locale, or null if it
              wasn't found.



---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the sorting option.

    **Returns:**
    - sorting option ID


---

### getSortingRule()
- getSortingRule(): [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)
  - : Returns the sorting rule for this sorting option,
      or `null` if there is no associated rule.


    **Returns:**
    - a ProductSortingRule instance representing the rule
      for this option or null.



---

<!-- prettier-ignore-end -->

<!-- document id=d222ebd8c2024549badc372e9e1a753c2d757ebc36e0c0904ea7ccba6ef980c6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.SortingRule.md -->

<!-- prettier-ignore-start -->
# Class SortingRule

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.catalog.SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)

Represents a product sorting rule for use with the [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md).


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the sorting rule. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md#getid)() | Returns the ID of the sorting rule. |

### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the sorting rule.


---

## Method Details

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the sorting rule.

    **Returns:**
    - sorting rule ID


---

<!-- prettier-ignore-end -->

<!-- document id=d8fdee771bb674a06bffd5fa329ae874324e63301015ffb5472de43a2027fdad url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.SourceCodeGroup.md -->

<!-- prettier-ignore-start -->
# Class SourceCodeGroup

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.campaign.SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md)

A source code group defines a collection of source codes. Source code groups
are generally pattern based and any source code satisfying the pattern
belongs to the group. In this way, merchants may define a large set of source
codes which qualify a customer for site experiences (different prices, for
example), which customers without that source code do not receive.
The class [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md) represents an individual source
code.



## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The ID of the SourceCodeGroup. |
| [priceBooks](#pricebooks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a Collection of PriceBooks the SourceCodeGroup is assigned to. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md#getid)() | The ID of the SourceCodeGroup. |
| [getPriceBooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md#getpricebooks)() | Returns a Collection of PriceBooks the SourceCodeGroup is assigned to. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The ID of the SourceCodeGroup.


---

### priceBooks
- priceBooks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a Collection of PriceBooks the SourceCodeGroup is assigned to.


---

## Method Details

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The ID of the SourceCodeGroup.

    **Returns:**
    - the ID.


---

### getPriceBooks()
- getPriceBooks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a Collection of PriceBooks the SourceCodeGroup is assigned to.

    **Returns:**
    - Collection of PriceBooks the SourceCodeGroup is assigned to.


---

<!-- prettier-ignore-end -->

<!-- document id=59a9e1f8a4d138fa7d11d53119e22af273094007c730c7eb9969d7c80c6ce0c2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.SourceCodeInfo.md -->

<!-- prettier-ignore-start -->
# Class SourceCodeInfo

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md)

Class representing a code (i.e. a "source code") that has been applied to a
customer's session. Source codes can qualify customers for different
campaigns, promotions, and other site experiences from those that the typical
customer sees. Codes are organized into source code groups.


Typically, a code is applied to a customer's session automatically by
Commerce Cloud Digital when a customer accesses a Digital URL with a well
known request parameter in the querystring.  A code may also be explicitly
applied to a customer session using the `SetSourceCode`
pipelet.



## Constant Summary

| Constant | Description |
| --- | --- |
| [STATUS_ACTIVE](#status_active): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | The literal source-code is found and currently active. |
| [STATUS_INACTIVE](#status_inactive): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | The literal source-code is found but not active. |
| [STATUS_INVALID](#status_invalid): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | The literal source-code is not found in the system. |

## Property Summary

| Property | Description |
| --- | --- |
| [code](#code): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | The literal source-code. |
| [group](#group): [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md) `(read-only)` | The associated source-code group. |
| [redirect](#redirect): [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md) `(read-only)` | Retrieves the redirect information from the last processed SourceCodeGroup (active or inactive). |
| [status](#status): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | The status of the source-code. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md#getcode)() | The literal source-code. |
| [getGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md#getgroup)() | The associated source-code group. |
| [getRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md#getredirect)() | Retrieves the redirect information from the last processed SourceCodeGroup (active or inactive). |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md#getstatus)() | The status of the source-code. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### STATUS_ACTIVE

- STATUS_ACTIVE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : The literal source-code is found and currently active.


---

### STATUS_INACTIVE

- STATUS_INACTIVE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : The literal source-code is found but not active.


---

### STATUS_INVALID

- STATUS_INVALID: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : The literal source-code is not found in the system.


---

## Property Details

### code
- code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : The literal source-code.


---

### group
- group: [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md) `(read-only)`
  - : The associated source-code group.


---

### redirect
- redirect: [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md) `(read-only)`
  - : Retrieves the redirect information from the last processed SourceCodeGroup (active or inactive). If none exists,
      then the redirect information is retrieved from the source-code preferences, based on the active/inactive status
      of the SourceCodeGroup. The redirect information is then resolved to the output URL. If the redirect information
      cannot be resolved to a URL, or there is an error retrieving the preferences, then null is returned.



---

### status
- status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : The status of the source-code.  One of the following:
      STATUS\_INVALID - The source code is not found in the system.
      STATUS\_INACTIVE - The source code is found but not active.
      STATUS\_INACTIVE - The source code is found and active.



---

## Method Details

### getCode()
- getCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The literal source-code.

    **Returns:**
    - the source-code.


---

### getGroup()
- getGroup(): [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md)
  - : The associated source-code group.

    **Returns:**
    - the source-code group.


---

### getRedirect()
- getRedirect(): [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)
  - : Retrieves the redirect information from the last processed SourceCodeGroup (active or inactive). If none exists,
      then the redirect information is retrieved from the source-code preferences, based on the active/inactive status
      of the SourceCodeGroup. The redirect information is then resolved to the output URL. If the redirect information
      cannot be resolved to a URL, or there is an error retrieving the preferences, then null is returned.


    **Returns:**
    - URLRedirect containing the location and status code, null in case of no redirect was found


---

### getStatus()
- getStatus(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The status of the source-code.  One of the following:
      STATUS\_INVALID - The source code is not found in the system.
      STATUS\_INACTIVE - The source code is found but not active.
      STATUS\_INACTIVE - The source code is found and active.


    **Returns:**
    - the status.


---

<!-- prettier-ignore-end -->

<!-- document id=5eead6e81dad34367d7d3f72e4bc3744c28c0cbeb130b9d5ea85094fec276cb3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.SourceCodeStatusCodes.md -->

<!-- prettier-ignore-start -->
# Class SourceCodeStatusCodes

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.SourceCodeStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeStatusCodes.md)

Helper class which contains error result codes returned by the SetSourceCode
pipelet.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CODE_INACTIVE](#code_inactive): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CODE_INACTIVE" | Indicates that the specified source code was found in one or more  source-code groups, none of which are active. |
| [CODE_INVALID](#code_invalid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CODE_INVALID" | Indicates that the specified source code is not contained  in any source-code group. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SourceCodeStatusCodes](#sourcecodestatuscodes)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CODE_INACTIVE

- CODE_INACTIVE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CODE_INACTIVE"
  - : Indicates that the specified source code was found in one or more
      source-code groups, none of which are active.



---

### CODE_INVALID

- CODE_INVALID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "CODE_INVALID"
  - : Indicates that the specified source code is not contained
      in any source-code group.



---

## Constructor Details

### SourceCodeStatusCodes()
- SourceCodeStatusCodes()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=93641eae2f1fd0e3cffaf382a685dff931467b0957848c030b1b7b325967e6bb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Status.md -->

<!-- prettier-ignore-start -->
# Class Status

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)

A Status is used for communicating an API status code back to a client. A status
consists of multiple StatusItem. Most often a Status contains only one StatusItem.
For convenience, a message with parameters is formatted using standard
formatting patterns. If you want to display locale-specific messages in your
application, you should use the Status.getCode() as key for a resource bundle.



## Property Summary

| Property | Description |
| --- | --- |
| [ERROR](#error): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | status value to indicate an ERROR status |
| [OK](#ok): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | status value to indicate an OK status |
| [code](#code): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the status code either of the first ERROR StatusItem or when there  is no ERROR StatusITEM, the first StatusItem in the overall list. |
| [details](#details): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the details either of the first ERROR StatusItem or when there  is no ERROR StatusItem, the first StatusItem in the overall list. |
| [error](#error): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Checks if the status is an ERROR. |
| [items](#items): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns all status items. |
| [message](#message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the message either of the first ERROR StatusItem or when there  is no ERROR StatusItem, the first StatusItem in the overall list. |
| [parameters](#parameters): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns the parameters either of the first ERROR StatusItem or when there  is no ERROR StatusItem, the first StatusItem in the overall list. |
| [status](#status): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the overall status. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Status](#status)() | Creates a Status object with no StatusItems. |
| [Status](#statusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a Status with a single StatusItem. |
| [Status](#statusnumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a Status with a single StatusItem. |
| [Status](#statusnumber-string-string-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a Status with a single StatusItem. |

## Method Summary

| Method | Description |
| --- | --- |
| [addDetail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#adddetailstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Add detail information for the given key of the first ERROR StatusItem  or when there is no ERROR StatusItem, the first StatusItem in the overall list. |
| [addItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#additemstatusitem)([StatusItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md)) | Adds an additional status item to this status instance. |
| [getCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getcode)() | Returns the status code either of the first ERROR StatusItem or when there  is no ERROR StatusITEM, the first StatusItem in the overall list. |
| [getDetail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getdetailstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the detail value for the given key of the first ERROR StatusItem  or when there is no ERROR StatusItem, the first StatusItem in the  overall list. |
| [getDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getdetails)() | Returns the details either of the first ERROR StatusItem or when there  is no ERROR StatusItem, the first StatusItem in the overall list. |
| [getItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getitems)() | Returns all status items. |
| [getMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getmessage)() | Returns the message either of the first ERROR StatusItem or when there  is no ERROR StatusItem, the first StatusItem in the overall list. |
| [getParameters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getparameters)() | Returns the parameters either of the first ERROR StatusItem or when there  is no ERROR StatusItem, the first StatusItem in the overall list. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#getstatus)() | Returns the overall status. |
| [isError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#iserror)() | Checks if the status is an ERROR. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ERROR
- ERROR: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : status value to indicate an ERROR status


---

### OK
- OK: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : status value to indicate an OK status


---

### code
- code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the status code either of the first ERROR StatusItem or when there
      is no ERROR StatusITEM, the first StatusItem in the overall list.
      
      The status code is the unique identifier for the message and can be used by
      client programs to check for a specific status and to generate a localized
      message.



---

### details
- details: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the details either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.



---

### error
- error: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Checks if the status is an ERROR. The Status is an ERROR if one of the
      contained StatusItems is an ERROR.



---

### items
- items: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns all status items.


---

### message
- message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the message either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.
      
      Note: Custom code and client programs must not use this message to identify
      a specific status. The getCode() must be used for that purpose. The actual
      message can change from release to release.



---

### parameters
- parameters: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns the parameters either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.



---

### status
- status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the overall status. If all StatusItems are OK, the method returns
      OK. If one StatusItem is an ERROR it returns ERROR.



---

## Constructor Details

### Status()
- Status()
  - : Creates a Status object with no StatusItems.


---

### Status(Number)
- Status(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a Status with a single StatusItem. The status is set to the given
      value.


    **Parameters:**
    - status - either OK or ERROR


---

### Status(Number, String)
- Status(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a Status with a single StatusItem. The StatusItem is initialized
      with the given values.


    **Parameters:**
    - status - either OK or ERROR
    - code - a string representing a more detailed status code, e.g. "IMPEX-120"


---

### Status(Number, String, String, Object...)
- Status(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), parameters: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates a Status with a single StatusItem. The StatusItem is initialized
      with the given values.


    **Parameters:**
    - status - either OK or ERROR
    - code - a string representing a more detailed status code, e.g. "IMPEX-120".
    - message - a default human readable message
    - parameters - a list of parameters to construct a custom message


---

## Method Details

### addDetail(String, Object)
- addDetail(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Add detail information for the given key of the first ERROR StatusItem
      or when there is no ERROR StatusItem, the first StatusItem in the overall list.


    **Parameters:**
    - key - the key of the first ERROR StatusItem or the first StatusItem  in the list.
    - value - the detail value.


---

### addItem(StatusItem)
- addItem(item: [StatusItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md)): void
  - : Adds an additional status item to this status instance.

    **Parameters:**
    - item - the status item to add.


---

### getCode()
- getCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status code either of the first ERROR StatusItem or when there
      is no ERROR StatusITEM, the first StatusItem in the overall list.
      
      The status code is the unique identifier for the message and can be used by
      client programs to check for a specific status and to generate a localized
      message.


    **Returns:**
    - the status code


---

### getDetail(String)
- getDetail(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the detail value for the given key of the first ERROR StatusItem
      or when there is no ERROR StatusItem, the first StatusItem in the
      overall list.


    **Parameters:**
    - key - the key for the detail to return.

    **Returns:**
    - the detail value for the given key of the first ERROR StatusItem
      or when there is no ERROR StatusItem, the first StatusItem in the
      overall list.



---

### getDetails()
- getDetails(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the details either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.


    **Returns:**
    - the details either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.



---

### getItems()
- getItems(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns all status items.

    **Returns:**
    - all status items.


---

### getMessage()
- getMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the message either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.
      
      Note: Custom code and client programs must not use this message to identify
      a specific status. The getCode() must be used for that purpose. The actual
      message can change from release to release.


    **Returns:**
    - the message either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.



---

### getParameters()
- getParameters(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the parameters either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.


    **Returns:**
    - the parameters either of the first ERROR StatusItem or when there
      is no ERROR StatusItem, the first StatusItem in the overall list.



---

### getStatus()
- getStatus(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the overall status. If all StatusItems are OK, the method returns
      OK. If one StatusItem is an ERROR it returns ERROR.


    **Returns:**
    - either OK or ERROR


---

### isError()
- isError(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks if the status is an ERROR. The Status is an ERROR if one of the
      contained StatusItems is an ERROR.


    **Returns:**
    - true if status is an ERROR, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=4fca30bbee8e79f7d44c5d7bfedc2b876f496ce735040b7f244fb55940d789d2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.StatusItem.md -->

<!-- prettier-ignore-start -->
# Class StatusItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.StatusItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md)

A StatusItem holds all the status information. Multi StatusItems are bundled
together into a Status.



## Property Summary

| Property | Description |
| --- | --- |
| [code](#code): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The status code is the unique identifier for the message and can be used by  client programs to check for a specific status and to generate a localized  message. |
| [details](#details): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)` | Returns the optional details for this StatusItem. |
| [error](#error): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether this Status Item represents and error. |
| [message](#message): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the default human readable message for this Status. |
| [parameters](#parameters): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) | Returns the parameters to construct a custom message. |
| [status](#status): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Returns the status. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [StatusItem](#statusitem)() | Constructs a new OK StatusItem. |
| [StatusItem](#statusitemnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs a new StatusItem with the given status. |
| [StatusItem](#statusitemnumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new StatusItem with the given status and code. |
| [StatusItem](#statusitemnumber-string-string-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Constructs a new StatusItem with the given values. |

## Method Summary

| Method | Description |
| --- | --- |
| [addDetail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#adddetailstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Add an additional detail to this StatusItem. |
| [getCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getcode)() | The status code is the unique identifier for the message and can be used by  client programs to check for a specific status and to generate a localized  message. |
| [getDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getdetails)() | Returns the optional details for this StatusItem. |
| [getMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getmessage)() | Returns the default human readable message for this Status. |
| [getParameters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getparameters)() | Returns the parameters to construct a custom message. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#getstatus)() | Returns the status. |
| [isError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#iserror)() | Returns whether this Status Item represents and error. |
| [setCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#setcodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Method to set the status code. |
| [setMessage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#setmessagestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the default human readable message for this Status. |
| [setParameters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#setparametersobject)([Object\[\]](TopLevel.Object.md)) | Sets the parameters for a custom message. |
| [setStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md#setstatusnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Set the status. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### code
- code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The status code is the unique identifier for the message and can be used by
      client programs to check for a specific status and to generate a localized
      message.



---

### details
- details: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md) `(read-only)`
  - : Returns the optional details for this StatusItem.


---

### error
- error: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether this Status Item represents and error.


---

### message
- message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the default human readable message for this Status.
      
      Note: Custom code and client programs must not use this message to identify
      a specific status. The getCode() must be used for that purpose. The actual
      message can change from release to release.



---

### parameters
- parameters: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the parameters to construct a custom message.


---

### status
- status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status.


---

## Constructor Details

### StatusItem()
- StatusItem()
  - : Constructs a new OK StatusItem.


---

### StatusItem(Number)
- StatusItem(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs a new StatusItem with the given status.

    **Parameters:**
    - status - either [Status.OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#ok) or  [Status.ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#error).


---

### StatusItem(Number, String)
- StatusItem(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a new StatusItem with the given status and code.

    **Parameters:**
    - status - either [Status.OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#ok) or  [Status.ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#error).
    - code - a string representing a more detailed status code, e.g. "IMPEX-120".


---

### StatusItem(Number, String, String, Object...)
- StatusItem(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), parameters: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Constructs a new StatusItem with the given values.

    **Parameters:**
    - status - [Status.OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#ok) or  [Status.ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#error).
    - code - a string representing a more detailed status code, e.g. "IMPEX-120".
    - message - a default human readable message
    - parameters - a list of parameters to construct a custom message


---

## Method Details

### addDetail(String, Object)
- addDetail(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Add an additional detail to this StatusItem.

    **Parameters:**
    - key - the key for the detail.
    - value - the detail value.


---

### getCode()
- getCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The status code is the unique identifier for the message and can be used by
      client programs to check for a specific status and to generate a localized
      message.


    **Returns:**
    - the status code.


---

### getDetails()
- getDetails(): [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)
  - : Returns the optional details for this StatusItem.

    **Returns:**
    - the optional details for this StatusItem.


---

### getMessage()
- getMessage(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the default human readable message for this Status.
      
      Note: Custom code and client programs must not use this message to identify
      a specific status. The getCode() must be used for that purpose. The actual
      message can change from release to release.


    **Returns:**
    - the default human readable message for this Status.


---

### getParameters()
- getParameters(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns the parameters to construct a custom message.

    **Returns:**
    - the parameters to construct a custom message.


---

### getStatus()
- getStatus(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status.

    **Returns:**
    - either [Status.OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#ok) or
      [Status.ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#error).



---

### isError()
- isError(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this Status Item represents and error.

    **Returns:**
    - true is this item represents an error, false otherwise.


---

### setCode(String)
- setCode(code: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Method to set the status code.
      The status code is the unique identifier for the message and can be used by
      client programs to check for a specific status and to generate a localized
      message.


    **Parameters:**
    - code - the status code.


---

### setMessage(String)
- setMessage(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the default human readable message for this Status.

    **Parameters:**
    - message - the default human readable message for this Status.


---

### setParameters(Object[])
- setParameters(parameters: [Object\[\]](TopLevel.Object.md)): void
  - : Sets the parameters for a custom message.

    **Parameters:**
    - parameters - the parameters for a custom message.


---

### setStatus(Number)
- setStatus(status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Set the status.

    **Parameters:**
    - status - either  [Status.OK](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#ok) or  [Status.ERROR](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md#error).


---

<!-- prettier-ignore-end -->

<!-- document id=bf0bc419772056c8254285484a677a4de61d5aa4f59f7e6e66505f1f1b9c1a52 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.StopIteration.md -->

<!-- prettier-ignore-start -->
# Class StopIteration

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.StopIteration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.StopIteration.md)

A special type of exception that is thrown when an Iterator or Generator 
sequence is exhausted.


**See Also:**
- [Generator.next()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Generator.md#next)
- [Iterator.next()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterator.md#next)


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [StopIteration](#stopiteration)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### StopIteration()
- StopIteration()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=d95d9f4ea809e40a8b3a43ab385eeabbe4dda06afd65563a8040fd46a8921e8a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.Store.md -->

<!-- prettier-ignore-start -->
# Class Store

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.Store](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md)

Represents a store in Commerce Cloud Digital.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the store. |
| [address1](#address1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address1 of the store. |
| [address2](#address2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the address2 of the store. |
| [city](#city): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the city of the store. |
| [countryCode](#countrycode): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)` | Returns the countryCode of the store. |
| ~~[demandwarePosEnabled](#demandwareposenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)` | Returns the demandwarePosEnabled flag for the store. |
| [email](#email): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the email of the store. |
| [fax](#fax): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the fax of the store. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the store image. |
| [inventoryList](#inventorylist): [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md) `(read-only)` | Returns the inventory list the store is associated with. |
| [inventoryListID](#inventorylistid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the inventory list id the store is associated with. |
| [latitude](#latitude): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the latitude of the store. |
| [longitude](#longitude): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the longitude of the store. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the store. |
| [phone](#phone): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the phone of the store. |
| [posEnabled](#posenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the posEnabled flag for the Store. |
| [postalCode](#postalcode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the postalCode of the store. |
| [stateCode](#statecode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the stateCode of the store. |
| [storeEvents](#storeevents): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the storeEvents of the store. |
| [storeGroups](#storegroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all the store groups this store belongs to. |
| [storeHours](#storehours): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the storeHours of the store. |
| [storeLocatorEnabled](#storelocatorenabled): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns the storeLocatorEnabled flag for the store. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAddress1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getaddress1)() | Returns the address1 of the store. |
| [getAddress2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getaddress2)() | Returns the address2 of the store. |
| [getCity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getcity)() | Returns the city of the store. |
| [getCountryCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getcountrycode)() | Returns the countryCode of the store. |
| [getEmail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getemail)() | Returns the email of the store. |
| [getFax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getfax)() | Returns the fax of the store. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getid)() | Returns the ID of the store. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getimage)() | Returns the store image. |
| [getInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getinventorylist)() | Returns the inventory list the store is associated with. |
| [getInventoryListID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getinventorylistid)() | Returns the inventory list id the store is associated with. |
| [getLatitude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getlatitude)() | Returns the latitude of the store. |
| [getLongitude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getlongitude)() | Returns the longitude of the store. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getname)() | Returns the name of the store. |
| [getPhone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getphone)() | Returns the phone of the store. |
| [getPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getpostalcode)() | Returns the postalCode of the store. |
| [getStateCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getstatecode)() | Returns the stateCode of the store. |
| [getStoreEvents](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getstoreevents)() | Returns the storeEvents of the store. |
| [getStoreGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getstoregroups)() | Returns all the store groups this store belongs to. |
| [getStoreHours](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getstorehours)() | Returns the storeHours of the store. |
| ~~[isDemandwarePosEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#isdemandwareposenabled)()~~ | Returns the demandwarePosEnabled flag for the store. |
| [isPosEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#isposenabled)() | Returns the posEnabled flag for the Store. |
| [isStoreLocatorEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#isstorelocatorenabled)() | Returns the storeLocatorEnabled flag for the store. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the store.


---

### address1
- address1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address1 of the store.


---

### address2
- address2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the address2 of the store.


---

### city
- city: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the city of the store.


---

### countryCode
- countryCode: [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md) `(read-only)`
  - : Returns the countryCode of the store.


---

### demandwarePosEnabled
- ~~demandwarePosEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~ `(read-only)`
  - : Returns the demandwarePosEnabled flag for the store.
      Indicates that this store uses Commerce Cloud Store for point-of-sale.


    **Deprecated:**
**warning:** Use [isPosEnabled()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#isposenabled) instead

---

### email
- email: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the email of the store.


---

### fax
- fax: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the fax of the store.


---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the store image.


---

### inventoryList
- inventoryList: [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md) `(read-only)`
  - : Returns the inventory list the store is associated with. If the
      store is not associated with a inventory list, or the inventory list does not
      exist, the method returns null.



---

### inventoryListID
- inventoryListID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the inventory list id the store is associated with. If the
      store is not associated with a inventory list, or the inventory list does not
      exist, the method returns null.



---

### latitude
- latitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the latitude of the store.


---

### longitude
- longitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the longitude of the store.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the store.


---

### phone
- phone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the phone of the store.


---

### posEnabled
- posEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the posEnabled flag for the Store.
      Indicates that this store uses Commerce Cloud Store for point-of-sale.



---

### postalCode
- postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the postalCode of the store.


---

### stateCode
- stateCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the stateCode of the store.


---

### storeEvents
- storeEvents: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the storeEvents of the store.


---

### storeGroups
- storeGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all the store groups this store belongs to.


---

### storeHours
- storeHours: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the storeHours of the store.


---

### storeLocatorEnabled
- storeLocatorEnabled: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns the storeLocatorEnabled flag for the store.


---

## Method Details

### getAddress1()
- getAddress1(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address1 of the store.

    **Returns:**
    - address1 of the store


---

### getAddress2()
- getAddress2(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the address2 of the store.

    **Returns:**
    - address2 of the store


---

### getCity()
- getCity(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the city of the store.

    **Returns:**
    - city of the store


---

### getCountryCode()
- getCountryCode(): [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)
  - : Returns the countryCode of the store.

    **Returns:**
    - countryCode of the store


---

### getEmail()
- getEmail(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the email of the store.

    **Returns:**
    - email of the store


---

### getFax()
- getFax(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the fax of the store.

    **Returns:**
    - fax of the store


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the store.

    **Returns:**
    - ID of the store


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the store image.

    **Returns:**
    - the store image.


---

### getInventoryList()
- getInventoryList(): [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)
  - : Returns the inventory list the store is associated with. If the
      store is not associated with a inventory list, or the inventory list does not
      exist, the method returns null.


    **Returns:**
    - ProductInventoryList or null


---

### getInventoryListID()
- getInventoryListID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the inventory list id the store is associated with. If the
      store is not associated with a inventory list, or the inventory list does not
      exist, the method returns null.


    **Returns:**
    - the inventory list id


---

### getLatitude()
- getLatitude(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the latitude of the store.

    **Returns:**
    - latitude of the store


---

### getLongitude()
- getLongitude(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the longitude of the store.

    **Returns:**
    - longitude of the store


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the store.

    **Returns:**
    - name of the store


---

### getPhone()
- getPhone(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the phone of the store.

    **Returns:**
    - phone of the store


---

### getPostalCode()
- getPostalCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the postalCode of the store.

    **Returns:**
    - postalCode of the store


---

### getStateCode()
- getStateCode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the stateCode of the store.

    **Returns:**
    - stateCode of the store


---

### getStoreEvents()
- getStoreEvents(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the storeEvents of the store.

    **Returns:**
    - storeEvents of the store


---

### getStoreGroups()
- getStoreGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all the store groups this store belongs to.

    **Returns:**
    - collection of store groups


---

### getStoreHours()
- getStoreHours(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the storeHours of the store.

    **Returns:**
    - storeHours of the store


---

### isDemandwarePosEnabled()
- ~~isDemandwarePosEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Returns the demandwarePosEnabled flag for the store.
      Indicates that this store uses Commerce Cloud Store for point-of-sale.


    **Returns:**
    - the demandwarePosEnabled flag

    **Deprecated:**
**warning:** Use [isPosEnabled()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#isposenabled) instead

---

### isPosEnabled()
- isPosEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the posEnabled flag for the Store.
      Indicates that this store uses Commerce Cloud Store for point-of-sale.


    **Returns:**
    - the posEnabled flag


---

### isStoreLocatorEnabled()
- isStoreLocatorEnabled(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns the storeLocatorEnabled flag for the store.

    **Returns:**
    - the storeLocatorEnabled flag


---

<!-- prettier-ignore-end -->

<!-- document id=e93cca4cfc75d060becb203e4b9e449c28e34897564d22b9a74c942ff31c0b74 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.StoreGroup.md -->

<!-- prettier-ignore-start -->
# Class StoreGroup

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.StoreGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md)

Represents a store group. Store groups can be used to group the stores for different marketing purposes.


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the store group. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the store group. |
| [stores](#stores): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all the stores that are assigned to the store group. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md#getid)() | Returns the ID of the store group. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md#getname)() | Returns the name of the store group. |
| [getStores](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md#getstores)() | Returns all the stores that are assigned to the store group. |

### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the store group.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the store group.


---

### stores
- stores: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all the stores that are assigned to the store group.


---

## Method Details

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the store group.

    **Returns:**
    - ID of the store group


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the store group.

    **Returns:**
    - name of the store group


---

### getStores()
- getStores(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all the stores that are assigned to the store group.

    **Returns:**
    - collection of the stores


---

<!-- prettier-ignore-end -->

<!-- document id=52e323ae9864b751bd6758fc1b2a4735c1ebd445e83bb33a0b7ed33e9caba8f3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.StoreInventoryFilter.md -->

<!-- prettier-ignore-start -->
# Class StoreInventoryFilter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)



This class represents a store inventory filter, which can be used at
[ProductSearchModel.setStoreInventoryFilter(StoreInventoryFilter)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setstoreinventoryfilterstoreinventoryfilter) to filter the search result by one or more
store inventories. Compared to the default parameter 'ilids' (Inventory List IDs) see
([ProductSearchModel.INVENTORY_LIST_IDS_PARAMETER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#inventory_list_ids_parameter) the store inventory filter allows a customization of the
parameter name and the inventory list ID parameter values for the URL generations via all URLRefine and URLRelax
methods e.g. for [ProductSearchModel.urlRefineCategory(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrefinecategorystring-string),
[ProductSearchModel.urlRelaxPrice(URL)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#urlrelaxpriceurl),
[SearchModel.urlRefineAttribute(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md#urlrefineattributestring-string-string).


Example custom URL: city=Burlington|Boston



```
new dw.catalog.StoreInventoryFilter( "city",
    new dw.util.ArrayList( new dw.catalog.StoreInventoryFilterValue( "Burlington", "inventory_store_store9" ),
        new dw.catalog.StoreInventoryFilterValue( "Boston", "inventory_store_store8" ) ) );
```



## Property Summary

| Property | Description |
| --- | --- |
| [semanticURLParameter](#semanticurlparameter): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the semantic URL parameter of this StoreInventoryFilter. |
| [storeInventoryFilterValues](#storeinventoryfiltervalues): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)` | Returns a list of [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances used by this StoreInventoryFilter. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [StoreInventoryFilter](#storeinventoryfilterstring-list)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)) | Creates a new StoreInventoryFilter instance for the given semantic URL parameter and a list of  [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances. |

## Method Summary

| Method | Description |
| --- | --- |
| [getSemanticURLParameter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md#getsemanticurlparameter)() | Returns the semantic URL parameter of this StoreInventoryFilter. |
| [getStoreInventoryFilterValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md#getstoreinventoryfiltervalues)() | Returns a list of [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances used by this StoreInventoryFilter. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### semanticURLParameter
- semanticURLParameter: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the semantic URL parameter of this StoreInventoryFilter.


---

### storeInventoryFilterValues
- storeInventoryFilterValues: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md) `(read-only)`
  - : Returns a list of [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances used by this StoreInventoryFilter.


---

## Constructor Details

### StoreInventoryFilter(String, List)
- StoreInventoryFilter(semanticURLParameter: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), storeFilterValues: [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md))
  - : Creates a new StoreInventoryFilter instance for the given semantic URL parameter and a list of
      [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances. The semantic URL parameter e.g. city, zip, store and the semantic
      store inventory values from the storeFilterValues will be used for URL generation. The mapped inventory list IDs
      from the storeFilterValues will be used for filtering. on the mapped


    **Parameters:**
    - semanticURLParameter - The semantic URL parameter which should be used for URL generation instead of 'ilids'                              (Inventory List IDs)
    - storeFilterValues - A list of [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances containing the store inventory                              values and the related real inventory list ID.

    **Throws:**
    - NullArgumentException - in case of missing required parameter.


---

## Method Details

### getSemanticURLParameter()
- getSemanticURLParameter(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the semantic URL parameter of this StoreInventoryFilter.

    **Returns:**
    - the semantic URL parameter of this StoreInventoryFilter.


---

### getStoreInventoryFilterValues()
- getStoreInventoryFilterValues(): [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)
  - : Returns a list of [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances used by this StoreInventoryFilter.

    **Returns:**
    - a list of [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md) instances used by this StoreInventoryFilter.


---

<!-- prettier-ignore-end -->

<!-- document id=02eb5877d93a5d21b8a99f3b9ec3543d067806f943cac75fd265da8bd140387b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.StoreInventoryFilterValue.md -->

<!-- prettier-ignore-start -->
# Class StoreInventoryFilterValue

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md)



This class represents a store inventory filter value, which can be used for a [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md) to filter
the search result by one or more store inventory list IDs via
[ProductSearchModel.setStoreInventoryFilter(StoreInventoryFilter)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setstoreinventoryfilterstoreinventoryfilter). Compared to
[ProductSearchModel.setInventoryListIDs(List)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setinventorylistidslist) the store inventory filter allows a customization of the
inventory parameter name and the inventory list ID values for URL generations. A StoreInventoryFilterValue provides
the mapping between a semantic value e.g. store1,store2 or Burlington,Boston to the related real inventory list ID.


Example custom URL: city=Burlington|Boston



```
new dw.catalog.StoreInventoryFilter("city",
    new dw.util.ArrayList(
        new dw.catalog.StoreInventoryFilterValue("Burlington","inventory_store_store9"),
        new dw.catalog.StoreInventoryFilterValue("Boston","inventory_store_store8")
));
```



## Property Summary

| Property | Description |
| --- | --- |
| [inventoryListID](#inventorylistid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the real inventory list ID of this store inventory filter value. |
| [semanticInventoryID](#semanticinventoryid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the semantic inventory ID of this store inventory filter value. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [StoreInventoryFilterValue](#storeinventoryfiltervaluestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Creates a new StoreInventoryFilterValue instance for the semantic inventory ID and real inventory list ID. |

## Method Summary

| Method | Description |
| --- | --- |
| [getInventoryListID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md#getinventorylistid)() | Returns the real inventory list ID of this store inventory filter value. |
| [getSemanticInventoryID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md#getsemanticinventoryid)() | Returns the semantic inventory ID of this store inventory filter value. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### inventoryListID
- inventoryListID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the real inventory list ID of this store inventory filter value.


---

### semanticInventoryID
- semanticInventoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the semantic inventory ID of this store inventory filter value.


---

## Constructor Details

### StoreInventoryFilterValue(String, String)
- StoreInventoryFilterValue(semanticInventoryListID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), inventoryListID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : 
      
      Creates a new StoreInventoryFilterValue instance for the semantic inventory ID and real inventory list ID.


    **Parameters:**
    - semanticInventoryListID - The semantic inventory list ID of this store inventory filter value.
    - inventoryListID - The real inventory list ID to filter the search result on.

    **Throws:**
    - NullArgumentException - in case of missing required parameter.


---

## Method Details

### getInventoryListID()
- getInventoryListID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the real inventory list ID of this store inventory filter value.

    **Returns:**
    - the real inventory list ID of this store inventory filter value.


---

### getSemanticInventoryID()
- getSemanticInventoryID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the semantic inventory ID of this store inventory filter value.

    **Returns:**
    - the semantic inventory ID of this store inventory filter value.


---

<!-- prettier-ignore-end -->

<!-- document id=a5cdf6b6558558b906a4fcc3a1dedc410237d91388d274b4e6784d0d9efc7efb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.StoreMgr.md -->

<!-- prettier-ignore-start -->
# Class StoreMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.catalog.StoreMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md)

Provides helper methods for getting stores based on id and querying for
stores based on geolocation.



## Property Summary

| Property | Description |
| --- | --- |
| [allStoreGroups](#allstoregroups): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all the store groups of the current site. |
| [storeIDFromSession](#storeidfromsession): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the store id associated with the current session. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getAllStoreGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#getallstoregroups)() | Returns all the store groups of the current site. |
| static [getStore](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#getstorestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the store object with the specified id or null if store with this  id does not exist in the site. |
| static [getStoreGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#getstoregroupstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the store group with the specified id or null if the store group with this id does not exist in the current site. |
| static [getStoreIDFromSession](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#getstoreidfromsession)() | Get the store id associated with the current session. |
| static [searchStoresByCoordinates](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#searchstoresbycoordinatesnumber-number-string-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Convenience method. |
| static [searchStoresByCoordinates](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#searchstoresbycoordinatesnumber-number-string-number-string-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Search for stores based on geo-coordinates. |
| static [searchStoresByPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#searchstoresbypostalcodestring-string-string-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Convenience method. |
| static [searchStoresByPostalCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#searchstoresbypostalcodestring-string-string-number-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Search for stores by country/postal code and optionally by additional  filter criteria. |
| static [setStoreIDToSession](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#setstoreidtosessionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the store id for the current session. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### allStoreGroups
- allStoreGroups: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all the store groups of the current site.


---

### storeIDFromSession
- storeIDFromSession: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the store id associated with the current session. By default, the session store id is null.


---

## Method Details

### getAllStoreGroups()
- static getAllStoreGroups(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all the store groups of the current site.

    **Returns:**
    - The store groups of the current site.


---

### getStore(String)
- static getStore(storeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Store](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md)
  - : Returns the store object with the specified id or null if store with this
      id does not exist in the site.


    **Parameters:**
    - storeID - the store identifier.

    **Returns:**
    - Store for specified id or null.


---

### getStoreGroup(String)
- static getStoreGroup(storeGroupID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [StoreGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md)
  - : Returns the store group with the specified id or null if the store group with this id does not exist in the current site.

    **Parameters:**
    - storeGroupID - the store group identifier.

    **Returns:**
    - The store group for specified id or null.


---

### getStoreIDFromSession()
- static getStoreIDFromSession(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the store id associated with the current session. By default, the session store id is null.

    **Returns:**
    - store id, null is returned and means no store id is set on session


---

### searchStoresByCoordinates(Number, Number, String, Number)
- static searchStoresByCoordinates(latitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), longitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), distanceUnit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxDistance: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)
  - : Convenience method.  Same as searchStoresByCoordinates(latitude, longitude, distanceUnit, maxDistance, null).

    **Parameters:**
    - latitude - Latitude coordinate which is the center of the search             area. Must not be null or an exception is thrown.
    - longitude - Longitude coordinate which is the center of the search             area. Must not be null or an exception is thrown.
    - distanceUnit - The distance unit to be used for the calculation.             Supported values are 'mi' and 'km' (for miles and kilometers             respectively). If an invalid value is passed then 'km' will be             used.
    - maxDistance - Area (radius) in DistanceUnit where Stores will be             searched for. If null is passed, a system default is used.

    **Returns:**
    - The stores and their distance from the specified location, sorted
              in ascending order by distance.



---

### searchStoresByCoordinates(Number, Number, String, Number, String, Object...)
- static searchStoresByCoordinates(latitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), longitude: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), distanceUnit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxDistance: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)
  - : Search for stores based on geo-coordinates. The method returns a list of
      stores for the current site that are within a specified distance of a
      location on the earth and which optionally satisfy additional filter
      criteria. If no additional criteria are specified, then this method
      behaves similar to GetNearestStores pipelet. The criteria are specified
      as a querystring, using the same syntax as
      [SystemObjectMgr.querySystemObjects(String, String, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md#querysystemobjectsstring-string-string-object)
      
      
      The stores and their distance from the specified location are returned as
      a LinkedHashMap of Store objects to distances, sorting in ascending order
      by distance. The distance is interpreted either in miles or kilometers
      depending on the "distanceUnit" parameter.
      
      
      The latitude and longitude of each store is determined by first looking
      at [Store.getLatitude()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getlatitude) and
      [Store.getLongitude()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md#getlongitude). If these are not set, then the
      system deduces the location of the store by looking for a configured
      geolocation matching the store's postal and country codes.


    **Parameters:**
    - latitude - Latitude coordinate which is the center of the search             area. Must not be null or an exception is thrown.
    - longitude - Longitude coordinate which is the center of the search             area. Must not be null or an exception is thrown.
    - distanceUnit - The distance unit to be used for the calculation.             Supported values are 'mi' and 'km' (for miles and kilometers             respectively). If an invalid value is passed then 'km' will be             used.
    - maxDistance - Area (radius) in DistanceUnit where Stores will be             searched for. If null is passed, a system default is used.
    - queryString - optional filter criteria specified as querystring.
    - args - the arguments to fill in the values in the querystring.

    **Returns:**
    - The stores and their distance from the specified location, sorted
              in ascending order by distance.



---

### searchStoresByPostalCode(String, String, String, Number)
- static searchStoresByPostalCode(countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), distanceUnit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxDistance: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)
  - : Convenience method.  Same as searchStoresByPostalCode(countryCode, postalCode, distanceUnit, maxDistance, null).

    **Parameters:**
    - countryCode - The country code for the search area, must not be null.
    - postalCode - The postal code for the center of the search area, must             not be null.
    - distanceUnit - The distance unit to be used for the calculation.             Supported values are 'mi' and 'km' (for miles and kilometers             respectively). If an invalid value is passed then 'km' will be             used.
    - maxDistance - Area (radius) in DistanceUnit where Stores will be             searched for. If null is passed, a system default is used.

    **Returns:**
    - The stores and their distance from the specified location, sorted
              in ascending order by distance.



---

### searchStoresByPostalCode(String, String, String, Number, String, Object...)
- static searchStoresByPostalCode(countryCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), postalCode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), distanceUnit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxDistance: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)
  - : Search for stores by country/postal code and optionally by additional
      filter criteria. This method is analagous to
      [searchStoresByCoordinates(Number, Number, String, Number, String, Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md#searchstoresbycoordinatesnumber-number-string-number-string-object)
      but identifies a location on the earth indirectly using country and
      postal code. The method will look first in the saved geolocations of the
      system to find a geolocation matching the passed country and postal code.
      If none is found, this method will return an empty map. If one is found,
      it will use the latitude/longitude of the found geolocation as the center
      of the search.


    **Parameters:**
    - countryCode - The country code for the search area, must not be null.
    - postalCode - The postal code for the center of the search area, must             not be null.
    - distanceUnit - The distance unit to be used for the calculation.             Supported values are 'mi' and 'km' (for miles and kilometers             respectively). If an invalid value is passed then 'km' will be             used.
    - maxDistance - Area (radius) in DistanceUnit where Stores will be             searched for. If null is passed, a system default is used.
    - queryString - An optional search querystring which provides             additional criteria to filter stores by.
    - args - The arguments providing the dynamic values to the             querystring.

    **Returns:**
    - The stores and their distance from the specified location, sorted
              in ascending order by distance.



---

### setStoreIDToSession(String)
- static setStoreIDToSession(storeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the store id for the current session. The store id is also saved on the cookie with the cookie name
      "dw\_store" with no expiration time. Null is allowed to remove store id from session, when null is passed in, the
      cookie will be removed when browser exits.


    **Parameters:**
    - storeID - the id of the store. The leading and trailing white spaces are removed by system from storeID


---

<!-- prettier-ignore-end -->

<!-- document id=cce5d02d2b3fd044069f65898f34647749b7761a3f7ef312915d413ceb0b8ae8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.String.md -->

<!-- prettier-ignore-start -->
# Class String

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)

The String object represents any sequence of zero or more characters that are to be
treated strictly as text.



## Property Summary

| Property | Description |
| --- | --- |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The length of the String object. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [String](#string)() | Constructs the String. |
| [String](#stringnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Constructs the String from the specified  Number object. |
| [String](#stringstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs a new String from the specified  String object. |

## Method Summary

| Method | Description |
| --- | --- |
| [charAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#charatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a string containing the character at position _index_. |
| [charCodeAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#charcodeatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the UTF-16 code unit at the given position index. |
| [codePointAt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#codepointatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the Unicode code point at the given position index. |
| [concat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#concatstring)([String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a new String created by concatenating the string arguments together. |
| [endsWith](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#endswithstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Tests if this string ends with a given string. |
| [endsWith](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#endswithstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Tests if this string ends with a given string. |
| [equals](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#equalsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if this string is equal to the string representation of the  passed objects. |
| [equalsIgnoreCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#equalsignorecaseobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if this string is equal to the string representation of the  passed objects. |
| static [fromCharCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#fromcharcodenumber)([Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new String from one or more UTF-16 code units. |
| static [fromCodePoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#fromcodepointnumber)([Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new String from one or more characters with Unicode code points. |
| [includes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#includesstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns if _substring_ is contained in this String object. |
| [includes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#includesstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns if _substring_ is contained in this String object. |
| [indexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#indexofstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the index of _substring_ in this String object. |
| [indexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#indexofstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the index of _substring_ in this String object using  the specified _start_ value as the location to begin searching. |
| [lastIndexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#lastindexofstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the last index of _substring_ in this String object. |
| [lastIndexOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#lastindexofstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the last index of _substring_ in this String object,  using the specified _start_ position as the location from which  to begin the search. |
| [localeCompare](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#localecomparestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a number indicating whether the current String sorts before, the same as,  or after the parameter _other_, based on browser and system-dependent  string localization. |
| [match](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#matchregexp)([RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)) | Returns an array of strings that match the regular expression  _regexp_. |
| [normalize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#normalize)() | Returns the normalized form of this Unicode string. |
| [normalize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#normalizestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the normalized form of this Unicode string according to the standard as described in [https://unicode.org/reports/tr15/](https://unicode.org/reports/tr15/). |
| [padEnd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#padendnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Appends space characters to the current string to ensure the resulting string reaches the given target length. |
| [padEnd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#padendnumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Appends a string (possibly multiple times) to the current string to ensure the resulting string reaches the given target length. |
| [padStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#padstartnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Prepends space characters to the current string to ensure the resulting string reaches the given target length. |
| [padStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#padstartnumber-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Prepends a string (possibly multiple times) to the current string to ensure the resulting string reaches the given target length. |
| static [raw](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#rawobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The static `String.raw()` method is a tag function of template literals. |
| [repeat](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#repeatnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new string repeating this string the given number of times. |
| [replace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replaceregexp-function)([RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Returns a new String that results when matches of the _regexp_  parameter are replaced by using the specified _function_. |
| [replace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replaceregexp-string)([RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a new String that results when matches of the _regexp_  parameter are replaced by the _replacement_ parameter. |
| [replace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replacestring-function)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Returns a new String that results when matches of the _literal_  parameter are replaced by using the specified _function_. |
| ~~[replace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replacestring-function-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns a new String that results when matches of the _literal_  parameter are replaced by using the specified _function_. |
| [replace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replacestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a new String that results when matches of the _literal_  parameter are replaced by the _replacement_ parameter. |
| ~~[replace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replacestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns a new String that results when matches of the _literal_  parameter are replaced by the _replacement_ parameter. |
| [search](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#searchregexp)([RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)) | Searches for a match between the passed regular expression and this  string and returns the zero-based index of the match, or -1 if no match  is found. |
| [slice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#slicenumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a substring of the current String where the  specified _start_ and _end_ locations are used  to delimit the String. |
| [split](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#splitregexp)([RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)) | Returns an array of String instances created by splitting the current  String based on the regular expression. |
| [split](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#splitregexp-number)([RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an array of String instances created by splitting the current  String based on the regular expression and limited in size by the _limit_  parameter. |
| [split](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#splitstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an array of String instances created by splitting the current  String based on the delimiter. |
| [split](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#splitstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns an array of String instances created by splitting the current  String based on the delimiter and limited in size by the _limit_  parameter. |
| [startsWith](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#startswithstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Tests if this string starts with a given string. |
| [startsWith](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#startswithstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Tests if this string starts with a given string. |
| [substr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#substrnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates and returns a new String by splitting the current string  at the specified _start_ location until the end of the String. |
| [substr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#substrnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates and returns a new String by splitting the current string  at the specified _start_ location and limited by the _length_  value. |
| [substring](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#substringnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates and returns a new String by splitting the current string  at the specified _from_ location until the end of the String. |
| [substring](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#substringnumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates and returns a new String by splitting the current string  at the specified _from_ location until the specified _to_ location. |
| [toLocaleLowerCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#tolocalelowercase)() | Returns a copy of the current string in all lower-case letters. |
| [toLocaleUpperCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#tolocaleuppercase)() | Returns a copy of the current string in all upper-case letters. |
| [toLowerCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#tolowercase)() | Returns a copy of the current string in all lower-case letters. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#tostring)() | Returns a String value of this object. |
| [toUpperCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#touppercase)() | Returns a copy of the current string in all upper-case letters. |
| [trim](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#trim)() | Removes white space characters at the start and the end of the string. |
| [trimEnd](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#trimend)() | Removes white space characters at the end of the string. |
| [trimLeft](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#trimleft)() | Removes white space characters at the start of the string. |
| [trimRight](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#trimright)() | Removes white space characters at the end of the string. |
| [trimStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#trimstart)() | Removes white space characters at the start of the string. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#valueof)() | Returns a String value of this object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The length of the String object.


---

## Constructor Details

### String()
- String()
  - : Constructs the String.


---

### String(Number)
- String(num: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Constructs the String from the specified
      Number object.


    **Parameters:**
    - num - the number that will  be converted to a String.


---

### String(String)
- String(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs a new String from the specified
      String object.


    **Parameters:**
    - str - the String that will  be converted to a new String.


---

## Method Details

### charAt(Number)
- charAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string containing the character at position _index_.
      You should use this method instead
      of substring when you need only a single character.


    **Parameters:**
    - index - the index at which the character string is located.

    **Returns:**
    - a string containing the character at position _index_.


---

### charCodeAt(Number)
- charCodeAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the UTF-16 code unit at the given position index. If the position is invalid `NaN` is returned.

    **Parameters:**
    - index - The index of the code unit within the string.

    **Returns:**
    - a non-negative integer representing a UTF-16 code unit or `NaN` if the index is not valid.


---

### codePointAt(Number)
- codePointAt(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the Unicode code point at the given position index. The index is a position within the string in UTF-16
      encoding. If the index points to the begin of a surrogate pair the only the code unit at the position is returned.
      If the index is invalid `undefined` is returned.


    **Parameters:**
    - index - The index of the starting code unit within the string.

    **Returns:**
    - The Unicode code point, an UTF-16 code unit or `undefined`.

    **API Version:**
**note:** Available from version 21.2.

---

### concat(String...)
- concat(strings: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new String created by concatenating the string arguments together.

    **Parameters:**
    - strings - zero, one, or more String arguments

    **Returns:**
    - a new String created by concatenating the string arguments together.


---

### endsWith(String)
- endsWith(searchString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Tests if this string ends with a given string.

    **Parameters:**
    - searchString - The characters to be searched for this string.

    **Returns:**
    - `true` if the search string was found else `false`

    **API Version:**
**note:** Available from version 21.2.

---

### endsWith(String, Number)
- endsWith(searchString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Tests if this string ends with a given string.

    **Parameters:**
    - searchString - The characters to be searched for this string.
    - length - Assumes this string has only this given length.

    **Returns:**
    - `true` if the search string was found else `false`

    **API Version:**
**note:** Available from version 21.2.

---

### equals(Object)
- equals(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this string is equal to the string representation of the
      passed objects.


    **Parameters:**
    - obj - another object, typically another string


---

### equalsIgnoreCase(Object)
- equalsIgnoreCase(obj: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this string is equal to the string representation of the
      passed objects. The comparison is done case insensitive.


    **Parameters:**
    - obj - another object, typically another string


---

### fromCharCode(Number...)
- static fromCharCode(c: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new String from one or more UTF-16 code units.

    **Parameters:**
    - c - zero, one, or more UTF-16 code units.


---

### fromCodePoint(Number...)
- static fromCodePoint(c: [Number...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new String from one or more characters with Unicode code points.

    **Parameters:**
    - c - zero, one, or more code points.

    **API Version:**
**note:** Available from version 21.2.

---

### includes(String)
- includes(substring: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if _substring_ is contained in this String object.

    **Parameters:**
    - substring - the String to search for in this String.

    **Returns:**
    - `true` if _substring_ occurs within the current string, else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### includes(String, Number)
- includes(substring: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if _substring_ is contained in this String object.

    **Parameters:**
    - substring - the String to search for in this String.
    - start - the location in the String from which to begin the search.

    **Returns:**
    - `true` if _substring_ occurs within the current string, else `false`.

    **API Version:**
**note:** Available from version 21.2.

---

### indexOf(String)
- indexOf(substring: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index of _substring_ in this String object.
      If there is no match, _-1_ is returned.


    **Parameters:**
    - substring - the String to search for in this String.

    **Returns:**
    - the index of _substring_ or _-1_.


---

### indexOf(String, Number)
- indexOf(substring: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the index of _substring_ in this String object using
      the specified _start_ value as the location to begin searching.
      If there is no match, _-1_ is returned.


    **Parameters:**
    - substring - the String to search for in this String.
    - start - the location in the String from which to  begin the search.

    **Returns:**
    - the index of _substring_ or _-1_.


---

### lastIndexOf(String)
- lastIndexOf(substring: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the last index of _substring_ in this String object.
      If there is no match, _-1_ is returned.


    **Parameters:**
    - substring - the String to search for in this String.

    **Returns:**
    - the last index of _substring_ or _-1_.


---

### lastIndexOf(String, Number)
- lastIndexOf(substring: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the last index of _substring_ in this String object,
      using the specified _start_ position as the location from which
      to begin the search.
      If there is no match, _-1_ is returned.


    **Parameters:**
    - substring - the String to search for in this String.
    - start - the location from which to begin the search.

    **Returns:**
    - the last index of _substring_ or _-1_.


---

### localeCompare(String)
- localeCompare(other: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns a number indicating whether the current String sorts before, the same as,
      or after the parameter _other_, based on browser and system-dependent
      string localization.


    **Parameters:**
    - other - the String to compare against this String.

    **Returns:**
    - a number indicating whether the current String sorts before, the same as,
      or after the parameter _other_.



---

### match(RegExp)
- match(regexp: [RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)): [String\[\]](TopLevel.String.md)
  - : Returns an array of strings that match the regular expression
      _regexp_.


    **Parameters:**
    - regexp - the regular expression to use.

    **Returns:**
    - an array of strings that match the regular expression.


---

### normalize()
- normalize(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the normalized form of this Unicode string. Same as calling [normalize(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#normalizestring) with parameter **'NFC'**.

    **Returns:**
    - The normalized form of this Unicode string.

    **API Version:**
**note:** Available from version 21.2.

---

### normalize(String)
- normalize(form: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the normalized form of this Unicode string according to the standard as described in [https://unicode.org/reports/tr15/](https://unicode.org/reports/tr15/).
      In a normalized string, identical text is replaced by identical sequences of code points.


    **Parameters:**
    - form - The normalization variant to use. Must be one of **'NFC'**, **'NFD'**, **'NFKC'**, **'NFKD'**.

    **Returns:**
    - The normalized form of this Unicode string.

    **API Version:**
**note:** Available from version 21.2.

---

### padEnd(Number)
- padEnd(targetLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Appends space characters to the current string to ensure the resulting string reaches the given target length.

    **Parameters:**
    - targetLength - The length to be reached.

    **Returns:**
    - This string if the string length is already greater than or equal to the target length. Else a new string with the _targetLength_ ending with space characters.

    **API Version:**
**note:** Available from version 21.2.

---

### padEnd(Number, String)
- padEnd(targetLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), fillString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Appends a string (possibly multiple times) to the current string to ensure the resulting string reaches the given target length.

    **Parameters:**
    - targetLength - The length to be reached.
    - fillString - The string providing the characters to be used for filling.

    **Returns:**
    - This string if the string length is already greater than or equal to the target length. Else a new string with the _targetLength_ with the (possibly multiple times) added and truncated _fillString_.

    **API Version:**
**note:** Available from version 21.2.

---

### padStart(Number)
- padStart(targetLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Prepends space characters to the current string to ensure the resulting string reaches the given target length.

    **Parameters:**
    - targetLength - The length to be reached.

    **Returns:**
    - This string if the string length is already greater than or equal to the target length. Else a new string with the _targetLength_ starting with space characters.

    **API Version:**
**note:** Available from version 21.2.

---

### padStart(Number, String)
- padStart(targetLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), fillString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Prepends a string (possibly multiple times) to the current string to ensure the resulting string reaches the given target length.

    **Parameters:**
    - targetLength - The length to be reached.
    - fillString - The string providing the characters to be used for filling.

    **Returns:**
    - This string if the string length is already greater than or equal to the target length. Else a new string with the _targetLength_ with the (possibly multiple times) added and truncated _fillString_.

    **API Version:**
**note:** Available from version 21.2.

---

### raw(Object, String...)
- static raw(callSite: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), substitutions: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The static `String.raw()` method is a tag function of template literals.
      
      
      It can be used in different ways:
      
      ```
      String.raw`Hello\n${40+2}!`;
      // returns: Hello\n42!
      // \ is here not an escape character like in string literals
      
      String.raw({ raw: ['a', 'b', 'c'] }, '-', '.' );
      // returns: a-b.c
      ```


    **Parameters:**
    - callSite - A well-formed template call site object, like `{ raw: ['a', 'b', 'c'] }`.
    - substitutions - The substitution values.

    **Returns:**
    - A string constructed by the template with filled substitutions.

    **API Version:**
**note:** Available from version 22.7.

---

### repeat(Number)
- repeat(count: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new string repeating this string the given number of times.

    **Parameters:**
    - count - The number of times this string should be repeated. Must be non-negative.

    **Returns:**
    - A new string repeating this string the given number of times.

    **API Version:**
**note:** Available from version 21.2.

---

### replace(RegExp, Function)
- replace(regexp: [RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md), function: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new String that results when matches of the _regexp_
      parameter are replaced by using the specified _function_. The
      original String is not modified so you must capture the new String
      in a variable to preserve changes. When you specify a function as the
      second parameter, the function is invoked after the match has been performed.


    **Parameters:**
    - regexp - the regular expression to use.
    - function - a Function that operates on matches of  _regexp_ in the current String.

    **Returns:**
    - a new String that results when matches of the _regexp_
      parameter are replaced by the _function_.



---

### replace(RegExp, String)
- replace(regexp: [RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md), replacement: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new String that results when matches of the _regexp_
      parameter are replaced by the _replacement_ parameter. The
      original String is not modified so you must capture the new String
      in a variable to preserve changes. If regexp has the global flag set,
      all occurrences are replaced, if the global flag is not set only the
      first occurrence is replaced.


    **Parameters:**
    - regexp - the regular expression to use.
    - replacement - a String that is to take the place of all matches of  _regexp_ in the current String.

    **Returns:**
    - a new String that results when matches of the _regexp_
      parameter are replaced by the _replacement_.



---

### replace(String, Function)
- replace(literal: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), function: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new String that results when matches of the _literal_
      parameter are replaced by using the specified _function_. The
      original String is not modified so you must capture the new String
      in a variable to preserve changes. When you specify a function as the
      second parameter, the function is invoked after the match has been
      performed.


    **Parameters:**
    - literal - the literal string to locate.
    - function - a Function that operates on the match of  _literal_ in the current String.

    **Returns:**
    - a new String that results when the first match of the _literal_
      parameter is replaced by the specified _function_.



---

### replace(String, Function, String)
- ~~replace(literal: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), function: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md), flags: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns a new String that results when matches of the _literal_
      parameter are replaced by using the specified _function_. The
      original String is not modified so you must capture the new String
      in a variable to preserve changes. When you specify a function as the
      second parameter, the function is invoked after the match has been
      performed.


    **Parameters:**
    - literal - the literal string to locate.
    - function - a Function that operates on the match of  _literal_ in the current String.
    - flags - a String containing any combination of the Regular  Expression flags of g - global match, i - ignore case, m - match over  multiple lines.

    **Returns:**
    - a new String that results when the first match of the _literal_
      parameter is replaced by the specified _function_.


    **Deprecated:**
**warning:** Use [replace(RegExp, Function)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replaceregexp-function) instead.
    **API Version:**
**note:** No longer available as of version 21.2.

---

### replace(String, String)
- replace(literal: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), replacement: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a new String that results when matches of the _literal_
      parameter are replaced by the _replacement_ parameter. The
      original String is not modified so you must capture the new String
      in a variable to preserve changes. This method only replaces the first
      occurrence of the literal. To replace all occurrences see the polymorphic
      method with a regular expression as argument.


    **Parameters:**
    - literal - the literal string to locate.
    - replacement - a String that is to take the place of all matches of  _regexp_ in the current String.

    **Returns:**
    - a new String that results when the first match of the _literal_
      parameter is replaced by the _replacement_ parameter.



---

### replace(String, String, String)
- ~~replace(literal: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), replacement: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), flags: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns a new String that results when matches of the _literal_
      parameter are replaced by the _replacement_ parameter. The
      original String is not modified so you must capture the new String
      in a variable to preserve changes. This method only replaces the first
      occurrence of the literal. To replace all occurrences see the polymorphic
      method with a regular expression as argument. Note that if flags


    **Parameters:**
    - literal - the literal string to locate.
    - replacement - a String that is to take the place of all matches of  _regexp_ in the current String.
    - flags - a String containing any combination of the Regular  Expression flags of g - global match, i - ignore case, m - match over  multiple lines.

    **Returns:**
    - a new String that results when the first match of the _literal_
      parameter is replaced by the _replacement_ parameter.


    **Deprecated:**
**warning:** Use [replace(RegExp, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#replaceregexp-string) instead.
    **API Version:**
**note:** No longer available as of version 21.2.

---

### search(RegExp)
- search(regexp: [RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Searches for a match between the passed regular expression and this
      string and returns the zero-based index of the match, or -1 if no match
      is found.


    **Parameters:**
    - regexp - the regular expression to use.

    **Returns:**
    - the zero-based indexed value of the first character in the
              current string that matches the pattern of the regular expression
              _regexp_, or -1 if no match is found.



---

### slice(Number, Number)
- slice(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a substring of the current String where the
      specified _start_ and _end_ locations are used
      to delimit the String.


    **Parameters:**
    - start - the start position in the current  String from which the slice will begin.
    - end - the end position in the current  String from which the slice will terminate.

    **Returns:**
    - the String between the _start_ and _end_ positions.


---

### split(RegExp)
- split(regexp: [RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)): [String\[\]](TopLevel.String.md)
  - : Returns an array of String instances created by splitting the current
      String based on the regular expression.


    **Parameters:**
    - regexp - the regular expression to use to split the string.

    **Returns:**
    - an array of String instances created by splitting the current
      String based on the regular expression.



---

### split(RegExp, Number)
- split(regexp: [RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md), limit: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String\[\]](TopLevel.String.md)
  - : Returns an array of String instances created by splitting the current
      String based on the regular expression and limited in size by the _limit_
      parameter.


    **Parameters:**
    - regexp - the regular expression to use to split the string.
    - limit - controls the maximum number of items that will  be returned.

    **Returns:**
    - an array of String instances created by splitting the current
      String based on the regular expression and limited in size by the _limit_
      parameter.



---

### split(String)
- split(delimiter: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String\[\]](TopLevel.String.md)
  - : Returns an array of String instances created by splitting the current
      String based on the delimiter.


    **Parameters:**
    - delimiter - the delimiter to use to split the string.

    **Returns:**
    - an array of String instances created by splitting the current
      String based on the delimiter.



---

### split(String, Number)
- split(delimiter: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), limit: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String\[\]](TopLevel.String.md)
  - : Returns an array of String instances created by splitting the current
      String based on the delimiter and limited in size by the _limit_
      parameter.


    **Parameters:**
    - delimiter - the delimiter to use to split the string.
    - limit - controls the maximum number of items that will  be returned.

    **Returns:**
    - an array of String instances created by splitting the current
      String based on the delimiter and limited in size by the _limit_
      parameter.



---

### startsWith(String)
- startsWith(searchString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Tests if this string starts with a given string.

    **Parameters:**
    - searchString - The characters to be searched for this string.

    **Returns:**
    - `true` if the search string was found else `false`

    **API Version:**
**note:** Available from version 21.2.

---

### startsWith(String, Number)
- startsWith(searchString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), position: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Tests if this string starts with a given string.

    **Parameters:**
    - searchString - The characters to be searched for this string.
    - position - The position in this string at which to begin searching for searchString.

    **Returns:**
    - `true` if the search string was found else `false`

    **API Version:**
**note:** Available from version 21.2.

---

### substr(Number)
- substr(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Creates and returns a new String by splitting the current string
      at the specified _start_ location until the end of the String.


    **Parameters:**
    - start - the start position in the current string from which  the new string will be created.

    **Returns:**
    - a new String created by splitting the current string
      starting at the specified _start_ location until the end of the String.



---

### substr(Number, Number)
- substr(start: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Creates and returns a new String by splitting the current string
      at the specified _start_ location and limited by the _length_
      value.


    **Parameters:**
    - start - the start position in the current string from which  the new string will be created.
    - length - controls the length of the new string.

    **Returns:**
    - a new String created by splitting the current string
      starting at the specified _start_ location and limited by the _length_
      value.



---

### substring(Number)
- substring(from: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Creates and returns a new String by splitting the current string
      at the specified _from_ location until the end of the String.


    **Parameters:**
    - from - the start position in the current string from which  the new string will be created.

    **Returns:**
    - a new String created by splitting the current string
      starting at the specified _from_ location until the end of the String.



---

### substring(Number, Number)
- substring(from: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), to: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Creates and returns a new String by splitting the current string
      at the specified _from_ location until the specified _to_ location.


    **Parameters:**
    - from - the start position in the current string from which  the new string will be created.
    - to - the end position in the current string from which the  new string will be created.

    **Returns:**
    - a new String created by splitting the current string
      starting at the specified _from_ location until the specified
      _to_ location.
      value.



---

### toLocaleLowerCase()
- toLocaleLowerCase(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a copy of the current string in all lower-case letters.

    **Returns:**
    - a copy of the current string in all lower-case letters.


---

### toLocaleUpperCase()
- toLocaleUpperCase(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a copy of the current string in all upper-case letters.

    **Returns:**
    - a copy of the current string in all upper-case letters.


---

### toLowerCase()
- toLowerCase(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a copy of the current string in all lower-case letters.

    **Returns:**
    - a copy of the current string in all lower-case letters.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a String value of this object.

    **Returns:**
    - a String value of this object.


---

### toUpperCase()
- toUpperCase(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a copy of the current string in all upper-case letters.

    **Returns:**
    - a copy of the current string in all upper-case letters.


---

### trim()
- trim(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Removes white space characters at the start and the end of the string.

    **Returns:**
    - A new string without leading and ending white space characters.


---

### trimEnd()
- trimEnd(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Removes white space characters at the end of the string.

    **Returns:**
    - A new string without ending white space characters.

    **API Version:**
**note:** Available from version 21.2.

---

### trimLeft()
- trimLeft(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Removes white space characters at the start of the string.
      [trimStart()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#trimstart) should be used instead of this.


    **Returns:**
    - A new string without leading white space characters.

    **API Version:**
**note:** Available from version 21.2.

---

### trimRight()
- trimRight(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Removes white space characters at the end of the string.
      [trimEnd()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#trimend) should be used instead of this.


    **Returns:**
    - A new string without ending white space characters.

    **API Version:**
**note:** Available from version 21.2.

---

### trimStart()
- trimStart(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Removes white space characters at the start of the string.

    **Returns:**
    - A new string without leading white space characters.

    **API Version:**
**note:** Available from version 21.2.

---

### valueOf()
- valueOf(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a String value of this object.

    **Returns:**
    - a String value of this object.


---

<!-- prettier-ignore-end -->

<!-- document id=3c366bf7329406d0b9d6b3aee91e064aa8925b17aeeeebe81a2a6513e1be29bf url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.StringUtils.md -->

<!-- prettier-ignore-start -->
# Class StringUtils

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.StringUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md)

String utility class.


## Constant Summary

| Constant | Description |
| --- | --- |
| [ENCODE_TYPE_HTML](#encode_type_html): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | String encoding type HTML. |
| ~~[ENCODE_TYPE_WML](#encode_type_wml): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2~~ | String encoding type WML. |
| [ENCODE_TYPE_XML](#encode_type_xml): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | String encoding type XML. |
| [TRUNCATE_CHAR](#truncate_char): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "char" | String truncate mode 'char'. |
| [TRUNCATE_SENTENCE](#truncate_sentence): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sentence" | String truncate mode 'sentence'. |
| [TRUNCATE_WORD](#truncate_word): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "word" | String truncate mode 'word'. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [decodeBase64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#decodebase64string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Interprets a Base64 encoded string as byte stream of an UTF-8 encoded string. |
| static [decodeBase64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#decodebase64string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Interprets a Base64 encoded string as the byte stream representation of a string. |
| static [decodeString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#decodestringstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Convert a given syntax-safe string to a string according to the  selected character entity encoding type. |
| static [encodeBase64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#encodebase64string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Encodes the byte representation of the given string as Base64. |
| static [encodeBase64](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#encodebase64string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Encodes the byte representation of the given string as Base64. |
| static [encodeString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#encodestringstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Convert a given string to a syntax-safe string according to the  selected character entity encoding type. |
| static [format](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a formatted string using the specified format and arguments. |
| static [formatCalendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatcalendarcalendar)([Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)) | Formats a Calendar object with Calendar.INPUT\_DATE\_TIME\_PATTERN format  of the current request locale, for example "MM/dd/yyyy h:mm a" for the  locale en\_US. |
| static [formatCalendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatcalendarcalendar-string)([Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Formats a Calendar object with the provided date format. |
| static [formatCalendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatcalendarcalendar-string-number)([Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Formats a Calendar object with the date format defined by the provided locale  and Calendar pattern. |
| ~~static [formatDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatdatedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md))~~ | Formats a date with the default date format of the current site. |
| ~~static [formatDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatdatedate-string)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Formats a date with the provided date format. |
| ~~static [formatDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatdatedate-string-string)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Formats a date with the provided date format in specified locale. |
| static [formatInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatintegernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a formatted integer number using the default integer format of the current  site. |
| static [formatMoney](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatmoneymoney)([Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)) | Formats a Money Object with the default money format of the current request locale. |
| static [formatNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatnumbernumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a formatted number using the default number format of the current site. |
| static [formatNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatnumbernumber-string---variant-1)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a formatted string using the specified number and format. |
| static [formatNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatnumbernumber-string-string---variant-1)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a formatted number as a string using the specified number format in specified locale. |
| static [formatNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatnumbernumber-string---variant-2)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a formatted string using the specified number and format. |
| static [formatNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatnumbernumber-string-string---variant-2)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a formatted number as a string using the specified number format in specified locale. |
| static [garble](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#garblestring-string-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Return a string in which specified number of characters in the suffix is not changed  and the rest of the characters replaced with specified character. |
| static [ltrim](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#ltrimstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the string with leading white space removed. |
| static [pad](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#padstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | This method provides cell padding functionality to the template. |
| static [rtrim](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#rtrimstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the string with trailing white space removed. |
| static [stringToHtml](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#stringtohtmlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Convert a given string to an HTML-safe string. |
| ~~static [stringToWml](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#stringtowmlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Converts a given string to a WML-safe string. |
| static [stringToXml](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#stringtoxmlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Converts a given string to a XML-safe string. |
| static [trim](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#trimstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the string with leading and trailing white space removed. |
| static [truncate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#truncatestring-number-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Truncate the string to the specified length using specified truncate mode. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ENCODE_TYPE_HTML

- ENCODE_TYPE_HTML: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : String encoding type HTML.

    **See Also:**
    - [encodeString(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#encodestringstring-number)


---

### ENCODE_TYPE_WML

- ~~ENCODE_TYPE_WML: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2~~
  - : String encoding type WML.

    **See Also:**
    - [encodeString(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#encodestringstring-number)

    **Deprecated:**
**warning:** Don't use this constant anymore.

---

### ENCODE_TYPE_XML

- ENCODE_TYPE_XML: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : String encoding type XML.

    **See Also:**
    - [encodeString(String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#encodestringstring-number)


---

### TRUNCATE_CHAR

- TRUNCATE_CHAR: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "char"
  - : String truncate mode 'char'. Truncate string to the nearest character. Default mode if no truncate mode is specified.

    **See Also:**
    - [truncate(String, Number, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#truncatestring-number-string-string)


---

### TRUNCATE_SENTENCE

- TRUNCATE_SENTENCE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sentence"
  - : String truncate mode 'sentence'. Truncate string to the nearest sentence.

    **See Also:**
    - [truncate(String, Number, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#truncatestring-number-string-string)


---

### TRUNCATE_WORD

- TRUNCATE_WORD: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "word"
  - : String truncate mode 'word'. Truncate string to the nearest word.

    **See Also:**
    - [truncate(String, Number, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#truncatestring-number-string-string)


---

## Method Details

### decodeBase64(String)
- static decodeBase64(base64: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Interprets a Base64 encoded string as byte stream of an UTF-8 encoded string.
      
      The method throws an IllegalArgumentException in case the encoding
      failed because of a mismatch between the input string and the character encoding.


    **Parameters:**
    - base64 - the Base64 encoded string - should not be empty or `null`.

    **Returns:**
    - the decoded string.


---

### decodeBase64(String, String)
- static decodeBase64(base64: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), characterEncoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Interprets a Base64 encoded string as the byte stream representation of a string.
      The given character encoding is used for decoding the byte stream into the
      character representation.
      
      The method throws an IllegalArgumentException in case the encoding
      failed because of a mismatch between the input String and the character encoding.


    **Parameters:**
    - base64 - the Base64 encoded string - should not be empty or `null`.
    - characterEncoding - the character encoding to read the input string -                 should not be empty or `null`.

    **Returns:**
    - the decoded string.


---

### decodeString(String, Number)
- static decodeString(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Convert a given syntax-safe string to a string according to the
      selected character entity encoding type.


    **Parameters:**
    - str - String to be decoded
    - type - decode type

    **Returns:**
    - decoded string


---

### encodeBase64(String)
- static encodeBase64(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encodes the byte representation of the given string as Base64.
      The string is converted into the byte representation with UTF-8 encoding.
      
      The method throws an IllegalArgumentException in case the encoding
      failed because of a mismatch between the input string and the character encoding.


    **Parameters:**
    - str - the string to encode - should not be empty or `null`.

    **Returns:**
    - the encoded string.


---

### encodeBase64(String, String)
- static encodeBase64(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), characterEncoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encodes the byte representation of the given string as Base64.
      The string is converted into the byte representation using the given
      character encoding.
      
      The method throws an IllegalArgumentException in case the encoding
      failed because of a mismatch between the input string and the character encoding.


    **Parameters:**
    - str - the string to encode - should not be empty or `null`.
    - characterEncoding - the character encoding to read the input string -                should not be empty or `null`.

    **Returns:**
    - the encoded string.


---

### encodeString(String, Number)
- static encodeString(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Convert a given string to a syntax-safe string according to the
      selected character entity encoding type.


    **Parameters:**
    - str - String to be encoded
    - type - encode type

    **Returns:**
    - encoded string


---

### format(String, Object...)
- static format(format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a formatted string using the specified format and arguments.
      The formatting string is a Java MessageFormat expression, e.g.
      format( "Message: {0}, {1}", "test", 10 ) would result in "Message: test, 10".
      
      If a Collection is passed as the only argument, the elements of this collection
      are used as arguments for the formatting.


    **Parameters:**
    - format - Java like formatting string.
    - args - optional list of arguments or a collection, which are included into the result string

    **Returns:**
    - the formatted result string.


---

### formatCalendar(Calendar)
- static formatCalendar(calendar: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Formats a Calendar object with Calendar.INPUT\_DATE\_TIME\_PATTERN format
      of the current request locale, for example "MM/dd/yyyy h:mm a" for the
      locale en\_US. The used time zone is the time zone of the calendar object.


    **Parameters:**
    - calendar - the calendar object.

    **Returns:**
    - a string representation of the formatted calendar object.


---

### formatCalendar(Calendar, String)
- static formatCalendar(calendar: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Formats a Calendar object with the provided date format. The format is a
      Java date format, like "yyy-MM-dd". The used time zone is the time zone
      of the calendar object.


    **Parameters:**
    - calendar - the calendar object to be printed
    - format - the format to use.

    **Returns:**
    - a string representation of the formatted calendar object.


---

### formatCalendar(Calendar, String, Number)
- static formatCalendar(calendar: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md), locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), pattern: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Formats a Calendar object with the date format defined by the provided locale
      and Calendar pattern.  The locale can be for instance the request.getLocale().
      The used time  zone is the time zone of the calendar object.


    **Parameters:**
    - calendar - the calendar object to be printed
    - locale - the locale, which defines the date format to be used
    - pattern - the pattern is one of a calendar pattern e.g. SHORT\_DATE\_PATTERN                 as defined in the regional settings for the locale

    **Returns:**
    - a string representation of the formatted calendar object.


---

### formatDate(Date)
- ~~static formatDate(date: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Formats a date with the default date format of the current site.

    **Parameters:**
    - date - the date to format.

    **Returns:**
    - a string representation of the formatted date.

    **Deprecated:**
**warning:** Use [formatCalendar(Calendar, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatcalendarcalendar-string) instead.

---

### formatDate(Date, String)
- ~~static formatDate(date: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Formats a date with the provided date format. The format is the
      Java date format, like "yyyy-MM-DD". The locale of the calling context
      request is used in formatting.


    **Parameters:**
    - date - the date to format.
    - format - the format to use.

    **Returns:**
    - a string representation of the formatted date.

    **Deprecated:**
**warning:** Use [formatCalendar(Calendar, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatcalendarcalendar-string) instead.

---

### formatDate(Date, String, String)
- ~~static formatDate(date: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Formats a date with the provided date format in specified locale. The format is
      Java date format, like "yyyy-MM-DD".


    **Parameters:**
    - date - the date to format.
    - format - the format to use.
    - locale - the locale to use.

    **Returns:**
    - a string representation of the formatted date.

    **Deprecated:**
**warning:** Use [formatCalendar(Calendar, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md#formatcalendarcalendar-string) instead.

---

### formatInteger(Number)
- static formatInteger(number: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a formatted integer number using the default integer format of the current
      site. The method can be also called to format a floating number as integer.


    **Parameters:**
    - number - the number to format.

    **Returns:**
    - a formatted an integer number with the default integer format of the current
      site.



---

### formatMoney(Money)
- static formatMoney(money: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Formats a Money Object with the default money format of the current request locale.

    **Parameters:**
    - money - The Money instance that should be formatted.

    **Returns:**
    - The formatted String representation of the passed
                 money. In case of an error the string 'N/A' is returned.



---

### formatNumber(Number)
- static formatNumber(number: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a formatted number using the default number format of the current site.
      
      Decimal and grouping separators are used as specified in the locales regional settings.


    **Parameters:**
    - number - the number to format.

    **Returns:**
    - a formatted number using the default number format of the current site.


---

### formatNumber(Number, String) - Variant 1
- static formatNumber(number: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a formatted string using the specified number and format. The format is
      Java number format, like "\#,\#\#\#.00". To format as an integer
      number provide "0" as format string. The locale of the calling context
      request is used in formatting.


    **Parameters:**
    - number - the number to format.
    - format - the format to use.

    **Returns:**
    - a formatted string using the specified number and format.

    **API Version:**
**note:** No longer available as of version 18.10.

---

### formatNumber(Number, String, String) - Variant 1
- static formatNumber(number: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a formatted number as a string using the specified number format in specified locale. The format is
      Java number format, like "\#,\#\#\#.00". To format as an integer
      number provide "0" as format string.


    **Parameters:**
    - number - the number to format.
    - format - the format to use.
    - locale - the locale to use.

    **Returns:**
    - a formatted number as a string using the specified number format in specified locale.

    **API Version:**
**note:** No longer available as of version 18.10.

---

### formatNumber(Number, String) - Variant 2
- static formatNumber(number: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a formatted string using the specified number and format. The format is
      Java number format, like "\#,\#\#\#.00". To format as an integer
      number provide "0" as format string. The locale of the calling context
      request is used in formatting.
      
      Decimal and grouping separators are used as specified in the locales regional settings (when configured, otherwise a fallback to the internal configuration is done).


    **Parameters:**
    - number - the number to format.
    - format - the format to use.

    **Returns:**
    - a formatted string using the specified number and format.

    **API Version:**
**note:** Available from version 18.10.
In prior versions this method did fall back to Java formatting rules, instead of using the definitions in regional settings.

---

### formatNumber(Number, String, String) - Variant 2
- static formatNumber(number: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), format: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a formatted number as a string using the specified number format in specified locale. The format is
      Java number format, like "\#,\#\#\#.00". To format as an integer
      number provide "0" as format string.
      
      Decimal and grouping separators are used as specified in the locales regional settings (when configured, otherwise a fallback to the internal configuration is done).


    **Parameters:**
    - number - the number to format.
    - format - the format to use.
    - locale - the locale to use.

    **Returns:**
    - a formatted number as a string using the specified number format in specified locale.

    **API Version:**
**note:** Available from version 18.10.
In prior versions this method did fall back to Java formatting rules, instead of using the definitions in regional settings.

---

### garble(String, String, Number)
- static garble(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), replaceChar: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), suffixLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return a string in which specified number of characters in the suffix is not changed
      and the rest of the characters replaced with specified character.


    **Parameters:**
    - str - String to garble
    - replaceChar - character to use as a replacement
    - suffixLength - length of the suffix

    **Returns:**
    - the garbled string.


---

### ltrim(String)
- static ltrim(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string with leading white space removed.

    **Parameters:**
    - str - the String to remove characters from.

    **Returns:**
    - the string with leading white space removed.


---

### pad(String, Number)
- static pad(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), width: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : This method provides cell padding functionality to the template.

    **Parameters:**
    - str - the string to process
    - width - The absolute value of this number defines the                       width of the cell. A possitive number forces left,                       a negative number right alignment.                       A '0' doesn't change the string.

    **Returns:**
    - the processed string.


---

### rtrim(String)
- static rtrim(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string with trailing white space removed.

    **Parameters:**
    - str - the String to remove characters from.

    **Returns:**
    - the string with trailing white space removed.


---

### stringToHtml(String)
- static stringToHtml(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Convert a given string to an HTML-safe string.
      This method substitutes characters that conflict with HTML syntax
      (<,>,&,") and characters that are beyond the ASCII
      chart (Unicode 160-255) to HTML 3.2 named character entities.


    **Parameters:**
    - str - String to be converted.

    **Returns:**
    - converted string.


---

### stringToWml(String)
- ~~static stringToWml(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Converts a given string to a WML-safe string.
      This method substitutes characters that conflict with WML syntax
      (<,>,&,&apos;,"$) to WML named character entities.


    **Parameters:**
    - str - String to be converted.

    **Returns:**
    - the converted string.

    **Deprecated:**
**warning:** Don't use this method anymore

---

### stringToXml(String)
- static stringToXml(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Converts a given string to a XML-safe string.
      This method substitutes characters that conflict with XML syntax
      (<,>,&,&apos;,") to XML named character entities.


    **Parameters:**
    - str - String to be converted.

    **Returns:**
    - the converted string.


---

### trim(String)
- static trim(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string with leading and trailing white space removed.

    **Parameters:**
    - str - the string to trim.

    **Returns:**
    - the string with leading and trailing white space removed.


---

### truncate(String, Number, String, String)
- static truncate(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), mode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), suffix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Truncate the string to the specified length using specified truncate mode. Optionally,
      append suffix to truncated string.


    **Parameters:**
    - str - string to truncate
    - maxLength - maximum length of the truncated string, not including suffix
    - mode - truncate mode (TRUNCATE\_CHAR, TRUNCATE\_WORD, TRUNCATE\_SENTENCE), if null TRUNCATE\_CHAR is assumed
    - suffix - suffix append to the truncated string

    **Returns:**
    - the truncated string.


---

<!-- prettier-ignore-end -->

<!-- document id=9140298b2566c80da46ea213ecfaab6fec6a879a2cd2c1758358ce84f22a52f3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.StringWriter.md -->

<!-- prettier-ignore-start -->
# Class StringWriter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)
    - [dw.io.StringWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.StringWriter.md)

A Writer that can be used to generate a String.


In most cases it is not necessary to use StringWriter. If the final
destination of the output is a file, use [FileWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md) directly.
This will help to reduce memory usage. If you wish to transfer a feed to a
remote FTP, SFTP or WebDAV server, first write the feed to the file system
using FileWriter and optionally [CSVStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamWriter.md) or
[XMLStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md), then upload the file with
[FTPClient.putBinary(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md#putbinarystring-file),
[SFTPClient.putBinary(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md#putbinarystring-file), or
[WebDAVClient.put(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#putstring-file).


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [StringWriter](#stringwriter)() | Creates a new StringWriter. |

## Method Summary

| Method | Description |
| --- | --- |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.StringWriter.md#tostring)() | Returns a string representation of this writer. |
| [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.StringWriter.md#writestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Write the given string to the stream. |
| [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.StringWriter.md#writestring-number-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Write the given string to the stream. |

### Methods inherited from class Writer

[close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#close), [flush](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#flush), [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring), [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring-number-number)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### StringWriter()
- StringWriter()
  - : Creates a new StringWriter.


---

## Method Details

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a string representation of this writer.

    **Returns:**
    - a string representation of this writer.


---

### write(String)
- write(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Write the given string to the stream.

    **Parameters:**
    - str - the string to write to the stream.


---

### write(String, Number, Number)
- write(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), off: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), len: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Write the given string to the stream.

    **Parameters:**
    - str - the string to write to the stream.
    - off - the offset from which to start writing characters to the             stream.
    - len - the number of characters to write from the stream.


---

<!-- prettier-ignore-end -->

<!-- document id=98f72f5a7d1710e8824cad39db286a4f6fadcd258c6dca918de7ae4d737b67ed url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.rpc.Stub.md -->

<!-- prettier-ignore-start -->
# Class Stub

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.rpc.Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)

This is the base class for all service stubs accessible
through a WebReference object. The Stub provides access to the WSDL operations.


Demandware recommends a low timeout to ensure responsiveness
of the site and to avoid thread exhaustion. Use the Services module
in Business Manager to set timeout values, not the methods for this class.
The Services module provides better analytics and timeout management.


The default timeout, if not set, is 15 minutes when the web service is used in a job,
and 2 minutes otherwise. If the timeout of the calling script is lower,
the script timeout is used.


```
 // get WebReference
    var webref : WebReference = webreferences.myWSDLname;
 // get service stub
    var stub : Stub = webref.defaultService;
```


**See Also:**
- [WebReference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.WebReference.md)
- [SOAPUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md)

**Deprecated:**
**warning:** This class is deprecated, please use webreferences2 instead (see also [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)).

## Constant Summary

| Constant | Description |
| --- | --- |
| ~~[CONNECTION_TIMEOUT](#connection_timeout): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | This property allows the user to set the web service connection timeout value in milliseconds. |
| ~~[ENDPOINT_ADDRESS_PROPERTY](#endpoint_address_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Standard property: target service endpoint address. |
| ~~[PASSWORD_PROPERTY](#password_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Standard property: password for authentication. |
| ~~[SESSION_MAINTAIN_PROPERTY](#session_maintain_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Standard property: this boolean property is used by a service  client to indicate whether or not it wants to participate in  a session with a service endpoint. |
| ~~[USERNAME_PROPERTY](#username_property): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Standard property: user name for authentication. |

## Property Summary

| Property | Description |
| --- | --- |
| ~~[password](#password): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Returns the password. |
| ~~[timeout](#timeout): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~ | Returns the current read timeout value in milliseconds for this Stub. |
| ~~[username](#username): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ | Returns the user name. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Stub](#stub)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| ~~[_getProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#_getpropertystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Gets the value of a specific configuration property. |
| ~~[_setProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#_setpropertystring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | Sets the name and value of a configuration property  for this Stub instance. |
| ~~[getPassword](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#getpassword)()~~ | Returns the password. |
| ~~[getTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#gettimeout)()~~ | Returns the current read timeout value in milliseconds for this Stub. |
| ~~[getUsername](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#getusername)()~~ | Returns the user name. |
| ~~[setHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#setheaderstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))~~ | Sets an additional SOAP header value for the next  operation. |
| ~~[setPassword](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#setpasswordstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the password. |
| ~~[setTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#settimeoutnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))~~ | Sets the timeout in milliseconds for the next call through this Stub. |
| ~~[setUsername](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#setusernamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Sets the user name. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CONNECTION_TIMEOUT

- ~~CONNECTION_TIMEOUT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : This property allows the user to set the web service connection timeout value in milliseconds. By default,
      the web service connection timeout is 5000 milliseconds (5 seconds). The minimum allowed value is 100 milliseconds
      and the maximum allowed value is 15000 milliseconds (15 seconds). Demandware recommends setting timeout values
      in Business Manager Services module as it provides better analytics and timeout management.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### ENDPOINT_ADDRESS_PROPERTY

- ~~ENDPOINT_ADDRESS_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Standard property: target service endpoint address. The
      URI scheme for the endpoint address specification must
      correspond to the protocol/transport binding for this
      stub class.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### PASSWORD_PROPERTY

- ~~PASSWORD_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Standard property: password for authentication.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### SESSION_MAINTAIN_PROPERTY

- ~~SESSION_MAINTAIN_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Standard property: this boolean property is used by a service
      client to indicate whether or not it wants to participate in
      a session with a service endpoint. If this property is set to
      true, the service client indicates that it wants the session
      to be maintained. If set to false, the session is not maintained.
      The default value for this property is false.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### USERNAME_PROPERTY

- ~~USERNAME_PROPERTY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Standard property: user name for authentication.

    **Deprecated:**
**warning:** use webreferences2 instead

---

## Property Details

### password
- ~~password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the password.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### timeout
- ~~timeout: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~
  - : Returns the current read timeout value in milliseconds for this Stub.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### username
- ~~username: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the user name.
      
      
      **Note:** this method handles sensitive security-related data.
      Pay special attention to PCI DSS v3. requirements 2, 4, and 12.


    **Deprecated:**
**warning:** use webreferences2 instead

---

## Constructor Details

### Stub()
- Stub()
  - : 


---

## Method Details

### _getProperty(String)
- ~~_getProperty(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)~~
  - : Gets the value of a specific configuration property.

    **Parameters:**
    - name - Name of the property whose value is to be           retrieved

    **Returns:**
    - Value of the configuration property

    **Deprecated:**
**warning:** use webreferences2 instead

---

### _setProperty(String, Object)
- ~~_setProperty(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void~~
  - : Sets the name and value of a configuration property
      for this Stub instance. If the Stub instance contains
      a value for the same property, the old value is replaced.
      
      **Note:** the `_setProperty` method may not
      perform a validity check on a configured property value. An
      example is the standard property for the target service
      endpoint address, which is not checked for validity in the
      `_setProperty` method.
      In this case, stub configuration errors are detected at
      the remote method invocation.


    **Parameters:**
    - name - Name of the configuration property
    - value - Value of the property

    **Deprecated:**
**warning:** use webreferences2 instead

---

### getPassword()
- ~~getPassword(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the password.

    **Returns:**
    - the password.
      
      
      **Note:** this method handles sensitive security-related data.
      Pay special attention to PCI DSS v3. requirements 2, 4, and 12.


    **Deprecated:**
**warning:** use webreferences2 instead

---

### getTimeout()
- ~~getTimeout(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)~~
  - : Returns the current read timeout value in milliseconds for this Stub.

    **Returns:**
    - the current timeout value for this Stub.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### getUsername()
- ~~getUsername(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Returns the user name.
      
      
      **Note:** this method handles sensitive security-related data.
      Pay special attention to PCI DSS v3. requirements 2, 4, and 12.


    **Returns:**
    - the user name.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setHeader(String, String, Object)
- ~~setHeader(namespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void~~
  - : Sets an additional SOAP header value for the next
      operation.


    **Parameters:**
    - namespace - the namespace to use.
    - name - the name of the header item.
    - value - the value for the header item.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setPassword(String)
- ~~setPassword(password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the password.

    **Parameters:**
    - password - the password to set.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setTimeout(Number)
- ~~setTimeout(timeout: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void~~
  - : Sets the timeout in milliseconds for the next call through this Stub.
      
      
      This timeout value controls "read timeout" (how
      long, after connecting, it will wait without any data being read).
      To control "connection timeout" you use the [_setProperty(String, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#_setpropertystring-object)
      method where the name parameter is [CONNECTION_TIMEOUT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#connection_timeout).


    **Parameters:**
    - timeout - the timeout for the next call through  this stub.

    **See Also:**
    - [_setProperty(String, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#_setpropertystring-object)
    - [CONNECTION_TIMEOUT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md#connection_timeout)

    **Deprecated:**
**warning:** use webreferences2 instead

---

### setUsername(String)
- ~~setUsername(username: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void~~
  - : Sets the user name.

    **Parameters:**
    - username - the user name to set.

    **Deprecated:**
**warning:** use webreferences2 instead

---

<!-- prettier-ignore-end -->

<!-- document id=03bee924c8778089bf0165dbcfac017d656baacab007502c76a9714193834d7d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SuggestedCategory.md -->

<!-- prettier-ignore-start -->
# Class SuggestedCategory

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SuggestedCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedCategory.md)

This class represents a suggested catalog category.
Use [getCategory()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedCategory.md#getcategory) method to get access to the actual [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) object.



## Property Summary

| Property | Description |
| --- | --- |
| [category](#category): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | This method returns the actual [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) object corresponding to this suggested category. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedCategory.md#getcategory)() | This method returns the actual [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) object corresponding to this suggested category. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### category
- category: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : This method returns the actual [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) object corresponding to this suggested category.


---

## Method Details

### getCategory()
- getCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : This method returns the actual [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) object corresponding to this suggested category.

    **Returns:**
    - the category object corresponding to this suggested category


---

<!-- prettier-ignore-end -->

<!-- document id=ff98d397d89e6961531db6cbdb01f81850bad7fbdd0000fe2f5fa90fa1f786a7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SuggestedContent.md -->

<!-- prettier-ignore-start -->
# Class SuggestedContent

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SuggestedContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedContent.md)

This class represents a suggested content page.
Use [getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedContent.md#getcontent) method to get access to the actual [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) object.



## Property Summary

| Property | Description |
| --- | --- |
| [content](#content): [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) `(read-only)` | This method returns the actual [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) object corresponding to this suggested content. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedContent.md#getcontent)() | This method returns the actual [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) object corresponding to this suggested content. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### content
- content: [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) `(read-only)`
  - : This method returns the actual [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) object corresponding to this suggested content.


---

## Method Details

### getContent()
- getContent(): [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md)
  - : This method returns the actual [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) object corresponding to this suggested content.

    **Returns:**
    - the content object corresponding to this suggested content


---

<!-- prettier-ignore-end -->

<!-- document id=aff5952e92375db3202e9c84faa7e9537812f376979805ed146f208538798b32 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SuggestedPhrase.md -->

<!-- prettier-ignore-start -->
# Class SuggestedPhrase

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md)

This class represents a suggested phrase.
Use [getPhrase()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md#getphrase) method to get access to the phrase.



## Property Summary

| Property | Description |
| --- | --- |
| [exactMatch](#exactmatch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | This method returns a flag signaling whether this phrase is a exact match. |
| [phrase](#phrase): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | This method returns the actual phrase as a string value. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md#getphrase)() | This method returns the actual phrase as a string value. |
| [isExactMatch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md#isexactmatch)() | This method returns a flag signaling whether this phrase is a exact match. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### exactMatch
- exactMatch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : This method returns a flag signaling whether this phrase is a exact match.


---

### phrase
- phrase: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : This method returns the actual phrase as a string value.


---

## Method Details

### getPhrase()
- getPhrase(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : This method returns the actual phrase as a string value.

    **Returns:**
    - the phrase


---

### isExactMatch()
- isExactMatch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : This method returns a flag signaling whether this phrase is a exact match.

    **Returns:**
    - true if this phrase is a exact match, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=e1c5a704109c8e78cb7cf8b78d8da944f2a06aeeabd824b92509a0b4e09b7e89 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SuggestedProduct.md -->

<!-- prettier-ignore-start -->
# Class SuggestedProduct

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SuggestedProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedProduct.md)

This class represents a suggested product.
Use [getProductSearchHit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedProduct.md#getproductsearchhit) method to get access to the actual [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) object.



## Property Summary

| Property | Description |
| --- | --- |
| [productSearchHit](#productsearchhit): [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) `(read-only)` | This method returns the actual [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) object  corresponding to this suggested product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedProduct.md#getproductsearchhit)() | This method returns the actual [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) object  corresponding to this suggested product. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### productSearchHit
- productSearchHit: [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) `(read-only)`
  - : This method returns the actual [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) object
      corresponding to this suggested product.



---

## Method Details

### getProductSearchHit()
- getProductSearchHit(): [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md)
  - : This method returns the actual [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md) object
      corresponding to this suggested product.


    **Returns:**
    - the product search hit corresponding to this suggested product


---

<!-- prettier-ignore-end -->

<!-- document id=303b49f85db54fb7ec010d57baa434b49497e018ce2f1a3d852949ae21cfac3c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SuggestedTerm.md -->

<!-- prettier-ignore-start -->
# Class SuggestedTerm

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)

A single suggested term.

Each user input term of the search phrase
is being processed separately by the suggestion engine. For each
original term, a list of terms will be suggested, either completed terms,
corrected terms or even the exact term if it is known to the engine.


Each suggested term is represented by a instance of this class. The list of suggested terms
belonging to a single original term is represented by a instance of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) class.


The suggested term value can either be the completed version of the original term,
the corrected version of the original term or exactly the original term.



## Property Summary

| Property | Description |
| --- | --- |
| [additional](#additional): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether this suggested term is a additional term that has no corresponding term in the original search phrase. |
| [completed](#completed): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether this suggested term is a auto completed version of the original term. |
| [corrected](#corrected): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether this suggested term is a corrected version of the original term. |
| [exactMatch](#exactmatch): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns whether this suggested term is exactly matching the original term. |
| [value](#value): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns this suggested term as String value. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md#getvalue)() | Returns this suggested term as String value. |
| [isAdditional](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md#isadditional)() | Returns whether this suggested term is a additional term that has no corresponding term in the original search phrase. |
| [isCompleted](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md#iscompleted)() | Returns whether this suggested term is a auto completed version of the original term. |
| [isCorrected](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md#iscorrected)() | Returns whether this suggested term is a corrected version of the original term. |
| [isExactMatch](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md#isexactmatch)() | Returns whether this suggested term is exactly matching the original term. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### additional
- additional: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether this suggested term is a additional term that has no corresponding term in the original search phrase.


---

### completed
- completed: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether this suggested term is a auto completed version of the original term.
      In other words, this method returns true if the original term is a prefix of this suggested term.



---

### corrected
- corrected: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether this suggested term is a corrected version of the original term.


---

### exactMatch
- exactMatch: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns whether this suggested term is exactly matching the original term.


---

### value
- value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns this suggested term as String value.


---

## Method Details

### getValue()
- getValue(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns this suggested term as String value.

    **Returns:**
    - the string representation of this suggested term


---

### isAdditional()
- isAdditional(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this suggested term is a additional term that has no corresponding term in the original search phrase.

    **Returns:**
    - `true` if this suggested term is a additional term, `false` otherwise


---

### isCompleted()
- isCompleted(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this suggested term is a auto completed version of the original term.
      In other words, this method returns true if the original term is a prefix of this suggested term.


    **Returns:**
    - `true` if this suggested term is evaluated by auto completion, `false` otherwise


---

### isCorrected()
- isCorrected(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this suggested term is a corrected version of the original term.

    **Returns:**
    - `true` if this suggested term is a corrected version of the original term, `false` otherwise


---

### isExactMatch()
- isExactMatch(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this suggested term is exactly matching the original term.

    **Returns:**
    - `true` if this suggested term exactly matches the original term, `false` otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=32a78c99f54e2db684ad68082094e5d91f3e2428dc707f79b762276647ce7858 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SuggestedTerms.md -->

<!-- prettier-ignore-start -->
# Class SuggestedTerms

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md)

This container represents a list of suggested terms, all belonging to a
particular single original term of the users input search phrase.

Each user input term of the search phrase
is being processed separately by the suggestion engine. For each
original term, a list of terms will be suggested, either completed terms,
corrected terms or even the exact term if they are known to the engine as they are.

A instance of this class refers to the original unmodified term, as well as
to a list of [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)s objects representing a single suggested term.



## Property Summary

| Property | Description |
| --- | --- |
| [empty](#empty): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns true if this set of suggested terms is empty. |
| [firstTerm](#firstterm): [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md) `(read-only)` | This method returns the suggested term which is considered best matching  with the original term. |
| [originalTerm](#originalterm): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the original term of the user input, for which this instance  provides a list of suggested terms. |
| [terms](#terms): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Returns the list of [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)s suggested for the original term. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getFirstTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getfirstterm)() | This method returns the suggested term which is considered best matching  with the original term. |
| [getOriginalTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getoriginalterm)() | Returns the original term of the user input, for which this instance  provides a list of suggested terms. |
| [getTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getterms)() | Returns the list of [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)s suggested for the original term. |
| [isEmpty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#isempty)() | Returns true if this set of suggested terms is empty. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### empty
- empty: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns true if this set of suggested terms is empty.


---

### firstTerm
- firstTerm: [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md) `(read-only)`
  - : This method returns the suggested term which is considered best matching
      with the original term. See [getTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getterms) for a note on ordering of
      suggested terms.


    **See Also:**
    - [getOriginalTerm()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getoriginalterm)
    - [getTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getterms)


---

### originalTerm
- originalTerm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the original term of the user input, for which this instance
      provides a list of suggested terms. Suggested terms can either be corrected,
      or completed or exact matching.



---

### terms
- terms: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Returns the list of [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)s suggested for the original term.

    **See Also:**
    - [getOriginalTerm()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getoriginalterm)
    - [isEmpty()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#isempty)


---

## Method Details

### getFirstTerm()
- getFirstTerm(): [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)
  - : This method returns the suggested term which is considered best matching
      with the original term. See [getTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getterms) for a note on ordering of
      suggested terms.


    **Returns:**
    - the best matching term

    **See Also:**
    - [getOriginalTerm()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getoriginalterm)
    - [getTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getterms)


---

### getOriginalTerm()
- getOriginalTerm(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the original term of the user input, for which this instance
      provides a list of suggested terms. Suggested terms can either be corrected,
      or completed or exact matching.


    **Returns:**
    - the original unmodified term of the user input search phrase


---

### getTerms()
- getTerms(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Returns the list of [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)s suggested for the original term.

    **Returns:**
    - a iterator of suggested terms, might be empty

    **See Also:**
    - [getOriginalTerm()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#getoriginalterm)
    - [isEmpty()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#isempty)


---

### isEmpty()
- isEmpty(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this set of suggested terms is empty.

    **Returns:**
    - true if no suggested term is contained in this set, false otherwise


---

<!-- prettier-ignore-end -->

<!-- document id=56aad55a57123e16f45af0e708bce6faacc90e6c441b2462b436b1be761e8f5d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.Suggestions.md -->

<!-- prettier-ignore-start -->
# Class Suggestions

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md)

This is the base class for suggestions containers.
For each type of items, a sub class provides methods to
access the actual items.


See the sub classes for more specific information.



## All Known Subclasses
[BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md), [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md), [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md), [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md), [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md)
## Property Summary

| Property | Description |
| --- | --- |
| [searchPhraseSuggestions](#searchphrasesuggestions): [SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md) `(read-only)` | Returns the suggested search phrases that are associated to this suggestions. |
| ~~[suggestedPhrases](#suggestedphrases): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~ `(read-only)` | Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the  user input search phrase. |
| ~~[suggestedTerms](#suggestedterms): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~ `(read-only)` | Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getSearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions)() | Returns the suggested search phrases that are associated to this suggestions. |
| ~~[getSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedphrases)()~~ | Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the  user input search phrase. |
| ~~[getSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms)()~~ | Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. |
| ~~[hasSuggestedPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases)()~~ | Returns whether this suggestions container has any suggested phrases. |
| ~~[hasSuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedterms)()~~ | Returns whether this suggestions container has any suggested terms. |
| [hasSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestions)() | Returns whether this suggestions container has any suggested items, i.e. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### searchPhraseSuggestions
- searchPhraseSuggestions: [SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md) `(read-only)`
  - : Returns the suggested search phrases that are associated to this suggestions.
      
      
      In contrast to the suggested items, the suggested phrases contains the corrected and
      completed versions of the original search phrase.



---

### suggestedPhrases
- ~~suggestedPhrases: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~ `(read-only)`
  - : Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the
      user input search phrase.


    **See Also:**
    - [hasSuggestedPhrases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases)

    **Deprecated:**
**warning:** Please use method [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions) to obtain the suggested search phrases.

---

### suggestedTerms
- ~~suggestedTerms: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~ `(read-only)`
  - : Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. Each of the returned
      instances represents a set of terms suggested for a particular single term
      of the user input search phrase.


    **Deprecated:**
**warning:** Please use method [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions) to obtain the suggested search phrases.

---

## Method Details

### getSearchPhraseSuggestions()
- getSearchPhraseSuggestions(): [SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md)
  - : Returns the suggested search phrases that are associated to this suggestions.
      
      
      In contrast to the suggested items, the suggested phrases contains the corrected and
      completed versions of the original search phrase.


    **Returns:**
    - the suggested search phrases for this suggestions


---

### getSuggestedPhrases()
- ~~getSuggestedPhrases(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~
  - : Returns a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md) objects that relates to the
      user input search phrase.


    **Returns:**
    - a list of [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md)s

    **See Also:**
    - [hasSuggestedPhrases()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#hassuggestedphrases)

    **Deprecated:**
**warning:** Please use method [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions) to obtain the suggested search phrases.

---

### getSuggestedTerms()
- ~~getSuggestedTerms(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)~~
  - : Returns a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) objects. Each of the returned
      instances represents a set of terms suggested for a particular single term
      of the user input search phrase.


    **Returns:**
    - a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md) for each term of the user input search phrase

    **Deprecated:**
**warning:** Please use method [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions) to obtain the suggested search phrases.

---

### hasSuggestedPhrases()
- ~~hasSuggestedPhrases(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Returns whether this suggestions container has any suggested phrases.
      
      
      Note that this method only looks for suggested phrases. It does not account
      for suggested terms or suggested objects. In other words,
      even if there are suggested terms or objects, this method
      will return false if this suggestions container has no phrases.


    **Returns:**
    - true only if there are phrases available

    **Deprecated:**
**warning:** Please use method [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions) to obtain the suggested search phrases.

---

### hasSuggestedTerms()
- ~~hasSuggestedTerms(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)~~
  - : Returns whether this suggestions container has any suggested terms.
      
      
      Note that this method checks suggested terms only,
      but not suggested phrases or suggested objects.


    **Returns:**
    - true only if there are terms available

    **Deprecated:**
**warning:** Please use method [getSearchPhraseSuggestions()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsearchphrasesuggestions) to obtain the suggested search phrases.

---

### hasSuggestions()
- hasSuggestions(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns whether this suggestions container has any suggested items, i.e. products.
      
      
      Note that this method only looks for concrete suggested items. It does not account
      for suggested terms. In other words, even if there are suggested terms, this method
      will return false if no matching items, like products or categories, were found
      for the suggested terms.
      
      
      To find out whether there are suggested terms and how they match with respect to
      the original search phrase, one can use [getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms) to obtain
      a list of [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md).


    **Returns:**
    - true only if there are items found using the suggested terms

    **See Also:**
    - [getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md#getsuggestedterms)
    - [SuggestedTerms.isEmpty()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md#isempty)


---

<!-- prettier-ignore-end -->

<!-- document id=8be822a3f324f076a1cd6625f2c6af41232d9f21c04cc917f3134d8ed629e1dc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.SuggestModel.md -->

<!-- prettier-ignore-start -->
# Class SuggestModel

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.suggest.SuggestModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md)

The Suggest model provides methods and functions
to access search suggestions.


The search suggestion feature basically covers two functional areas.
First is just to suggest words, based on the users input,
utilizing spell correction or prediction (also known as auto completion).
The second functional area is also often referred to as search-as-you-type,
where, based on the users input, specific items are
already looked up, before the user actually has completed typing a word
or even fired up the search.


This model combines both functional areas and provides access to both - the
suggested words and the items found while using the predicted words.


This model supports various types of items that are being suggested, like
products, categories, brands, content pages as well merchant provided search phrases.
For each type, there is a [Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md) implementation
available and accessible through this model: [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md),
[CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md), [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md), [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md),
and [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md).


For each type of suggestions, the actual suggested items (like
products) can by obtained, and, on the other hand, a list of terms
is provided which were used to lookup the found items.
The terms can be used to present a advanced user experience in the
storefront, e.g. show auto completed words, spell corrections and so on.
The SuggestModel script API will always create suggestions with Autocorrections
regardless of the value of "Search Autocorrections" search preference.



## Constant Summary

| Constant | Description |
| --- | --- |
| [MAX_SUGGESTIONS](#max_suggestions): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | The maximum number of suggestions that can be obtain from this model: `10` |

## Property Summary

| Property | Description |
| --- | --- |
| [brandSuggestions](#brandsuggestions): [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) `(read-only)` | Returns a [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) container for the current search phrase. |
| [categorySuggestions](#categorysuggestions): [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) `(read-only)` | Returns a [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) container for the current search phrase. |
| [contentSuggestions](#contentsuggestions): [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) `(read-only)` | Returns a [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) container for the current search phrase. |
| [customSuggestions](#customsuggestions): [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) `(read-only)` | Returns a [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) container for the current search phrase. |
| [effectiveSearchMode](#effectivesearchmode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the effective search mode that was used for the last suggestion execution. |
| [filteredByFolder](#filteredbyfolder): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | The method returns true, if the search suggestions are filtered by the folder. |
| [popularSearchPhrases](#popularsearchphrases): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Use this method to obtain a list of search phrases  that currently are very popular among all users across the Site. |
| [productSuggestions](#productsuggestions): [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) `(read-only)` | Returns a [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) container for the current search phrase. |
| [recentSearchPhrases](#recentsearchphrases): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)` | Use this method to obtain a list of personalized search phrases  that the current user entered recently. |
| [searchMode](#searchmode): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the search mode that was requested for the next suggestion execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchmodestring),  or `null` if no mode was explicitly requested. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SuggestModel](#suggestmodel)() | Constructs a new SuggestModel. |

## Method Summary

| Method | Description |
| --- | --- |
| [addRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#addrefinementvaluesstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a refinement for product suggestions. |
| [getBrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getbrandsuggestions)() | Returns a [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) container for the current search phrase. |
| [getCategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getcategorysuggestions)() | Returns a [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) container for the current search phrase. |
| [getContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getcontentsuggestions)() | Returns a [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) container for the current search phrase. |
| [getCustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getcustomsuggestions)() | Returns a [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) container for the current search phrase. |
| [getEffectiveSearchMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#geteffectivesearchmode)() | Returns the effective search mode that was used for the last suggestion execution. |
| [getPopularSearchPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getpopularsearchphrases)() | Use this method to obtain a list of search phrases  that currently are very popular among all users across the Site. |
| [getProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getproductsuggestions)() | Returns a [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) container for the current search phrase. |
| [getRecentSearchPhrases](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getrecentsearchphrases)() | Use this method to obtain a list of personalized search phrases  that the current user entered recently. |
| [getSearchMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#getsearchmode)() | Returns the search mode that was requested for the next suggestion execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchmodestring),  or `null` if no mode was explicitly requested. |
| [isFilteredByFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#isfilteredbyfolder)() | The method returns true, if the search suggestions are filtered by the folder. |
| [removeRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#removerefinementvaluesstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Removes a refinement. |
| [setCategoryID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setcategoryidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Apply a category ID to filter product, brand and category suggestions. |
| [setFilteredByFolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setfilteredbyfolderboolean)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Set a flag to indicate if the search suggestions filter for elements that do not belong to a folder. |
| [setMaxSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Use this method to setup the maximum number of returned suggested  items. |
| [setRefinementValues](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setrefinementvaluesstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets product suggestion refinement values for an attribute. |
| [setSearchMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchmodestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the search mode for the next suggestion execution. |
| [setSearchPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the user input search phrase. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### MAX_SUGGESTIONS

- MAX_SUGGESTIONS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : The maximum number of suggestions that can be obtain from this model: `10`


---

## Property Details

### brandSuggestions
- brandSuggestions: [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) `(read-only)`
  - : Returns a [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) container for the current search phrase.
      The [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) container provides access to the found brands (if any) and
      the terms suggested by the system with respect to the known product brands in the catalog.


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### categorySuggestions
- categorySuggestions: [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) `(read-only)`
  - : Returns a [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) container for the current search phrase.
      The [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) container provides access to the found categories (if any) and
      the terms suggested by the system with respect to the known categories in the catalog.


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### contentSuggestions
- contentSuggestions: [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) `(read-only)`
  - : Returns a [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) container for the current search phrase.
      The [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) container provides access to the found content pages (if any) and
      the terms suggested by the system with respect to the known content in the library.


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### customSuggestions
- customSuggestions: [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) `(read-only)`
  - : Returns a [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) container for the current search phrase.
      The [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) container provides access to matching
      custom phrases (if any) and the terms suggested
      by the system with respect to the merchant provided custom phrases.


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### effectiveSearchMode
- effectiveSearchMode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the effective search mode that was used for the last suggestion execution. This reflects the actual
      matching approach that ran, which may differ from the requested mode if a fallback occurred. Returns `null`
      if no suggestions have been executed yet.



---

### filteredByFolder
- filteredByFolder: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if the search suggestions are filtered by the folder. If this returns true it is not
      possible for search suggestions to contain Page Designer content as it belongs to no folder.



---

### popularSearchPhrases
- popularSearchPhrases: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Use this method to obtain a list of search phrases
      that currently are very popular among all users across the Site.
      
      The search phrases are specific to the region (based on user's IP address),
      language (locale) and the user's browser type (agent).



---

### productSuggestions
- productSuggestions: [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) `(read-only)`
  - : Returns a [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) container for the current search phrase.
      The [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) container provides access to the found products (if any) and
      the terms suggested by the system with respect to the known products in the catalog.


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### recentSearchPhrases
- recentSearchPhrases: [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md) `(read-only)`
  - : Use this method to obtain a list of personalized search phrases
      that the current user entered recently.
      
      The user is being identified by the CQuotient tracking cookie.



---

### searchMode
- searchMode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the search mode that was requested for the next suggestion execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchmodestring),
      or `null` if no mode was explicitly requested. This reflects the caller's requested preference, not the
      mode that actually ran — the requested mode is non-authoritative and `"semantic"` may still be demoted to
      `"lexical"` by the search router. Use [getEffectiveSearchMode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#geteffectivesearchmode) to obtain the mode that was
      actually used.



---

## Constructor Details

### SuggestModel()
- SuggestModel()
  - : Constructs a new SuggestModel.


---

## Method Details

### addRefinementValues(String, String)
- addRefinementValues(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), values: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a refinement for product suggestions.
      The method can be called to add an additional query
      parameter specified as name-value pair. The values string may encode
      multiple values delimited by the pipe symbol ('|').


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - values - the refinement value to set


---

### getBrandSuggestions()
- getBrandSuggestions(): [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md)
  - : Returns a [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) container for the current search phrase.
      The [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md) container provides access to the found brands (if any) and
      the terms suggested by the system with respect to the known product brands in the catalog.


    **Returns:**
    - a brand suggestions container for the current search phrase,
               returns `null` for insufficient search input


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### getCategorySuggestions()
- getCategorySuggestions(): [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md)
  - : Returns a [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) container for the current search phrase.
      The [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md) container provides access to the found categories (if any) and
      the terms suggested by the system with respect to the known categories in the catalog.


    **Returns:**
    - a category suggestions container for the current search phrase,
               returns `null` for insufficient search input


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### getContentSuggestions()
- getContentSuggestions(): [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md)
  - : Returns a [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) container for the current search phrase.
      The [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md) container provides access to the found content pages (if any) and
      the terms suggested by the system with respect to the known content in the library.


    **Returns:**
    - a content suggestions container for the current search phrase,
               returns `null` for insufficient search input


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### getCustomSuggestions()
- getCustomSuggestions(): [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md)
  - : Returns a [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) container for the current search phrase.
      The [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md) container provides access to matching
      custom phrases (if any) and the terms suggested
      by the system with respect to the merchant provided custom phrases.


    **Returns:**
    - a custom suggestions container for the current search phrase,
               returns `null` for insufficient search input


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### getEffectiveSearchMode()
- getEffectiveSearchMode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the effective search mode that was used for the last suggestion execution. This reflects the actual
      matching approach that ran, which may differ from the requested mode if a fallback occurred. Returns `null`
      if no suggestions have been executed yet.


    **Returns:**
    - `"semantic"` if the query ran against the external search provider, `"lexical"` if it ran
              against the native search, or `null` if no suggestions have been executed yet



---

### getPopularSearchPhrases()
- getPopularSearchPhrases(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Use this method to obtain a list of search phrases
      that currently are very popular among all users across the Site.
      
      The search phrases are specific to the region (based on user's IP address),
      language (locale) and the user's browser type (agent).


    **Returns:**
    - a list of personalized popular search phrases


---

### getProductSuggestions()
- getProductSuggestions(): [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md)
  - : Returns a [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) container for the current search phrase.
      The [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md) container provides access to the found products (if any) and
      the terms suggested by the system with respect to the known products in the catalog.


    **Returns:**
    - a product suggestions container for the current search phrase,
               returns `null` for insufficient search input


    **See Also:**
    - [setMaxSuggestions(Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setmaxsuggestionsnumber)
    - [setSearchPhrase(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchphrasestring)


---

### getRecentSearchPhrases()
- getRecentSearchPhrases(): [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)
  - : Use this method to obtain a list of personalized search phrases
      that the current user entered recently.
      
      The user is being identified by the CQuotient tracking cookie.


    **Returns:**
    - a list of recent search phrases of the current user


---

### getSearchMode()
- getSearchMode(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the search mode that was requested for the next suggestion execution via [setSearchMode(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#setsearchmodestring),
      or `null` if no mode was explicitly requested. This reflects the caller's requested preference, not the
      mode that actually ran — the requested mode is non-authoritative and `"semantic"` may still be demoted to
      `"lexical"` by the search router. Use [getEffectiveSearchMode()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#geteffectivesearchmode) to obtain the mode that was
      actually used.


    **Returns:**
    - `"semantic"` or `"lexical"` if a mode was requested, or `null` if no mode was requested


---

### isFilteredByFolder()
- isFilteredByFolder(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The method returns true, if the search suggestions are filtered by the folder. If this returns true it is not
      possible for search suggestions to contain Page Designer content as it belongs to no folder.


    **Returns:**
    - True if search suggestions are filtered by the folder of the content asset.


---

### removeRefinementValues(String, String)
- removeRefinementValues(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), values: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Removes a refinement. The method can be called to remove previously added
      refinement values. The values string may encode multiple values delimited
      by the pipe symbol ('|').


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - values - the refinement value to remove or null to remove all values


---

### setCategoryID(String)
- setCategoryID(categoryID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Apply a category ID to filter product, brand and category suggestions.
      
      
      Suggested products, brands and categories, as well as corrected and completed
      terms are specific to the given category or one of it's sub categories.
      
      
      For example, in the specified category "television", the search term "pla"
      will be auto completed to "plasma" (instead of e.g. "player") and
      only televisions will be included in the list of suggested products.


    **Parameters:**
    - categoryID - the category to filter suggestions for


---

### setFilteredByFolder(Boolean)
- setFilteredByFolder(filteredByFolder: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Set a flag to indicate if the search suggestions filter for elements that do not belong to a folder.
      Must be set to false to return content assets that do not belong to any folder.


    **Parameters:**
    - filteredByFolder - filter the search suggestions by folder


---

### setMaxSuggestions(Number)
- setMaxSuggestions(maxSuggestions: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Use this method to setup the maximum number of returned suggested
      items. For example, set this to 3 in order to only retrieve the
      3 most relevant suggested products.
      
      
      The maximum number of suggestions that can be queried are defined as [MAX_SUGGESTIONS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md#max_suggestions).


    **Parameters:**
    - maxSuggestions - the number of suggested items to be returned by this model instance


---

### setRefinementValues(String, String)
- setRefinementValues(attributeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), values: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets product suggestion refinement values for an attribute.
      The method can be called to set
      an additional query parameter specified as name-value pair. The value
      string may encode multiple values delimited by the pipe symbol ('|').
      Existing refinement values for the attribute will be removed.


    **Parameters:**
    - attributeID - The ID of the refinement attribute.
    - values - the refinement values to set (delimited by '|') or null to             remove all values


---

### setSearchMode(String)
- setSearchMode(mode: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the search mode for the next suggestion execution. The mode influences the routing decision made by the
      search router, but is non-authoritative — `"semantic"` still runs the full routing cascade and may be
      demoted to `"lexical"` based on availability and query characteristics.


    **Parameters:**
    - mode - the search mode to request, either `"semantic"` or `"lexical"`

    **Throws:**
    - IllegalArgumentException - if the mode is not one of the allowed values


---

### setSearchPhrase(String)
- setSearchPhrase(searchPhrase: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the user input search phrase. This search phrase is being processed
      by applying auto completion, spell correction and enhancement with alternative
      similar search terms.
      
      
      The resulting search phrase is used to lookup the actual items,
      like products or categories (search-as-you-type).
      
      
      In order to access the processed terms, one can use the
      [SearchPhraseSuggestions.getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms) method of each of the respective
      results returned by the methods in this model.


    **Parameters:**
    - searchPhrase - the user input search phrase

    **See Also:**
    - [SearchPhraseSuggestions.getSuggestedTerms()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md#getsuggestedterms)


---

<!-- prettier-ignore-end -->

<!-- document id=27e255bffd2f4870bb18e8ae02bb18bbc7c0013db385533040aa728a6eb451f4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.SumItem.md -->

<!-- prettier-ignore-start -->
# Class SumItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md)

Container used to represent an subtotal or grandtotal item which contains various prices and a tax breakdown
held in a collection of tax-items.


**Usage example:**

```
var invoice : Invoice = ...;
var productNet = invoice.productSubTotal.netPrice;
var serviceNet = invoice.serviceSubTotal.netPrice;
var grandNet   = invoice.grandTotal.netPrice;
var grandTax   = invoice.grandTotal.tax;
var grandGross = invoice.grandTotal.grossPrice;

# tax breakdown
for each(taxItem : TaxItem in invoice.grandTotal.taxItems) {
  var tax : Money         = taxItem.amount;
  var taxGroup : TaxGroup = taxItem.taxGroup;
  var rate : Double       = taxGroup.rate;
  var caption :String     = taxGroup.caption;
  var taxType :String     = taxGroup.taxType;
}
```



## Property Summary

| Property | Description |
| --- | --- |
| [grossPrice](#grossprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Gross price of SumItem. |
| [netPrice](#netprice): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Net price of SumItem. |
| [tax](#tax): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Total tax for SumItem. |
| [taxBasis](#taxbasis): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Price of entire SumItem on which tax calculation is based. |
| [taxItems](#taxitems): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Tax items representing a tax breakdown for the SumItem. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getGrossPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#getgrossprice)() | Gross price of SumItem. |
| [getNetPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#getnetprice)() | Net price of SumItem. |
| [getTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#gettax)() | Total tax for SumItem. |
| [getTaxBasis](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#gettaxbasis)() | Price of entire SumItem on which tax calculation is based. |
| [getTaxItems](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#gettaxitems)() | Tax items representing a tax breakdown for the SumItem. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### grossPrice
- grossPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Gross price of SumItem.


---

### netPrice
- netPrice: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Net price of SumItem.


---

### tax
- tax: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Total tax for SumItem.


---

### taxBasis
- taxBasis: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Price of entire SumItem on which tax calculation is based. Same as [getNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#getnetprice)
      or [getGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#getgrossprice) depending on whether the order is based on net or gross prices.



---

### taxItems
- taxItems: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Tax items representing a tax breakdown for the SumItem.

    **See Also:**
    - [TaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md)


---

## Method Details

### getGrossPrice()
- getGrossPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Gross price of SumItem.

    **Returns:**
    - Gross price of SumItem.


---

### getNetPrice()
- getNetPrice(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Net price of SumItem.

    **Returns:**
    - Net price of SumItem.


---

### getTax()
- getTax(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Total tax for SumItem.

    **Returns:**
    - Total tax for SumItem.


---

### getTaxBasis()
- getTaxBasis(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Price of entire SumItem on which tax calculation is based. Same as [getNetPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#getnetprice)
      or [getGrossPrice()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md#getgrossprice) depending on whether the order is based on net or gross prices.


    **Returns:**
    - Price of entire item on which tax calculation is based


---

### getTaxItems()
- getTaxItems(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Tax items representing a tax breakdown for the SumItem.

    **Returns:**
    - tax items representing a tax breakdown for the SumItem

    **See Also:**
    - [TaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md)


---

<!-- prettier-ignore-end -->

<!-- document id=11953ecc5bcf55cc1b9adafdb38137947afeff11a38c42be1e0f0fa3d7dfaa01 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Symbol.md -->

<!-- prettier-ignore-start -->
# Class Symbol

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)

Symbol is a primitive data type that can serve as object properties.
Symbol instance can be created explicitly or via a global registry, see [for(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md#forstring---variant-1).


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [hasInstance](#hasinstance): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by `instanceof`. |
| [isConcatSpreadable](#isconcatspreadable): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by [Array.concat(Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#concatobject). |
| [iterator](#iterator): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by `for...of`. |
| [match](#match): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by [String.match(RegExp)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#matchregexp). |
| [replace](#replace): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by `String.replace()`. |
| [search](#search): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by [String.search(RegExp)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#searchregexp). |
| [species](#species): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used to create derived objects. |
| [split](#split): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by `String.split()`. |
| [toPrimitive](#toprimitive): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used to convert an object to a primitive value. |
| [toStringTag](#tostringtag): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by [Object.toString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring). |
| [unscopables](#unscopables): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md) | The symbol used by `with`. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Symbol](#symbol)() | Creates a new symbol. |
| [Symbol](#symbolstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new symbol. |

## Method Summary

| Method | Description |
| --- | --- |
| static [for](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md#forstring---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Obtains a symbol from the global registry. |
| static [keyFor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md#keyforsymbol)([Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)) | Returns the key within the global symbol registry under which the given symbol is stored. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### hasInstance

- hasInstance: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by `instanceof`.


---

### isConcatSpreadable

- isConcatSpreadable: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by [Array.concat(Object...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md#concatobject).


---

### iterator

- iterator: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by `for...of`.


---

### match

- match: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by [String.match(RegExp)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#matchregexp).


---

### replace

- replace: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by `String.replace()`.


---

### search

- search: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by [String.search(RegExp)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md#searchregexp).


---

### species

- species: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used to create derived objects.


---

### split

- split: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by `String.split()`.


---

### toPrimitive

- toPrimitive: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used to convert an object to a primitive value.


---

### toStringTag

- toStringTag: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by [Object.toString()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring).


---

### unscopables

- unscopables: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : The symbol used by `with`.


---

## Constructor Details

### Symbol()
- Symbol()
  - : Creates a new symbol. Note that it must be called without `new`.
      Symbols created via this method are always distinct.



---

### Symbol(String)
- Symbol(description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new symbol. Note that it must be called without `new`.
      Symbols created via this method are always distinct.


    **Parameters:**
    - description - A description for this symbol.


---

## Method Details

### for(String) - Variant 1
- static for(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)
  - : Obtains a symbol from the global registry. If no symbol exists for the key within the registry a new symbol is
      created and stored in the global registry.


    **Parameters:**
    - key - The key for a symbol within the global registry.

    **Returns:**
    - The found or newly created symbol.

    **API Version:**
**note:** Available from version 21.2.

---

### keyFor(Symbol)
- static keyFor(symbol: [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the key within the global symbol registry under which the given symbol is stored.

    **Parameters:**
    - symbol - The symbol to look for.

    **Returns:**
    - The key for the given symbol if the symbol is known to the global registry, else return `undefined`.


---

<!-- prettier-ignore-end -->

<!-- document id=c5e3d70a11a9dfc87758d393756af4ee53d31dfa02729a437acc9d57d123af22 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.SyntaxError.md -->

<!-- prettier-ignore-start -->
# Class SyntaxError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.SyntaxError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.SyntaxError.md)

Represents a syntax error.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SyntaxError](#syntaxerror)() | Constructs the error. |
| [SyntaxError](#syntaxerrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the   specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### SyntaxError()
- SyntaxError()
  - : Constructs the error.


---

### SyntaxError(String)
- SyntaxError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the 
      specified message.


    **Parameters:**
    - msg - the syntax error message.


---

<!-- prettier-ignore-end -->

<!-- document id=4d203c7c4d79e9cc352e0681607722f2f9fc218d3fc36040c54e13a2888ab665 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.System.md -->

<!-- prettier-ignore-start -->
# Class System

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.System](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md)

Represents the Commerce Cloud Digital server instance. An application server instance is configured to be of one of three types,
"development system", "staging system" or "production system".



## Constant Summary

| Constant | Description |
| --- | --- |
| [DEVELOPMENT_SYSTEM](#development_system): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Represents the development system. |
| [PRODUCTION_SYSTEM](#production_system): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Represents the production system. |
| [STAGING_SYSTEM](#staging_system): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Represents the staging system. |

## Property Summary

| Property | Description |
| --- | --- |
| [calendar](#calendar): [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md) `(read-only)` | Returns a new Calendar object in the time zone of the  current instance. |
| [compatibilityMode](#compatibilitymode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the compatibility mode of the custom code version that is currently active. |
| [instanceHostname](#instancehostname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns instance hostname. |
| [instanceTimeZone](#instancetimezone): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the instance time zone. |
| [instanceType](#instancetype): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the type of the instance. |
| [preferences](#preferences): [OrganizationPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.OrganizationPreferences.md) `(read-only)` | This method returns a container of all global preferences of this  organization (instance). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getCalendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getcalendar)() | Returns a new Calendar object in the time zone of the  current instance. |
| static [getCompatibilityMode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getcompatibilitymode)() | Returns the compatibility mode of the custom code version that is currently active. |
| static [getInstanceHostname](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getinstancehostname)() | Returns instance hostname. |
| static [getInstanceTimeZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getinstancetimezone)() | Returns the instance time zone. |
| static [getInstanceType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getinstancetype)() | Returns the type of the instance. |
| static [getPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#getpreferences)() | This method returns a container of all global preferences of this  organization (instance). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DEVELOPMENT_SYSTEM

- DEVELOPMENT_SYSTEM: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Represents the development system.


---

### PRODUCTION_SYSTEM

- PRODUCTION_SYSTEM: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Represents the production system.


---

### STAGING_SYSTEM

- STAGING_SYSTEM: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Represents the staging system.


---

## Property Details

### calendar
- calendar: [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md) `(read-only)`
  - : Returns a new Calendar object in the time zone of the
      current instance.



---

### compatibilityMode
- compatibilityMode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the compatibility mode of the custom code version that is currently active. The compatibility mode is
      returned as a number, e.g. compatibility mode "15.5" is returned as 1505.



---

### instanceHostname
- instanceHostname: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns instance hostname.


---

### instanceTimeZone
- instanceTimeZone: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the instance time zone. The instance time zone is the time zone in which global actions like jobs or
      reporting are specified in the system. Keep in mind that the instance time zone is cached at the current session.
      Changes will affect only new sessions.



---

### instanceType
- instanceType: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the type of the instance. An application server instance is configured to be of one of three types,
      "development system", "staging system" or "production system".
      
      This method returns a constant representing the instance type of **this**
      application server.


    **See Also:**
    - [DEVELOPMENT_SYSTEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#development_system)
    - [PRODUCTION_SYSTEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#production_system)
    - [STAGING_SYSTEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#staging_system)


---

### preferences
- preferences: [OrganizationPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.OrganizationPreferences.md) `(read-only)`
  - : This method returns a container of all global preferences of this
      organization (instance).



---

## Method Details

### getCalendar()
- static getCalendar(): [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)
  - : Returns a new Calendar object in the time zone of the
      current instance.


    **Returns:**
    - a Calendar object in the time zone of the
              instance.



---

### getCompatibilityMode()
- static getCompatibilityMode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the compatibility mode of the custom code version that is currently active. The compatibility mode is
      returned as a number, e.g. compatibility mode "15.5" is returned as 1505.


    **Returns:**
    - The currently active compatibility mode.


---

### getInstanceHostname()
- static getInstanceHostname(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns instance hostname.

    **Returns:**
    - instance hostname.


---

### getInstanceTimeZone()
- static getInstanceTimeZone(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the instance time zone. The instance time zone is the time zone in which global actions like jobs or
      reporting are specified in the system. Keep in mind that the instance time zone is cached at the current session.
      Changes will affect only new sessions.


    **Returns:**
    - the instance time zone.


---

### getInstanceType()
- static getInstanceType(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the type of the instance. An application server instance is configured to be of one of three types,
      "development system", "staging system" or "production system".
      
      This method returns a constant representing the instance type of **this**
      application server.


    **Returns:**
    - the instance type of the application server where this method was
              called.


    **See Also:**
    - [DEVELOPMENT_SYSTEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#development_system)
    - [PRODUCTION_SYSTEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#production_system)
    - [STAGING_SYSTEM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md#staging_system)


---

### getPreferences()
- static getPreferences(): [OrganizationPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.OrganizationPreferences.md)
  - : This method returns a container of all global preferences of this
      organization (instance).


    **Returns:**
    - a preferences object containing all global system and custom
              preferences of this instance



---

<!-- prettier-ignore-end -->

<!-- document id=49e1f9e7904a4dcae502a18a6e00598bbf28326494286c8b27d39a508cde3f6e url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.SystemError.md -->

<!-- prettier-ignore-start -->
# Class SystemError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.SystemError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.SystemError.md)

This error indicates an error in the system, which doesn't fall into
any of the other error categories like for example IOError. The SystemError
is always related to a systems internal Java exception. The class provides
access to some more details about this internal Java exception.



## Property Summary

| Property | Description |
| --- | --- |
| [causeFullName](#causefullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the full name of the associated Java exception. |
| [causeMessage](#causemessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the message of the associated Java exception. |
| [causeName](#causename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the simplified name of the associated Java exception. |
| [javaFullName](#javafullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The full name of the underlying Java exception. |
| [javaMessage](#javamessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The message of the underlying Java exception. |
| [javaName](#javaname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The simplified name of the underlying Java exception. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [SystemError](#systemerror)() |  |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### causeFullName
- causeFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the full name of the associated Java exception.



---

### causeMessage
- causeMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the message of the associated Java exception.



---

### causeName
- causeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the simplified name of the associated Java exception.



---

### javaFullName
- javaFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The full name of the underlying Java exception.


---

### javaMessage
- javaMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The message of the underlying Java exception.


---

### javaName
- javaName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The simplified name of the underlying Java exception.


---

## Constructor Details

### SystemError()
- SystemError()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=fe782811d388f584b7717db812cc5b55d1d6e7c6c9f8a78756e60ef225be6450 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.SystemObjectMgr.md -->

<!-- prettier-ignore-start -->
# Class SystemObjectMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.SystemObjectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md)

Manager class which provides methods for querying of system objects with
meta data using the Commerce Cloud Digital query language. See individual API methods for
details on the query language.


Note: Other manager classes such as [CustomerMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md),
[ProductMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md), etc provide more specific and fine-grained
querying methods that can not be achieved using the general query language.



The following system object types are supported:


- GiftCertificate
- SourceCodeGroup
- Store
- ProductList


Support for the following system object types is deprecated:


- Order
- Profile


Use the search methods from [CustomerMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md) and [OrderMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md),
respectively for querying these types.


To search for custom objects, use [CustomObjectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md).
**Note:** this class allows access to sensitive information through
operations that retrieve the Profile and Order objects.
Pay attention to appropriate legal and regulatory requirements related to this data.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md#describestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the object type definition for the given system object type. |
| static [getAllSystemObjects](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md#getallsystemobjectsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all system objects of a specific type. |
| static [querySystemObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md#querysystemobjectstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Searches for a single system object instance. |
| static [querySystemObjects](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md#querysystemobjectsstring-map-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | <p>  Searches for system object instances. |
| static [querySystemObjects](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md#querysystemobjectsstring-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | <p>  Searches for system object instances. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### describe(String)
- static describe(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)
  - : Returns the object type definition for the given system object type.
      
      This method can be used for all system object types that are derived from ExtensibleObject.


    **Parameters:**
    - type - system object type whose type definition should be returned

    **Returns:**
    - the matching object type definition or `null` in case no
               such type definition exists.



---

### getAllSystemObjects(String)
- static getAllSystemObjects(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : Returns all system objects of a specific type.
      The following system object types are supported:
      
      - GiftCertificate
      - Order
      - Profile
      - SourceCodeGroup
      - Store
      - ProductList
      
      
      
      The method throws an exception in case of another system type.
      
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator
      if not all of its elements are being retrieved. This will ensure the proper cleanup of system resources.


    **Parameters:**
    - type - The name of the system object type.                If a matching type definition cannot be found for the given type a                MetaDataException will be thrown.

    **Returns:**
    - SeekableIterator containing all system objects of a specific type.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### querySystemObject(String, String, Object...)
- static querySystemObject(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
  - : 
      
      Searches for a single system object instance. The following system object types are supported:
      
      
      - GiftCertificate
      - Order
      - Profile
      - SourceCodeGroup
      - Store
      - ProductList
      
      
      
      
      
      The method throws an exception in case of another system type.
      
      
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality.
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom defined attributes the prefix custom is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      The following types of attributes are not queryable:
      
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      Note, that some system attributes are not queryable by default regardless of the actual value type code.
      
      
      
      
      The following **operators** are supported in a condition:
      
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number and Date types only
      - `>`Greater than - Integer, Number and Date types only
      - `<=`Less or equals than - Integer, Number and Date types only
      - `>=`Greater or equals than - Integer, Number and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search(`custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only, use to support case insensitive query  (`custom.country ILIKE 'usa'`), does also support wildcards for substring matching
      
      
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT' and nested using parenthesis e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1' and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      
      
      If there is more than one object matching the specified query criteria, the result is not deterministic. In order
      to retrieve a single object from a sorted result set it is recommended to use the following code:
      `querySystemObjects("", "custom.myAttr asc", null).first()`. The method `first()` returns
      only the next element and closes the iterator.
      
      
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator if not all of its
      elements are being processed. This will enable the cleanup of system resources.
      
      
      
      
      This method does not consider locale specific attributes. It returns all objects by checking the default
      non-localizable attributes. Any locale specific filtering after fetching the objects must be done by other custom
      code.
      
      Example: For store objects, such a locale specific filtering can be:
      
      - Get the store objects using this method with non-localized attributes query.
      - Access the `store.getCustom("myattr")`. It returns the localized value of the attribute.


    **Parameters:**
    - type - the system object type for the query.
    - queryString - the actual query.
    - args - optional parameters for the queryString.

    **Returns:**
    - the system object defined by `type` which was found when executing the
              `queryString`.


    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### querySystemObjects(String, Map, String)
- static querySystemObjects(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), queryAttributes: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      
      Searches for system object instances. The following system object types are supported:
      
      
      - GiftCertificate
      - Order
      - Profile
      - SourceCodeGroup
      - Store
      - ProductList
      
      
      
      
      
      The method throws an exception in case of another system type.
      
      
      
      
      The search can be configured with a map, which key-value pairs are converted into a query expression. The
      key-value pairs are turned into a sequence of '=' or 'like' conditions, which are combined with AND statements.
      
      
      
      
      Example:
      
      A map with the key/value pairs: _'name'/'tom\*', 'age'/66_ will be converted as follows:
      `"name like 'tom*' and age = 66"`
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom defined attributes the prefix custom is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      The following types of attributes are not queryable:
      
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      Note, that some system attributes are not queryable by default regardless of the actual value type code.
      
      
      
      
      The **sorting** parameter is optional and may contain a comma separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). Default
      sorting directions is ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator if not all of its
      elements are being retrieved. This will ensure the proper cleanup of system resources.
      
      
      
      
      This method does not consider locale specific attributes. It returns all objects by checking the default
      non-localizable attributes. Any locale specific filtering after fetching the objects must be done by other custom
      code.
      
      Example: For store objects, such a locale specific filtering can be:
      
      - Get the store objects using this method with non-localized attributes query.
      - Access the `store.getCustom("myattr")`. It returns the localized value of the attribute.


    **Parameters:**
    - type - the system object type for the query.
    - queryAttributes - key-value pairs, which define the query.
    - sortString - an optional sorting or null if no sorting is necessary.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

### querySystemObjects(String, String, String, Object...)
- static querySystemObjects(type: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), queryString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), sortString: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)
  - : 
      
      Searches for system object instances. The following system object types are supported:
      
      
      - GiftCertificate
      - Order
      - Profile
      - SourceCodeGroup
      - Store
      - ProductList
      
      
      
      
      
      The method throws an exception in case of another system type.
      
      
      
      
      The search can be configured using a simple query language, which provides most common filter and operator
      functionality.
      
      
      
      
      The identifier for an **attribute** to use in a query condition is always the ID of the attribute as defined
      in the type definition. For custom defined attributes the prefix custom is required in the search term (e.g.
      `custom.color = {1}`), while for system attributes no prefix is used (e.g. `name = {4}`).
      
      
      
      
      Supported attribute value **types** with sample expression values:
      
      - _String_`'String', 'Str*', 'Strin?'`
      - _Integer_`1, 3E4`
      - _Number_`1.0, 3.99E5`
      - _Date_`yyyy-MM-dd e.g. 2007-05-31 (Default TimeZone = UTC)`
      - _DateTime_`yyyy-MM-dd'T'hh:mm:ss+Z e.g. 2007-05-31T00:00+Z (Z TimeZone = UTC) or 2007-05-31T00:00:00`
      - _Boolean_`true, false`
      - _Email_`'search@demandware.com', '*@demandware.com'`
      - _Set of String_`'String', 'Str*', 'Strin?'`
      - _Set of Integer_`1, 3E4`
      - _Set of Number_`1.0, 3.99E5`
      - _Enum of String_`'String', 'Str*', 'Strin?'`
      - _Enum of Integer_`1, 3E4`
      
      
      
      The following types of attributes are not queryable:
      
      
      - _Image_
      - _HTML_
      - _Text_
      - _Quantity_
      - _Password_
      
      
      
      Note, that some system attributes are not queryable by default regardless of the actual value type code.
      
      
      
      
      The following **operators** are supported in a condition:
      
      
      - `=`Equals - All types; supports NULL value (`thumbnail = NULL`)
      - `!=`Not equals - All types; supports NULL value (`thumbnail != NULL`)
      - `<`Less than - Integer, Number and Date types only
      - `>`Greater than - Integer, Number and Date types only
      - `<=`Less or equals than - Integer, Number and Date types only
      - `>=`Greater or equals than - Integer, Number and Date types only
      - `LIKE`Like - String types and Email only; use if leading or trailing wildcards will be used to  support substring search(`custom.country LIKE 'US*'`)
      - `ILIKE`Caseindependent Like - String types and Email only, use to support case insensitive query  (`custom.country ILIKE 'usa'`), does also support wildcards for substring matching
      
      
      
      
      
      Conditions can be combined using logical expressions 'AND', 'OR' and 'NOT' and nested using parenthesis e.g.
      `gender = {1} AND (age >= {2} OR (NOT profession LIKE {3}))`.
      
      
      
      
      The query language provides a placeholder syntax to pass objects as additional search parameters. Each passed
      object is related to a placeholder in the query string. The placeholder must be an Integer that is surrounded by
      braces. The first Integer value must be '0', the second '1' and so on, e.g.
      `querySystemObjects("sample", "age = {0} or creationDate >= {1}", 18, date)`
      
      
      
      
      The **sorting** parameter is optional and may contain a comma separated list of attribute names to sort by.
      Each sort attribute name may be followed by an optional sort direction specifier ('asc' | 'desc'). Default
      sorting directions is ascending, if no direction was specified.
      
      Example: `age desc, name`
      
      Please note that specifying a localized custom attribute as the sorting attribute is currently not supported.
      
      
      
      
      Sometimes it is desired to get all instances of specified type with a special sorting condition. This can be
      easily done by providing the 'type' of the system object and the 'sortString' in combination with an empty
      'queryString', e.g. `querySystemObjects("sample", "", "ID asc")`
      
      
      
      
      It is strongly recommended to call `close()` on the returned SeekableIterator if not all of its
      elements are being retrieved. This will ensure the proper cleanup of system resources.
      
      
      
      
      This method does not consider locale specific attributes. It returns all objects by checking the default
      non-localizable attributes. Any locale specific filtering after fetching the objects must be done by other custom
      code.
      
      Example: For store objects, such a locale specific filtering can be:
      
      - Get the store objects using this method with non-localized attributes query.
      - Access the `store.getCustom("myattr")`. It returns the localized value of the attribute.


    **Parameters:**
    - type - the system object type for the query.
    - queryString - the actual query.
    - sortString - an optional sorting or null if no sorting is necessary.
    - args - optional parameters for the queryString.

    **Returns:**
    - SeekableIterator containing the result set of the query.

    **See Also:**
    - [SeekableIterator.close()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md#close)


---

<!-- prettier-ignore-end -->

<!-- document id=45159611f67e7d7ca307551cdaa5ead509ae0759ebd2be50897c8d257fb50b13 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.TaxGroup.md -->

<!-- prettier-ignore-start -->
# Class TaxGroup

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)

Contains the formal definition of a tax including a type (it's just the key), a [percentage value](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getrate)
if provided, a [caption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getcaption) and a [description](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getdescription).



## Property Summary

| Property | Description |
| --- | --- |
| [caption](#caption): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the caption. |
| [description](#description): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the description. |
| [rate](#rate): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Gets the percentage amount of the rate. |
| [taxType](#taxtype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Gets the tax type. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#createstring-string-string-decimal)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)) | Creates a TaxGroup. |
| [getCaption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getcaption)() | Gets the caption. |
| [getDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getdescription)() | Gets the description. |
| [getRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getrate)() | Gets the percentage amount of the rate. |
| [getTaxType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#gettaxtype)() | Gets the tax type. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### caption
- caption: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the caption.


---

### description
- description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the description.


---

### rate
- rate: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Gets the percentage amount of the rate.


---

### taxType
- taxType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Gets the tax type.


---

## Method Details

### create(String, String, String, Decimal)
- static create(taxType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), caption: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), description: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), taxRate: [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)): [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)
  - : Creates a TaxGroup. 
      
      This TaxGroup can be used for example in [ReturnItem.addTaxItem(Decimal, TaxGroup)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md#addtaxitemdecimal-taxgroup).


    **Parameters:**
    - taxType - the tax type
    - caption - the caption
    - description - the description
    - taxRate - the tax rate as floating point.              `1.0` means 100 %.

    **Returns:**
    - the tax group


---

### getCaption()
- getCaption(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the caption.

    **Returns:**
    - the caption


---

### getDescription()
- getDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the description.

    **Returns:**
    - the description


---

### getRate()
- getRate(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Gets the percentage amount of the rate.

    **Returns:**
    - the tax rate percentage value


---

### getTaxType()
- getTaxType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the tax type.

    **Returns:**
    - the tax type


---

<!-- prettier-ignore-end -->

<!-- document id=3208a6eb563deca958f72804b866dab942d8bc107ba8cb8e76b1a871ba4b1354 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.TaxHooks.md -->

<!-- prettier-ignore-start -->
# Class TaxHooks

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.hooks.TaxHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md)

This interface represents tax extension points for Commerce App tax providers.


These hooks provide integration points for external tax calculation services installed via the Commerce App
framework. They are distinct from the legacy `dw.order.calculateTax` extension point.


**IMPORTANT:** These hooks should **only** be implemented and registered by Commerce Apps
(applications installed via the Commerce App framework with a CAP file). They are not intended for custom merchant
cartridges or storefront implementations. Merchants who want custom tax calculation logic should use the legacy
`dw.order.calculateTax` extension point instead.


Hook Registration A function must be defined inside a JavaScript source and must be exported. The script
with the exported hook function must be located inside a site cartridge. Inside the site cartridge a
`package.json` file with a 'hooks' entry must exist:


```
"hooks": "./hooks.json"
```



The hooks entry links to a JSON file, relative to the `package.json` file. This file lists all registered
hooks inside the hooks property:




```
"hooks": [
   {"name": "sfcc.app.tax.calculate", "script": "./calculate.js"},
   {"name": "sfcc.app.tax.commit", "script": "./commit.js"},
   {"name": "sfcc.app.tax.cancel", "script": "./cancel.js"}
]
```



A hook entry has a `name` and a `script` property:



- The `name`contains the extension point name (the hook name).
- The `script`contains the script path relative to the hooks file, with the exported hook  function.



**Function Naming Convention:** The exported JavaScript function name must match the last segment of the
extension point name, for example, `calculate`, `commit`, `cancel`..


Order Lifecycle Context Each hook fires at a specific point in the order lifecycle:

- **calculate:**Fires during basket calculation on every basket operation (e.g., adding items,  changing quantities, updating shipping). Calculates tax amounts for the basket line items.
- **commit:**Fires immediately after successful order creation (order status `CREATED`).  Notifies the tax provider that the order has been created and tax amounts should be committed.
- **cancel:**Fires on order cancellation or failure. Notifies the tax provider to void or cancel  previously committed tax amounts.

Hook Precedence

- When `sfcc.app.tax.calculate`is registered, it takes precedence over the legacy  `dw.order.calculateTax`hook.
- If the Commerce App hook is not registered, the platform falls back to `dw.order.calculateTax`(if  registered).
- If neither hook is available, the platform uses default platform tax calculation.



**Important:** If you override the `dw.order.calculate` hook (the parent basket calculation
hook), the platform's tax hook selection logic is bypassed entirely. In this case, if you want to use Commerce App
tax providers, you must manually invoke the `sfcc.app.tax.calculate` hook from within your custom
`dw.order.calculate` implementation.


SCAPI Behavior


SCAPI requests with `ScapiHookExecutionEnabled` disabled bypass all hooks (both Commerce App tax hooks and
the legacy `dw.order.calculateTax` hook) and go straight to the default platform tax calculation.


Hook Arguments and Return Types

- **calculate:**Receives a `dw.order.LineItemCtnr`(typically a  `dw.order.Basket`) as the first argument. Must return a `dw.system.Status`object (or  `null`for success).
- **commit:**Receives a `dw.order.Order`object as the first argument. Must return a  `dw.system.Status`object (or `null`for success).
- **cancel:**Receives a `dw.order.Order`object as the first argument. Must return a  `dw.system.Status`object (or `null`for success).

Error Handling
For calculate hook:

- **Always blocks on error:**Both returning a `Status.ERROR`and throwing an exception  prevent the basket calculation from completing successfully. The platform logs the error and halts the current basket  operation. Since order creation requires a successful basket calculation, this also prevents orders from being  created with incorrect tax amounts.

For commit hook:


The Commerce App developer chooses whether errors should block order creation by how they handle errors in their hook
implementation:



- **Non-blocking error:**Catch exceptions and return a `Status.ERROR`. The platform logs  the error as a warning and continues with the order lifecycle. Use this when the tax provider is temporarily  unavailable but the order should still be created.    
  ```
  return new Status(Status.ERROR, 'TAX_COMMIT_FAILED', 'Details about the failure');
  ```

- **Blocking error:**Let exceptions propagate (don't catch them). The platform logs the error and  rolls back the order lifecycle operation, preventing the order from being created.    
  ```
  throw new Error('Tax provider unavailable');
  ```


For cancel hook:


The Commerce App developer chooses whether errors should block order cancellation by how they handle errors in their
hook implementation:



- **Non-blocking error:**Catch exceptions and return a `Status.ERROR`. The platform logs  the error as a warning and continues with the order lifecycle. Use this when the tax provider is temporarily  unavailable but the order cancellation should still proceed.    
  ```
  return new Status(Status.ERROR, 'TAX_CANCEL_FAILED', 'Details about the failure');
  ```

- **Blocking error:**Let exceptions propagate (don't catch them). The platform logs the error and  rolls back the order cancellation operation.    
  ```
  throw new Error('Tax provider unavailable');
  ```



## Constant Summary

| Constant | Description |
| --- | --- |
| [extensionPointAppCalculateTax](#extensionpointappcalculatetax): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.tax.calculate" | The extension point name sfcc.app.tax.calculate. |
| [extensionPointAppCancelTax](#extensionpointappcanceltax): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.tax.cancel" | The extension point name sfcc.app.tax.cancel. |
| [extensionPointAppCommitTax](#extensionpointappcommittax): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.tax.commit" | The extension point name sfcc.app.tax.commit. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [calculate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#calculatelineitemctnr)([LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)) | The function is called by extension point [extensionPointAppCalculateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#extensionpointappcalculatetax). |
| [cancel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#cancelorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | The function is called by extension point [extensionPointAppCancelTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#extensionpointappcanceltax) during OrderMgr.failOrder() or  OrderMgr.cancelOrder(). |
| [commit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#commitorder)([Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)) | The function is called by extension point [extensionPointAppCommitTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#extensionpointappcommittax) during order creation in the order  creation transaction. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### extensionPointAppCalculateTax

- extensionPointAppCalculateTax: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.tax.calculate"
  - : The extension point name sfcc.app.tax.calculate.


---

### extensionPointAppCancelTax

- extensionPointAppCancelTax: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.tax.cancel"
  - : The extension point name sfcc.app.tax.cancel.


---

### extensionPointAppCommitTax

- extensionPointAppCommitTax: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "sfcc.app.tax.commit"
  - : The extension point name sfcc.app.tax.commit.


---

## Method Details

### calculate(LineItemCtnr)
- calculate(lineItemCtnr: [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointAppCalculateTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#extensionpointappcalculatetax). It calculates tax amounts for
      the basket line items during basket calculation. This hook fires on every basket operation (e.g., adding items,
      changing quantities, updating shipping), not only before order creation.
      
      
      **Note:** If the `dw.order.calculate` hook is overridden, the platform's automatic tax
      hook selection is bypassed. You must manually invoke this hook from within your custom
      `dw.order.calculate` implementation if you want to use Commerce App tax providers.
      
      
      
      
      **Error Handling:** Both returning a `Status.ERROR` and throwing an exception will
      prevent the basket calculation from completing successfully. The platform logs the error and halts the current
      basket operation. Since order creation requires a successful basket calculation, this also prevents orders from
      being created with incorrect tax amounts.
      
      
      
      
      **SCAPI Behavior:** When `ScapiHookExecutionEnabled` is disabled, SCAPI requests bypass
      this hook and use default platform tax calculation.
      
      
      
      
      **Sample Implementation:**
      
      
      
      
      ```
      function calculate(basket) {
          var TaxMgr = require('dw/order/TaxMgr');
          var Status = require('dw/system/Status');
          var HTTPClient = require('dw/net/HTTPClient');
      
          // 1. Extract shipping address and line items
          var shipment = basket.getDefaultShipment();
          var shippingAddress = shipment.getShippingAddress();
      
          // 2. Build request for external tax provider
          var taxRequest = {
              addresses: {
                  shipTo: {
                      line1: shippingAddress.getAddress1(),
                      city: shippingAddress.getCity(),
                      region: shippingAddress.getStateCode(),
                      country: shippingAddress.getCountryCode().getValue(),
                      postalCode: shippingAddress.getPostalCode()
                  }
              },
              lines: []
          };
      
          // Add product line items
          var pliIterator = basket.getProductLineItems().iterator();
          while (pliIterator.hasNext()) {
              var pli = pliIterator.next();
              taxRequest.lines.push({
                  itemCode: pli.getProductID(),
                  quantity: pli.getQuantityValue(),
                  amount: pli.getAdjustedPrice().getValue(),
                  taxCode: pli.getTaxClassID() // Product tax category
              });
          }
      
          // 3. Call external tax service
          var httpClient = new HTTPClient();
          httpClient.open('POST', 'https://api.taxprovider.com/calculate');
          httpClient.setRequestHeader('Authorization', 'Bearer ' + apiKey);
          httpClient.send(JSON.stringify(taxRequest));
      
          if (httpClient.statusCode !== 200) {
              return new Status(Status.ERROR, 'TAX_CALC_FAILED', 'Tax calculation failed: ' + httpClient.errorText);
          }
      
          var taxResponse = JSON.parse(httpClient.text);
      
          // 4. Apply tax amounts to basket line items using TaxMgr
          taxResponse.lines.forEach(function(line, index) {
              var pli = basket.getProductLineItems()[index];
              TaxMgr.setProductLineTax(pli, line.tax);
          });
      
          // Set shipping tax if applicable
          if (taxResponse.shippingTax) {
              TaxMgr.setShippingTax(shipment, taxResponse.shippingTax);
          }
      
          return new Status(Status.OK);
      }
      
      exports.calculate = calculate;
      ```
      
      
      
      **Common APIs used:** `dw.order.TaxMgr` (setProductLineTax, setShippingTax),
      dw.net.HTTPClient, `dw.order.LineItemCtnr` (getProductLineItems, getShipments),
      `dw.order.ProductLineItem` (getProductID, getTaxClassID), `dw.order.OrderAddress`
      (getAddress1, getCity, getStateCode).


    **Parameters:**
    - lineItemCtnr - the line item container (basket) for which tax should be calculated.

    **Returns:**
    - `Status.OK` or `null` for success; `Status.ERROR` to block the basket
              calculation with details about the failure. Throwing an exception will also block the basket calculation.



---

### cancel(Order)
- cancel(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointAppCancelTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#extensionpointappcanceltax) during OrderMgr.failOrder() or
      OrderMgr.cancelOrder(). It notifies the Commerce App tax provider that the order has been cancelled or has
      failed, and that previously committed tax amounts should be voided or cancelled in the tax provider.
      
      
      **Error Handling:**
      
      
      
      - **Non-blocking error:**Return `Status.ERROR`. The platform logs the error as a  warning and continues with the order lifecycle. Use this when the tax provider is temporarily unavailable but the  order cancellation should still proceed.
      - **Blocking error:**Throw an exception. The platform logs the error and rolls back the order  lifecycle operation.
      
      
      
      **SCAPI Behavior:** When `ScapiHookExecutionEnabled` is disabled, SCAPI requests bypass
      this hook.
      
      
      
      
      **Sample Implementation:**
      
      
      
      
      ```
      function cancel(order) {
          var Status = require('dw/system/Status');
          var HTTPClient = require('dw/net/HTTPClient');
      
          // 1. Retrieve the external transaction ID stored during commit
          var taxProviderTransactionId = order.custom.taxProviderTransactionId;
      
          if (!taxProviderTransactionId) {
              // No transaction to cancel - tax was never committed
              return new Status(Status.OK);
          }
      
          // 2. Build void/cancel request for external tax provider
          var cancelRequest = {
              code: order.getOrderNo(),
              type: 'SalesInvoice'
          };
      
          // 3. Call external tax service to void/cancel the transaction
          var httpClient = new HTTPClient();
          httpClient.open('POST', 'https://api.taxprovider.com/transactions/' + taxProviderTransactionId + '/void');
          httpClient.setRequestHeader('Authorization', 'Bearer ' + apiKey);
          httpClient.send(JSON.stringify(cancelRequest));
      
          if (httpClient.statusCode !== 200 && httpClient.statusCode !== 204) {
              // Non-blocking error: log warning but allow order cancellation to proceed
              return new Status(Status.ERROR, 'TAX_CANCEL_FAILED',
                  'Failed to void tax transaction in provider, order cancellation will proceed. Error: ' + httpClient.errorText);
          }
      
          return new Status(Status.OK);
      }
      
      exports.cancel = cancel;
      ```
      
      
      
      **Common APIs used:** dw.net.HTTPClient, `dw.order.Order` (getOrderNo, custom
      attributes), dw.system.Status.


    **Parameters:**
    - order - the order that has been cancelled and for which tax should be voided.

    **Returns:**
    - `Status.OK` or `null` for success; `Status.ERROR` to log a warning
              without blocking the order cancellation. Throwing an exception will roll back the order cancellation
              operation.



---

### commit(Order)
- commit(order: [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)): [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)
  - : The function is called by extension point [extensionPointAppCommitTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md#extensionpointappcommittax) during order creation in the order
      creation transaction. It notifies the Commerce App tax provider that the order has been successfully created and
      that tax amounts should be committed to the tax provider. The order is in `CREATED` status at this
      point (before being placed).
      
      
      **Error Handling:**
      
      
      
      - **Non-blocking error:**Return `Status.ERROR`. The platform logs the error as a  warning and continues with the order lifecycle. Use this when the tax provider is temporarily unavailable but the  order should still be created.
      - **Blocking error:**Throw an exception. The platform logs the error and rolls back the order  lifecycle operation, preventing the order from being created.
      
      
      
      **SCAPI Behavior:** When `ScapiHookExecutionEnabled` is disabled, SCAPI requests bypass
      this hook.
      
      
      
      
      **Sample Implementation:**
      
      
      
      
      ```
      function commit(order) {
          var Transaction = require('dw/system/Transaction');
          var Status = require('dw/system/Status');
          var HTTPClient = require('dw/net/HTTPClient');
      
          // 1. Build commit request for external tax provider
          var commitRequest = {
              code: order.getOrderNo(), // Use order number as unique transaction ID
              type: 'SalesInvoice',
              companyCode: 'DEFAULT',
              date: order.getCreationDate(),
              customerCode: order.getCustomerNo(),
              addresses: {
                  shipTo: {
                      line1: order.getDefaultShipment().getShippingAddress().getAddress1(),
                      city: order.getDefaultShipment().getShippingAddress().getCity(),
                      region: order.getDefaultShipment().getShippingAddress().getStateCode(),
                      country: order.getDefaultShipment().getShippingAddress().getCountryCode().getValue(),
                      postalCode: order.getDefaultShipment().getShippingAddress().getPostalCode()
                  }
              },
              lines: [],
              commit: true // Tell provider to commit the transaction
          };
      
          // Add order line items
          var pliIterator = order.getProductLineItems().iterator();
          while (pliIterator.hasNext()) {
              var pli = pliIterator.next();
              commitRequest.lines.push({
                  itemCode: pli.getProductID(),
                  quantity: pli.getQuantityValue(),
                  amount: pli.getAdjustedPrice().getValue(),
                  tax: pli.getAdjustedTax().getValue()
              });
          }
      
          // 2. Call external tax service to commit transaction
          var httpClient = new HTTPClient();
          httpClient.open('POST', 'https://api.taxprovider.com/transactions');
          httpClient.setRequestHeader('Authorization', 'Bearer ' + apiKey);
          httpClient.send(JSON.stringify(commitRequest));
      
          if (httpClient.statusCode !== 200 && httpClient.statusCode !== 201) {
              // Non-blocking error: log warning but allow order to proceed
              return new Status(Status.ERROR, 'TAX_COMMIT_FAILED',
                  'Failed to commit tax to provider, order will proceed. Error: ' + httpClient.errorText);
          }
      
          var commitResponse = JSON.parse(httpClient.text);
      
          // 3. Store external transaction ID in order custom attribute for later reference (cancel/refund)
          Transaction.wrap(function() {
              order.custom.taxProviderTransactionId = commitResponse.id;
          });
      
          return new Status(Status.OK);
      }
      
      exports.commit = commit;
      ```
      
      
      
      **Common APIs used:** dw.system.Transaction, dw.net.HTTPClient, `dw.order.Order`
      (getOrderNo, getProductLineItems, getDefaultShipment, custom attributes), `dw.order.ProductLineItem`
      (getAdjustedTax).


    **Parameters:**
    - order - the order that has been created and for which tax should be committed.

    **Returns:**
    - `Status.OK` or `null` for success; `Status.ERROR` to log a warning
              without blocking the order. Throwing an exception will roll back the order creation.



---

<!-- prettier-ignore-end -->

<!-- document id=8b03631f3647bcc1bda8101f1bbab57e054a9261799b62188e19501a89e6a5f0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.TaxItem.md -->

<!-- prettier-ignore-start -->
# Class TaxItem

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.TaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md)

An item containing tax information allowing a tax breakdown between a number of [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)s.


## Property Summary

| Property | Description |
| --- | --- |
| [amount](#amount): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)` | Gets the amount. |
| [taxGroup](#taxgroup): [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md) `(read-only)` | Returns the [tax group](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAmount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md#getamount)() | Gets the amount. |
| [getTaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md#gettaxgroup)() | Returns the [tax group](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### amount
- amount: [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md) `(read-only)`
  - : Gets the amount.


---

### taxGroup
- taxGroup: [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md) `(read-only)`
  - : Returns the [tax group](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md).

    **See Also:**
    - [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)


---

## Method Details

### getAmount()
- getAmount(): [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)
  - : Gets the amount.

    **Returns:**
    - the amount


---

### getTaxGroup()
- getTaxGroup(): [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)
  - : Returns the [tax group](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md).

    **Returns:**
    - the tax rate

    **See Also:**
    - [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)


---

<!-- prettier-ignore-end -->

<!-- document id=d3f1c48117262301d22031211b44b48e889220fb2d601f45ff7d22677dfe2e13 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.TaxMgr.md -->

<!-- prettier-ignore-start -->
# Class TaxMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.TaxMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md)

Provides methods to access the tax table.


## Constant Summary

| Constant | Description |
| --- | --- |
| [TAX_POLICY_GROSS](#tax_policy_gross): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | Constant representing the gross taxation policy. |
| [TAX_POLICY_NET](#tax_policy_net): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Constant representing the net taxation policy. |

## Property Summary

| Property | Description |
| --- | --- |
| [customRateTaxClassID](#customratetaxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the tax class that represents items with a custom tax rate. |
| [defaultTaxClassID](#defaulttaxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the default tax class defined for the site. |
| [defaultTaxJurisdictionID](#defaulttaxjurisdictionid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the default tax jurisdiction defined for the site. |
| [taxExemptTaxClassID](#taxexempttaxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the ID of the tax class that represents tax exempt items. |
| [taxationPolicy](#taxationpolicy): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the taxation policy (net/gross) configured for the current site. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [applyExternalTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#applyexternaltaxbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Applies externally set tax rates to the given [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md). |
| static [applyTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#applytaxbasket)([Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)) | Applies tax to the given [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) using the platform's tax hook dispatch logic. |
| static [getCustomRateTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#getcustomratetaxclassid)() | Returns the ID of the tax class that represents items with a custom tax rate. |
| static [getDefaultTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#getdefaulttaxclassid)() | Returns the ID of the default tax class defined for the site. |
| static [getDefaultTaxJurisdictionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#getdefaulttaxjurisdictionid)() | Returns the ID of the default tax jurisdiction defined for the site. |
| static [getTaxExemptTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#gettaxexempttaxclassid)() | Returns the ID of the tax class that represents tax exempt items. |
| static [getTaxJurisdictionID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#gettaxjurisdictionidshippinglocation)([ShippingLocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md)) | Returns the ID of the tax jurisdiction for the specified address. |
| static [getTaxRate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#gettaxratestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the tax rate defined for the specified combination of tax class and tax jurisdiction. |
| static [getTaxationPolicy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#gettaxationpolicy)() | Returns the taxation policy (net/gross) configured for the current site. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### TAX_POLICY_GROSS

- TAX_POLICY_GROSS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : Constant representing the gross taxation policy.


---

### TAX_POLICY_NET

- TAX_POLICY_NET: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Constant representing the net taxation policy.


---

## Property Details

### customRateTaxClassID
- customRateTaxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the tax class that represents items with a custom tax rate. The standard order calculation
      process assumes that such line items are initialized with a tax rate and a being ignored during the tax rate
      lookup sequence of the calculation process.
      
      
      Note that this tax class does not appear in the Business Manager tax module.



---

### defaultTaxClassID
- defaultTaxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the default tax class defined for the site. This class might be used in case a product or
      service does not define a tax class. 
      
      If no default tax class is defined, the method returns null.



---

### defaultTaxJurisdictionID
- defaultTaxJurisdictionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the default tax jurisdiction defined for the site. This jurisdiction might be used in case no
      jurisdiction is defined for a specific address. 
      
      If no default tax jurisdiction is defined, this method returns null.



---

### taxExemptTaxClassID
- taxExemptTaxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the ID of the tax class that represents tax exempt items. The tax manager will return a tax rate of 0.0
      for this tax class.
      
      
      Note that this tax class does not appear in the Business Manager tax module.



---

### taxationPolicy
- taxationPolicy: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the taxation policy (net/gross) configured for the current site.

    **See Also:**
    - [TAX_POLICY_GROSS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#tax_policy_gross)
    - [TAX_POLICY_NET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#tax_policy_net)


---

## Method Details

### applyExternalTax(Basket)
- static applyExternalTax(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): void
  - : Applies externally set tax rates to the given [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md). Only use when
      [LineItemCtnr.isExternallyTaxed()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#isexternallytaxed) returns true. Note: a basket can only be created in EXTERNAL
      tax mode using SCAPI.
      
      
      Typical usage in tax calculation:
      
      
      ```
         var TaxMgr = require('dw/order/TaxMgr');
      
         calculateTaxes: function () {
            Basket basket = BasketMgr.getCurrentBasket();
            if ( basket.isExternallyTaxed() )
            {
               TaxMgr.applyExternalTaxation( basket );
            }
            else
            {
               // calculation with tax tables or customization
            }
         }
      ```


    **Parameters:**
    - basket - apply external taxation to this basket


---

### applyTax(Basket)
- static applyTax(basket: [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)): void
  - : Applies tax to the given [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md) using the platform's tax hook dispatch logic.
      
      
      This method is intended for use in custom `dw.order.calculate` hook implementations (e.g., in SFRA or
      SiteGenesis) that override the default basket calculation. Calling this method instead of directly invoking
      `dw.order.calculateTax` ensures that Commerce App tax providers registered via
      `sfcc.app.tax.calculate` are invoked when available, with automatic fallback to the legacy
      `dw.order.calculateTax` hook or the platform default tax calculation.
      
      
      
      
      **WARNING:** Do NOT call this method from within a `dw.order.calculateTax` hook
      implementation, as this will cause infinite recursion. This method is designed to be called from
      `dw.order.calculate` hooks only.
      
      
      
      
      The dispatch precedence is:
      
      1. `sfcc.app.tax.calculate`— if a Commerce App tax provider is installed and the feature is   enabled.
      2. `dw.order.calculateTax`— if registered by the storefront.
      3. Platform default tax calculation — using the site's tax tables.
      
      
      
      
      
      **Typical usage in a custom `dw.order.calculate` hook:**
      
      
      
      
      ```
      var TaxMgr = require('dw/order/TaxMgr');
      
      exports.calculate = function (basket) {
          // ... product prices, promotions, shipping ...
          TaxMgr.applyTax(basket);
          basket.updateTotals();
      };
      ```


    **Parameters:**
    - basket - the basket for which tax should be calculated.


---

### getCustomRateTaxClassID()
- static getCustomRateTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the tax class that represents items with a custom tax rate. The standard order calculation
      process assumes that such line items are initialized with a tax rate and a being ignored during the tax rate
      lookup sequence of the calculation process.
      
      
      Note that this tax class does not appear in the Business Manager tax module.



---

### getDefaultTaxClassID()
- static getDefaultTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the default tax class defined for the site. This class might be used in case a product or
      service does not define a tax class. 
      
      If no default tax class is defined, the method returns null.


    **Returns:**
    - the ID of the default tax class defined for the site or null.


---

### getDefaultTaxJurisdictionID()
- static getDefaultTaxJurisdictionID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the default tax jurisdiction defined for the site. This jurisdiction might be used in case no
      jurisdiction is defined for a specific address. 
      
      If no default tax jurisdiction is defined, this method returns null.


    **Returns:**
    - the ID of the default tax jurisdiction defined for the site or null.


---

### getTaxExemptTaxClassID()
- static getTaxExemptTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the tax class that represents tax exempt items. The tax manager will return a tax rate of 0.0
      for this tax class.
      
      
      Note that this tax class does not appear in the Business Manager tax module.



---

### getTaxJurisdictionID(ShippingLocation)
- static getTaxJurisdictionID(location: [ShippingLocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the ID of the tax jurisdiction for the specified address. If no tax jurisdiction defined for the site
      matches the specified address, this method returns null.


    **Parameters:**
    - location - The shipping location

    **Returns:**
    - the ID of the tax jurisdiction for the specified address or null.


---

### getTaxRate(String, String)
- static getTaxRate(taxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), taxJurisdictionID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the tax rate defined for the specified combination of tax class and tax jurisdiction. 
      
      Method returns null if no tax rate is defined. 
      
      Method returns 0.0 of 'nontaxable' tax rate is specified (see method 'getNontaxableTaxClassID'.


    **Parameters:**
    - taxClassID - ID of the tax class
    - taxJurisdictionID - ID of tax jusrisdiction

    **Returns:**
    - the tax rate defined for the specified combination of tax class and tax jurisdiction.


---

### getTaxationPolicy()
- static getTaxationPolicy(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the taxation policy (net/gross) configured for the current site.

    **Returns:**
    - Taxation policy configured for current site

    **See Also:**
    - [TAX_POLICY_GROSS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#tax_policy_gross)
    - [TAX_POLICY_NET](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md#tax_policy_net)


---

<!-- prettier-ignore-end -->

<!-- document id=75da92bbfe52561a7770d807a8478eef2cd3234e14e258f5df2eefedaff8271c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.Template.md -->

<!-- prettier-ignore-start -->
# Class Template

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.Template](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md)

Reads an ISML template from the file system and renders it into a
[MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md) object. Optional substitution values can be
passed to the isml template via the [render(Map)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#rendermap)
method. Substitution parameters can be accessed within the template through


```
    <isprint value="${param.parameter}">
```


or for backward compatibility through


```
    <isprint value="${pdict.parameter}">
```


The access through pdict only gives access to the parameter map provided at
rendering time and doesn't offer access to the system PipelineDictionary. The
pdict access to the property map is only considered to ease the transition
from SendMail pipelet API based templates. If the PipelineDictionary or
properties of the PipelineDictionary are needed, they need to be included in
the Property map passed to the render method.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Template](#templatestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new template. |
| [Template](#templatestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new template with the locale being set to the given localeID. |

## Method Summary

| Method | Description |
| --- | --- |
| [render](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#render)() | Renders the template specified at instantiation time, without any  substitution parameters. |
| [render](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#rendermap)([Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)) | Renders the template specified at instantiation time with the given  substitution parameters. |
| [setLocale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#setlocalestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets an optional localeID which is used instead of the current requests  localeID. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### Template(String)
- Template(templateName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new template. Doesn't render the template until
      [render()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#render) or [render(Map)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#rendermap)
      is invoked. The current request localeID will be used for Rendering.


    **Parameters:**
    - templateName - file system path to the ISML template


---

### Template(String, String)
- Template(templateName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new template with the locale being set to the given localeID.
      Rendering doesn't happen until [render()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#render) or
      [render(Map)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#rendermap) is invoked.


    **Parameters:**
    - templateName - file system path to the ISML template
    - localeID - localeID to be used for Rendering


---

## Method Details

### render()
- render(): [MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md)
  - : Renders the template specified at instantiation time, without any
      substitution parameters. Any isprint tags referring to param/pdict will
      be unresolved and will be replaced with empty strings. If there's an
      explicit localeID set through [setLocale(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#setlocalestring),
      it takes precedence over the localeID associated with the current
      request.


    **Returns:**
    - MimeEncodedText with isprint tags referring to param/pdict
              replaced with an empty String



---

### render(Map)
- render(params: [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)): [MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md)
  - : Renders the template specified at instantiation time with the given
      substitution parameters. These parameters are available to ISML templates
      through variables named 'param' and 'pdict'. Note that in this context,
      pdict is not referring to the system PipelineDictionary, as the System
      Pipeline Dictionary is not accessible from this script API. If there's an
      explicit localeID set through [setLocale(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md#setlocalestring),
      it takes precedence over the localeID associated with the current
      request.


    **Parameters:**
    - params - Map of substitution parameters which are specified within the             ISML template. Access is available from within the ISML             template through named variables param or pdict.

    **Returns:**
    - MimeEncodedText containing the rendered template. Variables in
              the template referring to param/pdict are replaced with the value
              from the params map or empty if the value isn't found in the map



---

### setLocale(String)
- setLocale(localeID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Template](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md)
  - : Sets an optional localeID which is used instead of the current requests
      localeID.


    **Parameters:**
    - localeID - to be used for processing this template. Throws an exception             if localeID is blank

    **Returns:**
    - this Template object


---

<!-- prettier-ignore-end -->

<!-- document id=3fbd3d2c7c73948e5163bfb87877ac507997e0809a0103abf7f148eb447f8712 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.TotalFixedPriceDiscount.md -->

<!-- prettier-ignore-start -->
# Class TotalFixedPriceDiscount

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.campaign.Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)
    - [dw.campaign.TotalFixedPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.TotalFixedPriceDiscount.md)

Represents a _total fix price_ discount on a group of products in the
discount plan.  For example:  "buy 3 products of type X for a total price
of $29.99".



## Property Summary

| Property | Description |
| --- | --- |
| [totalFixedPrice](#totalfixedprice): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the total fixed price amount. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getTotalFixedPrice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.TotalFixedPriceDiscount.md#gettotalfixedprice)() | Returns the total fixed price amount. |

### Methods inherited from class Discount

[getItemPromotionTiers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getitempromotiontiers), [getPromotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotion), [getPromotionTier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getpromotiontier), [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#getquantity), [getType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md#gettype)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### totalFixedPrice
- totalFixedPrice: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the total fixed price amount.


---

## Method Details

### getTotalFixedPrice()
- getTotalFixedPrice(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the total fixed price amount.

    **Returns:**
    - Total fixed price amount


---

<!-- prettier-ignore-end -->

<!-- document id=47ce2cd33da0e464f3ed9873a4bde06bd1998078a64d633c0eb6f2bc6630357c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.TrackingInfo.md -->

<!-- prettier-ignore-start -->
# Class TrackingInfo

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)
    - [dw.order.TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)

Provides basic information about a tracking info. An instance is identified by an ID and can be referenced from n ShippingOrderItems
using [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)s. This also allows one [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) to be associated with n TrackingInfo.


**See Also:**
- [ShippingOrder.addTrackingInfo(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#addtrackinginfostring)
- [ShippingOrderItem.addTrackingRef(String, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md#addtrackingrefstring-quantity)


## Property Summary

| Property | Description |
| --- | --- |
| [ID](#id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the mandatory identifier for this tracking information. |
| [carrier](#carrier): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Get the Carrier. |
| [carrierService](#carrierservice): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Get the service(ship method) of the used carrier. |
| [shipDate](#shipdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) | Get the ship date. |
| [shippingOrder](#shippingorder): [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) `(read-only)` | Gets the shipping order. |
| [trackingNumber](#trackingnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Get the tracking number. |
| [trackingRefs](#trackingrefs): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Gets the tracking refs (shipping order items) which are assigned to this tracking info. |
| [warehouseID](#warehouseid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Get the id of the shipping warehouse. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getCarrier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#getcarrier)() | Get the Carrier. |
| [getCarrierService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#getcarrierservice)() | Get the service(ship method) of the used carrier. |
| [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#getid)() | Get the mandatory identifier for this tracking information. |
| [getShipDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#getshipdate)() | Get the ship date. |
| [getShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#getshippingorder)() | Gets the shipping order. |
| [getTrackingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#gettrackingnumber)() | Get the tracking number. |
| [getTrackingRefs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#gettrackingrefs)() | Gets the tracking refs (shipping order items) which are assigned to this tracking info. |
| [getWarehouseID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#getwarehouseid)() | Get the id of the shipping warehouse. |
| [setCarrier](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#setcarrierstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the Carrier. |
| [setCarrierService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#setcarrierservicestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the service(ship method) of the used carrier. |
| [setShipDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#setshipdatedate)([Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)) | Set the ship date. |
| [setTrackingNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#settrackingnumberstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the TrackingNumber. |
| [setWarehouseID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md#setwarehouseidstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Set the id of the shipping warehouse. |

### Methods inherited from class Extensible

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md#getcustom)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ID
- ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the mandatory identifier for this tracking information. The id allows the tracking information to be referenced from
      [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)s. To support short shipping a shipping-order-item can manage a list of
      TrackingRefs, each with an optional quantity value allowing individual items to ship in multiple
      parcels with known item quantity in each.


    **See Also:**
    - [ShippingOrder.addTrackingInfo(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#addtrackinginfostring)


---

### carrier
- carrier: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the Carrier.


---

### carrierService
- carrierService: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the service(ship method) of the used carrier.


---

### shipDate
- shipDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Get the ship date.


---

### shippingOrder
- shippingOrder: [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md) `(read-only)`
  - : Gets the shipping order.


---

### trackingNumber
- trackingNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the tracking number.


---

### trackingRefs
- trackingRefs: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Gets the tracking refs (shipping order items) which are assigned to this tracking info.


---

### warehouseID
- warehouseID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the id of the shipping warehouse.


---

## Method Details

### getCarrier()
- getCarrier(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the Carrier.

    **Returns:**
    - the Carrier


---

### getCarrierService()
- getCarrierService(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the service(ship method) of the used carrier.

    **Returns:**
    - the carrier service (ship method)


---

### getID()
- getID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the mandatory identifier for this tracking information. The id allows the tracking information to be referenced from
      [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)s. To support short shipping a shipping-order-item can manage a list of
      TrackingRefs, each with an optional quantity value allowing individual items to ship in multiple
      parcels with known item quantity in each.


    **Returns:**
    - the id

    **See Also:**
    - [ShippingOrder.addTrackingInfo(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#addtrackinginfostring)


---

### getShipDate()
- getShipDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Get the ship date.

    **Returns:**
    - the ship date


---

### getShippingOrder()
- getShippingOrder(): [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)
  - : Gets the shipping order.

    **Returns:**
    - the shipping order


---

### getTrackingNumber()
- getTrackingNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the tracking number.

    **Returns:**
    - the TrackingNumber


---

### getTrackingRefs()
- getTrackingRefs(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Gets the tracking refs (shipping order items) which are assigned to this tracking info.

    **Returns:**
    - the tracking refs (shipping order items) which are assigned to this tracking info.


---

### getWarehouseID()
- getWarehouseID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the id of the shipping warehouse.

    **Returns:**
    - the id of the shipping warehouse


---

### setCarrier(String)
- setCarrier(carrier: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the Carrier.

    **Parameters:**
    - carrier - the Carrier


---

### setCarrierService(String)
- setCarrierService(carrierService: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the service(ship method) of the used carrier.

    **Parameters:**
    - carrierService - the carrier service, eg. the ship method


---

### setShipDate(Date)
- setShipDate(shipDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)): void
  - : Set the ship date.

    **Parameters:**
    - shipDate - the ship date


---

### setTrackingNumber(String)
- setTrackingNumber(trackingNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the TrackingNumber.

    **Parameters:**
    - trackingNumber - the TrackingNumber


---

### setWarehouseID(String)
- setWarehouseID(warehouseID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Set the id of the shipping warehouse.

    **Parameters:**
    - warehouseID - the id of the shipping warehouse


---

<!-- prettier-ignore-end -->

<!-- document id=982cc5c411c530838d068a7a2c56b6db993359b203cf8d7bb243ebe77113371a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.TrackingRef.md -->

<!-- prettier-ignore-start -->
# Class TrackingRef

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.order.TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)

Provides basic information about the [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md) a
[ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) is contained.



## Property Summary

| Property | Description |
| --- | --- |
| [quantity](#quantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) | Gets the quantity, the shipping order item is assigned to the tracking  info. |
| [shippingOrderItem](#shippingorderitem): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) `(read-only)` | Gets the shipping order item which is assigned to the tracking info. |
| [trackingInfo](#trackinginfo): [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md) `(read-only)` | Gets the tracking info, the shipping order item is assigned to. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md#getquantity)() | Gets the quantity, the shipping order item is assigned to the tracking  info. |
| [getShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md#getshippingorderitem)() | Gets the shipping order item which is assigned to the tracking info. |
| [getTrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md#gettrackinginfo)() | Gets the tracking info, the shipping order item is assigned to. |
| [setQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md#setquantityquantity)([Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)) | Sets the quantity, the shipping order item is assigned to the tracking  info. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### quantity
- quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Gets the quantity, the shipping order item is assigned to the tracking
      info.



---

### shippingOrderItem
- shippingOrderItem: [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) `(read-only)`
  - : Gets the shipping order item which is assigned to the tracking info.


---

### trackingInfo
- trackingInfo: [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md) `(read-only)`
  - : Gets the tracking info, the shipping order item is assigned to.


---

## Method Details

### getQuantity()
- getQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Gets the quantity, the shipping order item is assigned to the tracking
      info.


    **Returns:**
    - the quantity the shipping order item is assigned to the tracking
              info.



---

### getShippingOrderItem()
- getShippingOrderItem(): [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)
  - : Gets the shipping order item which is assigned to the tracking info.

    **Returns:**
    - the shipping order item


---

### getTrackingInfo()
- getTrackingInfo(): [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)
  - : Gets the tracking info, the shipping order item is assigned to.

    **Returns:**
    - the tracking info


---

### setQuantity(Quantity)
- setQuantity(quantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)): void
  - : Sets the quantity, the shipping order item is assigned to the tracking
      info.


    **Parameters:**
    - quantity - the quantity, the shipping order item is assigned to the             tracking info.


---

<!-- prettier-ignore-end -->

<!-- document id=2b4a1e2be824b6a6b6c1f90be68f08a6e3956da6baf301b733d0ec1685c980f0 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.Transaction.md -->

<!-- prettier-ignore-start -->
# Class Transaction

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.system.Transaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md)

Represents the current transaction. A transaction provides a context for performing atomic changes to persistent
business objects. Before a business object can be created, changed, or deleted, a transaction must be started using
the [begin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#begin) method. All changes on the touched business objects will only be made durable when the
transaction is committed with [commit()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#commit). If a transaction is rolled back, all changes so far will be reverted
and the business object will have their previous state again. It is possible to begin a transaction multiple times in
a nested way (like begin-begin-commit-commit). In this case, in order to commit the changes the commit method must be
called symmetrically as often as begin. It is also possible to run multiple transactions within a single request, one
after another (like begin-commit-begin-commit). In case of any exception while working with business objects inside
of a transaction, the transaction cannot be committed anymore, but only be rolled back. Business code may try to take
appropriate actions if it expects business-related problems at commit (for example, constraint violations). When a
transaction is still open at the end of a pipeline call, controller call, or job step, the remaining changes are
committed unless an exception is thrown.


The following best practices exist for using transactions:

- Avoid long running transactions in jobs.
- Use one transaction for changes that belong together and need a joint rollback. In most cases, one transaction  for all changes in a request is better than multiple transactions for each individual object.
- Don’t begin and commit a huge number of small transactions in a loop.
- Avoid changing the same objects in parallel transactions.



Example 1 - explicit control:


```
var txn = require('dw/system/Transaction');
txn.begin();
// work with business objects here
txn.commit();
```



Example 2 - implicit control:


```
var txn = require('dw/system/Transaction');
txn.wrap(function(){
    // work with business objects here
});
```



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [begin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#begin)() | Begins a transaction. |
| static [commit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#commit)() | Commits the current transaction. |
| static [rollback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#rollback)() | Rolls back the current transaction. |
| static [wrap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#wrapfunction)([Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)) | Encloses the provided callback function in a begin-commit transactional context. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### begin()
- static begin(): void
  - : Begins a transaction.


---

### commit()
- static commit(): void
  - : Commits the current transaction. The transaction must have been started with [begin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#begin) before.


---

### rollback()
- static rollback(): void
  - : Rolls back the current transaction. The transaction must have been started with [begin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md#begin) before.


---

### wrap(Function)
- static wrap(callback: [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Encloses the provided callback function in a begin-commit transactional context. If the transaction cannot be
      committed successfully, it is rolled back instead and an exception is thrown.


    **Parameters:**
    - callback - a function that should be executed within a transactional context

    **Returns:**
    - the result of the callback function, if it returns something


---

<!-- prettier-ignore-end -->

<!-- document id=9589ea8eb20940ebcd5e8cdb58763e7b2a10405d753d8f5f634bf535b1556496 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.TypeError.md -->

<!-- prettier-ignore-start -->
# Class TypeError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.TypeError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.TypeError.md)

Represents a type error.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [TypeError](#typeerror)() | Constructs the error. |
| [TypeError](#typeerrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the   specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### TypeError()
- TypeError()
  - : Constructs the error.


---

### TypeError(String)
- TypeError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the 
      specified message.


    **Parameters:**
    - msg - the type error message.


---

<!-- prettier-ignore-end -->

<!-- document id=34e0be4bc17ecce61f096aacd334b345f92068bfd24038f333f2be5aa8df5b71 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Uint16Array.md -->

<!-- prettier-ignore-start -->
# Class Uint16Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Uint16Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint16Array.md)

An optimized array to store 16-bit unsigned integer numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | The number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Uint16Array](#uint16array)() | Creates an empty array. |
| [Uint16Array](#uint16arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Uint16Array](#uint16arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Uint16Array](#uint16arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Uint16Array](#uint16arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint16Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint16Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint16Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : The number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Uint16Array()
- Uint16Array()
  - : Creates an empty array.


---

### Uint16Array(Number)
- Uint16Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Uint16Array(Object)
- Uint16Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Uint16Array(Array)
- Uint16Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Uint16Array(ArrayBuffer, Number, Number)
- Uint16Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Uint16Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint16Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=1b1dcf4721561b12013f3124a43a1b16c936b23b995015f8b895c09e1dc66687 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Uint32Array.md -->

<!-- prettier-ignore-start -->
# Class Uint32Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Uint32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint32Array.md)

An optimized array to store 32-bit unsigned integer numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Uint32Array](#uint32array)() | Creates an empty array. |
| [Uint32Array](#uint32arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Uint32Array](#uint32arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Uint32Array](#uint32arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Uint32Array](#uint32arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint32Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint32Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint32Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Uint32Array()
- Uint32Array()
  - : Creates an empty array.


---

### Uint32Array(Number)
- Uint32Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Uint32Array(Object)
- Uint32Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Uint32Array(Array)
- Uint32Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Uint32Array(ArrayBuffer, Number, Number)
- Uint32Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Uint32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint32Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=1d4eb133e3601ad6b177bf4c0ce657fb8e031e30cabfb2d391d4b0f3669eb3cb url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Uint8Array.md -->

<!-- prettier-ignore-start -->
# Class Uint8Array

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Uint8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md)

An optimized array to store 8-bit unsigned integer numbers. Elements of this array are stored in an
[ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Uint8Array](#uint8array)() | Creates an empty array. |
| [Uint8Array](#uint8arraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Uint8Array](#uint8arrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Uint8Array](#uint8arrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Uint8Array](#uint8arrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Uint8Array()
- Uint8Array()
  - : Creates an empty array.


---

### Uint8Array(Number)
- Uint8Array(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Uint8Array(Object)
- Uint8Array(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Uint8Array(Array)
- Uint8Array(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Uint8Array(ArrayBuffer, Number, Number)
- Uint8Array(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Uint8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=e145e27a5c72e7020fb92a7d33cb646390d79a671879a134c5eb0ccbaa144387 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.Uint8ClampedArray.md -->

<!-- prettier-ignore-start -->
# Class Uint8ClampedArray

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Uint8ClampedArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8ClampedArray.md)

An optimized array to store 8-bit unsigned integer numbers. If a value outside of the range 0-255 is attempted to be
set, either 0 or 255 is set instead. Elements of this array are stored in an [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) object.


**API Version:**
**note:** Available from version 21.2.

## Constant Summary

| Constant | Description |
| --- | --- |
| [BYTES_PER_ELEMENT](#bytes_per_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Number value of the element size. |

## Property Summary

| Property | Description |
| --- | --- |
| [buffer](#buffer): [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) | The array buffer referenced by this typed array. |
| [byteLength](#bytelength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of bytes in the array buffer used by this typed array. |
| [byteOffset](#byteoffset): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The start offset for this typed array within the array buffer. |
| [length](#length): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The number of elements. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Uint8ClampedArray](#uint8clampedarray)() | Creates an empty array. |
| [Uint8ClampedArray](#uint8clampedarraynumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates an array with the given element count. |
| [Uint8ClampedArray](#uint8clampedarrayobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an array as a copy of the passed typed array. |
| [Uint8ClampedArray](#uint8clampedarrayarray)([Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)) | Creates an array as a copy of the passed array. |
| [Uint8ClampedArray](#uint8clampedarrayarraybuffer-number-number)([ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md). |

## Method Summary

| Method | Description |
| --- | --- |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8ClampedArray.md#getnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value at the specified index. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8ClampedArray.md#setobject-number)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Copies all values from the source array into this typed array. |
| [subarray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8ClampedArray.md#subarraynumber-number)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### BYTES_PER_ELEMENT

- BYTES_PER_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Number value of the element size.


---

## Property Details

### buffer
- buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)
  - : The array buffer referenced by this typed array.


---

### byteLength
- byteLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of bytes in the array buffer used by this typed array.


---

### byteOffset
- byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The start offset for this typed array within the array buffer.


---

### length
- length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The number of elements.


---

## Constructor Details

### Uint8ClampedArray()
- Uint8ClampedArray()
  - : Creates an empty array.


---

### Uint8ClampedArray(Number)
- Uint8ClampedArray(length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates an array with the given element count.

    **Parameters:**
    - length - The number of elements.


---

### Uint8ClampedArray(Object)
- Uint8ClampedArray(typedArray: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates an array as a copy of the passed typed array.

    **Parameters:**
    - typedArray - The source typed array.


---

### Uint8ClampedArray(Array)
- Uint8ClampedArray(array: [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md))
  - : Creates an array as a copy of the passed array.

    **Parameters:**
    - array - The source array.


---

### Uint8ClampedArray(ArrayBuffer, Number, Number)
- Uint8ClampedArray(buffer: [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md), byteOffset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), length: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md))
  - : Creates a typed array as a view on the given [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).

    **Parameters:**
    - buffer - The array buffer storage object.
    - byteOffset - Optional. The offset within the array buffer in bytes.
    - length - Optional. The number of elements for the target typed array. The passed array buffer must be large enough to store the number of elements specified.


---

## Method Details

### get(Number)
- get(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the value at the specified index. 
      
      Note: This is not ECMAScript standard. Use array element access syntax for single value access.


    **Parameters:**
    - index - The index to use.

    **Returns:**
    - The value at the specified index.


---

### set(Object, Number)
- set(values: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), offset: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Copies all values from the source array into this typed array.

    **Parameters:**
    - values - The source values. Can be an array or a typed array.
    - offset - Optional. Target offset.


---

### subarray(Number, Number)
- subarray(begin: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), end: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Uint8ClampedArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8ClampedArray.md)
  - : Returns a new array object based on the same [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md) store.

    **Parameters:**
    - begin - Optional. The first included element.
    - end - Optional. The index of the end. This element is not included.

    **Returns:**
    - The new array object.


---

<!-- prettier-ignore-end -->

<!-- document id=b78f1b97a2a2117befb65369f1977fc9a7d0a45b30d43e022450c38992a9591a url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.URIError.md -->

<!-- prettier-ignore-start -->
# Class URIError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.URIError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.URIError.md)

Represents a URI error.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [URIError](#urierror)() | Constructs the error. |
| [URIError](#urierrorstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the error with the   specified message. |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### URIError()
- URIError()
  - : Constructs the error.


---

### URIError(String)
- URIError(msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the error with the 
      specified message.


    **Parameters:**
    - msg - the URI error message.


---

<!-- prettier-ignore-end -->

<!-- document id=d28b580cfa907735732ad93c460c7de719d8df6f80d21b24bd0d3d53aa0ac18e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.URL.md -->

<!-- prettier-ignore-start -->
# Class URL

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)

Represents a URL in Commerce Cloud Digital.


## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#abs)() | Makes the URL absolute and ensures that the protocol of the request is used  or http in a mail context. |
| [append](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#appendstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Append a request parameter to this URL. |
| [appendCSRFTokenBM](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#appendcsrftokenbm)() | <p>Appends, if applicable, a CSRF protection token to this URL. |
| [host](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#hoststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Updates the URL with the specified host name  Note: This method is not applicable for static content or image transformation  URLs. |
| [http](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#http)() | Makes the URL absolute and ensures that the protocol http is used. |
| [https](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#https)() | Makes the URL absolute and ensures that the protocol https is used. |
| [relative](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#relative)() | Makes the URL relative. |
| [remove](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#removestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Remove a request parameter from this URL. |
| [siteHost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#sitehost)() | Updates the URL with the site host name  Note: This method is not applicable for static content or image transformation  URLs. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md#tostring)() | Return String representation of the URL. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### abs()
- abs(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Makes the URL absolute and ensures that the protocol of the request is used
      or http in a mail context.
      Note: This method is not applicable for static content or image transformation
      URLs. In this case a runtime exception is thrown.


    **Returns:**
    - A new URL instance.


---

### append(String, String)
- append(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Append a request parameter to this URL.

    **Parameters:**
    - name - The parameter name.  Must not be null.
    - value - The parameter value.  If null, then treated as empty value.

    **Returns:**
    - A reference to this URL.


---

### appendCSRFTokenBM()
- appendCSRFTokenBM(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : 
      Appends, if applicable, a CSRF protection token to this URL. The CSRF token will only be appended under the following conditions:
      
      
      - the URL is a pipeline URL
      - the URL is for Business Manager
      
      
      
      If a CSRF token already exists in the URL, it will be replaced with a newly generated one.


    **Returns:**
    - a reference to this URL, with a CSRF token appended if applicable.


---

### host(String)
- host(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Updates the URL with the specified host name
      Note: This method is not applicable for static content or image transformation
      URLs. In this case a runtime exception is thrown.


    **Parameters:**
    - host - The host name that is used to update the URL.

    **Returns:**
    - A new URL instance.


---

### http()
- http(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Makes the URL absolute and ensures that the protocol http is used.
      Note: This method is not applicable for static content or image transformation
      URLs. In this case a runtime exception is thrown.


    **Returns:**
    - A new URL instance.


---

### https()
- https(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Makes the URL absolute and ensures that the protocol https is used.
      Note: This method is not applicable for static content or image transformation
      URLs. In this case a runtime exception is thrown.


    **Returns:**
    - A new URL instance.


---

### relative()
- relative(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Makes the URL relative.
      Note: This method is not applicable for static content or image transformation
      URLs. In this case a runtime exception is thrown.


    **Returns:**
    - A new URL instance.


---

### remove(String)
- remove(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Remove a request parameter from this URL. If the parameter is not part
      of the URL, nothing is done.


    **Parameters:**
    - name - The parameter name.  Must not be null.

    **Returns:**
    - A reference to this URL.


---

### siteHost()
- siteHost(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Updates the URL with the site host name
      Note: This method is not applicable for static content or image transformation
      URLs. In this case a runtime exception is thrown.


    **Returns:**
    - A new URL instance.


---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return String representation of the URL.

    **Returns:**
    - the URL as a string.


---

<!-- prettier-ignore-end -->

<!-- document id=358dc04a8a78e96a9fa744ed4f5c19e065aa5da4a34f1f475c037ec007331a0a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.URLAction.md -->

<!-- prettier-ignore-start -->
# Class URLAction

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md)

The class is needed for the URL creation within template processing. It
represents a reference to a pipeline name and start node, usually used in a
HREF or a FORM action. URLAction instances are usually passed to one of the
methods in [URLUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md) in order to generate an appropriately
constructed Commerce Cloud Digital URL.  For example:


`
  var urlAction : URLAction = new URLAction("SimplePipeline-Start", "SampleSite");

  var url : URL = URLUtils.abs(false, urlAction1);

  // url.toString() equals "http://" + request.httpHost + "/on/demandware.store/Sites-SampleSite-Site/default/SimplePipeline-Start"

 `



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [URLAction](#urlactionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an action for the current site and locale. |
| [URLAction](#urlactionstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an action for the specified site and the current locale. |
| [URLAction](#urlactionstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an action for the specified site and locale. |
| [URLAction](#urlactionstring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs an URL action for the specified site, locale and hostname. |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### URLAction(String)
- URLAction(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs an action for the current site and locale.

    **Parameters:**
    - action - the target pipeline/controller, e.g. 'Default-Start'


---

### URLAction(String, String)
- URLAction(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), siteName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs an action for the specified site and the current locale.

    **Parameters:**
    - action - the target pipeline/controller, e.g. 'Default-Start'
    - siteName - the target site, e.g. 'SampleSite'


---

### URLAction(String, String, String)
- URLAction(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), siteName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs an action for the specified site and locale.

    **Parameters:**
    - action - the target pipeline/controller, e.g.: 'Default-Start'
    - siteName - the target site, e.g. 'SampleSite'
    - locale - the target locale, e.g. 'default'


---

### URLAction(String, String, String, String)
- URLAction(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), siteName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), locale: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), hostName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs an URL action for the specified site, locale and hostname. 
      
      The hostname must be defined in the site alias settings. If no hostname is provided, the HTTP/HTTPS
      host defined in the site alias settings will be used. If no HTTP/HTTPS host is defined in the site alias
      settings, the hostname of the current request is used.


    **Parameters:**
    - action - the target pipeline/controller, e.g.: 'Default-Start'
    - siteName - the target site, e.g. 'SampleSite'
    - locale - the target locale, e.g. 'default'
    - hostName - the host name, e.g. ‘www.shop.com'

    **Throws:**
    - Exception - if hostName is not defined in site alias settings


---

<!-- prettier-ignore-end -->

<!-- document id=044fee210aa920f67037f14180fe8e0caa5365e18a84634178986022173109ba url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.URLParameter.md -->

<!-- prettier-ignore-start -->
# Class URLParameter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.URLParameter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)

This class represents a key-value-pair for URL parameters.


## Constructor Summary

| Constructor | Description |
| --- | --- |
| [URLParameter](#urlparameterstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Constructs the parameter using the specified name and value and endocded  in the form "name=value". |
| [URLParameter](#urlparameterstring-string-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Constructs the parameter using the specified name and value. |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### URLParameter(String, String)
- URLParameter(aName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Constructs the parameter using the specified name and value and endocded
      in the form "name=value".


    **Parameters:**
    - aName - the name
    - aValue - the value


---

### URLParameter(String, String, Boolean)
- URLParameter(aName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), aValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encodeName: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md))
  - : Constructs the parameter using the specified name and value. If the "encodeName" is set to true,
      the parameter is encoded in the form "name=value". Otherwise, it only
      contains the "value" (needed for URL patterns).


    **Parameters:**
    - aName - the name
    - aValue - the value
    - encodeName - if true, the name will be part of the string form


---

<!-- prettier-ignore-end -->

<!-- document id=8ebc06878a9c0b695a6181947f4a9496581bc4c62c76fc19eef7f7bb30dcbebf url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.URLRedirect.md -->

<!-- prettier-ignore-start -->
# Class URLRedirect

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)

Represents a URLRedirect in Commerce Cloud Digital.


## Property Summary

| Property | Description |
| --- | --- |
| [location](#location): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the URL which was calculated to be the redirect URL. |
| [status](#status): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the corresponding status code for the redirect location. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getLocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md#getlocation)() | Returns the URL which was calculated to be the redirect URL. |
| [getStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md#getstatus)() | Returns the corresponding status code for the redirect location. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### location
- location: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the URL which was calculated to be the redirect URL.
      The Location parameter can be directly used as value for an redirect location.



---

### status
- status: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the corresponding status code for the redirect location.


---

## Method Details

### getLocation()
- getLocation(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the URL which was calculated to be the redirect URL.
      The Location parameter can be directly used as value for an redirect location.


    **Returns:**
    - redirect location


---

### getStatus()
- getStatus(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the corresponding status code for the redirect location.

    **Returns:**
    - status code


---

<!-- prettier-ignore-end -->

<!-- document id=acb753e97a0ce100f0ba575c6ea89825414c2735ea691351b2d567758b8c97e7 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.URLRedirectMgr.md -->

<!-- prettier-ignore-start -->
# Class URLRedirectMgr

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.URLRedirectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md)

URLRedirect manager class. Methods in this class generate URLRedirects based on the
current configuration for Static, Dynamic and URLRedirect mappings in Commerce
Cloud Digital.

Information used to calculate URLRedirects are determined from the current HTTP
request. The URL which is used to find a redirect can be accessed with [getRedirectOrigin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md#getredirectorigin).



## Property Summary

| Property | Description |
| --- | --- |
| [redirect](#redirect): [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md) `(read-only)` | Returns an URLRedirect object, containing a location and status. |
| [redirectOrigin](#redirectorigin): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the relative origin url (without protocol, port, hostname and site path information)  which will be used in [getRedirect()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md#getredirect) to calculate a redirect location for. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [getRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md#getredirect)() | Returns an URLRedirect object, containing a location and status. |
| static [getRedirectOrigin](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md#getredirectorigin)() | Returns the relative origin url (without protocol, port, hostname and site path information)  which will be used in [getRedirect()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md#getredirect) to calculate a redirect location for. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### redirect
- redirect: [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md) `(read-only)`
  - : Returns an URLRedirect object, containing a location and status. The redirect is calculated
      based on origin url of current request and the configured Static, Dynamic and URLRedirect mappings for
      the requested site.



---

### redirectOrigin
- redirectOrigin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the relative origin url (without protocol, port, hostname and site path information)
      which will be used in [getRedirect()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md#getredirect) to calculate a redirect location for.



---

## Method Details

### getRedirect()
- static getRedirect(): [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)
  - : Returns an URLRedirect object, containing a location and status. The redirect is calculated
      based on origin url of current request and the configured Static, Dynamic and URLRedirect mappings for
      the requested site.


    **Returns:**
    - URLRedirect containing the location and status code,
        null in case of no redirect was found



---

### getRedirectOrigin()
- static getRedirectOrigin(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the relative origin url (without protocol, port, hostname and site path information)
      which will be used in [getRedirect()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md#getredirect) to calculate a redirect location for.


    **Returns:**
    - relative origin url


---

<!-- prettier-ignore-end -->

<!-- document id=0955ad80fd83b9ab231b078807256b882bf4b4f89e5844f30de6cb7cf133539c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.URLUtils.md -->

<!-- prettier-ignore-start -->
# Class URLUtils

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.web.URLUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md)

URL utility class. Methods in this class generate URLs used in Commerce Cloud Digital.


Site related information in the generated URLs is determined from the current HTTP request.


Methods belong to two groups: generating absolute and relative URLs. Absolute URL methods
are further subdivided into those creating URLs with specified protocol and those
using protocol information from the request. Corresponding to the protocol, the host name
from the HTTP/HTTPS host preference is used. If preference is not set, the host name from the
current request is included in resulting absolute URL.


URLs do not include a session ID anymore. The appendSID argument therefore does not have any effect.


When creating a pipeline URL with one of the methods url(), http(), https() or abs() by default
the generated URL is a Commerce Cloud Digital URL ("/on/demandware.store/..."). If search friendly URLs are
enabled (old or new) the methods generate search friendly URLs. Search friendly URLs are only generated for
certain pipeline names. Here a list of these pipeline names:

- Product-Show with a 'pid' parameter \[productID\] - search friendly URL for a product
- Product-ShowInCategory with the 'cgid' parameter \[categoryID\] and 'pid' parameter \[productID\] - search friendly URL for a product shown in a specific category
- Search-Show with a 'cgid' parameter \[categoryID\] - search friendly URL for a category
- Search-Show with a 'pid' parameter \[productID\] - search friendly URL for a product
- Search-ShowContent with a 'fdid' parameter \[folderID\] - search friendly URL for a folder (ONLY works with new storefront URLs)
- Page-Show with a 'cid' parameter \[contentID\] - search friendly URL for a content page


Parameter `transform`:


Some methods allow the specification of image transformation parameters. Image
transformation is only performed if the Dynamic Imaging Service (DIS) is available
for the Commerce Cloud Digital instance. Otherwise a standard static content URL is returned.
The to-be-transformed image needs to be hosted on Digital.


Image transformation parameters are specified as JavaScript object literal. They
are translated into URL parameters. See [Create Image Transformation URLs.](https://help.salesforce.com/s/articleView?id=cc.b2c\_creating\_image\_transformation\_urls.htm)


| Type of transformation | Parameters | Description |
| --- |--- |--- |
| Scale an image |           `scaleWidth`<br/>          `scaleHeight`<br/>          `scaleMode`       |           The `scaleWidth` and `scaleHeight` parameters          are both integers; setting one of these parameters triggers a          scaling operation. If both are provided, the one that scales the          image less is used to calculate the scale factor. The image is then          automatically cropped accord to the second dimension, with a          centered position of the cropped area. If the parameter would scale          the image larger, only this operation is applied, if the image          remains within acceptable pixel dimensions.<p/>           Note: `scaleMode` can only be used in combination with `scaleHeight` and `scaleWidth`.<p/>           The `scaleMode` parameter can be set to `cut`          or `fit`. The default `scaleMode` is          `cut`, the behavior of which is explained above. If you          specify `fit` as the `scaleMode`, the system          scales the image into the given box of dimensions while keeping the          aspect ratio (possibly resulting in a smaller image in one          dimension).       |
| Overlay an image |           `imageX`<br/>          `imageY`<br/>          `imageURI`       |           The `imageX` and `imageY` parameters are both          integers. Valid values for these parameters are 0 or greater.<p/>           Supported formats are `png`, `jpg`, `jp2`, and          `gif`.<p/>           The `imageURI` parameter can be set to the absolute path          of the overlaid image. The value of the `imageURI`          parameter must be given in proper URL encoding, and it cannot exceed          400 characters in length. The path may include query string          parameters, which supports dynamically generating the overlaid image          itself through this service; that is, the overlaid image can itself          be a transformed image.<p/>           If the overlaid image extends over the primary image's boundaries,          the overlaid image is cropped so that it fits directly over the          primary image.       |
| Crop an image |           `cropX`<br/>          `cropY`<br/>          `cropWidth`<br/>          `cropHeight`       |           The `cropX`, `cropY`, `cropWidth`,          `cropHeight` parameters are integers. All four parameters          must be specified to trigger a cropping operation.<p/>           Valid values for the `cropX` and `cropY`          parameters are 0 or greater. If the crop location defined by          `cropX` and `cropY` is outside the image area,          nothing is cropped.<p/>           Valid values for the `cropWidth` and          `cropHeight` parameters are 10 or greater. If the          `cropWidth` and `cropHeight` parameters          specify a size that is greater than the original image, the crop          area is reduced to the actual image area. If `cropWidth`          and `cropHeight` are 0 or less, no transformation is          applied.       |
| Format an image | `format` |           The `format` parameter specifies the target format of the          image. Supported formats are `png`, `jpg`, `jp2`, and          `gif`. If no target format is specified, no format          conversion is performed.<p/>           The source image file is references with attribute          `relPath`. Source image's format is recognized by the          file extension which must be `tif`, `tiff`,          `jpg`, `jpeg`, `png`, or          `gif`.<p/>           In the generated URL the file extension of the target format is used          in the URL path. This is to make sure the image is loaded from an          URL with a matching file extension. The source format is provided as          URL parameter.       |
| Adjust image compression quality | `quality` |           The `quality` parameter specifies a quality setting for `jpg` and `jp2` images,          and specifies the compression level for `png` images.<p/>           For `jpg` and `jp2` images, you can set values from 1–100 for the highest quality.          The default quality is 80. If you're not changing the default quality, you don't need to pass in a value.<p/>           For `png` images, the quality setting has no effect on the appearance of the `png`, since the compression is always lossless.          Instead you can use the quality setting to set the zlib compression level and filter-type for PNG images.          The tens digit sets the zlib compression level(1-9). The ones digit sets the filter type.<p/>           If the `png` setting is not present or set to 0, it uses a default value of 75.          If this setting is set to 100, it actually equals the quality setting 90.       |
| Adjust Metadata stripping | `strip` |           The `strip` parameter specifies if metadata like EXIF and color profiles is          stripped from the image during transformation.<p/>           Valid values for the `strip` parameter are between `true` and `false`.          The default is `true`       |
| Change background color | `bgcolor(color) or bgcolor(color+alpha)` |           The `bgcolor` parameter specifies the background color for images that support transparency          as well as JPEG images when being converted from a format that supports transparency.          Optionally, alpha setting for PNG images are also supported.<p/>           `bgcolor` expects a 6 digit hexadecimal value of RGB with an optional          two hexadecimal characters representing alpha value that determines transparency.<p/>           FF0000 = Red<p/>           FF000077 = Red with 50% transparency<p/>           Alpha values are optional. When the alpha value is omitted, the resulting color is opaque.          Alpha values are only valid when the image output format is PNG.       |


Example:

   The following code

   `var url = URLUtils.imageURL('/somepath/image.png', {scaleWidth: 100, format: 'jpg'});`

   will produce an image transformation URL like

   `http://<image server host name>/.../on/demandware.static/.../somepath/image.jpg?sw=100&sfrm=png`.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CONTEXT_CATALOG](#context_catalog): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ContextCatalog" | ID for a catalog context. |
| [CONTEXT_LIBRARY](#context_library): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ContextLibrary" | ID for a library context. |
| [CONTEXT_SITE](#context_site): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ContextSite" | ID for a site context (= assigned cartridges). |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| ~~static [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absboolean-urlaction-urlparameter)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md))~~ | Return an absolute URL with protocol and host from current request. |
| ~~static [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absboolean-string-string)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Return an absolute URL with protocol and host from current request. |
| static [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absurlaction-urlparameter)([URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)) | Return an absolute URL with protocol and host from the current request. |
| static [abs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Return an absolute URL with protocol and host from current request. |
| static [absImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absimagestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to absStatic( String ) this method returns a static URL for a resource  in the current site. |
| static [absImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absimagestring-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to absStatic( String, String, String ) this method returns a static URL for a resource  in the current site. |
| static [absStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absstaticstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns a static URL for a resource in the current site. |
| static [absStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absstaticstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the absolute URL to the static location of the specified context. |
| ~~static [absWebRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#abswebroot)()~~ | Return an absolute web root URL with protocol and host same as the current request. |
| static [continueURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#continueurl)() | Return a URL, which can be used in combination with an Interaction Continue Node, to  continue the user interface flow. |
| static [home](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#home)() | Generates a hostname-only url if an alias is set, or an url to the Home-Show    pipeline in the default format using the protocol of the incoming request. |
| ~~static [http](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpboolean-urlaction-urlparameter)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md))~~ | Return an absolute URL with HTTP protocol. |
| ~~static [http](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpboolean-string-string)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Return an absolute URL with HTTP protocol. |
| static [http](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpurlaction-urlparameter)([URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)) | Return an absolute URL with HTTP protocol. |
| static [http](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Return an absolute URL with HTTP protocol. |
| static [httpContinue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpcontinue)() | Return a URL, which can be used in combination with an Interaction Continue Node, to  continue the user interface flow. |
| static [httpHome](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httphome)() | Generates a hostname-only url if an alias is set, or an url to the Home-Show    pipeline in the default format using the HTTP protocol. |
| static [httpImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpimagestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpStatic( String ) this method returns a static URL for a resource  in the current site. |
| static [httpImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpimagestring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpStatic( String ) this method returns a static URL for a resource  in the current site. |
| static [httpImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpimagestring-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpStatic( String, String, String ) this method returns a static URL for a resource  in the current site. |
| static [httpImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpimagestring-string-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpStatic( String, String, String ) this method returns a static URL for a resource  in the current site. |
| static [httpStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns a static URL for a resource in the current site. |
| static [httpStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns a static URL for a resource in the current site. |
| static [httpStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the absolute URL to the static location of the specified context. |
| static [httpStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the absolute URL to the static location of the specified context. |
| ~~static [httpWebRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpwebroot)()~~ | Return an absolute web root URL with HTTP protocol and host information from current  request. |
| ~~static [https](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsboolean-urlaction-urlparameter)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md))~~ | Return an absolute URL with HTTPS protocol. |
| ~~static [https](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsboolean-string-string)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Return an absolute URL with HTTPS protocol. |
| static [https](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsurlaction-urlparameter)([URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)) | Return an absolute URL with HTTPS protocol. |
| static [https](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Return an absolute URL with HTTPS protocol. |
| static [httpsContinue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpscontinue)() | Return a URL, which can be used in combination with an Interaction Continue Node, to  continue the user interface flow. |
| static [httpsHome](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpshome)() | Generates a hostname-only url if an alias is set, or an url to the Home-Show    pipeline in the default format using the HTTPS protocol. |
| static [httpsImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsimagestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpsStatic( String ) this method returns a static URL for a resource  in the current site. |
| static [httpsImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsimagestring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpsStatic( String ) this method returns a static URL for a resource  in the current site. |
| static [httpsImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsimagestring-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpsStatic( String, String, String ) this method returns a static URL for a resource  in the current site. |
| static [httpsImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsimagestring-string-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to httpsStatic( String, String, String ) this method returns a static URL for a resource  in the current site. |
| static [httpsStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns a static URL for a resource in the current site. |
| static [httpsStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns a static URL for a resource in the current site. |
| static [httpsStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the absolute URL to the static location of the specified context. |
| static [httpsStatic](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the absolute URL to the static location of the specified context. |
| ~~static [httpsWebRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpswebroot)()~~ | Return an absolute web root URL with HTTPS protocol and host and domain information from the current  request. |
| static [imageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#imageurlstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to staticURL( String ) this method returns a static URL for a resource  in the current site. |
| static [imageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#imageurlstring-string-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Similar to staticURL( String, String, String ) this method returns a static URL for a resource  in the current site. |
| static [sessionRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#sessionredirectstring-url)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | This method is used to create a URL that redirects to a location in  the current site with another host name. |
| static [sessionRedirectHttpOnly](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#sessionredirecthttponlystring-url)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)) | This method is used to create a URL that redirects to a location in  the current site with another host name. |
| static [staticURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#staticurlstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | The method returns a static URL for a resource in the current site. |
| static [staticURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#staticurlstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the relative URL to the static location of the specified context. |
| ~~static [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#urlboolean-urlaction-urlparameter)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md))~~ | Return a relative URL. |
| ~~static [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#urlboolean-string-string)([Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Return a relative URL. |
| static [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#urlurlaction-urlparameter)([URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)) | Return a relative URL. |
| static [url](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#urlstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Return a relative URL. |
| ~~static [webRoot](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#webroot)()~~ | Return a relative web root URL. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CONTEXT_CATALOG

- CONTEXT_CATALOG: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ContextCatalog"
  - : ID for a catalog context. See staticURL() method.


---

### CONTEXT_LIBRARY

- CONTEXT_LIBRARY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ContextLibrary"
  - : ID for a library context. See staticURL() method.


---

### CONTEXT_SITE

- CONTEXT_SITE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "ContextSite"
  - : ID for a site context (= assigned cartridges). See staticURL() method.


---

## Method Details

### abs(Boolean, URLAction, URLParameter...)
- ~~static abs(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute URL with protocol and host from current request.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding abs() method without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID.
    - action - URL action
    - params - URL parameters

    **Returns:**
    - an absolute URL with protocol and host from current request.

    **Deprecated:**
**warning:** Use [abs(URLAction, URLParameter...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absurlaction-urlparameter) instead.

---

### abs(Boolean, String, String...)
- ~~static abs(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute URL with protocol and host from current request.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding method abs() without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID.
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs, e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - an absolute URL with protocol and host from current request.

    **Deprecated:**
**warning:** Use [abs(String, String...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absstring-string) instead.

---

### abs(URLAction, URLParameter...)
- static abs(action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return an absolute URL with protocol and host from the current request.

    **Parameters:**
    - action - URL action
    - params - URL parameters

    **Returns:**
    - an absolute URL with protocol and host from the current request.


---

### abs(String, String...)
- static abs(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return an absolute URL with protocol and host from current request.

    **Parameters:**
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs, for example: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - an absolute URL with protocol and host from current request.


---

### absImage(String, Object)
- static absImage(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to absStatic( String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.


    **Parameters:**
    - relPath - the relative path of the file
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - the URL for the specified image resource


---

### absImage(String, String, String, Object)
- static absImage(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to absStatic( String, String, String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - URL for the specified location


---

### absStatic(String)
- static absStatic(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : The method returns a static URL for a resource in the current site. Site
      resources are actually located in the cartridges associated with the site.
      This resources are typically logos, button images, CSS files and JavaScript
      files. The method will transform the given relative path to include cache
      related information, which enables better cache control.
      
      The created URL is an absolute URL with same protocol as the current incoming
      request.
      
      Note: This method replaces the original mechanisms of using the webroot()
      method to construct a URL. The new method is better integrated into the
      overall cache management.


    **Parameters:**
    - relPath - the relative path of the file

    **Returns:**
    - the URL for the specified location


---

### absStatic(String, String, String)
- static absStatic(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the absolute URL to the static location of the specified context. The context
      can be either a specific catalog (URLUtils.CONTEXT\_CATALOG),
      a content library (URLUtils.CONTEXT\_LIBRARY) or a site (URLUtils.CONTEXT\_SITE).
      Respectively either a URL to images in a catalog, a library or a site are created.
      
      
      The contextID parameter is optional and only used for context CONTEXT\_CATALOG, where
      is specifies the ID of a specific catalog. If defined, the static URL for the specified
      catalog is returned. If not defined, the static URL for the current site catalog
      is returned (or null if no site catalog is defined). 
      
      For context CONTEXT\_SITE and context CONTEXT\_LIBRARY, the contextID parameter is
      ignored and the static URL for the current site / site library is returned.
      
      
      Parameter relPath can be defined to specify the relative path within the context-specific
      path.
      
      
      The method returns an absolute URL with the same protocol as the current request.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library

    **Returns:**
    - URL for the specified location


---

### absWebRoot()
- ~~static absWebRoot(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute web root URL with protocol and host same as the current request.
      
      Note: The use of this method is deprecated. The method absStatic() should
      be used instead. It provides better cache integration.


    **Returns:**
    - an absolute web root URL with protocol, host from current request.

    **Deprecated:**
**warning:** Use [absStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absstaticstring) or [absStatic(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#absstaticstring-string-string) instead.

---

### continueURL()
- static continueURL(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return a URL, which can be used in combination with an Interaction Continue Node, to
      continue the user interface flow.


    **Returns:**
    - an absolute URL with protocol and host from current context request.


---

### home()
- static home(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Generates a hostname-only url if an alias is set, or an url to the Home-Show
        pipeline in the default format using the protocol of the incoming request.


    **Returns:**
    - a hostname-only url if an alias is set, or an url to the Home-Show
        pipeline in the default format using the protocol of the incoming request.
        Uses the default locale of the site making the request.



---

### http(Boolean, URLAction, URLParameter...)
- ~~static http(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute URL with HTTP protocol. If an HTTP host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding http() method without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID.
    - action - URL action
    - params - URL parameters

    **Returns:**
    - an absolute URL with HTTP protocol.

    **Deprecated:**
**warning:** Use [http(URLAction, URLParameter...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpurlaction-urlparameter) instead.

---

### http(Boolean, String, String...)
- ~~static http(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute URL with HTTP protocol. If an HTTP host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding http() method without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID.
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs, e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - an absolute URL with HTTP protocol.

    **Deprecated:**
**warning:** Use [http(String, String...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstring-string) instead.

---

### http(URLAction, URLParameter...)
- static http(action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return an absolute URL with HTTP protocol. If an HTTP host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.


    **Parameters:**
    - action - URL action
    - params - URL parameters

    **Returns:**
    - an absolute URL with HTTP protocol.


---

### http(String, String...)
- static http(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return an absolute URL with HTTP protocol. If an HTTP host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.


    **Parameters:**
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs, e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - an absolute URL with HTTP protocol.


---

### httpContinue()
- static httpContinue(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return a URL, which can be used in combination with an Interaction Continue Node, to
      continue the user interface flow. For security reasons the httpContinue() function returns
      a HTTPS continue URL if the interaction flow has started with a HTTPS request. Otherwise a
      HTTP continue URL is returned.
      If an HTTP/HTTPS host is configured in the preferences the returned URL will include that
      host, otherwise, the host from current request is used.


    **Returns:**
    - an absolute URL with HTTP protocol.


---

### httpHome()
- static httpHome(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Generates a hostname-only url if an alias is set, or an url to the Home-Show
        pipeline in the default format using the HTTP protocol.


    **Returns:**
    - a hostname-only url if an alias is set, or an url to the Home-Show
        pipeline in the default format using the HTTP protocol.



---

### httpImage(String, Object)
- static httpImage(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpStatic( String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.


    **Parameters:**
    - relPath - the relative path of the file
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - the URL for the specified location


---

### httpImage(String, String, Object)
- static httpImage(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpStatic( String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - relPath - the relative path of the file
    - transform - Object with transformation parameters

    **Returns:**
    - the URL for the specified location


---

### httpImage(String, String, String, Object)
- static httpImage(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpStatic( String, String, String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - URL for the specified location


---

### httpImage(String, String, String, String, Object)
- static httpImage(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpStatic( String, String, String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library
    - transform - Object with transformation parameters

    **Returns:**
    - URL for the specified location


---

### httpStatic(String)
- static httpStatic(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : The method returns a static URL for a resource in the current site. Site
      resources are actually located in the cartridges associated with the site.
      This resources are typically logos, button images, CSS files and JavaScript
      files. The method will transform the given relative path to include cache
      related information, which enables better cache control.
      
      
      The created URL is an absolute URL with HTTP protocol.
      
      
      Note: This method replaces the original mechanisms of using the webroot()
      method to construct a URL. The new method is better integrated into the
      overall cache management.


    **Parameters:**
    - relPath - the relative path of the file

    **Returns:**
    - the URL for the specified location


---

### httpStatic(String, String)
- static httpStatic(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : The method returns a static URL for a resource in the current site. Site
      resources are actually located in the cartridges associated with the site.
      This resources are typically logos, button images, CSS files and JavaScript
      files. The method will transform the given relative path to include cache
      related information, which enables better cache control.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.
      
      
      The created URL is an absolute URL with HTTP protocol.
      
      
      Note: This method replaces the original mechanisms of using the webroot()
      method to construct a URL. The new method is better integrated into the
      overall cache management.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - relPath - the relative path of the file

    **Returns:**
    - the URL for the specified location


---

### httpStatic(String, String, String)
- static httpStatic(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the absolute URL to the static location of the specified context. The context
      can be either a specific catalog (URLUtils.CONTEXT\_CATALOG),
      a content library (URLUtils.CONTEXT\_LIBRARY) or a site (URLUtils.CONTEXT\_SITE).
      Respectively either a URL to images in a catalog, a library or a site are created.
      
      
      The contextID parameter is optional and only used for context CONTEXT\_CATALOG, where
      is specifies the ID of a specific catalog. If defined, the static URL for the specified
      catalog is returned. If not defined, the static URL for the current site catalog
      is returned (or null if no site catalog is defined). 
      
      For context CONTEXT\_SITE and context CONTEXT\_LIBRARY, the contextID parameter is
      ignored and the static URL for the current site / site library is returned.
      
      
      Parameter relPath can be defined to specify the relative path within the context-specific
      path.
      
      
      The method returns an absolute URL with HTTP protocol.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library

    **Returns:**
    - URL for the specified location


---

### httpStatic(String, String, String, String)
- static httpStatic(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the absolute URL to the static location of the specified context. The context
      can be either a specific catalog (URLUtils.CONTEXT\_CATALOG),
      a content library (URLUtils.CONTEXT\_LIBRARY) or a site (URLUtils.CONTEXT\_SITE).
      Respectively either a URL to images in a catalog, a library or a site are created.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.
      
      
      The contextID parameter is optional and only used for context CONTEXT\_CATALOG, where
      is specifies the ID of a specific catalog. If defined, the static URL for the specified
      catalog is returned. If not defined, the static URL for the current site catalog
      is returned (or null if no site catalog is defined). 
      
      For context CONTEXT\_SITE and context CONTEXT\_LIBRARY, the contextID parameter is
      ignored and the static URL for the current site / site library is returned.
      
      
      Parameter relPath can be defined to specify the relative path within the context-specific
      path.
      
      
      The method returns an absolute URL with HTTP protocol.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library

    **Returns:**
    - URL for the specified location


---

### httpWebRoot()
- ~~static httpWebRoot(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute web root URL with HTTP protocol and host information from current
      request. If an HTTP host is configured in the preferences the returned URL will include
      that host.
      
      Note: The use of this method is deprecated. The method httpStatic() should
      be used instead. It provides better cache integration.


    **Returns:**
    - an absolute web root URL with HTTP protocol and host information from the current
      request.


    **Deprecated:**
**warning:** Use the [httpStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring) or [httpStatic(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpstaticstring-string-string) methods instead.

---

### https(Boolean, URLAction, URLParameter...)
- ~~static https(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute URL with HTTPS protocol. If an HTTPS host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding https() method without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID.
    - action - URL action
    - params - URL parameters

    **Returns:**
    - an absolute URL with HTTPS protocol.

    **Deprecated:**
**warning:** Use the [https(URLAction, URLParameter...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsurlaction-urlparameter) method instead.

---

### https(Boolean, String, String...)
- ~~static https(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute URL with HTTPS protocol. If an HTTPS host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding https() method without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs, e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - an absolute URL with HTTPS protocol.

    **Deprecated:**
**warning:** Use the [https(String, String...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstring-string) method instead.

---

### https(URLAction, URLParameter...)
- static https(action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return an absolute URL with HTTPS protocol. If an HTTPS host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.


    **Parameters:**
    - action - URL action
    - params - URL parameters

    **Returns:**
    - an absolute URL with HTTPS protocol.


---

### https(String, String...)
- static https(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return an absolute URL with HTTPS protocol. If an HTTPS host is configured in the preferences
      the returned URL will include that host, otherwise, the host from current request is used.


    **Parameters:**
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs, e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - an absolute URL with HTTPS protocol.


---

### httpsContinue()
- static httpsContinue(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return a URL, which can be used in combination with an Interaction Continue Node, to
      continue the user interface flow. An absolute URL with HTTPS protocol is returned.
      If an HTTPS host is configured in the preferences the returned URL will include that
      host, otherwise, the host from current request is used.


    **Returns:**
    - an absolute URL with HTTPS protocol.


---

### httpsHome()
- static httpsHome(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Generates a hostname-only url if an alias is set, or an url to the Home-Show
        pipeline in the default format using the HTTPS protocol.


    **Returns:**
    - a hostname-only url if an alias is set, or an url to the Home-Show
        pipeline in the default format using the HTTPS protocol..



---

### httpsImage(String, Object)
- static httpsImage(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpsStatic( String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.


    **Parameters:**
    - relPath - the relative path of the file
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - the URL for the specified location


---

### httpsImage(String, String, Object)
- static httpsImage(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpsStatic( String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - relPath - the relative path of the file
    - transform - Object with transformation parameters

    **Returns:**
    - the URL for the specified location


---

### httpsImage(String, String, String, Object)
- static httpsImage(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpsStatic( String, String, String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - URL for the specified location


---

### httpsImage(String, String, String, String, Object)
- static httpsImage(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to httpsStatic( String, String, String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library
    - transform - Object with transformation parameters

    **Returns:**
    - URL for the specified location


---

### httpsStatic(String)
- static httpsStatic(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : The method returns a static URL for a resource in the current site. Site
      resources are actually located in the cartridges associated with the site.
      This resources are typically logos, button images, CSS files and JavaScript
      files. The method will transform the given relative path to include cache
      related information, which enables better cache control.
      
      
      The created URL is an absolute URL with HTTPS protocol.
      
      
      Note: This method replaces the original mechanisms of using the webroot()
      method to construct a URL. The new method is better integrated into the
      overall cache management.


    **Parameters:**
    - relPath - the relative path of the file

    **Returns:**
    - the URL for the specified location


---

### httpsStatic(String, String)
- static httpsStatic(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : The method returns a static URL for a resource in the current site. Site
      resources are actually located in the cartridges associated with the site.
      This resources are typically logos, button images, CSS files and JavaScript
      files. The method will transform the given relative path to include cache
      related information, which enables better cache control.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.
      
      
      The created URL is an absolute URL with HTTPS protocol.
      
      
      Note: This method replaces the original mechanisms of using the webroot()
      method to construct a URL. The new method is better integrated into the
      overall cache management.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - relPath - the relative path of the file

    **Returns:**
    - the URL for the specified location


---

### httpsStatic(String, String, String)
- static httpsStatic(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the absolute URL to the static location of the specified context. The context
      can be either a specific catalog (URLUtils.CONTEXT\_CATALOG),
      a content library (URLUtils.CONTEXT\_LIBRARY) or a site (URLUtils.CONTEXT\_SITE).
      Respectively either a URL to images in a catalog, a library or a site are created.
      
      
      The contextID parameter is optional and only used for context CONTEXT\_CATALOG, where
      is specifies the ID of a specific catalog. If defined, the static URL for the specified
      catalog is returned. If not defined, the static URL for the current site catalog
      is returned (or null if no site catalog is defined). 
      
      For context CONTEXT\_SITE and context CONTEXT\_LIBRARY, the contextID parameter is
      ignored and the static URL for the current site / site library is returned.
      
      
      Parameter relPath can be defined to specify the relative path within the context-specific
      path.
      
      
      The method returns an absolute URL with HTTPS protocol.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library

    **Returns:**
    - URL for the specified location


---

### httpsStatic(String, String, String, String)
- static httpsStatic(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the absolute URL to the static location of the specified context. The context
      can be either a specific catalog (URLUtils.CONTEXT\_CATALOG),
      a content library (URLUtils.CONTEXT\_LIBRARY) or a site (URLUtils.CONTEXT\_SITE).
      Respectively either a URL to images in a catalog, a library or a site are created.
      
      
      The host parameter is optional. If provided, then this host name will be used
      in precedence to the host name provided by the current request. The specified host
      name must be defined in the alias settings for the site, otherwise an exception will
      be thrown.
      
      
      The contextID parameter is optional and only used for context CONTEXT\_CATALOG, where
      is specifies the ID of a specific catalog. If defined, the static URL for the specified
      catalog is returned. If not defined, the static URL for the current site catalog
      is returned (or null if no site catalog is defined). 
      
      For context CONTEXT\_SITE and context CONTEXT\_LIBRARY, the contextID parameter is
      ignored and the static URL for the current site / site library is returned.
      
      
      Parameter relPath can be defined to specify the relative path within the context-specific
      path.
      
      
      The method returns an absolute URL with HTTPS protocol.


    **Parameters:**
    - host - Optional host name, used to set the host explicitly.
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library

    **Returns:**
    - URL for the specified location


---

### httpsWebRoot()
- ~~static httpsWebRoot(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return an absolute web root URL with HTTPS protocol and host and domain information from the current
      request. If an HTTP host is configured in the preferences the returned URL will include that host.
      
      Note: The use of this method is deprecated. The method httpsStatic() should
      be used instead. It provides better cache integration.


    **Returns:**
    - an absolute web root URL with HTTPS protocol and host information from the current
      request.


    **Deprecated:**
**warning:** Use the [httpsStatic(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring) or [httpsStatic(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#httpsstaticstring-string-string) method instead.

---

### imageURL(String, Object)
- static imageURL(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to staticURL( String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.
      
      The URL returned is always an absolute URL.


    **Parameters:**
    - relPath - the relative path of the file
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - the URL for the specified location


---

### imageURL(String, String, String, Object)
- static imageURL(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transform: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Similar to staticURL( String, String, String ) this method returns a static URL for a resource
      in the current site. The method assumes, that the URL refers to an image an
      supports an additional parameter with optional image transformation parameters.
      The image transformation parameters must be specified as JavaScript object literal.
      
      The URL returned is always an absolute URL.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id
    - relPath - Relative path within the catalog or library
    - transform - Object with transformation parameters (see class header)

    **Returns:**
    - URL for the specified location


---

### sessionRedirect(String, URL)
- static sessionRedirect(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : This method is used to create a URL that redirects to a location in
      the current site with another host name. When the URL is submitted,
      the system copies all system cookies, such that user, session and basket
      information are shared across different hosts. 
      
      The specified host name must be defined in the alias settings for the site,
      otherwise an exception will be thrown when submitting the redirect URL.
      
      If the specified host is the same as the current host, the method will return
      a "normal" URL because no redirect is required.


    **Parameters:**
    - host - Target host with or without a site-path
    - url - Target URL on current site (relative or absolute),  pass null to redirect to new host only

    **Returns:**
    - an absolute secure URL to the redirect mechanism


---

### sessionRedirectHttpOnly(String, URL)
- static sessionRedirectHttpOnly(host: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), url: [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : This method is used to create a URL that redirects to a location in
      the current site with another host name. When the URL is submitted,
      the system copies all system cookies, such that user, session and basket
      information are shared across different hosts. 
      
      The specified host name must be defined in the alias settings for the site,
      otherwise an exception will be thrown when submitting the redirect URL.
      
      If the specified host is the same as the current host, the method will return
      a "normal" URL because no redirect is required.
      
      
      **Note:** since this method generates a non-secure (HTTP) link, no
      HTTPS Cookies are copied, which might lead to sessions being incorrectly being
      detected as hijacked. It is strongly recommended to use [sessionRedirect(String, URL)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#sessionredirectstring-url)
      where possible.


    **Parameters:**
    - host - Target host with or without a site-path
    - url - Target URL on current site (relative or absolute),  pass null to redirect to new host only

    **Returns:**
    - an absolute URL to the redirect mechanism


---

### staticURL(String)
- static staticURL(relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : The method returns a static URL for a resource in the current site. Site
      resources are actually located in the cartridges associated with the site.
      This resources are typically logos, button images, CSS files and JavaScript
      files. The method will transform the given relative path to include cache
      related information, which enables better cache control.
      
      The created URL is a relative URL.
      
      Note: This method replaces the original mechanisms of using the webroot()
      method to construct a URL. The new method is better integrated into the
      overall cache management.


    **Parameters:**
    - relPath - the relative path of the file

    **Returns:**
    - the URL for the specified location


---

### staticURL(String, String, String)
- static staticURL(context: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contextID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), relPath: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Returns the relative URL to the static location of the specified context. The context
      can be either a specific catalog (URLUtils.CONTEXT\_CATALOG),
      a content library (URLUtils.CONTEXT\_LIBRARY) or a site (URLUtils.CONTEXT\_SITE).
      Respectively either a URL to images in a catalog, a library or a site are created.
      
      
      The contextID parameter is optional and can be used with context either CONTEXT\_CATALOG or CONTEXT\_LIBRARY, where
      it specifies the ID of a specific catalog or a shared library respectively. If defined, the static URL for the specified
      catalog/shared library is returned. If not defined, the static URL for the current site catalog/site library
      is returned (or null if no site catalog/site library is defined). 
      
      For context CONTEXT\_SITE, the contextID parameter is ignored and the static URL for the current site is returned.
      
      
      Parameter relPath can be defined to specify the relative path within the context-specific
      path.
      
      
      The method returns an relative URL with the same protocol as the current request.


    **Parameters:**
    - context - Either CONTEXT\_CATALOG, CONTEXT\_LIBRARY or CONTEXT\_SITE
    - contextID - Optional context id, currently only used to specify a catalog id or a shared library id
    - relPath - Relative path within the catalog or library or site

    **Returns:**
    - URL for the specified location


---

### url(Boolean, URLAction, URLParameter...)
- ~~static url(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return a relative URL.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding url() method without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID.
    - action - URL action
    - params - URL parameters

    **Returns:**
    - a relative URL.

    **Deprecated:**
**warning:** Use [url(URLAction, URLParameter...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#urlurlaction-urlparameter) instead.

---

### url(Boolean, String, String...)
- ~~static url(appendSID: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return a relative URL.
      
      Note: The use of this method is deprecated, because session URL rewriting
            is no longer supported. Use the corresponding url() method without the
            appendSID parameter instead.


    **Parameters:**
    - appendSID - when true the resulting URL will include session ID.
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs, e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - a relative URL.

    **Deprecated:**
**warning:** Use [url(String, String...)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#urlstring-string) instead.

---

### url(URLAction, URLParameter...)
- static url(action: [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md), params: [URLParameter...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return a relative URL.

    **Parameters:**
    - action - URL action
    - params - URL parameters

    **Returns:**
    - a relative URL.


---

### url(String, String...)
- static url(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)
  - : Return a relative URL.

    **Parameters:**
    - action - the pipeline, which should be invoked, e.g.: 'Pipeline-StartNode'
    - namesAndParams - several strings with name=value pairs , e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - a relative URL.


---

### webRoot()
- ~~static webRoot(): [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)~~
  - : Return a relative web root URL. A web root URL is used to access all static
      media context for the site. The actual media file can be referenced by appending
      a relative path.
      
      Note: The use of this method is deprecated. The method staticURL() should
      be used instead. It provides better cache integration.


    **Returns:**
    - a relative web root URL.

    **Deprecated:**
**warning:** Use the [staticURL(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#staticurlstring) or the [staticURL(String, String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md#staticurlstring-string-string) method instead.

---

<!-- prettier-ignore-end -->

<!-- document id=302f4ec8deef08505aee4f1960740967e7edf38436d28d9e16401e821682441b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.UUIDUtils.md -->

<!-- prettier-ignore-start -->
# Class UUIDUtils

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.util.UUIDUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.UUIDUtils.md)

Utility methods around generating unique IDs.


## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [createUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.UUIDUtils.md#createuuid)() | The method generates a unique id. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### createUUID()
- static createUUID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The method generates a unique id.

    **Returns:**
    - the generated unique id


---

<!-- prettier-ignore-end -->

<!-- document id=b6876b9e558a0e64440f2b9cc209e0ed76edffc02673731d645d77f694cda9ef url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.Variant.md -->

<!-- prettier-ignore-start -->
# Class Variant

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
        - [dw.catalog.Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md)

Represents a variant of a product variation. If the variant does not define an own value,
the value is retrieved by fallback from variation groups (sorted by their position) or the
variation master.



## Property Summary

| Property | Description |
| --- | --- |
| [EAN](#ean): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the EAN of the product variant. |
| [UPC](#upc): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the UPC of the product variant. |
| [allProductLinks](#allproductlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all product links of the product variant. |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the brand of the product variant. |
| [classificationCategory](#classificationcategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the classification category of the product variant. |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes of the variant. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the image of the product variant. |
| [longDescription](#longdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the long description of the product variant. |
| [manufacturerName](#manufacturername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the manufacturer name of the product variant. |
| [manufacturerSKU](#manufacturersku): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the manufacturer sku of the product variant. |
| [masterProduct](#masterproduct): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the ProductMaster for this mastered product. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the product variant. |
| [onlineFrom](#onlinefrom): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the onlineFrom date of the product variant. |
| [onlineTo](#onlineto): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the onlineTo date of the product variant. |
| [optionProduct](#optionproduct): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the variant has any options, otherwise 'false'. |
| [pageDescription](#pagedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageDescription of the product variant. |
| [pageKeywords](#pagekeywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageKeywords of the product variant. |
| [pageTitle](#pagetitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageTitle of the product variant. |
| [pageURL](#pageurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageURL of the product variant. |
| [productLinks](#productlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all product links of the product variant for which the target  product is assigned to the current site catalog. |
| [shortDescription](#shortdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the short description of the product variant. |
| [taxClassID](#taxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the tax class id of the product variant. |
| [template](#template): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the rendering template name of the product variant. |
| [thumbnail](#thumbnail): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the thumbnail image of the product variant. |
| [unit](#unit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the sales unit of the product variant as defined by the  master product. |
| [unitQuantity](#unitquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the unitQuantity of the product variant as defined by the  master product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getallproductlinks)() | Returns all product links of the product variant. |
| [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getallproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all product links of the specified type of the product variant. |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getbrand)() | Returns the brand of the product variant. |
| [getClassificationCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getclassificationcategory)() | Returns the classification category of the product variant. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getcustom)() | Returns the custom attributes of the variant. |
| [getEAN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getean)() | Returns the EAN of the product variant. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getimage)() | Returns the image of the product variant. |
| [getLongDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getlongdescription)() | Returns the long description of the product variant. |
| [getManufacturerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getmanufacturername)() | Returns the manufacturer name of the product variant. |
| [getManufacturerSKU](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getmanufacturersku)() | Returns the manufacturer sku of the product variant. |
| [getMasterProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getmasterproduct)() | Returns the ProductMaster for this mastered product. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getname)() | Returns the name of the product variant. |
| [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getonlinefrom)() | Returns the onlineFrom date of the product variant. |
| [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getonlineto)() | Returns the onlineTo date of the product variant. |
| [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getpagedescription)() | Returns the pageDescription of the product variant. |
| [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getpagekeywords)() | Returns the pageKeywords of the product variant. |
| [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getpagetitle)() | Returns the pageTitle of the product variant. |
| [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getpageurl)() | Returns the pageURL of the product variant. |
| [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getproductlinks)() | Returns all product links of the product variant for which the target  product is assigned to the current site catalog. |
| [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all product links of the specified type of the product variant  for which the target product is assigned to the current site catalog. |
| [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getrecommendationsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Retrieve the sorted collection of recommendations of the specified type  for this product variant. |
| [getShortDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getshortdescription)() | Returns the short description of the product variant. |
| [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#gettaxclassid)() | Returns the tax class id of the product variant. |
| [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#gettemplate)() | Returns the rendering template name of the product variant. |
| [getThumbnail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getthumbnail)() | Returns the thumbnail image of the product variant. |
| [getUPC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getupc)() | Returns the UPC of the product variant. |
| [getUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getunit)() | Returns the sales unit of the product variant as defined by the  master product. |
| [getUnitQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#getunitquantity)() | Returns the unitQuantity of the product variant as defined by the  master product. |
| [isOptionProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md#isoptionproduct)() | Returns 'true' if the variant has any options, otherwise 'false'. |

### Methods inherited from class Product

[assignedToCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#assignedtocategorycategory), [getActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getactivedata), [getAllCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallcategories), [getAllCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallcategoryassignments), [getAllIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallincomingproductlinks), [getAllIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallincomingproductlinksnumber), [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallproductlinks), [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallproductlinksnumber), [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallrecommendationscatalog), [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallrecommendationscatalog-number), [getAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel), [getAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel), [getAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodelproductinventorylist), [getAvailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailableflag), [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbrand), [getBundledProductQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundledproductquantityproduct), [getBundledProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundledproducts), [getBundles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundles), [getCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategories), [getCategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategoryassignmentcategory), [getCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategoryassignments), [getClassificationCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getclassificationcategory), [getEAN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getean), [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getid), [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimage), [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring), [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring-number), [getImages](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring), [getIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getincomingproductlinks), [getIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getincomingproductlinksnumber), [getLongDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getlongdescription), [getManufacturerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getmanufacturername), [getManufacturerSKU](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getmanufacturersku), [getMinOrderQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getminorderquantity), [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getname), [getOnlineCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlinecategories), [getOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlineflag), [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlinefrom), [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlineto), [getOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getoptionmodel), [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getorderablerecommendations), [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getorderablerecommendationsnumber), [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagedescription), [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagekeywords), [getPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagemetatagstring), [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagemetatags), [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagetitle), [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpageurl), [getPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodel), [getPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodelproductoptionmodel), [getPrimaryCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getprimarycategory), [getPrimaryCategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getprimarycategoryassignment), [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductlinks), [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductlinksnumber), [getProductSetProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductsetproducts), [getProductSets](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductsets), [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendations), [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendationsnumber), [getSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchplacement), [getSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchrank), [getSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchableflag), [getSearchableIfUnavailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchableifunavailableflag), [getShortDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getshortdescription), [getSiteMapChangeFrequency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemapchangefrequency), [getSiteMapIncluded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemapincluded), [getSiteMapPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemappriority), [getStepQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstepquantity), [getStoreReceiptName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstorereceiptname), [getStoreTaxClass](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstoretaxclass), [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#gettaxclassid), [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#gettemplate), [getThumbnail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getthumbnail), [getUPC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getupc), [getUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getunit), [getUnitQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getunitquantity), [getVariants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariants), [getVariationGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationgroups), [getVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationmodel), [includedInBundle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#includedinbundleproduct), [isAssignedToCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtocategorycategory), [isAssignedToSiteCatalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtositecatalog), [isAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isavailable), [isBundle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isbundle), [isBundled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isbundled), [isCategorized](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#iscategorized), [isFacebookEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isfacebookenabled), [isMaster](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#ismaster), [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isonline), [isOptionProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isoptionproduct), [isPinterestEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#ispinterestenabled), [isProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproduct), [isProductSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductset), [isProductSetProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductsetproduct), [isRetailSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isretailset), [isSearchable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#issearchable), [isSiteProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#issiteproduct), [isVariant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isvariant), [isVariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isvariationgroup), [setAvailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setavailableflagboolean), [setOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setonlineflagboolean---variant-1), [setOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setonlineflagboolean---variant-2), [setSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchplacementnumber---variant-1), [setSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchplacementnumber---variant-2), [setSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchranknumber---variant-1), [setSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchranknumber---variant-2), [setSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchableflagboolean---variant-1), [setSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchableflagboolean---variant-2)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### EAN
- EAN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the EAN of the product variant. 
      
      
      If the variant does not define an own value for 'EAN', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'EAN', the value of
      the master product is returned.



---

### UPC
- UPC: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the UPC of the product variant. 
      
      
      If the variant does not define an own value for 'UPC', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'UPC', the value of
      the master product is returned.



---

### allProductLinks
- allProductLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all product links of the product variant. 
      
      
      If the variant does not define any product links, the product links are retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define any product links, the product links are
      retrieved from the master product.



---

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the brand of the product variant. 
      
      
      If the variant does not define an own value for 'brand', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'brand', the value of
      the master product is returned.



---

### classificationCategory
- classificationCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the classification category of the product variant. 
      
      
      **Please note** that the classification category is always inherited
      from the master and cannot be overridden by the variant.



---

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes of the variant. 
      
      
      Custom attributes are inherited from the master product and can
      be overridden by the variant.



---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the image of the product variant. 
      
      
      If the variant does not define an own value for 'image', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'image', the value of
      the master product is returned.



---

### longDescription
- longDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the long description of the product variant. 
      
      
      If the variant does not define an own value for 'longDescription', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'longDescription', the value of
      the master product is returned.



---

### manufacturerName
- manufacturerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the manufacturer name of the product variant. 
      
      
      If the variant does not define an own value for 'manufacturerName', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'manufacturerName', the value of
      the master product is returned.



---

### manufacturerSKU
- manufacturerSKU: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the manufacturer sku of the product variant. 
      
      
      If the variant does not define an own value for 'manufacturerSKU', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'manufacturerSKU', the value of
      the master product is returned.



---

### masterProduct
- masterProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the ProductMaster for this mastered product.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the product variant. 
      
      
      If the variant does not define an own value for 'name', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'name', the value of
      the master product is returned.



---

### onlineFrom
- onlineFrom: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the onlineFrom date of the product variant. 
      
      
      If the variant does not define an own value for 'onlineFrom', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'onlineFrom', the value of
      the master product is returned.



---

### onlineTo
- onlineTo: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the onlineTo date of the product variant. 
      
      
      If the variant does not define an own value for 'onlineTo', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'onlineTo', the value of
      the master product is returned.



---

### optionProduct
- optionProduct: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the variant has any options, otherwise 'false'.
      Method also returns 'true' if the variant has not any options,
      but the related variation groups (sorted by position) or
      master product has options.



---

### pageDescription
- pageDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageDescription of the product variant. 
      
      
      If the variant does not define an own value for 'pageDescription', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageDescription', the value of
      the master product is returned.



---

### pageKeywords
- pageKeywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageKeywords of the product variant. 
      
      
      If the variant does not define an own value for 'pageKeywords', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageKeywords', the value of
      the master product is returned.



---

### pageTitle
- pageTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageTitle of the product variant. 
      
      
      If the variant does not define an own value for 'pageTitle', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageTitle', the value of
      the master product is returned.



---

### pageURL
- pageURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageURL of the product variant. 
      
      
      If the variant does not define an own value for 'pageURL', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageURL', the value of
      the master product is returned.



---

### productLinks
- productLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all product links of the product variant for which the target
      product is assigned to the current site catalog. 
      
      
      If the variant does not define any product links, the product links are retrieved
      from the assigned variation groups, sorted by their position
      
      If none of the variation groups define any product links, the product links are retrieved
      from the master product.



---

### shortDescription
- shortDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the short description of the product variant. 
      
      
      If the variant does not define an own value for 'shortDescription', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'shortDescription', the value of
      the master product is returned.



---

### taxClassID
- taxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the tax class id of the product variant. 
      
      
      If the variant does not define an own value for 'taxClassID', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'taxClassID', the value of
      the master product is returned.



---

### template
- template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the rendering template name of the product variant. 
      
      
      If the variant does not define an own value for 'template', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'template', the value of
      the master product is returned.



---

### thumbnail
- thumbnail: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the thumbnail image of the product variant. 
      
      
      If the variant does not define an own value for 'thumbnail', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'thumbnail', the value of
      the master product is returned.



---

### unit
- unit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the sales unit of the product variant as defined by the
      master product. 
      
      
      If the variant does not define an own value for 'unit', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'unit', the value of
      the master product is returned.



---

### unitQuantity
- unitQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the unitQuantity of the product variant as defined by the
      master product. 
      
      
      If the variant does not define an own value for 'unitQuantity', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'unitQuantity', the value of
      the master product is returned.



---

## Method Details

### getAllProductLinks()
- getAllProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the product variant. 
      
      
      If the variant does not define any product links, the product links are retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define any product links, the product links are
      retrieved from the master product.


    **Returns:**
    - All product links of the variant, variation group or master


---

### getAllProductLinks(Number)
- getAllProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the specified type of the product variant. 
      
      
      If the variant does not define any product links of the specified type,
      the product links are retrieved for the specified type from the assigned
      variation groups, sorted by their position.
      
      If none of the variation groups define any product links of the specified type,
      the product links are retrieved for the specified type from the master product.


    **Parameters:**
    - type - Type of the product link

    **Returns:**
    - Product links of specified type of the variant, variation group or master


---

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the brand of the product variant. 
      
      
      If the variant does not define an own value for 'brand', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'brand', the value of
      the master product is returned.


    **Returns:**
    - The brand of the variant, variation group or master


---

### getClassificationCategory()
- getClassificationCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the classification category of the product variant. 
      
      
      **Please note** that the classification category is always inherited
      from the master and cannot be overridden by the variant.


    **Returns:**
    - The classification category as defined for the master product of the variant


---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes of the variant. 
      
      
      Custom attributes are inherited from the master product and can
      be overridden by the variant.


    **Returns:**
    - the custom attributes of the variant.


---

### getEAN()
- getEAN(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the EAN of the product variant. 
      
      
      If the variant does not define an own value for 'EAN', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'EAN', the value of
      the master product is returned.


    **Returns:**
    - The EAN of the variant, variation group or master


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the image of the product variant. 
      
      
      If the variant does not define an own value for 'image', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'image', the value of
      the master product is returned.


    **Returns:**
    - The image of the variant, variation group or master


---

### getLongDescription()
- getLongDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the long description of the product variant. 
      
      
      If the variant does not define an own value for 'longDescription', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'longDescription', the value of
      the master product is returned.


    **Returns:**
    - The long description of the variant, variation group or master


---

### getManufacturerName()
- getManufacturerName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the manufacturer name of the product variant. 
      
      
      If the variant does not define an own value for 'manufacturerName', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'manufacturerName', the value of
      the master product is returned.


    **Returns:**
    - The manufacturer name of the variant, variation group or master


---

### getManufacturerSKU()
- getManufacturerSKU(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the manufacturer sku of the product variant. 
      
      
      If the variant does not define an own value for 'manufacturerSKU', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'manufacturerSKU', the value of
      the master product is returned.


    **Returns:**
    - The manufacturer sku of the variant, variation group or master


---

### getMasterProduct()
- getMasterProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the ProductMaster for this mastered product.

    **Returns:**
    - the ProductMaster of this mastered product


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the product variant. 
      
      
      If the variant does not define an own value for 'name', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'name', the value of
      the master product is returned.


    **Returns:**
    - The name of the variant, variation group or master


---

### getOnlineFrom()
- getOnlineFrom(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the onlineFrom date of the product variant. 
      
      
      If the variant does not define an own value for 'onlineFrom', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'onlineFrom', the value of
      the master product is returned.


    **Returns:**
    - The onlineFrom date of the variant, variation group or master


---

### getOnlineTo()
- getOnlineTo(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the onlineTo date of the product variant. 
      
      
      If the variant does not define an own value for 'onlineTo', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'onlineTo', the value of
      the master product is returned.


    **Returns:**
    - The onlineTo date of the variant, variation group or master


---

### getPageDescription()
- getPageDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageDescription of the product variant. 
      
      
      If the variant does not define an own value for 'pageDescription', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageDescription', the value of
      the master product is returned.


    **Returns:**
    - The pageDescription of the variant, variation group or master


---

### getPageKeywords()
- getPageKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageKeywords of the product variant. 
      
      
      If the variant does not define an own value for 'pageKeywords', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageKeywords', the value of
      the master product is returned.


    **Returns:**
    - The pageKeywords of the variant, variation group or master


---

### getPageTitle()
- getPageTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageTitle of the product variant. 
      
      
      If the variant does not define an own value for 'pageTitle', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageTitle', the value of
      the master product is returned.


    **Returns:**
    - The pageTitle of the variant, variation group or master


---

### getPageURL()
- getPageURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageURL of the product variant. 
      
      
      If the variant does not define an own value for 'pageURL', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'pageURL', the value of
      the master product is returned.


    **Returns:**
    - The pageURL of the variant, variation group or master


---

### getProductLinks()
- getProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the product variant for which the target
      product is assigned to the current site catalog. 
      
      
      If the variant does not define any product links, the product links are retrieved
      from the assigned variation groups, sorted by their position
      
      If none of the variation groups define any product links, the product links are retrieved
      from the master product.


    **Returns:**
    - Product links of the variant, variation group or master


---

### getProductLinks(Number)
- getProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the specified type of the product variant
      for which the target product is assigned to the current site catalog. 
      
      
      If the variant does not define any product links of the specified type,
      the product links are retrieved for the specified type from the assigned
      variation groups, sorted by their position
      
      If none of the variation groups define any product links of the specified type,
      the product links are retrieved for the specified type from the master product.


    **Parameters:**
    - type - Type of the product link

    **Returns:**
    - Product links of specified type of the variant, variation group or master


---

### getRecommendations(Number)
- getRecommendations(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Retrieve the sorted collection of recommendations of the specified type
      for this product variant.  The types (cross-sell, up-sell, etc) are
      enumerated in the `dw.catalog.Recommendation` class.  Only
      recommendations which are stored in the current site catalog are returned.
      Furthermore, a recommendation is only returned if the target of the
      recommendation is assigned to the current site catalog.
      
      
      
      If the variant does not define any recommendations, recommendations are
      retrieved from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define any recommendations, the recommendations
      of the master are returned.


    **Parameters:**
    - type - the recommendation type

    **Returns:**
    - the sorted collection, never null but possibly empty.


---

### getShortDescription()
- getShortDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the short description of the product variant. 
      
      
      If the variant does not define an own value for 'shortDescription', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'shortDescription', the value of
      the master product is returned.


    **Returns:**
    - The short description of the variant, variation group or master


---

### getTaxClassID()
- getTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tax class id of the product variant. 
      
      
      If the variant does not define an own value for 'taxClassID', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'taxClassID', the value of
      the master product is returned.


    **Returns:**
    - The tax class id of the variant, variation group or master


---

### getTemplate()
- getTemplate(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the rendering template name of the product variant. 
      
      
      If the variant does not define an own value for 'template', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'template', the value of
      the master product is returned.


    **Returns:**
    - The rendering template name of the variant, variation group or master


---

### getThumbnail()
- getThumbnail(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the thumbnail image of the product variant. 
      
      
      If the variant does not define an own value for 'thumbnail', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'thumbnail', the value of
      the master product is returned.


    **Returns:**
    - The thumbnail image of the variant, variation group or master


---

### getUPC()
- getUPC(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the UPC of the product variant. 
      
      
      If the variant does not define an own value for 'UPC', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'UPC', the value of
      the master product is returned.


    **Returns:**
    - The UPC of the variant, variation group or master


---

### getUnit()
- getUnit(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the sales unit of the product variant as defined by the
      master product. 
      
      
      If the variant does not define an own value for 'unit', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'unit', the value of
      the master product is returned.


    **Returns:**
    - The sales unit of the variant, variation group or master


---

### getUnitQuantity()
- getUnitQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the unitQuantity of the product variant as defined by the
      master product. 
      
      
      If the variant does not define an own value for 'unitQuantity', the value is retrieved
      from the assigned variation groups, sorted by their position.
      
      If none of the variation groups define a value for 'unitQuantity', the value of
      the master product is returned.


    **Returns:**
    - The unitQuantity of the variant, variation group or master


---

### isOptionProduct()
- isOptionProduct(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the variant has any options, otherwise 'false'.
      Method also returns 'true' if the variant has not any options,
      but the related variation groups (sorted by position) or
      master product has options.


    **Returns:**
    - true if the variant has any options, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=5ca251add0b5c546826f8679dd992afb297b9b8a25766ec1923ad927649a5bf1 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.VariationGroup.md -->

<!-- prettier-ignore-start -->
# Class VariationGroup

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.object.PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)
    - [dw.object.ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)
      - [dw.catalog.Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
        - [dw.catalog.VariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md)

Class representing a group of variants within a master product who share a
common value for one or more variation attribute values. Variation groups are
used to simplify merchandising of products.


From a more technical perspective, variation groups are defined by two things:


- A relation to a master product.
- A set of variation attributes which have fixed values.

A variant of the related master product is considered in the group if and
only if it matches on the fixed variation attribute values.


Similar to a Variant, a VariationGroup does a fallback to the master product
for all attributes (name, description, etc) and relations (recommendations,
etc).



## Property Summary

| Property | Description |
| --- | --- |
| [EAN](#ean): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the EAN of the product variation group. |
| [UPC](#upc): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the UPC of the product variation group. |
| [allProductLinks](#allproductlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all product links of the product variation group. |
| [brand](#brand): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the brand of the product variation group. |
| [classificationCategory](#classificationcategory): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)` | Returns the classification category of the product variation group. |
| [custom](#custom): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)` | Returns the custom attributes of the variation group. |
| [image](#image): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the image of the product variation group. |
| [longDescription](#longdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the long description of the product variation group. |
| [manufacturerName](#manufacturername): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the manufacturer name of the product variation group. |
| [manufacturerSKU](#manufacturersku): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the manufacturer sku of the product variation group. |
| [masterProduct](#masterproduct): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)` | Returns the ProductMaster for this mastered product. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the product variation group. |
| [onlineFrom](#onlinefrom): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the onlineFrom date of the product variation group. |
| [onlineTo](#onlineto): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the onlineTo date of the product variation group. |
| [optionProduct](#optionproduct): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Returns 'true' if the variation group has any options, otherwise 'false'. |
| [pageDescription](#pagedescription): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageDescription of the product variation group. |
| [pageKeywords](#pagekeywords): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageKeywords of the product variation group. |
| [pageTitle](#pagetitle): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageTitle of the product variation group. |
| [pageURL](#pageurl): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the pageURL of the product variation group. |
| [productLinks](#productlinks): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns all product links of the product variation group for which the target  product is assigned to the current site catalog. |
| [shortDescription](#shortdescription): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)` | Returns the short description of the product variation group. |
| [taxClassID](#taxclassid): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the tax class id of the product variation group. |
| [template](#template): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the rendering template name of the product variation group. |
| [thumbnail](#thumbnail): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)` | Returns the thumbnail image of the product variation group. |
| [unit](#unit): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the sales unit of the product variation group as defined by the  master product. |
| [unitQuantity](#unitquantity): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)` | Returns the unitQuantity of the product variation group as defined by the  master product. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getallproductlinks)() | Returns all product links of the product variation group. |
| [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getallproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all product links of the specified type of the product variation group. |
| [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getbrand)() | Returns the brand of the product variation group. |
| [getClassificationCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getclassificationcategory)() | Returns the classification category of the product variation group. |
| [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getcustom)() | Returns the custom attributes of the variation group. |
| [getEAN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getean)() | Returns the EAN of the product variation group. |
| [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getimage)() | Returns the image of the product variation group. |
| [getLongDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getlongdescription)() | Returns the long description of the product variation group. |
| [getManufacturerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getmanufacturername)() | Returns the manufacturer name of the product variation group. |
| [getManufacturerSKU](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getmanufacturersku)() | Returns the manufacturer sku of the product variation group. |
| [getMasterProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getmasterproduct)() | Returns the ProductMaster for this mastered product. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getname)() | Returns the name of the product variation group. |
| [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getonlinefrom)() | Returns the onlineFrom date of the product variation group. |
| [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getonlineto)() | Returns the onlineTo date of the product variation group. |
| [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getpagedescription)() | Returns the pageDescription of the product variation group. |
| [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getpagekeywords)() | Returns the pageKeywords of the product variation group. |
| [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getpagetitle)() | Returns the pageTitle of the product variation group. |
| [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getpageurl)() | Returns the pageURL of the product variation group. |
| [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getproductlinks)() | Returns all product links of the product variation group for which the target  product is assigned to the current site catalog. |
| [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getproductlinksnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns all product links of the specified type of the product variation group  for which the target product is assigned to the current site catalog. |
| [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getrecommendationsnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Retrieve the sorted collection of recommendations of the specified type  for this product variation group. |
| [getShortDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getshortdescription)() | Returns the short description of the product variation group. |
| [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#gettaxclassid)() | Returns the tax class id of the product variation group. |
| [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#gettemplate)() | Returns the rendering template name of the product variation group. |
| [getThumbnail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getthumbnail)() | Returns the thumbnail image of the product variation group. |
| [getUPC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getupc)() | Returns the UPC of the product variation group. |
| [getUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getunit)() | Returns the sales unit of the product variation group as defined by the  master product. |
| [getUnitQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#getunitquantity)() | Returns the unitQuantity of the product variation group as defined by the  master product. |
| [isOptionProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md#isoptionproduct)() | Returns 'true' if the variation group has any options, otherwise 'false'. |

### Methods inherited from class Product

[assignedToCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#assignedtocategorycategory), [getActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getactivedata), [getAllCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallcategories), [getAllCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallcategoryassignments), [getAllIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallincomingproductlinks), [getAllIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallincomingproductlinksnumber), [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallproductlinks), [getAllProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallproductlinksnumber), [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallrecommendationscatalog), [getAllRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getallrecommendationscatalog-number), [getAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getattributemodel), [getAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodel), [getAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailabilitymodelproductinventorylist), [getAvailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getavailableflag), [getBrand](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbrand), [getBundledProductQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundledproductquantityproduct), [getBundledProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundledproducts), [getBundles](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getbundles), [getCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategories), [getCategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategoryassignmentcategory), [getCategoryAssignments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getcategoryassignments), [getClassificationCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getclassificationcategory), [getEAN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getean), [getID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getid), [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimage), [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring), [getImage](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagestring-number), [getImages](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getimagesstring), [getIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getincomingproductlinks), [getIncomingProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getincomingproductlinksnumber), [getLongDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getlongdescription), [getManufacturerName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getmanufacturername), [getManufacturerSKU](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getmanufacturersku), [getMinOrderQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getminorderquantity), [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getname), [getOnlineCategories](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlinecategories), [getOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlineflag), [getOnlineFrom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlinefrom), [getOnlineTo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getonlineto), [getOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getoptionmodel), [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getorderablerecommendations), [getOrderableRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getorderablerecommendationsnumber), [getPageDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagedescription), [getPageKeywords](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagekeywords), [getPageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagemetatagstring), [getPageMetaTags](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagemetatags), [getPageTitle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpagetitle), [getPageURL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpageurl), [getPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodel), [getPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getpricemodelproductoptionmodel), [getPrimaryCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getprimarycategory), [getPrimaryCategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getprimarycategoryassignment), [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductlinks), [getProductLinks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductlinksnumber), [getProductSetProducts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductsetproducts), [getProductSets](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getproductsets), [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendations), [getRecommendations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getrecommendationsnumber), [getSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchplacement), [getSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchrank), [getSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchableflag), [getSearchableIfUnavailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsearchableifunavailableflag), [getShortDescription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getshortdescription), [getSiteMapChangeFrequency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemapchangefrequency), [getSiteMapIncluded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemapincluded), [getSiteMapPriority](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getsitemappriority), [getStepQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstepquantity), [getStoreReceiptName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstorereceiptname), [getStoreTaxClass](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getstoretaxclass), [getTaxClassID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#gettaxclassid), [getTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#gettemplate), [getThumbnail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getthumbnail), [getUPC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getupc), [getUnit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getunit), [getUnitQuantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getunitquantity), [getVariants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariants), [getVariationGroups](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationgroups), [getVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#getvariationmodel), [includedInBundle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#includedinbundleproduct), [isAssignedToCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtocategorycategory), [isAssignedToSiteCatalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isassignedtositecatalog), [isAvailable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isavailable), [isBundle](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isbundle), [isBundled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isbundled), [isCategorized](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#iscategorized), [isFacebookEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isfacebookenabled), [isMaster](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#ismaster), [isOnline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isonline), [isOptionProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isoptionproduct), [isPinterestEnabled](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#ispinterestenabled), [isProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproduct), [isProductSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductset), [isProductSetProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isproductsetproduct), [isRetailSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isretailset), [isSearchable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#issearchable), [isSiteProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#issiteproduct), [isVariant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isvariant), [isVariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#isvariationgroup), [setAvailableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setavailableflagboolean), [setOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setonlineflagboolean---variant-1), [setOnlineFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setonlineflagboolean---variant-2), [setSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchplacementnumber---variant-1), [setSearchPlacement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchplacementnumber---variant-2), [setSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchranknumber---variant-1), [setSearchRank](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchranknumber---variant-2), [setSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchableflagboolean---variant-1), [setSearchableFlag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md#setsearchableflagboolean---variant-2)
### Methods inherited from class ExtensibleObject

[describe](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#describe), [getCustom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md#getcustom)
### Methods inherited from class PersistentObject

[getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getcreationdate), [getLastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getlastmodified), [getUUID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md#getuuid)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### EAN
- EAN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the EAN of the product variation group. 
      
      
      If the variation group does not define an own value for 'EAN', the value of
      the master product is returned.



---

### UPC
- UPC: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the UPC of the product variation group. 
      
      
      If the variation group does not define an own value for 'UPC', the value of
      the master product is returned.



---

### allProductLinks
- allProductLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all product links of the product variation group. 
      
      
      If the variation group does not define any product links, but the master product
      does, the product links of the master are returned.



---

### brand
- brand: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the brand of the product variation group. 
      
      
      If the variation group does not define an own value for 'brand', the value of
      the master product is returned.



---

### classificationCategory
- classificationCategory: [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md) `(read-only)`
  - : Returns the classification category of the product variation group. 
      
      
      **Please note** that the classification category is always inherited
      from the master and cannot be overridden by the variation group.



---

### custom
- custom: [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md) `(read-only)`
  - : Returns the custom attributes of the variation group. 
      
      
      Custom attributes are inherited from the master product and can
      be overridden by the variation group.



---

### image
- image: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the image of the product variation group. 
      
      
      If the variation group does not define an own value for 'image', the value of
      the master product is returned.



---

### longDescription
- longDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the long description of the product variation group. 
      
      
      If the variation group does not define an own value for 'longDescription', the value of
      the master product is returned.



---

### manufacturerName
- manufacturerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the manufacturer name of the product variation group. 
      
      
      If the variation group does not define an own value for 'manufacturerName', the value of
      the master product is returned.



---

### manufacturerSKU
- manufacturerSKU: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the manufacturer sku of the product variation group. 
      
      
      If the variation group does not define an own value for 'manufacturerSKU', the value of
      the master product is returned.



---

### masterProduct
- masterProduct: [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) `(read-only)`
  - : Returns the ProductMaster for this mastered product.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the product variation group. 
      
      
      If the variation group does not define an own value for 'name', the value of
      the master product is returned.



---

### onlineFrom
- onlineFrom: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the onlineFrom date of the product variation group. 
      
      
      If the variation group does not define an own value for 'onlineFrom', the value of
      the master product is returned.



---

### onlineTo
- onlineTo: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the onlineTo date of the product variation group. 
      
      
      If the variation group does not define an own value for 'onlineTo', the value of
      the master product is returned.



---

### optionProduct
- optionProduct: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Returns 'true' if the variation group has any options, otherwise 'false'.
      Method also returns 'true' if the variation group has not any options,
      but the related master product has options.



---

### pageDescription
- pageDescription: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageDescription of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageDescription', the value of
      the master product is returned.



---

### pageKeywords
- pageKeywords: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageKeywords of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageKeywords', the value of
      the master product is returned.



---

### pageTitle
- pageTitle: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageTitle of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageTitle', the value of
      the master product is returned.



---

### pageURL
- pageURL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the pageURL of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageURL', the value of
      the master product is returned.



---

### productLinks
- productLinks: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns all product links of the product variation group for which the target
      product is assigned to the current site catalog. 
      
      
      If the variation group does not define any product links, but the master product
      does, the product links of the master are returned.



---

### shortDescription
- shortDescription: [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md) `(read-only)`
  - : Returns the short description of the product variation group. 
      
      
      If the variation group does not define an own value for 'shortDescription', the value of
      the master product is returned.



---

### taxClassID
- taxClassID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the tax class id of the product variation group. 
      
      
      If the variation group does not define an own value for 'taxClassID', the value of
      the master product is returned.



---

### template
- template: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the rendering template name of the product variation group. 
      
      
      If the variation group does not define an own value for 'template', the value of
      the master product is returned.



---

### thumbnail
- thumbnail: [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md) `(read-only)`
  - : Returns the thumbnail image of the product variation group. 
      
      
      If the variation group does not define an own value for 'thumbnailImage', the value of
      the master product is returned.



---

### unit
- unit: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the sales unit of the product variation group as defined by the
      master product. 
      
      
      If the variation group does not define an own value for 'unit', the value of
      the master product is returned.



---

### unitQuantity
- unitQuantity: [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md) `(read-only)`
  - : Returns the unitQuantity of the product variation group as defined by the
      master product. 
      
      
      If the variation group does not define an own value for 'unitQuantity', the value of
      the master product is returned.



---

## Method Details

### getAllProductLinks()
- getAllProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the product variation group. 
      
      
      If the variation group does not define any product links, but the master product
      does, the product links of the master are returned.


    **Returns:**
    - All product links of the variation group or master


---

### getAllProductLinks(Number)
- getAllProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the specified type of the product variation group. 
      
      
      If the variation group does not define any product links, but the master product
      does, the product links of the master are returned.


    **Parameters:**
    - type - Type of the product link

    **Returns:**
    - Product links of specified type of the variation group or master


---

### getBrand()
- getBrand(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the brand of the product variation group. 
      
      
      If the variation group does not define an own value for 'brand', the value of
      the master product is returned.


    **Returns:**
    - The brand of the variation group or master


---

### getClassificationCategory()
- getClassificationCategory(): [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)
  - : Returns the classification category of the product variation group. 
      
      
      **Please note** that the classification category is always inherited
      from the master and cannot be overridden by the variation group.


    **Returns:**
    - The classification category as defined for the master product of the variation group


---

### getCustom()
- getCustom(): [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)
  - : Returns the custom attributes of the variation group. 
      
      
      Custom attributes are inherited from the master product and can
      be overridden by the variation group.


    **Returns:**
    - the custom attributes of the variation group.


---

### getEAN()
- getEAN(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the EAN of the product variation group. 
      
      
      If the variation group does not define an own value for 'EAN', the value of
      the master product is returned.


    **Returns:**
    - The EAN of the variation group or master


---

### getImage()
- getImage(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the image of the product variation group. 
      
      
      If the variation group does not define an own value for 'image', the value of
      the master product is returned.


    **Returns:**
    - The image of the variation group or master


---

### getLongDescription()
- getLongDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the long description of the product variation group. 
      
      
      If the variation group does not define an own value for 'longDescription', the value of
      the master product is returned.


    **Returns:**
    - The long description name of the variation group or master


---

### getManufacturerName()
- getManufacturerName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the manufacturer name of the product variation group. 
      
      
      If the variation group does not define an own value for 'manufacturerName', the value of
      the master product is returned.


    **Returns:**
    - The manufacturer name of the variation group or master


---

### getManufacturerSKU()
- getManufacturerSKU(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the manufacturer sku of the product variation group. 
      
      
      If the variation group does not define an own value for 'manufacturerSKU', the value of
      the master product is returned.


    **Returns:**
    - The manufacturer sku of the variation group or master


---

### getMasterProduct()
- getMasterProduct(): [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)
  - : Returns the ProductMaster for this mastered product.

    **Returns:**
    - the ProductMaster of this mastered product


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the product variation group. 
      
      
      If the variation group does not define an own value for 'name', the value of
      the master product is returned.


    **Returns:**
    - The name of the variation group or master


---

### getOnlineFrom()
- getOnlineFrom(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the onlineFrom date of the product variation group. 
      
      
      If the variation group does not define an own value for 'onlineFrom', the value of
      the master product is returned.


    **Returns:**
    - The onlineFrom date of the variation group or master


---

### getOnlineTo()
- getOnlineTo(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the onlineTo date of the product variation group. 
      
      
      If the variation group does not define an own value for 'onlineTo', the value of
      the master product is returned.


    **Returns:**
    - The onlineTo date of the variation group or master


---

### getPageDescription()
- getPageDescription(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageDescription of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageDescription', the value of
      the master product is returned.


    **Returns:**
    - The pageDescription of the variation group or master


---

### getPageKeywords()
- getPageKeywords(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageKeywords of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageKeywords', the value of
      the master product is returned.


    **Returns:**
    - The pageKeywords of the variation group or master


---

### getPageTitle()
- getPageTitle(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageTitle of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageTitle', the value of
      the master product is returned.


    **Returns:**
    - The pageTitle of the variation group or master


---

### getPageURL()
- getPageURL(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the pageURL of the product variation group. 
      
      
      If the variation group does not define an own value for 'pageURL', the value of
      the master product is returned.


    **Returns:**
    - The pageURL of the variation group or master


---

### getProductLinks()
- getProductLinks(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the product variation group for which the target
      product is assigned to the current site catalog. 
      
      
      If the variation group does not define any product links, but the master product
      does, the product links of the master are returned.


    **Returns:**
    - Product links of the variation group or master


---

### getProductLinks(Number)
- getProductLinks(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns all product links of the specified type of the product variation group
      for which the target product is assigned to the current site catalog. 
      
      
      If the variation group does not define any product links of the specified type,
      but the master product does, the product links of the master are returned.


    **Parameters:**
    - type - Type of the product link

    **Returns:**
    - Product links of specified type of the variation group or master


---

### getRecommendations(Number)
- getRecommendations(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Retrieve the sorted collection of recommendations of the specified type
      for this product variation group.  The types (cross-sell, up-sell, etc) are
      enumerated in the `dw.catalog.Recommendation` class.  Only
      recommendations which are stored in the current site catalog are returned.
      Furthermore, a recommendation is only returned if the target of the
      recommendation is assigned to the current site catalog.
      
      
      If the variation group does not define any recommendations, but the master
      product does, the recommendations of the master are returned.


    **Parameters:**
    - type - the recommendation type

    **Returns:**
    - the sorted collection, never null but possibly empty.


---

### getShortDescription()
- getShortDescription(): [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)
  - : Returns the short description of the product variation group. 
      
      
      If the variation group does not define an own value for 'shortDescription', the value of
      the master product is returned.


    **Returns:**
    - The short description name of the variation group or master


---

### getTaxClassID()
- getTaxClassID(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the tax class id of the product variation group. 
      
      
      If the variation group does not define an own value for 'taxClassID', the value of
      the master product is returned.


    **Returns:**
    - The tax class id of the variation group or master


---

### getTemplate()
- getTemplate(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the rendering template name of the product variation group. 
      
      
      If the variation group does not define an own value for 'template', the value of
      the master product is returned.


    **Returns:**
    - The rendering template name of the variation group or master


---

### getThumbnail()
- getThumbnail(): [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)
  - : Returns the thumbnail image of the product variation group. 
      
      
      If the variation group does not define an own value for 'thumbnailImage', the value of
      the master product is returned.


    **Returns:**
    - The thumbnail image of the variation group or master


---

### getUPC()
- getUPC(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the UPC of the product variation group. 
      
      
      If the variation group does not define an own value for 'UPC', the value of
      the master product is returned.


    **Returns:**
    - The UPC of the variation group or master


---

### getUnit()
- getUnit(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the sales unit of the product variation group as defined by the
      master product. 
      
      
      If the variation group does not define an own value for 'unit', the value of
      the master product is returned.


    **Returns:**
    - The sales unit of the variation group or master


---

### getUnitQuantity()
- getUnitQuantity(): [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)
  - : Returns the unitQuantity of the product variation group as defined by the
      master product. 
      
      
      If the variation group does not define an own value for 'unitQuantity', the value of
      the master product is returned.


    **Returns:**
    - The unitQuantity of the variation group or master


---

### isOptionProduct()
- isOptionProduct(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns 'true' if the variation group has any options, otherwise 'false'.
      Method also returns 'true' if the variation group has not any options,
      but the related master product has options.


    **Returns:**
    - true if the variation group has any options, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=27a3658cbe229ecdad5bea125a94fc6fd306ec868b86334e97b59d48ab11926a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.template.Velocity.md -->

<!-- prettier-ignore-start -->
# Class Velocity

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.template.Velocity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md)

This class renders an Apache Velocity template. For Velocity template syntax, see
[Velocity 1.7](https://velocity.apache.org/engine/releases/velocity-1.7/).


The render() methods identify the template to render from:

- a template file name, which is resolved in the Dynamic WebDAV file location for the current site.  Template file names must end with either '.vm' or '.vs'.
- a dw.io.File object, which can point to any file system location that is accessible from a script
- a string that holds the template content directly

**Note:** Files included from an ISML template (either via `#parse` or `#include`) are always resolved
in the Dynamic location, and it is not possible to provide an absolute path.



On the target side of rendering, by default the render() methods write to the current response writer. When needed,
a `dw.io.Writer` can be supplied as a target.


Parameters for rendering can be passed as a single object holding the parameters as properties.


To create a URL, pass the `URLUtils` class.


To access localized strings, pass the `Resource` class:

```
var urlUtil = require('dw/web/URLUtils');
velocity.render("$url.abs('Foo-Bar','cgid',$res.msg('key')", {'url' : urlUtil, 'res' : dw.web.Resource});
```

The complete set of [VelocityTools](https://velocity.apache.org/tools/releases/2.0/generic.html)
 are provided to the template. You can use the tools to escape dynamic data, format text, and for other common tasks.


Template files are cached for different amounts of time, depending on the instance type.



## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| static [remoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md#remoteincludestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Includes the rendered content of the specified action URL, which usually is a pipeline or controller. |
| static [render](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md#renderstring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Renders an inline template to the response writer. |
| static [render](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md#renderstring-object-writer)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)) | Renders an inline template to the provided writer. |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md#rendertemplatefile-object)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Renders a template file to the response writer. |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md#rendertemplatefile-object-writer)([File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)) | Renders a template file to the provided writer. |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md#rendertemplatestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Renders a template file to the response writer. |
| static [renderTemplate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md#rendertemplatestring-object-writer)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)) | Renders a template file to the provided writer. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Method Details

### remoteInclude(String, String...)
- static remoteInclude(action: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namesAndParams: [String...](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Includes the rendered content of the specified action URL, which usually is a pipeline or controller. Must only be used inside a Velocity
      template, such as `$velocity.remoteInclude('Product-Show','sku','42')`


    **Parameters:**
    - action - the URL (pipeline or controller) to be included
    - namesAndParams - several strings with name=value pairs , e.g.: 'pid', 'value1', 'cgid', value2'.

    **Returns:**
    - the string that needs to be added to the Velocity template to execute the remote include


---

### render(String, Object)
- static render(templateContent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Renders an inline template to the response writer.

    **Parameters:**
    - templateContent - the template content
    - args - the argument object


---

### render(String, Object, Writer)
- static render(templateContent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)): void
  - : Renders an inline template to the provided writer.

    **Parameters:**
    - templateContent - the template content
    - args - the argument object
    - writer - the target writer


---

### renderTemplate(File, Object)
- static renderTemplate(templateFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), args: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Renders a template file to the response writer.

    **Parameters:**
    - templateFile - the file object denoting the template
    - args - the argument object


---

### renderTemplate(File, Object, Writer)
- static renderTemplate(templateFile: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), args: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)): void
  - : Renders a template file to the provided writer.

    **Parameters:**
    - templateFile - the file object denoting the template
    - args - the argument object
    - writer - the target writer


---

### renderTemplate(String, Object)
- static renderTemplate(templateFileName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Renders a template file to the response writer.

    **Parameters:**
    - templateFileName - the file name of the template, relative to the current sites Dynamic file location.  For example, for a file at a location similar to:  
```
https://mydomain.com/on/demandware.servlet/webdav/Sites/Dynamic/SiteGenesis/myfile.vm
```
  render the file in this way:   
```
velocity.renderTemplate("myfile.vm", null);
```

    - args - the argument object


---

### renderTemplate(String, Object, Writer)
- static renderTemplate(templateFileName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), args: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)): void
  - : Renders a template file to the provided writer.

    **Parameters:**
    - templateFileName - the file name of the template, relative to the current sites Dynamic file location.  For example, for a file at a location similar to:  
```
https://mydomain.com/on/demandware.servlet/webdav/Sites/Dynamic/SiteGenesis/mydir/myfile.vm
```
  render the file in this way:   
```
velocity.renderTemplate("mydir/myfile.vm", null, result);
```

    - args - the argument object to pass to the template
    - writer - the target writer


---

<!-- prettier-ignore-end -->

<!-- document id=13709dfe324459872a2d66ea045ab2cce243cdfb93e4b0c9cc1032a90b320f07 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.Wallet.md -->

<!-- prettier-ignore-start -->
# Class Wallet

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.customer.Wallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md)

Represents a set of payment instruments associated with a registered customer.


**Note:** this class allows access to sensitive personal and private
information. Pay attention to appropriate legal and regulatory requirements
when developing.



## Property Summary

| Property | Description |
| --- | --- |
| [defaultPaymentInstrument](#defaultpaymentinstrument): [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md) `(read-only)` | Returns the default payment instrument associated with the related customer. |
| [paymentInstruments](#paymentinstruments): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)` | Returns a collection of all payment instruments associated with the  related customer. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [createPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md#createpaymentinstrumentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new, empty payment instrument object associated with the  related customer for the given payment method. |
| [getDefaultPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md#getdefaultpaymentinstrument)() | Returns the default payment instrument associated with the related customer. |
| [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md#getpaymentinstruments)() | Returns a collection of all payment instruments associated with the  related customer. |
| [getPaymentInstruments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md#getpaymentinstrumentsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a collection of all payment instruments associated with the  related customer filtered by the given payment method id. |
| [removePaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md#removepaymentinstrumentcustomerpaymentinstrument)([CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md)) | Removes a payment instrument associated with the customer. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### defaultPaymentInstrument
- defaultPaymentInstrument: [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md) `(read-only)`
  - : Returns the default payment instrument associated with the related customer. If not available, returns the first
      payment instrument or null if no payment instruments are associated with the customer.



---

### paymentInstruments
- paymentInstruments: [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) `(read-only)`
  - : Returns a collection of all payment instruments associated with the
      related customer.



---

## Method Details

### createPaymentInstrument(String)
- createPaymentInstrument(paymentMethodId: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md)
  - : Creates a new, empty payment instrument object associated with the
      related customer for the given payment method.


    **Parameters:**
    - paymentMethodId - the id of a payment method

    **Returns:**
    - the new payment instrument object.

    **Throws:**
    - NullArgumentException - If passed 'paymentMethodId' is null.


---

### getDefaultPaymentInstrument()
- getDefaultPaymentInstrument(): [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md)
  - : Returns the default payment instrument associated with the related customer. If not available, returns the first
      payment instrument or null if no payment instruments are associated with the customer.


    **Returns:**
    - The default payment instrument object.


---

### getPaymentInstruments()
- getPaymentInstruments(): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all payment instruments associated with the
      related customer.


    **Returns:**
    - Collection of all payment instruments.


---

### getPaymentInstruments(String)
- getPaymentInstruments(paymentMethodID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)
  - : Returns a collection of all payment instruments associated with the
      related customer filtered by the given payment method id. If
      `null` is passed as payment method id all payment instruments
      of the customer will be retrieved. If for the given payment method id no
      payment instrument is associated with the customer an empty collection
      will be returned.


    **Parameters:**
    - paymentMethodID - the paymentMethodID the payment method id to filter for

    **Returns:**
    - Collection of payment instruments for a payment method.


---

### removePaymentInstrument(CustomerPaymentInstrument)
- removePaymentInstrument(instrument: [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md)): void
  - : Removes a payment instrument associated with the customer.

    **Parameters:**
    - instrument - the instrument associated with this customer

    **Throws:**
    - NullArgumentException - If passed 'instrument' is null.
    - IllegalArgumentException - If passed 'instrument' belongs to an other customer


---

<!-- prettier-ignore-end -->

<!-- document id=128b379fbd5717ab4ec7800cf9b6a388f84ee87ec15fce926054c6891a3d9367 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.WeakCipher.md -->

<!-- prettier-ignore-start -->
# Class WeakCipher

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.WeakCipher](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md)

This API provides access to Deprecated algorithms.


See [Cipher](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md) for full documentation. WeakCipher is simply a drop-in replacement that **only** supports
deprecated algorithms and key lengths. This is helpful when you need to deal with weak algorithms for backward
compatibility purposes, but Cipher should always be used for new development and for anything intended to be secure.


**Note:** this class handles sensitive security-related data. Pay special attention to PCI DSS v3 requirements 2,
4, and 12.



## Constant Summary

| Constant | Description |
| --- | --- |
| [CHAR_ENCODING](#char_encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UTF8" | Strings containing keys, plain texts, cipher texts etc. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WeakCipher](#weakcipher)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-keyref-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-1), which allows to use a key in  the keystore for the decryption. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level decryption API. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-keyref-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-2), which allows to use a key in  the keystore for the decryption. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level decryption API. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-keyref-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-3), which allows to use a key in  the keystore for the decryption. |
| [decryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level decryption API. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-keyref-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-1), which allows using a key in the  keystore for the decryption. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Decrypts the message using the given parameters. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-keyref-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-2), which allows using a key in the  keystore for the decryption. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Decrypts the message using the given parameters. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-keyref-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-3), which allows using a key in the  keystore for the decryption. |
| [decrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Decrypts the message using the given parameters. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-certificateref-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-1), which allows  to use a key in the keystore for the encryption. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-1)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level encryption API. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-certificateref-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-2), which allows  to use a key in the keystore for the encryption. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-2)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level encryption API. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-certificateref-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-3), which allows  to use a key in the keystore for the encryption. |
| [encryptBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-3)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Lower-level encryption API. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-certificateref-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-string-string-string-number---variant-1)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-certificateref-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-string-string-string-number---variant-2)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-certificateref-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |
| [encrypt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-string-string-string-number---variant-3)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Encrypt the passed message by using the specified key and applying the  transformations described by the specified parameters. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### CHAR_ENCODING

- CHAR_ENCODING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UTF8"
  - : Strings containing keys, plain texts, cipher texts etc. are internally
      converted into byte arrays using this encoding (currently UTF8).



---

## Constructor Details

### WeakCipher()
- WeakCipher()
  - : 


---

## Method Details

### decryptBytes(Bytes, KeyRef, String, String, Number) - Variant 1
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-1), which allows to use a key in
      the keystore for the decryption. See [Cipher.decryptBytes(Bytes, KeyRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-keyref-string-string-number---variant-1) for full
      documentation.


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - privateKey - A reference to a private key in the key store.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decryptBytes(Bytes, String, String, String, Number) - Variant 1
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level decryption API. Decrypts the passed bytes using the specified
      key and applying the transformations described by the specified
      parameters. See [Cipher.decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-1) for full
      documentation.


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - key - The key to use for decryption.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **See Also:**
    - [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-1)

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decryptBytes(Bytes, KeyRef, String, String, Number) - Variant 2
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-2), which allows to use a key in
      the keystore for the decryption. See [Cipher.decryptBytes(Bytes, KeyRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-keyref-string-string-number---variant-2) for full
      documentation.


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - privateKey - A reference to a private key in the key store.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decryptBytes(Bytes, String, String, String, Number) - Variant 2
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level decryption API. Decrypts the passed bytes using the specified
      key and applying the transformations described by the specified
      parameters. See [Cipher.decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-2) for full
      documentation.


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - key - The key to use for decryption.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **See Also:**
    - [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-2)

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decryptBytes(Bytes, KeyRef, String, String, Number) - Variant 3
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptbytesbytes-string-string-string-number---variant-3), which allows to use a key in
      the keystore for the decryption. See [Cipher.decryptBytes(Bytes, KeyRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-keyref-string-string-number---variant-3) for full
      documentation.


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - privateKey - A reference to a private key in the key store.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### decryptBytes(Bytes, String, String, String, Number) - Variant 3
- decryptBytes(encryptedBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level decryption API. Decrypts the passed bytes using the specified
      key and applying the transformations described by the specified
      parameters. See [Cipher.decryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptbytesbytes-string-string-string-number---variant-3) for full
      documentation.


    **Parameters:**
    - encryptedBytes - The bytes to decrypt.
    - key - The key to use for decryption.
    - transformation - The transformation used to originally encrypt.
    - saltOrIV - the salt or IV to use.
    - iterations - the iterations to use.

    **Returns:**
    - The decrypted bytes.

    **See Also:**
    - [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-3)

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### decrypt(String, KeyRef, String, String, Number) - Variant 1
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-1), which allows using a key in the
      keystore for the decryption. See [Cipher.decrypt(String, KeyRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-keyref-string-string-number---variant-1) for full
      documentation.


    **Parameters:**
    - base64Msg - the base64 encoded data to decrypt
    - privateKey - A reference to a private key in the key store.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decrypt(String, String, String, String, Number) - Variant 1
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decrypts the message using the given parameters. See
      [Cipher.decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-1) for full documentation.


    **Parameters:**
    - base64Msg - the base64 encoded data to decrypt
    - key - The decryption key
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### decrypt(String, KeyRef, String, String, Number) - Variant 2
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-2), which allows using a key in the
      keystore for the decryption. See [Cipher.decrypt(String, KeyRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-keyref-string-string-number---variant-2) for full
      documentation.


    **Parameters:**
    - base64Msg - the base64 encoded data to decrypt
    - privateKey - A reference to a private key in the key store.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decrypt(String, String, String, String, Number) - Variant 2
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decrypts the message using the given parameters. See
      [Cipher.decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-2) for full documentation.


    **Parameters:**
    - base64Msg - the base64 encoded data to decrypt
    - key - The decryption key
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### decrypt(String, KeyRef, String, String, Number) - Variant 3
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Alternative method to [decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#decryptstring-string-string-string-number---variant-3), which allows using a key in the
      keystore for the decryption. See [Cipher.decrypt(String, KeyRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-keyref-string-string-number---variant-3) for full
      documentation.


    **Parameters:**
    - base64Msg - the base64 encoded data to decrypt
    - privateKey - A reference to a private key in the key store.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### decrypt(String, String, String, String, Number) - Variant 3
- decrypt(base64Msg: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Decrypts the message using the given parameters. See
      [Cipher.decrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#decryptstring-string-string-string-number---variant-3) for full documentation.


    **Parameters:**
    - base64Msg - the base64 encoded data to decrypt
    - key - The decryption key
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - the original plaintext message.

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encryptBytes(Bytes, CertificateRef, String, String, Number) - Variant 1
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-1), which allows
      to use a key in the keystore for the encryption. See [Cipher.encryptBytes(Bytes, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-certificateref-string-string-number---variant-1) for full documentation.


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - publicKey - A reference to a public key
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-certificateref-string-string-number---variant-1)

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encryptBytes(Bytes, String, String, String, Number) - Variant 1
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level encryption API. Encrypts the passed bytes by using the specified key and applying the transformations
      described by the specified parameters. See [Cipher.encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-1)
      for full documentation.


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - key - The key to use for encryption.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-string-string-string-number---variant-1)

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encryptBytes(Bytes, CertificateRef, String, String, Number) - Variant 2
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-2), which allows
      to use a key in the keystore for the encryption. See [Cipher.encryptBytes(Bytes, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-certificateref-string-string-number---variant-2) for full documentation.


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - publicKey - A reference to a public key.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-certificateref-string-string-number---variant-2)

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encryptBytes(Bytes, String, String, String, Number) - Variant 2
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level encryption API. Encrypts the passed bytes by using the specified key and applying the transformations
      described by the specified parameters. See [Cipher.encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-2)
      for full documentation.


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - key - The key to use for encryption.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-string-string-string-number---variant-2)

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encryptBytes(Bytes, CertificateRef, String, String, Number) - Variant 3
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Alternative method to [encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptbytesbytes-string-string-string-number---variant-3), which allows
      to use a key in the keystore for the encryption. See [Cipher.encryptBytes(Bytes, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-certificateref-string-string-number---variant-3) for full documentation.


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - publicKey - A reference to a public key.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-certificateref-string-string-number---variant-3)

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encryptBytes(Bytes, String, String, String, Number) - Variant 3
- encryptBytes(messageBytes: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Lower-level encryption API. Encrypts the passed bytes by using the specified key and applying the transformations
      described by the specified parameters. See [Cipher.encryptBytes(Bytes, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptbytesbytes-string-string-string-number---variant-3)
      for full documentation.


    **Parameters:**
    - messageBytes - The bytes to encrypt.
    - key - The key to use for encryption.
    - transformation - Transformation in _"algorithm/mode/padding"_ format.
    - saltOrIV - Initialization value appropriate for the algorithm.
    - iterations - The number of passes to make when turning a passphrase into a key.

    **Returns:**
    - the encrypted bytes.

    **See Also:**
    - [encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md#encryptstring-string-string-string-number---variant-3)

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encrypt(String, CertificateRef, String, String, Number) - Variant 1
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      See [Cipher.encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-1) for full documentation.


    **Parameters:**
    - message - Message to encrypt (this will be converted to UTF-8 first)
    - publicKey - A reference to a public key
    - transformation - Transformation in _"algorithm/mode/padding"_ format
    - saltOrIV - Initialization value appropriate for the algorithm
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - Base64-encoded encrypted data

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encrypt(String, String, String, String, Number) - Variant 1
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      See [Cipher.encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-1) for full documentation.


    **Parameters:**
    - message - Message to encrypt (this will be converted to UTF-8 first)
    - key - Key
    - transformation - Transformation in _"algorithm/mode/padding"_ format
    - saltOrIV - Initialization value appropriate for the algorithm
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - Base64-encoded encrypted data

    **API Version:**
**note:** No longer available as of version 15.5.
Under some conditions this method allowed a non-Base64 encrypted value for the salt parameter.

---

### encrypt(String, CertificateRef, String, String, Number) - Variant 2
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      See [Cipher.encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-2) for full documentation.


    **Parameters:**
    - message - Message to encrypt (this will be converted to UTF-8 first)
    - publicKey - A reference to a public key
    - transformation - Transformation in _"algorithm/mode/padding"_ format
    - saltOrIV - Initialization value appropriate for the algorithm
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - Base64-encoded encrypted data

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encrypt(String, String, String, String, Number) - Variant 2
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      See [Cipher.encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-2) for full documentation.


    **Parameters:**
    - message - Message to encrypt (this will be converted to UTF-8 first)
    - key - Key
    - transformation - Transformation in _"algorithm/mode/padding"_ format
    - saltOrIV - Initialization value appropriate for the algorithm
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - Base64-encoded encrypted data

    **API Version:**
**note:** Available from version 15.5.
No longer available as of version 16.2.
Requires Base64-encryption for the salt parameter.

---

### encrypt(String, CertificateRef, String, String, Number) - Variant 3
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      See [Cipher.encrypt(String, CertificateRef, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-certificateref-string-string-number---variant-3) for full documentation.


    **Parameters:**
    - message - Message to encrypt (this will be converted to UTF-8 first)
    - publicKey - A reference to a public key
    - transformation - Transformation in _"algorithm/mode/padding"_ format
    - saltOrIV - Initialization value appropriate for the algorithm
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - Base64-encoded encrypted data

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

### encrypt(String, String, String, String, Number) - Variant 3
- encrypt(message: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), transformation: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), saltOrIV: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), iterations: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Encrypt the passed message by using the specified key and applying the
      transformations described by the specified parameters.
      
      See [Cipher.encrypt(String, String, String, String, Number)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md#encryptstring-string-string-string-number---variant-3) for full documentation.


    **Parameters:**
    - message - Message to encrypt (this will be converted to UTF-8 first)
    - key - Key
    - transformation - Transformation in _"algorithm/mode/padding"_ format
    - saltOrIV - Initialization value appropriate for the algorithm
    - iterations - The number of passes to make when turning a passphrase into a key, if applicable

    **Returns:**
    - Base64-encoded encrypted data

    **API Version:**
**note:** Available from version 16.2.
Does not use a default initialization vector.

---

<!-- prettier-ignore-end -->

<!-- document id=5411bfde1853a8eede11eb1a5152cfe3b586ade09be71c332f0631d8c9cd03b3 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.WeakMac.md -->

<!-- prettier-ignore-start -->
# Class WeakMac

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.WeakMac](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMac.md)

This API provides access to Deprecated algorithms.


See [Mac](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Mac.md) for full documentation. WeakMac is simply a drop-in replacement that **only** supports
deprecated algorithms. This is helpful when you need to deal with weak algorithms for backward
compatibility purposes, but Mac should always be used for new development and for anything intended to be secure.


This class provides the functionality of a "Message Authentication Code" (MAC) algorithm.
A MAC provides a way to check the integrity of information transmitted over or
stored in an unreliable medium, based on a secret key.
Typically, message authentication codes are used between two parties
that share a secret key in order to validate information transmitted between these parties.
A MAC mechanism that is based on cryptographic hash functions is referred to as HMAC.
HMAC can be used with any cryptographic hash function, e.g., SHA256,
in combination with a secret shared key. HMAC is specified in RFC 2104.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Constant Summary

| Constant | Description |
| --- | --- |
| [HMAC_MD5](#hmac_md5): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacMD5" | Constant representing the HMAC-MD5 keyed-hashing algorithm as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997). |
| [HMAC_SHA_1](#hmac_sha_1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA1" | Constant representing the HmacSHA1 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)  with SHA-1 as the message digest algorithm. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WeakMac](#weakmacstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a Mac encryption instance with the specified algorithm name. |

## Method Summary

| Method | Description |
| --- | --- |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMac.md#digestbytes-bytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Computes the hash value for the passed bytes input using the passed secret key. |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMac.md#digeststring-bytes)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Computes the hash value for the passed string input using the passed secret key. |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMac.md#digeststring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Computes the hash value for the passed string input using the passed secret key. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### HMAC_MD5

- HMAC_MD5: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacMD5"
  - : Constant representing the HMAC-MD5 keyed-hashing algorithm as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997).
      This algorithm uses as MD5 cryptographic hash function.
      
      
      This algorithm is obsolete. Do not use it for any sensitive data



---

### HMAC_SHA_1

- HMAC_SHA_1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "HmacSHA1"
  - : Constant representing the HmacSHA1 algorithms as defined in RFC 2104 "HMAC: Keyed-Hashing for Message Authentication" (February 1997)
      with SHA-1 as the message digest algorithm.
      
      
      This algorithm is obsolete. Do not use it for any sensitive data



---

## Constructor Details

### WeakMac(String)
- WeakMac(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a Mac encryption instance with the specified algorithm name. The
      supported algorithms are:
      
      
      - HmacMD5
      - HmacSHA1


    **Parameters:**
    - algorithm - the standard name of the digest algorithm, must not be             null.

    **Throws:**
    - NullArgumentException - if algorithm is null.
    - IllegalArgumentException - if the specified algorithm name is not              supported.


---

## Method Details

### digest(Bytes, Bytes)
- digest(input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), key: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed bytes input using the passed secret key.

    **Parameters:**
    - input - The bytes to calculate a RFC 2104 compliant HMAC hash value.
    - key - The secret key as byte array ready for use with the algorithm.           The key's format depends on the chosen algorithm and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.           Only such keys that have no key parameters associated with them.

    **Returns:**
    - The resulting hash value as bytes.

    **Throws:**
    - IllegalArgumentException - if algorithm is not null and the              specified algorithm name is not supported.


---

### digest(String, Bytes)
- digest(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed string input using the passed secret key.
      Given input will be first converted with UTF-8 encoding into a byte array.
      The resulting hash is typically converted with base64 back into a string.


    **Parameters:**
    - input - A string to calculate a RFC 2104 compliant HMAC hash value for.
    - key - The secret key as bytes ready for use with the algorithm.           The key's format depends on the chosen algorithm and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.           Only such keys that have no key parameters associated with them.

    **Returns:**
    - The resulting hash value as bytes.

    **Throws:**
    - IllegalArgumentException - if algorithm is not null and the              specified algorithm name is not supported.


---

### digest(String, String)
- digest(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed string input using the passed secret key.
      Given input and the given key will be first converted with UTF-8 encoding into a byte array.
      The resulting hash is typically converted with base64 back into a string.


    **Parameters:**
    - input - A string to calculate a RFC 2104 compliant HMAC hash value for.
    - key - The secret key ready for use with the algorithm.           The key's format depends on the chosen algorithm and the           keys are assumed to be correctly formulated for the algorithm           used, for example that the lengths are correct.           Keys are _not_ checked for validity.           Only such keys that have no key parameters associated with them.

    **Returns:**
    - The resulting hash value as bytes.

    **Throws:**
    - IllegalArgumentException - if algorithm is not null and the              specified algorithm name is not supported.


---

<!-- prettier-ignore-end -->

<!-- document id=be4317b5c88026cae96160433c3e2454ad9e6cfbd4e0b535828f9c3214380df5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.WeakMap.md -->

<!-- prettier-ignore-start -->
# Class WeakMap

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.WeakMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md)

The WeakMap is map whose entries are subject to garbage collection if there are no more references to the keys.
Keys must be objects (no primitives). Elements can't be iterated.


**API Version:**
**note:** Available from version 21.2.

## Property Summary

| Property | Description |
| --- | --- |
| [size](#size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | Number of key/value pairs stored in this map. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WeakMap](#weakmap)() | Creates an empty map. |
| [WeakMap](#weakmapiterable)([Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)) | If the passed value is null or undefined then an empty map is constructed. |

## Method Summary

| Method | Description |
| --- | --- |
| [clear](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md#clear)() | Removes all key/value pairs from this map. |
| [delete](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md#deleteobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Removes the entry for the given key. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md#getobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the value associated with the given key. |
| [has](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md#hasobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if this map has value associated with the given key. |
| [set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md#setobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds or updates a key/value pair to the map. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### size
- size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Number of key/value pairs stored in this map.


---

## Constructor Details

### WeakMap()
- WeakMap()
  - : Creates an empty map.


---

### WeakMap(Iterable)
- WeakMap(values: [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md))
  - : If the passed value is null or undefined then an empty map is constructed. Else an iterator object is expected
      that produces a two-element array-like object whose first element is a value that will be used as a Map key and
      whose second element is the value to associate with that key.


    **Parameters:**
    - values - The initial map values


---

## Method Details

### clear()
- clear(): void
  - : Removes all key/value pairs from this map.


---

### delete(Object)
- delete(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Removes the entry for the given key.

    **Parameters:**
    - key - The key of the key/value pair to be removed from the map.

    **Returns:**
    - `true` if the map contained an entry for the passed key that was removed. Else `false` is returned.


---

### get(Object)
- get(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value associated with the given key.

    **Parameters:**
    - key - The key to look for.

    **Returns:**
    - The value associated with the given key if an entry with the key exists else `undefined` is returned.


---

### has(Object)
- has(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if this map has value associated with the given key.

    **Parameters:**
    - key - The key to look for.

    **Returns:**
    - `true` if an entry with the key exists else `false` is returned.


---

### set(Object, Object)
- set(key: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [WeakMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md)
  - : Adds or updates a key/value pair to the map.

    **Parameters:**
    - key - The key object.
    - value - The value to be associate with the key.

    **Returns:**
    - This map object.


---

<!-- prettier-ignore-end -->

<!-- document id=39c42dfbef375c4598553adf7115b6388bd2f3ca638429ec8e460bcd8490d024 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.WeakMessageDigest.md -->

<!-- prettier-ignore-start -->
# Class WeakMessageDigest

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.WeakMessageDigest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMessageDigest.md)

This API provides access to Deprecated algorithms.


See [MessageDigest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md) for full documentation. WeakMessageDigest is simply a drop-in replacement that **only** supports
deprecated algorithms. This is helpful when you need to deal with weak algorithms for backward
compatibility purposes, but MessageDigest should always be used for new development and for anything intended to be secure.


**Note:** this class handles sensitive security-related data.
Pay special attention to PCI DSS v3. requirements 2, 4, and 12.



## Constant Summary

| Constant | Description |
| --- | --- |
| [DIGEST_MD2](#digest_md2): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD2" | Constant representing the MD2 algorithm. |
| [DIGEST_MD5](#digest_md5): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD5" | Constant representing the MD5 algorithm. |
| [DIGEST_SHA](#digest_sha): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA" | Constant representing the SHA algorithm. |
| [DIGEST_SHA_1](#digest_sha_1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-1" | Constant representing the SHA 1 algorithm. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WeakMessageDigest](#weakmessagedigeststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Construct a MessageDigest with the specified algorithm name. |

## Method Summary

| Method | Description |
| --- | --- |
| [digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMessageDigest.md#digest)() | Completes the hash computation by performing final operations such as  padding. |
| ~~[digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMessageDigest.md#digeststring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Digests the passed string and returns a computed hash value as a string. |
| ~~[digest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMessageDigest.md#digeststring-bytes)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md))~~ | Computes the hash value for the passed array of bytes. |
| [digestBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMessageDigest.md#digestbytesbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Computes the hash value for the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md). |
| [updateBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMessageDigest.md#updatebytesbytes)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)) | Updates the digest using the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DIGEST_MD2

- DIGEST_MD2: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD2"
  - : Constant representing the MD2 algorithm.
      
      
      This algorithm is obsolete. Do not use it for any sensitive data



---

### DIGEST_MD5

- DIGEST_MD5: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "MD5"
  - : Constant representing the MD5 algorithm.
      
      
      This algorithm is obsolete. Do not use it for any sensitive data



---

### DIGEST_SHA

- DIGEST_SHA: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA"
  - : Constant representing the SHA algorithm.
      
      
      This algorithm is obsolete. Do not use it for any sensitive data



---

### DIGEST_SHA_1

- DIGEST_SHA_1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SHA-1"
  - : Constant representing the SHA 1 algorithm.
      
      
      This algorithm is obsolete. Do not use it for any sensitive data



---

## Constructor Details

### WeakMessageDigest(String)
- WeakMessageDigest(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Construct a MessageDigest with the specified algorithm name.

    **Parameters:**
    - algorithm - The standard name of the digest algorithm, must not be         null and must be a supported algorithm.


---

## Method Details

### digest()
- digest(): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Completes the hash computation by performing final operations such as
      padding.
      
      The binary representation of the message is typically derived from a
      string and the resulting hash is typically converted with base64 back
      into a string. Example:
      
      `
       Encoding.toBase64( digest() );
       `


    **Returns:**
    - The resulting hash value.


---

### digest(String)
- ~~digest(input: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Digests the passed string and returns a computed hash value as a string.
      The passed String is first encoded into a sequence of bytes using the
      platform's default encoding. The digest then performs any prerequisite
      padding, before computing the hash value. The hash is then converted into
      a string by converting all digits to hexadecimal.


    **Parameters:**
    - input - The value to hash as String, must not be null.

    **Returns:**
    - The resulting hash value as hex-encoded string.

    **Deprecated:**
**warning:** Deprecated because the conversion of the input to bytes using
            the default platform encoding and the hex-encoded return
            value are not generally appropriate.

---

### digest(String, Bytes)
- ~~digest(algorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)~~
  - : Computes the hash value for the passed array of bytes. The algorithm
      argument is optional. If null, then the algorithm established at
      construction time is used.
      
      The binary representation of the message is typically derived from a
      string and the resulting hash is typically converted with base64 back
      into a string. Example:
      
      `
       Encoding.toBase64( digest( "MD5", new Bytes( "my password", "UTF-8" ) ) );
       `


    **Parameters:**
    - algorithm - The standard name of the digest algorithm, or null if             the algorithm passed at construction time is to be used.             The algorithm must be a supported algorithm.
    - input - The value to hash, must not be null.

    **Returns:**
    - The resulting hash value.

    **Deprecated:**
**warning:** Deprecated because the digest algorithm should be the one
            set in the constructor.

---

### digestBytes(Bytes)
- digestBytes(input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Computes the hash value for the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md).
      
      The binary representation of the message is typically derived from a
      string and the resulting hash is typically converted with base64 back
      into a string. Example:
      
      `
       Encoding.toBase64( digest( new Bytes( "my password", "UTF-8" ) ) );
       `


    **Parameters:**
    - input - The value to hash, must not be null.

    **Returns:**
    - The resulting hash value.


---

### updateBytes(Bytes)
- updateBytes(input: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)): void
  - : Updates the digest using the passed [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md).

    **Parameters:**
    - input - The value to hash, must not be null.


---

<!-- prettier-ignore-end -->

<!-- document id=3c809b2b1f477413ad7f71a54b57276c7a0f28eb8a535243ee79a5d2defd7af4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.WeakSet.md -->

<!-- prettier-ignore-start -->
# Class WeakSet

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.WeakSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakSet.md)

The WeakSet is set whose elements are subject to garbage collection if there are no more references to the elements.
Only objects (no primitives) can be stored. Elements can't be iterated.


**API Version:**
**note:** Available from version 21.2.

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WeakSet](#weakset)() | Creates an empty Set. |
| [WeakSet](#weaksetiterable)([Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)) | If the passed value is null or undefined then an empty set is constructed. |

## Method Summary

| Method | Description |
| --- | --- |
| [add](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakSet.md#addobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds an element to the set. |
| [delete](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakSet.md#deleteobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Removes the element from the set. |
| [has](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakSet.md#hasobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns if this set contains the given object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### WeakSet()
- WeakSet()
  - : Creates an empty Set.


---

### WeakSet(Iterable)
- WeakSet(values: [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md))
  - : If the passed value is null or undefined then an empty set is constructed. Else an iterable object is expected
      that delivers the initial set entries.


    **Parameters:**
    - values - The initial set entries.


---

## Method Details

### add(Object)
- add(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [WeakSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakSet.md)
  - : Adds an element to the set. Does nothing if the set already contains the element.

    **Parameters:**
    - object - The object to add.

    **Returns:**
    - This set object.


---

### delete(Object)
- delete(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Removes the element from the set.

    **Parameters:**
    - object - The object to be removed.

    **Returns:**
    - `true` if the set contained the object that was removed. Else `false` is returned.


---

### has(Object)
- has(object: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns if this set contains the given object.

    **Parameters:**
    - object - The object to look for.

    **Returns:**
    - `true` if the set contains the object else `false` is returned.


---

<!-- prettier-ignore-end -->

<!-- document id=ce7f7119730728e557798fca6419d1cbe8d183872909077a2720e1a7aea454f5 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.WeakSignature.md -->

<!-- prettier-ignore-start -->
# Class WeakSignature

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.WeakSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md)

This API provides access to Deprecated algorithms.


See [Signature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md) for full documentation. WeakSignature is simply a drop-in replacement that **only** supports
deprecated algorithms. This is helpful when you need to deal with weak algorithms for backward compatibility
purposes, but Signature should always be used for new development and for anything intended to be secure.




This class allows access to signature services offered through the Java Cryptography Architecture (JCA). At this time
the signature/verification implementation of the methods is based on the default RSA JCE provider of the JDK -
sun.security.rsa.SunRsaSign




dw.crypto.WeakSignature is an adapter to the security provider implementation and only covers one digest algorithm:

- SHA1withRSA





**Note:** this class handles sensitive security-related data. Pay special attention to PCI DSS v3. requirements 2,
4, 12, and other relevant requirements.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WeakSignature](#weaksignature)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| [isDigestAlgorithmSupported](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#isdigestalgorithmsupportedstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Checks to see if a digest algorithm is supported |
| [sign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#signstring-keyref-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs a string and returns a string |
| [sign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#signstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs a string and returns a string |
| [signBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#signbytesbytes-keyref-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs bytes and returns bytes |
| [signBytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#signbytesbytes-string-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Signs bytes and returns bytes |
| [verifyBytesSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#verifybytessignaturebytes-bytes-certificateref-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as bytes |
| [verifyBytesSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#verifybytessignaturebytes-bytes-string-string)([Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as bytes |
| [verifySignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#verifysignaturestring-string-certificateref-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as string |
| [verifySignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md#verifysignaturestring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Verifies a signature supplied as string |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### WeakSignature()
- WeakSignature()
  - : 


---

## Method Details

### isDigestAlgorithmSupported(String)
- isDigestAlgorithmSupported(digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Checks to see if a digest algorithm is supported

    **Parameters:**
    - digestAlgorithm - the digest algorithm name

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### sign(String, KeyRef, String)
- sign(contentToSign: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Signs a string and returns a string

    **Parameters:**
    - contentToSign - base64 encoded content to sign
    - privateKey - a reference to a private key entry in the keystore
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - the base64 encoded signature


---

### sign(String, String, String)
- sign(contentToSign: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), privateKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Signs a string and returns a string

    **Parameters:**
    - contentToSign - base64 encoded content to sign
    - privateKey - base64 encoded private key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - the base64 encoded signature


---

### signBytes(Bytes, KeyRef, String)
- signBytes(contentToSign: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Signs bytes and returns bytes

    **Parameters:**
    - contentToSign - transformed with UTF-8 encoding into a byte stream
    - privateKey - a reference to a private key entry in the keystore
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - signature


---

### signBytes(Bytes, String, String)
- signBytes(contentToSign: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), privateKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)
  - : Signs bytes and returns bytes

    **Parameters:**
    - contentToSign - transformed with UTF-8 encoding into a byte stream
    - privateKey - base64 encoded private key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - signature


---

### verifyBytesSignature(Bytes, Bytes, CertificateRef, String)
- verifyBytesSignature(signature: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), contentToVerify: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), certificate: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as bytes

    **Parameters:**
    - signature - signature to check as bytes
    - contentToVerify - as bytes
    - certificate - a reference to a trusted certificate
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### verifyBytesSignature(Bytes, Bytes, String, String)
- verifyBytesSignature(signature: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), contentToVerify: [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md), publicKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as bytes

    **Parameters:**
    - signature - signature to check as bytes
    - contentToVerify - as bytes
    - publicKey - base64 encoded public key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### verifySignature(String, String, CertificateRef, String)
- verifySignature(signature: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contentToVerify: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), certificate: [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as string

    **Parameters:**
    - signature - base64 encoded signature
    - contentToVerify - base64 encoded content to verify
    - certificate - a reference to a trusted certificate
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

### verifySignature(String, String, String, String)
- verifySignature(signature: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), contentToVerify: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), publicKey: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), digestAlgorithm: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Verifies a signature supplied as string

    **Parameters:**
    - signature - base64 encoded signature
    - contentToVerify - base64 encoded content to verify
    - publicKey - base64 encoded public key
    - digestAlgorithm - must be one of the currently supported ones

    **Returns:**
    - a boolean indicating success (true) or failure (false)


---

<!-- prettier-ignore-end -->

<!-- document id=210f346d66dbf4f893e27b6b80ec2d8ffcee3732a975842c84c17199d301303a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.WebDAVClient.md -->

<!-- prettier-ignore-start -->
# Class WebDAVClient

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.WebDAVClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md)

The WebDAVClient class supports the WebDAV methods GET, PUT, MKCOL, MOVE,
COPY, PROPFIND,OPTIONS and DELETE.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.
 The client can be used as shown in the following example:



```
var webdavClient : WebDAVClient = new WebDAVClient("http://mywebdav.server.com","myusername", "mypassword");
var getString : String = webdavClient.get("myData.xml","UTF-8");
var message : String;

if (webdavClient.succeeded())
{
     message = webDavClient.statusText;
}
else
{
    // error handling
    message="An error occurred with status code "+webdavClient.statusCode;
}

var data : XML = new XML(getString);
```



The WebDAV client supports the following authentication schemes:

- Basic authentication
- Digest authentication


The methods of this class do not generally throw exceptions if the underlying
WebDAV operation do not succeed.The result of a WebDAV operation can be
checked using the methods succeeded(), getStatusCode(), and getStatusText().


Important note: This WebDAV client cannot be used to access the Commerce Cloud Digital
server via WebDAV protocol.



## Constant Summary

| Constant | Description |
| --- | --- |
| [DEFAULT_ENCODING](#default_encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UTF-8" | The default encoding character set. |
| [DEFAULT_GET_FILE_SIZE](#default_get_file_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5242880 | The default size for `get()` returning a File is 5MB. |
| [DEFAULT_GET_STRING_SIZE](#default_get_string_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2097152 | The default size for `get()` returning a String is 2MB. |
| [DEPTH_0](#depth_0): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0 | The depth of searching a WebDAV destination using the PROPFIND method -  if that depth is given to the PROPFIND method as an input parameter the  destination will be searched only on the level of the given path and a  list of all containing files on that level will be returned \[is not  supported by every server\]. |
| [DEPTH_1](#depth_1): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | The depth of searching a WebDAV destination using the PROPFIND method -  if that depth is given to the PROPFIND method as an input parameter the  destination will be searched until one level under the given path and a  list of all containing files in that two levels \[/path and one level  underneath\] will be returned \[is not supported by every server\]. |
| [DEPTH_INIFINITY](#depth_inifinity): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2147483647 | The depth of searching a WebDAV destination using the PROPFIND method -  if that depth is given to the PROPFIND method as an input parameter the  destination will be fully searched and a list of all containing files  will be returned \[is not supported by every server\]. |
| [MAX_GET_FILE_SIZE](#max_get_file_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200 | The maximum size for `get()` returning a File is forty times  the default size for getting a file. |
| [MAX_GET_STRING_SIZE](#max_get_string_size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760 | The maximum size for `get()` returning a String is five  times the default size for getting a String. |

## Property Summary

| Property | Description |
| --- | --- |
| [allResponseHeaders](#allresponseheaders): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) `(read-only)` | Returns a [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) of all response headers. |
| [statusCode](#statuscode): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the status code after the execution of a method. |
| [statusText](#statustext): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the status text after the execution of a method. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WebDAVClient](#webdavclientstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new client for the use at a server which requires  authentication. |
| [WebDAVClient](#webdavclientstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a new client for the use at a server which does not require  authentication. |

## Method Summary

| Method | Description |
| --- | --- |
| [addRequestHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#addrequestheaderstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a request header to the next WebDAV call. |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#close)() | Closes the current connection to the server. |
| [copy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#copystring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Copies a file on the server from one place `rootUrl`/`origin`  to the other `rootUrl`/`destination`. |
| [copy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#copystring-string-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Copies a file on the server from one place `rootUrl`/`origin`  to the other `rootUrl`/`destination`. |
| [copy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#copystring-string-boolean-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Copies a file on the server from one place `rootUrl`/`origin`  to the other `rootUrl`/`destination`. |
| [del](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#delstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Deletes a file or directory from the remote server that can be found  under `rootUrl`/`path`. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Reads the content of a remote file or directory that can be found under  `rootUrl`/`path` and returns a string  representation of the data found in the DEFAULT\_ENCODING encoding. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Reads the content of a remote file or directory that can be found under  `rootUrl`/`path` in DEFAULT\_ENCODING  encoding and writes a [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) in the system's standard  encoding, which is "UTF-8". |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstring-file-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Reads the content of a remote file or directory that can be found under  `rootUrl`/`path` in DEFAULT\_ENCODING  encoding and writes a [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) in the system's standard  encoding, which is "UTF-8". |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstring-file-string-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Reads the content of a remote file or directory that can be found under  `rootUrl`/`path` in the passed encoding and  writes a [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) in the system standard encoding, which is  "UTF-8". |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Reads the content of a remote file or directory that can be found under  `rootUrl`/`path` and returns a string  representation of the data found in the given `encoding`. |
| [get](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstring-string-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Reads the content of a remote file or directory that can be found under  `rootUrl`/`path` and returns a string  representation of the data found in the given `encoding`. |
| [getAllResponseHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getallresponseheaders)() | Returns a [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) of all response headers. |
| [getBinary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getbinarystring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Reads the content of a remote binary file that can be found under  `rootUrl`/`path` and creates a local copy  in [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md). |
| [getBinary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getbinarystring-file-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Reads the content of a remote binary file that can be found under  `rootUrl`/`path` and creates a local copy  in [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md). |
| [getResponseHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getresponseheaderstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a specified response header - multiple headers are separated by  CRLF. |
| [getStatusCode](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstatuscode)() | Returns the status code after the execution of a method. |
| [getStatusText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#getstatustext)() | Returns the status text after the execution of a method. |
| [mkcol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#mkcolstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Creates a directory on the remote server on the location  `rootUrl`/`path`. |
| [move](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#movestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Moves a file on the server from one place `rootUrl` + "/" +`origin`  to the other `rootUrl`/`destination`. |
| [move](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#movestring-string-boolean)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Moves a file on the server from one place `rootUrl`/`origin`  to the other `rootUrl`/`destination` Can  also be used to rename a remote file. |
| [options](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#optionsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a list of methods which can be executed on the server location  `rootUrl`/`path`. |
| [propfind](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#propfindstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Get file listing of a remote location. |
| [propfind](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#propfindstring-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Get file listing of a remote location. |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#putstring-file)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)) | Puts content out of a passed local file into a remote located file  at `rootUrl`/`path`. |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#putstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Puts content encoded with DEFAULT\_ENCODING into a remote located file at  `rootUrl`/`path`. |
| [put](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#putstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Puts content encoded with the passed encoding into a remote located file  at `rootUrl`/`path`. |
| [succeeded](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#succeeded)() | Returns true if the last executed WebDAV method was executed successfully - otherwise false. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### DEFAULT_ENCODING

- DEFAULT_ENCODING: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UTF-8"
  - : The default encoding character set.


---

### DEFAULT_GET_FILE_SIZE

- DEFAULT_GET_FILE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5242880
  - : The default size for `get()` returning a File is 5MB.


---

### DEFAULT_GET_STRING_SIZE

- DEFAULT_GET_STRING_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2097152
  - : The default size for `get()` returning a String is 2MB.


---

### DEPTH_0

- DEPTH_0: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 0
  - : The depth of searching a WebDAV destination using the PROPFIND method -
      if that depth is given to the PROPFIND method as an input parameter the
      destination will be searched only on the level of the given path and a
      list of all containing files on that level will be returned \[is not
      supported by every server\].



---

### DEPTH_1

- DEPTH_1: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : The depth of searching a WebDAV destination using the PROPFIND method -
      if that depth is given to the PROPFIND method as an input parameter the
      destination will be searched until one level under the given path and a
      list of all containing files in that two levels \[/path and one level
      underneath\] will be returned \[is not supported by every server\].



---

### DEPTH_INIFINITY

- DEPTH_INIFINITY: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2147483647
  - : The depth of searching a WebDAV destination using the PROPFIND method -
      if that depth is given to the PROPFIND method as an input parameter the
      destination will be fully searched and a list of all containing files
      will be returned \[is not supported by every server\].



---

### MAX_GET_FILE_SIZE

- MAX_GET_FILE_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 209715200
  - : The maximum size for `get()` returning a File is forty times
      the default size for getting a file. The largest file allowed is 200MB.



---

### MAX_GET_STRING_SIZE

- MAX_GET_STRING_SIZE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10485760
  - : The maximum size for `get()` returning a String is five
      times the default size for getting a String. The largest String allowed
      is 10MB.



---

## Property Details

### allResponseHeaders
- allResponseHeaders: [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) `(read-only)`
  - : Returns a [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) of all response headers.


---

### statusCode
- statusCode: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the status code after the execution of a method.


---

### statusText
- statusText: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the status text after the execution of a method.


---

## Constructor Details

### WebDAVClient(String, String, String)
- WebDAVClient(rootUrl: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), username: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new client for the use at a server which requires
      authentication.
      The client supports the following authentication schemes:
           - Basic authentication scheme
           - Digest authentication scheme


    **Parameters:**
    - rootUrl - the url of the server one wants to connect to. All commands             will be executed by the client relative to that url.
    - username - username of the user for server authentication.
    - password - password of the user for server authentication.


---

### WebDAVClient(String)
- WebDAVClient(rootUrl: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Creates a new client for the use at a server which does not require
      authentication.


    **Parameters:**
    - rootUrl - the url of the server one wants to connect to. All commands             will be executed by the client relative to that url.


---

## Method Details

### addRequestHeader(String, String)
- addRequestHeader(headerName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), headerValue: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a request header to the next WebDAV call.

    **Parameters:**
    - headerName - name of the header.
    - headerValue - value of the header.


---

### close()
- close(): void
  - : Closes the current connection to the server.


---

### copy(String, String)
- copy(origin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), destination: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Copies a file on the server from one place `rootUrl`/`origin`
      to the other `rootUrl`/`destination`. If
      `destination` already exists it gets overwritten. Returns
      true if succeeded, otherwise false.


    **Parameters:**
    - origin - The origin where a file is located, relative to the             `rootUrl` stated when instantiating the client.
    - destination - The destination where the file should be copied to, relative             to the `rootUrl` stated when instantiating the             client.

    **Returns:**
    - true if succeeded, otherwise false.


---

### copy(String, String, Boolean)
- copy(origin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), destination: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), overwrite: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Copies a file on the server from one place `rootUrl`/`origin`
      to the other `rootUrl`/`destination`. If
      the passed parameter `overwrite` is true and
      `destination` already exists it gets overwritten. Returns
      true if succeeded, otherwise false.


    **Parameters:**
    - origin - The origin where a file is located, relative to the             `rootUrl` stated when instantiating the client.
    - destination - The destination where the file should be copied to, relative             to the `rootUrl` stated when instantiating the             client.
    - overwrite - A flag which determines whether the destination gets             overwritten if it exists before copying.

    **Returns:**
    - true if succeeded, otherwise false.


---

### copy(String, String, Boolean, Boolean)
- copy(origin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), destination: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), overwrite: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), shallow: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Copies a file on the server from one place `rootUrl`/`origin`
      to the other `rootUrl`/`destination`. If
      the passed parameter `overwrite` is true and
      `destination` already exists it gets overwritten. If the
      passed parameter `shallow` is true a flat copy mechanism is
      used.
      
      Returns true if succeeded, otherwise false.


    **Parameters:**
    - origin - The origin where a file is located, relative to the             `rootUrl` stated when instantiating the client.
    - destination - The destination where the file should be copied to, relative             to the `rootUrl` stated when instantiating the             client.
    - overwrite - A flag which determines whether the destination gets             overwritten if it exits before copying
    - shallow - A flag which determines how to copy the given data.

    **Returns:**
    - true if succeeded, otherwise false.


---

### del(String)
- del(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Deletes a file or directory from the remote server that can be found
      under `rootUrl`/`path`. Returns true if
      succeeded, otherwise false.


    **Parameters:**
    - path - The path of the file or collection to delete, relative to the             `rootUrl` stated when instantiating the client.

    **Returns:**
    - true if succeeded, otherwise false.


---

### get(String)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a remote file or directory that can be found under
      `rootUrl`/`path` and returns a string
      representation of the data found in the DEFAULT\_ENCODING encoding. If the
      remote location is a directory the result depends on the server
      configuration, some return an HTML formatted directory listing. Returns
      at most DEFAULT\_GET\_STRING\_SIZE bytes.


    **Parameters:**
    - path - The path of the collection or file one wants to get, relative             to the `rootUrl` stated when instantiating the             client.

    **Returns:**
    - returns the String representation of the data found on the given
              path.



---

### get(String, File)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote file or directory that can be found under
      `rootUrl`/`path` in DEFAULT\_ENCODING
      encoding and writes a [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) in the system's standard
      encoding, which is "UTF-8". If the remote location is a directory the
      result depends on the server configuration, some return an HTML formatted
      directory listing. Receives at most DEFAULT\_GET\_FILE\_SIZE bytes which
      determines the file size of the local file. Returns true if succeeded
      otherwise false.


    **Parameters:**
    - path - The path of the collection or file one wants to get -             relative to the `rootUrl` stated when instantiating             the client.
    - file - The file to save the received data in.

    **Returns:**
    - returns true if succeeded, otherwise false.


---

### get(String, File, Number)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), maxFileSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote file or directory that can be found under
      `rootUrl`/`path` in DEFAULT\_ENCODING
      encoding and writes a [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) in the system's standard
      encoding, which is "UTF-8". If the remote location is a directory the
      result depends on the server configuration, some return an HTML formatted
      directory listing. Receives at most maxFileSize bytes which determines
      the file size of the local file. Returns true if succeeded, otherwise
      false.


    **Parameters:**
    - path - The path of the collection or file one wants to get -             relative to the `rootUrl` stated when instantiating             the client.
    - file - The file to save the received data in.
    - maxFileSize - The maximum size of bytes to stream into the file. Not             to exceed MAX\_GET\_FILE\_SIZE.

    **Returns:**
    - returns true if succeeded, otherwise false.


---

### get(String, File, String, Number)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxFileSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote file or directory that can be found under
      `rootUrl`/`path` in the passed encoding and
      writes a [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md) in the system standard encoding, which is
      "UTF-8". If the remote location is a directory the result depends on the
      server configuration, some return an HTML formatted directory listing.
      Receives at most maxFileSize bytes which determines the file size of the
      local file. Returns true if succeeded, otherwise false.


    **Parameters:**
    - path - The path of the collection or file one wants to get -             relative to the `rootUrl` stated when instantiating             the client.
    - file - The file to save the received data in.
    - encoding - The encoding to use when reading the remote file.
    - maxFileSize - The maximum number of bytes to stream into the file.             Not to exceed MAX\_GET\_FILE\_SIZE.

    **Returns:**
    - returns true if succeeded, otherwise false.


---

### get(String, String)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a remote file or directory that can be found under
      `rootUrl`/`path` and returns a string
      representation of the data found in the given `encoding`. If
      the remote location is a directory the result depends on the server
      configuration, some return an HTML formatted directory listing. Returns
      at most DEFAULT\_GET\_STRING\_SIZE bytes.


    **Parameters:**
    - path - The path of the collection or file one wants to get -             relative to the `rootUrl` stated when instantiating             the client.
    - encoding - The encoding of the resulting String.

    **Returns:**
    - returns the String representation of the data found on the given
              path in the given encoding.



---

### get(String, String, Number)
- get(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), maxGetSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a remote file or directory that can be found under
      `rootUrl`/`path` and returns a string
      representation of the data found in the given `encoding`. If
      the remote location is a directory the result depends on the server
      configuration, some return an HTML formatted directory listing. Returns
      at most maxGetSize bytes.


    **Parameters:**
    - path - The path of the collection or file one wants to get -             relative to the `rootUrl` stated when instantiating             the client.
    - encoding - The encoding of the resulting String.
    - maxGetSize - The maximum size of data in bytes. Not to exceed             MAX\_GET\_STRING\_SIZE.

    **Returns:**
    - returns the String representation of the data found on the given
              path in the given encoding.



---

### getAllResponseHeaders()
- getAllResponseHeaders(): [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)
  - : Returns a [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md) of all response headers.

    **Returns:**
    - all headers in a [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md).


---

### getBinary(String, File)
- getBinary(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote binary file that can be found under
      `rootUrl`/`path` and creates a local copy
      in [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md). If the remote location is a directory the result
      depends on the server configuration, some return an HTML formatted
      directory listing. Copies at most DEFAULT\_GET\_FILE\_SIZE bytes. Returns
      true if succeeded, otherwise false.


    **Parameters:**
    - path - The path relative to `rootUrl` on the remote             server including the file name.
    - file - The local file where the received binary data should be             stored.

    **Returns:**
    - true if succeeded, otherwise false.


---

### getBinary(String, File, Number)
- getBinary(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md), maxFileSize: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Reads the content of a remote binary file that can be found under
      `rootUrl`/`path` and creates a local copy
      in [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md). If the remote location is a directory the result
      depends on the server configuration, some return an HTML formatted
      directory listing. Copies at most maxFileSize bytes. Returns true if
      succeeded, otherwise false.


    **Parameters:**
    - path - The path relative to `rootUrl` on the remote             server including the file name.
    - file - The file local file where the received binary data should be             stored.
    - maxFileSize - The maximum number of bytes to stream into the file.             Not to exceed MAX\_GET\_FILE\_SIZE.

    **Returns:**
    - true if succeeded, otherwise false.


---

### getResponseHeader(String)
- getResponseHeader(header: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a specified response header - multiple headers are separated by
      CRLF.


    **Parameters:**
    - header - The name of the header.

    **Returns:**
    - The header - in case of multiple headers separated by CRLF.


---

### getStatusCode()
- getStatusCode(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the status code after the execution of a method.

    **Returns:**
    - the `statusCode`.


---

### getStatusText()
- getStatusText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the status text after the execution of a method.

    **Returns:**
    - the `statusText`.


---

### mkcol(String)
- mkcol(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Creates a directory on the remote server on the location
      `rootUrl`/`path`.


    **Parameters:**
    - path - The path relative to the `rootUrl` stated when             instantiating the client where the new collection should be             created.

    **Returns:**
    - true if succeeded, otherwise false.


---

### move(String, String)
- move(origin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), destination: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Moves a file on the server from one place `rootUrl` + "/" +`origin`
      to the other `rootUrl`/`destination`. If
      `destination` already exists it gets overwritten. Can also
      be used to rename a remote file. Returns true if succeeded, otherwise
      false.


    **Parameters:**
    - origin - The origin where a file is located, relative to the             `rootUrl` stated when instantiating the client.
    - destination - The destination where the file should be moved to, relative             to the `rootUrl` stated when instantiating the             client.

    **Returns:**
    - true if succeeded, otherwise false.


---

### move(String, String, Boolean)
- move(origin: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), destination: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), overwrite: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Moves a file on the server from one place `rootUrl`/`origin`
      to the other `rootUrl`/`destination` Can
      also be used to rename a remote file. If `overwrite` is true
      and `destination` already exists it gets overwritten.
      Returns true if succeeded, otherwise false.


    **Parameters:**
    - origin - The origin where a file is located, relative to the             `rootUrl` stated when instantiating the client.
    - destination - The destination where the file should be moved to, relative             to the `rootUrl` stated when instantiating the             client.
    - overwrite - A flag which determines whether the destination gets             overwritten if it exists before moving.

    **Returns:**
    - true if succeeded, otherwise false.


---

### options(String)
- options(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String\[\]](TopLevel.String.md)
  - : Returns a list of methods which can be executed on the server location
      `rootUrl`/`path`.


    **Parameters:**
    - path - The path relative to the `rootUrl` stated when             instantiating the client one wants to get the options for.

    **Returns:**
    - list of WebDav methods which can be executed on the given path.


---

### propfind(String)
- propfind(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [WebDAVFileInfo\[\]](dw.net.WebDAVFileInfo.md)
  - : Get file listing of a remote location.
      
      Returns a list of [WebDAVFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md) objects which contain
      information about the files and directories located on
      `rootUrl`/`path` and DEPTH\_1 (1) level
      underneath.


    **Parameters:**
    - path - The path relative to the `rootUrl` stated when             instantiating the client where to get information about the             containing files from.

    **Returns:**
    - an Array of [WebDAVFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md) objects which hold
              information about the files located on the server at the
              location.



---

### propfind(String, Number)
- propfind(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), depth: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [WebDAVFileInfo\[\]](dw.net.WebDAVFileInfo.md)
  - : Get file listing of a remote location.
      
      Returns a list of [WebDAVFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md) objects which contain
      information about the files and directories located on
      `rootUrl`/`path` and the passed depth
      underneath.


    **Parameters:**
    - path - The path relative to the `rootUrl` stated when             instantiating the client where to get information about the             containing files from.
    - depth - The level starting from `rootUrl` down to which             the file information gets collected.

    **Returns:**
    - an Array of [WebDAVFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md) objects which hold
              information about the files located on the server at the
              location.



---

### put(String, File)
- put(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), file: [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Puts content out of a passed local file into a remote located file
      at `rootUrl`/`path`. This method performs
      a binary file transfer. Returns true if succeeded, otherwise false.


    **Parameters:**
    - path - The path to put given content up to, relative to the             `rootUrl` stated when instantiating the client.
    - file - The file to push up to the server.

    **Returns:**
    - true if succeeded, otherwise false.


---

### put(String, String)
- put(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Puts content encoded with DEFAULT\_ENCODING into a remote located file at
      `rootUrl`/`path`. Returns true if
      succeeded, otherwise false.
      
      
      If the content of a local file is to be uploaded, please use method
      [put(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#putstring-file) instead.


    **Parameters:**
    - path - The path to put given content up to, relative to the             `rootUrl` stated when instantiating the client.
    - content - The content that has to be pushed on to the server.

    **Returns:**
    - true if succeeded, otherwise false.


---

### put(String, String, String)
- put(path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), content: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Puts content encoded with the passed encoding into a remote located file
      at `rootUrl`/`path`. Returns true if
      succeeded, otherwise false.
      
      
      If the content of a local file is to be uploaded, please use method
      [put(String, File)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#putstring-file) instead.


    **Parameters:**
    - path - The path to put a given content up to, relative to the             `rootUrl` stated when instantiating the client.
    - content - The content that has to be pushed on to a remote location.
    - encoding - The encoding in which the data should be stored on the             server.

    **Returns:**
    - true if succeeded, otherwise false.


---

### succeeded()
- succeeded(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the last executed WebDAV method was executed successfully - otherwise false.
      See the code snippet above for an example how to use the succeed() method.


    **Returns:**
    - true if the last executed WebDAV method was successful - otherwise false.

    **See Also:**
    - [WebDAVClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md)


---

<!-- prettier-ignore-end -->

<!-- document id=587ddc5c095379527c5c9b38459261c5c52aa40a502c490a772299ecf9569237 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.WebDAVFileInfo.md -->

<!-- prettier-ignore-start -->
# Class WebDAVFileInfo

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.net.WebDAVFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md)

Simple class representing a file on a remote WebDAV location.  The class
possesses only read-only attributes of the file and does not permit any
manipulation of the file itself.  Instances of this class are returned
by [WebDAVClient.propfind(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md#propfindstring) which is used to get a
listing of files in a WebDAV directory.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## Property Summary

| Property | Description |
| --- | --- |
| [contentType](#contenttype): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the content type of the file. |
| [creationDate](#creationdate): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the creationDate of the file. |
| [directory](#directory): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the file is a directory. |
| [name](#name): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the name of the file. |
| [path](#path): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the path of the file. |
| [size](#size): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the size of the file. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getContentType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md#getcontenttype)() | Returns the content type of the file. |
| [getCreationDate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md#getcreationdate)() | Returns the creationDate of the file. |
| [getName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md#getname)() | Returns the name of the file. |
| [getPath](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md#getpath)() | Returns the path of the file. |
| [getSize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md#getsize)() | Returns the size of the file. |
| [isDirectory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md#isdirectory)() | Identifies if the file is a directory. |
| [lastModified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md#lastmodified)() | Returns the lastModified date of the file. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### contentType
- contentType: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the content type of the file.


---

### creationDate
- creationDate: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the creationDate of the file.


---

### directory
- directory: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the file is a directory.


---

### name
- name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the name of the file.


---

### path
- path: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the path of the file.


---

### size
- size: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the size of the file.


---

## Method Details

### getContentType()
- getContentType(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the content type of the file.

    **Returns:**
    - the content type of the file.


---

### getCreationDate()
- getCreationDate(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the creationDate of the file.

    **Returns:**
    - the creationDate of the file.


---

### getName()
- getName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the name of the file.

    **Returns:**
    - the name of the file.


---

### getPath()
- getPath(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the path of the file.

    **Returns:**
    - the path of the file.


---

### getSize()
- getSize(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the size of the file.

    **Returns:**
    - the size of the file.


---

### isDirectory()
- isDirectory(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the file is a directory.

    **Returns:**
    - true if the file is a directory, false otherwise.


---

### lastModified()
- lastModified(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the lastModified date of the file.

    **Returns:**
    - the lastModified date of the file.


---

<!-- prettier-ignore-end -->

<!-- document id=1aa1deb9849b7cfc7642249ae75c2b505ba61c5a52d728c12c031267b02bf864 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.rpc.WebReference.md -->

<!-- prettier-ignore-start -->
# Class WebReference

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.rpc.WebReference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.WebReference.md)

Represents a web service defined in a WSDL file. The implementation is backed by a JAX-RPC framework.
You should use the newer dw.ws package and [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md) class instead, which is based on JAX-WS.


Use the Services module in Business Manager to set timeout values, not the methods for this class.
The Services module provides better analytics and timeout management.

To create an instance of a WebReference object, in a B2C Commerce Script file, reference a WSDL file in the `webreferences`
directory and request the service [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md) using one of the get service methods.
For example, if your WSDL file is `MyWSDL.wsdl`,
to create an instance of WebReference and access the [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md):



```
var webref : WebReference = webreferences.MyWSDL;
var stub : Stub = webref.getDefaultService();
```


**Note:** script classes representing your WSDL file are are generated by the platform and then placed in the `WebReferences`
package. You do not need to include the `importPackage`
statement in your B2C Commerce Script file to use classes in the `WebReferences` package.


**See Also:**
- [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)
- [SOAPUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md)

**Deprecated:**
**warning:** This class is deprecated, please use webreferences2 instead (see also [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)).
            
In migrating from webreferences to webreferences2 the property `collectionType=indexed` may be helpful.
            Setting this in the property file for the WSDL will make the generated API more closely resemble the API generated by webreferences.

## Property Summary

| Property | Description |
| --- | --- |
| ~~[defaultService](#defaultservice): [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)~~ `(read-only)` | Returns the default service of the WebReference object. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WebReference](#webreference)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| ~~[getDefaultService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.WebReference.md#getdefaultservice)()~~ | Returns the default service of the WebReference object. |
| ~~[getService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.WebReference.md#getservicestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))~~ | Returns a specific service from this WebReference. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### defaultService
- ~~defaultService: [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)~~ `(read-only)`
  - : Returns the default service of the WebReference object. If you have more than one service
      defined in your WSDL, the default service is the first service alphabetically. If the service
      has multiple ports defined, the default service uses the SOAP port name that is first alphabetically.


    **Deprecated:**
**warning:** use webreferences2 instead

---

## Constructor Details

### WebReference()
- WebReference()
  - : 


---

## Method Details

### getDefaultService()
- ~~getDefaultService(): [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)~~
  - : Returns the default service of the WebReference object. If you have more than one service
      defined in your WSDL, the default service is the first service alphabetically. If the service
      has multiple ports defined, the default service uses the SOAP port name that is first alphabetically.


    **Returns:**
    - the default service of the WebReference object.

    **Deprecated:**
**warning:** use webreferences2 instead

---

### getService(String, String)
- ~~getService(service: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), port: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)~~
  - : Returns a specific service from this WebReference.

    **Parameters:**
    - service - the service to locate.
    - port - the port name to use.  
```
 var port =  webref.getService("SampleServiceName","SamplePortName");
```


    **Returns:**
    - a specific service from this WebReference.

    **Deprecated:**
**warning:** use webreferences2 instead

---

<!-- prettier-ignore-end -->

<!-- document id=49985746c0832c794f497fcbc12617262a67d38c90519e578b27cee85a382d1f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.ws.WebReference2.md -->

<!-- prettier-ignore-start -->
# Class WebReference2

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.ws.WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)

Represents a web service defined in a WSDL file. The implementation is backed by a JAX-WS framework.


This implementation does not support `RPC/encoded` WSDLs. Such a WSDL must be migrated to a
supported encoding such as `Document/literal` to work with this API.


To create an instance of a WebReference2, you put a web service WSDL file in the `webreferences2`
directory and reference the WSDL file in a B2C Commerce Script. You then request the service [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)
using one of the get service methods. For example, if your WSDL file is `MyWSDL.wsdl`,
here is how you create an instance of WebReference2 and access the [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md):



```
var webref : WebReference2 = webreferences2.MyWSDL;
var port : Port = webref.getDefaultService();
```


Note that all script classes representing your WSDL file are placed in the `webreferences2`
package. To use classes in the `webreferences2` package, you do not need to use the `importPackage`
statement in your B2C Commerce Script file.



The generated API may be customized via a property file named `<WSDLFile>.properties`.
For example, if your WSDL file is `MyWSDL.wsdl`, the property file name is `MyWSDL.wsdl.properties`.
Supported properties include:

| Name | Type | Description |
| --- |--- |--- |
| `namespace` | `boolean` | If the WSDL contains different types with the same name a compilation error may occur. Set this to `true` to      generate a namespace-aware [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md), which will have classes separated into packages based on their associated namespace.      The default value is `false` |
| `underscoreBinding` | `string` | If you have elements in a WSDL schema that contain the underscore character, code generation may fail. Set this property      to `asCharInWord` to resolve the problem. The default value is `asWordSeparator`. |
| `collectionType` | `string` | The generated API will use array types instead of List types for collections when this value is set to      `indexed`. This results in code that is more compatible with older `webreferences`-based      implementations. The default behavior is to generate Lists. |
| `enableWrapperStyle` | `boolean` | The generated API will use "bare" methods when this is `false`. When this is `true`,      "wrapped" methods may be generated instead. The default value is `true`, but a `false`      value is more  compatible with older `webreferences`-based implementations. |


The messages sent to and from the remote server are logged at DEBUG level on sandboxes, and not logged at all on production.
The custom log category used is derived from the WSDL name and message type. For example, the custom log categories for the file
`MyWSDL.wsdl` are `webreferences2.MyWSDL.request` and `webreferences2.MyWSDL.response`. This
logging is controlled by the following in the WSDL properties:

| Name | Type | Description |
| --- |--- |--- |
| `logging.enabled` | `boolean` | `true` to explicitly allow logging, `false` to disallow. Default is `true` on Sandboxes      and `false` on all other instance types |
| `logging.level` | `string` | The logging level to use (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`).       Default is `DEBUG`. |
| `logging.pretty` | `boolean` | `true` to pretty-print the SOAP XML. Default is `false` to log the actual message body. |
| `logging.verbose` | `boolean` | `true` to log HTTP headers and other message information. Default is `false` to only log the      message body |
| `logging.filter.elements` | comma-separated `string` | List of element tag names containing sensitive information. These will be filtered out of the message. All properties with      this prefix will be used. For example `logging.filter.elements=Password,Token` is equivalent to two different properties      `logging.filter.elements.01=Token` and `logging.filter.elements.02=Token` |
| `logging.filter.headers` | comma-separated `string` | List of message header names containing sensitive information. These will be filtered out of the message. All properties with      this prefix will be used. For example `logging.filter.headers=Authorization,Token` is equivalent to two different properties      `logging.filter.headers.01=Authorization` and `logging.filter.headers.02=Token` |


**See Also:**
- [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)
- [WebReference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.WebReference.md)


## Property Summary

| Property | Description |
| --- | --- |
| [defaultService](#defaultservice): [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md) `(read-only)` | Returns the default service endpoint interface port of the web reference. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WebReference2](#webreference2)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| [getDefaultService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md#getdefaultservice)() | Returns the default service endpoint interface port of the web reference. |
| [getService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md#getservicestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a specific service from this web reference. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### defaultService
- defaultService: [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md) `(read-only)`
  - : Returns the default service endpoint interface port of the web reference. The default service is
      determined as the first service based on the alphabetic order of the service name, and within
      the service the first SOAP port based on the alphabetic order of the port name.



---

## Constructor Details

### WebReference2()
- WebReference2()
  - : 


---

## Method Details

### getDefaultService()
- getDefaultService(): [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)
  - : Returns the default service endpoint interface port of the web reference. The default service is
      determined as the first service based on the alphabetic order of the service name, and within
      the service the first SOAP port based on the alphabetic order of the port name.


    **Returns:**
    - the default service of the web reference.


---

### getService(String, String)
- getService(service: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), portName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)
  - : Returns a specific service from this web reference.

    **Parameters:**
    - service - the service to locate.
    - portName - the name of the port to use.

    **Returns:**
    - a specific service from this web reference.


---

<!-- prettier-ignore-end -->

<!-- document id=c8eba3df2c8faab32052d0d28aa6428d0ef8583fc57c0c0d427df10c295a4ac2 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.Writer.md -->

<!-- prettier-ignore-start -->
# Class Writer

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)

The class supports writing characters to a stream.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



## All Known Subclasses
[FileWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md), [PrintWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md), [StringWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.StringWriter.md)
## Constructor Summary

| Constructor | Description |
| --- | --- |
| [Writer](#writeroutputstream)([OutputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.OutputStream.md)) | Create a writer from a stream using UTF-8 character encoding. |
| [Writer](#writeroutputstream-string)([OutputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.OutputStream.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Create a writer from a stream using the specified character encoding. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#close)() | Closes the writer. |
| [flush](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#flush)() | Flushes the buffer. |
| [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Write the given string to the stream. |
| [write](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md#writestring-number-number)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Write the given string to the stream. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### Writer(OutputStream)
- Writer(stream: [OutputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.OutputStream.md))
  - : Create a writer from a stream using UTF-8 character encoding.

    **Parameters:**
    - stream - the output stream to use when creating the writer.


---

### Writer(OutputStream, String)
- Writer(stream: [OutputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.OutputStream.md), encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md))
  - : Create a writer from a stream using the specified character encoding.

    **Parameters:**
    - stream - the output stream to use when creating the writer.
    - encoding - the encoding to use when creating the writer.


---

## Method Details

### close()
- close(): void
  - : Closes the writer.


---

### flush()
- flush(): void
  - : Flushes the buffer.


---

### write(String)
- write(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Write the given string to the stream.

    **Parameters:**
    - str - the string to write to the stream.


---

### write(String, Number, Number)
- write(str: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), off: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), len: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): void
  - : Write the given string to the stream.

    **Parameters:**
    - str - the string to write to the stream.
    - off - the offset from which to start writing characters to the stream.
    - len - the number of characters to write from the stream.


---

<!-- prettier-ignore-end -->

<!-- document id=5faef153557453ade45601fc98203db7f4e4490b78d99a1f9b6c69b1df72ed44 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.ws.WSUtil.md -->

<!-- prettier-ignore-start -->
# Class WSUtil

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.ws.WSUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md)

A utility class for performing SOAP-based operations for Web Services
for use with [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md). This class provides
methods for setting SOAP headers and a set of constants representing the
well-known supported header names. You also use this class to set connection and request
timeout values for Web Service calls.


**See Also:**
- [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
- [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


## Constant Summary

| Constant | Description |
| --- | --- |
| [KEY_ID_TYPE_DIRECT_REFERENCE](#key_id_type_direct_reference): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DirectReference" | This key identifier method is used when the X.509 Certificate is included in the message. |
| [KEY_ID_TYPE_ENC_KEY_SHA1](#key_id_type_enc_key_sha1): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "EncryptedKeySHA1" | This Key Identifier method only applies for Encryption. |
| [KEY_ID_TYPE_ISSUE_SERIAL](#key_id_type_issue_serial): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IssuerSerial" | This key identifier method means that the Issuer Name and Serial Number of a X.509  Certificate is included directly in the KeyInfo Element. |
| [KEY_ID_TYPE_SKI_IDENTIFIER](#key_id_type_ski_identifier): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SKIKeyIdentifier" | This Key Identifier method refers to a Certificate via a Base-64 encoding of the  Subject Key Identifier. |
| [KEY_ID_TYPE_THUMBPRINT](#key_id_type_thumbprint): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Thumbprint" | This Key Identifier method refers to the Certificate via a SHA-1 Thumbprint. |
| [KEY_ID_TYPE_X509_KEY_IDENTIFIER](#key_id_type_x509_key_identifier): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X509KeyIdentifier" | This key identifier method is similar to KEY\_ID\_TYPE\_DIRECT\_REFERENCE, in that the certificate is  included in the request. |
| [WS_ACTION](#ws_action): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "action" | WS-Security action property name. |
| [WS_ENCRYPT](#ws_encrypt): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Encrypt" | WS-Security action: Encrypt the message. |
| [WS_ENCRYPTION_PARTS](#ws_encryption_parts): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionParts" | WS-Security Encryption: Defines which parts of the request shall be encrypted. |
| [WS_ENCRYPTION_USER](#ws_encryption_user): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionUser" | WS-Security Encryption: The user's name for encryption. |
| [WS_ENC_KEY_ID](#ws_enc_key_id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionKeyIdentifier" | Defines which key identifier type to use for encryption. |
| [WS_ENC_PROP_KEYSTORE_ALIAS](#ws_enc_prop_keystore_alias): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreAlias" | WS-Security Encryption: The encryption and decryption keystore alias name |
| [WS_ENC_PROP_KEYSTORE_PW](#ws_enc_prop_keystore_pw): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystorePassword" | WS-Security Encryption: The encryption and decryption keystore password |
| [WS_ENC_PROP_KEYSTORE_TYPE](#ws_enc_prop_keystore_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreType" | WS-Security Encryption: The signature keystore type ( jks, pkcs12, or managed ). |
| [WS_NO_SECURITY](#ws_no_security): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NoSecurity" | WS-Security action: No security. |
| [WS_PASSWORD_TYPE](#ws_password_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "passwordType" | WS-Security password type: Parameter for UsernameToken action to define the encoding  of the password. |
| [WS_PW_DIGEST](#ws_pw_digest): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordDigest" | WS-Security password type "digest": Use a password digest to send the password information. |
| [WS_PW_TEXT](#ws_pw_text): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordText" | WS-Security password type "text": Send the password information in clear. |
| [WS_SECRETS_MAP](#ws_secrets_map): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SecretsMap" | A secrets map with the username and password entries needed to create the password  callback object. |
| [WS_SIGNATURE](#ws_signature): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Signature" | WS-Security action: Sign the message. |
| [WS_SIGNATURE_PARTS](#ws_signature_parts): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureParts" | WS-Security Signature: Defines which parts of the request shall be signed. |
| [WS_SIGNATURE_USER](#ws_signature_user): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureUser" | WS-Security Signature: The user's name for signature. |
| [WS_SIG_DIGEST_ALGO](#ws_sig_digest_algo): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureDigestAlgorithm" | WS-Security Signature: Defines which signature digest algorithm to use. |
| [WS_SIG_KEY_ID](#ws_sig_key_id): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureKeyIdentifier" | Defines which key identifier type to use for signature. |
| [WS_SIG_PROP_KEYSTORE_ALIAS](#ws_sig_prop_keystore_alias): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreAlias" | WS-Security Signature: The signature keystore alias name. |
| [WS_SIG_PROP_KEYSTORE_PW](#ws_sig_prop_keystore_pw): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystorePassword" | WS-Security Signature: The signature keystore password. |
| [WS_SIG_PROP_KEYSTORE_TYPE](#ws_sig_prop_keystore_type): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreType" | WS-Security: The signature keystore type ( jks, pkcs12, or managed ). |
| [WS_TIMESTAMP](#ws_timestamp): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Timestamp" | WS-Security action: Add a timestamp to the security header. |
| [WS_USER](#ws_user): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "user" | WS-Security user name. |
| [WS_USERNAME_TOKEN](#ws_username_token): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UsernameToken" | WS-Security action: Add a UsernameToken identification. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [WSUtil](#wsutil)() |  |

## Method Summary

| Method | Description |
| --- | --- |
| static [addSOAPHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#addsoapheaderobject-object-boolean-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a header element to the SOAP Header. |
| static [addSOAPHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#addsoapheaderobject-string-boolean-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Adds a header element to the SOAP Header. |
| static [clearSOAPHeaders](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#clearsoapheadersobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Removes all SOAP header elements from the port's request context. |
| static [createHolder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#createholderobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates an jakarta.xml.ws.Holder instance that wraps the specified element. |
| static [getConnectionTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#getconnectiontimeoutobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the connection timeout value for the port. |
| static [getHTTPRequestHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#gethttprequestheaderobject-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an HTTP request header property value using the specified key. |
| static [getProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#getpropertystring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the value of the SOAP request property using the specified key on a port  returned from one of the WebReference2 getService methods. |
| static [getRequestTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#getrequesttimeoutobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the read timeout value for a request made on the specified port. |
| static [getResponseProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#getresponsepropertystring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the property value using the specified key and on a port returned from one of  the WebReference2 getService methods. |
| static [isAllowChunking](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#isallowchunkingobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns true if the HTTP request may be chunked, false otherwise |
| static [setAllowChunking](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setallowchunkingobject-boolean)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)) | Indicate that HTTP chunked Transfer-Encoding may be used. |
| static [setConnectionTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setconnectiontimeoutnumber-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the connection timeout for the port. |
| static [setHTTPRequestHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#sethttprequestheaderobject-string-string)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets an HTTP request header property using the specified key and value. |
| static [setProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setpropertystring-object-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Set the SOAP request property using the specified key and value on a port  returned from one of the WebReference2 getService() methods. |
| static [setRequestTimeout](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setrequesttimeoutnumber-object)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Sets the read timeout value for a request made on the specified port. |
| static [setUserNamePassword](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setusernamepasswordstring-string-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Set the user name and password to use with Basic authentication. |
| static [setWSSecurityConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setwssecurityconfigobject-object-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Set the WS-Security configuration for the request and response based on the  constants defined (see above). |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### KEY_ID_TYPE_DIRECT_REFERENCE

- KEY_ID_TYPE_DIRECT_REFERENCE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "DirectReference"
  - : This key identifier method is used when the X.509 Certificate is included in the message.
      The certificate is Base-64 encoded and included in the request via a BinarySecurityToken element


    **See Also:**
    - [WS_ENC_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_enc_key_id)
    - [WS_SIG_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_sig_key_id)


---

### KEY_ID_TYPE_ENC_KEY_SHA1

- KEY_ID_TYPE_ENC_KEY_SHA1: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "EncryptedKeySHA1"
  - : This Key Identifier method only applies for Encryption. Unlike the previous methods
      it refers to the way the EncryptedData references the EncryptedKey Element,
      rather than the way the EncryptedKey Element refers to the public key.


    **See Also:**
    - [WS_ENC_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_enc_key_id)


---

### KEY_ID_TYPE_ISSUE_SERIAL

- KEY_ID_TYPE_ISSUE_SERIAL: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "IssuerSerial"
  - : This key identifier method means that the Issuer Name and Serial Number of a X.509
      Certificate is included directly in the KeyInfo Element.


    **See Also:**
    - [WS_ENC_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_enc_key_id)
    - [WS_SIG_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_sig_key_id)


---

### KEY_ID_TYPE_SKI_IDENTIFIER

- KEY_ID_TYPE_SKI_IDENTIFIER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "SKIKeyIdentifier"
  - : This Key Identifier method refers to a Certificate via a Base-64 encoding of the
      Subject Key Identifier.


    **See Also:**
    - [WS_ENC_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_enc_key_id)
    - [WS_SIG_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_sig_key_id)


---

### KEY_ID_TYPE_THUMBPRINT

- KEY_ID_TYPE_THUMBPRINT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Thumbprint"
  - : This Key Identifier method refers to the Certificate via a SHA-1 Thumbprint.
      The certificate may or may not be included in the request.


    **See Also:**
    - [WS_ENC_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_enc_key_id)
    - [WS_SIG_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_sig_key_id)


---

### KEY_ID_TYPE_X509_KEY_IDENTIFIER

- KEY_ID_TYPE_X509_KEY_IDENTIFIER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "X509KeyIdentifier"
  - : This key identifier method is similar to KEY\_ID\_TYPE\_DIRECT\_REFERENCE, in that the certificate is
      included in the request. However, instead of referring to a certificate, the certificate is
      included directly in the KeyInfo element.


    **See Also:**
    - [WS_ENC_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_enc_key_id)
    - [WS_SIG_KEY_ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#ws_sig_key_id)


---

### WS_ACTION

- WS_ACTION: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "action"
  - : WS-Security action property name.
      Allowed property values are WS\_NO\_SECURITY, WS\_TIMESTAMP, WS\_ENCRYPT,
      WS\_SIGNATURE, WS\_USERNAME\_TOKEN or a space separated list of these values.



---

### WS_ENCRYPT

- WS_ENCRYPT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Encrypt"
  - : WS-Security action: Encrypt the message.
      The encryption specific parameters define how to encrypt.



---

### WS_ENCRYPTION_PARTS

- WS_ENCRYPTION_PARTS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionParts"
  - : WS-Security Encryption: Defines which parts of the request shall be encrypted.


---

### WS_ENCRYPTION_USER

- WS_ENCRYPTION_USER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionUser"
  - : WS-Security Encryption: The user's name for encryption.


---

### WS_ENC_KEY_ID

- WS_ENC_KEY_ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "encryptionKeyIdentifier"
  - : Defines which key identifier type to use for encryption. Permissible
      values are:
      
      - `KEY_ID_TYPE_ISSUE_SERIAL`(default value)
      - `KEY_ID_TYPE_DIRECT_REFERENCE`
      - `KEY_ID_TYPE_X509_KEY_IDENTIFIER`
      - `KEY_ID_TYPE_THUMBPRINT`
      - `KEY_ID_TYPE_SKI_IDENTIFIER`
      - `KEY_ID_TYPE_ENC_KEY_SHA1`


    **See Also:**
    - [KEY_ID_TYPE_ISSUE_SERIAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_issue_serial)
    - [KEY_ID_TYPE_DIRECT_REFERENCE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_direct_reference)
    - [KEY_ID_TYPE_X509_KEY_IDENTIFIER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_x509_key_identifier)
    - [KEY_ID_TYPE_THUMBPRINT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_thumbprint)
    - [KEY_ID_TYPE_SKI_IDENTIFIER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_ski_identifier)
    - [KEY_ID_TYPE_ENC_KEY_SHA1](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_enc_key_sha1)


---

### WS_ENC_PROP_KEYSTORE_ALIAS

- WS_ENC_PROP_KEYSTORE_ALIAS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreAlias"
  - : WS-Security Encryption: The encryption and decryption keystore alias name


---

### WS_ENC_PROP_KEYSTORE_PW

- WS_ENC_PROP_KEYSTORE_PW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystorePassword"
  - : WS-Security Encryption: The encryption and decryption keystore password


---

### WS_ENC_PROP_KEYSTORE_TYPE

- WS_ENC_PROP_KEYSTORE_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__EncryptionPropKeystoreType"
  - : WS-Security Encryption: The signature keystore type ( jks, pkcs12, or managed ).
      
      
      The default is jks.
      
      
      The "managed" type will resolve aliases against the names of certificates and keys in Business Manager.
      
      
      Note: For non-managed types, the keystore file has the basename of the WSDL file and the
      file extension based on the keystore type (e.g. MyService.jks).
      The keystore file has to be placed in the same cartridge directory
      as the WSDL file.



---

### WS_NO_SECURITY

- WS_NO_SECURITY: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "NoSecurity"
  - : WS-Security action: No security.


---

### WS_PASSWORD_TYPE

- WS_PASSWORD_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "passwordType"
  - : WS-Security password type: Parameter for UsernameToken action to define the encoding
      of the password. Allowed values are PW\_DIGEST or PW\_TEXT.



---

### WS_PW_DIGEST

- WS_PW_DIGEST: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordDigest"
  - : WS-Security password type "digest": Use a password digest to send the password information.


---

### WS_PW_TEXT

- WS_PW_TEXT: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "PasswordText"
  - : WS-Security password type "text": Send the password information in clear.


---

### WS_SECRETS_MAP

- WS_SECRETS_MAP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SecretsMap"
  - : A secrets map with the username and password entries needed to create the password
      callback object.



---

### WS_SIGNATURE

- WS_SIGNATURE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Signature"
  - : WS-Security action: Sign the message.
      The signature specific parameters define how to sign and which keys
      to use.



---

### WS_SIGNATURE_PARTS

- WS_SIGNATURE_PARTS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureParts"
  - : WS-Security Signature: Defines which parts of the request shall be signed.


---

### WS_SIGNATURE_USER

- WS_SIGNATURE_USER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureUser"
  - : WS-Security Signature: The user's name for signature.


---

### WS_SIG_DIGEST_ALGO

- WS_SIG_DIGEST_ALGO: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureDigestAlgorithm"
  - : WS-Security Signature: Defines which signature digest algorithm to use.


---

### WS_SIG_KEY_ID

- WS_SIG_KEY_ID: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "signatureKeyIdentifier"
  - : Defines which key identifier type to use for signature.
      
      Permissible values are:
      
      - `KEY_ID_TYPE_ISSUE_SERIAL`
      - `KEY_ID_TYPE_DIRECT_REFERENCE`(default value)
      - `KEY_ID_TYPE_X509_KEY_ID_IDENTIFIER`
      - `KEY_ID_TYPE_THUMBPRINT`
      - `KEY_ID_TYPE_SKI_IDENTIFIER`


    **See Also:**
    - [KEY_ID_TYPE_ISSUE_SERIAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_issue_serial)
    - [KEY_ID_TYPE_DIRECT_REFERENCE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_direct_reference)
    - [KEY_ID_TYPE_X509_KEY_IDENTIFIER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_x509_key_identifier)
    - [KEY_ID_TYPE_THUMBPRINT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_thumbprint)
    - [KEY_ID_TYPE_SKI_IDENTIFIER](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#key_id_type_ski_identifier)


---

### WS_SIG_PROP_KEYSTORE_ALIAS

- WS_SIG_PROP_KEYSTORE_ALIAS: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreAlias"
  - : WS-Security Signature: The signature keystore alias name.


---

### WS_SIG_PROP_KEYSTORE_PW

- WS_SIG_PROP_KEYSTORE_PW: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystorePassword"
  - : WS-Security Signature: The signature keystore password.


---

### WS_SIG_PROP_KEYSTORE_TYPE

- WS_SIG_PROP_KEYSTORE_TYPE: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "__SignaturePropKeystoreType"
  - : WS-Security: The signature keystore type ( jks, pkcs12, or managed ).
      
      
      The default is jks.
      
      
      The "managed" type will resolve aliases against the names of certificates and keys in Business Manager.
      
      
      Note: For non-managed types, the keystore file has the basename of the WSDL file and the
      file extension based on the keystore type (e.g. MyService.jks).
      The keystore file has to be placed in the same cartridge directory
      as the WSDL file.



---

### WS_TIMESTAMP

- WS_TIMESTAMP: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "Timestamp"
  - : WS-Security action: Add a timestamp to the security header.


---

### WS_USER

- WS_USER: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "user"
  - : WS-Security user name.


---

### WS_USERNAME_TOKEN

- WS_USERNAME_TOKEN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) = "UsernameToken"
  - : WS-Security action: Add a UsernameToken identification.


---

## Constructor Details

### WSUtil()
- WSUtil()
  - : 


---

## Method Details

### addSOAPHeader(Object, Object, Boolean, String)
- static addSOAPHeader(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), xml: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), mustUnderstand: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), actor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a header element to the SOAP Header. Each header element should be XML and
      it should typically contain a namespace URI.


    **Parameters:**
    - port - the port.
    - xml - the header element XML. The XML should contain a namespace URI.
    - mustUnderstand - directs target endpoint to validate payload.
    - actor - an URI that identifies that intended recipient of this header element.


---

### addSOAPHeader(Object, String, Boolean, String)
- static addSOAPHeader(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), xml: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), mustUnderstand: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md), actor: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Adds a header element to the SOAP Header. Each header element should be XML and
      it should typically contain a namespace URI.


    **Parameters:**
    - port - the port.
    - xml - the header element XML as a String. The XML should contain a namespace URI.
    - mustUnderstand - directs target endpoint to validate payload.
    - actor - an URI that identifies that intended recipient of this header element.


---

### clearSOAPHeaders(Object)
- static clearSOAPHeaders(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Removes all SOAP header elements from the port's request context.

    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### createHolder(Object)
- static createHolder(element: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Creates an jakarta.xml.ws.Holder instance that wraps the specified element. When a WSDL operation is
      defined to have an input and output message using the same type, the operation may require the operation's
      object to be wrapped in a holder.


    **Parameters:**
    - element - the element to be wrapped in the Holder.

    **Returns:**
    - the holder.


---

### getConnectionTimeout(Object)
- static getConnectionTimeout(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the connection timeout value for the port.

    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.

    **Returns:**
    - the connection timeout value.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### getHTTPRequestHeader(Object, String)
- static getHTTPRequestHeader(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an HTTP request header property value using the specified key. Null is returned
      if the key does not represent an HTTP header property.


    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.
    - key - the header property key.

    **Returns:**
    - an HTTP request header property value using the specified key or null.


---

### getProperty(String, Object)
- static getProperty(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the value of the SOAP request property using the specified key on a port
      returned from one of the WebReference2 getService methods. The property
      keys are defined as constants in [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md).


    **Parameters:**
    - key - the key to use.
    - port - the port on which the property is set.

    **Returns:**
    - the property using the specified key and port.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### getRequestTimeout(Object)
- static getRequestTimeout(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the read timeout value for a request made on the specified port.
      If the request exceeds the timeout value, an error is thrown.


    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.

    **Returns:**
    - the request timeout value for the port.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### getResponseProperty(String, Object)
- static getResponseProperty(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the property value using the specified key and on a port returned from one of
      the WebReference2 getService methods.


    **Parameters:**
    - key - the key to use.
    - port - the port on which the property is set

    **Returns:**
    - the property using the specified key and port.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### isAllowChunking(Object)
- static isAllowChunking(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if the HTTP request may be chunked, false otherwise

    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.

    **Returns:**
    - returns true if the HTTP request may be chunked and false otherwise


---

### setAllowChunking(Object, Boolean)
- static setAllowChunking(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), allow: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)): void
  - : Indicate that HTTP chunked Transfer-Encoding may be used.
      
      
      The default behavior is true. If false then the request will not
      be chunked and the Content-Length will always be sent.


    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.
    - allow - true to enable chunking, false otherwise


---

### setConnectionTimeout(Number, Object)
- static setConnectionTimeout(timeoutInMilliseconds: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the connection timeout for the port.

    **Parameters:**
    - timeoutInMilliseconds - the connection timeout.
    - port - a port returned from one of the WebReference2 getService methods.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### setHTTPRequestHeader(Object, String, String)
- static setHTTPRequestHeader(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets an HTTP request header property using the specified key and value.

    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.
    - key - the header property key.
    - value - the header property value. If the value is null, the property  identified by the key is removed from the HTTP request header.


---

### setProperty(String, Object, Object)
- static setProperty(key: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Set the SOAP request property using the specified key and value on a port
      returned from one of the WebReference2 getService() methods. The property
      keys are defined as constants in [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md).


    **Parameters:**
    - key - the key to use.
    - value - the value.
    - port - the port on which the property is set.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### setRequestTimeout(Number, Object)
- static setRequestTimeout(timeoutInMilliseconds: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Sets the read timeout value for a request made on the specified port.
      If the request exceeds the timeout value, an error is thrown.


    **Parameters:**
    - timeoutInMilliseconds - the timeout.
    - port - a port returned from one of the WebReference2 getService methods.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### setUserNamePassword(String, String, Object)
- static setUserNamePassword(userName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), password: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Set the user name and password to use with Basic authentication. For stronger
      authentication, use the [setWSSecurityConfig(Object, Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setwssecurityconfigobject-object-object) method.


    **Parameters:**
    - userName - the user name.
    - password - the password.
    - port - a port returned from one of the WebReference2 getService methods.

    **See Also:**
    - [setWSSecurityConfig(Object, Object, Object)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md#setwssecurityconfigobject-object-object)
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

### setWSSecurityConfig(Object, Object, Object)
- static setWSSecurityConfig(port: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), requestConfigMap: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), responseConfigMap: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Set the WS-Security configuration for the request and response based on the
      constants defined (see above).


    **Parameters:**
    - port - a port returned from one of the WebReference2 getService methods.
    - requestConfigMap - the WS-Security request configuration.
    - responseConfigMap - the WS-Security response configuration.

    **See Also:**
    - [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md)
    - [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)


---

<!-- prettier-ignore-end -->

<!-- document id=13c7695e7ab0a26e5557e59ce15b33d76dd48839541cde0e683109154e710053 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.X509Certificate.md -->

<!-- prettier-ignore-start -->
# Class X509Certificate

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.crypto.CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)
    - [dw.crypto.X509Certificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md)

Represents an X.509 public key certificate as defined in RFC 5280.


It provides access to the standard fields of an X.509 certificate including version, serial number, validity period,
distinguished names, and signature algorithm.



## Property Summary

| Property | Description |
| --- | --- |
| [issuerDN](#issuerdn): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the X.500 distinguished name of the entity that signed this certificate. |
| [notAfter](#notafter): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the end date of the certificate validity period. |
| [notBefore](#notbefore): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)` | Returns the start date of the certificate validity period. |
| [serialNumber](#serialnumber): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the certificate serial number in string format. |
| [sigAlgName](#sigalgname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the algorithm used to sign this certificate. |
| [subjectDN](#subjectdn): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the X.500 distinguished name of the entity this certificate belongs to. |
| [version](#version): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the X.509 certificate version number. |

## Constructor Summary

This class does not have a constructor, so you cannot create it directly.
## Method Summary

| Method | Description |
| --- | --- |
| [getIssuerDN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md#getissuerdn)() | Returns the X.500 distinguished name of the entity that signed this certificate. |
| [getNotAfter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md#getnotafter)() | Returns the end date of the certificate validity period. |
| [getNotBefore](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md#getnotbefore)() | Returns the start date of the certificate validity period. |
| [getSerialNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md#getserialnumber)() | Returns the certificate serial number in string format. |
| [getSigAlgName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md#getsigalgname)() | Returns the algorithm used to sign this certificate. |
| [getSubjectDN](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md#getsubjectdn)() | Returns the X.500 distinguished name of the entity this certificate belongs to. |
| [getVersion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md#getversion)() | Returns the X.509 certificate version number. |

### Methods inherited from class CertificateRef

[toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### issuerDN
- issuerDN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the X.500 distinguished name of the entity that signed this certificate.


---

### notAfter
- notAfter: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the end date of the certificate validity period.


---

### notBefore
- notBefore: [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md) `(read-only)`
  - : Returns the start date of the certificate validity period.


---

### serialNumber
- serialNumber: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the certificate serial number in string format. The serial number is a unique positive integer assigned
      by the CA to each certificate.



---

### sigAlgName
- sigAlgName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the algorithm used to sign this certificate. The name follows the format defined in RFC 5280 (e.g.,
      "SHA256withRSA", "SHA384withECDSA").



---

### subjectDN
- subjectDN: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the X.500 distinguished name of the entity this certificate belongs to.


---

### version
- version: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the X.509 certificate version number.


---

## Method Details

### getIssuerDN()
- getIssuerDN(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the X.500 distinguished name of the entity that signed this certificate.

    **Returns:**
    - the issuer's X.500 distinguished name


---

### getNotAfter()
- getNotAfter(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the end date of the certificate validity period.

    **Returns:**
    - the date after which this certificate is not valid


---

### getNotBefore()
- getNotBefore(): [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)
  - : Returns the start date of the certificate validity period.

    **Returns:**
    - the date before which this certificate is not valid


---

### getSerialNumber()
- getSerialNumber(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the certificate serial number in string format. The serial number is a unique positive integer assigned
      by the CA to each certificate.


    **Returns:**
    - the certificate serial number as a string


---

### getSigAlgName()
- getSigAlgName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the algorithm used to sign this certificate. The name follows the format defined in RFC 5280 (e.g.,
      "SHA256withRSA", "SHA384withECDSA").


    **Returns:**
    - the signature algorithm name


---

### getSubjectDN()
- getSubjectDN(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the X.500 distinguished name of the entity this certificate belongs to.

    **Returns:**
    - the subject's X.500 distinguished name


---

### getVersion()
- getVersion(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the X.509 certificate version number.

    **Returns:**
    - certificate version (typically 1, 2, or 3)


---

<!-- prettier-ignore-end -->

<!-- document id=119982ce53f188153ac3e0d70845553f6a569ff335bbfdd1a30bafb6c44c9440 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.XML.md -->

<!-- prettier-ignore-start -->
# Class XML

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)

The XML object contains functions and properties for working with XML
instances. The XML object implements the powerful XML-handling standards
defined in the ECMA-357 specification (known as "E4X").


Use the toXMLString() method to return a string representation of the XML
object regardless of whether the XML object has simple content or complex
content.


Do not create large XML objects in memory to avoid out-of-memory conditions.
When dealing with XML streams use [XMLStreamReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md) and
[XMLStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md). The following example shows how:


```
var id : String = "p42";
var pname : String = "a product";

// use E4X syntax
var product : XML =
  <product id={id}>
    <name>{pname}</name>
    <shortdesc></shortdesc>
  </product>;

product.shortdesc = "a fine product";
product.longdesc = "this is a fine product";

var xmlString = product.toXMLString();

fileWriter.write(xmlString);
```





The code above will write the following to file:


```
<product id="p42">
  <name>a product</name>
  <shortdesc>a fine product</shortdesc>
  <longdesc>this is a fine product</longdesc>
</product>
```





Do not create large XML objects in memory to avoid out-of-memory conditions.
When dealing with XML streams use [XMLStreamReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md) and
[XMLStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md).



## Property Summary

| Property | Description |
| --- | --- |
| [ignoreComments](#ignorecomments): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | The ignoreComments property determines whether or not XML comments are  ignored when XML objects parse the source XML data. |
| [ignoreProcessingInstructions](#ignoreprocessinginstructions): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | The ignoreProcessingInstructions property determines whether or not XML  processing instructions are ignored when XML objects parse the source XML data. |
| [ignoreWhitespace](#ignorewhitespace): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | The ignoreWhitespace property determines whether or not white space  characters at the beginning and end of text nodes are ignored during parsing. |
| [prettyIndent](#prettyindent): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The prettyIndent property determines the amount of indentation applied by  the toString() and toXMLString() methods when the XML.prettyPrinting  property is set to true. |
| [prettyPrinting](#prettyprinting): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) | The prettyPrinting property determines whether the toString() and toXMLString()  methods normalize white space characters between some tags. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [XML](#xml)() | Creates a new XML object. |
| [XML](#xmlobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a new XML object. |

## Method Summary

| Method | Description |
| --- | --- |
| [addNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#addnamespaceobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Adds a namespace to the set of in-scope namespaces for the XML object. |
| [appendChild](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#appendchildobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Appends the specified child to the end of the object's properties. |
| [attribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#attributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the attribute associated with this XML object that  is identified by the specified name. |
| [attributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#attributes)() | Returns an XMList of the attributes in this XML Object. |
| [child](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#childobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the children of the XML object based on the specified  property name. |
| [childIndex](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#childindex)() | Identifies the zero-based index of this XML object within  the context of its parent, or -1 if this object has no parent. |
| [children](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#children)() | Returns an XMLList containing the children of this XML object, maintaing  the sequence in which they appear. |
| [comments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#comments)() | Returns the properties of the XML object that contain comments. |
| [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#containsxml)([XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)) | Returns true if this XML object contains the specified  XML object, false otherwise. |
| [copy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#copy)() | Returns a copy of the this XML object including  duplicate copies of the entire tree of nodes. |
| static [defaultSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#defaultsettings)() | Returns a new Object with the following properties set to the default values:  ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyIndent,  and prettyPrinting. |
| [descendants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#descendants)() | Returns all descendents of the XML object. |
| [descendants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#descendantsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns all descendents of the XML object that  have the specified name parameter. |
| [elements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#elements)() | Returns a list of all of the elements of the XML object. |
| [elements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#elementsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns a list of the elements of the XML object using the  specified name to constrain the list. |
| [hasComplexContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#hascomplexcontent)() | Returns a Boolean value indicating whether  this XML object contains complex content. |
| [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#hasownpropertystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a Boolean value indicating whether this object has the  property specified by _prop_. |
| [hasSimpleContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#hassimplecontent)() | Returns a Boolean value indicating whether this XML object contains  simple content. |
| [inScopeNamespaces](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#inscopenamespaces)() | Returns an Array of Namespace objects representing the namespaces  in scope for this XML object in the context of its parent. |
| [insertChildAfter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#insertchildafterobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Inserts the specified _child2_ after the specified _child1_  in this XML object and returns this XML object. |
| [insertChildBefore](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#insertchildbeforeobject-object)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Inserts the specified _child2_ before the specified _child1_  in this XML object and returns this XML object. |
| [length](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#length)() | Returns a value of 1 for XML objects. |
| [localName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#localname)() | Returns the local name portion of the qualified name of the XML object. |
| [name](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#name)() | Returns the qualified name for the XML object. |
| [namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#namespace)() | Returns the namespace associated with the qualified name  of this XML object. |
| [namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#namespacestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the namespace that matches the specified prefix and  that is in scope for the XML object. |
| [namespaceDeclarations](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#namespacedeclarations)() | Returns an Array of namespace declarations associated  with the XML Obnject in the context of its parent. |
| [nodeKind](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#nodekind)() | Returns the type of the XML object, such  as _text_, _comment_, _processing-instruction_,  or _attribute_. |
| [normalize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#normalize)() | Merges adjacent text nodes and eliminates and eliminates  empty text nodes for this XML object and all its  descendents. |
| [parent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#parent)() | Returns the parent of the XML object  or null if the XML object does not have  a parent. |
| [prependChild](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#prependchildobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Inserts the specified child into this XML object  prior to its existing XML properties and then returns  this XML object. |
| [processingInstructions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#processinginstructions)() | Returns an XMLList containing all the children of this XML object  that are processing-instructions. |
| [processingInstructions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#processinginstructionsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns an XMLList containing all the children of this XML object  that are processing-instructions with the specified _name_. |
| [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#propertyisenumerablestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a Boolean indicating whether the specified  _property_ will be included in the set of properties iterated  over when this XML object is used in a _for..in_ statement. |
| [removeNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#removenamespacenamespace)([Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md)) | Removes the specified namespace from the in scope namespaces  of this object and all its descendents, then returns a copy of  this XML object. |
| [replace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#replacestring-object)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Replaces the XML properties of this XML object specified by  _propertyName_ with _value_ and returns this  updated XML object. |
| [setChildren](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#setchildrenobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Replaces the XML properties of this XML object  with a new set of XML properties from _value_. |
| [setLocalName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#setlocalnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Replaces the local name of this XML object with  a string constructed from the specified _name_. |
| [setName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#setnamestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Replaces the name of this XML object with a  QName or AttributeName constructed from the specified  _name_. |
| [setNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#setnamespacenamespace)([Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md)) | Replaces the namespace associated with the name of  this XML object with the specified _namespace_. |
| static [setSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#setsettings)() | Restores the default settings for the following XML  properties:  <ul>  <li>XML.ignoreComments = true</li>  <li>XML.ignoreProcessingInstructions = true</li>  <li>XML.ignoreWhitespace = true</li>  <li>XML.prettyIndent = 2</li>  <li>XML.prettyPrinting = true</li>  </ul> |
| static [setSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#setsettingsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Updates the collection of global XML properties:  ignoreComments, ignoreProcessingInstructions, ignoreWhitespace,  prettyPrinting, prettyIndent, and prettyPrinting. |
| static [settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#settings)() | Returns the collection of global XML properties:  ignoreComments, ignoreProcessingInstructions, ignoreWhitespace,  prettyPrinting, prettyIndent, and prettyPrinting. |
| [text](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#text)() | Returns an XMLList containing all XML properties of  this XML object that represent XML text nodes. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#tostring)() | Returns the String representation of the XML object. |
| [toXMLString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#toxmlstring)() | Returns a XML-encoded String representation of the XML object, including tag and  attributed delimiters. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md#valueof)() | Returns this XML object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### ignoreComments
- ignoreComments: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The ignoreComments property determines whether or not XML comments are
      ignored when XML objects parse the source XML data.



---

### ignoreProcessingInstructions
- ignoreProcessingInstructions: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The ignoreProcessingInstructions property determines whether or not XML
      processing instructions are ignored when XML objects parse the source XML data.



---

### ignoreWhitespace
- ignoreWhitespace: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The ignoreWhitespace property determines whether or not white space
      characters at the beginning and end of text nodes are ignored during parsing.



---

### prettyIndent
- prettyIndent: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The prettyIndent property determines the amount of indentation applied by
      the toString() and toXMLString() methods when the XML.prettyPrinting
      property is set to true.



---

### prettyPrinting
- prettyPrinting: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : The prettyPrinting property determines whether the toString() and toXMLString()
      methods normalize white space characters between some tags.



---

## Constructor Details

### XML()
- XML()
  - : Creates a new XML object.


---

### XML(Object)
- XML(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates a new XML object.
      You must use the constructor to create an XML object before you
      call any of the methods of the XML class.
      Use the toXMLString() method to return a string representation
      of the XML object regardless of whether the XML object has simple
      content or complex content.


    **Parameters:**
    - value - any Object that can be converted to XML via  the top-level XML() function.


---

## Method Details

### addNamespace(Object)
- addNamespace(ns: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Adds a namespace to the set of in-scope namespaces for the XML object.
      If the namespace already exists in the in-scope namespaces for the XML
      object, then the prefix of the existing namespace is set to _undefined_.
      If _ns_ is a Namespace instance, it is used directly.
      However, if _ns_ is a QName instance, the input parameter's URI is used
      to create a new namespace. If _ns_ is not a Namespace or QName instance,
      _ns_ is converted to a String and a namespace is created from the String.


    **Parameters:**
    - ns - the namespace to add to the XML object.

    **Returns:**
    - a new XML object, with the namespace added.


---

### appendChild(Object)
- appendChild(child: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Appends the specified child to the end of the object's properties.
      _child_ should be a XML object, an XMLList object or any other
      data type that will then be converted to a String.


    **Parameters:**
    - child - the object to append to this XML object.

    **Returns:**
    - the XML object with the child appended.


---

### attribute(String)
- attribute(attributeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns the attribute associated with this XML object that
      is identified by the specified name.


    **Parameters:**
    - attributeName - the name of the attribute.

    **Returns:**
    - the value of the attribute as either an XMLList or an empty XMLList


---

### attributes()
- attributes(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns an XMList of the attributes in this XML Object.

    **Returns:**
    - an XMList of the attributes in this XML Object.


---

### child(Object)
- child(propertyName: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns the children of the XML object based on the specified
      property name.


    **Parameters:**
    - propertyName - the property name representing the  children of this XML object.

    **Returns:**
    - an XMLList of children that match the property name
      parameter.



---

### childIndex()
- childIndex(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Identifies the zero-based index of this XML object within
      the context of its parent, or -1 if this object has no parent.


    **Returns:**
    - the index of this XML object in the context of
      its parent, or -1 if this object has no parent.



---

### children()
- children(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns an XMLList containing the children of this XML object, maintaing
      the sequence in which they appear.


    **Returns:**
    - an XMLList containing the children of this XML object.


---

### comments()
- comments(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns the properties of the XML object that contain comments.

    **Returns:**
    - properties of the XML object that contain comments.


---

### contains(XML)
- contains(value: [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this XML object contains the specified
      XML object, false otherwise.


    **Parameters:**
    - value - the object to locate in this XML object.

    **Returns:**
    - true if this XML object contains the specified
      XML object, false otherwise.



---

### copy()
- copy(): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Returns a copy of the this XML object including
      duplicate copies of the entire tree of nodes.
      The copied XML object has no parent.


    **Returns:**
    - the copy of the object.


---

### defaultSettings()
- static defaultSettings(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns a new Object with the following properties set to the default values:
      ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyIndent,
      and prettyPrinting. The default values are as follows:
      
      - ignoreComments = true
      - ignoreProcessingInstructions = true
      - ignoreWhitespace = true
      - prettyIndent = 2
      - prettyPrinting = true
      
      
      Be aware that this method does not apply the settings to an existing instance
      of an XML object. Instead, this method returns an Object containing the
      default settings.


    **Returns:**
    - an Object with properties set to the default settings.


---

### descendants()
- descendants(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns all descendents of the XML object.

    **Returns:**
    - a list of all descendents of the XML object.


---

### descendants(String)
- descendants(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns all descendents of the XML object that
      have the specified name parameter. To return all descendents,
      use \* as the _name_ parameter.


    **Parameters:**
    - name - the name of the element to match. To return all descendents,  use \* as the _name_ parameter.

    **Returns:**
    - a list of all descendents constrained by the name parameter.


---

### elements()
- elements(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns a list of all of the elements of the XML object.


---

### elements(Object)
- elements(name: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns a list of the elements of the XML object using the
      specified name to constrain the list. _name_ can be a
      QName, String, or any other data type that will be converted
      to a string prior to performing the search for elements of that
      name.
      
      To list all objects use \* for the value of _name_.


    **Parameters:**
    - name - the name of the elements to return or an  \* to return all elements.

    **Returns:**
    - a list of the elements of the XML object using the
      specified name to constrain the list.



---

### hasComplexContent()
- hasComplexContent(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean value indicating whether
      this XML object contains complex content. An XML object is considered
      to contain complex content if it represents an XML element that has
      child elements. XML objects representing attributes, comments, processing
      instructions and text nodes do not have complex content. The existence of
      attributes, comments, processing instructions and text nodes within an XML
      object is not significant in determining if it has complex content.


    **Returns:**
    - a Boolean value indicating whether this XML object contains complex content.


---

### hasOwnProperty(String)
- hasOwnProperty(prop: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean value indicating whether this object has the
      property specified by _prop_.


    **Parameters:**
    - prop - the property to locate.

    **Returns:**
    - true if the property exists, false otherwise.


---

### hasSimpleContent()
- hasSimpleContent(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean value indicating whether this XML object contains
      simple content. An XML object is considered to contain simple
      content if it represents a text node, represents an attribute node
      or if it represents an XML element that has no child elements. XML
      objects representing comments and processing instructions do not
      have simple content. The existence of attributes, comments,
      processing instructions and text nodes within an XML object is not
      significant in determining if it has simple content.


    **Returns:**
    - a Boolean value indicating whether this XML object contains
      simple content.



---

### inScopeNamespaces()
- inScopeNamespaces(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns an Array of Namespace objects representing the namespaces
      in scope for this XML object in the context of its parent. If the
      parent of this XML object is modified, the associated namespace
      declarations may change. The set of namespaces returned by this
      method may be a super set of the namespaces used by this value


    **Returns:**
    - an Array of Namespace objects representing the namespaces
      in scope for this XML object in the context of its parent.



---

### insertChildAfter(Object, Object)
- insertChildAfter(child1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), child2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Inserts the specified _child2_ after the specified _child1_
      in this XML object and returns this XML object. If _child1_ is null,
      inserts _child2_ before all children of
      this XML object. If _child1_ does not exist
      in this XML object, it returns without modifying this XML object.


    **Parameters:**
    - child1 - the child after which _child2_ is inserted.
    - child2 - the child to insert into this XML object.

    **Returns:**
    - the updated XML object.


---

### insertChildBefore(Object, Object)
- insertChildBefore(child1: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md), child2: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Inserts the specified _child2_ before the specified _child1_
      in this XML object and returns this XML object. If _child1_ is null,
      inserts _child2_ after all children of
      this XML object. If _child1_ does not exist
      in this XML object, it returns without modifying this XML object.


    **Parameters:**
    - child1 - the child before which _child2_ is inserted.
    - child2 - the child to insert into this XML object.

    **Returns:**
    - the updated XML object.


---

### length()
- length(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns a value of 1 for XML objects.

    **Returns:**
    - the value of 1.


---

### localName()
- localName(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the local name portion of the qualified name of the XML object.

    **Returns:**
    - the local name as either a String or null.


---

### name()
- name(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the qualified name for the XML object.

    **Returns:**
    - the qualified name as either a QName or null.


---

### namespace()
- namespace(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the namespace associated with the qualified name
      of this XML object.


    **Returns:**
    - the namespace associated with the qualified name
      of this XML object.



---

### namespace(String)
- namespace(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the namespace that matches the specified prefix and
      that is in scope for the XML object. if there is no such
      namespace, the method returns undefined.


    **Parameters:**
    - prefix - the prefix to use when attempting to  locate a namespace.

    **Returns:**
    - the namespace that matches the specified prefix and
      that is in scope for the XML object. If specified
      namespace does not exist, the method returns undefined.



---

### namespaceDeclarations()
- namespaceDeclarations(): [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)
  - : Returns an Array of namespace declarations associated
      with the XML Obnject in the context of its parent.


    **Returns:**
    - an Array of namespace declarations associated
      with the XML Obnject in the context of its parent.



---

### nodeKind()
- nodeKind(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the type of the XML object, such
      as _text_, _comment_, _processing-instruction_,
      or _attribute_.


    **Returns:**
    - the type of the XML object.


---

### normalize()
- normalize(): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Merges adjacent text nodes and eliminates and eliminates
      empty text nodes for this XML object and all its
      descendents.


    **Returns:**
    - the normalized XML object.


---

### parent()
- parent(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the parent of the XML object
      or null if the XML object does not have
      a parent.


    **Returns:**
    - the parent of the XML object
      of null if the XML object does not have
      a parent.



---

### prependChild(Object)
- prependChild(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Inserts the specified child into this XML object
      prior to its existing XML properties and then returns
      this XML object.


    **Parameters:**
    - value - the child to prepend to this  XML object.

    **Returns:**
    - the XML object updated with the prepended child.


---

### processingInstructions()
- processingInstructions(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns an XMLList containing all the children of this XML object
      that are processing-instructions.


    **Returns:**
    - an XMLList containing all the children of this XML object
      that are processing-instructions.



---

### processingInstructions(String)
- processingInstructions(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns an XMLList containing all the children of this XML object
      that are processing-instructions with the specified _name_. If you
      use \* for the name, all processing-instructions are returned.


    **Parameters:**
    - name - the name representing the processing-instructions  you want to retreive.

    **Returns:**
    - an XMLList containing all the children of this XML object
      that are processing-instructions with the specified _name_.



---

### propertyIsEnumerable(String)
- propertyIsEnumerable(property: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean indicating whether the specified
      _property_ will be included in the set of properties iterated
      over when this XML object is used in a _for..in_ statement.


    **Parameters:**
    - property - the property to test.

    **Returns:**
    - true when the property can be iterated in a _for..in_
      statement, false otherwise.



---

### removeNamespace(Namespace)
- removeNamespace(ns: [Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Removes the specified namespace from the in scope namespaces
      of this object and all its descendents, then returns a copy of
      this XML object. This method will not remove a namespace from
      an object when it is referenced by that object's QName or
      the ONames of that object's attributes.


    **Parameters:**
    - ns - the namespace to remove.

    **Returns:**
    - a copy of this XML object with the namespace removed.


---

### replace(String, Object)
- replace(propertyName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Replaces the XML properties of this XML object specified by
      _propertyName_ with _value_ and returns this
      updated XML object. If this XML object contains no properties
      that match _propertyName_, the replace method returns without
      modifying this XML object.
      
      The _propertyName_ parameter may be a numeric property name,
      an unqualified name for a set of XML elements, a qualified
      name for a set of XML elements or the properties wildcard \*.
      
      When the _propertyName_ parameter is an unqualified name,
      it identifies XML elements in the default namespace. The _value_
      parameter may be an XML object, XMLList object or any value
      that may be converted to a String.


    **Parameters:**
    - propertyName - a numeric property name,  an unqualified name for a set of XML elements, a qualified  name for a set of XML elements or the properties wildcard \*.
    - value - an XML object, XMLList object or any value  that may be converted to a String.

    **Returns:**
    - the updated XML object.


---

### setChildren(Object)
- setChildren(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Replaces the XML properties of this XML object
      with a new set of XML properties from _value_.


    **Parameters:**
    - value - a single XML object or an XMLList.

    **Returns:**
    - the updated XML object.


---

### setLocalName(String)
- setLocalName(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Replaces the local name of this XML object with
      a string constructed from the specified _name_.


    **Parameters:**
    - name - the new local name.


---

### setName(String)
- setName(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Replaces the name of this XML object with a
      QName or AttributeName constructed from the specified
      _name_.


    **Parameters:**
    - name - the new name of this XML object.


---

### setNamespace(Namespace)
- setNamespace(ns: [Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md)): void
  - : Replaces the namespace associated with the name of
      this XML object with the specified _namespace_.


    **Parameters:**
    - ns - the namespace to associated with the  name of thix XML object.


---

### setSettings()
- static setSettings(): void
  - : Restores the default settings for the following XML
      properties:
      
      - XML.ignoreComments = true
      - XML.ignoreProcessingInstructions = true
      - XML.ignoreWhitespace = true
      - XML.prettyIndent = 2
      - XML.prettyPrinting = true



---

### setSettings(Object)
- static setSettings(settings: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): void
  - : Updates the collection of global XML properties:
      ignoreComments, ignoreProcessingInstructions, ignoreWhitespace,
      prettyPrinting, prettyIndent, and prettyPrinting.


    **Parameters:**
    - settings - an object with each of the following properties:  ignoreComments, ignoreProcessingInstructions, ignoreWhitespace,  prettyIndent, and prettyPrinting.


---

### settings()
- static settings(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the collection of global XML properties:
      ignoreComments, ignoreProcessingInstructions, ignoreWhitespace,
      prettyPrinting, prettyIndent, and prettyPrinting.


    **Returns:**
    - an object with each of the following properties:
      ignoreComments, ignoreProcessingInstructions, ignoreWhitespace,
      prettyIndent, and prettyPrinting.



---

### text()
- text(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns an XMLList containing all XML properties of
      this XML object that represent XML text nodes.


    **Returns:**
    - an XMLList containing all XML properties of
      this XML object that represent XML text nodes.



---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the String representation of the XML object. If the object contains
       simple content, this method returns a String with tag, attributes, and
       namespace declarations removed. However, if the object contains complex
       content, this method returns an XML encoded String representing the entire
       XML object. If you want to return the entire XML object regardless of
       content complexity, use the _toXMLString()_ method.


    **Returns:**
    - the String representation of the XML object.


---

### toXMLString()
- toXMLString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns a XML-encoded String representation of the XML object, including tag and
      attributed delimiters.


    **Returns:**
    - the string representation of the XML object.


---

### valueOf()
- valueOf(): [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)
  - : Returns this XML object.

    **Returns:**
    - this XML object.


---

<!-- prettier-ignore-end -->

<!-- document id=cf696d288ca75c6d48f47e1770c1e6788388cc3f862e461ef48af3b3ef413029 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.XMLIndentingStreamWriter.md -->

<!-- prettier-ignore-start -->
# Class XMLIndentingStreamWriter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.XMLStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md)
    - [dw.io.XMLIndentingStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md)

A XMLIndentingStreamWriter writes the XML output formatted for good
readability.


**Note:** when this class is used with sensitive data, be careful
in persisting sensitive information to disk.



## Property Summary

| Property | Description |
| --- | --- |
| [indent](#indent): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the indent. |
| [newLine](#newline): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the string that is used for a new line character. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [XMLIndentingStreamWriter](#xmlindentingstreamwriterwriter)([Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)) | Constructs the writer for the specified writer. |

## Method Summary

| Method | Description |
| --- | --- |
| [getIndent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md#getindent)() | Returns the indent. |
| [getNewLine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md#getnewline)() | Returns the string that is used for a new line character. |
| [setIndent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md#setindentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Specifies a string that will be used as identing characters. |
| [setNewLine](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md#setnewlinestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the string that is used for a new line character. |

### Methods inherited from class XMLStreamWriter

[close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#close), [flush](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#flush), [getDefaultNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#getdefaultnamespace), [getPrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#getprefixstring), [setDefaultNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#setdefaultnamespacestring), [setPrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#setprefixstring-string), [writeAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeattributestring-string), [writeAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeattributestring-string-string), [writeAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeattributestring-string-string-string), [writeCData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writecdatastring), [writeCharacters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writecharactersstring), [writeComment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writecommentstring), [writeDTD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writedtdstring), [writeDefaultNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writedefaultnamespacestring), [writeEmptyElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeemptyelementstring), [writeEmptyElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeemptyelementstring-string), [writeEmptyElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeemptyelementstring-string-string), [writeEndDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeenddocument), [writeEndElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeendelement), [writeEntityRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeentityrefstring), [writeNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writenamespacestring-string), [writeProcessingInstruction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeprocessinginstructionstring), [writeProcessingInstruction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeprocessinginstructionstring-string), [writeRaw](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writerawstring), [writeStartDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartdocument), [writeStartDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartdocumentstring), [writeStartDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartdocumentstring-string), [writeStartElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartelementstring), [writeStartElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartelementstring-string), [writeStartElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartelementstring-string-string)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### indent
- indent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the indent.


---

### newLine
- newLine: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string that is used for a new line character. The
      default is the normal new line character.



---

## Constructor Details

### XMLIndentingStreamWriter(Writer)
- XMLIndentingStreamWriter(writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md))
  - : Constructs the writer for the specified writer.

    **Parameters:**
    - writer - the writer to use.


---

## Method Details

### getIndent()
- getIndent(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the indent.

    **Returns:**
    - Returns the indent.


---

### getNewLine()
- getNewLine(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the string that is used for a new line character. The
      default is the normal new line character.


    **Returns:**
    - the new line.


---

### setIndent(String)
- setIndent(indent: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Specifies a string that will be used as identing characters. The
      default are two space characters.


    **Parameters:**
    - indent - The indent to set.


---

### setNewLine(String)
- setNewLine(newLine: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the string that is used for a new line character.

    **Parameters:**
    - newLine - The newLine to set.


---

<!-- prettier-ignore-end -->

<!-- document id=73275225745514a882563a373d57c902b46e304771a488aa5252d6b566a3ecf6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.XMLList.md -->

<!-- prettier-ignore-start -->
# Class XMLList

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)

An XMLList object is an ordered collection of properties.
A XMLList object represents a XML document, an XML fragment,
or an arbitrary collection of XML objects.
An individual XML object is the same thing as an XMLList
containing only that XML object. All operations available
for the XML object are also available for an XMLList object
that contains exactly one XML object.



## Constructor Summary

| Constructor | Description |
| --- | --- |
| [XMLList](#xmllistobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Creates a new XMLList object using the  specified _value_. |

## Method Summary

| Method | Description |
| --- | --- |
| [attribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#attributestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the attribute associated with this XMLList object that  is identified by the specified name. |
| [attributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#attributes)() | Returns an XMList of the attributes in this XMLList Object. |
| [child](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#childobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Returns the children of the XMLList object based on the specified  property name. |
| [children](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#children)() | Returns an XMLList containing the children of this XMLList object, maintaing  the sequence in which they appear. |
| [comments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#comments)() | Returns the properties of the XMLList object that contain comments. |
| [contains](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#containsxml)([XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)) | Returns true if this XMLList object contains the specified  XML object, false otherwise. |
| [copy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#copy)() | Returns a deep copy of the this XMLList object. |
| [descendants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#descendants)() | Calls the _descendants()_ method of each XML object in this XMLList  object and returns an XMLList containing the  results concatenated in order. |
| [descendants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#descendantsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Calls the _descendants(name)_ method of each XML object in this XMLList  object and returns an XMLList containing the  results concatenated in order. |
| [elements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#elements)() | Calls the _elements()_ method in each XML object in this XMLList  object and returns an XMLList containing the results concatenated in order. |
| [elements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#elementsobject)([Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)) | Calls the _elements(name)_ method in each of the XML objects in  this XMLList object and returns an XMLList containing the results  concatenated in order. |
| [hasComplexContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#hascomplexcontent)() | Returns a Boolean value indicating whether  this XMLList object contains complex content. |
| [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#hasownpropertystring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a Boolean value indicating whether this object has the  property specified by _prop_. |
| [hasSimpleContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#hassimplecontent)() | Returns a Boolean value indicating whether this XML object contains  simple content. |
| [length](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#length)() | Returns the number of children in this XMLList  object. |
| [normalize](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#normalize)() | Puts all text nodes in this XMLList, all the XML objects it  contains and the descendents of all the XML objects it  contains into a normal form by merging adjacent text nodes  and eliminating empty text nodes. |
| [parent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#parent)() | Returns the parent of the XMLList object  or null if the XMLList object does not have  a parent. |
| [processingInstructions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#processinginstructions)() | Calls the _processingInstructions()_ method of each XML object  in this XMLList object and returns an XMList containing the results  in order. |
| [processingInstructions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#processinginstructionsstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Calls the _processingInstructions(name)_ method of each XML object  in this XMLList object and returns an XMList containing the results  in order. |
| [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#propertyisenumerablestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns a Boolean indicating whether the specified  _property_ will be included in the set of properties iterated  over when this XML object is used in a _for..in_ statement. |
| [text](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#text)() | Calls the _text()_ method of each XML object contained  in this XMLList object and returns an XMLList containing  the results concatenated in order. |
| [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#tostring)() | Returns the String representation of this XMLList object. |
| [toXMLString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#toxmlstring)() | Returns an XML-encoded String representation of the XMLList object  by calling the _toXMLString_ method on each property contained  within this XMLList object. |
| [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md#valueof)() | Returns this XMLList object. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constructor Details

### XMLList(Object)
- XMLList(value: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md))
  - : Creates a new XMLList object using the
      specified _value_.


    **Parameters:**
    - value - the value to use.


---

## Method Details

### attribute(String)
- attribute(attributeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns the attribute associated with this XMLList object that
      is identified by the specified name.


    **Parameters:**
    - attributeName - the name of the attribute.

    **Returns:**
    - the value of the attribute as either an XMLList or an empty XMLList


---

### attributes()
- attributes(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns an XMList of the attributes in this XMLList Object.

    **Returns:**
    - an XMList of the attributes in this XMLList Object.


---

### child(Object)
- child(propertyName: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns the children of the XMLList object based on the specified
      property name.


    **Parameters:**
    - propertyName - the property name representing the  children of this XMLList object.

    **Returns:**
    - an XMLList of children that match the property name
      parameter.



---

### children()
- children(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns an XMLList containing the children of this XMLList object, maintaing
      the sequence in which they appear.


    **Returns:**
    - an XMLList containing the children of this XMLList object.


---

### comments()
- comments(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns the properties of the XMLList object that contain comments.

    **Returns:**
    - properties of the XMLList object that contain comments.


---

### contains(XML)
- contains(value: [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if this XMLList object contains the specified
      XML object, false otherwise.


    **Parameters:**
    - value - the object to locate in this XMLList object.

    **Returns:**
    - true if this XMLList object contains the specified
      XML object, false otherwise.



---

### copy()
- copy(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns a deep copy of the this XMLList object.

    **Returns:**
    - the deep copy of the object.


---

### descendants()
- descendants(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Calls the _descendants()_ method of each XML object in this XMLList
      object and returns an XMLList containing the
      results concatenated in order.


    **Returns:**
    - a list of all descendents of the XML objects in this XMLList object.


---

### descendants(String)
- descendants(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Calls the _descendants(name)_ method of each XML object in this XMLList
      object and returns an XMLList containing the
      results concatenated in order.


    **Parameters:**
    - name - the name of the element to match. To return all descendents,  use \* as the _name_ parameter.

    **Returns:**
    - a list of all descendents of the XML objects in this XMLList
      constrained by the _name_ parameter.



---

### elements()
- elements(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Calls the _elements()_ method in each XML object in this XMLList
      object and returns an XMLList containing the results concatenated in order.



---

### elements(Object)
- elements(name: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Calls the _elements(name)_ method in each of the XML objects in
      this XMLList object and returns an XMLList containing the results
      concatenated in order. _name_ can be a
      QName, String, or any other data type that will be converted
      to a string prior to performing the search for elements of that
      name.
      
      To list all objects use \* for the value of _name_.


    **Parameters:**
    - name - the name of the elements to return.

    **Returns:**
    - a list of all elements of the XML objects in this XMLList
      constrained by the _name_ parameter.



---

### hasComplexContent()
- hasComplexContent(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean value indicating whether
      this XMLList object contains complex content. An XMLList object is considered
      to contain complex content if it is not empty, contains a single XML item
      with complex content or contains elements.


    **Returns:**
    - a Boolean value indicating whether this XMLList object contains complex content.


---

### hasOwnProperty(String)
- hasOwnProperty(prop: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean value indicating whether this object has the
      property specified by _prop_.


    **Parameters:**
    - prop - the property to locate.

    **Returns:**
    - true if the property exists, false otherwise.


---

### hasSimpleContent()
- hasSimpleContent(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean value indicating whether this XML object contains
      simple content. An XMLList object is considered to contain simple
      content if it is empty, contains a single XML item with simple
      content or contains no elements.


    **Returns:**
    - a Boolean value indicating whether this XML object contains
      simple content.



---

### length()
- length(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the number of children in this XMLList
      object.


    **Returns:**
    - the number of children in this XMLList
      object.



---

### normalize()
- normalize(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Puts all text nodes in this XMLList, all the XML objects it
      contains and the descendents of all the XML objects it
      contains into a normal form by merging adjacent text nodes
      and eliminating empty text nodes.


    **Returns:**
    - the XMLList object containing normailzed objects.


---

### parent()
- parent(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Returns the parent of the XMLList object
      or null if the XMLList object does not have
      a parent.


    **Returns:**
    - the parent of the XMLList object
      or null if the XMLList object does not have
      a parent.



---

### processingInstructions()
- processingInstructions(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Calls the _processingInstructions()_ method of each XML object
      in this XMLList object and returns an XMList containing the results
      in order.


    **Returns:**
    - an XMLList contaiing the result of calling the
      _processingInstructions()_ method of each XML object
      in this XMLList object.



---

### processingInstructions(String)
- processingInstructions(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Calls the _processingInstructions(name)_ method of each XML object
      in this XMLList object and returns an XMList containing the results
      in order.


    **Parameters:**
    - name - the name representing the processing-instructions  you want to retreive.

    **Returns:**
    - an XMLList containing the result of calling the
      _processingInstructions(name)_ method of each XML object
      in this XMLList object.



---

### propertyIsEnumerable(String)
- propertyIsEnumerable(property: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns a Boolean indicating whether the specified
      _property_ will be included in the set of properties iterated
      over when this XML object is used in a _for..in_ statement.


    **Parameters:**
    - property - the property to test.

    **Returns:**
    - true when the property can be iterated in a _for..in_
      statement, false otherwise.



---

### text()
- text(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Calls the _text()_ method of each XML object contained
      in this XMLList object and returns an XMLList containing
      the results concatenated in order.


    **Returns:**
    - the concatenated results of calling the _text()_
      method of every XML object contained in this XMLList.



---

### toString()
- toString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the String representation of this XMLList object.

    **Returns:**
    - the String representation of this XMLList object.


---

### toXMLString()
- toXMLString(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns an XML-encoded String representation of the XMLList object
      by calling the _toXMLString_ method on each property contained
      within this XMLList object.


    **Returns:**
    - an XML-encoded String representation of the XMLList object
      by calling the _toXMLString_ method on each property contained
      within this XMLList object.



---

### valueOf()
- valueOf(): [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)
  - : Returns this XMLList object.

    **Returns:**
    - this XMLList object.


---

<!-- prettier-ignore-end -->

<!-- document id=c743fb326b5413e2aa5caebe5ff35e3d23ba7a11e113676255d4a254aec155ff url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.XMLStreamConstants.md -->

<!-- prettier-ignore-start -->
# Class XMLStreamConstants

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.XMLStreamConstants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamConstants.md)

Useful constants for working with XML streams.


## Constant Summary

| Constant | Description |
| --- | --- |
| [ATTRIBUTE](#attribute): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10 | Represents an attribute in an element. |
| [CDATA](#cdata): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12 | Represents a CDATA section in an element. |
| [CHARACTERS](#characters): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4 | Represents the character data in an XML document. |
| [COMMENT](#comment): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5 | Represents a comment in an XML document. |
| [DTD](#dtd): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11 | Represents the document type definition. |
| [END_DOCUMENT](#end_document): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8 | Represents the end of an XML document. |
| [END_ELEMENT](#end_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2 | Represents the end of an element in an XML document. |
| [ENTITY_DECLARATION](#entity_declaration): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 15 | Represents the entity declaration in an XML document. |
| [ENTITY_REFERENCE](#entity_reference): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9 | Represents an entity reference in an XML document. |
| [NAMESPACE](#namespace): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13 | Represents a namespace declaration in an XML document. |
| [NOTATION_DECLARATION](#notation_declaration): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 14 | Represents the notation declaration in an XML document. |
| [PROCESSING_INSTRUCTION](#processing_instruction): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3 | Represents processing instruction in an XML document. |
| [SPACE](#space): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6 | Represents a space in an XML document. |
| [START_DOCUMENT](#start_document): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7 | Represents the start of an XML document. |
| [START_ELEMENT](#start_element): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1 | Represents the start of an element in an XML document. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [XMLStreamConstants](#xmlstreamconstants)() |  |

## Method Summary

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Constant Details

### ATTRIBUTE

- ATTRIBUTE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 10
  - : Represents an attribute in an element.


---

### CDATA

- CDATA: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 12
  - : Represents a CDATA section in an element.


---

### CHARACTERS

- CHARACTERS: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 4
  - : Represents the character data in an XML document.


---

### COMMENT

- COMMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 5
  - : Represents a comment in an XML document.


---

### DTD

- DTD: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 11
  - : Represents the document type definition.


---

### END_DOCUMENT

- END_DOCUMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 8
  - : Represents the end of an XML document.


---

### END_ELEMENT

- END_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 2
  - : Represents the end of an element in an XML document.


---

### ENTITY_DECLARATION

- ENTITY_DECLARATION: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 15
  - : Represents the entity declaration in an XML document.


---

### ENTITY_REFERENCE

- ENTITY_REFERENCE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 9
  - : Represents an entity reference in an XML document.


---

### NAMESPACE

- NAMESPACE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 13
  - : Represents a namespace declaration in an XML document.


---

### NOTATION_DECLARATION

- NOTATION_DECLARATION: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 14
  - : Represents the notation declaration in an XML document.


---

### PROCESSING_INSTRUCTION

- PROCESSING_INSTRUCTION: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 3
  - : Represents processing instruction in an XML document.


---

### SPACE

- SPACE: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 6
  - : Represents a space in an XML document.


---

### START_DOCUMENT

- START_DOCUMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 7
  - : Represents the start of an XML document.


---

### START_ELEMENT

- START_ELEMENT: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) = 1
  - : Represents the start of an element in an XML document.


---

## Constructor Details

### XMLStreamConstants()
- XMLStreamConstants()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=70989f4bed430399d89a0d4a51fb239fcdacc12ad3b462018aa4f482aafb10bf url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.XMLStreamError.md -->

<!-- prettier-ignore-start -->
# Class XMLStreamError

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [TopLevel.Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)
    - [TopLevel.XMLStreamError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLStreamError.md)

This error indicates an XML streaming related error in the system. The IOError
is always related to a systems internal Java exception. The class provides
access to some more details about this internal Java exception. In particular
the class informs about the location of the error.



## Property Summary

| Property | Description |
| --- | --- |
| [causeFullName](#causefullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the full name of the associated Java exception. |
| [causeMessage](#causemessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the message of the associated Java exception. |
| [causeName](#causename): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | If the exception is associated with a root cause, the property  contains the simplified name of the associated Java exception. |
| [javaFullName](#javafullname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The full name of the underlying Java exception. |
| [javaMessage](#javamessage): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The message of the underlying Java exception. |
| [javaName](#javaname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | The simplified name of the underlying Java exception. |
| [xmlColumnNumber](#xmlcolumnnumber): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The column number where the error occured. |
| [xmlLineNumber](#xmllinenumber): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) | The line where the error occured. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [XMLStreamError](#xmlstreamerror)() |  |

## Method Summary

### Methods inherited from class Error

[captureStackTrace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#capturestacktraceerror-function), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md#tostring)
### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### causeFullName
- causeFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the full name of the associated Java exception.



---

### causeMessage
- causeMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the message of the associated Java exception.



---

### causeName
- causeName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the exception is associated with a root cause, the property
      contains the simplified name of the associated Java exception.



---

### javaFullName
- javaFullName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The full name of the underlying Java exception.


---

### javaMessage
- javaMessage: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The message of the underlying Java exception.


---

### javaName
- javaName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : The simplified name of the underlying Java exception.


---

### xmlColumnNumber
- xmlColumnNumber: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The column number where the error occured.


---

### xmlLineNumber
- xmlLineNumber: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : The line where the error occured.


---

## Constructor Details

### XMLStreamError()
- XMLStreamError()
  - : 


---

<!-- prettier-ignore-end -->

<!-- document id=a7d2393690077dfd4b52608ced5d77ab120f5875105733ae1bf308326948cdba url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.XMLStreamReader.md -->

<!-- prettier-ignore-start -->
# Class XMLStreamReader

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.XMLStreamReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md)

The XMLStreamReader allows forward, read-only access to XML.  It is designed
to be the lowest level and most efficient way to read XML data.


 The XMLStreamReader is designed to iterate over XML using
next() and hasNext().  The data can be accessed using methods such as getEventType(),
getNamespaceURI(), getLocalName() and getText();



 The [next()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#next) method causes the reader to read the next parse event.
The next() method returns an integer which identifies the type of event just read.


 The event type can be determined using [getEventType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#geteventtype).


 Parsing events are defined as the XML Declaration, a DTD,
start tag, character data, white space, end tag, comment,
or processing instruction.  An attribute or namespace event may be encountered
at the root level of a document as the result of a query operation.



The following table describes which methods are valid in what state.
If a method is called in an invalid state the method will throw a
java.lang.IllegalStateException.


|           Valid methods for each state         |
| --- |
| Event Type | Valid Methods |
|  All States   |  getProperty(), hasNext(), require(), close(),             getNamespaceURI(), isStartElement(),             isEndElement(), isCharacters(), isWhiteSpace(),             getNamespaceContext(), getEventType(),getLocation(),             hasText(), hasName()         |
|  START\_ELEMENT   |  next(), getName(), getLocalName(), hasName(), getPrefix(),             getAttributeXXX(), isAttributeSpecified(),             getNamespaceXXX(),             getElementText(), nextTag(), getXMLObject()         |
|  ATTRIBUTE   |  next(), nextTag()             getAttributeXXX(), isAttributeSpecified(),         |
|  NAMESPACE   |  next(), nextTag()             getNamespaceXXX()         |
|  END\_ELEMENT   |  next(), getName(), getLocalName(), hasName(), getPrefix(),             getNamespaceXXX(), nextTag()        |
|  CHARACTERS   |  next(), getTextXXX(), nextTag()  |
|  CDATA   |  next(), getTextXXX(), nextTag()  |
|  COMMENT   |  next(), getTextXXX(), nextTag()  |
|  SPACE   |  next(), getTextXXX(), nextTag()  |
|  START\_DOCUMENT   |  next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(),             getCharacterEncodingScheme(), nextTag() |
|  END\_DOCUMENT   |  close() |
|  PROCESSING\_INSTRUCTION   |  next(), getPITarget(), getPIData(), nextTag()  |
|  ENTITY\_REFERENCE   |  next(), getLocalName(), getText(), nextTag()  |
|  DTD   |  next(), getText(), nextTag()  |





The following is a code sample to read an XML file containing multiple
"myobject" sub-elements.  Only one myObject instance is kept in memory at
any given time to keep memory consumption low:


```
var fileReader : FileReader = new FileReader(file, "UTF-8");
var xmlStreamReader : XMLStreamReader = new XMLStreamReader(fileReader);

while (xmlStreamReader.hasNext())
{
  if (xmlStreamReader.next() == XMLStreamConstants.START_ELEMENT)
  {
    var localElementName : String = xmlStreamReader.getLocalName();
    if (localElementName == "myobject")
    {
      // read single "myobject" as XML
      var myObject : XML = xmlStreamReader.getXMLObject();

      // process myObject
    }
  }
}

xmlStreamReader.close();
fileReader.close();
```



## Property Summary

| Property | Description |
| --- | --- |
| [PIData](#pidata): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the data section of a processing instruction. |
| [PITarget](#pitarget): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the target of a processing instruction. |
| ~~[XMLObject](#xmlobject): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)~~ `(read-only)` | Reads a sub-tree of the XML document and parses it as XML object. |
| [attributeCount](#attributecount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the count of attributes on this START\_ELEMENT,  this method is only valid on a START\_ELEMENT or ATTRIBUTE. |
| [characterEncodingScheme](#characterencodingscheme): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the character encoding declared on the XML declaration  Returns null if none was declared. |
| [characters](#characters): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the cursor points to a character data event. |
| [columnNumber](#columnnumber): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the column number where the current event ends or -1 if none is  available. |
| ~~[elementText](#elementtext): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)` | Reads the content of a text-only element, an exception is thrown if this is not a text-only element. |
| [encoding](#encoding): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Return input encoding if known or null if unknown. |
| [endElement](#endelement): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the cursor points to an end tag. |
| [eventType](#eventtype): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns an integer code that indicates the type  of the event the cursor is pointing to. |
| [lineNumber](#linenumber): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the line number where the current event ends or -1 if none is  available. |
| [localName](#localname): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the (local) name of the current event. |
| [namespaceCount](#namespacecount): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the count of namespaces declared on this START\_ELEMENT or END\_ELEMENT,  this method is only valid on a START\_ELEMENT, END\_ELEMENT or NAMESPACE. |
| [namespaceURI](#namespaceuri): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | If the current event is a START\_ELEMENT or END\_ELEMENT  this method  returns the URI of the prefix or the default namespace. |
| [prefix](#prefix): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the prefix of the current event or null if the event does not have a prefix |
| [standalone](#standalone): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Get the standalone declaration from the xml declaration. |
| [startElement](#startelement): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the cursor points to a start tag. |
| [text](#text): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Returns the current value of the parse event as a string,  this returns the string value of a CHARACTERS event,  returns the value of a COMMENT, the replacement value  for an ENTITY\_REFERENCE, the string value of a CDATA section,  the string value for a SPACE event,  or the String value of the internal subset of the DTD. |
| [textLength](#textlength): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the length of the sequence of characters for this  Text event within the text character array. |
| [textStart](#textstart): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)` | Returns the offset into the text character array where the first  character (of this text event) is stored. |
| [version](#version): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)` | Get the xml version declared on the xml declaration. |
| [whiteSpace](#whitespace): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)` | Identifies if the cursor points to a character data event  that consists of all whitespace. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [XMLStreamReader](#xmlstreamreaderreader)([Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md)) | Constructs the stream readon on behalf of the reader. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#close)() | Frees any resources associated with this Reader. |
| [getAttributeCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getattributecount)() | Returns the count of attributes on this START\_ELEMENT,  this method is only valid on a START\_ELEMENT or ATTRIBUTE. |
| [getAttributeLocalName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getattributelocalnamenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the localName of the attribute at the provided  index. |
| [getAttributeNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getattributenamespacenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the namespace of the attribute at the provided  index. |
| [getAttributePrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getattributeprefixnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the prefix of this attribute at the  provided index. |
| [getAttributeType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getattributetypenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the XML type of the attribute at the provided  index. |
| [getAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getattributevaluenumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the value of the attribute at the  index. |
| [getAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getattributevaluestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Returns the normalized attribute value of the  attribute with the namespace and localName  If the namespaceURI is null the namespace  is not checked for equality |
| [getCharacterEncodingScheme](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getcharacterencodingscheme)() | Returns the character encoding declared on the XML declaration  Returns null if none was declared. |
| [getColumnNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getcolumnnumber)() | Returns the column number where the current event ends or -1 if none is  available. |
| ~~[getElementText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getelementtext)()~~ | Reads the content of a text-only element, an exception is thrown if this is not a text-only element. |
| [getEncoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getencoding)() | Return input encoding if known or null if unknown. |
| [getEventType](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#geteventtype)() | Returns an integer code that indicates the type  of the event the cursor is pointing to. |
| [getLineNumber](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getlinenumber)() | Returns the line number where the current event ends or -1 if none is  available. |
| [getLocalName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getlocalname)() | Returns the (local) name of the current event. |
| [getNamespaceCount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getnamespacecount)() | Returns the count of namespaces declared on this START\_ELEMENT or END\_ELEMENT,  this method is only valid on a START\_ELEMENT, END\_ELEMENT or NAMESPACE. |
| [getNamespacePrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getnamespaceprefixnumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the prefix for the namespace declared at the  index. |
| [getNamespaceURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getnamespaceuri)() | If the current event is a START\_ELEMENT or END\_ELEMENT  this method  returns the URI of the prefix or the default namespace. |
| [getNamespaceURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getnamespaceurinumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Returns the uri for the namespace declared at the  index. |
| [getNamespaceURI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getnamespaceuristring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Return the uri for the given prefix. |
| [getPIData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getpidata)() | Get the data section of a processing instruction. |
| [getPITarget](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getpitarget)() | Get the target of a processing instruction. |
| [getPrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getprefix)() | Returns the prefix of the current event or null if the event does not have a prefix |
| [getText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#gettext)() | Returns the current value of the parse event as a string,  this returns the string value of a CHARACTERS event,  returns the value of a COMMENT, the replacement value  for an ENTITY\_REFERENCE, the string value of a CDATA section,  the string value for a SPACE event,  or the String value of the internal subset of the DTD. |
| [getTextLength](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#gettextlength)() | Returns the length of the sequence of characters for this  Text event within the text character array. |
| [getTextStart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#gettextstart)() | Returns the offset into the text character array where the first  character (of this text event) is stored. |
| [getVersion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getversion)() | Get the xml version declared on the xml declaration. |
| ~~[getXMLObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#getxmlobject)()~~ | Reads a sub-tree of the XML document and parses it as XML object. |
| [hasName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#hasname)() | Identifies if the current event has a name (is a START\_ELEMENT or END\_ELEMENT) |
| [hasNext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#hasnext)() | Returns true if there are more parsing events and false  if there are no more events. |
| [hasText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#hastext)() | Indicates if the current event has text. |
| [isAttributeSpecified](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#isattributespecifiednumber)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)) | Identifies if this  attribute was created by default. |
| [isCharacters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#ischaracters)() | Identifies if the cursor points to a character data event. |
| [isEndElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#isendelement)() | Identifies if the cursor points to an end tag. |
| [isStandalone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#isstandalone)() | Get the standalone declaration from the xml declaration. |
| [isStartElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#isstartelement)() | Identifies if the cursor points to a start tag. |
| [isWhiteSpace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#iswhitespace)() | Identifies if the cursor points to a character data event  that consists of all whitespace. |
| [next](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#next)() | Get next parsing event - a processor may return all contiguous  character data in a single chunk, or it may split it into several chunks. |
| [nextTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#nexttag)() | Skips any white space (isWhiteSpace() returns true), COMMENT,  or PROCESSING\_INSTRUCTION,  until a START\_ELEMENT or END\_ELEMENT is reached. |
| [readElementText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#readelementtext)() | Reads the content of a text-only element, an exception is thrown if this is not a text-only element. |
| [readXMLObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#readxmlobject)() | Reads a sub-tree of the XML document and parses it as XML object. |
| [require](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#requirenumber-string-string)([Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Test if the current event is of the given type and if the namespace and name match the current  namespace and name of the current event. |
| [standaloneSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#standaloneset)() | Identifies if standalone was set in the document. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### PIData
- PIData: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the data section of a processing instruction.


---

### PITarget
- PITarget: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the target of a processing instruction.


---

### XMLObject
- ~~XMLObject: [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)~~ `(read-only)`
  - : Reads a sub-tree of the XML document and parses it as XML object.
      
      
      The stream must be positioned on a START\_ELEMENT. Do not call the method
      when the stream is positioned at document's root element. This would
      cause the whole document to be parsed into a single XML what may lead to
      an out-of-memory condition. Instead use \#next() to navigate to
      sub-elements and invoke getXMLObject() there. Do not keep references to
      more than the currently processed XML to keep memory consumption low. The
      method reads the stream up to the matching END\_ELEMENT. When the method
      returns the current event is the END\_ELEMENT event.


    **Deprecated:**
**warning:** Use [readXMLObject()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#readxmlobject)

---

### attributeCount
- attributeCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the count of attributes on this START\_ELEMENT,
      this method is only valid on a START\_ELEMENT or ATTRIBUTE.  This
      count excludes namespace definitions.  Attribute indices are
      zero-based.



---

### characterEncodingScheme
- characterEncodingScheme: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the character encoding declared on the XML declaration
      Returns null if none was declared.



---

### characters
- characters: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the cursor points to a character data event.


---

### columnNumber
- columnNumber: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the column number where the current event ends or -1 if none is
      available.



---

### elementText
- ~~elementText: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~ `(read-only)`
  - : Reads the content of a text-only element, an exception is thrown if this is not a text-only element. This method
      always returns coalesced content. 
      
      Precondition: the current event is START\_ELEMENT. 
      
      Postcondition: the current event is the corresponding END\_ELEMENT. 
      
      The method does the following (implementations are free to be optimized but must do equivalent processing):
      
      
      ```
      if ( getEventType() != XMLStreamConstants.START_ELEMENT )
      {
          throw new XMLStreamException( "parser must be on START_ELEMENT to read next text", getLocation() );
      }
      int eventType = next();
      StringBuffer content = new StringBuffer();
      while ( eventType != XMLStreamConstants.END_ELEMENT )
      {
          if ( eventType == XMLStreamConstants.CHARACTERS || eventType == XMLStreamConstants.CDATA
              || eventType == XMLStreamConstants.SPACE || eventType == XMLStreamConstants.ENTITY_REFERENCE )
          {
              buf.append( getText() );
          }
          else if ( eventType == XMLStreamConstants.PROCESSING_INSTRUCTION || eventType == XMLStreamConstants.COMMENT )
          {
              // skipping
          }
          else if ( eventType == XMLStreamConstants.END_DOCUMENT )
          {
              throw new XMLStreamException( "unexpected end of document when reading element text content", this );
          }
          else if ( eventType == XMLStreamConstants.START_ELEMENT )
          {
              throw new XMLStreamException( "element text content may not contain START_ELEMENT", getLocation() );
          }
          else
          {
              throw new XMLStreamException( "Unexpected event type " + eventType, getLocation() );
          }
          eventType = next();
      }
      return buf.toString();
      ```


    **Deprecated:**
**warning:** Use [readElementText()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#readelementtext)

---

### encoding
- encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Return input encoding if known or null if unknown.


---

### endElement
- endElement: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the cursor points to an end tag.


---

### eventType
- eventType: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns an integer code that indicates the type
      of the event the cursor is pointing to.



---

### lineNumber
- lineNumber: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the line number where the current event ends or -1 if none is
      available.



---

### localName
- localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the (local) name of the current event.
      For START\_ELEMENT or END\_ELEMENT returns the (local) name of the current element.
      For ENTITY\_REFERENCE it returns entity name.
      The current event must be START\_ELEMENT or END\_ELEMENT,
      or ENTITY\_REFERENCE.



---

### namespaceCount
- namespaceCount: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the count of namespaces declared on this START\_ELEMENT or END\_ELEMENT,
      this method is only valid on a START\_ELEMENT, END\_ELEMENT or NAMESPACE. On
      an END\_ELEMENT the count is of the namespaces that are about to go
      out of scope.  This is the equivalent of the information reported
      by SAX callback for an end element event.



---

### namespaceURI
- namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : If the current event is a START\_ELEMENT or END\_ELEMENT  this method
      returns the URI of the prefix or the default namespace.
      Returns null if the event does not have a prefix.



---

### prefix
- prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the prefix of the current event or null if the event does not have a prefix


---

### standalone
- standalone: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Get the standalone declaration from the xml declaration.


---

### startElement
- startElement: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the cursor points to a start tag.


---

### text
- text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Returns the current value of the parse event as a string,
      this returns the string value of a CHARACTERS event,
      returns the value of a COMMENT, the replacement value
      for an ENTITY\_REFERENCE, the string value of a CDATA section,
      the string value for a SPACE event,
      or the String value of the internal subset of the DTD.
      If an ENTITY\_REFERENCE has been resolved, any character data
      will be reported as CHARACTERS events.



---

### textLength
- textLength: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the length of the sequence of characters for this
      Text event within the text character array.



---

### textStart
- textStart: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md) `(read-only)`
  - : Returns the offset into the text character array where the first
      character (of this text event) is stored.



---

### version
- version: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) `(read-only)`
  - : Get the xml version declared on the xml declaration.
      Returns null if none was declared.



---

### whiteSpace
- whiteSpace: [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md) `(read-only)`
  - : Identifies if the cursor points to a character data event
      that consists of all whitespace.



---

## Constructor Details

### XMLStreamReader(Reader)
- XMLStreamReader(reader: [Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md))
  - : Constructs the stream readon on behalf of the reader.

    **Parameters:**
    - reader - the reader to use.


---

## Method Details

### close()
- close(): void
  - : Frees any resources associated with this Reader.  This method does not close the
      underlying reader.



---

### getAttributeCount()
- getAttributeCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the count of attributes on this START\_ELEMENT,
      this method is only valid on a START\_ELEMENT or ATTRIBUTE.  This
      count excludes namespace definitions.  Attribute indices are
      zero-based.


    **Returns:**
    - returns the number of attributes.


---

### getAttributeLocalName(Number)
- getAttributeLocalName(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the localName of the attribute at the provided
      index.


    **Parameters:**
    - index - the position of the attribute.

    **Returns:**
    - the local name of the attribute.


---

### getAttributeNamespace(Number)
- getAttributeNamespace(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the namespace of the attribute at the provided
      index.


    **Parameters:**
    - index - the position of the attribute

    **Returns:**
    - the namespace URI (can be null)


---

### getAttributePrefix(Number)
- getAttributePrefix(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the prefix of this attribute at the
      provided index.


    **Parameters:**
    - index - the position of the attribute.

    **Returns:**
    - the prefix of the attribute.


---

### getAttributeType(Number)
- getAttributeType(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the XML type of the attribute at the provided
      index.


    **Parameters:**
    - index - the position of the attribute.

    **Returns:**
    - the XML type of the attribute.


---

### getAttributeValue(Number)
- getAttributeValue(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the value of the attribute at the
      index.


    **Parameters:**
    - index - the position of the attribute.

    **Returns:**
    - the attribute value.


---

### getAttributeValue(String, String)
- getAttributeValue(namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the normalized attribute value of the
      attribute with the namespace and localName
      If the namespaceURI is null the namespace
      is not checked for equality


    **Parameters:**
    - namespaceURI - the namespace of the attribute
    - localName - the local name of the attribute, cannot be null

    **Returns:**
    - returns the value of the attribute or null if not found.


---

### getCharacterEncodingScheme()
- getCharacterEncodingScheme(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the character encoding declared on the XML declaration
      Returns null if none was declared.


    **Returns:**
    - the encoding declared in the document or null.


---

### getColumnNumber()
- getColumnNumber(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the column number where the current event ends or -1 if none is
      available.


    **Returns:**
    - the column number or -1.


---

### getElementText()
- ~~getElementText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)~~
  - : Reads the content of a text-only element, an exception is thrown if this is not a text-only element. This method
      always returns coalesced content. 
      
      Precondition: the current event is START\_ELEMENT. 
      
      Postcondition: the current event is the corresponding END\_ELEMENT. 
      
      The method does the following (implementations are free to be optimized but must do equivalent processing):
      
      
      ```
      if ( getEventType() != XMLStreamConstants.START_ELEMENT )
      {
          throw new XMLStreamException( "parser must be on START_ELEMENT to read next text", getLocation() );
      }
      int eventType = next();
      StringBuffer content = new StringBuffer();
      while ( eventType != XMLStreamConstants.END_ELEMENT )
      {
          if ( eventType == XMLStreamConstants.CHARACTERS || eventType == XMLStreamConstants.CDATA
              || eventType == XMLStreamConstants.SPACE || eventType == XMLStreamConstants.ENTITY_REFERENCE )
          {
              buf.append( getText() );
          }
          else if ( eventType == XMLStreamConstants.PROCESSING_INSTRUCTION || eventType == XMLStreamConstants.COMMENT )
          {
              // skipping
          }
          else if ( eventType == XMLStreamConstants.END_DOCUMENT )
          {
              throw new XMLStreamException( "unexpected end of document when reading element text content", this );
          }
          else if ( eventType == XMLStreamConstants.START_ELEMENT )
          {
              throw new XMLStreamException( "element text content may not contain START_ELEMENT", getLocation() );
          }
          else
          {
              throw new XMLStreamException( "Unexpected event type " + eventType, getLocation() );
          }
          eventType = next();
      }
      return buf.toString();
      ```


    **Deprecated:**
**warning:** Use [readElementText()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#readelementtext)

---

### getEncoding()
- getEncoding(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return input encoding if known or null if unknown.

    **Returns:**
    - the encoding of this instance or null


---

### getEventType()
- getEventType(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns an integer code that indicates the type
      of the event the cursor is pointing to.


    **Returns:**
    - an integer code that indicates the type
      of the event the cursor is pointing to.



---

### getLineNumber()
- getLineNumber(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the line number where the current event ends or -1 if none is
      available.


    **Returns:**
    - the line number or -1.


---

### getLocalName()
- getLocalName(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the (local) name of the current event.
      For START\_ELEMENT or END\_ELEMENT returns the (local) name of the current element.
      For ENTITY\_REFERENCE it returns entity name.
      The current event must be START\_ELEMENT or END\_ELEMENT,
      or ENTITY\_REFERENCE.


    **Returns:**
    - the local name.


---

### getNamespaceCount()
- getNamespaceCount(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the count of namespaces declared on this START\_ELEMENT or END\_ELEMENT,
      this method is only valid on a START\_ELEMENT, END\_ELEMENT or NAMESPACE. On
      an END\_ELEMENT the count is of the namespaces that are about to go
      out of scope.  This is the equivalent of the information reported
      by SAX callback for an end element event.


    **Returns:**
    - returns the number of namespace declarations on this specific element.


---

### getNamespacePrefix(Number)
- getNamespacePrefix(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the prefix for the namespace declared at the
      index.  Returns null if this is the default namespace
      declaration.


    **Parameters:**
    - index - the position of the namespace declaration.

    **Returns:**
    - returns the namespace prefix.


---

### getNamespaceURI()
- getNamespaceURI(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : If the current event is a START\_ELEMENT or END\_ELEMENT  this method
      returns the URI of the prefix or the default namespace.
      Returns null if the event does not have a prefix.


    **Returns:**
    - the URI bound to this elements prefix, the default namespace, or null.


---

### getNamespaceURI(Number)
- getNamespaceURI(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the uri for the namespace declared at the
      index.


    **Parameters:**
    - index - the position of the namespace declaration.

    **Returns:**
    - returns the namespace uri.


---

### getNamespaceURI(String)
- getNamespaceURI(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Return the uri for the given prefix.
      The uri returned depends on the current state of the processor.
      
      
      **NOTE:**The 'xml' prefix is bound as defined in
      [Namespaces in XML](http://www.w3.org/TR/REC-xml-names/\#ns-using)
      specification to "http://www.w3.org/XML/1998/namespace".
      
      
      **NOTE:** The 'xmlns' prefix must be resolved to following namespace
      [http://www.w3.org/2000/xmlns/](http://www.w3.org/2000/xmlns/)


    **Parameters:**
    - prefix - The prefix to lookup, may not be null

    **Returns:**
    - the uri bound to the given prefix or null if it is not bound


---

### getPIData()
- getPIData(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the data section of a processing instruction.

    **Returns:**
    - the data or null.


---

### getPITarget()
- getPITarget(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the target of a processing instruction.

    **Returns:**
    - the target or null.


---

### getPrefix()
- getPrefix(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the prefix of the current event or null if the event does not have a prefix

    **Returns:**
    - the prefix or null.


---

### getText()
- getText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current value of the parse event as a string,
      this returns the string value of a CHARACTERS event,
      returns the value of a COMMENT, the replacement value
      for an ENTITY\_REFERENCE, the string value of a CDATA section,
      the string value for a SPACE event,
      or the String value of the internal subset of the DTD.
      If an ENTITY\_REFERENCE has been resolved, any character data
      will be reported as CHARACTERS events.


    **Returns:**
    - the current text or null.


---

### getTextLength()
- getTextLength(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the length of the sequence of characters for this
      Text event within the text character array.


    **Returns:**
    - the length of the sequence of characters for this
      Text event within the text character array.



---

### getTextStart()
- getTextStart(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Returns the offset into the text character array where the first
      character (of this text event) is stored.


    **Returns:**
    - the offset into the text character array where the first
      character (of this text event) is stored.



---

### getVersion()
- getVersion(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Get the xml version declared on the xml declaration.
      Returns null if none was declared.


    **Returns:**
    - the XML version or null.


---

### getXMLObject()
- ~~getXMLObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)~~
  - : Reads a sub-tree of the XML document and parses it as XML object.
      
      
      The stream must be positioned on a START\_ELEMENT. Do not call the method
      when the stream is positioned at document's root element. This would
      cause the whole document to be parsed into a single XML what may lead to
      an out-of-memory condition. Instead use \#next() to navigate to
      sub-elements and invoke getXMLObject() there. Do not keep references to
      more than the currently processed XML to keep memory consumption low. The
      method reads the stream up to the matching END\_ELEMENT. When the method
      returns the current event is the END\_ELEMENT event.


    **Deprecated:**
**warning:** Use [readXMLObject()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md#readxmlobject)

---

### hasName()
- hasName(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the current event has a name (is a START\_ELEMENT or END\_ELEMENT)

    **Returns:**
    - true if the current event has a name, false otherwise.


---

### hasNext()
- hasNext(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Returns true if there are more parsing events and false
      if there are no more events.  This method will return
      false if the current state of the XMLStreamReader is
      END\_DOCUMENT


    **Returns:**
    - true if there are more events, false otherwise


---

### hasText()
- hasText(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Indicates if the current event has text.
      The following events have text:
      CHARACTERS,DTD ,ENTITY\_REFERENCE, COMMENT, SPACE.


    **Returns:**
    - true if the current event has text, false otherwise.


---

### isAttributeSpecified(Number)
- isAttributeSpecified(index: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if this
      attribute was created by default.


    **Parameters:**
    - index - the position of the attribute.

    **Returns:**
    - true if this is a default attribute, false otherwise.


---

### isCharacters()
- isCharacters(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cursor points to a character data event.

    **Returns:**
    - true if the cursor points to character data, false otherwise.


---

### isEndElement()
- isEndElement(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cursor points to an end tag.

    **Returns:**
    - true if the cursor points to an end tag, false otherwise.


---

### isStandalone()
- isStandalone(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Get the standalone declaration from the xml declaration.

    **Returns:**
    - true if this is standalone, or false otherwise.


---

### isStartElement()
- isStartElement(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cursor points to a start tag.

    **Returns:**
    - true if the cursor points to a start tag, false otherwise.


---

### isWhiteSpace()
- isWhiteSpace(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if the cursor points to a character data event
      that consists of all whitespace.


    **Returns:**
    - true if the cursor points to all whitespace, false otherwise.


---

### next()
- next(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Get next parsing event - a processor may return all contiguous
      character data in a single chunk, or it may split it into several chunks.
      If the property javax.xml.stream.isCoalescing is set to true
      element content must be coalesced and only one CHARACTERS event
      must be returned for contiguous element content or
      CDATA Sections.
      
      By default entity references must be
      expanded and reported transparently to the application.
      An exception will be thrown if an entity reference cannot be expanded.
      If element content is empty (i.e. content is "") then no CHARACTERS event will be reported.
      
      
      Given the following XML:
      
      <foo><!--description-->content text<!&#91;CDATA&#91;<greeting>Hello</greeting>&#93;&#93;>other content</foo>
      
      The behavior of calling next() when being on foo will be:
      
      1- the comment (COMMENT)
      
      2- then the characters section (CHARACTERS)
      
      3- then the CDATA section (another CHARACTERS)
      
      4- then the next characters section (another CHARACTERS)
      
      5- then the END\_ELEMENT
      
      
      
      **NOTE:** empty element (such as <tag/>) will be reported
       with  two separate events: START\_ELEMENT, END\_ELEMENT - This preserves
        parsing equivalency of empty element to <tag></tag>.
      
      This method will throw an IllegalStateException if it is called after hasNext() returns false.


    **Returns:**
    - the integer code corresponding to the current parse event


---

### nextTag()
- nextTag(): [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)
  - : Skips any white space (isWhiteSpace() returns true), COMMENT,
      or PROCESSING\_INSTRUCTION,
      until a START\_ELEMENT or END\_ELEMENT is reached.
      If other than white space characters, COMMENT, PROCESSING\_INSTRUCTION, START\_ELEMENT, END\_ELEMENT
      are encountered, an exception is thrown. This method should
      be used when processing element-only content separated by white space.
      
      
       Precondition: none
      
       Postcondition: the current event is START\_ELEMENT or END\_ELEMENT
      and cursor may have moved over any whitespace event.
      
      
      Essentially it does the following (implementations are free to optimized
      but must do equivalent processing):
      
      
      ```
      int eventType = next();
      while ( (eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace() )
            || (eventType == XMLStreamConstants.CDATA && isWhiteSpace())
            || eventType == XMLStreamConstants.SPACE
            || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
            || eventType == XMLStreamConstants.COMMENT )
      {
          eventType = next();
      }
      if ( eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT )
      {
          throw new String XMLStreamException( "expected start or end tag", getLocation() );
      }
      return eventType;
      ```


    **Returns:**
    - the event type of the element read (START\_ELEMENT or END\_ELEMENT)


---

### readElementText()
- readElementText(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Reads the content of a text-only element, an exception is thrown if this is not a text-only element. This method
      always returns coalesced content. 
      
      Precondition: the current event is START\_ELEMENT. 
      
      Postcondition: the current event is the corresponding END\_ELEMENT. 
      
      The method does the following (implementations are free to be optimized but must do equivalent processing):
      
      
      ```
      if ( getEventType() != XMLStreamConstants.START_ELEMENT )
      {
          throw new XMLStreamException( "parser must be on START_ELEMENT to read next text", getLocation() );
      }
      int eventType = next();
      StringBuffer content = new StringBuffer();
      while ( eventType != XMLStreamConstants.END_ELEMENT )
      {
          if ( eventType == XMLStreamConstants.CHARACTERS || eventType == XMLStreamConstants.CDATA
              || eventType == XMLStreamConstants.SPACE || eventType == XMLStreamConstants.ENTITY_REFERENCE )
          {
              buf.append( getText() );
          }
          else if ( eventType == XMLStreamConstants.PROCESSING_INSTRUCTION || eventType == XMLStreamConstants.COMMENT )
          {
              // skipping
          }
          else if ( eventType == XMLStreamConstants.END_DOCUMENT )
          {
              throw new XMLStreamException( "unexpected end of document when reading element text content", this );
          }
          else if ( eventType == XMLStreamConstants.START_ELEMENT )
          {
              throw new XMLStreamException( "element text content may not contain START_ELEMENT", getLocation() );
          }
          else
          {
              throw new XMLStreamException( "Unexpected event type " + eventType, getLocation() );
          }
          eventType = next();
      }
      return buf.toString();
      ```



---

### readXMLObject()
- readXMLObject(): [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - : Reads a sub-tree of the XML document and parses it as XML object.
      
      
      The stream must be positioned on a START\_ELEMENT. Do not call the method
      when the stream is positioned at document's root element. This would
      cause the whole document to be parsed into a single XML what may lead to
      an out-of-memory condition. Instead use \#next() to navigate to
      sub-elements and invoke getXMLObject() there. Do not keep references to
      more than the currently processed XML to keep memory consumption low. The
      method reads the stream up to the matching END\_ELEMENT. When the method
      returns the current event is the END\_ELEMENT event.



---

### require(Number, String, String)
- require(type: [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md), namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Test if the current event is of the given type and if the namespace and name match the current
      namespace and name of the current event.  If the namespaceURI is null it is not checked for equality,
      if the localName is null it is not checked for equality.


    **Parameters:**
    - type - the event type
    - namespaceURI - the uri of the event, may be null
    - localName - the localName of the event, may be null


---

### standaloneSet()
- standaloneSet(): [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)
  - : Identifies if standalone was set in the document.

    **Returns:**
    - true if standalone was set in the document, false otherwise.


---

<!-- prettier-ignore-end -->

<!-- document id=7c6763b0ad8a595adaf5a259b23697b960e344051c015dcc8251a751a78679ea url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.XMLStreamWriter.md -->

<!-- prettier-ignore-start -->
# Class XMLStreamWriter

- [TopLevel.Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)
  - [dw.io.XMLStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md)

The XMLStreamWriter can be used to write small and large XML feeds.


**Note:** when this class is used with sensitive data, be careful in persisting sensitive information to disk.



The XMLStreamWriter does not perform well-formedness checking on its input.
However the writeCharacters method escapes '&' , '<' and '>'. For attribute
values the writeAttribute method escapes the above characters plus '"' to
ensure that all character content and attribute values are well formed.


The following example illustrates how to use this class:


```
var fileWriter : FileWriter = new FileWriter(file, "UTF-8");
var xsw : XMLStreamWriter = new XMLStreamWriter(fileWriter);

xsw.writeStartDocument();
xsw.writeStartElement("products");
  xsw.writeStartElement("product");
  xsw.writeAttribute("id", "p42");
    xsw.writeStartElement("name");
      xsw.writeCharacters("blue t-shirt");
    xsw.writeEndElement();
    xsw.writeStartElement("rating");
      xsw.writeCharacters("2.0");
    xsw.writeEndElement();
  xsw.writeEndElement();
xsw.writeEndElement();
xsw.writeEndDocument();

xsw.close();
fileWriter.close();
```





The code above will write the following to file:


```
<?xml version="1.0" ?>
<products>
  <product id="p42">
    <name>a blue t-shirt</name>
    <rating>2.0</rating>
  </product>
</products>
```


Note:  This output has been formatted for readability. See
[XMLIndentingStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md).



## All Known Subclasses
[XMLIndentingStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md)
## Property Summary

| Property | Description |
| --- | --- |
| [defaultNamespace](#defaultnamespace): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md) | Returns the current default name space. |

## Constructor Summary

| Constructor | Description |
| --- | --- |
| [XMLStreamWriter](#xmlstreamwriterwriter)([Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)) | Constructs the XMLStreamWriter for a writer. |

## Method Summary

| Method | Description |
| --- | --- |
| [close](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#close)() | Close this writer and free any resources associated with the  writer. |
| [flush](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#flush)() | Write any cached data to the underlying output mechanism. |
| [getDefaultNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#getdefaultnamespace)() | Returns the current default name space. |
| [getPrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#getprefixstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Gets the prefix the URI is bound to. |
| [setDefaultNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#setdefaultnamespacestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Binds a URI to the default namespace. |
| [setPrefix](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#setprefixstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Sets the prefix the uri is bound to. |
| [writeAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeattributestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an attribute to the output stream without  a prefix. |
| [writeAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeattributestring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an attribute to the output stream. |
| [writeAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeattributestring-string-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an attribute to the output stream. |
| [writeCData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writecdatastring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes a CData section. |
| [writeCharacters](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writecharactersstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Write text to the output. |
| [writeComment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writecommentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an XML comment with the data enclosed. |
| [writeDTD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writedtdstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Write a DTD section. |
| [writeDefaultNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writedefaultnamespacestring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes the default namespace to the stream. |
| [writeEmptyElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeemptyelementstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an empty element tag to the output. |
| [writeEmptyElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeemptyelementstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an empty element tag to the output. |
| [writeEmptyElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeemptyelementstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an empty element tag to the output. |
| [writeEndDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeenddocument)() | Closes any start tags and writes corresponding end tags. |
| [writeEndElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeendelement)() | Writes an end tag to the output relying on the internal  state of the writer to determine the prefix and local name  of the event. |
| [writeEntityRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeentityrefstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes an entity reference. |
| [writeNamespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writenamespacestring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes a namespace to the output stream. |
| [writeProcessingInstruction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeprocessinginstructionstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes a processing instruction. |
| [writeProcessingInstruction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writeprocessinginstructionstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes a processing instruction. |
| [writeRaw](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writerawstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes the given string directly into the output stream. |
| [writeStartDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartdocument)() | Write the XML Declaration. |
| [writeStartDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartdocumentstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Write the XML Declaration. |
| [writeStartDocument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartdocumentstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Write the XML Declaration. |
| [writeStartElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartelementstring)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes a start tag to the output. |
| [writeStartElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartelementstring-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes a start tag to the output. |
| [writeStartElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md#writestartelementstring-string-string)([String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)) | Writes a start tag to the output. |

### Methods inherited from class Object

[assign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#assignobject-object), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject), [create](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#createobject-object), [defineProperties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertiesobject-object), [defineProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#definepropertyobject-object-object), [entries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#entriesobject), [freeze](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#freezeobject), [fromEntries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#fromentriesiterable), [getOwnPropertyDescriptor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertydescriptorobject-object), [getOwnPropertyNames](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertynamesobject), [getOwnPropertySymbols](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getownpropertysymbolsobject), [getPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#getprototypeofobject), [hasOwnProperty](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#hasownpropertystring), [is](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isobject-object), [isExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isextensibleobject), [isFrozen](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isfrozenobject), [isPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#isprototypeofobject), [isSealed](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#issealedobject), [keys](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#keysobject), [preventExtensions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#preventextensionsobject), [propertyIsEnumerable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#propertyisenumerablestring), [seal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#sealobject), [setPrototypeOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#setprototypeofobject-object), [toLocaleString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tolocalestring), [toString](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#tostring), [valueOf](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valueof), [values](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md#valuesobject)
## Property Details

### defaultNamespace
- defaultNamespace: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current default name space.


---

## Constructor Details

### XMLStreamWriter(Writer)
- XMLStreamWriter(writer: [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md))
  - : Constructs the XMLStreamWriter for a writer.

    **Parameters:**
    - writer - the writer for which the XMLStreamWriter is constructed.


---

## Method Details

### close()
- close(): void
  - : Close this writer and free any resources associated with the
      writer.  This method does not close the underlying writer.



---

### flush()
- flush(): void
  - : Write any cached data to the underlying output mechanism.


---

### getDefaultNamespace()
- getDefaultNamespace(): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Returns the current default name space.

    **Returns:**
    - the current default name space.


---

### getPrefix(String)
- getPrefix(uri: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)
  - : Gets the prefix the URI is bound to.

    **Parameters:**
    - uri - the URI to use.

    **Returns:**
    - the prefix or null.


---

### setDefaultNamespace(String)
- setDefaultNamespace(uri: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Binds a URI to the default namespace.
      This URI is bound
      in the scope of the current START\_ELEMENT / END\_ELEMENT pair.
      If this method is called before a START\_ELEMENT has been written
      the uri is bound in the root scope.


    **Parameters:**
    - uri - the uri to bind to the default namespace, may be null.


---

### setPrefix(String, String)
- setPrefix(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), uri: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Sets the prefix the uri is bound to.  This prefix is bound
      in the scope of the current START\_ELEMENT / END\_ELEMENT pair.
      If this method is called before a START\_ELEMENT has been written
      the prefix is bound in the root scope.


    **Parameters:**
    - prefix - the prefix to bind to the uri, may not be null.
    - uri - the uri to bind to the prefix, may be null.


---

### writeAttribute(String, String)
- writeAttribute(localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an attribute to the output stream without
      a prefix.


    **Parameters:**
    - localName - the local name of the attribute.
    - value - the value of the attribute.


---

### writeAttribute(String, String, String)
- writeAttribute(namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an attribute to the output stream.

    **Parameters:**
    - namespaceURI - the uri of the prefix for this attribute.
    - localName - the local name of the attribute.
    - value - the value of the attribute.


---

### writeAttribute(String, String, String, String)
- writeAttribute(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), value: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an attribute to the output stream.

    **Parameters:**
    - prefix - the prefix for this attribute.
    - namespaceURI - the uri of the prefix for this attribute.
    - localName - the local name of the attribute.
    - value - the value of the attribute.


---

### writeCData(String)
- writeCData(data: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes a CData section.

    **Parameters:**
    - data - the data contained in the CData Section, may not be null.


---

### writeCharacters(String)
- writeCharacters(text: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Write text to the output.

    **Parameters:**
    - text - the value to write.


---

### writeComment(String)
- writeComment(data: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an XML comment with the data enclosed.

    **Parameters:**
    - data - the data contained in the comment, may be null.


---

### writeDTD(String)
- writeDTD(dtd: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Write a DTD section.  This string represents the entire doctypedecl production
      from the XML 1.0 specification.


    **Parameters:**
    - dtd - the DTD to be written.


---

### writeDefaultNamespace(String)
- writeDefaultNamespace(namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes the default namespace to the stream.

    **Parameters:**
    - namespaceURI - the uri to bind the default namespace to.


---

### writeEmptyElement(String)
- writeEmptyElement(localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an empty element tag to the output.

    **Parameters:**
    - localName - local name of the tag, may not be null.


---

### writeEmptyElement(String, String)
- writeEmptyElement(namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an empty element tag to the output.

    **Parameters:**
    - namespaceURI - the uri to bind the tag to, may not be null.
    - localName - local name of the tag, may not be null.


---

### writeEmptyElement(String, String, String)
- writeEmptyElement(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an empty element tag to the output.

    **Parameters:**
    - prefix - the prefix of the tag, may not be null.
    - localName - local name of the tag, may not be null.
    - namespaceURI - the uri to bind the tag to, may not be null.


---

### writeEndDocument()
- writeEndDocument(): void
  - : Closes any start tags and writes corresponding end tags.


---

### writeEndElement()
- writeEndElement(): void
  - : Writes an end tag to the output relying on the internal
      state of the writer to determine the prefix and local name
      of the event.



---

### writeEntityRef(String)
- writeEntityRef(name: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes an entity reference.

    **Parameters:**
    - name - the name of the entity.


---

### writeNamespace(String, String)
- writeNamespace(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes a namespace to the output stream.
      If the prefix argument to this method is the empty string,
      "xmlns", or null this method will delegate to writeDefaultNamespace.


    **Parameters:**
    - prefix - the prefix to bind this namespace to.
    - namespaceURI - the uri to bind the prefix to.


---

### writeProcessingInstruction(String)
- writeProcessingInstruction(target: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes a processing instruction.

    **Parameters:**
    - target - the target of the processing instruction, may not be null.


---

### writeProcessingInstruction(String, String)
- writeProcessingInstruction(target: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), data: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes a processing instruction.

    **Parameters:**
    - target - the target of the processing instruction, may not be null.
    - data - the data contained in the processing instruction, may not be null.


---

### writeRaw(String)
- writeRaw(raw: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes the given string directly into the output stream. No checks
      regarding the correctness of the XML are done. The caller must ensure
      that the final result is a correct XML.


    **Parameters:**
    - raw - the string to write to the output stream.


---

### writeStartDocument()
- writeStartDocument(): void
  - : Write the XML Declaration. Defaults the XML version to 1.0, and the encoding to utf-8


---

### writeStartDocument(String)
- writeStartDocument(version: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Write the XML Declaration. Defaults the XML version to 1.0

    **Parameters:**
    - version - version of the xml document.


---

### writeStartDocument(String, String)
- writeStartDocument(encoding: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), version: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Write the XML Declaration.  Note that the encoding parameter does
      not set the actual encoding of the underlying output.  That must
      be set when the instance of the XMLStreamWriter is created using the
      XMLOutputFactory.


    **Parameters:**
    - encoding - encoding of the xml declaration.
    - version - version of the xml document.


---

### writeStartElement(String)
- writeStartElement(localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes a start tag to the output.  All writeStartElement methods
      open a new scope in the internal namespace context.  Writing the
      corresponding EndElement causes the scope to be closed.


    **Parameters:**
    - localName - local name of the tag, may not be null.


---

### writeStartElement(String, String)
- writeStartElement(namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes a start tag to the output.

    **Parameters:**
    - namespaceURI - the namespaceURI of the prefix to use, may not be null.
    - localName - local name of the tag, may not be null.


---

### writeStartElement(String, String, String)
- writeStartElement(prefix: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), localName: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md), namespaceURI: [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)): void
  - : Writes a start tag to the output.

    **Parameters:**
    - prefix - the prefix of the tag, may not be null.
    - localName - local name of the tag, may not be null.
    - namespaceURI - the uri to bind the prefix to, may not be null.


---

<!-- prettier-ignore-end -->

<!-- document id=5278eac6375cc84279130b703967ab3217f62687b638b90cca1a432c0db2ed43 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/client-ip-forwarding.md -->

# Client IP Forwarding

Forwarding Client IPs to the B2C Commerce platform is a prerequisite for services such as geolocation. You can use any of the following options to pass shopper client IPs to the B2C Commerce platform.

In Custom API implementations and hooks, access the client IP using the Script API method [Request.getRemoteAddress()](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_Request.html#dw_system_Request_getHttpRemoteAddress_DetailAnchor).
**note:** This method only works correctly if one of the following options (either Shopper Context or Request Header) is implemented.

## Shopper Context

You can use the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) API to pass a client IP to the B2C Commerce Platform. The [client IP can be stored](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-geolocation.html#retrieve-geolocation-with-client-ip-address-and-use-for-subsequent-requests) in the shopper profile and used in subsequent requests.

## Request Header

In **Business Manager > {Your-Site} >** **Merchant Tools** > **SEO** > **Customer CDN Settings**, in the **Dynamic Content** section, configure the _Client IP Header Name_ field. For each request the B2C Commerce API will use this setting to retrieve the client IP address from the request header instead of the CDN network connection source address. If the request header isn't provided, the CDN connection source address will be used.

**note:** - If both options are used, Shopper Context takes precedence.

<!-- document id=a656e1da64cf50e9e070be5dd76f08afb9e63f05a701ab3ae31e4775354ac49e url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-payment-clientside-setup.md -->

# Client-Side Payment Processing Flow

With client-side payment processing, you create a checkout UI component that interacts directly with a payment provider. You also implement a payment adapter that independently validates transactions.

Create your store and configure checkout before you set up your payment system.

**note:** Among the benefits of the client-side integration model is PCI compliance and security. Isolating the handling of sensitive payment data in a cross-domain UI component owned by the payment provider means much of the PCI burden is on the provider.

Similar to a server side integration, a client side integration requires creating a PaymentGatewayAdapter but with these differences:

- The adapter implements a PostAuth request to validate the transaction. The PostAuth request type ensures that the provided payment authorization token is valid. The client calls the Checkout Payment API with the requestType PostAuth, which in turn invokes the adapter with a commercepayments.PostAuthorizationRequest. That request provides the adapter with the amount, currency code, and payment token.  The adapter can then use this data to validate the transaction and provide a response..
- A custom Checkout UI component (which may wrap or adapt a payment provider component).
- A server-side call to fetch keys or configurations required to load the Checkout UI component. You use a standard Salesforce Apex Controller to bootstrap the client component.

A payment provider client typically manages the authorization and tokenization functions. In that case, the [Commerce Payment Connect APIs](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_payments.htm) required for client-side implementation are:

- Capture
- ReferencedRefund
- AuthorizationReversal
- PostAuth

The diagram depicts a high level view of a typical client-side integration.

![Diagram of Client-side payment flow.](https://developer.salesforce.com/media/d2c-commerce/clientside_payment_flow.png)When a shopper clicks Place Order:

1.  a. The Client Payment Controller initiates a payment transaction with the Payment Apex Controller and 1. b. The Payment Apex Controller initiates a transaction with the Payment Gateway.

2.  The Client posts an authenticated and tokenized transaction to the Payment Gateway This is the client-to-gateway transaction that gives client side payments its name. Typically this is done with payment provider-built UI components.

3.  a. The UI client component calls the Checkout payment API with a requestType of PostAuth to validate the transaction and 3. b. The Apex Payment Adapter processes the PostAuth request, fetching the transaction details - including currency code, amount and account ID - from the gateway for verification. (See [ConnectApi.PostAuthorizeRequest](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_connectapi_input_post_auth.htm). ) The Apex implementation then returns the gateway auth code, gateway result code, Salesforce result code and the amount. If the payment is asynchronous and can’t be fully confirmed at 3. b, see [Create a Custom Payment Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-integrate-payment-lwc.md).

4.  In an asynchronous implementation, the Payment Gateway issues a web hook notification to affirm the transaction.

To implement client-side payment processing, see

- [Create a Custom Payment Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-integrate-payment-lwc.md)
- [Customize a Checkout Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-checkout-component.md)
- [Payment Gateway Adapters](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_adapter_intro.htm)
- [Connect a Payment Gateway to Store Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-connect-gateway.md)

**See Also**

- [_Apex Reference Guide_: Payment Gateway Adapters](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_adapter_intro.htm)

<!-- document id=3204e11f0797defb8472c5d390eb7648f1b2f053968c362cf7c6285a1b475135 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/clienteling-spi.md -->

Clienteling SPI

# Clienteling SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/clienteling-spi/clienteling-spi-oas-public.yaml)

Merchant SPI to create, search, and retrieve customers from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in Point of Sale (POS) CMS for the POS to use during clienteling operations. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

**Version:** 2.3.4

## Tags

### Clienteling SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/clienteling-spi/clienteling-spi-oas-public.yaml)

Merchant SPI to create, search, and retrieve customers from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in Point of Sale (POS) CMS for the POS to use during clienteling operations. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

## Operations

### GET Search and retrieve customers.

`GET /merchant/spi/sample/endpoint/sa/customers`

Operation ID: `searchCustomers`. Tags: Clienteling SPI.

Search and retrieve customers based on input parameters. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Parameters

*   `start` (query, integer (int32))  
    Default: `0`.
*   `count` (query, integer (int32))  
    Default: `20`.
*   `firstName` (query, string)
*   `lastName` (query, string)
*   `phone` (query, string)
*   `email` (query, string)
*   `id` (query, string)
*   `postalCode` (query, string)
*   `searchString` (query, string)
*   `countryCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SearchCustomersResponse`.
    

### PUT Update customer.

`PUT /merchant/spi/sample/endpoint/sa/customers`

Operation ID: `updateCustomer`. Tags: Clienteling SPI.

Update the existing customer. The existing customerId is provided under 'profile.customerId'. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Request body

Media type: `application/json`. Schema: `UpdateCustomerRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UpdateCustomerResponse`.
    

### POST Create customer.

`POST /merchant/spi/sample/endpoint/sa/customers`

Operation ID: `createCustomer`. Tags: Clienteling SPI.

Create customer based on customer data entered in POS. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Request body

Media type: `application/json`. Schema: `CreateCustomerRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CreateCustomerResponse`.
    

### GET Retrieve customer details.

`GET /merchant/spi/sample/endpoint/sa/customers/{customerId}`

Operation ID: `getCustomer`. Tags: Clienteling SPI.

Retrieve customer data based on customer ID. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Parameters

*   `customerId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `GetCustomerResponse`.
    

## Schemas

### SearchCustomersResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `customers` (_array of CustomerData_, nullable) List of Customers.
*   `associateSessionId` (_string_, nullable) Store associate session ID.
*   `error` (_boolean_)

### UpdateCustomerRequest

*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable, deprecated) Deprecated. Not supported in create or update customer requests. Use profile.address instead. To add additional addresses, use the Customer Address SPI (CREATE\_CUSTOMER\_ADDRESS or UPDATE\_CUSTOMER\_ADDRESS). The complete address collection is returned in responses only.
*   `consents` (_Consents_)
*   `storeAttribution` (_SpiStoreAttribution_)
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)

### UpdateCustomerResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system, contains the complete address collection, including the primary address from profile.address.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)
*   `error` (_boolean_)

### CreateCustomerRequest

*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable, deprecated) Deprecated. Not supported in create or update customer requests. Use profile.address instead. To add additional addresses, use the Customer Address SPI (CREATE\_CUSTOMER\_ADDRESS or UPDATE\_CUSTOMER\_ADDRESS). The complete address collection is returned in responses only.
*   `consents` (_Consents_)
*   `storeAttribution` (_SpiStoreAttribution_)

### CreateCustomerResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system, contains the complete address collection, including the primary address from profile.address.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)
*   `error` (_boolean_)

### GetCustomerResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `sessionId` (_string_) Active session ID.
*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system: contains the complete address collection, including the primary address from profile.address.
*   `cartProductList` (_array of ClientelingCartProduct_, nullable) List of products saved in customer cart.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)
*   `error` (_boolean_)

### CustomerData

List of Customers.

*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_) Customer's addresses.
*   `cartProductList` (_array of ClientelingCartProduct_) Wish list or products from customer's abandoned cart.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### Consents

Consents for different types of sign ups.

*   `smsSignUp` (_boolean_, nullable) Consent for SMS signup.
*   `newsLetterSignUp` (_boolean_, nullable) Consent for news letter signup.
*   `agreeToTC` (_boolean_, nullable) Consent for terms and conditions.
*   `directMailSignUp` (_boolean_, nullable) Consent for direct mail signup.
*   `phoneSignUp` (_boolean_, nullable) Consent for phone signup.
*   `loyaltySignUp` (_boolean_, nullable) Consent for loyalty signup.
*   `eReceipt` (_boolean_, nullable) Consent for eReceipt signup.

### SpiStoreAttribution

Store ID and associate details of created customer.

*   `storeAssociateId` (_string_, nullable) ID of the store associate who creates customer account and rings the transaction.
*   `storeId` (_string_, nullable) Store Id.

### CustomerLoyaltyProfile

The loyalty profile of the customer if they are enrolled in Loyalty program.

*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `firstName` (_string_) Customer's first name.
*   `lastName` (_string_) Customer's last name.
*   `accountNumber` (_string_) Customer's loyalty account number.
*   `loyaltyStatusCode` (_string_, nullable) Customer's loyalty status code.
*   `currentPoints` (_integer (int32)_, nullable) Customer's current loyalty points. If provided, it will be used for validation against the individual reward points (If points are sent in reward).
*   `currentStoreCredit` (_number (double)_, nullable) Customer's current store credit.
*   `lifetimePoints` (_integer (int32)_, nullable) Loyalty point accumulated so far by the customer.
*   `nextRewardPoints` (_integer (int32)_, nullable) Loyalty point eligible for next reward cycle.
*   `transactions` (_Transactions_)
*   `rewards` (_array of Reward_, nullable) Earned rewards.
*   `tierLevelLabel` (_string_, nullable) Customer's tier level label.
*   `tierLevelValue` (_string_, nullable) Customer's tier level value.
*   `tierLevelCode` (_string_, nullable) Customer's tier level code.
*   `redemptionType` (_string_)
*   `internalMemberId` (_string_, nullable) Customer's internal member ID.
*   `homePhoneNumber` (_string_, nullable) Customer's home phone number.
*   `mobilePhoneNumber` (_string_, nullable) Customer's mobile phone number.
*   `address` (_Address_)
*   `currentTier` (_Tier_)
*   `nextTier` (_Tier_)
*   `customLoyaltyAttributes` (_CustomAttributes_)
*   `totalRewardsAmount` (_number_, nullable) Total amount value of all the rewards available for the customer. If provided, this will be used for validation when applying the individual rewards.
*   `loyaltyIdBarCodeType` (_string_)

### ClientelingCartProduct

Summary of a product line in the customer's saved cart. Current implementation only supports productId as the details are fetched from the product catalog.

*   `productId` (_string_, required) Product / SKU identifier of the product.

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### Transactions

Loyalty transactions.

*   `nextStartMonth` (_integer (int32)_)
*   `txnActivity` (_array of TransactionActivity_)

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### Tier

Customer's next tier details.

*   `name` (_string_) Tier name.
*   `minPoints` (_number_) Minimum points required for the tier.
*   `display` (_string_)
*   `points` (_integer (int32)_)
*   `memberSince` (_integer (int64)_) Member since, of this tier.
*   `title` (_string_)
*   `subTitle` (_string_)
*   `imageUrl` (_string_)
*   `expiryDate` (_integer (int64)_) Expiry date of the customer's membership.

### CustomAttributes

Custom attributes.

*   `customLabel` (_string_)
*   `customValues` (_array of CustomValue_)

### TransactionActivity

*   `orderId` (_string_)
*   `date` (_integer (int64)_)
*   `description` (_string_)
*   `points` (_integer (int32)_)
*   `amount` (_number_)
*   `pointStatus` (_string_)  
    Allowed values: `EARNED`, `PENDING`, `REWARD`, `REDEEMED`.
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    

### CustomValue

*   `laabel` (_string_)
*   `value` (_string_)
*   `iconType` (_string_)

<!-- document id=4ecb16311cc358f5b73f66a030fcae75cd77425881f56ea679b4a91e518e5b4b url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/clienteling-spi-field-mapping.md -->

# Clienteling SPI Field Mapping

Use the Clienteling SPI to create, search, update, and retrieve details of a specific customer. This guide summarizes how Clienteling SPI fields map to customer-related information tags. For specification details, see [Clienteling SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/clienteling-spi?meta=Summary).

<!-- Paul (8-19-25): Have to fix the link in the following paragraph, commenting out for now.

For more information on tags, please read [PS Tags](https://developer.salesforce.com/docs/commerce/cms-layouts-ux/tags/print-tags-configuration.md). -->

For more information on tags, read PS Tags.

| **PS Tag on Layout**              | **Backend SPI Field**                                                                                                                                                                                                                          | **CMS Grouping**     |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| :ps_salutation                    | profile.salutation                                                                                                                                                                                                                             | User Profile         |
| :ps_customer_name                 | profile.firstName & profile.lastName                                                                                                                                                                                                           | User Profile         |
| :ps_first_name                    | profile.firstName                                                                                                                                                                                                                              | User Profile         |
| :ps_last_name                     | profile.lastName                                                                                                                                                                                                                               | User Profile         |
| :ps_email                         | profile.email                                                                                                                                                                                                                                  | User Profile         |
| :ps_gender                        | profile.gender                                                                                                                                                                                                                                 | User Profile         |
| :ps_customer_phone                | profile.phoneMobile                                                                                                                                                                                                                            | User Profile         |
| :ps_profile_home_phone_number     | profile.phoneHome **Note:** "If configuring this field on any clienteling layouts, the "profile.phoneHome" field should be configured in NetSuite. Alternatively, you can map it to the **phone** attribute in NetSuite using "profile.phone". | User Profile         |
| :ps_birthday                      | profile.birthday                                                                                                                                                                                                                               | User Profile         |
| :ps_profile_city                  | profile.address.city                                                                                                                                                                                                                           | User Profile         |
| :ps_profile_country_code          | profile.address.countryCode                                                                                                                                                                                                                    | User Profile         |
| :ps_profile_preferred_language    | profile.preferredLanguage                                                                                                                                                                                                                      | User Profile         |
| :ps_customer_tax_id               | profile.taxInfo.taxId                                                                                                                                                                                                                          | User Profile         |
| :ps_alternate_customer_id         | profile.alternateCustomerId                                                                                                                                                                                                                    | User Profile         |
| :ps_num_orders_completed          | orderCount                                                                                                                                                                                                                                     | User Profile         |
| :ps_num_addresses                 | addressList                                                                                                                                                                                                                                    | User Profile         |
| :ps_num_orders_placed             | orderList                                                                                                                                                                                                                                      | User Profile         |
| :ps_num_payment_cards             | cardList                                                                                                                                                                                                                                       | User Profile         |
| :ps_num_wishlist_products         | products                                                                                                                                                                                                                                       | User Profile         |
| :ps_profile_addressline1          | profile.address.addressLine1                                                                                                                                                                                                                   | User Profile         |
| :ps_profile_addressline2          | profile.address.addressLine2                                                                                                                                                                                                                   | User Profile         |
| :ps_profile_city                  | profile.address.city                                                                                                                                                                                                                           | User Profile         |
| :ps_profile_state                 | profile.address.state                                                                                                                                                                                                                          | User Profile         |
| :ps_profile_zip                   | profile.address.postalCode                                                                                                                                                                                                                     | User Profile         |
| :ps_profile_country               | profile.address.countryCode                                                                                                                                                                                                                    | User Profile         |
| :ps_profile_address_phone_number  | profile.phoneMobile                                                                                                                                                                                                                            | User Profile         |
| consents.newsLetterSignUp         | consents.newsLetterSignUp                                                                                                                                                                                                                      | Form Field           |
| consents.eReceipt                 | consents.eReceipt                                                                                                                                                                                                                              | Form Field           |
| consents.smsSignUp                | consents.smsSignUp                                                                                                                                                                                                                             | Form Field           |
| consents.agreeToTC                | consents.agreeToTC                                                                                                                                                                                                                             | Form Field           |
| consents.directMailSignUp         | consents.directMailSignUp                                                                                                                                                                                                                      | Form Field           |
| consents.phoneSignUp              | consents.phoneSignUp                                                                                                                                                                                                                           | Form Field           |
| consents.loyaltySignUp            | consents.loyaltySignUp                                                                                                                                                                                                                         | Form Field           |
| :ps_total_store_credit            | loyaltyProfile.currentStoreCredit                                                                                                                                                                                                              | User Loyalty Profile |
| :ps_current_loyalty_tier_name     | loyaltyProfile.currentTier.name                                                                                                                                                                                                                | User Loyalty Profile |
| :ps_current_loyalty_tier_title    | loyaltyProfile.currentTier.title                                                                                                                                                                                                               | User Loyalty Profile |
| :ps_current_loyalty_tier_subtitle | loyaltyProfile.currentTier.subTitle                                                                                                                                                                                                            | User Loyalty Profile |
| :ps_current_reward_points         | loyaltyProfile.currentPoints                                                                                                                                                                                                                   | User Loyalty Profile |
| :ps_current_tier_date             | loyaltyProfile.currentTier.memberSince                                                                                                                                                                                                         | User Loyalty Profile |
| :ps_current_tier_expiry_date      | loyaltyProfile.currentTier.expiryDate                                                                                                                                                                                                          | User Loyalty Profile |
| :ps_current_loyalty_tier_display  | loyaltyProfile.currentTier.display                                                                                                                                                                                                             | User Loyalty Profile |
| :ps_next_loyalty_tier_display     | loyaltyProfile.nextTier.display                                                                                                                                                                                                                | User Loyalty Profile |
| :ps_next_loyalty_tier_name        | loyaltyProfile.nextTier.name                                                                                                                                                                                                                   | User Loyalty Profile |
| :ps_next_loyalty_tier_title       | loyaltyProfile.nextTier.title                                                                                                                                                                                                                  | User Loyalty Profile |
| :ps_total_points                  | loyaltyProfile.lifetimePoints                                                                                                                                                                                                                  | User Loyalty Profile |
| :ps_loyalty_custom                | loyaltyProfile.customAttributes                                                                                                                                                                                                                | User Loyalty Profile |
| :ps_account_number                | loyaltyProfile.accountNumber                                                                                                                                                                                                                   | User Loyalty Profile |
| :ps_num_cash_rewards              | loyaltyProfile.cashRewards                                                                                                                                                                                                                     | User Loyalty Profile |
| :ps_points_to_next_tier           | loyaltyProfile.nextTier.points - loyaltyProfile.lifetimePoints                                                                                                                                                                                 | User Loyalty Profile |
| :ps_num_rewards                   | loyaltyProfile.rewards                                                                                                                                                                                                                         | User Loyalty Profile |
| :ps_current_credits               | loyaltyProfile.currentStoreCredit                                                                                                                                                                                                              | User Loyalty Profile |
| :ps_points_to_next_reward         | loyaltyProfile.nextRewardPoints - loyaltyProfile.currentPoints                                                                                                                                                                                 | User Loyalty Profile |
| :ps_num_rewards_total             | loyaltyProfile.rewards.amount                                                                                                                                                                                                                  | User Loyalty Profile |
| :ps_num_rewards_total_2           | Sum of loyaltyProfile.rewards[].amount and if loyaltyProfile.rewards.status                                                                                                                                                                    | User Loyalty Profile |
| :ps_num_rewards_total_2_no_dec    | Sum of loyaltyProfile.rewards[].amount and if loyaltyProfile.rewards.status = AVAILABLE                                                                                                                                                        | User Loyalty Profile |
| :ps_num_cash_rewards_total_no_dec | Sum of loyaltyProfile.cashRewards.amount if loyaltyProfile.cashRewards.status = AVAILABLE                                                                                                                                                      | User Loyalty Profile |
| :ps_num_cash_rewards_total        | Sum of loyaltyProfile.cashRewards.amount                                                                                                                                                                                                       | User Loyalty Profile |
| :ps_club_contact_id               | loyaltyProfile.accountNumber OR loyaltyProfile.loyaltyId                                                                                                                                                                                       | Wine Loyalty         |
| :ps_club_id                       | loyaltyProfile.tierLevelValue                                                                                                                                                                                                                  | Wine Loyalty         |
| :ps_club_membership_id            | loyaltyProfile.loyaltyId                                                                                                                                                                                                                       | Wine Loyalty         |
| :ps_club_name                     | loyaltyProfile.currentTier.name                                                                                                                                                                                                                | Wine Loyalty         |
| :ps_profile_company               | profile.companyName                                                                                                                                                                                                                            | Wine Loyalty         |
| :ps_profile_title                 | loyaltyProfile.title                                                                                                                                                                                                                           | Wine Loyalty         |

<!-- document id=de92046d8fbbe71b0f0d4865455dc856e063a27d0b2e0ce6106d0ee0ec407e56 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/clienteling-spi-for-crm.md -->

# Clienteling SPI for CRM

Implementing the Clienteling SPI allows merchants to use their own system as the system of record for managing customer profiles, configuring Point of Sale to create, update, search, and retrieve customer profiles from the merchant system. This approach provides an alternative to using one of our standard connectors to a CRM (for example, Agentforce Service or Netsuite).

The Clienteling SPI has three prerequisites:

1. Merchant builds the SPI service for the endpoints (that is, for each clienteling operation to be supported)
2. Merchant configures the connector in CMS, specifying the details of the integration between Retail Cloud and the SPI endpoint you’ve built

3. Merchant configures the layouts in CMS. Layouts allow you to define a custom form for the POS that will take associate inputs and pass them as parameters in requests to the SPI endpoint

The Clienteling SPI supports four endpoints. See [Clienteling SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/clienteling-spi?meta=Summary) for detailed specifications for each endpoint.

| **Endpoint Name** | **Sample Endpoint**                 | **Method** | **Description**                                                                                                                                                                                                |
| ----------------- | ----------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CREATE_CUSTOMER   | /endpoint/sa/customers              | POST       | Create new customer profile based on customer data entered in POS.                                                                                                                                             |
| UPDATE_CUSTOMER   | /endpoint/sa/customers              | PUT        | Update existing customer by specifying values for the parameters passed. Customer parameters not provided in the request will be left unchanged. The specific customer to update is identified by customer ID. |
| SEARCH_CUSTOMERS  | /endpoint/sa/customers              | GET        | Search and retrieve customers previously created based on input parameters passed from POS.                                                                                                                    |
| GET_CUSTOMER      | /endpoint/sa/customers/{customerId} | GET        | Retrieve customer data based on provided customer ID.                                                                                                                                                          |

## Clienteling SPI and Associate Journey

Merchants can define which customer attributes are passed from the POS to the Clienteling SPI, specifying only the data they wish to track and maintain. For each clienteling operation, the data the associate collects are determined by the fields configured on the corresponding layout.

To better understand the Clienteling SPI, let's consider each endpoint, the specific associate journey that invokes it, the layout used to capture the customer information, and the presentation of data from the SPI response in the POS app.

### Customer Search

When a store associate searches for a customer, whether to add them to the cart during checkout or to view their profile during clienteling activities, the associate’s inputs in the Customer Search layout are passed to the SEARCH_CUSTOMERS endpoint.

See the below example of a Customer Search layout, presented as a full-page form when the associate taps the clienteling CTA (the "person" icon) in the top right corner of the home screen. Results retrieved from the SEARCH_CUSTOMERS endpoint's response are presented in a list view below the search form.

![mceclip9.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip9.png)

Selecting one of the profiles in the list will login that customer. When a customer is logged in, the customer's first name and profile photo are shown in the top right corner of the home screen.

![mceclip15.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip15.png)

### Create Customer

When a store associate creates a new customer profile, the fields in the Customer Signup layout are passed in a request to the CREATE_CUSTOMER endpoint. See the below example of a Customer Signup layout. Associates typically will access this layout when searching for a customer and finding no results or during checkout if they have not already logged a customer in for the cart.

![mceclip13.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip13.png)

### Retrieve Customer Profile

After logging in a customer, the associate can view the customer’s profile, and, as needed, make edits to the profile, which result in calls to the GET_CUSTOMER and UPDATE_CUSTOMER endpoints, respectively. The *View profile* CTA in the below screenshot will take the associate to the customer's profile.

![mceclip12.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip12.png)

<!-- Paul(8-19-25): Have to fix the link in the following paragraph, commenting out for now:

Below is an example of a Customer 360 layout, the customer's profile rendered with the details from the GET_CUSTOMER response. For more detail on setting up this layout, see: [Understanding & Configuring Customer 360°](https://developer.salesforce.com/docs/commerce/modern-pos-features/analytics-reporting/understanding-configuring-customer-360%C2%B0.md). -->

Below is an example of a Customer 360 layout, the customer's profile rendered with the details from the GET_CUSTOMER response. For more detail on setting up this layout, see: Understanding & Configuring Customer 360°.

![mceclip11.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip11.png)

### Update Customer Profile

An associate might update a customer's profile when acquiring new or updated information about a customer's preferences, location, contact details, and personal attributes. The Update Customer layout is typically a form with the same fields as the Customer Signup layout, pre-filled with the existing values against each customer profile attribute. The form is accessed via a deep link configured on the customer's profile. Upon making and submitting the desired edits, the associate will trigger a request to the UPDATE_CUSTOMER endpoint, and result in the specified changes to the customer's profile.

![mceclip4.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip4.png)

To summarize, the clienteling endpoints are invoked in the following POS flows:

| **Endpoint Name** | **Associate Journey on POS**                                                                                                                                                                                          | **Layout**                                                                                                                                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SEARCH_CUSTOMERS  | Associate performs a customer search to find an existing profile: <br>- Whether customer already logged in and changing to another profile, or none logged in <br>- Whether during checkout or clienteling activities | Customer Search                                                                                                                                                                                            |
| CREATE_CUSTOMER   | Create customer profile using New Customer Sign-up                                                                                                                                                                    | Customer Signup                                                                                                                                                                                            |
| GET_CUSTOMER      | Selecting a customer’s profile from the customer search results                                                                                                                                                       | Retrieving a customer’s details does not require a layout, but it’s important to have a clienteling profile layout so associates can view key attributes, order history, and loyalty status of a customer. |
| UPDATE_CUSTOMER   | Edit customer profile, for example, with Edit layout accessed from Customer 360                                                                                                                                       | Customer Signup                                                                                                                                                                                            |

**note:** When creating layouts for the above Clienteling operations, refer to [Clienteling SPI Field Mapping](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-field-mapping.html) for a complete mapping between the template tags you configure on the layout and the corresponding attributes of the objects exchanged with the SPI endpoint.

<!-- Paul (8-19-25): Have to fix the link in the following row, commenting out for now.

| SEARCH_CUSTOMERS  | Associate performs a customer search to find an existing profile: <br>- Whether customer already logged in and changing to another profile, or none logged in <br>- Whether during checkout or clienteling activities | [Customer Search](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-customer-search-layout.html)                                                                                                                                                                                                                                          | -->
<!-- Paul (8-19-25): Have to fix the link in the following row, commenting out for now.

| CREATE_CUSTOMER   | Create customer profile using New Customer Sign-up                                                                                                                                                                    | [Customer Signup](https://developer.salesforce.com/docs/commerce/cms-layouts-ux/layout-templates/new-customer-sign-up-layout.md)                                                                                                                                                                                                     | -->
<!-- Paul (8-19-25): Have to fix the link in the following row, commenting out for now.

| GET_CUSTOMER      | Selecting a customer’s profile from the customer search results                                                                                                                                                       | Retrieving a customer’s details does not require a layout, but it’s important to have a [clienteling profile](https://developer.salesforce.com/docs/commerce/cms-layouts-ux/layout-templates/clienteling-profile-layout-templates.md) layout so associates can view key attributes, order history, and loyalty status of a customer. | -->
<!-- Paul (8-19-25): Have to fix the link in the following row, commenting out for now.

| UPDATE_CUSTOMER   | Edit customer profile, for example, with Edit layout accessed from Customer 360                                                                                                                                              | [Customer Signup](https://developer.salesforce.com/docs/commerce/cms-layouts-ux/layout-templates/new-customer-sign-up-layout.md)                                                                                                                                                                                                     | -->

### Key Resources and Clienteling Data Model

In general, the core resource being exchanged in Clienteling workflows is the customer object, which comprises addresses, consents, customer profiles, and loyalty profiles.

```json
{
   addressList: [...],
   consents: [...],
   profile: [...],
   customerLoyaltyProfile: [...],
   storeAttribution: [...]
}
```

This object represents a shopper–their name and contact information, their addresses for billing and shipping, and many other attributes, including, whether they’ve consented to terms and conditions, marketing communications, and loyalty program enrollment.

For each parameter of the customer object, see the below for a summary overview:

| **Parameter**          | **Type**               | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| addressList            | Array of dictionaries  | Customer's list of Addresses used for billing and shipping. The Address object represents a customer address, typically for shipping, but also for billing, when applicable. It is passed as part of the Clienteling SPI endpoints’ addressList parameter, which is all shipping and billing addresses associated to a customer. It is also part of the Customer object, in profile.address and customerLoyaltyProfile.address.                                           |
| consents               | Dictionary of booleans | Customer consents. Child attributes:<br>• consents.agreeToTC<br>• consents.directMailSignUp<br>• consents.eReceipt<br>• consents.loyaltySignUp<br>• consents.newsLetterSignUp<br>• consents.phoneSignUp<br>• consents.smsSignUp                                                                                                                                                                                                                                           |
| profile                | Dictionary             | Customer profile object. Some of its child attributes are:<br>• address<br>• customerId<br>• email<br>• firstName<br>• postalCode<br>• customerGroup<br>• loyaltyId<br>• preferredLanguage<br>• country<br>• allowSmsNotifications<br><br>It encapsulates a customer’s personal and contact information, their loyalty ID, and other attributes. For order-related SPIs and webhooks, the profile object is used to exchange customer information associated with a sale. |
| customerLoyaltyProfile | Dictionary             | This object represents the customer loyalty profile, which is used if you are managing a customer loyalty program in Point of Sale. Some of its child attributes are:<br>• accountNumber<br>• address<br>• cashRewards<br>• currentPoints<br>• currentStoreCredit<br>• currentTier<br>• customLoyaltyAttributes<br>• firstName<br>• lastName                                                                                                                              |
| storeAttribution       | Dictionary             | This captures the store ID and ID of the associate who creates the customer account and completes the transaction.                                                                                                                                                                                                                                                                                                                                                        |

## Example Scenarios: SPI Requests and Responses in Practice

### Scenario 1: Create Customer Profile

In this scenario, a store associate completes and submits the Customer Signup layout for the shopper, triggering a POST request to the merchant’s CREATE_CUSTOMER SPI endpoint. A response with the new customer object is provided to the POS.

**Request**

```json
{
  "profile": {
    "email": "timothy@gmail.com",
    "firstName": "timothy",
    "lastName": "smith",
    "address": {
      "addressLine1": "111 Wilshire Boulevard",
      "addressLine2": "",
      "city": "Santa Monica",
      "state": "CA",
      "postalCode": "90401",
      "countryCode": "US",
      "preferred": false
    },
    "phoneMobile": ""
  },
  "consents": {
    "newsLetterSignUp": true,
    "loyaltySignUp": true
  },
  "storeAttribution": {
    "storeAssociateId": "as1",
    "storeId": "1920"
  }
}
```

**Response**

Note that the customer's identifying attributes (name, email, etc.) and address are added to the customer profile object under **customer.profile** and **customer.profile.address**, respectively. The customer's address is also added to **customer.loyaltyProfile.address** (because the customer consented to participating in the merchant's loyalty program) and to **customer.addressList**.

```json
{
  "loyaltyProfile": {
    "accountNumber": "12344",
    "address": {
      "addressId": "09999",
      "addressLine1": "111 Wilshire Boulevard",
      "city": "Santa Monica",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "90401",
      "state": "CA",
      "storeId": "1920"
    },
    "currentTier": {
      "display": "https://acme.com/loyalty/image/upload/star-silver.png",
      "name": "SILVER"
    },
    "loyaltyId": "1",
    "nextTier": {},
    "rewards": [],
    "tierLevelCode": "SILVER"
  },
  "profile": {
    "address": {
      "addressId": "09999",
      "addressLine1": "111 Wilshire Boulevard",
      "city": "Santa Monica",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "90401",
      "state": "CA",
      "storeId": "1920",
      "emailAddress": "timothy@gmail.com"
    },
    "customerId": "234900",
    "email": "timothy@gmail.com",
    "firstName": "Timothy",
    "lastName": "Smith",
    "postalCode": "90401",
    "customerGroup": "SILVER"
  },
  "addressList": [
    {
      "addressId": "09999",
      "addressLine1": "111 Wilshire Boulevard",
      "city": "Santa Monica",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "90401",
      "state": "CA",
      "storeId": "1920"
    }
  ],
  "consents": {
    "agreeToTC": true,
    "directMailSignUp": true,
    "eReceipt": true,
    "loyaltySignUp": true,
    "newsLetterSignUp": true,
    "phoneSignUp": true,
    "smsSignUp": true
  }
}
```

### Scenario 2: Add New Shipping Address to Profile From Cart

In this scenario, a store associate is placing an order for a customer. The associate searches and retrieves the customer’s profile, logging them in on the POS. Then, when selecting a shipping address for the order, the associate enters a new address for the customer instead of the existing address on file. The option to “Save this address to profile” is toggled on. After adding the new shipping address, a PUT request is sent to the merchant’s UPDATE_CUSTOMER SPI endpoint. As a result, the new address is added to the addressList array in the Customer object, **customer.addressList**.

**Request**

```json
{
  "customerId": "234900",
  "address": {
    "addressName": "Timothy Smith",
    "firstName": "Timothy",
    "lastName": "Smith",
    "addressLine1": "1100 Van Ness Avenue",
    "addressLine2": "",
    "addressLine3": "",
    "addressLine4": "",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94109",
    "countryCode": "US",
    "isDefaultBilling": false,
    "isDefaultShipping": false,
    "preferred": false,
    "emailAddress": "timothy@gmail.com"
  }
}
```

**Response**

```json
{
  "loyaltyProfile": {
    "accountNumber": "12344",
    "address": {
      "addressId": "09999",
      "addressLine1": "111 Wilshire Boulevard",
      "city": "Santa Monica",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "90401",
      "state": "CA",
      "storeId": "1920"
    },
    "currentTier": {
      "display": "https://acme.com/loyalty/image/upload/star-silver.png",
      "name": "SILVER"
    },
    "loyaltyId": "1",
    "nextTier": {},
    "rewards": [],
    "tierLevelCode": "SILVER"
  },
  "profile": {
    "address": {
      "addressId": "09999",
      "addressLine1": "111 Wilshire Boulevard",
      "city": "Santa Monica",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "90401",
      "state": "CA",
      "storeId": "1920",
      "emailAddress": "timothy@gmail.com"
    },
    "customerId": "234900",
    "email": "timothy@gmail.com",
    "firstName": "Timothy",
    "lastName": "Smith",
    "postalCode": "94109",
    "customerGroup": "SILVER"
  },
  "addressList": [
    {
      "addressId": "10000",
      "addressLine1": "1100 Van Ness Avenue",
      "city": "San Francisco",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "94109",
      "state": "CA",
      "storeId": "1920"
    },
    {
      "addressId": "09999",
      "addressLine1": "111 Wilshire Boulevard",
      "city": "Santa Monica",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "90401",
      "state": "CA",
      "storeId": "1920"
    }
  ],
  "consents": {
    "agreeToTC": true,
    "directMailSignUp": true,
    "eReceipt": true,
    "loyaltySignUp": true,
    "newsLetterSignUp": true,
    "phoneSignUp": true,
    "smsSignUp": true
  }
}
```

### Scenario 3: Update Customer Profile

In this scenario, a store associate searches and retrieves an existing customer, logging them in on the POS. Then the associate uses a deep link on that customer’s clienteling profile to edit the profile information. The associate edits the customer’s profile address. When the edits on the customer layout are submitted, a PUT request is sent to the merchant’s UPDATE_CUSTOMER SPI endpoint.

Below you can see the request and response payloads for that operation. Notice that, in the response, there are three changes:

- **customer.loyaltyProfile.address** and **customer.profile.address** are updated to the new address
- and the new address is appended to the **customer.addressList** array

**Request**

```json
{
  "profile": {
    "email": "timothy@gmail.com",
    "firstName": "Timothy",
    "lastName": "Smith",
    "address": {
      "firstName": "Timothy",
      "lastName": "Smith",
      "addressLine1": "241 West 107th Street",
      "addressLine2": "",
      "city": "New York",
      "state": "NY",
      "postalCode": "10025",
      "countryCode": "US",
      "storeId": "1920",
      "preferred": true
    },
    "phoneMobile": ""
  },
  "addressList": [],
  "consents": {
    "smsSignUp": true,
    "newsLetterSignUp": true,
    "agreeToTC": true,
    "directMailSignUp": true,
    "phoneSignUp": true,
    "loyaltySignUp": true,
    "eReceipt": true
  },
  "storeAttribution": {
    "storeAssociateId": "as1",
    "storeId": "1920"
  }
}
```

**Response**

```json
{
  "loyaltyProfile": {
    "accountNumber": "12344",
    "address": {
      "addressId": "10003697201",
      "addressLine1": "241 West 107th Street",
      "city": "New York",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "10025",
      "state": "NY",
      "storeId": "1920"
    },
    "currentTier": {
      "display": "https://acme.com/loyalty/image/upload/star-silver.png",
      "name": "SILVER"
    },
    "loyaltyId": "1",
    "nextTier": {},
    "rewards": [],
    "tierLevelCode": "SILVER"
  },
  "profile": {
    "address": {
      "addressId": "10001",
      "addressLine1": "241 West 107th Street",
      "city": "New York",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "10025",
      "state": "NY",
      "storeId": "1920",
      "emailAddress": "timothy@gmail.com"
    },
    "customerId": "234900",
    "email": "timothy@gmail.com",
    "firstName": "Timothy",
    "lastName": "Smith",
    "postalCode": "90401",
    "customerGroup": "SILVER"
  },
  "addressList": [
    {
      "addressId": "09999",
      "addressLine1": "111 Wilshire Boulevard",
      "city": "Santa Monica",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "90401",
      "state": "CA",
      "storeId": "1920"
    },
    {
      "addressId": "10000",
      "addressLine1": "1100 Van Ness Avenue",
      "city": "San Francisco",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "94109",
      "state": "CA",
      "storeId": "1920"
    },
    {
      "addressId": "10001",
      "addressLine1": "241 West 107th Street",
      "city": "New York",
      "countryCode": "US",
      "firstName": "Timothy",
      "lastName": "Smith",
      "postalCode": "10025",
      "state": "NY",
      "storeId": "1920"
    }
  ],
  "consents": {
    "agreeToTC": true,
    "directMailSignUp": true,
    "eReceipt": true,
    "loyaltySignUp": true,
    "newsLetterSignUp": true,
    "phoneSignUp": true,
    "smsSignUp": true
  }
}
```

<!-- document id=bf30802af37f72330f1ffdd8ce0417eb79a02ed077f786939ef3a885e3932a7d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/sandboxes/b2c-clone-on-demand-sandboxes.md -->

# Clone On-Demand Sandboxes

Use on-demand sandbox cloning to create exact replicas of existing sandboxes in minutes, not hours. It helps teams move faster while reducing risk by providing fully isolated environments for development, testing, and operational workflows.

With a single API call, provision a fully isolated replica of your sandbox that includes your database, application code, platform configurations, and all configured feature toggles.

To maintain a consistent and reliable clone, the source sandbox is automatically placed in a protected Stopped state during the initial backup phase of the cloning process. This safeguard guarantees data integrity and configuration consistency. After the backup completes, the source sandbox becomes available again, while the remaining clone phases continue in the background.

Each cloned sandbox is fully isolated, with dedicated compute, storage, and database resources.

Typical use cases include:

- Reproducing production bugs safely without impacting live systems
- Validating disaster recovery plans in isolated replicas
- Spinning up development or test environments for teams quickly
- Validating upgrades and configuration changes before deployment
- Testing feature or performance changes before deployment
- Supporting CI/CD pipelines with on-demand test environments
- Providing realistic training or experimentation environments
- Optimizing costs by cloning sandboxes only when needed

## What Is Included in a Clone

A sandbox clone includes:

- Database schema and data
- Custom code and cartridges
- Storefront, site data, and configurations
- Catalogs and pricebooks
- Orders and content data
- Feature toggles
- Maintenance pages
- Standard platform configuration files

## What Is Not Included

The following data is excluded to protect security, privacy, and tenant integrity:

- Logs and jobs history
- Customer PII and GDPR-related data
- Analytics data
- Geolocation data
- Order activity
- Exchange rate data
- Change logs
- Tenant-specific configurations

Sensitive data is either omitted or transformed to ensure compliance with platform security and privacy requirements.

## How Sandbox Cloning Works

The cloning process includes six detailed steps grouped into four main progress stages:

1. **Prep Instance**
   - Validation: Checks the source sandbox status, permissions, and resource availability.
2. **Data Backup**
   - Backup Creation: Creates a consistent snapshot of the source database, sharedata and configurations.
3. **Data Restore**
   - Target Provisioning: Allocates compute, storage, and network resources for the new sandbox.
   - Data Restoration: Copies database tables, indexes, and files to the cloned environment.
   - Configuration Transformation: Updates system files and credentials to ensure independence.
4. **Post Validation**
   - Activation: Validates sandbox health, tests connectivity, and makes the clone available.

Total duration is typically 10–30 minutes, depending on sandbox size and data volume.

The source sandbox is unavailable only during the initial backup phase of the clone operation. Once the backup is complete, the source sandbox becomes available again. If the source sandbox was running when the clone operation was initiated, it's automatically restarted after the backup completes. If it was already stopped, it remains in the stopped state.

The remaining phases of the clone operation continue in the background and don't require the source sandbox to be stopped.

Although the source sandbox becomes available before the clone operation finishes, you can't start another clone from the same source until the current clone completes. See the [Sandbox Cloning FAQ](#sandbox-cloning-faq) for more details.

A clone request can target either a single sandbox (one-to-one cloning) or multiple sandboxes (one-to-many cloning), with up to five target sandboxes per request. With one-to-many cloning, the source sandbox is backed up once, and that backup is used to restore all target sandboxes in parallel. The source availability behavior remains the same regardless of the number of targets.

Each target sandbox progresses through cloning independently. If one target encounters an error, the remaining targets continue processing and can complete successfully.

## Prerequisites

To clone sandboxes, you need:

**Account Requirements**

- Sandbox API User role assigned in B2C Commerce Account Manager with realm/tenant-level access.

**Source Sandbox Requirements**

- Source sandbox must be in Running or Stopped state
- Source sandbox should be in Enabled state
- Source sandbox must not have pending operations
- Permissions to access source sandbox data

**note:** Sandbox cloning is also available through Control Center. For more information, see [Clone On-Demand Sandboxes for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_cc_clone_ods_instance.htm&type=5).

## Clone a Sandbox Using the API

Sandbox cloning is available through the B2C Commerce On-Demand Sandbox REST API. Use the clone API to programmatically create and manage sandbox clones, giving developers and admins full control over provisioning and monitoring of the clones.

Access documentation for the Clone APIs and issue API calls from the Sandbox API user interface at [https://admin.dx.commercecloud.salesforce.com/](https://admin.dx.commercecloud.salesforce.com/). Click **Authorize** to log in with the API Client ID you configured using Account Manager.

### Create a Clone

Initiate a clone operation using the POST endpoint.

**Request**

```http
POST /sandboxes/{sandboxId}/clones HTTP/1.1
Host: admin.dx.commercecloud.salesforce.com
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "targetProfile": "xlarge",
  "emails": ["email1@example.com"],
  "ttl": 24
}
```

**cURL**

```
curl -X 'POST' \
  'https://<host>/api/v1/sandboxes/{sandboxId}/clones' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "targetProfile": "medium",
  "emails": [
    "email1@example.com"
  ],
  "ttl": 24
}'
```

**Parameters**

| Parameter     | Type          | Required | Description                                                                                                                                                                                   |
| ------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sandboxId     | string (UUID) | Yes      | Unique identifier of the source sandbox to clone                                                                                                                                              |
| targetProfile | string        | Yes      | Resource profile for the cloned sandbox: medium, large, xlarge, or xxlarge. Note: Target Profile can't be lower than the source sandbox.                                                      |
| targetCount   | int           | No       | Number of sandbox clones to create from this source. Valid values: 1–5. Default: 1 (a single one-to-one clone). When greater than 1, the clones are created as a batch that shares a batchId. |
| emails        | List          | No       | Email addresses for notifications                                                                                                                                                             |
| ttl           | int           | No       | Number of hours for the sandbox clone lifetime. Default: 24 hours                                                                                                                             |

**Success Response (201 Created)**

```
{
  "cloneId": "abcd-001-180620251331"
}
```

The cloneId can be used to track the clone operation status.

**Error Responses**

**400 Bad Request** - Illegal Argument

```
{
  "kind": "Status",
  "code": 400,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "Profile downgrade not allowed. Current profile: large, Requested profile: medium. Only same profile or upgrades are permitted.",
    "reason": "IllegalArgument"
  }
}
```

**403 Forbidden** - AccessDenied

```
{
  "kind": "Status",
  "code": 403,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "User doesn't have access to this realm",
    "reason": "AccessDenied"
  }
}
```

**404 Not Found** - Sandbox not found

```
{
  "kind": "Status",
  "code": 404,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "Sandbox '34801747-1011-43d0-a3b5-5d46f1b49dfb' doesn't exist.",
    "reason": "SandboxNotFound"
  }
}
```

### Create Multiple Clones (One-to-Many)

Set `targetCount` to a value from 2–5 to create multiple sandbox clones from the same source in a single request. The source sandbox is backed up once, and the backup is used to create each target sandbox in parallel. This approach reduces source downtime compared to submitting separate one-to-one clone requests.

To create multiple clones, add `targetCount` to the request body.

**Request**

```http
POST /sandboxes/{sandboxId}/clones HTTP/1.1
Host: admin.dx.commercecloud.salesforce.com
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "targetProfile": "xlarge",
  "targetCount": 3,
  "emails": ["email1@example.com"],
  "ttl": 24
}
```

**cURL**

```
curl -X 'POST' \
  'https://<host>/api/v1/sandboxes/{sandboxId}/clones' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "targetProfile": "medium",
  "targetCount": 3,
  "emails": [
    "email1@example.com"
  ],
  "ttl": 24
}'
```

**Success Response (201 Created)**

```
{
  "cloneId": "abcd-001-1784379488544",
  "batchId": "batch-abcd-001-1784379488543-dfa36a1d",
  "siblingCloneIds": [
    "abcd-001-1784379488544",
    "abcd-001-1784379488545",
    "abcd-001-1784379488546"
  ]
}
```

Use the individual clone IDs in `siblingCloneIds` to monitor each target clone. See [Monitor Sandbox Clone Operations](#monitor-sandbox-clone-operations).

**Error Responses**

**400 Bad Request** - Illegal Argument

```
{
  "kind": "Status",
  "code": 400,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "targetCount must be between 1 and 5. Requested: {n}",
    "reason": "IllegalArgument"
  }
}
```

### Monitor Sandbox Clone Operations

Monitor the progress of a clone operation using the clone ID and source sandbox ID. This can also be used to retrieve details for a specific cloned sandbox.

**Request**

```
GET /sandboxes/{sandboxId}/clones/{cloneId}
Host: admin.dx.commercecloud.salesforce.com
Authorization: Bearer {access_token}
Content-Type: application/json
```

**cURL**

```
curl -X 'GET' \
  'https://<host>/api/v1/sandboxes/<sandboxId>/clones/<cloneId>' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <token>' \
  -H 'Content-Type: application/json'
```

**Parameters**

| Parameter | Type          | Required | Description                              |
| --------- | ------------- | -------- | ---------------------------------------- |
| sandboxId | string (UUID) | Yes      | Unique identifier of the source sandbox  |
| cloneId   | string        | Yes      | Unique identifier of the clone operation |

**Success Response (200 OK)**

For a single (one-to-one) clone:

```
{
  "cloneId": "abcd-001-1771055271197",
  "realm": "abcd",
  "sourceInstance": "001",
  "targetInstance": "002",
  "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
  "targetInstanceId": "2b2d1805-a66f-4b07-943f-9ef6808f5efa",
  "targetProfile": "medium",
  "createdAt": "2026-02-14T07:45:07.742Z",
  "createdBy": "test@example.com",
  "lastUpdated": "2026-02-14T07:45:07.742Z",
  "status": "IN_PROGRESS",
  "elapsedTimeInSec": 240,
  "progressPercentage": 23,
  "lastKnownState": "Data Backup In Progress",
  "customCodeVersion": "SFRA_01_01_2026",
  "storefrontCount": 1,
  "filesystemUsageSize": 1024,
  "databaseTransferSize": 2048
}
```

For a target that's part of a one-to-many batch, the response also includes `batchId` and `siblingCloneIds`:

```
{
  "cloneId": "abcd-001-1784379488544",
  "realm": "abcd",
  "sourceInstance": "001",
  "targetInstance": "002",
  "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
  "targetInstanceId": "2b2d1805-a66f-4b07-943f-9ef6808f5efa",
  "targetProfile": "medium",
  "createdAt": "2026-02-14T07:45:07.742Z",
  "createdBy": "test@example.com",
  "lastUpdated": "2026-02-14T07:45:07.742Z",
  "status": "IN_PROGRESS",
  "elapsedTimeInSec": 240,
  "progressPercentage": 23,
  "lastKnownState": "Data Backup In Progress",
  "customCodeVersion": "SFRA_01_01_2026",
  "storefrontCount": 1,
  "filesystemUsageSize": 1024,
  "databaseTransferSize": 2048,
  "batchId": "batch-abcd-001-1784379488543-dfa36a1d",
  "siblingCloneIds": ["abcd-001-1784379488544", "abcd-001-1784379488545", "abcd-001-1784379488546"]
}
```

Each target has its own cloneId and its own independent status, so poll each cloneId from `siblingCloneIds` separately. One target completing, failing, or still running has no effect on the reported status of the others. Each response represents a single target in the batch, not the entire batch. All targets in the batch share the same `batchId`, and `siblingCloneIds` is identical in every target's response, listing all clones in the batch.

**Response Fields**

| Field                | Type              | Description                                                                                                              |
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| cloneId              | string            | Unique identifier for the clone operation                                                                                |
| realm                | string            | Four-letter realm identifier                                                                                             |
| sourceInstance       | string            | Source instance number                                                                                                   |
| targetInstance       | string            | Target instance number                                                                                                   |
| sourceInstanceId     | string (UUID)     | UUID of the source sandbox                                                                                               |
| targetInstanceId     | string (UUID)     | UUID of the cloned sandbox                                                                                               |
| targetProfile        | string            | Resource profile: medium, large, xlarge, or xxlarge                                                                      |
| createdAt            | string (ISO 8601) | Timestamp when clone was initiated                                                                                       |
| createdBy            | string (email)    | Email of user who initiated the clone                                                                                    |
| lastUpdated          | string (ISO 8601) | Timestamp of most recent status update                                                                                   |
| status               | string            | Current status: IN_PROGRESS, COMPLETED, or FAILED                                                                        |
| elapsedTimeInSec     | integer           | Elapsed time since clone started (seconds)                                                                               |
| progressPercentage   | integer           | Completion progress (0-100)                                                                                              |
| lastKnownState       | string            | Current state of the clone progress                                                                                      |
| storefrontCount      | integer           | Count of storefronts                                                                                                     |
| filesystemUsageSize  | integer           | Share data transfer size in megabytes                                                                                    |
| databaseTransferSize | integer           | Database transfer size in megabytes                                                                                      |
| customCodeVersion    | string            | Code version                                                                                                             |
| batchId              | string            | Shared batch identifier for clones created together via one-to-many cloning. Absent for a single (one-to-one) clone.     |
| siblingCloneIds      | array of string   | cloneIds of all clones in the same batch, in target order (includes this clone). Absent for a single (one-to-one) clone. |

**Clone Status Values**

| Status      | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| IN_PROGRESS | Clone operation is currently running. Continue polling for updates.       |
| COMPLETED   | The clone operation finished successfully. Target sandbox is operational. |
| FAILED      | Clone operation encountered an error. Review error details.               |

**Error Responses**

**403 Forbidden** - AccessDenied

```
{
  "kind": "Status",
  "code": 403,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "User doesn't have access to this realm",
    "reason": "AccessDenied"
  }
}
```

**404 Not Found** - Invalid Sandbox Id

```
{
  "kind": "Status",
  "code": 404,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "DB entry for id '0c7bd46d-3300-4880-984f-cf8df01685e6' doesn't exist",
    "reason": "NotFound"
  }
}
```

**404 Not Found** - No Clone Found

```
{
  "kind": "Status",
  "code": 404,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "No clone found with id 'zyom-002-017-180620251331'",
    "reason": "NotFound"
  }
}
```

### List All Clones

Fetch details of all clone operations associated with a specific sandbox.

**Request**

```
GET /sandboxes/{sandboxId}/clones
Host: admin.dx.commercecloud.salesforce.com
Authorization: Bearer {access_token}
Content-Type: application/json
```

**cURL**

```
curl -X 'GET' \
  'https://<host>/api/v1/sandboxes/<sandboxId>/clones' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <token>' \
  -H 'Content-Type: application/json'
```

**Parameters**

| Parameter | Type           | Required | Description                                                                                                                                      |
| --------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| sandboxId | string (UUID)  | Yes      | Unique identifier of the source sandbox to clone                                                                                                 |
| fromDate  | string (query) | No       | Filter clones created on or after this date (ISO 8601 date format). When provided without toDate, toDate defaults to the current timestamp.      |
| toDate    | string (query) | No       | Filter clones created on or before this date (ISO 8601 date format). If omitted when fromDate is provided, it defaults to the current timestamp. |
| status    | string (query) | No       | Filter clones by status. If not provided, returns all clones regardless of status. Available values: Pending, InProgress, Failed, Completed.     |
| batchId   | string (query) | No       | Filter clones by their one-to-many batch identifier. When provided, returns only the clones that belong to that batch.                           |

**Success Response (200 OK)**

For a single (one-to-one) clone:

```
{
  "clones": [
    {
      "cloneId": "abcd-001-1771055271197",
      "realm": "abcd",
      "sourceInstance": "001",
      "targetInstance": "002",
      "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
      "targetInstanceId": "2b2d1805-a66f-4b07-943f-9ef6808f5efa",
      "targetProfile": "medium",
      "createdAt": "2026-02-14T07:45:07.742Z",
      "createdBy": "test@example.com",
      "lastUpdated": "2026-02-14T07:45:07.742Z",
      "status": "IN_PROGRESS",
      "elapsedTimeInSec": 240,
      "progressPercentage": 23,
      "lastKnownState": "Data Backup In Progress",
      "customCodeVersion": "SFRA_01_01_2026",
      "storefrontCount": 1,
      "filesystemUsageSize": 1024,
      "databaseTransferSize": 2048
    }
  ]
}
```

Filtered by `batchId`, showing every target in the batch as its own row:

```
{
  "clones": [
    {
      "cloneId": "abcd-001-1784379488544",
      "realm": "abcd",
      "sourceInstance": "001",
      "targetInstance": "002",
      "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
      "targetInstanceId": "2b2d1805-a66f-4b07-943f-9ef6808f5efa",
      "targetProfile": "medium",
      "createdAt": "2026-02-14T07:45:07.742Z",
      "createdBy": "test@example.com",
      "lastUpdated": "2026-02-14T08:00:19.742Z",
      "status": "COMPLETED",
      "elapsedTimeInSec": 912,
      "progressPercentage": 100,
      "lastKnownState": "Completed",
      "customCodeVersion": "SFRA_01_01_2026",
      "storefrontCount": 1,
      "filesystemUsageSize": 1024,
      "databaseTransferSize": 2048,
      "batchId": "batch-abcd-001-1784379488543-dfa36a1d",
      "siblingCloneIds": ["abcd-001-1784379488544", "abcd-001-1784379488545", "abcd-001-1784379488546"]
    },
    {
      "cloneId": "abcd-001-1784379488545",
      "realm": "abcd",
      "sourceInstance": "001",
      "targetInstance": "003",
      "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
      "targetInstanceId": "faa21fa1-38b2-4f84-b892-f9967522e89e",
      "targetProfile": "medium",
      "createdAt": "2026-02-14T07:45:07.742Z",
      "createdBy": "test@example.com",
      "lastUpdated": "2026-02-14T07:53:07.742Z",
      "status": "IN_PROGRESS",
      "elapsedTimeInSec": 480,
      "progressPercentage": 47,
      "lastKnownState": "Data Restore In Progress",
      "customCodeVersion": "SFRA_01_01_2026",
      "storefrontCount": 1,
      "filesystemUsageSize": 1024,
      "databaseTransferSize": 2048,
      "batchId": "batch-abcd-001-1784379488543-dfa36a1d",
      "siblingCloneIds": ["abcd-001-1784379488544", "abcd-001-1784379488545", "abcd-001-1784379488546"]
    },
    {
      "cloneId": "abcd-001-1784379488546",
      "realm": "abcd",
      "sourceInstance": "001",
      "targetInstance": "004",
      "sourceInstanceId": "0c7bd46d-3300-4880-984f-cf8df01685e6",
      "targetInstanceId": "9d4e7c02-1a5b-4f83-b6e2-7c3a8d1f6b40",
      "targetProfile": "medium",
      "createdAt": "2026-02-14T07:45:07.742Z",
      "createdBy": "test@example.com",
      "lastUpdated": "2026-02-14T07:50:12.742Z",
      "status": "FAILED",
      "elapsedTimeInSec": 305,
      "progressPercentage": 31,
      "lastKnownState": "Failed",
      "customCodeVersion": "SFRA_01_01_2026",
      "storefrontCount": 1,
      "filesystemUsageSize": 1024,
      "databaseTransferSize": 2048,
      "batchId": "batch-abcd-001-1784379488543-dfa36a1d",
      "siblingCloneIds": ["abcd-001-1784379488544", "abcd-001-1784379488545", "abcd-001-1784379488546"]
    }
  ]
}
```

**Response Fields**

| Field                | Type              | Description                                                                                                              |
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| cloneId              | string            | Unique identifier for the clone operation                                                                                |
| realm                | string            | Four-letter realm identifier                                                                                             |
| sourceInstance       | string            | Source instance number                                                                                                   |
| targetInstance       | string            | Target instance number                                                                                                   |
| sourceInstanceId     | string (UUID)     | UUID of the source sandbox                                                                                               |
| targetInstanceId     | string (UUID)     | UUID of the cloned sandbox                                                                                               |
| targetProfile        | string            | Resource profile: medium, large, xlarge, or xxlarge                                                                      |
| createdAt            | string (ISO 8601) | Timestamp when clone was initiated                                                                                       |
| createdBy            | string (email)    | Email of user who initiated the clone                                                                                    |
| lastUpdated          | string (ISO 8601) | Timestamp of most recent status update                                                                                   |
| status               | string            | Current status: IN_PROGRESS, COMPLETED, or FAILED                                                                        |
| elapsedTimeInSec     | integer           | Elapsed time since clone started (seconds)                                                                               |
| progressPercentage   | integer           | Completion progress (0-100)                                                                                              |
| lastKnownState       | string            | Current state of the clone progress                                                                                      |
| storefrontCount      | integer           | Count of storefronts                                                                                                     |
| filesystemUsageSize  | integer           | Share data transfer size in megabytes                                                                                    |
| databaseTransferSize | integer           | Database transfer size in megabytes                                                                                      |
| customCodeVersion    | string            | Code version                                                                                                             |
| batchId              | string            | Shared batch identifier for clones created together via one-to-many cloning. Absent for a single (one-to-one) clone.     |
| siblingCloneIds      | array of string   | cloneIds of all clones in the same batch, in target order (includes this clone). Absent for a single (one-to-one) clone. |

**Clone Status Values**

| Status      | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| IN_PROGRESS | Clone operation is currently running. Continue polling for updates.       |
| COMPLETED   | The clone operation finished successfully. Target sandbox is operational. |
| FAILED      | Clone operation encountered an error. Review error details.               |

**Error Responses**

**403 Forbidden** - AccessDenied

```
{
  "kind": "Status",
  "code": 403,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "User doesn't have access to this realm",
    "reason": "AccessDenied"
  }
}
```

**404 Not Found** - Invalid Sandbox Id

```
{
  "kind": "Status",
  "code": 404,
  "status": "Failure",
  "error": {
    "status": "Failure",
    "message": "DB entry for id '0c7bd46d-3300-4880-984f-cf8df01685e6' doesn't exist",
    "reason": "NotFound"
  }
}
```

## Additional Configuration Required

After cloning completes, you must manually update (if any):

- Custom tenant-specific configurations
- Hard-coded URLs in custom cartridges or scripts
- Third-party service URLs and API endpoints
- Keystore references and certificates tied to the source sandbox
- Custom jobs or schedules that reference the source instance

**note:** In a one-to-many clone, these steps apply per target. Repeat them for each resulting sandbox.

## Best Practices

**Choose Appropriate Resource Profiles**

Select the profile that meets your requirements. For cloning, the target profile should be the same size or larger than the source sandbox profile.

**Review Custom Configurations**

After cloning completes, test all integrations and custom configurations. Update third-party endpoints, keystores, and Business Manager customizations that reference the source sandbox.

**Manage Cloned Sandboxes**

Delete cloned sandboxes when no longer needed to reduce credit consumption.

**Plan Clone Operations**

Where feasible, execute large clone operations during times when sandbox usage is low.

**Save Your Work**

During the initial backup phase of the clone process, the source sandbox is stopped. Make sure to save any open work before triggering the clone operation.

**Monitor Clone Progress**

Monitor the progress of a clone using the Monitor Clone Progress API. Poll the API every 30–60 seconds to check status, but avoid excessive polling, which may trigger rate limits. For a one-to-many clone, poll each target's cloneId independently. Don't assume all targets finish at the same time or that one target's failure affects the others.

**Set Time-to-Live Values**

Configure the ttl parameter to automatically clean up temporary clones and avoid consuming unnecessary credits.

**Resume Work on the Source Early**

The source sandbox becomes available again shortly after the clone starts, once the backup stage completes. You don't need to wait for the full clone to finish before resuming work on the source. You still can't trigger a new clone on that same source until the current one completes, even though the source itself is available again.

**Plan Multi-Target Requests**

When cloning to multiple targets, the source is stopped once, for the duration of the single shared backup step, not once per target. The targetProfile, emails, and ttl values apply to the entire batch. If different targets need different settings, submit separate clone requests, or clone with shared settings and adjust individual targets afterward using the Sandbox Update API (PATCH /sandboxes/{sandboxId}).

## Sandbox Cloning FAQ

**Q.** What state must the source sandbox be in to perform a clone?\
**A.** The source sandbox must be in an Enabled state, either Running or Stopped, to be successfully cloned.

**Q.** What happens to the source sandbox during cloning?\
**A.** It's placed in a Stopped state during the initial backup phase to protect data integrity. After the backup completes, the source becomes available again, although you can't start another clone from it until the current clone finishes.

**Q.** Can multiple clone operations run from the same source sandbox at the same time?\
**A.** No. Only one clone can run per source sandbox at a time, however different source sandboxes can be cloned simultaneously.

**Q.** Where is the cloned sandbox created?\
**A.** It's created in the same realm as the source sandbox.

**Q.** Are platform configuration files updated automatically during cloning?\
**A.** Standard platform configurations are updated automatically. Custom configurations must be reviewed manually.

**Q.** Are tenant-specific configurations and customizations updated automatically?\
**A.** No. Tenant-specific configurations, custom keystores, certificates, and Business Manager customizations aren't updated automatically.

**Q.** Can a clone operation be paused or resumed?\
**A.** No. Once started, a clone operation can't be paused or resumed.

**Q.** How long does cloning usually take?\
**A.** It typically takes 10–30 minutes. In rare cases, it may take up to 60 minutes. If it exceeds 60 minutes, the process fails and the source sandbox is restored.

**Q.** Are there any credit requirements for cloning?\
**A.** Yes. A sufficient credit balance is required for both the clone operation and the target sandbox uptime.

**Q.** What happens to feature toggles during cloning?\
**A.** Any manually set or customized feature toggles are copied to the cloned sandbox.

**Q.** What is the default minimum TTL (Time To Live) for a cloned sandbox?\
**A.** The minimum TTL is 24 hours to avoid accidental deletion during setup.

**Q.** Can I clone a sandbox to a profile lower than the current profile of the source sandbox?\
**A.** No. The cloned sandbox can have a profile that is the same as or higher than the source sandbox's profile, but not lower.

**Q.** What happens if I accidentally delete the source sandbox after successfully creating the clone?\
**A.** Once the clone sandbox is successfully created, it operates as an independent sandbox. Deleting the source sandbox will have no impact on the cloned sandbox.

**Q.** What happens if I don't include the emails attribute when calling the Create Clone API?\
**A.** If you don't explicitly provide the emails attribute, the cloned sandbox won't inherit or copy the email settings from the source sandbox by default.

**Q.** Can I clone a sandbox to more than one target at once?\
**A.** Yes. Set targetCount to a value from 1–5 in your clone request. The source is backed up once and restored to all targets concurrently.

**Q.** Is there a limit on how many targets I can clone to at once?\
**A.** Yes. targetCount accepts values from 1–5.

**Q.** If one target fails in a one-to-many clone, do the others fail too?\
**A.** No. Each target is tracked and processed independently. A failure on one target has no effect on the others. Check each target's cloneId status individually.

**Q.** Can I set a different profile, TTL, or notification email list for each target in a one-to-many clone?\
**A.** No. targetProfile, ttl, and emails apply to the whole request, not per target. Submit separate clone requests if targets need different settings, or use the Sandbox Update API to adjust individual targets afterward.

**Q.** If my source sandbox becomes available again early, can I start another clone on it right away?\
**A.** No. Although the source sandbox becomes available shortly after the backup stage completes, you can't trigger a new clone on that same source until the current clone operation finishes (Completed or Failed). The early availability lets you resume other work on the source sooner. It doesn't open a new clone slot.

<!-- document id=b5afbfb3b04c2c6b24f46ee9a97daa5388703f2f20424266cfc9ddd1ebc9d1bc url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_clone_ods_instance.md -->

# Clone On-Demand Sandboxes for B2C Commerce

Create replicas of existing on-demand sandboxes for development, testing, and operational workflows.

**note:** For detailed information about the cloning process, including what data is included or excluded, configuration requirements, and how the cloning workflow operates, see [Clone On-Demand Sandboxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-clone-on-demand-sandboxes.html) in the API documentation.

<!-- document id=2c00ad91a3c45ebba7e9b247eaa66e5aae4a3599679f97fd6d5b74462e064e18 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/cms-user-management-api.md -->

CMS User Management API

# CMS User Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cms-user-management-api/cms-user-management-api-oas-public.yaml)

Merchant API to create, search, update, and delete CMS users from the POS system.

**Version:** 2.3.4

## Tags

### CMS User Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cms-user-management-api/cms-user-management-api-oas-public.yaml)

Merchant API to create, search, update, and delete CMS users from the POS system.

## Operations

### GET Get CMS users.

`GET /merchant/{version}/users`

Operation ID: `getUsers`. Tags: CMS User Management API.

Retrieve all CMS users.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### PUT Update a CMS user.

`PUT /merchant/{version}/users`

Operation ID: `updateUser`. Tags: CMS User Management API.

Update a CMS user. If the user is updated successfully, the successful response includes a list of all users. Otherwise, the response includes ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `EditUserRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### POST Create CMS users.

`POST /merchant/{version}/users`

Operation ID: `createUsers`. Tags: CMS User Management API.

Create CMS users. If the users are created successfully, the response includes all users. Otherwise, the response includes ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `CreateCMSUsersRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### DELETE Delete a CMS user.

`DELETE /merchant/{version}/users`

Operation ID: `deleteUser`. Tags: CMS User Management API.

Delete the provided CMS user. On successful deletion, the response includes a list of all remaining users. Otherwise, it contains ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `userId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### PATCH Update CMS users.

`PATCH /merchant/{version}/users`

Operation ID: `patchUsers`. Tags: CMS User Management API.

Update the CMS users in the request. If all users are updated successfully, the successful response includes a list of all users. Otherwise, the response includes ErrorMessage and ErrorCode corresponding to the failure.

**Limit:** 100 users per request.

Validation includes:

1.  Empty or null request
2.  Valid existing CMS users.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `UpdatesCMSUsersRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### GET Get CMS user.

`GET /merchant/{version}/users/{userId}`

Operation ID: `getUserByUserId`. Tags: CMS User Management API.

Retrieve CMS user details.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `userId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UserAccount`.
    

## Schemas

### ListUserAccountsResponse

Payload that contains the list of CMS users.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `users` (_array of UserAccount_) List of CMS users.
*   `error` (_boolean_)

### EditUserRequest

*   `oldUserId` (_string_, required) The existing user ID.
*   `newUserId` (_string_, nullable) New user ID. Must be a valid Google account.
*   `role` (_string_, nullable) New Role.
*   `timeZoneId` (_string_, nullable) New timezone ID. Don't use a timezone abbreviation.  
    Example: `America/Los_Angeles`.
*   `userType` (_string_, nullable) New user type.  
    Allowed values: `GLOBAL`, `REGIONAL`. Example: `GLOBAL`.

### CreateCMSUsersRequest

Request payload to create the CMS users.

*   `userAccounts` (_array of UserAccount_) List of users for CMS account creation.

### UpdatesCMSUsersRequest

*   `userRequestList` (_array of EditUserRequest_)

### UserAccount

Payload that contains information about CMS user.

*   `userId` (_string_, required) User ID. Must be a valid Google account.
*   `merchantId` (_string_, required) Merchant ID.
*   `permissions` (_string_, nullable) User's permission in CMS in the JSON form.  
    Example: `{"role":"CMS POWER USER","permissions":[{"LAYOUTS":["EDIT"]},{"FEEDS":["EDIT"]}]}`.
*   `role` (_string_, nullable) User's role.  
    Default: `CMS POWER USER`.
*   `timeZoneId` (_string_, nullable) User's timezone ID. Don't use a timezone abbreviation.  
    Default: `UTC`. Example: `America/Los_Angeles`.
*   `userType` (_string_) User Type.  
    Allowed values: `GLOBAL`, `REGIONAL`. Default: `GLOBAL`.

<!-- document id=9312ad8067e1cd948df41b039f8b9fbba70b046acf90ed5dce3d0f190a7af938 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-code-deployment.md -->

# Code Deployment

Manage code versions and securely upload code.

## Code Versions

B2C Commerce supports multiple custom code versions uploaded to the system at the same time. The code is arranged in a top-level directory, called `Version Directories.` Name each directory in accordance with your versions, for example, `v12` or `summer_release`.

### Code Versions and the Active Version

When developing your storefront, select one _active_ code version with which to work by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Site Development** > **Code Deployment**. Select a version directory as the active version for a site. All templates, pipelines, scripts, and images are taken from this _active_ version.

B2C Commerce automatically and asynchronously removes the oldest code versions on all instance types. The active code version and the previously active code version aren't included in this process. Configure the number of retained code versions.

Roll back your storefront to a previous version if necessary. Develop your application with a newer version while maintaining an active storefront on a stable code base.

B2C Commerce doesn't let you upload code using a .zip file containing a distinct code version. Instead, you must upload your cartridge. Most development teams have a regular method for uploading code to staging.

#### Troubleshooting Tip for Code Versioning

If you get the following error when you try to view the storefront, check that you're uploading your cartridge to the current code version.

```
Technical Page There were technical problems while the request was being processed!
Executed Request:
Default Technical Details: System template default used directly or indirectly in custom site
```

**note:** Plan to test a new code version first on a Staging instance before moving it to the Production instance.

### Code Uploads to an Active or Inactive Version

Best practice is to upload code into an inactive version on a Staging instance and later replicate the code to a Development or Production instance.

Code uploads into an _active_ version are only allowed on Staging, Development, and Sandbox instances. Production instances reject WebDAV-based code uploads that occur directly into the currently active version. Code uploads onto a Production instance can only be to an inactive version.

### Code Compatibility Mode

Specify the active compatibility mode (API version). B2C Commerce supports activating a new compatibility mode or reverting to the previously active compatibility mode.

Replicate code to another system. Code Replication transports the active code version from the staging instance to the target production or development instance.

**note:** The term `Compatibility Mode` is interchangeable with the term `API Version.`

## Manage Code Versions

A code version is a folder that contains custom cartridges. An instance uses the currently active code version. Upload additional code versions to the server via WebDAV. These can be new code versions that will be activated later, or previous ones to allow for code rollbacks.

A compatibility mode can be assigned to each code version and is activated when the code version is activated. Code versions that haven't been explicitly assigned to a compatibility mode are marked with an asterisk (\*) and assume the current active compatibility mode. Selectable compatibility modes are those that are newer than the active compatibility mode, in addition to the previously active compatibility mode. You can't select a compatibility mode that is older than the previously active one.

The platform automatically and asynchronously removes the oldest code versions on all instance types. The active code version and the previously active code version aren't included in this process. Configure the number of retained code versions (see below).
The platform automatically and asynchronously removes the oldest code versions on all instance types. The active code version and the previously active code version aren't included in this process. You can configure the number of retained code versions (see below).

### Manage Code Versions with the B2C Commerce CLI

Instead of manual uploads via Business Manager, you can use the CLI to push and activate code versions in a single step. This is the recommended method for GitHub Actions or Jenkins pipelines. First, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md) to install the tool and authenticate.

Once configured, use the CLI to push and activate a code version:

```bash
# Deploy cartridges and activate the code version
b2c code deploy --code-version <version_name> --reload
# Or activate separately
b2c code activate <version_name>
```

For local development, use `b2c code watch` to continuously sync cartridge file changes to your sandbox so edits are reflected immediately without a full redeploy:

```bash
b2c code watch --code-version <version_name>
```

For a complete list of code deployment CLI commands, see [Code Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/code.html).

### Manage Code Versions with Business Manager

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**. You must assign custom cartridges to sites.

2.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Code Deployment**.

    On the Manage Code Versions page, there are two timestamp columns:

    - Modification time: Ddate and time the code was created or last updated on the instance.
    - Activation time: Date and time of the last code activation.

      The timestamp changes after an activation, roll back (for the new active version), or replication. Code versions that weren't activated don't show an activation time, for example, a new code version.

      If you upload code changes without creating a new cartridge, activation time represents the date and time the code initially went live on a Production instance.

3.  Click a link in the Code Version column.

    The Version Summary page opens, where you can drill down into the code via WebDAV.

4.  Click a compatibility mode link to view a list of available compatibility modes.

    The Compatibility Mode page opens with a list of available compatibility modes.

    - The currently active compatibility mode
    - The previously active compatibility mode
    - Any new compatibility modes that you can select
      Each compatibility mode provides a Change Docs link that provides a summary of applicable changes and a Documentation link to the respective API documentation.

5.  Click **Back** to return to the Manage Code Versions page.

6.  To rename a code version, click **Rename** beside a code version in the list.

    Renaming a code version also changes the respective entries in the version file.

7.  To activate a code version, click **Activate** beside a code version in the list.

    It isn't possible to select a compatibility mode older than the previously active one.

    A code version is activated by adding its folder to the list of folders in which the server looks up resources. At the same time, the folder of the previous active code version is removed from the list.

    The features included in the new code version are immediately available. Cached items (which might be dependent on a change to the compatibility mode) are cleared after activating a new code version.

8.  Click **Rollback** to automatically activate the previous code version, if this code version is still installed.

    If the previous code version is no longer available (it has been deleted), the rollback fails. The action also activates the compatibility mode associated with the previous code version.

9.  Select one or more inactive code versions and click **Delete** to delete them. You can't delete the active code version.

10. Click **Add** to create a new empty code version. The new code version will be set to the currently active compatibility mode.

    To protect B2C Commerce against directory traversal attempts when creating or renaming a custom code version, an exception is thrown on any attempts to access a parent directory or sub-directory. For example, you can't pass `my/new/version` when creating or renaming a custom code version. The effective version name is the end of the expression, in this case, `version`. This type of input results in an error.

11. To configure the number of retained code versions:

    1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Site Development > Code Deployment** (admin user only).

    2.  In the Code Version Retention section, enter the number of retained code versions (3 to 20, the default is 10).

        The initial value for existing customers is 0, which means that the feature is disabled. If you activate this feature (by setting a value other than 0) only Salesforce Support can reset it to 0. All newly provisioned instances have a default of 10.

    3.  Click **Apply**.

12. To work with a single version:

    1.  Click the code version name link.

        The Code Version Summary page opens.

        This page provides a detailed view of the code version. The top section provides summary information, while the bottom section provides a paged list view of resources that are part of the code version. The list view shows files regardless of where they are located within the code version (that is, regardless of cartridge and subdirectory).

    2.  Click **Activate** to activate this code version.

    3.  Click **Download** in the top section to download the entire code version, or click **Download** beside an individual file to download that file.

    4.  Use the File Filter to search for a file or set of files.

## Code Version Best Practices

As a best practice, maintain consistent use of version numbers for each software update.

It is tempting to simply upload a fix to a current production directory. But if there are problems, this approach doesn't permit quick roll backs. This approach can also cause unnecessary delays in addressing a potentially critical situation.

Using version numbers consistently helps development and support teams diagnose and fix issues in a timely manner. If a new version causes issues that were unknown during the test phase, support can roll back to a previous known working version. Being able to roll back is especially helpful if a version makes the system unstable and support is required to respond in a 24x7 environment. With versioning, the development team can review specific code fixes within the context of multiple previous versions.

## Compatibility Modes

_Compatibility mode_ refers to a B2C Commerce API version that includes changes that affect backward compatibility with the previous API version.

Not every API version affects backward compatibility, so only some API versions have a compatibility mode. Use API versioning to actively select from multiple compatibility modes, with the full knowledge and acceptance of incompatible changes. Select the compatibility mode to maintain your customizations on a previous compatibility mode, while B2C Commerce introduces new functionality in one or more newer compatibility modes.

Selectable compatibility modes are newer than the active compatibility mode, in addition to the previously active compatibility mode. You can't select a compatibility mode that is older than the previously active one.

**note:** Not every release introduces an API version or compatibility mode. We try to keep the number of API compatibility modes to a maximum of two per year.

B2C Commerce supports a single _active_ compatibility mode; and maintains a reference to the previously active compatibility mode, to which you can revert, if necessary.

The complete list of compatibility modes available at any time consists of:

- The currently active compatibility mode
- The previously active compatibility mode
- Any new compatibility modes you can activate

When your system was initially provisioned, the active compatibility mode was set to the latest (or most recent) compatibility mode. For example, if you initially provisioned with version 2.10.6, then the active compatibility mode is 2.10.6 because 2.10.6 introduced a corresponding 2.10.6 API version (compatibility mode).

Specify how many code versions to retain. The oldest, except for the active and previously active code versions, are automatically removed by B2C Commerce (Sandboxes only).

### API Documentation

A single API documentation set describes multiple compatibility modes at the class and method level, and potentially multiple compatibility modes for certain methods.

### When Do You Need to Change Your Application?

Before activating a new compatibility mode, it's important that you understand the behavioral changes the new mode brings. If the change impacts your application, you might need to modify your application to make it function correctly with the changes and then test. Roll back to the previously active compatibility mode only if your code is compatible with the old mode (API version). If you write code that takes advantage of the API of a newer version that is incompatible with the old version, roll back only if you also revert the respective code.

When using API versioning, you must pay close attention to certain situations:

- All cartridges in an application must use the same active compatibility mode.
- There can be only one active compatibility mode at a time (no wildcard support).
- Change the compatibility mode on all instances, but we don't recommend changing the mode directly on Production.
- Avoid using different compatibility modes on Staging and Production.

## Configure Secure Code Uploads

To upload code securely, use two-factor authentication to upload the code to the staging instance. After the code is on the staging instance, use code replication to propagate the code from staging to the production instance.

For a human user, use a Business Manager or Account Manager username and password as the first factor for uploading to staging. For an automated script, use Account Manager to get an authorization token for a Client ID and use that as the first factor. See [OCAPI OAuth 2.0](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/oauth.html) for details about authenticating an API client. The second factor of authentication for code uploads to staging is always a client certificate. To enforce this process of secure uploads, make sure that your configuration requires two-factor authentication for uploading code to the staging instance, and disallows code uploads to the production instance. As of August 1, 2020, Salesforce mandates these settings.

1.  See if two-factor authentication is required for uploading code to your staging instance and enable if necessary:

    1.  Log in to Business Manager on the staging instance as a user with administrative privileges.

    2.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup**.

    3.  Look at the status message under **WebDAV Access, Cartridges**.

        If the message is **A client certificate is required to upload code to this instance type**, two-factor authentication is already enabled. If the message is **A client certificate isn't required to upload code to this instance**, two factor-authentication isn’t enabled and you must enable it, as described in the next step.

    4.  To enable two-factor authentication, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Global Preferences** > **Security** > **Access Restriction** and select **Require client certificate for code uploads**.

        When you require the client certificate for code uploads, the option to configure this setting is no longer available in Business Manager. Only Salesforce Customer Support can revert the setting.

2.  See if code uploads are allowed to your production instance and disallow if necessary:

    1.  Log in to Business Manager on the production instance as a user with administrative privileges.

    2.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup**.

    3.  Look at the status message under **WebDAV Access, Cartridges**.

        If the message is **Uploading code to this instance type isn't allowed**, code uploads are disallowed to the production instance. If the message is **Uploading code to this instance type is allowed**, code uploads are allowed to production and you must disallow uploads, as described in the next step.

    4.  To disallow code uploads, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Global Preferences** > **Security** > **Access Restriction** and select **Disallow code uploads**.

        When you disallow code uploads, the option to configure this setting is no longer available in Business Manager. Only Salesforce Customer Support can revert the setting.

## Deploy and Replicate Code

Use Business Manager to replicate code from Staging to Production.

1.  Make sure you have the current updated version of the API on which the instance is running.

    1.  Make sure that deprecated APIs are accounted for in your application. (Check the `WebDav/Sites/Logs/deprecation/` directory on your server for a full list of deprecated APIs in use.) This makes sure that references to deprecated APIs are removed before the API is discontinued.

    2.  Make sure that any sandbox used for site development is upgraded at the same time as the Primary instances.

2.  Merge code in the code repository.

3.  Retrieve the collective changes from the code repository, then deploy the code to a Build/Merge instance.

4.  Use Business Manager to create a new B2C Commerce version directory on the Staging and Development instances.

    1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Code Deployment**.

    2.  Select an active version for these instances.

5.  Provide a readme.txt file in the cartridge that lists the code fixes/enhancements in this version.

6.  Copy the cartridge to the newly created version directories on Staging and Development via WebDav.

7.  Test the new version (see above consideration).

8.  Push the newly tested version to the Production instance for live usage. Use Business Manager to push code from Staging to Production. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Replication** > **Code Replication**. The replication process takes the current active version directory, creates the same version directory, then copies the cartridge code from Staging to Production.

**important:** You _must_ follow these steps for each version that is being replicated from Staging to Development and from Staging to Production. If any change, no matter how insignificant, is made to a site, it must be delivered via a version change. A new version must be created, even if it's intended to find or fix an issue that occurs with a new version, so that if a problem exists, the site can be rolled back to a known working version as quickly as possible.

## Generate, Sign, and Use Client Certificates for Secure Code Uploads

Two-factor authentication to upload code securely to the staging instance requires a username and password or authentication token as one factor and a client certificate as the second factor. Generate the client certificate and sign it with a key provided by Salesforce. Generate multiple client certificates with different expiration dates.

You must have a B2C Commerce `Certificate.zip` file to complete this procedure. Salesforce typically provides the `Certificate.zip` file as part of the realm provisioning request. Request a `Certificate.zip` file from Salesforce Customer Support if needed.

**important:** Before performing the steps in this section, make sure that your certificate is valid. Otherwise, when you attempt to upload the pkcs12 file, you will receive a `ca key too small` error. If this happens, request a new Certificate.zip file from Salesforce Customer Support.

The `Certificate.zip` file contains the following files:

- `{\<name>}.key`
- `{\<name>}.crt`
- `{\<name>}.srl`
- `{\<name>}.txt`

_\<name>_ is a unique identifier that reflects your instance or company name, plus a serial number. For `{\<name>}.srl` only, the serial number isn't included in the file name.

The `{\<name>}.txt` file contains the passphrase used to access the key. You must provide this passphrase every time you sign a key request.

The files in `Certificate.zip` are highly sensitive. A best practice is to provide the files to only a single trusted employee within your organization, typically the administrator of your B2C Commerce instances.

1.  If you're using Windows, install OpenSSL on your machine.

    If you're using MacOS or Unix operating system, you don't have to install OpenSSL. OpenSSL is provided as part of the operating system.

    1.  Download a Windows OpenSSL client from the following location: [http://www.slproweb.com/products/Win32OpenSSL.html](http://www.slproweb.com/products/Win32OpenSSL.html)

    2.  Accept the default installation instructions. OpenSSL is installed to `C:\OpenSSL`.

        These instructions assume the default installation location.

2.  Create a certificate request.

    1.  Unzip the `Certificate.zip` file.

        If you're using Windows, unzip the contents of the file to the `C:\OpenSSL\bin` directory. If you're using MacOS or a Unix operating system, use any directory of your choice.

    2.  Navigate to the directory where you unzipped the contents of `Certificate.zip`.

    3.  To generate a request, enter the following command: `openssl req -new -sha256 -newkey rsa:2048 -nodes -out {\<user>}.req -keyout {\<user>}.key`

        Salesforce B2C Commerce doesn't support client certificates with key length less than 1024 bits. We recommend that you use client certificates with at least a 2048-bit length. _\<user>_ is the user that this key is for. We recommend that _\<user>_ be the same as the corresponding Business Manager user. For example, if the B2C Commerce instance username is `jsmith`, use `jsmith` for the certificate user. Don't use a generic name like `Release Team`.

        The result of this step is similar to the following:

        ```
        Generating a 2048 bit RSA private key
        ....................
        ++++++++++++
        ........
        ++++++++++++
        writing new private key to 'user.key'
        -----
        you're about to be asked to enter information that will be incorporated into your certificate request.
        What you're about to enter is what is called a Distinguished Name or a DN.
        There are quite a few fields but you can leave some blank
        For some fields there will be a default value,
        If you enter '.', the field will be left blank.
        -----
        Country Name (2 letter code) [AU]:
        State or Province Name (full name) [Some-State]:
        Locality Name (city) []:
        Organization Name (company) [Internet Widgits Pty Ltd]:
        Organizational Unit Name (section) []:
        Common Name (YOUR name) []:
        Email Address []:
        Enter the following 'extra' attributes
        to be sent with your certificate request
        A challenge password []:
        An optional company name []:
        ```

    4.  When prompted, provide your location and name information and the email address of the person using the certificate.

        We recommend that you leave the challenge password and optional company name blank. The challenge password isn't used.

        For example:

        ```
        Country Name (2 letter code) [AU]: *US*
        State or Province Name (full name) [Some-State]: `Massachusetts`
        Locality Name (city) []:
        Organization Name (company) [Internet Widgits Pty Ltd]: `B2C Commerce`
        Organizational Unit Name (section) []: `Customer Services`
        Common Name (YOUR name) []: `John Smith`
        Email Address []: `jsmith@salesforce.com`
        Enter the following 'extra' attributes
        to be sent with your certificate request
        A challenge password []:
        An optional company name []:

        ```

    OpenSSL creates files named `{\<user>}.req` and `{\<user>}.key`, in the same directory where the contents of the `Certificate.zip` file are stored.

3.  Sign the certificate request (`{\<user>}.req`) with your certificate.

    1.  Enter the following command at the command prompt: `openssl x509 -CA {\<name>}.crt -CAkey {\<name>}.key -CAserial {\<name>}.srl -req -in {\<user>}.req -out {\<user>}.pem -days {\<days>}`

        - _\<days>_ is the number of days you want this client certificate to be valid.
        - _\<name>_ is the unique identifier provided by Salesforce, as reflected in the file names in the `Certificate.zip` file.
        - _\<user>_ is the user of the client certificate you're signing.
          For example:

        `openssl x509 -CA cert.staging.web.customer.demandware.net_01.crt -CAkey cert.staging.web.customer.demandware.net_01.key -CAserial cert.staging.web.customer.demandware.net.srl -req -in jsmith.req -out jsmith.pem -days 10`

        The result of this step is similar to the following:

        ```
        Signature ok
        subject=/C=XX/ST=XX/L=XX/O=XX/OU=XX/CN=XX/emailAddress=user@co.com
        Getting CA Private Key
        Enter pass phrase for name.key:
        ```

    2.  Enter the passphrase contained in `{\<name>}.txt` in the `Certificate.zip` file to sign the certificate.

4.  Export the certificate and client information to pkcs12 format.

    1.  Enter the following command: `openssl pkcs12 -export -in {\<user>}.pem -inkey {\<user>}.key -certfile {\<name>}.crt -name "{\<user>}" -out {\<user>}.p12`

        - _\<name>_ is the unique identifier provided by Salesforce.
        - _\<user>_ is the user of the client certificate you're signing.
          For example:

        `openssl pkcs12 -export -in jsmith.pem -inkey jsmith.key -certfile cert.staging.web.customer.demandware.net_01.crt -name "jsmith" -out jsmith.p12`

        The system prompts for an export password for the file.

    2.  Specify an export password.

        Provide the export password to the person who uses the certificate.

        The system creates files named `{\<user>}.pem` and `{\<user>}.p12` in the same directory where the contents of the `Certificate.zip` file are stored. Use the `{\<user>}.p12` file to connect to a staging instance with UX Studio, as described in the next step. Use other WebDAV clients such as the Windows built-in WebDAV client, or third-party tools such as Cyberduck.

5.  To connect to a staging instance with UX Studio, create a server connection.

    1.  Open UX Studio and click **File** > **New** > **Digital Server Connection**.

    2.  Enter the new instance URL as `cert.staging.{\<realm>}.{\<customer>}.demandware.net`.

    3.  Click the **Use Certificate Authentication** check box.

    4.  Browse to the `{\<user>}.p12` file and click **Select**.

    5.  Enter the export password for the `{\<user>}.p12` file.

    6.  Click **Finish**.

        If there is a proxy server between UX Studio and your instance, test your connection. If you can't connect to your staging instance, install the certificate on the proxy server. See your proxy server documentation for more information on uploading certificates.

    7.  If you have to extract the certificate from the pkcs12 file before uploading it to the proxy server, enter `openssl pkcs12 -in {\<user>}.p12 -clcerts -out {\<user>}.cer`

        - _\<user>_ is the user of the client certificate.
          For example:

        ```
        openssl pkcs12 -in jsmith.p12 -clcerts -out jsmith.cer
        ```

        OpenSSL prompts you for the password on the pks12 file.

## Generate, Sign, and Use Client Certificates for Secure Code Uploads (Hyperforce)

The following procedure only applies to Hyperforce B2C Commerce environments. It uses a customer-generated CA certificate and the standard staging hostname. If your realm uses the legacy Salesforce-provided `Certificate.zip` and the `cert.staging.*` hostname, use the procedure in [Generate, Sign, and Use Client Certificates for Secure Code Uploads](#generate-sign-and-use-client-certificates-for-secure-code-uploads) instead.

Two-factor authentication to upload code securely to the staging instance requires a username and password or authentication token as one factor and a client certificate as the second factor. In Hyperforce, you generate your own CA (Certificate Authority) certificate, upload it to eCDN, then sign client certificates with that CA. You can generate multiple client certificates with different expiration dates.

**note:** Hyperforce changes two-factor code upload because code uploads use the standard Business Manager staging hostname, for example, `staging-<realm>-<customer>.demandware.net` or your realm-specific hostname. There's no separate hostname for code uploads. The legacy `cert.staging.<realm>.<customer>.demandware.net` pattern is deactivated for Hyperforce. Regular Business Manager login doesn't require a client certificate, and the client certificate is only required for **code uploads** (and related WebDAV operations). Salesforce doesn't receive or store your CA bundle—you generate and register it with eCDN yourself. Initial upload and **rotation** of the CA are self-service. The CA certificate bundle has a maximum validity of 365 days.

Before and after migration: Until your realm has migrated to Hyperforce, continue to use existing client certificates with the legacy `cert.staging` hostname if applicable. After migration, generate new client certificates signed by your uploaded CA and use the standard Business Manager hostname.

### 1. Generate your CA Certificate and Private Key

You must create a self-signed CA certificate bundle yourself. Salesforce does not provide a `Certificate.zip` for Hyperforce. The platform accepts client certificates signed by a CA that you upload to eCDN.

1.  If you're using Windows, install OpenSSL on your machine. On macOS or Unix, OpenSSL is typically provided by the operating system.

    - Windows: Download from [Win32 OpenSSL](http://www.slproweb.com/products/Win32OpenSSL.html) and accept the default installation (for example, `C:\OpenSSL`).

2.  Set a host identifier and generate the CA certificate and private key. A common choice is to align `${CERT_HOST}` with your staging hostname, replacing `<realm>` and `<customer>` with your values:

    ```bash
    CERT_HOST=staging-<realm>-<customer>.demandware.net
    openssl req -new -newkey rsa:2048 -sha256 -days 365 -x509 -nodes -keyout ${CERT_HOST}.key -out ${CERT_HOST}.crt
    ```

    When prompted, enter the Distinguished Name (DN) details for your CA. For **Common Name**, use the same value as `${CERT_HOST}` (for example, `staging-realm-customer.demandware.net`). Leave the challenge password and optional company name blank if you don't need them.

    This produces:

    - `${CERT_HOST}.key` — CA private key (keep this secure).
    - `${CERT_HOST}.crt` — CA certificate (you will upload this to eCDN along with the key).

    B2C Commerce doesn't support client certificates with key length less than 1024 bits. Use at least 2048-bit keys for the CA and for client certificates. The CA certificate can't exceed **365 days** validity.

### 2. Upload the CA Certificate to eCDN

Upload your self-generated CA certificate and private key to eCDN so the platform will accept client certificates signed by your CA.

**Option 1 — Business Manager**

1.  Log in to Business Manager on your **staging** instance.
2.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and go to **Administration** > **Site Development** > **Code Upload Certificate** (tab).
3.  Click **Add Certificate**. Enter a **Certificate Name** (for your own organization), then paste the **Certificate** and **Private Key** contents from the `.crt` and `.key` files you generated, and save.

After you save, eCDN is configured to accept client certificates signed by this CA.

**(Optional) Remove unused or expired CAs:** Multiple CA certificates can be active at the same time. You can delete unused, expired, or compromised CA certificates from the same **Code Upload Certificate** page.

![Code Upload Certificate in Site Development](https://developer.salesforce.com/media/b2c-commerce/b2c_code_deployment_hyperforce_add_certificate.png)
![Uploaded Code Deployment Certificate in Site Development](https://developer.salesforce.com/media/b2c-commerce/b2c_code_deployment_hyperforce_upload_certificate.png)

**Option 2 — CDN API**

Use the Commerce CDN API to upload, list, and delete code-upload CA certificates programmatically. You need an API client with the correct OAuth scopes and an access token for the **Authorization** header. You can send requests with `curl`, Postman, or another HTTP client.

#### Format the Certificate and Private Key for the API Request Body

The CDN API expects the certificate and private key as **single-line strings** in JSON, with **literal** `\n` characters where line breaks were in the PEM file.

From a shell (example using Perl):

```bash
cat ${CERT_HOST}.crt | perl -pe 's/\n/\\n/g'
cat ${CERT_HOST}.key | perl -pe 's/\n/\\n/g'
```

Or use a text editor that supports regular expressions (for example, Sublime Text):

1. Open the `.crt` file.
2. Open **Find** → **Replace**.
3. Enable **Regular expression** mode.
4. **Find:** `\n` — **Replace:** `\\n`
5. Click **Replace All**, then save. Repeat for the `.key` file.

Use the reformatted strings as the `certificate` and `privateKey` values in the JSON body (keep `-----BEGIN CERTIFICATE-----` / `-----END CERTIFICATE-----` and `-----BEGIN PRIVATE KEY-----` / `-----END PRIVATE KEY-----` boundaries as required by the API).

#### Obtain an Access Token

Follow [Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) to authenticate your API client. The OAuth scope required for CDN API calls that manage code-upload certificates includes **`sfcc.cdn-zones.rw`**.

Reference example (client credentials)—replace `<api_client_id>`, `<client_secret>`, and `<realm>` with your values:

```bash
curl "https://account.demandware.com/dwsso/oauth2/access_token" \
  --request POST \
  --user "<api_client_id>:<client_secret>" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=client_credentials" \
  --data-urlencode "scope=SALESFORCE_COMMERCE_API:<realm>_stg sfcc.cdn-zones.rw"
```

#### Upload the CA Certificate (Create)

Replace `<shortcode>`, `<realmid>`, and the bearer token with your values. Replace `certificate` and `privateKey` with the reformatted strings from the previous step.

```bash
curl --location "https://<shortcode>.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_<realmid>_stg/mtls/code-upload-certificates" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <access_token>" \
  --data '{
    "name": "client ca for code upload",
    "certificate": "-----BEGIN CERTIFICATE-----\n<certificate_pem_with_literal_newlines>\n-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\n<private_key_pem_with_literal_newlines>\n-----END PRIVATE KEY-----"
}'
```

#### List Code Upload Certificates

Use a **GET** request to retrieve existing certificates (including `mtlsCertificateId` values for deletes):

```bash
curl --location "https://<shortcode>.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_<realmid>_stg/mtls/code-upload-certificates" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <access_token>"
```

#### Delete a Code Upload Certificate

Use the `mtlsCertificateId` from the list response. Example:

```bash
curl --location --request DELETE "https://<shortcode>.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_<realmid>_stg/mtls/code-upload-certificates/<mtlsCertificateId>" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <access_token>"
```

#### CDN API Troubleshooting

- 401 Unauthorized or 403 Forbidden: Confirm the API client default and allowed scopes. Default scopes often include values such as `mail`, `roles`, `tenantFilter`, `profile`, and `openId`. Allowed scopes must include `sfcc.cdn-zones` and `sfcc.cdn-zones.rw`. Verify the client ID, secret, and token request.
- Certificate can't be parsed: Recheck PEM-to-JSON formatting (literal `\n` only). Confirm the certificate and private key are a matching pair using a certificate/key matcher tool in **original** PEM file form (not the JSON-escaped form)—for example, [SSL Checker matcher](https://www.sslchecker.com/matcher).

### 3. Create a client certificate request

Create one client certificate **per user** who uploads code; each can be signed with the same CA.

1.  Navigate to a working directory (for example, the same folder as your CA files, or a dedicated directory for client certs).

2.  Generate a client certificate request and private key. Use `<user>` as the Business Manager username (for example, `jsmith`). You can set `USER=<bm_username>` in your shell and use `${USER}` in place of `<user>` in the file names as shown in this example. Run:

    ```bash
    openssl req -new -sha256 -newkey rsa:2048 -nodes -out <user>.req -keyout <user>.key
    ```

    When prompted, enter location, name, and email. We recommend leaving the challenge password and optional company name blank. OpenSSL creates `<user>.req` and `<user>.key`.

### 4. Sign the Client Certificate with Your CA

Sign the client request using your CA certificate and key (the same `${CERT_HOST}` used in step 1). OpenSSL will create or update a serial file (for example, `${CERT_HOST}.srl`) when you sign. Run:

```bash
openssl x509 -CA ${CERT_HOST}.crt -CAkey ${CERT_HOST}.key -CAcreateserial -req -in <user>.req -out <user>.pem -days <days>
```

- _\<days>_ is the number of days the client certificate is valid.
- If you already have a serial file, you can use `-CAserial ${CERT_HOST}.srl` instead of `-CAcreateserial`.

Example (CA named `mycompany-ca`, user `jsmith`, valid 365 days):

```bash
openssl x509 -CA mycompany-ca.crt -CAkey mycompany-ca.key -CAcreateserial -req -in jsmith.req -out jsmith.pem -days 365
```

If your CA key was created with a passphrase, OpenSSL will prompt for it.

### 5. Export the Signed Certificate to PKCS#12 (.p12)

Export the signed client certificate and key to a `.p12` file for use with UX Studio or other WebDAV clients.

**note:** You must include the `-legacy` flag so that newer versions of OpenSSL produce a `.p12` file that can be imported into Mac keychains and other tools.

```bash
openssl pkcs12 -export -legacy -in <user>.pem -inkey <user>.key -certfile ${CERT_HOST}.crt -name "<user>" -out <user>.p12
```

Example:

```bash
openssl pkcs12 -export -legacy -in jsmith.pem -inkey jsmith.key -certfile mycompany-ca.crt -name "jsmith" -out jsmith.p12
```

Specify an export password when prompted and provide it to the person who will use the certificate. You can use the `<user>.p12` file to connect to your staging instance with UX Studio or other WebDAV clients (for example, Cyberduck).

### 6. Connect to the Staging Instance

Use the standard Business Manager staging hostname for your realm, for example, `staging-na01-<customer>.demandware.net`. Don't use the legacy `cert.staging.<realm>.<customer>.demandware.net` hostname. That hostname is deactivated for Hyperforce.

1.  Open UX Studio and click **File** > **New** > **Digital Server Connection**.
2.  Enter the instance URL using your standard staging hostname (for example, `https://staging-na01-<customer>.demandware.net`).
3.  Select **Use Certificate Authentication** and browse to the `<user>.p12` file.
4.  Enter the export password for the `.p12` file and click **Finish**.

If a proxy sits between UX Studio and your instance, you may need to install the client certificate on the proxy. To extract the certificate from the `.p12` file for proxy or other use:

```bash
openssl pkcs12 -in <user>.p12 -clcerts -out <user>.cer
```

OpenSSL will prompt for the `.p12` export password.

### 7. Rotate or Renew the CA Certificate

The CA certificate bundle is limited to a maximum of one year (365 days). Before it expires, generate and upload a new CA so code uploads aren't interrupted. Follow the same procedure if the CA private key or any client certificate signed by it may have been compromised.

1.  Generate a new self-signed CA (new `${CERT_HOST}` or new files) and upload it using Business Manager or the CDN API, following **Upload the CA certificate to eCDN** earlier in this topic.
2.  Overlap is supported: Multiple CA bundles can be active at the same time. Keep the old CA active while you issue new client certificates signed by the new CA and confirm code uploads work with the standard staging hostname.
3.  Re-sign users: Each user needs a new `.p12` signed by the new CA. Repeat **Create a client certificate request**, **Sign the client certificate with your CA**, and **Export the signed certificate to PKCS#12 (.p12)** using the new `${CERT_HOST}.crt` and `.key`.
4.  After all users have switched and you have validated uploads, remove the old CA on the **Code Upload Certificate** page in Business Manager, or call the CDN API `DELETE` endpoint with the old certificate's `mtlsCertificateId`.

## Collaborative Development and Deployment

The Salesforce B2C Commerce architecture supports multiple Sandbox instances where individual developers can work on discrete portions of an application, making efficient use of resources. At release time, developers file their changes back into a source control system for consolidation and testing.

Eclipse comes with a built-in client for the Concurrent Versions System (CVS). Use another system, such as Subversion (SVN) for your code repository. Many code repository/version control systems use a branch model to support multiple courses of work that are somewhat isolated from each other, yet still highly interdependent. This model supports individuals working on a team project, sharing their work with others as changes are made, and accessing the work of others as the project evolves. As team members produce new work, they share their work by committing their changes to the branch. Similarly, when they want to get the latest available work, they update their local workspaces to the changes on the branch. Thus the branch is constantly changing, moving forward as team members submit new work.

As a B2C Commerce development team member, it is important that you implement both a code repository/version control system and a versioning plan that follows a standard process. This process includes deploying/replicating code from the developer's sandbox instance to various other instances for integration and testing, and final deployment to Production.

## Software Deployment Stages

The software deployment stages for B2C Commerce development include Sandbox, Build and Merge, Staging, Development, and Production.

The following table describes the software deployment stages :

| Instance    | Description                                                                                                                                                                                                                                     | Considerations                                                                                                                                                                                                                                             |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Sandbox     | Each development team gets one sandbox per developer and one sandbox to be used as a Build/Merge instance.                                                                                                                                      | Each developer is responsible for their own sandbox, where they build code, metadata, custom objects.                                                                                                                                                      |
| Build/Merge | As a project progresses and interval version points are reached, developers merge their code/data on a Build/Merge instance, where internal QA is done.                                                                                         | Designate one of your sandbox instances as the Build/Merge instance, specifically for testing major releases. This means that of the three sandbox instances provided for in a subscription, only two can be used by individual developers.                |
| Staging     | As development continues, builds are moved from the Build/Merge instance to the Staging instance, where they are replicated to the Development instance for internal/external QA.                                                               | Major releases _can't_ be tested on the Staging, because they can include incompatible data definitions. Therefore, data replication _can't_ be performed to the Production instance during the test phase.                                                |
| Development | Some customers use the Development instance to test the data and code replication process before replicating to Production. Others use the Development instance as a secondary Staging instance, where another version is prepared in parallel. | When new code versions include changes to object or preference definitions or introduce new sites or catalogs, they _can't_ be created and tested on a Development instance. This disqualifies the Development instance for the testing of major releases. |
| Production  | When testing is complete, the release is pushed to the Production instance.                                                                                                                                                                     | Having the same version on Development as on Production lets Support and Solution Support Engineers use the Development version for testing if problems occur on Production.                                                                               |

This process is repeated as the development cycle continues. The development team must determine (based on the number and severity of bugs outstanding):

- When an internal build is ready to be deployed to the Build/Merge instance.
- When the build is ready to be pushed to Staging for replication.
- When the build is ready for Production.

<!-- document id=422fc6d4cc9fd473b74c803ddf7ec8507fa6dfbb2ab63a304fa226c8812d29a3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-cli.md -->

# Command-Line Interface (CLI) Reference

The `sfnext` CLI is your primary tool for developing and deploying Storefront Next projects. It's provided by the `@salesforce/storefront-next-dev` package, which is installed as a project dependency—not globally.

## Running CLI Commands

### Using Project `package.json` Scripts

Storefront Next projects include pre-configured scripts in `package.json` for common tasks:

```bash
pnpm dev        # Start the development server
pnpm build      # Create a production build
pnpm start      # Preview the production build locally
pnpm push       # Deploy to Managed Runtime
```

### Running Commands Directly

For commands that don't have a `package.json` script, or when you need to pass specific options, run `pnpm sfnext` from your project's root directory:

```bash
pnpm sfnext <command> [options]
```

For example:

```bash
pnpm sfnext dev --port 3000
pnpm sfnext extensions list
```

You can also view all available commands and options:

```bash
pnpm sfnext --help
pnpm sfnext <command> --help
```

This works because `pnpm` automatically resolves binaries installed in your project's `node_modules/.bin`. Running `sfnext` this way ensures the CLI version always matches your project's dependencies.

**important:** Don’t install `@salesforce/storefront-next-dev` globally. Always run commands from within your project directory so that the CLI version stays in sync with your dependencies.

### Creating a Storefront Without a Project

The `create-storefront` command is the one exception—it runs _before_ a project exists, so there's no local `node_modules` to resolve from. For this command, use `pnpm dlx` to download and execute the package directly:

```bash
pnpm dlx @salesforce/storefront-next-dev create-storefront
```

For all other commands, use `pnpm sfnext` from within your project.

## Commands

| Command                                   | package.json Script | Description                                                |
| ----------------------------------------- | ------------------- | ---------------------------------------------------------- |
| [`create-storefront`](#create-storefront) | —                   | Scaffold a new storefront project from a template.         |
| [`dev`](#dev)                             | `pnpm dev`          | Start the development server with hot module replacement.  |
| [`preview`](#preview--start)              | `pnpm start`        | Preview a production build locally.                        |
| [`push`](#push)                           | `pnpm push`         | Build a bundle and deploy it to Managed Runtime.           |
| [`create-bundle`](#create-bundle)         | —                   | Create a deployment bundle without pushing.                |
| [`extensions`](#extensions)               | —                   | Manage feature extensions (install, remove, create, list). |

## `create-storefront`

Scaffold a new Storefront Next project. The command clones a template repository, walks you through extension selection, and configures your environment variables.

Because this command creates a new project, it's the one CLI command you run _before_ a project exists. Use `pnpm dlx` to download and run it without a prior installation:

```bash
pnpm dlx @salesforce/storefront-next-dev create-storefront [options]
```

### Options

| Option                           | Description                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `-n, --name <name>`              | Name for the storefront. Skips the interactive prompt.                                         |
| `-t, --template <template>`      | Template URL or local path (for example, a GitHub URL or `file:///path/to/template`).          |
| `-l, --local-packages-dir <dir>` | Local monorepo packages directory. Used with `file://` templates to pre-fill dependency paths. |
| `-v, --verbose`                  | Enable verbose output.                                                                         |

### Examples

Create a storefront interactively:

```bash
pnpm dlx @salesforce/storefront-next-dev create-storefront
```

Create a storefront with a specific name:

```bash
pnpm dlx @salesforce/storefront-next-dev create-storefront --name my-storefront
```

After the command completes, follow the on-screen instructions to install dependencies and start developing:

```bash
cd my-storefront
pnpm install
pnpm build
pnpm dev
```

For a walkthrough of creating a storefront with the CLI, see [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-sf.md).

## `dev`

Start a local development server powered by Vite with full server-side rendering (SSR) support. The server includes hot module replacement (HMR) for both client and server code, and an API proxy to B2C Commerce.

```bash
pnpm dev
```

Or with options:

```bash
pnpm sfnext dev [options]
```

### Options

| Option                          | Description                     | Default           |
| ------------------------------- | ------------------------------- | ----------------- |
| `-d, --project-directory <dir>` | Path to the project directory.  | Current directory |
| `-p, --port <port>`             | Port number for the dev server. | `5173`            |

### Examples

Start the dev server:

```bash
pnpm dev
```

Start the dev server on a custom port:

```bash
pnpm sfnext dev --port 3000
```

Start with the Node.js debugger attached:

```bash
pnpm dev:debug
```

### What the Dev Server Does

- Runs Vite in middleware mode within an Express server for full SSR support.
- Proxies B2C Commerce API requests through `/mobify/proxy/api` so that you can develop against live data without CORS issues.
- Loads environment variables from your `.env` file.
- Prints your Commerce API configuration (short code, organization ID, site ID) at startup.

## `preview` / `start`

Start a local server that serves your production build. Use this to test production behavior before deploying. If no build exists, the command automatically runs `pnpm build` first.

The CLI command is `preview`. In `package.json`, it's mapped to `pnpm start`.

```bash
pnpm start
```

Or with options:

```bash
pnpm sfnext preview [options]
```

### Options

| Option                          | Description                         | Default           |
| ------------------------------- | ----------------------------------- | ----------------- |
| `-d, --project-directory <dir>` | Path to the project directory.      | Current directory |
| `-p, --port <port>`             | Port number for the preview server. | `3000`            |

### Examples

Preview the production build:

```bash
pnpm start
```

Preview on a custom port:

```bash
pnpm sfnext preview --port 8080
```

### How Preview Differs from Dev

| Feature              | `dev`                            | `preview`                    |
| -------------------- | -------------------------------- | ---------------------------- |
| Build type           | On-the-fly via Vite              | Pre-built production bundle  |
| HMR                  | Yes                              | No                           |
| Static asset serving | Vite handles                     | Express with compression     |
| Performance          | Optimized for speed of iteration | Reflects production behavior |

## `push`

Create a deployment bundle from your production build and push it to Managed Runtime (MRT). You must build your project before running this command.

```bash
pnpm push
```

Or with options:

```bash
pnpm sfnext push [options]
```

### Options

| Option                        | Description                                       | Default                                             |
| ----------------------------- | ------------------------------------------------- | --------------------------------------------------- |
| `--project-directory <dir>`   | Path to the project directory.                    | Current directory                                   |
| `-b, --build-directory <dir>` | Path to the build output directory.               | Auto-detected                                       |
| `-m, --message <message>`     | Descriptive message for the bundle.               | `git branch:commit`                                 |
| `-p, --project <slug>`        | Unique project identifier on Managed Runtime.     | From `SFCC_MRT_PROJECT` or `MRT_PROJECT` env var    |
| `-e, --environment <target>`  | Target environment to deploy to.                  | From `SFCC_MRT_ENVIRONMENT` or `MRT_TARGET` env var |
| `-w, --wait`                  | Wait for the deployment to finish before exiting. | `false`                                             |
| `--api-key <key>`             | API key for MRT authentication.                   | From `SFCC_MRT_API_KEY` env var                     |
| `--credentials-file <file>`   | Path to the MRT credentials file.                 | From `MRT_CREDENTIALS_FILE` env var                 |
| `--cloud-origin <origin>`     | MRT API origin URL.                               | Production default                                  |
| `--config <path>`             | Path to `dw.json` config file.                    | Auto-discovered from project directory              |
| `-i, --instance <name>`       | Named instance from config file.                  | From `SFCC_INSTANCE` env var                        |

### Authentication

Authenticate with Managed Runtime using one of these methods:

- **Credentials file** (default): The CLI reads stored credentials automatically. Use `--credentials-file` to specify a custom path.
- **API key**: Pass `--api-key` on the command line or set the `SFCC_MRT_API_KEY` environment variable.

### Setting Up MRT Resources

Before you can deploy, you need a Managed Runtime project and SLAS client credentials. Use the [B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/storefront-next.html#storefront-next) to create these resources.

### Examples

Build and deploy to MRT:

```bash
pnpm build
pnpm push
```

Deploy to a specific environment and wait for completion:

```bash
pnpm sfnext push --environment staging --wait
```

Deploy with an API key:

```bash
pnpm sfnext push --api-key your-api-key
```

## `create-bundle`

Create a deployment bundle and save it to disk without pushing to Managed Runtime. This is useful for inspecting bundle contents or integrating with custom deployment pipelines.

```bash
pnpm sfnext create-bundle -d <project-directory> [options]
```

### Options

| Option                          | Description                                   | Default                                          |
| ------------------------------- | --------------------------------------------- | ------------------------------------------------ |
| `-d, --project-directory <dir>` | **(Required)** Path to the project directory. |                                                  |
| `-b, --build-directory <dir>`   | Path to the build output directory.           | Auto-detected                                    |
| `-o, --output-directory <dir>`  | Directory where bundle files are written.     | `.bundle`                                        |
| `-m, --message <message>`       | Descriptive message for the bundle.           | `git branch:commit`                              |
| `-s, --project-slug <slug>`     | Unique project identifier on Managed Runtime. | From `.env` `MRT_PROJECT` or `package.json` name |

### Output

The command generates two files in the output directory:

- `bundle.tgz` — The compressed deployment bundle.
- `bundle.json` — Bundle metadata (message, SSR parameters, file sizes).

### Example

```bash
pnpm build
pnpm sfnext create-bundle -d . -o ./my-bundle
```

## `extensions`

Manage feature extensions for your storefront project. Extensions add pre-built functionality, such as store locators or theme switchers.

```bash
pnpm sfnext extensions <subcommand> [options]
```

### `extensions list`

List all extensions currently installed in your project.

```bash
pnpm sfnext extensions list [options]
```

| Option                          | Description                    | Default           |
| ------------------------------- | ------------------------------ | ----------------- |
| `-d, --project-directory <dir>` | Path to the project directory. | Current directory |

#### Example

```bash
pnpm sfnext extensions list
```

### `extensions install`

Install an extension from a source template repository. The CLI clones the source repository, lets you select an extension, and copies the extension files into your project.

```bash
pnpm sfnext extensions install [options]
```

| Option                          | Description                                                                                              | Default                          |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `-d, --project-directory <dir>` | Path to the target project directory.                                                                    | Current directory                |
| `-e, --extension <extension>`   | Extension marker value to install (for example, `SFDC_EXT_STORE_LOCATOR`). Skips the interactive prompt. |                                  |
| `-s, --source-git-url <url>`    | Git URL of the source template that contains extensions.                                                 | Default Storefront Next template |
| `-v, --verbose`                 | Enable verbose output.                                                                                   |                                  |

If the extension has dependencies on other extensions, the CLI detects them and installs the full dependency chain in the correct order.

#### Examples

Install an extension interactively:

```bash
pnpm sfnext extensions install
```

Install a specific extension by marker:

```bash
pnpm sfnext extensions install -e SFDC_EXT_STORE_LOCATOR
```

### `extensions remove`

Remove one or more installed extensions from your project. The CLI automatically detects and removes dependent extensions.

```bash
pnpm sfnext extensions remove [options]
```

| Option                          | Description                                                                                                                                        | Default           |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `-d, --project-directory <dir>` | Path to the project directory.                                                                                                                     | Current directory |
| `-e, --extensions <extensions>` | Comma-separated list of extension markers to remove (for example, `SFDC_EXT_STORE_LOCATOR,SFDC_EXT_THEME_SWITCHER`). Skips the interactive prompt. |                   |
| `-v, --verbose`                 | Enable verbose output.                                                                                                                             |                   |

#### Example

Remove extensions interactively:

```bash
pnpm sfnext extensions remove
```

Remove specific extensions by marker:

```bash
pnpm sfnext extensions remove -e SFDC_EXT_STORE_LOCATOR
```

### `extensions create`

Scaffold a new extension in your project. This command creates the extension directory structure with placeholder folders for components, hooks, locales, and routes.

```bash
pnpm sfnext extensions create [options]
```

| Option                            | Description                                            | Default           |
| --------------------------------- | ------------------------------------------------------ | ----------------- |
| `-p, --project-directory <dir>`   | Path to the project directory.                         | Current directory |
| `-n, --name <name>`               | Name of the extension (for example, `"My Extension"`). |                   |
| `-d, --description <description>` | Description of the extension.                          |                   |

#### Example

```bash
pnpm sfnext extensions create --name "Store Locator" --description "Find nearby stores"
```

The generated directory structure:

```
src/extensions/store-locator/
  components/
  hooks/
  locales/
  routes/
  README.md
```

## Environment Variables

Several CLI commands read configuration from environment variables defined in your `.env` file.

| Variable                                     | Used By                 | Description                                                    |
| -------------------------------------------- | ----------------------- | -------------------------------------------------------------- |
| `SFCC_MRT_PROJECT`                           | `push`, `create-bundle` | Project slug for Managed Runtime.                              |
| `SFCC_MRT_ENVIRONMENT`                       | `push`                  | Deployment target environment.                                 |
| `SFCC_MRT_API_KEY`                           | `push`                  | API key for MRT authentication.                                |
| `SFCC_PROJECT_DIRECTORY`                     | All commands            | Project directory (alternative to `--project-directory` flag). |
| `MRT_PROJECT`                                | `push`, `create-bundle` | Legacy alias for `SFCC_MRT_PROJECT`.                           |
| `MRT_TARGET`                                 | `push`                  | Legacy alias for `SFCC_MRT_ENVIRONMENT`.                       |
| `PUBLIC__app__commerce__api__shortCode`      | `dev`, `preview`        | B2C Commerce API short code.                                   |
| `PUBLIC__app__commerce__api__organizationId` | `dev`, `preview`        | B2C Commerce organization ID.                                  |
| `PUBLIC__app__commerce__api__clientId`       | `dev`, `preview`        | B2C Commerce client ID.                                        |
| `PUBLIC__app__commerce__api__siteId`         | `dev`, `preview`        | B2C Commerce site ID.                                          |

## See Also

- [Build Tools](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-build-tools.md) — Vite configuration and build system details.
- [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md) — Environment variables and storefront configuration.
- [B2C CLI: Storefront Next](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/storefront-next.html#storefront-next) — Create SLAS clients and Managed Runtime resources.

<!-- document id=bac9adf059939f7bf2d1a137d8bdadb70bcd13c7de65e70c8f2e14e5901a6735 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/commerce-apps-overview.md -->

# Commerce Apps Overview

A Commerce App is a packaged, installable solution that bundles frontend UI components, backend server-side code, admin configuration, and platform data into a single deployable unit called a Commerce App Package (CAP). Commerce Apps represent the evolution of the Commerce Cloud cartridge model into a marketplace-ready packaging format designed for plug-and-play installation.

This guide is for two audiences who share the same CAP format and install job:

- **ISVs** publish to the [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps). Merchants discover those apps in Business Manager and click to install.
- **SIs** build merchant-specific **private** apps. They install from WebDAV (`AppSource=WebDAV`, feature type `CUSTOM_APP`) and don't appear in the Cart & Checkout Hub catalog. See [Develop a Private Commerce App](/docs/commerce/b2c-commerce/guide/private-commerce-apps.md).

For merchants, public Commerce Apps are discoverable in Business Manager. For ISV and SI developers, Commerce Apps can be managed through pro-code CLI solutions with automated local-to-cloud deployments and CI/CD integration. Both paths converge on the same platform framework.

The framework automates the orchestration of back-end extensions (cartridges, hooks) and frontend UI components for Storefront Next, significantly reducing implementation costs and time-to-value across the entire development lifecycle.

![Commerce Apps Framework Architecture](https://developer.salesforce.com/media/b2c-commerce/commerce-apps-framework-architecture.png)

## What Can a Commerce App Contain?

A Commerce App can include any combination of the following:

- **Storefront Next extensions:** React components, React hooks, routes, and data providers that render in UI target locations across the storefront (PDP, PLP, Cart, Checkout, My Account, and so on).

- **Backend cartridges:** Server-side scripts, controllers, and hooks that implement business logic. These include both site cartridges (storefront logic) and BM cartridges (admin functionality).

  - **Domain-specific hook implementations:** Script API implementations that fulfill platform-defined extension point contracts (for example, `sfcc.app.tax.calculate`).

  - **Custom SCAPIs:** Custom API endpoints for headless/API-driven backend functionality.

  - **IMPEX data:** Site-scoped XML for services, jobs, site preferences, custom object definitions, and metadata. Includes both install and uninstall payloads.

- **App configuration:** A `tasksList.json` file that defines the post-install configuration wizard steps a merchant must complete to activate the app.

- **App manifest:** A `commerce-app.json` file that defines the app's identity, version, domain, and publisher information. See [commerce-app.json Schema](/docs/commerce/b2c-commerce/guide/reference.md#commerce-appjson-schema).

Depending on what you build, your app follows one of three architectures: **UI-only** (frontend extensions only), **Backend-only** (extension point hook implementations only), or **Fullstack** (both frontend and backend, with two sub-types: extension points or custom SCAPI). See [The Three Architectures for Commerce Apps](/docs/commerce/b2c-commerce/guide/architecture.md#the-three-architectures-for-commerce-apps) for details.

## How Commerce Apps Differ from Cartridges

Commerce Cloud developers are familiar with cartridges as the primary unit of extensibility. Commerce Apps build on cartridges but add significant new capabilities:

- **Automated installation:** No more manual cartridge uploads, path editing, or IMPEX imports. The platform handles all of this through a single install job.

- **Frontend orchestration:** If your Commerce App includes Storefront Next components, installation can create a pull request that adds them to the merchant's storefront repository. The UI Targets framework then renders these components in the appropriate locations.

- **Domain isolation:** Commerce Apps introduce domain-specific extension points (for example, `sfcc.app.tax.calculate` instead of the shared `dw.order.calculateTax`) that eliminate code conflicts between integrations.

- **State tracking:** The platform tracks installation status, configuration progress, and activation state per-site through the CommerceFeatureState system.

- **Optional registry distribution:** ISVs can publish apps to the centralized [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps) for discovery and installation. Private apps use WebDAV instead.

## Quick Start with Claude Code

Use Claude Code's `/scaffold-app` skill to scaffold a new Commerce App in seconds. The skill generates a complete app directory structure with templates for `commerce-app.json`, `tasksList.json`, and starter IMPEX files. Additional skills for IMPEX generation (`/generate-service-impex`, `/generate-site-preferences-impex`), validation (`/validate-app`), and packaging (`/package-app`) are also available. See [Development Environment Setup](/docs/commerce/b2c-commerce/guide/development-environment.md#claude-code-skills) for the full list.

## Commerce App Development Lifecycle

Building a Commerce App follows this lifecycle:

1. [Understand the architecture](/docs/commerce/b2c-commerce/guide/architecture.md): domains, extension points, UI targets, and the three architectures.

2. [Set up your development environment](/docs/commerce/b2c-commerce/guide/development-environment.md) and sandbox.

3. [Build your app](/docs/commerce/b2c-commerce/guide/building-your-app.md): implement extension points, build UI extensions, create IMPEX data.

4. [Package your app](/docs/commerce/b2c-commerce/guide/packaging.md) into a Commerce App Package (CAP) following the required structure.

5. [Test and validate](/docs/commerce/b2c-commerce/guide/testing-validation.md) on a sandbox. ISVs also use the [review checklist](/docs/commerce/b2c-commerce/guide/testing-validation.md#review-checklist) before registry submission.

6. **Distribute:**
   - **ISVs:** [Publish to the App Registry](/docs/commerce/b2c-commerce/guide/submission-review.md) for review and BM discoverability.
   - **SIs:** [Install privately](/docs/commerce/b2c-commerce/guide/private-commerce-apps.md) with `b2c cap install` (WebDAV). Do not open a registry PR.

7. [Maintain](/docs/commerce/b2c-commerce/guide/post-publication.md) the installed app (replication, multi-site, monitoring). Registry versioning applies to ISVs only.

<!-- document id=af80f1d3f291873ec681566a9c71548a31c8a55ff6be75708619b999f1c111cb url=/developer/current/en-us/commerce-cloud/sfra/guides/sfra-community-cloud-community-suite.md -->

# Commerce Community Suite

The Commerce Community Suite is a selection of tools and libraries that you can use in your projects. We’ve chosen the tools based on their popularity and interoperability.

Unless you’re using another build tool, we also recommend using the Build Suite to deploy to environments in the primary instance group (staging, for example). As a best practice, don’t deploy to production systems by connecting your local workspace.

**tip:** Only existing customers can access some of the following links. Visit [Access the GitHub Repositories](https://trailhead.salesforce.com/content/learn/modules/b2c-developer-resources-and-tools/b2c-developer-access-repositories) for information about how to get access to the Community Suite repositories.

## Product Tools

[Storefront Reference Architecture](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture)

Check out this repository for the Storefront Reference Architecture (SFRA) reference application.

## SOM-SFRA Self-Service Plugin

[SOM-SFRA Self-Service Plugin](https://github.com/SalesforceCommerceCloud/plugin_ordermanagement)

Check out this repository for the Salesforce Order Management - SFRA Self-Service Plugin. This plugin enhances the `app_storefront_base` cartridge by providing "Salesforce Order Management self-service" functionality.

## Community Suite

[Page Designer Reference Implementation](https://github.com/SalesforceCommerceCloud/page-designer-reference)

This resource contains example page types and component types for Salesforce B2C Commerce Page Designer. Use these examples as a starting point for developing your own custom page types and component types.

[SFRA Themes Plugin](https://github.com/SalesforceCommerceCloud/plugin_themes)

This plugin enhances the Storefront Reference Architecture (SFRA) by providing theming capabilities using Page Designer. Modify the look and feel of your website with clicks not code!

[Instance Initializer](https://github.com/SalesforceCommerceCloud/instance-initializer)

Create and initialize a sandbox by deploying code and data, and bootstrapping the instance (that is, building the search index, installing plugins, and so on). Use this tool to quickly spin up a [Storefront Reference Architecture](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture) Demo Box. This tool also provides examples on how to use [sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci).

[SFRA Service Worker Plugin](https://github.com/SalesforceCommerceCloud/plugin_serviceworker)

This service worker plugin for Storefront Reference Architecture (SFRA) includes basic Progressive Web Apps (PWA) features and advanced caching capabilities.

[Style Guide](https://github.com/SalesforceCommerceCloud/styleguide)

The coding style guide applies a defined set of standards to the development process. It includes ESLint configuration files so that you can automate code checks.

[SFRA Webpack Builder](https://github.com/SalesforceCommerceCloud/sfra-webpack-builder)

Because webpack can be cumbersome to set up, especially in multicartridge projects for SFRA, use this plugin to bundle all your .js, .scss, and .jsx files out of the box.

[Unit Testing / DW API Mock](https://github.com/SalesforceCommerceCloud/dw-api-mock/)

The API mock provides the B2C Commerce API as stubs and instructions on how to use this stub with Mocha JS to create and run unit tests for B2C Commerce scripts. The tests run in a Node.js environment and can be embedded into build scripts or BitBucket pipelines.

[Build Suite](https://github.com/SalesforceCommerceCloud/build-suite)
The Build Suite is a popular and well-tested JavaScript tool powered by Grunt. Use a set of scripts to automate your build processes and add additional value. The Build Suite offers numerous features such as Linting (server-side DS files), resource optimization, Storefront Toolkit Build information, test files, and two-factor authentication (2FA).

[B2C Commerce CI](https://github.com/SalesforceCommerceCloud/sfcc-ci)

The Salesforce B2C Commerce CI is a command-line interface (CLI) for interacting with B2C Commerce instances from the command line or shell of various operating systems to facilitate Continuous Integration practices. It provides a JavaScript API that you can use to integrate with higher-level build tools, such as the Build Suite.

[Custom Feeds](https://github.com/SalesforceCommerceCloud/custom-feeds)

Use Custom Feeds to define extra export feeds in XML or CSV format. Check out the detailed instructions. Provide catalog feeds to marketing providers, such as Google Shopping or ad agencies.

[Simple Ratings & Reviews](https://github.com/SalesforceCommerceCloud/simple-r-r)

Simple Ratings & Reviews uses custom objects to let customers submit reviews, and aggregates the numbers later (number of reviews, average, and so on).

**note:** This feature is intended for small and medium-size clients, with a limit of one million product reviews total.

[Business Manager Tools](https://github.com/SalesforceCommerceCloud/bm-tools)

This solution provides the following tools for Business Manager:

- Total File Demander: Access a remote server from this instance to circumvent firewall issues.
- Browse Remote - HTTP(s): Access remote HTTP(s) URLs from this instance to check if a connection between the systems can be established, to circumvent firewall issues and to check the responses a request produces.

[Catalog Reducer](https://github.com/SalesforceCommerceCloud/catalog-reducer)

Use this node tool to reduce the size of a large catalog by using selection criteria. For example, you can reduce a catalog with 100,000 products to a catalog with 1,000 products by having a minimum number of main products, or products with certain attributes set.

[He-Com](https://github.com/SalesforceCommerceCloud/he-com)

This sample implementation shows Headless ecommerce running on, for example, Heroku.

[Job Components](https://github.com/SalesforceCommerceCloud/job-components)

This toolbox is for basic operations done in jobs. It’s a successor for the deprecated Integration Framework’s Standard Components.

## Tooling/IDEs

[Visual Studio Code - Prophet Debugger](https://marketplace.visualstudio.com/items?itemName=SqrTT.prophet)

This extension enables code upload and debugging.

[Digital API Language Definitions in Typescript Format](https://github.com/SalesforceCommerceCloud/dw-api-types)

Use these type definitions for code completion in WebStorm or VS Code.

## Deprecated Tools

[Service Framework / package.dw.svc](https://github.com/SalesforceCommerceCloud/service-framework)

The Service Framework wraps web services into script classes and provides configuration for synchronous services (SOAP, HTTP, and FTP).

[Active Recommendations](https://github.com/SalesforceCommerceCloud/active_recommendations)

Use Active Recommendations to implement a simple upselling feature. This solution uses live order analysis and customer active data to create a product recommendation section to show shoppers during checkout as an upsell incentive.

[Content Copy Tool](https://github.com/SalesforceCommerceCloud/content-copy-tool)

Use this custom Business Manager module to transfer files between different server locations and the local file system, similar to an FTP client. Upload files, manipulate folders, and copy Content Assets or Content Slots, making your merchandising work so much easier.
[Data Resource Usage](https://github.com/SalesforceCommerceCloud/dataresourceusage)

Data Resource Usage gives access to the environment via WebDAV and calculates the aggregated size of directories.

[Dynamic Imaging Service (DIS) Wrapper](https://github.com/SalesforceCommerceCloud/dis-product-image-wrapper)

The Dynamic Imaging Service (DIS) Wrapper is helpful when you need multiple product image sizes but don’t have the backend system or processes to scale and replicate all the data to B2C Commerce sandboxes. Upload one image size, and any additional sizes that you need for your website are derived from the uploaded image.

[Agentforce Marketing Connector](https://github.com/SalesforceCommerceCloud/marketing-cloud-connector)

The Agentforce Marketing Connector includes reusable code (written in B2C Commerce JavaScript) and implementation best practices to accelerate integration between B2C Commerce and Agentforce Marketing. Supported use cases include sending transactional emails and behavioral emails, such as for abandoned cart, abandoned browse, and abandoned search.

[Agentforce Service Connector](https://github.com/SalesforceCommerceCloud/service-cloud-connector)

The Salesforce B2C Commerce to Agentforce Service Connector is a Salesforce Labs project that facilitates the integration between Salesforce B2C Commerce and Agentforce Service. This connector provides a framework for integrating these two products, leveraging public REST APIs to share and synchronize data.

<!-- document id=1a8c11249615cd6d7d48756dcabd34f41a088c29836b24873772ebc19b1c9bca url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/commerce-delivery-service.md -->

Commerce Delivery Service

# Commerce Delivery Service

## API Overview

The Commerce Delivery Service API provides estimation endpoints plus provisioning, routing, and health endpoints. It also predicts the estimated delivery date for one or more items on the storefront (from a product detail page (PDP) or checkout), reflecting the fulfillment location if an order is placed.

This specification includes both v1 and v2 API endpoints. Use version-prefixed paths (/v1/\* or /v2/\*) to access the respective API versions.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

The API client must also have the `sfcc.commercedeliveryservice.shopper` OAuth scope. You must include the relevant scope in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Use Cases

#### Estimate Delivery Date

Use the delivery-date endpoint to provide an estimated delivery date or delivery date range when

*   A shopper is on a PDP and wants to know the estimated delivery date for a product before adding it to their cart, or
*   A shopper is checking out and wants to know the estimated delivery date for the products being purchased.

#### Estimate Delivery Date by Location

Use the delivery-date-by-locations endpoint to provide an estimated delivery date or delivery date range based on a specific location group level when

*   A shopper is on a PDP and wants to know the estimated delivery date for a product based on a specific location before adding it to their cart, or
*   A shopper is checking out and wants to know the estimated delivery date for the products being purchased based on a specific location.

#### Estimate Buy Online, Pick Up In Store (BOPIS) Time

Use the BOPIS endpoint to provide an estimated earliest pickup time for BOPIS orders when

*   A shopper is on a Product Detail Page (PDP) and wants to know when a product will be ready for pickup at specific store locations before adding it to their cart.
*   A shopper wants to find nearby stores within a specified radius where a product is available for pickup, sorted by distance, along with the earliest pickup time at each location. This use case supports "find stores near me" scenarios where you provide an address, radius distance, unit (miles/km), and an optional maximum number of locations to return, sorted by distance with pickup times.
*   A shopper is checking out with a BOPIS delivery method and wants to know the earliest pickup time and available inventory for the products being purchased at nearby store locations.

**Version:** v1

## Servers

*   `https://api.salesforce.com/commerce/delivery`

Default security: bearerAuth.

## Security

*   `bearerAuth` (http) Bearer token (e.g. OAuth access token)
    *   HTTP scheme: bearer (JWT)

## Operations

### PUT Provisions a core Org as a commerce delivery service (CDS) tenant in the service

`PUT /v1/organization/{orgId}`

Operation ID: `organization/provision`. Tags: Provisioning.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId

#### Request body (required)

Media type: `application/json`. Schema: `ProvisionCDSTenantRequest`.

#### Responses

*   **200** An existing CDS tenant record is updated with the specified values
*   **201** A new CDS tenant record is created with the specified values
*   **500** An internal server error when processing the request

### DELETE Deprovisions a CDS tenant

`DELETE /v1/organization/{orgId}`

Operation ID: `organization/deprovision`. Tags: De-Provisioning.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId

#### Responses

*   **200** CDS tenant successfully deprovisioned
*   **404** Specified CDS tenant (OrgId) does not exist
*   **500** An internal server error when processing the request

### PUT Provisions the given B2CE Tenant for a the specified core org

`PUT /v1/organization/{orgId}/b2ce-tenant/{b2ceTenantId}`

Operation ID: `organization/b2ce-tenant/provision`. Tags: Provisioning.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId
*   `b2ceTenantId` (path, string, required) B2CE realm and instance separated by underscore (\_)

#### Request body (required)

Media type: `application/json`. Schema: `ProvisionB2CETenantRequest`.

#### Responses

*   **200** An existing B2CE tenant record is updated with the specified values
*   **201** A new B2CE tenant record is created with the specified values
*   **404** Specified CDS tenant (OrgId) does not exist
*   **500** An internal server error when processing the request

### DELETE Deprovisions a B2CE tenant

`DELETE /v1/organization/{orgId}/b2ce-tenant/{b2ceTenantId}`

Operation ID: `organization/b2ce-tenant/deprovision`. Tags: De-Provisioning.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId
*   `b2ceTenantId` (path, string, required) B2CE realm and instance separated by underscore (\_)

#### Responses

*   **200** B2CE tenant successfully deprovisioned
*   **404** Specified B2CE tenant does not exist
*   **500** An internal server error when processing the request

### PUT Creates or Updates the delivery estimation configuration for the given CDS tenant

`PUT /v1/organization/{orgId}/configuration/{externalReference}`

Operation ID: `organization/configuration`. Tags: Provisioning.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId
*   `externalReference` (path, string, required) Name of the WebStore or SalesChannel

#### Request body (required)

Media type: `application/json`. Schema: `CommerceDeliveryServiceSetupRequest`.

#### Responses

*   **200** An existing delivery estimation config record is updated with the specified values for a given CDS tenant
*   **201** A new delivery estimation config record is created with the specified values for a given CDS tenant
*   **404** Specified CDS tenant (OrgId) does not exist
*   **500** An internal server error when processing the request

### PUT Creates or updates the location graph for an organization

`PUT /v1/organization/{orgId}/locationgraph`

Operation ID: `organization/locationgraph/upsert`. Tags: Location Graph.

Upserts location graph data including locations and location groups for delivery estimation routing

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) The ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId

#### Request body (required)

Media type: `application/json`. Schema: `LocationGraphRequest`.

#### Responses

*   **200** An existing location graph is updated
    
    Media type: `application/json`. Schema: `ApiResponse`.
    
*   **201** A new location graph is created
    
    Media type: `application/json`. Schema: `ApiResponse`.
    
*   **400** Bad request - validation failed or tenant not found
    
    Media type: `application/json`. Schema: `ApiResponse`.
    
*   **500** Internal server error
    
    Media type: `application/json`. Schema: `ApiResponse`.
    

### PUT Performs delta synchronization of entities for a CDS tenant

`PUT /v1/organization/{orgId}/{entityType}`

Operation ID: `deltaSyncEntities`. Tags: Delta Sync.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `ContinueOnError` (header, boolean) Whether to continue processing on errors  
    Default: `true`.
*   `orgId` (path, string, required) A valid 18 char core OrgId
*   `entityType` (path, string, required) Type of entity to sync (e.g., Location, LocationGroup)

#### Request body (required)

Media type: `application/json`. Schema: `array of DeltaSyncItemRequest`.

Array of `DeltaSyncItemRequest`.

#### Responses

*   **200** Delta sync completed
    
    Media type: `application/json`. Schema: `DeltaSyncResponse`.
    
*   **400** Bad request - validation failed
    
    Media type: `application/json`. Schema: `DeltaSyncResponse`.
    
*   **500** Internal server error
    
    Media type: `application/json`. Schema: `DeltaSyncResponse`.
    

### PUT Creates or Updates the fulfilment routing criteria configuration for the given CDS tenant

`PUT /v1/organization/{orgId}/fulfillment-criteria-management/{externalReference}`

Operation ID: `organization/fulfillment-criteria-management-provision`. Tags: Provisioning.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId
*   `externalReference` (path, string, required) Name of the WebStore or SalesChannel

#### Request body (required)

Media type: `application/json`. Schema: `FulfillmentCriteriaRequest`.

#### Responses

*   **200** An existing fulfilment routing criteria record is updated with the specified values for a given CDS tenant
    
    Media type: `application/json`. Schema: `ApiResponse`.
    
*   **201** A new fulfilment routing criteria record is created with the specified values for a given CDS tenant
    
    Media type: `application/json`. Schema: `ApiResponse`.
    
*   **404** Specified CDS tenant (OrgId) does not exist
*   **500** An internal server error when processing the request

### DELETE Delete the fulfilment routing criteria configuration for the given CDS tenant

`DELETE /v1/organization/{orgId}/fulfillment-criteria-management/{externalReference}`

Operation ID: `organization/fulfillment-criteria-management-deprovision`. Tags: De-Provisioning.

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region
*   `orgId` (path, string, required) A valid 18 char core OrgId
*   `externalReference` (path, string, required) Name of the WebStore or SalesChannel

#### Responses

*   **200** A fulfilment routing criteria record is deleted with the specified values for a given CDS tenant
    
    Media type: `application/json`. Schema: `ApiResponse`.
    
*   **404** Specified CDS tenant (OrgId) does not exist
*   **500** An internal server error when processing the request

### POST Calculates the EstimatedShipDate and EstimatedDeliveryDate based on default store level settings

`POST /v1/estimate/delivery-date`

Operation ID: `estimate/delivery-date`. Tags: DeliveryEstimation.

Get Estimation Delivery Date API based on the "LocationGroup" level (default) settings

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region

#### Request body (required)

Media type: `application/json`. Schema: `GetDeliveryEstimationDateRequest`.

#### Responses

*   **200** Returns the EstimatedShipDate and EstimatedDeliveryDate based on the default settings
    
    Media type: `application/json`. Schema: `GetDeliveryEstimationDateResponse`.
    
*   **400** Returns the GetDeliveryEstimationDateResponse with error code and error message
    
    Media type: `application/json`. Schema: `GetDeliveryEstimationDateResponse`.
    
*   **500** An internal server error when processing the request

### POST Calculates the EstimatedShipDate and EstimatedDeliveryDate based on location level settings

`POST /v1/estimate/delivery-date-by-locations`

Operation ID: `estimate/delivery-date-by-locations`. Tags: DeliveryEstimation.

Get Estimation Delivery Date API based on the "Location" level (override) settings, if the overrides is not configured use the default configuration values

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region

#### Request body (required)

Media type: `application/json`. Schema: `GetDeliveryEstimationDateRequest`.

#### Responses

*   **200** Returns the EstimatedShipDate and EstimatedDeliveryDate based on the overrides settings if exist, otherwise based on default configuration values
    
    Media type: `application/json`. Schema: `GetDeliveryEstimationDateResponse`.
    
*   **400** Returns the GetDeliveryEstimationDateResponse with error code and error message
    
    Media type: `application/json`. Schema: `GetDeliveryEstimationDateResponse`.
    
*   **500** An internal server error when processing the request

### POST Calculates the earliest pickup time for locations that accept BOPIS orders

`POST /v1/estimate/bopis`

Operation ID: `estimate/bopis`. Tags: DeliveryEstimation.

Get Estimation Delivery Date API for Bopis orders

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region

#### Request body (required)

Media type: `application/json`. Schema: `BopisEstimationRequest`.

#### Responses

*   **200** Returns the earliest pickup time for a products with inventory data.
    
    Media type: `application/json`. Schema: `BopisEstimationResponse`.
    
*   **400** Returns the BopisEstimationResponse with errors
    
    Media type: `application/json`. Schema: `BopisEstimationResponse`.
    
*   **500** An internal server error when processing the request

### POST Returns the best routing route for the given skus

`POST /v1/route/routing-rules`

Operation ID: `route/routing-rules`. Tags: DeliveryRoutingEngine.

Executes the routing fulfilment routing criteria and return the best routing route for the given request

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region

#### Request body (required)

Media type: `application/json`. Schema: `RoutingRulesExecutionRequest`.

#### Responses

*   **200** Returns the best route for delivery/estimation.
    
    Media type: `application/json`. Schema: `RoutingRulesExecutionResponse`.
    
*   **400** Returns the RoutingRulesExecutionResponse with errors
    
    Media type: `application/json`. Schema: `RoutingRulesExecutionResponse`.
    
*   **500** An internal server error when processing the request

### GET Checks the status of the DB and authorization service.

`GET /v1/health`

Operation ID: `getHealth`. Tags: Application.

Gets the health of the application.

#### Responses

*   **200** Return the health of the db and authorization Service.
    
    Media type: `application/json`. Schema: `HealthResponse`.
    
*   **500** Returns error message when we can't determine the health of the application and status of Down.
    
    Media type: `application/json`. Schema: `HealthResponse`.
    

### POST Calculates the EstimatedShipDate and EstimatedDeliveryDate based on default store level settings

`POST /v2/estimate/delivery-date`

Operation ID: `estimate/delivery-date-v2`. Tags: DeliveryEstimation.

Get Estimation Delivery Date API based on the "LocationGroup" level (default) settings

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region

#### Request body (required)

Media type: `application/json`. Schema: `GetDeliveryEstimationDateRequest`.

#### Responses

*   **200** Returns the EstimatedShipDate and EstimatedDeliveryDate based on the default settings
    
    Media type: `application/json`. Schema: `DeliveryEstimationResponse`.
    
*   **400** Returns the DeliveryEstimationResponse with error code and error message
    
    Media type: `application/json`. Schema: `DeliveryEstimationResponse`.
    
*   **500** An internal server error when processing the request

### POST Calculates the EstimatedShipDate and EstimatedDeliveryDate based on location level settings

`POST /v2/estimate/delivery-date-by-locations`

Operation ID: `estimate/delivery-date-by-locations-v2`. Tags: DeliveryEstimation.

Get Estimation Delivery Date API based on the "Location" level (override) settings, if the overrides is not configured use the default configuration values

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region

#### Request body (required)

Media type: `application/json`. Schema: `GetDeliveryEstimationDateRequest`.

#### Responses

*   **200** Returns the EstimatedShipDate and EstimatedDeliveryDate based on the overrides settings if exist, otherwise based on default configuration values
    
    Media type: `application/json`. Schema: `DeliveryEstimationResponse`.
    
*   **400** Returns the DeliveryEstimationResponse by location with error code and error message
    
    Media type: `application/json`. Schema: `DeliveryEstimationResponse`.
    
*   **500** An internal server error when processing the request

### POST Calculates the earliest pickup time for locations that accept BOPIS orders

`POST /v2/estimate/bopis`

Operation ID: `estimate/bopis-v2`. Tags: DeliveryEstimation.

Get Estimation Delivery Date API for Bopis orders

#### Parameters

*   `Authorization` (header, string, required) Token Authorization
*   `Correlation-ID` (header, string, required) the ID used to correlate requests
*   `x-salesforce-region` (header, string, required) The service's targeted deployment region

#### Request body (required)

Media type: `application/json`. Schema: `BopisEstimationRequest`.

#### Responses

*   **200** Returns the earliest pickup time for a products with inventory data.
    
    Media type: `application/json`. Schema: `BopisEstimationResponse`.
    
*   **400** Returns the BopisEstimationResponse with errors
    
    Media type: `application/json`. Schema: `BopisEstimationResponse`.
    
*   **500** An internal server error when processing the request

## Schemas

### ProvisionCDSTenantRequest

*   `CoreC2CEnvironment` (_string_, required)
*   `CoreUrl` (_string_, required)
*   `UserId` (_string_, required)
*   `EinsteinFalconInstance` (_string_)
*   `InventoryShortCode` (_string_)
*   `TenantGroupUUID` (_string_, required)

### ProvisionB2CETenantRequest

*   `Url` (_string_, required)
*   `UserId` (_string_, required)

### CommerceDeliveryServiceSetupRequest

*   `DeliveryEstimationSetup` (_object_, required)
    *   `Name` (_string_, required)
    *   `Id` (_string_, required)
    *   `UserId` (_string_, required)
    *   `RoutingCalcType` (_string_, required)
    *   `FulfillmentTimeCalcType` (_string_, required)
    *   `TransitTimeCalcType` (_string_, required)
    *   `LocationGroupName` (_string_, required)
    *   `RoutingAIApplicationId` (_string_)
    *   `IsDefault` (_boolean_, required)
    *   `IsEnabled` (_boolean_, required)
    *   `ProcessingTime` (_integer_, required)
    *   `ProcessingTimeUnit` (_string_, required)
    *   `PickUpTime` (_string_, required)
    *   `TimeZoneSid` (_integer_, required)
    *   `BusinessHours` (_BusinessHours_, required)
    *   `ShippingCarrierMethods` (_array of ShippingCarrierMethod_, required)
*   `locations` (_array of Location_)

### LocationGraphRequest

*   `UserId` (_string_, required) The user ID performing the operation
*   `Locations` (_array of Location_, required) List of locations in the graph
*   `Groups` (_array of Group_, required) List of location groups

### ApiResponse

*   `isSuccess` (_boolean_, required)
*   `error` (_array of Error_)

### DeltaSyncItemRequest

*   `key` (_object_, required) Unique identifier for the entity being synced
*   `standardFields` (_object_) Standard fields for the entity
*   `customFields` (_array of CustomFieldRequest_) Custom fields for the entity

### DeltaSyncResponse

*   `totalCount` (_integer_) Total number of entities in the sync request
*   `successCount` (_integer_) Number of entities successfully synced
*   `failedCount` (_integer_) Number of entities that failed to sync
*   `results` (_array of DeltaSyncItemResult_) Detailed results for each entity
*   `success` (_boolean_) Overall success status of the sync operation

### FulfillmentCriteriaRequest

*   `id` (_string_, required)
*   `name` (_string_, required)
*   `usageType` (_string_, required)
*   `description` (_string_)
*   `isActive` (_boolean_, required)
*   `pubFulfmtRoutgCritGrpVer` (_string_)
*   `draftFulfmtRoutgCritGrpVer` (_string_)
*   `externalReference` (_string_, required)
*   `fulfmtRoutgCriteriaGrpVer` (_FulfmtRoutgCriteriaGrpVer_, required)

### GetDeliveryEstimationDateRequest

*   `deliveryEstimationSetupName` (_string_, required)
*   `shippingCarrier` (_object_, required)
    *   `name` (_string_)
    *   `methods` (_array of object_, required)
        *   `name` (_string_, required)
*   `locations` (_array of string_)
*   `products` (_array of object_, required)
    *   `stockKeepingUnit` (_string_, required)
    *   `quantity` (_integer_, required)  
        Minimum: 1.
*   `deliveryAddress` (_object_, required)
    *   `country` (_string_, required)
    *   `state` (_string_, required)
    *   `city` (_string_, required)
    *   `postalCode` (_string_, required)
    *   `latitude` (_number_)
    *   `longitude` (_number_)

### GetDeliveryEstimationDateResponse

*   `estimatedDeliveryReference` (_string_, required)
*   `deliveryEstimates` (_array of object_, required)
    *   `shippingCarrierMethod` (_string_, required)
    *   `ProductDeliveryEstimations` (_array of ProductDeliveryEstimations_)
    *   `error` (_object_)
        *   `code` (_string_, required)
            
            dictionary:
            
            *   B2CE\_TENANT\_NOT\_FOUND The B2CE Tenant is not configured for delivery estimation
            *   SHIPPING\_CARRIER\_METHOD\_NOT\_FOUND The ShippingCarrierMethod is not configured for DeliveryEstimation
            *   DELIVERY\_ESTIMATION\_TENANT\_NOT\_FOUND The Commerce Delivery Service Tenant is not configured for DeliveryEstimation
            *   CHANNEL\_NOT\_SUPPORTED The channel is not configured for DeliveryEstimation
            *   INTERNAL\_SERVER\_ERROR Unexpected error occurred when processing the request
            
              
            Allowed values: `B2CE_TENANT_NOT_FOUND`, `SHIPPING_CARRIER_METHOD_NOT_FOUND`, `DELIVERY_ESTIMATION_TENANT_NOT_FOUND`, `CHANNEL_NOT_SUPPORTED`, `INTERNAL_SERVER_ERROR`.
        *   `message` (_string_, required)

### BopisEstimationRequest

*   `deliveryEstimationSetupName` (_string_, required)
*   `products` (_array of Product_, required)
*   `locations` (_array of string_)
*   `address` (_CustomerAddress_)
*   `radius` (_number (double)_)
*   `unit` (_string_)
*   `maxReturnedLocations` (_integer (int32)_)

### BopisEstimationResponse

*   `error` (_array of object_)
    *   `code` (_string_, required)
    *   `message` (_string_, required)
*   `results` (_array of object_)
    *   `stockKeepingUnit` (_string_, required)
    *   `location` (_string_, required)
    *   `inventory` (_object_, required)
        *   `onHand` (_integer_, required)
        *   `availableToOrder` (_integer_, required)
        *   `availableToFulfill` (_integer_, required)
    *   `distance` (_number_, required)
    *   `unit` (_string_, required) Unit of distance measurement
    *   `inStore` (_object_, required) In-store pickup information
        *   `earliestPickupTime` (_string_, required)

### RoutingRulesExecutionRequest

*   `tenantId` (_string_, required)
*   `fullfilmentCriteriaGroupName` (_string_, required)
*   `products` (_array of Product_, required)
*   `locationGroupName` (_string_, required)
*   `deliveryAddress` (_DeliveryAddress_, required)
*   `excludeLocations` (_array of string_)

### RoutingRulesExecutionResponse

*   `routes` (_array of Route_)
*   `bestLocationsPerSKU` (_object_)
    
    Additional properties: `array of LocationInfo`.
    
*   `errors` (_array of Error_)
*   `success` (_boolean_)

### HealthResponse

*   `status` (_string_, required)
*   `details` (_object_)
    *   `auth` (_string_)
    *   `db` (_string_)
    *   `Error` (_string_)

### DeliveryEstimationResponse

*   `estimatedDeliveryReference` (_string_, required)
*   `deliveryEstimates` (_array of object_, required)
    *   `deliveryGroupId` (_integer_, required)
    *   `deliveryEstimateGroup` (_array of DeliveryEstimateGroup_, required)

### BusinessHours

*   `Id` (_string_)
*   `MondayStartTime` (_string_)
*   `MondayEndTime` (_string_)
*   `TuesdayStartTime` (_string_)
*   `TuesdayEndTime` (_string_)
*   `WednesdayStartTime` (_string_)
*   `WednesdayEndTime` (_string_)
*   `ThursdayStartTime` (_string_)
*   `ThursdayEndTime` (_string_)
*   `FridayStartTime` (_string_)
*   `FridayEndTime` (_string_)
*   `SaturdayStartTime` (_string_)
*   `SaturdayEndTime` (_string_)
*   `SundayStartTime` (_string_)
*   `SundayEndTime` (_string_)

### ShippingCarrierMethod

*   `Name` (_string_, required)
*   `Id` (_string_, required)
*   `CarrierName` (_string_, required)
*   `MinTransitTime` (_integer_)
*   `MaxTransitTime` (_integer_)
*   `TransitTimeUnit` (_string_)
*   `ShippingAreaType` (_string_, required)

### Location

*   `name` (_string_, required)
*   `id` (_string_, required)
*   `processingTime` (_integer_)
*   `processingTimeUnit` (_string_)
*   `pickUpTime` (_string_)
*   `timeZoneSid` (_integer_)
*   `isEnabled` (_boolean_, required)
*   `address` (_Address_)
*   `businessHours` (_BusinessHours_)
*   `shippingCarrierMethods` (_array of ShippingCarrierMethod_)
*   `HasProductsInMarkdown` (_boolean_) Whether location has markdown products
*   `IsEligibleForPickup` (_boolean_) Whether location supports pickup
*   `EarliestPickupTimeOffset` (_integer_) Earliest pickup time offset in minutes
*   `LatestPickupTimeOffset` (_integer_) Latest pickup time offset in minutes
*   `PickupProcessingTime` (_integer_) Processing time for pickup orders
*   `PickupProcessingTimeUnit` (_string_) Unit of time for pickup processing  
    Allowed values: `Minutes`, `Hours`, `Days`, `Weeks`.
*   `ShouldTrackFoCapacity` (_boolean_) Whether to track fulfillment order capacity
*   `AssignedFoCount` (_integer_) Number of assigned fulfillment orders
*   `FoCapacity` (_integer_) Fulfillment order capacity
*   `Priority` (_string_) Location priority (DynamicEnum)
*   `CustomFields` (_array of CustomField_)

### Group

*   `Id` (_string_, required) Unique identifier for the location group
*   `Name` (_string_, required) Name of the location group
*   `Locations` (_array of string_, required) List of location IDs belonging to this group

### Error

*   `code` (_string_, required)  
    Allowed values: `B2CE_TENANT_NOT_FOUND`, `INVALID_C2C_ISSUING_CLOUD`, `INTERNAL_SERVER_ERROR`, `ROUTING_ROUTES_EVALUATION_LIMIT_EXCEEDED`, `INVALID_REQUEST`, `RULE_GROUP_NOT_FOUND`, `INSUFFICIENT_INVENTORY`, `INVENTORY_SERVICE_ERROR`, `INVENTORY_LOCATION_NOT_FOUND`, `INVENTORY_CALL_TIMEOUT`, `LOCATION_GROUP_NOT_FOUND`.
*   `message` (_string_, required)

### CustomFieldRequest

*   `FieldName` (_string_, required) Name of the custom field
*   `FieldType` (_string_, required) Data type of the custom field
*   `FieldValue` (_any_) Value of the custom field (any type)

### DeltaSyncItemResult

*   `key` (_object_) The key of the synced entity
*   `status` (_string_) Status of the sync operation for this entity  
    Allowed values: `SUCCESS`, `FAILED`, `SKIPPED`.
*   `errorCode` (_string_) Error code if the sync failed
*   `errorMessage` (_string_) Error message if the sync failed

### FulfmtRoutgCriteriaGrpVer

*   `id` (_string_, required)
*   `name` (_string_, required)
*   `description` (_string_)
*   `fulfmtRoutgCriteriaGrp` (_string_, required)
*   `versionNumber` (_string_, required)
*   `refFulfmtRoutgCritGrpVer` (_string_)
*   `state` (_string_, required)
*   `maxSplitsAllowed` (_integer_)
*   `byPassSplits` (_boolean_)
*   `fulfmtRoutgCriteria` (_array of FulfmtRoutgCriteria_)

### ProductDeliveryEstimations

*   `stockKeepingUnit` (_string_)
*   `quantity` (_integer_)  
    Minimum: 1.
*   `routingCalculationType` (_string_)
*   `estimatedShipDate` (_EstimatedShipDate_)
*   `estimatedDeliveryDate` (_EstimatedDeliveryDate_)

### Product

*   `stockKeepingUnit` (_string_, required)
*   `quantity` (_integer_, required)  
    Minimum: 1.

### CustomerAddress

*   `countryCode` (_string_) ISO country code
*   `postalCode` (_string_) Postal or ZIP code
*   `latitude` (_number (double)_) Latitude coordinate  
    Minimum: -90. Maximum: 90.
*   `longitude` (_number (double)_) Longitude coordinate  
    Minimum: -180. Maximum: 180.

### DeliveryAddress

*   `country` (_string_, required)
*   `state` (_string_)
*   `city` (_string_)
*   `postalCode` (_string_, required)
*   `latitude` (_number (double)_)
*   `longitude` (_number (double)_)

### Route

*   `locations` (_array of LocationRoute_)
*   `totalScore` (_number (double)_)

### LocationInfo

*   `locationId` (_string_)
*   `quantityAvailableToOrder` (_integer_)
*   `unitScore` (_number (double)_)

### DeliveryEstimateGroup

*   `location` (_string_, required)
*   `productDeliveryEstimations` (_array of ProductDeliveryEstimationsV2_, required)
*   `shippingMethods` (_array of object_, required)
    *   `shippingCarrierMethod` (_string_, required)
    *   `routingCalculationType` (_string_, required)
    *   `estimatedShipDate` (_DeliveryEstimate_, required)
    *   `estimatedDeliveryDate` (_DeliveryEstimate_)
*   `error` (_object_)
    *   `code` (_string_, required)
        
        dictionary:
        
        *   B2CE\_TENANT\_NOT\_FOUND The B2CE Tenant is not configured for delivery estimation
        *   SHIPPING\_CARRIER\_METHOD\_NOT\_FOUND The ShippingCarrierMethod is not configured for DeliveryEstimation
        *   DELIVERY\_ESTIMATION\_TENANT\_NOT\_FOUND The Commerce Delivery Service Tenant is not configured for DeliveryEstimation
        *   CHANNEL\_NOT\_SUPPORTED The channel is not configured for DeliveryEstimation
        *   INTERNAL\_SERVER\_ERROR Unexpected error occurred when processing the request
        
          
        Allowed values: `B2CE_TENANT_NOT_FOUND`, `SHIPPING_CARRIER_METHOD_NOT_FOUND`, `DELIVERY_ESTIMATION_TENANT_NOT_FOUND`, `CHANNEL_NOT_SUPPORTED`, `INTERNAL_SERVER_ERROR`.
    *   `message` (_string_, required)

### Address

*   `street1` (_string_)
*   `street2` (_string_)
*   `state` (_string_)
*   `city` (_string_)
*   `postalCode` (_string_, required)
*   `country` (_string_)
*   `latitude` (_number_)
*   `longitude` (_number_)

### CustomField

*   `FieldName` (_string_, required) Name of the custom field
*   `FieldType` (_string_, required) Data type of the custom field
*   `FieldValue` (_any_) Value of the custom field (any type)

### FulfmtRoutgCriteria

*   `id` (_string_, required)
*   `name` (_string_, required)
*   `type` (_string_, required)
*   `usageType` (_string_, required)
*   `templateName` (_string_)
*   `isActive` (_boolean_, required)
*   `description` (_string_)
*   `refFulfmtRoutgCriteria` (_string_)
*   `fulfmtRoutgCriteriaGrpVer` (_string_, required)
*   `conditionExpression` (_string_)
*   `weight` (_number (double)_)
*   `actionExpression` (_string_)
*   `startDate` (_string (date-time)_)
*   `endDate` (_string (date-time)_)
*   `fulfmtRoutgCriteriaActnVar` (_array of FulfmtRoutgCriteriaActnVar_, required)
*   `fulfmtRoutgCriteriaCond` (_array of FulfmtRoutgCriteriaCond_, required)

### EstimatedShipDate

*   `type` (_string_, required)
*   `min` (_string (date-time)_, required)
*   `max` (_string (date-time)_, required)

### EstimatedDeliveryDate

*   `type` (_string_, required)
*   `min` (_string (date-time)_, required)
*   `max` (_string (date-time)_, required)

### LocationRoute

*   `location` (_string_)
*   `products` (_array of ProductRoute_)

### ProductDeliveryEstimationsV2

*   `stockKeepingUnit` (_string_)
*   `quantity` (_integer_)  
    Minimum: 1.

### DeliveryEstimate

*   `type` (_string_, required)
*   `min` (_string (date-time)_, required)
*   `max` (_string (date-time)_, required)

### FulfmtRoutgCriteriaActnVar

*   `id` (_string_, required)
*   `fulfmtRoutgCriteria` (_string_, required)
*   `variableIdentifier` (_string_, required)
*   `entity` (_string_, required)
*   `field` (_string_)

### FulfmtRoutgCriteriaCond

*   `id` (_string_, required)
*   `fulfmtRoutgCriteria` (_string_, required)
*   `identifier` (_integer_, required)
*   `operator` (_string_, required)
*   `leftEntity` (_string_, required)
*   `leftField` (_string_, required)
*   `rightEntity` (_string_)
*   `rightField` (_string_)
*   `rightValue` (_string_)

### ProductRoute

*   `product` (_string_)
*   `quantity` (_number_)
*   `unitScore` (_number (double)_)

### GetDeliveryEstimationDateLocationResponse

*   `estimatedDeliveryReference` (_string_, required)
*   `deliveryEstimates` (_array of object_, required)
    *   `shippingCarrierMethod` (_string_, required)
    *   `location` (_string_)
    *   `ProductDeliveryEstimations` (_array of ProductDeliveryEstimations_)
    *   `error` (_object_)
        *   `code` (_string_, required)
            
            dictionary:
            
            *   B2CE\_TENANT\_NOT\_FOUND The B2CE Tenant is not configured for delivery estimation
            *   SHIPPING\_CARRIER\_METHOD\_NOT\_FOUND The ShippingCarrierMethod is not configured for DeliveryEstimation
            *   DELIVERY\_ESTIMATION\_TENANT\_NOT\_FOUND The Commerce Delivery Service Tenant is not configured for DeliveryEstimation
            *   CHANNEL\_NOT\_SUPPORTED The channel is not configured for DeliveryEstimation
            *   INTERNAL\_SERVER\_ERROR Unexpected error occurred when processing the request
            *   LOCATION\_NOT\_FOUND The location is not configured for DeliveryEstimation
            
              
            Allowed values: `B2CE_TENANT_NOT_FOUND`, `SHIPPING_CARRIER_METHOD_NOT_FOUND`, `DELIVERY_ESTIMATION_TENANT_NOT_FOUND`, `CHANNEL_NOT_SUPPORTED`, `INTERNAL_SERVER_ERROR`, `LOCATION_NOT_FOUND`.
        *   `message` (_string_, required)

### AttributeSet

*   `groupEligibilityExclusion` (_array of string_) List of groups from which this attribute set is excluded

### InventoryInfo

*   `onHand` (_integer_) On-hand inventory quantity
*   `availableToOrder` (_integer_) Available to order quantity
*   `availableToFulfill` (_integer_) Available to fulfill quantity
*   `attributeSet` (_AttributeSet_)

<!-- document id=c11c4967ba51bc1cf5af7084922cead969f3369aca5431add8908a1a37e21a21 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-activity-tracking-api.md -->

# Commerce Einstein Activity Tracking API

Commerce Einstein product recommendations require activity tracking data. For example, tracking the viewProduct activity provides insight into top-viewed products. The Activity Tracking API provides access to these activities for use in recommendations.

The [Commerce Einstein Recommendation Validator](https://chrome.google.com/webstore/detail/commerce-cloud-recommenda/dobmbolmcejainkefklnpkjbaibgjihn?hl=en-US) extension helps with preliminary validation when integrating Commerce Einstein Activity Tracking on Salesforce production instances. This extension is available only for the Google Chrome browser. You can search for and install the B2C Commerce Recommendation Validator extension from the Chrome Web Store.

## View Product Activity

Trigger the viewProduct activity when a shopper views a Product Detail page. Don’t fire if a product is displayed via a recommendation, search result, or any other means.

**note:** If you replace the Product Detail Purchase Options component with a custom component, implement the viewProduct activity to ensure that Commerce Einstein Recommendations use cases generate results based on shopper or buyer view behavior.

Parameters

- product—The product that the customer viewed. An object with an 18-character product ID.
- sku—(Optional) A unique stock keeping unit identifier for the product.

Example usage

```nolang
trackViewProduct({ id: '01t000000000000001', sku: 'sku123' });
```

## View Recommendations Activity

Trigger the viewReco activity when a recommendation is displayed to the customer. Implement this activity when building a custom Commerce Einstein recommendations component.

**note:** If you calculate a recommendation but don’t show it to the customer—for example, it doesn’t have as many results as you like—don’t fire this activity.

Parameters

- recommenderName—The name of the recommender.
- recoUUID—A string representing the unique ID for this recommendation response.
- products—The products displayed to the customer. A list of one or more 18-character product IDs.
- sku—(Optional) A unique stock keeping unit identifier for the product.

Example usage

```nolang
trackViewReco(
 'similar-products',
 '123-456',
 [{ id: '01t000000000000001', sku: 'sku123' }, { id: '01t000000000000002', sku: 'sku456' }]
);

```

## Click Recommendations Activity

Trigger the clickReco activity when a recommended product is clicked and the customer is taken to the product detail page. Implement this activity when building a custom Commerce Einstein recommendations component.

Parameters

- recommenderName—The name of the recommender.
- recoUUID—A string representing the unique ID for this recommendation response.
- product—The product that the customer clicked. An object with an 18-character product ID.
- sku—(Optional) A unique stock keeping unit identifier for the product.

Example usage

```nolang
trackClickReco('similar-products', '123-456', { id: '01t000000000000001', sku: 'sku123' });
```

## Add To Cart Activity

Trigger the addToCart activity when a shopper adds a product to the cart.

**note:** If you replace the Product Detail Purchase Options component with a custom component, implement the addToCart activity to ensure that Commerce Einstein Recommendations use cases generate results based on shopper or buyer view behavior.

Parameters

- product—The product that the customer adds to cart. An object with an 18-character product ID.
- sku—(Optional) A unique stock keeping unit identifier for the product.
- quantity—(Optional) The total number of this item in the cart.
- price—(Optional) The price of each individual unit of this product.
- originalPrice—(Optional) The original price of each individual unit of this product.

Example usage

```nolang
trackAddProductToCart({ id: '01t000000000000001', sku: 'sku123', quantity: 2, price: '9.99', originalPrice: '10.99' });
```

**See Also**

- [Commerce Einstein APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-einstein-apis.md)
- [Prepare Commerce Einstein to Use Custom Components](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-prepare-einstein-custom-comps.md)
- [Create a Custom Recommendations Component for B2C Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-b2c-cust-ein-reco-comp.md)
- [Create a Custom Recommendations Component for B2B Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-b2b-cust-ein-reco-comp.md)

<!-- document id=b63264a0f1a94e1a7ae460c8b0f1edab11afdb610a32d8b19bc22efb01cd40dd url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-einstein-apis.md -->

# Commerce Einstein APIs

Use Activity Tracking and Product Recommendation APIs to call Einstein Recommendations for your Salesforce Commerce B2C and B2B stores. These APIs provide access to underlying data behind Einstein Recommendations and enable modification of the front-end experience with custom Lightning web components or Aura components.

Einstein product recommendations require activity tracking data. For example, tracking the viewProduct activity provides insight into top-viewed products. The Activity Tracking API provides access to these activities for use in B2B and B2C Einstein Recommendations components.

Calls to the Product Recommendation API deliver Einstein recommendations. For Salesforce Commerce for B2C Einstein Recommendations components, the API is accessed using a [wire adapter](https://lwc.dev/guide/wire_adapter). The Product Recommendation API returns a set of products to populate the Einstein Recommendations component.

For Salesforce Commerce for B2B Einstein Recommendations components, use the Commerce Einstein Recommendations Connect REST API to select and deliver recommendations. Using the Connect REST API ensures appropriate product entitlement filtering before recommendations are delivered.

**See Also**

- [Prepare Commerce Einstein to Use Custom Components](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-prepare-einstein-custom-comps.md)
- [Create a Custom Recommendations Component for B2C Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-b2c-cust-ein-reco-comp.md)
- [Create a Custom Recommendations Component for B2B Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-b2b-cust-ein-reco-comp.md)
- [Commerce Einstein Recommendations API Reference](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-einstein-recs-api-ref.md)

<!-- document id=91b7ae7d98ba021ea40c6e3c84ceb45d1a0512a281b6e506f030c6dcfca28477 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-einstein-recs-api-ref.md -->

# Commerce Einstein Recommendations API Reference

Modifying Einstein Recommendations interfaces in your B2B Commerce stores requires using the Activity Tracking API and a Product Recommendation API. These APIs provide access to the underlying data behind Einstein Recommendations and enable modification of the front-end experience with custom Lightning web components.

**See Also**

- [Commerce Einstein Activity Tracking API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-activity-tracking-api.md)
- [B2B Commerce Einstein Product Recommendations API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-einstein-b2b-reco-api-ref.md)

<!-- document id=4d1a00b9893ba0b193420e73abd42e42459456d2c1a2e9549fd4d908643ff5ee url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-storefront-performance-best-practices.md -->

# Commerce LWR Storefront Performance Best Practices

Great performance is critical to the success of your LWR Commerce storefront, as fast loading sites can have [3 to 5 times higher conversion rates](https://www.portent.com/blog/analytics/research-site-speed-hurting-everyones-revenue.htm) than slower sites.

Follow these recommended best practices to optimize your storefront's overall performance.

- [Performance Measurement Best Practices](#performance-measurement-best-practices)
- [CDN Caching Best Practices](#cdn-caching-best-practices)
- [Component Best Practices](#component-best-practices)
- [Image and Resource Optimization Best Practices](#image-and-resource-optimization-best-practices)
- [Network Optimization Best Practices](#network-optimization-best-practices)
- [Configuration Best Practices](#configuration-best-practices)

Also, if you are currently using an Aura storefront, we recommend that you [migrate](https://developer.salesforce.com/docs/commerce/lwr-migration/overview) to an LWR storefront for optimal performance.

## Performance Measurement Best Practices

Effective performance measurement is key to understanding and improving your storefront’s performance. Take measurements before and after each change to see its impact, analyze the results, and iterate accordingly.

Use industry-standard performance tools and metrics. Get familiar with [Core Web Vitals](https://web.dev/articles/vitals), which captures different facets of user-perceived performance, affecting how Google [ranks your storefront pages](https://developers.google.com/search/docs/appearance/page-experience).

To collect synthetic performance data, we recommend using these tools against a representative mobile device on a 4G connection:

- [Google Lighthouse](https://developer.chrome.com/docs/lighthouse/overview) is an open-source, automated tool that evaluates the quality of web pages based on various criteria, including performance, accessibility, SEO, and progressive web app (PWA) best practices. It generates comprehensive reports highlighting improvement areas.

- [WebPageTest](https://www.webpagetest.org/) is a web performance tool providing diagnostics about how a page performs under a variety of conditions. WebPageTest is a freemium product with a generous free tier plan (300 runs per month). It's an advanced tool enabling developers to run deep-dive performance analysis.

- [Salesforce Page Optimizer](https://chromewebstore.google.com/detail/salesforce-page-optimizer/alkcnclapbnefkodhbkpifdkceldogka?pli=1) is a browser plugin that helps analyze and debug the performance of lightning applications.

After your storefront is deployed to production, continue to measure your site performance using Real User Monitoring (RUM). Consider using a third-party RUM tool for detailed measurements. Google Chrome automatically and anonymously collects performance data for all sites. If your site receives enough traffic in production, you can use [CrUX dashboard](https://developer.chrome.com/docs/crux/dashboard) to track your site's performance.

## CDN Caching Best Practices

Your CDN caching strategy greatly impacts your storefront performance.

By caching resources at the CDN level, you can significantly reduce load times for end users. CDNs store copies of static content closer to users, minimizing latency and speeding up access to data.

When you cache resources at the CDN level, data is served directly to the consumer from the CDN using HTTP/3 protocols. This approach increases server scalability by preventing requests from reaching the origin server.

All Salesforce resources are CDN cacheable, with Lightning Component caching [now on by default](https://developer.salesforce.com/docs/platform/lwc/guide/perf-cdn.html). Apex controller responses are also eligible for CDN caching via an annotation in the code. For more information, see the [section about Apex Controllers](#priority-3-apex-controllers).

Ensure resources from third-party origins have appropriate cache headers, whether they’re static (like .js files) or dynamic (like API results).

## Component Best Practices

LWR components are flexible and offer a wide range of choices. To use components in a way that optimizes performance, follow these best practices.

### Always Use Up-To-Date, Out-Of-The-Box Components

Before creating a custom component, check if a suitable out-of-the-box (OOTB) component is available and can meet your needs with CSS overrides. Built-in components available in the Experience Builder pallete are optimized for both client-side and server-side rendering and typically include the latest performance enhancements.

For existing sites, check your Experience Builder pages to ensure they don’t reference any component marked as "deprecated."

### Prefer Out-Of-The-Box APIs

Binding components to data can be done in various ways. However, to avoid unnecessary server requests and keep the data consistent on the page, prefer these APIs, listed in priority order.

#### Priority 1: Data Providers

Many pages and components use assigned data providers, which retrieve data in an optimized manner. We recommend that, where possible, your components use data from these providers using [LWR expressions](https://help.salesforce.com/s/articleView?id=commerce.comm_components_expressions.htm&type=5). Data providers are essential for accessing server-side data during server-side rendering (SSR).

#### Priority 2: Commerce Client APIs

If data providers aren't available or sufficient, use [client-side storefront APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_display_lwc_apis.htm) provided by the Commerce Runtime. These APIs are optimized with proper caching at both the CDN and browser levels.

Client-side storefront APIs are extensible and support custom fields. For example, if you add a custom field to the `Product2` object, the custom field's value is included in the payload when accessing products.

To minimize unnecessary API calls, don't invoke Connect APIs directly through `fetch()` or `XmlHttpRequest`. Instead, exercise the underlying Connect APIs via the client-side storefront APIs.

**Note:** Data providers, the preferred way to access data, are built on top of the client-side storefront APIs and benefit from their optimizations and support for custom fields.

Here is an example accessing the ApplicationContext:

```
export default MyComponent extends LightningElement {
    @wire(AppContextAdapter)
      wireAppContext({ data, error, loaded }) {
        this.appContext = data;
    }


    myMethod() {
      if(this.appContext) {
           ...
      }
    }
}
```

#### Priority 3: Apex Controllers

If data providers and Commerce Client APIs aren’t available or sufficient, create custom Experience APIs (Backend For Frontend - BFF) using Apex controllers. Optimize these APIs for the pages where they’re used and minimize the number of APEX calls. It's also very important to make the API result cacheable when appropriate.

- Tailor and optimize your custom APIs for the pages where they’re used.
- Make less than three Apex calls. Aggregate (batch) the data into a single call when they’re related.
- Make the API result cacheable for both the CDN and the browser by annotating the Apex method with `@AuraEnabled(cacheable=true,scope='global')`.
- If CDN cacheable isn’t appropriate (for example, the call executes in the user context), enable browser caching by annotating the Apex method with `@AuraEnabled(cacheable=true)`.
- Prefer using [Platform Cache](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_cache_namespace_overview.htm) over accessing the database directly. Platform Cache is faster than querying the database and scales better when you [follow Platform Cache best practices](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_platform_cache_best_practices.htm).
- Minimize the number of SOQL requests. Batch all SOQL requests if possible.

#### APIs to Avoid

Some Salesforce APIs are designed to support B2B and transactional applications:

- **UI APIs:** These are designed for transactional applications and their results aren’t cached, leading to SOQL requests on the server.
- **Access to permissions:** Salesforce provides a convenient way to check permissions with perm lookup, through `@salesforce/userPermission`. See [@saleforce/userPermission](https://developer.salesforce.com/docs/platform/lwc/guide/reference-salesforce-modules.html#salesforceuserpermission) and [@salesforce/customPermission](https://developer.salesforce.com/docs/platform/lwc/guide/reference-salesforce-modules.html#salesforcecustompermission). Avoid checking permissions on the client. If necessary, consolidate them in a single Apex call and don't block page rendering based on permissions.

#### Other API Pitfalls

- Avoid the [n+1 query problem](https://stackoverflow.com/a/97253), where requests are sequentially dependent on each other. This problem often occurs when a list component retrieves a list of records and each list item component subsequently fetches additional data for each record. Instead, strive to parallelize execution and aggregate data retrieval as high as possible in your custom component tree.

- Avoid redundant data retrieval. Use one service call to get the necessary data and avoid having multiple service calls returning the same data. This is often seen in custom Apex controllers and is a bad practice.

- By default, the checkout process is designed to handle each step in sequence. Concurrent calls or changes to checkout entities, including [WebCart](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webcart.htm), within the same checkout session are not supported.

## Image and Resource Optimization Best Practices

Effective image and resource optimization can significantly enhance the performance of your site.

### Optimize Image Delivery

A common mistake is downloading and rendering oversized images, such as a 2-MB image displayed as a vignette. Make the actual size of the image, in bytes, correspond to the surface area it occupies on the screen.

The Commerce platform provides the capability to dynamically resize images based on how they’re displayed on the screen and to return them in an optimized file format (like WebP and AVIF). To take advantage of this capability, make sure that:

- The image is displayed using an out-of-the-box (OOTB) component (preferred) or, for custom components, the image is displayed using `experience/picture` URLs. These components use the browser's responsive image capability to query images via an image optimization service.
- If you can't use these components, you can programmatically compose the proper URL with resizing capabilities using utilities built for `experience/picture` (for example, `createImageDataMap`).

We recommend uploading your images to Salesforce CMS to optimize their delivery. If you must host your own images, ensure proper CDN and browser caching is achieved with `cache-control` headers.

### Minimize the Number of Resources Required for a Page

Every resource -- image, Javascript, CSS, web font, AP Apex call -- takes time to download and hurts the overall page performance. For optimal site performance:

- Remove references to unused resources.
- Minimize how many resources are loaded and reduce the size of each resource.

## Network Optimization Best Practices

Optimizing network performance is crucial for ensuring fast load times and a smooth user experience. Follow these best practices to minimize latency and improve the efficiency of your network requests.

### Limit the Number of Origins

Reducing the number of origins from which assets are loaded can significantly improve your site's performance. Follow these guidelines to streamline asset hosting and reduce latency.

- Host all assets with Salesforce (preferred).
- If that's not possible, host them on a single origin that supports CDN and browser caching with proper `cache-control` headers.
- If the assets hosted on a third-party origin are critical for the page load, adding a `<link rel=“preconnect”>` ([mdn](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect)) to the `<head>` markup speeds up the initial HTTP connection time.

### Minimize the Number of Third-Party Scripts and IFrames

Including third-party scripts and IFrames can introduce performance bottlenecks and security risks. It's crucial to limit their use and optimize their loading to ensure your site remains fast and secure.

- Third-party scripts and IFrames can introduce performance bottlenecks and security risks. Only include third-party content that’s essential for the functionality of your site.
- Defer loading of non-essential third-party scripts until after the main content has loaded. This can be achieved using the `async` attribute on script tags.
- Regularly audit your third-party scripts and IFrames to ensure they’re still necessary and aren’t introducing unnecessary delays or vulnerabilities.
- Consider using alternatives to IFrames, such as embedding content directly into the page, to avoid the additional overhead and potential security issues they can cause.

By adhering to these best practices, you can optimize the network performance of your site, ensuring faster load times and a better user experience.

## Configuration Best Practices

Performance can be impacted by sub-optimal configurations across data and settings. We recommend reviewing you data and removing duplicate or inactive data, such as inactive or unused promotions.

We also recommend that you review configuration tradeoffs and enable settings that improve performance. For more information, see these topics.

- [Faster Add to Cart](https://help.salesforce.com/s/articleView?id=commerce.comm_faster_add_to_cart.htm&type=5)
- [Reduce Entitlement Checks](https://help.salesforce.com/s/articleView?language=en_US&id=commerce.comm_search_skip_entitlement_check.htm&type=5)
- [Displayable Fields](https://help.salesforce.com/s/articleView?id=commerce.comm_displayable_fields_top.htm&type=5)
- [Secure Browser Caching](https://developer.salesforce.com/docs/platform/lwc/guide/perf-secure-browser-caching.html)

<!-- document id=a6464fda57b7114b0396550b283b140bf835f3e2eb4c9f2f2a66be4a0b766703 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payment-component-options.md -->

# Commerce Payment Component Options

Options include standard and custom components for card payment or purchase order processing. For client-side implementations, you can also build a custom payment component, or adapt an existing one.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce and B2B2C Commerce                           |

## Commerce Payment Components

Choose the Payment or Dual Payment component for server-side B2B store implementations. The dual component processes both card payments and purchase orders.

After you set up your B2B server-side payment gateway and payment service provider, use Experience Builder to select your payment component. If you have a third-party payment provider, you use the Payment or Dual Payment component.

- The Payment component includes a credit card option.
- The Dual Payment component includes both a credit card option and a purchase order option and is for B2B implementations only.

To use either of these payment components see [Customize Payments in Checkout](https://help.salesforce.com/s/articleView?id=commerce.comm_checkout_customize_payments.htm).

## Salesforce Payments Component

The Salesforce Payments component accepts a variety of payment methods including digital wallets. Customizable in Experience Builder, the Salesforce Payments Component also supports B2B purchase order business models.

If you have Salesforce Payments:

- Use the Salesforce Payments component. Adminstrators confgure the component payment keys and optionally enable saved payment methods. If you have a B2B store, you can also choose to show a purchase order option.

- If you have Salesforce Payments and you want to provide digital wallet payment options, add and configure the Express Checkout component. Express Checkout supports Apple Pay, Google Pay, PayPal, and Venmo.

To implement the Salesforce Payments component, see [Customize Payouts in Checkout](https://help.salesforce.com/s/articleView?id=commerce.comm_checkout_customize_payments.htm) and [Add Salesforce Payments Features to Store Checkout](https://help.salesforce.com/s/articleView?id=commerce.comm_custom_checkout.htm&type=5).

## Custom Payment Component

A custom, client-side payment component interacts directly with a payment provider. Implementation requires creating a custom LWC checkout UI component that is provisioned to interact directly with the payment gateway.

For more on the architecture, flow, and advantages of a custom client-side component, see [Set Up Client-Side Payment Processing](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-payment-clientside-container.md).

## Purchase Order Component

The Purchase Order Component supports B2B stores that don’t require a payment gateway.

While not technically a payment, a purchase order in a B2B (LWR) store can “stand in” as a form of payment. Buyers enter a purchase order number and place an order. (If there is neither payment authorization nor purchase order for the cart, the order cannot be placed.) The purchase order number is used downstream system for invoicing and payment processing. Purchase orders do not trigger payment flows out of the box within the Salesforce system.

If you want your B2B store to accept purchase orders only, use the Purchase Order Component. To implement a Purchase Order component, see [Customize Payments in Checkout](https://help.salesforce.com/s/articleView?id=commerce.comm_checkout_customize_payments.htm).

<!-- document id=b01c4b791b289ea6bc5c02882db403bed83a354980583862a5a975d566b9f1f3 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payment-gateway.md -->

# Commerce Payment Gateway

Payment Integration in checkout is built on the foundation of the commerce payment framework in Salesforce that is used in other products in the Salesforce portfolio such as Revenue Cloud and Order Management. This framework allows you to author an Apex class that acts as an adapter between Salesforce and the payment gateway. The framework handles the creation of payment specific records in the Salesforce system, logging calls to the gateway for auditing, idempotency in a secure, PCI-compliant fashion.

<!-- document id=f07e21589a270a8d16ef166ad4c6d91d82cfffa33cffa586a66d92bf1051a7e1 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payment-gateway-options.md -->

# Commerce Payment Gateway Options

Options include AppExchange payment provider packages, Salesforce Payments, or a custom gateway integration. Salesforce Payments and some AppExchange payment providers may be interoperable across the B2B Commerce solution and Salesforce Order Management.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce and B2B2C Commerce                           |

## AppExchange Gateway Integration

Select a payment provider listed on the Salesforce AppExchange by using Commerce app in your org. AppExchange providers are vetted for security, compatibility, and ease of integration by Salesforce.

To check availability and select a payment package for your org instance, browse [AppExchange](https://help.salesforce.com/s/articleView?id=commerce.comm_set_up_payment.htm)in your Commerce app. Always  check the listings for a package that supports a B2B or B2C store.

For a full, current list of Salesforce partners for Commerce, see [AppExchange>Payment Processing](https://appexchange.salesforce.com/appxstore?filter=a0L3000000OvSOwEAN)

## Salesforce Payments Gateway Integration

Salesforce Payments is the established path for implementing payment on Salesforce Commerce and is the fastest way to get up and running with payments in your Salesforce Commerce B2B store. A native integration with Stripe, Salesforce Payments supports an extensive set of capabilities out of the box and intricate connectivity to Salesforce Order Management.

To set up a Salesforce Payments gateway, administrators use the Commerce app to perform steps that:

- Establish a data channel (an Experience Cloud site) for payment data to flow from the payment gateway to Salesforce Payments
- Create a Salesforce Payments merchant account that accepts electronic payments from a variety of payment methods including customer-saved methods and Apple Pay
- Optionally use the Payments app to associate Stripe with the merchant account to generate B2B and B2C payment intent records.

To understand and implement a Salesforce Payments gateway, see [Set Up Salesforce Payments](https://help.salesforce.com/s/articleView?id=commerce.payments_setup_intro.htm&type=5).

## Custom Gateway Integration

A custom payment gateway supports a client-side payment component that you create or adapt. For server-side implementations, the custom work requires writing the Apex adapter that uses our out-of-the-box payment components. The gateway interacts directly with the UI component, which then issues a PostAuth validation to register and process the transaction for Salesforce Order Management.

To understand and implement a custom client-side payment integration, see [Client-Side Payment Processing Flow](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-payment-clientside-setup.md).For more on server-side payment integration, see [Set Up Server-Side Payment Processing](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-payment-serverside-setup.md).

<!-- document id=2d8e25f389f25a8d0632d152022f7c1065d7d605415b36984f67438ce5eaedab url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payment-gateway-processing.md -->

# Commerce Payment Gateway Processing

The Commerce Payment Gateway connects your store and third party payment providers. The gateway validates and processes payment API requests including tokenization, authorization, capture, refund, and other checkout API requests.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce and B2B2C Commerce                           |

The Commerce Payments Gateway uses the CommercePayments Apex namespace. For more information, see the [Apex Reference Guide](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_namespace_commercepayments.htm).

The Commerce Payments Gateway parses key object fields passed by the UI Checkout components. These fields include data to tokenize and authorize the payment request. For example, the Payments Gateway requires a tokenize request to pass this information.

```
cardPaymentMethod: {
    cardHolderName: <string>,
    cardNumber: <string>,
    expiryMonth: <string>,
    expiryYear: <string>,
    cvv: <string>
}
address: {
    street: <string>,
    city: <string>,
    state: <string>,
    postalCode: <string>,
    country: <string>
}

```

Authorization, capture, refund, and other requests also pass these objects. Review the Stripe adapter samples in the [Payments Reference Package](https://github.com/forcedotcom/commerce-on-lightning/tree/main-2/examples/b2c/checkout/payment-gateway-integration) to see how objects for transmission to Stripe are handled.

Examples for the Salesforce Payment Adapter include:

- `tokenizeRequest → commercePayments.PaymentMethodTokenizationRequest`
- `authRequest → commercePayments.AuthorizationRequest`
- `captureRequest → commercePayments.CaptureRequest`
- `refundRequest → commercePayments.ReferencedRefundRequest`

<!-- document id=cb9cbc8dbdfdd08f36e6eaa4161ad4cba1ee26438537c807452b318b7f50c17b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-set-up-dev-env.md -->

# Commerce SFDX Environment Setup

Salesforce recommends the Salesforce Developer Experience (SFDX) environment for building Lightning web components (LWC), and for custom tax, shipping, and payment integration packages and extensions. SFDX provides easy access to Salesforce extensions and GitHub repositories containing LWC templates and reference packages. SFDX also integrates with Salesforce CLI, the Visual Studio Code editor with the Salesforce Extension Pack, and plug-ins to quickly deploy packages and components to scratch orgs and stores.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

## Install the SFDX CLI

The Salesforce DX (SFDX) CLI synchronizes your source code between the Salesforce orgs that you deploy to and your version control system.

Install the CLI. See [Install the Salesforce SFDX CLI](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.get_started_cli).

To confirm installation, open a command or terminal window and enter `sfdx`.

![Screenshot confirming CLI installaiton](https://developer.salesforce.com/media/d2c-commerce/confirm_sfdx_cli_install.png)

## Install the Visual Studio Code Editor

The free Visual Studio (VS) Code editor is an ideal development environment for creating, debugging, and deploying Salesforce Lightning web components and integration packages and extensions.

The free VS Code editor is open-source and optimized for cloud and web coding. The project folder combines, compiles, and displays the output of the HTML, JavaScript, and CSS files for your component.

- [Install the open source Visual Studio Code editor](https://code.visualstudio.com/download).

## Get Salesforce Extensions for VS Code Editor

The VS Code editor provides access to Salesforce extensions that support creating integration packages and custom components for B2B and B2C stores created with an LWR template. The extensions include features for working with scratch orgs, sandboxes, and DE orgs, Lightning web components (LWC), and more.

For more information, see the [Salesforce Extensions for VS Code Overview](https://developer.salesforce.com/tools/vscode/).

1.  Open the VS Code app.

2.  Navigate to **View** | **Extensions**.

3.  In the search field, enter `Salesforce`.

4.  To install the package, click **Salesforce Extension Pack** (v. 51.4.0 or later).

5.  To confirm installation in the VS Code Editor, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS) and enter `sfdx`.

Confirmation looks like this:

![Screenshot of VS Code confirming installation of extensions.](https://developer.salesforce.com/media/d2c-commerce/confirm_sfdx_extensions_install.png)

The Salesforce Extension Pack includes:

- Salesforce SFDX CLI integration for VS Code
- ESLint JavaScript integration for VS Code
- LWC for VS Code, which uses the VS Code HTML server to provide code-editing features for the LWC program model, including syntax highlighting, code completion, and file outlining

To display a list of the installed extensions, click the Extensions icon in the left navigation pane or press Ctrl+Shift+X (Windows) or Cmd+Shift+X (macOS) and scroll to view them all.

![Screenshot of VS Editor Navigator pane showing list of installed extensions.](https://developer.salesforce.com/media/d2c-commerce/display_sf_extensions.png)

For an overview, see [Salesforce Extensions for LWC](https://developer.salesforce.com/tools/vscode/en/lwc/writing)

![Screenshot of LW Components Plugin for VS Code.](https://developer.salesforce.com/media/d2c-commerce/lwc_vs_code_sf_ext.png)

<!-- document id=926b8017ffad661d047bb4433e90a053dab3f2eed9af0eb819d5e4e748399909 url=/developer/current/en-us/commerce-cloud/solutions/guides/consumer-goods-sk.md -->

# Commerce Solution for Consumer Goods

![Consumer Goods](https://developer.salesforce.com/docs/media/solutions/consumer.png)

## Consumer Good Companies Connect the Consumer

Salesforce for Consumer Goods enables brands to take control of their brand experience and build a personalized, intelligent, data-rich B2C Commerce experience. Companies can meet their shoppers online and build an ecommerce presence quickly. And with insights on customer behavior, companies can increase brand loyalty with intelligent merchandising, subscriptions, payments, customizable content, and a connected experience through delivery and fulfillment.

Also, Consumer Packaged Goods companies who sell through retailers can use B2B Commerce to reach smaller retailers such as convenience stores.

## Business Value

Building D2C isn’t merely about creating a channel to sell products. It’s about creating an experience and building personalized, one-on-one engagements. Why? Consumers want a relationship with your brand.

- 52% of customers already visit a brand’s website with the intent to purchase. [Source](https://www.salesforce.com/uk/blog/2020/07/building-the-right-customer-experience.html#:~:text=A%20D2C%20report%20found%20that,with%20the%20intent%20to%20purchase.)
- 80% of consumers say the experience a company provides is as important as the product or services it offers. [Source](https://www.salesforce.com/news/stories/state-of-the-connected-customer-report-outlines-changing-standards-for-customer-engagement/)

D2C drives growth, increases revenue, and provides access to first-party data that can transform the consumer experience that you offer. This data can inform everything from product decisions to retailer relationships, and it can even help you unlock new consumer segments.

D2C also means directing organizational change, selecting the right team to craft a consumer-centric approach, and balancing existing relationships with channel partners. In some instances, that means opening up a new B2B Commerce channel.

For more information, check out the [Going Direct to Consumer](https://www.salesforce.com/form/commerce/conf/direct-to-consumer/?leadcreated=true&redirect=true&DriverCampaignId=cta-body-promo-158&FormCampaignId=7010M000002E47OQAS) guide.

## Consumer Goods Use Cases

With consumer behavior rapidly changing, B2C Commerce makes it easy to launch your ecommerce site and get to the market in weeks, not months. With B2C Commerce:

- Launch a direct to consumer storefront
- Implement a subscriptions offering
- Integrate payments
- Extend commerce to new channels and touchpoints
- Connect order management and inventory
- Open a B2B channel

For more information, see [Salesforce Consumer Goods](https://www.salesforce.com/solutions/industries/consumer-goods/overview/).

## Platform Features and Accelerators

Building a digital shopping experience requires a best-in-class commerce toolset to connect to shoppers anytime, anywhere. The B2C Commerce Platform toolset can help create unified, intelligent digital commerce experiences.

### Top Features for Consumer Goods

- [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (Mobile First)
- Multiple and Localized Site Management
- SEO Optimization and URL Management
- Onsite Search
- Product Management (Price Books, Catalogs, Navigation)
- Marketing, Campaigns, and Promotions Engine
- Customer Profile and Account Management
- Customer Segmentation
- AB Testing
- Page Designer and Content
- Dynamic Imaging Service
- Inventory
- Analytics
- Privacy Tools
- Embedded CDN
- Integrated Payments
- Guided Selling
- Curbside Pickup
- Headless API Experience
- AI-Driven Capabilities Powered by Einstein
  - Einstein Predictive Sort
  - Einstein Product Recommendations
  - Einstein Commerce Insights
  - Einstein Search Dictionaries
  - Einstein Search Recommendations
- Salesforce Order Management
- Ecosystem
  - [Agentforce Commerce Partner Marketplace](https://www.salesforce.com/products/commerce-cloud/partner-marketplace/)
  - [AppExchange](https://appexchange.salesforce.com/)
- Agentforce Marketing and Agentforce Service Integration

## Implementation Overview

Developers have two paths:

- Build on the Salesforce Commerce Platform using developer tooling, sample apps, headless APIs, and best practices.
- Launch Commerce Quick Start Commerce Solutions that provide out-of-the-box (OOTB) solutions for Direct to Consumer, Subscriptions, Channels, Grocery, Quick Service Restaurants, along with B2B Commerce. Developers can offload implementation and managed services to partners in these offerings.

### Salesforce Commerce Platform

### B2C Developer Tools

- [Agentforce Commerce Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud)
- Open Commerce API (OCAPI)
- Salesforce Commerce API
- Software Development Kits (SDK)
- Mulesoft Connector for Data API

### B2C Commerce

- [Build Your Ecommerce Site with Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/build-ecommerce-site-with-cc-digital?trailmix_creator_id=bcommerce&trailmix_slug=get-started-with-salesforce-b-2-c-commerce)
- [Develop for Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/develop-for-commerce-cloud)
- Headless Commerce: [Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-commerce-basics), [Implementation Strategies](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-implementation-strategies), [PWA Kit & Managed Runtime](https://trailhead.salesforce.com/en/content/learn/modules/commerce-pwa-kit-and-managed-runtime)
- [Configure On-Demand Sandboxes](https://trailhead.salesforce.com/content/learn/modules/b2c-on-demand-sandbox)
- [Documentation Hub: B2C & OMS](https://help.salesforce.com/s/articleView?id=cc.b2c_data_input_output_overview.htm&type=5)

### Order Management

- [Getting Started with Salesforce Order Management](https://trailhead.salesforce.com/content/learn/modules/om-salesforce-order-management)
- [Salesforce Order Management Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/order_management_developer_guide_intro.htm)

### B2B Commerce

- [Salesforce B2B Commerce Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2b-commerce-basics)
- [Administer Salesforce B2B Commerce on Lightning Experience](https://trailhead.salesforce.com/en/content/learn/trails/administer-salesforce-b2b-commerce-on-lightning-experience)
- [Documentation Hub: B2B](https://help.salesforce.com/articleView?id=commerce.b2b_commerce.htm&type=5)

### Salesforce Professional Services

Salesforce Professional Services teams help you every step of the way. With deep industry and commerce expertise, customer success experts can help plan, scope, and build your next Consumer Goods project.

## Additional Consumer Good Resources

Launch a Commerce Quick Start Solution that provides quick to market OOTB solutions for Direct to Consumer and B2B use cases. Developers can offload implementation and managed services to partners in these offerings.
[Quick Start for Direct-to-Consumer](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-consumer-essential-goods-data-sheet.pdf)
Launch a direct-to-consumer commerce site for essential and consumer goods.
[Quick Start for Subscriptions](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/quick-start-commerce-for-subscriptions.pdf)
Give customers an easy way to stock up on products they love.
[Quick Start for Channels](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-channels.pdf)
Extend your ecommerce to new channels.
[Quick Start for Grocery and Quick Service](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-grocery-data-sheet.pdf)
Sell essential grocery and food items online.
[Quick Start for B2B Commerce](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-B2b-data-sheet.pdf)
Deploy a B2B Commerce storefront for self-service ordering.

<!-- document id=606d085c59e5ab01e3f99bf7abd45759d4310b0d4dd8aa7e1f346608a6525eba url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-orders-api.md -->

# Commerce Webstore Checkout Orders API

Use for simple, synchronous checkout scenarios with minimal customization. The Commerce Webstore Checkout Orders API is also referred to as Place Order V1.

**Endpoint:** POST [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}/orders`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order.htm)

**How it works:**

- Invoke single-step Place Order API (no request body required).
- The API performs all validations and places the order in a single call.
- On success, returns 201 Created with Order Reference Number (ORN).
- On failure, returns 422 Unprocessable Entity.

**Call after:**

- Payment APIs have completed.

**Supported cart states:**

- Checkout
- PendingClosed (returns existing ORN)

**Execution flow:**

- Validations, inventory, coupon processing, and order placement execute in a single call.
- Cart-to-order processing runs asynchronously after API call.

<!-- document id=e9dd08a391bcafb232431c40c956cf721faa15e1fcaab00e6551ea1b591426d9 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-place-order-action-api.md -->

# Commerce Webstore Checkout Place Order Action API

Use for advanced scenarios requiring better control, extensibility, and resilience through a staged workflow. The Commerce Webstore Checkout Place Order Action API is also referred to as Place Order V2 or Streamlined Place Order.

**Endpoint:** POST [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm)

**Prerequisite:** Streamlined Place Order enabled for webstore. See [Streamlined Place Order](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-streamlined-place-order.html)

**How it works:**

- The request must include an action in the body: `prepare` or `submit`.
- Two-step process:
  - Prepare – Performs validations and readiness checks.
  - Submit – Finalizes and creates order.
- On success, returns 200 OK (Submit returns ORN).
- On failure, returns 422 Unprocessable object.

**Orchestration:**

- Call Prepare before payments.
- Process payments.
- Call Submit after payments.

#### Prepare Action

Validates whether cart is ready for order placement.

**Supported cart states:**

- Checkout
- PendingClosed (returns early if already in this state).

**Extension support:**

- Custom validations via `Commerce_Domain_Checkout_PlaceOrder`. See [CheckoutPlaceOrder](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/CheckoutPlaceOrder.html).

#### Submit Action

Finalizes and creates order.

**Supported cart states:**

- Checkout
- PendingClosed (returns existing OrderReferenceNumber (ORN) if already in this state)

**Execution flow:**

- Validations, inventory, coupon processing in Prepare.
- Order placement in Submit.
- Cart-to-order processing runs asynchronously after Submit.

**Extension support:**

- Custom validations via `Commerce_Domain_Checkout_PlaceOrder`. See [CheckoutPlaceOrder](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/CheckoutPlaceOrder.html).

<!-- document id=53d1775ea9e4bbbd77e270708d452e3cd6ccc789fc58495686d049baf5c55c43 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/community.md -->

# Community

At Salesforce B2C Commerce, we want to encourage our developer community to connect, share, and collaborate—whether that’s through official or unofficial channels!

## Official Channels

Through official channels, Salesforce employees can speak directly about Salesforce products, procedures, and policy. When Salesforce employees participate in the “unofficial” community, nothing they say or do can be endorsed by Salesforce. For example, product announcements or positioning statements can _only_ be made through official channels.

Our official channels include:

- [Trailblazer Community](https://trailhead.salesforce.com/trailblazer-community/groups/0F94S000000H1fESAS)
- [Idea Exchange for Commerce](https://trailblazer.salesforce.com/ideaSearch?sort=2&filter=Commerce)
- [Partner Community](https://partners.salesforce.com/_ui/core/chatter/groups/GroupProfilePage?g=0F93A0000009SFY)

## Unofficial Slack

Alongside official channels, there’s also the [Salesforce B2C Commerce “Unofficial” Slack](https://sfcc-unofficial.slack.com/home) community. It was created by B2C Commerce users a few years ago and has steadily grown over the years.

The “Unofficial” Slack is a place for developers to work together to solve the problems they encounter on a daily basis. It also gives members a place to discuss Salesforce B2C Commerce in a free and open environment. It’s run independently from Salesforce, with its own [administrators](https://github.com/sfcc-unofficial/docs/blob/master/admins.md) and [Terms of Use](https://github.com/sfcc-unofficial/docs/blob/master/terms-of-use.md).

Here are some key channels to join: [#scapi](https://sfcc-unofficial.slack.com/archives/C01AWMT7GSZ), [#headless](https://sfcc-unofficial.slack.com/archives/CH4U3SBKJ), and [#pwa-kit](https://sfcc-unofficial.slack.com/archives/C02KUCHDEKH).

With the [acquisition of Slack](https://www.salesforce.com/news/press-releases/2021/07/21/salesforce-slack-deal-close/), Salesforce provides sponsored access to features like expanded history. Beyond this sponsorship arrangement, Salesforce has no other involvement in how the community is run. The community maintains full independence from Salesforce.

Join the community today! Anyone can join in one of two ways:

1.  Someone who is already in the community can extend an invitation to you.
2.  Complete this [Google Form](https://docs.google.com/forms/d/e/1FAIpQLSdy875PlJuib35naCkr3-Frn2qtaSuuRgYezRSb2uBYkhXt7g/viewform) to request access.

You don’t have to be affiliated with a B2C Commerce customer or partner to join.

See more details on [joining](https://github.com/sfcc-unofficial/docs/blob/master/README.md) and [getting started](https://github.com/sfcc-unofficial/docs/blob/master/getting-started.md) on GitHub.

**note:** For urgent issues that require timely resolution, contact [Salesforce Support](https://help.salesforce.com/s/support/).

<!-- document id=5ad71173be002a36bccdd96dfd577c700404ee5daf6961bc884ed59260f1a8d8 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-compatibility-mode-considerations.md -->

# Compatibility Mode Changes

To upgrade to the latest compatibility mode, you must understand what changed between modes, to make the corresponding changes to your code.

Your site uses one of the following compatibility modes: 10.4, 10.6, 13.6, 15.5, 16.1, 16.2,17.7, 18.2, 18.10, 19.10, 21.2, or 22.7.

The `dw.system.System.getCompatibilityMode()` method returns the compatibility mode of the custom code version that is currently active. The compatibility mode is returned as a number, for example, compatibility mode 15.5 is returned as 1505.

## 22.7

With compatibility mode 22.7, the B2C Commerce server-side JavaScript engine supports more elements from ECMAScript 6 (ES6) and later. Access new and expanded features, including top-level built-in types and methods for existing classes.

- Shorthand property names
- New JavaScript primitive type `bigint`, replaces `dw.util.BigInteger`
- Template literal support
- `String.raw`
- `globalThis`
- Exponential operator
- `Object.values` / `Object.entries` / `objectfromEntries` / `Number.EPSILON`
- dw.order.Order.getOrderExportXML() API v2 with strict argument validation and extended RSA algorithm support
  - The encryption parameter handling for encrypted and masked payment instrument data in `dw.order.Order#getOrderExportXML` API is revised.
  - Data Includes
    - Credit card number
    - Bank account number
    - Bank account driver's license number
  - Change Details
    - `dw.order.Order.getOrderExportXML(encryptionAlgorithm, encryptionKey, encryptUsingEKID)` was removed entirely. This method was deprecated because the `encryptUsingEKID` parameter was never used. To return encrypted payment instrument data with the given algorithm or key, use `dw.order.Order.getOrderExportXML(encryptionAlgorithm, encryptionKey)` instead. To return payment instrument data unmasked, use `dw.order.Order.getOrderExportXML()`.
    - dw.order.Order.getOrderExportXML(encryptionAlgorithm, encryptionKey) no longer accepts an invalid encryption argument, which includes null, blank, or otherwise empty algorithms or keys.
    - `dw.order.Order.getOrderExportXML(encryptionAlgorithm, encryptionKey)` supports the current RSA/ECB/OAEPWithSHA-256AndMGF1Padding encryption algorithm. Previously, the `encryptionAlgorithm` argument was ignored and the (now deprecated) algorithm RSA/ECB/PKCS1Padding was always used when a non-blank key was provided.
    - `dw.order.Order.getOrderExportXML(encryptionAlgorithm, encryptionKey)` no longer accepts a null key, which was used as a “magic” value for returning the payment instrument data as masked instead of encrypted. Only use `dw.order.Order.getOrderExportXML()` to return masked payment instrument data.

## 21.7

- Any use of invalid characters in a cookie name, as described in RFC6265, which references RFC2068, now causes dw.web.Cookie to throw an exception.

The `dw.catalog.ProductInventoryRecord` class has the following updates

- The already-deprecated method `getOnHand()` has been removed.
- The allocation amount now requires an allocation reset date. For that reason, the `setAllocation(allocationAmount, allocationResetDate)` has replaced the `setAllocation(allocationAmount)` method, which has been removed.
- Product Inventory Records are now read-only in a storefront context. Thus, you can no longer call the following methods within a storefront context:
  - `setAllocation(allocationAmount, allocationResetDate)`
  - `setBackorderable(boolean)`
  - `setInStockDate(Date)`
  - `setPerpetual(boolean)`
  - `setPreorderable(boolean)`
  - `setPreorderBackorderAllocation(double)`

## 21.2

- The JavaScript server-side engine supports some ECMAScript 6 and later language elements.
- B2C Commerce JavaScript is based on Rhino JavaScript. Compatibility modes earlier than 21.2 use the ECMAScript 5 (ES5) language version. With 21.2, some ECMAScript 6 (ES6) language elements, standardized as ECMAScript 2015 and later, are supported. Keep in mind that ES6 isn’t completely compatible with ES5. ES6 introduces the following new keywords that can no longer be used as identifiers.
  - In general: `class`, `export`, `extends`, `import`, `super`, `await`, `enum`
  - In strict mode only: `implements`, `interface`, `package`, `private`, `protected`, `public`, `static`
- Compatibility mode 21.2 activates numerous B2C Commerce JavaScript changes, including many small fixes and changes to existing features. Some of the significant changes and new features are as follows:
  - More features for strict mode.
  - New JavaScript top-level built-in types, including Symbol, Map, Set, and typed arrays. The new types are designated as **API Versioned, From version 21.2** in B2C Commerce Script documentation.
  - New methods for existing classes, for example `String`, `Number`, `Array`, `Math`, and `Object`. The new methods are designated as **API Versioned, From version 21.2** in B2C Commerce Script documentation.
  - Support for Symbols.
  - `for..of` loops.
  - Arrow functions.
  - Generator functions (functions that use `function *` syntax.)
  - Shorthand method declarations. (Shorthand properties aren’t supported.)
  - Destructuring of objects.
  - More consistent timeout handling.

## 19.10

19.10 includes the following changes:

- Long running scripts now abort as expected after the timeout period. Previously, some scripts didn’t time out under some conditions.
- The classes `dw.svc.ServiceRegistry`, `dw.svc.ServiceDefinition`, and the subclasses of `dw.svc.ServiceDefinition` have been removed from the script API. These classes had been previously deprecated and replaced with `dw.svc.LocalServiceRegistry`. You can’t register `ServiceDefinitions` using an `init` script in `package.json`. The `init` scripts are no longer executed.
- Objects of unsupported types can no longer be stored at the session. Previously, if you used an unsupported type, you got a deprecation warning message. With 19.10, the session object refuses objects of unsupported types with an exception. If you implemented your storefront based on SiteGenesis, sometimes you have to adjust the code. In SiteGenesis, when a shopper logs in, the requested location is held in a session variable of type URL. In `guard.js`, change the type to string, as follows:

  Change this:

  ```
  session.custom.TargetLocation = browsing.lastUrl();
  ```

  To this:

  ```
  session.custom.TargetLocation = ''+browsing.lastUrl();
  ```

## 18.10

The `dw.util.StringUtils#formatNumber(number,format,locale)` API method now respects the regional settings of the locale for grouping and decimal characters.

Before Compatibility Mode 18.10, this method ignored the defined regional settings and used the format setting from Java for the specified locale.

## 18.2

Exceptions from JavaScript functions called by script API classes were wrapped as a SystemError. This situation led to issues if the exception was an APIException, because the additional properties weren’t accessible.

A method where this situation occurred is `dw.util.Transaction.wrap()`:

```
try {
 dw.util.Transaction.wrap(function () {
   throw new Error("my error");
   });
 } catch (e)
 {
 return {message: e.message, name: e.name};
 }
```

Before Compatibility Mode 18.2, this example returned the unexpected result:

```
message: com.demandware.core.script.capi.ScriptingException: Error: test error (...) name: SystemError.
```

With 18.2 Compatibility Mode, the original exception object remains intact, which means the example returns the following message:

```
test error name: Error
```

## 17.7

APP-49849: Changed Argument Handling of ISML.RenderTemplate

The behavior of the `dw.template.ISML.renderTemplate()` method has changed slightly. The template execution is now scoped. All variables passed to the template are only placed in the dictionary temporarily. After the template finishes, the original pipeline dictionary is recovered. Previously, arguments passed into the template were placed in the global pipeline dictionary. Having the arguments in the global pipeline dictionary led to naming conflicts and changed values in the dictionary after the template returned.

**important:** Because this change is a breaking change, a new API compatibility mode was added. The new behavior is only activate if API mode is set to 17.7 or later.

## 16.2

With Compatibility Mode 16.2 it, encrypt and decrypt a message with a salt of ‘0’, using the Cipher class in the Salesforce B2C Commerce API. When using a previous compatibility mode, a system-defined salt was used if the developer passed a salt that consisted solely of bytes with value 0x00 or other characters that are represented by ASCII codes less than or equal to 0x20.

Compatibility Mode 16.1 used the following salt values:

- salt 0x7d, 0x60, 0x43, 0x5f, 0x02, 0xe9, 0xe0, 0xae (Base64 encoded fWBDXwLp4K4=) as the default salt in the cases mentioned previously for PBE-based encryption.
- salt 0x73, 0x2f, 0x2d, 0x33, 0xc8, 0x01, 0x73, 0x2b, 0x72, 0x06, 0x75, 0x6c, 0xbd, 0x44, 0xf9, 0xc1 (Base64 encoded cy8tM8gBcytyBnVsvUT5wQ==) as the default salt for AES-based encryptions.

If you must reproduce the behavior of compatibility modes before Release 16.2 on an instance that has 16.2 enabled, use these salts as the salt parameters to encrypt or decrypt.

## 16.1

APP-33920: ECMAScript 5 compliant behavior of global function _parseInt(String)_ in code compatibility version 16.1

Starting with B2C Commerce Script API (code compatibility) version 16.1, the _parseInt(String)_ function is ECMAScript 5 compliant. In older versions, the function was only compliant with ECMAScript 3. The difference is that with ECMAScript 5, octal number support was dropped. Numbers starting with leading zeros are now parsed to radix 10 instead of radix 8, as previously. If the dynamic radix determination isn't needed explicitly, the use of _parseInt(String, Number)_ is still recommended.

APP-34144: Map.Values() Returns a View to the Map in Code Compatibility Version 16.1

Starting with B2C Commerce Script API (code compatibility) version 16.1, the _Map.values()_ method now returns a view to a map the same way the _Map.keySet()_ and _Map.entrySet()_ methods did in earlier versions. Previously, the _Map.values()_ method returned an independent collection where modification didn’t change the map.

## 15.5

APP-32403: SiteGenesis Release 15.3 and 15.4 Developers Must Modify Their Code If Using the Release 15.5 B2C Commerce Script API

A recent change in the way the 15.5 B2C Commerce Script API handles global variables means that customers who have adopted SiteGenesis Releases 15.3 or 15.4 must explicitly declare the paths of global functions such as `dw.system.Logger` and `dw.web.URLUtils`.

Who Does This Affect?

This change affects only customers using SiteGenesis Releases 15.3 and 15.4, _and_ who have set the B2C Commerce Script API Compatibility Mode to 15.5. This change doesn't affect customers using B2C Commerce Script API Version 13.6 or using SiteGenesis 15.2 or earlier or SiteGenesis 15.5 or later.

How Does the Problem Appear?

If you’re using SiteGenesis Release 15.3 or 15.4 _and_ you’re using B2C Commerce Script API 15.5, you can't access the Cart page in SiteGenesis. You get an error in your log file as follows:

```
org.mozilla.javascript.EcmaError: ReferenceError:
 "Logger" isn't defined.
 (app_storefront_core/cartridge/scripts/cart/calculate.js#271)
 in line 271
```

What Should I Do If This Happens to Me?

1.  If possible, merge SiteGenesis Release 15.5 into your code, or
2.  Use the SiteGenesis 15.5 version of `calculate.js`, or
3.  In `calculate.js`, replace all calls to `Logger()` to the fully qualified version, as follows: `dw.system.Logger()`.
4.  Only if you have no opportunity to fix the code to comply with the updated JavaScript standard set the compatibility mode to 13.6.

**note:** This change is a temporary fix until the required code changes are made.

APP-23919: Global Scope of Caller Not Accessible by Called Modules with Compatibility Version 15.5

The `require()` script now works properly within pipelines (Assign Node). Previously, global variables were shared between modules, which limited isolation and reusability. Global variables defined in a module script didn’t work, while they worked properly when requiring the module in another script.

See the following example:

TopLevelScript.ds

```

importPackage( dw.system );
 var globalVariable = PIPELET_ERROR;
 function execute( args : PipelineDictionary ) :
 Number
 {
 return require("myModule");
 }
```

MyModule.ds

```
var globalVariable;
 module.exports = globalVariable || PIPELET_NEXT;
```

With compatibility version 15.5, the `PIPELET_NEXT` is returned, while previous compatibility versions returned a `PIPELET_ERROR`.

Activate the new behavior by selecting compatibility version 15.5.

Customer impact: Review your code for use of the `require()` script that relies on the leakage of variables from the caller scope into the module.

APP-30008: Cipher Methods Expect a Base64-Encoded Salt with Compatibility Version 15.5

Starting with API Version 15.5, all `dw.crypto.Cipher` methods expect the salt argument to be base64-encoded.

**note:** Passing undefined as salt is no longer possible, because it was previously used for some algorithms. With the new API version, you encounter an EncryptionException with the message base64 decoding of salt failed.

APP-30138: Module Lifetime Is Entire Request with Compatibility Version 15.5

With code compatibility version 15.5, modules are now loaded and instantiated only once per request. If within script code a `require()` call requests the module a second time, then the same instance as the first call is returned. This return of the same instance happens regardless of the location of the require call (pipeline, script files, or ISML files).

Previously, the module cache that was held within the implementation of `require()` wasn’t global per request, but belonged to the JavaScript context. For every new context, a new cache was created. Modules that were resolved in a script were therefore not visible to script sections contained in templates (for example, `isscript`) because scripts had their scope, and templates had another scope.

APP-30693: Log notification for changed methods in older API Versions

If a method behavior changes, but the method signature stays the same, and the method is still used with an old B2C Commerce Script API version active (also referred to as Compatibility Mode), B2C Commerce now writes notifications to the API log.

For example, if a fictitious class method apiClass.setMethod(String one) existed in the old B2C Commerce Script API Version 13.6 (which is the last active Compatibility Mode in 15.4) and the behavior changed with the new B2C Commerce Script API (a new Compatibility Mode) in Release 15.5, the usage of apiClass.setMethod in Release 15.5 executed on the old B2C Commerce Script API version 13.6 will log a message such as the following to the API log file:

```
API Method apiClass.setMethod(String) has been changed in a newer API Version.
Consider updating."
```

The same invocation on the newer B2C Commerce Script API (Compatibility Mode 15.5 after you activated this new API) will no longer log this type of message.

APP-31925: Strict JSON parsing enforced with code compatibility version 15.5

Starting with B2C Commerce Script API (code compatibility) version 15.5, strict parsing is enforced. Previously, versions of the JSON parsers in B2C Commerce accepted invalid JSON that contained extraneous commas before closing brackets.

APP-32088: ECMAScript compliance issue in B2C Commerce script parser fixed with compatibility version 15.5

When compatibility version 15.5 is selected, an error is thrown when code accesses undeclared properties, which is proper ECMAScript behavior. For compatibility reasons, this behavior is still allowed if you select a compatibility version earlier than 15.5.

## 13.6

APP-18307: SeekableIterator in Pipeline Dictionary

In B2C Commerce script files, call API methods that return a `dw.util.SeekableIterator` instance. A `SeekableIterator` iterates over its elements a single time. However, if you put this iterator into the Pipeline Dictionary and your API compatibility mode is earlier than 13.6, the iterator can be used multiple times. Depending on the number of elements the iterator represents, this approach can cause memory usage issues.

As of API compatibility mode 13.6, the elements in the `SeekableIterator` can only be accessed one time. If you’re using an API compatibility mode that pre-dates 13.6, there are entries in the API log indicating that the SeekableIterator is being placed into the Pipeline Dictionary. These log entries enable you to identify uses of SeekableIterator where moving to 13.6 compatibility mode can cause a change in your Pipeline behavior.

The log entries take the following form:

```
PipelineDictionary usage violation:
 WARN: dw.util.SeekableIterator put in dictionary.
 KEY: key_name, SCRIPT: script_name
```

where `key_name` is the pipeline dictionary key, and `script_name` is the name of the script that is putting the `SeekableIterator` into the dictionary.

## 10.6

APP-46080: `SeekableIterator.close()` now ensures that the iterator is closed

As of Release 17.2, `SeekableIterator.close() n`ow ensures that the iterator is closed. Previously in some situations, it was possible to read elements from a `dw.util.SeekableIterator` even after close was explicitly called.

Customer impact: for compatibility modes 10.6 and greater, the iterator must always be empty after a call to `close()`.

APP-15882: API Behavior Change When Accessing SeekableIteratot via the Pipeline Dictionary

Instances of `SeekableIterator` are returned in the API whenever a method returns mass data. Starting with API version 10.6, these iterators can only be iterated one time to avoid possible memory problems for large iterators. Putting them into the pipeline dictionary and trying to loop them multiple times is no longer possible because this approach would require buffering the iterated elements internally.

Previously, and for all customers still running API version 10.4 (compatibility mode), `SeekableIterator` instances stored in the pipeline dictionary could be iterated multiple times (for example, by several loop nodes).

Customer Impact: Check your code for instances of SeekableIterator and adjust as required.

Product Attributes Set At Site Level (No Release Note)

With Compatibility Mode 10.6, the product attributes `onlineFlag`, `searchableFlag`, `searchPlacement`, and `searchRank` are set at the site level. Previously they were set at global level.

APP-15381: Improved ProductAttributeModel Methods GetValue() and GetDisplayValue()

The `getValue()` and `getDisplayValue()` `ProductAttributeModel` methods now return a `MediaFile` instance if there’s a custom image attribute, or a MarkupText instance if there’s a custom HTML attribute. Previously, both methods returned the image path or the HTML source as a simple String.

**note:** Compatibility mode 10.6 must be activated for your code version to take advantage of this functionality.

APP-12148: Inventory levels are now adjusted on order cancellation and order Replacement

For instances configured (via API versioning) to use the B2C Commerce API version 10.6 or later, inventory levels are now adjusted to reflect items from canceled or replaced orders. Previously, when an order was canceled or replaced, no change was made to inventory levels.

Example 1: If an order has 5 units of product X, when the order is canceled, the availability of product X increases by five units.

Example 2: Assume the following:

- Order A has two units of X and three units of Y.
- Order B has three units of X, one unit of Y, and five units of Z.

If order A is replaced by order B, then the number of units available changes: -1 units of X, +2 units of Y, and -5 units of Z

When replacing order A with order B, the inventory levels now reflect that the items in order A are available.

## 10.4

This behavior is the original behavior. You have this version or greater.

**See Also**

**Parent topic:**[Code Deployment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-code-deployment.md)

<!-- document id=006e8407465944db7d93b0a1401eb2dd0accf55e64d50b5ee219686a12cbb3eb url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-components.md -->

# Component Differences with PWA Kit

PWA Kit components are typically JavaScript + PropTypes with Chakra primitives and style props. Storefront Next components are TypeScript-first and generally composed from Radix/shadcn patterns with utility-class styling and CVA-based variants. The main shift is from runtime styling and theme objects to compile-time class composition and typed component contracts.

## Component Architecture

| Aspect            | PWA Kit                | Storefront Next            |
| ----------------- | ---------------------- | -------------------------- |
| Language          | JavaScript + PropTypes | TypeScript                 |
| Type Checking     | Runtime (PropTypes)    | Compile-time (TypeScript)  |
| Component Library | Chakra UI (runtime)    | shadcn/ui (copied source)  |
| Styling Approach  | CSS-in-JS (Emotion)    | Utility classes (Tailwind) |
| Variant System    | Theme config           | Class Variance Authority   |
| Primitives        | Chakra components      | Radix UI headless          |

## Styling Comparison

| Aspect           | PWA Kit (Chakra)                        | Storefront Next (Tailwind)              |
| ---------------- | --------------------------------------- | --------------------------------------- |
| Inline styles    | `<Box padding="4" bg="blue.500">`       | `<div className="p-4 bg-blue-500">`     |
| Responsive       | `display={{base: 'none', lg: 'block'}}` | `className="hidden lg:block"`           |
| Hover states     | `_hover={{bg: 'blue.600'}}`             | `className="hover:bg-blue-600"`         |
| Theme tokens     | `color="gray.500"`                      | `className="text-gray-500"`             |
| Component styles | `useMultiStyleConfig('Button')`         | `buttonVariants({ variant, size })`     |
| Style override   | Props spread: `{...styles.container}`   | Class merge: `cn(baseClass, className)` |

## Responsive Design Patterns

PWA Kit:

```jsx
// Object syntax for breakpoints
<Box display={{base: 'block', md: 'flex', lg: 'grid'}}>

// Array syntax (base, sm, md, lg, xl)
<Grid templateColumns={['1fr', '1fr', 'repeat(2, 1fr)', 'repeat(4, 1fr)']}>

// Hook-based
const [isDesktop] = useMediaQuery('(min-width: 992px)')
```

Storefront Next:

```tsx
// Breakpoint prefixes (mobile-first)
<div className="block md:flex lg:grid">

// Responsive grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4">

// JavaScript detection
const isDesktop = typeof window !== 'undefined' &&
    window.matchMedia('(min-width: 1024px)').matches;
```

## Component Variants

PWA Kit (Theme-based):

```jsx
// In theme/components/button.js
export default {
    baseStyle: {...},
    variants: {
        solid: {...},
        outline: {...},
    },
    sizes: {
        sm: {...},
        md: {...},
    }
}

// Usage
<Button variant="solid" size="md">Click</Button>
```

Storefront Next (CVA):

```tsx
// In component file
const buttonVariants = cva("base-classes", {
  variants: {
    variant: { solid: "...", outline: "..." },
    size: { sm: "...", md: "..." },
  },
});

// Usage
<Button variant="solid" size="md">
  Click
</Button>;
```

## Key Similarities

- Composition over inheritance: Both use functional components composed from primitives
- Props passthrough: Both spread `...rest` props to underlying elements
- Responsive-first: Both prioritize mobile-first responsive design
- Variant systems: Both support component variants for consistent styling
- Accessibility: Both build on accessible component foundations (Chakra/Radix)
- HOC patterns: Both use HOCs for cross-cutting concerns (auth, suspense)

## Conversion Considerations

Here are some tips for moving from Chakra to Tailwind.

- Style props vs. Utility classes: Convert `padding="4"` to `className="p-4"`.
- Theme tokens vs. Tailwind config: Map color/spacing scales.
- useMultiStyleConfig vs. CVA: Convert component style objects to variant functions.
- Responsive objects vs. breakpoint prefixes: Replace `{{base: 'x', lg: 'y'}}` with `"x lg:y"`.

## Component Library Conversion

| Chakra Component             | Storefront Next Equivalent                           | Notes                                                               |
| ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| _Layout Primitives_          |                                                      |                                                                     |
| `Box`                        | `<div>` with Tailwind                                | Use `className="..."` for styling                                   |
| `Flex`                       | `<div className="flex">`                             | Add `flex-row`, `flex-col`, `gap-*` as needed                       |
| `HStack`                     | `<div className="flex flex-row gap-*">`              | Horizontal stack                                                    |
| `VStack`                     | `<div className="flex flex-col gap-*">`              | Vertical stack                                                      |
| `Stack`                      | `<div className="flex gap-*">`                       | Use `flex-row` or `flex-col`                                        |
| `StackDivider`               | `<Separator>` (ui/separator)                         | Or use `divide-y`/`divide-x` classes                                |
| `Center`                     | `<div className="flex items-center justify-center">` |                                                                     |
| `Container`                  | `<div className="container mx-auto">`                |                                                                     |
| `Grid`                       | `<div className="grid">`                             | Add `grid-cols-*`, `gap-*`                                          |
| `GridItem`                   | `<div>`                                              | Use `col-span-*`, `row-span-*`                                      |
| `SimpleGrid`                 | `<div className="grid grid-cols-*">`                 |                                                                     |
| `Wrap`                       | `<div className="flex flex-wrap">`                   |                                                                     |
| `WrapItem`                   | `<div>`                                              | Direct child of flex-wrap                                           |
| `Spacer`                     | `<div className="flex-1">`                           | Or use `gap-*` on parent                                            |
| `AspectRatio`                | `<AspectRatio>` (ui/aspect-ratio)                    | Radix-based                                                         |
| `Divider`                    | `<Separator>` (ui/separator)                         | Radix-based                                                         |
| **Typography**               |                                                      |                                                                     |
| `Text`                       | `<p>`, `<span>` with Tailwind                        | Use `text-*`, `font-*` classes                                      |
| `Heading`                    | `<h1>`-`<h6>` with Tailwind                          | Use `text-*`, `font-bold`                                           |
| **Buttons & Links**          |                                                      |                                                                     |
| `Button`                     | `<Button>` (ui/button)                               | CVA variants: default, destructive, outline, secondary, ghost, link |
| `ButtonGroup`                | `<div className="flex gap-2">`                       | Group buttons manually                                              |
| `IconButton`                 | `<Button size="icon">`                               | Use icon size variant                                               |
| `Link`                       | React Router `<Link>`                                | Or `<a>` with Tailwind                                              |
| `CloseButton`                | `<Button size="icon" variant="ghost">`               | With X icon                                                         |
| **Form Controls**            |                                                      |                                                                     |
| `Input`                      | `<Input>` (ui/input)                                 |                                                                     |
| `InputGroup`                 | `<div className="relative">`                         | Position elements manually                                          |
| `InputLeftElement`           | `<div className="absolute left-3">`                  | Position inside relative parent                                     |
| `InputRightElement`          | `<div className="absolute right-3">`                 | Position inside relative parent                                     |
| `Select`                     | `<SelectNative>` (ui/select-native)                  | Native select element                                               |
| `Checkbox`                   | `<Checkbox>` (ui/checkbox)                           | Radix-based                                                         |
| `Radio`                      | `<RadioGroup>` (ui/radio-group)                      | Radix-based                                                         |
| `RadioGroup`                 | `<RadioGroup>` (ui/radio-group)                      | Radix-based                                                         |
| `FormControl`                | `<div>`                                              | Use `<Label>` + input + error message                               |
| `FormLabel`                  | `<Label>` (ui/label)                                 |                                                                     |
| `FormErrorMessage`           | `<p className="text-destructive text-sm">`           |                                                                     |
| `useNumberInput`             | Custom implementation                                | No direct equivalent                                                |
| **Feedback**                 |                                                      |                                                                     |
| `Alert`                      | `<Alert>` (ui/alert)                                 |                                                                     |
| `AlertIcon`                  | Icon inside `<Alert>`                                | Use Lucide icons                                                    |
| `AlertTitle`                 | `<AlertTitle>` (ui/alert)                            |                                                                     |
| `AlertDescription`           | `<AlertDescription>` (ui/alert)                      |                                                                     |
| `Spinner`                    | `<div className="animate-spin">`                     | Or a custom Spinner component                                       |
| `Skeleton`                   | `<Skeleton>` (ui/skeleton)                           |                                                                     |
| `useToast`                   | Custom toast implementation                          | Or use sonner/react-hot-toast                                       |
| **Overlay**                  |                                                      |                                                                     |
| `Modal`                      | `<Dialog>` (ui/dialog)                               | Radix-based                                                         |
| `ModalOverlay`               | Built into `<Dialog>`                                | Automatic overlay                                                   |
| `ModalContent`               | `<DialogContent>` (ui/dialog)                        |                                                                     |
| `ModalHeader`                | `<DialogHeader>` (ui/dialog)                         |                                                                     |
| `ModalBody`                  | `<div>` inside DialogContent                         |                                                                     |
| `ModalFooter`                | `<DialogFooter>` (ui/dialog)                         |                                                                     |
| `ModalCloseButton`           | Built into `<DialogContent>`                         | Optional `showCloseButton` prop                                     |
| `AlertDialog`                | `<AlertDialog>` (ui/alert-dialog)                    | Radix-based                                                         |
| `AlertDialogOverlay`         | Built into `<AlertDialog>`                           |                                                                     |
| `AlertDialogContent`         | `<AlertDialogContent>`                               |                                                                     |
| `AlertDialogHeader`          | `<AlertDialogHeader>`                                |                                                                     |
| `AlertDialogFooter`          | `<AlertDialogFooter>`                                |                                                                     |
| `AlertDialogBody`            | `<AlertDialogDescription>`                           |                                                                     |
| `Drawer`                     | `<Drawer>` (ui/drawer)                               | Vaul-based, or use `<Sheet>`                                        |
| `DrawerOverlay`              | Built into `<Drawer>`                                |                                                                     |
| `DrawerContent`              | `<DrawerContent>`                                    |                                                                     |
| `DrawerHeader`               | `<DrawerHeader>`                                     |                                                                     |
| `DrawerBody`                 | `<div>` inside DrawerContent                         |                                                                     |
| `DrawerFooter`               | `<DrawerFooter>`                                     |                                                                     |
| `DrawerCloseButton`          | `<DrawerClose>`                                      |                                                                     |
| `Popover`                    | `<Popover>` (ui/popover)                             | Radix-based                                                         |
| `PopoverTrigger`             | `<PopoverTrigger>`                                   |                                                                     |
| `PopoverContent`             | `<PopoverContent>`                                   |                                                                     |
| `PopoverHeader`              | `<div>` with styling                                 | No separate component                                               |
| `PopoverBody`                | `<div>` inside PopoverContent                        |                                                                     |
| `PopoverFooter`              | `<div>` with styling                                 | No separate component                                               |
| `PopoverArrow`               | CSS-based                                            | Tailwind arrow styling                                              |
| `PopoverCloseButton`         | `<Button>` with X icon                               |                                                                     |
| `Tooltip`                    | `<Tooltip>` (ui/tooltip)                             | Radix-based                                                         |
| `Portal`                     | React Portal or Radix Portal                         | Built into overlay components                                       |
| **Disclosure**               |                                                      |                                                                     |
| `Accordion`                  | `<Accordion>` (ui/accordion)                         | Radix-based                                                         |
| `AccordionItem`              | `<AccordionItem>`                                    |                                                                     |
| `AccordionButton`            | `<AccordionTrigger>`                                 |                                                                     |
| `AccordionPanel`             | `<AccordionContent>`                                 |                                                                     |
| `AccordionIcon`              | Built into `<AccordionTrigger>`                      | Chevron icon included                                               |
| `useDisclosure`              | React state or Radix open state                      | `const [open, setOpen] = useState(false)`                           |
| **Navigation**               |                                                      |                                                                     |
| `Breadcrumb`                 | `<Breadcrumb>` (ui/breadcrumb)                       |                                                                     |
| `BreadcrumbItem`             | `<BreadcrumbItem>`                                   |                                                                     |
| `BreadcrumbLink`             | `<BreadcrumbLink>`                                   |                                                                     |
| `Menu` (dropdown)            | `<DropdownMenu>` (ui/dropdown-menu)                  | Radix-based                                                         |
| Navigation Menu              | `<NavigationMenu>` (ui/navigation-menu)              | Radix-based                                                         |
| **Data Display**             |                                                      |                                                                     |
| `Badge`                      | `<Badge>` (ui/badge)                                 | CVA variants                                                        |
| `Image` / `Img`              | `<img>` with Tailwind                                | Use `object-cover`, `rounded-*`                                     |
| `Avatar`                     | `<Avatar>` (ui/avatar)                               | Radix-based                                                         |
| `List`                       | `<ul>` or `<ol>`                                     |                                                                     |
| `ListItem`                   | `<li>`                                               |                                                                     |
| `Card`                       | `<Card>` (ui/card)                                   | Composition pattern                                                 |
| **Other**                    |                                                      |                                                                     |
| `Icon`                       | Lucide React icons                                   | `import { IconName } from 'lucide-react'`                           |
| `VisuallyHidden`             | `<span className="sr-only">`                         | Screen reader only                                                  |
| `Fade`                       | CSS transitions                                      | `transition-opacity` with conditional `opacity-0`                   |
| **Hooks**                    |                                                      |                                                                     |
| `useMultiStyleConfig`        | CVA + `cn()`                                         | Define variants in component                                        |
| `useStyleConfig`             | CVA + `cn()`                                         |                                                                     |
| `useTheme`                   | Tailwind CSS variables                               | Access via `var(--color-*)`                                         |
| `useMediaQuery`              | `window.matchMedia()`                                | Or use Tailwind breakpoints                                         |
| `useBreakpoint`              | Tailwind breakpoints                                 | Responsive classes preferred                                        |
| `useBreakpointValue`         | Tailwind breakpoints                                 | Use responsive class syntax                                         |
| `useRadio` / `useRadioGroup` | Radix RadioGroup                                     | Built into component                                                |
| `useStyles`                  | Not needed                                           | Styles are class-based                                              |
| `createStylesContext`        | React Context                                        | Or pass classes as props                                            |
| `StylesProvider`             | React Context                                        | Or use Tailwind directly                                            |
| `extendTheme`                | `tailwind.config.js`                                 | Extend Tailwind theme                                               |
| `ChakraProvider`             | Not needed                                           | Tailwind is build-time                                              |

## TypeScript Adoption

- Convert PropTypes to TypeScript interfaces.
- Add explicit return types to functions.
- Use `React.ComponentProps<'element'>` for HTML element props.
- Replace `PropTypes.shape({...})` with `interface` definitions.

<!-- document id=94ad49f0a5448dc0eaa167d488d400e2a78a5b6e369cd0111624ca24c394d29f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/component-override-sdk.md -->

# Component Override SDK

The Component Override SDK gives a storefront a way to replace the widget's built-in product and agent-action rendering with its own markup. It's a messaging-mode capability. Overrides use a framework-agnostic contract based on standard custom elements, so you don't need React to author them.

## How overrides work

An override is the **tag name of a custom element you've registered** (a string, such as `"product-card"`), not a function. You register the element with `customElements.define` before the widget renders, then map an override key to the tag name. When the widget needs to render that slot, it calls `document.createElement(tagName)` and assigns a single props object to the element's `props` setter.

You provide overrides as one flat map, `ComponentOverrides`, from an override key to a tag name:

```js
window.CimulateOverrides = {
  // Standard built-in slots
  ProductTile: "product-card",
  ProductCarousel: "product-carousel",
  ProgressSteps: "progress-steps",
  // Custom agent-action block, matched by output_name
  recentOrders: "cx-recent-orders",
};
```

`ProductTile`, `ProductCarousel`, `ProductDetailCard`, `ProductComparison`, and `ProgressSteps` are the named keys the widget consults for its built-in UI. Every other key, such as `recentOrders` above, is a custom key matched against a streaming `tool_results` block by its top-level `output_name` (see [Custom agent-action blocks](#custom-agent-action-blocks)). If you leave a built-in key unset, the widget renders its built-in default.

A tag name must be a valid custom element name: lowercase and containing a hyphen. Anything else (for example, `"ProductTile"` or `"div"`) is rejected with a console error, and that slot renders blank.

## Overridable slots

| Override Key | Replaces | Payload Shape |
| --- | --- | --- |
| `ProductTile` | An individual product card inside a carousel | One raw product |
| `ProductCarousel` | The whole carousel (title plus cards) | `{ title, products }` |
| `ProductDetailCard` | The in-chat product detail card | One raw product-detail block, `{ id, data }` |
| `ProductComparison` | The in-chat product comparison table | `{ products, table }` |
| `ProgressSteps` | The "Loading Step N" panel shown while an agent action streams | `{ steps }` |
| any other key | A custom agent-action block matched by `output_name` | The block's raw `data` |

**note:** `ProductDetailCard` and `ProductComparison` were added in version 1.28.0. On earlier versions, those keys are ignored and the built-in card and table always render.

Overriding `ProductDetailCard` replaces the **entire** built-in card, including its express-checkout section. When express checkout is enabled on the storefront, the built-in card renders Apple Pay and Google Pay buttons in an iframe served from a Salesforce Payments URL on your storefront. Your override receives that URL at `payload.data.expressPaymentUrl` and must build its own checkout UI from it (the built-in card loads it in an iframe). If `expressPaymentUrl` is absent, the product isn't express-checkout eligible and you should render no payment button.

**note:** Express checkout is a server-side feature: it requires the `plugin_salesforcepayments` cartridge (SFRA) and express checkout enabled on the storefront before `expressPaymentUrl` appears in the payload. Enabling it is out of scope for this guide. Overriding `ProductDetailCard` only changes how the card, and the express button within it, is rendered.

**note:** Widget chrome (the header, search bar, and follow-up suggestions) is intentionally not overridable. Those keys are accepted by the map but have no render path, so they're silently ignored. Style chrome with theme properties and custom CSS instead. See [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md).

If you override `ProductCarousel`, your `ProductTile` override is not used inside it; you own everything the carousel renders.

## The props contract

Every override, whether a product slot or a custom block, receives the same props object on its element's `props` setter:

```
{ name, payload, api }
```

- **`name`** is the override key that matched (`"ProductTile"`, `"ProductCarousel"`, `"ProductDetailCard"`, `"ProductComparison"`, `"ProgressSteps"`, or your custom block's `output_name`).
- **`payload`** is the raw agent block data, untouched. The widget does not normalize it, so its shape depends on `name`. For products, the data lives at `payload.data` (`name`, `price`, `discountPrice`, `currencyCode`, `imageUrl`, `productPageUrl`), and your custom catalog fields arrive at `payload.customProperties.c_*`. For a carousel, iterate `payload.products`, where each entry has that same product shape. For progress steps, `payload.steps` is the list of step messages received so far, in order; the last entry is the active step.
- **`api`** gives the override a way to interact with the agent and adapt to the widget's presentation.

## The override API

| Member | Type | Notes |
| --- | --- | --- |
| `sendMessage(text, options?)` | function | Post a message to the agent on the override's behalf. |
| `isLoading` | `boolean` | True while a normal send awaits the agent. |
| `isConnected` | `boolean` | True while the widget is connected to the backend. |
| `componentType` | `"chat" \| "dialog" \| "modal"` | Widget presentation mode. Use to adapt layout. |
| `mode` | `"standalone" \| "embedded"` | Whether the widget is the only UI on the page or coexists with storefront chrome. |

`sendMessage` accepts one option, `silent`. Pass `{ silent: true }` to suppress the outgoing user bubble for a machine-readable payload (such as a form's final JSON) that would be noise in the transcript:

```js
api.sendMessage(JSON.stringify(record), { silent: true });
```

Only the outgoing bubble is suppressed; the agent's reply still arrives and renders as a normal message. Your override isn't notified of that reply, and `isLoading` stays `false` for a silent send, so you can't wait on one. Render your own confirmation from data you already hold, or have the agent emit a `tool_results` block that an override renders.

**note:** The `silent` option was added in version 1.28.0.

## Precedence

When more than one override source is present, the widget resolves them in this order:

1. `overridesUrl` (a hosted script the widget loads)
2. `overrides` (an inline map passed to the injection function)
3. `window.CimulateOverrides` (a global set before the widget loads)
4. none (built-in rendering)

Override resolution never blocks the widget. The widget renders its built-in UI and opens the messaging connection immediately, then swaps in your custom elements once the map resolves. A hosted script that errors or times out resolves to an empty map, so the widget can never stall waiting on your override script.

## Author an override

Author each override as a custom element with a `props` setter that drives rendering. The messaging entry exports an optional `OverrideElement` base class that implements the props setter, getter, and lifecycle for you:

```js
import { OverrideElement } from "@cimulate/copilot-widget/messaging";

class ProductCard extends OverrideElement {
  render() {
    const { payload, api } = this.props || {};
    // Build your DOM here. Escape every agent-supplied value.
  }
}
customElements.define("product-card", ProductCard);
```

Script-tag consumers reach the same class as `CimulateMessaging.OverrideElement` on the UMD bundle. You can also implement the contract directly on `HTMLElement`: a `props` setter that stores the value and calls your render, a matching getter, and a `connectedCallback` that renders.

The widget persists your element instance across its own re-renders. `connectedCallback` fires once; on later renders, the widget assigns to your `props` setter in place, so instance state, listeners, and focus survive. (An unregistered tag name is rebuilt on every commit instead, which is why registering the element matters.)

### Escape agent-supplied values

The widget does no sanitization of payload data. You own the DOM your override produces, so escape every value that comes from the agent or catalog before you insert it into markup. Build structure as author-constant strings and pass data through an escaping helper; never drop an unescaped value into `innerHTML`. Guard against script and other unsafe URL schemes before assigning to `href` or `src`.

### Guard your registration

`customElements.define` throws if the tag is already registered, and an uncaught throw aborts the whole script before your `window.CimulateOverrides` assignment runs, so every override silently falls back. Always guard the define:

```js
function defineOnce(tag, ctor) {
  if (!customElements.get(tag)) customElements.define(tag, ctor);
}
defineOnce("product-card", ProductCard);
```

## Custom agent-action blocks

Beyond the named product slots, any other key in the map renders a custom agent-action payload: order tracking, option pickers, warranty forms, surveys, and so on. The agent emits a single `tool_results` block:

```json
{ "type": "tool_results", "index": 0, "output_name": "recentOrders", "data": {} }
```

The widget recognizes the block by its top-level `type`, routes on `output_name` alone (never a field inside `data`, so agent JSON can't hijack routing), and renders the element registered for that key. An unmatched `output_name` renders nothing.

Your override receives only the raw `data` as `payload`; the widget strips its own bookkeeping fields first. Because `data` streams in token by token, the widget withholds it until the JSON is complete, so your `render` always receives one fully formed payload rather than a half-built object.

For example, an agent action that returns a shopper's recent orders emits a block with `output_name: "recentOrders"` and an orders array in `data`. Register a custom element for that key and render the array:

```js
import { OverrideElement } from "@cimulate/copilot-widget/messaging";

class RecentOrders extends OverrideElement {
  render() {
    const { payload } = this.props || {};
    const orders = payload?.orders ?? [];
    // Build rows from `orders`. Escape every agent-supplied value.
  }
}
defineOnce("cx-recent-orders", RecentOrders);

window.CimulateOverrides = {
  ...window.CimulateOverrides,
  recentOrders: "cx-recent-orders",
};
```

The `data` the agent sent (here, `{ orders: [...] }`) arrives as `payload`, so `payload.orders` is the array to render. The key in the map (`recentOrders`) must match the block's `output_name` exactly.

## Error handling

Failure is contained per slot. If creating the element or assigning its props throws, that one slot renders blank and the widget logs a warning prefixed with `[CimulateOverrides]`. The rest of the transcript is unaffected and the widget never crashes.

## Deploy overrides

At the widget level, you supply overrides two ways:

- **Hosted URL (primary).** Host a script on HTTPS that defines your custom elements and assigns `window.CimulateOverrides`. Point `overridesUrl` at it. The widget injects the script (HTTPS only, `crossOrigin="anonymous"`, with a 5-second timeout), and reads the global once it runs.
- **Inline object.** If your app has already defined the custom elements, pass the map directly to the injection function. `overridesUrl` takes precedence when both are set.

```js
injectMessagingWidget({
  elementId: "messaging-widget",
  messagingConfig: {
    scrt2Url: "https://your-org.my.salesforce-scrt.com",
    orgId: "00Dxx0000000000",
    esDeveloperName: "Your_Messaging_Channel",
  },
  overrides: {
    ProductTile: "product-card",
    recentOrders: "cx-recent-orders",
  },
});
```

Because `window.CimulateOverrides` is a plain object, you can assign to it from multiple files. Merge rather than replace so the files coexist, and make sure each runs synchronously at the top level before the widget's first render.

On a framework storefront, you don't call `injectMessagingWidget` yourself, so you deploy overrides through the framework's configuration instead of the injection function.

### On SFRA

The `plugin_commerce_client` cartridge loads overrides from a static script inside the cartridge. Place your script at `cartridge/static/default/jscript/cimulate/overrides.js`, define your custom elements, and assign `window.CimulateOverrides` there. Then upload the cartridge and point the widget at the script:

1. Add the script to the cartridge at `cartridge/static/default/jscript/cimulate/overrides.js`.
2. Upload the cartridge with `npm run uploadCartridge` (same command and `dw.json` you used to install it; see [Install the Agentforce Commerce Client on SFRA](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-sfra.md)).
3. Set the `cc_overridesUrl` key in the `cc_config` Site Preference to the relative path:

   ```json
   {
     "cc_overridesUrl": "/jscript/cimulate/overrides.js"
   }
   ```

A relative path avoids a cross-origin request, and the cartridge derives the `script-src` CSP entry from the preference automatically. For the full cartridge install, `dw.json`, and site-path steps, see [Install the Agentforce Commerce Client on SFRA](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-sfra.md).

### On PWA Kit

The retail-react-app template accepts overrides through `COMMERCE_AGENT_SETTINGS`, either as an inline `cc_overrides` map or as a hosted `cc_overridesUrl` script. Set only one: the template forwards `cc_overrides` and drops the URL when both are present. For the inline map route:

1. Author the custom element as a class that extends `OverrideElement` from `@cimulate/copilot-widget/messaging`, escaping every agent-supplied value.
2. Register the element from the browser entry point (`app/main.jsx`), because `customElements` isn't available during server-side rendering.
3. Map the override key to the element's tag name in `cc_overrides`:

   ```json
   {
     "provider": "commerce-client",
     "cc_overrides": {
       "ProductTile": "cx-product-tile"
     }
   }
   ```

For a hosted script instead, set `cc_overridesUrl` to an HTTPS script that defines your elements and assigns `window.CimulateOverrides`. For the full route detail, the Content Security Policy setup, and complete code, see [Install the Agentforce Commerce Client on PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-pwa-kit.md).

## Related resources

- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md)
- [Choose a Customization Approach](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/customization-decision-guide.md)

<!-- document id=f5df94160294517341e198be629d4950638798b74634f9b964c6167999f5a702 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/references/about/pwa-api-doc.md -->

# Composable Storefront API Specifications

You are currently viewing the Composable Storefront documentation. To view the full Composable Storefront reference specifications in the left navigation, select the **Reference** tab (if you are currently in the **Guides** tab).

To view additional API specifications:

- <a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/" target="_blank" class="external-link-guide">B2C Commerce API (also known as Salesforce Commerce API or SCAPI)</a>
- [OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/)
- [B2C Commerce Developer Resources (Script API)](https://salesforcecommercecloud.github.io/b2c-dev-doc/)
- <a href="https://developer.salesforce.com/docs/commerce/einstein-api/references/" target="_blank" class="external-link-guide">B2C Commerce Einstein API</a>

<!-- document id=f4ee43e4794e737a363c72c38905c450d69b96e7ace6887b1fd50068e3d103ec url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/getting-started.md -->

**important:** [PWA Kit v3.0.0](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/v3.0.0) and later are available with [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md). To upgrade, see [Upgrade to v3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.md).

# Composable Storefront Overview

The Composable Storefront solution for B2C Commerce is based on two key technologies: the Progressive Web App Kit (PWA Kit) for creating your storefront and Managed Runtime for hosting it.

Like all composable, API-driven technologies, PWA Kit and Managed Runtime can be combined with other ecommerce technologies from Salesforce or other vendors. With Composable Storefront, you can architect a technology stack that meets your exact needs and can scale with your business.

For a summary of the developer workflow, see [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md).

## PWA Kit

The PWA Kit is a framework for creating storefronts in JavaScript (or TypeScript) using the React platform, which has become a fixture of modern web development.

With the PWA Kit framework you get:

- Project templates, including the Retail React App. The Retail React App is a customizable storefront that implements core ecommerce flows from home page to checkout.
- A rendering system that works on both the server side and client side—and handles [hydration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Hydration_(web_development)>) (the process of transferring rendering from server to client).
- A routing system that allows you to inject data from the Commerce API into your components.
- Utility functions and scripts for automating routine development tasks.
- Integration with the [B2C Commerce API](https://developer.salesforce.com/docs/commerce/commerce-api/guide) and [Open Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html) (OCAPI).

**important:** Security patches are provided for 24 months after the general availability of each major version of the framework (1.0, 2.0, and so on).

### What’s a Progressive Web App?

A progressive web app (PWA) is a website whose user experience includes features that we normally associate with mobile apps, including fast load times, smooth rendering, and seamless transitions.

The reason they’re called “progressive” is that these features are added one-at-a-time (or _progressively_), based on what the user’s device and browser can support.

## Managed Runtime

Managed Runtime provides the infrastructure to deploy, host, and monitor your PWA Kit storefront on a public cloud platform. With Managed Runtime, you can focus on developing your storefront instead of managing servers.

Managed Runtime follows the [Twelve-factor App methodology](https://12factor.net/). Your storefront is powered by a single codebase that is built statelessly and can be deployed on the most efficient and low-cost computing infrastructure available. Each deployment completely replaces the previous deployment and is reconfigured from scratch.

And most importantly, Managed Runtime offers the same enterprise-grade security and 99.99% historical uptime as all Salesforce technologies.

For more detailed information, see the [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.md).

## Mobify Branding

The Composable Storefront tools occasionally make reference to Mobify, which was the name of the company that originally developed these technologies. Mobify was acquired by Salesforce in 2020.

## Open-Source Technology

We welcome contributions to PWA Kit from the open-source community! To learn more about the contribution process, see [Contributing to PWA Kit](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/CONTRIBUTING.md).

If you like PWA Kit, consider starring the [GitHub Repo](https://github.com/SalesforceCommerceCloud/pwa-kit/). It helps others discover PWA Kit!

## Next Steps

Now that you’re familiar with the basics of PWA Kit and Managed Runtime, explore these hands-on guides:

1. [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.md)
2. [Deploy Your Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.md)

## See Also

- [Composable Storefront Release Notes](/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html)
- [Video: Use the PWA Kit to Create a New Project | Configure PWA Kit](https://www.youtube.com/watch?v=SsTBreklZ6s)
- [Video: Configure a Composable Storefront with the PWA Kit | Configure PWA Kit](https://www.youtube.com/watch?v=IUtMy_tfp38)
- [Video: How to Use the Managed Runtime Admin Tool | Configure PWA Kit](https://www.youtube.com/watch?v=zxE1SD3FuzM)

<!-- document id=5a72ee7e9f1be2ebc6e43972586d5b521b1d40729d7d3bee4f4778ed4d55cd18 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/references/about/about.md -->

# Composable Storefront Release Notes

These release notes include updates to Progressive Web App (PWA) Kit and Managed Runtime.

**tip:** The latest PWA Kit release notes are published on the [releases page on GitHub](https://github.com/SalesforceCommerceCloud/pwa-kit/releases) before they’re published here. To stay informed about new PWA Kit releases, subscribe to GitHub notifications for releases. See [Configuring your watch settings](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository).

**note:** - Release notes may be published before the relevant Github packages are updated. The release notes identify any applicable package version that a feature is available in.
- For the general B2C Commerce release notes, see [Salesforce Help](https://help.salesforce.com/s/articleView?id=commerce.b2c_rn_release_notes.htm&type=5).

## 10/08/2026

### PWA Kit 3.21 Changes

### Show Delivery Estimates for a Product in Composable Storefront

Shoppers use the Estimated Delivery Date panel to get delivery date estimates for a specific postal code. The delivery estimate for the shipping method that has the latest delivery date is shown. Also, shoppers view delivery date estimates and shipping costs based on the available shipping methods.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How**: In the Estimated Delivery Date panel of the product detail page, shoppers enter a postal code and then click **Calculate**.

![Get delivery date estimates for a product](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-delivery-date.png '{"class": "image-lg"}')

After clicking **Calculate**, the estimated delivery date is populated. To view shipping costs and more delivery dates based on shipping methods, shoppers click **View All Shipping Options**.

![The estimated delivery date appears after specifying a postal code and clicking Calculate](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-calculated-delivery-date-bopis.png '{"class": "image-lg"}')

To provide the delivery date, install the Commerce Delivery Service (CDS) Commerce App. See [Configure Commerce Delivery Service for B2C Commerce](https://help.salesforce.com/s/articleView?id=commerce.om_configure_commerce_delivery_service.htm&type=5). If a specific product variant, such as a distinct color, isn't configured in the Commerce App, the system calls the [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProduct) SCAPI endpoint to get all shipping methods. Also, it displays a default delivery estimate, such as delivery within 7 to 10 business days.

### Guest Shoppers Can Look Up Orders Quickly Without Registration

Enable guest shoppers to look up their order status, shipment tracking, and other details in a PWA Kit store for orders placed without authentication or account registration. The self-service order lookup feature reduces support inquiries and improves the post-purchase shopper experience. The guest shopper provides their order number and an email address that's different than the one in their registered account. To make sure only the order recipient can access order details, guest shoppers must undergo multi-factor verification via email. Guest order lookup returns read-only order details—guests can't make changes to the order, such as canceling an order or returning order items, which require authentication. This feature is turned off by default.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**See Also**

- [Guest Order Lookup for Unregistered Shoppers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/pwa-guest-order.md)

### Access Site Preferences Without Latency from the MRT Data Store

If your composable storefront code requires access to the site preferences that administrators manage in Business Manager, access site preferences directly from the Managed Runtime (MRT) Data Store. Accessing site preferences from the MRT data store is faster than making a Salesforce B2C Commerce API (SCAPI) call. Enable the MRT data store by using a configuration or an environment variable.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**See Also**

- [Access Site Preferences in Your Composable Storefront from the MRT Data Store](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/pwa-site-prefs.md)

## 10/6/2026 - B2C Commerce 26.10

### Managed Runtime Changes

### Restrict SCAPI Access to Managed Runtime Traffic

Available starting with B2C Commerce 26.10, the **Managed Runtime SCAPI Request Identification** feature switch locks down the Salesforce B2C Commerce API (SCAPI) so that it accepts requests only from your Managed Runtime (MRT) environments. When you enable the switch, MRT attaches a shared secret header to every request it forwards to SCAPI, so SCAPI's eCDN zone can distinguish genuine MRT traffic from a direct request sent to SCAPI from anywhere else, including one that spoofs MRT's IP range or user agent. After you enable the switch, add your own custom firewall rule to block or log direct SCAPI traffic that doesn't carry the header.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**See Also**

- [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/scapi-request-identification.md)

## 10/1/2026

### Managed Runtime Changes

## Automate Your Storefront Administration with the New B2C Commerce API (SCAPI)

The new Managed Runtime SCAPI-based APIs offer expanded administration tasks for managing Storefront Next and Composable Storefront (PWA Kit). For more information, see [Automate Your Storefront Administration with the New B2C Commerce API (SCAPI)](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-release-notes.md#automate-your-storefront-administration-with-the-new-b2c-commerce-api-scapi).

### Managed Runtime - Node 22 Deprecation

Node 22 has an end-of-life date of June 1, 2027. Starting today, developers with projects running on Node 22 see a warning that a Node.js version upgrade is required for uninterrupted deployments. We strongly recommend that you upgrade your production projects to Node 24 well ahead of the end-of-life date.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**See Also**

- [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md)

### Managed Runtime Read-Only APIs During Maintenance

During planned maintenance windows, Managed Runtime APIs reject write requests (POST, PUT, PATCH, and DELETE) with an `HTTP 503` response, error code `service_read_only`, and detail message `Service is in READ_ONLY mode`. Read requests (GET) continue to work normally.

**Where:** This change applies to Managed Runtime.

### Certificate Renewal and Expiry Notification Schedule Updated

Managed Runtime changed the timing of SSL certificate renewal and expiration notification emails. Renewal-pending notifications now fire 40 days before certificate expiry (previously 60 days). Expiration reminders are now sent at 30, 15, 7, and 2 days before expiry (previously 45, 30, 15, 7, and 2 days).

**Where:** This change applies to Managed Runtime with Composable Storefront.

## 8/25/2026

### Managed Runtime Changes

To learn about Managed Runtime changes, see [Managed Runtime Release Notes](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-mrt-release-notes.md).

## 7/28/2026

### Managed Runtime Changes

### Proxy Requests to Your Backend Now Require HTTPS

Managed Runtime proxy requests to your backend now require HTTPS. Previously, proxy requests could use HTTP, which risked sending shopper data unencrypted. This change closes that gap and requires no configuration changes if your backend already supports HTTPS, which most Commerce API and third-party endpoints do.

**Where:** This change applies to Managed Runtime with Composable Storefront.

### SSR Bundle Size Limit Lowered to 247 MB

The maximum combined size of `ssr_only` and `ssr_shared` files in an SSR bundle is now 247 MB, down from 249 MB. This reserves headroom for the fixed overhead Managed Runtime adds to every bundle, so bundles near the previous limit don't fail during publish after upload. Check your bundle size before pushing if you're close to the limit.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

**See Also**

- [Pushing and Deploying Bundles](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/pushing-and-deploying-bundles.md)

## 7/21/2026

### Apply a Shared Password to Composable Storefront and Storefront Next Environments

When you enable a Protected Storefront in Business Manager, use the new **Apply to Composable Storefront and StorefrontNext** option to require a shared password for all Managed Runtime environments associated with the site. Limiting access to a storefront under development helps prevent unauthorized users from viewing work in progress.

**Where:** This change applies to Composable Storefronts and Storefront Next in B2C Commerce.

**See Also**

- [Limit Access to a Storefront Under Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/protect-storefront.md)

## 7/7/2026

### PWA Kit 3.19 Changes

### Maintain Shopper Sessions Across Subdomains

Configure a shared parent cookie domain to keep shoppers logged in and preserve their baskets when navigating between different subdomains in hybrid PWA Kit and SFRA storefronts. Without this configuration, shoppers lose their login status and shopping baskets when crossing subdomain boundaries, such as `www.example.com` and `shop.example.com`. The loss of login status happens because browsers isolate cookies to individual hosts by default. Prevent frustration and abandoned carts by setting up a shared parent cookie domain.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How**: In Business Manager, go to **Merchant Tools > _Your Site_**. In the quick-find box, search for `hybrid auth` and then select **Hybrid Auth Settings**.

**See Also**

- [GitHub: Hybrid Cookie Domain Configuration](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/hybrid-cookie-domain-configuration.md)

### Use HttpOnly Session Cookies for Improved Storefront Security

When you enable HttpOnly session cookies, the storefront stores Shopper Login and API Access Service (SLAS) access and refresh tokens as HttpOnly cookies instead of local storage. The server-side SLAS proxy layer handles token injection transparently. Only browsers can read and send HttpOnly cookies. JavaScript code that runs on the page can't access them. Using HttpOnly cookies prevents client-side scripts from exploiting the storefront and makes the storefront more secure.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How**: Turn on HttpOnly cookies with the `enableHttpOnlySessionCookies` app configuration in `config/default.js`.

**See Also**

- [GitHub: HttpOnly Session Cookies — Architecture](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/httponly-cookies-architecture.md)
- [GitHub: HttpOnly Mode: SLAS Property Storage Mapping](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/httponly-storage-mapping.md)

### Managing Orders in Your Composable Storefront Is Available for Shoppers

The Salesforce Order Management (SOM) integration in your Composable Storefront lets registered shoppers manage orders stored in SOM. PWA Kit provides default implementations for the order actions in SOM so you don't have to implement them. The actions available for shoppers are tracking order shipments, canceling an order, and returning order items. Managing orders requires that you connect your B2C Commerce instance to the Salesforce Order Management organization.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

![Order detail page showing buttons for tracking shipments, canceling an order, and returning items](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-order-action-buttons.png '{"class": "image-xl"}')

**See Also**

- [Provide Orders from Salesforce Order Management: Managing Orders in SOM](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/order-mgmt.md#managing-orders-in-som)

## 7/6/2026

### Managed Runtime Changes

### Control Proxy User-Agent Forwarding

Control whether proxied requests forward the shopper's original browser user agent or replace it with an infrastructure user agent. The new **Proxy User Agent** setting gives your backend control over how much device and browser information it receives from proxied requests.

- **Browser**: Forwards the shopper's original user agent, including device and browser details. Use this setting if your backend personalizes responses based on device type or browser.
- **Infrastructure**: Replaces the user agent with the Amazon CloudFront value, hiding shopper device details from your backend.

Set the default for all new environments in **Project Settings**, or override it per environment in **Environment Settings > Advanced**.

**Where:** This change applies to Managed Runtime.

**See Also**

- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md)
- [Proxy Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/proxying-requests.md)

### Fix Redirect Operations for Paths with URL-Reserved Characters

Deleting, editing, or reading redirect rules that include URL-reserved characters (such as `%`, `#`, or `?`) now works correctly in Runtime Admin. Previously, these operations could fail silently for redirects whose paths included encoded or reserved characters.

**Where:** This change applies to Managed Runtime.

## 6/24/2026

### Managed Runtime Changes

### Search and Page Through Your Project List

Find any project in your organization with the new project search box in Runtime Admin. The search filters across all your projects, not just the ones on the current page. You can also choose how many projects to show per page (20, 50, or 100). Your search term and page size are saved in the page URL, so you can bookmark or share a filtered view.

**Where:** This change applies to Managed Runtime.

### Server-Side Cookie Access Is On by Default for New Projects

New projects now have Server-Side Cookie Access enabled by default, letting your storefront access and manage cookies from server-side code as required for personalization and integrations, such as Shopper Agent. Existing projects continue to have server-side cookies turned off by default.

**Where:** This change applies to Managed Runtime and Composable Storefronts.

## 6/18/2026

### Managed Runtime Changes

### x86 Server Architecture Is Scheduled for Retirement

The x86 server architecture in Managed Runtime is scheduled for retirement on **January 31, 2027**. After that date, environments running on x86 can't be deployed. Environments aren't deleted and continue to respond to requests, but deployments are blocked until the environment is switched to ARM.

The ARM architecture is already the default for all new projects. For existing projects, switch each environment's architecture in Runtime Admin under environment settings. Most projects can switch to ARM with no code changes. If your project uses architecture-specific native modules, test in a non-production environment before switching production.

**Where:** This change applies to Composable Storefronts using Managed Runtime.

**See Also**

- [Server-Side Rendering Architecture](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#server-side-rendering-architecture)
- [Feature Retirement](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/feature-retirement.md)

### HTTP Proxy Support Is Scheduled for Retirement

Managed Runtime will retire support for HTTP (non-secure) proxy configurations on **August 31, 2026**. After that date, only HTTPS proxy configurations are supported. Update any proxy configurations using HTTP to HTTPS before the retirement date to avoid disruptions.

**Where:** This change applies to Composable Storefronts using Managed Runtime proxies.

**See Also**

- [Proxy Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/proxying-requests.md)
- [Feature Retirement](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/feature-retirement.md)

## 6/8/2026

### Managed Runtime Changes

### Improved Header Forwarding for Proxy Requests

The Managed Runtime proxy now correctly forwards request headers that were previously dropped or overwritten.

- User-Agent is preserved. The original client `User-Agent` is now correctly forwarded to all origins on proxy requests.
- Access Control Headers (ACH) reach B2C Commerce API (SCAPI). ACH headers are no longer stripped before reaching SCAPI.

**Where:** This change applies to Composable Storefronts using the MRT proxy.

## 6/4/2026

### Preview Your Storefront in Business Manager

Preview your PWA Kit storefront in Business Manager to verify how it looks based on shopper context including customer groups, date and time, source code triggers, and qualifiers. Use it to test changes to products, pricing, and marketing strategies in a staging environment before deploying to production, ensuring your site displays correctly for specific scenarios like upcoming sales or seasonal campaigns. Previewing your storefront in Business Manager requires less setup than in Runtime Admin. Connect your PWA Kit storefront to B2C Commerce first to make the MRT environment and storefront data available. We recommend using PWA Kit version 3.18 or later.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

- [See Also](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/storefront-preview-bm.md)

## 5/7/2026

### PWA Kit 3.18 Changes

### Manage Express Payment Visibility Across Your Composable Storefront

Control where Express Checkout payment methods appear on your Composable Storefront using switches in Business Manager. Enable or disable Express Checkout payment methods for the Checkout, Cart, Mini-Cart, and Product Detail pages without modifying code.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How:** In Business Manager, click App Launcher, and then select **Merchant Tools** | **Site** | **Ordering** | **Salesforce Payments**. Click **Settings**. In the Express Checkout Display section, select where the Express Checkout payment methods appear on your storefront.

![Add and reorder Checkout and Express Checkout payment methods](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/express_checkout_display.png '{"class": "image-xl"}')

**See Also**

- [Customize Where Express Checkout Payment Methods Appear on Your Storefront](https://help.salesforce.com/s/articleView?id=cc.b2c_express_checkout_display.htm)

### Change the Order of the Payment Methods for Your Composable Storefront

Arrange the sequence of payment methods in Business Manager so that shoppers see your preferred options first. Organize Checkout and Express Checkout payment methods for your payment zones. This feature replaces the previous static list.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How:** In Business Manager, click App Launcher, and then select **Merchant Tools** | **Site** | **Ordering** | **Salesforce Payments**. Select a payment zone. In the Configured Payment Methods menu, select **Edit**. Drag the Checkout and Express Checkout payment methods into your preferred order.

![Add and reorder Checkout and Express Checkout payment methods](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/reorder_payment_methods.png '{"class": "image-xl"}')

**See Also**

- [Manage Payment Methods for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_manage_payment_methods.htm)

### Boost International Sales with Expanded Payment Methods for Your Composable Storefront

Provide shoppers with familiar, localized payment methods. Offer Amazon Pay for Stripe and TWINT for Adyen as native Salesforce Payments options.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How:** In Business Manager, click App Launcher, and then select **Merchant Tools** | **Site** | **Ordering** | **Salesforce Payments**. Select a payment zone. In the Configured Payment Methods menu, select **Edit** and add a payment method.

**See Also**

- [Manage Payment Methods for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_manage_payment_methods.htm)
- [Salesforce Payment Platforms and Services for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_salesforce_payments_platforms_services.htm)

<!-- ### Access Site Preferences with Zero Latency in Your Composable Storefront

If your storefront code requires access to the site preferences that administrators manage in Business Manager, access site preferences directly from the Managed Runtime Data Store instead of making a slower Salesforce B2C Commerce API (SCAPI) call.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

<!-- **See Also**
- [Integrate Site Preferences](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/site-prefs.md) -->

## 4/21/2026

### Managed Runtime Changes

### WebAssembly Static Assets

WebAssembly (`application/wasm`) files can now be uploaded as part of bundles and served as static assets, unlocking the ability to integrate high-performance client-side experiences, such as barcode scanners.

## 3/27/2026

### Build B2C Storefronts Faster with the B2C DX MCP Server (Generally Available)

The B2C DX Model Context Protocol (MCP) is now generally available. Use the B2C DX MCP to enhance your development workflow by connecting an AI assistant, such as Claude, Cursor, or GitHub Copilot, to your B2C Commerce environment. The new B2C DX MCP server is a unified MCP that is the starting point for various development tools and storefronts. The B2C DX MCP server provides your AI assistant with real-time access to B2C Commerce APIs (SCAPI), storefront development, cartridge deployment, and Managed Runtime (MRT) deployments. For example, you can use natural language prompts to deploy cartridges to a sandbox, create a custom SCAPI endpoint, and deploy a storefront to MRT without leaving your IDE!

**See Also**

- [B2C DX MCP Server](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/)

## 3/20/2026

### PWA Kit 3.17.1 Changes

### Set an Environment Base Path to Route Requests to an MRT Environment

If your composable storefront has multiple MRT environments under a single domain, set environment base paths to each MRT environment to route requests to specific environments. Also use an environment base path to host the storefront within a specific subpath.

**See Also**

- [Set an Environment Base Path](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/base-paths.md)

## 3/12/2026

### Managed Runtime Changes

### Node.js 24 Support

Managed Runtime now supports Node.js 24, bringing the latest features and security improvements to your storefronts. Node.js 24 provides enhanced performance, updated dependencies, and long-term support.

**How:** See the details at [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md). Ensure your local development environment, CI servers, and build systems are also updated to Node.js 24. Node.js 24 is available starting in [PWA Kit 3.17.0](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/3.17.0) and [PWA Kit 2.11.0](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/v2.11.0).

**See Also**

- [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md)
- [Supported Node Versions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md#supported-node-versions)

### ARM Architecture Support for Server-Side Rendering

Managed Runtime now supports ARM architecture for Server-Side Rendering (SSR), providing more efficient processing capabilities for your storefronts. ARM architecture is the default for all new projects, offering improved performance and efficiency.

**How:** ARM architecture is automatically enabled for new projects created in Managed Runtime. For existing customer projects, environments can be switched over to ARM from x86.

**Benefits:**

- Enhanced performance for server-side rendering operations
- More efficient resource utilization

**note:** Migration to the ARM architecture is required before January 31, 2027. After that date, environments running on x86 can't be deployed.

**See Also**

- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#server-side-rendering-architecture)

### PWA Kit 3.17 Changes

### Integrate Salesforce Payments into Composable Storefronts for a Seamless Checkout Experience

Streamline the checkout experience for shoppers with a native Salesforce Payments solution that supports multiple payment methods and payment gateways such as Adyen, Stripe, and PayPal. Reduce the complexity and cost of implementing payments and provide developers with extensive customization capabilities.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How:** This feature is available for Composable Storefronts after the B2C Commerce 26.3 release and the PWA Kit version 3.17 release. To enable Salesforce Payments for Composable Storefronts, see [Set Up Salesforce Payments for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_setting_up_salesforce_payments.htm).

![Checkout using Salesforce Payments](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/salesforce_payments.png '{"class": "image-xl"}')

**See Also**

- [Configure Salesforce Payments for Your B2C Commerce Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/salesforce-payments.html)

### Manage Basket Imports with the V2 Shopper Baskets API

Enhance your storefront’s reliability by transitioning to the Shopper Baskets V2 API for basket imports. This update standardized basket operations across cart and checkout to ensure that you maintain consistent data. Update your imports to V2 for all customized template files to prevent cache inconsistencies and keep your basket data synchronized for shoppers.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How:** To use the Shopper Baskets V2 aliased hooks, make sure that your B2C Commerce instance supports the Shopper Baskets V2 API, and then update your imports from @salesforce/commerce-sdk-react. Example:

```
// Before:
import {useShopperBasketsMutation} from '@salesforce/commerce-sdk-react'
// After:
import {useShopperBasketsV2Mutation as useShopperBasketsMutation} from '@salesforce/commerce-sdk-react'
```

**See Also**

- [Shopper Baskets V2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary)
- [Upgrade to Shopper Baskets V2](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-shopper-baskets-to-v2.html)

### Boost Conversion with One-Click Checkout

Offer shoppers a streamlined checkout experience and reduce cart abandonment with one-click checkout. When a first-time shopper checks out, they can now save their shipping and payment information for future use and create an account with your store. When a registered shopper returns to make another purchase, the shopper only needs to enter their email and a verification code to check out. Their shipping and payment information is automatically filled in. Shoppers always have the option to check out as a guest.

**Where:** This change applies to Composable Storefronts in B2C Commerce.

**How:** This feature is available for Composable Storefronts after the B2C Commerce 26.3 release and the PWA Kit version 3.17 release. To enable one-click checkout for Composable Storefronts, see [Configure One-Click Checkout for Your B2C Commerce Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/one-click-checkout.html).

![Save payment, address, and contact information for future use with one-click checkout](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/one_click_checkout.png '{"class": "image-xl"}')

### Build Composable Storefront Components in Page Designer Without ISML

You can now expose React-based composable storefront pages and components directly in Page Designer without building ISML storefront versions. The new Page Designer architecture removes the ISML rendering layer, so your React components render the page directly. No need to maintain duplicate storefront code. You just add metadata attributes to use the more integrated development workflow. By eliminating duplicate storefront code, you can significantly reduce development time.

**See Also**

- [Composable Storefront: Integrate Page Designer with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.html)
- [B2C Commerce: Page Designer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-dev-for-page-designer.html)

### Build B2C Storefronts Faster with the B2C DX MCP Server (Developer Preview)

Use the B2C DX Model Context Protocol (MCP) to enhance your development workflow by connecting an AI assistant, such as Claude, Cursor, or GitHub Copilot, to your B2C Commerce environment. The new B2C DX MCP server is a unified MCP that is the starting point for various development tools and storefronts. The B2C DX MCP server provides your AI assistant with real-time access to B2C Commerce APIs (SCAPI), storefront development, cartridge deployment, and Managed Runtime (MRT) deployments. For example, you can use natural language prompts to deploy cartridges to a sandbox, create a custom SCAPI endpoint, and deploy a storefront to MRT without leaving your IDE!

**important:** The B2C DX MCP Server is available as a developer preview. The B2C DX MCP Server isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality in production with these commands or tools.

**See Also**

- [B2C DX MCP Server](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/)

## 2/12/2026

### PWA Kit 3.16 Changes

### Provide Orders from Salesforce Order Management

Starting in PWA Kit 3.16, Composable Storefront orders are integrated with Salesforce Order Management (SOM). The storefront shows customer order details and order history from SOM, if available. The integration requires that you set up a connection between the B2C Commerce instance and the SOM organization. Providing shoppers with a real-time view of their past and current orders from SOM empowers them to check their order status and history, which reduces support costs. This integration keeps storefront orders synchronized with the merchant’s backend order management system.

**important:** This feature is available starting with B2C Commerce version 26.3.

**See Also**

- [Provide Orders from Salesforce Order Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/order-mgmt.md)

### Registered Shoppers Can Register and Log in Without a Password

Use SLAS to send a registered shopper a one-time password (OTP) through email for login or password reset. No third-party integration is required.

**See Also**

- [Implement Passwordless Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/passwordless-login.md)
- [Implement Password Reset](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/password-reset.md)
- [B2C Commerce API Guide: Passwordless Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html)

## 2/2/2026

### Managed Runtime Changes

### Bundle Deletion

Project admins and developers can now delete bundles they no longer need or want to retain in Managed Runtime. This feature helps keep your project organized by allowing you to remove problematic or outdated bundles, improving bundle management.

**Where:** This change applies to Managed Runtime environments accessed via Runtime Admin and the Managed Runtime API.

**How:** Use the Runtime Admin interface or the Managed Runtime API to delete bundles that are no longer needed.

**note:** You can't delete deployed bundles.

**See Also**

- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#delete-a-bundle)

### Stable Domain DNS Configuration in Environment Settings

Environment Settings now include a DNS Configuration field that shows the required DNS record value for environments that use custom domains with the Managed Runtime CDN. This enhancement simplifies the storefront launch process by providing clear DNS instructions directly within the Runtime Admin interface.

**Where:** This change applies to all Managed Runtime environments configured to use custom domains.

**How:** Go to Environment Settings in Runtime Admin to view the DNS Configuration section, which displays the CNAME record value needed to point your domain to the Managed Runtime CDN. Copy these values to configure your DNS provider during the storefront launch process.

**See Also**

- [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/launching-your-storefront.md#6-perform-the-cutover)
- [Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#edit-environment-settings)

## 1/29/2026

### Managed Runtime Changes

### Manage Certificates

Organization admins and organization users with the Manage Certificates permission can now manage TLS certificates for their Managed Runtime environments. This feature provides enhanced control over certificate lifecycle management when using the Managed Runtime CDN.

**Where:** This change applies to Managed Runtime organizations using the Managed Runtime CDN for TLS certificate provisioning.

**How:** Contact your organization admin to assign the Managed Certificates permission. Once assigned, you can request, monitor, and manage TLS certificates through Runtime Admin.

**See Also**

- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#certificate-management)
- [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/launching-your-storefront.md)
- [Decide which CDN to Use](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/decide-on-cdn.md)

### Check CDN Error Logs in Log Center

CDN Error logs with status Code `5xx` are now automatically sent to Log Center for production environments. You can search and filter these logs within Log Center alongside your existing Managed Runtime and B2C Commerce logs, providing a unified debugging experience.

**Where:** This change applies to production environments in Managed Runtime.

**How:** Access Log Center to search and filter CDN error logs. The logs appear with a service type identifier `mrt` and request types `CDN`. You can filter the logs by status code, timestamp, and other criteria to help debug issues.

**See Also**

- [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#debug-using-log-center)
- [Monitor Your PWA Kit Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/monitor-site.md)

## 12/20/2025

### PWA Kit 3.15 Changes

### Streamline Checkout with Address Autocomplete

Reduce shoppers’ keystrokes and errors at the most abandonment-prone step of checkout with address autocomplete. During checkout, a shopper now needs to enter only three characters of their shipping or billing address to instantly receive Google-powered recommendations. When the shopper selects an address from the list of recommendations, Google completes the remaining address fields.

**Where:** This change applies PWA Kit storefronts in B2C Commerce on First Party data centers.

**How:** This feature is available in PWA Kit storefronts starting with the PWA Kit version 3.15 release. To use address autocomplete, see [Configure Address Autocomplete for Your B2C Commerce PWA Kit Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/address-autocomplete.md).

![Address autocomplete shipping and billing address](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa_address_autocomplete.png '{"class": "image-xl"}')

## 11/17/2025

### Accelerate PWA Kit Development with the PWA Kit MCP Server (Developer Preview)

The PWA Kit MCP server offers intelligent tools that optimize your developer workflow in Cursor. The PWA Kit MCP Server provides AI-assisted code generation for creating your PWA Kit project, built-in best practices, and performance and accessibility testing within your development environment. In addition, you can access B2C Commerce API documentation, discover custom APIs in your Commerce instance, and get React hook recommendations without leaving your IDE.

**important:** Feature is available as a developer preview. Feature isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. All commands, parameters, and other features are subject to change or deprecation at any time, with or without notice. Don't implement functionality in production with these commands or tools.

The PWA Kit MCP server provides you with these benefits.

- Reduced time-to-market: By standardizing development workflows and providing AI-assisted code generation, development teams can accelerate storefront deployment cycles and get products to market faster.
- Lower development costs: The automated testing, best practice guidance, and code generation capabilities can reduce the need for extensive manual testing, code reviews, and troubleshooting, potentially lowering overall development expenses.
- Enhanced code quality and compliance: Automated accessibility and performance testing, combined with standardized development patterns, can improve overall code quality and help ensure compliance with web standards and accessibility requirements.

<!-- **See Also**

- [Developer Guide: Accelerate PWA Kit Development with the PWA Kit MCP Server (Developer Preview)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/mcp-server-intro.md) -->

## 11/4/2025

### PWA Kit 3.14 Changes

### Provide Rule-Based Promotions for Bonus Products in Your Storefront

Rule-based bonus product promotions expand the promotions you can offer to customers natively in your storefront without writing any custom code. Previously, only list-based bonus product promotions were available, which let shoppers choose bonus products from a list of prespecified items. With rule-based bonus product promotions, when a shopper's order meets the promotion's conditions, the shopper can choose any bonus product from a certain category or segment that meets the discounted product rule. For example, if a shopper adds \$200 worth of men's clothing to their cart, they can pick two free ties of their choice.

Keep these considerations in mind when using rule-based bonus product promotions.

- Only one bonus product promotion is supported for a qualifying item. If a product qualifies for a rule-based and a list-based bonus product promotion, only one promotion takes effect and it's the promotion with the highest priority. For example, one promotion grants the shopper two free ties of their choice when buying $200 worth of men's clothing. A higher priority promotion grants the shopper a free pair of shoes when buying a men's suit. When the shopper adds a men's suit to their cart worth $200, they can't get both promotions—they get only the free pair of shoes and not the two free ties.
- Cart-level choice of bonus product promotions aren't supported. Automatic bonus product promotions are supported.

**See Also**

- _Salesforce Help_: [Choice of Bonus Product Discount in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_choice_of_bonus_product_discount.htm&type=5)

### Test Your Hybrid App in Secondary Instance Group (SIG) Instances with Hybrid Proxy

Enable the hybrid proxy feature in the `pwa-kit-runtime` package to develop and test hybrid shopper apps that use PWA Kit and SFRA or SiteGenesis on SIG instances, such as an on-demand sandbox (ODS) or a local development server. SIG instances don't have an eCDN to route traffic to SFRA and Managed Runtime (MRT) at the same time but they can use hybrid proxy for traffic routing.

**See Also**

- [Step 2: Set Up Hybrid Locally (SIG Instances)](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md#step-2-set-up-hybrid-locally-sig-instances) in [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md)
- [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md)

## 10/2/2025

### Managed Runtime - Changes to Managed Runtime Admin Role Assignment

The Managed Runtime Admin role is now directly assigned via [Account Manager](https://account.demandware.com), making it easier to manage and clean up unused projects and environments.

### Key Changes

- New Admin Capabilities: Managed Runtime Admins will have view access to all projects within their organization.
- Role Assignment Process: The `Managed Runtime Admin` role is now assigned via Account Manager.
- Primary Organization Only: The admin role only applies to your primary Account Manager organization.
- Implementation Partner Requirements: Implementation partners managing customer organizations must use separate Account Manager accounts with different email addresses for each customer organization. We recommend leveraging [Account Manager subaddressing](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_manage_partner_access.htm&type=5).

### Action Required

Current Managed Runtime Admins must ensure they have the `Managed Runtime Admin` role assigned in Account Manager to retain organization-specific read-only permissions.

**See Also**

- [Managed Runtime Users Abilities and Roles](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/mrt-overview.md#users-abilities-and-roles)

## 9/25/2025

### PWA Kit 3.13 Changes

### Enable Agentforce Guided Shopping

Enable the Guided Shopping Agent for B2C Storefronts to provide an AI-assisted shopping experience in your storefront. This agent is powered by generative AI and advanced language models. Visitors to your storefront can take advantage of the agent's assistance to discover and purchase products to improve the shopping experience and help boost sales.

#### Required Licenses

Before you turn on the Guided Shopping Agent, enable these required licenses and required add-on licenses:

Required Licenses

- B2C Commerce
- Agentforce Service or Agentforce Sales in Enterprise or Unlimited editions

Required Add-on Licenses

- Agentforce Add-on
- Supported Editions for Messaging

**See Also**

- _Salesforce Help_: [Agentforce for Guided Shopping for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_agent_guided_shopping.htm&type=5)

### Offer a Choice of Multiple Bonus Products

The built-in support of bonus products offers shoppers a choice of adding one or more free bonus products for a qualifying product in the storefront. Providing a choice of bonus products incentivizes shoppers to buy more products and can result in increased sales. Shoppers can choose bonus products from the cart or the add-to-cart confirmation modal.

![Choice of bonus products](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa_choice_bonus_products.png '{"class": "image-md"}')

**See Also**

- _Salesforce Help_: [Choice of Bonus Product Discount in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_choice_of_bonus_product_discount.htm&type=5)

### Return Rich Search Results

Enhanced search results contain product images and prices, and search term suggestions. Enhanced search results help shoppers find the right product more easily and quickly on the storefront site. Search term suggestions are returned for partial matches when the first few letters match a product name or a category name. For example, searching for "bro" provides suggestions for "bracelet" or "bottom". In addition, plural search terms return products with the singular name too. For example, "shirts" returns products whose name includes "shirt" and "shirts".

![Enhanced search results](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa_enhanced_search.png '{"class": "image-md"}')

### Managed Runtime - Default Domain Change for New Environments

Newly created environments now use the `*.exp-delivery.com` domain instead of `*.mobify-storefront.com` as the default domain. This change affects all newly created environments.

**Important Notes:**

- Existing environments using `*.mobify-storefront.com` will continue to function normally and aren't affected by this change.
- Only new environments created after this date will use the new `*.exp-delivery.com` domain by default.
- Update public SLAS clients so that `redirectUri` includes the new default domain. See [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client)

**See Also**

- [Create an Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#create-an-environment)
- [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/mrt-overview.md)

## 9/4/2025

### PWA Kit 3.12 Changes

**important:** PWA Kit 3.12 introduces some breaking changes. To learn about the breaking changes, see the [v3.12.0](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/v3.12.0) release in the `pwa-kit` GitHub repository.

### Ship Products to Multiple Addresses and Stores in a Single Order

With the Retail React app template in PWA Kit v3.12 and later, enable multiple shipments in one order to give shoppers greater flexibility in choosing their order fulfillment options in the cart and the checkout page. For example, a shopper can order gifts for multiple recipients with different addresses in the same order. If in-store pickup is also enabled, shoppers can choose to pick up products from different stores in the same order, in addition to specifying multiple shipping addresses. For example, a shopper can send items to themselves to the locations they're traveling to, such as a home address, a hotel, and pick up items at store locations in different cities. This feature provides convenience and a faster checkout experience by avoiding the placement of separate orders for each recipient and shipment type.

**See Also**

- [Developer Guide: Ship Products to Multiple Addresses and Stores in a Single Order](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)

### Store Locator Setting Was Renamed and Moved to a Configuration

In PWA Kit v3.12, to consolidate configuration options in one file, the setting for store locator was moved from the [app/constants.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/cdea5994a47174d7ea38b3f3412b4e4393fe701a/packages/template-retail-react-app/app/constants.js) to [config/default.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/config/default.js) and the setting's name changed from `STORE_LOCATOR_IS_ENABLED` to `storeLocatorEnabled`.

```
module.exports = {
  app: {
      ...
      storeLocatorEnabled: true
  },
```

## 8/21/2025

### Managed Runtime - Node.js 20 Deprecation

Node.js 20 has reached deprecation status and will reach end of life on April 30, 2026. After this date, you will no longer be able to deploy bundles using Node.js 20 on Managed Runtime.

We strongly recommend upgrading to Node.js 22, the current recommended version, well ahead of the end-of-life date to ensure uninterrupted deployments and maintain security compliance.

To upgrade your Node.js version, see [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-node-version.html). For information about notification preferences for Node.js deprecation and end-of-life alerts, see [Opt Out of Notifications](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md#opt-out-of-notifications).

## 7/30/2025

### PWA Kit - Use Hybrid Auth in PWA Kit v2

The PWA Kit 2.10.0 release introduces compatibility with Hybrid Auth and integration with the `@salesforce/commerce-sdk-react` package. PWA Kit v2.10.0 supports only SLAS Public Clients. Previously, Hybrid Auth was available only for PWA Kit v3.10 and later.

To upgrade a PWA Kit v2 app to version 2.10.0 and implement Hybrid Auth, see [Implement Hybrid Authentication for PWA Kit v2](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-auth-pwa-kit-v2.html).

To understand the code changes, check out the [complete pwa-kit GitHub diff](https://github.com/SalesforceCommerceCloud/pwa-kit/compare/v2.9.1...v2.10.0).

## 7/22/2025

### PWA Kit - Expand Shopping Options with In-Store Pickup

Provide in-store pickup for online orders in your composable storefront app with the Retail React app template in PWA Kit v3.11 and later. By using the built-in feature, you don't have to write custom code to implement in-store pickup. Adding an option for shoppers to pick up their orders from a store boosts the store’s sales and provides more flexibility for shoppers.

**See Also**

- [Developer Guide: Expand Shopping Options with In-Store Pickup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/instore-pickup.md)

### PWA Kit - Offer Bonus Product Promotions in your Composable Storefront

The Retail React app template in PWA Kit v3.11 and later includes built-in support for automatic bonus products as part of the shopping experience. Implement bonus products without writing custom code and enhance the shopping experience. When a customer adds a qualifying product to the cart, a free bonus product is also added to the cart. Bonus products are displayed in various pages-the cart, order summary in checkout, order confirmation, and order details. Previously, bonus products weren't available in the template and required a custom implementation in the PWA app.

### PWA Kit - Sell Standard Products in your Composable Storefront

The Retail React app template in PWA Kit v3.11 and later offers built-in support for standard products, which are products that have no variants, such as color or size. Standard products are also available within product sets and product bundles. Offering standard products in your storefront increases your storefront sales and enhances shoppers' experience. Previously, standard products weren't available in the template and required a custom implementation in the PWA app.

### PWA Kit - Additional Languages in the UI

The PWA Kit user interface is now also available in Dutch (Netherlands), Polish, Danish, Norwegian, Swedish and Finnish. The new languages are in addition to English, (UK), German, French, Italian, Spanish (Mexico), Portuguese (Brazil), Japanese, Korean, Simplified Chinese and Traditional Chinese, bringing the total number of available UI languages to 16. To choose the desired UI language, select the respective value in the language dropdown in the lower left of the home page.

### PWA Kit - Accessibility (a11y) Improvement

In our ongoing commitment to accessibility, we've updated the email confirmation modal to ensure its contents are properly announced by screen readers like VoiceOver.

### PWA Kit - Control the Hydration Behavior of Your Composable Storefront and Boost your Site's Performance

Enable the `<Island/>` component in PWA Kit v3.11 to implement partial hydration. With the `<Island/>` component, you get fine-grained control over when specific server-rendered components are hydrated on the client. This targeted hydration approach improves performance by avoiding unnecessary computation and reducing time to interactivity. By deferring hydration to only essential components, you benefit from server-rendering at scale without the overhead of hydrating the entire page at once. The `<Island/>` component is inspired by Astro's Islands architecture. The `<Island/>` component enables you to choose to hydrate components on initial page load, when the browser is idle, when the component is visible in the viewport, or to never hydrate the component.

To enable the `<Island/>` component, set `PARTIAL_HYDRATION_ENABLED = true` in [app/constants.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/app/constants.js) in your app.

**See Also**

- [pwa-kit GitHub: Islands](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/app/components/island/README.md)

### PWA Kit - Support Art Direction and Responsive Preloading in `<DynamicImage/>` Components

Responsive images that the `<DynamicImage/>` component creates are now based on the `<picture/>` element in PWA Kit v3.11. This change enables art direction and responsive preloading for images. Also, we've adjusted the responsive image sizes on Product Listing Pages (PLPs) to account for the search refinements panel. Previously, image dimensions didn't consider the panel's impact, leading to significant overfetching of images. This optimization reduces unnecessary image fetches.

### PWA Kit - On-Demand Script Loading for Faster Performance

To improve site speed and Core Web Vitals, Active Data scripts are now loaded on demand rather than by default. This change ensures that these resources are only loaded when necessary, resulting in a quicker initial page load for all users.

## 7/17/2025

### Managed Runtime - Node.js Deprecation and End-of-Life Email Notifications

Proactively manage Node.js upgrades with automated email notifications. Project teams regularly receive reminder emails when their environments are using deprecated or end-of-life Node.js versions, helping ensure smooth deployments and security compliance.

Email notifications include:

- **Deprecation notifications**: Sent when a Node.js version reaches deprecation status, warning that an upgrade will be required in the future.
- **End-of-life notifications**: Sent when a Node.js version approaches end of life, after which deployments are no longer supported.

The notifications help you stay ahead of required Node.js upgrades and avoid deployment disruptions. See [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-node-version.md#opt-out-of-notifications) to learn about how to opt out of the notifications.

### Managed Runtime Enhancements

- **Sorting Redirects**: You can now sort redirects in Runtime Admin by publishing status, status code, URL, and updated by for improved management and organization.
- **Long Redirect URLs**: URLs now wrap properly for improved visibility and readability in the Runtime Admin.

## 6/20/2025

### Managed Runtime - Configurable Log Levels

Set appropriate log levels for your environment to reduce noise when debugging issues via Log Center and Log Tailing.

Use log levels to perform these tasks.

- Configure log levels (`TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`) per environment.
- Filter out unnecessary logs to focus on relevant information.

See [Manage Log Levels](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#manage-log-levels) for detailed information about configuring log levels, and [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#debug-using-log-center) and [Tail Logs on Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#tail-logs-on-managed-runtime) for more information about logs.

## 5/23/2025

### PWA Kit v3.10.0 - Source Map Support and Data Cloud Integration

PWA Kit version 3.10.0 and Retail React App version 6.1.0 introduce several key improvements.

- Source maps support for both client and server on Managed Runtime.
- Data Cloud integration with PWA Kit events. See [PWA Kit - Data Cloud Integration](#pwa-kit---data-cloud-integration).
- Page meta data tags from Business Manager now supported on Product Detail Pages (PDP) and Product List Pages (PLP).
- Improved password management with Confirm New Password field in Reset & Change Password flows.
- Enhanced performance logging for server-timing headers.
- Fixed `hreflang` alternate links and accessibility issues.

See [Debug Using Source Maps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#debug-using-source-maps) for information about using source maps in your development workflow.

### Commerce SDK React Updates v3.3.0

Commerce SDK React version 3.3.0 includes important improvements.

- Fixed guest login token handling with hybrid authentication.
- Improved cache management during logout.
- Added support for custom parameters in SLAS authorization calls.

See [v3.10.0 (retail-react-app@6.1.0 and commerce-sdk-react@3.3.0)](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/v3.10.0) on GitHub.

### PWA Kit - Data Cloud Integration

PWA Kit storefronts can now send engagement events to Data Cloud, providing enhanced visibility into real-time, unified customer data. See [Integrate PWA Kit with Data Cloud](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/integrate-data-cloud.html).

## 3/18/2025

### Managed Runtime - Improved Redirects Management and Hyderabad Region Support

Managing redirects in the Runtime Admin UI is more efficient with a new paginated table-based format, allowing you to see more redirect information up front. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).

Deployment failures on environments now provide more detailed information, giving you more clarity on corrective actions to take. See [Troubleshoot Bundle Push Errors](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html#troubleshoot-bundle-push-errors).

`ap-south-2` region (Hyderabad) is now supported for environments. See the list of [Supported Regions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#supported-regions).

Various Runtime Admin bugs have also been addressed:

- Adding multiple Environment Variables in a row via Runtime Admin is fixed
- Deleting Access Control Headers via Runtime Admin is fixed
- Storefront Preview decoding for Base64URLs is fixed

## 3/11/2025

### PWA Kit - Support for Hybrid Auth

With B2C Commerce version 25.3, hybrid authentication (auth) replaces Plugin SLAS. Hybrid auth improves the performance and stability of hybrid storefronts by moving the feature directly into the B2C Commerce platform. See [Configure a Hybrid Storefront with Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

## 2/18/2025

### Managed Runtime - Node 22 Support and Node 18 Deprecation

You can now deploy your PWA Kit projects with [Node 22](https://nodejs.org/en/blog/announcements/v22-release-announce)! To update your Node.js version, follow the instructions in [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md).

Every year, versions of Node.js exit formal support. To ensure a strong security posture and smooth developer experience, we restrict the Node version of projects deployed to Managed Runtime. Node 18 has an end-of-life date of September 1, 2025.

We strongly recommend that you upgrade your production projects well ahead of the end-of-life date. Depending on your PWA Kit version, you can update to Node 20 or 22.

### PWA Kit - Support for Social Login

This feature is generally available from Retail React App version 6.0. Improve shopper experience with reduced implementation time. With social login, shoppers can quickly log into your site and create profiles by using their social network accounts. See [Implement Social Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/social-login.md).

### PWA Kit - Support for Password Reset

This feature is generally available from Retail React App version 6.0. Improve shopper experience with reduced implementation time. With password reset, if shoppers forgot their password, they can use a verification code or a link in an email or text to regain access to their account by creating a new password. See [Implement Password Reset](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/password-reset.md).

### PWA Kit - Support for Passwordless Login

This feature is generally available from Retail React App version 6.0. Improve shopper experience with reduced implementation time. With passwordless login, shoppers can securely log into your site using a verification code or a link in an email or text instead of a password. See [Implement Passwordless Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/passwordless-login.md).

### PWA Kit - Tracking Consent Banner

A tracking consent banner is generally available with Retail React App template version 6.0 or later. Preserve shopper trust and reduce implementation costs. With the tracking consent banner, your shoppers can opt in or out of activity tracking on your site. See [Protect Privacy with a Tracking Consent Banner](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/tracking-consent.md).

### PWA Kit - Redirects in PWA Kit

This feature is generally available from PWA Kit version 3.9. Use the RedirectWithStatus component to create redirects with a status code. See [Trigger Redirects in PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/pwa-redirects.md).

## 10/28/2024

### PWA Kit - Hybrid Storefront Stability Improvements

Improve stability and performance for [hybrid storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.html) and ensure optimal shopper experience. See [Hybrid Stability Upgrade for PWA Kit Version 3.8.0](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-upgrade-v3.x.md) or [Hybrid Stability Upgrade for PWA Kit Version 2.x](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-upgrade-v2.x.md).

### PWA Kit - Personalization with Shopper Context

Personalization with Shopper Context is now pre-integrated into Retail React App version 5.0.0 or later. Support personalized shopping experiences and reduce implementation costs. With Shopper Context, you can use features such as tailored promotions, pricing, and product recommendations to increase conversion and shopper loyalty. See [Personalize with Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/personalize-with-shopper-context.md).

## 9/26/2024

### Managed Runtime - New Supported Regions

Going even more global! To optimize performance by co-locating with backend instances in [Hyperforce](https://help.salesforce.com/s/articleView?id=000388902&type=1) regions, you can now deploy your Managed Runtime environments to these [regions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#supported-regions):

- sa-east-1 - South America (São Paulo)
- eu-central-2 - EU (Zurich)
- eu-south-1 - EU (Milan)
- ap-southeast-3 - Asia Pacific (Jakarta)
- me-central-1 - Middle East (United Arab Emirates)
- il-central-1 - Israel (Tel Aviv)

### Managed Runtime - Log Center Logs for ODS and SIG Instances

Previously, you could view logs [in Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#debug-using-log-center) for only production environments associated with primary instance group (PIG) instances. Now you can view logs for secondary instance group (SIG) and on-demand sandbox (ODS) instances. These new logs count towards [log volume limits](https://help.salesforce.com/s/articleView?id=cc.b2c_configuration_for_administrators.htm&type=5).

## 8/7/2024

### PWA Kit - Optimize Site Performance with \_\_server_timing

This feature is generally available from PWA Kit version 3.7. With the `__server_timing` query parameter you can monitor the performance of your PWA Kit site to support your optimization efforts. The parameter provides access to the Server-Timing HTTP header and logs, that offer metrics about parts of the server-side rendering process such as route matching, component loading, and fetch strategies. Performance metrics logs are also available in Log Center. See [\_\_server_timing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#__server_timing).

## 7/23/2024

### PWA Kit - Update SLAS Calls to Prevent Unauthorized Access Across Sites

Retail React App version 4.0 consumes the new versions of [Commerce SDK React](https://salesforcecommercecloud.github.io/pwa-kit/) and [Commerce SDK Isomorphic](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic). These SDKs now satisfy Shopper Login and API Access (SLAS) guidance to pass `channel_id` as an argument when retrieving guest access tokens. See [Guest Tokens](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#guest-tokens).

### PWA Kit - Store Locator Support

Store locator is generally available with Retail React App version 4.0 or later and Commerce SDK React version 2.0.1 or later. With our store locator, your shoppers can find nearby storefront locations based on their ZIP code, city, and more. Easily extend your store information in Business Manager to customize the displayed location metadata on your site. See [Boost In-Store Sales with Store Locator](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/store-locator.md).

### PWA Kit - Increase Revenue with Product Bundles

Product bundles are generally available with Retail React App version 4.0 or later and Commerce SDK React version 2.0.1 or later. Use product bundles to group multiple related products into one orderable product for shopper convenience and personalization. Shoppers can update bundle variants and quantities directly in their cart. For example, an online sports apparel store can offer a "Runner’s Bundle" so shoppers can select shoe size, apparel size, and fitness tracker model directly in their cart. Product bundles can help you to reduce cart abandonment and improve inventory management. See [Product Bundles](https://help.salesforce.com/s/articleView?id=sales.cpq_bundle_products.htm&type=5).

### Managed Runtime - Origin Lockdown with Embedded CDN (eCDN)

Restrict access to a Managed Runtime environment to traffic coming from eCDN. Set a shared access control header across eCDN and environment to ensure that shoppers, bots, and crawlers don’t access your environment directly.

See the updated [Launch Your Storefront Guide](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/launching-your-storefront.md) and the new [upsertOriginHeaderModification API](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=upsertOriginHeaderModification) for details on how to configure Managed Runtime and eCDN to lock down your environment.

### Managed Runtime - Debug Faster in Log Center

Quickly find logs generated by your PWA Kit site by searching on namespaces added as prefixes to logs in Log Center. The namespace pinpoints the specific part of your codebase where an error occurred, helping you to focus your troubleshooting efforts. See [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-log-center).

## 6/20/2024

### Managed Runtime - Origin Lockdown for Third-Party CDNs

Restrict access to your Managed Runtime environment to traffic coming from your third-party content delivery network (CDN). Set a shared access control header across your CDN and environment to ensure that shoppers, bots, and crawlers don’t access your environment directly.

See [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#access-control-headers) and the [projects_target_access_control_header_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_access_control_header_create) API to learn how you can lock down your environment.

## 6/19/2024

### PWA Kit - Product Tile Enhancements

Drive conversion and shopper engagement and reduce implementation costs with our greatly improved product tiles available in the PWA Kit Retail React App. Product tiles now feature:

- Promo callouts
- Strike-through pricing
- Product tile swatches for variant selection
- Product badges
- Use of the productSearch API with expansions, which offers improved performance over the combination of the productSearch and getProduct(s) APIs

## 6/18/2024

### PWA Kit - BM-Generated Sitemaps Available for Headless Sites

Easily create a sitemap in Business Manager (BM) for your headless or PWA Kit storefront built on B2C Commerce. Sitemaps provide search crawlers with instructions on the pages to index and site hierarchy and they help to improve SEO ranking. See [Improve SEO with a Sitemap](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/create-a-sitemap.md).

### PWA Kit - Collect Active Data Order Events

PWA Kit now supports the collection of Active Data order metrics. Use this collection to understand customer behavior and optimize your merchandising and segmentation strategy. See [Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/active-data.md).

## 6/17/2024

### Managed Runtime - Environment Variable Support

Use Runtime Admin to manage environment variables. This feature is available as an alternative to managing environment variables by using the Managed Runtime API. Environment variables allow you to add variables into the application process running in an environment, without having to make code changes. See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/environment-variables.md).

## 6/3/2024

### Managed Runtime - Centralized Logs in Log Center

This feature is now generally available.

Troubleshoot errors in your site built with PWA Kit by using Log Center:

- Search and filter many logs. Check historical logs.
- Access a single user interface to view logs from [Managed Runtime (MRT)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#tail-logs-on-managed-runtime) and your B2C Commerce instance. Connect what’s happening in your MRT environment with what’s going on in your B2C Commerce instance.
- Easily see MRT logs without using a CLI.

See [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#debug-using-log-center).

## 3/28/2024

### PWA Kit - SLAS Private Client Support

This feature is generally available from PWA Kit version 3.5. Check the [releases page on GitHub](https://github.com/SalesforceCommerceCloud/pwa-kit/releases) for the latest available version of PWA Kit.

Enable a Shopper Login and API Access Service (SLAS) private client in your PWA Kit site so you can support these features with reduced implementation time:

- Passwordless login
- Password reset
- Faster page load times

See [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html).

## 3/15/2024

### Managed Runtime - CDN Performance Enhancements

Get reduced page load times after redeploying your bundles. These Content Delivery Network (CDN) enhancements improve app performance:

- HTTP/3 — We automatically use the [HTTP/3](https://en.wikipedia.org/wiki/HTTP/3) protocol for all browsers and clients that support it. HTTP/3 improves performance, especially for shoppers who use network-constrained devices, such as mobile.
- Cross-region CDN caching — We automatically use cached responses across regions to improve the cache hit ratio and performance for sites with a global audience.
- More CDN regions — We added more regions to the CDN, resulting in faster response times and shorter network hops if you use a stacked CDN setup.

## 2/2/2024

### Managed Runtime - Cookie Support

Use Runtime Admin to enable server-side cookies. This feature is available as an alternative to enabling server-side cookies by using the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update). Using server-side cookies helps you enhance privacy and security and supports more tailored personalization and marketing. See [Personalize with Cookies](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/personalize-with-cookies.md).

### Managed Runtime - Source Maps for Debugging

Use Runtime Admin to enable source maps. This feature is available as an alternative to enabling source maps by using the Managed Runtime API. Source maps are designed to greatly improve the development and debugging experience by enhancing error stack readability. See [Debug Using Source Maps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-source-maps).

## 1/19/2024

### PWA Kit - Storefront Preview Integration with a Third-Party CMS

Use a third-party content management system (CMS) with Storefront Preview. For example, if you have a holiday sale banner managed by your CMS, use Storefront Preview to see how the banner will appear on your site during your specified time period. See [Storefront Preview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/storefront-preview.md).

### PWA Kit - Validate Customer-Specific Site Changes

Preview how your Progressive Web App (PWA) Kit site will look based on one or more customer group IDs. For example, preview your site as it would appear to shoppers who get an employee discount. See [Preview Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/storefront-preview.md#preview-your-storefront).

### Managed Runtime - Node 20 Support

Projects can now deploy with [Node 20](https://nodejs.org/en/blog/announcements/v20-release-announce)! PWA Kit projects will need to upgrade to the latest 3.4.x version and follow the instructions in [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md).

### Managed Runtime - Osaka Region

Customers in Japan can now run their environment in the Osaka region, in addition to the existing Tokyo region. Your region can be changed via Environment Settings.

### Managed Runtime - Source Maps for Debugging

Source maps are now available in Managed Runtime. This feature is designed to greatly improve the development and debugging experience by enhancing error stack readability. Source Maps can be generated starting in PWA Kit 3.4.x, and can be enabled by toggling the `enable_source_maps` environment setting. See [Debug Using Source Maps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-source-maps).

## 2023

### 11/30/2023

#### PWA Kit - Improve Customer Engagement with Active Data

Use Active Data in your PWA Kit site to observe product performance metrics and set automated rules for merchandising. See [Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/active-data.md).

### 11/2/2023

#### PWA Kit - Validate Upcoming Site Changes with Storefront Preview

Use the Storefront Preview feature to see how your PWA Kit site will look in different contexts such as specified source code, customer groups, or a particular date or time. For example, preview your site changes in a staging environment before deploying them to production. See [Storefront Preview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/storefront-preview.md).

#### Managed Runtime - Enhanced Integration with B2C Commerce

When you create an environment in Runtime Admin, you can now select a B2C Commerce instance and sites to connect to the environment. This allows for deeper integration between your Managed Runtime environments and the B2C Commerce platform. You can also use new Managed Runtime API endpoints to manage and track your environments’ connections to B2C Commerce instances. For more information, see this documentation:

- [Create an Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html?#create-an-environment)
- [Managed Runtime API Tutorial](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.html#tutorial)
- [cc_b2c_organization_info_retrieve](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=cc_b2c_organization_info_retrieve) (can be outdated or unavailable before 11/8/2023)
- [cc_b2c_target_info_retrieve](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=cc_b2c_target_info_retrieve) (can be outdated or unavailable before 11/8/2023)
- [cc_b2c_target_info_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=cc_b2c_target_info_partial_update) (can be outdated or unavailable before 11/8/2023)

For release notes published before October 2023, see:

- [PWA Kit Release Notes](https://help.salesforce.com/s/articleView?id=commerce.b2c_pwa_kit_release_notes_archive.htm&type=5)
- [Managed Runtime Release Notes](https://help.salesforce.com/s/articleView?id=commerce.b2c_managed_runtime_release_notes.htm&type=5)

<!-- document id=1f127b10512a596497eb99723a3c6be73f8d4eadf89f3d962d57f796b3efd006 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-configuration.md -->

# Configuration and Discovery

Enable UCP for your storefront in **Salesforce Commerce Business Manager**. Those settings power your **business profile**—the document platforms fetch to learn what you support before they start a checkout.

This is how platforms discover your _capabilities_ (services, payment handlers, protocol version). Product discovery and platform onboarding are platform-specific; for Google, see [Enabling Google as a Platform](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md). To call Checkout Session APIs after the profile is published, see [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md).

## Business Profile

Platforms don't start at checkout. They retrieve your business profile from a well-known URL. B2C Commerce publishes that profile from the UCP settings you save in Business Manager. The discovery endpoint is unauthenticated and is meant to be called before any checkout-session request. Checkout Session APIs themselves require SLAS; see [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md).

Starting with B2C Commerce release 26.9, Salesforce publishes a versioned profile:

| Endpoint                         | What it returns                                                                                                               |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `GET /.well-known/ucp`           | The root profile at your preferred protocol version, plus a `supported_versions` map of other versions this release can serve |
| `GET /.well-known/ucp/{version}` | A complete leaf profile pinned to that protocol version. Leaf profiles don't include `supported_versions`                     |

```
https://{shortCode}.api.commercecloud.salesforce.com/ucp/shopper-ucp/v1/organizations/{instanceId}/sites/{siteId}/.well-known/ucp
https://{shortCode}.api.commercecloud.salesforce.com/ucp/shopper-ucp/v1/organizations/{instanceId}/sites/{siteId}/.well-known/ucp/{version}
```

Replace `{shortCode}`, `{instanceId}`, and `{siteId}` with values for your instance and site.

After you save UCP settings in Business Manager, GET the root well-known URL and confirm the profile before you test checkout sessions. Check that `ucp.version`, capabilities, and payment handlers match what you configured.

### What the Profile Advertises

The profile declares:

- **Services** — the shopping API endpoint platforms use for checkout sessions
- **Capabilities** — checkout, fulfillment, and order (order is advertised so platforms can receive lifecycle webhooks; there is no shopper Order GET in this release)
- **Payment handlers** — how the platform acquires payment credentials (assembled from Business Manager when you use Salesforce Payments)
- **Signing keys** — public keys platforms use to verify order lifecycle events

| Business Manager setting                                                      | Where it shows up                                                |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| UCP Active                                                                    | Profile and checkout APIs are served only while UCP is enabled   |
| Payment Provider, Payment Zone, Google Pay Merchant ID / Name, Storefront URL | `ucp.payment_handlers` on the profile (Salesforce Payments path) |
| Saving UCP settings                                                           | `signing_keys` generated automatically on the profile            |

Continue URL, Privacy Policy URL, and Order Lookup URL are returned on checkout session responses, not on the well-known profile. Configure them in [UCP Checkout Settings](#ucp-checkout-settings).

### Protocol Versions

B2C Commerce release 26.9 supports protocol versions `2026-01-23` and `2026-04-08`. The root profile is a single version. Other supported versions appear in `ucp.supported_versions` as URLs to the leaf endpoint.

If a platform requests a version this release doesn't support, `GET /.well-known/ucp/{version}` returns HTTP `422` with the UCP error code `version_unsupported`.

**note:** **Customizing the profile**

Salesforce assembles the default profile from Business Manager. To replace payment handlers—for example when you use a [third-party payment provider](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#third-party-payment-providers)—implement `sfcc.ucp.shopperBusinessProfiles.v1.businessProfile.modifyGETResponse`. Don't change `ucp.version` in that hook.

## UCP Checkout Settings

Go to **Merchant Tools > AI & Social Integrations > UCP** to configure the protocol. The fields on this screen are what B2C Commerce writes into the business profile and checkout session responses.

### Mandatory URLs

| URL                         | Description                                                                                                                             |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Storefront URL              | Your live site's base domain                                                                                                            |
| Privacy Policy URL          | Direct link to your legal privacy terms                                                                                                 |
| Order Lookup URL            | Direct link to order lookup page                                                                                                        |
| Continue URL (Handoff Path) | URL returned on checkout session responses when a session can't finish on the platform (such as age verification or complex promotions) |

### Continue URL Limitations

Salesforce returns this URL on checkout session responses when a session can't finish on the platform. **Whether the platform shows it, how it is labeled, and when the shopper is sent there is up to the platform.** You can't control that UX.

If a platform does send the shopper to your Continue URL:

- **Without a storefront plugin**, they land with an empty cart and must re-add items. Avoid that handoff when you can by handling the case in hooks. If you can't, use a landing page that explains why they are on your site and links to the products they were buying.
- **With the SFRA plugin** [`plugin_universal_commerce_protocol`](https://github.com/SalesforceCommerceCloud/plugin_universal_commerce_protocol), the UCP basket is promoted onto the storefront so they land on checkout with their items intact. See the plugin README for installation, hybrid auth, cartridge path, service credentials, and extension hooks.

When you use the plugin, the **Continue URL** field in **Merchant Tools > AI & Social Integrations > UCP** must point to the plugin's route **with the `basketId` and `usid` placeholders**. UCP substitutes those values at handoff time. If they are missing, the plugin has nothing to promote and the buyer lands with an empty cart.

```
https://{storefrontDomain}/on/demandware.store/Sites-{SiteId}-Site/{locale}/UCPContinue-Start?basketId={basketId}&usid={usid}
```

Replace `{storefrontDomain}`, `{SiteId}`, and `{locale}` with values for your site. Leave `{basketId}` and `{usid}` literal—those are UCP's substitution tokens, not values you fill in.

### Payment Provider Setup

In the "Payment Setup" section of the UCP Configuration screen, select which **Payment Provider** you use for UCP checkout:

- **Salesforce Payments** (default) — the platform assembles the Google Pay / Salesforce Payments handler automatically from the Payment Zone, Google Pay Merchant ID, and Google Pay Merchant Name fields.
- **Third Party Provider (DIY)** — hides the Salesforce Payments fields and expects your custom hook implementation to provide the payment configuration. See [Third-Party Payment Providers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#third-party-payment-providers).

For this release, Google Pay is the only payment method the native Salesforce Payments handler advertises, whether you select Salesforce Payments or a third-party payment provider. Google as a platform still expects Google Pay today.

#### Salesforce Payments

If you use Salesforce Payments as your UCP payment engine (the default), the Salesforce Payments SKU is required. You can use Adyen via Salesforce Payments or Stripe Salesforce Payments. Because the native Salesforce Payments path uses Google Pay, Google Pay must be active in your gateway dashboard.

- Locate your Google Pay Merchant ID and Merchant Name from the Google Pay Console to enter into Business Manager.
- For **Adyen via Salesforce Payments**, the ID must match the Google Pay Merchant ID listed as the MID in your Live Adyen Customer Area.
- For **Stripe via Salesforce Payments**, Google Pay must be enabled on the Stripe account used by the payment zone.

### Auto-Fail Orders

Go to **Merchant Tools > Site Preferences > Order** and set Auto-Fail Orders (in minutes). Salesforce Payments places orders asynchronously; set this long enough for the Adyen or Stripe webhook to arrive.

**note:** **Adyen third-party cartridge users**

If you're using the Adyen third-party cartridge for processing `adyenNotifications`, configure the Process job to run more frequently than the AutoFail order job's timeout. This makes sure webhooks are processed before orders become eligible for auto-failing. Under normal conditions, only orders that receive no webhook within the timeout window are auto-failed. If a webhook arrives later, the AUTHORISATION handler attempts recovery as designed.

Consider these site preferences to make the recovery process more resilient:

- `OversellWhenUndoFailOrder` - prevents inventory contention from blocking order recovery
- `SkipCouponRedemptionLimitWhenUndoFailOrder` - prevents coupon limits from blocking order recovery

### Security

When you save, the platform automatically generates signing keys (private/public) to secure Order lifecycle event delivery to the platform. Checkout Session APIs are authorized with a SLAS shopper token; see [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md).

## Order Management System (OMS) Integration

Set up your OMS to work with UCP so customers can receive automatic shipping updates or status changes within the platform experience. This is in addition to other provided order tracking through existing channels (email, your website).

Salesforce OMS integration is optional for UCP:

- **With Salesforce OMS:** Out-of-the-box full order lifecycle event tracking to the platform (shipping confirmations, cancellations, status updates)
- **Third-party OMS:** Connect an external Order Management System so it serves order data through the same Shopper Orders and Shopper Customers SCAPIs. See [Connect a Third-Party OMS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/commerce-apps/connect-third-party-oms.md). See [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md) for how those events become signed UCP snapshots.

## Disable or Roll Back UCP

Turn **UCP Active** off to disable UCP or roll back the integration. Your Business Manager settings stay in place.

### Disable UCP

To disable UCP while keeping your configuration intact:

1. Go to **Merchant Tools > AI & Social Integrations > UCP** in Business Manager
2. Turn **UCP Active** off
3. Save the settings

#### Effect

- New orders from the platform fail to initiate
- The system aborts in-flight checkout sessions
- If using Google, your product feed in GMC remains active but products aren't available for purchase through Google
- All configuration is preserved for when you re-enable

<!-- document id=f08ee9856f99ad1b77305f8cc5aa829df84cdc30532384e55a60ffea6c8bcd2b url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/configuration-options.md -->

# Configuration Files

With configuration files, you can customize many aspects of how your PWA Kit application works, including: API access, URL formatting, handling multiple sites, request proxying, and server-side rendering.

A configuration file can be written in your choice of JavaScript, YAML, or JSON. The following file extensions are supported: `.js`, `.yml`, `.yaml`, and `.json`.

When a PWA Kit project is created with the Retail React App template, it comes with a single configuration file: `/config/default.js`. The configuration objects that it exports are set based on the options provided to `pwa-kit-create-app`, but you can update your configuration at any time. Updates are often necessary after the initial project generation to stay in sync with changes to B2C Commerce instances.

**note:** To support isomorphic rendering, configuration values are serialized to page. **Don't place secrets in your configuration!**

You can replace `default.js` or complement it with additional configuration files because PWA Kit supports environment-specific configurations, which are covered later in this guide.

Let's start by looking at the specific configuration objects and properties available in `default.js` or any configuration file.

**note:** The project string that associates your application with Managed Runtime is _not_ part of a configuration file, but can be found in the `name` property at the top of the `package.json` file at the root of your project directory. After initial project generation, you can change the value of `name` to match the project ID that you see in Runtime Admin.

## API Access

**note:** Before version 1.5.0 of PWA Kit, these settings were in `api.config.js`.

To configure access to the B2C Commerce API and Open Commerce API (OCAPI), you can edit the `app.commerceAPI` object that is exported from the configuration file.

Here's an annotated code snippet with example values:

```javascript
commerceAPI = {
  proxyPath: `/mobify/proxy/api`,
  parameters: {
    clientId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', // Client ID (UUID) for API access used by the Shopper Login and API Access Service (SLAS)
    organizationId: 'f_ecom_xxxx_xxx', // Organization ID from Business Manager
    shortCode: 'xxxxxxxx', // Short code from Business Manager
    siteId: 'RefArch' // Site ID from Business Manager
  }
}
```

To configure access to the Einstein API, you can edit the `app.einsteinAPI` object.

Here's another annotated code snippet with example values:

```javascript
einsteinAPI = {
  host: 'https://api.cquotient.com',
  einsteinId: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', // Client ID (UUID) for API access used for Einstein API
  // This differs from the siteId in commerceAPIConfig for testing purposes
  siteId: 'aaij-MobileFirst'
}
```

For more information on the `CommerceAPI` class that consumes the configuration object in the previous code snippet, see our architecture guide to [The Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md#commerce-api).

For more information on the setup tasks in Account Manager and Business Manager to enable API access for a B2C Commerce instance, see our guide to [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md).

## URL Formatting

You can customize how storefront URLs are formatted in the `app.url` object.

The `app.url` object is configured with the following values by default:

```javascript
url: {
    site: 'path',
    locale: 'path',
    showDefaults: true
},
```

With these defaults settings, both the current site and locale are displayed in the URL path.

You can choose how the current locale appears (or doesn’t appear) in the URL by setting `url.locale` to one of the following values:

- `path`: Locale is included in the URL path. Example: `/en-US/women/dress`
- `query_param`: Locale is included as a query parameter. Example: `/women/dress?locale=en-US`
- `none`: Locale isn’t included in the URL. Example: `/women/dress`

`url.showDefaults`: This boolean value dictates whether the default site or locale values are shown in the url. Defaults to: false.

## Handling Multiple Sites

We extract the sites configured for your application into its own file called `config/sites.js`. This file is imported into each configuration file and exported within the `app` object. Separating the files this way allows you to more easily synchronize the sites supported by your application and the sites defined in your Business Manager backend. (You can define your sites directly in the configuration file, if you prefer.)

The `app` object also contains other settings for managing multiple sites and their aliases. These settings are covered in more detail in our guide to [Multiple Sites](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/multiple-sites.md).

## Request Proxying

Request proxying is configured in the `ssrParameters.proxyConfigs` array, which is covered in detail in our guide to [Proxying Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md).

## Server-Side Rendering

**note:** Before version 1.5.0 of PWA Kit, these settings were in `package.json`.

The following table highlights the configuration options related to server-side rendering. These options are not part of the `app` object and are expressed as individual properties of the main `exports` object.

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">Property</th>
<th colspan="1" rowspan="1">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1"><code>ssrParameters.ssrFunctionNodeVersion</code></td>
<td colspan="1" rowspan="1">String that determines which version of Node to use for running the App Server.<br />
<br />

Allowed values: Supported [Node version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-node-version.md#supported-node-versions)</td>

</tr>
<tr>
<td colspan="1" rowspan="1"><code>ssrEnabled</code></td>
<td colspan="1" rowspan="1">Boolean that enables or disables building the files necessary for server-side rendering. <b>Setting this value to <code>false</code> is deprecated as of August 2021</b>.</td>
</tr>
<tr>
<td colspan="1" rowspan="1"><code>ssrOnly</code></td>
<td colspan="1" rowspan="1">Array of <a href="https://www.npmjs.com/package/minimatch">glob expressions</a> where <code>*</code> is a wildcard matching zero or more instances of any character. <br /><br />Determines which files are available exclusively to the server-side rendering system and are <i>not</i> available through the <code>/mobify/bundle/</code> path.<br />
<br />
Defaults for a newly generated project: <code>['ssr.js', 'ssr.js.map', 'node_modules/**/*.*']</code>

</td>
</tr>
<tr>
<td colspan="1" rowspan="1"><code>ssrShared</code></td>
<td colspan="1" rowspan="1">Array of <a href="https://www.npmjs.com/package/minimatch">glob expressions</a> where <code>*</code> is a wildcard matching zero or more instances of any character.<br /><br />Determines which files <i>are</i> available to the server-side rendering system <i>and</i> available through the <code>/mobify/bundle/</code> path.<br />
<br />
Defaults for a newly generated project:

```javascript
"ssrShared": [
"static/ico/favicon.ico",
"static/robots.txt",
"**/*.js",
"**/*.js.map",
"**/*.json"
]
```

</td>
</tr>
</tbody>

</table>

## Environment-Specific Configurations

You can include multiple configuration files in the `config` directory, including configuration files for specific environments.

Environment-specific configurations can make your deployments more efficient and flexible. For example, you can:

- Deploy a single bundle to multiple Managed Runtime environments and have each of environment connect to a different B2C Commerce instance.
- Connect to your own on-demand sandbox during local development but connect to different instances when deployed to Managed Runtime.

To create an environment-specific configuration file, follow the same conventions used in `default.js`, but use the name of the target environment as the base name of the file. Use any of the supported file formats and the corresponding file extension. Examples: `production.js`, `staging.json`.

## Loading the Right Configuration

A PWA Kit application chooses the right configuration file to load by searching the `config` directory and asking the following questions, in the following order:

1. Is there a file that matches the name of the currently running environment on Managed Runtime?
2. If it's running locally, is there a file called `local` with a supported file extension?
3. If no configuration file has been found yet, is there a file called `default` with a supported file extension?

As soon as the answer to one these questions is "Yes," PWA Kit stops looking and loads the file in question.

If two files have the same base name but different file extensions, the file extension with the highest assigned precedence is chosen. The supported file extensions are assigned precedence in the following order, ranging from highest to lowest precedence: `.js`, `.yml`, `.yaml`, or `.json`. That means that between `default.js` and `default.json`, PWA Kit would load `default.js` because it has the higher precedence.

<!-- document id=371e496cc955ea723281c39c7005924e715bc31fa37926c7185903c34e95dddd url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-default-idp.md -->

# Configure a Default IDP

If you're using Shopper API Access and Login (SLAS) with 3rd party identity providers (IDP) and you would like to use an IDP that is not [supported by SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-identity-providers.md), use SLAS' Default IDP feature to communicate with your IDP.

This guide covers the steps required to configure a Default IDP with SLAS using either the SLAS Admin API or UI.

Depending on your IDP, there are two ways to configure it:

- If the IDP does not support the [OpenID Connect Discovery](https://datatracker.ietf.org/doc/html/rfc8414) (OIDC) protocol, use SLAS Admin UI or the SLAS Admin API's [registerIdentityProvider](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider) endpoint.
- If the IDP supports the [OpenID Connect Discovery](https://datatracker.ietf.org/doc/html/rfc8414) protocol, use SLAS automation.

**important:** SLAS only supports IDPs that support OpenID Connect. SLAS does not support SAML.

## Default IDP Configuration Requirements

Configuring a default IDP requires the same SLAS properties as supported IDPs:

- The `name`, `clientId`, `clientSecret`, IDP urls, scopes, and `preferenceValue` are all required SLAS IDP client configuration values. For details, see [Register an Identity Provider.](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider)

with the following additional requirements:

- Provide the `oidcClaimMapper` property. It is used to map the IDP's token claims to SLAS' required IDP keys to get user information when the user successfully authenticates. The `oidcClaimMapper` property is a list of strings in which each string's format is `$KEY=$VAL`, where `$KEY` is a required SLAS IDP key and `$VAL` is the name of the corresponding IDP token claim. For example: `accessToken=access_token`. `accessToken` is the SLAS key, and `access_token` is the IDP Claim.
- Map each of the following keys to the applicable IDP value:
  - `accessToken`: Value of access token.
  - `accessTokenTTL`: Time to live of access token.
  - `refreshToken`: Value of the refresh token.
  - `idToken`: Value of the ID token.
  - `subject`: The subject. This is the unique identifier of the shopper.
  - `userId`: Also the subject. This is the unique identifier of the shopper.
  - `email`: Shopper's email.
  - `familyName`: Shopper's family name.
  - `givenName`: Shopper's given name.
  - `name`: Shopper's full name.
- Verify the values that are returned by your identity provider for IDP `/token` and `/userinfo` endpoints are correct.

The following example can be used as a starting point for SLAS IDP configuration:

```text
"oidcClaimMapper":
[
    "accessToken={access_token}",
    "refreshToken={refresh_token}",
    "accessTokenTTL={expires_in}",
    "idToken={id_token}",
    "subject={sub}",
    "email={email}",
    "userId={sub}",
    "familyName={family_name}",
    "givenName={given_name}",
    "name={name}"
]

```

## Default IDP Configuration with SLAS Admin User Interface

To configure a Default IDP using the SLAS Admin user interface (UI):

1. Navigate to the **Idps** tab.
2. Select **Add Idp**.
3. Select the **Idp Name** field and then select `default` from the drop down menu.
4. Add all applicable information. In the **Default IDP Claim Map** field, add the `oidcClaimMapper` keys described in the previous section.
5. Save your configuration information.

## Default IDP Configuration with registerIdentityProvider Endpoint

If the third-party IDP does not support the [Open ID Connect Discovery](https://datatracker.ietf.org/doc/html/rfc8414) protocol, use SLAS Admin API's [registerIdentityProvider endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider) to configure a Default IDP. For example:

```sh
curl --location --request PUT '<SLAS Host>/tenants/<SLAS Organization>/idps/default-idp' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <SLAS Admin Token>
--data '{
    "name": "default-idp",
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "authUrl": "https://idp.example.com/oidc/auth",
    "tokenUrl": "https://idp.example.com/oidc/token",
    "tokenInfoUrl": "https://idp.example.com/oidc/tokenInfo",
    "userInfoUrl": "https://idp.example.com/oidc/auth/userInfo",
    "redirectUrl": "https://'$CODE'.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/default-idp",
    "wellKnownUrl": "http://localhost:9011/a8f79c10-0d31-b7a9-8409-5979e1ba4d86/.well-known/openid-configuration",
    "origin": "default",
    "preferenceValue": false,
    "scopes": [
        "openid",
        "offline_access"
    ],
    "keyId": "",
    "teamId": "",
    "isClientCredsBody": 0,
    "loginMergeClaims": null,
    "oidcClaimMapper": [
        "accessToken=access_token",
        "refreshToken=refresh_token",
        "accessTokenTTL=expires_in",
        "idToken=id_token",
        "subject=sub",
        "userId=sub",
        "email=email",
        "familyName=family_name",
        "givenName=given_name",
        "name=name"
    ],
    "isClientCredsBody": false
}'
```

## Default IDP Configuration with SLAS Automation

If the IDP supports the [Open ID Connect Discovery](https://datatracker.ietf.org/doc/html/rfc8414) protocol, the simplest way to configure a Default IDP is to use the identity provider `.../well-known/openid-configuration` endpoint. SLAS can then automatically configure your Default IDP.

Specify the following required properties for automated Default IDP configuration:

- `wellKnownUrl`: The URL of the IDP's Open ID Connect Discovery endpoint.
- `useWellKnown`: A boolean that when set to `true` indicates that SLAS should attempt to automatically configure the Default IDP using the Open ID Connect Discovery endpoint.

For example:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/$TENANT/idps/default-idp" \
    --request 'PUT' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --data-raw '{
        "name": "default-idp",
        "clientId": "my-client-id",
        "clientSecret": "my-client-secret",
        "redirectUrl": "https://'$CODE'.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/default-idp",
        "origin": "default-idp",
        "preferenceValue": false,
        "wellKnownUrl": "https://idp.example.com/.well-known/openid-configuration",
        "useWellKnown": true
    }'
```

A successful third-party IDP response contains `"claims_parameter_supported": true` and the OIDC claim mappings for SLAS configuration. If `claims_parameter_supported` is not returned, then SLAS uses a default mapping. The IDP token claims for UserInfo can be found in the `/.well-known/openid-configuration/` response from the `claims-supported` section, for example:

```text
"claims_parameter_supported": true,
"claims_supported": [
    "aud",
    "sub",
    "iss",
    "auth_time",
    "name",
    "given_name",
    "family_name",
    "preferred_username",
    "email",
    "acr"
],
```

SLAS then uses the `wellKnownUrl` for configuration, and if successful, returns information similar to the following example:

```json
{
"id": 111,
"name": "default-idp",
"clientId": "my-client-id",
"clientSecret": "my-client-secret",
"authUrl": "http://localhost:9090/realms/SLAS_Realm/protocol/openid-connect/auth",
"tokenUrl": "http://localhost:9090/realms/SLAS_Realm/protocol/openid-connect/token",
"tokenInfoUrl": "http://localhost:9090/realms/SLAS_Realm/protocol/openid-connect/token",
"userInfoUrl": "http://localhost:9090/realms/SLAS_Realm/protocol/openid-connect/userinfo",
"redirectUrl": ""https://'$CODE'.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/default-idp"",
"wellKnownUrl": "https://idp.example.com/.well-known/openid-configuration",
"origin": "default-idp",
"isPreferred": true,
"scopes": [
"openid",
"phone",
"offline_access",
"roles",
"address",
"microprofile-jwt",
"profile",
"web-origins",
"email",
"acr"
],
"keyId": "",
"teamId": "",
"oidcClaimMapper": [
"accessToken=access_token",
"refreshToken=refresh_token",
"accessTokenTTL=expires_in",
"idToken=id_token",
"subject=sub",
"userId=sub",
"email=email",
"familyName=family_name",
"givenName=given_name",
"name=name"
]
}
```

## Troubleshooting

SLAS takes the IDP response and applies `oidcClaimMapper` information. Authentication fails and a 400 response code is returned if:

- A required mapping parameter is missing.
- A required mapping field or mapping value is invalid, for example: an invalid URL.
- One or more corresponding claims cannot be found in the IDP token response.

In the event of an error, review your `oidcClaimMapper` information for errors. Make sure that your mapping includes valid values for all required fields.

<!-- document id=6f93cb46e6c78996c91bdc2106725f08be72bb9a6a1e3cc601a4ef35105ed4ac url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/hybrid-auth.md -->

# Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)

Starting with B2C Commerce version 25.3, hybrid authentication (Hybrid Auth) replaces Plugin SLAS. Hybrid Auth keeps the SFRA/SiteGenesis session (`dwsid`) and SLAS authorization (JWT) synchronized across a storefront that spans PWA Kit (Composable Storefront) and platform-rendered routes.

This guide covers the **PWA Kit / Composable Storefront** implementation path on **PWA Kit v3**. It's the path for new Hybrid Auth implementations—new customers must start on PWA Kit v3.

**note:** - For the shared, architecture-neutral setup (Business Manager Hybrid Auth settings, SLAS session bridging, Shopper Context, Do-Not-Track synchronization, and basket merge), see [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md).
- Building a **Storefront Next** hybrid storefront instead? See [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid.md).
- Maintaining an **existing PWA Kit v2.x** project that isn't moving to v3 yet? See [Hybrid Auth Implementation with PWA Kit v2.x](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-pwa-kit-v2.md).

## Prerequisites

Build your PWA Kit site with:

- `commerce-sdk-react@4.0.0` or later
- Progressive Web App (PWA) Kit version 3.12 or later

For details, see [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.html).

## Complete the Shared Hybrid Auth Setup First

Before configuring PWA Kit, complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md):

- Create a SLAS client (public or private) and add the `sfcc.session_bridge` scope.
- Enable Hybrid Auth in Business Manager (**Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings**) using the same SLAS client ID.
- (Optional) Enable Shopper Context and Do-Not-Track synchronization.
- Remove `plugin_slas` from the cartridge path if you previously used Plugin SLAS.

## Configure PWA Kit for Hybrid Auth

After you complete the shared setup, configure your PWA Kit project with the following steps.

### Step 1: Create or Update Your PWA Kit Retail React App

Do either of these:

- Create a Retail React App with a SLAS public or private client configuration:
  - Run the generator command in a terminal window: `npx @salesforce/pwa-kit-create-app my-hybrid-storefront`.
  - Select **The Retail app using your own B2C Commerce instance** and follow the terminal instructions.
- Or generate a Retail React App with a preset configuration, then change the SLAS client ID to your public or private client after generation:
  - Follow the steps in the [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.html).
  - Use a SLAS public or [private client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md).
  - Make sure the SLAS client used for Hybrid Auth includes the `sfcc.session_bridge` scope.

### Step 2: Enable `hybridAuthEnabled` in the `_app-config` Component

In `app/components/_app-config/index.jsx` (or `overrides/app/components/_app-config/index.jsx` if you use [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html)), find the `CommerceApiProvider` component and uncomment the `hybridAuthEnabled` prop:

```jsx
<CommerceApiProvider
    ...
    hybridAuthEnabled={true}
    ...
>
```

Do **not** set this prop for hybrid storefronts that still use Plugin SLAS. Enable it only for sites that use Hybrid Auth.

### Step 3: Update PWA Kit Routes

By default, PWA Kit uses the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) for navigation. When a shopper clicks a link made with a [React Router](https://reactrouter.com/home) component, it triggers a soft navigation to the component matching the path in `app/routes.jsx`. To link to a non-PWA Kit page (one powered by SFRA, for example), remove any route matching that URL pathname from `app/routes.jsx`.

1. If your PWA Kit project was generated with version 3.x of the Retail React App template using [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html), override the `overrides/app/routes.jsx` file to filter out links to non-PWA Kit pages using JavaScript. For an example override that filters out `/cart` and `/checkout`, see this [public gist](https://gist.github.com/shethj/c9d52aa1fe4188c431336438305f8e32).
2. Update the PWA catch-all route (`/*`) in `app/routes.jsx`. In this example, the PWA `<PageNotFound />` component is replaced with a redirect to the default origin:

```js
import {withRouter} from 'react-router-dom'
    ...
    {
        path: '*',
        component: withRouter((props) => {
            const {location} = props
            const urlParams = new URLSearchParams(location.search)

            useEffect(() => {
                const newURL = new URL(window.location)
                if (!urlParams.has('redirected')) {
                    newURL.searchParams.append('redirected', '1')
                    window.location.href = newURL
                }
            }, [window.location.href])
            if (urlParams.has('redirected')) {
                return <PageNotFound {...props} />
            }
            return null
        })
    }
```

### Step 4: Handle Cookie Responses in the Client Browser

As part of Hybrid Auth, SLAS token calls include the `dwsid` in the `Set-Cookie` response header. Make sure the `Set-Cookie` headers from SLAS API calls are respected and the cookies are set in the browser.

**note:** If you use the Commerce Cloud React SDK with the Composable Storefront, this cookie handling is done for you with PWA Kit v3.9 and later. If your site uses `commerce-sdk-react`, upgrade to `@salesforce/commerce-sdk-react@4.0.0` or later.

### Step 5: Enable Cookies on Managed Runtime

When Hybrid Auth is enabled, SLAS `/oauth2/token` requests contain a session-bridged `dwsid` using the `Set-Cookie` header in the response. In Managed Runtime, enable cookie passthrough:

1. Log in to [Managed Runtime Admin](https://runtime.commercecloud.com/).
2. Navigate to your project and environment.
3. Select **Environment Settings**.
4. Scroll to the **Advanced** section and select **Edit**.
5. Enable the switch next to **Cookies**.
6. Scroll back to the **Advanced** section and select **Update**.
7. Wait for your storefront bundle to redeploy.

### Step 6: Configure eCDN Origin Routing

Route top-of-funnel pages (home `/`, category `/category`, product `/product`) to your PWA Kit storefront on Managed Runtime (MRT), and route transactional routes (such as `/cart` and `/checkout`) to SFRA/SiteGenesis.

- To configure eCDN routing rules, see [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md).
- To compare route split patterns, see the [Hybrid Storefront Routing Matrix (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-routing-matrix.md).
- (Optional) Get analytics with [Einstein Activities for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/einstein-activities-for-phased-headless-rollouts.md).

## Set Up Hybrid on On-Demand Sandbox (ODS) Instances Using eCDN

**Applies to: PWA Kit**

On-demand sandbox (ODS) instances include an embedded CDN (eCDN), so configure hybrid routing on ODS the same way you do on a Primary Instance Group (PIG) instance—through the eCDN UI in Business Manager—rather than with the local hybrid proxy. This lets you validate hybrid behavior in a deployed environment that mirrors production routing.

1. Deploy your PWA Kit bundle to a Managed Runtime environment connected to the ODS instance.
2. Complete the [shared Hybrid Auth setup](#complete-the-shared-hybrid-auth-setup-first) and the PWA Kit configuration steps above (Steps 1–5).
3. Configure eCDN origin routing rules for the ODS zone using the Business Manager UI. Route top-of-funnel pages (home, category, product, search) to Managed Runtime, and keep transactional routes (such as `/cart` and `/checkout`) on SFRA/SiteGenesis. For the UI steps, see [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md#configure-routing-rules-in-the-business-manager-ui).
4. Verify routing and cookie/session behavior as described in [Verify Your Hybrid Auth Setup](#verify-your-hybrid-auth-setup).

**note:** Use eCDN—not the hybrid proxy—on ODS instances. Reserve the hybrid proxy for local development on `localhost`.

## Set Up Hybrid Locally for Local Development

**Applies to: PWA Kit**

For local development on `localhost`, eCDN isn't available, so use a reverse proxy instead. The PWA Kit **hybrid proxy** feature is available starting in PWA Kit v3.14 in the `pwa-kit-runtime` package.

Enable hybrid proxy for **local development only**. On PIG and ODS instances, use eCDN to direct requests to the PWA Kit Composable Storefront or SFRA/SiteGenesis store. Don't enable hybrid proxy on PIG or ODS instances: because hybrid proxy sets `localAllowCookies: true`, it can cause security issues on deployed instances.

Follow these steps to enable hybrid proxy locally.

1. Upgrade the `pwa-kit-runtime` package dependency to v3.14.0 or later.
2. Configure the `hybridProxy` value in your Composable Storefront `ssr.js` for a server-side reverse proxy:
   - `localAllowCookies: true`
   - `hybridProxy.enabled: true`
   - `hybridProxy.sfccOrigin: [your SFCC store]`
3. Update `default.js` to configure client-side routing:

   - Update `app.commerceAPI.parameters` to point to the correct Commerce API SIG instance.
   - Add `app.enableHybrid: true` so that you can toggle hybrid mode on and off.
   - Add a proxy config for the `dwrestatic` path:

   ```text
   ssrParameters.proxyConfigs: add
   {
     host: [your SFCC store],
     path: 'dwrestatic'
   }
   ```

4. In `app/components/_app-config/index.jsx`, uncomment `hybridAuthEnabled` (see [Step 2](#step-2-enable-hybridauthenabled-in-the-_app-config-component)). Don't set this flag for hybrid storefronts that still use Plugin SLAS.
5. Update `app/routes.jsx` to exclude routes from PWA Kit so that the matching pages render on SFRA/SiteGenesis. This example removes the `/cart` and `/checkout` routes from the PWA Kit store and uses the catch-all `*` route to trigger server-side rendering of the proxied SFRA/SiteGenesis cart and checkout pages. For reference, see this [public gist](https://gist.github.com/clavery/c0c8689ee852876cfc5b297985c4300e#file-routes-jsx-L116).

   ```js
   // Remove SFRA/SiteGenesis routes from PWA Kit
   const ecomRoutes = ['/cart', '/checkout', '*']

   const hybridRoutes = [
     ...routes.filter((route) => !ecomRoutes.includes(route.path)),
     {
       path: '*',
       component: withRouter((props) => {
         const config = getConfig()
         const {location} = props
         const urlParams = new URLSearchParams(location.search)
         const {site} = useMultiSite()
         const siteId = site && site.id ? site.id : config?.app?.defaultSite

         if (typeof window !== 'undefined') {
           useEffect(() => {
             const newURL = new URL(window.location)
             if (!urlParams.has('redirected')) {
               newURL.searchParams.append('redirected', '1')
               newURL.pathname = `/s/${siteId}/${window.location.pathname
                 .split('/')
                 .slice(2)
                 .join('/')}`
               window.location.replace(newURL)
             }
           }, [window.location.href])
         }

         if (urlParams.has('redirected')) {
           return <PageNotFound {...props} />
         }
         return null
       })
     }
   ]

   export default () => {
     const config = getConfig()
     // Use these routes only in hybrid mode; otherwise use the defaults.
     // This is driven by the config and environment variables.
     const routesToConfigure = config.app.enableHybrid ? hybridRoutes : routes
     return configureRoutes(routesToConfigure, config, {
       ignoredRoutes: ['/callback', '*']
     })
   }
   ```

For environment-specific differences (PIG, ODS, localhost), see [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-environment-matrix.md).

## Verify Your Hybrid Auth Setup

1. Go to your storefront using the vanity domain configured in eCDN.
2. Navigate to a page on SFRA/SiteGenesis.
3. Open browser **Developer Tools** and inspect cookies. Confirm these cookies are set:
   - `cc-nx-g_{Site_ID}`: Guest refresh token
   - `dwsid`: B2C Commerce session ID
   - `usid`: SLAS customer ID
   - `cc-at_{Site_ID}`: SLAS access token (appears only when the user lands on an SFRA page; not seen when navigating from a PWA Kit page to an SFRA page)
4. Navigate to any PWA Kit page and verify:
   - `cc-nx-g_{SiteID}` is unchanged.
   - `dwsid` is unchanged.
   - `usid_{SiteID}` is unchanged.
   - `cc-at_{SiteID}` is no longer present, because PWA Kit consumes it and moves the access token to `localStorage`. Confirm the `accesstoken{SiteID}` value in `localStorage` matches the original `cc-at_{SiteID}` cookie.
5. In Developer Tools, switch to the **Network** tab.
6. Add an item to the cart on PWA Kit.
7. Inspect the SCAPI **Add to Cart** request. In **Request Headers**, confirm the `sfdc_dwsid` header is set to the `dwsid` cookie value. This header is required to keep hybrid storefront behavior stable at production scale when traffic is distributed across multiple app servers. If you're not using PWA Kit, set this header from your headless application whenever the `dwsid` cookie is available.

**note:** You might observe a 302 redirect if a session has expired (while retaining a valid refresh token in the `cc-nx*` or `cc-nx-g*` cookies) or if a refresh token is invalid. This is expected. Make sure your implementation follows these redirects.

## Hybrid Auth Feature Support Matrix

The following table compares PWA Kit feature support for Plugin SLAS versus Hybrid Auth.

| Feature Name                           | Supported in PWA Kit w. Plugin SLAS | Supported in PWA Kit w. Hybrid Auth                                                                                                               | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| -------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SiteGenesis                            | N                                   | Y                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Third Party IDPs and Social Login      | N                                   | Y                                                                                                                                                 | <ul><li>Third-party IDP: Starting with B2C Commerce version 25.8, hybrid auth supports third-party IDP and Social Login, but you must perform all interactions with a third-party IDP using SLAS. Configure OAuth2 providers in [SLAS Admin](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html) instead of Business Manager and add a redirect URI in Hybrid Auth Settings.</li><li>Social Login: Starting with B2C Commerce version 25.8, you must perform all logins using SLAS.</li></ul>                                                                           |
| Passwordless Login                     | N                                   | N                                                                                                                                                 | Hybrid storefronts don't support passwordless login. See [Implement Passwordless Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/passwordless-login.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| SLAS Private Clients                   | Y                                   | Y                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| SLAS Public Clients                    | Y                                   | Y                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| SLAS Trusted System (TSOB)             | N                                   | Y                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Script API "Remember Me" functionality | N                                   | N/A <ul><li>The traditional remember me functionality enhanced with SLAS extended expiry times and is redundant when you migrate to HA.</li></ul> |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| PWA Kit Version 2.x                    | Y                                   | Y                                                                                                                                                 | <ul><li>To use hybrid auth, you need `salesforce/commerce-sdk-react` _v4.0.0_ or later.</li><li>`salesforce/commerce-sdk-react` _v3.4.0_ comes packaged with PWA Kit v2.10.</li><li>`salesforce/commerce-sdk-react` _v5.1.1_ comes packaged with PWA Kit v2.11.</li></ul>                                                                                                                                                                                                                                                                                                                                           |
| PWA Kit Version 3.x                    | Y                                   | Y                                                                                                                                                 | <ul><li>To use hybrid auth, you need `salesforce/commerce-sdk-react` _v4.0.0_ or later.</li><li>`salesforce/commerce-sdk-react` _v3.3.0_ comes packaged with PWA Kit 3.10.0.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Do Not Track (DNT)                     | N                                   | Y                                                                                                                                                 | You must perform specific steps to enable and synchronize DNT. See [Step 8: Enable or Disable Do-Not-Track Synchronization](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-8-optional-enable-or-disable-do-not-track-synchronization).                                                                                                                                                                                                                                                                                                                                                                  |
| Shopper Context                        | N                                   | Y                                                                                                                                                 | <ul><li>Salesforce recommends that you enable Shopper Context for Hybrid Authentication as it is the only way personalization data is made available for APIs. See the [Shopper Context documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guides/shopper-context-api.md).</li><li>Geolocation-based personalization must be synchronized between Shopper Context and SFRA/SiteGenesis. See [Step 7: Set Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-7-optional-set-shopper-context).</li><li>Note: The Script API for Shopper Context is available for geolocation-based personalization.</li></ul> |
| Controller exclusion                   | Y                                   | N                                                                                                                                                 | In Hybrid Auth, there is no need to exclude any controllers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Cookie setting customization           | Y, via customization                | N/A                                                                                                                                               | In Hybrid Auth, unlike Plugin SLAS, you no longer have access to the cookie object and can no longer override cookie settings.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Agent/Order On Behalf Of (OOBO)        | N                                   | Y                                                                                                                                                 | Starting with B2C Commerce version 26.1, Agent/OOBO is supported out of the box in Hybrid Auth with PWA Kit when using the Customer Service Center in Business Manager. If your site uses a third-party cartridge for Agent/OOBO, make sure that you perform testing in a local environment before deploying to your live site.                                                                                                                                                                                                                                                                                     |

## Related Guidance

- [Hybrid Authentication Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md)
- [Hybrid Storefront Routing Matrix (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-routing-matrix.md)
- [Hybrid Auth Implementation with PWA Kit v2.x](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-pwa-kit-v2.md)
- [Hybrid Storefront Basket Guidance](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-storefront-baskets.md#hybrid-storefront-best-practices-for-working-with-baskets)
- [Hybrid Auth Troubleshooting](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-troubleshooting.md)

<!-- document id=4f2e3a859649b2531c4ed2cce168a3a2347a568a278bf78e35cfec9921499998 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/phased-headless-rollouts.md -->

# Configure a Hybrid Storefront with Plugin SLAS

Phased rollouts of headless technologies are possible for users of the [Storefront Reference Architecture (SFRA)](https://developer.salesforce.com/docs/commerce/sfra/guide) and PWA Kit. For example, you can deploy a new experience for product pages using [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.md) and keep the checkout flow on SFRA until the next phase of your headless transition. This phased approach helps you get started sooner, expedites business outcomes, and minimizes potential disruption from a “big bang” style cutover to headless.

To create a seamless user experience, use session bridging and eCDN routing rules to enable PWA Kit to power one set of pages and SFRA to power another.

To learn more about using Einstein Activities in a phased headless context, see [Einstein Activities for Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/commerce-api/guides/einstein-activities-for-phased-headless-rollouts.md).

Although SiteGenesis is not officially supported, there is a [Site Genesis + Composable POC](https://github.com/SalesforceCommerceCloud/composable-hybrid-sitegenesis-poc) built by the community.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


**note:** - With B2C Commerce version 25.3, Hybrid Authentication (Hybrid Auth) replaces Plugin SLAS. For more information, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md).
- We highly recommend migrating to Hybrid Auth so that you can take advantage of the improved performance and streamlined workflow.
- The instructions in this guide describe how to combine PWA Kit and SFRA flows, and the same instructions can be adapted for SiteGenesis using this [proof of concept](https://github.com/SalesforceCommerceCloud/composable-hybrid-sitegenesis-poc). Please note that implementations using Sitegenesis with Composable Storefront aren't officially supported.

## Process Summary

When you implement a hybrid storefront, you must perform the following configuration for a complete and successful build and a seamless shopper experience. The following steps are executed in multiple infrastructure layers, including your SFRA build, Business Manager, PWA Kit, and your CDN layer:

The tasks involved in a hybrid implementation with Plugin SLAS include:

1. [Set Up SLAS for PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md#1-set-up-slas-for-pwa-kit) (Required).
2. Set Up [Session Bridging](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md#2-session-bridging) (Required).
3. Configure [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md#3-routing) (Required). See Also [CDN APIs for Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md).
4. [Install the Redirect Cartridge](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md#4-install-the-redirect-cartridge-recommended) (Recommended).
5. Make [Other Changes to PWA Kit Projects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md#5-other-changes-to-pwa-kit-projects) (Required).
6. [Set up Hybrid Locally ](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md#6-set-up-hybrid-locally-sig-instances) (Required).
7. Review SCAPI [Hybrid Storefront Basket Best Practices](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html) (Recommended).
8. Get analytics Using [Einstein Activities for Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/commerce-api/guides/einstein-activities-for-phased-headless-rollouts.md) (Optional).

## 1. Set Up SLAS for PWA Kit

The first step in creating a phased headless rollout is to set up your PWA Kit application to use Plugin SLAS (if you haven’t already). Follow the instructions in our [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md) guide. Plugin SLAS extends authentication for guest users and registered shoppers using the Shopper Login and API Access Service (SLAS).

When setting up SLAS, you'll want to decide whether you set up a SLAS public client or a SLAS private client as this will affect some of the setup steps that follow.
If you are setting up a SLAS private client, follow the steps in [Use A SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md) to get set up.

**note:** All PWA versions prior to PWA Kit 3.5 support only SLAS _public_ clients.

**important:** - Use Plugin_SLAS for hybrid deployments with the PWA Kit to ensure formal support. Custom headless web applications are possible but not formally supported. Consider using B2C Commerce APIs directly for specific use cases.
- Read all constraints and configuration instructions in the [Plugin SLAS README](https://github.com/SalesforceCommerceCloud/plugin_slas).

### Install the SLAS Cartridge

**important:** If your Plugin SLAS installation is on **version 7.0.0 or later** your PWA Kit project must be generated using or be fully upgraded to **version 2.7.1 or later** of the Retail React App template.

To enable a phased headless rollout with SFRA, you must install the Plugin SLAS cartridge. Complete installation instructions are provided in the [Plugin SLAS README](https://github.com/SalesforceCommerceCloud/plugin_slas) for the cartridge.

**tip:** In addition to session bridging, the Plugin SLAS cartridge allows you to implement other shopper-friendly features, such as 90-day user sessions and basket persistence.

### Plugin SLAS and PWA Kit Compatibility

Refer to the table to make sure you're using compatible versions of the Plugin SLAS cartridge and PWA Kit.
| **Plugin SLAS** | **PWA Kit** | **retail-react-app** | **commerce-sdk-react** | **Notable Changes** |
|:-----------------:|:-----------------:|:--------------------:|:----------------------:|:------------------------------------------------------------------------:|
| v7.4.0 or later | v3.8.0 or later | v5.0.0 or later | v3.1.0 or later | - Hybrid Stability upgrade & Remove OCAPI `/sessions` call from PWA Kit. |  
| v7.3.0 | v3.7.0 | v4.0.0 | v3.0.0 | - SLAS Private Client Support |
| v7.0.0 - v7.2.0 | v2.7.1 - v2.9.0 | N/A | N/A | - PWA Kit v2.x is not supported with Plugin SLAS v7.3.0 or later |

For more details about the notable features, see the Plugin SLAS Release Notes under the [Plugin SLAS Releases](https://github.com/SalesforceCommerceCloud/plugin_slas/releases).

**Important Considerations for SLAS Cartridge Users**

The Plugin SLAS cartridge makes multiple calls to various APIs, which can impact storefront performance. Before adding the cartridge to a production storefront, compare the performance of your storefront with and without the cartridge to decide if it’s right for you.

The cartridge also introduces a redirect under the following conditions:

- When a shopper logs in
- When a shopper’s session cookie has expired

Currently, the cartridge only replaces direct login to the B2C Commerce system where the credentials are stored within Salesforce.

When used with the [wishlists plugin](https://github.com/SalesforceCommerceCloud/plugin_wishlists), guest wishlists aren’t transferred on login to the registered user.

Before using the cartridge, review the [issues page](https://github.com/SalesforceCommerceCloud/plugin_slas/issues) on GitHub.

### Guidance for SiteGenesis Implementations

Because the Plugin SLAS cartridge is designed for SFRA, additional code must be written to use it with SiteGenesis. A SiteGenesis implementation can use code from the cartridge at various points in the shopper authentication and authorization flows.

Because the cartridge uses the [B2C Commerce Web Service Framework](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html) to handle SLAS API calls, a SiteGenesis implementation can make requests to the web services implemented by the cartridge. These web services include guest login, registered customer login, token refresh, logout, and merging the guest basket. The cartridge also implements a service to merge API sessions and storefront sessions.

A SiteGenesis implementation can also use a custom hook (`app.plugin.slas.login`) to implement login for guests and registered users with SLAS. Examine the custom code in the cartridge’s [onSession](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/LegacyDeveloperDocumentation.pdf) hook in `dw.system.request.onSession` to see how it replaces the Script API with SLAS for shopper login.

For a working example, see [Site Genesis + Composable POC](https://github.com/SalesforceCommerceCloud/composable-hybrid-sitegenesis-poc).

## 2. Session Bridging

Enabling shoppers to seamlessly navigate between pages powered by different storefront architectures requires using a technique called session bridging. Session bridging uses cookies to share shopper refresh tokens and session tokens across different systems.

The key to unlocking session bridging is SLAS, a new standards-based solution for authentication and authorization that can be accessed through HTTP requests. Shopper authentication with SLAS is based on OpenID Connect and authorization for B2C Commerce’s Shopper APIs is based on OAuth 2.

When a shopper browses a headless storefront, you use SLAS to request an access token and a refresh token and store them as cookies on the shopper’s browser. As the shopper transitions from an SFRA page to a PWA Kit page (or vice versa), the cookies with the access token and refresh token are sent along with the HTTP request and PWA Kit/SFRA use these to inherit the same session from the other.

For more session bridging information and examples, see the [Session Bridging Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guides/slas-session-bridge-overview.md).

### Session Bridging in Plugin SLAS

Plugin SLAS manages B2C Commerce sessions (associated with a `dwsid`) as well as SLAS sessions (associated with an `access_token`). Session bridging links `dwsid` and `access_token` to the same shopper session.

Plugin SLAS uses the SLAS Session Bridge (API: [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getSessionBridgeAccessToken)), which:

- Is used by Plugin SLAS for **New Guest Login** only
- Doesn’t generate a new `dwsid` after session-bridging hence the storefront doesn’t require a re-render and can be sent a 200 OK response
- For session bridging details and authorization with SCAPI, see:
  - [Session Bridge Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-session-bridge-overview.html)
  - [Session Bridge Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-session-bridge-auth.html)

### Modify PWA Kit to Use Cookies

To make session bridging possible with PWA Kit, you must modify the code in `commerce-api/auth.js` that handles API authorization to use cookies instead of local storage.

If your PWA Kit project was generated with **version 2.7.x** of the Retail React App template, you can uncomment [this line of code in auth.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/release-2.7.x/packages/template-retail-react-app/app/commerce-api/auth.js#L53-L56), to switch to `CookieStorage` for storing tokens. This is required for managing sessions between SFRA and PWA Kit sites.

You must also modify the code in `commerce-api/auth.js` that calls the session-bridge API after shopper login. To do so, you must uncomment [this line of code in auth.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/86230de07ba887e62209d1fa536b3a999f0e00e1/packages/template-retail-react-app/app/commerce-api/auth.js#L259).

To save you time, we’ve created an alternate version of the file with all the changes in place and made it available on GitHub through [a public gist](https://gist.github.com/shethj/0e5b069aa5b5779351c826d65dcd2de3).

If your PWA Kit project was generated with **version 3.0.0 or later** of the Retail React App template, the previous changes are enabled by default and no further code changes are required.

The authorization flow starts with the refresh token. If the refresh token cookie is available, the PWA Kit app exchanges the refresh token for an access token. Otherwise, the app starts an authorization code grant flow, as defined by the OAuth 2.1 standard. It also follows the proof key for code exchange (PKCE) flow.

When SLAS grants the new access token and the new refresh token, the app stores them in cookies. Then the app makes a POST request to OCAPI’s create session endpoint (`/session`). This endpoint creates a session that is used by SFRA. The app stores the session token in a cookie.

Cookies created by the PWA Kit app:

- `cc-nx-g` - SLAS guest shopper refresh token
- `cc-nx` - SLAS registered shopper refresh token
- `token` - SLAS access token
- `dwsid` - Demandware session id

### Understand Session Management between SFRA and PWA Kit

#### OCAPI Session-Bridge (`/sessions`) Call in PWA Kit

The call to OCAPI session-bridge after shopper login on PWA Kit pages is required to notify the SFRA pages whenever the authentication state of the shopper changes on PWA Kit pages. Whenever the shopper's auth state changes, PWA Kit sends the new `access_token` in `/sessions` call for session bridging and receives a new `dwsid`. The `dwsid` cookie value is updated with the one received in the `/sessions` response.

#### Access Token Handling in PWA Kit

**PWA Kit v3.4.0 and earlier**
PWA Kit maintains a copy of the refresh token in the `LocalStorage`, which is compared to the refresh token key and value stored in `CookieStorage` before each request. If the tokens differ, PWA Kit invalidates the current session and triggers the authorization flow again to keep sessions in sync with SFRA.

**Changes in PWA Kit v3.5.0 ([commerce-sdk-react@1.4.0](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/v3.5.0))**\
We've updated the logic used to invalidate PWA Kit sessions based on shopper's auth state in SFRA in a phased launch setup. SFRA now stores the SLAS access*token in a cookie with key `cc-at*{siteId}`. When a shopper navigates from SFRA to PWA Kit this cookie is shared with PWA Kit. This cookie can either hold the actual access_token value from SLAS if a valid access token is available. If not, the value of the cookie is set to`refresh`. If a valid access_token is seen, PWA Kit replaces the current value of access_token with the value of`cc-at*{siteId}`cookie. If`cc-at*{siteId}`is set to`refresh`, PWA Kit triggers a refresh_token login flow to get a new access_token.

**note:** You may notice multiple `cc-at_{siteId}` cookies like `cc-at_RefArch` and `cc-at_RefArch_2`. If the access_token is large it is broken down into multiple chunks and is concatenated back together when the access_token is being read by PWA Kit.

See [`getAccessToken()`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/8cdef3dada4eb5d9809596847754ecf6607c6dad/packages/commerce-sdk-react/src/auth/index.ts#L305-L348) for implementation details.

#### `dwsid` and `onSession` Hook Behavior

B2C Commerce looks at the clickstream of the session associated with the `dwsid`. An empty clickstream indicates a new session and `onSession` is triggered.
A new or a changed value of the `dwsid` cookie does not directly imply the session is new.

In a phased launch setup, PWA Kit calls `/sessions` OCAPI endpoint to bridge B2C Commerce and SLAS sessions whenever the login state of the shopper changes to notify SFRA of the login state change. The `/sessions` endpoint returns a new value for `dwsid` which is associated with the newly bridged session and hence has an empty clickstream. This triggers `onSession` when a shopper navigates to the SFRA site.

If a shopper repeatedly hops between PWA Kit and SFRA sites, you may notice the `dwsid` value changes but it may still be associated with an ongoing B2C Commerce session or may have a non-empty clickstream. In this situation, `onSession` hook is not triggered.

## 3. Routing

To ensure a seamless user experience during a phased rollout, use a content delivery network (CDN) to route traffic to two different origins: the Managed Runtime (MRT) environment and your B2C Commerce instance.

Imagine the following scenario:

You have an existing SFRA storefront running on `www.mystorefront.com`. You know the benefits of headless architecture and want to leverage PWA Kit to deliver performant and engaging experiences. At the same time, you want to minimize risk to the schedule, so you choose a phased approach to rolling out your PWA Kit storefront.

You configure the CDN to send page requests at the top of the funnel to PWA Kit: home page (`/`), the category listing page (`/category`), and the product details page (`/product`). These PWA Kit pages are deployed to a Managed Runtime environment running on `mystorefront.mobify-storefront.com`. When the shopper decides to make a purchase, the CDN redirects the shopper to the existing SFRA checkout page running on `www.mystorefront.com`.

For more information about routing traffic to MRT, see:

- [CDN APIs for Phased Headless Rollout](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md)
- [TLS Certificates](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md#3.-tls-certificates)
- [DNS CNAME](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md#4.-dns-cname)
- [Configure Your Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md#5.-configure-your-environment)

### Configure CDN Rules

To handle traffic routing, you can choose the embedded CDN (eCDN) solution from Salesforce (and powered by Cloudflare) or choose a CDN from a different vendor.

### PWA Kit Routes

To help design your origin rules, gather a comprehensive list of routes for PWA Kit pages. For a PWA Kit project based on the Retail React App template, the routes are listed in `app/routes.jsx`. Because the server-side rendering system for PWA Kit uses internal routes for proxies and static assets, you must also include `/mobify/*` in the routing rules.

For our example scenario, the following routes must be configured in your CDN:

```
/
/category/*
/product/*
...(all PWA routes)

/mobify/*
/callback
/worker.js
```

Build an origin rule that includes all the PWA Kit routes on your list to forward the request to the Managed Runtime environment (`mystorefront.mobify-storefront.com` in our example scenario).

The following diagram shows the eCDN configuration for the example scenario that we described earlier:

![Associated diagram](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/phased-headless-cdn-routing.png '{"class": "image-framed image-lg"}')

### eCDN Routing Overview

To use eCDN to route traffic to Managed Runtime, use the Commerce API endpoint [`createMrtRules`](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createMrtRules). You can also [Configure MRT Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-mrt-routing-bm.md).

The API supports routing traffic to Managed Runtime using Cloudflare [Rule Expressions](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/). It supports a subset of the [available fields](https://developers.cloudflare.com/ruleset-engine/rules-language/fields/) in the Rules language. The following fields are supported:

- `http.host` to match with the host name
- `http.request.uri.path` to match against the request path
- `http.request.uri` to match against both the request path and query string
- `http.cookie` to match against cookies

You can request 100 individual rules per instance on proxy zones and 100 individual rules in total shared between dev/prod instances on legacy zones.

<!-- REVIEW(SME/eCDN + Hybrid Auth team): This bullet previously stated that eCDN is "not available for sandbox or on-demand sandbox (ODS) instances." That contradicts the Hybrid Auth guidance in hybrid-auth.md ("Set Up Hybrid on On-Demand Sandbox (ODS) Instances Using eCDN"), sfnext-hybrid-ods.md, and hybrid-auth-environment-matrix.md, which all state that ODS instances include an eCDN for hybrid routing configured through the Business Manager UI. Reconciled to point ODS users to eCDN. Please confirm the exact boundary: does ODS eCDN apply only to hybrid routing configured in the Business Manager eCDN UI, or also to the createMrtRules API described above? If the API path still excludes ODS, refine this wording accordingly. -->

- The eCDN is available for production and development (PIG) instances. On-demand sandbox (ODS) instances also include an eCDN for hybrid routing, configured through the Business Manager eCDN UI. See [Set Up Hybrid on On-Demand Sandbox (ODS) Instances Using eCDN](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md#set-up-hybrid-on-on-demand-sandbox-ods-instances-using-ecdn).
- Staging instances must be onboarded to eCDN using the eCDN API. For more information, see [Configure eCDN for Staging](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_ecdn_for_staging.htm) on the B2C Commerce Infocenter and [this article](https://www.rhino-inquisitor.com/how-to-set-up-the-ecdn-for-staging-in-salesforce-b2c-commerce-cloud/) from the Rhino Inquisitor blog.
- The eCDN doesn’t support routing based on geolocation.

For detailed eCDN implementation details, see [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html).

## 4. Install the Redirect Cartridge (Recommended)

By default, the Retail React App template for PWA Kit projects has a different URL routing pattern than SFRA. For example, the URL path for a product detail page in the Retail React App is `/products/{productId}`. With SFRA, the pattern is `/{categoryId}/{productId}`.

We recommend that you change the routing patterns in your PWA Kit storefront to match your SFRA site. If you can't match the URL patterns for a specific page (like the product listing page when the category ID isn’t available in the URL), use the [Redirect Cartridge](https://github.com/SalesforceCommerceCloud/plugin_redirect) to set up redirects that close the gap. Complete installation instructions are provided in the [README](https://github.com/SalesforceCommerceCloud/plugin_redirect) for the cartridge.

## 5. Other Changes to PWA Kit Projects

To complete the setup process for a phased headless rollout, you must make a few more changes to your PWA Kit project.

By default, PWA Kit uses the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) for navigation. When a shopper clicks a link made with React Router’s `<Link>` component, it triggers a soft navigation to the component matching the path in the route object defined in `app/routes.jsx`. To link to a non-PWA Kit page (one powered by SFRA, for example), you must remove any route matching the URL pathname from `app/routes.jsx`.

For example, if your PWA Kit project was generated with **version 2.7.x** or **version 3.x** of the Retail React App template **without** using extensibility: remove checkout from the routes array.
![Remove-checkout-route](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/phased-headless-remove-checkout.png '{"class": "image-framed image-xl"}')

If your PWA Kit project was generated with **version 3.x** of the Retail React App template using extensibility, you can override the `overrides/app/routes.jsx` file to filter out links to non-PWA Kit pages using javascript.
We’ve created an example override of the `overrides/app/routes.jsx` file with all the changes in place to filter out `/cart` and `/checkout` routes and made it available on GitHub through [a public gist](https://gist.github.com/shethj/c9d52aa1fe4188c431336438305f8e32).

Lastly, update the PWA catch-all route (`/*`) in `app/routes.jsx`. Replace the PWA `<PageNotFound />` component with a redirect to the default origin.

```js
import {withRouter} from 'react-router-dom'
...
{
    path: '*',
    component: withRouter((props) => {
        const {location} = props
        const urlParams = new URLSearchParams(location.search)

        useEffect(() => {
            const newURL = new URL(window.location)
            if (!urlParams.has('redirected')) {
                newURL.searchParams.append('redirected', '1')
                window.location.href = newURL
            }

        }, [window.location.href])
        if (urlParams.has('redirected')) {
            return <PageNotFound {...props} />
        }
        return null
    })
}
```

**important:** Notice the dependency on `window.location.href` in the `useEffect` hook for handling the catch-all (`*`) route. We recommend restricting the `useEffect` to run only when the page URL changes. This restriction prevents duplicate concurrent requests to SFRA pages in cases where a shopper tries to switch between PWA Kit and SFRA sites as it might result in session inconsistencies.

## 6. Set Up Hybrid Locally (SIG Instances)

We highly recommend testing your hybrid setup in a local environment. For local development on `localhost`, eCDN isn't available, so use your own reverse-proxy or CDN to split traffic between PWA Kit and SFRA/SiteGenesis.

For deployed on-demand sandbox (ODS) instances, don't use a reverse proxy—use eCDN instead, the same way you do on production. See [Set Up Hybrid on On-Demand Sandbox (ODS) Instances Using eCDN](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md#set-up-hybrid-on-on-demand-sandbox-ods-instances-using-ecdn).

We have created a sample Node.js app that can be used to develop and test hybrid deployment shopper flows across PWA Kit and SFRA/SiteGenesis.
Setup, configuration, and testing instructions for setting up reverse-proxy are mentioned in the [README](https://github.com/SalesforceCommerceCloud/composable-hybrid-dev-server) for the repo.

This demo video shows the steps to set up phased rollouts on SIG instances.

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/TNn6aYo7CRNQ8BXmRyYoNE" title="Phased Rollouts on SIG" type="vidyard"}

### Configure On-Demand Sandbox to Use Alias

You can configure your ODS to use an alias's configuration that is similar to your production configuration. This can help to keep your local and production setups identical. For instance by configuring your sandbox such that your hybrid site is available at the `/` URI ensures that URLs sent by pwa-kit don’t need to be translated to include the site ID. This is usually how a production site is configured.

To enable aliases in Business Manager, follow instructions in this module for [Salesforce B2C Commerce Hostname Aliases](https://trailhead.salesforce.com/content/learn/modules/b2c-hostname-aliases) on Trailhead.

### Configure PWA Kit Routes to Prefix Outgoing URLs (Optional)

You can configure your PWA Kit routes configuration to prefix all outgoing URLs (for example, those intended for SFRA) to include the `/s/SiteID` prefix. This ensures that your instance receives controller URLs in a manner normally used on sandboxes without needing to explicitly configure hostname aliases. Note that this may not be appropriate for production configuration so you may want to have a different catch-all route for production vs sandbox deployments.

To configure route prefixes, update the PWA catch-all route (`/*`) in `app/routes.jsx` or `overrides/app/routes.jsx`.

```js
import {withRouter} from 'react-router-dom'
// extensible
import useMultiSite from '@salesforce/retail-react-app/app/hooks/use-multi-site';
// non-extensible
import useMultiSite from './hooks/use-multi-site';

const DEFAULT_SITE_ID = 'RefArch'
...
 {
    path: '*',
    component: withRouter((props) => {
        const {location} = props
        const urlParams = new URLSearchParams(location.search)
        const {site} = useMultiSite()
        const siteId = site && site.id ? site.id : DEFAULT_SITE_ID
        useEffect(() => {
            const newURL = new URL(window.location)
            if (!urlParams.has('redirected')) {
                newURL.searchParams.append('redirected', '1')
                newURL.pathname = `/s/${siteId}/${window.location.pathname
                    .split('/')
                    .slice(2)
                    .join('/')}`
                window.location.replace(newURL)
            }
        }, [window.location.href])
        if (urlParams.has('redirected')) {
            return <PageNotFound {...props} />
        }
        return null
    })
}
```

## See Also

- [Hybrid Implementation Guidance](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html)
- [Hybrid Stability Upgrade for PWA Kit Version 3.8.0](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-upgrade-v3.x.md)
- [Hybrid Stability Upgrade for PWA Kit Version 2.x](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-upgrade-v2.x.md)
- [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-authentication.html)

<!-- document id=f32af66d115f7f78d4e3cc03d6e969a235e0725f26b35c39fdfd4f69b442cb99 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-salesforce-idp.md -->

# Configure a Salesforce Connected Application to Work with SLAS

Learn how the Shopper Login and API Access Service (SLAS) can work with Salesforce as an identity provider (IDP) using OpenID Connect.

## Create the Connected Application

1. Log in to your Salesforce org.
2. From Setup, in the Quick Find box, enter `App`, and then select **App Manager**.
3. Click **New Connected App**.
4. Enter the connected app’s name. The name must be unique within the org.
5. Enter the API name used when referring to your app from a program. It defaults to a version of the name without spaces. Only letters, numbers, and underscores are allowed. If the original app name contains any other characters, edit the default name.
6. Enter a contact email.
7. Click **Enable OAuth Settings**.
8. Enter the **Callback URL**. Example URL: `https://$SHORTCODE.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/salesforce`
9. Add the following OAuth Scopes to the list:
   1. **Access the identity URL service (id, profile, email, address, phone)**
   2. **Access unique user identifiers (openid)**
   3. **Full access (full)**
   4. **Manage user data via Web browsers (web)**
   5. **Perform requests at any time (refresh_token, offline_access)**
10. Click **Save**.
11. Click **Continue**.
12. Wait while the connected app is deployed.
13. For Consumer Secret, click **Manage Consumer Details**.
14. Copy the **Consumer Key** and **Consumer Secret** and save them in a password manager or other secure location.

## Configure SLAS for Salesforce IDP

Now create an IDP in SLAS for the Salesforce Connected app. Have the **Consumer Key** and **Consumer Secret** that you copied earlier handy.

Using the SLAS Admin UI or the SLAS Admin API, create a Salesforce IDP in SLAS. For more information about the API, see [Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md) and the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary) reference.

Example request:

```bash
curl "https://$SHORTCODE.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/$TENANT/idps/salesforce" \
  --request 'PUT' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "salesforce",
    "clientId": "'$CONNECTED_APP_CONSUMER_ID'",
    "clientSecret": "'$CONNECTED_APP_CONSUMER_SECRET'",
    "authUrl": "https://login.salesforce.com/services/oauth2/authorize",
    "tokenUrl": "https://login.salesforce.com/services/oauth2/token",
    "tokenInfoUrl": "https://login.salesforce.com/services/oauth2/introspect",
    "userInfoUrl": "https://login.salesforce.com/services/oauth2/userinfo",
    "redirectUrl": "https://"'$SHORTCODE'".api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/salesforce",
    "scopes": ["openid", "email", "profile"],
    "preferenceValue": false
}'
```

<!-- document id=1f527876e815e4cd988f4b577d4051c95b8f850160b1d268e7c719737129a5f7 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/configure-boris-order-controller.md -->

# Configure a Separate Order Controller for Buy Online Return In-Store (BORIS) Orders

Set up an external controller for Point of Sale BORIS orders. You can still use Salesforce order management for all in-store orders. You can have a separate ecommerce controller and still process BORIS returns as receipted and referenced.

BORIS is an order fulfillment method that allows a customer to purchase a product online and have it shipped to their home. If the customer is unsatisfied with their purchase, they can return it in-store.

To use Salesforce as the order controller, see [Process BORIS Returns with Salesforce Order Management (SFOM) Connector](https://help.salesforce.com/s/articleView?id=commerce.rt_pos_returns_process_boris_sfom.htm&type=5) in _Salesforce Help_.

**important:** Point of Sale enforces a check that prevents orders from being returned unless they have a status of Completed, Exchanged, Partially Exchanged, Fulfilled, or Partially Refunded. Orders with a status of, for example, Shipped can't be returned.

1.  To configure an external order controller, set up Point of Sale [Order SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/order-spi).

    1.  In CMS, go to **Integrations** | **Customer Connecters**.

    2.  Click **Create**.

    3.  For Connecter Type, select **SPI**.

    4.  For Endpoint Name, select **BORIS_GET_ORDER_DETAIL**.

    5.  Configure the rest of the fields for the SPI. See [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

    6.  Save your changes.

2.  To use the latest order search capabilities, enable enhanced search functionality.

    1.  In CMS, go to **Store Management** | **Store Settings** | **System**.

    2.  Expand **Rollout**.

    3.  Turn on Use new order search service (useOrderSearchV2).

<!-- document id=93cf12b491f18c2ce8e2df81f371457df7058a8b2a17160cae3bfe502dbfc5f1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-configuring-browse-on-behalf-of.md -->

# Configure a Storefront Hostname

Configure a custom storefront URL that lets Customer Service Center open the storefront and 'browse on behalf of' the customer. The Storefront host name is instance-specific.

1.  Assign a unique domain (host name) for Customer Service Center. It must be different than the Business Management instance URL but must resolve to the same IP address as the Business Manager instance.

2.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites** > **Business Manager**.

3.  To add the domain name to the allowed host names list, click the **Hostnames** tab, add the unique domain name host name allowlist, and then click **Apply**. For example, you could enter 'sitegenesis.co'.

    **note:** You also must edit the /etc/hosts file to point to this domain in Business Manager.

4.  To set the Storefront Hostname as the domain name, Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Site Preferences** > **Customer Service Center** and add the domain name, for example, 'sitegenesis.co', in the Storefront Hostname field.

5.  To create a host name alias for your custom URL, Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Site URLs** > **Aliases**.

    - A host name alias is required to create short, meaningful URLs for external search engines to index. Assign at least one host name alias that is the current host name on which the instance is running.

6.  On the Alias page, set the host name alias for the Customer Service Center site. For example, sitegenesis.co.

    - The Storefront button is enabled in Customer Service Center. When you click **Storefront**, a new tab opens with the customer as the logged-in user and doesn't log out the user from a Business Manager or Customer Service Center session.

<!-- document id=1d225a285dd6af8829c9c051e69d215a973e1493df91d1c77897b0cec7499604 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-address-autocomplete.md -->

# Configure Address Autocomplete for Storefront Next

Address autocomplete streamlines checkout in Storefront Next for B2C Commerce. During checkout, shoppers can enter the first three characters of their shipping or billing address to instantly receive Google-powered recommendations. When a shopper selects an address from the list of recommendations, Google completes the remaining fields.

![Checkout by using address autocomplete.](https://developer.salesforce.com/docs/media/sfnext/sfnext-address-autocomplete.png '{"class": "image-xl"}')

On production instances, address autocomplete uses a Salesforce-provided platform API Key by default, so no additional API Key setup is required.

On non-production environments, such as on-demand sandboxes (ODS), development, and staging instances, you must set up and use your own API Key. Set up your own Google Cloud Platform (GCP) project and billing, and your own API Key for the Google Maps Platform. Then, input the API Key as a new `PUBLIC__app__features__googleCloudAPI__apiKey` environment variable in your Managed Runtime (MRT) project. See [Getting started with Google Maps Platform](https://developers.google.com/maps/get-started#create-project) and [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html). You can also configure a custom API Key on production instances if you don't want to use the Salesforce-provided platform API Key.

1. Set up Storefront Next.

   To create a storefront with a GitHub repository, see [Create a Storefront in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md). To create a storefront with local code, see [Create a Storefront in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md).

2. (Required only for production instances) To allow the Google API key to become available in Storefront Next, update the hostnames in your alias file.

   a. In Business Manager, click App Launcher, and then select **Merchant Tools** | **Site** | **SEO** | **Aliases**.

   b. Specify your hostnames in the alias file, and then save your changes.

   **important:** If you’ve already specified your hostnames in the alias file, save the file again for the Google API key to become available.

   See [Hostname Aliases](https://help.salesforce.com/s/articleView?language=en_US&id=cc.b2c_hostname_aliases.htm), [Configure a Hostname Alias](https://help.salesforce.com/s/articleView?language=en_US&id=cc.b2c_configuring_hostname_alias.htm), and [Configure MRT Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-mrt-routing-bm.html).

<!-- document id=c65c0146f368ad24d11822fddf593bca0462082357dea4447a5b438fbcf7f22a url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/address-autocomplete.md -->

# Configure Address Autocomplete for Your B2C Commerce PWA Kit Storefronts

Address autocomplete streamlines checkout in your B2C Commerce Progressive Web App (PWA) Kit storefronts on First Party data centers. During checkout, shoppers can enter the first three characters of their shipping or billing address to instantly receive Google-powered recommendations. When a shopper selects an address from the list of recommendations, Google completes the remaining fields.

![Address autocomplete shipping and billing address](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa_address_autocomplete.png '{"class": "image-xl"}')

On production instances, address autocomplete uses a Salesforce-provided platform API Key by default, so no additional API Key setup is required.

On non-production environments, such as on-demand sandboxes (ODS), development, and staging instances, you must set up and use your own API Key. Set up your own Google Cloud Platform (GCP) project and billing, and your own API Key for the Google Maps Platform. Then, input the API Key as a new `GOOGLE_CLOUD_API_KEY` environment variable in your Managed Runtime (MRT) project. See [Getting started with Google Maps Platform](https://developers.google.com/maps/get-started#create-project) and [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html). You can also configure a custom API Key on production instances if you don't want to use the Salesforce-provided platform API Key.

1. If your PWA Kit isn’t version 3.15 or later, [Upgrade to v3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.html).
2. (Required only for production instances) To allow the Google API key to become available in your PWA Kit storefront, update the hostnames in your alias file.

   a. In Business Manager, click App Launcher, and then select **Merchant Tools** | **Site** | **SEO** | **Aliases**.

   b. Specify your hostnames in the alias file and save your changes.

   **important:** If you’ve already specified your hostnames in the alias file, save the file again for the Google API key to become available.

   See [Hostname Aliases](https://www.google.com/search?q=https://help.salesforce.com/s/articleView%3Fid%3Dcc.b2c_hostname_aliases.htm%26type%3D5), [Configure a Hostname Alias](https://help.salesforce.com/s/articleView?id=cc.b2c_configuring_hostname_alias.htm&type=5), and [Configure MRT Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-mrt-routing-bm.html).

3. Add the `sfcc.shopper-configurations` security scope to the Shopper Configurations API for your PWA Kit SLAS client.

   The [Shopper Configuration](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-configurations?meta=Summary) API retrieves the configuration that PWA Kit uses to enable address autocomplete. See [Authorization for Shopper APIs](https://www.google.com/search?q=https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html%23slas-admin-ui-create-a-slas-client) and [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

<!-- document id=0ac89107d9e25ad1c3cf46ba454454bdbb5c080ca908d58c5df3490fead8d8b0 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-recommendations/configure-and-test-recommenders.md -->

# Configure and Test Recommenders

When using the Einstein Product Recommendations API, configure the recommenders you want to use first, and then test the output of those recommenders.

Configuring recommenders for the API is the same as creating them for your storefront. For more information on where to place recommenders and how to select strategies, see [Recommenders](https://help.salesforce.com/s/articleView?id=cc.b2c_recommenders.htm&type=5) and [Strategies](https://help.salesforce.com/s/articleView?id=cc.b2c_recommender_strategies.htm&type=5) in the Salesforce B2C Commerce Infocenter.

For a step-by-step tutorial on how to set up and configure recommenders, you can view the visit [Configuring a Recommender for Product Recommendations](https://help.salesforce.com/s/articleView?id=cc.b2c_recommender_config_product_recommendation.htm&type=5) in the Salesforce B2C Commerce Infocenter.

## Usage Examples

These high-level examples can help you start creating and placing recommenders that you can use to test the Einstein Recommendations API.

- **Homepage** - Consider recommending best sellers or the most popular products from the whole catalog. To do that, select a _Products in All Categories_ recommender, and select "Recent top sellers" or "Recent most viewed" as the primary strategy.
- **Product Detail Page** - To recommend products based on the product currently being viewed, consider a _Product to Product_ recommender. To show products that a shopper may also like, select "Customers who viewed also viewed" as the primary strategy for this recommender. To show products that others also bought, select "Customers who bought also bought" as the primary strategy for this recommender. To recommend complementary items for apparel sets, consider _Complete the Set_ recommender.
- **Category Grid Page** - To recommend products based on the category currently being viewed, consider the _Products in a Category_ recommender. To show featured products in this category, select "Recent top sellers" or "Recent most viewed" as the primary strategy.
- **Cart** - To capture upsell opportunities on an empty cart, consider the _Recently Viewed_ or _Products in All Categories_ recommenders, which require no anchor. Because these recommenders don't use the cart's contents, their recommendations are the same regardless of what's in the cart. When the cart contains products, configure the cart page to take in those products as anchors and use the _Product to Product_ or _Complete the Set_ recommender for personalized upsell.
- **404 or No Search Result Page** - Consider showing shoppers featured products by using the _Products in All Categories_ recommender. Or remind shoppers of recently visited products by using the _Recently Viewed_ recommender.

## Test Getting Recommendations

To test getting recommendations, get a list of available recommenders for your site first, and then test the recommendation results generated by the recommender you choose.

1. To get a list of available recommenders, use the [`getRecommenders` endpoint](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=getRecommenders).
2. Make sure that you have one or more of the available recommenders set up in [Einstein Configurator](https://configurator.cquotient.com).
3. From the list of recommenders, choose one and test the generated product recommendations provided using the [`getRecommendations` endpoint](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=getRecommendations).

<!-- document id=fdfa497860764bb7968e85cd07579c1f2f5b8cb396de6886bdbc50fb0841afab url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-one-click-checkout.md -->

# Configure Checkout for Storefront Next

Streamline the checkout experience for shoppers in Storefront Next for B2C Commerce. When a first-time shopper checks out, they can save their checkout information for future use. If the shopper selects Save for Future Use, a one-time password (OTP) window appears where they can enter the code sent to their email address. After the shopper verifies their email address, the system creates an account for them with your store and saves their shipping and payment information for future use.

![Create an account for faster checkout.](https://developer.salesforce.com/docs/media/sfnext/sfnext-one-click-checkout.png '{"class": "image-xl"}')

If a registered shopper returns to make another purchase, the shopper only has to enter their email address and a verification code to check out. B2C Commerce automatically fills in the shopper’s default or first saved shipping address and payment information.

Shoppers always have the option to check out as a guest. Additionally, shoppers can log into their account to view their saved shipping and payment information.

Prerequisites:

- Set up Storefront Next. 

   To create a storefront with a GitHub repository, see [Create a Storefront in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md). To create a storefront with local code, see [Create a Storefront in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md).

- Create a SLAS private client.

   See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html?q=passwordless#configure-a-slas-private-client).

- Set up Passwordless Login for Storefront Next. 

   See [Passwordless Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passwordless-login.md).

1. To allow OTP-based logins, enable email verification.
  
   a. In Business Manager, click App Launcher, and then select **Merchant Tools** | **Site** | **Site Preferences** | **Storefront Login Preferences**. 

   b. Turn on Enable Email Verification.  

   c. Click **Apply**.

   ![Create an account for faster checkout.](https://developer.salesforce.com/docs/media/sfnext/sfnext-checkout-email-verification.png '{"class": "image-xl"}')

   See [OTP-Based Email Verification with SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-otp-email-verification.html). 

2. To protect passwordless login and account registration from bots, in `.env`, configure   Turnstile bot protection. 

   a. Enable Turnstile and map your Cloudflare site key to your domain. 

      ```
      PUBLIC__app__security__turnstile__enabled=true
      PUBLIC__app__security__turnstile__sites={"production":[{"siteKey":"0x4AAAAAAA...","domains":["www.mystore.com"]}]}
      ```

   b. To validate the challenge token against Cloudflare’s Siteverify API before processing the request, enable server-side verification. 

      ```
      TURNSTILE_VERIFICATION_ENABLED=true
      TURNSTILE_SECRET_KEYS={"0x4AAAAAAA...":"0x4AAAAAAB..."}
      ```

      See [eCDN Turnstile](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-turnstile.html).

<!-- document id=f675eb977b162595027393dd2787b1421fc581b070a11e42f2de3baa1054ef23 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-private-key-jwt.md -->

# Configure Client Authentication with Private Key JWT

OpenID Connect (OIDC) `private_key_jwt` client authentication is a secure method for the Salesforce Login API and Access Service (SLAS) to authenticate itself to a 3rd party identity provider (IDP). This method is a more secure alternative to using a shared secret and is a common choice in environments that require high-security authentication.

## Private Key JWT

Instead of sending a shared secret, SLAS uses a JSON Web Token (JWT) that's signed with its private key. The third-party IDP then verifies the signature of this JWT using a corresponding public key that SLAS has registered with the IDP. This process ensures strong authentication by leveraging asymmetric cryptography, which helps prevent shared secret risks and reduces the chances of leaks or breaches.

![Private Key JWT authentication flow](https://developer.salesforce.com/docs/media/commerce-api/slas-private-key-jwt-flow.png '{"class": "image-md"}')

### Private Key JWT Assertion

The JWT assertion crafted by SLAS includes several required claims:

- `iss` (Issuer) and `sub` (Subject): Both contain the third-party IDP's `client_id`.
- `aud` (Audience): The token endpoint of the third-party IDP.
- `exp` (Expiration Time): The JWT's expiration time.
- `iat` (Issued at Time): The timestamp when the JWT was created.
- `jti` (JWT Id): A unique identifier for the token to prevent replay attacks.

## 1. Configure Client IDP for Private Key JWT

First, configure your client IDP for `private_key_jwt` authentication. For example, if you use Okta, follow these steps.

1. Create an Okta application that uses Public Key / Private Key client authentication.
2. Make sure that your Okta application public key configuration is set to save keys in Okta.

## 2. Configure with SLAS Admin User Interface

To configure `private_key_jwt` authentication, use the SLAS Admin UI to create a key pair and get a public key for the 3rd party IDP.

1. Go to the **IDPs** tab.
2. Select **Add Idp**.
3. Add all applicable information.
   1. Enter your URLs and scopes. To autofill these fields, enter you 3rd party IDP’s OIDC Well-Known URL. For example, https://accounts.google.com/.well-known/openid-configuration. Then click **Search and Populate URLs**.
   2. Select a tenant from the dropdown menu.
   3. In the **Idp name** field, enter the name of your 3rd party IDP.
   4. In the **Secret** field, enter NA. A secret isn’t needed, but SLAS requires a placeholder value.
   5. In the **Idp Client Id** field, enter the client ID from your 3rd party IDP.
   6. In the **Client Type** field, select `client_private_jwt` from the dropdown menu.
   7. In the **Key Algorithm** field, select a key pair algorithm from the dropdown menu. If unspecified, the default value is `RS256`.
   8. In the **Login Merge Claims** field, enter space separated IDP supported userInfo claims.
4. Click **Add** to save your configuration. SLAS now creates the public and private key pair using the selected key algorithm.
5. Copy the resulting public key (Public Json Web Key) and register it in your 3rd party IDP for use in validating the JWT that is created and sent by SLAS in the /token request.
6. On your authenticate call to SLAS, make sure that the hint query parameter matches the new IDP. See [Authorize customer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer).

## Rotate the JWT Keys

To rotate the JWT key pair for an IDP, use the SLAS Admin UI to switch the client type to `client_secret` and then back to `client_private_jwt`. This action rotates the key pair and creates a new public key.

1. Go to the Idps tab.
2. Click **Edit** for the IDP that you want to rotate keys for.
   1. In the **Client Type** field, select `client_secret` from the dropdown menu.
   2. Click **Save**.
3. Click **Edit** again for the same IDP.
   1. In the **Client Type** field, select `client_private_jwt` from the dropdown menu.
   2. In the **Key Algorithm** field, select a key pair algorithm from the dropdown menu. If unspecified, the default value is `RS256`.
   3. Click **Save**.
4. Copy the resulting public key (Public Json Web Key) and register it in your 3rd party IDP.

<!-- document id=1f268ab644b58137613f17c91bfa325ad5c49900efa536285196d32697cd5311 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-guest-jwt-implementation.md -->

# Configure External Client App for Guest JWT Authentication

Follow these steps to enable headless guest support for Cart and Checkout APIs using JWT in your B2B Commerce store.

## Step 1: Enable CORS

Web applications use Cross-Origin Resource Sharing (CORS) to request resources from origins other than their own. For example, a web page can use CORS to request information about a user from your My Domain login URL or Experience Cloud site URL. In addition to public and allowlisted web pages, Salesforce supports CORS for certain OAuth endpoints when requested from a My Domain login URL or Experience Cloud site URL.

See [Enable CORS for OAuth Endpoints](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_enable_cors_oauth.htm&type=5) for more information.

## Step 2: Configure External Client App

The External Client App (Connected App) is the foundation of your headless guest support implementation.

Create an external client app in App Manager. Local external client apps are available only on the org where you create them. Packageable external client apps can be packaged for distribution to other orgs. See [Create an External Client App](https://help.salesforce.com/s/articleView?id=sf.external_client_app_create.htm&type=5) for more information.

1. From Setup, in the Quick Find box, enter **App Manager**, and then select **App Manager**.
2. Click **New External Client App**.
3. Enter a name for the external client app to display in the **External Client App Manager**.
4. Enter the contact email for Salesforce to use to contact you or your support team.

   > **Note:** This address isn't given to Salesforce admins who install the app.

5. Select **Enable OAuth** in the **API (Enable OAuth Settings)** area of the page.

   The OAuth Settings area expands and the OAuth settings fields are visible.

6. Enter the callback URL (endpoint) that Salesforce calls back to your application during OAuth in the **App Settings** area of the page. It's the same as the OAuth redirect URI.

   Depending on which OAuth flow you use, the URL is typically the one that a user's browser is redirected to after successful authorization.

   **Example:**

   - Store URL: `https://mgltd.my.site-com.5ps3ut55w1pn004g6z7ffte3819ke.aa.crm.dev:6101/agent`
   - Callback URL: `https://mgltd.my.site-com.5ps3ut55w1pn004g6z7ffte3819ke.aa.crm.dev:6101/agent`

7. Select **Access unique user identifiers (openid)** in the **OAuth Scopes** area of the page. The returned token can include the ID token.

   > **Note:** The ID token is always included in access token responses.

8. Select **Enable Authorization Code and Credentials Flow** in the **Flow Enablement** area of the page.
9. Click **Create**.

## Step 3: Configure External Client App's Policies

OAuth policies are an important part of the external client app OAuth plugin that are generated with default values when an external client app is saved or during deployment to a subscriber org. Admins configure the OAuth policies file for their specific use case.

Policies only apply to the org where they are configured, whether that is the same org where the external client app was created or the external client app was installed. After an admin updates policies, the values persist even if the developer updates the app Settings. See [Configure OAuth Policies](https://help.salesforce.com/s/articleView?id=sf.external_client_app_oauth_policies.htm&type=5) and [Manage External Client Apps](https://help.salesforce.com/s/articleView?id=sf.external_client_app_manage.htm&type=5) for more information.

1. From Setup, in the Quick Find box, enter **External Client Apps Manager**, and then select **External Client Apps Manager**.
2. From the actions list for the external client app, select **Edit Policies**.

Then edit the App or OAuth policies.

3. Click **OAuth Policies** to expand the section.
4. Select **Admin approved users are pre-authorized** from the **Permitted Users** dropdown in the OAuth Policies area of the page.
5. To admin-approve users, select permission sets assigned to your app's users. For more information, see [Permission Sets](https://help.salesforce.com/s/articleView?id=sf.perm_sets_overview.htm&type=5).
6. Click **Save**.

Your app can now use the Authorization Code and Credentials Flow for headless login, passwordless login, and registration.

## Step 4: Configure Policies for Guest User Flow

Use these additional OAuth policies to enable your app for the guest user flow variation.

1.  From the external client app policies page, turn on **Enable Code and Credentials Flow for Guest Users** in the **OAuth Flows and External Client App Enhancements** area of the page.
2.  For Guest JSON Web Token (JWT) Timeout, select **Use the Experience Cloud guest user session timeout** to define how long the guest access token remains valid after it’s issued.
3.  Click **Save**.

## Step 5: Access Consumer Details

In this OAuth 2.0 client credentials flow, the client app exchanges its client credentials defined in the external app—its consumer key and consumer secret—for an access token.

1. From Setup, in the Quick Find box, enter **External Client Apps Manager**, and then select **External Client Apps Manager**.
2. Click the external client app.
3. Click **Settings** and expand the **OAuth Settings** section.
4. From the App Settings section, click **Consumer Key and Secret**.

   In the Consumer Details page, copy the **Consumer Key** and **Consumer Secret** and save them for use in the headless API calls.

<!-- document id=ff92e0773b263eb39ba7fad13283d27730bd19718934a2a7009a45d5812d7924 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/spi-webhook-monitoring.md -->

# Configure Monitoring for SPIs and Webhooks in Point of Sale CMS

Enable Web Client Service to monitor SPI and webhook integrations configured in Point of Sale CMS. Set up a monitoring webhook to track performance and get alerts if an SPI or webhook fails. Define a latency threshold for the response time.

## Turn On Web Client Service.

1.  Go to **Store Management** | **Store Settings** | **System**.

2.  Expand the **Rollout** section.

3.  Turn on **Enabled Web Client Service (supportWebClient)**.

4.  Save your changes.

## Configure a Monitoring Webhook

1.  In CMS, go to **Integrations** | **Custom Connectors**.

2.  Click **Create**.

3.  For Connector Type, select **Webhook (1)**.

4.  For Endpoint Name, select **EXPORT_MONITORING_EVENTS (2)**.

5.  For API Endpoint, provide the URL endpoint of the API (3).

6.  For Integration Type, select **HTTP_POST or HTTP_PUT**.

7.  Save your changes.

![The Monitoring Webhook Settings in Point of Sale CMS](https://developer.salesforce.com/docs/media/retail-cloud/rt-cms-modules-config-monitoring-webhook.png)

## Turn On Monitoring for a Webhook or SPI

1.  Go to **Integrations** | **Custom Connectors**.

2.  Click the pencil icon to edit the webhook or SPI configuration you want to enable monitoring for.

3.  Turn on **Enable Monitoring** (1).

4.  (Optional) If you want to be notified of a slow response time, enter a maximum time (in seconds) for Latency Threshold (2). For example, a Latency Threshold of 120 triggers a monitoring alert if a webhook or SPI takes 120 seconds or longer to respond.

5.  Save your changes.

![The Enable Monitoring and Legacy Threshold settings in Point of Sale CMS.](https://developer.salesforce.com/docs/media/retail-cloud/rt-cms-module-enable-monitoring-webhook.png)

<!-- document id=9e8966d98d4a3211193b2f2737535cba643142d66aab0226ae6969c10766bf88 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/configure-mrt-routing-bm.md -->

# Configure MRT Routing Rules in Business Manager

Starting with B2C Commerce version 25.4, you can configure routing rules for embedded content delivery network (eCDN) by using Business Manager as an alternative to the [createCustomRule API](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createCustomRule) (CDN API).

By using Business Manager instead of the CDN API to route traffic to your Managed Runtime (MRT) environment, you can:

- Speed up CDN setup with an intuitive UI.
- Simplify deployment processes.

This guide explains how to use Business Manager to view, create, edit, or delete routing rules for zones in a Progressive Web App (PWA) Kit site or [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.html).

**note:** This guide applies to you if you’re using eCDN, it doesn’t apply if you’re using the MRT CDN or a third-party CDN. See [Decide which CDN to Use](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/decide-on-cdn.html).

## Prerequisites

Before you configure routing rules:

- Define your hostnames in the alias file. To do so, in Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Merchant Tools > _Your Site_ > SEO > Aliases**.
- Find the zone ID of the eCDN zone to be used with Managed Runtime. To get this info, use the [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo) endpoint of the CDN Zones API.
- Complete the steps under [Before You Begin](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#before-you-begin).

## Considerations

Here are a few points to consider when you create a rule expression:

- Include one expression per rule.
- You can set up all paths or specific paths for a particular hostname to be forwarded to MRT.
- When you create or edit a routing rule, if you don’t provide paths in a rule expression and you select only a hostname, all traffic is routed to MRT.
- The structure of the rule expression differs slightly when creating rules using Business Manager instead of the CDN API. When you configure rules in Business Manager, leave the http.host field out of the rule expression. You select the hostnames separately on the page, and they’re automatically prepended to the rule expression during rule creation. Requests are directed to your specified MRT origin.
- If you provide a single path, the path condition is combined with the host condition using an "AND" operator. This means that both the host and the path conditions must be true for the rule to take effect.
- When you provide multiple paths using an "OR" operator, if any of the specified paths match, the rule takes effect.

In this example, the rule applies if the URL path starts with either `/products` or `/be/fr/home-page` followed by any number of characters.

`http.request.uri.path matches "^/products" or http.request.uri.path matches "^/be/fr/home-page.*"`

For more examples, see [Create a Routing Rule](#create-a-routing-rule).

## View Routing Rules

**note:** Routing rules are configured per **zone**.

1. In Business Manager, navigate to the Embedded CDN Settings page.
2. Locate the zone you wish to view.
3. Click on the caret dropdown to the right of the zone.
4. Select **Configure Routing Rules**.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/view-routing-rules2.png)

The following page displays the existing routing rules for the selected zone. Click the caret icon next to each rule to expand or collapse the rule details. You can also use the search bar to quickly filter rules by name.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/view-routing-rules-list.png)

## Create a Routing Rule

To route traffic to a Managed Runtime environment, create a routing rule.

1. In Business Manager, on the Configure Routing Rules page, click **New Rule**.
2. Fill out the required input fields. Refer to the tooltips for additional information regarding each field.
3. (Optional) A few rule templates are available to help you get started. They provide a foundation for building rule expressions based on your specific use case. For some key points that apply to rule expressions, see [Considerations](#considerations).

### Example 1

This example shows how to route all traffic to MRT.

- On the Rule Template list, select **Recommended Fully Composable**.
- Leave the Rule Expression field blank.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/route-all-traffic-to-mrt.png)

### Example 2

This example shows how to route only specific paths to MRT.

- On the Rule Template list, make a selection.
- In the Rule Expression field, enter specific paths to route to MRT.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/route-specific-traffic.png)

4. Click **Save**.
5. When the confirmation message appears, click **Save** again to create the rule.

After a moment, the newly created rule is visible on the Configure Routing Rules page.

## Edit a Routing Rule

You can update an existing routing rule. For example, you can route traffic to a different Managed Runtime environment or make updates if the structure of your site URLs changed.

1. In Business Manager, on the Configure Routing Rules page, locate the routing rule you wish to edit.
2. Click **Edit**.
3. Update the fields as desired. For some key points that apply to rule expressions, see [Considerations](#considerations).
4. Click **Save**.
5. When the confirmation message appears, click **Save** again to update the rule.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/edit-rule.png)

After a moment, the updated rule is visible on the Configure Routing Rules page.

## Delete a Routing Rule

If you're switching to a third-party CDN or you no longer want to route a particular path from eCDN to MRT, you can delete a routing rule.

1. In Business Manager, on the Configure Routing Rules page, locate the routing rule you wish to edit.
2. Click **Delete/Trash**.
3. When the confirmation message appears, click **Delete** to delete the rule.

After a few seconds, the rule is removed from the Configure Routing Rules page.

## See Also

- [Decide which CDN to Use](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/decide-on-cdn.html)
- [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html)
- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.html)
- [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html)

<!-- document id=136157239dd54bf5ace4f161c7191dd59b16360dff3e86e1bb76ba06efa65108 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-multi-site.md -->

# Configure Multisite URLs

Storefront Next supports serving multiple B2C Commerce sites and locales from a single deployment. This configuration applies whether you operate a single site or multiple sites—in both cases, the multisite middleware handles site and locale resolution. Configure how site and locale identifiers appear in your URLs—in the path, as query parameters, or a combination of both. For single-site storefronts, you can omit identifiers from the URL entirely and let the middleware resolve everything from cookies and headers.

## How Multisite URLs Work

Multisite configuration controls how site and locale identifiers appear in your storefront URLs. The `url` config determines the URL pattern, and the detection config determines how the middleware reads site and locale back from incoming requests.

Configuration is in `config.server.ts` under three areas:

- `commerce.sites` defines the available sites and their supported locales.
- `defaultSiteId` determines the fallback site when no site can be resolved from the URL, cookie, or header.
- `url` defines the URL pattern, which includes the path prefix, query parameters, and excluded routes.

### Default Template Behavior

The Storefront Next template defaults to a convention where all URLs—including the homepage—use site and locale prefixes (for example, `/global/en-GB/` for the homepage, `/global/en-GB/product/123` for subpages). Requests to bare `/` are redirected server-side to the default site and locale prefix. This makes all URLs shareable and fully deterministic.

|                     | Homepage (`/global/en-GB/`)   | Subpages                                    |
| ------------------- | ----------------------------- | ------------------------------------------- |
| **URL**             | Prefixed with site/locale     | Includes site/locale prefix or query params |
| **Site resolution** | From URL path or query params | From URL path or query params               |
| **Shareable?**      | Yes (deterministic from URL)  | Yes (deterministic from URL)                |

The bare `/` redirect is handled in the homepage loader (`_app._index.tsx`), so you can customize the redirect behavior as needed.

## Define Your Sites

Sites and locales are defined under `commerce.sites` in `config.server.ts`. By default, sites and their locales are retrieved from the MRT Data Store. See [MRT Data Store Sites](#mrt-data-store-sites). If the MRT Data Store sites option is turned off, sites and locales are retrieved from `config.server.ts`.

```typescript
// config.server.ts
export default defineConfig({
  app: {
    defaultSiteId: "RefArchGlobal",
    commerce: {
      sites: [
        {
          id: "RefArchGlobal",
          defaultLocale: "en-GB",
          defaultCurrency: "GBP",
          supportedLocales: [
            { id: "en-GB", preferredCurrency: "GBP" },
            { id: "fr-FR", preferredCurrency: "EUR" },
            { id: "it-IT", preferredCurrency: "EUR" },
            { id: "ja-JP", preferredCurrency: "JPY" },
            { id: "zh-CN", preferredCurrency: "CNY" },
          ],
          supportedCurrencies: ["EUR", "GBP"],
        },
        {
          id: "RefArch",
          defaultLocale: "en-US",
          defaultCurrency: "USD",
          supportedLocales: [{ id: "en-US", preferredCurrency: "USD" }],
          supportedCurrencies: ["USD"],
        },
      ],
    },
  },
});
```

Each field serves a specific purpose:

- **`id`** — The B2C Commerce site ID. This must match the site ID configured in Business Manager.
- **`defaultLocale`** — The locale used when no locale can be resolved from the URL, cookie, or header.
- **`defaultCurrency`** — The fallback currency when no currency preference exists.
- **`supportedLocales`** — An array of locales available for this site. Each entry includes an `id` and a `preferredCurrency` that is applied when the user selects that locale.
- **`supportedCurrencies`** — The currencies available for manual selection on this site.
- **`defaultSiteId`** — Defined at the `app` level, this determines which site is used on a first visit when no `site_id` cookie exists.

**note:** Keep the `i18n.supportedLngs` array in sync with the locale `id` values across all entries in `commerce.sites[].supportedLocales`. A mismatch causes the locale switcher to show unsupported locales or hide valid ones.

### MRT Data Store Sites

On by default. When `commerce.sitesFromDal` is on, live site data synced through the [MRT Data Store](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-data-store.md) replaces the static `commerce.sites` for site, locale, and currency resolution, resolved per request. `defaultSiteId`, `siteAliasMap`, and `localeAliasMap` stay static and derived from config, never from the MRT Data Store. Set the flag to `false` to keep the static `commerce.sites` authoritative.

**Fallback behavior.** When the middleware can't get site data from the MRT Data Store, the storefront keeps serving the static `commerce.sites` and doesn't fail the request. This fallback applies whenever `commerce.sitesFromDal` is off, the MRT Data Store entry is unavailable, the payload yields no usable sites, or the usable sites omit the site named by `defaultSiteId`. That last case logs a warning naming the missing default and the site IDs actually present, so the issue is visible in monitoring.

**URL aliasing stays config-owned.** The MRT Data Store supplies which sites exist and their locale and currency data, but not how their URLs are aliased. `siteContextMiddleware` runs after the data store rewrite and derives each resolved site's routing `alias` from the config `siteAliasMap`, keyed by site `id` (the same key for the data store and static sites), so `siteAliasMap` and `localeAliasMap` stay the config-owned source for the `:siteId` and `:localeId` URL refs. A per-site `alias` on the data store payload would be overwritten before routing reads it, so the rewrite drops it at the source. This is what keeps multi-site URLs stable when sites go live from the data store.

```bash
# Opt out via env (see README-CONFIG.md) to keep static commerce.sites authoritative
# PUBLIC__app__commerce__sitesFromDal=false
```

## Configure URL Patterns

The `url` config in `config.server.ts` controls how multisite URLs are constructed.

```typescript
url: {
    prefix: '/:siteId/:localeId',
    search: '?lng=:localeId',
    excludeRoutes: ['/resource/**', '/action/**'],
}
```

- **`prefix`** — Path segments prepended to subpage URLs. Use `:siteId` and `:localeId` as placeholders that are replaced with the resolved values at URL build time.
- **`search`** — Query parameters appended to subpage URLs. Use the same `:siteId` and `:localeId` placeholder syntax.
- **`excludeRoutes`** — Glob patterns for routes that skip prefixing (e.g., API resource routes and server actions).

Both `prefix` and `search` are optional. Use either, both, or neither depending on your URL strategy.

When `url.search` is configured, `buildUrl` injects the search params using `searchParams.set()`. This **overwrites** any existing query param with the same key, but **preserves** all other query params. For example, a product search URL like `/product?q=shoes` with `search: '?lng=:localeId'` resolves to `/global/product?q=shoes&lng=en-GB`—the existing `q` param is preserved and `lng` is appended. If your URL already contained a `lng` param, the configured value takes precedence.

**warning:** `url.prefix` and `url.excludeRoutes` are protected configuration paths. They cannot be overridden via `PUBLIC__` environment variables at runtime. Changing these values requires updating `config.server.ts` and rebuilding the application. This is because the prefix determines the React Router route structure, which is baked into the build.

## Use Alias Maps for Clean URLs

Map B2C Commerce site IDs and locale IDs to shorter, URL-friendly aliases. Define these at the `app` level in `config.server.ts`.

```typescript
// config.server.ts
export default defineConfig({
  app: {
    siteAliasMap: {
      RefArchGlobal: "global",
      RefArch: "us",
    },
    localeAliasMap: {
      "en-US": "us",
      "en-GB": "gb",
    },
  },
});
```

With `siteAliasMap`, the site `RefArchGlobal` appears as `global` in URLs: `/global/en-GB/product/123`

With `localeAliasMap`, the locale `en-GB` appears as `gb`: `/global/gb/product/123`

Both alias maps are optional. Without them, the raw B2C Commerce IDs appear in URLs.

## Configure Site and Locale Detection

The URL config (`prefix`, `search`) controls how URLs are **built**. The detection config controls how site and locale are **read back** from incoming requests. These must stay in sync.

The default detection config is:

```typescript
// Default site detection
siteDetectionConfig: {
    order: ['path', 'querystring', 'cookie', 'header'],
    lookupFromPathIndex: 0,
    lookupQuerystring: 'site',
    lookupCookie: 'site_id',
    lookupHeader: 'X-Site-Id',
    caches: ['cookie'],
}

// Default locale detection
localeDetectionConfig: {
    order: ['path', 'querystring', 'cookie', 'header'],
    lookupFromPathIndex: 1,
    lookupQuerystring: 'lng',
    lookupCookie: 'lng',
    lookupHeader: 'Accept-Language',
    caches: ['cookie'],
}
```

The middleware checks each source in the specified `order` and uses the first match.

Each field controls a specific detection behavior:

- **`order`**—The priority sequence for resolving the value. The middleware tries each source in order and uses the first match. For example, `['path', 'querystring', 'cookie', 'header']` checks the URL path first, then query parameters, then cookies, then HTTP headers.
- **`lookupFromPathIndex`**—Which URL path segment to read when `'path'` is in the `order`. `0` means the first segment (e.g., `/global/en-GB/...` → `'global'`), `1` means the second segment (e.g., `/global/en-GB/...` → `'en-GB'`).
- **`lookupQuerystring`**—The query parameter name to check when `'querystring'` is in the `order`. For example, `'site'` looks for `?site=global`, and `'lng'` looks for `?lng=en-GB`.
- **`lookupCookie`**—The cookie name to check when `'cookie'` is in the `order`. For example, `'site_id'` checks the `site_id` cookie, and `'lng'` checks the `lng` cookie.
- **`lookupHeader`**—The HTTP header to check when `'header'` is in the `order`. For example, `'X-Site-Id'` checks the `X-Site-Id` request header, and `'Accept-Language'` checks the `Accept-Language` header.
- **`caches`**—Where to persist the resolved value. `['cookie']` means the resolved value is stored in a cookie for subsequent requests, ensuring consistency across page navigations.

**important:** The query param key for locale must be `lng` to match the i18next cookie key and default detection config. The query param key for site defaults to `site`. If you use different keys in your `url.search` config, update the corresponding `lookupQuerystring` value in the detection config.

## Configure Site-Context Cookies

The `siteContext` config in `config.server.ts` controls how site-context cookies are stored. Site-context cookies are site, locale, and currency cookies. The `siteContext` fields are optional.

```typescript
// config.server.ts
export default defineConfig({
  app: {
    siteContext: {
      currencyCookieName: "currency",
      cookieOptions: {
        httpOnly: true,
        secure: true,
        sameSite: "lax",
        maxAge: 604800, // 7 days
      },
    },
  },
});
```

- **`currencyCookieName`**—The cookie name used to persist the shopper's selected currency. Defaults to `'currency'`.
- **`cookieOptions`**—Cookie attributes that are applied to all three site-context cookies: site, locale, and currency. Valid options include `httpOnly`, `maxAge`, `secure`, `sameSite`, `path`, `domain`, and so on. These options follow the standard [Cookie](https://reactrouter.com/api/cookie) options from React Router. Defaults to `{ path: '/', sameSite: 'lax', secure: true, httpOnly: true }`.

## URL Pattern Use Cases

Below are common URL patterns you can achieve by combining `prefix`, `search`, and the corresponding detection config overrides. The available placeholders are `:siteId` and `:localeId`, which are resolved from the current site and locale, after alias mapping.

### Site and Locale in the Path (Default)

```typescript
// config.server.ts
export default defineConfig({
  app: {
    url: {
      prefix: "/:siteId/:localeId",
      excludeRoutes: ["/resource/**", "/action/**"],
    },
    // No detection config override needed — the defaults match this URL pattern.
  },
});
```

This is the default configuration. Both site and locale are visible in every URL, including the homepage. The default detection config expects site at path index 0 and locale at path index 1, which matches this pattern. No detection config override is needed.

Best for: Most multisite storefronts. Clean, fully deterministic URLs.

| Page                            | URL                             |
| ------------------------------- | ------------------------------- |
| Homepage (RefArchGlobal, en-GB) | `/global/en-GB/`                |
| Product (RefArchGlobal, en-GB)  | `/global/en-GB/product/123`     |
| Product (RefArch, en-US)        | `/us/en-US/product/123`         |
| Category (RefArchGlobal, it-IT) | `/global/it-IT/category/womens` |

### Locale Only in the Path

```typescript
// config.server.ts
export default defineConfig({
  app: {
    url: {
      prefix: "/:localeId",
      excludeRoutes: ["/resource/**", "/action/**"],
    },
    // Required: locale moved from path index 1 to 0.
    localeDetectionConfig: { lookupFromPathIndex: 0 },
    // Recommended: explicitly remove 'path' from site detection order so the
    // middleware doesn't attempt to read a locale string (e.g., 'en-GB') as a
    // site ID. Without this override, site detection will try path index 0,
    // fail to match a valid site, and fall through — which works but is less
    // explicit. Removing 'path' from site detection is the safer and more
    // defensive approach.
    siteDetectionConfig: { order: ["querystring", "cookie", "header"] },
  },
});
```

With this pattern, the site is resolved via the detection fallback chain. You **must** update `localeDetectionConfig` to set `lookupFromPathIndex: 0`, because the locale is now the first path segment instead of the second. It is also recommended to explicitly remove `'path'` from `siteDetectionConfig.order` so that the middleware does not attempt to interpret the locale string (for example, `en-GB`) as a site ID.

Best for: Single-site storefronts with multiple locales, or when the site is determined by cookie or domain.

| Page             | URL                      |
| ---------------- | ------------------------ |
| Homepage (en-GB) | `/en-GB/`                |
| Product (en-GB)  | `/en-GB/product/123`     |
| Product (en-US)  | `/en-US/product/123`     |
| Category (it-IT) | `/it-IT/category/womens` |

### Site in the Path, Locale in Query Params

```typescript
// config.server.ts
export default defineConfig({
  app: {
    url: {
      prefix: "/:siteId",
      search: "?lng=:localeId",
      excludeRoutes: ["/resource/**", "/action/**"],
    },
    // No detection config override required.
    // Site is still at path index 0 (default).
    // Locale detection tries path index 1 first (e.g., 'product'), doesn't find a valid
    // locale, and falls through to querystring where it finds ?lng=en-GB.
  },
});
```

No detection config override is required. The site is still resolved from path index 0. For locale, the default detection tries path index 1 first, doesn't find a valid locale ID there, and falls through to the `?lng=` query parameter.

Best for: Shorter path segments while keeping locale in the URL for shareability.

| Page                            | URL                                 |
| ------------------------------- | ----------------------------------- |
| Homepage (RefArchGlobal, en-GB) | `/global/?lng=en-GB`                |
| Product (RefArchGlobal, en-GB)  | `/global/product/123?lng=en-GB`     |
| Product (RefArch, en-US)        | `/us/product/123?lng=en-US`         |
| Category (RefArchGlobal, it-IT) | `/global/category/womens?lng=it-IT` |

### Everything in Query Params

```typescript
// config.server.ts
export default defineConfig({
  app: {
    url: {
      search: "?site=:siteId&lng=:localeId",
      excludeRoutes: ["/resource/**", "/action/**"],
    },
    // No detection config override required.
    // Path detection reads page path segments (e.g., 'product', '123'), doesn't find
    // valid site/locale IDs, and falls through to querystring where it finds
    // ?site=global&lng=en-GB.
  },
});
```

Without a `prefix`, React Router doesn't need site/locale route params in its route definitions. No detection config override is required—the default detection tries path segments first, doesn't find valid site or locale IDs, and naturally falls through to the query parameters.

Best for: Storefronts that want clean paths and don't mind query params.

| Page     | URL                                  |
| -------- | ------------------------------------ |
| Homepage | `/?site=global&lng=en-GB`            |
| Product  | `/product/123?site=global&lng=en-GB` |
| Category | `/category/womens?site=us&lng=en-US` |

### Locale Only in Query Params

```typescript
// config.server.ts
export default defineConfig({
  app: {
    url: {
      search: "?lng=:localeId",
      excludeRoutes: ["/resource/**", "/action/**"],
    },
    // No detection config override required.
    // Path detection doesn't find valid site/locale IDs in page path segments
    // and falls through. Site resolves from cookie or header; locale from ?lng=.
  },
});
```

No detection config override is required. The default detection falls through path segments to find the locale in the `?lng=` query parameter. Site is resolved from cookie or header via the same fallback chain.

Best for: Single-site storefronts that want locale-aware URLs without path changes.

| Page     | URL                          |
| -------- | ---------------------------- |
| Homepage | `/?lng=en-GB`                |
| Product  | `/product/123?lng=en-GB`     |
| Category | `/category/womens?lng=it-IT` |

### No Prefix (Single Site)

```typescript
// config.server.ts
export default defineConfig({
  app: {
    defaultSiteId: "RefArch",
    commerce: {
      sites: [
        {
          id: "RefArch",
          defaultLocale: "en-US",
          defaultCurrency: "USD",
          supportedLocales: [{ id: "en-US", preferredCurrency: "USD" }],
          supportedCurrencies: ["USD"],
        },
      ],
    },
    url: {
      prefix: "/",
      excludeRoutes: ["/resource/**", "/action/**"],
    },
    // No detection config override required.
    // Path detection doesn't find valid site/locale IDs in page path segments
    // and falls through. Both site and locale resolve from cookie or header.
  },
});
```

This configuration produces the cleanest possible URLs with no site or locale identifiers at all. The multisite middleware still runs, but it resolves site and locale entirely from cookies and headers using the detection fallback chain. On a first visit with no cookies, the `defaultSiteId` and `defaultLocale` values from `config.server.ts` determine which site and locale are used.

No detection config override is required. The default detection tries path segments first, doesn't find valid site or locale IDs, and falls through to cookies and headers. Because there is only one site and one locale configured, the defaults are always used on the first visit and persisted via cookies for subsequent requests.

Best for: Single-site, single-locale storefronts that don't need site or locale identifiers in the URL.

| Page     | URL                |
| -------- | ------------------ |
| Homepage | `/`                |
| Product  | `/product/123`     |
| Category | `/category/womens` |

## Switch Sites, Locales, and Currencies

The Storefront Next template includes built-in switcher components for site, locale, and currency. Each switcher posts to the `/action/set-site-context` server action, which sets the appropriate cookies and redirects to the updated URL.

### Site Switcher

The site switcher component is at `src/components/site-switcher`. When a shopper selects a new site:

1. The dropdown calls `i18n.changeLanguage` with the default locale of the new site.
2. A `POST` is submitted to `/action/set-site-context` with the new `siteId` and `localeId`.
3. The server action sets the `site_id` and `lng` cookies and issues a redirect.
4. The page reloads with the new site and locale applied.

### Locale Switcher

The locale switcher component is at `src/components/locale-switcher`. When a shopper selects a new locale:

1. The current URL path is stripped of its site/locale prefix using `stripPathPrefix`.
2. The new URL is rebuilt with the updated locale using `buildUrl`.
3. `i18n.changeLanguage` is called with the new locale string.
4. A `POST` is submitted to `/action/set-site-context` with the updated `localeId`.
5. The server action sets the `lng` cookie.
6. React Router triggers a full loader revalidation so all page data is reloaded with the new locale context.

### Currency Switcher

When a shopper selects a currency, the currency switcher posts the new currency to `/action/set-site-context`, which stores it in the currency cookie (default name: `currency`).

The active currency is resolved using the following priority order:

| Priority | Source                                            |
| -------- | ------------------------------------------------- |
| 1        | Currency cookie (shopper's explicit selection)    |
| 2        | `preferredCurrency` from the active locale config |
| 3        | `defaultCurrency` from the active site config     |

## Access Site Context in React Components

Use `useSite()` to access the current site, language, and currency in React components:

```typescript
import { useSite } from "@salesforce/storefront-next-runtime/site-context";

function MyComponent() {
  const { site, language, currency } = useSite();
  // site: Site object (id, supportedLocales, supportedCurrencies, etc.)
  // language: current locale ID (e.g., 'en-GB')
  // currency: current currency code (e.g., 'GBP')
}
```

`useSite()` throws if called outside a `SiteProvider`. In the template, `SiteProvider` is mounted in `root.tsx` and wraps the entire app.

**note:** `useSite` also returns the `locale` object that contains the i18next language string, but Storefront Next doesn't use it for locale switching. It uses the `language` value, which represents the language for the app.

## Navigate with Site Context

Storefront Next provides multisite-aware navigation utilities that automatically prepend the active site and locale prefix to every URL. Always use these instead of the standard React Router equivalents.

### Link and NavLink

Import `Link` and `NavLink` from `@/components/link` instead of from React Router. These components are drop-in replacements that automatically prefix paths with the active site and locale.

```typescript
import { Link, NavLink } from "@/components/link";

// Renders as /global/en-GB/product/123
<Link to="/product/123">View Product</Link>

// External URLs and non-string `to` values (e.g., objects with pathname) pass
// through unchanged, so you can use the same component for all link types.
<Link to="https://example.com">External</Link>
```

### useNavigate

Import `useNavigate` from `@/hooks/use-navigate` instead of from React Router. The returned navigate function applies the site and locale prefix automatically.

```typescript
import { useNavigate } from "@/hooks/use-navigate";

function MyComponent() {
  const navigate = useNavigate();

  // Navigate to a prefixed path string
  navigate("/product/123");

  // Navigate to root (resolves to the site/locale homepage, e.g., /global/en-GB/)
  navigate("/");

  // Navigate with an object
  navigate({ pathname: "/product/123", search: "?color=red" });

  // History navigation (back/forward) passes through unchanged
  navigate(-1);
}
```

### useCurrentSiteAndLocaleRef

Use the `useCurrentSiteAndLocaleRef` hook when you need to build URLs manually outside of Link or useNavigate:

```typescript
import { useCurrentSiteAndLocaleRef } from "@salesforce/storefront-next-runtime/site-context";
import { buildUrl } from "@/lib/url";
import { useConfig } from "@salesforce/storefront-next-runtime/config";

function MyComponent() {
  const config = useConfig();
  const currentSiteAndLocaleRef = useCurrentSiteAndLocaleRef();

  const url = buildUrl("/product/123", config.app.url, currentSiteAndLocaleRef.current);
  // url: /global/en-GB/product/123
}
```

### React Router Form Actions

React Router's `<Form>` component does **not** go through `buildUrl`. If you pass an `action` prop to `<Form>`, you must prefix it manually:

```typescript
import { Form } from "react-router";
import { buildUrl } from "@/lib/url";
import { useConfig } from "@salesforce/storefront-next-runtime/config";
import { useCurrentSiteAndLocaleRef } from "@salesforce/storefront-next-runtime/site-context";

function SearchForm() {
  const config = useConfig();
  const currentSiteAndLocaleRef = useCurrentSiteAndLocaleRef();

  const action = buildUrl("/action/search", config.app.url, currentSiteAndLocaleRef.current);

  return (
    <Form method="post" action={action}>
      ...
    </Form>
  );
}
```

**warning:** Using `<Form action="/some-path">` without prefixing produces a URL without the site/locale prefix, which causes a 404 error.

## Important Considerations

1. **Homepage URL uses site and locale prefix.** All URLs—including the homepage—use the configured site and locale prefix (e.g., `/global/en-GB/`). Requests to bare `/` are redirected server-side to the default site and locale prefix. This redirect is handled in the homepage loader (`_app._index.tsx`) and can be customized.

2. **URL prefix changes require a rebuild.** `url.prefix` and `url.excludeRoutes` are protected paths. They can't be changed via `PUBLIC__` environment variables. Update `config.server.ts` and rebuild the application.

3. **Detection config overrides are only required when path indexes shift.** The detection middleware uses a fallback chain—if it doesn't find a valid site or locale at the current source, it moves to the next one. In most non-default URL patterns, path detection simply fails to match and falls through to querystring or cookie. The only case where an override is **required** is when a path segment's position changes (e.g., locale moves from index 1 to index 0 in a locale-only prefix).

4. **Query param keys are not arbitrary.** The locale query param key must be `lng` (matching the i18next cookie). The site key defaults to `site`. Custom keys require matching updates to the detection config.

5. **Use multisite-aware navigation.** Always use `Link` and `NavLink` from `@/components/link`, `useNavigate` from `@/hooks/use-navigate`, and `buildUrlFromContext` for server-side redirects. These automatically apply the URL prefix. Using React Router's `Link` or `redirect` directly produces URLs without the prefix, resulting in 404 errors.

   In loaders and actions, use `buildUrlFromContext` from `@/lib/url.server` to build redirect URLs:

   ```typescript
   import { redirect } from "react-router";
   import { buildUrlFromContext } from "@/lib/url.server";

   export async function loader({ request, context }: LoaderFunctionArgs) {
     if (!isAuthenticated) {
       // bare redirect('/login') produces a URL without the prefix → 404
       throw redirect(buildUrlFromContext("/login", context));
     }
   }
   ```

6. **Keep i18n and site config in sync.** The locale IDs in your `i18n.supportedLngs` must match the `id` values in `commerce.sites[].supportedLocales`. A mismatch causes the locale switcher to show unsupported locales or hide valid ones.

7. **Always include framework routes in excludeRoutes.** The `/resource/**` and `/action/**` patterns must remain in `excludeRoutes`. Removing them causes resource routes and server actions to be incorrectly prefixed with site/locale segments.

8. **Prefix React Router Form action values manually.** React Router's `<Form>` component does not go through `buildUrl`. If you use `<Form action="/some-path">`, prefix the action yourself using `buildUrl` with `useConfig` and `useCurrentSiteAndLocaleRef`. See [Navigate with Site Context](#navigate-with-site-context) for a code example.

## See Also

- [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md)
- [Internationalization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-intl.md)
- [SEO URL Rules Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-seo-url-rules-best-practices.md)

<!-- document id=aced44cc6d61af456394efe25174696692558c859948664b4cae60c2d58201d7 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/one-click-checkout.md -->

# Configure One-Click Checkout for Your B2C Commerce Composable Storefronts

One-click checkout streamlines the checkout experience for shoppers in your B2C Commerce Composable storefronts. When a first-time shopper checks out, they can save their checkout information for future use. If the shopper selects **Create an account to check out faster,** a one-time password (OTP) window appears where they can enter the code sent to their email address. After the shopper verifies their email address, the system creates an account for them with your store and saves their shipping and payment information for future use.

![Save payment, address, and contact information for future use with one-click checkout](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/one_click_checkout.png '{"class": "image-xl"}')

If a registered shopper returns to make another purchase, the shopper only needs to enter their email address and a verification code to check out. Their default or first saved shipping address and payment information is automatically filled in.

Shoppers always have the option to check out as a guest. Additionally, shoppers can log into their account to view their saved shipping and payment information.

Set up one-click checkout for B2C Commerce Composable storefronts.

1. If your PWA Kit isn’t version 3.17 or later, [Upgrade to v3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.html).

2. In `packages/template-retail-react-app/config/default.js`, set `oneClickCheckout.enabled` to `true`.

```
//config/default.js
app: {
    // …existing config
    oneClickCheckout: {
        enabled: true
    }
}
```

3. Create a SLAS private client. See [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html#configure-the-pwa-kit).
4. In `packages/template-retail-react-app/ssr.js`, add the `onSLASPrivateProxyRes` callback to the runtime options to handle the passwordless login responses.

```
onSLASPrivateProxyRes: (responseBuffer, proxyRes, req, res) => {
    // Undo the 404 → 200 masking for /oauth2/passwordless/login
    if (req.path?.match(/\/oauth2\/passwordless\/login/) && proxyRes.statusCode === 404) {
        res.statusCode = 404
        res.statusMessage = 'Not Found'
    }
    return responseBuffer
},
```

5. To send shoppers a one-time password via email, [Configure Email Templates](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#3-configure-email-templates).
6. To maintain security, we recommend that you implement these safegaurds.

   a. Captcha - Protects the passwordless login from bots.

   b. OTP for Email Changes - Verifies your identity before an email update, prevents accidental account lockouts from typos, and prevents unauthorized users from gaining access to saved payment methods.

<!-- document id=5b73b6f30b33939f6c88370e9d0dd4079d702df60dbef8a26d40e66808b6e2c9 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-profile-connector/configure-profile-data.md -->

# Configure Profile Data

Einstein requires that business users set up correlations between shopper profile data and product catalog attributes. These correlations enable Einstein to effectively promote or demote product recommendations for shoppers.

You set up this mapping in the Einstein Configurator Rules tab for each recommender.

![Shopper Profile Rules](https://developer.salesforce.com/media/commerce-einstein-api/shopper_profile_rules.png)

## Before You Begin

Before attempting to configure any shopper profile rules, make sure to complete the following:

1. Add Client IDs for access to the B2C Commerce Einstein API. Using this API does not require using the Einstein Recommendations API. Use it with the Einstein Recommendations API, or use this API along with a traditional B2C Commerce storefront implementation.

   ![Add Client ID](https://developer.salesforce.com/media/commerce-einstein-api/add_client_id.png)

2. Make sure that Einstein has access to shopper profile data through the Profile Connector API. Shopper profile data access is accomplished through either bulk upload or by using real-time updateProfile activity tracking.

   **note:** It can take up to an hour for our system to reflect changes made from bulk uploading data.

After you complete these steps, an Add Shopper Profile Rule button appears on the Einstein Configurator Rules tab for each supporting recommender.

![Add Shopper Profile Rule](https://developer.salesforce.com/media/commerce-einstein-api/add_shopper_profile_rule.png)

## Limitations of Shopper Profile Rules Setup

When configuring shopper profile rules, keep these limitations in mind:

- Configure a maximum of 15 shopper profile rules for each recommender.
- Specify only promote or demote actions for a shopper profile rule.

## Rule Configuration Examples

Here are a few scenarios and examples to help you get started defining shopper profile rules.

**note:** All field names and values were created at random.

### Example 1

**Scenario:** You want to promote women's clothing to shoppers with an attribute of `female`. The product attribute (womens) doesn't match the shopper attribute (female). To map the two values, create a profile rule.

This example shows how to create a rule to promote products in the Womens Pants & Shorts `classification_category` to shoppers with a gender value of `female`.

![Rule Example 1](https://developer.salesforce.com/media/commerce-einstein-api/rule_example_1.png)

### Example 2

**Scenario:** You want to promote a brand to shoppers who have a number of profile values that match values associated with that brand.

**note:** Data is case sensitive. For values to match, they must also match in case format.

This example creates a rule to promote products with brand values that match values in the shopper profile `brand_list`.

**note:** Use the Match Shopper value only when the majority of product values match the shopper profile values.

![Rule Example 2](https://developer.salesforce.com/media/commerce-einstein-api/rule_example_2.png)

<!-- document id=a4df5bc3c06d5329d2d807348cedf5d77c0a1ce8c0166f284a0da94a2b4dea18 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-routing-bm.md -->

# Configure Routing Rules in Business Manager

For vanity or custom domains, configure routing rules in the embedded content delivery network (eCDN) to route traffic to a Managed Runtime (MRT) environment. For default domains, you don't need to configure routing rules.

## Default Routing Rules for Default Domains

When you create Storefront Next in Business Manager, the storefront is automatically configured with eCDN, a default domain, and a default routing rule. The routing rule for default domains directs traffic from the storefront’s default domain, `*.my.cc.salesforce.com`, to the MRT origin domain, `*.exp-delivery.com`. The MRT origin is no longer directly accessible and is accessed via eCDN. This change ensures that all MRT traffic flows through eCDN, applying WAF rules, rate limits, and observability consistently across vanity and default domains.

View your default routing rule in your storefront in Business Manager by clicking the environment, and then clicking **Manage in Embedded CDN Settings**.

![Find a project in Runtime Admin](https://developer.salesforce.com/docs/media/sfnext/sfnext-ecdn-routing-default.png)

For more information about default domains and zones, see [Default Domain Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_default_domain.htm&type=5) in _Salesforce Help_.

### Origin Rule for DIS Traffic Bypassing MRT

Your storefront has a default MRT routing rule that bypasses MRT for image and static content. When using Dynamic Image Service (DIS) and serving image and static content from B2C Commerce, certain request paths must reach the B2C Commerce origin directly instead of routing through Managed Runtime (MRT). This bypass makes sure that image transformations, static assets, and dynamic controllers function correctly and don’t reach MRT because MRT doesn’t host storefront images.

These B2C Commerce request paths must bypass MRT and reach the B2C Commerce origin:

- `/on/demandware.static/*`: Raw static assets (CSS, JavaScript, fonts, and so on)
- `/on/demandware.image/*`: Product image transformations via DIS
- `/on/demandware.store/*`: Dynamic B2C Commerce controllers

In your existing origin rule configuration, make sure that it accounts for all these paths and uses this format:

```
http.request.uri.path matches "^/on/demandware\.(static|image|store)/.*"
```

### View the Storefront's Routing Rule

To access your storefront's routing rule in Business Manager:

1. Access the embedded CDN settings pages in one of these ways.

   a. Go to **Administration > Storefronts**, click you storefront and then the environment, and then click **Manage in Embedded CDN Settings** from your storefront's environment page.

   b. Go to **Administration > Sites > Embedded CDN Settings**.

2. The page shows the default zone. Click the caret dropdown to the right of the zone, and then select **Configure Routing Rules**.
3. Filter the rules list to find your hostname. Expand the routing rule for your hostname.
   The rule shows the hostname and the MRT origin.

   ![The eCDN routing rule in Business Manager showing the hostname and MRT origin](https://developer.salesforce.com/docs/media/sfnext/sfnext-ecdn-routing-rule.png)

## Custom Routing Rules for Vanity or Custom Domains

To route traffic to a Managed Runtime (MRT) environment for vanity or custom domains, configure eCDN routing rules. Business Manager speeds up CDN setup with an intuitive UI and simplifies deployment processes. Use Business Manager to view, create, edit, or delete routing rules for zones in a Storefront Next site or [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid.md).

**note:** As an alternative to the Business Manager steps covered in this section, use the [createCustomRule API](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createCustomRule) CDN API to route traffic programmatically.

### Prerequisites

Before you configure routing rules:

- Define your hostnames in the alias file. To do so, in Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Merchant Tools > _Your Site_ > SEO > Aliases**.
- Find the zone ID of the eCDN zone to be used with Managed Runtime. To find the zone ID, use the [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo) endpoint of the CDN Zones API.
- Complete the steps under [Before You Begin](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-launch-storefront.md#before-you-begin).

## Considerations

Keep these points in mind when creating a rule expression:

- Include one expression per rule.
- You can set up all paths or specific paths for a particular hostname to be forwarded to MRT.
- When you create or edit a routing rule, if you don’t provide paths in a rule expression and you select only a hostname, all traffic is routed to MRT.
- The structure of the rule expression differs slightly when creating rules using Business Manager instead of the CDN API. When you configure rules in Business Manager, leave the http.host field out of the rule expression. You select the hostnames separately on the page, and they’re automatically prepended to the rule expression during rule creation. Requests are directed to your specified MRT origin.
- If you provide a single path, the path condition is combined with the host condition using an "AND" operator. This means that both the host and the path conditions must be true for the rule to take effect.
- When you provide multiple paths using an "OR" operator, if any of the specified paths match, the rule takes effect.

In this example, the rule applies if the URL path starts with either `/products` or `/be/fr/home-page` followed by any number of characters.

`http.request.uri.path matches "^/products" or http.request.uri.path matches "^/be/fr/home-page.*"`

## Create a Routing Rule for a Custom Domain

**note:** Routing rules are configured per **zone**.

To route traffic to a Managed Runtime environment for a custom domain, create a routing rule.

1. Go to **Administration > Sites > Embedded CDN Settings**.
2. Click the caret dropdown to the right of the zone and then select **Configure Routing Rules**.
3. On the Configure Routing Rules page, click **New Rule**.
4. Fill out the required input fields. See the tooltips for information about each field.
5. (Optional) A few rule templates are available to help you get started. They provide a foundation for building rule expressions based on your specific use case. For some key points that apply to rule expressions, see [Considerations](#considerations).

To route all traffic to MRT:

- On the Rule Template list, select **Recommended Fully Composable**.
- Leave the Rule Expression field blank.

To route only specific paths to MRT.

- On the Rule Template list, make a selection.
- In the Rule Expression field, enter specific paths to route to MRT.

![Associated screenshot](https://developer.salesforce.com/docs/media/sfnext/route-specific-traffic.png)

1. Click **Save**.
2. When the confirmation message appears, click **Save** again to create the rule.

The new rule displays on the Configure Routing Rules page.

## See Also

- [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html)
- [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-launch-storefront.md)

<!-- document id=ff2f4a59a14b4bb2b62486c80541d5044b7886342ca1ba2ba8c4904e02462649 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-salesforce-payments.md -->

# Configure Salesforce Payments for Storefront Next

Salesforce Payments streamlines the checkout experience for shoppers in Storefront Next for B2C Commerce. Salesforce Payments is a native solution that supports multiple payment methods and payment gateways, such as Adyen, Stripe, and PayPal.

## Set Up Salesforce Payments for Storefront Next

### Prerequisites

- Purchase a Salesforce Payments license by contacting your Salesforce account executive.
- Set up Storefront Next.
  To create a storefront with a GitHub repository, see [Create a Storefront in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md). To create a storefront with local code, see [Create a Storefront in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md).
- In Business Manager, install the Salesforce Payments Commerce App. See [Install a Commerce App for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_install_commerce_app.htm).

### Steps

1. Configure your payment gateway in Business Manager.
   Salesforce Payments behavior on your storefront depends on the gateway configuration. To configure:

   - Adyen, see [Configure Salesforce Payments with Adyen for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_salesforce_payments_with_adyen.htm)
   - Stripe, see [Configure Salesforce Payments with Stripe for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_salesforce_payments_with_stripe.htm)
   - PayPal, see [Configure Salesforce Payments with PayPal for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_salesforce_payments_with_paypal.htm)

2. In `src/types/config.ts`, under `AppConfig`, add the type definition for the Salesforce Payments configuration.

```
// Salesforce Payments (sf-payments extension) configuration.
//   `sdkUrl` is read client-side by using `useConfig()` and gates the SDK download.
//   `metadataUrl` is read server-side by using `getConfig(context)` by the metadata proxy route.

sfPayments?: {
    sdkUrl: string;
    metadataUrl: string;
};
```

3. In `config.server.ts`, set `sdkUrl` and `metadataUrl` to point to your B2C Commerce instance host by replacing `[bm_or_vanity_host]` with your Business Manager or vanity URL host.

```
// Salesforce Payments configuration
// Set `sdkUrl` and `metadataUrl` to point to your B2C Commerce instance host by replacing `[bm_or_vanity_host]` with your Business Manager or vanity URL host name.
//
//   sdkUrl:      https://[bm_or_vanity_host]/on/demandware.static/Sites-Site/-/-/internal/jscript/sfp/v1/sfp.js
//   metadataUrl: https://[bm_or_vanity_host]/on/demandware.static/Sites-Site/-/-/internal/metadata/v1.json

sfPayments: {
 sdkUrl: '',
 metadataUrl: ''
}
```

4. (Optional) In `config.server.ts`, switch to a private client.
   Salesforce Payments doesn't require a private client. By default, `privateKeyEnabled` is set to `false`. Only change this setting if another feature in your storefront requires it. If another feature depends on a private client to function, make that feature optional or turn it off.

   a. Set `commerce.api.privateKeyEnabled` to `true`.

   b. Set `COMMERCE_API_SLAS_SECRET` in your environment.

5. In `config.server.ts`, configure Content Security Policy (CSP) directives.

   a. To support the CSP directives that Salesforce Payments requires, import the default CSP directives object.

   ```
   import { defaultCspDirectives } from '@salesforce/storefront-next-runtime/security';
   ```

   b. Expand the CSP directives object to include the directives that Salesforce Payments requires.

   ```
   csp: {
       directives: {
           ...defaultCspDirectives,
           'script-src': [
               ...defaultCspDirectives['script-src']!,
               'https://*.demandware.net',
               'https://*.sfdc.cl',
               'https://js.stripe.com',
               'https://maps.googleapis.com',
               'https://*.adyen.com',
               'https://pay.google.com',
               'https://www.paypal.com',
               'https://www.paypalobjects.com',
           ],
           'style-src': [
               ...(defaultCspDirectives['style-src'] ?? []),
               'https://*.adyen.com',
           ],
           'img-src': [
               ...defaultCspDirectives['img-src']!,
               'https://*.adyen.com',
               'https://www.gstatic.com',
               'https://pay.google.com',
               'https://www.paypal.com',
               'https://www.paypalobjects.com',
           ],
           'frame-src': [
               ...defaultCspDirectives['frame-src']!,
               'https://js.stripe.com',
               'https://hooks.stripe.com',
               'https://*.adyen.com',
               'https://pay.google.com',
               'https://www.paypal.com',
               'https://www.sandbox.paypal.com',
           ],
           'connect-src': [
               ...defaultCspDirectives['connect-src']!,
               'https://*.sfdc.cl',
               'https://api.stripe.com',
               'https://*.adyen.com',
               'https://pay.google.com',
               'https://google.com',
               'https://www.google.com',
               'https://www.paypal.com',
               'https://www.sandbox.paypal.com',
               'https://*.paypal.com',
               'ws://localhost:*',
           ],
       },
       reportOnly: false,
   },
   ```

6. (Optional) To use Salesforce Payments outside of the US and Canada, configure Salesforce Payments for other countries.

   a. In `src/components/customer-address-form/constants.ts`, add the country code to the `COUNTRY_CODES` constant.

   ```
   export const COUNTRY_CODES: readonly CountryCode[] = ['US', 'CA', 'GB'] as const;
   ```

   b. In the locale translations file for that country, for example `src/locales/en-GB/translations.json`, add the provinces or states for the locale.

   ```
   "GB": {
       "name": "United Kingdom",
       "states": {
           "ENG": "England",
           "SCT": "Scotland",
           "WLS": "Wales",
           "NIR": "Northern Ireland"
       }
   }
   ```

**note:** Storefront Next doesn't require eCDN setup for Salesforce Payments. The eCDN routing rules for Storefront Next include `/resource/*` by default, alongside other Storefront Next infrastructure paths, such as `/action/*`, `/mobify/*`, and `*.data`. This setup applies even if you configure a vanity domain for Business Manager within the eCDN zone.

<!-- document id=9104ef70098bfec7d016cc44096ef2e8735681d5cdc406851ecf5817e7479b2f url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/salesforce-payments.md -->

# Configure Salesforce Payments for Your B2C Commerce Composable Storefronts

Salesforce Payments streamlines the checkout experience for shoppers in your B2C Commerce Composable Storefronts. Salesforce Payments is a native solution that supports multiple payment methods and payment gateways such as Adyen, Stripe, and PayPal.

Set up Salesforce Payments for B2C Commerce Composable Storefronts.

1. If your PWA Kit isn’t version 3.17 or later, [Upgrade to v3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.html).
2. If you configured a vanity domain within an eCDN zone, redirect the PWA Kit endpoint `(/api/metadata)` to a B2C Commerce instance static asset that’s respected by an eCDN.

   See [Configure MRT Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-mrt-routing-bm.html).

   a. In Business Manager, click App Launcher, and then select **Administration** | **Sites** | **Embedded CDN Settings**.

   b. Locate the zone that you want to view.

   c. Click on the caret dropdown to the right of the zone.

   d. Select **Configure Routing Rules**.

   e. Locate the rule that you want to edit.

   f. Click **Edit**.

   g. To allow the CDN to route the vanity domain to specific instances, in the Rule Expression section, add `/api*` to the routes.

3. In your default.js file, update the Salesforce Payments configuration.

   a. Set Salesforce Payments to `true`.

   b. Set the sdkUrl and metadataUrl values to point to your B2C Commerce instance host by replacing the [bm_or_vanity_host] placeholder with your Business Manager or vanity URL host.

   ```
   // Salesforce Payments configuration
   // To enable Salesforce Payments in a Composable storefront, set Salesforce Payments to true (Salesforce Payments must also be enabled in the B2C Commerce instance).
   // To disable Salesforce Payments in a Composable storefront, set Salesforce Payments to false(Salesforce Payments in the B2C Commerce instance is unaffected).
   // Set the sdkUrl and metadataUrl values to point to your B2C Commerce instance host by replacing the [bm_or_vanity_host] placeholder with your Business Manager or vanity URL host name.
   //
   //   sdkUrl:      https://[bm_or_vanity_host]/on/demandware.static/Sites-Site/-/-/internal/jscript/sfp/v1/sfp.js
   //   metadataUrl: https://[bm_or_vanity_host]/on/demandware.static/Sites-Site/-/-/internal/metadata/v1.json

   sfPayments: {
     enabled: false,
     sdkUrl: '',
     metadataUrl: ''
   }
   ```

4. To ship to countries outside of the U.S. and Canada, update the constants.js file.

   ```
    // add the local and labels to this array.

    export const SHIPPING_COUNTRY_CODES = [
    {value: 'DE', label: 'Germany'},
    {value: 'GB', label: 'United Kingdom'},
    ]
   ```

5. To test Salesforce Payments for Composable Storefronts in a development instance before setting it up in your Managed Runtime (MRT) project, set up the development instance.

   When you run a Composable storefront in a development instance, only HTTP is supported. Salesforce Payments requires HTTPs.

   a. Create a self-signed certificate (for example, `localhost.pem`) and place it in the project root.

   b. In the package.json file, add a development script.

   ```
   "start:https": "cross-env NODE_TLS_REJECT_UNAUTHORIZED=0
   NODE_ICU_DATA=node_modules/full-icu DEV_SERVER_PROTOCOL=https
   DEV_SERVER_SSL_FILE_PATH=localhost.pem pwa-kit-dev start"
   ```

   c. To start the Composable Storefront in a developer instance using HTTPS, use `npm run start:https` to run the application.

   This setup is required for some payment methods.

6. Set up Apple Pay methods.

   a. For Apple Pay to work with Stripe, register MRT domains on the Stripe Dashboard.

   b. For Apple Pay to work with Adyen, register MRT domains.

7. To set up Salesforce Payments for new Composable Storefronts, complete these steps.

   New storefronts have the latest Content Security Policy (CSP) configuration.

   a. To configure Salesforce Payments with a SLAS private client, in your SSR.js file, set these values.

   You can configure Salesforce Payments with a public or a private client. By default, Salesforce Payments is configured with a public client. For more information, see [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html#configure-the-pwa-kit).
   - In `packages/template-retail-react-app/app/components/_app-config/index.jsx`, set `enablePWAKitPrivateClient={true}`.

   - In `packages/template-retail-react-app/ssr.js`:
     - Set `useSLASPrivateClient:true`.
     - Uncomment `applySLASPrivateClientToEndpoints`.

8. To set up Salesforce Payments for existing Composable Storefronts, complete these steps.

   a. In your ssr.js file, update the content security policy with these directories.

   Google Pay may require additional endpoints depending on the integration. You can adjust the values as needed for your instance.

   ```
   'img-src': [
       '.commercecloud.salesforce.com',
       '.demandware.net',
       '*.adyen.com',
       'pay.google.com',
       'www.gstatic.com‘
   ]
   'script-src': [
       'storage.googleapis.com',
       'maps.googleapis.com',
       'places.googleapis.com',
       '*.stripe.com',
       '*.paypal.com',
       '*.adyen.com',
       'pay.google.com',
       'www.gstatic.com',
       '*.demandware.net'
   ]
   'connect-src': [
       'api.cquotient.com',
       '*.c360a.salesforce.com',
       'maps.googleapis.com',
       'places.googleapis.com',
       '*.salesforce-scrt.com',
       '*.demandware.net',
       '*.adyen.com',
       '*.paypal.com',
       'pay.google.com',
       'payments.google.com',
       'google.com/pay',
       'google.com/pay/',
       'www.google.com/pay',
       'www.google.com/pay/'
   ]
   'frame-src': [
       '*.site.com',
       '*.stripe.com',
       '*.paypal.com',
       '*.adyen.com',
       'payments.google.com',
       'pay.google.com'
   ]
   ```

   b. To read metadata from the B2C Commerce instance, add this code to the top of the import before `app.get('*', runtime.render)`.

   ```
   function transformIconPaths(data, ecomServerHost) {
   const baseUrl = `https://${ecomServerHost}/on/demandware.static/Sites-Site/-/-/internal`
   const methodTypes = data?.paymentMethodTypes

   if (methodTypes) {
       for (const method of Object.values(methodTypes)) {
           for (const image of method.images ?? []) {
               if (image.src?.startsWith('/icons/')) {
                   image.src = `${baseUrl}${image.src}`
               }
           }
       }
   }
       return data
   }
   app.get('/api/payment-metadata', async (req, res) => {
   try {
       const response = await fetch(config.app.sfPayments.metadataUrl, {
           headers: {Accept: 'application/json'}
       })
       if (!response.ok) {
           throw new Error(`Metadata request failed with status: ${response.status}`)
       }
       const data = await response.json()
       const transformedData = transformIconPaths(
           data,
           new URL(config.app.sfPayments.metadataUrl).hostname
       )
       res.setHeader('Content-Type', 'application/json')
       res.json(transformedData)
   } catch (error) {
       res.status(500).json({
           error: 'Failed to fetch metadata',
           details: error.message
           })
       }
   })
   ```

<!-- document id=7ffaf21c15c637fac610b00054029df9c4de3ae1b6ce14bf1d3a2fe507d5a939 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-configuring-sfra.md -->

# Configure SFRA

After you've built and pushed your code to your instance, configure your application in Business Manager and in your browser.

## Configure the SFRA Cartridge Path

Before you can use the contents of a cartridge, upload the cartridge to the server and register the cartridge with the server. In Business Manager, register cartridges to a site. By registering cartridges, you make the cartridges available. Cartridges can be shared among sites.

1.  Select **Administration** > **Sites** > **Manage Sites** > **site**.

2.  Click the **Settings** tab.

3.  In the Cartridges field, enter a colon-separated list of cartridge names. Cartridges at the beginning of the list (at the left) take precedence over cartridges at the end of the path (at the right).

    - An SFRA storefront cartridge path can contain the following cartridges:

      ```
      plugin_applepay: app_storefront_base
      ```

    - A custom storefront cartridge path can contain the following cartridges:

      ```
      app_custom_*mybrand*: plugin_applepay: app_storefront_base
      ```

4.  Click **Apply**.

## Import SFRA Data into an Instance

To view products in Storefront Reference Architecture (SFRA) storefront sites, import the standard SFRA data. This data includes product information and images.

It's safe to import SFRA into an empty sandbox. However, if you also want to import custom sites, make sure that you import SFRA first before importing the custom sites. By importing SFRA first and then importing your custom site, you make sure that custom attributes for your custom sites are retained if there are conflicts. Your custom attributes overwrite any imported SFRA custom attributes. If the SFRA custom attributes are overwritten, you risk changing the SFRA site’s behavior, but your custom attribute data is retained.

**note:** Do not import SFRA data into an instance in your Primary Instance Group (PIG).

**warning:** If you import SFRA into an instance that contains other customized sites, you risk overwriting existing attributes and losing data.

1.  Zip up the repository data.

    If you are performing this step on a Mac, don't use the Mac OS archive utility. Instead, zip up the repository from the command line. Files compressed using the MacOS archive utility cause errors on import.

2.  Select **Administration** > **Site Development** > **Site Import & Export**.

3.  In the Import section, select **Local** to upload the site .zip file from your local machine.

4.  Click **Browse**, select the .zip file you want to upload, and click **Open**

    The name of the .zip file appears in the grid.

5.  In the Select column, select the .zip file and click **Import**.

6.  Click **OK** to import the selected archive.

## Configure Site URL

We recommend using standard Salesforce B2C Commerce URL syntax in the early phases of development.

1.  Select **_site_** > **Merchant Tools** > **Site Preference** > **Storefront URL**.

2.  On the Storefront URL Preferences page, make sure the **Enable Storefront URLs** option isn't selected.

    Now you can enter a URL such as `https://localhost/on/demandware.store/Sites-RefArch-Site/default/Hello-World` directly in your browser to test new controllers. Make sure cookies are enabled in your browser.

## Configure Storefront Preferences for SFRA

Select the instance type and other preferences for SFRA.

1.  Select **_site_** > **Merchant Tools** > **Site Preferences** > **Custom Preferences** > **Storefront Configuration**.

2.  On the Custom Site Preferences page, select the instance type (if you are changing the type).

    The instance type is applied immediately. Some Business Manager modules have settings that are specific to a selected instance type. The instance types are:

    - Sandbox / Development
    - Staging
    - Production

3.  Enter the tag that is used by the storefront application as a Google verification tag.

    Google uses this tag to verify the site.

4.  Enter the email addresses to be sent the build notifications, separated by a semicolon.

    Send email notification to one or more email addresses when a new build is available.

5.  Enter the default list price book ID to be used by the storefront.

6.  To save your changes, click **Apply**.

<!-- document id=962352052ff40934fa448f1bfd4098310ab5aca158a624432ac3bdd5722183db url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/configure-the-commerce-client.md -->

# Configure the Agentforce Commerce Client

Both the React component and the CDN injection function accept the same configuration object, `CopilotWidgetProps`. This topic describes the properties you're most likely to set.

Styling and theming properties (`theme`, `headerConfig`, `suggestionButtonConfig`, `searchConfig`, and `globalClassName`) are covered in [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md). Component-override properties (`overrides`, `overridesUrl`, `inlineOverrides`) are covered in [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md).

## Connection

The widget connects through `messagingConfig`, which is required. It configures the Agentforce SCRT2 connection.

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `scrt2Url` | `string` | Yes | SCRT2 messaging endpoint URL. |
| `orgId` | `string` | Yes | The 18-character ID of the Salesforce org that hosts your Agentforce agent, not your B2C Commerce instance or realm ID. |
| `esDeveloperName` | `string` | Yes | Embedded Service messaging channel developer name. |
| `routingAttributes` | `Record<string, string>` | No | Pre-chat routing attributes passed to the channel. |
| `capabilitiesVersion` | `string` | No | Capabilities version for the SCRT2 token request. Set to `"63"` or higher (release 254) to receive action progress-indicator messages. |
| `enableDownloadTranscript` | `boolean` | No | Show a transcript-download control. Requires the org's messaging channel to allow transcript download. Defaults to `true`. |
| `enableEscalationToAgent` | `boolean` | No | Show an escalate-to-agent control. Requires the Agentforce agent to be configured with an escalation path; otherwise, the button is a no-op. Defaults to `false`. |
| `showProductCaptions` | `boolean` | No | Show captions on product cards. |
| `progressStepsLimit` | `number` | No | Maximum number of progress steps shown in the chat window. When the list grows past the limit, only the most recent steps are shown. |
| `onProductResult` | `(detail: ProductResultDetail) => void` | No | Called whenever a finalized agent message carries a product result, from either a product search or a product-details lookup. See [Observe product results](#observe-product-results). |

## Content and behavior

| Property | Type | Notes |
| --- | --- | --- |
| `disclaimerText` | `string` | Plain-text disclaimer shown in the widget. |
| `disclaimerMarkdown` | `string` | Markdown disclaimer, as an alternative to `disclaimerText`. |
| `openLinksInNewTab` | `boolean` | Open links from the widget in a new tab. |
| `showProductDescription` | `boolean` | Show product descriptions in product displays. |
| `autoScroll` | `boolean` | Auto-scroll to the latest message. Defaults to `true`. |
| `messageAlignment` | `"start" \| "end"` | Alignment of the message list. Defaults to `"start"`. |
| `conversationHistory` | `{ sinceHours?: number; limit?: number }` | Bounds how much prior conversation the widget loads. |
| `promptsConfig` | `PromptsExtensionConfig` | Configures the prompts extension. See [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md). |
| `isDevelopment` | `boolean` | Enables development logging. |

## Component presentation

The `componentConfig` object controls how the widget presents itself (as inline chat, a floating dialog, or a modal) and its open state.

| Field | Type | Notes |
| --- | --- | --- |
| `type` | `"chat" \| "dialog" \| "modal"` | Presentation form. |
| `isOpen` | `boolean` | Whether the widget starts open. |
| `isMinimized` | `boolean` | Whether the widget starts minimized. |
| `enableMinimize` | `boolean` | Allow the shopper to minimize the widget. |
| `options.dialogPosition` | `DialogPosition` | Dialog anchor position, such as `"bottom-right"`. |
| `options.dialogFullHeight` | `boolean` | Make the dialog full height. |
| `options.dialogWidth` | `string` | Dialog width. |
| `options.isModalFullscreen` | `boolean` | Make the modal fullscreen. |

## Observe product results

Set `messagingConfig.onProductResult` to react when the agent returns products. The widget calls it whenever a finalized agent message carries a product result, from either a product search or a product-details lookup, so your storefront can sync its own UI (for example, highlight the returned products on the page).

The callback receives a `ProductResultDetail`:

| Field | Type | Notes |
| --- | --- | --- |
| `agentSessionId` | `string` | The Agentforce session the result belongs to. |
| `kind` | `"search" \| "detail"` | Whether the result came from a product search or a product-details lookup. |
| `productIds` | `string[]` | The product IDs the agent returned. |

messagingConfig: {
  scrt2Url: "https://your-org.my.salesforce-scrt.com",
  orgId: "00Dxx0000000000",
  esDeveloperName: "Your_Messaging_Channel",
  onProductResult: (detail) => {
    if (detail.kind === "search") {
      // Sync your storefront UI to the products the agent surfaced.
    }
  },
}
```

## Observe widget state

The widget also reports UI state changes as a browser `CustomEvent` on `window`, so a storefront can react to them from plain JavaScript without importing anything. The widget dispatches the `cimulate:ui-state-update` event whenever a tracked piece of state changes, such as the connection status or the widget's open, minimized, presentation, or entry-type state.

Each event carries a `detail` object of `{ property, value }`, where `property` names what changed (for example, `"connected"`, `"isOpen"`, `"isMinimized"`, `"type"`, or `"entryType"`) and `value` is the new value.

```html
<script>
  window.addEventListener("cimulate:ui-state-update", (event) => {
    const { property, value } = event.detail;
    if (property === "isOpen") {
      // Sync your storefront UI to the widget's open state.
    }
  });
</script>
```

## Control the widget from your storefront

The CDN global `window.CimulateMessaging` exposes an `eventHandlers.components` object your storefront can call to control the widget after it's injected. The most common use is a storefront-owned launcher: Render your own button (for example, an "Ask AI" entry point in your search suggestions) and open the widget when the shopper selects it.

```html
<div id="messaging-widget"></div>

<!-- Storefront-owned launcher: style and position this button yourself. -->
<button type="button" onclick="openShopperAgent()">Ask AI</button>

<script>
  function openShopperAgent() {
    // Pass true to force open, false to force close, or omit to toggle.
    window.CimulateMessaging?.eventHandlers.components.toggleWidgetOpen(true);
  }
</script>
```

These control methods are available on `eventHandlers.components`:

| Method | Notes |
| --- | --- |
| `toggleWidgetOpen(isOpen?)` | Open or close the widget. Pass `true` to force open, `false` to force close, or omit to toggle. Opening also restores the widget if it's minimized. |
| `toggleWidgetMinimized(isMinimized?)` | Minimize or restore the widget. Pass a boolean to force a state, or omit to toggle. Minimizing also closes the widget. |
| `setWidgetType(type)` | Switch the presentation form: `"chat"`, `"dialog"`, or `"modal"`. |
| `setWidgetDialogPosition(position)` | Set the dialog anchor position, such as `"bottom-right"`. |
| `toggleModalFullscreen(isFullscreen)` | Switch the modal's fullscreen state on or off. |

:::note
The top-level SDK doesn't expose a method to send a search utterance or message on the shopper's behalf. Your launcher can open the widget, but the shopper starts the conversation from there. Component overrides are the exception: An override's `api.sendMessage` can send a message from within a rendered slot. See [Component Override SDK](component-override-sdk.md).
:::

## Related resources

- [Install the Agentforce Commerce Client](install-the-commerce-client.md)
- [Style and Theme the Widget](style-and-theme-the-widget.md)
- [Component Override SDK](component-override-sdk.md)

<!-- document id=3bc89198bb4d11509e83b584f74af9ba31092d450e3ece498bcef0bc654e7451 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-activities/confirm-activities.md -->

# Confirm Activities

Sending activities tracking data to the Einstein engine provides insights into how customers interact with your site. When implementing the Einstein Activities API, confirm that you’re making the API calls to send each activity when events occur. See `Specification - Endpoints - Activities` for details on the API calls.

When the API successfully sends activities, the API call returns a `200 - OK` status response code. In addition, to confirm the receipt and processing of activities, check the API page activity health status dashboard in the Einstein Configurator. If Einstein receives an activity 5 times or more in the last 7 days, that activity is marked as healthy. The system marks fewer than 5 received activities as unhealthy, or indicates when no activities are received at all.

**important:** Individual activities don’t always appear as independent data events. Instead, Einstein gathers data from every activity, from each page, and uses that data to build a more sophisticated, comprehensive view of each customer session. Activities data typically appears within 48 hours in the Einstein dashboard tab in the Reports and Dashboards app.

<!-- document id=8dac86cfb038226e26df8578d9ab7f92a0f338b143d7bb2ed316a9b7956c1b8d url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/spi-live-inventory-check.md -->

# Confirm Product Inventory in Point of Sale

Check both in-store and online inventory availability using Point of Sale SPIs.

If you change the cart in the Point of Sale app (for example, adding items, deleting items, changing the number of items, and so on), Point of Sale sends the cart contents to the external system through the SPI. Point of Sale checks the external system for product availability by checking inventory count. If the product isn't available, an error appears and the item isn’t added to the cart.

Point of Sale offers [two additional inventory SPIs](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/inventory-lookup-on-pdp-via-spis.html) that check nearby inventory and get inventory information based on a delivery ZIP code on the Product Detail Page (PDP).

## Set up Point of Sale CMS for Checking Product Inventory

The merchant SPI implementation must provide an endpoint for the POS app to request inventory for the provided products. Configure these endpoints in Point of Sale CMS so that the POS app can perform live inventory checks.

1. Go to **Inventory** | **Inventory Configurations**.

2. Under Provider, select **SPI** and configure the rest of the toggles by referring to [Inventory Configurations](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_modules_inventory_configuration.htm&type=5) in _Salesforce Help_.

3. In CMS, and go to **Store Management** | **Integration** | **Custom Connectors**.

4. Click **Create**.

5. Fill out the fields using this information:

   1. For **API Config** | **API Key**, enter **ONLINE_ITEM_INVENTORY_CHECK**.

   2. For **API Config | API Endpoint**, enter the external endpoint to get the order. For example, `https://sample/external/to/export/return/order/to/external/system`.

   3. For **JSON Config** | **Integration Type**, enter **HTTP_POST**.

   4. For **JSON Config** | **JSON Headers**, enter the API header. Headers can be **Content-Type**, authorization attributes like **clientId/password**. For example, `{"Content-Type":"application/json","client_id":"myClientId","client_secret":"myClientSecret"}`.

6. Confirm that the app configuration settings are turned off:

   1. **HasOnlineInventory** (**App Config | Modules | Settings**)

   2. **HasStoreInventory** (**App Config | Modules | In-Store Fulfillment**)

7. Confirm that the store settings are turned on:

   1. **enable.online.inventory.tracking** (**Store Management | Store Settings | Inventory**)

   2. **check.store.inventory** (**Store Management | Store Settings | Store Fulfillment | BOPIS**)

The next sections include examples of the request and response. In the response, the merchant receives the product ID, the type of inventory check (for example, `ONLINE`), the store ID (optional), and the purpose of the inventory check (for example, `AVAILABILITY`).

## Example SPI Request

The SPI is triggered on the POS app when a user clicks **Add to Cart** for a product or changes the fulfillment type in the cart.

```java
{
  "products": [
    {
      "inventoryAction": "string",
      "inventoryType": "string",
      "productId": "string",
      "storeId": "string"
    }
  ]
}

```

## Example SPI Response

```java
{
  "errorMessage": "string",
  "inventory": [
    {
      "inventoryType": "string",
      "productId": "string",
      "quantity": 0,
      "storeId": "string"
    }
  ]
}

```

<!-- document id=b04afd2d4c3f1a79439353306c38cbf4392d6808d86ce7943acb2cf39fdc41f0 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-connect-gateway.md -->

# Connect a Payment Gateway to Store Checkout

The last steps in implementing payment processing include connecting the payment gateway to checkout in your store.

Set up server- or client-side payment processing. This procedure applies only to custom checkout.

1.  Connect your payment gateway to your checkout using the integrated store service.

    1.  In the navigation sidebar, select a store from the **Store** dropdown.

    2.  Click **Settings | Checkout**, and then click the **Payments** tab.

    3.  Choose the payment service that you want to use.

- To use Salesforce Payments, on the Salesforce Payments tile, click **Configure**. Then, set up the merchant account. If you don’t see a Salesforce Payments tile, contact your Salesforce account executive.
- To use a third-party service, on the Alternate Provider tile, click **Select Provider**. Then, select a gateway provider from a third-party package. If no adapter is listed, get one from AppExchange or create one. Check the listings for a package that supports a B2B or D2C store.
  After you configure your payment service, confirm that your store’s Checkout page is configured correctly. See Customize Payments on a Store Checkout Page.

To integrate a third-party service without using AppExchange, see Reference Implementations for B2B Commerce and Reference Implementations for D2C Commerce. To create a custom package, see Payments Integration in the B2B Commerce Developer Guide.

2.  Test your payment gateway to make sure that it’s working as expected. If you have trouble, check the Payment Gateway logs in your Commerce app. The PaymentGatewayLogs object creates records for every payment attempt and provides information when errors occur.

3.  Publish your store.

<!-- document id=28c7834d23c28708cf91eb42f0561cbd7f057f3d5d3a8dad6135eccdd22c2860 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/connect-third-party-oms.md -->

# Connect a Third-Party Order Management System (OMS)

The OMS domain is a **backend-only** [Commerce App](/docs/commerce/b2c-commerce/guide/commerce-apps-overview.md): you implement `sfcc.app.oms.order.*` extension points so a third-party Order Management System serves current order data through Shopper Orders, Shopper Customers, and UCP order lifecycle updates. Declare `"domain": "oms"` in `commerce-app.json`. For the framework this app builds on, see [Architecture Overview](/docs/commerce/b2c-commerce/guide/architecture.md#the-three-architectures-for-commerce-apps) and [Building Your Commerce App](/docs/commerce/b2c-commerce/guide/building-your-app.md).

## Overview

B2C Commerce is a high-scale **order-taking engine**: it captures orders at peak traffic and is
the point of origin for every order placed on your digital storefronts and channels. After an order is
created, the work of **post-purchase processing** — fulfillment, shipping, cancellations, returns,
refunds — is typically handled by an **Order Management System (OMS)**.

Salesforce offers a tightly integrated OMS (Salesforce Order Management) for exactly this. But you
aren't limited to it: plug in a **third-party OMS** and have it serve order data
through the same integrated surfaces B2C Commerce already exposes — the [**Shopper Orders**](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) and
[**Shopper Customers**](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary) SCAPIs, and the Universal Commerce Protocol (UCP) order lifecycle
updates. The shopper- and agent-facing experience is identical no matter which OMS is behind it.

Connect a third-party OMS so it serves current order data through the same shopper APIs. The standard `GET` endpoints return the order as
it was **created** in B2C Commerce, but carry no real-time data from the integrated OMS. That gap is
closed with the **`expand=oms`** parameter on certain shopper-facing APIs. That parameter loads the current
order data from the OMS. When Salesforce Order Management is integrated, that parameter works automatically.
When you want to integrate a **third-party OMS** instead, the rest of this document describes how.

Build a **Commerce App** whose backend (site) cartridge implements a small set
of server-side **hooks**. When your app registers the hooks and the integration is enabled, the
platform routes order operations to your hooks automatically. Your hooks are responsible for one
thing: talking to your OMS and mapping its data to the platform's order shape. Everything else —
shopper authentication, the access decision, request/response validation, the public API surface —
stays with the platform.

**Nothing changes for API consumers.** Storefronts, the mobile app, and agentic-commerce channels
keep calling the same SCAPI Shopper Orders endpoints. The response shape is identical whether the
data came from the built-in store or your OMS.

### How a Request Flows

![Request flow from a SCAPI expand=oms call through platform authentication, the retrieve hook, access control, and the SCAPI response](https://developer.salesforce.com/media/b2c-commerce/commerce-apps-third-party-oms-request-flow.png)

When a request arrives, **the platform** authenticates the shopper and loads the order from its own
store if it still holds it. It then hands **your hook** an order document — **pre-populated with the
platform's data when the order was found locally, or empty when it was not** — for your hook to
augment. Your hook decides what it needs from the OMS: it can fill in a document the platform left
empty, or enrich a pre-populated one with fields the platform doesn't have (live fulfillment status,
tracking, and so on), and it can skip the OMS call entirely when the platform's data already
suffices. **The platform** then takes over again: it applies access control, and, for a cancel or
return, calls **your** cancel or return hook, which executes the operation against the OMS and
returns the updated order. Finally **the platform** serializes the resulting document as the SCAPI
response.

Your hooks own every interaction with the OMS — enriching order data on reads and executing the
actions on writes; everything around them — authentication, access control, validation, and the
response — is the platform's. Access control, in particular, is only exercised for an order the
platform did **not** already load and access-check itself: an order the platform served from its own
store is already trusted, whereas an order that exists only in the OMS (or one your list hook adds)
is access-checked before it is returned. That check uses a sensible default (the shopper must own the
order), but when it doesn't fit your needs a custom access-control hook can **fully override** it — at
which point the platform steps aside and you own and enforce the access decision yourself.

---

## The Hooks

The integration is made up of two groups of hooks: four **core** hooks that form the integration
itself, and two **optional** hooks you use to refine specific behaviors.

### Core Hooks (Required)

These four are the integration. The platform routes order operations to your OMS only when **all
four** are registered together and the feature toggle is on. If any one is missing, the platform
ignores the others and falls back to its default behavior. Register all four even if some start out
as temporary no-ops during development.

- **`sfcc.app.oms.order.retrieve`** — provides a **single** order. The platform hands you the order
  document — pre-populated when it still holds the order locally, empty when it doesn't — and your
  hook augments it from the OMS: enriching it with data the platform lacks (live fulfillment status,
  tracking, ...) or filling it entirely when the platform had nothing. This is the workhorse of the
  integration: it runs when a shopper views an order, up front on every cancel, return, and
  access-code request, and whenever the platform needs the current order internally — for example to
  assemble an order snapshot for UCP webhook events.
- **`sfcc.app.oms.order.list`** — provides orders belonging to a **single customer** for their order
  history. The platform pre-populates the result with the orders it already holds for that customer,
  and your hook augments the list — typically appending the customer's OMS-only orders. This is the
  only hook that is customer-scoped by nature, and it may need to return a specific subset of orders
  (paging).
- **`sfcc.app.oms.order.cancel`** — cancels a whole order in your OMS. The platform calls it after
  it has loaded the order and confirmed the shopper is allowed to cancel it.
- **`sfcc.app.oms.order.return`** — starts a return for specific order items, called under the same
  post-access-check conditions as cancel.

### Optional Hooks

Both of these are independent — register only the ones you need; they don't affect whether the
integration is active.

- **`sfcc.app.oms.order.accessControl`** — overrides the platform's default ownership decision.
  Register it only when "does this shopper own this order?" can't be answered by matching the
  platform customer ID (for example, when your OMS uses a different customer identifier and you
  manage it via custom attributes on the customer profile). It runs after
  a retrieve and fully replaces the default check.
- **`sfcc.app.oms.order.reasonCodes`** — supplies the cancel and return reason codes your OMS
  accepts. The platform uses them both to serve the `oms-meta-data` endpoint (so the storefront can
  render a reason picker) and to validate a submitted reason.

**note:** **Reference:** The `sfcc.app.oms.order.*` extension points are documented with full contract details, parameter types, and return values in the [B2C Commerce Script API documentation](https://salesforcecommercecloud.github.io/b2c-dev-doc/).

---

## Prerequisites

- A Commerce App whose `commerce-app.json` declares `"domain": "oms"`, with a **backend (site) cartridge**. See [commerce-app.json Schema](/docs/commerce/b2c-commerce/guide/reference.md#commerce-appjson-schema) and [Packaging Your Commerce App](/docs/commerce/b2c-commerce/guide/packaging.md).
- The app **installed** on the site. App-specific extension points (`sfcc.app.*`) run only through Commerce App install—you can't invoke them from a cartridge that isn't part of an installed app. See [Building Your Commerce App — Extension Points](/docs/commerce/b2c-commerce/guide/building-your-app.md#extension-points).
- Your OMS reachable from hook scripts—typically through an HTTP service you define in the same cartridge (`dw.svc.LocalServiceRegistry`).

---

## Enabling the Integration

The integration is active for a site only when **both** of these are true:

1. The **OMS App Hooks** feature switch is **on**. This is a platform kill switch, **not a
   merchant-facing setting**, and it is **enabled by default** — so you normally don't need to touch
   it. For reference, it lives in Business Manager under **Administration > Feature Switches**,
   labeled **"Enable OMS App Hooks (sfcc.app.order.\*)"** in the **Commerce Apps** group section
   (internal name `OmsAppHooksEnabled`).
2. All **four core hooks** are registered:
   `sfcc.app.oms.order.retrieve`, `sfcc.app.oms.order.list`,
   `sfcc.app.oms.order.cancel`, and `sfcc.app.oms.order.return`.

This is **all-or-nothing**: if any of the four is missing, the platform doesn't route order
operations to your app and falls back to its default behavior. Register all four even if some are
temporary no-ops during development.

**note:** **Triggering the hook on reads.** For `getOrder` and `getCustomerOrders`, the storefront request
must include the query parameter **`expand=oms`** to route to your retrieve hooks. Without it, the
platform serves the request from its own order store as usual.

---

## Step 1 — Register the Hooks

Register the four core `sfcc.app.oms.order.*` extension points in the site cartridge's `hooks.json`, and point `package.json` at it. This is the same registration pattern as other backend-only domains (for example, Tax). The following JSON is what the app registers. Install still goes through the Commerce App package, not a standalone cartridge-path hook. See [Building Your Commerce App — Extension Points](/docs/commerce/b2c-commerce/guide/building-your-app.md#extension-points).

```json
// hooks.json
{
  "hooks": [
    { "name": "sfcc.app.oms.order.retrieve", "script": "./oms/retrieve.js" },
    { "name": "sfcc.app.oms.order.list", "script": "./oms/listOrders.js" },
    { "name": "sfcc.app.oms.order.cancel", "script": "./oms/cancel.js" },
    { "name": "sfcc.app.oms.order.return", "script": "./oms/return.js" }
  ]
}
```

```json
// package.json
{ "hooks": "./hooks.json" }
```

Add optional hooks as extra entries:

```json
({ "name": "sfcc.app.oms.order.accessControl", "script": "./oms/accessControl.js" },
{ "name": "sfcc.app.oms.order.reasonCodes", "script": "./oms/reasonCodes.js" })
```

---

## Step 2 — Implement the Hooks

Each hook takes two arguments — an **input** and an **order document** to work with — and returns a
`dw.system.Status`. For most hooks the input is a purpose-built **context** object (for example
`OmsOrderContext`, carrying `siteId` and `orderNo`). The one exception is `accessControl`, whose
first argument is the authenticated shopper as a standard `dw.customer.Customer` object rather than a
context.

The order document is **not always empty**. On the read hooks the platform pre-populates it with the
order it already holds locally, and hands you an empty document only when it has none. Your hook can
therefore either enrich the data already there or fill a blank document — inspect it and add only what
the OMS needs to contribute.

- `new Status(Status.OK)` — success.
- `new Status(Status.ERROR, ...)` — failure. On a single-order retrieve this surfaces as **404**.

**important:** **Always return a `Status`.** A hook that returns nothing is treated as a failure, not a success.

The order documents you populate are Script API work objects. Use **`snake_case`** property
names in your hook (`order_no`, `customer_info`, `product_items`, `tracking_number`). The platform
serializes them to the `camelCase` SCAPI response (`orderNo`, `customerInfo`, `productItems`,
`trackingNumber`) automatically.

### `retrieve` — Provide One Order

Signature: `retrieve(context, orderResponse)`.

The context identifies the order by the combined key **`context.siteId` + `context.orderNo`**. It does
**not** carry a customer id — a retrieve hook is a pure data provider and must not implement its own
ownership logic; the platform handles access control.

`orderResponse` arrives **pre-populated** when the platform still holds the order locally, and empty
when it doesn't. Your hook typically does one of two things:

- **Enrich** an order the platform already loaded — add the post-purchase data the platform doesn't
  have (live fulfillment status, tracking, carrier, delivery dates). Skip the OMS call
  entirely when the platform's data is already enough.
- **Fill** an order the platform no longer holds (empty document) — populate it fully from the OMS.

To detect which case you're in, check whether the document already carries an order number.

```js
"use strict";
var Status = require("dw/system/Status");

function retrieve(context, orderResponse) {
  var alreadyLoaded = !!orderResponse.orderNo; // platform pre-populated it

  var omsOrder = MyOms.getByOrderNo(context.siteId, context.orderNo);

  // Order isn't in the platform AND isn't in the OMS → not found.
  if (!alreadyLoaded && !omsOrder) {
    return new Status(Status.ERROR, "ORDER_NOT_FOUND", "Order not found");
  }

  if (!alreadyLoaded) {
    // Empty document: fill the base order from the OMS.
    orderResponse.orderNo = omsOrder.number;
    orderResponse.status = "open"; // must map to an allowed status enum value
    orderResponse.orderTotal = omsOrder.total;
    orderResponse.currency = omsOrder.currency;
    orderResponse.guest = omsOrder.isGuest;

    // customer_id must be the platform customer id — the default access check compares against it.
    orderResponse.customerInfo = {
      customer_id: omsOrder.platformCustomerId,
      customer_no: omsOrder.customerNo,
      email: omsOrder.email,
    };
    orderResponse.productItems = omsOrder.lines.map(function (l) {
      return {
        product_id: l.sku,
        product_name: l.name,
        quantity: l.qty,
        price: l.price,
        item_id: l.lineId, // stable line id — needed to return specific items
        shipment_id: l.shipmentId, // groups line items; NOT fulfillment/tracking data
      };
    });
    // A full order also carries payment instruments, promotions, gift certificates, taxes, etc.
    // Map whatever your storefront's order experiences need — omitted here for brevity.
  }

  // In both cases, enrich with the live post-purchase data the platform doesn't hold. Put
  // fulfillment/tracking under omsData.shipments — the shipment object that carries tracking
  // links, carrier, and delivery dates. (order.shipments is line-item grouping, not this.)
  if (omsOrder) {
    orderResponse.omsData = {
      shipments: omsOrder.shipments.map(function (s) {
        return {
          id: s.id,
          status: s.status, // e.g. 'shipped', 'delivered'
          tracking_number: s.tracking,
          tracking_url: s.trackingUrl,
          provider: s.carrier,
        };
      }),
    };
  }

  return new Status(Status.OK);
}

exports.retrieve = retrieve;
```

### `order.list` — Provide a Customer's Orders

Signature: `list(context, customerOrdersResponse)`.

This is the one hook that is customer-scoped by nature. The context carries the authenticated
shopper's identifiers and paging/filter inputs:

| Field                            | Notes                                                      |
| -------------------------------- | ---------------------------------------------------------- |
| `context.customerId`             | Platform customer id of the authenticated shopper.         |
| `context.start`, `context.count` | Paging window. Your hook owns pagination against your OMS. |
| `context.from`, `context.until`  | Optional date filters.                                     |
| `context.status`                 | Optional status filter.                                    |
| `context.siteId`                 | The site.                                                  |
| `context.crossSites`             | Whether the request spans sites.                           |

`customerOrdersResponse` arrives **pre-populated** with the orders the platform already holds for
this customer, in its `data` list. Your hook augments that list — typically **appending** the
customer's OMS-only orders rather than replacing what's there. Add **only** orders belonging to
`context.customerId`. The platform trusts the entries it put there and access-checks the ones you
add.

```js
"use strict";
var Status = require("dw/system/Status");

function listOrders(context, customerOrdersResponse) {
  var page = MyOms.getOrdersForCustomer(
    context.customerId,
    context.start,
    context.count,
    context.siteId,
  );

  // Append the OMS orders to whatever the platform already loaded.
  var existing = customerOrdersResponse.data || [];
  var omsOrders = page.orders.map(function (o) {
    return {
      order_no: o.number,
      status: "completed",
      creation_date: o.createdAt, // a java.util.Date
      order_total: o.total,
      currency: o.currency,
      customer_info: { customer_id: o.platformCustomerId, customer_no: o.customerNo },
      product_items: o.lines.map(function (l) {
        return {
          product_id: l.sku,
          product_name: l.name,
          quantity: l.qty,
          price: l.price,
          item_id: l.lineId,
        };
      }),
    };
  });

  customerOrdersResponse.data = existing.concat(omsOrders);
  customerOrdersResponse.count = customerOrdersResponse.data.length;

  return new Status(Status.OK);
}

exports.list = listOrders;
```

### `cancel` — Cancel a Whole Order

Signature: `cancel(context, orderResponse)`. Context carries `orderNo`, `siteId`, and `reason`
(already validated and defaulted by the platform).

Before the platform calls this hook, it has already loaded the order (via your `retrieve` hook) and
run it through access control, and it hands that populated order to you as `orderResponse`. Then
inspect it to perform your own eligibility checks (for example, refuse to cancel an order that has
already shipped). If the order is eligible, forward the cancellation to your OMS, then **update the
same `orderResponse` in place** to reflect the post-cancellation state — the platform returns it as
the response.

```js
"use strict";
var Status = require("dw/system/Status");

function cancel(context, orderResponse) {
  // orderResponse is the already-loaded, access-checked order — use it for eligibility checks.
  var shipments = orderResponse.omsData ? orderResponse.omsData.shipments : null;
  if (shipments && shipments.length > 0) {
    return new Status(Status.ERROR, "NOT_CANCELABLE", "Order has already shipped");
  }

  var result = MyOms.cancelOrder(context.orderNo, context.reason);
  if (!result.ok) {
    return new Status(Status.ERROR, "OMS_CANCEL_REJECTED", result.message);
  }

  // Update the loaded order to its post-cancellation state.
  orderResponse.status = "cancelled";
  return new Status(Status.OK);
}

exports.cancel = cancel;
```

### `return` — Start a Return

Signature: `returnOrder(context, orderResponse)`. The context carries `productItems` — the items to
return, each with `itemId`, `quantity`, and a validated `reason`. As with cancel, `orderResponse` is
the already-loaded, access-checked order: inspect it for eligibility, forward the return to your OMS,
then update it in place to reflect the post-return state.

Because `return` is a reserved word in JavaScript, **name the function anything else and export it
under the `return` key**:

```js
"use strict";
var Status = require("dw/system/Status");

function startReturn(context, orderResponse) {
  var result = MyOms.createReturn(context.productItems);
  if (!result.ok) {
    return new Status(Status.ERROR, "OMS_RETURN_REJECTED", result.message);
  }
  orderResponse.status = "completed";
  return new Status(Status.OK);
}

exports["return"] = startReturn; // NOT exports.return
```

### `accessControl` — Custom Ownership Decision _(Optional)_

Signature: `accessControl(customer, orderResponse)`, where `customer` is a `dw.customer.Customer`.

By default the platform grants access when the order's `customer_info.customer_id` matches the
authenticated shopper. Register this hook only when your ownership rule is different — for example
when your OMS uses a different customer identifier and you manage it via custom attributes on the
customer profile. When registered, this hook **fully replaces** the default check. Return
`Status.OK` to grant, `Status.ERROR` to deny.

```js
"use strict";
var Status = require("dw/system/Status");

exports.accessControl = function (customer, orderResponse) {
  // The OMS uses its own customer identifier, stored as a custom attribute on the profile.
  var externalCustomerId = customer.custom.externalOmsCustomerId;
  if (externalCustomerId && externalCustomerId === orderResponse.customerInfo.customer_id) {
    return new Status(Status.OK);
  }
  return new Status(Status.ERROR);
};
```

### `reasonCodes` — Supply Cancel / Return Reasons _(Optional)_

Signature: `reasonCodes(context, omsMetaData)`. The `context` carries `context.siteId` (use it if
your OMS has per-site reason codes). Fill `cancelReasonCodes` and `returnReasonCodes`, each an array
of `{ reason, default }`. Mark exactly one entry per list as `default: true`.

```js
"use strict";
var Status = require("dw/system/Status");

function reasonCodes(context, omsMetaData) {
  // context.siteId identifies the site the codes are requested for.
  var codes = [
    { reason: "Not specified", default: true },
    { reason: "Defect", default: false },
    { reason: "Wrong item", default: false },
  ];
  omsMetaData.cancelReasonCodes = codes;
  omsMetaData.returnReasonCodes = codes;
  return new Status(Status.OK);
}

exports.reasonCodes = reasonCodes;
```

The platform serves these codes on the `oms-meta-data` endpoint and validates cancel/return reasons
against them.

---

## The Order Response

Your hooks map your OMS's data onto the platform's order shape. The full set of available fields is
defined by the SCAPI **Order** schema in the [Shopper Orders API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary); you decide which of them
your storefront's order experiences need and populate those — unset fields are absent from the
response.

Two things always hold, regardless of which fields you populate:

- **Property names are `snake_case` in the hook, `camelCase` on the wire** — for example set
  `order_no`, `customer_info`, `product_items`; the platform serializes them as `orderNo`,
  `customerInfo`, `productItems`.
- **`customer_info.customer_id` is load-bearing** for the default access check. It must carry the
  **platform customer id** of the shopper who owns the order, because the default access check
  compares it against the authenticated shopper. This has an
  upstream consequence: when an order is exported to your OMS, the OMS must **persist the platform
  customer id** alongside the order, so that your `retrieve` and `list` hooks can map it back into
  `customer_info.customer_id` on load. Storing it at creation time is what makes the default access
  check work; if your OMS instead keys the shopper on a different identifier, map that identifier and
  register a custom `accessControl` hook.

### Watch for Constrained Fields

Some fields in the Order schema are **enums** — the OpenAPI Specification (OAS) restricts them to a fixed set of allowed
values. `status` is the most common example. Where a field is an enum, you must map your OMS's native
value onto one of the allowed values; anything else is rejected. Check the Order schema in the
Shopper Orders API reference for the exact enum values on each field before you map to it.

---

## Access Control

The platform — never your `retrieve` hook — decides whether the authenticated shopper may see an
order. It does so either with its built-in checks or, when you register one, by delegating to your
custom `accessControl` hook.

**Access control runs only for orders the platform didn't already load and check itself.** When the
platform served the order from its own store, it was already access-checked during that load and is
trusted as-is — the OMS access decision below does **not** run again for it. The access decision
below applies to orders the platform did **not** hold: an order that exists only in the OMS (so your
`retrieve` hook filled an empty document), or an order your `list` hook appended. For those, after
your hook returns, the platform resolves access in this order:

1. **Guest order access code.** If the request carries a valid access code for a guest order, access
   is granted (and the `accessControl` hook is **not** consulted).
2. **Ownership check — your hook _or_ the default, never both.** If you registered an `accessControl`
   hook, the platform calls it and uses its verdict; the default check doesn't run. If you didn't,
   the platform applies the default check: the order's `customer_info.customer_id` must match the
   authenticated shopper's platform customer id.

If none grants access, the platform returns **404 Not Found** — order existence is never leaked to a
shopper who doesn't own it.

**note:** **Guest orders via OTP.** Step 1 is an alternative access path evaluated **up front**, and it
applies **only to guest orders** — the platform requires the order to be flagged as a guest order
(your hook set `guest = true` with a non-null `customer_info.customer_id`). For such an order, a
valid access code (OTP) grants access there and then — neither your `accessControl` hook nor the
platform's default ownership check is invoked. Orders owned by a **registered** customer can't be
accessed via OTP; for them the access code is ignored and access falls to step 2.

Because the platform owns this decision, your single-order hooks (`retrieve`, `cancel`, `return`)
receive **no customer id** and must not re-check ownership. The **list** hook does receive
`context.customerId` — it is customer-scoped by design and needs it to query your OMS for the right
customer's orders. Even so, the platform doesn't take the orders you add to the list on trust: it
runs the access decision **individually for each order your hook appended** — your `accessControl`
hook if registered, otherwise the default ownership check — and filters out any that doesn't pass.
(The orders the platform pre-populated are already access-checked and are kept as-is.) So the
`customerId` on the list context is a query aid, not the access control itself.

For cancel and return, the platform first calls your `retrieve` hook, verifies ownership, and only
then calls your `cancel` / `return` hook — so a mutation is never forwarded to your OMS for an order
the shopper doesn't own.

---

## Reason Codes for Cancel and Return

When a shopper cancels an order or returns items, the request may carry a `reason`. If your OMS has
its own set of accepted reasons, register the optional `reasonCodes` hook to supply them. The
platform uses those codes two ways:

1. The `GET .../orders/oms-meta-data` endpoint returns them so the storefront can render a reason
   picker.
2. Cancel and return requests are validated against them.

The reason-code list is **never empty**. If you don't register the hook (or it supplies no codes),
the platform injects a single default reason, `"Not specified"` (`default: true`). With no hook
registered, `"Not specified"` is therefore the only accepted reason: an omitted reason resolves to
it, and any other supplied reason is rejected with **400 Bad Request**. Register the hook to widen
the accepted set.

Rules:

- **Matching is case-sensitive and exact.** A supplied reason that is not in the list → **400 Bad
  Request**.
- **A missing reason resolves to the `default`-flagged code.**
- The picker and the validator read from the **same list**, so what the storefront shows is exactly
  what cancel / return accept.

**Caching.** Reason codes are near-static, so the platform does **not** call this hook on every
request. It caches the hook's output **per site** for a short time (a 180-second TTL) and serves both
`oms-meta-data` and cancel/return validation from that snapshot. When you activate a new code
version, the cache is flushed so an edit to `reasonCodes.js` takes effect immediately; otherwise a
change is picked up within the TTL window.

**note:** **Treat `reasonCodes` as a settings provider, not a per-request handler.** The platform can reuse a
cached result instead of calling your hook, so it won't necessarily run on every shopper request.
Return the list of codes. Don't put logic in it that runs each time an order is
canceled or returned. Its only input is `context.siteId`.

Even with caching, avoid calling your OMS from inside this hook on every cache miss. Reason codes
change rarely, so a live callout per miss adds latency to the first request in each TTL window for
no real benefit. Prefer a **synchronization** approach: periodically pull the codes from your OMS
and store them on B2C Commerce (for example in site preferences or a custom object), and have the
hook return that locally-stored copy. That keeps even uncached responses fast and insulates the
shopper path from OMS availability.

---

## Guest Order Access Codes (OTP)

**note:** **This is a separate, independent SCAPI-only feature.** Guest order access codes are a
**SCAPI-only** flow whose purpose is to let a guest shopper regain access to their own orders
**after the session they placed the order in is gone** (guests have no login to prove ownership).
It's not part of the OMS integration — it lives in its own `sfcc.app.order.*` namespace and works
with any order backend, not just a third-party OMS. This section covers only how the two features
interact — see [Guest Order Access with an Access Code (OTP)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/guest-order-access-code.html) for the full feature.

Guests have no account, so after the session they checked out in is gone, they have no way to prove
ownership of their order. To bridge that, the platform issues a one-time, 6-digit access code for
guest order access, valid for a short window. A shopper requests one via
`POST .../orders/{orderNo}/actions/request-access-code`, and then supplies the code to prove
ownership on the guest read and write paths alike — the order lookup as well as the cancel and return
requests. Note that the field the code goes in differs by endpoint:

- **Order lookup** (`POST .../orders/{orderNo}/lookup`) — put the code in **`orderViewCode`**. That
  field accepts either the static OrderViewCode or the 6-digit access code; the server tells them
  apart by format. There is no `orderAccessCode` field on the lookup request.
- **Cancel / return** (`.../actions/oms-cancel-order`, `.../actions/oms-return-order`) — put the code
  in **`orderAccessCode`**.

Where it intersects the OMS integration: a valid access code is checked **before** the OMS
`accessControl` hook, so it grants access regardless of other rules. For the platform to know which
guest order the code belongs to, your OMS `retrieve` hook must set `guest = true` and a non-null
`customer_info.customer_id`.

When the access-code request is made with **`expand=oms`**, the code-generation and email flow runs
against the **order data from your OMS** (loaded via the `retrieve` hook) rather than the platform's
local order. This has a useful side effect: the flow keeps working even after B2C Commerce has
**deleted its local copy** of the order — for example after the order has been handed off to the OMS
and purged from the platform. As long as the OMS still has the order and your `retrieve` hook can
return it, a guest can still request an access code and receive the email.

---

## Push Status Updates to the Platform

The retrieve hooks are **pull-based**: the platform calls your OMS when a shopper or channel requests
an order. To let your OMS **proactively notify** the platform when an order ships or is adjusted —
so the update propagates to agentic-commerce order webhooks — your OMS calls an inbound Admin API:

```
POST /organizations/{organizationId}/orders/{orderNo}/oms-status-events?siteId={siteId}
```

| Property       | Value                                                                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Auth           | Account Manager OAuth (client credentials), scope `sfcc.orders.rw`                                                                                   |
| Success        | **202 Accepted** (queued; processed asynchronously)                                                                                                  |
| Bad Request    | **400** when the request body is invalid (see the request body rules in this section)                                                                                    |
| OMS not active | **409 Conflict** when the OMS integration is not active for the site — the OMS App Hooks toggle is off, or the required hooks are not all registered |

The request body carries **exactly one** of a fulfillment event or an adjustment. The platform
assembles the full order (by calling your `retrieve` hook), merges the pushed change, and publishes
the downstream order webhook.

```jsonc
{
  // exactly ONE of the following:

  "fulfillmentEvent": {
    "id": "ship-001", // required
    "occurredAt": "2026-06-03T10:15:00.000Z", // required (RFC 3339)
    "type": "shipped", // required — processing | shipped | in_transit |
    //   delivered | failed_attempt | canceled |
    //   undeliverable | returned_to_sender (open string)
    "lineItems": [
      // required, 1..200
      { "id": "pli-001", "quantity": 2 } //   quantity >= 0
    ],
    "trackingNumber": "1Z999AA10123456784", // required when type != "processing"
    "trackingUrl": "https://www.ups.com/track?num=1Z999AA10123456784", // required when type != "processing"
    "carrier": "UPS", // optional
    "description": "Handed to carrier" // optional
  },

  "adjustment": {
    "id": "ret-7788", // required
    "type": "return", // required — open string: refund | return | credit | ...
    "occurredAt": "2026-06-03T10:15:00.000Z", // required (RFC 3339)
    "status": "completed", // required — pending | completed | failed
    "lineItems": [
      // optional; quantity may be negative — a negative
      { "id": "pli-001", "quantity": -1 } //   value means units removed/returned
    ],
    "totals": [
      // optional; amount in minor units (cents) and may be
      { "type": "total", "amount": -1999, "displayText": "Refund" }, // negative — negative = money
      { "type": "tax", "amount": -160 } // back to the buyer
    ],
    "description": "Customer requested — defective item" // optional
  }
}
```

For how B2C Commerce turns these events into signed UCP order snapshots, see [Order Post-Processing Events in the UCP Order Lifecycle](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/ucp/ucp-order-post-processing-events.md). The inbound request uses camelCase (`occurredAt`, `lineItems`); the UCP snapshot uses snake_case (`occurred_at`, `line_items`).

---

## The SCAPI Surface (for Reference)

These are the public Shopper endpoints your hooks power. Consumers call them exactly as they would
without an OMS integration.

Most of these endpoints belong to the **Shopper Orders** API, whose base is
`/checkout/shopper-orders/v1/organizations/{organizationId}`. The one exception is **List customer
orders**, which is a **Shopper Customers** API endpoint, with the base
`/customer/shopper-customers/v1/organizations/{organizationId}`. The `API` column below notes which
base each path is relative to. **`siteId` is a required query parameter on every endpoint** — both
the base and `siteId` are omitted from the paths for readability.

| Operation            | API               | Method + path                                     | Request body                                                          | Routes to        |
| -------------------- | ----------------- | ------------------------------------------------- | --------------------------------------------------------------------- | ---------------- |
| Get order            | Shopper Orders    | `GET /orders/{orderNo}?expand=oms`                | —                                                                     | `order.retrieve` |
| List customer orders | Shopper Customers | `GET /customers/{customerId}/orders?expand=oms`   | —                                                                     | `order.list`     |
| Guest order lookup   | Shopper Orders    | `POST /orders/{orderNo}/lookup?expand=oms`        | `{ orderViewCode?, email?, phone?, postalCode? }`                     | `order.retrieve` |
| Reason codes         | Shopper Orders    | `GET /orders/oms-meta-data`                       | —                                                                     | `reasonCodes`    |
| Cancel order         | Shopper Orders    | `POST /orders/{orderNo}/actions/oms-cancel-order` | `{ reason?, orderAccessCode? }`                                       | `order.cancel`   |
| Return items         | Shopper Orders    | `POST /orders/{orderNo}/actions/oms-return-order` | `{ productItems: [{ itemId, quantity, reason? }], orderAccessCode? }` | `order.return`   |

### Error Responses

| Status              | When                                                                                                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **400 Bad Request** | The provided input is not sufficient or valid for the requested action (for example, an unrecognized reason code, an unknown `itemId`, or a return quantity beyond what's returnable). |
| **404 Not Found**   | Order unknown, or the shopper is not authorized to see it (existence is not leaked).                                                                                                   |
| **409 Conflict**    | Order state doesn't permit the action, your OMS rejected it, or the OMS integration is not active for the site.                                                                        |

---

## Gotchas

- **Install the Commerce App.** `sfcc.app.oms.order.*` hooks don't run unless the app is installed on the site. Registering `hooks.json` on a cartridge that isn't part of an installed Commerce App isn't enough. See [Building Your Commerce App — Extension Points](/docs/commerce/b2c-commerce/guide/building-your-app.md#extension-points).
- **Always return a `Status`.** A missing return is treated as failure (surfaces as 404 on
  single-order retrieve), not as success.
- **Register all four core hooks together** — the integration is inactive unless all four are present
  and the toggle is on.
- **Pass `expand=oms`** on `getOrder` / `getCustomerOrders`, or your hook is not called at all and the
  platform serves only its own data.
- **The order document may arrive pre-populated.** On the read hooks, check what the platform already
  put there and enrich it rather than blindly overwriting it.
- **`retrieve` gets no customer id.** Don't implement ownership there — the platform runs access
  control for the orders it didn't already load.
- **`customer_info.customer_id` is load-bearing.** Set it to the platform customer id of the shopper
  who owns the order, or the default access check can't grant access.
- **The list hook appends, and returns only its customer's orders** — add to the pre-populated `data`
  list rather than replacing it, and include only `context.customerId`'s orders.
- **`reasonCodes` takes `(context, omsMetaData)`** and its output is cached per site. Return a
  static or per-site list; don't rely on per-request side effects.

<!-- document id=a127de5f1d5cdf2b0e6e9e9176de12c6970158d7b0a01b8e4fdb7ad5e26389a0 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-consent-tracking.md -->

# Consent Tracking in SFRA

Implement consent tracking on a storefront based on SFRA. Merchants can track personal information about their shoppers to improve the shopping experience. The merchant can collect and honor shoppers’ consent preferences when they are using the site.

The following example shows one way to implement consent tracking on a storefront adapted from SFRA and is provided for informational purposes only. As always, merchants can consult their own legal department or advisors to review and consent management process.

The implementation uses:

- A content asset for displaying a consent request message to the shopper
- The site-specific preference **Tracking** to disable tracking by default
- A session-specific flag to allow tracking if the shopper grants consent

## Consent Asset for the Consent Request Message

To display a consent message to the shopper, a content asset whose internal ID is `tracking_hint` is used. Replace the placeholder text in the content asset with your own message.

## Tracking Preference

The **Tracking** site preference determines the default tracking behavior. When set to **Opt-in**, personal information is not tracked by default for all shoppers visiting the site; when not set to **Opt-in**, personal information is tracked.

<!--TODO: Fix link post migration -->
<!-- The [**Tracking** site preference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/admin/b2c-setting-privacy-preferences.md) determines the default tracking behavior. When set to **Opt-in**, personal information is not tracked by default for all shoppers visiting the site; when not set to **Opt-in**, personal information is tracked.
 -->

To set this preference, select **Merchant Tools > _site_ > Site Preferences > Privacy**.

The example assumes the **Tracking** preference is set to **Opt-In**.

## Session Tracking Flag

The example presents a consent request message to the shopper, who can choose to allow tracking. If the shopper allows tracking, it is enabled during the shopper’s session. For more information, see Browser-Based Local Data Storage.

<!--TODO: Fix link post migration -->
<!-- The example presents a consent request message to the shopper, who can choose to allow tracking. If the shopper allows tracking, it is enabled during the shopper’s session. For more information, see [Browser-Based Local Data Storage](https://developer.salesforce.com/dataprotectionandprivacy/localdatastorage.md).
 -->

To enable tracking on a session:

- `dw.system.Session.setTrackingAllowed(boolean)` ― If the boolean value is `true`, tracking is enabled for the current session; if `false`, tracking is disabled.

To check the current value of the session's tracking flag:

- `dw.system.Session.isTrackingAllowed()` ― `true` indicates that tracking is enabled; `false`, disabled.

## Implementation Overview

The sample implementation adds a `<span>` tag to every page in the storefront. The `<span>` tag stores information about the shopper’s consent choices and makes the information available to client-side code running in the browser. If the shopper has not yet given consent, the client-side code inspects the `<span>` tag and displays a Tracking Consent window.

The `<span>` tag is created by the template `app_storefront_base/cartridge/templates/default/common/consent.isml`.

```html
<span
  class="api-${pdict.consentApi} ${pdict.tracking_consent == null ? '' : 'consented' } tracking-consent"
  data-url="${URLUtils.url('ConsentTracking-GetContent', 'cid', 'tracking_hint')}"
  data-reject="${URLUtils.url('ConsentTracking-SetSession', 'consent', 'false')}"
  data-accept="${URLUtils.url('ConsentTracking-SetSession', 'consent', 'true')}"
  data-acceptText="${Resource.msg('button.consentTracking.yes', 'common', null)}"
  data-rejectText="${Resource.msg('button.consentTracking.no', 'common', null)}"
  data-heading="${Resource.msg('heading.consentTracking.track.consent', 'common', null)}"
></span>
```

This template is rendered by the `ConsentTracking-Check` route in the `app_storefront_base/cartridge/controllers/ConsentTracking.js` controller.

```javascript
server.get("Check", consentTracking.consent, function (req, res, next) {
  res.render("/common/consent", {
    consentApi: Object.prototype.hasOwnProperty.call(req.session.raw, "setTrackingAllowed"),
  });
  next();
});
```

This route is called every time a storefront page is rendered. In the route, the middleware step `consentTracking.consent` is invoked before the `consent.isml` template is rendered.

This middleware step is implemented in the server-side script `app_storefront_base/cartridge/scripts/middleware/consentTracking.js`.

```javascript
"use strict";

/**
 * Middleware to use consent tracking check
 * @param {Object} req - Request object
 * @param {Object} res - Response object
 * @param {Function} next - Next call in the middleware chain
 * @returns {void}
 */
function consent(req, res, next) {
  var consented = req.session.privacyCache.get("consent");
  if (consented === null || consented === undefined) {
    req.session.privacyCache.set("consent", null);
  } else if (consented === false) {
    req.session.privacyCache.set("consent", false);
    req.session.raw.setTrackingAllowed(false);
  } else if (consented === true) {
    req.session.privacyCache.set("consent", true);
    req.session.raw.setTrackingAllowed(true);
  }

  res.setViewData({
    tracking_consent: req.session.privacyCache.get("consent"),
  });
  next();
}

module.exports = {
  consent: consent,
};
```

It checks the value of the session's `consent` property. Regardless if the value of the property is either `true` or `false`, it calls the `setTrackingAllowed()` method on the session to record the shopper’s choice.

It then adds the value of the `consent` property to the response's view data, storing it in the `tracking_consent` property. The `tracking_consent` property is made available to the `consent.isml` template via the `pdict` property.

The first time this code is executed in a session, the value of the session's `consent` property is `null`, so the `tracking_consent` property is also null. Because the value of the `tracking_consent` property is `null`, the first line in the `consent.isml` template:

```
<span class="api-${pdict.consentApi} ${pdict.tracking_consent == null ? '' : 'consented' } tracking-consent"
```

Outputs the following HTML:

```
 <span class="api-true tracking-consent" ...
```

In this output, the `consented` attribute value is absent, and its absence indicates to the client-side code that the shopper has not yet consented to tracking. The absence of this attribute causes the client-side code to display the Tracking Consent window, prompting the shopper to grant or deny consent.

After the shopper grants or denies consent, subsequent invocations of the `consentTracking.consent` middleware step set the `tracking_consent` property to a non-null value. As a consequence, the resulting HTML output looks like this code snippet:

```
 <span class="api-true consented tracking-consent" ...
```

In this output, the consented attribute value is present, which indicates to the client-side code that the shopper has either granted or denied access to tracking. Whichever choice the shopper made, it is no longer necessary to display the Tracking Consent window.

Every time the `consent.isml` template is rendered, the `consentApi` property is passed into the template via the `pdict` property. The value of the `consentApi` property is the result of the following call:

```
Object.prototype.hasOwnProperty.call(req.session.raw, 'setTrackingAllowed')
```

The call checks if the session has a `setTrackingAllowed` property. If it does, this call resolves to `true`; otherwise, `false`. This call always evaluates to `true` for Salesforce B2C Commerce version 18.4 and later.

The client-side script, `app_storefront_base/cartridge/client/default/js/components/consentTracking.js`, inspects the `<span>` tag created by the `consent.isml` template.

```javascript
"use strict";

/**
 * Renders a modal window that tracks the shoppers consenting to accepting site
 * tracking policy
 */
function showConsentModal() {
  var urlContent = $(".tracking-consent").data("url");
  var urlAccept = $(".tracking-consent").data("accept");
  var urlReject = $(".tracking-consent").data("reject");
  var textYes = $(".tracking-consent").data("accepttext");
  var textNo = $(".tracking-consent").data("rejecttext");
  var textHeader = $(".tracking-consent").data("heading");

  var htmlString =
    "<!-- Modal -->" +
    '<div class="modal show" id="consent-tracking" role="dialog" style="display: block;">' +
    '<div class="modal-dialog">' +
    "<!-- Modal content-->" +
    '<div class="modal-content">' +
    '<div class="modal-header">' +
    textHeader +
    "</div>" +
    '<div class="modal-body"></div>' +
    '<div class="modal-footer">' +
    '<div class="button-wrapper">' +
    '<button class="affirm btn btn-primary" data-url="' +
    urlAccept +
    '">' +
    textYes +
    "</button>" +
    '<button class="decline btn btn-primary" data-url="' +
    urlReject +
    '">' +
    textNo +
    "</button>" +
    "</div>" +
    "</div>" +
    "</div>" +
    "</div>" +
    "</div>";
  $.spinner().start();

  $("body").append(htmlString);

  $.ajax({
    url: urlContent,
    type: "get",
    dataType: "html",
    success: function (response) {
      $(".modal-body").html(response);
    },
    error: function () {
      $("#consent-tracking").remove();
    },
  });

  $("#consent-tracking .button-wrapper button").click(function (e) {
    e.preventDefault();
    var url = $(this).data("url");
    $.ajax({
      url: url,
      type: "get",
      dataType: "json",
      success: function () {
        $("#consent-tracking .modal-body").remove();
        $("#consent-tracking").remove();
        $.spinner().stop();
      },
      error: function () {
        $("#consent-tracking .modal-body").remove();
        $("#consent-tracking").remove();
        $.spinner().stop();
      },
    });
  });
}

module.exports = function () {
  if ($(".consented").length === 0 && $(".tracking-consent").hasClass("api-true")) {
    showConsentModal();
  }

  if ($(".tracking-consent").hasClass("api-true")) {
    $(".tracking-consent").click(function () {
      showConsentModal();
    });
  }
};
```

This script constructs a section of HTML, stores it in the variable `htmlString`, and appends it to the `<body>` element of the DOM. The script then performs an Ajax call to get the value of the `tracking_hint` content asset. If the call is successful, the script inserts the value of the content asset into the \<div> tag whose class attribute is `modal-body`. If the call fails, the script removes the entire section of appended HTML from the DOM.

The script then creates an event listener on both `<button>` elements in the appended HTML. If the shopper clicks either button in the Tracking Consent window, the script makes a second Ajax call, either enabling or disabling tracking on the session. The script then removes the Tracking Consent window from the DOM.

Lastly, this script exports a function whose purpose is to conditionally call the `showConsentModal()` function. The exported function is invoked in two situations: after each storefront page is fully loaded in the browser window, and when the shopper clicks **Consent to Track** in the Edit Profile form on the My Account page. For more information, see the `app_storefront_base/cartridge/templates/default/account/editProfileForm.isml` template.

<!-- document id=f039069720f76e0041c5fe8eafb87146787c5ec20209e377fafdd8e57afc05dd url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/consents.md -->

Consents

# Consents

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/consents/consents-oas-v1-public.yaml)

## API Overview

Use the Consents Admin API to manage customer consent subscription preferences for marketing communications across multiple channels. This API provides complete CRUD (Create, Read, Update, Delete) operations for subscription management, with support for rich text markup in subscription titles and subtitles.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include one of the following OAuth scopes in the client ID used to generate the token:

*   `sfcc.consents`: Required for reading subscription data (GET operations)
*   `sfcc.consents.rw`: Required for creating, updating, and deleting subscription data (POST, PUT, PATCH, DELETE operations)

For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Data Model

#### Subscriptions

Subscriptions represent a customer's consent to receive specific types of marketing communications. Each subscription includes:

*   Identifier:
    *   `subscriptionId`: Descriptive identifier following kebab-case format (1-255 characters, pattern: `^[a-z0-9]+(?:-[a-z0-9]+)*$`)
    *   `siteId`: Commerce Cloud site identifier for multi-site organizations
*   Display Information: Rich text content with localization and HTML markup support
    *   `title`: Localized subscription titles with markup support (required for creation)
    *   `subtitle`: Optional localized subscription subtitles with markup support
*   Consent Configuration:
    *   `channels`: Array of supported communication methods (required, 1-10 items)
    *   `tags`: Configurable filter tags for subscription categorization (0-10 items, defaults to empty array)
    *   `consentType`: Type classification (`marketing` or `legal`, defaults to `marketing`)
    *   `consentRequired`: Whether the subscription is mandatory (defaults to `false`)
    *   `defaultStatus`: Default consent state (`opt_in` or `opt_out`, defaults to `opt_out`)
    *   `enabled`: Whether the subscription is currently active (defaults to `true`) - defined as reusable `Enabled` schema component
*   System Integration:
    *   `umaSubscriptionId`: Salesforce UMA CommSubscription object ID (15-18 characters)

#### Channels

Channels define the communication methods available for a subscription:

*   `email`: Email communications
*   `sms`: SMS/text messages
*   `whatsapp`: WhatsApp

#### Tags

Tags can be used to filter the subscriptions for various uses. Provided tags include:

*   `homepage_banner`: Main website homepage
*   `registration`: Customer registration process
*   `checkout`: During the checkout process
*   `user_profile`: User profile management area

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

**Version:** 1.1.5

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/shopper/consents/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.consents: Consents READONLY
    *   Scope sfcc.consents.rw: Consents
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Get all subscriptions

`GET /organizations/{organizationId}/subscriptions`

Operation ID: `getSubscriptions`. Security: AmOAuth2 (sfcc.consents).

Retrieve all current subscriptions for the specified organization and site.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Successfully retrieved subscriptions.
    
    Media type: `application/json`. Schema: `SubscriptionsResponse`.
    
    _Example: GetSubscriptionsResponse_ Example response for getting all subscriptions for a specific site (RefArch)
    
    ```
    {
      "data": [
        {
          "subscriptionId": "weekly-newsletter",
          "siteId": "RefArch",
          "title": {
            "default": {
              "markup": "Weekly <strong>Newsletter</strong>",
              "source": "Weekly <strong>Newsletter</strong>"
            },
            "fr-FR": {
              "markup": "Bulletin <strong>Hebdomadaire</strong>",
              "source": "Bulletin <strong>Hebdomadaire</strong>"
            }
          },
          "subtitle": {
            "default": {
              "markup": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>",
              "source": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>"
            },
            "fr-FR": {
              "markup": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>",
              "source": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>"
            }
          },
          "tags": [
            "homepage_banner",
            "user_profile"
          ],
          "channels": [
            "email",
            "whatsapp"
          ],
          "umaSubscriptionId": "0Xl000000000000000",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "enabled": true
        },
        {
          "subscriptionId": "promotional-offers",
          "siteId": "RefArch",
          "title": {
            "default": {
              "markup": "Promotional <em>Offers</em>",
              "source": "Promotional <em>Offers</em>"
            },
            "fr-FR": {
              "markup": "Offres <em>Promotionnelles</em>",
              "source": "Offres <em>Promotionnelles</em>"
            }
          },
          "subtitle": {
            "default": {
              "markup": "Receive special promotional offers - <a href=\"https://example.com/offers\">View Offers</a>",
              "source": "Receive special promotional offers - <a href=\"https://example.com/offers\">View Offers</a>"
            },
            "fr-FR": {
              "markup": "Recevez des offres promotionnelles spéciales - <a href=\"https://example.com/offers\">Voir les offres</a>",
              "source": "Recevez des offres promotionnelles spéciales - <a href=\"https://example.com/offers\">Voir les offres</a>"
            }
          },
          "tags": [
            "checkout"
          ],
          "channels": [
            "sms",
            "email"
          ],
          "umaSubscriptionId": "0Xl000000000000001",
          "consentType": "legal",
          "consentRequired": true,
          "defaultStatus": "opt_in",
          "enabled": true
        }
      ]
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   The Marketing Consent feature is not enabled for this organization.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ConsentsFeatureNotEnabled_
    
    ```
    {
      "title": "Consents Feature Not Enabled",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/consents-feature-not-enabled",
      "detail": "The Marketing Consents feature is not enabled for this organization."
    }
    ```
    

### PUT Create subscription

`PUT /organizations/{organizationId}/subscriptions/{subscriptionId}`

Operation ID: `createSubscription`. Security: AmOAuth2 (sfcc.consents.rw).

Create a new subscription for the specified organization.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `subscriptionId` (path, SubscriptionId, required) The unique identifier of the subscription

#### Request body (required)

Media type: `application/json`. Schema: `SubscriptionPutRequest`.

_Example: PutSubscriptionRequest_ Example request for creating or replacing a subscription

```
{
  "subscriptionId": "weekly-newsletter",
  "siteId": "RefArch",
  "title": {
    "default": {
      "markup": "Weekly <strong>Newsletter</strong>",
      "source": "Weekly <strong>Newsletter</strong>"
    },
    "fr-FR": {
      "markup": "Bulletin <strong>Hebdomadaire</strong>",
      "source": "Bulletin <strong>Hebdomadaire</strong>"
    }
  },
  "subtitle": {
    "default": {
      "markup": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>",
      "source": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>"
    },
    "fr-FR": {
      "markup": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>",
      "source": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>"
    }
  },
  "tags": [
    "homepage_banner",
    "user_profile"
  ],
  "channels": [
    "email",
    "whatsapp"
  ]
}
```

#### Responses

*   **201** Subscription created successfully.
    
    Media type: `application/json`. Schema: `Subscription`.
    
    _Example: PutSubscriptionResponse_ Example response for creating or replacing a subscription
    
    ```
    {
      "subscriptionId": "weekly-newsletter",
      "siteId": "RefArch",
      "title": {
        "default": {
          "markup": "Weekly <strong>Newsletter</strong>",
          "source": "Weekly <strong>Newsletter</strong>"
        },
        "fr-FR": {
          "markup": "Bulletin <strong>Hebdomadaire</strong>",
          "source": "Bulletin <strong>Hebdomadaire</strong>"
        }
      },
      "subtitle": {
        "default": {
          "markup": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>",
          "source": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>"
        },
        "fr-FR": {
          "markup": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>",
          "source": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>"
        }
      },
      "tags": [
        "homepage_banner",
        "user_profile"
      ],
      "channels": [
        "email",
        "whatsapp"
      ],
      "umaSubscriptionId": "0Xl000000000000000",
      "consentType": "marketing",
      "consentRequired": false,
      "defaultStatus": "opt_out",
      "enabled": true
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   The Marketing Consent feature is not enabled for this organization.
    *   The request format is invalid or malformed JSON.
    *   Required fields (title, channels) are missing.
    *   The siteId in the request body does not match the siteId parameter.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ConsentsFeatureNotEnabled: same as GET /organizations/{organizationId}/subscriptions 400 response._
    
    _Example: SubscriptionCreationValidationError_
    
    ```
    {
      "title": "Subscription Creation Validation Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subscription-creation-validation-error",
      "detail": "Unable to create consent subscription."
    }
    ```
    
    _Example: SubscriptionIdMismatchError_
    
    ```
    {
      "title": "Subscription ID Mismatch",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subscription-id-mismatch",
      "detail": "The subscriptionId in the request body does not match the subscriptionId parameter."
    }
    ```
    
    _Example: SiteIdMismatchError_
    
    ```
    {
      "title": "Site ID Mismatch",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-id-mismatch",
      "detail": "The siteId in the request body does not match the siteId parameter. Both must specify the same site."
    }
    ```
    
*   **409** Conflict - Subscription already exists
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: SubscriptionAlreadyExists_
    
    ```
    {
      "title": "Subscription Already Exists",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subscription-already-exists",
      "detail": "A subscription with this ID already exists. Use PATCH to update existing subscriptions."
    }
    ```
    

### DELETE Delete subscription

`DELETE /organizations/{organizationId}/subscriptions/{subscriptionId}`

Operation ID: `deleteSubscription`. Security: AmOAuth2 (sfcc.consents.rw).

Delete an existing subscription for the specified organization.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `subscriptionId` (path, SubscriptionId, required) The unique identifier of the subscription

#### Responses

*   **204** Subscription deleted successfully.
*   **400**
    
    Possible reasons:
    
    *   The Marketing Consent feature is not enabled for this organization.
    *   The siteId parameter is invalid or does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ConsentsFeatureNotEnabled: same as GET /organizations/{organizationId}/subscriptions 400 response._
    

### PATCH Update subscription

`PATCH /organizations/{organizationId}/subscriptions/{subscriptionId}`

Operation ID: `updateSubscription`. Security: AmOAuth2 (sfcc.consents.rw).

Update an existing subscription for the specified organization.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `subscriptionId` (path, SubscriptionId, required) The unique identifier of the subscription

#### Request body (required)

Media type: `application/json`. Schema: `SubscriptionPatchRequest`.

_Example: PatchSubscriptionRequest_ Example request for updating a subscription

```
{
  "subscriptionId": "weekly-newsletter",
  "siteId": "RefArch",
  "title": {
    "default": {
      "markup": "Weekly <strong>Newsletter</strong> - <em>Updated</em>",
      "source": "Weekly <strong>Newsletter</strong> - <em>Updated</em>"
    },
    "fr-FR": {
      "markup": "Bulletin <strong>Hebdomadaire</strong> - <em>Mis à jour</em>",
      "source": "Bulletin <strong>Hebdomadaire</strong> - <em>Mis à jour</em>"
    }
  },
  "subtitle": {
    "default": {
      "markup": "Get our updated weekly newsletter with the latest features - <a href=\"https://example.com\">Learn More</a>",
      "source": "Get our updated weekly newsletter with the latest features - <a href=\"https://example.com\">Learn More</a>"
    },
    "fr-FR": {
      "markup": "Recevez notre bulletin hebdomadaire mis à jour avec les dernières fonctionnalités - <a href=\"https://example.com\">En savoir plus</a>",
      "source": "Recevez notre bulletin hebdomadaire mis à jour avec les dernières fonctionnalités - <a href=\"https://example.com\">En savoir plus</a>"
    }
  },
  "tags": [
    "homepage_banner",
    "user_profile",
    "checkout_page"
  ],
  "channels": [
    "email",
    "sms",
    "whatsapp"
  ],
  "consentType": "marketing",
  "consentRequired": false,
  "defaultStatus": "opt_out",
  "enabled": true
}
```

#### Responses

*   **200** Subscription updated successfully.
    
    Media type: `application/json`. Schema: `Subscription`.
    
    _Example: PatchSubscriptionResponse_ Example response for updating a subscription
    
    ```
    {
      "subscriptionId": "weekly-newsletter",
      "siteId": "RefArch",
      "title": {
        "default": {
          "markup": "Weekly <strong>Newsletter</strong> - <em>Updated</em>",
          "source": "Weekly <strong>Newsletter</strong> - <em>Updated</em>"
        },
        "fr-FR": {
          "markup": "Bulletin <strong>Hebdomadaire</strong> - <em>Mis à jour</em>",
          "source": "Bulletin <strong>Hebdomadaire</strong> - <em>Mis à jour</em>"
        }
      },
      "subtitle": {
        "default": {
          "markup": "Get our updated weekly newsletter with the latest features - <a href=\"https://example.com\">Learn More</a>",
          "source": "Get our updated weekly newsletter with the latest features - <a href=\"https://example.com\">Learn More</a>"
        },
        "fr-FR": {
          "markup": "Recevez notre bulletin hebdomadaire mis à jour avec les dernières fonctionnalités - <a href=\"https://example.com\">En savoir plus</a>",
          "source": "Recevez notre bulletin hebdomadaire mis à jour avec les dernières fonctionnalités - <a href=\"https://example.com\">En savoir plus</a>"
        }
      },
      "tags": [
        "homepage_banner",
        "user_profile",
        "checkout_page"
      ],
      "channels": [
        "email",
        "sms",
        "whatsapp"
      ],
      "umaSubscriptionId": "0Xl000000000000000",
      "consentType": "marketing",
      "consentRequired": false,
      "defaultStatus": "opt_out",
      "enabled": true
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   The Marketing Consent feature is not enabled for this organization.
    *   The request format is invalid or malformed JSON.
    *   The subscriptionId in the request body does not match the subscriptionId URL parameter.
    *   The siteId in the request body does not match the siteId parameter.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ConsentsFeatureNotEnabled: same as GET /organizations/{organizationId}/subscriptions 400 response._
    
    _Example SubscriptionIdMismatchError: same as PUT /organizations/{organizationId}/subscriptions/{subscriptionId} 400 response._
    
    _Example SiteIdMismatchError: same as PUT /organizations/{organizationId}/subscriptions/{subscriptionId} 400 response._
    
    _Example: SubscriptionUpdateValidationError_
    
    ```
    {
      "title": "Subscription Update Validation Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/subscription-update-validation-error",
      "detail": "Unable to update consent subscription due to validation errors."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SubscriptionsResponse

*   `data` (_array of Subscription_, required)  
    Minimum items: 0. Maximum items: 50.
    
    _Example_
    
    ```
    [
      {
        "id": "weekly-newsletter",
        "siteId": "RefArch",
        "title": {
          "default": {
            "markup": "Weekly <strong>Newsletter</strong>",
            "source": "Weekly <strong>Newsletter</strong>"
          },
          "fr-FR": {
            "markup": "Bulletin <strong>Hebdomadaire</strong>",
            "source": "Bulletin <strong>Hebdomadaire</strong>"
          }
        },
        "subtitle": {
          "default": {
            "markup": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>",
            "source": "Get our weekly newsletter with the latest updates - <a href=\"https://example.com\">Subscribe</a>"
          },
          "fr-FR": {
            "markup": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>",
            "source": "Recevez notre bulletin hebdomadaire avec les dernières mises à jour - <a href=\"https://example.com\">S&rsquo;abonner</a>"
          }
        },
        "tags": [
          "homepage_banner",
          "user_profile"
        ],
        "channels": [
          "email"
        ],
        "umaSubscriptionId": "0Xl000000000000000",
        "consentType": "marketing",
        "consentRequired": false,
        "defaultStatus": "OPT_OUT",
        "enabled": true
      }
    ]
    ```
    

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SubscriptionId

Identifier for the subscription

Type: `string`.

Minimum length: 1. Maximum length: 255. Pattern: ^\[a-z0-9\]+(?:-\[a-z0-9\]+)\*$. Example: `weekly-newsletter`.

### SubscriptionPutRequest

*   `siteId` (_SiteId_)
*   `subscriptionId` (_SubscriptionId_)
*   `title` (_SubscriptionTitle_, required)
*   `subtitle` (_SubscriptionSubtitle_)
*   `tags` (_array of Tag_)  
    Default: `[]`. Minimum items: 0. Maximum items: 10.
*   `channels` (_array of Channel_, required)
*   `consentType` (_ConsentType_)
*   `consentRequired` (_ConsentRequired_)
*   `defaultStatus` (_string_) Default state of the consent value  
    Allowed values: `opt_in`, `opt_out`. Default: `opt_out`. Example: `opt_out`.
*   `enabled` (_Enabled_)

### Subscription

*   `subscriptionId` (_SubscriptionId_, required)
*   `siteId` (_SiteId_)
*   `title` (_SubscriptionTitle_, required)
*   `subtitle` (_SubscriptionSubtitle_)
*   `tags` (_array of Tag_)  
    Default: `[]`. Minimum items: 0. Maximum items: 10.
    
    _Example_
    
    ```
    [
      "homepage_banner",
      "user_profile",
      "checkout",
      "registration"
    ]
    ```
    
*   `channels` (_array of Channel_, required)  
    Minimum items: 1. Maximum items: 10.
    
    _Example_
    
    ```
    [
      "email",
      "sms"
    ]
    ```
    
*   `umaSubscriptionId` (_string_) Salesforce Id for the corresponding CommSubscription object in UMA  
    Minimum length: 15. Maximum length: 18. Example: `0Xl000000000000000`.
*   `consentType` (_ConsentType_)
*   `consentRequired` (_ConsentRequired_)
*   `defaultStatus` (_string_) Default state of the consent value  
    Allowed values: `opt_in`, `opt_out`. Default: `opt_out`. Example: `opt_out`.
*   `enabled` (_Enabled_)

### SubscriptionPatchRequest

*   `siteId` (_SiteId_)
*   `subscriptionId` (_SubscriptionId_)
*   `title` (_SubscriptionTitle_)
*   `subtitle` (_SubscriptionSubtitle_)
*   `tags` (_array of Tag_)  
    Default: `[]`. Minimum items: 0. Maximum items: 10.
*   `channels` (_array of Channel_)
*   `consentType` (_ConsentType_)
*   `consentRequired` (_ConsentRequired_)
*   `defaultStatus` (_string_) Default state of the consent value  
    Allowed values: `opt_in`, `opt_out`. Default: `opt_out`. Example: `opt_out`.
*   `enabled` (_Enabled_)

### SubscriptionTitle

The localized title of the subscription with markup support

Additional properties: `MarkupText`.

_Example_

```
{
  "default": {
    "markup": "Monthly <strong>Product Updates</strong>",
    "source": "Monthly <strong>Product Updates</strong>"
  },
  "fr-FR": {
    "markup": "Mises à jour <strong>Produit Mensuelles</strong>",
    "source": "Mises à jour <strong>Produit Mensuelles</strong>"
  }
}
```

### SubscriptionSubtitle

The localized subtitle of the subscription with markup support

Additional properties: `MarkupText`.

_Example_

```
{
  "default": {
    "markup": "Stay informed about new features - <a href=\"https://example.com\">Learn More</a>",
    "source": "Stay informed about new features - <a href=\"https://example.com\">Learn More</a>"
  },
  "fr-FR": {
    "markup": "Restez informé des nouvelles fonctionnalités - <a href=\"https://example.com\">En savoir plus</a>",
    "source": "Restez informé des nouvelles fonctionnalités - <a href=\"https://example.com\">En savoir plus</a>"
  }
}
```

### Tag

Filter criteria for consent subscriptions

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `homepage_banner`.

### Channel

Type: `string`.

Allowed values: `email`, `sms`, `whatsapp`. Example: `email`.

### ConsentType

Type of consent subscription

Type: `string`.

Allowed values: `marketing`, `legal`. Default: `marketing`. Example: `marketing`.

### ConsentRequired

Whether this subscription is mandatory

Type: `boolean`.

Default: `false`. Example: `false`.

### Enabled

Whether this subscription is currently enabled

Type: `boolean`.

Default: `true`. Example: `true`.

### MarkupText

The markup text for rich text content

*   `markup` (_string_, required) The rendered HTML  
    Maximum length: 2000. Example: `Monthly <strong>Product Updates</strong> - <a href="https://example.com">Learn More</a>`.
*   `source` (_string_, required) The raw markup text  
    Maximum length: 2000. Example: `Monthly <strong>Product Updates</strong> - <a href="https://example.com">Learn More</a>`.

_Example_

```
{
  "markup": "Monthly <strong>Product Updates</strong> - <a href=\"https://example.com\">Learn More</a>",
  "source": "Monthly <strong>Product Updates</strong> - <a href=\"https://example.com\">Learn More</a>"
}
```

<!-- document id=2505e39d438209092d5b5d816d39355631de45f5d96adc7c465483409d8cf1a3 url=/developer/current/en-us/commerce-cloud/solutions/guides/manufacturing-sk.md -->

# Consumer Solution for Manufacturing

![Manufacturing](https://developer.salesforce.com/docs/media/solutions/manufacturing.png)

## Power Manufacturing and Distribution With Digital Commerce

Reimagining commerce is the new business imperative for manufacturers. Why? Twofold. Manufacturers are adopting digital B2B channels for business transactions, reducing total cost of ownership (TCO), and improving direct sales team efficiency. They also want to bring products and services directly to their consumers.
For manufacturers, B2B Commerce can offer an efficient buying channel for business customers, partners, and distributors. With B2B Commerce, companies can offer product discovery and research, ordering, payments, invoicing, returns, and case management, all while the sales and service teams view and guide their customers’ digital journey.
For a consumer offering, a B2C-rich online storefront, with AI-powered merchandising, cart, and checkout, as well as integrations across digital channels and devices, is one way to build a B2C direct-to-consumer channel.

## Business Value

Digital adoption continues to rise, but only one-third of manufacturers offer online purchasing capabilities. And that’s a problem because when consumers visit a manufacturer’s website, more than half of them intend to make a purchase.Also, 50% of B2B distributors predict that more than half of their clients plan to migrate to digital over the next 3 years. [Data Source](https://www.salesforce.com/content/dam/web/en_us/www/documents/commerce-cloud/b2b-manufacturing-datasheet.pdf)
Offering a commerce channel, whether B2B or B2C, often improves customer satisfaction and lifetime value. Order frequencies can increase and online access to product information can create more upsell and cross sell opportunities. The solution simplifies contract pricing, custom catalogs, and empowers sales teams with automated processes and 360-degree views of the customer. Learn how to [5 Tips for Manufacturers Going Direct To Consumer](https://www.salesforce.com/blog/tips-manufacturing-direct-to-consumer/).
Offering a commerce channel, whether B2B or B2C often improves customer satisfaction and lifetime value. Order frequencies increase and more upsell and cross-sell opportunities arise with online access to product information. The solution simplifies contract pricing, custom catalogs, and empowers sales teams with automated processes and 360-degree views of the customer. Learn more [here](https://www.salesforce.com/content/dam/web/en_us/www/documents/commerce-cloud/b2b-manufacturing-datasheet.pdf).

## Manufacturing Use Cases

With Salesforce B2B and B2C Commerce, Agentforce Commerce offers manufacturers and distributors a proven digital commerce solution with the rich experiences and capabilities to satisfy the needs of buyers.

### B2B Commerce

Built for business users and designed for a smaller set of known customers, B2B Commerce makes it easy for customers to make large orders and then reorder products quickly. B2B Commerce features include:

- Buyer accounts with curated or customized product catalogs, and negotiated and tiered pricing.
- A digital storefront for easy browsing, search, dynamic kits, order history, and service.
- Two-click purchasing and simple reordering.
- Flexible payment options, including PO, ACH, and credit card, as well as order tracking.
- Extensibility into mobile apps and touchpoints.

### B2C Commerce

B2C Commerce is designed to attract a large amount of site traffic, especially during significant sales or holidays. A rich merchandising experience showcases the most relevant products, promotions, and experiences, while Connected Payments and Order Management integrates checkout, fulfillment, and shipping. With B2C Commerce:

- Launch a direct-to-consumer storefront.
- Implement a subscriptions offering.
- Integrate payments.
- Extend commerce to new channels and touchpoints.
- Connect order management and inventory.

For more information, see [Salesforce Industry Solutions for Manufacturing](https://www.salesforce.com/solutions/industries/manufacturing/overview/).

## Platform Features and Accelerators

Building a digital shopping experience requires a best-in-class commerce toolset to connect with shoppers anytime, anywhere. The B2C Commerce Platform toolset can help create unified, intelligent digital commerce experiences.

### Top Features for B2B Use Cases

- Customer contract uploading to the B2B Commerce site for buyers to reference.
- Updated buying permissions as scope of contract is depleted.
- Out-of-the-box integration with Salesforce Manufacturing Cloud for an all-in-one revenue management solution.
- Large B2B size orders with hundreds or thousands of stock-keeping units (SKUs).
- Negotiated and account-specific pricing.
- Configure Price Quote (CPQ)
- Configurable checkout flows
- Integrated Sales, Service, and CMS data
- Ecosystem
  - [AppExchange](https://appexchange.salesforce.com/)

### Top Features for B2C Use Cases

- [B2C Commerce Storefront Reference Architecture](https://developer.salesforce.com/docs/commerce/sfra) (Mobile First)
- Multiple and Localized Site Management
- SEO Optimization and URL Management
- Onsite Search
- Product Management (Price Books, Catalogs, Navigation)
- Marketing, Campaigns, & Promotions Engine
- Customer Profile and Account Management
- Customer Segmentation
- AB Testing
- Page Designer and Content
- Dynamic Imaging Service
- Inventory
- Analytics
- Privacy Tools
- Embedded CDN
- Integrated Payments
- Guided Selling
- Curbside Pickup
- Headless API Experience
- AI-Driven Capabilities Powered by Einstein
  - Einstein Predictive Sort
  - Einstein Product Recommendations
  - Einstein Commerce Insights
  - Einstein Search Dictionaries
  - Einstein Search Recommendations
- Salesforce Order Management
- Ecosystem
  - [Agentforce Commerce Partner Marketplace](https://www.salesforce.com/products/commerce-cloud/partner-marketplace/)
  - [AppExchange](https://appexchange.salesforce.com/)
- Agentforce Marketing and Agentforce Service Integration
- Loyalty

## Implementation Overview

Developers have two paths:

- Build on the Salesforce Commerce Platform using developer tooling, sample apps, headless APIs, and best practices.
- Launch Commerce Quick Start Commerce Solutions that provide out-of-the-box (OOTB) solutions for Direct to Consumer, Subscriptions, Channels, Grocery, Quick Service Restaurants, along with B2B Commerce. Developers can offload implementation and managed services to partners in these offerings.

### Salesforce Commerce Platform

### B2B Commerce

- [Salesforce B2B Commerce Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2b-commerce-basics)
- [Administer Salesforce B2B Commerce on Lightning Experience](https://trailhead.salesforce.com/en/content/learn/trails/administer-salesforce-b2b-commerce-on-lightning-experience)
- [Documentation Hub: B2B](https://help.salesforce.com/articleView?id=commerce.b2b_commerce.htm&type=5)
- [Manufacturing Digital Bootcamp](http://sfdc.co/digital-bootcamp)

### B2C Developer Tools

- [Agentforce Commerce Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud)
- Open Commerce API (OCAPI)
- Salesforce Commerce API
- Software Development Kits (SDK)
- Mulesoft Connector for Data API

### B2C Commerce

- [Build Your Ecommerce Site with Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/build-ecommerce-site-with-cc-digital?trailmix_creator_id=bcommerce&trailmix_slug=get-started-with-salesforce-b-2-c-commerce)
- [Develop for Salesforce B2C Commerce](https://trailhead.salesforce.com/en/content/learn/trails/develop-for-commerce-cloud)
- Headless Commerce: [Basics](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-commerce-basics), [Implementation Strategies](https://trailhead.salesforce.com/en/content/learn/modules/b2c-headless-implementation-strategies), [PWA Kit & Managed Runtime](https://trailhead.salesforce.com/en/content/learn/modules/commerce-pwa-kit-and-managed-runtime)
- [Configure On-Demand Sandboxes](https://trailhead.salesforce.com/content/learn/modules/b2c-on-demand-sandbox)
- [B2C Commerce Help](https://help.salesforce.com/s/articleView?id=cc.b2c_getting_started.htm)
- [B2C Commerce Developer Center](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide)

### Order Management

- [Getting Started with Salesforce Order Management](https://trailhead.salesforce.com/content/learn/modules/om-salesforce-order-management)
- [Salesforce Order Management Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/order_management_developer_guide_intro.htm)

### Salesforce Professional Services

Salesforce Professional Services teams help you every step of the way. With deep industry and commerce expertise, customer success experts can help plan, scope, and build your next Manufacturing project.

## Additional Manufacturing Resources

Launch a Commerce Quick Start Solution that provides out-of-the-box solutions for D2C and B2B use cases. Developers can offload implementation and managed services to partners in these offerings.
[Quick Start for Direct-to-Consumer](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-consumer-essential-goods-data-sheet.pdf)
Launch a direct-to-consumer commerce site for essential and consumer goods.
[Quick Start for B2B Commerce](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-B2b-data-sheet.pdf)
Deploy a B2B Commerce storefront for self-service ordering.
[Quick Start for Subscriptions](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/quick-start-commerce-for-subscriptions.pdf)
Give customers an easy way to stock up on products they love.
[Quick Start for Channels](https://www.salesforce.com/content/dam/web/en_us/www/documents/campaign/quick-start-commerce-solutions/commerce-for-channels.pdf)
Extend your ecommerce to new channels.

<!-- document id=5d3b99680a7d11742df8c1c08b89d93961bfb12cc6db229ae50e3fe9353fe95c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/content/b2c-content-assets-for-developers.md -->

# Content Assets

Extend a content asset with its own attributes using the metadata system.

In Salesforce B2C Commerce, a content asset is a database object with attributes. The most common usage for content assets is to contain HTML that appears on the storefront as a standalone page or embedded within another page. Content assets are typically used for information that changes infrequently such as an _about us_ page or apparel sizing tables. These HTML blocks can reference images that are stored in a special area of the file system for content-related static files.

Customize how content assets behave in B2C Commerce. The following describes customization options.

<table><col /><col /><thead><tr><th> </th><th> </th></tr></thead><tbody><tr><td>Import and export and export</td><td><p>Import the content assets you use in your application and export the content of one site into another site. You can also export the content assets of a private library into a shared library.</p></td></tr><tr><td>Attributes and system objects</td><td><p>Use attributes and system objects to define storefront content.</p> <p>The <emph>Content</emph> system object, for example, supports site-specific attributes. Several existing attributes, including the <emph>onlineFlag</emph> attribute, are site-specific. Use this feature to specify content differences between sites that share the same content assets. For example, if the contents for two brands reside in the same shared library, specify the <emph>onlingFlag</emph> attribute so that the brand-specific content only appears on the site for that brand.</p> <p>Other site-specific attributes are: <emph>searchableFlag,</emph> <emph>siteMapChangeFrequency,</emph> <emph>siteMapPriority,</emph> and <emph>siteMapIncluded.</emph></p></td></tr><tr><td>Content links</td><td><p>When you create content assets, add links to other content assets, search results, or product detail pages. B2C Commerce provides a special syntax to define these links. Optionally, use content links to link to external web sites or other B2C Commerce sites.</p></td></tr><tr><td>Content slots</td><td><p>Use content slots to show targeted content on predefined browser areas.</p></td></tr><tr><td>Content APIs</td><td>Use the B2C Commerce APIs to customize how your storefront application handles content assets.</td></tr></tbody></table></sfdocstbl>
Before you begin, consider the best practices related to potential security ramifications.

### Export Page Designer Content with the B2C Commerce CLI

For Page Designer content, you can export pages and components or validate metadefinitions directly from the terminal using the [B2C Commerce CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md). To install the tool and authenticate, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md).

```bash
# List pages in a content library
b2c content list --library SharedLibrary

# Export specific pages from a library
b2c content export --library SharedLibrary homepage about-us

# Export pages matching a regex pattern into a directory
b2c content export --library SharedLibrary "hero-.*" --regex -o ./export

# Validate Page Designer metadefinitions in a local cartridge
b2c content validate ./cartridges/my_cartridge
```

For the full command reference, see [Content Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/content.html).

## Using Content Link Functions

B2C Commerce provides a special syntax to define content link functions.

All content link functions use standard Salesforce B2C Commerce URL syntax, not the syntax used for URLs optimized for SEO. For information on this syntax, see URL Syntax.

Here are the content asset link functions:

| Function       | Description                                                                                                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$staticlink$` | Creates a static link.                                                                                                                                                            |
| `$url()$`      | Creates an absolute URL that retains the protocol of the outer request.                                                                                                           |
| `$httpUrl()$`  | Creates an absolute URL, but with the http protocol.                                                                                                                              |
| `$httpsUrl()$` | Creates an absolute URL, but with the https protocol.                                                                                                                             |
| `$include()$`  | Can be used to include the result of another server call.                                                                                                                         |
| `$link$`       | Calls the Link pipeline in the Reference Application to call pipelines. In previous versions of B2C Commerce, this was the only way to link to pipelines. This is now deprecated. |

### $staticlink$

Creates a static content link.

Syntax

`="...?$staticlink$"`

When using `$staticlink$` placeholders in content markup, the resulting generated links are absolute URLs and contain a host name. The results are regardless of the instance type, Production, or Sandbox. CDN-based URLs are also absolute URLs.

For example, the following content:

```html
<p><a href="$url('Search-Show','cgid','mens')$">Mens</a>&lt;$&quot;/&gt;&nbsp;</p>
<p><img width="400" height="400" alt="" src="images/large/10152_230.jpg?$staticlink$" /> &nbsp;</p>
```

Generates the following HTML:

```html
<p><a href="http://localhost/on/demandware.store/Sites-SiteGenesis-Site/default/SearchShow?cgid=mens">Mens</a>
</p>
<p><img width="400" height="400" alt="" src="http://localhost/on/demandware.static/Sites-SiteGenesis-Site/Site/images/large/10152_230.jpg ""alt="">
</img>
</p>
```

Example:

This example shows how to include the function in your content asset, and the results of the link in the browser.

_Asset Link_

`<img src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site/content/promo_small_1.gif?$staticlink$">`

_Result_

Displays the image in the content asset.

### $Url()$

Creates an absolute URL and retains the protocol of the outer request.

Syntax

`$url('{pipeline}' [, '{key1}', '{value1}', '{key2}', '{value2}', ...])$`

Example:

This example shows the construction of the function, how to create a link in your content asset, and how the link appears in the browser. This example creates a link to the ABOUT_US content asset.

_Function_

`$Url('Search-ShowContent', 'q', 'customer')$`

_Asset Link_

`<a title="My URL Search Link" target="_new" href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$Url('Search-ShowContent', 'q', 'customer')$"><span>URL Search Link Content Asset Link </span></a>`

_Result_

`http://[host]/default/Search-ShowContent?q=customer`

### $HttpUrl()$

Creates an absolute URL and retains the protocol "http".

Syntax

`$httpUrl('{pipeline}' [, '{key1}', '{value1}', '{key2}', '{value2}', ...])$`

Example:

This example shows the construction of the function, how to create a link in your content asset, and how the link appears in the browser. This example creates a link to the Video category page.

_Function_

`$httpUrl('Search-Show', 'cgid', 'J','psortb1','category-pos_J')$`

_Asset Link_

`<a title="My Http Link" target="_new" href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$httpUrl('Search-Show', 'cgid', 'J','psortb1','category-pos_J')$"><span>Http Link Content Asset Link </span></a>`

_Result_

`http://user-tw.inside.dw.customer.net/Video/J,default,sc.html?`

`psortb1=category-pos_J`

### $HttpsUrl()$

Creates an absolute URL and retains the protocol "https".

Syntax

`$httpsUrl('{pipeline}' (, '{key1}', '{value1}', '{key2}', '{value2}', ...))$`

Examples:

This example creates a link to the Audio category page in the Reference Application. The link is to dynamic content that uses the Search pipeline.

_Function_

`$httpsUrl('Search-Show', 'cgid', 'K')$`

_Asset Link_

`<a title="My Https Category Link" target="_new" href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$httpsUrl('Search-Show', 'cgid', 'K')$"><span>Https Category Link Content Asset Link </span></a>`

_Result_

```txt
`https://` `{host}:{port}/on/demandware.store/Audio/K,default,sc.html`
```

### $Include()$

Creates a WAInclude with the given pipeline name and creates a relative URL. Can be used to include the result of another server call. A WAInclude is the result of a call to the B2C Commerce server. Usually, this call is a pipeline.

Syntax

```xml
`$include('{pipeline}' [, '{key1}', '{value1}', '{key2}', '{value2}', ...])$`
```

Examples:

_Function_

`$include('Search-Show', 'cgid', 'J','psortb1','category-pos_J')$`

_Asset Link_

`<a title="My Include Link" target="_new" href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$include('Search-Show', 'cgid', 'J','psortb1','category-pos_J')$"><span>Include Link Content Asset Link </span></a>`

_Result_

`<wainclude url="{URL without protocol, host and port}"/>`

### $Link$

Creates a link to the Link pipeline in the Reference Application. If you extend behavior, add other start nodes to the Link pipeline. This approach is an older version of static linking that can be present in code based on previous versions of B2C Commerce.

Caution

If a user makes a mistake in the definition, such as:

```txt
`$link-something` `&test=1$ `
```

The content object can never be opened again. The correct definition is:

```txt
$link-something:test...$.
```

Syntax

`$link-{type}[:key1=value1;key2=value2; ...]$`

Example:

This example links to the ABOUT_US content asset.

_Function_

`$link-page:cid=ABOUT_US$` _Asset Link_

`<a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$link-page:cid=ABOUT_US$" title="Read more about us">`

_Result_

```txt
http://{host}/About.Us/ABOUT_US,default,pg.html
```

### Create Content Asset Links

Create links to other sites or content assets.

1.  Decide if you want to link to:

    - Another site
    - Static content in your site - can be an image, product page, or article
    - Dynamic content in your site - is content that is determined when the link is clicked. For example, to link to a set of search results, you create a link to a pipeline that performs the search and returns the search results. Developers for your site can tell you the name and parameters of available pipelines.

2.  Determine the type of link to create.

3.  Open your browser and look at the URL of the page or image you want to link to.

    - If your URL looks like a URL outside your domain (www.otherstore.com), link to another site's domain.
    - If your URL looks like a category page or search result, use the Product or Category page URL hyperlink feature.
    - If your URL looks like an image, product or content asset, link to a static content asset.

4.  When creating or editing a hyperlink within a content asset, select one of these link types:

    - URL
    - Product detail page URL
    - Category page URL
    - Content page URL
    - Link to anchor in the text
    - E-Mail
      When you edit a hyperlink in the HTML editor using the Link editor, the link value you enter isn't used. The link text only changes when changing the:

    - Product SKU of a product detail page URL: if the product exists for the SKU or is set to the value the user entered, the link text is changed to the display name of the product.
    - Category ID of a catalog category page URL: if a catalog category exists for the ID or is set to the value the user entered, the link text is changed to the display name of the catalog category.
    - Content Asset ID of a content page URL: if a content asset exists for the given ID or is set to the value the user entered, the link text is changed to the display name of the content asset.
    - Search Phrase of a keyword search URL: the link text is changed to the new search phrase.
    - Protocol or the URL of a normal URL and the link text was equal to the previous protocol plus the URL: the link text is changed to new protocol plus the new URL.

5.  For Product, Category, and Content page URLs, enter a product SKU, category ID (of a category in the storefront catalog) or content asset ID (of an asset in the site library) respectively. The system generates the appropriate URL. If you create a hyperlink, the link text defaults to the display name of the product, category, or content asset in the currently selected locale. This is from the HTML view.

Content asset links for images are usually to folders in your image library. You can't use the content asset editor to dynamically create an absolute URL for an image in a content asset link that includes the full path to the image. Instead, you must either post-process the markup of your assets by using placeholders such as `#hostname#`. The placeholders are replaced with the correct value programmatically before outputting the markup or hard code the full image URLs from production into your asset. This is only a consideration if you are including content assets in emails.

### Linking to Another Site URL

You can include another site URL in your content asset, as you would for any HTML page.

This example links to the Salesforce B2C Commerce homepage.

`<a title="Visit the B2C Commerce Homepage" href="http://www.demandware.com/">www.demandware.com</a>`

#### Linking to a Pipeline

You can link to any pipeline using the $url()$, $httpUrl()$, $httpsUrl()$, or $include()$ content link functions. You can also link to the SiteGenesis Link pipeline using the $link$ function.

Each pipeline requires different information to be passed to it. You specify this information in the link.

In this example, you are linking to the link pipeline product subpipeline and sending it a product id.

`<a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$link-product:pid=S1917353$">Microsoft Xbox - Game console</a>`

To change this link to a different product, change the value for the pid argument:

`<a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$link-product:pid=%60S2364458%60$%60%20%60">Nikon UR E17 - Lens adapter</a>`

#### Linking to Static Content

Static content includes products, content assets, images, and email links.

The $staticlink$ functionality is the best way to create a URL to a static file in a library or catalog. This approach passes the correct unit, product, catalog, or library. The result is the creation of the correct static content URL. If you prefer, use the other content link functions.

Product Link Example

`<a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$link-product:pid=S1917353$">Microsoft Xbox - Game console</a>`

Content Asset Link Example

`<a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/$link-page:cid=ABOUT_US$" title="Read more about us"> <span>About Us</span></a><span class="divider">|</span></a>`

Image Link Example

`<img height="356" width="705" src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/demo/content/homepage_705_356_flatpanel.gif?$staticlink$" alt="Flat Panel Promotion" />`

Email Link Example

`<a href="mailto:info@salesforce.com" title="Contact Us via EMail">info@salesforce.com</a>`

### Content Asset Link Examples

These scenarios include several examples of creating or updating links in content assets.

#### Updating an Existing Link

You can easily update an existing link by changing the values that determine the category, content asset, image, or page.

To change a category Link

Find “cgid” (category ID) and change the next value to the category ID you want to link to. If the name of the category is included in the link, find the name and change it.

Change...

```xml
<a title="Category Search Link" target="_new" href="$httpUrl('Search-Show', 'cgid', 'P')$">
<span>Pans Search Link</span></a>
```

To

```xml
<a title="Category Search Link" target="_new" href="$httpUrl('Search-Show', 'cgid', 'J')$">
<span>Jams Search Link</span></a>
```

To change a product Link

Find “pid” (product ID) and change the next value. There can be more than one type of link, but they all use pid in the link to indicate a product.

Change...

```xml
<a title="MapSource BlueChart" target="_new" href="$httpUrl('Product-Show', 'pid', 'S1965524')$">
<span>MapSource BlueChart</span></a>
```

To

```xml
<a title="Terrain Navigator" target="_new" href="$httpUrl('Product-Show', 'pid', 'S2150489')$">
<span>Terrain Navigator</span></a>
```

To change a content asset Link

Find “cid” (content asset ID) and change the next value. All links use cid in the link to indicate a content asset.

Change...

```html
<a href="$httpUrl('Page-Show', 'cid', 'about-us')$"> About Us</a>
```

To

```html
<a href="$httpUrl('Page-Show', 'cid', 'gift-details')$"> Gift Details</a>
```

To change an image Link

Find “src” and change the image path.

Change...

```html
<img
  width="750"
  height="715"
  alt=""
  usemap="#instyle"
  src="images/asSeenIn/InStyle.jpg?$staticlink$"
/>
```

To

```html
<img
  width="750"
  height="715"
  alt=""
  usemap="#people"
  src="images/asSeenIn/People.jpg?$staticlink$"
/>
```

To change an email Link

Find “mailto:” and change the email address.

Change...

```html
<a href="mailto:rgeiger@salesforce.com">rgeiger@salesforce.com</a>
```

To

```html
<a href="mailto:freinhardt@salesforce.com">freinhardt@salesforce.com</a>
```

## Content Data Administration

When replicating content asset libraries, shared and private libraries appear differently in the Replication Tasks page.

For example:

| Section on Replication Tasks page... | Looks like...                                                 |
| ------------------------------------ | ------------------------------------------------------------- |
| Global section                       | <ul><li>Libraries</li><li>Library1</li><li>Library2</li></ul> |
| Site1 section                        | <ul><li>Site</li><li>Content Library</li></ul>                |

The assignment of libraries to sites is done through the site-level _Site Preferences_ replication task. The _Site Preferences_ replication task makes it possible to:

- create a shared library on Staging.
- assign it to a site A on Staging.
- replicate the library itself without the site being changed to actually use the library on the production instance.

WebDAV

You can access content asset static files within a library using WebDAV. See the instructions by selecting **Administration > Site Development > Development Setup.**

The URL is specified as follows:

```txt
https://host/on/demandware.servlet/webdav/Sites/Libraries/{Site name}
```

The value after /Libraries/ is interpreted as either a site ID or a shared library ID. If it's a site ID, the URL references the private library of the specified site. If not, then Salesforce B2C Commerce attempts to find a shared library with that ID. If the value is neither, the operation fails.

## Content Asset APIs

You can use these Salesforce B2C Commerce APIs to customize your storefront application relative to libraries and content assets for both private and shared libraries.

### B2C Commerce Script APIs

These APIs support both private and shared libraries.

| Class                 | Method                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dw.content.ContentMgr | <p><ul><li><code>getSiteLibrary();</code></li><li><code>getContent(String id);</code></li></ul></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| dw.content.Content    | <p><ul><li><code>getOnlineFlag();</code></li><li><code>isOnline();</code></li><li><code>getSiteMapChangeFrequency();</code></li><li><code>getSiteMapPriority();</code></li><li><code>getSiteMapIncluded();</code></li><li><code>getSearchableFlag();</code></li></ul></p>                                                                                                                                                                                                                                                                                                                                                   |
| dw.web.URLUtils       | <p>URL staticURL(String context, String contextID, String relPath); - use to specify the ID of any shared library in B2C Commerce. It isn't possible to generate a URL that points to the private library of another site.</p>                                                                                                                                                                                                                                                                                                                                                                                              |
| dw.io.File            | <p>File access to all libraries, folders, and content, for example:</p><p><code>LIBRARIES/{Library Name}(/...)</code></p><p>B2C Commerce uses a fall-back mechanism to determine the site library path. It first checks to see if the token represents the ID of a site in B2C Commerce. If it does, it constructs a file path within the private library of that site. If the token isn't the ID of a site, then B2C Commerce interprets it as the ID of a shared library within B2C Commerce. Use this mechanism to construct file paths for private and shared libraries (as long as there are no naming conflicts).</p> |

### Pipelets

These pipelets support both private and shared libraries: GetContent, ImportContent, and ExportContent

<!-- document id=3b6e4b35c4e80f320549f50baadd67add5f45c89df185bf3feab5083af9a5527 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-content-cache.md -->

# Content Cache

Configure caching to improve your site's overall performance and can minimize customer wait time.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Static and Page Cache

B2C Commerce uses two caches for different kinds of content, each of which can be configured and invalidated separately.

- Static content cache: used to cache images, icons, CSS style sheets, and other non-dynamic assets.
- Page cache: used to cache HTML pages generated from ISML templates when `<iscache>` is enabled.

Using page caching can improve your site's overall performance and can minimize customer wait times. The web server caches content to improve response times. Requested pages are stored in the cache and can be presented immediately upon request. Use caching on portions of pages to manage the customer experience while satisfying business requirements related to data changes like pricing and promotions.

B2C Commerce supports the cross-site sharing of static files. [Configure Time-To-Live (TTL)](#cache-configuration) for this globally cached static content.

## Adding ISML Tags to Templates

For a page on your storefront to be cached, you must add the ISML tag `<iscache>` to the appropriate template. The tag can be located anywhere in the template. If the `<iscache>` tag occurs several times in a template, the `<iscache>` tag with the lowest cache settings (either minimal cache duration or status=”off”), including all local template includes, determines the caching behavior of the resulting page.

**note:** For Storefront Reference Architecture (SFRA) implementations, use middleware for caching configuration. See [SFRA Features and Components](https://developer.salesforce.com/docs/commerce/sfra/guide/b2c-sfra-features-and-comps.html#middleware) and [cache.js](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture/blob/master/cartridges/app_storefront_base/cartridge/scripts/middleware/cache.js) for details.

When including other templates in a template, make sure that the included template doesn't contain an `<iscache>` tag that conflicts with your original settings.

Examples

```
<iscache type = "relative" hour = "24">
```

**note:** If the page caching preference isn't enabled in Business Manager, the `<iscache>` tag is ignored when it's encountered in a template.

## Page Caching Best Practices

1.  Caching is controlled on a per page basis, via the ISML template for the page.
2.  Caching duration is specified in the page, typically 24 hours.
3.  Frequently changing pages benefit from a shorter caching period.
4.  Stored pages are only invalidated and a new one pulled from the Application Server if any of the following happen:
    - the defined caching time is exceeded
    - a replication is performed
    - the merchant triggers an explicit page cache invalidation in Business Manager
5.  To see changes immediately, disable page caching on Sandboxes and Staging instances.
6.  Portions of pages can be cached separately. Assemble a page from snippets with different caching attributes using remote includes. Each part:
    - has to be a result of a pipeline request to the application server
    - is included using the `<isinclude url="">`syntax
    - can have different or no caching tags
    - all sections are assembled by Web Adapter and responded to client
7.  In general, don't cache pages that show buyer or session information.
8.  If you see certain trends in analytic data, you might decide to alter the time length for caching of static content.
9.  If you have a specific type of error in production, you might need to invalidate caching briefly to do a hot fix.

## Cache Configuration

Configure Static Content and Page Cache.

### Configure the Static Content Cache

The web server caches static content assets, such as images, icons, and CSS style sheets, in two ways. The global static cache holds content shared among sites at the organization level, and site-specific static caches hold content belonging to private site libraries.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

    - To configure the global cache for shared static content, click **Global Static Cache**.
    - To configure the static cache for a site (including the Business Manager site), click the site, then click the **Cache** tab.

2.  Select the instance type.

3.  Enter the Time To Live in seconds. The web server holds data for the TTL before requesting it again from the application server.

    - The default is 30 days (2,592,000 seconds).
    - For production instances, the minimum TTL is 24 hours (86,400 seconds).
    - To disable caching of static files, enter 0.
    - Setting the TTL affects both the static content and page caches.

### Configure the Page Cache

The web server caches HTML pages generated from ISML templates that are configured for caching. You configure page caching per site. The Time To Live (TTL) for page data is the same as the TTL for static content on the site.

The current instance type restricts cache settings as explained here.

| Current Instance Type  | Cache Restrictions                                                |
| ---------------------- | ----------------------------------------------------------------- |
| Sandbox or Development | None                                                              |
| Staging                | Values for the Production setting can’t be changed                |
| Production             | The page cache can’t be disabled, and the minimum TTL is 24 hours |

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

2.  Click the desired site (including the Business Manager site), then click the **Cache** tab.

3.  Select the instance type.

4.  Enter the Time To Live in seconds. The web server holds data for the TTL before requesting it again from the application server.

    - The default is 30 days (2,592,000 seconds).
    - For production instances, the minimum TTL is 24 hours (86,400 seconds).
    - To disable caching of static files, enter 0.
    - Setting the TTL affects both the static content and page caches.

5.  Check the **Enable Page Caching** box, and click **Apply**.

## Create a Page Cache Partition

All pipelines in a partition have their page caches invalidated together. As with a full page cache invalidation, the cache is gradually invalidated over 15 minutes. A pipeline can only be included in one partition. Create a maximum of 10 partitions. Each partition can contain up to 20 pipelines. A partition can get replication tasks assigned, that if chosen for a replication process that has page cache invalidation strategy 'Invalidate Impacted Cache Partitions' selected, causes the partition to be invalidated at the end of the replication process.

Before creating page cache partitions, understand the relative execution time of each pipeline, to avoid putting too many pipelines in the same partition. Also, be aware of what pieces of the storefront are cached.

The page cache for remote includes and `iscomponent` elements aren’t automatically invalidated when the page cache for the pipeline that contains the rendering template is invalidated. Therefore, if you want to refresh the content on the Home page by invalidating the Home-Show pipeline, and you have remote includes to Content-Show, then you must also explicitly invalidate the Content-Show pipeline.

Pipelines are only allowed in one partition, but you might want to refresh different page types, such as the home page and product detail page. Therefore, Salesforce recommends that you place pipelines used in remote includes in a separate partition. Then, invalidate the main pipelines of the page in one partition and the content or other remote includes in the other.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites** > **site**.

2.  From the Cache tab, under Page Partitions, click **Add Partition**.

3.  Enter a unique, meaningful ID for the partition. It can only contain characters allowed in URLs.

4.  Enter a name that describes the type of pipelines you’re including in your partition. For example: slot configurations and slot content.

5.  From the Pipelines tab, add pipeline names or remove existing ones.

    Use the Pipeline-StartNode name, for example: `Home-Show`.

    Pipeline names can be for the current site or for remote includes. A pipeline can only appear in one partition. Modifying an existing partition by removing a pipeline sets the page cache clear time to the partition clear time, which can invalidate cached content.

    If your storefront is based on SiteGenesis, import the partition definitions included with SiteGenesis.

    If your storefront is based on SFRA or SiteGenesis, import the partition definitions included with SFRA or SiteGenesis.

6.  From the Tab Replication Tasks tab, choose any Global or Site-specific replication tasks.

    If a replication process that has a page cache invalidation strategy of 'Invalidate Impacted Cache Partitions' is selected, the partition is invalidated at the end of the replication process.

7.  Click **Save**.

## Invalidate a Page Cache Partition

Invalidating a page cache partition empties the cache for each pipeline. The cache is only refreshed when the pipeline is called and the appropriate page rendered. To lessen the performance impact on the storefront, the cache is invalidated over a period of 15 minutes.

If you want to use the `InvalidateWebCache` pipelet to invalidate specific partitions across all of your sites, use the same name for all those partitions. The pipelines included in these definitions can differ, as long as the names of the partitions are the same.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites** > **site** > **Cache**.

2.  On the Manage Sites page Cache tab, click **Invalidate** beside a page cache partition name.

    If a pipeline in the partition is invalid or missing, the other pipeline caches are still invalidated. If you want to minimize impact on storefront performance when you invalidate more than one page cache partition, wait until the 15-minute transition phase is over for each partition before invalidating the next.

    The `Other Pipelines` partition can be used to invalidate cached pipeline output for all pipelines not included in any partitions.

### Invalidating a Page Cache Partition Programmatically

Create a pipeline to run in a job to invalidate one or more page cache partition IDs. It can invalidate partitions with matching names in different sites.

Use the `InvalidateWebCache` pipelet to invalidate a page cache partition, or a list of partitions.

- `SiteID` : specifies which site to invalidate. If not specified, the site context is used to invalidate partitions for the current site. Specifying `"ALL`” invalidates all sites in the organization.

- `InvalidateStaticCache` : when set to `true`, the static content cache and the entire page cache are invalidated, regardless of the other parameters.

- `InvalidatePageCache`: when set to`true`, the system invalidates all or part of the page cache, depending on the other parameters specified.

- `PageCachePartitionIDs` : if specified, only invalidates the partitions that are specified as a comma-separated list. For example, if `"Homepage,SlotsContent"` is specified, then the `Homepage` partition and `SlotsContent` partition are invalidated. Don't include spaces between the comma-separated partition IDs.

**note:** The 'Other pipelines' portion of the cache can't be invalidated via the `InvalidateWebCache` pipelet, as it doesn't have an ID.

## Cache Clearing Behavior

When data or code replication is performed, a site cache invalidation is automatically initiated. When you initiate a cache invalidation manually, the system begins a process of invalidating cached data. To reduce impact to performance and to minimize potential disruptions, cache eviction is completed over a period of 15 minutes (referred to here as the "Clear Period").

**important:** Repeatedly triggering cache invalidation within this "Clear Period" interferes with complete eviction of the cache. Frequent invalidation requests don't speed up the eviction as one might expect but can actually prevent it from invalidating in entirety. Despite multiple attempts to clear the cache, the site may retain outdated data since each clearing attempt resets the "Clear Period".

Types of cache invalidation that use this process:

- Cache invalidation (Entire Site and / or Partition) via Business Manager: Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites** > **Cache**.
- Jobs that trigger a Page Cache Invalidation

### Cache Clearing Best Practices

- Only perform cache invalidation when necessary.
- After initiating a cache invalidation request, allow the "Clear Period" to elapse for the system to complete the eviction process.
- For use cases which require frequent updates to the site, for example: frequent price changes, consider using Granular Replications instead of data replication to avoid waiting for the "Clear Period" and for the site to be updated.
- If you're performing frequent cache invalidation due to stale data, investigate the root cause of the stale data to avoid requesting repeated cache invalidation.
- A good starting point to troubleshoot a site serving stale cached data is by reviewing scheduled jobs in Business Manager that may be frequently triggering cache invalidation or cache partition invalidation.
- For additional information, see:
  - [Page Caching Best Practices](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-content-cache.html#page-caching-best-practices)
  - [Invalidate a Page Cache Partition](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-content-cache.html#invalidate-a-page-cache-partition)
  - [Granular Data Replication](https://help.salesforce.com/s/articleView?id=cc.b2c_granular_data_replications.htm&type=5)

## Quick Fixes or Emergency Edits of Production Content

You might occasionally need to make unplanned edits to content on the Production instance that must be live within a short period of time. Configure page cache partitions to make these edits and replicate them more safely with less effect on site performance.

### What Are Page Cache Partitions?

A page cache partition is the page cache for a group of pipelines. If the partition is invalidated, then the page cache for those pipelines is invalidated, but no other page caches are invalidated.

## Why Are Page Cache Partitions Useful?

While it is possible to edit products directly in Business Manger on a Production instance to make a quick fix, if the page that shows the product is cached, it might take a long time until the change appears in the storefront. To make the change appear faster, you must invalidate the page cache for the entire site. This makes the change go into effect within fifteen minutes, but has a significant performance impact, because the entire page cache is regenerated.

Changes made directly to the Production instance are outside the normal workflow, which allows for testing and previewing content. It also requires more work to get the Staging and Production instance data back in sync, which must happen before the next replication of data from Staging to Production.

Salesforce recommends that you configure page cache partitions and replication jobs for quick fixes of product or content information for a better workflow and site performance. Configuring partitions requires the permissions and expertise of your administration or operations staff.

### Configuring Page Cache Partitions

1.  Configure page cache partitions on your Staging instance.

    **note:** Changing your page cache configuration causes a reset of the cache clear time and should be done infrequently. Every time a partition is updated (pipelines added or removed) the page clear time of the updated partition and site is set to the shorter value of the partition or site. When a partition is deleted, the site's page clear time is set to the partition's page cache clear time if it's shorter. The clear time for the page cache can be seen as the _last invalidated_ date for page cache of the site.

2.  Replicate the cache settings site-level replication task to the Production instance. This replicates the required configuration to the Production instance. When replicated, you only need to replicate it again if you change the configuration of the partitions.

    **important:** Replicating the cache settings causes a full page cache invalidation across all sites.

### When You Need to Make a Quick Fix:

1. Change Product or Search Information

   Make the quick fix to product information on your Staging instance.

2. Configure Replication Jobs Without Page Cache Invalidation

   Create a replication job for your changes where the Page Cache option is set to **Do not invalidate**. See New Data Replication Process Step 1 General page.

   Selecting **Don't invalidate** for your replication process means that the page cache for the entire site isn't invalidated, as it normally is when you replicate. Because the entire page cache isn't invalidated you will see no performance effect on the storefront because of the replication. You will also not see any of your changes reflected in the storefront.

3. Invalidate Page Cache Partitions

   After replicating your changes to product or search, you invalidate the page cache partition manually in Business Manager on the Production instance.

   **note:** The page cache doesn't include the static content cache, which must be invalidated separately. The developers in your organization can tell you what pipelines to include in your partition definitions.

<!-- document id=a52298000d9a52240bfa6cc897791751df0644e2fc4ac6306ca30aac25c40294 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-caching-content.md -->

# Content Caching

Storefront Next uses a multi-tier strategy for caching content at different layers in the server architecture. First, the browser caches static content where it's served directly to end users. Then the site eCDN (Cloudflare) caches static content for globally distributed edge caching. Finally, storefront configuration and metadata are cached in Managed Runtime (MRT) for application-level caching. As requests move downstream, the B2C Commerce layer caches metadata, while B2C Commerce API (SCAPI) caches API response data.

![Storefront Next caching](https://developer.salesforce.com/docs/media/sfnext/sfnext-caching.png '{"class": "image-xl"}')

## Static Content

Static content refers to files and resources, such as JavaScript bundles, on a storefront site that are unchanged regardless of who requests them or when they're accessed. Storefront Next delivers static content to users as-is, without personalization or server-side processing. CDNs and the browser cache static content publicly as immutable, URL-addressable resources, typically with a greater than 99% cache hit ratio.

## Metadata Caching

Managed Runtime caches site and page metadata for faster page rendering.

## SCAPI Request Caching

Storefront Next performance and scalability depend heavily on web-tier caching of SCAPI responses.

SCAPI can store eligible `GET` responses in the web-tier cache and the content delivery network (CDN) cache. [Enable page caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#enable-caching) in Business Manager to use this implicit caching. Non-personalized response classification is a separate safety decision. See [Classify Non-Personalized Responses](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md#classify-non-personalized-responses).

**note:** Make only the necessary expansions in the request, as certain expansions have short cache entry live times. For example, unnecessarily including the "availability" expansion in requests to the Products and Product Search APIs reduces the cache hit rate drastically and negatively affects overall request performance. If no expand parameter is specified, then all expansions are selected.

For cache eligibility, time-to-live values, and cache-status headers, see [SCAPI Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) in the _B2C Commerce API Guide_. Cache status shows how a cache handled a response. It doesn't prove that the response is safe for all shoppers.

## HTML Documents

To support personalization, Storefront Next doesn't cache HTML documents.

<!-- document id=66e5c95403c64bb07129859cb854af4b54ce79dbf54b721466470f09606eabf9 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-contributions.md -->

# Contribute to SFRA

Fix or report a bug or contribute to the SFRA cartridges.

## Reporting a Bug or Requesting a Change

If you find a bug, let us know by entering the bug for the Storefront Reference Architecture repository.

## Fixing Bugs and Contributing to the Cartridge

Do you have some extra time and want to contribute? This section talks about the process of working on issues or adding functionality.

### Downloading and Developing

1.  Fork the Storefront Reference Architecture repository.
2.  Clone your fork to your local machine.
3.  Set your Git upstream to the Storefront Reference Architecture repository.
4.  Create a branch and add your code.

### Testing Locally

1.  Make sure to run `eslint` to lint your code before committing. If you want to contribute regularly, consider adding a Git hook to automatically lint your code before you commit.
2.  Run the automation tests locally.

### Submitting a Pull Request

1.  Push your changes.
2.  Submit the pull request to the main branch.
3.  Give read access permission for your fork to the Jenkins account and the testing team. See following section.
4.  Check whether the pull request has passed the automated testing.

### Giving Read Access Permission For Your Fork

1.  In GitHub, go to the page for your fork.
2.  In the left sidebar, click **Settings**.
3.  Click **User and group access**.
4.  Grant read access to the following users: `sg-jenkins`.

### What Happens After You Submit a Pull Request?

B2C Commerce Engineering reviews your pull request to determine if it's something we can pull into the code. If the change isn't accepted, the request is declined with a comment. If the change is accepted and passes all tests, the change is merged into the SFRA main branch.

**note:** If further changes are needed before the pull request to be accepted, Engineering leaves a comment on the pull request.

### Contacting The Team About a Pull Request

If you have a question about the status of a pull request, contact Engineering by adding a comment to the pull request.

### Making a Change to a Pull Request

If your pull request fails tests, troubleshoot the problem and change the pull request. To debug test failures, request Engineering to send you the log from the test failures. When you have committed your changes, rebase and remove the extra commit message.

```
git commit -a -m "Update1"
git rebase -i HEAD~2 git push origin *branchname* --force
```

<!-- document id=2fe16fba9e138d38be1de14b25e571a86f2599e435815c0f5c52343a1a351e39 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc.md -->

# Control Center

Use Control Center to monitor the state of Commerce Cloud instances and take appropriate action. Using Control Center, initialize (reset), start, stop, and restart instances. View utilization statistics (and optionally download these statistics to a .csv file). Optionally, view the Control Center audit log. This topic applies to B2C Commerce.

<!-- document id=4b6c3ff2dc014f03c2ca31f9273a49a8c9481e3bdd5d5cea768d600f1adcabc9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_roles.md -->

# Control Center Roles for B2C Commerce

To use Control Center, you need an account in Account Manager. An account administrator for your org then assigns the appropriate Control Center roles.

**note:** If you don't have an account in Account Manager, ask your account administrator to create one for you.

There are two predefined Control Center roles.

- **Control Center Administrator**—gives the account full administrative control over your organization's instances in Control Center. This Administrator role also gives the account the ability to configure permissions for other users in Control Center. Assign at least one person in the organization the Control Center Administrator role. This person can then log into Control Center, configure permissions for other users, and define fine-grained roles.
- **Control Center User**—enables the account to perform any Control Center actions permitted by a Control Center Administrator.

In addition to the predefined roles, a Control Center Administrators can create fine-grained roles for a subset of Control Center users. For a large organization, roles can save you time. For a small organization, it can be easier to configure instance-level permissions for each user. Roles are also beneficial when you assign the same set of permissions to a group of users.

A fine-grained role binds one or more users to a set of instance-level permissions. For example, an administrator wants to give 10 users permission to three sandboxes. One approach is to repeat the instance-level permissions for each user, which requires the administrator to specify instance-level permissions 30 times. If the administrator defines a role, the admin specifies instance-level permissions only three times, once per instance. The administrator can then assign all 10 users to that single role.

An administrator can also use a combination of instance-level permissions and roles).

<!-- document id=0c98ab24513c3256cf97a735345bd1d7b6b5e486d2aabf553f14dcc913fd0455 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-working-with-controllers.md -->

# Controllers

Controllers are server-side scripts that handle storefront requests. Controllers manage the flow of data in your application, and create `ViewModels` to process each storefront request as a `route` and generate an appropriate response. For example, in a storefront application, clicking a category menu item or entering a search term triggers a controller that renders a page.

Controllers are written in JavaScript and Salesforce B2C Commerce script. They must conform to the CommonJS module standard.

A controller's file extension can be either .ds or .js. Controllers must be located in the `controllers` folder at the top level of the cartridge. Exported methods for controllers must be explicitly made public to be available to handle storefront requests.

Example: SFRA Base Cartridge Controller Hello.Js

```javascript
"use strict";

var server = require("server");
var cache = require("*/cartridge/scripts/middleware/cache");

server.get("World", cache.applyDefaultCache, function (req, res, next) {
  res.render("helloworld", {
    Message: "Hello World! Again.",
  });
  next();
});

module.exports = server.exports();
```

Controllers can use `require` to:

- Import script modules. Any B2C Commerce script can be made into a CommonJS module and required by a controller.
- Import B2C Commerce packages, instead of using the `importPackages` method. This approach is the recommended way to reference functionality from a controller. Use the require method to import a single B2C Commerce class. For example:

  ```js
  var rootFolder = require("dw/content/ContentMgr").getSiteLibrary().root;
  ```

While it isn't best practice, controllers can also:

- Call other controllers. We don't recommend that controllers call each other, because controller functionality is self-contained to avoid circular dependencies. Sometimes, however, such as calling non-public controllers during the checkout process, it's unavoidable.
- Call pipelets. We strongly discourage calling pipelets from within a controller. However, it's allowed while there are still pipelets that don't have equivalent B2C Commerce script methods.
- Import packages. We discourage this approach because it doesn't use standard JavaScript patterns. This approach is Rhino-specific.
- Call pipelines that don't end in interaction continue nodes. This technique is only intended for use with existing link cartridges and is highly discouraged for general development.

  **note:** It isn't currently possible to call pipelines that end in interaction continue nodes.

## Request URLs

A request URL for a controller has the format `controller-function`. For example, the request URL for the Hello.js controller World function looks like:

```
https://localhost/on/demandware.store/Sites-RefArch-Site/default/Hello-World
```

For more information, see [B2C Commerce URL Syntax Without SEO](https://help.salesforce.com/s/articleView?id=cc.b2c_digital_url_syntax_without_seo.htm).

## Reserved Names for Controllers

B2C Commerce has several system names that are reserved and can't be used for custom controllers and their functions. For a full list, see System Pipelines and Controllers in our [Legacy Developer Documentation](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/LegacyDeveloperDocumentation.pdf).

## Global Variables, Request Parameters, and Page Meta Data

SFRA uses the `server.req`and `server.res` objects for request and response data. While global variables are still available, we don't recommend that you use them.

## Debugging

Almost any JavaScript-related error gets logged in the `customerror_* log` files, including errors from B2C Commerce scripts and controllers. The `error_*` log files contain Java-related errors on B2C Commerce, and are probably less useful to non-B2C Commerce employees

The `Error.js` controller services uncaught errors. By default, B2C Commerce returns a 410 error, which indicates that the resource is no longer available. If you prefer 404, it's fine to use as long as the related ISML template doesn't include `<isslot>`, `<iscomponent>`, or `<isinclude>` tags. When you want to handle these errors explicitly, use `try/catch` statements.

## Best Practices

Only require modules when you need them, not at the top of a module.

## Using with OCAPI

Build a mobile or native app in addition to your storefront. If you want to create modules that work both for a desktop storefront and a mobile app, use hooks.

<!-- document id=9b459026fbe2b2ec80c38f69522b56ba7ba6699369f6186777e57dfdf094c6f6 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/cors.md -->

Cors

# Cors

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/cors/cors-oas-v1-public.yaml)

## API Overview

The CORS Preferences API allows you to manage your Cross-Origin Resource Sharing (CORS) preferences.

By specifying which domains are permitted to access a site, you can define exceptions to the same-site policy that browsers would otherwise enforce.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.cors-preferences.rw` (read-write access) or `sfcc.cors-preferences` (read-only access) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Manage CORS configuration

You can use the preferences/cors endpoint to retrieve, set, or delete your configuration for CORS origins.

### Usage Notes

1.  This configuration is made per client ID and site.
2.  All known domain names and aliases are added to the list automatically and do not need to be configured for CORS explicitly.
3.  If a configuration is absent, CORS will not be active. To enable cors for a client without specifying custom origins, configure the client and site with an empty origin list. The known domain names and aliases will still apply.

**Version:** 1.1.1

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/configuration/cors/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.cors-preferences: CORS preferences READONLY scope
    *   Scope sfcc.cors-preferences.rw: CORS preferences scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Return all CORS preferences for the given site.

`GET /organizations/{organizationId}/cors`

Operation ID: `getCorsPreferences`. Security: AmOAuth2 (sfcc.cors-preferences, sfcc.cors-preferences.rw).

Return all CORS preferences for the given site.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** CORS preferences for the given site returned successfully.
    
    Media type: `application/json`. Schema: `CorsPreferences`.
    
    _Example: getCorsResultWithMappingsExample_
    
    ```
    {
      "corsClientPreferences": [
        {
          "clientId": "12345678-90ab-cdef-fedc-ba0987654321",
          "origins": [
            "http://foo.com",
            "https://foo.bar.com",
            "myapp://example.com"
          ]
        }
      ]
    }
    ```
    
    _Example: getCorsResultWithoutMappingsExample_
    
    ```
    {}
    ```
    

### PUT Create or replace all CORS preferences for the given site.

`PUT /organizations/{organizationId}/cors`

Operation ID: `updateCorsPreferences`. Security: AmOAuth2 (sfcc.cors-preferences.rw).

Create or replace all CORS preferences for the given site.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CorsPreferences`.

_Example CorsPutBodyExample: same as GET /organizations/{organizationId}/cors 200 response._

#### Responses

*   **200** CORS preferences for the given site replaced successfully.
    
    Media type: `application/json`. Schema: `CorsPreferences`.
    
    _Example updateCorsResultWithMappingsExample: same as GET /organizations/{organizationId}/cors 200 response._
    
    _Example: updateCorsResultWithoutMappingsExample_
    
    ```
    {}
    ```
    
*   **201** CORS preferences successfully created for the given site.
    
    Media type: `application/json`. Schema: `CorsPreferences`.
    
    _Example updateCorsResultWithMappingsExample: same as GET /organizations/{organizationId}/cors 200 response._
    
    _Example: updateCorsResultWithoutMappingsExample_
    
    ```
    {}
    ```
    
*   **400**
    
    Possible reasons:
    
    *   The clientId is missing.
    *   The domain names in the origins list are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: CorsBadRequestMissingClientIdExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Submitted content was invalid: Client ID must not be null or empty",
      "parameter": "Submitted content was invalid: Client ID must not be null or empty"
    }
    ```
    
    _Example: CorsBadRequestInvalidDomainNamesExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Submitted content was invalid: Origins must contain only valid domain names in the format '<scheme>://<domain>.<tld>', without a port or path.",
      "parameter": "Submitted content was invalid: Origins must contain only valid domain names in the format '<scheme>://<domain>.<tld>', without a port or path."
    }
    ```
    

### DELETE Delete all CORS preferences for the given site.

`DELETE /organizations/{organizationId}/cors`

Operation ID: `deleteCorsPreferences`. Security: AmOAuth2 (sfcc.cors-preferences.rw).

Delete all CORS preferences for the given site.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** CORS preferences for the given site deleted successfully.

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### CorsPreferences

Document representing all CORS preferences for a given site

*   `corsClientPreferences` (_array of CorsClientPreferences_) List of client-specific CORS preferences

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CorsClientPreferences

Document representing all CORS preferences of a specific client

*   `clientId` (_string_, required) Client ID  
    Pattern: ^\[-a-zA-Z0-9\]+$. Example: `12345678-90ab-cdef-fedc-ba0987654321`.
*   `origins` (_array of string_, required) List containing allowed origins in the format '://.'  
    Items: Pattern: ^\[a-zA-Z\_0-9\]\[-.+a-zA-Z\_0-9\]+://\[-.a-zA-Z\_0-9\]{1,253}$.

<!-- document id=4d69c76dffffad637404212e85db0bf1b268e3c64f1e5ec2c8c1120b2060eca5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/cors.md -->

# CORS (Cross-Origin Resource Sharing)

Cross-Origin Resource Sharing is a browser technology specification that defines ways for a web server to allow its resources to be accessed by a browser application from a different origin domain. Such access would otherwise be forbidden by the [same origin policy](https://en.wikipedia.org/wiki/Same-origin_policy). CORS defines a way in which the browser and the server can interact to determine whether to allow the cross-origin request. It’s a compromise that allows greater flexibility, but is more secure than simply allowing all such requests.

The CORS standard works by adding new HTTP headers that allow servers to serve resources to permitted origin domains. Browsers support these headers and enforce the restrictions they establish. Additionally, for HTTP request methods that can cause side-effects on user data (in particular, for HTTP methods other than GET, or for POST usage with certain MIME types) the specification mandates that browsers "pre-flight" the request, soliciting supported methods from the server with an HTTP OPTIONS request header, and then, upon "approval" from the server, sending the actual request with the actual HTTP request method. Servers can also notify clients whether "credentials" (including Cookies and HTTP Authentication data) should be sent with requests.

CORS can be used as a modern alternative to the [JSONP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jsonp.md) pattern. While [JSONP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jsonp.md) supports only the GET request method, CORS also supports other types of HTTP requests. Using CORS enables a web programmer to use `*XMLHttpRequest*`, which supports a better error handling than [JSONP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jsonp.md). CORS is supported by most modern web browsers. However, [JSONP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jsonp.md) works on legacy browsers that preclude CORS support.

## CORS and the Open Commerce API

The Open Commerce API supports the CORS specification.

If an API request contains an _Origin_ header, the origins in the header are verified against a _list_ of allowed origins. The list can be configured in Business Manager [Open Commerce API Settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md) on a per site and client application basis. If all the origins in the header match the configured origins, the API confirms the origins by returning all allowed origins in response header `*Access-Control-Allow-Origin*`. Additionally, the API returns the response header `*Access-Control-Allow-Credentials*` with value "true", which notifies the client to send also cookies. If an origin isn’t defined in the allowed origins list, the API does NOT add the `*Access-Control-Allow*` headers to the response. This is true for GET and HEAD requests. For PATCH, POST, PUT, and DELETE requests, the API returns a 401 fault of type `*UnauthorizedOriginException*` and ensures that there’s no processing on the server side.

"Preflighted" requests first send an HTTP OPTIONS request header to the resource on the other domain; this determines whether the actual request is safe to send. Cross-site requests are preflighted because the requests may affect user data. In particular, a request is preflighted if it uses methods other than GET or POST. A request is also preflighted if the POST method is used to send request data with a Content-Type other than `*application/x-www-form-urlencoded, multipart/form-data*`, or `*text/plain*`?for example, if the POST request sends an XML payload to the server using `*application/json, application/xml*` or `*text/xml*`, the request is preflighted.

## Configure Allowed Origin(s)

To configure allowed origins for the Open Commerce API, perform the following steps:

1.  In Business Manager, select **Administration > Site Development > Open Commerce API Settings**.
2.  Select a site for which you want to configure allowed origins.
3.  In the text field, you configure the property allowed_origins per client application in the JSON document, as described below.

```json
{
  "_v" : "24.5",
  "clients":
  [
    {
      "allowed_origins":["http://foo.com","https://secure.foo.com:8888"],
      "client_id":"[your_own_client_id]",
      "resources":
      [
        {
          "resource_id":"/customers/auth",
          "methods":["post"],
          "read_attributes":"(**)",
          "write_attributes":"(**)"
        },
        {
          "resource_id":"/baskets",
          "methods":["post"],
          "read_attributes":"(**)",
          "write_attributes":"(**)"
        },
        ...
      ]
    }
  ]
}
```

**note:** The '\*' wildcard isn’t supported.

## Examples

**Example 1:** GET request with unknown origin - no `*Access-Control-Allow*` headers in response; browser should reject the response by forcing same origin policy.

```txt
REQUEST:
GET /dw/shop/v24_5/products/123/availability HTTP/1.1
Host: example.com
Origin: http://bar.com

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate

{
  "id":"123",
  "name":"Shirt",
  "orderable":true
}
```

**Example 2:** GET request with known origin - `*Access-Control-Allow*` headers in response; modern browsers should make the response content available.

```txt
REQUEST:
GET /dw/shop/v24_5/products/123/availability HTTP/1.1
Host: example.com
Origin: http://foo.com

RESPONSE:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://foo.com
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: location,x-dw-version-status
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate

{
  "id":"123",
  "name":"Shirt",
  "orderable":true
}
```

**Example 3:** POST request with unknown origin: Pre-flight OPTIONS request contains no confirming `*Access-Control-Allow*` headers; browsers skip the second request.

```txt
REQUEST:
OPTIONS /dw/shop/v24_5/baskets HTTP/1.1
Host: example.com
Origin: http://bar.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type

RESPONSE:
HTTP/1.1 204 No Content
Allow: POST
```

**Example 4:** POST request with known origin: Pre-flight OPTIONS request has confirming `*Access-Control-Allow*` headers in response; browsers execute the second request.

```txt
REQUEST 1:
OPTIONS /dw/shop/v24_5/baskets HTTP/1.1
Host: example.com
Origin: http://foo.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Content-Type

RESPONSE 1:
HTTP/1.1 204 No Content
Access-Control-Allow-Methods: POST
Access-Control-Max-Age: 86400
Access-Control-Allow-Origin: http://foo.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type
Allow: POST

REQUEST 2:
POST /dw/shop/v24_5/baskets HTTP/1.1
Host: example.com
Origin: http://foo.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json
Content-Length: 67

{
  "product_id" : "456",
  "quantity" : 1.00
}

RESPONSE 2:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: http://foo.com
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: location,x-dw-version-status
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Length: 158

{
  "_v" : "24.5",
  "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
  "currency" : "USD",
  "product_sub_total" : 40.00,
  "product_total" : 40.00,
  "shipping_total" : null,
  "tax_total" : null,
  "order_total" : null,
  "product_items" :
  [
    {
      "product_id" : "456",
      "item_text" : "Product foo",
      "quantity" : 1.00,
      "product_name" : "foo",
      "base_price" : 40.00,
      "price" : 40.00
    }
  ]
}
```

<!-- document id=089b76150bef88b4ff4667abab2201eae45273f4d9492dbb761d1bb4fe907038 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/scapi-cors.md -->

# CORS in SCAPI

CORS allows a web service to establish exceptions to the same-site policy that browsers normally enforce. Without CORS, browser access to resources on other servers is possible, but the browser prevents the response from being accessed and processed by the script.

When a browser requests a resource from a site whose domain is different from the site where the script is executed, an `Origin` header is added to the request. A server supporting CORS returns the response header `Access-Control-Allow-Origin`, which contains a list of origins that are allowed to use the endpoint. If the current origin is not part of the list, the browser prevents the content from being accessed.

The following image shows the request flow for a server named `bar.com` that supports CORS:

![Cross-Origin Resource Sharing (CORS) request flow and validation process](https://developer.salesforce.com/docs/media/commerce-api/cors-overview.png)

Browsers automatically make preflight requests before a modifying request is executed. Each preflight request is made as an `OPTIONS` request with the `Origin` header and the `Access-Control-Request-Method` header.

The resulting CORS response contains the `Access-Control-Allow-Methods` header, which lists the methods that the client is allowed to execute from the origin. It also contains the `Access-Control-Max-Age` header, which tells the browser how long (in seconds) it can cache the preflight result and reuse it for subsequent requests without repeating the preflight.
The modifying request itself is then only executed if the preflight request is successful, as shown in the following example request flow:

![CORS preflight request process and header validation](https://developer.salesforce.com/docs/media/commerce-api/cors-preflight-request.png)

## Configure CORS in SCAPI

As of B2C Commerce 24.8, SCAPI adheres to the CORS standard and security best practices, and supports CORS requests for all Data and Shopper API endpoints.

Preflight (OPTIONS) requests are also supported.

If no configuration is provided, CORS is not active. To configure CORS in SCAPI, use the [CORS API](https://developer.salesforce.com/docs/commerce/commerce-api/references/cors?meta=Summary).

The configured list of aliases is automatically enriched with all known default names and site aliases. You do not need to explicitly configure them for CORS.

**note:** For security reasons, wildcards (\*) are not supported, and the returned `Access-Control-Allow-Origin` header does not contain the full list of allowed origins. It only contains the single origin that was submitted with the current request’s `Origin` header.

The configuration of allowed CORS origins is unique to each environment and is not replicated between environments. The configuration of allowed origins is done per client ID and site, which means:

- You can maintain separate lists of allowed origins for different applications.
- You cannot have individual API or endpoint configurations.

The CORS API requires an AM OAuth token with the scope `sfcc.cors-preferences.rw`. When you send a new CORS configuration with a PUT request, the response mirrors the stored configuration, for example:

```json
{
  "corsClientPreferences": [
    {
      "clientId": "12345678-90ab-cdef-fedc-ba0987654321",
      "origins": [
        "http://foo.com",
        "https://foo.bar.com",
        "myapp://example.com"
      ]
    }
  ]
}
```

Allowed URLs can contain any scheme and are not limited to HTTP and HTTPS. Each origin must adhere to the http-style format of `<scheme>://(<subdomain>.)<domain>(.<tld>)` and must not contain port or path information.

The port is not part of the configuration. If the origin domain is part of the allowlist, all ports are accepted by SCAPI CORS.

To enable CORS for a client without specifying custom origins, configure the client and site with an empty origin list. Known domain names and aliases still apply.

```json
{
  "corsClientPreferences": [
    {
      "clientId": "12345678-90ab-cdef-fedc-ba0987654321",
      "origins": []
    }
  ]
}
```

### CORS Responses

A CORS request, for example: a GET, PUT, POST, DELETE, or HEAD request, yields the same result as a typical request:

If a request contains a valid `Origin` header, the response contains the following headers:

```http
Access-Control-Allow-Origin
Access-Control-Allow-Headers (only if Access-Control-Request-Headers was included in the request)
Access-Control-Allow-Credentials (always true)
```

If a request contains an invalid `Origin` header, these response headers are simply missing, with no other changes.

Note: This behavior is different from OCAPI CORS where a manipulating request with an invalid origin results in a `401` status code and the message `Unauthorized Origin`.

For preflight requests with a valid endpoint, the server returns a `200 Success` status with the following headers:

```http
Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Max-Age
Access-Control-Allow-Headers (only if Access-Control-Request-Headers was included in the request)
Access-Control-Allow-Credentials (always true)
```http

The `Access-Control-Max-Age` header is set to `600` seconds (10 minutes). Browsers cap this value to their own maximum (for example, 7200 seconds in Chromium-based browsers and 86400 seconds in Firefox).

If the endpoint is invalid, the call will return a `404 Not Found` status.

### Example Responses

```markdown
REQUEST:
GET `https``:``//{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/{productId}`
Origin: https://foo.com

RESPONSE: 200
{
    "id": "{productId}",
    ...
}
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://foo.com
```

```markdown
REQUEST:
GET `https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/{productId}`
Origin: https://foobar.com

RESPONSE: 200
{
    "id": "{productId}",
    ...
}
(no CORS headers)
```http

```markdown
REQUEST:
OPTIONS `https``:``//{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/{id}`
Origin: https://foo.com
Access-Control-Request-Method: GET

RESPONSE: 200
(no Body)
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Origin: https://foo.com
Access-Control-Max-Age: 600
```http

```markdown
REQUEST:
OPTIONS `https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/{id}`
Origin: https://foo.com
Access-Control-Request-Method: GET

RESPONSE: 200
(no Body)
(no CORS headers)
```

### Constraints

Custom APIs are not currently supported.

<!-- document id=aba05b4465dff45c659f35d0f44eb1e67b0476bdd57cf650c75fff64b8ddd69d url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/coupons.md -->

Coupons

# Coupons

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/coupons/coupons-oas-v1-public.yaml)

## API Overview

Use the Coupons API to create, modify, retrieve, and delete coupons for a given channel. You can also use it to create and retrieve coupon codes using a couponID.

Coupons _must_ be added as a qualifier to a campaign before they can be used.

For more information, see [Using Coupons as Qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_coupons.htm&type=5) in the B2C Commerce documentation.

### Authentication & Authorization

The client requesting the coupon's information must have access to the Coupon resource. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account manager to log in.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Single-Use Coupon

Single-use coupons are your standard coupons, which you can only use once per customer.

For example, use the Coupons API to create a coupon with a single coupon code that can be applied only once per order per customer.

#### Multiple-Use Coupon

A multiple-use coupon can be used any number of times by any number of customers.

For example, use the Coupons API to create a coupon that can be applied once per order and has system-generated codes.

#### Search Coupon

Use the Coupons API to search for coupons using simple or complex querying.

#### Search Coupon Redemptions

Use the Coupons API to search for coupon redemptions using simple or complex querying.

For more detail, see [Coupon Redemption](https://help.salesforce.com/s/articleView?id=cc.b2c_coupons.htm&type=5) in the B2C Commerce documentation.

### Related APIs

*   [Campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns?meta=Summary) — Manage campaigns that use coupons as qualifiers.

**Version:** 1.0.44

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/coupons/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.promotions: promotions READONLY
    *   Scope sfcc.promotions.rw: promotions read/write
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### POST Search for coupons.

`POST /organizations/{organizationId}/coupons`

Operation ID: `couponsSearch`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

The Coupon Search document contains a search object that allows filtering on various attributes.

The following searchable query attributes can be used to narrow the search:

| Attribute | Type |
| --- | --- |
| couponId | String |
| description | String |
| type | one of {"single\_code", "multiple\_codes", "system\_codes"} |
| enabled | Boolean |

Note that only searchable attributes can be used in sorting.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SearchRequest`.

#### Responses

*   **200** Coupon information successfully retrieved.
    
    Media type: `application/json`. Schema: `CouponSearchResult`.
    
*   **400** Returned when the query is ill-formed.

### POST Search for coupon redemptions.

`POST /organizations/{organizationId}/coupons/redemptions`

Operation ID: `couponRedemptionsSearch`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

The Coupon Redemption Search document contains a search object that allows filtering on various attributes.

The following searchable query attributes can be used to narrow down the search:

| Attribute | Type |
| --- | --- |
| code | String |
| couponId | String |
| customerEmail | String |
| orderNo | String |

Note that only searchable attributes can be used in sorting.

If the user role does not have the `View_Coupon_Codes` permission, then the returned coupon codes are masked.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SearchRequest`.

#### Responses

*   **200** Coupon redemption information successfully retrieved.
    
    Media type: `application/json`. Schema: `CouponRedemptionSearchResult`.
    
*   **400** Returned when the query is ill-formed.

### POST Redeem a coupon code for an existing coupon for the specified site.

`POST /organizations/{organizationId}/coupons/actions/redeem`

Operation ID: `redeemCoupon`. Security: AmOAuth2 (sfcc.promotions.rw).

### The coupon code must be redeemable.

_**Note: Coupon redemptions are evaluated during checkout. A large number of coupon redemptions negatively impacts order creation performance and scale.**_

1.  Avoid importing unnecessary coupon redemptions.
2.  Clean up coupon codes and related redemptions when they are no longer required.

* * *

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `CouponCodeRedemptionRequest`.

_Example: PostRedeemCoupon_

```
{
  "code": "Code1",
  "customerEmail": "shopper@salesforce-test.com",
  "orderNo": "00023120@store4"
}
```

#### Responses

*   **201** Coupon was successfully redeemed and a redemption record created.
*   **400** Returned when the coupon code can not be redeemed, for example, if it is disabled, already redeemed, if the redemption limit (maximum number or timeframe) is exceeded or if it has no assigned active promotion.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/coupon-code-not-redeemable",
      "title": "Coupon Code Not Redeemable",
      "detail": "The coupon code 'CODE374' in site 'RefArch' is not redeemable because 'COUPON_DISABLED'.",
      "errorCode": "COUPON_DISABLED",
      "couponCode": "CODE374",
      "siteId": "RefArch"
    }
    ```
    
*   **404** Returned when the site does not contain a coupon, which defines whether the coupon code requested can be redeemed.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/coupon-not-found",
      "title": "Coupon Not Found",
      "detail": "No coupon for the given coupon code 'CODE374' and site 'RefArch' could be found.",
      "couponCode": "CODE374",
      "siteId": "RefArch"
    }
    ```
    

### GET Return coupon information for the specified coupon ID.

`GET /organizations/{organizationId}/coupons/{couponId}`

Operation ID: `getCoupon`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

If the user role does not have the View\_Coupon\_Codes permission, then the returned coupon codes are masked.

#### Parameters

*   `couponId` (path, string, required) The ID of the coupon to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Coupon information for the specified coupon ID successfully returned.
    
    Media type: `application/json`. Schema: `Coupon`.
    
    _Example: GetCoupon_
    
    ```
    {
      "couponId": "MyCoupon",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 0,
        "limitPerCustomer": 0,
        "limitPerTimeFrame": {
          "redemptionTimeFrame": 24,
          "limit": 1
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 50000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
    ```
    
*   **404** Returned when the coupon does not exist matching the given ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: getCoupon404_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/coupon-not-found",
      "title": "Coupon Not Found",
      "detail": "No coupon with ID 'foo' for site 'RefArch' could be found.",
      "couponId": "foo",
      "siteId": "RefArch"
    }
    ```
    

### PUT Create a coupon using the information provided. If a coupon with the specified identifier already exists, the existing coupon is replaced.

`PUT /organizations/{organizationId}/coupons/{couponId}`

Operation ID: `createCoupon`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `couponId` (path, string, required) The ID of the coupon to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `Coupon`.

#### Responses

*   **200** Coupon successfully created.
    
    Media type: `application/json`. Schema: `Coupon`.
    
    _Example CreateCoupon: same as GET /organizations/{organizationId}/coupons/{couponId} 200 response._
    
*   **400**
    
    Returned when the coupon passed is not valid (the argument indicates which field is invalid). Possible reasons:
    
    *   The code provided is in use by another coupon.
    *   A single code coupon set the coupon code improperly.
    *   The ID in the request does not match the ID in the document.
    *   A quota for system-generated coupons is violated.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: CouponCodeDuplicate400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/coupon-code-duplicate",
      "title": "Coupon Code Duplicate",
      "detail": "The coupon code 'bar' is already used in coupon 'foo'. Please make sure the code is unique.",
      "couponId": "foo",
      "couponCode": "bar"
    }
    ```
    
*   **403** Returned when the resource requires global context instead of site-specific context.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: createCoupon403_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-access-forbidden",
      "title": "Site Access Forbidden",
      "detail": "Site-specific access via '/s/RefArch/' isn't allowed. Organization-specific access is expected via '/s/-/'.",
      "siteId": "RefArch"
    }
    ```
    

### DELETE Delete a coupon with a specified ID.

`DELETE /organizations/{organizationId}/coupons/{couponId}`

Operation ID: `deleteCoupon`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `couponId` (path, string, required) The ID of the coupon to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Coupon successfully deleted.

### PATCH Update a coupon with the specified information.

`PATCH /organizations/{organizationId}/coupons/{couponId}`

Operation ID: `updateCoupon`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `couponId` (path, string, required) The ID of the coupon to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `Coupon`.

#### Responses

*   **200** Coupon successfully updated.
    
    Media type: `application/json`. Schema: `Coupon`.
    
    _Example UpdateCoupon: same as GET /organizations/{organizationId}/coupons/{couponId} 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   Cannot update certain fields in a coupon after redeeming it or exporting it
    *   The code provided is in use by another coupon.
    *   A quota for system-generated coupons is violated.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example updateCoupon400: same as PUT /organizations/{organizationId}/coupons/{couponId} 400 response._
    
*   **403** Returned when trying to update a broken coupon that should be deleted and re-created, or when trying to update a legacy coupon.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: updateCoupon403_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/coupon-legacy-update-forbidden",
      "title": "Coupon Legacy Update Forbidden",
      "detail": "The coupon 'foo' can't be modified because it was created before Release 16.7.2. Customers can still redeem this coupon code on the Storefront.",
      "couponId": "foo"
    }
    ```
    

### GET Get the coupon codes for the given coupon. If the user role does not have the View\_Coupon\_Codes permission, then the coupon codes returned are masked.

`GET /organizations/{organizationId}/coupons/{couponId}/codes`

Operation ID: `getCouponCodes`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `couponId` (path, string, required) The ID of the coupon to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Coupon codes successfully retrieved.
    
    Media type: `application/json`. Schema: `CouponCodes`.
    
    _Example: GetCouponCodes_
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 50,
      "data": [
        {
          "code": "CodeA",
          "issued": false,
          "redemptionCount": 0
        },
        {
          "code": "CodeB",
          "issued": false,
          "redemptionCount": 0
        },
        {
          "code": "CodeC",
          "issued": false,
          "redemptionCount": 0
        }
      ]
    }
    ```
    
*   **404** Returned when the coupon does not exist matching the given ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example CouponNotFound: same as GET /organizations/{organizationId}/coupons/{couponId} 404 response._
    

### POST Add or delete (modify) multiple codes to and from the supplied coupon.

`POST /organizations/{organizationId}/coupons/{couponId}/codes`

Operation ID: `updateCouponCodes`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `couponId` (path, string, required) The ID of the coupon to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `delete` (query, boolean) Pass as true to delete the passed codes.  
    Default: `false`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `CouponMultiCodesRequest`.

#### Responses

*   **204** Coupon codes successfully updated - this is also returned if we try to add an already existing code or to delete a non-existing code.
*   **400** Returned when the coupon code could not be created.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: updateCoupon400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/coupon-code-create",
      "title": "Coupon Code Create",
      "detail": "The coupon code 'bar' couldn't be created. Please make sure the code is valid.",
      "couponCode": "bar"
    }
    ```
    
*   **404** Returned if the coupon does not exist matching the given ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example CouponNotFound404: same as GET /organizations/{organizationId}/coupons/{couponId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### CouponSearchResult

Document representing a coupon search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Coupon_, required) The sorted array of coupon search hits. Can be empty.

### CouponRedemptionSearchResult

The result of the coupon redemption search.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of CouponRedemption_, required) The array of coupon redemption search hits. Can be empty.

### CouponCodeRedemptionRequest

Document representing a request to redeem a coupon.

*   `code` (_string_, required) The coupon code to redeem.  
    Example: `Code1`.
*   `customerEmail` (_string_) The customer email to use on the redemption.  
    Example: `shopper@salesforce-test.com`.
*   `orderNo` (_string_, required) The order number to use on the redemption. In case the coupon was redeemed externally and no order number is associated, use a reference id or custom string to identify the source of the redemption.  
    Example: `00023120@store4`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### Coupon

Document representing a coupon.

*   `couponId` (_string_, required) The ID of the coupon.  
    Minimum length: 1. Maximum length: 256. Example: `MyCoupon`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `2019-10-20T12:00:00Z`.
*   `description` (_string_) The description of the coupon.  
    Maximum length: 4000. Example: `This coupon is used to give 10% off stuff.` .
*   `enabled` (_boolean_, required) A flag indicating whether the coupon is enabled.  
    Example: `false`.
*   `exportedCodeCount` (_integer (int32)_) The number of coupon codes attached to the coupon that have been issued (read only).  
    Example: `0`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `2019-10-30T04:23:59Z`.
*   `redemptionCount` (_integer (int32)_) The number of times the coupon has been redeemed (read only). The count is updated once per hour.  
    Example: `3`.
*   `redemptionLimits` (_object_) The redemption limit per coupon code.
    
    Includes all fields of `RedemptionLimits`.
    
    _Example_
    
    ```
    {
      "limitPerCode": 1,
      "limitPerCustomer": 1,
      "limitPerTimeFrame": {
        "limit": 2,
        "redemptionTimeFrame": 24
      }
    }
    ```
    
*   `singleCode` (_string_) Single coupon code, only valid for Single Code type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCode`.
*   `systemCodesConfig` (_object_) The configuration of system coupon codes, including prefix and number of codes.
    
    Includes all fields of `CouponSystemCodeConfig`.
    
    _Example_
    
    ```
    {
      "codePrefix": "SG",
      "numberOfCodes": 500000
    }
    ```
    
*   `totalCodesCount` (_integer (int32)_) The total number of coupon codes associated with this coupon (read only). The count is updated once per hour.  
    Example: `50`.
*   `type` (_string_, required) The type of coupon code.  
    Allowed values: `single_code`, `multiple_codes`, `system_codes`. Example: `single_code`.

### CouponCodes

Document representing a set of coupon codes.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of CouponCode_, required) The collection of coupon codes.
    
    _Example_
    
    ```
    [
      {
        "code": "Code1",
        "issued": false,
        "redemptionCount": 0
      }
    ]
    ```
    

### CouponMultiCodesRequest

A request object to add and remove coupon codes from a document.

*   `codes` (_array of string_, required) The list of coupon codes to add or delete.  
    Items: Minimum length: 1. Maximum length: 256. Maximum items: 999.
    
    _Example_
    
    ```
    [
      "CodeA",
      "CodeB"
    ]
    ```
    

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### CouponRedemption

A redemption record returned from the coupon redemption resources.

*   `code` (_string_, required) The coupon code that was redeemed.
*   `couponId` (_string_, required) The coupon id that was redeemed.
*   `creationDate` (_string (date-time)_, required) Date when the redemption was created.
*   `customerEmail` (_string_, required) The customer email that was used to redeem it.
*   `orderNo` (_string_, required) The order number where the redemption occurred.
*   `viewOrderUrl` (_string_, required) A URL able to access the order.

### RedemptionLimits

Document representing a coupon.

*   `limitPerCode` (_integer (int32)_, required) The redemption limit per code.  
    Minimum: 0. Example: `0`.
*   `limitPerCustomer` (_integer (int32)_, required) The redemption limit per customer.  
    Minimum: 0. Example: `0`.
*   `limitPerTimeFrame` (_object_, required) The redemption limit per time frame.
    
    Includes all fields of `RedemptionLimitPerPeriod`.
    
    _Example_
    
    ```
    {
      "redemptionTimeFrame": 24,
      "limit": 1
    }
    ```
    

### CouponSystemCodeConfig

*   `codePrefix` (_string_, required) The code prefix for system-generated coupon codes.  
    Example: `SG`.
*   `numberOfCodes` (_integer (int32)_, required) The number of system coupon codes that can be issued.  
    Example: `50000`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### CouponCode

A coupon code with accompanying stats for redemptions and issues.

*   `code` (_string_, required) The code used to redeem the coupon.  
    Example: `MyCode`.
*   `issued` (_boolean_, required) Flag indicating if the coupon code has been issued.  
    Example: `true`.
*   `redemptionCount` (_integer (int32)_, required) The count of the number of redemptions associated with the code.  
    Example: `1`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### RedemptionLimitPerPeriod

Document representing a coupon redemption limit.

*   `limit` (_integer (int32)_, required) The limit on the number of times a coupon can be redeemed for a specified redemption time period.  
    Minimum: 0. Example: `1`.
*   `redemptionTimeFrame` (_integer (int32)_, required) The redemption time period.  
    Minimum: 0. Maximum: 999. Example: `24`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=7eb2640a0e0b5bf7c58c16d9d928cfd93663eee427c88c636e1907d5c3f49de1 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/coupons-giftcerts-bonus-products.md -->

# Coupons, Gift Certificates, and Bonus Products

This topic covers less common use cases for working with baskets.

## Add a Coupon to a Basket

1. Configure coupons using the information in [Using Coupons as Promotion Qualifiers for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_using_coupons_as_qualifiers.htm&type=5).
2. Get a guest token.
3. Create a basket.
4. Add a coupon to the basket using the [addCouponToBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addCouponToBasket) endpoint.

```sh
echo '--> Create basket...'
curl "$BASE_BASKET/baskets?siteId=$SITE" \
 -sSfH "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
"productItems": [{ "quantity": 1, "productId": "750518699585M"}],
"couponItems": [{ "code": "menssuits" }]
}' | jq -r '.couponItems'
```

For additional code examples, see [addCouponToBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addCouponToBasket).

## Gift Certificates

For gift certificate overview information and how to create a gift certificate, see [Gift Certificates](https://help.salesforce.com/s/articleView?id=cc.b2c_gift_certificates.htm&type=5).

Use the Shopper Baskets [addGiftCertificateItemToBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addGiftCertificateItemToBasket) endpoint to add a gift certificate to a basket, as shown in the following example:

```sh
curl "$BASE_BASKETS/$BASKET_ID/gift-certificate-items?siteId=$SITE" \
   -sS --fail-with-body \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
  -d '{
  "amount": 1,
  "recipientEmail": "miller@salesforce-test.com",
  "shipmentId": "me"
}'
```

## Create a Basket and Add Bonus Products With Choice

1. [Configure the bonus product in Business Manager](https://help.salesforce.com/s/articleView?id=cc.b2c_choice_of_bonus_product_discount.htm&type=5).
2. Get a guest token.
3. Create a basket.
4. Add one or more products that are associated with a bonus product choice promotion using the [createBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=createBasket) or [addItemToBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addItemToBasket) endpoint.
5. After a product is added to the basket, applicable bonus items become available. The basket response includes a property called `bonusDiscountLineItems`, which is a set of bonus products from which a customer can choose.
6. Copy the `productId` and the `bonusDiscountLineItemId` from the response and use it to select the bonus product using the [addItemToBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addItemToBasket) endpoint. Quantity is a compulsory field and cannot exceed the number of bonus products allowed in the promotion. In this case, it is 1.

```sh
echo '--> Create basket...'
RESPONSE=$(
    curl "$BASE_BASKET/baskets?siteId=$SITE" \
        -sS --fail-with-body \
        -H "Authorization: Bearer $TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"productItems": [{ "quantity": 1, "productId": "750518894553M"}]}'
)
BASKET=$(echo $RESPONSE | jq -r '.basketId')
echo $RESPONSE | jq -r '.bonusDiscountLineItems'
BONUS=$(echo $RESPONSE | jq -r '.bonusDiscountLineItems[0].id')

echo '--> Add the bonus product...'
curl "$BASE_BASKET/baskets/$BASKET/items?siteId=$SITE" \
    -sS --fail-with-body \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '[{ "quantity": 1, "productId": "793775370033M", "bonusDiscountLineItemId": "'$BONUS'"}]' \
 | jq '.productItems'
```

The previous script adds a product with bonus products to the basket. The first bonus product available in the bonusDiscountLineItems array is added to the basket.

<!-- document id=9e613f09526ae00a0417be4437c7ec8500c5fd0137991fabdbfd65a663e35ef9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_create_clone.md -->

# Create a Clone of an On-Demand Sandbox

Use Control Center to clone an existing on-demand sandbox.

**note:** To clone an on-demand sandbox, log in to Account Manager and verify you have the role `Sandbox_API_User` with a tenant filter in the format `<realm_id>_sbx`. For example, in the realm `abcd`, you see the `Sandbox_API_User` role with tenant filter `abcd_sbx`.

The source sandbox must be in either a **Running** or **Stopped** state before it can be cloned. Only one clone operation can be initiated at a time from a single sandbox. However, trigger multiple clone operations simultaneously as long as they originate from different source sandboxes within the same realm.

1. Log in to Control Center.
2. Select the realm where you want to create the clone.
3. Click the **Clone** button next to the instance you want to clone.
4. Complete the Clone On-Demand Sandbox form.
   - Set the **Time-to-live (TTL)**.
     - Select the number of hours the cloned sandbox should remain active:
       - 24 (default, minimum allowed for clones)
       - 48
       - 72
       - 168 (1 week)
       - 0 (infinite time - sandbox persists until manually deleted)
   - Set the **Resource Profile**.
     - Select the resource allocation:
       - Medium
       - Large
       - X Large
       - XX Large
         **note:** Select the same profile or a higher profile than the source sandbox. Profile downgrades aren't allowed. The dropdown defaults to the source sandbox's current profile.
   - Set the **Number of Clones**.
     - Select how many clones to create from this source sandbox in a single request:
       - 1 (default)
       - 2
       - 3
       - 4
       - 5
         **note:** Selecting more than 1 creates a batch of clones that share the same TTL, resource profile, and notification settings. Each resulting clone appears as a separate entry in Clone History.
   - (Optional) Configure **Notification Emails**.
     - To receive notifications, enter one or more email addresses, or leave the **Retain Email Addresses** option selected to use the same notification addresses configured for the source sandbox. These settings apply to every clone in the batch.
5. Click **Clone Instance**. As the clone process initiates, the source sandbox status changes to **Cloning**. All actions (start, stop, reset, clone, delete) for the source sandbox are temporarily disabled until cloning completes.

The clone operation begins. Total duration is typically 10–30 minutes, depending on sandbox size and data volume.

<!-- document id=f7b2a9a5fb98349308f882cf480f6e999641a954625e10b7adc6b9028761476b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-integrate-payment-lwc.md -->

# Create a Custom Payment Component

Use the same credit card payment methods and order processing across B2B stores by creating a custom payment component for a B2C (LWR) checkout page.

When you create a custom payment component, the checkout stages are of particular importance. Aside from the validation-related stage actions such as PostAuth, the following are specific to payment: BEFORE_PAYMENT and PAYMENT. BEFORE_PAYMENT is an important hook because it is where the component initiates a payment session with the gateway. At this stage the GrandTotalAmount of the WebCart will account for all adjustments including tax, shipping and promotions. For more on checkout stages in your component see [UseCheckoutComponent Interface](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-checkoutsavable.md)

To create and deploy the payment component, first [Commerce SFDX Environment Setup](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-set-up-dev-env.md) and optionally review [Build Custom Components](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-custom-component.md).

1.  In the Visual Studio Code editor, enter `SFDX`.

2.  Select **SFDX: Create an Apex Class** or navigate to the project containing an existing payment adapter class.

    The Apex class

    ```javascript
    commercepayments.PaymentGatewayAdapter;
    ```

    implements the (synchronous or asynchronous) adapter that connects the payment platform in Salesforce and an external payment gateway. You can create your own adapter using the code samples and instructions in [Payment Gateway Adapters](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_adapter_intro.htm). For example implementations associated with specific payment platforms, see [Sample Payment Gateway Implementation for CommercePayments](https://developer.salesforce.com/docs/atlas.en-us.248.0.apexcode.meta/apexcode/apex_commercepayments_ref_github_repo.htm).

3.  Add a PostAuth request handler to the Apex class.

    The PostAuth request type ensures that the provided payment token is valid. The token, the amount, and currency code are provided to the adapter through the PostAuth input. This validates completion of the client side transaction. The API to do this is the [Commerce Webstore Checkout Payment API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm). For a client side implementation the RequestType that validates and records a client side payment transaction is PostAuth. For convenience, we have provided a client-side API, `commerce/checkoutApi.postAuthorizePayment` (for more see [Storefront APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_display_lwc_apis.htm)). Invoking this API will in turn invoke the `processRequest` method on your payment gateway adapter with the `RequestType` being `PostAuth`.

    For details of the Apex implementation for PostAuth see [PostAuthorizationRequest Class](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_commercepayments_PostAuthorizationRequest.htm) (input) and [PostAuthorizationResponse Class](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_commercepayments_PostAuthorizationResponse.htm) (output)

4.  Create named credentials for the adapter class.

    1.  In Visual Studio Code Explorer, under `force-app/main/default`, create a subdirectory called `namedCredentials`.

    2.  In namedCredentials, create a file named `_payment_.namedCredential`.

    3.  In the public repo of a reference payment package, such as the [Stripe integration payments package](https://github.com/forcedotcom/commerce-on-lightning/tree/main/examples/b2c/checkout/payment-gateway-integration/Stripe/namedCredentials), go to the `/namedCredentials` folder and copy the contents of the `Stripe.namedCredential` file to your `_payment_.namedCredential`.

5.  Create the payment Lightning web component.

    1.  Create an SFDX project.

    2.  Authorize an org for the LWC deployment.

    3.  Create the [custom UI component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-checkout-component.md).

6.  Make sure that your payment component sets billing address information on the cart before the order is placed. If you use the [Checkout Payment APIs](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm), make a POST request to `/commerce/webstores/webstoreId/checkouts/activeOrCheckoutId/payments`. Specify the `billingAddress` fields in the request:

```javascript
{
   "requestType":"PostAuth",
   "paymentToken": 'pi_0swefj329r4ljsdfk',
   "billingAddress":{
      "name":"John Doe",
      "street":"123 Acme Drive",
      "city":"Los Angeles",
      "region":"CA",
      "country":"US",
      "postalCode":"90001"
   }
}
```

If your component doesn’t use the Checkout Payment APIs, set the billing address fields directly on the [WebCart](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webcart.htm) object. Failing to set billing address fields before order creation can cause an issue in which the order summary is missing a billing contact.

7.  Deploy the payment component and all the code and metadata required for the integration (LWC, Apex, named credentials, trusted sites) to your org.

    Note that payment provider UI component may require using an externally hosted javascript. To do this you will need to add a Content Security Policy (CSP) for the site as well as add it as a trusted script to the site within Experience Builder. The CSP can be managed via metadata as described in [CspTrustedSite](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_csptrustedsite.htm). The trusted script however is a manual step and must be done on a site by site basis as described in step 8.

8.  Create a payment gateway, as described in [Payment Gateway Adapters](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_adapter_intro.htm).

9.  In Experience Builder, register the third-party trusted sites for scripts that are required to run the LWC, as described in [Where to Allowlist Third-Party Hosts for Experience Builder Sites](https://help.salesforce.com/s/articleView?id=experience.networks_security_csp_allow.htm&type=5).

10. If you're implementing an asynchronous payment processing flow, designate the authorization as async in the payment gateway apex adapter by setting the [async status](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_commercepayments_PostAuthorizationResponse_setAsync.htm) to true: When the transaction results are posted, typically via a webhook notification, update the status of the [PaymentAuthorization](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentauthorization.htm). If the status is updated to `Processed` then downstream order management operations can be resumed.

```javascript
 commercepayments.PostAuthorizationResponse postAuthResponse = new commercepayments.PostAuthorizationResponse();
 postAuthResponse.setAsync(true);
```

See

- [Customize a Checkout Component for a B2B or B2C Store (LWR)](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-checkout-component.md)
- [Connect a Payment Service to Store Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-connect-gateway.md)

<!-- document id=cbed25473084ac8fe45daf0fd6fc2afcc57f3348801bb79934d7e6f808a641a6 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-create-b2b-cust-ein-reco-comp.md -->

# Create a Custom Recommendations Component for B2B Stores Using Commerce Einstein APIs

Creating a custom B2B Commerce Einstein recommendations component includes implementing the Activity Tracking API and connecting the component to the Commerce Einstein Webstore Recommendations Connect API resource. This process is for B2B stores on the Aura platform.

Using Connect APIs ensures appropriate product entitlement filtering before recommendations are delivered.

Make sure to reindex after you change associations between buyer groups and products, such as when changing entitlement policies or product-to-buyer group assignments.

Your component must incorporate calls to the Activity Tracking API. When configuring the API:

- Implement both the viewReco and clickReco activities.
- If you replace the Product Detail Purchase Options component with a custom component, implement the viewProduct activity.
- If you add custom add-to-cart functionality, implement the addToCart activity.

You can use custom JavaScript, HTML, and CSS to make front-end modifications. For more information, see the [Lightning Aura Components Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.lightning.meta/lightning/intro_framework.htm).

1.  Create a custom Apex controller.

    1.  Go to **Setup** | **Developer Console**.

    2.  Select **File** | **New** | **Apex Class**.

    3.  Enter a name for the Apex class.

        Make sure to match the component class name for easier identification. For example, `recsController`.

        The controller file (in this case, `recsController.apxc`) opens to show an empty class.

2.  Update the controller file, making sure to modify the _orgDomain_ and _webstoreId_ values to match your storefront domain and ID.

    ```apex
    public with sharing class recsController {
        @AuraEnabled
        public static String getRecs(String recommender, String anchorValues, String cookie) {
            String orgDomain = 'alpinecommerce236.my.salesforce.com';
            String webstoreId = '0ZEB0000000HMNGOA4';
            String endpoint = 'https://'+orgDomain+'/services/data/v55.0/commerce/webstores/
            '+webstoreId+'/ai/recommendations?language=en-US&asGuest=true&recommender='+recommender;
            if (anchorValues.length() > 0) {
                endpoint += '&anchorValues='+anchorValues;
            }

            HttpRequest req = new HttpRequest();
            req.setEndpoint(endpoint);
            req.setHeader('Cookie', cookie);
            req.setMethod('GET');
            req.setHeader('Authorization', 'OAuth ' + UserInfo.getSessionId());

            Http http = new Http();
            HTTPResponse res = http.send(req);
            return res.getBody();
        }
    }
    ```

3.  Update the controller file with the appropriate profile for buyers.

    1.  Go to **Setup** | **Custom Code** | **Apex Classes**.

    2.  Next to the controller file that you created, click **Security**.

    3.  Add the Shopper profile to the enabled profiles column.

    4.  Click **Save**.

4.  Create an SFDX project in Visual Studio Code and run the `SFDX: Create Aura Component` command.

5.  Specify a name for the component.

6.  Update the component file with the attribute configuration (for example, `force-app/main/default/aura/<project_name>/<component_name>.cmp`).

    Make sure to use the controller filename that you used when creating the Apex controller, and provide the tag needed for importing activity tracking.

    ```nolang
    <aura:component implements="forceCommunity:availableForAllPageTypes" controller="RecsController" access="global">

        <aura:attribute name="title" type="String" default="" required="true" />
        <aura:attribute name="recommender" type="String" default="RecentlyViewed" required="true" />
        <aura:attribute name="anchorValues" type="String" default="" required="false" />
        <aura:attribute name="uuid" type="String" default=""/>
        <aura:attribute name="loading" type="boolean" default="false"/>
        <aura:attribute name="showProducts" type="boolean" default="false"/>
        <aura:attribute name="products" type="List" default="[]" />

        <!-- Tag needed to import Commerce Activity Tracking-->
        <commerce:activitiesApi aura:id="activitiesApi" />

        <aura:handler name="init" value="{!this}" action="{!c.onLoadComponent}"/>

        <div>
            <aura:if isTrue="{!v.loading}">LOADING...</aura:if>

            <aura:if isTrue="{!v.showProducts}">
                <div class="title">{!v.title}</div>
                <div class="products">
                    <aura:iteration items="{!v.products}" var="product">
                        <div class="product">
                            <img data-pid="{!product.id}" onclick="{!c.handleClickProduct}" src="{!product.defaultImage.url}"/>
                            <a class="name" data-pid="{!product.id}" onclick="{!c.handleClickProduct}">{!product.name}</a>
                        </div>
                    </aura:iteration>
                </div>
            </aura:if>
        </div>

    </aura:component>
    ```

7.  Update the metadata in the component’s XML file (for example, `force-app/main/default/aura/<project_name>/<component_name>.cmp-meta.xml`).

    Make sure that the _\<apiVersion>_ tag references the latest API version.

    ```xml
    <?xml version="1.0" encoding="UTF-8" ?>
    <AuraDefinitionBundle xmlns="http://soap.sforce.com/2006/04/metadata">
        <apiVersion>55.0</apiVersion>
        <description>Aura Recommendations Component</description>
        <isExposed>true</isExposed>
        <targets>
            <target>lightningCommunity__Page</target>
            <target>lightningCommunity__Default</target>
        </targets>
    </AuraDefinitionBundle>
    ```

8.  Edit your component’s CSS file to add custom styling (for example, `force-app/main/default/aura/<project_name>/<component_name>.css`).

    This sample code includes modifications to the component’s image size and headings.

    ```css
    .THIS div.title {
      text-align: center;
      font-weight: 800;
      font-size: 2em;
    }

    .THIS .products {
      height: 400px;
      text-align: center;
    }
    .THIS .products .product {
      width: 25%;
      height: 450px;
      padding: 10px;
      display: inline-block;
    }
    .THIS .products .product img {
      cursor: pointer;
      max-height: 300px;
      width: auto;
    }
    .THIS .products .product .name {
      display: block;
    }
    ```

9.  Edit your component’s `Controller.js` file, making sure to modify the _storeName_ value for the current store (for example, `force-app/main/default/aura/<project_name>/<component_name>Controller.js`).

    ```javascript
    ({
      onLoadComponent: function (cmp, event, helper) {
        let pageProductId = helper.getProductDetailProductId();
        if (pageProductId) {
          // Component is on a product detail page; show Similar Products recommender
          cmp.set("v.title", "Similar Products");
          cmp.set("v.recommender", "SimilarProducts");
          cmp.set("v.anchorValues", pageProductId);
        } else {
          // Show Recently Viewed recommender
          cmp.set("v.title", "Recently Viewed");
          cmp.set("v.recommender", "RecentlyViewed");
          cmp.set("v.anchorValues", "");
        }
        helper.loadProductRecommendations(cmp, event, helper);
      },

      // send a clickReco activity and navigate to the product detail page
      handleClickProduct: function (cmp, event, helper) {
        let productId = event.currentTarget.getAttribute("data-pid");
        let trackClickReco = cmp.find("activitiesApi").trackClickReco;
        let recName = helper.recommenderNames[cmp.get("v.recommender")];
        let uuid = cmp.get("v.uuid");
        let products = cmp.get("v.products");
        let product = products.filter((p) => p.id === productId)[0];
        let productToSend = {
          id: product.id,
          price: product.prices ? product.prices.listPrice : undefined,
        };
        trackClickReco(recName, uuid, productToSend);

        // navigate to the product page
        let storeName = "AlpineB2B";
        let productName = product.name || "detail";
        let newHref = `/${storeName}/s/product/${productName}/${productId}`;
        window.location.href = newHref;
      },
    });
    ```

10. Edit your component’s `Helper.js` file, using this example for guidance (for example, `force-app/main/default/aura/<project_name>/<component_name>Helper.js)`.

    ```javascript
    ({
      loadProductRecommendations: function (cmp, event, helper) {
        try {
          cmp.set("v.loading", true);
          var action = cmp.get("c.getRecs");
          action.setParams({
            recommender: cmp.get("v.recommender"),
            anchorValues: cmp.get("v.anchorValues"),
            cookie: document.cookie,
          });
          // Create a callback that is executed after
          // the server-side action returns
          action.setCallback(this, function (response) {
            var state = response.getState();
            if (state === "SUCCESS") {
              try {
                let data = JSON.parse(response.getReturnValue());
                let products = data.productPage.products;
                // Keep it simple, only show 4 products
                cmp.set("v.products", products.slice(0, 4));
                cmp.set("v.uuid", data.uuid);
                cmp.set("v.loading", false);
                let showProducts = products.length > 0;
                cmp.set("v.showProducts", showProducts);
                // Only send the viewReco activity when we display the product
                // recommendations
                if (showProducts) {
                  helper.sendViewRecoActivity(cmp, helper);
                }
              } catch (err) {
                console.error("Error fetching recommendations", err);
                cmp.set("v.loading", false);
              }
            }
          });
          $A.enqueueAction(action);
        } catch (error) {
          console.error("Failed to load recommendations: ", error);
          cmp.set("v.loading", false);
        }
      },
      // The recommender names we pass into the Connect API are in a different format
      // than the recommender names we pass into the activities api.
      recommenderNames: {
        RecentlyViewed: "recently-viewed",
        SimilarProducts: "similar-products",
        MostViewedByCategory: "most-viewed-by-category",
        TopSelling: "top-selling",
        Upsell: "upsell",
      },

      formatPrice: function (price, curr) {
        return new Intl.NumberFormat("en-US", { style: "currency", currency: curr }).format(price);
      },

      sendViewRecoActivity: function (cmp, helper) {
        let trackViewReco = cmp.find("activitiesApi").trackViewReco;
        let recName = helper.recommenderNames[cmp.get("v.recommender")];
        let products = cmp.get("v.products").map((p) => ({ id: p.id }));
        let uuid = cmp.get("v.uuid");
        trackViewReco(recName, uuid, products);
      },

      getProductDetailProductId: function () {
        let pageProductIdMatch = window.location.href.match(new RegExp("01t[a-zA-Z0-9]{15}"));
        let pid = pageProductIdMatch ? pageProductIdMatch[0] : null;
        return pid;
      },
    });
    ```

11. After you create the custom Einstein Recommendations component, deploy it from Visual Studio Code and place it in your store with Experience Builder.

12. Before publishing your site from Experience Builder, click **Preview** to see how the custom component looks in a desktop browser window and on a mobile device.

**See Also**

- [Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_apis.htm)
- [Prepare Commerce Einstein to Use Custom Components](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_prepare_einstein_custom_comps.htm)
- [Commerce Einstein Activity Tracking API](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_activity_tracking_api.htm)
- [B2B Commerce Einstein Product Recommendations API](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_b2b_reco_api_ref.htm)
- [Tracked Data](https://help.salesforce.com/s/articleView?id=commerce.comm_einstein_data.htm)
- [Commerce Einstein Webstore Recommendations](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_ai_recommendations.htm)

<!-- document id=0088864bc0c778225bd7af9b5bac6919b7e7bce1a5a1fe65ea8b5d932dc36566 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-create-b2c-cust-ein-reco-comp.md -->

# Create a Custom Recommendations Component for B2C Stores Using Commerce Einstein APIs

Creating a custom B2C Commerce Einstein recommendations component includes implementing the Activity Tracking API and connecting the component to the Product Recommendation API.

For B2C storefronts, you connect the component to the Product Recommendation API through a wire adapter. Your component must incorporate calls to the Activity Tracking API. When configuring the Activity Tracking API, keep these considerations in mind.

- Implement both the viewReco and clickReco activities.
- If you build custom components that show product details without including the Product Detail Purchase Options component, make sure to implement the viewProduct activity.
- If you add custom add-to-cart functionality, also implement the addToCart activity.

You can also introduce custom JavaScript, HTML, and CSS to make front-end modifications. For more information, see the [Lightning Web Components Dev Guide](https://lwc.dev/guide/introduction).

**note:** This example shows a custom similar-products Commerce Einstein recommendation component using the PRODUCT anchor type. All steps refer to files created for a sample Lightning web component. For more information, see [Create a Sample Lightning Web Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-sample-lwc.md).

1.  In the component’s JavaScript file, define a custom component class (for example, `RecommendationsSample`). Implement the ProductRecommendationsAdapter to return Einstein product recommendations.

    For example, in `force-app/main/default/<Component Name>.js`, import this wire adapter from the `recommendationsApi` module within the commerce namespace (`commerce/recommendationsApi`). Declare its required parameters with the `@wire` decorator.

    ```apex

    import { LightningElement, api, track, wire } from 'lwc';
    import { ProductRecommendationsAdapter, ANCHOR_TYPES } from 'commerce/recommendationsApi';
    import { navigate, NavigationContext } from 'lightning/navigation';
    import { trackClickReco, trackViewReco } from 'commerce/activitiesApi';

    export default class RecommendationsSample extends LightningElement {

        @api products = [];
        @api productId;

        recommenderName = 'similar-products';
        anchorType = ANCHOR_TYPES.PRODUCT;
        get anchorValue() {
            return [this.productId];
        };

        @wire(ProductRecommendationsAdapter, {
            recommenderName: '$recommenderName',
            anchorType: '$anchorType',
            anchorValue: '$anchorValue',
        })
        async loadRecommendation(response) {
            let { data, error } = response;

            if (data && data.recoUUID && data.products && data.products.length > 0) {
                this.products = data.products;
                this.recoUUID = data.recoUUID;

                if (this.canDisplayRecommendations) {
                    this.sendViewReco();
                }
            } else if (error) {
                // unable to load recommendation, handle accordingly
                this.products = { data: [] };
                console.error('Unable to load product recommendations');
            }
        }

        get canDisplayRecommendations() {
            return this.products.length > 0;
        }

        // NavigationContext allows us to click a link to get to new Product page
        @wire(NavigationContext)
        navContext;

        handleClickProduct(event) {
            const pid = event.currentTarget.getAttribute('pid');
            const product = this.products.filter(p => p.id === pid)[0];

            trackClickReco(this.recommenderName, this.recoUUID, {
                id: product.id,
                sku: product.sku,
            });

            // go to the Product Detail Page for the product clicked
            navigate(this.navContext, {
                type: 'standard__recordPage',
                attributes: {
                    objectApiName: 'Product2',
                    recordName: product.fields.Name.replace(' ', '-'),
                    name: 'recordId',
                    recordId: pid,
                },
            });
        }

        sendViewReco() {
            trackViewReco(
                this.recommenderName,
                this.recoUUID,
                this.products.map((product) => {
                    return {
                        id: product.id,
                        sku: product.sku,
                    };
                })
            );
        }
    }

    ```

2.  Update the component’s HTML file (for example, `force-app/main/default/<Component Name>.html`).

    ```html

    <template>
        <section class="component-wrapper" if:true={canDisplayRecommendations}>
            <h1>Product Recommendations</h1>
            <table>
                <tr>
                    <th>Image</th>
                    <th>Name</th>
                    <th>List Price</th>
                    <th>Unit Price</th>
                </tr>
                <template for:each={products} for:item="product">
                    <tr key={product.id}>
                        <td><img src={product.defaultImage.url}></img></td>
                        <td>
                            <a key={product.id} class="product-line" onclick={handleClickProduct} pid={product.id}>
                                {product.fields.Name}
                            </a>
                        </td>
                        <td>{product.prices.listPrice} {product.prices.currencyIsoCode}</td>
                        <td>{product.prices.unitPrice} {product.prices.currencyIsoCode}</td>
                    </tr>
                </template>
            </table>
        </section>
    </template>

    ```

3.  Update the metadata in the component’s XML file (for example, `force-app/main/default/<Component Name>.js-meta.xml`).

    **note:** Ensure that the `<apiVersion>` tag references the latest API version.

    ```xml

    <?xml version="1.0" encoding="UTF-8"?>
    <LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
        <apiVersion>55.0</apiVersion>
        <isExposed>true</isExposed>
        <targets>
            <target>lightningCommunity__Page</target>
            <target>lightningCommunity__Default</target>
        </targets>

        <targetConfigs>
            <targetConfig targets="lightningCommunity__Default">
                <property label="Product Id" name="productId" type="String" default="{!recordId}" />
            </targetConfig>
        </targetConfigs>
    </LightningComponentBundle>

    ```

4.  In your lwc directory, create a CSS file with the same name as your project. In this example, the CSS file is named `recommendationsSample.css`.

    ![Screenshot showing the location for the new CSS file. The cursor is hovering over "New File" in the recommendationsSample folder.](https://developer.salesforce.com/media/d2c-commerce/RecsNewFile.png)

5.  In the CSS file, add custom CSS to style your component. The sample code provided includes modifications to the component’s image size and headings.

    ```css
    h1 {
      font-size: 1.5em;
      font-weight: 800;
    }
    img {
      width: 150px;
    }
    th {
      font-weight: 800;
    }
    ```

6.  After you create the custom Einstein Recommendations component, deploy the component from Visual Studio Code and place it in your store with Experience Builder.

7.  Before publishing your site from Experience Builder, click **Preview** to see how the custom component looks in a desktop browser window or on a mobile device.

**See Also**

- [Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_apis.htm)
- [Prepare Commerce Einstein to Use Custom Components](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_prepare_einstein_custom_comps.htm)
- [Commerce Einstein Activity Tracking API](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_activity_tracking_api.htm)
- [B2C Commerce Einstein Product Recommendations API](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_b2c_reco_api_ref.htm)
- [Customize Sites with Experience Builder](https://help.salesforce.com/s/articleView?id=commerce.community_designer_overview.htm)

<!-- document id=083c143f5066f07b778cb4750d087e60dc0029c55db3d1814ce791f457153278 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-create-discount-percentage-lwc.md -->

# Create a Pricing Component that Displays Discount Percentage

Enhance store pricing by displaying the percentage discount alongside a negotiated price. Create the app by adapting a `productPricing` component from the Commerce LWR library.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

![Screenshot showing discount percentage alongside reduced price.](https://developer.salesforce.com/media/d2c-commerce/show_discount_percentage.png)

**note:** Before you begin this task set up your Commerce DX environment and clone the Commerce LWR repo. See xref to Get Reference Components from the LWR Library. In Visual Studio (VS) Code editor, cloning by default places each library component in `force-app/main/default/lwc`.

Customizing the `productPricing` component to display the discount percentage alongside the negotiated price requires changes to the reference lightning web component project files.

- In the javascript file, you add the discount calculation logic.
- In the javascript-metadata file you optionally specify targets to deploy the custom component and optionally enable component property editing in Experience Builder.
- In the HTML template you specify where to display the discount percentage.

1.  Open your VS Code editor.

2.  In the `lwc/productPricing` folder, double-click `productPricing.js`.

    The file is open in the Visual Studio Code editor.

3.  To insert the discount percentage calculation logic, add the code in the snippet and highlighted in the screenshot.

    ```javascript

    ** * Gets the discount percentage.
         * * Calculated as
         * ((originalPrice - negotiatedPrice) / originalPrice) * 100 * @returns {number|null}
         * Returns null if discount percentage cannot be calculated
         * * @readonly
         * * @private
         * */ get discountPercentage() { if (this.originalPrice && this.negotiatedPrice)
            { const original = parseFloat(this.originalPrice); const negotiated = parseFloat(this.negotiatedPrice);
            if (original !== 0) { return Math.round(((original - negotiated) / original) * 100); } } return null;
            }
            /** * Gets whether the discount percentage is available * @type {boolean} * @readonly * @private */
            get isDiscountAvailable() { return this.discountPercentage !== null;
        }
        /**
    ```

    ![images/productPricing_js_disc_calc.png](https://developer.salesforce.com/media/d2c-commerce/productPricing_js_disc_calc.png)

4.  Save the file.

5.  In the `productPricing` folder, double-click `productPricing.js-meta.xml`.

    The file is open in the Visual Studio Code editor.

6.  **note:** If you deploy the `force-app/main/default/lwc` with this custom LWC, skip this step; the `lwc/builderProductPricing.js-meta.xml` file includes the Experience Builder target declarations.

    To make your LWC deployable in Experience Builder, set `isExposed` to `true`, and define `{lightningCommunity__Page}`, `{lightningCommunity__Page_Layout}`, or `{lightningCommunity__Theme_Layout}` in `targets`.

    The snippet specifies a pricing js.meta.xml for a component in Experience Builder and also enables component property editing.

    ![Screenshot of prodcutPricing js.meta file.](https://developer.salesforce.com/media/d2c-commerce/productPricing.js-meta.png)

7.  Save the file.

8.  In the Visual Studio Code explorer, double-click `productPricing.html`.

    The `productPricing.html` template is open in the Visual Studio Code editor.

9.  To display the discount percentage element alongside a negotiated price, add the `<span>` highlighted in the snippet.

    ![Screenshot showing discount percentage html snippet.](https://developer.salesforce.com/media/d2c-commerce/productPricing-html-disc_percentage.png)

10. Save the file.

11. From the component project directory in Visual Studio Code, right-click the enhanced productPricing under `force-app/main/lwc`, and select **SFDX: Deploy Source to Org**.

    View the status of your deployment on the Output tab of the integrated terminal, where SFDX displays a notice that includes an exit code, such as “SFDX: Deploy Source to Org ... ended with exit code 0.” Exit code 0 means that the command ran successfully.

12. In the VS Code editor, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).

13. Enter `SFDX`.

14. Select **SFDX: Open Default Org**.

    Your store opens in a separate browser.

15. In the left Navigation panel, click **Components**.

    The custom component displays under **Components** | **Custom Components**.

16. From the Custom area of the Lightning Components list, drag your Lightning web component to the page canvas.

17. To edit component properties, select the component on the page canvas, and enter changes in the component property editor.

<!-- document id=b53c99f7d1e574976060c68b7df3a384867e57852a4920f80bca24a0ce66929c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_create_a_role.md -->

# Create a Role in Control Center

A Control Center admin can create roles that apply to a subset of Control Center users. Roles can make configuration more flexible. This topic applies to B2C Commerce.

1. Log in to Control Center.
2. Click **Roles** > **New Role**.
3. Enter a name for the role and click **Save**. The role is added to the Roles view.
4. Select the newly added role. A page opens with tabs to Add Instances and Users.
5. In the **Add Instances** tab, add the role to one or more instances. The Select Instances slider opens, which lists all the realms in your organization. Each instance is individually selectable.
   **note:** To select all sandbox instances instead of individually selecting them, select the **All Sandboxes** pseudo instance. This option indicates to the system that you want the same permissions to apply to all sandbox instances in the realm. The All Sandboxes pseudo instance applies to any future sandboxes that you create in the realm.
   - Select one or more instances in one or more realms, and click Add. The instance is now available on the Instances tab, organized by realm.
   - For each instance, grant these permissions for the role:
     - Reset–A user can initialize an instance using Reset. Grant this permission for SIG sandboxes only, not PIG instances.
     - Start/Stop–A user can stop, start, and restart an instance.
     - View Statistics–A user can view usage statistics for an instance.
     - Grant Permissions–The user can give other users permissions for the instance. Users can only grant permissions currently granted to them; they can't grant permissions they don't have.
6. Assign users to the role.
   - Click **Users** > **Add Users**. In the Users slider, there are two tabs:
     - Inside Organization–Lists all Control Center admins or users in Account Manager for your organization.
     - Outside Organization–Lists individuals outside your organization that you work with, and want them to have Control Center access. For example, an individual in an implementation partner's organization, or if you're an implementation partner, and you want to specify individuals in the client's organization.
7. (Optional) On the Inside Organization tab, select one or more users to assign to the role, and click **Add**.
8. (Optional) On the Outside Organization tab, add a user external to the organization. Before you can add an outside user, grant that user Control Center Administrator or the Control Center User role in Account Manager.
   - On the **Outside Organization** tab, enter the user's email address, then select the user. If you don't see the user in the list, the email address isn't valid.
   - Click **Add**. This address becomes the outside user's login credential for Account Manager.

<!-- document id=896d9e9c8299b8f40378201a16b53652fb52ceb3b98dd064d28d30d0037defd4 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-create-sample-lwc.md -->

# Create a Sample Lightning Web Component

Create a sample custom component to deploy from SFDX to an authorized org. You can then reuse content from this Lightning web component file structure.
**note:** To display your LWR component in Experience Builder, you must specify target and capability configuration values in the `.js-meta.xml` file. You can also make component properties editable in Experience Builder.

1.  In the Visual Studio Code editor, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).

2.  Enter `SFDX`.

3.  Select **SFDX: Create Lightning Web Component**.

    Don’t select SFDX: Create Lightning Component, which creates an Aura component.

4.  Name the component, for example `helloWorld`.

5.  To accept the default `force-app/main/default/lwc` location, press **Enter**.

6.  To view the new files in Visual Studio Code Explorer, press Enter.

    ![Screenshot of Hello World LWC component in SFDX project.](https://developer.salesforce.com/media/d2c-commerce/helloWorld_lwc.png)

7.  Open the HTML file (for example, `helloWorld.html`), and write or copy and paste the HTML code for your project.

8.  Save the file.

9.  Open the JavaScript file (for example, `helloWorld.js`), and write or copy and paste the JavaScript code for your project.

10. Save the file.

11. Open the XML file (for example, `helloWorld.js-meta.xml`), and write or copy and paste the XML code for your project.

12. In the XML file, define the component design configuration values for Experience Builder. See [XML Configuration File Elements](https://developer.salesforce.com/docs/platform/lwc/guide/reference-configuration-tags.html).

    | Option                                   | Description                                                                                                                                                                           |
    | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **_`lightningCommunity__Page`_**         | For a custom drag-and-drop component on an LWR page in Experience Builder (appears in the Components panel).                                                                          |
    | **_`lightningCommunity__Page_Layout`_**  | For a custom page layout component in an LWR site in Experience Builder (appears in the Page Layout Window).                                                                          |
    | **_`lightningCommunity__Theme_Layout`_** | For a custom theme layout in an LWR site in Experience Builder (appears in Settings in the Theme area).                                                                               |
    | **_`lightningCommunity__Default`_**      | Enables editable component properties when the component is selected in Experience Builder. Supported property attribute types include integer, string, boolean, picklist, and color. |

    1.  To make your component usable in Experience Builder, set `isExposed` to `true`, and define `{lightningCommunity__Page}`, `{lightningCommunity__Page_Layout}`, or `{lightningCommunity__Theme_Layout}` in `targets`.

    2.  To include properties that are editable when the component is selected in Experience Builder, define `{lightningCommunity__Default}` in targets and define the properties in `targetConfigs`.
    3.  [Lightning Locker and Lightning Web Security (LWS)](https://developer.salesforce.com/docs/atlas.en-us.communities_dev.meta/communities_dev/communities_dev_security_locker_csp.htm) are disabled in B2B and D2C store LWR templates. To configure the component to run without Lightning Locker or LWS, define `{lightningCommunity__RelaxedCSP}` in `capabilities`.

## Example

The snippet specifies a custom component for an LWR page in Experience Builder, enables component property editing, and enables the component to run without Lightning Locker or LWS.

```nolang

<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentHelloWorld xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>59.0</apiVersion>
     <isExposed>true</isExposed>
    <targets>
        <target>lightningCommunity__Page</target>
        <target>lightningCommunity__Default</target>
    </targets>
    <capabilities>
        <capability>lightningCommunity__RelaxedCSP</capability>
    </capabilities>
</LightningComponentHelloWorld>
```

**See Also**

- [Deploy a Custom Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-deploy-lwc-component.htm)

<!-- document id=b90d116b38c2a1e7e00e98b12c009d77c2a45adb4dc87fa2f1e93795ce79c9d9 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-client-side-component.md -->

# Create a Saved Payment Method Record from a Client-Side Component

Buyers can save their payment details directly from a buyer-facing client-side component. The client-side component calls a third-party payment gateway to tokenize the buyer’s payment method. It then sends the token and related metadata to Salesforce by using the SavedPaymentMethod sObject API. Salesforce creates the Saved Payment Method (SPM) record.

This flow supports only third-party payment gateways and these payment methods categories:

- Alternative Payment Methods (APMs)
- Digital Wallets (such as Amazon Pay)
- Credit Cards

## Before You Begin

Before you begin, make sure your configuration meets these requirements.

- Payment gateway tokenization is configured. Your storefront or third-party gateway must tokenize the buyer’s payment details before sending any information to Salesforce.
- Buyer is authenticated and has access to the SavedPaymentMethod sObject API.
- Supported payment types—APMs, Digital Wallets, and Credit Cards—are configured in your Payments setup.
- Required fields such as paymentMethodType and payment token are available in your client-side component.
- HTTPS securely transmits all tokenized data.

## How It Works

1. Buyer enters their payment details in your storefront component.
2. Client-side component calls the third-party payment gateway to tokenize the payment method.
3. The gateway returns a payment token.
4. Client-side component sends the token and related payment metadata to the SavedPaymentMethod sObject API. Submit this information using one of the following ways:
   - [Synchronous saved payment method creation](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-spm-client-side-create-sync.md)
   - [Asynchronous saved payment method creation](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-spm-client-side-create-async.md)
5. Salesforce validates the request and creates the SPM record, including data such as:
   - Last four digits, expiration date, and name on card
   - Gateway token
6. The SPM record becomes available for future use by the Billing Engine.

**See Also**

- [_Object Reference for the Salesforce Platform_: SavedPaymentMethod](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_savedpaymentmethod.htm)

<!-- document id=7144ae13e8e80f3e97c2d0bea0a1471248b5a5991c6da41dca5c4cab02aeba4c url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-import-tokens-create.md -->

# Create a Saved Payment Method Using the sObject API

Use SavedPaymentMethod sObject API to create Saved Payment Method (SPM) records directly in Salesforce. To import payment details previously tokenized and stored by your payment gateway, include the existing payment token and related tokenized details in your request. The API creates the SavedPaymentMethod record and returns the Salesforce-generated SPM ID, which you then use for future transactions initiated from Salesforce.

**Resource**

`/services/data/<version>/sobjects/SavedPaymentMethod`

**Resource example**

`https://<my-domain>.salesforce.com/services/data/66.0/sobjects/SavedPaymentMethod`

**HTTP method**

POST

**Request body**

The API validates the input and creates the record in the SavedPaymentMethod object.

**Sample JSON request**

```json
{
  "merchantAccountId": "8zbSM0000000CxFYAU",
  "referenceOwnerId": "001SM00000GPtUqYAL",
  "paymentGatewayId": "0b0SM0000002VJ3YAM",
  "gatewayReference": "cus_Ssp02fOccymkwz",
  "status": "Active",
  "type": "card",
  "usageType": "OffSession",
  "name": "Visa....1111",
  "checksum": "unique_hash_ahht",
  "gatewayToken": "pm_1Rx3MvRBJ3juuXWQYIxYgVMc",
  "last4": "1234",
  "processingMode": "External",
  "expiryYear": "2030",
  "expiryMonth": "09"
}
```

| Name                        | Type   | Description                                                                                                                                                                                                                                                                                                                                               | Required or Optional                                                                    |
| --------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `checksum`                  | String | Specifies the unique value provided by the payment gateway. For example, use `pspReference` for Adyen and `fingerprint` for Stripe. The Checksum field is used in conjunction with paymentgatewayId and referenceOwnerId to enforce uniqueness and prevent duplicate SPM creation. An index on these three fields supports efficient duplicate detection. | Required                                                                                |
| `expiryYear`                | String | The year the payment method expires.                                                                                                                                                                                                                                                                                                                      | Optional <ul><li>This field is required for the card payment method. </li></ul>                       |
| `expiryMonth`               | String | The month the payment method expires.                                                                                                                                                                                                                                                                                                                     | Optional <ul><li>This field is required for the card payment method.  </li></ul>                      |
| `extendedPaymentMethodType` | String | The actual payment method type for extended APM/Wallet scenarios.                                                                                                                                                                                                                                                                                         | Optional <ul><li>This field is required if the `type` is `extd_wallet` or `extd_apm_type`.</li></ul>  |
| `gatewayToken`              | String | An unencrypted unique token ID generated by the payment gateway to represent the card payment method during transactions.                                                                                                                                                                                                                                 | Optional <ul><li> This field is required for creating an active Saved Payment Method. </li></ul>      |
| `gatewayReference`          | String | A reference to the saved payment owner at the payment gateway. For example, a Stripe customer ID.                                                                                                                                                                                                                                                         | Required                                                                                |
| `merchantAccountId`         | String | The Salesforce Payments merchant account ID.                                                                                                                                                                                                                                                                                                              | Required                                                                                |
| `name`                      | String | The name of the saved payment method.                                                                                                                                                                                                                                                                                                                     | Required                                                                                |
| `paymentGatewayId`          | String | The payment gateway that is used to create a gateway token. For transactions with a saved payment method in Salesforce, this field stores the payment gateway ID used in the transaction. This field is a relationship field.                                                                                                                             | Required                                                                                |
| `processingMode`            | String | Specifies the origin of the saved payment method. Possible values are: <ul><li>`External`–Set when importing an existing token using the SPM sObject API.</li><li>`Salesforce`–Set when creating an SPM record using Commerce CCS APIs.</li></ul>                                                                                                         | Optional <ul><li>Specify this field value as External when making the SPM sObject API call.</li></ul> |
| `referenceOwnerId`          | String | The ID of the Account or Contact record that owns the payment method.                                                                                                                                                                                                                                                                                     | Required                                                                                |
| `status`                    | String | The status of the saved payment method. Possible values are: <ul><li>`Active`</li><li>`AwaitingPayment`</li><li>`Errored—Failed`</li><li>`Expired`</li></ul>                                                                                                                                                                                              | Required                                                                                |
| `type`                      | String | The type of saved payment method. Possible values are: <ul><li>`au_becs_debit`</li><li>`bacs_debit`</li><li>`bancontact`</li><li>`card`</li><li>`ideal`</li><li>`sepa_debit`</li><li>`us_bank_account`–ACH Direct Debit</li></ul>                                                                                                                         | Required                                                                                |
| `usageType`                 | String | Determines whether the payment method is used on or off session. Possible values are: <ul><li>`OffSession`</li><li>`OnSession`</li><li>`RestrictedOffSession`</li></ul>                                                                                                                                                                                   | Required                                                                                |

**Response body**

The API returns the newly generated Salesforce Saved Payment Method ID of the imported record.

**Sample JSON response**

```json
{
  "id": "12qSM000000qKsHYAU",
  "success": true,
  "errors": []
}
```

| Name      | Type   | Description                                                                          |
| --------- | ------ | ------------------------------------------------------------------------------------ |
| `id`      | String | The ID of the saved payment method record.                                           |
| `success` | String | Indicates whether the saved payment method record was created successfully.          |
| `errors`  | String | Specifies the errors that occurred during the saved payment method creation request. |

You can use the Saved Payment Method creation process to bulk-import saved payment method records. For more information on bulk import, see [Bulk API](https://developer.salesforce.com/docs/atlas.en-us.api_asynch.meta/api_asynch/asynch_api_intro.htm).

**See Also**

- [_Object Reference for the Salesforce Platform_: SavedPaymentMethod](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_savedpaymentmethod.htm)
- [_REST API Developer Guide_: Create Records Using sObject Basic Information](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_basic_info_post.htm)
- [_REST API Developer Guide_: Create a Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm)
- [_Bulk API 2.0 and Bulk API Developer Guide_: Walkthrough for Bulk Insert](https://developer.salesforce.com/docs/atlas.en-us.236.0.api_asynch.meta/api_asynch/walkthrough_upload_data.htm)

<!-- document id=3a8decbb3e24e51cd510f55577e08cfdc51961b7a0403154ddce0377ed41f9c4 url=/developer/current/en-us/commerce-cloud/lwr-migration/guides/create-lwr-template.md -->

# Create a Store with the B2B Commerce (LWR) Template

To migrate your store from B2B Commerce Aura to LWR, create a store using the B2B Commerce (LWR) template. The preparation you do before migration can take place in your B2B Commerce Aura store, but you need a new template to complete the migration. For more information, see [Create a Store Using a Template](https://help.salesforce.com/s/articleView?id=commerce.comm_use_template.htm&type=5).

1. From Setup, in the Quick Find box, enter **Stores**, and then select **Stores**.
2. Click **Create a Store**.
3. From the template options, select **B2B Commerce (LWR)**, and then click **Get Started**.

![B2B Commerce (LWR) template option.](https://developer.salesforce.com/docs/media/lwr-migration/b2b_lwr.png)

4. Enter a Store Name and URL.
5. Click **Create**.

Your new LWR store is ready after a few minutes. Continue to the final steps of migration, including implementing any Lightning web components that you prepared in advance. See [Migrate Your Store](https://developer.salesforce.com/docs/commerce/lwr-migration/guide/store-migration.htm).

<!-- document id=0338b06b6cd1d7a594b51e20dfc27a2a8abbc6ec457cdc11f5ebc8690379447a url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/create-storefront-using-sandbox.md -->

# Create a Storefront Using an On-Demand Sandbox

To get started with creating a storefront app, set up an on-demand sandbox, and import sample data. Next, deploy your site using Managed Runtime.

**note:** Unlike the [quick start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.md) that uses the demo sandbox preset instance, which is preconfigured, this procedure is based on an on-demand sandbox that you create.

1. To create an on-demand sandbox, see [Create an On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/creating-an-on-demand-sandbox.md).
2. After creating your sandbox, ask an administrator with the Account Administrator role in Account Manager to create a SLAS Client. The SLAS client enables you to use Shopper APIs. See [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md) and [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).
3. Get the organization ID of your sandbox. See [Organization ID](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#organization-id) in [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html). Save this organization ID as you'll use it in a later step.
4. Get the short code for the sandbox's realm in Business Manager. See [Short Code](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#short-code) in [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html). Save this short code as you'll use it in a later step.
5. To be able to upload your app, create a Managed Runtime project and environment. When creating the new environment, connect the sandbox instance to the B2C Commerce instance, or for an existing environment, change the B2C Commerce instance Managed Runtime Environment settings. See [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md).
6. Add a proxy setting for Commerce API calls to avoid adding cross-origin resource sharing (CORS) headers. See [Configure Managed Runtime Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md#configure-managed-runtime-environments). For the path, use `api`, and for the host, use `{short-code}.api.commercecloud.salesforce.com` after replacing `{short-code}` with your sandbox instance short code, which you obtained earlier.
7. Get your project ID from Project Settings.
   - In [Runtime Admin](https://runtime.commercecloud.com/), click the name of your project.
   - Click **Project Settings** and copy the **Project ID** string. Example: `my-project`.
8. Create a storefront app based on the Retail React template and configure the app to point to your sandbox. To set up Node.js, see [Set Up Your Local Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-your-local-environment.md). Run this Node.js package to create the storefront.

   ```
   npx '@salesforce/pwa-kit-create-app@latest' --outputDir 'my-project'
   ```

9. Answer each prompt that the tool outputs.

   - For the template, choose the option for the retail app that uses your own B2C Commerce instance.
   - Choose whether you want template extensibility.
   - Enter your Managed Runtime project ID.
   - Enter your on-demand sandbox instance URL.
   - Enter SLAS client ID that you created earlier and whether your SLAS client is private.
   - Enter the site ID of your default site that you configured for your sandbox.
   - Enter the Commerce API organization ID of your sandbox that you obtained earlier.
   - Enter the Commerce short code of your sandbox that you obtained earlier.

10. In `config/sites.js`, make sure the correct currency and locale is selected for the default site.
11. From the app's directory, upload the storefront app to the Managed Runtime project and deploy it to the environment by typing this command in a Terminal window. Replace `{project-id}` with your project ID from **Project Settings** and `{environment-id}` with your target environment ID from **Environment Settings**.

```
npm run push -- -s "{project-id}" -m "Pushing this bundle for new app." -t "{environment-id}"

```

Congratulations! You created a storefront app based on your on-demand sandbox and uploaded it to Managed Runtime!

<!-- document id=5f4bf4450f17c6aada7ee3cccb1a702a9657f7a70334e9f3f8d037be096127db url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-storybook-create-story.md -->

# Create a Storybook Story

Create a story for a component for a specific rendered state to show its look and behavior. A component can have multiple stories, one per state—default, loading, and error. Add a story in the Storybook UI or use a code file.

To add a story in the Storybook UI, click **+** in the sidebar and search for your component. For more details, see [Working with Stories](https://storybook.js.org/docs/get-started/whats-a-story#working-with-stories) and [How to write stories](https://storybook.js.org/docs/writing-stories) in the Storybook documentation.

After you add a story in the Storybook UI, a story file is created. The story file format is `*.stories.tsx` (for example, `index.stories.tsx`, or named after a subcomponent such as `signup.stories.tsx`). Update the story file to customize it for the specific rendered state for displaying the component. If you add a story using a code file, add it in the `stories/` subfolder next to the component file.

This code example defines a Storybook story for a React component named `MyComponent`. It renders `MyComponent` in the `Default` state and exports a story with the primary variant.

```
import type { Meta, StoryObj } from '@storybook/react-vite';
import { MyComponent } from './MyComponent';

const meta: Meta<typeof MyComponent> = {
  title: 'Components/MyComponent',
  component: MyComponent,
  tags: ['autodocs'],
};

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = {
  args: {
    variant: 'primary',
  },
};

```

## Best Practices for Writing a Story

When you write a story, keep in mind these best practices.

- Use one file per component.
- To test components with different screen sizes, use Storybook's built-in viewport toolbar instead of creating separate stories.
- Use `args` & `argTypes` to make props interactive.
- Include play functions for interaction coverage.
- Add component description in the docs.
- Fix a11y issues directly in component logic.
- Avoid mocking real implementations incorrectly.
- Use mock data at the router boundary with story parameters. For components that require global context, wrap them in the provider stack via a decorator.

## See Also

- [GitHub: Storybook Readme](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/README-STORYBOOK.md)
- [Build and Test Components with Storybook](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storybook.md)

<!-- document id=e8a17b3f42de62e38b4c5a1f4488ee04ff0c1a3d3107c05075fc8a22aeee32b4 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-create-environment.md -->

# Create an Environment in Business Manager

Environments separate your production storefront from other storefronts for development and testing. Environments are hosted in Managed Runtime. The Storefront Next setup flow in Business Manager creates an environment for the new storefront. Admins can also create more environments for the storefront in Business Manager. Environments created in Business Manager are behind an embedded content delivery network (eCDN).

**note:** To create an environment in the Developer Workspace (Beta), see [Manage Storefront Next Environments in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-environments.md).

To create an environment:

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Administration > Sites > Storefronts**, and then click your storefront.
2. In the storefront detail page, in the Environments section, click **Create**.
3. Enter the environment name.
   The environment creation process starts. The environment status is updated to `Ready` after the environment is created. The system assigns a default region to your environment based on the region that's closest to your site. <!-- Double check -->

   ![Create an environment in Business Manager](https://developer.salesforce.com/docs/media/sfnext/sfnext-env-list.png)

4. Click **Create**.

**note:** - The default region for new environments is US East (N. Virginia) because it's located closest to on-demand sandboxes, which are commonly associated with development and testing environments.
- If you previously created an environment, you can [Edit Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md#edit-environment-settings) to connect it to a B2C Commerce instance and one or more site IDs.
- Production and non-production environments receive the same resources. All environments automatically scale to handle traffic in the same way. For details, see [Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md#environments).

## See Also

- [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md)
- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md)
- [Default Security Rules on On-Demand Sandbox (ODS) Instances](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ods-security-rules.md)

<!-- document id=cb457eb35ba7ab1fdc3adb8e3812713ac3b619262339897cb52c5daf82c57f12 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/creating-an-on-demand-sandbox.md -->

# Create an On-Demand Sandbox

**note:** If you already have a B2C Commerce instance, you can connect to it when you [generate a project](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.html#generate-the-project). In that case you can skip the steps below because you don't need an on-demand sandbox.

An on-demand sandbox (ODS) is a special B2C Commerce instance used for development and testing purposes. Although ODS instances are only temporary, they can be made available for up to 90 days.

The code for your PWA Kit storefront doesn’t include info data about catalogs, customers, baskets, etc. To get that critical commerce data, it needs to request it from an ecommerce back end using headless APIs.

Most PWA Kit projects start with at least one on-demand sandbox to serve as a back end while developing the storefront code. Some development teams share a small number of sandboxes while others create many different sandboxes for different purposes.

This guide helps you get started with PWA Kit as quickly as possible without tools or automation. The following steps walk you through creating an on-demand sandbox, importing a demo site, and using demo data. To create an ODS to test your own code and data, see [Get Started with On-Demand Sandboxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-get-started-sandboxes.html#create-an-on-demand-sandbox).

## Prerequisites

- An API client ID that you use for creating the ODS. Ask an administrator to create the API client ID using the steps in [Add an API Client in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5). <!-- (Salesforce internal users can get the client ID from [this Concierge article](https://concierge.it.salesforce.com/articles/en_US/Supportforce_Article/Account-Manager-access-and-role-updates).) -->
- The **Sandbox API User** role in Account Manager, with a tenant filter scoped to the sandbox realm.
- The four-character realm ID for your realm. If you don’t know your realm ID, ask your administrator.
- To import data into your ODS, you must have Business Manager administrator permission.

## Create an On-Demand Sandbox with the Sandbox REST API

To create an on-demand sandbox using B2C Commerce Developer Sandbox REST API:

1. Go to the [B2C Commerce Developer Sandbox REST API](https://admin.us01.dx.commercecloud.salesforce.com/). <!-- (Salesforce internal users must use a [different URL](https://admin.dx.commercecloud.salesforce.com/?_ga=2.31494974.1811675384.1719835170-2044223965.1718993109).) -->
2. Click **Authorize**.
3. Enter the API client ID for sandbox creation.
4. Click **Authorize**.
5. Log in with your Account Manager credentials.
6. To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.
7. In the Sandboxes section of the Sandbox API user interface, click to expand the `POST/sandboxes` method.
8. Click **Try it out**.
9. Delete the JSON object in the ProvisioningRequest field.
10. Copy the following JSON object and paste it into the ProvisioningRequest field:

    ```
    {
      "realm": "<your realm id>",
      "ttl": 24,
      "autoScheduled": false,
      "resourceProfile": "medium"
    }
    ```

11. Replace `<your realm id>` with your actual realm ID. Example: `zzdc`.
12. If you want the sandbox to be available for more than 24 hours, replace the `ttl` value with any number of hours up to 2160 (90 days).
13. You can also enter 0 or less for `ttl` to specify that the sandbox lasts until you delete it.
14. Click **Execute**.
15. If the ProvisioningRequest JSON is valid, a server response appears.
16. Copy the response body or click **Download** so that you can refer to it later.

In the next section, you must provide the Business Manager URL for your sandbox. The Business Manager URL can be found in the response body object in `data.links.bm`.

A Business Manager URL looks like this (but with its own unique hostname based on the realm ID and instance ID): `https://zzdc-001.dx.commercecloud.salesforce.com/on/demandware.store/Sites-Site`

More help with on-demand sandboxes is available in the B2C Commerce guide: [Get Started with On-Demand Sandboxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-get-started-sandboxes.html).

A more detailed Trailhead module is also available: [Salesforce B2C Commerce On-Demand Sandboxes](https://trailhead.salesforce.com/en/content/learn/modules/b2c-on-demand-sandbox).

## Import Sample Data

We recommend starting your PWA Kit project with a B2C Commerce instance that contains sample data.

Importing site data requires the Business Manager administrator permission. To import sample data into an instance:

1. Go to the Business Manager URL for your instance. (If you just created an ODS, it can take about 10 minutes for Business Manager to be available.)
2. Log in with your Account Manager credentials.
3. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Site Import & Export**.
4. Select **Storefront Reference Architecture Demo Sites**.
5. Click **Import**.
6. Select **Storefront Reference Architecture base**.
7. Click **Deploy**.
8. Click **Refresh** to track the progress the deployment.

After the deployment process is complete (about 15 minutes), your instance will contain sample data that can be used while developing with PWA Kit. The sample data import adds two sites: RefArch and RefArchGlobal.

## Rebuild Search Indexes

After your sample data has finished deploying, rebuild your search indexes to reflect the new data.

1. Go to the Business Manager URL for your instance.
2. Log in with your Account Manager credentials.
3. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Merchant Tools > _Your Site_ > Search > Search Indexes**.
4. Select the site you want to rebuild the indexes for, and select all of the indexes.
5. Click **Rebuild**.

## Set a Default Site

After importing the sample data, you have two sites, RefArch and RefArchGlobal, each for a different currency and locale. Choose a default site based on the desired currency and locale.

The RefArch site uses the US dollar (USD) currency and en-US locale. The RefArchGlobal site uses the British Pound (GBP) currency and en-GB locale. The `config/sites.js` file contains a definition of the sites that you configured in Business Manager. In the `/config/default.js` file, you can set the default site and optionally, map the site IDs with aliases. If no alias is defined for the site, then IDs are used in URLs. This example sets the default site to RefArch and defines an alias.

```
// /config/default.js

defaultSite: 'RefArch',
siteAliases: {
    RefArch: 'us'
},
```

## Troubleshooting

If you see broken catalog images on your PWA Kit storefront shortly after creating a new ODS, wait another 10 minutes or so for the issues to resolve on its own.

## See Also

- [On-Demand Sandboxes](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-developer-sandboxes.html)
- [Develop With Your On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-develop-with-on-demand-sandbox.html)

<!-- document id=15b5dd3a4e0c2602d2ddcfd86283b75d32a6649036cbb2d96455a80c13313ccd url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-create-sample-lwc-project.md -->

# Create an SFDX Project for the Custom Component

Create a Salesforce Developer Experience (SFDX) project to store your custom component files.

1.  In the Visual Studio Code editor, open the Command Palette by pressing Ctrl+Shift+P (Windows) or Cmd+Shift+P (macOS).

2.  Enter `SFDX`.

3.  Select **SFDX: Create Project**.

4.  Click Enter.

5.  Name the project, for example, `HelloWorldLightningWebComponent`, and click **Enter**.

6.  Select a folder to store the project.

7.  Click **Create Project**.

![Screenshot of LWC project files.](https://developer.salesforce.com/media/d2c-commerce/helloworld_lwc_project.png)

**See Also**

- [Authorize an Org for an SFDX Project](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-auth-org-lwc-project.htm)

<!-- document id=e02ac49efc72c8de7320681f3d979e4e743ed3c9c0a7cff73f1d889d07d09961 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-create-and-find-orders.md -->

# Create and Find Orders

## Find an Order

An agent can search for an order by order number, customer number, the entire or a portion of the customer name, or the entire customer email. The agent must have permission to use Customer Service Center.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Customer Service Center**.

2.  Select **Find an Order**.

3.  Enter the order number, customer number, the entire or a portion of the customer name, or the entire customer email.

4.  (optional) Apply a filter by clicking the filter icon to search by order number, customer number, customer name, product ID, creation date range or by attribute.

    **note:** Search for an order using order search attributes, such as currency code, coupon codes, order status. When you select the filter icon, the list of order search filters display in a slide-out panel.

5.  (optional) Apply a quick filter by clicking the filter icon next to the customer number or order status.

6.  To view order details, click the order number.

7.  To add a note to an order, click **Add Note**.

    **note:** Notes aren't visible on the order and are for the Customer Service Representative's reference only.

8.  To create an order, click **New Order**.

## Create an Order in CSC

An agent can create an order and set or change the order's customer. The agent must have permission to use Customer Service Center.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Customer Service Center**.

    **note:** Customer Service Center doesn't support different locales in a single site. Product and pricing information display in the default locale. You can place a customer order in a locale-specific site from the storefront.

2.  Select **Create an Order**.

3.  Click **Set Customer**, enter a portion or all of the customer's name, select the customer, and click **Set Customer**.

    1.  To specify an unregistered customer, a customer name isn't entered. An unregistered customer doesn't have an email address.

        Customize your site before the basket is submitted if your orders:

        - Require an email address and a customer name wasn't entered
        - Require a customer name according to your business rules

    2.  To change the customer for the order, click the pen icon in the customer's area.

    3.  To find a customer, click **Search**.

    4.  To create an order for a guest, click **Guest Order**.

        A guest refers to an order that includes an email address but not a customer name.

    5.  To register a customer, click **Register**.

4.  In Bill To, click **Please Select**, and enter the name and address. Alternatively, click **New Address** and enter the information.

    Addresses that are in the address book have an icon next to them. Addresses that aren't in the address book don't have an icon.

5.  Enter the item ID, name. Or, click **Add Product**, enter a search term, specify the order to show the results, and select the item.

    The product details appear in the customer's preferred locale's language.

6.  Select the product variation or option, if applicable.

7.  Select the quantity. Note the availability of the item, including whether an item is on backorder or can be preordered.

8.  (Optional) To override the price of the item, click the price, and enter the new price and reason for the override.

9.  Select the shipping address. Specify the shipping address as the billing address, if applicable.

    **note:** In Business Manager, manually add or update the billing and address form fields with dropdown values appropriate for your state or province and country. See Customer Service Center Customizable Areas. To verify address information, use Shop API hooks to access third-party address validation services.

10. Select the shipping method.

    The list of applicable shipping methods is loaded in the customer's preferred locale. If a customer doesn't have a preferred locale, the site's locale is used.

11. (Optional) To ship an item in the order to a different address:

    1.  Drag the product to the area below the existing shipment.

    2.  If the quantity of the product you are dragging is greater than one, select the number of items to include in the new shipment and click **Move**.

    3.  Select the shipping address for the new shipment.

12. (Optional) To override the shipping price, click the price, and enter the new price and reason for the override.

13. (Optional) Enter a coupon code or a source code.

    Based on your configuration, the field accepts only source codes, only coupon codes, or both.

    **note:** Some development work can be done to accurately calculate and display the sales tax and other applicable taxes on the Basket page in Customer Service Center.

14. Click **Submit Order**.

15. Select the payment method, and enter the payment information. Pay the balance in a single payment, multiple payments, or multiple payment methods.

    You can't enter a zero payment amount without attaching a payment tender. A tender lets you use multiple payment types on the same order. For example, a shopper received an incorrect or damaged item, and a replacement item was sent to the shopper without more payment required. You can then handle the payment tender in one of two ways.

    - Apply a payment to the shopper's payment method with an amount of zero
    - Create a tender type. Then apply a zero payment to the new tender type. Make sure that the payment provider is aware of this tender type so that the order can be processed without an authorization or capture transaction.

16. To specify multiple payments or multiple payment methods, click **Add Payment**.

    **note:** Some development work is required for Payment Service Provider (PSP) integration to work properly in Customer Service Center. The Shop API interactions require code to connect Customer Service Center with the B2C Commerce PSP cartridge. See [Payment Service Provider](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-csc-psp.md).

    1.  On the Add Payment Method panel, select the payment type, enter the amount and information, and click**Save**.

        If the balance due isn't paid in full, you see an incomplete payment message, and the Add Payment panel reopens. The remaining balance displays in red font.

    2.  Select the second payment method and information, and click **Save**.

    3.  Continue selecting the payment methods until the entire amount is paid.

        If the order is still not paid in full, the remaining balance displays in red font. To make another payment, click **Add Payment.**

        **note:** To submit the order, use the Shop API hooks.

    4.  Click **Review Order**.

        To change shipping or billing information, or to add or delete items, click **Back**.

    5.  If done, click **Submit Order** to create the order.

        To delete a payment, click **Details** and then click the trash can to delete that payment method or amount. This situation can occur when the order is submitted but the payment balance isn't paid in full.

17. (Optional) To override the price of the entire order, click the price, and enter the new price and reason for the override.

18. (Optional) To remove a price override, click it.

## Create an Order with the Storefront

The agent can place an order for a registered customer using the storefront in Customer Service Center. The agent creates the order to 'browse on behalf of' the customer. The agent must have permission to use Customer Service Center.

1.  Select **_site_** > **Merchant Tools** > **Ordering** > **Customer Service Center**.

2.  Click **Find Customer**.

3.  To create a customer, click **Create Customer** and enter the required information.

4.  To find a customer, enter a portion of the customer's name.

5.  (optional) To filter by customer number, first name, last name, email, company name, or phone click the Filter icon.

6.  From the customer record, or have identified the customer record, click **Storefront**.

    A new tab opens with the agent logged in as the registered customer. The agent can navigate the storefront, add items to the basket, apply promotions and promotional codes, and complete the checkout process for the registered customer. The agent can't make manual price adjustments for items, orders, or shipping. Orders placed by an agent reflect Customer Service Center as the channel_type and the agent's name or login information. Instead, they can be included for reporting purposes. There are no out-of-the-box reporting capabilities in Customer Service Center.

    Customize the storefront session to indicate an agent-initiated session on behalf of the customer. For an unregistered customer, the agent creates a user account in Customer Service Center.

**important:** Be sure that the browser settings permit popups for this site.

<!-- document id=7b205c308534fd80f4322d56b48b13098aa363ecbfee5316a44bcb648194495f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-customer-records.md -->

# Create and Manage Customer Records

## Find, Create, and Edit a Customer

An agent can search, create, and edit a customer. The agent must have permission to use Customer Service Center.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Customer Service Center**.

2.  Click **Find Customer**.

3.  To create a customer, click **Create Customer** and enter the required information.

    **note:** When you create a new registered account, make sure you click the password reset button to enable new users to set their own password. Development work is required to implement the reset password hook.

4.  To find a customer, enter a portion of the customer's name.

5.  (optional) To filter by customer number, first name, last name, email, company name, or phone click the Filter icon.

6.  To create an order for the customer, click **New Order** next to the customer's name and enter or select the information to create an order.

    Order number length can't be more than 50 characters.

7.  To edit the customer name, email, whether the customer is enabled, or preferred locale, click **Edit Customer**.

8.  To reset the customer's password, click **Reset Password**.

    **note:** Development work is required to implement the reset password hook. For details on using hooks to customize Customer Service Center, see [Customer Service Center Hooks](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-csc-hooks.md).

9.  To view a customer's orders, click the **Order History** tab.

    The customer's order history across sites appears.

10. To view the customer's baskets, click the **Baskets** tab.

11. To delete a customer basket, click the trash can icon beside the basket.

12. To see a customer's addresses, click the **Addresses** tab.

13. To remove a customer's address, click the trash can icon beside the address.

    **note:** In Business Manager, manually add or update the billing and address form fields with dropdown values appropriate for your state or province and country. See [Customer Service Center Customizable Areas](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-csc-customizable-areas.md).

14. To edit a customer's address, click the address ID.

15. To create an address for the customer, click **New Address**.

16. To browse the related storefront on behalf of the customer, click **Storefront**.

## Reset a Customer Password

An agent can help a customer reset their password in Customer Service Center. The agent must have permission to use Customer Service Center.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Customer Service Center**.

2.  Go to the Customer Detail page.

3.  Click the password reset button.

    The customer receives an email with a link to reset their password.

**note:** In order for the customer password reset to trigger sending the email, a developer in your organization has to implement the AfterPost hook.

## Edit Customer Information

The agent can edit a customer's first name, last name, or email in Customer Service Center. The agent must have the necessary permissions.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Customer Service Center**.

2.  Find a customer.

3.  Click **Edit Customer**.

4.  Modify the customer's first name, last name, or email.

5.  (optional) Click **Enable** to change the customer status.

6.  Click **Save**.

<!-- document id=8b8c418ba6fd4cc14a6128984c0db466b4a46f1209b198b4a324ac43e542a751 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-managing-sites-for-dev.md -->

# Create and Manage Sites for Development

Create and manage sites to test the storefronts you develop.

## List Sites and Manage Cartridge Paths with the B2C Commerce CLI

Use the B2C Commerce CLI to list sites and edit cartridge paths from your terminal. To install the tool and authenticate, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md).

```bash
# List all storefront sites on the instance
b2c sites list

# List the cartridge path for a site (or Business Manager)
b2c sites cartridges list --site-id RefArch
b2c sites cartridges list --bm

# Add a cartridge to a site's cartridge path
b2c sites cartridges add my_cartridge --site-id RefArch
b2c sites cartridges add my_cartridge --site-id RefArch --position first
b2c sites cartridges add my_cartridge --site-id RefArch --position after --target app_storefront_base

# Remove a cartridge
b2c sites cartridges remove my_cartridge --site-id RefArch
```

For the full command reference, see [Sites Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/sites.html) in the Agentic B2C Developer Toolkit documentation.

## Create a Site in Business Manager

When you create a site in Business Manager, the site contains no content or business data such as, products, prices, or features. Add data and images as part of your customization.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

    Use the sort buttons to list your sites in the order that you want them to appear.

2.  Click **New.**

3.  On the New Site page, enter the following information:

    - ID - Name the site up to 32 alphanumeric characters. You can't use spaces or special characters, but use hyphen and underscore characters.

      **important:** Don’t use the same ID for a shared library and a site. Doing so can cause unexpected errors. When you create a site in Business Manager, Salesforce recommends that you use a unique site name. Using unique site names helps prevent potential issues with processes running on the platform.

    - Currency - Select a default currency for the site. Multiple currencies are supported for a single site, but only one currency is the default.
    - Taxation - Select Net or Gross. U.S. sites usually require Net. and EMEA/Asia sites usually require Gross.
    - Description - Enter a description for the site.

4.  Click **Apply**.

    The site is created with the General, Settings, Cache, and Security tabs active. The system also creates directories for storefront-specific data (for example, images) and a domain for the new store on the server database.

    **note:** To develop on this site, you must have access privileges.

The next step is to disable page caching for the site, to immediately see changes made during development.

## Disable Page Caching for Development

Disable page caching for your site to immediately see changes made during development. Typically, you disable page caching only for sandbox instances, never for development or production instances.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites** > **_site_** > **Cache**.

    If you are developing a Business Manager extension instead of a new site, select **Administration** > **Sites** > **Manage Sites** > **Business Manager** > **Cache** .

2.  On the General tab of the Manage Sites page, for Instance Type, select **Sandbox/Development.**

3.  For Time to live (TTL) of static content, enter `0`.

4.  Deselect **Enable page caching**.

5.  Click **Apply**.

If you are working with SFRA, you already have a catalog assigned to the site, so the next step is to generate a search index. If you are developing a custom site, the next step is to assign a catalog.

## Assign Catalog and Locale

Assign a catalog for your site so that it has products and categories to display. Before creating your own site catalog, assign an existing catalog as a placeholder to get started.

1. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Products and Catalogs** > **Catalogs**.

2. Select **edit** on an existing catalog.

3. Select **Site Assignments** and select your newly created site. Click **Apply**

4. Select **_site_** > **Merchant Tools** > **Site Preferences** > **Locales**

5. Enable locales for your site and set one as the default. Click **Apply**

## Generate Search Indexes

In B2C Commerce Business Manager, create stop words and synonyms, modify guided search ranking, view statistics, view index documents along with their indexed fields, and rebuild indexes. Manage the capabilities of full text search indexes.

The search index uses one index for each index type: Product, Spelling, Content, Synonym, and Suggest. This index contains all localized and non-localized data for all storefront locales.

Dependencies between indexes require that some indexes are built together.

**note:** Run test queries on the product index.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Search** > **Search Indexes**.

2.  On the Search Indexes page, click the **Language Options** link to configure language specific stemming, and term completion and correction settings.

    If search isn’t required for the locale, exclude locales from the indexing process.

3.  On the Search Indexes page, if no full-text index has been built yet or you want to update an index, select one or more indexes using the checkboxes and click **Rebuild.**

    All index updates are performed asynchronously in the background for all locales. Old indexes remain operational until new indexes are ready.

    Progress information for the rebuild appears in the Status field.

4.  On the Search Indexes page, click the index type you want to manage, for example, click the **Product Index**.

    The Search Indexes details page that opens is where you manage full-text search indexes that are used in your site to fulfill search requests. This table shows the tabs that appear for each index type:

    | Index Type   | Tabs                                               |
    | ------------ | -------------------------------------------------- |
    | Product      | General, Sorting Attributes, Statistics, Documents |
    | Spelling     | General, Statistics, Documents                     |
    | Content      | General, Sorting Attributes, Statistics, Documents |
    | Synonym      | General, Statistics, Documents                     |
    | Suggestion   | General, Statistics, Documents                     |
    | Active Data  | General, Statistics, Documents                     |
    | Availability | General, Statistics, Documents                     |

5.  On the Search Indexes details page (Product Index page, for example), on the General tab, set the indexing mode for your storefront.

    Updates: Enable **Scheduled Index Rebuild** or **Incremental Index Updates**

    Indexing Mode: Select **Compact - Production** or **Verbose - Development**

6.  Click the **Sorting Attributes** tab (on the Product Index page) to add sorting attributes that are called directly from a pipeline.

    Only required for sorting attributes that aren’t used by the sorting rules feature.

7.  To view information about all indexed terms, click the **Statistics** tab. On this page you see:

    - Index summary: Number of indexed elements and the specific indexed fields.
    - Term frequency: By term and locale (for example, de_DE, default, en_US, and en_CA).
    - Dictionaries: By locale, where you can click **Analyze Terms** to analyze terms by locale.

8.  To see indexing information for a specific product, click the **Documents** tab.

## Disable a Site in Business Manager

Disable a site to test the offline maintenance page, to perform offline maintenance, or discontinue a microsite created around an event or product line.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

2.  Click **Site Name**.

3.  On the General tab on the Manage Sites page, in the Status list, select **Maintenance.**

4.  Click **Apply**.

5.  To confirm that the site is disabled, click **Storefront** on the main menu.

    Only the offline maintenance page for the site appears.

## View the Storefront

Open the current site storefront in a new tab from within Business Manager.

1.  On the main menu, click **Storefront**.

    If a site is selected, the storefront opens.

2.  Select the desired site.

    The storefront opens.

## Create a Hostname Allowlist

Provide a list of allowed hostnames to protect your site from certain host header attacks.

A B2C Commerce instance responds to a request only when the instance owner added the hostname to the allowlist. B2C Commerce-provided instance hostnames (`your.instance.hostname.example.com`) are always valid. You don’t have to add them to the allowlist explicitly.

**note:** This feature doesn't apply to hostnames in storefront sites.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

2.  On the Storefront - Sites page, click the **Manage the Business Manager site**.

3.  On the Sites-Site - Settings page, click the **Hostnames** tab.

    A list of allowed hostnames appears. B2C Commerce hostnames and configured hostname aliases are automatically included.

4.  Enter up to ten hostnames.

    If you want to access Business Manager with a customer-specific hostname (for example, `staging.customer.com`), add this hostname to the list of allowed hostnames. If you don't add the hostname, some Business Manager modules (for example, the Promotions or Coupons modules) display an error message.

## Continuing Development of a Storefront in Production

If you are updating or maintaining a site in production, import the contents of the production instance into your sandbox.

**note:** Salesforce recommends that you use a subset of your data in your sandboxes as sandboxes don't provide equivalent machine resources as a production instance. If you use the full data set in a sandbox instance, you'll run into performance issues, including but not limited to, long running search indexing and higher CPU usage due to large amounts of garbage collection.

For information on importing data into your sandbox from a production instance, see [Using Site Import/Export to Copy Instances](https://help.salesforce.com/s/articleView?id=cc.b2c_using_site_import_export_to_copy_instances.htm).

Custom jobs created for the production instance aren't run automatically on the sandbox, because doing so without checking or changing the job configuration can cause problems. Instead, custom jobs can still be run manually from within Business Manager.

<!-- document id=d457de856e2c9586bb75eaaa75b9843a9f6d2862edc03edb45aa538e9f6f3630 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-create-einstein-rec-comps.md -->

# Create Commerce Einstein Recommendations Components

Use Commerce Einstein Activity Tracking and Product Recommendations APIs to create custom components for your Salesforce Commerce B2C and B2B storefronts.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

<!-- document id=c518d48b152568e9ff375b759dbcdd2d50a7b1e0d50c01ea4993455261617830 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/scriptprogramming/creatingbusinessobjects.md -->

# Create Custom Business Objects

Create custom attributes for an existing system object. For example, create an object type of `ProcessingDays` to hold an integer that represents the number of days required to process the order.

If your data is especially complex, create a custom business object to handle the transaction. Creation of custom business objects can significantly impact overall performance, is typically unnecessary. Avoid creating a custom business object if there’s another possible solution.

Define custom business objects that require no explicit database schema changes. B2C Commerce uses the concept of metadata, where you first declare the data element, and then access it.

There are two parts to adding custom business objects to the B2C Commerce environment: definition and creation. You must use Business Manager to define a custom object. Use Business Manager, B2C Commerce JavaScript, or import pipelets to create the data for the custom object.

## Create a Custom Business Object Definition

Use Business Manager to create a custom business object definition. A custom object definition is available for use in all storefronts defined for the organization.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Custom Object Types**.

2.  To add a definition, click **Add**.

3.  Define your custom object and a key attribute.

    The attribute stores a unique key for every custom object of this type.

    For example, create a `ProcessingDays` object to inform customers how long it takes for their order to ship. Add a `ShipmentNo` key attribute.

4.  Click the **Attribute Definitions** tab.

    The system automatically creates three attributes for you: UUID, creationDate, and lastModified. These attributes store system data and can't be removed.

5.  To add more attributes, click **New**.

    For example, add the attributes `OrderProcessing`, `Shipping`, and `TotalShippingTime`.

6.  To save your changes, click **Apply**.

7.  To return to the previous page, click **Back**.

8.  To define attribute groups, click the **Attribute Grouping** tab.

    Attribute groups are shown in Business Manager and let you create or edit objects created through scripts.

9.  To add an attribute group, click **New**.

    For example, create an attribute group called `ShipmentTime`.

10. To add attributes to the group, click **Edit**.

    For example, add the attributes `OrderProcessing`, `Shipping`, and `TotalShippingTime`.

## Create a Custom Object Instance with Business Manager

Use Business Manager to create and manage an instance of a custom object. Instances of a custom object can be site-specific or organization-wide.

Store a custom object instance globally to make it available to the entire organization and all sites. Store instances locally per site. The custom object type definition is always available to the entire organization (to all sites).

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Custom Objects** > **Custom Object Editor**.

2.  Create an instance of a custom object.

3.  Assign values to the attributes.

    For example, assign `OrderProcessing` a value of 5, `Shipping` a value of 6, and `TotalShippingTime` a value of 11.

## Creating Custom Business Objects with Scripts

Add custom business objects through B2C Commerce JavaScript. This method offers the most flexibility and control.

Use the `dw.object` package, which contains these classes:

- `CustomObject`
- `CustomObjectMgr`

**note:** Refer to the API documentation for further details.

Sometimes you want to extend or modify data for an existing B2C Commerce object, such as a product, within a script using a wrapper object that includes a reference to a B2C Commerce object. If you want this information to persist in a pipeline after an interaction continue node, store it in a custom attribute for the object or a separate custom object. The context of the object is changed after an interaction continue node or interaction node and any custom script object you create, even one stored in the Pipeline Dictionary, doesn't let you access any objects referenced as part of that custom script wrapper object.

### Script Function with Reference to Product Object

The following script shows two functions. The first function, `execute()`, causes an error if the custom wrapper object (`containerObject()`) is stored in the Pipeline dictionary before an interaction continue node and then the product reference is accessed after the interaction continue node. The error is similar to the following.

```txt
?WARN: Invalid access to orm object PK{
com.demandware.beehive.core.capi.domain.PersistentObjectPOKey[com.demandware.beehive.xcs.internal.product.ProductPO]
[cdtVV9aacbTPYaaacOLbFjKMNQ]} from thread
{Thread[RequestHandlerServlet|19915763|Sites-SiteGenesis-Site|TestAPP15854-
Test|PipelineCall|D1uLw5zjszPGltCRMgqKwpyctSD1ayaYcfM=,5,main]} :
ORMObject context is invalid.
```

The second function, `executeX()`, doesn't cause an error.

```javascript
/**
 * @input inProduct             : Object
 * @output outProduct           : Object
 */

importPackage(dw.system);
importPackage(dw.value);
importPackage(dw.util);
importPackage(dw.catalog);

//
// this function doesn't work, because it uses a wrapper object
//
function execute(pdict: PipelineDictionary): Number {
  var PIPELET_NAME: String = "TestAvailability.ds";
  try {
    var container = pdict.inProduct;

    if (empty(container)) {
      var product = ProductMgr.getProduct("000906014545");
      var container = new containerObject();
      container.setProduct(product);
    }

    var availability = container.getProduct().getAvailabilityModel().getAvailabilityStatus();
    pdict.outProduct = container;
  } catch (e) {
    Logger.error("foo: " + e);
    return PIPELET_ERROR;
  }

  return PIPELET_NEXT;
}

function containerObject() {
  var _product = null;

  this.setProduct = function (product) {
    _product = product;
  };

  this.getProduct = function () {
    return _product;
  };
}

//
// this function works fine, because it doesn't use any wrapper object
//
function executeX(pdict: PipelineDictionary): Number {
  var PIPELET_NAME: String = "TestAvailability.ds";
  try {
    var product = pdict.inProduct;

    if (empty(product)) {
      var product = ProductMgr.getProduct("000906014545");
    }

    var availability = product.getAvailabilityModel().getAvailabilityStatus();
    pdict.outProduct = product;
  } catch (e) {
    return PIPELET_ERROR;
  }

  return PIPELET_NEXT;
}
```

### Creating Custom Objects

To use this structure, you would first import the package:

```javascript
importPackage(dw.object);
```

Then you would access the contents of the package, including all classes and methods as follows:

```javascript
var co: CustomObject = CustomObjectMgr.getCustomObject(type, keyValue);
```

In this case, getCustomObject is the method used by the CustomObjectMgr class to return a new custom object where the type ("ExampleType") is a string and the keyValue (123) is a number.

The following script returns a new custom object instance of the specified type, using the given key value.

```javascript
static createCustomObject(type : String, keyValue : Number) : CustomObject
```

**note:** The type declaration is used for code completion within the Studio environment, and ignored in the code.

<!-- document id=1a50fb6675e6706dc4b4a5a367a07688dddc0674174a4344301f62769db5fe5a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jobs/b2c-custom-job-steps.md -->

# Create Custom Job Step Types

To create a custom job step type, you must develop a task-oriented or chunk-oriented CommonJS script module or legacy pipeline to define what the step does. You must also create a JSON or XML `steptypes` file that describes the step, and then include the module or pipeline along with the `steptypes` file in a cartridge uploaded to the site.

## Run and Monitor Jobs with the B2C Commerce CLI

While iterating on a custom job step, you can run and inspect your job from the terminal by using the [B2C Commerce CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md) instead of clicking through Business Manager. To install the tool and authenticate, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md).

```bash
# Run a job and wait for it to complete
b2c job run my-custom-job --wait

# Pass step parameters
b2c job run my-custom-job -P "SiteScope={\"all_storefront_sites\":true}" -P OtherParam=value

# Run a built-in job with a JSON body
b2c job run sfcc-search-index-product-full-update --body '{"site_scope":{"named_sites":["RefArch"]}}'

# Inspect the log for the most recent execution (or a specific execution ID)
b2c job log my-custom-job
b2c job log my-custom-job abc123-def456

# Show only failed executions
b2c job log my-custom-job --failed

# Search recent job executions by status
b2c job search --job-id my-custom-job
b2c job search --status RUNNING,PENDING
```

For the full command reference, see [Job Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/jobs.html) in the Agentic B2C Developer Toolkit documentation.

To create a custom job step type, you must be familiar with creating and uploading a cartridge.

1. Create a cartridge.
2. Create a task-oriented or chunk-oriented CommonJS module to describe what the step does.
   A best practice is to put the CommonJS module in the `cartridge/scripts` directory or subdirectory, for example, `my_cartridge/cartridge/scripts/steps`.
   Instead of using a CommonJS module, use the UX Studio plug-in to the Eclipse IDE to create a pipeline. However, we recommend using CommonJS modules for jobs in the new framework.
3. Create a `steptypes.json` or `steptypes.xml` file that describes the job step and put the file in the root directory of the cartridge.
   Describe more than one custom job step in the same file. Each cartridge can have only one `steptypes.json` or `steptypes.xml` file.
4. Upload the cartridge, and include it in the cartridge path.
5. For a production system, replicate the code to production, and activate the code version that includes your cartridge.

When an administrator creates a job in Business Manager, custom steps defined in the `steptypes.json` or `steptypes.xml` file are listed as steps available to add to the job.

## Custom Job Step Type Modules

Define what a custom step type does using task- or chunk-oriented CommonJS script module, or a pipeline module, which executes a legacy pipeline.

**note:** Chunk-oriented steps can't be implemented with a pipeline module.

### Task-Oriented Script Module

A task-oriented CommonJS script module exposes a function to be called as the main function for the job step. When administrators create job steps using Business Manager, they set parameters that are available as scriptable objects for the module's function and for the `dw.job.JobStepExecution` object. The `dw.job.JobStepExecution` object allows read-only access to information about the current step execution and job execution.

The task-oriented script module is used as its best if there is a single task to execute where the progress can't be calculated or the boundaries are hard to calculate.

To control the exit status, the script module's function can return a `dw.system.Status` object. If the script finishes with an unhandled exception, the exit status code is **ERROR**, and the error status flag is true by default. If no status object is returned and no exception occurs, the status code is **OK** by default.

The following example is a task-oriented CommonJS module:

```js
var net = require( 'dw/net' );
var system = require( 'dw/system' );
var job = require( 'dw/job' );

const ConnectionFailedError = "ConnectionFailedError";
const FileNotFoundError = "FileNotFoundError";

function downloadFromFTP( hostURL, timeout, fileName )
{
  var ftpClient = new net.FTPClient();
  ftpClient.setTimeout( timeout );
  ftpClient.connect( hostURL );
  if( !ftpClient.connected )
  {
    throw ConnectionFailedError;
  }
  else
  {
    ...
    if( file == null )
    {
      throw FileNotFoundError;
    }
    ...
    ftpClient.getBinary(...)
  }
}

function downloadFromSFTP(...)
{
  ...
}

exports.ftpDownload = function( parameters, stepExecution )
{
  try
  {
    if( parameters.ftpType == 'sftp' )
    {
      downloadFromSFTP( parameters.hostURL, parameters.timeout, parameters.fileName, parameters.userID, parameters.password );
    }
    else
    {
      downloadFromFTP( parameters.hostURL, parameters.timeout, parameters.fileName );
    }

    return new system.Status( system.Status.OK );
  }
  catch( ConnectionFailedError )
  {
    return new system.Status( system.Status.ERROR, null, "Connection Failed!" );
  }
  catch( FileNotFoundError )
  {
    return new system.Status( system.Status.OK, "FILE_NOT_FOUND", "The file could not be found." );
  }
}
```

### Chunk-Oriented Script Module

A chunk-oriented CommonJS script module reads, processes, and writes items in chunks of a defined size. If the list contains more items than can be processed in one chunk, a new chunk is started. A chunk-oriented script can include any series of processing steps, not just database transactions. A job step that uses a chunk-oriented script allows fine-grained progress monitoring because the number of elements that are written is updated each time a chunk is finished.

The chunk-oriented script module is used as its best if the job step type processes countable data where the boundaries can be quickly calculated or are fixed.

When administrators create jobs using Business Manager, they set parameters that are available as scriptable objects for each exposed module function and for the `dw.job.JobStepExecution` object. The `dw.job.JobStepExecution` object allows read-only access to information about the current step execution and job execution. You can't define the exit status for a chunk-oriented script module. Chunk modules always finish with either **OK** or **ERROR**.

In the following chunk processing example, a list of 15 orders is exported to a file. Each chunk includes four orders:

<table>
<thead>
<tr>
<th>Chunk </th>
<th>Steps </th>
</tr>
</thead>
<tbody>
<tr>
<td>Chunk 1 </td>
<td>
  <ol>
    <li>Read Order 1</li>
    <li>Process Order 1</li>
    <li>Read Order 2</li>
    <li>Process Order 2</li>
    <li>Read Order 3</li>
    <li>Process Order 3</li>
    <li>Read Order 4</li>
    <li>Process Order 4</li>
    <li>Write Order 1</li>
    <li>Write Order 2</li>
    <li>Write Order 3</li>
    <li>Write Order 4</li>
  </ol>
</td>
</tr>
<tr>
<td>Chunk 2 </td>
<td>
  <ol>
    <li>Read Order 5</li>
    <li>Process Order 5</li>
    <li>Read Order 6</li>
    <li>Process Order 6</li>
    <li>Read Order 7</li>
    <li>Process Order 7</li>
    <li>Read Order 8</li>
    <li>Process Order 8</li>
    <li>Write Order 5</li>
    <li>Write Order 6</li>
    <li>Write Order 7</li>
    <li>Write Order 8</li>
  </ol>
</td>
</tr>
<tr>
<td>Chunk 3 </td>
<td>
  <ol>
    <li>Read Order 9</li>
    <li>Process Order 9</li>
    <li>Read Order 10</li>
    <li>Process Order 10</li>
    <li>Read Order 11</li>
    <li>Process Order 11</li>
    <li>Read Order 12</li>
    <li>Process Order 12</li>
    <li>Write Order 9</li>
    <li>Write Order 10</li>
    <li>Write Order 11</li>
    <li>Write Order 12</li>
  </ol>
</td>
</tr>
<tr>
<td>Chunk 4 </td>
<td>
  <ol>
    <li>Read Order 13</li>
    <li>Process Order 13</li>
    <li>Read Order 14</li>
    <li>Process Order 14</li>
    <li>Read Order 15</li>
    <li>Process Order 15</li>
    <li>Write Order 13</li>
    <li>Write Order 14</li>
    <li>Write Order 15</li>
  </ol>
</td>
</tr>
</tbody>
</table>

Chunk 4 read, processed, and wrote fewer items than the previous chunks, because only three items were left on the list.

To process the data in chunks, the developer has to implement the following methods:

| Function      | Required or Optional | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| beforeStep    | Optional             | Executed before a chunk step begins. Implements logic before all items of all chunks are read, processed, and written.                                                                                                                                                                                                                                                                                                                                   |
| getTotalCount | Optional             | Returns the total number of items that are available. Called by the framework exactly once before chunk processing begins. A known total count allows better monitoring, for example, to show that 50 of 100 items have already been processed.                                                                                                                                                                                                          |
| beforeChunk   | Optional             | Executed before a chunk begins. Implements logic before a chunk of S items is read, processed, and written.                                                                                                                                                                                                                                                                                                                                              |
| read          | ❗Required❗         | Returns one item or nothing if there are no more items.                                                                                                                                                                                                                                                                                                                                                                                                  |
| process       | ❗Required❗         | Transforms items and applies business logic to them. It receives the item returned by the read function, performs a process, and returns one item.The item returned can be the same item that the read function returned if no processing logic is necessary, or it can be a new item of a different type. If the process function returns nothing, then the read function item is filtered and doesn't appear in the list of items to be written later. |
| write         | ❗Required❗         | Receives a list of items. The list size matches the chunk size or, if the number of items in the last available chunk is smaller, it is smaller. The write function returns nothing.                                                                                                                                                                                                                                                                     |
| afterChunk    | Optional             | Executed after a chunk finishes. Implements logic after a chunk of S items has been read, processed, and written successfully.                                                                                                                                                                                                                                                                                                                           |
| afterStep     | Optional             | Executed after a chunk step finished successfully. Implements logic after all items of all chunks are read, processed, and written successfully.                                                                                                                                                                                                                                                                                                         |

The following example is a chunk-oriented CommonJS module:

```js
var system = require("dw/system");
var catalog = require("dw/catalog");
var job = require("dw/job");
var io = require("dw/io");

var products;
var fileWriter;

exports.beforeStep = function (parameters, stepExecution) {
  fileWriter = new io.FileWriter(new io.File(io.File.IMPEX), parameters.ExportFileName);
  products = catalog.ProductMgr.queryAllSiteProducts();
  fileWriter.writeLine("<products>");
};

exports.getTotalCount = function (parameters, stepExecution) {
  return products.count;
};

exports.read = function (parameters, stepExecution) {
  if (products.hasNext()) {
    return products.next();
  }
};

exports.process = function (product, parameters, stepExecution) {
  if (product.isOnline()) {
    return "<product>" + product.getID() + "</product>";
  }
};

exports.write = function (lines, parameters, stepExecution) {
  for (i = 0; i < lines.size(); i++) {
    fileWriter.writeLine(lines.get(i));
  }
};

exports.afterStep = function (success, parameters, stepExecution) {
  if (success) {
    fileWriter.writeLine("</products>");
  }

  fileWriter.close();
  products.close();
};
```

### Pipeline Module

A pipeline module executes the provided pipeline with the defined parameters. The pipeline is an XML file created and changed with UXStudio, a plugin for Eclipse.

The pipeline module should not be used anymore and available pipeline-based modules should be migrated to CommonJS script modules.

## Job Step Type Exit Status

In a **task-oriented script module** or **pipeline** for a custom job step, create an object of type `dw.system.Status` to control the exit status and error message for the step. The `Status` object includes a boolean flag that indicates whether or not the status is error, and also a status code and message. Messages appear in Business Manager and are written to log files. _You can't define the exit status for a chunk-oriented script module._

**Chunk-oriented script modules** _always_ finish with either OK or ERROR.

### Rules for Continuing Job Execution

The job framework uses the following rules to detect the step status and determine if job execution can continue:

| dw.system.Status.isError() | dw.system.Status.getCode() | Status Code | Error Status Flag | Job Execution Behavior (if not handled by a transition) | Notes                                                                                                                                          |
| -------------------------- | -------------------------- | ----------- | ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| n/a                        | n/a                        | OK          | FALSE             | Continue                                                |                                                                                                                                                |
| FALSE                      | n/a                        | OK          | FALSE             | Continue                                                |                                                                                                                                                |
| FALSE                      | OK                         | OK          | FALSE             | Continue                                                |                                                                                                                                                |
| FALSE                      | `<CUSTOM>`                 | `<CUSTOM>`  | FALSE             | Continue                                                | Custom status codes can't contain any comma (,) or wildcard (\*) characters, include leading or trailing whitespace, or exceed 100 characters. |
| TRUE                       | n/a                        | ERROR       | TRUE              | Stop                                                    |                                                                                                                                                |
| TRUE                       | ERROR                      | ERROR       | TRUE              | Stop                                                    |                                                                                                                                                |
| TRUE                       | `<CUSTOM>`                 | ERROR       | TRUE              | Stop                                                    | Custom status codes for statuses that represent an error aren't supported. If a custom status code is used the code is replaced with ERROR.    |

### Rules When No Status Object

If a pipeline or script module doesn't return a `dw.system.Status` object or if a pipeline or script module's function fails before a `Status` object is returned, the following rules apply.

#### Script Module Based Steps

| Script Module Function                                   | Status Code | Error Status Flag | Job Execution Behavior (if not handled by a transition) |
| -------------------------------------------------------- | ----------- | ----------------- | ------------------------------------------------------- |
| Finished with unhandled JavaScript exception             | ERROR       | TRUE              | Stop                                                    |
| Runtime exceeds configured (or default) timeout          | ERROR       | TRUE              | Stop                                                    |
| Returns an object that isn't a `dw.system.Status` object | OK          | FALSE             | Continue                                                |
| Returns no object                                        | OK          | FALSE             | Continue                                                |

#### Pipeline-Based Steps

| Pipeline                                                                                              | Status Code | Error Status Flag | Job Execution Behavior (if not handled by a transition) | Notes                                   |
| ----------------------------------------------------------------------------------------------------- | ----------- | ----------------- | ------------------------------------------------------- | --------------------------------------- |
| Finished with stop node                                                                               | ERROR       | TRUE              | Stop                                                    |                                         |
| Finished with interaction node                                                                        | ERROR       | TRUE              | Stop                                                    |                                         |
| Finished with unhandled exception                                                                     | ERROR       | TRUE              | Stop                                                    |                                         |
| Finished with end node                                                                                | OK          | FALSE             | Continue                                                | The name of the end node isn't relevant |
| Stores an object that isn't a `dw.system.Status` object under key `ExitStatus` in pipeline dictionary | OK          | FALSE             | Continue                                                |                                         |
| Stores no object under key `ExitStatus` in pipeline dictionary                                        | OK          | FALSE             | Continue                                                |                                         |

## Steptypes.json Definition File

Custom Step Types can be registered in the system with a `steptypes.json` file. Within this file, you describe the step types of the cartridge, their parameters, and status codes.

The file must be named `steptypes.json` and placed in a custom cartridge in the **root** folder. Each cartridge supports only **one** `steptypes.json` file.

```
my_cartridge
├── cartridge
│   ├── controllers
│   ├── scripts
│   ├── (other cartridge folders)
│   └── my_cartridge.properties
└── steptypes.json
```

The `steptypes.json` file requires a specific JSON syntax. If a `steptypes.json` file contains errors, the errors are logged and the custom step types aren't registered. The system then loads step types from the `steptypes.json` files of other cartridges.
A typical error message for an invalid `steptypes.json` file is:
`Invalid step [Step1]! Type with id [custom.MyCustomStep1] is unknown!`.

**note:** Each cartridge supports either a `steptypes.json` or a `steptypes.xml` file. Having both files in the same cartridge isn't supported.

### Schema File

Use the `steptypes.schema.json` file to check the syntax of your `steptypes.json` file.
The `steptypes.schema.json` file can be downloaded [here](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/steptypes.schema.json).

### Syntax/Construction

#### Root

```
{
  "step-types": {
    "script-module-step": [],
    "chunk-script-module-step": [],
    "pipeline-step": []
  }
}
```

| Attribute                | Required or Optional                                                                                  | Description                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| step-types               | ❗Required❗                                                                                          | The root object of the steptypes.json file.           |
| script-module-step       | Basically optional, but required if no `chunk-script-module-step` or `pipeline-step` is defined.      | Defines one or more task-oriented script step types.  |
| chunk-script-module-step | Basically optional, but required if no `script-module-step` or `pipeline-step` is defined.            | Defines one or more chunk-oriented script step types. |
| pipeline-step            | Basically optional, but required if no `script-module-step` or `chunk-script-module-step` is defined. | Defines one or more pipeline-based step types.        |

#### script-module-step

```json
{
  "@type-id": "custom.MyCustomScriptStepType",
  "@supports-parallel-execution": "true",
  "@supports-site-context": "true",
  "@supports-organization-context": "false",
  "description": "My custom script step type",
  "module": "my_cartridge/cartridge/scripts/steps/myModule.ds",
  "function": "myFunctionName",
  "transactional": "false",
  "timeout-in-seconds": "900",
  "parameters": {
    "parameter": []
  },
  "status-codes": {
    "status": []
  }
}
```

| Attribute                      | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @type-id                       | ❗Required❗         | Identifies the step type. <br> This is the name that users see in Business Manager, so make it descriptive. Must begin with `custom.`. <br>Must not contain leading or trailing white space or more than 100 characters. <br>Must be unique within the job definition. You can't register multiple steps with the same `@type-id` in different cartridges.<br> The `@type-id` is validated as unique by parsing the `steptypes` files from all cartridges on the cartridge path. If there is a step with the same `@type-id`, the step isn't loaded. <br>The `@type-id` value can't be the same as any system step, for example, `ExecutePipeline` or `IncludeStepsFromJob`. |
| @supports-parallel-execution   | Optional             | Determines if the step type can be used in parallel with itself or other step types. <br>Must have value `true` or `false`. Default is `true`. <br>If `false`, split flows that contain steps of this type are always executed sequentially and never in parallel. <br>If `true`, split flows that contain steps of this type are executed in parallel, as long as: <br>- The split flows don't contain steps with `supports-parallel-execution = false`. <br>- The split flows aren't configured to be executed sequentially. <br>- There are enough resources available to do parallel execution.                                                                          |
| @supports-site-context         | Optional             | Determines if the step type is intended to be used in site context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with one or more sites as scope. <br>If `false`, steps of this type can't be used for flows with one or more sites as scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                     |
| @supports-organization-context | Optional             | Determines if the step type is intended to be used in organization context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with organization scope. <br>If `false`, steps of this type can't be used for flows with organization scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                             |
| description                    | Optional             | The description of the step type. Not shown in Business Manager. Must not exceed 4000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| module                         | ❗Required❗         | Path to the script module to be executed. Must not contain leading or trailing white space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| function                       | ❗Required❗         | The function of the script module to execute. Must not contain leading or trailing white space. If not defined, the script module must export a function named `execute`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| transactional                  | Optional             | Indicates if the module requires a database transaction. <br>Must have value `true` or `false`. Default is `false`. <br>If this value is set to `true`, the job step executes as a single, potentially very large, transaction. <br>To avoid a negative impact on system performance and allow more granular transaction control, keep the default setting of `false`. Implement transaction handling within the job step using the `dw.system.Transaction` API.                                                                                                                                                                                                             |
| timeout-in-seconds             | Optional             | Sets the timeout in seconds for the script module's function. Must be an integer greater than zero. <br>There is no default timeout, but setting a limit is recommended.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| parameters                     | Optional             | Parameters for the step, which the user configures in Business Manager. Contains one `parameter` array-element with one or more `parameter` objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| status-codes                   | Optional             | Defines the meta data for status codes returned for the step. Contains one `status` array-element with one or more `status` objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### chunk-script-module-step

```json
{
  "@type-id": "custom.MyCustomChunkScriptModuleStep",
  "@supports-parallel-execution": "false",
  "@supports-site-context": "true",
  "@supports-organization-context": "false",
  "description": "My custom chunk script step type",
  "module": "my_cartridge/cartridge/scripts/steps/myModule.ds",
  "before-step-function": "beforeStep",
  "total-count-function": "getTotalCount",
  "before-chunk-function": "beforeChunk",
  "read-function": "read",
  "process-function": "process",
  "write-function": "write",
  "after-chunk-function": "afterChunk",
  "after-step-function": "afterStep",
  "chunk-size": 10,
  "transactional": "true",
  "parameters": {
    "parameter": []
  },
  "status-codes": {
    "status": []
  }
}
```

| Attribute                      | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @type-id                       | ❗Required❗         | Identifies the step type. <br> This is the name that users see in Business Manager, so make it descriptive. Must begin with `custom.`. <br>Must not contain leading or trailing white space or more than 100 characters. <br>Must be unique within the job definition. You can't register multiple steps with the same `@type-id` in different cartridges.<br> The `@type-id` is validated as unique by parsing the `steptypes` files from all cartridges on the cartridge path. If there is a step with the same `@type-id`, the step isn't loaded. <br>The `@type-id` value can't be the same as any system step, for example, `ExecutePipeline` or `IncludeStepsFromJob`. |
| @supports-parallel-execution   | Optional             | Determines if the step type can be used in parallel with itself or other step types. <br>Must have value `true` or `false`. Default is `true`. <br>If `false`, split flows that contain steps of this type are always executed sequentially and never in parallel. <br>If `true`, split flows that contain steps of this type are executed in parallel, as long as: <br>- The split flows don't contain steps with `supports-parallel-execution = false`. <br>- The split flows aren't configured to be executed sequentially. <br>- There are enough resources available to do parallel execution.                                                                          |
| @supports-site-context         | Optional             | Determines if the step type is intended to be used in site context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with one or more sites as scope. <br>If `false`, steps of this type can't be used for flows with one or more sites as scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                     |
| @supports-organization-context | Optional             | Determines if the step type is intended to be used in organization context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with organization scope. <br>If `false`, steps of this type can't be used for flows with organization scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                             |
| description                    | Optional             | The description of the step type. Not shown in Business Manager. Must not exceed 4000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| module                         | ❗Required❗         | Path to the script module to be executed. Must not contain leading or trailing white space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| before-step-function           | Optional             | References the function of the chunk-oriented script module to be executed before the step begins. <br>If not defined, no before-step logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| total-count-function           | Optional             | References the function to be executed to determine the total number of items. <br>If not defined, no total count is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| before-chunk-function          | Optional             | References the function of the chunk-oriented script module to be executed before a chunk begins. <br>If not defined, no before-chunk logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| read-function                  | Optional             | Read function of the chunk script. <br>If not defined, script must export a function named `read`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| process-function               | Optional             | Process function of the chunk script.<br>If not defined, script must export a function named `process`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| write-function                 | Optional             | References the write function of the chunk script. <br>If not defined, script must export a function named `write`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| after-chunk-function           | Optional             | References the function of the chunk-oriented script module to be executed after a chunk has finished. <br>If not defined, no after-chunk logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| after-step-function            | Optional             | References the function of the chunk-oriented script module to be executed after the step has finished. <br>If not defined, no after-step logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| chunk-size                     | ❗Required❗         | Defines the size of one chunk. Must be a numeric value greater than zero. Must not contain leading or trailing white space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| transactional                  | Optional             | Indicates if the module requires a database transaction. <br>Must have value `true` or `false`. Default is `false`. <br>If this value is set to `true`, the job step executes as a single, potentially very large, transaction. <br>To avoid a negative impact on system performance and allow more granular transaction control, keep the default setting of `false`. Implement transaction handling within the job step using the `dw.system.Transaction` API.                                                                                                                                                                                                             |
| parameters                     | Optional             | Parameters for the step, which the user configures in Business Manager. Contains one `parameter` array-element with one or more `parameter` objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| status-codes                   | Optional             | Defines the meta data for status codes returned for the step. Contains one `status` array-element with one or more `status` objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### pipeline-step

```json
{
  "@type-id": "custom.MyCustomPipelineStepType",
  "@supports-parallel-execution": "false",
  "@supports-site-context": "false",
  "@supports-organization-context": "true",
  "description": "This is a custom pipeline step type",
  "pipeline": "MyProcessPipeline-MyStartNode",
  "parameters": {
    "parameter": []
  },
  "status-codes": {
    "status": []
  }
}
```

| Attribute                      | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @type-id                       | ❗Required❗         | Identifies the step type. <br> This is the name that users see in Business Manager, so make it descriptive. Must begin with `custom.`. <br>Must not contain leading or trailing white space or more than 100 characters. <br>Must be unique within the job definition. You can't register multiple steps with the same `@type-id` in different cartridges.<br> The `@type-id` is validated as unique by parsing the `steptypes` files from all cartridges on the cartridge path. If there is a step with the same `@type-id`, the step isn't loaded. <br>The `@type-id` value can't be the same as any system step, for example, `ExecutePipeline` or `IncludeStepsFromJob`. |
| @supports-parallel-execution   | Optional             | Determines if the step type can be used in parallel with itself or other step types. <br>Must have value `true` or `false`. Default is `true`. <br>If `false`, split flows that contain steps of this type are always executed sequentially and never in parallel. <br>If `true`, split flows that contain steps of this type are executed in parallel, as long as: <br>- The split flows don't contain steps with `supports-parallel-execution = false`. <br>- The split flows aren't configured to be executed sequentially. <br>- There are enough resources available to do parallel execution.                                                                          |
| @supports-site-context         | Optional             | Determines if the step type is intended to be used in site context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with one or more sites as scope. <br>If `false`, steps of this type can't be used for flows with one or more sites as scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                     |
| @supports-organization-context | Optional             | Determines if the step type is intended to be used in organization context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with organization scope. <br>If `false`, steps of this type can't be used for flows with organization scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                             |
| description                    | Optional             | The description of the step type. Must not contain leading or trailing whitespace or more than 256 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| pipeline                       | ❗Required❗         | Pipeline to execute for the step. Format must be `<PipelineName>-<StartNodeName>`. For example: `Search-Show`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| parameters                     | Optional             | Parameters for the step, which the user configures in Business Manager. Contains one `parameter` array-element with one or more `parameter` objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| status-codes                   | Optional             | Defines the meta data for status codes returned for the step. Contains one `status` array-element with one or more `status` objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

#### parameter

```json
{
  "@name": "DoubleParameter",
  "@type": "double",
  "@required": "true",
  "@trim": "true",
  "description": "A required double parameter.",
  "default-value": "10"
}
```

| Attribute     | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @name         | ❗Required❗         | The name of the parameter. <br>Must not contain leading or trailing whitespace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| @type         | ❗Required❗         | Indicates the data type of the parameter value. <br>Must not contain leading or trailing whitespace. Must have a value of `boolean`, `string`, `long`, `double`, `datetime-string`, `date-string`, or `time-string`.                                                                                                                                                                                                                                                                                                                                                                        |
| @required     | Optional             | Describes if the parameter is required or optional. <br>Must have a value `true` or `false`. Default is `true`. If `true`, the parameter is required. If `false`, the parameter is optional.                                                                                                                                                                                                                                                                                                                                                                                                |
| @trim         | Optional             | Specifies whether the leading and trailing whitespace for the parameter value entered in Business Manager is removed before the value is validated. Must not contain leading or trailing whitespace. Must have a value `true` or `false`. <br>Default is `true`.                                                                                                                                                                                                                                                                                                                            |
| @target-type  | Optional             | The type to which the parameter value is converted, either `long` or `date`, after the user enters a value in Business Manager. Can be present only when `@type` is `datetime-string`, `date-string`, or `time-string`. <br>If `@target-type` isn't defined, `date` is the default value.                                                                                                                                                                                                                                                                                                   |
| description   | ❗Required❗         | The description of the parameter. <br>Must not contain leading or trailing whitespace or more than 256 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| default-value | Optional             | Default when no value is entered for the parameter. <br> Must have a valid data type value for the parameter (`boolean`, `string`, `long`, `double`, `datetime-string`, `date-string`, or `time-string`). If the parameter is assigned `enum-values`, the `default-value` must match one of the list of enum values.                                                                                                                                                                                                                                                                        |
| pattern       | Optional             | Only for parameter types: `string`. <br>Regular expression that defines the allowed values for the parameter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| min-length    | Optional             | Only for parameter types: `string`.<br> Minimum length of the string value for the parameter. Must be at least 1 and less than `max-length`. If not defined, there are no restrictions other than the general restriction that parameter values can't exceed 1000 characters.                                                                                                                                                                                                                                                                                                               |
| max-length    | Optional             | Only for parameter types: `string`. <br>Maximum length of a string value for this parameter. A string entered in Business Manager is validated against this restriction. Must be at least 1 and greater than or equal to `min-length`. If not defined, string length isn't restricted other than by the general requirement that parameter values can't exceed 1000 characters.                                                                                                                                                                                                             |
| min-value     | Optional             | Only for parameter types: `long`, `double`, `datetime-string`, `time-string`.<br> Minimum value for the parameter. Must not exceed the `max-value`. The minimum valid value for a long is -9223372036854775808 and for a double is 4.9E-324. If you don't explicitly define a `min-value`, those values are considered the `min-values` for long and double parameters. For datetime-string or time-string parameters, if you don't define a `min-value`, there are no restrictions other than the general restriction that parameter values can't exceed 1000 characters.                  |
| max-value     | Optional             | Only for parameter types: `long`, `double`, `datetime-string`, `time-string`. <br>Maximum numerical value for the parameter. Must be greater than or equal to `min-value`. The maximum valid value for a long is 9223372036854775807 and for a double is 1.7976931348623157E308. If you don't explicitly define a `max-value`, those values are considered the `max-values` for long and double parameters. For datetime-string or time-string parameters, if not defined, there are no restrictions other than the general restriction that parameter values can't exceed 1000 characters. |
| enum-values   | Optional             | Allowed values for the parameter. <br>The value entered by the user in Business Manager is validated against this list. Must not contain leading or trailing white spaces. The object contains a `value` array-object with the allowed values as strings. `"enum-values": { "value": [ "One", "Two", "Three" ] }`                                                                                                                                                                                                                                                                           |

#### status

```json
{
  "@code": "ERROR",
  "description": "Used when the step failed with an error."
}
```

| Attribute   | Required or Optional | Description                                                                                              |
| ----------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
| @code       | ❗Required❗         | The status code, the step type can return.<br> Must not contain leading or trailing white space.         |
| description | Optional             | The description of the status code. <br> Not shown in Business Manager. Must not exceed 4000 characters. |

### Job Scope and Execution

The following table shows the results of possible settings of the `supports-organization-context` and `supports-site-context` elements in the `steptypes.json` file.

| supports-organization-context | supports-site-context | Status                                                                                              |
| ----------------------------- | --------------------- | --------------------------------------------------------------------------------------------------- |
| TRUE                          | TRUE                  | Invalid configuration.                                                                              |
| TRUE                          | FALSE                 | Job is executable only if other steps in the same flow can be executed for the entire organization. |
| FALSE                         | TRUE                  | Job is executable only if other steps in the same flow can be executed for one or more sites.       |
| FALSE                         | FALSE                 | Invalid configuration.                                                                              |

### Example

This example shows a `steptypes.json` file that describes three custom steps: a step type defined using a task-oriented CommonJS module, a step type defined using a legacy pipeline, and a step type defined using a chunk-oriented CommonJS module.

```json
{
  "step-types": {
    "script-module-step": [
      {
        "@type-id": "custom.MyCustomScriptStepType",
        "@supports-parallel-execution": "true",
        "@supports-site-context": "true",
        "@supports-organization-context": "false",
        "description": "My custom script step type",
        "module": "my_cartridge/cartridge/scripts/steps/myModule.ds",
        "function": "myFunctionName",
        "transactional": "false",
        "timeout-in-seconds": "900",
        "parameters": {
          "parameter": [
            {
              "@name": "MyParameter1",
              "@type": "boolean",
              "@required": "true",
              "description": "A required boolean parameter."
            },
            {
              "@name": "MyParameter2",
              "@type": "long",
              "@required": "false",
              "description": "An optional long parameter. The default value is 10 when not defined.",
              "default-value": "10"
            },
            {
              "@name": "MyParameter3",
              "@type": "double",
              "@required": "true",
              "@trim": "true",
              "description": "A required double parameter were the raw value is trimmed, value must be betwenn -10 and +10.",
              "min-value": "-10",
              "max-value": "10"
            },
            {
              "@name": "MyParameter4",
              "@type": "string",
              "@required": "false",
              "description": "An optional string parameter, length must be between 10 and 50",
              "min-length": "10",
              "max-length": "50"
            },
            {
              "@name": "MyParameter5",
              "@type": "string",
              "@required": "true",
              "@trim": "false",
              "description": "A required string parameter, must be one of One, Two or Three.",
              "enum-values": {
                "value": ["One", "Two", "Three"]
              }
            },
            {
              "@name": "MyParameter6",
              "@type": "datetime-string",
              "@required": "false",
              "@target-type": "date",
              "description": "An optional datetime parameter."
            },
            {
              "@name": "MyParameter7",
              "@type": "date-string",
              "@required": "false",
              "@target-type": "date",
              "description": "An optional date parameter."
            },
            {
              "@name": "MyParameter8",
              "@type": "time-string",
              "@required": "false",
              "@target-type": "long",
              "description": "An optional time parameter."
            }
          ]
        },
        "status-codes": {
          "status": [
            {
              "@code": "ERROR",
              "description": "Used when the step failed with an error."
            },
            {
              "@code": "FINISHED",
              "description": "Used when the step finished successfully."
            },
            {
              "@code": "FINISHED_WITH_WARNINGS",
              "description": "Used when the step finished with warnings."
            }
          ]
        }
      }
    ],

    "pipeline-step": [
      {
        "@type-id": "custom.MyCustomPipelineStepType",
        "@supports-parallel-execution": "false",
        "@supports-site-context": "false",
        "@supports-organization-context": "true",
        "pipeline": "MyProcessPipeline-MyStartNode",
        "description": "This is a custom pipeline step type",
        "parameters": {
          "parameter": [
            {
              "@name": "MyParameter1",
              "@type": "boolean",
              "@required": "true",
              "description": "A required boolean parameter."
            }
          ]
        },
        "status-codes": {
          "status": [
            {
              "@code": "ERROR",
              "description": "Used when the step failed with an error."
            }
          ]
        }
      }
    ],

    "chunk-script-module-step": [
      {
        "@type-id": "custom.MyCustomChunkScriptModuleStep",
        "@supports-parallel-execution": "false",
        "@supports-site-context": "true",
        "@supports-organization-context": "false",
        "description": "My custom chunk script step type",
        "module": "my_cartridge/cartridge/scripts/steps/myModule.ds",
        "before-step-function": "beforeStep",
        "total-count-function": "getTotalCount",
        "before-chunk-function": "beforeChunk",
        "read-function": "read",
        "process-function": "process",
        "write-function": "write",
        "after-chunk-function": "afterChunk",
        "after-step-function": "afterStep",
        "chunk-size": 10,
        "transactional": "true",
        "parameters": {
          "parameter": [
            {
              "@name": "MyParameter",
              "@type": "boolean",
              "@required": "false"
            }
          ]
        },
        "status-codes": {
          "status": [
            {
              "@code": "ERROR",
              "description": "Used when the step failed with an error."
            },
            {
              "@code": "OK",
              "description": "Used when the step finished successfully."
            }
          ]
        }
      }
    ]
  }
}
```

---

## Steptypes.xml Definition File

Custom Step Types can be registered in the system with a `steptypes.xml` file. Within this file, you describe the step types of the cartridge, their parameters, and status codes.

The file must be named `steptypes.xml` and placed in a custom cartridge in the **root** folder. Each cartridge supports only **one** `steptypes.xml` file.

```
my_cartridge
├── cartridge
│   ├── controllers
│   ├── scripts
│   ├── (other cartridge folders)
│   └── my_cartridge.properties
└── steptypes.xml
```

The `steptypes.xml` file requires a specific XML syntax. If a `steptypes.xml` file contains errors, the errors are logged and the custom step types aren't registered. The system then loads step types from the `steptypes.xml` files of other cartridges.
A typical error message for an invalid `steptypes.xml` file is:
`Invalid step [Step1]! Type with id [custom.MyCustomStep1] is unknown!`.

**warning:** Each cartridge supports either a `steptypes.xml` or a `steptypes.json` file. Having both files in the same cartridge isn't supported.

**note:** The usage of `steptypes.xml` file should avoided. Use the `steptypes.json` file instead and migrate the `steptypes.xml` to `steptypes.json`.

### Syntax/Construction

#### Root

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<step-types>
  <script-module-step></script-module-step>
  <chunk-script-module-step></chunk-script-module-step>
  <pipeline-step></pipeline-step>
</step-types>
```

| Attribute                | Required or Optional                                                                                  | Description                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| step-types               | ❗Required❗                                                                                          | The root object of the steptypes.json file.           |
| script-module-step       | Basically optional, but required if no `chunk-script-module-step` or `pipeline-step` is defined.      | Defines one or more task-oriented script step types.  |
| chunk-script-module-step | Basically optional, but required if no `script-module-step` or `pipeline-step` is defined.            | Defines one or more chunk-oriented script step types. |
| pipeline-step            | Basically optional, but required if no `script-module-step` or `chunk-script-module-step` is defined. | Defines one or more pipeline-based step types.        |

#### script-module-step

```
<script-module-step
    type-id="custom.MyCustomScriptStepType"
    supports-parallel-execution="true"
    supports-site-context="true"
    supports-organization-context="false">
  <description>My custom script step type</description>
  <module>my_cartridge/cartridge/scripts/steps/myModule.ds</module>
  <function>myFunctionName</function>
  <transactional>false</transactional>
  <timeout-in-seconds>900</timeout-in-seconds>
  <parameters>
    <parameter></parameter>
  </parameters>
  <status-codes>
    <status></status>
  </status-codes>
</script-module-step>
```

| Attribute                      | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @type-id                       | ❗Required❗         | Identifies the step type. <br> This is the name that users see in Business Manager, so make it descriptive. Must begin with `custom.`. <br>Must not contain leading or trailing white space or more than 100 characters. <br>Must be unique within the job definition. You can't register multiple steps with the same `@type-id` in different cartridges.<br> The `@type-id` is validated as unique by parsing the `steptypes` files from all cartridges on the cartridge path. If there is a step with the same `@type-id`, the step isn't loaded. <br>The `@type-id` value can't be the same as any system step, for example, `ExecutePipeline` or `IncludeStepsFromJob`. |
| @supports-parallel-execution   | Optional             | Determines if the step type can be used in parallel with itself or other step types. <br>Must have value `true` or `false`. Default is `true`. <br>If `false`, split flows that contain steps of this type are always executed sequentially and never in parallel. <br>If `true`, split flows that contain steps of this type are executed in parallel, as long as: <br>- The split flows don't contain steps with `supports-parallel-execution = false`. <br>- The split flows aren't configured to be executed sequentially. <br>- There are enough resources available to do parallel execution.                                                                          |
| @supports-site-context         | Optional             | Determines if the step type is intended to be used in site context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with one or more sites as scope. <br>If `false`, steps of this type can't be used for flows with one or more sites as scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                     |
| @supports-organization-context | Optional             | Determines if the step type is intended to be used in organization context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with organization scope. <br>If `false`, steps of this type can't be used for flows with organization scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                             |
| **sub-tags:**                  |                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| description                    | Optional             | The description of the step type. Not shown in Business Manager. Must not exceed 4000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| module                         | ❗Required❗         | Path to the script module to be executed. Must not contain leading or trailing white space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| function                       | ❗Required❗         | The function of the script module to execute. Must not contain leading or trailing white space. If not defined, the script module must export a function named `execute`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| transactional                  | Optional             | Indicates if the module requires a database transaction. Must have value `true` or `false`. Default is `false`. If this value is set to `true`, the job step executes as a single, potentially very large, transaction. To avoid a negative impact on system performance and allow more granular transaction control, keep the default setting of `false`. Implement transaction handling within the job step using the `dw.system.Transaction` API.                                                                                                                                                                                                                         |
| timeout-in-seconds             | Optional             | Sets the timeout in seconds for the script module's function. Must be an integer greater than zero. There is no default timeout, but setting a limit is recommended.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| parameters                     | Optional             | Parameters for the step, which the user configures in Business Manager. Contains one or more `parameter` elements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| status-codes                   | Optional             | Defines the meta data for status codes returned for the step. Contains one or more `status` elements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

#### chunk-script-module-step

```
<chunk-script-module-step
    type-id="custom.MyCustomChunkScriptModuleStep"
    supports-parallel-execution="false"
    supports-site-context="true"
    supports-organization-context="false">
  <description>My custom chunk script step type</description>
  <module>my_cartridge/cartridge/scripts/steps/myModule.ds</module>
  <before-step-function>beforeStep</before-step-function>
  <total-count-function>getTotalCount</total-count-function>
  <before-chunk-function>beforeChunk</before-chunk-function>
  <read-function>read</read-function>
  <process-function>process</process-function>
  <write-function>write</write-function>
  <after-chunk-function>afterChunk</after-chunk-function>
  <after-step-function>afterStep</after-step-function>
  <chunk-size>10</chunk-size>
  <transactional>true</transactional>
  <parameters>
    <parameter></parameter>
  </parameters>
  <status-codes>
    <status></status>
  </status-codes>
</chunk-script-module-step>
```

| Attribute                      | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @type-id                       | ❗Required❗         | Identifies the step type. <br> This is the name that users see in Business Manager, so make it descriptive. Must begin with `custom.`. <br>Must not contain leading or trailing white space or more than 100 characters. <br>Must be unique within the job definition. You can't register multiple steps with the same `@type-id` in different cartridges.<br> The `@type-id` is validated as unique by parsing the `steptypes` files from all cartridges on the cartridge path. If there is a step with the same `@type-id`, the step isn't loaded. <br>The `@type-id` value can't be the same as any system step, for example, `ExecutePipeline` or `IncludeStepsFromJob`. |
| @supports-parallel-execution   | Optional             | Determines if the step type can be used in parallel with itself or other step types. <br>Must have value `true` or `false`. Default is `true`. <br>If `false`, split flows that contain steps of this type are always executed sequentially and never in parallel. <br>If `true`, split flows that contain steps of this type are executed in parallel, as long as: <br>- The split flows don't contain steps with `supports-parallel-execution = false`. <br>- The split flows aren't configured to be executed sequentially. <br>- There are enough resources available to do parallel execution.                                                                          |
| @supports-site-context         | Optional             | Determines if the step type is intended to be used in site context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with one or more sites as scope. <br>If `false`, steps of this type can't be used for flows with one or more sites as scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                     |
| @supports-organization-context | Optional             | Determines if the step type is intended to be used in organization context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with organization scope. <br>If `false`, steps of this type can't be used for flows with organization scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                             |
| **sub-tags:**                  |                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| description                    | Optional             | The description of the step type. Not shown in Business Manager. Must not exceed 4000 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| module                         | ❗Required❗         | Path to the script module to be executed. Must not contain leading or trailing white space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| before-step-function           | Optional             | References the function of the chunk-oriented script module to be executed before the step begins. If not defined, no before-step logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| total-count-function           | Optional             | References the function to be executed to determine the total number of items. If not defined, no total count is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| before-chunk-function          | Optional             | References the function of the chunk-oriented script module to be executed before a chunk begins. If not defined, no before-chunk logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| read-function                  | Optional             | Read function of the chunk script. If not defined, script must export a function named `read`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| process-function               | Optional             | Process function of the chunk script. If not defined, script must export a function named `process`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| write-function                 | Optional             | References the write function of the chunk script. If not defined, script must export a function named `write`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| after-chunk-function           | Optional             | References the function of the chunk-oriented script module to be executed after a chunk has finished. If not defined, no after-chunk logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| after-step-function            | Optional             | References the function of the chunk-oriented script module to be executed after the step has finished. If not defined, no after-step logic is used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| chunk-size                     | ❗Required❗         | Defines the size of one chunk. Must be a numeric value greater than zero. Must not contain leading or trailing white space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| transactional                  | Optional             | Indicates if the module requires a database transaction. Must have value `true` or `false`. Default is `false`. If this value is set to `true`, the job step executes as a single, potentially very large, transaction. To avoid a negative impact on system performance and allow more granular transaction control, keep the default setting of `false`. Implement transaction handling within the job step using the `dw.system.Transaction` API.                                                                                                                                                                                                                         |
| parameters                     | Optional             | Parameters for the step, which the user configures in Business Manager. Contains one or more `parameter` elements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| status-codes                   | Optional             | Defines the meta data for status codes returned for the step. Contains one or more `status` elements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

#### pipeline-step

```
<pipeline-step
    type-id="custom.MyCustomPipelineStepType"
    supports-parallel-execution="false"
    supports-site-context="false"
    supports-organization-context="true">
  <description>This is a custom pipeline step type</description>
  <pipeline>MyProcessPipeline-MyStartNode</pipeline>
  <parameters>
    <parameter></parameter>
  </parameters>
  <status-codes>
    <status></status>
  </status-codes>
</pipeline-step>
```

| Attribute                      | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @type-id                       | ❗Required❗         | Identifies the step type. <br> This is the name that users see in Business Manager, so make it descriptive. Must begin with `custom.`. <br>Must not contain leading or trailing white space or more than 100 characters. <br>Must be unique within the job definition. You can't register multiple steps with the same `@type-id` in different cartridges.<br> The `@type-id` is validated as unique by parsing the `steptypes` files from all cartridges on the cartridge path. If there is a step with the same `@type-id`, the step isn't loaded. <br>The `@type-id` value can't be the same as any system step, for example, `ExecutePipeline` or `IncludeStepsFromJob`. |
| @supports-parallel-execution   | Optional             | Determines if the step type can be used in parallel with itself or other step types. <br>Must have value `true` or `false`. Default is `true`. <br>If `false`, split flows that contain steps of this type are always executed sequentially and never in parallel. <br>If `true`, split flows that contain steps of this type are executed in parallel, as long as: <br>- The split flows don't contain steps with `supports-parallel-execution = false`. <br>- The split flows aren't configured to be executed sequentially. <br>- There are enough resources available to do parallel execution.                                                                          |
| @supports-site-context         | Optional             | Determines if the step type is intended to be used in site context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with one or more sites as scope. <br>If `false`, steps of this type can't be used for flows with one or more sites as scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                     |
| @supports-organization-context | Optional             | Determines if the step type is intended to be used in organization context. <br>Must have value `true` or `false`. Default is `true`. <br>If `true`, steps of this type can be used for flows with organization scope. <br>If `false`, steps of this type can't be used for flows with organization scope. <br>`@supports-organization-context` and `@supports-site-context` can't both have the same true or false setting. If `@supports-site-context` is false, `@supports-organization-context` must be true and vice versa.                                                                                                                                             |
| **sub-tags:**                  |                      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| description                    | Optional             | The description of the step type. Must not contain leading or trailing whitespace or more than 256 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| pipeline                       | ❗Required❗         | Pipeline to execute for the step. Format must be `<PipelineName>-<StartNodeName>`. For example: `Search-Show`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| parameters                     | Optional             | Parameters for the step, which the user configures in Business Manager. Contains one or more `parameter` elements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| status-codes                   | Optional             | Defines the meta data for status codes returned for the step. Contains one or more `status` elements.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

#### parameter

```
<parameter
    name="DoubleParameter"
    type="double"
    required="true"
    trim="true">
  <description>A required double parameter.</description>
  <default-value>10</default-value>
</parameter>
```

| Attribute     | Required or Optional | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name          | Required             | The name of the parameter. Must not contain leading or trailing whitespace.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| type          | Required             | Indicates the data type of the parameter value. <br>Must not contain leading or trailing whitespace. Must have a value of `boolean`, `string`, `long`, `double`, `datetime-string`, `date-string`, or `time-string`.                                                                                                                                                                                                                                                                                                                                                                                    |
| required      | Optional             | Describes if the parameter is required or optional. <br>Must have a value `true` or `false`. Default is `true`. If `true`, the parameter is required. If `false`, the parameter is optional.                                                                                                                                                                                                                                                                                                                                                                                                            |
| trim          | Optional             | Specifies whether leading and trailing whitespace for the parameter value entered in Business Manager is removed before the value is validated. <br>Must not contain leading or trailing whitespace. Must have value `true` or `false`. <br>Default is `true`.                                                                                                                                                                                                                                                                                                                                          |
| target-type   | Optional             | The type to which the parameter value is converted, either `long` or `date`, after the user enters a value in Business Manager. Can be present only when `type` is `datetime-string`, `date-string`, or `time-string`. If `target-type` isn't defined, `date` is the default value.                                                                                                                                                                                                                                                                                                                     |
| description   | Required             | The description of the parameter. Must not contain leading or trailing whitespace or more than 256 characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| default-value | Optional             | Default when no value is entered for the parameter. <br>Must have a valid data type value for the parameter (boolean, string, long, double, datetime-string, date-string, or time-string). If the parameter is assigned `enum-values`, the `default-value` must match one of the list of enum values.                                                                                                                                                                                                                                                                                                   |
| pattern       | Optional             | Only for parameter types: `string`. <br>Regular expression that defines the allowed values for the parameter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| min-length    | Optional             | Only for parameter types: `string`. <br>Minimum length of the string value for the parameter. Must be at least 1 and less than `max-length`. If not defined, there are no restrictions other than the general restriction that parameter values can't exceed 1000 characters.                                                                                                                                                                                                                                                                                                                           |
| max-length    | Optional             | Only for parameter types: `string`. <br>Maximum length of a string value for this parameter. String entered in Business Manager is validated against this restriction. Must be at least 1 and greater than or equal to `min-length`. If not defined, string length isn't restricted other than by the general requirement that parameter values can't exceed 1000 characters.                                                                                                                                                                                                                           |
| min-value     | Optional             | Only for parameter types: `long`, `double`, `datetime-string`, `time-string`. <br>Minimum value for the parameter. Must not exceed the `max-value`. <br>The minimum valid value for a long is -9223372036854775808 and for a double is 4.9E-324. <br>If you don't explicitly define a `min-value`, those values are considered the `min-values` for long and double parameters. <br>For datetime-string or time-string parameters, if you don't define a `min-value`, there are no restrictions other than the general restriction that parameter values can't exceed 1000 characters.                  |
| max-value     | Optional             | Only for parameter types: `long`, `double`, `datetime-string`, `time-string`. <br>Maximum numerical value for the parameter. Must be greater than or equal to `min-value`. <br>The maximum valid value for a long is 9223372036854775807 and for a double is 1.7976931348623157E308. <br>If you don't explicitly define a `max-value`, those values are considered the `max-values` for long and double parameters. <br>For datetime-string or time-string parameters, if not defined, there are no restrictions other than the general restriction that parameter values can't exceed 1000 characters. |
| enum-values   | Optional             | Allowed values for the parameter. <br>The value entered by the user in Business Manager is validated against this list. Must not contain leading or trailing white spaces. The object contains one or more `value` elements representing the allowed values. <br> <code>\<enum-values> <br> &nbsp;\<value>One\</value> <br> &nbsp;\<value>Two\</value><br> &nbsp;\<value>Three\</value><br> \</enum-values></code>                                                                                                                                                                                      |

#### status

```xml
<status code="ERROR">
  <description>Used when the step failed with an error.</description>
</status>
```

| Attribute     | Required or Optional | Description                                                                                            |
| ------------- | -------------------- | ------------------------------------------------------------------------------------------------------ |
| code          | ❗Required❗         | The status code, the step type can return. <br> Must not contain leading or trailing white space.      |
| **sub-tags:** |                      |                                                                                                        |
| description   | Optional             | The description of the status code.<br>Not shown in Business Manager. Must not exceed 4000 characters. |

### Job Scope and Execution

The following table shows the results of possible settings of the `supports-organization-context` and `supports-site-context` attributes in the `steptypes.xml` file.

| supports-organization-context | supports-site-context | Status                                                                                              |
| ----------------------------- | --------------------- | --------------------------------------------------------------------------------------------------- |
| TRUE                          | TRUE                  | Invalid configuration.                                                                              |
| TRUE                          | FALSE                 | Job is executable only if other steps in the same flow can be executed for the entire organization. |
| FALSE                         | TRUE                  | Job is executable only if other steps in the same flow can be executed for one or more sites.       |
| FALSE                         | FALSE                 | Invalid configuration.                                                                              |

### Example

This example shows a `steptypes.xml` file that describes three custom steps: a step type defined using a task-oriented CommonJS module, a step type defined using a legacy pipeline, and a step type defined using a chunk-oriented CommonJS module.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<step-types>
  <script-module-step type-id="custom.DownloadFromFTP">
    <description>Downloads files from a FTP server</description>
    <module>my_cartridge/cartridge/scripts/steps/FTPTransfer.ds</module>
    <function>download</function>
    <transactional>false</transactional>
    <parameters>
      <parameter name="DeleteFile" type="boolean" required="false" trim="false">
        <default-value>false</default-value>
      </parameter>
      <parameter name="FileNamePattern" type="string" required="true" trim="false"/>
      <parameter name="HostURL" type="string" required="true" trim="false"/>
      <parameter name="SourceFolder" type="string" required="true" trim="false"/>
      <parameter name="TargetFolder" type="string" required="true" trim="false"/>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when an error occurred during FTP download.</description>
      </status>
      <status code="NO_FILE_FOUND">
        <description>Used when no file could be found on the FTP.</description>
      </status>
      <status code="OK">
        <description>Used when FTP download was successful.</description>
      </status>
    </status-codes>
  </script-module-step>
  <pipeline-step type-id="custom.MyCustomImport">
    <pipeline>Import-Start</pipeline>
    <parameters>
      <parameter name="FileNamePattern" type="string" required="true" trim="false"/>
      <parameter name="ImportMode" type="string" required="true" trim="false">
        <enum-values>
          <value>DELETE</value>
          <value>MERGE</value>
          <value>REPLACE</value>
          <value>UPDATE</value>
        </enum-values>
      </parameter>
      <parameter name="ObjectType" type="string" required="true" trim="false">
        <enum-values>
          <value>catalog</value>
          <value>inventory</value>
          <value>pricebook</value>
          <value>promotion</value>
        </enum-values>
      </parameter>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when the import failed.</description>
      </status>
      <status code="NO_FILE_FOUND">
        <description>Used when no file to import was found.</description>
      </status>
      <status code="OK">
        <description>Used when the import was successful.</description>
      </status>
    </status-codes>
  </pipeline-step>
  <chunk-script-module-step type-id="custom.MyCustomChunkScriptModuleStep">
    <description>My custom chunk script step type/description>
    <module>my_cartridge/cartridge/scripts/steps/myModule.ds</module>
    <before-step-function>beforeStep</before-step-function>
    <total-count-function>beforeChunk</total-count-function>
    <before-chunk-function>beforeChunk</before-chunk-function>
    <read-function>read</read-function>
    <process-function>process</process-function>
    <write-function>write</write-function>
    <after-chunk-function>afterChunk</after-chunk-function>
    <after-step-function>afterStep</after-step-function>
    <chunk-size>10</chunk-size>
    <transactional>true</transactional>
    <parameters>
      <parameter name="MyParameter" type="boolean" required="false" trim="false"/>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when an error occurred.</description>
      </status>
      <status code="OK">
        <description>Used when no error occured.</description>
      </status>
    </status-codes>
  </chunk-script-module-step>
</step-types>
```

<!-- document id=a55d17d1522ba283d0067b965bb3801bbad20f479daa1764f7725314fe21f697 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/create-distribution-certificate.md -->

# Create Distribution Certificate and Resign Development IPA

## Overview

This guide outlines the steps to create the enterprise distribution profile and certificate and re-sign the IPA that was created for a different method of distribution (development/ad-hoc). It also lists the manual steps to resign the IPA using the enterprise certificate and provisioning profile, and to change the bundle ID of the app.

If you have your enterprise account but don't want to share the Distribution Certificate and Provisioning Profile with the Point of Sale team, you can request a PS dev IPA and re-sign it with your Distribution certificate and profile before distributing the Point of Sale app via your MDM.

## Steps to Create Distribution Certificate and Profile

1. Create the app ID in the Apple Developer Enterprise account. For example, `com.appName.prod.ios`.
2. Create an In-House Production Certificate and share the certificate and private key. This can also be an existing certificate used for other apps. Export the distribution certificate, which is required to resign the IPA
3. Create an In-House Provisioning Profile for the newly created app ID signed with the Production certificate. Export the Provisioning profile, which is required to resign the IPA
4. To enable notifications, create an Apple Push Notification service SSL (Sandbox & Production) certificate and export the .p12 file along with the password used to sign. Provide it to the Point of Sale team for upload to AWS.

## IPA Resigning Process

Each Enterprise Account has a uniquely registered bundle ID for the app, provisioning profile for enterprise distribution along with the certificate. Use these steps in terminal to resign a development IPA to enterprise IPA by signing with the new distribution certificate and profile.

1. Navigate to the IPA and unzip the file.

`unzip AppName.ipa`

**note:** If asked to replace `Payload/PSStore.app/\*`, provide `None` as the response to skip this step.

2. Remove the existing code signing.

`rm -rf Payload/AppName.app/_CodeSignature/`

3. Navigate to the PlistBuddy directory and update the bundle ID.

`/usr/libexec/PlistBuddy Payload/AppName.app/Info.plist`

**note:** PlistBuddy is a tool provided by Apple to perform operations on a plist file using bash commands. You can add, edit, and delete any values in a plist file using PlistBuddy.

From PlistBuddy, enter these commands.

```
Set :CFBundleIdentifier com.appname.beta.ios
save
quit
```

4. Switch the profile.

```
cp ~/Downloads/inHouseProfileName.mobileprovision
Payload/AppName.app/embedded.mobileprovision
```

5. Sign the app with the new distribution certificate.

`codesign -f -s "Apple Distribution Certificate Name" Payload/AppName.app`

6\. Rezip the IPA after resigning.

`zip -qr AppName-resigned.ipa Payload/`

<!-- document id=97e92a82f67ee6edcb9e0f523ab0b511934bc5552b16b9a1ca1bec662b3a9c3e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_create_ods_scheduler.md -->

# Create ODS Operation Schedulers

Use the Operation Scheduler to define your ODS availability. Use a combination of realm-level schedulers for any instance in a realm, and individual schedulers for specific instances. Create a start scheduler, a stop scheduler, or both.

To create and activate an ODS operation scheduler, log into Account Manager, and confirm that you have the `Sandbox_API_User` role with a tenant filter in the format `<realm_id>_sbx`. For example, the tenant filter for realm abcd is `abcd_sbx`.

1. In Control Center, select the realm you want to modify. Available realms are on the Realms page.
2. Under **On-Demand Sandboxes**, take one of these actions:
   - To create a realm-level scheduler, remain on the Realm page.
   - To create an individual instance scheduler, select a sandbox entry, and on the instance's page, select **Scheduler**.
   - The remaining steps apply to both types of ODS schedulers.
3. Click **Create Operation Scheduler**, and complete the fields.
   - In the **Type of Scheduler** dropdown menu, select whether to create a **Start Scheduler** or **Stop Scheduler**.
   - Select the days that the schedule applies.
   - Set the schedule start or stop time.
   - Click **Create**, and confirm the creation.
4. (Realm-level schedulers only) set the Schedule toggle on. An individual scheduler is turned on or off based on the defined schedule.
   **note:** If you set a start and stop schedule for the same day and time, the time difference must be greater than 10 minutes.

Edit or delete any ODS schedule.

<!-- document id=be68133372228c29965bdceb31741110e3345db4d33a7eb9a87c0c46d6643695 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_create_ods_instance.md -->

# Create On-Demand Sandboxes for B2C Commerce

To develop and test B2C Commerce instances, use on-demand sandboxes (ODS).

**note:** To create an on-demand sandbox, log in to Account Manager, and make sure you have the role `Sandbox_API_User` with a tenant filter in the format `<realm_id>_sbx`. For example, in the realm `abcd`, you see the Sandbox_API_User role with tenant filter `abcd_sbx`.

1. Log in to Control Center.
2. Select the realm where you want to add the ODS.
3. Click **Create on-demand sandbox**.
4. Complete the ODS Provisioning Request form.
   - Set the number of hours for the sandbox.
     - 0 (infinite time)
     - 24
     - 48
   - (Optional) To activate automatic start and stop actions, set **Auto Schedule** to true. Set the automatic actions to a dedicated time via the realm configuration API.
   - Set the resource allocation for the sandbox.
     - Medium (default)
     - Large
     - X-Large
     - XX-Large
       **note:** Setting the allocation to a large value consumes more credits.
   - Click **Create sandbox**. As the sandbox builds, the Control Center instance page shows the status as the sandbox builds (new, creating, starting, and system up and running).

<!-- document id=e0cebbe92beca7a9e23d649831f1ab92bd9d2d82c8ecf7ef1d282d9a81829cb6 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-client-side-create-async.md -->

# Create Saved Payment Method Asynchronously

Use the asynchronous flow when payment gateways generate tokens asynchronously. You create the SPM record with a Pending status, and the token is updated later via a webhook notification.

Here’s the high-level workflow for creating a saved payment method record asynchronously.

![High-level workflow diagram for creating a saved payment method record asynchronously using a third-party payment gateway](https://developer.salesforce.com/media/d2c-commerce/async_spm_creation.png '{"class": "image-lg", "title": "Asynchronously Saved Payment Method Creation"}')

Here are the steps to create a saved payment method asynchronously using the tokenized payment details received from a third-party payment gateway:

1. The client builds the asynchronous gateway adapater. See [Building a Asynchronous Gateway Adapter](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_async_adapter_concept.htm).
2. The client configures a webhook endpoint to receive notifications from the payment gateway. This webhook endpoint is mapped to Salesforce Notify API through an Apex adapter to receive notifications from payment gateway about payment events.
3. The client calls the payment gateway with the payment details entered through the buyer component.
4. The gateway returns a reference number that’s later used to correlate the asynchronous update.
5. The client-side component creates the saved payment method record using the SavedPaymentMethod sObject API. It sets all required fields, including:

   - `status` = `Pending`
   - `gatewayToken` = empty
   - `asyncGatewayRefNumber` (mandatory for async flows)

   **Sample JSON request**

   ```json
   {
     "merchantAccountId": "8zbSM0000000F8jYAE",
     "referenceOwnerId": "001SM00000FwMhEYAV",
     "paymentGatewayId": "0b0SM0000002oLhYAI",
     "Status": "Pending",
     "usageType": "OFFSESSION",
     "Name": "AmazonPay...001",
     "GatewayReference": "cus_TEGn3J3WI5onpb",
     "type": "extd_wallet",
     "Checksum": "UNIQUE_GATEWAY_HASH_Wallet_10001",
     "ExtendedPaymentMethodType": "amazon_pay",
     "last4": "1234"
   }
   ```

   **Sample JSON response**

   ```json
   {
     "id": "12qSM000000qfS6YAI",
     "success": true,
     "errors": []
   }
   ```

6. When the token is generated, the gateway sends a webhook to the configured endpoint with the same `AsyncGatewayRefNumber`. Upon receiving this notification, the SPM record status is updated to Active, and the gateway token is stored in the SavedPaymentMethod object.

**Salesforce Commerce Payments Notify API for Stripe**

Resource: `/commerce/payments/notify/stripe`

Here’s a sample Stripe notify response:

```json
{
  "id": "evt_1LgJRtSGZlJjI7oJelLGgSCg",
  "object": "event",
  "api_version": "2020-03-02",
  "created": 1662776977,
  "data": {
    "object": {
      "id": "acct_1M6wYxIDXrazRzyT",
      "object": "account",
      "business_profile": {
        "mcc": "5691",
        "name": null,
        "support_address": null,
        "support_email": null,
        "support_phone": "+917331163878",
        "support_url": null,
        "url": "https://www.salesforce.com"
      },
      "capabilities": {
        "card_payments": "inactive",
        "transfers": "active"
      },
      "charges_enabled": true,
      "controller": {
        "type": "application"
      },
      "country": "IN",
      "default_currency": "inr",
      "details_submitted": true,
      "email": "harish.lnmiit@gmail.com",
      "payouts_enabled": true,
      "settings": {
        "bacs_debit_payments": {},
        "branding": {
          "icon": null,
          "logo": null,
          "primary_color": null,
          "secondary_color": null
        },
        "card_issuing": {
          "tos_acceptance": {
            "date": null,
            "ip": null
          }
        },
        "card_payments": {
          "statement_descriptor_prefix": "KIAA",
          "statement_descriptor_prefix_kanji": null,
          "statement_descriptor_prefix_kana": null
        },
        "dashboard": {
          "display_name": "INAccount1",
          "timezone": "Etc/UTC"
        },
        "payments": {
          "statement_descriptor": "KIAAN",
          "statement_descriptor_kana": null,
          "statement_descriptor_kanji": null
        },
        "sepa_debit_payments": {}
      },
      "type": "standard"
    },
    "previous_attributes": {}
  },
  "livemode": true,
  "pending_webhooks": 1,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "account.updated"
}
```

Here’s a sample Adyen async response:

```json
{
  "live": "false",
  "notificationItems": [
    {
      "NotificationRequestItem": {
        "eventCode": "RECURRING_CONTRACT",
        "success": "true",
        "merchantReference": "KLARNA_TOKENIZE_TEST_EUR",
        "pspReference": "Q26N98PBKQ7F42W5",
        "paymentMethod": "klarna",
        "merchantAccountCode": "Amazon879ECOM",
        "originalReference": "KB44M8CFZRRPDKV5",
        "amount": {
          "currency": "EUR",
          "value": 100
        },
        "additionalData": {
          "recurring.shopperReference": "UNIQUE_SHOPPER_ID_12345",
          "recurring.recurringDetailReference": "Q26N98PBKQ7F42W5"
        }
      }
    }
  ]
}
```

Here’s a sample user interface that shows the status of a Saved Payment Method record before and after the webhook endpoint notification is sent.

Before webhook:

![Saved Payment Method record showing Pending status before the webhook notification is received from the payment gateway](https://developer.salesforce.com/media/d2c-commerce/spm_before_webhook.png '{"class": "image-lg", "title": "Saved Payment Method Status Before Webhook"}')

After webhook:

![Saved Payment Method record showing Active status and stored gateway token after the webhook notification is received](https://developer.salesforce.com/media/d2c-commerce/spm_after_webhook.png '{"class": "image-lg", "title": "Saved Payment Method Status After Webhook"}')

**See Also**

- [_Object Reference for the Salesforce Platform_: SavedPaymentMethod](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_savedpaymentmethod.htm)
- [_REST API Developer Guide_: Create a Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm)
- [_Apex Developer Guide_: Set Up a Asynchronous Payment Gateway Adapter](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_async_adapter_setup.htm)
- [_Apex Developer Guide_: Builder Examples for Payment Gateway Adapters](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_builder_examples.htm)

<!-- document id=0cfd5de8d6859d27931c0350cd22b92f83c5e567c3bdf2bf924b2d3d240436b0 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-client-side-create-sync.md -->

# Create Saved Payment Method Synchronously

In the synchronous flow, the gateway returns the token directly to the client. The client then immediately calls the SavedPaymentMethod sObject API to create the record with the received token and metadata.

Here’s the high-level workflow for creating a saved payment method record synchronously.

![High-level workflow diagram for creating a saved payment method record synchronously using a third-party payment gateway](https://developer.salesforce.com/media/d2c-commerce/sync_spm_creation.png '{"class": "image-lg", "title": "Synchronously Saved Payment Method Creation"}')

Here are the steps to create a saved payment method synchronously using the tokenized payment details received from a third-party payment gateway:

1. The client builds the synchronous gateway adapater. See [Building a Synchronous Gateway Adapter](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_sync_adapter_concept.htm).
2. The client calls the payment gateway with the payment details entered through the buyer component.
3. The gateway tokenizes the payment and returns the gateway token directly to the buyer component.
4. The client calls the SavedPaymentMethod sObject API to create the saved payment method record with the token and additional metadata details received from the gateway.

   **Sample JSON request**

   ```json
   {
     "merchantAccountId": "8zbSM0000000F8jYAE",
     "referenceOwnerId": "001SM00000FwMhEYAV",
     "paymentGatewayId": "0b0SM0000002oLhYAI",
     "Status": "Active",
     "usageType": "OFFSESSION",
     "Name": "AmazonPay...001",
     "GatewayReference": "cus_TEGn3J3WI5onpb",
     "type": "extd_wallet",
     "Checksum": "UNIQUE_GATEWAY_HASH_Wallet_10001",
     "ExtendedPaymentMethodType": "amazon_pay",
     "last4": "1234"
   }
   ```

   **Sample JSON response**

   ```json
   {
     "id": "12qSM000000qfS6YAI",
     "success": true,
     "errors": []
   }
   ```

**See Also**

- [_Object Reference for the Salesforce Platform_: SavedPaymentMethod](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_savedpaymentmethod.htm)
- [_REST API Developer Guide_: Create a Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm)
- [_Apex Developer Guide_: Set Up a Synchronous Payment Gateway Adapter](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_sync_adapter_setup.htm)
- [_Apex Developer Guide_: Builder Examples for Payment Gateway Adapters](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_builder_examples.htm)

<!-- document id=b8f8a1a16bc19d2a704e2ad7366e5473962c7d561712d54ae67c43ed0104f2dd url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-quick-start-create-bm-github.md -->

# Create Storefront Next in Business Manager with a GitHub Repository

Create a storefront and its dependent API and Managed Runtime (MRT) resources in Business Manager by connecting to GitHub. Storefront setup creates a GitHub repository to store the generated storefront code.

## Prerequisites

- A developer B2C Commerce instance or on-demand sandbox (ODS) instance. See [Create On-Demand Sandboxes for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_cc_create_ods_instance.htm&type=5) in _Salesforce Help_.
- Managed Runtime User or Managed Runtime Admin role in Account Manager.
- Business Administrator role in Account Manager or a role for the Business Manager Module and Organization context with read-write access to storefronts. See [Create a Role in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_roles.htm&type=5) in _Salesforce Help_.
- A GitHub account with the owner role in the GitHub organization. See the GitHub documentation for organization roles in [Permissions of predefined roles](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles#permissions-of-predefined-roles), and [Permission levels for a personal account repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/permission-levels-for-a-personal-account-repository) for personal accounts.
- A B2C Commerce site associated with a catalog, price book, and an inventory. See [Create and Manage Sites for Development](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-managing-sites-for-dev.html) and [Merchandising Your Site in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_merchandising_your_site.htm&type=5) in _Salesforce Help_.

## Constraints

- Storefront setup supports only one storefront per site. A site can't be associated with more than one storefront.
- If storefront setup fails, you must delete and recreate the storefront.

## Steps

1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Administration > Sites > Storefronts > New Storefront**.
2.  Select the template that's suitable for your storefront's merchandise. The built-in templates provide the layout, theme, and style that are customized for the products to sell, and product attributes specific to an industry. To check the layout of a template on a demo site, click **View Demo**. To select a template to build your storefront with, click **Use Template**. To learn more about the various templates, see [Storefront Next Template Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-template-compare.md).

    ![Select a template suitable for your merchandise](https://developer.salesforce.com/docs/media/sfnext/sfnext-select-template2.png '{"class": "image-lg"}')

3.  Enter the storefront name. For example, `my-storefront`.
4.  Select a site. You can select one or more sites for your storefront. For this task, select one site.

    **important:** You can assign a site to one storefront only. You can't reuse it for another storefront.

5.  Select **GitHub** to create a storefront in your GitHub repository and store the generated storefront code.

6.  Click **Add GitHub Account**, and then from the B2C Commerce GitHub integration, select a GitHub account to use for the repository.

    **important:** Make sure that your GitHub account has the owner role for the GitHub organization. See [Prerequisites](#prerequisites).

7.  Choose where you want to create the repository. Select a GitHub organization to share the repository with your team, or select a personal account for your own use. Make sure that you have owner access to the GitHub organization that you select.
8.  Grant the GitHub integration app access to all your repositories or specific repositories that you select from the list.
9.  If you haven't installed the integration app earlier, click **Install**. If you installed the integration app earlier, click **Save**.
10. Authenticate your GitHub account.
    After you authenticate your GitHub account, you return to the storefront setup page.
11. Enter a name for the GitHub repository that setup creates.

    ![Storefront setup page in Business Manager with a GitHub organization](https://developer.salesforce.com/docs/media/sfnext/sfnext-qs-new-sf-filled3.png '{"class": "image-lg"}')

12. To make the repository public, turn off the toggle next to the repository name. The new repository is private by default.
13. Click **Start Setup**.
14. After setup completes, in the Source Code section, click **Download .env** to download the `env.txt` environment file. It contains your storefront's configuration, Business Manager settings, and your Account Manager and Shopper Login and API Access Service (SLAS) credentials.

    ![The Storefront Next setup completion page points to development resources](https://developer.salesforce.com/docs/media/sfnext/sfnext-qs-completed-resources4.png '{"class": "image-xl"}')

    **note:** For your security, the client secrets are available for download only once and are deleted on subsequent downloads. You use the Account Manager and SLAS client credentials to run the storefront locally. When you run the storefront on MRT, MRT uses the autocreated environment variables.

15. To view the storefront on MRT, click the view icon next to the environment.
    ![View the storefront on MRT](https://developer.salesforce.com/docs/media/sfnext/sfnext-qs-view3.png '{"class": "image-lg"}')

    The new environment links to deployments and environment variables on MRT, and shows the eCDN routing rules for the default domain.
    Setup created an MRT project and sent an initial deployment of the storefront.

16. To view the deployment on MRT, from the storefront page in Business Manager, click **Manage** in the Deployments section. Take note of the MRT project name and environment name because you use them later.
    ![Initial storefront deployment in Managed Runtime](https://developer.salesforce.com/docs/media/sfnext/sf-initial-deploy2.png '{"class": "image-lg"}')
17. To check out the GitHub repository that contains the generated storefront code, on your storefront page, click **GitHub Repository**.
18. To customize the storefront locally, clone the GitHub repository to your local system, configure it, and build it.

    a. To run the storefront locally, create an `.env` file from the downloaded file.

    **note:** These environment variable configuration steps in the `.env` file are required only for running your storefront on your local system. The deployed storefront on Managed Runtime doesn't need the local environment settings. It uses the environment variables in Managed Runtime instead, which the storefront setup process created for you in [Runtime Admin](https://runtime.commercecloud.com/login).

    b. Open the storefront project folder in an IDE. In your project root directory, create a file with the name `.env`.

    c. Replace the contents of `{project-folder}/.env` with the contents of the downloaded `env.txt` file, which contains values specific to the new storefront and the B2C Commerce instance.

    **note:** The MRT project has a name and an ID, which are different. The environment file contains the MRT project ID.

    d. Make sure that your site's search indexes are up-to-date. For more information, see [Generate Search Indexes](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_search_indexes.htm&type=5) in _Salesforce Help_.

    e. In a terminal window, go to the storefront folder.

    ```
    cd {project-folder}
    ```

    f. Install Storefront Next project dependencies that are specified in `package.json`.

    ```
    pnpm install
    ```

    g. Build the storefront.

    ```
    pnpm run build
    ```

    h. Run the development server locally.

    ```
    pnpm run dev
    ```

    i. Open the development server URL shown in the output to view the storefront in the browser. For example, the URL with the default port is `http://localhost:5173`.

## Next Steps

- To deploy your storefront to MRT after making changes to it after the initial deployment, see [Deploy Storefront Next to Managed Runtime (MRT)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md).
- To change site assignments for the storefront, see [Manage Sites for Storefront Next in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-manage-sites.md).
- If you set up this storefront on an on-demand sandbox (ODS) instance, Business Manager automatically adds default security rules to the instance's default eCDN zone. These rules apply to every storefront hosted on that instance. See [Default Security Rules on On-Demand Sandbox (ODS) Instances](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ods-security-rules.md).

<!-- document id=3f03570b4acc9c37b36bd2fa1f24b68a97f8a30941081ce588f46919d7b2d632 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-quick-start-create-bm.md -->

# Create Storefront Next in Business Manager with Local Code

Create a storefront and its dependent API and Managed Runtime (MRT) resources in Business Manager with the local CLI option to generate and store your code locally.

## Prerequisites

- A developer B2C Commerce instance or on-demand sandbox (ODS) instance. See [Create On-Demand Sandboxes for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_cc_create_ods_instance.htm&type=5) in _Salesforce Help_.
- Managed Runtime User or Managed Runtime Admin role in Account Manager.
- Business Administrator role in Account Manager or a role for the Business Manager Module and Organization context with read-write access to storefronts. See [Create a Role in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_roles.htm&type=5) in _Salesforce Help_.
- The prerequisites for creating storefront code with the CLI. See the prerequisites in [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-sf.md).
- A B2C Commerce site associated with a catalog, price book, and an inventory. See [Create and Manage Sites for Development](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-managing-sites-for-dev.html) and [Merchandising Your Site in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_merchandising_your_site.htm&type=5) in _Salesforce Help_.

## Constraints

- Storefront setup supports only one storefront per site. A site can't be associated with more than one storefront.
- If storefront setup fails, you must delete and recreate the storefront.

## Steps

1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Administration > Sites > Storefronts > New Storefront**.
2.  Select the template that's suitable for your storefront's merchandise. The built-in templates provide the layout, theme, and style that are customized for the products to sell, and product attributes specific to an industry. To check the layout of a template on a demo site, click **View Demo**. To select a template to build your storefront with, click **Use Template**. To learn more about the various templates, see [Storefront Next Template Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-template-compare.md).

    ![Select a template suitable for your merchandise](https://developer.salesforce.com/docs/media/sfnext/sfnext-select-template2.png '{"class": "image-lg"}')

3.  Enter the storefront name. For example, `my-local-storefront`.
4.  Select a site. You can select one or more sites for your storefront. For this task, select one site.

    **important:** You can assign a site to one storefront only. You can't reuse it for another storefront.

5.  Select **Salesforce CLI** to generate the storefront code manually.

    ![Storefront setup page in Business Manager with the local CLI](https://developer.salesforce.com/docs/media/sfnext/sfnext-qs-local.png '{"class": "image-lg"}')

6.  Click **Start Setup**.

7.  After setup completes, in Source Code, click **Download .env** from the completion page to download the `env.txt` environment file. It contains your storefront's configuration, Business Manager settings, and your Account Manager and Shopper Login and API Access Service (SLAS) credentials.

    ![The Storefront Next setup completion page points to development resources](https://developer.salesforce.com/docs/media/sfnext/sfnext-cli-setup-github-connect-middle2.png '{"class": "image-lg"}')

    **note:** For your security, the client secrets are available for download only once and are deleted on subsequent downloads. You use the Account Manager and SLAS client credentials to run the storefront locally. When you run the storefront on MRT, MRT uses the autocreated environment variables.

8.  To view the storefront on MRT, click the view icon next to the environment.
    ![View the storefront on MRT](https://developer.salesforce.com/docs/media/sfnext/sfnext-qs-local-detail-env.png '{"class": "image-lg"}')
9.  To view details about the autocreated environment, in the Environments section, click the environment name. The new environment links to deployments, environment variables on MRT, and shows the eCDN routing rules for the default domain.

    Setup created an MRT project and sent an initial deployment of the storefront. The deployed bundle is a generated storefront that mirrors the storefront you generate with the CLI.

10. To view the deployment on MRT, from the storefront page in Business Manager, click **Manage** in the Deployments section. Verify that the setup process created an MRT project and environment and sent an initial deployment of the storefront app. To view the deployment on MRT, click **Managed Runtime Environment**.

    ![Initial storefront deployment in Managed Runtime](https://developer.salesforce.com/docs/media/sfnext/sfnext-qs-local-deploy.png '{"class": "image-lg"}')

11. To generate the storefront code, type this command in a terminal window.

    ```
    pnpm dlx @salesforce/storefront-next-dev create-storefront
    ```

    a. Provide the same storefront name you used earlier. For example, `my-local-storefront`.

    The storefront corresponds to a project in MRT. The autogenerated project ID, which is based on the storefront name, identifies your project in MRT. You set the project ID in a later step from the downloaded environment file.

    b. Select the same Storefront Next UI template you chose earlier.

    c. For the extensions, press Enter to accept the selected extensions.

    d. Accept the defaults for the client IDs and the B2C Commerce instance values.
    You overwrite the configuration with your own storefront environment file in the next steps.

12. Open the project folder in an IDE, and then open the environment file: `{project-folder}/.env`.
13. Replace the contents of `{project-folder}/.env` with the contents of the downloaded `env.txt` file, which contains values specific to the new storefront and the B2C Commerce instance.

    **note:** The MRT project has a name and an ID, which are different. The `env.txt` file contains the MRT project ID.

14. Make sure that your site's search indexes are up-to-date. For more information, see [Generate Search Indexes](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_search_indexes.htm&type=5) in _Salesforce Help_.

15. In a terminal window, go to the storefront folder.

    ```
    cd {project-folder}
    ```

16. Install Storefront Next project dependencies that are specified in `package.json`.

    ```
    pnpm install
    ```

17. Build the storefront.

    ```
    pnpm run build
    ```

18. Run the development server.

    ```
    pnpm run dev
    ```

19. Open the development server URL shown in the output to view the storefront in the browser. For example, the URL with the default port is `http://localhost:5173`.

## Next Steps

- To add or modify Page Designer pages and components, deploy Page Designer metadata. See [Deploy the Storefront Next Cartridge for Page Designer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pd-deploy-cartridge.md). This step isn't required when you set up a storefront by using GitHub.
- To deploy your storefront to MRT after making changes to it after the initial deployment, see [Deploy Storefront Next to Managed Runtime (MRT)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md).
- To change site assignments for the storefront, see [Manage Sites for Storefront Next in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-manage-sites.md).
- If you set up this storefront on an on-demand sandbox (ODS) instance, Business Manager automatically adds default security rules to the instance's default eCDN zone. These rules apply to every storefront hosted on that instance. See [Default Security Rules on On-Demand Sandbox (ODS) Instances](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ods-security-rules.md).
- To link your storefront to a GitHub organization, see [Link Your Storefront to a GitHub Repository in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-github-connect.md).

<!-- document id=e5ba2f0c85ad8f5bd9f9b26283505d21eab33fae603a35475757078426561782 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-create-impex-folder-structure-ds.md -->

# CreateImpExFolderStructure.ds

Review the CreateImpExFolderStructure.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/**
 * Create the ImpEx folder structure.
 *
 * @input TaskDirectoryName 		: String		Task directory name
 * @input SiteID  			: String		Site ID
 * @input sampleLogger  		: Object		Sample logger
 * @input Scope				: String		Scope [import/export]
 * @output DirectoryIncoming 		: dw.io.File	Incoming folder for the file (import tasks)
 * @output DirectoryOutgoing 		: dw.io.File	Outgoing folder for the file (export tasks)
 * @output DirectoryProcessing 	: dw.io.File	Processing folder for the file
 * @output DirectoryArchive 		: dw.io.File	Archive folder for the file
 * @output DirectoryError 		: dw.io.File	Directory folder for the file
 * @output sampleLogger 		: Object		Debug output for Sample logger
 * @output sampleError 			: Object		Error output for Sample logger
 * @output DirectoryOutgoingPath 	: String
 * @output DirectoryIncomingPath 	: String
 * @output DirectoryProcessingPath 	: String
 * @output DirectoryArchivePath 	: String
 * @output DirectoryErrorPath 	: String
 */
importPackage(dw.system);
importPackage(dw.io);
importPackage(dw.util);



// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");



function execute(pdict: PipelineDictionary): Number {



    // Sample Logging var
    var _context: String = new Context("CreateImpExFolderStructure.ds");
    var _logger: Log = Log.getLogger(pdict);

    // check for mandatory pipelet input parameters
    if (empty(pdict.TaskDirectoryName) || empty(pdict.SiteID)) {

        _logger.error(_context, "Mandatory pipelet input parameters are missing or null.");
        return PIPELET_ERROR;
    }

    // get impex scope
    var scope: String = pdict.Scope;

    // get site id
    var siteId: String = pdict.SiteID;

    // site specific impex base path
    var impexBasePath: String = File.IMPEX + File.SEPARATOR + 'src' + File.SEPARATOR + 'datafeeds' + File.SEPARATOR + siteId + File.SEPARATOR;

    var directoryIncomingPath: String = impexBasePath + pdict.TaskDirectoryName + File.SEPARATOR + 'incoming';
    var directoryOutgoingPath: String = impexBasePath + pdict.TaskDirectoryName + File.SEPARATOR + 'outgoing';
    var directoryProcessingPath: String = impexBasePath + pdict.TaskDirectoryName + File.SEPARATOR + 'processing';
    var directoryArchivePath: String = impexBasePath + pdict.TaskDirectoryName + File.SEPARATOR + 'archive';
    var directoryErrorPath: String = impexBasePath + pdict.TaskDirectoryName + File.SEPARATOR + 'error';

    var directoryIncoming: File = new File(directoryIncomingPath);
    var directoryOutgoing: File = new File(directoryOutgoingPath);
    var directoryProcessing: File = new File(directoryProcessingPath);
    var directoryArchive: File = new File(directoryArchivePath);
    var directoryError: File = new File(directoryErrorPath);

    try {

        switch (scope) {

        case Scope.IMPORT:
            directoryIncoming.mkdirs();
            break;
        case Scope.EXPORT:
            directoryOutgoing.mkdirs();
            break;
        default:
            directoryIncoming.mkdirs();
            directoryOutgoing.mkdirs();
            break;
        }
        directoryProcessing.mkdirs();
        directoryArchive.mkdirs();
        directoryError.mkdirs();

        switch (scope) {

        case Scope.IMPORT:
            pdict.DirectoryIncoming = directoryIncoming;
            break;
        case Scope.EXPORT:
            pdict.DirectoryOutgoing = directoryOutgoing;
            break;
        default:
            pdict.DirectoryIncoming = directoryIncoming;
            pdict.DirectoryOutgoing = directoryOutgoing;
            break;
        }
        pdict.DirectoryProcessing = directoryProcessing;
        pdict.DirectoryArchive = directoryArchive;
        pdict.DirectoryError = directoryError;

        switch (scope) {

        case Scope.IMPORT:
            pdict.DirectoryIncomingPath = directoryIncomingPath;
            break;
        case Scope.EXPORT:
            pdict.DirectoryOutgoingPath = directoryOutgoingPath;
            break;
        default:
            pdict.DirectoryIncomingPath = directoryIncomingPath;
            pdict.DirectoryOutgoingPath = directoryOutgoingPath;
            break;
        }
        pdict.DirectoryProcessingPath = directoryProcessingPath;
        pdict.DirectoryArchivePath = directoryArchivePath;
        pdict.DirectoryErrorPath = directoryErrorPath;
    } catch (e) {

        var exception: sampleException = new sampleException(_context, "Error occurred calling create ImpEx folder", e);
        _logger.error(_context, "Error occurred calling  create ImpEx folder: " + exception);
        pdict.sampleError = exception;

        return PIPELET_ERROR;
    }

    return PIPELET_NEXT;
}



// Constant for IMPEX scope
var Scope = {



    IMPORT: 'import',
    EXPORT: 'export'
};
```

<!-- document id=b49edcfe94d8c25f2355ce921e517d1978fa789b050dc75fabba9e5bc32a4d0e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-creating-a-csc-ui-config-manually.md -->

# Creating a CSC UI Configuration Manually

Create a UI configuration by entering it manually. The agent must have the necessary permissions.

1.  Select **Administration** > **Site Development** > **Customer Service Center Settings**.

2.  Select the customizable area.

    - Basket view
    - Basket billing address
    - Basket billing address view
    - Basket shipping address
    - Basket shipping address view
    - Customer address book
    - Customer address create
    - Customer address edit
    - Customer baskets
    - Customer create
      - Add or update form fields to capture additional customer information for the account. For example, birthday, phone number.
    - Customer edit
    - Customer order history
    - Customer search
    - Customer summary
    - Order billing address view
    - Order payment instrument
      - Update to reorder form fields for payment capture
    - Order search
      - Update to display additional fields for order search
    - Order shipping address view
    - Order summary
    - Price adjustment
      - Update reason codes for manual price adjustments
    - Product detail
      - Display product content, such as short or long descriptions and other product attributes
    - Product search - Display additional product content and attributes on product search result sets

      **note:** All customizable address areas must be updated if you want to include country and state/province values in the address form fields on the UI.

3.  Enter or edit the configuration.

4.  Click **Save**.

<!-- document id=72c659105b31cd074034840f9d1bcbcc4e69c418af7b1067fc83240dc460317b url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/custom-apis.md -->

Custom

# Custom

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/custom-apis/custom-apis-oas-v1-public.yaml)

## API Overview

The Custom APIs DX API provides enhanced transparency and manageability of Custom API endpoints within the platform. This API offers a user-friendly and secure approach by providing real-time feedback on endpoint registration status, including successful registrations and failed attempts with error reasons.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.custom-apis` (read-only access) or `sfcc.custom-apis.rw` (read-write access) in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

Access is intended for admin users only.

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Endpoint Status Transparency

During a new code version activation, developers and administrators often struggle to verify the status of all their Custom API endpoints. This can lead to confusion and time-consuming manual log checks to diagnose why an endpoint might not be active. By using the Custom APIs DX endpoint, a user can programmatically fetch a list of all endpoints and their current status (`active` or `not_registered`). This allows for quick identification of any registration issues, including specific error reasons for endpoints that failed to register, thereby streamlining the validation process after a deployment.

#### Debug Failed Registrations

When a Custom API endpoint fails to register, it can be difficult to understand the root cause without accessible error details. This API directly addresses this by providing an `errorReason` property for any endpoint with a `not_registered` status. For example, if an endpoint registration is skipped because its schema file cannot be read, the API response will explicitly state this, allowing developers to quickly pinpoint and resolve the issue without needing to contact support or search through extensive log files.

**Version:** 1.0.3

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.custom-apis: Custom APIs READONLY scope
    *   Scope sfcc.custom-apis.rw: Custom APIs scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Get a list of resolved Custom API endpoints.

`GET /organizations/{organizationId}/endpoints`

Operation ID: `getEndpoints`. Security: AmOAuth2 (sfcc.custom-apis).

List resolved Custom API endpoints, including not registered endpoints.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `status` (query, EndpointStatus) Filter endpoints by registration status.

#### Responses

*   **200** Successful operation
    
    Media type: `application/json`. Schema: `CustomApiEndpointResult`.
    
    _Example: SuccessWithFilter_
    
    ```
    {
      "limit": 1,
      "total": 2,
      "filter": {
        "status": "active"
      },
      "data": [
        {
          "apiName": "loyalty-info",
          "apiVersion": "v1",
          "cartridgeName": "my_cartridge",
          "endpointPath": "/customers",
          "status": "active"
        }
      ],
      "activeCodeVersion": "version1"
    }
    ```
    
    _Example: SuccessWithoutFilter_
    
    ```
    {
      "limit": 2,
      "total": 2,
      "data": [
        {
          "apiName": "loyalty-info",
          "apiVersion": "v1",
          "cartridgeName": "my_cartridge",
          "endpointPath": "/customers",
          "status": "active"
        },
        {
          "apiName": "loyalty-info",
          "apiVersion": "v1",
          "cartridgeName": "null",
          "endpointPath": "/customers",
          "errorReason": "Cartridge 'my_cartridge_2' not found.",
          "status": "not_registered"
        }
      ],
      "activeCodeVersion": "version1"
    }
    ```
    
*   **400** Invalid or malformed filter parameter
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidFilterParameter_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Invalid value 'foo' for filter parameter 'status'."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### EndpointStatus

Type: `string`.

Allowed values: `active`, `not_registered`. Example: `active`.

### CustomApiEndpointResult

Includes all fields of `ResultBase`.

*   `filter` (_CustomApiEndpointFilter_)
*   `data` (_array of CustomApiEndpoint_)
*   `activeCodeVersion` (_string_)  
    Minimum length: 1. Maximum length: 100. Example: `version1`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CustomApiEndpointFilter

*   `status` (_string_)  
    Allowed values: `active`, `not_registered`. Example: `not_registered`.

### CustomApiEndpoint

*   `apiName` (_string_)  
    Pattern: ^\[a-z0-9-\]+$. Example: `loyalty-info`.
*   `apiVersion` (_string_)  
    Maximum length: 100. Example: `v1`.
*   `cartridgeName` (_string_)  
    Pattern: ^\[a-zA-Z\]\[a-zA-Z0-9\_\]\*$. Example: `test_bc_wapi`.
*   `endpointPath` (_string_)  
    Maximum length: 4000. Example: `/customers`.
*   `errorReason` (_string_)  
    Maximum length: 4000. Example: `API schema not found.`.
*   `httpMethod` (_string_)  
    Allowed values: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `OPTIONS`, `HEAD`. Example: `GET`.
*   `id` (_string_)  
    Minimum length: 36. Maximum length: 36. Example: `10bd7f2dc40ab7aede7f0d60e5c3a783abcd`.
*   `implementationScript` (_string_)  
    Maximum length: 100. Example: `script.js`.
*   `operationId` (_string_)  
    Maximum length: 100. Example: `getLoyaltyInfo`.
*   `securityScheme` (_string_)  
    Allowed values: `ShopperToken`, `AmOAuth2`. Example: `ShopperToken`.
*   `schemaFile` (_string_)  
    Maximum length: 100. Example: `schema.yaml`.
*   `siteId` (_SiteId_)
*   `status` (_EndpointStatus_)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

<!-- document id=1088c7e67967ef539351f957a81dc5e67c39671fbea492a953a39dedac04826d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-custom-actions.md -->

# Custom Actions

Customer Service Center supports custom actions with a Business Manager extension cartridge.

- A controller represents each action
- The cartridge must be added to the BM cartridge path
- Every action is secured with a permission in the Customer Service Center permissions tab in the Roles & Permissions view.

Customizable actions can be registered for CSC UI pages:

- Customer
- Basket
- Order

The actions are registered with a `bm_extensions.xml` file.

- Every action is represented with a MenuAction of type CSC
- The menupath determines the page that the action is assigned. The following menu paths are supported.
  - customer action is registered for the customer page
  - basket action is registered for the basket page
  - order action is registered for the order page
- All custom actions can be localized

## Example

The following is an example `bm_extensions.xml` file:

```xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- =============================================================== -->
<!-- ==  CSC EXTENSIONS                                        == -->
<!-- =============================================================== -->
<extensions xmlns="http://www.demandware.com/xml/bmmodules/2007-12-11" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.demandware.com/xml/bmmodules/2007-12-11 bmext.xsd">
    <menuitem id="basket" site="true" type="CSC">
        <name xml:lang="x-default" >CSC Basket</name>
        <short_description xml:lang="x-default">Customer Service Center Basket</short_description>
        <description xml:lang="x-default">Customer Service Center Basket</description>
    </menuitem>
    <menuaction id="basket_gift_messaging" menupath="basket" type="CSC" site="true" position="3">
        <name xml:lang="x-default">Make it a Gift</name>
        <name xml:lang="fr-FR">Make it a gift (fr-FR)</name>
        <short_description xml:lang="x-default">Gift Messaging</short_description>
        <description xml:lang="x-default">Gift Messaging</description>
        <exec pipeline="CSCGiftMessaging" node="Start"/>
        <sub-pipelines>
            <pipeline name="CSCGiftMessaging" />
        </sub-pipelines>
        <parameters>
            <parameter name="basket_id" value="/basket_id"/>
        </parameters>
        <icon>csc_basket.png</icon>
    </menuaction>
    <menuaction id="basket_address_verification" menupath="basket" type="CSC" site="true" position="1">
        <name xml:lang="x-default">Verify addresses</name>
        <short_description xml:lang="x-default">Verifies all cart addresses</short_description>
        <description xml:lang="x-default">Verifies all cart addresses</description>
        <exec pipeline="CSCVerifyCartAddresses" node="Start"/>
        <sub-pipelines>
            <pipeline name="CSCVerifyCartAddresses" />
        </sub-pipelines>
        <parameters>
            <parameter name="basket_id" value="/basket_id"/>
        </parameters>
        <icon>check_address.png</icon>
    </menuaction>
    <menuitem id="order" site="true" type="CSC">
        <name xml:lang="x-default" >CSC Order</name>
        <short_description xml:lang="x-default">Customer Service Center Order</short_description>
        <description xml:lang="x-default">Customer Service Center Order</description>
    </menuitem>
    <menuaction id="order_payment_details" menupath="order" type="CSC" site="true" position="1">
        <name xml:lang="x-default">Review Payment details</name>
        <short_description xml:lang="x-default">Review Payment details</short_description>
        <description xml:lang="x-default">Review Payment details</description>
        <exec pipeline="CSCReviewPaymentDetails" node="Start"/>
        <sub-pipelines>
            <pipeline name="CSCReviewPaymentDetails" />
        </sub-pipelines>
        <parameters>
            <parameter name="order_no" value="/order_no"/>
        </parameters>
        <icon>check_address.png</icon>
    </menuaction>
    <menuitem id="customer" site="true" type="CSC">
        <name xml:lang="x-default" >CSC Customer</name>
        <short_description xml:lang="x-default">Customer Service Center Customer</short_description>
        <description xml:lang="x-default">Customer Service Center Customer</description>
    </menuitem>
    <menuaction id="customer_show_customer_groups" menupath="customer" type="CSC" site="true" position="1">
        <name xml:lang="x-default">Display Customer Groups</name>
        <short_description xml:lang="x-default">Display Customer Groups.</short_description>
        <description xml:lang="x-default">Display Customer Groups.</description>
        <exec pipeline="CSCCustomerGroups" node="Start"/>
        <sub-pipelines>
            <pipeline name="CSCCustomerGroups"/>
        </sub-pipelines>
        <parameters>
        </parameters>
        <icon>check_address.png</icon>
    </menuaction>
</extensions>
```

<!-- document id=06472dcff065c803ed19332ef573ffcffde8ad2717426d6969b11e21d53d12fe url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-status-report.md -->

# Custom API Status Report

The Custom API status report enhances transparency and reduces troubleshooting time by providing real-time visibility into the registration status of your Custom APIs. When you activate a code version that includes Custom APIs, the registration process can yield different outcomes for each endpoint. Previously, developers had to manually sift through logs to diagnose issues, but the Custom API status report simplifies this by offering clear, actionable feedback.



Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.custom-apis
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli scapi custom status --tenant-id abcd_001
npx @salesforce/b2c-cli scapi custom status --tenant-id abcd_001 --status not_registered
```

## Key Benefits

- **Real-time status reporting:** Get immediate feedback on endpoint registration status.
- **Error transparency:** Understand why an endpoint failed to register.
- **Reduced debugging time:** No manual log searching.
- **Improved development workflow:** Quickly identify and resolve endpoint issues.

## Endpoint Registration Status

Every Custom API endpoint can have one of the following registration statuses:

| Status           | Description                                                                     | Accessible? |
| ---------------- | ------------------------------------------------------------------------------- | ----------- |
| `active`         | Endpoint was successfully registered and is ready to handle requests.           | Y           |
| `not_registered` | Endpoint failed to register due to an error in configuration or implementation. | N           |

## Use the Custom API Status Report

### Authentication

The Custom API status report requires authentication using the Account Manager OAuth 2.0 flow with the required scope:

- `sfcc.custom-apis` (read-only)

### Endpoint URL

```http
GET https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints
```

### Parameters

| Parameter        | Type  | Required | Description                                                                                 |
| ---------------- | ----- | -------- | ------------------------------------------------------------------------------------------- |
| `shortCode`      | Path  | Yes      | An eight-character string assigned to a realm for routing purposes, for example: `kv7kzm78` |
| `organizationId` | Path  | Yes      | A short string that identifies your B2C Commerce instance, for example: `f_ecom_zzte_053`   |
| `status`         | Query | No       | Filter endpoints by status: `active` or `not_registered`                                    |

### Response Format

The endpoint returns a JSON object containing:

- `activeCodeVersion`: The currently active code version
- `total`: Total number of endpoints discovered across all sites and cartridges
- `limit`: Number of endpoints included in this response. This count matches the filter criteria and equals `total` when no filters are applied.
- `data`: Array of endpoint objects with detailed information
- `filter`: Object containing applied filters. This is present only if filters are used in the request.

Each endpoint object includes:

| Field                  | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| `id`                   | Unique identifier for the endpoint (consistent across code version activations) |
| `apiName`              | Name of the API, for example: `loyalty-info`                                    |
| `apiVersion`           | Version of the API, for example: `v1`                                           |
| `cartridgeName`        | Name of the cartridge containing the endpoint                                   |
| `endpointPath`         | The endpoint path, for example: `/customers`                                    |
| `httpMethod`           | HTTP method, for example: `GET`, `POST`)                                        |
| `operationId`          | Operation identifier from the OpenAPI schema                                    |
| `implementationScript` | Name of the implementation script file                                          |
| `schemaFile`           | Name of the OpenAPI schema file                                                 |
| `siteId`               | Site identifier where the endpoint is registered                                |
| `securityScheme`       | Security scheme used by the endpoint                                            |
| `status`               | Registration status (`active` or `not_registered`)                              |
| `errorReason`          | Error description (only present when status is `not_registered`)                |

## Examples

### List All Endpoints

Get information for all Custom API endpoints in your organization:

```bash
curl -X GET \
  'https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints' \
  -H 'Authorization: Bearer {access_token}'
```

Response:

```json
{
  "activeCodeVersion": "version1",
  "limit": 3,
  "data": [
    {
      "id": "10bd7f2dc40ab7aede7f0d60e5c3a783",
      "apiName": "loyalty-info",
      "apiVersion": "v1",
      "cartridgeName": "my_custom_cartridge",
      "endpointPath": "/customers",
      "httpMethod": "GET",
      "implementationScript": "customers.js",
      "operationId": "getLoyaltyInfo",
      "securityScheme": "ShopperToken",
      "schemaFile": "loyalty-schema.yaml",
      "siteId": "Sites-MyStore-Site",
      "status": "active"
    },
    {
      "id": "fd2e726fc9e23dac4951bfe325146c24",
      "apiName": "loyalty-info",
      "apiVersion": "v1",
      "cartridgeName": "my_custom_cartridge",
      "endpointPath": "/rewards",
      "httpMethod": "POST",
      "implementationScript": "rewards.js",
      "operationId": "addReward",
      "securityScheme": "AmOAuth2",
      "schemaFile": "loyalty-schema.yaml",
      "siteId": "Sites-MyStore-Site",
      "status": "active"
    },
    {
      "id": "7f8cfdf0534476b858d080b9059bc07e",
      "apiName": "loyalty-info",
      "apiVersion": null,
      "cartridgeName": "my_custom_cartridge",
      "endpointPath": null,
      "errorReason": "Schema file ../broken-schema.yaml in API folder loyalty-info must not be a relative path.",
      "httpMethod": null,
      "implementationScript": "broken-endpoint.js",
      "operationId": "brokenOperation",
      "securityScheme": null,
      "schemaFile": "../broken-schema.yaml",
      "siteId": "Sites-Site",
      "status": "not_registered"
    }
  ],
  "total": 3
}
```

### Filter by Status

Get endpoints that failed to register:

```bash
curl -X GET \
  'https://{shortCode}.api.commercecloud.salesforce.com/dx/custom-apis/v1/organizations/{organizationId}/endpoints?status=not_registered' \
  -H 'Authorization: Bearer {access_token}'
```

Response:

```json
{
  "activeCodeVersion": "version1",
  "limit": 1,
  "data": [
    {
      "id": "7f8cfdf0534476b858d080b9059bc07e",
      "apiName": "loyalty-info",
      "apiVersion": null,
      "cartridgeName": "my_custom_cartridge",
      "endpointPath": null,
      "errorReason": "Schema file ../broken-schema.yaml in API folder loyalty-info must not be a relative path.",
      "httpMethod": null,
      "implementationScript": "broken-endpoint.js",
      "operationId": "brokenOperation",
      "securityScheme": null,
      "schemaFile": "../broken-schema.yaml",
      "siteId": "Sites-Site",
      "status": "not_registered"
    }
  ],
  "filter": {
    "status": "not_registered"
  },
  "total": 3
}
```

## Responses

The API returns these standard HTTP status codes:

- `200`: Successful request
- `400`: Invalid filter parameter, for example: unsupported status value
- `401`: Authentication required
- `403`: Insufficient permissions (missing required scope)

## Common Error Scenarios

When endpoints have a `not_registered` status, common errors include:

- Invalid file paths: Schema or implementation files are not found
- Invalid files: Schema or implementation files are unreadable
- Configuration errors: Issues with API mapping
- Validation errors: Issues with security scheme or parameter definition
- Schema file errors: Invalid OpenAPI specification format or structure
- Schema reference errors: External dependency validation issues
- Path pattern errors: URL pattern parsing failures

## Troubleshooting Workflow

1. Check overall status: Use the status report without filters to get an overview of all endpoints.
2. Check code version: Verify that the active code version in the field `activeCodeVersion` is the version you expect.
3. Identify failed endpoints: Filter by `status=not_registered` to focus on problematic endpoints.
4. Analyze errors: Review the `errorReason` field for specific guidance.
5. Fix issues: Address the identified problems in your cartridge.
6. Reactivate: Upload and activate a new code version.
7. Verify: Call the status report again to confirm successful registration.

## Related Documentation

- [Custom API Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-troubleshooting.md): Additional troubleshooting guidance for Custom API development
- [Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md): Set up authentication for Status Report endpoints

<!-- document id=546de58cccea79e6ae7167c5ce8dbc02ecce3c0091d46325a165a3f75f70d228 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-apis.md -->

# Custom APIs

B2C Commerce provides powerful tools to customize shopper experiences. Today SCAPI can be customized via [Hooks](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/extensibility_via_hooks.md), where developers use the [B2C Commerce Script API](https://salesforcecommercecloud.github.io/b2c-dev-doc/) to add filters or modify responses before they get sent back to the calling application. A composable storefront calls custom APIs via hooks. Storefront Next calls them either as a generated typed client built on the [SCAPI client](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-api-integration.md#custom-apis) primitives, or directly with native `fetch`.

To further leverage existing development tools, B2C Commerce provides a framework enabling developers to write custom script code, such as controllers, and expose this functionality as a custom _REST API_ under the SCAPI framework.

The [SCAPI Custom APIs video](https://salesforce.vidyard.com/watch/ydP6b8do74w53tYnRtaAEs) walks you through how to build a cartridge with a Custom API. If you do not have access to the code samples provided in the video, see [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html).

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ydP6b8do74w53tYnRtaAEs" title="SCAPI Custom APIs" type="vidyard"}

## Overview

A Custom API URL has the following structural format:

`https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/{apiVersion}/organizations/{organizationId}/{endpointPath}`

The term `custom` must be used as API family. The parameters `apiName`, `apiVersion`, and `endpointPath` can be defined as described below.

In order to create a Custom API, three components are required:

- The **API contract** as an [OAS 3.0](https://spec.openapis.org/oas/v3.0.0) schema file.
- The **API implementation** as a script using the [B2C Commerce Script API](https://salesforcecommercecloud.github.io/b2c-dev-doc/).
- The **API mapping** defined in an `api.json` file.

In this guide, we will look at an example called _Loyalty Info API_ that can be used to retrieve the loyalty status for a given customer. This graphic shows the required components and their relationship:

![Custom API integration with B2C Commerce platform](https://developer.salesforce.com/docs/media/commerce-api/custom-api-overview.svg)

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


The components will be further explained in the next sections. Note the following details from the diagram:

- A dashed line shows where this URL segment is defined.
- The blue parameter is the endpoint identifier. It is used to bind the endpoint to the implementation and appears in all three components.

### Cartridge

Custom APIs are defined within custom code cartridges. In the `cartridge` directory, a new folder `rest-apis` must be created which is the root folder for all APIs in that cartridge.

In the `rest-apis` folder, subdirectories represent the actual APIs. The names of these directories represent the API names as they are addressed by the URL. Each directory contains the files for the three components representing this API.

**Example:** The structure for the example API called `loyalty-info` is expected to look like this:

```bash
/my-cartridge
    /cartridge
        package.json
        /rest-apis
            /loyalty-info
                api.json
                schema.yaml
                schema_v2.yaml
                script.js
                script_v2.js
        /pipelines
        /scripts
        /controllers
```

**important:** API directory names can only contain alphanumeric lowercase characters and hyphens.

**tip:** Due to the [registration process](#registration-of-endpoints), it is recommended to start implementing Custom API endpoints in a new code version.

### Contract

The API contract must be provided by an OAS 3.0 schema file in YAML format. For more information about OAS 3.0, refer to the [OAS 3.0 specification](https://spec.openapis.org/oas/v3.0.0).

In this schema file, the **API version** and the **endpoints** are defined. The API version is located in the `info.version` field and is transformed into a URL version by using the major version segment and prepending it with `v` (for example, `1.0.1` → `v1`).

The endpoints are defined as part of the `paths` object and can implement multiple operations (that is, HTTP methods). Each operation is required to have a property called `operationId`, which _must_ be unique within the schema file. It is used for mapping the endpoint to the implementation. The `path` of the endpoint becomes the `endpointPath` in the URL structure.

To secure the endpoint, define a valid security scheme as a shared component and apply it at the endpoint or global level. See [Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-authentication.md) for more details.

**Example:** The schema for a `/customers?c_customer_id={id}` endpoint in version `v1` is expected to look like this:

```yaml
openapi: 3.0.0
info:
  version: 1.0.1
  title: Loyalty Information API
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/my-org-id/oauth2/authorize
          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/my-org-id/oauth2/token
          scopes:
            c_loyaltyInfo_r: Read loyalty information of a customer
        clientCredentials:
          tokenUrl: https://my-shortcode.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/my-org-id/oauth2/token
          scopes:
            c_loyaltyInfo_r: Read loyalty information of a customer
paths:
  /customers:
    get:
      summary: Get loyalty information for customer
      operationId: getLoyaltyInfo
      parameters:
        - in: query
          name: c_customer_id
          required: true
          schema:
            type: string
        - in: query
          name: siteId
          required: true
          schema:
            type: string
            minLength: 1
        - in: query
          name: locale
          required: false
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Shows loyalty information for the customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  tier:
                    type: string
                  points:
                    type: integer
        "404":
          description: Shows that the customer is not found
          content:
            application/json:
              examples:
                not_found:
                  value:
                    {
                      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/customer-not-found",
                    }
security:
  - ShopperToken: ["c_loyaltyInfo_r"]
```

### Implementation

The API implementation is provided by a script file using the B2C Commerce Script API. The function name _must_ match the value of the endpoint’s `operationId` in the contract.

**Example:** A valid implementation for `/customers?c_customer_id={id}` based on the definition in the contract could look like this:

```javascript
var RESTResponseMgr = require("dw/system/RESTResponseMgr");

exports.getLoyaltyInfo = function () {

  var customerId = request
    .getHttpParameterMap()
    .get("c_customer_id")
    .getStringValue();

  /*
    ... some lookup of loyalty data based on customer id ...
  */

  if (customerId === "customer1") {

    var info = {
      tier: "silver",
      points: 14275
    };

    RESTResponseMgr
      .createSuccess(info)
      .render();

  } else {

    RESTResponseMgr
      .createError(404, "customer-not-found", "Customer Unknown", "You provided an unknown customer ID.")
      .render();

  }

};

exports.getLoyaltyInfo.public = true;
```

**important:** Always return responses in JSON format. Errors should additionally adhere to the SCAPI error format as described in [RFC 9457](https://datatracker.ietf.org/doc/html/rfc9457), with at least the `type` field being present. Response bodies are subject to validation in the future and may be declined if they don’t meet these requirements.
**important:** Make sure that the implementation contains high quality, well-tested code with sufficient error handling. In order to protect the platform, Custom APIs use a Circuit Breaker mechanism that will block API requests when the implementation throws too many errors. See [Circuit Breaker](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-circuit-breaker.md) for more information.
**tip:** To learn how to create JSON responses in your scripts with ease, have a look at the documentation of the Script API class [`RESTResponseMgr`](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/scriptapi/html/api/class_dw_system_RESTResponseMgr.html).

### Mapping

The `api.json` file provides the API mapping. It contains a list of endpoints, and for each entry the endpoint name, its schema file, and the name of the implementing script is defined.

**Example:** A valid mapping for `/customers?c_customer_id={id}` based on the definitions in the contract and implementation is expected to look like this:

```json
{
  "endpoints": [
    {"endpoint": "getLoyaltyInfo", "schema": "schema.yaml", "implementation": "script"},
    {"endpoint": "getLoyaltyInfo", "schema": "schema_v2.yaml", "implementation": "script_v2"}
  ]
}
```

**important:** Relative paths are not supported. The schema and implementation must be located at the same level as the corresponding `api.json`.
**important:** Provide the implementation name without the file extension.

## Registration of Endpoints

When the Custom API endpoints have been correctly defined as previously described, they must be registered in order to be accessible.

The registration is triggered by **activating the code version** containing the new API definitions. Whenever changes to an API are required, it is recommended to work in a new code version and to switch the version when ready.

## Versioning

Custom API versions are represented in two different formats, the **API version** and the **URL version**.

The API version is defined in the contract as part of the `info.version` field and applies to all endpoints defined in this file. The value must be numeric but can have multiple segments separated by a dot.

In the URL, the version is transformed by using the major version segment and prepending it with `v` . For example, this list shows valid API versions and their corresponding URL versions:

- 1 → v1
- 1.0 → v1
- 2.0 → v2
- 2.1.1 → v2

It is recommended to introduce breaking changes in a new major version. See the [SCAPI Change Policy](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-get-started.md#change-policy) for details.

## System Query Parameters

The following system query parameters exist and can be used when defined in the contract:

- **`siteId`** - The site of the current request
- **`locale`** - The locale of the current request

Make sure you understand the meaning of these parameters and when to use them. For example, the system uses the `siteId` to identify the site context, so using this parameter only makes sense for a Shopper API request. For an Admin API request that requires a site, for example: an API that returns objects filtered by site, use a custom query parameter like `c_siteId`. Note that the site is a query parameter instead of a path parameter, which is different from other ways of customization, such as using controllers and hooks.
The parameter `locale` is used to set the locale of the request, and behaves the same way as the Script API method `dw.system.Request#setLocale`.

If a `siteId` is not provided, the request is treated as a SCAPI Admin API request and the Business Manager site is used. If a `locale` is not provided in a request, the site’s default locale is used.

**note:** The parameter `siteId` is also used to register a Custom API. This means that if you don't add the cartridge containing a Custom API to a site cartridge path, any request to it with that `siteId` results in a `404` response. For Admin APIs, the cartridge must be added to the cartridge path of the Business Manager site.

Don't use a shopper token for an Admin API request. In these scenarios, use an `AmOAuth2` token.

**Example 1**: Define the system query parameter using the name for `siteId` and type `string`. If the parameter isn't a valid string, the request is declined.

```yaml
- in: query
  name: siteId
  required: true
  schema:
    type: string
    minLength: 1
```

**Example 2**: Define the system query parameter with the name `locale` and the type `string`. If the parameter isn't a valid string, the request is declined.

```yaml
- in: query
  name: locale
  required: false
  schema:
    type: string
    minLength: 1
```

**Example 3:** Make a Custom API request with system query parameters:

```http
GET https://my-shortcode.api.commercecloud.salesforce.com/custom/loyalty-info/v1/organizations/my-org-id/customers?c_customer_id=customer1&siteId=MySite&locale=en-US
```

**important:** Define system query parameters with the correct `schema` field as shown previously. Setting `required` to `false` means that the value is not required. When `required` is `true`, the request is refused if the parameter is missing or empty.

## Shopper and Admin API Endpoints

Like the non-custom B2C Commerce APIs (SCAPI), each endpoint is either a Shopper or an Admin API endpoint. For general information on how to differentiate those API groups, see [SCAPI Groups](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html#scapi-groups).

For Custom APIs, there are three main differences between Shopper and Admin endpoints:

1. Shopper endpoints have stricter limits for request body size and API quotas. See [Limitations](#limitations) for specific values.
2. Shopper endpoints require the `siteId` query parameter, while Admin endpoints must omit this parameter. Requests without a `siteId` are treated as Admin API requests.
3. Shopper endpoints require the `ShopperToken` security scheme, while Admin endpoints require the `AmOAuth2` security scheme, and each endpoint can have only one security scheme. See [Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-authentication.md) for details on how to use these.

## Supported HTTP Methods

Supported methods for Custom APIs include:

- GET
- POST
- PUT
- PATCH
- DELETE
- HEAD
- OPTIONS

The following example extends the Loyalty Information API with a POST method with which an admin can update the loyalty information:

```yaml
openapi: 3.0.0
info:
  version: 1.0.1
  title: Loyalty Information API
components:
  securitySchemes:
    AmOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes:
            c_loyaltyInfo_rw: Read or Update loyalty information of a customer
        clientCredentials:
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes:
            c_loyaltyInfo_rw: Read or Update loyalty information of a customer
paths:
  /customers/{customerId}:
    post:
      summary: Update loyalty information for customer
      operationId: updateLoyaltyInfo
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              required:
                - points
              properties:
                points:
                  type: number
                  minimum: 1
                  maximum: 99999
      responses:
        "200":
          description: Shows loyalty information for the customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  tier:
                    type: string
                  points:
                    type: integer
        "404":
          description: Shows that the customer is not found
          content:
            application/json:
              examples:
                not_found:
                  value:
                    {
                      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/custom-errors/customer-not-found",
                    }
security:
  - AmOAuth2: ["c_loyaltyInfo_rw"]
```

Here is a sample implementation for this endpoint:

```javascript
var RESTResponseMgr = require("dw/system/RESTResponseMgr");

exports.updateLoyaltyInfo = function () {

  var customerId = request
    .getSCAPIPathParameters()
    .get('customerId');

  var requestBody = request
    .httpParameterMap
    .requestBodyAsString;
  var requestJSON = JSON.parse( requestBody );

  /*
    ... Update loyalty points based on customer id and request body ...
  */


  if (customerId === "customer1") {

    var updatedInfo = {
      tier: "silver",
      points: requestJSON.points
    };

    RESTResponseMgr
      .createSuccess(updatedInfo)
      .render();

  } else {

    RESTResponseMgr
      .createError(404, "customer-not-found", "Customer Unknown", "You provided an unknown customer ID.")
      .render();

  }

};

exports.updateLoyaltyInfo.public = true;
```

**tip:** To learn more about new convenience methods for SCAPI path parsing, refer to the [`Request`](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/scriptapi/html/index.html?target=class_dw_system_Request.html) class in Script API.
**note:** The attribute `additionalProperties` is NOT allowed when defining the request body schema. To take advantage of request body validation and build robust APIs, define the request body schema in detail. If the request body schema of an endpoint contains `additionalProperties`, the endpoint is not registered.

## Validation

All request parameters _must_ be defined in the contract as requests with unknown parameters are declined. Custom query parameters must be prefixed with `c_`. [System query parameters](#system-query-parameters) must be added to the contract if used.

**Example:** Defining a mandatory query parameter with the name `c_status` and the type `integer`. If the parameter is not present or is not a valid integer, the request is declined.

```yaml
/error:
  get:
    summary: Throw an error
    operationId: throwError
    parameters:
      - in: query
        name: c_status
        required: true
        schema:
          type: integer
```

## Sample Custom API Collection

**tip:** To get access to this repository, complete the trail [Tools & Resources for Salesforce B2C Commerce Developers](https://trailhead.salesforce.com/content/learn/modules/b2c-developer-resources-and-tools/b2c-developer-access-repositories).

Our community is maintaining a Custom API collection within the [Sample Hooks Collection](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#sample-hooks-collection), providing the functionality earlier offered with hooks as new Custom APIs. Here are a few APIs available with this collection:

- URL Resolution
- URL List API
- Guest Order Look Up
- Customer Groups API
- Mini Product
- Send Mail API
- Geo IP API

For more information, check out the [Custom APIs Collection](https://github.com/SalesforceCommerceCloud/sfcc-hooks-collection/tree/main/commerce-cloud-code/plugin_hooktacular/cartridge/rest-apis) on the Salesforce Commerce Cloud GitHub repository.

## Limitations

The following limitations are in place:

- General:
  - Transactions can’t be committed in the case of GET requests.
  - The schema attribute `additionalProperties` is not allowed.
  - Shopper and Admin APIs must adhere to the applicable API quotas. For quota details, see [API Quotas documentation](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/API_Quotas.html).
- Shopper APIs:
  - Default request runtime of 60 seconds, configurable up to 120 seconds via the [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary).

    **note:** A 10-second runtime is recommended for Shopper endpoints. Set the runtime via the Timeouts API.

  - Maximum request body size of 5 MiB (5,242,880 bytes).
  - `STOREFRONT` activity type. Storefront quota limits are applied.
- SCAPI Admin APIs:
  - Default request runtime of 60 seconds, configurable up to 120 seconds via the [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary).
  - Maximum request body size of 20 MB (20,000,000 bytes).
  - `BUSINESS_MANAGER` activity type. Default quota limits are applied.

<!-- document id=5881758552567af0de6ecb541f614a7a37766973d66b89cee263486c567acc01 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/caches/b2c-custom-caches.md -->

# Custom Caches

Using a custom cache can help you improve code performance by storing data that is expensive to calculate, takes a long time to retrieve, or is accessed frequently. You define a custom cache in a JSON file in a custom cartridge.

## What Is a Custom Cache?

Approximately 20 MB of memory is reserved for all custom caches on each application server. A B2C Commerce instance can have multiple application servers, but custom caches on different application servers within the same instance are separate and not synchronized across the instance.

A common use case is to cache information that is expensive to calculate. For example, let's suppose that in your storefront, the appearance of a base product depends on the attributes of all its variation products. If any variation product is part of a promotion, the base product displays an On Sale banner. Iterating through all variation products to check whether they’re part of a promotion is an expensive operation that you don't want to repeat every time the base product is displayed, but the information can't be persisted because it could change. A good workaround is to calculate the information and add it to a custom cache for a few minutes.

Another common use case is to cache responses from an external system. For example, in-store availability and prices can be stored on an external system. Instead of making a call to the system every time you need the information, cache the information for a period of time, reducing the number of calls and page load time.

Use a custom cache to enable fast access to configuration settings from storefront requests. To implement a configuration-as-code approach, retrieve configuration data from an arbritrary source, such as a JSON file from a versioning system, and store that data in a custom cache.

## Defining a Custom Cache

You define a custom cache in a cartridge using a JSON file. Up to 100 custom caches are supported across all cartridges in a code version. Any cartridge within a code version can access all the caches defined in all the cartridges of that code version.

You reference the path of the cache definition JSON file in the cartridge's `package.json` file. The path is relative to the directory where the `package.json` is located. For example, this entry in the `package.json` file specifies that the custom caches for the cartridge are defined in a file named `caches.json` that is in the same directory as the `package.json` file.

```
"caches": "./caches.json"
```

You assign each cache an ID that is unique across all cartridges in a code version. If you use an ID in more than one cartridge in the code version, the cache isn't enabled and an error is logged. Optionally specify the maximum number of seconds an entry is retained in the cache. This JSON file defines two custom caches: UnlimitedTestCache, which doesn't have an expiration time, and TestCacheWithExpiration, which has an expiration time of 10 seconds.

```
{
  "caches": [
    {
      "id": "UnlimitedTestCache"
    },
    {
      "id": "TestCacheWithExpiration",
      "expireAfterSeconds": 10
    }
  ]
}
```

Problems with invalid cache definitions are reported in the custom error log.

If you change any file in the active code version, or activate a new code version, the content of all custom caches in the code version is cleared. Custom caches are also cleared at the end of data replications or code replications.

## Using Custom Caches

To store, retrieve, or manage a cache entry, use the B2C Commerce script API classes `dw.system.CacheMgr` and `dw.system.Cache`.

The `dw.system.CacheMgr.getCache(cacheID)` method returns caches that are already defined.

```
var cache = CacheMgr.getCache( 'SiteConfigurations' );
```

Entries within the cache are identified by a key. The `dw.system.Cache.get(key)` method returns the object associated with the key if an entry exists. To specify a scope, such as site or catalog, include a scope reference in the key construction.

```
cache.get( Site.current.ID + "config", function loadSiteConfiguration() {return loadCfg( Site.current );} );
```

A best practice is to populate a cache using `dw.system.Cache.get(key, loader)`, which returns the value associated with the key in the cache or invokes the loader function to generate the entry if no entry is found. Store an object up to 128 KB in the cache. If the value returned by the loader function is too large, the value isn't stored in the cache but `dw.system.Cache.get(key, loader)` still returns it. In this case, a log message is written to the custom warn log, and the operation is a "write failure" in the access statistics. No exception is thrown.

The cache can store only JavaScript primitive values and tree-like object structures. A cache can store `null` but not `undefined`. Objects retrieved from cache are immutable copies of the entries stored in the cache.

Custom cache content is stored in transient memory. Data isn’t persisted, and there’s no guarantee that an entry can be retrieved from the cache. The storage allocated for entries is limited, and clearing or invalidation could occur at any time.

When using a custom cache, keep in mind that caches in different application servers of the same instance are separate. The `dw.system.Cache.invalidate(key)` method clears an entry only for the current application server.

For more information about `dw.system.CacheMgr` and `dw.system.Cache`, see [B2C Commerce Script](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html).

<!-- document id=47ddc117ce590a16c370df04d9f885781c2a8dde8ff21d03b88254b41956a247 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/custom-objects.md -->

Custom Objects

# Custom Objects

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/custom-objects/custom-objects-oas-v1-public.yaml)

## API Overview

The Custom Objects API lets you manage custom objects in Commerce Cloud.

### Overview

Custom objects are instances of custom object types that can hold any business-specific data. Each custom object belongs to an object type and is identified by a unique key attribute.

Custom objects can be scoped globally (organization-level) or to a specific site.

### Key Features

*   **CRUD Operations**: Create, read, update, and delete custom objects by object type and key
*   **Search**: Search custom objects using flexible query expressions with pagination and sorting
*   **Site-Specific Scope**: Operate on global or site-specific custom objects via separate endpoints

### Searchable Attributes

The following attributes can be used in search queries:

*   `keyValueString` - The string key value of the custom object (String)
*   `keyValueInteger` - The integer key value of the custom object (Integer)
*   `creationDate` - The creation date of the custom object (Date)
*   `lastModified` - The last modification date of the custom object (Date)
*   `siteId` - The site identifier (String)
*   Any custom attribute

### Sortable Attributes

Only searchable attributes can be used in sorting.

### Authentication

This API requires OAuth 2.0 authentication with the appropriate scopes:

*   `sfcc.custom-objects` - Read access to custom object resources
*   `sfcc.custom-objects.rw` - Read and write access to custom object resources

**Version:** 1.1.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/custom-object/custom-objects/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2) Authentication via Account Manager OAuth 2.0.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.custom-objects: Allows read access to custom objects.
    *   Scope sfcc.custom-objects.rw: Allows read and write access to custom objects.

## Operations

### GET Read a global custom object by its object type ID and key.

`GET /organizations/{organizationId}/custom-objects/{objectType}/{key}`

Operation ID: `getCustomObject`. Security: AmOAuth2 (sfcc.custom-objects, sfcc.custom-objects.rw).

Reads a global custom object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Responses

*   **200** Custom object retrieved successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: MalformedKeyParameter_
    
    ```
    {
      "title": "Malformed Key Parameter",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-key-parameter",
      "detail": "The format of path parameter 'abc' for data type 'integer' is invalid."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user."
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Your access token is valid, but you don’t have the required permissions to access the resource."
    }
    ```
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: CustomObjectNotFound_
    
    ```
    {
      "title": "Custom Object Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-object-not-found",
      "detail": "No custom object with key 'nonexistent' for object type 'MyCustomType' could be found."
    }
    ```
    
    _Example: ObjectTypeNotFound_
    
    ```
    {
      "title": "Object Type Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/object-type-not-found",
      "detail": "No object type with ID 'NonExistentType' could be found."
    }
    ```
    

### PUT Create or replace a global custom object.

`PUT /organizations/{organizationId}/custom-objects/{objectType}/{key}`

Operation ID: `createCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw).

Creates a global custom object from request body. Note that an existing global custom object with the same key will be overwritten by this action.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Request body (required)

Media type: `application/json`. Schema: `CustomObject`.

_Example: CreateCustomObjectExample_

```
{
  "c_textField": "some text value",
  "c_numberField": 42,
  "c_booleanField": true
}
```

#### Responses

*   **200** Custom object replaced successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **201** Custom object created successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

### DELETE Delete a global custom object.

`DELETE /organizations/{organizationId}/custom-objects/{objectType}/{key}`

Operation ID: `deleteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw).

Deletes a global custom object. If the custom object does not exist, this will do nothing.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Responses

*   **204** Custom object deleted successfully.
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

### PATCH Update a global custom object.

`PATCH /organizations/{organizationId}/custom-objects/{objectType}/{key}`

Operation ID: `updateCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw).

Updates a global custom object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Request body (required)

Media type: `application/json`. Schema: `CustomObject`.

_Example: UpdateCustomObjectExample_

```
{
  "c_textField": "updated text value"
}
```

#### Responses

*   **200** Custom object updated successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example CustomObjectNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

### POST Search custom objects by object type.

`POST /organizations/{organizationId}/custom-objects-search/{objectType}`

Operation ID: `searchCustomObjects`. Security: AmOAuth2 (sfcc.custom-objects, sfcc.custom-objects.rw).

Searches for custom objects of a specific object type.

The query attribute specifies a complex query that can be used to narrow down the search. The following attributes are searchable:

*   `keyValueString` (String)
*   `keyValueInteger` (Integer)
*   `creationDate` (Date)
*   `lastModified` (Date)
*   `siteId` (String)
*   Any custom attribute

Only searchable attributes can be used in sorting.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50.  
    Default: `50`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Request body (required)

Media type: `application/json`. Schema: `SearchRequest`.

_Example: SearchCustomObjectsExample_

```
{
  "query": {
    "matchAllQuery": {}
  },
  "limit": 25,
  "offset": 0,
  "sorts": [
    {
      "field": "key_value_string",
      "sortOrder": "asc"
    }
  ]
}
```

_Example: SearchCustomObjectsBySiteIdExample_ Search custom objects belonging to a specific site

Restricts the search to custom objects of a specific site by filtering on the searchable `siteId` attribute. Custom object search is not scoped by site at the URL level, so filtering by `siteId` is the supported way to limit results to a single site.

```
{
  "query": {
    "termQuery": {
      "fields": [
        "siteId"
      ],
      "operator": "is",
      "values": [
        "SiteGenesis"
      ]
    }
  },
  "limit": 25,
  "offset": 0
}
```

#### Responses

*   **200** Custom objects search result.
    
    Media type: `application/json`. Schema: `CustomObjectSearchResult`.
    
    _Example: CustomObjectSearchResultExample_
    
    ```
    {
      "limit": 2,
      "hits": [
        {
          "keyProperty": "global_key",
          "keyValueString": "key1",
          "objectType": "MyCustomType",
          "c_textField": "value1"
        },
        {
          "keyProperty": "global_key",
          "keyValueString": "key2",
          "objectType": "MyCustomType",
          "c_textField": "value2"
        }
      ],
      "query": {
        "matchAllQuery": {}
      },
      "offset": 0,
      "total": 2
    }
    ```
    
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TypeMismatch_
    
    ```
    {
      "title": "Type Mismatch",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/type-mismatch",
      "detail": "There is a type mismatch for field 'key_value_integer'."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

### GET Read a site-specific custom object by its object type ID and key.

`GET /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}`

Operation ID: `getSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects, sfcc.custom-objects.rw).

Reads a site-specific custom object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (path, SiteId, required) The ID of the site that the custom object belongs to.
    
    _Example_
    
    ```
    SiteGenesis
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Responses

*   **200** Custom object retrieved successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example CustomObjectNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

### PUT Create or replace a site-specific custom object.

`PUT /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}`

Operation ID: `createSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw).

Creates a site-specific custom object from request body. Note that an existing site-specific custom object with the same key will be overwritten by this action.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (path, SiteId, required) The ID of the site that the custom object belongs to.
    
    _Example_
    
    ```
    SiteGenesis
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Request body (required)

Media type: `application/json`. Schema: `CustomObject`.

_Example: CreateCustomObjectExample_

```
{
  "c_textField": "some text value",
  "c_numberField": 42,
  "c_booleanField": true
}
```

#### Responses

*   **200** Custom object replaced successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **201** Custom object created successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

### DELETE Delete a site-specific custom object.

`DELETE /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}`

Operation ID: `deleteSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw).

Deletes a site-specific custom object. If the custom object does not exist, this will do nothing.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (path, SiteId, required) The ID of the site that the custom object belongs to.
    
    _Example_
    
    ```
    SiteGenesis
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Responses

*   **204** Custom object deleted successfully.
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

### PATCH Update a site-specific custom object.

`PATCH /organizations/{organizationId}/sites/{siteId}/custom-objects/{objectType}/{key}`

Operation ID: `updateSiteCustomObject`. Security: AmOAuth2 (sfcc.custom-objects.rw).

Updates a site-specific custom object with information from request body. Note that only mentioned attributes will be updated and the key attribute is ignored. All other attributes will be left unattended.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (path, SiteId, required) The ID of the site that the custom object belongs to.
    
    _Example_
    
    ```
    SiteGenesis
    ```
    
*   `objectType` (path, string, required) The ID of the custom object type.  
    Minimum length: 1. Maximum length: 256. Example: `MyCustomType`.
*   `key` (path, string, required) The key attribute value that identifies the custom object.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.

#### Request body (required)

Media type: `application/json`. Schema: `CustomObject`.

_Example: UpdateCustomObjectExample_

```
{
  "c_textField": "updated text value"
}
```

#### Responses

*   **200** Custom object updated successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "keyValueString": "my-key-value",
      "objectType": "MyCustomType",
      "c_textField": "some text value",
      "c_numberField": 42,
      "c_booleanField": true
    }
    ```
    
*   **400** Bad request.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MalformedKeyParameter: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 403 response._
    
*   **404** Not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example CustomObjectNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    
    _Example ObjectTypeNotFound: same as GET /organizations/{organizationId}/custom-objects/{objectType}/{key} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### CustomObject

Document representing a custom object that contains all defined custom attributes for its object type.

*   `keyProperty` (_string_) The name of the key property for the custom object. This is ignored in input documents.  
    Minimum length: 1. Maximum length: 256. Example: `myKey`.
*   `keyValueInteger` (_integer (int32)_) The id of the custom object when the type of the key is Integer. This is ignored in input documents.  
    Example: `42`.
*   `keyValueString` (_string_) The id of the custom object when the type of the key is String. This is ignored in input documents.  
    Minimum length: 1. Maximum length: 256. Example: `my-key-value`.
*   `objectType` (_string_) The id of the object type. This is ignored in input documents.  
    Maximum length: 256. Example: `MyCustomType`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `2019-10-20T12:00:00Z`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `2019-10-20T13:00:00Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### CustomObjectSearchResult

Search result containing a paginated list of custom objects.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of CustomObject_, required) The sorted array of search hits. Can be empty.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "value": {
    "must": [
      {
        "textQuery": {
          "fields": [
            "couponId"
          ],
          "searchPhrase": "DEAL"
        }
      },
      {
        "textQuery": {
          "fields": [
            "description"
          ],
          "searchPhrase": "Big bargain deal"
        }
      }
    ],
    "mustNot": [
      {
        "termQuery": {
          "fields": [
            "enabled"
          ],
          "operator": "is",
          "values": [
            false
          ]
        }
      }
    ]
  }
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "value": {
    "operator": "and",
    "filters": [
      {
        "termFilter": {
          "field": "id",
          "operator": "is",
          "values": [
            "myId"
          ]
        }
      },
      {
        "termFilter": {
          "field": "couponId",
          "operator": "is",
          "values": [
            "couponOne"
          ]
        }
      }
    ]
  }
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=05e28c2b1eb63550920436455d220e26bb555452523ec001a95dbeb15cb95780 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-properties.md -->

# Custom Properties

Use SCAPI to set custom properties of business objects in input documents and to read custom properties in output documents. Whether a business object supports custom properties can be found in the [following tables](#document-types-supporting-custom-properties).
Custom properties are always marked with the prefix `c_` and have therefore their own namespace.

## Custom Properties Example

The following example shows a document response including some custom properties:

```txt
REQUEST: GET /product/shopper-products/v1/organizations/ORG_ID/products/creative-zen-v HTTP/1.1
Host: SHORTCODE.api.commercecloud.salesforce.com
Accept: application/json

RESPONSE: HTTP/1.1 200 OK
Content-Type:  application/json; charset=UTF-8
Cache-Control:  max-age=900,must-revalidate
{
   ...
   "c_mediaFormat" : [ "0010", "0020", "0030", "0040" ],
   "c_memorySize" : "1GB",
   "c_tabDescription" : "The ZEN V player was designed for people like you those who walk a step or two ahead of the pack."
}
```

## Custom Properties Value Types

SCAPI supports the following value types for input and output of custom properties:

- Text
- String
- Enum of Strings
- Set of Strings
- Integer
- Enum of Integers
- Set of Integers
- Double
- Set of Doubles
- Boolean
- EMail
- Password
- Date
- Date+Time

**note:** The value types **HTML** and **Image** are only supported as output, but not as input value type for custom properties in SCAPI.

## Document Types Supporting Custom Properties

The following tables list the document types that support custom properties. Hooks (`modify...`) that use the referenced document types can
add custom properties using the `c_` prefix. See [Customization With Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) for more information.

### Shopper API

The following Shopper API documents support custom properties.

| Document Type                    | Reference                                                                                                                                                                 |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Basket v1                        | [Basket v1](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABasket)                                                    |
| Basket v2                        | [Basket v2](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=type%3ABasket)                                                 |
| BasketPaymentInstrumentRequest   | [BasketPaymentInstrumentRequest](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABasketPaymentInstrumentRequest)       |
| BonusDiscountLineItem            | [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABonusDiscountLineItem)                         |
| Category                         | [Category](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=type%3ACategory)                                                  |
| CouponItem                       | [CouponItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACouponItem)                                               |
| CustomObject                     | [customObject](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-custom-objects?meta=type%3AcustomObject)                                    |
| Customer                         | [Customer](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer)                                                 |
| CustomerAddress                  | [CustomerAddress](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress)                                   |
| CustomerInfo                     | [CustomerInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACustomerInfo)                                           |
| CustomerPaymentInstrument        | [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerPaymentInstrument)               |
| CustomerPaymentInstrumentRequest | [CustomerPaymentInstrumentRequest](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerPaymentInstrumentRequest) |
| CustomerProductList              | [CustomerProductList](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList)                           |
| CustomerProductListItem          | [CustomerProductListItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem)                   |
| CustomerProductListItemPurchase  | [CustomerProductListItemPurchase](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItemPurchase)   |
| GiftCertificate                  | [GiftCertificate](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-gift-certificates?meta=type%3AGiftCertificate)                           |
| GiftCertificateItem              | [GiftCertificateItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AGiftCertificateItem)                             |
| OptionItem                       | [OptionItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3AOptionItem)                                             |
| Order                            | [Order](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder)                                                          |
| OrderAddress                     | [OrderAddress](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderAddress)                                           |
| OrderPaymentInstrument           | [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderPaymentInstrument)                       |
| OrderPaymentInstrumentRequest    | [OrderPaymentInstrumentRequest](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderPaymentInstrumentRequest)         |
| PathRecord                       | [PathRecord](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=type%3APathRecord)                                              |
| PaymentCardSpec                  | [PaymentCardSpec](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3APaymentCardSpec)                                      |
| PaymentMethod                    | [PaymentMethod](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3APaymentMethod))                                         |
| PriceAdjustment                  | [PriceAdjustment](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3APriceAdjustment)                                      |
| PriceAdjustmentRequest           | [PriceAdjustmentRequest](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3APriceAdjustmentRequest)                        |
| Product                          | [Product](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=type%3AProduct)                                                    |
| ProductItem                      | [ProductItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AProductItem)                                             |
| ProductListItem                  | [CustomerProductListItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem)                   |
| ProductListItemReference         | [ProductListItemReference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3AProductListItemReference)                 |
| ProductListLink                  | [ProductListLink](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3AProductListLink)                                   |
| ProductSearchHit                 | [ProductSearchHit](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=type%3AProductSearchHit)                                    |
| Promotion                        | [Promotion](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-promotions?meta=type%3APromotion)                                              |
| PublicProductList                | [PublicProductList](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3APublicProductList)                               |
| PublicProductListItem            | [PublicProductListItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3APublicProductListItem)                       |
| PublicProductListLink            | [ProductListLink](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3AProductListLink)                                   |
| Recommendation                   | [Recommendation](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=type%3ARecommendation)                                      |
| Shipment                         | [Shipment](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShipment)                                                   |
| ShippingItem                     | [ShippingItem](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AShippingItem)                                            |
| ShippingMethod                   | [ShippingMethod](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShippingMethod)                                       |
| ShippingPromotion                | [ShippingPromotion](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AShippingPromotion)                                  |
| Store                            | [Store](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-stores?meta=type%3AStore)                                                          |
| SuggestedCategory                | [SuggestedCategory](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=type%3ASuggestedCategory)                                  |
| SuggestedPhrase                  | [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=type%3ASuggestedPhrase)                                      |
| SuggestedProduct                 | [SuggestedProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=type%3ASuggestedProduct)                                    |
| Suggestion                       | [Suggestion](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=type%3ASuggestion)                                                |

<!-- document id=6c9fff5847838f14ae151be56f9153be5e01c993df4c8ac9498e76981ed10b78 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-custom-readiness-rules.md -->

# Custom Rules for Product Readiness

Merchandisers can run Product Readiness on their catalogs to ensure that all products in a catalog are storefront ready. By default, Product Readiness uses a rule set that contains criteria based on SKUs, images, categories, and descriptions. If the default Product Readiness rule set doesn’t fit your organization’s needs, create a custom rule set to determine what criteria a product must fit to be considered ready.

Use an APEX class to create a rule set, and then activate the Readiness.ProductEvaluator. After the rule set is enabled, an admin must rebuild the index.

A custom rule can’t be added to the default rule set. If a custom rule set is enabled, it replaces the default rule set.

ProductScore records are associated with productIds as a measure of Product Readiness. If there are no score details returned for a given product, the score record is deleted. This rule allows for obsolete product scores to be deleted if the rules no longer return scores for these cases.

## Example

```nolang
public class ProductReadinessDescriptionEvaluator implements Readiness.ProductEvaluator {

    // return true for the rule to run
    public boolean isActive() {
        return true;
    }

    // return a list of Readiness.ProductScoreDetail which will become the product readiness score
    public List<Readiness.ProductScoreDetail> evaluateReadiness(Readiness.ProductEvaluationContext productContext) {
        // example implmentation which checks for a description and a price
        Set<ID> productIds = productContext.ProductIds;
        List<Readiness.ProductScoreDetail> scores = new List<Readiness.ProductScoreDetail>();

        List<Product2> products = [SELECT
              id, description
              FROM  Product2
              WHERE
              id IN : productIds];

        for (Product2 product : products) {
            scores.add(new Readiness.ProductScoreDetail(
                product.Id,
                'Description Length',
                String.isBlank(product.description) ? 0 : 100,
                'Product does not have a Description.'));

            List<PricebookEntry> entries = [SELECT id FROM PricebookEntry WHERE Product2Id = :product.Id];
            Integer pricebookScore = (entries.size() == 0) ? 0 : 100;
            scores.add(new Readiness.ProductScoreDetail(
                product.Id,
                'Price',
                pricebookScore,
                'Product must have a price.'));
        }

        return scores;
    }
}
```

<!-- document id=f4a797d3c165ad46dc67f24d27e63d3d8affbca76c2571393eb22a916e4038de url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-custom-error-pages.md -->

# Custom Storefront Error Pages

Create branded custom error pages (technically referred to as a 404 error page) within the storefront. Use custom error pages to provide a helpful message to your customers, with information about what to do next, instead of a generic message like `404 URL not found`.

Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Custom Error Pages**.

Upload customized error pages for the following HTTP status errors:

- Internal Server Error (majorerror.html)
- URL not found (url_error.html)
- Timeout (overload.html)

**note:** Static resource error pages can't be customized.

## Uploading

The B2C Commerce Web Server error pages are uploaded to a shared directory. To view this directory, select **Administration** > **Site Development** > **Custom Error Pages**.

Within Business Manager, download a template .zip file containing all error pages that are used in cases where the application server is down or doesn't respond in time. After you download the .zip file, customize the content, archive your work, and upload it.

Upload the pages as one .zip file that includes the following:

- One html file per error code
- CSS files and images as necessary

The uploaded .zip file must be named errorpages.zip. Don't use names such as `myCustomErrorPages.zip`.

**note:** Only one .zip file can be uploaded at a time. Remember to reference CSS files and images using `/waroot/FILENAME`.

After your upload, the .zip file is automatically extracted and the content is stored on the web server.

**note:** The content is loaded to the web server via a job that runs every 2 hours. You might have to wait up to 2 hours to see the content on the server.

## Testing

Test customized errors by:

- 404 error: entering an invalid URL.
- Transmission error: Call support and request that they take down the application server for the instance. Only do this on Sandboxes.

## Error Page Best Practices

We recommend following error page best practices to give your customers the best experience.

- Briefly explain what happened. Provide a reason for your customer ending up on a page they didn't expect to see.
- Don't blame the user. Don't tell the user that they messed up. Simply apologize and move on to something more positive.
- Provide a search box. Give the user a way to search for the page they want to find.
- Offer more navigation. Give the user multiple ways of navigating back to the site. Perhaps have links to specific products or categories and try to provide ways for them to quickly get back to shopping, such as:
  - Going back one step
  - Returning to the home page
  - Going to the customer service or help page
- Use a little humor. Lighten up the situation and interruption with a little brand-based humor.
- Ask the customer to help you. Offer a way to let you know about a broken link with a link to customer service and a promotion code thanking them.
- Build error pages as content assets within B2C Commerce. Content assets reduce the need to involve web developers for changes, and reuse elements in other places (such as the Zero Search Results page).

<!-- document id=304013a135fe513eba41b85ec7b0c5a48258c986314f639053f34629657a68d3 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/customer-and-associates.md -->

# Customer & Associates

Implement clienteling logic and manage store associate access.

## In this section

- [Clienteling SPI for CRM](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-for-crm.html)
- [Clienteling SPI Field Mapping](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-field-mapping.html)
- [SPI Customer Search Layout](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-customer-search-layout.html)
- [Bulk APIs for Creating & Updating Store Associates](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/bulk-apis-for-creating-updating-store-associates.html)

<!-- document id=01a00ed7694a6ac07388fb9520c8f11099d502a28ad160444ee7dfe49aa67003 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/customer-address-spi.md -->

Customer Address SPI

# Customer Address SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/customer-address-spi/customer-address-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to modify customer addresses.

**Version:** 2.3.4

## Tags

### Customer Address SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/customer-address-spi/customer-address-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to modify customer addresses.

## Operations

### GET Retrieve customer address list.

`GET /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `getCustomerAddresses`. Tags: Customer Address SPI.

Retrieve a list of addresses for a customer by customer ID.

#### Parameters

*   `customerId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `GetCustomerAddressesResponse`.
    

### PUT Update customer address.

`PUT /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `updateCustomerAddress`. Tags: Customer Address SPI.

Update customer address by customer ID and address ID.

#### Request body

Media type: `application/json`. Schema: `UpdateCustomerAddressRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UpdateCustomerAddressResponse`.
    

### POST Add new customer address.

`POST /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `addCustomerAddress`. Tags: Customer Address SPI.

Add a new address for a customer.

#### Request body

Media type: `application/json`. Schema: `AddCustomerAddressRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `AddCustomerAddressResponse`.
    

### DELETE Delete customer address.

`DELETE /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `deleteCustomerAddress`. Tags: Customer Address SPI.

Delete customer address by customer ID and address ID.

#### Parameters

*   `customerId` (query, string)
*   `addressId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DeleteCustomerAddressResponse`.
    

## Schemas

### GetCustomerAddressesResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_, nullable) List of customer addresses.
*   `error` (_boolean_)

### UpdateCustomerAddressRequest

*   `customerId` (_string_) Customer ID.
*   `address` (_Address_)
*   `addressId` (_string_) Address ID of address to update.

### UpdateCustomerAddressResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_) List of customer addresses.
*   `error` (_boolean_)

### AddCustomerAddressRequest

*   `customerId` (_string_) Customer ID.
*   `address` (_Address_)

### AddCustomerAddressResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_) List of customer addresses.
*   `error` (_boolean_)

### DeleteCustomerAddressResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_, nullable) List of customer addresses.
*   `error` (_boolean_)

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

<!-- document id=f52a1093b64c22271f4fef40b078373990e2c84911aeb28194105c188cc10e90 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/customer-api.md -->

Customer API

# Customer API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/customer-api/customer-api-oas-public.yaml)

Merchant API to manage customer data in the POS system.

**Version:** 2.3.4

## Tags

### Customer API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/customer-api/customer-api-oas-public.yaml)

Merchant API to manage customer data in the POS system.

## Operations

### POST Mask customer data.

`POST /merchant/{version}/customer/mask`

Operation ID: `maskCustomerData`. Tags: Mask Customer Data, Customer API.

Administrative API to mask specific customer data to satisfy CCPA/GDPR requirements. Customer records are identified by customer ID or email address, and PII fields are replaced with mask characters across all relevant data stores.

The following categories of customer data are masked:

*   **Names** — first name, last name, middle name, initials
*   **Contact information** — email addresses, phone numbers
*   **Addresses** — billing and shipping addresses, including street, city, state/province, ZIP/postal code, and country
*   **Demographic information** — gender, age, date of birth
*   **Payment information** — credit card numbers, card type, expiration dates, billing address
*   **Loyalty and consent** — loyalty enrollment data and related consents
*   **Identification numbers** — driver's license, national ID, and similar identifiers

Masking is applied across relational databases (MySQL), NoSQL databases (DynamoDB), caches (Redis), and data warehouses (Redshift). Object storage (S3) is covered by TTL policies.

Masking is asynchronous. The response returns a `requestId` and an `IN_PROGRESS` status. Use the request ID to poll for completion.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerMaskResponse`.
    

## Schemas

### CustomerMaskResponse

*   `requestId` (_string_) Unique identifier for this masking request.  
    Example: `e7966181-88a6-4247-9261-0ef0f35eb336`.
*   `customerCount` (_integer (int32)_) Number of customer records included in the masking request.  
    Example: `2`.
*   `status` (_string_)
    
    Current status of the masking request.
    
    *   `IN_PROGRESS` — Masking is running asynchronously.
    *   `SUCCESSFUL` — All specified customer records have been masked.
    *   `FAILED` — Masking failed. See `errorCode` and `errorMessage` for details.
    
      
    Allowed values: `IN_PROGRESS`, `SUCCESSFUL`, `FAILED`.
*   `requestedOn` (_integer (int64)_) Unix timestamp (milliseconds) indicating when the masking request was submitted.  
    Example: `1746136132000`.
*   `errorCode` (_string_) Machine-readable error code. Present only when `status` is `FAILED`.  
    Example: `MISSING_ID`.
*   `errorMessage` (_string_) Human-readable error message. Present only when `status` is `FAILED`.  
    Example: `No customer identifier(s) provided`.

<!-- document id=8cd68a5eebcc6c584b99ae56471ea353453201d932cf8421b405dd593f551b3b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customers/b2c-customer-data-for-developers.md -->

# Customer Data

Use the Salesforce B2C Commerce API to run customer searches.

For example, when using the Customer Service Suite. B2C Commerce supports a search relevance service.

Access customer data programmatically. See the B2C Commerce API documentation.

Your application can interact with OAuth2 Providers, which enable you to authenticate and obtain information about customers at their request via their accounts with other parties.

## APIs for Customer Search

Use the search relevance functionality for improved performance.

Many customers use the Salesforce B2C Commerce scripting API to run customer searches. B2C Commerce automatically performs a full-text search.

**note:** To take advantage of the search relevance functionality and its improved performance, convert all code to use the `searchProfiles` and `processProfiles` methods.

### API Usage

The `dw.customer.CustomerMgr` APIs behave as follows:

- Wildcards are filtered from the query (\*, %, +) and replaced by spaces.
- LIKE and ILIKE queries are executed as full text queries (working on whole words).
- LIKE queries are case insensitive.
- Using logical operators can change the execution of LIKE/ILIKE clauses to exact string comparisons, depending on how they are combined.

  LIKE and ILIKE work on the entire text, but with some text preprocessing, such as stemming. This type of analysis, however, can't be used on some queries, depending on the combination of logical operators.

- Using logical operators can result in degraded performance, depending on how they are combined.

  Having both AND and OR in the same query impacts performance.

- Having range queries (which includes anything such as a>b) impacts performance.

- The search only returns the first 1000 hits from the search result.

### Customer Profile Batch Processing API

Use the scripting API, _dw.customer.CustomerMgr.processProfiles()_, to process customer profiles in batch mode. This API, based on the full text search service, can process a many profile objects with optimized search performance and memory management.

Use this API in custom jobs to replace these older APIs:

- `dw.customer.CustomerMgr.queryProfiles(…)`
- `dw.object.SystemObjectMgr.querySystemObject(profile, …)`

The _dw.customer.CustomerMgr.processProfiles(…)_ API accepts a customer profile object query and a JavaScript callback function as input parameters. The method searches customer profiles based on the specified query parameters and executes the specified callback function for each search result.

Here is an example of how you would use this API:

```javascript
function callback(profile: Profile) {
  // PROCESSING CODE GOES HERE
}
dw.customer.CustomerMgr.processProfiles("gender=1", callback);
```

## Customer Authorization with OAuth2

OAuth2 authenticates customers and obtains information about them by interacting with other parties such as Google, Facebook, or LinkedIn. Customers must authorize such access.

Salesforce B2C Commerce supports the [OAuth2 Specification](http://tools.ietf.org/html/rfc6749) for storefronts to interact with [OAuth2 Providers](http://oauth.net/2/).

This feature also makes it faster and easier for customers to register with and log in to your storefront. Instead of entering personal information, customers can log in with an existing account, such as a Google account. Using an existing account gives your storefront permission to retrieve their personal information from that account.

This feature involves the following steps.

| Step                                                                                               | Who does it?                     |
| -------------------------------------------------------------------------------------------------- | -------------------------------- |
| Register Your Site ("Application") with the OAuth2 Providers that you want to support.             | Storefront developers            |
| Configure the OAuth2 Providers for your storefront.                                                | Storefront developers and admins |
| Use OAuth2 APIs in your storefront to give customers the option to log in using external accounts. | Storefront developers            |

For more information, see [Configure OAuth2 Providers](https://help.salesforce.com/s/articleView?id=cc.b2c_configuring_oauth2_providers.htm).

### Register Your Site with OAuth2 Providers

To enable your storefront to interact with OAuth2 providers such as Google and Facebook, register your site as a client application with the providers you want to support.

The registration process is provider-specific. The following sections provide some helpful information about the registration processes of popular OAuth2 providers to help you get started.

**note:** This topic assumes that you are familiar with the OAuth2 specification and OAuth2-related concepts. In addition, several of the links provided here require a site-specific account.

### Google

Obtain client credentials for your application from the [Google API Console](https://console.developers.google.com/).

For information on using OAuth2 with Google, see the following resources:

- [https://developers.google.com/identity/protocols/OAuth2](https://developers.google.com/identity/protocols/OAuth2)
- [https://developers.google.com/oauthplayground/](https://developers.google.com/oauthplayground/)

### LinkedIn

To register your client application, go to [https://www.linkedin.com/secure/developer](https://www.linkedin.com/secure/developer).

For more information, see [https://docs.microsoft.com/en-us/linkedin/shared/authentication/authentication](https://docs.microsoft.com/en-us/linkedin/shared/authentication/authentication).

### Microsoft

To register your client application, go to [https://account.live.com/developers/applications/index](https://account.live.com/developers/applications/index).

If you have a regular Live customer account through which you can test OAuth login as an end user, you can see what permissions you have given the client application by going [Here](https://account.live.com/consent/Manage) and selecting **Apps and Services**.

For background information, see [https://docs.microsoft.com/en-us/azure/active-directory/develop/](https://docs.microsoft.com/en-us/azure/active-directory/develop/).

### Facebook

To register your client application, go to [https://developers.facebook.com/apps](https://developers.facebook.com/apps).

Facebook doesn't follow the OAuth2 specification in some older versions, because some of the responses in the authentication flow are in plain text, instead of JSON. Facebook also expects a non-standard access token query parameter name in one of the URLs.

For more information, see [https://developers.facebook.com/docs/facebook-login/](https://developers.facebook.com/docs/facebook-login/).

### GitHub

To register your client application, go to [https://github.com/settings/applications/new](https://github.com/settings/applications/new). The Callback URL must be an absolute URL, for example:

`https://domain/on/demandware.store/Sites-SiteGenesis-Site/default/Login-OAuthReentryGitHub`

GitHub allows only one URL. For more information, see [https://developer.github.com/apps/building-oauth-apps/](https://developer.github.com/apps/building-oauth-apps/).

<!-- document id=64cffea643aee2e6326d9a9a91a20aecb7bf3b5a3949b36188073921626f9466 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-customer-service-center.md -->

# Customer Service Center

The Customer Service Center module lets you create and search for orders and customers as well as view order and some customer data. You can also customize Customer Service Center behavior and appearance to meet your business needs.

**note:** Customer Service Center is turned off by default. All users (including administrators) must have permissions set in Business Manager to be able to use the Customer Service Center module.

Depending on your permission, this module lets you:

- Search for orders
- Create orders, including:
  - Adjust prices on individual items, shipping cost, or entire orders
  - Enter coupon code to apply to a new order
  - Specify shipping and billing address
  - Search for products and refine the quantity in an order
- Search for customers
- Create customers
- Create an order for a customer
- View a customer's orders
- View and modify customer data

Customize Customer Service Center to modify the behavior and appearance of its business logic and user interface.

- Business logic, through Shop API hooks. For example, payment processing or hosted payment pages customization
- Areas of the CSC UI by modifying the JSON for those areas in Business Manager

Use existing B2C Commerce capabilities and integrations in Customer Service Center using B2C Commerce Soap APIs and Open Commerce API (OCAPI) hooks. For example, Payment Service Providers and Order Calculation.

<!-- document id=1bf72d7e049dd7d609d54eb18bcb4696939641618384ec21a814132d155f9bec url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-customizable-areas.md -->

# Customer Service Center Customizable Areas

Areas contain the specific tab layout and are referenced in the tabs.

```json
"areas": {
    "customer_info": {
      "layout": [
        {
          "layout": [
            {
              "id": "form",
              "layout": [
                {
                  "attribute": "email"
                }
              ]
            }
          ]
        }
      ],
      "widgets": {
        "form": {
          "type": "attribute_form"
        }
      }
    }
  }
```

Customize a CSC customizable area. The customizable areas can be modified and localized.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Customer Service Center Settings**.
2.  Select the **Customizable Area** from the list.
3.  Modify the configuration and click **Save**.

    - To return the configuration to the default, delete the existing configuration and click **Save**.
    - Customer Service Center recognizes MetaData Regex configurations for customizable forms. Also, overwrite a regex in a particular form configuration.

**note:** Customizable areas aren't localized into languages supported by Business Manager.

Details on customizing each area are included in the remaining sections of this guide.

## Basket View

Use basket view to configure the entire basket view.

- Widget `basket_shipments`

  Shows the shipments including the items grid and the drop area for multi shipments if enabled.

  ```json
  "basket_shipments" : {
     "type" : "basket_shipments"
  }
  ```

  **note:** Use the DefaultShipment data provider to configure the default shipment as a gift and add a gift message. Use DefaultShipment in any of the customization pages, as long as a basket is available.

- Widget `order_totals`

  Displays all basket (future order) prices.

  ```json
  "order_totals" : {
    "type" : "order_totals"
  }
  ```

- Widget `basket_coupons`

  Captures coupons and source codes and display application status.

  Configuration:

  | Name   | Type                               | Description                                                                |
  | ------ | ---------------------------------- | -------------------------------------------------------------------------- |
  | `type` | `enum (coupon, source_code, both)` | Controls whether the widget track coupons only, source codes only or both. |

  ```json
  "basket_coupons" : {
    "type" : "basket_coupons",
    "config": { "type" : "both"}
  }

  "basket_coupons" : {
    "type" : "basket_coupons",
    "config": { "type" : "coupon"}
  }

  "basket_coupons" : {
    "type" : "basket_coupons",
    "config": { "type" : "source_code"}
  }
  ```

## Basket Billing Address

The basket shipping and billing address can contain a form to enter a new address.

## Basket Billing Address View

The basket billing address view is a customizable area. This view shows the billing address of a basket as well as the appearance of each list-entry in the billing from the customer's address book.

![Basket billing address view showing a billing address and address book entries in the Customer Service Center](https://developer.salesforce.com/media/b2c-commerce/b2c_customer_service_center_billing_address_without_anything.png)

## Basket Payment Instrument

The basket payment instrument lets you show a payment form that contains all values needed for a particular payment. The form appears after selecting a particular payment method and adds a payment to the order.

- Widget `payment_method`

  Provides a selection grid for a payment method.

- Widget `payment_totals`

  Shows the payment totals of a basket or an order to have an overview of subtotals and totals (which varies with payment promotions).

  ```json
  "order_totals" : {
    "type" : "order_totals"
  }
  ```

## Basket Shipping Address

The basket shipping address contains a form to add an address.

## Customer Address Create

The customer address is a customizable area that creates a form.

## Customer Address Edit

The customer address edit form is a customizable area.

## Customer Create

The customer create form is a customizable area

## Customer Edit

The customer edit form is a customizable area.

## Customer Summary

A customizable area that shows the customer details in the customer's view.

## Order Billing Address View

A customizable view that shows that the billing addresses are formatted correctly.

## Order Payment Instrument

The order payment instrument is a customizable area that shows a payment form that contains all values needed for a particular payment. The form appears after selecting a particular payment method and adds a payment to the order.

- Widget `payment_method`

  Provides a selection grid for a payment method.

- Widget `payment_totals`

  Shows the payment totals of a basket or an order to have an overview of subtotals and totals (which varies if there are payment promotions).

  ```json
  "order_totals" : {
    "type" : "order_totals"
  }
  ```

## Order Shipping Address View

A customizable view for verifying that shipping addresses are correctly formatted.

## Order Summary

A customizable area atop of the items view to show arbitrary content.

## Price Adjustment

This customizable area is used for adding product, shipping, or order price adjustments of a basket. Beyond the standard form widgets, a `price_adjustment_value` widget can be added for entering the particular value.

- Widget `price_adjustment_value`

  Shows the price adjustment value element that can be switch between amount off, percentage off and price change.

## Product Detail

The Product Detail page is entirely customizable. In addition to the common widgets, other widgets are supported and can be placed anywhere in the area.

- Widget `gallery`

  Configuration

  | Name    | Type                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
  | ------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | mapping | Business Manager's view types to client viewtypes map | Maps the Business Manager's view types to client view types. Important are the view types for "large" and "small". The viewtype "large" specifies all available images while viewtype "small" is responsible for the navigation images. The following example maps the Business Manager's view type "small" to the client's "small" view type, "large" to the client's "large" and "hi-res" to the client's "high" view type. It is possible to have multiple business manager view types per target view type. |

  ```json
  {
    "mapping": [
      {
        "small": "small",
        "large": "large",
        "high": "hi-res"
      },
      {
        "small": "swatch",
        "large": "swatch"
      }
    ]
  }
  ```

- Widget `product_variation`

  Displays and allows the modification of the product's variation attributes.

- Widget `product_availability`

  Displays stock level of a product. In case a product is out of stock (pre- or back-ordered), this component shows the expected in-stock date.

- Widget `product_option`

  Displays and allows the modification of product options.

- Widget `product_unit_price`

  Shows the unit price of a product.

- Widget `product_total_price`

  Shows the total price of a product. This widget includes all options and considers the selected quantity.

- Widget `product_quantity`

  Displays and allows modification of the quantity of a product item.

- Widget `product_title`

  Shows the product's title. This widget consists of the product name, the product brand, and the product ID.

## Product Search

Customize the product search results, for example, with attributes such as size, color, a secondary product title. This information helps agents more easily identify the correct item without having to open a product detail page.

The customizable area appears below the area where the tile content, which includes the image, product title, SKU, price, and availability. You select configurable attributes in Business Manager.

<!-- document id=b1b02ee4beaac71ac68c608fb2d26308c8083b7213e16287957a4b1edc39eee2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-data-sources.md -->

# Customer Service Center Data Resources

Each customizable area shows data from its default data source. For this data source, no configuration is necessary. If a customizable area shows (or modifies) data from different resource, that resource must be configured. To show other attributes from other data resources in vies or forms, the element data has to be added as a new top-level element.

In this data section, the additional attributes have to be configured accordingly.

```json
"attributes": {
    "attributname": {
        "read": {
            "resource": "Resourcename",
            "path": "attribute read path"
        },
        "write": {
            "resource": "Resourcename",
            "path": "attribute write path"
        }
    }
}
```

The attribute read path can also contain XPath expressions and functions.

## Example

An agent wants to check (and possibly modify) the customer's email address when editing the basket billing address, because an email address is required for ordering. With customization of the basket billing address and by using a different resource (BasketCustomer, which provides the customer's email address), the email address can be added to the configuration.

Because the CSC Basket Customer Info Data Provider takes care of metadata handling, the necessary type information is transferred accordingly. The attribute customeremail is available in attribute_layout or attribute_form widgets and can be edited while editing the billing address.

The following is a slightly stripped down billing address configuration:

```json
{
  "data": {
    "attributes": {
      "customeremail": {
        "read": {
          "resource": "BasketCustomer",
          "path": "/email"
        },
        "write": {
          "resource": "BasketCustomer",
          "path": "/email"
        }
      }
    }
  },
  "layout": [
    {
      "condition": "data",
      "layout": [
        {
          "id": "address",
          "layout": [
            {
              "attribute": "customeremail", "width":12
            },
            {
              "attribute": "first_name",
              "meta": {
                "maxLength": 50
              },
              "width": 6
            },
            {
              "attribute": "last_name",
              "meta": {
                "maxLength": 50,
                "required": true
              },
              "width": 6
            },
            {... more attributes... }
          ]
        }
      ]
    }
  ],
  "widgets": {
    "address": {
      "type": "attribute_form"
    }
  }
}
```

The resulting billing address form contains now an email that is updated outside the actual billing address.

## Area-Specific Data Sources

|                                                                                                                                                                                                                                     |                           |                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------- |
| Customizable area                                                                                                                                                                                                                   | Default data source       | Alternative data sources              |
| Product Detail                                                                                                                                                                                                                      | BasketProduct             | Basket Address, Customer Info, Basket |
| Basket Shipping Address                                                                                                                                                                                                             | Basket Address            | Customer Info, Basket                 |
| Basket Billing Address                                                                                                                                                                                                              | Basket Address            | Customer Info, Basket                 |
| Basket Billing Address View <ul><li>These customizable areas are also used to show a list of all basket addresses for selecting the billing or shipping address of a basket.</li><li>The data source is Basket Addresses.</li></ul> | Basket Address            | Customer Info, Basket                 |
| Basket Shipping Address View                                                                                                                                                                                                        | Basket Address            | Customer Info, Basket                 |
| Basket Payment Instrument                                                                                                                                                                                                           | Basket Payment Instrument | Customer Info, Basket                 |
| Price Adjustment                                                                                                                                                                                                                    | Price Adjustment          | Basket Address, Customer Info, Basket |
| Order Payment Instrument                                                                                                                                                                                                            | Order Payment Instrument  | Order Address, Order                  |
| Order Billing Address View                                                                                                                                                                                                          | Order Address             | Order                                 |
| Order Shipping Address View                                                                                                                                                                                                         | Order Address             | Order                                 |

### Basket

Provides data from a basket.

Name in configuration: Basket

Parameter:

| Name      | Meaning          | Required? |
| --------- | ---------------- | --------- |
| basket_id | ID of the basket | yes       |

### Basket Address

Provides data of an address of a basket.

Name in configuration: BasketAddress

Parameters:

| Name        | Meaning                                      | Required?                                     |
| ----------- | -------------------------------------------- | --------------------------------------------- |
| basket_id   | ID of the basket                             | yes                                           |
| shipment_id | ID of the shipment to fetch the address from | no, the billing address is returned otherwise |

### Basket Payment Instrument

Provides data about the payment instrument.

Name in configuration: BasketPaymentInstrument

Parameters:

| Name                  | Meaning                              | Required? |
| --------------------- | ------------------------------------ | --------- |
| basket_id             | ID of the basket                     | yes       |
| payment_method_id     | ID of the payment method to pay with | no        |
| payment_card_type     | type of the credit card to use       | no        |
| payment_instrument_id | ID of the payment instrument         | no        |

### Basket Product

Provides data of a product item.

Name in configuration: BasketProduct

Parameters:

| Name       | Meaning                | Required?                    |
| ---------- | ---------------------- | ---------------------------- |
| basket_id  | ID of the basket       | yes                          |
| item_id    | ID of the product item | no, if a product_id is given |
| product_id | ID of a product        | yes, if no item_id is given  |

### Customer Info

Provides data of a customer.

Name in configuration: BasketCustomer

Parameter:

| Name      | Meaning          | Required? |
| --------- | ---------------- | --------- |
| basket_id | ID of the basket | yes       |

### Order

Provides data from an order.

Name in configuration: Order

Parameter:

| Name     | Meaning      | Required? |
| -------- | ------------ | --------- |
| order_no | order number | yes       |

### Order Address

Provides data of an address of an order.

Name in configuration: OrderAddress

Parameters:

| Name        | Meaning                                      | Required?                                     |
| ----------- | -------------------------------------------- | --------------------------------------------- |
| order_no    | order number                                 | yes                                           |
| shipment_id | ID of the shipment to fetch the address from | no, the billing address is returned otherwise |

### Order Payment Instrument

Provides data about the payment instrument of an order.

Name in configuration: OrderPaymentInstrument

Parameters:

| Name                  | Meaning                              | Required? |
| --------------------- | ------------------------------------ | --------- |
| order_no              | order number                         | yes       |
| payment_method_id     | ID of the payment method to pay with | no        |
| payment_card_type     | type of the credit card to use       | no        |
| payment_instrument_id | ID of the payment instrument         | no        |

For a provided payment_method_id, the payment_card_type is also considered and the data returned is as complete as possible:

- a credit card payment method returns a partially filled out credit card object
- a bank transfer payment method returns a partially filled out bank transfer object
- a provided payment_instrument_id returns the data of the payment instrument

### Price Adjustment

Provides data of a price adjustment.

Name in configuration: BasketPriceAdjustment

Parameter:

| Name      | Meaning                | Required?                    |
| --------- | ---------------------- | ---------------------------- |
| basket_id | ID of the basket       | yes                          |
| item_id   | ID of the product item | no, if a product_id is given |

## Generic Data Sources

Data source: site

Provides site information, the possible properties of the site object can be checked in the Site documentation from Shop API. Here is an example using name, id, and timezone properties.

```json
"data": {
  "attributes": {
    "sitename": {
      "read": {
        "resource": "Site",
        "path": "/name"
      }
    },
    "siteid": {
      "read": {
        "resource": "Site",
        "path": "/id"
      }
    },
    "sitetz": {
      "read": {
        "resource": "Site",
        "path": "/timezone"
      }
    }
  }
},
"layout": {
  [{
    "id": "siteinfo",
    "condition": "data.siteid === 'SiteGenesis'",
    "width": 12
  }]
},
"widgets": {
  "siteinfo": {
    "type": "attribute_listing",
    "config": {
      "attributes": [
        "sitename",
        "siteid",
        "sitetz"
      ],
      "columns": 2
    }
  }
}
```

<!-- document id=ac6abb24375a3abf3511c94afc651d293a1cd3d3870915fd96b4691af8aa7495 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-hooks.md -->

# Customer Service Center Hooks

Use the Shop API hooks to customize Customer Service Center.

**note:** The Shop API hooks use OCAPI version 17.8 except for <li>dw.ocapi.shop.customer.modifyGETResponse, which uses OCAPI version 18.3.

## Find an Order

| CSC Function  | Resource                                                                                                                                                                                                                                                                                            | Shop API Hooks                                |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Search orders | POST /order_search<ul><li>The Created On (From) and Created On (To) search filter criteria are consolidated into one search filter criteria, Created On, which can define a date range.</li><li>Previously, the two separate search filter criteria were required to filter a date range.</li></ul> | dw.ocapi.shop.order_search.modifyPOSTResponse |
| Open an order | GET /orders/{order_no}                                                                                                                                                                                                                                                                              | dw.ocapi.shop.order.modifyGETResponse         |
| Add a note    | POST /orders/{order_no}/notes                                                                                                                                                                                                                                                                       | dw.ocapi.shop.order.note.modifyPOSTResponse   |

## Create a New Order

| Customer Service Center Function                            | Resource                                                                                                  | Shop API Hooks                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New order                                                   | POST /baskets GET /baskets/{basket_id}                                                                    | <ul><li>dw.ocapi.shop.basket.modifyPOSTResponse</li><li>dw.ocapi.shop.basket.modifyGETResponse</li></ul>                                                                                                                                                                                                                                                                                        |
| Set Customer                                                | PUT /baskets/{basket_id}/customer                                                                         | <ul><li>dw.ocapi.shop.basket.beforePutCustomer</li><li>dw.ocapi.shop.basket.afterPutCustomer</li><li>dw.ocapi.shop.basket.customer.modifyPUTResponse</li></ul>                                                                                                                                                                                                                                |
| Set Billing Address                                         | PUT /baskets/{basket_id}/billing_address                                                                  | <ul><li>dw.ocapi.shop.basket.beforePutBillingAddress</li><li>dw.ocapi.shop.basket.afterPutBillingAddress</li><li>dw.ocapi.shop.basket.billing_address.modifyPUTResponse</li></ul>                                                                                                                                                                                                           |
| Set Shipping Address                                        | PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address                                         | <ul><li>dw.ocapi.shop.basket.shipment.beforePutShippingAddress</li><li>dw.ocapi.shop.basket.shipment.afterPutShippingAddress</li><li>dw.ocapi.shop.basket.shipment.shipping_address.modifyPUTResponse</li></ul>                                                                                                                                                                             |
| Add Product                                                 | POST /baskets/{basket_id}/items                                                                           | <ul><li>dw.ocapi.shop.basket.items.beforePOST</li><li>dw.ocapi.shop.basket.items.afterPOST</li><li>dw.ocapi.shop.basket.items.modifyPOSTResponse</li></ul>                                                                                                                                                                                                                                      |
| Update Product Item (such as quantity and custom properties | PATCH /baskets/{basket_id}/items/{item_id}                                                                | <ul><li>dw.ocapi.shop.basket.beforePatchItem</li><li>dw.ocapi.shop.basket.afterPatchItem</li><li>dw.ocapi.shop.basket.item.modifyPATCHResponse</li></ul>                                                                                                                                                                                                                                   |
| Remove a product item                                       | DELETE /baskets/{basket_id}/items/{item_id}                                                               | <ul><li>dw.ocapi.shop.basket.beforeDeleteItem</li><li>dw.ocapi.shop.basket.afterDeleteItem</li><li>dw.ocapi.shop.basket.item.modifyDELETEResponse</li></ul>                                                                                                                                                                                                                                   |
| Set shipping method                                         | PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method                                          | <ul><li>dw.ocapi.shop.basket.beforePutShippingAddress</li><li>dw.ocapi.shop.basket.afterPutShippingAddress</li><li>dw.ocapi.shop.basket.shipment.shipping_method.modifyPUTResponse</li></ul>                                                                                                                                                                                                    |
| Add Coupon                                                  | POST /baskets/{basket_id}/coupons                                                                         | <ul><li>dw.ocapi.shop.basket.beforePostCoupon</li><li>dw.ocapi.shop.basket.afterPostCoupon</li><li>dw.ocapi.shop.basket.coupon.modifyPOSTResponse</li></ul>                                                                                                                                                                                                                                   |
| Remove Coupon                                               | DELETE /baskets/{basket_id}/coupons/{coupon_item_id}                                                      | <ul><li>dw.ocapi.shop.basket.beforeDeleteCoupon</li><li>dw.ocapi.shop.basket.afterDeleteCoupon</li><li>dw.ocapi.shop.basket.coupon.modifyDELETEResponse</li></ul>                                                                                                                                                                                                                             |
| Add Price Adjustment                                        | POST /baskets/{basket_id}/price_adjustments                                                               | <ul><li>dw.ocapi.shop.basket.beforePostPriceAdjustment</li><li>dw.ocapi.shop.basket.afterPostPriceAdjustment</li><li>dw.ocapi.shop.basket.price_adjustment.modifyPOSTResponse</li></ul>                                                                                                                                                                                                     |
| Delete Price Adjustment                                     | DELETE /baskets/{basket_id}/price_adjustments/{price_adjustment_id}                                       | <ul><li>dw.ocapi.shop.basket.beforeDeletePriceAdjustment</li><li>dw.ocapi.shop.basket.afterDeletePriceAdjustment</li><li>dw.ocapi.shop.basket.price_adjustment.modifyDELETEResponse</li></ul>                                                                                                                                                                                               |
| Submit Basket                                               | POST /orders                                                                                              | <ul><li>dw.ocapi.shop.order.beforePOST</li><li>dw.ocapi.shop.order.afterPOST</li><li>dw.ocapi.shop.order.modifyPOSTResponse</li></ul>                                                                                                                                                                                                                                                           |
| Get Payment Methods                                         | GET /baskets/{basket_id}/payment_methods (first payment selection) GET /orders/{order_no}/payment_methods | <ul><li>dw.ocapi.shop.basket.payment_methods.modifyGETResponse</li><li>dw.ocapi.shop.order.payment_methods.modifyGETResponse</li></ul>                                                                                                                                                                                                                                                          |
| Add Payment Instrument                                      | POST /orders/{order_no}/payment_instruments                                                               | <ul><li>dw.ocapi.shop.order.beforePostPaymentInstrument</li><li>dw.ocapi.shop.order.afterPostPaymentInstrument</li><li>dw.ocapi.shop.order.payment_instrument.modifyPOSTResponse<ul><li>For payment integrations, use dw.order.hooks.PaymentHooks.</li></ul><li>dw.order.payment.authorize</li><li>dw.order.payment.authorizeCreditCard</li><li>dw.ocapi.shop.order.validateOrder</li></ul> |
| Delete Payment Instrument                                   | DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}                                     | <ul><li>dw.ocapi.shop.order.payment_instrument.modifyDELETEResponse</li><li>dw.ocapi.shop.order.validateOrder</li></ul>                                                                                                                                                                                                                                                                         |
| Guide                                                       | all basket resources                                                                                      | <ul><li>dw.ocapi.shop.basket.validateBasket</li></ul>                                                                                                                                                                                                                                                                                                                                           |

## Find Customers

| Customer Service Center Function | Resource                                                                    | Shop API Hooks                                                                                                                                                                          |
| -------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| View Customer                    | GET /customers/{customer_id}                                                | <ul><li>dw.ocapi.shop.customer.modifyGETResponse</li><li>dw.ocapi.shop.customer.modifyGETResponse uses OCAPI version 18.3.</li></ul>                                                    |
| Edit Customer                    | PATCH /customers/{customer_id}                                              | <ul><li>dw.ocapi.shop.customer.beforePatchCustomer</li><li>dw.ocapi.shop.customer.afterPatchCustomer</li><li>dw.ocapi.shop.customer.modifyPATCHResponse</li></ul>                       |
| Create a Customer                | POST /customers                                                             | <ul><li>dw.ocapi.shop.customer.beforePost</li><li>dw.ocapi.shop.customer.afterPost</li><li>dw.ocapi.shop.customer.modifyPOSTResponse</li></ul>                                          |
| Reset Password                   | POST /customers/password_reset POST /customers/{customer_id}/password_reset | <ul><li>dw.ocapi.shop.customers.password_reset.afterPOST</li><li>dw.ocapi.shop.customer.password_reset.afterPOST The AfterPost hook triggers a customer password reset email.</li></ul> |
| Create an Address                | POST /customers/{customer_id}/addresses                                     | <ul><li>dw.ocapi.shop.customer.addresses.beforePOST</li><li>dw.ocapi.shop.customer.addresses.afterPOST</li><li>dw.ocapi.shop.customer.addresses.modifyPOSTResponse</li></ul>            |
| Edit Address                     | PATCH /customers/{customer_id}/addresses/{address_name}                     | <ul><li>dw.ocapi.shop.customer.address.beforePATCH</li><li>dw.ocapi.shop.customer.address.afterPATCH</li><li>dw.ocapi.shop.customer.address.modifyPATCHResponse</li></ul>               |
| Delete Address                   | DELETE /customers/{customer_id}/addresses/{address_name}                    | <ul><li>dw.ocapi.shop.customer.address.beforeDELETE</li><li>dw.ocapi.shop.customer.address.afterDELETE</li></ul>                                                                        |

<!-- document id=0c119e46c7b34ee4659a6ac1da7484576d7f5a015ff31c8a3dcff365f28bd81e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-ui-customization.md -->

# Customer Service Center UI Customization

There are customizable areas in the Customer Service Center UI that can be modified directly in Business Manager.

**note:** Customizable areas aren't localized into languages supported by Business Manager. Customizable areas can be modified and localized as needed.

The customizable areas are composed of forms or views. All labels are obtained from Salesforce B2C Commerce metadata and can be overwritten.

Each customizable area has a default configuration. Modify the configuration as needed. To reset a configuration to the default, delete the modified configuration. However, before resetting the configuration to the default, if you want to save the modified configuration, copy, paste, and save it outside of Business Manager.

Replicate Customer Service Center UI customizations to a target system by checking CSC Settings as one of the Replication Tasks.

An advanced customization lets you reference data from predefined sources.

All attributes follow the naming conventions of OCAPI:

- System attributes are referenced as described in the corresponding Shop API documents. for example: postal_code
- Custom attributes are always marked with the prefix c\_ and have their own namespace, for example: c_HouseNumber

Each configuration contains at least two top-level elements and the version:

- version: specifies the version of the current configuration. When a new version is available, the version is automatically updated.
- areas: is the top-level and outermost configuration that defines the spaces or sections on the presentation layer. The area contains the layout and widgets. The area contains the specific tab layout and is referenced in the tab.
- [layout:](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-csc-layouts.md) specifies the appearance of a customizable area. For example, a form layout defines the fields in the form. The layout contains the widgets.
- [widgets:](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-csc-widgets.md) specifies functional UI elements that are used in the layout. Widgets register widgets and their respective configuration.

For example:

```json
{
  "_v": "4",
  "areas": {},
  "layout": [],
  "widgets": {}
}
```

<!-- document id=f63516b64a518c6c3c63339415b87a7eb99374004bd8ba1f0ed41ff1923114c4 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/customers.md -->

Customers

# Customers

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/customers/customers-oas-v1-public.yaml)

## API Overview

Use the Customers API to search for and manage customer information within a customer list. It also enables you to search for customer groups.

Once you find information for a customer, you can also use the API to manage customer addresses.

The `customerNo` is created when you create a shopper record. You can create a shopper record using the Customers API or Business Manager. For details, see [registerCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=registerCustomer) and [Create and Manage Customer Records](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-customer-records.html?q=create%20customer).

![b2c-commerce-customers-screenshot-1.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-customers-screenshot-1.png)

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include the relevant scope(s) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Related APIs

*   [Shopper Customers](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=Summary) — Shopper-facing registration, login, and profile management.

**Version:** 1.1.4

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/customer/customers/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.customerlists: Customer Lists scope READONLY
    *   Scope sfcc.customerlists.rw: Customer Lists scope
    *   Scope sfcc.customergroups: Customer Groups scope READONLY
    *   Scope sfcc.customergroups.rw: Customer Groups scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### POST Search for customers in a customer list.

`POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search`

Operation ID: `searchCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw).

Search for customers in a customer list. The query attribute specifies a complex query that can be used to narrow down the search. The following list provides searchable attributes:

| Attribute | Type |
| --- | --- |
| customerNo | String |
| firstName | String |
| secondName | String |
| lastName | String |
| suffix | String |
| salutation | String |
| title | String |
| fax | String |
| phoneHome | String |
| phoneBusiness | String |
| phoneMobile | String |
| email | String |
| gender | Integer |
| companyName | String |
| credentials.login | String |
| credentials.enabled | Boolean |

#### Parameters

*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `SearchRequest`.

_Example: CustomerSearchBody_

```
{
  "limit": 2,
  "offset": 50,
  "query": {
    "textQuery": {
      "fields": [
        "email"
      ],
      "searchPhrase": "wleung"
    }
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerSearchResult`.
    
    _Example: CustomerSearchResult_
    
    ```
    {
      "hits": [
        {
          "data": {
            "birthday": "1999-12-31",
            "companyName": "Salesforce",
            "creationDate": "2023-07-21T07:29:39.505Z",
            "credentials": {
              "enabled": true,
              "locked": false,
              "login": "af4ab358-3187-4ec5-82a6-918e0fe8a21f"
            },
            "customerId": "absAzIVSkman3GPpSYluYBbLrB",
            "customerNo": "00000012",
            "email": "w.leung@gmail.com",
            "fax": "123-123-1234",
            "firstName": "Wei",
            "gender": 1,
            "lastModified": "2023-07-21T07:29:39.506Z",
            "lastName": "Leung",
            "phoneBusiness": "123-123-1234",
            "phoneHome": "123-123-1234",
            "phoneMobile": "123-123-1234",
            "preferredLocale": "en-US",
            "salutation": "Dr.",
            "secondName": "J",
            "suffix": "Jr.",
            "title": "Mr."
          },
          "relevance": 4.258296012878418
        }
      ],
      "limit": 1,
      "offset": 0,
      "query": {
        "textQuery": {
          "fields": [
            "email"
          ],
          "searchPhrase": "w.leung@gmail.com"
        }
      },
      "total": 1
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: searchCustomerInCustomerList400_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter",
      "detail": "offset-BAD-REQUEST parameters are not defined in RAML."
    }
    ```
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: searchCustomerInCustomerList401_
    
    ```
    {
      "title": "Invalid Access Token",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token",
      "detail": "The request is unauthorized, the access token is invalid.",
      "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp"
    }
    ```
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: searchCustomerInCustomerList404_
    
    ```
    {
      "title": "Customer List Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-list-not-found",
      "detail": "No customer list with ID 'SiteGenesis-NOT-FOUND' could be found.",
      "listId": "SiteGenesis-NOT-FOUND"
    }
    ```
    

### POST Create a new customer in a customer list.

`POST /organizations/{organizationId}/customer-lists/{customerListId}/customers`

Operation ID: `createCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw).

Create a new customer. The customer is created using the specified credentials and customer information. This action verifies:

*   Login acceptance criteria and uniqueness.
*   Mandatory customer properties.

If the action fails to create the customer, it returns a 400 fault with an appropriate message.

#### Parameters

*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Customer`.

_Example: PostCustomerBody_

```
{
  "credentials": {
    "enabled": true,
    "locked": false,
    "login": "wleung",
    "passwordQuestion": ""
  },
  "lastName": "Leung",
  "customerNo": "00005002"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example: postCustomers_
    
    ```
    {
      "creationDate": "2019-09-23T19:46:07.412Z",
      "credentials": {
        "enabled": true,
        "locked": false,
        "login": "wleung"
      },
      "customerId": "adg2p1zObo8JDt3iXZCNIZBcai",
      "customerNo": "00005001",
      "lastModified": "2019-09-23T19:46:07.417Z",
      "lastName": "Leung"
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### GET Get customer information.

`GET /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}`

Operation ID: `getCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw).

Action to get customer information.

#### Parameters

*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### PUT Create a new customer in a customer list.

`PUT /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}`

Operation ID: `createCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw).

Create a new customer. The customer is created using the specified customer number, credentials, and customer information. This action verifies:

*   Login acceptance criteria and uniqueness.
*   Mandatory customer properties.

If the action fails to create the customer, it returns a 400 fault with an appropriate message.

#### Parameters

*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Customer`.

_Example: PostCustomerBody_

```
{
  "credentials": {
    "enabled": true,
    "locked": false,
    "login": "wleung",
    "passwordQuestion": ""
  },
  "lastName": "Leung",
  "customerNo": "00005002"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._
    
*   **201** Created
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### DELETE Delete a customer from a customer list.

`DELETE /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}`

Operation ID: `deleteCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw).

Deletes the customer, including all related information like the customer addresses.

#### Parameters

*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** No Content
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### PATCH Update a customer in a customer list.

`PATCH /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}`

Operation ID: `updateCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw).

Updates the customer with the specified information. The customer number can be updated, but results in a CustomerNumberAlreadyInUseException if there is another customer with the same customer number.

#### Parameters

*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Customer`.

_Example: PostCustomerBody_

```
{
  "credentials": {
    "enabled": true,
    "locked": false,
    "login": "wleung",
    "passwordQuestion": ""
  },
  "lastName": "Leung",
  "customerNo": "00005002"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example postCustomers: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### GET Get a list of customer addresses.

`GET /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses`

Operation ID: `getAddressesForCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw).

Returns a list of all customer addresses in pages. The default page size is 10 customer addresses.

#### Parameters

*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerAddressResult`.
    
    _Example: addressesGet_
    
    ```
    {
      "data": [
        {
          "addressId": "1",
          "city": "San Francisco",
          "companyName": "Ursa Major Solar",
          "countryCode": "US",
          "creationDate": "2019-09-23T16:14:07.000Z",
          "etag": "d288bfd83f75b23640b4bbab2b0d3f65a5c5e934dab818f2246b7c1aed5672f8",
          "firstName": "Wei",
          "fullName": "Leung",
          "jobTitle": "",
          "lastModified": "2019-09-23T16:23:19.000Z",
          "lastName": "Leung",
          "phone": "415-555-1212",
          "postalCode": "94105",
          "salutation": "Ms",
          "secondName": "",
          "stateCode": "CA"
        }
      ],
      "limit": 1,
      "offset": 0,
      "total": 1
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### POST Add a new customer address.

`POST /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses`

Operation ID: `createAddressForCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw).

Creates a new customer address with the given address information.

#### Parameters

*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CustomerAddress`.

_Example: AddressesBody_

```
{
  "addressId": "2",
  "address1": "123 Trailblazer Ave.",
  "postalCode": "94105",
  "lastName": "Leung",
  "title": "",
  "salutation": "Ms",
  "companyName": "Ursa Major Solar",
  "secondName": "",
  "phone": "415-555-1212",
  "countryCode": "US",
  "city": "San Francisco",
  "address2": "",
  "firstName": "Wei",
  "jobTitle": "",
  "stateCode": "CA"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerAddress`.
    
    _Example: addressesPost_
    
    ```
    {
      "addressId": "3",
      "city": "San Francisco",
      "companyName": "Ursa Major Solar",
      "countryCode": "US",
      "creationDate": "2019-09-23T20:49:38.370Z",
      "etag": "8772fd1c59fed8313a6c1ad260544c116dc0af4bc13941957173244edba47d31",
      "firstName": "Wei",
      "fullName": "Wei Leung",
      "jobTitle": "",
      "lastModified": "2019-09-23T20:49:38.372Z",
      "lastName": "Leung",
      "phone": "415-555-1212",
      "postalCode": "94105",
      "salutation": "Ms",
      "secondName": "",
      "stateCode": "CA"
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### GET Get a customer address.

`GET /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses/{addressId}`

Operation ID: `getAddressForCustomerFromCustomerList`. Security: AmOAuth2 (sfcc.customerlists, sfcc.customerlists.rw).

Action that returns a single customer address from a customer list.

#### Parameters

*   `addressId` (path, string, required) The address ID.  
    Minimum length: 1. Maximum length: 256. Example: `Home`.
*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerAddress`.
    
    _Example: AddressGet_
    
    ```
    {
      "address1": "123 Trailblazer Ave.",
      "address2": "",
      "addressId": "HomeAddress",
      "city": "San Francisco",
      "companyName": "",
      "countryCode": "US",
      "firstName": "Wei",
      "fullName": "Wei Leung",
      "jobTitle": "",
      "lastName": "Leung",
      "phone": "",
      "postalCode": "",
      "postBox": "",
      "salutation": "Ms.",
      "secondName": "",
      "stateCode": "CA",
      "suffix": "",
      "suite": "",
      "title": ""
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### DELETE Delete a customer address.

`DELETE /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses/{addressId}`

Operation ID: `removeAddressForCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw).

Deletes a customer address.

#### Parameters

*   `addressId` (path, string, required) The address ID.  
    Minimum length: 1. Maximum length: 256. Example: `Home`.
*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** No Content
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### PATCH Update a customer address.

`PATCH /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses/{addressId}`

Operation ID: `updateAddressForCustomerInCustomerList`. Security: AmOAuth2 (sfcc.customerlists.rw).

Updates an address of a customer with the given address information.

#### Parameters

*   `addressId` (path, string, required) The address ID.  
    Minimum length: 1. Maximum length: 256. Example: `Home`.
*   `customerNo` (path, string, required) The customer number.  
    Minimum length: 1. Maximum length: 100. Example: `1`.
*   `customerListId` (path, string, required) The customer list ID.  
    Minimum length: 1. Maximum length: 256. Example: `Site1CustomerList`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CustomerAddress`.

_Example AddressesBody: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses request._

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerAddress`.
    
    _Example addressesPost: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customers/{customerNo}/addresses 200 response._
    
*   **400** Bad Request. Returned when a specified parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList400: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    
*   **404** Not Found. This error is thrown when the ID does not match any of the customer group sites or if the ID is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList404: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 404 response._
    

### POST Search for customer groups.

`POST /organizations/{organizationId}/customer-group-search`

Operation ID: `searchCustomerGroup`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw).

Search for customer groups in a given site ID. The query attribute specifies a complex query that can be used to narrow down the search. The following list provides searchable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| description | String |
| type | String |

Note: This endpoint is available with B2C Commerce version 24.2.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `SearchRequest`.

_Example: CustomerSearchBody_

```
{
  "limit": 2,
  "offset": 50,
  "query": {
    "textQuery": {
      "fields": [
        "email"
      ],
      "searchPhrase": "wleung"
    }
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerGroupSearchResult`.
    
    _Example: CustomerGroupSearchResult_
    
    ```
    {
      "limit": 1,
      "hits": [
        {
          "creationDate": "2020-01-09T16:50:32.000Z",
          "description": "Big Spenders",
          "id": "Big Spenders",
          "inDeletion": false,
          "lastModified": "2020-01-09T16:50:32.000Z",
          "memberCount": 109,
          "rule": {
            "description": "Customers who spend more than $1000 in the last month"
          },
          "type": "dynamic"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id"
          ],
          "searchPhrase": "Big"
        }
      },
      "offset": 0,
      "total": 1
    }
    ```
    
*   **400** Bad Request. Returned if the search term in term query does not match any of the customer group or if the query is ill-formed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: searchCustomerGroup400_
    
    ```
    {
      "title": "Customer Group Type Invalid",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter",
      "detail": "The customer group type 'stat' is invalid."
    }
    ```
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example searchCustomerInCustomerList401: same as POST /organizations/{organizationId}/customer-lists/{customerListId}/customer-search 401 response._
    

### GET Get a list of customer groups.

`GET /organizations/{organizationId}/customer-groups`

Operation ID: `getCustomerGroups`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw).

Returns a list of all customer groups for a given site in pages. The default page size is 25 customer groups.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerGroupResult`.
    
    _Example: CustomerGroupResult_
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 50,
      "data": [
        {
          "creationDate": "2020-01-09T16:50:32.000Z",
          "description": "Big Spenders",
          "id": "Big Spenders",
          "lastModified": "2020-01-09T16:50:32.000Z",
          "rule": {
            "description": "Customers who spent more than $1000 in the last month"
          },
          "type": "dynamic"
        },
        {
          "creationDate": "2019-05-15T10:30:00.000Z",
          "description": "VIP Customers",
          "id": "VIP",
          "lastModified": "2020-03-20T14:15:30.000Z",
          "type": "static"
        },
        {
          "creationDate": "2018-01-01T00:00:00.000Z",
          "description": "Everyone",
          "id": "Everyone",
          "lastModified": "2018-01-01T00:00:00.000Z",
          "type": "system"
        }
      ]
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is invalid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: malformedSelector400_
    
    ```
    {
      "title": "Malformed Selector",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector",
      "detail": "The property selector '(invalid' is malformed.",
      "selector": "(invalid"
    }
    ```
    

### PUT Assign multiple customers to a customer group.

`PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members`

Operation ID: `assignCustomerGroupMembers`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw).

Add multiple customers to a (static) customer group. This endpoint assigns the specified customers to the customer group identified by the given ID. Only static customer groups support this operation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `customerGroupId` (path, CustomerGroupId, required) The customer group identifier.
*   `customerNos` (query, array of CustomerNo, required, style: form, explode: false) List of customer numbers to assign or unassign from the customer group.  
    Minimum items: 1. Maximum items: 50.
    
    _Example_
    
    ```
    [
      "00001234",
      "00005678",
      "00009012"
    ]
    ```
    

#### Responses

*   **200** Successfully returned the assigned customer group members.
    
    Media type: `application/json`. Schema: `CustomerGroupMemberResult`.
    
    _Example: AssignMembersSuccess_ Successful assignment of customers to a customer group
    
    Example response after successfully assigning multiple customers to a customer group
    
    ```
    {
      "limit": 3,
      "total": 5,
      "data": [
        {
          "customerNo": "00001234",
          "login": "johndoe",
          "firstName": "John",
          "lastName": "Doe",
          "active": true
        },
        {
          "customerNo": "00005678",
          "login": "janesmith",
          "firstName": "Jane",
          "lastName": "Smith",
          "active": true
        },
        {
          "customerNo": "00009012",
          "login": "bobjones",
          "firstName": "Bob",
          "lastName": "Jones",
          "active": true
        }
      ]
    }
    ```
    
*   **403** Forbidden. The customer group is not a static group.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: customerGroupUnsupportedAssignment403_
    
    ```
    {
      "title": "Customer Group Unsupported Assignment",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-group-unsupported-assignment",
      "detail": "No customer can be assigned to the non-static group 'Unregistered' for site 'RefArch'."
    }
    ```
    
*   **404** Not Found. The customer group does not exist or one or more customers were not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: customerGroupNotFound404_
    
    ```
    {
      "title": "Customer Group Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-group-not-found",
      "detail": "No customer group with ID 'invalidId' for site 'RefArch' could be found."
    }
    ```
    
    _Example: customerNotFound404_
    
    ```
    {
      "title": "Customer Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-not-found",
      "detail": "No customer with number '[\"invalidCustomerNo\"]' for site 'RefArch' could be found."
    }
    ```
    
*   **409** Conflict. The customer group is already in deletion state.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: objectInDeletionConflict409_
    
    ```
    {
      "title": "Object In Deletion Conflict",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/object-in-deletion-conflict",
      "detail": "The request on object '{1}' can't be executed since it's already in the process of being deleted.",
      "objectId": "CustomerGroupInDeletion"
    }
    ```
    

### DELETE Unassign multiple customers from a customer group.

`DELETE /organizations/{organizationId}/customer-groups/{customerGroupId}/members`

Operation ID: `unassignCustomerGroupMembers`. Security: AmOAuth2 (sfcc.customergroups, sfcc.customergroups.rw).

Remove multiple customers from a (static) customer group. This endpoint unassigns the specified customers from the customer group identified by the given ID. Only static customer groups support this operation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `customerGroupId` (path, CustomerGroupId, required) The customer group identifier.
*   `customerNos` (query, array of CustomerNo, required, style: form, explode: false) List of customer numbers to assign or unassign from the customer group.  
    Minimum items: 1. Maximum items: 50.
    
    _Example_
    
    ```
    [
      "00001234",
      "00005678",
      "00009012"
    ]
    ```
    

#### Responses

*   **204** The customers were successfully unassigned from the customer group.
*   **404** Not Found. The customer group does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example customerGroupNotFound404: same as PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members 404 response._
    
    _Example customerNotFound404: same as PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members 404 response._
    
*   **409** Conflict. The customer group is already in deletion state.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example objectInDeletionConflict409: same as PUT /organizations/{organizationId}/customer-groups/{customerGroupId}/members 409 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### CustomerSearchResult

Document representing a customer search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of CustomerSearchHit_, required) The sorted array of search hits. Can be empty.
    
    _Example_
    
    ```
    [
      {
        "customerNo": "D100201",
        "lastName": "Leung"
      }
    ]
    ```
    

_Example_

```
{
  "value": {
    "hits": [
      {
        "data": {
          "birthday": "1999-12-31",
          "companyName": "Salesforce",
          "creationDate": "2023-07-21T07:29:39.505Z",
          "credentials": {
            "enabled": true,
            "locked": false,
            "login": "af4ab358-3187-4ec5-82a6-918e0fe8a21f"
          },
          "customerId": "absAzIVSkman3GPpSYluYBbLrB",
          "customerNo": "00000012",
          "email": "w.leung@gmail.com",
          "fax": "123-123-1234",
          "firstName": "Wei",
          "gender": 1,
          "lastModified": "2023-07-21T07:29:39.506Z",
          "lastName": "Leung",
          "phoneBusiness": "123-123-1234",
          "phoneHome": "123-123-1234",
          "phoneMobile": "123-123-1234",
          "preferredLocale": "en-US",
          "salutation": "Dr.",
          "secondName": "J",
          "suffix": "Jr.",
          "title": "Mr."
        },
        "relevance": 4.258296012878418
      }
    ],
    "limit": 1,
    "offset": 0,
    "query": {
      "textQuery": {
        "fields": [
          "email"
        ],
        "searchPhrase": "w.leung@gmail.com"
      }
    },
    "total": 1
  }
}
```

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### Customer

Person or entity who shops on Commerce Cloud storefronts by creating a shopper account in Commerce Cloud.

*   `birthday` (_string (date)_) The customer's birthday.  
    Example: `1999-12-31`.
*   `companyName` (_string_) The customer's company name.  
    Maximum length: 256. Example: `Ursa Major Solar`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `credentials` (_Credentials_)
*   `customerId` (_string_) The customer's ID. Both registered and guest customers have a customer ID.  
    Maximum length: 28. Example: `wleung`.
*   `customerNo` (_string_, required) The customer's number.  
    Maximum length: 100. Example: `D100201`.
*   `email` (_string_) The customer's email address.  
    Maximum length: 256. Example: `wleung@example.com`.
*   `fax` (_string_) The customer's fax number. The length is restricted to 32 characters.  
    Maximum length: 32. Example: `415-555-1213`.
*   `firstName` (_string_) The customer's first name.  
    Maximum length: 256. Example: `Wei`.
*   `gender` (_integer (int32)_) The customer's gender.  
    Example: `2`.
*   `jobTitle` (_string_) The customer's job title.  
    Maximum length: 256.
*   `lastLoginTime` (_string (date-time)_) The last login time of the customer.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `lastName` (_string_, required) The customer's last name.  
    Maximum length: 256. Example: `Leung`.
*   `lastVisitTime` (_string (date-time)_) The last visit time of the customer.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `phoneBusiness` (_string_) The customer's business phone number.  
    Maximum length: 32. Example: `333-333-3333`.
*   `phoneHome` (_string_) The customer's home phone number.  
    Maximum length: 32. Example: `415-555-1211`.
*   `phoneMobile` (_string_) The customer's mobile phone number.  
    Maximum length: 32. Example: `415-555-1212`.
*   `preferredLocale` (_string_) The customer's preferred locale.  
    Maximum length: 5. Example: `en_US`.
*   `previousLoginTime` (_string (date-time)_) The time when the customer previously logged in.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `previousVisitTime` (_string (date-time)_) The time when the customer previously visited the store.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `primaryAddress` (_CustomerAddress_)
*   `salutation` (_string_) The customer's salutation.  
    Maximum length: 256. Example: `Ms.`.
*   `secondName` (_string_) The customer's second name.  
    Maximum length: 256. Example: `Leung`.
*   `suffix` (_string_) The customer's suffix (for example, "Jr." or "Sr.").  
    Maximum length: 256.
*   `title` (_string_) The customer's title (for example, "Mrs" or "Mr").  
    Maximum length: 256.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CustomerAddressResult

Result document containing an array of customer addresses.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of CustomerAddress_) The array of customer address documents.

### CustomerAddress

Any address that is associated with a customer (billing, shipping, mailing, and so on).

*   `address1` (_string_) The customer's first address.  
    Maximum length: 256. Example: `123 Trailblazer Ave.`.
*   `address2` (_string_) The customer's second address value.  
    Maximum length: 256.
*   `addressId` (_string_, required) The customer address ID.  
    Maximum length: 256. Example: `Home`.
*   `city` (_string_) The customer's city.  
    Maximum length: 256. Example: `San Francisco`.
*   `companyName` (_string_) The customer's company name.  
    Maximum length: 256. Example: `Ursa Major Solar`.
*   `countryCode` (_string_, required) The customer's two-character country code per ISO 3166-1 alpha-2.  
    Maximum length: 2. Example: `US`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `etag` (_string_) The generated eTag representing the state of the customer address.  
    Example: `0267dee58b0ddd9a13f27309470b84f5b2b7e00fa53dfcf400c1f7a5661f319d`.
*   `firstName` (_string_) The customer's first name.  
    Maximum length: 256. Example: `Wei`.
*   `fullName` (_string_) The concatenation of the customer's first, middle, last names, and suffix.  
    Maximum length: 1027. Example: `Wei Leung`.
*   `jobTitle` (_string_) The customer's job title.  
    Maximum length: 256.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `lastName` (_string_, required) The customer's last name.  
    Maximum length: 256. Example: `Leung`.
*   `phone` (_string_) The customer's phone number.  
    Maximum length: 32. Example: `415-555-1212`.
*   `postBox` (_string_) The customer's post box.  
    Maximum length: 256.
*   `postalCode` (_string_) The customer's postal code.  
    Maximum length: 256. Example: `94105`.
*   `salutation` (_string_) The customer's salutation.  
    Maximum length: 256. Example: `Ms.`.
*   `secondName` (_string_) The customer's second name.  
    Maximum length: 256. Example: `Leung`.
*   `stateCode` (_string_) The customer's state.  
    Maximum length: 256. Example: `CA`.
*   `suffix` (_string_) The customer's suffix.  
    Maximum length: 256.
*   `suite` (_string_) The customer's suite.  
    Maximum length: 32.
*   `title` (_string_) The customer's title.  
    Maximum length: 256.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### CustomerGroupSearchResult

Document representing a customer group search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of CustomerGroup_, required) The sorted array of search hits. Can be empty.

_Example_

```
{
  "value": {
    "limit": 1,
    "hits": [
      {
        "creationDate": "2020-01-09T16:50:32.000Z",
        "description": "Big Spenders",
        "id": "Big Spenders",
        "inDeletion": false,
        "lastModified": "2020-01-09T16:50:32.000Z",
        "memberCount": 109,
        "rule": {
          "description": "Customers who spend more than $1000 in the last month"
        },
        "type": "dynamic"
      }
    ],
    "query": {
      "textQuery": {
        "fields": [
          "id"
        ],
        "searchPhrase": "Big"
      }
    },
    "offset": 0,
    "total": 1
  }
}
```

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### CustomerGroupResult

Document representing an unfiltered list of customer groups.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of CustomerGroup_, required) The list of customer groups.

### CustomerGroupId

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `preferred-customers`.

### CustomerNo

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `00001234`.

### CustomerGroupMemberResult

Results containing a list of customer group members

Includes all fields of `ResultBase`.

*   `data` (_array of CustomerGroupMember_, required) List of customer group members.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### CustomerSearchHit

Document representing a customer search hit.

*   `data` (_object_, required) List of found customers.
    
    Includes all fields of `Customer`.
    
*   `relevance` (_number (double)_, required) The hit's relevance score.  
    Example: `1`.

### Credentials

Document representing the credentials of a customer.

*   `enabled` (_boolean_) A flag indicating whether the customer is enabled and can log in.  
    Example: `true`.
*   `locked` (_boolean_) A flag indicating whether the customer account is locked.  
    Example: `false`.
*   `login` (_string_, required) The login of the customer.  
    Maximum length: 256. Example: `wleung`.
*   `passwordQuestion` (_string_) The password question.  
    Maximum length: 256. Example: `Pet Name?`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### CustomerGroup

Document representing a customer group.

*   `creationDate` (_string (date-time)_) The date the customer group was created.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `description` (_string_) Customer Group description.  
    Maximum length: 4000. Example: `Customers who spent more than $1000 in last month`.
*   `id` (_string_, required) Customer Group id.  
    Minimum length: 1. Maximum length: 256. Example: `Big Spenders`.
*   `inDeletion` (_boolean_) Boolean to indicate if the customer group is marked for deletion.  
    Example: `false`.
*   `lastModified` (_string (date-time)_) The date the customer group was last modified.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `memberCount` (_integer (int32)_) Number of members in the customer group  
    Example: `109`.
*   `rule` (_CustomerGroupRule_)
*   `type` (_string_) Customer Group Type.  
    Allowed values: `system`, `dynamic`, `static`. Example: `static`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CustomerGroupMember

*   `customerNo` (_string_, required) Customer number of the customer group member  
    Minimum length: 1. Maximum length: 100. Example: `00001234`.
*   `login` (_string_) Customer login  
    Maximum length: 256. Example: `johndoe`.
*   `firstName` (_string_) Customer's first name  
    Maximum length: 256. Example: `John`.
*   `lastName` (_string_) Customer's last name  
    Maximum length: 256. Example: `Doe`.
*   `active` (_boolean_) Flag indicating whether the customer is active  
    Example: `true`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### CustomerGroupRule

Customer Group Rule

*   `description` (_string_, required) Customer Group Rule description. Describing its conditions in natural language.  
    Example: `Customers who spend more than $1000 in the last month`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=fc0d1b579318251debf9411f91ecb0da96f969652ccc681faa6562e593c7d079 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-customizable-grids.md -->

# Customizable Grids

A customizable grid lets the administrator define how the customer search result appears. Customizable grids consist of columns that define what appears in the particular grid.

The columns contain a title to define the column header manually. If the title is empty, the column header is generated based on the metadata of the attribute defined for that column. If the column contains multiple attributes, the column header remains empty. A layout is defined for each column containing an attribute or an array of attributes that define where the data comes from. Those attributes are resolved against the specific grid data source.

Supported customizable grids are listed in the remaining sections of this guide.

## Customer Search

Source: Customer

```json
{
  "columns": [
    {
      "label": "Name",
      "layout": {
        "layout": [
          { "attribute": "first_name" },
          { "attribute": "last_name", "suppress_new_column": true }
        ]
      }
    },
    {
      "layout": { "attribute": "email" }
    },
    {
      "layout": { "attribute": "company_name" }
    }
  ]
}
```

## Customer Baskets

Source: Basket

```json
{
  "columns": [
    {
      "layout": {
        "attribute": "last_modified"
      }
    },
    {
      "label": "Items",
      "layout": {
        "xpath": "replace(trim(concat(/product_items[1]/product_name , '\n' , /product_items[2]/product_name, '\n' , /product_items[3]/product_name )),'\n',', ')",
        "meta": { "type": "string" }
      }
    }
  ]
}
```

Admins can configure the Customer Baskets grid by defining both system and custom attributes. All columns can contain consolidated content and can have custom labels. The column can be defined with either attribute or xpath, for example:

```json
concat('First Product: ', /product_items[1]/product_name)
```

## Customer Orders

Source: Order

```json
{
  "columns": [
    {
      "label": "Items",
      "layout": {
        "xpath": "replace(trim(concat(/product_items[1]/product_name , '\n' , /product_items[2]/product_name, '\n' , /product_items[3]/product_name )),'\n',', ')",
        "meta": { "type": "string" }
      }
    },
    {
      "layout": {
        "attribute": "creation_date"
      }
    },
    {
      "layout": {
        "attribute": "status"
      }
    }
  ]
}
```

## Customer Address Book

Source: CustomerAddress

```json
{
  "columns": [
    {
      "layout": {
        "attribute": "preferred"
      }
    },
    {
      "layout": {
        "attribute": "full_name"
      }
    },
    {
      "layout": {
        "attribute": "postal_code"
      }
    },
    {
      "layout": {
        "attribute": "city"
      }
    },
    {
      "layout": {
        "attribute": "state_code"
      }
    },
    {
      "layout": {
        "attribute": "phone"
      }
    }
  ]
}
```

## Order Search

Source: Order

```json
{
  "columns": [
    {
      "layout": {
        "attribute": "customer_name"
      }
    },
    {
      "layout": {
        "attribute": "customer_info.customer_no"
      }
    },
    {
      "label": "Items",
      "layout": {
        "xpath": "replace(trim(concat(/product_items[1]/product_name , '\n' , /product_items[2]/product_name, '\n' , /product_items[3]/product_name )),'\n',', ')",
        "meta": { "type": "string" }
      }
    },
    {
      "layout": {
        "attribute": "creation_date"
      }
    },
    {
      "layout": {
        "attribute": "status"
      }
    }
  ]
}
```

<!-- document id=88db8dad065e752d1ae6560bdd1dcbd3042a89f5639527bbe9f327672f3fff2c url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-component-extend-upgrade.md -->

# Customization Best Practices and Upgrades

When you customize the built-in storefront template code, including React components, hooks, and functions, and Salesforce later releases a new template version, you need a strategy to adopt the improvements while preserving your customizations. Select the approach that best fits your team's workflow and the extent of your customizations.

## Customizing Existing Components and Code

If you customized storefront template code, use one of these approaches for upgrading the storefront template.

### Minor Updates: Merge Updates in Storefront Code

If you've made minor modifications to existing storefront code, including components, hooks, and functions, and want to adopt Salesforce updates, merge the changes directly. For straightforward cases with minimal code conflicts, a supervised Git merge can be sufficient. Carefully review all changes during the merge process to ensure your customizations are preserved while incorporating Salesforce improvements.

#### When to Use This Method

- Customizations are minimal and code conflicts are straightforward to resolve.
- Maintain a single version of each component, hook, or function.
- Comfortable with Git merge workflows.

#### Trade-offs

Advantages:

- Automatically receive Salesforce improvements and bug fixes.
- Maintain a single code version without duplication.
- Stay in sync with upstream changes.
- Simpler project structure with fewer files to manage.

Disadvantages:

- Potential merge conflicts when Salesforce releases updates.
- Requires immediate conflict resolution to adopt updates.
- Can require rework of customizations if Salesforce makes significant structural changes.
- Less predictable upgrade process.

### Major Updates: Maintain Separate Code Copies

For drastic customizations or full replacements, maintain customized copies of code, including components, hooks, and functions, in a separate directory and use Vite's path aliases to override the built-in implementations site-wide. This approach prevents Git conflicts and simplifies adoption of upstream template updates.

#### When to Use This Method

- Extensive customizations exist.
- Merge conflicts are complex or frequent.
- Prefer explicit control over when to adopt Salesforce updates.
- Minimize disruption during Storefront Next releases.

#### Implementation Steps

1. Create a separate directory for your customized code (for example, `/customizations`).
2. Copy the code you want to customize to this directory.
3. Modify your copy as needed.
4. Configure Vite to use your custom code instead of the original.

#### Vite Configuration Example

Use Vite's `resolve.alias` configuration to replace the original component with your customized version.

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import { reactRouter } from "@react-router/dev/vite";
import tailwindcss from "@tailwindcss/vite";
import tsconfigPaths from "vite-tsconfig-paths";
import storefrontNextPlugin from "@salesforce/storefront-next-dev";
import path from "path";

export default defineConfig({
  plugins: [reactRouter(), tailwindcss(), tsconfigPaths(), storefrontNextPlugin()],
  resolve: {
    alias: {
      // Replace the original component with your customized version
      "@/components/ProductCard": path.resolve(__dirname, "./customizations/ProductCard"),
    },
  },
});
```

For more information about Vite's aliasing capabilities, see the [Vite resolve.alias documentation](https://vite.dev/config/shared-options.html#resolve-alias).

#### Trade-offs

Advantages:

- Eliminates Git merge conflicts when Salesforce updates the storefront template.
- Original code remains untouched.
- Clear separation between built-in and customized code.

Disadvantages:

- You don't automatically receive Salesforce improvements.
- You must manually merge Salesforce updates into your customized copies.
- Requires maintaining awareness of upstream changes.

## Adding Net New Custom Components

When building entirely new components that don't replace existing ones, import your custom component to a page for use in a single storefront. Alternatively, to use the component in multiple storefronts or distribute it to customers, build an extension for the component.

### Single-Use Component: Import the Component

For a custom component that's used only in one storefront, import it and add it to the containing page.

```typescript
// In your page component
import { MyCustomComponent } from "@/components/MyCustomComponent";

export default function ProductPage() {
  return (
    <>
      <ProductCard />
      <MyCustomComponent />
    </>
  );
}
```

#### When to Use This Method

- A new component is used in one storefront only.
- Comfortable with the additional task of importing the component after an upgrade.

#### Trade-offs

Advantages:

- Simple approach with no additional tooling, configuration, or build pipeline required.
- Full control over the component's lifecycle and rendering behavior.
- Straightforward to debug because the component is a standard React import in your codebase.
- Changes are immediately visible and traceable in your project's file structure.
- No dependency management or versioning overhead beyond your existing project setup.

Disadvantages:

- Not scalable when the same component is needed in multiple storefronts—each storefront requires its own copy and manual sync.
- The import must be re-added to any new or restructured pages after a template upgrade, which is easy to miss.
- No centralized version control for the component across storefronts, which can lead to diverging implementations over time.
- If the component eventually needs to be shared, migrating to the extension model requires significant rework.

### Multi-Use Component: Use the Extension Model

Use the Storefront Next extension mechanism and UI target functionality when building reusable solutions that you want to package and deploy across multiple customers. This approach is designed for independent software vendors (ISVs) and partners. To learn about extensions, see the [Extensions Directory](https://github.com/SalesforceCommerceCloud/storefront-next-template/tree/main/src/extensions) readme in GitHub.

**important:** The extension model isn't intended for customizing individual built-in templates in your storefront. For template customization, use the other methods described in this guide.

#### When to Use This Method

- A new component is used in multiple storefronts or is distributed to customers.
- Willing to implement extensions.

#### Trade-offs

Advantages:

- Clean upgrade process because custom components are fully separated from the built-in storefront template code—template upgrades don't affect your extension.
- No Git merge conflicts when Salesforce releases new versions of the storefront.
- A single extension can be deployed consistently across multiple storefronts or distributed to customers, eliminating duplicated code.
- Extensions are versioned and packaged independently, making it easier to roll out updates and maintain backward compatibility.
- The UI target mechanism provides stable integration points that are explicitly maintained by Salesforce across releases.

Disadvantages:

- Requires learning the Storefront Next extension model and UI target API, which adds upfront complexity before you can build anything.
- More files and configuration to manage compared to a simple import.
- Extension packaging and deployment adds steps to your release workflow that aren't present when using direct imports.
- Debugging can be harder because the extension is transpiled dynamically and is further removed from the page component.

<!-- document id=8d795f180d69db546da4181d3b170bdefeb0cf6e3a1c2f86062558db99b8c46e url=/developer/current/en-us/commerce-cloud/commerce-api/guides/extensibility_via_hooks.md -->

# Customization with Hooks

Hooks allow you to alter and extend the behavior of existing Shopper API resources using the Script API.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


For more information on Script API, refer to the following documentation:

- [Salesforce B2C Commerce Site Development](https://help.salesforce.com/s/articleView?id=cc.b2c_getting_started.htm&type=5)
- [Development Components](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-components.html)
- [Cartridges](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-cartridges.html)
- [Scripts](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-working-with-scripts.html)

## Available Hooks

Resources can provide the following hooks:

- `before`: Useful for custom validation, for example, if you're sending an address that you want to validate.
- `after`: Useful for changing data, for example: you're sending payment information that you need to verify with an external system and then persist it.
- `modifyResponse`: Modify what is contained in the response, for example: If there’s an attribute that you don't need or an additional attribute that you do need, use a response hook to modify what is obtained from an external system.

![Available hooks in B2C Commerce system configuration](https://developer.salesforce.com/docs/media/commerce-api/availableHooks.png)

GET requests support `before` and `modifyResponse` hooks. State changing HTTP methods like POST, PATCH, PUT, and DELETE additionally support `after` hooks. The latter also writes transactions to the database accordingly.

Not all Shopper APIs support hooks. The following table shows hook support by API:

| Shopper API | Hooks | Notes |
|-------------|-------|-------|
| Shopper Baskets | Yes | Extensive hook coverage: basket, billing address, coupons, items, payment instruments, shipments, price adjustments, taxes |
| Shopper Orders | Yes | Order creation, payment instruments, taxes |
| Shopper Customers | Yes | Authentication, registration, addresses, payment instruments, product lists |
| Shopper Products | Yes | Product and category retrieval |
| Shopper Search | Yes | Product search and search suggestions |
| Shopper Promotions | Yes | Promotion retrieval |
| Shopper Gift Certificates | Yes | Gift certificate retrieval |
| Shopper Stores | Yes | Store retrieval |
| Shopper SEO | Yes | URL mapping |
| Shopper Context | Yes | Context creation and updates (site-level, requires B2C Commerce 24.7+) |
| Shopper Configurations | Yes | Configuration retrieval |
| Shopper Experience | **No** | Uses its own [Page Designer customization](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html) |
| Shopper Login (SLAS) | **No** | Authentication hooks use `dw.ocapi.shop.auth.*` (see [Hook Method Details](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hook-method-details.md#authentication)) |
| Shopper Payments | **No** | — |
| Shopper Custom Objects | **No** | — |
| Shopper Consents | **No** | — |

For detailed method signatures and parameters, see [Hook Method Details](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hook-method-details.md).

**note:** Hook extension point names use the historical `dw.ocapi.shop.*` prefix. The same hooks are called for both SCAPI and OCAPI requests.

## Hooks Prerequisites

To use hooks for Commerce API, first enable it in Business Manager for your B2C Commerce instance.

Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png), select **Administration > Global Preferences > Feature Switches**, and turn on API hook execution.

**note:** To enable, you must have the Account Manager role of `Business Manager Administrator` for the instance.

## Register Hooks

1. Place a `package.json` file in the top-level directory of your cartridge.
2. In the `package.json` file, define the `hooks` property to the path of the `hooks.json` configuration file. This path is relative to the directory containing the `package.json` file:
   ```json
   {
     "hooks": "./cartridge/scripts/hooks.json"
   }
   ```
3. In the `hooks.json` file, configure an array with the mappings of hooks to their script files with paths relative to the `hooks.json` file:
   ```json
   {
     "hooks": [
       {
         "name": "dw.ocapi.shop.basket.billing_address.beforePUT",
         "script": "./basket_hook_scripts.js"
       },
       {
         "name": "dw.ocapi.shop.basket.billing_address.afterPUT",
         "script": "./basket_hook_scripts.js"
       }
     ]
   }
   ```
4. For site specific use, register the cartridge to each appropriate site in Business Manager. To customize organization-level resources across _all_ sites, such as libraries, register the cartridge to the Business Manager site.

## Hook Scripts

Hook scripts are loaded as CommonJS modules. Hook functions must be exported. The exported name must match the name of the hook, without the package qualification. For example, the `dw.ocapi.shop.basket.billing_address.beforePUT` hook is exported as `beforePUT`:

```javascript
//  basket_hook_scripts.js
var Status = require("dw/system/Status");
var HookManager = require("dw/system/HookMgr");

exports.beforePUT = function (basket, doc) {
  // Detect whether the address is valid.
  var isValidAddress = true;
  if (isValidAddress) {
    return new Status(Status.OK);
  }
  return new Status(Status.ERROR);
};

exports.afterPUT = function (basket, doc) {
  // Calculate the basket by calling the convenience hook, which returns a status object.
  var status = HookManager.callHook("dw.order.calculate", "calculate", basket);
  return status;
};

exports.calculate = function (basket) {
  return new Status(Status.OK);
};
```

For each hook your code **MAY** return a `Status` object to the server. If the status is `OK`, the server continues processing. If the status is `ERROR`, representing a handled exception, the server stops further processing, **rolls back the transaction and** responds with an HTTP 400 Bad Request fault. When an `ERROR` occurs, the server returns a fault to the caller, containing information like the error code, message, and details from the `Status` object. Uncaught exceptions in your code including the errors you throw cause an HTTP 500 Internal Error fault; in this case, the server rolls back the transaction.

Hooks for Shopper API extension points that return a value will **SKIP** the system implementation of the hook and any subsequent registered hooks for that extension point. To make sure that the system implementation of a hook and any subsequent registered hooks for an extension point are not skipped, it is recommended that Shopper API hooks return nothing to allow important functions like the cart calculate hook to be executed.

Hooks for **custom** extension points will always execute all registered hook points regardless of their return value.

When an `ERROR` occurs, the server returns an [RFC IETF rfc7807](https://datatracker.ietf.org/doc/html/rfc7807) **ErrorResponse** to the caller, containing information like the error code, message, and details from the `Status` object.

If your hook code does not return a `Status` object, **multiple registered hook scripts might be executed**, including the overridden base implementation. The `Status` object or value returned by these hooks will then be returned instead.

### Pass Data Between Hooks

A single request can call multiple hooks. For example: adding a new [payment instrument to a basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addPaymentInstrumentToBasket) calls:

- `dw.ocapi.shop.basket.payment_instrument.beforePOST`
- `dw.ocapi.shop.basket.payment_instrument.afterPOST`
- `dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse`

To pass data between hooks, use [`request.custom`](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_Request.html). JavaScript objects added to the request are available in subsequent hooks.

For example, to call a 3rd party payment processor **inside the transaction** of adding a new payment instrument to the basket, make this call within the `dw.ocapi.shop.basket.payment_instrument.afterPOST` hook (to make sure that any errors roll back the transaction). After calling the payment service provider to initialize the payment request, return the relevant data to the client in the `dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse` hook. To do this, add relevant data to the `request.custom` container to be handled by the `modifyPOSTResponse` hook.

```javascript
// dw.ocapi.shop.basket.payment_instrument.afterPOST
exports.afterPOST = function (order, paymentInstrumentRequest) {
  //...
  request.custom.paymentIntentID = callPaymentService();
};
// dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse
exports.modifyPOSTResponse = function (basket, basketResponse, paymentInstrumentRequest) {
  // retrieve payment instrument created in this hook execution
  var addedPayment = basketResponse.paymentInstruments.toArray().filter(function (instr) {
    return instr.paymentMethodId === paymentInstrumentRequest.paymentMethodId;
  })[0];
  addedPayment.c_paymentIntentID = request.custom.paymentIntentID;
};
```

## Sample Hooks Collection

As a result of many projects with customers, our community is maintaining a hook collection with many useful implementations to extend functionality or even provide new functionality. The hooks in the community collection cover a wide range of practical use cases.

For more information, check out the [OCAPI Hooks Collection](https://github.com/SalesforceCommerceCloud/sfcc-hooks-collection/tree/main/commerce-cloud-code/plugin_hooktacular/cartridge/scripts) on the Salesforce Commerce Cloud GitHub repository.

## Calculate Hook

Use the Calculate hook, `dw.order.calculate`, to implement customized basket calculation logic. It can be used as the single place for basket calculation and recalculation. This hook provides a default implementation, which can be overridden.

The default logic of the following hooks implicitly call this hook:

- dw.ocapi.baskets.actions.afterMerge
- dw.ocapi.baskets.actions.afterTransfer
- dw.ocapi.shop.basket.afterPATCH
- dw.ocapi.shop.basket.afterPOST
- dw.ocapi.shop.basket.agent.afterPUT
- dw.ocapi.shop.basket.billing_address.afterPUT
- dw.ocapi.shop.basket.coupon.afterDELETE
- dw.ocapi.shop.basket.coupon.afterPOST
- dw.ocapi.shop.basket.customer.afterPUT
- dw.ocapi.shop.basket.gift_certificate_item.afterDELETE
- dw.ocapi.shop.basket.gift_certificate_item.afterPATCH
- dw.ocapi.shop.basket.gift_certificate_item.afterPOST
- dw.ocapi.shop.basket.item.afterDELETE
- dw.ocapi.shop.basket.item.afterPATCH
- dw.ocapi.shop.basket.items.afterPOST
- dw.ocapi.shop.basket.payment_instrument.afterDELETE
- dw.ocapi.shop.basket.payment_instrument.afterPATCH
- dw.ocapi.shop.basket.payment_instrument.afterPOST
- dw.ocapi.shop.basket.price_adjustment.afterDELETE
- dw.ocapi.shop.basket.price_adjustment.afterPATCH
- dw.ocapi.shop.basket.price_adjustment.afterPOST
- dw.ocapi.shop.basket.reference.afterPOST
- dw.ocapi.shop.basket.shipment.afterDELETE
- dw.ocapi.shop.basket.shipment.afterPATCH
- dw.ocapi.shop.basket.shipment.afterPOST
- dw.ocapi.shop.basket.shipment.shipping_address.afterPUT
- dw.ocapi.shop.basket.shipment.shipping_method.afterPUT
- dw.ocapi.shop.basket.storefront.afterPUT
- dw.ocapi.shop.order.beforePOST
- dw.ocapi.shop.order.beforePUT

The following code snippet shows a sample call:

```javascript
dw.system.HookMgr.callHook("dw.order.calculate", "calculate", basket);
```

In this sample call, the parameters are:

- `"dw.order.calculate"` - the extension point to call
- `"calculate"` - the script function to call
- `basket` - the basket to be calculated

**note:** SiteGenesis uses the default implementation of the `dw.order.calculate` hook for basket calculation logic.

## Shopper Context and Hooks

With B2C Commerce version 24.7, upload Shopper Context hooks at the site level by uploading a site-specific cartridge. When invoking site-specific hooks, you must provide a `siteId`.

**note:** If you do not provide a `siteId`, no error message is returned, but the site-specific hooks are not called. For details, see [createShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=createShopperContext) and [updateShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=updateShopperContext).

## Constraints and Best Practices

Using hooks with the B2C Commerce API (SCAPI) is similar to using hooks with OCAPI, but there are differences developers must be aware of. When you enable and maintain hooks, the _same hooks_ are called for both SCAPI and the related OCAPI endpoints, so it’s possible to write a hook that is used for both. This is important if you use both API frameworks for your client applications.

Use `request.isSCAPI()` to determine SCAPI or OCAPI usage, especially if you’re already using the calculate hook in the context of controllers and use transactions in that hook, as that breaks SCAPI.

### Conditional Behaviour

#### Custom Query Parameter

To add conditional behavior to a hook, use custom query string parameters. Parameters must be prefixed with `c_`:

```js
const Status = require("dw/system/Status");

exports.beforeGET = function () {
  const isRequiredParameterPresent = request.httpParameterMap.get("c_required");
  if (!isRequiredParameterPresent) {
    return new Status(Status.Error);
  }
};
```

### Custom Headers

SCAPI supports custom HTTP request and response headers for diagnostic and informational purposes.

**important:** - Custom headers must be prefixed with `c_`.
- Do not use custom headers to implement conditional behavior, because custom headers are not considered when constructing a cache key. For details, see [SCAPI Caching.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md)
- Never use custom request headers in a way that affects the response body. Custom headers are only intended for diagnostic or informational purposes, such as logging.

The following example logs an error message for a required parameter value missing in the request header:

```js
const Logger = require("dw/system/Logger");

exports.beforeGET = function logClientVersion() {
  const customClientVersion = request.httpHeaders.get("c_client_version");
  if (customClientVersion) {
    Logger.info("Client Version: " + customClientVersion);
  } else {
    Logger.error("Missing required header: c_client_version");
  }
};
```

The following example provides a sample custom response header:

```js
const response = require("dw/system/Response");

exports.afterGET = function sendCustomResponseHeader() {
  const customClientVersion = request.httpHeaders.get("c_client_version");
  if (customClientVersion) {
    response.setHttpHeaders("c_client_version_response", customClientVersion);
  }
};
```

### Custom Validation with Hooks

You can use SCAPI and OCAPI Hooks to implement custom validation logic to parse and handle errors.

For example, to use a hook to add custom validation of shipping addresses:

```js
const Status = require("dw/system/Status");

// dw.ocapi.shop.basket.shipment.shipping_address.beforePUT
exports.beforePUT = function shipperAddressValidationBeforePut(address) {
  const isValidAddress = myFancyAddressValidationLookup(address);
  if (!isValidAddress) {
    const status = new Status(Status.ERROR);
    status.addDetail("validation_error", "Bad Shipping Address");
    return status;
  }
};
```

Use `Status.addDetail(key, value)` to add details to the error that the client can parse and use. For additional details, see [Class Status.](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_Status.html#dw_system_Status_addDetail_String_Object_DetailAnchor)

If `isValidAddress` is false, SCAPI returns a HTTP 400 response with the content type: `application/problem+json`:

```json
{
  "title": "Hook Status",
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/hook-status",
  "detail": "An error occurred in ExtensionPoint 'dw.ocapi.shop.category.beforeGET'.",
  "extensionPoint": "dw.ocapi.shop.category.beforeGET",
  "statusCode": "ERROR",
  "statusMessage": "ERROR",
  "statusDetails": {
    "validation_error": "Bad Shipping Address"
  }
}
```

### Hook Error Handling

#### Unhandled Exception

If your hook raises an unhandled exception or error (network error, code syntax error), then an HTTP 500 response is returned:

```json
{
  "title": "Hook Internal Server Error",
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/hook-internal-server-error",
  "detail": "Hook Execution Error"
}
```

#### Circuit Breaker

The Hook Circuit Breaker protects the system from excessive hook execution failures. If your hook generates too many errors, the circuit breaker is activated and returns an HTTP 503 response:

```json
{
  "title": "Hook Circuit Breaker",
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/hook-circuit-breaker",
  "detail": "The ExtensionPoint 'dw.ocapi.shop.category.beforeGET' failure rate was above the threshold of '50 %'.",
  "extensionPointName": "dw.ocapi.shop.category.beforeGET",
  "threshold": "50"
}
```

For more information, see [Hook Circuit Breaker](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hookcircuitbreaker.html).

#### Track Hook Execution Errors

If a hook errors during processing, the request will fail. You can track hook errors with [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5). Configure a search using the `LCQL` query `category: ( com.demandware.wapi.servlet.ShopRestServlet ) AND stackTrace: ( HookInvocationException )`. Alternatively, use the [Correlation ID](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id) associated with the failing request.

#### Timeouts

All SCAPI responses must be returned within a specified timeout period. including the execution of any hooks that are applied. For details, see [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.md).

For details on timeout value errors, see [Error Response Codes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html#504-gateway-timeout).

### ModifyResponse Hook Restrictions

`modifyResponse` hooks are a powerful way to create a response that best fits the needs of the application. Add additional information to objects, or provide a more UI-friendly property set to improve the consumption on the client application.

Additional properties must be added only as custom properties (`c_` properties).

### Hooks and SCAPI Caching

When you enable caching for endpoints that use SCAPI hooks, the hook logic is executed by the application server and the result is cached. Neither the application server logic nor custom hook logic is executed again until the object expires from the cache. For details, see [SCAPI Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).

### Taxes APIs and Hooks

Basket calculations built into the B2C Commerce backend are enabled for determining basket information. SCAPI endpoints allow the manipulation of tax information on the basket.

With B2C Commerce 24.5, the following endpoints are supported with hooks enabled:

- `/checkout/baskets/{}/taxes`
- `/checkout/orders/{}/taxes`
- `/checkout/baskets/{}/items/{}/taxes`

The following Script API methods are available to support the SCAPI external taxation APIs with hooks:

- [dw.order.LineItemCtnr#isExternallyTaxed](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_order_LineItemCtnr.html#dw_order_LineItemCtnr_isExternallyTaxed_DetailAnchor): Returns `true` if the basket was created with `taxMode = external`.
- [dw.order.TaxMgr#applyExternalTax](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_order_TaxMgr.html#dw_order_TaxMgr_applyExternalTax_Basket_DetailAnchor): Applies externally set tax rates to the given basket. Use when `dw.order.LineItemCtnr#isExternallyTaxed` returns `true`.

The following endpoint is not supported with hooks enabled. Calling this endpoint with hooks enabled results in a [HTTP 409](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409) error response from the request.

- `/checkout/baskets/{basketId}/price-books`

<!-- document id=ea2676a757d7c8a6cf2354546cf576e68529fe9b3e291d977b4fb7418c45b770 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-create-checkout-component.md -->

# Customize a Checkout Component for a B2B or B2C Store (LWR)

You can customize checkout components to extend the default checkout processing for a B2B or B2C store created with an LWR template.

## Custom Component Placement

Custom components can be added anywhere in the checkout workflow, which is designed with a nested hierarchy. This hierarchy is structured into three primary levels: a layout component, section components, and child components. Additionally, certain components like the Place Order Button and Checkout Notification components are directly placed on the Checkout Page. For more information, see [Checkout Component Hierarchy](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-component-hierarchy.htm).

## Integration and Communication

Before implementing a custom checkout component, understand how the component will integrate and communicate within the established checkout hierarchy.

- On the checkout page for a B2B or B2C store created with an LWR template, child checkout components implement the `useCheckoutComponent` mixin interface to integrate with the checkout process of form validation and the
  synchronization of external API validations. See [UseCheckoutComponent Interface](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-checkoutsavable.htm).
- The checkout component communication framework supports the interaction between components, enabling data sharing and event handling that are crucial for a dynamic and responsive checkout experience. Two checkout layout options and corresponding processing flows are supported: one-page and accordion. For details, See [Checkout Component Communication](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-component-communication.htm).

## Considerations

**note:** Requests that modify cart or checkout resources must be executed sequentially. Concurrent requests that modify WebCart or related records cause Version Mismatch Exceptions or Checkout Conflict errors. Ensure each request completes before sending the next.

## Example

The sample Terms and Conditions Component demonstrates how to implement a custom checkout component, including the four necessary files. To get started, see [Sample Custom Checkout Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-sample-checkout-component.htm).

<!-- document id=b6cb58fdb550ad11e0eda9b550a9826f4a62129249a7bd1bea79a8a4c935e22b url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/create-a-custom-component.md -->

# Customize a Component with Template Extensibility

In this tutorial, we'll use [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html) to create a custom component for a site. In this example, we'll create a custom footer. Because a footer is an existing component in the base template and we don’t want to change the page layout, we’ll override the footer at the component level.

For more guidance, see this documentation: [Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md#template-extensibility-best-practices) and [Troubleshoot](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md#troubleshoot-template-extensibility).

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

**tip:** Use the headings on the right side of the page to move through this tutorial.

## Prerequisite

To complete this tutorial, do either of these:

1. Use a project created with PWA Kit version 3.x.

   or

2. If you don’t have a project, create a PWA Kit project by running:

   `npx @salesforce/pwa-kit-create-app@latest ——outputDir $PATH/TO/NEW/LOCAL/PROJECT`


## 1. Create Files to Override the Defaults

<style>
ul.no-bullets {
    list-style-type: "a. ";
}
</style>

<ul type="a">
  <li> Under <code>overrides/app</code>, create a folder called <code>components</code>.</li>
  <li> In the <code>components</code> folder, create a folder called <code>footer</code>.</li>
  <li> In the <code>footer</code> folder, create a file called <code>index.jsx.</code> </li>
</ul>

The new folders and file have this structure:

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/footer-folder.png)

## 2. Create a Custom Footer

Add this code to `overrides/components/footer/index.jsx`:

```jsx
import React from "react";

import {
  Box,
  Container,
  Stack,
  Text,
  Link,
  Icon,
  Input,
  Button,
  useColorModeValue,
} from "@chakra-ui/react";
import {
  SocialFacebookIcon,
  SocialTwitterIcon,
  SocialInstagramIcon,
} from "@salesforce/retail-react-app/app/components/icons";

const Footer = () => {
  return (
    <Box
      bg={useColorModeValue("gray.50", "gray.900")}
      color={useColorModeValue("gray.700", "gray.200")}
    >
      <Container as={Stack} maxW={"6xl"} py={10}>
        <Stack direction={{ base: "column", md: "row" }} spacing={4}>
          <Link href="/about">About Us</Link>
          <Link href="/contact">Contact</Link>
          <Link href="/faq">FAQ</Link>
        </Stack>
        <Stack
          direction={{ base: "column", md: "row" }}
          justifyContent={"space-between"}
          alignItems={"center"}
        >
          <Text>
            © {new Date().getFullYear()} Your Company Name. All rights reserved
          </Text>
          <Stack direction={"row"} spacing={6}>
            <Icon as={SocialFacebookIcon} />
            <Icon as={SocialTwitterIcon} />
            <Icon as={SocialInstagramIcon} />
          </Stack>
        </Stack>
        <Stack
          direction={{ base: "column", md: "row" }}
          spacing={4}
          mt={10}
          alignItems={"center"}
        >
          <Text>Subscribe to our newsletter</Text>
          <Input placeholder="Your email address" />
          <Button>Subscribe</Button>
        </Stack>
      </Container>
    </Box>
  );
};

export default Footer;
```

## 3. Preview Your Homepage

<style>
ul.no-bullets {
    list-style-type: "a. ";
}
</style>

<ul type="a">
  <li> Run <code>npm start</code>.</li>
  <li> Go to <a href=http://localhost:3000/my-new-route> http://localhost:3000</a>.</li>
</ul>
On the homepage, the footer looks similar to the one shown below. For example, the background color and wording are customized.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/new-footer.png)

## 4. Deploy Your Bundle

<style>
ul.no-bullets {
    list-style-type: "a. ";
}
</style>

<ul type="a">
  <li> Make sure that your project includes the <a href=https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html#required-project-file> Required Project Files</a> in the <code>overrides</code> folder.</li>
  <li><a href=https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html>Deploy your bundle</a>.</li>
</ul>

## See Also

- [Template Extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html)
- [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.html)

<!-- document id=3b83c33819d00fb8ae2f4a9634562883a1ee715e144e8a91fb47b466ae075b55 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/customize-a-page.md -->

# Customize a Page with Template Extensibility

Let’s imagine that you want to add a component to a page and there’s no existing component that can be overridden. Page-level extensibility solves this problem. In this tutorial, we’ll use [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html) to customize a product detail page (PDP) by adding a component to the page. In this example, we’ll add a promotional banner to the PDP.

For more guidance, see this documentation: [Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md#template-extensibility-best-practices) and [Troubleshoot](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md#troubleshoot-template-extensibility).

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

**tip:** Use the headings on the right side of the page to move through this tutorial.

## Prerequisite

To complete this tutorial, do either of these:

1. Use a project created with PWA Kit version 3.x.

   or

2. If you don’t have a project, create a PWA Kit project by running:

   `npx @salesforce/pwa-kit-create-app@latest ——outputDir $PATH/TO/NEW/LOCAL/PROJECT`


## 1. Create Files to Override Defaults

<style>
ul.no-bullets {
    list-style-type: "a. ";
}
</style>

<ul type="a">
  <li> Under <code>overrides/app/components</code>, create a folder called <code>banner.</code></li>
  <li> In the <code>banner</code> folder, create a file called <code>index.jsx.</code></li>
  <li> Under <code>overrides/app/pages</code>, create a folder called <code>product-detail.</code>.</li>
  <li> In the <code>product-detail</code> folder, create a file called <code>index.jsx.</code> </li>
</ul>

The new folders and files have this structure:

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/banner-folder.png)

## 2. Add a Product Detail Route

Add a product detail route to the list of of routes in `overrides/app/routes.jsx`:

```jsx
const routes = [
  {
    path: "/",
    component: Home,
    exact: true,
  },
  {
    path: "/my-new-route",
    component: MyNewRoute,
  },
  // Add a product detail route.
  {
    path: "/product/:productId",
    component: ProductDetail,
  },
  ..._routes,
];
```

## 3. Create a Custom Banner

Add this code to `overrides/app/components/banner/index.jsx`:

```jsx
import React from "react";
import { Box, Flex, Text } from "@chakra-ui/react";
import Link from "@salesforce/retail-react-app/app/components/link";
const BannerWithImage = () => {
  return (
    <Link to="/category/womens" bg="teal.200">
      <Box py={4} maxH="150px" overflow="hidden">
        <Flex
          maxW="1200px"
          mx="auto"
          align="center"
          justify="center"
          position="relative"
        >
          <Text fontSize="2xl" fontWeight="bold" color="black">
            Flash Sale on Women's Clothes. Up to 50% Off.
          </Text>
        </Flex>
      </Box>
    </Link>
  );
};

export default BannerWithImage;
```

## 4. Create a Custom PDP

Add the code below to `overrides/app/pages/product-detail/index.jsx`.

We want to keep the PDP’s current layout and only add a component to the page. So we’ll reuse the [code from base template](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/app/pages/product-detail/index.jsx) by copying it into the newly created `index.jsx` file. Then we can customize the code as we see fit.

In this example:

- On **line 5**, we’ll import a `BannerWithImage` component from the banner folder.
- On **line 333**, we’ll add the `BannerWithImage` component at the top of the page.

```jsx
import React, { Fragment, useCallback, useEffect, useState } from "react";
import PropTypes from "prop-types";
import { Helmet } from "react-helmet";
import { FormattedMessage, useIntl } from "react-intl";
// This is line 5. Import your banner.
import BannerWithImage from "../../components/banner";

// Components
import {
  Box,
  Button,
  Stack,
} from "@salesforce/retail-react-app/app/components/shared/ui";
import {
  useProduct,
  useCategory,
  useShopperBasketsMutation,
  useShopperCustomersMutation,
  useCustomerId,
} from "@salesforce/commerce-sdk-react";

// Hooks
import { useCurrentBasket } from "@salesforce/retail-react-app/app/hooks/use-current-basket";
import { useVariant } from "@salesforce/retail-react-app/app/hooks";
import useNavigation from "@salesforce/retail-react-app/app/hooks/use-navigation";
import useEinstein from "@salesforce/retail-react-app/app/hooks/use-einstein";
import useActiveData from "@salesforce/retail-react-app/app/hooks/use-active-data";
import { useServerContext } from "@salesforce/pwa-kit-react-sdk/ssr/universal/hooks";
// Project Components
import RecommendedProducts from "@salesforce/retail-react-app/app/components/recommended-products";
import ProductView from "@salesforce/retail-react-app/app/components/product-view";
import InformationAccordion from "@salesforce/retail-react-app/app/pages/product-detail/partials/information-accordion";

import {
  HTTPNotFound,
  HTTPError,
} from "@salesforce/pwa-kit-react-sdk/ssr/universal/errors";

// constant
import {
  API_ERROR_MESSAGE,
  EINSTEIN_RECOMMENDERS,
  MAX_CACHE_AGE,
  TOAST_ACTION_VIEW_WISHLIST,
  TOAST_MESSAGE_ADDED_TO_WISHLIST,
  TOAST_MESSAGE_ALREADY_IN_WISHLIST,
} from "@salesforce/retail-react-app/app/constants";
import { rebuildPathWithParams } from "@salesforce/retail-react-app/app/utils/url";
import { useHistory, useLocation, useParams } from "react-router-dom";
import { useToast } from "@salesforce/retail-react-app/app/hooks/use-toast";
import { useWishList } from "@salesforce/retail-react-app/app/hooks/use-wish-list";

const ProductDetail = () => {
  const { formatMessage } = useIntl();
  const history = useHistory();
  const location = useLocation();
  const einstein = useEinstein();
  const activeData = useActiveData();
  const toast = useToast();
  const navigate = useNavigation();
  const [productSetSelection, setProductSetSelection] = useState({});
  const childProductRefs = React.useRef({});
  const customerId = useCustomerId();
  /****************************** Basket *********************************/
  const { data: basket } = useCurrentBasket();
  const addItemToBasketMutation = useShopperBasketsMutation("addItemToBasket");
  const { res } = useServerContext();
  if (res) {
    res.set("Cache-Control", `s-maxage=${MAX_CACHE_AGE}`);
  }
  const isBasketLoading = !basket?.basketId;

  /*************************** Product Detail and Category ********************/
  const { productId } = useParams();
  const urlParams = new URLSearchParams(location.search);
  const {
    data: product,
    isLoading: isProductLoading,
    isError: isProductError,
    error: productError,
  } = useProduct(
    {
      parameters: {
        id: urlParams.get("pid") || productId,
        allImages: true,
      },
    },
    {
      // When shoppers select a different variant (and the app fetches the new data),
      // the old data is still rendered (and not the skeletons).
      keepPreviousData: true,
    }
  );

  // Note: Since category needs id from product detail, it can't be server side rendered atm
  // until we can do dependent query on server
  const {
    data: category,
    isError: isCategoryError,
    error: categoryError,
  } = useCategory({
    parameters: {
      id: product?.primaryCategoryId,
      levels: 1,
    },
  });

  /**************** Error Handling ****************/

  if (isProductError) {
    const errorStatus = productError?.response?.status;
    switch (errorStatus) {
      case 404:
        throw new HTTPNotFound("Product Not Found.");
      default:
        throw new HTTPError(`HTTP Error ${errorStatus} occurred.`);
    }
  }
  if (isCategoryError) {
    const errorStatus = categoryError?.response?.status;
    switch (errorStatus) {
      case 404:
        throw new HTTPNotFound("Category Not Found.");
      default:
        throw new HTTPError(`HTTP Error ${errorStatus} occurred.`);
    }
  }

  const isProductASet = product?.type.set;

  const [primaryCategory, setPrimaryCategory] = useState(category);
  const variant = useVariant(product);
  // This page uses the `primaryCategoryId` to retrieve the category data. This attribute
  // is only available on `master` products. Since a variation will be loaded once all the
  // attributes are selected (to get the correct inventory values), the category information
  // is overridden. This will allow us to keep the initial category around until a different
  // master product is loaded.
  useEffect(() => {
    if (category) {
      setPrimaryCategory(category);
    }
  }, [category]);

  /**************** Product Variant ****************/
  useEffect(() => {
    if (!variant) {
      return;
    }
    // update the variation attributes parameter on
    // the url accordingly as the variant changes
    const updatedUrl = rebuildPathWithParams(
      `${location.pathname}${location.search}`,
      {
        pid: variant?.productId,
      }
    );
    history.replace(updatedUrl);
  }, [variant]);

  /**************** Wishlist ****************/
  const { data: wishlist, isLoading: isWishlistLoading } = useWishList();
  const createCustomerProductListItem = useShopperCustomersMutation(
    "createCustomerProductListItem"
  );

  const handleAddToWishlist = (product, variant, quantity) => {
    const isItemInWishlist = wishlist?.customerProductListItems?.find(
      (i) => i.productId === variant?.productId || i.productId === product?.id
    );

    if (!isItemInWishlist) {
      createCustomerProductListItem.mutate(
        {
          parameters: {
            listId: wishlist.id,
            customerId,
          },
          body: {
            // NOTE: APi does not respect quantity, it always adds 1
            quantity,
            productId: variant?.productId || product?.id,
            public: false,
            priority: 1,
            type: "product",
          },
        },
        {
          onSuccess: () => {
            toast({
              title: formatMessage(TOAST_MESSAGE_ADDED_TO_WISHLIST, {
                quantity: 1,
              }),
              status: "success",
              action: (
                // it would be better if we could use <Button as={Link}>
                // but unfortunately the Link component is not compatible
                // with Chakra Toast, since the ToastManager is rendered via portal
                // and the toast doesn't have access to intl provider, which is a
                // requirement of the Link component.
                <Button
                  variant="link"
                  onClick={() => navigate("/account/wishlist")}
                >
                  {formatMessage(TOAST_ACTION_VIEW_WISHLIST)}
                </Button>
              ),
            });
          },
          onError: () => {
            showError();
          },
        }
      );
    } else {
      toast({
        title: formatMessage(TOAST_MESSAGE_ALREADY_IN_WISHLIST),
        status: "info",
        action: (
          <Button variant="link" onClick={() => navigate("/account/wishlist")}>
            {formatMessage(TOAST_ACTION_VIEW_WISHLIST)}
          </Button>
        ),
      });
    }
  };

  /**************** Add To Cart ****************/
  const showToast = useToast();
  const showError = () => {
    showToast({
      title: formatMessage(API_ERROR_MESSAGE),
      status: "error",
    });
  };

  const handleAddToCart = async (productSelectionValues) => {
    try {
      const productItems = productSelectionValues.map(
        ({ variant, quantity }) => ({
          productId: variant.productId,
          price: variant.price,
          quantity,
        })
      );

      await addItemToBasketMutation.mutateAsync({
        parameters: { basketId: basket.basketId },
        body: productItems,
      });

      einstein.sendAddToCart(productItems);

      // If the items were successfully added, set the return value to be used
      // by the add to cart modal.
      return productSelectionValues;
    } catch (error) {
      showError(error);
    }
  };

  /**************** Product Set Handlers ****************/
  const handleProductSetValidation = useCallback(() => {
    // Run validation for all child products. This will ensure the error
    // messages are shown.
    Object.values(childProductRefs.current).forEach(
      ({ validateOrderability }) => {
        validateOrderability({ scrollErrorIntoView: false });
      }
    );

    // Using ot state for which child products are selected, scroll to the first
    // one that isn't selected.
    const selectedProductIds = Object.keys(productSetSelection);
    const firstUnselectedProduct = product.setProducts.find(
      ({ id }) => !selectedProductIds.includes(id)
    );

    if (firstUnselectedProduct) {
      // Get the reference to the product view and scroll to it.
      const { ref } = childProductRefs.current[firstUnselectedProduct.id];

      if (ref.scrollIntoView) {
        ref.scrollIntoView({
          behavior: "smooth",
          block: "end",
        });
      }

      return false;
    }

    return true;
  }, [product, productSetSelection]);

  const handleProductSetAddToCart = () => {
    // Get all the selected products, and pass them to the addToCart handler which
    // accepts an array.
    const productSelectionValues = Object.values(productSetSelection);
    return handleAddToCart(productSelectionValues);
  };

  /**************** Einstein ****************/
  useEffect(() => {
    if (product && product.type.set) {
      einstein.sendViewProduct(product);
      const childrenProducts = product.setProducts;
      childrenProducts.map((child) => {
        try {
          einstein.sendViewProduct(child);
        } catch (err) {
          console.error(err);
        }
        activeData.sendViewProduct(category, child, "detail");
      });
    } else if (product) {
      try {
        einstein.sendViewProduct(product);
      } catch (err) {
        console.error(err);
      }
      activeData.sendViewProduct(category, product, "detail");
    }
  }, [product]);

  return (
    <Box
      className="sf-product-detail-page"
      layerStyle="page"
      data-testid="product-details-page"
    >
      <Helmet>
        <title>{product?.pageTitle}</title>
        <meta name="description" content={product?.pageDescription} />
      </Helmet>

      <Stack spacing={16}>
        // This is line 333. Add the banner component to the page.
        <BannerWithImage />
        {isProductASet ? (
          <Fragment>
            {/* Product Set: parent product */}
            <ProductView
              product={product}
              category={primaryCategory?.parentCategoryTree || []}
              addToCart={handleProductSetAddToCart}
              addToWishlist={handleAddToWishlist}
              isProductLoading={isProductLoading}
              isBasketLoading={isBasketLoading}
              isWishlistLoading={isWishlistLoading}
              validateOrderability={handleProductSetValidation}
            />

            <hr />

            {/* TODO: consider `childProduct.belongsToSet` */}
            {
              // Product Set: render the child products
              product.setProducts.map((childProduct) => (
                <Box key={childProduct.id} data-testid="child-product">
                  <ProductView
                    // Do no use an arrow function as we are manipulating the functions scope.
                    ref={function (ref) {
                      // Assign the "set" scope of the ref, this is how we access the internal
                      // validation.
                      childProductRefs.current[childProduct.id] = {
                        ref,
                        validateOrderability: this.validateOrderability,
                      };
                    }}
                    product={childProduct}
                    isProductPartOfSet={true}
                    addToCart={(variant, quantity) =>
                      handleAddToCart([
                        { product: childProduct, variant, quantity },
                      ])
                    }
                    addToWishlist={handleAddToWishlist}
                    onVariantSelected={(product, variant, quantity) => {
                      if (quantity) {
                        setProductSetSelection((previousState) => ({
                          ...previousState,
                          [product.id]: {
                            product,
                            variant,
                            quantity,
                          },
                        }));
                      } else {
                        const selections = { ...productSetSelection };
                        delete selections[product.id];
                        setProductSetSelection(selections);
                      }
                    }}
                    isProductLoading={isProductLoading}
                    isBasketLoading={isBasketLoading}
                    isWishlistLoading={isWishlistLoading}
                  />
                  <InformationAccordion product={childProduct} />

                  <Box display={["none", "none", "none", "block"]}>
                    <hr />
                  </Box>
                </Box>
              ))
            }
          </Fragment>
        ) : (
          <Fragment>
            <ProductView
              product={product}
              category={primaryCategory?.parentCategoryTree || []}
              addToCart={(variant, quantity) =>
                handleAddToCart([{ product, variant, quantity }])
              }
              addToWishlist={handleAddToWishlist}
              isProductLoading={isProductLoading}
              isBasketLoading={isBasketLoading}
              isWishlistLoading={isWishlistLoading}
            />
            <InformationAccordion product={product} />
          </Fragment>
        )}
        {/* Product Recommendations */}
        <Stack spacing={16}>
          {!isProductASet && (
            <RecommendedProducts
              title={
                <FormattedMessage
                  defaultMessage="Complete the Set"
                  id="product_detail.recommended_products.title.complete_set"
                />
              }
              recommender={EINSTEIN_RECOMMENDERS.PDP_COMPLETE_SET}
              products={[product]}
              mx={{ base: -4, md: -8, lg: 0 }}
              shouldFetch={() => product?.id}
            />
          )}
          <RecommendedProducts
            title={
              <FormattedMessage
                defaultMessage="You might also like"
                id="product_detail.recommended_products.title.might_also_like"
              />
            }
            recommender={EINSTEIN_RECOMMENDERS.PDP_MIGHT_ALSO_LIKE}
            products={[product]}
            mx={{ base: -4, md: -8, lg: 0 }}
            shouldFetch={() => product?.id}
          />

          <RecommendedProducts
            // The Recently Viewed recommender doesn't use `products`, so instead we
            // provide a key to update the recommendations on navigation.
            key={location.key}
            title={
              <FormattedMessage
                defaultMessage="Recently Viewed"
                id="product_detail.recommended_products.title.recently_viewed"
              />
            }
            recommender={EINSTEIN_RECOMMENDERS.PDP_RECENTLY_VIEWED}
            mx={{ base: -4, md: -8, lg: 0 }}
          />
        </Stack>
      </Stack>
    </Box>
  );
};

ProductDetail.getTemplateName = () => "product-detail";

ProductDetail.propTypes = {
  /**
   * The current react router match object. (Provided internally)
   */
  match: PropTypes.object,
};

export default ProductDetail;
```

## 5. Preview Your PDP

<style>
ul.no-bullets {
list-style-type: "a. ";
}
</style>

<ul type="a">
  <li> Run <code>npm start</code>.</li>
  <li> Go to <a href=http://localhost:3000/my-new-route> http://localhost:3000</a>.</li>
</ul>

Every PDP displays your customer banner as shown in the example below. In this scenario, when you click on the banner, it takes you to the women’s product listing page.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/customer-banner.png)

## 6. Deploy Your Bundle

<style>
ul.no-bullets {
    list-style-type: "a. ";
}
</style>

<ul type="a">
  <li> Make sure that your project includes the <a href=https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html#required-project-file> Required Project Files</a> in the <code>overrides</code> folder.</li>
  <li><a href=https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html>Deploy your bundle</a>.</li>
</ul>

## See Also

- [Template Extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html)
- [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.html)

<!-- document id=6efaaf91bd25f6235de785a59c80f764167f952c114a5184697e115523e7fa92 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/active-merchandising/b2c-active-data-for-developers.md -->

# Customize Active Data

Customize your application’s active data processing by using business objects, and B2C Commerce API pipelets and scripts.

## Business Objects

The following customizable business objects support this feature:

- CustomerActiveData
- CustomerGroup
- ProductActiveData
- SlotConfiguration

## API Pipelets

The following pipelets support active merchandising:

| Pipelet                | Description                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ImportActiveData       | Imports either ProductActiveData or CustomerActiveData attributes from a .csv file. The feed name contained in the file determines both the type of data and feed for the import process.                                                                                                                                                                                    |
| ValidateActiveDataFile | Validates the given active data .csv file and returns a status for the results of the validation. If the validation operation executes without process errors, regardless of the .csv file’s validity, the pipelet returns next. It then continues to the next node in the pipeline. If the given file doesn't exist in the given path the pipelet exits in a pipelet error. |
| Search                 | Retrieves search results. A SortingRuleID input parameter represents the ID of the sorting rule used to sort the products. The existing parameters SortBy1, SortBy1Direction, SortBy2, SortBy2Direction, SortBy3, and SortBy3Direction, can also be used with explicit sorting attribute steps in sorting rules.                                                             |

## API Scripts

The following classes support active merchandising:

| Class              | Description                                                |
| ------------------ | ---------------------------------------------------------- |
| ActiveData         | Represents the active data for an object in B2C Commerce.  |
| CustomerActiveData | Represents the active data for a Customer in B2C Commerce. |
| CustomerGroup      | See Dynamic Customer Groups.                               |
| ProductActiveData  | Represents the active data for a Product in B2C Commerce.  |

### Active Data

The following classes directly support active data:

- `dw.campaign.ProductActiveData` extends `dw.object.ExtensibleObject`
- `dw.campaign.CustomerActiveData` extends `dw.object.ExtensibleObject`

The following classes support active data:

- `dw.catalog.ProductAvailabilityModel` - `getTimeToOutOfStock()`, `getAvailability()`, and `getSKUCoverage()`
- `dw.customer.Customer` - `CustomerActiveData getActiveData()` and `getLastOrderDate()` methods added.

### Searchandising

The following classes support searchandising sorting rules:

- The `dw.catalog.SortingRule` method of the `dw.object.PersistentObject` class represents a sorting rule.
- The `dw.catalog.SortingOption` method of the `dw.object.PersistentObject` class represents a sorting option for a storefront catalog.

The following properties and methods in the dw.catalog.ProductSearchMode`l` class support searchandising:

- Properties
  - sortingRule : SortingRule
  - static final SORTING_RULE_PARAMETER : String constant from API ProductSearchModel
- Methods
  - setSortingRule(rule: SortingRule) : void
  - getSortingRule() : SortingRule
  - urlSortingRule(action : String, rule : SortingRule) : URL
  - urlSortingRule(url : URL, rule : SortingRule) : URL

The following methods of the CatalogMgr class support searchandising:

- static getSortingRules() : Collection
- static getSortingRule(ID : String)
- static getStorefrontSortingOptions() : List
- static getStorefrontSortingOption(ID : String)

**note:** The scripting API provides read, but not write, access to all active data metrics.

### Dynamic Customer Groups

The following scripting APIs support dynamic customer groups:

- The methods `dw.customer.CustomerGroup.assignCustomer` and `dw.customer.CustomerGroup.unassignCustomer` reject the assigning of customers to dynamic groups through the API.
- `Customer.getCustomerGroups` returns a list of static, dynamic, and system groups to which the customer is a member, as follows:

| Returns...                             | Storefront Sessions | Job Sessions |
| -------------------------------------- | ------------------- | ------------ |
| Dynamic customer groups                | x                   |              |
| Static customer groups                 | x                   | x            |
| System groups: Everyone and Registered | x                   | x            |
| System groups: Unregistered            | x                   |              |

`Customer#isMemberOfCustomerGroup` also checks for memberships in dynamic groups.

## Create Custom Attributes for Active Merchandising

Create custom attributes for the ProductActiveData or CustomerActiveData business objects. Attributes added to these business objects aren't replicated between instances and can't be exported.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **System Object Types.**

2.  On the System Object Type List page, select **ProductActiveData** or **CustomerActiveData.**

3.  On the System Object Type List page, click the **Attribute Definitions** tab.

    If you have already created a custom attribute, find and add it, otherwise, proceed to the next step.

4.  On the System Object Type List page Attribute Definitions tab, click **New.**

5.  Enter the properties for the custom attribute and click **Apply.**

    These attributes are created identically to any other custom attributes. However, you can't create the following attribute types for active data: Password, Image, Text, Html, or Email.

    To see the attributes in Business Manager, you must add them to the active data tab for products.

6.  Click **\<\< Back.**

7.  Click the **Attribute Grouping** tab.

8.  On the System Object Type List page Attribute Groupings tab, click **Edit** for the section on the active data tab where you want to add your attributes.

9.  To browse for your custom attribute click **...**. Check its checkbox and click **Select.**

To import values into these attributes, you must add them to an import feed definition and an associated active data feed file. See Defining Feeds as your next step.

<!-- CANNOT FIND -->
<!--TODO: Fix link post migration -->
<!-- See [Defining Feeds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-defining-feeds.md) as your next step. -->

## How Search Pipelet Sorting Rules Are Applied

The Search pipelet _SortingRuleID_ parameter specifies the ID of the sorting rule to use to sort the products. Optionally use the _SortBy1,_ _SortBy1Direction,_ _SortBy2,_ _SortBy2Direction,_ _SortBy3,_ and _SortBy3Direction_ attributes with explicit sorting attribute steps in sorting rules.

The Search pipelet uses the following rules to order search results:

- If a _SortingRuleID_ is specified and a valid rule exists with that ID, that rule is used.
- If no _SortingRuleID_ is specified or the specified ID is unknown or invalid, the default sorting rule for the search refining category is used.
- If the default sorting rule for the category refined by is invalid or no default rule was set for the category, the inherited default rule of the parent category is used.
- If the search isn't refined by category or there's no default rule set for any ancestor category, the default rule set for the root category of the storefront catalog is used.
- If there is no default rule set for the root category, the products are sorted by the sort conditions set using SortByX parameters.
- If no sorting rule applies, and no SortByX conditions are set, the products are sorted descending by text relevance based on the search term.
- If no sorting rule applies, no SortByX conditions are set, and there is no search term, the products aren't sorted in a particular order.

### Example

The following is an example:

1.  A customer searches for jacket on the home page. The search results are sorted by the default rule set for the root category of the storefront catalog.
2.  The customer refines the search by category Men's. The refined results are sorted by the default rule set for the Men's category.
3.  The customer further refines the search by the Raincoats subcategory. Because no default rule is set for Raincoats, the refined results are sorted by the default rule set for the Men's category.
4.  The customer selects **Sort by Price (Low-High)** in a sorting options dropdown. The sorting rule ID for that sorting option is specified to the Search pipelet. The same refined results are now sorted by the rule with that ID.

## Reference Application Templates for Active Merchandising

If you're implementing active data functionality in an existing storefront, you must tag different pages and change how you use the Search pipeline.

If your storefront is based on the Reference Application, instead of SiteGenesis, consider adding active data tags for the following templates:

| Template                      | Tags                                                                                                            |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
| htmlhead.isml                 | `<isactivedatahead>`                                                                                            |
| productbreadcrumbs.isml       | `<isactivedatacontext category="${category}">`                                                                  |
| productsearchbreadcrumbs.isml | `<isactivedatacontext category="${pdict.ProductSearchResult.category}">`                                        |
| pt_productdetails.isml        | `<isobject object="${pdict.Product}" view="detail"> and <isobject object="${pdict.Product}" view="setproduct">` |
| pt_productsearchresult.isml   | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |
| categoryTop.isml              | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |
| topsellers.isml               | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |
| productdetails.isml           | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |
| productlisting.isml           | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |
| set-product.isml              | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |
| productset-full.isml          | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |
| product_1x2.isml              | `<isobject object="${ProductSearchHit}" view="searchhit">`                                                      |

## Migrating Existing Applications to Use Active Merchandising

If your site was based on Salesforce B2C Commerce, Release 2.8x or earlier, your search and sorting rules were automatically migrated.

If you now want to take advantage of the active merchandising feature, you must make the following changes to your site:

- Change calls to the Search pipeline to use the SortingRuleID parameter instead of the SortBy parameter if your storefront fits the following criteria. You created your storefront application using the Reference Application (before SiteGenesis). You want to configure storefront search options to use in your application. See the Product and Search pipelines in the latest _SiteGenesis Storefront Core cartridge._
- Also, change the template that sets your sorting options. For example, change your version of the productsortingoptions.isml templates to include code similar to what’s in this file in the latest _SiteGenesis Storefront Core cartridge._

<!-- document id=0610beeb1a0d80385d0dfef128579d968c4642cd74fca2694639993b3a4a0520 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-custom.md -->

# Customize and Extend B2C Commerce

B2C Commerce offers extensive opportunities for customization and extension to meet unique business needs. Use JavaScript to create features and modify existing ones using B2C Commerce APIs and hooks. See [Script Programming](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/demandwarejavascript.htm) and [Understanding Server-Side JavaScript](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/understandingserversidejavascript.html).
Custom data models can be designed to accommodate specific business requirements, and integrations with external systems
such as ERP, PIM, CRM, payment gateways, and marketing automation tools can be seamlessly implemented. The platform also
supports customization of checkout, payment, and shipping processes. Additionally, the Salesforce AppExchange provides a
vast array of pre-built extensions and integrations, further expanding the platform's capabilities.

This section contains these guides.

- Run [Campaigns and Promotions in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_campaigns_and_promotions.htm&type=5).
- SFRA only: [Customize Promotions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/promotions/b2c-promotions-for-developers.md)
- Use [A/B Testing for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_ab_testing.htm&type=5) for scenarios such as comparing the performance of different promotions, search ordering, or types of content.
- [Create Custom Job Steps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/jobs/b2c-custom-job-steps.md) if there's no system job that does what you need to do. See [Jobs](https://help.salesforce.com/s/articleView?id=cc.b2c_job_creation_management.htm&type=5).
- Use [Customer Service Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/customer-service-center/b2c-customer-service-center.md) to create and search for order and customer data.
- [Customize Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-customize-business-manager.md).
- [Customize Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/active-merchandising/b2c-active-data-for-developers.md) to tailor your site's active merchandising. processing. See [Active Merchandising](https://help.salesforce.com/s/articleView?id=cc.b2c_active_merchandising.htm&type=5).
- SFRA only: Use [Explicit Recommendations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/recommendations/b2c-recommendations-for-developers.md) to define specific product-to-product relationships. Use these relationships for suggestions such as replacement products, cross-sells, or up-sells.

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/developer-workflow.md)

<!-- document id=beef06a1d19da905d232a6c8de880711df76ef9498fe39bd9128bc9acbeef911 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-open-source-components.md -->

# Customize B2B Store Components Using Open Source Components

Open source components provide editable source code for standard B2B store components. Using open source components, you can modify component functionality without building a new component from scratch.

The source code is available in a public Git repository. Clone the repository, customize and extend the components to meet your store requirements, and then deploy the updated versions to any B2B store using tools such as Salesforce Developer Experience (Salesforce DX) and Visual Studio Code (VS Code).

For detailed instructions on cloning and working with the open source components, see the [README.md](https://github.com/forcedotcom/b2b-commerce-open-source-components/blob/main/README.md) file in the Git repository.

**note:** We recommend you validate and test changes in a sandbox environment before deploying them to the production environment.

## Example Scenario: Personalize Product Pricing

A Commerce Admin wants to customize the Product Pricing Details component on a Product Details page to:

- Display the currency as a code (for example, USD) instead of a symbol (\$).
- Highlight the main price in a specific color.
- Display the percent difference between the main price and the strikethrough (original) price.

Using an open source component, a developer can implement these changes by modifying the existing component's code rather than rebuilding the product pricing details component from scratch.

## Code changes

1.  Open the Product Pricing Details component in VS Code:

    a. Pull the latest version of the component from your Salesforce org.

    b. Open the `productPricingDetails` component.

2.  Open the `productPricingDetailsui.html` file. This file contains the HTML markup for the Product Pricing Details component.

3.  Change all pricing displays using “symbol” (\$) to “code” (USD):

    a. Find ‌the text `"currency-display-as="symbol"`.

    b. Replace all the instances with `“currency-display-as=”code”`.

4.  Update component code logic to show the percent difference between the main and strikethrough prices:

    a. Calculate the percent difference in the `productPricingDetailsui.js` file. Add the following code to the JavaScript file to determine whether to display the percent difference and to calculate that difference:

    ```javascript
    /**
    * New:
    * Determine whether to display percentage difference between the strikethrough price and main price.
    * @type (boolean)
    * @public
    */
    get displayPercentageDifference() {
      // Display percentage if strikethrough price is higher than main price.
      return this.strikethroughPrice > this.mainPrice;
    }
    /**
    * New:
    * The percentage difference between the main price and strikethrough price.
    * This value is calculated as: ((strikethroughPrice - mainPrice) / mainPrice * 100.
    * @type (string)
    * @public
    */
    get percentageDifference() {
      if (this.mainPrice && this.strikethroughPrice) {
        const percentage = ((this.strikethroughPrice - this.mainPrice) / this.mainPrice) * 100;
        return `${percentage.toFixed(0)}`; // whole number percentage
      }
      return '0';
      //Default to ‘0%’ if prices are not set.
    }
    ```

    b. Format where the percent difference shows up in the `productPricingDetailsui.html` file. Add the following HTML to display the percent difference:

    ```html
    <!-- New! –>
    <span class=”slds-m-right_xx-small”>
      <span
        if:false={displayPercentageDifference}
        class=”percentage-difference slds-text-heading_small slds-p-right_x-small”>
        {percentageDifference}% off
      </span>
    <span>

    ```

    c. Replace all the instances with `“currency-display-as=”code”`.

    ```css
    /* New! */
    .percentage-difference {
      border: 1px solid #db3603; /* red border */
      color: #ffffff; /* white text */
      font-weight: 400;
      padding: 5px 5px;
      font-size: 12px;
      display: inline-block;
      text-align: center;
      background-color: #d83603; /* red background */
      margin-left: 10px; /* space from other prices */
    }
    ```

5.  Save the modified files.

6.  Use the Salesforce CLI or Developer Console to deploy the updated component to your Salesforce org.

7.  Refresh the Product Details page to verify the changes are applied to the Product Pricing Details component.

## See Also

- [_Salesforce Winter ’26 Release Notes_: Commerce Components](https://help.salesforce.com/s/articleView?id=release-notes.rn_comm_open_source_components.htm&release=258&type=5)
- [_Salesforce Help_: Open Source Components for B2B Stores](https://help.salesforce.com/s/articleView?id=commerce.comm_open_source_components.htm)
- [B2B Commerce Open Source Components Git Repository](https://github.com/forcedotcom/b2b-commerce-open-source-components)

<!-- document id=9164e1878c69717ee43348f4bf9b17dab72b992cf7b50355ef3c252ffa2d2560 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-customize-business-manager.md -->

# Customize Business Manager

Create a custom cartridge to modify existing Business Manager pages and add new ones.

The following four parts of the Business Manager user interface can be extended.

- menu items
- menu actions
- dialog actions
- forms

Each of the four types of extensions provides a different way to hook custom functionality into Business Manager. Because standard Business Manager menus use menu items and menu actions to access business functionality, Business Manager Extensions provided by merchants seamlessly integrate with existing menus.

**note:** Your custom Business Manager menus and functions must not reference Business Manager (core) URLs, because they aren't part of the standard Salesforce B2C Commerce API. They can be changed in any release (even hotfix level) without further notice.

Business Manager extensions are defined in XML files that are read during server startup. These XML files are placed in cartridges that implement the portions of Business Manager. A B2C Commerce server without customization has only one XML file located in the _app_business_manager_ cartridge. This file contains all the menu items and menu actions you can see in an unaltered Business Manager.

The Business Manager extensions framework takes the list of cartridges assigned to `Sites` to collect all XML files from which to load Business Manager extensions. All Business Manager extensions read from the XML files are merged into a table. The table contains the Business Manager extensions that are applicable for the current organization.

## Customize Existing Business Manager Functionality

Customize certain Business Manager functionality by creating a custom cartridge and modifying specific ISML templates in it. These templates, which override standard Business Manager templates, exist in folders under `/cartridge/templates/default`. Only the Business Manager templates listed here can be customized.

| Folder                                   | Customizable Templates                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| /cartridge/templates/default/application | <ul><li>MenuFrame.isml</li></ul>                                                                                                                                                                                                                                                                                                                                                           |
| /cartridge/templates/default/custom      | <ul><li>modules.isml</li></ul>                                                                                                                                                                                                                                                                                                                                                             |
| /cartridge/templates/default/marketing   | <ul><li>giftcertificateemail.isml</li><li>powerreviewsemail.isml</li></ul>                                                                                                                                                                                                                                                                                                                 |
| /cartridge/templates/default/order       | <ul><li>orderdetails.isml</li><li>orderemailcancellation.isml</li><li>orderemailconfirmation.ismal</li><li>orderemailcss.isml</li><li>orderemailgeneral.isml</li><li>orderemailpaymentconfirmation.isml</li><li>orderemailshippingconfirmation.isml</li><li>paymentdetails.isml</li><li>printordergeneral.isml</li><li>printorderinvoice.isml</li><li>printorderpackingslip.isml</li></ul> |
| /cartridge/templates/default/user        | <ul><li>miniaddress.isml</li><li>minicreditcard.isml</li><li>minishippingaddress.isml</li><li>passwordemail.isml</li></ul>                                                                                                                                                                                                                                                                 |

For example, a merchant conducts business in a region that uses VAT (Value-Added Tax), and wants to print legally valid VAT invoices from the Order page. The output of the standard invoice print function doesn't qualify. To implement this functionality, customize the `/cartridge/templates/default/order/printorderinvoice.isml` template to add the required information to the output of the **Print Invoice** button.

Find sample templates by creating a business manager extension cartridge using UX Studio.
Find sample templates in the UX Studio support bundle, which you can download from any sandbox using a fixed URL: [https://abcd-123.dx.commercecloud.salesforce.com/on/demandware.servlet/WFS/Studio/Sites/mock/demandware-mock.zip](https://abcd-123.dx.commercecloud.salesforce.com/on/demandware.servlet/WFS/Studio/Sites/mock/demandware-mock.zip)
(use your username and WebDAV/UX Studio access key). The `bm_extension.zip` file within this bundle contains the example
business manager extension and sample templates.

## Extend Business Manager

1.  Set up a custom cartridge.
2.  Create a file with name `*bm_extensions.xml_`in directory`/*\<cartridge_name>*/cartridge` of your custom cartridge.
3.  Add the following lines of XML to your file:

    ![XML Snippet for Business Manager Extension](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_bm_extensions_adding_xml.gif)

4.  Add the extension to that file.
5.  Implement the extension you want by implementing B2C Commerce scripts, pipelines, and templates. Place that implementation in your custom cartridge.
6.  Deploy your custom cartridge to the server.
7.  Add the cartridge to the cartridge path by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Sites** > **Manage Sites** > **Sites-Site: \< _Effective Cartridge Path_ >**.
8.  Test extensions.

## Add a New Menu Item

To add a menu item, for example, Merchants Custom Menu Item:

1.  Add the following XML in the `<extensions>` tag to your `bm_extensions.xml` file:

    ![XML Snippet for Custom Menu Item](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_bm_new_menu_item_xml.gif)

2.  Choose a unique ID for the menu item.
3.  Place the menu item in the Administration navigation menu by setting the _site_ attribute to _false._
4.  Use the position attribute to place the new menu item in the preferred order in the navigation list. The higher the number, the higher in the list it appears.
5.  To enhance the menu item, assign an image to it; put the image in directory `/*\<cartridge_name>*/cartridge/static/default/<my-image-directory>`. If you want different images for different languages, make sure to have a separate directory for each language. Use the ISO locale of the language as the directory name.

## Add a New Menu Action

Menu actions are the bridge between the navigation (menu item) and the business functionality. To link the navigation (menu item) with the business logic:

1.  Add the following XML inside the `<extensions>` tag to your `bm_extensions.xml` file:

    ![XML Snippet for Custom Menu Action](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_bm_adding_menu_actions_xml.gif)

2.  Supply a unique ID to the menu action.
3.  Because the parent menu item is hooked into the Administration section of the navigation, set this _site_ attribute to _false_.

    **note:** You can't add a menu action under a menu action. It must be below an existing menu item (custom or supplied by Salesforce).

4.  When selecting a menu action at the Business Manager overview, a pipeline is executed to show the first page of your custom business functionality. Specify the name of that pipeline and start node in the XML element _exec:_

    ![Pipeline and Start Node in the XML Element exec](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_bm_menu_action_pipeline_diagram.gif)

5.  List all pipelines that implement your menu action in the menu action's XML definition. List them inside the _\<_ _subpipelines>_ tag. Use a separate _\<_ \_pipeline\__ for each pipeline. If only some of a pipeline's start nodes belong to the menu action, restrict it by specifying _\_name of the pipeline-Name of the start node\_.

    ![XML Snippet Sub Pipeline](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_bm_menu_actions_pipeline_list.gif)

    **note:** Always add the exec-pipelines to the _\<_ _subpipelines>_ section. Non-public pipelines (where all start nodes have call mode = "Private") need not be added to the _\<_ _subpipelines>_ section.

6.  After successfully deploying your cartridge on the server, grant permissions on the menu action.

**note:** Change the context to a site if your menu action is site-specific.

**note:** Don't change the ID of a menu action after you have granted permissions on it. Otherwise, you have to grant permissions again and the former permission remains in the database, unused.

## Implement Dialog Actions

Dialog actions hook into existing Business Manager page. The dialog action can open a popup or navigate to a subpage.

1.  Add your custom dialog to the `bm_extensions.xml` file:

    ![XML Snippet for Custom Dialog Action](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_bm_dialog_actions_xml.gif)

2.  Select a unique ID for the dialog action.
3.  Choose the extension point from the list of available extension points (to which you want to hook the dialog action). The extension points are listed at the end of the `bm_extension.xml` file.
4.  Add this ID as a value of the `xp_ref` attribute to the XML.
5.  Make sure the tag _\<_ _exec pipeline=.._ contains the name of the pipeline executed when the user clicks the button of the dialog actions hook.
6.  To open a popup, set the attribute _extern_ to _true._ Make sure the page to be opened is designed to appear as a popup.

## Implement Form Extensions

1.  Add the form extension to `bm_extensions.xml`.

    ![XML Snippet for Custom Form Extension](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_bm_form_extensions_xml.gif)

2.  Choose the ID (into which you want to add the form extension) from the list of available extension points.
3.  Add this ID to the XML as the attribute ID value. Each _\<valueinput>_ element is rendered as an HTML form input field. The name of the form field must be unique within your form extension. Each form input field must specify the type of input data captured by the form field. Available data types are `string`, `int`, `double`.
4.  Specify a label to appear beside the form field. Specify the label at least for `x-default` locale. Add more _\<_ *label...*elements to localize for other languages.

**note:** Make sure that the search attributes defined by attribute `name` map to the attributes of the business object to search for. For example, if you extend Order Search, view that business object's attributes by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Site Development** > **System Object Types** > **Order** > **Attribute Definitions**.

**note:** Business Manager Form Extensions only support custom attributes; they don't support system attributes.

## Business Manager Extension Points

Customize Business Manager user interface elements to meet your storefront information management requirements:

### Menu Items

Business Manager has two first-level navigation elements: Administration and Site. A Business Manager menu item is a second-level navigation element in the Business Manager navigation panel. Add more menu items than are supplied with Business Manager if needed.

A menu item has the following properties:

| Property          | Usage                  | Description                                                                                                                            |
| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| ID                | Mandatory, unique      | identifies the menu item; must be unique across all menu items                                                                         |
| Name              | Mandatory, localizable | The caption of the menu item                                                                                                           |
| Description       | Optional, localizable  | Describes the menu item; shown at the overview that appears upon selecting the item                                                    |
| Short description | Optional, localizable  | Describes the menu item; used for GUI elements like tool tip texts and status bar messages                                             |
| Site              | Optional               | If True (default), then appears in the Site menu section; otherwise appears in the Administration section                              |
| Position          | Optional               | Number indicating position of menu item within its main menu (default, last position)                                                  |
| Icon              | Optional               | Relative path name of icon image for this menu item; appears in content section when parent main menu item is selected in menu section |

### Menu Actions

Business Manager menu actions are the third-level navigation element of Business Manager. They are submenu items of Business Manager menu items and are shown on the overview page of a menu item. Selecting a menu action at the overview page leads to the execution of an implemented functionality. Menu actions are the direct connection between the navigation panel and the actual business functionality. For example, the _Products_ menu action is the linking element between the navigation and the list view that shows products.

A menu action has the following properties:

| Property          | Usage                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ID                | Mandatory, unique      | Identifies the menu action; must be unique across all menu actions                                                                                                                                                                                                                                                                                                                                                                                                           |
| Menupath          | Optional               | ID of the parent menu item to which this menu action is assigned; must refer to the ID of an existing menu item. The menu item can be in the same bm_extensions.xml file or in a bm_extensions.xml file of another cartridge that is loaded in the same application. If the menupath property refers to an unknown menu item, then the extension framework rejects the menu action and doesn't display it in the user interface. (This behavior prevents orphan menu items.) |
| Name              | Mandatory, localizable | The name shown as the caption of the menu action                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Description       | Optional, localizable  | Description of the menu action; shown at the overview that appears upon selecting the parent menu item                                                                                                                                                                                                                                                                                                                                                                       |
| Short description | Optional, localizable  | Shorter description of the menu action; used for GUI elements such as tool tip texts and status bar messages                                                                                                                                                                                                                                                                                                                                                                 |
| Site              | Optional               | If True (default), the menu item of this menu action appears in the Site menu section; otherwise appears in the Administration section. Value must be the same as the site attribute of the containing menu item (see Menupath property).                                                                                                                                                                                                                                    |
| Exec              | Optional               | Entry pipeline (and start node) to be executed when the menu action is selected                                                                                                                                                                                                                                                                                                                                                                                              |
| Parameters        | Optional               | Some static parameters passed to the exec-pipeline                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Sub-pipelines     | Mandatory              | List of those pipelines that implement the menu action. All pipelines that are linked inside the menu action's business functionality must be specified here. The exec-pipeline is included.                                                                                                                                                                                                                                                                                 |
| Support           | Optional               | Flag indicating that this menu action is only visible to Commerce Cloud Support (default = false)                                                                                                                                                                                                                                                                                                                                                                            |
| Position          | Optional               | Number indicating the position of this menu action within its parent menu (default = last position)                                                                                                                                                                                                                                                                                                                                                                          |
| Extern            | Optional               | Default = false; if true, selecting this menu action causes a new browser window to open                                                                                                                                                                                                                                                                                                                                                                                     |
| Icon              | Optional               | Relative path name of the image for the icon of this menu action; appears in the content section of the parent menu item                                                                                                                                                                                                                                                                                                                                                     |
| Permissions       | Optional               | Deprecated since server version 2.6. Required if migrating Business Manager extensions and access privileges from a pre-2.6 version to 2.6                                                                                                                                                                                                                                                                                                                                   |

### Dialog Actions

Business Manager dialog actions enable you to add new functionality to the pages of a menu action. HTML buttons represent the extension points in which to hook dialog actions. Selecting a corresponding button on pages (templates) executes them. Existing templates contain extension points that are referenced using a unique ID.

Dialog actions have the following properties:

| Property                  | Usage     | Description                                                                                                         |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
| ID                        |           | Identifies the dialog action; must be unique across all dialog actions                                              |
| Name                      | Optional  | Names the action                                                                                                    |
| Extension point reference |           | ID of the extension point where this action is made accessible by the user                                          |
| Exec                      |           | The pipeline and start node to be executed when a user triggers the action                                          |
| Menuaction-ref            | Mandatory | The menu action where the dialog action extension is hooked in                                                      |
| Parameters                | Optional  | The names of the context parameters whose values are passed as dictionary entries to the executed pipeline          |
| Position                  | Optional  | A number indicating the position within all the actions linked to the same extension point                          |
| Extern                    | Optional  | Default = false; if true, clicking the button representing this dialog action triggers a new browser dialog to open |

### Form Extensions

Business Manager form extensions are a way to extend existing Business Manager forms, such as the search form, with more form fields. The values entered into these fields can be of type `string`, `int`, or `double`, and predefined values (options) can be specified for each field.

**note:** Business Manager form extensions only support custom attributes; they don't support system attributes.

When the additional fields have been declared in the XML descriptor (`bm_extensions.xml`), an arbitrary form containing a specific ISML tag (`<isformextension ..>`) can access that data, or, more specifically, a search form containing another specific ISML tag (`<issearchformextension ..>`) automatically contains the added (search) fields. To enable this functionality, you must specify a unique ID for the FormExtension in the XML file and in the ISML file that is supposed to use the respective data.

Salesforce recommends that you make every Business Manager form extensible by adding one of these form extension ISML tags, specifying extension IDs to use later in the XML descriptor (`bm_extensions.xml`). Choose IDs carefully, possibly by including parts of the corresponding pipeline or ISML template name (for example, order-search).

When defining a Business Manager form extension, the following attributes of the `<formextension ..>` element are specified:

| Property | Description                           |
| -------- | ------------------------------------- |
| ID       | A unique identifier of this extension |

The direct child elements of the `<formextension id="..">` tag are `<valueinput..>` elements. These elements each correspond to an added field and have the following attributes:

| Property     | Usage    | Description                                                                          |
| ------------ | -------- | ------------------------------------------------------------------------------------ |
| Type         |          | `string`, `int`, or `double`                                                         |
| Name         |          | The name of the field, also used as the name for the respective GET / POST parameter |
| Defaultvalue | Optional | A default value for this field                                                       |

Child elements must be specified for each `<valueinput..>` element. One is the `<label..>` element, which contains a descriptive label for this field. Because it's localizable, multiple `<label..>` elements can occur at the same level (that is, for the same field or value input). Salesforce recommends that you specify at least one label, preferably with the _default_ locale; attributes are as follows:

|`xml:lang`|Any locale ID (for example, en_US), or "x-default" to specify the default label for any locale not specified here explicitly|

The `<option>` element is also available. It has no attributes (and thus isn't localizable). Use it to encapsulate any text that could appear as an option for this value input.

**note:** If at least one _option_ is specified, the user can no longer enter text freely, but must select from a set of options.

**note:** If any options are specified, and a default value is given, this value must be specified as one of the available options.

## Determine Deprecated API Usage

Business Manager provides a convenient way for you to determine your application's deprecated API usage.

For a list of deprecated APIs, refer to What's New page provided with each release of the API.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Deprecated API Usage**.

    With the proper permission, see a list of deprecated APIs and their current usage. The usage count reflects the number of times a deprecated method was called within the last 24 hours.

<!-- document id=f03130963847798278a9fa81300dcb6a9ae3e178f6a92bffd52957d859b868bd url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-customization.md -->

# Customize Customer Service Center

Customize Customer Service Center to modify the behavior and appearance of its business logic and user interface. Customize business logic through Shop API hooks, and areas of the CSC UI by modifying the JSON for those areas in Business Manager.

Apply existing B2C capabilities and integrations using B2C Commerce Soap APIs and Open Commerce API (OCAPI) hooks. For a fully functional Customer Service Center, the following integrations are required and must be plugged into existing B2C Commerce integrations.

- Payment Service Providers
- Order Calculation

## Shop API Hooks

Customer Service Center uses the Shop API and its resources. Each action maps to a Shop API resource. Add your custom function in the hooks to apply the actions triggered in the UI, such as, setting the default address when selecting a customer. The Shop API hooks also provide payment hooks to run, for example for authorizations.

**note:** All of the Shop API hooks noted in this guide use OCAPI version 17.8.

Use Shop API hooks to modify address validation, fraud checks, payment processing, and set addresses automatically.

For payment processing you must link your payment provider logic to these hooks:

- dw.ocapi.shop.basket.afterPostPaymentInstrument
- dw.ocapi.shop.basket.beforePostPaymentInstrument
- dw.ocapi.shop.order.afterPostPaymentInstrument
- dw.ocapi.shop.order.beforePostPaymentInstrument (to be able to support multi-shipment)

All B2C payment methods are available in Customer Service Center. Use a hook if you want to remove a payment method from the list. For examples of these endpoints, see the Basket resource page in the Open Commerce API section of the Infocenter.

- dw.ocapi.shop.basket.payment_methods.modifyGETResponse
- dw.ocapi.shop.order.payment_methods.modifyGETResponse

To enable hosted payment pages from Customer Service Center, custom client logic is responsible for rendering the hosted payment page. In addition, you must configure hosted payment pages to use them. You use the hook with either:

- dw.csc.hosted_payment_pages.{payment_method_id}
- dw.csc.hosted_payment_pages.{payment_processor_id}

## UI Customization

Use UI customizations to modify:

- address templates and forms
- price adjustment forms
- payment templates and forms

<!-- document id=362acde5eb71a2943998becfcbace1aa8fa0b42e9b5762a99b646f4f6b6b17e6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-inventory-for-developers.md -->

# Customize Inventory Management

Customize the way your storefront application handles inventory.

Customizations you can implement include:

- Use or extend the SiteGenesis application to track product stock levels. See Inventory Scenarios.
- Integrate with other Inventory Management Systems.
- Extend the product inventory record object. (Not supported when using Omnichannel Inventory.)
- Use inventory-specific B2C Commerce APIs to calculate product availability.
- Access inventory list data via templates. See the SiteGenesis application for examples.
- Clean up unnecessary inventory transactions for improved cart checkout.

## Inventory Implementation Considerations

Consider the following as you implement inventory into your storefront application.

1.  What information can your Inventory Management System send to Salesforce B2C Commerce?
    - Does it support backorder or pre-order status?
    - Can it send all required data in a single batch transmission?
2.  What information can your Order Management System receive from B2C Commerce?
    - Does it support backorder or pre-order status?
    - Can it receive all required data in a single batch transmission?
3.  Model the use cases to determine what happens: if a product not available, if there isn't enough stock, or other circumstances.
4.  Identify when the availability stock level validation occurs:
    - Product page
    - Add to shopping cart
    - Checkout
5.  When tracking stock levels within B2C Commerce, understand:
    - What information tracking is there within B2C Commerce?
    - When would you like inventory levels to be decremented, at _order confirmation_ or _add to cart?_
6.  If supporting backorders:
    - Do you want to present an estimated availability date?
    - Can your backend system support backorders? If yes, what information is required?
    - How backorders impact your shipping logic?
7.  If supporting pre-orders:
    - Do you want to present an estimated availability date?
    - Can your backend system support pre-orders? If yes, what information is required?
    - How pre-orders impact your shipping logic?

### Inventory Best Practices

Follow these inventory guidelines as you develop customizations to your storefront inventory.

#### Training and Documentation

The developer must provide the marketing and merchandising teams with a clear understanding of how stock level tracking has been implemented within their storefront.

#### Testing Inventory

- Inventory record updates are tested in staging before going into production.
- Inventory record updates are monitored when they go live into production.

#### Implement and Document Stock Level Tracking

Develop a workflow for the inventory management application:

- Identify clear roles and responsibilities related to inventory management within your organization
- When are product inventory records transmitted to Salesforce B2C Commerce?
- What information do the product inventory records contain?
- Do batch transmissions replace all product inventory records or only merge changed records?
- Who is managing inventory once the products go live?
- What signatures are required, at which steps?
- What are the specific timelines and deadlines?

#### Daily Operations

- Retrieve inventory data in the XML format defined by inventory.xsd, then import the product inventory records using a scheduled job in Business Manager: Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Operations > Job Schedules.**
- If possible, retrieve changed product inventory records instead of all product inventory records.
- Import inventory into both the Production and Staging instances.
- Assign the inventory list. You assign each inventory list to one or more sites. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Products and Catalogs** > **Inventory Lists** > **inventory list** > **Site Assignments tab**. The assignment is a manual process.

#### Clean up Inventory Transactions

To speed record access (and cart checkout) time, delete zero amount inventory transactions and inventory transactions with zero sum that correspond to the same order as frequently as possible. See Inventory Transactions Cleanup.

### API Availability Calculation

This topic describes how the following APIs calculate >availability. There are some release-specific considerations for updating stock levels.

#### isOrderable()

**Simple product**

Returns true if

- product is online, product has no record and default availability = true or
- product is online, product has record and is perpetual or
- product is online, product has record and isn't perpetual and ATS is greater than or equal to the product.minOrderQuantity

**Product bundle**

Returns true if

- all bundled products are orderable and
- bundle is online, bundle has no record or
- bundle is online, bundle has record and is perpetual or
- bundle is online, bundle has record and isn't perpetual and ATS is greater than or equal to the bundle.minOrderQuantity

**Base product**

Returns true if all of the following conditions are true:

- base product is online
- at least one variation product is orderable

**Product set**

Returns true if all of the following conditions are true:

- product set is online
- at least one set product is orderable

#### isOrderable(Quantity)

**note:** isOrderable(quantity) doesn't depend on minOrderQuantity of product

**Simple product**

Identical to isOrderable(), except that the quantity must be greater than or equal to the specified quantity.

**Product bundle**

Identical to isOrderable(), except that the quantity must be greater than or equal to the specified quantity.

**Base product**

Identical to isOrderable(), except that the sum of orderable variation products must be greater than or equal to the quantity.

**Product set**

Identical to isOrderable(), except that the sum of orderable products in the set must be greater than or equal to the quantity.

#### isInStock()

**Simple product**

Returns true if

- product has no record and default in-stock is true or
- product has record and is perpetual or
- product has record and isn't perpetual and stock-level is greater than or equal to the product.minOrderQuantity.

**Product bundle**

Returns true if

- all bundled products are in-stock and
- bundle has no record or
- bundle has record and is perpetual or
- bundle has record and isn't perpetual and stock-level is greater than or equal to the bundle.minOrderQuantity

**Base product**

Returns true if

- at least one variation product is in-stock

**Product set**

Returns true if

- at least one set product is in-stock

#### isInStock(Quantity)

**note:** isInStock(quantity) doesn't depend on minOrderQuantity of product

**Simple product**

As above, but stock-level must be greater than or equal to the quantity, and the quantity must be greater than or equal to one.

**Product bundle**

As above, but stock-level must be greater than or equal to the quantity, and the quantity must be greater than or equal to one.

**Base product**

As above, but sum of variation product stock-levels must be greater than or equal to the quantity, and the quantity must be greater than or equal to one.

**Product set**

As above, but sum of set product stock-levels must be greater than or equal to the quantity, and the quantity must be greater than or equal to one.

#### GetAvailabilityStatus()

**Simple product**

Returns availability status for quantity one. Possible statuses are:

- IN_STOCK - returned if product is in stock
- BACKORDER - returned if product isn't in stock, but back-orderable, and at least one back-orderable item is left.
- PREORDER - returned if product isn't in stock, but pre-orderable, and at least one pre-orderable item is left
- NOT_AVAILABLE - returned if product is not IN_STOCK, nor BACKORDER, nor PREORDER

**Product bundle**

Returns availability status for quantity one. See "Simple Product" column for possible statuses.

Returned status is computed based on the records of the bundled products and the record of the bundle if it exists, and represents the lowest availability status of the involved products.

For example, if all bundled products are IN_STOCK, but the bundle has a record and is NOT_AVAILABLE, method returns NOT_AVAILABLE.

**Base product**

Returns availability status for the variation product with the best availability for quantity one. For example, if all variation products are BACKORDER, but only one is IN_STOCK, method returns IN_STOCK.

**Product set**

Returns availability status for the set product with the best availability.

#### GetAvailabilityLevels(Quantity)

**Simple product**

Returns availability statuses for quantity. For example, if requested quantity is 10, and stock level is two, and product can be backordered, and backorder quantity is five, the method returns the following: IN_STOCK-2, BACKORDER-5, NOT_AVAILABLE-3

**Product bundle**

Returns availability statuses for quantity. Based on the rules described previously, but computation combines the availability levels of all bundled products and the bundle itself (if it has a record).

**Base product**

Returns availability status for quantity based on the variation products with the best availability.

**Product set**

Returns availability statuses for quantity based on the set products with the best availability

#### ReserveInventoryForOrder(Basket)

**Simple product**

Decrement product stock-level. Fails if ATS is less than the productLineItem.quantity.

**Product bundle**

If bundle has record, decrement stock-level of bundle. Decrement stock-levels of bundled product line items recursively. Fails if the available to sell (ATS) value is less than the productLineItem.quantity.

**Base product**

Fails if product line item is base product. A base product can't be ordered.

**Product set**

Fails if product line item is product set. A product set can't be ordered.

#### GetAvailability()

Uses the preorder/backorder allocation and the inventory list default-in-stock flag to calculate availability.

### Inventory APIs and Pipelets

Customize your application with programmatic inventory access.

Use the following:

- API Methods: use to manage inventory lists, and to retrieve product inventory and availability information.
- Pipelets: use to get and set inventory record values.
- Resources: use for inventory-related (localizable) messages.

Use Salesforce B2C Commerce APIs to determine product availability within your application.

### Inventory List Export

Salesforce B2C Commerce exports an Inventory List record and its associated Product Inventory Records via an XML file. The structure of the XML file follows the semantic of the XML `inventory.xsd` schema definition.

#### Data for Inventory Lists

Inventory list export contains these attributes:

- allocation
- allocation-timestamp
- perpetual
- preorder-backorder-handling
- preorder-backorder-allocation
- in-stock-date
- in-stock-datetime
- ats (available to sell)
- on-order
- turnover

## Inventory List Import

Salesforce B2C Commerce imports an Inventory List record and its associated Product Inventory Records via an XML file. The structure of the XML file follows the semantic of the XML `inventory.xsd` schema definition.

A typical import file is shown in the following example:

```xml
<?xml version="1.0" encoding="UTF-8" ?>
```

Specify the `inventory.xsd` file that defines the schema.

```xml
<inventory xmlns="http://www.demandware.com/xml/impex/inventory/2007-05-31">
   <inventory-list>
```

## ProductInventoryRecord Objects

```xml
      <records>
```

Set the stock level at 10 for product "ProductWithAllocation".

```xml
         <record product-id="ProductWithAllocation">
            <allocation>10</allocation>
            <perpetual>false</perpetual>
         </record>
```

Set the stock level at 10 and the backorder allocation at 10 for product " ProductWithBackorderAllocation ".

```xml
         <record product-id="ProductWithBackorderAllocation">
            <allocation>10</allocation>
            <perpetual>false</perpetual>
            <preorder-backorder-handling>backorder</preorder-backorder-handling>
            <preorder-backorder-allocation>10</preorder-backorder-allocation>
         </record>
```

Define "ProductWithPerpetualFlag" as a product always in stock.

```xml
         <record product-id="ProductWithPerpetualFlag">
            <perpetual>true</perpetual>
          </record>
      </records>
</inventory-list>
```

### Inventory Methods

Use these methods from the _dw.catalog.ProductInventoryList_ class to manage your inventory lists, and retrieve product inventory and availability information.

| Class                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ProductInventoryList      | Given a product or a product ID, the `ProductInventoryList` object provides access to the list's ID, description and `defaultInStockFlag`. Each site can have a single `ProductInventoryList`, although that `ProductInventoryList` can be used by more than one site. The main function of a `ProductInventoryList` is to hold `ProductInventoryRecords`, each of which holds the following inventory information about a single product. |
| ProductInventoryMgr       | The `ProductInventoryMgr`object provides access to inventory related objects.                                                                                                                                                                                                                                                                                                                                                              |
| ProductInventoryRecord    | The `ProductInventoryRecord`holds information about a product's inventory and availability.                                                                                                                                                                                                                                                                                                                                                |
| ProductAvailabilityModel  | The `ProductAvailabilityModel`object provides methods for retrieving all information on availability of a single product.                                                                                                                                                                                                                                                                                                                  |
| ProductAvailabilityLevels | The `ProductAvailabilityLevels` object returns the quantity of items available for each availability status.                                                                                                                                                                                                                                                                                                                               |

### Inventory Pipelets

Use the following pipelets to modify or extend the inventory implementation in the SiteGenesis application. They provide convenient methods and properties for getting and setting inventory record values.

<table><col /><col /><thead><tr><th>Pipelet</th><th>Description</th></tr></thead><tbody><tr><td>ReserveInventoryForOrder</td><td><p>Reserves the inventory for each product line item of the specified <code>LineItemCtnr.</code> The reserved inventory is automatically finalized with the commit of the order creation transaction (encloses the CreateOrder pipelet).</p> <p>If no inventory finalization takes place within 10 minutes, the reservation expires. The pipelet cleans up existing reservations for the <code>LineItemCtnr</code> before it's called again. The reserved inventory doesn't count toward the current stock level.</p> <code>This pipelet should only be used for the inventory reservation during an order creation.</code></td></tr><tr><td>ImportInventoryLists</td><td><p>Imports inventory lists from the given import file in the specified mode. The result of the import operation is represented by the <code>Status</code> output property. The pipelet returns to the error connector if a process error occurred when executing the import.</p> <p>A process error prevents or interrupts the basic execution of the import. An example of a process error is when the specified import file doesn't exist on the file system.</p> <p>Client code should consult the <code>Status</code>object details to determine if there were any problems importing the individual data within the import file.</p></td></tr></tbody></table></sfdocstbl>

### Inventory Resources

The following localizable resources are available for inventory-related messages. These are located in the SiteGenesis Storefront Core cartridge (templates/resources).

| File                  | Resource                                | Default Text                                                                                                             |
| --------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| checkout.properties   | cart.cart.allBackorder                  | This item is available on backorder.                                                                                     |
|                       | cart.cart.allInStock                    | This item is in stock and ready to ship.                                                                                 |
|                       | cart.cart.allNotAvailable               | This item is currently not available. Remove the item from your cart in order to proceed with the checkout.              |
|                       | cart.cart.allPreorder                   | This item is available for pre-order.                                                                                    |
|                       | cart.cart.inStockDate                   | The expected in-stock date is                                                                                            |
|                       | cart.quantityBackorder                  | {0} item(s) are available on backorder.                                                                                  |
|                       | cart.cart.quantityPreorder              | {0} item(s) are available for pre-order.                                                                                 |
|                       | cart.cart.quantityInStock               | {0} item(s) are in stock and ready to ship.                                                                              |
|                       | cart.cart.remainingBackorder            | The remaining items are available on backorder.                                                                          |
|                       | cart.cart.remainingNotAvailable         | The remaining items are currently not available. Adjust the quantity in your cart in order to proceed with the checkout. |
|                       | cart.cart.remainingPreorder             | The remaining items are available for pre-order.                                                                         |
| components.properties | components.common-details.005           | This item is in stock.                                                                                                   |
|                       | components.common-details.006           | This item isn't available.                                                                                               |
|                       | components.common-details.007           | Only {0} items left.                                                                                                     |
|                       | components.common-details.008           | More items on backorder.                                                                                                 |
|                       | components.common-details.backorder     | This item is available on backorder.                                                                                     |
|                       | components.common-details.in-stock-date | The expected in-stock date is                                                                                            |
|                       | components.common-details.pre-order     | This item is available for pre-order.                                                                                    |

### Inventory.xsd Schema

The `inventory.xsd` file defines how to structure the XML file that transmits inventory data to Salesforce B2C Commerce. This file defines the Inventory List record and its associated Product Inventory Records.

The inventory.xml file can contain 0 or more inventory lists.

#### Inventory List Record

```xml
<xsd:complexType name="complexType.Header">
<xsd:sequence>
```

An inventory list must always have a value for the default product availability flag.

```xml
<xsd:element name="default-instock" type="xsd:boolean" minOccurs="1" maxOccurs="1" />
```

The description field is optional and up to 4000 characters.

```xml
<xsd:element name="description"
   type="simpleType.Generic.String.4000" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
```

The list ID is required and up to 256 characters.

```xml
<xsd:attribute name="list-id" type="simpleType.Generic.NonEmptyString.256" use="required" />
```

The import mode is optional.

```xml
   <xsd:attribute name="mode" type="simpleType.ImportMode" use="optional" />
</xsd:complexType>
```

The list can contain zero or more inventory records.

```xml
<xsd:complexType name="complexType.InventoryRecords">
    <xsd:sequence>
        <xsd:element name="record" type="complexType.InventoryRecord"
            minOccurs="0" maxOccurs="unbounded" />
    </xsd:sequence>
</xsd:complexType>
```

#### Product Inventory Records

```xml
<xsd:complexType name="complexType.InventoryRecord">
   <xsd:sequence>
```

The allocation, perpetual, preorder-backorder-handling, preorder-backorder-allocation, in-stock-date, ats, on-order, turnover, and custom-attribute fields of an inventory record are optional.

```xml
<xsd:complexType name="complexType.InventoryRecord">
   <xsd:sequence>
      <xsd:element name="allocation" type="simpleType.Allocation" minOccurs="0" maxOccurs="1" />
      <xsd:element name="allocation-timestamp" type="xsd:dateTime" minOccurs="0" maxOccurs="1" />
      <xsd:element name="perpetual" type="xsd:boolean" minOccurs="0" maxOccurs="1" />
      <xsd:element name="preorder-backorder-handling" type="simpleType.InventoryRecord.PreorderBackorderHandling" minOccurs="0" maxOccurs="1" />
      <xsd:element name="preorder-backorder-allocation" type="simpleType.Allocation" minOccurs="0" maxOccurs="1" />
      <xsd:element name="in-stock-date" type="xsd:date" minOccurs="0" maxOccurs="1" />
      <xsd:element name="ats" type="simpleType.Allocation" minOccurs="0" maxOccurs="1" />
      <xsd:element name="on-order" type="simpleType.Allocation" minOccurs="0" maxOccurs="1" />
      <xsd:element name="turn-over" type="simpleType.Allocation" minOccurs="0" maxOccurs="1" />
      <xsd:element name="custom-attributes" type="sharedType.CustomAttributes" minOccurs="0" maxOccurs="1" />
   </xsd:sequence>
   <xsd:attribute name="product-id" type="simpleType.Generic.NonEmptyString.100" use="required" />
   <xsd:attribute name="mode" type="simpleType.ImportMode" use="optional" />
</xsd:complexType>
```

Product IDs are required.

```xml
<xsd:attribute name="product-id"
   type="simpleType.Generic.NonEmptyString.256" use="required" />
</xsd:complexType>

```

Allocation contains a decimal value greater than or equal to "0.0".

```xml
<xsd:simpleType name="simpleType.Allocation">
   <xsd:restriction base="xsd:decimal">
      <xsd:minInclusive value="0.0" />
   </xsd:restriction>
</xsd:simpleType>
```

ImportMode defaults to "delete".

```xml
<xsd:simpleType name="simpleType.ImportMode">
   <xsd:restriction base="xsd:string">
      <xsd:enumeration value="delete" />
   </xsd:restriction>
</xsd:simpleType>
```

The preorder backorder handling field must be equal to "none", "preorder" or "backorder".

```xml
<xsd:simpleType name="simpleType.InventoryRecord.PreorderBackorderHandling">
   <xsd:restriction base="xsd:string">
      <xsd:enumeration value="none" />
      <xsd:enumeration value="preorder" />
      <xsd:enumeration value="backorder" />
   </xsd:restriction>
 </xsd:simpleType>
```

This defines a "simpleType.Generic.String", which is the basis for the next three definitions.

```xml
<xsd:simpleType name="simpleType.Generic.String">
   <xsd:restriction base="xsd:string" />
</xsd:simpleType>
```

This defines an optional string with a maximum length of 256 characters.

```xml
<xsd:simpleType name="simpleType.Generic.String.256">
   <xsd:restriction base="simpleType.Generic.String">
      <xsd:minLength value="0" />
      <xsd:maxLength value="256" />
   </xsd:restriction>
</xsd:simpleType>
```

This defines an optional string with a maximum length of 4000 characters.

```xml
<xsd:simpleType name="simpleType.Generic.String.4000">
   <xsd:restriction base="simpleType.Generic.String">
      <xsd:minLength value="0" />
      <xsd:maxLength value="4000" />
   </xsd:restriction>
</xsd:simpleType>
```

This defines a non-empty string with a maximum length of 256 characters.

```xml
<!--  Nonempty string with no leading or trailing whitespace -->
<xsd:simpleType name="simpleType.Generic.NonEmptyString.256">
   <xsd:restriction base="simpleType.Generic.String">
      <xsd:minLength value="1" />
      <xsd:maxLength value="256" />
      <xsd:pattern value="\S(.*\S)*" />
    </xsd:restriction>
 </xsd:simpleType>
```

### SiteGenesis Application Inventory Implementation

The SiteGenesis storefront implements an inventory scenario that showcases a combination of variation products.

Variants include:

- Pre-order, back-order, and discontinued products
- Stock-level and availability based on `getAvailabilityModel().isInStock()`
- Show available on-hand inventory level for `quantity < 5 ("only x items left")`
- Out-of-stock products with and without available date

Availability is indicated on the following:

- Product lists (catalog, search, shopping cart, wish lists)
- Product details page

Availability is checked during the following steps of the order process:

- Add-to-Cart
- Checkout
- Order-Now

The SiteGenesis application enables customers to order pre-order and back-order items.

The Salesforce B2C Commerce APIs allow for customization and the addition of new features not demonstrated in the SiteGenesis application.

## Inventory Scenarios

When dealing with inventory, there are many ways to manage inventory and communicate information about it to customers.

Inventory consists of the products you have available to sell. Review these scenarios, which illustrate how to use or extend the SiteGenesis application to track product stock levels, when considering your Salesforce B2C Commerce inventory implementation:

**note:** These models generally assume that you aren’t using Salesforce Omnichannel Inventory. Many of their details don’t apply to implementations that use Omnichannel Inventory.

| Model Name | Description                                                                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Model 1    | Consider all products permanently in stock.                                                                                                                                  |
| Model 2    | Some products have inventory records that control their availability. Other products without inventory records are considered to be permanently in stock.                    |
| Model 3    | All products are assumed to have inventory records. A front-end system frequently updates stock levels. There is no attempt to track inventory availability in B2C Commerce. |
| Model 4    | All products are assumed to have inventory records. B2C Commerce maintains stock levels for product display, cart display, and checkout.                                     |
| Model 5    | B2C Commerce maintains stock levels for product display and checkout. B2C Commerce calls the external inventory system at add-to-cart for a real-time stock level check.     |
| Model 6    | B2C Commerce maintains stock levels for product display and cart display. B2C Commerce calls the external inventory system at checkout for a real-time stock level check.    |

After reviewing these scenarios, answer the following questions and plan your inventory strategy.

1.  Do you maintain inventory levels?

    If no:

    - Do you want to treat all products as always available? Refer to Model 1 - No Product Records
    - Do you want to treat individual products as always available? Refer to Model 2 - Inventory Information for Some Products
      If yes:

    - What information can your Inventory Management System transmit to B2C Commerce?
    - Consider models 2 through 5.

2.  Do you support backorder or pre-order?

    If no:

    - How to you want to handle these orders? Refer to Model 3 - B2C Commerce Doesn't Calculate ATS Values and Model 4 - B2C Commerce Calculates ATS Values
    - What information does your Order Management System require?
      If yes, consider models 2 through 5.

3.  Do you support an in stock date?

    If no:

    - Do you want to treat all products as always available? Refer to Model 1 - No Product Records
    - Do you want to treat individual products as always available? Refer to Model 2 - Inventory Information for Some Products
      If yes, consider models 2 through 5.

4.  Can you support real-time stock level checks?

    If yes:

    - To check at Add-to-Cart, refer to Model 5 - Real-Time Inventory Availability At Add-to-Cart
    - To check at Checkout, refer to Model 6 - Real-Time Inventory Availability At Checkout

5.  Do you want to take a product off-line when out of stock?
    - If yes, refer to Common Implementations and Customizations
    - If no, no changes are required.
6.  How do you treat secondary products in a bundle? Refer to Updating Stock Levels
    - When the primary product becomes unavailable?
    - When the stock level of the primary product is incremented or decremented?
7.  How do you want to show unavailable products on category pages?
8.  Can you support partial inventory updates? If yes, how often do you want to run them?
9.  How often do you want to run full inventory updates?
10. Do you support bundled products? If yes, how do you structure order information that you transmit back to the order management system?

### Model 1 - No Product Records

Model 1 is appropriate for a merchant whose inventory is always physically in stock, and has no worries about product availability.

Module 1 is also appropriate for the merchant whose Inventory Management System is incapable of transmitting product availability data to Salesforce B2C Commerce.

**note:** This model can apply to implementations that use Salesforce Omnichannel Inventory.

This model considers all products permanently in stock. Standard B2C Commerce storefront functionality has two optional objects: `ProductInventoryList`(the inventory list) and `ProductInventoryRecord`(each product's inventory record).

If the following conditions exist:

1.  There is an inventory list.
2.  There are no product inventory records.
3.  `ProductInventoryList.DefaultInStock = true`

The result is that any particular product is considered to be in stock and available. The storefront behavior is as follows.

| Status        | Behavior                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------- |
| Available     | The product record appears in product detail, cart, and checkout views. The product can be ordered. |
| Backordered   | Not supported                                                                                       |
| Pre-ordered   | Not supported                                                                                       |
| Not available | Not supported                                                                                       |

### Model 2 - Inventory Information for Some Products

Model 2 is appropriate for a merchant who has some inventory that is always physically in stock.

Module 2 is also appropriate for a merchant who only monitors the availability of a subset of products.

This model has inventory records that control the availability of some products. Other products without inventory records are considered to be permanently in stock.

**note:** If you use Salesforce Omnichannel Inventory, then inventory records and availability data are managed in Omnichannel Inventory. The details of this model apply to implementations that don’t use Omnichannel Inventory.

If the following conditions exist:

1.  There is an inventory list that is periodically refreshed.
    - `ProductInventoryList.DefaultInStock = true`
2.  There are some product inventory records. The new and modified records have these values:
    - `ProductInventoryRecord.allocation = {units}`
    - `ProductInventoryList.perpetual = false`

The product inventory records can also have these values set. The values affect the calculation of ProductInventoryRecord.ATS.

- `ProductInventoryList.backorderable = true`
- `ProductInventoryList.preorderable = true`
- `ProductInventoryList.preorderBackorderAllocation= {units}`
- `ProductInventoryList.inStockDate= {date}`

Salesforce B2C Commerce calculates `ProductInventoryRecord.ATS = {units}` for all product records. The result is that any product without a product inventory record is considered to be in stock and available. Product inventory records for the other products indicate their availability.

The storefront behavior for products without inventory records is as follows.

| Status        | Behavior                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------- |
| Available     | The product record appears in product detail, cart, and checkout views. The product can be ordered. |
| Backordered   | Not supported                                                                                       |
| Pre-ordered   | Not supported                                                                                       |
| Not available | Not supported                                                                                       |

The storefront behavior for products with inventory records is as follows.

| Status        | Behavior                                                                                                 |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| Available     | The product record appears in product detail, cart, and checkout views. The product can be ordered.      |
| Backordered   | The product record appears. The product can be ordered. The backorder date appears in the shopping cart. |
| Pre-ordered   | The product record appears. The product can be ordered. The pre-order date appears in the shopping cart. |
| Not available | The product record appears with a no longer available message. The product can't be ordered.             |

### Model 3 - Salesforce B2C Commerce Doesn't Calculate ATS Values

Model 3 is appropriate for the merchant who is able to frequently refresh the inventory data in B2C Commerce.

The frequency would be sufficient to eliminate concerns about accidental out-of-stock conditions. Perhaps the merchant would only update product status for products that had been sold since the last full inventory update.

In this model, all products have inventory records, but there is no attempt to track inventory availability in B2C Commerce. B2C Commerce initially sets ATS equal to allocation, but both values remain unchanged after purchases. (The storefront doesn't use either the `UpdateStockLevel`pipelet or the `ProductAvailabilityModel.UpdateStockLevel()`method.) A front-end system frequently updates stock levels many times per day.

**note:** If you use Salesforce Omnichannel Inventory, then inventory records and availability data are managed in Omnichannel Inventory. The details of this model apply to implementations that don’t use Omnichannel Inventory.

If the following conditions exist:

1.  There is an inventory list that is periodically refreshed.
    - `ProductInventoryList.DefaultInStock = true`
2.  There are product inventory records for all products. The new and modified records have these values:
    - `ProductInventoryRecord.allocation = {units}`
    - `ProductInventoryList.perpetual = false`

Optionally, set these inventory record fields to support backorder. These record fields affect the calculation of `ProductInventoryRecord.ATS`.

- `ProductInventoryList.backorderable = true`
- `ProductInventoryList.preorderBackorderAllocation= {units}`
- `ProductInventoryList.inStockDate= {date}`

Optionally, set these inventory record fields to support pre-order. These record fields affect the calculation of `ProductInventoryRecord.ATS`.

- `ProductInventoryList.preorderable = true`
- `ProductInventoryList.preorderBackorderAllocation= {units}`
- `ProductInventoryList.inStockDate= {date}`

The result is that any product without a product inventory record is considered to be in stock and available. Product inventory records for the other products indicate their availability. There is no adjustment to allocation (stock level) values as products are sold.

The storefront behavior for products is as follows.

| Status        | Behavior                                                                                                 |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| Available     | The product record appears in product detail, cart, and checkout views. The product can be ordered.      |
| Backordered   | The product record appears. The product can be ordered. The backorder date appears in the shopping cart. |
| Pre-ordered   | The product record appears. The product can be ordered. The pre-order date appears in the shopping cart. |
| Not available | The product record appears with a no longer available message. The product can't be ordered.             |

### Model 4 - Salesforce B2C Commerce Calculates ATS Values

Model 4 is appropriate when you want to update B2C Commerce's inventory status. Update the inventory status once per day or less frequently. B2C Commerce can warn your customers when products are out of stock, on backorder, or pre-order.

In this model, all products have inventory records. B2C Commerce maintains stock levels for product display, cart display, and checkout. The merchant keeps inventory data reasonably fresh, perhaps with a daily batch feed.

**note:** If you use Salesforce Omnichannel Inventory, then inventory records and availability data are managed in Omnichannel Inventory. The details of this model apply to implementations that don’t use Omnichannel Inventory.

If the following conditions exist:

- There is an inventory list that is periodically refreshed.
- `ProductInventoryList.DefaultInStock = false`

There are product inventory records for all products. The new and modified records have these values:

- `ProductInventoryRecord.allocation = {units}`
- `ProductInventoryList.perpetual = false`

Optionally, set these inventory record fields to support backorder. These record fields affect the calculation of `ProductInventoryRecord.ATS`.

- `ProductInventoryList.backorderable = true`
- `ProductInventoryList.preorderBackorderAllocation = {units}`
- `ProductInventoryList.inStockDate= {date}`

Optionally, set these inventory record fields to support pre-order. These record fields affect the calculation of`ProductInventoryRecord.ATS`.

- `ProductInventoryList.preorderable = true`
- `ProductInventoryList.preorderBackorderAllocation {units}`
- `ProductInventoryList.inStockDate = {date}`

The result is that product inventory records indicate their availability. The calculated ATS values are presumed to be close to actual. The storefront behavior is as follows.

| Status        | Behavior                                                                                                 |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| Available     | The product record appears. The product can be ordered.                                                  |
| Backordered   | The product record appears. The product can be ordered. The backorder date appears in the shopping cart. |
| Pre-ordered   | The product record appears. The product can be ordered. The pre-order date appears in the shopping cart. |
| Not Available | The product record appears with a no longer available message. The product can't be ordered.             |

### Model 5 - Real-Time Inventory Availability at Add-to-Cart

Model 5 is appropriate when you want to minimize the risk of having a customer order a product that isn't available. And have your Inventory Management System respond to real-time requests for product inventory status.

Model 5 requires customization.

Salesforce B2C Commerce calls the front-end system at add-to-cart for a real-time stock level check. The merchant keeps inventory data reasonably fresh, perhaps with a daily batch feed.

**note:** This model doesn’t apply to implementations that use Salesforce Omnichannel Inventory.

If the following conditions exist:

- There is an inventory list that is periodically refreshed.
- `ProductInventoryList.DefaultInStock = true`

The result is that all products appear to be in stock until the customer attempts to add-to-cart. At this point, the customer can be notified that a product is partially or totally unavailable. B2C Commerce doesn't notify a customer of an availability issue at checkout. The storefront behavior is as follows.

| Status        | Behavior                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------- |
| Available     | The product record appears in product detail, cart, and checkout views. The product can be ordered. |
| Backordered   | Not implemented                                                                                     |
| Pre-ordered   | Not implemented                                                                                     |
| Not available | Not implemented                                                                                     |

### Model 6 - Real-Time Inventory Availability at Checkout

Model 6 is appropriate when you want to eliminate the risk of having a customer order a product that isn't available. And your Inventory Management System responds to real-time requests for product inventory status.

Model 6 requires customization of the SiteGenesis application.

Salesforce B2C Commerce calls the inventory system at checkout for a real-time stock level check. The merchant keeps inventory data reasonably fresh, perhaps with a daily batch feed.

**note:** This model doesn’t apply to implementations that use Salesforce Omnichannel Inventory.

If the following conditions exist:

- There is an inventory list that is periodically refreshed.
- `ProductInventoryList.DefaultInStock = true`

The result is that all products appear to be in stock until the customer attempts to check out. At this point, the customer is notified that a product is partially or totally unavailable. B2C Commerce doesn't notify a customer of an availability issue at add-to-cart. The storefront behavior is as follows.

|Status|Behavior|
|Available|The product record appears in product detail, cart, and checkout views. The product can be ordered.|
|Backordered|Not implemented|
|Pre-ordered|Not implemented|
|Not available|Not implemented|

## Updating Stock Levels

The mechanism for updating stock levels depends on the version of the API your storefront is using.

### Stock Level Update Cancellation or Replacement Mechanism

If an order is canceled or replaced, the inventory for the products in the order is updated. For example, if an order for five rings is canceled, the inventory for the rings increases by five. Because order cancellation and replacement are normally done through an integration with an order management system (OMS), there is no example of cancellation and replacement in SiteGenesis.

The stock update mechanism, which uses the `ReserveInventoryForOrder` pipelet is the recommended method for updating stock levels.

**note:** If you are using the inventory import feed to reset inventory levels, if the inventory level is set to zero via an import feed and an order is then replaced or canceled, the inventory is updated and the inventory level set to the quantity of inventory in the order. The replacement or cancellation is important in the case of a product recall or other situation in which you have decided to immediately stop selling a product and don't want it to appear as an available product.

Replacing an order uses the mechanism for canceling an order followed by the mechanism for creating an order. For replacement orders, the `ReserveInventoryForOrder` pipelet only reserves inventory for the new order and items for the order being replaced are available for the replacement order.

Order cancellation inventory Process

The following table shows the changes to inventory levels throughout the checkout process.

<table><col /><col /><col /><col /><col /><thead><tr><th>Checkout step</th><th>Pipelet</th><th>Change</th><th>Inventory Total</th><th>Example</th></tr></thead><tbody><tr><td>Customer has created an order, but hasn't entered the checkout process</td><td> </td><td> </td><td><p><emph>i</emph></p> <p><emph>i</emph> is the inventory at the start of the checkout process.</p></td><td><p>5 shirts, 3 pants, 10 caps available</p> <p>two shirts, one pants, three caps in order</p></td></tr><tr><td>Customer enters the checkout process for order X</td><td>ReserveInventoryForOrder</td><td>Reserves the change to the inventory for the order. This transaction includes an internal timestamp, so that reservations can timeout if the cart is abandoned.</td><td><p><emph>i - x</emph> (while the timestamp is valid)</p> <p>where:</p> <p><emph>i</emph> is the inventory at the start of the checkout process.</p> <p><emph>x</emph> is the quantity in order X.</p></td><td><p>Three shirts, two pants, seven caps available</p> <p>two shirts, one pants, three caps in reserved for order</p></td></tr><tr><td><p>Customer submits order X</p></td><td>CreateOrder</td><td>Finalizes the inventory change made using ReserveInventoryForOrder.</td><td><p><emph>i - x</emph></p></td><td>Three shirts, two pants, seven caps available</td></tr><tr><td>Customer cancels order X</td><td>CancelOrder</td><td>Returns the inventory for the order.</td><td><p><emph>i -</emph>x + <emph>x</emph></p> <p><emph>x</emph> is the quantity in order X.</p></td><td>5 shirts, 3 pants, 10 caps available</td></tr></tbody></table></sfdocstbl>
The cancellation mechanism isn't implemented in SiteGenesis, because replacement and cancellation are only used when Salesforce B2C Commerce is integrated with an order management system and SiteGenesis doesn't generally include integration functionality.

Order Replacement Inventory Process

The following table shows the changes to inventory levels throughout the checkout process. An order replacement is equivalent to an order cancellation followed by a new order, except that is it wholly handled by the `CreateOrder` pipelet. The process allows the inventory from the canceled order to be used for the new order. If the creation of the replacement order fails, the items continue to be reserved for the replacement order.

<table><col /><col /><col /><col /><col /><thead><tr><th>Checkout step</th><th>Pipelet</th><th>Change</th><th>Inventory Total</th><th>Example</th></tr></thead><tbody><tr><td>Customer has created an order, but hasn't entered the checkout process</td><td> </td><td> </td><td><p><emph>i</emph></p> <p><emph>i</emph> is the inventory at the start of the checkout process.</p></td><td><p>5 shirts, 3 pants, 10 caps available</p> <p>two shirts, one pants, three caps in order</p></td></tr><tr><td>Customer enters the checkout process for order X</td><td>ReserveInventoryForOrder</td><td>Reserves the change to the inventory for the order. This transaction includes an internal timestamp, so that reservations can timeout if the cart is abandoned.</td><td><p><emph>i - x</emph> (while the timestamp is valid)</p> <p>where:</p> <p><emph>i</emph> is the inventory at the start of the checkout process.</p> <p><emph>x</emph> is the quantity in order X.</p></td><td><p>Three shirts, two pants, seven caps available</p> <p>Two shirts, one pants, three caps in reserved for order</p></td></tr><tr><td><p>Customer submits order X</p></td><td>CreateOrder</td><td>Finalizes the inventory change made using ReserveInventoryForOrder.</td><td><p><emph>i - x</emph></p></td><td>Three shirts, two pants, seven caps available</td></tr><tr><td>Customer replaces order X with order Y</td><td>ReserveInventoryForOrder</td><td><p>Calculates the change in order quantities and reserves the new quantity.</p></td><td><p><emph>(x - y) = d</emph></p> <p><emph>i + d</emph></p> <p><emph>x</emph> is the quantity in order X.</p> <p><emph>y</emph> is the quantity in order Y.</p> <p><emph>d</emph> is the change quantity between in order X and Y. The change for each item in the order is calculated separately. The change can be either negative or positive depending on whether the replacement order item quantity is larger or smaller than the original order.</p></td><td><p>Four shirts, one pant, four caps in the new order</p> <p>One shirt, two pants, six caps available</p> <p>Four shirts, one pants, five caps in reserved for order</p></td></tr><tr><td> </td><td>CreateOrder</td><td>Updates the inventory for the order if the change, returning inventory if fewer items were ordered and finalizing the reservation if more items were ordered.</td><td><p><emph>i + d</emph></p> <p><emph>d</emph> is the change quantity between in order X and Y.</p></td><td><p>One shirt, two pants, six caps available</p> <p>Four shirts, one pants, five caps in reserved for order</p></td></tr></tbody></table></sfdocstbl>
The order replacement mechanism isn't implemented in SiteGenesis, because replacement is only used when B2C Commerce is integrated with an order management system and SiteGenesis doesn't generally include integration functionality.

Canceling or replacing orders in Business Manager

While you can manually cancel or replace orders in Business Manager, the process doesn't update the stock level for your storefront.

Canceling or Replacing Orders Using Order.SetStatus()

While you can manually cancel or replace orders using the `Order.setStatus()` method, the process doesn't affect the stock level.

### Stock Level Update Mechanism for Order Placement

The stock update mechanism prevents accidental overselling by reserving inventory early in the transaction and not finalizing the stock update until the order is placed.

<table><col /><col /><col /><col /><thead><tr><th>Checkout step</th><th>Pipelet</th><th>Change</th><th>Inventory Total</th></tr></thead><tbody><tr><td>Customer starts the checkout process</td><td> </td><td> </td><td><p>i</p> <p>where <emph>n</emph> is the inventory at the start of the checkout process.</p></td></tr><tr><td>After payment calculation and before personal information gathered</td><td>ReserveInventoryForOrder</td><td>Reserves the change to the inventory for the order. This transaction includes an internal timestamp, so that reservations can timeout if the cart is abandoned.</td><td><p><emph>i - x</emph> (while the timestamp is valid)</p> <p><emph>i</emph> (after the timestamp expires)</p> <p>where<emph>:</emph></p><ul><li><p><emph>n</emph> is the inventory at the start of the checkout process.</p></li><li><p><emph>a</emph> is the quantity in the order.</p></li></ul> <p /></td></tr><tr><td>After personal information gathered and before payment handling</td><td>CreateOrder</td><td>Finalizes the inventory change made using ReserveInventoryForOrder.</td><td><p><emph>i -</emph>x</p></td></tr></tbody></table></sfdocstbl>
An example of this mechanism is implemented in the SiteGenesis `COPlaceOrder` pipeline.

**note:** Using the `Order.setStatus()` method doesn't affect the stock level.

if an order is canceled or replaced, inventory isn't returned.

## Integration with Inventory Management Systems

Use the Salesforce B2C Commerce Inventory feature to track inventory levels between regular inventory updates to the production system from a backend inventory system.

Use the inventory levels to present more accurate stock level information to customers. Update the B2C Commerce inventory status in several ways:

- Frequently - every 15 minutes or every hour
- Infrequently - every 24 hours
- With complete replacements of the product inventory records
- With replacement of only those records that have changed

The data that the Inventory Management System transmits can be defined either:

- By the default inventory schema (`inventory.xsd`), which allows for a wide range of features.
- By a different schema (with customization) that has fewer, more, or different product inventory record attributes.

## Extend the ProductInventoryRecord Object

Extend the _ProductInventoryRecord_ object to store more fields.

For example, show a special message when the inventory of a particular product drops below its _threshold_ value. There are multiple steps to this process.

See Inventory.

1.  Extend the _ProductInventoryRecord_ object.

    1.  Select **Administration > Site Development > System Object Types.**

    2.  Select **ProductInventoryRecord** and click the **Attribute Definitions** tab.

    3.  Add the new object attribute.

2.  Add a new message to the `components.properties` resource file.

3.  Modify `availability.isml`to analyze and react to the _Threshold_ value.

```xml
<isif condition="${availabilityStatus == dw.catalog.ProductAvailabilityModel.AVAILABILITY_STATUS_IN_STOCK}">
  <span class="isinstock"> ${Resource.msg('components.common-details.005','components',null)} <br />
    <isif condition="${inventoryRecord != null && inventoryRecord.stockLevel.available}">
      <isif condition="${inventoryRecord.stockLevel.value <= inventoryRecord.Threshold. value }"> ${StringUtils. format(Resource.msg('components.custom.001','components',null)) }
         <isif condition="${inventoryRecord.ATS.available && inventoryRecord.ATS.value > inventoryRecord.stockLevel.value}">
            ${StringUtils.format(Resource.msg( 'components.common-details.008','components',null))}
        </isif>
      </isif>
    </isif>
  </span>
</isif>
```

## Inventory Transactions Clean Up

For instances that create many orders in a short time frame or at a constant high rate, retention of this inventory data slows checkout.

Load tests show a direct dependency between the number of existing transactions and the number of orders that can be created per second. The dependency is even more severe for flash sales where transactions are booked against only one or few distinct inventory records.

The _CleanupInventoryTransaction_ job, introduced in Release 17.1, runs hourly to delete zero amount inventory transactions and inventory transactions with zero sum corresponding to the same order.

You aren't permitted to update inventory allocation by setting the allocation reset date to older than it was. However, a feature switch lets you suppress this restriction in a case of an exception.

A quota checks for violations of this value. The quota: _The maximum hours reallocation date can be set in the past_ `( id="object.ProductInventoryRecordPO.maxReallocationTimeInPast" )` is set to 48 hours. The quota is violated if the inventory allocation reset date is set to a date earlier than 48 hours in the past.

**note:** Salesforce B2C Commerce doesn't enforce this quota because some customers must set an older allocation reset date.

We recommend that if your site doesn't violate this quote, you ask Support to enforce it for you. With enforcement, take advantage of the inventory transactions cleanup capability.

- When the quota is enforced, the _CleanupInventoryTransaction_ job cleans up all final inventory transactions older than the corresponding allocation reset date and older than 48 hours.
- When the quota isn't enforced, the _CleanupInventoryTransaction_ job cleans up all final inventory transactions older than the corresponding allocation reset date and older than 7 days.

<!-- document id=9a00a949e1c45842a9d689588875046e9cb49e5f9c4178f7da3f52a949186777 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/promotions/b2c-promotions-for-developers.md -->

# Customize Promotions

When configuring promotions for Salesforce B2C Commerce, extend your application to meet your unique campaign and promotion requirements using components such as:

- Business objects: add or change existing campaign, promotion, and promotion qualifier [business objects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/custom-objects/b2c-business-objects.md) to customize your application.
- APIs: use the B2C Commerce APIs that are specific for promotions.
- Templates: add or change templates.

Implement the following promotion types, which aren't included automatically in B2C Commerce:

- [Choice of Bonus Product Discount](https://help.salesforce.com/s/articleView?id=cc.b2c_implementing_choice_of_bonus_product_discount.htm)
- [Alert On Approaching Discount](#alert-on-approaching-discounts)

Customize your code to show [different promotional messages](#displaying-two-promotional-messages) on the product detail page, depending on if the product is a qualifying or discounted product (or both) for a promotion for which a customer qualifies. Use an alternate way to calculate tax for line items in an order, especially if your back-end systems can't handle order-level discounts.

Use the B2C Commerce APIs and Business Manager to handle qualifiers, such as source codes and coupons.

- Redirect customers programmatically when they enter source codes. See [URL Call to Pipeline Start Node for Source Codes](https://help.salesforce.com/s/articleView?id=cc.b2c_url_call_pipeline_start_node_for_source_codes.htm).
- [Dynamically map an incoming URL](https://help.salesforce.com/s/articleView?id=cc.b2c_dynamic_mapping_of_incoming_url_for_source_codes.htm) to navigate to a specific page or pages.
- Configure your coupons so that customers can [redeem multiple coupon codes](https://help.salesforce.com/s/articleView?id=cc.b2c_apis_for_coupons.htm) in the same order.

## Bonus Discount Promotions

Bonus products are a special, more complex discount than typical monetary or percentage discounts.

Bonus discounts describe the actual bonus products granted by the promotion rule. The current XML schema supports the definition of SKU lists of bonus products.

```xml
<xsd:complexType name="Bonus">
 <xsd:choice>
  <xsd:element name="bonus-products" type="BonusProductList" />
 </xsd:choice>
</xsd:complexType>
<xsd:complexType name="BonusProductList">
 <xsd:sequence>
  <xsd:element name="product-id" type="Generic.NonEmptyString.256" minOccurs="1" maxOccurs="unbounded" />
 </xsd:sequence>
</xsd:complexType>
```

## Displaying Two Promotional Messages

Customize your code to show different promotional messages on a product detail page, depending on whether the product is a qualifying or discounted product (or both) for a promotion for which a customer qualifies. This communicates a different message on the qualifying product than on the participating products.

For example, if you wanted to offer a gift with a purchase, you might want to say something like Buy a Sawzall and get a FREE Sawzall Blade Set - \$19.99 Value! on qualifying products, and Receive this Blade Set FREE with Purchase of Any Sawzall! on the discounted product. This doubles the potential exposure for a particular promotion, and hopefully, increases product revenue.

This feature isn't implemented in SiteGenesis. To implement this feature, you must add a custom attribute to handle the message for a qualifying product, and you must change your storefront code to show different promotion messages using specific APIs. If you don't change your storefront code, Salesforce B2C Commerce behaves as before (see Case C in the table below).

### How Do I Change My Storefront Code?

Use these methods to show different messages for a promotion on the product detail page, depending on the role the product plays in the promotion (qualifying or discounted).

| Method                                                                         | Description                                                                                                                                                                                |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `PromotionPlan.getProductPromotionsForQualifyingProduct(Product) : Collection` | Returns the product promotions for which the specified product is a qualifying, but not a discounted product.                                                                              |
| `PromotionPlan.getProductPromotionsForDiscountedProduct(Product) : Collection` | Returns the product promotions for which the specified product is a discounted (and possibly also a qualifying) product. It also returns promotions where the specified product is a bonus |

These methods provide an alternative to `PromotionPlan.getProductPromotions(Product) : Collection`. See the API documentation for details.

To use the new API methods, do the following:

1.  Define a custom attribute on the Promotion object type, for example, calloutMsg2, to hold the callout message relevant for qualifying products. Use the existing attribute calloutMsg for discounted products.
    - Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Site Development > System Object Types > _promotion_ > Attribute Definitions tab**, use the same parameters as for `calloutMsg.` Make sure you include your callout message attribute in an Attribute Grouping (click **Attribute Grouping** tab)
2.  Change all promotions to define two separate callout messages. If you don't want different messages for the two cases, duplicate the callout message to both attributes.
    - Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Online Marketing** > **Promotions** > **_promotion,_**. Enter information into the Qualifying Callout Message2 field that you just created.
3.  Change the storefront templates.

    - SiteGenesis currently uses template code such as the following to show information about the highest ranked promotion associated with a product:

      ```xml

                  promotions.isml
      <isset name="promos" value="${dw.campaign.PromotionMgr.getActiveCustomerPromotions().getProductPromotions(pdict.Product)}" scope="page"/>
      <isloop items="${promos}" var="promo">
          <!-- display calloutMsg for first returned promotion (omitted) -->
          <isbreak/>
      </isloop>
      ```

    - Replace this method call with code such as the following, which shows one of two different messages, depending on the relation of the product to the promotion:

      ```xml
      promotions.isml (new)
      <isset name="activeCustomerPromos" value="${dw.campaign.PromotionMgr.activeCustomerPromotions}" scope="page" />
      <isset name="productPromos" value="${activeCustomerPromos.getProductPromotions(pdict.Product)}" scope="page" />
      <isif condition="${! empty(productPromos)}">
        <isloop items="${productPromos}" var="promo">
          <isif condition="${activeCustomerPromos.getProductPromotionsForQualifyingProduct(pdict.Product).contains(promo)}">
           <isprint value="${promo.custom.calloutMsg2}" encoding="off"/>
          <iselse>
            <isprint value="${promo.calloutMsg}" encoding="off"/>
          </isif>
          <isbreak/>
        </isloop>
      </isif>
      ```

For more information, see [Product Promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_product_promotions.htm).

## Sample Extensions for Promotions

Use these approaches to extend Salesforce B2C Commerce to meet your unique campaign and promotion requirements:

| If you want to...                                                                                                             | The implementation might look like...                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Display popup storefront ads for a featured campaign                                                                          | <ul><li>Create additional attributes that the merchant or marketer can manage by entering text to be used as a popup window title and HTML to be used to populate the window body.</li><li>Define the business logic the system will use to determine when, where and which popup ad to show if more than one is defined.</li></ul>                                                                                                                                                                                          |
| Implement dynamic messaging in the cart for order promotions, such as: Spend X more and be eligible for an additional 10% off | <ul><li>Define additional attributes that merchant can use to control message text and identify custom threshold values.</li><li>Define the business logic used to dynamically calculate how much more a consumer must spend to qualify for an order promotion discount.</li><li>Define the presentation logic for rendering the dynamic message in the cart.</li></ul>                                                                                                                                                      |
| Map promotions to print catalogs                                                                                              | <ul><li>Use the source code framework to implement this functionality, which also lets the merchant trigger the pricing (using price books) and promotions featured in that catalog, and define storefront redirect behavior.</li><li>Create source codes.</li><li>Map source codes to promotions, price books.</li><li>Add a text entry box to the storefront where consumers can provide the catalog source code.</li></ul>                                                                                                |
| Attach images to promotions as attention grabbers within the storefront                                                       | <ul><li>Create icons that represent _hot deals_ or _free shipping,_ for example.</li><li>Map these images to the general image attribute for each promotion.</li><li>Define the presentation logic and handling of these images in the storefront.</li></ul>                                                                                                                                                                                                                                                                 |
| Implement custom landing pages for campaigns or promotions that are featured in email campaigns                               | <ul><li>Create custom landing page content assets.</li><li>Define logic for rendering content asset on a custom landing page.</li><li>Share links to custom landing pages with the marketing team.</li><li>Consider using the source code framework. This framework already contains logic to handle a link that redirects to specified page (custom landing page). Additionally, the link can activate the associated promotions and price books. Analytics for source code conversion is standard functionality.</li></ul> |
| Modify how promotions are processed                                                                                           | <ul><li>Modify the CalculateCart.ds script to meet your requirements.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                              |

**note:** Modification details will depend on your specific implementation.

## Alert on Approaching Discounts

Salesforce B2C Commerce can calculate discounts for which a basket almost qualifies. These discounts are called approaching discounts or upsell discounts. The API retrieves the collection of discounts that almost qualify and shows a message for one or more of them in the storefront.

These promotion types have an Alert flag in Business Manager that controls whether customers are notified of the promotion before they fully meet the merchandise conditions:

- Order: with amount of order merchandise total
- Shipping: with amount of shipment merchandise total

If the Alert flag is set, specify a monetary value threshold that determines how close the customer must be in order to be notified of the discount. If the value is omitted, the customer is alerted as long as their basket is under the discount threshold. For tiered promotions, the alert only triggers for the lowest tier.

### Examples

Suppose a merchant has three active promotions:

| Promotion | Description                                | Enable upsells | Upsell threshold |
| --------- | ------------------------------------------ | -------------- | ---------------- |
| 1         | 10% off orders over \$150                  | true           | 50               |
| 2         | 20% off orders over \$200                  | true           | 75               |
| 3         | Free ground shipping for orders over \$200 | true           | 60               |

**Case 1**

A customer has \$140 worth of merchandise in their cart, but doesn't qualify for any of the promotions. The API returns all three approaching discounts because the cart is within the thresholds defined by all three promotions.

**Case 2**

A customer has $150 worth of merchandise in their cart and receives 10% off their order due to Promotion 1. The merchandise total is now $135. The basket is within the threshold for Promotion 2, so the customer sees the upsell message for Promotion 2:

`"Buy $65 more worth of merchandise and receive '20% off orders over $200.00'"`

The customer doesn't see upsell message for Promotion 3 because the merchandise total after order discounts is $135, which is less than $140 and therefore not within the threshold range defined by that promotion.

**note:** B2C Commerce doesn't consider the exclusivity or rank of promotions in the PromotionPlan during this process. The reason is that the rank of two promotions that are based on the amount of merchandise total is irrelevant if the cart satisfies one condition threshold but not the other. In this case, the cart receives the discount for the promotions whose condition is satisfied, regardless of rank. Only when the cart satisfies the thresholds for both, can rank make a difference.

### Adding Approaching Discounts to Your Application

Additional support is needed for this feature to your storefront application. To help you, we’ve provided this feature in the SiteGenesis application as follows:

- In the SiteGenesis demo data, all order promotions of type With amount of qualifying products and shipping promotions or With amount of shipment qualifying products have Enable Upsells set to true with thresholds defined.
- The cart page shows order and shipping promotions for which customers almost qualify.
- The shipping page shows shipping promotions for which the customer almost qualifies.

### Use These APIs

Use these APIs to implement approaching discount in your application.

**ApproachingDiscount**

The API class ApproachingDiscount, which represents a discount that a customer almost qualifies for based on the merchandise in their cart has these methods:

| Method                                      | Description                                                                                                                       |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Discount getDiscount()`                    | The discount the customer receives if they add more merchandise to the cart.                                                      |
| `Money getConditionThreshold()`             | The amount of merchandise required in the cart in order to receive the discount.                                                  |
| `Money getMerchandiseValue()`               | The amount of merchandise in the cart contributing towards the condition threshold (is always less than the condition threshold). |
| `Money getDistanceFromConditionThreshold()` | The amount of additional money needed in the order or shipment to receive the discount.                                           |

**DiscountPlan**

The API class DiscountPlan, which retrieves the collection of discounts the cart almost qualifies for has these methods:

| Method                                                                                         | Description                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Collection getApproachingOrderDiscounts()`                                                    | Gets the collection of order discounts that the LineItemCtnr almost qualifies for based on the merchandise total in the cart. Here almost is controlled by thresholds configured at the promotion level.                                                                                                                        |
| `Collection getApproachingShippingDiscounts(Shipment shipment, Collection shippingMethods)`    | Gets the collection of shipping discounts that the passed shipment almost qualifies for based on the merchandise total in the shipment. Here almost is controlled by thresholds configured at the promotion level. This method only returns discounts for shipping promotions that apply to one of the passed shipping methods. |
| `Collection getApproachingShippingDiscounts(Shipment shipment, ShippingMethod shippingMethod)` | Same as before, but filters by only a single shipping method.                                                                                                                                                                                                                                                                   |

B2C Commerce calculates approaching promotions based on DiscountPlan and not the cart directly. DiscountPlan is a formal description of discounts to be applied on a line item. B2C Commerce calculates the discounts themselves based on a specific set of promotions, that is, the PromotionPlan. It only selects approaching discounts from promotions in the original PromotionPlan. Removing discounts from the DiscountPlan has no effect on the approaching discounts returned by the API, and isn't supported.

**How the APIs Work**

Order promotions - The API retrieves the approaching order discounts of an order. An order can have approaching discounts even if it has actual applied discounts. To determine the approaching discounts, B2C Commerce:

1.  Reviews each non-applied order promotion in the original PromotionPlan with the enable upsells flag on.
2.  Determines if the order is within the condition threshold for the promotion rule by comparing the merchandise total of the DiscountPlan after product and order discounts are applied against the condition threshold.
3.  If the merchandise total is within the range, includes the promotion in the returned collection. This collection can include multiple order promotions.
4.  Sorts the returned collection by the condition threshold ascending. Merchants typically want to show one promotion that represents the smallest amount of merchandise the customer must add to the cart to get a discount. Some merchants, however, want to show multiple messages. For example: "10% off orders over $200. 20% off orders over $300".

Shipping promotions - Approaching shipping discounts are calculated in a similar way. The API retrieves the approaching shipping discounts for each shipment in an order based on a set of shipping methods. A shipment can have approaching shipping discounts even if it has actual applied shipping discounts. When determining the approaching discounts, B2C Commerce:

1.  Reviews each non-applied shipping promotion in the original PromotionPlan with the enable upsells flag on.
2.  Filters promotions that don't apply to any of the included shipping methods.
3.  For each remaining promotion, determines if the shipment is within the condition threshold for the promotion rule. It determines this by considering the merchandise total of the shipment before other shipping discounts (and after product and prorated order discounts).
4.  Sorts the returned collection by the condition threshold ascending. This collection can include multiple shipping promotions.

**Example**

Using the API, retrieve the list of approaching promotions from within a template and show the appropriate messages, as shown in this example:

```xml
<!-- Approaching order promotions -->
 <isset name="DiscountPlan" value="${dw.campaign.PromotionMgr.getDiscounts(pdict.Basket)}" />
 <isloop items="${DiscountPlan.getApproachingOrderDiscounts()}" var="orderDiscount">
  Buy <isprint value="${orderDiscount.getDistanceFromConditionThreshold()}" />
  more worth of merchandise and receive:
  ${orderDiscount.getDiscount().getPromotion().getCalloutMsg()}<br/>
 </isloop>
<!-- Approaching shipping promotions (for default shipment) -->
 <isset name="Shipment" value="${pdict.Basket.getDefaultShipment()}" />
 <isset name="ShippingMethods" value=
 "${dw.order.ShippingMgr.getShipmentShippingModel(Shipment)
 .getApplicableShippingMethods()}" />
 <isloop items="${DiscountPlan.getApproachingShippingDiscounts(Shipment, ShippingMethods)}" var="shippingDiscount">
  Buy <isprint value="${shippingDiscount.getDistanceFromConditionThreshold()}" />
  more worth of merchandise and receive:
  ${shippingDiscount.getDiscount().getPromotion().getCalloutMsg()}<br/>
 </isloop>
```

## Product Shipping Promotion Elements

The `product.xsd` schema supports product shipping promotions.

Import and export product shipping promotions that are specified in `promotions.xsd` support the following elements:

- `<shipping-methods>` in `ProductPromotionRule`.
- `<fixed-price-shipping>` and `<free-shipping>` in `SimpleProductDiscount` and `TieredProductDiscount`.

## APIs for Promotions

Create Salesforce B2C Commerce promotions in a B2C Commerce tool (such as Business Manager) and access these promotions via the B2C Commerce API.

### Promotion Pipelets

Use the `AddBonusProductToBasket` pipelet to implement a [choice of bonus product discount](https://help.salesforce.com/s/articleView?id=cc.b2c_implementing_choice_of_bonus_product_discount.htm).

### Promotion Scripting APIs

Access B2C Commerce promotions via the scripting API, which provide a well-defined process that identifies, prioritizes, and applies promotions:

1.  Manipulate the result of each process step
2.  Implement custom business rules
3.  Expose relevant promotion information

Access to B2C Commerce promotions is via the classes available in the dw.Campaign package.

Use the `dw.Order` package for certain promotion types.

- `BonusDiscountLineItem`
- `CouponLineItem`
- `PriceAdjustment`
- `ProductShippingLineItem`
- `ShippingMgr`
- `ProductLineItem` (See [API Bonus Promotion Positioning](#api-choice-of-bonus-product).)

To learn about specific promotion areas, see the Related links section below.

**note:** APIs are release-specific and subject to change. Check the API documentation for the release you are using.

### API: Storefront Search for Products Eligible for Promotion

Use the Salesforce B2C Commerce API to search for all products that are eligible for a promotion, whether they are qualifying or discounted. Search for qualifying products only, discounted products only, or both.

Use the _PromotionProductType_ input parameter in the _Search_ pipelet and the _ProductSearchModel_ scripting class to perform this level of search.

- Valid values for the B2C Commerce Script API parameter are: _all_, _bonus_, _discounted_, _parameter_, and _qualifying_.
- Valid values for the pipelet parameter are _all_, _qualifying_, and _discounted_.

**note:** For the Search pipelet, the same product can be returned by all three types of search. This behavior is different than the API methods _PromotionPlan.getProductPromotionsForQualifyingProduct(Product)_ and _getProductPromotionsForDiscountedProduct(Product),_ which never return the same promotion for a given product.

The products returned by this type of product search depend on the class of the promotion and other aspects of its configuration. The rules are listed below.

**All Promotion Types**

For all promotion types, the promotion must be marked as _searchable_ if you want to search for products using that promotion. A product isn't returned by a product search if it's globally excluded, and the individual promotion doesn't disable global product exclusions.

There are additional rules, as follows, by promotion class:

**Product Promotions**

For product promotions, a search for qualifying or discounted products returns a product if that product satisfies the qualifying or discounted product rule, respectively.

**Order Promotions**

For order promotions:

- A product isn't returned by a search if it satisfies the order promotion excluded products rule.
- If the promotion has an explicit qualifying product rule (for example, only products in a specific category qualify), a product must satisfy the rule in order to be returned by a qualifying product search.
- If the promotion doesn't have an explicit qualifying product rule, all products are returned by a qualifying product search.
- If the order promotion is configured so that discounted products is equal to qualifying products, a discounted product search will return the same products as a qualifying product search. Otherwise, all products participating in the discount are returned by a discounted product search.

**Shipping Promotions**

For shipping promotions:

- If the promotion has an explicit qualifying product rule (for example, only products in a specific category qualify), a product must satisfy the rule in order to be returned by a qualifying product search.
- If the promotion doesn't have an explicit qualifying product rule, all products are returned by a qualifying product search.
- No products are returned by a discounted product search because this makes no sense for shipping promotions.

**important:** You must rebuild the product index for this feature to take effect. Because only promotions marked as _searchable_ are included, if you don't want the behavior to occur, explicitly mark all shipping and order promotions as _not searchable._ In general, if you don't use this feature in the storefront, it's better to mark promotions as _not searchable_, because setting them to _searchable_ will increases indexing time.

### API: Product Promotional Price

Use the Salesforce B2C Commerce APIs to show the promotional price of a product on the product detail page or on a product list.

The API provides the calculated price of an item via the `getPromotionalPrice` method (of the `dw.campaign.Promotion` class) if there is an applicable item level promotion (\$ off, % off, or fixed price promotions without qualifying products only).

**note:** The customer will only see promotions for which they are eligible.

#### Example

To calculate the promotional price, the `getPromotionalPrice` method uses the current sales price of the product for quantity 1.0, and applies the discount associated with the promotion to this price. If the product price is \$14.99, and:

| The promotion discount is... | The method will return... |
| ---------------------------- | ------------------------- |
| 10%                          | \$13.49                   |
| \$2                          | \$12.99                   |
| \$10.00 fixed price          | \$10.00                   |

To calculate the promotional price using the second version of the method (`getPromotionalPrice(product : Product, optionModel : ProductOptionModel`) using the `ProductOptionModel` parameter, consider a product base price of $15.00 and a selected options surcharge of $5.00.

| The promotion discount is... | The method will return... |
| ---------------------------- | ------------------------- |
| 10%                          | \$18.00                   |
| \$2                          | \$18.00                   |
| \$10.00 fixed price          | \$15.00                   |

For percentage discounts, the discount is applied to the option surcharge, and for the other discount types, it only applies to the base product price.

#### dw.campaign.Promotion

**Promotional Price**

This class provides the following methods to calculate the promotional price of a product without actually adding the product to the basket and applying the promotion using the PromotionMgr API:

- `getPromotionalPrice(product : Product) : Money`
- `getPromotionalPrice(product : Product, optionModel : ProductOptionModel) : Money`

These methods are useful on product pages when you want to show the actual product price to the customer. These methods are restricted to simple product promotions without qualifying products and of discount type _percentage,_ _amount_ or _fixed price._ The methods don't consider the case of multiple promotions applying to a single product. As a result, there might be cases where the returned price doesn't reflect the actual charge to a consumer; but the methods should return accurate values in most scenarios.

**Promotion Class**

When using the `getPromotionClass()` method, consider the following:

- A promotion can be combined in the shopping cart with other active product promotions, resulting in a different price reduction. Promotional price isn't considered for product sorting. The API doesn't consider dependencies between promotions.
- When implementing this feature, consider the currently selected product options. If a product option is selected by the customer, the _value_ of the promotional discount message should be calculated on the total value of the item (which would include _surcharges_). For example, if the currently selected product options add a surcharge to the product, a "10% off promotion" should also take 10% off the surcharge.

### API: Shipping for Promotions

While promotions are evaluated and applied as one step of the basket calculation, other steps are:

- Determining product prices
- Calculating taxes
- Calculating shipping costs

Use the Salesforce B2C Commerce APIs to calculate and access shipment-level and product-level shipping costs. When using the `applyShippingCost` method (`dw.Order.ShippingMgr` Class), for example, the cart calculation script is simple:

```javascript
{
 ...
  dw.order.ShippingMgr.applyShippingCost(basket)
 ...
}
```

#### dw.order.ProductShippingLineItem Class

Use the B2C Commerce APIs to access product shipping costs. Product line items can have one dependent shipping line item. This shipping line item represents either the fixed or the surcharged shipping cost for this product line item. The price of the shipping line item is per product unit, and the shipping line item has a quantity field. The product shipping line item only exists if the product has individual shipping cost.

The following sample script accesses the product shipping costs:

```javascript
for(productLineItem : ProductLineItem, shipment.productLineItems)
{
	shippingLineItem : ProductShippingLineItem = productLineItem.shippingLineItem;
	if(shippingLineItem != null)
	{
		cost : Money = shippingLineItem.price;
	}
}
```

The following methods of this class support product shipping discounts:

- `getAdjustedGrossPrice() : Money`
- `getAdjustedNetPrice() : Money`
- `getAdjustedPrice() : Money`
- `getAdjustedTax() : Money`
- `getPriceAdjustments() : Collection`

#### dw.order.Shipment Class

Use the methods of this class to return the accumulated value of all shipment shipping line items and all product shipping line items in the shipment. If any of these shipping line items is N/A, the total price is N/A.

#### dw.order.ShippingLineItem Class

With this class, create, retrieve, and remove arbitrary shipping price adjustments (that is, price adjustments not controlled by B2C Commerce) and associate those adjustments with a specific shipping line item. This is useful for merchants who use multiple shipping line items to model various types of shipping charges, instead of just the standard shipping line item for all shipping costs.

#### dw.order.LineItemCtnr Class

The methods of this class return the accumulated value of all shipment shipping line items and all product shipping line items in the container. If any of these shipping line items is N/A, the total price is N/A.

#### dw.campaign.PromotionPlan

Fetch applicable shipping promotions during checkout using the methods in this class. Show _potential_ shipping promotions to the customer during the checkout process.

**note:** The SiteGenesis application doesn't show shipping promotions for unselected shipping methods.

### API Choice of Bonus Product

When implementing a choice of bonus product discount, use both scripting APIs and pipelets.

#### Salesforce B2C Commerce Script APIs

Use these B2C Commerce Script API classes to access the choice of bonus product discount feature:

- `dw.order.BonusDiscountLineItem`
- `dw.order.LineItemCtnr (getBonusDiscountLineItems())`
- `dw.campaign.BonusChoiceDiscount`

#### Pipelets

The `AddBonusProductToBasket` pipelet adds a bonus product to the basket associated with a specific bonus discount line item. This pipelet doesn't set the price of the bonus product. Salesforce B2C Commerce sets the price of selected bonus products when applying discounts.

Your code must use this pipelet instead of the standard `AddProductToBasket` pipelet to add bonus items to the basket.

When the `ProductLineItem` representing the selected bonus product is created using this special pipelet, it acts like a normal ProductLineItem. All normal methods can be called on it.

It is the responsibility of application logic to prevent the line items from being modified unexpectedly. For example, your application shouldn't let the customer change the quantity of the line item in the cart beyond the limits allowed by the discount, or change the product associated with the line item to a non-discounted product.

### APIs for Get Promotion Products

Using the Salesforce B2C Commerce APIs, search for all qualifying/discounted products that are associated with one or more product promotions and show them in one place on the storefront, giving customers more information and choices to help make better buying decisions.

For example, a storefront home page shows a promotion teaser "Buy 3 Shirts Get 1 Free". When the customer clicks the teaser, a list of all the qualifying shirts appears. Shirts that are sold out aren't included on the list. The customer can then refine the list by brand and sort the list by price. An example of refining search results by multiple promotions, is to filter search results to return products that qualify for either a 20% discount or a free bonus item.

**note:** This API only works for promotion type _Product._

The APIs for _Get promotion products_ are based on storefront search and can therefore be combined with other search refinements such as category, price, brand, and color.

#### Refining by Multiple Promotions

**note:** Refining by multiple promotions only works when the feature toggle, `Enable Multiple Promotions on Refinements`, is enabled. To enable the feature toggle, contact Customer Support.

Programmatically refine by multiple promotions using the following:

- B2C Commerce API (SCAPI): Use the `refine` parameter with the [Shopper Search `productSearch` endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch), for example: `refine=pmid=20-off-clothes|15-off-shoes`.
- Pipelet: use the `Search` pipelet to pass in a promotion ID value.
- B2C Commerce Script API: use the `dw.catalog.ProductSearchModel` B2C Commerce Script API to pass in a promotion ID value.
- Pipeline: use `Search URL` (in the Search pipeline) for a search result refined by multiple promotions.

The promotion ID is consumed by the Search pipelet and the search result contains only products for both promotions. To refine your search by multiple promotions via, use the `promotionID` parameter to enter a list of promotion IDs, separated by |, for example, `10%OFF|20%OFF.`

The following `dw.catalog.ProductSearchModel` methods support this feature:

| Method                                        | Description                                                                                  |
| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `getProducts() : String`                      | Returns the products in the search results.                                                  |
| `getPromotionID() : String`                   | Returns the promotion with the specified ID.                                                 |
| `setPromotionIDs(List promotionIDs) : String` | Specifies multiple promotion ids used for the search query. Supports up to 30 promotion IDs. |

When using the Search URL sub-pipeline, the value of the URL parameter `pmid` contains a list of promotion IDs separated by |, for example:

`.../search?prefn1=color&prefv1=red|green &pmid=10%OFF|FREE_BONUS`

#### Promotion Types and Discounts

Promotions can have qualifying or discounted products, or both. In many cases, qualifying and discounted products are the same. For the various combinations of promotion types and discount types, products of a promotion are returned by these APIs as follows:

<table><col /><col /><col /><thead><tr><th>Promotion type</th><th>Discount type</th><th>Products returned</th></tr></thead><tbody><tr><td><p>Without qualifying products</p> <p>With amount of qualifying products</p> <p>With number of qualifying products</p></td><td><p>Percent Off</p> <p>Amount Off</p> <p>Fixed Price</p>Percent Off Product Options<p>Price From Price Book</p> <p>Fixed Price Shipping</p> <p>Free Shipping</p></td><td><p>Discounted products/options</p></td></tr><tr><td><p>Buy X For Total</p></td><td><p>n/a</p></td><td><p>Discounted products</p></td></tr><tr><td><p>Buy X Get Y</p></td><td><p>Percent Off</p> <p>Amount Off</p> <p>Fixed Price</p> <p>Price From Price Book</p> <p>Free</p></td><td><p>Qualifying and discounted products</p></td></tr><tr><td><p>Without qualifying products</p> <p>With amount of qualifying products</p> <p>With number of qualifying products</p></td><td><p>Bonus Products</p> <p>Choice Of Bonus Products</p></td><td><p>Qualifying products</p></td></tr></tbody></table></sfdocstbl>

#### Business Manager

To use this feature, you must set the promotion to _searchable_ in Business manager. B2C Commerce considers a product promotion to be searchable if its _Searchable_ flag is set to _True_ and if it's active at any time 20 days in the past, any time 20 days in the future, or is currently active in the context of a campaign or A/B test.

When you create a new promotion or update the product rule of an existing promotion, you must perform a full rebuild of the product search index to include the updated promotion details. When the customer searches for a product in the storefront, and B2C Commerce executes a specific promotion ID, B2C Commerce looks for products that have this promotion ID incorporated into their index documents.

Promotion price and price book conditions are evaluated based on the price books assigned to the site at index time. Price books assigned to a session programmatically during run time aren't considered.

#### Example: Storefront Implementation

This is a storefront implementation example:

The Search pipeline supports the `pmid` (promotion ID) parameter. Use this in your application to show a promotion within a content asset.

- Suppose you create a promotion with the following values:
  - ID: 40off-womenfootwear-selected
  - Description: 40% Off dark Women's Shoes priced \$50 or more
  - Enabled: Yes
  - Searchable: Yes
  - Promotion Class: Product Without Qualifying Products
  - Discounted Products: Products in category _womens-footwear(Footwear)_ or subcategories, and with price >= \$50.00, and with attribute color = black, brown, or navy.
- Next, you add an image that shows the add called: _Save Up To 40% On Select Women's Footwear Styles._
- Next, you create a content asset (or edit an existing one) to contain a promotion search link as follows:

  _/Search-Show?pmid=40off-womenfootwear-selected_ on the image _Save Up To 40% On Select Women's Footwear Styles._

### APIs for Deal of the Day

Use the Salesforce B2C Commerce APIs to run a series of time-based promotions, such as "deal of the day" campaigns, by using methods that retrieve specific promotions within a campaign, based on time.

Multiple deal of the day campaigns can run at the same time (deal of the day, week, month, or year), where the storefront user will see the currently active deal, the number of missed deals, and the number of upcoming deals. Each deal is a promotion. All deals of the day are bundled in a campaign.

- Use the following methods from the `dw.campaign.PromotionMgr` class to retrieve promotions by the dates they are active. These methods differ from methods such as `getUpcomingPromotions()` in that they retrieve promotions assigned to a specific campaign and active within a specific date range, including past dates.
  - `getActivePromotionsForCampaign(Campaign campaign, Date from, Date to) : PromotionPlan`
  - `getActiveCustomerPromotionsForCampaign(Campaign campaign, Date from, Date to) : PromotionPlan`
- Use the following method from the `dw.campaign.PromotionPlan` class to sort promotions by start date.
  - `getPromotions(int sortOrder) : Collection`
- Use the following methods from the dw.campaign.Promotion class to access start and end dates.
  - `getStartTime() : Date`
  - `getEndTime(): Date`

### API: Bonus Promotion Positioning

When you configure bonus product promotions such as Buy any television, and get a free remote control, you might want the free remote to appear immediately after the television in the cart.

By default, Salesforce B2C Commerce sorts bonus products at the end of the cart. If the customer purchases any other merchandise, the free remote will most likely be positioned after the new items. By default, there is no programmatic connection between a bonus product and its qualifying product's product line items through the API.

Use the following methods, however, to determine the qualifying products that trigger a bonus product for a product promotion that is based on a number of qualifying products. Use this to show bonus products together with their _triggering_ products in the cart. To activate these methods, you must enable them via a [promotion site preference](https://help.salesforce.com/s/articleView?id=cc.b2c_configuring_promotion_preferences.htm). When this preference is enabled, B2C Commerce consolidates bonus products into a single product line item. These are the methods, located in the dw.order package, and the ProductLineItem class:

<table><col /><col /><thead><tr><th>Method</th><th>Description</th></tr></thead><tbody><tr><td>ProductLineItem getQualifyingProductLineItemForBonusProduct();</td><td><p>Returns the ProductLineItem that qualified the basket for this bonus product. This method is only applicable if the product line item is a bonus product line item, and if the promotion is a product promotion with a <emph>number of qualifying products</emph> that grants a bonus-product discount.</p> <p>If these conditions aren't met, the method returns null.</p> <p>If there are multiple product line items that triggered this bonus product, the method returns only the last one by position within the order.</p></td></tr><tr><td>Collection getRelatedBonusProductLineItems();</td><td><p>Returns all bonus product line items for which this line item is a qualifying product line item. This method is usually called when rendering the cart so that bonus products can be shown next to the products that triggered their creation.</p></td></tr></tbody></table></sfdocstbl>
SiteGenesis shows bonus products immediately after the qualifying products that triggered their creation with no changes to templates. Bonus products that don't have a clear qualifying product appear at the end of cart.

It isn't possible to import an order in such a way to indicate a connection between a bonus product line item and a qualifying product line item. (The _bonus_ flag isn't included in order export.)

### Promotion APIs for A/B Testing

Use the Salesforce B2C Commerce APIs for when a promotion is assigned to an A/B test and not to a campaign. These classes return a placeholder campaign, representing A/B tests, for API methods that return or process a campaign instance, when an A/B test (not a campaign) is in effect.

- `dw.campaign.Campaign`
- `dw.campaign.CampaignMgr`
- `dw.campaign.Promotion`
- `dw.campaign.PromotionMgr`

  **note:** Returned PromotionPlans don't contain multiple Promotion objects with the same ID.

- `dw.campaign.PriceAdjustment`

  **note:** A/B tests are just another case of a promotion without an associated campaign.

The method `Promotion.getCampaign.getCustom` isn’t accessible when a promotion is assigned to an A/B test and not a campaign. The method returns an empty map because this object isn't derived from an extensible object. The method promotions.campaign is a dummy object, which is an instance of `dw/object/ExtensibleObject.java`. When the method promotions.campaign.custom is called, the getCustom method on `dw/object/ExtensibleObject.java` is called and returns the “ExtensibleObjectAttributes id“ value. When a promotion or price adjustment is the result of an A/B test, the method Promotion.getCampaign.getID() always returns AB Testing.

When a promotion or price adjustment is the result of an A/B test, these methods return the following:

| With this method...                 | Returns...                 |
| ----------------------------------- | -------------------------- |
| `Promotion.getCampaign`             | placeholder campaign       |
| `Promotion.getCoupons`              | empty collection           |
| `Promotion.getCustomerGroups`       | empty collection           |
| `Promotion.getSourceCodeGroups`     | empty collection           |
| `Promotion.isBasedOnCoupon`         | false                      |
| `Promotion.isBasedOnCoupons`        | false                      |
| `Promotion.isBasedOnCustomerGroups` | false                      |
| `Promotion.isBasedOnSourceCodes`    | false                      |
| `PriceAdjustment.getCampaign`       | placeholder campaign       |
| `PriceAdjustment.getCampaignID`     | ID of placeholder campaign |
| `PriceAdjustment.getCouponLineItem` | null                       |
| `PriceAdjustment.isBasedOnCampaign` | true                       |
| `PriceAdjustment.isBasedOnCoupon`   | false                      |

[A/B Testing](https://help.salesforce.com/s/articleView?id=cc.b2c_ab_testing.htm)

## Related Links

[Campaigns and Promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_campaigns_and_promotions.htm)

[Promotion Discounts](https://help.salesforce.com/s/articleView?id=cc.b2c_promotion_discounts.htm)

[Qualifying and Discounted Products](https://help.salesforce.com/s/articleView?id=cc.b2c_qualifying_and_discounted_products.htm)

[Implementing Choice of Bonus Product(s) Discount](https://help.salesforce.com/s/articleView?id=cc.b2c_implementing_choice_of_bonus_product_discount.htm)

[Restricting Promotions to Identical Products](https://help.salesforce.com/s/articleView?id=cc.b2c_restricting_promotions_to_identical_products.htm)

<!-- document id=4ac90bff7a75ed5996dbc19ae141cc730ff8215523e65de060549433c1f9c32e url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-customizing-sfra.md -->

# Customize SFRA

Storefront Reference Architecture (SFRA) is extensible. Customize SFRA without editing the `app_storefront_base` cartridge or other plug-ins, such as `plugin_applepay`. The extensible design lets you more easily take security updates, bug fixes, and adopt new features.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Add Custom Cartridges

Implementing a site requires at least one custom cartridge. However, if you intend to create multiple sites, we suggest you create multiple custom cartridges. Each cartridge can separate functionality specific to a brand or locale, so that you can reuse most of your cartridge stack for a new site.

All available LINK and plug-in cartridges are on GitHub. Plug-in cartridges are in the SFRA project in GitHub. Include link and plug-in cartridges on your cartridge path and base path as you would any other cartridge in your stack.

**note:** Don't rename the `app_storefront_base` cartridge or other provided plug-ins. Keep your version of the `app_storefront_base` cartridge and other plug-ins up-to-date. By doing so, you make sure that you have the latest bug fixes and performance improvements.

### Adding Custom Cartridges When `sgmf-scripts` Is Globally Installed

If you globally installed `sgmf-scripts` through npm, follow these steps to add a custom cartridge:

1.  Create a folder for your project. For example:

    ```
    mkdir mysite
    ```

2.  Navigate into the folder.

    ```
    cd mysite
    ```

3.  Install the `sgmf-scripts` node.

    ```
    npm install sgmf-scripts
    ```

4.  Use the `sgmf-scripts --createCartridge` command.

    ```
    sgmf-scripts --createCartridge app_custom_storefront
    ```

    These directories and files are created in your folder:

    ```
    ├── cartridges
        └── app_custom_mybrand
            └── cartridge
                   ...
    ├── dw.json
    ├── node_modules
    └── package.json
    ```

5.  Install the dependencies required by the new cartridge:

    ```
    npm install
    ```

**note:** To see all the available SFRA-commands, enter `sgmf-scripts --help`.

### Adding Custom Cartridges When `sgmf-scripts` Isn't Globally Installed

If you want to avoid globally installing `sgmf-scripts`, follow these steps to add a custom cartridge:

1.  Create a folder for your project. For example: `mysite`.

    ```
    mkdir mysite
    ```

2.  Navigate into the folder.

    ```
    cd mysite
    ```

3.  Install the `sgmf-scripts` node via npm.

    ```
    npm install sgmf-scripts
    ```

4.  Use `Node.js` to call the `sgmf-scripts createCartridges` command.

    ```
    node node_modules/sgmf-scripts --createCartridge app_custom_mybrand
    ```

    The following directories and files are created in your folder:

    ```
    ├── cartridges
        └── app_custom_mybrand
            └── cartridge
                   ...
    ├── dw.json
    ├── node_modules
    └── package.json
    ```

5.  Install the dependencies required by the new cartridge:

    ```
    npm install
    ```

**note:** To see all the available SFRA-commands, enter `sgmf-scripts --help`.

### Updating Your package.json

Because you're not modifying the `app_storefront_base` cartridge directly, Salesforce B2C Commerce provides a mechanism to selectively override CSS styles and client-side JavaScript. In the `package.json` file, the paths property lists every cartridge with CSS and client-side JavaScript functionality customized in your site. When building your cartridge stack, the `paths` property lets you import functionality from CSS and JavaScript files in other cartridges and selectively override it. When you use the command-line `compile` tool, it compiles the JavaScript and CSS across cartridges.

1.  Navigate to the top level of your custom cartridge. For example, `mysite.`
2.  Open the `package.json` file and modify the `paths` property. The `paths.base` property points to the local directory containing `app_storefront_base`. Add properties for the cartridges you want to import functionality from.

    Example: adding `plugin_ratings`, `plugin_reviews`, and `app_storefront_base` to a custom cartridge:

    ```
      "paths": {
        "base": "../storefront-reference-architecture/cartridges/app_storefront_base/",
        "ratings": "../plugin_ratings/cartridges/plugin_ratings/",
        "reviews": "../plugin_reviews/cartridges/plugin_reviews/",
        "applepay": "../plugin-applepay/cartridges/plugin_applepay/"
      }
    }
    ```

3.  Import the CSS files you want to include and override into the `my_repository/cartridges/my_cartridge/cartridge/client/default/myfile.scss file`.

    The following sample global `.scss` file inherits most of its styles from the base cartridge. The location of the base cartridge is defined in `package.json`. This example uses the `base` property defined in the `package.json` to import style sheets.

    ```
    @charset "UTF-8";

    @import "~base/variables";
    @import "bootstrap/scss/bootstrap";
    @import "~base/bootstrap_overrides";
    @import "~base/utilities/responsiveUtils";
    @import "font-awesome/scss/font-awesome";
    @import "flag-icon";
    @import "components/menu";
    @import "~base/components/common";
    @import "~base/components/footer";
    @import "components/footer";
    @import "~base/components/hero";
    @import "~base/components/notification";
    @import url(https://fonts.googleapis.com/css?family=Source+Sans+Pro&subset=latin-ext);

    body {
        font-family: 'Source Sans Pro', sans-serif;
    }

    .modal-background {
        display: none !important;
    }
    ```

4.  Use the path object to include JavaScript modules from other cartridges when you want to inherit and override client-side JavaScript functionality.

    The following example uses the path described by the base property to require in a client-side script in the base cartridge.

    ```
    'use strict';
    var base = require('../base/product/base');
    ```

### After Creating Your Custom Cartridge

After you create your custom cartridge, refer to [Create and Manage Sites for Developmen](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/site-development/b2c-managing-sites-for-dev.md)

### Best Practices When Creating Custom Cartridges

- Create unit tests for models.
- Check for possible naming collisions between cartridges.

Anti-patterns:

- Don't override `pdict` variables.
- Don't delete properties off the `pdict.`
- Don't replace something in `pdict` with something else with a different signature.

## Build Your Cartridge Stack

Each cartridge is built independently, uploaded, and then added to the cartridge stack. Change and upload cartridges independently, as long as you develop against same code version.

The command-line tools are designed to work in the top-level folder of each plug-in or cartridge repository. For example, `watch` only works for the directory in which you start it.

Cartridges provided by B2C Commerce have to be built only once for each version and uploaded. Create a separate build script for routine maintenance of cartridges you update and upload. In contrast, create a lightweight script to dynamically build and upload just the cartridges you're currently working on.

## Customize Templates

The system searches the cartridge path for the first template that matches the specified name and location. To override a template, create a custom cartridge. In the custom cartridge, include a template with the same name as the template you want to override.

The location of your template in your cartridge must match the location of the original template in the original cartridge. Finally, add your custom cartridge to the cartridge path, placing your cartridge to the left of the original cartridge.

Decorator Templates in SFRA

There are only two decorator templates:

- `page.isml`: Contains navigation information
- `checkout.isml`: Doesn't contain navigation information. Removing navigation information has been shown to improve the percentage of cart abandonment.

These templates are located in `app_storefront_base/cartridge/templates/default/common/layout/`.

**note:** All of the `pt_..._VARS` and `pt_..._UI` templates that existed in previous versions of SiteGenesis were removed.

The navigation for a page is set through the new decorator templates. Client-side scripts and CSS files are set for each template using the `assets.addJs` and a`ssets.addCss` functions for each template. The top of every page template contains code similar to the following:

```xml
<isdecorate template="common/layout/page">
    <isscript>
        var assets = require('~/cartridge/scripts/assets.js');
        assets.addCss('/css/cart.css');
    </isscript>
```

Put _.css files and _.js files with the same names and in the same locations as indicated in the original template. This strategy overrides any like-named _.css files and _.js files in any cartridge to the right of the current cartridge on the cartridge path.

### Overriding CSS and Client-Side JavaScript for a Page

Override CSS and client-side JavaScript for a specific template. For example, if the template declares the following assets:

```xml
<isdecorate template="common/layout/page">

    <isscript>
        var assets = require('*/cartridge/scripts/assets');
        assets.addJs('/js/productDetail.js');
        assets.addCss('/css/product/detail.css');
    </isscript>
```

Create a `productDetail.js` and `detail.css` and place them in the same location as indicated in the template. The platform uses the first template with the correct name and location that it finds on the cartridge path.

When creating the CSS file you want to customize, create a file with the same name and location as the file you 're customizing. In your file, import the original file.

Example: Customizing Detail.Scss.

```javascript
@import "base/product/detail";

.description-and-detail {
    margin-top: 2em;

    .details {

        @include media-breakpoint-up(sm) {
            margin-bottom: 2em;
        }
    }
}

```

### Best Practices with ISML

Usually, business logic isn't included in `app_storefront_base` templates. Any logic in the templates is specific to rendering. The `app_storefront_base` cartridge demonstrates recommended strategies for using ISML:

- `iscache`: Set by default to 24 hours. We recommend changing this value in the controller.
- `isset`: Only used to set a variable used by `isinclude`. Don't use complex expressions in the `isset`.
- `isscript`: Only used to add client-side JavaScript/CSS to the page using the `asset` module.
- `ismodule`: Only used for content assets.
- `iscontent`: Change this value in the controller.
- `iscookie`: Change this value in the controller.
- `isredirect`: Change this value in the controller.
- `isstatus`: Change this value in the controller.
- `isobject`: Used to wrap products for analytics and the Storefront Toolkit.

## Customize Models

Models in SFRA provide a JSON object layer for the application. The models convert objects returned by the B2C Commerce script APIs into pure JSON objects designed for the storefront. The models also apply business logic for the storefront.

A model passed in for rendering a template is assigned to the `viewData` variable. Add extra properties to the `viewData` variable — properties that are not provided by the `app_storefront_base` cartridge.

Controllers create and update models. To customize a model, you create the model and then add data to it that can be used for rendering.

Anything in the `modules` folder or the `toplevel` folder is globally available and extendable.

Customize models to:

- Extend the model to include more data to be used when rendering the template
- Add extra models with objects used to render templates
- Change models to be used to render templates in a different framework

## Customize SFRA Controllers and Routes

Customize SFRA controllers and routes to work for your own storefront.

### Inheriting Functionality from Another Controller and Extending It

It's important to understand when to extend a controller and when to override it, because this decision can significantly impact functionality and performance.

- When do I want to Override?

  It's best to override if you want to avoid executing the middleware of the controller or script you're modifying.

  When extending a controller, you first execute the original middleware, and then execute the additional steps included in your extension. If the original middleware steps include interaction with a third-party system, that interaction is still executed. If your extension also includes the interaction, the interaction is executed twice. Similarly, if the original middleware includes one or more steps that are computationally expensive, you can avoid executing the original middleware.

- When do I want to Extend?

  If the middleware you want to override is looking up a string or performing inexpensive operations, extend the controller or module.

- How do I extend or Override?

  Use the `module.superModule` mechanism to import the functionality from a controller and then override or add to it.

#### Example: Adding Product Reviews to Product.Js

This example customizes the product detail page to include product review information. The code for this example is available in the [Plugin_reviews](https://github.com/SalesforceCommerceCloud/plugin-reviews) demo cartridge.

In this example, the `Product.js` controller uses the following APIs for customization:

- `module.superModule`: Imports functionality from the first controller with the same name and location found to the right of the current cartridge on the cartridge path.
- `server.extend`: Inherits the existing server object and extends it with a list of new routes from the super module. In this case, it adds the routes from the module.superModule Project.js file.
- `server.append`: Modifies the `Show` route by appending middleware that adds properties to the `viewData` object for rendering. Using `server.append` causes a route to execute both the original middleware chain and any additional steps. If you're interacting with a web service or third-party system, don’t use `server.append`.
- `res`.`getViewData`: Gets the current `viewData` object from the response object.
- `res`.`setViewData`: Updates the `viewData` object used for rendering the template. Create your customized template in the same location and with the same name as the template rendered by the `superModule` controller. For example, if this controller inherits functionality from `app_storefront_base`, the rendering template depends on the product type being rendered. The rendering template can be either `product/productDetails`, `product/bundleDetails`, or `product/setDetails.`

```
// Product.js

'use strict';

var server = require('server');
var page = module.superModule;        //inherits functionality from next Product.js found to the right on the cartridge path
server.extend(page);                  //extends existing server object with a list of new routes from the Product.js found by module.superModule

server.append('Show', function (req, res, next) { //adds additional middleware
    var viewData = res.getViewData();
    viewData.product.reviews = [{
        text: 'Lorem ipsum dolor sit amet, cibo utroque ne vis, has no sumo graece.' +
          ' Dicta persius his id. Ea maluisset scripserit contentiones quo, est ne movet dicam.' +
          ' Equidem scriptorem vis no. Civibus tacimates interpretaris has et,' +
          ' ei offendit ocurreret vis, eos purto pertinax eleifend ea.',
        rating: 3.5
    }, {
        text: 'Very short review',
        rating: 5
    }, {
        text: 'Lorem ipsum dolor sit amet, cibo utroque ne vis, has no sumo graece.',
        rating: 1.5
    }];

    res.setViewData(viewData);
    next();
});

module.exports = server.exports();
```

### Replacing or Adding a Route

If you want to completely replace a route, rather than append it, use `module.superModule` to inherit the functionality of the controller and route you want to replace. Then register the functions you want the route to use.

Example: replacing the `Product-Varation` route

In your custom cartridge, create a `Product.js` file in the same location as the `Product.js` file in the base cartridge. Use the following code to import the functionality of `Product.`js and redefine it.

```
var page = require('app_storefront_base/cartridge/controller/Product');
var server = require('server);

server.extend(page);

server.replace('Show', server.middleware.get, function(req, res, next){
    res.render('myNewTemplate');
    next();
});

```

### Overriding Instead of Replacing a Step in the Middleware Chain

We recommend that you replace a route to change individual steps in a middleware chain.

You can't change a step in the middleware chain. However, you can either replace the whole route or append a new step after the chain completes, but before the template renders. Usually, if you're appending a step, it's to override or add data to the `ViewData` object.

**important:** Be careful when appending existing routes. If you append a step, the existing middleware chain executes no matter what the appended step does. Therefore, it’s possible to execute the route twice. If the route calls a web service or updates a third-party system, such as an inventory management system, it can take the same action twice.

**note:** Information about middleware filtering classes is available in the SFRA JSDoc in the server-side documentation for `Global`.

### Changing the Access on an Existing Route

Use the middleware functions provided by B2C Commerce or create your own. We recommend that you replace a route when changing access.

These middleware filtering functions are provided by B2C Commerce:

- `get:` Filter for get requests
- `htt:` Filter for http requests
- `https:`Filter for https requests
- `include:` Filter for remote includes
- `post:` Filter for post requests

If the request doesn't match the filtering condition, the function returns an Error with the text `Params do not match route`.

### Customizing a Controller with a Web Service or a Call to a Third Party

In general, customizing a controller with a web service or third-party call uses the same mechanisms as other types of customizations. However, it's important to make sure that you don't execute the controller twice. Executing the controller twice is possible if you use `server.append` to customize the ViewData object passed to the rendering template. Instead, simply replace the route entirely.

<!-- document id=9d1f1c1c85d85af6541e521ba15d25ec8da5efd144e05eef8c82e2c73625212d url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-customize-sf.md -->

# Customize Storefront Next

Customize and extend your storefront, integrate AI agent capabilities, and implement the modernized storefront experience.

In this section:

- [Customization Best Practices and Upgrades](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-component-extend-upgrade.md)
- [Add a Page and a Component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-customize.md)
- [Modernized Storefront Experience in Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-modern-exp.md)
- [B2C Agent Skills](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mcp-server.md)
- [Extend Storefront Next with Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-extend.md)

<!-- document id=0ad72d82dd1fb98c2a3667b55efb52203bff867e1d72b0b0dea8eb244a13597f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-configuring-a-hosted-payment-page.md -->

# Customize the Hosted Payment Page

Customize Customer Service Center to modify the behavior of your system's business logic to render the hosted payment page.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


1.  Add your cartridge containing the code to be hosted.

    - Use custom client logic to render the hosted payment page.
    - Configure hosted payment pages. Use the hook with either dw.csc.hosted_payment_pages.{payment_method_id} or dw.csc.hosted_payment_pages.{payment_processor_id}
      For example, see this [sample cartridge](https://github.com/SalesforceCommerceCloud/customer-service-center/tree/master/cartridges/bm-adyen)

2.  Configure the hosted payment page with either dw.csc.hosted_payment_pages.{payment_method_id} or dw.csc.hosted_payment_pages.{payment_processor_id}.

3.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Payment Processors**.

4.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Payment Methods**.

    1.  On the Payment Method's page, select **Yes** to enable the payment method.

    2.  In the Payments Method's detail section, select the payment processor from the Payment Processor dropdown. For example, Adyen.

5.  Click **Apply**.

6.  To test the hosted payment page, click the test card number link. For example, [Adyen Test Card Number](https://docs.adyen.com/development-resources/testing/test-card-numbers).

7.  To enable the hosted payment page endpoint in your cartridge: add the {"name": "dw.csc.hosted_payment_pages.Adyen", "script": "./hpp/adyen.ds"}

    - The hook extension ".Adyen" tells Customer Service Center that it's a hosted payment page's payment method. Add with the ID as a normal payment method in Business Manager.
    - The script file specifies the controller and start node.
      For example, [hooks.json](https://github.com/SalesforceCommerceCloud/customer-service-center/tree/master/cartridges/bm-adyen/cartridge/scripts/hooks.json).

8.  The controller function in Customer Service Center makes a call to prepare the hosted payment page with the needed properties and redirects to a template in the cartridge. The template contains the form that sends the prepared data to the hosted payment page.

    For example, [CSCAdyenHostedPaymentPage.js](https://github.com/SalesforceCommerceCloud/customer-service-center/tree/master/cartridges/bm-adyen/cartridge/controllers/CSCAdyenHostedPaymentPage.js).

9.  From the hosted payment page, the payment success redirect is configured to the Confirm node in the controller when the payment is successful. Similarly, configure other controller endpoints for more hosted payment pages to Customer Service Center interactions.

    Salesforce B2C Commerce Adyen Cartridge Examples

    - [Sample CSC cartridge](https://github.com/SalesforceCommerceCloud/customer-service-center/tree/master/cartridges/bm-adyen)
    - [Sample B2C Commerce original cartridge](https://github.com/Adyen/adyen-salesforce-commerce-cloud)

<!-- document id=f06458d3a206eb0c9c79bff40d2b5c5b121f68917e376b807736f128933c5189 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-ab-test-search.md -->

Data A/B Test Search (deprecated)

# Data A/B Test Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST A/B Test Search

`POST /sites/{site_id}/ab_test_search`

Operation ID: `A/B Test Search`. Tags: sites. Security: oauth2\_application.

Searches for A/B Tests.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   id - String
    
*   description - String
    
*   enabled - Boolean
    
*   paused - Boolean
    
*   key\_metric\_id - String
    
*   email\_addresses - String
    
*   tags- String
    
*   expiration\_type - String enum\[session, never\]
    
*   start\_date - DateTime
    
*   end\_date - DateTime
    

These fields can only be used in Queries as conjunctions (using AND). If the field is used in a disjunction (OR) an exception will be thrown.

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   description - String
    
*   enabled - Boolean
    
*   paused - Boolean
    
*   key\_metric\_id - String
    

This endpoint may return the following faults:

*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_test_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### ab\_test\_search\_result

Request document containing a search response for A/B test

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_)  
    Minimum: 0.
*   `expand` (_array of string_)
*   `hits` (_array of ab\_test_) The search hits returned as an ordered list
*   `next` (_result\_page_) The URL of the next result page.
*   `previous` (_result\_page_) The URL of the previous result page.
*   `query` (_query_)
*   `select` (_string_) The fields that you want to select.
*   `sorts` (_array of sort_)
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "customer_groups": [
        "abtest_customer_group"
      ],
      "description": "my abtest1 description",
      "email_addresses": [
        "abtest1@salesforce.com"
      ],
      "enabled": true,
      "end_date": "2015-07-31T23:09:08.000Z",
      "expiration_type": "session",
      "id": "my-abtest1",
      "key_metric_id": "abtest_key_metric_id",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest1",
      "paused": true,
      "start_date": "2015-04-01T11:30:15.000Z",
      "tags": [
        "abtest_tag"
      ],
      "test_groups": [
        {
          "allocation": 20,
          "custom_experience": false,
          "id": "Control"
        },
        {
          "allocation": 40,
          "custom_experience": false,
          "description": "A description",
          "id": "Test Segment A"
        },
        {
          "allocation": 40,
          "custom_experience": false,
          "id": "Test Segment B"
        }
      ],
      "trigger": {
        "is_pipeline_based": false,
        "trigger_type": "immediately"
      }
    },
    {
      "customer_groups": [
        "abtest_customer_group"
      ],
      "description": "my abtest2 description",
      "email_addresses": [
        "abtest1@salesforce.com"
      ],
      "enabled": true,
      "end_date": "2015-07-31T23:09:08.000Z",
      "expiration_type": "session",
      "id": "my-abtest2",
      "key_metric_id": "abtest_key_metric_id",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest2",
      "paused": true,
      "start_date": "2015-04-01T11:30:15.000Z",
      "tags": [
        "abtest_tag"
      ],
      "test_groups": [
        {
          "allocation": 20,
          "custom_experience": false,
          "id": "Control"
        },
        {
          "allocation": 80,
          "custom_experience": false,
          "id": "Test Segment B"
        }
      ],
      "trigger": {
        "is_pipeline_based": true,
        "pipeline_calls": [
          "My-Pipeline"
        ],
        "trigger_type": "pipeline_call"
      }
    },
    {
      "customer_groups": [
        "abtest_customer_group"
      ],
      "description": "my abtest3 description",
      "email_addresses": [
        "abtest1@salesforce.com"
      ],
      "enabled": true,
      "end_date": "2015-07-31T23:09:08.000Z",
      "expiration_type": "session",
      "id": "my-abtest3",
      "key_metric_id": "abtest_key_metric_id",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest3",
      "paused": true,
      "start_date": "2015-04-01T11:30:15.000Z",
      "tags": [
        "abtest_tag"
      ],
      "test_groups": [
        {
          "allocation": 20,
          "custom_experience": false,
          "id": "Control"
        },
        {
          "allocation": 50,
          "custom_experience": false,
          "description": "A description",
          "id": "Test Segment A"
        },
        {
          "allocation": 30,
          "custom_experience": false,
          "id": "Test Segment B"
        }
      ],
      "trigger": {
        "is_pipeline_based": true,
        "pipeline_calls": [
          "Home-Show",
          "Default-Start"
        ],
        "trigger_type": "home_page_view"
      }
    },
    {
      "customer_groups": [
        "abtest_customer_group"
      ],
      "description": "my abtest4 description",
      "email_addresses": [
        "abtest1@salesforce.com"
      ],
      "enabled": true,
      "end_date": "2015-07-31T23:09:08.000Z",
      "expiration_type": "session",
      "id": "my-abtest4",
      "key_metric_id": "abtest_key_metric_id",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest4",
      "paused": true,
      "start_date": "2015-04-01T11:30:15.000Z",
      "tags": [
        "abtest_tag"
      ],
      "test_groups": [
        {
          "allocation": 0,
          "custom_experience": false,
          "id": "Control"
        }
      ],
      "trigger": {
        "categories": [
          "root"
        ],
        "is_pipeline_based": true,
        "pipeline_calls": [
          "Search-Show?cgid=root"
        ],
        "trigger_type": "category_page_view"
      }
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 4
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### ab\_test

The id of the A/B Test

*   `customer_groups` (_array of string_) The list of customer group ids assigned to the A/B Test. Defaults to 'Everyone' if not specified on create
*   `description` (_string_) The optional description of the A/B Test  
    Maximum length: 4000.
*   `email_addresses` (_array of string_) The optional list of email addresses to send A/B Test results
*   `enabled` (_boolean_) The flag representing the enabled state of the A/B Test. Defaults to false if not specified on create
*   `end_date` (_string (date-time)_) The date that the A/B Test ends. Defaults to two weeks from creation date if both start and end dates are not specified on create
*   `expiration_type` (_string_) The participant expiration type of the A/B Test. Defaults to 'never' if not specified on create  
    Allowed values: `session`, `never`.
*   `id` (_string_) The id of the A/B Test  
    Minimum length: 1. Maximum length: 40.
*   `key_metric_id` (_string_) The key metric that is most important to the A/B Test, among the metrics collected. Defaults to 'Revenue' if not specified from test participant activity  
    Maximum length: 256.
*   `link` (_string_) The URL to get the A/B test. This is a computed attribute and cannot be modified
*   `paused` (_boolean_) The flag representing the paused state of the A/B Test. Defaults to false if not specified on create
*   `segment_count` (_integer (int32)_) Segment count of A/B test. This is a computed attribute and cannot be modified
*   `start_date` (_string (date-time)_) The date that the A/B Test begins. Defaults to a week from creation date if both start and end dates are not specified on create
*   `status` (_string_) Status of A/B test. This is a computed attribute and cannot be modified  
    Allowed values: `ended`, `planned`, `running`.
*   `tags` (_array of string_) The optional list of tags to group similar A/B Tests so that they can be searched easily.
*   `test_groups` (_array of ab\_test\_group_) Test Groups created for an A/B Test. This is a read only attribute for now.
*   `test_segments` (_array of ab\_test\_segment_) Test Segments created for an A/B Test. This is a read only attribute for now
*   `trigger` (_ab\_test\_trigger_) The trigger that allows the test participant to be considered for an A/B Test

_Example_

```
{
  "customer_groups": [
    "abtest_customer_group"
  ],
  "description": "abtest description",
  "email_addresses": [
    "abtest1@salesforce.com"
  ],
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "expiration_type": "session",
  "id": "my-abtest",
  "key_metric_id": "abtest_key_metric_id",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest",
  "paused": true,
  "start_date": "2015-04-01T11:30:15.000Z",
  "tags": [
    "abtest_tag"
  ],
  "test_groups": [
    {
      "allocation": 20,
      "custom_experience": false,
      "id": "Control"
    },
    {
      "allocation": 40,
      "custom_experience": false,
      "description": "A description",
      "id": "Test Segment A"
    },
    {
      "allocation": 40,
      "custom_experience": false,
      "id": "Test Segment B"
    }
  ],
  "trigger": {
    "is_pipeline_based": false,
    "trigger_type": "immediately"
  }
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### ab\_test\_group

Document representing an A/B Test Group

*   `allocation` (_integer (int32)_) Test Group percentage allocation
*   `custom_experience` (_boolean_) Flag to determine if this Test Group is a customer experience
*   `description` (_string_) Test Group description
*   `id` (_string_) Test group id

_Example_

```
{
  "allocation": 20,
  "custom_experience": false,
  "id": "Control"
}
```

### ab\_test\_segment

Document representing an A/B Test Segment

*   `allocation` (_integer (int32)_) Test Group percentage allocation
*   `custom_experience` (_boolean_) Flag to determine if this Test Group is a customer experience
*   `description` (_string_) Test Group description  
    Maximum length: 4000.
*   `id` (_string_) Test group id  
    Minimum length: 1. Maximum length: 40.
*   `link` (_string_)
*   `preferences` (_array of object_) Preferences which this segment has as experiences
*   `promotions` (_array of object_) Promotions which this segment has as experiences
*   `slot_configs` (_array of object_) Slot configurations which this segment has as experiences
*   `sorting_rules` (_array of object_) Sorting rules which this segment has as experiences
*   `stats` (_ab\_test\_segment\_stats_) Statistics about the segment

_Example_

```
{
  "allocation": 10,
  "description": "modified description",
  "id": "my-segment",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest/segments/my-segment"
}
```

### ab\_test\_trigger

Document representing an A/B Test trigger.

*   `categories` (_array of string_) The list of categories. This is a modifiable attribute when trigger type is 'category\_page\_view' only
*   `is_pipeline_based` (_boolean_) The flag indicating if the trigger is based on pipelines. This is a computed attribute and cannot be modified
*   `pipeline_calls` (_array of string_) The list of pipeline name and start node combinations (for example, Account-Show). This is a modifiable attribute when trigger type is 'pipeline\_calls' only
*   `trigger_type` (_string_) The type of the trigger. Defaults to 'immediately' if not specified on create  
    Allowed values: `immediately`, `category_page_view`, `home_page_view`, `pipeline_call`.

_Example_

```
{
  "is_pipeline_based": false,
  "trigger_type": "immediately"
}
```

### ab\_test\_segment\_stats

*   `adds_to_baskets` (_integer (int32)_)
*   `average_adds_per_basket` (_number (double)_)
*   `average_adds_per_basket_std_error` (_number (double)_)
*   `average_discount_amount` (_number (double)_)
*   `average_discount_amount_std_error` (_number (double)_)
*   `average_discount_amount_with_coupon` (_number (double)_)
*   `average_discount_amount_with_coupon_std_error` (_number (double)_)
*   `average_discount_amount_without_coupon` (_number (double)_) The standard error for the average amount discounted for orders without using a coupon
*   `average_discount_amount_without_coupon_std_error` (_number (double)_) Units sold per hour
*   `average_order_value` (_number (double)_)
*   `average_order_value_std_error` (_number (double)_)
*   `average_revenue_per_visit` (_number (double)_)
*   `average_revenue_per_visit_std_error` (_number (double)_)
*   `average_units_added_per_basket` (_number (double)_)
*   `average_units_adder_per_basket_std_error` (_number (double)_)
*   `average_units_per_order_std_error` (_number (double)_)
*   `average_units_per_visit` (_number (double)_)
*   `average_units_per_visit_std_error` (_number (double)_)
*   `basket_rate` (_number (double)_)
*   `baskets` (_number (double)_)
*   `checkout_rate` (_number (double)_)
*   `checkouts` (_integer (int32)_)
*   `conversion_rate` (_number (double)_)
*   `discount_amount_with_coupon` (_number (double)_)
*   `discount_amount_without_coupon` (_number (double)_)
*   `orders` (_integer (int32)_)
*   `revenue` (_number (double)_)
*   `total_discount_amount` (_number (double)_)
*   `units` (_number (double)_)
*   `units_added_to_baskets` (_number (double)_)
*   `visitors` (_integer (int32)_)
*   `visits` (_integer (int32)_)

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=7e57e54ce33d9b3e07dff06cf9a5c456d9f2d87a284e04340134683dcf12c282 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-ab-tests.md -->

Data A/B Tests (deprecated)

# Data A/B Tests (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get AB/Tests

`GET /sites/{site_id}/ab_tests`

Operation ID: `Get AB/Tests`. Tags: sites. Security: oauth2\_application.

Action to get all the A/B tests with searching.

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).  
    Minimum: 0.
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).  
    Minimum: 0.
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_tests`.
    

### PUT Bind Promotion to A/B Test

`PUT /sites/{site_id}/ab_tests/{ab_test_id}/segments/{segment_id}/promotions/{promotion_id}`

Operation ID: `Bind Promotion to A/B Test`. Tags: sites. Security: oauth2\_application.

Action to bind a single promotion to a given abTest.

This endpoint may return the following faults:

*   404 - ABTestNotFoundException - Indicates that the abTest with the given abTest ID is not found.
*   404 - ABTestSegmentNotFoundException - thrown when the segment with the given id is not found.
*   404 - PromotionNotFoundException - Indicates that the promotion with the given promotion ID is not found.
*   404 - SiteNotFoundException - thrown when the site with the given id is not found.

#### Parameters

*   `site_id` (path, string, required) The ID of the site that contains the abTest and promotion.  
    Minimum length: 1.
*   `ab_test_id` (path, string, required) The ID of the abTest which contains the segment.  
    Minimum length: 1.
*   `segment_id` (path, string, required) The ID of the segment to to which the promotion is to be assigned.  
    Minimum length: 1.
*   `promotion_id` (path, string, required) The ID of the promotion that is to be assigned to the abTest.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `ABTestNotFoundException` - Indicates that the abTest with the given abTest ID is not found. or `ABTestSegmentNotFoundException` - thrown when the segment with the given id is not found. or `PromotionNotFoundException` - Indicates that the promotion with the given promotion ID is not found. or `SiteNotFoundException` - thrown when the site with the given id is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind Promotions

`DELETE /sites/{site_id}/ab_tests/{ab_test_id}/segments/{segment_id}/promotions/{promotion_id}`

Operation ID: `Unbind Promotions`. Tags: sites. Security: oauth2\_application.

Action to unbind one promotions from a given abTest.

This endpoint may return the following faults:

*   404 - ABTestNotFoundException - Indicates that the abTest with the given abTest ID is not found.
*   404 - ABTestSegmentNotFoundException - thrown when the segment with the given id is not found.
*   404 - PromotionNotFoundException - thrown when promotion is not found for one of the specified promotion ids.
*   404 - SiteNotFoundException - thrown when the site with the given id is not found.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `ab_test_id` (path, string, required) The abTest ID that promotions are to be unbound from  
    Minimum length: 1.
*   `segment_id` (path, string, required) the segment to bind to  
    Minimum length: 1.
*   `promotion_id` (path, string, required) The ID of the promotion that is to be assigned to the abTest.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `ABTestNotFoundException` - Indicates that the abTest with the given abTest ID is not found. or `ABTestSegmentNotFoundException` - thrown when the segment with the given id is not found. or `PromotionNotFoundException` - thrown when promotion is not found for one of the specified promotion ids. or `SiteNotFoundException` - thrown when the site with the given id is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Bind Slot Configuration

`PUT /sites/{site_id}/ab_tests/{ab_test_id}/segments/{segment_id}/slot_configurations/{slot_id}/{slot_config_id}`

Operation ID: `Bind Slot Configuration`. Tags: sites. Security: oauth2\_application.

Action to bind a slot configuration to a given abTest.

This endpoint may return the following faults:

*   400 - InvalidContextTypeException - Indicates the slot context type is not one of "global", "category", or "folder"
*   404 - ABTestNotFoundException - Indicates that the abTest with the given abTest ID is not found.
*   404 - ABTestSegmentNotFoundException - thrown when the segment with the given id is not found.
*   404 - SiteNotFoundException - thrown when the site with the given id is not found.
*   404 - SlotConfigurationIdentifierNotFoundException - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found.
*   404 - SlotWithContextTypeNotFoundException - Indicates that the slot with the given slot ID and context type is not found.

#### Parameters

*   `ab_test_id` (path, string, required) The id of the abTest  
    Minimum length: 1.
*   `segment_id` (path, string, required)  
    Minimum length: 1.
*   `site_id` (path, string, required) The id of the site  
    Minimum length: 1.
*   `slot_id` (path, string, required) The of the slot  
    Minimum length: 1.
*   `slot_config_id` (path, string, required) The id of the slot configuration  
    Minimum length: 1.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be folder, category or global), an equals sign (=), and the context id (either the category id or folder id). If you do not set this query parameter, the global context is used by default.  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `InvalidContextTypeException` - Indicates the slot context type is not one of "global", "category", or "folder"
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ABTestNotFoundException` - Indicates that the abTest with the given abTest ID is not found. or `ABTestSegmentNotFoundException` - thrown when the segment with the given id is not found. or `SiteNotFoundException` - thrown when the site with the given id is not found. or `SlotConfigurationIdentifierNotFoundException` - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found. or `SlotWithContextTypeNotFoundException` - Indicates that the slot with the given slot ID and context type is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind Slot Configuration

`DELETE /sites/{site_id}/ab_tests/{ab_test_id}/segments/{segment_id}/slot_configurations/{slot_id}/{slot_config_id}`

Operation ID: `Unbind Slot Configuration`. Tags: sites. Security: oauth2\_application.

Action to unbind a slot configuration from a given abTest.

This endpoint may return the following faults:

*   400 - InvalidContextTypeException - Indicates the slot context type is not one of "global", "category", or "folder"
*   404 - ABTestNotFoundException - Indicates that the abTest with the given abTest ID is not found.
*   404 - ABTestSegmentNotFoundException - thrown when the segment with the given id is not found.
*   404 - SiteNotFoundException - thrown when the site with the given id is not found.
*   404 - SlotConfigurationIdentifierNotFoundException - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found.
*   404 - SlotWithContextTypeNotFoundException - Indicates that the slot with the given slot ID and context type is not found.

#### Parameters

*   `ab_test_id` (path, string, required) The id of the abTest  
    Minimum length: 1.
*   `segment_id` (path, string, required)  
    Minimum length: 1.
*   `site_id` (path, string, required) The id of the site  
    Minimum length: 1.
*   `slot_id` (path, string, required) The of the slot  
    Minimum length: 1.
*   `slot_config_id` (path, string, required) The id of the slot configuration  
    Minimum length: 1.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be folder, category or global), an equals sign (=), and the context id (either the category id or folder id).  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `InvalidContextTypeException` - Indicates the slot context type is not one of "global", "category", or "folder"
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ABTestNotFoundException` - Indicates that the abTest with the given abTest ID is not found. or `ABTestSegmentNotFoundException` - thrown when the segment with the given id is not found. or `SiteNotFoundException` - thrown when the site with the given id is not found. or `SlotConfigurationIdentifierNotFoundException` - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found. or `SlotWithContextTypeNotFoundException` - Indicates that the slot with the given slot ID and context type is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Bind SortingRule to A/B Test

`PUT /sites/{site_id}/ab_tests/{ab_test_id}/segments/{segment_id}/sorting_rules/{sorting_rule_id}/{category_id}`

Operation ID: `Bind SortingRule to A/B Test`. Tags: sites. Security: oauth2\_application.

Action to bind a single sorting rule to a given abTest.

This endpoint may return the following faults:

*   400 - InvalidCategoryException - Indicates that the category with the given category ID is not found.
*   404 - ABTestNotFoundException - Indicates that the abTest with the given abTest ID is not found.
*   404 - ABTestSegmentNotFoundException - thrown when the segment with the given id is not found.
*   404 - SiteNotFoundException - thrown when the site with the given id is not found.
*   404 - SortingRuleNotFoundException - Indicates that the sorting rule with the given sorting rule ID is not found.
*   409 - SortingRuleCampaignAssignConflictException - Indicates that there is a sorting rule already assigned to the given abTest ID and category ID. The sorting rule with the given sorting rule ID cannot be assigned to the same abTest ID and category ID.

#### Parameters

*   `site_id` (path, string, required) The ID of the site that contains the abTest, sorting rule and category.  
    Minimum length: 1.
*   `ab_test_id` (path, string, required) The ID of the abTest to which the sorting rule is to be assigned.  
    Minimum length: 1.
*   `segment_id` (path, string, required)  
    Minimum length: 1.
*   `sorting_rule_id` (path, string, required) The ID of sorting rule that is to be assigned to the abTest.  
    Minimum length: 1.
*   `category_id` (path, string, required) The ID of the category that is associated with the sorting rule.  
    Minimum length: 1.
*   `rule_context` (query, string) the optional context of the sorting rule, either "site" (default) or "global"

#### Responses

*   **204**
*   **400** `InvalidCategoryException` - Indicates that the category with the given category ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ABTestNotFoundException` - Indicates that the abTest with the given abTest ID is not found. or `ABTestSegmentNotFoundException` - thrown when the segment with the given id is not found. or `SiteNotFoundException` - thrown when the site with the given id is not found. or `SortingRuleNotFoundException` - Indicates that the sorting rule with the given sorting rule ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `SortingRuleCampaignAssignConflictException` - Indicates that there is a sorting rule already assigned to the given abTest ID and category ID. The sorting rule with the given sorting rule ID cannot be assigned to the same abTest ID and category ID.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind SortingRule

`DELETE /sites/{site_id}/ab_tests/{ab_test_id}/segments/{segment_id}/sorting_rules/{sorting_rule_id}/{category_id}`

Operation ID: `Unbind SortingRule`. Tags: sites. Security: oauth2\_application.

Action to unbind a single sorting rule from a given abTest.

This endpoint may return the following faults:

*   400 - InvalidCategoryException - Indicates that the category with the given category ID is not found.
*   404 - ABTestNotFoundException - Indicates that the abTest with the given abTest ID is not found.
*   404 - ABTestSegmentNotFoundException - thrown when the segment with the given id is not found.
*   404 - SiteNotFoundException - thrown when the site with the given id is not found.
*   404 - SortingRuleNotFoundException - Indicates that the sorting rule with the given sorting rule ID is not found.

#### Parameters

*   `site_id` (path, string, required) The ID of the site that contains the abTest, sorting rule and category.  
    Minimum length: 1.
*   `ab_test_id` (path, string, required) The ID of the abTest to which the sorting rule is to be assigned.  
    Minimum length: 1.
*   `segment_id` (path, string, required)  
    Minimum length: 1.
*   `sorting_rule_id` (path, string, required) The ID of sorting rule that is to be assigned to the abTest.  
    Minimum length: 1.
*   `category_id` (path, string, required) The ID of the category that is associated with the sorting rule.  
    Minimum length: 1.
*   `rule_context` (query, string) the optional context of the sorting rule, either "site" (default) or "global"

#### Responses

*   **204**
*   **400** `InvalidCategoryException` - Indicates that the category with the given category ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ABTestNotFoundException` - Indicates that the abTest with the given abTest ID is not found. or `ABTestSegmentNotFoundException` - thrown when the segment with the given id is not found. or `SiteNotFoundException` - thrown when the site with the given id is not found. or `SortingRuleNotFoundException` - Indicates that the sorting rule with the given sorting rule ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get an A/B Test

`GET /sites/{site_id}/ab_tests/{id}`

Operation ID: `Get an A/B Test`. Tags: sites. Security: oauth2\_application.

Action to get an A/B Test information.

This endpoint may return the following faults:

*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1.
*   `expand` (query, array of string) The expand parameter. A comma separated list with the allowed values (stats, promotions, sorting\_rules, slot\_configs)

#### Responses

*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_test`.
    

### PUT Creates an A/B Test

`PUT /sites/{site_id}/ab_tests/{id}`

Operation ID: `Creates an A/B Test`. Tags: sites. Security: oauth2\_application.

Creates an A/B Test using the information provided. If an A/B Test with the same unique identifier exists, it will be deleted and a new one will be created unless the header x-dw-validate-existing=true is passed in with the request.

This endpoint may return the following faults:

*   400 - ABTestInvalidEmailException - Thrown if an invalid email is specified.
*   400 - ABTestInvalidPipelineException - Thrown if an invalid pipeline is specified.
*   400 - ABTestInvalidTriggerException - Thrown if there is missing pipline\_call or categories in the specified trigger of type pipeline\_call or category\_view\_page respectively.
*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id
*   409 - ABTestDuplicateException - If an A/B Test exists already in the site with the given identifier and the header x-dw-validate-existing=true is passed in with the request.

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1. Maximum length: 40.

#### Request body

Media type: `application/json, text/xml`. Schema: `ab_test`.

#### Responses

*   **400** `ABTestInvalidEmailException` - Thrown if an invalid email is specified. or `ABTestInvalidPipelineException` - Thrown if an invalid pipeline is specified. or `ABTestInvalidTriggerException` - Thrown if there is missing pipline\_call or categories in the specified trigger of type pipeline\_call or category\_view\_page respectively.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `ABTestDuplicateException` - If an A/B Test exists already in the site with the given identifier and the header x-dw-validate-existing=true is passed in with the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_test`.
    

### DELETE Delete A/B Test

`DELETE /sites/{site_id}/ab_tests/{id}`

Operation ID: `Delete A/B Test`. Tags: sites. Security: oauth2\_application.

Deletes the A/B Test by ID

This endpoint may return the following faults:

*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update an A/B Test

`PATCH /sites/{site_id}/ab_tests/{id}`

Operation ID: `Update an A/B Test`. Tags: sites. Security: oauth2\_application.

Updates the A/B Test with the specified information.

This endpoint may return the following faults:

*   400 - ABTestInvalidEmailException - Thrown if an invalid email is specified.
*   400 - ABTestInvalidPipelineException - Thrown if an invalid pipeline is specified.
*   400 - ABTestInvalidTriggerException - Thrown if there is missing pipline\_call or categories in the specified trigger of type pipeline\_call or category\_view\_page respectively.
*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id
*   409 - ABTestDuplicateException - Thrown if an A/B Test exists already in the site with the given identifier specified in the body that is different from the identifier in the path.

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `ab_test`.

#### Responses

*   **400** `ABTestInvalidEmailException` - Thrown if an invalid email is specified. or `ABTestInvalidPipelineException` - Thrown if an invalid pipeline is specified. or `ABTestInvalidTriggerException` - Thrown if there is missing pipline\_call or categories in the specified trigger of type pipeline\_call or category\_view\_page respectively.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `ABTestDuplicateException` - Thrown if an A/B Test exists already in the site with the given identifier specified in the body that is different from the identifier in the path.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_test`.
    

### GET Get A/B Test Segment

`GET /sites/{site_id}/ab_tests/{id}/segments/{segment_id}`

Operation ID: `Get A/B Test Segment`. Tags: sites. Security: oauth2\_application.

Gets an A/B Test segment using the information provided.

This endpoint may return the following faults:

*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id
*   404 - ABTestSegmentNotFoundException - Thrown if the segment cannot be found in the A/B Test provided

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1.
*   `segment_id` (path, string, required) The id of the segment in the test.  
    Minimum length: 1.
*   `expand` (query, array of string) The expand parameter. A comma separated list with the allowed values (stats, promotions, sorting\_rules, slot\_configs)

#### Responses

*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id or `ABTestSegmentNotFoundException` - Thrown if the segment cannot be found in the A/B Test provided
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_test_segment`.
    

### PUT Creates an A/B Test Segment

`PUT /sites/{site_id}/ab_tests/{id}/segments/{segment_id}`

Operation ID: `Creates an A/B Test Segment`. Tags: sites. Security: oauth2\_application.

Creates an A/B Test segment using the information provided.

This endpoint may return the following faults:

*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id
*   404 - ABTestSegmentNotFoundException - Thrown if the segment cannot be found in the A/B Test provided

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1.
*   `segment_id` (path, string, required) The id of the segment in the test.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `ab_test_segment`.

#### Responses

*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id or `ABTestSegmentNotFoundException` - Thrown if the segment cannot be found in the A/B Test provided
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_test_segment`.
    

### DELETE Delete A/B Test Segment

`DELETE /sites/{site_id}/ab_tests/{id}/segments/{segment_id}`

Operation ID: `Delete A/B Test Segment`. Tags: sites. Security: oauth2\_application.

Deletes the A/B Test Segment by ID

This endpoint may return the following faults:

*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id
*   404 - ABTestSegmentNotFoundException - Thrown if the segment cannot be found in the A/B Test provided

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1.
*   `segment_id` (path, string, required) The id of the segment in the test.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id or `ABTestSegmentNotFoundException` - Thrown if the segment cannot be found in the A/B Test provided
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update A/B Test Segment

`PATCH /sites/{site_id}/ab_tests/{id}/segments/{segment_id}`

Operation ID: `Update A/B Test Segment`. Tags: sites. Security: oauth2\_application.

Updates the A/B Test segment with the specified information.

This endpoint may return the following faults:

*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.
*   404 - ABTestNotFoundException - Thrown in case the A/B Test does not exist matching the given id
*   404 - ABTestSegmentNotFoundException - Thrown if the segment cannot be found in the A/B Test provided

#### Parameters

*   `site_id` (path, string, required) ID of the site that the A/B tests are contained within.  
    Minimum length: 1. Maximum length: 256.
*   `id` (path, string, required) The id of the requested A/B Test.  
    Minimum length: 1.
*   `segment_id` (path, string, required) The id of the segment in the test.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `ab_test_segment`.

#### Responses

*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown. or `ABTestNotFoundException` - Thrown in case the A/B Test does not exist matching the given id or `ABTestSegmentNotFoundException` - Thrown if the segment cannot be found in the A/B Test provided
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ab_test_segment`.
    

## Schemas

### ab\_tests

Request document containing a set of ABTests

*   `count` (_integer (int32)_)
*   `data` (_array of ab\_test_)
*   `expand` (_array of string_)
*   `next` (_string_)
*   `previous` (_string_)
*   `select` (_string_)
*   `start` (_integer (int32)_)  
    Minimum: 0.
*   `total` (_integer (int32)_)

_Example_

```
{
  "customer_groups": [
    "abtest_customer_group"
  ],
  "description": "my abtest1 description",
  "email_addresses": [
    "abtest1@salesforce.com"
  ],
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "expiration_type": "session",
  "id": "my-abtest1",
  "key_metric_id": "abtest_key_metric_id",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest1",
  "paused": true,
  "start_date": "2015-04-01T11:30:15.000Z",
  "tags": [
    "abtest_tag"
  ],
  "test_groups": [
    {
      "allocation": 20,
      "custom_experience": false,
      "id": "Control"
    },
    {
      "allocation": 40,
      "custom_experience": false,
      "description": "A description",
      "id": "Test Segment A"
    },
    {
      "allocation": 40,
      "custom_experience": false,
      "id": "Test Segment B"
    }
  ],
  "trigger": {
    "is_pipeline_based": false,
    "trigger_type": "immediately"
  }
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### ab\_test

The id of the A/B Test

*   `customer_groups` (_array of string_) The list of customer group ids assigned to the A/B Test. Defaults to 'Everyone' if not specified on create
*   `description` (_string_) The optional description of the A/B Test  
    Maximum length: 4000.
*   `email_addresses` (_array of string_) The optional list of email addresses to send A/B Test results
*   `enabled` (_boolean_) The flag representing the enabled state of the A/B Test. Defaults to false if not specified on create
*   `end_date` (_string (date-time)_) The date that the A/B Test ends. Defaults to two weeks from creation date if both start and end dates are not specified on create
*   `expiration_type` (_string_) The participant expiration type of the A/B Test. Defaults to 'never' if not specified on create  
    Allowed values: `session`, `never`.
*   `id` (_string_) The id of the A/B Test  
    Minimum length: 1. Maximum length: 40.
*   `key_metric_id` (_string_) The key metric that is most important to the A/B Test, among the metrics collected. Defaults to 'Revenue' if not specified from test participant activity  
    Maximum length: 256.
*   `link` (_string_) The URL to get the A/B test. This is a computed attribute and cannot be modified
*   `paused` (_boolean_) The flag representing the paused state of the A/B Test. Defaults to false if not specified on create
*   `segment_count` (_integer (int32)_) Segment count of A/B test. This is a computed attribute and cannot be modified
*   `start_date` (_string (date-time)_) The date that the A/B Test begins. Defaults to a week from creation date if both start and end dates are not specified on create
*   `status` (_string_) Status of A/B test. This is a computed attribute and cannot be modified  
    Allowed values: `ended`, `planned`, `running`.
*   `tags` (_array of string_) The optional list of tags to group similar A/B Tests so that they can be searched easily.
*   `test_groups` (_array of ab\_test\_group_) Test Groups created for an A/B Test. This is a read only attribute for now.
*   `test_segments` (_array of ab\_test\_segment_) Test Segments created for an A/B Test. This is a read only attribute for now
*   `trigger` (_ab\_test\_trigger_) The trigger that allows the test participant to be considered for an A/B Test

_Example_

```
{
  "customer_groups": [
    "abtest_customer_group"
  ],
  "description": "abtest description",
  "email_addresses": [
    "abtest1@salesforce.com"
  ],
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "expiration_type": "session",
  "id": "my-abtest",
  "key_metric_id": "abtest_key_metric_id",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest",
  "paused": true,
  "start_date": "2015-04-01T11:30:15.000Z",
  "tags": [
    "abtest_tag"
  ],
  "test_groups": [
    {
      "allocation": 20,
      "custom_experience": false,
      "id": "Control"
    },
    {
      "allocation": 40,
      "custom_experience": false,
      "description": "A description",
      "id": "Test Segment A"
    },
    {
      "allocation": 40,
      "custom_experience": false,
      "id": "Test Segment B"
    }
  ],
  "trigger": {
    "is_pipeline_based": false,
    "trigger_type": "immediately"
  }
}
```

### ab\_test\_segment

Document representing an A/B Test Segment

*   `allocation` (_integer (int32)_) Test Group percentage allocation
*   `custom_experience` (_boolean_) Flag to determine if this Test Group is a customer experience
*   `description` (_string_) Test Group description  
    Maximum length: 4000.
*   `id` (_string_) Test group id  
    Minimum length: 1. Maximum length: 40.
*   `link` (_string_)
*   `preferences` (_array of object_) Preferences which this segment has as experiences
*   `promotions` (_array of object_) Promotions which this segment has as experiences
*   `slot_configs` (_array of object_) Slot configurations which this segment has as experiences
*   `sorting_rules` (_array of object_) Sorting rules which this segment has as experiences
*   `stats` (_ab\_test\_segment\_stats_) Statistics about the segment

_Example_

```
{
  "allocation": 10,
  "description": "modified description",
  "id": "my-segment",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/ab_tests/my-abtest/segments/my-segment"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### ab\_test\_group

Document representing an A/B Test Group

*   `allocation` (_integer (int32)_) Test Group percentage allocation
*   `custom_experience` (_boolean_) Flag to determine if this Test Group is a customer experience
*   `description` (_string_) Test Group description
*   `id` (_string_) Test group id

_Example_

```
{
  "allocation": 20,
  "custom_experience": false,
  "id": "Control"
}
```

### ab\_test\_trigger

Document representing an A/B Test trigger.

*   `categories` (_array of string_) The list of categories. This is a modifiable attribute when trigger type is 'category\_page\_view' only
*   `is_pipeline_based` (_boolean_) The flag indicating if the trigger is based on pipelines. This is a computed attribute and cannot be modified
*   `pipeline_calls` (_array of string_) The list of pipeline name and start node combinations (for example, Account-Show). This is a modifiable attribute when trigger type is 'pipeline\_calls' only
*   `trigger_type` (_string_) The type of the trigger. Defaults to 'immediately' if not specified on create  
    Allowed values: `immediately`, `category_page_view`, `home_page_view`, `pipeline_call`.

_Example_

```
{
  "is_pipeline_based": false,
  "trigger_type": "immediately"
}
```

### ab\_test\_segment\_stats

*   `adds_to_baskets` (_integer (int32)_)
*   `average_adds_per_basket` (_number (double)_)
*   `average_adds_per_basket_std_error` (_number (double)_)
*   `average_discount_amount` (_number (double)_)
*   `average_discount_amount_std_error` (_number (double)_)
*   `average_discount_amount_with_coupon` (_number (double)_)
*   `average_discount_amount_with_coupon_std_error` (_number (double)_)
*   `average_discount_amount_without_coupon` (_number (double)_) The standard error for the average amount discounted for orders without using a coupon
*   `average_discount_amount_without_coupon_std_error` (_number (double)_) Units sold per hour
*   `average_order_value` (_number (double)_)
*   `average_order_value_std_error` (_number (double)_)
*   `average_revenue_per_visit` (_number (double)_)
*   `average_revenue_per_visit_std_error` (_number (double)_)
*   `average_units_added_per_basket` (_number (double)_)
*   `average_units_adder_per_basket_std_error` (_number (double)_)
*   `average_units_per_order_std_error` (_number (double)_)
*   `average_units_per_visit` (_number (double)_)
*   `average_units_per_visit_std_error` (_number (double)_)
*   `basket_rate` (_number (double)_)
*   `baskets` (_number (double)_)
*   `checkout_rate` (_number (double)_)
*   `checkouts` (_integer (int32)_)
*   `conversion_rate` (_number (double)_)
*   `discount_amount_with_coupon` (_number (double)_)
*   `discount_amount_without_coupon` (_number (double)_)
*   `orders` (_integer (int32)_)
*   `revenue` (_number (double)_)
*   `total_discount_amount` (_number (double)_)
*   `units` (_number (double)_)
*   `units_added_to_baskets` (_number (double)_)
*   `visitors` (_integer (int32)_)
*   `visits` (_integer (int32)_)

<!-- document id=cbd819e4d485b0ab79f68a5130c2baaee4586fd3400ff1b075ea5ec865ff20c9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-alerts.md -->

Data Alerts (deprecated)

# Data Alerts (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get alert descriptors

`GET /alerts/descriptors`

Operation ID: `Get alert descriptors`. Tags: alerts. Security: oauth2\_application.

Gets a collection of all alert descriptors

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_descriptors`.
    

### GET Get alert descriptors for application context

`GET /alerts/descriptors/{application_id}`

Operation ID: `Get alert descriptors for application context`. Tags: alerts. Security: oauth2\_application.

Gets a collection of all alert descriptors for the given application context.

#### Parameters

*   `application_id` (path, string, required) The application ID.  
    Minimum length: 1.
*   `application_context_path` (query, string) The application context path (optional).

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_descriptors`.
    

### GET Get alert descriptor

`GET /alerts/descriptors/{application_id}/{application_context_path}/{message_id}`

Operation ID: `Get alert descriptor`. Tags: alerts. Security: oauth2\_application.

Gets a single alert descriptor

This endpoint may return the following faults:

*   404 - AlertDescriptorNotFoundException - If no alert descriptor was found for the given path.

#### Parameters

*   `application_id` (path, string, required) The application ID.  
    Minimum length: 1.
*   `application_context_path` (path, string, required) The application context path.  
    Minimum length: 1.
*   `message_id` (path, string, required) The message ID.  
    Minimum length: 1.

#### Responses

*   **404** `AlertDescriptorNotFoundException` - If no alert descriptor was found for the given path.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_descriptor`.
    

### PATCH Trigger rule validation.

`PATCH /alerts/descriptors/{application_id}/{application_context_path}/{message_id}/revalidate`

Operation ID: `Trigger rule validation.`. Tags: alerts. Security: oauth2\_application.

Triggers rule validation for all described descriptors.

When a validation rule for a descriptor is triggered active alerts might be deleted if the conditions are not met anymore. Additionally, new alerts might be created if conditions of a descriptor are now met.

If the alert descriptor is context-specific, a context object ID needs to be provided in the request body. The request body can be ued to further restrict the set of descriptors that are validated.

This endpoint may return the following faults:

*   400 - ContextObjectIdRequiredException - If the descriptor is context specific but no context object id was provided in the request body.
*   404 - AlertDescriptorNotFoundException - If no matching alert descriptor was found.

#### Parameters

*   `application_id` (path, string, required) The application ID.  
    Minimum length: 1.
*   `application_context_path` (path, string, required) The application context path.  
    Minimum length: 1.
*   `message_id` (path, string, required) The message ID.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `alert_descriptors_revalidation_request`.

#### Responses

*   **204**
*   **400** `ContextObjectIdRequiredException` - If the descriptor is context specific but no context object id was provided in the request body.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AlertDescriptorNotFoundException` - If no matching alert descriptor was found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get alerts

`GET /alerts/items`

Operation ID: `Get alerts`. Tags: alerts. Security: oauth2\_application.

Gets a collection of alerts.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_items`.
    

### GET Get alerts for application

`GET /alerts/items/{application_id}`

Operation ID: `Get alerts for application`. Tags: alerts. Security: oauth2\_application.

Gets a collection of alerts for the given application ID.

#### Parameters

*   `application_id` (path, string, required) The application ID.  
    Minimum length: 1.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_items`.
    

### GET Get alert

`GET /alerts/items/{application_id}/{application_context_path}/{message_id}/{context_object_id}`

Operation ID: `Get alert`. Tags: alerts. Security: oauth2\_application.

Gets a single alert.

#### Parameters

*   `application_id` (path, string, required) The application ID.  
    Minimum length: 1.
*   `application_context_path` (path, string, required) The application context path.  
    Minimum length: 1.
*   `message_id` (path, string, required) The message ID.  
    Minimum length: 1.
*   `context_object_id` (path, string, required) The context object ID.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_item`.
    

### DELETE Delete alert

`DELETE /alerts/items/{application_id}/{application_context_path}/{message_id}/{context_object_id}`

Operation ID: `Delete alert`. Tags: alerts. Security: oauth2\_application.

Deletes a single alert.

#### Parameters

*   `application_id` (path, string, required) The application ID.  
    Minimum length: 1.
*   `application_context_path` (path, string, required) The application context path.  
    Minimum length: 1.
*   `message_id` (path, string, required) The message ID.  
    Minimum length: 1.
*   `context_object_id` (path, string, required) The context object ID.

#### Responses

*   **204**

### GET Get alert settings

`GET /alerts/usersettings`

Operation ID: `Get alert settings`. Tags: alerts. Security: oauth2\_application.

Gets the alert settings for the user.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_settings`.
    

### PATCH Change alert settings

`PATCH /alerts/usersettings`

Operation ID: `Change alert settings`. Tags: alerts. Security: oauth2\_application.

Changes the alert settings for the user.

#### Request body

Media type: `application/json, text/xml`. Schema: `alert_settings`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `alert_settings`.
    

## Schemas

### alert\_descriptors

Document containing a collection of alert descriptors.

*   `data` (_array of alert\_descriptor_) Collection of alert descriptors

_Example_

```
{
  "data": [
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "default_priority": "informational",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAuth/PasswordTooShort",
      "message_id": "PasswordTooShort"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "default_priority": "informational",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAuth/UnifiedAuthNotEnforced",
      "message_id": "UnifiedAuthNotEnforced"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "default_priority": "informational",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAuth/UnifiedAuthUsedExclusively",
      "message_id": "UnifiedAuthUsedExclusively"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "default_priority": "informational",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAuth/UnifiedAuthDisabled",
      "message_id": "UnifiedAuthDisabled"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "default_priority": "informational",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAuth/UnifiedAuthOnlySupported",
      "message_id": "UnifiedAuthOnlySupported"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "default_priority": "informational",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAuth/UnifiedAuthOnlyEncouraged",
      "message_id": "UnifiedAuthOnlyEncouraged"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "default_priority": "warning",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAccess/IpRestrictionsNotSet",
      "message_id": "IpRestrictionsNotSet"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "default_priority": "warning",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAccess/IpRestrictionsNoBlocking",
      "message_id": "IpRestrictionsNoBlocking"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "default_priority": "warning",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAccess/IpRestrictionsOnlyBlackList",
      "message_id": "IpRestrictionsOnlyBlackList"
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "default_priority": "warning",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_securityPrefs%2FuserAccess/IpRestrictionsNoSfWhitelist",
      "message_id": "IpRestrictionsNoSfWhitelist"
    },
    {
      "application_context_path": "marketing_promotions/custom_notification",
      "application_id": "marketing",
      "context_object_type": "PromotionPO",
      "default_priority": "warning",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/marketing/marketing_promotions%2Fcustom_notification/promo_in_past",
      "message_id": "promo_in_past"
    },
    {
      "application_context_path": "operations_certificates/certificates",
      "application_id": "operations",
      "context_object_type": "other.KeyStoreEntry",
      "default_priority": "action_required",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/operations/operations_certificates%2Fcertificates/CertExpired",
      "message_id": "CertExpired"
    },
    {
      "application_context_path": "operations_certificates/certificates",
      "application_id": "operations",
      "context_object_type": "other.KeyStoreEntry",
      "default_priority": "action_required",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/operations/operations_certificates%2Fcertificates/CertExpiring",
      "message_id": "CertExpiring"
    },
    {
      "application_context_path": "global-prefs_custom_prefs/custom_notification",
      "application_id": "global-prefs",
      "default_priority": "action_required",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/global-prefs/global-prefs_custom_prefs%2Fcustom_notification/missing_org_config",
      "message_id": "missing_org_config"
    },
    {
      "application_context_path": "customerlists_manage/customerAuth",
      "application_id": "sites",
      "context_object_type": "CustomerList",
      "default_priority": "informational",
      "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/sites/customerlists_manage%2FcustomerAuth/PasswordTooShort",
      "message_id": "PasswordTooShort"
    }
  ]
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### alert\_descriptor

Document describing a single alert descriptor.

*   `application_context_path` (_string_) The application context path.  
    Minimum length: 1.
*   `application_id` (_string_) The application ID.  
    Minimum length: 1.
*   `context_object_type` (_string_) The context object type.
*   `default_priority` (_string_) The default priority.  
    Allowed values: `not_allowed`, `hidden`, `informational`, `warning`, `action_required`. Minimum length: 1.
*   `link` (_string_) URL for this resource.  
    Minimum length: 1.
*   `message_id` (_string_) The message ID.  
    Minimum length: 1.

_Example_

```
{
  "application_context_path": "customerlists_manage/customerAuth",
  "application_id": "sites",
  "context_object_type": "CustomerList",
  "default_priority": "informational",
  "link": "https://example.com/s/-/dw/data/{version}/alerts/descriptors/sites/customerlists_manage%2FcustomerAuth/PasswordTooShort",
  "message_id": "PasswordTooShort"
}
```

### alert\_descriptors\_revalidation\_request

Contains parameters for a alert descriptor revalidation request.

*   `context_object_id` (_string_) ID of the object in which context messages should be revalidated.

_Example_

```
{
  "context_object_id": "123456"
}
```

### alert\_items

Document containing a collection of alerts.

*   `data` (_array of alert\_item_) Collection of alerts

### alert\_item

Document describing a single alert.

*   `application_context_path` (_string_) The application context path.  
    Minimum length: 1.
*   `application_id` (_string_) The application ID.  
    Minimum length: 1.
*   `context_object_id` (_string_) The context object ID.
*   `description` (_string_) The alert description.  
    Minimum length: 1.
*   `display_message` (_string_) The display message.  
    Minimum length: 1.
*   `link` (_string_) URL for this resource.  
    Minimum length: 1.
*   `message_id` (_string_) The message ID.  
    Minimum length: 1.
*   `remediation_action` (_string_) The remediation action.  
    Minimum length: 1.
*   `remediation_is_external` (_boolean_) True when the remediation targets an external URL.
*   `user_priority` (_string_) The user priority.  
    Allowed values: `not_allowed`, `hidden`, `informational`, `warning`, `action_required`. Minimum length: 1.

### alert\_settings

Document containing the alert settings of a user.

*   `settings` (_array of alert\_descriptor\_settings_) Alert settings.

_Example_

```
{
  "settings": [
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "is_user_override": true,
      "message_id": "PasswordTooShort",
      "priority": "hidden",
      "show_in_header": true,
      "show_on_homepage": false
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "UnifiedAuthNotEnforced",
      "priority": "informational",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "UnifiedAuthUsedExclusively",
      "priority": "informational",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "UnifiedAuthDisabled",
      "priority": "informational",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "UnifiedAuthOnlySupported",
      "priority": "informational",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAuth",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "UnifiedAuthOnlyEncouraged",
      "priority": "informational",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "IpRestrictionsNotSet",
      "priority": "warning",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "IpRestrictionsNoBlocking",
      "priority": "warning",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "IpRestrictionsOnlyBlackList",
      "priority": "warning",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_securityPrefs/userAccess",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "IpRestrictionsNoSfWhitelist",
      "priority": "warning",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "marketing_promotions/custom_notification",
      "application_id": "marketing",
      "is_user_override": false,
      "message_id": "promo_in_past",
      "priority": "warning",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "operations_certificates/certificates",
      "application_id": "operations",
      "is_user_override": false,
      "message_id": "CertExpired",
      "priority": "action_required",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "operations_certificates/certificates",
      "application_id": "operations",
      "is_user_override": false,
      "message_id": "CertExpiring",
      "priority": "action_required",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "global-prefs_custom_prefs/custom_notification",
      "application_id": "global-prefs",
      "is_user_override": false,
      "message_id": "missing_org_config",
      "priority": "action_required",
      "show_in_header": true,
      "show_on_homepage": true
    },
    {
      "application_context_path": "customerlists_manage/customerAuth",
      "application_id": "sites",
      "is_user_override": true,
      "message_id": "PasswordTooShort",
      "priority": "action_required",
      "show_in_header": false,
      "show_on_homepage": true
    }
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### alert\_descriptor\_settings

Document describing settings for a single alert descriptor.

*   `application_context_path` (_string_, required) The application context path.  
    Minimum length: 1.
*   `application_id` (_string_, required) The application ID.  
    Minimum length: 1.
*   `is_user_override` (_boolean_, required)
    
    Flag that indicates whether the settings for this descriptor have been changed by the user.
    
    In a PATCH request, this flag must be set to `true` to override the default settings. If this flag to `false` in a PATCH request, the default user settings for this descriptor are restored (and all other fields are ignored).
    
*   `message_id` (_string_, required) The message ID.  
    Minimum length: 1.
*   `priority` (_string_, required) The user priority.  
    Allowed values: `hidden`, `informational`, `warning`, `action_required`.
*   `show_in_header` (_boolean_, required) Flag that indicates whether the alert is shown in the Business Manager header.
*   `show_on_banner` (_boolean_) Flag that indicates whether the alert is shown on the Business Manager banner (on every page).
*   `show_on_homepage` (_boolean_, required) Flag that indicates whether the alert is shown on the Business Manager homepage.

_Example_

```
{
  "application_context_path": "customerlists_manage/customerAuth",
  "application_id": "sites",
  "is_user_override": true,
  "message_id": "PasswordTooShort",
  "priority": "action_required",
  "show_in_header": false,
  "show_on_homepage": true
}
```

<!-- document id=6624b36107162a937943d053fc4c5c597e37f064e1c4ed2067d077675502d2ee url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/data-and-analytics.md -->

# Data and Analytics

Make data-driven decisions with these analytics tools that are pre-integrated with [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html).

- [**Active Data**](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/active-data.html) (also called Active Merchandising): Observe product performance, order metrics, and conversion rates and use aggregate data to set automated rules for merchandising (for example, search result sorting). Analyze shopper behavior so that you can enhance the shopper experience and optimize product offerings to drive sales growth.
- [**B2C Commerce Reports & Dashboards**](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reports-and-dashboards.md): Provide insights to help you understand customer behavior, campaign effectiveness, and overall business health. Identify trends over time and make smarter business decisions based on your B2C Commerce data. View historical data on order conversion metrics, site traffic, frequently searched products, and more.
- [**Integrate PWA Kit with Data Cloud**](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/integrate-data-cloud.md): To unify your customer data on Salesforce, connect your Progressive Web App (PWA) Kit storefront to [Data Cloud](https://help.salesforce.com/s/articleView?id=data.c360_a_data_cloud.htm). After you set your store as a data source, Data Cloud receives engagement events, which are triggered by shopper activities in your storefront.

### See Also

- _Salesforce Help:_ [Active Merchandising](https://help.salesforce.com/s/articleView?id=cc.b2c_active_merchandising.htm&type=5)
- _Salesforce Help:_ [Reports & Dashboards](https://help.salesforce.com/s/articleView?id=cc.b2c_reports_and_dashboards.htm&type=5)

<!-- document id=2aaa15302f8d640e4f1fd2eb72e8f4cc95c11473b887bf348037bff6c3e4d05a url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-campaign-search.md -->

Data Campaign Search (deprecated)

# Data Campaign Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Campaigns

`POST /sites/{site_id}/campaign_search`

Operation ID: `Search Campaigns`. Tags: sites. Security: oauth2\_application.

Searches for campaigns.

The Campaign Search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   campaign\_id - String
    
*   description - String
    
*   enabled - Boolean
    
*   coupon\_id\* - String
    
*   customer\_group\* - String
    
*   source\_code\* - String
    
*   start\_date - Date
    
*   end\_date - Date
    
*   last\_modified - Date
    

These fields can only be used in Queries as conjunctions (using AND). If the field is used in a disjunction (OR) an exception will be thrown.

Note that only searchable attributes (excluding the ones marked with above with an asterisk) can be used in sorting Additionally start\_date, end\_date and last\_modified cannot be used in sorting.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `campaign_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### campaign\_search\_result

Document representing a campaign search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of campaign_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 4,
  "hits": [
    {
      "campaign_id": "disabled-campaign",
      "enabled": false,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/disabled-campaign"
    },
    {
      "campaign_id": "test-campaign",
      "coupons": [
        "couponOne"
      ],
      "customer_groups": [
        "Everyone"
      ],
      "description": "Test Campaign",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/test-campaign"
    },
    {
      "campaign_id": "test-campaign-continuous",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/test-campaign-continuous"
    },
    {
      "campaign_id": "test-campaign-end-continuous",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/test-campaign-end-continuous"
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "campaign"
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 5
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=b40ca903125a73afaa5d4c1b997698e5ff26eee84f70880deb6d5fd04a1c14df url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-campaigns.md -->

Data Campaigns (deprecated)

# Data Campaigns (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Campaign

`GET /sites/{site_id}/campaigns/{campaign_id}`

Operation ID: `Get Campaign`. Tags: sites. Security: oauth2\_application.

Action to get campaign information.

This endpoint may return the following faults:

*   404 - CampaignNotFoundException - Thrown in case the campaign does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site the requested campaign belongs to.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The id of the requested campaign.  
    Minimum length: 1.

#### Responses

*   **404** `CampaignNotFoundException` - Thrown in case the campaign does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `campaign`.
    

### PUT Create Campaign

`PUT /sites/{site_id}/campaigns/{campaign_id}`

Operation ID: `Create Campaign`. Tags: sites. Security: oauth2\_application.

Creates a campaign using the information provided.

This endpoint may return the following faults:

*   400 - IdConflictException - if the Id in request is not the same as the ID in document.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The id of the campaign to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `campaign`.

#### Responses

*   **400** `IdConflictException` - if the Id in request is not the same as the ID in document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `campaign`.
    

### DELETE Delete Campaign

`DELETE /sites/{site_id}/campaigns/{campaign_id}`

Operation ID: `Delete Campaign`. Tags: sites. Security: oauth2\_application.

Deletes the campaign by ID

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) A campaign id to remove

#### Responses

*   **204**

### PATCH Update Campaign

`PATCH /sites/{site_id}/campaigns/{campaign_id}`

Operation ID: `Update Campaign`. Tags: sites. Security: oauth2\_application.

Updates the campaign with the specified information.

This endpoint may return the following faults:

*   400 - CampaignDuplicateException - if a campaign exists already in the site with the given campaign id.
*   404 - CampaignNotFoundException - Thrown in case the campaign does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The id of the requested campaign.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `campaign`.

#### Responses

*   **400** `CampaignDuplicateException` - if a campaign exists already in the site with the given campaign id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Thrown in case the campaign does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `campaign`.
    

### PUT Bind Coupon

`PUT /sites/{site_id}/campaigns/{campaign_id}/coupons/{coupon_id}`

Operation ID: `Bind Coupon`. Tags: sites. Security: oauth2\_application.

Action to bind a single coupon to a given campaign.

This endpoint may return the following faults:

*   400 - ConstraintViolationException - Indicates some parameter constraint violation occurs
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign id is unknown.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The campaign ID that coupons are to be bound to  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The coupon ID to bind to a campaign  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `ConstraintViolationException` - Indicates some parameter constraint violation occurs
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind Coupon

`DELETE /sites/{site_id}/campaigns/{campaign_id}/coupons/{coupon_id}`

Operation ID: `Unbind Coupon`. Tags: sites. Security: oauth2\_application.

Action to unbind a coupon from a given campaign.

This endpoint may return the following faults:

*   400 - ConstraintViolationException - Indicates some parameter constraint violation occurs
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign id is unknown.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The campaign ID that coupons are to be unbound from  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The coupon ID to unbind from a campaign  
    Minimum length: 1.
*   `removeInPCA` (query, string)

#### Responses

*   **204**
*   **400** `ConstraintViolationException` - Indicates some parameter constraint violation occurs
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Bind Customer Group

`PUT /sites/{site_id}/campaigns/{campaign_id}/customer_groups/{customer_group_id}`

Operation ID: `Bind Customer Group`. Tags: sites. Security: oauth2\_application.

Action to bind a single customer group to a given campaign.

This endpoint may return the following faults:

*   400 - ConstraintViolationException - Indicates some parameter constraint violation occurs
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign id is unknown.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The campaign ID that coupons are to be bound to  
    Minimum length: 1.
*   `customer_group_id` (path, string, required) The customer group ID to bind to a campaign  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `ConstraintViolationException` - Indicates some parameter constraint violation occurs
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind Customer Group

`DELETE /sites/{site_id}/campaigns/{campaign_id}/customer_groups/{customer_group_id}`

Operation ID: `Unbind Customer Group`. Tags: sites. Security: oauth2\_application.

Action to unbind a customer group from a given campaign.

This endpoint may return the following faults:

*   400 - ConstraintViolationException - Indicates some parameter constraint violation occurs
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign id is unknown.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The campaign ID that coupons are to be unbound from  
    Minimum length: 1.
*   `customer_group_id` (path, string, required) The customer group ID to unbind from a campaign  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `ConstraintViolationException` - Indicates some parameter constraint violation occurs
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Bind Promotion to Campaign

`PUT /sites/{site_id}/campaigns/{campaign_id}/promotions/{promotion_id}`

Operation ID: `Bind Promotion to Campaign`. Tags: sites. Security: oauth2\_application.

Action to bind a single promotion to a given campaign.

This endpoint may return the following faults:

*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - PromotionNotFoundException - Indicates that the promotion with the given promotion ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.

#### Parameters

*   `site_id` (path, string, required) The ID of the site that contains the campaign and promotion.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The ID of the campaign to which the promotion is to be assigned.  
    Minimum length: 1.
*   `promotion_id` (path, string, required) The ID of the promotion that is to be assigned to the campaign.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `promotion_campaign_assignment`.

#### Responses

*   **204**
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `PromotionNotFoundException` - Indicates that the promotion with the given promotion ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind Promotion

`DELETE /sites/{site_id}/campaigns/{campaign_id}/promotions/{promotion_id}`

Operation ID: `Unbind Promotion`. Tags: sites. Security: oauth2\_application.

Action to unbind a single promotion from a given campaign.

This endpoint may return the following faults:

*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - PromotionNotFoundException - Indicates that the campaign with the given promotion ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.

#### Parameters

*   `site_id` (path, string, required) The ID of the site that contains the campaign and promotion.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The ID of the campaign to which the promotion is to be assigned.  
    Minimum length: 1.
*   `promotion_id` (path, string, required) The ID of the promotion that is to be assigned to the campaign.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `PromotionNotFoundException` - Indicates that the campaign with the given promotion ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Promotion Campaign Assignment

`PATCH /sites/{site_id}/campaigns/{campaign_id}/promotions/{promotion_id}`

Operation ID: `Update Promotion Campaign Assignment`. Tags: sites. Security: oauth2\_application.

Action to update the assignment of promotion to a campaign.

This endpoint may return the following faults:

*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - CouponNotFoundException - Indicates that the coupon with the given coupon ID is not found.
*   404 - CustomerGroupNotFoundException - Indicates that the customer group with the given customer group ID is not found.
*   404 - PromotionNotFoundException - Indicates that the promotion with the given promotion ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.
*   404 - SourceCodeGroupNotFoundException - Indicates that the source code group with the given source code group ID is not found.

#### Parameters

*   `campaign_id` (path, string, required) The ID of the campaign.  
    Minimum length: 1.
*   `site_id` (path, string, required) The ID of the site.  
    Minimum length: 1.
*   `promotion_id` (path, string, required) The ID of the promotion.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `promotion_campaign_assignment`.

#### Responses

*   **204**
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `CouponNotFoundException` - Indicates that the coupon with the given coupon ID is not found. or `CustomerGroupNotFoundException` - Indicates that the customer group with the given customer group ID is not found. or `PromotionNotFoundException` - Indicates that the promotion with the given promotion ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found. or `SourceCodeGroupNotFoundException` - Indicates that the source code group with the given source code group ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Bind Slot Configuration to Campaign

`PUT /sites/{site_id}/campaigns/{campaign_id}/slot_configurations/{slot_id}/{slot_config_id}`

Operation ID: `Bind Slot Configuration to Campaign`. Tags: sites. Security: oauth2\_application.

Action to bind a slot configuration to a given campaign.

This endpoint may return the following faults:

*   400 - IdConflictException - Indicates the ID in the URL does not match the ID in the request
*   400 - InvalidContextTypeException - Indicates the slot context type is not one of "global", "category", or "folder"
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.
*   404 - SlotConfigurationIdentifierNotFoundException - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found.
*   404 - SlotWithContextTypeNotFoundException - Indicates that the slot with the given slot ID and context type is not found.

#### Parameters

*   `campaign_id` (path, string, required) The ID of the campaign.  
    Minimum length: 1.
*   `site_id` (path, string, required) The ID of the site.  
    Minimum length: 1.
*   `slot_id` (path, string, required) The ID of the slot.  
    Minimum length: 1.
*   `slot_config_id` (path, string, required) The ID of the slot configuration.  
    Minimum length: 1.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be folder, category or global), an equals sign (=), and the context id (either the category id or folder id). If you do not set this query parameter, the global context is used by default.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `slot_configuration_campaign_assignment`.

#### Responses

*   **204**
*   **400** `IdConflictException` - Indicates the ID in the URL does not match the ID in the request or `InvalidContextTypeException` - Indicates the slot context type is not one of "global", "category", or "folder"
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found. or `SlotConfigurationIdentifierNotFoundException` - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found. or `SlotWithContextTypeNotFoundException` - Indicates that the slot with the given slot ID and context type is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind SlotConfiguration

`DELETE /sites/{site_id}/campaigns/{campaign_id}/slot_configurations/{slot_id}/{slot_config_id}`

Operation ID: `Unbind SlotConfiguration`. Tags: sites. Security: oauth2\_application.

Action to unbind a slot configuration from a given campaign.

This endpoint may return the following faults:

*   400 - InvalidContextTypeException - Indicates the slot context type is not one of "global", "category", or "folder"
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.
*   404 - SlotConfigurationIdentifierNotFoundException - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found.
*   404 - SlotWithContextTypeNotFoundException - Indicates that the slot with the given slot ID and context type is not found.

#### Parameters

*   `campaign_id` (path, string, required) The id of the campaign  
    Minimum length: 1.
*   `site_id` (path, string, required) The id of the site  
    Minimum length: 1.
*   `slot_id` (path, string, required) The of the slot  
    Minimum length: 1.
*   `slot_config_id` (path, string, required) The id of the slot configuration  
    Minimum length: 1.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be folder, category or global), an equals sign (=), and the context id (either the category id or folder id).  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `InvalidContextTypeException` - Indicates the slot context type is not one of "global", "category", or "folder"
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found. or `SlotConfigurationIdentifierNotFoundException` - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found. or `SlotWithContextTypeNotFoundException` - Indicates that the slot with the given slot ID and context type is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Slot Configuration Campaign Assignment

`PATCH /sites/{site_id}/campaigns/{campaign_id}/slot_configurations/{slot_id}/{slot_config_id}`

Operation ID: `Update Slot Configuration Campaign Assignment`. Tags: sites. Security: oauth2\_application.

Action to update the assignment of slot configuration to a campaign.

This endpoint may return the following faults:

*   400 - InvalidContextTypeException - Indicates the slot context type is not one of "global", "category", or "folder"
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.
*   404 - SlotConfigurationIdentifierNotFoundException - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found.
*   404 - SlotWithContextTypeNotFoundException - Indicates that the slot with the given slot ID and context type is not found.

#### Parameters

*   `campaign_id` (path, string, required) The ID of the campaign.  
    Minimum length: 1.
*   `site_id` (path, string, required) The ID of the site.  
    Minimum length: 1.
*   `slot_id` (path, string, required) The ID of the slot.  
    Minimum length: 1.
*   `slot_config_id` (path, string, required) The ID of the slot configuration.  
    Minimum length: 1.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be folder, category or global), an equals sign (=), and the context id (either the category id or folder id). If you do not set this query parameter, the global context is used by default.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `slot_configuration_campaign_assignment`.

#### Responses

*   **204**
*   **400** `InvalidContextTypeException` - Indicates the slot context type is not one of "global", "category", or "folder"
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found. or `SlotConfigurationIdentifierNotFoundException` - Indicates that the slot with the given slot ID, slot configuration ID and context type is not found. or `SlotWithContextTypeNotFoundException` - Indicates that the slot with the given slot ID and context type is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Bind SortingRule to Campaign

`PUT /sites/{site_id}/campaigns/{campaign_id}/sorting_rules/{sorting_rule_id}/{category_id}`

Operation ID: `Bind SortingRule to Campaign`. Tags: sites. Security: oauth2\_application.

Action to bind a single sorting rule to a given campaign.

This endpoint may return the following faults:

*   400 - InvalidCategoryException - Indicates that the category with the given category ID is not found.
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.
*   404 - SortingRuleNotFoundException - Indicates that the sorting rule with the given sorting rule ID is not found.
*   409 - SortingRuleCampaignAssignConflictException - Indicates that there is a sorting rule already assigned to the given campaign ID and category ID. The sorting rule with the given sorting rule ID cannot be assigned to the same campaign ID and category ID.

#### Parameters

*   `site_id` (path, string, required) The ID of the site that contains the campaign, sorting rule and category.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The ID of the campaign to which the sorting rule is to be assigned.  
    Minimum length: 1.
*   `sorting_rule_id` (path, string, required) The ID of sorting rule that is to be assigned to the campaign.  
    Minimum length: 1.
*   `category_id` (path, string, required) The ID of the category that is associated with the sorting rule.  
    Minimum length: 1.
*   `rule_context` (query, string) The context in which the rule lives, either "site" or "global"

#### Responses

*   **204**
*   **400** `InvalidCategoryException` - Indicates that the category with the given category ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found. or `SortingRuleNotFoundException` - Indicates that the sorting rule with the given sorting rule ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `SortingRuleCampaignAssignConflictException` - Indicates that there is a sorting rule already assigned to the given campaign ID and category ID. The sorting rule with the given sorting rule ID cannot be assigned to the same campaign ID and category ID.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE UnBind SortingRule

`DELETE /sites/{site_id}/campaigns/{campaign_id}/sorting_rules/{sorting_rule_id}/{category_id}`

Operation ID: `UnBind SortingRule`. Tags: sites. Security: oauth2\_application.

Action to unbind a single sorting rule from a given campaign.

This endpoint may return the following faults:

*   400 - InvalidCategoryException - Indicates that the category with the given category ID is not found.
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign ID is not found.
*   404 - SiteNotFoundException - thrown when site with the given site id is not found.
*   404 - SortingRuleNotFoundException - Indicates that the sorting rule with the given sorting rule ID is not found.

#### Parameters

*   `site_id` (path, string, required) The ID of the site that contains the campaign, sorting rule and category.  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The ID of the campaign to which the sorting rule is to be assigned.  
    Minimum length: 1.
*   `sorting_rule_id` (path, string, required) The ID of sorting rule that is to be assigned to the campaign.  
    Minimum length: 1.
*   `category_id` (path, string, required) The ID of the category that is associated with the sorting rule.  
    Minimum length: 1.
*   `rule_context` (query, string) The context in which the rule lives, either "site" or "global"

#### Responses

*   **204**
*   **400** `InvalidCategoryException` - Indicates that the category with the given category ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign ID is not found. or `SiteNotFoundException` - thrown when site with the given site id is not found. or `SortingRuleNotFoundException` - Indicates that the sorting rule with the given sorting rule ID is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Bind Source Code Group

`PUT /sites/{site_id}/campaigns/{campaign_id}/source_code_groups/{source_code_group_id}`

Operation ID: `Bind Source Code Group`. Tags: sites. Security: oauth2\_application.

Action to bind a single source code group to a given campaign.

This endpoint may return the following faults:

*   400 - ConstraintViolationException - Indicates some parameter constraint violation occurs
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign id is unknown.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The campaign ID that source code group are to be bound to  
    Minimum length: 1.
*   `source_code_group_id` (path, string, required) The source code group ID to bind to a campaign  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `ConstraintViolationException` - Indicates some parameter constraint violation occurs
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Unbind Source Code Group

`DELETE /sites/{site_id}/campaigns/{campaign_id}/source_code_groups/{source_code_group_id}`

Operation ID: `Unbind Source Code Group`. Tags: sites. Security: oauth2\_application.

Action to unbind a source code group from a given campaign.

This endpoint may return the following faults:

*   400 - ConstraintViolationException - Indicates some parameter constraint violation occurs
*   404 - CampaignNotFoundException - Indicates that the campaign with the given campaign id is unknown.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `campaign_id` (path, string, required) The campaign ID that source code groups are to be unbound from  
    Minimum length: 1.
*   `source_code_group_id` (path, string, required) The source code group ID to unbind from a campaign  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `ConstraintViolationException` - Indicates some parameter constraint violation occurs
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CampaignNotFoundException` - Indicates that the campaign with the given campaign id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### promotion\_campaign\_assignment

Document representing a promotion campaign assignment.

*   `campaign` (_campaign_) The campaign
*   `campaign_id` (_string_) The id of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The sorted array of assigned coupon ids.
*   `coupons_based` (_boolean_) True if the assigned promotion is coupon based. When set to false, Coupons in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The sorted array of assigned customer groups.
*   `customer_groups_based` (_boolean_) True if the assigned promotion is customer group based. When set to false, Customer Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `description` (_string_) The description of the promotion campaign assignment.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) link for convenience
*   `promotion` (_promotion_) The promotion
*   `promotion_id` (_string_) The id of the Promotion.  
    Minimum length: 1. Maximum length: 256.
*   `rank` (_integer (int32)_) The rank of promotion campaign assignment
*   `required_qualifier` (_string_) A constant indicating that one or all qualifier conditions must be met in order for the promotion to apply for a given customer. Valid values are "any" and "all".  
    Allowed values: `any`, `all`.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `source_code_based` (_boolean_) True if the assigned promotion is source code group based. When set to false, Source Code Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `source_code_groups` (_array of string_) The sorted array of assigned source code groups.

_Example_

```
{
  "campaign": {
    "campaign_id": "coupon-campaign",
    "description": "A campaign for coupons.",
    "enabled": true
  },
  "campaign_id": "coupon-campaign",
  "coupons": [
    "order-promotion-coupon"
  ],
  "description": "Coupon Order Promotion",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotions/coupon-promotion-order/campaigns/coupon-campaign",
  "promotion_id": "coupon-promotion-order",
  "schedule": {
    "end_date": "2050-01-01T00:00:00.000Z",
    "start_date": "2000-01-01T00:00:00.000Z"
  }
}
```

### slot\_configuration\_campaign\_assignment

Document representing a slot\_configuration\_campaign\_assignment

*   `campaign` (_campaign_) The campaign.
*   `campaign_id` (_string_) The id of the campaign that has the slot configuration assigned to it.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_, required) The slot context.  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The list of customer groups.
*   `description` (_string_) The description of the slot configuration.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL to the slot configuration-campaign assignment.
*   `rank` (_integer (int32)_) The rank of the slot confiuration-campaign assignment. This is different than the rank of the slot configuration.  
    Minimum: 1.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `slot_configuration` (_slot\_configuration_) The slotConfiguration
*   `slot_configuration_id` (_string_, required) The ID of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `slot_configuration_uuid` (_string_) The UUID of the slot configuration.  
    Maximum length: 28.
*   `slot_context_id` (_string_) The ID of the slot's context, for example, the category ID for a slot with category context.  
    Maximum length: 256.
*   `slot_id` (_string_, required) The ID of the slot.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "campaign_id": "campaign-registered",
  "context": "global",
  "description": "Free Microsoft Zune With Purchase Of $500 Or More In Electronics",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slot_configuration_campaign_assignments/campaign-registered",
  "schedule": {},
  "slot_configuration": {
    "assignment_information": {
      "active": true,
      "active_campaign_assignments": {
        "campaign_id": "campaign-registered",
        "context": "global",
        "enabled": true,
        "rank": 40
      }
    }
  },
  "slot_configuration_id": "Promo Zune",
  "slot_configuration_uuid": "bdL6MiWcbpakEaaadkHwIhZj1N",
  "slot_id": "404-promo"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### promotion

Document representing a promotion. Unless otherwise stated, attributes of this document are not supported when using the Open Commerce API to update multiple promotions at once.

*   `archived` (_boolean_) Determines whether or not this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `assignment_information` (_promotion\_assignment\_information_) Information about the assignments and assignment schedules of this promotion
*   `callout_msg` (_object (localized)_) The localized callout message of the promotion.
    
    Additional properties: `markup_text`.
    
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency_code` (_string_) The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.  
    Maximum length: 3.
*   `disable_globally_excluded` (_boolean_) Determines whether or not this promotion ignores the global product exclusions for promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `enabled` (_boolean_) Determines whether or not this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `exclusivity` (_string_) Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Allowed values: `no`, `class`, `global`.
*   `id` (_string_) The id for the promotion.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A URL that is used to get the details of this promotion.
*   `name` (_object (localized)_) The user supplied name of this promotion, which can be localized
    
    Additional properties: `string`.
    
*   `promotion_class` (_string_) The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, will be reset.  
    Allowed values: `product`, `shipping`, `order`.
*   `tags` (_array of tag_) Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags will be removed.

_Example_

```
{
  "enabled": true,
  "exclusivity": "class",
  "id": "my-promotion",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/my-promotion/my-promotion",
  "name": {
    "default": "My Promotion"
  },
  "promotion_class": "order"
}
```

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### slot\_configuration

Document representing a slot configuration.

*   `assignment_information` (_slot\_configuration\_assignment\_information_) Information about the assignments and assignment schedules of this slot configuration
*   `callout_msg` (_object (localized)_) The call out message.
    
    Additional properties: `markup_text`.
    
*   `configuration_id` (_string_) The id of this configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_) The context of the slot. Ignored in input documents.  
    Allowed values: `global`, `category`, `folder`.
*   `context_id` (_string_) When the context is _category_, this is a _category\_id_; when the context is _folder_, this is a _folder\_id_; and when the context is _global_, this is obsolete. This is ignored in input documents.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The customer groups ids.
*   `default` (_boolean_) A flag indicating whether the configuration is the default one for the slot.
*   `description` (_string_) The configuration description.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the slot is enabled.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link.
*   `rank` (_integer (int32)_) The rank of the slot configuration on its slot. This rank has nothing to do with the rank on any campaign-assignment, because these are completely different objects. These must be updated separately.  
    Allowed values: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100`. Minimum: 1.
*   `schedule` (_schedule_) The schedule for the slot.
*   `slot_content` (_slot\_content_, required) The content of the slot.
*   `slot_id` (_string_) The ID of the slot. Ignored in input documents.  
    Minimum length: 1. Maximum length: 256.
*   `template` (_string_) The template.  
    Maximum length: 256.
*   `uuid` (_string_, read-only) The uuid of the slot configuration. This property cannot be written and is ignored in input documents.  
    Minimum length: 1. Maximum length: 28.

_Example_

```
{
  "assigned_to_site": true,
  "callout_msg": {
    "default": "some message"
  },
  "configuration_id": "2015-06-24_16:33:18",
  "context": "global",
  "customer_groups": [
    "Administrators",
    "Registered"
  ],
  "default": true,
  "description": "slot configuration description",
  "enabled": true,
  "rank": 2,
  "schedule": {
    "end_date": "2022-03-28T23:21:00.000Z",
    "recurrence": {
      "day_of_week": [
        "monday",
        "sunday"
      ],
      "time_of_day": {
        "time_from": "00:00:00",
        "time_to": "23:59:00"
      }
    },
    "start_date": "2013-03-28T23:21:00.000Z"
  },
  "slot_content": {
    "body": {
      "default": "<html>HTML content</html>"
    },
    "type": "html"
  },
  "slot_id": "header-banner",
  "uuid": "fsdoi43ofijwdf"
}
```

### promotion\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": true,
  "active_campaign_assignments": [
    {
      "campaign_id": "coupon-campaign",
      "coupons": [
        "limitPerCode-coupon",
        "multipleCodes-coupon",
        "longCode-coupon",
        "systemCodes-coupon",
        "limitPerTimePeriod-coupon",
        "disabled-coupon",
        "singleCode-coupon",
        "limitPerCustomer-coupon"
      ],
      "description": "Coupon Promotion",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/coupon-promotion/coupon-campaign",
      "promotion_id": "coupon-promotion",
      "rank": 10,
      "schedule": {}
    }
  ],
  "campaign_id": "coupon-campaign",
  "end_date": "2050-06-01T00:00:00.000Z",
  "schedule": {},
  "schedule_type": "campaign",
  "start_date": "2020-05-01T00:00:00.000Z"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### tag

Document representing a tag

*   `tag_id` (_string_) The id of the tag.

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### slot\_configuration\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": false,
  "enabled": false,
  "schedule_type": "none"
}
```

### slot\_content

Document representing the content type for a slot.

*   `body` (_object (localized)_) The HTML body (valid only for type 'html').
    
    Additional properties: `markup_text`.
    
*   `category_ids` (_array of string_) The category ids (valid only for type 'categories').
*   `content_asset_ids` (_array of string_) The content asset ids (valid only for type 'content\_assets').
*   `product_ids` (_array of string_) The product ids (valid only for type 'products').
*   `type` (_string_, required) The type of content in the slot.  
    Allowed values: `products`, `categories`, `content_assets`, `html`, `recommended_products`.

_Example_

```
{
  "type": "html"
}
```

### promotion\_abtest\_group\_assignment

Document representing a promotionabtestgroupassignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `abtest_id` (_string_) The id for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `schedule` (_schedule_) The schedule informaiton for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment
*   `segment_id` (_string_) The id for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

### slot\_configuration\_abtest\_group\_assignment

Document representing a SlotConfiguration AB test group assignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `abtest_id` (_string_) The id for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `enabled` (_boolean_) True if the ABTest is enabled
*   `schedule` (_schedule_) The schedule information for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `segment_id` (_string_) The id for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.

<!-- document id=0ddd4f6c2a24adba5576872f9fe40540ac8cf7f7bcdd03e5d91bc4f84ca125a0 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-cartridges.md -->

Data Cartridges (deprecated)

# Data Cartridges (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### PUT Overwrite cartridge path

`PUT /sites/{site_id}/cartridges`

Operation ID: `Overwrite cartridge path`. Tags: sites. Security: oauth2\_application.

Overwrite cartridge path.

This endpoint may return the following faults:

*   400 - InvalidCartridgePathException - Indicates that the cartridge path is invalid
*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `cartridge_path_create_request`.

#### Responses

*   **400** `InvalidCartridgePathException` - Indicates that the cartridge path is invalid
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `cartridge_path_api_response`.
    

### POST Add a cartridge to cartridge path

`POST /sites/{site_id}/cartridges`

Operation ID: `Add a cartridge to cartridge path`. Tags: sites. Security: oauth2\_application.

Add a cartridge to current cartridge path.

This endpoint may return the following faults:

*   400 - CartridgeAlreadyExistException - Indicates that the cartridge already exist in cartridge path
*   400 - InvalidCartridgeException - Indicates that the cartridge name is invalid
*   400 - InvalidOperationException - The error may happen when position is either 'after' or 'before'. It indicates either target cartridge is not a existing custom cartridge.
*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `cartridge_path_add_request`.

#### Responses

*   **400** `CartridgeAlreadyExistException` - Indicates that the cartridge already exist in cartridge path or `InvalidCartridgeException` - Indicates that the cartridge name is invalid or `InvalidOperationException` - The error may happen when position is either 'after' or 'before'. It indicates either target cartridge is not a existing custom cartridge.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `cartridge_path_api_response`.
    

### DELETE Remove a cartridge from cartridge path

`DELETE /sites/{site_id}/cartridges/{cartridge_name}`

Operation ID: `Remove a cartridge from cartridge path`. Tags: sites. Security: oauth2\_application.

Remove a cartridge from cartridge path.

This endpoint may return the following faults:

*   400 - InvalidOperationException - It indicates either the cartridge doesn't exist in cartridge path or the cartridge can not be deleted (e.g. System Cartridge).
*   404 - SiteNotFoundException - Indicates that site specified with the given id is unknown.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.
*   `cartridge_name` (path, string, required) request body  
    Minimum length: 1.

#### Responses

*   **400** `InvalidOperationException` - It indicates either the cartridge doesn't exist in cartridge path or the cartridge can not be deleted (e.g. System Cartridge).
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - Indicates that site specified with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `cartridge_path_api_response`.
    

## Schemas

### cartridge\_path\_create\_request

Request Body for put operation

*   `cartridges` (_string_, required) New cartridge path

_Example_

```
{
  "cartridges": "new_cartridges1:new_cartridges2"
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### cartridge\_path\_api\_response

Response of cartridge path related operation

*   `cartridges` (_string_) Updated cartridge path
*   `site_id` (_string_) Site id

_Example_

```
{
  "cartridges": "new_cartridge:custom_cartridge_1:custom_cartridge_2:core",
  "site_id": "SiteGenesis"
}
```

### cartridge\_path\_add\_request

Request body for post operation

*   `name` (_string_, required) Name of the cartridge.
*   `position` (_string_, required) Position of the cartridge.  
    Allowed values: `first`, `last`, `before`, `after`.
*   `target` (_string_) When position is 'before' or 'after', need to specify the target cartridge

_Example_

```
{
  "name": "new_cartridge",
  "position": "before",
  "target": "custom_cartridge_1"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=924a8defd6dae662894d396304845beab37dd65af2548bc03af17721539a11e0 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-catalog-search.md -->

Data Catalog Search (deprecated)

# Data Catalog Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Catalogs

`POST /catalog_search`

Operation ID: `Search Catalogs`. Tags: catalog\_search. Security: oauth2\_application.

Searches for catalogs.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   name - String
    
*   description - String
    
*   creation\_date - DateTime
    
*   last\_modified - DateTime
    

There are two additional fields that can be used as search filters. They are not attributes in CatalogWO object, but can be used as filters to query catalogs based on site assignments.

*   is\_master\_catalog - Boolean
    
*   is\_storefront\_catalog - Boolean
    

On using is\_master\_catalog in the search query, catalogs without any site assignments are returned. On using is\_storefront\_catalog in the search query, catalogs with one or more site assignments are returned.

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   name - String
    
*   description - String
    
*   creation\_date - DateTime
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `catalog_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### catalog\_search\_result

Document representing a catalog search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of catalog_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "data": [
    {
      "assigned_product_count": 22,
      "assigned_sites": [
        {
          "customer_list_link": {
            "customer_list_id": "list1"
          },
          "description": "Site's site used for test.",
          "display_name": "Test site 1",
          "id": "site-1"
        },
        {
          "customer_list_link": {
            "customer_list_id": "list2"
          },
          "description": "Site's site used for test 2.",
          "display_name": "Test site 2",
          "id": "site-2"
        }
      ],
      "category_count": 14,
      "creation_date": "2015-11-18T05:00:00.000Z",
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "end_maintenance": "2015-9-20T05:00:00.000Z",
      "id": "my-catalog1",
      "is_master_catalog": false,
      "is_storefront_catalog": false,
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog1",
      "name": {
        "de": "A German my-name",
        "default": "my-name",
        "en": "An English my-name"
      },
      "online": true,
      "owned_product_count": 19,
      "recommendation_count": 20,
      "root_category": "my-root_category",
      "start_maintenance": "2015-7-22T05:00:00.000Z"
    },
    {
      "assigned_product_count": 22,
      "assigned_sites": [],
      "category_count": 14,
      "creation_date": "2015-11-18T05:00:00.000Z",
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "end_maintenance": "2015-9-20T05:00:00.000Z",
      "id": "my-catalog2",
      "is_master_catalog": false,
      "is_storefront_catalog": false,
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog1",
      "name": {
        "de": "A German my-name",
        "default": "my-name",
        "en": "An English my-name"
      },
      "online": true,
      "owned_product_count": 19,
      "recommendation_count": 20,
      "root_category": "my-root_category",
      "start_maintenance": "2015-7-22T05:00:00.000Z"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 2
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### catalog

Document representing a catalog

*   `assigned_product_count` (_integer (int32)_) The count of products assigned to the catalog. It is read only.
*   `assigned_sites` (_array of site_) The sites assigned to the catalog. It is read only.
*   `category_count` (_integer (int32)_) The category count of catalog. It is read only.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_object (localized)_) The description of catalog
    
    Additional properties: `string`.
    
*   `id` (_string_) The catalog Id
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance. It is read only.
*   `name` (_object (localized)_) The catalog name
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The online status of catalog
*   `owned_product_count` (_integer (int32)_) The count of products owned by the catalog. It is read only.
*   `recommendation_count` (_integer (int32)_) The recommendation count of the catalog. It is read only.
*   `root_category` (_string_) The root category of the catalog. It is read only

_Example_

```
{
  "assigned_product_count": 96,
  "assigned_sites": [
    {
      "customer_list_link": {
        "customer_list_id": "list1"
      },
      "description": "Site's site used for test.",
      "display_name": "Test site 1",
      "id": "site-1"
    },
    {
      "customer_list_link": {
        "customer_list_id": "list2"
      },
      "description": "Site's site used for test 2.",
      "display_name": "Test site 2",
      "id": "site-2"
    }
  ],
  "category_count": 37,
  "creation_date": "2015-10-02T14:16:08.000Z",
  "description": "My catalog.",
  "id": "my-catalog",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog",
  "name": "My Catalog",
  "online": true,
  "owned_product_count": 148,
  "recommendation_count": 5,
  "root_category": "root"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### site

Document representing a site.

*   `cartridges` (_string_) The cartridge Path of the site
*   `creation_date` (_string (date-time)_)
*   `customer_list_link` (_customer\_list\_link_) The link to the customer list.
*   `description` (_object (localized)_) The description of this site.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name entered by the user.
    
    Additional properties: `string`.
    
*   `id` (_string_, required) The id of this site.  
    Minimum length: 1.
*   `in_deletion` (_boolean_) The deletion status of this site, true if in deletion
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link directly to the site
*   `storefront_status` (_string_)  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`.

_Example_

```
{
  "customer_list_link": {
    "customer_list_id": "SiteGenesis",
    "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
  },
  "description": {
    "default": "Prototypical site used for starting point"
  },
  "display_name": {
    "default": "Site Genesis"
  },
  "id": "SiteGenesis",
  "in_deletion": false,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
  "storefront_status": "online"
}
```

### customer\_list\_link

Document representing a link to a customer list.

*   `customer_list_id` (_string_) The customerlist id.
*   `link` (_string_) The target of the link.
*   `title` (_object (localized)_) The link title.
    
    Additional properties: `string`.
    

_Example_

```
{
  "customer_list_id": "SiteGenesis",
  "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=629b0a821c64b7d96de92a73d4af0f0cff788be55dfc6b4f363a6e869c42f644 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-catalogs.md -->

Data Catalogs (deprecated)

# Data Catalogs (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Catalogs

`GET /catalogs`

Operation ID: `Get Catalogs`. Tags: catalogs. Security: oauth2\_application.

Action to get all the catalogs with no filtering.

#### Parameters

*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `expand` (query, array of string)

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `catalogs`.
    

### GET Get Catalog

`GET /catalogs/{catalog_id}`

Operation ID: `Get Catalog`. Tags: catalogs. Security: oauth2\_application.

Gets catalog information by catalog Id.

Expansion "stats" can be used to retrieved some expensive statistic data, such as assigned\_product\_count and owned\_product\_count. Example: /s/-/dw/data/v99\_9/catalogs/my-catalog?expand=stats

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown in case the catalog does not exist matching the given id or the catalog identified was already in deletion.

#### Parameters

*   `catalog_id` (path, string, required) The id of the requested catalog.  
    Minimum length: 1.
*   `expand` (query, array of string)
*   `select` (query, string) the selector for the get. If not passed, the defaultSelector will be used instead.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown in case the catalog does not exist matching the given id or the catalog identified was already in deletion.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `catalog`.
    

### PATCH Update Catalog

`PATCH /catalogs/{catalog_id}`

Operation ID: `Update Catalog`. Tags: catalogs. Security: oauth2\_application.

Updates the catalog with the specified information.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown in case the catalog id is unknown.

#### Parameters

*   `catalog_id` (path, string, required) The id of the requested catalog.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `catalog`.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown in case the catalog id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `catalog`.
    

### GET Get Categories

`GET /catalogs/{catalog_id}/categories`

Operation ID: `Get Categories`. Tags: catalogs. Security: oauth2\_application.

Action to get all the categories with no filtering.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates that the catalog is not provided in the request.

#### Parameters

*   `catalog_id` (path, string, required)  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `expand` (query, array of string)

#### Responses

*   **404** `CatalogNotFoundException` - Indicates that the catalog is not provided in the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `categories`.
    

### GET Get category

`GET /catalogs/{catalog_id}/categories/{category_id}`

Operation ID: `Get category`. Tags: catalogs. Security: oauth2\_application.

Action to read an existing category within a catalog. By default, the server also returns the first level of sub-categories, but you can specify another level by setting the levels parameter. Please note, using a large value for levels may cause performance issues in case of a large and deep category tree.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates that the catalog is not provided in the request.
*   404 - CategoryNotFoundException - Indicates that the category does not exist for the catalog provided in the request.

#### Parameters

*   `catalog_id` (path, string, required) the id of the catalog that the category belongs to  
    Minimum length: 1.
*   `category_id` (path, string, required) the id of the category requested  
    Minimum length: 1. Maximum length: 256.
*   `levels` (query, integer (int32)) Specifies how many levels of nested sub-categories you want the server to return. The default value is 1.  
    Minimum: 0.
*   `expand` (query, array of string) the expansion that client can use to specify and retrieve further information about the category (Internal use only for now).

#### Responses

*   **404** `CatalogNotFoundException` - Indicates that the catalog is not provided in the request. or `CategoryNotFoundException` - Indicates that the category does not exist for the catalog provided in the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category`.
    

### PUT Create Category

`PUT /catalogs/{catalog_id}/categories/{category_id}`

Operation ID: `Create Category`. Tags: catalogs. Security: oauth2\_application.

Creates a catalog category using the information provided.

This endpoint may return the following faults:

*   400 - CategoryInvalidException - Indicates that the category in the request is not valid (the argument indicates the field that was invalid).
*   400 - IdConflictException - Indicates that the category ID in the request URL does not match the category ID in the request body.
*   404 - CatalogNotFoundException - Indicates that the catalog is not provided in the request.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the category to be created  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `category`.

#### Responses

*   **400** `CategoryInvalidException` - Indicates that the category in the request is not valid (the argument indicates the field that was invalid). or `IdConflictException` - Indicates that the category ID in the request URL does not match the category ID in the request body.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Indicates that the catalog is not provided in the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category`.
    

### DELETE Delete Category

`DELETE /catalogs/{catalog_id}/categories/{category_id}`

Operation ID: `Delete Category`. Tags: catalogs. Security: oauth2\_application.

Deletes the category by catalog ID and category ID

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates that the catalog is not provided in the request.
*   404 - CategoryNotFoundException - Indicates that the category does not exist for the catalog provided in the request.

#### Parameters

*   `catalog_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `category_id` (path, string, required) The category id to remove  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `CatalogNotFoundException` - Indicates that the catalog is not provided in the request. or `CategoryNotFoundException` - Indicates that the category does not exist for the catalog provided in the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Category

`PATCH /catalogs/{catalog_id}/categories/{category_id}`

Operation ID: `Update Category`. Tags: catalogs. Security: oauth2\_application.

Updates a catalog category using the information provided.

This endpoint may return the following faults:

*   400 - CategoryInvalidException - Indicates that the category in the request is not valid (the argument indicates the field that was invalid).
*   404 - CatalogNotFoundException - Indicates that the catalog is not provided in the request.
*   404 - CategoryNotFoundException - Indicates that the category does not exist for the catalog provided in the request.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the category  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `category`.

#### Responses

*   **400** `CategoryInvalidException` - Indicates that the category in the request is not valid (the argument indicates the field that was invalid).
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Indicates that the catalog is not provided in the request. or `CategoryNotFoundException` - Indicates that the category does not exist for the catalog provided in the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category`.
    

### GET Get Category Links

`GET /catalogs/{catalog_id}/categories/{category_id}/category_links`

Operation ID: `Get Category Links`. Tags: catalogs. Security: oauth2\_application.

Action to get a set of outgoing category links in a given catalog category, sorted by position.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown in case the source catalog does not exist
*   404 - CategoryNotFoundException - Thrown in case the source category does not exist

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the source category.  
    Minimum length: 1.
*   `start` (query, integer (int32))
*   `count` (query, integer (int32))
*   `select` (query, string) Optional select clause for getting fields from the returned JSON document.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown in case the source catalog does not exist or `CategoryNotFoundException` - Thrown in case the source category does not exist
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_links`.
    

### GET Get Category Link

`GET /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}`

Operation ID: `Get Category Link`. Tags: catalogs. Security: oauth2\_application.

Action to get category link information.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown in case the source catalog or the target catalog do not exist
*   404 - CategoryLinkNotFoundException - Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type.
*   404 - CategoryNotFoundException - Thrown in case the source category or the target category do not exist

#### Parameters

*   `catalog_id` (path, string, required) The id of the source catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the source category.  
    Minimum length: 1.
*   `target_catalog_id` (path, string, required) The id of the target catalog.  
    Minimum length: 1.
*   `target_category_id` (path, string, required) The id of the target category.  
    Minimum length: 1.
*   `type` (path, string, required) the link type
*   `select` (query, string) Optional select clause for getting fields from the returned JSON document.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown in case the source catalog or the target catalog do not exist or `CategoryLinkNotFoundException` - Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type. or `CategoryNotFoundException` - Thrown in case the source category or the target category do not exist
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_link`.
    

### PUT Create Category Link

`PUT /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}`

Operation ID: `Create Category Link`. Tags: catalogs. Security: oauth2\_application.

Creates a category link using the information provided. If a category link with the same unique identifier, it will be updated with the new position.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown in case the source catalog or the target catalog do not exist
*   404 - CategoryNotFoundException - Thrown in case the source category or the target category do not exist

#### Parameters

*   `catalog_id` (path, string, required) The id of the source catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the source category.  
    Minimum length: 1.
*   `target_catalog_id` (path, string, required) The id of the target catalog.  
    Minimum length: 1.
*   `target_category_id` (path, string, required) The id of the target category.  
    Minimum length: 1.
*   `type` (path, string, required) the link type

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `category_link`.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown in case the source catalog or the target catalog do not exist or `CategoryNotFoundException` - Thrown in case the source category or the target category do not exist
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_link`.
    

### DELETE Delete Category Link

`DELETE /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}`

Operation ID: `Delete Category Link`. Tags: catalogs. Security: oauth2\_application.

Deletes the category link by ID

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown in case the source catalog or the target catalog do not exist
*   404 - CategoryLinkNotFoundException - Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type.
*   404 - CategoryNotFoundException - Thrown in case the source category or the target category do not exist

#### Parameters

*   `catalog_id` (path, string, required) The id of the source catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the source category.  
    Minimum length: 1.
*   `target_catalog_id` (path, string, required) The id of the target catalog.  
    Minimum length: 1.
*   `target_category_id` (path, string, required) The id of the target category.  
    Minimum length: 1.
*   `type` (path, string, required) the link type

#### Responses

*   **204**
*   **404** `CatalogNotFoundException` - Thrown in case the source catalog or the target catalog do not exist or `CategoryLinkNotFoundException` - Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type. or `CategoryNotFoundException` - Thrown in case the source category or the target category do not exist
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Category Link

`PATCH /catalogs/{catalog_id}/categories/{category_id}/category_links/{target_catalog_id}/{target_category_id}/{type}`

Operation ID: `Update Category Link`. Tags: catalogs. Security: oauth2\_application.

Updates the category link with the specified information.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown in case the source catalog or the target catalog do not exist
*   404 - CategoryLinkNotFoundException - Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type.
*   404 - CategoryNotFoundException - Thrown in case the source category or the target category do not exist

#### Parameters

*   `catalog_id` (path, string, required) The id of the source catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the source category.  
    Minimum length: 1.
*   `target_catalog_id` (path, string, required) The id of the target catalog.  
    Minimum length: 1.
*   `target_category_id` (path, string, required) The id of the target category.  
    Minimum length: 1.
*   `type` (path, string, required) the link type

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `category_link`.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown in case the source catalog or the target catalog do not exist or `CategoryLinkNotFoundException` - Thrown in case the category link does not exist from the source catalog/category to the destination catalog/category with the given type. or `CategoryNotFoundException` - Thrown in case the source category or the target category do not exist
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_link`.
    

### POST Search Category Product Assignment

`POST /catalogs/{catalog_id}/categories/{category_id}/category_product_assignment_search`

Operation ID: `Search Category Product Assignment`. Tags: catalogs. Security: oauth2\_application.

Searches for category product assignments.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   product\_id - String
    
*   product\_name - String
    
*   online\_flag - Boolean
    
*   searchable - Boolean
    
*   valid\_from - DateTime
    
*   valid\_to - DateTime
    
*   creation\_date - DateTime
    

Sortable Fields:

*   product\_id - String
    
*   product\_name - String
    
*   position - Double
    
*   creation\_date - DateTime
    

Expansions that can be applied for the search request:

*   product\_base - String - This expand will enable retrieval of the following basic **Product** information:
    
*   product\_images - String - to fetch preview image and image groups specified for the given product
    
*   product\_all\_images - String - to fetch preview image and image groups specified for the product plus images for its variants and variation groups
    
*   product\_variations - String to fetch variations related information, version 17.8+
    
*   product\_availability - String to fetch availability related information, version 17.8+
    
*   product\_categories - String to fetch category related information, version 17.8+
    
*   product\_prices - String to fetch prices related information, version 17.8+
    
*   product\_options - String to fetch options related information, version 17.8+
    
*   product\_all - String to fetch all expanded information, version 17.8+
    
    *   brand
        
    *   ean
        
    *   link
        
    *   long\_description
        
    *   manufacturer\_name
        
    *   manufacturer\_sku
        
    *   name
        
    *   page\_description
        
    *   page\_keywords
        
    *   page\_title
        
    *   searchable
        
    *   short\_description
        
    *   type
        
    *   unit
        
    *   upc
        

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.
*   404 - CatalogNotFoundException - Thrown if the catalog does not exist matching the given category\_id.
*   404 - CategoryNotFoundException - Thrown if the category does not exist matching the given catalog\_id.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the category.  
    Minimum length: 1.
*   `site_id` (query, string) The site context.

#### Request body

Media type: `application/json, text/xml`. Schema: `category_product_assignment_search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Thrown if the catalog does not exist matching the given category\_id. or `CategoryNotFoundException` - Thrown if the category does not exist matching the given catalog\_id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_product_assignment_search_result`.
    

### GET Get Category Product Assignment

`GET /catalogs/{catalog_id}/categories/{category_id}/products/{product_id}`

Operation ID: `Get Category Product Assignment`. Tags: catalogs. Security: oauth2\_application.

Retrieves category product assignment information.

Expands that can be applied for the get request

*   product\_base - String
    
*   product\_images - String - to fetch image groups specified for the given product
    
*   product\_all\_images - String - to fetch image groups specified for the given product plus images for its variants and variation groups
    

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown if the catalog does not exist matching the given id.
*   404 - CategoryNotFoundException - Thrown if the category does not exist matching the given id.
*   404 - CategoryProductAssignmentNotFoundException - Thrown if the category product assignment does not exist matching the given ids.
*   404 - ProductNotFoundException - Thrown if the product does not exist matching the given id.

#### Parameters

*   `catalog_id` (path, string, required) The catalog of the assignment.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the requested category.  
    Minimum length: 1.
*   `product_id` (path, string, required) The id (SKU) of the requested assigned product.  
    Minimum length: 1.
*   `site_id` (query, string) The site context.
*   `expand` (query, array of string) The List of expansion values applied to the product associated to the assignment.
*   `select` (query, string) The selector for the get. If not passed, then the defaultSelector will be used instead.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown if the catalog does not exist matching the given id. or `CategoryNotFoundException` - Thrown if the category does not exist matching the given id. or `CategoryProductAssignmentNotFoundException` - Thrown if the category product assignment does not exist matching the given ids. or `ProductNotFoundException` - Thrown if the product does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_product_assignment`.
    

### PUT Create Category Product Assignment

`PUT /catalogs/{catalog_id}/categories/{category_id}/products/{product_id}`

Operation ID: `Create Category Product Assignment`. Tags: catalogs. Security: oauth2\_application.

**Creates** a category product assignment using the information provided;

As the assigned position n is a **normalized target position** , we'll make sure that the product is assigned to a position so that the order of positions are maintained.

For example, product A, B, C at position 1, 2, 3. product D is assigned to position 2, the end result is A, D, B, C with order of positions 1, 2, 3, 4;

If there are n existing positioned assignment, assigning a new product to position >= n+1 will end with new assignment with position n+1.

This endpoint may return the following faults:

*   400 - IdConflictException - if the Id in request is not the same as the ID in document.
*   404 - CatalogNotFoundException - Thrown if the catalog does not exist matching the given id.
*   404 - CategoryNotFoundException - Thrown if the category does not exist matching the given id.
*   404 - ProductNotFoundException - Thrown if the product does not exist matching the given id.

#### Parameters

*   `catalog_id` (path, string, required) The id of the requested catalog to which to assign the product.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the requested category to which to assign the product.  
    Minimum length: 1.
*   `product_id` (path, string, required) The id (SKU) of the requested product to assign.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `category_product_assignment`.

#### Responses

*   **400** `IdConflictException` - if the Id in request is not the same as the ID in document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Thrown if the catalog does not exist matching the given id. or `CategoryNotFoundException` - Thrown if the category does not exist matching the given id. or `ProductNotFoundException` - Thrown if the product does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_product_assignment`.
    

### DELETE Delete Category Product Assignment

`DELETE /catalogs/{catalog_id}/categories/{category_id}/products/{product_id}`

Operation ID: `Delete Category Product Assignment`. Tags: catalogs. Security: oauth2\_application.

**Removes** a category product assignment;

For example, if we have products A, B, C at positions 1, 2, 7.5 and delete assignment for product B, this will end up the products A, B, C at positions 1, null, 7.5.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown if the catalog does not exist matching the given id.
*   404 - CategoryNotFoundException - Thrown if the category does not exist matching the given id.

#### Parameters

*   `catalog_id` (path, string, required) The catalog of the assignment.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the requested category.  
    Minimum length: 1.
*   `product_id` (path, string, required) The id of the requested product to un-assign.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `CatalogNotFoundException` - Thrown if the catalog does not exist matching the given id. or `CategoryNotFoundException` - Thrown if the category does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Category Product Assignment

`PATCH /catalogs/{catalog_id}/categories/{category_id}/products/{product_id}`

Operation ID: `Update Category Product Assignment`. Tags: catalogs. Security: oauth2\_application.

**Updates** the category product assignment with the specified information, such as position.

As the assigned position n is a **normalized target position** , we'll make sure that the product is assigned to a position so that the order of positions are maintained.

For example, if we have products A, B, C, D at positions 1, 2, 3, 4 and update product A with new position 3, the end result is B, C, A, D with order of positions 1, 2, 3, 4.

If we then update product C to no position, the end result is B, A, D, C with order of positions 1, 2, 3, null.

If there are n existing positioned assignment, updating product to position > = n will end with new assignment with position such that the order of positions is maintained.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Thrown if the catalog does not exist matching the given id.
*   404 - CategoryNotFoundException - Thrown if the category does not exist matching the given id.
*   404 - CategoryProductAssignmentNotFoundException - Thrown if the category product assignment does not exist.
*   404 - ProductNotFoundException - Thrown if the product does not exist matching the given id.

#### Parameters

*   `catalog_id` (path, string, required) The id of the requested catalog to which the product is assigned.  
    Minimum length: 1.
*   `category_id` (path, string, required) The id of the requested category to which the product is assigned.  
    Minimum length: 1.
*   `product_id` (path, string, required) The id (SKU) of the requested assigned product.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `category_product_assignment`.

#### Responses

*   **404** `CatalogNotFoundException` - Thrown if the catalog does not exist matching the given id. or `CategoryNotFoundException` - Thrown if the category does not exist matching the given id. or `CategoryProductAssignmentNotFoundException` - Thrown if the category product assignment does not exist. or `ProductNotFoundException` - Thrown if the product does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_product_assignment`.
    

### POST Search Categories within a Catalog

`POST /catalogs/{catalog_id}/category_search`

Operation ID: `Search Categories within a Catalog`. Tags: catalogs. Security: oauth2\_application.

Searches for catalog categories in the scope of catalog

By default, the server also returns the first level of subcategories, but you can specify another level by setting the levels parameter. Please note, using a large value for levels may cause performance issues in case of a large and deep category tree.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   name - String
    
*   description - String
    
*   creation\_date - DateTime
    
*   online - Boolean
    
*   parent\_category\_id - String
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   name - String
    
*   description - String
    
*   creation\_date - DateTime
    
*   online - Boolean
    
*   position - Double
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.
*   404 - CatalogNotFoundException - Thrown if the specified catalog does not exist.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1. Maximum length: 256.
*   `levels` (query, integer (int32))  
    Minimum: 0.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Thrown if the specified catalog does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_search_result`.
    

### GET Get Shared Product Options

`GET /catalogs/{catalog_id}/shared_product_options`

Operation ID: `Get Shared Product Options`. Tags: catalogs. Security: oauth2\_application.

Read shared product options in a catalog.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `currency` (query, string) The currency mnemonic for retrieving the product option values according to the sorting mode.ex:'USD'

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_options`.
    

### GET Get Product option

`GET /catalogs/{catalog_id}/shared_product_options/{id}`

Operation ID: `Get Product option`. Tags: catalogs. Security: oauth2\_application.

Read a shared product option in a catalog.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.
*   `currency` (query, string) The currency mnemonic for retrieving the product option values according to the sorting mode.ex:'USD'

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option`.
    

### PUT Create Shared Product Option

`PUT /catalogs/{catalog_id}/shared_product_options/{id}`

Operation ID: `Create Shared Product Option`. Tags: catalogs. Security: oauth2\_application.

Creates a shared product option using the information provided.

This endpoint may return the following faults:

*   400 - ProductOptionDuplicateException - Indicates the shared product option is a duplicate.
*   500 - AttributeDefinitionNotFoundException - Indicates the id specified is not a valid attribute definition.
*   404 - CatalogNotFoundException - Indicates the catalog is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option`.

#### Responses

*   **400** `ProductOptionDuplicateException` - Indicates the shared product option is a duplicate.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Indicates the catalog is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Indicates the id specified is not a valid attribute definition.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option`.
    

### DELETE Delete Shared Product Option

`DELETE /catalogs/{catalog_id}/shared_product_options/{id}`

Operation ID: `Delete Shared Product Option`. Tags: catalogs. Security: oauth2\_application.

Deletes a shared product option by ID.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the shared product option.

#### Responses

*   **204**
*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Shared Product Option

`PATCH /catalogs/{catalog_id}/shared_product_options/{id}`

Operation ID: `Update Shared Product Option`. Tags: catalogs. Security: oauth2\_application.

Updates a shared product option with the information provided.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option`.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option`.
    

### GET Get Shared Product Option Values

`GET /catalogs/{catalog_id}/shared_product_options/{option_id}/values`

Operation ID: `Get Shared Product Option Values`. Tags: catalogs. Security: oauth2\_application.

Read shared product option values of a shared product option in a catalog.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_values`.
    

### GET Get Shared Product Option Value

`GET /catalogs/{catalog_id}/shared_product_options/{option_id}/values/{id}`

Operation ID: `Get Shared Product Option Value`. Tags: catalogs. Security: oauth2\_application.

Read a shared product option value of a shared product option in a catalog.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.
*   404 - ProductOptionValueNotFoundException - Indicates the shared product option value is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.
*   `id` (path, string, required) the id of shared product option value.  
    Minimum length: 1.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found. or `ProductOptionValueNotFoundException` - Indicates the shared product option value is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_value`.
    

### PUT Create Shared Product Option Value

`PUT /catalogs/{catalog_id}/shared_product_options/{option_id}/values/{id}`

Operation ID: `Create Shared Product Option Value`. Tags: catalogs. Security: oauth2\_application.

Creates a shared product option value using the information provided.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the shared product option value.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option_value`.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_value`.
    

### DELETE Delete Shared Product Option Value

`DELETE /catalogs/{catalog_id}/shared_product_options/{option_id}/values/{id}`

Operation ID: `Delete Shared Product Option Value`. Tags: catalogs. Security: oauth2\_application.

Deletes a shared product option value by ID.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.
*   404 - ProductOptionValueNotFoundException - Indicates the shared product option value is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the shared product option value.

#### Responses

*   **204**
*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found. or `ProductOptionValueNotFoundException` - Indicates the shared product option value is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Shared Product Option Value

`PATCH /catalogs/{catalog_id}/shared_product_options/{option_id}/values/{id}`

Operation ID: `Update Shared Product Option Value`. Tags: catalogs. Security: oauth2\_application.

Updates a shared product option value with the information provided.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - ProductOptionNotFoundException - Indicates the shared product option is not found.
*   404 - ProductOptionValueNotFoundException - Indicates the shared product option value is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the shared product option.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the shared product option value.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option_value`.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `ProductOptionNotFoundException` - Indicates the shared product option is not found. or `ProductOptionValueNotFoundException` - Indicates the shared product option value is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_value`.
    

### GET Get shared Variation Attributes

`GET /catalogs/{catalog_id}/shared_variation_attributes`

Operation ID: `Get shared Variation Attributes`. Tags: catalogs. Security: oauth2\_application.

Reads variation attributes of a Domain.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.

#### Parameters

*   `catalog_id` (path, string, required) id of the catalog.  
    Minimum length: 1.
*   `start` (query, integer (int32))
*   `count` (query, integer (int32))
*   `select` (query, string)

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attributes`.
    

### GET Get Shared Variation Attribute Values

`GET /catalogs/{catalog_id}/shared_variation_attributes/{attribute_id}/values`

Operation ID: `Get Shared Variation Attribute Values`. Tags: catalogs. Security: oauth2\_application.

Reads variation attribute values of a variation attribute of a catalog.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - VariationAttributeNotFoundException - Indicate the variation attribute is not found

#### Parameters

*   `catalog_id` (path, string, required) id of the owning catalog.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The variation attribute ID that contains the values.  
    Minimum length: 1.
*   `start` (query, integer (int32)) the first record to get in the page
*   `count` (query, integer (int32)) the number of records to get
*   `select` (query, string) a string that specifies which fields to return (default is all).

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `VariationAttributeNotFoundException` - Indicate the variation attribute is not found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_values`.
    

### GET Get Shared Variation Attribute Value

`GET /catalogs/{catalog_id}/shared_variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Get Shared Variation Attribute Value`. Tags: catalogs. Security: oauth2\_application.

Action to get Shared Variation Attribute value information.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - VariationAttributeNotFoundException - Indicate the variation attribute is not found
*   404 - VariationAttributeValueNotFoundException - Indicate the variation attribute value is not found

#### Parameters

*   `catalog_id` (path, string, required) The owning catalog ID.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The variation attribute custom ID  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation attribute value  
    Minimum length: 1.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `VariationAttributeNotFoundException` - Indicate the variation attribute is not found or `VariationAttributeValueNotFoundException` - Indicate the variation attribute value is not found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.
    

### PUT Put Shared Variation Attribute Value

`PUT /catalogs/{catalog_id}/shared_variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Put Shared Variation Attribute Value`. Tags: catalogs. Security: oauth2\_application.

Action to create a Shared Variation Attribute value.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - VariationAttributeNotFoundException - Indicate the variation attribute is not found
*   404 - VariationAttributeValueNotFoundException - Indicate the variation attribute value is not found

#### Parameters

*   `catalog_id` (path, string, required) The owning catalog ID.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The variation attribute ID  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation attribute value  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `VariationAttributeNotFoundException` - Indicate the variation attribute is not found or `VariationAttributeValueNotFoundException` - Indicate the variation attribute value is not found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.
    

### DELETE Delete Shared Variation Attribute Value

`DELETE /catalogs/{catalog_id}/shared_variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Delete Shared Variation Attribute Value`. Tags: catalogs. Security: oauth2\_application.

Deletes the variation attribute value of a variation attribute bound to a catalog

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - if the catalog id specified cannot be found
*   404 - VariationAttributeNotFoundException - if the attribute id specified is not a valid variation attribute
*   404 - VariationAttributeValueNotFoundException - if the value id specified does not a valid value id

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The id of the variation attribute that contains the value.  
    Minimum length: 1.
*   `id` (path, string, required) The id of one value to remove

#### Responses

*   **204**
*   **404** `CatalogNotFoundException` - if the catalog id specified cannot be found or `VariationAttributeNotFoundException` - if the attribute id specified is not a valid variation attribute or `VariationAttributeValueNotFoundException` - if the value id specified does not a valid value id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Shared Variation Attribute Value

`PATCH /catalogs/{catalog_id}/shared_variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Update Shared Variation Attribute Value`. Tags: catalogs. Security: oauth2\_application.

Updates the variation attribute value of a variation attribute of a catalog.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - if the catalog id specified cannot be found
*   404 - VariationAttributeNotFoundException - if the attribute id specified is not a valid variation attribute
*   404 - VariationAttributeValueNotFoundException - if the value id specified does not a valid value id

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The id of the requested variation attribute.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation value.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.

#### Responses

*   **404** `CatalogNotFoundException` - if the catalog id specified cannot be found or `VariationAttributeNotFoundException` - if the attribute id specified is not a valid variation attribute or `VariationAttributeValueNotFoundException` - if the value id specified does not a valid value id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.
    

### GET Get shared Variation Attribute

`GET /catalogs/{catalog_id}/shared_variation_attributes/{id}`

Operation ID: `Get shared Variation Attribute`. Tags: catalogs. Security: oauth2\_application.

Action to get shared variation attribute information only for master Catalog.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - VariationAttributeNotFoundException - Thrown if the variation attribute matching the given id does not exist.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested variation attribute.  
    Minimum length: 1.

#### Responses

*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `VariationAttributeNotFoundException` - Thrown if the variation attribute matching the given id does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute`.
    

### PUT Create shared Variation Attribute

`PUT /catalogs/{catalog_id}/shared_variation_attributes/{id}`

Operation ID: `Create shared Variation Attribute`. Tags: catalogs. Security: oauth2\_application.

Creates a shared variation attribute using the information provided. To create a variation attribute specific to a product, use the products resource.

This endpoint may return the following faults:

*   400 - SharedVariationAttributeIDNotUniqueException - if the specified id isn't unique.
*   500 - AttributeDefinitionNotFoundException - if attribute definition supplied is not a product attribute.
*   404 - CatalogNotFoundException - Indicates the catalog is not found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation attribute to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute`.

#### Responses

*   **400** `SharedVariationAttributeIDNotUniqueException` - if the specified id isn't unique.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Indicates the catalog is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - if attribute definition supplied is not a product attribute.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute`.
    

### DELETE Delete shared Variation Attribute

`DELETE /catalogs/{catalog_id}/shared_variation_attributes/{id}`

Operation ID: `Delete shared Variation Attribute`. Tags: catalogs. Security: oauth2\_application.

Deletes the shared variation attribute by ID.

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - Indicates the catalog is not found.
*   404 - VariationAttributeNotFoundException - Thrown if the variation attribute does not exist.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) One variation attribute id to remove.

#### Responses

*   **204**
*   **404** `CatalogNotFoundException` - Indicates the catalog is not found. or `VariationAttributeNotFoundException` - Thrown if the variation attribute does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update shared Variation Attribute

`PATCH /catalogs/{catalog_id}/shared_variation_attributes/{id}`

Operation ID: `Update shared Variation Attribute`. Tags: catalogs. Security: oauth2\_application.

Updates the shared variation attribute with the specified information.

*   name
    
*   slicing
    

This endpoint may return the following faults:

*   404 - CatalogNotFoundException - if the specified catalog id cannot be found.

#### Parameters

*   `catalog_id` (path, string, required) The id of the catalog.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested variation attribute.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute`.

#### Responses

*   **404** `CatalogNotFoundException` - if the specified catalog id cannot be found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute`.
    

## Schemas

### catalogs

Document representing an unfiltered list of catalogs.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of catalog_) The collection of catalogs.
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "assigned_product_count": 22,
      "assigned_sites": [
        {
          "customer_list_link": {
            "customer_list_id": "list1"
          },
          "description": "Site's site used for test.",
          "display_name": "Test site 1",
          "id": "site-1"
        },
        {
          "customer_list_link": {
            "customer_list_id": "list2"
          },
          "description": "Site's site used for test 2.",
          "display_name": "Test site 2",
          "id": "site-2"
        }
      ],
      "category_count": 14,
      "creation_date": "2015-11-18T05:00:00.000Z",
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "end_maintenance": "2015-9-20T05:00:00.000Z",
      "id": "my-catalog1",
      "is_master_catalog": false,
      "is_storefront_catalog": false,
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog1",
      "name": {
        "de": "A German my-name",
        "default": "my-name",
        "en": "An English my-name"
      },
      "online": true,
      "owned_product_count": 19,
      "recommendation_count": 20,
      "root_category": "my-root_category",
      "start_maintenance": "2015-7-22T05:00:00.000Z"
    },
    {
      "assigned_product_count": 22,
      "assigned_sites": [],
      "category_count": 14,
      "creation_date": "2015-11-18T05:00:00.000Z",
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "end_maintenance": "2015-9-20T05:00:00.000Z",
      "id": "my-catalog2",
      "is_master_catalog": false,
      "is_storefront_catalog": false,
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog1",
      "name": {
        "de": "A German my-name",
        "default": "my-name",
        "en": "An English my-name"
      },
      "online": true,
      "owned_product_count": 19,
      "recommendation_count": 20,
      "root_category": "my-root_category",
      "start_maintenance": "2015-7-22T05:00:00.000Z"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 2
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### catalog

Document representing a catalog

*   `assigned_product_count` (_integer (int32)_) The count of products assigned to the catalog. It is read only.
*   `assigned_sites` (_array of site_) The sites assigned to the catalog. It is read only.
*   `category_count` (_integer (int32)_) The category count of catalog. It is read only.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_object (localized)_) The description of catalog
    
    Additional properties: `string`.
    
*   `id` (_string_) The catalog Id
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance. It is read only.
*   `name` (_object (localized)_) The catalog name
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The online status of catalog
*   `owned_product_count` (_integer (int32)_) The count of products owned by the catalog. It is read only.
*   `recommendation_count` (_integer (int32)_) The recommendation count of the catalog. It is read only.
*   `root_category` (_string_) The root category of the catalog. It is read only

_Example_

```
{
  "assigned_product_count": 96,
  "assigned_sites": [
    {
      "customer_list_link": {
        "customer_list_id": "list1"
      },
      "description": "Site's site used for test.",
      "display_name": "Test site 1",
      "id": "site-1"
    },
    {
      "customer_list_link": {
        "customer_list_id": "list2"
      },
      "description": "Site's site used for test 2.",
      "display_name": "Test site 2",
      "id": "site-2"
    }
  ],
  "category_count": 37,
  "creation_date": "2015-10-02T14:16:08.000Z",
  "description": "My catalog.",
  "id": "my-catalog",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog",
  "name": "My Catalog",
  "online": true,
  "owned_product_count": 148,
  "recommendation_count": 5,
  "root_category": "root"
}
```

### categories

Document representing an unfiltered list of categories.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of category_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 1,
  "data": [
    {
      "categories": [
        {
          "creation_date": "2015-11-30T18:48:37.333Z",
          "description": {
            "default": "sub-category 1 for main catalog"
          },
          "id": "sub-category-1",
          "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/sub-category-1",
          "name": {
            "default": "Sub-category 1"
          },
          "online": true,
          "parent_category_id": "root",
          "paths": [
            {
              "id": "sub-category-1",
              "name": {
                "default": "Sub-category 1"
              }
            }
          ],
          "position": 1,
          "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
        }
      ],
      "creation_date": "2015-11-29T18:48:37.333Z",
      "description": {
        "default": "root category for main catalog"
      },
      "id": "root",
      "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20image",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/root",
      "name": {
        "default": "Root Category"
      },
      "online": true,
      "paths": [
        {
          "id": "root",
          "name": {
            "default": "root"
          }
        }
      ],
      "position": 1,
      "sorting_rules": [
        {
          "creation_date": "2015-11-19T20:46:37.000Z",
          "description": "Sorts by price ascending",
          "id": "price-low-to-high",
          "product_sorting_rule_steps": [
            {
              "direction": "Ascending",
              "is_system": false,
              "position": 0,
              "text_relevance_included": false,
              "type_id": "price"
            }
          ],
          "site": "main-site"
        }
      ],
      "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20thumbnail"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 1
}
```

### category

Document representing a category.

*   `catalog_id` (_string_) The id of the catalog that contains it.
*   `categories` (_array of category_) The array of sub categories for the category.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_object (localized)_) The localized description of the category.
    
    Additional properties: `string`.
    
*   `id` (_string_) The id of the category.  
    Minimum length: 1. Maximum length: 256.
*   `image` (_string_) The name of the category image. The URL to the image is computed.  
    Minimum length: 1. Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The URL to get the category. This is a computed attribute and cannot be modified.
*   `name` (_object (localized)_) The localized name of the category.
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The online status of the category determines if it is visible in the storefront. Defaults to false if not specified on create.
*   `page_description` (_object (localized)_) The localized page description of the category.
    
    Additional properties: `string`.
    
*   `page_keywords` (_object (localized)_) The localized page keywords for the category.
    
    Additional properties: `string`.
    
*   `page_title` (_object (localized)_) The localized page title of the category.
    
    Additional properties: `string`.
    
*   `parent_category_id` (_string_) The id of the parent category. Defaults to root if not specified on create.  
    Minimum length: 1. Maximum length: 256.
*   `paths` (_array of path\_record_)
*   `position` (_number (double)_) The position of the category determines the display order in the storefront.
*   `sorting_rules` (_array of sorting\_rule_)
*   `thumbnail` (_string_) The name of the category thumbnail. The URL to the thumbnail is computed.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "categories": [
    {
      "creation_date": "2015-11-30T18:48:37.333Z",
      "description": {
        "default": "sub-category 1 for main catalog"
      },
      "id": "sub-category-1",
      "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/sub-category-1",
      "name": {
        "default": "Sub-category 1"
      },
      "online": true,
      "parent_category_id": "root",
      "paths": [
        {
          "id": "main-catalog",
          "name": {
            "default": "Main Catalog"
          }
        },
        {
          "id": "root",
          "name": {
            "default": "root category"
          }
        },
        {
          "id": "sub-category-1",
          "name": {
            "default": "Sub-category 1"
          }
        }
      ],
      "position": 1,
      "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
    },
    {
      "creation_date": "2015-12-02T18:48:37.333Z",
      "description": {
        "default": "sub-category 2 for main catalog"
      },
      "id": "sub-category-2",
      "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/sub-category-2",
      "name": {
        "default": "Sub-category 2"
      },
      "online": true,
      "parent_category_id": "root",
      "paths": [
        {
          "id": "main-catalog",
          "name": {
            "default": "Main Catalog"
          }
        },
        {
          "id": "root",
          "name": {
            "default": "root category"
          }
        },
        {
          "id": "sub-category-2",
          "name": {
            "default": "Sub-category 2"
          }
        }
      ],
      "position": 2,
      "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
    }
  ],
  "creation_date": "2015-11-29T18:48:37.333Z",
  "description": {
    "default": "root category for main catalog"
  },
  "id": "root",
  "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20image",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/root",
  "name": {
    "default": "Root Category"
  },
  "online": true,
  "paths": [
    {
      "id": "main-catalog",
      "name": {
        "default": "Main Catalog"
      }
    },
    {
      "id": "root",
      "name": {
        "default": "root"
      }
    }
  ],
  "position": 1,
  "sorting_rules": [
    {
      "creation_date": "2015-11-19T20:46:37.000Z",
      "description": "Sorts by price ascending",
      "id": "price-low-to-high",
      "product_sorting_rule_steps": [
        {
          "direction": "Ascending",
          "is_system": false,
          "position": 0,
          "text_relevance_included": false,
          "type_id": "price"
        }
      ],
      "site": "main-site"
    },
    {
      "creation_date": "2015-11-19T20:46:37.000Z",
      "description": "Sorts by price ascending",
      "id": "price-low-to-high",
      "product_sorting_rule_steps": [
        {
          "direction": "Ascending",
          "is_system": false,
          "position": 0,
          "text_relevance_included": false,
          "type_id": "price"
        }
      ],
      "site": "main-site"
    }
  ],
  "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20thumbnail"
}
```

### category\_links

Document representing an unfiltered list of category links.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of category\_link_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "last_modified": "2015-11-18.75:15:24.827Z",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other",
      "position": 1,
      "source_catalog_id": "MyCatalog",
      "source_catalog_name": {
        "default": "My Catalog"
      },
      "source_category_id": "MyCategory1",
      "source_category_name": {
        "default": "My Awesome Category"
      },
      "target_catalog_id": "OtherCatalog",
      "target_catalog_name": {
        "default": "That Other Catalog"
      },
      "target_category_id": "Category1",
      "target_category_name": {
        "default": "Category 1"
      },
      "type": "other"
    },
    {
      "last_modified": "2015-11-19T15:15:24.000Z",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category2/other",
      "position": 2,
      "source_catalog_id": "MyCatalog",
      "source_catalog_name": {
        "default": "My Catalog"
      },
      "source_category_id": "MyCategory1",
      "source_category_name": {
        "default": "My Awesome Category"
      },
      "target_catalog_id": "OtherCatalog",
      "target_catalog_name": {
        "default": "That Other Catalog"
      },
      "target_category_id": "Category2",
      "target_category_name": {
        "default": "Category 2"
      },
      "type": "other"
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 2
}
```

### category\_link

Document representing a category link

*   `last_modified` (_string (date-time)_) The date the link was last modified
*   `link` (_string_) URL that is used to get this instance
*   `position` (_number (double)_) The position in the source catalog / category for this link relative to the other links in the same category.  
    Minimum: 0.
*   `source_catalog_id` (_string_) The source catalog for the link
*   `source_catalog_name` (_object (localized)_) The name of the source catalog
    
    Additional properties: `string`.
    
*   `source_category_id` (_string_) The source category for the link
*   `source_category_name` (_object (localized)_) The name of the source category
    
    Additional properties: `string`.
    
*   `target_catalog_id` (_string_) The target category for the link
*   `target_catalog_name` (_object (localized)_) The name of the target catalog
    
    Additional properties: `string`.
    
*   `target_category_id` (_string_) The target category for the link
*   `target_category_name` (_object (localized)_) The name of the target category
    
    Additional properties: `string`.
    
*   `type` (_string_) The link type  
    Allowed values: `other`, `accessories`, `cross_selling`, `up_selling`, `spare_parts`.

_Example_

```
{
  "last_modified": "2015-11-18.75:15:24.827Z",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/MyCatalog/categories/MyCategory1/category_links/OtherCatalog/Category1/other",
  "position": 2,
  "source_catalog_id": "MyCatalog",
  "source_catalog_name": {
    "default": "My Catalog"
  },
  "source_category_id": "MyCategory1",
  "source_category_name": {
    "default": "My Awesome Category"
  },
  "target_catalog_id": "OtherCatalog",
  "target_catalog_name": {
    "default": "That Other Catalog"
  },
  "target_category_id": "Category1",
  "target_category_name": {
    "default": "Category 1"
  },
  "type": "other"
}
```

### category\_product\_assignment\_search\_request

Document representing product\_search\_request

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_)
    
    The list of expansions that can be applied:
    
    *   product\_base - String - This expand will enable retrieval of the following basic **Product** information:
        
        *   brand
            
        *   ean
            
        *   link
            
        *   long\_description
            
        *   manufacturer\_name
            
        *   manufacturer\_sku
            
        *   name
            
        *   page\_description
            
        *   page\_keywords
            
        *   page\_title
            
        *   searchable
            
        *   short\_description
            
        *   type
            
        *   unit
            
        *   upc
            
*   `query` (_query_, required) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

_Example_

```
{
  "expand": [
    "product_base"
  ],
  "query": {
    "text_query": {
      "fields": [
        "product_id"
      ],
      "search_phrase": "sample_product"
    }
  },
  "select": "(**)"
}
```

### category\_product\_assignment\_search\_result

Document representing a product search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of category\_product\_assignment_) The sorted array of search hits. This array can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "catalog_id": "SampleCatalog",
      "category_id": "SampleCategory",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/SampleCatalog/category_product_assignments/SampleCategory/sample_product1",
      "owning_catalog_name": {
        "default": "Apparel Main Catalog"
      },
      "position": 1,
      "product": {
        "id": "sample_product",
        "link": "https://example.com/s/-/dw/data/{version}/products/sample_product1",
        "long_description": {
          "default": "We took this classic crew neck and updated it with jewels and embroidery."
        },
        "name": {
          "default": "Long Sleeve Appliqued Crew Neck"
        },
        "online": true,
        "page_description": {
          "default": "We took this classic crew neck and updated it with jewels and embroidery."
        },
        "page_title": {
          "default": "Long Sleeve Appliqued Crew Neck"
        },
        "searchable": true,
        "short_description": {
          "default": "We took this classic crew neck and updated it with jewels and embroidery."
        },
        "type": {
          "variant": true
        },
        "upc": "701642824237"
      },
      "product_id": "sample_product1"
    },
    {
      "catalog_id": "SampleCatalog",
      "category_id": "SampleCategory",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/SampleCatalog/category_product_assignments/SampleCategory/sample_product2",
      "owning_catalog_name": {
        "default": "Apparel Main Catalog"
      },
      "position": 2,
      "product": {
        "id": "008884304023",
        "link": "https://example.com/s/-/dw/data/{version}/products/sample_product2",
        "long_description": {
          "default": "Love our easy care solid shirting? Then give our stripes a try! This subtle blue stripe is a nice option to have in your closet for workplace wear and it even has a bit of stretch for extra comfort."
        },
        "name": {
          "default": "Platinum Blue Stripes Easy Care Fitted Shirt "
        },
        "online": true,
        "page_description": {
          "default": "Love our easy care solid shirting? Then give our stripes a try! This subtle blue stripe is a nice option to have in your closet for workplace wear and it even has a bit of stretch for extra comfort."
        },
        "page_title": {
          "default": "Platinum Blue Stripes Easy Care Fitted Shirt "
        },
        "searchable": true,
        "short_description": {
          "default": "Love our easy care solid shirting? Then give our stripes a try! This subtle blue stripe is a nice option to have in your closet for workplace wear and it even has a bit of stretch for extra comfort."
        },
        "type": {
          "variant": true
        },
        "upc": "008884304023"
      },
      "product_id": "sample_product2"
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id"
      ],
      "search_phrase": "sample_product"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### category\_product\_assignment

Document representing a category product assignment.

*   `catalog_id` (_string_) The id of the catalog.  
    Minimum length: 1. Maximum length: 256.
*   `category_id` (_string_) The id of the category.  
    Minimum length: 1. Maximum length: 256.
*   `creation_date` (_string (date-time)_)
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL used to get the product category assignment.
*   `owning_catalog_name` (_object (localized)_) The name of the catalog that owns the product.
    
    Additional properties: `string`.
    
*   `position` (_number (double)_) The position of product category assignment.
*   `product` (_product_) The product that is assigned to the category.
*   `product_id` (_string_) The id of the Product.  
    Minimum length: 1. Maximum length: 256.
*   `product_name` (_object (localized)_) The name of the product.
    
    Additional properties: `string`.
    

_Example_

```
{
  "catalog_id": "SampleCatalog",
  "category_id": "SampleCategory",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/SampleCatalog/category_product_assignments/SampleCategory/sample_product1",
  "owning_catalog_name": {
    "default": "Apparel Main Catalog"
  },
  "position": 1,
  "product": {
    "id": "sample_product",
    "link": "https://example.com/s/-/dw/data/{version}/products/sample_product1",
    "long_description": {
      "default": "We took this classic crew neck and updated it with jewels and embroidery."
    },
    "name": {
      "default": "Long Sleeve Appliqued Crew Neck"
    },
    "online": true,
    "page_description": {
      "default": "We took this classic crew neck and updated it with jewels and embroidery."
    },
    "page_title": {
      "default": "Long Sleeve Appliqued Crew Neck"
    },
    "searchable": true,
    "short_description": {
      "default": "We took this classic crew neck and updated it with jewels and embroidery."
    },
    "type": {
      "variant": true
    },
    "upc": "701642824237"
  },
  "product_id": "sample_product1"
}
```

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### category\_search\_result

Document representing a catalog search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of category_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "data": [
    {
      "categories": [
        {
          "creation_date": "2015-11-30T18:48:37.333Z",
          "description": {
            "default": "sub-category 1 for main catalog"
          },
          "id": "sub-category-1",
          "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/sub-category-1",
          "name": {
            "default": "Sub-category 1"
          },
          "online": true,
          "parent_category_id": "root",
          "paths": [
            {
              "id": "sub-category-1",
              "name": {
                "default": "Sub-category 1"
              }
            }
          ],
          "position": 1,
          "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
        }
      ],
      "creation_date": "2015-11-29T18:48:37.333Z",
      "description": {
        "default": "root category for main catalog"
      },
      "id": "root",
      "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20image",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/root",
      "name": {
        "default": "Root Category"
      },
      "online": true,
      "paths": [
        {
          "id": "root",
          "name": {
            "default": "root"
          }
        }
      ],
      "position": 1,
      "sorting_rules": [
        {
          "creation_date": "2015-11-19T20:46:37.000Z",
          "description": "Sorts by price ascending",
          "id": "price-low-to-high",
          "product_sorting_rule_steps": [
            {
              "direction": "Ascending",
              "is_system": false,
              "position": 0,
              "text_relevance_included": false,
              "type_id": "price"
            }
          ],
          "site": "main-site"
        }
      ],
      "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20thumbnail"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 1
}
```

### product\_options

Document representing an unfiltered list of product options.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of product\_option_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "custom_name": {
        "default": "Shared Service"
      },
      "default_product_option_value": "S00",
      "description": {
        "default": "Service description"
      },
      "id": "service",
      "image": {
        "abs_url": "https://example.com/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
        "dis_base_url": "https://example.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
        "path": "Desert.jpg"
      },
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service",
      "name": "Shared Service",
      "shared": true,
      "sorting_mode": "byexplicitorder",
      "values": [
        {
          "id": "S00",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service/Values/S00",
          "sku_extension": "S00",
          "value": {
            "default": "None"
          }
        },
        {
          "id": "S01",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service/Values/S01",
          "option_price": {
            "USD": "9.99"
          },
          "sku_extension": "S01",
          "value": {
            "default": "1-year"
          }
        },
        {
          "id": "S02",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service/Values/S02",
          "option_price": {
            "USD": "19.99"
          },
          "sku_extension": "S02",
          "value": {
            "default": "2-year"
          }
        }
      ]
    },
    {
      "custom_name": {
        "default": "Extended Warranty"
      },
      "default_product_option_value": "000",
      "id": "warranty",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty",
      "name": "Extended Warranty",
      "shared": true,
      "sorting_mode": "byoptionprice",
      "values": [
        {
          "id": "001",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/001",
          "option_price": {
            "USD": "9.99"
          },
          "value": {
            "default": "1 Year Warranty"
          }
        },
        {
          "id": "003",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/003",
          "option_price": {
            "USD": "29.99"
          },
          "value": {
            "default": "5 Year Warranty"
          }
        },
        {
          "id": "000",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/000",
          "option_price": {
            "USD": "39.99"
          },
          "value": {
            "default": "None"
          }
        },
        {
          "id": "002",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/002",
          "option_price": {
            "USD": "49.99"
          },
          "value": {
            "default": "3 Year Warranty"
          }
        }
      ]
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 2
}
```

### product\_option

Document representing a product option

*   `custom_name` (_object (localized)_) The localized custom name of the product option.
    
    Additional properties: `string`.
    
*   `default_product_option_value` (_string_) The default product option value.
*   `description` (_object (localized)_) The localized description of the product option.
    
    Additional properties: `string`.
    
*   `id` (_string_) The object attribute definition id which is also the identifier for the product option.  
    Minimum length: 1.
*   `image` (_media\_file_) The image assigned to the product option.
*   `link` (_string_) The URL link to the product option.
*   `name` (_string_) The name of the object attribute definition.
*   `selected_option_value` (_string_) The selected option value of the product option.
*   `shared` (_boolean_) The flag that indicates if the product option is shared or local.
*   `sorting_mode` (_string_) The sorting mode for the product option values.  
    Allowed values: `byexplicitorder`, `byoptionprice`.
*   `values` (_array of product\_option\_value_) The sorted array of values of the product option.

_Example_

```
{
  "custom_name": {
    "default": "Option 15"
  },
  "description": {
    "default": "Description for Option 15"
  },
  "id": "option15",
  "image": {
    "abs_url": "https://example.com/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
    "dis_base_url": "https://example.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
    "path": "Desert.jpg"
  },
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15",
  "name": "15",
  "shared": true,
  "sorting_mode": "byoptionprice",
  "values": [
    {
      "id": "10",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15/Values/10",
      "option_price": {
        "USD": "9.99"
      },
      "sku_extension": "12",
      "value": {
        "default": "12"
      }
    },
    {
      "id": "121",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15/Values/121",
      "option_price": {
        "USD": "19.99"
      },
      "sku_extension": "12",
      "value": {
        "default": "12"
      }
    }
  ]
}
```

### product\_option\_values

Document representing an unfiltered list of product option values.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of product\_option\_value_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 3,
  "data": [
    {
      "default_product_option_value": true,
      "id": "value1",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S00",
      "sku_extension": "S00",
      "value": {
        "default": "None",
        "en": "None (en)"
      }
    },
    {
      "default_product_option_value": false,
      "id": "value2",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S01",
      "option_prices": [
        {
          "currency_mnemonic": "USD",
          "value": 9.99
        }
      ],
      "sku_extension": "S01",
      "value": {
        "default": "1-year",
        "en": "1-year (en)"
      }
    },
    {
      "default_product_option_value": false,
      "id": "value3",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S02",
      "option_prices": [
        {
          "currency_mnemonic": "USD",
          "value": 19.99
        }
      ],
      "sku_extension": "S02",
      "value": {
        "default": "2-year",
        "en": "2-year (en)"
      }
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 3
}
```

### product\_option\_value

Document representing a product option Value

*   `default_product_option_value` (_boolean_) Flag indicating if the product option value is the default value for the product option.
*   `id` (_string_) The id of the product option value.  
    Minimum length: 1.
*   `link` (_string_) The URL link to the product option value.
*   `option_prices` (_array of money_) The list of prices in the product option value.
*   `sku_extension` (_string_) The sku extension of the product option value.
*   `value` (_object (localized)_) The localized value of the product option.
    
    Additional properties: `string`.
    

_Example_

```
{
  "default_product_option_value": false,
  "id": "value3",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S02",
  "option_prices": [
    {
      "currency_mnemonic": "USD",
      "value": 19.99
    }
  ],
  "sku_extension": "S02",
  "value": {
    "default": "2-year",
    "en": "2-year (en)"
  }
}
```

### variation\_attributes

Document representing an unfiltered list of variation attributes.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of variation\_attribute_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 3,
  "data": [
    {
      "id": "fabric",
      "name": {
        "default": "Fabric"
      },
      "values": [
        {
          "name": {
            "default": "Leather"
          },
          "value": "leather"
        },
        {
          "name": {
            "default": "Linen"
          },
          "value": "linen"
        },
        {
          "name": {
            "default": "Plastic"
          },
          "value": "plastic"
        },
        {
          "name": {
            "default": "Metal"
          },
          "value": "metal"
        }
      ]
    },
    {
      "id": "color",
      "name": {
        "default": "Color"
      },
      "values": [
        {
          "name": {
            "default": "Red"
          },
          "value": "red"
        },
        {
          "name": {
            "default": "Blue"
          },
          "value": "blue"
        },
        {
          "name": {
            "default": "Black"
          },
          "value": "black"
        }
      ]
    },
    {
      "id": "size",
      "name": {
        "default": "Size"
      },
      "values": [
        {
          "description": {
            "default": "Small"
          },
          "name": {
            "default": "Small"
          },
          "value": "S"
        },
        {
          "description": {
            "default": "Medium"
          },
          "name": {
            "default": "Medium"
          },
          "value": "M"
        },
        {
          "description": {
            "default": "Large"
          },
          "name": {
            "default": "Large"
          },
          "value": "L"
        }
      ]
    }
  ],
  "start": 0,
  "total": 3
}
```

### variation\_attribute\_values

Document representing an unfiltered list of variation attribute values.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of variation\_attribute\_value_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 3,
  "data": [
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/master_product_1/variation_attributes/color/values/red",
      "value": "red"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/master_product_1/variation_attributes/color/values/blue",
      "value": "blue"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/master_product_1/variation_attributes/color/values/black",
      "value": "black"
    }
  ],
  "select": "(*,data.(value,link))",
  "start": 0,
  "total": 3
}
```

### variation\_attribute\_value

Document representing a variation attribute value.

*   `description` (_object (localized)_) The localized description of the variation value.
    
    Additional properties: `string`.
    
*   `image` (_media\_file_) The first product image for the configured viewtype and this variation value.
*   `image_swatch` (_media\_file_) The first product image for the configured viewtype and this variation value. (typically the swatch image)
*   `link` (_string_)
*   `name` (_object (localized)_) The localized display name of the variation value.
    
    Additional properties: `string`.
    
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.
*   `position` (_number (double)_) The position of the value among all values of a variation attribute.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1.

_Example_

```
{
  "name": {
    "default": "Leather"
  },
  "value": "leather"
}
```

### variation\_attribute

Document representing a variation attribute.

*   `attribute_definition_id` (_string_, required) The id of the requested attribute definition.
*   `attribute_definition_name` (_object (localized)_) The localized display name of the variation attribute definition.
    
    Additional properties: `string`.
    
*   `default_value` (_string_) default variation attribute value
*   `id` (_string_) The id of the variation attribute.  
    Minimum length: 1.
*   `link` (_string_) URL that is used to get this instance
*   `name` (_object (localized)_) The localized display name of the variation attribute.
    
    Additional properties: `string`.
    
*   `shared` (_boolean_) Returns the value of attribute 'shared' if attribute is local or shared
*   `slicing` (_boolean_) Returns the value of attribute 'slicing'.
*   `values` (_array of variation\_attribute\_value_) The sorted array of variation values. This array can be empty.
*   `variation_attribute_type` (_string_) variation attribute type  
    Allowed values: `string`, `int`, `unknown`.

_Example_

```
{
  "id": "fabric",
  "name": {
    "default": "Fabric"
  },
  "values": [
    {
      "name": {
        "default": "Leather"
      },
      "value": "leather"
    },
    {
      "name": {
        "default": "Linen"
      },
      "value": "linen"
    },
    {
      "name": {
        "default": "Plastic"
      },
      "value": "plastic"
    },
    {
      "name": {
        "default": "Metal"
      },
      "value": "metal"
    }
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### site

Document representing a site.

*   `cartridges` (_string_) The cartridge Path of the site
*   `creation_date` (_string (date-time)_)
*   `customer_list_link` (_customer\_list\_link_) The link to the customer list.
*   `description` (_object (localized)_) The description of this site.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name entered by the user.
    
    Additional properties: `string`.
    
*   `id` (_string_, required) The id of this site.  
    Minimum length: 1.
*   `in_deletion` (_boolean_) The deletion status of this site, true if in deletion
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link directly to the site
*   `storefront_status` (_string_)  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`.

_Example_

```
{
  "customer_list_link": {
    "customer_list_id": "SiteGenesis",
    "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
  },
  "description": {
    "default": "Prototypical site used for starting point"
  },
  "display_name": {
    "default": "Site Genesis"
  },
  "id": "SiteGenesis",
  "in_deletion": false,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
  "storefront_status": "online"
}
```

### path\_record

Document representing most basic info (id and name) of a category or catalog.

*   `id` (_string_) The id of the category path.
*   `name` (_object (localized)_) The name of the category path.
    
    Additional properties: `string`.
    

### sorting\_rule

Document representing a product sorting rule

*   `creation_date` (_string (date-time)_)
*   `description` (_string_) The description of the product sorting rule.  
    Maximum length: 4000.
*   `id` (_string_) the id of product sorting rule.
*   `last_modified` (_string (date-time)_)
*   `product_sorting_rule_steps` (_array of sorting\_rule\_step_) the steps involved in sorting by this rule.
*   `rule_context` (_string_) The context of the rule, either site or global
*   `site` (_string_)

_Example_

```
{
  "creation_date": "21.2-03-11T20:04:25.000Z",
  "id": "my-sorting-rule",
  "product_sorting_rule_steps": [
    {
      "attribute_id": "ID",
      "direction": "asc",
      "is_system": true,
      "position": 0,
      "text_relevance_included": false,
      "type_id": "product-attribute"
    }
  ],
  "rule-context": "site",
  "site": "SiteGenesis"
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### product

Document representing a product

*   `assigned_categories` (_array of catalog\_category\_id_) The catalog categories that the product is assigned to
*   `ats` (_number (double)_) The ATS(Available To Sell) inventory value of the product. This is a calculated value.
*   `brand` (_string_) The brand of the product.
*   `bundled_products` (_array of product_) The array of bundled products which the product includes.
*   `classification_category` (_catalog\_category\_id_) The classification category (default category) of the product
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `default_variant_id` (_string_) The ID of the product's default variant.
*   `ean` (_string_) The European Article Number of the product.
*   `id` (_string_) The ID (SKU) of the product.  
    Minimum length: 1. Maximum length: 100.
*   `image` (_media\_file_) The image(s) assigned to the product.
*   `image_groups` (_array of image\_group_) The array of product image groups.
*   `in_stock` (_boolean_) The flag that indicates if the product is in stock, or not. This is a calculated value.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A link to the product.
*   `localized_tax_class_id` (_object (localized)_)
    
    Additional properties: `string`.
    
*   `long_description` (_object (localized)_) The localized long description of the product.
    
    Additional properties: `markup_text`.
    
*   `manufacturer_name` (_string_) The name of the product's manufacturer.
*   `manufacturer_sku` (_string_) The SKU of the product's manufacturer.
*   `master` (_master_) The master of the product. This is applicable for product types "variation\_group" and "variant" only.
*   `name` (_object (localized)_) The localized name of the product.
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The flag that indicates if the product is online, or not. This is a calculated value.
*   `online_flag` (_object (site-specific)_) The site specific online status of the product.
    
    Additional properties: `boolean`.
    
*   `owning_catalog_id` (_string_) The ID of the catalog that owns the product.
*   `owning_catalog_name` (_object (localized)_) The localized name of the catalog that owns the product.
    
    Additional properties: `string`.
    
*   `page_description` (_object (localized)_) The localized page description of the product.
    
    Additional properties: `string`.
    
*   `page_keywords` (_object (localized)_) The localized page keywords of the product.
    
    Additional properties: `string`.
    
*   `page_title` (_object (localized)_) The localized page title of the product.
    
    Additional properties: `string`.
    
*   `price` (_number (double)_) The price of the product.
*   `price_currency` (_string_) The currency code for product's price.
*   `price_per_unit` (_number (double)_) The price per unit of the product
*   `primary_categories` (_array of catalog\_category\_id_) The catalog categories that are primary for the product
*   `primary_category_id` (_string_) The id of the products primary category.
*   `product_bundles` (_array of product_) The array of product bundles which the product belongs to.
*   `product_options` (_array of product\_option_) The array of product options. This is applicable for products of type "option".
*   `product_sets` (_array of product_) The array of product sets which the product belongs to.
*   `searchable` (_object (site-specific)_) The site specific searchable status of the product.
    
    Additional properties: `boolean`.
    
*   `set_products` (_array of product_) The array of set products which the product includes.
*   `short_description` (_object (localized)_) The localized short description of the product.
    
    Additional properties: `markup_text`.
    
*   `tax_class_id` (_string_) The catalog categories that the product is assigned to
*   `type` (_product\_type_) The type of the product. It can have one or more of the values "item", "master", "variation\_group", "variant", "bundle", and "set".
*   `unit` (_string_) The sales unit of the product.
*   `unit_measure` (_string_) The unitMeasure of the product.
*   `unit_quantity` (_number (double)_) The unitQuantity of the product.
*   `upc` (_string_) The Universal Product Code of the product.
*   `valid_from` (_object (site-specific)_) The time when product is valid from.
    
    Additional properties: `string (date-time)`.
    
*   `valid_to` (_object (site-specific)_) The time when product is valid to.
    
    Additional properties: `string (date-time)`.
    
*   `variants` (_array of variant_) The array of variants of the product. This is applicable for product types "master" and "variation\_group" only.
*   `variation_attributes` (_array of variation\_attribute_) The sorted array of variation attributes assigned to the product. This is applicable for product types "master", "variation\_group" and "variant" only.
*   `variation_groups` (_array of variation\_group_) The array of variation groups in the product. This is applicable for product type "master" only.
*   `variation_values` (_object_)
    
    The variation values selected for the product in variation attribute id and value pairs. This is applicable for product types "variant" and "variation\_group" only.
    
    ```
         Only for type variant and variation group.
    ```
    
    Additional properties: `string`.
    

_Example_

```
{
  "ats": 500,
  "brand": "Brand",
  "ean": "EAN",
  "id": "my-product",
  "in_stock": true,
  "link": "https://example.com/s/-/dw/data/{version}/products/my-product",
  "long_description": {
    "default": "Long Description"
  },
  "manufacturer_name": "Manufacturer",
  "manufacturer_sku": "Manufacturer ID",
  "name": {
    "default": "My Product"
  },
  "online": true,
  "online_flag": {
    "default": true
  },
  "owning_catalog_id": "my-catalog",
  "owning_catalog_name": {
    "default": "My Catalog"
  },
  "page_description": {
    "default": "Page description"
  },
  "page_keywords": {
    "default": "Page Keyword"
  },
  "page_title": {
    "default": "Page title"
  },
  "price": 100,
  "price_currency": "USD",
  "price_per_unit": 100,
  "searchable": {
    "default": true
  },
  "short_description": {
    "default": "Short Description"
  },
  "type": {
    "bundle": true,
    "bundled": true,
    "part_of_product_set": true
  },
  "unit": "bnd",
  "unit_measure": "each",
  "unit_quantity": 1,
  "upc": "UPC"
}
```

### media\_file

*   `abs_url` (_string_) The absolute URL with request protocol (read only)
*   `alt` (_object (localized)_) The alternative image text
    
    Additional properties: `string`.
    
*   `dis_base_url` (_string_) The DIS base URL only for product images
*   `path` (_string_) The raw media file path (only this needs to be provided in update request)
*   `title` (_object (localized)_) The image title
    
    Additional properties: `string`.
    

_Example_

```
{
  "path": "option.jpg"
}
```

### money

*   `currency_mnemonic` (_string_) The mnemonic for the money.
*   `value` (_number (double)_) The value for the money.

_Example_

```
{
  "currency_mnemonic": "USD",
  "value": 100
}
```

### customer\_list\_link

Document representing a link to a customer list.

*   `customer_list_id` (_string_) The customerlist id.
*   `link` (_string_) The target of the link.
*   `title` (_object (localized)_) The link title.
    
    Additional properties: `string`.
    

_Example_

```
{
  "customer_list_id": "SiteGenesis",
  "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
}
```

### sorting\_rule\_step

Document representing a product sorting rule step

*   `attribute_id` (_string_) the id for sorting attribute.
*   `direction` (_string_) the direction of the sorting attribute  
    Allowed values: `asc`, `desc`.
*   `is_system` (_boolean_) whether or not the attribute is a system attribute.
*   `position` (_integer (int32)_) the position of product sorting rule step.
*   `text_relevance_included` (_boolean_) The text relevance included.
*   `type_id` (_string_) the sorting type for sorting attribute.

_Example_

```
{
  "attribute_id": "ID",
  "direction": "asc",
  "is_system": true,
  "position": 0,
  "text_relevance_included": false,
  "type_id": "product-attribute"
}
```

### catalog\_category\_id

Document representing a catalog category id.

*   `catalog_id` (_string_) The id of the catalog that owns the category.  
    Minimum length: 1. Maximum length: 256.
*   `category_id` (_string_) The id of the category.  
    Minimum length: 1. Maximum length: 256.

### image\_group

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of media\_file_) The images of the image group.
*   `variation_attributes` (_array of variation\_attribute_) Returns a list of variation attributes applying to this image group.
*   `view_type` (_string_) The image view type.

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### master

Document representing a variation master.

*   `link` (_string_) The URL addressing the master product.
*   `master_id` (_string_, required) The id (SKU) of the master product.  
    Minimum length: 1. Maximum length: 100.
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.
*   `price` (_number (double)_) The minimum sales price of the related variants.
*   `price_max` (_number (double)_) The maximum sales of related variants.
*   `price_per_unit` (_number (double)_) The minimum sales price per unit of the related variants.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of the related variants.
*   `prices` (_object_)
    
    Additional properties: `number (double)`.
    

### product\_type

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.
*   `bundled` (_boolean_) A flag indicating whether the product is bundled.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.
*   `master` (_boolean_) A flag indicating whether the product is a master.
*   `option` (_boolean_) A flag indicating whether the product is an option.
*   `part_of_product_set` (_boolean_) A flag indicating whether the product is part of product set.
*   `part_of_retail_set` (_boolean_) A flag indicating whether the product is part of retail set.
*   `retail_set` (_boolean_) A flag indicating whether the product is a retail set.
*   `set` (_boolean_) A flag indicating whether the product is a set.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.
*   `variation_group` (_boolean_) A flag indicating whether the product is a variation group.

_Example_

```
{
  "bundled": true,
  "master": true,
  "part_of_product_set": true
}
```

### variant

Document representing a product variation.

*   `ats` (_number (double)_) Inventory "Available to Sell" of the product.
*   `default_product_variation` (_boolean_)
*   `image` (_media\_file_) URL to the preview image.
*   `in_stock` (_boolean_) `true` if the product is in stock, or `false` if not.
*   `link` (_string_) The URL addressing the product.
*   `online` (_boolean_) If the product is currently online. `true` if online `false` if not
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.
*   `price` (_number (double)_) The sales price of the variant.
*   `price_currency` (_string_) Currency code for the price of the product.
*   `price_per_unit` (_number (double)_) The sales price of the variant.
*   `product_id` (_string_, required) The id (SKU) of the variant.  
    Minimum length: 1. Maximum length: 100.
*   `searchable` (_object (site-specific)_)
    
    Additional properties: `boolean`.
    
*   `variation_attributes` (_array of variation\_attribute_) variation attributes
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "https://ocapi-mon.example.com/s/-/dw/data/{version}/products/dress-spring-red",
  "product_id": "dress-spring-red",
  "variation_values": {
    "color": "red"
  }
}
```

### variation\_group

Document representing a variation group.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.
*   `price` (_number (double)_) The sales price of the variation group.
*   `price_per_unit` (_number (double)_) The sales price per unit of the variation group.
*   `product_id` (_string_) The id (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "https://example.com/s/-/dw/data/{version}/products/my-product-5",
  "product_id": "my-product-5",
  "variation_values": {
    "color": "red"
  }
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=59f90b1f29220e7409d67483772dd64f0b11d52a01a51eff99958325da54c168 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-category-search.md -->

Data Category Search (deprecated)

# Data Category Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Categories

`POST /category_search`

Operation ID: `Search Categories`. Tags: category\_search. Security: oauth2\_application.

Searches for catalog categories anywhere they appear.

By default, the server also returns the first level of subcategories, but you can specify another level by setting the levels parameter. Please note, using a large value for levels may cause performance issues in case of a large and deep category tree.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   name - String
    
*   description - String
    
*   creation\_date - DateTime
    
*   online - Boolean
    
*   catalog\_id - String
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   name - String
    
*   description - String
    
*   creation\_date - DateTime
    
*   online - Boolean
    
*   position - Double
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `levels` (query, integer (int32))  
    Minimum: 0.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### category\_search\_result

Document representing a catalog search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of category_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "data": [
    {
      "categories": [
        {
          "creation_date": "2015-11-30T18:48:37.333Z",
          "description": {
            "default": "sub-category 1 for main catalog"
          },
          "id": "sub-category-1",
          "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/sub-category-1",
          "name": {
            "default": "Sub-category 1"
          },
          "online": true,
          "parent_category_id": "root",
          "paths": [
            {
              "id": "sub-category-1",
              "name": {
                "default": "Sub-category 1"
              }
            }
          ],
          "position": 1,
          "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
        }
      ],
      "creation_date": "2015-11-29T18:48:37.333Z",
      "description": {
        "default": "root category for main catalog"
      },
      "id": "root",
      "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20image",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/root",
      "name": {
        "default": "Root Category"
      },
      "online": true,
      "paths": [
        {
          "id": "root",
          "name": {
            "default": "root"
          }
        }
      ],
      "position": 1,
      "sorting_rules": [
        {
          "creation_date": "2015-11-19T20:46:37.000Z",
          "description": "Sorts by price ascending",
          "id": "price-low-to-high",
          "product_sorting_rule_steps": [
            {
              "direction": "Ascending",
              "is_system": false,
              "position": 0,
              "text_relevance_included": false,
              "type_id": "price"
            }
          ],
          "site": "main-site"
        }
      ],
      "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20thumbnail"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 1
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### category

Document representing a category.

*   `catalog_id` (_string_) The id of the catalog that contains it.
*   `categories` (_array of category_) The array of sub categories for the category.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_object (localized)_) The localized description of the category.
    
    Additional properties: `string`.
    
*   `id` (_string_) The id of the category.  
    Minimum length: 1. Maximum length: 256.
*   `image` (_string_) The name of the category image. The URL to the image is computed.  
    Minimum length: 1. Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The URL to get the category. This is a computed attribute and cannot be modified.
*   `name` (_object (localized)_) The localized name of the category.
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The online status of the category determines if it is visible in the storefront. Defaults to false if not specified on create.
*   `page_description` (_object (localized)_) The localized page description of the category.
    
    Additional properties: `string`.
    
*   `page_keywords` (_object (localized)_) The localized page keywords for the category.
    
    Additional properties: `string`.
    
*   `page_title` (_object (localized)_) The localized page title of the category.
    
    Additional properties: `string`.
    
*   `parent_category_id` (_string_) The id of the parent category. Defaults to root if not specified on create.  
    Minimum length: 1. Maximum length: 256.
*   `paths` (_array of path\_record_)
*   `position` (_number (double)_) The position of the category determines the display order in the storefront.
*   `sorting_rules` (_array of sorting\_rule_)
*   `thumbnail` (_string_) The name of the category thumbnail. The URL to the thumbnail is computed.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "categories": [
    {
      "creation_date": "2015-11-30T18:48:37.333Z",
      "description": {
        "default": "sub-category 1 for main catalog"
      },
      "id": "sub-category-1",
      "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/sub-category-1",
      "name": {
        "default": "Sub-category 1"
      },
      "online": true,
      "parent_category_id": "root",
      "paths": [
        {
          "id": "main-catalog",
          "name": {
            "default": "Main Catalog"
          }
        },
        {
          "id": "root",
          "name": {
            "default": "root category"
          }
        },
        {
          "id": "sub-category-1",
          "name": {
            "default": "Sub-category 1"
          }
        }
      ],
      "position": 1,
      "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
    },
    {
      "creation_date": "2015-12-02T18:48:37.333Z",
      "description": {
        "default": "sub-category 2 for main catalog"
      },
      "id": "sub-category-2",
      "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20image",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/sub-category-2",
      "name": {
        "default": "Sub-category 2"
      },
      "online": true,
      "parent_category_id": "root",
      "paths": [
        {
          "id": "main-catalog",
          "name": {
            "default": "Main Catalog"
          }
        },
        {
          "id": "root",
          "name": {
            "default": "root category"
          }
        },
        {
          "id": "sub-category-2",
          "name": {
            "default": "Sub-category 2"
          }
        }
      ],
      "position": 2,
      "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201.1%20thumbnail"
    }
  ],
  "creation_date": "2015-11-29T18:48:37.333Z",
  "description": {
    "default": "root category for main catalog"
  },
  "id": "root",
  "image": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20image",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/main-catalog/categories/root",
  "name": {
    "default": "Root Category"
  },
  "online": true,
  "paths": [
    {
      "id": "main-catalog",
      "name": {
        "default": "Main Catalog"
      }
    },
    {
      "id": "root",
      "name": {
        "default": "root"
      }
    }
  ],
  "position": 1,
  "sorting_rules": [
    {
      "creation_date": "2015-11-19T20:46:37.000Z",
      "description": "Sorts by price ascending",
      "id": "price-low-to-high",
      "product_sorting_rule_steps": [
        {
          "direction": "Ascending",
          "is_system": false,
          "position": 0,
          "text_relevance_included": false,
          "type_id": "price"
        }
      ],
      "site": "main-site"
    },
    {
      "creation_date": "2015-11-19T20:46:37.000Z",
      "description": "Sorts by price ascending",
      "id": "price-low-to-high",
      "product_sorting_rule_steps": [
        {
          "direction": "Ascending",
          "is_system": false,
          "position": 0,
          "text_relevance_included": false,
          "type_id": "price"
        }
      ],
      "site": "main-site"
    }
  ],
  "thumbnail": "https://example.com/on/demandware.static/-/Sites-main-catalog/default/v1447965267239/category%201%20thumbnail"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### path\_record

Document representing most basic info (id and name) of a category or catalog.

*   `id` (_string_) The id of the category path.
*   `name` (_object (localized)_) The name of the category path.
    
    Additional properties: `string`.
    

### sorting\_rule

Document representing a product sorting rule

*   `creation_date` (_string (date-time)_)
*   `description` (_string_) The description of the product sorting rule.  
    Maximum length: 4000.
*   `id` (_string_) the id of product sorting rule.
*   `last_modified` (_string (date-time)_)
*   `product_sorting_rule_steps` (_array of sorting\_rule\_step_) the steps involved in sorting by this rule.
*   `rule_context` (_string_) The context of the rule, either site or global
*   `site` (_string_)

_Example_

```
{
  "creation_date": "21.2-03-11T20:04:25.000Z",
  "id": "my-sorting-rule",
  "product_sorting_rule_steps": [
    {
      "attribute_id": "ID",
      "direction": "asc",
      "is_system": true,
      "position": 0,
      "text_relevance_included": false,
      "type_id": "product-attribute"
    }
  ],
  "rule-context": "site",
  "site": "SiteGenesis"
}
```

### sorting\_rule\_step

Document representing a product sorting rule step

*   `attribute_id` (_string_) the id for sorting attribute.
*   `direction` (_string_) the direction of the sorting attribute  
    Allowed values: `asc`, `desc`.
*   `is_system` (_boolean_) whether or not the attribute is a system attribute.
*   `position` (_integer (int32)_) the position of product sorting rule step.
*   `text_relevance_included` (_boolean_) The text relevance included.
*   `type_id` (_string_) the sorting type for sorting attribute.

_Example_

```
{
  "attribute_id": "ID",
  "direction": "asc",
  "is_system": true,
  "position": 0,
  "text_relevance_included": false,
  "type_id": "product-attribute"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=7e7b3b5480145d7e498ec2b58572413dd217345b84a36f6353865ebb692b4334 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-code-versions.md -->

Data Code Versions (deprecated)

# Data Code Versions (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get all code versions

`GET /code_versions`

Operation ID: `Get all code versions`. Tags: code\_versions. Security: oauth2\_application.

Read all existing code versions.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `code_version_result`.
    

### GET Get a code version

`GET /code_versions/{code_version_id}`

Operation ID: `Get a code version`. Tags: code\_versions. Security: oauth2\_application.

Read a code version.

This endpoint may return the following faults:

*   404 - CodeVersionIdNotFoundException - Indicates that a code version with the given id was not found.

#### Parameters

*   `code_version_id` (path, string, required) The id of the code version.  
    Minimum length: 1.
*   `expand` (query, array of string) The expand parameter. Allowed value (size).

#### Responses

*   **404** `CodeVersionIdNotFoundException` - Indicates that a code version with the given id was not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `code_version`.
    

### PUT Create code version

`PUT /code_versions/{code_version_id}`

Operation ID: `Create code version`. Tags: code\_versions. Security: oauth2\_application.

Create a new code version.

This endpoint may return the following faults:

*   409 - CodeVersionIdAlreadyExistsException - Indicates that a code version with the given id already exists.

#### Parameters

*   `code_version_id` (path, string, required) The id of the code version.  
    Minimum length: 1.

#### Responses

*   **409** `CodeVersionIdAlreadyExistsException` - Indicates that a code version with the given id already exists.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `code_version`.
    

### DELETE Delete a code version

`DELETE /code_versions/{code_version_id}`

Operation ID: `Delete a code version`. Tags: code\_versions. Security: oauth2\_application.

Delete a code version.

This endpoint may return the following faults:

*   400 - CodeVersionModificationException - Indicates that a code version with the given id can't be deleted (because it is active).
*   404 - CodeVersionIdNotFoundException - Indicates that a code version with the given id was not found.

#### Parameters

*   `code_version_id` (path, string, required) The id of the code version.  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `CodeVersionModificationException` - Indicates that a code version with the given id can't be deleted (because it is active).
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CodeVersionIdNotFoundException` - Indicates that a code version with the given id was not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update a code version

`PATCH /code_versions/{code_version_id}`

Operation ID: `Update a code version`. Tags: code\_versions. Security: oauth2\_application.

Update an existing code version.

*   Only an inactive code version can be updated.
    
*   Only the active flag and the id can be changed. The active flag can therefore only set to "true".
    
*   To set the active flag to "false" will not work.
    

This endpoint may return the following faults:

*   400 - CodeVersionModificationException - Indicates that a code version with the given id can't be updated (because it is active).
*   404 - CodeVersionIdNotFoundException - Indicates that a code version with the given id was not found.
*   409 - CodeVersionIdAlreadyExistsException - Indicates that a code version with the given id already exists.

#### Parameters

*   `code_version_id` (path, string, required) The id of the code version.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `code_version`.

#### Responses

*   **400** `CodeVersionModificationException` - Indicates that a code version with the given id can't be updated (because it is active).
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CodeVersionIdNotFoundException` - Indicates that a code version with the given id was not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `CodeVersionIdAlreadyExistsException` - Indicates that a code version with the given id already exists.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `code_version`.
    

## Schemas

### code\_version\_result

Result document containing an array of code versions.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of code\_version_) The array of code versions
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 1,
  "data": [
    {
      "activation_time": "2016-01-14T16:48:07Z",
      "active": true,
      "cartridges": "bc_gillian, test_bc_wapi, test_bc_wapi_deprecated",
      "compatibility_mode": "16.2",
      "id": "version1",
      "last_modification_time": "2016-01-14T16:48:07Z",
      "rollback": false,
      "total_size": "537 KB",
      "web_dav_url": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1"
    }
  ],
  "total": 1
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### code\_version

Document representing a code version

*   `activation_time` (_string (date-time)_) The code version activation time.
*   `active` (_boolean_) Use this method to determine, if this code version is currently active.
*   `cartridges` (_array of string_) A list containing the names of all cartridges participating in this code version.
*   `compatibility_mode` (_string_) The code version compatibility mode.
*   `id` (_string_) The code version id.
*   `last_modification_time` (_string (date-time)_) The last time, when the code version was changed.
*   `rollback` (_boolean_) Use this method to determine, if this code version is the current rollback version.
*   `total_size` (_integer (int64)_) Returns the total size of the file system content of this code version in bytes.
*   `web_dav_url` (_string_) Returns the HTTPS based WebDAV URL that can be used to access the code version resources.

_Example_

```
{
  "activation_time": "2016-01-14T16:48:07Z",
  "active": true,
  "cartridges": [
    "storefront",
    "storefront_richUI",
    "sitegenesis",
    "sitegenesis_richUI"
  ],
  "compatibility_mode": "16.2",
  "id": "version2",
  "last_modification_time": "2016-01-14T16:48:07Z",
  "rollback": false,
  "total_size": 537345,
  "web_dav_url": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version2"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=1ba0f82fe9331d67649df49562c7108b41697d86fcc87efc6868d14684009ff4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-coupon-redemption-search.md -->

Data Coupon Redemption Search (deprecated)

# Data Coupon Redemption Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Coupon Redemptions

`POST /sites/{site_id}/coupon_redemption_search`

Operation ID: `Search Coupon Redemptions`. Tags: sites. Security: oauth2\_application.

Searches for coupon redemptions.

The Coupon Redemption Search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   code - String
    
*   coupon\_id - String
    
*   customer\_email - String
    
*   order\_no - String
    

Note that only searchable attributes can be used in sorting.

If the role to which the user belongs does not have View\_Coupon\_Codes permission, then the coupon codes returned will be masked.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `coupon_redemption_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### coupon\_redemption\_search\_result

The result of the coupon redemption search

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of coupon\_redemption_) The hits from the search
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### coupon\_redemption

A redemption record returned from the coupon redemption resources

*   `code` (_string_) The coupon code that was redeemed
*   `coupon_id` (_string_) The coupon id that was redeemed
*   `creation_date` (_string (date-time)_)
*   `customer_email` (_string_) The customer email that was used to redeem it
*   `last_modified` (_string (date-time)_)
*   `order_no` (_string_) The order number where the redemption occurred
*   `view_order_url` (_string_) A URL able to access the order

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=18c80fe3e0775734551fa8ca0204fe5771536738b392881a6ac20ee3d9be01eb url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-coupon-search.md -->

Data Coupon Search (deprecated)

# Data Coupon Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Coupons

`POST /sites/{site_id}/coupon_search`

Operation ID: `Search Coupons`. Tags: sites. Security: oauth2\_application.

Searches for coupons.

The Coupon Search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   coupon\_id - String
    
*   description - String
    
*   type - one of {"single\_code", "multiple\_codes", "system\_codes"}
    
*   enabled - boolean
    

Note that only searchable attributes can be used in sorting. In case no sorting attribute is specified the result is sorted by coupon\_id.

The _stats_ expand value is required to return the following fields in the Coupon document:

*   exported\_code\_count
    
*   redemption\_count
    
*   total\_codes\_count
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `coupon_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### coupon\_search\_result

Document representing a coupon search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of coupon_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "coupon_id": "my-coupon1",
      "description": "system generated coupon code.",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/coupons/my-coupon1",
      "redemption_count": 5,
      "redemption_limits": {
        "limit_per_code": 1,
        "limit_per_customer": 0,
        "limit_per_time_frame": {
          "limit": 0,
          "redemption_time_frame": 0
        }
      },
      "system_codes_config": {
        "code_prefix": "xmas2014-",
        "max_number_of_codes": 100
      },
      "type": "system_codes"
    },
    {
      "coupon_id": "my-coupon2",
      "description": "single coupon code.",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/coupons/my-coupon2",
      "redemption_count": 0,
      "redemption_limits": {
        "limit_per_code": 3,
        "limit_per_customer": 3,
        "limit_per_time_frame": {
          "limit": 3,
          "redemption_time_frame": 7
        }
      },
      "single_code": "50OFF",
      "type": "single_code"
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### coupon

Document representing a coupon.

*   `case_insensitive` (_boolean_) `True` if a coupon is case insensitive; `false` otherwise. This attribute on the coupon can not be modified after the coupon has been created. If an attempt was made to modify this the system would return CouponUpdateForbiddenException
*   `coupon_id` (_string_, read-only) The id of the coupon.  
    Minimum length: 1. Maximum length: 256.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description of the coupon.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the coupon is enabled.
*   `exported_code_count` (_integer (int32)_) The number of coupon codes attached to the coupon that have been issued (request search only).
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A link to the coupon.
*   `multiple_codes_per_basket` (_boolean_) `True` if a coupon with multiple codes can have different codes used on the same basket or order. If the coupon type does not support this configuration, this will return `false`.
*   `redemption_count` (_integer (int32)_) The number of times the coupon has been redeemed (request search only).
*   `redemption_limits` (_redemption\_limits_) The redemption limit per coupon code.
*   `single_code` (_string_) Single coupon code, only valid for Single Code type  
    Minimum length: 1. Maximum length: 256.
*   `system_codes_config` (_coupon\_system\_code\_config_) The configuration of system coupon codes, including pre-fix and number of codes
*   `total_codes_count` (_integer (int32)_) The total number of coupon codes associated with this coupon
*   `type` (_string_, read-only) The type of the coupon code.  
    Allowed values: `single_code`, `multiple_codes`, `system_codes`.

_Example_

```
{
  "coupon_id": "my-coupon",
  "description": "sytem generated coupon code.",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/coupons/my-coupon",
  "redemption_count": 2,
  "redemption_limits": {
    "limit_per_code": 1,
    "limit_per_customer": 0,
    "limit_per_time_frame": {
      "limit": 0,
      "redemption_time_frame": 0
    }
  },
  "system_codes_config": {
    "code_prefix": "sys",
    "number_of_codes": 100
  },
  "type": "system_codes"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### redemption\_limits

Document representing a coupon.

*   `limit_per_code` (_integer (int32)_) The redemption limit per code  
    Minimum: 0.
*   `limit_per_customer` (_integer (int32)_) The redemption limit per customer  
    Minimum: 0.
*   `limit_per_time_frame` (_redemption\_limit\_per\_period_) The redemption limit per time frame

_Example_

```
{
  "limit_per_code": 1,
  "limit_per_customer": 0,
  "limit_per_time_frame": {
    "limit": 0,
    "redemption_time_frame": 0
  }
}
```

### coupon\_system\_code\_config

*   `code_prefix` (_string_) The code prefix for system-generated coupon codes.
*   `number_of_codes` (_integer (int32)_) The number of system coupon codes that can be issued.

### redemption\_limit\_per\_period

Document representing a coupon redemption limit.

*   `limit` (_integer (int32)_) The limit on the number of times a coupon can be redeemed for a specified redemption time period.  
    Minimum: 0.
*   `redemption_time_frame` (_integer (int32)_) The redemption time period.  
    Minimum: 0. Maximum: 999.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=d8e260174f60c0b8962436e4e2b61206b1bb67f96642518a0c015ec7791d03a5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-coupons.md -->

Data Coupons (deprecated)

# Data Coupons (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Coupons

`GET /sites/{site_id}/coupons`

Operation ID: `Get Coupons`. Tags: sites. Security: oauth2\_application.

Action to get all the coupons with no filtering.

The result is sorted by by coupon\_id ascending.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the codes from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the codes (default is 25).
*   `select` (query, string) The property selector.
*   `expand` (query, array of string)

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `coupons`.
    

### GET Get Coupon

`GET /sites/{site_id}/coupons/{coupon_id}`

Operation ID: `Get Coupon`. Tags: sites. Security: oauth2\_application.

Action to get coupon information.

The following fields are returned in the Coupon document when specifying the _stats_ expand:

*   exported\_code\_count
    
*   redemption\_count
    
*   total\_codes\_count
    

If the role to which the user belongs does not have View\_Coupon\_Codes permission, then the coupon codes returned will be masked.

This endpoint may return the following faults:

*   404 - CouponNotFoundException - Thrown in case the coupon does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the requested coupon.  
    Minimum length: 1.
*   `select` (query, string) The property selector.
*   `expand` (query, array of string) The expand parameter. A comma separated list with the allowed values ( _stats_ ).

#### Responses

*   **404** `CouponNotFoundException` - Thrown in case the coupon does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `coupon`.
    

### PUT Create Coupon

`PUT /sites/{site_id}/coupons/{coupon_id}`

Operation ID: `Create Coupon`. Tags: sites. Security: oauth2\_application.

Creates a coupon using the information provided. If a coupon exists with the same unique identifier, the coupon is replaced completely.

This endpoint may return the following faults:

*   400 - CouponCodeDuplicateException - Thrown if the code provided is in use by another coupon.
*   400 - CouponCreateSingleCodeException - Thrown if a single code coupon does not set the coupon code properly.
*   400 - CouponInvalidException - Thrown if the coupon passed in is not valid (the argument indicates the field that was invalid).
*   400 - IdConflictException - if the Id in request is not the same as the ID in document.
*   400 - SystemGeneratedCouponQuotaException - Thrown whenever a quota regarding system-generated coupons is violated
*   403 - SiteAccessForbiddenException - Thrown if the resource requires global instead of site-specific context.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the coupon to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `coupon`.

#### Responses

*   **400** `CouponCodeDuplicateException` - Thrown if the code provided is in use by another coupon. or `CouponCreateSingleCodeException` - Thrown if a single code coupon does not set the coupon code properly. or `CouponInvalidException` - Thrown if the coupon passed in is not valid (the argument indicates the field that was invalid). or `IdConflictException` - if the Id in request is not the same as the ID in document. or `SystemGeneratedCouponQuotaException` - Thrown whenever a quota regarding system-generated coupons is violated
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `SiteAccessForbiddenException` - Thrown if the resource requires global instead of site-specific context.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `coupon`.
    

### DELETE Delete Coupon

`DELETE /sites/{site_id}/coupons/{coupon_id}`

Operation ID: `Delete Coupon`. Tags: sites. Security: oauth2\_application.

Delete a coupon by id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) Id of the coupon to delete from the site.  
    Minimum length: 1.

#### Responses

*   **204**

### PATCH Update Coupon

`PATCH /sites/{site_id}/coupons/{coupon_id}`

Operation ID: `Update Coupon`. Tags: sites. Security: oauth2\_application.

Updates the coupon with the specified information.

This endpoint may return the following faults:

*   400 - CouponCodeDuplicateException - Thrown if the code provided is in use by another coupon.
*   400 - CouponUpdateReadOnlyException - Thrown if you try to update certain fields in a coupon after redeeming or exporting it.
*   400 - SystemGeneratedCouponQuotaException - Thrown whenever a quota regarding system-generated coupons is violated
*   403 - CouponLegacyUpdateForbiddenException - Thrown when trying to update a legacy coupon.
*   403 - CouponUpdateForbiddenException - Thrown when trying to update a broken coupon, that should be deleted and re-created.
*   404 - CouponNotFoundException - Thrown if the coupon does not exist matching the given id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the requested coupon.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `coupon`.

#### Responses

*   **400** `CouponCodeDuplicateException` - Thrown if the code provided is in use by another coupon. or `CouponUpdateReadOnlyException` - Thrown if you try to update certain fields in a coupon after redeeming or exporting it. or `SystemGeneratedCouponQuotaException` - Thrown whenever a quota regarding system-generated coupons is violated
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `CouponLegacyUpdateForbiddenException` - Thrown when trying to update a legacy coupon. or `CouponUpdateForbiddenException` - Thrown when trying to update a broken coupon, that should be deleted and re-created.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CouponNotFoundException` - Thrown if the coupon does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `coupon`.
    

### GET Get Campaigns

`GET /sites/{site_id}/coupons/{coupon_id}/campaigns`

Operation ID: `Get Campaigns`. Tags: sites. Security: oauth2\_application.

Get the campaigns that have a coupon assigned to them either directly or through promotions

This endpoint may return the following faults:

*   404 - CouponNotFoundException - Thrown if the coupon does not exist matching the given id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the coupon that is assigned to campaigns directly or through promotions.
*   `start` (query, integer (int32)) Optional start index for retrieving the campaigns (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving the campaigns (default is 25).
*   `select` (query, string)

#### Responses

*   **404** `CouponNotFoundException` - Thrown if the coupon does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `campaigns`.
    

### GET Get Promotions for Campaign

`GET /sites/{site_id}/coupons/{coupon_id}/campaigns/{campaign_id}/promotions`

Operation ID: `Get Promotions for Campaign`. Tags: sites. Security: oauth2\_application.

Get the promotions for a campaign that have a coupon assigned to them either directly or through campaigns.

This endpoint may return the following faults:

*   404 - CampaignNotFoundException - Thrown if the campaign does not exist matching the given id.
*   404 - CouponNotFoundException - Thrown if the coupon does not exist matching the given id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the coupon that is assigned to promotions directly or through campaigns.
*   `campaign_id` (path, string, required) The id of the campaign that we want to restrict the set of promotions for.
*   `start` (query, integer (int32)) Optional start index for retrieving the promotions (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving the promotions (default is 25).
*   `select` (query, string)

#### Responses

*   **404** `CampaignNotFoundException` - Thrown if the campaign does not exist matching the given id. or `CouponNotFoundException` - Thrown if the coupon does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotions`.
    

### GET Get Coupon Codes

`GET /sites/{site_id}/coupons/{coupon_id}/codes`

Operation ID: `Get Coupon Codes`. Tags: sites. Security: oauth2\_application.

Get the coupon codes for the given coupon.

If the role to which the user belongs does not have View\_Coupon\_Codes permission, then the coupon codes returned will be masked.

This endpoint may return the following faults:

*   404 - CouponNotFoundException - Thrown if the coupon does not exist matching the given id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the coupon from which to delete codes (must be a multiple code coupon).
*   `start` (query, integer (int32)) Optional start index for retrieving the codes from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the codes (default is 25).
*   `select` (query, string) Optional select clause for getting fields from the returned JSON document.

#### Responses

*   **404** `CouponNotFoundException` - Thrown if the coupon does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `coupon_codes`.
    

### POST Modify Multiple Codes

`POST /sites/{site_id}/coupons/{coupon_id}/multiple_codes`

Operation ID: `Modify Multiple Codes`. Tags: sites. Security: oauth2\_application.

Add or delete (modify) multiple codes to/from the supplied coupon.

This endpoint may return the following faults:

*   400 - CouponCodeCreateException - Thrown if the coupon code could not be created.
*   404 - CouponNotFoundException - Thrown if the coupon does not exist matching the given id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the coupon to modify codes (must be multiple code coupon).
*   `delete` (query, boolean) Optional parameter for specifying when to delete multiple codes.

#### Request body

Media type: `application/json, text/xml`. Schema: `coupon_multi_codes_request`.

#### Responses

*   **204**
*   **400** `CouponCodeCreateException` - Thrown if the coupon code could not be created.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CouponNotFoundException` - Thrown if the coupon does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get Promotions

`GET /sites/{site_id}/coupons/{coupon_id}/promotions`

Operation ID: `Get Promotions`. Tags: sites. Security: oauth2\_application.

Get the promotions that have a coupon assigned to them either directly or through campaigns.

This endpoint may return the following faults:

*   404 - CouponNotFoundException - Thrown if the coupon does not exist matching the given id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `coupon_id` (path, string, required) The id of the coupon that is assigned to promotions directly or through campaigns.
*   `start` (query, integer (int32)) Optional start index for retrieving the promotions (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving the promotions (default is 25).
*   `select` (query, string)

#### Responses

*   **404** `CouponNotFoundException` - Thrown if the coupon does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotions`.
    

## Schemas

### coupons

Document representing an unfiltered list of coupons.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of coupon_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### coupon

Document representing a coupon.

*   `case_insensitive` (_boolean_) `True` if a coupon is case insensitive; `false` otherwise. This attribute on the coupon can not be modified after the coupon has been created. If an attempt was made to modify this the system would return CouponUpdateForbiddenException
*   `coupon_id` (_string_, read-only) The id of the coupon.  
    Minimum length: 1. Maximum length: 256.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description of the coupon.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the coupon is enabled.
*   `exported_code_count` (_integer (int32)_) The number of coupon codes attached to the coupon that have been issued (request search only).
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A link to the coupon.
*   `multiple_codes_per_basket` (_boolean_) `True` if a coupon with multiple codes can have different codes used on the same basket or order. If the coupon type does not support this configuration, this will return `false`.
*   `redemption_count` (_integer (int32)_) The number of times the coupon has been redeemed (request search only).
*   `redemption_limits` (_redemption\_limits_) The redemption limit per coupon code.
*   `single_code` (_string_) Single coupon code, only valid for Single Code type  
    Minimum length: 1. Maximum length: 256.
*   `system_codes_config` (_coupon\_system\_code\_config_) The configuration of system coupon codes, including pre-fix and number of codes
*   `total_codes_count` (_integer (int32)_) The total number of coupon codes associated with this coupon
*   `type` (_string_, read-only) The type of the coupon code.  
    Allowed values: `single_code`, `multiple_codes`, `system_codes`.

_Example_

```
{
  "coupon_id": "my-coupon",
  "description": "sytem generated coupon code.",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/coupons/my-coupon",
  "redemption_count": 2,
  "redemption_limits": {
    "limit_per_code": 1,
    "limit_per_customer": 0,
    "limit_per_time_frame": {
      "limit": 0,
      "redemption_time_frame": 0
    }
  },
  "system_codes_config": {
    "code_prefix": "sys",
    "number_of_codes": 100
  },
  "type": "system_codes"
}
```

### campaigns

Document representing an unfiltered list of campaigns.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of campaign_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 3,
  "data": [
    {
      "campaign_id": "my-coupon-campaign1",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-coupon-campaign1"
    },
    {
      "campaign_id": "my-coupon-campaign2",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-coupon-campaign2"
    },
    {
      "campaign_id": "my-coupon-campaign3",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-coupon-campaign3"
    }
  ],
  "start": 0,
  "total": 3
}
```

### promotions

A set of promotions

*   `count` (_integer (int32)_)
*   `data` (_array of promotion_) The set of promotions
*   `expand` (_array of string_)
*   `next` (_string_)
*   `previous` (_string_)
*   `select` (_string_)
*   `start` (_integer (int32)_)  
    Minimum: 0.
*   `total` (_integer (int32)_)

_Example_

```
{
  "count": 1,
  "data": [
    {
      "id": "my-coupon-promotion1",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotions/my-coupon-promotion1"
    }
  ],
  "start": 0,
  "total": 1
}
```

### coupon\_codes

Document representing a set of coupon codes.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of coupon\_code_) The collection of coupon codes
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### coupon\_multi\_codes\_request

A request object to add and remove coupon codes from a document

*   `codes` (_array of string_, required) The list of coupon codes to add or delete

_Example_

```
{
  "codes": [
    "xyz",
    "pdq",
    "abc"
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### redemption\_limits

Document representing a coupon.

*   `limit_per_code` (_integer (int32)_) The redemption limit per code  
    Minimum: 0.
*   `limit_per_customer` (_integer (int32)_) The redemption limit per customer  
    Minimum: 0.
*   `limit_per_time_frame` (_redemption\_limit\_per\_period_) The redemption limit per time frame

_Example_

```
{
  "limit_per_code": 1,
  "limit_per_customer": 0,
  "limit_per_time_frame": {
    "limit": 0,
    "redemption_time_frame": 0
  }
}
```

### coupon\_system\_code\_config

*   `code_prefix` (_string_) The code prefix for system-generated coupon codes.
*   `number_of_codes` (_integer (int32)_) The number of system coupon codes that can be issued.

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### promotion

Document representing a promotion. Unless otherwise stated, attributes of this document are not supported when using the Open Commerce API to update multiple promotions at once.

*   `archived` (_boolean_) Determines whether or not this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `assignment_information` (_promotion\_assignment\_information_) Information about the assignments and assignment schedules of this promotion
*   `callout_msg` (_object (localized)_) The localized callout message of the promotion.
    
    Additional properties: `markup_text`.
    
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency_code` (_string_) The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.  
    Maximum length: 3.
*   `disable_globally_excluded` (_boolean_) Determines whether or not this promotion ignores the global product exclusions for promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `enabled` (_boolean_) Determines whether or not this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `exclusivity` (_string_) Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Allowed values: `no`, `class`, `global`.
*   `id` (_string_) The id for the promotion.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A URL that is used to get the details of this promotion.
*   `name` (_object (localized)_) The user supplied name of this promotion, which can be localized
    
    Additional properties: `string`.
    
*   `promotion_class` (_string_) The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, will be reset.  
    Allowed values: `product`, `shipping`, `order`.
*   `tags` (_array of tag_) Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags will be removed.

_Example_

```
{
  "enabled": true,
  "exclusivity": "class",
  "id": "my-promotion",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/my-promotion/my-promotion",
  "name": {
    "default": "My Promotion"
  },
  "promotion_class": "order"
}
```

### coupon\_code

A coupon code with accompanying stats for redemptions and issued.

*   `code` (_string_) The code used to redeem the coupon
*   `issued` (_boolean_) Flag indicating if the coupon code has been issued
*   `redemption_count` (_integer (int32)_) The count of the number of redemptions associated with the code

_Example_

```
{
  "code": "xmas2014-00001",
  "issued": true,
  "redemption_count": 1
}
```

### redemption\_limit\_per\_period

Document representing a coupon redemption limit.

*   `limit` (_integer (int32)_) The limit on the number of times a coupon can be redeemed for a specified redemption time period.  
    Minimum: 0.
*   `redemption_time_frame` (_integer (int32)_) The redemption time period.  
    Minimum: 0. Maximum: 999.

### promotion\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": true,
  "active_campaign_assignments": [
    {
      "campaign_id": "coupon-campaign",
      "coupons": [
        "limitPerCode-coupon",
        "multipleCodes-coupon",
        "longCode-coupon",
        "systemCodes-coupon",
        "limitPerTimePeriod-coupon",
        "disabled-coupon",
        "singleCode-coupon",
        "limitPerCustomer-coupon"
      ],
      "description": "Coupon Promotion",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/coupon-promotion/coupon-campaign",
      "promotion_id": "coupon-promotion",
      "rank": 10,
      "schedule": {}
    }
  ],
  "campaign_id": "coupon-campaign",
  "end_date": "2050-06-01T00:00:00.000Z",
  "schedule": {},
  "schedule_type": "campaign",
  "start_date": "2020-05-01T00:00:00.000Z"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### tag

Document representing a tag

*   `tag_id` (_string_) The id of the tag.

### promotion\_abtest\_group\_assignment

Document representing a promotionabtestgroupassignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `abtest_id` (_string_) The id for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `schedule` (_schedule_) The schedule informaiton for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment
*   `segment_id` (_string_) The id for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment

### promotion\_campaign\_assignment

Document representing a promotion campaign assignment.

*   `campaign` (_campaign_) The campaign
*   `campaign_id` (_string_) The id of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The sorted array of assigned coupon ids.
*   `coupons_based` (_boolean_) True if the assigned promotion is coupon based. When set to false, Coupons in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The sorted array of assigned customer groups.
*   `customer_groups_based` (_boolean_) True if the assigned promotion is customer group based. When set to false, Customer Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `description` (_string_) The description of the promotion campaign assignment.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) link for convenience
*   `promotion` (_promotion_) The promotion
*   `promotion_id` (_string_) The id of the Promotion.  
    Minimum length: 1. Maximum length: 256.
*   `rank` (_integer (int32)_) The rank of promotion campaign assignment
*   `required_qualifier` (_string_) A constant indicating that one or all qualifier conditions must be met in order for the promotion to apply for a given customer. Valid values are "any" and "all".  
    Allowed values: `any`, `all`.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `source_code_based` (_boolean_) True if the assigned promotion is source code group based. When set to false, Source Code Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `source_code_groups` (_array of string_) The sorted array of assigned source code groups.

_Example_

```
{
  "campaign": {
    "campaign_id": "coupon-campaign",
    "description": "A campaign for coupons.",
    "enabled": true
  },
  "campaign_id": "coupon-campaign",
  "coupons": [
    "order-promotion-coupon"
  ],
  "description": "Coupon Order Promotion",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotions/coupon-promotion-order/campaigns/coupon-campaign",
  "promotion_id": "coupon-promotion-order",
  "schedule": {
    "end_date": "2050-01-01T00:00:00.000Z",
    "start_date": "2000-01-01T00:00:00.000Z"
  }
}
```

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

<!-- document id=6fa464f5314c688d139587b1bf32326e65bb7c147cae290ff934a524f7ac6ece url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-custom-object-definitions.md -->

Data Custom Object Definitions (deprecated)

# Data Custom Object Definitions (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Attribute Definitions for Custom Object

`POST /custom_object_definitions/{object_type}/attribute_definition_search`

Operation ID: `Search Attribute Definitions for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Searches the attribute definitions of the specified custom object type.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. These are the list of searchable attributes with their corresponding buckets:

Main:

*   id - String
    
*   display\_name\* - Localized String
    
*   description\* - Localized String
    
*   key - boolean
    
*   mandatory - boolean
    
*   searchable - boolean
    
*   system - boolean
    
*   visible - boolean
    

Definition version:

*   localizable - boolean
    
*   site\_specific - boolean
    
*   value\_type - one of {string, int, double, text, html, date, image, boolean, money, quantity, datetime, email, password, set\_of\_string, set\_of\_int, set\_of\_double, enum\_of\_string, enum\_of\_int, unknown}
    

Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining localizable and description above, only a conjunction is allowed (AND), whereas display\_name and description can be joined using a disjunction because they are in the same bucket. If an attribute is used in a disjunction (OR) that violates this rule, an exception will be thrown.

Additionally, attribute definitions can also be searched by attribute group.

*   group - String
    

These attributes are not searchable or sortable for built in system attributes. They work normally for non system attributes.

Note that only searchable attributes can be used in sorting.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Indicates the query is ill-formed.
*   404 - ObjectTypeNotFoundException - Indicates that the object type cannot be found.

#### Parameters

*   `object_type` (path, string, required) The type of object

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Indicates the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Indicates that the object type cannot be found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition_search_result`.
    

### GET Get Attribute Definitions for Custom Object

`GET /custom_object_definitions/{object_type}/attribute_definitions`

Operation ID: `Get Attribute Definitions for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Action to get all the attribute definitions with no filtering.

This endpoint may return the following faults:

*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required)
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definitions`.
    

### GET Get Attribute Definition for Custom Object

`GET /custom_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Get Attribute Definition for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Action to get attribute definition information.

This endpoint may return the following faults:

*   500 - AttributeDefinitionNotFoundException - Thrown in case the attribute definition does not exist matching the given id
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) The object type id that contains these definitions
*   `id` (path, string, required) The id of the requested attribute definition.  
    Minimum length: 1.
*   `expand` (query, array of string) The expand "value" is available to retrieve value definitions of the attribute definition.
*   `select` (query, string) The selector for the get. If not passed, then the defaultSelector will be used instead.

#### Responses

*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Thrown in case the attribute definition does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.
    

### PUT Create Attribute Definition for Custom Object

`PUT /custom_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Create Attribute Definition for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Creates a attribute definition using the information provided.

This endpoint may return the following faults:

*   400 - AttributeDefinitionCreateException - if the attribute definition could not be created.
*   400 - AttributeDefinitionKeyReadOnlyException - Thrown when trying to create a key attribute of a custom object
*   400 - AttributeDefinitionLocalizableNotAllowedException - if trying to create a localizable attribute with a non-localizable type
*   400 - IdConflictException - if the Id in request is not the same as the ID in document.
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) The metadata object that contains these definitions
*   `id` (path, string, required) The id of the attribute definition to create.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.

#### Responses

*   **400** `AttributeDefinitionCreateException` - if the attribute definition could not be created. or `AttributeDefinitionKeyReadOnlyException` - Thrown when trying to create a key attribute of a custom object or `AttributeDefinitionLocalizableNotAllowedException` - if trying to create a localizable attribute with a non-localizable type or `IdConflictException` - if the Id in request is not the same as the ID in document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.
    

### DELETE Delete Attribute Definition for Custom Object

`DELETE /custom_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Delete Attribute Definition for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Deletes the attribute definition by ID

This endpoint may return the following faults:

*   400 - AttributeDefinitionKeyReadOnlyException - Thrown when trying to delete a key attribute of custom object
*   400 - AttributeDefinitionReadOnlyException - Thrown when trying to delete a internal attribute of custom object
*   500 - AttributeDefinitionNotFoundException - Thrown in case the attribute definition does not exist matching the given id
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) The metadata object that contains these definitions
*   `id` (path, string, required) Attribute definition id to remove  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `AttributeDefinitionKeyReadOnlyException` - Thrown when trying to delete a key attribute of custom object or `AttributeDefinitionReadOnlyException` - Thrown when trying to delete a internal attribute of custom object
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Thrown in case the attribute definition does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Attribute Definition for Custom Object

`PATCH /custom_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Update Attribute Definition for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Updates the attribute definition with the specified information.

This endpoint may return the following faults:

*   400 - AttributeDefinitionKeyReadOnlyException - Thrown when trying to modify a key attribute of custom object
*   400 - AttributeDefinitionPropertyReadOnlyException - Thrown in case a read only system attribute it tried to be changed, which is not allowed.
*   500 - AttributeDefinitionNotFoundException - Thrown in case the attribute definition does not exist matching the given id
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) The object type id that contains these definitions
*   `id` (path, string, required) The id of the requested attribute definition.  
    Minimum length: 1.
*   `If-Match` (header, string)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.

#### Responses

*   **400** `AttributeDefinitionKeyReadOnlyException` - Thrown when trying to modify a key attribute of custom object or `AttributeDefinitionPropertyReadOnlyException` - Thrown in case a read only system attribute it tried to be changed, which is not allowed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Thrown in case the attribute definition does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.
    

### POST Search Attribute Groups for Custom Object

`POST /custom_object_definitions/{object_type}/attribute_group_search`

Operation ID: `Search Attribute Groups for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Searches for attribute groups.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   position - Double
    
*   internal - Boolean
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   position - Double
    
*   internal - Boolean
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group_search_result`.
    

### GET Get Attribute Groups for Custom Object

`GET /custom_object_definitions/{object_type}/attribute_groups`

Operation ID: `Get Attribute Groups for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Action to get all the attribute groups with no filtering.

This endpoint may return the following faults:

*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required)
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `expand` (query, array of string)

#### Responses

*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_groups`.
    

### PUT Assign Custom Object Attribute Definition to Attribute Group

`PUT /custom_object_definitions/{object_type}/attribute_groups/{group_id}/attribute_definitions/{def_id}`

Operation ID: `Assign Custom Object Attribute Definition to Attribute Group`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Assign an attribute definition to an attribute group.

This endpoint may return the following faults:

*   500 - AttributeDefinitionNotFoundException - Indicates the specified attribute definition is not found.
*   404 - AttributeGroupNotFoundException - Indicates the specified attribute group is not found.
*   404 - ObjectTypeNotFoundException - Indicates the specified custom object is not found.

#### Parameters

*   `object_type` (path, string, required) The ID of the custom object that contains the attribute definition and attribute group.
*   `group_id` (path, string, required) The ID of the attribute group.  
    Minimum length: 1.
*   `def_id` (path, string, required) The ID of the attribute definition.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `AttributeGroupNotFoundException` - Indicates the specified attribute group is not found. or `ObjectTypeNotFoundException` - Indicates the specified custom object is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Indicates the specified attribute definition is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Un-assign Custom Object Attribute Definition from Attribute Group

`DELETE /custom_object_definitions/{object_type}/attribute_groups/{group_id}/attribute_definitions/{def_id}`

Operation ID: `Un-assign Custom Object Attribute Definition from Attribute Group`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Un-assign an attribute definition from an attribute group.

This endpoint may return the following faults:

*   500 - AttributeDefinitionNotFoundException - Indicates the specified attribute definition is not found.
*   404 - AttributeGroupNotFoundException - Indicates the specified attribute group is not found.
*   404 - ObjectTypeNotFoundException - Indicates the specified custom object is not found.

#### Parameters

*   `object_type` (path, string, required) The ID of the custom object that contains the attribute definition and attribute group.
*   `group_id` (path, string, required) The ID of the attribute group.  
    Minimum length: 1.
*   `def_id` (path, string, required) The ID of the attribute definition.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `AttributeGroupNotFoundException` - Indicates the specified attribute group is not found. or `ObjectTypeNotFoundException` - Indicates the specified custom object is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Indicates the specified attribute definition is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get Attribute Group for Custom Object

`GET /custom_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Get Attribute Group for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Action to get attribute group information.

This endpoint may return the following faults:

*   404 - AttributeGroupNotFoundException - Thrown in case the attribute group does not exist matching the given id
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) The id of the requested attribute group.  
    Minimum length: 1.
*   `select` (query, string)
*   `expand` (query, array of string)

#### Responses

*   **404** `AttributeGroupNotFoundException` - Thrown in case the attribute group does not exist matching the given id or `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group`.
    

### PUT Create Attribute Group for Custom Object

`PUT /custom_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Create Attribute Group for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Creates a attribute group using the information provided.

This endpoint may return the following faults:

*   400 - IdConflictException - when the id in the body does not match that provided in the URL
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) The id of the attribute group to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_group`.

#### Responses

*   **400** `IdConflictException` - when the id in the body does not match that provided in the URL
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group`.
    

### DELETE Delete Attribute Groups for Custom Object

`DELETE /custom_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Delete Attribute Groups for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Deletes the attribute group by ID

This endpoint may return the following faults:

*   404 - AttributeGroupNotFoundException - Thrown in case the attribute group does not exist matching the given id
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) One attribute group id to remove

#### Responses

*   **204**
*   **404** `AttributeGroupNotFoundException` - Thrown in case the attribute group does not exist matching the given id or `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Attribute Group for Custom Object

`PATCH /custom_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Update Attribute Group for Custom Object`. Tags: custom\_object\_definitions. Security: oauth2\_application.

Updates the attribute group with the specified information.

This endpoint may return the following faults:

*   404 - AttributeGroupNotFoundException - Thrown in case the attribute group does not exist matching the given id
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) The id of the requested attribute group.  
    Minimum length: 1.
*   `If-Match` (header, string)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_group`.

#### Responses

*   **404** `AttributeGroupNotFoundException` - Thrown in case the attribute group does not exist matching the given id or `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### object\_attribute\_definition\_search\_result

Document representing an attributedefinition search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of object\_attribute\_definition_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "description": {
        "default": "Description",
        "es": "mia description"
      },
      "display_name": {
        "default": "default name",
        "es": "nombre"
      },
      "id": "my-attributedefinition1",
      "key": false,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_definitions/my-attributedefinition1",
      "localizable": true,
      "mandatory": false,
      "queryable": true,
      "searchable": false,
      "site_specific": false,
      "system": false,
      "value_type": "string",
      "visible": false
    },
    {
      "display_name": {
        "default": "second name",
        "fr": "non de plume"
      },
      "id": "my-attributedefinition2",
      "key": true,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_definitions/my-attributedefinition2",
      "localizable": true,
      "mandatory": true,
      "queryable": true,
      "searchable": true,
      "site_specific": false,
      "system": false,
      "value_type": "string",
      "visible": true
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### object\_attribute\_definitions

Document representing an unfiltered list of object attribute definitions.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object\_attribute\_definition_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### object\_attribute\_definition

Document representing a attribute definition

*   `creation_date` (_string (date-time)_)
*   `default_value` (_object\_attribute\_value\_definition_) The default value of this attribute. It can be updated, but not created.
*   `description` (_object (localized)_) The localized description of the attribute.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The localized name presented to the user in forms.
    
    Additional properties: `string`.
    
*   `effective_id` (_string_) The effective ID, which is c\_id if the attribute is custom, and just the id otherwise. It is read only.
*   `externally_defined` (_boolean_) Flag indicating if this attribute is externally defined.
*   `externally_managed` (_boolean_) Flag indicating if this attribute is externally managed.
*   `field_height` (_integer (int32)_) The height of the field for this attribute in the editor.
*   `field_length` (_integer (int32)_) The length of the field for this attribute in the editor.
*   `id` (_string_) The user supplied ID of the attribute.
*   `key` (_boolean_) Flag indicating if this is a key attribute.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL that is used to get this instance. Value is computed and read-only.
*   `localizable` (_boolean_) Flag indicating if this attribute can be localized.
*   `mandatory` (_boolean_) Flag indicating if a value is mandatory for the attribute.
*   `max_value` (_number (double)_) The maximum possible value for this attribute.
*   `min_length` (_integer (int32)_) The minimum length of the field for this attribute.
*   `min_value` (_number (double)_) The minimum possible value for this attribute.
*   `multi_value_type` (_boolean_)
    
    True if the attribute can have multiple values.
    
    Attributes of the following types are multi-value capable:
    
    *   set\_of\_int
        
    *   set\_of\_number
        
    *   set\_of\_string
        
    
    Additionally, attributes of the following types can be multi-value enabled:
    
    *   enum\_of\_int
        
    *   enum\_of\_string
        
*   `order_required` (_boolean_) Flag indicating if this attribute is required for order of the attribute model's product. The set of these can be used in order line items.
*   `queryable` (_boolean_) Returns true if the attribute definition is explicitly marked queryable. If no explicit queryable is found and the attribute value type belongs to a queryable type, true is returned too. In all other cases false is returned. Value is computed and read-only.
*   `read_only` (_boolean_) Flag indicating if this attribute is read-only. It is read only.
*   `regular_expression` (_string_) A regular expression that defines the legal values for this attribute.
*   `requires_encoding` (_boolean_) Flag indicating if this attribute can be encoded using the encoding="off" flag in ISML templates. It is read only.
*   `scale` (_integer (int32)_) The minimum number of fraction digits for a value of this attribute.
*   `searchable` (_boolean_) Flag indicating if this attribute is searchable.
*   `set_value_type` (_boolean_) Flag indicating if this attribute is of type 'Set of'. It is read only.
*   `site_specific` (_boolean_) Flag indicating if this attribute is site-specific.
*   `system` (_boolean_) Flag indicating if this attribute is a system attribute.
*   `unit` (_object (localized)_) The unit of measure for this attribute.
    
    Additional properties: `string`.
    
*   `value_definitions` (_array of object\_attribute\_value\_definition_) A set of values that are possible for this attribute. It is read only.
*   `value_type` (_string_) The type of this attribute.  
    Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `image`, `boolean`, `money`, `quantity`, `datetime`, `email`, `password`, `set_of_string`, `set_of_int`, `set_of_double`, `enum_of_string`, `enum_of_int`, `unknown`.
*   `visible` (_boolean_) Flag indicating if this attribute is visible.

_Example_

```
{
  "description": {
    "default": "Description",
    "es": "mia description"
  },
  "display_name": {
    "default": "default name",
    "es": "nombre"
  },
  "id": "MyAttributeDefinition",
  "key": false,
  "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_definitions/MyAttributeDefinition",
  "localizable": true,
  "mandatory": false,
  "queryable": true,
  "searchable": false,
  "site_specific": false,
  "system": false,
  "value_type": "string",
  "visible": false
}
```

### object\_attribute\_group\_search\_result

Document representing a attributegroup search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of object\_attribute\_group_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "definitions_count": 5,
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "display_name": {
        "de": "A German my-display_name",
        "default": "my-display_name",
        "en": "An English my-display_name"
      },
      "id": "my-attributegroup1",
      "internal": false,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_groups/my-attributegroup1",
      "position": 1
    },
    {
      "definitions_count": 12,
      "display_name": {
        "default": "my-display_name"
      },
      "id": "my-attributegroup2",
      "internal": false,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_groups/my-attributegroup2",
      "position": 2
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### object\_attribute\_groups

Document representing an unfiltered list of object group definitions.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object\_attribute\_group_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### object\_attribute\_group

Document representing a attribute group

*   `attribute_definitions` (_array of object\_attribute\_definition_) Attributes with the group displayed when expand=definition
*   `attribute_definitions_count` (_integer (int32)_) The count of the attributes within the group. This is a computed attribute and is read-only
*   `creation_date` (_string (date-time)_)
*   `description` (_object (localized)_) The free-form text description of the group by locale
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The name used to display the group by locale.
    
    Additional properties: `string`.
    
*   `id` (_string_) The group's user specified identifier, used to retrieve the group
*   `internal` (_boolean_) True if the group is meant only for internal use, false otherwise. This property is read-only.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) URL that is used to get this instance. This is a computed attribute and is read-only
*   `position` (_number (double)_) The position of the group relative to other groups.  
    Minimum: 0.

_Example_

```
{
  "definitions_count": 17,
  "description": {
    "de": "A German my-description",
    "default": "my-description",
    "en": "An English my-description"
  },
  "display_name": {
    "de": "A German my-display_name",
    "default": "my-display_name",
    "en": "An English my-display_name"
  },
  "id": "my-attributegroup",
  "internal": false,
  "link": "https://example.com/s/-/dw/data/{version}/custom_objects/Global_String/attribute_groups/my-attributegroup",
  "position": 1
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### object\_attribute\_value\_definition

Document representing a attribute definition

*   `description` (_object (localized)_) A description of the attribute value.
    
    Additional properties: `string`.
    
*   `display_value` (_object (localized)_) A display name that can be used to present this value in the user interface. For example, the value might be '1' but the display name might be 'Order Exported'.
    
    Additional properties: `string`.
    
*   `id` (_string_) The ID of the attribute value.
*   `position` (_number (double)_) The position of the attribute value within the set of attribute values.
*   `value` (_object_) The value of the attribute.

_Example_

```
{
  "display_value": {
    "default": "Enum Of String Value 1"
  },
  "id": "EnumOfStringValue1",
  "position": 0,
  "value": "EnumOfStringValue1"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=1b539f44e6912686fcac4b127aa20849cfd097cef1e88d30f76d6b70928b814d url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-custom-objects.md -->

Data Custom Objects (deprecated)

# Data Custom Objects (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Read site specific Custom Object

`GET /sites/{site_id}/custom_objects/{object_type}/{key}`

Operation ID: `Read site specific Custom Object`. Tags: sites. Security: oauth2\_application.

Reads a site specific Custom Object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID
*   404 - CustomObjectNotFoundException - For an unknown object key

#### Parameters

*   `site_id` (path, string, required) the ID of the site  
    Minimum length: 1.
*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Responses

*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID or `CustomObjectNotFoundException` - For an unknown object key
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object`.
    

### PUT Create site specific Custom Object

`PUT /sites/{site_id}/custom_objects/{object_type}/{key}`

Operation ID: `Create site specific Custom Object`. Tags: sites. Security: oauth2\_application.

Creates a site specific Custom Object from the request body. Note that an existing site specific Custom Object with the same key is overwritten by this action.

Use Custom Properties prefixed with `c_` to define the Custom Object fields.  
For localizable strings, structure the field to support multiple language values by using a map where each locale, for example: en\_US, fr\_FR, has its corresponding string value.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID
*   404 - CustomObjectNotFoundException - For an unknown object key

#### Parameters

*   `site_id` (path, string, required) the ID of the site  
    Minimum length: 1.
*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `custom_object`.

#### Responses

*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID or `CustomObjectNotFoundException` - For an unknown object key
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object`.
    

### DELETE Delete site specific Custom Object

`DELETE /sites/{site_id}/custom_objects/{object_type}/{key}`

Operation ID: `Delete site specific Custom Object`. Tags: sites. Security: oauth2\_application.

Deletes a site specific Custom Object. If the Custom Object does not exist, this will do nothing. Note that the customization scripts are only called, if the Custom Object does exist.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID

#### Parameters

*   `site_id` (path, string, required) the ID of the site  
    Minimum length: 1.
*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update site specific Custom Object

`PATCH /sites/{site_id}/custom_objects/{object_type}/{key}`

Operation ID: `Update site specific Custom Object`. Tags: sites. Security: oauth2\_application.

Updates a site specific Custom Object with information from the request body. Note that only provided attributes are updated and that the key attribute is ignored. All other attributes are unchanged.

Use Custom Properties prefixed with `c_` to define the Custom Object fields.  
For localizable strings, structure the field to support multiple language values by using a map where each locale, for example: en\_US, fr\_FR, has its corresponding string value.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID
*   404 - CustomObjectNotFoundException - For an unknown object key

#### Parameters

*   `site_id` (path, string, required) the ID of the site  
    Minimum length: 1.
*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `custom_object`.

#### Responses

*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID or `CustomObjectNotFoundException` - For an unknown object key
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### custom\_object

Document representing a custom object that contains all defined custom attributes for its object type.

*   `key_property` (_string_) The name of the key property for the custom object. This is ignored in input documents.
*   `key_value_integer` (_integer (int32)_) The id of the custom object when the type of the key is Integer. This is ignored in input documents.
*   `key_value_string` (_string_) The id of the custom object when the type of the key is String. This is ignored in input documents.
*   `object_type` (_string_) The id of the object type. This is ignored in input documents.

_Example_

```
{
  "key_property": "key_attribute",
  "object_type": "my_object_type",
  "c_boolean": true,
  "c_date": "2015-02-03T00:00:00.000Z",
  "c_email": "jdoe@salesforce.com",
  "c_integer": 42,
  "c_number": 42,
  "c_string": "some text"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=bbaa16a080aa7de01588bedd5a41d660dbb4572855031cc9c1fcd7d0c9aa0028 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-custom-object-search.md -->

Data Custom Objects Search (deprecated)

# Data Custom Objects Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search custom objects

`POST /custom_objects_search/{object_type}`

Operation ID: `Search custom objects`. Tags: custom\_objects\_search. Security: oauth2\_application.

Search resource for custom objects in scope of a specific custom object type.

The custom object search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   key\_value\_string - String
    
*   key\_value\_integer - Integer
    
*   creation\_date - Date
    
*   last\_modified - Date
    
*   site\_id - String
    
*   any custom attribute
    

Note that only searchable attributes can be used in sorting.

This endpoint may return the following faults:

*   400 - TypeMissmatchException - Indicates that the value to search with does not match the type of the search field.
*   404 - ObjectTypeNotFoundException - In case of an unknown object type.

#### Parameters

*   `object_type` (path, string, required) ID of the object type to search objects for  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `TypeMissmatchException` - Indicates that the value to search with does not match the type of the search field.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - In case of an unknown object type.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### custom\_object\_search\_result

Document representing a custom object search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of custom\_object_) The sorted array of search hits. May be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "key_property": "key_attribute",
      "key_value_integer": 1,
      "object_type": "my_object_type",
      "c_boolean": true,
      "c_date": "2015-02-03T00:00:00.000Z",
      "c_email": "jdoe@salesforce.com",
      "c_integer": 42,
      "c_number": 42,
      "c_string": "some text"
    }
  ],
  "query": {
    "bool_query": {
      "must": [
        {
          "term_query": {
            "fields": [
              "site_id"
            ],
            "operator": "is",
            "values": [
              "SiteGenesis"
            ]
          }
        },
        {
          "term_query": {
            "fields": [
              "c_number"
            ],
            "operator": "is",
            "values": [
              42
            ]
          }
        }
      ]
    }
  },
  "select": "(**)",
  "start": 2,
  "total": 4
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### custom\_object

Document representing a custom object that contains all defined custom attributes for its object type.

*   `key_property` (_string_) The name of the key property for the custom object. This is ignored in input documents.
*   `key_value_integer` (_integer (int32)_) The id of the custom object when the type of the key is Integer. This is ignored in input documents.
*   `key_value_string` (_string_) The id of the custom object when the type of the key is String. This is ignored in input documents.
*   `object_type` (_string_) The id of the object type. This is ignored in input documents.

_Example_

```
{
  "key_property": "key_attribute",
  "object_type": "my_object_type",
  "c_boolean": true,
  "c_date": "2015-02-03T00:00:00.000Z",
  "c_email": "jdoe@salesforce.com",
  "c_integer": 42,
  "c_number": 42,
  "c_string": "some text"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=27c450567084a9d12ba32233763cd4535a8c7a848bb3d3142384beec8f7018cb url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-customer-group-search.md -->

Data Customer Group Search (deprecated)

# Data Customer Group Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search CustomerGroups

`POST /sites/{site_id}/customer_group_search`

Operation ID: `Search CustomerGroups`. Tags: sites. Security: oauth2\_application.

Searches for customer groups.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   description - String
    
*   type - String Enum value\[system, dynamic, static\]
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   description - String
    

This endpoint may return the following faults:

*   400 - CustomerGroupTypeInvalidException - Thrown if the search term in term query does not match any of the customer group type.
*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `CustomerGroupTypeInvalidException` - Thrown if the search term in term query does not match any of the customer group type. or `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### customer\_group\_search\_result

Document representing a customer group search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of customer\_group_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### customer\_group

Document representing a customer group

*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description for the customer group. This property is read-only for system groups.
*   `id` (_string_, read-only) The user specific identifier for the customer group, which must be unique across the organization. Property is read-only.  
    Minimum length: 1. Maximum length: 256.
*   `in_deletion` (_boolean_) The deletion status of this customer group.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `member_count` (_integer (int32)_) The number of members in this customer group.
*   `rule` (_rule_) The rule of this customer group. Only available for dynamic customer groups.
*   `type` (_string_) The type of the customer group. This property is read-only.  
    Allowed values: `system`, `dynamic`, `static`.

_Example_

```
{
  "description": "Test group",
  "id": "test_customergroup1",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/customer_groups/test_customergroup1",
  "type": "dynamic"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### rule

Document representing a customer group rule

*   `description` (_string_) The description of the rule, describing its conditions in natural language. Property is read-only.

_Example_

```
{
  "description": "'session.referrerURL' starts with [http://www.google.de]"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=84acdab5a66caaa94ecfa02cc3a31bed8a44ebba1b488011296a631cf517023b url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-customer-groups.md -->

Data Customer Groups (deprecated)

# Data Customer Groups (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Customer Groups

`GET /sites/{site_id}/customer_groups`

Operation ID: `Get Customer Groups`. Tags: sites. Security: oauth2\_application.

Action to get all the customer groups with no filtering.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_groups`.
    

### GET Get Customer Group

`GET /sites/{site_id}/customer_groups/{id}`

Operation ID: `Get Customer Group`. Tags: sites. Security: oauth2\_application.

Action to get customer group information.

This endpoint may return the following faults:

*   404 - CustomerGroupNotFoundException - Thrown in case the customer group does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested customer group.  
    Minimum length: 1.
*   `select` (query, string) The attribute selector. Include 'member\_count' explicitly if member count per customer group is required.

#### Responses

*   **404** `CustomerGroupNotFoundException` - Thrown in case the customer group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group`.
    

### PUT Create Customer Group

`PUT /sites/{site_id}/customer_groups/{id}`

Operation ID: `Create Customer Group`. Tags: sites. Security: oauth2\_application.

Creates a customer group using the information provided.

This endpoint may return the following faults:

*   400 - CustomerGroupCreateException - Thrown when there are system error in creating the customer group.
*   400 - IdConflictException - Thrown when id in query parameter is different from the id in the body.
*   403 - SystemCustomerGroupCreateForbiddenException - Thrown when attempting to create the system customer group.
*   409 - CustomerGroupAlreadyExistsException - if a customer group exists already in the site with the given identifier.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the customer group to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_group`.

#### Responses

*   **400** `CustomerGroupCreateException` - Thrown when there are system error in creating the customer group. or `IdConflictException` - Thrown when id in query parameter is different from the id in the body.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `SystemCustomerGroupCreateForbiddenException` - Thrown when attempting to create the system customer group.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `CustomerGroupAlreadyExistsException` - if a customer group exists already in the site with the given identifier.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group`.
    

### DELETE Delete Customer Group

`DELETE /sites/{site_id}/customer_groups/{id}`

Operation ID: `Delete Customer Group`. Tags: sites. Security: oauth2\_application.

Triggers customer group deletion by ID. Be aware that the deletion happens via asynchronous batch process which is the reason the deletion itself is not necessarily finished after the call to this resource returned. The customer group that is in deletion will be provided in the response.

This endpoint may return the following faults:

*   403 - SystemCustomerGroupDeleteForbiddenException - Thrown when attempting to delete the system customer group.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) One customer group id to remove
*   `select` (query, string) The attribute selector for the customer group which is now in deletion

#### Responses

*   **403** `SystemCustomerGroupDeleteForbiddenException` - Thrown when attempting to delete the system customer group.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group`.
    

### PATCH Update Customer Group

`PATCH /sites/{site_id}/customer_groups/{id}`

Operation ID: `Update Customer Group`. Tags: sites. Security: oauth2\_application.

Updates the customer group with the specified information.

This endpoint may return the following faults:

*   403 - SystemCustomerGroupUpdateForbiddenException - Thrown when attempting to update the system customer group.
*   404 - CustomerGroupNotFoundException - Thrown in case the customer group does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested customer group.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_group`.

#### Responses

*   **403** `SystemCustomerGroupUpdateForbiddenException` - Thrown when attempting to update the system customer group.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerGroupNotFoundException` - Thrown in case the customer group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group`.
    

### POST Search CustomerGroupMembers

`POST /sites/{site_id}/customer_groups/{id}/member_search`

Operation ID: `Search CustomerGroupMembers`. Tags: sites. Security: oauth2\_application.

Searches for customer group members. For dynamic customer groups and the system groups "Everyone" and "Unregistered" no result is returned (Status Code: 204 - No Content).

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. These are the list of searchable attributes with their corresponding buckets:

Main:

*   login - String
    
*   active - Boolean
    

Customer Profile:

*   customer\_no - String
    
*   first\_name - String
    
*   last\_name - String
    
*   email - String
    
*   zip - String
    

Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining login and customer\_no above, only a conjunction is allowed (AND), whereas customer\_no and email can be joined using a disjunction because they are in the same bucket. If an attribute is used in a disjunction (OR) that violates this rule, an exception will be thrown.

The output of the query can also be sorted. These are the list of sortable attributes:

*   customer\_no - String
    
*   login - String
    

If the Business manager customer search is configured to use the new Search Service, the following differences apply:

*   all attributes can be used for sorting (except for 'active')
    
*   searching for 'zip' will only search in the customers default address
    
*   logical operators can be used without limits (but may result in degraded performance, depending on how they are combined)
    
*   new assignments might not be found immediately via the search service, and removed assignments might also not be in effect immediately (there is a slight delay in updating the index)
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.
*   404 - CustomerGroupNotFoundException - Thrown in case the customer group does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested members customer group.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerGroupNotFoundException` - Thrown in case the customer group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group_member_search_result`.
    

### GET Get Customer Group Members

`GET /sites/{site_id}/customer_groups/{id}/members`

Operation ID: `Get Customer Group Members`. Tags: sites. Security: oauth2\_application.

Action to get all the customer group members with no filtering. For dynamic customer groups and the system groups "Everyone" and "Unregistered" no result is returned (Status Code: 204 - No Content).

This endpoint may return the following faults:

*   404 - CustomerGroupNotFoundException - Thrown in case the customer group does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `id` (path, string, required)  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **404** `CustomerGroupNotFoundException` - Thrown in case the customer group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group_members`.
    

### GET Get CustomerGroupMember

`GET /sites/{site_id}/customer_groups/{id}/members/{customer_no}`

Operation ID: `Get CustomerGroupMember`. Tags: sites. Security: oauth2\_application.

Action to get customer group member information.

This endpoint may return the following faults:

*   404 - CustomerGroupMemberNotFoundException - Thrown in case the customer group member did not exist, or the group is not a static group
*   404 - CustomerGroupNotFoundException - Thrown in case the customer group does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested members customer group.  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number of the requested customer group member.  
    Minimum length: 1.
*   `select` (query, string) The selector for selective response content.

#### Responses

*   **404** `CustomerGroupMemberNotFoundException` - Thrown in case the customer group member did not exist, or the group is not a static group or `CustomerGroupNotFoundException` - Thrown in case the customer group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group_member`.
    

### PUT Assign CustomerGroupMember to group

`PUT /sites/{site_id}/customer_groups/{id}/members/{customer_no}`

Operation ID: `Assign CustomerGroupMember to group`. Tags: sites. Security: oauth2\_application.

Action to add customer to (static) customer group.

This endpoint may return the following faults:

*   403 - CustomerGroupUnsupportedAssignmentException - Thrown when the customer group is not a static group.
*   404 - CustomerGroupNotFoundException - Thrown in case the customer group does not exist matching the given id.
*   404 - CustomerNotFoundException - Thrown in case the customer list did not exist, or the customer does not exist in in the list.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the customer group.  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number of the customer to add to the group.  
    Minimum length: 1.
*   `select` (query, string) The selector for selective response content.

#### Responses

*   **403** `CustomerGroupUnsupportedAssignmentException` - Thrown when the customer group is not a static group.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerGroupNotFoundException` - Thrown in case the customer group does not exist matching the given id. or `CustomerNotFoundException` - Thrown in case the customer list did not exist, or the customer does not exist in in the list.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_group_member`.
    

### DELETE Unassign CustomerGroupMember

`DELETE /sites/{site_id}/customer_groups/{id}/members/{customer_no}`

Operation ID: `Unassign CustomerGroupMember`. Tags: sites. Security: oauth2\_application.

Action to remove a customer from a (static) customer group.

This endpoint may return the following faults:

*   403 - CustomerGroupUnsupportedAssignmentException - Thrown when the customer group is not a static group.
*   404 - CustomerGroupNotFoundException - Thrown in case the customer group does not exist matching the given id.
*   404 - CustomerNotFoundException - Thrown in case the customer list did not exist, or the customer does not exist in the list.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the customer group.  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number of the customer to remove from the group.  
    Minimum length: 1.
*   `select` (query, string) The selector for selective response content.

#### Responses

*   **204**
*   **403** `CustomerGroupUnsupportedAssignmentException` - Thrown when the customer group is not a static group.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerGroupNotFoundException` - Thrown in case the customer group does not exist matching the given id. or `CustomerNotFoundException` - Thrown in case the customer list did not exist, or the customer does not exist in the list.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

## Schemas

### customer\_groups

Document representing an unfiltered list of customer groups.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of customer\_group_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "_resource_state": "c2309jd239jdrifj3ui4fn",
      "description": "Test group 1",
      "id": "test_customergroup_1",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/customer_groups/test_customergroup_1",
      "member_count": 5,
      "type": "static"
    },
    {
      "_resource_state": "82jhch39saxn23denx93e8",
      "description": "Test group 2",
      "id": "test_customergroup_2",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/customer_groups/test_customergroup_2",
      "member_count": 15,
      "type": "static"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 2
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### customer\_group

Document representing a customer group

*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description for the customer group. This property is read-only for system groups.
*   `id` (_string_, read-only) The user specific identifier for the customer group, which must be unique across the organization. Property is read-only.  
    Minimum length: 1. Maximum length: 256.
*   `in_deletion` (_boolean_) The deletion status of this customer group.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `member_count` (_integer (int32)_) The number of members in this customer group.
*   `rule` (_rule_) The rule of this customer group. Only available for dynamic customer groups.
*   `type` (_string_) The type of the customer group. This property is read-only.  
    Allowed values: `system`, `dynamic`, `static`.

_Example_

```
{
  "description": "Test group",
  "id": "test_customergroup1",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/customer_groups/test_customergroup1",
  "type": "dynamic"
}
```

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### customer\_group\_member\_search\_result

Document representing a customer group member search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of customer\_group\_member_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "active": true,
      "customer_no": "0001",
      "email": "rhood@example.com",
      "first_name": "Robin",
      "last_name": "Hood",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/customer_groups/test_customergroup/members/test_customer",
      "login": "test_customer"
    }
  ],
  "query": {
    "term_query": {
      "fields": [
        "active"
      ],
      "operator": "is",
      "values": [
        true
      ]
    }
  },
  "start": 0,
  "total": 1
}
```

### customer\_group\_members

Document representing an unfiltered list of customer groups.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of customer\_group\_member_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "active": true,
      "customer_link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis/customers/test_customer",
      "customer_no": "test_customer",
      "first_name": "John",
      "last_name": "Doe",
      "login": "test"
    },
    {
      "active": true,
      "customer_link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis/customers/bigshot_customer",
      "customer_no": "bigshot_customer",
      "first_name": "Big",
      "last_name": "Shot",
      "login": "bighsot"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 2
}
```

### customer\_group\_member

Document representing a customer group member

*   `active` (_boolean_) A flag indicating whether the customer is enabled and can log in.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_link` (_string_) The link to the customer resource.  
    Maximum length: 256.
*   `customer_no` (_string_) The customers number (id).  
    Maximum length: 100.
*   `email` (_string (email)_) The customer's email address.  
    Maximum length: 256.
*   `first_name` (_string_) The customer's first name.  
    Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `last_name` (_string_) The customer's last name.  
    Maximum length: 256.
*   `link` (_string_) The link to the customer group member resource.  
    Maximum length: 256.
*   `login` (_string_) The login of the customer.  
    Maximum length: 256.

_Example_

```
{
  "active": true,
  "customer_link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis/customers/test_customer",
  "customer_no": "test_customer",
  "first_name": "John",
  "last_name": "Doe",
  "login": "test"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### rule

Document representing a customer group rule

*   `description` (_string_) The description of the rule, describing its conditions in natural language. Property is read-only.

_Example_

```
{
  "description": "'session.referrerURL' starts with [http://www.google.de]"
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=d3d2b1265a8e21008ee3802982d56d7d25d44094328d0ef7c3005a484f400c54 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-customer-lists.md -->

Data Customer Lists (deprecated)

# Data Customer Lists (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search for customers in a customer list

`POST /customer_lists/{customer_list_id}/customer_search`

Operation ID: `Search for customers in a customer list`. Tags: customer\_lists. Security: oauth2\_application.

Action to search for customers in a customer list.

The query attribute specifies a complex query that can be used to narrow down the search. Note that a text\_query search only returns exact word matches. For example, the search term "Jon" returns "Jon Smith", but doesn't return "Jonathan Smith".

The sum of the values of the start and count parameters should not be more than 10000.

These attributes are searchable:

*   customer\_no - String
    
*   first\_name - String
    
*   second\_name - String
    
*   last\_name - String
    
*   suffix - String
    
*   salutation - String
    
*   title - String
    
*   fax - String
    
*   phone\_home - String
    
*   phone\_business - String
    
*   phone\_mobile - String
    
*   email - String
    
*   gender - Integer
    
*   company\_name - String
    
*   credentials.login - String
    
*   credentials.enabled - boolean
    

#### Parameters

*   `customer_list_id` (path, string, required) The customer list id to search in  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_search_result`.
    

### GET Get customer list

`GET /customer_lists/{list_id}`

Operation ID: `Get customer list`. Tags: customer\_lists. Security: oauth2\_application.

Action to read an existing customerlist.

This endpoint may return the following faults:

*   404 - CustomerListNotFoundException - Indicates that there was no customerlist found for the customerlist id.

#### Parameters

*   `list_id` (path, string, required) the id of the customerlist  
    Minimum length: 1.

#### Responses

*   **404** `CustomerListNotFoundException` - Indicates that there was no customerlist found for the customerlist id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_list`.
    

### POST Create customer

`POST /customer_lists/{list_id}/customers`

Operation ID: `Create customer`. Tags: customer\_lists. Security: oauth2\_application.

Action to create a new customer. The customer is created using the specified credentials and customer information.This action verifies the following:

*   Login acceptance criteria and uniqueness
    
*   Mandatory customer properties
    

If the action fails to create the customer, it returns a 400 fault with an appropriate message.

This endpoint may return the following faults:

*   400 - CredentialsMissingException - Indicates that the mandatory credentials are missing in the input document.
*   400 - InvalidLoginException - Indicates the login does not match the login acceptance criteria.
*   400 - LoginAlreadyInUseException - Indicates the login is already in use.
*   400 - LoginMissingException - Indicates that the mandatory login property is missing in the input document.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer`.

#### Responses

*   **400** `CredentialsMissingException` - Indicates that the mandatory credentials are missing in the input document. or `InvalidLoginException` - Indicates the login does not match the login acceptance criteria. or `LoginAlreadyInUseException` - Indicates the login is already in use. or `LoginMissingException` - Indicates that the mandatory login property is missing in the input document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### GET Get customer

`GET /customer_lists/{list_id}/customers/{customer_no}`

Operation ID: `Get customer`. Tags: customer\_lists. Security: oauth2\_application.

Action to get customer information.

This endpoint may return the following faults:

*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.

#### Responses

*   **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### PUT Create customer with given customer number

`PUT /customer_lists/{list_id}/customers/{customer_no}`

Operation ID: `Create customer with given customer number`. Tags: customer\_lists. Security: oauth2\_application.

Action to create a new customer. The customer is created using the specified customer number, credentials and customer information.This action verifies the following:

*   Login acceptance criteria and uniqueness
    
*   Mandatory customer properties
    

If the action fails to create the customer, it returns a 400 fault with an appropriate message.

This endpoint may return the following faults:

*   400 - CredentialsMissingException - Indicates that the mandatory credentials are missing in the input document.
*   400 - InvalidLoginException - Indicates the login does not match the login acceptance criteria.
*   400 - LoginAlreadyInUseException - Indicates that the given login is already in use.
*   400 - LoginMissingException - Indicates that the mandatory login property is missing in the input document.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer`.

#### Responses

*   **400** `CredentialsMissingException` - Indicates that the mandatory credentials are missing in the input document. or `InvalidLoginException` - Indicates the login does not match the login acceptance criteria. or `LoginAlreadyInUseException` - Indicates that the given login is already in use. or `LoginMissingException` - Indicates that the mandatory login property is missing in the input document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### DELETE Delete customer

`DELETE /customer_lists/{list_id}/customers/{customer_no}`

Operation ID: `Delete customer`. Tags: customer\_lists. Security: oauth2\_application.

Deletes the customer including all related information like the customer addresses.  

Returns a status code of 204 on successful completion when deleting the customer. If the customer to be deleted did not exist, a 204 will still be returned to indicate the resource is no longer present in the system.

This endpoint may return the following faults:

*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update customer

`PATCH /customer_lists/{list_id}/customers/{customer_no}`

Operation ID: `Update customer`. Tags: customer\_lists. Security: oauth2\_application.

Updates the customer with the specified information. The customer number is allowed to be updated but will result in a CustomerNumberAlreadyInUseException if there is already another customer with the same customer number existing.

This endpoint may return the following faults:

*   400 - InvalidLoginException - Indicates the login does not match the login acceptance criteria.
*   400 - LoginAlreadyInUseException - Indicates the login is already in use.
*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer`.

#### Responses

*   **400** `InvalidLoginException` - Indicates the login does not match the login acceptance criteria. or `LoginAlreadyInUseException` - Indicates the login is already in use.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### GET Get all customer addresses

`GET /customer_lists/{list_id}/customers/{customer_no}/addresses`

Operation ID: `Get all customer addresses`. Tags: customer\_lists. Security: oauth2\_application.

Action that returns a pageable list of all customer addresses. The default page size is 10 customer addresses.

This endpoint may return the following faults:

*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.

#### Responses

*   **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address_result`.
    

### POST Create customer address

`POST /customer_lists/{list_id}/customers/{customer_no}/addresses`

Operation ID: `Create customer address`. Tags: customer\_lists. Security: oauth2\_application.

The action creates a new customer address with the given address information.

This endpoint may return the following faults:

*   400 - AddressIdAlreadyInUseException - If the address id is already in use.
*   400 - InvalidAddressIdException - If the address id is null or empty.
*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_address`.

#### Responses

*   **400** `AddressIdAlreadyInUseException` - If the address id is already in use. or `InvalidAddressIdException` - If the address id is null or empty.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address`.
    

### GET Get customer address

`GET /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}`

Operation ID: `Get customer address`. Tags: customer\_lists. Security: oauth2\_application.

Action which returns an address of a customer.

This endpoint may return the following faults:

*   404 - CustomerListCustomerAddressNotFoundException - Indicates that the customer address id is unknown.
*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.
*   `address_id` (path, string, required) The address id  
    Minimum length: 1.

#### Responses

*   **404** `CustomerListCustomerAddressNotFoundException` - Indicates that the customer address id is unknown. or `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address`.
    

### DELETE Delete customer address

`DELETE /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}`

Operation ID: `Delete customer address`. Tags: customer\_lists. Security: oauth2\_application.

Action which deletes a customer address.

This endpoint may return the following faults:

*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.
*   `address_id` (path, string, required) The address id  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update customer address

`PATCH /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}`

Operation ID: `Update customer address`. Tags: customer\_lists. Security: oauth2\_application.

Action which updates an address of a customer with the given address information.

This endpoint may return the following faults:

*   400 - AddressIdAlreadyInUseException - If the new address id is already in use.
*   400 - InvalidAddressIdException - If the new address id is empty.
*   404 - CustomerListCustomerAddressNotFoundException - Indicates that the customer address id is unknown.
*   404 - CustomerListCustomerNotFoundException - Indicates that the customer with the given customer number is unknown.
*   404 - CustomerListNotFoundException - Indicates that the customer list with the given customer list id is unknown.

#### Parameters

*   `list_id` (path, string, required) The customer list id  
    Minimum length: 1.
*   `customer_no` (path, string, required) The customer number  
    Minimum length: 1.
*   `address_id` (path, string, required) The address id  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_address`.

#### Responses

*   **400** `AddressIdAlreadyInUseException` - If the new address id is already in use. or `InvalidAddressIdException` - If the new address id is empty.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerListCustomerAddressNotFoundException` - Indicates that the customer address id is unknown. or `CustomerListCustomerNotFoundException` - Indicates that the customer with the given customer number is unknown. or `CustomerListNotFoundException` - Indicates that the customer list with the given customer list id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### customer\_search\_result

Document representing a customer search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_)  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of customer\_search\_hit_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "data": {
        "customer_no": "000007"
      },
      "relevance": 1.5439257621765137
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "credentials.login"
      ],
      "search_phrase": "mmiller"
    }
  },
  "start": 0,
  "total": 1
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### customer\_list

Document representing a customer list.

*   `id` (_string_, required) The id of the customer list.  
    Minimum length: 1.
*   `preferences` (_customer\_list\_preferences_) The preferences of the customer list.

_Example_

```
{
  "id": "SiteGenesis"
}
```

### customer

Document representing a customer.

*   `birthday` (_string (date)_) The customer's birthday.
*   `company_name` (_string_) The customer's company name.  
    Maximum length: 256.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `credentials` (_credentials_) The customer's credentials.
*   `customer_id` (_string_) The customer's id. Both registered and guest customers have a customer id.  
    Maximum length: 28.
*   `customer_no` (_string_) The customer's number.  
    Maximum length: 100.
*   `email` (_string (email)_) The customer's email address.  
    Maximum length: 256.
*   `fax` (_string_) The fax number to use for the customer. The length is restricted to 32 characters.  
    Maximum length: 32.
*   `first_name` (_string_) The customer's first name.  
    Maximum length: 256.
*   `gender` (_integer (int32)_) The customer's gender.  
    Allowed values: `1`, `2`. Value meanings: `1`: Male; `2`: Female.
*   `global_party_id` (_string_) The Global Party ID is set by Customer 360 and identifies a person across multiple systems.
*   `job_title` (_string_) The customer's job title.  
    Maximum length: 256.
*   `last_login_time` (_string (date-time)_, read-only) The last login time of the customer.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `last_name` (_string_) The customer's last name.  
    Maximum length: 256.
*   `last_visit_time` (_string (date-time)_, read-only) The last visit time of the customer.
*   `phone_business` (_string_) The customer's business phone number.  
    Maximum length: 32.
*   `phone_home` (_string_) The customer's home phone number.  
    Maximum length: 32.
*   `phone_mobile` (_string_) The customer's mobile phone number.  
    Maximum length: 32.
*   `preferred_locale` (_string_, read-only) The customer's preferred locale, formatted with a hyphen. (For example: en-US) If the request uses an underscore, as with the Java locale format, the stored value is converted to a hyphen. (For example: en\_US is stored as en-US)
*   `previous_login_time` (_string (date-time)_) The time when the customer logged in previously.
*   `previous_visit_time` (_string (date-time)_) The time when the customer previously visited the store.
*   `primary_address` (_customer\_address_) The customers primary or default address.
*   `salutation` (_string_) The customer's salutation.  
    Maximum length: 256.
*   `second_name` (_string_) The customer's second name.  
    Maximum length: 256.
*   `suffix` (_string_) The customer's suffix (for example, "Jr." or "Sr.").  
    Maximum length: 256.
*   `title` (_string_) The customer's title (for example, "Mrs" or "Mr").  
    Maximum length: 256.

_Example_

```
{
  "birthday": "1970-01-31",
  "company_name": "Salesforce B2C Commerce",
  "creation_date": "2013-09-17T09:20:31.000Z",
  "credentials": {
    "enabled": true,
    "locked": false,
    "login": "dude",
    "password_question": "Mother's maiden name"
  },
  "customer_no": "0815",
  "email": "dude@salesforce.com",
  "fax": "001-444-4444",
  "first_name": "Dude",
  "job_title": "",
  "last_name": "Lebowski",
  "phone_business": "001-222-2222",
  "phone_home": "001-111-1111",
  "phone_mobile": "001-333-3333",
  "preferred_locale": "de_DE",
  "salutation": "Mr.",
  "second_name": "second",
  "suffix": "suffix",
  "title": "Dr."
}
```

### customer\_address\_result

Result document containing an array of customer addresses.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of customer\_address_) The array of customer address documents.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 10,
  "data": [
    {
      "_resource_state": "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
      "address1": "Lodyweg",
      "address_id": "my_home_address",
      "city": "Washingtonville",
      "company_name": "Salesforce B2C Commerce",
      "country_code": "SH",
      "first_name": "Pit",
      "full_name": "Pit Snipes",
      "job_title": "",
      "last_name": "Snipes",
      "phone": "001-111-1111",
      "postal_code": "15361",
      "state_code": "DE"
    }
  ],
  "next": "https://example.com/dw/data/{version}/customer_lists/4711/customers/0815/addresses?count=10&start=10",
  "start": 0,
  "total": 151
}
```

### customer\_address

Document representing a customer address.

*   `address1` (_string_) The customer's first address.  
    Maximum length: 256.
*   `address2` (_string_) The customer's second address value.  
    Maximum length: 256.
*   `address_id` (_string_, required) The customer address id.  
    Maximum length: 256.
*   `city` (_string_) The customer's city.  
    Maximum length: 256.
*   `company_name` (_string_) The customer's company name.  
    Maximum length: 256.
*   `country_code` (_string_, required) The customer's two-character country code per ISO 3166-1 alpha-2.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States. Maximum length: 2.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `etag` (_string_)
*   `first_name` (_string_) The customer's first name.  
    Maximum length: 256.
*   `full_name` (_string_) The concatenation of the customer's first, middle, and last names and its suffix.
*   `job_title` (_string_) The customer's job title.  
    Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `last_name` (_string_, required) The customer's last name.  
    Maximum length: 256.
*   `phone` (_string_) The customer's phone number.  
    Maximum length: 32.
*   `post_box` (_string_) The customer's post box.  
    Maximum length: 256.
*   `postal_code` (_string_) The customer's postal code.  
    Maximum length: 256.
*   `salutation` (_string_) The customer's salutation.  
    Maximum length: 256.
*   `second_name` (_string_) The customer's second name.  
    Maximum length: 256.
*   `state_code` (_string_) The customer's state.  
    Maximum length: 256.
*   `suffix` (_string_) The customer's suffix.  
    Maximum length: 256.
*   `suite` (_string_) The customer's suite.  
    Maximum length: 32.
*   `title` (_string_) The customer's title.  
    Maximum length: 256.

_Example_

```
{
  "address1": "10 Somewhere St.",
  "address2": "",
  "address_id": "myaddress",
  "city": "Boston",
  "company_name": "",
  "country_code": "",
  "first_name": "Dude",
  "full_name": "Dude Lebowski",
  "job_title": "",
  "last_name": "Lebowski",
  "phone": "",
  "post_box": "",
  "postal_code": "",
  "salutation": "",
  "second_name": "",
  "state_code": "",
  "suffix": "",
  "suite": "",
  "title": ""
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### customer\_search\_hit

Document representing a customer search hit.

*   `data` (_customer_) The search hit data
*   `relevance` (_number (double)_) The hit's relevance score.

_Example_

```
{
  "data": {
    "customer_no": "000007"
  },
  "relevance": 1.5439257621765137
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### customer\_list\_preferences

Document representing customer list preferences:

*   data-retention-age
    
*   customerno-sequence-enabled
    
*   lockout-enabled
    
*   max-failed-logins
    
*   lockout-effective-period
    
*   login-attempt-reset-time
    
*   min-password-length
    
*   min-password-special-chars
    
*   force-password-contains-alpha
    
*   force-password-contains-numeric
    
*   force-password-mixed-case
    
*   max-password-age
    
*   max-password-reset-token-age
    

*   `customer_no_sequence_enabled` (_boolean_, required) Used to determine if the customer number sequence is separated by customer list.
*   `data_retention_age` (_integer (int32)_, required) The number days to retain customer data (null or 0 <= x <= 99999).
*   `force_password_contains_alpha` (_boolean_, required) Used to determine if the password must contain an alphabetic character.
*   `force_password_contains_numeric` (_boolean_, required) Used to determine if the password must contain a numeric character.
*   `force_password_mixed_case` (_boolean_, required) Used to determine if the password must be mixed case.
*   `lockout_effective_period` (_integer (int32)_, required) The customer lockout period in minutes (one of 1, 30, 60, 120, 1440, 14400).
*   `lockout_enabled` (_boolean_, required) Used to determine if customers can be locked out.
*   `login_attempt_reset_time` (_integer (int32)_, required)
    
    The period after which the customer login attempt count resets in minutes (one of 0, 5, 30, 60, 120, 1440).
    
    ```
         1440)
    ```
    
*   `max_failed_logins` (_integer (int32)_, required) The maximum number of failed logins before a customer lockout can occur (1 <= x <= 200).
*   `max_password_age` (_integer (int32)_, required) The maximum age of the customer password in days (one of 7, 10, 14, 30, 60, 90, 365000).
*   `max_password_reset_token_age` (_integer (int32)_, required) The maximum age of the customer password reset token in minutes (one of 30, 60, 120, 360, 720, 1440).
*   `min_password_length` (_integer (int32)_, required)
    
    The minimum number of characters required for a customer password (one of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 20).
    
    ```
         12, 13, 14, 15, 20)
    ```
    
*   `min_password_special_chars` (_integer (int32)_, required) The minimum number of special characters required within a customer password (one of 0, 1, 2, 3, 4, 5).

### credentials

Document representing the credentials of a customer.

*   `enabled` (_boolean_) A flag indicating whether the customer is enabled and can log.
*   `locked` (_boolean_) A flag indicating whether the customer account is locked.
*   `login` (_string_, required) The login of the customer.  
    Maximum length: 256.
*   `password_question` (_string_) The password question.  
    Maximum length: 256.

_Example_

```
{
  "enabled": true,
  "locked": false,
  "login": "dude",
  "password_question": "Mother's maiden name"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=65472f92ac2b4344fac85d5e41b7a90a72c8f4ceb7ec61fef7dcfb09e31b1ace url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-data-deployment-tools.md -->

# Data Deployment Tools

Salesforce provides several tools for metadata deployment. Many deployment tools integrate with
[_Salesforce DevOps Center_](https://help.salesforce.com/s/articleView?id=platform.devops_center_overview.htm&type=5). DevOps Center is a change and release management tool.
Here's an overview of the most commonly used migration tools.

## Change Sets

Change sets is a Salesforce-native feature that transfers metadata between connected Salesforce orgs, such as from a source org to a target org. While not as robust and efficient as other tools, the feature is available to admin-level users through the Commerce setup UI. You can integrate change sets with the Salesforce DevOps Center to initiate and coordinate Change Sets between developers using command line UI and the declarative sets created by administrator level users. This approach offers a starting point for many organizations in using DevOps Center to manage metadata deployment.

The change sets feature doesn’t require additional installation. It’s limited to organizations with established Salesforce relationships (like sandboxes and their production org).

## Metadata API, Salesforce CLI (Command-Line Interface)

[Metadata API](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_intro.htm) is often used in complex deployments to retrieve, deploy, create, update, or delete customization information in Salesforce. It’s the backbone of many deployment processes. You can use it programmatically or through tools that provide a user interface for it, such as Salesforce CLI or Salesforce DevOps.

[Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.250.0.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm), which is part of Salesforce DX, is a command-line tool that supports both Metadata API and newer Salesforce DX commands. Salesforce DX is a suite of tools that facilitates a source-driven development approach, enabling developers to use scratch orgs for development and testing. With Salesforce DX, you can move metadata and code between orgs and their version control system and use packages for deploying metadata. Unlocked packages, in particular, are a part of the Salesforce DX offering and are designed to help modularize and deploy metadata and code. Salesforce DX integrates with Salesforce DevOps Center and other version control tools.

## DigitalExperienceBundle and DigitalExperienceConfig for Enhanced LWR Sites

Use the [DigitalExperienceBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_digitalexperiencebundle.htm) and DigitalExperienceConfig metadata types when you’re working with Salesforce Commerce enhanced LWR sites. These metadata types support deploying the metadata elements of a Salesforce Commerce store experience, including pages, layouts, themes, navigation menus, and site configurations.

The DigitalExperienceBundle metadata type ensures consistency and reduces the risk of manual errors during deployment. This approach offers a more controlled and reliable way to handle changes across different environments, from development to testing and production. It also supports a modern development approach that includes version control, collaborative development practices, and automated deployment pipelines.

The experience bundle metadata deployment process involves extracting the metadata from the source environment. Use Salesforce DX, Metadata API, change sets, or a third-party deployment tool, and then deploy to the target environment.

## ExperienceBundle for LWR Sites

Use the [ExperienceBundle](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_experiencebundle.htm) metadata type when you’re working with Salesforce Commerce LWR sites. The deployment process ‌involves extracting the metadata from the source org using Salesforce DX, change sets, or a third-party deployment tool, and then deploying it to the target org. Follow Salesforce’s best practices for deployment, and test thoroughly in the source org before deploying to the target org.

## DevOps Center

[DevOps Center](https://help.salesforce.com/s/articleView?id=platform.devops_center_overview.htm&type=5) is a change and release management tool. You can use deployment tools with DevOps Center to deploy metadata between Salesforce environments. With DevOps Center your developers work in a repeatable and scalable way, whether you use declarative builders or write code in Salesforce Extensions for VS Code.

These DevOps Center practices and tools are commonly used to deploy metadata in Salesforce.

- Version control systems like Git track changes in metadata and source code, allowing teams to collaborate more effectively. By using branches, tags, and commits, teams can manage development efforts and merge changes in a controlled manner.
- Continuous integration tools, such as Jenkins, Bamboo, or GitLab CI, automate testing and building metadata changes. These tools can run tests every time a change is made to the codebase, ensuring that issues are caught early.
- Continuous delivery tools automate the deployment of metadata changes to various Salesforce environments. These tools ensure that new features, bug fixes, and updates are delivered quickly and reliably.

## Third-Party Deployment Tools

Numerous third-party tools that can help with metadata deployment are available. Many third-party options also integrate with Salesforce DevOps, such as Gearset, Copado, Flosum, and AutoRABIT. These tools provide user-friendly interfaces and features to manage the deployment process effectively.

<!-- document id=97003179393d2e4bb19b0556fecb6904e9031e849f7e1f61efbeb3a4485e1a8a url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/data-exports-guide.md -->

# Data Exports

Stream or export transaction and cart data from Point of Sale to external systems for reporting, analytics, and loss prevention.

## In this section

- [Point of Sale Data Exports](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/data-exports.html)
- [Export the Transaction Log (TLog)](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-tlog.html)
- [Export Data When Suspending and Voiding Carts](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-data-when-suspending-voiding-carts.html)

<!-- document id=8b825d175f1565df99322d8504e93ba919757263a3cf2a093af1c47fe7aa2c31 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-data-loading.md -->

# Data Fetching

Storefront Next is built on [React Router](https://reactrouter.com/), leveraging its [Framework Mode](https://reactrouter.com/start/modes#framework) to provide a structured foundation for routing and data handling. As such, Storefront Next represents a **server-rendered single-page application** (SPA). This application model means that only the initial navigation request to a route is processed and responded to by the server. All subsequent client-side navigation requests are routed on the client and only trigger requests for data or additionally required assets, or both. Server-side rendering (SSR) ensures fast initial load times while client-side navigation and rendering (CSR) eliminates full page reloads after hydration, combining the strengths of SSR and CSR without their respective tradeoffs.

![Data fetching for initial and subsequent page loads](https://developer.salesforce.com/docs/media/sfnext/sfnext-data-fetching.png '{"class": "image-xl"}')

Storefront Next uses these data loading components:

- **[Loaders](#loaders):** Server-side functions that fetch data before component rendering.
- **[Actions](#actions):** Server-side functions that handle data mutations triggered by form submissions or programmatic calls.
- **[Fetchers](#fetchers):** Client-side functions that enable loading data from or submitting data to routes without causing navigation. Fetchers can call loaders (for reads) or actions (for writes) on any route, making them ideal for in-page interactions.
- **[Middlewares](#middlewares):** Functions that run in a pipeline before loaders and actions and allow intercepting navigation requests before a route renders.
- **[Cookies and Sessions](#cookies-and-sessions):** Server-side mechanisms for persisting state across requests, such as user preferences, authentication tokens, and flash messages.

## Dependencies

| Package        | Version | Purpose                                           |
| -------------- | ------- | ------------------------------------------------- |
| `react-router` | 7.18.0  | Framework mode with loaders, middlewares, actions |
| `react`        | 19.2.3  | React 19 with `use()` hook                        |

## Paradigms

### Server-Load Everything

One of the many strengths of React Router lies in its highly flexible mechanisms for controlling and calibrating data retrieval and data flows within an app. While it’s technically possible to implement complex, server/client-segregated data flows, we made the deliberate architectural decision for Storefront Next to promote a **server-load everything** paradigm.

**important:** In our proposed architecture, Managed Runtime (MRT) isn’t only used as a simple data proxy, but acts as **_the_ data orchestration layer**. Using React Router’s [server data loading](https://reactrouter.com/start/framework/data-loading#server-data-loading) functionality, we’re able to aggregate parallel and sequential SCAPI requests into a single request to MRT and progressively stream the response to the client. This ultimately means that all API requests are executed on the server (that is, MRT).

A solid understanding of this paradigm is suggested, as it directly impacts the structure and bundling of the app code, as well as overarching aspects such as performance, authentication, security, and SEO.

### Route-Level Data Fetching

In Storefront Next, we promote route-level data fetching via [loaders](#loaders), as they are the only mechanism that guarantees data is fetched before component rendering on the server.

**note:** **Component-level data fetching** (for example, [`useEffect`](https://react.dev/reference/react/useEffect) or direct [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) calls within components) isn’t recommended for initial page loads, as data is absent during SSR, resulting in degraded SEO and slower perceived performance. All of these client-side data fetching strategies should only be considered for [interaction-driven data](#interaction-driven-data) scenarios.

## Data Classification

Another pillar of an effective data fetching strategy is classifying data by its route-level relevance. This strategy requires answering three questions per route.

1. What data must be available before the route renders? (**_Blocking_** data, critical for SEO, and typically desirable for above-the-fold content.)
2. What data can be deferred? (**_Streamed_** data, below-the-fold content, but also negotiable for above-the-fold content in case of visually stable content/layouts.)
3. What data is interaction-driven? (Outside the initial data fetching lifecycle; fetched on user action.)

### Critical Data

Critical data comprises all information required to produce a complete, semantically correct, and layout-stable initial HTML response. This data includes above-the-fold content that determines [Largest Contentful Paint (LCP)](https://web.dev/articles/lcp), layout-defining attributes such as image dimensions that affect [Cumulative Layout Shift (CLS)](https://web.dev/articles/cls), and all SEO-relevant artifacts such as accurate title, meta description, canonical links, structured data, and correct HTTP status codes (for example, 200, 301, 404), and so on. It also includes any data necessary to render the correct document state for crawlers and social previews. Data is considered critical if its absence delays meaningful paint, changes initial layout, misrepresents document semantics, or produces an incorrect status code.

### Non-Critical Data

Non-critical data comprises information that doesn’t affect initial render completeness, layout stability, document semantics, or HTTP correctness. It doesn’t negatively impact loading metrics like LCP, or the visual stability of the above-the-fold structure, and isn’t required for accurate indexing or link previews. This category includes below-the-fold content, related items, recommendations, progressive personalization, analytics payloads, and enrichment UI elements. Such data can be deferred, streamed, or lazy-loaded without compromising performance metrics, crawlability, or document validity. [Learn more about visual stability here](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md).

### Interaction-Driven Data

Interaction-driven data is fetched in response to user actions, such as clicking a button, submitting a form, or triggering other UI interactions. Unlike route-level data fetching that occurs during navigation, interaction-driven data is requested after the initial page render.

**note:** The React Router framework provides [loaders](#loaders) for data fetching and [actions](#actions) for interaction-driven data mutations, with [middlewares](#middlewares) handling cross-cutting concerns (for example, authentication, logging, caching), and [fetchers](#fetchers) enabling interaction-driven data updates without navigation.

## Loaders

Loaders are exported functions in route modules that fetch data before (or during) the component tree renders.

The return value of a loader function is a record whose key–value pairs represent discrete data fragments that the route consumes. Alternatively, a `Promise` resolving to such a record can be returned. The framework transparently awaits such outer Promise.

The individual values within the returned record can themselves be either concrete values or Promises. In React Router, unresolved Promises inside the returned object are handled natively and can be consumed in combination with React [`<Suspense/>`](https://react.dev/reference/react/Suspense).

This enables fine-grained control over rendering behavior by separating:

- **Critical Data:** values awaited within the loader before returning the object.
- **Non-Critical Data:** Promises returned as values, resolved later and rendered within `<Suspense/>` boundaries.

### Loader Arguments

| Argument  | Type                  | Description                        |
| --------- | --------------------- | ---------------------------------- |
| `request` | Request               | Standard Fetch API Request object. |
| `params`  | Object                | Route parameters from URL.         |
| `context` | RouterContextProvider | Shared context from middleware.    |

### Server Loaders

While React Router also provides the concept of client loaders, we recommend the consistent use of server loaders in accordance with our server-load everything paradigm. Server loaders get invoked during server-side rendering (SSR), but also to fetch data during subsequent client-side navigation requests.

Server loaders offer several advantages and enhancements:

- **Security** can be enhanced by keeping API credentials and sensitive business logic server-side, never exposing them to the client bundle. Additionally, server loaders enable direct access to backend services, databases, and internal APIs without CORS concerns or public endpoint exposure.
- Perceived **performance** can benefit from server-side rendering as Core Web Vitals metrics like LCP (Largest Contentful Paint) and TTI (Time to Interactive) can improve significantly by delivering pre-rendered HTML. CLS (Cumulative Layout Shift) improvements require explicit layout stability measures like reserved space for dynamic content (for example, via skeletons).
- **Client bundle size** can remain minimal since data fetching code and dependencies don’t have to get shipped to the browser if kept out of the client module graph.
- **SEO** can benefit from fully-rendered HTML with data already present in the initial response, enabling bots to crawl complete content without having to execute JavaScript. Dynamic meta tags (title, description, Open Graph) can be populated with actual data, improving social sharing.

#### Example: Critical Data - Block Initial Rendering

This code example shows how to fetch all data for a specific route before the component for that route renders. It initiates two separate data fetches to external APIs using the standard fetch API. The function returns an object containing the two resolved data portions.

```typescript
// src/routes/product.$productId.tsx
import type { LoaderFunctionArgs } from "react-router";

export async function loader({ request, params, context }: LoaderFunctionArgs) {
  const { productId } = params;

  // Fetch data from two external APIs
  const productPromise = fetch(`https://api.example.com/products/${productId}`).then((r) =>
    r.json(),
  );
  const recommendationsPromise = fetch(
    `https://api.example.com/recommendations/${productId}`,
  ).then((r) => r.json());

  // Parallelize data fetching
  const [product, recommendations] = await Promise.all([productPromise, recommendationsPromise]);

  return {
    product,
    recommendations,
  };
}
```

#### Example: Critical Data - Handling 404 Responses for SEO

When a requested resource doesn’t exist, returning a proper 404 HTTP status code is critical for SEO. Search engines distinguish between valid pages and missing content to maintain accurate indexes and avoid crawl budget waste.

This code example shows how to throw a 404 response when a product isn’t found. The thrown `Response` is caught by the framework and returned with the correct HTTP status code, ensuring search engines and social media crawlers receive proper signals.

```typescript
// src/routes/product.$productId.tsx
import type { LoaderFunctionArgs } from "react-router";

export async function loader({ request, params, context }: LoaderFunctionArgs) {
  try {
    const { productId } = params;
    const product = await fetch(`https://api.example.com/products/${productId}`).then((r) =>
      r.json(),
    );
    return {
      product,
    };
  } catch {
    // Throw 404 Response if product doesn’t exist
    throw new Response("Product not found", { status: 404 });
  }
}
```

**tip:** Always throw a `Response` with a non-200 status code rather than returning error data with a 200 status code. Throwing this response ensures search engines correctly understand the page state and prevents indexing of non-existent content. The thrown `Response` will be caught and handled by the closest [`ErrorBoundary`](https://reactrouter.com/how-to/error-boundary) in your route hierarchy, enabling you to render custom 404 pages.

#### Example: Non-Critical Data - Streaming and Progressive Loading

React Router awaits route loaders before rendering route components. To unblock the loader for non-critical data, simply return a Promise instead of awaiting it in the loader.

Non-critical data enables **progressive rendering** by prioritizing above-the-fold content while deferring below-the-fold elements. This improves **perceived performance** by showing users meaningful content faster, reducing time-to-interactive. For **SEO**, critical data like product titles and descriptions are immediately available in the initial HTML, while supplementary content like reviews or recommendations can stream in afterward. This pattern optimizes the balance between fast initial page loads and comprehensive content delivery.

This code example defines a loader that demonstrates both data deferral and Promise chaining. The goal is to maximize performance by initiating fast and independent fetches immediately, while organizing dependent fetches to run as soon as their prerequisite data is available.

```typescript
// src/routes/product.$productId.tsx
import type { LoaderFunctionArgs } from "react-router";

export async function loader({ request, params, context }: LoaderFunctionArgs) {
  const { productId } = params;

  // Needs to be fast as it will both block the initial rendering and
  // is required for chained data fetching
  const product = fetch(`https://api.example.com/products/${productId}`).then((r) => r.json());

  // Dependent data requires chaining
  const category = product
    .then((product) => fetch(`https://api.example.com/categories/${product.categoryId}`))
    .then((r) => r.json());

  // Independently resolvable data
  const recommendations = fetch(`https://api.example.com/recommendations/${productId}`).then((r) =>
    r.json(),
  );

  return {
    product: await product, // <-- Critical: Await the Promise
    category, // <-- Non-Critical: Return the Promise
    recommendations, // <-- Non-Critical: Return the Promise
  };
}
```

#### Example: Consuming Loader Data

Components receive loader data and can either use React 19’s [`use()`](https://react.dev/reference/react/use) hook or React Router’s [`<Await/>`](https://reactrouter.com/api/components/Await) component to unwrap promises. This code example shows how to consume critical and non-critical data loaded by the data loader from the previous example. The component waits for the critical data to resolve, then renders the main content, for example, product name and description. Secondary data is rendered within `<Suspense>` boundaries, enabling us to influence the loading state of any promises that suspend within it.

```jsx
// src/routes/product.$productId.tsx
import { Suspense } from "react";
import Category, { CategorySkeleton } from "@/components/category";
import Recommendations, { RecommendationsSkeleton } from "@/components/recommendations";

type ProductPageData = {
  product: Product,
  category: Promise<Category>,
  recommendations: Promise<Recommendation[]>,
};

export default function ProductPage({
  loaderData: { product, category, recommendations },
}: {
  loaderData: ProductPageData,
}) {
  return (
    <>
      <h1>{product.name}</h1>
      <p>{product.description}</p>

      <Suspense fallback={<CategorySkeleton />}>
        <Category promise={category} />
      </Suspense>

      <Suspense fallback={<RecommendationsSkeleton />}>
        <Recommendations promise={recommendations} />
      </Suspense>
    </>
  );
}
```

**tip:** You can also use the [`useLoaderData`](https://reactrouter.com/api/hooks/useLoaderData) hook to retrieve the data.

```typescript
import { useLoaderData } from "react-router";

export default function ProductPage() {
  const loaderData = useLoaderData<ProductPageData>();
  // ...
}
```

For details on how loader data integrates with the broader state model, including `useLoaderData`, `useRouteLoaderData`, and middleware context as state, see [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md). For visual feedback during data loading, see [Loading States](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md).

### SCAPI Request Shape

SCAPI endpoints expose several knobs that control response size and cacheability, such as `expand`, `select`, `limit`/`offset`, and similar query parameters. Treat these as part of the loader's contract, not as defaults to copy from another route. Two side effects are easy to overlook:

**Payload size.** Every requested field crosses the network and lands in the SSR response. Over-fetching adds bytes to TTFB, inflates the streamed HTML, and increases hydration cost. Audit each loader and ask which fields the route actually renders — drop the rest.

**Cache TTL.** SCAPI caches responses per unique request URL, including the full query string. Adding or removing a parameter creates a separate cache entry. More importantly, fields with shorter TTLs (for example, real-time inventory or pricing) pull the entire cached response onto their shorter schedule when included inline. Prefer fetching short-TTL data separately via a non-critical deferred loader rather than mixing it into critical, long-cacheable payloads.

**Example (product search):** The `expand` parameter is typically the most common offender. `expand=variations,images` on a product with 50 color variants and 5 images each produces 250 image objects, and `expand=availability` shortens the cached response's effective TTL. Trim the `expand` list to what the PLP actually renders, and defer availability to a non-critical loader. The same reasoning applies to other SCAPI endpoints. See [expand Parameter Impact on Cache Hit Rates](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#expand-parameter-impact-on-cache-hit-rates).

Storefront Next uses the serialized request before per-call middleware to classify non-personalized SCAPI responses. Product and Product Search requests require an explicit list of reviewed expansions. Keep non-personalized response classification in the central server policy. Don't add `personalized=none` throughout your loaders. See [Classify Non-Personalized Responses](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md#classify-non-personalized-responses).

## Actions

Action functions handle data mutations, such as form submissions, updates, or deletions, the counterpart to loaders. While loaders handle read operations, actions handle writes. A GET/POST/PUT/DELETE distinction is a useful mental model, though React Router routes requests by navigation intent rather than HTTP method alone.

### Action Arguments

| Argument  | Type                  | Description                        |
| --------- | --------------------- | ---------------------------------- |
| `request` | Request               | Standard Fetch API Request object. |
| `params`  | Object                | Route parameters from URL.         |
| `context` | RouterContextProvider | Shared context from middleware.    |

### Server Actions

Comparable to server loaders, React Router also provides the concept of client actions. In line with our server-load everything paradigm, we recommend server actions exclusively. Server actions are functions that execute solely on the server, ensuring sensitive mutation logic, such as database writes or authentication checks, never reaches the client.

#### Action Return Pattern

Always return `data(payload, init?)` from `react-router` — never `Response.json(...)`. This:

- Preserves the HTTP status code so CDNs, server logs, and client-side `fetcher.formMethod` checks behave correctly.
- Keeps the payload type inferable, so consumers can use `useFetcher<typeof action>()` and get full type-safe access to `fetcher.data`.

Annotate every action with an explicit return type so the contract is enforced at the action definition (not just at the caller):

```typescript
import { data } from 'react-router';
import type { Route } from './+types/action.example';

/** Response shape returned by the example action. Exported so consumers can import the type. */
export type ExampleResponse = {
  success: boolean;
  error?: ActionError;
};

export async function action({
  request,
  context,
}: Route.ActionArgs): Promise<ReturnType<typeof data<ExampleResponse>>> {
  // ...
  return data({ success: true });
}
```

Consumers then bind the fetcher to the action:

```tsx
import type { action as exampleAction } from "@/routes/action.example";

const fetcher = useFetcher<typeof exampleAction>();
// fetcher.data is typed as ExampleResponse
```

For an action that may dispatch to one of several routes (for example, a single fetcher submitting to add/remove/update endpoints), use a union: `useFetcher<typeof addAction | typeof removeAction>()`.

#### Action Error Handling

Actions return structured error objects with a semantic `code` and a human-readable `message`. Use `createActionError` from `@/lib/action-error-helpers.server` to construct these consistently:

```typescript
import { data } from 'react-router';
import { createActionError } from '@/lib/action-error-helpers.server';
import { ErrorCode } from '@/lib/error-codes';

// Known validation error — provide code + message explicitly
return data(
  {
    success: false,
    error: createActionError({
      code: ErrorCode.REQUIRED_FIELD,
      message: 'Email is required',
    }),
  },
  { status: 400 },
);

// Caught exception — pass the error object directly.
// If it's an SCAPI ApiError, the code is inferred from the HTTP status
// and the message is extracted from the RFC 7807 response body.
catch (error) {
  return data(
    { success: false, error: createActionError({ error }) },
    { status: 500 },
  );
}
```

The error shape returned to consumers:

```typescript
interface ActionError {
  code: string; // Semantic error code (e.g., "NOT_FOUND", "OUT_OF_STOCK")
  message: string; // Human-readable message (English, not localized)
}
```

Available error codes are defined in `src/lib/error-codes.ts`: `NOT_FOUND`, `NOT_AUTHENTICATED`, `NOT_AUTHORIZED`, `INVALID_INPUT`, `REQUIRED_FIELD`, `CONFLICT`, `EXPIRED`, `OPERATION_FAILED`, `OUT_OF_STOCK`, `RATE_LIMITED`, `METHOD_NOT_ALLOWED`, `UNKNOWN`.

**Consumer-side handling:** The `message` field is always in English. Components should use translated strings for user-facing display and treat `code` as the dispatch mechanism:

```typescript
// Use a translated fallback for the toast — don't show error.message to users
const errorMsg = t("product:failedToAddToCart");
addToast(errorMsg, "error");

// Or interpolate error.message into a translated wrapper (for developer context)
const errorMsg = t("product:failedToAddToCart", { error: data.error?.message });
addToast(errorMsg, "error");
```

For details on how action return values integrate with the state model (optimistic UI, `fetcher.data`, `useActionState`), see [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md).

## Fetchers

Fetchers are React Router’s mechanism for triggering loaders or actions outside of navigation, enabling data fetches and mutations without changing the current route or URL. Unlike standard navigation, multiple fetchers can run concurrently and independently, each tracking their own submission state. This makes them well-suited for use cases such as inline form submissions, optimistic UI updates, or background data refreshes.

For details on how `fetcher.state` and `fetcher.data` integrate with the state model, see [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md#component-local-mutations-via-usefetcher). For visual feedback patterns based on `fetcher.state`, see [Loading States](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md#the-usefetcher-hook).

## Resource Routes

Resource routes are specialized routes that don’t render UI components but instead function as API endpoints within your app. Unlike traditional UI routes that export both a loader/action and a component, resource routes typically export only loaders, actions, or both. This makes them ideal for encapsulating server-side business logic that can be called from anywhere in your app.

Resource routes bridge the gap between loaders and actions by providing a dedicated location for reusable data operations. They leverage the same loader and action patterns you’ve learned, but organize them as callable endpoints rather than navigation destinations.

### When to use Resource Routes

Resource routes are particularly useful for:

- **Encapsulated business logic:** Complex operations that benefit from being isolated in dedicated route modules, such as basket management, wishlist operations, or multi-step workflows
- **Reusable endpoints:** Data operations that multiple components across different routes need to access without duplicating code
- **Non-navigational mutations:** Actions that modify data but shouldn’t trigger navigation, such as adding items to basket, toggling favorites, or updating preferences
- **Direct SCAPI calls:** Generic API proxy routes (for example, `resource/api/client/*`) that forward requests to SCAPI without requiring SCAPI client libraries on the client

### Defining Resource Routes

Resource routes follow the same patterns as regular routes but typically don’t export a default component. They can be prefixed with `resource/` to distinguish them from UI routes.

#### Example: Interaction-Driven Data - Basket Mutation Action

This example shows a resource route that encapsulates complex business logic for adding items to a shopping basket.

```typescript
// src/routes/resource.basket.add.ts
import type { ActionFunctionArgs } from "react-router";
import { addToBasket } from "@/lib/basket";
import { validateInventory } from "@/lib/inventory";
import { createActionError } from "@/lib/action-error-helpers.server";
import { ErrorCode } from "@/lib/error-codes";

export async function action({ request, context }: ActionFunctionArgs) {
  const formData = await request.formData();
  const productId = formData.get("productId") as string;
  const quantity = parseInt(formData.get("quantity") as string, 10);

  // Business logic: validate inventory
  const available = await validateInventory(productId, quantity);
  if (!available) {
    return Response.json(
      {
        success: false,
        error: createActionError({
          code: ErrorCode.OUT_OF_STOCK,
          message: "Insufficient inventory",
        }),
      },
      { status: 400 },
    );
  }

  try {
    // Add to basket via API
    const basket = await addToBasket(context, productId, quantity);
    return Response.json({ success: true, basket });
  } catch (error) {
    return Response.json({ success: false, error: createActionError({ error }) }, { status: 500 });
  }
}
```

```jsx
// src/components/add-to-basket-button.tsx
import { useFetcher } from "react-router";

export default function AddToBasketButton({
  productId,
  quantity,
}: {
  productId: string,
  quantity: number,
}) {
  const fetcher = useFetcher();

  const handleAddToBasket = () => {
    fetcher.submit({ productId, quantity }, { method: "post", action: "/resource/basket/add" });
  };

  return (
    <button onClick={handleAddToBasket} disabled={fetcher.state !== "idle"}>
      {fetcher.state === "submitting" ? "Adding..." : "Add to Basket"}
    </button>
  );
}
```

#### Example: Generic API Proxy Route

For direct API calls without client-side API libraries, you can use a generic proxy route pattern.

```typescript
// src/routes/resource.api.$.ts
import type { LoaderFunctionArgs } from "react-router";

// Generic proxy for GET requests to your API
export async function loader({ request, params }: LoaderFunctionArgs) {
  const apiPath = params["*"]; // Captures the wildcard path
  const url = new URL(request.url);

  // Forward to API with credentials
  const response = await fetch(`https://api.example.com/${apiPath}${url.search}`, {
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
      "Content-Type": "application/json",
    },
  });

  return response;
}

// Generic proxy for POST/PUT/DELETE requests to your API
export async function action({ request, params }: LoaderFunctionArgs) {
  const apiPath = params["*"];
  const body = await request.text();

  const response = await fetch(`https://api.example.com/${apiPath}`, {
    method: request.method,
    headers: {
      Authorization: `Bearer ${process.env.API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body,
  });

  return response;
}
```

```jsx
// src/components/product-reviews.tsx
import { useEffect } from "react";
import { useFetcher } from "react-router";

export default function ProductReviews({ productId }: { productId: string }) {
  const fetcher = useFetcher();

  useEffect(() => {
    // Load reviews on mount via generic API proxy
    fetcher.load(`/resource/api/products/${productId}/reviews`);
  }, [productId]);

  if (fetcher.state === "loading") {
    return <div>Loading reviews...</div>;
  }
  if (!fetcher.data) {
    return null;
  }
  return (
    <div>
      {fetcher.data.reviews.map((review) => (
        <div key={review.id}>{review.text}</div>
      ))}
    </div>
  );
}
```

## Middlewares

React Router middleware consists of functions that intercept navigation requests before a route renders, enabling cross-cutting concerns, such as authentication, redirects, or logging, to be applied declaratively at the routing layer, upstream of loaders and actions.

### Defining Middleware

```typescript
import type { MiddlewareFunction } from "react-router";

export const middleware: MiddlewareFunction<Response>[] = [
  loggingMiddleware,
  appConfigMiddleware,
  authMiddleware,
];

export const clientMiddleware: MiddlewareFunction<Record<string, DataStrategyResult>>[] = [
  appConfigMiddlewareClient,
  authMiddlewareClient,
  analyticsMiddlewareClient,
];
```

### Writing Middleware

This code example defines a logging middleware function named `loggingMiddleware`. It’s designed to run before any route loaders or other middleware in the chain, specifically to log request information and measure response times.

```typescript
// src/middlewares/logging.server.ts
import type { MiddlewareFunction } from "react-router";

export const loggingMiddleware: MiddlewareFunction<Response> = async ({ request }, next) => {
  // Before: Log incoming request
  const startTime = Date.now();
  const url = new URL(request.url);
  console.log(`[${request.method}] ${url.pathname}${url.search}`);

  // Execute next middleware / loader
  const response = await next();

  // After: Log response time and status
  const duration = Date.now() - startTime;
  console.log(`[${request.method}] ${url.pathname} - ${response.status} (${duration}ms)`);

  return response;
};
```

### Context System

Middlewares can store data in a shared context, which loaders and actions can access. The following code example shows this fundamental pattern. It uses the [`createContext`](https://reactrouter.com/api/utils/createContext) utility provided by React Router to establish a communication channel that bypasses global state or complex dependency injection.

```typescript
// Creating a context key
import { createContext, type LoaderFunctionArgs } from "react-router";
export const requestMetricsContext = createContext<{ startTime: number }>();

// In middleware: set context
export const loggingMiddleware: MiddlewareFunction<Response> = async ({ request }, next) => {
  context.set(requestMetricsContext, { startTime: Date.now() });
  // ...
};

// In loader: read context
export function loader({ context }: LoaderFunctionArgs) {
  const metrics = context.get(requestMetricsContext);
  // Use metrics data for performance tracking
}
```

For details on how middleware context functions as a state concept (request-scoped dependency injection vs. React Context API), see [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md#middleware-context).

## Cookies and Sessions

Cookies and sessions are React Router’s built-in mechanism for state that must persist across requests. Examples include user preferences (theme, locale, dismissed banners), shopping cart identifiers, and authentication tokens. Cookies and sessions integrate directly with the `loader`/`action` lifecycle: cookies are read from the incoming `Cookie` header in loaders and actions, and written via `Set-Cookie` response headers. Because cookies travel with every HTTP request, they’re available on the server during SSR without client-side synchronization, `localStorage` workarounds, or hydration mismatches.

### Cookies

[`createCookie`](https://reactrouter.com/explanation/sessions-and-cookies#cookies) defines a reusable, typed cookie object with sensible defaults for attributes like `httpOnly`, `sameSite`, and `maxAge`. The cookie is read in a `loader` and written in an `action`.

```typescript
// src/cookies.server.ts
import { createCookie } from "react-router";

export const userPrefs = createCookie("user-prefs", {
  path: "/",
  sameSite: "lax",
  httpOnly: true,
  secure: true,
  maxAge: 604_800, // one week
});
```

```jsx
// src/routes/home.tsx
import { type ActionFunctionArgs, data, Form, type LoaderFunctionArgs } from "react-router";
import { userPrefs } from "@/cookies.server";

export async function loader({ request }: LoaderFunctionArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const cookie = (await userPrefs.parse(cookieHeader)) || {};
  return { showBanner: cookie.showBanner ?? true };
}

export async function action({ request }: ActionFunctionArgs) {
  const cookieHeader = request.headers.get("Cookie");
  const cookie = (await userPrefs.parse(cookieHeader)) || {};
  const formData = await request.formData();

  if (formData.get("bannerVisibility") === "hidden") {
    cookie.showBanner = false;
  }

  return data({ ok: true }, { headers: { "Set-Cookie": await userPrefs.serialize(cookie) } });
}

export default function Home({ loaderData }: { loaderData: { showBanner: boolean } }) {
  return (
    <div>
      {loaderData.showBanner && (
        <div>
          <p>Don't miss our sale!</p>
          <Form method="post">
            <input type="hidden" name="bannerVisibility" value="hidden" />
            <button type="submit">Dismiss</button>
          </Form>
        </div>
      )}
      <h1>Welcome!</h1>
    </div>
  );
}
```

This pattern reads the cookie server-side in the `loader` (no `useEffect`, no SSR mismatch), writes it via the `action` with a `Set-Cookie` header, and triggers automatic revalidation so the UI reflects the new state immediately.

### Sessions

For structured, server-managed state, such as authentication tokens or multi-field user profiles, React Router provides [`createCookieSessionStorage`](https://reactrouter.com/explanation/sessions-and-cookies#sessions). A session storage object wraps cookie handling with `getSession`, `commitSession`, and `destroySession` helpers.

```typescript
// src/sessions.server.ts
import { createCookieSessionStorage } from "react-router";

type SessionData = {
  userId: string;
};

type SessionFlashData = {
  error: string;
};

export const { getSession, commitSession, destroySession } = createCookieSessionStorage<
  SessionData,
  SessionFlashData
>({
  cookie: {
    name: "__session",
    httpOnly: true,
    maxAge: 60 * 60 * 24, // 1 day
    path: "/",
    sameSite: "lax",
    secrets: ["s3cret1"],
    secure: true,
  },
});
```

```typescript
// In a loader or action
import { getSession, commitSession } from "@/sessions.server";

export async function loader({ request }: Route.LoaderArgs) {
  const session = await getSession(request.headers.get("Cookie"));
  const userId = session.get("userId");
  // ...
}

export async function action({ request }: Route.ActionArgs) {
  const session = await getSession(request.headers.get("Cookie"));
  session.set("userId", "abc123");

  return data({ ok: true }, { headers: { "Set-Cookie": await commitSession(session) } });
}
```

Sessions support flash data, values that exist only until the next read. That’s useful for one-time messages like "Login successful" or validation errors across redirects.

### Middleware Integration

Cookies and sessions combine naturally with [middleware context](#context-system). Rather than having every loader parse the session independently, a middleware can resolve the session once and inject it into the context. All downstream loaders and actions then access the pre-parsed session without repeating the boilerplate.

```typescript
// src/contexts.ts
import { createContext, type Session } from 'react-router';

type SessionData = { userId: string };
type SessionFlashData = { error: string };

export const sessionContext = createContext<Session<SessionData, SessionFlashData>>();
```

```typescript
// src/middlewares/session.server.ts
import type { MiddlewareFunction } from "react-router";
import { getSession, commitSession } from "@/sessions.server";
import { sessionContext } from "@/contexts";

export const sessionMiddleware: MiddlewareFunction<Response> = async (
  { request, context },
  next,
) => {
  const session = await getSession(request.headers.get("Cookie"));
  context.set(sessionContext, session);

  const response = await next();

  // Persist any mutations made by loaders or actions
  response.headers.append("Set-Cookie", await commitSession(session));
  return response;
};
```

```typescript
// In any loader — no cookie parsing needed
import { sessionContext } from "@/contexts";

export function loader({ context }: Route.LoaderArgs) {
  const session = context.get(sessionContext);
  const userId = session.get("userId");
  // ...
}
```

This eliminates duplicated session-parsing logic across routes and centralizes the `commitSession` call. The middleware owns the session lifecycle, loaders and actions simply read and write session data.

For details on how cookies and sessions fit into the broader state model alongside URL state, middleware context, and React primitives, see [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md#persistent-state-via-cookies-and-sessions).

## Revalidation Control

By default, React Router re-runs the loaders for every active route after a navigation or mutation. That keeps data fresh, but at scale it re-fetches data the change never touched. A route-level `shouldRevalidate` function is the opt-out. See [Revalidation Control](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/README-REVALIDATION.md) in the `storefront-next` GitHub repository for when revalidation fires, why the default over-fetches at scale, and how to gate it with `shouldRevalidate`.

<!-- document id=cf8f86a93017a000fe279e4c1099c49f58e93ef8180a26a717ebcf44e903a3fd url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-data-fetching.md -->

# Data Fetching and Loading States Differences with PWA Kit

PWA Kit follows a fetch-on-render model where hooks request data during component render and expose manual loading flags. Storefront Next follows fetch-then-render with route loaders that gather data before component rendering, enabling Suspense and streaming patterns more naturally. This moves data concerns out of presentation components and simplifies loading orchestration.

PWA Kit and Storefront Next handle loading states with different models. PWA Kit relies on manual conditional rendering, while Storefront Next uses React Suspense for declarative loading boundaries. PWA Kit’s approach gives explicit control through React Query’s `isLoading` flags and conditional rendering. Storefront Next’s Suspense-based approach keeps components focused on rendering with data while boundaries handle loading automatically. That reduces boilerplate and enables streaming, but it requires understanding Suspense patterns and React 19’s `use()` hook.

## Paradigm

| Aspect        | PWA Kit                   | Storefront Next              |
| ------------- | ------------------------- | ---------------------------- |
| Data Location | Inside components (hooks) | Outside components (loaders) |
| Discovery     | Automatic (hook scanning) | Explicit (route exports)     |

## Data Fetching

| Feature           | PWA Kit                    | Storefront Next       |
| ----------------- | -------------------------- | --------------------- |
| SSR Approach      | React Query auto-discovery | Loader functions      |
| Client Navigation | React Query refetch        | Client loader         |
| Legacy Support    | `getProps` static method   | N/A                   |
| Caching           | React Query cache          | Manual / React Router |

## Request Processing

| Feature              | PWA Kit                  | Storefront Next         |
| -------------------- | ------------------------ | ----------------------- |
| Pre-fetch Processing | Express middleware       | React Router middleware |
| Shared State         | Express `res.locals`     | Router context          |
| Request Access       | Full Express `req`/`res` | Fetch API `Request`     |

## Loading States and Suspense

| Aspect                 | PWA Kit                          | Storefront Next                           |
| ---------------------- | -------------------------------- | ----------------------------------------- |
| Approach               | Manual conditional rendering     | Declarative Suspense boundaries           |
| Loading detection      | `isLoading` flags from hooks     | `use()` hook suspends on pending promises |
| Skeleton display       | Explicit `if (isLoading)` checks | Automatic via Suspense fallback           |
| Multiple regions       | Manual state tracking per region | Multiple `<Suspense>` boundaries          |
| Navigation transitions | `keepPreviousData` option        | `getPageKey` + `shouldRevalidate`         |
| Code splitting         | `@loadable/component` fallback   | React Router automatic splitting          |
| Skeleton styling       | Chakra `<Skeleton>` component    | Tailwind `animate-pulse`                  |
| Streaming              | Limited                          | Native promise streaming                  |

### Pattern Comparison

PWA Kit — imperative:

```javascript
function ProductList() {
  const { data: products, isLoading } = useProducts();

  if (isLoading) {
    return <ProductListSkeleton />;
  }

  return products.map((p) => <ProductTile product={p} />);
}
```

Storefront Next — declarative:

```typescript
function ProductList({ loaderData }) {
  const products = use(loaderData.products);
  return products.map((p) => <ProductTile product={p} />);
}

export default createPage({
  component: ProductList,
  fallback: <ProductListSkeleton />,
});
```

### Streaming Vs Waterfall

PWA Kit can experience client-side waterfalls when data-fetching hooks depend on each other:

```javascript
// Sequential fetching
const { data: product } = useProduct({ id: productId });
const { data: category } = useCategory({ id: product?.categoryId }); // Waits for product
```

Storefront Next enables streaming where data resolves as it's ready:

```typescript
// Loader returns promises
export function loader({ params, context }) {
  const productPromise = fetchProduct(params.productId);
  const categoryPromise = productPromise.then((p) => fetchCategory(p.categoryId));

  return {
    product: productPromise,
    category: categoryPromise, // Streams after product
  };
}
```

## Key Similarities

PWA Kit and Storefront Next have these data fetching capabilities.

- Server-side rendering.
- Fetching data from any data source.
- Setting response headers.
- Middleware/pre-processing capabilities.

## Storefront Conversion Considerations

When converting your storefront from PWA Kit to Storefront Next, keep these tips in mind.

- Move data fetching to loaders: Extract `useQuery` calls into `loader` functions.
- Replace React Query: Use loader returns instead of hooks.
- Conditional rendering → Suspense: Replace `if (isLoading)` patterns with Suspense boundaries and the `createPage` factory.
- Update loading states: Replace `isLoading` conditionals with Suspense fallbacks.
- `keepPreviousData` → `shouldRevalidate`: Move “keep old data visible” logic from React Query options to router revalidation control.
- Loading spinners → skeleton fallbacks: Convert inline loading spinners to skeleton components in Suspense fallbacks.
- Multiple loading states → multiple boundaries: Split single-page loading into independent Suspense regions for granular streaming.
- Convert middleware: Express middleware becomes React Router middleware.
- Update request access: Use Fetch API `Request` instead of Express `req`.

<!-- document id=1d25407bb6a30790f37ae7936b45d4b6064365f6157f10777178d03b6d041946 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-gift-certificate-search.md -->

Data Gift Certificate Search (deprecated)

# Data Gift Certificate Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search GiftCertificates

`POST /sites/{site_id}/gift_certificate_search`

Operation ID: `Search GiftCertificates`. Tags: sites. Security: oauth2\_application.

Searches for gift certificates.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   merchant\_id - String
    
*   masked\_gift\_certificate\_code\* - String
    
*   order\_no - String
    
*   sender\_name - String
    
*   recipient\_name - String
    
*   recipient\_email - String
    
*   status - String
    
*   enabled - Boolean
    
*   message - String
    
*   description - String
    
*   creation\_date - Date
    
*   currency\_mnemonic\* - String
    

*   masked\_gift\_certificate\_code, also known as just code, can only be used in a term query. If a four-character code is supplied, it is assumed that the search is on the unmasked portion of the code, otherwise the full code must be matched. Text queries are not allowed.

*   currency\_mnemonic can only be joined with other attributes using a conjunction (AND).

Note that only searchable attributes can be used in sorting. The code attribute cannot be used for sorting.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `gift_certificate_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### gift\_certificate\_search\_result

Document representing a gift certificate search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of gift\_certificate_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 3,
  "hits": [
    {
      "amount": {
        "currency_mnemonic": "USD",
        "value": 100
      },
      "balance": {
        "currency_mnemonic": "USD",
        "value": 100
      },
      "creation_date": "2015-07-31T15:10:25.192Z",
      "description": "description",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/gift_certificates/my-merchant_id",
      "masked_gift_certificate_code": "************HHHZ",
      "merchant_id": "my-merchant_id",
      "order_no": "00000001",
      "status": "pending",
      "transactions": [
        {
          "amount": {
            "currency_mnemonic": "EUR",
            "value": 80
          },
          "order_no": "00000001",
          "timestamp": "2015-01-09T17:16:12.066Z",
          "type_code": "create"
        }
      ]
    },
    {
      "amount": {
        "currency_mnemonic": "USD",
        "value": 100
      },
      "balance": {
        "currency_mnemonic": "USD",
        "value": 100
      },
      "creation_date": "2015-07-31T15:03:24.188Z",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/gift_certificates/my-merchant_id",
      "masked_gift_certificate_code": "************DOIZ",
      "merchant_id": "my-merchant_id",
      "order_no": "00000002",
      "status": "pending",
      "transactions": [
        {
          "amount": {
            "currency_mnemonic": "EUR",
            "value": 80
          },
          "order_no": "00000002",
          "timestamp": "2015-02-09T17:16:12.066Z",
          "type_code": "create"
        }
      ]
    },
    {
      "amount": {
        "currency_mnemonic": "USD",
        "value": 100
      },
      "balance": {
        "currency_mnemonic": "USD",
        "value": 100
      },
      "creation_date": "2015-07-31T15:10:00.659Z",
      "description": "description",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/gift_certificates/my-merchant_id",
      "masked_gift_certificate_code": "************GSPZ",
      "merchant_id": "my-merchant_id",
      "order_no": "00000003",
      "status": "pending",
      "transactions": [
        {
          "amount": {
            "currency_mnemonic": "EUR",
            "value": 80
          },
          "order_no": "00000003",
          "timestamp": "2015-09-09T17:16:12.066Z",
          "type_code": "create"
        }
      ]
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "status"
      ],
      "search_phrase": "pending"
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 3
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### gift\_certificate

Document representing a gift certificate

*   `amount` (_money_) The gift certificate amount. The user cannot change the gift certificate amount after the creation of the gift certificate.
*   `balance` (_money_) The gift certificate balance. This is a computed attribute and cannot be modified.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description of the gift certificate.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag of the gift certificate.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The URL to get the gift certificate. This is a computed attribute and cannot be modified.
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code with all but the last 4 characters replaced with a '\*' character. This is a computed attribute and cannot be modified.
*   `merchant_id` (_string_) The merchant ID of the gift certificate. This is a unique attribute. This is a computed attribute and cannot be modified. This is used to get, update and the delete gift certificates.
*   `message` (_string_) The message to the recipient of the gift certificate.  
    Maximum length: 4000.
*   `order_no` (_string_) The order number of the gift certificate.
*   `recipient_email` (_string_) The email address of the recipient of the gift certificate.
*   `recipient_name` (_string_) The recipient of the gift certificate.  
    Maximum length: 256.
*   `sender_name` (_string_) The sender of the gift certificate.  
    Maximum length: 256.
*   `status` (_string_) The status of the gift certificate. While creating a gift certificate, user can set the status to either "pending" or "issued" only.  
    Allowed values: `issued`, `partially_redeemed`, `pending`, `redeemed`.
*   `transactions` (_array of account\_transaction_) The transactions of the gift certificate. This attribute is only available as part of the response.

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### money

*   `currency_mnemonic` (_string_) The mnemonic for the money.
*   `value` (_number (double)_) The value for the money.

_Example_

```
{
  "currency_mnemonic": "USD",
  "value": 100
}
```

### account\_transaction

Document representing an account transaction

*   `amount` (_money_) The amount of the gift certificate
*   `order_no` (_string_) The order number of the gift certificate
*   `timestamp` (_string (date-time)_) The timestamp of the transaction of the gift certificate
*   `type_code` (_string_) The type code of the gift certificate  
    Allowed values: `create`, `redeem`, `delete`, `enable`, `disable`.

_Example_

```
{
  "amount": {
    "currency_mnemonic": "EUR",
    "value": 80
  },
  "order_no": "my-order_no",
  "timestamp": "2015-09-09T17:16:12.066Z",
  "type_code": "create"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=d0138f3586fb9792ade0281adccd4c6f0be69c1fc24356ff4499ee42c8e06402 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-gift-certificates.md -->

Data Gift Certificates (deprecated)

# Data Gift Certificates (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get GiftCertificates

`GET /sites/{site_id}/gift_certificates`

Operation ID: `Get GiftCertificates`. Tags: sites. Security: oauth2\_application.

Action to get all the gift certificates with no filtering.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `gift_certificates`.
    

### POST Create GiftCertificate

`POST /sites/{site_id}/gift_certificates`

Operation ID: `Create GiftCertificate`. Tags: sites. Security: oauth2\_application.

Creates a gift certificate using the information provided.

This endpoint may return the following faults:

*   400 - GiftCertificateAmountOutOfRangeException - If the amount specified is out of range
*   400 - GiftCertificateCreateMerchantIDNotUniqueException - If merchant id is not unique
*   400 - InvalidGiftCertificateException - if the gift certificate passed in is not valid (the argument indicates the field that was invalid).
*   400 - InvalidGiftCertificateStatusException - If gift certificate status specified is invalid
*   400 - InvalidRecipientEmailException - If recipient email address is invalid

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `gift_certificate`.

#### Responses

*   **400** `GiftCertificateAmountOutOfRangeException` - If the amount specified is out of range or `GiftCertificateCreateMerchantIDNotUniqueException` - If merchant id is not unique or `InvalidGiftCertificateException` - if the gift certificate passed in is not valid (the argument indicates the field that was invalid). or `InvalidGiftCertificateStatusException` - If gift certificate status specified is invalid or `InvalidRecipientEmailException` - If recipient email address is invalid
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `gift_certificate`.
    

### GET Get GiftCertificate

`GET /sites/{site_id}/gift_certificates/{merchant_id}`

Operation ID: `Get GiftCertificate`. Tags: sites. Security: oauth2\_application.

Action to get gift certificate information using merchant ID.

This endpoint may return the following faults:

*   404 - GiftCertificateNotFoundException - Thrown in case the gift certificate does not exist matching the given merchant id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `merchant_id` (path, string, required) The merchant id of the requested gift certificate.  
    Minimum length: 1.

#### Responses

*   **404** `GiftCertificateNotFoundException` - Thrown in case the gift certificate does not exist matching the given merchant id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `gift_certificate`.
    

### DELETE Delete GiftCertificates

`DELETE /sites/{site_id}/gift_certificates/{merchant_id}`

Operation ID: `Delete GiftCertificates`. Tags: sites. Security: oauth2\_application.

Deletes the gift certificate by merchant ID

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `merchant_id` (path, string, required) One gift certificate merchant id to remove

#### Responses

*   **204**

### PATCH Update GiftCertificate

`PATCH /sites/{site_id}/gift_certificates/{merchant_id}`

Operation ID: `Update GiftCertificate`. Tags: sites. Security: oauth2\_application.

Updates the gift certificate with the specified information using merchant ID.

This API can not operate on the transactions attribute of the GiftCertificate request object.

This endpoint may return the following faults:

*   400 - InvalidGiftCertificateStatusException - If gift certificate status specified is invalid
*   400 - InvalidRecipientEmailException - If recipient email address is invalid
*   404 - GiftCertificateNotFoundException - Thrown in case the gift certificate does not exist matching the given merchant id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `merchant_id` (path, string, required) The merchant id of the requested gift certificate.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `gift_certificate`.

#### Responses

*   **400** `InvalidGiftCertificateStatusException` - If gift certificate status specified is invalid or `InvalidRecipientEmailException` - If recipient email address is invalid
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `GiftCertificateNotFoundException` - Thrown in case the gift certificate does not exist matching the given merchant id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `gift_certificate`.
    

## Schemas

### gift\_certificates

Document representing an unfiltered list of gift certificates.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of gift\_certificate_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### gift\_certificate

Document representing a gift certificate

*   `amount` (_money_) The gift certificate amount. The user cannot change the gift certificate amount after the creation of the gift certificate.
*   `balance` (_money_) The gift certificate balance. This is a computed attribute and cannot be modified.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description of the gift certificate.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag of the gift certificate.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The URL to get the gift certificate. This is a computed attribute and cannot be modified.
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code with all but the last 4 characters replaced with a '\*' character. This is a computed attribute and cannot be modified.
*   `merchant_id` (_string_) The merchant ID of the gift certificate. This is a unique attribute. This is a computed attribute and cannot be modified. This is used to get, update and the delete gift certificates.
*   `message` (_string_) The message to the recipient of the gift certificate.  
    Maximum length: 4000.
*   `order_no` (_string_) The order number of the gift certificate.
*   `recipient_email` (_string_) The email address of the recipient of the gift certificate.
*   `recipient_name` (_string_) The recipient of the gift certificate.  
    Maximum length: 256.
*   `sender_name` (_string_) The sender of the gift certificate.  
    Maximum length: 256.
*   `status` (_string_) The status of the gift certificate. While creating a gift certificate, user can set the status to either "pending" or "issued" only.  
    Allowed values: `issued`, `partially_redeemed`, `pending`, `redeemed`.
*   `transactions` (_array of account\_transaction_) The transactions of the gift certificate. This attribute is only available as part of the response.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### money

*   `currency_mnemonic` (_string_) The mnemonic for the money.
*   `value` (_number (double)_) The value for the money.

_Example_

```
{
  "currency_mnemonic": "USD",
  "value": 100
}
```

### account\_transaction

Document representing an account transaction

*   `amount` (_money_) The amount of the gift certificate
*   `order_no` (_string_) The order number of the gift certificate
*   `timestamp` (_string (date-time)_) The timestamp of the transaction of the gift certificate
*   `type_code` (_string_) The type code of the gift certificate  
    Allowed values: `create`, `redeem`, `delete`, `enable`, `disable`.

_Example_

```
{
  "amount": {
    "currency_mnemonic": "EUR",
    "value": 80
  },
  "order_no": "my-order_no",
  "timestamp": "2015-09-09T17:16:12.066Z",
  "type_code": "create"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=3f2393d60e7756ac509e26d6ec0119b484f314d70b5390c78ab1679da06b0a31 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-global-custom-objects.md -->

Data Global Custom Objects (deprecated)

# Data Global Custom Objects (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Read global Custom Object

`GET /custom_objects/{object_type}/{key}`

Operation ID: `Read global Custom Object`. Tags: custom\_objects. Security: oauth2\_application.

Reads a global Custom Object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID
*   404 - CustomObjectNotFoundException - For an unknown object key

#### Parameters

*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Responses

*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID or `CustomObjectNotFoundException` - For an unknown object key
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object`.
    

### PUT Create global Custom Object

`PUT /custom_objects/{object_type}/{key}`

Operation ID: `Create global Custom Object`. Tags: custom\_objects. Security: oauth2\_application.

Creates a global Custom Object from the request body. Note that an existing global Custom Object with the same key is overwritten by this action.

Use Custom Properties prefixed with `c_` to define the Custom Object fields.  
For localizable strings, structure the field to support multiple language values by using a map where each locale, for example: en\_US, fr\_FR, has its corresponding string value.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID
*   404 - CustomObjectNotFoundException - For an unknown object key

#### Parameters

*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `custom_object`.

#### Responses

*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID or `CustomObjectNotFoundException` - For an unknown object key
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object`.
    

### DELETE Delete global Custom Object

`DELETE /custom_objects/{object_type}/{key}`

Operation ID: `Delete global Custom Object`. Tags: custom\_objects. Security: oauth2\_application.

Deletes a global Custom Object. If the Custom Object does not exist, this will do nothing. Note that the customization scripts are only called, if the Custom Object does exist.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID

#### Parameters

*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update global Custom Object

`PATCH /custom_objects/{object_type}/{key}`

Operation ID: `Update global Custom Object`. Tags: custom\_objects. Security: oauth2\_application.

Updates a global Custom Object with information from the request body. Note that only provided attributes are updated and that the key attribute is ignored. All other attributes are unchanged.

Use Custom Properties prefixed with `c_` to define the Custom Object fields.  
For localizable strings, structure the field to support multiple language values by using a map where each locale, for example: en\_US, fr\_FR, has its corresponding string value.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - ObjectTypeNotFoundException - For an unknown object type ID
*   404 - CustomObjectNotFoundException - For an unknown object key

#### Parameters

*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the Custom Object  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `custom_object`.

#### Responses

*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - For an unknown object type ID or `CustomObjectNotFoundException` - For an unknown object key
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object`.
    

### POST Search custom objects

`POST /custom_objects_search/{object_type}`

Operation ID: `Search custom objects`. Tags: custom\_objects\_search. Security: oauth2\_application.

Search resource for custom objects in scope of a specific custom object type.

The custom object search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   key\_value\_string - String
    
*   key\_value\_integer - Integer
    
*   creation\_date - Date
    
*   last\_modified - Date
    
*   site\_id - String
    
*   any custom attribute
    

Note that only searchable attributes can be used in sorting.

This endpoint may return the following faults:

*   400 - TypeMissmatchException - Indicates that the value to search with does not match the type of the search field.
*   404 - ObjectTypeNotFoundException - In case of an unknown object type.

#### Parameters

*   `object_type` (path, string, required) ID of the object type to search objects for  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `TypeMissmatchException` - Indicates that the value to search with does not match the type of the search field.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - In case of an unknown object type.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object_search_result`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### custom\_object

Document representing a custom object that contains all defined custom attributes for its object type.

*   `key_property` (_string_) The name of the key property for the custom object. This is ignored in input documents.
*   `key_value_integer` (_integer (int32)_) The id of the custom object when the type of the key is Integer. This is ignored in input documents.
*   `key_value_string` (_string_) The id of the custom object when the type of the key is String. This is ignored in input documents.
*   `object_type` (_string_) The id of the object type. This is ignored in input documents.

_Example_

```
{
  "key_property": "key_attribute",
  "object_type": "my_object_type",
  "c_boolean": true,
  "c_date": "2015-02-03T00:00:00.000Z",
  "c_email": "jdoe@salesforce.com",
  "c_integer": 42,
  "c_number": 42,
  "c_string": "some text"
}
```

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### custom\_object\_search\_result

Document representing a custom object search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of custom\_object_) The sorted array of search hits. May be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "key_property": "key_attribute",
      "key_value_integer": 1,
      "object_type": "my_object_type",
      "c_boolean": true,
      "c_date": "2015-02-03T00:00:00.000Z",
      "c_email": "jdoe@salesforce.com",
      "c_integer": 42,
      "c_number": 42,
      "c_string": "some text"
    }
  ],
  "query": {
    "bool_query": {
      "must": [
        {
          "term_query": {
            "fields": [
              "site_id"
            ],
            "operator": "is",
            "values": [
              "SiteGenesis"
            ]
          }
        },
        {
          "term_query": {
            "fields": [
              "c_number"
            ],
            "operator": "is",
            "values": [
              42
            ]
          }
        }
      ]
    }
  },
  "select": "(**)",
  "start": 2,
  "total": 4
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=979d90d2f5db1e18716b4a96043fbe49066de6bbae32ad55e24fdfced42a784b url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-global-locale-info.md -->

Data Global Locale Info (deprecated)

# Data Global Locale Info (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Locales

`GET /locale_info/locales`

Operation ID: `Get Locales`. Tags: locale\_info. Security: oauth2\_application.

Action to get the set of active locales for which the user has read or write permission.

#### Parameters

*   `id` (query, string) optional locale to return by id. If specified, that locale is looked up and returned, otherwise the list is returned.
*   `select` (query, string) the set of fields to return from the request. Default is only the locale id.
*   `start` (query, integer (int32)) the start index for paging. Default is 0.
*   `count` (query, integer (int32)) the count of the records to return in this page. Default is 25.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `locale_result`.
    

## Schemas

### locale\_result

Contains the result of getting the system locales.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object_)
*   `hits` (_array of locale_) The locales found by the request
*   `id` (_string_) The input locale (none specifies get all locales)
*   `include_all` (_boolean_) True to get the all the hits for all the locales, not just the active allowed ones
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The string describing the set of fields to return in the result.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 4,
  "hits": [
    {
      "active": true,
      "country": "",
      "default": true,
      "display_country": "",
      "display_language": "",
      "display_name": "default",
      "id": "default",
      "iso3_country": "",
      "iso3_language": "",
      "language": "",
      "name": "default"
    },
    {
      "active": true,
      "country": "",
      "default": false,
      "display_country": "",
      "display_language": "español",
      "display_name": "español",
      "id": "es",
      "iso3_country": "",
      "iso3_language": "spa",
      "language": "es",
      "name": "Spanish"
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 4
}
```

### locale

Document that describes a single locale.

*   `active` (_boolean_) Flag that is true if the locale is currently active in the system.
*   `country` (_string_) The uppercase ISO 3166 2-letter country/region code for this Locale. If no country has been specified for this Locale, this value is an empty string.
*   `default` (_boolean_) Flag that is true if the locale is the default one to use if an explicit locale is not specified.
*   `display_country` (_string_) The display name of this Locale's country, in this Locale's language, not in the session locale's language. If no country has been specified for this Locale, this value is an empty string.
*   `display_language` (_string_) The display name of this Locale's language, in this Locale's language, not in the session locale's language. If no country has been specified for this Locale, this value is an empty string.
*   `display_name` (_string_) The display name of this Locale, in this Locale's language, not in the session locale's language. If no display name has been specified for this Locale, this value is an empty string.
*   `id` (_string_)
    
    Returns the String representation of the localeID.
    
    Combines the language and the country key, concatenated with "-". For example: "en-US". This attribute is the primary key of the class.
    
*   `iso3_country` (_string_) The uppercase ISO 3166 3-letter country/region code for this Locale. If no country has been specified for this Locale, this value is an empty string.
*   `iso3_language` (_string_) The 3-letter ISO 639 language code for this Locale. If no language has been specified for this Locale, this value is an empty string.
*   `language` (_string_) The lowercase ISO 639 language code for this Locale. If no language has been specified for this Locale, this value is an empty string.
*   `name` (_string_) The display name of the Locale. Uses the current request locale to localize the value.

_Example_

```
{
  "active": true,
  "country": "",
  "default": false,
  "display_country": "",
  "display_language": "español",
  "display_name": "español",
  "id": "es",
  "iso3_country": "",
  "iso3_language": "spa",
  "language": "es",
  "name": "Spanish"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=1e6c5a4036da77a127128450e917d4996699dc5f52c7ec3aafaff52f07445219 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-global-preferences.md -->

Data Global Preferences (deprecated)

# Data Global Preferences (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Custom Preferences

`GET /global_preferences/preference_groups/{group_id}/{instance_type}`

Operation ID: `Get Custom Preferences`. Tags: global\_preferences. Security: oauth2\_application.

For the specified instance, read the custom preferences in the preference group at the global(organization) level. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.

Note: If instance type sandbox is used, the preference values of development instance type will be returned as fallback.

This endpoint may return the following faults:

*   404 - CustomPreferenceGroupNotFoundException - Indicates the preference group is not found.

#### Parameters

*   `instance_type` (path, string, required) One of {staging,development,sandbox,production,current}.
*   `group_id` (path, string, required) The ID of the preference group.
*   `mask_passwords` (query, boolean) Set to true to mask the values of preferences of type Password.
*   `expand` (query, array of string) The expansion "sites" retrieves the custom preferences in the preference group for all the available sites.

#### Responses

*   **404** `CustomPreferenceGroupNotFoundException` - Indicates the preference group is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `organization_preferences`.
    

### PATCH Update Custom Preferences

`PATCH /global_preferences/preference_groups/{group_id}/{instance_type}`

Operation ID: `Update Custom Preferences`. Tags: global\_preferences. Security: oauth2\_application.

For the specified instance, update one or more custom preferences in the preference group at the global(organization) level.

Note: If instance type sandbox is used, the preference values of development instance type will be returned as fallback.

This endpoint may return the following faults:

*   404 - CustomPreferenceGroupNotFoundException - Indicates the preference group is not found.

#### Parameters

*   `instance_type` (path, string, required) One of {staging,development,sandbox,production}.
*   `group_id` (path, string, required) The ID of the preference group.
*   `mask_passwords` (query, boolean) Set to true to mask the values of preferences of type Password.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `organization_preferences`.

#### Responses

*   **404** `CustomPreferenceGroupNotFoundException` - Indicates the preference group is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `organization_preferences`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### organization\_preferences

Represents a set of preferences attached at the organization level.

*   `link` (_string_) A URL that returns the full details for a custom preference
*   `site_preferences` (_array of site\_preferences_) The list of site preferences, returned with expand=sites

_Example_

```
{
  "link": "https://example.com/s/-/dw/data/{version}/global_preferences/preference_groups/my-preferencegroup/staging",
  "site_preferences": [
    {
      "link": "https://example.com/s/-/dw/data/{version}/sites/Site1/site_preferences/preference_groups/my-preferencegroup/staging",
      "site": {
        "id": "Site1",
        "in_deletion": false,
        "link": "https://example.com/s/-/dw/data/{version}/sites/Site1",
        "storefront_status": "online"
      },
      "c_preference1": "Blue",
      "c_preference2": [
        "Small",
        "Medium"
      ],
      "c_preference3": true,
      "c_preference4": 11
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/sites/Site2/site_preferences/preference_groups/my-preferencegroup/staging",
      "site": {
        "id": "Site1",
        "in_deletion": false,
        "link": "https://example.com/s/-/dw/data/{version}/sites/Site1",
        "storefront_status": "online"
      },
      "c_preference1": "Green"
    }
  ],
  "c_preference1": "Red",
  "c_preference2": [
    "Small",
    "Large"
  ],
  "c_preference3": true,
  "c_preference4": 10
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### site\_preferences

Represents a set of preferences attached at the organization level.

*   `link` (_string_) A URL that returns the full details for a custom preference
*   `site` (_site_) The site that contains the preferences

_Example_

```
{
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/site_preferences/preference_groups/MyPreferenceGroup/staging",
  "site": {
    "customer_list_link": {
      "customer_list_id": "SiteGenesis",
      "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
    },
    "display_name": {
      "default": "SiteGenesis"
    },
    "id": "SiteGenesis",
    "in_deletion": false,
    "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
    "storefront_status": "online"
  }
}
```

### site

Document representing a site.

*   `cartridges` (_string_) The cartridge Path of the site
*   `creation_date` (_string (date-time)_)
*   `customer_list_link` (_customer\_list\_link_) The link to the customer list.
*   `description` (_object (localized)_) The description of this site.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name entered by the user.
    
    Additional properties: `string`.
    
*   `id` (_string_, required) The id of this site.  
    Minimum length: 1.
*   `in_deletion` (_boolean_) The deletion status of this site, true if in deletion
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link directly to the site
*   `storefront_status` (_string_)  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`.

_Example_

```
{
  "customer_list_link": {
    "customer_list_id": "SiteGenesis",
    "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
  },
  "description": {
    "default": "Prototypical site used for starting point"
  },
  "display_name": {
    "default": "Site Genesis"
  },
  "id": "SiteGenesis",
  "in_deletion": false,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
  "storefront_status": "online"
}
```

### customer\_list\_link

Document representing a link to a customer list.

*   `customer_list_id` (_string_) The customerlist id.
*   `link` (_string_) The target of the link.
*   `title` (_object (localized)_) The link title.
    
    Additional properties: `string`.
    

_Example_

```
{
  "customer_list_id": "SiteGenesis",
  "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
}
```

<!-- document id=e5e50ab573201572a173b3b6719d9cf7968eb556d4739f1d3517fa9d6d66b11a url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-global-site-preferences.md -->

Data Global Site Preferences (deprecated)

# Data Global Site Preferences (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Preferences

`POST /site_preferences/preference_groups/{group_id}/{instance_type}/preference_search`

Operation ID: `Search Preferences`. Tags: site\_preferences. Security: oauth2\_application.

Search preferences across sites in the specified preference group and instance.

The query attribute specifies a complex query that can be used to narrow down the search.

The following is a list of searchable fields:

*   id - String
    
*   display\_name - Localized String
    
*   description - Localized String
    
*   value\_type\* - one of {string, int, double, text, html, date, image, boolean, money, quantity, datetime, email, password, set\_of\_string, set\_of\_int, set\_of\_double, enum\_of\_string, enum\_of\_int}
    

*   value\_type can only be joined with other attributes using a conjunction (AND).

Note that only searchable attributes can be used in sorting.

Note: If instance type sandbox is used, the preference values of development instance type will be returned as fallback.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Indicates the query is ill-formed.
*   404 - CustomPreferenceGroupNotFoundException - Indicates the preference group is not found.

#### Parameters

*   `instance_type` (path, string, required) An instance type, one of {staging,development,sandbox,production}.
*   `group_id` (path, string, required) The ID of the preference group.
*   `mask_passwords` (query, boolean) The preference values of type Password are masked when set.
*   `expand` (query, array of string) The expand "value" is available to retrieve value definitions of the attribute definition.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Indicates the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomPreferenceGroupNotFoundException` - Indicates the preference group is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `preference_value_search_result`.
    

### GET Get Preference

`GET /site_preferences/preference_groups/{group_id}/{instance_type}/preferences/{preference_id}`

Operation ID: `Get Preference`. Tags: site\_preferences. Security: oauth2\_application.

Get a preference across sites in the specified preference group and instance.

Note: If instance type sandbox is used, the preference values of development instance type will be returned as fallback.

This endpoint may return the following faults:

*   404 - CustomPreferenceGroupNotFoundException - Indicates the preference group is not found.
*   404 - PreferenceNotFoundException - Indicates the preference is not found.

#### Parameters

*   `instance_type` (path, string, required) An instance type, one of {staging,development,sandbox,production}.
*   `group_id` (path, string, required) The ID of the preference group.
*   `preference_id` (path, string, required) The ID of the preference to retrieve.  
    Minimum length: 1.
*   `mask_passwords` (query, boolean) The preference values of type Password are masked when set.

#### Responses

*   **404** `CustomPreferenceGroupNotFoundException` - Indicates the preference group is not found. or `PreferenceNotFoundException` - Indicates the preference is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `preference_value`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### preference\_value\_search\_result

Document representing a preference value search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of preference\_value_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "attribute_definition": {
        "description": {
          "default": "Enum Of String Attribute"
        },
        "display_name": {
          "default": "Enum Of String Attribute"
        },
        "effective_id": "c_EnumOfStringAttr",
        "externally_defined": false,
        "externally_managed": false,
        "id": "EnumOfStringAttr",
        "key": false,
        "link": "https://example.com/s/-/dw/data/{version}/system_object_definitions/SitePreferences/attribute_definitions/EnumOfStringAttr",
        "localizable": false,
        "mandatory": false,
        "min_length": 0,
        "multi_value_type": false,
        "order_required": false,
        "queryable": true,
        "read_only": false,
        "requires_encoding": false,
        "searchable": false,
        "set_value_type": false,
        "site_specific": false,
        "system": false,
        "value_definitions": [
          {
            "display_value": {
              "default": "Enum Of String Value 1"
            },
            "id": "EnumOfStringValue1",
            "position": 0,
            "value": "EnumOfStringValue1"
          },
          {
            "display_value": {
              "default": "Enum Of String Value 2"
            },
            "id": "EnumOfStringValue2",
            "position": 1,
            "value": "EnumOfStringValue2"
          },
          {
            "display_value": {
              "default": "Enum Of String Value 3"
            },
            "id": "EnumOfStringValue3",
            "position": 2,
            "value": "EnumOfStringValue3"
          }
        ],
        "value_type": "enum_of_string",
        "visible": false
      },
      "id": "EnumOfStringAttr",
      "site_values": {
        "SiteGenesis": "EnumOfStringValue1",
        "SiteGenesis-Customization": "EnumOfStringValue2"
      }
    }
  ],
  "query": {
    "bool_query": {
      "must": [
        {
          "text_query": {
            "fields": [
              "id"
            ],
            "search_phrase": "EnumOfStringAttr"
          }
        }
      ]
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 1
}
```

### preference\_value

Represents a single preference value

*   `attribute_definition` (_object\_attribute\_definition_) The attribute definition for this preference
*   `description` (_object (localized)_) Description of the attribute
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) Display name for the attribute
    
    Additional properties: `string`.
    
*   `id` (_string_) The id of the attribute
*   `site_values` (_object_) The value of this attribute
    
    Additional properties: `object`.
    
*   `value_type` (_string_) The type of this attribute.  
    Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `image`, `boolean`, `money`, `quantity`, `datetime`, `email`, `password`, `set_of_string`, `set_of_int`, `set_of_double`, `enum_of_string`, `enum_of_int`, `unknown`.

_Example_

```
{
  "attribute_definition": {
    "description": {
      "default": "Enum Of String Attribute"
    },
    "display_name": {
      "default": "Enum Of String Attribute"
    },
    "effective_id": "c_EnumOfStringAttr",
    "externally_defined": false,
    "externally_managed": false,
    "id": "EnumOfStringAttr",
    "key": false,
    "link": "https://example.com/s/-/dw/data/{version}/system_object_definitions/SitePreferences/attribute_definitions/EnumOfStringAttr",
    "localizable": false,
    "mandatory": false,
    "min_length": 0,
    "multi_value_type": false,
    "order_required": false,
    "queryable": true,
    "read_only": false,
    "requires_encoding": false,
    "searchable": false,
    "set_value_type": false,
    "site_specific": false,
    "system": false,
    "value_definitions": [
      {
        "display_value": {
          "default": "Enum Of String Value 1"
        },
        "id": "EnumOfStringValue1",
        "position": 0,
        "value": "EnumOfStringValue1"
      },
      {
        "display_value": {
          "default": "Enum Of String Value 2"
        },
        "id": "EnumOfStringValue2",
        "position": 1,
        "value": "EnumOfStringValue2"
      },
      {
        "display_value": {
          "default": "Enum Of String Value 3"
        },
        "id": "EnumOfStringValue3",
        "position": 2,
        "value": "EnumOfStringValue3"
      }
    ],
    "value_type": "enum_of_string",
    "visible": false
  },
  "id": "EnumOfStringAttr",
  "site_values": {
    "SiteGenesis": "EnumOfStringValue1",
    "SiteGenesis-Customization": "EnumOfStringValue2"
  }
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### object\_attribute\_definition

Document representing a attribute definition

*   `creation_date` (_string (date-time)_)
*   `default_value` (_object\_attribute\_value\_definition_) The default value of this attribute. It can be updated, but not created.
*   `description` (_object (localized)_) The localized description of the attribute.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The localized name presented to the user in forms.
    
    Additional properties: `string`.
    
*   `effective_id` (_string_) The effective ID, which is c\_id if the attribute is custom, and just the id otherwise. It is read only.
*   `externally_defined` (_boolean_) Flag indicating if this attribute is externally defined.
*   `externally_managed` (_boolean_) Flag indicating if this attribute is externally managed.
*   `field_height` (_integer (int32)_) The height of the field for this attribute in the editor.
*   `field_length` (_integer (int32)_) The length of the field for this attribute in the editor.
*   `id` (_string_) The user supplied ID of the attribute.
*   `key` (_boolean_) Flag indicating if this is a key attribute.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL that is used to get this instance. Value is computed and read-only.
*   `localizable` (_boolean_) Flag indicating if this attribute can be localized.
*   `mandatory` (_boolean_) Flag indicating if a value is mandatory for the attribute.
*   `max_value` (_number (double)_) The maximum possible value for this attribute.
*   `min_length` (_integer (int32)_) The minimum length of the field for this attribute.
*   `min_value` (_number (double)_) The minimum possible value for this attribute.
*   `multi_value_type` (_boolean_)
    
    True if the attribute can have multiple values.
    
    Attributes of the following types are multi-value capable:
    
    *   set\_of\_int
        
    *   set\_of\_number
        
    *   set\_of\_string
        
    
    Additionally, attributes of the following types can be multi-value enabled:
    
    *   enum\_of\_int
        
    *   enum\_of\_string
        
*   `order_required` (_boolean_) Flag indicating if this attribute is required for order of the attribute model's product. The set of these can be used in order line items.
*   `queryable` (_boolean_) Returns true if the attribute definition is explicitly marked queryable. If no explicit queryable is found and the attribute value type belongs to a queryable type, true is returned too. In all other cases false is returned. Value is computed and read-only.
*   `read_only` (_boolean_) Flag indicating if this attribute is read-only. It is read only.
*   `regular_expression` (_string_) A regular expression that defines the legal values for this attribute.
*   `requires_encoding` (_boolean_) Flag indicating if this attribute can be encoded using the encoding="off" flag in ISML templates. It is read only.
*   `scale` (_integer (int32)_) The minimum number of fraction digits for a value of this attribute.
*   `searchable` (_boolean_) Flag indicating if this attribute is searchable.
*   `set_value_type` (_boolean_) Flag indicating if this attribute is of type 'Set of'. It is read only.
*   `site_specific` (_boolean_) Flag indicating if this attribute is site-specific.
*   `system` (_boolean_) Flag indicating if this attribute is a system attribute.
*   `unit` (_object (localized)_) The unit of measure for this attribute.
    
    Additional properties: `string`.
    
*   `value_definitions` (_array of object\_attribute\_value\_definition_) A set of values that are possible for this attribute. It is read only.
*   `value_type` (_string_) The type of this attribute.  
    Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `image`, `boolean`, `money`, `quantity`, `datetime`, `email`, `password`, `set_of_string`, `set_of_int`, `set_of_double`, `enum_of_string`, `enum_of_int`, `unknown`.
*   `visible` (_boolean_) Flag indicating if this attribute is visible.

_Example_

```
{
  "description": {
    "default": "Description",
    "es": "mia description"
  },
  "display_name": {
    "default": "default name",
    "es": "nombre"
  },
  "id": "MyAttributeDefinition",
  "key": false,
  "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_definitions/MyAttributeDefinition",
  "localizable": true,
  "mandatory": false,
  "queryable": true,
  "searchable": false,
  "site_specific": false,
  "system": false,
  "value_type": "string",
  "visible": false
}
```

### object\_attribute\_value\_definition

Document representing a attribute definition

*   `description` (_object (localized)_) A description of the attribute value.
    
    Additional properties: `string`.
    
*   `display_value` (_object (localized)_) A display name that can be used to present this value in the user interface. For example, the value might be '1' but the display name might be 'Order Exported'.
    
    Additional properties: `string`.
    
*   `id` (_string_) The ID of the attribute value.
*   `position` (_number (double)_) The position of the attribute value within the set of attribute values.
*   `value` (_object_) The value of the attribute.

_Example_

```
{
  "display_value": {
    "default": "Enum Of String Value 1"
  },
  "id": "EnumOfStringValue1",
  "position": 0,
  "value": "EnumOfStringValue1"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=6ca19319f1780666474d197ca4ac0a38cba1049c95ef4c471be68f820b1f429b url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-inventory-list-search.md -->

Data Inventory List Search (deprecated)

# Data Inventory List Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Inventory Lists

`POST /inventory_list_search`

Operation ID: `Search Inventory Lists`. Tags: inventory\_list\_search. Security: oauth2\_application.

Searches for inventory lists.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   id - String
    
*   default\_in\_stock - boolean
    
*   description - String
    
*   on\_order\_inventory\_enabled - boolean
    
*   status - one of {"normal","delete"}
    
*   use\_bundle\_inventory\_only - boolean
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.
*   400 - MalformedSelectorException - Thrown if the given selector is invalid.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed. or `MalformedSelectorException` - Thrown if the given selector is invalid.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `inventory_list_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### inventory\_list\_search\_result

Document representing a inventorylist search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of inventory\_list_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "assigned_sites": [
        "site1",
        "site2",
        "site3"
      ],
      "default_in_stock": true,
      "description": "description for inventory list 1.",
      "id": "my-inventory_list1",
      "link": "https://example.com/s/-/dw/data/{version}/inventory_lists/my-inventorylist",
      "on_order_inventory_enabled": false,
      "use_bundle_inventory_only": false
    },
    {
      "assigned_sites": [
        "site3"
      ],
      "default_in_stock": false,
      "description": "description for inventorylist 2.",
      "id": "my-inventorylist2",
      "link": "https://example.com/s/-/dw/data/{version}/inventory_lists/my-inventorylist2",
      "on_order_inventory_enabled": true,
      "use_bundle_inventory_only": false
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### inventory\_list

Document representing a inventorylist

*   `assigned_sites` (_array of string_) The list of sites this inventory list is assigned to. The assigned sites is a computed attribute, and cannot be directly modified.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `default_in_stock` (_boolean_) True if the default for the inventory list is to be in stock. THe default value is false if not specified.
*   `description` (_string_) The user supplied description of this instance.
*   `id` (_string_) The id for the inventory list, which is required and must be unique.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance. The URL is a computed attribute, and cannot be modified.
*   `on_order_inventory_enabled` (_boolean_) True if the on order flag is enabled. The default value is false if not specified.
*   `use_bundle_inventory_only` (_boolean_) True if the inventory list is used in bundle inventory only. The default value is false if not specified.

_Example_

```
{
  "assigned_sites": [
    "SiteGenesis",
    "MyOtherSite"
  ],
  "default_in_stock": true,
  "description": "description for inventorylist",
  "id": "my-inventorylist",
  "link": "https://example.com/s/-/dw/data/{version}/inventory_lists/my-inventorylist",
  "on_order_inventory_enabled": false,
  "use_bundle_inventory_only": false
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=ab32545522fd89fa1f9ac0d7b6d7d71aef836ab842c8512d08e78b63cb1ef202 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-inventory-lists.md -->

Data Inventory Lists (deprecated)

# Data Inventory Lists (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Inventory Lists

`GET /inventory_lists`

Operation ID: `Get Inventory Lists`. Tags: inventory\_lists. Security: oauth2\_application.

Action to get all the inventory lists with no filtering.

#### Parameters

*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `inventory_lists`.
    

### GET Get Inventory List

`GET /inventory_lists/{id}`

Operation ID: `Get Inventory List`. Tags: inventory\_lists. Security: oauth2\_application.

Action to get inventory list information.

This endpoint may return the following faults:

*   404 - InventoryListNotFoundException - Thrown in case the inventory list does not exist matching the given id

#### Parameters

*   `id` (path, string, required) The id of the requested inventory list.  
    Minimum length: 1.

#### Responses

*   **404** `InventoryListNotFoundException` - Thrown in case the inventory list does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `inventory_list`.
    

### PUT Create Inventory List

`PUT /inventory_lists/{id}`

Operation ID: `Create Inventory List`. Tags: inventory\_lists. Security: oauth2\_application.

Creates an inventory list using the information provided.

This endpoint may return the following faults:

*   400 - IdConflictException - if the Id in request is not the same as the ID in document.

#### Parameters

*   `id` (path, string, required) The id of the inventory list to create.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `inventory_list`.

#### Responses

*   **400** `IdConflictException` - if the Id in request is not the same as the ID in document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `inventory_list`.
    

### DELETE Delete Inventory List

`DELETE /inventory_lists/{id}`

Operation ID: `Delete Inventory List`. Tags: inventory\_lists. Security: oauth2\_application.

Deletes the inventory list by ID

#### Parameters

*   `id` (path, string, required) One inventory list id to remove

#### Responses

*   **204**

### PATCH Update Inventory List

`PATCH /inventory_lists/{id}`

Operation ID: `Update Inventory List`. Tags: inventory\_lists. Security: oauth2\_application.

Updates the inventory list with the specified information.

This endpoint may return the following faults:

*   404 - InventoryListNotFoundException - Thrown in case the inventory list does not exist matching the given id

#### Parameters

*   `id` (path, string, required) The id of the requested inventory list.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `inventory_list`.

#### Responses

*   **404** `InventoryListNotFoundException` - Thrown in case the inventory list does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `inventory_list`.
    

### GET Get Product Inventory Records

`GET /inventory_lists/{inventory_list_id}/product_inventory_records`

Operation ID: `Get Product Inventory Records`. Tags: inventory\_lists. Security: oauth2\_application.

Gets all product inventory records for an inventory list.

This endpoint may return the following faults:

*   404 - InventoryListNotFoundException - Indicates the inventory list does not exist.

#### Parameters

*   `inventory_list_id` (path, string, required) The inventory list ID  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **404** `InventoryListNotFoundException` - Indicates the inventory list does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_inventory_records`.
    

### GET Get Product Inventory Record

`GET /inventory_lists/{inventory_list_id}/product_inventory_records/{product_id}`

Operation ID: `Get Product Inventory Record`. Tags: inventory\_lists. Security: oauth2\_application.

Gets a product inventory record.

This endpoint may return the following faults:

*   404 - InventoryListNotFoundException - Indicates the inventory list does not exist.
*   404 - ProductInventoryRecordNotFoundException - Indicates the product inventory record does not exist.

#### Parameters

*   `inventory_list_id` (path, string, required) The inventory list ID  
    Minimum length: 1.
*   `product_id` (path, string, required) The product ID  
    Minimum length: 1.

#### Responses

*   **404** `InventoryListNotFoundException` - Indicates the inventory list does not exist. or `ProductInventoryRecordNotFoundException` - Indicates the product inventory record does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_inventory_record`.
    

### PUT Create Product Inventory Record

`PUT /inventory_lists/{inventory_list_id}/product_inventory_records/{product_id}`

Operation ID: `Create Product Inventory Record`. Tags: inventory\_lists. Security: oauth2\_application.

Creates a product inventory record using the information provided.

This endpoint may return the following faults:

*   404 - InventoryListNotFoundException - Indicates the inventory list does not exist.
*   409 - ConflictException - Indicates a concurrent update

#### Parameters

*   `inventory_list_id` (path, string, required) The inventory list ID  
    Minimum length: 1.
*   `product_id` (path, string, required) The product ID  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_inventory_record`.

#### Responses

*   **404** `InventoryListNotFoundException` - Indicates the inventory list does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `ConflictException` - Indicates a concurrent update
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_inventory_record`.
    

### DELETE Delete Product Inventory Record

`DELETE /inventory_lists/{inventory_list_id}/product_inventory_records/{product_id}`

Operation ID: `Delete Product Inventory Record`. Tags: inventory\_lists. Security: oauth2\_application.

Deletes a product inventory record by ID.

This endpoint may return the following faults:

*   404 - InventoryListNotFoundException - Indicates the inventory list does not exist.
*   404 - ProductInventoryRecordNotFoundException - Indicates the product inventory record does not exist.

#### Parameters

*   `inventory_list_id` (path, string, required) The inventory list ID  
    Minimum length: 1.
*   `product_id` (path, string, required) The product ID  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `InventoryListNotFoundException` - Indicates the inventory list does not exist. or `ProductInventoryRecordNotFoundException` - Indicates the product inventory record does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Product Inventory Record

`PATCH /inventory_lists/{inventory_list_id}/product_inventory_records/{product_id}`

Operation ID: `Update Product Inventory Record`. Tags: inventory\_lists. Security: oauth2\_application.

Updates the product inventory record with the specified information.

This endpoint may return the following faults:

*   404 - InventoryListNotFoundException - Indicates the inventory list does not exist.
*   404 - ProductInventoryRecordNotFoundException - Indicates the product inventory record does not exist.
*   409 - ConflictException - Indicates a concurrent update

#### Parameters

*   `inventory_list_id` (path, string, required) The inventory list ID  
    Minimum length: 1.
*   `product_id` (path, string, required) The product ID  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_inventory_record`.

#### Responses

*   **404** `InventoryListNotFoundException` - Indicates the inventory list does not exist. or `ProductInventoryRecordNotFoundException` - Indicates the product inventory record does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `ConflictException` - Indicates a concurrent update
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_inventory_record`.
    

## Schemas

### inventory\_lists

Document representing an unfiltered list of inventory lists.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of inventory\_list_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### inventory\_list

Document representing a inventorylist

*   `assigned_sites` (_array of string_) The list of sites this inventory list is assigned to. The assigned sites is a computed attribute, and cannot be directly modified.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `default_in_stock` (_boolean_) True if the default for the inventory list is to be in stock. THe default value is false if not specified.
*   `description` (_string_) The user supplied description of this instance.
*   `id` (_string_) The id for the inventory list, which is required and must be unique.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance. The URL is a computed attribute, and cannot be modified.
*   `on_order_inventory_enabled` (_boolean_) True if the on order flag is enabled. The default value is false if not specified.
*   `use_bundle_inventory_only` (_boolean_) True if the inventory list is used in bundle inventory only. The default value is false if not specified.

_Example_

```
{
  "assigned_sites": [
    "SiteGenesis",
    "MyOtherSite"
  ],
  "default_in_stock": true,
  "description": "description for inventorylist",
  "id": "my-inventorylist",
  "link": "https://example.com/s/-/dw/data/{version}/inventory_lists/my-inventorylist",
  "on_order_inventory_enabled": false,
  "use_bundle_inventory_only": false
}
```

### product\_inventory\_records

Document representing an unfiltered list of inventory records.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of product\_inventory\_record_) The collection of product inventory records.
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 4,
  "data": [
    {
      "link": "https://example.com/s/-/dw/data/{version}/inventory_lists/my-inventory-list/product_inventory_records/product-id-0",
      "product_id": "product-id-0"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/inventory_lists/my-inventory-list/product_inventory_records/product-id-1",
      "product_id": "product-id-1"
    }
  ],
  "start": 0,
  "total": 4
}
```

### product\_inventory\_record

Document representing a product inventory record.

*   `allocation` (_product\_inventory\_record\_allocation_) The allocation quantity and reset date.
*   `ats` (_number (double)_) The quantity of items available to sell (ATS). This is calculated as the allocation plus the preorderBackorderAllocation minus the turnover.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `in_stock_date` (_string (date-time)_) The date that the item is expected to be in stock.
*   `inventory_list_id` (_string_) The user supplied ID of the inventory list.
*   `inventory_turnover` (_number (double)_) The sum of all inventory transactions (decrements and increments) that have been recorded subsequent to the allocation was reset date. The quantity value can be negative due to higher quantity of inventory decrements than increments.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The URL that is used to get this instance.
*   `perpetual_flag` (_boolean_) The flag that determines if the product is perpetually in stock.
*   `pre_order_back_order_allocation` (_number (double)_) The quantity of items that are allocated for sale, beyond the initial stock allocation.
*   `pre_order_back_order_handling` (_string_) The enum holding the records pre-backorder-handling configuration. Possible values are NONE, PREORDER and BACKORDER. Method returns NONE in case the record pre-backorder-handling-code is null or unknown.  
    Allowed values: `none`, `preorder`, `backorder`.
*   `product_id` (_string_) The user supplied ID of the product.  
    Minimum length: 1. Maximum length: 256.
*   `product_name` (_string_) The name of the product.
*   `quantity_on_order` (_number (double)_) The on order quantity, the quantity of all transactions for this record since the allocation reset date.
*   `stock_level` (_number (double)_) The current stock level. This is calculated as the allocation minus the turnover.

_Example_

```
{
  "allocation": {
    "amount": 10,
    "reset_date": "2013-04-18.74:00:22.000Z"
  },
  "ats": 10,
  "inventory_list_id": "my-inventory-list",
  "inventory_turnover": 0,
  "link": "https://example.com/s/-/dw/data/{version}/my-inventory-list/product_inventory_records/my-product",
  "perpetual_flag": false,
  "pre_order_back_order_handling": "none",
  "product_id": "my-product",
  "product_name": "my product name",
  "quantity_on_order": 0,
  "stock_level": 10
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### product\_inventory\_record\_allocation

Document representing a product inventory record allocation.

*   `amount` (_number (double)_) The allocation quantity that is currently set. The quantity unit is the same unit as the product itself.  
    Minimum: 0.
*   `reset_date` (_string (date-time)_) The date the allocation quantity was initialized or reset.

<!-- document id=e3d97abc8fee4bc3d765cad37d79a00913a6996ff2acd5d5e86b89ca3da5bdfd url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-job-execution-search.md -->

Data Job Execution Search (deprecated)

# Data Job Execution Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Job Executions

`POST /job_execution_search`

Operation ID: `Search Job Executions`. Tags: job\_execution\_search. Security: oauth2\_application.

Searches for job executions.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   id - String
    
*   job\_id - String
    
*   start\_time - Date
    
*   end\_time - Date
    
*   status - String
    

This is the list of sortable attributes:

*   job\_id - String
    
*   start\_time - Date
    
*   end\_time - Date
    
*   status - String
    

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `job_execution_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### job\_execution\_search\_result

Document representing a job execution search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of job\_execution_) The sorted array of search hits. May be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 3,
  "hits": [
    {
      "domain_names": [
        "Sites-Site",
        "Sites-SiteGenesis-Site"
      ],
      "duration": 3000,
      "end_time": "2015-12-16T09:49:11.905Z",
      "exit_status": {
        "code": "OK",
        "message": "OK",
        "status": "ok"
      },
      "id": "cdYS39aaabttcaaadpCLYBAOMV",
      "is_log_file_existing": true,
      "is_restart": true,
      "job_id": "ImportProducts_stg",
      "log_file_name": "Job-ImportProducts_stg@Sites-Site-20151216094909124.log",
      "modification_time": "2015-12-16T09:49:11.617Z",
      "start_time": "2015-12-16T09:49:08.905Z",
      "status": "finished"
    }
  ]
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### job\_execution

*   `client_id` (_string_) When the execution was started by a client, this represents the client's id.
*   `continue_information` (_job\_execution\_continue\_information_) The continuation information of this execution if available.
*   `creation_date` (_string (date-time)_)
*   `duration` (_integer (int64)_) Time in milliseconds, the execution was or is running.
*   `effective_duration` (_integer (int64)_) Time in milliseconds, the job has done work. Paused times are evicted.
*   `end_time` (_string (date-time)_) Timestamp, when execution was finished.
*   `executed_server_id` (_string_) The ID of the server that executed the job.
*   `execution_scopes` (_array of string_) Sorted set of all execution scopes, used by individual steps.
*   `execution_status` (_string_) The current execution status.  
    Allowed values: `pending`, `running`, `pausing`, `paused`, `resuming`, `resumed`, `restarting`, `restarted`, `retrying`, `retried`, `aborting`, `aborted`, `finished`, `unknown`.
*   `exit_status` (_status_) The exit status of the execution, if the execution is in execution status 'finished', 'paused' or 'aborted' and is not executed currently anymore.
*   `id` (_string_) ID of the execution object.
*   `is_log_file_existing` (_boolean_) True if the log file exists, otherwise false.
*   `is_restart` (_boolean_) True if this execution represents a job restart.
*   `job_description` (_string_) Description of the job, this execution belongs to.
*   `job_id` (_string_) ID of the job, this execution belongs to.
*   `last_modified` (_string (date-time)_)
*   `log_file_path` (_string_) Full WebDAV path of the log file, containing execution log.
*   `modification_time` (_string (date-time)_) Timestamp of the last modification time for the execution.
*   `parameters` (_array of job\_execution\_parameter_) List of all job execution parameters.
*   `retry_information` (_job\_execution\_retry\_information_) The retry information of this execution if available.
*   `start_time` (_string (date-time)_) Timestamp, when execution was started.
*   `status` (_string_) The current status. If the execution is currently executed the execution status is returned. If the execution is not executed currently anymore the exit status code of the execution.
*   `status_metadata` (_status\_metadata_) The metadata of the status.
*   `step_executions` (_array of job\_step\_execution_) List of all steps, called for job execution.
*   `user_login` (_string_) When the execution was started by a registered user, this represents the user's login.

_Example_

```
{
  "client_id": "af7f5c90-ffc1-4ea4-9613-f5b375b7dc19",
  "duration": 185,
  "end_time": "2016-05-20T11:54:46.220Z",
  "execution_scopes": [
    "SiteGenesis",
    "SiteGenesis-US",
    "SiteGenesis-DE"
  ],
  "execution_status": "finished",
  "exit_status": {
    "code": "OK",
    "status": "ok"
  },
  "id": "90",
  "is_log_file_existing": true,
  "is_restart": false,
  "job_id": "CustomerImportJob",
  "log_file_name": "Job-JobExecutionTestJob1-20160520115446018.log",
  "modification_time": "2016-05-20T11:54:46.224Z",
  "start_time": "2016-05-20T11:54:46.035Z",
  "status": "OK",
  "step_executions": [
    {
      "duration": 16,
      "end_time": "2016-05-20T11:54:46.075Z",
      "execution_scope": "Organization",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41265",
      "modification_time": "2016-05-20T11:54:46.075Z",
      "start_time": "2016-05-20T11:54:46.059Z",
      "status": "OK",
      "step_description": "A step that executes a pipeline that can be configured via a parameter",
      "step_id": "Step1",
      "step_type_id": "ExecutePipeline",
      "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
    },
    {
      "duration": 12,
      "end_time": "2016-05-20T11:54:46.102Z",
      "execution_scope": "Organization",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41266",
      "modification_time": "2016-05-20T11:54:46.103Z",
      "start_time": "2016-05-20T11:54:46.090Z",
      "status": "OK",
      "step_description": "A step that executes a script module function that can be configured via a parameter",
      "step_id": "Step2",
      "step_type_id": "ExecuteScriptModule",
      "step_type_info": "testScriptModuleStep.ds#execute"
    },
    {
      "duration": 16,
      "end_time": "2016-05-20T11:54:46.132Z",
      "execution_scope": "SiteGenesis-DE",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41267",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.132Z",
      "start_time": "2016-05-20T11:54:46.116Z",
      "status": "OK",
      "step_description": "A step that executes a pipeline that can be configured via a parameter",
      "step_id": "Step3 - Step1",
      "step_type_id": "ExecutePipeline",
      "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
    },
    {
      "duration": 14,
      "end_time": "2016-05-20T11:54:46.159Z",
      "execution_scope": "SiteGenesis-DE",
      "execution_status": "finished",
      "exit_status": {
        "code": "SUCCESS",
        "message": "Step was successful!",
        "status": "ok"
      },
      "id": "41268",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.159Z",
      "start_time": "2016-05-20T11:54:46.145Z",
      "status": "SUCCESS",
      "step_description": "",
      "step_id": "Step3 - Step2",
      "step_type_id": "ExecuteScriptModule",
      "step_type_info": "testScriptModuleStep.ds#testReturnStatusOkWithCodeAndMessage"
    },
    {
      "duration": 15,
      "end_time": "2016-05-20T11:54:46.189Z",
      "execution_scope": "SiteGenesis",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41269",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.189Z",
      "start_time": "2016-05-20T11:54:46.174Z",
      "status": "OK",
      "step_description": "A step that executes a pipeline that can be configured via a parameter",
      "step_id": "Step3 - Step1",
      "step_type_id": "ExecutePipeline",
      "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
    },
    {
      "duration": 13,
      "end_time": "2016-05-20T11:54:46.216Z",
      "execution_scope": "SiteGenesis",
      "execution_status": "finished",
      "exit_status": {
        "code": "SUCCESS",
        "message": "Step was successful!",
        "status": "ok"
      },
      "id": "41270",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.216Z",
      "start_time": "2016-05-20T11:54:46.203Z",
      "status": "SUCCESS",
      "step_description": "",
      "step_id": "Step3 - Step2",
      "step_type_id": "ExecuteScriptModule",
      "step_type_info": "testScriptModuleStep.ds#testReturnStatusOkWithCodeAndMessage"
    }
  ]
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### job\_execution\_continue\_information

Information for a job execution continuation.

*   `continue_status` (_string_) Returns the status, this job execution will get on continuation if continuation is pending.  
    Allowed values: `pending`, `running`, `pausing`, `paused`, `resuming`, `resumed`, `restarting`, `restarted`, `retrying`, `retried`, `aborting`, `aborted`, `aborting_for_restart`, `aborted_for_restart`, `finished`, `unknown`.
*   `is_pending` (_boolean_) Returns `true` if the continuation of this job execution is pending and will be started soon, `false` otherwise.

### status

*   `code` (_string_) Status code.
*   `message` (_string_) Status message.
*   `status` (_string_) Status shows successful operation end.  
    Allowed values: `ok`, `error`.

_Example_

```
{
  "code": "SUCCESS",
  "message": "Step was successful!",
  "status": "ok"
}
```

### job\_execution\_parameter

Specification of a parameter for a job execution.  
  
Request example to execute the job in all storefront sites:

POST /dw/data/v19\_10/jobs/CustomerImportJob/executions
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{
"parameters": \[
{
"name": "SiteScope",
"value": "{\\"all\_storefront\_sites\\":true}"
}
\]
}

  
Request example to execute the job in specified sites only:

POST /dw/data/v19\_10/jobs/CustomerImportJob/executions
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{
"parameters": \[
{
"name": "SiteScope",
"value": "{\\"named\_sites\\":\[\\"SiteGenesis\\", \\"SiteGenesisGlobal\\"\]}"
}
\]
}

*   `name` (_string_, required) The name of the parameter.  
    Minimum length: 1. Maximum length: 256. Pattern: \\S|(\\S(.\*)\\S).
*   `value` (_string_, required) The value of the parameter.  
    Maximum length: 1000. Pattern: \\S|(\\S(.\*)\\S).

### job\_execution\_retry\_information

Retry information for a previous **failed** job execution.

*   `current_retry_attempt` (_integer (int32)_) The current attempt to retry the previous **failed** job execution.
*   `max_retries` (_integer (int32)_) The maximum number of retries.

### status\_metadata

*   `client_id` (_string_) The client ID that is responsible for the status.
*   `reason` (_string_) The reason of the status.
*   `user_login` (_string_) The user login that is responsible for the status.

### job\_step\_execution

*   `chunk_size` (_integer (int32)_) The chunk size for a chunk oriented step execution, otherwise null.
*   `duration` (_integer (int64)_) Time in milliseconds, the execution was or is running.
*   `end_time` (_string (date-time)_) Timestamp, when execution was finished.
*   `execution_scope` (_string_) The ID of the scope this step is or was executed for.
*   `execution_status` (_string_)
    
    Current execution status of the step.
    
    *   'pending': Execution of the step been initiated but the step is not executing yet. Possible next status: 'running'.
        
    *   'running': The step is currently actively executed. Possible next status: 'finished', 'pausing' or 'aborted'.
        
    *   'finished': The step execution is finished and is not actively executed currently. Possible next status: none.
        
    *   'pausing': Pausing of a running step execution has been initiated but the step is not paused yet. Possible next status: 'paused' or 'aborted'.
        
    *   'paused': The step execution is paused and is not actively executed currently. Possible next status: 'pending'.
        
    *   'aborted': A running step execution has been aborted and is not actively executed currently. Possible next status: none.
        
    
      
    Allowed values: `pending`, `running`, `pausing`, `paused`, `resuming`, `resumed`, `restarting`, `restarted`, `retrying`, `retried`, `aborting`, `aborted`, `finished`, `unknown`.
*   `exit_status` (_status_) The exit status of the step execution, if the step execution is in execution status 'finished', 'paused' or 'aborted' and is not executed currently anymore.
*   `id` (_string_) ID of the execution object.
*   `include_steps_from_job_id` (_string_) ID of the job the step of this step execution was included from, if the step was included from another job.
*   `is_chunk_oriented` (_boolean_) True if this execution represents a chunk oriented step execution.
*   `item_filter_count` (_integer (int32)_) The current number of items that have been filtered for a chunk oriented step execution, otherwise null.
*   `item_write_count` (_integer (int32)_) The current number of items that have been written for a chunk oriented step execution, otherwise null.
*   `modification_time` (_string (date-time)_) Timestamp of the last modification time for the execution.
*   `start_time` (_string (date-time)_) Timestamp, when execution was started.
*   `status` (_string_) The current status. If the step execution is currently executed (execution status is one of 'pending', 'running', 'pausing') the execution status is returned. If the step execution is not executed currently anymore (execution status is one one 'finished', 'paused' or 'aborted') the exit status code of the step execution is returned.
*   `status_metadata` (_status\_metadata_) The metadata of the status.
*   `step_description` (_string_) Description of the step, this execution belongs to.ID of the step
*   `step_id` (_string_) ID of the step, this execution belongs to.ID of the step
*   `step_type_id` (_string_) ID of the step's type at the time it is or was executed.
*   `step_type_info` (_string_) Additional information regarding the step's type at the time it is or was executed (e.g. name of a script module and function).
*   `total_item_count` (_integer (int64)_) The total number of items that will be processed for a chunk oriented step execution (null if unknown), otherwise null.

_Example_

```
{
  "duration": 16,
  "end_time": "2016-05-20T11:54:46.075Z",
  "execution_scope": "Organization",
  "execution_status": "finished",
  "exit_status": {
    "code": "OK",
    "message": "",
    "status": "ok"
  },
  "id": "41265",
  "modification_time": "2016-05-20T11:54:46.075Z",
  "start_time": "2016-05-20T11:54:46.059Z",
  "status": "OK",
  "step_description": "A step that executes a pipeline that can be configured via a parameter",
  "step_id": "Step1",
  "step_type_id": "ExecutePipeline",
  "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=8a6f3834a3c937eff8612bd2f5e1a6decceb0e2a5305fe76f59020b63d05db9a url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-jobs.md -->

Data Jobs (deprecated)

# Data Jobs (deprecated)

**Partial reference:** 1 operation(s) were omitted because their source references could not be resolved.

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Read job execution

`GET /jobs/{job_id}/executions/{id}`

Operation ID: `Read job execution`. Tags: jobs. Security: oauth2\_application.

Returns job execution information using the specified ID for the job having the specified job ID.

This endpoint may return the following faults:

*   404 - JobExecutionNotFoundException - for an unknown job ID or job execution ID

#### Parameters

*   `job_id` (path, string, required) the ID of the job.  
    Minimum length: 1.
*   `id` (path, string, required) the ID of the job execution

#### Responses

*   **404** `JobExecutionNotFoundException` - for an unknown job ID or job execution ID
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `job_execution`.
    

### DELETE Delete job execution

`DELETE /jobs/{job_id}/executions/{id}`

Operation ID: `Delete job execution`. Tags: jobs. Security: oauth2\_application.

Deletes job execution information using the specified ID for the job having the specified job ID.

This endpoint may return the following faults:

*   403 - JobExecutionNotFinishedException - if the job execution is not finished.
*   404 - JobExecutionNotFoundException - for an unknown job ID or job execution ID

#### Parameters

*   `job_id` (path, string, required) the ID of the job.  
    Minimum length: 1.
*   `id` (path, string, required) the ID of the job execution

#### Responses

*   **204**
*   **403** `JobExecutionNotFinishedException` - if the job execution is not finished.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `JobExecutionNotFoundException` - for an unknown job ID or job execution ID
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### job\_execution

*   `client_id` (_string_) When the execution was started by a client, this represents the client's id.
*   `continue_information` (_job\_execution\_continue\_information_) The continuation information of this execution if available.
*   `creation_date` (_string (date-time)_)
*   `duration` (_integer (int64)_) Time in milliseconds, the execution was or is running.
*   `effective_duration` (_integer (int64)_) Time in milliseconds, the job has done work. Paused times are evicted.
*   `end_time` (_string (date-time)_) Timestamp, when execution was finished.
*   `executed_server_id` (_string_) The ID of the server that executed the job.
*   `execution_scopes` (_array of string_) Sorted set of all execution scopes, used by individual steps.
*   `execution_status` (_string_) The current execution status.  
    Allowed values: `pending`, `running`, `pausing`, `paused`, `resuming`, `resumed`, `restarting`, `restarted`, `retrying`, `retried`, `aborting`, `aborted`, `finished`, `unknown`.
*   `exit_status` (_status_) The exit status of the execution, if the execution is in execution status 'finished', 'paused' or 'aborted' and is not executed currently anymore.
*   `id` (_string_) ID of the execution object.
*   `is_log_file_existing` (_boolean_) True if the log file exists, otherwise false.
*   `is_restart` (_boolean_) True if this execution represents a job restart.
*   `job_description` (_string_) Description of the job, this execution belongs to.
*   `job_id` (_string_) ID of the job, this execution belongs to.
*   `last_modified` (_string (date-time)_)
*   `log_file_path` (_string_) Full WebDAV path of the log file, containing execution log.
*   `modification_time` (_string (date-time)_) Timestamp of the last modification time for the execution.
*   `parameters` (_array of job\_execution\_parameter_) List of all job execution parameters.
*   `retry_information` (_job\_execution\_retry\_information_) The retry information of this execution if available.
*   `start_time` (_string (date-time)_) Timestamp, when execution was started.
*   `status` (_string_) The current status. If the execution is currently executed the execution status is returned. If the execution is not executed currently anymore the exit status code of the execution.
*   `status_metadata` (_status\_metadata_) The metadata of the status.
*   `step_executions` (_array of job\_step\_execution_) List of all steps, called for job execution.
*   `user_login` (_string_) When the execution was started by a registered user, this represents the user's login.

_Example_

```
{
  "client_id": "af7f5c90-ffc1-4ea4-9613-f5b375b7dc19",
  "duration": 185,
  "end_time": "2016-05-20T11:54:46.220Z",
  "execution_scopes": [
    "SiteGenesis",
    "SiteGenesis-US",
    "SiteGenesis-DE"
  ],
  "execution_status": "finished",
  "exit_status": {
    "code": "OK",
    "status": "ok"
  },
  "id": "90",
  "is_log_file_existing": true,
  "is_restart": false,
  "job_id": "CustomerImportJob",
  "log_file_name": "Job-JobExecutionTestJob1-20160520115446018.log",
  "modification_time": "2016-05-20T11:54:46.224Z",
  "start_time": "2016-05-20T11:54:46.035Z",
  "status": "OK",
  "step_executions": [
    {
      "duration": 16,
      "end_time": "2016-05-20T11:54:46.075Z",
      "execution_scope": "Organization",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41265",
      "modification_time": "2016-05-20T11:54:46.075Z",
      "start_time": "2016-05-20T11:54:46.059Z",
      "status": "OK",
      "step_description": "A step that executes a pipeline that can be configured via a parameter",
      "step_id": "Step1",
      "step_type_id": "ExecutePipeline",
      "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
    },
    {
      "duration": 12,
      "end_time": "2016-05-20T11:54:46.102Z",
      "execution_scope": "Organization",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41266",
      "modification_time": "2016-05-20T11:54:46.103Z",
      "start_time": "2016-05-20T11:54:46.090Z",
      "status": "OK",
      "step_description": "A step that executes a script module function that can be configured via a parameter",
      "step_id": "Step2",
      "step_type_id": "ExecuteScriptModule",
      "step_type_info": "testScriptModuleStep.ds#execute"
    },
    {
      "duration": 16,
      "end_time": "2016-05-20T11:54:46.132Z",
      "execution_scope": "SiteGenesis-DE",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41267",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.132Z",
      "start_time": "2016-05-20T11:54:46.116Z",
      "status": "OK",
      "step_description": "A step that executes a pipeline that can be configured via a parameter",
      "step_id": "Step3 - Step1",
      "step_type_id": "ExecutePipeline",
      "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
    },
    {
      "duration": 14,
      "end_time": "2016-05-20T11:54:46.159Z",
      "execution_scope": "SiteGenesis-DE",
      "execution_status": "finished",
      "exit_status": {
        "code": "SUCCESS",
        "message": "Step was successful!",
        "status": "ok"
      },
      "id": "41268",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.159Z",
      "start_time": "2016-05-20T11:54:46.145Z",
      "status": "SUCCESS",
      "step_description": "",
      "step_id": "Step3 - Step2",
      "step_type_id": "ExecuteScriptModule",
      "step_type_info": "testScriptModuleStep.ds#testReturnStatusOkWithCodeAndMessage"
    },
    {
      "duration": 15,
      "end_time": "2016-05-20T11:54:46.189Z",
      "execution_scope": "SiteGenesis",
      "execution_status": "finished",
      "exit_status": {
        "code": "OK",
        "message": "",
        "status": "ok"
      },
      "id": "41269",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.189Z",
      "start_time": "2016-05-20T11:54:46.174Z",
      "status": "OK",
      "step_description": "A step that executes a pipeline that can be configured via a parameter",
      "step_id": "Step3 - Step1",
      "step_type_id": "ExecutePipeline",
      "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
    },
    {
      "duration": 13,
      "end_time": "2016-05-20T11:54:46.216Z",
      "execution_scope": "SiteGenesis",
      "execution_status": "finished",
      "exit_status": {
        "code": "SUCCESS",
        "message": "Step was successful!",
        "status": "ok"
      },
      "id": "41270",
      "include_steps_from_job_id": "JobExecutionTestJob2",
      "modification_time": "2016-05-20T11:54:46.216Z",
      "start_time": "2016-05-20T11:54:46.203Z",
      "status": "SUCCESS",
      "step_description": "",
      "step_id": "Step3 - Step2",
      "step_type_id": "ExecuteScriptModule",
      "step_type_info": "testScriptModuleStep.ds#testReturnStatusOkWithCodeAndMessage"
    }
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### job\_execution\_continue\_information

Information for a job execution continuation.

*   `continue_status` (_string_) Returns the status, this job execution will get on continuation if continuation is pending.  
    Allowed values: `pending`, `running`, `pausing`, `paused`, `resuming`, `resumed`, `restarting`, `restarted`, `retrying`, `retried`, `aborting`, `aborted`, `aborting_for_restart`, `aborted_for_restart`, `finished`, `unknown`.
*   `is_pending` (_boolean_) Returns `true` if the continuation of this job execution is pending and will be started soon, `false` otherwise.

### status

*   `code` (_string_) Status code.
*   `message` (_string_) Status message.
*   `status` (_string_) Status shows successful operation end.  
    Allowed values: `ok`, `error`.

_Example_

```
{
  "code": "SUCCESS",
  "message": "Step was successful!",
  "status": "ok"
}
```

### job\_execution\_parameter

Specification of a parameter for a job execution.  
  
Request example to execute the job in all storefront sites:

POST /dw/data/v19\_10/jobs/CustomerImportJob/executions
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{
"parameters": \[
{
"name": "SiteScope",
"value": "{\\"all\_storefront\_sites\\":true}"
}
\]
}

  
Request example to execute the job in specified sites only:

POST /dw/data/v19\_10/jobs/CustomerImportJob/executions
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json; charset=UTF-8
{
"parameters": \[
{
"name": "SiteScope",
"value": "{\\"named\_sites\\":\[\\"SiteGenesis\\", \\"SiteGenesisGlobal\\"\]}"
}
\]
}

*   `name` (_string_, required) The name of the parameter.  
    Minimum length: 1. Maximum length: 256. Pattern: \\S|(\\S(.\*)\\S).
*   `value` (_string_, required) The value of the parameter.  
    Maximum length: 1000. Pattern: \\S|(\\S(.\*)\\S).

### job\_execution\_retry\_information

Retry information for a previous **failed** job execution.

*   `current_retry_attempt` (_integer (int32)_) The current attempt to retry the previous **failed** job execution.
*   `max_retries` (_integer (int32)_) The maximum number of retries.

### status\_metadata

*   `client_id` (_string_) The client ID that is responsible for the status.
*   `reason` (_string_) The reason of the status.
*   `user_login` (_string_) The user login that is responsible for the status.

### job\_step\_execution

*   `chunk_size` (_integer (int32)_) The chunk size for a chunk oriented step execution, otherwise null.
*   `duration` (_integer (int64)_) Time in milliseconds, the execution was or is running.
*   `end_time` (_string (date-time)_) Timestamp, when execution was finished.
*   `execution_scope` (_string_) The ID of the scope this step is or was executed for.
*   `execution_status` (_string_)
    
    Current execution status of the step.
    
    *   'pending': Execution of the step been initiated but the step is not executing yet. Possible next status: 'running'.
        
    *   'running': The step is currently actively executed. Possible next status: 'finished', 'pausing' or 'aborted'.
        
    *   'finished': The step execution is finished and is not actively executed currently. Possible next status: none.
        
    *   'pausing': Pausing of a running step execution has been initiated but the step is not paused yet. Possible next status: 'paused' or 'aborted'.
        
    *   'paused': The step execution is paused and is not actively executed currently. Possible next status: 'pending'.
        
    *   'aborted': A running step execution has been aborted and is not actively executed currently. Possible next status: none.
        
    
      
    Allowed values: `pending`, `running`, `pausing`, `paused`, `resuming`, `resumed`, `restarting`, `restarted`, `retrying`, `retried`, `aborting`, `aborted`, `finished`, `unknown`.
*   `exit_status` (_status_) The exit status of the step execution, if the step execution is in execution status 'finished', 'paused' or 'aborted' and is not executed currently anymore.
*   `id` (_string_) ID of the execution object.
*   `include_steps_from_job_id` (_string_) ID of the job the step of this step execution was included from, if the step was included from another job.
*   `is_chunk_oriented` (_boolean_) True if this execution represents a chunk oriented step execution.
*   `item_filter_count` (_integer (int32)_) The current number of items that have been filtered for a chunk oriented step execution, otherwise null.
*   `item_write_count` (_integer (int32)_) The current number of items that have been written for a chunk oriented step execution, otherwise null.
*   `modification_time` (_string (date-time)_) Timestamp of the last modification time for the execution.
*   `start_time` (_string (date-time)_) Timestamp, when execution was started.
*   `status` (_string_) The current status. If the step execution is currently executed (execution status is one of 'pending', 'running', 'pausing') the execution status is returned. If the step execution is not executed currently anymore (execution status is one one 'finished', 'paused' or 'aborted') the exit status code of the step execution is returned.
*   `status_metadata` (_status\_metadata_) The metadata of the status.
*   `step_description` (_string_) Description of the step, this execution belongs to.ID of the step
*   `step_id` (_string_) ID of the step, this execution belongs to.ID of the step
*   `step_type_id` (_string_) ID of the step's type at the time it is or was executed.
*   `step_type_info` (_string_) Additional information regarding the step's type at the time it is or was executed (e.g. name of a script module and function).
*   `total_item_count` (_integer (int64)_) The total number of items that will be processed for a chunk oriented step execution (null if unknown), otherwise null.

_Example_

```
{
  "duration": 16,
  "end_time": "2016-05-20T11:54:46.075Z",
  "execution_scope": "Organization",
  "execution_status": "finished",
  "exit_status": {
    "code": "OK",
    "message": "",
    "status": "ok"
  },
  "id": "41265",
  "modification_time": "2016-05-20T11:54:46.075Z",
  "start_time": "2016-05-20T11:54:46.059Z",
  "status": "OK",
  "step_description": "A step that executes a pipeline that can be configured via a parameter",
  "step_id": "Step1",
  "step_type_id": "ExecutePipeline",
  "step_type_info": "TestScheduleJobProcessPipeline-StartEnd"
}
```

<!-- document id=0212bb8be5516df20fbe35abacfe37709fea3fee00a4aaaf9399ae7909215536 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-libraries.md -->

Data Libraries (deprecated)

# Data Libraries (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get content asset.

`GET /libraries/{library_id}/content/{content_id}`

Operation ID: `Get content asset.`. Tags: libraries. Security: oauth2\_application.

Returns a content asset using the specified ID. If the content asset cannot be found, the server returns a 404 (ContentNotFoundException) fault. If the connection is not secure, the server returns a 403 (SecureCommunicationRequiredException).

This endpoint may return the following faults:

*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the ID of the content asset to retrieve.  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **404** `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_asset`.
    

### PUT Create content asset

`PUT /libraries/{library_id}/content/{content_id}`

Operation ID: `Create content asset`. Tags: libraries. Security: oauth2\_application.

Creates a new content asset in the specified library, or overwrites an existing content asset. If a content asset with the specified ID already exists, the server completely overwrites the content asset. Please note: Existing folder assignments are not touched. If the existing content asset is locked, the server returns a 409 (ResourceLockedException) fault. If the connection is not secure, the server returns a 403 (SecureCommunicationRequiredException) fault.

This endpoint may return the following faults:

*   400 - IdConflictException - Indicates that the ID from the request body doesn't match the URL-Id.
*   412 - ResourceLockedException - Indicates that the ID from the request body doesn't match the URL-Id.
*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the ID of the content asset to retrieve.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `content_asset`.

#### Responses

*   **400** `IdConflictException` - Indicates that the ID from the request body doesn't match the URL-Id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **412** `ResourceLockedException` - Indicates that the ID from the request body doesn't match the URL-Id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_asset`.
    

### DELETE Delete content asset.

`DELETE /libraries/{library_id}/content/{content_id}`

Operation ID: `Delete content asset.`. Tags: libraries. Security: oauth2\_application.

Deletes the content asset with the specified ID from the specified library. If the content asset is not found, the server returns a 404 (NotFoundException) fault. If the content asset is locked by another user, the server returns a 409 (ResourceLockedException) fault. If the connection is not secure, the server returns a 403 (SecureCommunicationRequiredException) fault.

This endpoint may return the following faults:

*   412 - ResourceLockedException - Indicates that the ID from the request body doesn't match the URL-Id.
*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the ID of the content asset to remove.  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **204**
*   **404** `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **412** `ResourceLockedException` - Indicates that the ID from the request body doesn't match the URL-Id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update content asset.

`PATCH /libraries/{library_id}/content/{content_id}`

Operation ID: `Update content asset.`. Tags: libraries. Security: oauth2\_application.

Updates a content asset. In the request, the If-Match header is required. The value of the header is an 'ETag' representing the last known base-point information for the content asset. If the header is missing, the server returns a 409 (IfMatchRequiredException) fault. If the header value does not match the server's 'ETag', the server returns a 412 (InvalidIfMatchException) fault. The delta information for the library folder containing the content asset is updated atomically: the information is written completely or not at all. If the content asset is locked, the server returns a 409 (ResourceLockedException) fault.

This endpoint may return the following faults:

*   400 - ContentIdAlreadyInUseException - Indicates that a content asset with the ID to change to is already existing.
*   412 - ResourceLockedException - Indicates that the ID from the request body doesn't match the URL-Id.
*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the ID of the content asset to retrieve.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `content_asset`.

#### Responses

*   **400** `ContentIdAlreadyInUseException` - Indicates that a content asset with the ID to change to is already existing.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **412** `ResourceLockedException` - Indicates that the ID from the request body doesn't match the URL-Id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_asset`.
    

### GET Get assigned folders list.

`GET /libraries/{library_id}/content/{content_id}/folders`

Operation ID: `Get assigned folders list.`. Tags: libraries. Security: oauth2\_application.

Action to get all assigned folders of a content asset.

This endpoint may return the following faults:

*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) The content id of the assignment.  
    Minimum length: 1. Maximum length: 256.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.

#### Responses

*   **404** `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder_result`.
    

### GET Get content folder assignment

`GET /libraries/{library_id}/folder_assignments/{content_id}/{folder_id}`

Operation ID: `Get content folder assignment`. Tags: libraries. Security: oauth2\_application.

Action to get a single content to folder assignment

This endpoint may return the following faults:

*   404 - AssignmentNotFoundException - Indicates that no assignment between the given content asset and folder exists
*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.
*   404 - ParentFolderNotFoundException - Indicates that the parent folder with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the ID of the content asset to retrieve.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **404** `AssignmentNotFoundException` - Indicates that no assignment between the given content asset and folder exists or `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown. or `ParentFolderNotFoundException` - Indicates that the parent folder with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder_assignment`.
    

### PUT Assign content asset to folder.

`PUT /libraries/{library_id}/folder_assignments/{content_id}/{folder_id}`

Operation ID: `Assign content asset to folder.`. Tags: libraries. Security: oauth2\_application.

Action to assign a content asset to a specified folder.

This endpoint may return the following faults:

*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.
*   404 - ParentFolderNotFoundException - Indicates that the parent folder with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) the ID of the shared library or the site-id in case of a private library  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the content id  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) the folder id  
    Minimum length: 1. Maximum length: 256.

#### Request body

Media type: `application/json, text/xml`. Schema: `content_folder_assignment`.

#### Responses

*   **404** `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown. or `ParentFolderNotFoundException` - Indicates that the parent folder with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder_assignment`.
    

### DELETE Unassign content asset from folder

`DELETE /libraries/{library_id}/folder_assignments/{content_id}/{folder_id}`

Operation ID: `Unassign content asset from folder`. Tags: libraries. Security: oauth2\_application.

Action to unassign a content asset from the specified library folder.

This endpoint may return the following faults:

*   404 - AssignmentNotFoundException - Indicates that no assignment between the given content asset and folder exists
*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.
*   404 - ParentFolderNotFoundException - Indicates that the parent folder with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the ID of the content asset to retrieve.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **204**
*   **404** `AssignmentNotFoundException` - Indicates that no assignment between the given content asset and folder exists or `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown. or `ParentFolderNotFoundException` - Indicates that the parent folder with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update content folder assignment

`PATCH /libraries/{library_id}/folder_assignments/{content_id}/{folder_id}`

Operation ID: `Update content folder assignment`. Tags: libraries. Security: oauth2\_application.

Action to update a single content to folder assignment. Currently only the position and default attribute can be changed.

This endpoint may return the following faults:

*   404 - AssignmentNotFoundException - Indicates that no assignment between the given content asset and folder exists.
*   404 - ContentNotFoundException - Indicates that the content asset with the given id is unknown.
*   404 - FolderNotFoundException - Indicates that the folder with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `content_id` (path, string, required) the content id of the assignment  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `content_folder_assignment`.

#### Responses

*   **404** `AssignmentNotFoundException` - Indicates that no assignment between the given content asset and folder exists. or `ContentNotFoundException` - Indicates that the content asset with the given id is unknown. or `FolderNotFoundException` - Indicates that the folder with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder_assignment`.
    

### GET Get folder.

`GET /libraries/{library_id}/folders/{folder_id}`

Operation ID: `Get folder.`. Tags: libraries. Security: oauth2\_application.

Action to get folder information.

This endpoint may return the following faults:

*   404 - FolderNotFoundException - Indicates that the folder with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **404** `FolderNotFoundException` - Indicates that the folder with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder`.
    

### PUT Create folder.

`PUT /libraries/{library_id}/folders/{folder_id}`

Operation ID: `Create folder.`. Tags: libraries. Security: oauth2\_application.

Action to create a new library folder, or to replace an existing folder. This action completely overwrites existing folders. Please note: Sub folders and assignments to content assets are not touched. This action ignores the folder ID in the input document.

This endpoint may return the following faults:

*   400 - IdConflictException - Indicates that the ID from the request body doesn't match the URL-Id.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.
*   404 - ParentFolderNotFoundException - Indicates that the parent folder with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `content_folder`.

#### Responses

*   **400** `IdConflictException` - Indicates that the ID from the request body doesn't match the URL-Id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `LibraryNotFoundException` - Indicates that library with the given id is unknown. or `ParentFolderNotFoundException` - Indicates that the parent folder with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder`.
    

### DELETE Delete a folder.

`DELETE /libraries/{library_id}/folders/{folder_id}`

Operation ID: `Delete a folder.`. Tags: libraries. Security: oauth2\_application.

Delete folder

This endpoint may return the following faults:

*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **204**
*   **404** `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update folder.

`PATCH /libraries/{library_id}/folders/{folder_id}`

Operation ID: `Update folder.`. Tags: libraries. Security: oauth2\_application.

Updates an existing folder. In the request, the If-Match header is required. The value of the header is an 'ETag' representing the last known base-point information for the library folder. If the header is missing, the server returns a 409 (IfMatchRequiredException) fault. If the header value does not match the server's 'ETag', the server returns a 412 (InvalidIfMatchException) fault. The delta information for the library folder is updated atomically: the information is written completely or not at all.

This endpoint may return the following faults:

*   400 - ContentFolderIdAlreadyInUseException - Indicates that a content folder with the ID to change to is already existing.
*   404 - FolderNotFoundException - Indicates that the folder with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `content_folder`.

#### Responses

*   **400** `ContentFolderIdAlreadyInUseException` - Indicates that a content folder with the ID to change to is already existing.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `FolderNotFoundException` - Indicates that the folder with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder`.
    

### GET Get assigned content assets list

`GET /libraries/{library_id}/folders/{folder_id}/content`

Operation ID: `Get assigned content assets list`. Tags: libraries. Security: oauth2\_application.

Action to get all assigned content assets of a folder.

This endpoint may return the following faults:

*   404 - FolderNotFoundException - Indicates that the folder with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.

#### Responses

*   **404** `FolderNotFoundException` - Indicates that the folder with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_asset_result`.
    

### GET Get sub folders.

`GET /libraries/{library_id}/folders/{folder_id}/sub_folders`

Operation ID: `Get sub folders.`. Tags: libraries. Security: oauth2\_application.

Action to get sub folders information.

This endpoint may return the following faults:

*   404 - FolderNotFoundException - Indicates that the folder with the given id is unknown.
*   404 - LibraryNotFoundException - Indicates that library with the given id is unknown.

#### Parameters

*   `library_id` (path, string, required) ID of the shared library or the site-id in case of a private library.  
    Minimum length: 1. Maximum length: 256.
*   `folder_id` (path, string, required) ID of a target folder.  
    Minimum length: 1. Maximum length: 256.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.

#### Responses

*   **404** `FolderNotFoundException` - Indicates that the folder with the given id is unknown. or `LibraryNotFoundException` - Indicates that library with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_sub_folder_result`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### content\_asset

Document representing a content asset.

*   `classification_folder_id` (_string_) The ID of the classification folder. It is only part of the response, if the assignment from this content asset to the folder is marked as 'default'. The property is read-only. To set the classification folder just create/update an assignment between this content asset and a folder and mark it as 'default'. See details in /libraries/{library\_id}/folder\_assignments/{content\_id}/{folder\_id} resource.
*   `classification_folder_link` (_string_) The link to the classification folder. It is only part of the response, if the assignment from this content asset to the folder is marked as 'default'. The property is read-only. To set the classification folder just create/update an assignment between this content asset and a folder and mark it as 'default'. See details in /libraries/{library\_id}/folder\_assignments/{content\_id}/{folder\_id} resource.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_object (localized)_) The localized content asset description.
    
    Additional properties: `string`.
    
*   `id` (_string_) The id of the content asset.  
    Minimum length: 1. Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link to the content asset resource.
*   `name` (_object (localized)_) The localized content asset name.
    
    Additional properties: `string`.
    
*   `online` (_object (site-specific)_) Is the asset online?
    
    Additional properties: `boolean`.
    
*   `page_description` (_object (localized)_) The localized content asset page description.
    
    Additional properties: `string`.
    
*   `page_keywords` (_object (localized)_) The localized content asset page keywords.
    
    Additional properties: `string`.
    
*   `page_title` (_object (localized)_) The localized content asset page title.
    
    Additional properties: `string`.
    
*   `page_url` (_object (localized)_) The localized content asset page url.
    
    Additional properties: `string`.
    
*   `searchable` (_object (site-specific)_) Is the asset searchable?
    
    Additional properties: `boolean`.
    
*   `site_map_change_frequency` (_object (site-specific)_) The content assets change frequency needed for the sitemap creation (always, hourly, daily, weekly, monthly, yearly, never).
    
    Additional properties: `string`.
    
    Allowed values: `always`, `daily`, `hourly`, `monthly`, `never`, `weekly`, `yearly`. Value meanings: `always`: always; `daily`: daily; `hourly`: hourly; `monthly`: monthly; `never`: never; `weekly`: weekly; `yearly`: yearly.
    
*   `site_map_included` (_object (site-specific)_) The status if the content asset is included into the sitemap (either 0 or 1).
    
    Additional properties: `integer (int32)`.
    
    Allowed values: `0`, `1`. Value meanings: `0`: NO; `1`: YES. Minimum: 0. Maximum: 1.
    
*   `site_map_priority` (_object (site-specific)_) The content assets priority needed for the sitemap creation (0.0 for no priority defined).
    
    Additional properties: `number (double)`.
    
    Maximum: 1.
    
*   `template` (_string_) The rendering template.

_Example_

```
{
  "description": {
    "default": "Global My Account Banner"
  },
  "id": "account-banner",
  "name": {
    "default": "My Account Banner"
  },
  "online": {
    "default": false
  },
  "searchable": {
    "default": false
  },
  "site_map_change_frequency": {
    "default": "never"
  },
  "site_map_included": {
    "default": 0
  },
  "site_map_priority": {
    "default": 0
  },
  "c_body": {
    "default": {
      "source": "<p>This is the account banner body.</p>"
    }
  }
}
```

### content\_folder\_result

Result document containing an array of content folders.

*   `count` (_integer (int32)_) The number of search results in the current page.
*   `data` (_array of object_) The returned objects.
*   `hits` (_array of content\_folder_) The sorted array of search hits. This array can be empty.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search result to include in the document.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of search results.

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "id": "about-us",
      "link": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/folders/about-us",
      "parent_link": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/folders/root",
      "sub_folders_link": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/folders/about-us/sub_folders"
    }
  ],
  "next": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/content/account-banner/folders?count=1&start=2",
  "previous": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/content/account-banner/folders?count=1&start=0",
  "start": 1,
  "total": 3
}
```

### content\_folder\_assignment

Document representing a content folder assignment.

*   `content_id` (_string_) The content id.  
    Maximum length: 256.
*   `content_link` (_string_) The content link.
*   `default` (_boolean_) A flag indicating whether the assignment is the default one.
*   `folder_id` (_string_) The folder id.  
    Maximum length: 256.
*   `folder_link` (_string_) The folder link.
*   `position` (_number (double)_) The position of the content asset in the folder.  
    Minimum: 0.

_Example_

```
{
  "content_id": "account-banner",
  "content_link": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/content/account-banner",
  "folder_id": "about-us",
  "folder_link": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/folders/about-us"
}
```

### content\_folder

Document representing a content folder.

*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_object (localized)_) The localized content folder description.
    
    Additional properties: `string`.
    
*   `id` (_string_) The id of the content folder.  
    Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link to the content folder resource.
*   `name` (_object (localized)_) The localized content folder name.
    
    Additional properties: `string`.
    
*   `online` (_boolean_) A flag indicating whether the folder in online (default is false).
*   `page_description` (_object (localized)_) The localized content folder page description.
    
    Additional properties: `string`.
    
*   `page_keywords` (_object (localized)_) The localized content folder page keywords.
    
    Additional properties: `string`.
    
*   `page_title` (_object (localized)_) The localized content folder page title.
    
    Additional properties: `string`.
    
*   `page_url` (_object (localized)_) The localized content folder page URL.
    
    Additional properties: `string`.
    
*   `parent_folder_id` (_string_) The id of the parent content folder.
*   `parent_link` (_string_) The URL to the parent content folder.
*   `sub_folders_link` (_string_) The URL to list the content sub-folders.
*   `template` (_string_) The rendering template.

_Example_

```
{
  "id": "about-us",
  "online": false,
  "page_description": {
    "default": "Page Descr. (Default)",
    "en": "Page Descr. (en)",
    "en-US": "Page Descr. (en_us)"
  },
  "page_keywords": {
    "default": "Page Keywords (Default)",
    "en": "Page Keywords (en)",
    "en-US": "Page Keywords (en_us)"
  },
  "parent_folder_id": "root"
}
```

### content\_asset\_result

Result document containing an array of content assets.

*   `count` (_integer (int32)_) The number of search results in the current page.
*   `data` (_array of object_) The returned objects.
*   `hits` (_array of content\_asset_) The sorted array of search hits. This array can be empty.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search result to include in the document.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of search results.

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "id": "about-us",
      "link": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/content/about-us"
    }
  ],
  "next": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/folders/about-us/content?count=1&start=2",
  "previous": "https://example.com/s/-/dw/data/{version}/libraries/SiteGenesis/folders/about-us/content?count=1&start=0",
  "start": 1,
  "total": 3
}
```

### content\_sub\_folder\_result

Result document containing an array of content subfolders.

*   `count` (_integer (int32)_) The number of search results in the current page.
*   `data` (_array of object_) The returned objects.
*   `hits` (_array of content\_folder_) The sorted array of search hits. This array can be empty.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search result to include in the document.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of search results.

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=135340095cf2d18673dea083bed25861ed4bc8e4383c262547b7952aacd22c95 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-locale-info.md -->

Data Locale Info (deprecated)

# Data Locale Info (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Locales for given Site

`GET /sites/{site_id}/locale_info/locales`

Operation ID: `Get Locales for given Site`. Tags: sites. Security: oauth2\_application.

Action to get the set of locales with the system given a site.

#### Parameters

*   `include_all` (query, boolean) true if we want to include all the locales. Default is false.
*   `id` (query, string) optional locale to return by id. If specified, that locale is looked up and returned, otherwise the list is returned.
*   `select` (query, string) the set of fields to return from the request. Default is only the locale id.
*   `start` (query, integer (int32)) the start index for paging. Default is 0.
*   `count` (query, integer (int32)) the count of the records to return in this page. Default is 25.
*   `site_id` (path, string, required) Only locales specified for the site are returned  
    Minimum length: 1.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `locale_result`.
    

## Schemas

### locale\_result

Contains the result of getting the system locales.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object_)
*   `hits` (_array of locale_) The locales found by the request
*   `id` (_string_) The input locale (none specifies get all locales)
*   `include_all` (_boolean_) True to get the all the hits for all the locales, not just the active allowed ones
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The string describing the set of fields to return in the result.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 4,
  "hits": [
    {
      "active": true,
      "country": "",
      "default": true,
      "display_country": "",
      "display_language": "",
      "display_name": "default",
      "id": "default",
      "iso3_country": "",
      "iso3_language": "",
      "language": "",
      "name": "default"
    },
    {
      "active": true,
      "country": "",
      "default": false,
      "display_country": "",
      "display_language": "español",
      "display_name": "español",
      "id": "es",
      "iso3_country": "",
      "iso3_language": "spa",
      "language": "es",
      "name": "Spanish"
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 4
}
```

### locale

Document that describes a single locale.

*   `active` (_boolean_) Flag that is true if the locale is currently active in the system.
*   `country` (_string_) The uppercase ISO 3166 2-letter country/region code for this Locale. If no country has been specified for this Locale, this value is an empty string.
*   `default` (_boolean_) Flag that is true if the locale is the default one to use if an explicit locale is not specified.
*   `display_country` (_string_) The display name of this Locale's country, in this Locale's language, not in the session locale's language. If no country has been specified for this Locale, this value is an empty string.
*   `display_language` (_string_) The display name of this Locale's language, in this Locale's language, not in the session locale's language. If no country has been specified for this Locale, this value is an empty string.
*   `display_name` (_string_) The display name of this Locale, in this Locale's language, not in the session locale's language. If no display name has been specified for this Locale, this value is an empty string.
*   `id` (_string_)
    
    Returns the String representation of the localeID.
    
    Combines the language and the country key, concatenated with "-". For example: "en-US". This attribute is the primary key of the class.
    
*   `iso3_country` (_string_) The uppercase ISO 3166 3-letter country/region code for this Locale. If no country has been specified for this Locale, this value is an empty string.
*   `iso3_language` (_string_) The 3-letter ISO 639 language code for this Locale. If no language has been specified for this Locale, this value is an empty string.
*   `language` (_string_) The lowercase ISO 639 language code for this Locale. If no language has been specified for this Locale, this value is an empty string.
*   `name` (_string_) The display name of the Locale. Uses the current request locale to localize the value.

_Example_

```
{
  "active": true,
  "country": "",
  "default": false,
  "display_country": "",
  "display_language": "español",
  "display_name": "español",
  "id": "es",
  "iso3_country": "",
  "iso3_language": "spa",
  "language": "es",
  "name": "Spanish"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=cbd8f11a6bcf74634b2019a6b7d98c4b9706fcf9d98d49e8bb750fe2c70899dd url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-log-requests.md -->

Data Log Requests (deprecated)

# Data Log Requests (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Request Log File

`POST /log_requests/ecdn`

Operation ID: `Request Log File`. Tags: log\_requests. Security: oauth2\_application.

Requests a LogFile-Fetching for the passed zone and time frame.

#### Request body (required)

Request body

Media type: `application/json, text/xml`. Schema: `ecdn_log_fetch_request`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ecdn_log_fetch_response`.
    

### GET Read Logfetching Execution status

`GET /log_requests/ecdn/{id}`

Operation ID: `Read Logfetching Execution status`. Tags: log\_requests. Security: oauth2\_application.

Retrieves the current execution status of the log file fetching.

#### Parameters

*   `id` (path, string, required) ID of the log fetching execution

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ecdn_log_fetch_response`.
    

## Schemas

### ecdn\_log\_fetch\_request

Input-Document for requesting a Log-Fetch process.

*   `end_time` (_string (date-time)_) Optional end time for log file entries, in Unix time stamp format. Must not be more than 1 hour after the start time. If not passed, a one hour time frame is assumed for the log file.
*   `start_time` (_string (date-time)_, required) Start time for log file entries, in Unix time stamp format. Must not be more than 7 days in the past
*   `zone_id` (_string_) zone id is optional but if it is provided then zone\_name is not considered
*   `zone_name` (_string_, required) The internationalized domain name representation (from RFC 3490) of the zone name

_Example_

```
{
  "end_time": "21.2-09-14T16:53:07Z",
  "start_time": "21.2-09-14T16:48:07Z",
  "zone_name": "sitegenesis.com"
}
```

### ecdn\_log\_fetch\_response

Response object, providing the status of the current log fetch request.

*   `id` (_string_) ID of the log fetch request
*   `link` (_string_) HTTPS Download link to the fetched log file, which has a lifetime of 30 minutes. This link will only appear, if the current status of the log fetching is 'finished'.
*   `message` (_string_) message for the log fetch request
*   `status` (_string_) Current status of the log fetch request  
    Allowed values: `pending`, `running`, `finished`.

_Example_

```
{
  "id": "9f83cls0-d93d-llus-foo1-p8dsl3dkcpw0",
  "link": "https://ecdn.commercecloud.salesforce.com/logs/sitegenesis_com_21.2_09_14.gz?token=3d03ekddsflk3m4fl3ekmdes",
  "status": "finished"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=de26429aecad4476835d6f7a166d8c6a2f833f9c5117ed8bd97c7713e12eb859 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-metrics.md -->

Data Metrics (deprecated)

# Data Metrics (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET API metrics

`GET /metrics/{apitype}`

Operation ID: `API metrics`. Tags: metrics. Security: oauth2\_application.

The metrics resource provides insights into runtimes of individual OCAPI requests against the shop or the data-API. Responses of the metrics resource are JSON wrapped metrics in Prometheus Exposition format. For each OCAPI resource, following metrics are available for the given dimension and the current time-frame (1-minute averages).

*   average time of a request (p50 and p95 timings are available under the quantile dimension) in milliseconds
    
*   minimum time of all requests in milliseconds
    
*   maximum time of all requests in milliseconds
    
*   m1-rate, or the one-minute-rate of requests in operations / second
    

Refer to the documentation of the response document for a detailed description of the metrics and dimensions exposed by this API.

This endpoint may return the following faults:

*   400 - TooManyRequestsException - Too many requests.
*   403 - FeatureNotEnabledException - Feature not enabled.

#### Parameters

*   `apitype` (path, string, required) Type of the api. Values are `data` or `shop` .  
    Minimum length: 1.
*   `offset` (query, integer (int32)) Optional offset of the result set not counting commentaries or empty lines.  
    Minimum: 0.
*   `limit` (query, integer (int32)) Optional limit of the result set not counting commentaries or empty lines.  
    Minimum: 1. Maximum: 4500.

#### Responses

*   **400** `TooManyRequestsException` - Too many requests.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `FeatureNotEnabledException` - Feature not enabled.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `metric_response`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### metric\_response

Metrics in Prometheus Exposition Format wrapped as Json array of strings.

*   `limit` (_integer (int32)_) Page size of result page
*   `metrics` (_array of string_)
    
    Metrics in Prometheus Exposition Format.
    
    A single metric is represented by a single line. They have a name, labels (dimensions), a value and a time-stamp.
    
    Example:
    
    OCAPI request: `GET /v21.10/products/{Id}/prices`
    
    total time metric: `products_Id_prices{method="GET",version="v21.10",path1="products",path2="prices",status="2xx"} 112.718755 1620735785000`
    
    The individual elements of a metric line are the metric name, metric dimensions (denoted by label / value pairs in curly braces), the actual metric value (in milliseconds or in operations / second for metrics ending in `_m1rate`) and a time-stamp in milliseconds since 01/01/1970 UTC.
    
    **name**
    
    The metric name will have both path segments and parameters separated by '\`\_\`'. Path segments in the metric name are in lower-case whereas path parameters are formatted in camel-case.
    
    **method**
    
    the HTTP method of the OCAPI request, one of `GET, PUT, POST, DELETE`
    
    **version**
    
    the version of the OCAPI request, e.g. v20.8
    
    **path1** .. **pathN**
    
    The path segments (not including the path-parameters) of the OCAPI request, from the example above, the path segments will be mapped to labels as: `path1="products", path2="prices"`
    
    **breakdown**
    
    Sub-timings of the request, in particular:
    
    *   **total** (implicit): total timings of the request (sum of the three breakdowns below). This dimension is denoted with no label.
        
    *   **platform**: amount of time spent in platform code (including database-tier)
        
    *   **custom**: amount of time spent in custom code (including database-tier)
        
    *   **thirdParty**: amount of time spent invoking third party services through the service framework
        
    
    **status**
    
    *   **2xx**: metrics for all requests with a status code between 200 and 299
        
    *   **3xx**: metrics for all requests with a status code between 300 and 399
        
    *   **4xx**: metrics for all requests with a status code between 400 and 499
        
    *   **5xx**: metrics for all requests with a status code between 500 and 599
        
    
    **quantile**
    
    *   **p50**: median timings
        
    *   **p95**: timings for the 95th percentile of all requests
        
    
    **serviceId** (only for metrics where breakdown = thirdParty)
    
    the `id` of the third party service that was invoked during the request. If multiple services were invoked, timings for each individual service are available
    
*   `offset` (_integer (int32)_) Offset of result page
*   `total` (_integer (int32)_) Total number of metrics

_Example_

```
{
  "limit": 4500,
  "metrics": [
    "# Type products_Id_prices summary",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"custom\",status=\"2xx\"} 4.036 1620735785000",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"custom\",status=\"2xx\",quantile=\"p50\"} 4.036 1620735785000",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"custom\",status=\"2xx\",quantile=\"p95\"} 4.036 1620735785000",
    "products_Id_prices_m1rate{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"custom\",status=\"2xx\"} 0.04850421492712977 1620735785000",
    "products_Id_prices_min{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"custom\",status=\"2xx\"} 4.036 1620735785000",
    "products_Id_prices_max{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"custom\",status=\"2xx\"} 4.036 1620735785000",
    "",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"platform\",status=\"2xx\"} 108.682755 1620735785000",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"platform\",status=\"2xx\",quantile=\"p50\"} 108.682755 1620735785000",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"platform\",status=\"2xx\",quantile=\"p95\"} 108.682755 1620735785000",
    "products_Id_prices_m1rate{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"platform\",status=\"2xx\"} 0.04850421492712977 1620735785000",
    "products_Id_prices_min{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"platform\",status=\"2xx\"} 108.682755 1620735785000",
    "products_Id_prices_max{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",breakdown=\"platform\",status=\"2xx\"} 108.682755 1620735785000",
    "",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",status=\"2xx\"} 112.718755 1620735785000",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",status=\"2xx\",quantile=\"p50\"} 112.718755 1620735785000",
    "products_Id_prices{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",status=\"2xx\",quantile=\"p95\"} 112.718755 1620735785000",
    "products_Id_prices_m1rate{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",status=\"2xx\"} 0.04850421492712977 1620735785000",
    "products_Id_prices_min{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",status=\"2xx\"} 112.718755 1620735785000",
    "products_Id_prices_max{method=\"GET\",version=\"v16.9\",path1=\"products\",path2=\"prices\",status=\"2xx\"} 112.718755 1620735785000",
    ""
  ],
  "offset": 0,
  "total": 18
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=0ce9734fdfa2509ca7512b4403fb7dbe5340375345902c1026cf9af27d607951 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-ocapi-configs.md -->

Data OCAPI Configs (deprecated)

# Data OCAPI Configs (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get all allowed resources for the client.

`GET /ocapi_configs/{clientId}`

Operation ID: `Get all allowed resources for the client.`. Tags: ocapi\_configs. Security: oauth2\_application.

Get all allowed resources for the client.

This endpoint may return the following faults:

*   400 - InvalidOCAPIConfigException - Indicates that at least one of the existing configs can not be parsed

#### Parameters

*   `clientId` (path, string, required) client ID  
    Minimum length: 1.

#### Responses

*   **400** `InvalidOCAPIConfigException` - Indicates that at least one of the existing configs can not be parsed
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ocapi_configs_api_response`.
    

### PUT Add a client to existing OCAPI configurations. Overwrite config if the client already exists.

`PUT /ocapi_configs/{clientId}`

Operation ID: `Add a client to existing OCAPI configurations. Overwrite config if the client already exists.`. Tags: ocapi\_configs. Security: oauth2\_application.

Add a client to existing OCAPI configurations. Overwrite config if the client already exists.

This endpoint may return the following faults:

*   400 - InvalidOCAPIConfigException - Indicates that the resulting config is not valid
*   400 - SelfUpdateException - Write operation on self is not allowed. (The clientId being used for calling this API should be different from target clientId)
*   404 - SiteNotFoundException - Indicates that at least one of the target sites is unknown

#### Parameters

*   `clientId` (path, string, required) client ID  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `ocapi_configs_api_request`.

#### Responses

*   **400** `InvalidOCAPIConfigException` - Indicates that the resulting config is not valid or `SelfUpdateException` - Write operation on self is not allowed. (The clientId being used for calling this API should be different from target clientId)
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - Indicates that at least one of the target sites is unknown
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ocapi_configs_api_response`.
    

### POST Add a client to existing OCAPI configurations. Return errors when client already exists.

`POST /ocapi_configs/{clientId}`

Operation ID: `Add a client to existing OCAPI configurations. Return errors when client already exists.`. Tags: ocapi\_configs. Security: oauth2\_application.

Add a client to existing OCAPI configurations. Return errors when client already exists.

This endpoint may return the following faults:

*   400 - InvalidOCAPIConfigException - Indicates that the resulting config is not valid
*   400 - SelfUpdateException - Write operation on self is not allowed. (The clientId being used for calling this API should be different from target clientId)
*   404 - SiteNotFoundException - Indicates that at least one of the target sites is unknown
*   409 - DuplicateClientIdException - Indicates that the client id already exists in original OCAPI configuration

#### Parameters

*   `clientId` (path, string, required) client ID  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `ocapi_configs_api_request`.

#### Responses

*   **400** `InvalidOCAPIConfigException` - Indicates that the resulting config is not valid or `SelfUpdateException` - Write operation on self is not allowed. (The clientId being used for calling this API should be different from target clientId)
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - Indicates that at least one of the target sites is unknown
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `DuplicateClientIdException` - Indicates that the client id already exists in original OCAPI configuration
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `ocapi_configs_api_response`.
    

### DELETE Delete a client.

`DELETE /ocapi_configs/{clientId}`

Operation ID: `Delete a client.`. Tags: ocapi\_configs. Security: oauth2\_application.

Delete a client.

This endpoint may return the following faults:

*   400 - InvalidOCAPIConfigException - Indicates that the resulting config is not valid
*   400 - SelfUpdateException - Write operation on self is not allowed. (The clientId being used for calling this API should be different from target clientId)

#### Parameters

*   `clientId` (path, string, required) Id of the client to be deleted.  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `InvalidOCAPIConfigException` - Indicates that the resulting config is not valid or `SelfUpdateException` - Write operation on self is not allowed. (The clientId being used for calling this API should be different from target clientId)
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### ocapi\_configs\_api\_response

OCAPI configuration APIs response. It contains all available resources for a client

*   `global` (_array of site\_resource\_info_) Global configuration
*   `sites` (_array of site\_resource\_info_) Site configurations

_Example_

```
{
  "resource_info": {
    "resource_type": "data",
    "resources": [
      {
        "methods": [
          "get"
        ],
        "read_attributes": "(**)",
        "resource_id": "/sites",
        "write_attributes": "(**)"
      },
      {
        "methods": [
          "post"
        ],
        "read_attributes": "(**)",
        "resource_id": "/customers",
        "write_attributes": "(**)"
      }
    ]
  }
}
```

### ocapi\_configs\_api\_request

OCAPI configuration APIs request

*   `resource_info` (_resource\_info_, required) Information of resources to be added
*   `sites` (_array of string_, required) Sites to be updated

_Example_

```
{
  "resource_info": {
    "allowed_origins": [
      "http://foo.example.org"
    ],
    "resource_type": "shop",
    "resources": [
      {
        "methods": [
          "post"
        ],
        "read_attributes": "(**)",
        "resource_id": "/baskets",
        "write_attributes": "(**)"
      },
      {
        "methods": [
          "put"
        ],
        "read_attributes": "(**)",
        "resource_id": "/baskets/*/billing_address",
        "write_attributes": "(**)"
      }
    ]
  }
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### site\_resource\_info

Object to represent a site configuration and available resources in the site configuration.

*   `site_configs` (_array of resource\_info_, required) Site configuration
*   `site_id` (_string_) Site ID

_Example_

```
{
  "site_configs": [
    {
      "resource_type": "data",
      "resources": [
        {
          "methods": [
            "get"
          ],
          "read_attributes": "(**)",
          "resource_id": "/sites",
          "write_attributes": "(**)"
        },
        {
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "resource_id": "/customers",
          "write_attributes": "(**)"
        }
      ]
    },
    {
      "allowed_origins": [
        "http://foo.example.org"
      ],
      "resource_type": "shop",
      "resources": [
        {
          "methods": [
            "post"
          ],
          "read_attributes": "(**)",
          "resource_id": "/baskets",
          "write_attributes": "(**)"
        },
        {
          "methods": [
            "put"
          ],
          "read_attributes": "(**)",
          "resource_id": "/baskets/*/billing_address",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}
```

### resource\_info

*   `allowed_origins` (_array of string_) Allowed Origins
*   `api_type` (_string_, required) API Type  
    Allowed values: `data`, `shop`.
*   `resources` (_array of resource\_object_, required) An array of resources  
    Minimum items: 1.
*   `response_headers` (_object_) Response Header
    
    Additional properties: `string`.
    

_Example_

```
{
  "allowed_origins": [
    "http://foo.example.org"
  ],
  "resource_type": "shop",
  "resources": [
    {
      "methods": [
        "post"
      ],
      "read_attributes": "(**)",
      "resource_id": "/baskets",
      "write_attributes": "(**)"
    },
    {
      "methods": [
        "put"
      ],
      "read_attributes": "(**)",
      "resource_id": "/baskets/*/billing_address",
      "write_attributes": "(**)"
    }
  ]
}
```

### resource\_object

Object to represent a resource in ocapi\_config\_api\_request

*   `cache_time` (_integer (int32)_) Resource Cache time
*   `config` (_object_) Configuration of the resource
    
    Additional properties: `string`.
    
*   `methods` (_array of string_, required) Allowed methods of the resource  
    Minimum items: 1.
*   `personalized_caching_enabled` (_boolean_) Indicate if the personalized caching is enabled for the resource
*   `read_attributes` (_string_) Read attributes of the resource
*   `resource_id` (_string_, required) Resource ID  
    Minimum length: 1.
*   `version_range` (_version\_range\_object_) Version range
*   `write_attributes` (_string_) Write attributes of the resource

_Example_

```
{
  "methods": [
    "post"
  ],
  "read_attributes": "(**)",
  "resource_id": "/baskets",
  "write_attributes": "(**)"
}
```

### version\_range\_object

Object to represent the Version Range. Used in resources\_object.

*   `from` (_string_) Starting version
*   `until` (_string_) Ending version

<!-- document id=f710ad391c178fbe7662b48b2c6e41bbcdc45580be9059976a5664b9697cea45 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-orders.md -->

Data Orders (deprecated)

# Data Orders (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### PATCH Updates the order

`PATCH /sites/{site_id}/orders/{order_no}`

Operation ID: `Updates the order`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the order.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Updates the order confirmation status

`PUT /sites/{site_id}/orders/{order_no}/confirmation_status`

Operation ID: `Updates the order confirmation status`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the order confirmation status.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_confirmation_status_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Updates the order export status

`PUT /sites/{site_id}/orders/{order_no}/export_status`

Operation ID: `Updates the order export status`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the order export status. Setting the status to EXPORTED will also trigger the finalization of on-order inventory transactions for this order, meaning that all inventory transactions with type on-order will be moved into final inventory transactions. This is only relevant when on-order inventory is turned on for the inventory list ordered products are in.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_export_status_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Updates the order external status

`PUT /sites/{site_id}/orders/{order_no}/external_status`

Operation ID: `Updates the order external status`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the order external status.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_external_status_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Updates the payment instrument of an order

`PATCH /sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id}`

Operation ID: `Updates the payment instrument of an order`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the payment instrument of an order.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - PaymentInstrumentNotFoundException - In case of the given payment\_instrument\_id does not reference an existing payment instrument.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) ID of the payment instrument  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `payment_instrument_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `PaymentInstrumentNotFoundException` - In case of the given payment\_instrument\_id does not reference an existing payment instrument. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Updates the transaction of an order payment instrument

`PATCH /sites/{site_id}/orders/{order_no}/payment_instruments/{payment_instrument_id}/transaction`

Operation ID: `Updates the transaction of an order payment instrument`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the transaction of an order payment instrument.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - PaymentInstrumentNotFoundException - In case of the given payment\_instrument\_id does not reference an existing payment instrument.
*   404 - PaymentTransactionNotFoundException - In case of the payment instrument does not reference a payment transaction.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) ID of the payment instrument  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `payment_transaction_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `PaymentInstrumentNotFoundException` - In case of the given payment\_instrument\_id does not reference an existing payment instrument. or `PaymentTransactionNotFoundException` - In case of the payment instrument does not reference a payment transaction. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Updates the order payment status

`PUT /sites/{site_id}/orders/{order_no}/payment_status`

Operation ID: `Updates the order payment status`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the order payment status.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_payment_status_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Updates (create or replace) the order shipment address

`PUT /sites/{site_id}/orders/{order_no}/shipments/{shipment_id}/shipping_address`

Operation ID: `Updates (create or replace) the order shipment address`. Tags: sites. Security: oauth2\_application; client\_id.

Updates (create or replace) the order shipment address.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - ShipmentNotFoundException - In case of the given shipment\_id does not reference an existing shipment.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.
*   `shipment_id` (path, string, required) ID of the shipment  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `shipping_address_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `ShipmentNotFoundException` - In case of the given shipment\_id does not reference an existing shipment. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Updates the order shipping status

`PUT /sites/{site_id}/orders/{order_no}/shipping_status`

Operation ID: `Updates the order shipping status`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the order shipping status.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.

#### Parameters

*   `site_id` (path, string, required) ID of the site.  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_shipping_status_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PUT Updates the order status

`PUT /sites/{site_id}/orders/{order_no}/status`

Operation ID: `Updates the order status`. Tags: sites. Security: oauth2\_application; client\_id.

Updates the order status by using the corresponding methods (fail, undoFail, place, cancel and undoCancel) from the dw.order.OrderMgr. Orders which are not in status CREATED or FAILED can not be set back.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - In case of the given order\_no does not reference an existing order.
*   404 - SiteNotFoundException - In case of the given site\_id does not reference an existing site.
*   409 - CancelOrderException - The order could not be cancelled.
*   409 - OrderIntegrationStatusException - The status change is not supported. An external order management system is integrated which has responsibility for further status changes on placed orders.
*   409 - OrderPreviouslyIntegratedStatusException - The status change is not supported. The order was previously integrated with an external order management system which has responsibility for further status changes.
*   409 - OrderStatusTransitionException - The status change is not supported.
*   409 - PlaceOrderException - The order could not be placed.
*   409 - UndoCancelOrderException - The cancelled order can not be reopened.
*   409 - UndoFailOrderException - The failed order can not be reopened.

#### Parameters

*   `site_id` (path, string, required) ID of the site  
    Minimum length: 1.
*   `order_no` (path, string, required) The order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_status_update_request`.

#### Responses

*   **204**
*   **404** `OrderNotFoundException` - In case of the given order\_no does not reference an existing order. or `SiteNotFoundException` - In case of the given site\_id does not reference an existing site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `CancelOrderException` - The order could not be cancelled. or `OrderIntegrationStatusException` - The status change is not supported. An external order management system is integrated which has responsibility for further status changes on placed orders. or `OrderPreviouslyIntegratedStatusException` - The status change is not supported. The order was previously integrated with an external order management system which has responsibility for further status changes. or `OrderStatusTransitionException` - The status change is not supported. or `PlaceOrderException` - The order could not be placed. or `UndoCancelOrderException` - The cancelled order can not be reopened. or `UndoFailOrderException` - The failed order can not be reopened.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

## Schemas

### order\_update\_request

Request body to update an order.

Type: `any`.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### order\_confirmation\_status\_update\_request

Request body to update the order confirmation status.

*   `status` (_string_, required) The new confirmation status for an order.  
    Allowed values: `confirmed`, `not_confirmed`.

### order\_export\_status\_update\_request

Request body to update the order export status.

*   `status` (_string_, required) The new export status for an order.  
    Allowed values: `exported`, `not_exported`, `ready`, `failed`.

### order\_external\_status\_update\_request

Request body to update the order external status.

*   `status` (_string_, required) The new external status for an order.  
    Minimum length: 1. Maximum length: 256.

### payment\_instrument\_update\_request

Request body to update an order payment instrument.

Type: `any`.

### payment\_transaction\_update\_request

Request body to update an order payment transaction.

Type: `any`.

### order\_payment\_status\_update\_request

Request body to update the order payment status.

*   `status` (_string_, required) The new payment status for an order.  
    Allowed values: `paid`, `part_paid`, `not_paid`.

### shipping\_address\_update\_request

Request body to update the order shipping address.

*   `address1` (_string_)
*   `address2` (_string_)
*   `city` (_string_)
*   `company_name` (_string_)
*   `country_code` (_string_)
*   `first_name` (_string_)
*   `full_name` (_string_)
*   `id` (_string_)
*   `job_title` (_string_)
*   `last_name` (_string_)
*   `phone` (_string_)
*   `post_box` (_string_)
*   `postal_code` (_string_)
*   `salutation` (_string_)
*   `second_name` (_string_)
*   `state_code` (_string_)
*   `suffix` (_string_)
*   `suite` (_string_)
*   `title` (_string_)

### order\_shipping\_status\_update\_request

Request body to update the order shipping status.

*   `status` (_string_, required) The new shipping status for an order.  
    Allowed values: `shipped`, `part_shipped`, `not_shipped`.

### order\_status\_update\_request

Request body to update the order status.

*   `status` (_string_, required) The new status for an order.  
    Allowed values: `created`, `new`, `open`, `completed`, `cancelled`, `failed`, `failed_with_reopen`.

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=f8d78a5610d7c21b4ac9df34637b98d4bf8e66a129dfa85e0e995d00825968c9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-permissions.md -->

Data Permissions (deprecated)

# Data Permissions (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Application Permissions

`GET /permissions`

Operation ID: `Get Application Permissions`. Tags: permissions. Security: oauth2\_application.

Get application specific permissions per type.

#### Parameters

*   `expand` (query, array of string) The permission expand. A comma separated list with the allowed values (bm, csc).

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `application_permissions`.
    

### GET Get Business Manager Permissions

`GET /permissions/bm`

Operation ID: `Get Business Manager Permissions`. Tags: permissions. Security: oauth2\_application.

Get Business Manager permissions per type.

#### Parameters

*   `expand` (query, array of string) The permission expand. A comma separated list with the allowed values (module, functional, webdav, locale).

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `bmpermissions`.
    

### GET Get Functional Permissions

`GET /permissions/bm/functional`

Operation ID: `Get Functional Permissions`. Tags: permissions. Security: oauth2\_application.

Get functional permissions per scope.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `functional_permissions`.
    

### GET Get Locale Permissions

`GET /permissions/bm/locale`

Operation ID: `Get Locale Permissions`. Tags: permissions. Security: oauth2\_application.

Get locale permissions per scope.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `locale_permissions`.
    

### GET Get Business Manager Module Permissions

`GET /permissions/bm/module`

Operation ID: `Get Business Manager Module Permissions`. Tags: permissions. Security: oauth2\_application.

Get Business Manager module permissions per scope.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `module_permissions`.
    

### GET Get WebDAV Permissions

`GET /permissions/bm/webdav`

Operation ID: `Get WebDAV Permissions`. Tags: permissions. Security: oauth2\_application.

Get WebDAV permissions per scope.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `webdav_permissions`.
    

### GET Get Permissions

`GET /permissions/csc`

Operation ID: `Get Permissions`. Tags: permissions. Security: oauth2\_application.

Get permissions per type.

#### Parameters

*   `expand` (query, array of string) The permission expand. A comma separated list with the allowed values (module, functional, webdav, locale).

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `cscpermissions`.
    

### GET Get CSC Module Permissions

`GET /permissions/csc/module`

Operation ID: `Get CSC Module Permissions`. Tags: permissions. Security: oauth2\_application.

Get CSC module permissions per scope.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `module_permissions`.
    

## Schemas

### application\_permissions

Document representing the available applications for retrieving permissions.

*   `applications` (_array of string_) The available applications (e.g. 'bm' for Business Manager).
*   `bm` (_bmpermissions_) The permissions of application 'bm'.
*   `csc` (_cscpermissions_) The permissions of application 'csc'.

### bmpermissions

Document representing the available permissions per type.

*   `functional` (_functional\_permissions_) The functional permissions available through expand ('functional').
*   `functional_link` (_string_) The url to the resource that provides functional permissions.
*   `locale` (_locale\_permissions_) The locale permissions available through expand ('locale').
*   `locale_link` (_string_) The url to the resource that provides locale permissions.
*   `module` (_module\_permissions_) The module permissions available through expand ('module').
*   `module_link` (_string_) The url to the resource that provides module permissions.
*   `types` (_array of string_)
*   `webdav` (_webdav\_permissions_) The webdav permissions available through expand ('webdav').
*   `webdav_link` (_string_) The url to the resource that provides webdav permissions.

### functional\_permissions

Document representing the available functional permissions.

*   `organization` (_array of functional\_permission_) The collection of available organization functional permissions.
*   `scopes` (_array of string_) The available functional permission scopes (e.g. organization, site).
*   `site` (_array of functional\_permission_) The list of available site functional permissions.

_Example_

```
{
  "organization": [
    {
      "name": "Delete_All_Catalogs",
      "type": "functional",
      "value": "ACCESS"
    }
  ],
  "site": [
    {
      "name": "Manage_Site_Catalog",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "ACCESS"
      }
    }
  ]
}
```

### locale\_permissions

Document representing the available locale permissions.

*   `scopes` (_array of string_) The available Locale permission scopes (e.g. unscoped).
*   `unscoped` (_array of locale\_permission_) The collection of available unscoped Locale permissions.

_Example_

```
{
  "scopes": [
    "unscoped"
  ],
  "unscoped": [
    {
      "display_name": {
        "default": "Default"
      },
      "locale_id": "default",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "Arabic"
      },
      "locale_id": "ar",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "Arabic (Algeria)"
      },
      "locale_id": "ar_DZ",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "Chinese"
      },
      "locale_id": "zh",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "Chinese (China)"
      },
      "locale_id": "zh_CN",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "Dutch"
      },
      "locale_id": "nl",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "English"
      },
      "locale_id": "en",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "English (Canada)"
      },
      "locale_id": "en_CA",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "English (United States)"
      },
      "locale_id": "en_US",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "French"
      },
      "locale_id": "fr",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "French (Belgium)"
      },
      "locale_id": "fr_BE",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "French (Canada)"
      },
      "locale_id": "fr_CA",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "French (France)"
      },
      "locale_id": "fr_FR",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "German"
      },
      "locale_id": "de",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "German (Germany)"
      },
      "locale_id": "de_DE",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "display_name": {
        "default": "Spanish"
      },
      "locale_id": "es",
      "type": "locale",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    }
  ]
}
```

### module\_permissions

Document representing the available module permissions in shape of menu items and menu actions.

*   `organization` (_array of menu\_item_) The collection of available organization menu items.
*   `scopes` (_array of string_) The available menu item scopes (e.g. organization, site).
*   `site` (_array of menu\_item_) The list of available site menu items.

_Example_

```
{
  "scopes": [
    "site",
    "organization"
  ],
  "site": [
    {
      "display_name": {
        "default": "Customer"
      },
      "menu_actions": [
        {
          "description": {
            "default": "Check a customer address."
          },
          "display_name": {
            "default": "Check Address"
          },
          "module_type": "CSC",
          "name": "customer_address_check",
          "system": false,
          "type": "module",
          "values": [
            "ACCESS"
          ]
        }
      ],
      "module_type": "CSC",
      "name": "customer",
      "type": "module"
    },
    {
      "display_name": {
        "default": "Basket"
      },
      "menu_actions": [
        {
          "description": {
            "default": "Check a shipping address."
          },
          "display_name": {
            "default": "Check Shipping Address"
          },
          "module_type": "CSC",
          "name": "basket_shipping_address_check",
          "system": false,
          "type": "module",
          "values": [
            "ACCESS"
          ]
        },
        {
          "description": {
            "default": "Check a billing address."
          },
          "display_name": {
            "default": "Check Billing Address"
          },
          "module_type": "CSC",
          "name": "basket_billing_address_check",
          "system": false,
          "type": "module",
          "values": [
            "ACCESS"
          ]
        },
        {
          "description": {
            "default": "Reserve inventory for the basket."
          },
          "display_name": {
            "default": "Reserve Inventory"
          },
          "module_type": "CSC",
          "name": "basket_reserve_inventory",
          "system": false,
          "type": "module",
          "values": [
            "ACCESS"
          ]
        }
      ],
      "module_type": "CSC",
      "name": "basket",
      "type": "module"
    },
    {
      "display_name": {
        "default": "Order"
      },
      "menu_actions": [
        {
          "description": {
            "default": "Check a billing address."
          },
          "display_name": {
            "default": "Check Billing Address"
          },
          "module_type": "CSC",
          "name": "order_billing_address_check",
          "system": false,
          "type": "module",
          "values": [
            "ACCESS"
          ]
        },
        {
          "description": {
            "default": "Check a shipping address."
          },
          "display_name": {
            "default": "Check Shipping Address"
          },
          "module_type": "CSC",
          "name": "order_shipping_address_check",
          "system": false,
          "type": "module",
          "values": [
            "ACCESS"
          ]
        }
      ],
      "module_type": "CSC",
      "name": "order",
      "type": "module"
    }
  ]
}
```

### webdav\_permissions

Document representing the available WebDAV permissions.

*   `scopes` (_array of string_) The available WebDAV permission scopes (e.g. unscoped).
*   `unscoped` (_array of webdav\_permission_) The collection of available unscoped WebDAV permissions.

_Example_

```
{
  "scopes": [
    "unscoped"
  ],
  "unscoped": [
    {
      "description": {
        "default": "Allows to access '/impex' via WebDAV."
      },
      "folder": "/impex",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access '/logs' via WebDAV."
      },
      "folder": "/logs",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access '/static' via WebDAV."
      },
      "folder": "/static",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access '/temp' via WebDAV."
      },
      "folder": "/temp",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": ""
      },
      "folder": "/catalogs/*",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access catalog 'SiteGenesis' via WebDAV."
      },
      "folder": "/catalogs/SiteGenesis",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access catalog 'SiteGenesisGlobal' via WebDAV."
      },
      "folder": "/catalogs/SiteGenesisGlobal",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": ""
      },
      "folder": "/libraries/*",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access library 'SiteGenesis' via WebDAV."
      },
      "folder": "/libraries/SiteGenesis",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access library 'SiteGenesisGlobal' via WebDAV."
      },
      "folder": "/libraries/SiteGenesisGlobal",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": ""
      },
      "folder": "/dynamic/*",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access dynamic 'SiteGenesis' via WebDAV."
      },
      "folder": "/dynamic/SiteGenesis",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access dynamic 'SiteGenesisGlobal' via WebDAV."
      },
      "folder": "/dynamic/SiteGenesisGlobal",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": ""
      },
      "folder": "/CustomerSnapshots/*",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access customer snapshots for site 'SiteGenesis' via WebDAV."
      },
      "folder": "/CustomerSnapshots/SiteGenesis",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    },
    {
      "description": {
        "default": "Allows to access customer snapshots for site 'SiteGenesisGlobal' via WebDAV."
      },
      "folder": "/CustomerSnapshots/SiteGenesisGlobal",
      "type": "webdav",
      "values": [
        "ACCESS",
        "READONLY"
      ]
    }
  ]
}
```

### cscpermissions

Document representing the available permissions per type.

*   `module` (_module\_permissions_) The module permissions available through expand ('module').
*   `module_link` (_string_) The url to the resource that provides module permissions.
*   `types` (_array of string_)

_Example_

```
{
  "module": {
    "scopes": [
      "site",
      "organization"
    ],
    "site": [
      {
        "display_name": {
          "default": "Customer"
        },
        "menu_actions": [
          {
            "description": {
              "default": "Check a customer address."
            },
            "display_name": {
              "default": "Check Address"
            },
            "module_type": "CSC",
            "name": "customer_address_check",
            "system": false,
            "type": "module",
            "values": [
              "ACCESS"
            ]
          }
        ],
        "module_type": "CSC",
        "name": "customer",
        "type": "module"
      },
      {
        "display_name": {
          "default": "Basket"
        },
        "menu_actions": [
          {
            "description": {
              "default": "Check a shipping address."
            },
            "display_name": {
              "default": "Check Shipping Address"
            },
            "module_type": "CSC",
            "name": "basket_shipping_address_check",
            "system": false,
            "type": "module",
            "values": [
              "ACCESS"
            ]
          },
          {
            "description": {
              "default": "Check a billing address."
            },
            "display_name": {
              "default": "Check Billing Address"
            },
            "module_type": "CSC",
            "name": "basket_billing_address_check",
            "system": false,
            "type": "module",
            "values": [
              "ACCESS"
            ]
          },
          {
            "description": {
              "default": "Reserve inventory for the basket."
            },
            "display_name": {
              "default": "Reserve Inventory"
            },
            "module_type": "CSC",
            "name": "basket_reserve_inventory",
            "system": false,
            "type": "module",
            "values": [
              "ACCESS"
            ]
          }
        ],
        "module_type": "CSC",
        "name": "basket",
        "type": "module"
      },
      {
        "display_name": {
          "default": "Order"
        },
        "menu_actions": [
          {
            "description": {
              "default": "Check a billing address."
            },
            "display_name": {
              "default": "Check Billing Address"
            },
            "module_type": "CSC",
            "name": "order_billing_address_check",
            "system": false,
            "type": "module",
            "values": [
              "ACCESS"
            ]
          },
          {
            "description": {
              "default": "Check a shipping address."
            },
            "display_name": {
              "default": "Check Shipping Address"
            },
            "module_type": "CSC",
            "name": "order_shipping_address_check",
            "system": false,
            "type": "module",
            "values": [
              "ACCESS"
            ]
          }
        ],
        "module_type": "CSC",
        "name": "order",
        "type": "module"
      }
    ]
  },
  "module_link": "https://example.com/s/-/dw/data/{version}/permissions/csc/module",
  "types": [
    "module"
  ]
}
```

### functional\_permission

Document representing a functional permission.

*   `description` (_object (localized)_) The description of the functional permission.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name of the functional permission.
    
    Additional properties: `string`.
    
*   `name` (_string_) The name of the functional permission.
*   `type` (_string_) The permission type.
*   `values` (_array of string_) The list of possible values for the functional permission, e.g. ACCESS or READONLY.

_Example_

```
{
  "name": "Delete_All_Catalogs",
  "type": "functional",
  "value": "ACCESS"
}
```

### locale\_permission

Document representing a locale permission.

*   `display_name` (_object (localized)_) The display name of the locale.
    
    Additional properties: `string`.
    
*   `locale_id` (_string_) The id of the locale.
*   `type` (_string_) The permission type.
*   `values` (_array of string_) The list of possible values for the locale permission, e.g. ACCESS or READONLY.

_Example_

```
{
  "display_name": {
    "default": "Default"
  },
  "locale_id": "default",
  "type": "locale",
  "values": [
    "ACCESS",
    "READONLY"
  ]
}
```

### menu\_item

Document representing a menu item.

*   `display_name` (_object (localized)_) The display name of the menu item.
    
    Additional properties: `string`.
    
*   `menu_actions` (_array of menu\_action_) The collection of available menu actions.
*   `module_type` (_string_) The module type of the menu item (BM or CC).
*   `name` (_string_) The name of the menu item.
*   `type` (_string_) The permission type.

_Example_

```
{
  "display_name": {
    "default": "Replication"
  },
  "menu_actions": [
    {
      "description": {
        "default": "Start and control data replication processes."
      },
      "display_name": {
        "default": "Data Replication"
      },
      "module_type": "BM",
      "name": "global-data-rep-processes",
      "system": true,
      "type": "module",
      "values": [
        "ACCESS"
      ]
    },
    {
      "description": {
        "default": "Start and control code replication processes."
      },
      "display_name": {
        "default": "Code Replication"
      },
      "module_type": "BM",
      "name": "global-code-rep-processes",
      "system": true,
      "type": "module",
      "values": [
        "ACCESS"
      ]
    }
  ],
  "module_type": "BM",
  "name": "global-replication",
  "type": "module"
}
```

### webdav\_permission

Document representing a WebDAV permission.

*   `description` (_object (localized)_) The description of the WebDAV permission.
    
    Additional properties: `string`.
    
*   `folder` (_string_) The folder of the WebDAV permission.
*   `type` (_string_) The permission type.
*   `values` (_array of string_) The list of possible values for the WebDAV permission, e.g. ACCESS or READONLY.

_Example_

```
{
  "description": {
    "default": "Allows to access '/impex' via WebDAV."
  },
  "folder": "/impex",
  "type": "webdav",
  "values": [
    "ACCESS",
    "READONLY"
  ]
}
```

### menu\_action

Document representing a menu action.

*   `description` (_object (localized)_) The description of the menu action.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name of the menu action.
    
    Additional properties: `string`.
    
*   `module_type` (_string_) The module type of the menu action (BM or CC).
*   `name` (_string_) The name of the menu action.
*   `system` (_boolean_) { action.
*   `type` (_string_) The permission type.
*   `values` (_array of string_) The list of possible values for the menu action, e.g. ACCESS or READONLY.

_Example_

```
{
  "description": {
    "default": "Start and control data replication processes."
  },
  "display_name": {
    "default": "Data Replication"
  },
  "module_type": "BM",
  "name": "global-data-rep-processes",
  "system": true,
  "type": "module",
  "values": [
    "ACCESS"
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=5dfc217c207f88d33f3966d3e08d2ac5ec5270c30bfc172e596da38d3fcf5b41 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-product-search.md -->

Data Product Search (deprecated)

# Data Product Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Products

`POST /product_search`

Operation ID: `Search Products`. Tags: product\_search. Security: oauth2\_application.

Searches for products.

Note: This resource does not return information about product master and product variation relationships. Use the ProductSearch SHOP API resource to retrieve more details about product relationships.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. These are the list of searchable attributes with their corresponding buckets:

Main:

*   id - String
    
*   name - String
    
*   online - SiteSpecific Boolean
    
*   searchable - SiteSpecific Boolean
    
*   valid\_from - SiteSpefic DateTime
    
*   valid\_to - SiteSpecfic DateTime
    
*   type - ProductType
    
*   creation\_date - DateTime
    
*   last\_modified - DateTime
    

Catalog:

*   catalog\_id - String
    

Category:

*   category\_id - String
    

Special:

*   type - {"item", "set, "bundle", "master", "part\_of\_product\_set", "bundled", "variant", "variation\_group", "option", "retail\_set", "part\_of\_retail\_set"}
    

The sortable properties are:

*   id - String
    
*   name - String
    
*   creation\_date - DateTime
    

When you specify a catalog\_id or category\_id, only products explicitly assigned to that catalog or category are returned. For example, if a product with variants is assigned to a catalog, but its variants are not, searching on that catalog\_id only returns the main product, not the variants. This behavior is different from that of the product search in Business Manager, which returns products that inherit the selected catalog or category assignment.

Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining id and catalog\_id above, only a conjunction is allowed (AND), whereas id and searchable can be joined using a disjunction because they are in the same bucket. If an attribute is used in a disjunction (OR) that violates this rule, an exception will be thrown.

The product search retrieves additional properties of the product when expansions are used. The available expand attribute values are:

*   'all' will retrieve all the product properties.
    
*   'availability' will retrieve the following properties:
    
    *   ats
        
    *   in\_stock
        
    *   online
        
*   'categories' will retrieve the following properties:
    
    *   assigned\_categories
        
*   'images' will retrieve the following properties:
    
    *   image
        
*   'all\_images' used with images will retrieve the following properties:
    
    *   image
        
    
    *   image\_groups
        
*   'prices' will retrieve the following properties:
    
    *   price
        
    *   price\_currency
        
*   'sets' will retrieve the following properties:
    
    *   set\_products
        
    *   product\_sets
        
*   'bundles' will retrieve the following properties:
    
    *   product\_bundles
        
    *   bundled\_products
        

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Indicates the search query is ill-formed.

#### Parameters

*   `site_id` (query, string) The site context.

#### Request body

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Indicates the search query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### product\_search\_result

Document representing a product search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of product_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "brand": "Brand",
      "id": "my-product",
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product",
      "long_description": {
        "default": "Long Description"
      },
      "manufacturer_name": "main manufacturer",
      "manufacturer_sku": "main manufacturer ID",
      "name": {
        "default": "Main"
      },
      "online": {
        "default": true
      },
      "owning_catalog_id": "my-catalog",
      "owning_catalog_name": {
        "default": "My Catalog"
      },
      "price": 100,
      "price_currency": "USD",
      "price_per_unit": 100,
      "searchable": {
        "default": true
      },
      "short_description": {
        "default": "Short Description"
      },
      "type": {
        "bundled": true,
        "master": true,
        "part_of_product_set": true
      },
      "unit": "mst",
      "unit_measure": "each",
      "unit_quantity": 1,
      "upc": "WapiMain UPC"
    },
    {
      "brand": "QA",
      "id": "my-product2",
      "in_stock": true,
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product2",
      "name": {
        "default": "Offline Categorized Variant 2"
      },
      "online": {
        "default": true
      },
      "searchable": {
        "default": true
      },
      "short_description": {
        "default": "Offline and categorized variant in offline master."
      },
      "type": {
        "variant": true
      }
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id"
      ],
      "search_phrase": "my-product"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### product

Document representing a product

*   `assigned_categories` (_array of catalog\_category\_id_) The catalog categories that the product is assigned to
*   `ats` (_number (double)_) The ATS(Available To Sell) inventory value of the product. This is a calculated value.
*   `brand` (_string_) The brand of the product.
*   `bundled_products` (_array of product_) The array of bundled products which the product includes.
*   `classification_category` (_catalog\_category\_id_) The classification category (default category) of the product
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `default_variant_id` (_string_) The ID of the product's default variant.
*   `ean` (_string_) The European Article Number of the product.
*   `id` (_string_) The ID (SKU) of the product.  
    Minimum length: 1. Maximum length: 100.
*   `image` (_media\_file_) The image(s) assigned to the product.
*   `image_groups` (_array of image\_group_) The array of product image groups.
*   `in_stock` (_boolean_) The flag that indicates if the product is in stock, or not. This is a calculated value.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A link to the product.
*   `localized_tax_class_id` (_object (localized)_)
    
    Additional properties: `string`.
    
*   `long_description` (_object (localized)_) The localized long description of the product.
    
    Additional properties: `markup_text`.
    
*   `manufacturer_name` (_string_) The name of the product's manufacturer.
*   `manufacturer_sku` (_string_) The SKU of the product's manufacturer.
*   `master` (_master_) The master of the product. This is applicable for product types "variation\_group" and "variant" only.
*   `name` (_object (localized)_) The localized name of the product.
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The flag that indicates if the product is online, or not. This is a calculated value.
*   `online_flag` (_object (site-specific)_) The site specific online status of the product.
    
    Additional properties: `boolean`.
    
*   `owning_catalog_id` (_string_) The ID of the catalog that owns the product.
*   `owning_catalog_name` (_object (localized)_) The localized name of the catalog that owns the product.
    
    Additional properties: `string`.
    
*   `page_description` (_object (localized)_) The localized page description of the product.
    
    Additional properties: `string`.
    
*   `page_keywords` (_object (localized)_) The localized page keywords of the product.
    
    Additional properties: `string`.
    
*   `page_title` (_object (localized)_) The localized page title of the product.
    
    Additional properties: `string`.
    
*   `price` (_number (double)_) The price of the product.
*   `price_currency` (_string_) The currency code for product's price.
*   `price_per_unit` (_number (double)_) The price per unit of the product
*   `primary_categories` (_array of catalog\_category\_id_) The catalog categories that are primary for the product
*   `primary_category_id` (_string_) The id of the products primary category.
*   `product_bundles` (_array of product_) The array of product bundles which the product belongs to.
*   `product_options` (_array of product\_option_) The array of product options. This is applicable for products of type "option".
*   `product_sets` (_array of product_) The array of product sets which the product belongs to.
*   `searchable` (_object (site-specific)_) The site specific searchable status of the product.
    
    Additional properties: `boolean`.
    
*   `set_products` (_array of product_) The array of set products which the product includes.
*   `short_description` (_object (localized)_) The localized short description of the product.
    
    Additional properties: `markup_text`.
    
*   `tax_class_id` (_string_) The catalog categories that the product is assigned to
*   `type` (_product\_type_) The type of the product. It can have one or more of the values "item", "master", "variation\_group", "variant", "bundle", and "set".
*   `unit` (_string_) The sales unit of the product.
*   `unit_measure` (_string_) The unitMeasure of the product.
*   `unit_quantity` (_number (double)_) The unitQuantity of the product.
*   `upc` (_string_) The Universal Product Code of the product.
*   `valid_from` (_object (site-specific)_) The time when product is valid from.
    
    Additional properties: `string (date-time)`.
    
*   `valid_to` (_object (site-specific)_) The time when product is valid to.
    
    Additional properties: `string (date-time)`.
    
*   `variants` (_array of variant_) The array of variants of the product. This is applicable for product types "master" and "variation\_group" only.
*   `variation_attributes` (_array of variation\_attribute_) The sorted array of variation attributes assigned to the product. This is applicable for product types "master", "variation\_group" and "variant" only.
*   `variation_groups` (_array of variation\_group_) The array of variation groups in the product. This is applicable for product type "master" only.
*   `variation_values` (_object_)
    
    The variation values selected for the product in variation attribute id and value pairs. This is applicable for product types "variant" and "variation\_group" only.
    
    ```
         Only for type variant and variation group.
    ```
    
    Additional properties: `string`.
    

_Example_

```
{
  "ats": 500,
  "brand": "Brand",
  "ean": "EAN",
  "id": "my-product",
  "in_stock": true,
  "link": "https://example.com/s/-/dw/data/{version}/products/my-product",
  "long_description": {
    "default": "Long Description"
  },
  "manufacturer_name": "Manufacturer",
  "manufacturer_sku": "Manufacturer ID",
  "name": {
    "default": "My Product"
  },
  "online": true,
  "online_flag": {
    "default": true
  },
  "owning_catalog_id": "my-catalog",
  "owning_catalog_name": {
    "default": "My Catalog"
  },
  "page_description": {
    "default": "Page description"
  },
  "page_keywords": {
    "default": "Page Keyword"
  },
  "page_title": {
    "default": "Page title"
  },
  "price": 100,
  "price_currency": "USD",
  "price_per_unit": 100,
  "searchable": {
    "default": true
  },
  "short_description": {
    "default": "Short Description"
  },
  "type": {
    "bundle": true,
    "bundled": true,
    "part_of_product_set": true
  },
  "unit": "bnd",
  "unit_measure": "each",
  "unit_quantity": 1,
  "upc": "UPC"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### catalog\_category\_id

Document representing a catalog category id.

*   `catalog_id` (_string_) The id of the catalog that owns the category.  
    Minimum length: 1. Maximum length: 256.
*   `category_id` (_string_) The id of the category.  
    Minimum length: 1. Maximum length: 256.

### media\_file

*   `abs_url` (_string_) The absolute URL with request protocol (read only)
*   `alt` (_object (localized)_) The alternative image text
    
    Additional properties: `string`.
    
*   `dis_base_url` (_string_) The DIS base URL only for product images
*   `path` (_string_) The raw media file path (only this needs to be provided in update request)
*   `title` (_object (localized)_) The image title
    
    Additional properties: `string`.
    

_Example_

```
{
  "path": "option.jpg"
}
```

### image\_group

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of media\_file_) The images of the image group.
*   `variation_attributes` (_array of variation\_attribute_) Returns a list of variation attributes applying to this image group.
*   `view_type` (_string_) The image view type.

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### master

Document representing a variation master.

*   `link` (_string_) The URL addressing the master product.
*   `master_id` (_string_, required) The id (SKU) of the master product.  
    Minimum length: 1. Maximum length: 100.
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.
*   `price` (_number (double)_) The minimum sales price of the related variants.
*   `price_max` (_number (double)_) The maximum sales of related variants.
*   `price_per_unit` (_number (double)_) The minimum sales price per unit of the related variants.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of the related variants.
*   `prices` (_object_)
    
    Additional properties: `number (double)`.
    

### product\_option

Document representing a product option

*   `custom_name` (_object (localized)_) The localized custom name of the product option.
    
    Additional properties: `string`.
    
*   `default_product_option_value` (_string_) The default product option value.
*   `description` (_object (localized)_) The localized description of the product option.
    
    Additional properties: `string`.
    
*   `id` (_string_) The object attribute definition id which is also the identifier for the product option.  
    Minimum length: 1.
*   `image` (_media\_file_) The image assigned to the product option.
*   `link` (_string_) The URL link to the product option.
*   `name` (_string_) The name of the object attribute definition.
*   `selected_option_value` (_string_) The selected option value of the product option.
*   `shared` (_boolean_) The flag that indicates if the product option is shared or local.
*   `sorting_mode` (_string_) The sorting mode for the product option values.  
    Allowed values: `byexplicitorder`, `byoptionprice`.
*   `values` (_array of product\_option\_value_) The sorted array of values of the product option.

_Example_

```
{
  "custom_name": {
    "default": "Option 15"
  },
  "description": {
    "default": "Description for Option 15"
  },
  "id": "option15",
  "image": {
    "abs_url": "https://example.com/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
    "dis_base_url": "https://example.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
    "path": "Desert.jpg"
  },
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15",
  "name": "15",
  "shared": true,
  "sorting_mode": "byoptionprice",
  "values": [
    {
      "id": "10",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15/Values/10",
      "option_price": {
        "USD": "9.99"
      },
      "sku_extension": "12",
      "value": {
        "default": "12"
      }
    },
    {
      "id": "121",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15/Values/121",
      "option_price": {
        "USD": "19.99"
      },
      "sku_extension": "12",
      "value": {
        "default": "12"
      }
    }
  ]
}
```

### product\_type

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.
*   `bundled` (_boolean_) A flag indicating whether the product is bundled.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.
*   `master` (_boolean_) A flag indicating whether the product is a master.
*   `option` (_boolean_) A flag indicating whether the product is an option.
*   `part_of_product_set` (_boolean_) A flag indicating whether the product is part of product set.
*   `part_of_retail_set` (_boolean_) A flag indicating whether the product is part of retail set.
*   `retail_set` (_boolean_) A flag indicating whether the product is a retail set.
*   `set` (_boolean_) A flag indicating whether the product is a set.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.
*   `variation_group` (_boolean_) A flag indicating whether the product is a variation group.

_Example_

```
{
  "bundled": true,
  "master": true,
  "part_of_product_set": true
}
```

### variant

Document representing a product variation.

*   `ats` (_number (double)_) Inventory "Available to Sell" of the product.
*   `default_product_variation` (_boolean_)
*   `image` (_media\_file_) URL to the preview image.
*   `in_stock` (_boolean_) `true` if the product is in stock, or `false` if not.
*   `link` (_string_) The URL addressing the product.
*   `online` (_boolean_) If the product is currently online. `true` if online `false` if not
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.
*   `price` (_number (double)_) The sales price of the variant.
*   `price_currency` (_string_) Currency code for the price of the product.
*   `price_per_unit` (_number (double)_) The sales price of the variant.
*   `product_id` (_string_, required) The id (SKU) of the variant.  
    Minimum length: 1. Maximum length: 100.
*   `searchable` (_object (site-specific)_)
    
    Additional properties: `boolean`.
    
*   `variation_attributes` (_array of variation\_attribute_) variation attributes
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "https://ocapi-mon.example.com/s/-/dw/data/{version}/products/dress-spring-red",
  "product_id": "dress-spring-red",
  "variation_values": {
    "color": "red"
  }
}
```

### variation\_attribute

Document representing a variation attribute.

*   `attribute_definition_id` (_string_, required) The id of the requested attribute definition.
*   `attribute_definition_name` (_object (localized)_) The localized display name of the variation attribute definition.
    
    Additional properties: `string`.
    
*   `default_value` (_string_) default variation attribute value
*   `id` (_string_) The id of the variation attribute.  
    Minimum length: 1.
*   `link` (_string_) URL that is used to get this instance
*   `name` (_object (localized)_) The localized display name of the variation attribute.
    
    Additional properties: `string`.
    
*   `shared` (_boolean_) Returns the value of attribute 'shared' if attribute is local or shared
*   `slicing` (_boolean_) Returns the value of attribute 'slicing'.
*   `values` (_array of variation\_attribute\_value_) The sorted array of variation values. This array can be empty.
*   `variation_attribute_type` (_string_) variation attribute type  
    Allowed values: `string`, `int`, `unknown`.

_Example_

```
{
  "id": "fabric",
  "name": {
    "default": "Fabric"
  },
  "values": [
    {
      "name": {
        "default": "Leather"
      },
      "value": "leather"
    },
    {
      "name": {
        "default": "Linen"
      },
      "value": "linen"
    },
    {
      "name": {
        "default": "Plastic"
      },
      "value": "plastic"
    },
    {
      "name": {
        "default": "Metal"
      },
      "value": "metal"
    }
  ]
}
```

### variation\_group

Document representing a variation group.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.
*   `price` (_number (double)_) The sales price of the variation group.
*   `price_per_unit` (_number (double)_) The sales price per unit of the variation group.
*   `product_id` (_string_) The id (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "https://example.com/s/-/dw/data/{version}/products/my-product-5",
  "product_id": "my-product-5",
  "variation_values": {
    "color": "red"
  }
}
```

### product\_option\_value

Document representing a product option Value

*   `default_product_option_value` (_boolean_) Flag indicating if the product option value is the default value for the product option.
*   `id` (_string_) The id of the product option value.  
    Minimum length: 1.
*   `link` (_string_) The URL link to the product option value.
*   `option_prices` (_array of money_) The list of prices in the product option value.
*   `sku_extension` (_string_) The sku extension of the product option value.
*   `value` (_object (localized)_) The localized value of the product option.
    
    Additional properties: `string`.
    

_Example_

```
{
  "default_product_option_value": false,
  "id": "value3",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S02",
  "option_prices": [
    {
      "currency_mnemonic": "USD",
      "value": 19.99
    }
  ],
  "sku_extension": "S02",
  "value": {
    "default": "2-year",
    "en": "2-year (en)"
  }
}
```

### variation\_attribute\_value

Document representing a variation attribute value.

*   `description` (_object (localized)_) The localized description of the variation value.
    
    Additional properties: `string`.
    
*   `image` (_media\_file_) The first product image for the configured viewtype and this variation value.
*   `image_swatch` (_media\_file_) The first product image for the configured viewtype and this variation value. (typically the swatch image)
*   `link` (_string_)
*   `name` (_object (localized)_) The localized display name of the variation value.
    
    Additional properties: `string`.
    
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.
*   `position` (_number (double)_) The position of the value among all values of a variation attribute.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1.

_Example_

```
{
  "name": {
    "default": "Leather"
  },
  "value": "leather"
}
```

### money

*   `currency_mnemonic` (_string_) The mnemonic for the money.
*   `value` (_number (double)_) The value for the money.

_Example_

```
{
  "currency_mnemonic": "USD",
  "value": 100
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=d78c16c5fb78f601cb332661f477c35d23aee1f02c4dffdb0715df10bd20be39 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-products.md -->

Data Products (deprecated)

# Data Products (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Product

`GET /products/{id}`

Operation ID: `Get Product`. Tags: products. Security: oauth2\_application.

Action to get product information.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.

#### Parameters

*   `id` (path, string, required) The product ID.  
    Minimum length: 1.
*   `site_id` (query, string) The site context.
*   `expand` (query, array of string)
    
    The list of expansions that can be applied to the product. They are:
    
    *   'all' will retrieve all the product properties.
        
    *   'availability' will retrieve the following properties:
        
        *   ats
            
        *   in\_stock
            
        *   online
            
    *   'images' will retrieve the following properties:
        
        *   image
            
        *   image\_groups
            
    *   'all\_images' used with images will retrieve the following properties, including the images specified for its variants and variation groups:
        
        *   image
            
        *   image\_groups
            
    *   'categories' will retrieve the following properties:
        
        *   assigned\_categories
            
        *   primary\_category
            
        *   classification\_category
            
    *   'options' will retrieve the following properties:
        
        *   product\_options
            
    *   'prices' will retrieve the following properties:
        
        *   price
            
        *   price\_currency
            
    *   'variations' will retrieve the following properties:
        
        *   master
            
        *   variation\_attributes
            
        *   variation\_groups
            
        *   variation\_values
            
        *   variants
            
    *   'sets' will retrieve the following properties:
        
        *   set\_products
            
        *   product\_sets
            
    *   'bundles' will retrieve the following properties:
        
        *   product\_bundles
            
        *   bundled\_products
            
    
    Note that only variants with variation values are retrieved for a product of type variation master.
    

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### PUT Create Product

`PUT /products/{id}`

Operation ID: `Create Product`. Tags: products. Security: oauth2\_application.

Creates a product using the information provided. If a product exists with the same identifier, it is cleared and overwritten unless the request includes the header x-dw-validate-existing=true. Note that the following read-only attributes aren't replaced: `assigned_categories` , `bundled_products` , `classification_category` , `creation_date` , `default_variant_id` , `image` , `image_groups` , `last_modified` , `owning_catalog_name` , `price_per_unit` , `primary_categories` , `primary_category_id` , `product_bundles` , `product_options` , `product_sets` , `set_products` , `type` , `variants` , `variation_attributes` , `variation_groups` , and `variation_values` .

This endpoint may return the following faults:

*   400 - IdConflictException - Indicates the ID in request URL does not match the ID in the product document.
*   400 - ProductDuplicateException - Indicate the product is already existed.
*   400 - ProductInvalidException - Indicates the catalog is not provided in the request.
*   404 - CatalogNotFoundException - Indicates the catalog is not found.

#### Parameters

*   `id` (path, string, required) The product ID.  
    Minimum length: 1. Maximum length: 100.
*   `x-dw-validate-existing` (header, boolean)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product`.

#### Responses

*   **400** `IdConflictException` - Indicates the ID in request URL does not match the ID in the product document. or `ProductDuplicateException` - Indicate the product is already existed. or `ProductInvalidException` - Indicates the catalog is not provided in the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CatalogNotFoundException` - Indicates the catalog is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### DELETE Delete Product

`DELETE /products/{id}`

Operation ID: `Delete Product`. Tags: products. Security: oauth2\_application.

Deletes the product by ID

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.

#### Parameters

*   `id` (path, string, required) The product ID.  
    Minimum length: 1. Maximum length: 100.

#### Responses

*   **204**
*   **404** `ProductNotFoundException` - Indicates the product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Product

`PATCH /products/{id}`

Operation ID: `Update Product`. Tags: products. Security: oauth2\_application.

Update a product using the information provided.

Fields that can be updated: name, page\_description, long\_description, page\_title, page\_keywords, brand, ean,upc, manufacture\_sku, manufacture\_name, searchable, unit, searchable, online\_flag, default\_variant\_id, valid\_to, valid\_from, tax\_class\_id, localized\_tax\_class\_id.

This endpoint may return the following faults:

*   400 - IdConflictException - Indicates the ID in request URL does not match the ID in the product document.
*   400 - ProductDefaultVariantException - Indicates there is a problem to set default variant for a product.
*   404 - ProductNotFoundException - Indicates the product to be updated is not found.

#### Parameters

*   `id` (path, string, required) The product ID.  
    Minimum length: 1. Maximum length: 100.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product`.

#### Responses

*   **400** `IdConflictException` - Indicates the ID in request URL does not match the ID in the product document. or `ProductDefaultVariantException` - Indicates there is a problem to set default variant for a product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product to be updated is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### POST Search Variants

`POST /products/{id}/variant_search`

Operation ID: `Search Variants`. Tags: products. Security: oauth2\_application.

Searches product variations for master product or variation group product.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   id - String
    
*   product\_id - String
    
*   name - String
    
*   online - SiteSpecific Boolean
    
*   in\_stock - Boolean
    
*   searchable - SiteSpecific Boolean
    
*   ats - Actual available quantity to sell - Double
    
*   variation\_attribute.ATTRIBUTE\_ID (Ex:variation\_attribute.color) - String
    

Sortable Fields:

*   id - String
    
*   product\_id - String
    
*   name - String
    
*   online - SiteSpecific Boolean
    
*   in\_stock - Boolean
    
*   searchable - SiteSpecific Boolean
    
*   ats - Actual available quantity to sell - Double
    

Note: The calculated value of "online" and "searchable" is used in the search/sort.

A search/sort by the the site specific attributes require the Site ID query parameter to be set. They are "online", "in\_stock", "searchable" and "ats".

We assume that every field that starts with variation\_attribute. is searchable and dot is followed by ATTRIBUTE\_ID".

The list of expansions to retrieve product information. The expand values available are:

*   \_base - Basic product information is retrieved. This expand is included by default.
    
*   all - All product information including the following properties are retrieved:
    
    *   image
        
    *   price - site\_id has to be provided to see this property
        
    *   price\_currency - site\_id has to be provided to see this property
        
*   availability - Information related to the availability of the product variation. This expand is not included by default.
    
    *   ats - site\_id has to be provided to see this property
        
    *   in\_stock - site\_id has to be provided to see this property
        
    *   online - site\_id has to be provided to see this property
        
    *   searchable
        
*   variations - Information related to product variation is retrieved. This expand is included by default.
    
*   attributes - Information related to product variation attributes is retrieved. This expand is not included by default.
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.
*   400 - ProductNotMasterGroupException - Thrown if the id is not the product id of a Variation Master product or Variation Group product.
*   400 - SiteIdMissingForSiteSpecificFilterException - Thrown if the Site ID query parameter is missing in the search of Variants by a site-specific product attribute.
*   404 - ProductNotFoundException - Thrown if the product is not found.

#### Parameters

*   `id` (path, string, required) The product id of master product or variation group product
*   `site_id` (query, string) The id of the site to get site specific product attributes.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed. or `ProductNotMasterGroupException` - Thrown if the id is not the product id of a Variation Master product or Variation Group product. or `SiteIdMissingForSiteSpecificFilterException` - Thrown if the Site ID query parameter is missing in the search of Variants by a site-specific product attribute.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Thrown if the product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variant_search_result`.
    

### GET Get Variation Groups

`GET /products/{master_product_id}/variation_groups`

Operation ID: `Get Variation Groups`. Tags: products. Security: oauth2\_application.

Reads variation groups for a product master.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates that the given product is not a variation master.
*   404 - ProductNotFoundException - Indicates the master product is not found.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product.  
    Minimum length: 1.
*   `site_id` (query, string) The site context.
*   `start` (query, integer (int32)) The start index of the variation groups to return (defaults to 0).
*   `count` (query, integer (int32)) The maximum number of variation groups to return (defaults to 25).
*   `select` (query, string) A selector that specifies the fields to return in the variation groups document.
*   `expand` (query, array of string) The valid expands are {price,availability}

#### Responses

*   **400** `ProductNotMasterException` - Indicates that the given product is not a variation master.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_groups`.
    

### GET Get Variation Group

`GET /products/{master_product_id}/variation_groups/{id}`

Operation ID: `Get Variation Group`. Tags: products. Security: oauth2\_application.

Read a variation group for a product master.

This endpoint may return the following faults:

*   400 - ProductIsNotVariationGroupException - Indicates the product specified is not a variation group.
*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   404 - ProductNotFoundException - Indicates either the master product or the variation group product cannot be found.
*   404 - VariationGroupNotFoundException - Indicates the product does not belong to the master product.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product that contains the variation group.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation group product.  
    Minimum length: 1.
*   `site_id` (query, string)
*   `expand` (query, array of string) The valid expands are {price,availability}

#### Responses

*   **400** `ProductIsNotVariationGroupException` - Indicates the product specified is not a variation group. or `ProductNotMasterException` - Indicates the master product id does not represent a master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation group product cannot be found. or `VariationGroupNotFoundException` - Indicates the product does not belong to the master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_group`.
    

### PUT Assign Variation Group

`PUT /products/{master_product_id}/variation_groups/{id}`

Operation ID: `Assign Variation Group`. Tags: products. Security: oauth2\_application.

Assign a variation group for a product master. If the variation group product does not initially exist, one is created using the body passed in.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   400 - VariationValueNotValidException - Indicates the values passed are not valid for the variation attributes.
*   404 - ProductNotFoundException - Indicates either the master product or the variation group product cannot be found.
*   404 - VariationAttributeValueNotFoundException - Indicates the value passed into a variation attribute is not one found in the valid values.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product that contains the variation group.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation group product.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_group`.

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product id does not represent a master product. or `VariationValueNotValidException` - Indicates the values passed are not valid for the variation attributes.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation group product cannot be found. or `VariationAttributeValueNotFoundException` - Indicates the value passed into a variation attribute is not one found in the valid values.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_group`.
    

### DELETE Unassign Variation Group

`DELETE /products/{master_product_id}/variation_groups/{id}`

Operation ID: `Unassign Variation Group`. Tags: products. Security: oauth2\_application.

Unassign a variation group product from a product master. The variation group product is not deleted: it remains as a normal product after unsassign.

This endpoint may return the following faults:

*   400 - ProductIsNotVariationGroupException - Indicates product specified is not a variation group.
*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   404 - ProductNotFoundException - Indicates either the master product or the variation group product cannot be found.
*   404 - VariationGroupNotFoundException - Indicates the product does not belong to the master product.

#### Parameters

*   `master_product_id` (path, string, required)  
    Minimum length: 1.
*   `id` (path, string, required)  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `ProductIsNotVariationGroupException` - Indicates product specified is not a variation group. or `ProductNotMasterException` - Indicates the master product id does not represent a master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation group product cannot be found. or `VariationGroupNotFoundException` - Indicates the product does not belong to the master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Variation Group

`PATCH /products/{master_product_id}/variation_groups/{id}`

Operation ID: `Update Variation Group`. Tags: products. Security: oauth2\_application.

Update a variation group for a product master.

This endpoint may return the following faults:

*   400 - ProductIsNotVariationGroupException - Indicates product specified is not a variation group.
*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   400 - VariationValueNotValidException - Indicates the values passed are not valid for the variation attributes.
*   404 - ProductNotFoundException - Indicates either the master product or the variation group product cannot be found.
*   404 - VariationGroupNotFoundException - Indicates the product does not belong to the master product.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product that contains the variation group.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation group product.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_group`.

#### Responses

*   **400** `ProductIsNotVariationGroupException` - Indicates product specified is not a variation group. or `ProductNotMasterException` - Indicates the master product id does not represent a master product. or `VariationValueNotValidException` - Indicates the values passed are not valid for the variation attributes.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation group product cannot be found. or `VariationGroupNotFoundException` - Indicates the product does not belong to the master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_group`.
    

### GET Get Variations

`GET /products/{master_product_id}/variations`

Operation ID: `Get Variations`. Tags: products. Security: oauth2\_application.

Reads variation for a product master.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates that the given product is not a variation master.
*   404 - ProductNotFoundException - Indicates the master product is not found.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product.  
    Minimum length: 1.
*   `site_id` (query, string) The site context.
*   `start` (query, integer (int32)) The start index of the variations to return (defaults to 0).
*   `count` (query, integer (int32)) The maximum number of variations to return (defaults to 25).
*   `select` (query, string) A selector that specifies the fields to return in the variations document.
*   `expand` (query, array of string) The valid expands are {price,availability}

#### Responses

*   **400** `ProductNotMasterException` - Indicates that the given product is not a variation master.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variants`.
    

### GET Get Variation

`GET /products/{master_product_id}/variations/{id}`

Operation ID: `Get Variation`. Tags: products. Security: oauth2\_application.

Read a variation for a product master.

This endpoint may return the following faults:

*   400 - ProductIsNotVariationException - Indicates the product specified is not a variation.
*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   404 - ProductNotFoundException - Indicates either the master product or the variation product cannot be found.
*   404 - VariationNotFoundException - Indicates the product does not belong to the master product.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product that contains the variation.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation product.  
    Minimum length: 1.
*   `site_id` (query, string)
*   `expand` (query, array of string) The valid expands are {variation,attributes,availability,prices}

#### Responses

*   **400** `ProductIsNotVariationException` - Indicates the product specified is not a variation. or `ProductNotMasterException` - Indicates the master product id does not represent a master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation product cannot be found. or `VariationNotFoundException` - Indicates the product does not belong to the master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variant`.
    

### PUT Assign Variation

`PUT /products/{master_product_id}/variations/{id}`

Operation ID: `Assign Variation`. Tags: products. Security: oauth2\_application.

Assign a variation for a product master. If the variation product does not initially exist, one is created using the body passed in.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   400 - VariationValueNotValidException - Indicates the values passed are not valid for the variation attributes.
*   404 - ProductNotFoundException - Indicates either the master product or the variation product cannot be found.
*   404 - VariationAttributeValueNotFoundException - Indicates the value passed into a variation attribute is not one found in the valid values.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product that contains the variation.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation product.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variant`.

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product id does not represent a master product. or `VariationValueNotValidException` - Indicates the values passed are not valid for the variation attributes.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation product cannot be found. or `VariationAttributeValueNotFoundException` - Indicates the value passed into a variation attribute is not one found in the valid values.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variant`.
    

### DELETE Unassign Variation Product

`DELETE /products/{master_product_id}/variations/{id}`

Operation ID: `Unassign Variation Product`. Tags: products. Security: oauth2\_application.

Unassign a variation product from a product master. The variation product is not deleted: it remains as a normal product after unsassign.

This endpoint may return the following faults:

*   400 - ProductIsNotVariationException - Indicates product specified is not a variation.
*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   404 - ProductNotFoundException - Indicates either the master product or the variation product cannot be found.
*   404 - VariationNotFoundException - Indicates the product does not belong to the master product.

#### Parameters

*   `master_product_id` (path, string, required)  
    Minimum length: 1.
*   `id` (path, string, required)  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `ProductIsNotVariationException` - Indicates product specified is not a variation. or `ProductNotMasterException` - Indicates the master product id does not represent a master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation product cannot be found. or `VariationNotFoundException` - Indicates the product does not belong to the master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Variation

`PATCH /products/{master_product_id}/variations/{id}`

Operation ID: `Update Variation`. Tags: products. Security: oauth2\_application.

Update a variation for a product master.

This endpoint may return the following faults:

*   400 - ProductIsNotVariationException - Indicates product specified is not a variation.
*   400 - ProductNotMasterException - Indicates the master product id does not represent a master product.
*   400 - VariationValueNotValidException - Indicates the values passed are not valid for the variation attributes.
*   404 - ProductNotFoundException - Indicates either the master product or the variation product cannot be found.
*   404 - VariationNotFoundException - Indicates the product does not belong to the master product.

#### Parameters

*   `master_product_id` (path, string, required) The id of the master product that contains the variation.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation product.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variant`.

#### Responses

*   **400** `ProductIsNotVariationException` - Indicates product specified is not a variation. or `ProductNotMasterException` - Indicates the master product id does not represent a master product. or `VariationValueNotValidException` - Indicates the values passed are not valid for the variation attributes.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates either the master product or the variation product cannot be found. or `VariationNotFoundException` - Indicates the product does not belong to the master product.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variant`.
    

### GET Get Local and Shared Product Options

`GET /products/{product_id}/product_options`

Operation ID: `Get Local and Shared Product Options`. Tags: products. Security: oauth2\_application.

Read local and shared product options of a product.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `currency` (query, string) The currency mnemonic for retrieving the product option values according to the sorting mode.ex:'USD'

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_options`.
    

### GET Get Local or Shared Product Option

`GET /products/{product_id}/product_options/{id}`

Operation ID: `Get Local or Shared Product Option`. Tags: products. Security: oauth2\_application.

Read a local or shared product option of a product.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local or shared product option is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the local or shared product option.  
    Minimum length: 1.
*   `currency` (query, string) The currency mnemonic for retrieving the product option values according to the sorting mode.ex:'USD'

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local or shared product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option`.
    

### PUT Create Local Product Option, Bind Shared Product Option

`PUT /products/{product_id}/product_options/{id}`

Operation ID: `Create Local Product Option, Bind Shared Product Option`. Tags: products. Security: oauth2\_application.

Creates a local product option using the information provided or binds a shared product option to the product.

This endpoint may return the following faults:

*   400 - ProductOptionCreateException - Indicates the local product option cannot be created for a product of type variation group.
*   404 - ProductNotFoundException - Indicates the product is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the local or shared product option.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option`.

#### Responses

*   **400** `ProductOptionCreateException` - Indicates the local product option cannot be created for a product of type variation group.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option`.
    

### DELETE Delete Local Product Option, Unbind Shared Product Option

`DELETE /products/{product_id}/product_options/{id}`

Operation ID: `Delete Local Product Option, Unbind Shared Product Option`. Tags: products. Security: oauth2\_application.

Deletes a local product option or unbinds a shared product option from the product.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local or shared product option is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the local or shared product option.

#### Responses

*   **204**
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local or shared product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Product Option

`PATCH /products/{product_id}/product_options/{id}`

Operation ID: `Update Product Option`. Tags: products. Security: oauth2\_application.

Updates a local product option with the information provided.

This endpoint may return the following faults:

*   400 - ProductOptionUpdateException - Indicates the shared product option cannot be updated.
*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local product option is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the local product option.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option`.

#### Responses

*   **400** `ProductOptionUpdateException` - Indicates the shared product option cannot be updated.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option`.
    

### GET Get Local Product Option Values

`GET /products/{product_id}/product_options/{option_id}/values`

Operation ID: `Get Local Product Option Values`. Tags: products. Security: oauth2\_application.

Read local product option values of a local product option in a product.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local product option is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the local product option.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_values`.
    

### GET Get Local Product Option Value

`GET /products/{product_id}/product_options/{option_id}/values/{id}`

Operation ID: `Get Local Product Option Value`. Tags: products. Security: oauth2\_application.

Read a local product option value of a local product option in a product.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local product option is not found.
*   404 - ProductOptionValueNotFoundException - Indicates the local product option value is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the local product option.  
    Minimum length: 1.
*   `id` (path, string, required) the id of local product option value.  
    Minimum length: 1.

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local product option is not found. or `ProductOptionValueNotFoundException` - Indicates the local product option value is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_value`.
    

### PUT Create Local Product Option Value

`PUT /products/{product_id}/product_options/{option_id}/values/{id}`

Operation ID: `Create Local Product Option Value`. Tags: products. Security: oauth2\_application.

Creates a local product option value using the information provided.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local product option is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the local product option.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the local product option value.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option_value`.

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local product option is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_value`.
    

### DELETE Delete Local Product Option Value

`DELETE /products/{product_id}/product_options/{option_id}/values/{id}`

Operation ID: `Delete Local Product Option Value`. Tags: products. Security: oauth2\_application.

Deletes a local product option value by ID.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local product option is not found.
*   404 - ProductOptionValueNotFoundException - Indicates the local product option value is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the local product option.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the local product option value.

#### Responses

*   **204**
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local product option is not found. or `ProductOptionValueNotFoundException` - Indicates the local product option value is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Local Product Option Value

`PATCH /products/{product_id}/product_options/{option_id}/values/{id}`

Operation ID: `Update Local Product Option Value`. Tags: products. Security: oauth2\_application.

Updates a local product option value with the information provided.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - ProductOptionNotFoundException - Indicates the local product option is not found.
*   404 - ProductOptionValueNotFoundException - Indicates the local product option value is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `option_id` (path, string, required) The id of the local product option.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the local product option value.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_option_value`.

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found. or `ProductOptionNotFoundException` - Indicates the local product option is not found. or `ProductOptionValueNotFoundException` - Indicates the local product option value is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_option_value`.
    

### GET Get Variation Attributes

`GET /products/{product_id}/variation_attributes`

Operation ID: `Get Variation Attributes`. Tags: products. Security: oauth2\_application.

Reads variation attributes of a product of type variant or variation master or variation group.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates the product is not found.

#### Parameters

*   `product_id` (path, string, required) The product ID of a variant or a variation master or a variation group.  
    Minimum length: 1.
*   `start` (query, integer (int32))
*   `count` (query, integer (int32))
*   `select` (query, string)

#### Responses

*   **404** `ProductNotFoundException` - Indicates the product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attributes`.
    

### GET Get Product Variation Attribute Values

`GET /products/{product_id}/variation_attributes/{attribute_id}/values`

Operation ID: `Get Product Variation Attribute Values`. Tags: products. Security: oauth2\_application.

Reads variation attribute values of a variation attribute bound to a product.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product is not found.
*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - VariationAttributeNotFoundException - If the attribute id specified is not a valid product attribute.

#### Parameters

*   `product_id` (path, string, required) id of the product  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The variation attribute ID that contains the values.  
    Minimum length: 1.
*   `site_id` (query, string)
*   `start` (query, integer (int32)) the first record to get in the page
*   `count` (query, integer (int32)) the number of records to get
*   `select` (query, string) a string that specifies which fields to return (default is all).
*   `expand` (query, array of string) set of expands to retrieve additional information: {availability, image}

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `VariationAttributeNotFoundException` - If the attribute id specified is not a valid product attribute.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_values`.
    

### GET Get Product Variation Attribute Value

`GET /products/{product_id}/variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Get Product Variation Attribute Value`. Tags: products. Security: oauth2\_application.

Action to get product variation attribute value information.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product is not found.
*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - VariationAttributeValueNotFoundException - If the value id specified is not a valid value id.

#### Parameters

*   `product_id` (path, string, required) The master product ID.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The variation attribute custom ID  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation attribute value  
    Minimum length: 1.
*   `site_id` (query, string) The site context.
*   `expand` (query, array of string) set of expands to retrieve additional information: {availability, image}

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `VariationAttributeValueNotFoundException` - If the value id specified is not a valid value id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.
    

### PUT Put Product Variation Attribute Value

`PUT /products/{product_id}/variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Put Product Variation Attribute Value`. Tags: products. Security: oauth2\_application.

Action to create a product variation attribute value.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product is not found.
*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - VariationAttributeNotFoundException - If the attribute id specified is not a valid product attribute.
*   404 - VariationAttributeValueNotFoundException - If the value id specified is not a valid value id.

#### Parameters

*   `product_id` (path, string, required) The master product ID.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The variation attribute ID  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation attribute value  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `VariationAttributeNotFoundException` - If the attribute id specified is not a valid product attribute. or `VariationAttributeValueNotFoundException` - If the value id specified is not a valid value id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.
    

### DELETE Delete Product Variation Attribute Value

`DELETE /products/{product_id}/variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Delete Product Variation Attribute Value`. Tags: products. Security: oauth2\_application.

Deletes the variation attribute value of a variation attribute bound to a master product

This endpoint may return the following faults:

*   404 - ProductNotFoundException - If the product id specified cannot be found.
*   404 - VariationAttributeNotFoundException - If the attribute id specified is not a valid product attribute.
*   404 - VariationAttributeValueNotFoundException - If the value id specified is not a valid value id.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The id of the variation attribute that contains the value.  
    Minimum length: 1.
*   `id` (path, string, required) The id of one value to remove

#### Responses

*   **204**
*   **404** `ProductNotFoundException` - If the product id specified cannot be found. or `VariationAttributeNotFoundException` - If the attribute id specified is not a valid product attribute. or `VariationAttributeValueNotFoundException` - If the value id specified is not a valid value id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Product Variation Attribute Value

`PATCH /products/{product_id}/variation_attributes/{attribute_id}/values/{id}`

Operation ID: `Update Product Variation Attribute Value`. Tags: products. Security: oauth2\_application.

Updates the variation attribute value of a variation attribute of a master product.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - If the product id specified cannot be found.
*   404 - VariationAttributeNotFoundException - If the attribute id specified is not a valid product attribute.
*   404 - VariationAttributeValueNotFoundException - If the value id specified is not a valid value id.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `attribute_id` (path, string, required) The id of the requested variation attribute.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation value.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.

#### Responses

*   **404** `ProductNotFoundException` - If the product id specified cannot be found. or `VariationAttributeNotFoundException` - If the attribute id specified is not a valid product attribute. or `VariationAttributeValueNotFoundException` - If the value id specified is not a valid value id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute_value`.
    

### GET Get Variation Attribute

`GET /products/{product_id}/variation_attributes/{id}`

Operation ID: `Get Variation Attribute`. Tags: products. Security: oauth2\_application.

Action to get variation attribute information only for master product.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product is not found.
*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - VariationAttributeNotFoundException - Indicates that the variation attribute is not found.

#### Parameters

*   `product_id` (path, string, required) The product ID of a variant or a variation master or a variation group.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested variation attribute.  
    Minimum length: 1.

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `VariationAttributeNotFoundException` - Indicates that the variation attribute is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute`.
    

### PUT Create Variation Attribute

`PUT /products/{product_id}/variation_attributes/{id}`

Operation ID: `Create Variation Attribute`. Tags: products. Security: oauth2\_application.

Creates a local variation attribute using the information provided. This endpoint can't create shared variation attributes. To create a shared variation attribute, use the catalogs resource.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product is not found.
*   400 - ProductVariationAttributeDefinitionNotUniqueException - Indicates that the variation attribute definition is not unique.
*   400 - ProductVariationAttributeIDNotUniqueException - Indicates that the variation attribute id is not unique.
*   500 - AttributeDefinitionNotFoundException - If attribute definition supplied is not a product attribute.
*   404 - ProductNotFoundException - Indicates the product is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the variation attribute to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute`.

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product is not found. or `ProductVariationAttributeDefinitionNotUniqueException` - Indicates that the variation attribute definition is not unique. or `ProductVariationAttributeIDNotUniqueException` - Indicates that the variation attribute id is not unique.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - If attribute definition supplied is not a product attribute.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute`.
    

### DELETE Delete Variation Attribute

`DELETE /products/{product_id}/variation_attributes/{id}`

Operation ID: `Delete Variation Attribute`. Tags: products. Security: oauth2\_application.

Deletes a variation attribute by ID.

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product is not found.
*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - VariationAttributeNotFoundException - Indicates that the variation attribute is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `id` (path, string, required) One variation attribute id to remove.

#### Responses

*   **204**
*   **400** `ProductNotMasterException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `VariationAttributeNotFoundException` - Indicates that the variation attribute is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Variation Attribute

`PATCH /products/{product_id}/variation_attributes/{id}`

Operation ID: `Update Variation Attribute`. Tags: products. Security: oauth2\_application.

Updates the variation attribute with the specified information.

*   name
    
*   slicing
    

This endpoint may return the following faults:

*   400 - ProductNotMasterException - Indicates the master product is not found.
*   404 - ProductNotFoundException - Indicates the product is not found.
*   404 - VariationAttributeNotFoundException - Indicates that the variation attribute is not found.

#### Parameters

*   `product_id` (path, string, required) The id of the product.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested variation attribute.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `variation_attribute`.

#### Responses

*   **400** `ProductNotMasterException` - Indicates the master product is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - Indicates the product is not found. or `VariationAttributeNotFoundException` - Indicates that the variation attribute is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `variation_attribute`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### product

Document representing a product

*   `assigned_categories` (_array of catalog\_category\_id_) The catalog categories that the product is assigned to
*   `ats` (_number (double)_) The ATS(Available To Sell) inventory value of the product. This is a calculated value.
*   `brand` (_string_) The brand of the product.
*   `bundled_products` (_array of product_) The array of bundled products which the product includes.
*   `classification_category` (_catalog\_category\_id_) The classification category (default category) of the product
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `default_variant_id` (_string_) The ID of the product's default variant.
*   `ean` (_string_) The European Article Number of the product.
*   `id` (_string_) The ID (SKU) of the product.  
    Minimum length: 1. Maximum length: 100.
*   `image` (_media\_file_) The image(s) assigned to the product.
*   `image_groups` (_array of image\_group_) The array of product image groups.
*   `in_stock` (_boolean_) The flag that indicates if the product is in stock, or not. This is a calculated value.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A link to the product.
*   `localized_tax_class_id` (_object (localized)_)
    
    Additional properties: `string`.
    
*   `long_description` (_object (localized)_) The localized long description of the product.
    
    Additional properties: `markup_text`.
    
*   `manufacturer_name` (_string_) The name of the product's manufacturer.
*   `manufacturer_sku` (_string_) The SKU of the product's manufacturer.
*   `master` (_master_) The master of the product. This is applicable for product types "variation\_group" and "variant" only.
*   `name` (_object (localized)_) The localized name of the product.
    
    Additional properties: `string`.
    
*   `online` (_boolean_) The flag that indicates if the product is online, or not. This is a calculated value.
*   `online_flag` (_object (site-specific)_) The site specific online status of the product.
    
    Additional properties: `boolean`.
    
*   `owning_catalog_id` (_string_) The ID of the catalog that owns the product.
*   `owning_catalog_name` (_object (localized)_) The localized name of the catalog that owns the product.
    
    Additional properties: `string`.
    
*   `page_description` (_object (localized)_) The localized page description of the product.
    
    Additional properties: `string`.
    
*   `page_keywords` (_object (localized)_) The localized page keywords of the product.
    
    Additional properties: `string`.
    
*   `page_title` (_object (localized)_) The localized page title of the product.
    
    Additional properties: `string`.
    
*   `price` (_number (double)_) The price of the product.
*   `price_currency` (_string_) The currency code for product's price.
*   `price_per_unit` (_number (double)_) The price per unit of the product
*   `primary_categories` (_array of catalog\_category\_id_) The catalog categories that are primary for the product
*   `primary_category_id` (_string_) The id of the products primary category.
*   `product_bundles` (_array of product_) The array of product bundles which the product belongs to.
*   `product_options` (_array of product\_option_) The array of product options. This is applicable for products of type "option".
*   `product_sets` (_array of product_) The array of product sets which the product belongs to.
*   `searchable` (_object (site-specific)_) The site specific searchable status of the product.
    
    Additional properties: `boolean`.
    
*   `set_products` (_array of product_) The array of set products which the product includes.
*   `short_description` (_object (localized)_) The localized short description of the product.
    
    Additional properties: `markup_text`.
    
*   `tax_class_id` (_string_) The catalog categories that the product is assigned to
*   `type` (_product\_type_) The type of the product. It can have one or more of the values "item", "master", "variation\_group", "variant", "bundle", and "set".
*   `unit` (_string_) The sales unit of the product.
*   `unit_measure` (_string_) The unitMeasure of the product.
*   `unit_quantity` (_number (double)_) The unitQuantity of the product.
*   `upc` (_string_) The Universal Product Code of the product.
*   `valid_from` (_object (site-specific)_) The time when product is valid from.
    
    Additional properties: `string (date-time)`.
    
*   `valid_to` (_object (site-specific)_) The time when product is valid to.
    
    Additional properties: `string (date-time)`.
    
*   `variants` (_array of variant_) The array of variants of the product. This is applicable for product types "master" and "variation\_group" only.
*   `variation_attributes` (_array of variation\_attribute_) The sorted array of variation attributes assigned to the product. This is applicable for product types "master", "variation\_group" and "variant" only.
*   `variation_groups` (_array of variation\_group_) The array of variation groups in the product. This is applicable for product type "master" only.
*   `variation_values` (_object_)
    
    The variation values selected for the product in variation attribute id and value pairs. This is applicable for product types "variant" and "variation\_group" only.
    
    ```
         Only for type variant and variation group.
    ```
    
    Additional properties: `string`.
    

_Example_

```
{
  "ats": 500,
  "brand": "Brand",
  "ean": "EAN",
  "id": "my-product",
  "in_stock": true,
  "link": "https://example.com/s/-/dw/data/{version}/products/my-product",
  "long_description": {
    "default": "Long Description"
  },
  "manufacturer_name": "Manufacturer",
  "manufacturer_sku": "Manufacturer ID",
  "name": {
    "default": "My Product"
  },
  "online": true,
  "online_flag": {
    "default": true
  },
  "owning_catalog_id": "my-catalog",
  "owning_catalog_name": {
    "default": "My Catalog"
  },
  "page_description": {
    "default": "Page description"
  },
  "page_keywords": {
    "default": "Page Keyword"
  },
  "page_title": {
    "default": "Page title"
  },
  "price": 100,
  "price_currency": "USD",
  "price_per_unit": 100,
  "searchable": {
    "default": true
  },
  "short_description": {
    "default": "Short Description"
  },
  "type": {
    "bundle": true,
    "bundled": true,
    "part_of_product_set": true
  },
  "unit": "bnd",
  "unit_measure": "each",
  "unit_quantity": 1,
  "upc": "UPC"
}
```

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### variant\_search\_result

Document that represents a search on certificates and keys.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of variant_) The hits from the search
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "expand": [
    "variations"
  ],
  "hits": [
    {
      "link": "https://ocapi-mon.example.com/s/-/dw/data/{version}/products/dress-spring-red",
      "product_id": "dress-spring-red",
      "variation_values": {
        "color": "red"
      }
    },
    {
      "link": "https://ocapi-mon.example.com/s/-/dw/data/{version}/products/dress-spring-blue",
      "product_id": "dress-spring-blue",
      "variation_values": {
        "color": "blue"
      }
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id"
      ],
      "search_phrase": "dress"
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 2
}
```

### variation\_groups

Document representing an unfiltered list of variation groups.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of variation\_group_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-5",
      "product_id": "my-product-5",
      "variation_values": {
        "color": "red"
      }
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-6",
      "product_id": "my-product-6",
      "variation_values": {
        "color": "black"
      }
    }
  ],
  "start": 0,
  "total": 2
}
```

### variation\_group

Document representing a variation group.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.
*   `price` (_number (double)_) The sales price of the variation group.
*   `price_per_unit` (_number (double)_) The sales price per unit of the variation group.
*   `product_id` (_string_) The id (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "https://example.com/s/-/dw/data/{version}/products/my-product-5",
  "product_id": "my-product-5",
  "variation_values": {
    "color": "red"
  }
}
```

### variants

Document representing an unfiltered list of variants.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of variant_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 9,
  "data": [
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-1",
      "product_id": "my-product-1"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-2",
      "product_id": "my-product-2"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-3",
      "product_id": "my-product-3"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-4",
      "product_id": "my-product-4"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-5",
      "product_id": "my-product-5"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-6",
      "product_id": "my-product-6"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-7",
      "product_id": "my-product-7"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-8",
      "product_id": "my-product-8"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/my-product-9",
      "product_id": "my-product-9"
    }
  ],
  "start": 0,
  "total": 9
}
```

### variant

Document representing a product variation.

*   `ats` (_number (double)_) Inventory "Available to Sell" of the product.
*   `default_product_variation` (_boolean_)
*   `image` (_media\_file_) URL to the preview image.
*   `in_stock` (_boolean_) `true` if the product is in stock, or `false` if not.
*   `link` (_string_) The URL addressing the product.
*   `online` (_boolean_) If the product is currently online. `true` if online `false` if not
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.
*   `price` (_number (double)_) The sales price of the variant.
*   `price_currency` (_string_) Currency code for the price of the product.
*   `price_per_unit` (_number (double)_) The sales price of the variant.
*   `product_id` (_string_, required) The id (SKU) of the variant.  
    Minimum length: 1. Maximum length: 100.
*   `searchable` (_object (site-specific)_)
    
    Additional properties: `boolean`.
    
*   `variation_attributes` (_array of variation\_attribute_) variation attributes
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "https://ocapi-mon.example.com/s/-/dw/data/{version}/products/dress-spring-red",
  "product_id": "dress-spring-red",
  "variation_values": {
    "color": "red"
  }
}
```

### product\_options

Document representing an unfiltered list of product options.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of product\_option_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "custom_name": {
        "default": "Shared Service"
      },
      "default_product_option_value": "S00",
      "description": {
        "default": "Service description"
      },
      "id": "service",
      "image": {
        "abs_url": "https://example.com/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
        "dis_base_url": "https://example.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
        "path": "Desert.jpg"
      },
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service",
      "name": "Shared Service",
      "shared": true,
      "sorting_mode": "byexplicitorder",
      "values": [
        {
          "id": "S00",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service/Values/S00",
          "sku_extension": "S00",
          "value": {
            "default": "None"
          }
        },
        {
          "id": "S01",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service/Values/S01",
          "option_price": {
            "USD": "9.99"
          },
          "sku_extension": "S01",
          "value": {
            "default": "1-year"
          }
        },
        {
          "id": "S02",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/service/Values/S02",
          "option_price": {
            "USD": "19.99"
          },
          "sku_extension": "S02",
          "value": {
            "default": "2-year"
          }
        }
      ]
    },
    {
      "custom_name": {
        "default": "Extended Warranty"
      },
      "default_product_option_value": "000",
      "id": "warranty",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty",
      "name": "Extended Warranty",
      "shared": true,
      "sorting_mode": "byoptionprice",
      "values": [
        {
          "id": "001",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/001",
          "option_price": {
            "USD": "9.99"
          },
          "value": {
            "default": "1 Year Warranty"
          }
        },
        {
          "id": "003",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/003",
          "option_price": {
            "USD": "29.99"
          },
          "value": {
            "default": "5 Year Warranty"
          }
        },
        {
          "id": "000",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/000",
          "option_price": {
            "USD": "39.99"
          },
          "value": {
            "default": "None"
          }
        },
        {
          "id": "002",
          "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/warranty/Values/002",
          "option_price": {
            "USD": "49.99"
          },
          "value": {
            "default": "3 Year Warranty"
          }
        }
      ]
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 2
}
```

### product\_option

Document representing a product option

*   `custom_name` (_object (localized)_) The localized custom name of the product option.
    
    Additional properties: `string`.
    
*   `default_product_option_value` (_string_) The default product option value.
*   `description` (_object (localized)_) The localized description of the product option.
    
    Additional properties: `string`.
    
*   `id` (_string_) The object attribute definition id which is also the identifier for the product option.  
    Minimum length: 1.
*   `image` (_media\_file_) The image assigned to the product option.
*   `link` (_string_) The URL link to the product option.
*   `name` (_string_) The name of the object attribute definition.
*   `selected_option_value` (_string_) The selected option value of the product option.
*   `shared` (_boolean_) The flag that indicates if the product option is shared or local.
*   `sorting_mode` (_string_) The sorting mode for the product option values.  
    Allowed values: `byexplicitorder`, `byoptionprice`.
*   `values` (_array of product\_option\_value_) The sorted array of values of the product option.

_Example_

```
{
  "custom_name": {
    "default": "Option 15"
  },
  "description": {
    "default": "Description for Option 15"
  },
  "id": "option15",
  "image": {
    "abs_url": "https://example.com/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
    "dis_base_url": "https://example.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-my-catalog/default/vc8f08a6edba0d7c8e1dec6c535661e44154b54b4/Desert.jpg",
    "path": "Desert.jpg"
  },
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15",
  "name": "15",
  "shared": true,
  "sorting_mode": "byoptionprice",
  "values": [
    {
      "id": "10",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15/Values/10",
      "option_price": {
        "USD": "9.99"
      },
      "sku_extension": "12",
      "value": {
        "default": "12"
      }
    },
    {
      "id": "121",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/option15/Values/121",
      "option_price": {
        "USD": "19.99"
      },
      "sku_extension": "12",
      "value": {
        "default": "12"
      }
    }
  ]
}
```

### product\_option\_values

Document representing an unfiltered list of product option values.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of product\_option\_value_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 3,
  "data": [
    {
      "default_product_option_value": true,
      "id": "value1",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S00",
      "sku_extension": "S00",
      "value": {
        "default": "None",
        "en": "None (en)"
      }
    },
    {
      "default_product_option_value": false,
      "id": "value2",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S01",
      "option_prices": [
        {
          "currency_mnemonic": "USD",
          "value": 9.99
        }
      ],
      "sku_extension": "S01",
      "value": {
        "default": "1-year",
        "en": "1-year (en)"
      }
    },
    {
      "default_product_option_value": false,
      "id": "value3",
      "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S02",
      "option_prices": [
        {
          "currency_mnemonic": "USD",
          "value": 19.99
        }
      ],
      "sku_extension": "S02",
      "value": {
        "default": "2-year",
        "en": "2-year (en)"
      }
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 3
}
```

### product\_option\_value

Document representing a product option Value

*   `default_product_option_value` (_boolean_) Flag indicating if the product option value is the default value for the product option.
*   `id` (_string_) The id of the product option value.  
    Minimum length: 1.
*   `link` (_string_) The URL link to the product option value.
*   `option_prices` (_array of money_) The list of prices in the product option value.
*   `sku_extension` (_string_) The sku extension of the product option value.
*   `value` (_object (localized)_) The localized value of the product option.
    
    Additional properties: `string`.
    

_Example_

```
{
  "default_product_option_value": false,
  "id": "value3",
  "link": "https://example.com/s/-/dw/data/{version}/catalogs/my-catalog/shared_product_options/my-option/values/S02",
  "option_prices": [
    {
      "currency_mnemonic": "USD",
      "value": 19.99
    }
  ],
  "sku_extension": "S02",
  "value": {
    "default": "2-year",
    "en": "2-year (en)"
  }
}
```

### variation\_attributes

Document representing an unfiltered list of variation attributes.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of variation\_attribute_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 3,
  "data": [
    {
      "id": "fabric",
      "name": {
        "default": "Fabric"
      },
      "values": [
        {
          "name": {
            "default": "Leather"
          },
          "value": "leather"
        },
        {
          "name": {
            "default": "Linen"
          },
          "value": "linen"
        },
        {
          "name": {
            "default": "Plastic"
          },
          "value": "plastic"
        },
        {
          "name": {
            "default": "Metal"
          },
          "value": "metal"
        }
      ]
    },
    {
      "id": "color",
      "name": {
        "default": "Color"
      },
      "values": [
        {
          "name": {
            "default": "Red"
          },
          "value": "red"
        },
        {
          "name": {
            "default": "Blue"
          },
          "value": "blue"
        },
        {
          "name": {
            "default": "Black"
          },
          "value": "black"
        }
      ]
    },
    {
      "id": "size",
      "name": {
        "default": "Size"
      },
      "values": [
        {
          "description": {
            "default": "Small"
          },
          "name": {
            "default": "Small"
          },
          "value": "S"
        },
        {
          "description": {
            "default": "Medium"
          },
          "name": {
            "default": "Medium"
          },
          "value": "M"
        },
        {
          "description": {
            "default": "Large"
          },
          "name": {
            "default": "Large"
          },
          "value": "L"
        }
      ]
    }
  ],
  "start": 0,
  "total": 3
}
```

### variation\_attribute\_values

Document representing an unfiltered list of variation attribute values.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of variation\_attribute\_value_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 3,
  "data": [
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/master_product_1/variation_attributes/color/values/red",
      "value": "red"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/master_product_1/variation_attributes/color/values/blue",
      "value": "blue"
    },
    {
      "link": "https://example.com/s/-/dw/data/{version}/products/master_product_1/variation_attributes/color/values/black",
      "value": "black"
    }
  ],
  "select": "(*,data.(value,link))",
  "start": 0,
  "total": 3
}
```

### variation\_attribute\_value

Document representing a variation attribute value.

*   `description` (_object (localized)_) The localized description of the variation value.
    
    Additional properties: `string`.
    
*   `image` (_media\_file_) The first product image for the configured viewtype and this variation value.
*   `image_swatch` (_media\_file_) The first product image for the configured viewtype and this variation value. (typically the swatch image)
*   `link` (_string_)
*   `name` (_object (localized)_) The localized display name of the variation value.
    
    Additional properties: `string`.
    
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.
*   `position` (_number (double)_) The position of the value among all values of a variation attribute.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1.

_Example_

```
{
  "name": {
    "default": "Leather"
  },
  "value": "leather"
}
```

### variation\_attribute

Document representing a variation attribute.

*   `attribute_definition_id` (_string_, required) The id of the requested attribute definition.
*   `attribute_definition_name` (_object (localized)_) The localized display name of the variation attribute definition.
    
    Additional properties: `string`.
    
*   `default_value` (_string_) default variation attribute value
*   `id` (_string_) The id of the variation attribute.  
    Minimum length: 1.
*   `link` (_string_) URL that is used to get this instance
*   `name` (_object (localized)_) The localized display name of the variation attribute.
    
    Additional properties: `string`.
    
*   `shared` (_boolean_) Returns the value of attribute 'shared' if attribute is local or shared
*   `slicing` (_boolean_) Returns the value of attribute 'slicing'.
*   `values` (_array of variation\_attribute\_value_) The sorted array of variation values. This array can be empty.
*   `variation_attribute_type` (_string_) variation attribute type  
    Allowed values: `string`, `int`, `unknown`.

_Example_

```
{
  "id": "fabric",
  "name": {
    "default": "Fabric"
  },
  "values": [
    {
      "name": {
        "default": "Leather"
      },
      "value": "leather"
    },
    {
      "name": {
        "default": "Linen"
      },
      "value": "linen"
    },
    {
      "name": {
        "default": "Plastic"
      },
      "value": "plastic"
    },
    {
      "name": {
        "default": "Metal"
      },
      "value": "metal"
    }
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### catalog\_category\_id

Document representing a catalog category id.

*   `catalog_id` (_string_) The id of the catalog that owns the category.  
    Minimum length: 1. Maximum length: 256.
*   `category_id` (_string_) The id of the category.  
    Minimum length: 1. Maximum length: 256.

### media\_file

*   `abs_url` (_string_) The absolute URL with request protocol (read only)
*   `alt` (_object (localized)_) The alternative image text
    
    Additional properties: `string`.
    
*   `dis_base_url` (_string_) The DIS base URL only for product images
*   `path` (_string_) The raw media file path (only this needs to be provided in update request)
*   `title` (_object (localized)_) The image title
    
    Additional properties: `string`.
    

_Example_

```
{
  "path": "option.jpg"
}
```

### image\_group

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of media\_file_) The images of the image group.
*   `variation_attributes` (_array of variation\_attribute_) Returns a list of variation attributes applying to this image group.
*   `view_type` (_string_) The image view type.

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### master

Document representing a variation master.

*   `link` (_string_) The URL addressing the master product.
*   `master_id` (_string_, required) The id (SKU) of the master product.  
    Minimum length: 1. Maximum length: 100.
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.
*   `price` (_number (double)_) The minimum sales price of the related variants.
*   `price_max` (_number (double)_) The maximum sales of related variants.
*   `price_per_unit` (_number (double)_) The minimum sales price per unit of the related variants.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of the related variants.
*   `prices` (_object_)
    
    Additional properties: `number (double)`.
    

### product\_type

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.
*   `bundled` (_boolean_) A flag indicating whether the product is bundled.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.
*   `master` (_boolean_) A flag indicating whether the product is a master.
*   `option` (_boolean_) A flag indicating whether the product is an option.
*   `part_of_product_set` (_boolean_) A flag indicating whether the product is part of product set.
*   `part_of_retail_set` (_boolean_) A flag indicating whether the product is part of retail set.
*   `retail_set` (_boolean_) A flag indicating whether the product is a retail set.
*   `set` (_boolean_) A flag indicating whether the product is a set.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.
*   `variation_group` (_boolean_) A flag indicating whether the product is a variation group.

_Example_

```
{
  "bundled": true,
  "master": true,
  "part_of_product_set": true
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### money

*   `currency_mnemonic` (_string_) The mnemonic for the money.
*   `value` (_number (double)_) The value for the money.

_Example_

```
{
  "currency_mnemonic": "USD",
  "value": 100
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=14d2862ba40bafc14e88bf924653ce479a28c241cb108fa582d2d2dc1e874e7d url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-promotion-campaign-assignment-search.md -->

Data Promotion Campaign Assignment Search (deprecated)

# Data Promotion Campaign Assignment Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Promotion Campaign Assignments

`POST /sites/{site_id}/promotion_campaign_assignment_search`

Operation ID: `Search Promotion Campaign Assignments`. Tags: sites. Security: oauth2\_application.

Searches for promotion campaign assignments.

The PromotionCampaignAssignment Search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. These are the list of searchable attributes with their corresponding buckets:

Main:

*   rank - Integer
    
*   start\_date - Date
    
*   end\_date - Date
    

Campaign:

*   campaign\_id - String
    

Promotion:

*   promotion\_id - String
    
*   description - String
    
*   enabled - Boolean
    

Special handling:

*   coupon\_id - String
    

Only fields in the same bucket can be joined using a disjunction (OR). For instance, when joining campaign\_id and rank above, only a conjunction is allowed (AND), whereas promotion\_id and description can be joined to each other using an OR because they are in the same bucket. Special handling fields must always use conjunctions. If the field is used in a disjunction (OR) that violates this rule, an exception will be thrown.

Expands that can be applied for the search request

*   promotion
    
*   campaign
    

Note that only searchable attributes (excluding the ones marked with above with an asterisk) can be used in sorting.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion_campaign_assignment_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### promotion\_campaign\_assignment\_search\_result

Document representing a promotion campaign assignment search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of promotion\_campaign\_assignment_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### promotion\_campaign\_assignment

Document representing a promotion campaign assignment.

*   `campaign` (_campaign_) The campaign
*   `campaign_id` (_string_) The id of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The sorted array of assigned coupon ids.
*   `coupons_based` (_boolean_) True if the assigned promotion is coupon based. When set to false, Coupons in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The sorted array of assigned customer groups.
*   `customer_groups_based` (_boolean_) True if the assigned promotion is customer group based. When set to false, Customer Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `description` (_string_) The description of the promotion campaign assignment.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) link for convenience
*   `promotion` (_promotion_) The promotion
*   `promotion_id` (_string_) The id of the Promotion.  
    Minimum length: 1. Maximum length: 256.
*   `rank` (_integer (int32)_) The rank of promotion campaign assignment
*   `required_qualifier` (_string_) A constant indicating that one or all qualifier conditions must be met in order for the promotion to apply for a given customer. Valid values are "any" and "all".  
    Allowed values: `any`, `all`.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `source_code_based` (_boolean_) True if the assigned promotion is source code group based. When set to false, Source Code Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `source_code_groups` (_array of string_) The sorted array of assigned source code groups.

_Example_

```
{
  "campaign": {
    "campaign_id": "coupon-campaign",
    "description": "A campaign for coupons.",
    "enabled": true
  },
  "campaign_id": "coupon-campaign",
  "coupons": [
    "order-promotion-coupon"
  ],
  "description": "Coupon Order Promotion",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotions/coupon-promotion-order/campaigns/coupon-campaign",
  "promotion_id": "coupon-promotion-order",
  "schedule": {
    "end_date": "2050-01-01T00:00:00.000Z",
    "start_date": "2000-01-01T00:00:00.000Z"
  }
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### promotion

Document representing a promotion. Unless otherwise stated, attributes of this document are not supported when using the Open Commerce API to update multiple promotions at once.

*   `archived` (_boolean_) Determines whether or not this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `assignment_information` (_promotion\_assignment\_information_) Information about the assignments and assignment schedules of this promotion
*   `callout_msg` (_object (localized)_) The localized callout message of the promotion.
    
    Additional properties: `markup_text`.
    
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency_code` (_string_) The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.  
    Maximum length: 3.
*   `disable_globally_excluded` (_boolean_) Determines whether or not this promotion ignores the global product exclusions for promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `enabled` (_boolean_) Determines whether or not this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `exclusivity` (_string_) Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Allowed values: `no`, `class`, `global`.
*   `id` (_string_) The id for the promotion.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A URL that is used to get the details of this promotion.
*   `name` (_object (localized)_) The user supplied name of this promotion, which can be localized
    
    Additional properties: `string`.
    
*   `promotion_class` (_string_) The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, will be reset.  
    Allowed values: `product`, `shipping`, `order`.
*   `tags` (_array of tag_) Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags will be removed.

_Example_

```
{
  "enabled": true,
  "exclusivity": "class",
  "id": "my-promotion",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/my-promotion/my-promotion",
  "name": {
    "default": "My Promotion"
  },
  "promotion_class": "order"
}
```

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### promotion\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": true,
  "active_campaign_assignments": [
    {
      "campaign_id": "coupon-campaign",
      "coupons": [
        "limitPerCode-coupon",
        "multipleCodes-coupon",
        "longCode-coupon",
        "systemCodes-coupon",
        "limitPerTimePeriod-coupon",
        "disabled-coupon",
        "singleCode-coupon",
        "limitPerCustomer-coupon"
      ],
      "description": "Coupon Promotion",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/coupon-promotion/coupon-campaign",
      "promotion_id": "coupon-promotion",
      "rank": 10,
      "schedule": {}
    }
  ],
  "campaign_id": "coupon-campaign",
  "end_date": "2050-06-01T00:00:00.000Z",
  "schedule": {},
  "schedule_type": "campaign",
  "start_date": "2020-05-01T00:00:00.000Z"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### tag

Document representing a tag

*   `tag_id` (_string_) The id of the tag.

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### promotion\_abtest\_group\_assignment

Document representing a promotionabtestgroupassignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `abtest_id` (_string_) The id for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `schedule` (_schedule_) The schedule informaiton for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment
*   `segment_id` (_string_) The id for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=d216ee86cb2f67fc30350a0c210a2ff35dd2e75eb6e66c958ab8c32083379047 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-promotion-search.md -->

Data Promotion Search (deprecated)

# Data Promotion Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Promotions

`POST /sites/{site_id}/promotion_search`

Operation ID: `Search Promotions`. Tags: sites. Security: oauth2\_application.

Searches for promotions.

The SearchRequest document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. These are the searchable attributes:

*   id - String
    
*   name - String
    
*   currency\_code - String
    
*   exclusivity - String
    
*   enabled - Boolean
    

Note that only searchable attributes can be used in sorting. Additionally, the following attribute can be used to sort:

*   promotion\_class - String
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The site context.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### promotion\_search\_result

Document representing a promotion search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of promotion_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "assignment_information": {
        "active": true,
        "active_campaign_assignments": [
          {
            "campaign_id": "coupon-campaign",
            "coupons": [
              "limitPerCode-coupon",
              "multipleCodes-coupon",
              "longCode-coupon",
              "systemCodes-coupon",
              "limitPerTimePeriod-coupon",
              "disabled-coupon",
              "singleCode-coupon",
              "limitPerCustomer-coupon"
            ],
            "description": "Coupon Promotion",
            "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/coupon-promotion/coupon-campaign",
            "promotion_id": "coupon-promotion",
            "rank": 10,
            "schedule": {}
          }
        ],
        "campaign_id": "coupon-campaign",
        "end_date": "2050-06-01T00:00:00.000Z",
        "schedule": {},
        "schedule_type": "campaign",
        "start_date": "2020-05-01T00:00:00.000Z"
      },
      "disable_globally_excluded": false,
      "enabled": true,
      "exclusivity": "no",
      "id": "coupon-promotion",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotions/coupon-promotion",
      "name": {
        "default": "Coupon Promotion"
      },
      "promotion_class": "product"
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "name"
      ],
      "search_phrase": "*coupon*"
    }
  },
  "select": "(**)",
  "sorts": [
    {
      "field": "id",
      "sort_order": "asc"
    }
  ],
  "start": 0,
  "total": 1
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### promotion

Document representing a promotion. Unless otherwise stated, attributes of this document are not supported when using the Open Commerce API to update multiple promotions at once.

*   `archived` (_boolean_) Determines whether or not this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `assignment_information` (_promotion\_assignment\_information_) Information about the assignments and assignment schedules of this promotion
*   `callout_msg` (_object (localized)_) The localized callout message of the promotion.
    
    Additional properties: `markup_text`.
    
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency_code` (_string_) The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.  
    Maximum length: 3.
*   `disable_globally_excluded` (_boolean_) Determines whether or not this promotion ignores the global product exclusions for promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `enabled` (_boolean_) Determines whether or not this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `exclusivity` (_string_) Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Allowed values: `no`, `class`, `global`.
*   `id` (_string_) The id for the promotion.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A URL that is used to get the details of this promotion.
*   `name` (_object (localized)_) The user supplied name of this promotion, which can be localized
    
    Additional properties: `string`.
    
*   `promotion_class` (_string_) The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, will be reset.  
    Allowed values: `product`, `shipping`, `order`.
*   `tags` (_array of tag_) Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags will be removed.

_Example_

```
{
  "enabled": true,
  "exclusivity": "class",
  "id": "my-promotion",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/my-promotion/my-promotion",
  "name": {
    "default": "My Promotion"
  },
  "promotion_class": "order"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### promotion\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": true,
  "active_campaign_assignments": [
    {
      "campaign_id": "coupon-campaign",
      "coupons": [
        "limitPerCode-coupon",
        "multipleCodes-coupon",
        "longCode-coupon",
        "systemCodes-coupon",
        "limitPerTimePeriod-coupon",
        "disabled-coupon",
        "singleCode-coupon",
        "limitPerCustomer-coupon"
      ],
      "description": "Coupon Promotion",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/coupon-promotion/coupon-campaign",
      "promotion_id": "coupon-promotion",
      "rank": 10,
      "schedule": {}
    }
  ],
  "campaign_id": "coupon-campaign",
  "end_date": "2050-06-01T00:00:00.000Z",
  "schedule": {},
  "schedule_type": "campaign",
  "start_date": "2020-05-01T00:00:00.000Z"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### tag

Document representing a tag

*   `tag_id` (_string_) The id of the tag.

### promotion\_abtest\_group\_assignment

Document representing a promotionabtestgroupassignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `abtest_id` (_string_) The id for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `schedule` (_schedule_) The schedule informaiton for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment
*   `segment_id` (_string_) The id for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment

### promotion\_campaign\_assignment

Document representing a promotion campaign assignment.

*   `campaign` (_campaign_) The campaign
*   `campaign_id` (_string_) The id of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The sorted array of assigned coupon ids.
*   `coupons_based` (_boolean_) True if the assigned promotion is coupon based. When set to false, Coupons in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The sorted array of assigned customer groups.
*   `customer_groups_based` (_boolean_) True if the assigned promotion is customer group based. When set to false, Customer Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `description` (_string_) The description of the promotion campaign assignment.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) link for convenience
*   `promotion` (_promotion_) The promotion
*   `promotion_id` (_string_) The id of the Promotion.  
    Minimum length: 1. Maximum length: 256.
*   `rank` (_integer (int32)_) The rank of promotion campaign assignment
*   `required_qualifier` (_string_) A constant indicating that one or all qualifier conditions must be met in order for the promotion to apply for a given customer. Valid values are "any" and "all".  
    Allowed values: `any`, `all`.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `source_code_based` (_boolean_) True if the assigned promotion is source code group based. When set to false, Source Code Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `source_code_groups` (_array of string_) The sorted array of assigned source code groups.

_Example_

```
{
  "campaign": {
    "campaign_id": "coupon-campaign",
    "description": "A campaign for coupons.",
    "enabled": true
  },
  "campaign_id": "coupon-campaign",
  "coupons": [
    "order-promotion-coupon"
  ],
  "description": "Coupon Order Promotion",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotions/coupon-promotion-order/campaigns/coupon-campaign",
  "promotion_id": "coupon-promotion-order",
  "schedule": {
    "end_date": "2050-01-01T00:00:00.000Z",
    "start_date": "2000-01-01T00:00:00.000Z"
  }
}
```

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=dc7f7b742e83c0d5dedd1588d6cd92186e51f1b1e4b7d562d0ba362fcfdfc498 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-promotions.md -->

Data Promotions (deprecated)

# Data Promotions (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Promotion

`GET /sites/{site_id}/promotions/{id}`

Operation ID: `Get Promotion`. Tags: sites. Security: oauth2\_application.

Action to get promotion information.

This endpoint may return the following faults:

*   404 - PromotionNotFoundException - Thrown in case the promotion does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested promotion.  
    Minimum length: 1.

#### Responses

*   **404** `PromotionNotFoundException` - Thrown in case the promotion does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion`.
    

### PUT Create Promotion

`PUT /sites/{site_id}/promotions/{id}`

Operation ID: `Create Promotion`. Tags: sites. Security: oauth2\_application.

Creates a promotion using the information provided.

This endpoint may return the following faults:

*   400 - IdConflictException - if the Id in request is not the same as the ID in document.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the promotion to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `promotion`.

#### Responses

*   **400** `IdConflictException` - if the Id in request is not the same as the ID in document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion`.
    

### DELETE Delete Promotion

`DELETE /sites/{site_id}/promotions/{id}`

Operation ID: `Delete Promotion`. Tags: sites. Security: oauth2\_application.

Deletes the promotion by ID

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) Promotion id to remove  
    Minimum length: 1.

#### Responses

*   **204**

### PATCH Update Promotion

`PATCH /sites/{site_id}/promotions/{id}`

Operation ID: `Update Promotion`. Tags: sites. Security: oauth2\_application.

Updates the promotion with the specified information.

This endpoint may return the following faults:

*   404 - PromotionNotFoundException - Thrown in case the promotion does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested promotion.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `promotion`.

#### Responses

*   **404** `PromotionNotFoundException` - Thrown in case the promotion does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### promotion

Document representing a promotion. Unless otherwise stated, attributes of this document are not supported when using the Open Commerce API to update multiple promotions at once.

*   `archived` (_boolean_) Determines whether or not this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `assignment_information` (_promotion\_assignment\_information_) Information about the assignments and assignment schedules of this promotion
*   `callout_msg` (_object (localized)_) The localized callout message of the promotion.
    
    Additional properties: `markup_text`.
    
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency_code` (_string_) The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.  
    Maximum length: 3.
*   `disable_globally_excluded` (_boolean_) Determines whether or not this promotion ignores the global product exclusions for promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `enabled` (_boolean_) Determines whether or not this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.
*   `exclusivity` (_string_) Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Allowed values: `no`, `class`, `global`.
*   `id` (_string_) The id for the promotion.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) A URL that is used to get the details of this promotion.
*   `name` (_object (localized)_) The user supplied name of this promotion, which can be localized
    
    Additional properties: `string`.
    
*   `promotion_class` (_string_) The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, will be reset.  
    Allowed values: `product`, `shipping`, `order`.
*   `tags` (_array of tag_) Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags will be removed.

_Example_

```
{
  "enabled": true,
  "exclusivity": "class",
  "id": "my-promotion",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/my-promotion/my-promotion",
  "name": {
    "default": "My Promotion"
  },
  "promotion_class": "order"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### promotion\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of promotion\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of promotion\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": true,
  "active_campaign_assignments": [
    {
      "campaign_id": "coupon-campaign",
      "coupons": [
        "limitPerCode-coupon",
        "multipleCodes-coupon",
        "longCode-coupon",
        "systemCodes-coupon",
        "limitPerTimePeriod-coupon",
        "disabled-coupon",
        "singleCode-coupon",
        "limitPerCustomer-coupon"
      ],
      "description": "Coupon Promotion",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotion_campaign_assignments/coupon-promotion/coupon-campaign",
      "promotion_id": "coupon-promotion",
      "rank": 10,
      "schedule": {}
    }
  ],
  "campaign_id": "coupon-campaign",
  "end_date": "2050-06-01T00:00:00.000Z",
  "schedule": {},
  "schedule_type": "campaign",
  "start_date": "2020-05-01T00:00:00.000Z"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### tag

Document representing a tag

*   `tag_id` (_string_) The id of the tag.

### promotion\_abtest\_group\_assignment

Document representing a promotionabtestgroupassignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `abtest_id` (_string_) The id for the ABTest assigned to the promotion in the promotionabtestgroupassignment
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `schedule` (_schedule_) The schedule informaiton for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment
*   `segment_id` (_string_) The id for the ABTest segment assigned to the promotion in the promotionabtestgroupassignment

### promotion\_campaign\_assignment

Document representing a promotion campaign assignment.

*   `campaign` (_campaign_) The campaign
*   `campaign_id` (_string_) The id of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The sorted array of assigned coupon ids.
*   `coupons_based` (_boolean_) True if the assigned promotion is coupon based. When set to false, Coupons in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The sorted array of assigned customer groups.
*   `customer_groups_based` (_boolean_) True if the assigned promotion is customer group based. When set to false, Customer Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `description` (_string_) The description of the promotion campaign assignment.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) link for convenience
*   `promotion` (_promotion_) The promotion
*   `promotion_id` (_string_) The id of the Promotion.  
    Minimum length: 1. Maximum length: 256.
*   `rank` (_integer (int32)_) The rank of promotion campaign assignment
*   `required_qualifier` (_string_) A constant indicating that one or all qualifier conditions must be met in order for the promotion to apply for a given customer. Valid values are "any" and "all".  
    Allowed values: `any`, `all`.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `source_code_based` (_boolean_) True if the assigned promotion is source code group based. When set to false, Source Code Groups in the campaign and on the PromotionCampaignAssignment are ignored. The default value is true.
*   `source_code_groups` (_array of string_) The sorted array of assigned source code groups.

_Example_

```
{
  "campaign": {
    "campaign_id": "coupon-campaign",
    "description": "A campaign for coupons.",
    "enabled": true
  },
  "campaign_id": "coupon-campaign",
  "coupons": [
    "order-promotion-coupon"
  ],
  "description": "Coupon Order Promotion",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/promotions/coupon-promotion-order/campaigns/coupon-campaign",
  "promotion_id": "coupon-promotion-order",
  "schedule": {
    "end_date": "2050-01-01T00:00:00.000Z",
    "start_date": "2000-01-01T00:00:00.000Z"
  }
}
```

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

<!-- document id=6935d41e765b9659650e9a1ea5328938e905eb7e9c7e828c5df7e4a315633d3c url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-recommender-names.md -->

Data Recommender Names (deprecated)

# Data Recommender Names (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get recommenders

`GET /sites/{site_id}/ai/recommender_names`

Operation ID: `Get recommenders`. Tags: sites. Security: oauth2\_application.

Get a list of available AI recommenders. Recommenders are configured in the Einstein configurator and are required with AI recommendation API requests.

This endpoint may return the following faults:

*   400 - CQuotientException - If CQuotient responds with a non-success status code.
*   404 - SiteNotFoundException - If the given site does not exist.

#### Parameters

*   `site_id` (path, string, required) Site ID to get a list of recommenders for.  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **400** `CQuotientException` - If CQuotient responds with a non-success status code.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SiteNotFoundException` - If the given site does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `recommenders_result`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### recommenders\_result

A list of recommenders available for use in recommendation requests.

*   `recommenders` (_array of recommender_) The recommender objects

_Example_

```
{
  "recommenders": [
    {
      "description": "Recommender for Alternate Products on a PDP",
      "name": "Alternate-Product-to-Product"
    },
    {
      "description": "** for shared demo **",
      "name": "topsellers"
    },
    {
      "description": "Shopper, Recently-Viewed",
      "name": "recently-viewed"
    },
    {
      "description": "demo",
      "name": "demo"
    }
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### recommender

The recommender object

*   `description` (_string_) The description of the recommender
*   `name` (_string_) The name of the recommender

_Example_

```
{
  "description": "Recommender for Alternate Products on a PDP",
  "name": "Alternate-Product-to-Product"
}
```

<!-- document id=62e1cbf862f968e5008fe3c3405bf267bdec0be3478081f8212844a4b13afd5f url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-role-search.md -->

Data Role Search (deprecated)

# Data Role Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search public Access Roles

`POST /role_search`

Operation ID: `Search public Access Roles`. Tags: role\_search. Security: oauth2\_application.

Searches for access roles.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   description - String
    

Optionally, a user ID (the user login) can be specified. When it is supplied, the search for roles is limited to the roles assigned to this user. When expanding the permissions for the roles, all effective permissions for this user can be retrieved.

Optionally, a (single) permission can be specified. When it is supplied, the search for roles is limited to the roles having this permission. When expanding the users for the roles, all users having this permission can be retrieved.

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   description - String
    

This endpoint may return the following faults:

*   400 - InvalidSearchQueryException - Throws when one of the search request restrictions is violated
*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `role_search_request`.

#### Responses

*   **400** `InvalidSearchQueryException` - Throws when one of the search request restrictions is violated or `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `role_search_result`.
    

## Schemas

### role\_search\_request

Document representing an role search.

Note that only either an user ID or a permission can be provided (or none), but not both. When one of them is provided, the further query elements will filter the respective role set (meaning the user ID / permission is AND-connected to the query definition).

When a permission definition is using a site scope, it can contain only one site.

When optional fields in the permission definitions are not provided, they will be treated as 'don't care' (so its e.g. possible so search for permission to site-specific BM modules without providing a site, and the search will return all roles having that permission for any site).

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `permissions` (_role\_permissions_) The permission to search for. Note that even though this is a container that can hold multiple permissions definitions, for a search request only one permission can be provided (otherwise an error will be returned).
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `user_id` (_string_) The id of the user whose roles are to be searched.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### role\_search\_result

Document representing an access role search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of role_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 7,
  "expand": [
    "users"
  ],
  "hits": [
    {
      "description": "Allowed to manage locales",
      "id": "LocaleManager",
      "link": "https://example.com/s/-/dw/data/{version}/roles/LocaleManager",
      "user_count": 1,
      "user_manager": false,
      "users": [
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_name": "LocaleDude",
          "locked": false,
          "login": "localeDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    },
    {
      "description": "Allowed to manage things global",
      "id": "OrgManager",
      "link": "https://example.com/s/-/dw/data/{version}/roles/OrgManager",
      "user_count": 1,
      "user_manager": false,
      "users": [
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_name": "OrgDude",
          "locked": false,
          "login": "orgDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    },
    {
      "description": "Allowed to manage roles",
      "id": "RoleManager",
      "link": "https://example.com/s/-/dw/data/{version}/roles/RoleManager",
      "user_count": 2,
      "user_manager": true,
      "users": [
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_login_date": "2017-01-11",
          "last_name": "RoleDude",
          "locked": false,
          "login": "roleDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        },
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_name": "SecondRoleManager",
          "locked": false,
          "login": "secondRoleManager",
          "preferred_data_locale": "en",
          "preferred_uilocale": "de"
        }
      ]
    },
    {
      "description": "Allowed to manage only site SiteGenesis-DE",
      "id": "SiteGenesisDEManager",
      "link": "https://example.com/s/-/dw/data/{version}/roles/SiteGenesisDEManager",
      "user_count": 1,
      "user_manager": false,
      "users": [
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_name": "SiteGenesisDEDude",
          "locked": false,
          "login": "SiteGenesisDEDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    },
    {
      "description": "Allowed to manage only site SiteGenesis",
      "id": "SiteGenesisManager",
      "link": "https://example.com/s/-/dw/data/{version}/roles/SiteGenesisManager",
      "user_count": 4,
      "user_manager": false,
      "users": [
        {
          "disabled": false,
          "email": "ocapi_agent@example.com",
          "first_name": "Ocapi",
          "last_name": "SiteGenesisAgentMultiRole",
          "locked": false,
          "login": "SiteGenesisAgentMultiRole",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        },
        {
          "disabled": false,
          "email": "ocapi_oauth2@example.com",
          "first_name": "Ocapi",
          "last_name": "SiteGenesisOAuth2",
          "locked": false,
          "login": "SiteGenesisOAuth2",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        },
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_login_date": "2017-01-11",
          "last_name": "SiteGenesisDude",
          "locked": false,
          "login": "SiteGenesisDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        },
        {
          "disabled": false,
          "email": "ocapi_oauth@example.com",
          "first_name": "Ocapi",
          "last_name": "SiteGenesisOAuth",
          "locked": false,
          "login": "SiteGenesisOAuth",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    },
    {
      "description": "Allowed to manage users",
      "id": "UserManager",
      "link": "https://example.com/s/-/dw/data/{version}/roles/UserManager",
      "user_count": 1,
      "user_manager": true,
      "users": [
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_login_date": "2017-01-11",
          "last_name": "UserDude",
          "locked": false,
          "login": "userDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    },
    {
      "description": "Allowed to manage users and roles",
      "id": "UserRoleManager",
      "link": "https://example.com/s/-/dw/data/{version}/roles/UserRoleManager",
      "user_count": 1,
      "user_manager": true,
      "users": [
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_name": "UserRoleDude",
          "locked": false,
          "login": "userRoleDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id"
      ],
      "search_phrase": "Manager"
    }
  },
  "select": "(**)",
  "sorts": [
    {
      "field": "id",
      "sort_order": "asc"
    }
  ],
  "start": 0,
  "total": 7
}
```

### role\_permissions

Document listing the permissions assigned to a certain role (accessible by type).

*   `functional` (_role\_functional\_permissions_) The functional permissions.
*   `locale` (_role\_locale\_permissions_) The locale permissions.
*   `module` (_role\_module\_permissions_) The module permissions.
*   `webdav` (_role\_webdav\_permissions_) The WebDAV permissions.

_Example_

```
{
  "functional": {
    "organization": [
      {
        "name": "Delete_All_Catalogs",
        "type": "functional",
        "value": "ACCESS"
      },
      {
        "name": "Manage_All_Catalogs",
        "type": "functional",
        "value": "ACCESS"
      },
      {
        "name": "WebDAV_Security_Logs_Access",
        "type": "functional",
        "value": "ACCESS"
      }
    ],
    "site": [
      {
        "name": "Manage_Site_Catalog",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "ACCESS"
        }
      },
      {
        "name": "Manage_Site_Library",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "ACCESS"
        }
      },
      {
        "name": "Manage_Site_PriceBooks",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS"
        }
      },
      {
        "name": "Manage_Site_Inventory",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS"
        }
      }
    ]
  },
  "locale": {
    "unscoped": [
      {
        "locale_id": "de",
        "type": "locale",
        "value": "ACCESS"
      },
      {
        "locale_id": "default",
        "type": "locale",
        "value": "READONLY"
      },
      {
        "locale_id": "en",
        "type": "locale",
        "value": "READONLY"
      },
      {
        "locale_id": "en_US",
        "type": "locale",
        "value": "ACCESS"
      },
      {
        "locale_id": "fr_FR",
        "type": "locale",
        "value": "ACCESS"
      }
    ]
  },
  "module": {
    "organization": [
      {
        "application": "bm",
        "name": "jobmonitor",
        "type": "module",
        "value": "READONLY"
      },
      {
        "application": "bm",
        "name": "jobschedules",
        "system": true,
        "type": "module",
        "value": "ACCESS"
      }
    ],
    "site": [
      {
        "application": "bm",
        "name": "library_content_libraries",
        "system": true,
        "type": "module",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "READONLY"
        }
      },
      {
        "application": "bm",
        "name": "library_folder",
        "system": true,
        "type": "module",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "ACCESS"
        }
      },
      {
        "application": "bm",
        "name": "library_content",
        "system": true,
        "type": "module",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "READONLY"
        }
      }
    ]
  },
  "webdav": {
    "unscoped": [
      {
        "folder": "/catalogs/apparel-catalog",
        "type": "webdav",
        "value": "ACCESS"
      },
      {
        "folder": "/catalogs/electronics-catalog",
        "type": "webdav",
        "value": "READONLY"
      },
      {
        "folder": "/catalogs/storefront-catalog-en",
        "type": "webdav",
        "value": "READONLY"
      },
      {
        "folder": "/catalogs/storefront-catalog-non-en",
        "type": "webdav",
        "value": "READONLY"
      },
      {
        "folder": "/libraries/SiteGenesis",
        "type": "webdav",
        "value": "ACCESS"
      },
      {
        "folder": "/libraries/SiteGenesisGlobal",
        "type": "webdav",
        "value": "READONLY"
      }
    ]
  }
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### role

Document representing an access role.

*   `creation_date` (_string (date-time)_)
*   `description` (_string_) The role description.
*   `id` (_string_) The role ID.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `permissions` (_role\_permissions_) The permissions assigned to the access role. Available through expands.
*   `user_count` (_integer (int32)_) Number of users assigned to the role.
*   `user_manager` (_boolean_) Flag whether this role is allowed to manage users or other access roles.
*   `users` (_array of user_) The users assigned to the access role. Available through expands.

_Example_

```
{
  "description": "Allowed to manage locales",
  "id": "LocaleManager",
  "link": "https://example.com/s/-/dw/data/{version}/roles/LocaleManager",
  "user_count": 1,
  "user_manager": false,
  "users": [
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "first_name": "Ocapi",
      "last_name": "LocaleDude",
      "locked": false,
      "login": "localeDude",
      "preferred_data_locale": "default",
      "preferred_uilocale": "default"
    }
  ]
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### role\_functional\_permissions

Document listing the functional permissions assigned to a certain role.

*   `organization` (_array of role\_functional\_permission_) The list of organization functional permissions.
*   `site` (_array of role\_functional\_permission_) The list of site functional permissions.

_Example_

```
{
  "organization": [
    {
      "name": "Delete_All_Catalogs",
      "type": "functional",
      "value": "ACCESS"
    },
    {
      "name": "Manage_All_Catalogs",
      "type": "functional",
      "value": "ACCESS"
    },
    {
      "name": "WebDAV_Security_Logs_Access",
      "type": "functional",
      "value": "ACCESS"
    }
  ],
  "site": [
    {
      "name": "Manage_Site_Catalog",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "ACCESS"
      }
    },
    {
      "name": "Manage_Site_Library",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "ACCESS"
      }
    },
    {
      "name": "Manage_Site_PriceBooks",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS"
      }
    },
    {
      "name": "Manage_Site_Inventory",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS"
      }
    }
  ]
}
```

### role\_locale\_permissions

Document listing the locale permissions assigned to a certain role.

*   `unscoped` (_array of role\_locale\_permission_) The list of unscoped locale permissions.

_Example_

```
{
  "unscoped": [
    {
      "locale_id": "de",
      "type": "locale",
      "value": "ACCESS"
    },
    {
      "locale_id": "default",
      "type": "locale",
      "value": "READONLY"
    },
    {
      "locale_id": "en",
      "type": "locale",
      "value": "READONLY"
    },
    {
      "locale_id": "en_US",
      "type": "locale",
      "value": "ACCESS"
    },
    {
      "locale_id": "fr_FR",
      "type": "locale",
      "value": "ACCESS"
    }
  ]
}
```

### role\_module\_permissions

Document listing the module permissions assigned to a certain role.

*   `organization` (_array of role\_module\_permission_) The list of organization module permissions.
*   `site` (_array of role\_module\_permission_) The list of site module permissions.

_Example_

```
{
  "organization": [
    {
      "application": "bm",
      "name": "jobmonitor",
      "type": "module",
      "value": "READONLY"
    },
    {
      "application": "bm",
      "name": "jobschedules",
      "system": true,
      "type": "module",
      "value": "ACCESS"
    }
  ],
  "site": [
    {
      "application": "bm",
      "name": "library_content_libraries",
      "system": true,
      "type": "module",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "READONLY"
      }
    },
    {
      "application": "bm",
      "name": "library_folder",
      "system": true,
      "type": "module",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "ACCESS"
      }
    },
    {
      "application": "bm",
      "name": "library_content",
      "system": true,
      "type": "module",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "READONLY"
      }
    }
  ]
}
```

### role\_webdav\_permissions

Document listing the WebDAV permissions assigned to a certain role.

*   `unscoped` (_array of role\_webdav\_permission_) The list of unscoped WebDAV permissions.

_Example_

```
{
  "unscoped": [
    {
      "folder": "/catalogs/apparel-catalog",
      "type": "webdav",
      "value": "ACCESS"
    },
    {
      "folder": "/catalogs/electronics-catalog",
      "type": "webdav",
      "value": "READONLY"
    },
    {
      "folder": "/catalogs/storefront-catalog-en",
      "type": "webdav",
      "value": "READONLY"
    },
    {
      "folder": "/catalogs/storefront-catalog-non-en",
      "type": "webdav",
      "value": "READONLY"
    },
    {
      "folder": "/libraries/SiteGenesis",
      "type": "webdav",
      "value": "ACCESS"
    },
    {
      "folder": "/libraries/SiteGenesisGlobal",
      "type": "webdav",
      "value": "READONLY"
    }
  ]
}
```

### user

Document representing a user.

*   `creation_date` (_string (date-time)_)
*   `disabled` (_boolean_) Flag whether the user is disabled.
*   `email` (_string_, required) The email address.  
    Maximum length: 256.
*   `external_id` (_string_) The external id. This attribute is only valid when the user uses centralized authentication.  
    Maximum length: 256.
*   `first_name` (_string_) The first name.  
    Maximum length: 256.
*   `last_login_date` (_string (date)_) Last login of the user.
*   `last_modified` (_string (date-time)_)
*   `last_name` (_string_, required) The last name.  
    Maximum length: 256.
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `locked` (_boolean_) Flag whether the user is locked.
*   `login` (_string_) The user login.  
    Maximum length: 256.
*   `password` (_string_) The password. This attribute is only used to set the password upon user creation. This attribute is only valid when the user does not use centralized authentication.
*   `password_expiration_date` (_string (date-time)_) The user password expiration time
*   `password_modification_date` (_string (date-time)_) The time, where the password was last modified
*   `preferred_data_locale` (_string_) The effective preferred data locale of the user. A locale is only considered if the user has at least read permission on the locale.
*   `preferred_ui_locale` (_string_) The preferred UI locale of the user.
*   `roles` (_array of string_) List of role ids the user is assigned to.

_Example_

```
{
  "disabled": false,
  "email": "someUserl@example.com",
  "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
  "first_name": "John",
  "last_name": "Doe",
  "locked": false,
  "login": "someUser",
  "password_expiration_date": "2016-01-14T16:48:07Z",
  "password_modification_date": "2016-04-14T16:48:07Z",
  "preferred_data_locale": "default",
  "preferred_ui_locale": "en-US",
  "roles": [
    "FirstRole",
    "SecondRole"
  ]
}
```

### role\_functional\_permission

Document representing a functional permission.

*   `name` (_string_, required) The name of the functional permission.  
    Minimum length: 1.
*   `type` (_string_, required) The permission type ("functional").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the functional permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the functional permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "name": "Delete_All_Catalogs",
  "type": "functional",
  "value": "ACCESS"
}
```

### role\_locale\_permission

Document representing a locale permission.

*   `locale_id` (_string_, required) The related locale id of the locale permission.  
    Minimum length: 1.
*   `type` (_string_, required) The permission type ("locale").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the locale permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the locale permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "locale_id": "en",
  "type": "locale",
  "value": "READONLY"
}
```

### role\_module\_permission

Document representing a module permission.

*   `application` (_string_, required) The permission application (e.g. "bm", "csc").  
    Minimum length: 1.
*   `name` (_string_, required) The related menu action name of the module permission.  
    Minimum length: 1.
*   `system` (_boolean_) Flag to indicate a system menu action. This is `false` for custom menu actions.
*   `type` (_string_, required) The permission type ("module").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the module permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the module permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "application": "bm",
  "name": "jobmonitor",
  "type": "module",
  "value": "READONLY"
}
```

### role\_webdav\_permission

Document representing a WebDAV permission.

*   `folder` (_string_, required) The related folder of the WebDAV permission.  
    Minimum length: 1.
*   `type` (_string_, required) The permission type ("webdav").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the WebDAV permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the WebDAV permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "folder": "/catalogs/apparel-catalog",
  "type": "webdav",
  "value": "ACCESS"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=8f9d9680a76467de322c459c99af4c05d7a22a7e762cc1911fbd67a37f133f20 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-roles.md -->

Data Roles (deprecated)

# Data Roles (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get public Access Roles

`GET /roles`

Operation ID: `Get public Access Roles`. Tags: roles. Security: oauth2\_application.

Action to get all the access roles with no filtering.

#### Parameters

*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `expand` (query, array of string) List of expansions.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `roles`.
    

### GET Get Access Role

`GET /roles/{id}`

Operation ID: `Get Access Role`. Tags: roles. Security: oauth2\_application.

Action to get a single access role.

This endpoint may return the following faults:

*   404 - RoleNotFoundException - Thrown if the access role with the given id does not exist.

#### Parameters

*   `id` (path, string, required) The id of the requested access role.  
    Minimum length: 1.
*   `expand` (query, array of string) The list of expansions.

#### Responses

*   **404** `RoleNotFoundException` - Thrown if the access role with the given id does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `role`.
    

### PUT Create Access Role

`PUT /roles/{id}`

Operation ID: `Create Access Role`. Tags: roles. Security: oauth2\_application.

Action to create an access role.

This endpoint may return the following faults:

*   400 - IdConflictException - Thrown when id in query parameter is different from the id in the body.
*   403 - RoleOperationNotAllowedException - Thrown when an access role with the id "Support" or "Business Support" should be created.
*   409 - RoleAlreadyExistsException - Thrown when an access role with the given id already exists.

#### Parameters

*   `id` (path, string, required) The id of the access role to create.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `role`.

#### Responses

*   **400** `IdConflictException` - Thrown when id in query parameter is different from the id in the body.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `RoleOperationNotAllowedException` - Thrown when an access role with the id "Support" or "Business Support" should be created.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `RoleAlreadyExistsException` - Thrown when an access role with the given id already exists.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `role`.
    

### DELETE Delete Access Role

`DELETE /roles/{id}`

Operation ID: `Delete Access Role`. Tags: roles. Security: oauth2\_application.

Action to delete an access role.

This endpoint may return the following faults:

*   403 - RoleOperationNotAllowedException - Thrown if deletion of the given role is not allowed
*   404 - RoleNotFoundException - Thrown if the given role does not exist

#### Parameters

*   `id` (path, string, required) The id of the access role to delete.  
    Minimum length: 1.

#### Responses

*   **204**
*   **403** `RoleOperationNotAllowedException` - Thrown if deletion of the given role is not allowed
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `RoleNotFoundException` - Thrown if the given role does not exist
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get role permissions

`GET /roles/{id}/permissions`

Operation ID: `Get role permissions`. Tags: roles. Security: oauth2\_application.

Retrieves a list of permissions assigned to the given role.

This endpoint may return the following faults:

*   404 - RoleNotFoundException - If the specified access role does not exist.

#### Parameters

*   `id` (path, string, required) The id of the requested access role.  
    Minimum length: 1.

#### Responses

*   **404** `RoleNotFoundException` - If the specified access role does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `role_permissions`.
    

### PUT Set role permissions

`PUT /roles/{id}/permissions`

Operation ID: `Set role permissions`. Tags: roles. Security: oauth2\_application.

Assigns permissions to the given role. This will replace the current permission assignments. For the 'Administrator' role only adjustments for custom module permissions will be processed but other given permissions will be ignored.

This endpoint may return the following faults:

*   400 - DefaultLocalePermissionMissingException - If no permission for the 'default' locale is given (permission for 'default' locale is mandatory).
*   400 - DuplicatePermissionException - If a permission is listed more than once within a scope.
*   400 - InvalidPermissionTypeException - If the type of a given permission does not match the expected type.
*   400 - InvalidPermissionValueException - If a permission value is given that is either unknown or not supported for a certain permission.
*   400 - InvalidPermissionValueScopeException - If values are given permission multi values are used where only single values are support or vice versa (e.g. setting 'values' attribute of ModulePermissionWO in organization scope).
*   400 - SystemFlagMissingException - If the 'system' flag is not set for a module permission.
*   400 - UnknownPermissionException - If the id of a given permission could not be resolved to a permission.
*   400 - UnknownSiteIdException - If a site specific permission is given for a site that is not known.
*   404 - RoleNotFoundException - If the specified access role does not exist.
*   409 - ResourceStateConflictException - In case of state token conflicts.

#### Parameters

*   `id` (path, string, required) The id of the access role for which the permissions will be set.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `role_permissions`.

#### Responses

*   **400** `DefaultLocalePermissionMissingException` - If no permission for the 'default' locale is given (permission for 'default' locale is mandatory). or `DuplicatePermissionException` - If a permission is listed more than once within a scope. or `InvalidPermissionTypeException` - If the type of a given permission does not match the expected type. or `InvalidPermissionValueException` - If a permission value is given that is either unknown or not supported for a certain permission. or `InvalidPermissionValueScopeException` - If values are given permission multi values are used where only single values are support or vice versa (e.g. setting 'values' attribute of ModulePermissionWO in organization scope). or `SystemFlagMissingException` - If the 'system' flag is not set for a module permission. or `UnknownPermissionException` - If the id of a given permission could not be resolved to a permission. or `UnknownSiteIdException` - If a site specific permission is given for a site that is not known.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `RoleNotFoundException` - If the specified access role does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `ResourceStateConflictException` - In case of state token conflicts.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `role_permissions`.
    

### POST Search for Users on a public Access Role

`POST /roles/{id}/user_search`

Operation ID: `Search for Users on a public Access Role`. Tags: roles. Security: oauth2\_application.

Searches for users of the specified access role.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   login - String
    
*   email - String
    
*   first\_name - String
    
*   last\_name - String
    
*   external\_id - String
    
*   last\_login\_date - Date
    
*   is\_locked - Boolean
    
*   is\_disabled - Boolean
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   login - String
    
*   email - String
    
*   first\_name - String
    
*   last\_name - String
    
*   external\_id - String
    
*   last\_login\_date - Date
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.
*   404 - RoleNotFoundException - If the specified access role does not exist.

#### Parameters

*   `id` (path, string, required)  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `RoleNotFoundException` - If the specified access role does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user_search_result`.
    

### GET Get Users assigned to an Access Role

`GET /roles/{id}/users`

Operation ID: `Get Users assigned to an Access Role`. Tags: roles. Security: oauth2\_application.

Action to get all the users assigned to the specified access role.

This endpoint may return the following faults:

*   404 - RoleNotFoundException - Thrown if the access role with the given id does not exist.

#### Parameters

*   `id` (path, string, required) ID of the access role.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **404** `RoleNotFoundException` - Thrown if the access role with the given id does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `users`.
    

### PUT Assign User to Access Role

`PUT /roles/{id}/users/{login}`

Operation ID: `Assign User to Access Role`. Tags: roles. Security: oauth2\_application.

Action to assign a user to an access role

This endpoint may return the following faults:

*   400 - InvalidRoleException - Thrown if the access role with the given id does not exist.
*   400 - InvalidUserLoginException - Thrown if a user with the given login does not exist.
*   403 - UserOperationNotAllowedException - Thrown if the operation is not allowed.

#### Parameters

*   `id` (path, string, required) ID of the access role.  
    Minimum length: 1.
*   `login` (path, string, required) Login of the user.  
    Minimum length: 1.

#### Responses

*   **400** `InvalidRoleException` - Thrown if the access role with the given id does not exist. or `InvalidUserLoginException` - Thrown if a user with the given login does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `UserOperationNotAllowedException` - Thrown if the operation is not allowed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user`.
    

### DELETE Unassign User to Access Role

`DELETE /roles/{id}/users/{login}`

Operation ID: `Unassign User to Access Role`. Tags: roles. Security: oauth2\_application.

Action to unassign a user to an access role

This endpoint may return the following faults:

*   403 - UserOperationNotAllowedException - Thrown if the admin user is unassigned from the Administrator role.
*   404 - RoleNotFoundException - Thrown if the access role with the given id does not exist.
*   404 - UserNotFoundException - Thrown if a user with the given login does not exist.

#### Parameters

*   `id` (path, string, required) ID of the access role.  
    Minimum length: 1.
*   `login` (path, string, required) Login of the user.  
    Minimum length: 1.

#### Responses

*   **204**
*   **403** `UserOperationNotAllowedException` - Thrown if the admin user is unassigned from the Administrator role.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `RoleNotFoundException` - Thrown if the access role with the given id does not exist. or `UserNotFoundException` - Thrown if a user with the given login does not exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

## Schemas

### roles

Document representing a list of access roles.

*   `count` (_integer (int32)_)
*   `data` (_array of role_) The list of access roles.
*   `expand` (_array of string_)
*   `next` (_string_)
*   `previous` (_string_)
*   `select` (_string_)
*   `start` (_integer (int32)_)  
    Minimum: 0.
*   `total` (_integer (int32)_)

_Example_

```
{
  "count": 2,
  "data": [
    {
      "description": "The administrator has the rights to perform tasks related to the overall administration of the merchant organization and its users and roles. This access role is not site-specific and will grant the user access to the entire organization.",
      "id": "Administrator",
      "link": "https://example.com/s/-/dw/data/{version}/roles/Administrator",
      "user_count": 1,
      "user_manager": false,
      "users": [
        {
          "disabled": false,
          "email": "ocapi@example.com",
          "first_name": "Ocapi",
          "last_name": "LocaleDude",
          "locked": false,
          "login": "localeDude",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    },
    {
      "description": "Read and Write Site Preferences of multiple Sites ",
      "id": "MultiSite-Full-ReadWriteSitePreferences",
      "link": "https://example.com/s/-/dw/data/{version}/roles/MultiSite-Full-ReadWriteSitePreferences",
      "user_count": 1,
      "user_manager": false,
      "users": [
        {
          "disabled": false,
          "email": "ocapi_bfl@example.com",
          "first_name": "Ocapi",
          "last_name": "MultiSite-Full-ReadWriteSitePreferences",
          "locked": false,
          "login": "MultiSite-Full-ReadWriteSitePreferences",
          "preferred_data_locale": "default",
          "preferred_uilocale": "default"
        }
      ]
    }
  ],
  "expand": [
    "users",
    "permissions"
  ],
  "select": "(**)",
  "start": 0,
  "total": 20
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### role

Document representing an access role.

*   `creation_date` (_string (date-time)_)
*   `description` (_string_) The role description.
*   `id` (_string_) The role ID.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `permissions` (_role\_permissions_) The permissions assigned to the access role. Available through expands.
*   `user_count` (_integer (int32)_) Number of users assigned to the role.
*   `user_manager` (_boolean_) Flag whether this role is allowed to manage users or other access roles.
*   `users` (_array of user_) The users assigned to the access role. Available through expands.

_Example_

```
{
  "description": "Allowed to manage locales",
  "id": "LocaleManager",
  "link": "https://example.com/s/-/dw/data/{version}/roles/LocaleManager",
  "user_count": 1,
  "user_manager": false,
  "users": [
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "first_name": "Ocapi",
      "last_name": "LocaleDude",
      "locked": false,
      "login": "localeDude",
      "preferred_data_locale": "default",
      "preferred_uilocale": "default"
    }
  ]
}
```

### role\_permissions

Document listing the permissions assigned to a certain role (accessible by type).

*   `functional` (_role\_functional\_permissions_) The functional permissions.
*   `locale` (_role\_locale\_permissions_) The locale permissions.
*   `module` (_role\_module\_permissions_) The module permissions.
*   `webdav` (_role\_webdav\_permissions_) The WebDAV permissions.

_Example_

```
{
  "functional": {
    "organization": [
      {
        "name": "Delete_All_Catalogs",
        "type": "functional",
        "value": "ACCESS"
      },
      {
        "name": "Manage_All_Catalogs",
        "type": "functional",
        "value": "ACCESS"
      },
      {
        "name": "WebDAV_Security_Logs_Access",
        "type": "functional",
        "value": "ACCESS"
      }
    ],
    "site": [
      {
        "name": "Manage_Site_Catalog",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "ACCESS"
        }
      },
      {
        "name": "Manage_Site_Library",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "ACCESS"
        }
      },
      {
        "name": "Manage_Site_PriceBooks",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS"
        }
      },
      {
        "name": "Manage_Site_Inventory",
        "type": "functional",
        "values": {
          "SiteGenesis": "ACCESS"
        }
      }
    ]
  },
  "locale": {
    "unscoped": [
      {
        "locale_id": "de",
        "type": "locale",
        "value": "ACCESS"
      },
      {
        "locale_id": "default",
        "type": "locale",
        "value": "READONLY"
      },
      {
        "locale_id": "en",
        "type": "locale",
        "value": "READONLY"
      },
      {
        "locale_id": "en_US",
        "type": "locale",
        "value": "ACCESS"
      },
      {
        "locale_id": "fr_FR",
        "type": "locale",
        "value": "ACCESS"
      }
    ]
  },
  "module": {
    "organization": [
      {
        "application": "bm",
        "name": "jobmonitor",
        "type": "module",
        "value": "READONLY"
      },
      {
        "application": "bm",
        "name": "jobschedules",
        "system": true,
        "type": "module",
        "value": "ACCESS"
      }
    ],
    "site": [
      {
        "application": "bm",
        "name": "library_content_libraries",
        "system": true,
        "type": "module",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "READONLY"
        }
      },
      {
        "application": "bm",
        "name": "library_folder",
        "system": true,
        "type": "module",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "ACCESS"
        }
      },
      {
        "application": "bm",
        "name": "library_content",
        "system": true,
        "type": "module",
        "values": {
          "SiteGenesis": "ACCESS",
          "SiteGenesisGlobal": "READONLY"
        }
      }
    ]
  },
  "webdav": {
    "unscoped": [
      {
        "folder": "/catalogs/apparel-catalog",
        "type": "webdav",
        "value": "ACCESS"
      },
      {
        "folder": "/catalogs/electronics-catalog",
        "type": "webdav",
        "value": "READONLY"
      },
      {
        "folder": "/catalogs/storefront-catalog-en",
        "type": "webdav",
        "value": "READONLY"
      },
      {
        "folder": "/catalogs/storefront-catalog-non-en",
        "type": "webdav",
        "value": "READONLY"
      },
      {
        "folder": "/libraries/SiteGenesis",
        "type": "webdav",
        "value": "ACCESS"
      },
      {
        "folder": "/libraries/SiteGenesisGlobal",
        "type": "webdav",
        "value": "READONLY"
      }
    ]
  }
}
```

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### user\_search\_result

Document representing an user search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of user_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
      "first_name": "Ocapi",
      "last_login_date": "2017-01-11",
      "last_name": "SiteGenesisDude",
      "locked": false,
      "login": "SiteGenesisDude",
      "preferred_data_locale": "default",
      "preferred_uilocale": "default"
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "login"
      ],
      "search_phrase": "Dude"
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 1
}
```

### users

Document representing a list of users.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of user_) The list of users.
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "first_name": "Ocapi",
      "last_login_date": "2017-01-12",
      "last_name": "RoleDude",
      "locked": false,
      "login": "roleDude",
      "preferred_data_locale": "default",
      "preferred_uilocale": "default"
    },
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "first_name": "Ocapi",
      "last_name": "SecondRoleManager",
      "locked": false,
      "login": "secondRoleManager",
      "preferred_data_locale": "en",
      "preferred_uilocale": "de"
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 2
}
```

### user

Document representing a user.

*   `creation_date` (_string (date-time)_)
*   `disabled` (_boolean_) Flag whether the user is disabled.
*   `email` (_string_, required) The email address.  
    Maximum length: 256.
*   `external_id` (_string_) The external id. This attribute is only valid when the user uses centralized authentication.  
    Maximum length: 256.
*   `first_name` (_string_) The first name.  
    Maximum length: 256.
*   `last_login_date` (_string (date)_) Last login of the user.
*   `last_modified` (_string (date-time)_)
*   `last_name` (_string_, required) The last name.  
    Maximum length: 256.
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `locked` (_boolean_) Flag whether the user is locked.
*   `login` (_string_) The user login.  
    Maximum length: 256.
*   `password` (_string_) The password. This attribute is only used to set the password upon user creation. This attribute is only valid when the user does not use centralized authentication.
*   `password_expiration_date` (_string (date-time)_) The user password expiration time
*   `password_modification_date` (_string (date-time)_) The time, where the password was last modified
*   `preferred_data_locale` (_string_) The effective preferred data locale of the user. A locale is only considered if the user has at least read permission on the locale.
*   `preferred_ui_locale` (_string_) The preferred UI locale of the user.
*   `roles` (_array of string_) List of role ids the user is assigned to.

_Example_

```
{
  "disabled": false,
  "email": "someUserl@example.com",
  "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
  "first_name": "John",
  "last_name": "Doe",
  "locked": false,
  "login": "someUser",
  "password_expiration_date": "2016-01-14T16:48:07Z",
  "password_modification_date": "2016-04-14T16:48:07Z",
  "preferred_data_locale": "default",
  "preferred_ui_locale": "en-US",
  "roles": [
    "FirstRole",
    "SecondRole"
  ]
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### role\_functional\_permissions

Document listing the functional permissions assigned to a certain role.

*   `organization` (_array of role\_functional\_permission_) The list of organization functional permissions.
*   `site` (_array of role\_functional\_permission_) The list of site functional permissions.

_Example_

```
{
  "organization": [
    {
      "name": "Delete_All_Catalogs",
      "type": "functional",
      "value": "ACCESS"
    },
    {
      "name": "Manage_All_Catalogs",
      "type": "functional",
      "value": "ACCESS"
    },
    {
      "name": "WebDAV_Security_Logs_Access",
      "type": "functional",
      "value": "ACCESS"
    }
  ],
  "site": [
    {
      "name": "Manage_Site_Catalog",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "ACCESS"
      }
    },
    {
      "name": "Manage_Site_Library",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "ACCESS"
      }
    },
    {
      "name": "Manage_Site_PriceBooks",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS"
      }
    },
    {
      "name": "Manage_Site_Inventory",
      "type": "functional",
      "values": {
        "SiteGenesis": "ACCESS"
      }
    }
  ]
}
```

### role\_locale\_permissions

Document listing the locale permissions assigned to a certain role.

*   `unscoped` (_array of role\_locale\_permission_) The list of unscoped locale permissions.

_Example_

```
{
  "unscoped": [
    {
      "locale_id": "de",
      "type": "locale",
      "value": "ACCESS"
    },
    {
      "locale_id": "default",
      "type": "locale",
      "value": "READONLY"
    },
    {
      "locale_id": "en",
      "type": "locale",
      "value": "READONLY"
    },
    {
      "locale_id": "en_US",
      "type": "locale",
      "value": "ACCESS"
    },
    {
      "locale_id": "fr_FR",
      "type": "locale",
      "value": "ACCESS"
    }
  ]
}
```

### role\_module\_permissions

Document listing the module permissions assigned to a certain role.

*   `organization` (_array of role\_module\_permission_) The list of organization module permissions.
*   `site` (_array of role\_module\_permission_) The list of site module permissions.

_Example_

```
{
  "organization": [
    {
      "application": "bm",
      "name": "jobmonitor",
      "type": "module",
      "value": "READONLY"
    },
    {
      "application": "bm",
      "name": "jobschedules",
      "system": true,
      "type": "module",
      "value": "ACCESS"
    }
  ],
  "site": [
    {
      "application": "bm",
      "name": "library_content_libraries",
      "system": true,
      "type": "module",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "READONLY"
      }
    },
    {
      "application": "bm",
      "name": "library_folder",
      "system": true,
      "type": "module",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "ACCESS"
      }
    },
    {
      "application": "bm",
      "name": "library_content",
      "system": true,
      "type": "module",
      "values": {
        "SiteGenesis": "ACCESS",
        "SiteGenesisGlobal": "READONLY"
      }
    }
  ]
}
```

### role\_webdav\_permissions

Document listing the WebDAV permissions assigned to a certain role.

*   `unscoped` (_array of role\_webdav\_permission_) The list of unscoped WebDAV permissions.

_Example_

```
{
  "unscoped": [
    {
      "folder": "/catalogs/apparel-catalog",
      "type": "webdav",
      "value": "ACCESS"
    },
    {
      "folder": "/catalogs/electronics-catalog",
      "type": "webdav",
      "value": "READONLY"
    },
    {
      "folder": "/catalogs/storefront-catalog-en",
      "type": "webdav",
      "value": "READONLY"
    },
    {
      "folder": "/catalogs/storefront-catalog-non-en",
      "type": "webdav",
      "value": "READONLY"
    },
    {
      "folder": "/libraries/SiteGenesis",
      "type": "webdav",
      "value": "ACCESS"
    },
    {
      "folder": "/libraries/SiteGenesisGlobal",
      "type": "webdav",
      "value": "READONLY"
    }
  ]
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### role\_functional\_permission

Document representing a functional permission.

*   `name` (_string_, required) The name of the functional permission.  
    Minimum length: 1.
*   `type` (_string_, required) The permission type ("functional").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the functional permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the functional permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "name": "Delete_All_Catalogs",
  "type": "functional",
  "value": "ACCESS"
}
```

### role\_locale\_permission

Document representing a locale permission.

*   `locale_id` (_string_, required) The related locale id of the locale permission.  
    Minimum length: 1.
*   `type` (_string_, required) The permission type ("locale").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the locale permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the locale permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "locale_id": "en",
  "type": "locale",
  "value": "READONLY"
}
```

### role\_module\_permission

Document representing a module permission.

*   `application` (_string_, required) The permission application (e.g. "bm", "csc").  
    Minimum length: 1.
*   `name` (_string_, required) The related menu action name of the module permission.  
    Minimum length: 1.
*   `system` (_boolean_) Flag to indicate a system menu action. This is `false` for custom menu actions.
*   `type` (_string_, required) The permission type ("module").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the module permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the module permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "application": "bm",
  "name": "jobmonitor",
  "type": "module",
  "value": "READONLY"
}
```

### role\_webdav\_permission

Document representing a WebDAV permission.

*   `folder` (_string_, required) The related folder of the WebDAV permission.  
    Minimum length: 1.
*   `type` (_string_, required) The permission type ("webdav").  
    Minimum length: 1.
*   `value` (_string_) The non domain specific value for the WebDAV permission, e.g. ACCESS or READONLY.
*   `values` (_object_) The map of value per domain for the WebDAV permission, e.g. ACCESS or READONLY per domain name.
    
    Additional properties: `string`.
    

_Example_

```
{
  "folder": "/catalogs/apparel-catalog",
  "type": "webdav",
  "value": "ACCESS"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=af95b9e907c3ec2636651b9bcb15b19225092fa4ec26e7568955f78d2a519d69 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-settings.md -->

Data Settings (deprecated)

# Data Settings (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Custom Log Settings

`GET /settings/logging/custom`

Operation ID: `Get Custom Log Settings`. Tags: settings. Security: oauth2\_application.

Action to get custom log settings.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_log_settings`.
    

### PATCH Update Custom Log Settings

`PATCH /settings/logging/custom`

Operation ID: `Update Custom Log Settings`. Tags: settings. Security: oauth2\_application.

Updates the custom log settings.

This endpoint may return the following faults:

*   400 - InvalidCustomLogCategoryException - if one of the categories names are invalid.
*   400 - InvalidLogLevelException - if on a production instance the configured level is DEBUG.
*   400 - InvalidRecipientEmailException - if the email addresses are invalid.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `custom_log_settings`.

#### Responses

*   **400** `InvalidCustomLogCategoryException` - if one of the categories names are invalid. or `InvalidLogLevelException` - if on a production instance the configured level is DEBUG. or `InvalidRecipientEmailException` - if the email addresses are invalid.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_log_settings`.
    

## Schemas

### custom\_log\_settings

Document representing custom logging settings.

*   `debug_permitted` (_boolean_) False if the current instance is production.
*   `debug_to_file` (_boolean_) Indicates if custom debug logs are written to file.
*   `email_to` (_string_) Email addresses for fatal log messages with a maximum length of 1000 characters.  
    Maximum length: 1000.
*   `error_to_file` (_boolean_) Indicates if custom error logs are written to file.
*   `fatal_to_file` (_boolean_) Indicates if custom fatal logs are written to file.
*   `info_to_file` (_boolean_) Indicates if custom info logs are written to file.
*   `log_categories` (_array of log\_category_) Defined custom log categories.
*   `root_level` (_string_) Custom root category log level.
*   `warn_to_file` (_boolean_) Indicates if custom warn logs are written to file.

_Example_

```
{
  "debug_permitted": true,
  "debug_to_file": false,
  "email_to": "admin@example.com",
  "error_to_file": true,
  "fatal_to_file": true,
  "info_to_file": false,
  "root_level": "WARN",
  "warn_to_file": true
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### log\_category

Document representing log category settings.

*   `enabled` (_boolean_) Returns true if the log category is enabled.
*   `level` (_string_) Level of the log category.
*   `name` (_string_) Log category name.

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=6140808da62c9a8057dc63cef9380b5e0208582b6e914076c1bd1f815a29f7c3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-site-preferences.md -->

Data Site Preferences (deprecated)

# Data Site Preferences (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Custom Site Preferences

`GET /sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type}`

Operation ID: `Get Custom Site Preferences`. Tags: sites. Security: oauth2\_application.

For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.

This endpoint may return the following faults:

*   404 - CustomPreferenceGroupNotFoundException - Indicates the preference group is not found.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `instance_type` (path, string, required) One of {staging,development,sandbox,production,current}.
*   `group_id` (path, string, required) The ID of the preference group.
*   `mask_passwords` (query, boolean) Set to true to mask the values of preferences of type Password.

#### Responses

*   **404** `CustomPreferenceGroupNotFoundException` - Indicates the preference group is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `site_preferences`.
    

### PATCH Update Custom Site Preferences

`PATCH /sites/{site_id}/site_preferences/preference_groups/{group_id}/{instance_type}`

Operation ID: `Update Custom Site Preferences`. Tags: sites. Security: oauth2\_application.

For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "\*\*\*\*\*\*\*\*\*\*\*\*" since it is a reserved value.

This endpoint may return the following faults:

*   404 - CustomPreferenceGroupNotFoundException - Indicates the preference group is not found.
*   404 - ObjectTypeNotFoundException - Indicates the SitePreferences system object is not found.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `instance_type` (path, string, required) One of {staging,development,sandbox,production}.
*   `group_id` (path, string, required) The ID of the preference group.
*   `mask_passwords` (query, boolean) Set to true to mask the values of preferences of type Password.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `site_preferences`.

#### Responses

*   **404** `CustomPreferenceGroupNotFoundException` - Indicates the preference group is not found. or `ObjectTypeNotFoundException` - Indicates the SitePreferences system object is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `site_preferences`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### site\_preferences

Represents a set of preferences attached at the organization level.

*   `link` (_string_) A URL that returns the full details for a custom preference
*   `site` (_site_) The site that contains the preferences

_Example_

```
{
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/site_preferences/preference_groups/MyPreferenceGroup/staging",
  "site": {
    "customer_list_link": {
      "customer_list_id": "SiteGenesis",
      "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
    },
    "display_name": {
      "default": "SiteGenesis"
    },
    "id": "SiteGenesis",
    "in_deletion": false,
    "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
    "storefront_status": "online"
  }
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### site

Document representing a site.

*   `cartridges` (_string_) The cartridge Path of the site
*   `creation_date` (_string (date-time)_)
*   `customer_list_link` (_customer\_list\_link_) The link to the customer list.
*   `description` (_object (localized)_) The description of this site.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name entered by the user.
    
    Additional properties: `string`.
    
*   `id` (_string_, required) The id of this site.  
    Minimum length: 1.
*   `in_deletion` (_boolean_) The deletion status of this site, true if in deletion
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link directly to the site
*   `storefront_status` (_string_)  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`.

_Example_

```
{
  "customer_list_link": {
    "customer_list_id": "SiteGenesis",
    "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
  },
  "description": {
    "default": "Prototypical site used for starting point"
  },
  "display_name": {
    "default": "Site Genesis"
  },
  "id": "SiteGenesis",
  "in_deletion": false,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
  "storefront_status": "online"
}
```

### customer\_list\_link

Document representing a link to a customer list.

*   `customer_list_id` (_string_) The customerlist id.
*   `link` (_string_) The target of the link.
*   `title` (_object (localized)_) The link title.
    
    Additional properties: `string`.
    

_Example_

```
{
  "customer_list_id": "SiteGenesis",
  "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
}
```

<!-- document id=96dd9c23b6e4c5cdfb2fa699a2969395aba7728e5214e393747ed971ad92ab04 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-site-search.md -->

Data Site Search (deprecated)

# Data Site Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Sites

`POST /site_search`

Operation ID: `Search Sites`. Tags: site\_search. Security: oauth2\_application.

Searches for sites.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   in\_deletion - Boolean
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   in\_deletion - Boolean
    

This endpoint may return the following faults:

*   400 - EnumConstraintViolationException - Thrown if the invalid value is entered for access\_type
*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `EnumConstraintViolationException` - Thrown if the invalid value is entered for access\_type or `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `site_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### site\_search\_result

Document representing a site search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of site_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "customer_list_link": {
        "customer_list_id": "my-site1",
        "link": "https://example.com/s/-/dw/data/{version}/customer_lists/my-site1"
      },
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "display_name": {
        "de": "A German my-display_name",
        "default": "my-display_name",
        "en": "An English my-display_name"
      },
      "id": "my-site1",
      "in_deletion": false,
      "link": "https://example.com/s/-/dw/data/{version}/sites/my-site1",
      "storefront_status": "online"
    },
    {
      "customer_list_link": {
        "customer_list_id": "my-site2",
        "link": "https://example.com/s/-/dw/data/{version}/customer_lists/my-site2"
      },
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "display_name": {
        "de": "A German my-display_name",
        "default": "my-display_name",
        "en": "An English my-display_name"
      },
      "id": "my-site2",
      "in_deletion": false,
      "link": "https://example.com/s/-/dw/data/{version}/sites/my-site2",
      "storefront_status": "online"
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### site

Document representing a site.

*   `cartridges` (_string_) The cartridge Path of the site
*   `creation_date` (_string (date-time)_)
*   `customer_list_link` (_customer\_list\_link_) The link to the customer list.
*   `description` (_object (localized)_) The description of this site.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name entered by the user.
    
    Additional properties: `string`.
    
*   `id` (_string_, required) The id of this site.  
    Minimum length: 1.
*   `in_deletion` (_boolean_) The deletion status of this site, true if in deletion
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link directly to the site
*   `storefront_status` (_string_)  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`.

_Example_

```
{
  "customer_list_link": {
    "customer_list_id": "SiteGenesis",
    "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
  },
  "description": {
    "default": "Prototypical site used for starting point"
  },
  "display_name": {
    "default": "Site Genesis"
  },
  "id": "SiteGenesis",
  "in_deletion": false,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
  "storefront_status": "online"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### customer\_list\_link

Document representing a link to a customer list.

*   `customer_list_id` (_string_) The customerlist id.
*   `link` (_string_) The target of the link.
*   `title` (_object (localized)_) The link title.
    
    Additional properties: `string`.
    

_Example_

```
{
  "customer_list_id": "SiteGenesis",
  "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=33192f848c717253b385913bac8cf34b8d6cdda914554758e034fdfe0261dfdf url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-sites.md -->

Data Sites (deprecated)

# Data Sites (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Sites

`GET /sites`

Operation ID: `Get Sites`. Tags: sites. Security: oauth2\_application.

Action to get all existing sites.

#### Parameters

*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `sites`.
    

### GET Get site

`GET /sites/{site_id}`

Operation ID: `Get site`. Tags: sites. Security: oauth2\_application.

Action to read an existing site.

#### Parameters

*   `site_id` (path, string, required) the id of the site  
    Minimum length: 1.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `site`.
    

## Schemas

### sites

Document representing an unfiltered list of sites.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of site_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "customer_list_link": {
        "customer_list_id": "SiteGenesis",
        "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
      },
      "description": {
        "default": "Prototypical site used for starting point"
      },
      "display_name": {
        "default": "Site Genesis"
      },
      "id": "SiteGenesis",
      "in_deletion": false,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
      "storefront_status": "online"
    },
    {
      "customer_list_link": {
        "customer_list_id": "MyCustomerList",
        "link": "https://example.com/s/-/dw/data/{version}/customer_lists/MyCustomerList"
      },
      "description": {
        "default": "A site that sells products"
      },
      "display_name": {
        "default": "My Site"
      },
      "id": "MySite",
      "in_deletion": false,
      "link": "https://example.com/s/-/dw/data/{version}/sites/MySite",
      "storefront_status": "online"
    }
  ],
  "select": "**",
  "start": 0,
  "total": 2
}
```

### site

Document representing a site.

*   `cartridges` (_string_) The cartridge Path of the site
*   `creation_date` (_string (date-time)_)
*   `customer_list_link` (_customer\_list\_link_) The link to the customer list.
*   `description` (_object (localized)_) The description of this site.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The display name entered by the user.
    
    Additional properties: `string`.
    
*   `id` (_string_, required) The id of this site.  
    Minimum length: 1.
*   `in_deletion` (_boolean_) The deletion status of this site, true if in deletion
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link directly to the site
*   `storefront_status` (_string_)  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`.

_Example_

```
{
  "customer_list_link": {
    "customer_list_id": "SiteGenesis",
    "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
  },
  "description": {
    "default": "Prototypical site used for starting point"
  },
  "display_name": {
    "default": "Site Genesis"
  },
  "id": "SiteGenesis",
  "in_deletion": false,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis",
  "storefront_status": "online"
}
```

### customer\_list\_link

Document representing a link to a customer list.

*   `customer_list_id` (_string_) The customerlist id.
*   `link` (_string_) The target of the link.
*   `title` (_object (localized)_) The link title.
    
    Additional properties: `string`.
    

_Example_

```
{
  "customer_list_id": "SiteGenesis",
  "link": "https://example.com/s/-/dw/data/{version}/customer_lists/SiteGenesis"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=a88b1531c76fe12b6cb38ddaf007692e580d790530575ee821544f4272ae9d21 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-slot-configuration-campaign-assignment-search.md -->

Data Slot Configuration Campaign Assignment Search (deprecated)

# Data Slot Configuration Campaign Assignment Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search SlotConfiguration Campaign Assignments

`POST /sites/{site_id}/slot_configuration_campaign_assignment_search`

Operation ID: `Search SlotConfiguration Campaign Assignments`. Tags: sites. Security: oauth2\_application.

Searches for slotconfiguration campaign assignments.

The SlotConfigCampaignAssignment Search document contains a search object that allows filtering on various attributes.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. These are the list of searchable attributes with their corresponding buckets:

Main:

*   rank - Integer
    
*   start\_date - Date
    
*   end\_date - Date
    

Campaign:

*   campaign\_id - String
    
*   enabled - Boolean
    

Slot configuration:

*   slot\_configuration\_id - String
    
*   description - String
    

Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining rank and description above, only a conjunction is allowed (AND), whereas slot\_configuration\_id and description can be joined using a disjunction because they are in the same bucket. If an attribute is used in a disjunction (OR) that violates this rule, an exception will be thrown.

Expands that can be applied for the search request

*   campaign
    
*   slotConfiguration
    

Note that only searchable attributes (excluding the ones marked with above with an asterisk) can be used in sorting.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The site context.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot_configuration_campaign_assignment_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### slot\_configuration\_campaign\_assignment\_search\_result

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of slot\_configuration\_campaign\_assignment_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "expand": [
    "slotConfiguration"
  ],
  "hits": [
    {
      "campaign_id": "campaign-registered",
      "context": "global",
      "description": "Free Microsoft Zune With Purchase Of $500 Or More In Electronics",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slot_configuration_campaign_assignments/campaign-registered",
      "schedule": {},
      "slot_configuration": {
        "assignment_information": {
          "active": true,
          "active_campaign_assignments": {
            "campaign_id": "campaign-registered",
            "context": "global",
            "enabled": true,
            "rank": 40
          }
        }
      },
      "slot_configuration_id": "Promo Zune",
      "slot_configuration_uuid": "bdL6MiWcbpakEaaadkHwIhZj1N",
      "slot_id": "404-promo"
    }
  ],
  "query": {
    "term_query": {
      "fields": [
        "campaign_id"
      ],
      "operator": "is",
      "values": [
        "campaign-registered"
      ]
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 1
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### slot\_configuration\_campaign\_assignment

Document representing a slot\_configuration\_campaign\_assignment

*   `campaign` (_campaign_) The campaign.
*   `campaign_id` (_string_) The id of the campaign that has the slot configuration assigned to it.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_, required) The slot context.  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The list of customer groups.
*   `description` (_string_) The description of the slot configuration.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL to the slot configuration-campaign assignment.
*   `rank` (_integer (int32)_) The rank of the slot confiuration-campaign assignment. This is different than the rank of the slot configuration.  
    Minimum: 1.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `slot_configuration` (_slot\_configuration_) The slotConfiguration
*   `slot_configuration_id` (_string_, required) The ID of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `slot_configuration_uuid` (_string_) The UUID of the slot configuration.  
    Maximum length: 28.
*   `slot_context_id` (_string_) The ID of the slot's context, for example, the category ID for a slot with category context.  
    Maximum length: 256.
*   `slot_id` (_string_, required) The ID of the slot.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "campaign_id": "campaign-registered",
  "context": "global",
  "description": "Free Microsoft Zune With Purchase Of $500 Or More In Electronics",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slot_configuration_campaign_assignments/campaign-registered",
  "schedule": {},
  "slot_configuration": {
    "assignment_information": {
      "active": true,
      "active_campaign_assignments": {
        "campaign_id": "campaign-registered",
        "context": "global",
        "enabled": true,
        "rank": 40
      }
    }
  },
  "slot_configuration_id": "Promo Zune",
  "slot_configuration_uuid": "bdL6MiWcbpakEaaadkHwIhZj1N",
  "slot_id": "404-promo"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### slot\_configuration

Document representing a slot configuration.

*   `assignment_information` (_slot\_configuration\_assignment\_information_) Information about the assignments and assignment schedules of this slot configuration
*   `callout_msg` (_object (localized)_) The call out message.
    
    Additional properties: `markup_text`.
    
*   `configuration_id` (_string_) The id of this configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_) The context of the slot. Ignored in input documents.  
    Allowed values: `global`, `category`, `folder`.
*   `context_id` (_string_) When the context is _category_, this is a _category\_id_; when the context is _folder_, this is a _folder\_id_; and when the context is _global_, this is obsolete. This is ignored in input documents.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The customer groups ids.
*   `default` (_boolean_) A flag indicating whether the configuration is the default one for the slot.
*   `description` (_string_) The configuration description.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the slot is enabled.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link.
*   `rank` (_integer (int32)_) The rank of the slot configuration on its slot. This rank has nothing to do with the rank on any campaign-assignment, because these are completely different objects. These must be updated separately.  
    Allowed values: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100`. Minimum: 1.
*   `schedule` (_schedule_) The schedule for the slot.
*   `slot_content` (_slot\_content_, required) The content of the slot.
*   `slot_id` (_string_) The ID of the slot. Ignored in input documents.  
    Minimum length: 1. Maximum length: 256.
*   `template` (_string_) The template.  
    Maximum length: 256.
*   `uuid` (_string_, read-only) The uuid of the slot configuration. This property cannot be written and is ignored in input documents.  
    Minimum length: 1. Maximum length: 28.

_Example_

```
{
  "assigned_to_site": true,
  "callout_msg": {
    "default": "some message"
  },
  "configuration_id": "2015-06-24_16:33:18",
  "context": "global",
  "customer_groups": [
    "Administrators",
    "Registered"
  ],
  "default": true,
  "description": "slot configuration description",
  "enabled": true,
  "rank": 2,
  "schedule": {
    "end_date": "2022-03-28T23:21:00.000Z",
    "recurrence": {
      "day_of_week": [
        "monday",
        "sunday"
      ],
      "time_of_day": {
        "time_from": "00:00:00",
        "time_to": "23:59:00"
      }
    },
    "start_date": "2013-03-28T23:21:00.000Z"
  },
  "slot_content": {
    "body": {
      "default": "<html>HTML content</html>"
    },
    "type": "html"
  },
  "slot_id": "header-banner",
  "uuid": "fsdoi43ofijwdf"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### slot\_configuration\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": false,
  "enabled": false,
  "schedule_type": "none"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### slot\_content

Document representing the content type for a slot.

*   `body` (_object (localized)_) The HTML body (valid only for type 'html').
    
    Additional properties: `markup_text`.
    
*   `category_ids` (_array of string_) The category ids (valid only for type 'categories').
*   `content_asset_ids` (_array of string_) The content asset ids (valid only for type 'content\_assets').
*   `product_ids` (_array of string_) The product ids (valid only for type 'products').
*   `type` (_string_, required) The type of content in the slot.  
    Allowed values: `products`, `categories`, `content_assets`, `html`, `recommended_products`.

_Example_

```
{
  "type": "html"
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

### slot\_configuration\_abtest\_group\_assignment

Document representing a SlotConfiguration AB test group assignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `abtest_id` (_string_) The id for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `enabled` (_boolean_) True if the ABTest is enabled
*   `schedule` (_schedule_) The schedule information for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `segment_id` (_string_) The id for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=9eb3314936d017a87c461da8e3194ac2c9b15cf52efb5771dcd48e16d0228795 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-slot-configuration-search.md -->

Data Slot Configuration Search (deprecated)

# Data Slot Configuration Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Slot Configurations

`POST /sites/{site_id}/slot_configuration_search`

Operation ID: `Search Slot Configurations`. Tags: sites. Security: oauth2\_application.

Searches for slot configurations.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. These are the list of searchable attributes with their corresponding buckets:

Main:

*   configuration\_id - String
    
*   default - Boolean
    
*   description - String
    
*   enabled - Boolean
    

Slot:

*   context - String
    
*   slot\_id - String
    

Only fields in the same bucket can be joined using a disjunction (OR). For instance, when joining context and description above, only a conjunction is allowed (AND), whereas context and slot\_id can be joined to each other using a disjunction because they are in the same bucket. If the field is used in a disjunction (OR) that violates this rule, an exception will be thrown.

This endpoint may return the following faults:

*   400 - TypeMissmatchException - Indicates that the value to search with does not match the type of the search field.

#### Parameters

*   `site_id` (path, string, required) The site context.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `TypeMissmatchException` - Indicates that the value to search with does not match the type of the search field.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot_configuration_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### slot\_configuration\_search\_result

Document representing a slot configuration search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of slot\_configuration_) The sorted array of search hits. This array can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "_resource_state": "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
      "callout_msg": {
        "de-DE": "Deutsche Nachricht",
        "default": "some message",
        "en-US": "US american message"
      },
      "configuration_id": "header_banner_html",
      "context": "category",
      "context_id": "men_shoes",
      "customer_groups": [
        "Administrators",
        "Registered"
      ],
      "default": true,
      "description": "slot configuration description",
      "enabled": true,
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slots/header-banner/slot_configurations/fsdoi43ofijwdf?context=category%3Dmen_shoes",
      "rank": 2,
      "schedule": {
        "end_date": "2022-03-28T23:21:00.000Z",
        "recurrence": {
          "day_of_week": [
            "monday",
            "sunday"
          ],
          "time_of_day": {
            "time_from": "00:00:00",
            "time_to": "23:59:00"
          }
        },
        "start_date": "2013-03-28T23:21:00.000Z"
      },
      "slot_content": {
        "body": {
          "de-DE": "<html>HTML Inhalt</html>",
          "default": "<html>HTML content</html>",
          "en-US": "<html>HTML content</html>"
        },
        "type": "html"
      },
      "slot_id": "header-banner"
    }
  ],
  "select": "(**)",
  "start": 0
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### slot\_configuration

Document representing a slot configuration.

*   `assignment_information` (_slot\_configuration\_assignment\_information_) Information about the assignments and assignment schedules of this slot configuration
*   `callout_msg` (_object (localized)_) The call out message.
    
    Additional properties: `markup_text`.
    
*   `configuration_id` (_string_) The id of this configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_) The context of the slot. Ignored in input documents.  
    Allowed values: `global`, `category`, `folder`.
*   `context_id` (_string_) When the context is _category_, this is a _category\_id_; when the context is _folder_, this is a _folder\_id_; and when the context is _global_, this is obsolete. This is ignored in input documents.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The customer groups ids.
*   `default` (_boolean_) A flag indicating whether the configuration is the default one for the slot.
*   `description` (_string_) The configuration description.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the slot is enabled.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link.
*   `rank` (_integer (int32)_) The rank of the slot configuration on its slot. This rank has nothing to do with the rank on any campaign-assignment, because these are completely different objects. These must be updated separately.  
    Allowed values: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100`. Minimum: 1.
*   `schedule` (_schedule_) The schedule for the slot.
*   `slot_content` (_slot\_content_, required) The content of the slot.
*   `slot_id` (_string_) The ID of the slot. Ignored in input documents.  
    Minimum length: 1. Maximum length: 256.
*   `template` (_string_) The template.  
    Maximum length: 256.
*   `uuid` (_string_, read-only) The uuid of the slot configuration. This property cannot be written and is ignored in input documents.  
    Minimum length: 1. Maximum length: 28.

_Example_

```
{
  "assigned_to_site": true,
  "callout_msg": {
    "default": "some message"
  },
  "configuration_id": "2015-06-24_16:33:18",
  "context": "global",
  "customer_groups": [
    "Administrators",
    "Registered"
  ],
  "default": true,
  "description": "slot configuration description",
  "enabled": true,
  "rank": 2,
  "schedule": {
    "end_date": "2022-03-28T23:21:00.000Z",
    "recurrence": {
      "day_of_week": [
        "monday",
        "sunday"
      ],
      "time_of_day": {
        "time_from": "00:00:00",
        "time_to": "23:59:00"
      }
    },
    "start_date": "2013-03-28T23:21:00.000Z"
  },
  "slot_content": {
    "body": {
      "default": "<html>HTML content</html>"
    },
    "type": "html"
  },
  "slot_id": "header-banner",
  "uuid": "fsdoi43ofijwdf"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### slot\_configuration\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": false,
  "enabled": false,
  "schedule_type": "none"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### slot\_content

Document representing the content type for a slot.

*   `body` (_object (localized)_) The HTML body (valid only for type 'html').
    
    Additional properties: `markup_text`.
    
*   `category_ids` (_array of string_) The category ids (valid only for type 'categories').
*   `content_asset_ids` (_array of string_) The content asset ids (valid only for type 'content\_assets').
*   `product_ids` (_array of string_) The product ids (valid only for type 'products').
*   `type` (_string_, required) The type of content in the slot.  
    Allowed values: `products`, `categories`, `content_assets`, `html`, `recommended_products`.

_Example_

```
{
  "type": "html"
}
```

### slot\_configuration\_abtest\_group\_assignment

Document representing a SlotConfiguration AB test group assignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `abtest_id` (_string_) The id for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `enabled` (_boolean_) True if the ABTest is enabled
*   `schedule` (_schedule_) The schedule information for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `segment_id` (_string_) The id for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.

### slot\_configuration\_campaign\_assignment

Document representing a slot\_configuration\_campaign\_assignment

*   `campaign` (_campaign_) The campaign.
*   `campaign_id` (_string_) The id of the campaign that has the slot configuration assigned to it.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_, required) The slot context.  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The list of customer groups.
*   `description` (_string_) The description of the slot configuration.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL to the slot configuration-campaign assignment.
*   `rank` (_integer (int32)_) The rank of the slot confiuration-campaign assignment. This is different than the rank of the slot configuration.  
    Minimum: 1.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `slot_configuration` (_slot\_configuration_) The slotConfiguration
*   `slot_configuration_id` (_string_, required) The ID of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `slot_configuration_uuid` (_string_) The UUID of the slot configuration.  
    Maximum length: 28.
*   `slot_context_id` (_string_) The ID of the slot's context, for example, the category ID for a slot with category context.  
    Maximum length: 256.
*   `slot_id` (_string_, required) The ID of the slot.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "campaign_id": "campaign-registered",
  "context": "global",
  "description": "Free Microsoft Zune With Purchase Of $500 Or More In Electronics",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slot_configuration_campaign_assignments/campaign-registered",
  "schedule": {},
  "slot_configuration": {
    "assignment_information": {
      "active": true,
      "active_campaign_assignments": {
        "campaign_id": "campaign-registered",
        "context": "global",
        "enabled": true,
        "rank": 40
      }
    }
  },
  "slot_configuration_id": "Promo Zune",
  "slot_configuration_uuid": "bdL6MiWcbpakEaaadkHwIhZj1N",
  "slot_id": "404-promo"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=da10edbbef7c8e4c3cef12c89d34455161dc0b055aabeb210e755fb7a7450a34 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-slot-configurations.md -->

Data Slot Configurations (deprecated)

# Data Slot Configurations (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Slot Configurations

`GET /sites/{site_id}/slot_configurations`

Operation ID: `Get Slot Configurations`. Tags: sites. Security: oauth2\_application.

Action to get all the slot configurations with no filtering.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot_configurations`.
    

## Schemas

### slot\_configurations

Document representing an unfiltered list of slot configurations.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of slot\_configuration_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### slot\_configuration

Document representing a slot configuration.

*   `assignment_information` (_slot\_configuration\_assignment\_information_) Information about the assignments and assignment schedules of this slot configuration
*   `callout_msg` (_object (localized)_) The call out message.
    
    Additional properties: `markup_text`.
    
*   `configuration_id` (_string_) The id of this configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_) The context of the slot. Ignored in input documents.  
    Allowed values: `global`, `category`, `folder`.
*   `context_id` (_string_) When the context is _category_, this is a _category\_id_; when the context is _folder_, this is a _folder\_id_; and when the context is _global_, this is obsolete. This is ignored in input documents.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The customer groups ids.
*   `default` (_boolean_) A flag indicating whether the configuration is the default one for the slot.
*   `description` (_string_) The configuration description.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the slot is enabled.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link.
*   `rank` (_integer (int32)_) The rank of the slot configuration on its slot. This rank has nothing to do with the rank on any campaign-assignment, because these are completely different objects. These must be updated separately.  
    Allowed values: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100`. Minimum: 1.
*   `schedule` (_schedule_) The schedule for the slot.
*   `slot_content` (_slot\_content_, required) The content of the slot.
*   `slot_id` (_string_) The ID of the slot. Ignored in input documents.  
    Minimum length: 1. Maximum length: 256.
*   `template` (_string_) The template.  
    Maximum length: 256.
*   `uuid` (_string_, read-only) The uuid of the slot configuration. This property cannot be written and is ignored in input documents.  
    Minimum length: 1. Maximum length: 28.

_Example_

```
{
  "assigned_to_site": true,
  "callout_msg": {
    "default": "some message"
  },
  "configuration_id": "2015-06-24_16:33:18",
  "context": "global",
  "customer_groups": [
    "Administrators",
    "Registered"
  ],
  "default": true,
  "description": "slot configuration description",
  "enabled": true,
  "rank": 2,
  "schedule": {
    "end_date": "2022-03-28T23:21:00.000Z",
    "recurrence": {
      "day_of_week": [
        "monday",
        "sunday"
      ],
      "time_of_day": {
        "time_from": "00:00:00",
        "time_to": "23:59:00"
      }
    },
    "start_date": "2013-03-28T23:21:00.000Z"
  },
  "slot_content": {
    "body": {
      "default": "<html>HTML content</html>"
    },
    "type": "html"
  },
  "slot_id": "header-banner",
  "uuid": "fsdoi43ofijwdf"
}
```

### slot\_configuration\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": false,
  "enabled": false,
  "schedule_type": "none"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### slot\_content

Document representing the content type for a slot.

*   `body` (_object (localized)_) The HTML body (valid only for type 'html').
    
    Additional properties: `markup_text`.
    
*   `category_ids` (_array of string_) The category ids (valid only for type 'categories').
*   `content_asset_ids` (_array of string_) The content asset ids (valid only for type 'content\_assets').
*   `product_ids` (_array of string_) The product ids (valid only for type 'products').
*   `type` (_string_, required) The type of content in the slot.  
    Allowed values: `products`, `categories`, `content_assets`, `html`, `recommended_products`.

_Example_

```
{
  "type": "html"
}
```

### slot\_configuration\_abtest\_group\_assignment

Document representing a SlotConfiguration AB test group assignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `abtest_id` (_string_) The id for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `enabled` (_boolean_) True if the ABTest is enabled
*   `schedule` (_schedule_) The schedule information for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `segment_id` (_string_) The id for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.

### slot\_configuration\_campaign\_assignment

Document representing a slot\_configuration\_campaign\_assignment

*   `campaign` (_campaign_) The campaign.
*   `campaign_id` (_string_) The id of the campaign that has the slot configuration assigned to it.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_, required) The slot context.  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The list of customer groups.
*   `description` (_string_) The description of the slot configuration.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL to the slot configuration-campaign assignment.
*   `rank` (_integer (int32)_) The rank of the slot confiuration-campaign assignment. This is different than the rank of the slot configuration.  
    Minimum: 1.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `slot_configuration` (_slot\_configuration_) The slotConfiguration
*   `slot_configuration_id` (_string_, required) The ID of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `slot_configuration_uuid` (_string_) The UUID of the slot configuration.  
    Maximum length: 28.
*   `slot_context_id` (_string_) The ID of the slot's context, for example, the category ID for a slot with category context.  
    Maximum length: 256.
*   `slot_id` (_string_, required) The ID of the slot.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "campaign_id": "campaign-registered",
  "context": "global",
  "description": "Free Microsoft Zune With Purchase Of $500 Or More In Electronics",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slot_configuration_campaign_assignments/campaign-registered",
  "schedule": {},
  "slot_configuration": {
    "assignment_information": {
      "active": true,
      "active_campaign_assignments": {
        "campaign_id": "campaign-registered",
        "context": "global",
        "enabled": true,
        "rank": 40
      }
    }
  },
  "slot_configuration_id": "Promo Zune",
  "slot_configuration_uuid": "bdL6MiWcbpakEaaadkHwIhZj1N",
  "slot_id": "404-promo"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=8158f912586c82632156ea952902c79d2b674f5df06b6c9bf91be32d7f6963cd url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-slot-search.md -->

Data Slot Search (deprecated)

# Data Slot Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Slots

`POST /sites/{site_id}/slot_search`

Operation ID: `Search Slots`. Tags: sites. Security: oauth2\_application.

Searches for slots.

The query attribute specifies a complex query that can be used to narrow down the search. The set of fields that are available to search are:

*   slot\_id - String
    
*   description - String
    
*   context\_type - String
    

Note that only searchable attributes can be used in sorting. "context\_type" value is restricted to Global/Folder/Category.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The site context.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### slot\_search\_result

Document representing a slot search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of slot_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### slot

Document representing a slot

*   `context_type` (_string_) A slot context  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `description` (_string_) The user supplied description of the slot  
    Maximum length: 4000.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link to the slot
*   `preview_url` (_string_) A preview URL the slot
*   `slot_configurations` (_array of slot\_configuration_) A list of slotconfigurations this slot has
*   `slot_id` (_string_, required) The id for the slot  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "context_type": "global",
  "description": "description for slot",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slots/my-slot/global",
  "slot_configurations": {
    "assignment_information": {
      "active": false,
      "enabled": false,
      "schedule_type": "none"
    },
    "configuration_id": "my-config",
    "context": "global",
    "default": false,
    "enabled": true,
    "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slots/my-slot/slot_configurations/Account%20Banner",
    "slot_content": {
      "type": "html"
    },
    "slot_id": "my-slot",
    "template": "slots/html/htmlslotcontainer.isml",
    "uuid": "cw6YLaOace0MUqwcsju07iKn3j"
  },
  "slot_id": "my-slot"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### slot\_configuration

Document representing a slot configuration.

*   `assignment_information` (_slot\_configuration\_assignment\_information_) Information about the assignments and assignment schedules of this slot configuration
*   `callout_msg` (_object (localized)_) The call out message.
    
    Additional properties: `markup_text`.
    
*   `configuration_id` (_string_) The id of this configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_) The context of the slot. Ignored in input documents.  
    Allowed values: `global`, `category`, `folder`.
*   `context_id` (_string_) When the context is _category_, this is a _category\_id_; when the context is _folder_, this is a _folder\_id_; and when the context is _global_, this is obsolete. This is ignored in input documents.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The customer groups ids.
*   `default` (_boolean_) A flag indicating whether the configuration is the default one for the slot.
*   `description` (_string_) The configuration description.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the slot is enabled.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link.
*   `rank` (_integer (int32)_) The rank of the slot configuration on its slot. This rank has nothing to do with the rank on any campaign-assignment, because these are completely different objects. These must be updated separately.  
    Allowed values: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100`. Minimum: 1.
*   `schedule` (_schedule_) The schedule for the slot.
*   `slot_content` (_slot\_content_, required) The content of the slot.
*   `slot_id` (_string_) The ID of the slot. Ignored in input documents.  
    Minimum length: 1. Maximum length: 256.
*   `template` (_string_) The template.  
    Maximum length: 256.
*   `uuid` (_string_, read-only) The uuid of the slot configuration. This property cannot be written and is ignored in input documents.  
    Minimum length: 1. Maximum length: 28.

_Example_

```
{
  "assigned_to_site": true,
  "callout_msg": {
    "default": "some message"
  },
  "configuration_id": "2015-06-24_16:33:18",
  "context": "global",
  "customer_groups": [
    "Administrators",
    "Registered"
  ],
  "default": true,
  "description": "slot configuration description",
  "enabled": true,
  "rank": 2,
  "schedule": {
    "end_date": "2022-03-28T23:21:00.000Z",
    "recurrence": {
      "day_of_week": [
        "monday",
        "sunday"
      ],
      "time_of_day": {
        "time_from": "00:00:00",
        "time_to": "23:59:00"
      }
    },
    "start_date": "2013-03-28T23:21:00.000Z"
  },
  "slot_content": {
    "body": {
      "default": "<html>HTML content</html>"
    },
    "type": "html"
  },
  "slot_id": "header-banner",
  "uuid": "fsdoi43ofijwdf"
}
```

### slot\_configuration\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": false,
  "enabled": false,
  "schedule_type": "none"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### slot\_content

Document representing the content type for a slot.

*   `body` (_object (localized)_) The HTML body (valid only for type 'html').
    
    Additional properties: `markup_text`.
    
*   `category_ids` (_array of string_) The category ids (valid only for type 'categories').
*   `content_asset_ids` (_array of string_) The content asset ids (valid only for type 'content\_assets').
*   `product_ids` (_array of string_) The product ids (valid only for type 'products').
*   `type` (_string_, required) The type of content in the slot.  
    Allowed values: `products`, `categories`, `content_assets`, `html`, `recommended_products`.

_Example_

```
{
  "type": "html"
}
```

### slot\_configuration\_abtest\_group\_assignment

Document representing a SlotConfiguration AB test group assignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `abtest_id` (_string_) The id for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `enabled` (_boolean_) True if the ABTest is enabled
*   `schedule` (_schedule_) The schedule information for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `segment_id` (_string_) The id for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.

### slot\_configuration\_campaign\_assignment

Document representing a slot\_configuration\_campaign\_assignment

*   `campaign` (_campaign_) The campaign.
*   `campaign_id` (_string_) The id of the campaign that has the slot configuration assigned to it.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_, required) The slot context.  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The list of customer groups.
*   `description` (_string_) The description of the slot configuration.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL to the slot configuration-campaign assignment.
*   `rank` (_integer (int32)_) The rank of the slot confiuration-campaign assignment. This is different than the rank of the slot configuration.  
    Minimum: 1.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `slot_configuration` (_slot\_configuration_) The slotConfiguration
*   `slot_configuration_id` (_string_, required) The ID of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `slot_configuration_uuid` (_string_) The UUID of the slot configuration.  
    Maximum length: 28.
*   `slot_context_id` (_string_) The ID of the slot's context, for example, the category ID for a slot with category context.  
    Maximum length: 256.
*   `slot_id` (_string_, required) The ID of the slot.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "campaign_id": "campaign-registered",
  "context": "global",
  "description": "Free Microsoft Zune With Purchase Of $500 Or More In Electronics",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slot_configuration_campaign_assignments/campaign-registered",
  "schedule": {},
  "slot_configuration": {
    "assignment_information": {
      "active": true,
      "active_campaign_assignments": {
        "campaign_id": "campaign-registered",
        "context": "global",
        "enabled": true,
        "rank": 40
      }
    }
  },
  "slot_configuration_id": "Promo Zune",
  "slot_configuration_uuid": "bdL6MiWcbpakEaaadkHwIhZj1N",
  "slot_id": "404-promo"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=9b3f939407c52a889a18f9449e1ee4bce1487b11f280649b894c856791a6aff3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-slots.md -->

Data Slots (deprecated)

# Data Slots (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Slots

`GET /sites/{site_id}/slots`

Operation ID: `Get Slots`. Tags: sites. Security: oauth2\_application.

Action to get all the slots with no filtering. Fetches the slot entities which are already populated in the database by crawling the active code.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slots`.
    

### GET Get slot configuration

`GET /sites/{site_id}/slots/{slot_id}/slot_configurations/{configuration_id}`

Operation ID: `Get slot configuration`. Tags: sites. Security: oauth2\_application.

Action to read an existing slot configuration.

This endpoint may return the following faults:

*   400 - InvalidContextTypeException - Thrown if the specified context type is invalid.
*   400 - MissingSlotConfigurationContextIdException - Thrown if the specified context id for given context 'category' or 'folder' is missing.
*   404 - SlotConfigurationNotFoundException - Thrown if there was no slot configuration found for the specified configuration id.
*   404 - SlotNotFoundException - Throw if there was no slot with the specified id found for the requested site.

#### Parameters

*   `site_id` (path, string, required) The id of the site for which you want to create the slot configuration.  
    Minimum length: 1. Maximum length: 32.
*   `slot_id` (path, string, required) The id of the slot.  
    Minimum length: 1. Maximum length: 256.
*   `configuration_id` (path, string, required) The id of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be _folder_ , _category_ or _global_ ), an equals sign ( **\=** ), and the context id (either the category id or folder id). If you do not set this query parameter, the global context is used by default.

#### Responses

*   **400** `InvalidContextTypeException` - Thrown if the specified context type is invalid. or `MissingSlotConfigurationContextIdException` - Thrown if the specified context id for given context 'category' or 'folder' is missing.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SlotConfigurationNotFoundException` - Thrown if there was no slot configuration found for the specified configuration id. or `SlotNotFoundException` - Throw if there was no slot with the specified id found for the requested site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot_configuration`.
    

### PUT Create slot configuration

`PUT /sites/{site_id}/slots/{slot_id}/slot_configurations/{configuration_id}`

Operation ID: `Create slot configuration`. Tags: sites. Security: oauth2\_application.

Creates a new configuration for an existing slot. If a slot configuration exists with the specified configuration\_id, slot\_id, and context, the existing slot configuration is overwritten.

This endpoint may return the following faults:

*   400 - IdConflictException - if the Id in request is not the same as the ID in document.
*   400 - InvalidContextTypeException - Thrown if the specified context type is invalid.
*   400 - MissingSlotConfigurationContextIdException - Thrown if the specified context id for given context 'category' or 'folder' is missing.
*   404 - ContentNotFoundException - Thrown if content asset does not exist in the library of the current domain but is assigned during creation of the configuration.
*   404 - SlotNotFoundException - Thrown if there was no slot with the given id found for the requested site.

#### Parameters

*   `site_id` (path, string, required) The id of the site for which you want to create the slot configuration.  
    Minimum length: 1. Maximum length: 32.
*   `slot_id` (path, string, required) The id of the slot.  
    Minimum length: 1. Maximum length: 256.
*   `configuration_id` (path, string, required) The id of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be _folder_ , _category_ or _global_ ), an equals sign ( **\=** ), and the context id (either the category id or folder id). If you do not set this query parameter, the global context is used by default.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `slot_configuration`.

#### Responses

*   **400** `IdConflictException` - if the Id in request is not the same as the ID in document. or `InvalidContextTypeException` - Thrown if the specified context type is invalid. or `MissingSlotConfigurationContextIdException` - Thrown if the specified context id for given context 'category' or 'folder' is missing.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ContentNotFoundException` - Thrown if content asset does not exist in the library of the current domain but is assigned during creation of the configuration. or `SlotNotFoundException` - Thrown if there was no slot with the given id found for the requested site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot_configuration`.
    

### DELETE Delete slot configuration

`DELETE /sites/{site_id}/slots/{slot_id}/slot_configurations/{configuration_id}`

Operation ID: `Delete slot configuration`. Tags: sites. Security: oauth2\_application.

Removes a configuration for slot in a given context from a site.

This endpoint may return the following faults:

*   400 - InvalidContextTypeException - Thrown if the specified context type is invalid.
*   404 - SlotNotFoundException - Throw if there was no slot with the specified id found for the requested site.

#### Parameters

*   `site_id` (path, string, required) The id of the site for which you want to create the slot configuration.  
    Minimum length: 1. Maximum length: 32.
*   `slot_id` (path, string, required) The id of the slot.  
    Minimum length: 1. Maximum length: 256.
*   `configuration_id` (path, string, required) The id of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be _folder_ , _category_ or _global_ ), an equals sign ( **\=** ), and the context id (either the category id or folder id). If you do not set this query parameter, the global context is used by default.

#### Responses

*   **204**
*   **400** `InvalidContextTypeException` - Thrown if the specified context type is invalid.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `SlotNotFoundException` - Throw if there was no slot with the specified id found for the requested site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update slot configuration

`PATCH /sites/{site_id}/slots/{slot_id}/slot_configurations/{configuration_id}`

Operation ID: `Update slot configuration`. Tags: sites. Security: oauth2\_application.

Updates an existing slot configuration. This action ignores the slot\_id and the context information in the input document. Note that this operation will not touch any relational properties, which means, that e.g. the rank on a specific campaign assignment will not be changed, when the rank for the slot configuration itself is updated.

This endpoint may return the following faults:

*   400 - InvalidContextTypeException - Thrown if the specified context type is invalid.
*   400 - MissingSlotConfigurationContextIdException - Thrown if the specified context id for given context 'category' or 'folder' is missing.
*   404 - ContentNotFoundException - Thrown if content asset does not exist in the library of the current domain but is assigned during update.
*   404 - SlotConfigurationNotFoundException - Thrown if there was no slot configuration found for the specified configuration id.
*   404 - SlotNotFoundException - Thrown if there was no slot with the given id found for the requested site.
*   409 - SlotConfigurationAlreadyExistsException - Thrown if the configuration ID should be updated into one that is already assigned.

#### Parameters

*   `site_id` (path, string, required) The id of the site for which you want to create the slot configuration.  
    Minimum length: 1. Maximum length: 32.
*   `slot_id` (path, string, required) The id of the slot.  
    Minimum length: 1. Maximum length: 256.
*   `configuration_id` (path, string, required) The id of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (query, string) The context string, which consists of three parts: the context type (which must be _folder_ , _category_ or _global_ ), an equals sign ( **\=** ), and the context id (either the category id or folder id). If you do not set this query parameter, the global context is used by default.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `slot_configuration`.

#### Responses

*   **400** `InvalidContextTypeException` - Thrown if the specified context type is invalid. or `MissingSlotConfigurationContextIdException` - Thrown if the specified context id for given context 'category' or 'folder' is missing.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ContentNotFoundException` - Thrown if content asset does not exist in the library of the current domain but is assigned during update. or `SlotConfigurationNotFoundException` - Thrown if there was no slot configuration found for the specified configuration id. or `SlotNotFoundException` - Thrown if there was no slot with the given id found for the requested site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `SlotConfigurationAlreadyExistsException` - Thrown if the configuration ID should be updated into one that is already assigned.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot_configuration`.
    

### GET Get Slot

`GET /sites/{site_id}/slots/{slot_id}/{context_type}`

Operation ID: `Get Slot`. Tags: sites. Security: oauth2\_application.

Action to get slot information. Fetches the slot entities which are already populated in the database by crawling the active code.

This endpoint may return the following faults:

*   404 - SlotNotFoundException - Indicates the slot does not exist matching the given id.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `slot_id` (path, string, required) The id of the requested slot.  
    Minimum length: 1.
*   `context_type` (path, string, required) The context type (folder, global, category).
*   `select` (query, string) The property selector. If not passed, then the default selector will be used.

#### Responses

*   **404** `SlotNotFoundException` - Indicates the slot does not exist matching the given id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `slot`.
    

## Schemas

### slots

Document representing an unfiltered list of slots.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of slot_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### slot\_configuration

Document representing a slot configuration.

*   `assignment_information` (_slot\_configuration\_assignment\_information_) Information about the assignments and assignment schedules of this slot configuration
*   `callout_msg` (_object (localized)_) The call out message.
    
    Additional properties: `markup_text`.
    
*   `configuration_id` (_string_) The id of this configuration.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_) The context of the slot. Ignored in input documents.  
    Allowed values: `global`, `category`, `folder`.
*   `context_id` (_string_) When the context is _category_, this is a _category\_id_; when the context is _folder_, this is a _folder\_id_; and when the context is _global_, this is obsolete. This is ignored in input documents.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The customer groups ids.
*   `default` (_boolean_) A flag indicating whether the configuration is the default one for the slot.
*   `description` (_string_) The configuration description.  
    Maximum length: 4000.
*   `enabled` (_boolean_) A flag indicating whether the slot is enabled.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) The link.
*   `rank` (_integer (int32)_) The rank of the slot configuration on its slot. This rank has nothing to do with the rank on any campaign-assignment, because these are completely different objects. These must be updated separately.  
    Allowed values: `10`, `20`, `30`, `40`, `50`, `60`, `70`, `80`, `90`, `100`. Minimum: 1.
*   `schedule` (_schedule_) The schedule for the slot.
*   `slot_content` (_slot\_content_, required) The content of the slot.
*   `slot_id` (_string_) The ID of the slot. Ignored in input documents.  
    Minimum length: 1. Maximum length: 256.
*   `template` (_string_) The template.  
    Maximum length: 256.
*   `uuid` (_string_, read-only) The uuid of the slot configuration. This property cannot be written and is ignored in input documents.  
    Minimum length: 1. Maximum length: 28.

_Example_

```
{
  "assigned_to_site": true,
  "callout_msg": {
    "default": "some message"
  },
  "configuration_id": "2015-06-24_16:33:18",
  "context": "global",
  "customer_groups": [
    "Administrators",
    "Registered"
  ],
  "default": true,
  "description": "slot configuration description",
  "enabled": true,
  "rank": 2,
  "schedule": {
    "end_date": "2022-03-28T23:21:00.000Z",
    "recurrence": {
      "day_of_week": [
        "monday",
        "sunday"
      ],
      "time_of_day": {
        "time_from": "00:00:00",
        "time_to": "23:59:00"
      }
    },
    "start_date": "2013-03-28T23:21:00.000Z"
  },
  "slot_content": {
    "body": {
      "default": "<html>HTML content</html>"
    },
    "type": "html"
  },
  "slot_id": "header-banner",
  "uuid": "fsdoi43ofijwdf"
}
```

### slot

Document representing a slot

*   `context_type` (_string_) A slot context  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `description` (_string_) The user supplied description of the slot  
    Maximum length: 4000.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) A link to the slot
*   `preview_url` (_string_) A preview URL the slot
*   `slot_configurations` (_array of slot\_configuration_) A list of slotconfigurations this slot has
*   `slot_id` (_string_, required) The id for the slot  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "context_type": "global",
  "description": "description for slot",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slots/my-slot/global",
  "slot_configurations": {
    "assignment_information": {
      "active": false,
      "enabled": false,
      "schedule_type": "none"
    },
    "configuration_id": "my-config",
    "context": "global",
    "default": false,
    "enabled": true,
    "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slots/my-slot/slot_configurations/Account%20Banner",
    "slot_content": {
      "type": "html"
    },
    "slot_id": "my-slot",
    "template": "slots/html/htmlslotcontainer.isml",
    "uuid": "cw6YLaOace0MUqwcsju07iKn3j"
  },
  "slot_id": "my-slot"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### slot\_configuration\_assignment\_information

*   `abtest_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test the segment belongs to. Otherwise, empty.
*   `abtest_segment_id` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the id of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_) true if the individual assignment or the multiple assignments are currently active (applicable only for non default schedule assignments i.e. either campaign or A/B test schedule).
*   `active_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of currently active A/B tests this is assigned to.
*   `active_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of currently active campaigns this is assigned to.
*   `campaign_id` (_string_) If there is only one assignment, and that assignment is a campaign, the id of the campaign. Otherwise, empty.
*   `enabled` (_boolean_)
*   `end_date` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `schedule` (_schedule_) The schedule of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null.
*   `schedule_type` (_string_) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (schedule\_type : "campaign" or schedule\_type : "abtest"). If there are no assignments, it will be schedule\_type : "none", otherwise, schedule\_type : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `start_date` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If schedule\_type is schedule\_type : "multiple" or schedule\_type : "none", then then result will be null. Also, a null date will also return null.
*   `upcoming_abtest_assignments` (_array of slot\_configuration\_abtest\_group\_assignment_) A list of upcoming A/B tests this is assigned to.
*   `upcoming_campaign_assignments` (_array of slot\_configuration\_campaign\_assignment_) A list of upcoming campaigns this is assigned to.

_Example_

```
{
  "active": false,
  "enabled": false,
  "schedule_type": "none"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### schedule

Document representing a time schedule for slots.

*   `end_date` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.
*   `recurrence` (_recurrence_) The recurrence of the schedule by day of week and time of day. Not all schedules will support a recurrence.
*   `start_date` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.

_Example_

```
{
  "end_date": "2050-01-01T00:00:00.000Z",
  "start_date": "2000-01-01T00:00:00.000Z"
}
```

### slot\_content

Document representing the content type for a slot.

*   `body` (_object (localized)_) The HTML body (valid only for type 'html').
    
    Additional properties: `markup_text`.
    
*   `category_ids` (_array of string_) The category ids (valid only for type 'categories').
*   `content_asset_ids` (_array of string_) The content asset ids (valid only for type 'content\_assets').
*   `product_ids` (_array of string_) The product ids (valid only for type 'products').
*   `type` (_string_, required) The type of content in the slot.  
    Allowed values: `products`, `categories`, `content_assets`, `html`, `recommended_products`.

_Example_

```
{
  "type": "html"
}
```

### slot\_configuration\_abtest\_group\_assignment

Document representing a SlotConfiguration AB test group assignment

*   `abtest_description` (_string_) The description for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `abtest_id` (_string_) The id for the ABTest assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `enabled` (_boolean_) True if the ABTest is enabled
*   `schedule` (_schedule_) The schedule information for the ABTest. Recurrence information is not supported.
*   `segment_description` (_string_) The description for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.
*   `segment_id` (_string_) The id for the ABTest segment assigned to the slot configuration in the SlotConfiguration AB test group assignment.

### slot\_configuration\_campaign\_assignment

Document representing a slot\_configuration\_campaign\_assignment

*   `campaign` (_campaign_) The campaign.
*   `campaign_id` (_string_) The id of the campaign that has the slot configuration assigned to it.  
    Minimum length: 1. Maximum length: 256.
*   `context` (_string_, required) The slot context.  
    Allowed values: `global`, `category`, `folder`.
*   `creation_date` (_string (date-time)_)
*   `customer_groups` (_array of string_) The list of customer groups.
*   `description` (_string_) The description of the slot configuration.  
    Maximum length: 4000.
*   `enabled` (_boolean_) True if the assignment resource is enabled
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL to the slot configuration-campaign assignment.
*   `rank` (_integer (int32)_) The rank of the slot confiuration-campaign assignment. This is different than the rank of the slot configuration.  
    Minimum: 1.
*   `schedule` (_schedule_) The schedule of the assignment resource
*   `slot_configuration` (_slot\_configuration_) The slotConfiguration
*   `slot_configuration_id` (_string_, required) The ID of the slot configuration.  
    Minimum length: 1. Maximum length: 256.
*   `slot_configuration_uuid` (_string_) The UUID of the slot configuration.  
    Maximum length: 28.
*   `slot_context_id` (_string_) The ID of the slot's context, for example, the category ID for a slot with category context.  
    Maximum length: 256.
*   `slot_id` (_string_, required) The ID of the slot.  
    Minimum length: 1. Maximum length: 256.

_Example_

```
{
  "campaign_id": "campaign-registered",
  "context": "global",
  "description": "Free Microsoft Zune With Purchase Of $500 Or More In Electronics",
  "enabled": true,
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/slot_configuration_campaign_assignments/campaign-registered",
  "schedule": {},
  "slot_configuration": {
    "assignment_information": {
      "active": true,
      "active_campaign_assignments": {
        "campaign_id": "campaign-registered",
        "context": "global",
        "enabled": true,
        "rank": 40
      }
    }
  },
  "slot_configuration_id": "Promo Zune",
  "slot_configuration_uuid": "bdL6MiWcbpakEaaadkHwIhZj1N",
  "slot_id": "404-promo"
}
```

### recurrence

Document representing a schedule recurrence.

*   `day_of_week` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
*   `time_of_day` (_time\_of\_day_) The time of the day for recurrence.

_Example_

```
{
  "day_of_week": [
    "thursday",
    "sunday",
    "saturday"
  ],
  "time_of_day": {
    "time_from": "01:14:00",
    "time_to": "20:00:00"
  }
}
```

### campaign

Document representing a campaign.

*   `campaign_id` (_string_) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_groups` (_array of string_) The array of assigned customer groups, not sorted
*   `description` (_string (text)_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.
*   `end_date` (_string (date-time)_) The date that the Scenario ends
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) link for convenience
*   `source_code_groups` (_array of string_) The array of assigned source code groups, not sorted
*   `start_date` (_string (date-time)_) The date that the Scenario begins

_Example_

```
{
  "coupons": [
    "testCoupon"
  ],
  "customer_groups": [
    "Registered"
  ],
  "description": "My Campaign",
  "enabled": true,
  "end_date": "2015-07-31T23:09:08.000Z",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/campaigns/my-campaign",
  "source_code_groups": [
    "WapiSourceCodeGroup1"
  ],
  "start_date": "2015-04-01T11:30:15.000Z"
}
```

### time\_of\_day

Document representing a time schedule within a single day.

*   `time_from` (_string (time)_) The time to start from. Time format: HH:mm:ss. Seconds are ignored and set to 0.
*   `time_to` (_string (time)_) The time to end on. Time format: HH:mm:ss. Seconds are ignored and set to 0.

_Example_

```
{
  "time_from": "01:14:00",
  "time_to": "20:00:00"
}
```

<!-- document id=a5d61faf6a646f3c04f0c25d1c1eb2897fe75fa91c59ba74ea5ffa7d9c26ec5c url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-sorting-rule-search.md -->

Data Sorting Rule Search (deprecated)

# Data Sorting Rule Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Product Sorting Rules

`POST /sites/{site_id}/sorting_rule_search`

Operation ID: `Search Product Sorting Rules`. Tags: sites. Security: oauth2\_application.

Searches for product sorting rules.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   description - String
    
*   creation\_date - date of creation
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   description - String
    
*   creation\_date - date of creation
    

This resource does not support expand options.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `rule_context` (query, string) the optional context in which the sorting rule should be looked up, either "site", "global", or "any" (default)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `sorting_rule_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### sorting\_rule\_search\_result

Document representing a source code group search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of sorting\_rule_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### sorting\_rule

Document representing a product sorting rule

*   `creation_date` (_string (date-time)_)
*   `description` (_string_) The description of the product sorting rule.  
    Maximum length: 4000.
*   `id` (_string_) the id of product sorting rule.
*   `last_modified` (_string (date-time)_)
*   `product_sorting_rule_steps` (_array of sorting\_rule\_step_) the steps involved in sorting by this rule.
*   `rule_context` (_string_) The context of the rule, either site or global
*   `site` (_string_)

_Example_

```
{
  "creation_date": "21.2-03-11T20:04:25.000Z",
  "id": "my-sorting-rule",
  "product_sorting_rule_steps": [
    {
      "attribute_id": "ID",
      "direction": "asc",
      "is_system": true,
      "position": 0,
      "text_relevance_included": false,
      "type_id": "product-attribute"
    }
  ],
  "rule-context": "site",
  "site": "SiteGenesis"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### sorting\_rule\_step

Document representing a product sorting rule step

*   `attribute_id` (_string_) the id for sorting attribute.
*   `direction` (_string_) the direction of the sorting attribute  
    Allowed values: `asc`, `desc`.
*   `is_system` (_boolean_) whether or not the attribute is a system attribute.
*   `position` (_integer (int32)_) the position of product sorting rule step.
*   `text_relevance_included` (_boolean_) The text relevance included.
*   `type_id` (_string_) the sorting type for sorting attribute.

_Example_

```
{
  "attribute_id": "ID",
  "direction": "asc",
  "is_system": true,
  "position": 0,
  "text_relevance_included": false,
  "type_id": "product-attribute"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=14b97f73b7639517c2dde1cfcb5f7c0f885166b2961c59beaf2690db45aff4a5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-source-code-group-search.md -->

Data Source Code Group Search (deprecated)

# Data Source Code Group Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search SourceCodeGroups

`POST /sites/{site_id}/source_code_group_search`

Operation ID: `Search SourceCodeGroups`. Tags: sites. Security: oauth2\_application.

Searches for source code groups.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   description - String
    
*   source\_code\* - String
    
*   start\_time - DateTime
    
*   end\_time - DateTime
    
*   creation\_date - DateTime
    
*   enabled - Boolean
    
*   active\* - Boolean
    

*   *   These fields can only be used in Queries as conjunctions (using AND). If the field is used in a disjunction (OR) an exception will be thrown.

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   description - String
    
*   enabled - Boolean
    
*   creation\_date - DateTime
    

Expands that can be applied for the search request

*   specifications - String
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `source_code_group_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### source\_code\_group\_search\_result

Document representing a source code group search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of source\_code\_group_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### source\_code\_group

Document representing a source code group

*   `active` (_boolean_) The active flag, a computed value based on start and end time
*   `active_redirect` (_source\_code\_redirect\_info_) The active redirect information
*   `cookie_duration` (_integer (int32)_) The cookie duration in days  
    Minimum: 0. Maximum: 999.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description
*   `enabled` (_boolean_) The enabled flag for storefront to consider the source code group, default to false.
*   `end_time` (_string (date-time)_) The end time
*   `id` (_string_) The id of source code group  
    Minimum length: 1. Maximum length: 28.
*   `inactive_redirect` (_source\_code\_redirect\_info_) The inactive redirect information
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance, read only
*   `specifications` (_array of source\_code\_specification_) Source Code specifications
*   `start_time` (_string (date-time)_) The start time

_Example_

```
{
  "description": "My source code group 1",
  "id": "my_source_code_group1",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/source_code_groups/my_source_code_group1",
  "specifications": [
    {
      "expression": "wsc4"
    },
    {
      "expression": "wsc4?"
    }
  ],
  "start_time": "2014-11-15T00:00:00.000Z"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### source\_code\_redirect\_info

Document representing a source code redirect info

*   `location` (_string_) The location of redirect, based on the type, this can be a product location, category location, home page, content page, or just a URL
*   `location_type` (_string_) The type of redirect location, e.g. product (for a product page), category (a category page), home (for home page), page (for content), url (for a URL location)  
    Allowed values: `default`, `home`, `product`, `category`, `page`, `url`.

_Example_

```
{
  "location_type": "default"
}
```

### source\_code\_specification

Document representing a source code specification

*   `expression` (_string_)
    
    Expression is a value for the "Source Code Specification" may be a literal source code, or it may contain wildcards.
    
    A literal code is simply the literal code. Valid characters are letters and numbers (no spaces).
    
    A wildcard allows a single source code specification to match multiple source codes. The following wildcards are supported:
    
    *   ? - Matches any single alpha-numeric character. For example: the source code specification 'ABC?' would match 'ABCD' or 'ABC3', but not 'ABCDE'.
        
    *   *   *   Matches any sequence of alpha-numeric characters. For example: the source code specification 'ABC\*' would match 'ABCD', 'ABCDE', or 'ABC123'.
    *   \[n1..n2\] - Matches any number from n1 through and including n2. For example: the source code specification 'ABC\[3..22\]' would match 'ABC3', 'ABC4' or 'ABC22', but not 'ABC33' or 'ABCD'.
        

_Example_

```
{
  "expression": "wsc4?"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=ca0edc1b6e40212e2b6cddbc3558144d9dbdcffb279a1053a468342ce1d6b3f9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-soure-code-groups.md -->

Data Source Code Groups (deprecated)

# Data Source Code Groups (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Source Code Groups

`GET /sites/{site_id}/source_code_groups`

Operation ID: `Get Source Code Groups`. Tags: sites. Security: oauth2\_application.

Action to get all the source code groups with no filtering.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `expand` (query, array of string)

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `source_code_groups`.
    

### GET Get Source Code Group

`GET /sites/{site_id}/source_code_groups/{id}`

Operation ID: `Get Source Code Group`. Tags: sites. Security: oauth2\_application.

Action to retrieve source code group information.

This endpoint may return the following faults:

*   404 - SourceCodeGroupNotFoundException - Thrown in case the source code group does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested source code group.  
    Minimum length: 1. Maximum length: 28.
*   `expand` (query, array of string) the query parameter takes an expansion list to include extra information, such as specifications. usage: expand=specifications.

#### Responses

*   **404** `SourceCodeGroupNotFoundException` - Thrown in case the source code group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `source_code_group`.
    

### PUT Create SourceCodeGroup

`PUT /sites/{site_id}/source_code_groups/{id}`

Operation ID: `Create SourceCodeGroup`. Tags: sites. Security: oauth2\_application.

Creates a source code group using the information provided.

This endpoint may return the following faults:

*   400 - IdConflictException - Thrown when the id given in request URL is different from the id provided in the source code group document
*   400 - SourceCodeGroupInvalidException - if the source code group passed in is not valid (the argument indicates the field that was invalid).

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the source code group to create.  
    Minimum length: 1. Maximum length: 28.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `source_code_group`.

#### Responses

*   **400** `IdConflictException` - Thrown when the id given in request URL is different from the id provided in the source code group document or `SourceCodeGroupInvalidException` - if the source code group passed in is not valid (the argument indicates the field that was invalid).
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `source_code_group`.
    

### DELETE Delete SourceCodeGroup

`DELETE /sites/{site_id}/source_code_groups/{id}`

Operation ID: `Delete SourceCodeGroup`. Tags: sites. Security: oauth2\_application.

Deletes the source code group by ID

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) One source code group id to remove  
    Minimum length: 1. Maximum length: 28.

#### Responses

*   **204**

### PATCH Update Source Code Group

`PATCH /sites/{site_id}/source_code_groups/{id}`

Operation ID: `Update Source Code Group`. Tags: sites. Security: oauth2\_application.

Updates the source code group with the specified information.

This endpoint may return the following faults:

*   404 - SourceCodeGroupNotFoundException - Thrown in case the source code group does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The id of the site.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested source code group.  
    Minimum length: 1. Maximum length: 28.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `source_code_group`.

#### Responses

*   **404** `SourceCodeGroupNotFoundException` - Thrown in case the source code group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `source_code_group`.
    

## Schemas

### source\_code\_groups

Document representing an unfiltered list of source code groups.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of source\_code\_group_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### source\_code\_group

Document representing a source code group

*   `active` (_boolean_) The active flag, a computed value based on start and end time
*   `active_redirect` (_source\_code\_redirect\_info_) The active redirect information
*   `cookie_duration` (_integer (int32)_) The cookie duration in days  
    Minimum: 0. Maximum: 999.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description
*   `enabled` (_boolean_) The enabled flag for storefront to consider the source code group, default to false.
*   `end_time` (_string (date-time)_) The end time
*   `id` (_string_) The id of source code group  
    Minimum length: 1. Maximum length: 28.
*   `inactive_redirect` (_source\_code\_redirect\_info_) The inactive redirect information
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `link` (_string_) URL that is used to get this instance, read only
*   `specifications` (_array of source\_code\_specification_) Source Code specifications
*   `start_time` (_string (date-time)_) The start time

_Example_

```
{
  "description": "My source code group 1",
  "id": "my_source_code_group1",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/source_code_groups/my_source_code_group1",
  "specifications": [
    {
      "expression": "wsc4"
    },
    {
      "expression": "wsc4?"
    }
  ],
  "start_time": "2014-11-15T00:00:00.000Z"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### source\_code\_redirect\_info

Document representing a source code redirect info

*   `location` (_string_) The location of redirect, based on the type, this can be a product location, category location, home page, content page, or just a URL
*   `location_type` (_string_) The type of redirect location, e.g. product (for a product page), category (a category page), home (for home page), page (for content), url (for a URL location)  
    Allowed values: `default`, `home`, `product`, `category`, `page`, `url`.

_Example_

```
{
  "location_type": "default"
}
```

### source\_code\_specification

Document representing a source code specification

*   `expression` (_string_)
    
    Expression is a value for the "Source Code Specification" may be a literal source code, or it may contain wildcards.
    
    A literal code is simply the literal code. Valid characters are letters and numbers (no spaces).
    
    A wildcard allows a single source code specification to match multiple source codes. The following wildcards are supported:
    
    *   ? - Matches any single alpha-numeric character. For example: the source code specification 'ABC?' would match 'ABCD' or 'ABC3', but not 'ABCDE'.
        
    *   *   *   Matches any sequence of alpha-numeric characters. For example: the source code specification 'ABC\*' would match 'ABCD', 'ABCDE', or 'ABC123'.
    *   \[n1..n2\] - Matches any number from n1 through and including n2. For example: the source code specification 'ABC\[3..22\]' would match 'ABC3', 'ABC4' or 'ABC22', but not 'ABC33' or 'ABCD'.
        

_Example_

```
{
  "expression": "wsc4?"
}
```

<!-- document id=e202c3ec3b157c2618564eff47c43dca68395ac1ce025e9e3da3f26efc8f5105 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-store-search.md -->

Data Store Search (deprecated)

# Data Store Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search Stores

`POST /sites/{site_id}/store_search`

Operation ID: `Search Stores`. Tags: sites. Security: oauth2\_application.

Searches for stores.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   address1 - String
    
*   address2 - String
    
*   city - String
    
*   country\_code - String
    
*   email - String
    
*   fax - String
    
*   id - String
    
*   inventory\_id - String
    
*   latitude - double
    
*   longitude - double
    
*   name - String
    
*   phone - String
    
*   postal\_code - String
    
*   state\_code - String
    
*   store\_hours - String
    
*   store\_events - String
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `site_id` (path, string, required) The site context.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `store_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### store\_search\_result

Document representing a store search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of store_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### store

Document representing a store

*   `address1` (_string_) Returns the first address.  
    Maximum length: 256.
*   `address2` (_string_) Returns the second address value.  
    Maximum length: 256.
*   `city` (_string_) Returns the city.  
    Maximum length: 256.
*   `country_code` (_string_) The two-character country code per ISO 3166-1 alpha-2.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States. Maximum length: 2.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `email` (_string_) Email address to contact the store  
    Maximum length: 256.
*   `fax` (_string_) Returns the fax number .  
    Maximum length: 256.
*   `id` (_string_) The id for the store  
    Maximum length: 256.
*   `image` (_media\_file_) The image associated with the store
*   `inventory_id` (_string_) The inventory list associated with the store  
    Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `latitude` (_number (double)_) The latitude of the store  
    Minimum: -90. Maximum: 90.
*   `link` (_string_) a URL that is used to get this instance. The property is computed and cannot be changed.
*   `longitude` (_number (double)_) The longitude of the store  
    Minimum: -180. Maximum: 180.
*   `name` (_string_) The name of the store
*   `phone` (_string_) Returns the phone number.  
    Maximum length: 256.
*   `pos_enabled` (_boolean_) Whether this store uses our Store product for Point-of-Sale
*   `postal_code` (_string_) The postal code for the store  
    Maximum length: 10.
*   `state_code` (_string_) Returns the customer's state.  
    Maximum length: 256.
*   `store_events` (_object (localized)_) The store events (localized)
    
    Additional properties: `markup_text`.
    
*   `store_hours` (_object (localized)_) The store opening hours (localized)
    
    Additional properties: `markup_text`.
    
*   `store_locator_enabled` (_boolean_) Whether this store should appear in store locator searches

_Example_

```
{
  "address1": "5 Wall St",
  "address2": "2nd Floor",
  "city": "Burlington",
  "country_code": "us",
  "demandware_pos_enabled": false,
  "email": "support@salesforce.com",
  "fax": "877-540-3035",
  "id": "my-store",
  "image": "http://example.com/on/demandware.static/-/Sites/default/v1437070303037/store99.jpg",
  "inventory_id": "inventoryListA",
  "latitude": "42.487796",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/stores/my-store",
  "longitude": "-71.18822",
  "phone": "877-540-3032",
  "postal_code": "01827",
  "state_code": "MA",
  "store_events": {
    "default": "50% off Sale"
  },
  "store_hours": {
    "default": "09:00 am - 06:00 pm"
  },
  "store_locator_enabled": true
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### media\_file

*   `abs_url` (_string_) The absolute URL with request protocol (read only)
*   `alt` (_object (localized)_) The alternative image text
    
    Additional properties: `string`.
    
*   `dis_base_url` (_string_) The DIS base URL only for product images
*   `path` (_string_) The raw media file path (only this needs to be provided in update request)
*   `title` (_object (localized)_) The image title
    
    Additional properties: `string`.
    

_Example_

```
{
  "path": "option.jpg"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=4044a7aeec06d8769b3a59201b131d2c63ca16c1986f4cb55159b5f7bdc1ec9e url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-stores.md -->

Data Stores (deprecated)

# Data Stores (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Stores

`GET /sites/{site_id}/stores`

Operation ID: `Get Stores`. Tags: sites. Security: oauth2\_application.

Action to get all the stores with no filtering.

#### Parameters

*   `site_id` (path, string, required)  
    Minimum length: 1.
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `stores`.
    

### GET Get Store

`GET /sites/{site_id}/stores/{id}`

Operation ID: `Get Store`. Tags: sites. Security: oauth2\_application.

Action to get store information.

This endpoint may return the following faults:

*   404 - StoreNotFoundException - Thrown in case the store does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested store.  
    Minimum length: 1. Maximum length: 256.
*   `select` (query, string) the selector for the get. If not passed, then the defaultSelector will be used instead.

#### Responses

*   **404** `StoreNotFoundException` - Thrown in case the store does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `store`.
    

### PUT Create Store

`PUT /sites/{site_id}/stores/{id}`

Operation ID: `Create Store`. Tags: sites. Security: oauth2\_application.

Creates a store using the information provided.

This endpoint may return the following faults:

*   400 - IdConflictException - if the Id in request is not the same as the ID in document.

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the store to create.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `store`.

#### Responses

*   **400** `IdConflictException` - if the Id in request is not the same as the ID in document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `store`.
    

### DELETE Delete Stores

`DELETE /sites/{site_id}/stores/{id}`

Operation ID: `Delete Stores`. Tags: sites. Security: oauth2\_application.

Deletes the store by ID

This endpoint may return the following faults:

*   404 - StoreNotFoundException - Thrown in case the store does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) One store id to remove  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **204**
*   **404** `StoreNotFoundException` - Thrown in case the store does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Store

`PATCH /sites/{site_id}/stores/{id}`

Operation ID: `Update Store`. Tags: sites. Security: oauth2\_application.

Updates the store with the specified information.

This endpoint may return the following faults:

*   404 - StoreNotFoundException - Thrown in case the store does not exist matching the given id

#### Parameters

*   `site_id` (path, string, required) The site context.  
    Minimum length: 1.
*   `id` (path, string, required) The id of the requested store.  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `store`.

#### Responses

*   **404** `StoreNotFoundException` - Thrown in case the store does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `store`.
    

## Schemas

### stores

Document representing an unfiltered list of stores.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of store_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "address1": "5 Wall St",
      "address2": "2nd Floor",
      "city": "Burlington",
      "country_code": "us",
      "demandware_pos_enabled": false,
      "email": "support@salesforce.com",
      "fax": "877-540-3035",
      "id": "my-store",
      "image": "http://example.com/on/demandware.static/-/Sites/default/v1437070303037/store99.jpg",
      "inventory_id": "inventoryListA",
      "latitude": "42.487796",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/stores/my-store",
      "longitude": "-71.18822",
      "phone": "877-540-3032",
      "postal_code": "01827",
      "state_code": "MA",
      "store_events": {
        "default": "50% off Sale"
      },
      "store_hours": {
        "default": "09:00 am - 06:00 pm"
      },
      "store_locator_enabled": true
    },
    {
      "address1": "100 Mall Rd",
      "city": "Burlington",
      "country_code": "us",
      "demandware_pos_enabled": false,
      "email": "mall@burlington.com",
      "fax": "555-555-1213",
      "id": "my-store2",
      "latitude": "42.000000",
      "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/stores/my-store2",
      "longitude": "-71.000000",
      "phone": "555-555-1212",
      "postal_code": "01827",
      "state_code": "MA",
      "store_locator_enabled": true
    }
  ],
  "select": "**",
  "start": 0,
  "total": 2
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### store

Document representing a store

*   `address1` (_string_) Returns the first address.  
    Maximum length: 256.
*   `address2` (_string_) Returns the second address value.  
    Maximum length: 256.
*   `city` (_string_) Returns the city.  
    Maximum length: 256.
*   `country_code` (_string_) The two-character country code per ISO 3166-1 alpha-2.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States. Maximum length: 2.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `email` (_string_) Email address to contact the store  
    Maximum length: 256.
*   `fax` (_string_) Returns the fax number .  
    Maximum length: 256.
*   `id` (_string_) The id for the store  
    Maximum length: 256.
*   `image` (_media\_file_) The image associated with the store
*   `inventory_id` (_string_) The inventory list associated with the store  
    Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `latitude` (_number (double)_) The latitude of the store  
    Minimum: -90. Maximum: 90.
*   `link` (_string_) a URL that is used to get this instance. The property is computed and cannot be changed.
*   `longitude` (_number (double)_) The longitude of the store  
    Minimum: -180. Maximum: 180.
*   `name` (_string_) The name of the store
*   `phone` (_string_) Returns the phone number.  
    Maximum length: 256.
*   `pos_enabled` (_boolean_) Whether this store uses our Store product for Point-of-Sale
*   `postal_code` (_string_) The postal code for the store  
    Maximum length: 10.
*   `state_code` (_string_) Returns the customer's state.  
    Maximum length: 256.
*   `store_events` (_object (localized)_) The store events (localized)
    
    Additional properties: `markup_text`.
    
*   `store_hours` (_object (localized)_) The store opening hours (localized)
    
    Additional properties: `markup_text`.
    
*   `store_locator_enabled` (_boolean_) Whether this store should appear in store locator searches

_Example_

```
{
  "address1": "5 Wall St",
  "address2": "2nd Floor",
  "city": "Burlington",
  "country_code": "us",
  "demandware_pos_enabled": false,
  "email": "support@salesforce.com",
  "fax": "877-540-3035",
  "id": "my-store",
  "image": "http://example.com/on/demandware.static/-/Sites/default/v1437070303037/store99.jpg",
  "inventory_id": "inventoryListA",
  "latitude": "42.487796",
  "link": "https://example.com/s/-/dw/data/{version}/sites/SiteGenesis/stores/my-store",
  "longitude": "-71.18822",
  "phone": "877-540-3032",
  "postal_code": "01827",
  "state_code": "MA",
  "store_events": {
    "default": "50% off Sale"
  },
  "store_hours": {
    "default": "09:00 am - 06:00 pm"
  },
  "store_locator_enabled": true
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### media\_file

*   `abs_url` (_string_) The absolute URL with request protocol (read only)
*   `alt` (_object (localized)_) The alternative image text
    
    Additional properties: `string`.
    
*   `dis_base_url` (_string_) The DIS base URL only for product images
*   `path` (_string_) The raw media file path (only this needs to be provided in update request)
*   `title` (_object (localized)_) The image title
    
    Additional properties: `string`.
    

_Example_

```
{
  "path": "option.jpg"
}
```

### markup\_text

*   `markup` (_string_) The rendered HTML (read only)
*   `source` (_string_) The raw markup text (only this needs to be provided in update request)

<!-- document id=e47e28dbe653a5a0e86d907a9286c74f27403aabfdcef77d273bdea106cd6942 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-system-object-definition-search.md -->

Data System Object Definition Search (deprecated)

# Data System Object Definition Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search SystemObjects

`POST /system_object_definition_search`

Operation ID: `Search SystemObjects`. Tags: system\_object\_definition\_search. Security: oauth2\_application.

Searches for system objects.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   object\_type - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   read\_only - Boolean
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   object\_type - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   read\_only - Boolean
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_type_definition_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### object\_type\_definition\_search\_result

Document representing a systemobject search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of object\_type\_definition_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### object\_type\_definition

Document representing a object type definition

*   `attribute_definition_count` (_integer (int32)_) Returns the number of attribute definitions contained by the type. This is a computed attribute and cannot be changed.
*   `attribute_group_count` (_integer (int32)_) Returns the number of attribute groups contained by the type. This is a computed attribute and cannot be changed.
*   `content_object` (_boolean_) True if the object type definition is marked as a content object
*   `creation_date` (_string (date-time)_)
*   `description` (_object (localized)_) The user entered description for the type (localizable)
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The user entered display name (localizable)
    
    Additional properties: `string`.
    
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) URL that is used to get this instance. This is a computed attribute and cannot be changed.
*   `object_type` (_string_) The object type identifier
*   `queryable` (_boolean_) True if the system object type is queryable, false otherwise. Default is true.
*   `read_only` (_boolean_) True if the system object is read-only, false otherwise. This is a computed attribute and cannot be changed.

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=0f89b6cff19876bbc8366e723d794ff191ba058a09cce2b16734c2f34dce7833 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-system-object-definitions.md -->

Data System Object Definitions (deprecated)

# Data System Object Definitions (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get System Objects

`GET /system_object_definitions`

Operation ID: `Get System Objects`. Tags: system\_object\_definitions. Security: oauth2\_application.

Action to get all the system objects with no filtering.

#### Parameters

*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_type_definitions`.
    

### GET Get System Object

`GET /system_object_definitions/{object_type}`

Operation ID: `Get System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Action to get system object information.

This endpoint may return the following faults:

*   404 - SystemObjectNotFoundException - Thrown in case the system object does not exist matching the given objectType

#### Parameters

*   `object_type` (path, string, required) The id of the object type for the requested system object.  
    Minimum length: 1.

#### Responses

*   **404** `SystemObjectNotFoundException` - Thrown in case the system object does not exist matching the given objectType
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_type_definition`.
    

### POST Search Attribute Definitions for System Object

`POST /system_object_definitions/{object_type}/attribute_definition_search`

Operation ID: `Search Attribute Definitions for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Searches the attribute definitions of the specified system object type.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets. These are the list of searchable attributes with their corresponding buckets:

Main:

*   id - String
    
*   display\_name\* - Localized String
    
*   description\* - Localized String
    
*   key - boolean
    
*   mandatory - boolean
    
*   searchable - boolean
    
*   system - boolean
    
*   visible - boolean
    

Definition version:

*   localizable - boolean
    
*   site\_specific - boolean
    
*   value\_type - one of {string, int, double, text, html, date, image, boolean, money, quantity, datetime, email, password, set\_of\_string, set\_of\_int, set\_of\_double, enum\_of\_string, enum\_of\_int}
    

Group:

*   group - String
    

Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining localizable and description above, only a conjunction is allowed (AND), whereas display\_name and description can be joined using a disjunction because they are in the same bucket. If an attribute is used in a disjunction (OR) that violates this rule, an exception will be thrown.

*   These attributes are not searchable or sortable for built in system attributes. They work normally for non system attributes.

Note that only searchable attributes can be used in sorting.

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Indicates the query is ill-formed.
*   404 - ObjectTypeNotFoundException - in case the object type does not match an existing system type

#### Parameters

*   `object_type` (path, string, required) The object type id that contains these definitions

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Indicates the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - in case the object type does not match an existing system type
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition_search_result`.
    

### GET Get Attribute Definitions for System Object

`GET /system_object_definitions/{object_type}/attribute_definitions`

Operation ID: `Get Attribute Definitions for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Action to get all the attribute definitions with no filtering.

This endpoint may return the following faults:

*   404 - ObjectTypeNotFoundException - in case the object type does not match an existing system type

#### Parameters

*   `object_type` (path, string, required)
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **404** `ObjectTypeNotFoundException` - in case the object type does not match an existing system type
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definitions`.
    

### GET Get Attribute Definition for System Object

`GET /system_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Get Attribute Definition for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Action to get attribute definition information.

This endpoint may return the following faults:

*   500 - AttributeDefinitionNotFoundException - Thrown in case the attribute definition does not exist matching the given id
*   404 - ObjectTypeNotFoundException - in case the object type does not match an existing system type

#### Parameters

*   `object_type` (path, string, required) The object type id that contains these definitions
*   `id` (path, string, required) The id of the requested attribute definition.  
    Minimum length: 1.
*   `select` (query, string) The selector for the get. If not passed, then the defaultSelector will be used instead.
*   `expand` (query, array of string) The expansion "value" is available to retrieve value definitions of the attribute definition.

#### Responses

*   **404** `ObjectTypeNotFoundException` - in case the object type does not match an existing system type
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Thrown in case the attribute definition does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.
    

### PUT Create Attribute Definition for System Object

`PUT /system_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Create Attribute Definition for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Creates a attribute definition using the information provided.

This endpoint may return the following faults:

*   400 - AttributeDefinitionCreateException - if the attribute definition could not be created.
*   400 - AttributeDefinitionDuplicateException - if a attribute definition exists already with the given attribute definition id.
*   400 - AttributeDefinitionReadOnlyException - Thrown when trying to create an internal attribute definition
*   400 - IdConflictException - if the Id in request is not the same as the ID in document.
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) The metadata object that contains these definitions
*   `id` (path, string, required) The id of the attribute definition to create.
*   `x-dw-validate-existing` (header, boolean)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.

#### Responses

*   **400** `AttributeDefinitionCreateException` - if the attribute definition could not be created. or `AttributeDefinitionDuplicateException` - if a attribute definition exists already with the given attribute definition id. or `AttributeDefinitionReadOnlyException` - Thrown when trying to create an internal attribute definition or `IdConflictException` - if the Id in request is not the same as the ID in document.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.
    

### DELETE Delete Attribute Definition for System Object

`DELETE /system_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Delete Attribute Definition for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Deletes the attribute definition by ID

This endpoint may return the following faults:

*   400 - AttributeDefinitionReadOnlyException - Thrown when trying to delete an internal attribute definition
*   500 - AttributeDefinitionNotFoundException - Thrown in case the attribute definition cannot be found
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) The metadata object that contains these definitions
*   `id` (path, string, required) Attribute definition id to remove  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `AttributeDefinitionReadOnlyException` - Thrown when trying to delete an internal attribute definition
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Thrown in case the attribute definition cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Attribute Definition for System Object

`PATCH /system_object_definitions/{object_type}/attribute_definitions/{id}`

Operation ID: `Update Attribute Definition for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Updates the attribute definition with the specified information. The request must include the If-Match header, which holds the last known base-point information. The value of this header is an "ETag" representing the attribute definition state. If the request does not contain an If-Match header with the current server customer "ETag", a 409 (IfMatchRequiredException) fault is returned. If the If-Match header does not match the current server attribute definition "ETag", a 412 (InvalidIfMatchException) fault is returned.

This endpoint may return the following faults:

*   400 - AttributeDefinitionPropertyReadOnlyException - Thrown in case a read only system attribute it tried to be changed, which is not allowed.
*   400 - AttributeDefinitionReadOnlyException - Thrown when trying to modify a read-only field of an internal attribute definition
*   500 - AttributeDefinitionNotFoundException - Thrown in case the attribute definition does not exist matching the given id
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) The object type id that contains these definitions
*   `id` (path, string, required) The id of the requested attribute definition.  
    Minimum length: 1.
*   `If-Match` (header, string) must match the last eTag

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.

#### Responses

*   **400** `AttributeDefinitionPropertyReadOnlyException` - Thrown in case a read only system attribute it tried to be changed, which is not allowed. or `AttributeDefinitionReadOnlyException` - Thrown when trying to modify a read-only field of an internal attribute definition
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Thrown in case the attribute definition does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_definition`.
    

### POST Search Attribute Groups for System Object

`POST /system_object_definitions/{object_type}/attribute_group_search`

Operation ID: `Search Attribute Groups for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Searches for attribute groups.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   id - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   position - Double
    
*   internal - Boolean
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
    
*   display\_name - Localized < String >
    
*   description - Localized < String >
    
*   position - Double
    
*   internal - Boolean
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Parameters

*   `object_type` (path, string, required)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group_search_result`.
    

### GET Get Attribute Groups for System Object

`GET /system_object_definitions/{object_type}/attribute_groups`

Operation ID: `Get Attribute Groups for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Action to get all the attribute groups with no filtering.

This endpoint may return the following faults:

*   404 - ObjectTypeNotFoundException - in case the object type does not match an existing system type

#### Parameters

*   `object_type` (path, string, required)
*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.
*   `expand` (query, array of string)

#### Responses

*   **404** `ObjectTypeNotFoundException` - in case the object type does not match an existing system type
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_groups`.
    

### PUT Assign System Object Attribute Definition to Attribute Group

`PUT /system_object_definitions/{object_type}/attribute_groups/{group_id}/attribute_definitions/{def_id}`

Operation ID: `Assign System Object Attribute Definition to Attribute Group`. Tags: system\_object\_definitions. Security: oauth2\_application.

Assign an attribute definition to an attribute group.

This endpoint may return the following faults:

*   500 - AttributeDefinitionNotFoundException - Indicates the specified attribute definition is not found.
*   404 - AttributeGroupNotFoundException - Indicates the specified attribute group is not found.
*   404 - ObjectTypeNotFoundException - Indicates the specified system object is not found.

#### Parameters

*   `object_type` (path, string, required) The ID of the system object that contains the attribute definition and attribute group.
*   `group_id` (path, string, required) The ID of the attribute group.  
    Minimum length: 1.
*   `def_id` (path, string, required) The ID of the attribute definition.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `AttributeGroupNotFoundException` - Indicates the specified attribute group is not found. or `ObjectTypeNotFoundException` - Indicates the specified system object is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Indicates the specified attribute definition is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### DELETE Un-assign System Object Attribute Definition from Attribute Group

`DELETE /system_object_definitions/{object_type}/attribute_groups/{group_id}/attribute_definitions/{def_id}`

Operation ID: `Un-assign System Object Attribute Definition from Attribute Group`. Tags: system\_object\_definitions. Security: oauth2\_application.

Un-assign an attribute definition from an attribute group.

This endpoint may return the following faults:

*   500 - AttributeDefinitionNotFoundException - Indicates the specified attribute definition is not found.
*   404 - AttributeGroupNotFoundException - Indicates the specified attribute group is not found.
*   404 - ObjectTypeNotFoundException - Indicates the specified system object is not found.

#### Parameters

*   `object_type` (path, string, required) The ID of the system object that contains the attribute definition and attribute group.
*   `group_id` (path, string, required) The ID of the attribute group.  
    Minimum length: 1.
*   `def_id` (path, string, required) The ID of the attribute definition.  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `AttributeGroupNotFoundException` - Indicates the specified attribute group is not found. or `ObjectTypeNotFoundException` - Indicates the specified system object is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **500** `AttributeDefinitionNotFoundException` - Indicates the specified attribute definition is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get Attribute Group for System Object

`GET /system_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Get Attribute Group for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Action to get attribute group information.

This endpoint may return the following faults:

*   404 - AttributeGroupNotFoundException - Thrown in case the attribute group does not exist matching the given id
*   404 - ObjectTypeNotFoundException - in case the object type does not match an existing system type

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) The id of the requested attribute group.  
    Minimum length: 1.
*   `select` (query, string)
*   `expand` (query, array of string)

#### Responses

*   **404** `AttributeGroupNotFoundException` - Thrown in case the attribute group does not exist matching the given id or `ObjectTypeNotFoundException` - in case the object type does not match an existing system type
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group`.
    

### PUT Create Attribute Group for System Object

`PUT /system_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Create Attribute Group for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Creates a attribute group using the information provided. If a attribute group with the same unique identifier, it will be deleted and a new one will be created unless the header x-dw-validate-existing=true is passed in with the request.

This endpoint may return the following faults:

*   400 - AttributeGroupDuplicateException - if a attribute group exists already in the site with the given identifier and the header x-dw-validate-existing=true is passed in with the request.
*   400 - AttributeGroupReadOnlyException - Thrown when trying to create an internal attribute group

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) The id of the attribute group to create.  
    Minimum length: 1.
*   `x-dw-validate-existing` (header, boolean) if true, and a attribute group already exists, will throw a AttributeGroupDuplicateException.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_group`.

#### Responses

*   **400** `AttributeGroupDuplicateException` - if a attribute group exists already in the site with the given identifier and the header x-dw-validate-existing=true is passed in with the request. or `AttributeGroupReadOnlyException` - Thrown when trying to create an internal attribute group
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group`.
    

### DELETE Delete Attribute Groups for System Object

`DELETE /system_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Delete Attribute Groups for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Deletes the attribute group by ID

This endpoint may return the following faults:

*   400 - AttributeGroupReadOnlyException - Thrown when trying to delete an internal attribute group
*   404 - AttributeGroupNotFoundException - Thrown in case the attribute group cannot be found
*   404 - ObjectTypeNotFoundException - Thrown in case the object type cannot be found

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) One attribute group id to remove

#### Responses

*   **204**
*   **400** `AttributeGroupReadOnlyException` - Thrown when trying to delete an internal attribute group
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AttributeGroupNotFoundException` - Thrown in case the attribute group cannot be found or `ObjectTypeNotFoundException` - Thrown in case the object type cannot be found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update Attribute Group for System Object

`PATCH /system_object_definitions/{object_type}/attribute_groups/{id}`

Operation ID: `Update Attribute Group for System Object`. Tags: system\_object\_definitions. Security: oauth2\_application.

Updates the attribute group with the specified information. The request must include the If-Match header, which holds the last known base-point information. The value of this header is an "ETag" representing the attribute group state. If the request does not contain an If-Match header with the current server customer "ETag", a 409 (IfMatchRequiredException) fault is returned. If the If-Match header does not match the current server attribute group "ETag", a 412 (InvalidIfMatchException) fault is returned.

This endpoint may return the following faults:

*   400 - AttributeGroupReadOnlyException - Thrown when trying to modify an attribute of a field of an attribute group that is read only
*   404 - AttributeGroupNotFoundException - Thrown in case the attribute group does not exist matching the given id

#### Parameters

*   `object_type` (path, string, required) the object type id that contains this attribute group
*   `id` (path, string, required) The id of the requested attribute group.  
    Minimum length: 1.
*   `If-Match` (header, string) must match the last eTag

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `object_attribute_group`.

#### Responses

*   **400** `AttributeGroupReadOnlyException` - Thrown when trying to modify an attribute of a field of an attribute group that is read only
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AttributeGroupNotFoundException` - Thrown in case the attribute group does not exist matching the given id
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `object_attribute_group`.
    

## Schemas

### object\_type\_definitions

Document representing an unfiltered list of system object types.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object\_type\_definition_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### object\_type\_definition

Document representing a object type definition

*   `attribute_definition_count` (_integer (int32)_) Returns the number of attribute definitions contained by the type. This is a computed attribute and cannot be changed.
*   `attribute_group_count` (_integer (int32)_) Returns the number of attribute groups contained by the type. This is a computed attribute and cannot be changed.
*   `content_object` (_boolean_) True if the object type definition is marked as a content object
*   `creation_date` (_string (date-time)_)
*   `description` (_object (localized)_) The user entered description for the type (localizable)
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The user entered display name (localizable)
    
    Additional properties: `string`.
    
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) URL that is used to get this instance. This is a computed attribute and cannot be changed.
*   `object_type` (_string_) The object type identifier
*   `queryable` (_boolean_) True if the system object type is queryable, false otherwise. Default is true.
*   `read_only` (_boolean_) True if the system object is read-only, false otherwise. This is a computed attribute and cannot be changed.

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### object\_attribute\_definition\_search\_result

Document representing an attributedefinition search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of object\_attribute\_definition_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "description": {
        "default": "Description",
        "es": "mia description"
      },
      "display_name": {
        "default": "default name",
        "es": "nombre"
      },
      "id": "my-attributedefinition1",
      "key": false,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_definitions/my-attributedefinition1",
      "localizable": true,
      "mandatory": false,
      "queryable": true,
      "searchable": false,
      "site_specific": false,
      "system": false,
      "value_type": "string",
      "visible": false
    },
    {
      "display_name": {
        "default": "second name",
        "fr": "non de plume"
      },
      "id": "my-attributedefinition2",
      "key": true,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_definitions/my-attributedefinition2",
      "localizable": true,
      "mandatory": true,
      "queryable": true,
      "searchable": true,
      "site_specific": false,
      "system": false,
      "value_type": "string",
      "visible": true
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### object\_attribute\_definitions

Document representing an unfiltered list of object attribute definitions.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object\_attribute\_definition_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### object\_attribute\_definition

Document representing a attribute definition

*   `creation_date` (_string (date-time)_)
*   `default_value` (_object\_attribute\_value\_definition_) The default value of this attribute. It can be updated, but not created.
*   `description` (_object (localized)_) The localized description of the attribute.
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The localized name presented to the user in forms.
    
    Additional properties: `string`.
    
*   `effective_id` (_string_) The effective ID, which is c\_id if the attribute is custom, and just the id otherwise. It is read only.
*   `externally_defined` (_boolean_) Flag indicating if this attribute is externally defined.
*   `externally_managed` (_boolean_) Flag indicating if this attribute is externally managed.
*   `field_height` (_integer (int32)_) The height of the field for this attribute in the editor.
*   `field_length` (_integer (int32)_) The length of the field for this attribute in the editor.
*   `id` (_string_) The user supplied ID of the attribute.
*   `key` (_boolean_) Flag indicating if this is a key attribute.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) The URL that is used to get this instance. Value is computed and read-only.
*   `localizable` (_boolean_) Flag indicating if this attribute can be localized.
*   `mandatory` (_boolean_) Flag indicating if a value is mandatory for the attribute.
*   `max_value` (_number (double)_) The maximum possible value for this attribute.
*   `min_length` (_integer (int32)_) The minimum length of the field for this attribute.
*   `min_value` (_number (double)_) The minimum possible value for this attribute.
*   `multi_value_type` (_boolean_)
    
    True if the attribute can have multiple values.
    
    Attributes of the following types are multi-value capable:
    
    *   set\_of\_int
        
    *   set\_of\_number
        
    *   set\_of\_string
        
    
    Additionally, attributes of the following types can be multi-value enabled:
    
    *   enum\_of\_int
        
    *   enum\_of\_string
        
*   `order_required` (_boolean_) Flag indicating if this attribute is required for order of the attribute model's product. The set of these can be used in order line items.
*   `queryable` (_boolean_) Returns true if the attribute definition is explicitly marked queryable. If no explicit queryable is found and the attribute value type belongs to a queryable type, true is returned too. In all other cases false is returned. Value is computed and read-only.
*   `read_only` (_boolean_) Flag indicating if this attribute is read-only. It is read only.
*   `regular_expression` (_string_) A regular expression that defines the legal values for this attribute.
*   `requires_encoding` (_boolean_) Flag indicating if this attribute can be encoded using the encoding="off" flag in ISML templates. It is read only.
*   `scale` (_integer (int32)_) The minimum number of fraction digits for a value of this attribute.
*   `searchable` (_boolean_) Flag indicating if this attribute is searchable.
*   `set_value_type` (_boolean_) Flag indicating if this attribute is of type 'Set of'. It is read only.
*   `site_specific` (_boolean_) Flag indicating if this attribute is site-specific.
*   `system` (_boolean_) Flag indicating if this attribute is a system attribute.
*   `unit` (_object (localized)_) The unit of measure for this attribute.
    
    Additional properties: `string`.
    
*   `value_definitions` (_array of object\_attribute\_value\_definition_) A set of values that are possible for this attribute. It is read only.
*   `value_type` (_string_) The type of this attribute.  
    Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `image`, `boolean`, `money`, `quantity`, `datetime`, `email`, `password`, `set_of_string`, `set_of_int`, `set_of_double`, `enum_of_string`, `enum_of_int`, `unknown`.
*   `visible` (_boolean_) Flag indicating if this attribute is visible.

_Example_

```
{
  "description": {
    "default": "Description",
    "es": "mia description"
  },
  "display_name": {
    "default": "default name",
    "es": "nombre"
  },
  "id": "MyAttributeDefinition",
  "key": false,
  "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_definitions/MyAttributeDefinition",
  "localizable": true,
  "mandatory": false,
  "queryable": true,
  "searchable": false,
  "site_specific": false,
  "system": false,
  "value_type": "string",
  "visible": false
}
```

### object\_attribute\_group\_search\_result

Document representing a attributegroup search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of object\_attribute\_group_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 2,
  "hits": [
    {
      "definitions_count": 5,
      "description": {
        "de": "A German my-description",
        "default": "my-description",
        "en": "An English my-description"
      },
      "display_name": {
        "de": "A German my-display_name",
        "default": "my-display_name",
        "en": "An English my-display_name"
      },
      "id": "my-attributegroup1",
      "internal": false,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_groups/my-attributegroup1",
      "position": 1
    },
    {
      "definitions_count": 12,
      "display_name": {
        "default": "my-display_name"
      },
      "id": "my-attributegroup2",
      "internal": false,
      "link": "https://example.com/s/-/dw/data/{version}/custom_object_definitions/Global_String/attribute_groups/my-attributegroup2",
      "position": 2
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "id",
        "description"
      ],
      "search_phrase": "my"
    }
  },
  "select": "**",
  "start": 0,
  "total": 2
}
```

### object\_attribute\_groups

Document representing an unfiltered list of object group definitions.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object\_attribute\_group_)
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

### object\_attribute\_group

Document representing a attribute group

*   `attribute_definitions` (_array of object\_attribute\_definition_) Attributes with the group displayed when expand=definition
*   `attribute_definitions_count` (_integer (int32)_) The count of the attributes within the group. This is a computed attribute and is read-only
*   `creation_date` (_string (date-time)_)
*   `description` (_object (localized)_) The free-form text description of the group by locale
    
    Additional properties: `string`.
    
*   `display_name` (_object (localized)_) The name used to display the group by locale.
    
    Additional properties: `string`.
    
*   `id` (_string_) The group's user specified identifier, used to retrieve the group
*   `internal` (_boolean_) True if the group is meant only for internal use, false otherwise. This property is read-only.
*   `last_modified` (_string (date-time)_)
*   `link` (_string_) URL that is used to get this instance. This is a computed attribute and is read-only
*   `position` (_number (double)_) The position of the group relative to other groups.  
    Minimum: 0.

_Example_

```
{
  "definitions_count": 17,
  "description": {
    "de": "A German my-description",
    "default": "my-description",
    "en": "An English my-description"
  },
  "display_name": {
    "de": "A German my-display_name",
    "default": "my-display_name",
    "en": "An English my-display_name"
  },
  "id": "my-attributegroup",
  "internal": false,
  "link": "https://example.com/s/-/dw/data/{version}/custom_objects/Global_String/attribute_groups/my-attributegroup",
  "position": 1
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### object\_attribute\_value\_definition

Document representing a attribute definition

*   `description` (_object (localized)_) A description of the attribute value.
    
    Additional properties: `string`.
    
*   `display_value` (_object (localized)_) A display name that can be used to present this value in the user interface. For example, the value might be '1' but the display name might be 'Order Exported'.
    
    Additional properties: `string`.
    
*   `id` (_string_) The ID of the attribute value.
*   `position` (_number (double)_) The position of the attribute value within the set of attribute values.
*   `value` (_object_) The value of the attribute.

_Example_

```
{
  "display_value": {
    "default": "Enum Of String Value 1"
  },
  "id": "EnumOfStringValue1",
  "position": 0,
  "value": "EnumOfStringValue1"
}
```

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=698c780362d68f9a57f2942f42c80dd0af4379ec1ff337c1fd8e6d0b8c993358 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-user-search.md -->

Data User Search (deprecated)

# Data User Search (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search users

`POST /user_search`

Operation ID: `Search users`. Tags: user\_search. Security: oauth2\_application.

Searches for users.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   login - String
    
*   email - String
    
*   first\_name - String
    
*   last\_name - String
    
*   external\_id - String
    
*   last\_login\_date - Date
    
*   is\_locked - Boolean
    
*   is\_disabled - Boolean
    

The output of the query can also be sorted. These are the list of sortable attributes:

*   login - String
    
*   email - String
    
*   first\_name - String
    
*   last\_name - String
    
*   external\_id - String
    
*   last\_login\_date - Date
    

This endpoint may return the following faults:

*   400 - MalformedSearchParameterException - Thrown if the query is ill-formed.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `search_request`.

#### Responses

*   **400** `MalformedSearchParameterException` - Thrown if the query is ill-formed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user_search_result`.
    

## Schemas

### search\_request

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields that each query supports are defined within the search resource.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### user\_search\_result

Document representing an user search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of user_) The sorted array of search hits. Can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
      "first_name": "Ocapi",
      "last_login_date": "2017-01-11",
      "last_name": "SiteGenesisDude",
      "locked": false,
      "login": "SiteGenesisDude",
      "preferred_data_locale": "default",
      "preferred_uilocale": "default"
    }
  ],
  "query": {
    "text_query": {
      "fields": [
        "login"
      ],
      "search_phrase": "Dude"
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 1
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) contain a search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "id",
  "sort_order": "asc"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### user

Document representing a user.

*   `creation_date` (_string (date-time)_)
*   `disabled` (_boolean_) Flag whether the user is disabled.
*   `email` (_string_, required) The email address.  
    Maximum length: 256.
*   `external_id` (_string_) The external id. This attribute is only valid when the user uses centralized authentication.  
    Maximum length: 256.
*   `first_name` (_string_) The first name.  
    Maximum length: 256.
*   `last_login_date` (_string (date)_) Last login of the user.
*   `last_modified` (_string (date-time)_)
*   `last_name` (_string_, required) The last name.  
    Maximum length: 256.
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `locked` (_boolean_) Flag whether the user is locked.
*   `login` (_string_) The user login.  
    Maximum length: 256.
*   `password` (_string_) The password. This attribute is only used to set the password upon user creation. This attribute is only valid when the user does not use centralized authentication.
*   `password_expiration_date` (_string (date-time)_) The user password expiration time
*   `password_modification_date` (_string (date-time)_) The time, where the password was last modified
*   `preferred_data_locale` (_string_) The effective preferred data locale of the user. A locale is only considered if the user has at least read permission on the locale.
*   `preferred_ui_locale` (_string_) The preferred UI locale of the user.
*   `roles` (_array of string_) List of role ids the user is assigned to.

_Example_

```
{
  "disabled": false,
  "email": "someUserl@example.com",
  "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
  "first_name": "John",
  "last_name": "Doe",
  "locked": false,
  "login": "someUser",
  "password_expiration_date": "2016-01-14T16:48:07Z",
  "password_modification_date": "2016-04-14T16:48:07Z",
  "preferred_data_locale": "default",
  "preferred_ui_locale": "en-US",
  "roles": [
    "FirstRole",
    "SecondRole"
  ]
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=640d3c67cf65317d670db04b3c2ad20142e08fb7c75d3b77bf4d6e1a359dde84 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-users.md -->

Data Users (deprecated)

# Data Users (deprecated)

Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage.

**Version:** 25.6

## Servers

*   `https://{host}/s/-/dw/data/v25_6`

Protocols: https.

## Security

*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get Users

`GET /users`

Operation ID: `Get Users`. Tags: users. Security: oauth2\_application.

Action to get all users with no filtering.

#### Parameters

*   `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0).
*   `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25).
*   `select` (query, string) The property selector.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `users`.
    

### GET Get user password expiration information

`GET /users/this`

Operation ID: `Get user password expiration information`. Tags: users. Security: oauth2\_application.

Action to get the user password expiration information.

This endpoint may return the following faults:

*   401 - UserIsLockedException - If the user profile is currently locked.
*   401 - UserNotAvailableException - If the user provided by the OAuth token cannot be found.

#### Responses

*   **401** `UserIsLockedException` - If the user profile is currently locked. or `UserNotAvailableException` - If the user provided by the OAuth token cannot be found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user`.
    

### PATCH Change a Local User Password

`PATCH /users/this/password`

Operation ID: `Change a Local User Password`. Tags: users. Security: oauth2\_application.

Action to change a local user password. This action cannot change the password for a user managed by Account Manager.

This endpoint may return the following faults:

*   400 - InvalidPasswordException - If the provided current user password is invalid.
*   400 - PasswordNotValidForReuseException - If the same new password was set recently before.
*   400 - PasswordPolicyViolationException - If the new password doesn't meet the acceptance crtiteria of a user password.
*   401 - UserIsLockedException - If the user profile is currently locked.
*   401 - UserNotAvailableException - If the user provided by the OAuth token cannot be found.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `password_change_request`.

#### Responses

*   **400** `InvalidPasswordException` - If the provided current user password is invalid. or `PasswordNotValidForReuseException` - If the same new password was set recently before. or `PasswordPolicyViolationException` - If the new password doesn't meet the acceptance crtiteria of a user password.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **401** `UserIsLockedException` - If the user profile is currently locked. or `UserNotAvailableException` - If the user provided by the OAuth token cannot be found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user`.
    

### GET Get User

`GET /users/{login}`

Operation ID: `Get User`. Tags: users. Security: oauth2\_application.

Action to get a user.

This endpoint may return the following faults:

*   404 - UserNotFoundException - If no user with the specified login could be found.

#### Parameters

*   `login` (path, string, required) login of the user  
    Minimum length: 1.

#### Responses

*   **404** `UserNotFoundException` - If no user with the specified login could be found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user`.
    

### PUT Create User

`PUT /users/{login}`

Operation ID: `Create User`. Tags: users. Security: oauth2\_application.

Action to create or overwrite a user.

If a user with the given login already exists, the existing user will be overwritten. If no such login exists, a new user is created.

This endpoint may return the following faults:

*   400 - ExternalIdAlreadyExistsException - If another user with the same external id already exists.
*   400 - InvalidCredentialsException - If password or external id of the user are invalid.
*   400 - LocalUserCreationException - If creation of a local Business Manager user is not allowed with the current server settings.
*   400 - PasswordPolicyViolationException - If the password doesn't meet the acceptance crtiteria of a user password.
*   400 - UnknownLocaleException - If either the Preferred UI Locale or the Preferred Data Locale are unknown.
*   400 - IdConflictException - If the login in the request URL is different from the login in the request body.
*   403 - UserOperationNotAllowedException - If creation or replacement of a user with the given login is not allowed.

#### Parameters

*   `login` (path, string, required) login of the user  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `user`.

#### Responses

*   **400** `ExternalIdAlreadyExistsException` - If another user with the same external id already exists. or `InvalidCredentialsException` - If password or external id of the user are invalid. or `LocalUserCreationException` - If creation of a local Business Manager user is not allowed with the current server settings. or `PasswordPolicyViolationException` - If the password doesn't meet the acceptance crtiteria of a user password. or `UnknownLocaleException` - If either the Preferred UI Locale or the Preferred Data Locale are unknown. or `IdConflictException` - If the login in the request URL is different from the login in the request body.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `UserOperationNotAllowedException` - If creation or replacement of a user with the given login is not allowed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user`.
    

### DELETE Delete User

`DELETE /users/{login}`

Operation ID: `Delete User`. Tags: users. Security: oauth2\_application.

Action to delete a single user.

This endpoint may return the following faults:

*   404 - UserNotFoundException - If no user with the specified login could be found.

#### Parameters

*   `login` (path, string, required) login of the user  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `UserNotFoundException` - If no user with the specified login could be found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update User

`PATCH /users/{login}`

Operation ID: `Update User`. Tags: users. Security: oauth2\_application.

Action to update a user.

Note: The `locked` flag and the user `password` cannot be updated with this resource.

This endpoint may return the following faults:

*   400 - ExternalIdAlreadyExistsException - If another user with the same external id already exists.
*   400 - ExternalIdNullException - If the external id is explicitly set to null for an externally managed user
*   400 - UnknownLocaleException - If either the Preferred UI Locale or the Preferred Data Locale are unknown.
*   400 - IdConflictException - If the login in the request URL is different from the login in the request body.
*   403 - UserOperationNotAllowedException - If creation or replacement of a user with the given login is not allowed.
*   404 - UserNotFoundException - If no user with the specified login could be found.

#### Parameters

*   `login` (path, string, required) login of the user  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `user`.

#### Responses

*   **400** `ExternalIdAlreadyExistsException` - If another user with the same external id already exists. or `ExternalIdNullException` - If the external id is explicitly set to null for an externally managed user or `UnknownLocaleException` - If either the Preferred UI Locale or the Preferred Data Locale are unknown. or `IdConflictException` - If the login in the request URL is different from the login in the request body.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `UserOperationNotAllowedException` - If creation or replacement of a user with the given login is not allowed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `UserNotFoundException` - If no user with the specified login could be found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `user`.
    

### GET Get access key

`GET /users/{login}/access_key/{scope}`

Operation ID: `Get access key`. Tags: users. Security: oauth2\_application.

Gets a single access key.

This endpoint may return the following faults:

*   403 - UserNotExternallyManagedException - When the specified user is not externally managed.
*   403 - UserAccessForbiddenException - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
*   404 - AccessKeyNotFoundException - If the access key does not exist.
*   404 - AuthenticationScopeNotFoundException - If the access scope does not exist.
*   404 - UserNotFoundException - If no user was found for the login.

#### Parameters

*   `login` (path, string, required) The login of the user.  
    Minimum length: 1.
*   `scope` (path, string, required) The scope of the access key.

#### Responses

*   **403** `UserNotExternallyManagedException` - When the specified user is not externally managed. or `UserAccessForbiddenException` - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AccessKeyNotFoundException` - If the access key does not exist. or `AuthenticationScopeNotFoundException` - If the access scope does not exist. or `UserNotFoundException` - If no user was found for the login.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `access_key_details`.
    

### PUT Creates access key

`PUT /users/{login}/access_key/{scope}`

Operation ID: `Creates access key`. Tags: users. Security: oauth2\_application.

Creates a single access key (and removes an existing one for the same scope).

This endpoint may return the following faults:

*   400 - AccessKeyIsExpiredException - If the acces key is already expired.
*   403 - UserNotExternallyManagedException - When the specified user is not externally managed.
*   403 - UserAccessForbiddenException - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
*   404 - AuthenticationScopeNotFoundException - If the access scope does not exist.
*   404 - UserNotFoundException - If no user was found for the login.

#### Parameters

*   `login` (path, string, required) The login of the user.  
    Minimum length: 1.
*   `scope` (path, string, required) The scope of the access key.

#### Request body

Media type: `application/json, text/xml`. Schema: `empty_body`.

#### Responses

*   **400** `AccessKeyIsExpiredException` - If the acces key is already expired.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `UserNotExternallyManagedException` - When the specified user is not externally managed. or `UserAccessForbiddenException` - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AuthenticationScopeNotFoundException` - If the access scope does not exist. or `UserNotFoundException` - If no user was found for the login.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `access_key_details`.
    

### DELETE Delete access key

`DELETE /users/{login}/access_key/{scope}`

Operation ID: `Delete access key`. Tags: users. Security: oauth2\_application.

Deletes a single access key.

This endpoint may return the following faults:

*   403 - UserNotExternallyManagedException - When the specified user is not externally managed.
*   403 - UserAccessForbiddenException - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
*   404 - AccessKeyNotFoundException - If the access key does not exist.
*   404 - AuthenticationScopeNotFoundException - If the access scope does not exist.
*   404 - UserNotFoundException - If no user was found for the login.

#### Parameters

*   `login` (path, string, required) The login of the user.  
    Minimum length: 1.
*   `scope` (path, string, required) The scope of the access key.

#### Responses

*   **204**
*   **403** `UserNotExternallyManagedException` - When the specified user is not externally managed. or `UserAccessForbiddenException` - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AccessKeyNotFoundException` - If the access key does not exist. or `AuthenticationScopeNotFoundException` - If the access scope does not exist. or `UserNotFoundException` - If no user was found for the login.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Enable / disable access key

`PATCH /users/{login}/access_key/{scope}`

Operation ID: `Enable / disable access key`. Tags: users. Security: oauth2\_application.

Enables / disables a single access key.

This endpoint may return the following faults:

*   403 - UserNotExternallyManagedException - When the specified user is not externally managed.
*   403 - UserAccessForbiddenException - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
*   404 - AccessKeyNotFoundException - If the access key does not exist.
*   404 - AuthenticationScopeNotFoundException - If the access scope does not exist.
*   404 - UserNotFoundException - If no user was found for the login.

#### Parameters

*   `login` (path, string, required) The login of the user.  
    Minimum length: 1.
*   `scope` (path, string, required) The scope of the access key.

#### Request body

Media type: `application/json, text/xml`. Schema: `access_key_update_request`.

#### Responses

*   **403** `UserNotExternallyManagedException` - When the specified user is not externally managed. or `UserAccessForbiddenException` - When the user executing the request is missing the required functional permission 'Manage\_Users\_Access\_Keys'.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AccessKeyNotFoundException` - If the access key does not exist. or `AuthenticationScopeNotFoundException` - If the access scope does not exist. or `UserNotFoundException` - If no user was found for the login.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `access_key_details`.
    

## Schemas

### users

Document representing a list of users.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of user_) The list of users.
*   `expand` (_array of string_) The list of expands set for the search request. Expands are optional.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "first_name": "Ocapi",
      "last_login_date": "2017-01-12",
      "last_name": "RoleDude",
      "locked": false,
      "login": "roleDude",
      "preferred_data_locale": "default",
      "preferred_uilocale": "default"
    },
    {
      "disabled": false,
      "email": "ocapi@example.com",
      "first_name": "Ocapi",
      "last_name": "SecondRoleManager",
      "locked": false,
      "login": "secondRoleManager",
      "preferred_data_locale": "en",
      "preferred_uilocale": "de"
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 2
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### user

Document representing a user.

*   `creation_date` (_string (date-time)_)
*   `disabled` (_boolean_) Flag whether the user is disabled.
*   `email` (_string_, required) The email address.  
    Maximum length: 256.
*   `external_id` (_string_) The external id. This attribute is only valid when the user uses centralized authentication.  
    Maximum length: 256.
*   `first_name` (_string_) The first name.  
    Maximum length: 256.
*   `last_login_date` (_string (date)_) Last login of the user.
*   `last_modified` (_string (date-time)_)
*   `last_name` (_string_, required) The last name.  
    Maximum length: 256.
*   `link` (_string_) URL that is used to get this instance. This property is computed and cannot be modified.
*   `locked` (_boolean_) Flag whether the user is locked.
*   `login` (_string_) The user login.  
    Maximum length: 256.
*   `password` (_string_) The password. This attribute is only used to set the password upon user creation. This attribute is only valid when the user does not use centralized authentication.
*   `password_expiration_date` (_string (date-time)_) The user password expiration time
*   `password_modification_date` (_string (date-time)_) The time, where the password was last modified
*   `preferred_data_locale` (_string_) The effective preferred data locale of the user. A locale is only considered if the user has at least read permission on the locale.
*   `preferred_ui_locale` (_string_) The preferred UI locale of the user.
*   `roles` (_array of string_) List of role ids the user is assigned to.

_Example_

```
{
  "disabled": false,
  "email": "someUserl@example.com",
  "external_id": "e2b07841-1db0-a5c1-9a1f-f6a02b6fa25c",
  "first_name": "John",
  "last_name": "Doe",
  "locked": false,
  "login": "someUser",
  "password_expiration_date": "2016-01-14T16:48:07Z",
  "password_modification_date": "2016-04-14T16:48:07Z",
  "preferred_data_locale": "default",
  "preferred_ui_locale": "en-US",
  "roles": [
    "FirstRole",
    "SecondRole"
  ]
}
```

### password\_change\_request

*   `current_password` (_string_, required) The current user password  
    Minimum length: 1.
*   `password` (_string_, required) The new user password  
    Minimum length: 1.

### access\_key\_details

Access key information

*   `access_key` (_string_) The newly created access key (only available upon access key creation, missing otherwise).
*   `enabled` (_boolean_) True when the access key is enabled.
*   `expiration_date` (_string (date-time)_) The date when the access key expires.

_Example_

```
{
  "enabled": true,
  "expiration_date": "2023-04-05T10:19:59.408Z"
}
```

### empty\_body

Type: `any`.

### access\_key\_update\_request

Request body to enable / disable an access key.

*   `enabled` (_boolean_) True when the access key should be enabled.

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=36d4b5811915b0d44f28bbf9e46b82aed2ebc0c2d9bf0ccbd479014a8151b178 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/datetimeslot-spi.md -->

DateTimeSlot SPI

# DateTimeSlot SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/datetimeslot-spi/datetimeslot-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to get delivery/pickup dates and time slots for applicable items in the order. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable delivery and pickup dates via their endpoint.

**Version:** 2.3.4

## Tags

### DateTimeSlot SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/datetimeslot-spi/datetimeslot-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to get delivery/pickup dates and time slots for applicable items in the order. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable delivery and pickup dates via their endpoint.

## Operations

### POST Retrieve date-time slots.

`POST /merchant/spi/sample/endpoint/sa/datetime/slots/from/external/system`

Operation ID: `getDeliveryDates`. Tags: DateTimeSlot SPI.

Retrieve delivery or pickup dates and time slots from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `DATE_PICKER`
    *   **API Endpoint:** Provide the external endpoint
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `SpiDeliveryDatesRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiDateTimesResponse`.
    

## Schemas

### SpiDeliveryDatesRequest

Request object to get delivery/pickup dates for products belonging to the same group, that is, products with the same shipping address, delivery group, or fulfillment type.

*   `products` (_array of SpiProduct_, required) The list of products in this group for which the delivery / pickup dates are to be returned in the response.
*   `datePickerType` (_string_, required) The type of action for which the dates are to be selected. Valid values: DELIVERY & PICKUP.  
    Allowed values: `DELIVERY`, `PICKUP`.
*   `shippingMethodId` (_string_, nullable) The shipping method ID in case the shipping method is selected for delivery items.
*   `address` (_SPIAddress_)

### SpiDateTimesResponse

Response object that contains a set of delivery/pickup date and time slots for the products sent in the request.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `dateTimeSlots` (_array of SpiDateTimeSlot_, required) The list of delivery/pickup date time slots for the products.
*   `availableDate` (_integer (int64)_, required) The first available date in epoch milliseconds that is eligible for delivery/pickup.
*   `dateTimeSlotType` (_string_, required) The type of date time slots provided. Valid values: Delivery & Pickup.  
    Allowed values: `Delivery`, `Pickup`.
*   `willCallDate` (_SpiDateTimeSlot_)
*   `error` (_boolean_)

### SpiProduct

The list of products in this group for which the delivery/pickup dates are to be returned in the response.

*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Product Quantity.
*   `gtin` (_string_) Product GTIN.

### SPIAddress

The full address of the destination of transaction.

*   `firstName` (_string_) Customer first name saved for address.
*   `lastName` (_string_) Customer last name saved for address.
*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.
*   `phone` (_string_) Phone.
*   `storeId` (_string_) Store ID if it is store address.
*   `emailAddress` (_string_) Customer Email Address.

### SpiDateTimeSlot

The backup delivery/pickup date in case slots are not available or unknown. (Default value can also be set in Store settings using property 'deliveryDatePickerWillCall' ).

*   `slotId` (_string_, required) Slot ID, unique value for this delivery/pickup day/date.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) The default selected time slot for the delivery/pickup date.  
    Example: `09:00 - 12:00`.
*   `availableTimeSlots` (_array of string_, nullable) The list of other time slots available for delivery/pickup.
*   `shippingMethodId` (_string_, nullable) Shipping Method ID for this slot in case of delivery item.

<!-- document id=328b91d65d5115585e9ceeda4997f3c58b4a286a7cb439ec1b13ad4982329036 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/debugging.md -->

# Debug PWA Kit Apps

Bugs and performance bottlenecks are an unavoidable part of web app development. With PWA Kit, you can get to the bottom of these issues with a variety of tools and techniques for examining your app up close.

Replace any placeholders in this guide with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

## General Troubleshooting

Before you follow the more targeted advice in this guide, try these general troubleshooting steps first:

- Double-check that you’re running a supported version of Node (refer to the [Get Started](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.md) guide) before starting your local development server.
- Confirm that your development server is still running and the port hasn’t been taken over by another process.
- After a code change, confirm that the message `HTTP development server listening` appears in the terminal before reloading your browser.
- Look for errors in both the browser console and in the terminal.
- Look for network error responses using your browser’s developer tools. (In Chrome’s DevTools, go to the **Network** tab.)
- To help identify syntax errors and typos, run a code formatter and a linter. Configuration files are provided for both [Prettier](https://prettier.io/) (code formatter) and [ESLint](https://eslint.org/) (linter) in the Retail React App.
- Check your computer’s antivirus and firewall settings for anything that is preventing your code from running or blocking network requests.
- To identify and analyze performance issues, use the Profiler in Chrome’s DevTools. For more information, see this guide from Google: [Analyze Runtime Performance](https://developer.chrome.com/docs/devtools/evaluate-performance/). You can also install the React Developer Tools extension for Chrome to get another Profiler tab where you can see similar info but at the component level.

## Query Parameters for Debugging

There are two special query parameters that you can add to any URL served by your commerce app to help debug issues with server-side code.

### `__server_only`

The `__server_only` query parameter stops the [hydration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Hydration_(web_development)>) process so that the page appears in your browser exactly as it does after server-side rendering. Seeing the server-side rendered version of the page helps troubleshoot issues not only with server-side rendering, but also with SEO since search engines crawl this version of the page.

### `__pretty_print`

The `__pretty_print` query parameter adds formatting to the `__PRELOADED_STATE__` object to make it more readable. This object provides a snapshot into your app’s state before hydration begins, so it can be helpful for debugging to see if it contains the values that you expect. To view the contents of the object, load your app, view the source of the page, and search for `__PRELOADED_STATE__`.

The `__PRELOADED_STATE__` object is included in a &lt;script&gt; tag within the HTML source of the page that was initially requested when your app begins running on the server side. The `__PRELOADED_STATE__` object contains serialized values returned from the `getProps` function (including the versions of `getProps` that are attached to the `_app` component and the page component).

### `__server_timing`

This feature is generally available from PWA Kit version 3.7.

The `__server_timing` query parameter provides detailed performance metrics for various stages of the rendering process with the HTTP [Server-Timing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing) header. This feature allows you to gain insights into the performance characteristics of your applications, helping in optimization and troubleshooting. When the `__server_timing` query parameter is present, the Server-Timing HTTP response header will be available, providing performance metrics. Performance metrics logs are also available in [Log Center](#debug-using-log-center).

#### Track Performance Metrics in Real-Time

To track the current performance on your site:

1. Run `npm start`.
2. Go to `http://localhost:3000?__server_timing`. Or go to any local URL for a page on your site and add the `__server_timing`query parameter to the URL.
3. Check the network responses using your browser’s developer tools. (In Chrome’s DevTools, go to the Network tab.)
4. Check the `Server-Timing` HTTP response header.

#### Performance Metrics

These metrics are included in the Server-Timing header. Each metric helps you understand specific aspects of the server-side rendering (SSR) process:

- `ssr.route-matching`: Measures the time taken to match an incoming request to a specific route. It is crucial for evaluating if the route configuration file (route.js) is optimally structured. Typically, this metric should be less than a few milliseconds.

- `ssr.load-component`: Represents the time required to load components on demand at the page level. Generally, this metric should also be less than a few milliseconds.

- `ssr.fetch-strategies`: Indicates how long in total your fetch strategy takes to complete.

- `ssr.fetch-strategies.get-props.<page-name>`: Time taken by the getProps function for execution, where `<page-name>` is either the `App` component or the page. This is only applicable when the `useLegacyGetProps` higher-order component (HOC) is used.

- `ssr.fetch-strategies.react-query.pre-render`: Duration for pre-render stage to collect all queries before rendering. This is only applicable when the `useReactQuery` HOC is used.

- `ssr.fetch-strategies.react-query.use-query.<query.meta.displayName>`: Time taken by individual useQuery calls. The display name can be set using the `meta.displayName` property of the query. By default, all queries in the `commerce-sdk-react` library have `displayName` configured. If no display name is added, it will be an integer index. This is only applicable when the `useReactQuery` HOC is used.

- `ssr.render-to-string`: Time taken to render the application to a string, after all network requests have completed. This metric is crucial for assessing the complexity of the application. Typical values are less than 100ms for small apps and may be longer for large-scale applications.

- `ssr.total`: The total time taken for the server to render the HTML output, encapsulating all stages of the SSR process.

#### Track Performance Metrics Continuously

If you want to capture performance metrics continuously, set the local `SERVER_TIMING` environment variable to `true`. This allows you to look up historical events and debug issues involving performance at a later time thru logs.

**note:** It's not recommended to set this environment variable on production environments because of its increased log usage.

For more performance-related recommendations, see [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.html).

## Debug Locally

By default, the app server displays console messages in the terminal but doesn’t otherwise allow you to observe code execution. This limitation can make it hard to debug the code that renders pages on the server side (or on your local machine).

For enhanced debugging, you can start your local development server with an alternate command that runs an inspector process in Node that a debugger can attach to. (For more details, see the [Node documentation](https://nodejs.org/en/docs/inspector).)

You can attach the debugger included in many popular browsers and text editors to Node’s inspector process. Here are instructions for Google Chrome and Visual Studio Code.

### Google Chrome

1.  Open a terminal.
2.  Go to your project directory.
3.  Start your local dev server using `npm run start:inspect`.
4.  To confirm that the debugger is listening, look for a “Debugger listening” message in the terminal output.
5.  Open Chrome and enter the URL chrome://inspect.
6.  Click **Open dedicated DevTools for Node**.
7.  DevTools opens in a new window.
8.  To confirm that the debugger is attached, look for a “Debugger attached” message in the terminal output.
9.  Set breakpoints, add `debugger` statements, and so on.
10. Load a page from your local development server in Chrome.
11. Use the dedicated window for debugging.

Now you can trace the execution of your server-side code!

To learn more about debugging with breakpoints in DevTools, see this guide from Google: [Debug JavaScript](https://developers.google.com/web/tools/chrome-devtools/javascript/).

### Visual Studio Code

1.  Open your project files in Visual Studio Code.
2.  From the menu bar, click **Terminal** > **New Terminal**.
3.  Start your local dev server using `npm run start:inspect`.
4.  Open the Command Palette. Shortcut for Windows: `Ctrl` + `Shift` + `P`. Shortcut for Mac `Command` + `Shift` + `P`.
5.  Type the following command: “Debug: Attach to Node Process.”
6.  A list of the Node processes appears. Choose the first one in the list.
7.  To confirm that the debugger is attached, look for a “Debugger Attached” message in the terminal output.
8.  Set breakpoints, add debugger statements, and so on.
9.  Load a page from your local development server in your web browser.
10. Use the integrated debugger in Visual Studio Code for debugging.

Now you can trace the execution of your server-side code in Visual Studio Code!

**tip:** To avoid having to attach the Node process repeatedly, open the Command Palette and enter “Debug: Toggle Auto Attach.” Toggle the setting to **Always** and restart your local dev server in the Visual Studio Code terminal.

## Debug on Managed Runtime

There are three ways to debug code deployed to Managed Runtime (MRT):

- Use [source maps](#debug-using-source-maps) to pinpoint where errors occurred.
- [Tail logs](#tail-logs-on-managed-runtime) to debug real-time issues or errors in a low-volume environment.
- For a production environment, use [Log Center](#debug-using-log-center), which offers powerful search and retention features.

### Debug Using Source Maps

Use source maps to identify any server-side errors. Source maps provide a simple error stack trace that pinpoints where an error occurred. For example, the stack trace identifies the file and line number where the error occurred to make troubleshooting easier.

**warning:** Enabling source maps has a performance impact, so we recommend using this feature in only non-production environments.

#### Source Maps Prerequisites

To use source maps, you must build your site using PWA Kit version 3.4.x or later. If you have an earlier version, upgrade your project to use PWA Kit 3.4.x.

#### Enable Source Maps

Enable source maps with Runtime Admin, the B2C CLI, or the Managed Runtime API.

**Use Runtime Admin**

1. Log into [Runtime Admin](https://runtime.commercecloud.com).
2. Click your project.
3. Click an environment.
4. Click **Environment Settings**.
5. In the Advanced section, click **Edit**.
6. Enable **Source Maps**.
7. At the top of the Advanced section, click **Update**.
8. Wait for the bundle to finish redeploying.

**Use the Managed Runtime API**

Call the [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) API endpoint and set `enable_source_maps` to `true`. This configures the `NODE_OPTIONS` Managed Runtime environment variable in your environment with `--enable-source-maps`and redeploys the bundle.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$API_KEY"

npx @salesforce/b2c-cli mrt env update \
  --project "$PROJECT_ID" --environment "$ENVIRONMENT_ID" --enable-source-maps
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/$ENVIRONMENT_ID/" \
--request 'PATCH' \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data '{"enable_source_maps": true}'
```

#### Upload Source Maps

1. When you build your project, generate the `ssr.js.map` file by using this local environment variable: `PWA_KIT_SSR_SOURCE_MAP=true`.

```bash
PWA_KIT_SSR_SOURCE_MAP=true npm run build
export PWA_KIT_SSR_SOURCE_MAP=true
```

2. [Deploy your bundle](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) to Managed Runtime.

#### View Source Maps

After you [enable](#enable-source-maps) and [upload](#upload-source-maps) source maps, you can view them using [Tail Logs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#tail-logs-on-managed-runtime) [on Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#tail-logs-on-managed-runtime).

#### Considerations

Using source maps can cause performance issues. For example, there’s latency anytime `error.stack` is accessed. So when you include `console.error(e)` in your code, this can slow down your site.

#### Default Settings for Source Maps

- **New Non-Production Environments:** `enable_source_maps` is set to `true`.
- **New Production Environments:** `enable_source_maps` is set to `false`. This behavior helps to avoid potential performance impacts that may arise when the source maps feature is enabled.
- **All Pre-existing Environments:** `enable_source_maps` is set to `false`.

### Manage Log Levels

Control the verbosity of server-side logs in your environment by setting appropriate log levels. The log level you set affects both Log Center and Log Tailing output.

Available log levels, from most to least verbose, are:

- `TRACE`—Detailed information about application flow.
- `DEBUG`—Information useful for debugging.
- `INFO`—General information about application operation.
- `WARN`—Warning messages for potentially harmful situations.
- `ERROR`—Error events that might still allow the application to continue running.
- `FATAL`—Severe error events that could lead to application termination.

#### Recommended Log Levels

- **Existing projects:** Set to `TRACE` level for backward compatibility.
- **New production environments:** Set to `WARN` level to reduce noise in production logs.
- **New non-production environments:** Set to `DEBUG` level to help with development and testing.

#### Set Log Level by Using Runtime Admin

1. Log into [Runtime Admin](https://runtime.commercecloud.com).
2. Click your project.
3. Click an environment.
4. Click **Environment Settings**.
5. In the Advanced section, click **Edit**.
6. Select your desired **Log Filtering** level.
7. At the top of the Advanced section, click **Update**.

#### Set Log Level by Using the Managed Runtime API

Call the [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) API endpoint to set the log level.

This example curl command makes a `PATCH` request to the API to set the log level to `WARN`.

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/$ENVIRONMENT_ID/" \
--request 'PATCH' \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data '{"log_level": "WARN"}'
```

### Tail Logs on Managed Runtime

When your app is deployed to Managed Runtime, remote debugging is not supported. However, you can tail logs for any Managed Runtime environment in real time to help diagnose any server-side errors.

Use the B2C CLI from any directory, or the PWA Kit project commands below.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY='your-runtime-admin-api-key'

npx @salesforce/b2c-cli mrt tail-logs --project my-storefront --environment staging
```

#### Within a PWA Kit Project

If you are working within a PWA Kit project generated from version 2.4.1 or higher, you can:

- View help for the logs command: `npm run tail-logs -- --help`
- Tail logs for a specific project and environment: `npm run tail-logs -- --environment $ENV_ID`

**note:** The extra `--` in the commands above is required.

#### Outside of a PWA Kit Project

If you are working outside of a PWA Kit project, or have a project generated from below version 2.4.1, you can use `npx` to:

- View help for the logs command: `npx @salesforce/pwa-kit-dev tail-logs --help`
- Tail logs for a specific environment ID and project ID: `npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID`

**note:** Instead of `--environment` and `--project` arguments, you can also use the shorter `-e` and `-p` arguments.

#### Constraints and Considerations

When tailing logs, keep in mind the following constraints:

- Each log tailing session will terminate after 60 minutes.
- Each environment can support up to 100 active log-tailing sessions at a time, across all users.
- To tail logs, you need to be given developer or admin user permissions to the Managed Runtime project.

### Debug Using Log Center

Use [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5) to troubleshoot errors if you built a site using [PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide) or you have a B2C Commerce instance. Log Center:

- Provides a single location to access logs from Managed Runtime (MRT) and your B2C Commerce instance. Connect what's happening in your MRT environment with what's going on in your B2C Commerce instance.
- Provides a dashboard for viewing MRT metrics, which includes charts for request counts, cache hits, and error rates, among others. See [Managed Runtime Metrics](https://help.salesforce.com/s/articleView?id=cc.b2c_metrics_managed_runtime.htm&type=5) in _Salesforce Help_.
- Lists Shopper Login and API Access (SLAS) errors. See [View SLAS Error Logs in Log Center](https://developer.salesforce.com/docs/commerce/commerce-api/guides/slas.md#view-slas-error-logs-in-log-center).
- Displays CDN error logs (Status Code 5xx), which help you troubleshoot content delivery and performance issues.
- Allows you to [search](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center_search.htm&type=5) and filter many historical logs. You can get more information about what happened in production, to help investigate and resolve issues quicker.

**note:** - MRT logs in Log Center are available for any [environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#environments) with Log Center logs enabled and a B2C Commerce instance associated. Marking the environment as production isn't required. See the [Prerequisites](#log-center-prerequisites).
- There can be a delay of up to 15 minutes between the time that an event happens and the log appears in Log Center.

This guide focuses on debugging for sites built using PWA Kit. For information about using Log Center with your B2C Commerce instance, see [Centralized Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5).

#### Log Center Prerequisites

To access MRT logs for an environment in Log Center, you must first:

1. Have the **Log Center User** role in Account Manager. To verify, check your role in [Account Manager](https://account.demandware.com/). If you don't have the role, ask your Account Manager admin to give you access. See [Managing Account Manager for Salesforce B2C Commerce Users](https://help.salesforce.com/s/articleView?id=000391212&type=1).
2. Set up the [environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#create-an-environment) as follows:

   - Select a B2C Commerce instance to connect to the environment.
   - Add one or more site IDs to associate with the environment.
   - Enable Log Center logs and Log Center metrics. See [Log Center Logs and Metrics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#log-center-logs-and-metrics).

#### View Logs

After you complete the [Prerequisites](#log-center-prerequisites), to view MRT logs in Log Center:

1. [Start Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_start_log_center.htm&type=5).
2. Select a **Region**.
3. Select a **[Realm](https://help.salesforce.com/s/articleView?id=cc.b2c_platform_overview.htm&type=5)**. If you don’t know your realm ID, ask your Account Executive (AE) or Customer Success Manager (CSM).
4. Click **Show filtered results**.
5. Click **Search > Current Search**.
6. Under Service Type, select **mrt** for Managed Runtime logs
7. Under Request Type, select **SSR** for application logs or **CDN** for CDN logs.
8. Under Host, select the environment whose logs you want to see. The format of the host is `$PROJECT.$ENVIRONMENT`. If you have more than one MRT environment with Log Center logs enabled, you can see multiple MRT host names.
9. View the MRT logs.

   If you’re using PWA Kit version 3.6.0 or later, you can quickly find logs generated by your PWA Kit site by searching on namespaces added as prefixes to logs in Log Center. The namespace pinpoints the specific part of your codebase where an error occurred.

   By default, PWA Kit provides namespacing in the format `<package-name>.<Component>.<action> <LOGLEVEL>`, the namespace is `<package-name>.<Component>.<action>.` Here are definitions of the parts of the namespace and the log level.

   - `<package-name>`: The name of the package where the error occurred.
   - `<component>`: The component within the package that encountered the issue.
   - `<action>`: The action being performed when the error was triggered.
   - `<LOGLEVEL>`: The severity level of the error.: TRACE, DEBUG, INFO, WARN, ERROR, or FATAL.

     Here are common examples of namespaces provided by PWA Kit:

     - `pwa-kit-runtime.httprequest`
     - `retail-react-app.App.render`
     - `retail-react-app.useActiveData.sendViewProduct`

     Logs with custom or unknown severity levels are forwarded to Log Center as INFO logs.

10. **Optional:** You can create your own custom namespace based on your requirements. For example, if you’re using a third-party integration such as a content management system (CMS), you can add the integration as a namespace. That way you can easily find errors associated with that integration in Log Center.

    To create a custom namespace:

    - Go to the file in your project for which you want to log messages. For example, your homepage file:
      `app/pages/home/index.jsx`.
    - Add this to the file:

      `import logger from '@salesforce/retail-react-app/app/utils/logger-instance`

    - In the component for which you want to create a namespace, add an if statement. In this example, we use a component called `CmsProductDescription` and add a namespace called `Home.CmsProductDescription`.

```jsx
<CmsProductDescription>
           if (err.code === 'MISSING_DESCRIPTION') {
               logger.warn('Missing Description', {
                   namespace: 'Home.CmsProductDescription',
                   additionalProperties: {
                       errorMessage: err.message
                   }
               });
           }
</CmsProductDescription>
```

### Limitations

- **Managed Runtime:** Each MRT log message available when you tail logs or use Log Center is limited to 32 KB. Any characters over 32 KB are truncated in the message. To avoid seeing truncated messages, you can [tail logs](#tail-logs-on-managed-runtime) in a non-production environment and shorten any long messages.
- **Log Center:** For information about log levels and log volumes, see [Configuration for Administrators](https://help.salesforce.com/s/articleView?id=cc.b2c_configuration_for_administrators.htm&type=5).

## See Also

- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.md)
- [Monitor Your PWA Kit Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/monitor-site.md)

<!-- document id=d41eff21fb562893615f6877252e2fb212cbc5fc9159ceef414135fc2399b240 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-debug.md -->

# Debug Storefront Next

Check out the debugging and troubleshooting tips to debug issues and performance bottlenecks in your storefront.

- [General Troubleshooting Tips for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug-troubleshoot.md)
<!-- - [Use Query Parameters for Debugging](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug-query-params.md) -->
- [Debug Your Storefront Next App Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug-locally.md)
- [Logging in Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-logging.md)
- [Debug Your Storefront Next Site Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug-log-center.md)

<!-- document id=06c2155639822f406557d8fb935e84830aa8f2d38cfdc6d3e672092793070867 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-debug-locally.md -->

# Debug Your Storefront Next App Locally

By default, the app server displays console messages in the terminal but you can't observe code execution. This limitation can make it hard to debug the code that renders pages on the server side (or on your local machine). For enhanced debugging, start your local development server with an alternate command that runs an inspector process in Node.js that a debugger attaches to.

For more information about the inspector process in Node.js, see the [Node.js documentation](https://nodejs.org/api/inspector.html).

Attach the debugger included in many popular browsers and text editors to Node’s inspector process. Here are instructions for Google Chrome and Visual Studio Code.

### Google Chrome

1. Open a terminal.
2. Go to your project directory.
3. Start your local dev server using `pnpm dev:debug`.
4. To confirm that the debugger is listening, look for a “Debugger listening” message in the terminal output.
5. Open Chrome and enter the URL `chrome://inspect`.
6. Click **Open dedicated DevTools for Node**.
7. DevTools opens in a new window.
8. To confirm that the debugger is attached, look for a “Debugger attached” message in the terminal output.
9. Set breakpoints, add `debugger` statements, and so on.
10. Load a page from your local development server in Chrome.
11. Use the dedicated window for debugging.

Now you can trace the execution of your server-side code!

To learn more about debugging with breakpoints in DevTools, see [Chrome DevTools](https://developer.chrome.com/docs/devtools/) from Google.

### Visual Studio Code

1. Open your project files in Visual Studio Code.
2. From the menu bar, click **Terminal** > **New Terminal**.
3. Start your local dev server using `pnpm dev:debug`.
4. Open the Command Palette. Shortcut for Windows: `Ctrl` + `Shift` + `P`. Shortcut for Mac `Command` + `Shift` + `P`.
5. Type the following command: “Debug: Attach to Node Process.”
6. A list of the Node processes appears. Choose the first one in the list.
7. To confirm that the debugger is attached, look for a “Debugger Attached” message in the terminal output.
8. Set breakpoints, add debugger statements, and so on.
9. Load a page from your local development server in your web browser.
10. Use the integrated debugger in Visual Studio Code for debugging.

Now you can trace the execution of your server-side code in Visual Studio Code!

**tip:** To avoid having to attach the Node process repeatedly, open the Command Palette and enter “Debug: Toggle Auto Attach.” Toggle the setting to **Always** and restart your local dev server in the Visual Studio Code terminal.

<!-- document id=f46b6ff326447d99736c90b75aa0768126a9e48204c1f51956257b39ff36be0e url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-debug-log-center.md -->

# Debug Your Storefront Next Site Using Log Center

Use [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5) to debug production issues for sites built using Storefront Next. Log Center aggregates logs from Managed Runtime (MRT) and your B2C Commerce instance in one place.

Log Center:

- Provides a single location to access logs from MRT and your B2C Commerce instance, so you can connect what's happening in your MRT environment with what's going on in your B2C Commerce instance.
- Lists Shopper Login and API Access (SLAS) errors. See [View SLAS Error Logs in Log Center](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#view-slas-error-logs-in-log-center).
- Displays CDN error logs (status code `5xx`), which help you troubleshoot content delivery and performance issues.
- Lets you [search](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center_search.htm&type=5) and filter many historical logs, so you can investigate and resolve issues faster.

**note:** - MRT logs in Log Center are available for any environment with Log Center logs enabled and a B2C Commerce instance associated. Marking the environment as production isn't required. See [Prerequisites](#log-center-prerequisites).
- There can be a delay of up to 15 minutes between the time that an event happens and the log appears in Log Center.

For information about the Storefront Next structured logger and log levels, see [Logging in Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-logging.md).

## Log Center Prerequisites

To access MRT logs for an environment in Log Center, first:

1. Have the **Log Center User** role in Account Manager. To verify, check your role in [Account Manager](https://account.demandware.com/). If you don't have the role, ask your Account Manager admin to give you access. See [Managing Account Manager for Salesforce B2C Commerce Users](https://help.salesforce.com/s/articleView?id=000391212&type=1).
2. Create an environment. See [Create an Environment in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-create-environment.md).

   Creating an environment in Business Manager associates the B2C Commerce instance and site IDs to the environment, which are prerequisites for Log Center logging.

3. Enable Log Center logs and Log Center metrics under Observability in Environment Settings. [DOUBLE CHECK THIS]

## View Logs

After you complete the [Prerequisites](#log-center-prerequisites), to view MRT logs in Log Center:

1. Open [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_start_log_center.htm&type=5).
2. Select a **Region**.
3. Select a **[Realm](https://help.salesforce.com/s/articleView?id=cc.b2c_platform_overview.htm&type=5)**. If you don't know your realm ID, ask your Salesforce account executive (AE) or customer success manager (CSM).
4. Click **Show filtered results**.
5. Click **Search > Current Search**.
6. Under Service Type, select **mrt** for Managed Runtime logs.
7. Under Request Type, select **SSR** for application logs or **CDN** for CDN logs.
8. Under Host, select the environment whose logs you want to see. The format of the host is `$PROJECT.$ENVIRONMENT`. If you have more than one MRT environment with Log Center logs enabled, you see multiple MRT host names.
9. View the MRT logs.

   Storefront Next emits logs in structured JSON format—one JSON object per line. Each line includes these fields.

   | Field           | Description                                                                                                                                   |
   | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
   | `level`         | Log severity: `error`, `warn`, `info`, or `debug`.                                                                                            |
   | `msg`           | The log message.                                                                                                                              |
   | `correlationId` | A unique ID assigned per request. All log entries for a single request share the same `correlationId`, so you can trace a request end to end. |
   | `method`        | The HTTP method, for example, `GET` or `POST`.                                                                                                |
   | `path`          | The URL pathname of the request.                                                                                                              |

   For example:

   ```json
   {
     "level": "warn",
     "correlationId": "a1b2c3",
     "method": "GET",
     "path": "/product/25518447M",
     "msg": "Product not found"
   }
   ```

   To narrow results to a specific request, filter on `correlationId`. To narrow results to a specific route, filter on `path` or `method`.

   **note:** The log level defaults to `warn` in production and `info` in other environments. The `SFCC_LOG_LEVEL` environment variable controls the log level. If you don't see expected log entries, check that the log level for your environment is set appropriately. See [Configure the Log Level](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-logging.md#configure-the-log-level).

10. (Optional) Generate logs for a specific component or third-party integration by using a custom field to make log filtering easier. Log Center lets you filter on the custom field to find all logs from a specific area of your codebase.

    For server-side code in loaders, actions, or middleware, use `getLogger(context)`. In this example, the custom field in the log call is `component`.

    ```typescript
    import { getLogger } from "@/lib/logger.server";

    export async function loader({ context }: LoaderFunctionArgs) {
      const logger = getLogger(context);
      if (err.code === "MISSING_DESCRIPTION") {
        logger.warn("Missing description", {
          component: "CmsProductDescription",
          errorCode: err.code,
        });
      }
    }
    ```

    For module-scope or client-side code where router context isn't available, use `createLogger()`:

    ```typescript
    import { createLogger } from "@/lib/logger";

    const logger = createLogger({ component: "CmsProductDescription" });
    logger.warn("Missing description", { errorCode: err.code });
    ```

    In both cases, the `component` field, or any custom field you add, appears in every log line and is searchable in Log Center.

## Limitations

- **Managed Runtime:** Each MRT log message available when you tail logs or use Log Center is limited to 32 KB. Characters over 32 KB are truncated. To avoid truncated messages, tail logs in a non-production environment and shorten any long messages. See [Tail Logs](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html#b2c-mrt-tail-logs) in the Agentic B2C Developer Toolkit.
- **Log Center:** For information about log levels and log volumes, see [Configuration for Administrators](https://help.salesforce.com/s/articleView?id=cc.b2c_configuration_for_administrators.htm&type=5).

## See Also

- [Logging in Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-logging.md)
- [Debug Your Storefront Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug-locally.md)

<!-- document id=64f257dd8185cb3ae3719958d90c51635b053ea1340413c116d9099804116556 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/decide-on-cdn.md -->

# Decide which CDN to Use

You have three content delivery network (CDN) options to launch and route traffic to your Progressive Web App (PWA) Kit site:

1. (Recommended) Use the Embedded CDN (eCDN), which is provided by Salesforce B2C Commerce. For more information about routing traffic to Managed Runtime using eCDN, see this [guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html). **eCDN is the recommended option for additional control over security features.**
2. Use the Managed Runtime (MRT) CDN. All new PWA Kit projects use the MRT CDN by default.
3. Use a third-party CDN such as CloudFlare or Akamai.

## CDN Comparison

This table summarizes the key differences between the various CDN options that you can use with your PWA Kit site.

Here are some key points in the table.

- If you have a [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md), stack eCDN or a third party CDN to facilitate traffic between your PWA Kit and SFRA sites.
- Using a third party CDN enables more features but requires more complexity, maintenance, and cost.

<table style="width: 100%; border-collapse: collapse; font-family: Arial, sans-serif; color: #4f4f4f;">
  <thead>
    <tr style="background-color: #f4f4f4; font-weight: bold;">
      <th style="border: 1px solid #ddd; padding: 10px 15px; text-align: left;"></th>
      <th style="border: 1px solid #ddd; padding: 10px 15px; text-align: left;"><b>MRT CDN (default)</b></th>
      <th style="border: 1px solid #ddd; padding: 10px 15px; text-align: left;"><b>eCDN</b></th>
      <th style="border: 1px solid #ddd; padding: 10px 15px; text-align: left;"><b>Third-Party CDN</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="padding: 10px 15px; font-weight: bold;">Why use it</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        Use the MRT CDN if:
        <ul style="font-size: 14px; margin-left: 20px;">
          <li>You want low cost to serve, quick time to market, and have limited CDN requirements.</li>
          <li>You need a CDN when working only with <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/creating-an-on-demand-sandbox.html" style="color: #0066cc;">on-demand sandboxes</a>.</li>
        </ul>
      </td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        Use eCDN if:
        <ul style="font-size: 14px; margin-left: 20px;">
          <li>You want to reduce the complexity of managing multiple systems, which is possible because eCDN is tightly integrated with B2C Commerce.</li>
          <li>You require additional control of web application firewall (WAF) rules available in eCDN.</li>
          <li>You need a CDN on only production, development, and staging environments, but not on sandboxes.</li>
        </ul>
      </td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        Use a third-party CDN if:
        <ul style="font-size: 14px; margin-left: 20px;">
          <li>You have a pre-existing relationship with your CDN vendor of choice, where internal teams are skilled in configuring and managing a CDN.</li>
          <li>You need additional control of CDN features above and beyond what eCDN or Managed Runtime provides.</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="padding: 10px 15px; font-weight: bold;">Use cases for which it's required</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">Not applicable</td>
      <td colspan="2" style="border: 1px solid #ddd; padding: 10px 15px;">
        eCDN or a third-party CDN is required if either of these use cases applies to your site: <b>a. </b> 
        You have a site that’s built 100% on Composable Storefront with multiple domains served from the same Managed Runtime environment; or <b>b. </b>You have a hybrid storefront with a single domain shared with SFRA.      
      </td>
    </tr>
    <tr>
      <td style="padding: 10px 15px; font-weight: bold;">Use cases for which it's optional</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">Not applicable</td>
      <td colspan="2" style="border: 1px solid #ddd; padding: 10px 15px;">
        eCDN or a third-party CDN is optional if you have a site that’s built 100% on Composable Storefront with one domain served from a single Managed Runtime environment.
      </td>
    </tr>
    <tr>
      <td style="padding: 10px 15px; font-weight: bold;">Summary of how to set it up</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        To set up the MRT CDN:
        <ol style="font-size: 14px; margin-left: 20px;">
          <li>Complete the steps under <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#before-you-begin" style="color: #0066cc;">Before You Begin</a>.</li>
          <li>Under <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#launching-an-environment" style="color: #0066cc;">Launching an Environment</a>, complete steps 1, 2, 3, 4, 5 (option 2), 6 (option 3), and 7.</li>
        </ol>
      </td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        To set up eCDN:
        <ol style="font-size: 14px; margin-left: 20px;">
          <li>Complete the steps under <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#before-you-begin" style="color: #0066cc;">Before You Begin</a>.</li>
          <li>Under <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#launching-an-environment" style="color: #0066cc;">Launching an Environment</a>, complete steps 1, 2, 5 (option 1), 6 (option 2), and 7.</li>
        </ol>
      </td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        To set up a third-party CDN:
        <ol style="font-size: 14px; margin-left: 20px;">
          <li><a href="https://help.salesforce.com/s/articleView?id=cc.b2c_configuring_an_external_cdn.htm&amp;type=5" style="color: #0066cc;">Configure an External CDN or Third-Party Proxy</a>.</li>
          <li>Use your chosen third-party CDN to ensure that URLs are constructed to point to the correct CDN domain and not the MRT domain. Add a dynamic header to incoming requests. To do so, in your third-party CDN, ensure that an x-forwarded-host header exists in requests sent to the MRT origin. Check your CDN vendor documentation for adding a dynamic header to incoming requests.</li>
          <li>Identify the remote IP of each shopper. See <a href="https://help.salesforce.com/s/articleView?id=000391453&type=1" style="color: #0066cc;">Deriving Remote End-User/Client IP Address</a>.</li>
          <li>Follow best practices for bot protection. See <a href="https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html#implementation-best-practices" style="color: #0066cc;">Implementation Best Practices</a> and <a href="https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-mitigation-sk.html" style="color: #0066cc;">Bot Mitigation Best Practices for Flash Sales</a>.</li>
          <li>Configure TLS certificates. Check your CDN vendor documentation for more information.</li>
          <li>Complete the steps under <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#before-you-begin" style="color: #0066cc;">Before You Begin</a>.</li>
          <li>Under <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#launching-an-environment" style="color: #0066cc;">Launching an Environment</a>, complete steps 1, 2, 5 (option 1), 6 (option 1), and 7.</li>
        </ol>
      </td>
    </tr>
  </tbody>
</table>

## See Also

- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.md)
- [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md)

<!-- document id=8dd993ea9870169382759fca186eb3e4a5bf6b5a18d8fed60cc756d5d2de785a url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-ods-security-rules.md -->

# Default Security Rules on On-Demand Sandbox (ODS) Instances

**Applies to: All storefronts on On-Demand Sandbox (ODS) instances — Storefront Next, Composable Storefront (PWA Kit), SFRA, and Site Genesis**

When you create a Storefront Next storefront on an on-demand sandbox (ODS) instance, Business Manager adds three security rules to the default zone in [Embedded CDN Settings](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones.md): two custom firewall rules and one rate limiting rule. The default zone is shared across every storefront on the instance, so these rules apply to all storefronts hosted there, including Storefront Next, Composable Storefront, SFRA, and Site Genesis, not only the storefront that triggered their creation.

**note:** These rules are added only on ODS instances. They aren't added to Primary Instance Group (PIG) environments, such as staging or production.

## Why These Rules Exist

ODS instances are for development and testing, not production traffic, and they have less capacity than a production instance. Left unchecked, known AI crawlers and bots that scan for common vulnerability paths can index development content and consume server resources that your team needs for active development. These default rules limit that automated traffic so your ODS storefronts stay responsive during development.

## View the Default Rules

1. In Business Manager, go to **Administration > Sites > Embedded CDN Settings**.
2. From the **Zone** dropdown, select the default zone for the instance.
3. Click the **Security Rules** tab.

![Default Custom Firewall Rules and Rate Limiting Rules on the Security Rules tab](https://developer.salesforce.com/docs/media/sfnext/sfnext-ods-security-rules-1.png '{"class": "image-xl"}')

The Security Rules tab shows two rule groups.

| Rule Group            | Rule Name                             | Action | Description                                                                                                                        |
| --------------------- | ------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| Custom Firewall Rules | Block Known AI Crawlers by User Agent | Block  | Blocks requests whose User-Agent header matches known AI crawler signatures.                                                       |
| Custom Firewall Rules | Block Known Probe Paths               | Block  | Blocks requests to paths that known bots and scanners commonly probe for exposed configuration, admin, or vulnerability endpoints. |
| Rate Limiting Rules   | Rate Limit by IP Address              | Block  | Blocks an IP address that exceeds 60 requests per minute against the default zone.                                                 |

## Default Exclusions

The **Rate Limit by IP Address** rule's expression excludes traffic that shouldn't count toward the limit, so normal storefront and developer traffic isn't throttled. By default, the rule excludes:

- Composable Storefront and Storefront Next static assets
- SFRA/Site Genesis static assets
- OCAPI and SCAPI API paths
- Business Manager and WebDAV paths

The two custom firewall rules (AI crawler and probe path blocking) don't include this exclusion list. If either firewall rule blocks traffic that you expect to allow, edit that rule directly.

## Adjust or Disable a Rule

We recommend adjusting a rule's exclusions or rate limit rather than disabling it. The rules exist to keep known bots and crawlers from consuming ODS resources and indexing content during development; disabling a rule removes that protection for every storefront on the default zone, not just yours.

### Add Exclusions to the Rate Limit Rule

1. On the **Security Rules** tab, under **Rate Limiting Rules**, click the caret next to **Rate Limit by IP Address** to expand the rule.
2. Add your path or pattern to the rule's expression so that matching requests are excluded from the rate limit.
3. Click **Save**.

For the full expression syntax and available operators, see [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-rule-expression-fields.md).

### Change the Rate Limit

1. On the **Security Rules** tab, under **Rate Limiting Rules**, click the caret next to **Rate Limit by IP Address** to expand the rule.
2. Update the requests-per-period value from the default of 60 requests per minute to the limit you want.
3. Click **Save**.

### Disable a Rule

Each rule has an **Enabled** toggle in its row on the **Security Rules** tab. Turning it off disables the rule for every storefront on the default zone. Before disabling a rule, try adjusting its exclusions or rate limit instead.

## Related Topics

- [Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-ods.md)
- [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-rate-limiting-rules.md)
- [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones-custom-rules.md)
- [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-rule-expression-fields.md)
- [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md)

<!-- document id=99e927410dbd68accfd9e29e3be9719f6524d66fd45e7f1b7f239c16abefea97 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-import-tokens-delete.md -->

# Delete a Saved Payment Method Using the sObject API

Use the SavedPaymentMethod sObject API to delete a Saved Payment Method (SPM) record directly in Salesforce.

**Resource**

`/services/data/{version}/sobjects/SavedPaymentMethod`

**Resource example**

`https://<my-domain>.salesforce.com/services/data/66.0/sobjects/SavedPaymentMethod/12qSxxxxx000qKsHYAU`

**HTTP method**

DELETE

You can also delete a SPM record directly from the Salesforce UI. Here’s a sample UI showing the implementation of the delete action.

![Diagram of the workflow for deleting a saved payment method record](https://developer.salesforce.com/media/d2c-commerce/delete_spm_record.png '{"class": "image-lg", "title": "Delete Saved Payment Method"}')

**See Also**

- [_REST API Developer Guide_: Delete a Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_delete_record.htm)

<!-- document id=cb54ba217a5b8de1678ca377e369a74cebaa98a3e69662661e4f4d5150d2a362 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_delete_ods_scheduler.md -->

# Delete an ODS Operation Scheduler

When an ODS operation scheduler is no longer needed, delete it.

**note:** To delete an ODS operation scheduler, you need the `Sandbox_API_User` role with a tenant filter in the format `<realm_id>_sbx` in Account Manager.

1. In Control Center, select the realm you want to modify.
2. Select **On-Demand Sandboxes**.
3. For the scheduler you want to delete, click **Edit**.
4. In the scheduler, click **Delete.**, and confirm the deletion.

<!-- document id=01c028a8000e1fe6bd6a1c4d879e25bf78a4d213b279169c0f22abccdba15643 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_delete_ods_instance.md -->

# Delete an On-Demand Sandbox

In Control Center, delete an on-demand sandbox (ODS) instance.

**note:** To delete an On-Demand sandbox, you must have the `Sandbox_API_User` role with a tenant filter in the format `<realm-id>\_sbx` in Account Manager. For example, to delete an ODS instance in the realm "abcd", you must have the `Sandbox_API_User` role with tenant filter "abcd_sbx" in Account Manager.

1. Log into Control Center.
2. Select the realm where you want to delete the ODS instance.
3. Locate the ODS instance you want to delete.
4. Click the **Delete icon** (trashcan). If you don't have sufficient permissions, the icon isn't active.
   **note:** When you delete an ODS instance, all instance data is deleted. This action can't be undone.
5. In the confirmation window, click **Yes, Delete**.

<!-- document id=6642446cb5e7c3d4ac6173994a8b5904b1dd8d565445b0b69326bf35b88789c1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-del-file-ds.md -->

# DelFile.ds

Review the DelFile.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/**
 * Delete the file or directory.
 *
 * @input SourceFileName  : String   the file to move
 * @input SourceDirectory : dw.io.File   the processing directory where the file is located
 * @input sampleLogger    : Object Sample logger	input for Sample logger
 * @output sampleLogger   : Object Sample logger	debug output for Sample logger
 * @output sampleError 	  : Object Sample error	error output for Sample logger
 */
importPackage(dw.system);
importPackage(dw.io);



// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");



function execute(pdict: PipelineDictionary): Number {
    // sample Logging var
    var _context: String = new Context("DelFile.ds");
    var _logger: Log = Log.getLogger(pdict);

    var sourceFileName: String = pdict.SourceFileName;
    var sourceDirectory: String = pdict.SourceDirectory;

    var sourceFile: File = new File(sourceDirectory, sourceFileName);

    if (!sourceFile.exists()) {
        _logger.error(_context, "Source file '" + sourceFile.name + "' in path '" + sourceFile.path + "' cannot be found");
        return PIPELET_ERROR;
    }

    _logger.info(_context, "Delet file " + sourceFile);

    try {
        sourceFile.remove();
    } catch (e) {
        var exception: sampleException = new sampleException(_context, "Failed delete file " + sourceFileName, e);
        _logger.error(_context, "Failed delete file " + sourceFileName + exception);
        pdict.sampleError = exception;
    }

    return PIPELET_NEXT;
}
```

<!-- document id=2b021a975cb86e3804316bfa463ab6e2cdcd005f90887250c9cbb15f27639a6e url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/delivery-group-spi.md -->

Delivery Group SPI

# Delivery Group SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/delivery-group-spi/delivery-group-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations to obtain the relevant delivery groups.

**Version:** 2.3.4

## Tags

### Delivery Group SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/delivery-group-spi/delivery-group-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations to obtain the relevant delivery groups.

## Operations

### POST Retrieve delivery group list.

`POST /merchant/spi/sample/endpoint/sa/deliveryGroup`

Operation ID: `getDeliveryGroupList`. Tags: Delivery Group SPI.

Retrieve delivery group from merchant's system. This SPI also provides shipping options for each delivery group. This SPI is used by POS to get delivery groups corresponding to cart and is triggered if the cart has a delivery item. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `DELIVERY_GROUP`
    *   **API Endpoint:** Provide the external endpoint to get the delivery group, for example: [https://sample/external/endpoint/to/get/deliveryGroup/from/external/system/456709](https://sample/external/endpoint/to/get/deliveryGroup/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `*/*`. Schema: `SPIShipmentProcessorRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SPIShipmentProcessorResponse`.
    

## Schemas

### SPIShipmentProcessorRequest

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `cartItemList` (_array of SPIShipmentProcessorRequestProduct_, required) All the items from the cart. Each item has a link to its delivery group via deliveryGroupId.
*   `deliveryGroupList` (_array of SPIShipmentProcessorRequestDeliveryGroup_, required) All delivery groups corresponding to the delivery items from the cart.

### SPIShipmentProcessorResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cartItemList` (_array of SPIShipmentProcessorResponseProduct_, required) All items from the cart are associated with a deliveryGroupId, enabling linkage to the corresponding deliveryGroup within the deliveryGroupList. Additionally, each item may possess custom attributes.
*   `deliveryGroupList` (_array of SPIShipmentProcessorResponseDeliveryGroup_, required) All delivery groups corresponding to the delivery items from the cart.
*   `error` (_boolean_)

### SPIShipmentProcessorRequestProduct

All the items from the cart. Each item has a link to its delivery group via deliveryGroupId.

*   `orderItemId` (_string_, required, write-only) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `parentOrderItemId` (_string_, write-only) Indicates the parent order item ID for add-on items, pointing to the main item's order item ID. For example, values like 1, 2, or 3 represent the line item number of the parent item.  
    Example: `1, 2, 3`.
*   `deliveryGroupId` (_string_, write-only) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `productId` (_string_, required, write-only) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required, write-only) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `customAttributeList` (_array of ProductFormAttribute_) Custom attributes related to the product. The products have custom attributes  
    like customString0,customString1. etc. Merchants can map their custom attributes to  
    these fields in field mapping and provide the values in the product feed.  
    For more details, see:  
    [Clienteling SPI Field Mapping](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-field-mapping.html)  
    If merchants want custom attributes to be exported in Order Export and also here in  
    this SPI request, they need to configure CMS's store settings as below  
    **CMS** > **Store Management** > **Store Setting** > **Oms** > **Order** export > tLogCustomProductAttributes >  
    customString0,customString1.. etc.  
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `name` (_string_, required, write-only) Name of the item.
*   `price` (_number_, required, write-only) Price of the item.
*   `quantity` (_integer (int32)_, required, write-only) Item's Quantity.
*   `imageURL` (_string_, required, write-only) Image URL of the item.
*   `subTotal` (_number_, required, write-only) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_, write-only) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required, write-only) Item's total (final amount charged for this item), inclusive of tax/VAT and discounts.
*   `productTax` (_ExternalProductTax_)
*   `size` (_string_, write-only) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required, write-only) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required, write-only)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, write-only) Item's GTIN.
*   `fulfillmentType` (_string_, required, write-only) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required, write-only)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `productClass` (_string_, required, write-only) Product class of the item.
*   `serialNumber` (_string_, write-only) Serial number of the item (if applicable).
*   `productCondition` (_string_, write-only) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `registryId` (_string_, write-only, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.

### SPIShipmentProcessorRequestDeliveryGroup

All delivery groups corresponding the delivery items from the cart.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Unique ID in alphanumeric format.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_SPIShipmentProcessorShippingMethod_)
*   `shippingAddress` (_ExternalAddress_)
*   `dateTimeSlot` (_ExternalDateTimeSlot_)
*   `availableDateTimeSlotList` (_array of ExternalAvailableDateTimeSlot_, read-only) Available delivery date time slots.
*   `deliveryDatePickerOption` (_string_, read-only) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `sortOrder` (_integer (int32)_, required) PS POS uses sort order to display delivery groups in a specific sequence. If not provided, the display order becomes unpredictable.
*   `fulfillmentAddress` (_ExternalAddress_)

### SPIShipmentProcessorResponseProduct

All items from the cart are associated with a deliveryGroupId,  
enabling linkage to the corresponding deliveryGroup within the deliveryGroupList.  
Additionally, each item may possess custom attributes.

*   `orderItemId` (_string_, required, read-only) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `deliveryGroupId` (_string_, read-only) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available in order export JSON at item level under attribute:  
    tLogCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    

### SPIShipmentProcessorResponseDeliveryGroup

All delivery groups corresponding the delivery items from the cart.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Unique ID in alphanumeric format.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_SPIShipmentProcessorShippingMethod_)
*   `shippingAddress` (_ExternalAddress_)
*   `dateTimeSlot` (_ExternalDateTimeSlot_)
*   `availableDateTimeSlotList` (_array of ExternalAvailableDateTimeSlot_, read-only) Available delivery date time slots.
*   `deliveryDatePickerOption` (_string_, read-only) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `sortOrder` (_integer (int32)_, required) PS POS uses sort order to display delivery groups in a specific sequence. If not provided, the display order becomes unpredictable.
*   `fulfillmentAddress` (_ExternalAddress_)
*   `shippingMethodList` (_array of SPIShipmentProcessorShippingMethod_) Available shipping method options corresponding to the delivery group. It is optional and must be provided if an address is provided for the delivery group.

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### ExternalProductTax

Tax/Vat details.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption.
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates.
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates.
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item.
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request.

### SPIShipmentProcessorShippingMethod

This selected or default shipping method must be chosen from the shippingMethodList if an address is provided for the delivery group. Refer to other attributes address and shippingMethodList for more details. It is optional.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `price` (_number_, required) Shipping cost.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `itemLevelCharges` (_array of SPIShipmentProcessorItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### ExternalAddress

Billing address.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, required, nullable) Customer first name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `addressLine1` (_string_, required, nullable) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required, nullable) City.  
    Maximum length: 64.
*   `state` (_string_, required, nullable) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required, nullable) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, required, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `addressType` (_string_, nullable) Address type- Home, Business.
*   `emailAddress` (_string_, nullable) Customer Email Address.  
    Maximum length: 64.
*   `country` (_string_, nullable) Country.

### ExternalDateTimeSlot

Delivery date time. It is optional. It must be provided if associate/customer has entered the delivery date for the delivery group.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `date` (_integer (int64)_, required) Delivery date in epoch.
*   `timeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ExternalAvailableDateTimeSlot

Available delivery date time slots.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `date` (_integer (int64)_, required) Delivery date in epoch.
*   `availableTimeSlots` (_array of string_) Available time slots.  
    Items: Example: `["12:00 - 14:00"]`.
    
    _Example_
    
    ```
    [
      "12:00 - 14:00"
    ]
    ```
    
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### SPIShipmentProcessorItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

<!-- document id=29ff0fec4cd4f44acb43bcb16372b5688977297ea3a5b8d6c86c7161e2983d35 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-deploy-lwc-component.md -->

# Deploy a Custom Component

Deploy a Lightning web component to use it on pages in your B2B store built with an LWR template.

1.  From the component project directory in Visual Studio Code, right-click the default folder under force-app/main, and select **SFDX: Deploy Source to Org**.

    ![Screenshot of SFDX deploy source to org menu in VS Code.](https://developer.salesforce.com/media/d2c-commerce/deploy_lwc.png)

2.  On the Output tab of the integrated terminal, view the results of your deployment. SFDX displays a deployment status notice that includes an exit code, such as “SFDX: Deploy Source to Org ... ended with exit code 0.” Exit code 0 means that the command ran successfully.

    ![Screenshot of deployment  success message.](https://developer.salesforce.com/media/d2c-commerce/success_deploy_lwc.png)

**See Also**

- [Add a Custom Component to Your Store](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-add-lwc-component.htm)

<!-- document id=7329b4de05ca036616e0e3638641bc1b8361985d8e7844d5206a4022885172e3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-section.md -->

# Deploy and Manage Storefront Next on Managed Runtime

Managed Runtime provides the cloud infrastructure to deploy, host, and monitor Storefront Next.

In this section:

- [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md)
- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md)
- [Deploy Storefront Next to Managed Runtime (MRT)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md)
- [Node Version Support](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-node-version.md)
- [Automate Environment Administration with the API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-api.md)
- [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md)
- [Troubleshoot Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-env-var-troubleshoot.md)
- [Environment Base Paths](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-base-path.md)
- [Managed Runtime (MRT) Data Store](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-data-store.md)
- [Manage Sites for Storefront Next in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-manage-sites.md)
- [Manage the Storefront Development Workflow in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-developer-workspace.md)

<!-- document id=d2b5ee4af9c7131199b4884f1908e9fcc9748b7331d4e32eb98ae41d1fe7afb1 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-deploy-experience-metadata.md -->

# Deploy Experience Metadata to a Target Org

Experience metadata supports the look and feel of the store, the user interface, and the user experience components. Deploying experience data can involve transferring customizations made to the store’s layout, design, and navigation and moving custom code or integrations.

## Deploy Experience Metadata with Change Sets

To deploy the Experience metadata with Change Sets, follow the steps outlined in [_Migrate Your Store Configuration_](https://help.salesforce.com/s/articleView?id=commerce.comm_migrate_store.htm&type=5). Configure the source and target [_deployment connections_](https://help.salesforce.com/s/articleView?id=platform.changesets_about_connection.htm&type=5), and follow the same set of steps substituting Experience Bundle, Network, and Custom Site for the component types.

## Deploy Experience Metadata with the DigitalExperienceBundle and DigitalExperienceConfig for Enhanced LWR Sites

The experience bundle metadata deployment process involves extracting the metadata from the source environment. Use Salesforce DX, Metadata API, change sets, or a third-party deployment tool, and then deploy to the target environment.

Before you deploy DigitalExperienceBundle, review these considerations.

- **Dependencies–**Make sure that all related metadata, such as Apex classes, Lightning components, and custom objects that the digital experience depends on, are included in your migration package.
- **Compatibility–**Check that the target org is compatible with the features and settings of the digital experience that you’re migrating.
- **Validation–**Test the migration in the target org without committing the changes so that you can address issues before the actual deployment.
- **Backup–**Before deploying to the target org, back up your current target metadata in case you need to roll back to a previous state.
- **Testing–**After deployment, thoroughly test the digital experience in the target org to confirm that all functionality works as expected.

## Deploy Experience Metadata with the ExperienceBundle for LWR Sites

Note: These guidelines outline a general approach to deploying Experience metadata for LWR sites. Each Salesforce Commerce instance is unique, and your process can vary. To retrieve and deploy DigitalExperienceBundle metadata, follow these guidelines.

1. Make sure the source environment is fully configured.
2. Document any manual configurations or settings that the metadata doesn’t capture.
3. Use the Salesforce Command-Line Interface (CLI) to retrieve the DigitalExperienceBundle metadata from the source environment.

   a. For example:

   `Sf Projet retrieve start --target-org my_scratch –-metadata ExperienceBundle -dir ./<directory>`

   This sample command pulls the metadata into your local Salesforce DX project.

4. Commit the retrieved metadata to a version control system like DevOps or Git. This step is crucial for tracking changes and maintaining a history of your configurations.
5. Make sure that the target environment is ready for the deployment.

   a. Set up dependencies that the DigitalExperienceBundle requires, such as custom objects, Apex classes, permission sets, and profiles.

6. Deploy the Metadata.

   a. Use Salesforce CLI to deploy the DigitalExperienceBundle metadata to the target environment with a command.
   b. For example:

   `Sf project deploy start --metadata ExperienceBundle --target-org a-prod-org --dir ./<directory>`

   c. Monitor the deployment for any errors and resolve them as needed.

7. After the metadata is deployed, perform any necessary post-deployment steps such as configuring domains, updating URLs, or setting up single sign-on (SSO) if necessary.
8. Manually reapply any settings or configurations that aren’t deployed with the metadata.

## Deploy Experience Metadata with the Salesforce Metadata API, Salesforce CLI, and Salesforce DX

Deploying a Salesforce B2B Commerce enhanced LWR store’s DigitalExperienceBundle metadata from one environment to another involves a series of steps. Here's a general process to follow.

These guidelines outline a general approach to deploying Experience metadata for enhanced LWR sites.

It’s important to have a rollback plan in case you encounter critical issues that can’t be resolved in the target environment post-deployment. Test your rollback procedures in the source org before the actual deployment to ensure that they work as expected.

1. Make sure that the source environment is fully configured.
2. Document the manual configurations or settings that the metadata doesn’t capture.
3. Use Salesforce CLI to retrieve the DigitalExperienceBundle metadata from the source environment.

   a. For example, this command pulls the metadata into your local Salesforce DX project.

   `Sf Projet retrieve start --target-org my_scratch –-metadata DigitalExperienceBundle -dir ./<directory>`

4. Commit the retrieved metadata to a version control system like DevOps or Git to track changes and maintain a history of your configurations.
5. Make sure that the target environment is ready for the deployment.

   a. Set up dependencies that the DigitalExperienceBundle requires, such as custom objects, Apex classes, permission sets, and profiles.

6. Deploy the metadata to the target environment.

   a. For example:

   `Sf project deploy start --metadata DigitalExperienceBundle --target-org a-prod-org --dir ./<directory>`

   Monitor the deployment for any errors and resolve them as needed.

7. Perform post-deployment steps, such as configuring domains, updating URLs, or setting up single sign-on.
8. Manually reapply settings or configurations that couldn’t be deployed with the metadata.

<!-- document id=26a1fcb49601acab860c82b9f28bb3b91f4b5c9651c5d2dd5573a642f533703f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-deploy-object-data.md -->

# Deploy Object Data

Deploying store object data from a Salesforce source org to a target org involves careful planning and execution to ensure data integrity and system stability. Here’s a general process to follow.

## Checklist for Deploying Object Data

1. Prepare data.

   a. Make sure that the data is accurate and up to date. Cleanse the data in the sandbox environment.

   b. Remove test data that ‌you don’t want deployed to the target org.

   c. Identify data dependencies and relationships to make sure that related records are deployed together.

2. Map the fields from the sandbox to the target org.

   a. Make sure that the data is directed to the correct fields.

   b. Before deployment, create the custom fields or objects that ‌don’t exist in the target org.

3. Back up your current target org data before importing new data.

   a. This backup is crucial for restoring the system in case the deployment causes unexpected issues.

4. Choose a data deployment tool that’s designed for bulk data operations, such as Salesforce Data Loader.

   a. Configure the tool with the target org’s credentials and endpoint.

5. Test in a full copy source org.

   Perform a test deployment in a full copy source org that is a replica of the target org to identify potential issues before they affect the target system.

6. Migrate the data

   a. To minimize the impact on users, schedule the deployment during off-peak hours.

   b. Use the Data Loader or deployment tool to insert, update, or upsert the data from the source org to the target org.

   c. Monitor the deployment process for errors or issues.

7. Validate the data in the target org.

   a. Make sure that all records were deployed successfully and that relationships are intact.

   b. Check the error logs, and address records that failed to deploy.

8. Test the deployed data.

   a. Thoroughly test the target org to make sure that the deployed data is functioning as expected.

   b. Test integrations, workflows, and processes that rely on the deployed data.

9. Review and clean up the data.

   a. Check for duplicate records or data inconsistencies. Duplicated records can be created during the deployment.

   b. Clean up unnecessary data that was inadvertently deployed.

10. Go live and monitor for issues.

    a. Monitor the target org for post-deployment issues and be prepared to respond quickly to problems.

11. Inform stakeholders of the deployment’s completion.

## Prepare Object Data for Deployment

Making sure that the data is clean, accurate, and formatted correctly smooths the transition from one environment to another. Use these guidelines to prepare your data for deployment.

1. **Data assessment**—Review the existing data structure, including all objects, fields, records, and relationships. Identify which data is relevant and must be deployed, including historical data that’s necessary for business operations or compliance.
2. **Data cleanup**—Remove unnecessary, outdated, and duplicate data from the source environment. Correct data inaccuracies, such as misspellings or incorrect field values. Standardize data formats. Archive or delete outdated or irrelevant data that doesn’t need to be deployed.
3. **Data validation**—Make sure that all data complies with the validation rules in the target environment. Check for mandatory fields and make sure that they’re populated with valid data.
4. **Data dependencies and relationships**—Map out the relationships between different datasets, such as parent-child relationships, lookups, and main-detail relationships. To maintain data integrity, plan the deployment order based on these dependencies. For example, deploy parent records before child records.
5. **Field mapping**—Create a field-mapping document that aligns the source fields with their corresponding target fields. Note transformations that must occur during the deployment process. For example, determine how to handle fields that don’t have a direct match.
6. **Record IDs and references**—Decide how to handle Salesforce record IDs, external IDs, and other unique identifiers. Ensure that the correct record IDs are used.
7. **Data formatting**—Format data to match the target system’s requirements, including dates, numbers, and strings. Ensure that multi-select picklist values, checkbox fields, and other special field types are formatted correctly.
8. **Data extraction**—Extract the data from Salesforce Commerce into a format suitable for deployment, typically CSV files. Ensure that the extraction process captures all necessary fields and records. To extract the data from the source environment, use a tool like Salesforce Data Loader.
9. **Data segmentation**—If the dataset is large, segment it into smaller, manageable batches. Segmentation can help with troubleshooting and reduces the risk of system performance issues during the deployment.
10. **Test deployment**—Perform a test deployment with a subset of the data in a full copy sandbox or developer sandbox. Address issues that arise during the test.
11. **Data backup**—Back up the data in both the source and target systems to ensure that you can restore the original state if necessary.
12. **Security and compliance**—To ensure that sensitive data is handled correctly during the deployment, review the security settings. Make sure that field-level security, sharing rules, and other security settings in the target environment allow for the proper visibility and access to the deployed data. Check that the deployment process complies with relevant data protection regulations.
13. **Deployment documentation**—Document the entire data preparation process, including field mappings, data dependencies, and special handling instructions. This documentation is valuable during the deployment and for any troubleshooting that is required afterward.
14. **Stakeholder communication**—Share the deployment documentation with all stakeholders for review and feedback, and update the documentation as needed..
15. **Final approval**—Obtain final approval from the project manager, data owner, and stakeholders. Ensure that all involved parties are informed about the deployment schedule and process.
16. **Detailed deployment plan**—Develop a comprehensive deployment plan that includes timelines, resources, roles, and responsibilities. Outline the order in which data is deployed, considering dependencies and relationships. Detail the sequence of migration steps, including data extraction, transformation, loading, and validation phases. Include contingency plans for handling potential issues during the deployment.
17. **Scheduling**—Plan the deployment during a period that minimizes impact on users, typically during off-peak hours or a scheduled maintenance window. Communicate the deployment schedule to all stakeholders and ensure that support staff are available during and after the deployment.
18. **Execution**—Monitor the deployment closely, logging all actions and issues that arise. Use the prepared documentation to guide the deployment and resolve issues.
19. **Post-deployment validation and testing**—Validate the data in the target system to ensure that it’s been loaded correctly and completely. Conduct thorough testing to confirm that the data works as expected within the new environment. To ensure that the deployed data meets user needs and expectations, involve end users in the validation process.
20. **Post-deployment issues**—Address issues identified during the validation and testing phase. Update the deployment documentation with changes made during this phase for future reference.

## Map Object Data Fields

Field mapping involves matching the source data fields to their corresponding target fields. Proper field mapping ensures that the data is imported correctly into the new system. Use these guidelines to prepare and complete field mapping.

1. Understand the source and target data models.

   - Familiarize yourself with the data schema of both the source and target systems. Identify the relevant objects and fields in the source system that correspond to the Salesforce objects.

2. List all fields from the source system, including custom and standard fields, that must be deployed. I
3. Identify the target fields.

   Determine the corresponding fields in Salesforce where the source data should reside. I

4. Create a mapping document.

   Use a spreadsheet or a data-mapping tool to create a field-mapping document. List source fields in one column and the corresponding target fields in another.

5. Map the fields.

   a. Begin with standard fields that have direct equivalents between the systems. For example, Product Name, Price, and SKU. For fields in the source system that don’t have a standard equivalent in Salesforce, determine if there are existing custom fields that you can use or if you need to create new custom fields.

   b. Map the custom fields. Make sure that equivalent fields exist in the target system or create them if necessary.

   c. Identify fields that require data transformation. For example, combine first and last name fields into a full name field, and convert date formats. Document the transformation rules and logic in the mapping document.

   d. Map complex relationships. Examine the relationships between records in the source data, such as parent-child links between products and categories or orders and customers. Ensure that these relationships are preserved in the target system by mapping the related fields correctly, such as lookup or main-detail fields in Salesforce. Plan the sequence of data loading to respect these relationships so that parent records are loaded before child records to maintain referential integrity.

   e. Make sure that the Salesforce data types can accommodate the data from the source fields. For example, for text, number, date, and field lengths, adjust the data or the Salesforce fields as necessary.

   f. Map default values.If the source system contains fields with default values that aren’t present in the data extract, specify these default values in the mapping document.

   g. Ensure that picklist and multi-select fields in the source system have equivalent values in Salesforce. Map or transform values as needed to fit the Salesforce environment.

   h. Handle unique identifiers. If the target system requires matching external IDs, map these fields to ensure that the data is included in the migration. Establish a method for generating new unique identifiers if they can’t be preserved or if the target system generates new ones upon data import.

   i. Set default values and null handling. Decide if empty or null source fields can be set to default values in the target system or left blank. Document the default values for fields that require them in the target system.

6. Validate field mappings with stakeholders. Make sure that all business requirements are met and that the data is usable in the target system. Adjust the mappings based on feedback and revalidate as necessary.

## Deploy Object Data with Salesforce Data Loader

Salesforce Data Loader bulk imports or exports data. Use it to insert, update, delete, or export B2B store object data from a source org to a target org. Use these guidelines to export and import data with Data Loader.

To download and install the Data Loader, go to [_https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/data_loader_intro.htm_](https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/data_loader_intro.htm).

1. Prepare object data.

   a. Ensure that the data in your sandbox is clean and ready for migration.

   b. Remove test data that you don’t want deployed to the target org.

   c. Identify data dependencies and relationships to ensure that related records are deployed together.

   d. Map the fields in your CSV file to the fields in Salesforce. See [_Define Data Loader Field Mappings_](https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/defining_field_mappings.htm).

   - Data Loader can auto-match fields by name, or you can manually map them.
   - Save your mapping to a file for future use if you plan to perform this operation regularly.

2. Export 0bject data from the source org to a CSV file.

   - See [_Export Data from Salesforce_](https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/exporting_data.htm).

3. Prepare the target org.

   a. Log in to your target org and ensure that all custom fields, objects, and dependencies are present and match the source configuration.

   b. Back up your target org data before importing new data.

4. Prepare the CSV files.

   a. Review the CSV files exported from the source org and make any necessary adjustments to the data, such as updating record IDs to match the target org or removing fields that aren’t needed. See Data Mapping.

   b. Ensure that the CSV files are properly formatted and encoded (UTF-8 is recommended).

   c. Make sure that the files have the necessary headers that correspond to the Salesforce field API names.

5. Test the import with a small dataset.

   a. Use Data Loader to import the test data into the target org. See [_Insert, Update, or Delete Data Using Data Loader_](https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/inserting_updating_or_deleting_data.htm).

   b. Import data in the correct order to maintain relationships, for example, import Accounts before Contacts.

   c. Verify that the test records are imported correctly and resolve any issues. See [_Review Data Loader Output Files_](https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/reviewing_output_files.htm).

6. Deploy the object data.

   - Data Loader supports batch mode operations from the Windows command line. See [_Run In Batch Mode (Windows Only)_](https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/loader_batchmode_intro.htm).

7. Verify the import.

   a. Review the Data Loader success and error files for which records were imported successfully and which weren’t.

   b. Investigate and resolve errors that occurred during the import. See [_Review Data Loader Output Files_](https://developer.salesforce.com/docs/atlas.en-us.dataLoader.meta/dataLoader/reviewing_output_files.htm).

8. Review the imported records.

   a. Log in to the target org and manually check the imported records to ensure that they are correct.

   b. Validate that relationships between records (like parent-child relationships) are intact.

   c. Perform any necessary post-import adjustments in the target org.

9. Test the migration.

   a. Make sure that the imported data works correctly within the target org.

   b. Test all related processes, workflows, and integrations.

<!-- document id=0f5b1936ee21ea8bb0efc51e8a03b061c10a4db9e32f0d4808db2e8baac2e411 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-deploy-store-metadata.md -->

# Deploy Store Metadata to a Target Org

The store metadata defines the store functionality.

## Deploying Store Metadata

Before you deploy metadata, review these Salesforce Developer topics:

- [_Metadata Components and Types_](https://developer.salesforce.com/docs/atlas.en-us.250.0.api_meta.meta/api_meta/meta_objects_intro.htm)
- [_Understanding Metadata API_](https://developer.salesforce.com/docs/atlas.en-us.250.0.api_meta.meta/api_meta/meta_intro.htm)
- [_Deploying and Retrieving Metadata_](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/file_based.htm)
- [_Salesforce CLI Command Reference_](https://developer.salesforce.com/docs/atlas.en-us.250.0.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm)

## Store Metadata Deployment Checklist.

- Extract the store metadata from the source org. You can use Salesforce DX, Metadata API, DevOps Center, or change sets. DevOps Center provides a better and more collaborative experience to manage change sets.
- Deploy the store metadata to the target org, and perform any necessary post-deployment configuration.
- Test the store metadata deployment in the target org. Make sure that all components are working as expected.
- Prepare the Experience Bundle. Package the components of the Experience Bundle metadata, which can include Visualforce pages, Lightning components, Apex classes, and static resources.
- Test the experience metadata deployment in the target org.
- Deploy the Experience Bundle Metadata: Deploy the experience components to the target org.
- Test the entire B2B store experience in the target org to confirm that everything functions as expected.

## Deploy Store Metadata with Change Sets

You can deploy Store and Experience metadata using change sets in the Commerce app. Deploy the Store metadata first, and then the Experience metadata.

Follow the steps outlined in [_Migrate Your Store Configuration_](https://help.salesforce.com/s/articleView?id=commerce.comm_migrate_store.htm&type=5). Make sure that you configure the source and target [_deployment connections_](https://help.salesforce.com/s/articleView?id=platform.changesets_about_connection.htm&type=5), and select [store.org](http://store.org/) as the store component type.

## Deploy Store Metadata with Salesforce Metadata API, Salesforce CLI, and Salesforce DX

Use the Salesforce Extensions for Visual Studio Code on Salesforce CLI to access Metadata API commands. The Salesforce Extensions for Visual Studio Code include tools for developing on the Salesforce platform in the lightweight, extensible VS Code editor. These tools provide features for working with development orgs (scratch orgs, sandboxes, and DE orgs), Apex, Aura components, and Visualforce.

Salesforce CLI is ideal if you use scripting or the command line for moving metadata between a local directory and a Salesforce org. For more information, see [_Salesforce Tools and Toolkits_](https://developer.salesforce.com/tools).

Here’s a high-level overview of how you can use Metadata API to deploy metadata from a source environment to a target environment. Your deployment requirements are unique to your organization and your approach can differ from these guidelines.

The command syntax for the CLI can differ. See the [_Salesforce CLI Command Reference_](https://developer.salesforce.com/docs/atlas.en-us.250.0.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_top.htm) for the most up-to-date information. Additionally, because the CLI is under active development, features and commands can change. Salesforce recommends you consult the latest Salesforce release notes or documentation for guidance on using the CLI for Salesforce Commerce metadata migration.

1. Log in to your source and target orgs to authenticate.
2. Back up your target org’s metadata and data before making changes.
3. Retrieve metadata from the source org.
   a. Identify the metadata components to deploy.
   b. Create a`package.xml` manifest file that lists the components.
   c. To retrieve the metadata, use the `sf project retrieve start` command with the —target-metadata—dir flag.

Example: `sf project retrieve start --target-org SandboxAlias –-metadata CustomObjects -dir ./custom_objects --package-xml ./package.xml`

4. Deploy metadata to the target org using the `sf project deploy start` command.
   a. Example: `sf project deploy start --target-org ProdAlias --source-dir ./custom_objects`
5. Monitor the deployment. Use the `sf project deploy validate` command.
   a. Perform post-deployment steps, such as data deployment or additional configuration in the target org.
   b. To ensure that everything works as expected, test your B2B Commerce store in the target org.

It’s important to establish a DevOps Center strategy that fits your organization’s requirements and to adopt tools that integrate well with your existing development workflow and deliver updates to users with minimal disruption.

<!-- document id=3a7943c188f8c9c5924269d618c1061f3c586fb5acadf1a00336e59c69eefcf1 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-push-mrt-auto.md -->

# Deploy Storefront Next to Managed Runtime (MRT)

To redeploy a storefront that was created in Business Manager after initial deployment, use the Storefront Next CLI and the autocreated MRT project and environment.

## Prerequisites

- Node Package Manager (pnpm) version 10.28.0 or later. See [Installation](https://pnpm.io/installation) on the pnpm site.
- Node.js version 24.13.0 or later. See [Download Node.js](https://nodejs.org/en/download) on the Node.js site.
- To install Storefront Next dependencies specified in `package.json`, run the `pnpm install` command.
- To save the MRT API key credentials using the B2C CLI, install the B2C CLI. See [Agentic B2C Developer Toolkit](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/).

## Steps

1. In Business Manager, navigate to your storefront. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png), then select **Administration > Sites > Storefronts**, and click your storefront.
2. In the storefront detail page, click your environment, and then next to Deployments, click **Manage**.
3. If you have an `.env` file in your storefront with the project ID (`MRT_PROJECT`) and environment ID (`MRT_TARGET`), skip this step. Otherwise, get these values from [Runtime Admin](https://runtime.commercecloud.com/).

   a. To get the environment ID, click **Environment Settings**, and copy the Environment ID value.

   b. To get the project ID, click the project name, then **Project Settings**, and copy the Project ID value.

4. To authenticate the CLI to Managed Runtime, use an API key. Get the Managed Runtime API key in Managed Runtime Admin. In Account Settings, under Personal API Key:

   a. If you haven't yet created an API key, click **Generate**.

   b. If you already have an API key, the value is partially masked. Click **Reset**, then click **Reset my API Key** when asked for confirmation.

   c. Run this command to save the API key locally in the `~/.mobify` file so it can be reused whenever you run the `pnpm sfnext push` command. Replace the placeholder values in this command before running it.

   ```
   b2c mrt save-credentials --user {your-email@example.com} --api-key {your-mrt-api-key}
   ```

   **note:** We recommend saving the MRT API key credentials. If you don't save the MRT API key, you can add the API key in the `MRT_API_KEY` variable in the `.env` file or supply it in the `--api-key` argument on the command line. See [MRT API Key](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html#mrt-api-key) in the Agentic B2C Developer Toolkit.

5. From your local storefront folder, use this command to create a bundle and deploy it to your Managed Runtime environment. Replace the placeholders with the MRT project ID, target environment, and the API key you got earlier.

   ```
   pnpm sfnext push --project {mrt-project-id} --environment {target-env}
   --message "Deploying quick start bundle."
   ```

   **tip:** Always run `pnpm sfnext push` from the local storefront folder. To run the push command from another folder outside your storefront, use `pnpm dlx @salesforce/storefront-next-dev push` instead and pass in the storefront folder path with `--project-directory {sfnext-project-folder}`.

   **note:** The `.env` file in your Storefront Next project folder contains environment variables that the Storefront Next CLI uses. You can set the project ID in the `MRT_PROJECT` variable and the target environment in the `MRT_TARGET` variable. If you specify these values in both the command line and the `.env` file, the command line arguments are used.

6. Verify that the bundle was deployed to the target environment. In Managed Runtime Admin, in Projects, click your project and then your environment.

## Deploy Bundles in Business Manager (Beta)

If your B2C org is enrolled in the Developer Workspace beta, deploy new bundles from Business Manager and track the deployment progress and history. Before deploying a bundle, create it by following the steps in this page. Omit the `--environment` argument to skip bundle deployment and only upload it. Also, make sure tho remove the `MRT_TARGET` variables from the `.env` file.

To upload a bundle, use either of these commands. Find the project ID in the downloaded `.env` file from the storefront detail page in Business Manager, or in the Complete Your Storefront task.

```
pnpm sfnext push --project {mrt-project-id} --message "Deploying quick start bundle."
```

Alternatively, use the B2C CLI to upload a bundle. With the B2C CLI commands, you can choose SCAPI and use SCAPI authentication with the `--mrt-backend` argument. For more information about setting up the B2C CLI, see [Automate Storefront Administration Tasks with the B2C CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-cli.md).

```
npx @salesforce/b2c-cli mrt bundle upload-v2  -p {mrt-project-id} --message "Deploying quick start bundle."
```

Next, deploy the bundle to an environment in Business Manager in **Administration > Storefronts > _Your Storefront_ > Bundles**.

![The deployed bundle is displayed in the target environment page](https://developer.salesforce.com/docs/media/sfnext/sfnext-bundles.png '{"class": "image-xl"}')

## Create and Deploy Bundles via the B2C CLI

Use the `mrt bundle` commands to create and deploy bundles to an environment. See [Automate Storefront Administration Tasks with the B2C CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-cli.md).

## See Also

- [CLI Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-cli.md)
- [Agentic B2C Developer Toolkit: Storefront Next](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/storefront-next.html)
- [Agentic B2C Developer Toolkit: Resolution Priority](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html#resolution-priority)
- [Manage the Storefront Development Workflow in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-developer-workspace.md)

<!-- document id=f2ea2a09c9643f664f1fe60100917f2b8d685144d4eb555a86457a93ca09bdcb url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pd-deploy-cartridge.md -->

# Deploy the Storefront Next Cartridge for Page Designer

Deploy the cartridge that contains Page Designer metadata for Page Designer pages after the initial storefront setup in Business Manager with local code. Also, every time you modify Page Designer components or add pages, deploy the Storefront Next cartridge to upload Page Designer metadata to the B2C Commerce instance.

**note:** The initial storefront setup with a GitHub repository deploys the Storefront Next cartridge via a GitHub action. There is no need to manually deploy the cartridge. Only if you modify Page Designer items, deploy the cartridge to update the Page Designer metadata.

## Prerequisites:

- A developer B2C Commerce instance or on-demand sandbox (ODS) instance.
- A Storefront Next project that you created locally on your system after the storefront setup in Business Manager. See [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md) or [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md).
- The B2C CLI. See [Installation](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/installation.html) in the Agentic B2C Developer Toolkit.

To deploy the Storefront Next cartridge:

1.  To configure the B2C Commerce credentials, use the `.env` file or the `dw.json`. Do one of these steps.

    a. In the `.env` file that's part of your Storefront Next local storefront project folder, add these variables.

    ```
    SFCC_SERVER="{sandbox-hostname}"
    SFCC_CODE_VERSION="version1"
    SFCC_CLIENT_ID="Account-Manager-client-ID"
    SFCC_CLIENT_SECRET="Account-Manager-client-secret"
    ```

    b. Alternatively, create the `dw.json` file in your Storefront Next local project folder. Add this content.

    ```
    {
      "hostname": "{sandbox-hostname}",
      "code-version": "version1",
      "username": "{sandbox-username}",
      "password": "{access-key}"
    }
    ```

    **note:** For more information about the B2C Commerce configuration files, see [Configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html) in the Agentic B2C Developer Toolkit.

2.  Replace the hostname and code version placeholders with valid values.

    a. `{sandbox-hostname}` with the domain of your sandbox or developer instance.

    b. Get your active code version from **Administration > Site Development > Code Deployment**. Replace `version1` with your active version, if different.

3.  If you're using the `.env` file, replace the Account Manager client ID and client secret placeholders. If you created the storefront in Business Manager, get the Account Manager client ID and client secret from the downloaded credentials file. Otherwise, get them from Account Manager.

4.  If you're using the `dw.json` file:

    a. Replace `{sandbox-username}` with your sandbox user name, which is in email format.

    b. Generate your access key in Business Manager. See [Create an Access Key for Logins for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_access_keys_for_business_manager.htm&type=5) in _Saleforce Help_.

    c. Copy the access key and replace `{access-key}` with it.

5.  Generate and deploy the Storefront Next cartridge by running these commands. You don't need to specify the cartrige path. The cartridge is in the `cartridges/app_storefrontnext_base` folder.

    ```
    pnpm cartridge:generate
    pnpm cartridge:deploy
    ```

    The cartridge deployment adds the metadata of Page Designer pages and components to your B2C Commerce instance.

## Automatic Cartridge Sync with the VS Code Extension

The B2C Commerce VS Code extension supports deploying cartridges from within VS Code and automatic upload on file changes. Enable code watch to upload cartridge changes to your sandbox as you save files, or use the extension's upload commands for manual deployment. For more information, see [Salesforce B2C Commerce VS Code Extension](https://salesforcecommercecloud.github.io/b2c-developer-tooling/vscode-extension/) and [Cartridge Management and Code Watch/Upload](https://salesforcecommercecloud.github.io/b2c-developer-tooling/vscode-extension/#cartridge-management-and-code-watch-upload).

<!-- document id=d3347671032788344e3d9197cbdc440948aa1d5b617b456fd6504b42923a57bc url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pushing-and-deploying-bundles.md -->

# Deploy Your Code

To run your commerce application on Managed Runtime, you must first push a code bundle and deploy it to a target environment.

**note:** You can also upload and deploy bundles with the B2C CLI or SCAPI.
For a complete list of the `mrt bundle` deployment commands, see [Bundle Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html#bundle-commands). To set up and configure authorization for the B2C CLI, see [Set Up the B2C CLI](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-mrt-cli.md#set-up-the-b2c-cli).
For more information about the SCAPI deployment endpoints, see [Automate Storefront Administration with APIs](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-mrt-api.md).

In this example, the bundle is created and deployed for the specified project ID and environment.

```
npx @salesforce/b2c-cli mrt bundle deploy -p {mrt-project-id} -e {target-env} --message "Test Release"
```

This guide shows you how to:

- Set up your API key.
- Use a command-line script to push a bundle to Managed Runtime.
- Use the Runtime Admin web application to deploy a bundle to the production environment.

**important:** Before you can use Managed Runtime and Runtime Admin, ask your B2C Commerce administrator to add one of these roles to your account in Account Manager: **Managed Runtime User** or **Managed Runtime Admin**.


## Save Your Credentials

**note:** If you already have a `.mobify` file in your home directory, you can skip this section.

Before you can push a bundle, you must first authorize your computer.

Start the authorization process by looking up your personal API key:

1.  Log in to [Runtime Admin](https://runtime.commercecloud.com/).
2.  Click the user profile icon (top right) and click [Account Settings](https://runtime.commercecloud.com/account/settings).
3.  Scroll down to the section called **API Key** and look for **Personal API Key.**
    - If you haven't yet created an API key, click the **Generate** link.
    - If you already have an API key, click the **Reset** link and click **Reset my API Key** when asked for confirmation.
4.  Copy the command to use your API key.
    For more information, see [Managed Runtime API Key](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.html#managed-runtime-api-key) in the Agentic B2C Developer Toolkit.

_For security, when you return to the Account Settings page, the API key isn’t displayed in full, so you must reset it to copy the full text of the API key again._

From the command line, go to your PWA Kit project directory and run the command that you copied.

Run the command again on any other computers that you want to use for pushing bundles.

## Push a Bundle

Pushing a bundle involves running a script that packages up your code into a Webpack bundle and uploads it to the Runtime Manager.

**important:** Instead of deploying a bundle using the command line, use SCAPI. See [B2C Commerce API: Deployments](https://developer.salesforce.com/docs/commerce/commerce-api/references/deployments?meta=Summary).

### Verify Project Configuration

Before pushing your first bundle, verify that the `package.json` file in your PWA Kit project directory is configured correctly:

1.  Log in to [Runtime Admin](https://runtime.commercecloud.com/).
2.  Click the name of your project.
3.  From the left navigation, click **Project Settings**.
4.  Copy the **Project ID** string. Example: `my-project`.
5.  Paste it into the `name` field in `package.json.`

### Configure Environment Proxies

To ensure that your bundle works correctly when deployed, you must [set your proxies on your environment in Runtime Admin](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md#configure-managed-runtime-environments).

### Configure Environment Variables

If you are using a SLAS private client, you must set the client secret via an [environment variable](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md#set-environment-variables).

**note:** Projects generated from PWA Kit 3.5 and above will be configured to use a SLAS private client by default.

To learn more about using SLAS private clients, see [Using A Slas Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md).

### Run the Push Script

To push a bundle, go to the command line and run the following command from your project directory:

```bash
npm run push -- -m "Message to help you recognize this bundle"
```

For a list of other options you can supply to the push script, run `npm run push -- --help`.

## Troubleshoot Bundle Push Errors

When a bundle is successfully pushed, the message `Beginning upload…` appears in the terminal followed by the message `Bundle Uploaded!`.

If something went wrong, look for one three possible error messages (based on HTTP response status codes) in your terminal after the `Beginning upload…` message.

Here’s how to troubleshoot each error message.

### HTTP 404 Error

An `HTTP 404` error is returned in the terminal when a project does not exist with the name specified in `package.json` or when you are not authorized to change the project.

To fix the error:

1.  Repeat the steps to push a bundle and make sure that the email address and API key settings you pass to the push script match the settings in Runtime Admin.
2.  Verify that your project appears on the Runtime Admin home page under **Projects**.
    - If your project does not appear, contact support to make sure that the project has been created and that you have been granted access to it as a team member
3.  Open the project on Runtime Admin.
4.  From the left navigation, click **Project Settings**.
5.  Copy the **Project ID** string. Example: `my-project`.
6.  Open the `package.json` inside your project directory.
7.  Verify that the values for `name` and `projectSlug` both match the project ID string that you copied.

### HTTP 401 Error

An `HTTP 401` error is returned in the terminal when you do not have permission to push bundles. To fix this error, contact your B2C Commerce Account Manager administrator and ask to have your permission elevated to include pushing bundles.

### HTTP 413 Error

An `HTTP 413` error is returned in the terminal when your bundle is too large. The maximum size for bundles is 400 MB and the maximum size of all `ssr_only` and `ssr_shared` files within the bundle is 247 MB. To fix this error, check the size of your bundle by inspecting the build folder within your project. If your project is nearing the maximum size or has already exceeded it, here’s what you can do to reduce it:

- Remove unused assets
- Remove unnecessary assets
- Scale down images

After reducing the size of your project files, try pushing the bundle again.

### HTTPS Errors

HTTPS errors can occur when your local computer or network proxies like a corporate VPN or firewall have not been configured to communicate with Managed Runtime's API, hosted at cloud.mobify.com.

These errors may include messages like `unable to get local issuer certificate` or `self signed certificate in certificate chain`.

To resolve these errors, work with your corporate IT team to configure your Node.js installation for your corporate network environment.

## Deploy a Bundle

After you’ve successfully pushed a bundle, you can deploy it to a target environment.

For any site that uses PWA Kit and Managed Runtime, you can only designate **one bundle at a time** as deployed for each environment. By default, every project comes with a single environment, called `production`. You can create more environments using Runtime Admin or the Managed Runtime API.

To deploy a bundle:

1.  Log in to [Runtime Admin](https://runtime.commercecloud.com/).
2.  Click the name of your project.
3.  Under **Environments**, click the name of the environment that you want to deploy to (example: **Production**).
4.  Under **Bundles**, click the **Deploy** button next to the bundle.
5.  Click **Confirm Deploy**.
6.  Wait until the deployment is complete.

When deployment has successfully completed, the bundle appears underneath the heading **Deployed Bundle**.

**note:** For your first deployment to a new environment, the process can take up to an hour to complete. Subsequent deployments take around a minute, unless changes to the CDN are required. A CDN change takes around 15 minutes and is required when the deployment contains changes to the request processor or proxy configuration.

<!-- document id=3ca936516ac507e130c239822f63aabf45ee06e470aac6f9e185b572ec264ea5 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-deployments.md -->

# Deploy Your Storefront from Business Manager (Beta)

In Business Manager, upload bundles, deploy them to your Managed Runtime environments, and track deployment progress.

**important:** Developer Workspace is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

## Prerequisites

- A B2C Commerce account with the "Storefront Deployments" permission for the target storefront.
- At least one environment configured for your storefront. See [Manage Your Environments in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-environments.md).
- A built storefront bundle. To create a bundle, see [Manage Deployments in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md#manage-deployments-in-business-manager-beta).

## View and Manage Bundles

1. In Business Manager, go to **Administration > Storefronts > _Your Storefront_**.
2. Click **Bundles**.

The **Bundles** page lists the bundles, including the bundle name, creation date, and the environment where the bundle is deployed.

From the **Bundles** page:

- Deploy a bundle.
- Delete a bundle.
  **note:** Deleting a bundle that's deployed doesn't affect the running environment. The environment continues to serve the deployed bundle until a new deployment replaces it.
- Download a bundle. Click the dropdown menu next to the bundle, and then select **Download**.
- Copy a bundle ID. Click the dropdown menu next to the bundle, and then select **Copy Bundle ID**.
- Filter the deployments list by status. Click the status picklist, and then select a status, such as `Failed`.

![Bundles tab for a storefront](https://developer.salesforce.com/docs/media/sfnext/sfnext-bundles.png '{"class": "image-xl"}')

When you deploy a bundle, the page shows deployment progress in real time. The page keeps updating until the deployment completes or fails.

**note:** Deployments run in the background. Leave the page, and then return to the environment page to check the status.

## View Deployment History

To view deployment history for the storefront, click **Activity**. The **Deployments** page lists past and current deployments, including the deployed bundle, the user who started it, and the outcome. Filter deployment activity by date range, deployment status, or user.

## Deployment Notifications

Set up deployment email notifications in Runtime Admin. See [Deployment Notifications](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md) in the _Composable Storefront Guide_.

## Next Steps

- [Launch Your Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-launch-storefront.md)

<!-- document id=8325bedd64ad1ddada914d343b70fb92eca72d7e5e6d55ee366af12880f78d34 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-deployment.md -->

# Deployment Differences with PWA Kit

PWA Kit uses Webpack with a single-command deployment that can auto-build. Storefront Next uses Vite with React Router 7, requiring separate build and push steps but providing more granular control over bundle sizes. Both deploy to the same Managed Runtime infrastructure, but Storefront Next offers more sophisticated bundle analysis and chunk splitting strategies for better performance optimization.

## Key Differences

| Aspect        | PWA Kit                 | Storefront Next      |
| ------------- | ----------------------- | -------------------- |
| Build Tool    | Webpack                 | Vite + React Router  |
| Build Command | `pwa-kit-dev build`     | `react-router build` |
| Push Command  | `pwa-kit-dev push`      | `sfnext push`        |
| Analysis Tool | Webpack Bundle Analyzer | Rollup Visualizer    |
| Config Format | JavaScript              | TypeScript           |

## Build Output

PWA Kit:

```
build/
├── main.js          (max 84 kB)
├── vendor.js        (max 335 kB)
├── ssr.js
└── static/
```

Storefront Next:

```
build/
├── client/
│   └── assets/
│       ├── -root.*.js           (max 110 kB)
│       ├── locales-en-US.*.js   (auto-split)
│       └── (component).*.js     (max 50 kB each)
├── server/
│   └── *.js                     (max 5 MB total)
└── static/
```

## Bundle Size Strategy

PWA Kit:

```json
// Two main bundles with global limits
"bundlesize": [
    {"path": "build/main.js", "maxSize": "84 kB"},
    {"path": "build/vendor.js", "maxSize": "335 kB"}
]
```

Storefront Next:

```json
// Granular per-chunk limits
"bundlesize": {
    "client": [
        {"name": "commerce-sdk-*", "limit": "454 kB"},
        {"name": "-root.*", "limit": "110 kB"},
        {"name": "**/*", "limit": "50 kB"}  // Default
    ]
}
```

## Deployment Process

PWA Kit:

```bash
npm run build        # Build first
npm run push         # Then deploy
# OR
pwa-kit-dev push     # Auto-builds if needed
```

Storefront Next:

```bash
pnpm build           # Build first
pnpm push            # Deploy built bundle
# Separate steps required
```

## Key Similarities

1. MRT Target: Both deploy to Managed Runtime.
2. Credentials: Same `~/.mobify` file format.
3. Node.js Version: Both use Node.js 22.x.
4. SSR Parameters: Same configuration structure.
5. Proxy Config: Same proxy path patterns.

## Storefront Conversion Considerations

1. Build Process

   - Replace `npm run build` with `pnpm build`.
   - Update CI/CD scripts for new commands.

2. Bundle Size Monitoring

   - Convert bundlesize config to new format.
   - Add granular chunk limits.

3. Deployment Scripts

   - Update from `pwa-kit-dev push` to `sfnext push`.
   - Ensure build runs before push.

4. Configuration Files
   - Migrate SSR config to `config.server.ts`.
   - Update environment variable format.

<!-- document id=aabdd459e56a24623bd7f129aaabf45a888c5fa98a61793f4e2868c9359e3102 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/deployments.md -->

Deployments

# Deployments

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/storefront/deployments-oas-v1-public.yaml)

## API Overview

The Deployments API provides SCAPI-native access to bundle and deployment management for Composable Commerce storefronts running on Managed Runtime (MRT).

*   **Bundles** — upload and list versioned SSR application packages for a storefront.
*   **Deployments** — trigger, list, and monitor deployments of bundles to storefront environments.

### Authentication & Authorization

Requests are authenticated with Account Manager OAuth 2.0 bearer tokens (`AmOAuth2`). Access is governed by the Deployments API scopes: `sfcc.storefront.deployments` grants read-only access, and `sfcc.storefront.deployments.rw` grants read and write access. Read operations (`GET`) accept either scope; write operations (`POST`) require `sfcc.storefront.deployments.rw`.

**Version:** 1.0.5

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/storefront/deployments/v1`
    *   `shortCode (default 123456gf)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.storefront.deployments: Read-only access to the Deployments API.
    *   Scope sfcc.storefront.deployments.rw: Read and write access to the Deployments API.
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.storefront.deployments: Read-only access to the Deployments API.
    *   Scope sfcc.storefront.deployments.rw: Read and write access to the Deployments API.

## Operations

### GET Get bundles for a storefront.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/bundles`

Operation ID: `getBundlesForStorefront`. Security: AmOAuth2 (sfcc.storefront.deployments, sfcc.storefront.deployments.rw).

Retrieves a paginated list of bundles uploaded to the specified storefront.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** List of bundles successfully retrieved.
    
    Media type: `application/json`. Schema: `BundleResult`.
    
    _Example: BundleListSuccess_ Successful bundle list result
    
    Example of a successful response returning a paginated list of bundles for a storefront.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 3,
      "data": [
        {
          "bundleId": 170,
          "description": "my bundle",
          "status": "ok",
          "lifecycleStatus": "active",
          "createdBy": "dev@example.com",
          "creationDate": "2026-04-08T21:47:28.188965Z",
          "lastModified": "2026-04-08T21:47:31.307595Z",
          "type": "ssr",
          "ssrParameters": {
            "runtime": "24.x",
            "runtimeDescription": "NodeJS 24.x",
            "envBasePath": "ca"
          },
          "inUseBy": [
            "production"
          ],
          "streamingEnabled": true
        },
        {
          "bundleId": 169,
          "description": "previous release",
          "status": "ok",
          "lifecycleStatus": "active",
          "createdBy": "dev@example.com",
          "creationDate": "2026-04-07T15:30:00.000000Z",
          "lastModified": "2026-04-07T15:30:05.000000Z",
          "type": "ssr",
          "ssrParameters": {
            "runtime": "24.x",
            "runtimeDescription": "NodeJS 24.x",
            "envBasePath": "ca"
          },
          "inUseBy": [],
          "streamingEnabled": false
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### POST Upload a bundle for a storefront.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/bundles`

Operation ID: `uploadBundleForStorefront`. Security: AmOAuth2 (sfcc.storefront.deployments.rw).

Uploads a bundle archive (uncompressed or gzip-compressed .tar file), which must not exceed 400 MB. Bundle configuration is derived from a configuration file inside the archive. Sent as `multipart/form-data`: the archive travels in the `bundle` part, with the remaining request metadata as sibling form fields.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront`.

#### Request body (required)

Media type: `multipart/form-data`. Schema: `BundleUploadRequest`.

_Example: BundleUpload_ Bundle upload with metadata

The `bundle` part carries the binary archive; the remaining parts carry the request metadata.

```
{
  "bundle": "<binary .tar.gz archive, e.g. storefront-bundle.tar.gz>",
  "message": "Release 2.1.0",
  "rootDir": "bld",
  "configPath": ".mrt/config.json",
  "matchMode": "strict"
}
```

#### Responses

*   **201** Bundle successfully uploaded.
    
    Media type: `application/json`. Schema: `BundleUploadResponse`.
    
    _Example: BundleUploadSuccess_ Successful bundle upload
    
    Example of a successful response after uploading a bundle.
    
    ```
    {
      "bundleId": 170,
      "warnings": [],
      "matches": {
        "ssrOnly": [
          "ssr.js",
          "worker.js"
        ],
        "ssrShared": [
          "shared.js",
          "utils.js"
        ]
      }
    }
    ```
    
*   **400** Bad Request. The uploaded bundle failed validation.
    
    Media type: `application/problem+json`. Schema: `BundleValidationFailedErrorResponse`.
    
    _Example: BundleValidationFailedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bundle-validation-failed",
      "detail": "We couldn't validate the bundle for these reasons: missing entry point",
      "title": "Bundle Validation Failed"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get deployments for an environment.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/deployments`

Operation ID: `getDeploymentsForEnvironment`. Security: AmOAuth2 (sfcc.storefront.deployments, sfcc.storefront.deployments.rw).

Retrieves a paginated list of deployments for the specified environment.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront`.
*   `environmentId` (path, string, required) The environment identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** List of deployments successfully retrieved.
    
    Media type: `application/json`. Schema: `DeploymentResult`.
    
    _Example: DeploymentListSuccess_ Successful deployment list result
    
    Example of a successful response returning a paginated list of deployments for an environment.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 1,
      "data": [
        {
          "deploymentId": "b035a4d7-ec6b-4dcd-af8f-3a847b10fed8",
          "status": "finished",
          "deploymentType": "publish",
          "creationDate": "2026-04-08T21:47:31.322339Z",
          "lastModified": "2026-04-08T21:51:55.692688Z",
          "duration": 76.867967,
          "createdBy": "dev@example.com",
          "statusMessage": "Deploy Finished",
          "progress": null,
          "bundle": {
            "bundleId": 170,
            "description": "my bundle",
            "status": "ok",
            "lifecycleStatus": "active",
            "createdBy": "dev@example.com",
            "creationDate": "2026-04-08T21:47:28.188965Z",
            "lastModified": "2026-04-08T21:47:31.307595Z",
            "type": "ssr",
            "ssrParameters": {
              "runtime": "24.x",
              "runtimeDescription": "NodeJS 24.x",
              "envBasePath": "ca"
            },
            "inUseBy": [
              "production"
            ],
            "streamingEnabled": true
          }
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### POST Create a deployment for an environment.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/deployments`

Operation ID: `createDeploymentForEnvironment`. Security: AmOAuth2 (sfcc.storefront.deployments.rw).

Triggers a new deployment of a bundle to the specified environment. Returns immediately with a deployment resource in a queued status. Poll the deployment by ID to track progress.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront`.
*   `environmentId` (path, string, required) The environment identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production`.

#### Request body (required)

Media type: `application/json`. Schema: `DeploymentCreateRequest`.

_Example: CreateDeployment_ Create a deployment

Trigger a deployment of a bundle to an environment by its bundleId.

```
{
  "bundleId": 170
}
```

#### Responses

*   **202** Deployment successfully queued.
    
    Media type: `application/json`. Schema: `Deployment`.
    
    _Example: DeploymentCreatedSuccess_ Successful deployment creation
    
    Example of a successful response when a new deployment is triggered (202 Accepted).
    
    ```
    {
      "deploymentId": "b035a4d7-ec6b-4dcd-af8f-3a847b10fed8",
      "status": "queued",
      "deploymentType": "publish",
      "creationDate": "2026-04-08T21:47:31.322339Z",
      "lastModified": "2026-04-08T21:47:31.322339Z",
      "duration": null,
      "createdBy": "dev@example.com",
      "statusMessage": "Queueing Bundle",
      "progress": null,
      "bundle": {
        "bundleId": 170,
        "description": "my bundle",
        "status": "ok",
        "lifecycleStatus": "active",
        "createdBy": "dev@example.com",
        "creationDate": "2026-04-08T21:47:28.188965Z",
        "lastModified": "2026-04-08T21:47:31.307595Z",
        "type": "ssr",
        "ssrParameters": {
          "runtime": "24.x",
          "runtimeDescription": "NodeJS 24.x",
          "envBasePath": "ca"
        },
        "inUseBy": [
          "production"
        ],
        "streamingEnabled": true
      }
    }
    ```
    
*   **400** Bad Request. The deployment request body is invalid.
    
    Media type: `application/problem+json`. Schema: `InvalidDeploymentRequestErrorResponse`.
    
    _Example: InvalidDeploymentRequestErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-deployment-request",
      "detail": "The deployment request body is invalid. A valid bundleId is required.",
      "title": "Invalid Deployment Request"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The bundle referenced by the deployment request was not found for this storefront.
    
    Media type: `application/problem+json`. Schema: `BundleNotFoundErrorResponse`.
    
    _Example: BundleNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bundle-not-found",
      "detail": "We couldn't find bundle 999.",
      "title": "Bundle Not Found"
    }
    ```
    
*   **409** The deployment cannot proceed because another deployment or deletion is already in progress for this environment.
    
    Media type: `application/problem+json`. Schema: `DeploymentConflictErrorResponse`.
    
    _Example: DeploymentConflictErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/deployment-conflict",
      "detail": "You can't request a deployment when another deployment or deletion is in progress.",
      "title": "Deployment Conflict"
    }
    ```
    

### GET Get a deployment by ID.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/deployments/{deploymentId}`

Operation ID: `getDeploymentById`. Security: AmOAuth2 (sfcc.storefront.deployments, sfcc.storefront.deployments.rw).

Retrieves the details of a specific deployment, including its current status and progress.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront`.
*   `environmentId` (path, string, required) The environment identifier. Must consist only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production`.
*   `deploymentId` (path, string (uuid), required) The deployment identifier.  
    Example: `b035a4d7-ec6b-4dcd-af8f-3a847b10fed8`.

#### Responses

*   **200** Deployment successfully retrieved.
    
    Media type: `application/json`. Schema: `Deployment`.
    
    _Example: DeploymentSuccess_ Successful deployment retrieval
    
    Example of a successful response returning a single deployment with all properties.
    
    ```
    {
      "deploymentId": "b035a4d7-ec6b-4dcd-af8f-3a847b10fed8",
      "status": "finished",
      "deploymentType": "publish",
      "creationDate": "2026-04-08T21:47:31.322339Z",
      "lastModified": "2026-04-08T21:51:55.692688Z",
      "duration": 76.867967,
      "createdBy": "dev@example.com",
      "statusMessage": "Deploy Finished",
      "progress": {
        "description": "Finished deployment",
        "percentage": 100
      },
      "bundle": {
        "bundleId": 170,
        "description": "my bundle",
        "status": "ok",
        "lifecycleStatus": "active",
        "createdBy": "dev@example.com",
        "creationDate": "2026-04-08T21:47:28.188965Z",
        "lastModified": "2026-04-08T21:47:31.307595Z",
        "type": "ssr",
        "ssrParameters": {
          "runtime": "24.x",
          "runtimeDescription": "NodeJS 24.x",
          "envBasePath": "ca"
        },
        "inUseBy": [
          "production"
        ],
        "streamingEnabled": true
      }
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The requested deployment was not found.
    
    Media type: `application/problem+json`. Schema: `DeploymentNotFoundErrorResponse`.
    
    _Example: DeploymentNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/deployment-not-found",
      "detail": "We couldn't find that deployment.",
      "title": "Deployment Not Found"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### BundleResult

Paginated result containing a list of bundles.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Bundle_, required) List of bundles.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### BundleUploadRequest

Request body to upload a bundle, sent as `multipart/form-data`. The archive travels in the `bundle` part, with the remaining request metadata as sibling form fields.

*   `bundle` (_string (binary)_, required) Bundle archive (uncompressed or gzip-compressed .tar file). The uploaded archive must not exceed 400 MB.  
    Example: `<binary .tar.gz archive, e.g. storefront-bundle.tar.gz>`.
*   `message` (_string_) Bundle description (optional metadata).  
    Maximum length: 2048. Example: `Release 2.1.0`.
*   `rootDir` (_string_) Root directory within bundle archive. Files in this directory are used for server-side rendering, published as static assets, or both. Any files in the bundle archive outside of this directory are ignored.  
    Default: `bld`. Maximum length: 256. Example: `bld`.
*   `configPath` (_string_) Path (relative to root directory) of bundle configuration file.  
    Default: `.mrt/config.json`. Maximum length: 256. Example: `.mrt/config.json`.
*   `matchMode` (_string_) Determines how files in the bundle configuration are matched. If `strict`, all files listed in `ssrOnly` and `ssrShared` fields in the bundle configuration must be present. If `ignore_missing`, missing files in the `ssrOnly` and `ssrShared` fields are ignored.  
    Allowed values: `strict`, `ignore_missing`. Default: `strict`. Example: `strict`.

### BundleUploadResponse

Response returned after a successful bundle upload.

*   `bundleId` (_integer (int32)_) The unique identifier of the uploaded bundle.  
    Example: `170`.
*   `warnings` (_array of string_) List of warnings generated during bundle processing.  
    Items: Maximum length: 4000. Example: `Deprecated runtime version detected`.
    
    _Example_
    
    ```
    []
    ```
    
*   `matches` (_object_) File matching results from bundle analysis.
    *   `ssrOnly` (_array of string_) Files matched as SSR-only (server-side only).  
        Items: Maximum length: 640. Example: `ssr.js`.
        
        _Example_
        
        ```
        [
          "ssr.js"
        ]
        ```
        
    *   `ssrShared` (_array of string_) Files matched as SSR-shared (used by both server and client).  
        Items: Maximum length: 640. Example: `shared.js`.
        
        _Example_
        
        ```
        [
          "shared.js"
        ]
        ```
        

### BundleValidationFailedErrorResponse

Returned when the uploaded bundle fails validation.

Includes all fields of `ErrorResponse`.

*   `error` (_string_) A human-readable description of why bundle validation failed.  
    Maximum length: 4000. Example: `missing entry point`.

### DeploymentResult

Paginated result containing a list of deployments.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Deployment_, required) List of deployments.

### DeploymentCreateRequest

Request body to create a new deployment.

*   `bundleId` (_integer (int32)_, required) The identifier of the bundle to deploy.  
    Example: `170`.

### Deployment

A deployment action that publishes a bundle to an environment.

*   `deploymentId` (_string_) The unique identifier of the deployment, in UUID format.  
    Minimum length: 36. Maximum length: 36. Pattern: ^\[0-9a-f\]{8}-\[0-9a-f\]{4}-\[0-9a-f\]{4}-\[0-9a-f\]{4}-\[0-9a-f\]{12}$. Example: `b035a4d7-ec6b-4dcd-af8f-3a847b10fed8`.
*   `status` (_string_) The current status of the deployment.  
    Allowed values: `queued`, `in_progress`, `failed`, `finished`. Example: `finished`.
*   `deploymentType` (_string_) The type of deployment.  
    Allowed values: `publish`, `reset_bundle`, `push`, `deploy_settings`, `redeploy`. Example: `publish`.
*   `creationDate` (_string (date-time)_) The timestamp when the deployment was created.  
    Example: `2026-04-08T21:47:31.322339Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the deployment was last modified.  
    Example: `2026-04-08T21:51:55.692688Z`.
*   `duration` (_number (double)_, nullable) The duration of the deployment in seconds. Null if the deployment has not finished.  
    Example: `76.867967`.
*   `createdBy` (_string_, nullable) The email address of the user who triggered the deployment. Null if no user is associated.  
    Maximum length: 254. Example: `dev@example.com`.
*   `statusMessage` (_string_) A human-readable message about the deployment's current state.  
    Maximum length: 4096. Example: `Queueing Bundle`.
*   `progress` (_object_, nullable) Progress information for the deployment. Null unless an external publish is in progress.
    *   `description` (_string_, nullable) A human-readable description of the current deployment stage.  
        Maximum length: 128. Example: `Updating CDN`.
    *   `percentage` (_integer (int32)_, nullable) Percentage of deployment completion.  
        Minimum: 0. Maximum: 100. Example: `0`.
*   `bundle` (_Bundle_)

### InvalidDeploymentRequestErrorResponse

Returned when the deployment request body is malformed or missing a valid bundleId.

Includes all fields of `ErrorResponse`.

### BundleNotFoundErrorResponse

Returned when the bundle referenced by the deployment request does not exist for this storefront.

Includes all fields of `ErrorResponse`.

*   `bundleId` (_integer (int32)_) The identifier of the bundle that couldn't be found.  
    Example: `999`.

### DeploymentConflictErrorResponse

Returned when a deployment cannot proceed because another deployment or deletion is already in progress for the environment.

Includes all fields of `ErrorResponse`.

### DeploymentNotFoundErrorResponse

Returned when the requested deployment does not exist.

Includes all fields of `ErrorResponse`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Bundle

A versioned build artifact (SSR application package) uploaded to a storefront.

*   `bundleId` (_integer (int32)_) The unique identifier of the bundle.  
    Example: `170`.
*   `description` (_string_) A user-provided message describing the bundle.  
    Maximum length: 2048. Example: `my bundle`.
*   `status` (_string_) The processing status of the bundle.  
    Allowed values: `ok`, `broken`, `preparing`. Example: `ok`.
*   `lifecycleStatus` (_string_) The lifecycle status of the bundle.  
    Allowed values: `active`, `cleanup_requested`, `cleanup_in_progress`, `cleanup_complete`, `cleanup_failed`. Example: `active`.
*   `createdBy` (_string_, nullable) The email address of the user who uploaded the bundle. Null if no user is associated.  
    Maximum length: 254. Example: `dev@example.com`.
*   `creationDate` (_string (date-time)_) The timestamp when the bundle was created.  
    Example: `2026-04-08T21:47:28.188965Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the bundle was last modified.  
    Example: `2026-04-08T21:47:31.307595Z`.
*   `type` (_string_) The bundle type.  
    Allowed values: `ssr`, `legacy`. Example: `ssr`.
*   `ssrParameters` (_object_, nullable) SSR configuration parameters for this bundle. Null for non-SSR bundles.
    *   `runtime` (_string_) The Node.js runtime version used by this bundle.  
        Maximum length: 256. Example: `24.x`.
    *   `runtimeDescription` (_string_) Human-readable description of the runtime version.  
        Maximum length: 256. Example: `NodeJS 24.x`.
    *   `envBasePath` (_string_) The base path for the environment associated with this bundle.  
        Maximum length: 256. Example: `ca`.
*   `inUseBy` (_array of string_) List of environment identifiers where this bundle is currently deployed.  
    Items: Maximum length: 256. Example: `production`.
    
    _Example_
    
    ```
    [
      "production"
    ]
    ```
    
*   `streamingEnabled` (_boolean_) Whether streaming is enabled for this bundle.  
    Example: `false`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=29c5c791262585836b5c23d6a719e7657f2ddf361ad77c31fda2a757f4fcbdd4 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/develop.md -->

# Develop

This section provides resources for building applications and services using the B2C Commerce APIs (SCAPI), including use cases and code samples to guide you through API capabilities and best practices.

## API Categories Overview

The B2C Commerce APIs are organized into two categories:

- **Shopper APIs** for customer-facing storefront experiences, authenticated with SLAS.
- **SCAPI Admin APIs** for backend operations and integrations, authenticated with Account Manager.

For the current API surface, use these source-of-truth references:

- [B2C Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references)
- [Commerce API release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)

As discussed in [Getting Started](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html), the B2C Commerce APIs are categorized as:

- Shopper APIs
  - Prefixed with `Shopper`
  - Used for storefront applications
  - Uses Shopper Admin API to access the API client
- SCAPI Admin APIs
  - Used for backend office applications
  - Uses Account Manager to access the API client

## Start Here: Common Task Paths

Choose the path that matches your development goal. These are starting paths, not exhaustive implementation checklists.

### Building a Storefront
1. **Set up authentication**: Configure [SLAS authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html) for your storefront
2. **Explore Shopper APIs**: Review [Use the Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-usage-container.html) and the [B2C Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references)
3. **Implement key features**: Start with product browsing, cart, and checkout flows
4. **Optimize**: Apply [performance best practices](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html)

### Automating Backend Operations
1. **Get Admin access**: Set up [Account Manager credentials](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html)
2. **Identify your APIs**: Review [Use the SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/admin-usage-container.html) and the [B2C Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references)
3. **Build integrations**: Implement inventory sync, CDN configuration, or custom workflows
4. **Monitor and test**: Use [API testing tools](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html#test-and-measure-your-apis)

### Building with Storefront Next
1. **Review Storefront Next architecture**: Start with [Storefront Next documentation](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-get-started.html)
2. **Confirm login and registration capabilities**: See [Login and Registration Support in Storefront Next](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-login-support.html)
3. **Configure SLAS and storefront features**: Follow the relevant Storefront Next authentication guides
4. **Deploy and test**: Use managed runtime environments for validation

### Building with PWA Kit
1. **Review PWA Kit requirements**: See [PWA Kit documentation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html)
2. **Configure SLAS**: Set up authentication for your PWA Kit storefront
3. **Customize API calls**: Extend or modify API interactions in your PWA Kit project
4. **Deploy and test**: Use managed runtime environments for testing

## Prerequisites

Make sure you have completed the following tasks:

- Determine the APIs that apply to your application: Shopper or SCAPI Admin.
- Obtain the required base URL configuration values and request formation. This applies to both Shopper and SCAPI Admin APIs.
- Set up [authentication and authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html) for your APIs. This includes creating an API client for Shopper APIs or SCAPI Admin APIs.

## Next Steps

- For Shopper APIs, review the use case information in [Use the Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-usage-container.html).
- For SCAPI Admin APIs, review the use case information in [Use the SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/admin-usage-container.html).
- Refer to the Reference section for endpoint details.

<!-- document id=7c3d1303bd20fd4a8e48cb675b5d3b35504e2024ddb764629efea1a9a3c6843e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/private-commerce-apps.md -->

# Develop a Private Commerce App

A private Commerce App is a standard Commerce App Package (CAP) installed with `AppSource=WebDAV`. The platform doesn't require a registry listing. Develop locally, upload with `b2c cap install`, and test on the storefront without publishing.

Build, package, and test using the shared guide. This page covers only the SI distribution path: install from WebDAV, skip the registry, and hand the CAP to the merchant.

## When to Stay Private

Stay private when the app is merchant-specific and shouldn't appear in the Cart & Checkout Hub catalog in Business Manager.

- Use the same CAP format and install job as public apps. See [Architecture Overview](/docs/commerce/b2c-commerce/guide/architecture.md) and [Packaging Your Commerce App](/docs/commerce/b2c-commerce/guide/packaging.md).
- Do not submit the app to the [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps). Registry review and `catalog.json` do not apply.
- Install with the B2C CLI or the install job (`app_source: WebDAV`). The app isn't discoverable or click-to-install in the Cart & Checkout Hub catalog. After installation, it appears with its installed state and configuration tasks in Business Manager.

If you later want merchants to find and install the app from Business Manager, follow [Publish to the App Registry](/docs/commerce/b2c-commerce/guide/submission-review.md) instead.

## Prerequisites

- A Commerce Cloud sandbox with Storefront Next enabled
- The [B2C CLI](/docs/commerce/b2c-commerce/guide/development-environment.md) installed, with job execution and WebDAV access
- The instance-level `CommerceAppsEnabled` toggle on (same as ISV installs)

You do **not** need access to the Commerce App Registry repository.

## Local Development Loop

```mermaid
flowchart LR
    A[Local CAP] --> B[validate / package]
    B --> C[WebDAV upload]
    C --> D["InstallCommerceApp CUSTOM_APP"]
    D --> E[BM tasks]
    E --> F[Storefront E2E]
```

1. Scaffold and implement the app. See [Building Your Commerce App](/docs/commerce/b2c-commerce/guide/building-your-app.md).
2. Validate and, when you need an artifact, package:

   ```bash
   b2c cap validate ./my-commerce-app
   b2c cap package ./my-commerce-app --output ./dist
   ```

   See [Packaging Your Commerce App](/docs/commerce/b2c-commerce/guide/packaging.md).

3. Install on the sandbox. Given a directory, the CLI packages, uploads via WebDAV, and starts the install job with `app_source: WebDAV`:

   ```bash
   b2c cap install ./my-commerce-app --site-id RefArch
   ```

4. Complete Business Manager configuration:

   ```bash
   b2c cap tasks my-commerce-app --site-id RefArch
   ```

5. Exercise the shopper flow on Storefront Next. See [Testing and Validation](/docs/commerce/b2c-commerce/guide/testing-validation.md).
6. Inspect, uninstall, and reinstall as you iterate:

   ```bash
   b2c cap list --site-id RefArch
   b2c cap uninstall my-commerce-app --site-id RefArch
   ```

> **Tip:** During rapid development, install from the source directory and skip the separate package step. See [Development Environment Setup](/docs/commerce/b2c-commerce/guide/development-environment.md#inner-development-loop-test-stage).

For all flags, authentication, and OCAPI setup, see [Development Environment Setup](/docs/commerce/b2c-commerce/guide/development-environment.md#cli-commands).

## What Install Does for Private Apps

The install job is the same `sfcc-install-commerce-app` pipeline used for public apps, with these WebDAV differences:

| Behavior | Private (`AppSource=WebDAV`) |
| :------- | :--------------------------- |
| Per-app registry listing | Skipped. Unregistered apps install. |
| Domain | The job's `app_domain` must still resolve to a recognized registry domain. An unknown domain stops installation before state is created. |
| Feature type | Forced to `CUSTOM_APP`. |
| Feature source | Persisted as `WebDAV`. |
| Package fetch | `AppPath` on WebDAV is required. |
| Display name | When valid, CAP `commerce-app.json` `name` is stored as optional display metadata. |
| Icon | One top-level SVG or PNG from CAP `icons/` can be stored as optional display metadata when it is within the platform size limit. |
| Cartridges, IMPEX, state | Same as public installs: unzip, validate `tasksList.json` / optional `adminComponents.json`, copy cartridges, update paths, process install IMPEX (`SITEID` / `LIBRARYID`), persist uninstall IMPEX, write `CommerceFeatureState`. |

Optional storefront PR creation uses the job parameter `should_create_pr` (default `false`). When requested and the CAP contains Storefront Next extensions or cartridges, the job attempts to open a PR against the merchant's Storefront Next repository. With the B2C CLI, add `--create-pr` to `b2c cap install` (see [B2C CLI CAP documentation](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/cap.html#creating-a-storefront-pull-request)). If PR creation fails, installation continues and adds a warning task. See [Install Job Parameters](/docs/commerce/b2c-commerce/guide/reference.md#install-job-parameters).

When calling the job API directly, first upload the CAP to WebDAV and set `app_path` to that uploaded file. The CLI normally uploads to `Impex/commerce-apps/`. See the full example in [Reference](/docs/commerce/b2c-commerce/guide/reference.md#install-job-parameters):

```json
POST /s/-/dw/data/v25_6/jobs/sfcc-install-commerce-app/executions
{
  "app_name": "avalara-tax",
  "app_source": "WebDAV",
  "app_domain": "tax",
  "site_id": "Sites-RefArch",
  "app_path": "webdav/Sites/Impex/commerce-apps/avalara-tax-v0.2.5.zip"
}
```

## Constraints

- **Known domain only.** The install job's `app_domain` parameter must match a recognized registry domain (`tax`, `oms`, `shipping`, and the others listed in [Supported Domains](/docs/commerce/b2c-commerce/guide/supported-domains.md)). `b2c cap install` derives this value from `commerce-app.json`; direct job callers supply it explicitly.
- **Not in the Cart & Checkout Hub catalog.** Merchants cannot discover or click-to-install a private app. Install with `b2c cap install` or upload the CAP to WebDAV before calling the job API with `app_source: WebDAV` and `app_path`.
- **Avoid registry ID collisions.** A registry entry isn't required. However, if `app_name` and `app_domain` match an existing entry, the installer can still apply that entry's required feature toggle and storefront compatibility metadata. Use an app ID that doesn't collide with a registered app.
- **Same CAP format.** Private apps should follow the standard CAP format, including `commerce-app.json`, `tasksList.json`, `SITEID` / `LIBRARYID` placeholders, uninstall IMPEX, and hook naming. See [Packaging Your Commerce App](/docs/commerce/b2c-commerce/guide/packaging.md) and [Known Limitations](/docs/commerce/b2c-commerce/guide/reference.md#known-limitations).

## Handoff to the Merchant

1. Deliver the packaged `.zip` from `b2c cap package` through an access-controlled channel. Provide its SHA-256 digest separately so the merchant can verify integrity before installation.
2. The merchant or SI installs on staging with `b2c cap install` or the job API.
3. Promote each app artifact and supported configuration from staging to production, then verify the target state. See [Post-Install Maintenance](/docs/commerce/b2c-commerce/guide/post-publication.md).
4. Do not run `/submit-pr` and do not edit `catalog.json`.

## CI

Use the shared pipeline from [CI/CD Pipeline Integration](/docs/commerce/b2c-commerce/guide/development-environment.md#cicd-pipeline-integration), and drop the registry publish step:

1. **On pull request:** `b2c cap validate <path> --json`
2. **On release:** `b2c cap package <path> --output ./dist --json` and keep the `.zip` as the artifact
3. **On promote:** `b2c cap install ./dist/<app>.zip --site-id <site-id> --clean-archive --json` against a dedicated sandbox, then `b2c cap list --site-id <site-id> --json`. Retain the release artifact in your controlled artifact store instead of leaving a private CAP on WebDAV.

<!-- document id=7287596e4dce529296f639b9318890800924db750d0a160ac20c55572c61d4ac url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/develop-and-extend.md -->

# Develop and Extend

Implement SPIs, manage data models, and prepare the app for distribution.

## In this section

- [Integration Fundamentals](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/integration-fundamentals.html)
- [Data Exports](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/data-exports-guide.html)
- [Customer & Associates](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/customer-and-associates.html)
- [Orders & Inventory](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/orders-and-inventory.html)
- [App Distribution](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/create-distribution-certificate.html)

## See also

- [Point of Sale Loyalty SPIs](https://help.salesforce.com/s/articleView?id=commerce.rt_pos_clienteling_loyalty_spis.htm) in _Salesforce Help_
- [Configuring Point of Sale SPIs as Order Master](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/manage-orders-with-spis.html)
- [SPI Customer Search Layout](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-customer-search-layout.html)
- [Cart Validation Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/cart-validation-via-spi.html)
- [Benchmarks and Best Practices for Orders and Transaction Export](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_export_tlog_benchmarks.htm) in _Salesforce Help_
- [Exporting Data When Suspending & Voiding Carts](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-data-when-suspending-voiding-carts.html)
- [Export the Transaction Log (TLog)](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-tlog.html)

<!-- document id=20267eb437837f48eac6100733657208cb7683305309d242e907288f71bb46cd url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/sandboxes/b2c-develop-with-on-demand-sandbox.md -->

# Develop With Your On-Demand Sandbox

This guide walks you through how to work directly with APIs to set up an [ODS](https://commerce-clo-hargrave-o-sgrlli.herokuapp.com/docs/commerce/b2c-commerce/guide/b2c-developer-sandboxes.html) with your code and data using [sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci). Use a third-party IDE if preferred, for example: [Prophet Debugger](https://marketplace.visualstudio.com/items?itemName=SqrTT.prophet).

To quickly get started using a PWA Kit demo site and demo data, see [Create an On-Demand Sandbox for PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/creating-an-on-demand-sandbox.html).

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


1. Create your ODS and log in:
   1. If needed, install [sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci).
   2. Create an API client to use with sfcc-ci. See [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).
   3. Authenticate using either of the following sfcc-ci commands:
      - `sfcc-ci auth:login {client_id}`
      - `sfcc-ci client:auth {client_id} {client_secret}`
   4. [Create your ODS](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-get-started-sandboxes.html#create-an-on-demand-sandbox).
      - Specify a sandbox on the `abcd` realm with an unlimited time to live. sfcc-ci ensures the WebDAV and OCAPI permissions are pre-configured using the `client_id` from authentication.
      - `sfcc-ci sandbox:create -r abcd --ttl 0`
   5. Validate your sandbox is started:
      - `sfcc-ci sandbox:get -s [sandbox_id]`
2. Zip up your cartridges:
   - Use your preferred tool to create a zip file of your cartridges. The zip should contain a top level folder with the code version name. In this folder should contain the cartridge folders.
   - Your .zip file name must exactly match the top level folder name inside the .zip file, for example if your code version is `version1` the zip should be called `version1.zip`
3. Upload and activate your code version. For the .zip file, use the same name that you used for the code version.
   - `sfcc-ci code:deploy code_version.zip`
   - `sfcc-ci code:activate code_version`
4. Upload and import your site data:
   - `sfcc-ci instance:upload archive.zip -i abcd-001.dx.commercecloud.salesforce.com`
   - `sfcc-ci instance:import archive.zip -i abcd-001.dx.commercecloud.salesforce.com`
5. Run a job to refresh your indexes:
   1. [Choose a job](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/globaljobs.html), for example, **Full Product Index Update**.
   2. Specify the job you selected and a [site scope](https://sfcclearning.com/infocenter/OCAPI/current/data/Documents/SearchIndexUpdateConfiguration.php). For example, if you selected the `Full Product index update` job:
      - `sfcc-ci job:run sfcc-search-index-product-full-update SiteScope='{"named_sites": ["RefArch"]}' -i abcd-001.dx.commercecloud.salesforce.com`

## Troubleshooting

- If you receive errors:
  - Make sure the code version information used in your .zip file name exactly matches the name of the top level folder inside of the .zip file.
  - When importing your data, make sure your .zip file archive, also known as the “site import archive”, has the required folder structure.
- If SLAS hybrid authentication fails with the error `Cannot construct SLAS session-bridge URL: no ACTIVE SCAPI short code found for this organization`, generate a dedicated SCAPI short code for your sandbox realm in Business Manager. See [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#short-code) and [Generate a Short Code and Create an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_generate_a_shortcode_and_api_client_id.htm&type=5).

## Next Steps

If you are using SCAPI: see

- [Quick Start](https://developer.salesforce.com/docs/commerce/commerce-api/guide/api-and-sdk-demo.html) for details on how to set up a demo using the SDK.
- [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) for information about how to set up a client.

<!-- document id=336530bb37c3fca78b256e50e5975569b430a03f281b75a83897570c16a8927f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/recommendations/b2c-developer-considerations-for-predictive-recommendations.md -->

# Developer Considerations for Einstein Product Recommendations

To implement Einstein Product Recommendations, modify ISML templates, define content slots, provide a unique ID, and make other customizations.

When you implement Einstein Product Recommendations, keep these points in mind:

- Modify ISML templates to define content slots and show Einstein Product Recommendations.
- When you define content slots for Einstein Product Recommendations, give the slot a unique ID and set the `context` to global.
- If the content slot renders recommendations on product detail or category-landing pages, include the referring product ID or category ID as part of the `context-object` attribute.
- Pass the `context-object` attribute a basket or `dw.util.Collection` of products. This option creates and uses recommendations based on selected products (up to 5), or all products in the basket.

This example `<isslot>` tag shows how to define a slot for use on a product detail page:

```xml
<isslot id="myslotid" context="global" context-object="${pdict.Product}"/>
```

This example shows how to define a slot for use on a category landing page:

```xml
<isslot id="cat-banner" context="category" context-object="${pdict.ProductSearchResult.category}" />
```

For defined content slots on your storefront, make sure to create a page template to render the recommended products. If you already have a template that renders other types of product content slots, reuse these templates with some modification. When reusing a template, copy it to the `/templates/default/slots/recommendation/` folder.

This example shows a product template for Einstein Product Recommendations:

```xml
<iscontent type="text/html" charset="UTF-8" compact="true"/>
<iscomment> should not be cached, the tiles are cached individually.</iscomment>

<isif condition="${slotcontent}">
<div class="product-listing product-listing-1x4">
        <h2>${slotcontent.calloutMsg}</h2>

        <ul class="search-result-items tiles-container">
                <isloop items="${slotcontent.content}" var="product" begin="0" end="3">
                        <isobject object="${product}" view="recommendation">
                                <li class="grid-tile">
                                        <isinclude url="${URLUtils.url('Product-HitTile',
                                                'pid', product.ID,
                                                'showswatches', 'true',
                                                'showpricing', 'true',
                                                'showpromotion', 'true',
                                                'showrating', 'true')}"/>
                                </li>
                        </isobject>
                </isloop>
        </ul>

</div>
</isif>
```

When you develop slot-rendering templates for Einstein Product Recommendations, don't cache the entire slot. Einstein Product Recommendations are dynamic, so caching the entire slot shows the same recommendations to every visitor. Cache individual product tiles instead of the entire template.

<!-- document id=6cf16f2b0ed8cc32c4418ef1e3638039cd126920d0ed3c698e421ef66914375f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/recommendations/b2c-recommendations-for-developers.md -->

# Developer Considerations for Explicit Recommendations

To control which products are recommended, use Explicit Recommendations. For example, use Explicit Recommendations for compatible products or for products that were photographed together. Use [Einstein Product Recommendations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-considerations-for-predictive-recommendations.md) to generate recommendations dynamically from shopper behavior.

## Existing Applications and Explicit Recommendations

Some Salesforce B2C Commerce storefront applications were developed using the product linking feature. This feature pre-dated the explicit recommendations feature in Business Manager and requires added considerations.

Define product-to-product relationships to provide for replacement products, cross-sells, up-sells accessories, follow-up, a different order unit or spare parts. With the product linking feature, you define simple links between products. For example, linking older versions of a product with newer versions.

If you use the product links feature, you don't need to convert to the recommendations feature. B2C Commerce also supports product linking. However, enhancements are made only to the recommendations feature.

With a product linking and explicit recommendation implementation, you can:

- Create added recommendation types through custom attribute definitions.
- Define the presentation logic for the additional recommendations within UX Studio in your storefront cartridge.

When using both features, keep the following in mind:

- Product links conceptually are intended for fundamental relationships between products. For example, product-to-part relationships.
- Recommendations can appear only on a site if the storefront catalog contains the recommendation. Product links aren't directly stored in a catalog and don't have this restriction.
- Recommendations are system objects and can have custom attributes. Product links can't have custom attributes.

Some reasons for moving away from a product linking implementation and switching to or adding recommendations include:

- Implementing category to product recommendations.
- Using recommendation-specific attributes (for example, name, short description, long description, callout message, or image). These attributes let you customize the presentation of a specific product based on the target object and recommendation type.

## Developer Best Practices for Explicit Recommendations

When working with Explicit Recommendations, use these developer best practices.

When working with your merchandising team:

- Make sure to provide the team with a clear understanding of how explicit recommendations are implemented within their storefront. It helps merchandisers to understand various use cases including:
  - Not defining any recommendations.
  - Defining more than the specified number of recommendations.
  - When imports are scheduled (if using the recommendation import functionality). This information is important for building imports into business process time and allowing for validation and augmentation as necessary.
- When using variation products, make sure to understand whether to assign recommendations to the base product, variation products, or both. How you assign these products affects how these products appear in the storefront.

As shown in the SiteGenesis application, the default behavior is to show recommended products regardless of availability. Change your application to show recommended products only if they're in stock.

## General Considerations for Explicit Recommendations

When determining how to implement explicit recommendations, consider these planning and development phase guidelines.

These guidelines include considerations for the following phases:

- Requirements phase
- Design phase
- Build phase
- Development and test phase

During the _requirements phase_, you identify how many types of recommendations are required for the solution. For each identified recommendation type, first determine requirements for the following:

- Presentation logic: Where each recommendation type renders, how many recommendations are presented at a time. This determination includes what occurs when:
  - No recommendations are defined for a given category or product.
  - Fewer than the planned number of recommendations are defined for a given category or product.
  - More than the planned number of recommendations are defined for a given category or product.
- Visualization requirements: How individual recommendations appear and what data elements are required to support any specific visualization.

After making these determinations, identify how you want recommendations populated (import, manual, programmatic, or other). Populate recommendations during development or when the site is live.

If you plan to manually create recommendations in Business Manager, make sure to identify the following:

- Who creates and maintains the recommendation.
- Any necessary review process.
- How to test the recommendation.
- How recommendation data is replicated with catalog data.

If you plan to import recommendations, define the import process. If possible, implement this process as a job within Salesforce B2C Commerce to take advantage of the scheduling and notification functionality built into the system.

After you solidify information in the requirements phase, move on to the _design phase_. During this phase, consider the operational overhead and merchant ease of use.

| Consideration        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operational overhead | Review the day-to-day operational overhead associated with creating and maintaining recommendations manually within the system―especially if you have large product catalogs. Determine whether you require that all products appear with explicit recommendations; if you do, consider whether it would be advantageous to add simple logic into the presentation rules. If you plan to build logic into B2C Commerce to dynamically determine which products to recommend, pay attention to any additional page rendering overhead. Additional overhead can negatively impact storefront performance. Make sure to consider what to populate as part of the import process using logic based on existing attributes and category assignments. |
| Merchant ease of use | Make sure you know the product or category ID. This information helps you search more accurately within the Business Manager Recommendations module. Make sure these values are meaningful to your organization.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

Following the design phase, you enter the _build phase_ where you build code to support recommendation requirements. You then facilitate the _development and test phase_:

- Create users with permissions that are in line with your business processes.
- Create an initial set of test recommendations.
- Use a test plan to make sure that all use cases are reviewed.
- Test the import process, if applicable.

## Business Objects for Explicit Recommendations

Explicit recommendations use an extensible system object to include native attributes.

This table lists the native attributes included with the _Recommendation_ system object.

| ID                             | Type            | Description                                                                              | Localizable |
| ------------------------------ | --------------- | ---------------------------------------------------------------------------------------- | ----------- |
| UUID                           | String          | The recommendation's internal identifier.                                                | No          |
| calloutMsg                     | Html            | The recommendation's callout message.                                                    | Yes         |
| creationDate                   | Date + Time     | The recommendation's creation date. This doesn't change.                                 | No          |
| image                          | Image           | The image associated with the recommendation that appears on the storefront.             | No          |
| lastModified                   | Date + Time     | The date and time at which the recommendation was modified. This changes with each edit. | No          |
| longDescription                | Html            | A detailed description of the recommendation.                                            | Yes         |
| name                           | String          | The name of the recommendation as it will appear on the storefront.                      | Yes         |
| RecommendationType (see below) | Enum of Integer | The recommendation type in integer format.                                               | No          |
| ShortDescription               | Html            | An abbreviated description of the recommendation.                                        | Yes         |

## RecommendationType

The number of recommendation types is extensible and the labels associated with the types in the Business Manager are configurable. _RecommendationType_ is configured with three default values:

- 1 (cross-sell)
- 2 (up-sell)
- 3 (other)

If these types don't satisfy your requirements, add new types or rename existing types.

To add additional attribute values, you can:

- Configure them manually in Business Manager: Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Site Development > System Object Type > Recommendation**.
- Create them as part of a meta data import feed.

## Analytics and Reporting for Explicit Recommendations

Salesforce B2C Commerce reports on recommendations using pipeline processing reports and system logs.

B2C Commerce provides pipeline processing data in Reports & Dashboards. To view the pipeline reports, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Analytics** > **Reports & Dashboards**. Select the Technical Dashboard tab.

Because many implementations use pipelines to process recommendations, the Pipeline Usage and Pipeline Errors reports can provide useful information when testing and troubleshooting recommendations. Use the Pipeline Debugger.

System logs capture information related to API processing, data staging, and error handling. These logs can provide useful information when troubleshooting recommendation-related issues. To access system logs, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup** > **WebDAV Log File section**.

<!-- document id=773088bbd1f6e4092047796d03a4b8b0aa3934aee12d63f3541edf2f8dc8d392 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-dev-best-practices.md -->

# Development Best Practices

We recommend some best practices to maximize development efficiency and results.

## Instance Naming

An instance is a server connection path. Give your instance a unique name such as firstInitial_lastName to avoid multiple developers changing the same instance, which can result in code overwrite or code loss. A unique name also identifies which developer is working on an instance.

## .zip Files in Code Repository

If you use .zip files to transfer code, we recommend that you unzip the files into the code repository. Otherwise, change tracking only affects the entire .zip file and not the individual files within it.

In our standard processes, cartridges aren't saved in .zip files. However, some implementation partners can have implemented a process where they zip versioned cartridges for storage.

It's possible to export a site into a .zip file (Site Export functionality). That .zip file contains site configuration data and other data objects. Track the contents in the versioning system.

## Development Guidelines and Limitations

We provide some recommendations and limitations for B2C Commerce development, including guidelines for video, email, templates, quotas, and scripts.

### Video Support

Video files are limited to 20MB.

Video files up to 20MB are cached. Video files greater than 20MB aren't cached, but delivered in streaming mode, which degrades performance. B2C Commerce doesn't support streaming video of any kind, because we don't have a streaming server.

B2C Commerce supports _download and play video;_ such as Flash, Windows Media and QuickTime. For high-traffic storefront pages, the recommended storefront implementation approach is to only download the container as part of initial page rendering, and subsequently download the video only upon user action (when they press play). For example, don't auto-download or auto-play as part of initial page rendering.

For heavy-use of real streaming media, or a high-volume of _download and play videos_ (or files greater than 20MB), we recommend that you use a specialty provider (such as Akamai) to deliver this type of content. For example, the recommended storefront implementation approach is to use the absolute URL to the separately hosted rich media.

These recommendations are designed to help you better manage data-transfer allocations, and avoid overage fees

Video file support

B2C Commerce supports these formats:

- video/ogg .ogv
- video/webm .webm
- video/mp4 .mp4

Use this to integrate with external applications, using the correct mime type, to show these types of videos.

### Email Support

Emails are limited to 3MB.

After sending an email via B2C Commerce, you might receive an error in the logs that looks like this, indicating that your email message is too large:

```txt
[2008-02-14 12:04:33.096 GMT] error - blade0-0.mon.demandware.net ES1 appserver - core - - - "pool-2-thread-1"
(-) exception occurred com.sun.mail.smtp.SMTPSendFailedException: 552 Error: message too large.
```

B2C Commerce supports outbound email sizes of 3MB or less. If you need to transfer data larger than 3MB, we recommend that you don't use email as the vehicle. B2C Commerce supports FTP, which has a much higher limit (100MB) for large files.

### Template Support

Templates are limited to 10MB.

If the generated output of an ISML template exceeds 10 MB, the page processing is canceled with the Exception `Page size limit of 10 MB exceeded`. This applies to Storefront as well as Business Manager ISML templates. The limit of 10MB should help prevent out of memory errors. It will also increase the speed of the Storefront and of Business Manager.

Exceeding the 10 MB limit in the following configurations, is know to return the error exception.

- Large number of images configured on a product.
- Excess content added in slot content configurations.

**tip:** To decrease generated response data, set a limit for the search results, use keywords, and don't load all the data

### Page Designer Page Size

Page Designer pages are limited to 3 MB.

When a Page Designer page is rendered through `dw.util.Template.render()`, the generated output is limited to 3 MB. If the rendered output exceeds this limit, then page processing is canceled and the page fails to render, appearing as a blank page on the storefront. Because the related log is internal, the storefront gives no indication of the cause. The log records an exception like this:

```txt
com.demandware.beehive.core.internal.request.LimitedSizeByteArrayOutputStream$PageSizeLimitExceeded: Page size limit of 3 MB exceeded
```

This 3 MB limit is separate from, and lower than, the 10 MB ISML template limit. A common cause of exceeding it is a component that renders a large data set on a single page, such as a product listing bound to a category that contains a large number of products.

To keep a Page Designer page within the 3 MB limit:

- Avoid assigning very large categories to a single Page Designer component. Use a more specific category or a curated product set instead.
- Limit the number of products or items rendered on a single page, and paginate or lazy-load large product lists.
- Reduce the number of components and the amount of content rendered on a single page. Split content across multiple pages when needed.

### Quotas

B2C Commerce is designed to be used as an online ecommerce system. Certain constraints and limits were set during its design and implementation to accommodate this, as follows:

- Memory usage
- Resource consumption
- API calls
- Number of business objects

In the current B2C Commerce version, we monitor these limits, but don't control them. However, customized code might exceed these limits, causing errors and other forms of operational disruption. Exceeding the limits is typically caused by a direct misuse of an API, when a more resource-efficient implementation method exists for the same functionality. We will enforce these limits soon in a future version. See the B2C Commerce API Documentation for details.

### B2C Commerce Script Timeout

The default B2C Commerce script timeout is 30 seconds.

### Tax Classes and Jurisdictions Limit

A large number of unnecessary tax classes and jurisdictions can exceed the `10 MB limit of the ISML template`. Exceeding the 10 MN limit causes the Business Manager | Ordering | Taxation Settings | TaxRate page to result in an error.

<!-- document id=9daa4c92e1eb6d7076ebcc368cfce53f3dd1bad6013d845ee64fb62c590f9872 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-dev-components.md -->

# Development Components

Each B2C Commerce site is made up of development component building blocks.

- [Cartridges](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-cartridges.md)

- [Controllers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-working-with-controllers.md)

- [Scripts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-working-with-scripts.md)

- [Templates](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-working-with-templates.md)

- [Forms](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/sfra/b2c-forms.md)

<!-- document id=c1745b336026c90a8e1282a940e048fe73d9bde83a624c6bcb5c6f7b7f13a9fa url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/development-environment.md -->

# Development Environment Setup

Set up your local development environment for building Commerce Apps.

## Prerequisites

Before building a Commerce App, ensure you have:

- A Commerce Cloud sandbox instance with Storefront Next enabled
- The [B2C CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md#run-the-b2c-cli) installed and configured with your instance credentials
- **ISVs only:** Access to the [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps). SIs building a merchant-specific app do not need the registry. See [Develop a Private Commerce App](/docs/commerce/b2c-commerce/guide/private-commerce-apps.md).
- Node.js and npm for Storefront Next development
- A code editor with JavaScript/TypeScript and React support
- Familiarity with Commerce Cloud cartridge development, IMPEX, and the SCAPI/OCAPI model

## Claude Code Skills

If you use Claude Code, the Commerce Apps repository provides skills that automate many manual steps:

| Skill                              | Description                                                   |
| :--------------------------------- | :------------------------------------------------------------ |
| `/scaffold-app`                    | Generate a complete app directory structure with templates    |
| `/package-app`                     | Package an app into a registry-ready ZIP                      |
| `/validate-app`                    | Comprehensive validation (structure, manifest, SHA256, IMPEX) |
| `/validate-impex`                  | Deep IMPEX validation for syntax and common errors            |
| `/generate-service-impex`          | Generate service credential, profile, and definition IMPEX    |
| `/generate-site-preferences-impex` | Generate site preference IMPEX                                |
| `/generate-custom-object-impex`    | Generate custom object type IMPEX                             |
| `/extract-app`                     | Extract a commerce app ZIP for development or modification    |
| `/diff-versions`                   | Compare two app versions for changelogs                       |
| `/submit-pr`                       | Guide through the PR submission process                       |

These skills complement the B2C CLI commands below. Use Claude Code skills for app scaffolding, IMPEX generation, and validation. Use the B2C CLI for installation, uninstallation, and sandbox testing.

## CLI Authentication Setup

The `cap install`, `cap uninstall`, `cap list` (without `--local`), `cap tasks`, and `cap pull` commands require OAuth credentials and OCAPI permissions on your target instance. These remote commands also require WebDAV access for package upload or download. The `cap validate`, `cap package`, and `cap list --local` commands are local-only and require no authentication.

For full details on B2C CLI authentication, see the [B2C CLI Authentication Guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.html).

### OCAPI Configuration

For remote commands (`install`, `uninstall`, `list`, `tasks`, `pull`), configure the Data API permissions for system jobs and related queries. Your API client must grant the standard B2C CLI job-execution permissions on `/jobs/*/executions`, `/jobs/*/executions/*`, and `/job_execution_search`. If `cap list` or `cap pull` must discover sites because `--site-id` is omitted, also grant `GET` access to `/sites`. Configure these in Business Manager under **Administration** > **Site Development** > **Open Commerce API Settings** > **Data API**.

For the exact JSON resource block, see [Required OCAPI Permissions](/docs/commerce/b2c-commerce/guide/reference.md#required-ocapi-permissions). For broader B2C CLI authentication setup, see the [B2C CLI Authentication Guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.html#ocapi-configuration).

### WebDAV Access

`cap install` uploads the CAP archive to the instance via WebDAV before triggering the installation job. SCAPI isn't a substitute for WebDAV upload — there is no SCAPI endpoint that uploads CAP archives. Authenticate WebDAV using one of these methods:

- **Business Manager credentials:** Set your BM username and WebDAV access key via `SFCC_USERNAME` and `SFCC_PASSWORD` environment variables, or use `--user-auth` to authenticate interactively via the browser.
- **Account Manager OAuth client:** Configure an OAuth client with **WebDAV Client Permissions** for the `/impex` path, in addition to the job-execution permissions described above. See the [B2C CLI WebDAV Access guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.html#webdav-access) for details.

## CLI Commands

The B2C CLI provides commands for Commerce App development under the `cap` topic:

### b2c cap validate

Performs local validation of basic manifest fields, folder structure, and required files. It doesn't validate IMPEX content or perform registry submission checks. Accepts a path to a CAP directory or a `.zip` file.

```bash
b2c cap validate <path>
```

**Examples:**

```bash
# Validate a CAP directory
b2c cap validate ./commerce-avalara-tax-app-v0.2.5

# Validate a packaged CAP zip
b2c cap validate ./commerce-avalara-tax-app-v0.2.5.zip
```

### b2c cap package

Packages your project directory into a distributable `.zip` CAP file. ISVs must still complete the App Registry validation and submission workflow.

```bash
b2c cap package <path> [--output, -o <dir-or-file>] [--json]
```

**Examples:**

```bash
# Package to the current directory
b2c cap package ./commerce-avalara-tax-app-v0.2.5

# Package to a specific output directory
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist

# Package to a specific filename
b2c cap package ./commerce-avalara-tax-app-v0.2.5 --output ./dist/my-app.zip
```

> **Tip:** Add `--json` to any `cap` command for machine-readable JSON output, useful for scripting and CI pipelines.

### b2c cap install

Installs a CAP on a target instance. Accepts a local directory or `.zip` file. The CLI automatically uploads the archive to WebDAV and triggers the server-side installation job. See [CLI Authentication Setup](#cli-authentication-setup) for required credentials.

```bash
b2c cap install <path> --site-id <site-id> [--clean-archive] [--timeout <seconds>] [--skip-validate] [--create-pr] [--force] [--json]
```

**Flags:**

| Flag              | Description                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| `--site-id`, `-s` | **(Required)** Site ID to install the Commerce App on. Alias: `--site`                                   |
| `--clean-archive` | Delete the uploaded zip from the instance after install. By default the archive is kept on the instance. |
| `--timeout`, `-t` | Timeout in seconds for the installation job                                                              |
| `--skip-validate` | Skip CAP structure validation before install                                                             |
| `--create-pr`     | Request a pull request for Storefront Next extensions or cartridges                                      |
| `--force`, `-f`   | Skip the confirmation prompt shown for non-Salesforce applications                                       |
| `--json`          | Output results as JSON                                                                                   |

**Examples:**

```bash
# Install from a directory
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch

# Install from a zip file
b2c cap install ./commerce-avalara-tax-app-v0.2.5.zip --site-id RefArch

# Install and skip pre-validation
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --skip-validate

# Install and clean up the archive from the instance afterward
b2c cap install ./commerce-avalara-tax-app-v0.2.5 --site-id RefArch --clean-archive
```

### b2c cap uninstall

Uninstalls a Commerce App from a target instance by app ID. The CLI automatically discovers the app's domain by querying the installed apps on the instance, so you don't need to specify it.

```bash
b2c cap uninstall <app-id> --site-id <site-id> [--timeout <seconds>] [--json]
```

**Flags:**

| Flag              | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `--site-id`, `-s` | **(Required)** Site ID to uninstall the Commerce App from. Alias: `--site` |
| `--timeout`, `-t` | Timeout in seconds for the uninstall job                                   |
| `--json`          | Output results as JSON                                                     |

**Examples:**

```bash
b2c cap uninstall avalara-tax --site-id RefArch
```

### b2c cap list

Lists Commerce Apps either locally (from the filesystem) or installed on a remote B2C Commerce instance. When querying a remote instance, requires the same authentication as `cap install`.

```bash
b2c cap list [--local] [--site-id <site-id>[,<site-id>]] [--timeout <seconds>] [--json]
```

**Flags:**

| Flag              | Description                                                                             |
| ----------------- | --------------------------------------------------------------------------------------- |
| `--local`, `-l`   | List Commerce Apps found in local directories instead of querying a remote instance     |
| `--site-id`, `-s` | Site ID(s) to query. Accepts comma-separated values for multiple sites. Alias: `--site` |
| `--timeout`, `-t` | Timeout in seconds for the remote query                                                 |
| `--json`          | Output results as JSON                                                                  |

**Examples:**

```bash
# List apps installed on a remote instance
b2c cap list --site-id RefArch

# List apps across multiple sites
b2c cap list --site-id RefArch,SiteGenesis

# List locally available Commerce App directories
b2c cap list --local
```

### b2c cap tasks

Lists configuration tasks for an installed Commerce App. Tasks include Business Manager deep links for completing post-install configuration such as entering service credentials or setting site preferences.

```bash
b2c cap tasks <app-name> --site-id <site-id> [--timeout <seconds>] [--json]
```

**Flags:**

| Flag              | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `--site-id`, `-s` | **(Required)** Site ID where the app is installed. Alias: `--site` |
| `--timeout`, `-t` | Timeout in seconds for the remote query                            |
| `--json`          | Output results as JSON                                             |

**Examples:**

```bash
# View configuration tasks for an installed app
b2c cap tasks avalara-tax --site-id RefArch
```

### b2c cap pull

Downloads installed Commerce App packages from a B2C Commerce instance to a local directory. If no app name is specified, pulls all registry-sourced apps installed on the instance.

This command is particularly useful for merchants who install Commerce Apps from Business Manager and want to integrate the app's code into their projects using their existing development workflows, rather than relying on the automated pull request flow. After pulling, the `storefront-next/` extensions and `cartridges/` from the downloaded package can be reviewed, customized if needed, and integrated into the merchant's storefront and cartridge projects through their standard source control and deployment processes.

```bash
b2c cap pull [app-name] [--site-id <site-id>] [--output, -o <dir>] [--timeout <seconds>] [--json]
```

**Flags:**

| Flag              | Description                                                          |
| ----------------- | -------------------------------------------------------------------- |
| `--site-id`, `-s` | Site ID to query for installed apps. Alias: `--site`                 |
| `--output`, `-o`  | Output directory for downloaded packages. Default: `./commerce-apps` |
| `--timeout`, `-t` | Timeout in seconds for the download                                  |
| `--json`          | Output results as JSON                                               |

**Examples:**

```bash
# Pull a specific app
b2c cap pull avalara-tax --site-id RefArch

# Pull all installed registry apps to a custom directory
b2c cap pull --site-id RefArch --output ./downloaded-apps
```

## End-to-End Development Lifecycle (ISV and SI)

From the perspective of an ISV building a Commerce App for the registry, or an SI building a private app for a specific merchant, the full lifecycle spans four stages — each backed by a combination of Claude Code skills and B2C CLI commands:

| Stage           | Goal                                                                                              | Primary tooling                                                                                                 |
| :-------------- | :------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- |
| **Scaffold**    | Generate a CAP directory structure and starter manifests                                          | `/scaffold-app`, `/generate-service-impex`, `/generate-site-preferences-impex`, `/generate-custom-object-impex` |
| **Develop**     | Implement cartridge hooks, Storefront Next extensions, and IMPEX                                  | Your editor + cartridge dev tooling; `/validate-impex` for incremental IMPEX checks                             |
| **Test**        | Validate, package, install on a sandbox, and exercise end-to-end                                  | `b2c cap validate`, `b2c cap package`, `b2c cap install`, `b2c cap tasks`, `b2c cap list`                       |
| **Submit/Ship** | Publish to the registry or deliver a private `.zip`                                            | ISV: `/diff-versions`, `/submit-pr`. SI: deliver the CAP; merchant or SI runs `b2c cap install`.                        |

ISVs publish through the [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps). SIs deliver the CAP and install it with `b2c cap install` (WebDAV). Private apps are not listed in the Cart & Checkout Hub catalog, so merchants cannot click-to-install them. The same packaging, validation, and installation tooling applies in both cases. See [Develop a Private Commerce App](/docs/commerce/b2c-commerce/guide/private-commerce-apps.md).

### Inner Development Loop (Test Stage)

Within the Test stage of the lifecycle above, the recommended sandbox iteration loop is:

1. Develop your code locally (cartridges, scripts, Storefront Next extensions)

2. Organize your project into the CAP directory structure (see [CAP Structure](/docs/commerce/b2c-commerce/guide/architecture.md#commerce-app-package-cap-structure))

3. Validate your CAP structure:

   ```bash
   b2c cap validate ./my-commerce-app
   ```

4. Package into a `.zip` file:

   ```bash
   b2c cap package ./my-commerce-app --output ./dist
   ```

5. Install on your sandbox (the CLI handles the WebDAV upload and job execution automatically):

   ```bash
   b2c cap install ./dist/my-commerce-app-v1.0.0.zip --site-id RefArch
   ```

6. View and complete configuration tasks:

   ```bash
   b2c cap tasks my-commerce-app --site-id RefArch
   ```

   Follow the Business Manager links provided to configure service credentials and site preferences.

7. Test end-to-end on your sandbox storefront

8. Verify installation status:

   ```bash
   b2c cap list --site-id RefArch
   ```

9. Iterate: make changes, re-validate, re-package, re-install

> **Tip:** During rapid development, install directly from the source directory (skipping the separate package step). The CLI packages and uploads for you:
>
> ```bash
> b2c cap install ./my-commerce-app --site-id RefArch
> ```

## Iterating Across Sandbox Environments

Most ISVs and SIs maintain more than one sandbox: a personal dev sandbox, a shared QA sandbox, and (for ISVs) a partner staging sandbox. The B2C CLI supports per-environment configuration through named instances in `dw.json` and the `--instance` flag. See [Multiple Instances](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html#multiple-instances).

Practical patterns:

- **Switch instances by environment variable.** Set `SFCC_HOSTNAME`, `SFCC_USERNAME`, and `SFCC_PASSWORD` per shell session (or use a `.env` loader) to point `b2c cap install` at a different sandbox without changing your project.
- **Reuse the same CAP across environments.** Package once, install many times. The same `.zip` produced by `b2c cap package` is valid on any compatible sandbox.
- **Reset between iterations.** Use `b2c cap uninstall <app-id> --site-id <site-id>` to remove an app cleanly before installing a new build. This exercises your uninstall IMPEX as part of the dev loop.
- **Retrieve an available source package.** Use `b2c cap pull <app-name> --site-id <site-id>` to download the retained WebDAV archive when it has a persisted version and is still available. Registry apps can fall back to the registry package. This command doesn't reconstruct the deployed state.

## Inspecting Installed App State

When an installation misbehaves, use the CLI to inspect what the platform actually recorded on the instance:

- **List installed apps:** `b2c cap list --site-id <site-id>` returns the apps registered against a site, including their version and lifecycle state. Use `--json` to pipe into `jq` for scripted checks.
- **View configuration tasks:** `b2c cap tasks <app-name> --site-id <site-id>` returns the merchant task list with deep links to Business Manager. If a task is unexpectedly incomplete, the deep link points directly at the BM page that needs attention.
- **Pull the live package:** `b2c cap pull <app-name> --site-id <site-id>` downloads the CAP exactly as the platform unpacked it. Diff the result against your source build.
- **Check the job log:** Lifecycle errors (`INSTALL_FAILED`, `CONFIGURATION_FAILED`, `UNINSTALL_FAILED`) write detailed step-by-step output to **Administration** > **Operations** > **Job Schedules** in Business Manager.
- **Read `CommerceFeatureState` directly:** The system object's `InstallationMetadata` JSON field contains the job execution ID, deployed cartridge names, and any error details. See [Monitoring and Support](/docs/commerce/b2c-commerce/guide/post-publication.md#monitoring-and-support).

## CI/CD Pipeline Integration

The `cap validate` and `cap package` commands are local-only and require no instance credentials, which makes them well-suited to CI. A typical pipeline:

1. **On pull request:** Run `b2c cap validate <path> --json` to fail the build on basic manifest or CAP structure errors. Pair with `/validate-impex` (Claude Code) or your own IMPEX linter to validate IMPEX content.
2. **On merge to a release branch:** Run `b2c cap package <path> --output ./dist --json` to produce the release `.zip`. Capture the file (and its SHA-256) as a build artifact.
3. **On promotion to a partner sandbox:** Run `b2c cap install ./dist/<app>.zip --site-id <site-id> --json` against a dedicated CI sandbox. Configure `SFCC_SERVER`, `SFCC_CLIENT_ID`, an OAuth credential such as `SFCC_CLIENT_SECRET`, and WebDAV authorization through client permissions or `SFCC_USERNAME`/`SFCC_PASSWORD`. Store credentials in the CI platform's encrypted, masked, environment-scoped secret store; prefer a dedicated least-privilege OAuth client, and never commit secrets to `dw.json` or source control. Follow with `b2c cap list --site-id <site-id> --json` to confirm the install succeeded. See [CLI Authentication Setup](#cli-authentication-setup) for the credential model.
4. **On registry publish (ISVs only):** Diff against the previous version (`/diff-versions`) to generate a changelog, then open a PR against the registry that updates the `version`, `zip`, and `sha256` fields. Do not edit `catalog.json` manually — registry CI handles version tracking.

> **Tip:** All `cap` commands accept `--json`. Prefer JSON output in CI to parse exit codes and structured error messages instead of scraping logs.

## Feature Toggles and Prerequisites

Enable every feature toggle that your app requires before installation. When the supplied app ID and domain match a registry entry, the installer checks its `requiredFeatureToggle`, when present, and fails if that toggle is disabled. The installer doesn't enable prerequisite toggles for you.

Verify that the top-level `CommerceAppsEnabled` toggle is enabled on your instance. The install and uninstall jobs need this toggle to execute. This toggle is enabled by default on sandboxes provisioned for Commerce Apps development. If your install job returns an error about Commerce Apps not being enabled, contact your administrator.

## Troubleshooting Development Issues

- **Install job returns `INSTALL_FAILED`:** Check the job execution log in Business Manager (**Administration** > **Operations** > **Job Schedules**). Common causes: missing OCAPI permissions, WebDAV access issues, or IMPEX validation errors.
- **App appears installed but hooks don't fire:** Verify the site's cartridge path includes your app's cartridges. For tax apps, verify `TaxAppHooksEnabled` is `true` in the feature toggles. Also confirm that SiteGenesis or SFRA cartridges aren't on the cartridge path — see [Storefront compatibility](/docs/commerce/b2c-commerce/guide/reference.md#storefront-compatibility) for details.
- **Re-install after code version switch:** If you switch the active code version, cartridges may be missing. Re-running the install job re-copies cartridges without re-running IMPEX (idempotency behavior).
- **IMPEX placeholder not replaced:** Ensure your file extension is one of the supported text types (`.xml`, `.csv`, `.txt`, `.json`, `.properties`, `.js`). Binary files are copied without placeholder replacement.

<!-- document id=4bf6f61bff547e8b4e3b4f8bf3acc770dd8758b4321b488e11d73a7b196193e1 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-dev-workflow.md -->

# Development Workflow Differences with PWA Kit

PWA Kit uses a traditional Webpack-based development server with configuration spread across multiple files. Storefront Next leverages Vite for faster development with native ESM, instant HMR, and type-safe configuration. The shift to Vite provides a more modern developer experience with faster feedback loops and better tooling integration.

## Key Differences

| Aspect        | PWA Kit             | Storefront Next              |
| ------------- | ------------------- | ---------------------------- |
| Dev Server    | Webpack Dev Server  | Vite Dev Server              |
| CLI Tool      | `pwa-kit-dev start` | `sfnext dev`                 |
| HMR           | Webpack HMR         | Vite native HMR              |
| Config Format | JavaScript          | TypeScript                   |
| Env Vars      | Standard .env       | Typed with `PUBLIC__` prefix |
| Testing       | Jest                | Vitest                       |
| Type Safety   | Optional            | Required                     |

## Key Similarities

1. Port conventions: Both can run on any port.
2. API proxy pattern: Both use `/mobify/proxy/` path.
3. Environment variables: Both support .env files.
4. Node.js debugging: Both support `--inspect` flag.
5. Express-based: Both use Express for SSR.

## Storefront Conversion Considerations

1. Port Change

   - Update any hardcoded port references from 3000 to 5173.
   - Or configure Vite to use port 3000.

2. Environment Variables

   - Convert standard env vars to `PUBLIC__` prefix format.
   - Update .env files with new naming convention.

3. Config Migration

   - Convert `config/default.js` to `config.server.ts`.
   - Add TypeScript types for configuration.

4. Testing Migration
   - Convert Jest tests to Vitest.
   - Update test configuration files.

<!-- document id=e1b2538c5a01b8ca7750e73d0796fb065a8bb58228dbdd25222d77c042787d96 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_dimension_tables.md -->

# Dimension Tables

Dimension tables store descriptive attributes that provide context to the facts.

| Dimension Table Name                                             | Description                                                                                                                                                                              | Indices                                                                                                                                                                                                                              |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [ccdw_dim_business_channel](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_business_channel.md)   | Categorizes different business channels.                                                                                                                                                 | `business_channel_id`, `business_type,order_channel`                                                                                                                                                                                 |
| [ccdw_dim_campaign](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_campaign.md)                   | Describes various marketing campaigns.                                                                                                                                                   | `campaign_id`, `ncampaign_id`                                                                                                                                                                                                        |
| [ccdw_dim_coupon](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_coupon.md)                       | Provides details about coupons.                                                                                                                                                          | `coupon_id`, `ncoupon_id`                                                                                                                                                                                                            |
| [ccdw_dim_currency](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_currency.md)                   | Provides details about various currencies. Each row represents an ISO 4217 currency.                                                                                                     | `currency_id`, `alpha_code`                                                                                                                                                                                                          |
| [ccdw_dim_customer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_customer.md)                   | Contains detailed information about customers.                                                                                                                                           | `customer_id`, `ncustomer_id`                                                                                                                                                                                                        |
| [ccdw_dim_date](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_date.md)                           | Contains various attributes related to dates, providing detailed temporal information. Each record represents a calendar date and its component parts (year, quarter, month, week, day). | `day_id`, `day_timestamp`, `week_id`, `week_timestamp`, `month_id`, `month_timestamp`, `quarter_id`, `quarter_timestamp`, `year_id`, `year_timestamp`, `weekyear_id`, `weekyear_timestamp`, `year_of_era,month_of_year,day_of_month` |
| [ccdw_dim_geography](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_geography.md)                 | Provides geographical information, particularly for regions and countries. Each region rolls up to a country.                                                                            | `geography_id`, `iso3166_alpha_code`, `country_code`                                                                                                                                                                                 |
| [ccdw_dim_locale](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_locale.md)                       | Stores information about different locales, such as language and country settings.                                                                                                       | `locale_id`, `locale_code`                                                                                                                                                                                                           |
| [ccdw_dim_location](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location.md)                   | Represents individual physical locations, likely for inventory or shipping.                                                                                                              | `location_id`, `nlocation_id`                                                                                                                                                                                                        |
| [ccdw_dim_location_group](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_location_group.md)       | Groups physical locations together.                                                                                                                                                      | `location_group_id`, `nlocation_group_id`                                                                                                                                                                                            |
| [ccdw_dim_payment_method](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_payment_method.md)       | Lists available payment methods.                                                                                                                                                         | `payment_method_id`, `npayment_method_id`                                                                                                                                                                                            |
| [ccdw_dim_product](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_product.md)                     | Contains detailed information about products and SKUs. Each SKU rolls up to a product.                                                                                                   | `sku_id`, `nsku_id`, `product_id`, `nproduct_id`                                                                                                                                                                                     |
| [ccdw_dim_promotion](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_promotion.md)                 | Describes various promotions.                                                                                                                                                            | `promotion_id`, `npromotion_id`                                                                                                                                                                                                      |
| [ccdw_dim_site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_site.md)                           | Stores information about different e-commerce sites or storefronts.                                                                                                                      | `site_id`, `nsite_id,nrealm_id`                                                                                                                                                                                                      |
| [ccdw_dim_source_code_group](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_source_code_group.md) | Categorizes source code groups, often used for tracking marketing channels.                                                                                                              | `source_code_group_id`, `nsource_code_group_id`                                                                                                                                                                                      |
| [ccdw_dim_time](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_time.md)                           | Contains various attributes related to time, providing detailed temporal information within a day. Each row represents a minute of a clock.                                              | `time_id`, `minute_of_day`, `hour_of_day`                                                                                                                                                                                            |
| [ccdw_dim_timezone](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_timezone.md)                   | Contains information about different time zones.                                                                                                                                         | `timezone_id`, `ntimezone_id`                                                                                                                                                                                                        |
| [ccdw_dim_traffic_source](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_traffic_source.md)       | Describes attributed external traffic sources.                                                                                                                                           | `traffic_source_id`                                                                                                                                                                                                                  |
| [ccdw_dim_user_agent](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_dim_user_agent.md)               | Stores details about user agents, which describe the client software making a request.                                                                                                   | `user_agent_id`, `nuser_agent_id`, `ua_family_code`, `ua_class_code`, `ua_family_vendor_code`, `crawler_category_code`, `os_family_code`, `os_family_vendor_code`, `device_class_code`, `device_brand_code`                          |

<!-- document id=7078e9930160832697495de03faace7d831948f213d472db9f93e0e83a8b998a url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-download-pi-data.md -->

# Download Shopper Information in SFRA

When you implement an SFRA-based storefront, consider providing your shoppers with a mechanism to download their data. The `plugin_datadownload` cartridge provides a sample implementation of this capability.

In the sample implementation, registered users see a **Download My Data** button on the **My Account** page. When a shopper clicks this button, SFRA downloads a JSON file to the shopper's browser. This file contains the following information:

- Profile
- Address
- Payment instruments
- Orders
- Wish lists
- Gift registries
- Shopping lists

The JSON file illustrates the type of information to provide to your shoppers. Your business can provide different data in a different format. To use the sample implementation, uploading the `plugin_datadownload` cartridge into your instance and add the cartridge to your [cartridge path](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-configuring-sfra.md#configure-the-sfra-cartridge-path).

## Sample JSON File

This sample file shows the type of information to provide to the shopper.

```
{
  "profile": {
    "birthday": "1988-10-21T00:00:00.000Z",
    "companyName": "",
    "customerNo": "D00000001",
    "email": "janedoe@mycompany.com",
    "fax": "",
    "firstName": "Test1",
    "gender": "Female",
    "jobTitle": "",
    "lastLoginTime": "2018-02-14T20:07:31.074Z",
    "lastName": "Doe",
    "lastVisitTime": "2018-02-14T20:07:31.074Z",
    "phoneBusiness": "",
    "phoneHome": "",
    "phoneMobile": "",
    "preferredLocale": "",
    "previousLoginTime": "2015-05-18T20:43:17.000Z",
    "previousVisitTime": "2015-05-18T20:43:17.000Z",
    "salutation": "",
    "secondName": "",
    "suffix": "",
    "taxID": null,
    "taxIDMasked": null,
    "taxIDType": null,
    "title": "",
    "male": false,
    "female": true,
    "nextBirthday": "2018-10-21T00:00:00.000Z"
  },
  "addressbook": [
    {
      "address1": "104 Presidential Way",
      "address2": null,
      "city": "Woburn",
      "companyName": null,
      "countryCode": "us",
      "firstName": "Test1",
      "fullName": "Test1 User1",
      "id": "Home",
      "jobTitle": null,
      "lastName": "User1",
      "phone": "781-555-1212",
      "postalCode": "01801",
      "postBox": null,
      "salutation": null,
      "secondName": null,
      "stateCode": "MA",
      "suffix": null,
      "suite": null,
      "title": null
    },
    {
      "address1": "91 Middlesex Tpke",
      "address2": null,
      "city": "Burlington",
      "companyName": null,
      "countryCode": "us",
      "firstName": "Jane",
      "fullName": "Jane Doe",
      "id": "Work",
      "jobTitle": null,
      "lastName": "Doe",
      "phone": "781-555-1212",
      "postalCode": "01803",
      "postBox": null,
      "salutation": null,
      "secondName": null,
      "stateCode": "MA",
      "suffix": null,
      "suite": null,
      "title": null
    }
  ],
  "wallet": [],
  "orders": [],
  "productList": {
    "whishlists": [],
    "giftregistries": [],
    "shoppinglists": []
  },
  "thirdpartydata": {}
}
```

## Implementation Details

The sample implementation provides a **Download my data** button in the `accountDashboard.isml` template.

```
<div class="row mb-3 clearfix hidden-sm-down">
	<div class="col">
		<div>
			<a href="${URLUtils.url('Account-DataDownload')}" class="btn btn-outline-primary pull-right"
			   role="button" aria-pressed="true">
				${Resource.msg('button.download.data', 'datadownload', null)}
			</a>
		</div>
	</div>
</div>
```

When the shopper clicks the button, the `Account-DataDownload` route is called. This route is implemented in `Account.js`.

```
'use strict';

var server = require('server');
server.extend(module.superModule);

var userLoggedIn = require('*/cartridge/scripts/middleware/userLoggedIn');

server.get('DataDownload',
    server.middleware.https,
    userLoggedIn.validateLoggedIn,
    function (req, res, next) {
        var customer = req.currentCustomer.raw;
        var dataDownloadHelper = require('~/cartridge/scripts/dataDownloadHelper');
        var site = require('dw/system/Site');

        var fileName = site.current.name
            + '_' + customer.profile.firstName
            + '_' + customer.profile.lastName
            + '.json';

        var profileData = dataDownloadHelper.getProfileData(customer);

        res.setHttpHeader(res.base.CONTENT_DISPOSITION, 'attachment; filename="' + fileName + '"');
        res.setContentType('application/octet-stream');
        res.print(profileData);

        next();
    }
);

module.exports = server.exports();

```

This route relies on the helper script `dataDownloadHelper.js`, which provides several helper functions, such as `getWallet(profile)`, `getWishlists(customer, ProductListMgr)`, and so on. The helper script exports `getProfileData`, which calls the helper functions, constructs the JSON string, and returns the result to the shopper's browser.

```

exports.getProfileData = function (profile) {
    var ProductListMgr = require('dw/customer/ProductListMgr');
    var downloadJSONObj = {};

    downloadJSONObj.profile = getProfile(profile);
    downloadJSONObj.addressbook = getAddressBook(profile);
    downloadJSONObj.wallet = getWallet(profile);
    downloadJSONObj.orders = getOrders(profile);
    downloadJSONObj.productList = {
        whishlists: getWishLists(ProductListMgr),
        giftregistries: getGiftregistries(ProductListMgr),
        shoppinglists: getShoppingLists(ProductListMgr)
    };

    downloadJSONObj.thirdpartydata = {};
    return JSON.stringify(downloadJSONObj, null, 2);
};

```

<!-- document id=30464b0b82b10f837a3b8420d95550b36a92ecd6dff47b774d31fed47edb7b3a url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-automatic-certs.md -->

# eCDN Automatic Certificates

Use eCDN automated certificates to serve storefront traffic over HTTPS without the hassle of managing certificates.

This guide covers how to enable it on new and existing hostnames as well as legacy eCDN zones using the CDN Zones API.

**note:** **You can also manage automated certificates in Business Manager.** _For more information, see [Add Managed SSL Certificates](https://help.salesforce.com/s/articleView?id=cc.b2c_add_managed_ssl_certificates.htm&type=5)_.

## Prerequisites

1. Familiarize yourself with [Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)
2. You must have an Account Manager API Client with the scope `sfcc.cdn-zones.rw`.
3. You must have an existing proxy zone associated with the hostname you'd like to use.
4. You must have a proxy zone. Automatic certificates are not supported by legacy zones. If you have a legacy zone, first [migrate to a proxy zone](#migrate-from-legacy-zones-to-proxy-zones-to-use-automatic-certificates).
5. You must know the zone ID of the proxy zone to be used with automatic certificates. To get this info, use [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo).

## Enable Automatic Certificates on an Existing Hostname

To use an automated certificate with an existing hostname that is associated with a custom certificate, lookup its certificate ID with [getCertificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getCertificates). Next, call [updateCertificate](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateCertificate):

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/certificates/$CERTIFICATE" \
  --request 'PATCH' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "hostname": "www.example.com",
    "certificateType": "automatic",
    "certificateAuthority": "lets_encrypt"
  }'
```

This call replaces the existing custom certificate with an automated certificate without downtime.

Let's review the data provided in the request body.

The value of `hostname` is the domain you'd like to use with the automated certificate. `certificateType` must be set to `automatic`. Finally, `certificateAuthority` controls which certificate authority is used to issue the certificate. The value must be either `lets_encrypt` or `google`. The choice of providers is up to you.

## Enable Automatic Certificates on a New Hostname

To use an automated certificate with a new hostname, follow the instructions to [configure eCDN](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_the_embedded_cdn.htm&type=5). Rather than adding a certificate through Business Manager, call [addCertificateForZone](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=addCertificateForZone):

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/certificates" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "hostname": "www.example.com",
    "certificateType": "automatic",
    "certificateAuthority": "lets_encrypt"
  }'
```

## Migrate from Legacy Zones to Proxy Zones to Use Automatic Certificates

Automatic certificates are not available for legacy zones.

**note:** A zone is a legacy zone if it does not end in `cc-ecdn.net`.

For more information on proxy and legacy zones, review [this article](https://help.salesforce.com/s/articleView?id=cc.b2c_ecdn_proxy_zone_faq.htm&type=5).

To use automatic certificates, you must first migrate to proxy zones.

To migrate to a proxy zone:

1. Create the storefront zones with [createStorefrontZone](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createStorefrontZone).
2. Copy required settings from your legacy zones to the proxy zones.
3. Request an automatic certificate with [addCertificateForZone](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=addCertificateForZone).
4. Perform a DNS cutover by updating your storefront's DNS records.

First, create your storefront zone:

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/storefront-zones" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "domainName": "example.com"
  }'
```

**note:** You must create the storefront zone for both your `prd` and `dev` organization IDs to continue to manage your zones in Business Manager.

Second, copy any required settings from your legacy zones using [createFirewallRule](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createFirewallRule), [updateSpeedSettings](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateSpeedSettings) and [updateSecuritySettings](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateSecuritySettings).

Third, request an automatic certificate with [addCertificateForZone](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=addCertificateForZone):

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/certificates" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "hostname": "www.example.com",
    "certificateType": "automatic",
    "certificateAuthority": "lets_encrypt"
  }'
```

Finally, perform a DNS cutover by updating your storefront's DNS records. Get the DNS CNAME record value from [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo)'s `name` property.

```txt
www.example.com    CNAME    commcloud.prod-abcd-example-com.cc-ecdn.net.
```

## Advanced Topics

Refer to the following sections for additional use case information.

### Revert to Custom Certificates

You can update an automatic certificate to a custom certificate using [updateCertificate](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateCertificate).

### CDN Stacking

In a stacking configuration, certificate renewals require validation, just as when certificates are initially requested. When traffic is flowing through eCDN, validation is done using HTTP by serving records from the eCDN edge automatically without any user intervention.

In a stacking scenario where regular store traffic flows through the stacked config, some stacked service configurations don’t pass the validation records along correctly. In such a scenario, the initial validation method doesn’t matter. Salesforce doesn’t have control of your DNS and can’t automatically place a new TXT record. The only means of automated validation is through HTTP validation.

For HTTP validation to complete, eCDN must serve a validation value for a URI matching this pattern:

```text
http://<hostname>/.well-known/acme-challenge/<random-validation-key>
```

**tip:** This check is completed over HTTP, not HTTPS. Confirm the URI is available over HTTP.
**note:** When using eCDN-managed certificates with a third-party CDN stacked on top, opting for TXT record validation is required every three months due to the certificate's automatic renewal cycle. Without domain control validation (DCV) delegation, TXT record updates are required every 2–3 months. DCV delegation automates the TXT verification process and is helpful if you're experiencing issues with HTTP validation. If needed, contact support for a DCV delegation UUID to include in your DNS record.
If you use certificate pinning, using automatic certificates is not possible as the certificate may be updated at any time.

### Validation Methods

There are two choices of validation for automated certificates: HTTP and DNS.

HTTP validation is used by default is the right choice in most cases.

Where a short issue delay is not acceptable, use DNS validation by providing the `certificateValidation` request property with a value of `txt`:

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/certificates" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "hostname": "www.example.com",
    "certificateType": "automatic",
    "certificateAuthority": "lets_encrypt",
    "certificateValidation": "txt"
  }'
```

Use [getCertificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getCertificates)'s `customHostnameVerificationTXTName` and `customHostnameVerificationTXTValue` response properties to create your validation DNS TXT record.

You can change a certificate's validation type using [updateCertificate](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateCertificate).

## Constraints

- Automated certificates are only available for proxy zones.
- You can request up to five hundred automated certificates per zone.
- Automated certificates are only available from Let's Encrypt and Google certificate authorities. To use a different certificate authority or a certificate with extended validation, use custom certificates.

<!-- document id=23d8a55f8450f7264214ced5b0f9c10ccdd8e30a3c30c4211b98d220e7c49548 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-cache-rules.md -->

# eCDN Cache Rules

Cache rules allow you to control which content is eligible for caching at the eCDN. By default, eCDN only caches based on file extension and does not cache HTML pages or JSON responses. Cache rules enable you to make these previously uncacheable resources eligible for edge caching, which is a prerequisite for using cache purging by tags or paths.

Cache rules make content _eligible_ for caching, but do not force caching. Your origin server must send appropriate `Cache-Control` headers for content to actually be cached. When a cache rule matches a request, eCDN evaluates specific conditions to determine whether to cache the resource.

eCDN does **not** cache the resource if a cache rule matches and **any** of the following conditions are true:

- The `Cache-Control` header is set to `private`, `no-store`, `no-cache`, or `max-age=0`.
- No `Cache-Control` header is present.
- The `Set-Cookie` header exists.
- The HTTP request method is anything other than `GET`.

eCDN **does** cache the resource if a cache rule matches and **all** of the following conditions are true:

- The request method is `GET`.
- No Set-Cookie header is present.
- Either the `Cache-Control` header is set to `public` and `max-age` is greater than 0, or the `Expires` header is set to a future date.
  - If both `max-age` and an `Expires` header are set, `max-age` takes precedence.
  - If `s-maxage` is present, it takes precedence over `max-age`.

For more resources on caching in general, refer to the following resources:

- [Content Cache](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-content-cache.html)
- [SCAPI Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)
- [Cache-Control HTTP Header](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#cache-control-http-header)

## Default Cached File Extensions

eCDN caches content based on file extension (not MIME type).

By default, eCDN caches the following file extensions:

Supported formats:

- 7Z, AVI, AVIF, APK, BIN, BMP, BZ2
- CLASS, CSS, CSV, DOC, DOCX, DMG
- EJS, EOT, EPS, EXE, FLAC, GIF, GZ
- ICO, ISO, JAR, JPG, JPEG, JS
- MID, MIDI, MKV, MP3, MP4, OGG, OTF
- PDF, PICT, PLS, PNG, PPT, PPTX, PS, RAR
- SVG, SVGZ, SWF, TAR, TIF, TIFF, TTF
- WEBM, WEBP, WOFF, WOFF2
- XLS, XLSX, ZIP, ZST

If your content has an extension that is not in the preceding list, use cache rules to make it eligible for caching. eCDN does not cache HTML, JSON, XML, or TXT files, except robots.txt.

The maximum cacheable file size is 5 GB.

## Cache Rule Parameters

### Required Parameters

| Parameter     | Type   | Description                                                                                                                                                                |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `description` | string | A description of the cache rule.                                                                                                                                           |
| `expression`  | string | A rule expression that defines when to apply the rule. Must use supported fields as described in the Supported Expression Fields section. Maximum length: 4096 characters. |
| `action`      | string | The action to perform. Currently, only `cache` is supported.                                                                                                               |

### Optional Parameters

| Parameter                 | Type             | Default                             | Description                                                                                                                                                                                                                                                     |
| ------------------------- | ---------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                 | boolean          | `true`                              | Whether the rule is enabled.                                                                                                                                                                                                                                    |
| `excludeQueryStrings`     | array of strings | `null` (all query strings included) | List of query string parameters to **exclude** from the cache key. If provided, must be non-empty. Use empty array `[]` in PATCH to clear existing exclusions.                                                                                                  |
| `ignoreQueryStringsOrder` | boolean          | `false`                             | If `true`, query strings are sorted alphabetically before creating the cache key. This means `?a=1&b=2` and `?b=2&a=1` share the same cache entry.                                                                                                              |
| `respectStrongEtags`      | boolean          | `false`                             | If `true`, eCDN uses strong ETag header validation to ensure that resources in the cache and on the origin server are byte-for-byte identical.                                                                                                                  |
| `position`                | object           | Last position                       | Specifies where to insert the rule in the ruleset. Must specify either `before` or `after` with a rule ID. Cache rules are evaluated in the order they appear in the ruleset. Multiple cache rules can match the same request, and the last matching rule wins. |

## Supported Expression Fields for Cache Rules

Cache rule expressions use the same operators and functions as rate limiting rules and custom rules, and support a different set of fields. See [Comparison Operators](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md#comparison-operators), [Logical Operators](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md#logical-operators), and [Functions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md#functions).

Cache rule expressions support the following fields:

| Field                  | Description                                                                                                                                                    | Usage in Expression               | Type                | Example                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **URI Full**           | Represents the full URI as received by the web server.                                                                                                         | `http.request.full_uri`           | String              | `http.request.full_uri eq "https://www.example.com/path/index?section=123456&expand=comments"`                                             |
| **URI**                | Represents the URI path and query string of the request.                                                                                                       | `http.request.uri`                | String              | `http.request.uri eq "/path/index?section=123456&expand=comments"`                                                                         |
| **URI Path**           | Represents the URI path of the request.                                                                                                                        | `http.request.uri.path`           | String              | `http.request.uri.path eq "/path/index"`                                                                                                   |
| **URI Query String**   | Represents the entire query string, without the `?` delimiter.                                                                                                 | `http.request.uri.query`          | String              | `http.request.uri.query eq "section=123456&expand=comments"`                                                                               |
| **URI Path Extension** | The lowercased file extension in the URI path without the dot (`.`) character.                                                                                 | `http.request.uri.path.extension` | String              | `http.request.uri.path.extension eq "html"`                                                                                                |
| **Host Name**          | Represents the host name used in the full request URI.                                                                                                         | `http.host`                       | String              | `http.host eq "www.example.com"`                                                                                                           |
| **Cookie**             | Represents the entire cookie as a string.                                                                                                                      | `http.cookie`                     | String              | `http.cookie eq "session=8521F670545D7865F79C3D7BEDC29CCE;-background=light"`                                                              |
| **Request Cookies**    | The `Cookie` HTTP header associated with a request represented as a Map (associative array).                                                                   | `http.request.cookies`            | `Map<String>\Array` | `any(http.request.cookies["app"][*] eq "test")`                                                                                            |
| **HTTP Headers**       | Represents HTTP request headers as a Map (or associative array).                                                                                               | `http.request.headers`            | `Map<String>\Array` | `any(http.request.headers["content-type"][*] eq "application/json")`                                                                       |
| **HTTP Referer**       | Represents the HTTP Referer request header, which contains the address of the web page that linked to the currently requested page.                            | `http.referer`                    | String              | `http.referer contains "www.example.com"`                                                                                                  |
| **User Agent**         | Represents the HTTP user agent, a request header that contains a characteristic string to allow identification of the client operating system and web browser. | `http.user_agent`                 | String              | `http.user_agent eq "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.61 Safari/537.36"` |
| **X-Forwarded-For**    | The full value of the `X-Forwarded-For` HTTP header.                                                                                                           | `http.x_forwarded_for`            | String              | `http.x_forwarded_for eq "203.0.113.195, 70.41.3.18"`                                                                                      |
| **SSL/HTTPS**          | Returns true when the HTTP connection to the client is encrypted.                                                                                              | `ssl`                             | Boolean             | `ssl`                                                                                                                                      |

### Expression Examples

Match specific path pattern using regex:

```text
(http.request.uri.path matches ".*/product/[^/]+/?$")
```

Match on file extension type:

```text
(http.request.uri.path.extension eq "html")
```

Combine conditions:

```text
(http.request.uri.path matches ".*/product/[^/]+/?$" and http.request.uri.path.extension eq "html")
```

Explicitly exclude certain paths:

````text
(http.request.uri.path.extension eq "html" and not (http.request.uri.path contains "/checkout" or http.request.uri.path contains "/account"))
```sh

## API Usage

### Create a Cache Rule

This endpoint creates a cache rule in the specified zone.

**important:** A maximum of 200 cache rules is allowed in a single zone.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/cache/rules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "description": "Cache product detail pages",
    "expression": "(http.request.uri.path matches \".*/product/[^/]+/?$\" and http.request.uri.path.extension eq \"html\")",
    "action": "cache",
    "excludeQueryStrings": ["gclid", "utm_campaign"],
    "ignoreQueryStringsOrder": true,
    "respectStrongEtags": true,
    "enabled": true
}'
````

Sample success response: 201 HttpStatus code response body contains the cache rule that was created.

````json
{
  "data": [
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Cache product detail pages",
      "expression": "(http.request.uri.path matches \".*/product/[^/]+/?$\" and http.request.uri.path.extension eq \"html\")",
      "action": "cache",
      "excludeQueryStrings": ["gclid", "utm_campaign"],
      "ignoreQueryStringsOrder": true,
      "respectStrongEtags": true,
      "enabled": true,
      "lastUpdated": "2022-12-14T21:25:22.329194Z"
    }
  ]
}
```sh

### Get All Cache Rules

This endpoint returns all of the cache rules in the specified zone in order of priority. If no cache rules exist, an empty array `[]` is returned (not 404).

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/cache/rules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'
````

Sample success response: 200 HttpStatus code response body contains all of the cache rules in the specified zone.

```json
{
  "data": [
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Cache product detail pages",
      "expression": "(http.request.uri.path matches \".*/product/[^/]+/?$\" and http.request.uri.path.extension eq \"html\")",
      "action": "cache",
      "excludeQueryStrings": ["gclid", "utm_campaign"],
      "ignoreQueryStringsOrder": true,
      "respectStrongEtags": true,
      "enabled": true,
      "lastUpdated": "2022-12-14T21:25:22.329194Z"
    },
    {
      "ruleId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "description": "Cache category pages",
      "expression": "(http.request.uri.path matches \".*/category/[^/]+/?$\" and http.request.uri.path.extension eq \"html\")",
      "action": "cache",
      "ignoreQueryStringsOrder": false,
      "respectStrongEtags": false,
      "enabled": true,
      "lastUpdated": "2022-12-14T21:47:24.323223Z"
    }
  ]
}
```

**note:** `excludeQueryStrings` is only included in the response when query strings are explicitly excluded. If all query strings are included in the cache key, this field is omitted from the response.

### Update a Cache Rule

This endpoint updates the requested cache rule. If the requested rule does not exist, a 404 Not Found response is returned.

- You must provide at least one cache rule parameter in the request body.
- In the scenario where you have set `excludeQueryStrings` but wish to remove it (and thus have all query strings included in the cache key), you must include `"excludeQueryStrings": []` in the request body to clear the value.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/cache/rules/2c0fc9fa937b11eaa1b71c4d701ab86e" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "description": "Cache product detail pages - updated",
    "excludeQueryStrings": ["gclid", "utm_campaign", "ref", "source"],
    "enabled": false
}'
```

Sample success response: 200 HttpStatus code response body contains the requested cache rule.

````json
{
  "data": [
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Cache product detail pages - updated",
      "expression": "(http.request.uri.path matches \".*/product/[^/]+/?$\" and http.request.uri.path.extension eq \"html\")",
      "action": "cache",
      "excludeQueryStrings": ["gclid", "utm_campaign", "ref", "source"],
      "ignoreQueryStringsOrder": true,
      "respectStrongEtags": true,
      "enabled": false,
      "lastUpdated": "2022-12-14T22:30:15.123456Z"
    }
  ]
}
```sh

### Delete a Cache Rule

This endpoint deletes the requested cache rule. If the requested rule doesn't exist, a 404 Not Found response is returned.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/cache/rules/2c0fc9fa937b11eaa1b71c4d701ab86e" \
--request 'DELETE' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'
````

Sample success response: 204 HttpStatus Code (No Content)

**note:** Deleting a rule doesn't purge cached content. Use the cache purge API if you need to immediately invalidate cached content.

## Best Practices and Common Mistakes

### Best Practices

1. Understand origin cache headers. Cache rules make content eligible, but origin must send the appropriate `Cache-Control` headers.
2. Start with specific rules. Begin with expressions scopes to specific pages and gradually expand.
3. Test in lower environments first. Always test cache rules in a development or staging environment before applying to production.
4. Use cache tags. Set `Cache-Tag` headers from origin to enable tag-based purging.
5. Exclude specific query strings. Use `excludeQueryStrings` to prevent cache fragmentation from tracking parameters and increase cache hit ratios.
6. Monitor cache hit ratios using BM Analytics or Logpush. Use the **Analytics** tab in Business Manager to monitor cache performance by viewing cache statuses. Alternatively, use [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html) to monitor logs and view cache statuses, response times, and more.

### Common Mistakes

1. Caching authentication endpoints or personalized content. Avoid caching paths like `/login`, `/account`, `/cart`, etc. that contain user-specific data. Ensure origin sends the correct headers `private`, `no-store`, `no-cache`, or `max-age=0` or explicitly exclude the paths from any cache rules.
2. Overly broad expressions. Avoid expressions that are too broad and match all traffic. Use specific path patterns instead.
3. Assuming content will be cached. Cache rules make content eligible, but content is only cached if:
   1. Origin sends `Cache-Control: public, max-age=X` (where X \> 0\).
   2. No `Set-Cookie` header is present.
   3. Request method is `GET`.
4. After enabling caching, eligible requests are served from eCDN cache. Keep in mind when monitoring system statistics that these requests won't reach the origin.

## Common Use Cases

### Cache PWA Kit Product Detail Pages

PWA Kit serves server-side rendered HTML product pages that aren't cached by default. Create a cache rule to make product pages eligible for caching. For more information about improving performance for PWA Kit storefronts, see [Maximize Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.html).

Sample cache rule:

```json
{
  "description": "Cache product detail pages",
  "expression": "(http.request.uri.path matches \".*/product/[^/]+/?$\" and http.request.uri.path.extension eq \"html\")",
  "action": "cache",
  "excludeQueryStrings": ["gclid", "utm_campaign"],
  "ignoreQueryStringsOrder": true,
  "respectStrongEtags": true,
  "enabled": true
}
```

### Cache SFRA Content Pages

SFRA content asset pages, landing pages, and marketing pages are HTML that you can cache.

Sample cache rule:

```json
{
  "description": "Cache SFRA content and marketing pages",
  "expression": "((http.request.uri.path contains \"/content/\" or http.request.uri.path contains \"/campaigns/\") and http.request.uri.path.extension eq \"html\")",
  "action": "cache",
  "ignoreQueryStringsOrder": true,
  "enabled": true
}
```

## Integrate with Cache Purge

Cache rules make content eligible for selective cache purging using the existing cache purge API. After creating cache rules, you can purge cached content by path or by tag. For details, see [cachePurge](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=cachePurge).

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn cache purge \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --path www.example.com/dw/shop/v25_10/products/12345
```

Purge by path:

```json
POST /{organizationId}/zones/{zoneId}/cachepurge
{
  "path": "www.example.com/dw/shop/v25_10/products/12345"
}
```

Purge by tag:

Set `Cache-Tag` headers from your origin, then purge by tag.

Origin response headers:

```text
Cache-Control: public, max-age=300
Cache-Tag: product-12345, category-shoes, page-product-detail
```

Purge request:

```json
POST /{organizationId}/zones/{zoneId}/cachepurge
{
  "tags": ["product-12345"]
}
```

## Frequently Asked Questions (FAQ)

### Can I use cache rules to bypass cache?

CDN-API cache rules currently only support making content eligible for caching (`action: "cache"`). As a workaround, ensure your origin sends `Cache-Control: private`, `no-store`, `no-cache`, or `max-age=0` for content that should not be cached. eCDN respects these headers and does not cache the content.

### What happens if multiple cache rules match?

All matching rules are evaluated, and **the last matching rule's settings take precedence**.

### Do cache rules override origin Cache-Control headers?

No, cache rules respect origin `Cache-Control` headers.

### Can I cache POST requests?

No. eCDN only caches GET requests, regardless of cache rule configuration. Cache rules can match POST/PUT/DELETE requests, but those requests won't be cached. You don't need to filter by HTTP method in your expression because eCDN automatically only caches GET requests.

### Why is my content not being cached?

If you created a cache rule but content still hits the origin:

1. Check origin headers. Verify origin sends `Cache-Control: public, max-age=X` (where X \> 0\).
2. Check for Set-Cookie. Responses with `Set-Cookie` headers are not cached.
3. Verify request method. eCDN only caches GET requests.
4. Verify rule expression. Ensure expression matches your URL patterns.
5. Check rule is enabled. Verify `enabled: true` in rule response.
6. Check the response headers. Look for `Cf-Cache-Status: HIT` (cached) or `MISS/DYNAMIC` (not cached).

### What should I do if stale content is being served?

1. Check cache TTL. Reduce `max-age` in origin `Cache-Control` header.
2. Purge cache. Use cache purge API after content updates.
3. Verify query strings. Ensure query parameters that affect content aren't excluded.

### What's the difference between `excludeQueryStrings` and `ignoreQueryStringsOrder`?

`excludeQueryStrings` removes specific query parameters from the cache key. `ignoreQueryStringsOrder` sorts query parameters alphabetically before creating the cache key. You can use them together to normalize URLs with tracking parameters.

### What happens if I delete a cache rule?

The rule is removed from the ruleset immediately. Previously cached content remains cached until:

- TTL expires (based on origin `Cache-Control: max-age`).
- Cache is purged manually via cache purge API.
- Origin sends updated `Cache-Control` headers.

Deleting a rule doesn't purge cached content. Use the [cachePurge API](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=cachePurge) if you need to immediately invalidate cached content.

<!-- document id=c07afeebfee80f09c6bfcf3b62c7dd4951ac40aa0ea567797ff695d1d006c714 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-custom-rules.md -->

# eCDN Custom Rules

Use custom rules to control incoming traffic by setting up security policies based on request parameters. With custom rules, you have complete control over the rule expression, the allowed request field types, and the rule actions. This flexibility helps you create expressions that match your traffic needs. To create a custom rule in Business Manager, see [Create a Custom Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_create_eCDN_firewall_rule.htm) in _Salesforce Help_.

## Validation Overview

### Rule Expression

See [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md) for the operators, functions, and fields supported in a custom rule expression. Rate limiting rule expressions use the same list.

**important:** **Challenge actions on SLAS login endpoints:** Don't apply `js_challenge`, `legacy_captcha`, or `managed_challenge` to SLAS login endpoints in a custom rule. SLAS login is API-based, not a browser page, so the endpoint cannot present an interactive challenge. Unless the storefront interprets the challenge response and presents a challenge to the shopper, a Challenge action behaves like a permanent block: a shopper whose credentials appear in a leak has no way to prove they are human and log in. Start the rule with the `log` action. While the rule is in log mode, monitor the traffic that matches it and assess whether those requests are safe to block—or, if the storefront can present a challenge, safe to Challenge.

### Rule Actions

The following rule actions are supported in the actions array:

- `block` - Denies access to the requested site.
- `js_challenge` - The client that made the request must pass a JavaScript Challenge before proceeding.
- `legacy_captcha` - The client that made the request must pass an interactive challenge.

  **note:** Legacy captcha still exist through the API. However, Salesforce recommends selecting the managed challenge response for a better user experience.

- `managed_challenge` - Depending on the characteristics of the request, the appropriate type of challenge is presented to the client.
- `log` - Logs matching requests.

The following skip actions are also supported in the actions array:

- `skip_custom_rules` - Skips all remaining custom rules (meaning custom rules with a lower priority are not evaluated).
- `skip_security_level` - Skips Security Level.
- `skip_rate_limiting_rules` - Skips rate limiting rules. See [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html) for related documentation.
- `skip_wafv2` - Skips WAFv2 managed rules. For additional information, see [eCDN WAFv2](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-wafv2.html).

**important:** If using the skip actions, the user can provide multiple skip actions in the array. Otherwise, the array includes only 1 rule action. See the following usage examples:

```json
"actions": ["block"]

"actions": ["skip_custom_rules", "skip_wafv2"]

"actions": ["managed_challenge"]
```

### Rule Order

Custom rules are evaluated in the order they are listed in the response body. If a custom rule’s expression is matched, the action is executed.

- The `managed_challenge`, `js_challenge`, `legacy_captcha`, `block`, and `skip_custom_rules` actions stop further custom rule evaluation and no other rules in the ruleset are evaluated.
- The `skip_security_level`, `skip_rate_limiting_rules`, `skip_wafv2`, and `log` actions do not stop custom rule evaluation.

### Position

When creating or updating a custom rule, users can provide a `position` attribute in the request body to insert the rule at a certain relative position in the ruleset. _If the position is not provided during rule creation, the rule is added to the end of the ruleset by default._ See the following usage examples:

```json
# Places the rule before rule <RULE_ID>

"position": {
   "before": "<RULE_ID>"
}

or

# Places the rule after rule <RULE_ID>

"position": {
   "after": "<RULE_ID>"
}
```

## Examples

The following examples show common custom rules. Combine and adjust them to your own business needs.

- **Challenge non-verified bots hitting the storefront cart endpoint:**
  - Expression: `(http.request.uri.path contains "/Cart-AddProduct" and not cf.client.bot)`
  - Action: `managed_challenge`
- **Allow verified search engines through a country-based block:**
  - Expression: `(ip.src.country in {"CU" "IR"} and not cf.client.bot)`
  - Action: `block`
- **Challenge login requests where the submitted password matches a known leak:**
  - Expression: `(http.request.uri.path contains "/Account-Login" and cf.waf.credential_check.password_leaked)`
  - Action: `managed_challenge`

## Create a Custom Rule

This endpoint creates a custom rule in the specified zone.

- The `description`, `expression`, and `actions` attributes are required.
- The `enabled` and `position` attributes are optional.
- Refer to the Validation Overview section for more information on input validation

**important:** Newly created rules are enabled by default and added to the end of the ruleset unless specified otherwise. A maximum of 500 custom rules is allowed.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn firewall create \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --description "Skip Merchant Approval" \
  --expression '(http.user_agent contains "MerchantApprovalServiceClient")' \
  --actions skip_custom_rules,skip_wafv2 --no-enabled \
  --before ffffe61cf25e4ec49c34b029ff3060f7
```

Alternatively, use the API:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "description": "Skip Merchant Approval",
    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
    "actions": ["skip_custom_rules", "skip_wafv2"],
    "enabled": false,
    "position": {
        "before": "ffffe61cf25e4ec49c34b029ff3060f7"
    }
}'
```

### Sample Success Response - 201 HttpStatus Code

Response body contains the custom rule that was created.

```json
{
  "data": {
    "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "description": "Skip Merchant Approval",
    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
    "actions": ["skip_custom_rules", "skip_wafv2"],
    "lastUpdated": "2022-12-14T21:25:22.329194Z",
    "enabled": false
  }
}
```

## Get All Custom Rules

This endpoint returns all of the custom rules in the specified zone. If no custom rules exist, a 404 Not Found response is returned.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'
```

### Sample Success Response - 200 HttpStatus Code

Response body contains all of the existing custom rules in the specified zone.

```json
{
  "data": [
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Skip Merchant Approval",
      "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
      "actions": ["skip_custom_rules", "skip_wafv2"],
      "lastUpdated": "2022-12-14T21:25:22.329194Z",
      "enabled": true
    },
    {
      "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
      "description": "Block Cuba",
      "expression": "(ip.src.country eq \"CU\")",
      "actions": ["block"],
      "lastUpdated": "2022-12-14T21:27:45.245836Z",
      "enabled": true
    }
  ]
}
```

## Get a Custom Rule

This endpoint returns the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules/$RULEID" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'
```

### Sample Success Response - 200 HttpStatus Code

Response body contains the requested custom rule.

```json
{
  "data": {
    "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "description": "Skip Merchant Approval",
    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
    "actions": ["skip_custom_rules", "skip_wafv2"],
    "lastUpdated": "2022-12-14T21:25:22.329194Z",
    "enabled": false
  }
}
```

## Update a Custom Rule

This endpoint updates the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.

- The user must provide at least one of the following attributes in the request body: `description`, `expression`, `actions`, `enabled`, or `position`.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules/$RULEID" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "description": "Block Merchant Approval",
    "actions": ["block"],
    "enabled": false,
    "position": {
        "after": "ffffe61cf25e4ec49c34b029ff3060f7"
    }
}'
```

### Sample Success Response - 200 HttpStatus Code

Response body contains the requested rule.

```json
{
  "data": {
    "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
    "description": "Block Merchant Approval",
    "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
    "actions": ["block"],
    "lastUpdated": "2022-12-14T21:27:22.329194Z",
    "enabled": false
  }
}
```

## Update the Order of All Custom Rules

This endpoint updates the order of all existing custom rules. The user provides an array of `ruleIds` that represents the new rule order. The array must contain exactly all of the existing custom rule ruleIds.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "ruleIds": ["ffffe61cf25e4ec49c34b029ff3060f7", "2c0fc9fa937b11eaa1b71c4d701ab86e"]
}'
```

### Sample Success Response - 200 HttpStatus Code

Response body contains all of the existing custom rules in updated rule order.

```json
{
  "data": [
    {
      "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
      "description": "Block Cuba",
      "expression": "(ip.src.country eq \"CU\")",
      "actions": ["block"],
      "lastUpdated": "2022-12-14T21:27:45.245836Z",
      "enabled": true
    },
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Skip Merchant Approval",
      "expression": "(http.user_agent contains \"MerchantApprovalServiceClient\")",
      "actions": ["skip_custom_rules", "skip_wafv2"],
      "lastUpdated": "2022-12-14T21:25:22.329194Z",
      "enabled": true
    }
  ]
}
```

## Delete a Custom Rule

This endpoint deletes the requested custom rule. If the requested rule does not exist, a 404 Not Found response is returned.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-custom/rules/$RULEID" \
--request 'DELETE' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'
```

### Sample Success Response - 204 HttpStatus Code (No Content)

## Custom Rules FAQ

- How do I construct the rule expression?
  - See the [Cloudflare documentation](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/) for more information regarding constructing rule expressions.

<!-- document id=1cd747df6f3cdfc0c20530ea4151f7f5edf4ebdd54b616f4b318e619e3d6afab url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-logpush.md -->

# eCDN Logpush

eCDN Logpush delivers eCDN logs in batches to specified destinations. eCDN logs contain valuable information, such as the client IP address, the requested URL, the user agent string, and details about firewall events such as blocked requests, firewall rule triggers, and more.

When creating a Logpush job through eCDN Logpush, view the list of available fields for [http_requests](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush-log-field.html#http-requests-log-fields), [firewall](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush-log-field.html#firewall-event-log-fields), and [pageshield](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush-log-field.html#page-shield-log-event-fields) events. Also specify which log types to deliver, including HTTP requests and firewall events, and specify different destination types:

- [Create Logpush job for Amazon S3](#create-amazon-s3-bucket-logpush-job) bucket (Requires ownership verification step)
- [Create Logpush job for Google Cloud Storage](#create-google-cloud-storage-gcs-logpush-job) (Requires ownership verification step)
- [Create Logpush job for Azure](#create-azure-logpush-job)
- [Create Logpush job for Datadog](#create-datadog-logpush-job)
- [Create Logpush job for Splunk](#create-splunk-logpush-job)
- [Create Logpush job for HTTPS](#create-https-logpush-job)
- [Create Logpush job for Kinesis](#create-kinesis-logpush-job)

## Create Amazon S3 Bucket Logpush Job

### Prerequisites

Enable log push for an Amazon S3 destination:

- Create an S3 bucket. For details, see [AWS S3](https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html) documentation.
- In the Amazon S3 console, navigate to **S3** \> **Bucket** \> **Permissions** \> **Bucket Policy**, and edit and paste the policy, replacing the Resource value with your own bucket path. The AWS Principal is owned by the CDN provider and must not be changed.

```json
{ "Id": "PutObjPolicy", "Version": "2012-10-17", "Statement": [ { "Sid": "AllowObjectFromeCDNLogpush", "Action": [ "s3:PutObject" ], "Effect": "Allow", "Resource": "arn:aws:s3:::example-bucket/*", "Principal": { "AWS": [ "arn:aws:iam::391854517948:user/cloudflare-logpush" ] } } ] }
```

**note:** To avoid incomplete files and minimize storage costs, use the `AbortIncompleteMultipartUpload` action when setting up a rule for S3 multipart uploads with eCDN Logpush. For details, see [Uploading and copying objects using multipart upload\_](https://docs.aws.amazon.com/AmazonS3/latest/dev/mpuoverview.html#mpu-abort-incomplete-mpu-lifecycle-config).

### Create Amazon S3 Bucket Ownership Token

eCDN Logpush supports pushing eCDN logs directly to Amazon S3 through [CDN-API Logpush API](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary).

However, before you can create an eCDN Logpush job to directly push logs to an AWS S3 bucket, you must demonstrate ownership of the S3 bucket. You do this by writing the ownership token file to the bucket destination. You must also create a unique ownership challenge token for each destination path within the same bucket.

You can use the special string `{DATE}` in the destination path to separate logs into daily subdirectories. For example, `s3://customer-bucket/logs/{DATE}?region=us-east-1\&sse=AES256`. When the logs are stored, the name of the directory is replaced with the date in `YYYYMMDD` format, for example: `20230215`.

Example request:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn logpush ownership \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --destination-path 's3://example-bucket/log?region=us-east-1'
```

Alternatively, use the API:

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/ownership" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "destinationPath": "s3://example-bucket/log?region=us-east-1"
}'
```

Example response:

`{ "data": { "destinationPath": "s3://example-bucket/log?region=us-east-1", "fileName": "log/ownership-challenge-072fd6be.txt" } }`

### Create Logpush Job API Call for Amazon S3

Populate the \`ownershipChallengeToken\` based on the call made in the previous section. The `destinationPath` must be the same as the one specified while generating the ownership token. For details, see the [Parameters](#parameters), [Optional Parameters](#optional-parameters) and [Limitations](#limitations) sections.

Example Logpush job API call:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli ecdn logpush jobs create \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --name ExampleLogPushJob \
  --destination-path 's3://example-bucket/log?region=us-east-1' \
  --ownership-token 'your-ownership-challenge-token' \
  --log-type http_requests \
  --log-fields CacheCacheStatus,ClientRequestHost,ClientRequestPath,EdgeResponseStatus,EdgeStartTimestamp
```

Alternatively, use the API:

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "s3://example-bucket/log?region=us-east-1",
  "logType": "http_requests",
  "ownershipChallengeToken": "Put your ownership challenge token here",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

Example API call response: 201 status code

```json
{"data": {"jobId": 213543,"name": "ExampleLogPushJob","logType": "http_requests","logFields": ["CacheCacheStatus","CacheResponseBytes","ClientRequestPath","ClientRequestBytes","ClientRequestHost", "ClientRequestUserAgent","EdgeResponseStatus","EdgeResponseBytes","EdgeStartTimestamp","EdgeTimeToFirstByteMs"],"destinationPath":"s3://example-bucket/log?region=us-east-1","enabled": false,"createdOn":"2023-04-18T17:18:43Z"}}
```

## Create Google Cloud Storage (GCS) Logpush Job

### Prerequisites

Enable log push for a GCS destination:

- Create a GCS bucket.
- Cloudflare uses Google Cloud Identity and Access Management (IAM) to gain access to your Google Cloud Storage bucket. The Cloudflare IAM service account needs admin permission for the bucket. Add the member `logpush@cloudflare-data.iam.gserviceaccount.com` with Storage Object Admin permission. This makes sure that Cloudflare can push the ownership verification and logs to the GCS bucket.

### Create GCS Ownership Token

eCDN Logpush supports pushing eCDN logs directly to Google Cloud Storage (GCS) through the [CDN Logpush API](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary).

However, before you can create an eCDN Logpush job for pushing logs to a GCS bucket, you must demonstrate ownership of the GCS bucket. You do this by writing the ownership token file to the bucket destination. You must also create a unique ownership challenge token for each destination path within the same bucket.  
You can use the special string `{DATE}` in the destination path to separate logs into daily subdirectories. For example `gs://customer-bucket/logs/{DATE}`. When the logs are stored, the name of the directory is replaced with the date in `YYYYMMDD` format, for example: `20230215`.

Example request:`

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/ownership" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "destinationPath": "gs://cflogpushtest/http_requests/{DATE}"
}'
```

Example response:

`{ "data": { "destinationPath": "gs://cflogpushtest/http_requests/20251008", "fileName": "http_requests/20251008/ownership-challenge-072fd6be.txt" } }`

### Create Logpush Job API Call for GCS

Populate the `ownershipChallengeToken` based on the call made in the previous section. The \`destinationPath\` must be the same as one specified while generating the ownership token. For details, see the [Parameters](#parameters), [Optional Parameters](#optional-parameters) and [Limitations](#limitations) sections.

Example logpush job API call:

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "gs://cflogpushtest/http_requests/{DATE}",
  "logType": "http_requests",
  "ownershipChallengeToken": "Put your ownership challenge token here",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

Example API call response: 201 status code

```json
{"data": {"jobId": 213543,"name": "ExampleLogPushJob","logType": "http_requests","logFields": ["CacheCacheStatus","CacheResponseBytes","ClientRequestPath","ClientRequestBytes","ClientRequestHost", "ClientRequestUserAgent","EdgeResponseStatus","EdgeResponseBytes","EdgeStartTimestamp","EdgeTimeToFirstByteMs"],"destinationPath":"gs://cflogpushtest/http_requests/{DATE}","enabled": false,"createdOn":"2023-04-18T17:18:43Z"}}
```

## Create Azure Logpush Job

### Prerequisites

Enable log push for an Azure destination:

- Create a Blob Storage container. For details, see [instructions from Azure ↗](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-quickstart-blobs-portal).
- Create a [shared access signature (SAS) ↗](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview) to secure and restrict access to your blob storage container.
- Use [Storage Explorer ↗](https://learn.microsoft.com/en-us/azure/storage/storage-explorer/vs-azure-tools-storage-manage-with-storage-explorer) to navigate to your container and right click on the container to create a signature. Set the signature to expire at least five years from the current date and only provide write permission.
- Provide the SAS URL as part of your `destinationPath` attribute.
- Logpush stops pushing logs if your SAS token expires, which is why an expiration period of at least five years is needed.

Example destination configuration for Azure:

```text
“azure://cflogpushtest.blob.core.windows.net//cflogpush/{DATE}?sv=2024-11-04&ss=b&srt=o&sp=wactf&se=2030-09-23T22:27:16Z&st=2025-09-23T14:12:16Z&spr=https&sig=abcdefgh%3D”
```

Cloudflare makes a test call to push test data to the Azure destination specified. If successful, the logpush job is created. If not, the logpush job creation fails.

### Create Logpush Job API call for Azure

The following example creates a logpush job with an Azure destination path. For details, see the [Parameters](#parameters), [Optional Parameters](#optional-parameters) and [Limitations](#limitations) sections.

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "azure://cflogpush.blob.core.windows.net//cflogpush/{DATE}?sv=2024-11-04&ss=b&srt=o&sp=wactf&se=2030-01-01T00:00:00Z&st=2025-01-01T00:00:00Z&spr=https&sig=abcdefghIJKLMNOP%3D",
  "logType": "http_requests",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

Example API call response: 201 status code

```json
{"data": {"jobId": 213543,"name": "ExampleLogPushJob","logType": "http_requests","logFields": ["CacheCacheStatus","CacheResponseBytes","ClientRequestPath","ClientRequestBytes","ClientRequestHost", "ClientRequestUserAgent","EdgeResponseStatus","EdgeResponseBytes","EdgeStartTimestamp","EdgeTimeToFirstByteMs"],"destinationPath":"azure://cflogpush.blob.core.windows.net//cflogpush/{DATE}?sv=2024-11-04&ss=b&srt=o&sp=wactf&se=2030-01-01T00:00:00Z&st=2025-01-01T00:00:00Z&spr=https&sig=abcdefghIJKLMNOP%3D","enabled": false,"createdOn":"2023-04-18T17:18:43Z"}}
```

## Create Datadog Logpush Job

### Prerequisites

Enable log push for a Datadog destination:

- Specify your destination configuration hostname as either `http-intake.logs.datadoghq.com/v1/input` or `http-intake.logs.datadoghq.com/api/v2/logs`
- Retrieve the Datadog API Key using the [Datadog documentation](https://docs.datadoghq.com/account_management/api-app-keys/#add-an-api-key-or-client-token). This is a **required** field.
- You can set the service, host name, Datadog `ddsource` field, and `ddtags` fields as URL parameters. While these parameters are **_optional_**, they can be useful for indexing or processing logs. For details, see the [Logs section ↗](https://docs.datadoghq.com/api/latest/logs/) in Datadog's documentation. Note that the values of these parameters can contain special characters, which should be URL encoded.

Example destination configuration for Datadog:

```json
 "datadog://<DATADOG_ENDPOINT_URL>?header_DD-API-KEY=<DATADOG_API_KEY>&ddsource=cloudflare&service=<SERVICE>&host=<HOST>&ddtags=<TAGS>”
```

Cloudflare makes a test call to push test data to the specified Datadog destination configuration. If successful, the logpush job is created. If not, the logpush job creation fails.

### Create Logpush Job API call for Datadog

This example creates a logpush job with a Datadog destination path. For details, see the [Parameters](#parameters), [Optional Parameters](#optional-parameters) and [Limitations](#limitations) sections.

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "datadog://<DATADOG_ENDPOINT_URL>?header_DD-API-KEY=<DATADOG_API_KEY>&ddsource=cloudflare&service=<SERVICE>&host=<HOST>&ddtags=<TAGS>",
  "logType": "http_requests",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

Example API call response: 201 status code

```json
{"data": {"jobId": 213543,"name": "ExampleLogPushJob","logType": "http_requests","logFields": ["CacheCacheStatus","CacheResponseBytes","ClientRequestPath","ClientRequestBytes","ClientRequestHost", "ClientRequestUserAgent","EdgeResponseStatus","EdgeResponseBytes","EdgeStartTimestamp","EdgeTimeToFirstByteMs"],"destinationPath":"datadog://<DATADOG_ENDPOINT_URL>?header_DD-API-KEY=<DATADOG_API_KEY>&ddsource=cloudflare&service=<SERVICE>&host=<HOST>&ddtags=<TAGS>","enabled": false,"createdOn":"2023-04-18T17:18:43Z"}}
```

## Create Splunk Logpush Job

### Prerequisites

Configure a Splunk destination with these values:

- <SPLUNK_ENDPOINT_URL>: The Splunk raw HTTP Event Collector URL with the port. For example: `splunk.cf-analytics.com:8088/services/collector/raw`.
  - Cloudflare expects the Splunk endpoint to be `/services/collector/raw` while configuring and setting up the Logpush job.
- <SOURCE_TYPE>: The Splunk source type, for example: `cloudflare:json`.
- <SPLUNK_AUTH_TOKEN>: The Splunk authorization token that is URL-encoded, for example: `Splunk%20e6d94e8c-5792-4ad1-be3c-29bcaee0197d`.
  - Make sure that you have enabled HEC in Splunk. For details, see [Splunk Analytics Integrations](https://developers.cloudflare.com/analytics/analytics-integrations/splunk/).
  - API requests fail with a 504 error if you add an incorrect URL. Typically, the Splunk Cloud endpoint URL includes text like `http-inputs-` before the hostname.
- <SPLUNK_CHANNEL_ID>: A unique channel ID. This is a random GUID that you can generate by using:
  - An online tool like the [GUID generator ↗](https://www.guidgenerator.com/).
  - The command line, for example: `python \-c 'import uuid; print(uuid.uuid4())'`.
- <INSECURE_SKIP_VERIFY>: A boolean value. Cloudflare recommends setting this value to `false`, because setting this value to `true` is equivalent to using the `-k` option with curl as shown in Splunk examples and is **not** recommended unless HEC uses a self-signed certificate.

Example destination configuration for Splunk:

```json
 "splunk://<SPLUNK_ENDPOINT_URL>?channel=<SPLUNK_CHANNEL_ID>&insecure-skip-verify=<INSECURE_SKIP_VERIFY>&sourcetype=<SOURCE_TYPE>&header_Authorization=<SPLUNK_AUTH_TOKEN>"
```

Cloudflare makes a test call to push test data to the endpoint specified. If successful, the logpush job is created. If not, the logpush job creation fails.

### Create Logpush Job API call for Splunk

This example creates a logpush job with a Splunk destination path. For details, see the [Parameters](#parameters), [Optional Parameters](#optional-parameters) and [Limitations](#limitations) sections.

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "splunk://<SPLUNK_ENDPOINT_URL>?channel=<SPLUNK_CHANNEL_ID>&insecure-skip-verify=<INSECURE_SKIP_VERIFY>&sourcetype=<SOURCE_TYPE>&header_Authorization=<SPLUNK_AUTH_TOKEN>",
  "logType": "http_requests",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

Example API call response: 201 status code

```json
{"data": {"jobId": 213543,"name": "ExampleLogPushJob","logType": "http_requests","logFields": ["CacheCacheStatus","CacheResponseBytes","ClientRequestPath","ClientRequestBytes","ClientRequestHost", "ClientRequestUserAgent","EdgeResponseStatus","EdgeResponseBytes","EdgeStartTimestamp","EdgeTimeToFirstByteMs"],"destinationPath":"splunk://<SPLUNK_ENDPOINT_URL>?channel=<SPLUNK_CHANNEL_ID>&insecure-skip-verify=<INSECURE_SKIP_VERIFY>&sourcetype=<SOURCE_TYPE>&header_Authorization=<SPLUNK_AUTH_TOKEN>","enabled": false,"createdOn":"2023-04-18T17:18:43Z"}}
```

## Create HTTPS Logpush Job

### Prerequisites

Configure the HTTPS destination:

- Make sure that the file upload to validate the destination accepts a gzipped `test.txt.gz` file with compressed content `{"content":"tests"}`. Otherwise, it returns an error, for example: `error validating destination: error writing object: error uploading`.
- Specify "header\_\*" URL parameters for setting request headers.
  - The HTTPS endpoint cannot have custom URL parameters that conflict with any "header\_\*" URL parameters you have set.
  - These parameters must be properly URL-encoded, for example: use "%20" for a whitespace. Otherwise, some special characters can be decoded incorrectly.
- For destination*conf , specify URL parameters in addition to special "header*\*" parameters.
  - Non URL-encoded special characters are encoded when uploaded.

Example destination configuration for HTTPS endpoint:

```text
https://logs.example.com?header_Authorization=Basic%20REDACTED&tags=host:salesforce.com,dataset:http_requests
```

Cloudflare makes a test call to push test data to the endpoint specified. If successful, the logpush job is created. If not, the logpush job creation fails.

### Create Logpush Job API call for HTTPS Endpoint

This example creates a logpush job with an HTTPS destination endpoint. For details, see the [Parameters](#parameters), [Optional Parameters](#optional-parameters) and [Limitations](#limitations) sections.

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "https://logs.example.com?header_Authorization=Basic%20REDACTED&tags=host:salesforce.com,dataset:http_requests",
  "logType": "http_requests",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

Example API call response: 201 status code

```json
{"data": {"jobId": 213543,"name": "ExampleLogPushJob","logType": "http_requests","logFields": ["CacheCacheStatus","CacheResponseBytes","ClientRequestPath","ClientRequestBytes","ClientRequestHost", "ClientRequestUserAgent","EdgeResponseStatus","EdgeResponseBytes","EdgeStartTimestamp","EdgeTimeToFirstByteMs"],"destinationPath":"https://logs.example.com?header_Authorization=Basic%20REDACTED&tags=host:salesforce.com,dataset:http_requests","enabled": false,"createdOn":"2023-04-18T17:18:43Z"}}
```

## Create Kinesis Logpush Job

### Prerequisites

Configure the Kinesis destination:

- Create an IAM Role for Cloudflare Logpush to Assume with this trust relationship:
  ```json
  {
      "Version": "2012-10-17",
      "Statement": [
          {
               "Effect": "Allow",
               "Principal": {
                   "AWS": [
                       "arn:aws:iam::391854517948:user/cloudflare-logpush"
                   ]
               },
               "Action": "sts:AssumeRole"
          }
      ]
  }
  ```
- Make sure that the IAM role has permissions to perform the `PutRecord` action on your Kinesis stream.
- Replace <AWS_REGION>, <YOUR_AWS_ACCOUNT_ID> and <STREAM_NAME> with your values:
  ```json
  {
      "Version": "2012-10-17",
      "Statement": [
          {
               "Effect": "Allow",
               "Action": "kinesis:PutRecord",
               "Resource": "arn:aws:kinesis:<AWS_REGION>:<YOUR_AWS_ACCOUNT_ID>:stream/<STREAM_NAME">
          }
      ]
  }
  ```
- (Optional) When using the STS Assume Role, include `sts-external-id` as a `destination_conf` parameter in your Logpush job's requests. For details, see [Securely Using External ID for Accessing AWS Accounts Owned by Others ↗](https://aws.amazon.com/blogs/apn/securely-using-external-id-for-accessing-aws-accounts-owned-by-others/) for more information.

Example destination configuration for setting up logpush to AWS Kinesis:
`kinesis://<STREAM_NAME>?region=<AWS_REGION>&sts-assume-role-arn=arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>`

### Create Logpush Job API call for Kinesis

This example creates a logpush job with Kinesis. For details, see the [Parameters](#parameters), [Optional Parameters](#optional-parameters) and [Limitations](#limitations) sections.

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "kinesis://<STREAM_NAME>?region=<AWS_REGION>&sts-assume-role-arn=arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>",
  "logType": "http_requests",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

Example API call response: 201 status code

```json
{"data": {"jobId": 213543,"name": "ExampleLogPushJob","logType": "http_requests","logFields": ["CacheCacheStatus","CacheResponseBytes","ClientRequestPath","ClientRequestBytes","ClientRequestHost", "ClientRequestUserAgent","EdgeResponseStatus","EdgeResponseBytes","EdgeStartTimestamp","EdgeTimeToFirstByteMs"],"destinationPath":"kinesis://<STREAM_NAME>?region=<AWS_REGION>&sts-assume-role-arn=arn:aws:iam::<YOUR_AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>","enabled": false,"createdOn":"2023-04-18T17:18:43Z"}}
```

### Parameters

- Name: Your site name, which can't be changed after the job is created.
- Destination Path: The destination path for receiving logs. The prerequisites information for each destination type describes how to get the `destinationPath` attribute.
- Ownership Challenge Token: This attribute is required for AWS S3 and Google Cloud Storage destinations. It isn't required for other destinations such as HTTPS, Datadog, Azure, Splunk, or Kinesis.
- Log Type: The type of logs you want to receive in your S3 bucket. Currently, the available types are `http_requests`, `firewall_events`, and `page_shield_events`.
- Log Fields: The available log fields, which vary depending on the type of logs. For details, see [eCDN Logpush Log Fields](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush-log-field.html).

### Optional Parameters

- Filter: Use filters to select specific types of events to include in your logs or remove events irrelevant to your analysis. By applying filters to your logs, focus on the most important data and avoid unnecessary noise.

For details, see [eCDN Logpush Filter](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush-filter.html).

### Limitations

You can create a maximum of _two_ Logpush jobs per zone.

## Enable Logpush Job

An eCDN Logpush Job isn't enabled upon creation. You must enable the Logpush Job to start receiving logs. For additional details, see [CDN Zones API Overview](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary).

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli ecdn logpush jobs update \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --job-id 213543 --enabled
```

Alternatively, use the API:

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs/{jobId}" \
  --request PUT \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "enabled": true
}'
```

### Example Request

```json
{ "enabled": true }
```

### Successful Response

A successful response returns 200.

```json
{ "data": { "jobId": 213543, "name": "ExampleLogPushJob", "logType": "http_requests", "logFields": [ "CacheCacheStatus", "CacheResponseBytes", "ClientRequestPath", "ClientRequestBytes", "ClientRequestHost", "ClientRequestUserAgent", "EdgeResponseStatus", "EdgeResponseBytes", "EdgeStartTimestamp", "EdgeTimeToFirstByteMs" ], "destinationPath": "s3://example-bucket/log?region=us-east-1", "enabled": true, "createdOn": "2023-04-18T17:18:43Z" } }
```

## eCDN Logpush Logs JSON Output Data

This example shows JSON log output from an eCDN Logpush job.

```json
{ "CacheCacheStatus": "dynamic", "CacheResponseBytes": 12191, "ClientRequestPath": "/404", "ClientRequestBytes": 2161, "ClientRequestHost": "edge01.sfcc-ecdn-test5.net", "ClientRequestUserAgent": "Fuzz Faster U Fool v1.5.0-dev", "EdgeResponseStatus": 410, "EdgeResponseBytes": 39065, "EdgeStartTimestamp": "2023-04-18T17:29:16Z", "EdgeTimeToFirstByteMs": 504, "ClientRequestSource":"eyeball" }
```

## List Logpush Jobs

For details, see [CDN Zones API Overview](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary).

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli ecdn logpush jobs list \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net
```

Alternatively, use the API:

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request GET \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'
```

### **Successful Response**

A successful response returns 200.

```json
{ "data": [ { "jobId": 213543, "name": "ExampleLogPushJob", "logType": "http_requests", "logFields": [ "CacheCacheStatus", "CacheResponseBytes", "ClientRequestPath", "ClientRequestBytes", "ClientRequestHost", "ClientRequestUserAgent", "EdgeResponseStatus", "EdgeResponseBytes", "EdgeStartTimestamp", "EdgeTimeToFirstByteMs" ], "destinationPath": "s3://example-bucket/log?region=us-east-1", "enabled": true, "createdOn": "2023-04-18T17:18:43Z" } ] }
```

## Delete Logpush Job

For details, see [CDN Zones API Overview](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=Summary).

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs/{jobId}" \
  --request DELETE \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json'
```

### **Successful Response**

A successful response returns 204.

## eCDN Logpush FAQ

- The Logpush job was accidentally turned off, and we missed some logs for a certain time period. Is there a way to retrieve those missed logs?
  - No, eCDN Logpush pushes the logs into the S3 bucket as soon as they become available and isn't able to backfill the missing logs.
- Can I adjust how often logs are pushed?
  - No, eCDN Logpush pushes the logs in batches to the destination specified at the earliest possible time.
- I created an ownership token, but I don’t see the file in my S3 bucket.
  - Check your S3 bucket policy for allowing eCDN Logpush to write a file to your bucket. Edit and paste the policy into **S3 \> Bucket \> Permissions \> Bucket Policy**, replacing the **Resource** value as shown in the [Enable eCDN Logpush to Amazon S3](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html#enable-ecdn-logpush-to-amazon-s3) section.

<!-- document id=0f5e3002376a2cbad9aba27184af4539429a5fb32cbe11157b72f935fa5613a9 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-logpush-filter.md -->

# eCDN Logpush Filter

## Create eCDN Logpush Job with Filter

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn logpush jobs create \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --name ExampleLogPushJob \
  --destination-path 's3://example-bucket/log?region=us-east-1' \
  --ownership-token 'your-ownership-challenge-token' \
  --log-type http_requests \
  --log-fields CacheCacheStatus,ClientRequestHost,ClientRequestPath,EdgeResponseStatus,EdgeStartTimestamp \
  --filter '{"where":{"key":"ClientRequestPath","operator":"contains","value":"/example-path"}}'
```

Alternatively, use the API:

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "s3://example-bucket/log?region=us-east-1",
  "logType": "http_requests",
  "ownershipChallengeToken": "Put your ownership challenge token here",
  "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

## Successful Response

A successful response returns 201.

```json
{
  "data": {
    "jobId": 213543,
    "name": "ExampleLogPushJob",
    "logType": "http_requests",
    "logFields": [
      "CacheCacheStatus",
      "CacheResponseBytes",
      "ClientRequestPath",
      "ClientRequestBytes",
      "ClientRequestHost",
      "ClientRequestUserAgent",
      "EdgeResponseStatus",
      "EdgeResponseBytes",
      "EdgeStartTimestamp",
      "EdgeTimeToFirstByteMs"
    ],
    "filter": "{\"where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}}",
    "destinationPath": "s3://example-bucket/log?region=us-east-1",
    "enabled": false,
    "createdOn": "2023-04-18T17:18:43Z"
  }
}
```

## Filter Detail

The following table shows the supported comparison operators along with example values.

To add filters, provide the filter criteria in the form of escaped JSON strings with the format
`{\"where\":{\"key"\:\"<field>\",\"operator\":\"<comparison_operator>\",\"value\":\"<value>\"}}`.

**note:** - The `\“Key”\` field value must correspond to one of the available fields listed in [eCDN Logpush Log Field](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-zones-logpush-log-field.md).
- For the Firewall events dataset, filtering is not supported for the following fields: `Action`, `Description`, `Kind`, `MatchIndex`,`Metadata`, `OriginatorRayID`, `RuleID`, and `Source`.

| Name                            | Operator Notation | Supported Field Types | Example                                                                                        |
| ------------------------------- | ----------------- | --------------------- | ---------------------------------------------------------------------------------------------- |
| Equal                           | eq                | String, Int, Bool     | `{\“where\":{\"key\":\"ClientRequestHost\",\"operator\":\"eq\",\"value\":\"example.com\"}}`    |
| Not equal                       | !eq               | String, Int, Bool     | `{\“where\":{\"key\":\"ClientCountry\",\"operator\":\"!eq\",\"value\":\"ca\"}} `               |
| Less than                       | lt                | Int                   | `{\“where\":{\"key\":\"BotScore\",\"operator\":\"lt\",\"value\":\"30\"}}`                      |
| Less than or equal              | leq               | Int                   | `{\“where\":{\"key\":\"BotScore\",\"operator\":\"leq\",\"value\":\"30\"}}`                     |
| Greater than                    | gt                | Int                   | `{\“where\":{\"key\":\"BotScore\",\"operator\":\"gt\",\"value\":\"30\"}}`                      |
| Greater than or equal           | geq               | Int                   | `{\“where\":{\"key\":\"BotScore\",\"operator\":\"geq\",\"value\":\"30\"}}`                     |
| Starts with                     | startsWith        | String                | `{\“where\":{\"key\":\"ClientRequestPath\",\"operator\":\"startsWith\",\"value\":\"/foo\"}}`   |
| Ends with                       | endsWith          | String                | `{\“where\":{\"key\":\"ClientRequestPath\",\"operator\":\"endsWith\",\"value\":\"/foo\"}}`     |
| Does not start with             | !startsWith       | String                | `{\“where\":{\"key\":\"ClientRequestPath\",\"operator\":\"!startsWith\",\"value\":\"/foo\"}}`  |
| Does not end with               | !endsWith         | String                | `{\“where\":{\"key\":\"ClientRequestPath\",\"operator\":\"!endsWith\",\"value\":\"/foo\"}}`    |
| Contains                        | contains          | String, Bool          | `{\“where\":{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/static\"}}`  |
| Does not contain                | !contains         | String, Bool          | `{\“where\":{\"key\":\"ClientRequestPath\",\"operator\":\"!contains\",\"value\":\"/static\"}}` |
| Value is in a set of values     | in                | String, Int, Array    | `{\“where\":{\"key\":\"EdgeResponseStatus\",\"operator\":\"in\",\"value\":[200,201]}}`         |
| Value is not in a set of values | !in               | String, Int, Array    | `{\“where\":{\"key\":\"EdgeResponseStatus\",\"operator\":\"!in\",\"value\":[200,201]}}`        |

## Logical Operators in Filter

- Filters can be connected using `AND, OR` logical operators.
- Logical operators can be nested.

Here are some examples of how the logical operators can be implemented. X, Y, and Z are used to represent filter criteria:

- X AND Y AND Z - `{"where":{"and":[{X},{Y},{Z}]}}`
- X OR Y OR Z - `{"where":{"or":[{X},{Y},{Z}]}}`
- X AND (Y OR Z) - `{"where":{"and":[{X}, {"or":[{Y},{Z}]}]}}`
- (X AND Y) OR Z - `{"where":{"or":[{"and": [{X},{Y}]},{Z}]}}`

## Example Request

In this example, the eCDN logpush job sends the logs to the S3 bucket only if the log has ClientRequestPath that contains `“/example-path”` and EdgeResponseStatus includes `502, 503, and 504.`

```bash
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/logpush/jobs" \
  --request POST \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "ExampleLogPushJob",
  "destinationPath": "s3://example-bucket/log?region=us-east-1",
  "logType": "http_requests",
  "ownershipChallengeToken": "Put your ownership challenge token here",
  "filter": "{\"where\":{\"and\":[{\"key\":\"ClientRequestPath\",\"operator\":\"contains\",\"value\":\"/example-path\"}, {\"key\":\"EdgeResponseStatus\",\"operator\":\"in\",\"value\":[502, 503, 504]}]}}",
  "logFields": [
    "CacheCacheStatus",
    "CacheResponseBytes",
    "ClientRequestPath",
    "ClientRequestBytes",
    "ClientRequestHost",
    "ClientRequestUserAgent",
    "EdgeResponseStatus",
    "EdgeResponseBytes",
    "EdgeStartTimestamp",
    "EdgeTimeToFirstByteMs"
  ]
}'
```

<!-- document id=79eb78e69a2a18c235f8ba8c6804acb8082cb84ba5d8e9c1d4965b8f66c0e445 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-logpush-log-field.md -->

# eCDN Logpush Log Event Fields

Field descriptions are provided in the following sections.

## HTTP Requests Log Fields

The following descriptions detail the fields available for `http_requests`. For code samples, see [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html#create-logpush-job).

|                 Field                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |     Type      |
| :-----------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------: |
|            BotDetectionIDs            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           List of IDs that correlate to the Bot Management Heuristic detections made on a request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |  array[int]   |
|               BotScore                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Bot Score. Scores below 30 are commonly associated with automated traffic. Available for Bot Management customers (contact Salesforce account team to enable).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |      int      |
|              BotScoreSrc              |                                                                                                                                                                                                                                                                                                                                                                                                                                                             Detection engine responsible for generating the Bot Score.<br>Possible values are: Not Computed \| Heuristics \| Machine Learning \| Behavioral Analysis \| Verified Bot \| JS Fingerprinting \| Cloudflare Service.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |    string     |
|                BotTags                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                   Type of bot traffic (if available). <br>The list of potential values are: <br>api \| google \| bing \| googleAds \| googleMedia \| googleImageProxy \| pinterest \| newRelic \| baidu \| apple \| yandex                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | array[string] |
|           CacheCacheStatus            | Cache status.<br>Possible values are: unknown \| miss \| expired \| updating \| stale \| hit \| ignored \| bypass \| revalidated \| dynamic \| stream_hit \| deferred<br><br>HIT: Found in eCDN cache<br>MISS: Not found in eCDN cache, served from origin<br>NONE/UNKNOWN: Not eligible for caching due to Firewall rule blocking request, or redirect page rule.<br>EXPIRED: Found in eCDN cache, but expired and served from origin<br>STALE: Served from eCDN cache, but expired and unable to retrieve updated resource from origin<br>BYPASS: Instructed by origin to bypass cache via Cache-Control header set to no-cache, private, or max-age=0 or when cookies are sent in the response header<br>REVALIDATED: Served from eCDN cache, but stale and revalidated by If-Modified-Since or If-None-Match header<br>UPDATING: Served from eCDN cache, expired, and being updated by origin. It's indicating for very popular cached resources at eCDN.<br>DYNAMIC: Not eligible for caching and not explicitly instructed to cache, requested from origin web server. This can mean, for example that it was blocked by the firewall. |    string     |
|           CacheReserveUsed            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Cache Reserve was used to serve this request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |     bool      |
|          CacheResponseBytes           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Number of bytes returned by the cache.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |      int      |
|               ClientASN               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Client AS number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |      int      |
|             ClientCountry             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           2-letter ISO-3166 country code of the client IP address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |    string     |
|           ClientDeviceType            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             Client device type.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |    string     |
|               ClientIP                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          IP address of the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |    string     |
|             ClientIPClass             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Client IP class.<br>Possible values are: unknown \| badHost \| searchEngine \| allowlist \| monitoringService \| noRecord \| scan \| tor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |    string     |
|          ClientRequestBytes           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Number of bytes in the client request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |      int      |
|           ClientRequestHost           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Host requested by the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |    string     |
|          ClientRequestMethod          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        HTTP method of client request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |    string     |
|           ClientRequestPath           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      URI path requested by the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |    string     |
|         ClientRequestProtocol         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       HTTP protocol of client request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |    string     |
|         ClientRequestReferer          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            HTTP request referrer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |    string     |
|          ClientRequestScheme          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   The URL scheme requested by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |    string     |
|          ClientRequestSource          |                                                       Identifies requests as coming from an external source or another service within CDN provider. <br><br>Refer to the list of potential values.<br><br>unknown: Should never happen<br>eyeball: A request from an end user. If you want to count requests made the CDN edge, the query should filter on requestSource=eyeball.<br>purge: A request made by the purge system.<br>alwaysOnline: A request made by CDN Always Online crawler.<br>healthcheck: A request made by CDN Health Check system.<br>edgeWorkerFetch: A fetch request made from an edge Worker.<br>edgeWorkerCacheAPI: A cache API call made from an edge Worker.<br>edgeWorkerKV: A KV call made from an edge Worker.<br>orangeToOrange: A request that comes from another orange clouded zone.<br>sslDetector: A request made by CDN SSL Detector system.<br>earlyHintsCache: An Early Hint request.<br>inBrowserChallenge: An end user request caused by a CDN security product (Challenges, JavaScript Detections). These requests never reach the origin.                                                        |    string     |
|           ClientRequestURI            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         URI requested by the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |    string     |
|        ClientRequestUserAgent         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      User agent reported by the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |    string     |
|            ClientSSLCipher            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Client SSL cipher.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |    string     |
|           ClientSSLProtocol           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   Client SSL (TLS) protocol. The value “none” means that SSL was not used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |    string     |
|            ClientTCPRTTMs             |                                                                                                                                                                                                                                                                                                                                                                                                                         The smoothed average of TCP round-trip time (SRTT). For the initial request on a connection, this is measured only during connection setup. For a subsequent request on the same connection, it is measured over the entire connection lifetime up until the time that request is received.                                                                                                                                                                                                                                                                                                                                                                                                                          |      int      |
|                Cookies                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     String key-value pairs for Cookies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |    object     |
|          EdgeCFConnectingO2O          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             True if the request looped through multiple zones on the eCDN. This is considered an orange to orange (o2o) request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |     bool      |
|             EdgeColoCode              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         IATA airport code of data center that received the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |    string     |
|              EdgeColoID               |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              eCDN edge colo id.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |      int      |
|           EdgeEndTimestamp            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     Timestamp at which the edge finished sending response to the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | int or string |
|             EdgePathingOp             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         Indicates what type of response was issued for this request (unknown = no specific action).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |    string     |
|            EdgePathingSrc             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   Details how the request was classified based on security checks (unknown = no specific classification).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |    string     |
|           EdgePathingStatus           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         Indicates what data was used to determine the handling of this request (unknown = no data).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |    string     |
|            EdgeRequestHost            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           Host header on the request from the edge to the origin.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |    string     |
|         EdgeResponseBodyBytes         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             Size of the HTTP response body returned to clients.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |      int      |
|           EdgeResponseBytes           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             Number of bytes returned by the edge to the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |      int      |
|     EdgeResponseCompressionRatio      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       Edge response compression ratio.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |     float     |
|        EdgeResponseContentType        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   Edge response Content-Type header value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |    string     |
|          EdgeResponseStatus           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               HTTP status code returned by eCDN to the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |      int      |
|             EdgeServerIP              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                     IP of the edge server making a request to the origin. Possible responses are string in IPv4 or IPv6 format, or empty string. Empty string means that there was no request made to the origin server.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |    string     |
|          EdgeStartTimestamp           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Timestamp at which the edge received request from the client.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | int or string |
|         EdgeTimeToFirstByteMs         |                                                                                                                                                                                                                                                                                                                                                                                                                                         Total view of Time To First Byte as measured at eCDN. Starts after a TCP connection is established and ends when eCDN begins returning the first byte of a response to eyeballs. Includes TLS handshake time (for new connections) and origin response time.                                                                                                                                                                                                                                                                                                                                                                                                                                         |      int      |
|            SecurityActions            |                                                                                                                                                                            Array of actions the security products performed on this request. The individual security products associated with this action be found in SecuritySources and their respective rule Ids can be found in SecurityRuleIDs. The length of the array is the same as SecurityRuleIDs and SecuritySources. <br> Possible actions are : unknown \| allow \| block \| challenge \| jschallenge \| log \| connectionClose \| challengeSolved \| challengeFailed \| challengeBypassed \| jschallengeSolved \| jschallengeFailed \| jschallengeBypassed \| bypass \| managedChallenge \| managedChallengeSkipped \| managedChallengeNonInteractiveSolved \| managedChallengeInteractiveSolved \| managedChallengeBypassed \| rewrite \| forceConnectionClose \| skip \| managedChallengeFailed.                                                                                                                                                                             | array[string] |
|            SecurityRuleIDs            |                                                                                                                                                                                                                                                                                                                                                                                                                                                      Array of rule IDs of the security product that matched the request. The security product associated with the rule ID can be found in SecuritySources. The length of the array is the same as SecurityActions and SecuritySources.                                                                                                                                                                                                                                                                                                                                                                                                                                                       | array[string] |
|            SecurityRuleID             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Rule ID of the security rule that triggered a terminating action, if any.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |    string     |
|            SecuritySources            |                                                                                                                                                                                                                          Array of security products that matched the request. The same product can appear multiple times, which indicates different rules or actions that were activated. The rule IDs can be found in SecurityRuleIDs, and the actions can be found in SecurityActions. The length of the array is the same as SecurityRuleIDs and SecurityActions. <br> Possible sources are : unknown \| asn \| country \| ip \| ipRange \| securityLevel \| zoneLockdown \| waf \| firewallRules \| uaBlock \| rateLimit \| bic \| hot \| l7ddos \| validation \| botFight \| apiShield \| botManagement \| dlp \| firewallManaged \| firewallCustom \| apiShieldSchemaValidation \| apiShieldTokenValidation.                                                                                                                                                                                                                           |               |
|        SecurityRuleDescription        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Description of the security rule that triggered a terminating action, if any.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |    string     |
|   OriginRequestHeaderSendDurationMs   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               Time taken to send request headers to origin after establishing a connection. Note that this value is usually 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |      int      |
|       OriginResponseDurationMs        |                                                                                                                                                                                                                                                                                                                                                                                                                                           Upstream response time, measured from the first datacenter that receives a request. Includes time taken by Argo Smart Routing and Tiered Cache, plus time to connect and receive a response from origin servers. This field replaces OriginResponseTime.                                                                                                                                                                                                                                                                                                                                                                                                                                           |      int      |
| OriginResponseHeaderReceiveDurationMs |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Time taken for origin to return response headers after eCDN finishes sending request headers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |      int      |
|         OriginResponseStatus          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               Status returned by the origin server. The value 0 means that there was no request made to the origin server and the response was served by eCDN.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |      int      |
|     OriginTCPHandshakeDurationMs      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     Time taken to complete TCP handshake with origin. This will be 0 if an origin connection is reused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |      int      |
|     OriginTLSHandshakeDurationMs      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     Time taken to complete TLS handshake with origin. This will be 0 if an origin connection is reused.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |      int      |
|              ParentRayID              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 Ray ID of the parent request if this request was made using a Worker script.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |    string     |
|                 RayID                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ID of the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |    string     |
|               ZoneName                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                The human-readable name of the zone (for example, ‘dev-example.cc-ecdn.net’).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |    string     |

## Firewall Event Log Fields

The following descriptions detail the fields available for `firewall_events`.

| Field                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Type          |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Action                 | The code of the first-class action the Firewall took on this request. <br> Possible actions are : unknown \| allow \| block \| challenge \| jschallenge \| log \| connectionclose \| challengesolved \| challengefailed \| challengebypassed \| jschallengesolved \| jschallengefailed \| jschallengebypassed \| bypass \| managedchallenge \| managedchallengeskipped \| managedchallengenoninteractivesolved \| managedchallengeinteractivesolved \| managedchallengebypassed. | string        |
| ClientASN              | The ASN number of the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                                   | int           |
| ClientASNDescription   | The ASN of the visitor as string.                                                                                                                                                                                                                                                                                                                                                                                                                                                | string        |
| ClientCountry          | Country from which request originated.                                                                                                                                                                                                                                                                                                                                                                                                                                           | string        |
| ClientIP               | The visitor’s IP address (IPv4 or IPv6).                                                                                                                                                                                                                                                                                                                                                                                                                                         | string        |
| ClientIPClass          | The classification of the visitor’s IP address, possible values are : unknown \| badHost \| searchEngine \| allowlist \| monitoringService \| noRecord \| scan \| tor.                                                                                                                                                                                                                                                                                                           | string        |
| ClientRefererHost      | The referer host.                                                                                                                                                                                                                                                                                                                                                                                                                                                                | string        |
| ClientRefererPath      | The referer path requested by visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                           | string        |
| ClientRefererQuery     | The referer query-string was requested by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                           | string        |
| ClientRefererScheme    | The referer URL scheme requested by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                 | string        |
| ClientRequestHost      | The HTTP hostname requested by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                      | string        |
| ClientRequestMethod    | The HTTP method used by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                             | string        |
| ClientRequestPath      | The path requested by visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                                   | string        |
| ClientRequestProtocol  | The version of HTTP protocol requested by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                           | string        |
| ClientRequestQuery     | The query-string was requested by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                   | string        |
| ClientRequestScheme    | The URL scheme requested by the visitor.                                                                                                                                                                                                                                                                                                                                                                                                                                         | string        |
| ClientRequestUserAgent | Visitor’s user-agent string.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | string        |
| Description            | The description of the rule triggered by this request.                                                                                                                                                                                                                                                                                                                                                                                                                           | string        |
| Datetime               | The date and time the event occurred at the edge.                                                                                                                                                                                                                                                                                                                                                                                                                                | int or string |
| EdgeColoCode           | The airport code of the CDN datacenter that served this request.                                                                                                                                                                                                                                                                                                                                                                                                                 | string        |
| EdgeResponseStatus     | HTTP response status code returned to browser.                                                                                                                                                                                                                                                                                                                                                                                                                                   | int           |
| Kind                   | The kind of event, currently only possible values are: _firewall_.                                                                                                                                                                                                                                                                                                                                                                                                               | string        |
| MatchIndex             | Rules match index in the chain.                                                                                                                                                                                                                                                                                                                                                                                                                                                  | int           |
| Metadata               | Additional product-specific information. Metadata is organized in key:value pairs. Key and Value formats can vary by the security product and can change over time.                                                                                                                                                                                                                                                                                                              | object        |
| OriginResponseStatus   | HTTP origin response status code returned to browser.                                                                                                                                                                                                                                                                                                                                                                                                                            | int           |
| OriginatorRayID        | The RayID of the request that issued the challenge/jschallenge.                                                                                                                                                                                                                                                                                                                                                                                                                  | string        |
| RayID                  | The RayID of the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | string        |
| RuleID                 | The security product-specific RuleID triggered by this request.                                                                                                                                                                                                                                                                                                                                                                                                                  | string        |
| Source                 | The security product triggered by this request. <br> Possible sources are : unknown \| asn \| country \| ip \| iprange \| securitylevel \| zonelockdown \| waf \| firewallrules \| uablock \| ratelimit \| bic \| hot \| l7ddos \| botfight \| apishield \| botmanagement \| dlp \| firewallmanaged \| firewallcustom.                                                                                                                                                           | string        |

## Page Shield Log Event Fields

| Field        | Description                                                                                                                           | Type                        |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| Action       | The action that was taken against the violation                                                                                       | string enum of log or allow |
| CSPDirective | The violated directive                                                                                                                | string                      |
| Host         | The host on which the resource was seen                                                                                               | string                      |
| PageURL      | The page URL on which the violation was seen                                                                                          | string                      |
| PolicyID     | The ID of the violated policy                                                                                                         | string                      |
| ResourceType | The resource type of the violated directive. Possible values include `script`, `connection` or `other` for unmonitored resource types | string                      |
| Timestamp    | The timestamp when the report was received                                                                                            | int                         |
| URL          | The resource URL                                                                                                                      | string                      |
| URLHost      | The domain host of the URL                                                                                                            | string                      |

<!-- document id=cf9af15d42ce11cbead372578dccd071059f1b74194b0b0b7ec2108e05ccccff url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-pci-4-compliance.md -->

# eCDN PCI 4.0 Compliance Tools

The eCDN PCI tools leverage Cloudflare Page Shield to help you meet the latest PCI 4.0 requirements. Page Shield provides tools for monitoring and addressing specific client-side security requirements outlined in the PCI DSS v4.0 standards.

While eCDN significantly assists with compliance, you must continue to manage your PCI certification process and make sure that you are following all applicable requirements. Configure the PCI Page Shield policies to meet your specific needs.

## Page Shield Overview

Page Shield manages scripts loaded by website visitors and triggers alert notifications for security teams when resource changes occur or are flagged as malicious.

Enabling Page Shield:

- Adds a [Content Security Policy (CSP) deployed with a report-only directive](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-supported-csp-directives.md) to collect information from the browser. This allows eCDN to provide you with a list of all scripts running on your application and the connections they make to third-party endpoints.
- Captures detected scripts for your storefront hostnames, respectively, including infrequent and inactive ones.

Since Page Shield monitoring is based on sampling, there may be a small delay between deploying a script and having this data available in the results.

### Page Shield Detection

Page Shield implements different mechanisms to determine if a script, or a connection made by a script, is malicious. These mechanisms include:

- Malicious script detection: Page Shield downloads the script file and runs it through a classifier. The classifier is a machine learning (ML) model that can detect malicious operations patterns, such as Magecart-type attacks. Page Shield also provides individual scores from 1 to 99 for different malicious code detections. The score threshold for considering a script as malicious is currently set to 10. If the script classification score is below 10, use the Page Shield [getPageShieldScripts](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldScripts) endpoint to retrieve the list of malicious scripts.
- Malicious URL checks: Page Shield searches threat intelligence feeds for the URLs of your JavaScript dependencies to determine if any of those scripts should be categorized as malicious. We do not alert on the malicious URL checks as it not required for PCI compliance.
- Malicious domain checks: Page Shield searches threat feeds for the domains of your client-side JavaScript dependencies to determine if any of those scripts are being served from a known malicious domain. A domain previously reported as malicious can later be reported as non-malicious if, after further analysis, the domain is deemed safe. Page Shield also checks the target domains of connections made by scripts in your domain's pages, following the same approach described for scripts. We do not alert on the malicious URL checks as it not required for PCI compliance

Threat feed updates trigger new checks for previously detected scripts or connections, which means that the Page Shield monitoring always reflects the latest categorization.

### Page Shield Alerts and Notifications

Configure alerts for:

- New resources alerts. Receive a notification when new resources are displayed in your storefront requests.
- Code change alerts. Receive a notification when JavaScript dependencies change in the pages of your storefront requests.
- Malicious script alerts. Receive a notification when Cloudflare detects JavaScript code classified as malicious in a storefront request.

**note:** Malicious URL and malicious domain alerts are not included in the alerting and notification via Webhooks because these alerts are not part of the PCI 4.0 requirements.

### Page Shield Policies

Policies use Content Security Policy (CSP) directives to define the resources that are allowed on your applications. Policies can log violations and also enforce an allowlist of resources, effectively blocking resources not included in the policies. According to this model, you define what is allowed and reject everything else. This approach helps you reduce the attack surface for unwanted third-party scripts in your application. To set up a Page Shield policy in Business Manager, see [Configure a Page Shield Policy for the eCDN](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_eCDN_page_shield_policy.htm) in _Salesforce Help_.

#### Page Shield Policy Actions

Each Page Shield policy performs one of the following actions:

- `Log`: Page Shield logs any resources not covered by the policy, without blocking any resources. Use the `Log` action to validate a new policy before deploying it. Resources not covered by the policy are reported as policy violations.
- `Allow`: Page Shield blocks any resources not explicitly allowed by the policy. Switch to the `Allow` action after you validate a new policy using the `Log` action, so that your policy does not block essential application resources and impact your application's end users. Policies with the `Allow` action log policy violations for any blocked resources.

#### Page Shield Policy Alerts

You receive an alert when:

- A policy is created for the zone using the `Allow` action.
- A new or a changed script or resource is listed in the allowed policy sources.
- Page Shield notification is correctly set up for alerts.

You do not receive an alert when:

- No configured policies exist in the zone.
- A policy is configured with the `Log` action.
- A policy is disabled.

#### Page Shield Policy Reporting

To obtain policy violation information:

- [Create a Logpush job for your AWS S3 bucket](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).
  - Logpush jobs only retrieve violation logs.
- [Access policy violation logs in Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-access-violation-logs.md)
  - The Log Center contains both audit logs and violation logs.

**note:** Audit events for policy additions or modifications are only available in the Log Center.

## Set Up Page Shield for PCI 4.0 Compliance

### Step 1. Set Up Script Monitoring

Use Page Shield script monitoring to:

- Keep track of JavaScript across all pages, including payment-related pages.
- Use filters to focus on specific parts of your website, vendors, or dependencies.
- Identify and fix script-related issues that could impact website security.
- Keep track of all third-party scripts on your website and make sure that they are compliant with your policies.
- Troubleshoot script-related errors and exceptions.

To set up script monitoring in pages requiring PCI compliance:

Call the CDN Zones API [Get page shield scripts](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldScripts) endpoint to retrieve the list of scripts and inventory dependencies.

- Specify a `limit` parameter value that does not exceed 200.
- Use different query parameters, for example: `pageUrl`, `prioritizeMalicious`, `status`, and `urls`, to focus on scripts that are running on the pages of interest.
- The results are paginated. View the pagination-related parameters in the response header.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/page-shield/scripts?excludeCdnCgi=true&orderBy=last_seen_at&direction=desc&offset=0&limit=3" --request 'GET' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json'
```

The following video shows examples of how to retrieve detected scripts:

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/F2kewfEdGwzAMaVTM4seRh" title="Get Page Shield Scripts" type="vidyard"}

#### Script Monitoring Best Practices

- Use filters to focus on the most important scripts on your website, for example: payment- and cart-related pages.
- Set up alerts to notify you of script-related issues. For details, see [Set Up Notifications and View Violation Logs](#step-3-set-up-notifications-and-view-violation-logs).
- Regularly review monitoring data to identify trends or patterns.
- Work with your development team to fix identified script-related issues.

### Step 2. Define Authorization Policies

Use Page Shield authorization policies to:

- Enhance compliance with security standards.
- Set appropriate Content Security Policy (CSP) headers, which control the scripts that are allowed to execute on your pages.
- Improve security by blocking unauthorized scripts.
- Reduce the risk of malicious code execution.

To authorize scripts using policies:

1. Identify the scripts that are required for the payments page. Using this information, create a Page Shield policy targeting a particular set of pages, for example:

   ```bash
   curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/f_ecom_bcxj_prd/zones/{zoneId}/page-shield/policies" \
     --request POST \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data-binary @- <<'JSON'
   {
     "action": "allow",
     "description": "Policy for payment page",
     "enabled": true,
     "expression": "ends_with(http.request.uri.path, \"/payments\")",
     "value": "script-src 'none' '*.stripe.com' '*.klarna.com'"
   }
   JSON
   ```

2. Refer to [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md) and [page shield directives](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-supported-csp-directives.md) to effectively target specific pages and scripts.

   **note:** The fields in [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md) apply to custom rules and rate limiting rules. Page Shield expressions aren't restricted to that list. Expressions are passed directly to Cloudflare without allowlist validation, so Cloudflare-supported fields that aren't shown there can also be valid. For Page Shield, that table is a reference, not an exhaustive list. Page Shield expression fields also differ from the [Page Shield log event fields](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-zones-logpush-log-field.md#page-shield-log-event-fields).

The following videos show examples of how to set up Page Shield script monitoring:

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/WBqPuQ1rtnsaANkBiY4BqK" title="Create a Page Shield policy with log mode" type="vidyard"}

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/v4QREm5m1cKwdS7VvtmRZ2" title="Demo checkout page before the policy is in allow mode" type="vidyard"}

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/37Ts9EeyveZdcYRGRTwgrY" title="Updating a policy to allow specific scripts" type="vidyard"}

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/1QPECt4vn8qfFHw6DWJWTe" title="Demo the checkout page in which the policy is in allow mode" type="vidyard"}

### Step 3. Set Up Notifications and View Violation Logs

#### Set Up Notifications

To set up Page Shield notifications, set up a webhook endpoint to receive new or modified script notifications from Cloudflare. You can get the zone names by using the CDN API [getZonesInfo](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getZonesInfo) endpoint. For example:

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/{organizationId}/page-shield/notifications" \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>" \
--data '{ "webhookUrl": "https://my.webhook.url/pageshield-notification", "secret": "<my_secret>",
          "zones": [ "mystorefront.com", "prd-abcd-my-proxy-zone-storefront-com.cc-ecdn.net" ] }'
```

To delete a webhook:

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/{organizationId}/page-shield/notifications/{webhookId}" \
  --request DELETE \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <token>"
```

#### View Violation Logs

[Access available violation logs in the Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-access-violation-logs.md) or by setting up a [eCDN Logpush job](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html) to stream the violations to your S3 bucket.

**note:** Page Shield policy violation logs are generated when events are received rather than when they occur in the browser. The Firefox browser sends CSP events in real time.

The following video shows examples of how to configure an alert, Slack integration, and how to manage alerts by zones:

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/WJVGf8vrg3cxUJseZzBRhe" title="Set Up Page Shield Notifications" type="vidyard"}

## eCDN Zones Page Script API Endpoints

### Get Scripts Identified by Page Shield

- [Get Page Shield scripts](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldScripts) - Get all scripts matching the specified query parameters. Results are paginated and the script you are interested in might not be in this result. Use the response header pagination information to modify the offsets and scan through different pages. You can use the query parameters to focus on scripts that are meaningful to your payments pages.
- [Get Page Shield script](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldScript) - Get details of a particular script specified by a script ID.

### Configure Page Shield Policies

- [Get Page Shield policies](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldPolicies) - Get all Page Shield policies set for a particular zone.
- [Create Page Shield policy](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createPageShieldPolicy) - Create a Page Shield policy for a zone. While creating the Page Shield policies, you can [reference expression fields](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md#fields). Page Shield doesn't limit expressions to that list. The directives that are set are captured in the values field of the policy. The [list of allowed directives](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-supported-csp-directives.md) and sample usage are captured here.
- [Get Page Shield policy](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldPolicy) - Get the specified Page Shield policy for a zone.
- [Update Page Shield policy](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updatePageShieldPolicy) - Update the specified Page Shield policy for a zone.
- [Delete Page Shield policy](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=deletePageShieldPolicy) - Delete the specified Page Shield policy for a zone.

### Configure Page Shield Alerts and Notifications

- [Get Page Shield notification](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldNotification) - Get a Page Shield alert notifications.
- [Put Page Shield notification](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=putPageShieldNotification) - Update or Create a Page Shield alert notifications.
- [Delete Page Shield notification](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=deletePageShieldNotification) - Delete a Page Shield alert notification.

### Configure Logpush for Consuming Policy Violation Logs

- [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html) has the job type [Create a logpush job](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createLogpushJob) for Page Shield, which streams policy violations to a your S3 bucket. [Access both violation logs and audit logs in the Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-access-violation-logs.md).

## Requirement 6.4.3 Compliance Summary

| Defined Requirement                                                                                                     | Meeting Defined Requirements                                                                                                                                                                                                                                                                                                             | Related Resources                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A method is implemented to confirm that each script is authorized.                                                      | Deploy policies on payment pages, based on monitored data suggestions, and/or hashes of inline scripts and thirdparty scripts.<br><br>Create allow policies to define selected JavaScript to run on the payment pages and deny-by-default any JavaScript not explicitly allowed.                                                         | <ul><li>[Create Page Shield policy](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createPageShieldPolicy)</li><li>[Update Page Shield policy](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updatePageShieldPolicy)</li></ul> |
| A method is implemented to assure the integrity of each script.                                                         | Configuring hash-based policies/directives provides a more effective way for validating script integrity.<br><br>Reviewing alerts and violation reports based on hashes of inline and third-party scripts.<br><br>Malicious resource detection is enabled for the your storefront zone and set up an alert for malicious code detection. | <ul><li>[Post Page Shield notification](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=postPageShieldNotification)</li></ul>                                                                                                                                       |
| An inventory of all scripts is maintained with written business or technical justification as to why each is necessary. | Get the list of scripts observed in the page using CDN-API and capture the response. You can get the list of scripts through CDN-API periodically and maintain the inventory on your end. The merchant is responsible for script inventory maintenance.                                                                                  | <ul><li>[Get Page Shield scripts](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldScripts)</li></ul>                                                                                                                                                   |

## Requirement 11.6.1 Compliance Summary

| Defined Requirement                                                                                                                                                                                                                                                          | Guideline on how requirements can be met                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Related resources                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| To alert personnel to unauthorized modification (including indicators of compromise, changes, additions, and deletions) to the HTTP headers and the contents of payment pages as received by the consumer browser.                                                           | Using Page Shield notifications for change code alerts, new resource alerts and new malicious script alerts, identify and be notified of new scripts/resources that are being loaded to the shopper's browser or are considered malicious. You are responsible for configuring these alerts.<br><br>Also monitor the new resources and code changes by configuring Page Shield notifications and policies/ policy violations.<br><br>Violated resources are blocked by the policy and get reported back in real-time for further review through the dashboard. Use Logpush to send these violation logs to your S3 buckets or view them in the Log Center. Allowed resources are constantly being checked by Cloudflare for changes and malicious behaviors. Configure these alerts through CDN-API highlighted on the right. | <ul><li>[Set Up Page Shield notification](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=putPageShieldNotification)</li><li>[Access policy violations logs in Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-access-violation-logs.md)</li></ul> |
| The mechanism functions are performed as follows: <ul><li>At least once every seven days OR </li><li>Periodically (at the frequency defined in the entity’s targeted risk analysis, which is performed according to all elements specified in Requirement 12.3.1).</li></ul> | Violation reports of deployed Policy can be viewed in Logcenter or can be obtained by configuring a logpush job to get in your S3 bucket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | <ul><li>[Create a Logpush job for your AWS S3 bucket.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html)</li><li>[Access policy violation logs in Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-access-violation-logs.md)</li></ul>        |

## Page Shield Limitations

- A maximum of 5 policies is allowed for a particular zone. This is sufficient to configure your policies for PCI compliance.
- A maximum of 5 notifications is allowed for a particular realm.
- [Get page shield scripts](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldScripts) retrieves a maximum of 200 scripts at a time. Use the offset query parameter to view additional results, and use other query parameters to limit the scope search to specific payment paths.
- Log Center logs are retained for 14 days.
- Page Shield monitoring is based on sampling. There might be a small delay between deploying a script and displaying it in the scripts/logs. It is also dependent on browser behavior for script and violation reporting.

## Best Practices with Content Security Policy (CSP)

Make sure that anything in `/cdn-cgi/challenge-platform/` is allowed. Your CSP should allow scripts served from your origin domain (`script-src self`).

If your CSP uses a nonce for script tags, Cloudflare adds these nonces to the scripts it injects by parsing your CSP response header.
If your CSP does not use nonce for script tags and JavaScript Detection is enabled, you might see a console error such as `Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self'". Either the 'unsafe-inline' keyword, a hash ('sha256-b123b8a70+4jEj+d6gWI9U6IilUJIrlnRJbRR/uQl2Jc='), or a nonce ('nonce-...') is required to enable inline execution.` We highly discourage the use of unsafe-inline and instead recommend using CSP nonces in script tags, which we parse and support in our CDN.

## Frequently Asked Questions (FAQs)

Is Page Shield enabled for my account?

- Yes, Page Shield is available by default for all B2C Commerce customers. However, you must define Policies and Notifications to fully use this functionality.

How do Page Shield Policy actions work?

- Page Shield logs any resources not covered by the policy without blocking them. Use this action to validate a new policy before deploying it. Resources not covered by the policy are reported in Policy violation logs.
- Page Shield blocks any resources not explicitly allowed by the policy. After validating a new policy with the Log action, switch to the Allow action to make sure that your policy does not block essential application resources, which could affect your application's end users. Policies with the Allow action log Policy violations for any blocked resources.

Does Page Shield detect inline scripts?

- Yes, inline scripts can be blocked with a Page Shield policy. However, these are not reported in the GET scripts identified by Page Shield and are not included in the Policy violation logs.

Are the CSP reports sampled?

- Yes, Page Shield adds a CSP report-only HTTP header to monitor web page resources to a sample of sent responses. This means there might be a small delay between deploying a script or cookie and having its data in GET scripts identified by Page Shield.

Why do I not see scripts after activating Page Shield?

- Page Shield uses a sampling approach to gather information efficiently, rather than collecting data on every single page view. Domains with lower traffic might take longer to generate initial reports. To speed up the reporting process, actively generate traffic to your application, providing Page Shield with more data to work with, leading to faster report generation.

Why do I see scripts that I do not recognize?

- Scripts often reference other scripts outside your application. If you see unexpected scripts, check them for signs of malicious activity. Retrieve the list of scripts using the [getPageShieldScript](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getPageShieldScript) endpoint.

Why do I see warnings in my browser's developer tools related to Content Security Policy (CSP)?

- Page Shield uses a CSP report-only directive to gather a list of all scripts running on your application. Some browsers display these scripts as warnings in the console pane of their developer tools. For example:

  ```json
  [Report Only] Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'none'".
  Either the 'unsafe-inline' keyword, a hash ('sha256-RFWPLDbv2BY+rCkDzsE+0fr8ylGr2R2faWMhq4lfEQc='), or a nonce ('nonce-...') is required to enable inline execution.
  ```

  Safely ignore these warnings, as they are related to the reports that Page Shield requires to detect loaded scripts.

Why do I get policy violation reports for a domain I allowlisted?

- Policy violations reported via CSP's report-only directive do not consider any redirects or redirect HTTP status codes. This is by design for security reasons. The format of the CSP report-only HTTP header added by Page Shield is as follows:

  ```text
  content-security-policy-report-only: script-src 'none'; connect-src 'none'; report-uri https://csp-reporting.cloudflare.com/cdn-cgi/script_monitor/report?<QUERY_STRING>
  ```

**note:** - The SFCC CDN provider adds the CSP report-only HTTP header used to monitor web page resources to a sample of sent responses. Configuring Page Shield log policies adds other CSP report-only headers to responses. The SFCC CDN provider won't perform any sampling for these report-only headers related to customer-defined policies.
- Some third-party services that you might want to cover in your Page Shield allow policies perform redirects. For example, Google Ads does not work well with CSP policies. If you add the `adservice.google.com` domain to an allow policy, you might receive policy violation reports for this domain due to redirects to a different domain not present in your allow policy. In such cases, the violation report still mentions the original domain, not the redirected destination domain, which can cause some confusion. To address this issue, add the domain of the redirected destination to your allow policy. You may need to add several domains to your policy due to redirects.

How do merchants use eCDN to achieve PCI 3.x compliance?

- eCDN helps merchants meet PCI DSS 2.0 and 3.0 requirement 6.6 through its Web Application Firewall (WAF). Additionally, eCDN supports the latest TLS encryption version, which is crucial for PCI compliance.

How do I get a complete list of the payment page scripts that are loaded and executed in the shopper's browser?

- Obtain detailed information about the third-party scripts loaded on your domain's pages by using the CDN Zones API endpoint. For PCI compliance, filter the page URL and list scripts that are loaded for your payment pages.

Which alerts do the PCI webhook notifications contain?

- Webhook notification types for PCI 4.0 are preconfigured and cannot be modified or customized. The included alerts are:
  - New Code Change Detection Alert: Get notified when the code of a JavaScript file loaded by your users has changed.
  - New Malicious Script Alert: Get notified when a JavaScript file loaded by your users is classified as malicious.
  - New Resources Alert: Get notified when your users load a new resource that has not previously been seen.

Can I get webhook notifications without creating a Page Shield Policy?

- No, a Page Shield policy is necessary in each proxy/legacy zone to receive alerts for script changes, additions, or malicious script detections. For zones with `Policies configured`, you do not receive notifications for resources blocked by an allow policy. [Review these policy violation logs in the Log Center using Logpush](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-access-violation-logs.md).

Do the PCI 4.0 tools work in both legacy and proxy Zones?

- Yes, The CDN ZONES API endpoints enable PCI policy, notifications, and log configurability in both legacy and proxy zones. Migrating to a proxy zone is recommended and is required for Hyperforce enablement.

<!-- document id=adb09e00e40e9623605e9a86523f9af7cfc32bb226d53d5558186dd4a1f34f05 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-rate-limiting-rules.md -->

# eCDN Rate Limiting Rules

Use rate limiting rules to specify rate limits for requests that match a particular expression and then perform an action when those rate limits are reached. With rate limiting rules, improve storefront availability by targeting specific traffic patterns and combating threats, such as bots.

This guide provides an overview on the various rate limiting parameters involved, as well as how to use CDN-API to enable these rules in your zones. Also refer to the [FAQ](#rate-limiting-rules-faq) section at the bottom of this page.

## Build a Rate Limiting Rule

The behavior of a rate limiting rule depends on a number of rate limiting parameters:

- Description
- Rule expression
- Characteristics
- Action
- Period
- Requests per period
- Mitigation timeout
- Counting expression (optional)
- Enabled (optional)
- Position (optional)

## Rate Limiting Parameters

### Description

- Usage in API: `description`
- A description of the rate limiting rule.

### Rule Expression

- Usage in API: `expression`
- Defines when to apply the rule. The rule expression is evaluated to either true or false. If the rule expression evaluates to true, then the rule is executed. For rate limiting rules, the rule's action is only applied if the rate limiting criteria is met at that time.
- For supported comparison operators, logical operators, functions, and fields, see [eCDN Rule Expression Fields](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rule-expression-fields.md).

**important:** **Actions on SLAS login endpoints:** SLAS login is an API surface and cannot serve an interactive challenge. For leaked-credentials matches on SLAS login endpoints, use a rate-limiting rule with the `block` action (HTTP 429) rather than `js_challenge`, `legacy_captcha`, or `managed_challenge`. The rule fires only when a login presents known-leaked credentials, so impact on legitimate traffic is low. A shopper whose valid password appears in a breach corpus is still blocked. Start the rule with the `log` action. While the rule is in log mode, monitor the traffic that matches it and assess whether those requests are safe to block. Then switch to `block`.

### Characteristics

- Usage in API: `characteristics`
- Takes an array of Strings. The characteristics determine how incoming requests are grouped together. Requests with the same values for the defined characteristics are grouped together and share a rate counter.
  - For example, say that _IP_ is used as the rule’s characteristics. If the rate of requests coming from a single IP address exceeds the defined limit, then further requests from that IP address are rate limited. Requests coming from other IP addresses do not share the same rate counter. In other words, the request rate of one IP address does not affect the request rate of other IP addresses.
- The following characteristics are supported:

| Characteristic      | Description                                                                                                                                     | Usage in Characteristics Array |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| IP                  | Groups requests based on the client TCP IP address.                                                                                             | `ip.src`                       |
| IP with NAT support | Uses privacy-preserving techniques to identify unique visitors, including in situations such as requests under NAT sharing the same IP address. | `cf.unique_visitor_id`         |

- Note that you cannot use both _IP with NAT support_ and _IP_ as characteristics of the same rate limiting rule. Therefore, the API usage examples are as follows:

  `"characteristics": ["ip.src"]`

  or

  `"characteristics": ["cf.unique_visitor_id"]`

**note:** Our recommendation is to use _IP with NAT support_. See the [FAQ](#rate-limiting-rules-faq) section for more details.

### Action

- Usage in API: `action`
- The action to perform when the rate limiting criteria is met.
- The following actions are supported: `block`, `log`, `legacy_captcha`, `js_challenge`, or `managed_challenge`
  - See documentation [here](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-zones-custom-rules.md#rule-actions) for more info on each action.

### Period

- Usage in API: `period`
- The period of time to consider when evaluating the request rate.
- The following values are supported: `10`, `60`, `120`, `300`, `600`, or `3600` (in seconds).

### Requests Per Period

- Usage in API: `requestsPerPeriod`
- Any positive integer value. Represents the limit for the number of requests in the specified period of time.

### Mitigation Timeout

- Usage in API: `mitigationTimeout`
- The “timeout” time. Once the rate limiting criteria is met, the rate limiting rule continues to apply the action to further requests matching the rule expression for the period of time defined in this field.
- The following values are supported: `0`, `10`, `60`, `120`, `300`, `600`, `3600`, or `86400` (in seconds).
  - The `mitigationTimeout` value must also be greater than or equal to the defined `period`.
- When the mitigation timeout is set to 0, the rate limiting rule only throttles requests that exceed the configured maximum rate. The chosen action is applied to those excess requests, while requests within the limit are still allowed.
- When the mitigation timeout is set to a value greater than 0, the rate limiting rule enforces the chosen action on all incoming requests for the specified duration immediately after the threshold is exceeded.

### Counting Expression (optional)

- Usage in API: `countingExpression`
- Defines the request criteria, which we want to rate limit. In other words, this parameter defines when to increment the rate counter. The rate counter keeps track of the number of requests per period. When the rate counter exceeds the defined requests per period limit we have set, the rule’s action is executed.
  - If the counting expression is not provided, then the counting expression is the same as the rule expression.
  - The counting expression supports the option to rate limit based on _HTTP response code._ This is not possible when using only the rule expression. The counting expression should be used if you wish to rate limit based on the HTTP response code. Refer to the [FAQ](#rate-limiting-rules-faq) for additional examples of when to use the counting expression.
- The validation for the counting expression is the same as the rule expression, with the addition of the following field:

| Field              | Description                                             | Usage in Counting Expression | Type    | Example                       |
| ------------------ | ------------------------------------------------------- | ---------------------------- | ------- | ----------------------------- |
| HTTP Response Code | Represents the HTTP status code returned to the client. | `http.response.code`         | Integer | ``http.response.code eq `400` |

### Enabled (optional)

- Usage in API: `enabled`
- Whether the rate limiting rule is enabled. Default value is `true`.

### Position (optional)

- Usage in API: `position`
- Providing this parameter inserts the rule at a certain relative position in the ruleset. This parameter may be used when creating or updating a rate limiting rule.

  - We validate that the provided index matches a rule in the current ruleset. If the position is not provided when creating a rate limiting rule, the rule is added to the end of the ruleset by default.

  ```json
  # Places the rule before rule <RULE_ID>

  "position": {
    "before": "<RULE_ID>"
  }

  or

  # Places the rule after rule <RULE_ID>

  "position": {
    "after": "<RULE_ID>"
  }
  ```

## Best Practices

The following section covers common use cases for rate limiting rules. You may use these examples, combine them as needed, and adjust them to your own business needs.

### Enforce Granular Access Control

- Enforce granular access control to resources, including access control based on criteria such as user agent, IP address, host, country, and world region.
- **Example A:** Limit the rate of requests performed by individual user agents.
  - Rule expression: `http.user_agent eq "MobileApp"`
  - Rate: 100 requests / 10 minutes
  - Action: Managed Challenge
- **Example B:** Exclude or include specific IP addresses or ASNs from a rate limiting rule.
  - Rule expression: `http.request.uri.path eq "/status" and http.request.method eq "GET" and not ip.src in { <defined IPs> }`
  - Rate: 10 requests / 1 minute
  - Action: Managed Challenge

### Protect Against Credential Stuffing

- Protect against credential stuffing and account takeover attacks. A typical use case is to protect a login endpoint. You may also create multiple rate limiting rules to define increasing penalties to manage clients making too many requests.
- **Example A:** Protect against too many failed login attempts.
  - Rule expression: `http.host eq "example.com" and http.request.uri.path eq "/login" and http.request.method eq "POST"`
  - Counting expression: `http.request.uri.path eq "/login" and http.request.method eq "POST" and http.response.code in {401 403}`
  - Rate: 5 requests / 1 minute
  - Action: Managed Challenge
- **Example B:** Create another protection layer for if a user were to pass the challenge presented by the rule defined in Example A. If the user exceeds this second threshold, they are blocked from accessing the login page for 10 minutes.
  - Rule expression: `http.host eq "example.com" and http.request.uri.path eq "/login"`
  - Counting expression: `http.request.uri.path eq "/login" and http.request.method eq "POST" and http.response.code in {401 403}`
  - Rate: 20 requests / 10 minutes
  - Action: Block for 10 minutes

### Limiting The Number of Operations

- Limit the number of operations performed by individual clients. Prevent scraping by bots, accessing sensitive data, bulk creation of new accounts, and programmatic buying.
- **Example A:** Prevent content scraping (via query string).
  - Rule expression: `http.request.uri.path eq "/merchant" and http.request.uri.query contains "action=lookup_price"`
  - Rate: 10 requests / 1 minute
  - Action: Managed Challenge
- **Example B:** Limit requests from bots. A general approach to identify traffic from bots is to rate limit requests that trigger a large volume of error response status codes.
  - Rule expression: `http.host eq "example.com"`
  - Counting expression: `http.response.code in {401 403}`
  - Rate: 25 requests / 2 minutes
  - Action: Managed Challenge
- **Example C:** Consider using the `bot_management` fields if your zone has Bot Management entitled.
  - Rule expression: `cf.bot_management.score lt 30 and http.request.uri.query contains "action=delete"`
  - Rate: 20 requests / 5 minutes
  - Action: Block for 1 hour

### Allow Verified Search Crawlers and Detect Leaked Credentials

- Use the `cf.client.bot` and `cf.verified_bot_category` fields to allow verified search-engine crawlers (Googlebot, Bingbot, and so on) through your rules, and to rate limit AI crawlers. Use the `cf.waf.credential_check.*` fields to act on requests that submit leaked credentials.
- **Example A:** Rate limit high-volume login POSTs but allow verified search crawlers through.
  - Rule expression: `(http.request.uri.path contains "/Account-Login" and http.request.method eq "POST" and not cf.client.bot)`
  - Characteristics: `ip.src`
  - Rate: 10 requests / 60 seconds
  - Action: Managed Challenge
- **Example B:** Block all login requests from an IP after it submits credentials that match a known leak. Because the counting expression—not the rule expression—checks for leaked credentials, the block applies to every subsequent login request from that IP, not only the requests that carry leaked credentials.
  - Rule expression: `(http.request.uri.path contains "/Account-Login" and http.request.method eq "POST")`
  - Counting expression: `(cf.waf.credential_check.username_and_password_leaked)`
  - Characteristics: `ip.src`
  - Rate: 1 request / 60 seconds
  - Action: Block

## API Usage

The following sections contain common use cases.

### Create a Rate Limiting Rule

This endpoint creates a rate limiting rule in the specified zone.

- Refer to the _Rate Limiting Parameters_ section above for more information on parameter validation.

**important:** Newly created rules are enabled by default and added to the end of the ruleset unless specified otherwise. A maximum of 50 rate limiting rules is allowed in a single zone.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn rate-limit create \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --description "Rate limit form traffic" \
  --expression 'http.request.uri.path eq "/form"' \
  --characteristics cf.unique_visitor_id --action block \
  --period 60 --requests-per-period 10000 --mitigation-timeout 600 \
  --counting-expression 'http.request.uri.path eq "/form" and http.response.code eq 400' \
  --no-enabled --position-before 2c0fc9fa937b11eaa1b71c4d701ab86e
```

Alternatively, use the API:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/rate-limiting/rules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "description": "Rate limit form traffic",
    "expression": "http.request.uri.path eq \"/form\"",
    "characteristics": ["cf.unique_visitor_id"],
    "action": "block",
    "period": 60,
    "requestsPerPeriod": 10000,
    "mitigationTimeout": 600,
    "countingExpression": "http.request.uri.path eq \"/form\" and http.response.code eq 400",
    "enabled": false,
    "position": {
        "before": "2c0fc9fa937b11eaa1b71c4d701ab86e"
    }
}'
```

**Sample Success Response - 201 HttpStatus Code**
Response body contains the rate limiting rule that was created.

```json
{
  "data": {
    "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
    "description": "Rate limit form traffic",
    "expression": "http.request.uri.path eq \"/form\"",
    "characteristics": ["cf.unique_visitor_id"],
    "action": "block",
    "period": 60,
    "requestsPerPeriod": 10000,
    "mitigationTimeout": 600,
    "countingExpression": "http.request.uri.path eq \"/form\" and http.response.code eq 400",
    "enabled": false,
    "lastUpdated": "2022-12-14T21:25:22.329194Z"
  }
}
```

### Get All Rate Limiting Rules

This endpoint returns all of the rate limiting rules in the specified zone in order of priority. If no rate limiting rules exist, a 404 Not Found response is returned.

```sh

curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/rate-limiting/rules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'

```

**Sample Success Response - 200 HttpStatus Code**
Response body contains all of the current rate limiting rules in the specified zone.

```json
{
  "data": [
    {
      "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
      "description": "Rate limit form traffic",
      "expression": "http.request.uri.path eq \"/form\"",
      "characteristics": ["cf.unique_visitor_id"],
      "action": "block",
      "period": 60,
      "requestsPerPeriod": 10000,
      "mitigationTimeout": 600,
      "countingExpression": "http.request.uri.path eq \"/form\" and http.response.code eq 400",
      "enabled": false,
      "lastUpdated": "2022-12-14T21:25:22.329194Z"
    },
    {
      "ruleId": "2c0fc9fa937b11eaa1b71c4d701ab86e",
      "description": "Rate limit by AS num",
      "expression": "ip.src.asnum eq 12345",
      "characteristics": ["ip.src"],
      "action": "managed_challenge",
      "period": 600,
      "requestsPerPeriod": 1000,
      "enabled": true,
      "lastUpdated": "2022-12-14T21:47:24.323223Z"
    }
  ]
}
```

### Get a Rate Limiting Rule

This endpoint returns the requested rate limiting rule. If the requested rule does not exist, a 404 Not Found response is returned.

```sh

curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/rate-limiting/rules/$RULEID" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'

```

**Sample Success Response - 200 HttpStatus Code**
Response body contains the requested rate limiting rule.

```json
{
  "data": {
    "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
    "description": "Rate limit form traffic",
    "expression": "http.request.uri.path eq \"/form\"",
    "characteristics": ["cf.unique_visitor_id"],
    "action": "block",
    "period": 60,
    "requestsPerPeriod": 10000,
    "mitigationTimeout": 600,
    "countingExpression": "http.request.uri.path eq \"/form\" and http.response.code eq 400",
    "enabled": false,
    "lastUpdated": "2022-12-14T21:25:22.329194Z"
  }
}
```

### Update a Rate Limiting Rule

This endpoint updates the requested rate limiting rule. If the requested rule does not exist, a 404 Not Found response is returned.

- You must provide at least one rate limiting parameter in the request body.
- In the scenario where you have set the `countingExpression` but wish to remove it (and thus have it default to the rule expression), you must include `"countingExpression": ""` in the request body to reset the value.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/rate-limiting/rules/$RULEID" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "description": "Log verified bot traffic to form",
    "expression": "http.request.uri.path eq \"/form\" and cf.bot_management.verified_bot",
    "characteristics": ["cf.unique_visitor_id"],
    "action": "log",
    "period": 10,
    "requestsPerPeriod": 500,
    "mitigationTimeout": 60,
    "countingExpression": "",
    "enabled": true,
    "position": {
        "after": "2c0fc9fa937b11eaa1b71c4d701ab86e"
    }
}'
```

**Sample Success Response - 200 HttpStatus Code**
Response body contains the requested rate limiting rule.

```json
{
  "data": {
    "ruleId": "ffffe61cf25e4ec49c34b029ff3060f7",
    "description": "Log verified bot traffic to form",
    "expression": "http.request.uri.path eq \"/form\" and cf.bot_management.verified_bot",
    "characteristics": ["cf.unique_visitor_id"],
    "action": "log",
    "period": 10,
    "requestsPerPeriod": 500,
    "mitigationTimeout": 60,
    "enabled": true,
    "lastUpdated": "2022-12-14T21:25:22.329194Z"
  }
}
```

### Delete a Rate Limiting Rule

This endpoint deletes the requested rate limiting rule. If the requested rule does not exist, a 404 Not Found response is returned.

```sh

curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/rate-limiting/rules/$RULEID" \
--request 'DELETE' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'

```

**Sample Success Response - 204 HttpStatus Code (No Content)**

## Rate Limiting Rules FAQ

- **How does the counting expression differ from the rule expression?**
  - The rule expression defines when to _evaluate_ the rate limiting rule. If a request matches the rule expression, then the rate limiting rule is evaluated. When we evaluate a rate limiting rule, we check if the rate counter exceeds the defined requests per period. If so, then the rule’s action is applied.
  - The counting expression defines _the kind of requests_ we want to rate limit. If a request matches the counting expression, then the rate counter is incremented. The counter keeps tracks of how many requests have met the rate limiting criteria.
- **When should I use the counting expression?**
  - In most use cases, you do not need to provide the counting expression as it is sufficient to have the counting expression be the same as the rule expression.
    - **Example A:** Rate limit high traffic going to a particular path. If the number of requests surpasses 10,000 requests in 1 minute, then block further requests to that path for 10 minutes.
      - Rule expression: `http.request.uri.path eq "/path"`
      - Counting expression (by default): `http.request.uri.path eq "/path"`
      - Rate: 10000 requests / 1 minute
      - Action: Block for 10 minutes
  - In some cases, we want to rate limit based on the HTTP response code. For these use cases, you must provide the counting expression as it offers the additional response code field. Rate limiting based on HTTP response code is not possible when using only the rule expression.
    - **Example B:** Prevent automated actors from overloading a form with malicious traffic by presenting them with a managed challenge. Rate limit traffic going to a particular form **that returns a 400 response code**.
      - Rule expression: `http.request.uri.path eq "/form"`
      - Counting expression: `http.request.uri.path eq "/form" and http.response.code eq 400`
      - Rate: 15 requests / 5 minutes
      - Action: Managed Challenge
  - Another example for where you may want the counting expression to differ from the rule expression is the following:
    - **Example C:** Protect a login endpoint from malicious actors. Once a user makes 15 bad login requests in 10 minutes, block them from visiting the _entire_ site for 1 hour.
      - Rule expression: `http.host eq "example.com"`
      - Counting expression: `http.request.uri.path eq "/login" and http.request.method eq "POST" and http.response.code in {401 403}`
      - Rate: 15 requests / 10 minutes
      - Action: Block for 1 hour
- **How do the characteristics work?**
  - Separate rate counters are kept for each value combination of the defined rule characteristics. In other words, the characteristics determine how incoming requests are grouped together.
    - Consider a rule configured with the following characteristics:
      - IP address
      - HTTP header `x-api-key`
    - In this case, two incoming requests with the same value for the HTTP header `X-API-Key` but _different_ IP addresses are counted separately, since the value combination is different. Additionally, counters are not shared across data centers.
  - Note that CDN-API currently only accepts _IP_ or _IP with NAT support_ as characteristics, and that these two characteristics cannot be used in the same rate limiting rule. Therefore, the usage example presented above is not relevant at this time, but serves as example to help understand how characteristics work.
- **Why is it recommended to use IP with NAT support?**
  - We recommend using IP with NAT support because it is able to identify unique visitors even in situations where requests may come into the eCDN under the same IP address.
  - **Using IP with NAT support is necessary for customers who have stacked eCDN configurations.** This is because requests route through the stacked provider before hitting the eCDN. Using IP with NAT support ensures that each unique visitor is properly identified and that the stacked provider source IPs are not rate limited.
- **Why does rule order matter?**
  - Rate limiting rules are evaluated in the order they are returned in the response body, starting with the first rule listed. To update the priority of a particular rule, you may use the PATCH endpoint and provide the `position` parameter in the request body.
  - If a request meets the rate limiting criteria and triggers the rate limiting rule to be executed, the rule’s action is executed and _no other rate limiting rules are evaluated for that particular request_. When the next request comes in, rule evaluation starts back at the top of the ruleset.
- **How do I construct the rule expression?**
  - See the documentation [here](https://developers.cloudflare.com/ruleset-engine/rules-language/expressions/) for more information regarding constructing rule expressions.
- **How do I use a particular field in the rule expression?**
  - See the documentation [here](https://developers.cloudflare.com/ruleset-engine/rules-language/fields) for more information on a particular field’s usage.

<!-- document id=6854d95079e7fec7f8e5dfe22c1ef5a41dc69c9df4555ab7d8a9491dd49272aa url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-rule-expression-fields.md -->

# eCDN Rule Expression Fields

Use these comparison operators, logical operators, functions, and fields in eCDN custom rule expressions and rate limiting rule expressions.

A rate limiting counting expression supports one additional field, HTTP Response Code (`http.response.code`). See [Counting Expression](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rate-limiting-rules.md#counting-expression-optional).

Cache rule expressions use these operators and functions with a different set of fields. See [Supported Expression Fields for Cache Rules](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-cache-rules.md#supported-expression-fields-for-cache-rules).

Page Shield policies can use these fields as a reference when targeting specific pages. Page Shield expressions aren't restricted to this list. See [eCDN PCI 4.0 Compliance Tools](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-pci-4-compliance.md).

The maximum length of a custom rule or rate limiting rule expression is 4096 characters.

To create a rule in Business Manager, see [Create a Custom Firewall Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_create_eCDN_firewall_rule.htm&type=5) and [Create a Rate Limiting Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_eCDN_create_rate_limiting_rule.htm&type=5) in _Salesforce Help_.

## Comparison Operators

`eq`, `ne`, `contains`, `matches`, `in`, `lt`, `le`, `gt`, `ge`

## Logical Operators

`not`, `and`, `or`, `xor`

## Functions

| **Function**        | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | **Usage in Expression**                                                                                                     | **Type** | **Example**                                                                                                                                                                                                                      |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| any                 | Returns `true` when the comparison operator in the argument returns `true` for _any_ of the values in the argument array. Returns `false` otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `any(Array<Boolean>)`                                                                                                       | Boolean  | `any(http.request.headers[\"content-type\"][*] eq \"application/x-www-form-urlencoded\")`                                                                                                                                        |
| all                 | Returns `true` when the comparison operator in the argument returns `true` for _all_ values in the argument array. Returns `false` otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `all(Array<Boolean>)`                                                                                                       | Boolean  | `all(http.request.headers[\"content-type\"][*] eq \"application/json\")`                                                                                                                                                         |
| concat              | Takes a comma-separated list of values. Concatenates the argument values into a single String.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `concat( String` <code>&#124;</code> `Integer` <code>&#124;</code> `Bytes` <code>&#124;</code> `Array elements)`            | String   | `concat(http.request.uri.path,\"String\") eq \"sampleString\"`                                                                                                                                                                   |
| ends_with           | Returns `true` when the source ends with the given substring. Returns `false` otherwise. The source cannot be a literal value (for example, `"foo"`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `ends_with(sourceString, substringString)`                                                                                  | Boolean  | `ends_with(http.request.uri.path, \".html\")`                                                                                                                                                                                    |
| len                 | Returns the byte length of a String or Bytes field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `len(String` <code>&#124;</code> `Bytes)`                                                                                   | Integer  | `len(http.host) lt 20`                                                                                                                                                                                                           |
| lookup_json_integer | Returns the integer value associated with the supplied `key` in `field`. <br><br>Note: The `field` must be a string representation of a valid JSON document. The `key` can be an attribute name, a zero-based position number in a JSON array, or a combination of these two options (as extra function parameters), while following the hierarchy of the JSON document to obtain a specific integer value. This function only works for plain integers. For example, it will not work for floating numbers with a zero decimal part such as `42.0`.                                                                                                                                                                                                                  | `lookup_json_integer(fieldString, keyString` <code>&#124;</code> `Integer [, keyString` <code>&#124;</code> Integer `, …])` | Integer  | <br>`lookup_json_integer(http.cookie, \"sampleCookie\") eq 10` <br><br>`lookup_json_integer(http.cookie, 1) eq 10` <br><br>`lookup_json_integer(http.cookie, 1, \"sampleCookie \") eq 10`                                        |
| lookup_json_string  | Returns the string value associated with the supplied `key` in `field`. <br><br>Note: The `field` must be a string representation of a valid JSON document. The `key` can be an attribute name, a zero-based position number in a JSON array, or a combination of these two options (as extra function parameters), while following the hierarchy of the JSON document to obtain a specific value.                                                                                                                                                                                                                                                                                                                                                                    | `lookup_json_string(fieldString, keyString` <code>&#124;</code> `Integer [, keyString` <code>&#124;</code> Integer`, …])`   | String   | <br>`lookup_json_string(http.cookie, \"sampleCookie\") eq \"sampleString\"` <br><br>`lookup_json_string(http.cookie, 1) eq \"sampleString\"` <br><br> `lookup_json_string(http.cookie, 1, \"sampleCookie\") eq \"sampleString\"` |
| lower               | Converts a string field to lowercase. Only uppercase ASCII bytes are converted. All other bytes are unaffected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `lower(String)`                                                                                                             | String   | `lower(http.host) eq \"www.example.com\"`                                                                                                                                                                                        |
| starts_with         | Returns `true` when the source starts with a given substring. Returns `false` otherwise. The source cannot be a literal value (for example, `"foo"`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `starts_with(sourceString, substringString)`                                                                                | Boolean  | `starts_with(http.request.uri.path, \"/blog\")`                                                                                                                                                                                  |
| substring           | Returns part of the `field` value (the value of a String or Bytes field) from the `start` byte index up to (but excluding) the `end` byte index. <br><br>The first byte in `field` has index `0`. If you do not provide the optional `end` index, the function returns the part of the string from `start` index to the end of the string. The `end` index must be greater than the `start` index. The `start` and `end` indexes can be negative integer values, which allows you to access characters from the end of the string instead of the beginning.                                                                                                                                                                                                           | `substring(fieldString` <code>&#124;</code> `Bytes, startInteger [, endInteger])`                                           | String   | <br>`substring(http.request.uri.path, 2, 5) eq \"sampleString\"` <br><br>`substring(http.request.uri.path, 2) eq \"sampleString\"`                                                                                               |
| upper               | Converts a string field to uppercase. Only lowercase ASCII bytes are converted. All other bytes are unaffected.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `upper(String)`                                                                                                             | String   | `upper(http.host) eq \"WWW.EXAMPLE.COM\"`                                                                                                                                                                                        |
| url_decode          | Decodes a URL-formatted string defined in `source`, as in the following: <br>- `%20` and `+` decode to a space character (``). <br><br>The `options` parameter is optional. You must provide any options as a single string wrapped in quotes, such as `"r"` or `"ur"`. The available options are the following: <br>- `r`: Applies recursive decoding. For example, `%2520` will be decoded twice (recursively) to a space character. <br>- `u`: Enables Unicode percent decoding. For example, `%E2%98%81%EF%B8%8F` will be decoded to a cloud emoji. | `url_decode(sourceString [, optionsString])` | String | <br>`url_decode(http.request.full_uri) contains \"sampleString\"` <br><br><br>`url_decode(http.request.full_uri, \"ur\") contains \"sampleString\"` |

## Fields

**note:** Deprecated values `ip.geoip.asnum`, `ip.geoip.country` and `ip.geoip.continent` have been replaced with `ip.src.asnum`, `ip.src.country`, and `ip.src.continent`, respectively.

**note:** The fields in the following table apply to custom rules and rate limiting rules. Page Shield expressions aren't restricted to this list. Expressions are passed directly to Cloudflare without allowlist validation, so Cloudflare-supported fields that aren't shown here can also be valid. For Page Shield, this table is a reference, not an exhaustive list.

| **Field**                    | **Description**                                                                                                                                                                                                                                                                                                               | **Usage in Expression**                                | **Type**         | **Example**                                                                                                                                  |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| AS Number                    | The Autonomous System (AS) number associated with the client IP address.                                                                                                                                                                                                                                                      | `ip.src.asnum`                                         | Integer          | `ip.src.asnum eq 12345`                                                                                                                      |
| Cookie                       | Represents the entire cookie as a string.                                                                                                                                                                                                                                                                                     | `http.cookie`                                          | String           | `http.cookie eq \"session=8521F670545D7865F79C3D7BEDC29CCE;-background=light\"`                                                              |
| Cookie value of              | The Cookie HTTP header on the request, represented as a Map (associative array) keyed by cookie name. Distinct from the existing "Cookie" field (`http.cookie`), which is the entire Cookie header as a single string.                                                                                                        | `http.request.cookies`                                 | Map              | `any(http.request.cookies[\"session\"][*] eq \"abc123\")`                                                                                    |
| Country                      | Represents the 2-letter country code in [ISO 3166-1 Alpha 2](https://www.iso.org/obp/ui/#search/code/) format.                                                                                                                                                                                                                | `ip.src.country`                                       | String           | `not ip.src.country eq \"US\"`                                                                                                               |
| Host Name                    | Represents the host name used in the full request URI.                                                                                                                                                                                                                                                                        | `http.host`                                            | String           | `http.host eq \"www.example.com\"`                                                                                                           |
| IP Address                   | Represents the client TCP IP address.                                                                                                                                                                                                                                                                                         | `ip.src`                                               | IP address       | `ip.src in {93.184.216.34 192.168.123.132}`                                                                                                  |
| HTTP Headers                 | Represents HTTP request headers as a Map (or associative array).                                                                                                                                                                                                                                                              | `http.request.headers`                                 | Map\String\Array | `any(http.request.headers[\"content-type\"][*] eq \"application/json\")`                                                                     |
| URI Full                     | Represents the full URI as received by the web server.                                                                                                                                                                                                                                                                        | `http.request.full_uri`                                | String           | `http.request.full_uri eq \"htt­ps://www.example.com/path/index?section=123456&expand=comments\"`                                            |
| URI                          | Represents the URI path and query string of the request.                                                                                                                                                                                                                                                                      | `http.request.uri`                                     | String           | `http.request.uri eq \"/path/index?section=123456&expand=comments\"`                                                                         |
| URI Path                     | Represents the URI path of the request.                                                                                                                                                                                                                                                                                       | `http.request.uri.path`                                | String           | `http.request.uri.path eq \"/path/index\"`                                                                                                   |
| URI Query String             | Represents the entire query string, without the `?` delimiter.                                                                                                                                                                                                                                                                | `http.request.uri.query`                               | String           | `http.request.uri.query eq \"section=123456&expand=comments\"`                                                                               |
| Raw URI Full                 | Similar to the `http.request.full_uri` non-raw field. Represents the full URI as received by the web server without the URI fragment (if any) and without any transformation. Note that this raw field may include some basic normalization by the HTTP server.                                                               | `raw.http.request.full_uri`                            | String           | `raw.http.request.full_uri eq \"htt­ps://www.example.com/path/index?section=123456&expand=comments\"`                                        |
| Raw URI                      | Similar to the `http.request.uri` non-raw field. Represents the URI path and query string of the request without any transformation. Note that this raw field may include some basic normalization by the HTTP server.                                                                                                        | `raw.http.request.uri`                                 | String           | `raw.http.request.uri eq \"/path/index?section=123456&expand=comments\"`                                                                     |
| Raw URI Path                 | Similar to the `http.request.uri.path` non-raw field. Represents the URI path of the request without any transformation. Note that this raw field may include some basic normalization by the HTTP server.                                                                                                                    | `raw.http.request.uri.path`                            | String           | `raw.http.request.uri.path eq \"/path/index\"`                                                                                               |
| Raw URI Query String         | Similar to the `http.request.uri.query` non-raw field. Represents the entire query string without the `?` delimiter and without any transformation. Note that this raw field may include some basic normalization by the HTTP server.                                                                                         | `raw.http.request.uri.query`                           | String           | `raw.http.request.uri.query eq \"section=123456&expand=comments\"`                                                                           |
| HTTP Referer                 | Represents the HTTP Referer request header, which contains the address of the web page that linked to the currently requested page.                                                                                                                                                                                           | `http.referer`                                         | String           | `http.referer contains \"www.example.com\"`                                                                                                  |
| User Agent                   | Represents the HTTP user agent, a request header that contains a characteristic string to allow identification of the client operating system and web browser.                                                                                                                                                                | `http.user_agent`                                      | String           | `http.user_agent eq \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.61 Safari/537.36\"` |
| Request Method               | Represents the HTTP method, returned as a string of uppercase characters.                                                                                                                                                                                                                                                     | `http.request.method`                                  | String           | `http.request.method eq \"GET\"`                                                                                                             |
| Continent                    | Represents the continent code associated with client IP address.<br>`AF` – Africa<br>`AN` – Antarctica<br>`AS` – Asia<br>`EU` – Europe<br>`NA` – North America<br>`OC` – Oceania<br>`SA` – South America<br>`T1` – Tor network                                                                                                | `ip.src.continent`                                     | String           | `ip.src.continent in {\"NA\" \"EU\"}`                                                                                                        |
| WAF Attack Score             | Represents the likelihood that a request is malicious, using a score from 1–99. A score of 1 indicates the request is almost certainly malicious; a score of 99 indicates the request is likely clean. The special score 100 indicates that Cloudflare did not score the request.                                             | `cf.waf.score`                                         | Integer          | `cf.waf.score lt 20`                                                                                                                         |
| Known Bot                    | Indicates whether the request originated from a known good bot or crawler. Available without a Bot Management add-on (base WAF).                                                                                                                                                                                              | `cf.client.bot`                                        | Boolean          | `cf.client.bot`                                                                                                                              |
| Verified Bot Category        | Identifies the specific purpose or type of a verified bot, such as `Search Engine Crawler` or `AI Crawler`. Available without a Bot Management add-on (base WAF). See [Cloudflare's verified bot categories](https://developers.cloudflare.com/bots/concepts/bot/verified-bots/#categories) for the list of supported values. | `cf.verified_bot_category`                             | String (enum)    | `cf.verified_bot_category eq \"Search Engine Crawler\"`                                                                                      |
| Bot Score\*                  | Represents the likelihood that a request originates from a bot using a score from 1–99. A low score indicates that the request comes from a bot or an automated agent.                                                                                                                                                        | `cf.bot_management.score`                              | Integer          | `cf.bot_management.score le 10`                                                                                                              |
| JA3 Fingerprint\*            | Provides an SSL/TLS fingerprint to help you identify potential bot requests.                                                                                                                                                                                                                                                  | `cf.bot_management.ja3_hash`                           | String           | `cf.bot_management.ja3_hash eq \"e7d705a3286e19ea42f587b344ee6865\"`                                                                         |
| JA4 Fingerprint\*            | Provides a normalized TLS client fingerprint to help identify and correlate requests from the same or similar client implementations. JA4 is a structured string. A value can look like `t13d1516h2_55b375c5d22e_0d5f5b7c`.                                                                                                   | `cf.bot_management.ja4`                                | String           | `cf.bot_management.ja4 eq \"t13d1516h2_55b375c5d22e_0d5f5b7c\"`                                                                              |
| Verified Bot\*               | When `true`, this field indicates the request originated from a known good bot or crawler, the same information as `cf.client.bot`. This field requires Bot Management; use `cf.client.bot` instead, which returns the same result without Bot Management.                                                                    | `cf.bot_management.verified_bot`                       | Boolean          | `cf.bot_management.verified_bot`                                                                                                             |
| Authentication Detected      | Indicates whether Cloudflare detected authentication credentials in the request.                                                                                                                                                                                                                                              | `cf.waf.auth_detected`                                 | Boolean          | `cf.waf.auth_detected`                                                                                                                       |
| Username Leaked              | Indicates whether the username detected in the request was previously leaked.                                                                                                                                                                                                                                                 | `cf.waf.credential_check.username_leaked`              | Boolean          | `cf.waf.credential_check.username_leaked`                                                                                                    |
| Password Leaked              | Indicates whether the password detected in the request was previously leaked.                                                                                                                                                                                                                                                 | `cf.waf.credential_check.password_leaked`              | Boolean          | `cf.waf.credential_check.password_leaked`                                                                                                    |
| Username and Password Leaked | Indicates whether the username-password pair detected in the request was previously leaked.                                                                                                                                                                                                                                   | `cf.waf.credential_check.username_and_password_leaked` | Boolean          | `cf.waf.credential_check.username_and_password_leaked`                                                                                       |
| Similar Credentials Leaked   | Indicates whether a similar version of the username and password credentials detected in the request was previously leaked.                                                                                                                                                                                                   | `cf.waf.credential_check.username_password_similar`    | Boolean          | `cf.waf.credential_check.username_password_similar`                                                                                          |

**note:** Fields marked with an asterisk begin with `cf.bot_management`. To use `cf.bot_management.*` fields, you must implement your own Cloudflare account (o2o) with Bot Management enabled. For verified bot detection, use `cf.client.bot` instead of `cf.bot_management.verified_bot`. Both fields return `true` when a request comes from a known, trusted bot or crawler (such as Googlebot or Bingbot), but `cf.client.bot` doesn't require Bot Management. Use `cf.client.bot` and `cf.verified_bot_category` to allow, challenge, block, or rate limit traffic at the edge, including AI crawlers.

**note:** **Leaked Credentials Detection and the SLAS login API:** Leaked Credentials Detection scans the `Authorization` header for HTTP Basic Authentication credentials. Use the `cf.waf.credential_check.*` fields on SLAS login endpoints (for example, `/shopper/auth/v1/organizations/{organizationId}/oauth2/login`) and on storefront login endpoints (for example, `/Account-Login`).

<!-- document id=627f5eb9e7212eaa2f6113214ebfec0fb84bb3b90236972ea96e5b29396fc218 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-turnstile.md -->

# eCDN Turnstile

Cloudflare Turnstile is a bot-mitigation solution that verifies that visitors are real without requiring them to solve a CAPTCHA. The eCDN Turnstile endpoints let you manage Turnstile widgets for your Commerce Cloud storefronts—creating, listing, updating, and deleting widgets programmatically.

Each widget is identified by a `sitekey` (the public key embedded in your storefront HTML) and has a corresponding `secret` (used server-side to validate challenge responses). The API returns the secret so that you can store it in your application's server-side configuration.

For general eCDN concepts and the zones API, see [CDN Zones](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-zones.md).

## Widget Modes

A widget operates in one of three modes:

| Mode              | Behavior                                                                           |
| ----------------- | ---------------------------------------------------------------------------------- |
| `managed`         | Cloudflare determines the optimal challenge type (recommended for most use cases). |
| `non-interactive` | A non-interactive challenge runs automatically without user action.                |
| `invisible`       | The challenge runs entirely in the background with no visible widget rendered.     |

## Scope

Widgets are scoped to the realm and environment derived from the organization ID. For example, a `GET` request from `f_ecom_bcxj_prd` returns only production widgets for realm `bcxj`.

## Domains

Each widget is associated with one or more domains (hostnames) where it can be presented. Only requests that originate from a listed domain pass validation. Update the domain list as hostnames are added to or removed from your storefront.

## Authorization

All Turnstile endpoints require an OAuth 2.0 bearer token with the `sfcc.cdn-zones.rw` scope.

The Turnstile endpoints are relative to the following base URL:

`https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/{organizationId}`

## List Turnstile Widgets

Retrieves all Turnstile widgets for the requesting instance. Results are paginated and cached for 5 minutes.

`GET /organizations/{organizationId}/turnstile/widgets`

Query parameters:

| Parameter | Required | Default | Description                          |
| --------- | -------- | ------- | ------------------------------------ |
| `name`    | No       | —       | Filter by widget name (exact match). |
| `offset`  | No       | `0`     | Pagination offset.                   |
| `limit`   | No       | `25`    | Results per page (1–50).             |

A `200 OK` response includes the following pagination headers:

- `SFDC-Pagination-Offset`
- `SFDC-Pagination-Limit`
- `SFDC-Pagination-Total-Count`
- `SFDC-Pagination-Result-Count`

Example response body:

```json
{
  "data": [
    {
      "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
      "name": "checkout-widget",
      "mode": "managed",
      "domains": ["shop.example.com", "www.example.com"],
      "bot_fight_mode": false,
      "region": "world",
      "offlabel": false,
      "clearance_level": "interactive",
      "created_on": "2026-01-15T12:00:00Z",
      "modified_on": "2026-02-20T08:30:00Z",
      "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
    }
  ]
}
```

## Create a Turnstile Widget

Creates a new Cloudflare Turnstile widget for the requesting instance. Each instance allows up to 5,000 widgets.

`POST /organizations/{organizationId}/turnstile/widgets`

Required attributes:

| Attribute | Type             | Description                                                     |
| --------- | ---------------- | --------------------------------------------------------------- |
| `name`    | string           | Logical widget name.                                            |
| `domains` | array of strings | Hostnames allowed to present the widget. At least one required. |
| `mode`    | string           | Widget mode: `managed`, `non-interactive`, or `invisible`.      |

Example request body:

```json
{
  "name": "checkout",
  "domains": ["shop.example.com", "www.example.com"],
  "mode": "managed"
}
```

A `201 Created` response returns the new widget, including its `secret`:

```json
{
  "data": {
    "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
    "name": "checkout-widget",
    "mode": "managed",
    "domains": ["shop.example.com", "www.example.com"],
    "bot_fight_mode": false,
    "region": "world",
    "offlabel": false,
    "clearance_level": "interactive",
    "created_on": "2026-01-15T12:00:00Z",
    "modified_on": "2026-01-15T12:00:00Z",
    "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
  }
}
```

**note:** The response includes the `secret`. Store it securely in your server-side configuration—you need it to validate Turnstile challenge responses.

## Get a Turnstile Widget

Retrieves the full configuration of a widget by sitekey, including the shared secret.

`GET /organizations/{organizationId}/turnstile/widgets/{sitekey}`

Path parameters:

| Parameter | Description                          |
| --------- | ------------------------------------ |
| `sitekey` | The unique identifier of the widget. |

A `200 OK` response returns the widget. The endpoint returns `404 Not Found` if the widget doesn't exist.

```json
{
  "data": {
    "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
    "name": "checkout-widget",
    "mode": "managed",
    "domains": ["shop.example.com", "www.example.com"],
    "bot_fight_mode": false,
    "region": "world",
    "offlabel": false,
    "clearance_level": "interactive",
    "created_on": "2026-01-15T12:00:00Z",
    "modified_on": "2026-02-20T08:30:00Z",
    "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
  }
}
```

## Update a Turnstile Widget

Updates the domains and/or mode of an existing widget.

`PUT /organizations/{organizationId}/turnstile/widgets/{sitekey}`

Path parameters:

| Parameter | Description                                    |
| --------- | ---------------------------------------------- |
| `sitekey` | The unique identifier of the widget to update. |

Optional attributes (at least one required):

| Attribute | Type             | Description                                                    |
| --------- | ---------------- | -------------------------------------------------------------- |
| `domains` | array of strings | Replacement list of allowed hostnames.                         |
| `mode`    | string           | New widget mode: `managed`, `non-interactive`, or `invisible`. |

Example request body:

```json
{
  "domains": ["shop.example.com", "www.example.com", "checkout.example.com"],
  "mode": "invisible"
}
```

A `200 OK` response returns the updated widget. The endpoint returns `404 Not Found` if the widget doesn't exist, and `400 Bad Request` if the request exceeds the Cloudflare hostname limit for the widget.

## Delete a Turnstile Widget

Deletes an existing widget. This operation is irreversible and immediately invalidates the sitekey and secret.

`DELETE /organizations/{organizationId}/turnstile/widgets/{sitekey}`

Path parameters:

| Parameter | Description                                    |
| --------- | ---------------------------------------------- |
| `sitekey` | The unique identifier of the widget to delete. |

Query parameters:

| Parameter         | Required | Default | Description                                                                                                            |
| ----------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `forceProduction` | No       | `false` | Must be `true` to delete a production widget. Without this flag, deleting a production widget returns `403 Forbidden`. |
| `dryRun`          | No       | `false` | When `true`, validates the request without performing the deletion.                                                    |

A successful deletion returns `204 No Content`. The endpoint returns `404 Not Found` if the widget doesn't exist, and `403 Forbidden` if you attempt to delete a production widget without `forceProduction=true`.

**note:** Production widgets (environment = `prd`) require an explicit `forceProduction=true`. Use `dryRun=true` to validate parameters before committing to deletion. Post-deletion verification runs automatically to confirm removal.

## Error Responses

All Turnstile endpoints return errors in `application/problem+json` format:

```json
{
  "title": "Short description of the error",
  "type": "ErrorType",
  "detail": "Additional context about what went wrong"
}
```

| Status Code | Meaning                                                                       |
| ----------- | ----------------------------------------------------------------------------- |
| `400`       | Bad request—invalid input, name too long, hostname limit exceeded, and so on. |
| `401`       | Unauthorized—missing or invalid bearer token.                                 |
| `403`       | Forbidden—insufficient scope, or production deletion without the force flag.  |
| `404`       | Not found—a widget with the given sitekey doesn't exist.                      |
| `500`       | Internal server error.                                                        |

## Integration Workflow

A typical workflow:

1. **Create a widget.** Call `POST /turnstile/widgets` with your desired name, domains, and mode.
2. **Configure your storefront.** Add the `sitekey` and `secret` from the response to your Managed Runtime application's `.env` file. For the exact environment variables and configuration, see steps 2(a) and 2(b) in the [Storefront Next One-Click Checkout guide](https://developer.salesforce.com/docs/commerce/storefront-next/guide/sfnext-one-click-checkout.html).
3. **Update domains.** As you add or remove storefront hostnames, call `PUT /turnstile/widgets/{sitekey}` to keep the domain list in sync.

## Limitations and Considerations

- Each instance allows up to 5,000 widgets.
- Each widget's domain list is subject to Cloudflare's per-widget hostname limit.
- List results are cached for 5 minutes, so newly created widgets can take up to 5 minutes to appear in list responses. To retrieve a new widget right away, use `GET /turnstile/widgets/{sitekey}`, which isn't cached.
- You can't change the `name` after creation. To rename a widget, delete and recreate it.
- Each environment (development, staging, production) has its own widgets. Widgets can't be shared across environments.
- If you delete a widget that is still in use, its sitekey and secret are immediately invalidated, and any Turnstile challenges that use that sitekey fail. Remove the widget HTML from your storefront before, or immediately after, deletion.

To choose a mode, use this guidance:

- Use `managed` (recommended) for most storefronts—Cloudflare picks the optimal challenge.
- Use `invisible` for a seamless experience where no widget is shown.
- Use `non-interactive` when you want the challenge to run automatically without a visible puzzle but still show the widget.

<!-- document id=d4038669503aaac87a35bc68e3e1f4714a8bddbf87bccf9e1496ca87fdd6220d url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-wafv2.md -->

# eCDN WAFv2

The Web Application Firewall (WAF) is an important component in mitigating bad actors and protecting your storefront. For details, see [eCDN Web Application Firewall](https://help.salesforce.com/s/articleView?id=cc.b2c_waf_application.htm&type=5).

With WAFv2, override specific managed rules and customize each ruleset to meet your specific traffic needs. WAFv2 rulesets are specifically designed to protect against threats such as zero-day vulnerabilities, top-10 attack techniques, use of stolen/exposed credentials, and extraction of sensitive data, and are regularly updated as new vulnerabilities are discovered to improve performance and reduce false positives.

WAFv2 rulesets include:

- eCDN Managed Ruleset
- OWASP Managed Ruleset
- Exposed Credentials Check Ruleset

Business Manager supports eCDN configuration of WAFv2 settings specific to each instance (Development, Staging, Production), for managing instances individually. When you migrate to, set, or update WAFv2, these changes are not replicated to other instances. This approach simplifies testing and deploying WAFv2 security settings from development and staging to production during transitions.

## eCDN Managed Ruleset

Ruleset ID: `efb7b8c949ac4650a09736fc376e9aee`

Created by the eCDN security team, this ruleset provides fast and effective protection for all of your applications. By default, some rules in the ruleset are disabled or set to `log` by default, to balance providing the right protection with reducing the number of false positives.

Configure the following settings for this ruleset:

- Action:
  - `default`, `block`, `log`, `managed_challenge`, `js_challenge`, `legacy_captcha`
- Enabled:
  - `true`, `false`

## OWASP Managed Ruleset

Ruleset ID: `4814384a9e5d4991b9815dcfc25d2f1f`

The OWASP Managed Ruleset is an implementation of the OWASP ModSecurity Core Rule Set (CRS). This ruleset is routinely monitored for OWASP updates, based on the latest version available from the official code repository. The OWASP Managed Ruleset is designed to work as a single entity to calculate a threat score and execute an action based on that score. Individual rules in the OWASP Managed Ruleset do not have their own default action. The ruleset’s action is what is executed if the calculated threat score exceeds the score threshold.

### Paranoia Level

The paranoia level (PL) classifies OWASP rules according to their aggressiveness. Available paranoia levels include:

- PL1
- PL2
- PL3
- PL4 (most aggressive)

Rules associated with higher paranoia levels are considered more aggressive and provide increased protection. However, they can cause legitimate traffic to get blocked due to false positives. When you configure the paranoia level of the OWASP Managed Ruleset, you are enabling all the rules belonging to all paranoia levels up to the level you select. For example, if you configure the ruleset paranoia level to PL3, you are enabling rules belonging to paranoia levels PL1, PL2, and PL3.

### Threat Score

Each OWASP rule that matches the current request has an associated score. The request threat score is the sum of the individual scores of all OWASP rules that matched the request.

### Anomaly Score Threshold

The anomaly score threshold (or anomaly score) defines the minimum cumulative score, which is obtained from matching OWASP rules, for the WAF to apply the configured OWASP Managed Ruleset action.

Available score thresholds:

- Low: 60 and higher
- Medium: 40 and higher (recommended default value)
- High: 25 and higher

Configure the following settings for this ruleset:

- Action
  - `block`, `log`, `managed_challenge`, `js_challenge`, `legacy_captcha`
- Paranoia Level
  - `1`, `2`, `3`, `4`
- Anomaly Score
  - `low`, `medium`, `high`
- Enabled
  - `true`, `false`

## Exposed Credentials Check Ruleset

Ruleset ID: `c2e184081120413c86c3ab7e14069605`

The Exposed Credentials Check Ruleset contains a set of rules that lookup the username/password pair in the request against a database of publicly available stolen credentials. When a request matches a particular rule’s expression and the exposed credentials check is true, the action configured in the rule is performed.
For details, see [How exposed credentials checks work](https://developers.cloudflare.com/waf/managed-rules/check-for-exposed-credentials/how-checks-work/).

Many web applications have suffered recent attacks in which there is a massive number of login attempts using username/password pairs from databases of exposed credentials. The Exposed Credentials Check Ruleset contains predefined rules for the following CMS applications:

- WordPress
- Joomla
- Drupal
- Ghost
- Plone
- Magento

This managed ruleset also includes generic rules for the following common patterns:

- Check forms submitted using a `POST` request containing `username` and `password` arguments.
- Check credentials sent as JSON with `email` and `password` keys.
- Check credentials sent as JSON with `username` and `password` keys.

By default, the Exposed Credentials Check Ruleset operates by adding an HTTP header to requests that are flagged by the managed rules in the ruleset (shown as having the `rewrite` action). The name of the added HTTP header is `Exposed-Credential-Check` and its value is `1`. Your application can then force a password reset, start a two-factor authentication process, or perform any other action. If you wish to challenge or block requests containing exposed credentials, then update the ruleset’s action. However, it is strongly recommend to test the Exposed Credentials Check Ruleset in log mode before changing to a different ruleset action.

Configure the following settings for this ruleset:

- Action:
  - `default`, `block`, `log`, `managed_challenge`, `js_challenge`, `legacy_captcha`
- Enabled:
  - `true`, `false`

## Configure Managed Rulesets

Configuring a managed ruleset can be done via both Business Manager and CDN-API.

When updating the ruleset’s action, selecting an action other than `default` overrides the action of _all_ managed rules in the ruleset. For example, by default, some rules in the eCDN Managed Ruleset are set to `block` while others are set to `log`. If you update the action of the eCDN Managed Ruleset to `block`, then all rules in the ruleset are set to `block`. If you wish to change the action of a particular managed rule, set an individual rule override.

Similarly, some rules in each managed ruleset are disabled by default. Disabling the entire ruleset will disable all managed rules in the ruleset. However, enabling a ruleset will _not_ enable all rules in the ruleset. Enabling a ruleset maintains each rule’s default status. If you wish to update a rule’s default status, set an individual rule override.

### Configure Managed Rulesets Using Business Manager

1. Navigate to **Embedded CDN Settings**. Locate the zone you want to update and navigate to the **WAF** tab. Verify the zone is using WAFv2.
2. Update the WAFv2 ruleset settings as needed using the checkboxes and drop-down menus.

### Configure Managed Rulesets Using CDN-API

1. Use [getWafManagedRulesets](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getWafManagedRulesets) to retrieve the WAFv2 managed rulesets and their current configurations by providing the zone ID.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-managed/rulesets" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'
```

Sample Success Response (200 HttpStatus Code):

```json
{
    "data": [
        {
            "name": "Managed Ruleset",
            "rulesetId": "efb7b8c949ac4650a09736fc376e9aee",
            "action": "default",
            "enabled": true
        },
        {
            "name": "OWASP Core Ruleset",
            "rulesetId": "4814384a9e5d4991b9815dcfc25d2f1f",
            "action": "log",
            "anomalyScoreThreshold": 25,
            "anomalyScore": "high",
            "paranoiaLevel": 1,
            "enabled": true
        },
        {
            "name": "Leaked Credentials Check Ruleset",
            "rulesetId": "c2e184081120413c86c3ab7e14069605",
            "action": "block",
            "enabled": true
        }
    ]
}
```

2. Use [updateWafManagedRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateWafManagedRuleset) to configure the desired ruleset by providing the zone and ruleset ID. You must provide at least one field in the request body.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-managed/rulesets/$RULESETID" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
   "action": "managed_challenge",
   "anomalyScore": "low"
   "paranoiaLevel": 2
   "enabled": true
}'
```

Sample Success Response (200 HttpStatus Code):

```json
{
    "data": {
        "name": "OWASP Core Ruleset",
        "rulesetId": "4814384a9e5d4991b9815dcfc25d2f1f",
        "action": "managed_challenge",
        "anomalyScore": "low",
        "anomalyScoreThreshold": 60,
        "paranoiaLevel": 2,
        "enabled": true
    }
}
```

## Configure Managed Rule Overrides

Configuring individual managed rule overrides must be done using CDN-API.

If you see false positives due to a particular managed rule, configure overrides to adjust the rule’s action or default enabled status. Individual managed rule overrides let you fine-tune your zone’s WAFv2 configuration beyond the available ruleset-level settings.

1. Use [getWafManagedRulesInRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getWafManagedRulesInRuleset) to view all of the rules in a particular managed ruleset by providing the zone and ruleset ID. The response will show the current configuration of each rule, taking into consideration the ruleset’s current action and enabled status. The response will also display the rule’s associated tags (such as `wordpress`) which are useful when searching for a specific group of rules.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-managed/rulesets/$RULESETID/rules" \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json'
```

Sample Success Response (200 HttpStatus Code):

```json
{
    "data": [
        {
            "ruleId": "5de7edfa648c4d6891dc3e7f84534ffa",
            "action": "block",
            "categories": [
                "cve-2014-5265",
                "cve-2014-5266",
                "cve-2014-5267",
                "dos",
                "drupal",
                "wordpress"
            ],
            "description": "Drupal, Wordpress - DoS - XMLRPC - CVE:CVE-2014-5265, CVE:CVE-2014-5266, CVE:CVE-2014-5267",
            "lastUpdated": "2024-07-17T21:05:18.777823Z",
            "enabled": false
        },
        {
            "ruleId": "e3a567afc347477d9702d9047e97d760",
            "action": "block",
            "categories": [
                "cve-2020-12720",
                "sqli",
                "vbulletin",
                "beta"
            ],
            "description": "vBulletin - SQLi - CVE:CVE-2020-12720 - beta",
            "lastUpdated": "2024-07-17T21:05:18.777823Z",
            "enabled": false
        },
        ...
    ]
}
```

2. Use [updateWafManagedRuleInRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateWafManagedRuleInRuleset) to configure a rule override by providing the zone, ruleset, and rule ID. You must provide at least one field in the request body.

Configure the following settings when updating a managed rule:

- Action:
  - `default`, `block`, `log`, `managed_challenge`, `js_challenge`, `legacy_captcha`
  - The `default` action will reset any existing action overrides and set the rule back to its default action.
  - The action field is only applicable for the eCDN Managed Ruleset and Exposed Credentials Check Ruleset. Setting an action override is not applicable for the OWASP Managed Ruleset because it operates by calculating a total threat score and then applying the overall ruleset’s action.
- Enabled:
  - `true`, `false`

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/firewall-managed/rulesets/$RULESETID/rules/$RULEID" \
--request 'PATCH' \
--header "Authorization: Bearer $TOKEN" \
--header 'Content-Type: application/json' \
--data '{
   "action": "log",
   "enabled": false
}'
```

Sample Success Response (200 HttpStatus Code):

```json
{
    "data": {
        "ruleId": "5de7edfa648c4d6891dc3e7f84534ffa",
        "action": "log",
        "categories": [
            "cve-2014-5265",
            "cve-2014-5266",
            "cve-2014-5267",
            "dos",
            "drupal",
            "wordpress"
        ],
        "description": "Drupal, Wordpress - DoS - XMLRPC - CVE:CVE-2014-5265, CVE:CVE-2014-5266, CVE:CVE-2014-5267",
        "lastUpdated": "2024-07-17T21:05:18.777823Z",
        "enabled": false
    }
}
```

### Best Practices for WAFv2 Migration

WAFv2 rules do not have a one-to-one mapping to WAF rules, and existing WAFv1 rule customizations might not be necessary or applicable.

Reevaluate the security settings in `log` mode as described in [Using WAF for the First Time](https://help.salesforce.com/s/articleView?id=cc.b2c_waf_using_waf_first_time.htm&language=en_US&type=5). Review WAF logs using any of the following methods:

- [Request eCDN-WAF Logs with an OCAPI Call](https://help.salesforce.com/s/articleView?id=cc.b2c_waf_log_ocapi_call.htm&language=en_US&type=5)
- [Request WAF Logs Using the Business Manager UI](https://help.salesforce.com/s/articleView?id=cc.b2c_waf_configuring_how.htm&language=en_us&release=2.0.1&type=5)
- [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html) firewall events with the `logType` set to `firewall_events`.

For the OWASP Managed Ruleset, we recommend the following WAFv2 settings based on your previous OWASP WAFv1 sensitivity setting:

1. OWASP WAFv1 Sensitivity High → Paranoia level: PL2; Anomaly score: Medium (40 and higher)
2. OWASP WAFv1 Sensitivity Medium → Paranoia level: PL1; Anomaly score: High (25 and higher)
3. OWASP WAFv1 Sensitivity Low → Paranoia level: PL1; Anomaly score: Medium (40 and higher)

**note:** WAFv2 default sensitivity settings → Paranoia level: PL2; Anomaly score: Medium (40 and higher)

## False Positives

- For immediate impact relief, set the ruleset to `log`.
- For visibility into WAFv2 firewall events, set up [eCDN Logpush](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html) with the `logType` set to `firewall_events`. You can view logs of firewall events in your zone and get insights into which ruleset and rule(s) are causing the false positives. After you idenitfy the problematic managed rule, use the [updateWafManagedRuleInRuleset](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateWafManagedRuleInRuleset) CDN-API endpoint to override the rule’s action or disable the rule completely.
- If you are seeing false positives originating from the OWASP Managed Ruleset, adjust the ruleset’s paranoia level and score threshold.
- You can create a custom rule with the `skip_wafv2` action to have particular requests skip WAFv2 completely. Any traffic matching the rule expression is not evaluated by WAFv2.

<!-- document id=a4542cd8ff1d7dc2323798281dabbb0b9b7452a90d7beb2c3bf2199a53bb44fe url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_edit_ods_scheduler.md -->

# Edit an ODS Operation Scheduler

Edit an ODS operation scheduler in response to changes in your business needs.

**note:** To edit an ODS operation scheduler, you need the `Sandbox_API_User` role with a tenant filter in the format `<realmid>_sbx` in Account Manager.

1. In Control Center, select the realm you want to modify.
2. Select **On-Demand Sandboxes**.
3. For the scheduler you want to modify, click **Edit**.
4. Modify the scheduler settings, click **Edit.**, and confirm the change.

<!-- document id=2312ab665ceba8ccc49282bdd19913be4468202662b3c070fe9b7c7ac538eed7 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-reason-codes.md -->

# Edit Reason Codes

Add or edit user-defined reason codes in Business Manager to track line item, order-level, or shipping price adjustments. The agent must have the necessary permissions.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **System Object Types**.

2.  On the System Object Type List page, select **PriceAdjustment**.

3.  On the General tab, click the **Attribute Definitions** tab.

4.  On the Attribute Definitions tab, click the **[attribute name]** or the **Edit** button to edit the attribute.

5.  On the Attribute Definition Details page, edit the attributes and click **Apply** to save your changes.

    - Default reason code values are provided.

6.  Manually configure the location of the reason codes field from the Customer Service Center settings.

<!-- document id=0c1412f23e8276544b1611cc2c64ddea4d23d0a104705834a19ea50f786383eb url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-activities/einstein-activities-overview.md -->

# Einstein Activities

Send Einstein-related site activities to enhance the customer experience.

---

The Einstein Activities API provides access to activities that you can use to track site interactions, and send them to the Einstein engine to enhance user experiences or provide reporting data.

The primary purpose of the Einstein Activities API is to send activities to Einstein. Using this API does not require using the Einstein Recommendations API. Some activities are automatically used with Salesforce Storefront Reference Architecture (SFRA) storefronts, like those for sending and receiving Einstein Recommendations. However, even when you aren't using the micro-services associated with SFRA, like when using Progressive Web App (PWA) storefronts, you can send activities to the Einstein engine for processing.

## Enable Access

To enable access to any Einstein API endpoints, go to [Einstein Configurator](https://configurator.cquotient.com), and input your Account Manager client ID in the API page. Using Site Administrator access, you can [add an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5) on the Account Manager page.

When enabled, and as long as the correct site ID and client ID are passed, the API functions in all environments, including production, staging, development, and sandbox instances.

## Authentication

Each API call must pass the `x-cq-client-id` header for API key authentication.

Implementing our API on the client or server side comes with tradeoffs, and both approaches are valid. For more security, we recommend a server-side implementation to protect your client ID. A client-side implementation runs the risk of exposing the client ID to bad actors. For example, this exposure can affect the quality or accuracy of outputs such as product recommendations and analytics.

## Business Manager Configuration

**warning:** [Reports & Dashboards](https://developer.salesforce.com/docs/pwa-kit-managed-runtime/guides/reports-and-dashboards.md) can use data from Einstein Activites or web adapter logs, but not both. If you're considering a phased headless rollout, where some site elements are powered by a headless front end and others are powered by SFRA or Sitegensis, you must [update your SFRA storefront to use the Einstein Activities API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/einstein-activities-for-phased-headless-rollouts.html).

**important:** Before you can use Einstein Activities for analytics, you must contact Support and ask them to enable the feature in Business Manager.

To configure a B2C Commerce instance to use Einstein Activities for analytics:

1. Log in to Business Manager.
2. Go to **Administration** > **Operations**
3. Click **Active Merchandising Analytics Configuration**.
4. Choose the site that you want to configure.
5. For Source for Activities, select **Einstein Activities** (must be enabled by Support).
6. Apply the change.

**important:** There can only be 1 active source for the _Source for Activities_: either the Web Adapter Log or the Einstein Activities. This configuration is site-specific (for example, RefArch, RefArchGlobal). Whichever it's set to, that's where [Reports &amp; Dashboards](https://developer.salesforce.com/docs/pwa-kit-managed-runtime/guides/reports-and-dashboards.md) will look for the data.

## Scalability

Our service is globally distributed, horizontally scalable, and can automatically scale up and down based on traffic so load testing is unnecessary. We recommend that you avoid any load testing because it affects recommendation results.

## Reporting

Einstein doesn’t provide separate reporting for activity data. View standard reporting in the [Einstein Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_dashboard.htm&type=5).

<!-- document id=73ed3e6636e91dbb82ba48722b32c5c2ea1a9f5755473d21573b5589a752a424 url=/developer/current/en-us/commerce-cloud/einstein/references/generated-api-specs/einstein-activities.md -->

Einstein Activities

# Einstein Activities

Use the Einstein engine to track shopper activity.

**Version:** v3

## Servers

*   `https://api.cquotient.com/v3`

Protocols: HTTPS.

## /activities (Activities)

## Operations

### POST sendViewReco

`POST /activities/{siteId}/viewReco`

Display name: viewReco.

Tells the Einstein engine when a user views a set of recommendations.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `recommenderName` (_string_, required) The name of the recommender used in the recommendation request.
*   `__recoUUID` (_string_, required) The UUID that was returned in the recommendation response.
*   `products` (_array of ProductForView_, required) The product recommendations that the user viewed.
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendClickReco

`POST /activities/{siteId}/clickReco`

Display name: clickReco.

Tells the Einstein engine when a user clicks a recommendation.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `recommenderName` (_string_, required) The name of the recommender used in the recommendation request.
*   `__recoUUID` (_string_, required) The UUID that was returned in the recommendation response.
*   `product` (_ProductForView_, required)
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendViewProduct

`POST /activities/{siteId}/viewProduct`

Display name: viewProduct.

Tells the Einstein engine when a user opens a product page.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `product` (_ProductForView_, required)
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendAddToCart

`POST /activities/{siteId}/addToCart`

Display name: addToCart.

Tells the Einstein engine when a user adds an item to their cart.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `products` (_array of object_, required) The products that the user has added to their cart.
    *   `id` (_string_, required) A unique identifier for the given product.
    *   `sku` (_string_, required) A unique identifier for a sellable unit of the given product, when applicable.
    *   `price` (_number_, required) The discounted or negotiated price of each individual unit of the product.
    *   `originalPrice` (_number_, required) The price of each individual unit of the product.
    *   `quantity` (_integer_, required) The total number of items in the cart for the product.
*   `source` (_SourceParam_) The page or site location where the Add to Cart button was clicked. Accepted values are `pdp`, `plp`, `recs`, `quick add` and `wishlist`.
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendViewSearch

`POST /activities/{siteId}/viewSearch`

Display name: viewSearch.

Tells the Einstein engine when a user is looking at the results of their search.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `locale` (path, string) A descriptor that combines language and country codes. If using [Einstein Search Recommendations](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_search_recommendations.htm), the locale must match a locale defined in Business Manager. The locale typically follows ISO standards, such as ISO 639 for the language and ISO 3166 for the country. The locale can also just refer to a language code as a default if there is no specific match for a country.
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `searchText` (_string_, required) The text that the user searched for.
*   `products` (_array of ProductForView_, required) The products that the user is viewing on a search results page.
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.
*   `correlationId` (_CorrelationIDParam_) Identifies the search request. Ensure that the ID matches in viewSearch and clickSearch. Must be unique. Generating a UUID is recommended.
*   `sortingRule` (_SortingRuleData_)
*   `itemRange` (_ItemRangeData_) Represents pagination. Use the `start` property for the rank of the first product that is displayed.
*   `locale` (_string_) A descriptor that combines language and country codes. If using [Einstein Search Recommendations](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_search_recommendations.htm), the locale must match a locale defined in Business Manager. The locale typically follows ISO standards, such as ISO 639 for the language and ISO 3166 for the country. The locale can also just refer to a language code as a default if there is no specific match for a country.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendClickSearch

`POST /activities/{siteId}/clickSearch`

Display name: clickSearch.

Tells the Einstein engine when a user clicks a search result.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `searchText` (_string_, required) The text that the user searched for.
*   `product` (_ProductForView_, required)
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.
*   `correlationId` (_CorrelationIDParam_) Identifies the search request. Ensure that the ID matches in viewSearch and clickSearch. Must be unique. Generating a UUID is recommended.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendViewPage

`POST /activities/{siteId}/viewPage`

Display name: viewPage.

Tells the Einstein engine when a user views a page that doesn't fit another activity.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendViewCategory

`POST /activities/{siteId}/viewCategory`

Display name: viewCategory.

Tells the Einstein engine when a user is looking at a category listing page.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `category` (_CategoryParam_, required) A grouping of products within the catalog.
*   `products` (_array of ProductForView_, required) The products that the user is viewing on a category listing page.
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.
*   `correlationId` (_CorrelationIDCategoryParam_) Identifies the category of a search request. Ensure that the ID matches in viewSearch and clickSearch. Must be unique. Generating a UUID is recommended.
*   `sortingRule` (_SortingRuleData_)
*   `itemRange` (_ItemRangeData_) Represents pagination. Use the `start` property for the rank of the first product that is displayed.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendClickCategory

`POST /activities/{siteId}/clickCategory`

Display name: clickCategory.

Tells the Einstein engine when a user clicks a product from the category listing page and not when the user clicks a category from the navigation bar.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `ClickCategoryActivityData (extended)`.

Includes all fields of `ClickCategoryActivityData`.

*   `category` (_CategoryParam_, required) A grouping of products within the catalog.
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.
*   `correlationId` (_CorrelationIDCategoryParam_) Identifies the category of a search request. Ensure that the ID matches in viewSearch and clickSearch. Must be unique. Generating a UUID is recommended.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendBeginCheckout

`POST /activities/{siteId}/beginCheckout`

Display name: beginCheckout.

Tells the Einstein engine when a user starts a checkout process but hasn't completed it yet.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `products` (_array of ProductForCheckout_, required) The products whose purchase has been initiated.
*   `amount` (_AmountParam_, required) The total checkout amount of the purchase, including taxes and discounts.
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendCheckoutStep

`POST /activities/{siteId}/checkoutStep`

Display name: checkoutStep.

Tells the Einstein engine when a user performs one of the site's checkout steps.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `stepName` (_string_, required) The name of the step being performed by the user within the checkout process. For example, `Billing`, `OrderSummary`, `ShippingMethod`.
*   `stepNumber` (_string_, required) The number of the step being performed by the user within the checkout process. For example, `2`, `3`, `6`.
*   `basketId` (_string_, required) The basket ID of the user's current basket.
*   `userId` (_UserIdParam_) A unique identifier for logged-in users (hashed) that is provided by the application.
*   `cookieId` (_CookieIdParam_, required) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.
*   `realm` (_RealmParam_) A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

## Schemas

### EinsteinSiteIdParam

The Einstein site ID. Locate this ID in the upper-right corner of the [Einstein Configurator](https://configurator.cquotient.com). The ID has the format `xxxx-<Commerce Cloud Site ID>`.

Type: `string`.

### ClientIdParam

Make sure to pass the `x-cq-client-id` header with your API Client ID from Account Manager. Locate this value in Business Manager under **Administration** > **Site Development** > **Open Commerce API Settings**. This settings page displays a JSON object containing the current OCAPI configuration. You can use any of the values in a `client_id` field, but it's better to create one specifically for Einstein API calls.

Type: `string`.

### ProductForView

*   `id` (_string_, required) A unique identifier for the given product.
*   `sku` (_string_) A unique identifier for a sellable unit of the given product, when applicable.
*   `altId` (_string_) An alternate identifier for the given product. You must specify a type in the `altIdType` field.
*   `altIdType` (_string_) The type of alternate identifier.  
    Allowed values: `vgroup`.

### UserIdParam

A unique identifier for logged-in users (hashed) that is provided by the application.

Type: `string`.

### CookieIdParam

The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**

Type: `string`.

### ClientIpParam

The IP address of the end user. Use this parameter if you're sending activities on the server side for a client application.

Type: `string`.

### ClientUserAgentParam

The User Agent of the end user. Use this paramenter if you're sending activities on the server side for a client application.

Type: `string`.

### RealmParam

A unique, four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein site ID. If your site changes realms, the Einstein site ID won’t use the correct realm.

Type: `string`.

### ActivityResponse

*   `uuid` (_string_, required) The unique identifier for the end user. If you don't already have identifiers associated with a user, you can use this value in subsequent requests.  
    Example: `ce035cc0-2cbb-4d9e-95ed-c67fa55d1eb8`.

### ValidationError

*   `code` (_string_, required) A short error code to classify types of errors.  
    Example: `ValidationError`.
*   `errors` (_array of object_, required) A set of invalid parameters.
    *   `location` (_string_, required) The location of the invalid parameter.  
        Example: `body`.
    *   `msg` (_string_, required) A message describing why the parameter is invalid.  
        Example: ``Must provide a `products` array.``.
    *   `param` (_string_, required) The name of the invalid parameter.  
        Example: `products`.
*   `msg` (_string_, required) A descriptive message about the error that you can use to troubleshoot.  
    Example: ``There was a problem validating the request. See `errors`.``.

### SourceParam

The page or site location where the Add to Cart button was clicked. Accepted values are `pdp`, `plp`, `recs`, `quick add` and `wishlist`.

Type: `string`.

### CorrelationIDParam

Identifies the search request. Ensure that the ID matches in viewSearch and clickSearch. Must be unique. Generating a UUID is recommended.

Type: `string`.

### SortingRuleData

Array of `object`.

*   `attribute` (_string_, required)
*   `direction` (_string_, required)

_Example_

```
-
  attribute: price
  direction: ascending
```

### ItemRangeData

Represents pagination. Use the `start` property for the rank of the first product that is displayed.

*   `start` (_number_, required)

_Example_

```
start: 17
```

### CategoryParam

A grouping of products within the catalog.

*   `id` (_string_, required) A unique identifier for the given category.

### CorrelationIDCategoryParam

Identifies the category of a search request. Ensure that the ID matches in viewSearch and clickSearch. Must be unique. Generating a UUID is recommended.

Type: `string`.

### ClickCategoryActivityData

*   `category` (_object_, required)
    
    Includes all fields of `CategoryParam`.
    
*   `product` (_object_, required) The product on the category page that the user clicked.
    
    Includes all fields of `ProductForView`.
    
*   `userId` (_UserIdParam (string)_)
*   `cookieId` (_CookieIdParam (string)_)
*   `clientIp` (_ClientIpParam (string)_)
*   `clientUserAgent` (_ClientUserAgentParam (string)_)
*   `realm` (_RealmParam (string)_)
*   `correlationId` (_CorrelationIDCategoryParam (string)_)

### ProductForCheckout

*   `id` (_string_, required) A unique identifier for the given product.
*   `sku` (_string_, required) A unique identifier for a sellable unit of the given product, when applicable.
*   `price` (_number_, required) The price of each individual unit of the product.
*   `quantity` (_integer_, required) The total number of items purchased for the product.

### AmountParam

The total checkout amount of the purchase, including taxes and discounts.

Type: `number`.

<!-- document id=31c69cb941edf1fac7e864f9d84e7e360d5c32b1c2aaf207d3f1c468563ad31a url=/developer/current/en-us/commerce-cloud/commerce-api/guides/einstein-activities-for-phased-headless-rollouts.md -->

# Einstein Activities for Hybrid Implementations

With [Reports & Dashboards](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/reports-and-dashboards.md), identify trends over time and make smarter business decisions based on your B2C Commerce data.

Reports & Dashboards analytics can only be derived from either web adapter logs or the Einstein Activities API. By default, SFRA and SiteGenesis analytics data are stored in web adapter logs, while the PWA Kit sends analytics data to Einstein Activities API.

If you are pursuing a [Hybrid Implementation Guidance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-storefront-baskets.md), where some pages are powered by PWA Kit and others are powered by SFRA or SiteGenesis, and you want to use Reports & Dashboards across your entire site, you must update your SFRA or SiteGenesis implementation to use the Einstein Activities API. This ensures that the API captures the full shopper experience, regardless of whether the shopper is in PWA Kit, SFRA, or SiteGenesis.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


This guide shows you **how to integrate the Einstein Activities API with SFRA's checkout**, so that it sends the same activities as [PWA Kit's checkout](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/180cf0b11f9b34e4d504aee3cb3c9d178797d57d/packages/template-retail-react-app/app/pages/checkout/util/checkout-context.js#L60-L72).

If your phased rollout has additional pages on SFRA or SiteGenesis that send analytics data to the web adapter logs, then for those pages follow a process similar to what's described in this guide. Look at the corresponding pages in the [Retail React App](https://pwa-kit.mobify-storefront.com/) and observe which activities they send out. You'll then need to send the same activities on your SFRA or SiteGenesis pages. As a resource, this [overview of Einstein activities](https://developer.salesforce.com/docs/commerce/einstein/guides/einstein-activities/usage.md) shows you where those activities are supposed to be used.

**note:** Implementations using SiteGenesis with Composable Storefront aren't officially supported.

## About the Code Examples

Use caution when integrating the code examples provided, and always test your code thoroughly before pushing it to production.

Lines to be added to existing code are marked with the addition (`+`) symbol and lines to be deleted are marked with the subtraction (`-`) symbol.

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

## Step 1\: Update Checkout Controller

Start by updating your checkout controller to include the current basket ID.

```diff
  res.render('checkout/checkout', {
+   basketId: currentBasket.UUID,
    order: orderModel,
    customer: accountModel,
    ...
});
```

## Step 2\: Update Checkout Template

Update the ISML template used for checkout. This change makes the basket ID, items, and total available to the browser.

```diff
-    <div id="checkout-main" class="container data-checkout-stage <isif condition="${pdict.order.usingMultiShipping && pdict.order.shipping.length > 1}">multi-ship</isif>" data-customer-type="${pdict.customer.registeredUser ? 'registered' : 'guest'}" data-checkout-stage="${pdict.currentStage}" data-checkout-get-url="${URLUtils.https('CheckoutServices-Get')}">
+    <div id="checkout-main" class="container data-checkout-stage <isif condition="${pdict.order.usingMultiShipping && pdict.order.shipping.length > 1}">multi-ship</isif>" data-customer-type="${pdict.customer.registeredUser ? 'registered' : 'guest'}" data-checkout-stage="${pdict.currentStage}" data-checkout-get-url="${URLUtils.https('CheckoutServices-Get')}" data-checkout-price-total="${pdict.order.priceTotal}" data-checkout-items="${JSON.stringify(pdict.order.items)}" data-basket-id="${pdict.basketId}">
```

## Step 3\: Create Helpers

Create a JavaScript file called `js/einsteinHelpers.js` that contains helper functions:

**important:** Don’t forget to replace the placeholders `$YOUR_SITE_ID` and `$YOUR_CLIENT_ID` with actual values.

```javascript
"use strict";

/**
 * Get the value of a cookie
 * Source: https://gist.github.com/wpsmith/6cf23551dd140fb72ae7
 * @param  {string} name  The name of the cookie
 * @return {string | undefined}       The cookie value
 */
function getCookie(name) {
  var value = "; " + document.cookie;
  var parts = value.split("; " + name + "=");
  var result;

  if (parts.length === 2) {
    result = parts.pop().split(";").shift();
  }
  return result;
}

/**
 * Fire a given Einstein activity with the provided data.
 *
 * @param {string} name - The name of the activity.
 * @param {Object} data - The activity payload.
 */
function fireEinsteinActivity(name, data) {
  // NOTE: These should be placed in the custom preferences of BM. This will help
  // avoid any code deployments if you need to change these values.
  // NOTE 2: this is _Einstein_ site id (not the same as SFRA one like RefArch).
  var SITE_ID = "$YOUR_SITE_ID";
  var CLIENT_ID = "$YOUR_CLIENT_ID";
  // Reports & Dashboards will only show data that's been tagged as `prd` (production)
  var INSTANCE_TYPE = "prd";

  // Assign the realm to the data.
  var activityData = Object.assign(data, {
    realm: SITE_ID.split("-")[0],
    instanceType: INSTANCE_TYPE,
  });

  var userId = data.userId;
  var cookieId = data.cookieId;

  // Apply payload information for logged in users.
  if (userId) {
    activityData = Object.assign(activityData, {
      userId: userId,
    });
  }

  if (cookieId) {
    activityData = Object.assign(activityData, {
      cookieId: cookieId,
    });
  }

  var url = "https://api.cquotient.com/v3/activities" + "/" + SITE_ID + "/" + name;

  try {
    fetch(url, {
      headers: {
        "Content-Type": "application/json",
        "x-cq-client-id": CLIENT_ID,
      },
      method: "POST",
      body: JSON.stringify(activityData),
    });
  } catch (e) {
    console.error(e);
  }
}

var exports = {
  fireEinsteinActivity: fireEinsteinActivity,
  getCookie: getCookie,
};

module.exports = exports;
```

## Step 4\: Record Activities

Update your `checkout.js` script to record activities. You must add this call to `require()` at the top of your checkout script, and it must appear after any existing imports.

```javascript
var einsteinHelpers = require('../einsteinHelpers');
```

Trigger the `checkoutStep` activity when the checkout stage is changed. Append the following code to the `updateUrl` method:

```javascript
/**
 * @returns {boolean} whether the current customer is registered or not
 */
function isRegisteredCustomer() {
  return $(".data-checkout-stage").data("customer-type") === "registered";
}

/**
 * Get the cookieId, which is a unique identifier used for linking subsequent activities to the same user.
 * If the cookieId is not defined, then Reports & Dashboards will treat the activity as coming from an anonymous user.
 * @returns {string | undefined} value of the cookieId param for Einstein Activities API
 */
function getCookieId() {
  var siteId = window.CQuotient && window.CQuotient.siteId;
  // This usid cookie is set by either PWA or plugin_slas
  return (
    einsteinHelpers.getCookie("usid_" + siteId) || einsteinHelpers.getCookie("usid") || undefined
  );
}

/**
 * Get the userId, which is for linking registered users across different devices.
 * @returns {string | undefined} value of the userId param for Einstein Activities API
 */
function getUserId() {
  var siteId = window.CQuotient && window.CQuotient.siteId;
  // This enc_user_id is set by PWA
  return (
    window.localStorage.getItem("enc_user_id_" + siteId) ||
    window.localStorage.getItem("enc_user_id") ||
    undefined
  );
}

/**
 * Updates the URL to determine stage
 * @param {number} currentStage - The current stage the user is currently on in the checkout
 */
function updateUrl(currentStage) {
  // ...

  var cookieId = getCookieId();
  var userId = isRegisteredCustomer() ? getUserId() : undefined;

  einsteinHelpers.fireEinsteinActivity("checkoutStep", {
    basketId: $("#checkout-main").data("basket-id"),
    stepName: checkoutStages[currentStage],
    stepNumber: currentStage,
    cookieId: cookieId,
    userId: userId,
  });
}
```

**note:** Triggering the `checkoutStep` activity in the `updateUrl` method ensures that any transition from one checkout stage to the next (or previous) is tracked.

Trigger the `beginCheckout` activity at the end of the `initialize` function for your checkout code:

```javascript
//
// Send Einstein `beginCheckout` activity
//
// Parse total amount value
var amount = $("#checkout-main").data("checkout-price-total");
amount = Number(amount.replace(/[^0-9.-]+/g, ""));

var products = $("#checkout-main")
  .data("checkout-items")
  .items.map(function (item) {
    return {
      id: item.id,
      price: Number(item.priceTotal.price.replace(/[^0-9.-]+/g, "")),
      quantity: item.quantity,
    };
  });

var cookieId = getCookieId();
var userId = isRegisteredCustomer() ? getUserId() : undefined;

einsteinHelpers.fireEinsteinActivity("beginCheckout", {
  products: products,
  amount: amount,
  cookieId: cookieId,
  userId: userId,
});
```

**note:** The `beginCheckout` activity is only triggered one time per page load during checkout. Activity data preparation is handled automatically.

That’s it! You’ve successfully integrated Einstein Activities with SFRA's checkout. To finish your setup of Reports &amp; Dashboards, complete the steps in [Reports &amp; Dashboards](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/reports-and-dashboards.md).

## See Also

- [Hybrid Implementation Guidance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-storefront-baskets.md)
- [Data and Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/data-and-analytics.md)
- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/pwa-developer-workflow.md)

<!-- document id=f560f84286132239ce4cc938e95f050b8ccc731a886fabbd939a9d231bd659fa url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-activities/usage.md -->

# Einstein Activity Usage

Commerce Einstein uses session storage objects to store and track browser activities. With this information, Einstein can tailor customer experiences. Where and how to use activities depends on what information you want to send to Einstein.

Where you place API activities is important. The `viewReco`, `clickReco`, `viewProduct`, and `addToCart` activities are required for use with the [Einstein Recommendations API](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-recommendations-overview.html). However, implement activities independently on pages where you want to gather specific browser interactions. For example, using the viewSearch and clickSearch activities can enhance Discovery Search configurations, whereas category or checkout activities can send information about customer site interactions.

All of these activities are implemented in the PWA Kit template. If you have already implemented Einstein Recommendations activities, make sure to add other API callouts manually to take advantage of their capabilities. Hybrid setups, where you are using a combined SFRA and PWA Kit implementation, can require that you invoke the APIs in a different way. Contact Support for details.

Use the [Commerce Cloud Recommendation Validator](https://chrome.google.com/webstore/detail/commerce-cloud-recommenda/dobmbolmcejainkefklnpkjbaibgjihn?hl=en-US) to see when activities are sent from an existing site.


| Activity      | Usage                                                                                                                     | Placement                                                                                                                                                                                                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| viewReco      | Indicates when a customer views a served recommendation.                                                                  | Pages where a customer views any served recommendations.                                                                                                                                                                                                                                           |
| clickReco     | Indicates when a customer clicks the link for a served recommendation.                                                    | Pages where a customer can click the link for a served recommendation.                                                                                                                                                                                                                             |
| viewProduct   | Indicates when a customer opens a product page.                                                                           | Product-related pages.                                                                                                                                                                                                                                                                             |
| addToCart     | Indicates when a customer adds a product to their cart.                                                                   | Any checkout pages where customers add products to a cart or basket.                                                                                                                                                                                                                               |
| viewSearch    | Indicates when a customer is looking at the results of their search.                                                      | Pages where a customer views search results.                                                                                                                                                                                                                                                       |
| clickSearch   | Indicates when a customer clicks a result from their search.                                                              | Pages where a customer can click to select links from search results.                                                                                                                                                                                                                              |
| viewPage      | Indicates when a customer is viewing a page.                                                                              | Any page where you want to gather data about when a customer views the page. When a page includes any other activity, it automatically indicates when the page is viewed, making this activity unnecessary.                                                                                        |
| viewCategory  | Indicates when a customer is looking at a category listing page.                                                          | Any category listing pages.                                                                                                                                                                                                                                                                        |
| clickCategory | Indicates when a customer clicks an item from the category listing page.                                                  | Category listing pages where a customer can select items.                                                                                                                                                                                                                                          |
| beginCheckout | Indicates when a customer starts a checkout process.                                                                      | Pages where a customer can start a checkout process. For example, customers can start a checkout process by adding an item from a product page to their cart, from any page where they click to access the cart page directly, or only from cart page when they begin to provide checkout details. |
| checkoutStep  | Indicates when a customer performs one of the site’s checkout steps, as defined for customers using the headless PWA kit. | Any pages, after the page where the checkout process begins, that are part of a defined checkout process.                                                                                                                                                                                          |

<!-- document id=a48df4f67394484d0ebd0fcbdf5e1a897c55995692ffd1d90dec33855d1f397d url=/developer/current/en-us/commerce-cloud/einstein/references/generated-api-specs/einstein-gdpr.md -->

Einstein GDPR

# Einstein GDPR

The Einstein GDPR Delete API enables you to delete buyer and shopper data from the Einstein data engine.

**Version:** v3

## Servers

*   `https://api.cquotient.com/v3`

Protocols: HTTPS.

## Security

*   `AMAuth` (OAuth 2.0)
    
    If you're bulk uploading files or using GDPR Delete APIs, you must pass an OAuth2 `Authorization` header with an Account Manager access token. To get that token, make the following request:
    
    ```
    curl -X POST \
      https://account.demandware.com/dw/oauth2/access_token \
      -H 'Authorization: Basic <INSERT BASIC AUTH HERE>' \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials'
    ```
    
    For the Basic Authorization header, use base64 encoded `<Client ID>:<Password>`
    
    *   Header Authorization: \`JWT <AM access token>\`

## Operations

### POST sendGDPRDelete

`POST /privacy/{siteId}/delete`

Display name: GDPR Delete. Security: AMAuth.

Alerts Einstein when a GDPR delete request is made by the customer or merchant.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `objects` (_object_, required) The request body supports two parameters - idType and idValue which must be encapsulated by objects key.
    *   `idType` (_string_, required)
        
        Indicates the type of ID to identify shopper data. The idType can be a - emailId, userId and cookieId.
        
        emailId - Email address of the buyer or shopper.
        
        userId - Unique identifier of a logged-in shopper (for example, a login\_id, username, or userId value specific to the Einstein API).
        
        cookieId - Unique identifier of an anonymous shopper. Typically, the cookieId is the value of a first-party cookie. (See [User Identifier Parameters](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-recommendations-overview.html#user-identifier-parameters) for more information).
        
    *   `idValue` (_string_, required) The ID value for the given idType.

#### Responses

*   **202** A successful response contains delete Id and delete status link.
    
    Media type: `application/json`. Schema: `GDPRDeleteResponse`.
    
*   **400** A validation error response contains a description of the problem.
*   **403** Either the provided client ID or authorization token was invalid.

### POST getGDPRDeleteStatus

`POST /privacy/{siteId}/delete/{deleteId}/status`

Display name: GDPR Delete Status. Security: AMAuth.

Gets the status of the delete request.

#### Parameters

*   `deleteId` (path, string, required)
*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Responses

*   **200** A successful response shows the status - PENDING or COMPLETE.
    
    Media type: `application/json`. Schema: `GDPRDeleteStatusResponse`.
    
*   **400** An invalid request ID.
*   **403** Either the provided client ID or authorization token was invalid.

## Schemas

### EinsteinSiteIdParam

The Einstein Site ID. Locate this ID in the upper-right corner of the [Einstein Configurator](https://configurator.cquotient.com). The ID has the format `xxxx-<Commerce Cloud Site ID>`.

Type: `string`.

### ClientIdParam

Make sure to pass the `x-cq-client-id` header with your Commerce Cloud Account Manager API Client ID. Locate this value in Business Manager, under Administration > Site Development > Open Commerce API Settings. This settings page displays a JSON object containing the current OCAPI configuration. You can use any of the values in a `client_id` field, but ideally you should create one specifically for Einstein API calls.

Type: `string`.

### GDPRDeleteResponse

*   `deleteId` (_string_, required) The ID of the queued delete request.
*   `deleteStatusLink` (_string_, required) The link to use to check the status of the delete request.

### GDPRDeleteStatusResponse

*   `status` (_string_, required) The status of the delete request.

<!-- document id=e91dfea81f49ccb0ff539bf1b92eabd774ec977f10c0a42997cd6dfbff6fabbe url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-gdpr-delete/einstein-gdpr-delete.md -->

# Einstein GDPR Delete

In compliance with General Data Protection Regulation (GDPR) laws, the Einstein GDPR Delete API enables you to delete buyer and shopper data from the Einstein data engine.

Affected data includes any legacy order data uploaded to the Einstein engine using an external store order feed. It also includes any shopper profile data that was bulk uploaded to the Einstein engine using the `sendBulkProfile` endpoint using the Einstein Profile Connector API.

## Enable Access

To enable access to any Einstein API endpoints, go to [Einstein Configurator](https://configurator.cquotient.com/), and input your Account Manager client ID in the API page. Using Site Administrator access, you can [add an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5) on the [Account Manager](https://account.demandware.com/) page.

When enabled, and as long as the correct site ID and client ID are passed, the API functions in all environments, including production, staging, development, and sandbox instances.

## Authentication

Each API call must pass the `x-cq-client-id` header for API key authentication.

Implementing our API on the client side or server side comes with some tradeoffs. To make sure that you keep your client ID secret, we recommend that you implement our API on the server side for increased security. Client-side implementation runs the risk of exposing your client ID to bad actors.

## Authorization

Deleting data can have impacts on individual customer experiences, and on how the Einstein engine generates and provides experiences in general. For this reason, we allow only authorized users to delete data. In addition, each GDPR Delete API call must pass a required authorization header (bearer) access token obtained from Account Manager.

**note:** To reduce load on the Account Manager server, avoid generating any new tokens until the current token expires. Refer to the API Specification for more information on bulk upload API calls.

## Expectations and Limitations

The purpose of the GDPR Delete API is to delete data for individual users based on a specific user request. The API is not intended for bulk removal of user data, or to perform complete data resets. When setting up the API to perform multiple delete requests in succession, we strongly recommend that you limit the requests to only a few hundred within a 24 hour period.

## Reporting

Einstein doesn’t provide separate reporting for activity data. View standard reporting on the [Einstein Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_dashboard.htm&type=5).

<!-- document id=397af1d072efeab41b9d1d8c6be8678718adfabd5e9e38ed5d4a3ed02ad549cb url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-gdpr-delete/use-gdpr-delete.md -->

# Einstein GDPR Delete Usage

Commerce Einstein uses email addresses, user IDs, and cookie IDs to identify buyers and shoppers and deliver tailored customer experiences. Commerce Einstein uses these same values when locating and deleting customer data, or locating and rendering customer data anonymous.

## How It Works

When you post a `sendGDPRDelete` request, the API uses the provided `idType` object, coupled with the provided `idValue` object, to locate matching data in the Einstein engine. How the API treats found data depends on the type of data it locates, and how the data was originally obtained. For example, the API deletes any customer data uploaded using data feeds, and any site activity data associated with a specified ID. However, for internal data extracted through machine learning, the API makes the data anonymous by removing any association between internal IDs using the data, and customer IDs residing in the Einstein engine.

When deleting data, the API not only deletes rows of data where an ID is present, it also deletes data for any associated IDs. For example, when searching activity data or data feeds, if the API finds another ID associated with the ID you want to delete, the API also deletes data for that associated ID.

## GDPR Delete Request Body Parameters

The Einstein GDPR Delete API request body supports two parameters for locating data. You must specify values for both parameters in the request body.

- `idType` - Indicates the type of ID you want to use when identifying customer data. Options include:

  - `emailId` - Email address of the buyer or shopper.
  - `userId` - Unique identifier of a logged-in shopper (for example, a login_id, username, or userId value specific to the Einstein API). This value enables Einstein to link the same logged-in user across multiple devices.
  - `cookieId` - Unique identifier of an anonymous shopper. Typically, the cookieId is the value of the first-party cookie.

- `idValue` - Specifies the value that you want to locate and delete, in the form of the idType you specify.

  **note:** When specifying an email value, make sure that it uses a valid format.

## Einstein GDPR Delete Status

When the API successfully deletes data from the Einstein engine, the API returns `202` status response containing a `deleteId` value and a `deleteStatusLink`. Using this information from this response, view the status of a `getGDPRDeleteStatus` request in two different ways.

- Include the `deleteId` value from your `sendGDPRDelete` request response in the `getGDPRDeleteStatus` request. For example:

  `https://api.cquotient.com/v3/privacy/{siteId}/delete/{deleteId}/status`

  A successful response shows the status - `PENDING` or `COMPLETE`.

- Use the URL provided as the `deleteStatusLink` to view the status – `PENDING` or `COMPLETE`.

<!-- document id=3f874634cb80de18d5c439e29c93b1d4ba118f45e52f5ceb9843a12b801fd479 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-profile-connector/einstein-profile-connector-overview.md -->

# Einstein Profile Connector

Brands often gather data on their shoppers. For example, brands might offer surveys or quizzes to shoppers to learn their preferences. Brands might also obtain shopper attributes from some-third party data. Using the Profile Connector API, Einstein can take in this data and use it to boost personalized recommendation results.

To send shopper-oriented data to Einstein, brand developers can leverage the Profile Connector API to bulk upload historical data or to capture shopper information in real time. Merchandisers can then use Einstein Configurator to set up shopper profile rules and promote products or categories that match shopper attributes. Einstein can use this data to promote or demote products, recommending products based on an individual shopper’s unique preferences.

## General Configuration Process

The general process to enable and configure the API to use profile data includes:

1. Developers enable access to the Profile Connector API. (Instructions are covered in the next section, Enable Access).
2. Developers work with Merchandisers to evaluate shopper data as it relates to recommendations. Merchandisers can then plan what data to send to Einstein, and how shopper data maps to the product catalog.
3. Developers set up API calls to facilitate uploading profile data. See [Send Profile Data](https://developer.salesforce.com/docs/commerce/einstein-api/guide/send-profile-data.md).
4. Merchandisers who manage Einstein Configurator set up which products and categories they want Einstein to use when recommending products associated with certain shopper attributes. See [Configure Profile Data](https://developer.salesforce.com/docs/commerce/einstein-api/guide/configure-profile-data.md).
5. Use Einstein Configurator to preview recommendations and plan any A/B testing for recommendation results as needed.
6. Save any changes made to recommenders.

   **note:** Changes to recommendations can take up to 10 minutes to apply.

This video provides a demo of how to enable the Profile Connector API:

::video{src="https://developer.salesforce.com/docs/commerce/einstein-api/guide/XDsjgXmfLD9VnrMNn182KJ" title="" type="vidyard"}

## Enable Access

To enable access to any Einstein API endpoints, go to [Einstein Configurator][2], and input your Account Manager client ID in the API page. Using Site Administrator access, you can create the necessary client ID on the [Account Manager page][3]. For more information, see [Add an API Client ID][4].

When enabled, and as long as the correct client ID is passed, the API functions in all environments, including production, staging, development, and sandbox instances.

**note:** Using this API does not require using the Einstein Recommendations API. Use it with the Einstein Recommendations API, or use this API along with a traditional B2C Commerce storefront implementation.

## Authentication

Each API call must pass the `x-cq-client-id` header for API key authentication.

Implementing our API on the client side or server side comes with some tradeoffs. To make sure that you keep your client ID secret, we recommend that you implement our API on the server side for increased security. Client-side implementation runs the risk of exposing your client ID to bad actors.

## Scalability

Our service is globally distributed, horizontally scalable, and can automatically scale up and down based on traffic so load testing is unnecessary. We recommend that you avoid any load testing because it affects recommendation results.

## Reporting

Einstein doesn’t provide separate reporting for how your shopper profile data performs. View standard recommender performance reporting on the Einstein Dashboard (see [this document][5] to learn more about the Einstein Dashboard).

[2]: https://configurator.cquotient.com/
[3]: https://account.demandware.com/
[4]: https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5
[5]: https://success.salesforce.com/0693A000007TZdU?retUrl=/_ui/core/chatter/content/GroupFileListPage

<!-- document id=80bc6a0b7f0024da0523151b01c6ab93513c609d200ba8fb4e5ca89a74d3f898 url=/developer/current/en-us/commerce-cloud/einstein/references/generated-api-specs/einstein-profile-connector.md -->

Einstein Profile Connector

# Einstein Profile Connector

## API Overview

The Einstein Profile Connector API lets brands use the data they gather from their shoppers to personalize recommendations.

For setup and usage information information, see [Einstein Profile Connector](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-profile-connector-overview.html) in the Guides section.

* * *

_Rights of ALBERT EINSTEIN are used with permission of The Hebrew University of Jerusalem. Represented exclusively by Greenlight._

**Version:** v3

## Servers

*   `https://api.cquotient.com/v3`

Protocols: HTTPS.

## Security

*   `AMAuth` (OAuth 2.0)
    
    If you're bulk uploading files, you must pass an OAuth2 `Authorization` header with an Account Manager access token.
    
    To get that token, make the following request:
    
    ```
    curl -X POST \
      https://account.demandware.com/dwsso/oauth2/access_token \
      -H 'Authorization: Basic <INSERT BASIC AUTH HERE>' \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials'
    ```
    
    For the Basic Authorization header, use base64 encoded `<Client ID>:<Password>`
    
    *   Header Authorization: \`JWT <AM access token>\`

## Operations

### POST sendUpdateProfile

`POST /activities/{siteId}/updateProfile`

Display name: Real-Time Activity.

Alerts the Einstein engine when a user updates their profile preferences.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `profile` (_array of UserProfileParam_, required) The array of profile data updated by the user. All profile data is treated as case sensitive.
*   `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed).
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The user agent of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendBulkProfile

`POST /upload/{siteId}/profile`

Display name: Bulk Upload. Security: AMAuth.

Bulk upload of profile data to the Einstein engine. All profile data is treated as case-sensitive.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `multipart/form-data`. Schema: `object`.

*   `file` (_any_, required) The gzipped tsv profile data file to be uploaded.
    
    _Example_
    
    ```
    profile.tsv.gz
    ```
    

#### Responses

*   **200** A successful response is OK with no body.
*   **400** A validation error response contains a description of the problem.
*   **403** Either the provided client ID or authorization token was invalid.

## Schemas

### EinsteinSiteIdParam

The Einstein Site ID. Locate this ID in the upper-right corner of the [Einstein Configurator](https://configurator.cquotient.com). The ID has the format `xxxx-<Commerce Cloud Site ID>`.

Type: `string`.

### ClientIdParam

Make sure to pass the `x-cq-client-id` header with your B2C Commerce Account Manager API Client ID. Locate this value in Business Manager, under Administration > Site Development > Open Commerce API Settings. This settings page displays a JSON object containing the current OCAPI configuration. You can use any of the values in a `client_id` field, but ideally you should create one specifically for Einstein API calls.

Type: `string`.

### UserProfileParam

*   `name` (_string_, required) A unique name for the profile attribute.
*   `value` (_array of string_, required) An array of string values for the profile attribute.

### UserIdParam

Application-provided unique identifier for logged in users (hashed).

Type: `string`.

### CookieIdParam

The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**

Type: `string`.

### ClientIpParam

The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.

Type: `string`.

### ClientUserAgentParam

The user agent of the end user. Use this parameter if you're sending activities server-side for a client application.

Type: `string`.

### RealmParam

A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

Type: `string`.

### ActivityResponse

*   `uuid` (_string_, required) The unique identifier for the end user. If you don't already have identifiers associated with a user, you can use this value in subsequent requests.  
    Example: `ce035cc0-2cbb-4d9e-95ed-c67fa55d1eb8`.

### ValidationError

*   `code` (_string_, required) A short error code to classify types of errors.  
    Example: `ValidationError`.
*   `errors` (_array of object_, required) A set of invalid parameters.
    *   `location` (_string_, required) The location of the invalid parameter.  
        Example: `body`.
    *   `msg` (_string_, required) A message describing why the parameter is invalid.  
        Example: ``Must provide a `products` array.``.
    *   `param` (_string_, required) The name of the invalid parameter.  
        Example: `products`.
*   `msg` (_string_, required) A descriptive message about the error that you can use to troubleshoot problems.  
    Example: ``There was a problem validating the request. See `errors`.``.

<!-- document id=2891c010cfc248243f12c062336df1b7bd006826b019596fe2ca22ba73698393 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-recommendations/einstein-recommendations-overview.md -->

# Einstein Recommendations

The Einstein Recommendations API has two main functions: to receive activities and to output recommendations. Our customers can also achieve flexibility in switching recommenders without any code changes by using our Zone components.

This API documentation is primarily intended for Salesforce B2C Commerce customers.

## Enable Access

To enable access to the Einstein Recommendations API, go to the [Einstein Configurator](https://configurator.cquotient.com/), and input your Account Manager client ID in the API page. Using Site Administrator access, you can [add an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5) on the [Account Manager](https://account.demandware.com/) page.

When enabled, and as long as the correct client ID is passed, the API functions in all environments, including production, staging, development, and sandbox instances.

## Authentication

Each API call must pass the `x-cq-client-id` header for API key authentication.

Implementing our API on the client side or server side comes with some tradeoffs. To make sure that you keep your client ID secret, we recommend that you implement our API on the server side for increased security. Client-side implementation runs the risk of exposing your client ID to bad actors.

The requests to get recommendations, and certain user activities like viewProduct, viewReco, and clickReco, require caching considerations if implemented on the server side. For example, in the case of a user viewing a cached product page, the viewProduct activity should still be sent. It is important that Einstein receives all events, and that recommendations are not cached.

## API Email Limitations

This Einstein Recommendations API is not designed for the email recommendations use case. It does not support embedding Einstein recommendations in emails.

## Scalability

Our service is globally distributed, horizontally scalable, and can automatically scale up and down based on traffic, so load testing is unnecessary. We recommend that you avoid any load testing because it affects recommendation results.

## User Identifier Parameters

To help generate relevant product recommendations for each shopper, the Einstein Recommendations API provides parameters for shopper identification.

**note:** To avoid potential malicious activity, user identifier parameters must be non-sequential. The parameters should not include sequences, patterns, IP addresses, email addresses, names, or anything linked to a specific person. All user identifier parameters must comply with General Data Protection Regulation (GDPR) through hashing or other methods.

- `cookieId` (required) - Unique identifier of an anonymous shopper. Typically, the `cookieId` is the value of a first-party cookie.
  - When making API requests from a traditional B2C Commerce storefront, pass the `cqcid` cookie value to match the automatic activity tracking on the traditional storefront. For more information, see [Browser-Based Local Data Storage](https://help.salesforce.com/s/articleView?id=cc.b2c_local_data_storage.htm&type=5).
  - When using the Salesforce Commerce APIs, pass the `USID` value available as part of the token retrieval process. For more information, see the Shopper Login and API Access Service documentation.
  - When using OCAPI, pass the `visit_id` value from the guest login response to match automatic activities. For more information, see the [OCAPI Customer Document](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer).
- `userId` (encouraged) - Unique identifier of a logged-in shopper. This parameter enables Einstein to link the same logged-in user across multiple devices.
  - When making API requests from a traditional B2C Commerce storefront, pass the `cquid` cookie value to match automatic activity tracking on the traditional storefront. For more information, see [Browser-Based Local Data Storage](https://help.salesforce.com/s/articleView?id=cc.b2c_local_data_storage.htm&type=5).
  - When using the Salesforce Commerce APIs, pass the `hashed_login` value from the registered login response to match automatic activities. For more information, see the Shopper Login and API Access Service documentation.
  - When using OCAPI, pass the `hashed_login` value from the registered login response to match automatic activities. For more information, see the [OCAPI Customer Document](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer).

## Reporting

Standard performance reporting for recommenders used through the Einstein API is the same as that for other recommenders used on your digital sites. View reporting on the Einstein Dashboard (see [Einstein Dashboard FAQ](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/EinsteinDashboardFAQv1.pdf) to learn more about the Einstein Dashboard).

To make separate reporting and troubleshooting easier, we recommend that you create separate recommenders for the Einstein API. For example, naming a recommender “pdp-mobile-API” indicates that the recommender is used on the product detail page on a mobile app.

**note:** Reporting metrics are based on activities. If an application using the Einstein Recommendations API fails to send activities, all metrics for the API recommender appear as zero (0).

`Rights of ALBERT EINSTEIN are used with permission of The Hebrew University of Jerusalem. Represented exclusively by Greenlight.`

<!-- document id=884087b1ddd4f2b87e45ca40218737001eefc9ca753ba8649855b7e2a6f92433 url=/developer/current/en-us/commerce-cloud/einstein/references/generated-api-specs/einstein-recommendations.md -->

Einstein Recommendations

# Einstein Recommendations

## API Overview

The Einstein Recommendations API has two main functions: to receive activities and to output recommendations.

For setup and usage information information, see [Einstein Recommendations](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-recommendations-overview.html) in the Guides section.

* * *

_Rights of ALBERT EINSTEIN are used with permission of The Hebrew University of Jerusalem. Represented exclusively by Greenlight._

**Version:** v3

## Servers

*   `https://api.cquotient.com/v3`

Protocols: HTTPS.

## /activities (Activities)

## /personalization (Personalization)

## Operations

### POST sendViewProduct

`POST /activities/{siteId}/viewProduct`

Display name: viewProduct.

Tells the Einstein engine when a user opens a product page.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `product` (_ProductForView_, required)
*   `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed).
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application.
*   `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendViewReco

`POST /activities/{siteId}/viewReco`

Display name: viewReco.

Tells the Einstein engine when a user views a set of recommendations.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `recommenderName` (_string_, required) The name of the recommender used in the recommendation request.
*   `__recoUUID` (_string_, required) The UUID that was returned in the recommendation response.
*   `products` (_array of ProductForView_, required) The recommendations that the user viewed.
*   `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed).
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application.
*   `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendClickReco

`POST /activities/{siteId}/clickReco`

Display name: clickReco.

Tells the Einstein engine when a user clicks a recommendation.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `recommenderName` (_string_, required) The name of the recommender used in the recommendation request.
*   `__recoUUID` (_string_, required) The UUID that was returned in the recommendation response.
*   `product` (_ProductForView_, required)
*   `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed).
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application.
*   `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST sendAddToCart

`POST /activities/{siteId}/addToCart`

Display name: addToCart.

Tells the Einstein engine when a user adds an item to their cart.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `products` (_array of object_, required) The products that the user has added to their cart.
    *   `id` (_string_, required) A unique identifier for the given product.
    *   `sku` (_string_, required) A unique identifier for a sellable unit of the given product, when applicable.
    *   `price` (_number_, required) The discounted or negotiated price of each individual unit of the product.
    *   `originalPrice` (_number_, required) The original price of each individual unit of the product.
    *   `quantity` (_integer_, required) The total number of this item in the cart.
*   `source` (_SourceParam_) The page or site location where the 'Add To Cart' button was clicked. Accepted values are `pdp`, `plp`, `recs`, `quick add`, and `wishlist`.
*   `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed).
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application.
*   `realm` (_RealmParam_) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

#### Responses

*   **200** A successful response contains a UUID for the given user.
    
    Media type: `application/json`. Schema: `ActivityResponse`.
    
*   **400** A validation error response contains an array of invalid parameters.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### GET getRecommenders

`GET /personalization/recommenders/{siteId}`

Display name: Recommenders.

Get a list of recommenders that can be used in recommendation requests.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Responses

*   **200** A successful response will contain a list of recommenders available for use in recommendation requests.
    
    Media type: `application/json`. Schema: `RecommendersResponse`.
    
*   **400** Either there was no OCAPI client id in the request, or the given OCAPI client id was not valid.
    
    Media type: `application/json`. Schema: `ValidationError`.
    
*   **403** The given site ID is not valid.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST getRecommendations

`POST /personalization/recs/{siteId}/{recommenderName}`

Display name: Recommendations.

Get a set of recommendations.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `recommenderName` (path, string, required) Name of the recommender to use for recommendations. This item should exist in a response to GET /recommenders for the same site id.
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `products` (_array of ProductForView_) The products to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple product anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped. Exception is Complete the Set Recommender where recommendations reflect whichever single anchor produced the most recommendations.
*   `categories` (_array of object_) The product categories to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple category anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped.
    *   `id` (_string_, required) A unique identifier for the given category.
*   `rules` (_Rules_) Extra rules to add filtering on the set of recommendations
*   `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed).
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application.
*   `realm` (_RealmParam_, required) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

#### Responses

*   **200** A successful response will contain a set of recommendations.
    
    Media type: `application/json`. Schema: `RecommendationsResponse`.
    
*   **400** A request parameter was missing or invalid.
    
    Media type: `application/json`. Schema: `ValidationError`.
    
*   **404** Either the given `recommenderName` or `siteId` was invalid.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

### POST getZoneRecommendations

`POST /personalization/{siteId}/zones/{zoneName}/recs`

Display name: Zone Recommendations.

Get a set of recommendations for a zone.

#### Parameters

*   `siteId` (path, EinsteinSiteIdParam, required)
*   `zoneName` (path, string, required) Name of the recommendation zone.
*   `x-cq-client-id` (header, ClientIdParam, required)

#### Request body

Media type: `application/json`. Schema: `object`.

*   `products` (_array of ProductForView_) The products to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple product anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped. Exception is Complete the Set Recommender where recommendations reflect whichever single anchor produced the most recommendations.
*   `categories` (_array of object_) The product categories to use as context for generating recommendations. Any given request must have only one of categories or products. When multiple category anchors are sent, recommendations are generated against the first 4 only, reflecting a union of recommendations for each anchor (A-rec1, B-rec1, A-rec2, B-rec2...) with anchors stripped out and recommendations deduped.
    *   `id` (_string_, required) A unique identifier for the given category.
*   `rules` (_Rules_) Extra rules to add filtering on the set of recommendations
*   `userId` (_UserIdParam_) Application-provided unique identifier for logged in users (hashed).
*   `cookieId` (_CookieIdParam_) The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**
*   `clientIp` (_ClientIpParam_) The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.
*   `clientUserAgent` (_ClientUserAgentParam_) The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application.
*   `realm` (_RealmParam_, required) A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

#### Responses

*   **200** A successful response will contain a set of recommendations.
    
    Media type: `application/json`. Schema: `ZoneResponse`.
    
*   **400** A request parameter was missing or invalid.
    
    Media type: `application/json`. Schema: `ValidationError`.
    
*   **404** Either the given `recommenderName` or `siteId` was invalid.
    
    Media type: `application/json`. Schema: `ValidationError`.
    

## Schemas

### EinsteinSiteIdParam

The Einstein Site ID. Locate this ID in the upper-right corner of the [Einstein Configurator](https://configurator.cquotient.com). The ID has the format `xxxx-<Commerce Cloud Site ID>`.

Type: `string`.

### ClientIdParam

Make sure to pass the `x-cq-client-id` header with your B2C Commerce Account Manager API Client ID. Locate this value in Business Manager, under Administration > Site Development > Open Commerce API Settings. This settings page displays a JSON object containing the current OCAPI configuration. You can use any of the values in a `client_id` field, but ideally you should create one specifically for Einstein API calls.

Type: `string`.

### ProductForView

*   `id` (_string_, required) A unique identifier for the given product.
*   `sku` (_string_) A unique identifier for a sellable unit of the given product, where applicable.
*   `altId` (_string_) An alternate identifier for the given product. You must specify a type in the `altIdType` field.
*   `altIdType` (_string_) The type of alternate identifier.  
    Allowed values: `vgroup`.

### UserIdParam

Application-provided unique identifier for logged in users (hashed).

Type: `string`.

### CookieIdParam

The unique identifier of an anonymous shopper. **If you're making API requests from a traditional B2C Commerce storefront, pass the `dwanonymous_*` cookie value (See [Browser-Based Local Data Storage](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2FDataProtectionAndPrivacy%2FLocalDataStorage.html&resultof=%22%64%77%61%6e%6f%6e%79%6d%6f%75%73%22%20%22%64%77%61%6e%6f%6e%79%6d%22%20) for more information).**

Type: `string`.

### ClientIpParam

The IP address of the end user. Use this parameter if you're sending activities server-side for a client application.

Type: `string`.

### ClientUserAgentParam

The User Agent of the end user. Use this paramenter if you're sending activities server-side for a client application.

Type: `string`.

### RealmParam

A unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM). The realm is often the first four characters of the Einstein Site ID. However, if your site changes realms in B2C Commerce, the Einstein Site ID won’t use the correct realm.

Type: `string`.

### ActivityResponse

*   `uuid` (_string_, required) The unique identifier for the end user. If you don't already have identifiers associated with a user, you can use this value in subsequent requests.  
    Example: `ce035cc0-2cbb-4d9e-95ed-c67fa55d1eb8`.

### ValidationError

*   `code` (_string_, required) A short error code to classify types of errors.  
    Example: `ValidationError`.
*   `errors` (_array of object_, required) A set of invalid parameters.
    *   `location` (_string_, required) The location of the invalid parameter.  
        Example: `body`.
    *   `msg` (_string_, required) A message describing why the parameter is invalid.  
        Example: ``Must provide a `products` array.``.
    *   `param` (_string_, required) The name of the invalid parameter.  
        Example: `products`.
*   `msg` (_string_, required) A descriptive message about the error that you can use to troubleshoot problems.  
    Example: ``There was a problem validating the request. See `errors`.``.

### SourceParam

The page or site location where the 'Add To Cart' button was clicked. Accepted values are `pdp`, `plp`, `recs`, `quick add`, and `wishlist`.

Type: `string`.

### RecommendersResponse

*   `recommenders` (_array of object_, required) The list of available recommenders.
    
    Includes all fields of `Recommender`.
    

### Rules

Extra rules to add filtering on the set of recommendations

Array of `object`.

Each item: A condition that the set of recommendations must meet.

A condition that the set of recommendations must meet.

*   `type` (_string_, required) show, hide, promote, or demote  
    Example: `show`.
*   `field` (_string_, required) The name of the field to compare.  
    Example: `current_price`.
*   `operator` (_string_, required) equals, greaterThan, or lessThan. For notEquals, use the opposite rule type (e.g. use a hide rule instead of a show rule).  
    Example: `greaterThan`.
*   `values` (_array of string | number_, required) The list of values to compare. For greaterThan or lessThan operations, the array should consist of just one number element.
    
    _Example_
    
    ```
    - 19.99
    ```
    

### RecommendationsResponse

*   `recoUUID` (_string_, required) Identifier of this recommendation set.  
    Example: `05e0bd80-64eb-4149-ad5a-dfe1996f8f57`.
*   `recs` (_array of object_, required) The set of recommendations.
    
    Includes all fields of `Recommendation`.
    

### ZoneResponse

*   `displayMessage` (_string_) Text to (optionally) use to accompany the given recommendations. This message can be edited in the Configurator.  
    Example: `Recently Viewed`.
*   `recoUUID` (_string_, required) An identifier of the recommendation set.  
    Example: `05e0bd80-64eb-4149-ad5a-dfe1996f8f57`.
*   `recs` (_array of object_, required) The set of recommendations.
    
    Includes all fields of `Recommendation`.
    
*   `recommenderName` (_string_, required) The name of the recommender that was used.  
    Example: `recently-viewed-products`.

### Recommender

*   `name` (_string_, required) The name of the recommender.  
    Example: `recently-viewed-products`.
*   `description` (_string_) The description of the recommender.  
    Example: `Recently viewed products.`.
*   `recommenderType` (_string_, required) The type of the recommender.  
    Example: `recently-viewed`.

### Recommendation

*   `id` (_string_, required) The ID of the recommendation.  
    Example: `prod_123`.
*   `product_name` (_string_, required) The name of the recommendation.  
    Example: `Product ABC`.
*   `product_url` (_string_, required) The product URL of the recommendation.  
    Example: `prod_abc.test.com`.
*   `image_url` (_string_, required) The image URL of the recommendation.  
    Example: `prod_abc.test.com`.

<!-- document id=f4f284cb85c2bb8f9de73599ed5494a5b4e795fd3459ee5f21b6a3366d1300da url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-email-verification.md -->

# Email Verification for Storefront Next

Storefront Next supports email verification to confirm shopper identity using a one-time passcode (OTP). A Business Manager site preference controls email verification. When enabled, the site preference activates these features.

- **Passwordless registration and login as default** — Shoppers create accounts and log in using an OTP instead of a password.
- **Email verification** — Shoppers verify their email address during registration and on the Account Details page.
- **Email update support** — Shoppers have the option to change their email address in account details. If they don’t have a password, OTP-based identity confirmation is required before the system applies the change. OTP verification isn’t required for shoppers who do have a password.

## Prerequisites

- Configure a Shopper Login and API Access Service (SLAS) private client with passwordless login enabled. For instructions, see [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html#configure-a-slas-private-client) in the _B2C Commerce API Developer Guide_.
- In `config.server.ts`, set `commerce.api.privateKeyEnabled` to `true`. If `false`, passwordless login is disabled at run time.
- Enable **Enable Loginid Updates for SCAPI**. With this setting, shoppers can update their login email via SCAPI. Contact support to enable this feature.
- In **Merchant Tools \> Site Preferences \> Storefront Login Preferences**, turn on **Enable Email Verification**. This preference enables passwordless registration, post-registration email verification, and the email change flow in account details.

![Enable Email Verification site preference in Storefront Login Preferences](https://developer.salesforce.com/docs/media/sfnext/slas-email-verification.png)

**note:** Changes to site preferences can take up to 5 minutes to reflect on a deployed storefront.

## Configure Settings

To control OTP settings, update `auth` and `features.otpRequest` in `config.server.ts`.

```ts
auth: {
    otpLength: 6,
},
features: {
    otpRequest: {
        mode: 'email',
    },
}
```

- `otpLength`: The length of the OTP code. Valid values are `6` or `8`. Defaults to `6`. Make sure that this value matches the OTP length configured in your SLAS client. See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#1-configure-a-slas-private-client) in the _B2C Commerce API Developer Guide_.
- `mode`: The mode used to deliver the OTP to the shopper (`email` or `callback`). Defaults to `email`. The `callback` mode doesn’t support email verification.

To override configuration options, use Managed Runtime (MRT) environment variables with the `PUBLIC__` prefix.

```shell
PUBLIC__app__auth__otpLength=6
PUBLIC__app__features__otpRequest__mode="email"
```

## OTP Delivery with Email (SLAS Native Email Service)

Passwordless login supports both email and callback modes, but only the email mode supports email verification. When `mode` is set to `email`, SLAS sends the OTP directly to the shopper's email without third-party integration. This mode doesn't require a callback URI.

1. Configure SLAS for passwordless login with email. See [Passwordless Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html) in the _B2C Commerce API Developer Guide_.
2. In `config.server.ts`, set the OTP mode to `email`.

```ts
features: {
    otpRequest: {
        mode: 'email',
    },
}
```

## Registration

This diagram shows the complete registration flow. When **Enable Email Verification** is turned off, accounts are created without verification. When it's turned on, shoppers can use passwordless mode (the default) or create a password to register. The numbered callouts in the diagram correspond to the steps described in each registration method (Passwordless and Password-Based with Email Verification).

![Registration flow diagram showing passwordless and password-based paths with numbered callouts](https://developer.salesforce.com/docs/media/sfnext/sfnext-email-verification-registration.png)

### Passwordless Registration

If a site has **Enable Email Verification** turned on, the registration page defaults to passwordless mode. To create an account, shoppers enter their name and email and complete OTP verification.

1. The shopper submits their name and email (1).
2. The storefront calls the SLAS passwordless login endpoint, which creates the account and sends an OTP to the shopper's email.
3. The shopper enters the OTP in the verification modal to complete registration (2).

![Passwordless registration form with OTP verification modal](https://developer.salesforce.com/docs/media/sfnext/sfnext-create-your-account.png '{"class": "image-md"}')

### Password-Based Registration with Email Verification

Shoppers who register with a password also verify their email after account creation.

1. The shopper submits their name, email, and password (3).
2. The storefront creates the account and immediately requests an OTP for the registered email.
3. The shopper enters the OTP in the verification modal (4). If the OTP request fails, the account is still created and the shopper is redirected without requiring verification. The shopper can verify their email on the Account Details page at a later time.

![Password-based registration form with OTP verification modal](https://developer.salesforce.com/docs/media/sfnext/sfnext-create-your-account-2.png '{"class": "image-md"}')

## Login

### Passwordless Login

If a site has **Enable Email Verification** turned on, the login page defaults to passwordless mode. To log in, shoppers enter their email and complete OTP verification.  
![Login page showing passwordless, password, and social login options](https://developer.salesforce.com/docs/media/sfnext/sfnext-email-verification-setting.png)  
If **Enable Email Verification** is turned off, the login page supports password (1) or social login (2), if configured.

If **Enable Email Verification** is turned on, the login page supports passwordless (3), password (4), and social login (5), if configured. Both login pages in this example also include **Forgot your password?** buttons.

## Account Details

### Email Verification Badge

If a site uses email verification, the Account Details page shows a **Verified** or **Unverified** badge next to the shopper's email address.

![Account Details page showing Verified email badge](https://developer.salesforce.com/docs/media/sfnext/sfnext-email-verified.png)![Account Details page showing Unverified email badge](https://developer.salesforce.com/docs/media/sfnext/sfnext-email-unverified.png)

### Change Email

The Account Details page only shows the **Change Email** button if the site has email verification turned on. The identity confirmation method depends on whether the shopper has a password.

- **Accounts without a password** — The shopper verifies their identity with an OTP sent to their current email address before they can change their email.
- **Accounts with a password** — The shopper verifies their identity with their current password.

1. The shopper clicks **Change Email**.
2. The shopper confirms their identity using their password.
3. The shopper enters their new email address and submits the change.

### Password Card

For passwordless accounts (accounts without a password), the password card shows a **Reset Password** button instead of **Change Password**, so shoppers can set a password if they choose.  
![Password card showing Reset Password button for passwordless accounts](https://developer.salesforce.com/docs/media/sfnext/sfnext-password-card.png)

## Best Practices for Email Verification

- Implement rate limiting to prevent abuse of password reset. For example, if you use embedded CDN (eCDN), apply \[eCDN Rate Limiting Rules\](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).
- Use robust security measures to protect shopper accounts. For example, if you use a third-party content delivery network (CDN) such as Cloudflare, \[Block requests by Threat Score\](https://developers.cloudflare.com/waf/custom-rules/use-cases/block-ip-reputation/).
- Track shopper usage of authentication options and diagnose issues efficiently. For example, use \[Log Center\](https://help.salesforce.com/s/articleView?id=cc.b2c\_log\_center.htm\&type=5) to access logs from Managed Runtime (MRT) and your B2C Commerce instance.

## Troubleshoot Email Verification

For common troubleshooting scenarios, see \[Troubleshoot Passwordless Login\](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-troubleshoot.html) in the _B2C Commerce API Developer Guide_.

<!-- document id=4cbc1bf0c2e0fcff3b8762803c5ed1a4adcb7b537a9f8c0bf6e0d22b3afb7fe9 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/employee-verification-spi.md -->

Employee Verification SPI

# Employee Verification SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/employee-verification-spi/employee-verification-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to verify employee status and details.

**Version:** 2.3.4

## Tags

### Employee Verification SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/employee-verification-spi/employee-verification-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to verify employee status and details.

## Operations

### POST Verify employee.

`POST /merchant/spi/sample/endpoint/sa/employee/verification/to/verify/employee/from/external/system`

Operation ID: `verifyEmployee`. Tags: Employee Verification SPI.

Verify employee details from merchant's system based on provided input. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `VERIFY_EMPLOYEE`
    *   **API Endpoint:** Provide the external endpoint to verify employee, for example: [https://sample.com/external/endpoint/to/verify/employee/from/external/system](https://sample.com/external/endpoint/to/verify/employee/from/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"contentType": "application/json"} **Response:** If response is NULL or empty, or has ErrorCode or ErrorMessage, employee verification fails. **Use Case:** If an employee makes the purchase, authenticate their details when they are added to the cart.

#### Request body

Media type: `application/json`. Schema: `EmployeeVerificationRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `EmployeeVerificationResponse`.
    

## Schemas

### EmployeeVerificationRequest

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)
*   `storeId` (_string_) Store ID provided for employee verification.
*   `associateId` (_string_) Associate ID provided for employee verification.

### EmployeeVerificationResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `employeeId` (_string_) Identification of employee.
*   `firstName` (_string_) Employee's first name.
*   `lastName` (_string_) Employee's last name.
*   `email` (_string_) Employee's email.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `error` (_boolean_)

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

<!-- document id=3918d23f64f56ac419de7974df3da7ec5167e84816ec19fea440e4957a14a677 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/activation-codes-via-spi.md -->

# Enable Activation Codes With the SPI

Point of Sale supports retrieving activation codes using an SPI. For merchants selling products through digital codes (for example, product downloads), this SPI allows Point of Sale to request the code from the merchant's server. The code can then be printed on the customer's receipt.

- Modern POS App Build: 10.4.1 or greater
- Platform Support: iPad & iPhone
- Offline Support: No

**note:** For details on this SPI, see [Activation Code SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/activation-code-spi?meta=Summary) in the Point of Sale reference documentation.

For a comprehensive list of Point of Sale APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Configure Product Class

1.  In CMS, go to **Products** | **Product Class**.

2.  Configure a new class for activation codes. For more information, see [Set Up Non-Merchandise SKUs](https://help.salesforce.com/s/articleView?id=commerce.rt_pos_orders_custom_non_merchandise_sku.htm) in _Salesforce Help_.

3.  Turn on the **Requires Activation Code via External Source** setting.![The CMS shows the requiring activation code via external source flag.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-special-types-activation-code-product-class.png)

## Configure SPI

1.  In CMS, go to **Integrations** | **Custom Connectors.**.

2.  Click **Create**.

3.  For Connector Type, select **SPI**.

4.  For Endpoint Name, select **GENERATE_ACTIVATION_CODE**.

5.  For API Endpoint, provide the external endpoint to retrieve activation codes.

6.  For Integration Type, select **HTTP_POST**.

7.  Specify any required JSON headers. See [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) for examples.

8.  Configure the rest of the fields as needed.

9.  Save your changes.
    ![The CMS shows SPI settings.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-special-types-activation-code-spi.png)

## Sample Request and Response

### Request

During checkout, if any product in the cart belongs to a Product Class with Requires Activation Code via External Source enabled, the app makes a single call to the Activation Code SPI. The request includes the `orderId`, `storeId`, `transactionId`, and `productList`. The `productList` includes `productId` and `orderItemId`.

```java
{
  "orderId": "string",
  "storeId": "string",
  "transactionId": "1-test-20240612131829-4-1",
  "productList": [
    {
      "productId": "string",
      "orderItemId": "It can have values like 1, 2, 3, etc... which represents line item number within the order."
   }
  ]
}

```

### Response

The response provides an activation code for each product quantity, with multiple quantities of the same item returned as an array. Each activation code has a maximum length of 32 characters. The response also includes a context code, serving as a reference to the activation code, with a maximum length of 32 characters.

```java
{
  "errorMessage": "Invalid request. Please check the request and try again.",
  "errorCode": "INTERNAL_ERROR",
  "serializedUnitDetailList": [
    {
      "activationCode": "string",
      "contextCode": "string",
      "orderItemId": "string"
    }
  ],
  "error": true
}

```

## Receipts

[Print](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/rt-cms-layouts-templates-receipt.html) and [Email](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/rt-cms-layouts-templates-email.html) tags can be used to print the activation code on a receipt.

<table>
<col />
<col />
<thead>
  <tr>
    <th>
      Email Receipt Tag
    </th>
    <th>
      Print Receipt Tag
    </th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>
      {activationCode}
    </td>
    <td>
      :ps_p_actviation_code
    </td>
  </tr>
</tbody>
</table>

![An example receipt containing an activation code.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-special-types-activation-code-receipt.png)

The activation code is only printed on receipts and isn't displayed on the POS app. However, the Order History does display the product's context code, which is a reference to the activation code.

![The POS app shows an activation code in receipt detail details.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-special-types-activation-code-pos.png)

**important:** Offline orders don't display activation codes on the receipt, as the app can't access the SPI while offline. As a result, no codes appear on the printed receipt. Once the offline order is synced successfully, and the subsequent SPI call is also successful, the order is marked as successful. The order history then reflects the context codes, and reprinting the receipt includes the activation codes.

## Known Issues and Restrictions

- Activation codes aren't eligible for returns.
- Order edits aren't supported. If an order is edited and a product with an activation code is added, it doesn't trigger the SPI to retrieve the activation code.
- POS app doesn't restrict the fulfillment type of a product with an activation code.
- Activation codes aren't displayed in the POS UI.
- Offline support isn't available for the sale of items requiring digital codes.
- This feature isn't supported for all other fulfillment types (for example, Ship to Home).

<!-- document id=3c1aac16ba617d13e054ea69ffb857f1c61f42f1c97972c6bd55792ed226e12c url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/enable-merchant-team.md -->

# Enable Your Merchant Team

Use these no-code features to complete some optional site design and merchandising tasks while building on Composable Storefront. This section contains the following guides.

- [Storefront Preview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md)
- [Data and Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/data-and-analytics.md)
- [Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/active-data.md)
- [Reports & Dashboards](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reports-and-dashboards.md)

### See Also

- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)

<!-- document id=5a23966ba4fde7410ea912d7e7b19b50d7c5dc1e4cd1601e62fa4686e4e819f4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-google-gmc-configuration.md -->

# Enabling Google as a Platform

The enablement process is split between making yourself a UCP-compliant **business** and onboarding with each **platform**. Salesforce publishes your [business profile](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#business-profile) from Business Manager. Google as a platform discovers your **products** in Google Merchant Center (GMC) and must also accept you into Google's UCP program before shoppers see a Buy button in Gemini or AI Mode in Search.

Join Google's UCP waitlist first—even before your Salesforce implementation or Merchant Center feed is finished. Waitlist, GMC, and Salesforce UCP setup can proceed in parallel. Complete [Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md) and [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md) as you go. You still publish a business profile from Business Manager; for now Google calls the checkout URL you submit on their secrets form rather than fetching that profile.

- [Onboard with Google](#onboard-with-google)
- [Google Merchant Center (GMC) Setup](#google-merchant-center-gmc-setup)
- [End-to-End Testing](#end-to-end-testing)
- [Get Support](#get-support)

Google's own developer and Merchant Center guides are the source of truth for Google's program, waitlist, and sandbox. Start with [Getting started with UCP on Google](https://developers.google.com/merchant/ucp) and [How to onboard to UCP in Merchant Center](https://support.google.com/merchants/answer/16992327).

## Onboard with Google

Publishing a Salesforce business profile and a GMC feed does **not** by itself put a Buy button on Gemini. Google gates access to their UCP surfaces (Gemini and AI Mode in Search). Submit Google's forms **to Google**—Salesforce doesn't collect these values.

1. Join Google's UCP waitlist. Follow [How to onboard to UCP in Merchant Center](https://support.google.com/merchants/answer/16992327) and [Google's UCP developer guide](https://developers.google.com/merchant/ucp). Do this first, even if Business Manager and the Merchant Center feed are still in progress.
2. When Google selects you, they notify you and give you the Merchant Center UCP onboarding experience — including a sandbox to validate your UCP profile and native checkout APIs.
3. In parallel, complete the Salesforce UCP implementation in this guide (Business Manager, checkout APIs, payment path) and [Google Merchant Center (GMC) Setup](#google-merchant-center-gmc-setup). Create the SLAS private client you share with Google—[Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md).
4. After Google accepts you, submit the [MC UCP Checkout API Secrets](https://docs.google.com/forms/d/e/1FAIpQLSfGrPY_F-SsMF6EgwG49k13sRP7sJ0WEp6TWmZ6de8fiNNRQg/viewform) form so Google can authenticate to your checkout APIs. See [Share Checkout API Credentials](#share-checkout-api-credentials).

Google rolls that Merchant Center experience out gradually. A UCP integration tab can appear in Merchant Center as it becomes available for your account. Google's checkout feature is currently limited to participating merchants; Salesforce UCP on an en-US site doesn't skip Google's waitlist.

## Google Merchant Center (GMC) Setup

When transacting with Google as a platform, Google Merchant Center is the source of truth for your **products**. Checkout still happens on Salesforce; Google uses GMC for product data and inventory for discovery. Finish this setup before you test the Buy button—Gemini can only offer SKUs that are in GMC with `native_commerce` set. Start the feed before waitlist acceptance.

Also complete Google's Merchant Center account requirements in [Prepare your Merchant Center account](https://developers.google.com/merchant/ucp/guides/merchant-center):

- **Return policy** — required on the checkout screen. Include return cost, return window, and a link to the full policy.
- **Customer support info** — at least one of website, email, or phone. Google uses this for the "Contact Merchant" link on the order confirmation page.

### 1. Account and Feed Verification

Make sure your GMC account is verified and your product feed is active. The feed must target the en-US locale.

### 2. Product Discovery

Your products must be synced to GMC to be eligible for discovery. Sync by using the Salesforce Commerce Cloud (SFCC) GMC integration, a third-party integration, or a manual feed. If you already have a feed integration into GMC via a third-party feed aggregator, continue using that.

### 3. Required Product Fields for UCP

Two additional product fields are required for UCP that aren't in existing GMC feeds today:

- `native_commerce` - A boolean attribute that indicates whether a product is available for purchase directly through Google as a platform
- `consumer_notice` - Optional consumer-facing notices or disclaimers

For products to be eligible for UCP checkout, they must have the `native_commerce` attribute set to `true`. Only listings with that eligibility signal show the Buy button. Google documents this as `native_commerce(checkout_eligibility)` in [Prepare your Merchant Center account](https://developers.google.com/merchant/ucp/guides/merchant-center#2_product_data).

The product `id` in your GMC feed must match the product ID your checkout APIs expect. If they differ, Google's `merchant_item_id` custom attribute maps them.

#### If You're Using Your Existing GMC Feed Integration

Add those two fields to your feed via a supplemental feed as suggested by [Google's UCP documentation](https://developers.google.com/merchant/ucp/guides/merchant-center#2_product_data).

#### If You're Using SFCC's GMC Feed Integration

Configure those fields in your catalog and map them in the field mapping table. They are included in your feed file automatically.

### 4. Disable Tax and Shipping Settings

**important:** Leave tax and shipping rate fields empty in Google Merchant Center.

Because UCP uses a Dynamic Checkout model, the platform pulls real-time tax and shipping costs directly from Salesforce during the checkout session. Static settings in GMC cause price mismatches and checkout failures.

#### Where Tax and Shipping Are Configured

Tax and shipping rates are calculated dynamically by B2C Commerce using your existing platform hooks:

- **Tax calculation:** `dw.order.calculateTax` hook

  - Integrates with your tax provider (Avalara, Vertex, etc.)
  - Uses real-time tax rates based on shipping address

- **Shipping calculation:** `dw.order.calculateShipping` hook
  - Uses your configured shipping methods and rates
  - Applies real-time carrier rates if integrated

Make sure these hooks are configured and tested before enabling UCP. See [Technical Audit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-technical-audit.md#hook-inventory) for what to check, including logic that today lives on other SCAPI endpoints.

### Ineligible Products

Some product categories can't check out through Google (subscriptions, personalized goods, age-restricted items, and others). Leave `native_commerce` unset or `false` for those SKUs. See [Google's product restrictions](https://developers.google.com/merchant/ucp/guides/merchant-center#product_restrictions).

### Removing Products from UCP Eligibility

To make specific products unavailable for UCP purchase:

1. Set the `native_commerce` attribute to `false` for those products in your catalog
2. Update your product feed to GMC
3. Products remain discoverable in Google but won't be available for checkout

## End-to-End Testing

End-to-end testing means an allowlisted Google account, signed into Gemini or AI Mode in Search, sees a Buy button on your GMC products and can complete checkout. Getting there has four parts: share checkout credentials so Google can call you, allowlist tester accounts, use live payments for the Buy-button walkthrough, and validate from sandbox up to production.

### Share Checkout API Credentials

Use Google's [MC UCP Checkout API Secrets](https://docs.google.com/forms/d/e/1FAIpQLSfGrPY_F-SsMF6EgwG49k13sRP7sJ0WEp6TWmZ6de8fiNNRQg/viewform) form **after** you are accepted off the waitlist. Google uses the checkout URL and client credentials when an allowlisted user clicks Buy.

| Form field                                        | What to provide                                                                                                                                                                                            |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Merchant Center ID                                | The merchant ID from your Google Merchant Center account                                                                                                                                                   |
| Merchant or partner name                          | Your business name                                                                                                                                                                                         |
| Email of submitter                                | A contact Google can use for follow-up                                                                                                                                                                     |
| Checkout API endpoint (prod)                      | The shopping service endpoint for your production site                                                                                                                                                     |
| Checkout API endpoint (staging or other non-prod) | The shopping service endpoint for the environment you test first                                                                                                                                           |
| What kind of secret(s)                            | **Client credentials**                                                                                                                                                                                     |
| Client ID and client secret                       | The SLAS private client ID and secret for each environment you listed. Create these in [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md). The secret is shown only once when you create the client. |

Copy the checkout API endpoint from the published [business profile](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#business-profile): the `endpoint` on the `dev.ucp.shopping` service. That is the checkout API **base URL** (the host that serves `/checkout-sessions`). Don't submit the `/.well-known/ucp` discovery URL.

As of August 2026, Google does **not** fetch your business profile for checkout. They call the checkout URL you specify on this form, with the client ID and secret you provide. Keep publishing the profile from Business Manager—other platforms and your own validation still use it—but Google's Buy button path is the URL on the form until they move to profile-based discovery.

Tell Google **which environment is live** for testers (sandbox, staging, or production). Google switches that toggle as you move from environment to environment. See [Validate by Environment](#validate-by-environment).

### Allowlist Test Users

Before you test the Buy button in Gemini, add the Google accounts that see it. Do this in addition to the [checkout API secrets form](#share-checkout-api-credentials)—credentials let Google call your APIs; allowlisting controls who sees the button.

Use **personal Google accounts** (`@gmail.com`). Corporate Google accounts are often blocked from UCP, so personal accounts are the reliable path.

Submit testers at [https://sfdc.co/ucp-test-users](https://sfdc.co/ucp-test-users). Allowlisting with Google takes a day or two after you submit, so add testers early—before you need them for an end-to-end walkthrough.

### Live Mode Payments

Google supports **live mode** payment testing only. The end-to-end Buy button flow in Gemini or AI Mode in Search requires live payment credentials on the environment Google is calling (a live Adyen or Stripe account, with live Google Pay). You can't complete that walkthrough with test or sandbox payment credentials.

Headless testing of Checkout Session APIs — Postman or a similar tool — can use test payments. Use that path to validate hooks, tax, shipping, and the session lifecycle before you click Buy on Google's surfaces.

### Validate by Environment

Validate the Buy button in Gemini from the lowest environment up. Don't skip ahead.

1. **Sandbox** — validate the full Gemini walkthrough first.
2. **Staging** — after sandbox passes, validate again on staging.
3. **Production** — after staging passes, run a pre-production go-live check on production.

Google must change their environment toggle and allow lists for you to move from one environment to the next, and again for final go-live. Salesforce can't flip that. When you are ready to progress, tell Google which environment is live (and which tester Gmails apply) using the same channels as [Share Checkout API Credentials](#share-checkout-api-credentials) and [Allowlist Test Users](#allowlist-test-users).

## Get Support

Use the channel that owns the problem:

| Issue                                                                                                 | Where to go                                                                                          |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Merchant Center, product feed, allowlisting, Gemini / AI Mode Buy button, Google's sandbox or go-live | [Google's dedicated UCP support](https://support.google.com/merchants/contact/ucp_dedicated_support) |
| Business Manager UCP settings, checkout APIs, hooks, Salesforce Payments, SLAS                        | Salesforce Support                                                                                   |

Google's intake is for questions that sit on the Google side. Salesforce Support is for the Commerce Cloud integration.

<!-- document id=d8687ce2c58f2d5d1e4c0af0cc4aef7c9e42ce63a3a9f6d1bbbddb0f5d8d211e url=/developer/current/en-us/commerce-cloud/commerce-api/guides/url-encode.md -->

# Encode URL Special Characters

In SCAPI, the comma (,) is used as a value separator and percent sign (%) is used for URL encoding.

These characters are treated as reserved characters and must be additionally URL encoded in UTF-8 when used within the following resource identifiers for SCAPI requests:

- Request path parameters
- Query parameters

for example: `productID`, `categoryID`, and `promotionID`.

## Request Path Parameter Encoding

If a comma (,) or percent sign (%) is contained within resource identifiers in request path parameter values, the values must be additionally URL encoded in UTF-8. The following example shows a request for the `productId` resource identifier: "Flour,1KG":

```sh
`curl "https://{shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/{organizationId}/products/Flour%2C1KG"`
```

When the client submits the request, the request is usually automatically encoded one more time by the HTTP library and sent to SCAPI:

```text
https://{shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/{organizationId}/products/Flour%252C1KG
```

SCAPI decodes the resource identifier in the request:

```text
ProductId -> "Flour,1KG"
```

## Query Parameter Encoding

If a comma (,) or percent sign (%) is contained within resource identifiers in query parameter values, the values must be additionally URL encoded in UTF-8. The following example shows a request for the `productId` resource identifier: "Flour,1KG" and "1%Milk":

```sh
`curl "https://{shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/{organizationId}/products?ids=Flour%2C1KG,1%25Milk`
```

When the client submits the request, the request is usually automatically encoded one more time by the HTTP library and sent to SCAPI:

```text
https://{shortCode}.api.commercecloud.salesforce.com/product/products/v1/organizations/{organizationId}/products?ids=Flour%252C1KG%2C1%2525Milk
```

SCAPI decodes the resource identifier in the request:

```text
ProductIds -> "Flour,1KG"
           -> "1%Milk"
```

**note:** We generally recommend NOT using special characters like commas (,) or percent signs (%) within resource identifiers.

<!-- document id=661a55ffc0cc2a96146be21db04262883ce732f144beec0086bfe1d28bd2fc2b url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-e2e-testing.md -->

# End-to-End Testing with CodeceptJS

Your Storefront Next app includes an end-to-end test suite built with [CodeceptJS](https://codecept.io/) and [Playwright](https://playwright.dev/). Run automated tests against your storefront locally or in a remote environment to verify that user-facing flows work as expected.

## Before You Begin

Configure the storefront app from the project root.

1. Copy `.env.default`, the included environment template, or start from any `.env` file you already have configured.

   ```bash
   cp .env.default .env
   ```

2. Edit `.env` with your B2C Commerce credentials.

## Set Up Your Environment

From the project root, install dependencies.

```bash
pnpm install
```

This step also installs Playwright browsers.

## Configure the Test Environment

Copy the environment template from the `e2e` directory.

```bash
cp e2e/.env.sample e2e/.env
```

This table describes the key variables in `.env`.

| Variable     | Default                 | Description                                               |
| ------------ | ----------------------- | --------------------------------------------------------- |
| `BASE_URL`   | `http://localhost:5173` | Storefront URL                                            |
| `SITE_ID`    | `RefArchGlobal`         | B2C Commerce site ID                                      |
| `SITE_ALIAS` | global                  | URL prefix for multisite routing                          |
| `LOCALE`     | en-GB                   | Locale prefix for multisite routing                       |
| `HEADLESS`   | `false`                 | Run browser headless                                      |
| `VERBOSE`    | `false`                 | Get more debug logging and stack traces during test runs. |

## Run Your First Test

```bash
# Run all tests against a running storefront
pnpm e2e

# Auto-start local dev server and run tests
pnpm e2e --mode=local
```

## Run Tests

Run all commands from the template root.

| Command                       | Description                                    |
| ----------------------------- | ---------------------------------------------- |
| `pnpm e2e`                    | Run all tests                                  |
| `pnpm e2e --mode=local`       | Auto-start local dev server and run tests      |
| `pnpm e2e --mode=remote`      | Run against a remote URL (requires `BASE_URL`) |
| `pnpm e2e --grep "@checkout"` | Filter tests by tag or name                    |
| `pnpm e2e --headed`           | Run tests with the browser visible             |
| `pnpm e2e --ui`               | Open interactive UI mode                       |
| `pnpm e2e --debug`            | Debug with the CodeceptJS inspector            |
| `pnpm report`                 | Open the Allure test report                    |

## Use AI Features

The test suite integrates with [CodeceptJS AI](https://codecept.io/ai/) to provide self-healing tests, an interactive debugging console, and automatic page object generation. AI features are disabled by default. To use them, pass the `--ai` flag.

### Set Up AI Features

1. Get an API key from [console.anthropic.com](https://console.anthropic.com).

2. Add the key to `.env`.

   ```
   ANTHROPIC_API_KEY=sk-ant-...
   ```

3. Run tests with AI enabled.

   ```bash
   pnpm e2e --ai
   ```

### AI Capabilities

- **Self-healing**: Automatically repairs broken locators when tests fail.
- **Interactive console**: Add `pause()` to a test, then describe actions in plain English.
- **Page object generation**: Call `I.askForPageObject()` to read the live document object model (DOM) and generate a page object.

To see AI healing decisions in the console, run:

```bash
DEBUG="codeceptjs:ai" pnpm e2e --ai
```

## Generate Tests with AI Coding Assistants

AI coding assistants such as Cursor and Claude Code can generate complete E2E tests using the `generate-storefront-e2e-test` skill. This is separate from the Anthropic API key used for runtime self-healing—no additional API key is required.

The skill guides the assistant through a structured workflow, from understanding the commerce scenario to producing spec files, page objects, and self-healing recipes.

### Use the Skill

Ask your AI assistant to create an E2E test. Any of these prompts activates the skill.

```
"Create an E2E test for the checkout flow"
"Write a test that validates product search"
"Add E2E coverage for the shopping cart"
```

The assistant:

1. **Clarifies requirements**—asks about scope, device targets, and guest or authenticated flows
2. **Audits existing coverage**—reviews unit tests and Storybook stories to avoid duplication
3. **Proposes a test plan**—lists scenarios, tags, and page objects before writing code
4. **Generates artifacts**—spec files, page objects, flow files, and self-healing recipes
5. **Registers everything**—updates `src/pages/index.ts`, `src/flows/index.ts`, and `helpers/self-healing/recipes.ts`

### Generated Artifacts

This table describes the files the skill produces.

| Artifact        | Location                          | Purpose                                |
| --------------- | --------------------------------- | -------------------------------------- |
| Spec file       | `src/specs/<feature>/*.spec.ts`   | Test scenarios with Chai assertions    |
| Page object     | `src/pages/*.page.ts`             | Reusable element interactions          |
| Flow            | `src/flows/*.flow.ts`             | Multi-page workflows                   |
| Healing recipes | `helpers/self-healing/recipes.ts` | Fallback selectors for AI self-healing |

### Conventions

Generated code follows these conventions.

- Scenarios never call `I.*` directly—all browser interactions live in page objects or flows.
- Chai `expect()` for value assertions, CodeceptJS methods for UI interactions.
- All hardcoded paths wrapped in `buildSitePath()` for multisite support.
- Each scenario is independent and can run in any order.
- Page objects use semantic locators with `.as('Name')` descriptions.

After generation, verify the tests.

```bash
pnpm e2e --grep "@your-tag"
```

## Generate TypeScript Definitions

TypeScript definitions are auto-generated before each test run. To generate them manually for IDE IntelliSense, run:

```bash
pnpm def
```

## Accessibility Testing

The end-to-end test suite includes full-page accessibility scanning using [axe-core](https://github.com/dequelabs/axe-core) via `@axe-core/playwright`. Scans run in a real browser against the running storefront and catch issues that component-level Storybook a11y tests can't detect, such as page composition, routing, layout, and responsive behavior issues.

### How It Works

- **Scope**: WCAG 2.1 AA (`wcag2a`, `wcag2aa`, `wcag21aa` tags)
- **Viewports**: Desktop (1200×900) and mobile (Pixel 7 emulation). `pnpm a11y` runs both passes sequentially via `scripts/run-a11y.ts`, starting with desktop and then enabling mobile with `PLAYWRIGHT_MOBILE=true`.
- **Baseline**: The test suite snapshots violation counts per page per viewport. CI fails only when critical or serious violations increase or a new critical/serious rule appears. Moderate and minor regressions are logged as informational and don't block CI.
- **Retries**: The test suite retries infrastructure failures such as timeouts and navigation errors up to two times via `.retry(2)` on the Feature. The `a11yNoRetry` plugin never retries confirmed a11y regressions (thrown as `A11yBaselineError`) because axe scans are deterministic and re-running a real violation always reproduces it.

### Quick Start

**note:** Start the storefront development server before running scans. From `packages/template-retail-rsc-app`, run `pnpm dev`.

```bash
# Run a11y scans against the running storefront
pnpm a11y

# Generate a Markdown report with ticket-friendly violation details
pnpm a11y:report

# Scan all pages and write existing or known a11y issues as the new baseline.
# Typically useful for gating new a11y issues while the existing ones are being addressed.
pnpm a11y:update-baseline
```

### Console Output

Each scan prints a banner identifying the page, viewport, and WCAG standard.

```
════════════════════════════════════════
  A11Y SCAN: homepage | desktop
  Standard: WCAG 2.1 AA (wcag2a, wcag2aa, wcag21aa)
════════════════════════════════════════
```

The test suite prints the severity legend once at the start of the run. On completion, each scan prints one of these results.

- `✓ PASS: homepage/desktop—5 violations (within baseline)`—scan passed
- `↓ homepage/desktop—violations decreased, run pnpm a11y:update-baseline`—improvement detected
- `ⓘ 2 moderate/minor rules exceeded baseline (not blocking—update with pnpm a11y:update-baseline)`—moderate or minor counts increased; informational only, printed below the PASS line
- Failure: full violation report followed by a summary of new or increased critical/serious rules

### Generate a Markdown Report

`pnpm a11y:report` runs all scans with result collection enabled and writes two files to `a11y-report/`.

- **`report.md`**—Markdown summary table (page × viewport × severity counts) and per-violation detail with rule ID, description, axe-core help URL, and HTML snippets of affected elements. Use this to create accessibility tickets.
- **`report.html`**—Styled HTML version of the same report, intended for CI artifact upload and browser viewing.

`a11y-report/` is gitignored and treated as a generated artifact. Generate it locally when needed.

```bash
pnpm a11y:report
# Writes a11y-report/report.md and a11y-report/report.html
```

### How the Baseline Works

The test suite stores the baseline in `a11y-baseline.json` at the package root. Each entry maps a `<pageKey>/<viewport>` key to a `Record<ruleId, nodeCount>`.

```json
{
  "homepage/desktop": { "color-contrast": 3, "image-alt": 1 },
  "homepage/mobile": { "color-contrast": 2 },
  "login/desktop": {}
}
```

On every test run, the spec compares the current axe output against the baseline.

- **New critical/serious rule** or **more critical/serious violations** than baseline → the test fails
- **New moderate/minor rule** or **more moderate/minor violations** than baseline → the test passes and logs the violation
- **Fewer violations** than baseline → the test passes with a log message suggesting a baseline update

**Ratchet-down workflow**: After fixing a known issue, update the baseline to lock in the improvement.

```bash
pnpm a11y:update-baseline
# Review the diff in a11y-baseline.json, then commit it
git add a11y-baseline.json
git commit -m "chore: ratchet down a11y baseline after fixing color-contrast on homepage"
```

**Initial setup for new pages**: After adding a new page, run `pnpm a11y:update-baseline`. The command creates baseline entries automatically and populates them with current violation counts. Commit the result.

### Run at a Specific Viewport

`pnpm a11y` always runs both viewport passes. To target a single viewport, invoke the test runner directly.

```bash
# Desktop only
tsx src/scripts/cli/test-runner.ts --grep @a11y

# Mobile only (Pixel 7 emulation)
PLAYWRIGHT_MOBILE=true tsx src/scripts/cli/test-runner.ts --grep @a11y
```

**note:** `pnpm e2e run --multiple desktop --grep "@a11y"` doesn't work. CodeceptJS `run-multiple` doesn't forward `--grep` to its workers, so all tests run instead of just the a11y suite.

### Add a New Page

1. Add a `Scenario` to `src/specs/core/accessibility.spec.ts`. Use this pattern as a starting point.

   ```typescript
   Scenario("My New Page accessibility", async () => {
     myPage.navigate();
     await scanAndAssert("my-new-page");
   })
     .tag("@a11y")
     .tag("@my-new-page");
   ```

2. Run `pnpm a11y:update-baseline`. The command creates baseline entries for the new page automatically.

3. Review the diff in `a11y-baseline.json`, then commit it.

### Severity Levels

axe-core reports violations with four impact levels.

| Level      | Meaning                                                                      |
| ---------- | ---------------------------------------------------------------------------- |
| `critical` | Blocks access entirely for users with disabilities                           |
| `serious`  | Creates significant barriers; fix quickly                                    |
| `moderate` | Creates difficulty for users with disabilities. Workarounds sometimes exist. |
| `minor`    | Low impact; fix when convenient                                              |

Severity appears in these places in test output.

- **Scan banner**: Printed before each scan alongside the WCAG standard.
- **Failure summary**: Each failing rule appears inline as `rule-id [impact]: N violations` so you can assess priority at a glance.
- **Full violation report**: Printed above the summary, grouped by impact level with rule descriptions, help URLs, and affected element selectors and HTML snippets.
- **Markdown report**: Summary table and per-rule detail sections with help URLs and HTML snippets for ticket creation.

### Environment Variables

This table describes the environment variables for the a11y suite.

| Variable               | Values | Description                                                                                                                                            |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BASE_URL`             | URL    | Storefront URL to scan. Defaults to `http://localhost:5173`.                                                                                           |
| `PLAYWRIGHT_MOBILE`    | `true` | Enables Pixel 7 emulation. `pnpm a11y` sets this automatically for the mobile pass. Use it directly to run a single mobile pass.                       |
| `A11Y_UPDATE_BASELINE` | `true` | Writes current violation counts to `a11y-baseline.json` at the package root instead of asserting. `pnpm a11y:update-baseline` sets this automatically. |
| `A11Y_COLLECT_RESULTS` | `true` | Writes scan results to `a11y-report/data/` for offline report generation. `pnpm a11y:report` sets this automatically.                                  |

### CI Integration

A11y scans run as a parallel job alongside the core E2E suite on every PR, merge group event, and push to `main` or `release-*` branches. Both jobs share the same MRT deployment, so there's no extra deploy cost.

- **Caller workflow**: `.github/workflows/e2e-core-pr.yml`
- **Reusable runner**: `.github/workflows/e2e-pr-runner.yml`—the `run_a11y` job handles the scan, reporting, and artifact upload.
- **Kill switch**: The `run_a11y` job is gated on the `ENABLE_A11Y_CI` repository variable. Set it to `false` to disable a11y CI globally without modifying any workflow file.
- **Command**: `pnpm a11y:report --no-ai`—runs scans in collect mode and generates both `a11y-report/report.md` and `a11y-report/report.html`.
- **Job summary**: The CI job appends `a11y-report/report.md` to the GitHub Actions job summary after each run, so you can view violation details directly in the Actions UI without downloading anything.
- **HTML report artifact**: The CI job uploads `a11y-report/report.html` as a CI artifact (`a11y-report-<run-id>`) after each run. Download it from the Actions run summary to view violation details in a browser without cloning the branch.

## Troubleshooting

**TypeScript errors about missing page objects**

Regenerate definitions.

```bash
pnpm def
```

**Tests fail with "Element not found"**

Enable AI self-healing.

```bash
pnpm e2e --ai --grep "@failing-test"
```

**Local dev server won't start**

Check that `.env` exists at the project root and contains valid B2C Commerce credentials.

**Port 5173 is already in use**

```bash
lsof -ti:5173 | xargs kill
```

**AI features aren't working**

Verify that `ANTHROPIC_API_KEY` is set in `.env`.

```bash
cat .env | grep ANTHROPIC
```

**Remote tests fail: "BASE_URL required"**

Set `BASE_URL` before running the command.

```bash
BASE_URL=https://your-site.com pnpm e2e --mode=remote
```

<!-- document id=5a5a8c2cda6b400c109bb737ffcc66df005a19f3b4d19297ecf31586c575992d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-end-file-log-ds.md -->

# EndFileLog.ds

Review the EndFileLog.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/***********************************************************
 * Name: EndFileLog.ds
 *
 * Description:
 *  Resets FileLogger to stop writing all logging events to file.
 *  This replaces the FileLogger with a normal logger in the pdict.
 *
 * @input sampleLogger   : Object
 * @output sampleLogger  : Object
 * @output sampleError   : Object
 *
 ***********************************************************/
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");



function execute(pdict: PipelineDictionary): Number {



    var _context: Context = new Context("EndFileLog.ds");
    var _logger: Log = pdict.sampleLogger;

    try {

        if (empty(_logger)) {

            throw new sampleException(_context,
                "No Log instance found. " +
                "Make sure the corresponding 'BeginFileLog' pipelet was set on this pipeline.");
        }

        _logger.debug(_context, "Now stopped logging to file.");

        if (FileLog.prototype.isPrototypeOf(_logger)) {

            // resets logger to the original instance
            pdict.sampleLogger = _logger.getBaseLogger();
        } else {

            // resets logwriter on logger
            _logger.setLogWriter(null);
            pdict.sampleLogger = _logger;
        }
    } catch (e) {

        // Call into error handler
        _logger.error(_context, "Error occurred processing pipelet: " + e.message);

        // wrap error into custom exception
        var exception: sampleException = new sampleException(_context, "Error occured in pipelet", e);
        pdict.sampleError = exception;

        return PIPELET_ERROR;
    }

    return PIPELET_NEXT;
}
```

<!-- document id=dd0033946e9e4100600287deec45f005809ba511e537d3560ae8c78d7cc94ffd url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-adapters.md -->

# Engagement Adapter Pattern

The adapter pattern decouples analytics components from vendor-specific event APIs. Components call a generic interface and the adapter translates those calls into the vendor's API. Storefront Next provides three built-in adapters for analytics event tracking that use Einstein, Active Data, and Data 360 (formerly Data Cloud).

| Adapter         | Purpose                                                      | Config key                       |
| --------------- | ------------------------------------------------------------ | -------------------------------- |
| **Einstein**    | Analytics event tracking (viewProduct, addToCart, and so on) | `engagement.adapters.einstein`   |
| **Active Data** | Analytics event tracking (dwac beacon)                       | `engagement.adapters.activeData` |
| **Data 360**    | Salesforce Data 360 — view/impression events only            | `engagement.adapters.data360`    |

All three implement the `EngagementAdapter` interface and are registered in a shared store.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     Component Layer                         │
│  (PageViewTracker, AddToCartButton, etc.)                   │
└──────────────────────────┬──────────────────────────────────┘
                           │ sendEvent(event)
                           ↓
┌─────────────────────────────────────────────────────────────┐
│                     Adapter Store                           │
│  Map<string, EngagementAdapter>                             │
│  + ensureAdaptersInitialized() (lazy, idempotent)           │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ↓
┌─────────────────────────────────────────────────────────────┐
│              Vendor Implementations                         │
│  createEinsteinAdapter → POST to api.cquotient.com          │
│  createActiveDataAdapter → pixel/beacon requests            │
│  createData360Adapter → sendBeacon to                       │
│    {tenantId}.c360a.salesforce.com                          │
└─────────────────────────────────────────────────────────────┘
```

## File Structure

```
src/lib/adapters/
├── index.ts                        # Re-exports store, types, utils
└── engagement/
    ├── types.ts                    # EngagementAdapter interface, EngagementAdapterConfig
    ├── store.ts                    # addAdapter, getAdapter, getAllAdapters, removeAdapter
    ├── einstein.ts                 # createEinsteinAdapter factory (analytics events only)
    ├── active-data.ts              # createActiveDataAdapter factory
    ├── data360.ts                  # createData360Adapter factory (view/impression events only)
    ├── register.ts                 # initializeEngagementAdapters (reads config, creates + registers)
    ├── initialize.ts               # ensureAdaptersInitialized (idempotent, lazy-loads register.ts)
    ├── einstein-config.ts          # validateEinsteinConfig helper
    ├── data360-config.ts           # Data360Config type + validateData360Config helper
    └── utils.ts                    # hasConsent helper
```

## Adapter Interface

```typescript
// src/lib/adapters/engagement/types.ts
export interface EngagementAdapter extends EventAdapter {
  name: string;
  sendEvent?: (
    event: AnalyticsEvent,
    siteInfo?: EventSiteInfo,
    consentPreferences?: ConsentPreferences,
  ) => Promise<unknown>;
  send?: (url: string, options?: RequestInit) => Promise<Response>;
}
```

## Adapter Store

A `Map<string, EngagementAdapter>` with functional accessors:

```typescript
addAdapter("einstein", adapter); // Register
getAdapter("einstein"); // Retrieve by name
getAllAdapters(); // All registered adapters
removeAdapter("einstein"); // Unregister
```

## Lazy Initialization

Adapter code is dynamically imported to stay out of the initial bundle:

```typescript
// src/lib/adapters/engagement/initialize.ts
export async function ensureAdaptersInitialized(appConfig: AppConfig): Promise<void> {
  if (getAllAdapters().length > 0) return; // Already done
  const { initializeEngagementAdapters } = await import("./register");
  initializeEngagementAdapters(appConfig);
}
```

The dynamic `import()` means that the Einstein, Active Data, and Data 360 implementation modules are code-split into a separate chunk.

## Configuration

Adapters are configured in `config.server.ts` under `engagement.adapters`:

```typescript
engagement: {
    adapters: {
        einstein: {
            enabled: true,
            host: 'https://api.cquotient.com',
            einsteinId: '<your-einstein-id>',
            siteId: '<your-site-id>',
            realm: '<realm>',
            isProduction: false,
            consentCategory: 'analytics',
            eventToggles: { view_product: true, cart_item_add: true, ... },
        },
        activeData: {
            enabled: true,
            host: '<host>',
            siteUUID: '<uuid>',
            consentCategory: 'analytics',
            eventToggles: { view_product: true, cart_item_add: true, ... },
        },
        data360: {
            enabled: true,
            appSourceId: '<your-app-source-id>',
            tenantId: '<your-tenant-id>',
            siteId: '<your-site-id>',
            webStoreId: 'sfnext',           // separates Storefront Next traffic from PWA Kit's in a shared DLO
            consentCategory: 'analytics',
            eventToggles: { view_product: true, view_category: true, ... },
        },
    },
},
```

If an adapter's `enabled` flag is `false`, it isn't registered.

**Data 360 maps only view and impression events** — `view_page`, `view_product`, `view_search`, `view_category`, and `view_recommender`. Cart, checkout, wishlist, and click events have no Data 360 mapping and ship disabled in `eventToggles`.

For how to provision Data 360 and connect your storefront, see [Send Storefront Next Analytics Events to Data 360](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data360.md).

## Testing

### Mocking Adapters in Tests

```typescript
import { addAdapter, removeAdapter } from "@/lib/adapters";

const mockAdapter: EngagementAdapter = {
  name: "mock-einstein",
  sendEvent: vi.fn().mockResolvedValue(undefined),
};

beforeEach(() => addAdapter("einstein", mockAdapter));
afterEach(() => removeAdapter("einstein"));
```

### Testing Initialization

```typescript
import { resetAdaptersInitialization } from "@/lib/adapters/engagement/initialize";

afterEach(() => resetAdaptersInitialization()); // Clear cached promise for clean state
```

## Add an Engagement Adapter

1. Create `src/lib/adapters/engagement/your-adapter.ts` with a factory function returning `EngagementAdapter`.
2. Register it in `src/lib/adapters/engagement/register.ts` inside `initializeEngagementAdapters()`.
3. Add configuration under `engagement.adapters.yourAdapter` in `config.server.ts`.

<!-- document id=11a97dba7d112c5b621127c8f5a2a8682fa76303267fb8ec1f980e3164bfe514 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-instore-pickup.md -->

# Enhance Shopper Experience with Store Locator and In-Store Pickup

With store locator, shoppers find stores near a specific zip code or their current location. With in-store pickup, shoppers choose whether to pick up a product at the store or have it delivered to an address. These features provide flexibility and convenience, boosting in-store sales while meeting diverse shopper needs.

In-store pickup depends on the Shop the Store feature, which enables shoppers to refine search results for a specific store. Shoppers refine search results and category-browse through the In Stock checkbox on the Product Listing Page (PLP). For more information, see [Shop the Store](https://help.salesforce.com/s/articleView?id=cc.b2c_shop_the_store.htm&type=5) in _Salesforce Help_.

Find nearby stores by entering a zip code or by using geolocation.

![Find nearby stores by entering a zip code or by using geolocation](https://developer.salesforce.com/docs/media/sfnext/sfnext-store-locator.png '{"class": "image-md"}')

Filter products by in-store availability at your selected store.
![Filter products by in-store availability at your selected store](https://developer.salesforce.com/docs/media/sfnext/sfnext-bopis.png '{"class": "image-xl"}')

## Default Extensions

Create Storefront Next with the Store Locator and Buy Online Pickup In Store extensions. These extensions are enabled by default when you create Storefront Next in Business Manager or the CLI.

## Configure Stores and Inventory Lists in Business Manager

- Add the countries that you want shoppers to find on your site. See [Store Geolocation Data in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_store_geolocation_data.htm&type=5).
- Enable Shop the Store feature. Add stores and associate an inventory list with each store. See [Enable Shop the Store](https://help.salesforce.com/s/articleView?id=cc.b2c_enable_shop_the_store.htm&type=5) in _Salesforce Help_.
- Enable in-store pickup:
  - In Business Manager, click App Launcher, and then select **Merchant Tools > Ordering > Shipping Methods**.
  - Under Store Pick Up, click **Store Pickup Enabled**.

### Store Locator Constraints

- Returns up to 200 stores at a time.
- Searches for stores within a maximum radius of 100 kilometers. The default unit is kilometers but you can change it to miles in `/src/extensions/store-locator/stores/store-locator-store.ts`.

<!-- document id=a5c1ae8d961e0c3750171bcb9219e1329b08fc3cfc4445e76c3996ea526c47da url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-entitlement-limits.md -->

# Entitlement Data Limits

| Object                              | Limit B2B Except Where Indicated | Store or Org | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------------- | -------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Entitlement Policies                | B2B: 105,000                     | Org          | **Note:** You can associate any number of entitlement policies with a buyer group.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Products per Entitlement Policy     | B2B: 3 million<sup>\*</sup>      | Store        | Because store products can be based on a single entitlement policy. Make sure this limit is consistent with the number of products supported at your store level.                                                                                                                                                                                                                                                                                                                                               |
| Buyer Groups per Entitlement Policy | B2B: 200                         | N/A          | Extending this limit beyond capacity can lead to data scaling issues.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Buyer Entitlements per Product      | B2B: 2,000                       | Store        | B2B: This limit refers to the number of Buyer Groups within which a product can be entitled. Extending this limit beyond recommendation can significantly impede the search service. During search indexing, only the first two thousand buyer groups for a product are included in the index. buyer groups above two thousand are not included. In the context of a search, the buyer groups over two thousand do not return entitlements. Note: This limit is not enforced when loading data into Salesforce. |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce customer support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

Salesforce recommends you keep entitlements data within the scope of the established limits. If you have requirements that exceed these limits, consider the impact on your store and org operations before you request a limit increase. For example:

- Extending buyer entitlements per product can adversely impede search indexing.
- Extending the buyer groups per entitlement policy limit can cause data scaling issues.

Increasing data limits also impacts the comprehensive application of store and org-level data limits. For each entitlement limit extension, measure the additional data the product generates.

- Does the additional data push the related data objects beyond their limits?
- Can you offset a data increase by decreasing data requirements in other store or org functions?

After you assess the impact of a data increase, if you still want to request an increase, contact Support.

<!-- document id=27a89d6f9c2536368cbf7c989fe3606c0e5819df2d2f45eaf34069a57e4445f5 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/environment-variables.md -->

# Environment Variables

Environment variables allow you to add variables into the application process running in an environment, without having to make code changes. Environment variables are stored securely, making them ideal for use cases such as:

- API keys for third-party integrations
- Feature flags for application logic
- Configuration that differs between environments or that might not be secret

**note:** Environment variables are only accessible in the app server. They can't modify the behavior of edge services including proxies and edge functions.

## Prerequisites

You must have a developer or admin role on the project for which you’re managing environment variables. If you don't have access, ask someone in a Managed Runtime admin role to help you with that.

## Tutorials

Follow these tutorials to set environment variables then implement code in your PWA Kit site to use the variables. You can customize the code according to your specific requirements. The tutorials show you how to:

- [Access Protected Resources with Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/env-var-3rd-party-CMS.md)
- [Use Environment Variables in React.js](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/env-var-feature-access.md)

We recommend testing the steps on your local machine, then in a non-production environment before deploying your changes to production. For more guidance, see [Best Practices](#best-practices), [Troubleshoot Environment Variables](#troubleshoot-environment-variables), and [Debugging Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debugging-locally).

## Manage Environment Variables

Environment variables:

- Can be managed using the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md#use-the-managed-runtime-api) or [Runtime Admin](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md#use-runtime-admin)
- Are accessed in Node.js using [`process.env`](https://nodejs.org/docs/latest-v18.x/api/process.html#processenv)

When you introduce a new environment variable, first set it via API or Runtime Admin. Wait until redeploy completes and then deploy a new bundle that uses it.

### Use the Managed Runtime API

**Set, Update, and Unset Environment Variables**

Use [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update):

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$MOBIFY_API_KEY"

npx @salesforce/b2c-cli mrt env var set \
  'API_KEY=b3Blbi1zZXNhbWU=' \
  'STOREFRONT_CONFIG={"showBuyNowButton": false}' \
  SLAS_CLIENT_ID=da422690-7800-41d1-8ee4-3ce983961078 \
  --project "$PROJECT" --environment "$ENVIRONMENT"
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
  --request 'PATCH' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $MOBIFY_API_KEY" \
  --data '{
    "API_KEY": {"value": "b3Blbi1zZXNhbWU="},
    "STOREFRONT_CONFIG": {"value": "{\"showBuyNowButton\": false}"},
    "SLAS_CLIENT_ID": {"value": "da422690-7800-41d1-8ee4-3ce983961078"}
}'
```

To unset an existing environment variable, set its value to `null`.

Modifying environment variables redeploys the environment. The updated values are available when the deploy completes.

**Get all Environment Variables**

Use [projects_target_env_var_list](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_list):

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
  --header "Authorization: Bearer $MOBIFY_API_KEY" \
  --header 'Accept: application/json'
```

### Use Runtime Admin

To create, update, remove, or view environment variables:

1. Log into [Runtime Admin](https://runtime.commercecloud.com). To get access to Runtime Admin, see [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md).
2. Go to a project’s Overview page.
3. Click the name of the environment for which you want to manage environment variables.
4. Click **Environment Variables** in the left navigation.

## Best Practices

- Choose environment variable names that make sense for your app. Use descriptive names: Choose clear and concise names for your environment variables to make them easily understandable for your team.
- Avoid hardcoding sensitive information like API keys in your code. Use environment variables to keep them secure.
- Don't pass environment variables into data that will be serialized to the page. Consider adding a test to make sure you're not leaking environment variable data.
- Don't return environment variables from `getProps` or react-query hooks.
- Use environment variables only server-side. By default, environment variables aren’t exposed client-side. You can choose to expose them client-side (for example, in your configuration file), but make sure that exposing the values complies with your security practices.
- Test your environment variables on your local machine, then in a non-production environment before deploying them to production. This helps to ensure that you can quickly resolve issues locally, then simulate site behavior, validate functionality, and do any user acceptance testing before deploying to production.
- Include error handling in your code that uses environment variables to prevent failures due to undefined environment variables.
- Control access to the environment variables to prevent unauthorized modifications.
- Document the purpose and configuration of each environment variable. This helps in onboarding new developers and troubleshooting issues.

## Constraints

The usage of environment variables is subject to the following constraints:

- Each environment has a limit of 100 environment variables.
- Environment variable names can contain only alphanumeric characters, underscores ( \_ ), and dashes ( - ).
- Environment variable names must be 512 characters or less, and cannot start with reserved prefixes: `AWS`, `MRT`, `X_MRT`, `MOBIFY`, `X_MOBIFY`, `SSR_PROXY`, `NODE`.
- Environment variable names cannot use any reserved names: `BUNDLE_ID`, `DEPLOY_ID`, `DEPLOY_TARGET`, `EXTERNAL_DOMAIN_NAME`, `HANDLER`, `LAMBDA_RUNTIME_DIR`, `LAMBDA_TASK_ROOT`, `NODE_ENV`, `REDIRECT_BUCKET`, `REDIRECT_KEY`, `REDIRECT_UPDATE`, `REMOTE`, `X_AMZN_TRACE_ID`.
- Environment variable values must be strings. To store complex values, encode JSON into a string.
- The maximum size of the values of environment variables set for an environment is 32 KB.

## Troubleshoot Environment Variables

This section provides suggested solutions for common errors that you might encounter while using environment variables.

### Environment Variable Isn’t Set

Your code throws an `Error` stating that a variable is missing.

**Cause:** The environment variable that the code calls isn’t set.

**Suggested Solution:** Call the [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update) API endpoint to set the applicable environment variable.

### Incorrect Environment Variable Name

Your code logs an error message stating that the environment variable wasn’t found.

**Cause:** The code couldn’t find the environment variable because there’s a typo in the code or an incorrect environment variable name is used.

**Suggested Solution:** Confirm that you spelled the environment variable name correctly in your code and you used the desired environment variable name. Check the environment variable name by calling the [projects_target_env_var_list](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_list) API endpoint to see the full list of variables that are set.

### Unsupported Environment Variable Name

Your API call to set an environment variable fails.

**Cause:** The environment variable name might not comply with the [constraints](#constraints). For example, the size of the value of an environment variable is over 32 KB.

**Suggested Solution:** Confirm that your environment variable complies with the [constraints](#constraints).

### Invalid API Key Format

Authentication errors occur when you execute code that involves using an API key.

**Cause:** The API key that you used when you set the environment variable is not in the expected format or is missing.

**Suggested Solution:** Confirm that the API key stored by an environment variable is correct. If needed, call the [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update) API endpoint to correct the API key.

### Invalid URL for an API Endpoint

A `fetch` request fails with a network error.

**Cause:** A URL for any API endpoint called in your code might not have been correctly defined or is invalid. For example, the URL for a content management system (CMS) endpoint is incorrect.

**Suggested Solution:** Confirm that any URLs for API endpoints in your code are correct.

<!-- document id=e55f8333a6edb79938f3133401dd70f9ed774df1c03ca7cbbc287da713659ecb url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-environment-vars.md -->

# Environment Variables

Use environment variables to manage configuration values for your Storefront Next storefront without making code changes. They're stored securely outside your codebase, making them ideal for API keys for third-party integrations, secrets, feature flags for application logic, and configuration that differs between environments such as development, staging, and production. Environment variables are accessible in your app server code only and aren't available to edge services. On Managed Runtime, environment variables are injected into the server process at startup and are accessible to server-side code through `process.env`.

## Prerequisites

- You must have a developer or admin role on the project for which you're managing environment variables. If you don't have access, ask a Managed Runtime admin for access.
- For the Developer Workspace (Beta), you must have the "Storefront Environment Variables" permission for a specific storefront with the appropriate read, write, and delete rights.

## Environment Variable Types

Storefront Next uses a naming convention to control where a variable is available.

- `PUBLIC__` prefix: Variables with this prefix are safe to expose to the browser. They're automatically merged into the app configuration at run time and available in both server and client code via `getConfig()` and `useConfig()`. Use these for client IDs, feature flags, public API endpoints, and other non-sensitive values.
- No prefix: Variables without the `PUBLIC__` prefix are server-only. They're never bundled into client JavaScript. Use these for secrets, API credentials, and private tokens. Read them directly from `process.env` in server-side code such as loaders, actions, and middleware.

## The `PUBLIC__` Path Syntax

Use the double underscore (`__`) in `PUBLIC__` variable names to target nested configuration paths. This path syntax maps directly to dot notation in your config object.

For example, this environment variable:

```Bash
PUBLIC__app__myFeature__apiEndpoint=https://api.example.com
```

Maps to this config path:

```Bash
config.app.myFeature.apiEndpoint
```

Values are automatically parsed to the correct type:

```Bash
PUBLIC__app__myFeature__count=42 # → number
PUBLIC__app__myFeature__enabled=true # → boolean
PUBLIC__app__myFeature__items=["a","b"] # → array
PUBLIC__app__myFeature__data='{"x":1}' # → object
PUBLIC__app__myFeature__name=hello # → string
```

For complex nested values, set an entire object at once using JSON:

```Bash
PUBLIC__app__pages__cart='{"quantityUpdateDebounce":1000,"maxQuantityPerItem":500}'
```

When you set environment variables in Runtime Admin, use single-line JSON without surrounding quotes.

## Manage Environment Variables in Business Manager (Beta)

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Administration > Sites > Storefronts**, and then click your storefront.
2. Depending on which environment you want to access, under Primary Environment or Additional Environments, click the dropdown arrow and select **Environment Settings**.
3. Click **Environment Variables**.
4. Add, edit, or delete an environment variable on this page.

## Manage Environment Variables in Runtime Admin

Manage environment variables in the UI in Runtime Admin.

### Use Runtime Admin

To create, update, remove, or view environment variables:

1. If you created your storefront in Business Manager, access your environment variables from the storefront page.

   a. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Administration > Sites > Storefronts**, and then click your storefront.

   b. In the storefront detail page, click the environment, and then click **Manage** next to **Environment Variables**.
   You're redirected to the Environment Variables page in Managed Runtime in a new tab.

2. Alternatively, access your storefront from Managed Runtime.

   a. Log in to [Runtime Admin](https://runtime.commercecloud.com).

   b. Go to a project’s Overview page.

   c. Click the name of the environment.

   d. Click **Environment Variables** in the left navigation.

When you add a new environment variable, wait for the redeploy of the bundle to complete, and then deploy a new bundle that uses the new variable.

**note:** Also, you can manage environment variables via the CLI or API. See [Automate Environment Variable Management with the CLI or API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-cli.md).

## Manage Environment Variables in Business Manager (Beta)

In the Developer Workspace (Beta), access and managed environment variables from the Storefront Settings page.

### View and Manage Environment Variables

1. In Business Manager, go to **Administration > Sites > Storefronts > _Your Storefront_**.
2. Next to an environment, click the dropdown arrow and select **Environment Settings**.
3. Click **Environment Variables**.

The page lists all variables defined for the environment, including the variable name and whether the value is visible or masked.

To add an environment variable from the Environment Variables page, click **New Environment Variable**. To edit or delete an environment variable, select it and then update or delete it.

**warning:** Deleting an environment variable takes effect on the next deployment. If your storefront code references the deleted variable, the behavior at run time depends on how your code handles a missing value.

## Best Practices

- Choose clear, descriptive names for your environment variables.
- Avoid hardcoding sensitive information such as API keys in your code. Use environment variables to keep them secure.
- Don't pass environment variables into data that will be serialized to the page. Consider adding a test to make sure you're not leaking environment variable data.
- Never store secrets or private keys in `PUBLIC__` variables. The're exposed to the browser.
- Read server-only secrets directly from process.env. Never pass them through the config system.
- Test variable changes locally and in a non-production environment before applying them to production. Testing in stages helps resolve issues early, simulate site behavior, validate functionality, and run user acceptance testing before deploying to production.
- Add error handling in your code for cases where a variable might be undefined.
- Don't return environment variables from `loader` functions or react-query hooks.
- Use environment variables only server-side. By default, environment variables aren’t exposed client-side. To expose them client-side (for example, in your configuration file), make sure that exposing the values complies with your security practices.
- Control access to the environment variables to prevent unauthorized modifications.
- Document the purpose and configuration of each environment variable. This helps in onboarding new developers and troubleshooting issues.
- Restart your dev server after changing `.env` files. Environment variables load at startup.

## Constraints

Environment variables are subject to these constraints.

- Each environment has a limit of 100 environment variables.
- Environment variable names can contain only alphanumeric characters, underscores ( \_ ), and dashes ( - ).
- Environment variable names must be 512 characters or less, and cannot start with reserved prefixes: `AWS`, `MRT`, `X_MRT`, `MOBIFY`, `X_MOBIFY`, `SSR_PROXY`, `NODE`.
- Environment variable names cannot use any reserved names: `BUNDLE_ID`, `DEPLOY_ID`, `DEPLOY_TARGET`, `EXTERNAL_DOMAIN_NAME`, `HANDLER`, `LAMBDA_RUNTIME_DIR`, `LAMBDA_TASK_ROOT`, `NODE_ENV`, `REDIRECT_BUCKET`, `REDIRECT_KEY`, `REDIRECT_UPDATE`, `REMOTE`, `X_AMZN_TRACE_ID`.
- Environment variable values must be strings. To store complex values, encode JSON into a string.
- The maximum size of the values of environment variables set for an environment is 32 KB.
- Paths used in `PUBLIC__` variable names must already exist in `config.server.ts`. Variables that reference undefined paths are rejected at startup.

## See Also

- [Troubleshoot Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-env-var-troubleshoot.md)
- [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md)

<!-- document id=8086f51f9cbbeac56d5f0c2ac752c20ccae442dabbb714d995727a62c463415a url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/environments.md -->

Environments

# Environments

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/storefront/environments-oas-v1-public.yaml)

## API Overview

The Environments API provides B2C Commerce (SCAPI)-native access to Managed Runtime (MRT) environment data for Storefront Next and PWA Kit storefronts. It replaces the Business Manager UI and partial data API setup flow. The B2C CLI and other tooling can use it for end-to-end automation.

*   **Environment tasks** — create, retrieve, list, update (display name and server-side rendering configuration), delete environments belonging to a storefront, and clone or promote them.
*   **Cache invalidations** — trigger a CDN cache invalidation on an environment by path prefix.
*   **Environment variables** — read and merge-update the customer-defined key/value configuration on an environment.
*   **Access control headers** — create, read, and delete header-based access control rules on an environment.
*   **Redirects** — create, list, read, update, delete, and clone URL redirect rules on an environment.

Environment creation and deletion are asynchronous: the API returns immediately with the resource in a non-terminal status, and callers poll the resource by ID to track progress.

### Authentication & Authorization

Requests are authenticated with Account Manager OAuth 2.0 bearer tokens (`AmOAuth2`). Access is governed by the Environments API scopes: `sfcc.storefront.environments` grants read-only access, and `sfcc.storefront.environments.rw` grants read and write access. Read operations (`GET`) accept either scope. Write operations (`POST`, `PATCH`, `PUT`, `DELETE`) require the `.rw` variant.

### Idempotency

*   `POST .../environments`: This operation isn't idempotent, in effect or response. `environmentId` is server-generated, so there is no client-supplied key to reject a retry against. Each call creates a new, distinct environment.
*   `PATCH .../environments/{environmentId}`: This operation is idempotent. It is a partial update — only the supplied fields are changed. Repeating an identical request produces the same resulting state.
*   `DELETE .../environments/{environmentId}`: This operation is idempotent in effect, but not in response code. The first call queues deletion (202). Once deletion completes, retrying returns 404. Deleting an environment that is still `building` or `deleting` returns 409 (`EnvironmentBusyErrorResponse`) rather than queuing a duplicate deletion.
*   `PUT .../environments/{environmentId}/primary`: This operation is idempotent. Setting an already-primary environment as primary again has no effect and returns 200.

### Use Cases

*   Provision a storefront's environments.
*   Clone an existing environment to stand up a new one with matching configuration.
*   Poll environment status during asynchronous provisioning or teardown.
*   Promote an environment to be the storefront's primary environment.
*   Decommission environments belonging to a storefront.
*   Purge stale content from a storefront's CDN after a release.
*   Manage environment variables, access control headers, and redirects as part of storefront development and administration.

**Version:** 1.0.5

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/storefront/environments/v1`
    *   `shortCode (default 123456gf)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.storefront.environments: Read-only access to the Environments API.
    *   Scope sfcc.storefront.environments.rw: Read and write access to the Environments API.

## Operations

### GET Get environments for a storefront.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments`

Operation ID: `getEnvironmentsForStorefront`. Security: AmOAuth2 (sfcc.storefront.environments, sfcc.storefront.environments.rw).

Retrieves the list of environments belonging to the specified storefront, ordered by creationDate in ascending order.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** List of environments successfully retrieved.
    
    Media type: `application/json`. Schema: `EnvironmentResult`.
    
    _Example: EnvironmentListSuccess_ Successful environment list result
    
    Example of a successful response returning the list of environments for a storefront.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 1,
      "data": [
        {
          "environmentId": "production-a1b2c3d4",
          "displayName": "Production",
          "status": "ready",
          "isPrimary": true,
          "subdomain": "production",
          "mrtOrigin": "https://production-my-storefront.exp-delivery.com",
          "defaultEcdnHostname": "marketstreetb82739d375a9270f.zzzz-001.my.cc.salesforce.com",
          "creationDate": "2026-04-08T21:47:28.188965Z",
          "lastModified": "2026-04-08T21:47:31.307595Z"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested storefront.
    
    Media type: `application/problem+json`. Schema: `StorefrontNotFoundErrorResponse`.
    
    _Example: StorefrontNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-not-found",
      "detail": "We couldn't find storefront my-storefront-a1b2c3.",
      "title": "Storefront Not Found"
    }
    ```
    

### POST Create an environment for a storefront.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/environments`

Operation ID: `createEnvironmentForStorefront`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Queues creation of a new environment for the specified storefront. Returns immediately with the environment resource in the building status. Poll the environment by ID to track provisioning progress.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

#### Request body (required)

Media type: `application/json`. Schema: `EnvironmentCreateRequest`.

_Example: CreateEnvironment_ Create an environment

Create a new environment for a storefront.

```
{
  "displayName": "Production"
}
```

#### Responses

*   **202** Environment creation successfully queued.
    
    Media type: `application/json`. Schema: `Environment`.
    
    _Example: EnvironmentCreatedSuccess_ Successful environment creation
    
    Example of a successful response when a new environment is queued for creation (202 Accepted).
    
    ```
    {
      "environmentId": "production-a1b2c3d4",
      "displayName": "Production",
      "status": "building",
      "isPrimary": true,
      "subdomain": null,
      "mrtOrigin": null,
      "defaultEcdnHostname": null,
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-08T21:47:28.188965Z"
    }
    ```
    
*   **400** Bad Request. The environment creation request body is invalid.
    
    Media type: `application/problem+json`. Schema: `InvalidEnvironmentCreateRequestErrorResponse`.
    
    _Example: InvalidEnvironmentCreateRequestErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-environment-create-request",
      "detail": "The environment creation request body is invalid. A valid displayName is required.",
      "title": "Invalid Environment Create Request"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested storefront.
    
    Media type: `application/problem+json`. Schema: `StorefrontNotFoundErrorResponse`.
    
    _Example StorefrontNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments 404 response._
    

### POST Clone an environment for a storefront.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/clone`

Operation ID: `cloneEnvironmentForStorefront`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Queues creation of a new environment for the specified storefront by cloning an existing environment. Returns immediately with the environment resource in the building status. Poll the environment by ID to track provisioning progress. The clone always starts as a non-primary environment.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

#### Request body (required)

Media type: `application/json`. Schema: `EnvironmentCloneRequest`.

_Example: CloneEnvironment_ Clone an environment

Create a new environment by cloning an existing one.

```
{
  "sourceEnvironmentId": "production-a1b2c3d4",
  "displayName": "Production (EU)",
  "cloneEnvironmentVariables": true,
  "cloneRedirects": true
}
```

#### Responses

*   **202** Environment clone successfully queued.
    
    Media type: `application/json`. Schema: `Environment`.
    
    _Example: EnvironmentCloneAcceptedSuccess_ Successful environment clone
    
    Example of a successful response when a new environment is queued for creation via clone (202 Accepted).
    
    ```
    {
      "environmentId": "prod-eu-f9e8d7c6",
      "displayName": "Production (EU)",
      "status": "building",
      "isPrimary": false,
      "subdomain": null,
      "mrtOrigin": null,
      "defaultEcdnHostname": null,
      "creationDate": "2026-04-09T09:45:00.000000Z",
      "lastModified": "2026-04-09T09:45:00.000000Z"
    }
    ```
    
*   **400** Bad Request. The environment clone request body is invalid.
    
    Media type: `application/problem+json`. Schema: `InvalidEnvironmentCloneRequestErrorResponse`.
    
    _Example: InvalidEnvironmentCloneRequestErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-environment-clone-request",
      "detail": "The environment clone request body is invalid. A valid sourceEnvironmentId and displayName are required.",
      "title": "Invalid Environment Clone Request"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the storefront or the source environment specified in the clone request.
    
    Media type: `application/problem+json`. Schema: `StorefrontNotFoundErrorResponse | SourceEnvironmentNotFoundErrorResponse`.
    
    One of: `StorefrontNotFoundErrorResponse`, `SourceEnvironmentNotFoundErrorResponse`.
    
    _Example StorefrontNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments 404 response._
    
    _Example: SourceEnvironmentNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/source-environment-not-found",
      "detail": "We couldn't find source environment production-a1b2c3d4 for storefront my-storefront-a1b2c3.",
      "title": "Source Environment Not Found"
    }
    ```
    

### GET Get an environment by ID.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}`

Operation ID: `getEnvironmentById`. Security: AmOAuth2 (sfcc.storefront.environments, sfcc.storefront.environments.rw).

Retrieves the details of a specific environment, including its current status.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Responses

*   **200** Environment successfully retrieved.
    
    Media type: `application/json`. Schema: `Environment`.
    
    _Example: EnvironmentSuccess_ Successful environment retrieval
    
    Example of a successful response returning a single environment.
    
    ```
    {
      "environmentId": "production-a1b2c3d4",
      "displayName": "Production",
      "status": "ready",
      "isPrimary": true,
      "subdomain": "production",
      "mrtOrigin": "https://production-my-storefront.exp-delivery.com",
      "defaultEcdnHostname": "marketstreetb82739d375a9270f.zzzz-001.my.cc.salesforce.com",
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-08T21:47:31.307595Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example: EnvironmentNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-not-found",
      "detail": "We couldn't find environment production-a1b2c3d4 for storefront my-storefront-a1b2c3.",
      "title": "Environment Not Found"
    }
    ```
    

### DELETE Delete an environment.

`DELETE /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}`

Operation ID: `deleteEnvironment`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Queues deletion of the environment. Returns immediately with the environment resource in the deleting status. Poll the environment by ID to track deletion progress.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Responses

*   **202** Environment deletion successfully queued.
    
    Media type: `application/json`. Schema: `Environment`.
    
    _Example: EnvironmentDeleteAcceptedSuccess_ Successful environment deletion request
    
    Example of a successful response when an environment is queued for deletion (202 Accepted).
    
    ```
    {
      "environmentId": "production-a1b2c3d4",
      "displayName": "Production",
      "status": "deleting",
      "isPrimary": true,
      "subdomain": "production",
      "mrtOrigin": "https://production-my-storefront.exp-delivery.com",
      "defaultEcdnHostname": "marketstreetb82739d375a9270f.zzzz-001.my.cc.salesforce.com",
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-09T09:30:00.000000Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    
*   **409** We couldn't delete the environment because it is currently building or already being deleted.
    
    Media type: `application/problem+json`. Schema: `EnvironmentBusyErrorResponse`.
    
    _Example: EnvironmentBusyErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-busy",
      "detail": "Environment 'production-a1b2c3d4' can't be deleted while it is 'building'.",
      "title": "Environment Busy"
    }
    ```
    

### PATCH Update an environment.

`PATCH /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}`

Operation ID: `updateEnvironment`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Partially updates the specified environment. Only the supplied fields are changed; at least one field must be provided.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Request body (required)

Media type: `application/json`. Schema: `EnvironmentUpdateRequest`.

_Example: UpdateEnvironment_ Update an environment

Update an environment's display name and server-side rendering configuration.

```
{
  "displayName": "Production (EU)",
  "ssrRegion": "eu_west_1",
  "ssrArchitecture": "arm64",
  "allowCookies": true,
  "preserveProxyUserAgent": false,
  "logLevel": "warn"
}
```

#### Responses

*   **200** Environment successfully updated.
    
    Media type: `application/json`. Schema: `Environment`.
    
    _Example: EnvironmentUpdatedSuccess_ Successful environment update
    
    Example of a successful response after updating an environment.
    
    ```
    {
      "environmentId": "production-a1b2c3d4",
      "displayName": "Production (EU)",
      "status": "ready",
      "isPrimary": true,
      "subdomain": "production",
      "mrtOrigin": "https://production-my-storefront.exp-delivery.com",
      "defaultEcdnHostname": "marketstreetb82739d375a9270f.zzzz-001.my.cc.salesforce.com",
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-09T09:00:00.000000Z",
      "ssrRegion": "eu_west_1",
      "ssrArchitecture": "arm64",
      "ssrExternalHostname": "www.customer.com",
      "ssrExternalDomain": "customer.com",
      "ssrWhitelistedIps": null,
      "ssrProxyConfigs": null,
      "isProduction": true,
      "allowCookies": true,
      "preserveProxyUserAgent": false,
      "enableSourceMaps": false,
      "logLevel": "warn",
      "distributedTracing": false,
      "distributedTracingSamplingRate": 0.1,
      "certificateId": 42
    }
    ```
    
*   **400** Bad Request. The environment update request body is invalid — for example a disabled ssrRegion, an ssrArchitecture that isn't enabled or is past end-of-life, an invalid certificateId, an SSR networking field that must be changed in Business Manager, or invalid ssrProxyConfigs (too many proxies, duplicate paths, or an invalid host).
    
    Media type: `application/problem+json`. Schema: `InvalidEnvironmentUpdateRequestErrorResponse | EnvironmentSsrRegionDisabledErrorResponse | EnvironmentSsrArchitectureNotEnabledErrorResponse | EnvironmentSsrArchitectureX86EndOfLifeErrorResponse | EnvironmentCertificateInvalidErrorResponse | EnvironmentSsrFieldBusinessManagerErrorResponse | EnvironmentInvalidProxyConfigErrorResponse`.
    
    One of: `InvalidEnvironmentUpdateRequestErrorResponse`, `EnvironmentSsrRegionDisabledErrorResponse`, `EnvironmentSsrArchitectureNotEnabledErrorResponse`, `EnvironmentSsrArchitectureX86EndOfLifeErrorResponse`, `EnvironmentCertificateInvalidErrorResponse`, `EnvironmentSsrFieldBusinessManagerErrorResponse`, `EnvironmentInvalidProxyConfigErrorResponse`.
    
    _Example: InvalidEnvironmentUpdateRequestErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-environment-update-request",
      "detail": "The environment update request body is invalid.",
      "title": "Invalid Environment Update Request"
    }
    ```
    
    _Example: EnvironmentSsrRegionDisabledErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-ssr-region-disabled",
      "detail": "SSR region 'eu_south_1' is temporarily disabled. Choose a different region.",
      "title": "Environment Ssr Region Disabled"
    }
    ```
    
    _Example: EnvironmentSsrArchitectureNotEnabledErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-ssr-architecture-not-enabled",
      "detail": "The Server-Side Rendering architecture configuration isn't enabled for this organization.",
      "title": "Environment Ssr Architecture Not Enabled"
    }
    ```
    
    _Example: EnvironmentSsrArchitectureX86EndOfLifeErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-ssr-architecture-x86-end-of-life",
      "detail": "x86 is past end-of-life and can no longer be selected. Use arm64.",
      "title": "Environment Ssr Architecture X86 End Of Life"
    }
    ```
    
    _Example: EnvironmentCertificateInvalidErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-certificate-invalid",
      "detail": "The supplied certificateId is invalid for this environment.",
      "title": "Environment Certificate Invalid"
    }
    ```
    
    _Example: EnvironmentSsrFieldBusinessManagerErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-ssr-field-business-manager",
      "detail": "Updates to ssrExternalHostname when the environment uses eCDN must be done in Business Manager.",
      "title": "Environment Ssr Field Business Manager"
    }
    ```
    
    _Example: EnvironmentInvalidProxyConfigErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-invalid-proxy-config",
      "detail": "The ssrProxyConfigs are invalid: The max number of proxies allowed is 8, but 9 given.",
      "title": "Environment Invalid Proxy Config"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. The requested environment update is not permitted.
    
    Media type: `application/problem+json`. Schema: `EnvironmentUpdateForbiddenErrorResponse`.
    
    _Example: EnvironmentUpdateForbiddenErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-update-forbidden",
      "detail": "The requested environment update is not permitted.",
      "title": "Environment Update Forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

### PUT Set an environment as the storefront's primary environment.

`PUT /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/primary`

Operation ID: `setPrimaryEnvironment`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Marks the specified environment as the storefront's primary environment. The environment must have a status of ready or build\_failed. Idempotent — setting an already-primary environment as primary again has no effect.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Responses

*   **200** Environment successfully set as primary.
    
    Media type: `application/json`. Schema: `Environment`.
    
    _Example: EnvironmentSetPrimarySuccess_ Successful primary environment update
    
    Example of a successful response after setting an environment as the storefront's primary environment.
    
    ```
    {
      "environmentId": "staging-e5f6a7b8",
      "displayName": "Staging",
      "status": "ready",
      "isPrimary": true,
      "subdomain": "staging",
      "mrtOrigin": "https://staging-my-storefront.exp-delivery.com",
      "defaultEcdnHostname": "marketstreet4c9b1e7f2a6d3081.zzzz-002.my.cc.salesforce.com",
      "creationDate": "2026-04-09T08:00:00.000000Z",
      "lastModified": "2026-08-20T09:15:00.000000Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    
*   **409** We couldn't make the environment primary because of its current status.
    
    Media type: `application/problem+json`. Schema: `PrimaryEnvironmentInvalidStatusErrorResponse`.
    
    _Example: PrimaryEnvironmentInvalidStatusErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/primary-environment-invalid-status",
      "detail": "Environment 'production-a1b2c3d4' can't be made primary while it is 'building'.",
      "title": "Primary Environment Invalid Status"
    }
    ```
    

### POST Trigger a cache invalidation.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/cache-invalidations`

Operation ID: `createCacheInvalidation`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Triggers a CDN cache invalidation on the environment for the supplied path prefix. Invalidation is always a wildcard operation — every cached path beginning with the prefix is cleared. The request is fire-and-forget: it returns `202 Accepted` with an empty body and no invalidation id to poll, and the invalidation itself is performed asynchronously. The environment must have an SSR bundle deployed.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Request body (required)

Media type: `application/json`. Schema: `CacheInvalidationRequest`.

_Example: CacheInvalidation_ Trigger a cache invalidation

Invalidate every cached path beginning with `/products/` on the CDN.

```
{
  "pattern": "/products/*"
}
```

#### Responses

*   **202** Cache invalidation accepted. The invalidation is processed asynchronously; no body is returned.
*   **400** Bad Request. The `pattern` is missing or does not start with `/`, or no SSR bundle is deployed to the environment.
    
    Media type: `application/problem+json`. Schema: `CacheInvalidationPatternInvalidErrorResponse | CacheInvalidationNoBundleErrorResponse`.
    
    One of: `CacheInvalidationPatternInvalidErrorResponse`, `CacheInvalidationNoBundleErrorResponse`.
    
    _Example: CacheInvalidationPatternInvalidErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/cache-invalidation-pattern-invalid",
      "detail": "The invalidation pattern is missing or does not start with '/'.",
      "title": "Cache Invalidation Pattern Invalid"
    }
    ```
    
    _Example: CacheInvalidationNoBundleErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/cache-invalidation-no-bundle",
      "detail": "No SSR bundle is deployed to this environment, so there is nothing to invalidate.",
      "title": "Cache Invalidation No Bundle"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    
*   **429** Too Many Requests. The cache invalidation was throttled by the backend rate limits (`CacheInvalidationsPerHour` / `CacheInvalidationsPer5Minutes`). Retry later.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CacheInvalidationThrottled_ Cache invalidation throttled
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "The cache invalidation rate limit has been exceeded for this environment. Retry later."
    }
    ```
    

### GET Get environment variables.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/environment-variables`

Operation ID: `getEnvironmentVariables`. Security: AmOAuth2 (sfcc.storefront.environments, sfcc.storefront.environments.rw).

Retrieves the complete set of environment variables for the environment, as a map keyed by variable name. Values are masked. This is a singleton resource — one set per environment — and is not a paginated collection.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Responses

*   **200** Environment variables successfully retrieved.
    
    Media type: `application/json`. Schema: `EnvironmentVariables`.
    
    _Example: EnvironmentVariablesSuccess_ Successful environment variables retrieval
    
    Example of a successful response returning the full set of environment variables, keyed by name, with masked values.
    
    ```
    {
      "PAYMENT_GATEWAY_API_KEY": {
        "value": "****e5f6",
        "createdBy": "jane.doe@example.com",
        "creationDate": "2026-08-24T09:23:28.872916Z",
        "lastModified": "2026-08-24T10:15:02.111000Z",
        "lastModifiedBy": "john.doe@example.com",
        "publishingStatus": "completed"
      },
      "LOG_LEVEL": {
        "value": "****info",
        "createdBy": "jane.doe@example.com",
        "creationDate": "2026-08-20T08:00:00.000000Z",
        "lastModified": "2026-08-20T08:00:00.000000Z",
        "lastModifiedBy": "jane.doe@example.com",
        "publishingStatus": "pending"
      }
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

### PATCH Update environment variables.

`PATCH /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/environment-variables`

Operation ID: `updateEnvironmentVariables`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Merge-updates the environment variables. Keys present in the payload are created or replaced; a key whose value is `null` is deleted; keys omitted from the payload are preserved. Returns `204 No Content` on success.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Request body (required)

Media type: `application/json`. Schema: `EnvironmentVariablesUpdateRequest`.

_Example: EnvironmentVariablesUpdate_ Merge-update environment variables

Upsert two variables and delete a third. Keys present in the payload are created or replaced; a key whose value is `null` is deleted; omitted keys are preserved.

```
{
  "MAX_CART_ITEMS": {
    "value": 50
  },
  "PAYMENT_GATEWAY_API_KEY": {
    "value": "sk_live_a1b2c3d4e5f6"
  },
  "LEGACY_CHECKOUT_URL": {
    "value": null
  }
}
```

#### Responses

*   **204** Environment variables successfully updated.
*   **400** Bad Request. A variable name is invalid or restricted, or the combined size of all variable values exceeds 32 KB.
    
    Media type: `application/problem+json`. Schema: `EnvironmentVariableNameInvalidErrorResponse | EnvironmentVariableSizeExceededErrorResponse`.
    
    One of: `EnvironmentVariableNameInvalidErrorResponse`, `EnvironmentVariableSizeExceededErrorResponse`.
    
    _Example: EnvironmentVariableNameInvalidErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-variable-name-invalid",
      "detail": "The environment variable name MRT_INTERNAL_FLAG is invalid or restricted.",
      "title": "Environment Variable Name Invalid"
    }
    ```
    
    _Example: EnvironmentVariableSizeExceededErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/environment-variable-size-exceeded",
      "detail": "The combined size of all environment variable values exceeds the 32 KB limit.",
      "title": "Environment Variable Size Exceeded"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

### GET Get access control headers.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/access-control-headers`

Operation ID: `getAccessControlHeaders`. Security: AmOAuth2 (sfcc.storefront.environments, sfcc.storefront.environments.rw).

Retrieves a paginated list of access control headers on the environment. Values are masked.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `orderBy` (query, array of string, style: form, explode: false) Attributes to order the returned access control headers by, in priority order, applied left to right. Append `:asc` or `:desc` to set the direction; when omitted, `:asc` is assumed. Sortable attributes: `creation_date`, `id`, `publishing_status`.  
    Items: Pattern: ^(creation\_date|id|publishing\_status)(:(asc|desc))?$. Example: `creation_date:desc`. Maximum items: 3.
    
    _Example_
    
    ```
    [
      "creation_date:desc"
    ]
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** List of access control headers successfully retrieved.
    
    Media type: `application/json`. Schema: `AccessControlHeaderResult`.
    
    _Example: AccessControlHeaderListSuccess_ Successful access control header list result
    
    Example of a successful response returning a paginated list of access control headers.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 2,
      "data": [
        {
          "id": "ff832a9e-0e55-11ef-8f23-0242ac110002",
          "value": "****************by0z",
          "createdBy": "jane.doe@example.com",
          "creationDate": "2026-08-24T09:23:28.872916Z",
          "publishingStatus": "completed"
        },
        {
          "id": "a1b2c3d4-0e55-11ef-8f23-0242ac110099",
          "value": "****************k9zq",
          "createdBy": "john.doe@example.com",
          "creationDate": "2026-08-22T11:05:10.000000Z",
          "publishingStatus": "pending"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

### POST Create an access control header.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/access-control-headers`

Operation ID: `createAccessControlHeader`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Creates a header-based access control rule on the environment. The created value is masked in the response.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Request body (required)

Media type: `application/json`. Schema: `AccessControlHeaderCreateRequest`.

_Example: CreateAccessControlHeader_ Create an access control header

Create a header-based access control rule on the environment.

```
{
  "value": "jfoWikeaby0z"
}
```

#### Responses

*   **201** Access control header successfully created.
    
    Media type: `application/json`. Schema: `AccessControlHeader`.
    
    _Example: AccessControlHeaderCreatedSuccess_ Successful access control header creation
    
    Example of a successful response after creating an access control header.
    
    ```
    {
      "id": "ff832a9e-0e55-11ef-8f23-0242ac110002",
      "value": "****************by0z",
      "createdBy": "jane.doe@example.com",
      "creationDate": "2026-08-24T09:23:28.872916Z",
      "publishingStatus": "pending"
    }
    ```
    
*   **400** Bad Request. The per-environment header limit has been reached, or the value is invalid.
    
    Media type: `application/problem+json`. Schema: `AccessControlHeaderLimitReachedErrorResponse | AccessControlHeaderValueInvalidErrorResponse`.
    
    One of: `AccessControlHeaderLimitReachedErrorResponse`, `AccessControlHeaderValueInvalidErrorResponse`.
    
    _Example: AccessControlHeaderLimitReachedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/access-control-header-limit-reached",
      "detail": "The maximum number of access control headers for this environment has been reached.",
      "title": "Access Control Header Limit Reached"
    }
    ```
    
    _Example: AccessControlHeaderValueInvalidErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/access-control-header-value-invalid",
      "detail": "The supplied access control header value is invalid.",
      "title": "Access Control Header Value Invalid"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

### GET Get an access control header by ID.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/access-control-headers/{accessControlHeaderId}`

Operation ID: `getAccessControlHeader`. Security: AmOAuth2 (sfcc.storefront.environments, sfcc.storefront.environments.rw).

Retrieves a single access control header by its identifier. The value is masked.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `accessControlHeaderId` (path, string (uuid), required) The access control header identifier, in UUID format.  
    Example: `ff832a9e-0e55-11ef-8f23-0242ac110002`.

#### Responses

*   **200** Access control header successfully retrieved.
    
    Media type: `application/json`. Schema: `AccessControlHeader`.
    
    _Example: AccessControlHeaderSuccess_ Successful access control header retrieval
    
    Example of a successful response returning a single access control header.
    
    ```
    {
      "id": "ff832a9e-0e55-11ef-8f23-0242ac110002",
      "value": "****************by0z",
      "createdBy": "jane.doe@example.com",
      "creationDate": "2026-08-24T09:23:28.872916Z",
      "publishingStatus": "completed"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The requested access control header was not found on the environment.
    
    Media type: `application/problem+json`. Schema: `AccessControlHeaderNotFoundErrorResponse`.
    
    _Example: AccessControlHeaderNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/access-control-header-not-found",
      "detail": "We couldn't find access control header ff832a9e-0e55-11ef-8f23-0242ac110002.",
      "title": "Access Control Header Not Found"
    }
    ```
    

### DELETE Delete an access control header.

`DELETE /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/access-control-headers/{accessControlHeaderId}`

Operation ID: `deleteAccessControlHeader`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Deletes an access control header by its identifier.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `accessControlHeaderId` (path, string (uuid), required) The access control header identifier, in UUID format.  
    Example: `ff832a9e-0e55-11ef-8f23-0242ac110002`.

#### Responses

*   **204** Access control header successfully deleted.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The requested access control header was not found on the environment.
    
    Media type: `application/problem+json`. Schema: `AccessControlHeaderNotFoundErrorResponse`.
    
    _Example AccessControlHeaderNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/access-control-headers/{accessControlHeaderId} 404 response._
    

### GET Get redirects.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects`

Operation ID: `getRedirects`. Security: AmOAuth2 (sfcc.storefront.environments, sfcc.storefront.environments.rw).

Retrieves a paginated, orderable list of redirects on the environment.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `orderBy` (query, array of string, style: form, explode: false) Attributes to order the returned redirects by, in priority order, applied left to right. Append `:asc` or `:desc` to set the direction; when omitted, `:asc` is assumed. Sortable attributes: `creation_date`, `last_modified`, `source`, `destination`, `last_modified_by`, `http_status_code`, `publishing_status`.  
    Items: Pattern: ^(creation\_date|last\_modified|source|destination|last\_modified\_by|http\_status\_code|publishing\_status)(:(asc|desc))?$. Example: `creation_date:desc`. Maximum items: 7.
    
    _Example_
    
    ```
    [
      "creation_date:desc"
    ]
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** List of redirects successfully retrieved.
    
    Media type: `application/json`. Schema: `RedirectResult`.
    
    _Example: RedirectListSuccess_ Successful redirect list result
    
    Example of a successful response returning a paginated list of redirects.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 2,
      "data": [
        {
          "redirectId": "3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
          "source": "/spring",
          "destination": "/summer-newbranding",
          "httpStatusCode": 301,
          "forwardQuerystring": false,
          "forwardWildcard": false,
          "publishingStatus": "completed",
          "createdBy": "john.doe@example.com",
          "lastModifiedBy": "john.doe@example.com",
          "creationDate": "2026-08-24T00:00:00.000Z",
          "lastModified": "2026-08-24T00:00:00.000Z"
        },
        {
          "redirectId": "7c1e2f3a-8b9c-4d5e-6f7a-1b2c3d4e5f6a",
          "source": "/old-page",
          "destination": "/new-page",
          "httpStatusCode": 302,
          "forwardQuerystring": true,
          "forwardWildcard": false,
          "publishingStatus": "pending",
          "createdBy": "jane.doe@example.com",
          "lastModifiedBy": "jane.doe@example.com",
          "creationDate": "2026-08-23T12:30:00.000Z",
          "lastModified": "2026-08-23T12:30:00.000Z"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

### POST Create a redirect.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects`

Operation ID: `createRedirect`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Creates a redirect on the environment. Returns the created redirect and a `Location` header.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Request body (required)

Media type: `application/json`. Schema: `RedirectCreateRequest`.

_Example: CreateRedirect_ Create a single redirect

Create one redirect rule on the environment.

```
{
  "source": "/spring",
  "destination": "/summer-newbranding",
  "httpStatusCode": 301,
  "forwardQuerystring": false,
  "forwardWildcard": false
}
```

#### Responses

*   **201** Redirect successfully created. Returns the created redirect and a `Location` header.
    
    Headers:
    
    *   `Location` (string (uri)) The URL of the created redirect.  
        Example: `https://123456gf.api.commercecloud.salesforce.com/storefront/environments/v1/organizations/f_ecom_blnd_stg/storefronts/my-storefront/environments/production/redirects/3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`.
    
    Media type: `application/json`. Schema: `Redirect`.
    
    _Example: RedirectCreatedSuccess_ Successful redirect creation
    
    Example of a successful response after creating a single redirect.
    
    ```
    {
      "redirectId": "3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "source": "/spring",
      "destination": "/summer-newbranding",
      "httpStatusCode": 301,
      "forwardQuerystring": false,
      "forwardWildcard": false,
      "publishingStatus": "pending",
      "createdBy": "john.doe@example.com",
      "lastModifiedBy": "john.doe@example.com",
      "creationDate": "2026-08-24T00:00:00.000Z",
      "lastModified": "2026-08-24T00:00:00.000Z"
    }
    ```
    
*   **400** Bad Request. A duplicate `source`, a redirect loop, or a field validation failure.
    
    Media type: `application/problem+json`. Schema: `RedirectDuplicatePathErrorResponse | RedirectLoopErrorResponse | RedirectValidationErrorResponse`.
    
    One of: `RedirectDuplicatePathErrorResponse`, `RedirectLoopErrorResponse`, `RedirectValidationErrorResponse`.
    
    _Example: RedirectDuplicatePathErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/redirect-duplicate-path",
      "detail": "A redirect already exists for the source path /spring.",
      "title": "Redirect Duplicate Path"
    }
    ```
    
    _Example: RedirectLoopErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/redirect-loop",
      "detail": "The redirect would create a redirect loop.",
      "title": "Redirect Loop"
    }
    ```
    
    _Example: RedirectValidationErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/redirect-validation",
      "detail": "The redirect request failed validation: destination must be a valid path or URL",
      "title": "Redirect Validation"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

### GET Get a redirect by ID.

`GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/{redirectId}`

Operation ID: `getRedirect`. Security: AmOAuth2 (sfcc.storefront.environments, sfcc.storefront.environments.rw).

Retrieves a single redirect by its identifier.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `redirectId` (path, string (uuid), required) The redirect identifier, in UUID format.  
    Example: `3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`.

#### Responses

*   **200** Redirect successfully retrieved.
    
    Media type: `application/json`. Schema: `Redirect`.
    
    _Example: RedirectSuccess_ Successful redirect retrieval
    
    Example of a successful response returning a single redirect.
    
    ```
    {
      "redirectId": "3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "source": "/spring",
      "destination": "/summer-newbranding",
      "httpStatusCode": 301,
      "forwardQuerystring": false,
      "forwardWildcard": false,
      "publishingStatus": "completed",
      "createdBy": "john.doe@example.com",
      "lastModifiedBy": "john.doe@example.com",
      "creationDate": "2026-08-24T00:00:00.000Z",
      "lastModified": "2026-08-24T00:00:00.000Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The requested redirect was not found on the environment.
    
    Media type: `application/problem+json`. Schema: `RedirectNotFoundErrorResponse`.
    
    _Example: RedirectNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/redirect-not-found",
      "detail": "We couldn't find redirect 3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d.",
      "title": "Redirect Not Found"
    }
    ```
    

### DELETE Delete a redirect.

`DELETE /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/{redirectId}`

Operation ID: `deleteRedirect`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Deletes a redirect by its identifier.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `redirectId` (path, string (uuid), required) The redirect identifier, in UUID format.  
    Example: `3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`.

#### Responses

*   **204** Redirect successfully deleted.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The requested redirect was not found on the environment.
    
    Media type: `application/problem+json`. Schema: `RedirectNotFoundErrorResponse`.
    
    _Example RedirectNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/{redirectId} 404 response._
    

### PATCH Update a redirect.

`PATCH /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/{redirectId}`

Operation ID: `updateRedirect`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Partially updates a redirect by its identifier. Only the supplied fields are changed.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `redirectId` (path, string (uuid), required) The redirect identifier, in UUID format.  
    Example: `3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`.

#### Request body (required)

Media type: `application/json`. Schema: `RedirectUpdateRequest`.

_Example: UpdateRedirect_ Update a redirect

Partially update a redirect; only the supplied fields are changed.

```
{
  "destination": "/summer-2027"
}
```

#### Responses

*   **200** Redirect successfully updated.
    
    Media type: `application/json`. Schema: `Redirect`.
    
    _Example: RedirectUpdatedSuccess_ Successful redirect update
    
    Example of a successful response after partially updating a redirect.
    
    ```
    {
      "redirectId": "3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "source": "/spring",
      "destination": "/summer-2027",
      "httpStatusCode": 301,
      "forwardQuerystring": false,
      "forwardWildcard": false,
      "publishingStatus": "pending",
      "createdBy": "john.doe@example.com",
      "lastModifiedBy": "jane.doe@example.com",
      "creationDate": "2026-08-24T00:00:00.000Z",
      "lastModified": "2026-08-25T08:12:44.000Z"
    }
    ```
    
*   **400** Bad Request. A duplicate `source`, a redirect loop, or a field validation failure.
    
    Media type: `application/problem+json`. Schema: `RedirectDuplicatePathErrorResponse | RedirectLoopErrorResponse | RedirectValidationErrorResponse`.
    
    One of: `RedirectDuplicatePathErrorResponse`, `RedirectLoopErrorResponse`, `RedirectValidationErrorResponse`.
    
    _Example RedirectDuplicatePathErrorResponseExample: same as POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects 400 response._
    
    _Example RedirectValidationErrorResponseExample: same as POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects 400 response._
    
    _Example: RedirectLoopErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/redirect-loop",
      "detail": "The redirect would create a redirect loop.",
      "title": "Redirect Loop"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** The requested redirect was not found on the environment.
    
    Media type: `application/problem+json`. Schema: `RedirectNotFoundErrorResponse`.
    
    _Example RedirectNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/{redirectId} 404 response._
    

### POST Clone redirects from a source environment.

`POST /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId}/redirects/actions/clone`

Operation ID: `cloneRedirects`. Security: AmOAuth2 (sfcc.storefront.environments.rw).

Copies all redirects from a source environment into the environment in the request path. The source environment must differ from the destination environment.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (path, string, required) The environment identifier that B2C Commerce generates based on the provided display name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

#### Request body (required)

Media type: `application/json`. Schema: `RedirectCloneRequest`.

_Example: CloneRedirects_ Clone redirects from a source environment

Copy all redirects from a source environment into this environment.

```
{
  "sourceEnvironmentId": "staging"
}
```

#### Responses

*   **201** Redirects successfully cloned into the destination environment.
*   **400** Bad Request. The source environment must differ from the destination environment.
    
    Media type: `application/problem+json`. Schema: `RedirectCloneSameEnvironmentErrorResponse`.
    
    _Example: RedirectCloneSameEnvironmentErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/redirect-clone-same-environment",
      "detail": "The source environment must differ from the destination environment.",
      "title": "Redirect Clone Same Environment"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested environment.
    
    Media type: `application/problem+json`. Schema: `EnvironmentNotFoundErrorResponse`.
    
    _Example EnvironmentNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId}/environments/{environmentId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### EnvironmentResult

Result containing a paginated list of environments.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Environment_, required) The list of environments belonging to the storefront. This value can be empty.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### StorefrontNotFoundErrorResponse

Returned when the storefront that the environment belongs to does not exist for this organization.

Includes all fields of `ErrorResponse`.

*   `storefrontId` (_string_) The identifier of the storefront that couldn't be found.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

### EnvironmentCreateRequest

Request body to create an environment for a storefront.

*   `displayName` (_string_, required) The display name for the new environment.  
    Maximum length: 256. Example: `Production`.

### Environment

An environment within Managed Runtime (MRT) where to deploy storefronts to separate phases of your development lifecycle, such as development, staging, or production.

*   `environmentId` (_string_, required) The generated environment identifier. Unique within the storefront, with an auto-generated hash suffix.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `displayName` (_string_, required) The display name of the environment.  
    Maximum length: 256. Example: `Production`.
*   `status` (_EnvironmentStatus_, required)
*   `isPrimary` (_boolean_, required) Indicates whether the environment is the storefront's primary environment. Only one environment per storefront can be primary.  
    Example: `true`.
*   `subdomain` (_string_, nullable) The subdomain assigned to this environment. The subdomain is available after the environment finishes building and is null before then.  
    Maximum length: 256. Example: `production`.
*   `mrtOrigin` (_string_, nullable) The Managed Runtime origin URL that backs this environment. The origin is available after the environment finishes building and is null before then.  
    Maximum length: 512. Example: `https://production-my-storefront.exp-delivery.com`.
*   `defaultEcdnHostname` (_string_, nullable) The eCDN hostname for the environment's default domain zone, used by the preview link. The eCDN hostname is available after the environment finishes building and is null before then.  
    Maximum length: 256. Example: `marketstreetb82739d375a9270f.zzzz-001.my.cc.salesforce.com`.
*   `creationDate` (_string (date-time)_) The timestamp when the environment was created.  
    Example: `2026-04-08T21:47:28.188965Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the environment was last modified.  
    Example: `2026-04-08T21:47:31.307595Z`.
*   `ssrRegion` (_SsrRegion_)
*   `ssrArchitecture` (_string_, nullable) The architecture for the environment's server-side rendering function. Null when no architecture default is configured.  
    Allowed values: `x86`, `arm64`. Example: `arm64`.
*   `ssrExternalHostname` (_string_, nullable) The full custom hostname used by the environment (e.g. [www.customer.com](http://www.customer.com)). Null when not configured.  
    Maximum length: 128. Example: `www.customer.com`.
*   `ssrExternalDomain` (_string_, nullable) The external domain for the ssrExternalHostname (e.g. customer.com). When omitted it is derived from ssrExternalHostname. Null when not configured.  
    Maximum length: 128. Example: `customer.com`.
*   `ssrWhitelistedIps` (_string_, nullable) A space-separated list of IPv4 or IPv6 CIDR blocks permitted to access the environment. Null or empty allows all IPs.  
    Maximum length: 8192. Example: `192.0.2.0/24 198.51.100.0/24`.
*   `ssrProxyConfigs` (_array of SsrProxyConfig_, nullable) The proxy configurations for the environment. Null when none are configured.  
    Maximum items: 8.
*   `isProduction` (_boolean_) Whether the environment is provisioned with production-tier capacity.  
    Example: `false`.
*   `allowCookies` (_boolean_) Whether cookies are forwarded to and respected from the environment's origin.  
    Example: `true`.
*   `preserveProxyUserAgent` (_boolean_) Whether the end-user's User-Agent header is preserved on requests forwarded through the environment's configured proxies.  
    Example: `false`.
*   `enableSourceMaps` (_boolean_) Whether source maps are enabled for the environment's server-side rendering bundle.  
    Example: `false`.
*   `logLevel` (_string_, nullable) The minimum log level emitted by the environment's server-side rendering function. Null when inherited from the default.  
    Allowed values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`. Example: `warn`.
*   `distributedTracing` (_boolean_) Whether distributed tracing is enabled for the environment.  
    Example: `false`.
*   `distributedTracingSamplingRate` (_number (double)_) The fraction of requests sampled for distributed tracing.  
    Minimum: 0. Maximum: 1. Example: `0.1`.
*   `certificateId` (_integer (int32)_, nullable) The identifier of the certificate associated with the environment's custom domain. Null when using the default Managed Runtime domain.  
    Minimum: 0. Example: `42`.

### InvalidEnvironmentCreateRequestErrorResponse

Returned when the environment creation request body is malformed or missing a valid displayName.

Includes all fields of `ErrorResponse`.

### EnvironmentCloneRequest

Request body to create an environment by cloning an existing one.

*   `sourceEnvironmentId` (_string_, required) The identifier of the environment to clone.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `displayName` (_string_, required) The display name for the new environment.  
    Maximum length: 256. Example: `Production (EU)`.
*   `cloneEnvironmentVariables` (_boolean_) Indicates whether to copy the source environment's environment variables to the new environment.  
    Default: `false`. Example: `true`.
*   `cloneRedirects` (_boolean_) Indicates whether to copy the source environment's redirects to the new environment.  
    Default: `false`. Example: `true`.
*   `cloneB2cTargetInfo` (_boolean_) Indicates whether to copy the source environment's B2C Commerce target information to the new environment.  
    Default: `true`. Example: `true`.

### InvalidEnvironmentCloneRequestErrorResponse

Returned when the environment clone request body is malformed or missing a valid sourceEnvironmentId or displayName.

Includes all fields of `ErrorResponse`.

### SourceEnvironmentNotFoundErrorResponse

Returned when the sourceEnvironmentId in a clone request does not exist for the specified storefront.

Includes all fields of `ErrorResponse`.

*   `storefrontId` (_string_) The identifier of the storefront the clone was requested under.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `sourceEnvironmentId` (_string_) The identifier of the source environment that couldn't be found.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

### EnvironmentNotFoundErrorResponse

Returned when the requested environment (or the source environment referenced in a clone request) does not exist for the specified storefront.

Includes all fields of `ErrorResponse`.

*   `storefrontId` (_string_) The identifier of the storefront the environment was requested under.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `environmentId` (_string_) The identifier of the environment that couldn't be found.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.

### EnvironmentBusyErrorResponse

Returned when an environment deletion is requested while the environment is already building or deleting.

Includes all fields of `ErrorResponse`.

*   `environmentId` (_string_) The identifier of the environment.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `status` (_string_) The environment's current status.  
    Allowed values: `building`, `deleting`. Example: `building`.

### EnvironmentUpdateRequest

Request body to update an environment. Every field is optional and only the supplied fields are changed; at least one field must be provided.

Minimum properties: 1.

*   `displayName` (_string_) The new display name for the environment.  
    Maximum length: 256. Example: `Production`.
*   `ssrRegion` (_SsrRegion_)
*   `ssrArchitecture` (_string_, nullable) The architecture for the environment's server-side rendering function. Set to null to inherit the storefront default.  
    Allowed values: `x86`, `arm64`. Example: `arm64`.
*   `ssrExternalHostname` (_string_, nullable) The full custom hostname used by the environment (e.g. [www.customer.com](http://www.customer.com)). Set to null to clear it.  
    Maximum length: 128. Example: `www.customer.com`.
*   `ssrExternalDomain` (_string_, nullable) The external domain for the ssrExternalHostname (e.g. customer.com). When omitted it is derived from ssrExternalHostname. Set to null to clear it.  
    Maximum length: 128. Example: `customer.com`.
*   `ssrWhitelistedIps` (_string_, nullable) A space-separated list of IPv4 or IPv6 CIDR blocks permitted to access the environment. Set to null or empty to allow all IPs.  
    Maximum length: 8192. Example: `192.0.2.0/24 198.51.100.0/24`.
*   `ssrProxyConfigs` (_array of SsrProxyConfig_, nullable) The proxy configurations for the environment. Set to null to clear them.  
    Maximum items: 8.
*   `isProduction` (_boolean_) Whether the environment is provisioned with production-tier capacity.  
    Example: `false`.
*   `allowCookies` (_boolean_) Whether cookies are forwarded to and respected from the environment's origin.  
    Example: `true`.
*   `preserveProxyUserAgent` (_boolean_) Whether the end-user's User-Agent header is preserved on requests forwarded through the environment's configured proxies.  
    Example: `false`.
*   `enableSourceMaps` (_boolean_) Whether source maps are enabled for the environment's server-side rendering bundle.  
    Example: `false`.
*   `logLevel` (_string_, nullable) The minimum log level emitted by the environment's server-side rendering function. Set to null to inherit the default.  
    Allowed values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`. Example: `warn`.
*   `distributedTracing` (_boolean_) Whether distributed tracing is enabled for the environment.  
    Example: `false`.
*   `distributedTracingSamplingRate` (_number (double)_) The fraction of requests sampled for distributed tracing.  
    Minimum: 0. Maximum: 1. Example: `0.1`.
*   `certificateId` (_integer (int32)_, nullable) The identifier of the certificate to associate with the environment's custom domain. Set to null to remove the certificate association. Not permitted when using the default Managed Runtime domain.  
    Minimum: 0. Example: `42`.

### InvalidEnvironmentUpdateRequestErrorResponse

Returned when the environment update request body is malformed, empty, or contains an unsupported value (for example an invalid ssrRegion, ssrArchitecture, or logLevel).

Includes all fields of `ErrorResponse`.

### EnvironmentSsrRegionDisabledErrorResponse

Returned when the requested ssrRegion is in the temporarily disabled set.

Includes all fields of `ErrorResponse`.

*   `ssrRegion` (_string_) The identifier of the SSR region that is temporarily disabled.  
    Maximum length: 32. Example: `eu_south_1`.

### EnvironmentSsrArchitectureNotEnabledErrorResponse

Returned when the x86 ssrArchitecture is requested but the organization is not permitted to configure the SSR architecture.

Includes all fields of `ErrorResponse`.

### EnvironmentSsrArchitectureX86EndOfLifeErrorResponse

Returned when the x86 ssrArchitecture is requested after its end-of-life date and the organization has no active grace period.

Includes all fields of `ErrorResponse`.

### EnvironmentCertificateInvalidErrorResponse

Returned when the supplied certificateId does not exist for the organization, is not in a validated state, does not match the environment's hostname domain, or is supplied while the environment uses the default Managed Runtime domain.

Includes all fields of `ErrorResponse`.

*   `certificateId` (_integer (int32)_) The identifier of the certificate that was rejected.  
    Minimum: 0. Example: `42`.

### EnvironmentSsrFieldBusinessManagerErrorResponse

Returned when an SSR networking field (ssrExternalHostname, ssrExternalDomain, or ssrWhitelistedIps) is changed on an environment that is served through eCDN, where such changes must be made in Business Manager.

Includes all fields of `ErrorResponse`.

*   `field` (_string_) The name of the SSR field that cannot be changed through this API.  
    Maximum length: 64. Example: `ssrExternalHostname`.

### EnvironmentInvalidProxyConfigErrorResponse

Returned when ssrProxyConfigs fail validation — for example more than the maximum of 8 proxies, duplicate proxy paths, an invalid proxy host, or an unsupported protocol (only https is supported).

Includes all fields of `ErrorResponse`.

*   `reason` (_string_) A human-readable description of the proxy configuration validation failure.  
    Maximum length: 4000. Example: `The max number of proxies allowed is 8, but 9 given.`.

### EnvironmentUpdateForbiddenErrorResponse

Returned when the requested update is not permitted — for example changing allowCookies on a Storefront Next environment (where cookies are always enabled), or changing an SSR networking field on a protected environment.

Includes all fields of `ErrorResponse`.

### PrimaryEnvironmentInvalidStatusErrorResponse

Returned when an environment is set as primary while its status is not ready or build\_failed.

Includes all fields of `ErrorResponse`.

*   `environmentId` (_string_) The identifier of the environment.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `production-a1b2c3d4`.
*   `status` (_string_) The environment's current status.  
    Allowed values: `building`, `deleting`, `deleted`, `delete_failed`. Example: `building`.

### CacheInvalidationRequest

Request body to trigger a CDN cache invalidation on the environment.

*   `pattern` (_string_, required) The path prefix to invalidate. Must start with `/`. Cache invalidation is always a wildcard operation: the CDN clears every cached path that begins with this value (a trailing `*` is always implied), so `/products` and `/products*` invalidate the same paths. If the value contains a `*`, only the portion before the first `*` is used as the prefix and the remainder is ignored. The invalidation is performed asynchronously.  
    Minimum length: 1. Pattern: ^/.\*$. Example: `/products/*`.

### CacheInvalidationPatternInvalidErrorResponse

Returned when the cache invalidation `pattern` is missing or does not start with `/`.

Includes all fields of `ErrorResponse`.

### CacheInvalidationNoBundleErrorResponse

Returned when no SSR bundle is deployed to the environment, so there is nothing to invalidate.

Includes all fields of `ErrorResponse`.

### EnvironmentVariables

The complete set of environment variables for the environment, as a map keyed by variable name. Values are masked. This is a singleton resource (one set per environment) and is not a paginated collection.

Additional properties: `EnvironmentVariableEntry`.

_Example_

```
{
  "PAYMENT_GATEWAY_API_KEY": {
    "value": "****e5f6",
    "createdBy": "jane.doe@example.com",
    "creationDate": "2026-08-24T09:23:28.872916Z",
    "lastModified": "2026-08-24T09:23:28.872916Z",
    "lastModifiedBy": "jane.doe@example.com",
    "publishingStatus": "completed"
  }
}
```

### EnvironmentVariablesUpdateRequest

A merge (upsert) update of environment variables, keyed by variable name. Keys present in the payload are created or replaced; a key whose value is `null` is deleted; keys omitted from the payload are preserved.

Additional properties: `EnvironmentVariableUpdateEntry`.

_Example_

```
{
  "MAX_CART_ITEMS": {
    "value": 50
  },
  "PAYMENT_GATEWAY_API_KEY": {
    "value": "sk_live_a1b2c3d4e5f6"
  },
  "LEGACY_CHECKOUT_URL": {
    "value": null
  }
}
```

### EnvironmentVariableNameInvalidErrorResponse

Returned when an environment variable name is invalid or restricted — for example an `MRT_`\-prefixed name, which is reserved.

Includes all fields of `ErrorResponse`.

*   `name` (_string_) The environment variable name that was rejected.  
    Maximum length: 256. Example: `MRT_INTERNAL_FLAG`.

### EnvironmentVariableSizeExceededErrorResponse

Returned when the combined size of all environment variable values exceeds 32 KB.

Includes all fields of `ErrorResponse`.

### AccessControlHeaderResult

Paginated result containing a list of access control headers.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of AccessControlHeader_, required) List of access control headers.

### AccessControlHeaderCreateRequest

Request body to create an access control header.

*   `value` (_string_, required) The header value.  
    Minimum length: 9. Maximum length: 127. Example: `jfoWikeaby0z`.

### AccessControlHeader

A header-based access control rule on the environment.

*   `id` (_string (uuid)_) The unique identifier of the access control header, in UUID format.  
    Example: `ff832a9e-0e55-11ef-8f23-0242ac110002`.
*   `value` (_string_) The masked header value. Actual values are never returned in clear text.  
    Maximum length: 127. Example: `****************by0z`.
*   `createdBy` (_string_, nullable) The email address of the user who created the header. Null if no user is associated.  
    Maximum length: 255. Example: `jane.doe@example.com`.
*   `creationDate` (_string (date-time)_) The timestamp when the header was created.  
    Example: `2026-08-24T09:23:28.872916Z`.
*   `publishingStatus` (_PublishingStatus_)

### AccessControlHeaderLimitReachedErrorResponse

Returned when the per-environment access control header limit has been reached.

Includes all fields of `ErrorResponse`.

### AccessControlHeaderValueInvalidErrorResponse

Returned when the supplied access control header value is invalid.

Includes all fields of `ErrorResponse`.

### AccessControlHeaderNotFoundErrorResponse

Returned when the requested access control header does not exist on the environment.

Includes all fields of `ErrorResponse`.

*   `accessControlHeaderId` (_string_) The identifier of the access control header that couldn't be found.  
    Minimum length: 36. Maximum length: 36. Pattern: ^\[0-9a-f\]{8}-\[0-9a-f\]{4}-\[0-9a-f\]{4}-\[0-9a-f\]{4}-\[0-9a-f\]{12}$. Example: `ff832a9e-0e55-11ef-8f23-0242ac110002`.

### RedirectResult

Paginated result containing a list of redirects.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Redirect_, required) List of redirects.

### RedirectCreateRequest

Request body to create a single redirect.

*   `source` (_string_, required) The source path that triggers the redirect.  
    Minimum length: 1. Maximum length: 2000. Example: `/spring`.
*   `destination` (_string_, required) The destination path or URL the request is redirected to.  
    Minimum length: 1. Maximum length: 2000. Example: `/summer-newbranding`.
*   `httpStatusCode` (_RedirectHttpStatusCode_)
*   `forwardQuerystring` (_boolean_) Whether the incoming query string is forwarded to the destination.  
    Default: `false`. Example: `false`.
*   `forwardWildcard` (_boolean_) Whether a trailing wildcard match on the source is forwarded to the destination.  
    Default: `false`. Example: `false`.

### Redirect

A URL redirect rule on the environment.

*   `redirectId` (_string (uuid)_) The unique identifier of the redirect, in UUID format.  
    Example: `3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`.
*   `source` (_string_) The source path that triggers the redirect.  
    Minimum length: 1. Maximum length: 2000. Example: `/spring`.
*   `destination` (_string_) The destination path or URL the request is redirected to.  
    Minimum length: 1. Maximum length: 2000. Example: `/summer-newbranding`.
*   `httpStatusCode` (_RedirectHttpStatusCode_)
*   `forwardQuerystring` (_boolean_) Whether the incoming query string is forwarded to the destination.  
    Example: `false`.
*   `forwardWildcard` (_boolean_) Whether a trailing wildcard match on the source is forwarded to the destination.  
    Example: `false`.
*   `publishingStatus` (_PublishingStatus_)
*   `createdBy` (_string_, nullable) The email address of the user who created the redirect. Null if no user is associated.  
    Maximum length: 255. Example: `john.doe@example.com`.
*   `lastModifiedBy` (_string_, nullable) The email address of the user who last modified the redirect. Null if no user is associated.  
    Maximum length: 255. Example: `john.doe@example.com`.
*   `creationDate` (_string (date-time)_) The timestamp when the redirect was created.  
    Example: `2026-08-24T00:00:00.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the redirect was last modified.  
    Example: `2026-08-24T00:00:00.000Z`.

### RedirectDuplicatePathErrorResponse

Returned when the payload contains a `source` path that already has a redirect on the environment.

Includes all fields of `ErrorResponse`.

*   `source` (_string_) The duplicate source path.  
    Maximum length: 2000. Example: `/spring`.

### RedirectLoopErrorResponse

Returned when the redirect would create a loop (the destination resolves back to the source).

Includes all fields of `ErrorResponse`.

### RedirectValidationErrorResponse

Returned when a redirect field fails validation — for example a malformed `source` or `destination`.

Includes all fields of `ErrorResponse`.

*   `reason` (_string_) A human-readable description of the validation failure.  
    Maximum length: 4000. Example: `destination must be a valid path or URL`.

### RedirectNotFoundErrorResponse

Returned when the requested redirect does not exist on the environment.

Includes all fields of `ErrorResponse`.

*   `redirectId` (_string_) The identifier of the redirect that couldn't be found.  
    Minimum length: 36. Maximum length: 36. Pattern: ^\[0-9a-f\]{8}-\[0-9a-f\]{4}-\[0-9a-f\]{4}-\[0-9a-f\]{4}-\[0-9a-f\]{12}$. Example: `3f9b1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d`.

### RedirectUpdateRequest

Request body to partially update a redirect. Only the supplied fields are changed.

Minimum properties: 1.

*   `source` (_string_) The source path that triggers the redirect.  
    Minimum length: 1. Maximum length: 2000. Example: `/spring`.
*   `destination` (_string_) The destination path or URL the request is redirected to.  
    Minimum length: 1. Maximum length: 2000. Example: `/summer-2027`.
*   `httpStatusCode` (_RedirectHttpStatusCode_)
*   `forwardQuerystring` (_boolean_) Whether the incoming query string is forwarded to the destination.  
    Example: `false`.
*   `forwardWildcard` (_boolean_) Whether a trailing wildcard match on the source is forwarded to the destination.  
    Example: `false`.

### RedirectCloneRequest

Request body to clone all redirects from a source environment into this environment.

*   `sourceEnvironmentId` (_string_, required) The identifier of the environment to copy redirects from. Must differ from the environment in the request path.  
    Minimum length: 1. Maximum length: 19. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `staging`.

### RedirectCloneSameEnvironmentErrorResponse

Returned when a redirect clone request names a source environment that is the same as the destination environment in the request path.

Includes all fields of `ErrorResponse`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### EnvironmentStatus

The current provisioning or lifecycle status of the environment.

Type: `string`.

Allowed values: `building`, `ready`, `build_failed`, `deleting`, `deleted`, `delete_failed`. Example: `ready`.

### SsrRegion

The AWS region for the server-side rendering function of the environment. Each value corresponds to the AWS region of the same name with underscores substituted for hyphens (for example, `us_east_2` is the AWS region `us-east-2`).

Type: `string`.

Allowed values: `us_east_1`, `us_east_2`, `us_west_1`, `us_west_2`, `ap_south_1`, `ap_south_2`, `ap_northeast_2`, `ap_southeast_1`, `ap_southeast_2`, `ap_southeast_3`, `ap_northeast_1`, `ap_northeast_3`, `ca_central_1`, `eu_central_1`, `eu_central_2`, `eu_west_1`, `eu_west_2`, `eu_west_3`, `eu_north_1`, `eu_south_1`, `sa_east_1`. Example: `us_east_2`.

### SsrProxyConfig

A single proxy configuration entry for the environment, defined by its `path`, `host`, and `protocol`.

*   `path` (_string_) The request path prefix routed to the proxy origin.  
    Maximum length: 2048. Example: `/api`.
*   `host` (_string_) The proxy origin host.  
    Maximum length: 255. Example: `api.example.com`.
*   `protocol` (_string_) The protocol used to reach the proxy origin. Only `https` is supported.  
    Allowed values: `https`. Example: `https`.

### EnvironmentVariableEntry

A single environment variable's masked value and audit metadata.

*   `value` (_string_, nullable) The masked variable value. Actual values are never returned in clear text.  
    Maximum length: 32768. Example: `****e5f6`.
*   `createdBy` (_string_, nullable) The email address of the user who created the variable. Null if no user is associated.  
    Maximum length: 255. Example: `jane.doe@example.com`.
*   `creationDate` (_string (date-time)_) The timestamp when the variable was created.  
    Example: `2026-08-24T09:23:28.872916Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the variable was last modified.  
    Example: `2026-08-24T10:15:02.111000Z`.
*   `lastModifiedBy` (_string_, nullable) The email address of the user who last modified the variable. Null if no user is associated.  
    Maximum length: 255. Example: `john.doe@example.com`.
*   `publishingStatus` (_PublishingStatus_)

### EnvironmentVariableUpdateEntry

The desired value for a single environment variable in a merge update. Set `value` to `null` to delete the variable.

*   `value` (_string | number_, required) The new variable value. Accepts a string or a number (numbers are stored as strings). Set to `null` to delete the variable. The combined size of all variable values must not exceed 32 KB.
    
    One of: `string`, `number`.
    
    *   _string_
        
        Type: `string`.
        
        Maximum length: 32768. Example: `sk_live_a1b2c3d4e5f6`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `50`.
        

### PublishingStatus

The publishing status of the resource on the environment.

Type: `string`.

Allowed values: `pending`, `completed`, `failed`. Example: `pending`.

### RedirectHttpStatusCode

The HTTP status code returned for the redirect.

Type: `integer (int32)`.

Allowed values: `301`, `302`. Default: `301`. Example: `301`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=5ad470ceaf37acaf1f91e12b7c33bb875de338eb4de6958c6f8d913041c3ea5e url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/ereceipt-spi.md -->

EReceipt SPI

# EReceipt SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/ereceipt-spi/ereceipt-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send order eReceipts.

**Version:** 2.3.4

## Tags

### EReceipt SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/ereceipt-spi/ereceipt-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send order eReceipts.

## Operations

### POST Receive eReceipt.

`POST /merchant/spi/sample/endpoint/sa/orderEmail`

Operation ID: `postReceipt`. Tags: EReceipt SPI.

Receive order's detail. Merchant must implement this endpoint per this specification and then configure it in CMS. See SA\_ORDER\_INTIMATION.

#### Request body

Media type: `application/json`. Schema: `EReceiptRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

## Schemas

### EReceiptRequest

*   `type` (_string_) Receipt's type.  
    Allowed values: `TRANSACTION_PRINT_RECEIPT`, `ORDER_PRINT_RECEIPT`, `CUSTOMER_ORDER_CONFIRMATION`, `GIFT_RECEIPT`, `REFUND_CONFIRMATION`, `SA_ORDER_INTIMATION`.
*   `emailTo` (_array of string_) Emails to receive order.
*   `customerOrder` (_CustomerOrder_)
*   `receiptPrintCount` (_integer (int32)_) Receipt print count (number of original and duplicate receipts).
*   `receiptLanguage` (_string_)
    
    Language selected for the receipt template. This field is optional.
    
    The language value is resolved using the following priority order:
    
    1.  **Thank You Page language** — Uses the language option configured on the Thank You Page.
    2.  **Store Setting languages default** — If no Thank You Page language is configured, uses the default language from the languages Store Setting.
    3.  **Mobile Config defaultSupportedLanguage** — If neither of the above is set, falls back to Receipt Configuration > defaultSupportedLanguage in the Mobile Config.
    4.  **iPad locale** — If none of the above are populated, defaults to the associated iPad's locale.

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### CustomerOrder

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128. Example: `PS00027533`.
*   `quoteId` (_string_, nullable) Quote reference identifier. Links the order to a quote. Available when the order is based on a quote.  
    Maximum length: 128.
*   `externalQuoteId` (_string_, nullable) External quote reference identifier. Quote ID from the external system. Available when the order is based on a quote.  
    Maximum length: 128.
*   `orderStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `status` (_string_, read-only, nullable, deprecated)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderType` (_string_, nullable) Type of order. It is used in case of order fulfilled by the stores,  
    E.g. BOPIS, BOFIS, BOSS orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `email` (_string_, nullable) Customer Email ID.  
    It is available for signed-in customers or when email is captured in the  
    shipping address for guest customers.  
    Maximum length: 128.
*   `totalAmount` (_number_, required) Order total.
*   `shippingSubTotal` (_number_, nullable) Shipping sub total.
*   `shippingDiscount` (_number_, nullable) Shipping discount.
*   `shippingMethod` (_ShippingMethod_)
*   `shippingTax` (_number_, nullable) Shipping method tax.
*   `shippingTaxClass` (_string_, nullable) Shipping method tax class.
*   `taxSubTotal` (_number_, nullable) Total tax amount for this order.  
    It is applicable for regions/countries where Tax is supported. For countries where VAT is applicable, refer to valueAddedTax.  
    
*   `taxExemption` (_number_, nullable) The tax exemption amount for this order.  
    It is applicable whenever an associate applies a tax exemption to the order in store.  
    
*   `shippingTaxExemption` (_number_, nullable) Total Shipping tax exemption amount for this order. This does not include any product price or shipping cost. It includes only the tax exemption on Shipping.
*   `valueAddedTax` (_number_, nullable) Total VAT amount for this order.  
    It is applicable for regions/countries where VAT is supported. For countries where tax is applicable, refer to taxSubTotal.  
    
*   `orderSubTotal` (_number_, required) Order total excluding discounts, shipping costs and taxes but  
    inclusive of VAT.
*   `tenders` (_array of OrderPaymentDetail_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.  
    When importing an order paid with a credit card from an external system, make sure to include all required fields as well as the following fields:  
    1\. requestId  
    2\. cardType  
    For a **referenced refund** on the credit card, all the above fields and CMS configuration are necessary. Set the below CMS property to **Default** to initiate a referenced refund.  
    **CMS** > **Store Management** > **Store Settings** > **Refund Mode for External Order**.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products.  
    The list doesn't include returned products. While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `orderProductList` (_array of OrderProduct_, required) A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.
*   `returnProductList` (_array of ReturnedProduct_, nullable) List of items that have been returned.  
    While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `discount` (_number_, nullable) Order discount amount. Total discount applied using promo coupons and/or item level price override.  
    It doesn't include transaction discount. For transaction discount, refer to transactionDiscountAmount.  
    Mandatory: If any promo coupon is applied or any item level price override is applied.
*   `externalOrderId` (_string_, nullable) The reference ID of the order that corresponds to the external system. This is relevant in cases where the external downstream system or ERP system uses its own ID instead of the POS order ID for further processing. It is necessary to provide this reference ID while importing the order in POS, especially when updates like returns are required.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store where the order is captured. For BOPIS orders placed via a website,  
    this field contains the store ID for pickup.  
    Maximum length: 128.
*   `storeAssociateId` (_string_, required) The logged-in store associate's ID.  
    Maximum length: 256.
*   `orderSource` (_string_, required) This is the channel or source of an order or transaction. It must be IN\_STORE for all orders placed in store. It must be WEB for all orders placed on the website. When importing an order from an external system, ensure to provide: 1. IN\_STORE for orders placed in store, otherwise the order will not be available in CMS under successful order report. 2. WEB for orders placed on the website to skip its entry from successful order report.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `paymentSource` (_string_, nullable) Payment source. If an order is paid with a single tender,  
    it has the payment method of that tender. The following payment methods  
    are supported: CreditCard, Unknown, External, GiftCard, MixedMode, Cash, Miscellaneous,  
    Finance, StoreCredit, PayByLink, RemotePayByLink, Reward, and Check.  
    In the case of multi-tender payment, the payment source should be MixedMode.
*   `shippingMethodId` (_string_, nullable) Shipping method ID.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `installationId` (_string_, nullable) The device identifier is required for IN\_STORE purchases.  
    If not provided, it defaults to EXTERNAL for orders from external systems.  
    Default: `EXTERNAL`. Maximum length: 128.
*   `lastDateToReturnTimeStamp` (_integer (int64)_, nullable) Last date to return. The return window policy sets the last date for a return.  
    For example, if the policy is one month long and a sale occurs on April 1st,  
    the lastDateToReturnTimeStamp will be set to May 1st.  
    When an order is imported from an external system,  
    the system will determine the order's eligibility for return based on the provided date.  
    If the date is not provided, the item can be returned without any time limitation.  
    Note: Represented as number of milliseconds since epoch.  
    .  
    Example: `1653078974310`.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown. Mandatory if tax engine is configured along with tax rates.  
    For VAT countries, refer to vatRates.
*   `taxExemptions` (_array of TaxExemptionRequest_, nullable) List of tax exemptions, if any, applied to order.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown. Mandatory if tax engine is configured along with VAT rates. For TAX countries, refer to taxRates.
*   `shippingName` (_string_, nullable) Shipping name  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.name from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingDescription` (_string_, nullable) Shipping description.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.description from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingCarrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Required for delivery orders.  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.carrier from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingServiceLevel` (_string_, nullable) Shipping service level, for example, 3-5 Days, 1-Day, Express, Standard, or Overnight.  
    Required for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.serviceLevel from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `phoneNumber` (_string_, nullable) Customer phone number. Mandatory for signed-in customers  
    or when phone number is captured in the shipping address for guest customers.  
    
*   `orderDate` (_integer (int64)_, required) Date when order was placed.  
    Represented as number of milliseconds since epoch.
*   `coupons` (_array of string_, nullable) List of coupon codes applied for this order.
*   `customerProfile` (_Profile_)
*   `updateDate` (_integer (int64)_, required) Date when the order was last updated. Represented as number of milliseconds since epoch.
*   `taxableAmount` (_number_, nullable) Taxable amount.  
    Mandatory if the tax engine is configured along with tax rates.
*   `fulfillmentType` (_string_, required, deprecated) Order fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `rewardAmount` (_number_, nullable) Reward amount applied to this order if any.
*   `transactionDiscountAmount` (_number_, nullable) Transaction discount applied to this order if any.
*   `canReturn` (_boolean_, write-only, nullable) Flag indicating if this order can be returned.  
    During order import in POS, if it is not provided,the order remains returnable.
*   `paymentDetails` (_array of OrderPaymentDetail_, nullable, deprecated) Deprecated. Use 'tenders' instead.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Order refund payment details.  
    If an order is returned, it will have all refunded tenders.  
    
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `failedReasonCode` (_string_, read-only, nullable) Failed order reason code corresponding to payment.  
    Possible values are CANCELED, PAYMENT\_DECLINED, and PAYMENT\_REVERTED.  
    Applicable only if the order fails. Not required when importing an order from an external system.  
      
    Allowed values: `CANCELED`, `PAYMENT_DECLINED`, `PAYMENT_REVERTED`, `PAYMENT_REVERSAL_FAILED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_NOT_FOUND`.
*   `twoPhaseCommitReferenceId` (_string_, read-only, nullable, deprecated) Used for internal processing. Don't use in external systems.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `partiallyPaid` (_boolean_) Flag indicating if this order is partially paid for.
*   `orderActivityLog` (_array of OrderActivityLog_, nullable) The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.
*   `storeAttribution` (_StoreAttribution_)
*   `tipTotal` (_number_, nullable) Total tip added to the order.
*   `orderFiscalData` (_array of OrderFiscalData_, nullable) All fiscal data for this order if any.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `offlineMode` (_boolean_, nullable) Flag indicating if the order got created in offline mode.  
    If not mentioned, it is considered as false.
*   `employee` (_Employee_)
*   `originalOrderId` (_string_) Order ID of the original order if the order is an exchange order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method and other delivery details.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    2\. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `rewardList` (_array of Reward_, read-only, nullable) The list of loyalty rewards applied in this transaction.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `returnCustomerInformationList` (_array of OrderReturnCustomerInformation_, nullable) List of customer/person who returned the items.  
    Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.  
    
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `taxFreeDocument` (_TaxFreeDocument_)
*   `orderRefundFeeDetailList` (_array of OrderRefundFeeDetail_, nullable) List of Refund fee like restocking fee on returned or canceled items.  
    Applicable when item is returned or canceled and refund fee is configured.  
    For more detail on refund fee,
*   `error` (_boolean_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### OrderPaymentDetail

Deprecated. Use 'tenders' instead.

*   `transactionId` (_string_, required) The unique identifier for a transaction that completes the order. - This is particularly helpful in cases where a payment is made in multiple transactions, such as in the case of a deposit. - In POS, the transaction ID corresponds to the sale transaction when you place an order. - However, if you import an order from an external system, the transaction ID should correspond to the order in the external system and can be the same as the Order ID.  
    Maximum length: 128.
*   `paymentId` (_string_, required) The unique identifier for a payment/tender. As the order can have multiple payments, each payment will have a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method. Required for BOPIS and BOFIS. Not applicable for ROPIS.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. Possible values are: - `UNPROCESSED` is used internally by cloud services as a transient state. - `DISCARDED` is used when cash tender is part of a multi-tender payment and is deleted by swiping right. - `ABORTED` is used when we internally remove a tender from the tender list and add a new tender (e.g., for gift cards).  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device. If the payment is made in an external system, set the payment device to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards and gift cards through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender. Applicable for credit cards. for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal. Typically used for referenced refunds that are performed automatically by the POS without the customer presenting the card during a refund. In the case of Adyen payments, this field maps to `pspReference`. Required for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode, it generates a temporary payment ID, which is provided in the alternate payment request ID attribute. For example, the Adyen terminal generates a temporary ID called a "tender reference" whenever it goes into store and forward mode. This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund payment request ID issued by the payment gateway/terminal. Required for refund on credit cards.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item, and the original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried forward to the new order. This attribute provides the original order ID if the tender is carried over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item. The original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried over to the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and the tender is carried over to the new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Required for credit card payments using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment. For example, if a customer pays with cash first and the remaining amount with a credit card, the cash tender should have a paymentSequenceNumber of 1, and the credit card tender should have a paymentSequenceNumber of 2.
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number. Applicable when payment method is 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check' and 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.
*   `cardToken` (_string_) This field contains the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment** Gateways > Adyen > Payment Tokenization Events).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender. Normally, it is received after calling a call center agent of a payment processor. For example: call for authorization code after check denial or referral, or manual authorization code for a credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Required for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee. Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to finance approval/order/confirmation number in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderProduct

A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orignalQuantity` (_integer (int32)_)
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ReturnedProduct

List of items that have been returned. While importing an order from an external system, it is optional as the products and return products both can be provided in orderProductList.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `refundDate` (_integer (int64)_, required) The date and time, in milliseconds since epoch, when the item was returned.  
    Example: `1617222000000`.
*   `exchangedForOrderId` (_string_, nullable) The order ID for which the item was exchanged. Applicable for exchange.  
    Maximum length: 128.
*   `returnedAtStoreId` (_string_, required) The store ID where the item was returned.  
    Maximum length: 256.
*   `returnProcessedByAssociateId` (_string_, required) ID of the store associate who performed the return.  
    Maximum length: 256.
*   `returnedAtStoreRegisterId` (_string_, required) The register ID where the item was returned.  
    Maximum length: 128.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `offlineMode` (_boolean_, nullable) Specifies whether the item is returned in offline mode. If not provided, it is considered to be in online mode.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderRefundPaymentDetail

Refund payments.  
For return or exchange transactions, this contains the refund payments.  

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) A transaction ID is a unique identifier corresponding to the return  
    transaction. It is especially useful in situations where a refund is issued in multiple  
    return transactions. When importing an order from an external system and it has a refund,  
    the transaction ID should match the return transaction that carried out the refund.  
    In case the external system doesn't have a return transaction ID, you can use the order  
    ID in its place.  
    Maximum length: 128.
*   `paymentId` (_string_, required) It is a unique identifier for refund payments.  
    It must be unique within an order. When multiple refunds are issued for a single payment,  
    a unique ID is necessary to differentiate each refund.  
    Maximum length: 128.
*   `cardNumber` (_string_, nullable) Card Number to which refund was applied. Last 4 digits in case of refund to CreditCard. Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardType` (_string_, nullable) Card type, for example, mastercard, interac\_card, or visa.  
    Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `originalPaymentId` (_string_, required) A refund is issued against a original payment.  
    This ID provides a reference to the original payment.  
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Reference to original transaction that performs the payment.  
    This ID provides a reference to the original transaction.
*   `paymentMethod` (_string_, required) Refund payment method, for example, Cash or CreditCard.  
    For possible values, see the tenders.paymentMethod attribute.
*   `refundDate` (_string (date-time)_, required, nullable) Timestamp when refund payment was processed.Format: yyyy-MM-dd HH:mm:ss.
*   `refundedAmount` (_number_, required) Refund Amount.  
    Example: `100`.
*   `refundedAsPartOfOrderId` (_string_, nullable) Original Order Id for which this refund payment is processed.  
    Maximum length: 128.
*   `refundRequestId` (_string_, nullable) Refund request identification issued by the payment gateway/terminal.  
    In the case of Adyen payments, this field maps to pspReference of a refund.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use RefundMode instead.
*   `paymentDevice` (_string_, nullable) Device using which payment was refunded. For possible values, please refer to tenders.paymentDevice attribute. Applicable for CreditCard refund only.  
    Maximum length: 32.
*   `paymentDeviceId` (_string_, nullable) Payment Device Identifier. Applicable for CreditCard refund only.  
    Maximum length: 128.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt lines for refund payment.  
    Available in case of unreferenced refunds using CreditCard.  
    Unreferenced refunds are refunds that are not associated with a original payment and  
    customer is prompted to swipe/tap CreditCard during refund.  
    When an order is imported from an external system, it is optional.  
    
*   `cardExpirationMonth` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration month of the card to which payment was refunded.
*   `cardExpirationYear` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration year of the card to which payment was refunded.
*   `roundingAmount` (_number_, nullable) Rounding amount during refund using cash. Applicable for cash refund  
    in regions where rounding is applicable.
*   `refundMode` (_string_, nullable) Refund Mode. It is applicable for CreditCard refunds. The modes are:  
    1\. Unreferenced: Refund is not associated to original payment and is issued on different credit card  
    2\. External: Refund is initiated externally and not by POS  
    3\. Default: Regular refund. It is initiated by POS against original CreditCard  
    It is not necessary to provide this while importing an order from external system.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `fundingSource` (_string_, nullable) Funding source, for example, CREDIT, DEBIT, or CHARGED.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `tip` (_number_) Refunded Tip.
*   `tenderBalance` (_number_) Gift Card balance after refund. Available in case of Gift Card refund.
*   `cardAlias` (_string_, nullable) Card alias of the card to which payment was refunded.
*   `externalPaymentSystemId` (_string_, nullable) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_, nullable) External payment reference identifier in case of External tender.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### OrderActivityLog

The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) The unique Id identifying the transaction.  
    Maximum length: 128. Example: `2808-10-20240419131925-2-7`.
*   `amount` (_number_, nullable) The total transaction amount value.
*   `associateSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `data` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `installationId` (_string_, required, read-only) Unique ID of the register.  
    Maximum length: 128.
*   `productId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `storeAssociateId` (_string_, nullable) The Id of the particular associate at a store.
*   `storeId` (_string_, nullable) The identifier of the store where the order is taking place.  
    Maximum length: 128.
*   `transactionDate` (_string (date-time)_, required) Transaction time, that is, the time when the transaction was executed.
*   `transactionType` (_string_, nullable) The type of transaction. Three types of transactions can be done on an order: SALE, RETURN, and EXCHANGE.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.
*   `userSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `appTransactionId` (_string_, nullable) Unique sequence number generated by POS App. It is reset after daily or relaunch of the App.  
    Maximum length: 48. Example: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ...`.
*   `transactionData` (_Transaction_, required)
*   `manualReceiptId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `s3KeyTransactionData` (_string_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `transactionStartDate` (_string (date-time)_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `receiptPrintCount` (_integer (int32)_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### OrderFiscalData

All fiscal data for this order if any.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier which lead to this payment capture/refund.
*   `transactionType` (_string_) Transaction Type.
*   `fiscalData` (_string_) Fiscalization Data.
*   `printData` (_array of PrintData_) Fiscalization Data that needs to be printed on receipt.
*   `fiscalTransactionId` (_string_) Fiscal Transaction ID.
*   `receiptPrintCount` (_integer (int32)_) Combined Count of transaction paper/e-receipts.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### OrderReturnCustomerInformation

List of customer/person who returned the items. Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier.
*   `firstName` (_string_) First name of the person.
*   `lastName` (_string_) Last name of the person.
*   `email` (_string_) Email of the person.
*   `phone` (_string_) Phone number of the person.
*   `addressLine1` (_string_) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_) City.
*   `state` (_string_) State.
*   `postalCode` (_string_) Postal Code.
*   `country` (_string_) Country.
*   `idType` (_string_) ID Type.
*   `idValue` (_string_) ID Value.
*   `idIssuedBy` (_string_) ID Issued By.
*   `idExpiry` (_string (date-time)_) ID Expiry Date.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### TaxFreeDocument

Tax-free document associated with this order.

*   `docId` (_string_) Global Blue tax-free document identifier.
*   `status` (_string_) Current status of the tax-free document (ISSUED or VOIDED).  
    Allowed values: `ISSUED`, `VOIDED`.

### OrderRefundFeeDetail

List of Refund fee like restocking fee on returned or canceled items.  
Applicable when item is returned or canceled and refund fee is configured.  
For more detail on refund fee,

*   `orderId` (_string_) OrderID towards the refund fees are applied.
*   `transactionId` (_string_) Refund transactionId during which refund fees are applied.
*   `storeId` (_string_) Store where the refund is performed.
*   `refundFeeId` (_string_) Refund fee id Eg. Restocking, Miscellaneous.
*   `refundFeeLabel` (_string_) Refund fee display name Eg. Restocking Fee, Miscellaneous Fee.
*   `refundFeeAmount` (_number_) Refund fee amount.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### Transaction

The transaction details.

*   `transactionTimeStamp` (_integer (int64)_, required) Timestamp from when the transaction was executed. Epoch time in milliseconds.  
    Example: `1714112491`.
*   `transactionType` (_TransactionType_)
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128.
*   `summary` (_CartSummary_, required)
*   `storeAttribution` (_StoreAttribution_)
*   `receiptPrintCount` (_integer (int32)_, nullable) Receipt print count — the number of original and duplicate receipts.  
    Default: `1`.
*   `fiscalData` (_OrderFiscalData_)
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions. Applicable for tax countries and if the sale is tax exempted.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `tenders` (_array of OrderPaymentDetails_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Refund payments. If it is a return or exchange transaction, it will have refund payments.
*   `shippingAddress` (_Address_)
*   `shippingMethod` (_ShippingMethod_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products in this order. The list doesn't include returned products. Required for sale transactions. For returns where all items were returned, the list is empty.
*   `returnProductList` (_array of Product_, nullable) List of items that have been returned. It is mandatory for return and exchange transaction.
*   `numberOfLineItems` (_integer (int32)_, read-only) Total number of line items.
*   `receiptId` (_string_, read-only, nullable) Receipt ID for the transaction. Applicable for fiscal reporting.
*   `store` (_Store_, required)
*   `profile` (_Profile_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `returnProductPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `customerEmail` (_string_, nullable) Customer email ID. Available for signed-in customers or when email is captured in the shipping address for guest customers.  
    Maximum length: 128.
*   `manualReceiptId` (_string_, nullable) Manual receipt ID. Required in some countries like Portugal where a pre-printed paper receipt with its own receipt ID needs to be issued for offline transactions.
*   `offlineMode` (_boolean_, nullable) Flag indicating if the transaction was executed in offline mode or not.  
    Default: `false`.
*   `referenceReceiptId` (_string_, nullable) Reference receipt ID. Populated for return and exchange transactions. This field provides original sale's receipt ID for reference.
*   `storeAssociate` (_Associate_)
*   `duplicateReceiptText` (_string_) For internal use only. Don't use in external systems. Duplicate receipt text printed on the receipt, for example, 'Duplicata' or 'Copy of Original Document'.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `productNotesList` (_array of OrderDetailNote_, nullable) List of product notes for this transaction if any.
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `employee` (_Employee_)
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method, and other delivery details. This field is used for item level shipping method and address. Mandatory for all delivery items if item level shipping method or item level shipping address is enabled. For more details, see:.
*   `deliveryGroupChangeList` (_ProductDeltaDeliveryGroup_)
*   `nafCode` (_string_, nullable) NAF code. NAF codes in France are used to identify the type of business of an enterprise. For example, 4772A means retail sale of footwear.
*   `rewardList` (_array of Reward_, read-only, nullable, deprecated) Deprecated. Use `orderProductList.priceAdjustments` instead.
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `productPickUpDetailList` (_array of ProductPickUpDetail_, nullable) List of product pickup detail.  
    Applicable if the order is edit order.
*   `returnCustomerInformation` (_ReturnCustomerInformation_)
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Fulfillment type for the order. For example, IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `removedDeliveryGroups` (_array of DeliveryGroup_, nullable) The removed delivery group during the edit order mode.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### PrintData

Print Data object. Used to print fiscalization related information on receipts.

*   `name` (_string_) Name of the field which holds this value.
*   `value` (_string_) Actual value that will be printed.
*   `label` (_string_) Label against which this value will be printed.
*   `type` (_string_) Indicates type of data to be printed, for example, TEXT or QRCode.  
    Allowed values: `Text`, `QRCode`.

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### TransactionType

The type of transaction. Three types of transactions can be done on an order: SALE, RETURN and EXCHANGE.

Type: `string`.

Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`, `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### OrderPaymentDetails

Payment information: The system supports multiple payment options.  
Whenever an order is purchased using payment instrument/s,  
the order will have this list of tenders. However, there are some exceptional scenarios  
where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### Associate

Store associate.

*   `storeAssociateID` (_string_) ID of the store associate (POS login ID for the associate).
*   `storeID` (_string_, nullable) Store ID of the associate.
*   `merchantUserID` (_string_, nullable) Merchant's underlying system's user ID for the store associates. For example, LoginId for underlying OMS or Salseforce Commerce.
*   `paymentDeviceMerchantID` (_string_, nullable) Merchant ID of a payment device assigned to the associate.
*   `paymentDeviceID` (_string_, nullable) ID of a payment device, like terminal ID, assigned to the associate.
*   `storeAssociatePassword` (_string_) Store associate's password (POS Login Password for the associate).
*   `merchantPassword` (_string_, nullable) Merchant's underlying system's password for the associate.
*   `storeAssociatePasswordPin` (_string_, nullable) Password hint for the associate's POS login.
*   `firstName` (_string_, nullable) First name of the associate.
*   `lastName` (_string_, nullable) Last name of the associate.
*   `storeType` (_string_) Type of the store where the associate works. Possible values include: Regular, Popup, Outlet or eComm.
*   `role` (_string_) The associate's role in the store. Possible values include: STORE\_ASSOCIATE, STORE\_MANAGER or AREA\_MANAGER.
*   `passwordSetOn` (_integer (int64)_, nullable) Date when password was set last time. Represented as the number of milliseconds since epoch.
*   `storeAssociatePasswordFlag` (_boolean_) Flag indicating that the store associate password is updated during associate update operation. Used only during update operation.
*   `merchantPasswordFlag` (_boolean_) Flag indicating that the merchant password is updated during associate update operation. Used only during update operation.
*   `storeAssociateSecretFlag` (_boolean_, nullable) Flag indicating that the store associate secret is updated during associate update operation. Used only during update operation.
*   `imageUrl` (_string_, nullable) The associate's image URL.
*   `active` (_boolean_) Specifies whether the status of the associate is active (true) or removed/deactivated (false).
*   `emailId` (_string_, nullable) Email ID of the associate.
*   `mobilePhoneNumber` (_string_, nullable) Mobile phone number of the associate.
*   `additionalStoreIDs` (_array of string_, nullable) Additional store IDs where the associate can log in.
*   `gender` (_string_) Gender of the store associate.  
    Allowed values: `Male`, `Female`, `Neutral`, `Unknown`.
*   `hireDate` (_integer (int64)_, nullable) Date when the associate is hired or can start work in the store.
*   `terminationDate` (_integer (int64)_, nullable) Termination date for the associate.
*   `firstLoginPasswordReset` (_boolean_) Flag indicating that the password is set on the first login.
*   `mobileConfigID` (_string_, nullable) Mobile configuration ID.  
    Maximum length: 128. Example: `134ac374-0f49-4239-a161-ccfe4d3d7686`.

### ProductDeltaDeliveryGroup

List of delivery groups for product.  
, corresponding order item id and new delivery group id.  
It is used for edit order only when changing the delivery group for existing item.

*   `deliveryGroupId` (_string_, required) Delivery group id. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.

### ProductPickUpDetail

List of product pickup detail.  
Applicable if the order is edit order.

*   `orderItemId` (_string_)
*   `pickupDetailId` (_string_)
*   `pickupLocation` (_Store_)
*   `dateTimeSlot` (_DateTimeSlot_)

### ReturnCustomerInformation

Return - Customer Information. For return or exchange transactions, use this object to capture information about the person returning the items. Note: This might or might not be the actual customer who purchased the items. This object is exclusively to capture information about the person returning items.

*   `firstName` (_string_, nullable) First Name.
*   `lastName` (_string_, nullable) Last Name.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `email` (_string_, nullable) Email ID.
*   `address` (_Address_)
*   `personalId` (_PersonalID_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### PersonalID

Customer/Person Identification Information.

*   `type` (_string_, nullable) ID type, for example, State ID, Military ID, or Driving License.
*   `value` (_string_, nullable) ID Number/Value.
*   `expiry` (_string (date-time)_, nullable) ID Expiration Date.
*   `issuedBy` (_string_, nullable) Issued by state.

<!-- document id=2c6d2020300356073763df591d28dd456dc56fb9124af37c037f411f26bb85d9 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-client-side-example-for-card.md -->

# Example: Create a Saved Payment Method for a Card

Provide both `expiryYear` and `expiryMonth` when creating Saved Payment Method (SPM) for a card. If either field is missing or the card is expired, the SPM isn’t created. Additionally, include the `last4` field.

If the input is valid, Salesforce creates the record and returns the SPM ID.

**Sample JSON request**

```json
{
  "merchantAccountId": "8zbSM0000000CxFYAU",
  "referenceOwnerId": "001SM00000GPtUqYAL",
  "paymentGatewayId": "0b0SM0000002VJ3YAM",
  "gatewayReference": "cus_Ssp02fOccymkwz",
  "status": "Active",
  "type": "card",
  "usageType": "OffSession",
  "name": "Visa....1111",
  "checksum": "unique_hash_ahht",
  "gatewayToken": "pm_1Rx3MvRBJ3juuXWQYIxYgVMc",
  "ProcessingMode": "External",
  "expiryYear": "2030",
  "expiryMonth": "09"
}
```

**Sample JSON response**

```json
{
  "id": "12qSM000000qKx7YAE",
  "success": true,
  "errors": []
}
```

<!-- document id=f9a80e5e4833d74833bffc5290093eee36aa5e8fbff37ca28ef5e4ea29417f48 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-import-tokens-create-example-for-card.md -->

# Example: Create a Saved Payment Method for a Card

Provide both `expiryYear` and `expiryMonth` when creating Saved Payment Method (SPM) for a card. If either field is missing or the card is expired, the SPM isn’t created. Additionally, include the `last4` field. If the input is valid, Salesforce creates the record and returns the SPM ID.

**Sample JSON request**

```json
{
  "merchantAccountId": "8zbSM0000000CxFYAU",
  "referenceOwnerId": "001SM00000GPtUqYAL",
  "paymentGatewayId": "0b0SM0000002VJ3YAM",
  "gatewayReference": "cus_Ssp02fOccymkwz",
  "status": "Active",
  "type": "card",
  "usageType": "OffSession",
  "name": "Visa....1111",
  "checksum": "unique_hash_ahht",
  "gatewayToken": "pm_1Rx3MvRBJ3juuXWQYIxYgVMc",
  "ProcessingMode": "External",
  "expiryYear": "2030",
  "expiryMonth": "09"
}
```

**Sample JSON response**

```json
{
  "id": "12qSM000000qKx7YAE",
  "success": true,
  "errors": []
}
```

Here’s a sample UI showing example records created via the SPM sObject API.

You can view the saved payment methods created in your Salesforce org, open the App launcher and select **Saved Payment Methods**.

![Example of a saved payment method record for a card payment type showing field values and status](https://developer.salesforce.com/media/d2c-commerce/example_spm_card.png '{"class": "image-lg", "title": "Saved Payment Method for a Card"}')

<!-- document id=2ac9d85dabbf986320b9c77c60d8841d38b7e9cb73e7e4561e3cea97a3bbcaeb url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-client-side-example-for-bankorapm.md -->

# Example: Create a Saved Payment Method for Alternative Payment Method

Create Saved Payment Methods for bank or alternative payment methods in one of two ways:

- Salesforce-Supported Types: Use supported types, such as `sepa_debit`, `bancontact`, `ideal`, `us_bank_account` (ACH), `bacs_debit`, and `au_becs_debit`

  Or

- Extended Payment Method Types: If the `type` isn’t supported by Salesforce, set `type` to `extd_apm_type` and provide the exact payment method type recognized by your payment gateway in the `extendedPaymentMethodType` field.

**note:** The `ExtendedPaymentMethodType` field and extended types (`extd_apm_type`, `extd_wallet`) are supported only for third-party gateways.

**Sample JSON request**

```json
{
  "merchantAccountId": "8zbSM0000000EkXYAU",
  "referenceOwnerId": "001SM00000GPtUqYAL",
  "paymentGatewayId": "0b0SM0000002nsfYAA",
  "status": "Active",
  "usageType": "OFFSESSION",
  "name": "AmazonPay...001",
  "gatewayReference": "cus_TS4IZLLrrbsYce",
  "gatewayToken": "pm_1SVA9qIQmmvzCzdJsQb2fogA",
  "last4": "1234",
  "type": "extd_apm_type",
  "checksum": "UNIQUE_GATEWAY_HASH_Wallet_1090901",
  "extendedPaymentMethodType": "klarna"
}
```

**Sample JSON response**

```json
{
  "id": "12qSM000000qKx7YAE",
  "success": true,
  "errors": []
}
```

<!-- document id=09cb7a0b0003d65649c97ae4d376792629318a6cd08d58b6124156ebde9c67ef url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-import-tokens-create-example-for-bankorapm.md -->

# Example: Create a Saved Payment Method for Bank or Alternative Payment Method

Create Saved Payment Methods (SPM) for bank or alternative payment methods in one of two ways:

- Salesforce-Supported Types: Use supported types, such as `sepa_debit`, `bancontact`, `ideal`, `us_bank_account` (ACH), `bacs_debit`, and `au_becs_debit`.

  Or

- Extended Payment Method Types: If the `type` isn’t supported by Salesforce, set `type` to `extd_apm_type` and provide the exact payment method type recognized by your payment gateway in the `extendedPaymentMethodType` field.

**note:** The `ExtendedPaymentMethodType` field and extended types (`extd_apm_type`, `extd_wallet`) are supported only for third-party gateways.

**Sample JSON request**

```json
{
  "merchantAccountId": "8zbSM0000000EkXYAU",
  "referenceOwnerId": "001SM00000GPtUqYAL",
  "paymentGatewayId": "0b0SM0000002nsfYAA",
  "status": "Active",
  "usageType": "OFFSESSION",
  "name": "AmazonPay...001",
  "gatewayReference": "cus_TS4IZLLrrbsYce",
  "gatewayToken": "pm_1SVA9qIQmmvzCzdJsQb2fogA",
  "last4": "1234",
  "type": "extd_apm_type",
  "checksum": "UNIQUE_GATEWAY_HASH_Wallet_1090901",
  "extendedPaymentMethodType": "klarna"
}
```

**Sample JSON response**

```json
{
  "id": "12qSM000000qKx7YAE",
  "success": true,
  "errors": []
}
```

Here’s a sample UI showing example records created for `extd_apm_type`.
**note:** In this example, `ExtendedPaymentMethodType` is set to klarna for testing. You can use any value not supported by Salesforce and customize your implementation as needed.

![Example of a saved payment method record for a bank or alternative payment method showing field values and status](https://developer.salesforce.com/media/d2c-commerce/example_spm_apm.png '{"class": "image-lg", "title": "Saved Payment Method for Bank or Alternative Payment Method"}')

<!-- document id=0202e8b1331884eaf9e507ad27b9411e443c76f2225e3bdc4460842bf628ef6d url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-client-side-example-for-wallet.md -->

# Example: Create Saved Payment Method for Wallet

Set the type field to `extd_wallet` and provide the exact wallet payment type expected by your payment gateway in the `extendedPaymentMethodType` field to create Saved Payment Method (SPM) for a wallet payment method.

**Sample JSON request**

```json
{
  "merchantAccountId": "8zbSM0000000F8jYAE",
  "referenceOwnerId": "001SM00000FwMhEYAV",
  "paymentGatewayId": "0b0SM0000002oLhYAI",
  "Status": "Active",
  "usageType": "OFFSESSION",
  "Name": "AmazonPay...001",
  "GatewayReference": "cus_TEGn3J3WI5onpb",
  "gatewayToken": "pm_1SHoagRO2MG01L0jLSbc4sdm",
  "last4": "1234",
  "type": "extd_wallet",
  "Checksum": "UNIQUE_GATEWAY_HASH_Wallet_10001",
  "ExtendedPaymentMethodType": "amazon_pay"
}
```

**Sample JSON response**

```json
{
  "id": "12qSM000000qfS6YAI",
  "success": true,
  "errors": []
}
```

<!-- document id=ee4c18c16b454bb1a19a40d3de9285da5aeb33dabea09d855475db91b0157b4b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-import-tokens-create-example-for-wallet.md -->

# Example: Create Saved Payment Method for Wallet

Set the `type` field to `extd_wallet` and provide the exact wallet payment type expected by your payment gateway in the `extendedPaymentMethodType` field to create Saved Payment Method (SPM) for a wallet payment method.

**Sample JSON request**

```json
{
  "merchantAccountId": "8zbSM0000000F8jYAE",
  "referenceOwnerId": "001SM00000FwMhEYAV",
  "paymentGatewayId": "0b0SM0000002oLhYAI",
  "Status": "Active",
  "usageType": "OFFSESSION",
  "Name": "AmazonPay...001",
  "GatewayReference": "cus_TEGn3J3WI5onpb",
  "gatewayToken": "pm_1SHoagRO2MG01L0jLSbc4sdm",
  "last4": "1234",
  "type": "extd_wallet",
  "Checksum": "UNIQUE_GATEWAY_HASH_Wallet_10001",
  "ExtendedPaymentMethodType": "amazon_pay"
}
```

**Sample JSON response**

```json
{
  "id": "12qSM000000qfS6YAI",
  "success": true,
  "errors": []
}
```

Here’s a sample UI showing example records created for `extd_wallet`.
**note:** In this example, `ExtendedPaymentMethodType` is set to amazon_pay for testing. You can use any value not supported by Salesforce and customize your implementation as needed.

![Example of a saved payment method record for a wallet payment type showing field values and status](https://developer.salesforce.com/media/d2c-commerce/example_spm_wallet.png '{"class": "image-lg", "title": "Saved Payment Method for Wallet"}')

<!-- document id=56b6a74cde48280fb3c50051cf5825c6741d717d0b19c834786e2fab1306899d url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/instore-pickup.md -->

# Expand Shopping Options with In-Store Pickup

Shop by store and provide in-store pickup for online orders in your composable storefront app by using PWA Kit 3.11 and later from the [Retail React app template](https://pwa-kit.mobify-storefront.com/). Adding an option for shoppers to pick up their orders from a store boosts the store’s sales and provides more flexibility to shoppers.

In-store pickup depends on the Shop the Store feature, which enables refining search results for a specific store. Shoppers can refine search results and category-browse through the In Stock checkbox on the Product Listing Page (PLP). For more information, see [Shop the Store](https://help.salesforce.com/s/articleView?id=cc.b2c_shop_the_store.htm&type=5) in _Salesforce Help_.

## Prerequisites

- Set up a store locator. See [Boost In-Store Sales with Store Locator](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/store-locator.html).
- Set up a store with an inventory list and enable Shop the Store. See [Enable Shop the Store](https://help.salesforce.com/s/articleView?id=cc.b2c_enable_shop_the_store.htm&type=5) in _Salesforce Help_.
- Build your site with:
  - The [Retail React app template](https://pwa-kit.mobify-storefront.com/)
  - Retail React App version 7.0 or later
  - Commerce SDK React version 3.4.0 or later

## Implement In-Store Pickup in Your App

1. Ensure you have the necessary custom attributes. See [In-Store Pickup Attribute Reference](#in-store-pickup-attribute-reference).
2. In your cloned [pwa-kit GitHub repository](https://github.com/SalesforceCommerceCloud/pwa-kit/), enable store locator in [config/default.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/config/default.js) by setting the `storeLocatorEnabled` value to `true` if you haven't already.

```
   module.exports = {
    app: {
        ...
        storeLocatorEnabled: true
    },
```

3. Enable in-store pickup.
   - In Business Manager, click App Launcher, and then select **Merchant Tools > Ordering > Shipping Methods**.
   - Under Store Pick Up, click **Store Pickup Enabled**.

## In-Store Pickup Attribute Reference

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


### Custom Attributes

Set up these custom attributes for the in-store pickup feature.

#### ShippingMethod: `storePickupEnabled`

- Type: boolean
- Custom attribute definition in `system-objecttype-extensions.xml`: [storePickupEnabled](https://github.com/SalesforceCommerceCloud/storefrontdata/blob/master/demo_data_sfra/meta/system-objecttype-extensions.xml#L4226)
- Description: The `storePickupEnabled` attribute determines whether the shipping method appears as an in-store shipping method.

#### Shipment: `fromStoreId`

- Type: string
- Custom attribute definition in `system-objecttype-extensions.xml`: [fromStoreId](https://github.com/SalesforceCommerceCloud/storefrontdata/blob/master/demo_data_sfra/meta/system-objecttype-extensions.xml#L4158)
- Description: The `fromStoreId` attribute is used to store an ID reference to a given Store object on a shipment level.

### System Attributes

System attributes are part of your B2C Commerce instance. They don't require any setup.

#### Store: `inventoryListID`

- Type: string
- Description: Use this field to store an ID reference to a store’s associated inventory list (or external inventory ID when using an API). This field is the inventory list used to determine product availability. Upon adding it to cart, it will also be associated with the ProductLineItem via the `productInventoryListID` field. Note that this system field is different than the custom attribute with the same name but different capitalization: `inventoryListId`.

<!-- document id=713fefbbb8b3c7a932bf609c10f1548373cfed9e65cee8aead85803ce2a4ea42 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/experiences.md -->

Experiences

# Experiences

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/experiences/experiences-oas-v1-public.yaml)

## API Overview

The Experiences API provides a unified endpoint for creating and updating Page Designer pages in B2C Commerce Cloud. Use this API to programmatically create new pages or update existing pages with comprehensive configuration options.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.experience.rw` in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Use Cases

#### Unified Create/Update

Create new pages or update existing Page Designer pages with comprehensive configuration.

#### Component configuration

Define and configure page components with their associated data.

#### Region Setup

Set up page regions and assign components to them.

#### Custom Properties

Create custom attributes using the c\_\* property pattern.

#### SEO Support

Configure page-level SEO metadata including titles, descriptions, and keywords.

### Usage Guidelines

This API is specifically designed for single page creation operations.

*   The Page ID must be unique within the site.
*   Newly created pages are in draft status by default.
*   Existing pages are updated with provided data (partial updates supported).
*   Page Activation: To make a page active/published, use the Business Manager UI to change the page status from draft to active.
*   Custom properties (c\_\*) are supported through the open object pattern.
*   All text fields support localization through the Commerce Cloud localization framework.
*   This API supports both create and update operations using PUT semantics.

### Related APIs

*   [Shopper Experience](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary) — Retrieve Page Designer pages and content for shoppers.

**Version:** 1.4.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/experience/experiences/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 authentication for admin operations
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/oauth2/token)
    *   Scope sfcc.experiences: Read-only access to merchandiser experiences
    *   Scope sfcc.experiences.rw: Read and write access to merchandiser experiences

## Operations

### PUT Create or update a Page Designer page.

`PUT /organizations/{organizationId}/pages/{pageId}`

Operation ID: `createOrUpdatePage`. Security: AmOAuth2 (sfcc.experiences.rw).

This API is designed specifically for single page creation or updating existing pages with all necessary metadata, regions, and components.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   By default, the created page is in draft status.
*   Page ID in URL must match the page ID in the request body.
*   All required fields must be provided in the request body.
*   This API supports both create and update operations using PUT semantics.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `pageId` (path, string, required) Identifier for the requested page.  
    Maximum length: 256. Example: `homepage`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PageRequest`.

_Example: CreatePageRequest_ Example request to create a new page

```
{
  "id": "new-homepage",
  "typeId": "storePage",
  "aspectTypeId": "pdpAspect",
  "name": "New Homepage",
  "description": "New home page for the storefront",
  "pageTitle": "New Homepage - My Shop",
  "pageDescription": "Welcome to our new homepage",
  "pageKeywords": "homepage, fashion, my shop",
  "thumbnail": "new-homepage.jpg",
  "data": {
    "site_map_priority": 0.8,
    "layout": "default"
  },
  "regions": [
    {
      "id": "header",
      "components": [
        {
          "id": "welcome-banner",
          "typeId": "commerce_assets.banner",
          "data": {
            "title": "Welcome to Our New Store",
            "bannerImage": "welcome-banner.jpg"
          }
        }
      ]
    },
    {
      "id": "main",
      "components": [
        {
          "id": "featured-products",
          "typeId": "commerce_assets.carousel",
          "data": {
            "title": "Featured Products",
            "category": "featured"
          }
        }
      ]
    },
    {
      "id": "footer",
      "components": []
    }
  ]
}
```

_Example: UpdatePageRequest_ Example request to update an existing page

```
{
  "id": "new-homepage",
  "typeId": "storePage",
  "name": "Updated Homepage",
  "description": "Updated home page for the storefront",
  "pageTitle": "Updated Homepage - My Shop",
  "pageDescription": "Welcome to our updated homepage",
  "data": {
    "thumbnail": "updated-homepage.jpg",
    "priority": 1
  },
  "regions": [
    {
      "id": "header",
      "components": [
        {
          "id": "welcome-banner",
          "typeId": "commerce_assets.banner",
          "data": {
            "title": "Updated Welcome Banner",
            "bannerImage": "updated-welcome-banner.jpg"
          }
        }
      ]
    }
  ]
}
```

#### Responses

*   **200** Page updated successfully
    
    Media type: `application/json`. Schema: `Page`.
    
    _Example: UpdatedPage_ Example response for a successfully updated page
    
    ```
    {
      "id": "new-homepage",
      "typeId": "storePage",
      "aspectTypeId": "pdpAspect",
      "name": "Updated Homepage",
      "description": "Updated home page for the storefront",
      "pageTitle": "Updated Homepage - My Shop",
      "pageDescription": "Welcome to our updated homepage",
      "data": {
        "thumbnail": "updated-homepage.jpg",
        "priority": 1
      },
      "custom": {
        "thumbnail_full": "http://static.myshop.com/updated-homepage.jpg"
      },
      "regions": [
        {
          "id": "header",
          "components": [
            {
              "id": "welcome-banner",
              "typeId": "commerce_assets.banner",
              "data": {
                "title": "Updated Welcome to Our New Store",
                "bannerImage": "updated-welcome-banner.jpg"
              },
              "custom": {
                "banner_url": "http://static.myshop.com/updated-welcome-banner.jpg"
              }
            }
          ]
        }
      ],
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-01-15T11:00:00.000Z",
      "online": true
    }
    ```
    
*   **201** Page created successfully
    
    Media type: `application/json`. Schema: `Page`.
    
    _Example: CreatedPage_ Example response for a successfully created page
    
    ```
    {
      "id": "new-homepage",
      "typeId": "storePage",
      "aspectTypeId": "pdpAspect",
      "name": "New Homepage",
      "description": "New home page for the storefront",
      "pageTitle": "New Homepage - My Shop",
      "pageDescription": "Welcome to our new homepage",
      "pageKeywords": "homepage, fashion, my shop",
      "thumbnail": "new-homepage.jpg",
      "data": {
        "site_map_priority": 0.8,
        "layout": "default"
      },
      "custom": {
        "thumbnail_full": "http://static.myshop.com/new-homepage.jpg"
      },
      "regions": [
        {
          "id": "header",
          "components": [
            {
              "id": "welcome-banner",
              "typeId": "commerce_assets.banner",
              "data": {
                "title": "Welcome to Our New Store",
                "bannerImage": "welcome-banner.jpg"
              },
              "custom": {
                "banner_url": "http://static.myshop.com/welcome-banner.jpg"
              }
            }
          ]
        },
        {
          "id": "main",
          "components": [
            {
              "id": "featured-products",
              "typeId": "commerce_assets.carousel",
              "data": {
                "title": "Featured Products",
                "category": "featured"
              },
              "custom": {
                "carousel_url": "http://static.myshop.com/featured"
              }
            }
          ]
        },
        {
          "id": "footer",
          "components": []
        }
      ],
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z",
      "online": false
    }
    ```
    
*   **400** Invalid page data provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidPageData_ Example error response for invalid page data
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The request body contains invalid page data",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/required-field-missing",
          "detail": "Required field 'id' is missing",
          "field": "id"
        }
      ]
    }
    ```
    
    _Example: MissingSiteId_ Example error response for missing site ID
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The siteId query parameter is required",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/required-parameter-missing",
          "detail": "The siteId query parameter is required",
          "field": "siteId"
        }
      ]
    }
    ```
    
    _Example: PageIdMismatch_ Example error response for page ID mismatch between path and body
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-id-mismatch",
      "title": "Page Id Mismatch",
      "detail": "The page ID in the request path ('path-id') doesn't match the page ID in the request body ('body-id').",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/path-id",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-id-mismatch",
          "detail": "The page ID in the request path ('path-id') doesn't match the page ID in the request body ('body-id').",
          "pathPageId": "path-id",
          "bodyPageId": "body-id"
        }
      ]
    }
    ```
    
    _Example: MissingTypeId_ Example error response for missing typeId field
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Field 'typeId' cannot be empty",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
          "detail": "Field 'typeId' cannot be empty.",
          "field": "typeId"
        }
      ]
    }
    ```
    
    _Example: InvalidPageType_ Example error response for invalid page type ID during page creation
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "No page type with ID 'invalidPageType' was found in site 'RefArch'.",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
          "detail": "No page type with ID 'invalidPageType' was found in site 'RefArch'.",
          "field": "typeId",
          "pageTypeId": "invalidPageType",
          "site": "RefArch"
        }
      ]
    }
    ```
    
    _Example: InvalidPageId_ Example error response for invalid page ID format
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid",
      "title": "Content Id Invalid",
      "detail": "The ID 'test page' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;=",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/test page",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid",
          "detail": "The ID 'test page' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;=",
          "id": "test page",
          "field": "id"
        }
      ]
    }
    ```
    
    _Example: UnsupportedAspectType_ Example error response for unsupported aspect type
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-aspect-type",
      "title": "Unsupported Aspect Type",
      "detail": "The aspect type 'invalidAspectType' isn't supported for page type 'storePage'.",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-aspect-type",
          "detail": "The aspect type 'invalidAspectType' isn't supported for page type 'storePage'.",
          "aspectType": "invalidAspectType",
          "pageType": "storePage",
          "field": "aspectTypeId"
        }
      ]
    }
    ```
    
    _Example: InvalidCustomDataFormat_ Example error response for invalid custom data format
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Field 'data' must be an object",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
          "detail": "Field 'data' must be an object",
          "field": "data"
        }
      ]
    }
    ```
    
    _Example: InvalidVisibilityRule_ Example error response for invalid visibility rule format
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Field 'customerGroups' must be an array/list, but was: String",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-field-value",
          "detail": "Field 'customerGroups' must be an array/list, but was: String",
          "field": "data.visibilityRule.customerGroups"
        }
      ]
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified site ID does not exist.
    *   An existing page's page type is missing or invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: SiteNotFound_ Example error response for site not found
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "title": "Not Found",
      "detail": "The specified site does not exist",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
          "detail": "Site with ID 'invalid-site' does not exist",
          "field": "siteId"
        }
      ]
    }
    ```
    
    _Example: PageTypeNotFound_ Example error response for page type not found when retrieving an existing page.
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-type-not-found",
      "title": "Page Type Not Found",
      "detail": "No page type with ID 'invalidPageType' was found for page 'test-page' in site 'RefArch'.",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/test-page",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-type-not-found",
          "detail": "No page type with ID 'invalidPageType' was found for page 'test-page' in site 'RefArch'.",
          "pageTypeId": "invalidPageType",
          "pageId": "test-page",
          "site": "RefArch"
        }
      ]
    }
    ```
    
*   **409** Page ID mismatch or validation error.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: PageIdConflict_ Example error response for page ID conflict
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-already-in-use",
      "title": "Conflict",
      "detail": "A Page with the specified ID already exists.",
      "instance": "/experience/experiences/v1/organizations/f_ecom_zzrf_001/pages/new-homepage",
      "issues": [
        {
          "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-already-in-use",
          "detail": "Page with ID 'new-homepage' already exists in the site.",
          "field": "id"
        }
      ]
    }
    ```
    

### GET Get a content folder

`GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}`

Operation ID: `getContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw).

Retrieves detailed information about a specific content folder within a library.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The folder must exist in the specified library.
*   Returns localized content if available.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Responses

*   **200** Content folder retrieved successfully
    
    Media type: `application/json`. Schema: `ContentFolder`.
    
    _Example: RetrievedFolder_ Example response for a successfully retrieved content folder
    
    ```
    {
      "id": "seasonal-content",
      "description": {
        "default": "Localized seasonal folder (Default)"
      },
      "name": {
        "default": "Localized folder (Default)"
      },
      "online": true,
      "parentFolderId": "root",
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-01-15T11:00:00.000Z"
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified library does not exist.
    *   The specified folder does not exist in the library.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    ```
    {
      "title": "Folder Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/folder-not-found",
      "detail": "No content folder with ID 'unknown-folder' in library 'SiteLibrary' could be found."
    }
    ```
    
    _Example: LibraryNotFound_ Example error response for library not found
    
    ```
    {
      "title": "Library Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/library-not-found",
      "detail": "No library with ID 'unknown-library' could be found."
    }
    ```
    

### PUT Create or update a content folder

`PUT /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}`

Operation ID: `createOrUpdateContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw).

Creates a new content folder or updates an existing one in the specified library.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   If the folder doesn't exist, it will be created (201).
*   If the folder exists, it will be updated (200).
*   Folder ID in URL must match the folder ID in the request body.
*   The library must exist before creating folders.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Request body (required)

Media type: `application/json`. Schema: `ContentFolder`.

_Example: CreateFolderRequest_ Example request to create a new content folder

```
{
  "id": "seasonal-content",
  "pageDescription": {
    "default": "Page Descr. (Default)",
    "en": "Page Descr. (en)",
    "en-US": "Page Descr. (en_us)"
  },
  "pageKeywords": {
    "default": "Page Keywords (Default)",
    "en": "Page Keywords (en)",
    "en-US": "Page Keywords (en_us)"
  },
  "parentFolderId": "root",
  "online": false
}
```

_Example: UpdateFolderRequest_ Example request to update an existing content folder

```
{
  "id": "seasonal-content",
  "name": {
    "default": "Localized folder (Default)",
    "en": "Localized folder (en)",
    "en-US": "Localized folder (en_us)"
  },
  "parentFolderId": "root",
  "online": true
}
```

#### Responses

*   **200** Content folder updated successfully
    
    Media type: `application/json`. Schema: `ContentFolder`.
    
    _Example: UpdatedFolder_ Example response for a successfully updated content folder
    
    ```
    {
      "id": "seasonal-content",
      "name": {
        "default": "Localized folder (Default)",
        "en": "Localized folder (en)",
        "en-US": "Localized folder (en_us)"
      },
      "parentFolderId": "root",
      "online": true,
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-01-15T11:00:00.000Z"
    }
    ```
    
*   **201** Content folder created successfully
    
    Media type: `application/json`. Schema: `ContentFolder`.
    
    _Example: CreatedFolder_ Example response for a successfully created content folder
    
    ```
    {
      "id": "seasonal-content",
      "pageDescription": {
        "default": "Page Descr. (Default)",
        "en": "Page Descr. (en)",
        "en-US": "Page Descr. (en_us)"
      },
      "pageKeywords": {
        "default": "Page Keywords (Default)",
        "en": "Page Keywords (en)",
        "en-US": "Page Keywords (en_us)"
      },
      "parentFolderId": "root",
      "online": false,
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z"
    }
    ```
    
*   **400** Invalid folder data provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ContentIdInvalid_ Example error response for invalid folder ID format
    
    ```
    {
      "title": "Content Id Invalid",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-id-invalid",
      "detail": "The ID 'test folder' is invalid. The ID can't have leading or trailing whitespaces. It can only contain alphanumeric characters and the following special characters: _-~:[]@!'*,;="
    }
    ```
    
*   **404** The specified library does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### DELETE Delete a content folder

`DELETE /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}`

Operation ID: `deleteContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw).

Deletes a content folder from the specified library.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The folder must exist to be deleted.
*   This operation cannot be undone.
*   Child folders and content may need to be handled separately.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Responses

*   **204** Content folder deleted successfully
*   **404** The requested resource was not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### PATCH Partially update a content folder

`PATCH /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}`

Operation ID: `patchContentFolder`. Security: AmOAuth2 (sfcc.experiences.rw).

Updates specific properties of an existing content folder without replacing the entire resource.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Only the properties provided in the request body will be updated.
*   The folder must already exist.
*   Useful for updating custom attributes without affecting other properties.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Request body (required)

Media type: `application/json`. Schema: `ContentFolder`.

_Example: PatchFolderRequest_ Example request to partially update a content folder

```
{
  "id": "winter-content",
  "name": {
    "default": "Localized winter content folder (Default)",
    "en": "Localized winter content folder (en)",
    "en-US": "Localized winter content folder (en_us)"
  },
  "parentFolderId": "root",
  "online": false
}
```

#### Responses

*   **200** Content folder updated successfully
    
    Media type: `application/json`. Schema: `ContentFolder`.
    
    _Example UpdatedFolder: same as PUT /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 200 response._ Example response for a successfully updated content folder
    
    _Example: UpdatedFolder_ Example response for a successfully updated content folder
    
*   **400** Invalid folder data provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ContentIdInvalid: same as PUT /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 400 response._ Example error response for invalid folder ID format
    
    _Example: ContentIdInvalid_ Example error response for invalid folder ID format
    
*   **404** The requested resource was not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### GET Get sub-folders of a content folder

`GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}/sub-folders`

Operation ID: `getSubFolders`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves a list of sub-folders (child folders) within a specific content folder.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Returns only direct children of the specified folder.
*   Results can be paginated using limit and offset parameters.
*   Only folders within the specified library are included.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Sub-folders retrieved successfully
    
    Media type: `application/json`. Schema: `ContentSubFolderResult`.
    
    _Example: SubFoldersResult_ Example response for successfully retrieved sub-folders
    
    ```
    {
      "limit": 3,
      "offset": 3,
      "total": 30,
      "hits": [
        {
          "id": "winter-2024",
          "name": {
            "default": "Winter 2024 Collection",
            "en": "Winter 2024 Collection",
            "en-US": "Winter 2024 Collection"
          },
          "description": {
            "default": "Content for winter 2024 season",
            "en": "Content for winter 2024 season"
          },
          "parentFolderId": "seasonal-content",
          "online": true,
          "pageTitle": {
            "default": "Winter 2024",
            "en": "Winter 2024"
          },
          "pageDescription": {
            "default": "Explore our winter collection",
            "en": "Explore our winter collection"
          },
          "pageKeywords": {
            "default": "winter, 2024, seasonal",
            "en": "winter, 2024, seasonal"
          },
          "template": "rendering/folder/seasonal",
          "creationDate": "2024-01-10T09:00:00.000Z",
          "lastModified": "2024-01-10T09:00:00.000Z"
        },
        {
          "id": "spring-2024",
          "name": {
            "default": "Spring 2024 Collection",
            "en": "Spring 2024 Collection"
          },
          "description": {
            "default": "Content for spring 2024 season",
            "en": "Content for spring 2024 season"
          },
          "parentFolderId": "seasonal-content",
          "online": false,
          "pageTitle": {
            "default": "Spring 2024",
            "en": "Spring 2024"
          },
          "pageDescription": {
            "default": "Explore our spring collection",
            "en": "Explore our spring collection"
          },
          "pageKeywords": {
            "default": "spring, 2024, seasonal",
            "en": "spring, 2024, seasonal"
          },
          "template": "rendering/folder/seasonal"
        },
        {
          "id": "summer-2024",
          "name": {
            "default": "Summer 2024 Collection",
            "en": "Summer 2024 Collection"
          },
          "description": {
            "default": "Content for summer 2024 season",
            "en": "Content for summer 2024 season"
          },
          "parentFolderId": "seasonal-content",
          "online": false,
          "pageTitle": {
            "default": "Summer 2024",
            "en": "Summer 2024"
          },
          "pageDescription": {
            "default": "Explore our summer collection",
            "en": "Explore our summer collection"
          },
          "pageKeywords": {
            "default": "summer, 2024, seasonal",
            "en": "summer, 2024, seasonal"
          },
          "template": "rendering/folder/seasonal"
        }
      ]
    }
    ```
    
*   **400** Invalid request parameters provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidLimitParameter_ Example error response for invalid limit parameter
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "The limit parameter must be between 1 and 200."
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified library does not exist.
    *   The specified parent folder does not exist in the library.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### GET Get a content asset

`GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}`

Operation ID: `getContent`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves detailed information about a specific content asset within a library.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The content asset must exist in the specified library.
*   Returns localized content if available.
*   Content assets can contain rich text, HTML, images, and custom attributes.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.

#### Responses

*   **200** Content asset retrieved successfully
    
    Media type: `application/json`. Schema: `ContentAsset`.
    
    _Example: RetrievedContent_ Example response for a successfully retrieved content asset
    
    ```
    {
      "id": "homepage-banner",
      "name": {
        "default": "Homepage Banner",
        "en": "Homepage Banner"
      },
      "description": {
        "default": "Main promotional banner for the homepage",
        "en": "Main promotional banner for the homepage"
      },
      "pageDescription": {
        "default": "Discover amazing products at great prices",
        "en": "Discover amazing products at great prices"
      },
      "pageKeywords": {
        "default": "banner, promotion, homepage",
        "en": "banner, promotion, homepage"
      },
      "pageTitle": {
        "default": "Homepage Banner - My Shop",
        "en": "Homepage Banner - My Shop"
      },
      "folderId": "homepage-folder",
      "online": {
        "default": true
      },
      "template": "rendering/content/banner"
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified library does not exist.
    *   The specified content asset does not exist in the library.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    ```
    {
      "title": "Content Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-not-found",
      "detail": "No content asset with ID 'unknown-content' in library 'SiteLibrary' was found."
    }
    ```
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### PUT Create or update a content asset

`PUT /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}`

Operation ID: `createOrUpdateContent`. Security: AmOAuth2 (sfcc.experiences.rw).

Creates a new content asset or updates an existing one in the specified library.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   If the content asset doesn't exist, it will be created (201).
*   If the content asset exists, it will be updated (200).
*   Content ID in URL must match the content ID in the request body.
*   The library must exist before creating content assets.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.

#### Request body (required)

Media type: `application/json`. Schema: `ContentAsset`.

_Example: CreateContentRequest_ Example request to create a new content asset

```
{
  "id": "homepage-banner",
  "name": {
    "default": "Homepage Banner",
    "en": "Homepage Banner",
    "en-US": "Homepage Banner"
  },
  "description": {
    "default": "Main promotional banner",
    "en": "Main promotional banner"
  },
  "pageDescription": {
    "default": "Discover amazing products",
    "en": "Discover amazing products"
  },
  "pageKeywords": {
    "default": "banner, promotion, homepage",
    "en": "banner, promotion, homepage"
  },
  "pageTitle": {
    "default": "Homepage Banner - My Shop",
    "en": "Homepage Banner - My Shop"
  },
  "folderId": "homepage-folder",
  "online": {
    "default": true
  },
  "template": "rendering/content/banner"
}
```

_Example: UpdateContentRequest_ Example request to update an existing content asset

```
{
  "id": "homepage-banner",
  "name": {
    "default": "Updated Homepage Banner",
    "en": "Updated Homepage Banner"
  },
  "description": {
    "default": "Updated promotional banner",
    "en": "Updated promotional banner"
  },
  "folderId": "homepage-folder",
  "online": {
    "default": true
  }
}
```

#### Responses

*   **200** Content asset updated successfully
    
    Media type: `application/json`. Schema: `ContentAsset`.
    
    _Example: UpdatedContent_ Example response for a successfully updated content asset
    
    ```
    {
      "id": "homepage-banner",
      "name": {
        "default": "Updated Homepage Banner",
        "en": "Updated Homepage Banner"
      },
      "description": {
        "default": "Updated promotional banner",
        "en": "Updated promotional banner"
      },
      "pageTitle": {
        "default": "Homepage Banner - My Shop",
        "en": "Homepage Banner - My Shop"
      },
      "folderId": "homepage-folder",
      "online": {
        "default": true
      }
    }
    ```
    
*   **201** Content asset created successfully
    
    Media type: `application/json`. Schema: `ContentAsset`.
    
    _Example: CreatedContent_ Example response for a successfully created content asset
    
    ```
    {
      "id": "homepage-banner",
      "name": {
        "default": "Homepage Banner",
        "en": "Homepage Banner"
      },
      "description": {
        "default": "Main promotional banner",
        "en": "Main promotional banner"
      },
      "pageDescription": {
        "default": "Discover amazing products",
        "en": "Discover amazing products"
      },
      "pageKeywords": {
        "default": "banner, promotion, homepage",
        "en": "banner, promotion, homepage"
      },
      "pageTitle": {
        "default": "Homepage Banner - My Shop",
        "en": "Homepage Banner - My Shop"
      },
      "folderId": "homepage-folder",
      "online": {
        "default": false
      },
      "template": "rendering/content/banner"
    }
    ```
    
*   **400** Invalid content data provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: UnknownSiteId_ Example error response for unknown site id
    
    ```
    {
      "title": "Unknown Site Id",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unknown-site-id",
      "detail": "The site ID 'NotExistingSite' is unknown."
    }
    ```
    
*   **404** The specified library does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### DELETE Delete a content asset

`DELETE /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}`

Operation ID: `deleteContent`. Security: AmOAuth2 (sfcc.experiences.rw).

Deletes a content asset from the specified library.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The content asset must exist to be deleted.
*   This operation cannot be undone.
*   Any references to this content asset in slots or other resources may need to be updated.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.

#### Responses

*   **204** Content asset deleted successfully
*   **404** The requested resource was not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### PATCH Partially update a content asset

`PATCH /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}`

Operation ID: `patchContent`. Security: AmOAuth2 (sfcc.experiences.rw).

Updates specific properties of an existing content asset without replacing the entire resource.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Only the properties provided in the request body will be updated.
*   The content asset must already exist.
*   Useful for updating specific attributes without affecting other properties.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.

#### Request body (required)

Media type: `application/json`. Schema: `ContentAsset`.

_Example: PatchContentRequest_ Example request to partially update a content asset

```
{
  "id": "homepage-banner",
  "online": {
    "default": true
  },
  "pageTitle": {
    "default": "Updated Homepage Banner - My Shop",
    "en": "Updated Homepage Banner - My Shop"
  }
}
```

#### Responses

*   **200** Content asset updated successfully
    
    Media type: `application/json`. Schema: `ContentAsset`.
    
    _Example UpdatedContent: same as PUT /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 200 response._ Example response for a successfully updated content asset
    
    _Example: UpdatedContent_ Example response for a successfully updated content asset
    
*   **404** The requested resource was not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### GET Get folder information for a content asset

`GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId}/folders`

Operation ID: `getContentFolders`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves folder information associated with a specific content asset, including the parent folder and folder hierarchy.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The content asset must exist in the specified library.
*   Returns the folder path and hierarchy information.
*   Useful for understanding where a content asset is located within the library structure.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Folder information retrieved successfully
    
    Media type: `application/json`. Schema: `ContentFolderResult`.
    
    _Example: ContentFolderInfo_ Example response for content asset folder information
    
    ```
    {
      "limit": 4,
      "offset": 5,
      "total": 20,
      "hits": [
        {
          "id": "homepage-folder",
          "name": {
            "default": "Homepage Folder",
            "en": "Homepage Folder"
          },
          "description": {
            "default": "Folder containing homepage content assets",
            "en": "Folder containing homepage content assets"
          },
          "parentFolderId": "seasonal-content",
          "online": true,
          "pageTitle": {
            "default": "Homepage Folder - My Store",
            "en": "Homepage Folder - My Store"
          },
          "pageDescription": {
            "default": "SEO description for homepage folder"
          },
          "en": "SEO description for homepage folder",
          "pageKeywords": {
            "default": "homepage, main, landing",
            "en": "homepage, main, landing"
          },
          "template": "rendering/folder/homepage"
        },
        {
          "id": "root",
          "name": {
            "default": "Root Folder",
            "en": "Root Folder"
          },
          "online": true
        },
        {
          "id": "seasonal-content",
          "name": {
            "default": "Seasonal Content",
            "en": "Seasonal Content"
          },
          "description": {
            "default": "Folder for seasonal content",
            "en": "Folder for seasonal content"
          },
          "parentFolderId": "root",
          "online": true,
          "pageTitle": {
            "default": "Seasonal Content - My Store",
            "en": "Seasonal Content - My Store"
          },
          "template": "rendering/folder/seasonal",
          "creationDate": "2024-01-05T08:00:00.000Z",
          "lastModified": "2024-01-05T08:00:00.000Z"
        },
        {
          "id": "homepage-folder",
          "name": {
            "default": "Homepage Folder",
            "en": "Homepage Folder"
          },
          "description": {
            "default": "Folder containing homepage content assets",
            "en": "Folder containing homepage content assets"
          },
          "parentFolderId": "seasonal-content",
          "online": true,
          "pageTitle": {
            "default": "Homepage Folder - My Store",
            "en": "Homepage Folder - My Store"
          },
          "pageDescription": {
            "default": "SEO description for homepage folder",
            "en": "SEO description for homepage folder"
          },
          "pageKeywords": {
            "default": "homepage, main, landing",
            "en": "homepage, main, landing"
          },
          "template": "rendering/folder/homepage"
        }
      ]
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified library does not exist.
    *   The specified content asset does not exist in the library.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### GET Get a folder assignment for a content asset

`GET /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}`

Operation ID: `getFolderAssignment`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves information about the assignment relationship between a content asset and a folder.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Returns the assignment details including when it was created and last modified.
*   The content asset must be assigned to the specified folder.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Responses

*   **200** Folder assignment retrieved successfully
    
    Media type: `application/json`. Schema: `ContentFolderAssignment`.
    
    _Example: FolderAssignment_ Example response for a successfully retrieved folder assignment
    
    ```
    {
      "contentId": "homepage-banner",
      "folderId": "homepage-folder",
      "position": 0,
      "default": true
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified library does not exist.
    *   The specified content asset does not exist in the library.
    *   The specified folder does not exist in the library.
    *   The assignment between the content asset and folder does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: AssignmentNotFound_ Example error response for folder assignment not found
    
    ```
    {
      "title": "Assignment Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/assignment-not-found",
      "detail": "No assignment from content asset with ID 'homepage-banner' to content folder with ID 'homepage-folder' in library 'SiteLibrary' could be found."
    }
    ```
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### PUT Create a content folder assignment for a content asset

`PUT /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}`

Operation ID: `createOrUpdateFolderAssignment`. Security: AmOAuth2 (sfcc.experiences.rw).

Creates a new assignment assignment between a content asset and a folder.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   If the assignment doesn't exist, it will be created (201).
*   If the assignment exists, it will be updated (200).
*   Both the content asset and folder must exist before creating the assignment.
*   A content asset can be assigned to multiple folders.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Request body (required)

Media type: `application/json`. Schema: `ContentFolderAssignment`.

_Example: CreateAssignmentRequest_ Example request to create a new folder assignment

```
{
  "contentId": "homepage-banner",
  "folderId": "homepage-folder",
  "position": 3,
  "default": true
}
```

_Example: UpdateAssignmentRequest_ Example request to update an existing folder assignment

```
{
  "contentId": "homepage-banner",
  "folderId": "homepage-folder",
  "position": 2,
  "default": false
}
```

#### Responses

*   **200** Content Folder assignment updated successfully
    
    Media type: `application/json`. Schema: `ContentFolderAssignment`.
    
    _Example: UpdatedAssignment_ Example response for a successfully updated folder assignment
    
    ```
    {
      "contentId": "homepage-banner",
      "folderId": "homepage-folder",
      "position": 8,
      "default": false
    }
    ```
    
*   **201** Content Folder assignment created successfully
    
    Media type: `application/json`. Schema: `ContentFolderAssignment`.
    
    _Example: CreatedAssignment_ Example response for a successfully created folder assignment
    
    ```
    {
      "contentId": "homepage-banner",
      "folderId": "homepage-folder",
      "position": 0,
      "default": true
    }
    ```
    
*   **404** The specified resource does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### DELETE Delete a content folder assignment for a content asset

`DELETE /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}`

Operation ID: `deleteFolderAssignment`. Security: AmOAuth2 (sfcc.experiences.rw).

Removes the assignment relationship between a content asset and a folder.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The assignment must exist to be deleted.
*   This operation cannot be undone.
*   The content asset and folder themselves are not deleted, only their assignment relationship.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Responses

*   **204** Content folder assignment deleted successfully
*   **404** The requested resource was not found.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example AssignmentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId} 404 response._ Example error response for folder assignment not found
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: AssignmentNotFound_ Example error response for folder assignment not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### PATCH Update a content folder assignment for a content asset

`PATCH /organizations/{organizationId}/libraries/{libraryId}/folder-assignments/{contentId}/{folderId}`

Operation ID: `updateFolderAssignment`. Security: AmOAuth2 (sfcc.experiences.rw).

Updates an existing assignment between a content asset and a folder.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   If the assignment doesn't exist, it will be created (201).
*   If the assignment exists, it will be updated (200).
*   Both the content asset and folder must exist before creating the assignment.
*   A content asset can be assigned to multiple folders.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `contentId` (path, string, required) Identifier for the content asset.  
    Maximum length: 256. Example: `homepage-banner`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.

#### Request body (required)

Media type: `application/json`. Schema: `ContentFolderAssignment`.

_Example: CreateAssignmentRequest_ Example request to create a new folder assignment

```
{
  "contentId": "homepage-banner",
  "folderId": "homepage-folder",
  "position": 3,
  "default": true
}
```

_Example: UpdateAssignmentRequest_ Example request to update an existing folder assignment

```
{
  "contentId": "homepage-banner",
  "folderId": "homepage-folder",
  "position": 2,
  "default": false
}
```

#### Responses

*   **200** Content folder assignment updated successfully
    
    Media type: `application/json`. Schema: `ContentFolderAssignment`.
    
    _Example: UpdatedAssignment_ Example response for a successfully updated folder assignment
    
    ```
    {
      "contentId": "homepage-banner",
      "folderId": "homepage-folder",
      "position": 8,
      "default": false
    }
    ```
    
*   **404** The specified resource does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### GET Get content assets in a folder

`GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId}/content`

Operation ID: `getFolderContent`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves a list of content assets within a specific folder.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Returns all content assets directly assigned to the specified folder.
*   Results can be paginated using limit and offset parameters.
*   Content assets are returned with their assignment metadata including sort order.
*   Only content assets assigned to this specific folder are included (not sub-folders).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `libraryId` (path, string, required) Identifier for the content library.  
    Maximum length: 256. Example: `SiteLibrary`.
*   `folderId` (path, string, required) Identifier for the content folder.  
    Maximum length: 256. Example: `seasonal-content`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Content assets retrieved successfully
    
    Media type: `application/json`. Schema: `ContentAssetResult`.
    
    _Example: FolderContentResult_ Example response for content assets in a folder
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 10,
      "hits": [
        {
          "id": "homepage-banner",
          "name": {
            "default": "Homepage Banner",
            "en": "Homepage Banner"
          },
          "description": {
            "default": "Main promotional banner for the homepage",
            "en": "Main promotional banner for the homepage"
          },
          "online": {
            "default": true
          },
          "pageTitle": {
            "default": "Homepage Banner - My Shop",
            "en": "Homepage Banner - My Shop"
          },
          "pageDescription": {
            "default": "Discover amazing products at great prices",
            "en": "Discover amazing products at great prices"
          },
          "pageKeywords": {
            "default": "banner, promotion, homepage",
            "en": "banner, promotion, homepage"
          },
          "folderId": "homepage-folder",
          "template": "rendering/content/banner"
        },
        {
          "id": "hero-image",
          "name": {
            "default": "Hero Image",
            "en": "Hero Image"
          },
          "description": {
            "default": "Hero section image",
            "en": "Hero section image"
          },
          "online": {
            "default": true
          },
          "pageTitle": {
            "default": "Hero Image - My Shop",
            "en": "Hero Image - My Shop"
          },
          "classificationFolderId": "homepage-folder",
          "template": "rendering/content/image"
        },
        {
          "id": "cta-section",
          "name": {
            "default": "Call to Action Section",
            "en": "Call to Action Section"
          },
          "description": {
            "default": "Homepage call to action content",
            "en": "Homepage call to action content"
          },
          "online": {
            "default": true
          },
          "pageTitle": {
            "default": "CTA Section - My Shop",
            "en": "CTA Section - My Shop"
          },
          "classificationFolderId": "homepage-folder",
          "template": "rendering/content/cta"
        }
      ]
    }
    ```
    
*   **400** Invalid request parameters provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidLimitParameter_ Example error response for invalid limit parameter
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "The limit parameter must be between 1 and 200."
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified library does not exist.
    *   The specified folder does not exist in the library.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example FolderNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for folder not found
    
    _Example LibraryNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/folders/{folderId} 404 response._ Example error response for library not found
    
    _Example: FolderNotFound_ Example error response for folder not found
    
    _Example: LibraryNotFound_ Example error response for library not found
    

### GET Get a slot

`GET /organizations/{organizationId}/slots/{slotId}/{contextType}`

Operation ID: `getSlot`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves detailed information about a specific slot including its configurations.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The slot must exist in the specified context.
*   Returns the slot with all associated slot configurations.
*   Context type can be global, category, or folder.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `slotId` (path, string, required) Identifier for the slot  
    Maximum length: 256. Example: `homepage-banner-slot`.
*   `contextType` (path, string, required) Context type for the slot (global, category, or folder)  
    Allowed values: `global`, `category`, `folder`. Example: `global`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    

#### Responses

*   **200** Slot retrieved successfully
    
    Media type: `application/json`. Schema: `Slot`.
    
    _Example: RetrievedSlot_ Example response for a successfully retrieved slot
    
    ```
    {
      "slotId": "homepage-banner-slot",
      "description": "Main banner slot on homepage",
      "previewUrl": "https://example.com/preview/slot/homepage-banner-slot",
      "contextType": "global",
      "slotConfigurations": [
        {
          "configurationId": "homepage-banner-config",
          "slotId": "homepage-banner-slot",
          "uuid": "abc123def456ghi789jkl012",
          "enabled": true,
          "default": false,
          "description": "Default banner configuration",
          "rank": 1,
          "context": "global",
          "slotContent": {
            "type": "contentAssets",
            "contentAssetIds": [
              "homepage-banner",
              "promo-banner"
            ]
          }
        }
      ],
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z"
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified site does not exist.
    *   The specified slot does not exist in the given context.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example: SlotNotFound_ Example error response for slot not found
    
    ```
    {
      "title": "Slot Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/slot-not-found",
      "detail": "Slot with ID 'homepage-banner-slot' in context 'global' could not be found for site 'RefArch'."
    }
    ```
    
    _Example: SiteNotFound_ Example error response for site not found
    

### POST Search for slots

`POST /organizations/{organizationId}/slot-search`

Operation ID: `searchSlots`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

This API allows searching for slots based on various criteria such as slot ID, description, and context type.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The search uses POST method to support complex query structures.
*   Results are paginated and can be sorted.
*   Searchable fields include: slotId (String), description (String), contextType (String).
*   Only searchable attributes can be used in sorting.
*   Context type value is restricted to Global/Folder/Category.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `SlotSearchRequest`.

_Example: SearchBySlotId_ Example search request by slot ID

```
{
  "query": {
    "textQuery": {
      "fields": [
        "slotId"
      ],
      "searchPhrase": "homepage"
    }
  },
  "limit": 25,
  "offset": 0
}
```

_Example: SearchByContext_ Example search request by context type

```
{
  "query": {
    "filteredQuery": {
      "query": {
        "matchAllQuery": {}
      },
      "filter": {
        "termFilter": {
          "field": "contextType",
          "operator": "is",
          "values": [
            "global"
          ]
        }
      }
    }
  },
  "limit": 2,
  "offset": 0
}
```

#### Responses

*   **200** Search completed successfully
    
    Media type: `application/json`. Schema: `SlotSearchResult`.
    
    _Example: SearchResults_ Example response for slot search
    
    ```
    {
      "query": {
        "textQuery": {
          "fields": [
            "slotId"
          ],
          "searchPhrase": "homepage"
        }
      },
      "limit": 2,
      "offset": 0,
      "total": 25,
      "hits": [
        {
          "slotId": "homepage-banner-slot",
          "description": "Main banner slot on homepage",
          "contextType": "global",
          "creationDate": "2024-01-15T10:30:00.000Z",
          "lastModified": "2024-01-15T10:30:00.000Z"
        },
        {
          "slotId": "category-promo-slot",
          "description": "Category promotional slot",
          "contextType": "category",
          "creationDate": "2024-01-16T14:20:00.000Z",
          "lastModified": "2024-01-16T14:20:00.000Z"
        }
      ]
    }
    ```
    
*   **400** Invalid search query provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: SqlQueryMalformedJoin_ Example error response for malformed SQL query
    
    ```
    {
      "title": "SQL Query Malformed Join",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/sql-query-malformed-join",
      "detail": "One or more attributes 'slotId' are in a different bucket and therefore must be joined with an AND operator.",
      "field": "slotId"
    }
    ```
    
    _Example: UnqueryableField_ Example error response for unqueryable field
    
    ```
    {
      "title": "Unqueryable Field",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "detail": "The field 'uuid' can't be queried.",
      "field": "uuid"
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified site does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example: SiteNotFound_ Example error response for site not found
    

### GET Get a slot configuration

`GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}`

Operation ID: `getSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves detailed information about a specific slot configuration.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The slot configuration must exist.
*   Returns the configuration with all properties including schedule, content, and assignment information.
*   Requires siteId query parameter to identify the site context.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `slotId` (path, string, required) Identifier for the slot  
    Maximum length: 256. Example: `homepage-banner-slot`.
*   `configurationId` (path, string, required) Identifier for the slot configuration  
    Maximum length: 256. Example: `homepage-banner-config`.
*   `context` (query, string) The context for the slot configuration (global, category, or folder)  
    Allowed values: `global`, `category`, `folder`. Example: `global`.

#### Responses

*   **200** Slot configuration retrieved successfully
    
    Media type: `application/json`. Schema: `SlotConfiguration`.
    
    _Example: RetrievedSlotConfiguration_ Example response for a successfully retrieved slot configuration
    
    ```
    {
      "configurationId": "homepage-banner-config",
      "slotId": "homepage-banner-slot",
      "uuid": "abc123def456ghi789jkl012",
      "enabled": true,
      "default": false,
      "description": "Default banner configuration for homepage",
      "callout": {
        "default": {
          "source": "Limited Time Offer!",
          "markup": "<p>Limited Time Offer!</p>"
        }
      },
      "customerGroups": [
        "registered-customers",
        "vip-customers"
      ],
      "rank": 1,
      "template": "slots/banner/homepage",
      "context": "global",
      "schedule": {
        "startDate": "2024-01-01T00:00:00.000Z",
        "endDate": "2024-12-31T23:59:59.000Z"
      },
      "slotContent": {
        "type": "products",
        "productIds": [
          "product-001",
          "product-002"
        ]
      },
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z"
    }
    ```
    
*   **400**
    
    Invalid request parameters. This can occur when:
    
    *   The specified context type is invalid.
    *   The context ID is missing for category or folder context.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidContextType_ Example error response for invalid context type
    
    ```
    {
      "title": "Invalid Context Type",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-context-type",
      "detail": "The specified context type is invalid. Valid values are: global, category, folder."
    }
    ```
    
    _Example: MissingContextId_ Example error response for missing context ID
    
    ```
    {
      "title": "Missing Context ID",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-context-id",
      "detail": "Context ID is required when context type is 'category' or 'folder'."
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified slot does not exist.
    *   The specified slot configuration does not exist.
    *   The specified site does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example: SlotNotFound_ Example error response for slot not found
    
    _Example: SlotConfigurationNotFound_ Example error response for slot configuration not found
    
    ```
    {
      "title": "Slot Configuration Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/slot-configuration-not-found",
      "detail": "Slot configuration with ID 'homepage-banner-config' could not be found for site 'RefArch'."
    }
    ```
    
    _Example: SiteNotFound_ Example error response for site not found
    

### PUT Create or update a slot configuration

`PUT /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}`

Operation ID: `createOrUpdateSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences.rw).

Creates a new slot configuration or updates an existing one.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   If the slot configuration doesn't exist, it will be created (201).
*   If the slot configuration exists, it will be updated (200).
*   Configuration ID in URL must match the configuration ID in the request body.
*   The slot must exist before creating configurations.
*   Requires siteId query parameter to identify the site context.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `slotId` (path, string, required) Identifier for the slot  
    Maximum length: 256. Example: `homepage-banner-slot`.
*   `configurationId` (path, string, required) Identifier for the slot configuration  
    Maximum length: 256. Example: `homepage-banner-config`.
*   `context` (query, string) The context for the slot configuration (global, category, or folder)  
    Allowed values: `global`, `category`, `folder`. Example: `global`.

#### Request body (required)

Media type: `application/json`. Schema: `SlotConfiguration`.

_Example: CreateSlotConfigRequest_ Example request to create a new slot configuration

```
{
  "configurationId": "new-banner-config",
  "slotId": "homepage-banner-slot",
  "enabled": true,
  "default": false,
  "description": "New promotional banner configuration",
  "callout": {
    "default": {
      "source": "New Arrivals!"
    }
  },
  "customerGroups": [
    "registered-customers"
  ],
  "rank": 2,
  "template": "slots/banner/promo",
  "context": "global",
  "slotContent": {
    "type": "contentAssets",
    "contentAssetIds": [
      "promo-banner-001"
    ]
  }
}
```

_Example: UpdateSlotConfigRequest_ Example request to update an existing slot configuration

```
{
  "configurationId": "homepage-banner-config",
  "slotId": "homepage-banner-slot",
  "enabled": true,
  "default": true,
  "description": "Updated banner configuration for homepage",
  "callout": {
    "default": {
      "source": "Sale Now On!"
    }
  },
  "customerGroups": [
    "all-customers"
  ],
  "rank": 1,
  "template": "slots/banner/homepage",
  "context": "global",
  "slotContent": {
    "type": "contentAssets",
    "contentAssetIds": [
      "sale-banner",
      "promo-banner"
    ]
  }
}
```

#### Responses

*   **200** Slot configuration updated successfully
    
    Media type: `application/json`. Schema: `SlotConfiguration`.
    
    _Example: UpdatedSlotConfiguration_ Example response for a successfully updated slot configuration
    
    ```
    {
      "configurationId": "homepage-banner-config",
      "slotId": "homepage-banner-slot",
      "uuid": "abc123def456ghi789jkl012",
      "enabled": true,
      "default": true,
      "description": "Updated banner configuration for homepage",
      "callout": {
        "default": {
          "source": "Sale Now On!",
          "markup": "<p>Sale Now On!</p>"
        }
      },
      "customerGroups": [
        "all-customers"
      ],
      "rank": 1,
      "template": "slots/banner/homepage",
      "context": "global",
      "slotContent": {
        "type": "contentAssets",
        "contentAssetIds": [
          "sale-banner",
          "promo-banner"
        ]
      },
      "creationDate": "2024-01-15T10:30:00.000Z",
      "lastModified": "2024-03-31T16:00:00.000Z"
    }
    ```
    
*   **201** Slot configuration created successfully
    
    Media type: `application/json`. Schema: `SlotConfiguration`.
    
    _Example: CreatedSlotConfiguration_ Example response for a successfully created slot configuration
    
    ```
    {
      "configurationId": "new-banner-config",
      "slotId": "homepage-banner-slot",
      "uuid": "xyz789abc456def123ghi456",
      "enabled": true,
      "default": false,
      "description": "New promotional banner configuration",
      "callout": {
        "default": {
          "source": "New Arrivals!",
          "markup": "<p>New Arrivals!</p>"
        }
      },
      "customerGroups": [
        "registered-customers"
      ],
      "rank": 2,
      "template": "slots/banner/promo",
      "context": "global",
      "slotContent": {
        "type": "contentAssets",
        "contentAssetIds": [
          "promo-banner-001"
        ]
      },
      "creationDate": "2024-03-31T15:45:00.000Z",
      "lastModified": "2024-03-31T15:45:00.000Z"
    }
    ```
    
*   **400**
    
    Invalid slot configuration data provided. This can occur when:
    
    *   The ID in the request path does not match the ID in the request body.
    *   The specified context type is invalid.
    *   The context ID is missing for category or folder context.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example InvalidContextType: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for invalid context type
    
    _Example MissingContextId: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for missing context ID
    
    _Example: IdConflict_ Example error response for ID conflict
    
    ```
    {
      "title": "ID Conflict",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the request path does not match the ID in the request body."
    }
    ```
    
    _Example: InvalidContextType_ Example error response for invalid context type
    
    _Example: InvalidSlotId_ Example error response for invalid slot ID
    
    ```
    {
      "title": "Invalid Slot ID",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-slot-id",
      "detail": "The specified slot ID is invalid or the slot does not exist."
    }
    ```
    
    _Example: MissingContextId_ Example error response for missing context ID
    
*   **404**
    
    The specified resource was not found. This can occur when:
    
    *   The specified site does not exist.
    *   The specified slot does not exist.
    *   Content asset does not exist in the library.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example: SiteNotFound_ Example error response for site not found
    
    _Example: SlotNotFound_ Example error response for slot not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    

### DELETE Delete a slot configuration

`DELETE /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}`

Operation ID: `deleteSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences.rw).

Deletes a slot configuration.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The slot configuration must exist to be deleted.
*   This operation cannot be undone.
*   Requires siteId query parameter to identify the site context.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `slotId` (path, string, required) Identifier for the slot  
    Maximum length: 256. Example: `homepage-banner-slot`.
*   `configurationId` (path, string, required) Identifier for the slot configuration  
    Maximum length: 256. Example: `homepage-banner-config`.
*   `context` (query, string) The context for the slot configuration (global, category, or folder)  
    Allowed values: `global`, `category`, `folder`. Example: `global`.

#### Responses

*   **204** Slot configuration deleted successfully
*   **400**
    
    Invalid request parameters. This can occur when:
    
    *   The specified context type is invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example InvalidContextType: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for invalid context type
    
    _Example: InvalidContextType_ Example error response for invalid context type
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified site does not exist.
    *   The specified slot does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found
    
    _Example: SiteNotFound_ Example error response for site not found
    
    _Example: SlotNotFound_ Example error response for slot not found
    

### PATCH Partially update a slot configuration

`PATCH /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId}`

Operation ID: `patchSlotConfiguration`. Security: AmOAuth2 (sfcc.experiences.rw).

Updates specific properties of an existing slot configuration without replacing the entire resource.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Only the properties provided in the request body will be updated.
*   The slot configuration must already exist.
*   Useful for updating specific attributes without affecting other properties.
*   Requires siteId query parameter to identify the site context.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `slotId` (path, string, required) Identifier for the slot  
    Maximum length: 256. Example: `homepage-banner-slot`.
*   `configurationId` (path, string, required) Identifier for the slot configuration  
    Maximum length: 256. Example: `homepage-banner-config`.
*   `context` (query, string) The context for the slot configuration (global, category, or folder)  
    Allowed values: `global`, `category`, `folder`. Example: `global`.

#### Request body (required)

Media type: `application/json`. Schema: `SlotConfiguration`.

_Example: PatchSlotConfigRequest_ Example request to partially update a slot configuration

```
{
  "configurationId": "homepage-banner-config",
  "slotId": "homepage-banner-slot",
  "enabled": false,
  "description": "Temporarily disabled banner",
  "slotContent": {
    "type": "products",
    "productIds": [
      "product-001"
    ]
  }
}
```

#### Responses

*   **200** Slot configuration updated successfully
    
    Media type: `application/json`. Schema: `SlotConfiguration`.
    
    _Example UpdatedSlotConfiguration: same as PUT /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 200 response._ Example response for a successfully updated slot configuration
    
    _Example: UpdatedSlotConfiguration_ Example response for a successfully updated slot configuration
    
*   **400**
    
    Invalid slot configuration data provided. This can occur when:
    
    *   The specified context type is invalid.
    *   The context ID is missing for category or folder context.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example InvalidContextType: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for invalid context type
    
    _Example MissingContextId: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 400 response._ Example error response for missing context ID
    
    _Example: InvalidContextType_ Example error response for invalid context type
    
    _Example: MissingContextId_ Example error response for missing context ID
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified slot does not exist.
    *   The specified slot configuration does not exist.
    *   The specified site does not exist.
    *   Content asset does not exist in the library.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SlotNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/{contextType} 404 response._ Example error response for slot not found
    
    _Example SlotConfigurationNotFound: same as GET /organizations/{organizationId}/slots/{slotId}/slot-configurations/{configurationId} 404 response._ Example error response for slot configuration not found
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example ContentNotFound: same as GET /organizations/{organizationId}/libraries/{libraryId}/content/{contentId} 404 response._ Example error response for content asset not found
    
    _Example: SlotNotFound_ Example error response for slot not found
    
    _Example: SlotConfigurationNotFound_ Example error response for slot configuration not found
    
    _Example: SiteNotFound_ Example error response for site not found
    
    _Example: ContentNotFound_ Example error response for content asset not found
    
*   **409**
    
    Conflict with existing resource. This can occur when:
    
    *   A slot configuration with the specified ID already exists in this context.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: SlotConfigurationAlreadyExists_ Example error response for slot configuration conflict
    
    ```
    {
      "title": "Slot Configuration Already Exists",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/slot-configuration-already-exists",
      "detail": "A slot configuration with the specified ID already exists in this context."
    }
    ```
    

### POST Search for slot configurations

`POST /organizations/{organizationId}/slot-configurations-search`

Operation ID: `searchSlotConfigurations`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

This API allows searching for slot configurations based on various criteria such as slot ID, context, customer groups, and more.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   The search uses POST method to support complex query structures.
*   Results are paginated and can be sorted.
*   Use the query parameter to filter results based on specific criteria.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `SlotConfigurationSearchRequest`.

_Example: SearchBySlotId_ Example request to search slot configurations by slot ID

```
{
  "query": {
    "textQuery": {
      "fields": [
        "slotId"
      ],
      "searchPhrase": "homepage-banner"
    }
  },
  "limit": 25,
  "offset": 0
}
```

_Example: SearchByContext_ Example request to search slot configurations by context

```
{
  "query": {
    "boolQuery": {
      "must": [
        {
          "termQuery": {
            "fields": [
              "context"
            ],
            "operator": "is",
            "values": [
              "global"
            ]
          }
        },
        {
          "termQuery": {
            "fields": [
              "enabled"
            ],
            "operator": "is",
            "values": [
              true
            ]
          }
        }
      ]
    }
  },
  "limit": 50,
  "offset": 0,
  "sorts": [
    {
      "field": "rank",
      "sortOrder": "asc"
    }
  ]
}
```

#### Responses

*   **200** Search completed successfully
    
    Media type: `application/json`. Schema: `SlotConfigurationSearchResult`.
    
    _Example: SearchResults_ Example response for slot configuration search
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 25,
      "hits": [
        {
          "configurationId": "homepage-banner-config",
          "slotId": "homepage-banner",
          "uuid": "abc123def456ghi789jkl012",
          "enabled": true,
          "default": true,
          "description": "Default banner configuration for homepage",
          "callout": {
            "default": {
              "source": "Limited Time Offer!",
              "markup": "<p>Limited Time Offer!</p>"
            }
          },
          "customerGroups": [
            "registered-customers",
            "vip-customers"
          ],
          "rank": 1,
          "template": "slots/banner/homepage",
          "context": "global",
          "schedule": {
            "startDate": "2024-01-01T00:00:00.000Z",
            "endDate": "2024-12-31T23:59:59.000Z"
          },
          "slotContent": {
            "type": "products",
            "productIds": [
              "product-001",
              "product-002"
            ]
          },
          "assignmentInformation": {
            "activeCampaignAssignments": [
              {
                "slotId": "homepage-banner",
                "slotConfigurationId": "homepage-banner-config",
                "slotConfigurationUuid": "abc123def456ghi789jkl012",
                "description": "Holiday campaign banner",
                "campaignId": "holiday-2024",
                "rank": 1,
                "customerGroups": [
                  "registered-customers"
                ],
                "context": "global",
                "enabled": true,
                "schedule": {
                  "startDate": "2024-11-01T00:00:00.000Z",
                  "endDate": "2024-12-31T23:59:59.000Z"
                }
              }
            ],
            "upcomingCampaignAssignments": [],
            "activeAbtestAssignments": [],
            "upcomingAbtestAssignments": []
          },
          "creationDate": "2024-01-15T10:30:00.000Z",
          "lastModified": "2024-01-15T10:30:00.000Z"
        },
        {
          "configurationId": "category-banner-config",
          "slotId": "category-banner",
          "uuid": "xyz789abc456def123ghi456",
          "enabled": true,
          "default": false,
          "description": "Banner configuration for electronics category",
          "customerGroups": [
            "all-customers"
          ],
          "rank": 2,
          "template": "slots/banner/category",
          "context": "category",
          "contextId": "electronics",
          "schedule": {
            "startDate": "2024-01-01T00:00:00.000Z",
            "endDate": "2024-06-30T23:59:59.000Z",
            "recurrence": {
              "dayOfWeek": [
                "monday",
                "wednesday",
                "friday"
              ],
              "timeOfDay": {
                "timeFrom": "09:00:00",
                "timeTo": "17:00:00"
              }
            }
          },
          "slotContent": {
            "type": "html",
            "body": {
              "default": {
                "source": "<h1>Welcome to Electronics</h1><p>Check out our latest deals!</p>",
                "markup": "<h1>Welcome to Electronics</h1><p>Check out our latest deals!</p>"
              }
            }
          },
          "assignmentInformation": {
            "activeCampaignAssignments": [],
            "upcomingCampaignAssignments": [],
            "activeAbtestAssignments": [
              {
                "abtestId": "electronics-test-001",
                "abtestDescription": "Electronics banner A/B test",
                "enabled": true,
                "schedule": {
                  "startDate": "2024-02-01T00:00:00.000Z",
                  "endDate": "2024-03-31T23:59:59.000Z"
                },
                "segmentId": "segment-a",
                "segmentDescription": "Segment A - Control group"
              }
            ],
            "upcomingAbtestAssignments": []
          },
          "creationDate": "2024-01-10T08:00:00.000Z",
          "lastModified": "2024-01-20T14:30:00.000Z"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "slotId"
          ],
          "searchPhrase": "banner"
        }
      },
      "sorts": [
        {
          "field": "rank",
          "sortOrder": "asc"
        }
      ]
    }
    ```
    
*   **400** Invalid search query provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SqlQueryMalformedJoin: same as POST /organizations/{organizationId}/slot-search 400 response._ Example error response for malformed SQL query
    
    _Example UnqueryableField: same as POST /organizations/{organizationId}/slot-search 400 response._ Example error response for unqueryable field
    
    _Example: SqlQueryMalformedJoin_ Example error response for malformed SQL query
    
    _Example: UnqueryableField_ Example error response for unqueryable field
    
    _Example: FieldNotSortable_ Example error response for field not sortable
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'template' can't be used to sort the results.",
      "field": "template"
    }
    ```
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified site does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example: SiteNotFound_ Example error response for site not found
    

### GET Get page types

`GET /organizations/{organizationId}/page-types`

Operation ID: `getPageTypes`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves the list of Page Designer page types available for a site, including their region definitions, attribute definitions, and supported aspect types.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Requires the siteId query parameter to identify the site context.
*   Aspect types are returned embedded within each page type's supportedAspectTypes.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Page types retrieved successfully
    
    Media type: `application/json`. Schema: `PageTypeResult`.
    
    _Example: PageTypesResult_ Example response for successfully retrieved page types
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "hits": [
        {
          "id": "storePage",
          "name": {
            "default": "Store Page",
            "en": "Store Page"
          },
          "description": {
            "default": "A general-purpose storefront page",
            "en": "A general-purpose storefront page"
          },
          "route": "storefront",
          "archType": "headless",
          "regionDefinitions": [
            {
              "id": "regionA",
              "name": {
                "default": "Main Region",
                "en": "Main Region"
              },
              "maxComponents": 5,
              "componentTypeExclusions": []
            }
          ],
          "attributeDefinitionGroups": [
            {
              "id": "general",
              "name": {
                "default": "General",
                "en": "General"
              },
              "attributeDefinitions": [
                {
                  "id": "title",
                  "name": {
                    "default": "Title",
                    "en": "Title"
                  },
                  "type": "string",
                  "required": true
                }
              ]
            }
          ]
        },
        {
          "id": "productDetailPage",
          "name": {
            "default": "Product Detail Page",
            "en": "Product Detail Page"
          },
          "description": {
            "default": "Displays a single product bound to a product aspect",
            "en": "Displays a single product bound to a product aspect"
          },
          "route": "product",
          "archType": "headless",
          "regionDefinitions": [
            {
              "id": "regionA",
              "name": {
                "default": "Main Region",
                "en": "Main Region"
              },
              "maxComponents": 5,
              "componentTypeExclusions": []
            }
          ],
          "attributeDefinitionGroups": [],
          "supportedAspectTypes": [
            {
              "id": "pdpAspect",
              "name": {
                "default": "Product Detail Aspect",
                "en": "Product Detail Aspect"
              },
              "description": {
                "default": "Provides product context to the page",
                "en": "Provides product context to the page"
              },
              "archType": "headless",
              "supportedObjectTypes": [
                "product"
              ],
              "attributeDefinitions": [
                {
                  "id": "primaryProduct",
                  "name": {
                    "default": "Primary Product",
                    "en": "Primary Product"
                  },
                  "type": "product",
                  "required": true
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
    _Example: EmptyPageTypesResult_ Example response when the requested page contains no page types
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 0,
      "hits": []
    }
    ```
    
*   **400** Invalid request parameters provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MissingSiteId: same as PUT /organizations/{organizationId}/pages/{pageId} 400 response._ Example error response for missing site ID
    
    _Example: MissingSiteId_ Example error response for missing site ID
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified site does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example: SiteNotFound_ Example error response for site not found
    

### GET Get component types

`GET /organizations/{organizationId}/component-types`

Operation ID: `getComponentTypes`. Security: AmOAuth2 (sfcc.experiences, sfcc.experiences.rw).

Retrieves the list of Page Designer component types available for a site, including their group, region definitions, and attribute definitions.

**Important**:

*   This is an admin-only operation requiring appropriate permissions.
*   Requires the siteId query parameter to identify the site context.
*   Each component type carries its group id and localized group name.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Component types retrieved successfully
    
    Media type: `application/json`. Schema: `ComponentTypeResult`.
    
    _Example: ComponentTypesResult_ Example response for successfully retrieved component types
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "hits": [
        {
          "id": "commerce_assets.banner",
          "name": {
            "default": "Banner",
            "en": "Banner"
          },
          "description": {
            "default": "A promotional banner component",
            "en": "A promotional banner component"
          },
          "archType": "headless",
          "embedded": false,
          "group": {
            "id": "commerce_assets",
            "name": {
              "default": "Commerce Assets",
              "en": "Commerce Assets"
            }
          },
          "attributeDefinitionGroups": [
            {
              "id": "general",
              "name": {
                "default": "General",
                "en": "General"
              },
              "attributeDefinitions": [
                {
                  "id": "heading",
                  "name": {
                    "default": "Heading",
                    "en": "Heading"
                  },
                  "type": "string",
                  "required": true
                }
              ]
            }
          ]
        },
        {
          "id": "commerce_assets.carousel",
          "name": {
            "default": "Carousel",
            "en": "Carousel"
          },
          "description": {
            "default": "A rotating carousel of slides",
            "en": "A rotating carousel of slides"
          },
          "archType": "headless",
          "embedded": false,
          "group": {
            "id": "commerce_assets",
            "name": {
              "default": "Commerce Assets",
              "en": "Commerce Assets"
            }
          },
          "regionDefinitions": [
            {
              "id": "slides",
              "name": {
                "default": "Slides",
                "en": "Slides"
              },
              "maxComponents": 10,
              "componentTypeExclusions": []
            }
          ],
          "attributeDefinitionGroups": []
        }
      ]
    }
    ```
    
    _Example: EmptyComponentTypesResult_ Example response when the requested page contains no component types
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 0,
      "hits": []
    }
    ```
    
*   **400** Invalid request parameters provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example MissingSiteId: same as PUT /organizations/{organizationId}/pages/{pageId} 400 response._ Example error response for missing site ID
    
    _Example: MissingSiteId_ Example error response for missing site ID
    
*   **404**
    
    The requested resource was not found. This can occur when:
    
    *   The specified site does not exist.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SiteNotFound: same as PUT /organizations/{organizationId}/pages/{pageId} 404 response._ Example error response for site not found
    
    _Example: SiteNotFound_ Example error response for site not found
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### PageRequest

Includes all fields of `PageBase`.

*   `regions` (_array of RegionRequest_) The regions and their assigned components for the page

### Page

Includes all fields of `PageBase`.

*   `custom` (_object_) Any custom data added by the custom code for the page type
    
    _Example_
    
    ```
    {
      "thumbnail_full": "http://static.myshop.com/new-homepage.jpg"
    }
    ```
    
*   `regions` (_array of Region_) The regions (and their assigned components) for the page
*   `creationDate` (_string (date-time)_) The date and time of page creation  
    Example: `2024-01-15T10:30:00.000Z`.
*   `lastModified` (_string (date-time)_) The date and time when the page was last modified  
    Example: `2024-01-15T10:30:00.000Z`.
*   `online` (_boolean_) Indicates whether the page is online (active) or offline (draft)  
    Example: `false`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ContentFolder

*   `id` (_string_, required) The ID of the content folder  
    Maximum length: 256. Example: `seasonal-content`.
*   `description` (_object_) The localized content folder description B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Folder for seasonal content",
      "en": "Folder for seasonal content"
    }
    ```
    
*   `name` (_object_) The localized content folder name B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en": "Seasonal Content"
    }
    ```
    
*   `online` (_boolean_) A flag indicating whether the folder is online (default is false)  
    Example: `false`.
*   `pageDescription` (_object_) The localized content folder page description B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Seasonal content page description",
      "en": "Seasonal content page description"
    }
    ```
    
*   `pageKeywords` (_object_) The localized content folder page keywords B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "seasonal, content, folder",
      "en": "seasonal, content, folder"
    }
    ```
    
*   `pageTitle` (_object_) The localized content folder page title B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Seasonal Content",
      "en": "Seasonal Content"
    }
    ```
    
*   `pageUrl` (_object_) The localized content folder page URL B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "/seasonal",
      "en": "/seasonal"
    }
    ```
    
*   `parentFolderId` (_string_) The ID of the parent content folder  
    Example: `root`.
*   `template` (_string_) The rendering template  
    Example: `rendering/folder/seasonal`.
*   `creationDate` (_string (date-time)_, read-only) The date and time when the slot configuration was created  
    Example: `2024-01-15T10:30:00.000Z`.
*   `lastModified` (_string (date-time)_, read-only) The date and time when the slot configuration was last modified  
    Example: `2024-01-15T10:30:00.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ContentSubFolderResult

Result document containing an array of content subfolders.

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ContentFolder_) The sorted array of search hits. This array can be empty

### ContentAsset

*   `id` (_string_, required) The ID of the content asset  
    Maximum length: 256. Example: `homepage-banner`.
*   `classificationFolderId` (_string_) The ID of the classification folder. It is only part of the response, if the assignment from this content asset to the folder is marked as 'default'. The property is read-only. To set the classification folder just create/update an assignment between this content asset and a folder and mark it as 'default'. See details in /libraries/{libraryId}/folder-assignments/{contentId}/{folderId} resource.  
    Example: `classificationFolderId`.
*   `name` (_object_) The localized content asset name B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Homepage Banner",
      "en": "Homepage Banner"
    }
    ```
    
*   `description` (_object_) The localized content asset description B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Main promotional banner for the homepage",
      "en": "Main promotional banner for the homepage"
    }
    ```
    
*   `online` (_object_) A flag indicating whether the content asset is online (default is false) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "default": true
    }
    ```
    
*   `pageDescription` (_object_) The localized content asset page description for SEO B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Discover amazing products at great prices",
      "en": "Discover amazing products at great prices"
    }
    ```
    
*   `pageKeywords` (_object_) The localized content asset page keywords for SEO B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "banner, promotion, homepage",
      "en": "banner, promotion, homepage"
    }
    ```
    
*   `pageTitle` (_object_) The localized content asset page title for SEO B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "Homepage Banner - My Shop",
      "en": "Homepage Banner - My Shop"
    }
    ```
    
*   `pageUrl` (_object_) The localized content asset page URL B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default": "/seasonal",
      "en": "/seasonal"
    }
    ```
    
*   `searchable` (_object_) A site specific flag indicating whether the content asset is searchable B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "default": true
    }
    ```
    
*   `siteMapChangeFrequency` (_object_) The content assets change frequency needed for the sitemap creation (always, hourly, daily, weekly, monthly, yearly, never). B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Allowed values: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`.
    
    _Example_
    
    ```
    {
      "default": "always"
    }
    ```
    
*   `siteMapIncluded` (_object_) The status if the content asset is included into the sitemap (either 0 or 1). B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `integer`.
    
    Minimum: 0. Maximum: 1.
    
    _Example_
    
    ```
    {
      "default": 0
    }
    ```
    
*   `siteMapPriority` (_object_) The content assets priority needed for the sitemap creation (0.0 for no priority defined). B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `number`.
    
    _Example_
    
    ```
    {
      "default": 0
    }
    ```
    
*   `template` (_string_) The rendering template  
    Example: `rendering/content/banner`.
*   `creationDate` (_string (date-time)_, read-only) The date and time when the slot configuration was created  
    Example: `2024-01-15T10:30:00.000Z`.
*   `lastModified` (_string (date-time)_, read-only) The date and time when the slot configuration was last modified  
    Example: `2024-01-15T10:30:00.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ContentFolderResult

Result document containing an array of content folders.

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ContentFolder_) The sorted array of search hits. This array can be empty

### ContentFolderAssignment

*   `contentId` (_string_, required) The ID of the content asset  
    Maximum length: 256. Example: `homepage-banner`.
*   `folderId` (_string_, required) The ID of the folder  
    Maximum length: 256. Example: `homepage-folder`.
*   `position` (_number (double)_) The sort order/position of the content asset within the folder  
    Minimum: 0. Example: `1`.
*   `default` (_boolean_) Indicates whether this is the default/primary folder assignment for the content asset  
    Example: `true`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ContentAssetResult

Result document for content assets in a folder

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ContentAsset_) The sorted array of search hits. This array can be empty.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### Slot

Document representing a slot

*   `slotId` (_string_, required) The ID of the slot  
    Maximum length: 256. Example: `homepage-banner-slot`.
*   `description` (_string_) The user-supplied description of the slot  
    Maximum length: 4000. Example: `Main banner slot on homepage`.
*   `previewUrl` (_string_) A URL for previewing the slot in context. This URL is system-generated and allows viewing the slot's appearance on the storefront.  
    Maximum length: 4000. Example: `https://example.com/preview/slot/homepage-banner-slot`.
*   `contextType` (_string_, required) The context type of the slot  
    Allowed values: `global`, `category`, `folder`. Example: `global`.
*   `slotConfigurations` (_array of SlotConfiguration_) List of slot configurations associated with this slot
*   `creationDate` (_string (date-time)_) The date and time when the slot was created  
    Example: `2024-01-15T10:30:00.000Z`.
*   `lastModified` (_string (date-time)_) The date and time when the slot was last modified  
    Example: `2024-01-15T10:30:00.000Z`.

### SlotSearchRequest

Request body for searching slots

Includes all fields of `SearchRequest`.

### SlotSearchResult

Result document for a slot search

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Slot_) The sorted array of search hits

### SlotConfiguration

Document representing a slot configuration

*   `configurationId` (_string_, required) The ID of the configuration  
    Maximum length: 256. Example: `homepage-banner-config`.
*   `slotId` (_string_, required) The ID of the slot  
    Maximum length: 256. Example: `homepage-banner`.
*   `uuid` (_string_) The UUID of the slot configuration  
    Maximum length: 28. Example: `abc123def456ghi789jkl012`.
*   `enabled` (_boolean_, required) Specifies whether the slot is enabled  
    Example: `true`.
*   `default` (_boolean_) Specifies whether the configuration is the default for the slot  
    Example: `false`.
*   `description` (_string_) The configuration description  
    Maximum length: 4000. Example: `Default banner configuration for homepage`.
*   `callout` (_object_) The call out message (localized) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `MarkupText`.
    
    _Example_
    
    ```
    {
      "default": {
        "source": "Limited Time Offer!",
        "markup": "<p>Limited Time Offer!</p>"
      }
    }
    ```
    
*   `customerGroups` (_array of string_) The customer groups ids  
    Items: Example: `registered-customers`.
    
    _Example_
    
    ```
    [
      "registered-customers",
      "vip-customers"
    ]
    ```
    
*   `rank` (_integer_) The rank of the slot configuration on its slot  
    Minimum: 1. Example: `1`.
*   `template` (_string_) The template  
    Maximum length: 256. Example: `slots/banner/homepage`.
*   `contextId` (_string_) The identifier for the context. Required when context is 'category' (categoryId) or 'folder' (folderId). Not applicable for 'global' context.  
    Maximum length: 256. Example: `electronics`.
*   `context` (_string_) The context of the slot  
    Allowed values: `global`, `category`, `folder`. Example: `global`.
*   `schedule` (_Schedule_)
*   `slotContent` (_SlotContent_, required)
*   `assignmentInformation` (_SlotConfigurationAssignmentInformation_)
*   `creationDate` (_string (date-time)_) The date and time when the slot configuration was created  
    Example: `2024-01-15T10:30:00.000Z`.
*   `lastModified` (_string (date-time)_) The date and time when the slot configuration was last modified  
    Example: `2024-01-15T10:30:00.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### SlotConfigurationSearchRequest

Request body for searching slot configurations

Includes all fields of `SearchRequest`.

### SlotConfigurationSearchResult

Result document for a slot configuration search

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of SlotConfiguration_) The sorted array of search hits

### PageTypeResult

Result document containing an array of page types.

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of PageType_, required) The sorted array of page types. This array can be empty.

### ComponentTypeResult

Result document containing an array of component types.

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ComponentType_, required) The sorted array of component types. This array can be empty.

### PageBase

*   `id` (_string_, required) Unique identifier for the page  
    Maximum length: 256. Example: `new-homepage`.
*   `typeId` (_string_, required) Page type identifier  
    Maximum length: 256. Example: `storePage`.
*   `aspectTypeId` (_string_) The aspect type to assign to the page  
    Maximum length: 256. Example: `pdpAspect`.
*   `name` (_string_, required) Display name of the page  
    Maximum length: 4000. Example: `New Homepage`.
*   `description` (_string_) Description of the page  
    Maximum length: 4000. Example: `New home page for the storefront`.
*   `pageTitle` (_string_) The SEO title of the page  
    Maximum length: 4000. Example: `New Homepage - My Shop`.
*   `pageDescription` (_string_) The SEO description of the page  
    Maximum length: 4000. Example: `Welcome to our new homepage.`.
*   `pageKeywords` (_string_) The SEO keywords of the page  
    Maximum length: 4000. Example: `homepage, fashion, my shop`.
*   `thumbnail` (_string_) The thumbnail image for the page  
    Maximum length: 256. Example: `new-homepage.jpg`.
*   `data` (_object_)
    
    The configuration data for the page. This is an open object that can contain:
    
    *   Custom attributes defined by the page type
    *   A `visibilityRule` object (see VisibilityRule schema) that defines visibility conditions for the page
    
    _Example_
    
    ```
    {
      "site_map_priority": 0.8,
      "layout": "default",
      "visibilityRule": {
        "customerGroups": [
          {
            "id": "registered-customers"
          }
        ],
        "validFrom": "2024-01-01T00:00:00.000Z",
        "validTo": "2024-12-31T23:59:59.000Z"
      }
    }
    ```
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### RegionRequest

*   `id` (_string_, required) Region identifier  
    Maximum length: 256. Example: `header`.
*   `components` (_array of ComponentRequest_) The components to assign to the region

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Region

*   `id` (_string_, required) Region identifier  
    Maximum length: 256. Example: `header`.
*   `components` (_array of Component_) The components in the region

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### MarkupText

Document representing markup text with source and rendered HTML

*   `source` (_string_) The raw markup text  
    Example: `<h1>Welcome to our store</h1>`.
*   `markup` (_string_) The rendered HTML (read only)  
    Example: `<h1>Welcome to our store</h1>`.

### Schedule

Document representing a time schedule. Defines an optional validity window (startDate/endDate) and an optional recurrence. Omitting a bound leaves that side of the window open (unbounded).

*   `startDate` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-31T23:59:59.000Z`.
*   `recurrence` (_object_) The recurrence of the schedule by day of week and time of day. Not all schedules support a recurrence.
    
    Includes all fields of `Recurrence`.
    

### SlotContent

Document representing the content type for a slot

*   `type` (_string_, required) The type of content in the slot  
    Allowed values: `products`, `categories`, `contentAssets`, `html`, `recommendedProducts`. Example: `products`.
*   `productIds` (_array of string_) The product ids (valid only for type 'products')  
    Items: Maximum length: 100. Example: `product-001`.
    
    _Example_
    
    ```
    [
      "product-001",
      "product-002"
    ]
    ```
    
*   `categoryIds` (_array of string_) The category ids (valid only for type 'categories')  
    Items: Maximum length: 256. Example: `electronics`.
    
    _Example_
    
    ```
    [
      "electronics",
      "computers"
    ]
    ```
    
*   `recommendationRuleId` (_string_) The recommendation rule id (valid only for type 'recommendedProducts')  
    Maximum length: 256. Example: `top-sellers`.
*   `contentAssetIds` (_array of string_) The content asset ids (valid only for type 'contentAssets')  
    Items: Example: `banner-001`.
    
    _Example_
    
    ```
    [
      "banner-001",
      "banner-002"
    ]
    ```
    
*   `body` (_object_) The HTML body (valid only for type 'html', localized) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `MarkupText`.
    
    _Example_
    
    ```
    {
      "default": {
        "source": "<h1>Welcome</h1>",
        "markup": "<h1>Welcome</h1>"
      }
    }
    ```
    

### SlotConfigurationAssignmentInformation

Information about assignments and assignment schedules of a slot configuration

*   `activeCampaignAssignments` (_array of SlotConfigurationCampaignAssignment_) A list of currently active campaigns this is assigned to
*   `upcomingCampaignAssignments` (_array of SlotConfigurationCampaignAssignment_) A list of upcoming campaigns this is assigned to
*   `activeAbtestAssignments` (_array of SlotConfigurationABTestGroupAssignment_) A list of currently active A/B tests this is assigned to
*   `upcomingAbtestAssignments` (_array of SlotConfigurationABTestGroupAssignment_) A list of upcoming A/B tests this is assigned to

### PageType

*   `id` (_string_, required) The page type id  
    Maximum length: 256. Example: `storePage`.
*   `name` (_LocalizedText_)
*   `description` (_LocalizedText_)
*   `route` (_string_) The route the page type is used for  
    Maximum length: 256. Example: `storefront`.
*   `archType` (_string_) The storefront architecture this type targets  
    Allowed values: `controller`, `headless`. Example: `headless`.
*   `preview` (_string_) Preview indicator; present only for preview container page types  
    Allowed values: `default`. Example: `default`.
*   `regionDefinitions` (_array of RegionDefinition_) The regions components can be assigned to
*   `attributeDefinitionGroups` (_array of AttributeDefinitionGroup_) The grouped attribute definitions for the page type
*   `supportedAspectTypes` (_array of AspectType_) The aspect types this page type supports, resolved as full objects

### ComponentType

*   `id` (_string_, required) The component type id  
    Maximum length: 256. Example: `commerce_assets.banner`.
*   `name` (_LocalizedText_)
*   `description` (_LocalizedText_)
*   `archType` (_string_) The storefront architecture this type targets  
    Allowed values: `controller`, `headless`. Example: `headless`.
*   `embedded` (_boolean_) Whether this is embedded content  
    Example: `false`.
*   `componentId` (_string_) Developer-defined content id for embedded components, used as the Content.ID when the component is created  
    Maximum length: 256. Example: `banner`.
*   `group` (_ComponentTypeGroup_)
*   `regionDefinitions` (_array of RegionDefinition_) The regions components can be assigned to
*   `attributeDefinitionGroups` (_array of AttributeDefinitionGroup_) The grouped attribute definitions for the component type

### ComponentRequest

*   `id` (_string_, required) Component identifier  
    Maximum length: 256. Example: `banner-component-1`.
*   `typeId` (_string_, required) Component type identifier  
    Maximum length: 256. Example: `commerce_assets.banner`.
*   `name` (_string_) Display name of the component  
    Maximum length: 256. Example: `Header Banner`.
*   `data` (_object_) The configuration data for the component
    
    _Example_
    
    ```
    {
      "title": "Welcome Banner",
      "bannerImage": "welcome-banner.jpg"
    }
    ```
    
*   `visible` (_boolean_) Indicates whether the component is visible  
    Example: `true`.
*   `localized` (_boolean_) Indicates whether the component is localized for the current locale  
    Example: `true`.
*   `designMetadata` (_object_) Design metadata of the component. This includes information about the component type definition needed by the page designer for design-time functionality.
    
    _Example_
    
    ```
    {
      "id": "commerce_assets.banner",
      "name": "Banner Component",
      "archType": "headless"
    }
    ```
    
*   `regions` (_array of RegionRequest_) The regions for the component (for nested components)

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Component

*   `id` (_string_, required) Component identifier  
    Maximum length: 256. Example: `banner-component-1`.
*   `typeId` (_string_, required) Component type identifier  
    Maximum length: 256. Example: `commerce_assets.banner`.
*   `name` (_string_) Display name of the component  
    Maximum length: 256. Example: `Header Banner`.
*   `data` (_object_) The configuration data assigned to the component
    
    _Example_
    
    ```
    {
      "title": "Welcome Banner",
      "bannerImage": "welcome-banner.jpg"
    }
    ```
    
*   `custom` (_object_) Any custom data added by the custom code for this component
    
    _Example_
    
    ```
    {
      "banner_url": "http://static.myshop.com/welcome-banner.jpg"
    }
    ```
    
*   `visible` (_boolean_) Indicates whether the component is visible  
    Example: `true`.
*   `localized` (_boolean_) Indicates whether the component is localized for the current locale  
    Example: `true`.
*   `fragment` (_boolean_) Indicates whether the component is a fragment. True if the component is a fragment, otherwise false.  
    Example: `false`.
*   `embedded` (_boolean_) Indicates whether the component is embedded in another component. True if the component is embedded, otherwise false.  
    Example: `false`.
*   `designMetadata` (_object_) Design metadata of the component. This includes information about the component type definition needed by the page designer for design-time functionality.
    
    _Example_
    
    ```
    {
      "id": "commerce_assets.banner",
      "name": "Banner Component",
      "archType": "headless"
    }
    ```
    
*   `regions` (_array of Region_) The regions (and their assigned components) for the component

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Recurrence

Document representing a schedule recurrence.

*   `dayOfWeek` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Example: `monday`.
*   `timeOfDay` (_object_) The time of the day for recurrence.
    
    Includes all fields of `TimeOfDay`.
    

### SlotConfigurationCampaignAssignment

Document representing a slotConfigurationCampaignAssignment

*   `slotId` (_string_, required) The ID of the slot  
    Maximum length: 256. Example: `homepage-banner`.
*   `slotConfigurationId` (_string_, required) The ID of the slot configuration  
    Maximum length: 256. Example: `homepage-banner-config`.
*   `slotConfigurationUuid` (_string_) The UUID of the slot configuration  
    Maximum length: 28. Example: `abc123def456ghi789jkl012`.
*   `description` (_string_) The description of the slot configuration  
    Maximum length: 4000. Example: `Holiday campaign banner`.
*   `campaignId` (_string_) The id of the campaign that has the slot configuration assigned to it  
    Maximum length: 256. Example: `holiday-2024`.
*   `rank` (_integer_) The rank of the slot configuration-campaign assignment  
    Minimum: 1. Example: `1`.
*   `customerGroups` (_array of string_) The list of customer groups  
    Items: Example: `registered-customers`.
    
    _Example_
    
    ```
    [
      "registered-customers"
    ]
    ```
    
*   `context` (_string_, required) The slot context  
    Allowed values: `global`, `category`, `folder`. Example: `global`.
*   `slotContextId` (_string_) The ID of the slot's context  
    Maximum length: 256. Example: `electronics`.
*   `enabled` (_boolean_) A flag indicating whether the assignment is enabled  
    Example: `true`.
*   `schedule` (_Schedule_)
*   `campaign` (_object_) The campaign details
    
    _Example_
    
    ```
    {
      "campaignId": "holiday-2024",
      "description": "Holiday campaign"
    }
    ```
    
*   `slotConfiguration` (_SlotConfiguration_)
*   `creationDate` (_string (date-time)_) The date and time when the assignment was created  
    Example: `2024-11-01T10:00:00.000Z`.
*   `lastModified` (_string (date-time)_) The date and time when the assignment was last modified  
    Example: `2024-11-01T10:00:00.000Z`.

### SlotConfigurationABTestGroupAssignment

Document representing a SlotConfiguration AB test group assignment

*   `abtestId` (_string_) The ID of the A/B test assigned to the slot configuration  
    Example: `homepage-test-001`.
*   `abtestDescription` (_string_) The description of the A/B test  
    Example: `Homepage banner A/B test`.
*   `enabled` (_boolean_) Specifies whether the A/B test is enabled (true) or not (false)  
    Example: `true`.
*   `schedule` (_Schedule_)
*   `segmentId` (_string_) The ID of the A/B test segment  
    Example: `segment-a`.
*   `segmentDescription` (_string_) The description of the A/B test segment  
    Example: `Segment A - Control group`.

### LocalizedText

A localized string keyed by locale id, plus a 'default' fallback B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)

Additional properties: `string`.

Maximum length: 4000. Example: `Store Page`.

_Example_

```
{
  "default": "Store Page",
  "en": "Store Page"
}
```

### RegionDefinition

*   `id` (_string_, required) The region id, unique within its type  
    Maximum length: 256. Example: `regionA`.
*   `name` (_LocalizedText_)
*   `description` (_LocalizedText_)
*   `maxComponents` (_integer_) The maximum number of components rendered in the region  
    Example: `3`.
*   `componentTypeExclusions` (_array of ComponentTypeExclusion_) Component types that may not be assigned to this region

### AttributeDefinitionGroup

*   `id` (_string_, required) The attribute definition group id, unique within its type  
    Maximum length: 256. Example: `general`.
*   `name` (_LocalizedText_)
*   `description` (_LocalizedText_)
*   `attributeDefinitions` (_array of AttributeDefinition_) The attribute definitions in this group

### AspectType

*   `id` (_string_, required) The aspect type id  
    Maximum length: 256. Example: `pdpAspect`.
*   `name` (_LocalizedText_)
*   `description` (_LocalizedText_)
*   `archType` (_string_) The storefront architecture this type targets  
    Allowed values: `controller`, `headless`. Example: `headless`.
*   `supportedObjectTypes` (_array of string_) The object types this aspect can be assigned to  
    Items: Maximum length: 256. Example: `product`.
    
    _Example_
    
    ```
    [
      "product"
    ]
    ```
    
*   `attributeDefinitions` (_array of AttributeDefinition_) The aspect's attribute definitions (a flat list)

### ComponentTypeGroup

*   `id` (_string_, required) The component type group id  
    Maximum length: 256. Example: `commerce_assets`.
*   `name` (_LocalizedText_)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### TimeOfDay

Document representing a time schedule within a single day.

*   `timeFrom` (_string_) The time to start from. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `09:00:00`.
*   `timeTo` (_string_) The time to end on. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `17:00:00`.

### ComponentTypeExclusion

*   `typeId` (_string_, required) The excluded component type id  
    Maximum length: 256. Example: `commerce_assets.carousel`.

### AttributeDefinition

*   `id` (_string_, required) The attribute definition id, unique within its type  
    Maximum length: 256. Example: `title`.
*   `name` (_LocalizedText_)
*   `description` (_LocalizedText_)
*   `type` (_string_) The attribute value type  
    Allowed values: `string`, `text`, `markup`, `product`, `category`, `file`, `page`, `image`, `boolean`, `integer`, `enum`, `url`, `custom`, `cms_record`. Example: `string`.
*   `required` (_boolean_) Whether a value for this attribute is required  
    Example: `true`.
*   `defaultValue` (_string | boolean | integer | number_) The default value applied when no value is set; its type follows the attribute 'type'  
    Example: `Welcome`.
    
    One of: `string`, `boolean`, `integer`, `number`.
    
    *   _string_
        
        Type: `string`.
        
        Maximum length: 4000. Example: `Welcome`.
        
    *   _boolean_
        
        Type: `boolean`.
        
        Example: `true`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
    
    Example: `Welcome`.
    
*   `values` (_array of string | integer | number_) The set of valid values, used when type is 'enum'
    
    _Example_
    
    ```
    [
      "small",
      "medium",
      "large"
    ]
    ```
    
*   `editor` (_object_) Editor configuration; populated only for 'custom' and 'cms\_record' types, otherwise omitted
    
    _Example_
    
    ```
    {
      "contentType": "product"
    }
    ```
    
*   `dynamicLookup` (_object_) Runtime lookup that aliases this attribute to an aspect attribute
    
    *   `aspectAttributeAlias` (_string_) The aspect attribute id this attribute aliases at render time  
        Maximum length: 256. Example: `primaryProduct`.
    
    _Example_
    
    ```
    {
      "aspectAttributeAlias": "primaryProduct"
    }
    ```
    

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=c456514dcb7e7e8e8eecb6d12b56263d33068dfc098377546f8c2082ad25bb0f url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-quick-start-create-sf.md -->

# Explore Storefront Next Code Locally

Explore Storefront Next locally without setting up a B2C Commerce instance or using Business Manager. This procedure uses the default configuration values for the demo instance and isn't for creating your own storefront. Generate the storefront code via the command line using the predefined B2C Commerce demo instance.

## Prerequisites

- Node Package Manager (pnpm) version 10.28 or later. See [Installation](https://pnpm.io/installation) on the pnpm site.
- Node.js version 24.13.0 or later. See [Download Node.js](https://nodejs.org/en/download) on the Node.js site.
- The Storefront Next dependencies are specified in `package.json`. You install them in this quick start by using the `pnpm install` command.

## Steps

1. Create a folder for all your storefront projects and navigate to it.

2. Discover the Storefront Next CLI commands available by typing this command.

   ```
   pnpm dlx @salesforce/storefront-next-dev --help
   ```

   To learn more about each subcommand, type the `-h` or `--help` argument after the command.

3. Create a Storefront Next project by typing this command in the new folder, and then answer the questions to configure your storefront.

   ```
   pnpm dlx @salesforce/storefront-next-dev create-storefront
   ```

   a. Provide a name for your storefront. For example, `my-demo-storefront`.

   b. Select a Storefront Next UI template, for example, `Salesforce B2C Commerce Retail Storefront (Fashion)`. To learn more about the various templates, see [Storefront Next Template Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-template-compare.md).

   c. For the extensions, press Enter to accept the selected extensions.

   d. Accept the defaults for the SLAS client ID, organization ID, short code, and site ID. The default values reference the demo B2C Commerce instance.

   **tip:** To use your own B2C Commerce instance, use Business Manager to create your storefront and related resources. See [Create a Storefront in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md) or [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md). To create a SLAS client ID via the CLI, see [Storefront Next](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/storefront-next.html) in the Agentic B2C Developer Toolkit documentation on GitHub.

   The command creates a project folder under the current directory with your storefront name, and clones the template into it from the [storefront-next-template](https://github.com/SalesforceCommerceCloud/storefront-next-template/) GitHub repository.

4. Open the project folder in an IDE.

5. (Optional) Verify your configuration in the generated `.env` file. The default values connect to a demo B2C Commerce instance.

6. In a terminal window, go to the storefront folder.

   ```
   cd {project-folder}
   ```

7. Install Storefront Next project dependencies that are specified in `package.json`.

   ```
   pnpm install
   ```

8. Build the storefront.

   ```
   pnpm run build
   ```

9. Run the development server.

   ```
   pnpm run dev
   ```

10. Open the development server URL shown in the output to view the storefront in the browser. For example, the URL with the default port is `http://localhost:5173`.

## Next Steps

- [Customize Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-customize.md)

<!-- document id=13084417ba7c60c9468bf6e00ebd0e312a12075b8a29a0d01df8e99fde43257c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/active-merchandising/b2c-exporting-active-data.md -->

# Export Active Data

Active data doesn't need to be exported to be added to other instances. It’s always collected from the Production instance and automatically uploaded to any instance that uses it. Active data is only exported for extra analysis or reporting outside Salesforce B2C Commerce.

Exported active data files can't be reimported onto the same instance. It fails validation. However, upload and import the .csv file onto a Sandbox system for further analysis.

<!-- CANNOT FIND -->
<!--TODO: Fix link post migration -->
<!-- However, you can upload and [import](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-importing-active-data-csv-files.md) the .csv file onto a Sandbox system for further analysis. -->

1.  Select **_site_** > **Merchant Tools** > **Online Marketing** > **Active Data** > **Import & Export.**

2.  On the Import & Export page, click **Download**.

3.  Click a file link to open it.

    The file has the following format:

    - First line is empty.
    - Second line contains the type of active data, either Product Active Data or Customer Active Data.
    - Third line contains column headers, which are the attribute IDs for the data included in the file.
    - Remaining lines contain active data values. The attribute value formats match the formats used for active data import.

<!-- document id=481281655096f884cfc4380da20aed556aa1ba7caab7551ca0855a59f836eaed url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/export-data-when-suspending-voiding-carts.md -->

# Export Data When Suspending and Voiding Carts

By integrating with Point of Sale webhook APIs, merchants can export real-time data when a cart is voided or suspended in the POS app. This data includes details like product information, pricing, fulfillment methods, and more. You can store this information for loss prevention (LP) audits.

For details of the data structure and example values in the request and response payloads, refer to [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Configure Void Cart Webhook

When configured, this webhook triggers in various scenarios, both manually and automatically. For manual scenarios, an example is when a store associate voids the cart via a deep link. Automatically, the webhook triggers when a cart experiences an idle timeout, displaying the error message, `Idle time limit exceeded and the cart has been voided.` The payload for the voided cart is empty, indicating the cart's expired status. For a complete list of scenarios that trigger the void cart webhook and their associated reason codes, refer to [Void Cart Webhook Scenarios and Reason Codes](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-data-when-suspending-voiding-carts.html#void-cart-webhook-scenarios-and-reason-codes).

For more information on voiding a cart on the POS app, refer to [Configuring and Customizing Cart Options on the Point of Sale App](https://help.salesforce.com/s/articleView?id=commerce.rt_pos_settings_custom_cart_options.htm&type=5) in _Salesforce Help_.

1.  In CMS, go to **Integrations** | **Custom Connectors**.

2.  Click **Create**.

3.  For Connector Type, select **Webhook**.

4.  For Endpoint Name, select **VOID_CART**.

5.  Configure the rest of the fields and save your changes.

![The CMS shows settings for void cart data export.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-process-export-suspend-void-data-void-webhook-settings.png)

### Void Cart Webhook Scenarios and Reason Codes

For automatically voided carts, a system-generated [reason code](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_settings_reason_codes.htm&type=5) is included. Depending on the scenario, the payload can also contain product details. System-generated reason codes include the prefix `SYS`.

<table>
<col />
<col />
<thead>
  <tr>
    <th>
      Scenario
    </th>
    <th>
      Reason Code
    </th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>
      Customer logs out with items in the cart
    </td>
    <td>
      SYS_CUSTOMER_LOGOUT
    </td>
  </tr>
  <tr>
    <td>
      Cart session time expires (as set by
      <code>cartSessionExpiryDurationInSeconds</code>
      )
    </td>
    <td>
      SYS_CART_EXPIRED
    </td>
  </tr>
  <tr>
    <td>
      <p>
        Last item in a sales, returns, or bundle product is removed from the cart
      </p>
    </td>
    <td>
      SYS_LAST_ITEM_REMOVED
    </td>
  </tr>
  <tr>
    <td>
      Switching from online to offline mode
    </td>
    <td>
      SYS_SWITCHED_TO_OFFLINE
    </td>
  </tr>
  <tr>
    <td>
      Phase two fails and the order is not placed
    </td>
    <td>
      SYS_ORDER_FAILED
    </td>
  </tr>
  <tr>
    <td>
      Associate logs out manually or via a timer in offline mode
    </td>
    <td>
      SYS_ASSOCIATE_LOGOUT
    </td>
  </tr>
  <tr>
    <td>
      Switching from offline to online mode with return items
    </td>
    <td>
      SYS_SWITCHED_TO_ONLINE
    </td>
  </tr>
  <tr>
    <td>
      Starting a return when there are already canceled or edited items in the cart
    </td>
    <td>
      SYS_VOID_TO_START_RETURN
    </td>
  </tr>
  <tr>
    <td>
      Clicking <b>Void Cart</b> manually without reason codes configured
    </td>
    <td>
      No reason code is sent
    </td>
  </tr>
  <tr>
    <td>
      Clicking <b>Cash Pickup</b>, <b>No Sale</b>, or <b>Cash Audit</b> deep links with items in cart
    </td>
    <td>
      SYS_CASH_EVENT
    </td>
  </tr>
  <tr>
    <td>
      Editing an order with items already in the cart
    </td>
    <td>
      SYS_VOID_TO_START_EDIT_ORDER
    </td>
  </tr>
</tbody>
</table>

## Configure Suspend Cart Webhook

When configured, this webhook triggers in two scenarios: when the store associate manually suspends the cart via a deep link or when the associate logs outs.

For more information about suspending a cart on the POS app, refer to [Suspend and Resume Carts](https://help.salesforce.com/s/articleView?id=commerce.rt_pos_orders_process_suspend_cart.htm&type=5) in _Salesforce Help_.

1.  In CMS, go to **Integrations** | **Custom Connectors**.

2.  Click **Create**.

3.  For Connector Type, select **Webhook**.

4.  For Endpoint Name, select **SUSPEND_CART**.

5.  Configure the rest of the fields and save your changes.

![The CMS shows settings for a webhook to export data for suspended cart.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-process-export-suspend-void-data-suspend-webhook-settings.png)

## Repost Webhooks

Point of Sale offers the ability to manually repost failed webhook events.

1.  In CMS, go to **Store Management** | **Reporting and Analytics** | **Repost Failed Webhook Events**.

2.  Search for the failed webhook event by configuring the search query parameters.

3.  Click **View Details** to view the details of the payload inside the selected webhook event.

4.  Click **Repost** to manually trigger a webhook event repost.

## Frequently Asked Questions (FAQs)

**What's the difference between `suspendCartId` and `cartID` for a suspended cart?**

The `suspendCartId` is a Globally Unique Identifier (GUID) specifically used to resume a suspended cart. In contrast, the `CartID` follows the format of an `orderID`, which it's converted to if the transaction is completed rather than suspended.

<!-- document id=71da2ceb316edf39f408624b6658487c985308e9a9686944770bdd3c6f566969 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/export-tlog.md -->

# Export the Transaction Log (TLog)

Export transaction logs, also known as TLogs, from the Point of Sale app to transfer point-of-service information to external systems. You can use TLog exports to obtain the message set that contains transaction details. Review the available options to customize your TLog exports.

**Supported Transactions**

The TLog export supports these store transactions.

- In-store order
- Endless aisle order
- Return transaction
- Exchange transaction

**note:** Even Exchange, Exchange (customer pays), and Exchange (customer gets refund) transactions require more than one export file. Two files are exported for each scenario, New Sale and Return of Old Transaction.

**Export Options**

Point of Sale offers these TLog export options.

- Real time export
- Batch export
- Webhook integration

## Use Real Time Export

**important:** If using both SPI order export and TLog export, omit this step, as the Real Time Export toggle needs to be disabled. SPI order export is, by default, a real time export and the TLog export needs to be scheduled. If you aren't using both, continue reading.

With Real Time Export, the TLog export occurs automatically after each transaction is captured in the Point of Sale platform using SFTP.

Follow these steps to enable Real Time Export.

1. In the CMS, go to **Store Management** | **Store Settings** | **OMS**.

2. Turn on **Real Time Export**.![A screenshot shows the option for enabling the real time export.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-real-time-export-option.png)

3. To configure the SFTP endpoint, refer to [Order Export Configuration](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-tlog.html#order-export-configuration). Even though real time is enabled, it is strongly recommended to configure the [Use Batch Export](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-tlog.html#use-batch-export) daily at the end of the day.

For supported file format, refer to [Transaction Log Format](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-tlog.html#transaction-log-format).

## Use Batch Export

The batch export functionality performs the TLog export periodically via SFTP. Each export consists of the transactions that occurred since the last export job. The transaction can be sent according to the [Transaction Log Format](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-tlog.html#transaction-log-format). To enable batch export, refer to [Order Export Configuration](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/export-tlog.html#order-export-configuration).

## Use Webhook Integration

The webhook integration sends a Point of Sale `CustomerOrder` object as JSON to an external endpoint via HTTP POST. This event occurs synchronously at the end of order processing. Webhooks are triggered for these order lifecycle events.

1. New order creation
2. Partial or full order return
3. Order cancellation

**tip:** For a list of events Point of Sale can stream, refer to [Point of Sale Data Exports](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/data-exports.html).

To configure the Webhook endpoint CMS Store Settings:

1. In the CMS, go to **Store Management** | **Advanced** | **Store Settings**.

2. Configure the Real Time Order Export endpoint (OrderPostProcessingConfigJSON).

3. Configure the Real Time Returns Export endpoint (OrderReturnPostProcessingConfigJSON).![A screenshot shows the settings for webhook integration.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-webhook-integration-options.png)

## SFTP Configuration

The real time and batch exports are performed via SFTP with a single transaction per file.

### Transaction Log Format

These file formats are supported via SFTP:

<table>
<col />
<col />
<col />
<col />
<thead>
  <tr>
    <th>
    </th>
    <th>
      Single transaction per file
    </th>
    <th>
      Multiple transactions per file
    </th>
    <th>
      Additional Information
    </th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>
      POSLog (XML)
    </td>
    <td>
      Yes
    </td>
    <td>
      No
    </td>
    <td>
      Support for POSLog v6.0
    </td>
  </tr>
</tbody>
</table>

### Order & Item Level Attributes

For CSV and TSV TLog exports, field mappings must be configured. Otherwise, the order export job fails. By using field mappings, also customize the order and attributes at the item level in the CMS, including defining attribute names, setting attribute order, and applying data transformations as necessary.

1. In CMS, go to **Feeds** | **Field Mappings** | **Export Orders**.

2. Map the fields. As a guide, use [Define Export Orders Field Mappings](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_data_feeds_maps_export_orders.htm&type=5) in _Salesforce Help_. ![A screenshot shows the mapping of attribute between order and item level](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-order-and-item-level-attributes-mapping.png)

3. Save your changes.

## Transaction File

A transaction can have multiple lines if it contains multiple products or tender types. For example, Order PS00021916 with two items, 100000 and 100582, purchased with two credit cards, Visa and MasterCard. In this case, the transaction has four lines in total.

![A screenshot shows an example of transaction file items.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-transaction-file.png)

## Order Export Configuration

A TLog export performed using SFTP is configured in CMS’s order export job. This configuration is required for both real time and batch exports using SFTP. This configuration allows you to select the listed following TLog attributes.

- TLog file format (POSLog or CSV or RetailNext)
- Brand's SFTP destination
- In the case of batch export, it is a batch interval.
- One transaction per file or more (not applicable for POSLog as it can send one transaction per file).

**note:** The max limit for running batch export is 1,000 per batch. To determine how frequently export jobs need to run, use calculate the total number of orders daily divided by 1,000.

### Configure SFTP for the first time

1.  Go to **Feeds** | **Export Jobs**.

2.  Click the Plus icon.![A screenshot shows the options for a new export job.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-to-configure-sftp-for-the-first-time-new-export-job-dialog.png)

3.  Click **Order**.![A screenshot shows a new order export job.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-to-configure-sftp-for-the-first-time-new-export-job.png)

### Edit an existing SFTP configuration

1.  Go to **Feeds** | **Export Jobs**.

2.  Hover over the Order card and click the Edit icon.
    ![A screenshot shows an example of a scheduled feed.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-feed-schedule.png)

**note:** For more information on configuring feed schedules, see [Schedule Feed Runs](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/rt-adv-config-data-feeds-manage-schedule.html) in _Salesforce Help_.

## PS NRF POSLog/TLog (XML)

### NRF PosLog/TLog Overview

Point of Sale can export sale, return, and exchange transactions according to the NRF schema. The output is one XML file per transaction that brands can consume and ingest in their systems.

### PosLog/TLog Sectional Details

#### Identifying information

- Order ID - Whenever an item leaves the store, a new order ID is generated for sales or exchanges. Note that sales and exchanges have different order numbers in Adyen. For uneven exchanges (where the customer pays more), there's no refund reference in Adyen. Instead, the additional amount paid by the customer is recorded as a second Adyen transaction.

- Transaction ID - An order can have multiple transactions. In the case of exchanges, a single transaction ID spans across two orders.

- Receipt ID - POS generates a receipt ID for each transaction (Sale, Return, or Exchange). The receipt ID is generally printed on receipts only in fiscal countries and is present in POS Log export for reporting purposes in fiscal countries, such as Spain.

**note:** As part of the 8.9.1 build, TLogs include the transaction start (`transactionStartDate`) and end time (`transactionDate`). The recording time starts from when the cart is first created (when the first item is added to the cart) to when the order/transaction is completed (sales, returns, or exchange).

#### Locate file details

- The file begins with the store ID, order number, and associate ID.![A screenshot show store ID, order number, associate ID, and others at the top of the tlog.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-1.png)
- The end of the file includes the order date, order update date, and till ID.![A screenshot shows the order date, order, update, date, and till ID at the bottom of the tlog file.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-2.png)
- The `<LineItem>` tag includes the line item, product details, and sales attribution.![A screenshot showed the line item, product, details, and sale attribution under the line item tag.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-3.png)
- The `<LineItem>` tag also includes the tender, order level taxes, and delivery details, but with different types to distinguish the line items.![A screenshot shows the tender, order level tax, and delivery details under the line item tag, but with different types to distinguish the line items.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-4.png)
- The `<Customer>` tag includes the customer information.![A screenshot showing customer information under the customer tag.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-5.png)
- The `<TaxExemption>` tag (nested under the `<Tax>` tag) includes the reported tax exemptions.![A screenshot shows the tax exemptions reported under the tax exemption tag.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-6.png)

  **note:** TLogs and receipts don't record jurisdiction or registration number.

- The `IsExchange` field on the `<CustomerOrderTransaction>` tag specifies whether the transaction is for an item returned along with the purchase of another item.![A screenshot shows an exchange transaction returned with the purchase of another item.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-7.png)
- The `orderActivityLog` specifies all information about the history of an order, including the original transaction type files.![A screenshot shows order history and original transaction types under the order activity log.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-export-tlog-poslog-tlog-sectional-details-8.png)

  - For exchanges, the `orderActivityLog` for the new order (that is, PS00000002) contains the following return information:

    - `returnProductList` - Returned products
    - `returnProductList.productTax` - Return item's tax
    - `returnProductPriceAdjustments` - Promotions/Discount/PriceOverride of returned items
    - `refundPaymentDetails` - Refunded payment, available only if the customer gets a refund during the exchange.
      **tip:** For more information, see [TLog Export FAQs](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_export_tlog_export_faq.htm&type=5) in _Salesforce Help_.

- Format of `requestId` with `TENDER_REFERENCE_`:

  - Store and Forward (SAF) refers to orders with payments taken when the Adyen terminal operates in offline mode or experiences difficulties interacting with their platform. During SAF payments, Adyen does not generate the typical `requestID` (PSP reference) since the terminal is offline. Instead, the Point of Sale app uses `TENDER_REFERENCE_<AlternateRequestID>` as the request ID and includes it in TLogs.
  - The `AlternateRequestID` is generated by the Adyen terminal and serves as a means to track and reconcile payments, accessible through the Adyen Portal.
  - Subsequently, Point of Sale updates the `requestID` (PSP reference) field from `TENDER_REFERENCE_<AlternateRequestID>` to the actual PSP reference. This update occurs when Adyen initiates a callback after the SAF payment has been successfully synchronized with the Adyen platform. At that point, TLogs are sent out.
  - Point of Sale re-exports the order once the backend receives the Adyen callback with the actual `requestID` (PSP reference). Because this can result in two identical payloads for a single order, configure your system for updates or ignore the second callback.

- Custom string attributes, mapped in the product feed and configured in the CMS under the `tLogCustomProductAttributes` setting, are included in the order JSON. Custom string attributes must use camel case (for example, `customString1`). These attributes appear in the following product arrays:

  - `productList`
  - `orderProductList`
  - `returnProductList`
  - `orderactivity.transactionData.returnProductList`
  - `orderactivity.transactionData.productList`

### Example Files

- [CheckoutOrder.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/CheckoutOrder.xml)
- [CheckoutPromotion.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/CheckoutPromotion.xml)
- [ExchangeChargeMore.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/ExchangeChargeMore.xml)
- [ExchangeEven.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/ExchangeEven.xml)
- [ExchangeRefundDue.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/ExchangeRefundDue.xml)
- [FullReturn.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/FullReturn.xml)
- [PartialReturn.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/PartialReturn.xml)
- [PriceOverride.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/PriceOverride.xml)
- [TransactionDiscount.xml](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/TransactionDiscount.xml)

<!-- document id=aa1c2a698164ba3702064f8ba7a971f8adbf67a745d5d5156de2daa9f0bbe5b1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/exportdataunitsconfiguration.md -->

# ExportDataUnitsConfiguration document

Document representing a configuration for the data units which a site export needs to identify what exactly should be exported. All unit types (site specific, global, ...) which should be exported need to be set to ‘true‘. Units set to 'false' are simply ignored with this version and can also be skipped.

| Property                 | Type                                                                 | Constraints | Description                                                                                                             |
| :----------------------- | :------------------------------------------------------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------- |
| catalog_static_resources | Map[String, Boolean]                                                 |             | The Catalog Static Resources which should be exported. If "all":true is included, all available units will be exported. |
| catalogs                 | Map[String, Boolean]                                                 |             | The Catalogs which should be exported. If "all":true is included, all available units will be exported.                 |
| customer_lists           | Map[String, Boolean]                                                 |             | The Customer Lists which should be exported. If "all":true is included, all available units will be exported.           |
| global_data              | [ExportGlobalDataConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/exportglobaldataconfiguration.md)    |             | The Global Data which should be exported. If "all":true is set, all available units will be exported.                   |
| inventory_lists          | Map[String, Boolean]                                                 |             | The Inventory Lists which should be exported. If "all":true is included, all available units will be exported.          |
| libraries                | Map[String, Boolean]                                                 |             | The Libraries which should be exported. If "all":true is included, all available units will be exported.                |
| library_static_resources | Map[String, Boolean]                                                 |             | The Library Static Resources which should be exported. If "all":true is included, all available units will be exported. |
| price_books              | Map[String, Boolean]                                                 |             | The Price Books which should be exported. If "all":true is included, all available units will be exported.              |
| sites                    | Map[String, [ExportSitesConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/exportsitesconfiguration.md)] |             | The Sites which should be exported. If property "all" is assigned, all available sites will be exported.                |

<!-- document id=980df011ddb58dba7c09d4137737a7f63a3a196f49788ea10539f2db8aa7933a url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/exportglobaldataconfiguration.md -->

# ExportGlobalDataConfiguration document

Document representing a configuration for the global data units which should be exported.

| Property                  | Type    | Constraints | Description                                                                                                                                                                                                       |
| :------------------------ | :------ | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| access_roles              | Boolean |             | Access roles of the organization.                                                                                                                                                                                 |
| all                       | Boolean |             | Flag, if all Global Data should be exported.                                                                                                                                                                      |
| csc_settings              | Boolean |             | Settings for Customer Service Center customization.                                                                                                                                                               |
| csrf_whitelists           | Boolean |             | CSRF Allowlists. Where possible, we changed noninclusive terms to align with our company value of Equality. Because changing terms in our code can break current implementations, we maintained this object name. |
| custom_preference_groups  | Boolean |             | Custom Preference Groups (Meta Data).                                                                                                                                                                             |
| custom_quota_settings     | Boolean |             | Custom quota settings of the instance.                                                                                                                                                                            |
| custom_types              | Boolean |             | Custom Types (Meta Data).                                                                                                                                                                                         |
| geolocations              | Boolean |             | Geolocations of the organization.                                                                                                                                                                                 |
| global_custom_objects     | Boolean |             | Global custom objects.                                                                                                                                                                                            |
| job_schedules             | Boolean |             | Scheduled job definitions.                                                                                                                                                                                        |
| job_schedules_deprecated  | Boolean |             | Deprecated scheduled job definitions.                                                                                                                                                                             |
| locales                   | Boolean |             | Locales.                                                                                                                                                                                                          |
| meta_data                 | Boolean |             | System object type extensions and custom object type extensions.                                                                                                                                                  |
| oauth_providers           | Boolean |             | OAuth providers.                                                                                                                                                                                                  |
| ocapi_settings            | Boolean |             | Global OCAPI settings.                                                                                                                                                                                            |
| page_meta_tags            | Boolean |             | Page meta tag definitions.                                                                                                                                                                                        |
| preferences               | Boolean |             | Global preferences.                                                                                                                                                                                               |
| price_adjustment_limits   | Boolean |             | Price adjustment limits for all roles.                                                                                                                                                                            |
| services                  | Boolean |             | Service definitions from the service framework.                                                                                                                                                                   |
| sorting_rules             | Boolean |             | Global sorting rules.                                                                                                                                                                                             |
| static_resources          | Boolean |             | Global static resources.                                                                                                                                                                                          |
| system_type_definitions   | Boolean |             | System Type Definitions (Meta Data).                                                                                                                                                                              |
| users                     | Boolean |             | Users of the organization.                                                                                                                                                                                        |
| webdav_client_permissions | Boolean |             | Global WebDAV Client Permissions.                                                                                                                                                                                 |

<!-- document id=34bcc6ec98fbeb5481b0e0bdfef848e24b95e741ca6469b586933074a3635eb2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/exportsitesconfiguration.md -->

# ExportSitesConfiguration document

Document representing a configuration for the site specific data units which should be exported.

| Property                        | Type    | Constraints | Description                                 |
| :------------------------------ | :------ | :---------- | :------------------------------------------ |
| ab_tests                        | Boolean |             | A/B Tests.                                  |
| active_data_feeds               | Boolean |             | Active Data Feeds.                          |
| all                             | Boolean |             | Flag, if all site units should be exported. |
| cache_settings                  | Boolean |             | Cache Settings.                             |
| campaigns_and_promotions        | Boolean |             | Campaigns and Promotions.                   |
| content                         | Boolean |             | Content.                                    |
| coupons                         | Boolean |             | Coupons.                                    |
| custom_objects                  | Boolean |             | Custom Objects.                             |
| customer_cdn_settings           | Boolean |             | Customer CDN Settings.                      |
| customer_groups                 | Boolean |             | Customer Groups.                            |
| distributed_commerce_extensions | Boolean |             | Distributed Commerce Extensions.            |
| dynamic_file_resources          | Boolean |             | Dynamic File Resources.                     |
| gift_certificates               | Boolean |             | Gift Certificates.                          |
| ocapi_settings                  | Boolean |             | OCAPI Settings.                             |
| payment_methods                 | Boolean |             | Payment Methods.                            |
| payment_processors              | Boolean |             | Payment Processors.                         |
| redirect_urls                   | Boolean |             | Redirect URLs.                              |
| search_settings                 | Boolean |             | Search Settings.                            |
| shipping                        | Boolean |             | Shipping.                                   |
| site_descriptor                 | Boolean |             | Site Descriptor.                            |
| site_preferences                | Boolean |             | Site Preferences.                           |
| sitemap_settings                | Boolean |             | Sitemap Settings.                           |
| slots                           | Boolean |             | Slots.                                      |
| sorting_rules                   | Boolean |             | Sorting Rules.                              |
| source_codes                    | Boolean |             | Source Codes.                               |
| static_dynamic_alias_mappings   | Boolean |             | Static, Dynamic and Alias mappings.         |
| stores                          | Boolean |             | Stores.                                     |
| tax                             | Boolean |             | Tax.                                        |
| url_rules                       | Boolean |             | URL Rules.                                  |

<!-- document id=62ed85efae07b56059590a636f5b7c39a2c7d2af69cfaca83833e79f7a3adfa5 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-extend.md -->

# Extend Storefront Next with Features

Enable built-in extensions to add more features to your storefront with the Storefront Next extension framework. You can also build custom extensions to reuse across multiple storefronts or distribute to multiple customers. Independent Software Vendors (ISVs) build extensions that customers install in their storefronts. Implementers apply extensions to multiple customers.

**tip:** - If you plan to use a customization only once, customize your storefront code instead of building an extension.
- To build a Commerce App, see [Commerce Apps Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guide/commerce-apps-overview.html) in the _Commerce Apps ISV Developer Guide_.

All extensions are defined in `/src/extensions/config.json` in the retail app.

## Enable Built-In Extensions

The built-in extensions that are available and enabled by default for your storefront include:

- Store Locator: Enables a shopper to find a store based on a given location.
- Buy Online Pickup In Store: Enables a shopper to order online and pick up their order at a physical store. Requires the Store Locator extension to be installed.
- Multiship: Enables shoppers to ship items to multiple different addresses in a single order.
- (Demo) Buy Now Pay Later: Renders an inline installment message and a payment-schedule modal on the PDP. Ships with mock fixtures; replace the bodies of the API functions to integrate a real provider, such as PayPal, Klarna, and Affirm.
- (Demo) Customer Preferences: Enables shoppers to manage interests and shopping preferences from their account page.
- (Demo) Ratings & Reviews: Renders customer reviews on the Product Detail Page (PDP), the rating summary on the cart-item modal, and the per-line rate-and-review CTA on order detail. Includes prototyped fixtures. Replace the bodies of the API functions to integrate a real provider, such as Bazaarvoice, PowerReviews, Yotpo, and Trustpilot.
- (Demo) Product Content: Renders three PDP surfaces backed by editorial or CMS-style content. The PDF surfaces include a returns and warranty card with a 'View Policies' modal, an 'Ask assistant' FAQ, and the merchant-customizable collapsible sections (Materials, Usage Instructions, Care Instructions, and Specifications). Includes prototyped fixtures. Replace the bodies of the API functions to integrate a real CMS, PIM, or Page Designer-backed content service.
- (Demo) Shipping & Delivery: Renders estimated delivery information on the PDP and provides a zip-code shipping estimator for the Buy Online Pickup In Store delivery flow. Includes prototyped fixtures. Replace the API function bodies to integrate a real shipping provider.

**note:** All the demo extensions aren't connected to data sources. Modify these extensions to connect them to third-party services.

When you create a storefront with the `pnpm dlx @salesforce/storefront-next-dev create-storefront` command, choose which extensions to enable and disable. To enable an extension after the storefront is created, use the `pnpm dlx @salesforce/storefront-next-dev extensions install` command. To disable an extension, use the `pnpm sfnext extensions remove` command. For a command reference, see [Command-Line Interface (CLI) Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-cli.md).

## Build a Custom Extension

Build a custom extension to add more features or reusable components to your storefront. For example, add UI widgets, backend integrations, or business logic add-ons. To build an extension, follow the instructions in [Extensions Directory](https://github.com/SalesforceCommerceCloud/storefront-next-template/tree/main/src/extensions). This file is at `/src/extensions/README.md` in your local retail app folder.

<!-- document id=5887024d335d5d7a24c5ebc861479e76fee2d77ed2314519082df19c164002f6 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/extend.md -->

# Extensibility

Learn how to use the B2C Commerce API (SCAPI) to seamlessly customize and extend functionalities for your unique needs.

- To extend the functionality of existing APIs, use [Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html).
- If you need additional functionality that is not available using the existing hooks, see [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html).

<!-- document id=23b062aef1ee7d73bf4ec064abf71ba328c52cd4fcd4c2351f261128375abc5f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/extension-provider-examples.md -->

# Extension Provider Examples

Extension provider examples are stored in the [commerce-extensiblity](https://github.com/forcedotcom/commerce-extensibility) repo.

## Buyer Groups Extension Example

This [example](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/domain/buyergroup/service/classes/BuyerGroupEvaluationServiceSample.cls) shows an extension provider for a buyer groups service. This example extends the [`CommerceBuyGrp.BuyerGroupEvaluationService`](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_CommerceBuyGrp_BuyerGroupEvaluationService.htm) base class.

## Cart Calculation Orchestrator Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/orchestrators/classes/CartCalculateSample.cls) shows an extension provider for a cart calculation orchestrator. This example extends the [`CartExtension.CartCalculate`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/CartCalculate.html) base class. This example also demonstrates default orchestration behavior for B2B and B2C stores.

**note:** This example demonstrates cart calculation behavior before checkout and during checkout.

## Cart Item Extension Example

This [example](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/endpoint/cart/CartItemExtensionSample.cls) shows an extension provider for a cart item. This example extends the [`ConnectApi.BaseEndpointExtension`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/BaseEndpointExtension.html) base class.

## Cart Item Collection Extension Example

This [example](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/endpoint/cart/CartItemCollectionExtensionSample.cls) shows an extension provider for a cart item collection. This example extends the [`ConnectApi.BaseEndpointExtension`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/BaseEndpointExtension.html) base class.

## Create Order Service Extension Example

This [example](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/domain/checkout/order/createOrder/classes/CreateOrderSample.cls) shows an extension provider for the create order service. This example extends the [`CartExtension.CheckoutCreateOrder`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/CheckoutCreateOrder.html) base class.

## Place Order Service Extension Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/checkout/order/placeOrder/classes) shows an extension provider for the place order service. This example extends the [`CartExtension.CheckoutPlaceOrder`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/CheckoutPlaceOrder.html) base class.

## Inventory Cart Calculator Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/inventory/cart/calculator/classes) shows an extension provider for the inventory cart calculator. This example extends the [`CartExtension.InventoryCartCalculator`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/InventoryCartCalculator.html) base class.

## Pricing Service Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/pricing/service/classes/PricingServiceSample.cls) shows an extension provider for the pricing service. This example extends the [`commercestorepricing.PricingService`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/PricingService.html) base class.

## Promotion Calculator Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/promotion/cart/calculator/classes/PromotionCalculatorSample.cls) shows an extension provider for a promotion calculator. This example extends the [`CartExtension.PromotionsCartCalculator`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/PromotionsCartCalculator.html) base class.

## Shipping Calculator Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/shipping/cart/calculator/classes/ShippingCartCalculatorSample.cls) shows an extension provider for a shipping calculator. This example extends the [`CartExtension.ShippingCartCalculator`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/ShippingCartCalculator.html) base class.

## Split Shipment Service Extension Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/shipping/splitshipment/SplitShipmentSample.cls) shows an extension provider for the split shipment service. This example extends the [`CartExtension.SplitShipmentService`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/SplitShipmentService.html) base class.

## Tax Calculator Example

This [example](https://github.com/forcedotcom/commerce-extensibility/tree/main/commerce/domain/tax/cart/calculator/classes/TaxCartCalculatorSample.cls) shows an extension provider for a tax calculator. This example extends the [`CartExtension.TaxCartCalculator`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/TaxCartCalculator.html) base class.

## Search Products Example

This [example](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/endpoint/search/SearchProductsSample.cls) shows an extension provider for the GET-based [product search](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm) endpoint. This example extends the [`ConnectApi.BaseEndpointExtension`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/BaseEndpointExtension.html) base class.

## Search ProductSearch Example

This [example](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/endpoint/search/SearchProductSearchSample.cls) shows an extension provider for the POST-based [product search](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm) endpoint. This example extends the [`ConnectApi.BaseEndpointExtension`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/BaseEndpointExtension.html) base class.

## Search Suggestions Example

This [example](https://github.com/forcedotcom/commerce-extensibility/blob/main/commerce/endpoint/search/SearchSuggestionsSample.cls) shows an extension provider for [product search suggestions](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_suggestions.htm). This example extends the [`ConnectApi.BaseEndpointExtension`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/BaseEndpointExtension.html) base class.

## Things to Consider While Working with Endpoint Extensions

Here are some key considerations when extending the Commerce APIs using before and after hooks:

- The Endpoint extensions request parameter doesn’t support values of the `StringList` data type.
- During an asynchronous flow, the post hook for `Commerce_Endpoint_Cart_ItemCollection` can execute either before or after the asynchronous cart processing completes. However, if a before hook is present, it always executes before the cart is processed.
- The before and after hooks for `Commerce_Endpoint_Cart_Item` and `Commerce_Endpoint_Cart_ItemCollection` extension providers are triggered regardless of whether the Cart Checkout API (CCA) is enabled or disabled.
- Data Manipulation Language (DML) operations are not supported in before and after hook. For example, if you attempt to perform a DML operation such as an `insert` or `update` within a before or after hook, it triggers an exception and cause the operation to fail.
- Salesforce callouts are supported in before hooks but not in after hooks for endpoints, except for GET requests. For example, you can use a callout in a before PUT hook to validate data before it's saved. However, making a callout in an after PUT hook results in an operation failure.

**See Also**

- [_B2B Commerce Developer Guide_: Available Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/available-extensions.html)
- [_B2B Commerce Developer Guide_: Register and Map Extension Class](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extensions.html)

<!--

## Cart Calculate API Extension Provider Examples

The examples in this section are part of the [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.md) and affect various aspects of cart calculation.

### Cart Calcutation Orchestrator Example

### Inventory Cart Calculator Example

### Inventory Service Example

### Pricing Cart Calculator Example

### Pricing Service Example

### Shipping Cart Calculator Example

### Tax Cart Calculator Example

### Tax Service Example

## Connect API Endpoint Extension Provider Examples

### Commerce_Endpoint_Account_Addresses Example

### Commerce_Endpoint_Account_Address Example

### Commerce_Endpoint_Catalog_Products Example

### Commerce_Endpoint_Catalog_Product Example



### Commerce_Endpoint_Search_ProductsByCategory Example

## Checkout Example

## Order Management Example

-->

<!-- document id=e5bd21cd24b9118cf0a4e8b1a2cdcbe9f7fd5f25282605a6ce2b90196778158d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_fact_tables.md -->

# Fact Tables

Fact tables contain the quantitative data or "facts" about business events, often linked to dimension tables by foreign keys.

| Fact Table Name                                                                                  | Description                                                                                                                                                                    | Indices                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ccdw_fact_customer_list_snapshot](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_customer_list_snapshot.md)                     | Provides snapshots of customer list metrics over time.                                                                                                                         | None listed                                                                                                                                                                                                                  |
| [ccdw_fact_customer_registration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_customer_registration.md)                       | Records customer registration events.                                                                                                                                          | None listed                                                                                                                                                                                                                  |
| [ccdw_fact_inventory_record_snapshot](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_inventory_record_snapshot.md)               | Captures daily snapshots of inventory levels. Data currently only represents data sourced from OCI.                                                                            | `inventory_record_id`, `utc_record_timestamp`, `utc_record_day_id`, `utc_record_time_id`, `location_id`, `location_group_id`, `sku_id`                                                                                       |
| [ccdw_fact_inventory_record_snapshot_hourly](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_inventory_record_snapshot_hourly.md) | Captures hourly snapshots of inventory levels. Contains similar fields to the daily snapshot but at a finer granularity. Data currently only represents data sourced from OCI. | `inventory_record_id`, `utc_record_timestamp`, `utc_record_day_id`, `utc_record_time_id`, `location_id`, `location_group_id`, `sku_id`                                                                                       |
| [ccdw_fact_line_item](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_line_item.md)                                               | Captures details of individual line items within orders. Each row represents a line item in an order.                                                                          | `line_item_id`, `order_id`, `sku_id`, `std_submit_day_id`, `site_id`, `business_channel_id`, `norder_id`, `locale_id`, `user_agent_id`, `customer_id`, `utc_submit_timestamp`, `utc_submit_day_id`                           |
| [ccdw_fact_order_payments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_order_payments.md)                                     | Records payment transactions for orders. Each row represents an order payment.                                                                                                 | `order_payment_id`, `site_id`, `business_channel_id`, `payment_method_id`, `std_submit_day_id`, `locale_id`, `user_agent_id`, `norder_id`, `customer_id`                                                                     |
| [ccdw_fact_promotion_activation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_promotion_activation.md)                         | Records instances where promotions are activated.                                                                                                                              | `promotion_activation_id`, `promotion_id`, `campaign_id`, `std_activation_day_id`, `activation_site_id`, `locale_id`, `user_agent_id`, `customer_id`, `utc_activation_timestamp`, `utc_activation_day_id`                    |
| [ccdw_fact_promotion_line_item](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_promotion_line_item.md)                           | Records the application of promotions to individual line items. Each row represents a promotion line item in an order.                                                         | `promotion_line_item_id`, `promotion_id`, `sku_id`, `order_id`, `std_submit_day_id`, `site_id`, `business_channel_id`, `coupon_id`, `locale_id`, `user_agent_id`, `customer_id`, `utc_submit_timestamp`, `utc_submit_day_id` |
| [ccdw_fact_realtime_metric](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_realtime_metric.md)                                   | Captures real time metrics.                                                                                                                                                    | `metric_id`, `metric_name,create_date`                                                                                                                                                                                       |
| [ccdw_fact_source_codes_activation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/jdbc_ccdw_fact_source_codes_activation.md)                   | Records the activation of source codes.                                                                                                                                        | `source_code_activation_id`, `source_code_group_id`, `user_agent_id`, `customer_id`, `utc_activation_day_id`, `std_activation_day_id`, `activation_site_id`, `locale_id`                                                     |

<!-- document id=fd616b38ec6b1e3c03172841a4d23bdb2422e64a65518374a84d9913ebddf6b6 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/references/about/feature-retirement.md -->

# Feature Retirement

This page lists Managed Runtime features that are scheduled for retirement or have already been retired. Retirement means the feature is no longer supported after the listed date. Take action before the retirement date to avoid disruptions to your storefront.

**tip:** Watch your email for automated notifications as retirement dates approach. See [Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.md) for announcements.

## Scheduled Retirements

| Feature                 | Retirement Date  | Action Required                                                                                                                                                                                      |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| x86 server architecture | January 31, 2027 | Switch environments to ARM in Runtime Admin under environment settings. See [Server-Side Rendering Architecture](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#server-side-rendering-architecture). |
| Node.js 22.x            | June 1, 2027     | See [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md).                                                                                                                                    |

## Past Retirements

| Feature                   | Retired            | Notes                                                             |
| ------------------------- | ------------------ | ----------------------------------------------------------------- |
| HTTP proxy configurations | August 31, 2026    | See [Proxy Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/proxying-requests.md).          |
| Node.js 20.x              | April 30, 2026     | See [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md). |
| Node.js 18.x              | September 1, 2025  | See [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md). |
| Node.js 16.x              | September 13, 2023 | See [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md). |
| Node.js 14.x              | September 13, 2023 | See [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/upgrade-node-version.md). |

<!-- document id=bf684fa9046212fc2895d75f6a232e8e4ad178d5f633b702617bdbb4cc98af86 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_filter_clone_history.md -->

# Filter and Search Clone History

Refine the clone history view using filters and search options.

Use the **Filter & Search** options in the Activity Timeline to refine the clone history view.

1. Navigate to the **Activity Timeline** tab for a sandbox instance.
2. Use the **Time Period Filter** to limit results by date range.
   - Available time period options:
     - Last day
     - Last 7 days
     - Last month
     - Last 6 months
     - Last year
3. Use the **Status Filter** to show only clones with a specific status.
   - Available status options:
     - In Progress
     - Completed
     - Failed
4. Use the **Search** field to search by source instance, target instance, or time/date.

<!-- document id=f476ba537e329f56bff9e8840b697702f41db358e2e36b815cdc7ebe51f1dbf1 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/fiscal-spi.md -->

Fiscal SPI

# Fiscal SPI

**Partial reference:** 3 operation(s) were omitted because their source references could not be resolved.

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/fiscal-spi/fiscal-spi-oas-public.yaml)

Merchant SPI endpoints for fiscal integration. These are sample endpoints that provide specifications for merchants on how to implement fiscal API on their end and then configure them in CMS. The fiscal SPI enables Point of Sale to delegate fiscal operations (SALE, RETURN, LOGIN, LOGOUT, etc.) to a merchant-provided SI connector.

**Version:** 2.3.4

## Tags

### Fiscal SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/fiscal-spi/fiscal-spi-oas-public.yaml)

Merchant SPI endpoints for fiscal integration. These are sample endpoints that provide specifications for merchants on how to implement fiscal API on their end and then configure them in CMS. The fiscal SPI enables Point of Sale to delegate fiscal operations (SALE, RETURN, LOGIN, LOGOUT, etc.) to a merchant-provided SI connector.

<!-- document id=180e9ab8cd65d9c0319dc11a0e7feefc7e2d49c2926e562b7ace6cf547afe222 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/best-practices.md -->

# Follow Best Practices

Protect your shoppers' data and enhance their shopping experience with these best practices for site performance, security, privacy, and more. This section contains these guides.

- [Site Performance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-performance/b2c-site-performance.md)
- [Custom Caches](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/caches/b2c-custom-caches.md)
- [Caching Strategies](https://developer.salesforce.com/docs/commerce/solutions/guides/caching-strategies-sk.md)
- [B2C Commerce Security Guide](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_security_guide.htm&type=5)
- [Data Protection and Privacy](https://help.salesforce.com/s/articleView?id=cc.b2c_data_protection_and_privacy.htm&language=en_US&type=5)
- <a href="https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html" target="_blank">Bot Management</a>
- <a href="https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-mitigation-sk.html" target="_blank">Bot Mitigation Best Practices for Flash Sales</a>
- [SEO for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_seo_overview.htm&type=5)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=e1633d72540b49047282e9bd956817ea06aebb01195977ef7d6237355c75eebe url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/sfra/b2c-forms.md -->

# Forms

Create HTML forms in B2C Commerce using templates and controllers. Using form definitions, persist form data during a session and store it in system objects or custom objects.

## Creating a Form

Create a standard HTML form that uses AJAX for validation and error rendering. If you're creating a simple form that doesn't store data, is easily localized, and only requires client-side validation, this type of form is appropriate. Create a complex form that stores data, requires server-side validation, and has sophisticated localization requirements. Sophisticated localization can include adding, removing, or rearranging fields in the form or changing the data object you have to store with form data.

If you're creating a complex form, use a B2C Commerce form definition. A form definition results in an in-memory object that persists during the session. Use this object with various platform features for localization, server-side validation, and data storage.

The following example uses a form definition. The form has a text field to input a nickname, a submit button, and a cancel button. After the form is submitted, another page is rendered that shows the nickname entered in the previous form.

### Form Definition

The first thing you create for a form is the form definition. The form definition describes the data you need from the form, the data validation, and the system objects you want to store the data in. This example only has one input field and two buttons. This form doesn't validate or store data permanently.

SFRAFormDef.xml

```
<?xml version="1.0"?>
<form xmlns="http://www.demandware.com/xml/form/2008-04-19">
	<field formid="nickname" label="Nickname:" type="string" mandatory="true" max-length="50" />
	<action formid="submit" valid-form="true"/>
	<action formid="cancel" valid-form="false"/>
</form>
```

### In-memory Form Object

The form definition determines the structure of the in-memory form object. The in-memory form object persists data during the session, unless you explicitly clear the data.

In the Storefront Reference Architecture (SFRA), the first step to create a form is to create a JSON object to contain the form data. The `server.getForm` function uses the form definition to create this object. Data from the form is accessible in templates using the `pdict` variable. However, the form is available only if the `server.getForm` object is passed to the template by the controller.

### Controller to Render the Form

The controller in this example exposes a `Start` function that renders an empty form.

The `Start` function sets the `actionURL` that's used to handle the submit action for the form and creates a JSON object based on the form definition.

#### SFRAForm.Js

```
/**
 * A simple form controller.
 *
 */

'use strict';
var server = require('server');
var URLUtils = require('dw/web/URLUtils');

server.get(
 'Start', server.middleware.http, function (req, res, next) {
    var actionUrl = URLUtils.url('SFRAFormResult-Show'); //sets the route to call for the form submit action
 var SFRAhelloform = server.forms.getForm('SFRAFormDef'); //creates empty JSON object using the form definition
 SFRAhelloform.clear();

   res.render('SFRAFormTemplate', {
       actionUrl: actionUrl,
       SFRAhelloform: SFRAhelloform
   });
 next();
});

module.exports = server.exports();
```

### Form Template - SFRAFormTemplate.isml

In this example, `SFRAFormTemplate.isml` is the empty form rendered for the user and the `SFRAResultTemplate.isml` shows data entered into the form.

The form action uses the `actionUrl` property passed to it by the controller.

The client-side JavaScript and css files are included using the `assets.j`s module.

```
<!--- TEMPLATENAME: helloform.isml --->
 <!--- <isscript>
var assets = require('*/cartridge/scripts/assets.js');
assets.addCss('/css/helloform.css');
assets.addJs('/js/helloform.js'); </isscript>--->

<div class="hero slant-down login-banner">
	<h1>SFRA Hello World Form</h1>
</div>

<!--- --->
<div class="card">
	<form action="${pdict.actionUrl}" class="login" method="POST"
		name="SFRAHelloForm">

		<div class="form-group required">
			<label> Nickname: </label> <input type="input" id="nickname"
				class="form-control" name="nickname">
		</div>

		<button type="submit" class="btn btn-block btn-primary">Submit</button>
		<button type="submit" class="btn btn-block btn-primary">Cancel</button>
	</form>
</div>
```

### Controller to Render Form Results - SFRAFormResult.Js

After a form is submitted, data from the form is available as part of the `req.form` property. In the following example, the nickname entered in the original form is passed to a new template for rendering.

```
/**
 * Handles the simple form rendered by the SFRAForm.js controller.
 *
 */

'use strict';
var server = require('server');
var URLUtils = require('dw/web/URLUtils');


server.post('Show', server.middleware.http,
  function(req, res, next) {

  var nickname = req.form.nickname;

  res.render('SFRAResultTemplate', {
    nickname : nickname});
   next();
  });

module.exports = server.exports();
```

### Form Result Template - SFRAResultTemplate.isml

This template prints the form field label and data stored from the form.

```
<<!--- TEMPLATENAME: SFRAResultTemplate.isml --->
<iscontent type="text/html" charset="UTF-8" compact="true" />
<!doctype html>
<head></head>
<body>
<h1>Hello World Form Result</h1>
<p>Nice to meet you, ${pdict.nickname}.</p>
</body>
</html>
```

### Hiding Form Fields

Most SFRA forms are standard HTML forms, so use `input type="hidden"` to hide form fields in templates.

### Reusing Form Definitions

The form you create in your template can contain fields from multiple form definitions. The same fields can be reused in other forms as many times as required. This ability can be useful for prepopulating form data that the customer has already entered. For example, address or payment preference data.

### Using Form Metadata

Use the metadata entered for a custom or system object in Business Manager to determine form definition information. This manages data attributes in one place without having to change code. For example, if you wanted to let merchants change the labels on form fields, you could include `label` as a metadata attribute and reference it.

### Dynamic, Multi-Part, Embedded, or Nested Forms

SFRA doesn't include dynamic forms.

However, if you want to create them, use the `isdynamicform` tag to generate dynamic forms. The `dynamicform.isml` template and the `dynamicForm.js` script control how code is generated using the `isdynamicform` tag.

SFRA doesn't include multi-part, embedded, or nested forms. We don't recommend them as a best practice.

## Localizing a Form

Change the structure of a form depending on the locale. For example, include different address fields, such as state or province, depending on the country. To localize the form structure, create different form definitions for each locale. These form definitions have the same name, but a different structure or different fields for different locales.

In your cartridge, create a `forms/default` folder for the standard locale and then separate folders that are named for each locale of the form. Store a different form definition in each locale folder. If a locale doesn't have a separate folder, the default form definition is used.

```
forms
	default
		billingaddress.xml
	it_IT
		billingaddress.xml
	ja_JP
	billingaddress.xml
```

### Localizing Strings Within Simple Forms

Use resource strings directly from a form. The following example is of the `loginform.isml` that logs customers into the site. In this case, the form uses the `label.input.login.email resource string identifier.`

```
<form action="${pdict.actionUrl}" class="login" method="POST" name="login-form">
    <div class="form-group required">
        <label class="form-control-label" for="login-form-email">
            ${Resource.msg('label.input.login.email', 'login', null)}
        </label>
        <input type="email" id="login-form-email" class="form-control" name="loginEmail" value="${pdict.userName}">
        <div class="form-control-feedback"></div>
    </div>
```

Depending on the locale, this resource identifier resolves to different values

In the English `app_storefront_base/cartridge/templates/resources/login.properties` file:

```
label.input.login.email=Email
```

In the French `app_storefront_base/cartridge/templates/resources/login_fr_FR.properties` file:

```
label.input.login.email=E-mail
```

**note:** Remember to add the country to select to your country selector and to configure the locale for the site in Business Manager.

### Localizing Strings Within Complex Forms

All form strings can be replaced with resource strings. Resource strings for forms are located by default in the `forms.properties` file for your cartridge and referenced from the form definition file. Add files with the name `forms_locale_.properties` to add localized strings. For example, add a `forms_it_IT.properties` file for an Italian version of the same properties. Different fields for the form may be needed, depending on the locale. Make sure that the strings for those fields are included in the localized version of the properties files.

### Example: Localizing Labels and Error Messages

The following form definition file defines a form to enter contact information. This example doesn't show the entire form definition, just some of the fields that use localized strings for labels and error messages. Find this file as the `contactus.xml` form in the SiteGenesis `app_storefront_core` cartridge.

```
<?xml version="1.0"?>
<form xmlns="http://www.demandware.com/xml/form/2008-04-19">

	<field formid="firstname" label="contactus.firstname.label" type="string" mandatory="true" binding="firstName" max-length="50"/>
	<field formid="lastname" label="contactus.lastname.label" type="string" mandatory="true" binding="lastName" max-length="50"/>
	<field formid="email" label="contactus.email.label" type="string" mandatory="true"  parse-error="contactus.email.parse-error" />
```

The label and error strings in bold reference the properties set in the `forms.properties` file, which contains entries like the following for the default site locale:

```
##############################################
# Template name: forms/contactus
##############################################
contactus.firstname.label=First Name
contactus.lastname.label=Last Name
contactus.email.label=Email
contactus.email.parse-error=The email address is invalid.
```

The form is localized in the `forms_it_IT.properties` file (along with the other locale-specific `forms_locale_.properties` files) with entries like the following:

```
##############################################
# Template name: forms/contactus
##############################################
contactus.firstname.label=Nome
contactus.lastname.label=Cognome
contactus.email.label=Email
contactus.email.parse-error=L'indirizzo email non è valido.
```

## Validating Form Data

Server-side validation on form data is configured in the form definition. SFRA uses jQuery AJAX methods to render a page after server-side validation.

### Validation by Attribute

The attributes set on the form field are used for validation. In the following example, the `mandatory` attribute requires a value for the field. The `regexp` attribute determines the content of the field. And the `max-length` attribute sets the maximum length of the data for the field.

**note:** The `max-length` attribute is used only for validation of strings. For other field types, it's used only to format the field length and not to validate data.

```
<field formid="email" label="contactus.email.label" type="string" mandatory="true" regexp="^[\w.%+-]+@[\w.-]+\.[\w]{2,6}$" max-length="50"/>
```

Errors shown for attribute validation:

- Default error for form invalidation: `value-error`
- Mandatory flag invalid: `missing-error`

- Entered value invalid: `parse-error`

### Validation by Function

Use the validation attribute to specify a function to run to validate form data. Run these validations on container elements, such as form or group, or on individual fields.

```
<field formid="password"
       label="label.password"
       type="string"
       range-error="resource.customerpassword"
       validation="${require('~/cartridge/scripts/forms/my_custom_script.ds').my_custom_validation(formfield);}"
```

Selectively invalidate form elements using the `InvalidateFormElement` pipelet in pipelines or the `invalidateFormElement` function in the `FormModel` or any model that requires it. If any element in a form is invalid, the entire form is invalid. However, in your form definition, create error messages that are specific to a field. See the example of `range-error`, which points to a resource string with a message for the customer on why the field is invalid.

### Client-Side Validation Scripts

Simple forms are standard HTML forms, so use any client-side validation method you choose. B2C Commerce uses default HTML5 validation for client-side validation. Find the client-side JavaScript for a page by identifying the script added by the `assets.AddJs` function.

B2C Commerce provides two utility scripts for validating form data:

- form-validation: This script validates a specific field in the form. It uses the validation criteria set in the form definition and included in the attributes for the form JSON object. This script is required by the client-side JavaScript doing the validation for a specific form and is loaded at `document.ready`. This file is located in `app_storefront_base/cartridge/client/js/default/components/form-validation.js`.
- client-side-validation: This script validates the entire form and clears a form for validation. This file is required by `main.js`. It’s located in `app_storefront_base/cartridge/client/js/default/components/client-side-validation.js`

## Saving Form Data

The `route:BeforeComplete` event is used to store form data. Different APIs are used to save data, depending on the type of form.

This example constructs an object that contains the relevant information from the form and saves it to the `ViewData` object, so it can be passed. This example can be seen in the `Account.js` `SavePassword` function.

```
var profileForm = server.forms.getForm('profile');       //gets the profile form object
var newPasswords = profileForm.login.newpasswords;
...
var result = {                                           //constructs an object containing the form result
    currentPassword: profileForm.login.currentpassword.value,
    newPassword: newPasswords.newpassword.value,
    newPasswordConfirm: newPasswords.newpasswordconfirm.value,
    profileForm: profileForm
};

if (profileForm.valid) {
    res.setViewData(result);                         // adds form result to the ViewData object
    this.on('route:BeforeComplete', function () { // creates the function to run before middleware completion
        var formInfo = res.getViewData();            // creates object with data to save
        var customer = CustomerMgr.getCustomerByCustomerNumber( //gets current customer
            req.currentCustomer.profile.customerNo
        );
        var status;
        Transaction.wrap(function () {                //saves the new customer password and returns status
            status = customer.profile.credentials.setPassword(
                formInfo.newPassword,
                formInfo.currentPassword,
                true
            );
        });
```

## Clearing or Refreshing a Form

In SFRA, you use the `server.getForms` function to get the form data structure from the relevant form definition and convert it into a JSON object. The object is then added to the data passed to the template, so that it's available to the template via the `pdict` variable. To clear the form, you must manually call the `clear` method.

This example gets the profile form and clears it.

```
function (req, res, next) {
    var accountModel = getModel(req);
    var profileForm = server.forms.getForm('profile'); //gets the profile form object
    profileForm.clear();              //clears the form using a function from the server module forms.js
```

## Prepopulating Form Data

Prepopulate forms with information from system objects, custom objects, and form data.

### To Get Data from System Objects

Use the `server` module `form.js`copyObjectToForm` method to get data from an existing form object. Use the metadata attributes for a system or custom object to prefill form data.

### To Get Data from Other Forms

Use the `FormModel`.js `copyFrom` function to get data from an existing form object. Usually, if you have used `app.getForm` to get a copy of a form model, it makes more sense to use the function. Transfer form data from one form to another directly. In the following example, if a customer decides to use the shipping address for billing, the values from one form are copied to the other.

```
server.get(
    'EditProfile',
    server.middleware.https,
    csrfProtection.generateToken,
    userLoggedIn.validateLoggedIn,
    function (req, res, next) {
        var accountModel = getModel(req);
        var profileForm = server.forms.getForm('profile'); //gets the profile.xml form definition and converts it to a JSON object.
        profileForm.clear();                               //clears the JSON object
        profileForm.customer.firstname.value = accountModel.profile.firstName;    //copies data from one field to another
        profileForm.customer.lastname.value = accountModel.profile.lastName;
        profileForm.customer.phone.value = accountModel.profile.phone;
        profileForm.customer.email.value = accountModel.profile.email;
        res.render('account/profile', {
            profileForm: profileForm,                                          //adds the JSON object to the data for the template
            breadcrumbs: [
                {
                    htmlValue: Resource.msg('global.home', 'common', null),
                    url: URLUtils.home().toString()
                },
                {
                    htmlValue: Resource.msg('page.title.myaccount', 'account', null),
                    url: URLUtils.url('Account-Show').toString()
                }
            ]
        });
        next();
    }
    );
```

### To Copy Values from One Object to Another

To copy values from one custom object to another, don't use the `dw.web.FormGroup` `copyFrom()` and `copyTo()` methods. The `copyTo()` method requires a form submit to set values in the custom object. Instead, use Javascript to directly copy the values, as in this example:

```
let testObject = { name:"default name", subject:"default subject", message:"default message" };
let output = {};
Object.keys( testObject ).forEach( function( key ) {
   output[key] = testObject[key];
});
```

## Converting Form Data to JSON Objects

Prepopulate forms with information from system objects, custom objects, and in-memory form data. This data is available directly from the model you're working with or from the `ViewData` object used for rendering the template. The `server` module in the `modules` folder includes a `forms.js` module that converts form data into JSON objects. For more information, see the following functions in the server-side JSDoc.

- `parseForm(Form)`
- `copyObjectToForm(object, CurrentForm)`
- `findValue(formGroup, name)`
- `clearOptions(obj)`

SFRA provides a forms module that abstracts the form definition into a JSON representation. If you want to work with JSON objects, use the modules and forms methods to get and store data.

## Securing Forms

Use the new CSRF (Cross-Site Request Forgery) framework to add fields that are protected from request forgery.

CSRF in SFRA is provided as middleware by B2C Commerce. CSRF checks are performed as the middleware step `csrfProtection.validateAjaxRequest.`

Example: CSRF check is made for login information. This example is available in the `Account.js` controller.

```
server.post(
    'Login',
    server.middleware.https,
    csrfProtection.validateAjaxRequest,
    function (req, res, next) {
        var data = res.getViewData();
        if (data && data.csrfError) {
            res.json();
            return next();
        }
```

For more information, see `validateRequest` and `validateAjaxRequest` in the JSDoc.

<!-- document id=5d6d7da6d6efabe203f83d9d7372a825b278a38ec4a55166bd2b9ab24fc03dd6 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-profile-connector/FAQ.md -->

# Frequently Asked Questions

**Q:** How do shopper profile rules work with existing product recommendation rules in the Einstein Configurator for each recommender?

**A:** Shopper profile rules enhance the results generated by product recommendation rules. The Einstein engine first generates initial recommendation results based on how merchants set up recommenders, strategies, and product rules. Only after these initial results are generated does the Einstein engine use shopper profile rules to promote or demote products mapped within the results.

---

**Q:** How do multiple shopper profile rules work together?

**A:** The more shopper profile rules a product matches, the higher their preference and the higher they appear in sorting order. For example, if you configure five shopper profile rules, and product A matches all five of the rules, product B matches two of the rules, and product C matches none of the rules, the product sorting order for the recommendation results is A, B, C.

---

**Q:** Why do shopper profile rules not support show or hide actions?

**A:** Rules like show or hide, because they filter matched results, can potentially lead to fewer recommendations than desired. The promote and demote rules do not eliminate recommendations, but alter the order in which a recommendation appears to the shopper.

---

**Q:** Can I apply shopper profile rules to all recommender types?

**A:** With the exception of the Complete the Set recommender, this API applies to all recommender types. The Complete the Sets recommender generates set recommendations based on product attributes and automatically takes gender, age, and other factors into consideration.

---

**Q:** Can I preview the recommendation results for each shopper profile rule?

**A:** Yes, you can preview recommendation results with one or more shopper profile rules enabled. We recommend that you test rules thoroughly using the Preview option provided for each recommender.

---

**Q:** How many shopper profile rules can I add to a recommender?

**A:** You can add up to 15 shopper profile rules to each recommender. After you reach that limit, the `Add Shopper Profile Rule` button is disabled. To add a new shopper profile rule to the recommender, you must first remove an existing rule.

---

**Q:** I understand that I can configure up to 30 product rules and up to 15 shopper profile rules for each recommender in Einstein Configurator. Can extra mapping rules be allowed?

**A:** Not currently. Applying too many rules to a recommender can adversely affect recommendation results. It’s also harder to manage. For these reasons, we encourage you to add rules sparingly to avoid confusion, overlap, and possible contradiction.

---

**Q:** Does Einstein automatically take in customer groups set up in Business Manager?

**A:** No. Einstein does not currently support the use of customer group data.

---

**Q:** Does Einstein require shoppers to log in to use this feature?

**A:** This feature works for anonymous shoppers if you implement the `updateProfile` activity with `cookieId`. For more information, access the Send Profile Data section and review the User Identifiers sections under both Bulk Upload and Real-Time Activity Tracking.

<!-- document id=0c74a5fcf491f425c6c03bee208e79e83be4d9a550c5d3a3f4de93f7069df2ee url=/developer/current/en-us/commerce-cloud/sfra/guides/sfra-faq.md -->

# Frequently Asked Questions

Storefront Reference Architecture (SFRA) provides customers with a starting point for web-storefront design. It combines best practices in site design and technical architecture to provide a blueprint for merchants looking to build and customize their ecommerce storefronts. It includes:

- A JavaScript controllers development and customization model which allows teams to use a model-view-controller (MVC) development pattern.
- The popular Bootstrap UI framework to optimize the shopping experience across devices.

_SFRA was launched in 2018 as a successor to the SiteGensis framework. In 2021, an alternative to SFRA, [PWA Kit and Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/getting-started.md) was launched. Talk to your Account Manager to understand which is the best fit for your needs._

Here are the answers to your most frequently asked questions...

**Are merchants using SiteGenesis required to move to the B2C Commerce Storefront Reference Architecture?**

No. Merchants are encouraged to move to the B2C Commerce Storefront Reference Architecture when it is right for them. It should be considered during planned site-redesigns to make sure brands are using the latest and greatest storefront innovation.
Merchants who are not ready for a site-redesign can continue to leverage the existing SiteGenesis—a storefront framework trusted across over 2,700 sites. With native responsive design, a codebase fundamental to modifying the entire user experience based on the shopper’s device, merchants can build mobile optimized sites, and many already have.
B2C Commerce provides merchants resources to optimize their existing storefront environments, and plan for future site redesigns, including:

- Mobile design best practices, based on data-driven insight into more than 2,000 mobile sites. These best practices, such as a persistent search bar and simplified categorization can be implemented today in the existing current reference architecture.
- Cloud’s Retail Practice team can provide mobile design consultations and heat mapping to allow merchants to optimize their existing storefront environment. B2C Commerce Practice Accelerators provide best practices on user experience and visual design.

**Who is the Storefront Reference Architecture intended for?**

The Storefront Reference Architecture provides merchants with the latest mobile optimized design and architecture components for merchants willing to make an investment in site design or redesign. The new storefront architecture is being created with two main audiences in mind:

- Merchants who are beginning new site implementations with B2C Commerce.
- Merchants who are making a major overhaul of their existing storefront.

![Use Cases](https://developer.salesforce.com/docs/media/sfra/sfrausecases.jpeg)

**For merchants who want to take advantage of the Storefront Reference Architecture, do they have to reimplement their entire digital platform?**

Merchants do not have to reimplement their digital platform in order to take advantage of the Storefront Reference Architecture. All the pre-existing data, merchant rules, etc. built in B2C Commerce will remain unaffected. Merchants who choose to implement the Storefront Reference Architecture are able to evolve their storefront while taking advantage a new underlying codebase. Adopting the Storefront Reference Architecture allows brands to maintain their existing backend integrations, customer data, catalog, rules, and the digital capabilities that marketers and merchandisers already know and love.

Merchants typically redesign their sites every 3 to 5 years, so they should plan to incorporate the new reference architecture into their ongoing development process. As site redesigns can be resource heavy, customers are advised to adopt the new architecture at their own pace during evolutionary site redesigns.

**What about LINK integrations?**

B2C Commerce is committed to making sure that the new reference architecture is ecosystem ready, this includes the LINK technology ecosystem. LINK partners have been engaged prior to GA to make sure they have a head-start building cartridges for the Storefront Reference Architecture. Currently there are over 30 LINK technology providers that have integrations into the Storefront Reference Architecture, this includes essential storefront functionality like payments, tax, ratings and reviews, shipping, and more.
As merchants leverage a wide variety of LINK cartridges, it is anticipated there will be cartridges that will not be compatible to the new reference architecture by the GA date. When evaluating new site designs or redesigns, merchants and system integrators should check the LINK marketplace for the latest list of certified cartridges.

**What is the upgrade path to the Storefront Reference Architecture?**

While the reference architecture serves as a blueprint for building a site, customer developers are free to customize and extend the reference architecture code base. Brands are empowered to design “pixel perfect” sites and meticulously build unique web experiences. Developers bring in new code (both custom and community developed), integrate with 3rd party providers, and progressively iterate on their site designs. As a result, merchants completely own their storefront and the underlying code base.
The Storefront Reference Architecture introduces a new Model-View-Controller (MVC) architecture. The new MVC architecture is component based which means that developers can build new components (for example, features like Wishlist, Apple Pay, Payment Integrations, etc.) and independently plug them into the storefront. This architecture allows for a more lightweight and cleaner codebase allowing for continuous, iterative, and evolutionary site design.
As merchants fully own and customize their reference architecture code base, no two sites are identical. Due to that, along with the new architecture, the Storefront Reference Architecture is intended for merchants who are beginning new site implementations or redesigning their existing storefront.

**Can I use SiteGenesis and the Storefront Reference Architecture between brands or regions?**

Merchants can use the existing SiteGenesis architecture and the new Storefront Reference Architecture across different brands or regions at the same time. For example one brand or region could run on the Storefront Reference Architecture and another brand or region could run on SiteGenesis. However, this may introduce some additional developer operational and code management complexity that merchants should consider.

**Is there feature parity between the Storefront Reference Architecture and SiteGenesis?**

The Storefront Reference Architecture will GA with with all must-have features needed to build a B2C Commerce storefront. Developers can begin a new site redesign project with confidence it has the features they need to build a site. Q3 2018 will bring full feature parity. Merchants can expect three additional features coming Q3 2018 including: wish lists, gift registry, gift certificates. See the Feature List for more information.

**What will happen to the roadmap for existing the SiteGenesis platform after the Storefront Reference Architecture is launched?**

B2C Commerce’s best-in-class SiteGenesis architecture is currently being used by over 2,700 B2C Commerce sites and is a proven foundation to some of the world’s leading brands. SiteGenesis will continue to be supported and receive maintenance for high priority bug fixes and security-related issues—there is no plan to discontinue support.
SiteGenesis customers will also continue to receive platform innovation through the B2C Commerce API layer. Customers can choose to adopt platform innovation into their storefront through the API layer. The new MVC architecture is built for developer efficiency and to accelerate the feature adoption process.

**What other tools will be available, and how can I learn about the Storefront Reference Architecture in advance?**

There will be tools, documentation, and guidance resources available to help deploy a new site on the Storefront Reference Architecture. B2C Commerce will also be building wireframe commentary around Storefront Reference Architecture UX enhancements. This commentary will include descriptions of new features, annotations of UX design placement, and statistics supporting design decisions.

B2C Commerce will be conducting in-house developer training sessions to help with any architectural design questions and many system integrators have already been introduced to the Storefront Reference Architecture and are participating in the developer preview.

<!-- document id=6a0b6773d22967ea53f0e15d2d8e5350922650074d80491175da7a10654bcd8f url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/fulfillment-order-api.md -->

Fulfillment Order API

# Fulfillment Order API

**Partial reference:** 2 operation(s) were omitted because their source references could not be resolved.

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/fulfillment-order-api/fulfillment-order-api-oas-public.yaml)

APIs for in-store fulfillment of orders (BOPIS, BOFIS, ROPIS) imported into the POS from other channels.

**Version:** 2.3.4

## Tags

### Fulfillment Order API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/fulfillment-order-api/fulfillment-order-api-oas-public.yaml)

APIs for in-store fulfillment of orders (BOPIS, BOFIS, ROPIS) imported into the POS from other channels.

## Operations

### POST Create BOFIS order.

`POST /merchant/v1/sa/fulfillment/orders/bofis`

Operation ID: `createBofisOrder`. Tags: Fulfillment Order API.

Create a BOFIS order in the POS system and allocate inventory for store fulfillment.

#### Request body

Media type: `application/json`. Schema: `FulfillmentOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Create BOPIS order.

`POST /merchant/v1/sa/fulfillment/orders/bopis`

Operation ID: `createBopisOrder`. Tags: Fulfillment Order API.

Create a BOPIS order in the POS system and allocate inventory for store fulfillment.

#### Request body

Media type: `application/json`. Schema: `FulfillmentOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Cancel BOPIS Items.

`POST /merchant/v1/sa/fulfillment/orders/{bopisOrderId}/stores/{storeId}/bopis/cancel`

Operation ID: `cancelBopisItems`. Tags: Fulfillment Order API.

Cancels BOPIS items for a specific order and store.

#### Parameters

*   `bopisOrderId` (path, string, required)
*   `storeId` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `ExternalBopisCancellationRequest`.

#### Responses

*   **default** default response
    
    Media type: `application/json`. Schema: `FulfillmentEvent`.
    

### POST Create ROPIS order.

`POST /merchant/v1/sa/fulfillment/orders/ropis`

Operation ID: `createRopisOrder`. Tags: Fulfillment Order API.

Create a ROPIS order in the POS system and allocate inventory for store fulfillment.

#### Request body

Media type: `application/json`. Schema: `FulfillmentOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### FulfillmentOrder

*   `orderId` (_string_, required) Order ID. In the case of ROPIS, the orderID serves as the uspendedCartId as POS generates a brand new orderId for the ROPIS order during checkout.
*   `orderType` (_string_, required) Order Type. BOPIS = STORE\_PICKUP, BOFIS = STORE\_FULFILLMENT,ROPIS = ONLINE\_RESERVE.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `orderSource` (_string_, required) OrderSource must be WEB for BOPIS, BOFIS and ROPIS orders.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `storeId` (_string_, required) StoreId which is going to fulfill the order.
*   `status` (_string_, required) Store fulfillment status. Possible values include: 1. PACK: BOPIS, BOFIS OR ROPIS item is packed by store associate. 2. DELIVERED: BOPIS item is picked up by the customer or pickup person. 3. CANCELED: BOPIS or BOFIS item is canceled by store associate. 4. SHIPPED: BOFIS item is shipped by store associate. 5. READY: When importing a fulfillment order into POS, it must have a 'READY' status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`.
*   `orderDate` (_integer (int64)_, required) Date when order was placed. Represented as number of milliseconds since epoch.
*   `totalAmount` (_number_, required) Order total.
*   `taxSubTotal` (_number_, nullable) Total tax amount for this order. Excludes any product price or shipping cost. Includes only the sum of taxes. Mandatory: If taxes are applicable, refer to valueAddedTax for VAT.
*   `valueAddedTax` (_number_, nullable) Value added tax amount for this order. Mandatory: If VAT is applicable, refer to taxSubTotal for taxes.
*   `taxableAmount` (_number_, nullable) Taxable amount.
*   `orderSubTotal` (_number_, required) Order total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `installationId` (_string_)
*   `shipmentList` (_array of ShipmentDetail_) List of shipments. Each shipment has shipping details for a BOFIS order. The shipping details consist of shipping address, shipping method, expected delivery date, and products corresponding to the shipment. **Note:** This field should be provided if the CMS property `Allow multiple shipments per cart/order` is enabled. This CMS setting can be found at: - **CMS** > **Store Management** > **Store Setting** > **Store fulfillment** > **Omni settings If this** flag is disabled, the shipping details should instead be provided in the following attributes: - `shippingMethodId` - `shippingCarrier` - `shippingCost` - `shippingAddress` - `deliveryDate` - `deliveryTimeSlot`.
*   `tenders` (_array of OrderPaymentDetail_, nullable) Representation of list of payments for this order. Required for BOPIS and BOFIS. Not applicable for ROPIS.
*   `customerProfile` (_CustomerProfile_)
*   `pickUpDetail` (_PickupDetail_)
*   `shippingAddress` (_Address_)
*   `shippingMethodId` (_string_, nullable) Shipping method ID. Refer to shipmentList for more details on when to provide shippingMethodId.
*   `shippingCarrier` (_string_) Shipping carrier code. Refer to shipmentList for more details on when to provide shippingCarrier.  
    Example: `UPS`.
*   `shippingCost` (_number_) Shipping cost. Refer to shipmentList for more details on when to provide shippingCost.
*   `deliveryDate` (_integer (int64)_) Delivery date in epoch.
*   `deliveryTimeSlot` (_string_) Expected delivery time slot. Refer to shipmentList for more details on when to provide deliveryTimeSlot.
*   `expectedShippingDate` (_integer (int64)_) Expected shipping date in epoch. Used for SLA calculation in BOFIS orders.
*   `lastPickupDate` (_string_) Last pickup date in ISO\_LOCAL\_DATE format (yyyy-MM-dd). Specifies the deadline for BOPIS order pickup, used for display purposes and automated cancellation logic.  
    Example: `2026-08-20`.
*   `productList` (_array of FulfillmentProduct_, required) List of products in the order.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### ExternalBopisCancellationRequest

Request to cancel BOPIS items.

*   `productList` (_array of CancelItem_, required) List of products to cancel.
*   `orderId` (_string_, required) Order ID.
*   `storeId` (_string_, required) Store ID.

### FulfillmentEvent

*   `orderId` (_string_, required) Order Id.
*   `orderType` (_string_, required) Order type. It can be either: 1. Store Fulfillment: order is fulfilled by a store. 2. Store Pickup: order is available for pickup at a store.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `productList` (_array of FulfillmentProduct_, required) Item list.
*   `status` (_string_, required) Store Fulfillment Status. 1. PACK: BOPIS, BOFIS, or ROPIS item is packed by store associate. 2. DELIVERED: BOPIS item is picked up by the customer or pickup person. 3. CANCELED: BOPIS or BOFIS item is canceled by store associate. 4. SHIPPED: BOFIS item is shipped by store associate. 5. READY: When importing a fulfillment order into POS, it must have a 'READY' status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`.
*   `storeId` (_string_, required) Store ID from where the item(s) are picked or fulfilled.
*   `deliveryGroupList` (_array of ShipmentDetail_, nullable) The shipping details of the items for store fulfillment order. Each delivery group has shipping address and corresponding shipping method. Each delivery item from productList is associated with its delivery group using productList\[\].deliveryGroupId. Note: It is available only if the CMS Property - 'Allow multiple shipments per cart/order' is enabled. This is a CMS setting and can be found in **CMS** > **Store Management** > **Store Setting** > **Store** fulfillment > Omni settings. If the property is disabled, refer to shipment.
*   `shipment` (_ShipmentDetail_)
*   `pickupDetail` (_PickupDetail_)
*   `note` (_string_) Note provided by associate during pack, pick, or shipment.

### ShipmentDetail

Shipping details applicable for store fulfillment order. If CMS flag 'Allow multiple shipments per cart/order' is enabled, the shipment will be populated. Refer to deliveryGroupList for more details on this CMS flag.

*   `shipmentId` (_string_, required) Shipment ID. Unique number.
*   `trackingNumber` (_string_, required) Shipment tracking number entered by store associate during fulfillment from the store.
*   `shippingMethodId` (_string_, required) Shipping method ID used during placing order. Mandatory.
*   `shippingName` (_string_) Shipping name. Optional.  
    Example: `Express shipping`.
*   `shippingDescription` (_string_) Shipping description. Optional.  
    Example: `Express shipping arrives in 2-3 business days`.
*   `shippingCarrier` (_string_, required) Shipping carrier code. Mandatory.  
    Example: `UPS`.
*   `shippingServiceLevel` (_string_) Shipping service level. Optional.  
    Example: `3 Business Days`.
*   `price` (_number_, required) Shipping Cost. Mandatory.
*   `deliveryDate` (_integer (int64)_) Delivery date in epoch.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.
*   `items` (_array of DeliveryItem_) List of items in this shipment. This can be a subset of the product list provided at the order level.
*   `shippingAddress` (_Address_, required)
*   `expectedShippingDate` (_integer (int64)_) Expected shipping date in epoch. Used for SLA calculation in BOFIS orders.

### OrderPaymentDetail

Deprecated. Use 'tenders' instead.

*   `transactionId` (_string_, required) The unique identifier for a transaction that completes the order. - This is particularly helpful in cases where a payment is made in multiple transactions, such as in the case of a deposit. - In POS, the transaction ID corresponds to the sale transaction when you place an order. - However, if you import an order from an external system, the transaction ID should correspond to the order in the external system and can be the same as the Order ID.  
    Maximum length: 128.
*   `paymentId` (_string_, required) The unique identifier for a payment/tender. As the order can have multiple payments, each payment will have a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method. Required for BOPIS and BOFIS. Not applicable for ROPIS.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. Possible values are: - `UNPROCESSED` is used internally by cloud services as a transient state. - `DISCARDED` is used when cash tender is part of a multi-tender payment and is deleted by swiping right. - `ABORTED` is used when we internally remove a tender from the tender list and add a new tender (e.g., for gift cards).  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device. If the payment is made in an external system, set the payment device to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards and gift cards through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender. Applicable for credit cards. for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal. Typically used for referenced refunds that are performed automatically by the POS without the customer presenting the card during a refund. In the case of Adyen payments, this field maps to `pspReference`. Required for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode, it generates a temporary payment ID, which is provided in the alternate payment request ID attribute. For example, the Adyen terminal generates a temporary ID called a "tender reference" whenever it goes into store and forward mode. This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund payment request ID issued by the payment gateway/terminal. Required for refund on credit cards.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item, and the original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried forward to the new order. This attribute provides the original order ID if the tender is carried over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item. The original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried over to the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and the tender is carried over to the new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Required for credit card payments using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment. For example, if a customer pays with cash first and the remaining amount with a credit card, the cash tender should have a paymentSequenceNumber of 1, and the credit card tender should have a paymentSequenceNumber of 2.
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number. Applicable when payment method is 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check' and 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.
*   `cardToken` (_string_) This field contains the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment** Gateways > Adyen > Payment Tokenization Events).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender. Normally, it is received after calling a call center agent of a payment processor. For example: call for authorization code after check denial or referral, or manual authorization code for a credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Required for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee. Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to finance approval/order/confirmation number in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### CustomerProfile

Profile for the customer.

*   `customerId` (_string_, required) Customer ID.
*   `email` (_string_, required) Customer Email ID.
*   `firstName` (_string_, required) Customer first name.
*   `lastName` (_string_, required) Customer last name.
*   `phoneMobile` (_string_, nullable) Customer's Phone#.

### PickupDetail

Pickup information for store pickup order.

*   `storeId` (_string_) Store Id.
*   `firstName` (_string_) First name of pickup person.
*   `lastName` (_string_) Last name of pickup person.
*   `email` (_string_, nullable) Email of pickup person.
*   `phone` (_string_, nullable) Phone of pickup person.
*   `pickupDate` (_integer (int64)_, nullable) Customer pickup date & time. Milliseconds since epoch.

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### FulfillmentProduct

Item list.

*   `productId` (_string_, required) Product Id.  
    Example: `N0345123`.
*   `orderItemId` (_string (The value should be numeric in string format)_, required) Item sequence/system generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `itemStatus` (_string_, required) Store fulfillment status. Possible values are: 1. **PACK**: The BOPIS, BOFIS, or ROPIS item is packed by a store associate. 2. **DELIVERED**: The BOPIS item is picked up by the customer or a designated pickup person. 3. **CANCELED**: The BOPIS or BOFIS item is canceled by a store associate. 4. **SHIPPED**: The BOFIS item is shipped by a store associate. 5. **READY**: When importing a fulfillment order into POS, it must have a **READY** status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`. Example: `PACK`.
*   `name` (_string_, required) Item name.  
    Example: `White Shirt`.
*   `quantity` (_integer (int32)_, required) Item quantity. This represents the original quantity. If the store setting `treatEachItemInCartAsSeparateLineItem` is enabled in CMS, then the quantity should be 1 per line item. This setting can be found in: **CMS** > **Store Management** > **Store Settings** > **OMS** > **Advanced**.  
    Example: `1`.
*   `price` (_number_, required) Item price.  
    Example: `12.05`.
*   `total` (_number_, required) Item total after discount and taxes.  
    Example: `14`.
*   `adjustedQuantity` (_integer (int32)_, required, read-only) Packed quantity for a PACK event, picked-up quantity for a DELIVERED event, and shipped quantity for a SHIPPED event.

### CancelItem

Item to be canceled in an order.

*   `productId` (_string_, required) Product ID.  
    Example: `PROD-123`.
*   `orderItemId` (_string_, required) Order Item ID.  
    Example: `1`.
*   `quantity` (_integer (int32)_, required) Quantity to cancel.  
    Example: `2`.
*   `reasons` (_array of Reason_) List of reasons for cancellation.

### DeliveryItem

List of items in this shipment. This can be a subset of the product list provided at the order level.

*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Number of items.
*   `orderItemId` (_string_) Item sequence/system generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

<!-- document id=c092ef0ebeadc683e088082818a0200b698a4ee92fd280a7d7705bf359c4f953 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/general-guidance.md -->

# General Guidance

This section contains guidance for functionality that applies across multiple B2C Commerce APIs (SCAPI). Use it as a starting point to find the cross-cutting topics most relevant to your implementation.

## Authentication & Authorization

- [Authorization Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization.md) — How SCAPI client permissions work.
- [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md) — Set up SLAS clients for storefront access.
- [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md) — Set up Account Manager clients for backend access.
- [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/auth-z-scope-catalog.md) — Complete list of available scopes.
- [SLAS Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md) — Grant types, token types, and advanced SLAS topics.

## Extensibility

- [Customization with Hooks](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/extensibility_via_hooks.md) — Alter and extend Shopper API behavior using the Script API.
- [Hook Method Details](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hook-method-details.md) — Available hooks with method signatures.
- [Custom APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-apis.md) — Build custom REST endpoints under the SCAPI framework.

## Caching & Performance

- [SCAPI Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md) — Which APIs are cached, TTLs, and personalization settings.
- [Shopper API Performance and Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/performance.md) — Optimize response times for hooks, Custom APIs, and catalog size.

## Personalization

- [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md) — Set context information to retrieve personalized promotions, payment methods, and shipping methods.
- [Shopper Context Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-best-practices.md) — Guidelines for using Shopper Context effectively.

## Error Handling & Troubleshooting

- [HTTP Status Codes and Errors](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/error-response-codes.md) — Common error messages, error response format, and best practices.
- [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.md) — Default timeout values and request/response size constraints.
- [Load Shedding and Rate Limiting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/throttle-rates.md) — Rate limits per API family.
- [Troubleshoot Request Timeouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeout-troubleshoot.md) — Diagnose and resolve timeout issues.
- [View SCAPI Logs and Track Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md) — Use correlation IDs and Log Center.

## Working with Baskets & Orders

- [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/work-with-baskets-orders.md) — End-to-end checkout flow with code examples.
- [Hybrid Storefront Best Practices for Working with Baskets](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-storefront-baskets.md) — Best practices for hybrid SFRA/headless deployments.
- [Coupons, Gift Certificates, and Bonus Products](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/coupons-giftcerts-bonus-products.md) — Promotional features in basket flows.

## Request Formatting

- [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md) — How to construct well-formed API requests.
- [Property Selection](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-property-selection.md) — Select specific attributes of the response to return.
- [URL Encoding of Special Characters](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/url-encode.md) — Double-encode special characters in resource identifiers.
- [Custom Properties](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-properties.md) — Read and write custom `c_` properties on business objects.

## Security & CORS

- [Security](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/security.md) — Authentication, authorization, and the shared responsibility model.
- [CORS in SCAPI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-cors.md) — Configure cross-origin resource sharing for browser-based access.

<!-- document id=06a2b27a9d6e1af6546c8da904dcdde6352268671def20140d5fddb3b54d7acf url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/get-order-spi-reference.md -->

# Get Order SPI Reference

The table below provides sample JSON schemas for specific use cases when using the Point of Sale [Get Order SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

| **Use Case**                                                                                                                             | **Refer to Attribute**                                                                                                                                                                                                           | **Notes**                                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Sale**                                                                                                                                 |                                                                                                                                                                                                                                  |                                                                                             |
| [Single-item sale](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_singleItemSale.json)                     | orderProductList                                                                                                                                                                                                                 |                                                                                             |
| [Multi-item sale](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_multiItemSale.json)                       | orderProductList                                                                                                                                                                                                                 |                                                                                             |
| [Sale with customer](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_saleWithCustomer.json)                 | customerProfile<br>email<br>phoneNumber<br>billingAddress                                                                                                                                                                        |                                                                                             |
| [Item-level discount](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_itemLevelDiscount.json)               | priceOverrideReason<br>priceOverrideReasonCode<br>orderProductList.priceAdjustments<br>orderProductList.discount<br>orderProductList.promotionTitle<br>orderProductList.reasons<br>productPriceAdjustments<br>reasons            | • To calculate item-level discounts, use orderProductList.price - orderProductList.discount |
| [Transaction-level discount](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_transactionLevelDiscount.json) | orderProductList.priceAdjustments<br>orderProductList.discount<br>orderProductList.promotionTitle<br>orderProductList.reasons<br>productPriceAdjustments<br>reasons<br>transactionDiscountAmount<br>transactionDiscountReason    |                                                                                             |
| [Promotion](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_promotion.json)                                 | orderProductList.priceAdjustments<br>orderProductList.discount<br>orderProductList.promotionTitle<br>orderProductList.reasons<br>productPriceAdjustments                                                                         |                                                                                             |
| [Single-Use Promotion Code (SUPC)](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_SUPC.json)               | priceOverrideReason<br>priceOverrideReasonCode<br>orderProductList.priceAdjustments<br>orderProductList.discount<br>orderProductList.promotionTitle<br>orderProductList.reasons<br>productPriceAdjustments<br>reasons<br>coupons |                                                                                             |
| [Tax exemption](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_taxExempt.json)                             | taxExemptions<br>orderProductList.taxExemption<br>orderProductList.productTax.taxExemption                                                                                                                                       |                                                                                             |
| [Item-level note](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_itemLevelDiscount.json)                   | orderProductList.notesList                                                                                                                                                                                                       |                                                                                             |
| [Order-level note](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_notes.json)                              | notesList                                                                                                                                                                                                                        |                                                                                             |
| [Split sales attribution](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_splitTender.json)                 | orderProductList.salesAssociateAttribution                                                                                                                                                                                       |                                                                                             |
| **Sale / Omni**                                                                                                                          |                                                                                                                                                                                                                                  |                                                                                             |
| [Charge & send / Endless aisle](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_endlessAisle.json)          | shippingAddress<br>orderProductList.omniFulfillmentType                                                                                                                                                                          | • omniFulfillmentType = SHIP_TO_HOME                                                        |
| [Ship from store / Ship from another store](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_shipFromStore.json) | fulfillmentType<br>fulfillmentsubtype<br>shippingAddress<br>orderProductList.fulfillmentLocation<br>orderProductList.omniFulfillmentLocationType<br>orderProductList.omniFulfillmentType                                         | • omniFulfillmentLocationType: Regular<br>• omniFulfillmentType: SHIP_TO_HOME_CURRENT_STORE |
| **Tenders**                                                                                                                              |                                                                                                                                                                                                                                  |                                                                                             |
| [Cash payment](https://support.predictspring.com/hc/article_attachments/29585192623379)                                                  | tenders.paymentMethod<br>tenders.cardType                                                                                                                                                                                        |                                                                                             |
| [Credit card payment](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_creditCardPayment.json)               | requestId<br>paymentDetails.alternateRequestId<br>paymentDetails.authorizationDate<br>paymentDetails.cardExpirationMonth<br>paymentDetails.cardExpirationYear<br>paymentDetails.cardNumber<br>paymentDetails.fundingSource       | • fundingSource = CREDIT                                                                    |
| [Debit card payment](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_debitCardPayment.json)                 | requestId<br>tenders.alternateRequestId<br>tenders.authorizationDate<br>tenders.cardExpirationMonth<br>tenders.cardExpirationYear<br>tenders.cardNumber<br>tenders.fundingSource                                                 | • fundingSource = DEBIT                                                                     |
| [Gift card payment](https://support.predictspring.com/hc/article_attachments/29585208262675)                                             | requestId<br>tenders.alternateRequestId<br>tenders.authorizationDate<br>tenders.cardExpirationMonth<br>tenders.cardExpirationYear<br>tenders.cardNumber<br>tenders.fundingSource                                                 |                                                                                             |
| [Miscellaneous payment](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_misc.json)                          | tenders.accountNumber<br>tenders.externalPaymentReferenceId<br>tenders.requestId                                                                                                                                                 |                                                                                             |
| [Split payment](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_splitTender.json)                           | requestId<br>tenders.alternateRequestId<br>tenders.authorizationDate<br>tenders.cardExpirationMonth<br>tenders.cardExpirationYear<br>tenders.cardNumber<br>tenders.fundingSource                                                 | • paymentDetails will show two payment objects if paid with two tenders                     |
| [In-store pay by link](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_instorePaybylink.json)               | requestId<br>tenders.alternateRequestId<br>tenders.authorizationDate<br>tenders.cardExpirationMonth<br>tenders.cardExpirationYear<br>tenders.cardNumber<br>tenders.fundingSource<br>tenders.paymentSource                        | • paymentMethod = Paybylink<br>• paymentSource = Paybylink                                  |
| [Remote pay by link](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/GetOrderSPI_remotePaybylink.json)                  | requestId<br>tenders.alternateRequestId<br>tenders.authorizationDate<br>tenders.cardExpirationMonth<br>tenders.cardExpirationYear<br>tenders.cardNumber<br>tenders.fundingSource<br>tenders.paymentSource                        | • paymentMethod = RemotePaybylink<br>• paymentSource = RemotePaybylink                      |

<!-- ## Unreferenced attachments:

- title=Get Order SPI Reference, img=single_item_sale_json, inline=False
- title=Get Order SPI Reference, img=promotion_json, inline=False
- title=Get Order SPI Reference, img=multi_item_sale_json, inline=False
- title=Get Order SPI Reference, img=attribution_json, inline=False
- title=Get Order SPI Reference, img=item_level_discount_json, inline=False
- title=Get Order SPI Reference, img=supc_json, inline=False
- title=Get Order SPI Reference, img=sale_with_customer_json, inline=False
- title=Get Order SPI Reference, img=transaction_level_discount_json, inline=False
- title=Get Order SPI Reference, img=notes_json, inline=False
- title=Get Order SPI Reference, img=tax_exempt_json, inline=False
- title=Get Order SPI Reference, img=ship_from_store_json, inline=False
- title=Get Order SPI Reference, img=debit_card_payment_json, inline=False
- title=Get Order SPI Reference, img=credit_card_payment_json, inline=False
- title=Get Order SPI Reference, img=remote_paybylink_json, inline=False
- title=Get Order SPI Reference, img=instore_paybylink_json, inline=False
- title=Get Order SPI Reference, img=endless_aisle_json, inline=False
- title=Get Order SPI Reference, img=split_tender_json, inline=False
- title=Get Order SPI Reference, img=misc_json, inline=False -->

<!-- document id=5161a71022bef5a68b1845667ca711ec5eb5fa6104e108e55885cd99538713bf url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/get-set-up.md -->

# Get Set Up

Understand the recommended prerequisites before building a B2C Commerce site. This section contains these guides.

- [Get B2C Commerce User Access](https://help.salesforce.com/s/articleView?id=000391212&type=1).
- Create [On-Demand Sandboxes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sandboxes/b2c-developer-sandboxes.md) to access flexible and scalable environments for site development and testing.
- [Enable and Configure Einstein Activities](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-activities-overview.html) to support metrics reporting.

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=5272e459c2d77ee5686a25be8907d266bb1f693f2dc8102e9e4360a03effbe99 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-get-set-up.md -->

# Get Set Up

Ready to dive into developing your site? Start here with these comprehensive setup guides.

- [Create an On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/creating-an-on-demand-sandbox.md)
- [Multiple Sites](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/multiple-sites.md)
- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md)
- [Set up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md)
- [Set up Your Local Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-your-local-environment.md)
- [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md)

### See Also

- Salesforce Commerce API (SCAPI) Tutorial: [Develop With Your On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-develop-with-on-demand-sandbox.html)

<!-- document id=af41c285c65296f092348f1995dd74949cdfab2429dd9d4f6b431b4600f813e3 url=/developer/current/en-us/commerce-cloud/lwr-migration/guides/get-started.md -->

# Get Started

B2B stores on Lightning Web Runtime (LWR) deliver blazing-fast digital experiences to your customers and bring you the power and flexibility of the lightweight and composable Lightning Web Components (LWC) programming model. For more information, see [Lightning Web Runtime](https://developer.salesforce.com/docs/platform/lwr/overview).

If your B2B storefront uses the Aura Components programming model, switch to the B2B Commerce (LWR) template. Don’t worry about recreating a store from scratch. Your investment in Aura makes migration as simple as refactoring and replacing certain UI components. To get started, see [Key Differences](https://developer.salesforce.com/docs/commerce/lwr-migration/guide/key-differences.htm).

When you create a store, select either a B2B or a B2C store template built on the LWR (Lightning Web Runtime) platform. If your org was enabled for Commerce before Spring ’23, you can also select a B2B store template built on the Aura platform. We recommend that you select the B2B LWR template for new stores and consider migrating existing B2B stores based on Aura to LWR.

<!-- document id=dd02df6a308df8a2704106b32fa2bd4a21b9b86ae0549a6b7eb3c12483e98753 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/get-started.md -->

# Get Started

Set up authentication and API access for Point of Sale development.

## In this section

- [Point of Sale API Developer Guide (Non-Hyperforce)](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-developer-guide.html)
- [External API Access Guide for Hyperforce Users](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/external-api-access-guide-for-hyperforce-users.html)
- [Setting Up OAuth with Point of Sale APIs](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/setting-up-oauth-with-retail-cloud-apis.html)

<!-- document id=07083d59dca5e149ace01dc5ea8b10e813a96a138dd6dbbc5811766b16cf7632 url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-build-storefront-next-project.md -->

# Get Started with Agentforce Commerce Vibes

Build and administer a Storefront Next project with Agentforce Commerce Vibes. The B2C workflows require that you install the extension and connect to a Salesforce org.

## Build a Storefront

1. Install the Commerce Vibes extension and log in to your Salesforce org as described in [Install and Launch the Commerce Vibes Extension](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-install-extension.md).
2. If you haven't done so, launch the extension by clicking the ![Commerce Vibes icon](https://developer.salesforce.com/docs/media/commerce-vibes/cv-com-vibes-icon.png '{"class": "image-icon-sm"}') in the Activity Bar.
   A Welcome page appears.

   **tip:** When you open a folder that doesn't contain a storefront project, the Welcome page is displayed. When you open a chat panel in Commerce Vibes, the chat displays project-aware example prompts: prompts to get started or prompts that apply to your storefront type after creating a storefront project.

3. To create a sample project for Storefront Next, click the Storefront Next tile in the Welcome page.
4. Choose to create a new project, and provide the storefront name in the chat.

   The output of the executed commands is displayed in the Terminal tab.

   **tip:** As the agent executes tasks, it asks you to approve some tasks. You can configure when the agent asks for approval to run actions in Settings. See [Agentforce Commerce Vibes Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-settings.md).

5. Answer questions about the vertical template and B2C Commerce settings in the Terminal. Provide the configuration information of your sandbox instance or accept the defaults to use the B2C demo sandbox instance.

   Salesforce provides the B2C sandbox demo instance to use for samples but you don't have administration privileges to manage this instance.
   After the storefront is created, VS Code opens the project folder in a new window.

6. Go to Commerce Vibes by clicking the ![Commerce Vibes icon](https://developer.salesforce.com/docs/media/commerce-vibes/cv-com-vibes-icon.png '{"class": "image-icon-sm"}') in the Activity Bar.
7. Optionally, write more prompts to customize the storefront.
8. To understand the contents of the project that was created, write this prompt: `Explain Storefront Next project structure.`
9. To build and run the storefront locally, type this prompt: `View my storefront.`

## Administer Your B2C Commerce Instance

Commerce Vibes runs agent skills from the [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md) that perform administration tasks in your B2C Commerce instance. Here's an example prompt for running a job on a sandbox instance.

- `Run the search indexing job on my sandbox specified in the dw.json file.`

  **note:** Configure credentials with permission to run the job on the selected instance. You can use a project `dw.json` file, global configuration, or environment variables. See [Optional: Configure B2C Commerce Credentials](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-install-extension.md#optional-configure-b2c-commerce-credentials).

## Search the B2C Documentation

The toolkit provides search across official B2C Commerce developer, administrator, and merchant documentation. Ask your assistant to find relevant guidance and explain how it applies to your task. Here are some example prompts.

- `Search the docs about data fetching in Storefront Next.`
- `Search the docs about the headless architecture in Page Designer.`

## Browse the B2C Toolkit

Familiarize yourself with the MCP server tools and agent skills from the [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md) available in Commerce Vibes.

1. In VS Code, in the Agentforce Commerce Vibes panel, click the **B2C Toolkit** tab.
2. Click **MCP Servers > B2C Commerce DX** to browse the MCP tools available for B2C development.
3. Click **Skills** and check out the agent skills available for B2C development.
4. Click **Rules** and check out the deterministic rules.

![Browse the toolkit](https://developer.salesforce.com/docs/media/commerce-vibes/cv-toolkit.png '{"class": "image-xl"}')

**note:** To complement the built-in toolkit and provide more development assistance, add other MCP servers, skills, and rules. For example, reference an MCP server that assists with React development, or add a rule for team development instructions to follow. Rules are saved in `.afv/` folder in your project.

## See Also

- [Chat with Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-chat-interface.md)
- [Commerce Cloud Developer Center](https://developer.salesforce.com/developer-centers/commerce-cloud)

<!-- document id=52e23be536034cce792ba6500055de37e2ef581e2ee33556690364a1e932a62b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-dev-guide.md -->

# Get Started with B2B Commerce

If you're considering developing a sophisticated business-to-business sales platform or a direct-to-consumer online store for your organization, leverage Salesforce's B2B Commerce APIs alongside Lightning Experience capabilities to build robust and scalable e-commerce solutions.

Start by designing your platform to meet your organization's unique business requirements. Integrate seamlessly with critical third-party applications to enhance functionality and extend capabilities as needed.

Use the Commerce Experience Builder template as the foundational tool for creating personalized commerce environments. Customize this powerful tool to serve retailers, wholesalers, distributors, and consumers, ensuring seamless purchasing experiences across every channel.

Here are some key topics covered to help you, as a developer, learn the Salesforce Commerce APIs and access the developer resources essential for successfully building a complex B2B sales platform or a direct-to-consumer online store:

1. Data Models:

- Understand the essential data models for commerce applications, which include cart, checkout, product and catalog, product attributes, pricing and promotions, inventory, store, and order processing. Better understanding of these models ensures efficient operations and a seamless user experience in your e-commerce solutions. See [B2B Commerce Data Model](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-dev-data-model.md).

2. Commerce APIs:

- The B2B Commerce Developer Guide details how to use the Connect Commerce API for managing various e-commerce functions within Salesforce. This API helps integrate and manage web store operations like product catalogs, inventory, customer carts, and order processing. It enables developers to build seamless and robust e-commerce solutions for both B2B settings. See [B2B Commerce APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-storefront-apis-parent.md).

1. Customization and Extension:

- Learn how to customize and extend your e-commerce solutions using Salesforce's tools and frameworks. This section focuses on enhancing functionality, integrating with services, and tailoring the shopping experience to meet specific business needs.
- B2B Commerce supports extensive customization and integration. Learn various approaches to extend the commerce capabilities of Salesforce, including using APIs to connect with external applications like ERP systems and payment gateways. See [B2B Commerce Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/d2c-comm-extensions-intro.md).

1. Integrations:

- Explore integration points for B2B Commerce, especially within the cart and checkout experience. Integration services work seamlessly across both B2B stores.
- Predefined flows simplify package integration for tax, shipping, and payment providers for B2B stores created with an LWR template. Understand how integration platforms and various components interact for a B2B store created with the Aura template. See [B2B Commerce Integrations](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-integration-architecture.md).

1. Payment Processing Setup:

- Learn how to set up a payment gateway and connect it to your checkout process. The guide covers both server-side and client-side payment processing implementations. Last steps in implementing payment processing include connecting the payment gateway to checkout in your store. See [Set Up Payment processing](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-payment-b2b-setup.md).

6. Building Custom Components Using LWC and LWR:

- Lightning Web Components (LWC) and Lightning Web Runtime (LWR) are innovative technologies from Salesforce that allow for highly customizable and efficient front-end experiences. This guide will walk you through using these technologies to build customized storefronts that are both engaging and fast.
- Learn how to add custom components to your B2B store using an LWR template. Salesforce recommends using the Salesforce Developer Experience (SFDX) environment for building Lightning web components (LWC). See [Build Custom Components](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-custom-component.md).

<!-- document id=c01a5602e6eb026ad07cfee91ed32952da1e9c0227256e7539f197b5c3bfea0d url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-get-started.md -->

# Get Started with B2B Commerce Checkout

The B2B checkout process transitions a shopper's cart into a permanent order through a state-driven workflow powered by B2B Commerce APIs. This guide shows you how to implement checkout flows using asynchronous background calculations for pricing, promotions, taxes, shipping, and inventory.

Use this guide when you're:

- Building custom checkout experiences
- Integrating with Commerce APIs
- Understanding calculator orchestration
- Managing checkout currency conflicts
- Troubleshooting checkout issues

<!-- document id=f4b546fafdbc2a9975d2739c6795955e6f173237429326f178ab4447e3bb7954 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/developer-workflow.md -->

# Get Started with B2C Commerce

This high-level developer workflow outlines how to efficiently create a performant site on the B2C Commerce Platform. In this guide, we mainly summarize broad tasks that apply regardless of which parts of B2C Commerce you're using. This guide is meant to supplement the detailed documentation about products available within B2C Commerce such as Storefront Reference Architecture (SFRA), Composable Storefront, or B2C Commerce API.

**tip:** To get detailed answers to your questions about B2C developer and merchandiser/admin features, go to [help.salesforce.com](https://help.salesforce.com). Log in with your Trailblazer account and use Agentforce, our generative AI-powered documentation search tool.

**note:** Unless otherwise stated, all of the tasks in this guide apply to sites that are built using Composable Storefront, SFRA, other parts of B2C Commerce, or a combination of the three.

## 1. Discover

Get an introduction to B2C Commerce.

- B2C Commerce Demo

  Watch this video to get a brief introduction to B2C Commerce.

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/LpfKECErPJzbZoSoynX8vD" title="Salesforce B2C Commerce Demo" type="vidyard"}

- [B2C Commerce Storefront Options](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/which-product.md): Understand the available site implementations such as Composable Storefront or SFRA.
- Use the [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start-landing-page.md) to try out some basic steps for using a few of the B2C storefront options.
- Get an [Overview of B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/understand-b2c.md) architecture and key concepts.

## 2. Get Training

- Sign up for [instructor-led B2C Commerce classes](https://trailheadacademy.salesforce.com/all-classes#f-products=Commerce).

## 3. Get Set Up

Understand the recommended prerequisites before building a B2C Commerce site.

- [Use the Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md) to guide you through auth and instance setup, verify connectivity, and get you ready for hands‑on development without hunting through UIs.
- [Get B2C Commerce User Access](https://help.salesforce.com/s/articleView?id=000391212&type=1).
- Create [On-Demand Sandboxes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sandboxes/b2c-developer-sandboxes.md) to access flexible and scalable environments for site development and testing.
- [Enable and Configure Einstein Activities](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-activities-overview.html) to support metrics reporting.

## 4. Build Your Site

Get your B2C Commerce site up and running quickly with this recommended process. Here are some key steps.

- [Code Repositories](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-github-repo-access.md): Access our open source repositories and code shared by B2C Commerce customers and partners.
- [Use the Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md) to automate everyday tasks, including creating SLAS clients, pushing/activating code versions, and managing On‑Demand Sandboxes.
- [Merchandising Your Site in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_merchandising_your_site.htm&type=5): Learn about adding data such as product and marketing information.
- Use [Page Designer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer/b2c-dev-for-page-designer.md) to manage templates that your merchant team can use to create site pages.
- SFRA only: Integrate with [Salesforce Payments](https://help.salesforce.com/s/articleView?id=cc.b2c_salesforce_payments.htm&type=5) to collect payments.
- Watch this video to learn how [Commerce Einstein](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_cloud_einstein.htm&type=5) can power up your ecommerce with AI.

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/xxMS9jvwKnpwrzudvfKyQ2" title="Commerce Einstein Demo" type="vidyard"}

- [Troubleshoot](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ops-troubleshooting/b2c-troubleshooting.md) your site.

[Learn more about building your site.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/build-your-site.md)

### Resources

- Access documentation about [B2C Commerce Storefront Options](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/which-product.md) such as [Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide), [SFRA](https://developer.salesforce.com/docs/commerce/sfra/guide), or a [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.html).
- [Use APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/api-doc.md) such as B2C Commerce API or B2C Commerce Developer Resources (Script API) to customize your storefront or build your own custom storefront.
- Connect your assistant to the [B2C MCP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-developer-tooling.md#connect-your-ai-assistant) to search official documentation, debug live cartridge code, investigate logs, and work with SCAPI Admin APIs. Included skills also support administrators investigating incidents and failed orders.

## 5. Customize and Extend

Learn about B2C Commerce's opportunities for customization and extension to meet your unique business needs. Here are examples of customization options.

- Run [Campaigns and Promotions in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_campaigns_and_promotions.htm&type=5).
- SFRA only: [Customize Promotions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/promotions/b2c-promotions-for-developers.md).
- [Customize Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/active-merchandising/b2c-active-data-for-developers.md) to tailor your site's active merchandising. processing. See [Active Merchandising](https://help.salesforce.com/s/articleView?id=cc.b2c_active_merchandising.htm&type=5).

[Learn more about customizing and extending B2C Commerce.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-custom.md)

## 6. Follow Best Practices

Protect your shoppers' data and enhance their shopping experience with these best practices for site performance, security, privacy, and more.

- [Site Performance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-performance/b2c-site-performance.md)
- [B2C Commerce Security Guide](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_security_guide.htm&type=5)
- [Data Protection and Privacy](https://help.salesforce.com/s/articleView?id=cc.b2c_data_protection_and_privacy.htm&language=en_US&type=5)

[Learn more best practices.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/best-practices.md)

## 7. Test and Launch

Discover the keys to a smooth site launch and make sure shoppers have a positive experience from Day 1. Test and launch your site by taking key actions such as:

- Create [Custom Storefront Error Pages](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-custom-error-pages.md).
- [Open a Go Live Ticket](https://help.salesforce.com/s/articleView?id=000391578&type=1).

[Learn more about testing and launching your site.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/test-launch.md)

## 8. Monitor and Maintain

Learn how to effectively monitor key metrics and perform essential maintenance tasks to keep your site running smoothly after launch. Monitor and maintain your site with key resources such as:

- [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&language=en_US&type=5): Review site errors and metrics.
- [Control Center](https://help.salesforce.com/s/articleView?id=cc.b2c_cc.htm&language=en_US&type=5): Monitor the state of your B2C Commerce instances.

[Learn more about monitoring and maintaining your site.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/monitor-maintain.md)

## 9. Track Analytics

Make data-driven decisions with analytics tools.

- [Analytics Reporting Integration](https://help.salesforce.com/s/articleView?id=cc.b2c_analytics_reporting_integration.htm&type=5)
- [Reports & Dashboards](https://help.salesforce.com/s/articleView?id=cc.b2c_reports_and_dashboards.htm&type=5)

## Learn More

- Ask the B2C Commerce Developer [Community](https://developer.salesforce.com/docs/commerce/commerce-api/guides/community.md).
- _Trailhead_: [B2C Commerce - Developers and Architects](https://trailhead.salesforce.com/users/rcompiani/trailmixes/b-2-c-commerce-developers-it)
- [Blogs](https://developer.salesforce.com/blogs)
- [Podcasts](https://developer.salesforce.com/podcast)
- [Webinars](https://www.salesforce.com/events/webinars)
- [Events](https://www.salesforce.com/events)

## See Also

- <a href="https://developer.salesforce.com/developer-centers/commerce-cloud" target="_blank">Agentforce Commerce Developer Center</a>
- [B2C Commerce Release Notes](https://help.salesforce.com/s/articleView?id=commerce.b2c_parent.htm&type=5): Learn about new features in B2C Commerce, B2C Commerce API, Composable Storefront, SFRA, and more.
- For summaries of new Commerce features in each Salesforce release, check out the release highlights in [Prepare for Salesforce Releases](https://trailhead.salesforce.com/content/learn/trails/sf_release_prep).
- Speed up your time to launch with <a href="https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/solutions-landing-overview.html" target="_blank">B2C Commerce Solutions</a>, which are tools and accelerators for various industries.
- Use <a href="https://developer.salesforce.com/docs/commerce/marketplace/guide/get-started.html" target="_blank">Commerce Marketplace</a> to manage third-party sellers by using a Lightning app.
- Additional _Salesforce Help_:
  - [Get Started with B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_getting_started.htm&type=5)
  - [Administering Your Organization](https://help.salesforce.com/s/articleView?id=cc.b2c_administering_your_organization.htm&type=5)
  - Use [Account Manager for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_overview.htm&type=5) to create and maintain Commerce Cloud accounts.

<!-- document id=bd18004d3dac201fc7a9d869eb79d7784e07d2c5b0934e558e8ee73a99748843 url=/developer/current/en-us/commerce-cloud/einstein/guides/commerce-einstein-api.md -->

# Get Started with B2C Commerce Einstein API

Use B2C Commerce Einstein API to send shopper profiles to the Einstein engine. Send a single shopper's profile or send shopper profiles in bulk. A shopper profile includes the shopper's preferences.

Use B2C Commerce Einstein API to get recommendations from the Einstein engine. To help Einstein build recommendations, use the API to tell the Einstein engine when a shopper:

- views a product
- views a recommendation
- clicks a recommendation
- adds a product to their cart

To get started, configure the API to use profile data. See
[Set Up Einstein Profile Connector](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-profile-connector/einstein-profile-connector-overview.md).

<!-- document id=2eed0a9870b51a9dd0920ba821bf20ab800f45ed56553b0587864830bbb3b44f url=/developer/current/en-us/commerce-cloud/solutions/guides/solutions-landing-overview.md -->

# Get Started with B2C Commerce Solutions

B2C Commerce Solutions are designed with you and your business in mind. Using common real-world use cases, commerce-driven APIs, and third-party integrations, solutions accelerate time to launch and are powered by Salesforce C360.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Industry Solutions

Companies across all industries are looking to digital platforms as the cornerstone for leading a digital transformation across the entire 360-degree customer journey. Savvy developers see the potential in building a commerce strategy on a flexible platform with proven AI-powered commerce services, that can extend to any touchpoint, integrate across data and systems, and provide trusted availability.

To guide learning and accelerate time-to-market for building industry solutions on the Salesforce Commerce Platform, developers have access to guides that combine business value, platform features, proven best practices, resources, and more.

Each guide shows opportunities for extending the Commerce Platform for industry use cases, along with features, and how to get started. There are also toolkits for certain industries. These toolkits provide developer blueprints, with code, sample apps, and tooling on how to bring together Salesforce Industry and Customer 360 solutions for an integrated solution.

## Technical Solutions

Developers and architects of all skill levels can build well-performing solutions on our B2C Enterprise solution. Read our technical guides to learn how to efficiently build scalable solutions that perform all year long through any sales season.

Before you start exploring and building on B2C Commerce, you must be familiar with the powerful features and development tools of the Salesforce Commerce API, Storefront Applications, and Page Designer.

[Self-Service Order Management for SFRA](https://github.com/SalesforceCommerceCloud/plugin_ordermanagement) (Access granted via GitHub).

## Retail Solutions

With Salesforce B2C Solution Kits, explore the power of multi-cloud solutions to create customer experiences that connect with customers, grow your business, and provide resilience to market changes. These kits show you how to implement Salesforce recommended cross-cloud solutions to common retail use cases.

Get product recommendations, workflow details, and instructions to help you implement the solution from start to finish. Each use case overview gives you a real-world example of the problematic situation that each solution kit solves. And for developers, we include the information needed to deploy the functionality so that you can deliver a perfectly personalized experience to your ecommerce shoppers.

<!-- document id=5bf5e0b9939cfac43d058de54c51330f479fd312608aa38b342d98948e748a0a url=/developer/current/en-us/commerce-cloud/marketplace/guides/get-started.md -->

# Get Started with Commerce Marketplace

Use Commerce Marketplace to manage third-party sellers using a Lightning app.

To learn more, including a detailed guide for marketplace operators, go to [Salesforce Help](https://help.salesforce.com/s/articleView?id=commerce.commerce_marketplace.htm&type=5).

**note:** These guides and API reference are for developers building integrations for Commerce Marketplace.

## Marketplace Integration Toolkit

The Marketplace Integration Toolkit is a reference application. Use it to sync data between B2C Commerce and Commerce Marketplace. To start the setup process, see the [Initial Setup](https://developer.salesforce.com/docs/commerce/marketplace/guide/marketplace-initial-setup.md) guide.

## B2C Commerce Cartridges

We offer a series of cartridges to help developers build their integrations. Each one is responsible for a new service or component that can be added to the storefront. These cartridges can be added to any storefront based on the Storefront Reference Architecture (SFRA).

Available cartridges:

- **Plugin** (`plugin_marketplace_storefront`)
  Customizes the front end. Controls all interactive and visual features, including controllers, templates, and more. Doesn’t process back-end functions.
- **Int** (`int_marketplace`)
  A required cartridge used mostly in the backend for creating requests to the middleware.
- **Buybox** (`plugin_marketplace_buybox`)
  Shows different seller offers in a Product Display Page.
- **Checkout** (`plugin_marketplace_checkout`)
  Splits the cart and the order per seller and allows customers to finish their order. Customers can insert their address, select the better shipping method per seller, review all products added to the cart grouped by sellers and also insert the payment information.
- **BASE** (`int_marketplace_service`)
  An internal cartridge that works as an integration accelerator. The `int_marketplace` cartridge requires the `int_marketplace_service` cartridge.

## Marketplace Seller Integration API

For third-party sellers, we offer a REST API to build custom tooling for managing your items within Commerce Marketplace. For more information, see the [API Reference](https://developer.salesforce.com/docs/commerce/marketplace/references).

## About the Atonit Brand

While using Commerce Marketplace, you’ll see occasional references to Atonit, which was the name of the company that originally developed these technologies. Atonit was acquired by Salesforce in 2022, and we’re still in the process of rebranding.

<!-- document id=7ba9786d55ab7778a714fd8cdcc29b6211f2f44f5a1823127f3ec2876c24a749 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-developer-workflow.md -->

# Get Started with Composable Storefront

Follow this recommended developer workflow to efficiently create a performant business-to-consumer (B2C) Commerce site with Composable Storefront. Optional tasks are also identified.

**note:** Unless otherwise stated, all of these tasks apply to sites that are either built 100% on Composable Storefront or [hybrid storefronts](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html).

## 1. Discover

Get a short orientation then build and deploy a demo site. Understand the benefits of Composable Storefront.

- [Check out the Demo Site](https://pwa-kit.mobify-storefront.com)
- [Composable Storefront Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.md)
- [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.md)
- [Deploy Your Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.md)
- [Introduction to Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/intro.md)
- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.md)
- [Performance Guide for Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-guide.md)

**tip:** To optimize site performance, factor in recommended practices and rate limits when you make API calls. See the [Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.md#considerations) for using the Managed Runtime API.

## 2. Use a Hybrid Implementation

Is part of your site on Storefront Reference Architecture (SFRA) or SiteGenesis? Check these guides for additional tasks that apply to only hybrid implementations (also called phased headless rollouts).

- [Hybrid Implementation Guidance](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html)
- [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-authentication.html)
- [Content Delivery Network (CDN) APIs for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html)
- [Einstein Activities for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/einstein-activities-for-phased-headless-rollouts.html)

## 3. Learn More

Understand the architecture of Composable Storefront. Get support during your development journey.

- [Progressive Web App (PWA) Kit Framework](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-framework.md)
- [Skills for Success](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/skills-for-success.md)
- [Ask the B2C Developer Community](https://developer.salesforce.com/docs/commerce/commerce-api/guides/community.md)
- [Sign up for Instructor-Led Training](https://trailheadacademy.salesforce.com/classes/b2c201-develop-a-b2c-composable-storefront)

## 4. Get Set Up

Ready to dive into developing your site? Start here with these comprehensive setup guides.

- [Decide which CDN to Use](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/decide-on-cdn.md)
- [Create an On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/creating-an-on-demand-sandbox.md)
- [Create a Storefront Using an On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-storefront-using-sandbox.md)
- [Multiple Sites](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/multiple-sites.md)
- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md)
- [Set up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md)
- [Set up Your Local Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-your-local-environment.md)
- [Use a Shopper Login and API Access (SLAS) Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md)

**Optional:**

- Salesforce Commerce API (SCAPI) Tutorial: [Develop With Your On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-develop-with-on-demand-sandbox.html)

## 5. Build Your Site

Get your PWA Kit site up and running quickly. Use template extensibility with the Retail React App to customize your site.

- [Integrate Page Designer with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.md)
- [Template Extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md)
  - Tutorials:
    - [Customize a Component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-custom-component.md)
    - [Customize a Page](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/customize-a-page.md)
- SCAPI Overviews and Tutorials:
  - [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html)
  - [Promotion Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/promotion-details.html)
  - [Coupons, Gift Certificates, and Bonus Products](https://developer.salesforce.com/docs/commerce/commerce-api/guide/coupons-giftcerts-bonus-products.html)

[Learn more about building your site.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/build-customize.md)

## 6. Optional: Enable Your Merchant Team

Use these no-code features to complete some site design and merchandising tasks.

- [Storefront Preview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md)
- [Data and Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/data-and-analytics.md)

## 7. Test, Launch, Monitor, and Maintain

Discover the keys to a smooth site launch and ensure a positive shopper experience from Day 1. Learn how to effectively monitor key metrics and perform essential maintenance tasks to keep your site running smoothly after launch.

- [Debug PWA Kit Apps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.md)
- [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md)
- [Monitor Your Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/monitor-site.md)
- [Maintain Your Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maintain.md)

## See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/developer-workflow.html)
- [Search Engine Optimization (SEO) for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_seo_overview.htm&type=5)
- [PWA Kit GitHub Repository](https://github.com/SalesforceCommerceCloud/pwa-kit)
- [Managed Runtime API Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary)
- [Composable Storefront Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html)
- [Why Use SCAPI Instead of Open Commerce API (OCAPI)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/why-use-scapi.html)
- [Salesforce Commerce API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references)

<!-- document id=8283b06803e013a93aa36e203bf3e2abba177dc41d42d2b72a2440ca58024538 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/get-started-with-ocapi.md -->

# Get Started With OCAPI

The Open Commerce API (OCAPI) enables you to access resources using HTTP requests and HTTP responses. Each resource is addressed by its unique URL, which includes the API version. Data is transported using request or header parameters, or within the request body as a JSON document with a defined structure. 

OCAPI is divided into different APIs:
- Shop API: allows a client to interact with the system as a shop customer or as an agent shopping on behalf of a customer.
- Data API: gives create/read/update/delete access to system resources.
- Meta API: retrieves a formal description of the Open Commerce API, including custom attributes.

The following steps are recommended to start using the APIs:

- Read about the [HTTP Methods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/httpmethods.md) used to request resources and the [HTTP status codes and faults](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/httpstatuscodesandfaults.md) used in the responses.
- A client ID is mandatory for all requests. Read [get a client ID](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/clientapplicationidentification.md) for your application client.
- Review the [URL Schema](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/urlschema.md) used in the requests.
- Read about the [Resource States framework](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/resourcestates.md) used to ensure data consistency.
- Learn about the need to configure [Open Commerce API Settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md) to _authorize_ the usage of the resources, globally or for one site.

## Shop API

Use the Shop API to:
- Access public shop information such as product and catalog data, images, recommendations, and prices or promotions. Because in this case you're probably interacting with the system in the context of a guest customer, authentication isn’t required. However, as with every request, the system checks the [Open Commerce API Settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md) to verify that the client ID you provide is allowed to use the specified resource.
- Interact with the system as a registered or guest customer, for example: to access customer-specific data or to create and submit a basket. Authenticate the customer by obtaining a [JWT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jwt.md) to be passed in each request.
- Interact with the system as an agent on behalf of a customer in the context of a Business Manager user, for example: to access customer-specific data or to create and submit a basket. Authenticate the user by obtaining an [OAuth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/oauth.md) token for a Business Manager user to be passed in each request. The system checks both the [Open Commerce API Settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md) and the required Business Manager permissions before allowing the request.
- Enable personalized headless storefront experiences, such as customized promotions, pricing, and shipping methods. Set a shopper's context to enable personalized experiences using the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary).

## Data API
Use the Data API to access or update merchant resources such as coupons, customer lists, slot configurations or content. Authenticate the requests by obtaining an [OAuth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/oauth.md) token for your client ID or for a Business Manager user, to be passed in each request.

## Meta API
Use the [Meta API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/metadata.md) to access details about the resources and documents provided by the Open Commerce API.

For additional learning material, see the following:

- [Introduction to OCAPI (video)](https://embed.vidyard.com/share/SuHKKP72voLN2ezSDidqeB)
- [Introduction to OCAPI (slides)](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/OpenCommerceAPI.pdf)
- [OCAPI authorization and sample call overview using Postman (video)](https://embed.vidyard.com/share/ziVZBiEBQB4hoAat2BiAa5)
- [OCAPI Performance Best Practices FAQ](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/OCAPIPerformanceBestPracticesExternalFAQ.pdf)
- [Postman collection, environment. and OCAPI settings (GitHub repository)](https://gist.github.com/jorgehernandezSF/0fe8866996b5968f0daceb0c408be824)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/guides/developer-workflow.md)

<!-- document id=e2e25255adbce457d8408f3ef3c64f24dfba0e838b34ef076a0452a9054d33a2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/sandboxes/b2c-get-started-sandboxes.md -->

# Get Started with On-Demand Sandboxes

To access on-demand sandboxes, you must purchase sandbox credits, set up user roles, configure an API client key, and obtain your realm ID. Then provision and manage on-demand sandboxes as a self-service feature using the Sandbox API.

## Purchase On-Demand Sandbox Credits

To use on-demand sandboxes, you must purchase sandbox credits. Contact your Account Executive for more information.

When you issue a Sandbox API call to create a new on-demand sandbox, the system checks to make sure that your license has remaining credits. A user assigned to the Sandbox API User role controls how the credits are consumed. Monitor credit usage on a sandbox or on the realm using the Sandbox API.

## Set Up User Roles for On-Demand Sandboxes

An administrator uses Account Manager to assign appropriate roles to on-demand sandbox users. For each role, configure a scope filter and set it to either All Sandboxes or one or more individual sandboxes in the realm. A user with scope filter of All Sandboxes has access to all sandboxes as well as realm level operations, including realm level usage, creating and deleting a sandbox in the realm. A user with scope filter of individual sandboxes has access to only those individual sandboxes and the APIs of the sandboxes; the user doesn't have access to realm level operations or creating a new sandbox in the realm.

To assign roles to new or existing users, use the [Create a User Account in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_create_user.htm) or [Edit a User Account in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_edit_user.htm) procedures.

| Role                           | Purpose                                                                                                                                                           | Persona                                     | Scope Filter  |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------- |
| Sandbox API User               | Create, manage, and operate on-demand sandboxes. Users assigned to the Sandbox API User role can create on-demand sandboxes and consume credits and affect costs. | Administrator or Developer (optional)       | All Sandboxes |
| Business Manager Administrator | Access the on-demand sandbox using Business Manager, maintain data and use administrative functionality of on-demand sandboxes from Business Manager.             | Business Manager Administrator or Developer | All Sandboxes |
| Log Center User                | View log files for on-demand sandboxes in Logcenter.                                                                                                              | Administrator or Developer                  | All Sandboxes |
| OCAPI Explorer Debug User      | View debug information for OCAPI REST calls to the on-demand sandboxes.                                                                                           | Developer                                   | All Sandboxes |

## Configure an API Client ID

To allow users access to the Sandbox API, the administrator uses Account Manager to create an API client ID. If you plan to use scripts to automate API calls, the API Client ID requires the password for authentication.

To add an API client ID for the Sandbox API, use the [Add an API Client in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm) procedure.

| Setting                    | Value                                                                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Default Scopes             | <ul><li>roles</li> <li>tenantFilter</li> <li>profile</li></ul>                                                                           |
| Redirect URLs              | [https://admin.dx.commercecloud.salesforce.com/oauth2-redirect.html](https://admin.dx.commercecloud.salesforce.com/oauth2-redirect.html) |
| Token Endpoint Auth Method | `client_secret_post`                                                                                                                     |
| Access Token Format        | `JWT`                                                                                                                                    |

## Get Your Realm ID

To create and manage sandboxes, you must know the ID of your realm.

A realm contains your Primary Instance Group (PIG) and Secondary Instance Group (SIG). The SIG contains the sandboxes. Each realm has a unique four-character ID that you can get from your Account Executive (AE) or Customer Success Manager (CSM).

## Create an On-Demand Sandbox

### Automate Sandbox Management with the B2C Commerce CLI

You can skip manual API calls and manage your ODS lifecycle directly from your terminal. First, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md) to install the tool and authenticate.

**note:** To manage sandboxes via the CLI, your Account Manager user (or API Client) must be assigned the Sandbox API User role with a scope filter set to "All Sandboxes" for your specific realm. See [On-Demand Sandboxes for B2C Commerce Partners](https://help.salesforce.com/s/articleView?id=000388949&type=1) for detailed instructions.

Once configured, use the CLI to create, start, or stop sandboxes programmatically:

```Bash
b2c sandbox create --realm <id>
```

For a complete list of Sandbox CLI commands, see [Sandbox Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/sandbox.html).

### Set Up Your Sandox Using the Sandbox API

Use the `POST/sandboxes` method of the Sandbox API to create an on-demand sandbox.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Sandboxes section of the Sandbox API user interface, click to expand the `POST/sandboxes` method.

6.  Click **Try it out**.

7.  In the request body, replace `<your realm id>` with the appropriate value.

8.  If you don't want to use 24 hours for the Time-to-Live value for the sandbox, replace the **ttl** value of 24 with any number of hours up to 2160. Enter 0 or less for **ttl** to specify that the sandbox lasts until you delete it.

9.  Enter values for OCAPI or WebDAV settings if applicable, or delete those sections of the request body. To upload and deploy your code, and import site data, provision your ODS with the correct API client ID <link to correct info> By provisioning your sandbox with a [WebDAV](https://help.salesforce.com/s/articleView?id=cc.b2c_web_dav_client_permissions.htm&type=5) and [OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.html) configuration, use tools such as [sfcc-ci](https://github.com/SalesforceCommerceCloud/sfcc-ci) to further bootstrap your sandbox.

10. Click **Execute**.

    ![Request Body Contents](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_create_sandbox_minimum.png)

## Access Business Manager for On-Demand Sandboxes

You access Business Manager for on-demand sandboxes with a unified cluster-agnostic host name, so you don't have to remember the cluster that your sandbox belongs to.

To access Business Manager use a hostname that matches the pattern `<realm>-<instanceId>.dx.commercecloud.salesforce.com, for example, zzzz-001.dx.commercecloud.salesforce.com.` It also matches the domain name of the B2C centralized admin API server, [https://admin.dx.commercecloud.salesforce.com/](https://admin.dx.commercecloud.salesforce.com/).

<!-- document id=0a99cfe9ce7b39ff849c36c90c9f310d6dd1c7b68937e3f5581ca403ea0b749f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/extensions.md -->

# Get Started with Salesforce Commerce Extensions

Extensions are a mechanism for using Apex to customize the functionality that powers B2B and B2C storefronts. The custom Apex class that implements an extension is called an extension provider.

There are two types of extensions: **domain extensions** and **endpoint extensions**. Domain extensions are related to a functional domain, such as pricing. Endpoint extensions are related to specific Connect API endpoints (resources).

When you implement an extension provider for a domain extension, you affect a functional area, and the customizations that you provide can affect multiple Connect API endpoints. In contrast, when you implement an extension provider for an endpoint extension, you affect only a single Connect API endpoint (resource).

For domain extensions, a provider can extend or _replace_ the default functionality of a commerce domain. Extensions are available for a wide range of commerce domains, including cart, pricing, inventory, and more.

For endpoint extensions, a provider can modify the request and response of the Connect API endpoint, but can't replace the default functionality.

For the complete list of extensions that you can customize, see [Available Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/available-extensions.md).

**important:** Extensions don’t apply to the B2C Commerce architecture, which uses a different extensibility system called hooks.

## Extensions and Integrations

Extensions represent the next step for Salesforce Commerce extensibility that began with [integrations](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_integration_architecture.htm?q=integrations). Extensions allow you to customize functionality in a more targeted way than integrations. Also, extensions are available for more commerce domains than integrations.

Here’s a summary of the key differences between integrations and extensions:

|                  | Integrations             | Extensions                                                                         |
| ---------------- | ------------------------ | ---------------------------------------------------------------------------------- |
| Coding approach  | Implement Apex interface | Extend Apex base class                                                             |
| Customization    | Replace                  | Extend (for both domain or endpoint extensions) or replace (for domain extensions) |
| Commerce domains | Checkout calculators (4) | Cart/checkout calculators (5), pricing service, other services                     |

**important:** To check whether an extension is generally available, see [Available Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/available-extensions.md).

Although extensions are now the preferred way to customize Salesforce Commerce, integrations remain fully supported. Currently, payments can’t be customized with an extension.

## Use Cases

Extensions can be used by a wide range of developers. An in-house team or a systems integrator can create an extension provider to make small, targeted changes to a storefront to meet a merchant’s unique business needs. For more comprehensive solutions, a vendor can bundle several extension providers together and distribute them as a package on AppExchange.

Extensions unlock new opportunities to integrate B2C Commerce with other software (such as ERP systems), cut maintenance costs, and deliver great customer experiences.

## Cart and Checkout Calculations

Several domain extensions are designed to support cart calculation use cases, including cart calculations that occur during checkout. These extensions, taken together, comprise the Cart Calculate API. For more information, see [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.md).

## Architecture

In the Salesforce Commerce architecture, extensions can interact with many other parts of the system, including other extensions.

This diagram traces how a domain extension fits into the architecture using Pricing Service as an example.

![Extensions Flow](https://developer.salesforce.com/docs/media/salesforce-commerce/extension-flow.svg)

Let’s look at what’s happening at each stage of the extension flow, as indicated by the corresponding numbers in the diagram:

1. The Pricing Service extension is invoked. An extension can be triggered by a user action, a Connect API request—or even another extension. The extensible code checks to see if an extension provider class is mapped for the specific extension and store. The code that checks the mapping is called an **extension point**. The identifier used to uniquely identify an extension is called an **extension point name** (EPN). The EPN is used to map an extension point to one or more extension providers.
2. If an extension provider class is registered and mapped to the extension point name, the custom Apex in the extension provider class is executed. The extension provider can optionally make API requests.
3. For domain extensions, the extension provider can invoke the default implementation using the `super()` method. If you plan to modify -- but not completely replace -- default functionality, we strongly recommend calling the `super()` method as a best practice to ensure platform compatibility. If we add features, the features are automatically supported in the super() method implementation.
4. The extension provider can optionally invoke other commerce domain functionality, which can also be extended.

Each domain extension has a corresponding base class. Endpoint extensions, in contrast, all extend the same base class, and the extension provider can’t invoke a `super()` method.

## Domain Extension Provider Class Walkthrough

To show how a domain extension provider class is constructed, let’s walk through a series of code snippets. The snippets extend the base Apex class for the Pricing Service extension.

**note:** The actual implementation details are left out of the snippets so that you can follow the structure of the extension class more easily. A working version of this extension class (along with other examples) is available on the [Extension Provider Examples](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extension-provider-examples.md) page. This example class is provided for illustration purposes only and isn’t designed to represent a realistic use case.

Start by extending the base class, which is [`commercestorepricing.PricingService`](/docs/commerce/salesforce-commerce/references/comm-apex-reference/PricingService.html):

```java
public class PricingServiceSample extends commercestorepricing.PricingService {
    // Extension code.
}
```

You can override the `processPrice` method of [`commercestorepricing.PricingService`](/docs/commerce/salesforce-commerce/references/comm-apex-reference/PricingService.html), which is used on PLPs and PDPs. In this example, we’ve replaced the entire method with custom logic to extract product data, get the price from an external service, and process the pricing response.

```java
    public override commercestorepricing.PricingResponse processPrice(commercestorepricing.PricingRequest request) {

        // Extract product data from the request with custom logic and get the product's price from an external service.

        // Create a pricing response without the default processing.
        commercestorepricing.PricingResponse response = new commercestorepricing.PricingResponse('USD');

        // Process the pricing response with more custom logic.

        // Return the processed pricing response.
        return response;
    }
```

The base class has another method that you can override: `processTransactionalPrice`. Overriding this method affects cart and checkout. For illustration purposes only, we treat this method differently than `processPrice`. Instead of replacing the entire method with custom logic, we call the base method with the `super()` method. Although we’re calling the base method, we can still insert custom logic before and after the `super()` call.

```java
    public override commercestorepricing.TransactionalPricingResponse processTransactionalPrice(commercestorepricing.TransactionalPricingRequest request2) {
        // Get the transactional pricing response using the default implementation of the processPrice method. Although processTransactionalPrice is called unmodified, you can supply it with a modified version of the request.
        commercestorepricing.TransactionalPricingResponse txnResponse = super.processTransactionalPrice(request2);

        // Modify the transactional pricing response with custom logic.

        // Return the modified transactional pricing response.
        return txnResponse;
    }
```

We define a custom private method to get the prices from an external service:

```java
    private Map<String, PriceDataFromExternalService> getPricesFromExternalService(Set<String> productIds){
        // Custom logic.
    }
```

As you can see from this example, for domain extensions, you have the flexibility to create extension classes that can:

- Replace the entire default implementation of each base class method with custom logic.
- Add custom logic before calling the default implementation of a base class method.
- Add customer logic after calling the default implementation of a base class method.
- Add custom methods and classes.

To learn how to add your own Apex classes to a Salesforce org, see [Adding an Apex Class](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_qs_class.htm).

## Endpoint Extension Provider Class Walkthough

All endpoint extension provider classes extend the [ConnectApi.BaseEndpointExtension](/docs/commerce/salesforce-commerce/references/comm-apex-reference/BaseEndpointExtension.html) class.

### Virtual Methods

The `ConnectApi.BaseEndpointExtension` class defines the following virtual methods:

- `global virtual ConnectApi.EndpointExtensionRequest beforeGet(ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionResponse afterGet(ConnectApi.EndpointExtensionResponse response, ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionRequest beforePost(ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionResponse afterPost(ConnectApi.EndpointExtensionResponse response, ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionRequest beforePatch(ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionResponse afterPatch(ConnectApi.EndpointExtensionResponse response, ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionRequest beforePut(ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionResponse afterPut(ConnectApi.EndpointExtensionResponse response, ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionRequest beforeDelete(ConnectApi.EndpointExtensionRequest request)`
- `global virtual ConnectApi.EndpointExtensionResponse afterDelete(ConnectApi.EndpointExtensionResponse response, ConnectApi.EndpointExtensionRequest request)`

For each HTTP method, the base class provides a `before` and `after` method. You can override `before` methods to modify the request before the Connect API endpoint is called. And you can override `after` methods to modify the response of the Connect API endpoint after it's called.

### ConnectApi.EndpointExtensionRequest

The [ConnectApi.EndpointExtensionRequest](/docs/commerce/salesforce-commerce/references/comm-apex-reference/EndpointExtensionRequest.html) object wraps the request payload for the Connect API endpoint request. This object provides the following methods:

- `global Object getParam(String name)` -- get the value for a parameter name.
- `global void setParam(String name, Object value)` -- set the value for a parameter name.
- `global Set<String> getKeys()` -- return all parameter names in the request.

### ConnectApi.EndpointExtensionResponse

The [ConnectApi.EndpointExtensionResponse](/docs/commerce/salesforce-commerce/references/comm-apex-reference/EndpointExtensionResponse.html) object wraps the response payload returned by the Connect API endpoint, and provides the following method:

- `global Object getResponseObject()` -- returns the Connect API response wrapped as an Object.

### Manipulating Requests and Responses

To manipulate a request or response, you cast the request or response to a type that's expected for the Connect API endpoint.

For example, let's consider the [Commerce Webstore Account Addresses](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm) Connect API endpoint.

This endpoint has an HTTP GET method and an HTTP POST method. Therefore, in your extension provider class for this endpoint, you can override the `beforeGet`, `afterGet`, `beforePost`, and `afterPost` methods.

To handle the requests and responses, you must know the Apex types for the various inputs and outputs.

In this example, the GET method doesn't take an input, but the request URL can specify multiple URL parameters.

The GET method returns a [Commerce Address Collection](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_commerce_address_collection.htm) output. Within your Apex code, you reference this type as `ConnectApi.CommerceAddressCollectionRepresentation`.

The POST method takes an input, but the request URL doesn't specify URL parameters. The POST method takes a [Commerce Address Input](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_commerce_address_input.htm) input. Within your Apex code, you reference this type as `ConnectApi.CommerceAddressInputRepresentation`.

The POST method returns a [Commerce Address](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_commerce_address_output.htm) output. Within your Apex code, you reference this type as `ConnectApi.CommerceAddressOutputRepresentation`.

In the `beforeGet` method, you can access the URL parameters in the request like this:

```java
// Getting the value of the sortOrder request parameter
String mySortOrder = request.getParam('sortOrder');
```

In the `afterGet` method, you access the body of the response like this:

```java
// Cast the response object to the type returned by Connect API endpoint
ConnectApi.CommerceAddressCollectionRepresentation output = (ConnectApi.CommerceAddressCollectionRepresentation)response.getResponseObject();
```

In the `beforePost` method, you can access the request like this:

```java
// Cast the request body to the input type for the Connect API endpoint
// Notice the lowercase "c" in the argument to getParam()
ConnectApi.CommerceAddressInputRepresentation input = (ConnectApi.CommerceAddressInputRepresentation)request.getParam('commerceAddressInputRepresentation');
```

Lastly, in the `afterPost` method, you can access the response like this:

```java
// Cast the response object to the type returned by Connect API endpoint
ConnectApi.CommerceAddressOutputRepresentation output = (ConnectApi.CommerceAddressOutputRepresentation)response.getResponseObject();
```

After you create a variable for the request or response, you can access the properties of the request and response with getters and setters. Each property has a corresponding getter and setter.

For example, you can access the `count` property of the `ConnectApi.CommerceAddressCollectionRepresentation` response like this:

```java
ConnectApi.CommerceAddressCollectionRepresentation output = (ConnectApi.CommerceAddressCollectionRepresentation)response.getResponseObject();
Integer myCount = output.getCount();
```

## Manage Extensions with Salesforce CLI

After adding an extension class to a Salesforce org, there are two more tasks required before you can fill an extension slot with a custom extension provider:

1. Register the extension class.
2. Map the extension class to a B2B store.

The easiest way to register and map extension classes is with Salesforce CLI and the Salesforce Commerce plug-in for `sf`.

**important:** To manage extensions, you must use the latest version of Salesforce CLI. For detailed instructions, see [Install Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm) and [Update Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_update_cli.htm).

To install the plug-in, run `sf plugins install @salesforce/commerce`.

Example commands:

```bash
# Register an extension class
sf commerce:extension:register --targetusername pia@northerntrailoutfitters.com --apex-class-name PricingDemoService --extension-point-name Commerce_Domain_Pricing_Service --registered-extension-name PricingDemoService

# Map an extension class
sf commerce:extension:map --registered-extension-name PricingDemoService --store-id 0ZETC000000DflJ4AS

# Unmap an extension class
sf commerce:extension:unmap --registered-extension-name PricingDemoService --store-id 0ZETC000000DflJ4AS
```

For detailed installation and usage information, see the plug-in’s [README](https://github.com/forcedotcom/commerce-on-lightning).

### Alternate Methods

You can also register and map an extension provider by inserting custom Apex into sObjects. The setup process for extensions is similar to the [setup process for integrations](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_integration_setup.htm). To register an extension provider, modify [RegisteredExternalService](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_registeredexternalservice.htm) and to map an extension provider, modify [StoreIntegratedService](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_storeintegratedservice.htm).

### Commerce Extensions Resources

Developers can register an extension Apex class and map it to a web store using the Commerce Extensions resources. To accomplish this, make a POST request to the [Commerce Extension Providers API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_extension_providers.htm) to register the extension class. Then, make a POST request to the [Commerce Extension Mappings API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_extension_mappings.htm) to map the extension class to the store. To unmap the extension class, send a DELETE request to the [Commerce Extension Mapping API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_extension_mapping.htm).

### User Interface

Merchants can map and unmap domain extension providers directly in the administration interface. See [Replace a Default Commerce Process with an Apex Class](https://help.salesforce.com/s/articleView?id=commerce.comm_extensions.htm&type=5) on Salesforce Help.

## Next Steps

In this guide we’ve explored how Salesforce Commerce extensions give you fine-grained control over storefront functionality. We’ve examined how extensions fit into the Salesforce Commerce architecture. We've walked through the construction of an example extension provider. We've also described the methods for registering and mapping extension providers.

Now that you have a solid understanding of extensions, the next steps are to:

- Explore the [Extension Provider Examples](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extension-provider-examples.md).
- Explore the list of [Available Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/available-extensions.md) and look up the base Apex classes that are relevant to your application.
- Learn more about extension development and testing with other guides, including:
  - [Write Tests for an Extension Provider](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/write-tests-for-an-extension-provider.md)
  - [Mock the Base Apex Class](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/mock-the-base-apex-class.md)

<!-- document id=ddea7556783aeb04930db7a97974566fe675c0beac5ac0449125b9cb98977aad url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-build-sfra.md -->

# Get Started with SFRA

To use SFRA to develop your own storefront, first get the code and supporting tools. Then build and configure SFRA.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Get the SFRA Repositories from GitHub

You must have access to the Salesforce CommerceCloud repositories on GitHub, where you are able to either download a copy of the SFRA repositories or clone the repositories on your local system. If you clone the repositories, issue git commands to perform tasks like getting the latest updates or seeing recent changes.

1.  If you don’t have a GitHub account, see [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/site-development/b2c-github-repo-access.md).

2.  Search for the following repositories, and click **Clone or download** to copy each repository to your local system.

    **note:** Clone or download the repositories next to each other, as siblings, as in the following example. If you nest the repositories, you can’t use the build tools.

    ```
    your project
    ├── eslint-plugin-sitegenesis
    ├── lib_productlist
    ├── plugin-applepay
    ├── plugin_commercepayments
    ├── plugin_datadownload
    ├── plugin_giftregistry
    ├── plugin_instorepickup
    ├── plugin_productcompare
    ├── plugin_salesforcepayments
    ├── plugin_sitemap
    ├── plugin_wishlists
    ├── sfra-jsdoc
    ├── sgmf-scripts
    ├── storefront-reference-architecture
        ├── cartridges
        │   ├── app_storefront_base
        │   └── modules
    └── storefrontdata
    ├── app_custom_domain_mysite1
    ├── app_custom_domain_mysite2

    ```

    - **[eslint-plugin-sitegenesis](https://github.com/SalesforceCommerceCloud/eslint-plugin-sitegenesis)**—Optional. Used to lint and test code.
    - **[lib_productlist](https://github.com/SalesforceCommerceCloud/lib_productlist)**—Optional. A shared code base required by both the plugin_wishlist and plugin_giftregistry repositories.
    - **[plugin-applepay](https://github.com/SalesforceCommerceCloud/plugin-applepay)**—Optional. Extends the base cartridge to add Apple Pay to your site.
    - **[plugin_commercepayments](https://github.com/SalesforceCommerceCloud/plugin_commercepayments)**—Optional. This repository will be retired in a future version. We recommend using the plugin_salesforcepayments repository for payment integration with Stripe.
    - **[plugin_salesforcepayments](https://github.com/SalesforceCommerceCloud/plugin_salesforcepayments)**—Optional. Provides functionality for payment integration with Adyen, Stripe, and PayPal.
      **note:** For the Stripe's terms of service with the SEPA payment option, you must replace `[the seller]` with the the appropriate name in the `sepa_debit.message.mandate` key name entry in `plugin_commercepayments/cartridges/plugin_commercepayments/cartridge/templates/resources/salesforcepayments.properties`.

    See [SDD Core Mandate Translations](https://www.europeanpaymentscouncil.eu/other/core-sdd-mandate-translations) for details on the SEPA Direct Debit (SDD) payment mandate.

    **note:** The plugin_salesforcepayments and plugin_commercepayments cartridges don't support payments that use the plugin-applepay or plugin_instorepickup cartridges. If you're applying additional cartridges to the storefront, you must disable the plugin-applepay and plugin_instorepickup in the site preferences and in the cartridge path.

    Internet Explorer isn't a supported browser for Salesforce Payments or Commerce Payments.

    - **[plugin_datadownload](https://github.com/SalesforceCommerceCloud/plugin_datadownload)**—Optional. Provides GDPR related functionality.
    - **[plugin_giftregistry](https://github.com/SalesforceCommerceCloud/plugin_giftregistry)**—Optional. Provides gift registry functionality.
    - **[plugin_instorepickup](https://github.com/SalesforceCommerceCloud/plugin_instorepickup)**—Optional. Provides buy-online-pick-up-in-store functionality.
    - **[plugin_productcompare](https://github.com/SalesforceCommerceCloud/plugin_productcompare)**—Optional. Provides functionality to compare various products.
    - **[plugin_sitemap](https://github.com/SalesforceCommerceCloud/plugin_sitemap)**—Optional. Provides sitemap functionality.
    - **[plugin_wishlists](https://github.com/SalesforceCommerceCloud/plugin_wishlists)**—Optional. Provides wishlist functionality.
    - **[plugin_ordermanagement](https://github.com/SalesforceCommerceCloud/plugin_ordermanagement)**-Optional. Provides Salesforce Order Management self-service functionality.
    - **[sfra-jsdoc](https://github.com/SalesforceCommerceCloud/sfra-jsdoc)**—Optional. Builds the JSDoc for the project. Extend the JSDoc to include the JSDoc for custom cartridges.
    - **[sgmf-scripts](https://github.com/SalesforceCommerceCloud/sgmf-scripts)**—Required. The command-line tools that compile the project and upload the cartridges.
    - **[storefront-reference-architecture](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture)**—Required. Includes the `app_storefront_base` cartridge and a `modules` cartridge that includes the server module.
    - **[storefrontdata](https://github.com/SalesforceCommerceCloud/storefrontdata)**—Required. Contains the data for SFRA.

3.  If you downloaded the repositories, expand the .zip files.

    **note:** On macOS, you can use the command-line **unzip** utility to expand the files.

## Install and Configure SFRA Tools

Configure the `app_storefront_base` cartridge and any plugin cartridges you want for your storefront.

### Downloading and Installing Development, Debugging, and Deployment Tools

Contribute to the [dwdebugger](https://github.com/SalesforceCommerceCloud/dwdebugger) repository, which uses the Script Debugger API to provide debugging capabilities for VSC and node-inspector.

If you want to upload your code automatically, use the upload tool included with the `sgmf-scripts` command-line tools.

### Installing npm Dependencies for SFRA

SFRA depends on modules managed by npm. If you downloaded the repository as a .zip file, these instructions assume that you have expanded it.

1.  Open a command prompt and navigate to the `storefront-reference-architecture` directory.
2.  Download and install [Node.js](https://nodejs.org/download/) version 18 (which has been tested with SFRA). Test whether node is installed by entering:

    ```
    node -v
    ```

    If node is already installed, this command returns a version number. If it's installed, skip to the next step.

    **note:** B2C Commerce uses Node.js only for npm dependency management.

3.  Use npm to install the modules included with SFRA. This approach is possible only if you're in the `storefront-reference-architecture` directory and you installed Node.js.

    ```
    npm install
    ```

    **important:** Run this command any time you download a new version of SFRA, because the dependencies included with the application sometimes change.

### Installing SFRA Command-Line Tools

While packages are easy to install globally on most operating systems, it can be complicated to globally install packages on the Mac OS/X. If you're working on a \*nix or Window system, we recommend that you install the command-line build tools for SFRA globally. This approach makes it simple to create custom cartridges with the correct structure anywhere on your development machine.

```
npm install -g sgmf-scripts
```

After installation, use the `sgmf-scripts` command-line tools in any directory on your machine with a syntax similar to:

```
sgmf-scripts --help
```

If you're installing on a Mac and get an EACCES error, try [Fixing Your Permissions](https://docs.npmjs.com/getting-started/fixing-npm-permissions) to globally install the node. Adjust your node installation if necessary. This process can be time-consuming. Global installation isn't necessary, but it eliminates the installation step for any new cartridge.

If you want to install `sgmf-scripts` locally, enter:

```
npm install sgmf-scripts
```

After installation, use `sgmf-scripts` in the current folder with a syntax similar to:

```
node node_modules/sgmf-scripts --help
```

## Build SFRA

Build SFRA and upload code to your sandbox. If a cartridge has style sheets or JavaScript, compile it before uploading.

### Building a Cartridge

To compile the style sheets and JavaScript for a cartridge:

1.  Open a command-line terminal.
2.  Navigate to the top-level folder of the repository containing the cartridges directory, such as `storefront-reference-architecture`.
3.  To compile both CSS and JavaScript, enter:

    ```
    npm run compile:js && npm run compile:scss && npm run compile:fonts
    ```

    To compile only CSS:

    ```
    npm run compile:scss
    ```

    To compile only JavaScript:

    ```
    npm run compile:js
    ```

    **note:** Usually, you only have to compile fonts once.

### Build Commands

The build commands are defined in the `scripts` section of the `package.json` for your top-level folder. Change the commands and add commands for other command-line tools in the `package.json` file.

If you have installed the `sgmf-scripts` node globally, use this command to see all current build commands:

```
sgmf-scripts --help
```

If you have installed the `sgmf-scripts` node locally, use this command to see all current build commands:

```
node node_modules/sgmf-scripts --help
```

Customize the build commands or add new ones in your `package.json`. See npm documentation for more information about adding scripts for npm.

### Building the JSDoc

To build an HTML version of the JSDoc:

1.  Clone or download the [sfra-jsdoc](https://github.com/SalesforceCommerceCloud/sfra-jsdoc) repository from GitHub.
2.  Read the ReadMe for the most up-to-date instructions on how to configure and run the repository.

## Upload Code for SFRA

Use the SFRA command-line upload tool to upload your code.

1.  In the cartridge you want to upload, locate, or create a `dw.json` file.

    The `dw.json` file is automatically created if the `sgmf-scripts` `createCartridge` build tool command is used to create the cartridge. However, for some cartridges, such as the `app_storefront_base` and `modules` cartridges provided by B2C Commerce, you must create the `dw.json` file and add it to the cartridge. Create the `dw.json` file in the top-level folder of the repository, as a sibling of the `cartridges` directory.

    The `dw.json` file contains the information required to establish a server connection and the code version to upload your cartridges to.

    ```
    {
        "hostname": "yoursandbox-inside-your-realm.demandware.net",
        "username": "yourusername",
        "password": "yourpwd",
        "code-version": "version1"
    }
    ```

    **note:** This file is normally unencrypted. However, because it contains the instance and password data necessary to upload code, you can use extra measures to secure it.

2.  To upload the code, use the applicable command.

    - To upload all cartridges for the repository, use `uploadCartridge`:

      ```
      npm run uploadCartridge
      ```

    - To upload a specific cartridge, use `uploadCartridge` with the name of the cartridge:

      ```
      npm run uploadCartridge *mycartridge*

      ```

    - To upload a single file, use `upload`.

      If you use the same commands as the app_storefront_base cartridge, run:

      ```
      npm run upload *path/to/my/filename.ext*

      ```

    - To detect changes to files in your cartridge and automatically upload them to the server, use `watch`.

      If you use the same commands as the `app_storefront_base` cartridge, run:

      ```
      npm run watch
      ```

      The `watch` command makes it simple to keep the code on your sandbox instanace up-to-date.

3.  Make sure that your code is actually on the server:

    1.  Select **Administration** > **Site Development** > **Code Deployment**.

    2.  Click the **Code Version** link for the code version you specified in the `dw.json` file.

        If your cartridge was uploaded successfully, it appears in the list of cartridges on the Version Summary page.

The command-line `watch` and `upload` commands are wrappers for the [Dwupload](https://github.com/SalesforceCommerceCloud/dwupload) project. Download the project from GitHub if you want to contribute.

## See Also

- [Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/commerce-vibes/guides/cv-agentforce-commerce-vibes.md)

<!-- document id=cda1b9ecced7ada573f795ab09640a4ceccbd82c61f3ccffae8b46d4fd567ddc url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-get-started-section.md -->

# Get Started with Storefront Next

Learn about the architecture and core concepts that power Storefront Next, and review browser compatibility requirements to ensure your storefront works across different platforms. Get up and running with Storefront Next by creating a new storefront or linking an existing one to B2C Commerce.

In this section:

- [Storefront Next Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-release-notes.md)
- [Managed Runtime Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-release-notes.md)
- [Architecture and Core Concepts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-architecture.md)
- [Browser Compatibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-browser-comp.md)
- [Storefront Next Template Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-template-compare.md)
- [Quick Start: Create Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-choice.md)
- [Create an Environment in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-create-environment.md)
- [Link an Existing Storefront to B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-link-storefront.md)

<!-- document id=680f2136fb927fbece940ca218229a00f8f1d7c109efc221eb7257e41bc22d4f url=/developer/current/en-us/commerce-cloud/sfra/guides/sfra-overview.md -->

# Get Started with Storefront Reference Architecture

Mobile now accounts for more than 60% of shopping visits, yet mobile conversion rates are still a fraction of desktop rates. Why? While retailers have adopted mobile optimization technologies, they have done so on top of existing desktop-oriented site architectures, creating friction across the mobile shopping journey.

B2C Commerce provides merchants with the Storefront Reference Architecture (SFRA) to serve as a framework for website design. SFRA provides customers with a starting point for web-storefront design. It combines best practices in site design and technical architecture to provide a blueprint for merchants looking to build and customize their ecommerce storefronts. It includes:

- A JavaScript controllers development and customization model which allows teams to use a model-view-controller (MVC) development pattern.
- The popular Bootstrap UI framework to optimize the shopping experience across devices.

SFRA was engineered through a data-driven design analysis of over 2,000 mobile storefronts to identify optimal UX approaches. Its modern architecture lets merchandisers and developers build mobile experiences faster than ever.

With Storefront Reference Architecture, brands are empowered to:

- Improve shopping experiences on mobile web.
- Reduce storefront total cost of ownership and stay up to date easier.
- Innovate faster with industry-standard developer tools and best-of-breed third-party integrations.

For more SFRA details, [SFRA Frequently Asked Questions](https://developer.salesforce.com/docs/commerce/sfra/guide/sfra-faq.html) and [SFRA Features](https://developer.salesforce.com/docs/commerce/sfra/guide/sfra-feature-list.html).

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


[Storefront Reference Architecture](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture) reference application

**tip:** [PWA Kit and Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/overview) was launched in 2021 as an alternative to SFRA. Talk to your Account Manager to understand which is the best fit for your needs.

## Customize Your Storefront Architecture

Storefront Reference Architecture connects to the digital platform through an API layer, which allows brands to bring in new code, integrate with third-party providers, and progressively iterate onsite design. The B2C Commerce digital platform releases new innovations up to 10 times a year. These new functionalities, such as artificial intelligence, Apple Pay, and more, are integrated into the Storefront Reference Architecture through the API layer.

## Optimize Your Storefront for Mobile

With Storefront Reference Architecture, iteratively build a mobile-first site based on mobile design best practices. Plus, get on the right path with site design consultations and accelerators offered through the B2C Commerce practice team.

## Launch Faster with a Quicker ROI

Merchants can simply use the prebuilt storefront design along with preconfigured integrations. This means lower project costs, faster time to value, and as a result, they benefit from incremental revenue and quicker go-live

## Enhance the Mobile Shopping Experience

From reducing the number of taps in the checkout flow to integration with Apple Pay, Storefront Reference Architecture provides a complete and intelligently designed storefront built to increase conversion.

## Develop Efficiently and Reduce Storefront TCO

Storefront Reference Architecture leverages JavaScript controllers, Bootstrap 4 development framework, and a model-view-controller architecture approach, making it easy to maintain and update the storefront following initial implementation.

## Extend Core Functionality

An enhanced set of mobile APIs and a network of certified partners extend Storefront Reference Architecture core functionality with prebuilt integrations from a trusted network of technology providers.

<!-- document id=2dc8607c9836cb7fa03b2960f6dd97d012c8129d236e942ed433280de014bb0c url=/developer/current/en-us/commerce-cloud/commerce-api/guides/scapi-get-started.md -->

# Get Started with the B2C Commerce API

The B2C Commerce API (SCAPI) is a set of RESTful APIs for building storefronts, merchant tools, and integrations on the B2C Commerce platform. It also goes by "Salesforce Commerce API" or just "Commerce API." For B2C Commerce customers, the API is available at no extra cost.

**tip:** To browse the endpoints, see the [API Reference](/docs/commerce/commerce-api/references/about-commerce-api/about.html). To learn how SCAPI fits into the B2C Commerce stack, see [Composable Storefront and SCAPI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-scapi.html).

## Make Your First Request

The following two curl commands are all you need to get started. They use a SLAS private client to get a guest token, then fetch a product from the demo sandbox.

### Step 1: Get a Guest Token

Replace `{client_id}` and `{client_secret}` with your SLAS private client credentials. (To create a SLAS client, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).)

```sh
curl "https://kv7kzm78.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/f_ecom_zzte_053/oauth2/token" \
  -u "{client_id}:{client_secret}" \
  -d "grant_type=client_credentials" \
  -d "channel_id=RefArch"
```

The response includes an `access_token`:

```json
{
  "access_token": "eyJ0eXAiOiJKV1Q...",
  "expires_in": 1800,
  "token_type": "Bearer"
}
```

### Step 2: Call a Shopper API

Use the `access_token` from Step 1 to fetch a product:

```sh
curl "https://kv7kzm78.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_zzte_053/products/25695327M?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

A successful response returns product details as JSON:

```json
{
  "id": "25695327M",
  "name": "Striped Silk Tie",
  "currency": "USD",
  "price": 19.19,
  ...
}
```

In addition to securing access to the Shopper API, SLAS can also turn on third-party identity providers, single sign-on, and personalization in your application.

**note:** **Other ways to get started:**
- Run a complete example (including token acquisition) with the Commerce SDK: [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/api-and-sdk-demo.md)
- Explore APIs interactively: [SCAPI Postman Collection](https://www.postman.com/salesforce-developers/workspace/salesforce-developers/collection/15394816-b59efa68-87fd-4398-ba68-f15e931b879f)
- Use the B2C CLI to verify instance connectivity: [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md)

## Choose Your Path

| I want to...                      | Start here                                                                                                                                                                  |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Build a storefront**            | [Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide) uses the Shopper APIs exclusively.                                   |
| **Build backend or admin tools**  | Use the [SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md) with an Account Manager token.                                                                                 |
| **Extend existing API behavior**  | Add custom logic with [Hooks](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/extensibility_via_hooks.md).                                                                                                                  |
| **Create new API endpoints**      | Build [Custom APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-apis.md) under the SCAPI framework.                                                                                                              |
| **Migrate from OCAPI**            | See [Why Use SCAPI Instead of OCAPI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/why-use-scapi.md).                                                                                                                     |

## Set Up Your Instance

If you don't have a B2C Commerce instance, try the demo sandbox used in the example above. It's also used in the [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/api-and-sdk-demo.md).

To set up your own instance:

1. Determine your environment (dev, staging, or production), or create an [on-demand sandbox](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/creating-an-on-demand-sandbox.html).
2. Look up your configuration values: [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md).
3. Set up API access: [Authorization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization.md).

## Understand SCAPI

### Shopper APIs vs. Admin APIs

SCAPI consists of two API types, plus open-source SDKs and a developer tooling ecosystem. The API type you use depends on your application.

| | Shopper APIs | Admin APIs |
|-|-------------|------------|
| **Purpose** | Customer-facing (browsing, cart, checkout) | Merchant-facing (product, order, inventory management) |
| **Authentication** | [SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md) (OAuth 2.1) | [Account Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-admin-apis.md) |
| **Scale** | High-scale, supports anonymous users | Moderate usage |
| **Access** | Read-only (exceptions: Baskets, Orders) | Read and write |
| **Naming** | API names start with "Shopper" | No naming convention |

### JavaScript SDKs

| Package                                                                                          | Description                                          | Docs                                                                       |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| [`commerce-sdk`](https://www.npmjs.com/package/commerce-sdk)                                     | Node.js (server-side or CLI)                         | [Docs](https://salesforcecommercecloud.github.io/commerce-sdk/)            |
| [`commerce-sdk-isomorphic`](https://www.npmjs.com/package/commerce-sdk-isomorphic)               | Isomorphic (server + browser)                        | [Docs](https://salesforcecommercecloud.github.io/commerce-sdk-isomorphic/) |
| [`@salesforce/commerce-sdk-react`](https://www.npmjs.com/package/@salesforce/commerce-sdk-react) | React hooks for SCAPI                                | [Docs](https://salesforcecommercecloud.github.io/pwa-kit/)                 |

For other languages, use the [SCAPI Postman Collection](https://www.postman.com/salesforce-developers/workspace/salesforce-developers/collection/15394816-b59efa68-87fd-4398-ba68-f15e931b879f) or the API specs in [`commerce-sdk`](https://github.com/SalesforceCommerceCloud/commerce-sdk/tree/main/apis).

To explore SCAPI with your assistant, use the [B2C MCP](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md#connect-your-ai-assistant). It provides documentation search, schema discovery, and general-purpose execution of SCAPI Admin APIs, including discovered Custom Admin APIs. Shopper schemas are available for reference; Shopper API execution uses your storefront code or a direct API client.

## Operational Reference

The following information is important when preparing for production use.

### Constraints

- SCAPI requests are [rate limited](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/throttle-rates.md) to ensure availability.
- Shopper APIs must respond within 10 seconds; Admin APIs within 60 seconds. See [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.md).
- Request and response bodies have size limits. See [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.md).
- Shopper API requests are routed by USID. Don't reuse the same USID for many guest shoppers.
- For staging with vanity domains, set up [eCDN for Staging](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_ecdn_for_staging.htm&type=5).
- For cross-origin browser access, configure [CORS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-cors.md).

### Troubleshooting

- Use correlation IDs to match requests to responses. Include a `correlation-id` header in your request and the response returns it as `x-correlation-id`. See [View SCAPI Logs and Track Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md).

### Change Policy

**important:** Some new features are available only with specific B2C Commerce versions. This information is included in the [B2C Commerce Release Notes](https://help.salesforce.com/s/articleView?id=commerce.b2c_rn_release_notes.htm&type=5) and the API specification where applicable.

Make sure that your code can handle nonbreaking changes to the API, such as new fields, new optional parameters, or changes to error messages.

SCAPI is updated regularly with new features, bug fixes, and improvements. Updates are announced in [Salesforce Status](https://status.salesforce.com/products/B2C_Commerce_Cloud) and the [SCAPI Release Notes](/docs/commerce/commerce-api/references/about-commerce-api/about.html). Some features require specific [B2C Commerce versions](https://help.salesforce.com/s/articleView?id=commerce.b2c_rn_release_notes.htm&type=5).

For the full list of nonbreaking change types and the deployment schedule, see the [B2C Commerce Deployment Schedule](https://help.salesforce.com/s/articleView?id=commerce.b2c_deploy_schedule_24.htm&type=5).

### Availability

Subscribe to availability updates on [Salesforce Status](https://status.salesforce.com/products/B2C_Commerce_Cloud). During maintenance, SCAPI returns [maintenance responses](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/response-handling.md). For load management details, see [Load Shedding and Rate Limiting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/throttle-rates.md).

## Next Steps

- For detailed use cases and examples, see [Develop](https://developer.salesforce.com/docs/commerce/commerce-api/guide/dev-container.html).
- To explore endpoint specifications, see the [API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references).
- For cross-cutting topics (authentication, caching, hooks, personalization), see [General Guidance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/general-guidance.md).

<!-- document id=b9d4e9d294fcd4ca085843f907ca9d5718b06adc6fd2ed1dd91312461be8780d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-get-files-from-directory-ds.md -->

# GetFilesFromDirectory.ds

Review the GetFilesFromDirectory.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```

/*
 * Gets a file list from an FTP/HTTP(S) server
 *
 * @input Directory  : dw.io.File   the directory to browse
 * @input SortDirection : String    'ASCENDING' or 'DESCENDING'
 * @input NamePattern  : String    The pattern for the filenames (use ".*" to get all)
 * @input sampleLogger  : Object Sample logger input for Sample logger
 * @output FileList  : dw.util.Collection  The files matching the pattern
 * @output sampleLogger : Object Sample logger debug output for Sample logger
 * @output sampleError  : Object Sample error error output for Sample logger
*
*/
importPackage( dw.system );
importPackage( dw.util );
importPackage( dw.io );

// Sample Logging ImportScript
importPackage(dw.system);
importPackage(dw.util);
importPackage(dw.io);

// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");

function execute(pdict: PipelineDictionary): Number {
    // sample Logging var
    var _context: String = new Context("GetFilesFromDirectory.ds");
    var _logger: Log = Log.getLogger(pdict);

    // input variables
    var directory: File = pdict.Directory;
    var sortDirection: String = pdict.SortDirection;
    var patternString: String = pdict.NamePattern;


    if (directory == null || !directory.isDirectory()) {
        return PIPELET_ERROR;
    }
    try {
        var sorted: SortedSet = getSortedFileList(directory, patternString, sortDirection);

        if (sorted != null) {
            pdict.FileList = sorted;

            _logger.info(_context, "Get files from " + directory);
            // sample Logging call into debug handler
            pdict.sampleLogger = _logger;

            return PIPELET_NEXT;
        } else {
            _logger.debug(_context, "App server directory " + directory + " is empty.");
            // sample Logging call into debug handler
            pdict.sampleLogger = _logger;
            return PIPELET_ERROR;
        }
    } catch (e) {
        var exception: sampleException = new sampleException(_context, "Error occurred calling get files from directory", e);
        _logger.error(_context, "Error occurred calling  get files from directory" + exception);
        pdict.sampleError = exception;

        return PIPELET_ERROR;
    }
}

// UTIL.ds ?

function descending(var1: Object, var2): Number {
    if (var1 == var2) return 0
    else if (var1 < var2) return 1
    else return -1;
}

function getSortedFileList(directory: File, patternString: String, sortDirection: String): SortedSet {
    var fileList: SortedSet = ((sortDirection == "DESCENDING") ? new SortedSet(descending) : new SortedSet());
    return fileList.addAll(getFileList(directory, patternString)) ? fileList : null;
}

function getFileList(directory: File, patternString: String): ArrayList {
    //@TODO : remove dir work around
    Logger.debug("Get file list from app server directory {0}.", directory);



    var fileList : ArrayList = new ArrayList();


 var content : Array = directory.list();
 if (content.length > 0)
 {
  if (!empty(patternString))
   Logger.debug("Apply pattern {0}", patternString);
  var pattern : RegExp = !empty(patternString) ? new RegExp(patternString) : null;
  / /
    var pattern = patternString;
    for (var i: Number = 0; i < content.length; i++) {
        var file: String = content[i];
        if ((pattern == null) || file.match(pattern)) {
            fileList.add(file);
            Logger.debug("File / directory {0} added to list.", file);
        } else
            Logger.debug("File / directory {0} skipped.", file);
    }
} else {
    //@TODO : remove dir work around
    Logger.debug("App server directory {0} is empty.", directory);
}

return fileList;
}
```

<!-- document id=bb92d73f0516301ea4c4cbe6ea558cc33d027c9e77600dedc807dd869bbc5034 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-get-files-from-ftp-server-ds.md -->

# GetFilesFromFTPServer.ds

Review the GetFilesFromFTPServer.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```

/**
 * Connected to FTP server.
 *
 * @input Hostname   : String    The host name
 * @input Username   : String    The user name
 * @input Password   : String    The password
 * @input Directory  : String    The directory
 * @input sampleLogger  : Object Sample logger input for Sample logger
 * @output sampleLogger : Object Sample logger debug output for Sample logger
 * @output sampleError  : Object Sample error error output for Sample logger
 */
importPackage(dw.system);
importPackage(dw.net);



// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");



function execute(pdict: PipelineDictionary): Number {
    // Sample Logging var
    var _context: String = new Context("GetFilesFromFTPServer.ds");
    var _logger: Log = Log.getLogger(pdict);

    var scriptName: String = "bc_sample:pipelets/impex/GetFilesFromFTPServer.ds";

    if (Logger.isDebugEnabled()) {

        Logger.debug(scriptName + ": BEGIN");
    }

    //*** get script parameters ***//
    var host: String = pdict.Hostname;
    var userName: String = pdict.Username;
    var password: String = pdict.Password;

    var ftpClient: FTPClient = new FTPClient();
    var connectedFlag: Boolean = false;

    try {

        connectedFlag = ftpClient.connect(host, userName, password);
    } catch (e) {
        // Sample Logging wrap error into custom exception
        var exception: sampleException = new sampleException(_context, scriptName + ': Error connecting to FTP server: ' + +host + '\n' + e.message, e);

        // Sample Logging call into error handler
        _logger.error(_context, scriptName + ': Error connecting to FTP server: ' + +host + '\n' + e.message + exception);
        pdict.sampleError = exception;

        return PIPELET_ERROR;
    }

    if (connectedFlag) {

        if (Logger.isDebugEnabled()) {

            _logger.debug(_context, scriptName + ': Connected to host: ' + host);
        }

        try {

            /*var files = ftpClient.list();
   for each (var file : FTPFileInfo in files) {

    Logger.debug("---> " + file.name);
   }*/

            ftpClient.disconnect();

            if (Logger.isDebugEnabled()) {

                _logger.debug(_context, scriptName + ': Disconnected from host: ' + host);
            }
        } catch (e) {

            _logger.error(_context, scriptName + ': FTP opreration failed: ' + e.message);

            return PIPELET_ERROR;
        }
    } else {

        if (Logger.isDebugEnabled()) {

            _logger.debug(_context, scriptName + ': Could not connect to host: ' + host);
        }

        return PIPELET_ERROR;
    }

    //*** set script output parameters ***//


    if (Logger.isDebugEnabled()) {

        _logger.debug(_context, scriptName + ": END");
    }

    return PIPELET_NEXT;
}
```

<!-- document id=dde5b4fe5de8796aedf778e8a253f1df82fbae7f73ae217dae5bb72bd51b8263 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-get-files-from-http-server-ds.md -->

# GetFilesFromHttpServer.ds

Review the GetFilesFromHTTPServer.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/*
 * Gets a file list from an HTTP(S) server
 *
 * @input ConnectionUrl  : String    of the server URL including protocol
 * @input Login    : String    The login for authentication
 * @input Password   : String    The password for authentication
 * @input SortDirection  : String    'ASCENDING' or 'DESCENDING'
 * @input NamePattern   : String    The pattern for the filenames (use ".*" to get all)
 * @input ServerPath   : String    the directory path at the server
 * @input sampleLogger   : Object Sample logger input for Sample logger
 *
 * @output FileList   : dw.util.Collection  The files matching the pattern
 * @output StatusCode   : Number    The servers status code
 * @output StatusMessage  : String    The servers status message
 * @output sampleLogger  : Object Sample logger debug output for Sample logger
 * @output sampleError   : Object Sample error error output for Sample logger
 *
 */
importPackage( dw.system );
importPackage( dw.util );
importPackage( dw.net );
// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");
/*
*/
function execute( pdict : PipelineDictionary ) : Number {
 // Sample Logging var
 var _context : String = new Context("GetFilesFromHttpServer.ds");
 var _logger : Log = Log.getLogger(pdict);

 // constants for parsing
 var pattern_dir  : String ="/";
 var tag_a_href   : String = "<a";   //<a href="...
 var char_left   : String = '"';    // .....>file_name<...
 var char_right   : String = '"';
 // input variables
 // input variables
 var connectionURL   : String = pdict.ConnectionUrl;
 var login     : String = pdict.Login;
 var password    : String = pdict.Password;
 var sortDirection   : String = pdict.SortDirection;
 var pattern    : RegExp = new RegExp(pdict.NamePattern);
 var serverPath    : String = pdict.ServerPath;

 var httpSvc : HTTPClient = new HTTPClient();

 var url : String = connectionURL + serverPath;

 // get server response for directory
 httpSvc.open("POST",url); // old httpSvc.open("POST",url,login,password);
 try{
  httpSvc.send();
 }
 catch( e ){
  var exception : sampleException = new sampleException(_context, "Could not connect to remote resource {0}. ( {1} )",url,e);
  _logger.error(_context, "Could not connect to remote resource {0}. ( {1} )" + exception);
  pdict.sampleError = exception;

  return PIPELET_ERROR;
 }
 if(httpSvc.statusCode != 200){
  _logger.error(_context, "Server responded with Status code {0} ( {1} )!",httpSvc.statusCode,httpSvc.statusMessage);
  return PIPELET_ERROR;
 }else{
  _logger.debug(_context, "Successfully read directory listing of {0}.",url);
 }

 var response = httpSvc.text;

 _logger.debug(_context, "Content: " + response);
 var fileName : String = "";
 var sorted : SortedSet = ((sortDirection == "DESCENDING") ? new SortedSet(descending) :  new SortedSet());
 var line = response;

 // IIS HTML Format
 var line_pos : Number = 0;
 var index : String = line;
 var indexLowerCase : String = index.toLowerCase();

 //++line_count;
 while (line_pos != -1)
 {
  //find contents of <a...>needed_text</a>
  if ((line_pos = indexLowerCase.indexOf(tag_a_href, line_pos + 6)) != -1)
  {
   if ((line_pos = indexLowerCase.indexOf(char_left, line_pos + tag_a_href.length)) != -1)
   {
    var idx = indexLowerCase.indexOf(char_right, line_pos + 1);
    fileName = index.substring(line_pos + 1, idx);
    // Remove any directory from the filename
    if (fileName.lastIndexOf(pattern_dir) != -1 && fileName.lastIndexOf(pattern_dir) + 1 < fileName.length) {
     fileName = fileName.substring(fileName.lastIndexOf(pattern_dir) + 1);
    }

    _logger.debug(_context, "Found Filename '" + fileName + "'");

             if (idx != -1 && fileName.match(pattern) && fileName.substring(fileName.length - 1) != pattern_dir)
    {
     sorted.add(fileName);
    }
   }
  }
 }

 pdict.StatusCode = httpSvc.statusCode;
 pdict.StatusMessage = httpSvc.statusMessage;

 // if directory contains files, return them
 if ( !sorted.empty)
 {
     // store 'FileList' in pipeline dictionary
     pdict.FileList = sorted;

     return PIPELET_NEXT;
 }
 return PIPELET_ERROR;
}
function descending( var1 : Object, var2) : Number{
 if( var1 == var2) return 0
  else if ( var1 < var2) return -1
   else return 1;
}
```

<!-- document id=242520f18baa00dc486857f3ba1451d56825436578327da15f22bfb08781ccf8 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-get-imp-ex-processing-path-ds.md -->

# GetImpExProcessingPath.ds

Review the GetImpExProcessingPath.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/**
 * GetImpExProcessingPath.ds
 * Get the import processing path.
 *
 * @input TaskDirectoryName   : String  Task directory name
 * @input SiteID     : String  Site ID
 * @input FileName   : String  File name
 * @input ImpexRoot   : Boolean  Root directory is IMPEX [default: false]
 * @input FileExtension   : String  Processing File Extension [.processing]
 * @input sampleLogger    : Object  Sample logger
 * @output ImpExProcessing  : dw.io.File Import/Export processing file
 * @output ImpExProcessingPath : String  Import/Export processing file path
 * @output sampleLogger   : Object  Debug output for Sample logger
 * @output sampleError    : Object  Error output for Sample logger
 */
importPackage(dw.system);
importPackage(dw.io);
importPackage(dw.util);
// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");
function execute(pdict : PipelineDictionary) : Number {
 // Sample Logging var
 var _context : String = new Context("GetImpExProcessingPath.ds");
 var _logger : Log = Log.getLogger(pdict);

 // check for mandatory pipelet input parameters
 if(empty(pdict.TaskDirectoryName) || empty(pdict.SiteID) || empty(pdict.FileName)) {

  _logger.error(_context, "Mandatory pipelet input parameters are missing or null.");
  return PIPELET_ERROR;
 }

 // get site id
 var siteId : String = pdict.SiteID;

 // processing file extension
 var processingFileExtension : String = pdict.FileExtension;

 // impex file path
 var impexPath : String = File.IMPEX + File.SEPARATOR + 'src' + File.SEPARATOR;
 // IMPEX is root directory
 var impexRoot : Boolean = empty(pdict.ImpexRoot) || (pdict.ImpexRoot == false) ? false : true;
 _logger.debug(_context,"Impex Root: " + impexRoot + " -- Impex Root Dictionary Value: "+pdict.ImpexRoot);

 var rootPath : String = impexRoot ? impexPath  +  'datafeeds' : 'datafeeds';

 // site specific impex base path
 var impexBasePath : String = rootPath + File.SEPARATOR + siteId + File.SEPARATOR;
 _logger.debug(_context,"UNA: " + impexBasePath);

 // get import processing path
 var impexProcessingPath : String = impexBasePath + pdict.TaskDirectoryName + File.SEPARATOR + 'processing' + File.SEPARATOR + pdict.FileName;
 if(!empty(processingFileExtension)) {

  impexProcessingPath += processingFileExtension;
 }

 _logger.debug(_context,"Processing Path: " + impexProcessingPath);

 var filePath = impexPath + siteId + File.SEPARATOR + pdict.TaskDirectoryName + File.SEPARATOR + 'processing' + File.SEPARATOR + pdict.FileName;
 _logger.debug(_context,"File Path: " + filePath);

 try {

  pdict.ImpExProcessing  = new File(filePath);
  pdict.ImpExProcessingPath = impexProcessingPath;
 }
 catch(e) {
  var exception : sampleException = new sampleException(_context, "Error occurred while creating ImpEx processing file", e);
  pdict.sampleError = exception;
  return PIPELET_ERROR;
 }
 return PIPELET_NEXT;
}
```

<!-- document id=ae88dbd7a534d69fd0a4f4c2d3cf90bd12e890071fa2f9b09b9c6ac1631b0553 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-get-unzip-ds.md -->

# GetUnzip.ds

Review the GetUnzip.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/**
 * GetUnzip.ds
 *
 * Unzip a file.
 *
 * @input ZIPFileName    : String  The file name of the .zip file
 * @input SourceDirectory : dw.io.File    The processing directory where the file is located
 * @input sampleLogger  : Object  Sample logger
 * @output UnzipDirectory : dw.io.File    The unzip directory where the extracted import file is located
 * @output ZIPFile  : dw.io.File The .zip file
 * @output sampleLogger  : Object  Sample logger
 * @output sampleError  : Object  Sample error
 */
importPackage(dw.system);
importPackage(dw.io);
importScript("bc_sample:library/impex/libImpExConstants.ds");
// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");
function execute(pdict : PipelineDictionary) : Number {
 var _context : String = new Context("GetUnzip.ds");
 var _logger : Log = Log.getLogger(pdict);

 var sourceDirectory : File = pdict.SourceDirectory;
 var zipFileName : String = pdict.ZIPFileName;

 var sourceFile : File = new File(sourceDirectory, zipFileName);
 var targetFile : File = new File(File.TEMP + File.SEPARATOR + 'IMPEX_UNZIP' + File.SEPARATOR + zipFileName);
 var zipFile : File  = new File(sourceDirectory, zipFileName);

 var unzipDirectory : File = new File(File.TEMP + File.SEPARATOR + 'IMPEX_UNZIP' + File.SEPARATOR + zipFileName);
 unzipDirectory.mkdirs();

 var fileExtension : String = sourceFile.name.substring(sourceFile.name.length-4, sourceFile.name.length);

 if (!sourceFile.exists()) {
  _logger.error(_context, "Source file '" + sourceFile.name + "' in path '" + sourceFile.path + "' cannot be found!");
  return PIPELET_ERROR;
 }

 // check for file extension .zip
 if ((fileExtension == '.zip') || (fileExtension == '.ZIP')) {

  try {

   sourceFile.unzip(targetFile);
   pdict.UnzipDirectory = unzipDirectory;
   pdict.ZIPFile = zipFile;
  }
  catch (e) {

   var exception : sampleException = new sampleException(_context, "Error occurred calling unzip: ", e);
   _logger.error(_context, "Error occurred calling unzip: " + exception);
   pdict.sampleError = exception;

   return PIPELET_ERROR;
  }

  return PIPELET_NEXT;
 }

 _logger.info(_context, "No .zip file :" + zipFile.name);
 return PIPELET_NEXT;
}
```

<!-- document id=f30d8eaaa839f91df5012afca84c5f28d2e867ccc0d5cb5f0d4ec7348036251c url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/gift-card-spi.md -->

Gift Card SPI

# Gift Card SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-card-spi/gift-card-spi-oas-public.yaml)

Merchant SPI to perform gift card operations via a customer-managed provider adapter. Enables retailers to integrate any gift card provider without Point of Sale engineering involvement.

APIs include balance check, card activation, loading funds, redemption, and void/reversal.

### Configuration

1.  **Store Management** > **Integration** > **Custom API Connectors** > **Create**
    *   **API KEY:** GIFT\_CARD\_SERVICE with authentication details and URL Base.
    *   All the APIs defined below will use this URL base; only the operation-specific path suffix will change.
2.  Set **Store Management** > **Integration** > **Gift Card** > **Service** to `SPI`
3.  **Store Management** > **Integration** > **Gift Card** > **PIN Setting** controls whether cardPin is required or optional in requests.

**Version:** 2.3.4

## Tags

### Gift Card SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-card-spi/gift-card-spi-oas-public.yaml)

Merchant SPI to perform gift card operations via a customer-managed provider adapter. Enables retailers to integrate any gift card provider without Point of Sale engineering involvement.

APIs include balance check, card activation, loading funds, redemption, and void/reversal.

### Configuration

1.  **Store Management** > **Integration** > **Custom API Connectors** > **Create**
    *   **API KEY:** GIFT\_CARD\_SERVICE with authentication details and URL Base.
    *   All the APIs defined below will use this URL base; only the operation-specific path suffix will change.
2.  Set **Store Management** > **Integration** > **Gift Card** > **Service** to `SPI`
3.  **Store Management** > **Integration** > **Gift Card** > **PIN Setting** controls whether cardPin is required or optional in requests.

## Operations

### POST Activate Gift Card

`POST /merchant/spi/sample/endpoint/spiGiftCard/activateGiftCard`

Operation ID: `activateGiftCard`. Tags: Gift Card SPI.

Activates a new or inactive gift card at the provider with the specified amount. Called when a store associate sells a new gift card or issues a refund to a new card (step 1 of a two-step flow). The response `cardNumber` should echo back the card number from the request. The `providerTransactionId` returned must be stored by the platform and passed back in any subsequent void request. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardActivateRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardActivateResponse`.
    

### POST Add Balance to Gift Card

`POST /merchant/spi/sample/endpoint/spiGiftCard/addBalance`

Operation ID: `addBalance`. Tags: Gift Card SPI.

Loads funds onto an existing active gift card. Used during gift card purchase (step 2 after activation) or when issuing a refund to an existing card. The `providerTransactionId` returned must be stored by the platform and passed back in any subsequent void request. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardAddBalanceRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardAddBalanceResponse`.
    

### POST Check Gift Card Balance

`POST /merchant/spi/sample/endpoint/spiGiftCard/checkBalance`

Operation ID: `checkBalance`. Tags: Gift Card SPI.

Checks the current balance and active status of a gift card. This single endpoint serves two platform operations:

*   **getBalance()** — platform reads `balance` and `cardNumber` from the response
*   **isInactive()** — platform reads `isActive` from the response The response must always include both `balance` and `isActive` so either operation can be served. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardBalanceRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardBalanceResponse`.
    

### POST Redeem Gift Card

`POST /merchant/spi/sample/endpoint/spiGiftCard/redeemGiftCard`

Operation ID: `redeemGiftCard`. Tags: Gift Card SPI.

Deducts funds from a gift card. Used for two scenarios:

*   **Payment tender** — deducts the requested amount during checkout
*   **Cash out** — platform validates the balance is at or below the configured threshold, then calls this endpoint with the full balance to bring the card to $0 On success (no errorCode), the full requested amount is redeemed. Partial redemption is not supported. The `providerTransactionId` is stored as the capture token and the `providerReferenceId` is stored as the requestId on the tender — both are required for reconciliation and void operations. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardRedeemRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardRedeemResponse`.
    

### POST Void Gift Card Transaction

`POST /merchant/spi/sample/endpoint/spiGiftCard/voidGiftCard`

Operation ID: `voidGiftCard`. Tags: Gift Card SPI.

Reverses a previous gift card operation (redeem or addBalance). Called when an order fails after a gift card charge was captured, or when an explicit reversal is needed. The `originalProviderTransactionId` in the request must match the `providerTransactionId` returned by the original operation so the provider can identify which transaction to reverse. The `amount` must match the `approvedAmount` from the original operation. The `providerReferenceId` returned is stored by the platform as the paymentReversalRequestId on the tender. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardVoidRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardVoidResponse`.
    

## Schemas

### SpiGiftCardActivateRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Activation amount (gift card purchase price); non-negative.

### SpiGiftCardActivateResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations.
*   `error` (_boolean_)

### SpiGiftCardAddBalanceRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Amount to load onto the card; non-negative.

### SpiGiftCardAddBalanceResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations.
*   `error` (_boolean_)

### SpiGiftCardBalanceRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.

### SpiGiftCardBalanceResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `isActive` (_boolean_) True if the card is active and usable; defaults to true.
*   `cardNumber` (_string_) Echoed card number from the request.
*   `error` (_boolean_)

### SpiGiftCardRedeemRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Amount to deduct from the card; non-negative.

### SpiGiftCardRedeemResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations.
*   `providerReferenceId` (_string_, required) Provider's reference identifier; stored by platform as requestId on the tender for reconciliation.
*   `error` (_boolean_)

### SpiGiftCardVoidRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Amount to reverse; must match the approvedAmount from the original operation.
*   `originalProviderTransactionId` (_string_, required) Provider's transaction identifier from the original operation being voided.

### SpiGiftCardVoidResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `providerReferenceId` (_string_, required) Provider's reference identifier for the void; stored by platform as paymentReversalRequestId.
*   `error` (_boolean_)

<!-- document id=b1673f0134d4ba606e7051c36d03add3ea74a53d6907fefe859d7a0bab11f837 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/gift-certificates.md -->

Gift Certificates

# Gift Certificates

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/gift-certificates/gift-certificates-oas-v1-public.yaml)

## API Overview

Use the Gift Certificates API to create, update, and delete gift certificates, so that your storefront customers can purchase and redeem gift certificates.

### Authentication & Authorization

The client requesting the gift certificate information must have access to the Gift Certificates resource. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account Manager to log in.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Capture All Gift Certificates

Retrieve all gift certificates for a site with no filtering.

#### Capture Specific Gift Certificates

Retrieve a specific gift certificate for a site using a merchant ID.

#### Create Site Specific Gift Certificates

Create and issue site-specific gift certificates with information such as amount, description, status, recipient email, recipient name, sender name, and so on.

#### Update Gift Certificates

Update a gift certificate with specified information using a merchant ID.

### Related APIs

*   [Shopper Gift Certificates](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-gift-certificates?meta=Summary) — Retrieve gift certificate details for shoppers.

**Version:** 1.0.43

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/gift-certificates/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.gift-certificates: gift certificate READONLY
    *   Scope sfcc.gift-certificates.rw: gift certificate read/write
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### PUT Create a gift certificate using the information provided.

`PUT /organizations/{organizationId}/gift-certificates`

Operation ID: `createGiftCertificate`. Security: AmOAuth2 (sfcc.gift-certificates.rw).

If an existing identifier is specified, the gift certificate with that unique identifier is deleted and a new one is created.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `GiftCertificate`.

_Example: Gift-Certificates_

```
{
  "amount": {
    "currencyMnemonic": "USD",
    "value": 1000
  },
  "description": "Birthday gift",
  "message": "A birthday present to you",
  "senderName": "Jane Doe",
  "recipientName": "John Doe",
  "recipientEmail": "john.doe@gmail.com",
  "status": "issued",
  "orderNo": "CA17293",
  "enabled": false
}
```

#### Responses

*   **200** Successfully created the gift certificate.
    
    Media type: `application/json`. Schema: `GiftCertificate`.
    
    _Example: CreateGiftCertificateSuccess_
    
    ```
    {
      "amount": {
        "currencyMnemonic": "USD",
        "value": 100
      },
      "balance": {
        "currencyMnemonic": "USD",
        "value": 100
      },
      "creationDate": "2015-07-31T14:36:17.544Z",
      "description": "Birthday gift",
      "enabled": false,
      "maskedGiftCertificateCode": "************KTIP",
      "merchantId": "NorthernTrailOutfitters",
      "message": "A birthday gift for you",
      "orderNo": "CA17293",
      "recipientName": "John Doe",
      "recipientEmail": "john.doe@gmail.com",
      "senderName": "Jane Doe",
      "status": "issued",
      "transactions": [
        {
          "amount": {
            "currencyMnemonic": "EUR",
            "value": 80
          },
          "orderNo": "my-order_no",
          "timestamp": "2015-09-09T17:16:12.066Z",
          "typeCode": "create"
        }
      ]
    }
    ```
    
*   **400**
    
    Potential reasons:
    
    *   Returned when the merchant ID is not unique.
    *   Returned when the specified gift certificate status is invalid.
    *   Returned when the specified gift certificate is not valid (the argument indicates the field that was invalid).
    *   Returned when the specified amount is out of range.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidRecipientEmail400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-recipient-email",
      "title": "Invalid Recipient Email Exception",
      "detail": "Invalid recipient email ID provided."
    }
    ```
    
    _Example: InvalidStatus400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-status",
      "title": "Invalid Gift Certificate Status Exception",
      "detail": "Invalid gift certificate status provided."
    }
    ```
    
    _Example: Invalid400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid",
      "title": "Invalid Gift Certificate Exception",
      "detail": "Invalid gift certificate provided."
    }
    ```
    
    _Example: MerchantIdNotUnique400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/merchant-id-not-unique",
      "title": "Gift Certificate Create Merchant Id Not Unique Exception",
      "detail": "Merchant id is not unique."
    }
    ```
    
*   **404** Returned when the gift certificate does not exist or does not match the specified merchant ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: createGiftCertificate404_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "title": "Gift Certificate Not Found Exception",
      "detail": "No gift certificate with merchant ID 'my-merchant_id' for site 'TestWapi' was found."
    }
    ```
    

### POST Search for gift certificates.

`POST /organizations/{organizationId}/gift-certificates`

Operation ID: `giftCertificatesSearch`. Security: AmOAuth2 (sfcc.gift-certificates, sfcc.gift-certificates.rw).

Use the following searchable query attributes to narrow the search:

| Attribute | Type | Sortable |
| --- | --- | --- |
| merchantId | String | yes |
| maskedGiftCertificateCode \* | String | no |
| orderNo | String | yes |
| senderName | String | yes |
| recipientName | String | yes |
| recipientEmail | String | yes |
| status | String | yes |
| enabled | Boolean | yes |
| message | String | yes |
| description | String | yes |
| creationDate | Date | yes |
| currencyMnemonic \*\* | String | yes |

### Notes:

*   \*`maskedGiftCertificateCode`, also known as just code, can only be used in a term query. If a four-character code is supplied, it is assumed that the search is on the unmasked portion of the code. Otherwise, the full code must be matched. Text queries are not allowed.
*   \*\*`currencyMnemonic` can only be joined with other attributes using a conjunction (`AND`).
*   Only searchable attributes can be used in sorting.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SearchRequest`.

#### Responses

*   **200** Successfully returned the gift certificate information.
    
    Media type: `application/json`. Schema: `GiftCertificateSearchResult`.
    
    _Example: GiftCertificatesSearchSuccess_
    
    ```
    {
      "limit": 3,
      "hits": [
        {
          "amount": {
            "currencyMnemonic": "USD",
            "value": 100
          },
          "balance": {
            "currencyMnemonic": "USD",
            "value": 100
          },
          "creationDate": "2015-07-31T15:10:25.192Z",
          "description": "Birthday Gift",
          "enabled": true,
          "maskedGiftCertificateCode": "************HHHZ",
          "merchantId": "NorthernTrailOutfitters",
          "orderNo": "CA17293",
          "status": "pending",
          "transactions": [
            {
              "amount": {
                "currencyMnemonic": "EUR",
                "value": 80
              },
              "orderNo": "CA17293",
              "timestamp": "2015-01-09T17:16:12.066Z",
              "typeCode": "create"
            }
          ]
        },
        {
          "amount": {
            "currencyMnemonic": "USD",
            "value": 100
          },
          "balance": {
            "currencyMnemonic": "USD",
            "value": 100
          },
          "creationDate": "2015-07-31T15:03:21.988Z",
          "enabled": true,
          "maskedGiftCertificateCode": "************DOIZ",
          "merchantId": "my-merchant_id",
          "orderNo": "00000002",
          "status": "pending",
          "transactions": [
            {
              "amount": {
                "currencyMnemonic": "EUR",
                "value": 80
              },
              "orderNo": "00000002",
              "timestamp": "2015-02-09T17:16:12.066Z",
              "typeCode": "create"
            }
          ]
        },
        {
          "amount": {
            "currencyMnemonic": "USD",
            "value": 100
          },
          "balance": {
            "currencyMnemonic": "USD",
            "value": 100
          },
          "creationDate": "2015-07-31T15:10:00.659Z",
          "description": "Promotion Gift",
          "enabled": true,
          "maskedGiftCertificateCode": "************GSPZ",
          "merchantId": "NorthernTrailOutfitters",
          "orderNo": "00000003",
          "status": "pending",
          "transactions": [
            {
              "amount": {
                "currencyMnemonic": "EUR",
                "value": 80
              },
              "orderNo": "00000003",
              "timestamp": "2015-09-09T17:16:12.066Z",
              "typeCode": "create"
            }
          ]
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "status"
          ],
          "searchPhrase": "pending"
        }
      },
      "offset": 0,
      "total": 3
    }
    ```
    
*   **400**
    
    Potential reasons:
    
    *   Returned when the given query field cannot be queried.
    *   Returned when the query is malformed.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: UnqueryableField400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "title": "Unqueryable Field Exception",
      "detail": "Given field cannot be queried. For example - The field 'link' is unqueryable."
    }
    ```
    
    _Example: MalformedSearchParameter400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-search-parameter",
      "title": "Malformed Search Parameter Exception",
      "detail": "An error occurred while decoding the request, the body was 'malformed'."
    }
    ```
    

### GET getGiftCertificate

`GET /organizations/{organizationId}/gift-certificates/{merchantId}`

Operation ID: `getGiftCertificate`. Security: AmOAuth2 (sfcc.gift-certificates, sfcc.gift-certificates.rw).

Retrieve gift certificate information for a specified merchant ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `merchantId` (path, string, required) The merchant ID of the requested gift certificate.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Successfully retrieved the gift certificate information for the specified merchant ID.
    
    Media type: `application/json`. Schema: `GiftCertificate`.
    
    _Example: GetGiftCertificateSuccess_
    
    ```
    {
      "amount": {
        "currencyMnemonic": "USD",
        "value": 100
      },
      "balance": {
        "currencyMnemonic": "USD",
        "value": 100
      },
      "creationDate": "2015-07-31T14:56:38.936Z",
      "description": "Birthday Gift",
      "enabled": true,
      "maskedGiftCertificateCode": "************LKWJ",
      "merchantId": "NorthernTrailOutfitters",
      "message": "A birthday gift for you",
      "orderNo": "CA17293",
      "recipientName": "John Doe",
      "recipientEmail": "john.doe@gmail.com",
      "senderName": "Jane Doe",
      "status": "issued",
      "transactions": [
        {
          "amount": {
            "currencyMnemonic": "EUR",
            "value": 80
          },
          "orderNo": "CA17293",
          "timestamp": "2015-09-09T17:16:12.066Z",
          "typeCode": "create"
        }
      ]
    }
    ```
    
*   **404** Returned when the gift certificate does not exist or does not match the specified merchant ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example createGiftCertificate404: same as PUT /organizations/{organizationId}/gift-certificates 404 response._
    

### DELETE Delete gift certificate information for a specified merchant ID.

`DELETE /organizations/{organizationId}/gift-certificates/{merchantId}`

Operation ID: `deleteGiftCertificate`. Security: AmOAuth2 (sfcc.gift-certificates.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `merchantId` (path, string, required) The merchant ID of the requested gift certificate.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Successfully deleted the gift certificate information for the specified merchant ID.

### PATCH Update gift certificate information for a specified merchant ID.

`PATCH /organizations/{organizationId}/gift-certificates/{merchantId}`

Operation ID: `updateGiftCertificate`. Security: AmOAuth2 (sfcc.gift-certificates.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `merchantId` (path, string, required) The merchant ID of the requested gift certificate.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `GiftCertificate`.

_Example: Gift-Certificates_

```
{
  "description": "Birthday Gift",
  "enabled": false,
  "message": "A birthday gift for you",
  "recipientEmail": "john.doe@gmail.com",
  "recipientName": "John Doe",
  "senderName": "Jane Doe",
  "status": "pending"
}
```

#### Responses

*   **200** Successfully updated the gift certificate information for the specified merchant ID.
    
    Media type: `application/json`. Schema: `GiftCertificate`.
    
    _Example: updateGiftCertificateSuccess_
    
    ```
    {
      "amount": {
        "currencyMnemonic": "USD",
        "value": 100
      },
      "balance": {
        "currencyMnemonic": "USD",
        "value": 100
      },
      "creationDate": "2015-07-31T15:05:52.311Z",
      "description": "Birthday Gift",
      "enabled": false,
      "maskedGiftCertificateCode": "***********cate",
      "merchantId": "NorthernTrailOutfitters",
      "message": "A birthday gift for you",
      "orderNo": "CA17293",
      "recipientEmail": "john.doe@gmail.com",
      "recipientName": "John Doe",
      "senderName": "Jane Doe",
      "status": "pending",
      "transactions": [
        {
          "amount": {
            "currencyMnemonic": "EUR",
            "value": 80
          },
          "orderNo": "CA17293",
          "timestamp": "2015-09-09T17:16:12.066Z",
          "typeCode": "create"
        }
      ]
    }
    ```
    
*   **400**
    
    Potential reasons:
    
    *   Returned when the recipient email address is invalid.
    *   Returned when the specified gift certificate status is invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example InvalidRecipientEmail400: same as PUT /organizations/{organizationId}/gift-certificates 400 response._
    
    _Example InvalidStatus400: same as PUT /organizations/{organizationId}/gift-certificates 400 response._
    
*   **404** Returned when the gift certificate does not exist or does not match the specified merchant ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example createGiftCertificate404: same as PUT /organizations/{organizationId}/gift-certificates 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### GiftCertificate

Document representing a gift certificate.

*   `amount` (_object_) The gift certificate amount. The user cannot change the gift certificate amount after the creation of the gift certificate.
    
    Includes all fields of `Money`.
    
*   `balance` (_object_) The gift certificate balance. This is a computed attribute and cannot be modified.
    
    Includes all fields of `Money`.
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `1578516896.641`.
*   `description` (_string_) The description of the gift certificate.  
    Maximum length: 4000. Example: `A gift certificate for birthday.` .
*   `enabled` (_boolean_) The enabled flag of the gift certificate.  
    Example: `true`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `1578516896.641`.
*   `maskedGiftCertificateCode` (_string_) Masked code.  
    Example: `*******XQTY`.
*   `merchantId` (_string_) The merchant ID of the gift certificate. This is a unique attribute. This is a computed attribute and cannot be modified. This is used to get, update and the delete gift certificates.  
    Example: `Macy's1256489` .
*   `message` (_string_) The message to the recipient of the gift certificate.  
    Maximum length: 4000. Example: `This gift certificate is to be given as birthday present` .
*   `orderNo` (_string_) The order number of the gift certificate.  
    Example: `MyOrder5421` .
*   `recipientEmail` (_string_) The email address of the recipient of the gift certificate.  
    Example: `my-recipient-email@gmail.com` .
*   `recipientName` (_string_) The recipient of the gift certificate.  
    Maximum length: 256. Example: `Jane Doe` .
*   `senderName` (_string_) The sender of the gift certificate.  
    Maximum length: 256. Example: `John Smith` .
*   `status` (_string_) The status of the gift certificate. While creating a gift certificate, user can set the status to either "pending" or "issued" only.  
    Allowed values: `issued`, `partially_redeemed`, `pending`, `redeemed`. Example: `issued`.
*   `transactions` (_array of AccountTransaction_) The transactions of the gift certificate.
    
    _Example_
    
    ```
    [
      {
        "amount": {
          "currencyMnemonic": "USD",
          "value": 1000
        },
        "orderNo": "my-test-order_no",
        "timestamp": "2020-01-08T20:54:56.644Z",
        "typeCode": "create"
      }
    ]
    ```
    

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### GiftCertificateSearchResult

Document representing a gift certificate search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of GiftCertificate_, required)

### Money

A combination of a Currency and an amount of that Currency.

*   `currencyMnemonic` (_CurrencyCode_)
*   `value` (_number (double)_) The amount of money for the given currency.  
    Example: `1234.56`.

### AccountTransaction

Document representing an account transaction.

*   `amount` (_Money_, required)
*   `orderNo` (_string_, required) The order number of the gift certificate.  
    Example: `my-order-43128`.
*   `timestamp` (_string (date-time)_, required) The timestamp of the transaction of the gift certificate.  
    Example: `1578516896.641`.
*   `typeCode` (_string_, required) The type code of the gift certificate.  
    Allowed values: `create`, `redeem`, `delete`, `enable`, `disable`. Example: `redeem`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=b0822f0e1dd7b48beb939bd4d9f92f13f1646faa7e310b590d5c1f7ad5feec52 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/gift-registry-spi.md -->

Gift Registry SPI

# Gift Registry SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-registry-spi/gift-registry-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for POS to perform Gift registry actions such as registry lookup, buy / return registry items.

Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**.

Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    
    *   **API Key:** `GIFT_REGISTRY`
    *   **API Endpoint:** Provide the common external endpoint for registry APIs, for example: [https://sample/external/endpoint/giftregistry](https://sample/external/endpoint/giftregistry)
2.  Under **JSON Config**:
    
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: `{"Content-Type":"application/json","client_id":"myClientId","client_secret":"myClientSecret"}`

Merchant to implement below APIs and use the same ending keyword for the individual APIs.

**Version:** 2.3.4

## Tags

### Gift Registry SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-registry-spi/gift-registry-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for POS to perform Gift registry actions such as registry lookup, buy / return registry items.

Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**.

Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    
    *   **API Key:** `GIFT_REGISTRY`
    *   **API Endpoint:** Provide the common external endpoint for registry APIs, for example: [https://sample/external/endpoint/giftregistry](https://sample/external/endpoint/giftregistry)
2.  Under **JSON Config**:
    
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: `{"Content-Type":"application/json","client_id":"myClientId","client_secret":"myClientSecret"}`

Merchant to implement below APIs and use the same ending keyword for the individual APIs.

## Operations

### GET Retrieve products for registry ID.

`GET /merchant/spi/sample/endpoint/giftregistry/{identifier}`

Operation ID: `getRegistryProducts`. Tags: Gift Registry SPI.

Retrieve the list of all products belonging to the particular registry ID. The list is available for the customer to select from. The identifier is the registryId, which is a path parameter.

#### Parameters

*   `identifier` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiRegistryDetailResponse`.
    

### POST Return gift registry product.

`POST /merchant/spi/sample/endpoint/giftregistry/returnRegistryItem`

Operation ID: `searchGiftRegistry`. Tags: Gift Registry SPI.

Retrieve a gift registry product based on the registryId, productId, and quantity passed in the request, which can be added to cart to initiate the NRR flow.

#### Request body

Media type: `application/json`. Schema: `ReturnRegistryRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiRegistryReturnResponse`.
    

### POST Search gift registries.

`POST /merchant/spi/sample/endpoint/giftregistry/searchRegistries`

Operation ID: `searchGiftRegistry_1`. Tags: Gift Registry SPI.

Fetch the list of gift registries from the external system based on the search criteria, allowing customers to select products from the registry to add to the order. Please provide one or more query parameters.

#### Request body

Media type: `application/json`. Schema: `SearchRegistryRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiGiftRegistryResponse`.
    

## Schemas

### SpiRegistryDetailResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `registryId` (_string_, required) The unique ID of the registry.
*   `firstName` (_string_, required) The First name of the Registrant.
*   `lastName` (_string_, required) The last name of the Registrant.
*   `coRegistrantName` (_string_, nullable) The Co-Registrant name for the registry if available.
*   `eventType` (_string_, required) The event type for which the registry was created. For example, Wedding, Engagement, Housewarming.
*   `eventDate` (_integer (int64)_, required) The event date in epoch milliseconds, to be shown in a suitable format on the app.
*   `preEventAddress` (_SPIAddress_, required)
*   `postEventAddress` (_SPIAddress_, required)
*   `productList` (_array of SpiRegistryProduct_, required) The list of gift products that are present with this registry, with all the availability details.
*   `error` (_boolean_)

### ReturnRegistryRequest

*   `registryId` (_string_, required) The unique ID of the registry.
*   `productId` (_string_, required) Product Identifier.
*   `gtin` (_string_, nullable) Item's GTIN, alternate field to product ID.
*   `storeId` (_string_, nullable) Store ID of the current store.
*   `quantity` (_integer (int32)_, required) Quantity of the product to be returned. The response returns an error if the requested quantity isn't available.  
    Default: `1`.

### SpiRegistryReturnResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `items` (_array of RegistryLineItem_, required) The list of line items corresponding to the product Id sent in request, where each line can be of differing prices, quantities, belonging to different orders.
*   `error` (_boolean_)

### SearchRegistryRequest

*   `registryId` (_string_, nullable) The unique ID of the registry.
*   `firstName` (_string_, nullable) The First name of the Registrant.
*   `lastName` (_string_, nullable) The last name of the Registrant.
*   `storeId` (_string_, nullable) Store ID of the current store.
*   `email` (_string_, nullable) The email ID of the registrant.
*   `phone` (_string_, nullable) The Phone number of the Registrant.

### SpiGiftRegistryResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `giftRegistries` (_array of GiftRegistry_, required) The list of gift registries matching the search.
*   `error` (_boolean_)

### SPIAddress

The full address of the destination of transaction.

*   `firstName` (_string_) Customer first name saved for address.
*   `lastName` (_string_) Customer last name saved for address.
*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.
*   `phone` (_string_) Phone.
*   `storeId` (_string_) Store ID if it is store address.
*   `emailAddress` (_string_) Customer Email Address.

### SpiRegistryProduct

The list of gift products that are present with this registry, with all the availability details.

*   `productId` (_string_, required) Product Identifier.
*   `quantityWanted` (_integer (int32)_, required) The quantity of this item that the registrant is looking for.
*   `quantityPurchased` (_integer (int32)_, required) Quantity of the item that have already been purchased as a gift.
*   `preEventAvailability` (_boolean_, required) Flag indicating whether item is available for Ship to the Pre event address.
*   `postEventAvailability` (_boolean_, required) Flag indicating whether item is available for Ship to the Post event address.
*   `inStoreAvailability` (_boolean_, required) Flag indicating whether item is available to take with / In Store order.
*   `quantity` (_integer (int32)_, required) Quantity of the product that is available to purchase.

### RegistryLineItem

The list of line items corresponding to the product Id sent in request, where each line can be of differing prices, quantities, belonging to different orders.

*   `eligibleForReturn` (_boolean_, required) Flag to indicate whether product is eligible for return.
*   `productId` (_string_, required) Product Identifier.
*   `price` (_number_, required) Product price inclusive of quantity.
*   `quantity` (_integer (int32)_, required) Quantity of the product.
*   `taxAmount` (_number_, required) Tax amount inclusive of quantity.
*   `externalReferenceId` (_string_, required) The orderId or reference ID associated with the registry item being returned. Pass this when adding the item to the cart for NRR.

### GiftRegistry

The list of gift registries matching the search.

*   `imageUrl` (_string_, required) The URL of the image to be shown along with the Registry details.
*   `registryId` (_string_, required) The unique ID of the registry.
*   `firstName` (_string_, required) The First name of the Registrant.
*   `lastName` (_string_, required) The last name of the Registrant.
*   `coRegistrantName` (_string_, nullable) The Co-Registrant name for the registry if available.
*   `state` (_string_, required) The state where the event is taking place.
*   `eventType` (_string_, required) The event type for which the registry was created. For example, Wedding, Engagement, Housewarming.
*   `eventDate` (_integer (int64)_, required) The event date in epoch milliseconds, to be shown in a suitable format on the app.

<!-- document id=ba414cd179b324997af41d50bbf5fc92b1bc88c1cb7925a120c9a8edc69349a5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/globaljobs.md -->

# Global Jobs

There are several global jobs you can use.

## Full Active Data Index Update

This job builds all active-data-related search indexes for the given site scope

| Job Value         | Description                                                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-active-data-full-update/executions` |
| Request Document  | [SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/searchindexupdateconfiguration.md)                                  |
| Response Document | JobExecution                                                                                         |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-active-data-full-update/executions|
|Request Document|[SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/searchindexupdateconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

Faults

| Status | Type                                 | Arguments                      | Description                                                                                                     |
| ------ | ------------------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| 400    | `MissingSiteScopeParameterException` |                                | if the site scope parameter is missing                                                                          |
| 400    | `InvalidSiteScopeParameterException` | siteScopeValue (String)        | if the site scope parameter is empty or contains an invalid site id                                             |
| 400    | `JobAlreadyRunningException`         | jobId (String)                 | if a full active data index update job is already running for any other site scope                              |
| 403    | `UserAccessForbiddenException`       | method (String), path (String) | if the user doesn't have permission to build active-data-related search indexes for all sites of the site scope |

## Full Content Index Update

This job builds all content related search indexes for the given site scope

| Job Value         | Description                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-content-full-update/executions` |
| Request Document  | [SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/searchindexupdateconfiguration.md)                              |
| Response Document | JobExecution                                                                                     |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-content-full-update/executions|
|Request Document|[SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/searchindexupdateconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

Faults

| Status | Type                                 | Arguments                      | Description                                                                                                 |
| ------ | ------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| 400    | `MissingSiteScopeParameterException` |                                | if the site scope parameter is missing                                                                      |
| 400    | `InvalidSiteScopeParameterException` | siteScopeValue (String)        | if the site scope parameter is empty or contains an invalid site id                                         |
| 400    | `JobAlreadyRunningException`         | jobId (String)                 | if a full content index update job is already running for any other site scope                              |
| 403    | `UserAccessForbiddenException`       | method (String), path (String) | if the user doesn't have permission to build content related search indexes for all sites of the site scope |

## Full Product Index Update

This job builds all product-related search indexes for the given site scope

| Job Value         | Description                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-product-full-update/executions` |
| Request Document  | [SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/searchindexupdateconfiguration.md)                              |
| Response Document | JobExecution                                                                                     |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-product-full-update/executions|
|Request Document|[SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/searchindexupdateconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

Faults

| Status | Type                                 | Arguments                      | Description                                                                                                 |
| ------ | ------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| 400    | `MissingSiteScopeParameterException` |                                | if the site scope parameter is missing                                                                      |
| 400    | `InvalidSiteScopeParameterException` | siteScopeValue (String)        | if the site scope parameter is empty or contains an invalid site id                                         |
| 400    | `JobAlreadyRunningException`         | jobId (String)                 | if a full product index update job is already running for any other site scope                              |
| 403    | `UserAccessForbiddenException`       | method (String), path (String) | if the user doesn't have permission to build product-related search indexes for all sites of the site scope |

Incremental Active Data Index Update

This job updates all active-data-related search indexes for the given site scope

| Job Value         | Description                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-active-data-incremental-update/executions` |
| Request Document  | [SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/searchindexupdateconfiguration.md)                                         |
| Response Document | JobExecution                                                                                                |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-active-data-incremental-update/executions|
|Request Document|[SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/searchindexupdateconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

Faults

| Status | Type                                 | Arguments                      | Description                                                                                          |
| ------ | ------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| 400    | `MissingSiteScopeParameterException` |                                | if the site scope parameter is missing                                                               |
| 400    | `InvalidSiteScopeParameterException` | siteScopeValue (String)        | if the site scope parameter is empty or contains an invalid site id                                  |
| 400    | `JobAlreadyRunningException`         | jobId (String)                 | if an incremental active data index update job is already running for any other site scope           |
| 403    | `UserAccessForbiddenException`       | method (String), path (String) | if the user doesn't have permission to update active-data-related search indexes for all given sites |

## Incremental Content Index Update

This job updates all content-related search indexes for the given site scope

| Job Value         | Description                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-content-incremental-update/executions` |
| Request Document  | [SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/searchindexupdateconfiguration.md)                                     |
| Response Document | JobExecution                                                                                            |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-content-incremental-update/executions|
|Request Document|[SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/searchindexupdateconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

Faults

| Status | Type                                 | Arguments                      | Description                                                                                                 |
| ------ | ------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| 400    | `MissingSiteScopeParameterException` |                                | if the site scope parameter is missing                                                                      |
| 400    | `InvalidSiteScopeParameterException` | siteScopeValue (String)        | if the site scope parameter is empty or contains an invalid site id                                         |
| 400    | `JobAlreadyRunningException`         | jobId (String)                 | if an incremental content index update job is already running for any other site scope                      |
| 403    | `UserAccessForbiddenException`       | method (String), path (String) | if the user doesn't have permission to build content related search indexes for all sites of the site scope |

## Incremental Product Index Update

This job updates all product-related search indexes for the given site scope

| Job Value         | Description                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------- |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-content-incremental-update/executions` |
| Request Document  | [SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/searchindexupdateconfiguration.md)                                     |
| Response Document | JobExecution                                                                                            |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-search-index-content-incremental-update/executions|
|Request Document|[SearchIndexUpdateConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/searchindexupdateconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

Faults

| Status | Type                                 | Arguments                      | Description                                                                                                 |
| ------ | ------------------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| 400    | `MissingSiteScopeParameterException` |                                | if the site scope parameter is missing                                                                      |
| 400    | `InvalidSiteScopeParameterException` | siteScopeValue (String)        | if the site scope parameter is empty or contains an invalid site id                                         |
| 400    | `JobAlreadyRunningException`         | jobId (String)                 | if an incremental product index update job is already running for any other site scope                      |
| 403    | `UserAccessForbiddenException`       | method (String), path (String) | if the user doesn't have permission to build product-related search indexes for all sites of the site scope |

## Site Archive Export

This job is for executing a site export to an archive file based on data unit configuration in json format.

| Job Value         | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-site-archive-export/executions` |
| Request Document  | [SiteArchiveExportConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/sitearchiveexportconfiguration.md)                 |
| Response Document | JobExecution                                                                        |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-site-archive-export/executions|
|Request Document|[SiteArchiveExportConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/sitearchiveexportconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

## Site Archive Import

This job is for importing a whole site import ZIP file. The file is specified by its simple file name and must be already uploaded to the server. You can specify an import mode, where currently only 'merge' is supported.

| Job Value         | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| URL               | `POST https://hostname:port/dw/data/v24_5/jobs/sfcc-site-archive-import/executions` |
| Request Document  | [SiteArchiveImportConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/sitearchiveimportconfiguration.md)                 |
| Response Document | JobExecution                                                                        |

<!--TODO: Fix link post migration -->
<!-- |URL:|POST https://hostname:port/dw/data/v24_5/jobs/sfcc-site-archive-import/executions|
|Request Document|[SiteArchiveImportConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/sitearchiveimportconfiguration.md)|
|Response Document|[JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/data/documents/jobexecution.md)| -->

Faults

| Status | Type                     | Arguments         | Description                      |
| ------ | ------------------------ | ----------------- | -------------------------------- |
| 400    | `FileNotExistsException` | filePath (String) | if the import file doesn't exist |

<!-- document id=bfcbb6f382a3fee9a2e8c6fcb83c1d64dc54d0aa28f6445b4b7e53584571b09f url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-go-live.md -->

# Go Live

When your storefront is ready for staging or production, launch it to make it accessible from a public web address. Configure routing rules in Business Manager for vanity or custom domains to direct traffic to the right environment.

In this section:

- [Launch Your Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-launch-storefront.md)
- [Configure Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-routing-bm.md)

<!-- document id=49a91939c65efa69ede6e94ef6e033e3ae65cdc768579de71b4591e7cf1755b9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/quotas/b2c-governance-and-quotas.md -->

# Governance and Quotas

B2C Commerce includes constraints and limits to maintain the efficiency and stability of solutions built on the platform. These limits concern memory usage, resource consumption, API calls, and the number of business objects. Quotas are used to monitor resource usage in custom code. Resources include memory, application server threads, and database table sizes. Typically, when a quota is exceeded, custom code is using supported capabilities inefficiently, and a more efficient solution is possible.

The quota status is aggregated across all application servers of the instance. _Object_ quotas status is updated with an up to 20-minute delay. _Object relation_ quotas are checked and status is updated when relations are modified, not when they are traversed. The status of [object relation quotas and API quotas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/) is shown for the last 24 hours or since server start.

**note:** While most object quotas have a 20-minute delay, the _Private Keys and Certificates_ quotas are updated every 24 hours.

## What Happens When a Quota Is Exceeded?

All API Object quotas have a default action, as follows, that occurs at the instance level (PRD, STG, DEV, Sandbox).

| Action   | Quota Type                                                        | B2C Commerce Function                                                                                                              | Recommended Action                                                                                                                                                                                                |
| -------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| log_only | In the evaluation stage (by Salesforce).                          | Report usage levels against the quota limit within quota log-files (only).                                                         | Ignore the reported information for now.                                                                                                                                                                          |
| warn     | A valid indicator of potential performance or stability concerns. | Report usage levels against the quota limits within quota log-files and within the Quota Status dashboard within Business Manager. | Take corrective action at the _warning_ thresholds (60% of limit). B2C Commerce doesn't prevent usage beyond the _error_ threshold (100% of limit). Consequential realm instability or non-performance can occur. |
| error    | A valid indicator of potential performance or stability concerns. | Report usage levels against the quota limits within quota log-files and within the Quota Status dashboard within Business Manager. | Take corrective action immediately. B2C Commerce prevents usage beyond the Error threshold (100% of limit), and prevents\*\* consequential realm instability or non-performance.                                  |

B2C Commerce enforces API Object quotas for all new B2C Commerce realms. API Object quotas set to _error_ are enforced on all instances (PRD, STG, DEV, Sandbox) unless they are _softened_ (set to _warn_), as follows:

- For Production instances, only Salesforce Support can _soften_ quotas.
- For Sandbox instances, soften quotas that are already softened in Production. Export them from a Production instance and import them to the Sandbox instance. This approach matches your Development environment to your Production environment.

A quota is either _enforced_ or _not enforced._ If an enforced quota is exceeded, an exception is thrown, which prevents the current operation from completing. Do not catch quota violation exceptions within a customization. Instead, use _avoidance of quota violations_ as a design criterion.

Examples of quota violations are:

- A collection with too many elements was created in memory
- Too many persistent objects of a certain type were created in an instance

If an enforced quota is exceeded in a storefront request, the general error page opens. If an enforced quota is exceeded during a standard import, a warning or error is reported. If a quota isn't enforced, B2C Commerce doesn't act when the limit is exceeded. B2C Commerce plans to enforce all quotas in the future.

## Internal Quotas

Internal quotas are experimental or developmental in nature, and aren't enforced. They don’t appear in Business Manager. Ignore log messages about them.

## How Safe Is My Implementation

Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Quota Status** for information about API and object usage levels, number of violations on an instance, and which quotas are enforced. Business Manager shows quota usage or violations since server restart or within the last 24 hours.

With the proper permission, view details on:

- Object quotas status and limits
- Object relation quotas status and limits
- API quotas status and limits
- Sandbox system's database status

A quota status can be:

- green/ok = OK
- orange/warning = Near Quota Limit
- red/error = Action Required

Some quotas also specify a warning threshold, to give you an early indication that a quota limit is in danger of being exceeded.

When the warning threshold is exceeded and when the quota limit is exceeded, messages are written to the quota log files. Messages are written for all quotas, enforced and unenforced. The log files are written to the log files folder and have the prefix `quota.` Keep in mind that quota log files are written with a time delay. The log files contain information about where the quota violation occurred. Also, they can contain information about unenforced internal quotas that don’t appear in Business Manager. Safely ignore them.

## Best Practices

Review the quotas and see how stay within the limits. For any quota exception, the display shows `Action required.` Unless a quota is enforced, no action is required to fix an exception. However, use this real-time data (along with the Quota Log Files) to assess your current API Object usage. For example, it can help you troubleshoot a site that is experiencing performance issues. Check the quota logs to help identify pipelines that exceed limits.

## Implement Quota Overrides

Quotas are enforced by default on all instances. Salesforce B2C Commerce IT can _soften_ quotas as required on primary instances (PRD, STG, and DEV), by resetting them from error to warn. To use the same (softened) quotas on a Sandbox, export those quotas from a production instance and import (overwrite) them onto a Sandbox instance.

**note:** Export quota settings from all instances as needed. However, only import quota settings to Sandboxes. You can't import these settings into production instances.

1.  On a Production instance, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Site Import & Export**.

2.  In the Export section, under Data Units to Export, expand **Global Data** and select **Custom Quota Settings.**

3.  Enter an archive name and select if you want the file to be saved in the global export directory (recommended).

4.  To export the settings, click **Export**.

    The job appears in the Status section. Click the process link to view the log file. Download the log file if needed.

5.  To return to the Site Import & Export page, click **\<\< Back**.

6.  On a Sandbox instance, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Site Import & Export**.

7.  Upload the file that you exported from the production system.

    1.  Select **Local** or **Remote.**

    2.  Browse to search.

8.  To import the uploaded file, click **Import**.

    The job appears in the Status section. Click the process link to view the log file. Download the log file if needed. Select **Administration** > **Operations** > **Quota Status** and view custom quota overrides on the Custom Quota Actions page.

    If custom quota actions are active on an instance, a message appears on the Quota page.

## View Quota Status

View quota status and limits in the Administration module. Identify issues with your code and correct them before they cause significant problems.

View Quota violations in the Quota log file by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Site Development** > **Development Setup** > **WebDAV Access section** > **Log files**.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Quota Status**.

2.  On the Quota page, review the Custom Quota Actions section to see if any custom quota actions are active on the instance.

3.  To view details, expand a quota.

4.  On the Custom Quota Actions page, review the API quota limits and current usage for the quota elements that are of concern to you. Pay attention to any elements that appear in red or orange. Every quota is color-coded:

        |Green|OK|

    |Orange|Warning / Near Quota Limit|
    |Red|Error / Action Required|

    If you are using a Sandbox, database size limit and current usage are displayed in the Database Usage section.

    The API values reflect the last 24 hours only.

5.  To send out a daily summary of all quotas that are in violation, add any email addresses, and select **Enabled**.

    When a quota is violated, an email is sent to all recipients defined in this field.

    Recipients can be a single email address or a list of comma-separated email addresses. To save these settings, click **Apply**. To revert to the initial values, click **Reset**.

## Quota Log Files

Quota log files aggregate quota messages over a set period. Messages are written when the warn threshold or limit of a quota is exceeded.

The code location of the most recent event is written to the log file. The code locations of the aggregated events aren’t exposed. Quota log files show information about the location where a quota-warn threshold or limit was exceeded. The information includes the site name, job name, and top pipeline name. Additional information is sometimes included about the executed pipelet, script, pipeline node, and template.

Quota log files use this general format:

- a timestamp
- the thread name (contains type of request, site, pipeline name, and other parameters)
- the actual message

This format produces log entries such as the following:

`[2012-05-23 13:00:22.577 GMT] [RequestHandlerServlet|14320460|Sites-SiteGenesis-Site|Product-Show| PipelineCall|pRLNN0PXCp7rqIClq7IcPUvuEEjtkOWUAMBdUWhniPRFlV4Xvim3HwhDw96bRZ7e5BUxhnkC2ExrVYZVBFLJtw==] Quota api.jsStringLength (enforced, warn 600000, limit 1000000): warn threshold exceeded 1 time(s), max actual was 600010, current location: request/site Sites-SiteGenesis-Site/top pipeline Product-Show/ interaction node/template refapp.default_.CustomDisplay`

This section of the entry is the timestamp:

`[2012-05-23 13:00:22.577 GMT]`

This section of the entry is the internal reference:

`[RequestHandlerServlet|14320460|Sites-SiteGenesis-Site|Product-Show|PipelineCall| pRLNN0PXCp7rqIClq7IcPUvuEEjtkOWUAMBdUWhniPRFlV4Xvim3HwhDw96bRZ7e5BUxhnkC2ExrVYZVBFLJtw==]`

This section of the entry is the message:

Quota api.jsStringLength (enforced, warn 600000, limit 1000000): warn threshold exceeded 1 time(s),
max actual was 600010, current location: request/site Sites-SiteGenesis-Site/top pipeline
Product-Show/interaction node/template refapp.default\_.CustomDisplay

The message contains details to help identify problems. See:

- If a quota is _enforced_ or _not enforced_
- If applicable, the _warn_ threshold
- The limit
- The number of times since the last log entry for this quota that the warn threshold or limit was exceeded
- The highest observed reading (max actual)
- The _current location,_ which shows where the warn threshold or limit was exceeded

**note:** Read-only quotas don't have a warn threshold or limit, for example, _Quota object.ProductPO.readonly@SF (enforced)._

<!-- document id=3d2ab84193f56d325896a6ef32487b54ac47b113236ab4f4ad226f4d7add62c2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_specify_instance_permissions.md -->

# Grant Instance Permissions to Control Center Users

If you have the Control Center Administrator role, or if you have Grant Permissions, give other individual users permissions to your instances. If your organization has a few users, specify permissions individually. If your organization has many users, use roles. Optionally, combine both configuration techniques. This topic applies to B2C Commerce.

**note:** You can't change your own permissions in Control Center. A user with the correct permissions can update your Control Center permissions for you.

1. Log in to Control Center.
2. (Control Center Administrators) Click **Users**. If you're not a Control Center Administrator, go to an instance and click the **Users** tab. Search for and select a user or add a user.
3. On the **Instances** tab, click **Add Instances**. Optionally, assign the user to a role by clicking the **Roles** tab. The Select Instances slider opens, and shows a list of all realms in your organization. Expand a realm to see the instances.
4. Select one or more instances in one or more realms, and click **Add** to add each to the list.
5. Specify permissions for the instances. The permissions available for assignment depend on the instance type (PIG, SIG, or ODS). If you are a Control Center Administrator, you don't need to grant the instance permissions to yourself.
   - Reset (available only for SIG instances) — Users can initialize an instance with this permission.
   - Start/Stop — User can stop, start, and restart an instance.
   - View Statistics (available only for ODS instances) — Users can view usage statistics for an instance.
   - Grant Permissions — Users can administratively assign other users permissions for the instance. Users can only grant permissions that they already have.

<!-- document id=13dd7a985eb6e1611466ed35c2c56f3fd15e6d399af134f69e8a145b9bfde66e url=/developer/current/en-us/commerce-cloud/commerce-api/guides/guest-order-access-code.md -->

# Guest Order Access with an Access Code (OTP)

When a guest shopper checks out without an account and later loses their session by closing the browser, switching devices, or clearing cookies, they can't get back to the order they placed.

The Order Access Code flow gives that shopper a secure way back in. The shopper requests a 6-digit,
time-limited access code (OTP), the platform emails it to the address on the order, and the shopper
enters it to look up, cancel, or return that order through the
[Shopper Orders API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary).
This guide is for merchants and Commerce App developers enabling guest order self-service (view,
cancel, and return) on B2C Commerce.

There is one thing you must build to make this flow work: the email delivery hook. The platform
generates, stores, expires, and validates the code for you. It does not send the email. Instead, it
hands the code to a hook you implement, and your hook delivers it to the email address on the order
(for example, via a transactional email provider or Marketing Cloud). If you don't register the
hook, no code is ever delivered and the flow cannot complete.

**note:** Email is the supported channel. The flow is designed around the email address on the order. That
address is what the platform validates the request against. Other channels are out of scope today.

**important:** An integrated OMS unlocks the full flow. With no OMS, the access code enables order lookup only. The
shopper can view the order, but cannot cancel or return it. Cancel and return require an integrated
Order Management System (OMS): they run through the `oms-cancel-order` and `oms-return-order`
endpoints, which are backed by OMS. To offer guests the complete self-service experience (view,
cancel, and return), you need OMS integration.

## What the Platform Does vs. What You Do

| Concern                                                                             | Owner                                |
| ----------------------------------------------------------------------------------- | ------------------------------------ |
| Generate the 6-digit code                                                           | Platform                             |
| Store the code, enforce 15-minute expiry, attempt limits, and regeneration cooldown | Platform                             |
| Validate the code on lookup / cancel / return                                       | Platform                             |
| Match the submitted email against the order before generating a code                | Platform                             |
| Restrict the flow to guest orders                                                   | Platform                             |
| Deliver the code to the shopper by email                                            | You (the `sendOrderAccessCode` hook) |
| Compose the message body, subject, branding, localization                           | You                                  |

The platform is deliberately delivery-agnostic. It never sends an email itself and doesn't ship a
default email template. Delivery is entirely your hook's responsibility.

## Capabilities With and Without OMS

The access-code mechanism is the same either way: request a code, receive it by email, submit it.
What the shopper can do with the order afterward depends on whether your orders are backed by an
integrated OMS.

| Capability                            | Without OMS | With integrated OMS |
| ------------------------------------- | ----------- | ------------------- |
| Request an access code                | Yes         | Yes                 |
| Look up / view the order (`lookup`)   | Yes         | Yes                 |
| Cancel the order (`oms-cancel-order`) | No          | Yes                 |
| Return items (`oms-return-order`)     | No          | Yes                 |

Cancel and return are only available for orders integrated with an OMS. They run exclusively through
the `oms-cancel-order` and `oms-return-order` endpoints, which are OMS-backed. Without OMS, the
access code is a read-only key: great for letting a guest re-find and view their order, but it stops
at lookup.

Integrate an OMS to offer guests the complete self-service journey: view, cancel, and return.

### Reach Orders No Longer in B2C Commerce

With an integrated OMS, the flow reaches orders that no longer exist in B2C Commerce, for example,
orders that have been purged or archived out of the B2C Commerce order store but are still held in
the OMS. When the order isn't found in B2C Commerce, resolution falls back to the OMS, so both the
access code request (email validation) and the lookup succeed against the OMS copy. Cancel and
return are OMS-backed to begin with, so they operate on the OMS order directly.

This makes the access code a durable way for a guest to reach an old order long after B2C Commerce
would have dropped it, as long as the request carries `expand=oms`. Without an OMS integration, an
order missing from B2C Commerce is simply a 404.

## Flow Overview

### Lookup Only (No OMS)

```
1. Shopper enters order number + email on your "Track Order" page.
2. Storefront → POST .../orders/{orderNo}/actions/request-access-code   Body: { email }
3. Platform verifies the email matches the order, generates a 6-digit code,
   stores it in a 15-minute window, and calls your sendOrderAccessCode hook.
4. Your hook emails the code to the shopper.
5. Platform returns 202 Accepted (always — see "Why the response is always 202").
6. Shopper enters the code.
7. Storefront → POST .../orders/{orderNo}/lookup            Body: { orderViewCode: "<code>" }
   → returns the full order for the shopper to view.
```

### Full Self-Service (with Integrated OMS)

Steps 1–7 are identical; the lookup response additionally exposes eligibility so the storefront can
offer cancel/return, and steps 8+ become available:

```
7. Storefront → POST .../orders/{orderNo}/lookup            Body: { orderViewCode: "<code>" }
   → returns the full order; storefront shows Cancel / Return where eligible.
8. Storefront → POST .../orders/{orderNo}/actions/oms-cancel-order   Body: { orderAccessCode, reason }
   or           POST .../orders/{orderNo}/actions/oms-return-order   Body: { orderAccessCode, productItems }
```

The same code works for lookup and the follow-up cancel/return, as long as all calls happen within
the 15-minute window. The shopper requests the code once.

## Implement the Delivery Hook

### Register the Extension Point

The extension point is `sfcc.app.order.sendOrderAccessCode`. Register it in your cartridge's
`hooks.json`:

```json
{
  "hooks": [{ "name": "sfcc.app.order.sendOrderAccessCode", "script": "./order/sendAccessCode.js" }]
}
```

…referenced from your `package.json`:

```json
{ "hooks": "./hooks.json" }
```

### Implement the Script

The hook receives the order and the generated access code, and returns a `Status`:

```js
"use strict";
var Status = require("dw/system/Status");

exports.sendOrderAccessCode = function (order, accessCode) {
  // order      — the order the code is for (see "Hook Parameters")
  // accessCode — the freshly generated 6-digit code, for example, "847291"

  var email = order.customerInfo.email; // the address on the order

  // Compose and send by email — for example, transactional email provider or Marketing Cloud.
  MyMailer.send({
    to: email,
    subject: "Your order access code",
    body: "Your access code is " + accessCode + ". It expires in 15 minutes.",
  });

  return new Status(Status.OK);
};
```

### Hook Parameters

| Argument     | Type   | Description                                                                                                                                                              |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order`      | Order  | The full order the code was requested for. Use `order.customerInfo.email` for the recipient and `order.orderNo` in the message. All standard order fields are populated. |
| `accessCode` | String | The generated code, always 6 digits, matching `^\d{6}$` (for example, `"847291"`).                                                                                       |

### Return Values

| Your hook returns       | Endpoint result                                                                       |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `Status.OK`             | 202 Accepted. Normal success.                                                         |
| _(hook not registered)_ | 202 Accepted, but no code is delivered. The flow is a dead end until you register it. |
| `Status.ERROR`          | A delivery-failure error surfaces to the caller (not masked as 202).                  |

Delivery failures are intentionally not hidden behind the enumeration-safe 202 response, so that a
genuinely broken mailer is observable to your storefront rather than failing silently.

Your hook runs only when the order/email combination is valid, so returning `Status.ERROR` surfaces
a non-202 error and thereby reveals that this order/email was valid, the exact enumeration signal the
always-202 response exists to hide. Never use it to signal "order/email didn't match" (the platform
already returns a uniform 202 for that, before your hook is called). Reserve it strictly for genuine
delivery failures (for example, your mailer is down), and even then, note that the error is
observable to the caller. When in doubt, return `Status.OK` and handle delivery problems out of band
(logging, retries, alerting) so the 202 contract stays intact.

### Deliver Through a Non-Email Channel

The hook is technically channel-agnostic. Nothing stops you from reading a phone number off the order
and sending the code by SMS. But the flow is designed for email only today, and there are two things
to be aware of before going down that path:

- The platform validates the request against the order's email, not a phone number. The
  `request-access-code` endpoint takes an `email` and matches it against the address on the order.
  There is no phone-number equivalent, so an SMS channel would inherit email-based authorization
  while delivering to a number the platform never checked.
- You own the trust implications. Because the phone number isn't validated in the flow, sending the
  code by SMS is entirely at your discretion and risk.

Treat SMS or any non-email channel as an unsupported extension for now, not part of the intended
design.

## Call the Shopper Orders Endpoints

All endpoints live under `/organizations/{organizationId}/orders/{orderNo}` in the
[Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary)
SCAPI family and require a SLAS `ShopperToken`.

### Request an Access Code

`POST .../actions/request-access-code`

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-orders/v1/organizations/{organizationId}/orders/{orderNo}/actions/request-access-code?siteId={siteId}" \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "email": "shopper@example.com" }'
```

| Field   | Required | Description                                                                                    |
| ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `email` | Yes      | Must match the email on the order (exact, case-sensitive) for a code to be generated and sent. |

| Response | Meaning                                                                |
| -------- | ---------------------------------------------------------------------- |
| 202      | Accepted. Always returned when the request is well-formed (see below). |
| 400      | The `email` field is missing or empty.                                 |

**note:** Add `expand=oms` to include the integrated OMS. With `expand=oms` on the query string, email
validation resolves the order from the integrated OMS when it isn't found in B2C Commerce. Omit it
and the code request considers only the B2C Commerce order store.

Why the response is always 202. The endpoint returns 202 whether or not the order + email
combination is valid, and whether or not a code was actually generated. This prevents an attacker
from discovering valid order/email pairs, or probing cooldown state, by watching for response
differences. Your storefront should always tell the shopper "If that order and email match, we've
sent you a code," never "code sent" vs. "no such order."

### Look Up the Order

`POST .../lookup`

Full order access with the code uses the `orderViewCode` field (the same field the legacy,
long-lived OrderViewCode used; the server tells the two apart by format, so both keep working).

#### Without Integrated OMS

The lookup resolves the order from the B2C Commerce order store only. The shopper can view the
order, but the response does not carry the OMS-sourced eligible quantities
(`quantityAvailableToCancel`, `quantityAvailableToReturn`), and cancel/return are not available.
Orders that no longer exist in B2C Commerce return 404.

```sh
curl ".../orders/{orderNo}/lookup?siteId={siteId}" \
  -X POST -H "Authorization: Bearer {access_token}" -H "Content-Type: application/json" \
  -d '{ "orderViewCode": "847291" }'
```

#### With Integrated OMS (`expand=oms`)

Add `expand=oms` to the query string. The lookup then resolves the order from the integrated
OMS, including orders no longer present in B2C Commerce, and the response carries the per-item
eligible quantities (`quantityAvailableToCancel`, `quantityAvailableToReturn`), so your storefront
can show Cancel/Return only where the action is actually possible.

```sh
curl ".../orders/{orderNo}/lookup?siteId={siteId}&expand=oms" \
  -X POST -H "Authorization: Bearer {access_token}" -H "Content-Type: application/json" \
  -d '{ "orderViewCode": "847291" }'
```

**note:** Intended flow: always load the order via `lookup` first, then offer cancel/return based on the
eligibility in that response.

### Cancel an Order (Requires Integrated OMS)

`POST .../actions/oms-cancel-order`

Cancel and return are OMS-backed and only work when your orders are integrated with an OMS. Both
take the code in the `orderAccessCode` field (note: a different field name than lookup):

```sh
curl ".../orders/{orderNo}/actions/oms-cancel-order?siteId={siteId}" \
  -X POST -H "Authorization: Bearer {access_token}" -H "Content-Type: application/json" \
  -d '{ "reason": "Changed mind", "orderAccessCode": "847291" }'
```

| Field             | Required | Description                                                                                                |
| ----------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `reason`          | No       | Must match a configured cancel reason code (see `oms-meta-data`). Server applies the default when omitted. |
| `orderAccessCode` | No       | The code. Only needed when the current `ShopperToken` doesn't already grant access to the order.           |

### Return Items (Requires Integrated OMS)

`POST .../actions/oms-return-order`

```sh
curl ".../orders/{orderNo}/actions/oms-return-order?siteId={siteId}" \
  -X POST -H "Authorization: Bearer {access_token}" -H "Content-Type: application/json" \
  -d '{
        "productItems": [ { "itemId": "10uVF0000003W0BYAU", "quantity": 1.0, "reason": "Defect" } ],
        "orderAccessCode": "847291"
      }'
```

| Field                   | Required | Description                                                                          |
| ----------------------- | -------- | ------------------------------------------------------------------------------------ |
| `productItems`          | Yes      | Items to return. `quantity` must not exceed `quantityAvailableToReturn`.             |
| `productItems[].reason` | No       | Must match a configured return reason code. Server applies the default when omitted. |
| `orderAccessCode`       | No       | The code. Only needed when the `ShopperToken` doesn't already grant access.          |

## Access Code Rules

| Rule                       | Value                                                                                                                 |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Code format                | 6 numeric digits (`000000`–`999999`)                                                                                  |
| Validity                   | 15 minutes from generation                                                                                            |
| Reusable within the window | Yes, a successful lookup does not consume the code; the same code works for a following cancel/return                 |
| Failed-attempt limit       | 3 wrong entries → the code is invalidated immediately                                                                 |
| Regeneration cooldown      | A new code cannot be generated for 15 minutes after the last one, even if it was invalidated early by failed attempts |
| Single active code         | Only one valid code exists per order at any time                                                                      |

What this means:

- If the shopper enters the wrong code 3 times, tell them to request a new code, but they must wait
  out the 15-minute cooldown before a new one can be issued.
- A 404 is always a generic "order not found." It never states why, so don't parse it for a reason.
  Interpret it from the sequence of calls instead:
  - If earlier calls with the same code returned 200 and a later one suddenly returns 404, the
    shopper has lost access. The code expired mid-flow. Prompt them to request a new code.
  - If there was never a 200, the code is likely wrong or was invalidated early (for example, by too
    many failed attempts). Have the shopper re-check the code, or request a new one.
- The code is delivered in the email body as plain text, not as a link. Don't build magic-link flows
  around it. Putting the code in a URL would expose it in server, proxy, and browser logs.

## Limitations

- Guest orders only. The platform rejects an access code submitted for an order owned by a
  registered customer. Registered shoppers use the standard login-based order access. There is no
  merchant configuration to change this today.
- Email is the trust boundary. The code goes to whatever email is on the order. Anyone with access
  to that inbox (within 15 minutes) can access the order. This is by design and matches standard OTP
  delivery.
- No feature toggle to "turn on." There is no site preference to enable. The `request-access-code`
  endpoint is always live; the flow becomes usable the moment you register the `sendOrderAccessCode`
  hook. Without the hook, no code is delivered.
- Cancel and return require an integrated OMS. Without OMS, the access code enables order lookup
  only. The `oms-cancel-order` and `oms-return-order` endpoints are OMS-backed; there is no non-OMS
  cancel/return path for this flow.
- `expand=oms` is required to reach OMS-resolved orders. On `request-access-code` and `lookup`, the
  platform only consults the OMS when the request carries `expand=oms`. This is what lets email
  validation and lookup succeed against an OMS copy, including orders no longer present in B2C
  Commerce. Cancel and return are OMS-native and don't take this parameter.

## Best Practices

- The hook is not optional for this flow. No hook → no email → the shopper never gets a code. This is
  the single most common reason "the flow doesn't work."
- Be careful with `Status.ERROR`. It breaks the uniform 202 and can leak whether an order/email was
  valid, so reserve it for genuine delivery failures. See [Return Values](#return-values) for the
  full rationale.
- Mind the two field names: `orderViewCode` on lookup, `orderAccessCode` on cancel/return.
- Don't message "no such order" on the request step. Always give the neutral "if it matches, we sent
  a code" response to preserve enumeration protection.
- Localize inside your hook. The platform renders no content. The request's `locale` is available to
  your storefront/hook logic; the message body, subject, and language are entirely yours to build.

## See Also

- [Shopper Orders API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary): `request-access-code`,
  `lookup`, `oms-cancel-order`, `oms-return-order`.
- [Connect a Third-Party OMS](/docs/commerce/b2c-commerce/guide/connect-third-party-oms.md#guest-order-access-codes-otp)

<!-- document id=17ad584812323534bd2a08027080b682b1e84b69b92d3e62adb7a1a429e710a3 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-guest-order.md -->

# Guest Order Lookup for Unregistered Shoppers

Enable guest shoppers to look up their order status, shipment tracking, and other details in a PWA Kit store for orders placed without authentication or account registration. The self-service order lookup feature reduces support inquiries and improves the post-purchase shopper experience. To make sure only the order recipient can access order details, guest shoppers must undergo multi-factor verification via email. This feature is turned off by default.

**important:** Shoppers must provide an email address that isn't associated with a registered account. To look up an order based on an email tied to a registered account, shoppers must log in to their account.

To view order details as a guest shopper:

1. Click **Order Lookup** in the storefront footer.
2. Enter your order number and email address.
   After submitting these details, you receive a 6-digit access code by email.

   **note:** The access code expires after 15 minutes. You can request a new code if needed. B2C Commerce sets the expiration time and it isn't configurable in the storefront.

3. Enter the access code to view your order details, including status, order items, and shipping information.

## Prerequisites

- [PWA Kit](https://github.com/SalesforceCommerceCloud/pwa-kit) v3.21 or later.
- Cookies allowed:
  - The server writes a `Secure; HttpOnly; SameSite=Strict` session cookie after verification.
  - For local development, set `localAllowCookies: true` in the SSR server options (`app/ssr.js`). For MRT deployments, set `MRT_ALLOW_COOKIES=true`. Without either setting, the MRT runtime silently strips `Set-Cookie` headers—verification appears to succeed but the order lookup returns 404.
  - Local development also requires HTTPS. Run the dev server with `pwa-kit-dev --https` so that the browser accepts the secure cookie. Plain-HTTP local server runs can't complete the verification flow.
- Business Manager email hook: The `sfcc.app.order.sendOrderAccessCode` hook must be configured and active in Business Manager for shoppers to receive access codes.

## Guest Order Lookup Configuration

Configure guest order lookup in the `app.guestOrderLookup` key of `config/default.js`.

```js
// config/default.js
module.exports = {
  app: {
    guestOrderLookup: {
      enabled: true,
      orderNumberRegex: '^[a-zA-Z0-9-]{6,32}$',
      requestCodeThrottle: {
        windowMs: 60000, // 1-minute rolling window
        max: 5 // max verify attempts per IP per window
      }
    }
  }
}
```

### Configuration Options

| Option                         | Type    | Default                  | Description                                                                                                         |
| ------------------------------ | ------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| `enabled`                      | boolean | `false`                  | Enables or disables the feature. When `false`, all `/order-lookup` routes return 503 and the footer link is hidden. |
| `orderNumberRegex`             | string  | `'^[a-zA-Z0-9-]{6,32}$'` | Regex applied client-side to validate the order number format. Adjust to match your order ID format.                |
| `requestCodeThrottle.windowMs` | number  | `60000`                  | Rolling window in milliseconds for the rate limit on `POST /api/order-lookup/verify`.                               |
| `requestCodeThrottle.max`      | number  | `5`                      | Maximum verification attempts per IP address within `windowMs`. Requests over the limit receive HTTP 429.           |

## API Integration

Guest order lookup uses the [guestOrderLookup](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=guestOrderLookup) API call in B2C Commerce API (SCAPI) to fetch order data.

## Guest Order Lookup Considerations

### Field-Level Security

- Guest order lookup suppresses these fields for security.
  - Cardholder name
  - Full phone number
  - Payment details (beyond masked method)
  - Billing address
  - Detailed financial information

## Security

- HttpOnly session cookie: After successful verification, the server writes `cc-goa_{siteId}` with `Secure; HttpOnly; SameSite=Strict`. The cookie isn't readable from JavaScript.

### No Persistent Storage

- No order data or personally-identifiable information persists beyond browser session.
- Session data expires after 15 minutes (Max-Age=900) regardless of browser state.

## Troubleshooting

### Feature Not Visible

**Problem**: Footer "Order Lookup" link doesn't appear.

**Solution**: Check that `app.guestOrderLookup.enabled` is `true` in the config loaded by the running server. Config changes require a server restart. Confirm the correct config file is active by checking `NODE_ENV` and any environment-specific overrides.

### Access Codes Not Sending

**Problem**: Shoppers aren't receiving the access code email.

**Solution**: The access code email is triggered by the B2C Commerce Business Manager hook `sfcc.app.order.sendOrderAccessCode`. Verify the hook is configured and active in Business Manager. PWA Kit calls the SCAPI endpoint only — it doesn't control email delivery and can't detect whether the email was delivered.

### Session Cookie Issues

**Problem**: Session cookie isn't set after verification.

**Solution**: Check that cookies are allowed. For local development, set `localAllowCookies: true` in the SSR server options. For MRT deployments, set `MRT_ALLOW_COOKIES=true`. Without this, the `Set-Cookie` header is silently dropped and subsequent order lookup requests fail with 404.

### Access Code Locked After Too Many Attempts

**Problem**: Rate limiting is rejecting legitimate requests.

**Solution**: The default throttle allows 5 verify attempts per IP per 60-second window. Increase `requestCodeThrottle.max` or `requestCodeThrottle.windowMs` in `config/default.js` if needed. In MRT deployments, all requests arrive from the MRT proxy IP, so IP-based throttling applies to all shoppers equally. Consider a higher `max` for MRT-deployed storefronts.

<!-- document id=aed33f2f7b7b14fcc795672e2f87e13f792dfcc07183d08fa1e933114f5ec6d6 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-guest-order.md -->

# Guest Order Lookup for Unregistered Shoppers

Enable guest shoppers to look up their order status, shipment tracking, and other details in Storefront Next for orders placed without authentication or account registration. The self-service order lookup feature reduces support inquiries and costs, and improves the post-purchase shopper experience. To make sure only the order recipient can access the order details, guest shoppers must undergo multi-factor verification via email. This feature is turned off by default.

**important:** Shoppers must provide an email address that isn't associated with a registered account. To look up an order based on an email tied to a registered account, shoppers must log in to their account.

To view order details as a guest shopper:

1. Click **Order Lookup** in the storefront footer.
2. Enter the order number and your email address.
   After submitting these details, you receive a 6-digit one-time access code in an email.

   **note:** The access code expires after 15 minutes. You can request a new code if needed. B2C Commerce sets the expiration time and it isn't configurable in the storefront.

3. Enter the access code, and view the order details, such as the order status, date, order items, and shipping information.

## Prerequisites

- [Storefront Next](https://github.com/SalesforceCommerceCloud/storefront-next-template/) v1.3.0 or later.
- `GUEST_ORDER_LOOKUP_COOKIE_SECRET` environment variable: Set this variable to sign the session cookie that stores order access state. For local development, add it to your `.env` file. For MRT deployments, set it in your Managed Runtime project environment variables. If unset, the feature falls back to `CLIENT_SECRET`. If neither is set, every request returns `CONFIGURATION_ERROR`.
- Business Manager email hook: The `sfcc.app.order.sendOrderAccessCode` hook must be configured and active in Business Manager for shoppers to receive access codes.

## Guest Order Lookup Configuration

Configure guest order lookup settings in the app config file, `config.server.ts`, or by using environment variables.

### Configure Guest Order Lookup in the App Config File

Add these settings to your `config.server.ts`:

```typescript
export const config = {
  app: {
    guestOrderLookup: {
      enabled: true,
      orderNumberPattern: "^[a-zA-Z0-9-]{6,32}",
      cooldownSeconds: 60,
      turnstile: {
        enabled: true,
        failOpen: false,
      },
    },
  },
};
```

### Configure Guest Order Lookup Using Environment Variables

Override configuration via environment variables:

```bash
PUBLIC__app__guestOrderLookup__enabled=true
PUBLIC__app__guestOrderLookup__orderNumberPattern='^[a-zA-Z0-9-]{6,32}'
PUBLIC__app__guestOrderLookup__cooldownSeconds=60
PUBLIC__app__guestOrderLookup__turnstile__enabled=true
PUBLIC__app__guestOrderLookup__turnstile__failOpen=false
```

### Configuration Options

| Option               | Type     | Default                 | Description                                                                    |
| -------------------- | -------- | ----------------------- | ------------------------------------------------------------------------------ |
| `enabled`            | boolean  | `false`                 | Enable or disable the guest order lookup feature.                              |
| `orderNumberPattern` | string   | `'^[a-zA-Z0-9-]{6,32}'` | Regex pattern for validating order number format on the form.                  |
| `cooldownSeconds`    | number   | `60`                    | Minimum seconds between code requests per IP address.                          |
| `allowedFields`      | string[] | See `config.server.ts`  | Allowlist of order fields the server returns to the client after verification. |
| `turnstile.enabled`  | boolean  | `true`                  | Enable Cloudflare Turnstile bot protection on the verification form.           |
| `turnstile.failOpen` | boolean  | `false`                 | When `true`, allow requests through if Turnstile is unreachable.               |

## Routes

When enabled, these routes are registered:

- `/order-lookup` — Request access code form
- `/order-lookup/verify/:orderNo` — Enter access code form
- `/order-lookup/results/:orderNo` — View order details (after verification)

The `/order-lookup` route (from the entry form) routes redirects authenticated users to `/account/orders`.

## API Integration

Guest order lookup uses the [guestOrderLookup](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=guestOrderLookup) API call in B2C Commerce API (SCAPI) to fetch order data.

## Guest Order Lookup Considerations

### Field-Level Security

- Guest order lookup suppresses these fields for security.
  - Cardholder name
  - Full phone number
  - Payment details (beyond masked method)
  - Billing address
  - Detailed financial information

## Security

- HttpOnly session cookie: After successful verification, the server writes `glo_order_<orderHash>` with `Secure; HttpOnly; SameSite=Strict`. The cookie isn't readable from JavaScript.

### Turnstile Bot Protection

Storefront Next integrates Cloudflare Turnstile on the guest order lookup form. Turnstile is enabled by default (`turnstile.enabled: true`) and blocks automated requests before they reach SCAPI.

Set `turnstile.failOpen: true` to allow requests through if the Turnstile service is unreachable. The default (`false`) blocks requests when Turnstile can't be reached, which is the more secure posture for production.

### No Persistent Storage

- No order data or personally-identifiable information persists beyond browser session.
- Session data expires after 15 minutes (Max-Age=900) regardless of browser state.

## Troubleshooting

### Feature Not Visible

**Problem**: Footer "Order Lookup" link doesn't appear.

**Solution**:

1. Check `config.app.guestOrderLookup.enabled` is `true`.
2. Verify configuration is loaded correctly.
3. Clear browser cache and reload.

### Access Codes Not Sending

**Problem**: Shoppers don't receive an access code.

**Solution**:

1. Check email service configuration.
2. Verify SCAPI `requestOrderAccessCode` endpoint is accessible.
3. Check API logs for errors.
4. Verify shopper's email address is valid.

### Order Not Found Errors

**Problem**: Valid orders return "not found".

**Solution**:

1. Verify order number format matches configuration regex.
2. Check email address matches order email exactly.
3. Confirm order exists in Commerce Cloud.
4. Verify SCAPI `guestOrderLookup` endpoint permissions.

### Access Code Locked After Too Many Attempts

**Problem**: Shopper entered the wrong access code five times and is locked out. The form rejects all further attempts, even a correct code.

**Cause**: After five failed attempts, Storefront Next marks the order-state cookie as `ATTEMPTS_EXCEEDED`. The cookie is permanently locked—further entries are rejected regardless of whether the code is correct.

**Solution**: The shopper must restart the order lookup and request a new access code. Requesting a new code issues a fresh order-state cookie and resets the attempt counter. The previous locked cookie is replaced automatically. The shopper doesn't need to clear cookies or take any other action.

### Access Code Request Errors

**Problem**: Shoppers receive errors when requesting an access code too quickly.

**Solution**:

1. Review the `cooldownSeconds` setting (default: 60 seconds between requests per IP address).
2. Check if a proxy or load balancer is forwarding the correct client IP address.
3. Consider lowering `cooldownSeconds` for production if the default is too strict.

## See Also

- [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md)
- [guestOrderLookup API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=guestOrderLookup)

<!-- document id=68ee08a5a685a01b225211c5717e340e733f7227beb7b26e9464a01f813220dd url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-hand-off-a-basket.md -->

# Hand Off a Basket

## Hand Off a Basket to a Registered Customer

The agent hands off a basket for an order received over the phone so that the registered customer can then complete the checkout process in the merchant's storefront. The agent must have the necessary permissions.

1.  Create an order.

    1.  Select the customer.

    2.  Add products.

2.  Click **Hand Off Basket**.

    The customer can then log in to the merchant's storefront, access the shopping cart, and complete the checkout process.

**note:** The customer can have only one active cart session at time.

## Hand Off a Basket to an Agent

A registered customer's active basket can be handed off to an agent in Customer Service Center. The agent can then add or update the cart with new items, apply discounts, and then return the basket back to the customer to complete the checkout process via the merchant's storefront. The agent must have the necessary permissions.

1.  Select **_site_** > **Merchant Tools** > **Ordering** > **Customer Service Center**.

2.  Click **Find Customer**.

3.  To find a customer, enter a portion of the customer's name, and then select the customer.

4.  To access the registered customer's active basket, click the **Baskets** tab.

5.  From the Customer Detail page, click the active storefront basket.

    The customer's order page opens with the customer's basket items prepopulated.

6.  (optional) Add, update, or remove items from the basket.

7.  (optional) Add promotions to the basket.

8.  (optional) Based on granted permissions, apply manual price adjustments to the items, shipping, or the order.

9.  (optional) Hand off the basket back to the customer to complete the order.

<!-- document id=499a832cb19386a599c59793931708d16afc2ab0a8771aa94757775a8841b310 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-async-processing.md -->

# Handle Asynchronous Processing

Checkout APIs invoke calculators that run asynchronously. A successful API response doesn't mean processing is complete or data is ready.

![Diagram showing how asynchronous processing is handled during the B2B Commerce checkout flow](https://developer.salesforce.com/media/d2c-commerce/commerce-checkout-async-process.png '{"class": "image-lg", "title": "Handle Asynchronous Processing"}')

Response codes:

- 200 OK – Processing complete, data ready for consumption, and proceed to next step.
- 202 Accepted – Background calculators still running, cart locked for updates, and poll GET endpoint until you receive 200.
- 409 Conflict – Request made while previous operation still in progress, wait for completion before retrying.

## Concurrent Update Example

Scenario: Custom Apex updates a custom field on WebCart when the user clicks Place Order.

- Payment API loads the cart (version = x).
- Simultaneously, custom Apex updates the cart (version = x + 1).
- Payment API tries to save with old version (x).
- The system detects the mismatch and rejects with "Looks like your cart is currently in use. Please try again later."

Result: Payment processes successfully but isn't saved to the cart, preventing order creation.

## Asynchronous Operation Example

Scenario: The user adds a product and clicks Checkout, invoking PUT /checkouts.

- API returns 202 Accepted (checkout session creation in progress).
- User immediately invokes PATCH /checkouts to update delivery info without waiting.
- System returns 409 Conflict with error code CHECKOUT_CONFLICT.

Result: Update fails because previous operation hasn't completed.

## Avoid Conflicts

Don't:

- Make concurrent API calls that modify the cart.
- Run custom code that updates cart while Checkout APIs are processing.
- Invoke next Checkout API before receiving 200 OK.

Do:

- Wait for 200 OK before making next API call.
- Poll GET /checkouts after 202 responses.
- Coordinate custom code to avoid simultaneous cart updates.

<!-- document id=3a4892f5ca776f5fee0fde1011aa3c768df75b2b4340673b6df0506f5a23fae3 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-cart-currency-change.md -->

# Handle Currency Changes

## Switch Currency for an Existing Active Cart

Commerce carts don’t automatically support currency changes. If your store supports multiple currencies, we recommend that you deactivate the currency picker when a customer places an item in the cart. However, you can create a custom process to handle currency changes when items are in the cart. First create a secondary cart to move existing items into, and then set the desired currency for the new cart.

Make sure that products and price books are set up correctly in each currency that your store supports.

1.  Create a new cart in the new currency. Use [Commerce Webstore Carts](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts.htm).

2.  Add items from the previous cart to the new cart. Use [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm) or [Commerce Webstore Cart Items, Batch](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items_batch.htm).

3.  Delete the previous cart. Use the DELETE method on [Commerce Webstore Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart.htm).

4.  Set the new cart as the primary cart. Use [Commerce Webstore Cart, Make Primary](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_make_primary.htm).

## Set Currency When Creating a New Cart

To allow buyers to shop in a non-default currency, you can specify a currency when creating a new cart. This creates the cart in the user's preferred currency without changing the account's default currency.

**note:** Ensure that you provide the `currencyIsoCode` value in uppercase, for example, `EUR` when creating or retrieving the cart.

- When creating a cart using the [Commerce Webstore Carts](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartCollection) API, set the `currencyIsoCode` parameter to specify a currency different from the account’s default. This overrides the account’s default currency for that specific cart only.
- The account’s default currency remains unchanged, preventing conflicts when multiple users from the same account shop in different currencies.

  For example, your account Account1 defaults to `USD`, but you want to shop in `EUR`. Include `"currencyIsoCode": "EUR"` when creating the cart. The system creates your cart in `EUR`, while other users in Account1 continue shopping in `USD`.

- To retrieve a cart created with a non-default currency, include the same `currencyIsoCode` you used during creation in your GET request to the [Get Cart Item Collection](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartItemCollection) API.

<!-- document id=9c4e475220127988096e535fcb8980633e926e2b953f6d4d26d5104508ccfda9 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-scapi.md -->

# Headless Commerce with Salesforce Commerce API

Composable Storefront, an alternative to Storefront Reference Architecture (SFRA), takes a modular approach to building a custom online storefront using individual, standalone components. With the decoupled frontend and backend architecture, the storefront and user experience are separated from data and business logic. You can compose your own unique brand identity and experience using a customizable, scalable solution.

Composable Storefront consists of two primary components:

- Progressive Web Application (PWA) Kit: an open source framework for creating storefronts using JavaScript with the React.js framework. This allows you to control how your storefront looks and feels to your shoppers.
- Managed Runtime (MRT): a serverless, highly scalable, highly available hosting environment for your headless digital storefront. Managed Runtime provides the infrastructure to deploy, host, and manage your PWA frontend.

With Composable Storefront, you build your storefront on top of Salesforce Commerce API (SCAPI), and you can augment the built-in functionality by composing solutions that include other vendors, for example, adding a third-party search application or content management system (CMS) provider.

The following image provides an example B2C Commerce stack. Composable Storefront, which contains PWA Kit and MRT, is shown as one of two headless implementations using SCAPI to communicate with the B2C Commerce instance. An SFRA storefront, which communicates directly with the B2C Commerce instance, is also shown. B2C Commerce components include the Script API and cartridges with SCAPI hooks and SCAPI custom APIs.

![B2C Commerce Stack](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/b2c-stack.png)

## Progressive Web Application (PWA) Kit

The PWA Kit framework includes tools to help create a complete storefront for the entire shopper journey. You can view an example PWA Kit storefront on our [demo site](https://pwa-kit.mobify-storefront.com/).

## Managed Runtime Environment (MRT)

The PWA Kit app that you create runs on top of MRT. The MRT uses SCAPI to interact with the features on your site, including products, catalogs, a shopper basket, promotions, inventory, shipping, and billing.

#### Content Delivery Network (CDN)

The CDN, which is included with MRT and does not require additional configuration, is in charge of directing requests to the nearest app server to ensure quick and efficient handling.

The CDN includes four primary components:

- The CDN cache
- Edge functions, which optimize cache hit ratio. If the same request is made again, the response can be retrieved from the cache instead of having to be generated again. This improves the overall shopper experience by providing faster response times.
- Storefront-related assets, for example: static Javascript, CSS, and sprites.
- Proxies for forwarding requests to SCAPI, OCAPI, and other external APIs.

With the CDN, you can:

- Stack embedded CDN (eCDN), B2C Commerce’s default CDN, on top of MRT CDN for more control over web application firewall (WAF)/Logs/Security/Routing,
- Use the Edge Functions to customize how requests are routed to the serverless infrastructure (the request processor).

### Serverless Infrastructure

The PWA Kit is hosted as a serverless implementation on the MRT. Serverless infrastructure is highly scalable, highly available, lower maintenance, and performant:

- MRT scales up or down to accommodate all levels of storefront traffic, whether it's a significant increase for holiday shopping or a test environment with minimal traffic.
- You can have _many_ managed runtime environments (100 out of the box) at no additional cost, and it's easy to start and stop instances using the UI or API.
- You can quickly roll out changes and view all changes in the change history, which also enables easy rollback.
- All MRT environments are allocated equivalent resources, which means that your production and development environments look the same.

## SCAPI

SCAPI functionality is divided into two main groups: Shopper APIs and Admin APIs. Each group is further divided into API families, with each family focusing on related functionality. The Shopper API group is designed for customer-facing functions such as product browsing, shopping cart management and checkout. The Admin API group is aimed at merchant-facing functionality such as product management, order management, inventory management, and customer management.

When building out a composable storefront or other headless storefront, you also have SCAPI hooks that allow you to customize the behavior and add more custom endpoints.

The following diagram illustrates the communication flow between a shopper's browser and MRT, and MRT communication with SCAPI, OCAPI, and external APIs.

![How Composable Storefront Works with SCAPI](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/mrt-scapi.png)

## Next Steps

Explore other Composable Storefront and SCAPI guides:

### Composable Storefront

- [Get Started](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)
- [Composable Storefront Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html)
- [Build a Demo Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.md)
- [Deploy Your Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.md)
- [MRT API Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary)

### SCAPI

- [Get Started](https://developer.salesforce.com/docs/commerce/commerce-api/guide)
- [API and SDK Demo](https://developer.salesforce.com/docs/commerce/commerce-api/guide/api-and-sdk-demo.html)
- [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)
- [Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html)
- [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-request-identification.md)
- [API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references)

### OCAPI

[Get Started with OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html)

## See Also

- [Why Use SCAPI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/why-use-scapi.html)

<!-- document id=2227f0f5c8f7a2735931cd5470087fd9bbdac268928851fe46acea0aafc51380 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-guest-jwt.md -->

# Headless Guest Support for Cart and Checkout APIs Using JWT

Implement headless guest cart and checkout flows in B2B Commerce using a JSON Web Token (JWT) to establish guest identity and authorization. This approach enables secure, token-based interactions with Commerce APIs for guest users in headless storefronts.

Headless guest support allows anonymous users to interact with Commerce APIs without requiring authentication as registered users. JWT tokens securely identify and authorize guest sessions.

## What This Enables

- Guest users can browse, add items, and complete checkout without logging in.
- Guest identity remains consistent across requests using UVID and JWT.
- Use a backend-for-frontend (BFF) pattern to invoke Cart and Checkout APIs securely.

## Prerequisites

Before implementing headless guest support, make sure that you have:

### Salesforce Experience Cloud Setup

- Active Experience Cloud site
- Web store launched and configured
- Valid domain configured

### API Access

- Commerce API access enabled
- Appropriate API permissions configured

### Development Environment

- Backend application for handling guest user management
- Capability to generate and manage UVIDs
- Secure storage for OAuth credentials

## See Also

- [Connect to Experience Cloud Sites](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_sites.htm)
- [Headless Identity APIs: Headless Guest Flow for Public Clients](https://help.salesforce.com/s/articleView?id=sf.external_identity_headless_guest_flow.htm&type=5)
- [Configure a Connected App to Issue JWT-Based Access Tokens](https://help.salesforce.com/s/articleView?id=sf.remoteaccess_oauth_jwt_flow.htm&type=5)

<!-- document id=ab9752187b71698bef0cb7b59004eda1e64405df8e158e11d6f0d30a5d62594b url=/developer/current/en-us/commerce-cloud/commerce-api/guides/hook-method-details.md -->

# Hook Method Details

This document lists available SCAPI hooks with method details.

For SLAS hook details, see [SLAS Support for Custom Parameters and Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-custom-parameters.html).

For custom property type details, see [Custom Properties](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html).

## Authentication

Authentication hooks for the Shopper API, called by the [`/login`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer) endpoint.

---

**dw.ocapi.shop.auth.afterPOST**

`POST /customers/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, authRequestType : <i>dw.value.EnumValue</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the authenticated customer</dd>
    <dd>authRequestType - does the request specify a guest, login or refresh authentication</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.auth.beforePOST**

`POST /customers/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (authorizationHeader : <i>String</i>, authRequestType : <i>dw.value.EnumValue</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>authorizationHeader - the authorization header. Differs depending on the type: 
      <ul>
        <li>guest - no content relevant to the authentication.</li>
        <li>credentials - Base64 encoded username and password. For example Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=. It is possible to extract the username or password: <codeblock>var credentials = authHeader.substr(6); // cut out Basic var base64decoded : String = StringUtils.decodeBase64(credentials, "UTF-8"); var userName : String = base64decoded.split(":")[0]; var password : String = base64decoded.split(":")[1];</codeblock></li>
        <li>refresh - A refresh token, for example Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX</li>
        <li>session - no content relevant to the authentication. Authentication based on cookies.</li>
      </ul>
    </dd>
    <dd>authRequestType - does the request specify a guest, login or refresh authentication</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.auth.modifyPOSTResponse**

`POST /customers/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer">Customer</a></i>, authRequestType : <i>dw.value.EnumValue</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the auth customer</dd>
    <dd>customerResponse - customer response object</dd>
    <dd>authRequestType - auth request type enum</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Basket

Basket hooks for the Shopper API.

---

**dw.ocapi.baskets.actions.afterMerge**

`POST /baskets/actions/merge`

<details>  
<summary>Method details</summary>

<p>
  <b>afterMerge</b> (destinationBasket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the basket is merged. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>destinationBasket - the registered user basket into which the guest basket was merged.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.baskets.actions.afterTransfer**

`POST /baskets/actions/transfer`

<details>  
<summary>Method details</summary>

<p>
  <b>afterTransfer</b> (transferredBasket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the basket is transferred. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>transferredBasket - the basket that was transferred to the registered user.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.afterDELETE**

`DELETE /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the identifier of the removed basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.afterPATCH**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, basketInput : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket that was updated</dd>
    <dd>basketInput - the basket delta containing the desired changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.afterPOST**

`POST /baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the basket was created. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the created basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforeDELETE**

`DELETE /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforeGET**

`GET /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforePATCH**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, basketInput : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to be updated</dd>
    <dd>basketInput - the basket delta containing the desired changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforePOST_v2**

`POST /baskets`

<details>
<summary>Method details</summary>

<p>
  <b>beforePOST_v2</b> (basketRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=type%3ABasket">Basket</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketRequest - the basket request</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.billing_address.afterPUT**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, billingAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderAddress">OrderAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of the billing address to the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>billingAddress - the billing address that was set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.billing_address.beforePUT**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, billingAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderAddress">OrderAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of the billing address to the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>billingAddress - the billing address to be set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.billing_address.modifyPUTResponse**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, addressRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderAddress">OrderAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>addressRequest - address request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.afterDELETE**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, couponItemID : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a coupon from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get removed from</dd>
    <dd>couponItemID - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.afterPOST**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, couponItem : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, addressRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACouponItem">CouponItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding a coupon to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get added to</dd>
    <dd>couponItem - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.beforeDELETE**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, couponItemID : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a coupon from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get removed from</dd>
    <dd>couponItemID - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.beforePOST**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, couponItem : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, addressRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACouponItem">CouponItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding a coupon to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get added to</dd>
    <dd>couponItem - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, couponItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>couponItemId - coupon item id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.modifyPOSTResponse**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, couponRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, addressRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACouponItem">CouponItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>couponRequest - coupon request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.customer.afterPUT**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, customerInfo : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACustomerInfo">CustomerInfo</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of customer information for the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>customerInfo - the customer information that were set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.customer.beforePUT**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, customerInfo : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACustomerInfo">CustomerInfo</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of customer information for the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>customerInfo - the customer information to be set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.customer.modifyPUTResponse**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, customerRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ACustomerInfo">CustomerInfo</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>customerRequest - customer request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.afterDELETE**

`DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after deleting a gift certificate item from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the deleted gift certificate item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.afterPATCH**

`PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AGiftCertificateItem">GiftCertificateItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating a gift certificate item of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the updated gift certificate item</dd>
    <dd>item - the new gift certificate item data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.afterPOST**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AGiftCertificateItem">GiftCertificateItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding a gift certificate item to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the gift certificate item to add</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.beforeDELETE**

`DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before deleting a gift certificate item from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the gift certificate item to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.beforePATCH**

`PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AGiftCertificateItem">GiftCertificateItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a gift certificate item of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the gift certificate item to be updated</dd>
    <dd>item - the new gift certificate item data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.beforePOST**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AGiftCertificateItem">GiftCertificateItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding a gift certificate item to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the gift certificate item to add</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>giftCertificateItemId - the id of the deleted gift certificate item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>giftCertificateItemId - the id of the updated gift certificate item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.modifyPOSTResponse**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, certificateItemRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AGiftCertificateItem">GiftCertificateItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>certificateItemRequest - certificateItem request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.afterDELETE**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a basket item is removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>productItemId - the id of the removed product item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.afterPATCH**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AProductItem">ProductItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating of the basket's item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the product item delta containing the desired changes to the product item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.beforeDELETE**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a basket item is removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>productItemId - the id of the product item to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.beforePATCH**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AProductItem">ProductItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating of the basket's item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the product item delta containing the desired changes to the product item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>productItemId - productItemId request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>productItemId - productItemId request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.afterPOST**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, items : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AProductItem">ProductItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>items - productItems array of product items</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.beforePOST**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, items : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AProductItem">ProductItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>items - productItems array of product items</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.modifyPOSTResponse**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, productItems : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AProductItem">ProductItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>productItems - productItems array of product items</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.modifyGETResponse**

`GET /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.modifyPATCHResponse**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.modifyPOSTResponse**

`POST /baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the created basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.afterDELETE**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  It is called after the <i>order payment instrument</i> is removed from the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the payment instrument was removed from</dd>
    <dd>paymentInstrument - the payment instrument to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.afterPATCH**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, paymentInstrumentRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABasketPaymentInstrumentRequest">BasketPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating a payment instrument of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the updated payment instrument</dd>
    <dd>paymentInstrumentRequest - the new payment instrument data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.afterPOST**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABasketPaymentInstrumentRequest">BasketPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after payment instrument adding to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the payment instrument added to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.beforeDELETE**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, delete : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  It is called before the <i>order payment instrument</i> is removed from the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to remove the payment instrument from</dd>
    <dd>delete - the order payment instrument document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.beforePATCH**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, newPaymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABasketPaymentInstrumentRequest">BasketPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a payment instrument of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the payment instrument to be updated</dd>
    <dd>newPaymentInstrument - the new payment instrument data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.beforePOST**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABasketPaymentInstrumentRequest">BasketPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before payment instrument adding to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the payment instrument to be added to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>paymentInstrumentRequest - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>paymentInstrumentRequest - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, paymentInstrumentRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3ABasketPaymentInstrumentRequest">BasketPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>paymentInstrumentRequest - payment instrument request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_methods.afterGET**

`GET /baskets/{basket_id}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>afterGET</b> (basket : <i>dw.order.Basket</i>, paymentMethods : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3APaymentMethodResult">PaymentMethodResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  Called before returning the list of available payment methods to the customer. Allowing modifications of the result. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>paymentMethods - the available payment methods</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_methods.beforeGET**

`GET /baskets/{basket_id}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_methods.modifyGETResponse_v2**

`GET /baskets/{basket_id}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (basket : <i>dw.order.Basket</i>, paymentMethodResultResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=type%3APaymentMethodResult">PaymentMethodResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the payment method result retrieved for.</dd>
    <dd>paymentMethodResultResponse - paymentMethodResult response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.afterDELETE**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Called after the basket's shipment was removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket that was updated</dd>
    <dd>shipmentId - the id of the deleted shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.afterPATCH**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shipmentInfo : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShipment">Shipment</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after patching of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment was changed</dd>
    <dd>shipment - the shipment that has been updated</dd>
    <dd>shipmentInfo - the shipment information for the shipment update</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.afterPOST**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, shipment : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShipment">Shipment</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the creation of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment was created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.beforeDELETE**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Called before the basket's shipment is removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to be updated</dd>
    <dd>shipment - the shipment to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.beforePATCH**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shipmentInfo : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShipment">Shipment</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before changing of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment will be updated</dd>
    <dd>shipment - the current shipment to be updated</dd>
    <dd>shipmentInfo - the shipment information for the shipment update (update data)</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.beforePOST**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, shipment : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShipment">Shipment</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the creation of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment will be created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shipmentId - shipment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shipmentId - shipment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.modifyPOSTResponse**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, shipmentRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShipment">Shipment</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shipmentRequest - shipment request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_address.afterPUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderAddress">OrderAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of the shipping address to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingAddress - the shipping address that was set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_address.beforePUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderAddress">OrderAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of the shipping address to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingAddress - the shipping address to be set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_address.modifyPUTResponse**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, orderAddressRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AOrderAddress">OrderAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>orderAddressRequest - order address request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_method.afterPUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingMethod : <i><a href = "https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShippingMethod">ShippingMethod</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of the shipping method to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingMethod - the shipping method that was set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_method.beforePUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingMethod : <i><a href = "https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShippingMethod">ShippingMethod</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of the shipping method to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingMethod - the shipping method to be set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_method.modifyPUTResponse**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, shippingMethodRequest : <i><a href = "https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=type%3AShippingMethod">ShippingMethod</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shippingMethodRequest - shipping method request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipments.shipping_methods.beforeGET**

`GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the target basket id</dd>
    <dd>shipmentId - the shipment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipments.shipping_methods.modifyGETResponse_v2**

`GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (shipment : <i>dw.order.Shipment</i>, shippingMethodResult : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=type%3AShippingMethodResult">ShippingMethodResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>shipment - the shipment the shipping methods result retrieved for.</dd>
    <dd>shippingMethodResult - shipping method result object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`GET /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/price_adjustments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=Summary">Basket</a></i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Category

Category hooks for the Shopper API.

---

**dw.ocapi.shop.category.beforeGET**

`GET /categories/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (categoryId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>categoryId - the id of the category</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.category.modifyGETResponse**

`GET /categories/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptCategory : <i>dw.catalog.Category</i>, doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=type%3ACategory">Category</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptCategory - an instance of dw.catalog.Category</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Configurations

Configurations hooks for the Shopper API.

**dw.shop.shopper_configuration.modifyGETResponse**

`GET /configurations`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (configurationsResponse : <i>object</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>configurationsResponse - the shopper configurations result response object (extensible).</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer

Customer hooks for the Shopper API.

---

**dw.ocapi.shop.customer.afterPATCH**

`PATCH /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, customerInput : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer">Customer</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a customer was updated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer to be updated</dd>
    <dd>customerInput - the input customer containing the patch changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.afterPOST**

`POST /customers`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, registration : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerRegistration">CustomerRegistration</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a new customer registration. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the registered customer</dd>
    <dd>registration - the customer registration information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.auth.afterPOST**

`POST /customers/{customer_id}/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer that is authenticated</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.auth.beforePOST**

`POST /customers/{customer_id}/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer that is authenticated</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.auth.modifyPOSTResponse**

`POST /customers/{customer_id}/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer">Customer</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.baskets.beforeGET**

`GET /customers/{customer_id}/baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the baskets result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.baskets.modifyGETResponse_v2**

`GET /customers/{customer_id}/baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, customerBasketsResultResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ABasketsResult">BasketsResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the baskets result retrieved for.</dd>
    <dd>customerBasketsResultResponse - customer basket result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.beforeGET**

`GET /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - The customer id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.beforePATCH**

`PATCH /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, customerInput : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer">Customer</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a customer is updated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer to be updated</dd>
    <dd>customerInput - the input customer containing the patch changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.beforePOST**

`POST /customers`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (registration : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerRegistration">CustomerRegistration</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a new customer registration. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>registration - the customer registration information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.modifyGETResponse**

`GET /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer">Customer</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.modifyPATCHResponse**

`PATCH /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer">Customer</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.modifyPOSTResponse**

`POST /customers`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomer">Customer</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - created customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.orders.beforeGET**

`GET /customers/{customer_id}/orders`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the orders are retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.orders.modifyGETResponse_v2**

`GET /customers/{customer_id}/orders`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, customerOrderResultResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerOrderResult">CustomerOrderResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the orders are retrieved for.</dd>
    <dd>customerOrderResultResponse - customer order result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.password.beforePUT**

`PUT /customers/{customer_id}/password`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a customer's password. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customerId for which the password is being updated</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.password.afterPUT_v2**

`PUT /customers/{customer_id}/password`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT_v2</b> (customer : <i>dw.customer.Customer</i>, passwordChangeRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3APasswordChangeRequest">PasswordChangeRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called to update a customer's password.
  The default implementation tries to change the authenticated user password
  to the new password provided in the request. In case of an error, the default
  implementation returns one of the error statuses listed in
  dw.customer.Credentials#setPassword(String, String, boolean).
  To change a password in a third-party system, use a custom implementation.
  Because the password is updated in this hook, not in the PUT call, if
  you customize this hook, your custom code must update the password.
  Otherwise, the password is not updated.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for which the password is being updated</dd>
    <dd>passwordChangeRequest - The PasswordChangeRequest object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.password_reset.afterPOST**

`POST /customers/{customer_id}/password_reset`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, resetToken : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows resetting a customer password. See the example below sending an email with a password reset link.
</p>

<div>

```javascript
var variables: Map = new dw.util.HashMap();
variables.put("Customer", customer);
variables.put("ResetPasswordToken", token);
var template: Template = new dw.util.Template("mail/resetpasswordemail.isml");
var content: MimeEncodedText = template.render(variables);
var mail: Mail = new Mail()
  .setSubject("Password Reset")
  .setContent(content)
  .setFrom("noreply@salesforce.com")
  .addTo(customer.profile.email);
mail.send();
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to reset the password</dd>
    <dd>resetToken - the token generated by the system to be used for the reset</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.password_reset.beforePOST**

`POST /customers/{customer_id}/password_reset`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to reset the password</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.afterDELETE**

`DELETE /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a payment instrument of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to delete the payment instrument</dd>
    <dd>paymentInstrumentId - the id of the payment instrument that was deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.afterPOST**

`POST /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, paymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerPaymentInstrumentRequest">CustomerPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a payment instrument was added to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to add the payment instrument</dd>
    <dd>paymentInstrument - the payment instrument that was added</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.beforeDELETE**

`DELETE /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a payment instrument of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to delete the payment instrument</dd>
    <dd>paymentInstrumentId - the id of the payment instrument to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.beforeGET**

`GET /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - target customer id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.beforePOST**

`POST /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, paymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerPaymentInstrumentRequest">CustomerPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a payment instrument is added to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to add the payment instrument</dd>
    <dd>paymentInstrument - the payment instrument to be added</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.modifyGETResponse**

`GET /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, customerPaymentInstrument : <i>dw.customer.CustomerPaymentInstrument</i>, customerPaymentInstrumentResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerPaymentInstrument">CustomerPaymentInstrument</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerPaymentInstrument - payment instrument</dd>
    <dd>customerPaymentInstrumentResponse - customer payment instrument response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.modifyPOSTResponse**

`POST /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerPaymentInstrument : <i>dw.customer.CustomerPaymentInstrument</i>, customerPaymentInstrumentResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerPaymentInstrument">CustomerPaymentInstrument</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>Customer - target customer</dd>
    <dd>customerPaymentInstrument - payment instrument</dd>
    <dd>customerPaymentInstrumentResponse - customer payment instrument response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instruments.beforeGET**

`GET /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, paymentMethodId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the customer payment instruments result retrieved for.</dd>
    <dd>paymentMethodId - the id of the payment method, if null - all payment instruments are retrieved</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instruments.modifyGETResponse_v2**

`GET /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, customerPaymentInstrumentResultResponse : <i>CustomerPaymentInstrumentResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the customer payment instruments result retrieved for.</dd>
    <dd>customerPaymentInstrumentResultResponse - customer payment instrument result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.afterDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, productListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a customer product list is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productListId - the product list id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.afterPATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList">CustomerProductList</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after modifying a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.beforeDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a customer product list is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, productListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - The customer id.</dd>
    <dd>productListId - The product list id.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.beforePATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList">CustomerProductList</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before modifying a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.afterDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, itemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after deleting an item from a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>itemId - the id of the deleted item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.afterPATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating an item of a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the updated item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.beforeDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i>dw.customer.ProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before deleting an item from a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the product list item to delete</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, productListId : <i>String</i>, productListItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - target customer id</dd>
    <dd>productListId - the customers product list id the product list item purchase result retrieved for.</dd>
    <dd>productListItemId - the product list id item the product list item purchase result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.beforePATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating an item of a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the product list item to update</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.modifyGETResponse**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, productListItem : <i>dw.customer.ProductListItem</i>, customerProductListItemResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productListItem - target product list item</dd>
    <dd>customerProductListItemResponse - customer product list item response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.modifyPATCHResponse**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListItemResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>, customerProductListItemRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListItemRequest - customer product list item request object</dd>
    <dd>customerProductListItemResponse - customer product list item response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.modifyPOSTResponse**

`POST /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListItemResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>, customerProductListItemRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListItemResponse - customer product list item response object</dd>
    <dd>customerProductListItemRequest - customer product list item request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.afterPOST**

`POST /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding an item to a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the item added to the customer product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, productListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the customer product list items result retrieved for.</dd>
    <dd>productListId - the product list id the customer product list items result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.beforePOST**

`POST /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListItem">CustomerProductListItem</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding an item to a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the item to add to the customer product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.modifyGETResponse_v2**

`GET /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListItemResultResponse : <i>CustomerProductListItemResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the customer product list items result retrieved for.</dd>
    <dd>productList - the product list the customer product list items result retrieved for.</dd>
    <dd>customerProductListItemResultResponse - customer product list item result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.modifyGETResponse**

`GET /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList">CustomerProductList</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListResponse - customer product list response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.modifyPATCHResponse**

`PATCH /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList">CustomerProductList</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListResponse - customer product list response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.modifyPOSTResponse**

`POST /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList">CustomerProductList</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - product list</dd>
    <dd>customerProductListResponse - customer product list response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.afterPOST**

`POST /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList">CustomerProductList</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after creating a new product list for the specified customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the created product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.beforeGET**

`GET /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the customer product lists result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.beforePOST**

`POST /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductList">CustomerProductList</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before creating a new product list for the specified customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list to create</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.modifyGETResponse_v2**

`GET /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, customerProductListResultResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerProductListResult">CustomerProductListResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the customer product lists result retrieved for.</dd>
    <dd>customerProductListResultResponse - customer product list pageable result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer Address

Customer address hooks for the Shopper API.

---

**dw.ocapi.shop.customer.address.afterDELETE**

`DELETE /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was deleted</dd>
    <dd>addressName - the name of the address that was deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.afterPATCH**

`PATCH /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was updated</dd>
    <dd>addressName - the name of the address that was updated</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.beforeDELETE**

`DELETE /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to delete the address</dd>
    <dd>addressName - the name of the address to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.beforeGET**

`GET /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, addressName : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerAddress - target customer address</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.beforePATCH**

`PATCH /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to update the address</dd>
    <dd>addressName - the name of the address to be updated</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.modifyGETResponse**

`GET /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, customerAddressResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerAddress - target customer address</dd>
    <dd>customerAddressResponse - customer address response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.modifyPATCHResponse**

`PATCH /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, customerAddressResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>, customerAddressRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerAddress - target customer address</dd>
    <dd>customerAddressResponse - customer address response object</dd>
    <dd>customerAddressRequest - customer address request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.modifyPOSTResponse**

`POST /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, customerAddressResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>, customerAddressRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before returning response. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was added.</dd>
    <dd>customerAddress - created customer address</dd>
    <dd>customerAddressResponse - customer address response object.</dd>
    <dd>customerAddressRequest - the customer address request object.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer Addresses

Customer addresses hooks for the Shopper API.

---

**dw.ocapi.shop.customer.addresses.afterPOST**

`POST /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding an address to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was added</dd>
    <dd>addressName - the name of the address that was added</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.addresses.beforeGET**

`GET /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.addresses.beforePOST**

`POST /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=type%3ACustomerAddress">CustomerAddress</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding an address to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to add the address</dd>
    <dd>addressName - the name of the address to be added</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.addresses.modifyGETResponse**

`GET /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customerAddressResultResponse : <i>CustomerAddressResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerAddressResultResponse - customer addresses result response</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Gift Certificate

Gift certificate hooks for version 23.1.

**dw.ocapi.shop.gift_certificate.beforePOST**

`POST /gift_certificate`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (giftCertificateRequest : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-gift-certificates?meta=type%3AGiftCertificateRequest">GiftCertificateRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>giftCertificateRequest - The request containing the gift certificate code.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.gift_certificate.modifyPOSTResponse**

`POST /gift_certificate`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (giftCertificate : <i>dw.order.GiftCertificate</i>, giftCertificateResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-gift-certificates?meta=type%3AGiftCertificate">GiftCertificate</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>giftCertificate - the target gift certificate</dd>
    <dd>giftCertificateResponse - gift certificate response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order

Order hooks for the Shopper API.

---

**dw.ocapi.shop.order.afterPOST**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (order : <i>dw.order.Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after an order was created from the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order that was created for the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.beforeGET**

`GET /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (orderNo : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderNo - the order number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.beforePOST**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before an order is created for the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.modifyGETResponse**

`GET /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.modifyPOSTResponse**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.scapi.orders.afterPOST**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (order : <i>dw.order.Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after an order was created.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the created order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.scapi.orders.beforePOST**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (request : OrderCreateRequestWO) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before an order is created.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>request - the order create request</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.scapi.shop.orders.lookup.afterPOST**

`POST /orders/{order_no}/lookup`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (order : <i>dw.order.Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after looking up an order.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the looked up order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.scapi.shop.orders.lookup.beforePOST**

`POST /orders/{order_no}/lookup`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (request : OrderLookupRequestWO) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before looking up an order.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>request - the order lookup request</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.scapi.shop.orders.lookup.modifyPOSTResponse**

`POST /orders/{order_no}/lookup`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (orderLookupResponse : OrderWO) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the post lookup order.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderLookupResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Payment

Order payment hooks for the Shopper API.

---

**dw.order.payment.authorize**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>authorize</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.order.payment.authorize**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>authorize</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.order.payment.authorizeCreditCard**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>authorizeCreditCard</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>, cvn : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization of a credit card - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
    <dd>cvn - the credit card verification number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.order.payment.authorizeCreditCard**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>authorizeCreditCard</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>, cvn : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization of a credit card - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
    <dd>cvn - the credit card verification number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.validateOrder**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateOrder</b> (order : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes:
</p>
<div>
  
```javascript
exports.validateBasket = function() {
  order.addFlash({
    type: "PaymentAuthorizationFailure",
    message: "Order was not successfully authorized.",
    path: "authorizations",
    details: {
      "result": "reject",
      "reason": "invalid_credit_card"
    }
  });
}
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.validateOrder**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateOrder</b> (order : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes:
</p>
<div>

```javascript
exports.validateBasket = function () {
  order.addFlash({
    type: "PaymentAuthorizationFailure",
    message: "Order was not successfully authorized.",
    path: "authorizations",
    details: {
      result: "reject",
      reason: "invalid_credit_card",
    },
  });
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.validateOrder**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateOrder</b> (order : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes:
</p>
<div>

```javascript
exports.validateBasket = function () {
  order.addFlash({
    type: "PaymentAuthorizationFailure",
    message: "Order was not successfully authorized.",
    path: "authorizations",
    details: {
      result: "reject",
      reason: "invalid_credit_card",
    },
  });
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Payment Instruments

Order payment instruments hooks for the Shopper API.

---

**dw.ocapi.shop.order.payment_instrument.afterDELETE**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the removed payment instrument</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.afterPATCH**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, newPaymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrderPaymentInstrumentRequest">OrderPaymentInstrumentRequest</a></i>, successfullyAuthorized : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the updated payment instrument</dd>
    <dd>newPaymentInstrument - the new payment instrument data</dd>
    <dd>successfullyAuthorized - was the payment instrument successfully authorized.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.afterPOST**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrderPaymentInstrumentRequest">OrderPaymentInstrumentRequest</a></i>, successfullyAuthorized : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a payment instrument was added to the order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument that was added to the order</dd>
    <dd>successfullyAuthorized - was the payment instrument successfully authorized.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.beforeDELETE**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.beforePATCH**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, newPaymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrderPaymentInstrumentRequest">OrderPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument to be updated</dd>
    <dd>newPaymentInstrument - the new payment instrument data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.beforePOST**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrderPaymentInstrumentRequest">OrderPaymentInstrumentRequest</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a payment instrument is added to the order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument to be added to the order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.modifyDELETEResponse**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
    <dd>paymentInstrumentId - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.modifyPATCHResponse**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
    <dd>paymentInstrumentId - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.modifyPOSTResponse**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3AOrder">Order</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Payment Methods

Order payment methods hooks for the Shopper API.

---

**dw.ocapi.shop.order.payment_methods.beforeGET**

`GET /orders/{order_no}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (orderNumber : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderNumber - the order number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_methods.modifyGETResponse_v2**

`GET /orders/{order_no}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (order : <i>dw.order.Order</i>, paymentMethodResultResponse : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=type%3APaymentMethodResult">PaymentMethodResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order the payment method result retrieved for.</dd>
    <dd>paymentMethodResultResponse - payment method result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Product

Product hooks for the Shopper API.

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=type%3AProduct">Product</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Product Search

Product search hooks for the Shopper API.

---

**dw.ocapi.shop.product_search.beforeGET**

`GET /product_search`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.modifyGETResponse**

`GET /product_search`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=type%3AProductSearchResult">ProductSearchResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Promotion

Promotion hooks for the Shopper API.

---

**dw.ocapi.shop.promotion.beforeGET**

`GET /promotions/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (id : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>id - The id of the requested promotion.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.promotion.modifyGETResponse**

`GET /promotions/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptPromotion : <i>dw.campaign.Promotion</i>, doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-promotions?meta=type%3APromotion">Promotion</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptPromotion - an instance of dw.campaign.Promotion</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Promotions

Promotions hooks for the Shopper API.

---

**dw.ocapi.shop.promotions.beforeGET**

`GET /promotions`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (campaignId : <i>String</i>, startDate : <i>String</i>, endDate : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>campaignId - Find the promotions assigned to this campaign (mandatory)</dd>
    <dd>startDate - The start date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ</dd>
    <dd>endDate - The end date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.promotions.modifyGETResponse**

`GET /promotions`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-promotions?meta=type%3APromotionResult">PromotionResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Search Suggestions

Search suggestions hooks for Shop API.

---

**dw.ocapi.shop.search_suggestion.beforeGET**

`GET /search_suggestion`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.search_suggestion.modifyGETResponse**

`GET /search_suggestion`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=type%3ASuggestionResult">SuggestionResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## SEO URL Mapping

SEO URL Mapping hooks for the Shopper API.

---

**dw.shop.seo.url_mapping.beforeGET**

`GET /url-mapping`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (urlSegment : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>urlSegment - The URL for which the mapping needs to be retrieved.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.shop.seo.url_mapping.modifyGETResponse**

`GET /url-mapping`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (urlMapping : <i>UrlMapping</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>urlMapping - Returns URL mapping information for a URL that a shopper clicked or typed in</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Shopper Context Mapping

Shopper Context Mapping hooks for the Shopper API.

---

**dw.shop.shopper_context.beforePUT**

`PUT /shopper-context`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (usid: string , siteId: string , shopperContext: ShopperContext ) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>usid - SLAS user ID.</dd>
    <dd>siteId - site ID for the shopper context.</dd>
    <dd>shopperContext - shopper context to be saved.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.shop.shopper_context.beforePATCH**

`PATCH /shopper-context`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (usid: string , siteId: string , shopperContext: ShopperContext ) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the shopper context is updated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>usid - SLAS user ID.</dd>
    <dd>siteId - site ID for the shopper context.</dd>
    <dd>shopperContext - shopper context to be saved.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.shop.shopper_context.modifyPATCHResponse**

`PATCH /shopper-context`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the new shopper context was updated. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Store

Store hooks for Shop API.

---

**dw.ocapi.shop.store.beforeGET**

`GET /stores/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (id : <i>String</i>, siteId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>id - The id of the requested store.</dd>
    <dd>siteId - The ID of the site to get the store from</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.store.modifyGETResponse**

`GET /stores/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptStore : <i>dw.catalog.Store</i>, doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-stores?meta=type%3AStore">Store</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptStore - an instance of dw.catalog.Store</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Stores

Stores hooks for Shop API.

---

**dw.ocapi.shop.stores.beforeGET**

`GET /stores`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (latitude : <i>Double</i>, longitude : <i>Double</i>, countryCode : <i>String</i>, postalCode : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>latitude - The geo coordinate latitude to search for stores (value range -90.00 .. 90.00).</dd>
    <dd>longitude - The geo coordinate longitude to search for stores (value range -180.00 .. 180.00).</dd>
    <dd>countryCode - The two letter ISO country code for example, "US".</dd>
    <dd>postalCode - The postal code for example, "01801".</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.stores.modifyGETResponse**

`GET /stores`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i><a href="https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-stores?meta=type%3AStoreResult">StoreResult</a></i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

<!-- document id=ae5e0fff0eddf1c52fc2366f44e5aafcab714ffd5bb0c509fb48af98de90cc1d url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-how-standard-works.md -->

# How Standard B2B Commerce Checkout Works

Learn how the standard B2B Commerce checkout process works using Commerce APIs. Checkout runs through a series of steps, each triggering background calculators based on cart status and available information:

The steps include:

1. Add to Cart

   - If `CartStatus=ACTIVE`. This runs the Pricing and Promotions calculator.
   - If `CartStatus=CHECKOUT`. This runs the Pricing, Promotion, and Inventory calculator.
     - If shipping address is present/selected, then Shipping and Tax calculators are also executed.

2. Start Checkout

   - Use the PUT Checkout API.
   - This checks if there’s an existing Checkout Session and returns the same if found.
   - If no session exists, create a new Checkout Session and run Pricing, Promotion, and Inventory calculator. If the delivery address is present (registered user has an address saved), then it also runs Shipping and Tax calculators.

3. Enter contact information (Only for Guest User)

   - Add contact information such as phone number or email using the PATCH Checkout API for a headless use case, but it must be done after a checkout session is created.

4. Enter Delivery Information

   - Use the PATCH Checkout API to update contact and delivery information.
   - If the delivery information wasn't available prior to this or there's a change in the address, this triggers Tax and Shipping calculators.
   - Even if shipping is turned off, an address is required for tax calculation. In such a case, adding an address triggers only the Tax calculator.

5. Select shipping method (If shipping is enabled).
6. Process Payment – Captures payment authorization.
7. Place Order – Validates and creates the order.

<!-- document id=8ae59012cea1a9b917d65fe01617fefbe0fa2b85ff65748c66846f174574ee90 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/error-response-codes.md -->

# HTTP Status Codes and Errors

To help you handle errors and special cases, the B2C Commerce APIs (SCAPI) return HTTP status codes and error messages.

The following tables list HTTP status codes and typical use cases.

## Success Status Codes

| HTTP Status Code   | Use Cases                                                                                                  |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| 200 (OK)           | GET, PUT, or POST request successfully completed.                                                          |
| 201 (Created)      | POST or PUT request successfully created a new resource or relationship resource.                          |
| 204 (No Content)   | Request successfully completed and returned no content.                                                    |
| 207 (Multi-Status) | Request succeeded with multiple status results for suboperations, for example: batch or partial responses. |

## Error Status Codes

| HTTP Status Code             | Use Cases                                                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 (Bad Request)            | Request contains invalid information, such as malformed parameters, malformed header values, or a malformed body.                           |
| 401 (Unauthorized)           | Request is not authorized to be processed.                                                                                                  |
| 403 (Forbidden)              | Request is declined by the server.                                                                                                          |
| 404 (Not Found)              | Requested resource does not exist.                                                                                                          |
| 405 (Method Not Allowed)     | Resource does not support supplied HTTP method.                                                                                             |
| 409 (Conflict)               | The request could not be completed due to a conflict with the current state of the resource.                                                |
| 412 (Precondition Failed)    | PATCH request provided an outdated last-known base point, which means the resource was changed on server, possibly by a concurrent request. |
| 415 (Unsupported Media Type) | Media type specified in "format" request parameter (or Accept header) is not supported.                                                     |
| 500 (Internal Server Error)  | Request cannot be fulfilled because of an unexpected condition on the server.                                                               |

## Common SCAPI Error Messages by HTTP Status Code

All B2C Commerce APIs share some common error messages, which can be returned by any API.
Documentation on the API level focuses on API-specific error messages.

#### 400 (Bad Request)

| Type                        | Detail                                                                              |
| --------------------------- | ----------------------------------------------------------------------------------- |
| missing-query-parameter     | Missing required query parameter(s): '{missingParams}'                              |
| undefined-query-parameter   | Query parameter '{undefinedParam}' is not defined in the API.                       |
| value-constraint-violation  | Value for parameter '{parameterName}' violates API constraint '{constraintName}'.   |
| constraint-violation        | '{parameterName}' value constraint violated. Expected value is between '(x..y)'.    |
| adhoc-logging-not-supported | This API does not support `sdfc-log-level` or `sfdc-verbose headers`. Remove these. |
| incorrect-preflight         | A preflight request was malformed or incomplete: {detail}                           |

#### 401 (Unauthorized)

| Type         | Detail               |
| ------------ | -------------------- |
| unauthorized | Unauthorized request |

#### 403 (Forbidden)

| Type      | Detail                                     |
| --------- | ------------------------------------------ |
| forbidden | Access to requested resource is forbidden. |

#### 404 (Not Found)

| Type                   | Detail                                                       |
| ---------------------- | ------------------------------------------------------------ |
| resource-not-found     | Could not find requested resource.                           |
| organization-not-found | No organization found for organizationId '{organizationId}'. |

#### 405 (Method Not Allowed)

| Type                | Detail                                                        | Additional Information                                                                                                           |
| ------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| method-not-allowed  | The request method is not allowed for the requested resource. |                                                                                                                                  |
| custom-apis-options | The OPTIONS method is not supported for custom APIs.          | [Troubleshooting Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-troubleshooting.html) |

#### 413 (Payload Too Large)

| Type                 | Detail                                      |
| -------------------- | ------------------------------------------- |
| request-uri-too-long | Request URL length limit has been exceeded. |

#### 414 (Payload Too Large)

| Type              | Detail                                                              | Additional Information                                                                                        |
| ----------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| payload-too-large | The request payload or request header size is too large to process. | [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) |

#### 415 (Unsupported Media Type)

| Type                     | Detail                                                                        |
| ------------------------ | ----------------------------------------------------------------------------- |
| missing-content-type     | The Content-Type header is missing. Expected: '{expected}'                    |
| unsupported-content-type | The media type in Content-Type header isn't supported. Expected: '{expected}' |
| unsupported-content-type | The charset in Content-Type header isn't supported. Expected: '{expected}'    |

#### 429 (Too Many Requests)

| Type              | Detail                                                                              |
| ----------------- | ----------------------------------------------------------------------------------- |
| too-many-requests | You have performed too many requests with ad hoc logging in a short period of time. |

#### 500 (Internal Server Error)

| Type                  | Detail                |
| --------------------- | --------------------- |
| internal-server-error | Internal Server Error |

#### 503 (Service Unavailable)

| Type                     | Detail                                                                                                               | Additional Information                                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| service-unavailable      | The request could not be processed at this time.                                                                     |                                                                                                                        |
| service-unavailable      | The request has been throttled due to high resource consumption on server side. See 'sfdc_load' headers for details. |                                                                                                                        |
| system-under-maintenance | The request could not be processed as the system is currently under maintenance.                                     | [Maintenance Response Codes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/response-handling.html) |
| site-under-maintenance   | The request could not be processed as the site is currently under maintenance.                                       | [Maintenance Response Codes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/response-handling.html) |

#### 504 (Request Timeout)

If responding to a SCAPI request takes too long, a HTTP 504 status code is returned:

| Type            | Detail                                                                         | Additional Information                                                                                                       |
| --------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| request-timeout | The request could not be processed by the system within the timeout threshold. | [Troubleshoot Request Timeouts](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeout-troubleshoot.html) |

```json
{
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/request-timeout",
  "title": "Request Timeout",
  "detail": "The request could not be processed by the system within the timeout threshold."
}
```

By default, Shopper API requests must respond within 10 seconds, and Custom API and SCAPI Admin API requests within 60 seconds. These timeouts are configurable via the [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary). If a response to a SCAPI request exceeds the timeout threshold, the HTTP 504 status code is returned.

If you are encountering issues with timeouts, seek to optimize your hook implementations.

**note:** Some API families, such as SLAS and Omnichannel Inventory (OCI), do not have gateway timeouts.

### Error Response Format

For status codes greater than or equal to 400, the API returns an error response following the [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) format, for example:

```json
{
  "title": "You do not have enough credit",
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-enough-money",
  "detail": "Your current balance is 30, but that costs 50",
  "instance": "/account/12345/msgs/abc"
}
```

The error response contains the following properties:

- `title`: A short, human-readable summary of the problem type. It won't change from occurrence to occurrence of the problem, except for purposes of localization.
- `type`: A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about:blank".
- `detail`: A human-readable explanation specific to this occurrence of the problem.
- `instance`: A URI reference that identifies the specific occurrence of the problem. It might or might not yield further information if dereferenced.

## Best Practices for Error Handling

When handling SCAPI errors in your application:

1. Always code to the HTTP response status code, not the HTTP response message.
2. Use the last segment of the `type` field to programmatically handle different error scenarios.
3. Consider implementing retry logic for 503 errors, as these are typically temporary server issues.
4. Validate input on the client side to minimize 400 errors.
5. In case of 500 errors with an unknown root cause:
   - Check for customization header (`sfdc_customization_error`). If the value is "1", an error occurred within a hook execution.
   - Copy the `sfdc_correlation_id` response header value to trace down a root cause or open a support case.

<!-- document id=c850a6867ec73c2b90ee0764984bc197089ce47880768d0da12763073414a101 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/httpversions.md -->

# HTTP Versions

OCAPI expects requests and returns responses by default with HTTP version 1.1. However, it is possible to use HTTP version 2 if the instance belongs to the Primary Instance Group \(Production, Staging, and Development\) or is an On-Demand Sandbox \(ODS\). This page describes the difference in HTTP header formats regarding the versions.

## HTTP/1.1

In HTTP/1.1, header names are **case-insensitive**, as per [RFC 2616, Hypertext Transfer Protocol — HTTP/1.1, Section 4.2](https://www.rfc-editor.org/rfc/rfc2616#section-4.2):

Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive.

This means that a specific format must not be assumed by the server or client. Therefore, the response may contain header names in a mixed-case format:

```
Accept-Ranges: bytes
x-dw-request-base-id: RgFS4PN7HWQCABqs
Allow: GET,HEAD,OPTIONS
X-Content-Type-Options: nosniff
x-dw-version-status: deprecated
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
jweb: y
Content-Type: application/json;charset=UTF-8
Content-Length: 864
```

## HTTP/2

In HTTP/2, header names must be **lowercase**, as per [RFC 7540, Hypertext Transfer Protocol Version 2 \(HTTP/2\), Section 8.1.2](https://www.rfc-editor.org/rfc/rfc7540#section-8.1.2):

Just as in HTTP/1.x, header field names are strings of ASCII characters that are compared in a case-insensitive fashion.
However, header field names MUST be converted to lowercase prior to their encoding in HTTP/2. A request or response
containing uppercase header field names MUST be treated as malformed (Section 8.1.2.6).

This means that uppercase header names in the request must not be accepted and the response will always have lowercase names:

```
accept-ranges: bytes
x-dw-request-base-id: RgFS4PN7HWQCABqs
allow: GET,HEAD,OPTIONS
x-content-type-options: nosniff
x-dw-version-status: deprecated
cache-control: max-age=0,no-cache,no-store,must-revalidate
jweb: y
content-type: application/json;charset=UTF-8
content-length: 864
```

## Additional Information

Usually, HTTP clients capable of HTTP/2 will automatically do the format conversion. But it should be noted that header names have been case-insensitive since the publishing of HTTP/1.1 in 1999. As a consequence, code that behaves as case-sensitive \(i.e. it assumes a specific case\) should be fixed in order to avoid issues with future HTTP standards.

<!-- document id=2b3a38126e0de40e0bdc48c936ec1209ba5fabfbd78253dc0a0b7c7679ada67c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/hybrid-auth-environment-matrix.md -->

# Hybrid Auth Environments and Routing (All Architectures)

Hybrid Auth works across all B2C Commerce environments. The core setup is identical in every environment—only the traffic routing differs. Use this page to find the setup guide for your architecture and instance type, see what changes per environment, and decide which routes each runtime owns.

## Setup Guide by Architecture and Environment

Start here. The core Hybrid Auth configuration is the same for every architecture and instance type—only the routing setup differs by environment. Follow the guide for your architecture and instance type:

| Architecture                    | PIG                                                                                                                                                                                                                          | ODS                                                                                                                                     | Localhost                                                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Storefront Next                 | [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid.md)                                                                                                                                       | [Set Up Hybrid on ODS Using eCDN](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-ods.md)                                                             | [Set Up Hybrid Proxy Locally](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-proxy-local-dev.md)                                          |
| PWA Kit / Composable Storefront | [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md)                                                                                                              | [PWA Kit ODS via eCDN](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md#set-up-hybrid-on-on-demand-sandbox-ods-instances-using-ecdn) | [PWA Kit local development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md#set-up-hybrid-locally-for-local-development) |
| Custom headless + SFRA          | [Headless Storefront + SFRA Hybrid Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-manual-setup.md#headless-storefronts--sfrasitegenesis) (Step 4)                                                                                                        | same (Step 4)                                                                                                                           | same (Step 4)                                                                                                                |
| SFRA/SiteGenesis only           | [SFRA and SiteGenesis Hybrid Setup (Existing Customers)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-manual-setup.md#sfrasitegenesis-proper--hybrid-auth-session-extension-and-slas-setup) (Business Manager only; no eCDN unless adding a headless runtime) | same                                                                                                                                    | same                                                                                                                         |

## Configuration by Environment

This table summarizes what differs by instance type, regardless of architecture:

| Environment                   | Description                                               | Hybrid Auth in Business Manager | Runtime Environment Variables | Routing Setup                               |
| ----------------------------- | --------------------------------------------------------- | ------------------------------- | ----------------------------- | ------------------------------------------- |
| PIG (Primary Instance Group)  | Production, staging, and development instances            | Required                        | Required                      | eCDN, configured in the Business Manager UI |
| ODS (On-Demand Sandbox)       | On-demand sandboxes in the Secondary Instance Group (SIG) | Required                        | Required                      | eCDN, configured in the Business Manager UI |
| Localhost (local development) | A headless runtime running locally during development     | Required (target sandbox/site)  | Required for local runtime    | Local proxy-based routing instead of eCDN   |

## Route Ownership

In a hybrid storefront, decide which requests your headless runtime serves and which stay on SFRA/SiteGenesis. The following principles are conceptual guidance—for concrete, copy-ready rules, use the canonical matrix for your architecture below.

- Route top-of-funnel discovery paths (home, category, product, search) to the headless storefront runtime.
- Route transaction-critical legacy flows (cart, checkout, account) to SFRA/SiteGenesis until they are migrated.
- Keep path ownership explicit and avoid ambiguous overlap between runtimes.
- Validate redirects and cookie/session propagation during each path transition.

## Canonical Routing Rules

Use the ready-to-use split configurations in the matrix for your architecture:

- Storefront Next: [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-routing-matrix.md) — Cloudflare rule expressions, `HYBRID_ROUTING_RULES`, and `legacyRoutes` examples, with six ready-to-use split configurations.
- PWA Kit / Composable Storefront: [Hybrid Storefront Routing Matrix (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-routing-matrix.md) — eCDN rule expressions and `app/routes.jsx` filtering, with six ready-to-use split configurations.

To configure eCDN routing rules in the Business Manager UI (PIG and ODS), see [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md).

## Notes

- Do not use localhost proxy settings in production environments.
- Keep SLAS client and site configuration aligned across all environments.
- Validate auth/session sync after every environment change.

<!-- document id=d0e98938271f41674eb0dfd0c6aa3abc845d8f7ca0e458e7ec898d6a075aafe3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/hybrid-auth-troubleshooting.md -->

# Hybrid Auth Troubleshooting

Use this guide to diagnose common Hybrid Auth implementation issues.

## Hybrid Auth Not Applying

- Confirm Hybrid Auth is enabled in Business Manager for the active site.
- Confirm storefront uses the expected SLAS client ID.

## Token or Session Drift Across Runtimes

- Validate SLAS client scope includes `sfcc.session_bridge`.
- Confirm headless runtime forwards and accepts required cookies/headers.
- Confirm route ownership does not cause auth loops between origins.

## eCDN Routing Mismatch

- Validate route rules and order in Business Manager.
- Verify hostnames and target origin configuration.
- Confirm cart/checkout routes still map to intended origin.
- Check hybrid route ownership guidance for your architecture: Storefront Next [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-routing-matrix.md) or PWA Kit [Hybrid Storefront Routing Matrix (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-routing-matrix.md).

## Localhost and Sandbox Differences

- Use proxy routing for localhost, not production eCDN settings.
- Confirm ODS/PIG-specific settings align with environment requirements.
- Confirm environment-specific setup for your architecture: Storefront Next [Set Up Hybrid Proxy Locally](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-proxy-local-dev.md) or PWA Kit [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

## Missing SCAPI Short Code on On-Demand Sandboxes (ODS)

- If session-bridge authentication fails with the error `Cannot construct SLAS session-bridge URL: no ACTIVE SCAPI short code found for this organization`, the ODS realm has no active SCAPI short code.
- Generate a dedicated short code for the realm in Business Manager to resolve the error. No Support ticket is required. The previously shared common short code (`kv7kzm78`) still works, but a dedicated short code is required for SLAS hybrid authentication.
- For instructions, see [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guides/base-url.md#short-code) and [Generate a Short Code and Create an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_generate_a_shortcode_and_api_client_id.htm&type=5).

<!-- document id=5bb388f2e14e20011d6a5666647ce85fc7b77e6952380b2e5319e4a6cecc9a65 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/hybrid-authentication.md -->

# Hybrid Authentication Overview

Starting with B2C Commerce version 25.3, hybrid authentication (Hybrid Auth) replaces Plugin SLAS.

Hybrid Auth keeps SFRA/SiteGenesis session state (`dwsid`) and SLAS authorization state (JWT) synchronized for storefronts that span multiple runtimes. It applies to all hybrid storefront architectures: Storefront Next, PWA Kit (Composable Storefront), and SFRA/SiteGenesis.

The [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-shared-setup.md) covers the architecture-neutral steps that every hybrid storefront needs. After you complete it, follow the implementation guide for your storefront architecture.

## What Hybrid Auth Solves

- Synchronizes shopper auth context between platform-rendered pages and headless pages
- Replaces Plugin SLAS with a platform-native implementation
- Enables consistent handling for Shopper Context, session extension, and Do-Not-Track (DNT) synchronization
- Supports eCDN-based traffic splitting for phased headless rollouts

**note:** For non-PWA Kit headless storefronts, if you're using Hybrid Auth and the `dwsid` cookie exists, include the `sfdc_dwsid` header with the `dwsid` cookie value on all SCAPI calls.

## Benefits

- **Platform-native, no Plugin SLAS**: Launch faster with out-of-the-box authentication that automatically synchronizes data between SFRA/SiteGenesis and headless pages—no Plugin SLAS required.
- **Seamless shopper experience**: Shoppers move across your hybrid site with no disruption or data loss, including synchronized Shopper Context attributes and consistent analytics.
- **Full support for all templates**: A fully productized solution for both SFRA and SiteGenesis eases your path to Composable Storefront.

## Architecture

![B2C Commerce hybrid authentication architecture with SFRA/SiteGenesis and headless storefront components](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-architecture.png '{"class": "image-lg"}')

## Next Steps

1. Choose your architecture in [Select Your Storefront](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-select-storefront.md). For an existing PWA Kit v2.x project, see [Hybrid Auth Implementation with PWA Kit v2.x](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-pwa-kit-v2.md).
2. Complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-shared-setup.md)—the architecture-neutral steps that every hybrid storefront needs.
3. Follow the setup path for your architecture: [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-quick-start.md) (Storefront Next only) or [Manual Setup](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-manual-setup.md) (all other architectures).
4. Review per-environment differences and route ownership in [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-environment-matrix.md).
5. Resolve issues with [Hybrid Auth Troubleshooting](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-troubleshooting.md).

<!-- document id=fc7188449547d056f297d92acd39f67d11fe4794b74977f2e2a23c24e7ed58b0 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/hybrid-storefront-baskets.md -->

# Hybrid Implementation Guidance

A hybrid storefront allows the combination of traditional storefronts built on B2C Commerce with decoupled, headless Composable Storefront sites. B2C Commerce supports hybrid storefront implementations so that you can execute on your headless strategy with reduced cost and faster time to market.

Use a B2C Commerce hybrid implementation to combine Storefront Reference Architecture (SFRA) and script API with Composable Storefront and SCAPI. For example, implement PWA Kit for your product detail pages (PDP) and product listing pages (PLP) while providing your checkout in SFRA. Implementations using Sitegenesis with Composable Storefront are supported, but Sitegenesis implementations with Plugin SLAS are not.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


This hybrid approach offers the following benefits:

- **Flexibility and Customization**: Create tailored storefronts that meet specific business needs and customer expectations.
- **Scalability**: The modular nature of Composable Storefront allows for easy scaling and adaptation to changing requirements.
- **Seamless Integration**: SCAPI ensures seamless integration with B2C Commerce, providing access to a wide range of commerce functionalities.
- **Enhanced User Experience**: By combining the power of SCAPI and the flexibility of Composable Storefront, businesses can deliver personalized and engaging shopping experiences.

**note:** This information does **not** apply if you have a pure SFRA/SiteGenesis (SG) _(controller based)_ storefront or pure PWA Kit _(REST based with SCAPI/OCAPI)_ storefront.

## Hybrid Authentication

Starting with B2C Commerce version 25.3, [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md) replaces Plugin SLAS. Hybrid Auth is a standalone solution for implementations that need both SFRA/SiteGenesis authorization and Shopper Login and API Access Service (SLAS) authorization. This means you need both a `dwsid` (SFRA/SiteGenesis) and a JSON Web Token (SLAS), and these tokens must be kept in sync. Hybrid Auth is an improvement over the Plugin SLAS approach, offering enhanced performance and stability of hybrid storefronts by moving the feature directly into the B2C Commerce platform.

Hybrid storefronts that use Plugin SLAS but are NOT Sitegenesis will continue to work, but we highly encourage adopting hybrid auth.

For implementation details, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md) and [Use Composable Storefront in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-implementation.md).

## Hybrid Storefront Considerations

### Cost to Maintain

Decide on the goals, scope, and timeline for your hybrid (phased headless) rollout. Keep in mind that the longer your site is in hybrid mode, the more time you have to spend on the operating complexity involved. Set a due date for transitioning to a 100% Composable site.

### Performance Optimization

A principal benefit of a single page application (SPA) like PWA Kit is that the app bundle is sent to the client and subsequent page requests can often be served without server requests. For this reason, we highly recommend having more than 1 page on PWA Kit to gain performance and shopper UX efficiencies, for example: instead of just your homepage - migrate your homepage and next 1-2 most common journey steps (homepage & search; homepage & our brand). Use the analytics tools at your disposal to chart these common customer journey paths through your site.

## Hybrid Storefront Best Practices for Working with Baskets

The following sections provide best practices for hybrid storefront implementations, with particular focus on basket management and technical implementation details.

### Avoid Empty Baskets

Only create a basket when there is a need, for example, when adding the first product or storing customer information such as address information. This is a general best practice but is especially important for hybrid storefronts.

### Create or Retrieve a Basket

SFRA/SG (controller-based) storefronts use the Script API `getCurrentOrNewBasket()` to create baskets, while PWA Kit uses SCAPI `POST baskets` to create baskets.

When implementing a hybrid site, use the API that best fits your use case. For example, if you implement your PDP in SFRA or SG, use the Script API `getCurrentBasket()`. If your hybrid site uses PWA Kit for the PDP, use SCAPI `POST baskets`.

This best practice aligns with only creating a basket when adding items to it, not beforehand, in order to avoid empty baskets.

**important:** - Never call SCAPI from Script API controllers. Instead, call the respective Script API function. SCAPI endpoints must be called from PWA Kit.
- Never use getCurrentOrNewBasket() in Custom APIs. Instead, make a POST request to [createBasket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket).

| Technology Stack and Recommendation | SFRA/SG (controller/pipelet only)                                                                                                                                                                    | Headless (SCAPI/OCAPI only)                                                                                                                                                                                                                                                 | Hybrid                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Basket creation                     | [getCurrentOrNewBasket()](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_order_BasketMgr.html#dw_order_BasketMgr_getCurrentOrNewBasket_DetailAnchor) | [POST baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket)                                                                                                                                                 | For PWA Kit, use [POST baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket). <br><br>For SFRA and SG, avoid calls to getCurrentOrNewBasket().                                                                                                                                                               |
| Basket retrieval                    | [getCurrentBasket()](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_order_BasketMgr.html#dw_order_BasketMgr_getCurrentBasket_DetailAnchor)           | [GET baskets/{}](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=getBasket) <br>[GET customers/{}/baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=getCustomerBaskets) | For PWA Kit, use: <ul><li>[GET baskets/{}](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=getBasket)</li><li>[GET customers/{}/baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=getCustomerBaskets).</li></ul> <br>For SFRA and SG, avoid calls to getCurrentBasket(). |

<!--
[//]: # ## Plugin SLAS
[//]: #
[//]: # - Use the latest version of Plugin SLAS to ensure correct session handling.
[//]: # - If you are not using Plugin_SLAS version xxxx or later, or not using Plugin SLAS at all (not recommended), minimize new session creation and reuse existing sessions as much as possible.
[//]: #- For JWT creation for SCAPI/OCAPI calls, refer to [Obtain Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/sessionbridge.html#obtain-session). This is  required for optimal performance.
-->

### Asynchronous Functions

Use caution with asynchronous functions when managing baskets:

- Single page applications (SPA) such as PWA Kit follow a different request execution style than traditional platform development models like SFRA. SPAs provide more focus on a non-blocking architecture, in which APIs are used in an asynchronous way for lazy loading, preloading data, or handling user interactions.
- Consider this request architecture carefully and understand what type of requests are executed when, where, and in what sequence.
- If the same type of request (updating the same data) executes in parallel, those requests can overwrite each other and the last one to complete produces the final result, potentially causing unexpected behavior. For example, a basket that is created through multiple steps, including various data validations and dependencies, can increase the likelihood of race conditions if not correctly implemented. An asynchronous design pattern, for example: promises, async/await, or callbacks, is required to manage dependencies where requests rely on each other's completion and avoid potential issues.

### Hooks

- Do not create baskets in hooks with `getCurrentOrNewBasket()`.
- Avoid using `getCurrentBasket()` in hooks. Instead, use the basket that is passed, for example: [`dw.ocapi.shop.basket.afterPATCH`](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook-method-details.html):

```text
afterPATCH (basket : dw.order.Basket, basketInput : Basket) : dw.system.Status
```

- In general, outgoing calls in hooks should be avoided due to potential challenges with connectivity and latency to other systems. Instead, these calls should be initiated by the client system, such as the server runtime, Backend for Frontend (BFF), or client browser. Specifically, avoid making calls to OCAPI and SCAPI, because internal calls can bind resources, impacting performance and scalability. Additionally, when the same objects are modified in a hook and in an outgoing call, race conditions can occur, leading to unpredictable behavior. The recommended approach is to call the respective Script API function from the hook or call the respective SCAPI resource outside of a hook from the client side.

These are general best practices but are especially important for hybrid storefronts.

### Merge Baskets on Shopper Login

The B2C Commerce platform provides a default, out-of-the-box implementation for merging baskets. Some customers need further customization and can use the sample implementation in this [GitHub gist](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f), which behaves like the default implementation, making it an ideal starting point for customization.

After a guest shopper logs in as a registered shopper, manage the shopper basket with the `dw.order.mergeBasket` hook (added in B2C Commerce version 25.10). Invoke this merge hook using either of these options:

- With a REST API call for headless storefronts (PWA Kit and custom headless)
- Within the controller logic for non-headless storefronts (SFRA/SiteGenesis)

After invoking the hook, verify that the guest shopper's basket is appropriately combined with the registered shopper's basket.

#### Invoke the Hook with the REST API

When you use the `transferBasket` endpoint with the parameter `merge=true`, the guest basket is transferred and becomes the current basket. The `dw.order.mergeBasket` hook is then invoked, merging the registered shopper's basket into the current basket. This API behavior is described in the [`transferBasket`](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=transferBasket) specification.

#### Invoke the Hook with a Custom Controller Implementation

To add the basket merge hook into an existing controller, use the [Script API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html) to transfer the basket from the guest shopper to the registered shopper by calling `BasketMgr.getCurrentBasket()`. Personal information, such as payment and address information, is removed from the guest basket, and it becomes the current basket. Invoke the `dw.order.mergeBasket` hook to process the merge, ensuring a seamless and consistent shopper experience. Use `BasketMgr.getStoredBasket()` to access the registered shopper's basket, which is deleted when the request ends.

For example, to add the basket merge hook for `Account-Login`, append the merge handling to the login function. The [GitHub gist](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f) contains a detailed explanation, but the following example summarizes how baskets can be obtained and merged using the Script API with the `dw.order.mergeBasket` hook:

```javascript
// the (transferred) basket from the previous guest shopper
var currentBasket = BasketMgr.getCurrentBasket();

// the basket from the registered shopper, attached before the login (deleted when the request ends)
var storedBasket = BasketMgr.getStoredBasket();

if (storedBasket && currentBasket) {
  dw.system.HookMgr.callHook("dw.order.mergeBasket", "mergeBasket", storedBasket, currentBasket);
}
```

## Next Steps

- To implement hybrid authentication (recommended), see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md). It replaces Plugin SLAS and is the recommended approach for new and existing hybrid storefronts.
- If you maintain an existing Plugin SLAS storefront, see [Configure a Hybrid Storefront with Plugin SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/phased-headless-rollouts.md) (legacy).

<!-- document id=b6b2bf99f9bc296864b8594c6981ddaba6f45359c651cc206f91fb28376051f0 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/hybrid-upgrade-v2.x.md -->

# Hybrid Stability Upgrade for PWA Kit Version 2.x

This guide explains how to make and verify code changes in a [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md) to:

- Update a Progressive Web App (PWA) Kit project on version 2.8.4 or earlier to implement hybrid stability. This potentially improves the performance of baskets.
- Upgrade from Plugin Shopper Login and API Access Service (Plugin SLAS) version 7.3.0 or later to version 7.4.0.

We recommend testing the steps in a non-production environment before deploying your changes to production.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


**note:** - The steps in this guide apply to a hybrid storefront that uses [Plugin SLAS](https://github.com/SalesforceCommerceCloud/plugin_slas). With B2C Commerce version 25.3, hybrid authentication (auth) replaces Plugin SLAS. For more information, see [Configure a Hybrid Storefront with Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md).
- This guide applies to hybrid storefronts built in part with PWA Kit version 2.8.4 or earlier. For the steps that apply to PWA Kit version 3.x, see [Hybrid Stability Upgrade for PWA Kit Version 3.8.0](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-upgrade-v3.x.md).

## What’s New

To improve stability and performance for hybrid storefronts, we:

- Removed calls to `OCAPI /sessions` from PWA Kit to eliminate session churn (frequent changes to `dwsid`). For more information about `dwsid`, see [Understand Session Management between SFRA and PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html?q=dwsid#understand-session-management-between-sfra-and-pwa-kit).
- Added a header (`sfdc_dwsid`) to Salesforce Commerce API (SCAPI) calls to send the `dwsid` to SCAPI to ensure that requests from a given shopper session are routed to the same app server.
- Removed the Open Commerce API (OCAPI) proxy from the PWA Kit configuration, which makes PWA Kit fully SCAPI-based.

## Prerequisites

If you haven’t already done so, complete these steps.

- [Set Up SLAS for PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#1-set-up-slas-for-pwa-kit).
- Set Up [Session Bridging](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#2-session-bridging).
- Configure [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#3-routing). See also [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html).
- Make [Other Changes to PWA Kit Projects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#5-other-changes-to-pwa-kit-projects).

## Submit a Support Request

Open a support case that asks Salesforce Customer Support to enable Session Override for dwsid. In the support case:

- Request to enable both parent and child toggles.
- Mention your correct realm ID and tenant ID. If you don’t know your realm ID, ask your Account Executive or Customer Success Manager.

## Make PWA Kit Code Changes

If you're using PWA Kit version 2.8.4 or earlier, complete these steps in your project.

1. Check the diff between these files in your project and the files changed in this [pull request](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2036/files).

   - `template-retail-react-app/app/commerce-api/auth.js`
   - `template-retail-react-app/app/commerce-api/index.js`
   - `template-retail-react-app/app/commerce-api/utils.js`

2. Update your project with the new and changed code in the pull request.

## Make Plugin SLAS Code Changes

If you're using Plugin SLAS version 7.3.0 or later, complete these steps.

1. In `cartridges/plugin_slas/cartridge/controllers/Login.js`:

   - Remove the `access_token` cookie after logout in the `/Login-Logout` controller
   - Add `config.ACCESS_TOKEN_COOKIE_NAME` to the `cookiesToRemove` array in the `/Login-Logout` controller.

2. In `cartridges/plugin_slas/cartridge/scripts/helpers/slasAuthHelper.js`, update the `removeCookie` function to remove any existing chunks of cookies:

   - Change the condition from exact match (==) to `.startsWith`.

3. In `cartridges/plugin_slas/cartridge/scripts/hooks/request/onSession.js`, update the `onSession` hook implementation for the new guest shopper flow:
   - Extract the `dwsid` from `x-is-session_id header` into a variable.
   - Use the variable in the call to `getSLASAccessTokenForGuestSessionBridge`.
   - Set the `dwsid` cookie to the response for new guest shoppers.

See the files changed in this [pull request](https://github.com/SalesforceCommerceCloud/plugin_slas/pull/207/files?diff=split).

## Verify Your Code Changes

1. Confirm that PWA Kit isn’t making calls to `OCAPI /sessions`.

   - Go to your storefront and clear all site data.

     If you’re using Chrome DevTools, see [Delete all cache data](https://developer.chrome.com/docs/devtools/storage/cache#deletecache).

   - Refresh your storefront or go to any page that’s PWA Kit-based and inspect the Network Tab in Chrome DevTools. Confirm that you don’t see requests being made to `dw/shop/<version>/sessions`. See this example from Chrome DevTools.

![No Sessions](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/no-sessions.png)

2. Confirm that `dwsid` is sent with all SCAPI requests.

   - Go to your storefront. Visit any SFRA/SG-based page then go to a PWA Kit-based page.
   - If you’re using Chrome DevTools:
     - Open Cookie Storage and look for `dwsid` value in the cookies. See [Open the Cookies pane](https://developer.chrome.com/docs/devtools/application/cookies#open).
     - Open the Network Tab and inspect any SCAPI request (for example, `/baskets`). In the Request Headers, confirm that you see the `sfdc_dwsid` header with the value same as the `dwsid` that you found in the previous step. See this example from Chrome DevTools.

![No Sessions](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/dwsid3.png)

## See Also

- [Configure a Hybrid Storefront with Plugin SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md)
- [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html)
- [Get Started with the B2C Commerce API (SCAPI)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html)
- [Configure a Hybrid Storefront with Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md)
- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)

<!-- document id=30ed144a2e49d38881800577fb8017b79cc836bfed1cd525d618252ace2e5ae1 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/hybrid-upgrade-v3.x.md -->

# Hybrid Stability Upgrade for PWA Kit Version 3.8.0

This guide explains how to make and verify code changes in a [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md) to:

- Update a Progressive Web App (PWA) Kit project from version 3.5.0 or later to version 3.8.0.
- Upgrade from Plugin Shopper Login and API Access Service (Plugin SLAS) version 7.3.0 or later to version 7.4.0.

We recommend testing the steps in a non-production environment before deploying your changes to production.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


**note:** - The steps in this guide apply to a hybrid storefront that uses [Plugin SLAS](https://github.com/SalesforceCommerceCloud/plugin_slas). With B2C Commerce version 25.3, hybrid authentication (auth) replaces Plugin SLAS. For more information, see [Configure a Hybrid Storefront with Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md).
- This guide applies to hybrid storefronts built in part with PWA Kit version 3.5.0 or later. For the steps that apply to PWA Kit version 2.x, see [Hybrid Stability Upgrade for PWA Kit Version 2.x](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-upgrade-v2.x.md).

## What’s New

To improve stability and performance for hybrid storefronts, we:

- Removed calls to `OCAPI /sessions` from PWA Kit to eliminate session churn (frequent changes to `dwsid`). For more information about `dwsid`, see [Understand Session Management between SFRA and PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html?q=dwsid#understand-session-management-between-sfra-and-pwa-kit).
- Added a header to Salesforce Commerce API (SCAPI) calls to send the `dwsid` to SCAPI to ensure that requests from a given shopper session are routed to the same app server.
- Removed the Open Commerce API (OCAPI) proxy from the PWA Kit configuration, which makes PWA Kit fully SCAPI-based.

## Prerequisites

If you haven’t already done so, complete these steps.

- [Set Up SLAS for PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#1-set-up-slas-for-pwa-kit).
- Set Up [Session Bridging](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#2-session-bridging).
- Configure [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#3-routing). See also [CDN APIs for Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html).
- Make [Other Changes to PWA Kit Projects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#5-other-changes-to-pwa-kit-projects).

## Submit a Support Request

Open a support case that asks Salesforce Customer Support to enable Session Override for dwsid. In the support case:

- Request to enable both parent and child toggles.
- Mention your correct realm ID and tenant ID. If you don’t know your realm ID, ask your Account Executive or Customer Success Manager.

## Make PWA Kit Code Changes

If you're using PWA Kit version 3.5.0 or later:

1. To upgrade to the latest version of Commerce SDK React, run:

   `npm install @salesforce/commerce-sdk-react@latest`

2. To upgrade to the latest version of the Retail React App, run:

   `npm install @salesforce/retail-react-app@latest`

## Make Plugin SLAS Code Changes

If you're using Plugin SLAS version 7.3.0 or later, complete these steps.

1. In `cartridges/plugin_slas/cartridge/controllers/Login.js`:

   - Remove the `access_token` cookie after logout in the `/Login-Logout` controller
   - Add `config.ACCESS_TOKEN_COOKIE_NAME` to the `cookiesToRemove` array in the `/Login-Logout` controller.

2. In `cartridges/plugin_slas/cartridge/scripts/helpers/slasAuthHelper.js`, update the `removeCookie` function to remove any existing chunks of cookies:

   - Change the condition from exact match (==) to `.startsWith`.

3. In `cartridges/plugin_slas/cartridge/scripts/hooks/request/onSession.js`, update the `onSession` hook implementation for the new guest shopper flow:
   - Extract the `dwsid` from `x-is-session_id header` into a variable.
   - Use the variable in the call to `getSLASAccessTokenForGuestSessionBridge`.
   - Set the `dwsid` cookie to the response for new guest shoppers.

See the files changed in this [pull request](https://github.com/SalesforceCommerceCloud/plugin_slas/pull/207/files?diff=split).

## Verify Your Code Changes

1. Confirm that PWA Kit isn’t making calls to `OCAPI /sessions`.

   - Go to your storefront and clear all site data.

     If you’re using Chrome DevTools, see [Delete all cache data](https://developer.chrome.com/docs/devtools/storage/cache#deletecache).

   - Refresh your storefront or go to any page that’s PWA Kit-based and inspect the Network Tab in Chrome DevTools. Confirm that you don’t see requests being made to `dw/shop/<version>/sessions`. See this example from Chrome DevTools.

![No Sessions](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/no-sessions.png)

2. Confirm that `dwsid` is sent with all SCAPI requests.

   - Go to your storefront. Visit any SFRA/SG-based page then go to a PWA Kit-based page.
   - If you’re using Chrome DevTools:
     - Open Cookie Storage and look for `dwsid` value in the cookies. See [Open the Cookies pane](https://developer.chrome.com/docs/devtools/application/cookies#open).
     - Open the Network Tab and inspect any SCAPI request (for example, `/baskets`). In the Request Headers, confirm that you see the `sfdc_dwsid` header with the value same as the `dwsid` that you found in the previous step. See this example from Chrome DevTools.

![No Sessions](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/dwsid3.png)

## See Also

- [Configure a Hybrid Storefront with Plugin SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md)
- [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html)
- [Get Started with the B2C Commerce API (SCAPI)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html)
- [Configure a Hybrid Storefront with Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md)
- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)

<!-- document id=3785c95d89479eac0baefdd7c9e094ccf1ae4658aa019ea76854d1b61fe943f3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-hybrid-routing-matrix.md -->

# Hybrid Storefront Routing Matrix

Use this routing matrix to choose a hybrid storefront split between Storefront Next and SFRA/SiteGenesis.

The examples in this guide apply to all hybrid setups:

- For local hybrid proxy setups, set `HYBRID_ROUTING_RULES` in your environment variables.
- For on-demand sandbox (ODS) and production setups, paste the same rule expression directly into eCDN routing rules.

## Use the Right Rule Syntax by Setup Type

Use the same expression pattern in every setup, but use different input formats:

- **Local hybrid proxy (`.env`)**: Assign the rule to `HYBRID_ROUTING_RULES` and wrap the expression in single quotes.
- **ODS and production (eCDN UI)**: Paste only the rule expression in **Rule expression**. Do not include `HYBRID_ROUTING_RULES=` and do not wrap the expression in single quotes.

Example for local hybrid proxy:

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*")'
```

Example for eCDN:

```text
(http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*")
```

## Architectural Foundations

1. `HYBRID_ROUTING_RULES`: A single Cloudflare expression used by the edge routing layer. The pattern supports both unprefixed paths and paths with a `/:siteId/:locale` prefix. Prefix values can be aliases or raw IDs.
2. `PUBLIC__app__hybrid__legacyRoutes`: A JSON array used by the Storefront Next client-side routing middleware to force a full-page navigation to SFRA/SiteGenesis routes.

The examples use the optional prefix pattern `^(/[^/]+/[^/]+)?`. The first segment matches any site value, and the second segment matches any locale value. Each value can be an alias or a raw ID, so the eCDN rule doesn't need an allowlist of every site-locale combination. If your application uses a different `url.prefix` shape, replace the entire sample prefix with a pattern for that shape.

For configurations where Storefront Next handles the Home route, use a separate Home expression: `^(/|/[^/]+/[^/]+/)$`. It matches `/` and a prefixed Home path such as `/us/en-US/`. When an exactly two-segment path represents prefixed Home, end it with a trailing slash; an unprefixed two-segment route must use its canonical form without a trailing slash, such as `/product/123`. This convention lets eCDN distinguish the two shapes without maintaining site and locale allowlists. The expression intentionally doesn't match `/us/en-US` or `/us/en-US/home`. Configure `url.prefix`, generated Home links, and SFRA/SiteGenesis redirects to use the canonical trailing-slash Storefront Next root.

**important:** A prefixed Home URL must end with a trailing slash, for example, `/us/en-US/`. Reserve the exactly-two-segment trailing-slash shape for prefixed Home; don't use that shape for an unprefixed two-segment route such as `/product/123`.

## Matrix Configurations

Check out some examples of the different ways you can set up your hybrid storefront.

### Matrix-01: Modern Core (Home, PDP, PLP on Storefront Next)

- **Strategy:** The active customer discovery funnel, search, account, and social authentication routes run on Storefront Next. Only checkout (`/cart` and `/checkout`) stays on SFRA/SiteGenesis.
- **HYBRID_ROUTING_RULES:**

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/|/[^/]+/[^/]+/)$" or http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search|account|login|signup|logout|reset-password|social-callback)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'
```

- `PUBLIC__app__hybrid__legacyRoutes`:

```bash
PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout"]'
```

### Matrix-02: Modern Checkout (Cart and Checkout on Storefront Next)

- **Strategy:** Use this split to test or roll out a Storefront Next checkout while keeping browse and discovery routes on SFRA/SiteGenesis.
- **HYBRID_ROUTING_RULES:**

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(cart|checkout)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'
```

- `PUBLIC__app__hybrid__legacyRoutes`:

```bash
PUBLIC__app__hybrid__legacyRoutes='["/", "/category/:id", "/product/:id", "/search", "/account", "/login", "/signup", "/reset-password"]'
```

### Matrix-03: Modern Entry Only (Home on Storefront Next)

- **Strategy:** Use this split during early pilots when only the home page is modernized and deeper flows remain on SFRA/SiteGenesis.
- **HYBRID_ROUTING_RULES:**

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/|/[^/]+/[^/]+/)$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'
```

- `PUBLIC__app__hybrid__legacyRoutes`:

```bash
PUBLIC__app__hybrid__legacyRoutes='["/category/:id", "/product/:id", "/search", "/account", "/login", "/signup", "/reset-password", "/cart", "/checkout"]'
```

### Matrix-04: Legacy Entry Only (Home on SFRA)

- **Strategy:** Use this split when the home page stays on SFRA/SiteGenesis, while deeper browse and transactional routes move to Storefront Next.
- **HYBRID_ROUTING_RULES:**

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search|account|login|signup|logout|reset-password|social-callback|cart|checkout)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'
```

- `PUBLIC__app__hybrid__legacyRoutes`:

```bash
PUBLIC__app__hybrid__legacyRoutes='["/"]'
```

### Matrix-05: Catalog-Only Migration (PLP/PDP on Storefront Next)

- **Strategy:** Move high-volume catalog routes (category, product, search) to Storefront Next while preserving legacy account and checkout routes.
- **HYBRID_ROUTING_RULES:**

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'
```

- `PUBLIC__app__hybrid__legacyRoutes`:

```bash
PUBLIC__app__hybrid__legacyRoutes='["/", "/account", "/login", "/signup", "/reset-password", "/cart", "/checkout"]'
```

### Matrix-06: Account and Auth Only (Identity Flows on Storefront Next)

- **Strategy:** Move account and authentication experiences to Storefront Next while leaving catalog and checkout on SFRA/SiteGenesis.
- **HYBRID_ROUTING_RULES:**

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(account|login|signup|logout|reset-password|social-callback)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")'
```

- `PUBLIC__app__hybrid__legacyRoutes`:

```bash
PUBLIC__app__hybrid__legacyRoutes='["/", "/category/:id", "/product/:id", "/search", "/cart", "/checkout"]'
```

## Global Framework Requirements

Keep these route clauses in every matrix configuration:

- `^/resource.*` and `^/action/.*` to avoid loop routing on modern layouts and handlers.
- `.*\.data.*` to prevent React Router 7 data prefetch requests from being routed to SFRA/SiteGenesis.
- `^/assets/.*` and `^/favicon\.ico$` for core Storefront Next static assets.

<!-- document id=5b0a2c0c6339f688ce8b1a2372bf7ea11c4c0ad49ab98e1fede2250ff49554f0 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/hybrid-routing-matrix.md -->

# Hybrid Storefront Routing Matrix (PWA Kit)

Use this routing matrix to choose a hybrid storefront split between PWA Kit (Composable Storefront) and SFRA/SiteGenesis.

PWA Kit hybrid routing has two complementary parts:

1. **eCDN routing rules** — a Cloudflare rule expression that routes matching paths to your Managed Runtime (MRT) environment. Everything else stays on SFRA/SiteGenesis.
2. **`app/routes.jsx` filtering** — remove the SFRA/SiteGenesis-owned routes from your PWA Kit route table so that React Router forces a full-page navigation (instead of a soft, client-side navigation) to those paths.

Keep the two definitions complementary: any path routed to MRT by eCDN should remain in `app/routes.jsx`, and any path owned by SFRA/SiteGenesis should be removed from `app/routes.jsx`.

**note:** This matrix is for PWA Kit. For Storefront Next, see [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-routing-matrix.md).

## Use the Right Rule Syntax by Setup Type

Use the same Cloudflare expression pattern in every environment, but apply it differently:

- **PIG and ODS (eCDN)**: Paste the rule expression into **Rule expression** in the Business Manager eCDN UI, or pass it to the [`createMrtRules`](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=createMrtRules) API. When you use the API, also scope the expression to your hostname with `http.host`. For the setup steps, see [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md).
- **Local development (hybrid proxy)**: eCDN isn't available on `localhost`. Use the PWA Kit hybrid proxy instead. See [Set Up Hybrid Locally for Local Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md#set-up-hybrid-locally-for-local-development).

## Architectural Foundations

- **eCDN MRT rule expression**: A single Cloudflare expression evaluated at the edge. Requests whose path matches the expression are routed to Managed Runtime (PWA Kit); all other requests go to SFRA/SiteGenesis. The matrix expressions support paths without a prefix and paths with a two-segment `/:site/:locale` prefix, such as `/category/mens` and `/us/en-US/category/mens`.
- **`app/routes.jsx`**: The PWA Kit client-side route table. Remove SFRA/SiteGenesis-owned routes so PWA Kit hard-navigates to them. For projects that use template extensibility, override `overrides/app/routes.jsx`.

The route patterns below use the default Retail React App routes (`/`, `/category/:categoryId`, `/product/:productId`, `/search`, `/account`, `/login`, `/registration`, `/reset-password`, `/cart`, `/checkout`). Adjust them to match your project's routes.

The examples use the optional prefix pattern `^(/[^/]+/[^/]+)?`. The first segment matches any site value, and the second segment matches any locale value. Each value can be an alias or a raw ID, so the eCDN rule doesn't need an allowlist of every site-locale combination. If your application uses a different prefix shape, replace the entire sample prefix with a pattern for that shape.

For configurations where PWA Kit handles the Home route, the dedicated Home expression `^(/|/[^/]+/[^/]+/)$` matches `/` and a prefixed Home path such as `/us/en-US/`. When an exactly two-segment path represents prefixed Home, end it with a trailing slash; an unprefixed two-segment route must use its canonical form without a trailing slash, such as `/product/123`. This convention lets eCDN distinguish the two shapes without maintaining site and locale allowlists. The expression intentionally doesn't match `/us/en-US` or `/us/en-US/home`. Configure generated Home links and SFRA/SiteGenesis redirects to use the canonical trailing-slash PWA Kit root.

**important:** A prefixed Home URL must end with a trailing slash, for example, `/us/en-US/`. Reserve the exactly-two-segment trailing-slash shape for prefixed Home; don't use that shape for an unprefixed two-segment route such as `/product/123`.

## Matrix Configurations

Each configuration lists the eCDN rule expression (paths routed to PWA Kit on MRT) and the routes to remove from `app/routes.jsx` (paths owned by SFRA/SiteGenesis).

### Matrix-01: Modern Core (Home, PDP, PLP on PWA Kit)

- **Strategy:** The discovery funnel, search, account, and authentication routes run on PWA Kit. Only checkout (`/cart` and `/checkout`) stays on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/|/[^/]+/[^/]+/)$" or http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search|account|login|registration|reset-password)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/cart`, `/checkout`

### Matrix-02: Modern Checkout (Cart and Checkout on PWA Kit)

- **Strategy:** Test or roll out a PWA Kit checkout while keeping browse and discovery routes on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(cart|checkout)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`, `/category/:categoryId`, `/product/:productId`, `/search`, `/account`, `/login`, `/registration`, `/reset-password`

### Matrix-03: Modern Entry Only (Home on PWA Kit)

- **Strategy:** An early pilot where only the home page is modernized and deeper flows remain on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/|/[^/]+/[^/]+/)$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/category/:categoryId`, `/product/:productId`, `/search`, `/account`, `/login`, `/registration`, `/reset-password`, `/cart`, `/checkout`

### Matrix-04: Legacy Entry Only (Home on SFRA)

- **Strategy:** The home page stays on SFRA/SiteGenesis, while deeper browse and transactional routes move to PWA Kit.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search|account|login|registration|reset-password|cart|checkout)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`

### Matrix-05: Catalog-Only Migration (PLP/PDP on PWA Kit)

- **Strategy:** Move high-volume catalog routes (category, product, search) to PWA Kit while preserving legacy account and checkout routes.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(category|product|search)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`, `/account`, `/login`, `/registration`, `/reset-password`, `/cart`, `/checkout`

### Matrix-06: Account and Auth Only (Identity Flows on PWA Kit)

- **Strategy:** Move account and authentication experiences to PWA Kit while leaving catalog and checkout on SFRA/SiteGenesis.
- **eCDN rule expression:**

```text
(http.request.uri.path matches "^(/[^/]+/[^/]+)?/(account|login|registration|reset-password)(/.*)?$" or http.request.uri.path matches "^/mobify.*" or http.request.uri.path matches "^/callback.*" or http.request.uri.path matches "^/worker\.js.*")
```

- **Remove from `app/routes.jsx`:** `/`, `/category/:categoryId`, `/product/:productId`, `/search`, `/cart`, `/checkout`

## Global Framework Requirements

Keep these route clauses routed to Managed Runtime in every matrix configuration. PWA Kit's server-side rendering system relies on them:

- `^/mobify.*` for PWA Kit internal proxies and static assets.
- `^/callback.*` for the SLAS authentication callback.
- `^/worker\.js.*` for the PWA Kit service worker.

For the catch-all route, update the PWA `/*` route in `app/routes.jsx` to redirect to the default origin instead of rendering `<PageNotFound />`. For the full procedure, see [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md#step-3-update-pwa-kit-routes).

<!-- document id=5e1c47f6c477dddcc051d95671e04446c0a5d27f1b633b494130b7faac37e522 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ops-troubleshooting/b2c-identifying-staging-problems.md -->

# Identify Staging Problems

To troubleshoot issues with replicating from a staging environment to a production or development environment, follow this process.

When staging problems occur, isolating problem causes can help formulate a solution.

**note:** This example covers staging from the Staging environment to Production, but the same steps apply to any staging process running from staging to development.

1.  Monitor the job status of the data replication process on the Staging instance.

2.  If it fails, look at the staging logs for failure messages.

3.  Look at the staging logs of the Staging instance first.

4.  Look at the most recent staging log file. A single staging log often contains several days' worth of staging events in one file.

    ```
     https://staging.web.customerName.demandware.net/on/
    demandware.servlet/webdav/Sites/Logs
    ```

    This only works with Firefox. Microsoft Internet Explorer isn't supported.

5.  Look for the beginning of the replication process in the logs. It will have a similar timestamp to the data replication task you started. (individual tasks created in Business Manager)

    ```
    [2007-01-15 21:17:12.848 GMT] ISH-CORE-2250: New replication task "1168895828901" in domain "Sites-Site" successfully created.
    [2007-01-15 21:18:34.171 GMT] ISH-CORE-2250: New replication task "1168895910472" in domain "Sites-customerName" successfully created.
    [2007-01-15 21:21:13.574 GMT] ==========================================================================
    [2007-01-15 21:21:13.574 GMT] ReplicationPublication process created.
    [2007-01-15 21:21:13.575 GMT] Start date: Mon Jan 15 21:21:12 GMT 2007
    [2007-01-15 21:21:13.575 GMT] TargetSystem: Production (http://216.75.207.174:80)
    [2007-01-15 21:21:13.575 GMT] Process uuid: bcvh6iaalTxJYaaacowN3YFqCG)
    [2007-01-15 21:21:13.575 GMT] --------------------------------------------
    ```

6.  Scroll down through the log file. You will see the job go through steps such as gathering stats for all tables:

    ```
    [2007-01-15 21:27:06.602 GMT] ISH-CORE-2070: SQL (64ms, rows=1): begin dbms_stats.gather_table_stats(user, 'PRODUCTOPTION_AV$1', method_opt => 'for all indexed columns', cascade => TRUE); end;
    [2007-01-15 21:27:06.654 GMT] ISH-CORE-2070: SQL (52ms, rows=1): begin dbms_stats.gather_table_stats(user, 'PRODUCTOPTION$1', method_opt => 'for all indexed columns', cascade => TRUE); end;
    [2007-01-15 21:27:06.826 GMT] ISH-CORE-2070: SQL (171ms, rows=1): begin dbms_stats.gather_table_stats(user, 'BUNDLEASSIGNMENT$1', method_opt => 'for all indexed columns', cascade => TRUE); end;
    [2007-01-15 21:27:06.869 GMT] ISH-CORE-2070: SQL (43ms, rows=1): begin dbms_stats.gather_table_stats(user, 'PRODUCTOPTIONPRICE_AV$1', method_opt => 'for all indexed columns', cascade => TRUE); end;
    [2007-01-15 21:27:06.869 GMT] ISH-CORE-2067: Starting new transaction...
    [2007-01-15 21:27:06.872 GMT] ISH-CORE-2069: Commit transaction.
    [2007-01-15 21:27:06.882 GMT] ISH-CORE-2067: Starting new transaction..
    ```

7.  Next you will see the rsynch running which gets the actual file system directories ready for copying to the target instance

    ```
    2007-01-15 21:27:08.317 GMT] StagingGroup: Site specific content search index (Relative directory: search/content)
    [2007-01-15 21:27:08.317 GMT] ISH-CORE-2486: Synchronize Files of unit 'Sites-customerName-Site' in site 'Sites-customerName-Site' to exchange directory at '/remote/aaas/staging/stg'.
    [2007-01-15 21:27:08.318 GMT] Executing command: /build/2.0.0/system/bin/synchronize.sh /remote/aaas/aaas_stg/sharedata/sites/Sites-customerName-Site/1/search/content/
    /remote/aaas/staging/stg/Sites-customerName-Site/search/content/ ()
    [2007-01-15 21:27:08.402 GMT] rsync debug (/usr/bin/rsync -tr --delete /remote/aaas/aaas_stg/sharedata/
    sites/Sites-customerName-Site/1/search/content/ /remote/aaas/staging/stg/Sites-customerName-Site/
    search/content/)
    [2007-01-15 21:27:08.476 GMT] ISH-CORE-1956: Files in path 'search/content' of site 'Sites-customerName-Site' are successfully prepared
    ```

8.  The final step on the Staging instance should be a handoff to the target (Production server). Its staging log entry resembles the following line.

    ```
    [2007-01-15 21:27:09.783 GMT] Staging pipeline in live system successfully called.
    ```

9.  If you don't see this success message, look for errors such as the following and follow the recommended steps.

    ```
    ISH-CORE-2491: Setting state of process with uuid='dC8KAANna1AAAAEOTN9h9md4' from 'StartingStagingProcess' to 'ErrorAcquiringEditingLocks
    ```

## Fix Staging Problems

If you identify a staging problem, follow this process.

1.  Stop and restart the staging and target instance via Control Center.

2.  Repeat the failed staging process with the same parameters.

3.  If the staging environment log shows no errors, look at the production staging log.

    ```
    https://production-web-customerName.demandware.net/on/demandware.servlet/webdav/Sites/Logs
    ```

4.  Production staging logs will start with a message that looks like this.

    ```
    2007-01-15 20:29:30.321 GMT] Copy staging process with uuid=bcFvkiaalTMxMaaaco4bVYFqBX[2007-01-15 20:29:32.347 GMT] Starting StagingResources-Acquire@Sites-Site (
    ```

5.  Depending on what you are staging, you will see the database table copy begin.

    ```
    [2007-01-15 20:30:20.296 GMT] ISH-CORE-2070: SQL (123ms, rows=1): INSERT /*+ APPEND */ INTO CATALOG$1 dest SELECT CATALOGDOMAINID,ID,TYPECODE,STATUS,PROXYFLAG,STARTMAINTENANCE,
    ENDMAINTENANCE,POSITION,UUID,OCA,DOMAINID,LASTMODIFIED FROM CATALOG$S src WHERE src.DOMAINID NOT IN ('bcIxgiaalXEYQaaacmKaN9rLDa')
    [2007-01-15 20:30:20.665 GMT] ISH-CORE-2070: SQL (369ms, rows=0): TRUNCATE TABLE CATALOGSITEASSIGNMENT$1 REUSE STORAGE
    [2007-01-15 20:30:20.769 GMT] ISH-CORE-2070: SQL (100ms, rows=1): INSERT /*+ APPEND */ INTO CATALOGSITEASSIGNMENT$1
    ```

6.  After copying, we switch from temp to source tables $2 to $1.

    ```
    [2007-01-15 20:35:43.935 GMT] ISH-CORE-2300: <dbms_output> Switching synonym PRODUCT_AV from PRODUCT_AV$2 to PRODUCT_AV$1...
    [2007-01-15 20:35:43.935 GMT] ISH-CORE-2300: <dbms_output> Switching synonym DELETEDPRODUCT from DELETEDPRODUCT$2 to DELETEDPRODUCT$1...
    [2007-01-15 20:35:43.935 GMT] ISH-CORE-2300: <dbms_output> Switching synonym PRODUCT from PRODUCT$2 to PRODUCT$1...
    [2007-01-15 20:35:43.935 GMT] ISH-CORE-2300: <dbms_output> Switching synonym PRODUCTLINK from PRODUCTLINK$2 to PRODUCTLINK$1...
    [2007-01-15 20:35:43.935 GMT] ISH-CORE-2300: <dbms_output> Switching synonym PRODUCTOPTION from PRODUCTOPTION$2 to PRODUCTOPTION$1
    ```

7.  If it finishes successfully, you will see the following message at the end of the logs.

    ```
    [2007-01-15 21:31:17.434 GMT] ReplicationPublication process finished with state 'StagingProcessCompleted'.
    [2007-01-15 21:31:17.435 GMT] Process uuid: cfbcMiaalTlpoaaado7llYFqCL)
    [2007-01-15 21:31:17.435 GMT] End date: Mon Jan 15 21:31:16 GMT 2007
    [2007-01-15 21:31:17.435 GMT] =======================================
    ```

<!-- document id=11aeed93f2e55ef810d7ae76871aa0fe29e53370c04171777a61e9c110173eeb url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-image-optim.md -->

# Image Optimization Best Practices

Maintain fast and responsive websites on tablets, mobiles, and desktops by tailoring image sizes to adjust based on a device’s screen resolution. This section includes best practices to ensure images on your customer’s store are responsive, load faster, and have no layout shifts.

## Switch Resolution Based on the Browser Size

Ensure your customer’s browser picks responsive and optimized images based on their device screen size. When you build custom components, implement attributes, `srcset` and `sizes`, in the `img` element.

`srcset` defines a set of images based on the device's screen size and resolution. The `srcset` attribute helps you define multiple image sources of different widths, separated by a comma. Browser picks the most appropriate image, based on the screen size and resolution. The attribute sizes define the size of the image element. You can use any length value to represent the size, but not percentages. For example, the size can represent the absolute width (480 px) or a width relative to the viewport (50 vw).

For example, consider an image with these attributes:

```javascript/js
<img
  srcset="product-480w.jpg 480w, product-800w.jpg 800w"
  sizes="(max-width: 600px) 480px,800px"
  src="product-800w.jpg"
  alt="Product Image">
```

From the example,

- `(product-480w.jpg)` represents the image filename and type, and(480w)represents the image’s intrinsic width in pixels.
- `(max-width: 600px)480px` represents that if the viewport width is up to 600 px, each image takes up 480-px width.

You can also provide a better user experience for customers using stores by specifying the `srcset` in the picture element to include a higher resolution version of the image. For example, consider a picture element where the `srcset`attribute has x-descriptors and the`sizes` attribute isn’t defined.

```javascript/js
<picture>
  <source srcset="product.png?width=400, product.png?width=800 2x">
  <source media="(max-width: 800px)" srcset="product.png?width=200, product.png?width=400 2x">
  <img src="product.png" alt="Product Image">
</picture>
```

If the device accessing the page has a standard or a low-resolution display, with one device pixel representing each CSS pixel, the `product.png?width=400` image is displayed. Whereas if the device has a high resolution of two device pixels per CSS pixel or more, the `product.png?width=800` image is displayed.

## Avoid Cumulative Layout Shifts

Ensure that your customer’s browser can reserve the appropriate amount of space in the layout before the images are fully loaded, thus preventing any disruptive shifts. Define the image's aspect ratio, which is the ratio of width to height. This example shows how width and height are defined for an image.

```javascript/js
<img
  src="product.png"
  width="800px" height="800px"
  alt="Product Image">
```

This example shows the width and aspect ratio attributes added to the image.

```javascript/js
//html
<img
  src="product.png"
  alt="Product Image">

//css
img {
  width: 800px;
  aspect-ratio: 1/1;
}
```

## Improve Image Loading Time

Ensure images have a high quality and small size, for a quicker loading time. Leverage the built-in image scaling CDN (Content Delivery Network) and CMS (Content Management System) capabilities. Automatically scale images, instead of uploading the same image in different sizes. By using the resource resolver from experience/resourceResolver, component developers can leverage a URL resolver that works for both CDN and CMS.  
Here’s an example of how to scale images to the appropriate sizes for the various devices and screen resolutions.

```javascript/js
import { resolve } from 'experience/resourceResolver';

// External URL && Cloudflare
const externalUrl = resolve('https://www.imageserver/product.png', true, { width: 800, height: 800 });
console.log(externalUrl)
// {storeHostname}/cdn-cgi/images/width=800&height=800/https://www.imageserver/product.png

// CMS URL && no CDN
const cmsUrl = resolve('cms/sfsites/product.png', true, { width: 800, height: 800 });
console.log(cmsUrl)
// cms/sfsites/product.png?width=800&height=800
```

## Enhance Image Using the Experience-Picture Component

If you prefer to customize an image with appropriate source elements, and not create the attributes `srcset` and `sizes`, use the experience-picture component. This component allows you to define multiple sources for the image based on factors such as device resolution, viewport size, and pixel density.

The component exposes these properties

| Property        | Type                       | Default   | Description                                                                                                                                                                                                                                       |
| --------------- | -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alternativeText | string \| undefined        | undefined | The alternative text for the image. This value is set to empty for decorative images.                                                                                                                                                             |
| loading         | lazy \| eager \| undefined | eager     | Determines how the image is loaded on a webpage.                                                                                                                                                                                                  |
| url             | string \| undefined        | undefined | The placeholder image if the specified image isn’t found or unable to load.                                                                                                                                                                       |
| images          | ImageData\[\] \| undefined | undefined | The srcSet for each form factor or media query. Either use CustomizedImageData with your own media query or use the PredefinedImageData with the formFactor name and a media query based on the SLDS breakpoints, which is created automatically. |

Consider this example that explains how to use the component.

```javascript/js
 ## Image Types
type CustomizedImageData =
{
  /**
  * media condition that defines breakpoint
  * optional - if unset the slds default can be used by setting the formFactor
  */
  media?: string;

  /**
  * defines a set of source sizes, each containing a media condition and a size value
  * (min-width: 768px) 700px,
  * (min-width: 1024px) 600px,
  * 500px
  */
  sizes: string;

  /**
  * defines image sources containing an url followed by a whitespace and either a width descriptor or pixel density
  * product-small.jpg 700w,
  * product-medium.jpg 1200w,
  * product-large.jpg 1600w
  */
  srcSet: string;
};

type PredefinedImageData =
{
  /**
  * used to mimic the slds breakpoints for different screen sizes
  */
  formFactor: FormFactor;

  /**
  * defines a set of source sizes, each containing a media condition and a size value
  * (min-width: 768px) 700px,
  * (min-width: 1024px) 600px,
  * 500px
  */
  sizes?: string;

  /**
  * defines image sources containing an url followed by a whitespace and either a width descriptor or pixel density
  * product-small.jpg,
  * product-medium.jpg 2x,
  * product-large.jpg 3x
  */
  srcSet: string;
};

export type ImageData = PredefinedImageData | CustomizedImageData;
export type FormFactor = 'mobile' | 'tablet' | 'desktop';

```

Additionally you can use a utility method from `experience/picture` to create those srcSets based on
the image widths of your component.

```html
type ImageSizes = Record<FormFactor, number>;
createImageDataMap(url, [ImageSizes], [devicePixelRatio])
```

Here’s an example:

```javascript/js
createImageDataMap(
  'https://example.com/image.jpg',
  {
    mobile: 200,
    tablet: 400,
    desktop: 600
  }
  [1, 2]
)

--> returns a srcSet for each of the form factors
[
  {
    formFactor: 'mobile'
    srcSet: 'https://example.com/image.jpg?width=200,
    https://example.com/image.jpg?width=400 2x'
  },
  {
    formFactor: 'tablet'
    srcSet: 'https://example.com/image.jpg?width=2=400,
    https://example.com/image.jpg?width=800 2x'
  }
  {
    formFactor: 'desktop'
    srcSet: 'https://example.com/image.jpg?width=600,
    https://example.com/image.jpg?width=800 2x'
  }
]
// The picture component uses these media queries for the different form factors
export const MEDIA_QUERIES: { mobile: string; tablet: string; desktop: string } =
{
  mobile: '(max-width: 47.9375em)',
  tablet: '(max-width: 64em)',
  desktop: '(min-width: 64.0625em)',
};
<experience-picture
  alternative-text="Product Image"
  url="https://example.com/image.jpg"
  images="{images}"
></experience-picture>

--> inside the picture component this html is generated
<picture>
  <source
    media="(min-width: 64.0625em)"
    srcset="https://example.com/image.jpg?width=600, https://example.com/image.jpg?width=800 2x"
  />
  <source
    media="(max-width: 64em)"
    srcset="https://example.com/image.jpg?width=400, https://example.com/image.jpg?width=800 2x"
  />
  <source
    media="(max-width: 47.9375em)"
    srcset="https://example.com/image.jpg?width=200, https://example.com/image.jpg?width=400 2x"
  />
  <img src="https://example.com/image.jpg" alt="Product Image" />
</picture>
```

<!-- document id=9dff045037a90eddd1603dabc99354fc03bec59ba6ea25a8aea00dc6f8d8238d url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-images.md -->

# Images

Use the Dynamic Imaging Service (DIS) and the `<DynamicImage>` component to deliver optimized, responsive images in your storefront. DIS formats the correct size for each image application and eliminates the need of uploading multiple images with different sizes.

Images are typically the single largest contributor to page weight. Unoptimized images directly degrade Core Web Vitals, increasing Largest Contentful Paint (LCP) and slowing Time to Interactive. Storefront Next provides built-in DIS integration that handles format conversion, server-side resizing, and responsive source generation automatically.

## Dynamic Imaging Service (DIS)

Salesforce B2C Commerce's [Dynamic Imaging Service](https://help.salesforce.com/s/articleView?id=cc.b2c_image_transformation_service.htm&type=5) (DIS) is an image transformation service that optimizes images on-the-fly. Instead of storing pre-generated image variants, DIS transforms images at request time based on URL parameters. CDNs in front of DIS cache the transformed results at the edge.

### Why Use DIS

DIS addresses image optimization at the infrastructure level:

- **Format conversion**: Serves modern formats like WebP (25–35% smaller than JPEG/PNG) with automatic fallback. The `sfrm` (source format) parameter tells DIS the original format so it can transcode on the fly.
- **Server-side resizing**: Sends each device exactly the pixels it needs. A mobile phone receives a 400px-wide image, not a 1400px desktop image downscaled in the browser. When only `sw` (scale width) is set, DIS scales proportionally. When both `sw` and `sh` (scale height) are set, DIS scales the image to those exact output dimensions, constraining the aspect ratio.
- **Quality control**: The `q` parameter lets you balance visual fidelity against file size. The default `q=70` is a good baseline for commerce product photography.

### DIS URL Anatomy

Storefront Next rewrites static B2C Commerce image URLs into DIS URLs with transformation parameters:

```
Original (static asset):
https://demo-001.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-catalog/default/.../image.jpg

DIS URL:
https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/DEMO_001/on/demandware.static/-/Sites-catalog/default/.../image.webp?sfrm=jpg&sw=720&sh=480&q=70
        └─────────────── DIS Host ──────────────┘           └ Realm ┘                                                       └─ Format(s) ─┘└──── Params ────┘
```

**Parameters used by `<DynamicImage>`:**

| Parameter | Full Name     | Description                                                                                    | Example    |
| --------- | ------------- | ---------------------------------------------------------------------------------------------- | ---------- |
| `sw`      | `scaleWidth`  | Scale width. Resizes to this width in pixels. When used alone, aspect ratio is preserved.      | `sw=720`   |
| `sh`      | `scaleHeight` | Scale height. When combined with `sw`, scales to exact dimensions (constraining aspect ratio). | `sh=480`   |
| `q`       | `quality`     | Quality: 1 to 100. Controls compression level.                                                 | `q=70`     |
| `sfrm`    | —             | Source format. Tells DIS the original format for transcoding.                                  | `sfrm=jpg` |

The file extension in the URL path determines the **output** format (for example, `.webp`), while `sfrm` records the original format.

**Additional DIS parameters** not used by `<DynamicImage>` (but available for custom URL construction):

| Parameter              | Full Name                                   | Description                                                                                                                           |
| ---------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `sm`                   | `scaleMode`                                 | Controls scaling behavior: `fit` (default, fits within `sw`×`sh` preserving aspect ratio), `cut` (fills `sw`×`sh` and crops overflow) |
| `cx`, `cy`, `cw`, `ch` | `cropX`, `cropY`, `cropWidth`, `cropHeight` | Pixel-precise crop region. All four parameters must be specified together.                                                            |
| `bgcolor`              | —                                           | Background color for transparent areas (6-digit hex, for example `bgcolor=FFFFFF`)                                                    |
| `strip`                | —                                           | Remove image metadata (for example, EXIF)                                                                                             |

### Configuration

Configure DIS behavior in `config.server.ts` under the `images` key:

```typescript
images: {
    quality: 70,            // Default DIS quality (1-100)
    formats: ['webp'],      // Target format(s) for <source> elements
    fallbackFormat: 'jpg',  // Format for the <img> fallback src
    host: DIS_DEFAULT_HOST, // DIS endpoint URL
    enableDis: true,        // Master switch to enable/disable DIS
    realmHostMappings: [],  // Custom realm mappings for vanity domains
}
```

Override these values per environment with environment variables:

```bash
PUBLIC__app__images__quality=80
PUBLIC__app__images__enableDis=false
PUBLIC__app__images__host=https://edge.dis.commercecloud.salesforce.com
```

**DIS hosts:**

- Staging: `https://edge.disstg.commercecloud.salesforce.com`
- Production: `https://edge.dis.commercecloud.salesforce.com`

When `enableDis` is `false` (for example, in workspace environments), the image system falls back to serving static assets directly. Format conversion, server-side resizing, and `<source>` generation are all skipped.

### Vanity Domains and Custom Realm Mappings

By default, Storefront Next infers the DIS realm from the SFCC hostname. For standard SFCC hostnames — `*.commercecloud.salesforce.com`, `*.demandware.net`, and `*.my.cc.salesforce.com` — the realm is extracted automatically from the first subdomain (for example, `demo-001.dx.commercecloud.salesforce.com` → realm `DEMO_001`).

When your storefront uses a custom or vanity domain (for example, `shop.example.com`), the realm cannot be inferred from the hostname. Use `realmHostMappings` to supply explicit mappings:

```typescript
images: {
    realmHostMappings: [
        { hostSuffix: 'shop.example.com', realm: 'EXAMPLE_001' },
        { hostSuffix: '.acme.io', realm: 'ACME_001' },
    ],
}
```

Matching rules:

- A `hostSuffix` value without a leading dot matches only the exact hostname (for example, `shop.example.com` matches only `shop.example.com`).
- A `hostSuffix` value with a leading dot matches any subdomain (for example, `.acme.io` matches `www.acme.io`, `staging.acme.io`, and so on).
- Realm values are automatically uppercased, so `example_001` and `EXAMPLE_001` are equivalent.
- Custom mappings are checked before the built-in SFCC hostname patterns.

If an image URL does not match any custom mapping or built-in SFCC pattern, `toDisImageUrl()` returns `undefined` and the image is served from its original URL without DIS transformation.

## Image Filtering on Product Listing Pages

Search responses (`fetchSearchProducts`) include an `imageGroups` array on every hit. By default, B2 Commerce API (SCAPI) returns every imageGroup for every variant, which on variant-heavy catalogs can be the dominant contributor to PLP payload size—most of those images are never rendered.

The template restricts the response via SCAPI's [`imgTypes` query parameter](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch) using `config.server.ts`:

```typescript
search: {
  products: {
    images: {
      tile: 'medium',
      swatch: 'swatch',
    },
  },
}
```

Each role names the viewType a specific consumer reads: `tile` for the product tile hero, and `swatch` for the color thumbnails. The search filter derives its `imgTypes` query parameter as the union of these values (deduplicated and joined with `,`), so adding a new role automatically widens the filter. Setting a role to `undefined` opts that role out. Setting all roles to `undefined`, or providing an empty `images: {}`, disables filtering entirely and returns the full payload. `imgTypes` requires `expand=images` and `allImages=true`—both are set by `fetchSearchProducts`.

### Keeping Role-Named Values Aligned with Consumers

If you customize the product tile to read a different viewType (for example, switch the hero from `medium` to `large`), you must update the matching role here. Otherwise, the tile will receive empty image arrays for the unrequested viewType. The built-in consumers that should eventually read from these declarations are:

- `tile` in `src/components/product-image/index.tsx` (currently hardcodes `'medium'`)
- `swatch` in `src/lib/product/product-utils.ts` (`getDecoratedVariationAttributes`, defaults `swatchViewType` to `'swatch'`)

The hardcoded strings in those consumers are tracked for a followup cleanup that derives them from these same role-named declarations, eliminating drift.

## `DynamicImage` Component

`<DynamicImage>` is a responsive image component that generates an optimized `<picture>` element with DIS-powered `<source>` elements and responsive preloading via React 19's [`preload()`](https://react.dev/reference/react-dom/preload) API.

```typescript
import { DynamicImage } from "@/components/dynamic-image";
```

### Basic Usage

```jsx
<DynamicImage src="https://example.com/image.jpg" alt="Product photo" widths={[400, 800, 1200]} />
```

This renders a `<picture>` element with `<source>` elements sized per breakpoint, each requesting a DIS-resized WebP variant with 1x and 2x srcSet descriptors.

### The src Prop and Placeholder Syntax

The `src` prop accepts plain URLs or URLs with **placeholder syntax**: bracket-delimited segments that `DynamicImage` replaces with computed values.

```jsx
// Plain URL. DynamicImage appends sw/sh/q params automatically
<DynamicImage src="https://example.com/image.jpg" widths={[400, 800]} />

// Placeholder syntax. {width} and {height} are replaced per breakpoint
<DynamicImage src="https://example.com/image.jpg[?sw={width}&sh={height}]" widths={[400, 800]} heights={[300, 600]} />

// Inline placeholder in path segment
<DynamicImage src="https://example.com/image[_{width}].jpg" widths={[400, 800]} />
```

The bracket syntax `[...]` marks optional URL segments that are stripped when no dimensions are provided.

### Responsive Widths

The `widths` prop controls how wide each `<source>` requests its image from DIS. It determines the `sw` parameter value and the `sizes` attribute in the generated markup. It accepts three formats:

**Array of numbers** (interpreted as px):

```jsx
<DynamicImage src={imageSrc} widths={[400, 600, 800, 1000]} />
```

**Array of strings** (px or vw units):

```jsx
// Mixed units: vw for fluid layouts, px for fixed layouts
<DynamicImage src={imageSrc} widths={["100vw", "50vw", "680px"]} />
```

When using `vw` units, `DynamicImage` calculates the actual pixel width at each breakpoint to request the correct size from DIS.

**Object with breakpoint keys** (maps to Tailwind's default breakpoints):

```jsx
<DynamicImage src={imageSrc} widths={{ base: 400, sm: 600, md: 800, lg: 1000 }} />

// With units
<DynamicImage src={imageSrc} widths={{ base: '100vw', sm: '50vw', md: '680px' }} />
```

Breakpoint keys correspond to Tailwind's default theme: `base`, `sm`, `md`, `lg`, `xl`, `2xl`. Values are carried forward: `{ base: 400, lg: 800 }` produces `[400, 400, 400, 800]`.

Use fixed px widths when the image container has a predetermined size (for example, carousels). Use vw-based widths when the image scales with the viewport (for example, product grids, hero banners).

### Server-Side Scaling with Heights

The `heights` prop enables DIS server-side scaling via the `sh` parameter. When provided alongside `widths`, it defines exact output dimensions, giving you precise aspect ratio control across responsive breakpoints.

```jsx
// 4:3 aspect ratio maintained across all breakpoints
<DynamicImage
  src="https://example.com/image.jpg[?sw={width}&sh={height}]"
  widths={[400, 800, 1200]}
  heights={[300, 600, 900]}
/>
```

Both values are multiplied by the DPR factor. At 2x, `widths={[400]}` and `heights={[300]}` generates srcSet entries for `sw=400&sh=300` (1x) and `sw=800&sh=600` (2x).

`heights` supports the same formats as `widths` (arrays, objects with breakpoint keys, comma-separated strings for Page Designer).

When `heights` is omitted, DIS preserves the original aspect ratio based on `sw` alone.

### Loading Priority and Preloading

`DynamicImage` integrates with React 19's [`preload()`](https://react.dev/reference/react-dom/preload) to emit `<link rel="preload">` hints for high-priority images during server rendering:

```jsx
// Explicitly high priority. Preloaded during SSR, loaded eagerly.
<DynamicImage src={heroImage} widths={[...]} priority="high" loading="eager" />

// Auto priority (default). Determined by DynamicImageProvider context.
<DynamicImage src={productImage} widths={[...]} />

// Explicitly low priority. Lazy-loaded, no preload hints.
<DynamicImage src={belowFoldImage} widths={[...]} priority="low" loading="lazy" />
```

When `priority` isn't set, the component checks the `DynamicImageProvider` context to determine whether the image should be treated as high priority. If no context is present, it defaults to `'auto'` priority with `loading="lazy"`.

In practice, the PDP image gallery uses conditional priority to eagerly load the first visible image while lazy-loading the rest:

```jsx
<DynamicImage
  src={`${selectedImage.src}[?sw={width}]`}
  alt={selectedImage.alt || imageAltFallback}
  widths={["100vw", "680px"]}
  loading={eager ? "eager" : "lazy"}
  priority={eager ? "high" : undefined}
/>
```

## `DynamicImageProvider` Context

The `DynamicImageProvider` is an optional React context that controls image priority and dimensions for nested `<DynamicImage>` components. It solves a practical problem: in deep component trees (for example, product grid → product tile → product image), determining whether an image is above-the-fold requires knowledge the image component itself doesn't have. The provider bridges that gap by separating the decision about importance from the rendering of individual images.

```typescript
import DynamicImageProvider from "@/providers/dynamic-image";
```

### How It Works

The provider deliberately exposes **two different interfaces**: one for the outer container that sets up the context, and one for the nested consumers that interact with it.

**Container interface** (passed via `value` prop). The container defines the business logic:

```typescript
value: {
    sources?: Set<string>;                                       // Shared source registry
    widths?: DynamicImageDimensions;                             // Responsive widths for all nested images
    heights?: DynamicImageDimensions;                            // Responsive heights for all nested images
    addSource?: (src: string, sources: Set<string>) => boolean;  // Strategy: how to register an image
    hasSource?: (src: string, sources: Set<string>) => boolean;  // Strategy: how to determine importance
}
```

The container receives the raw `Set<string>` alongside each `src`, giving it full control over the registration and lookup logic. It decides what it means for an image to be important.

**Consumer interface** (returned by `useDynamicImageContext()`). Consumers just register and query:

```typescript
{
  addSource: (src: string) => boolean; // Register this image (Set is hidden)
  hasSource: (src: string) => boolean; // Is this image important?
  widths: DynamicImageDimensions | undefined;
  heights: DynamicImageDimensions | undefined;
}
```

Consumers never see the `Set` or the strategy. They call `addSource(src)` to register themselves and read `widths`/`heights` for their dimensions. The `<DynamicImage>` component calls `hasSource(src)` internally: when it returns `true`, the image is promoted to `priority="high"` and `loading="eager"`.

This separation means the container owns all policy decisions while nested components remain generic and reusable.

### Example: Product Grid with Critical and Non-Critical Images

Split product grid tiles into critical (above-the-fold) and non-critical (below-the-fold) batches:

```jsx
const responsiveImageWidths = [
    '40vw', // base: 2 columns
    '25vw', // sm: 3 columns
    '18vw', // md: 4 columns
    '14vw', // lg: 4 columns with refinement panel
    '16vw', // xl
    '16vw', // 2xl
];

// Critical tiles: all images are high priority
const hasSource = useCallback(() => true, []);

<DynamicImageProvider value={{ hasSource, widths: responsiveImageWidths }}>
    {criticalProducts.map(product => <ProductTile ... />)}
</DynamicImageProvider>

// Non-critical tiles: no hasSource → all images default to lazy
<DynamicImageProvider value={{ widths: responsiveImageWidths }}>
    {nonCriticalProducts.map(product => <ProductTile ... />)}
</DynamicImageProvider>
```

The `ProductTile` component itself is identical in both batches. It doesn't know whether it's above or below the fold. The provider controls that from the outside.

### Example: Capping High-Priority Images with a Single Provider

A single provider can use the shared `Set<string>` to cap how many images are promoted. This example treats only the first row of a four-column grid as high priority:

```jsx
const addSource = useCallback((src, sources) => {
    if (sources.size < 4) { sources.add(src); return true; }
    return false;
}, []);
const hasSource = useCallback((src, sources) => sources.has(src), []);

<DynamicImageProvider value={{ addSource, hasSource, widths: responsiveImageWidths }}>
    {allProducts.map(product => <ProductTile ... />)}
</DynamicImageProvider>
```

The first four tiles to call `addSource` get registered. When `<DynamicImage>` later calls `hasSource`, only those four return `true`.

### Example: Selective Registration in Product Tile

Inside each product tile, the `ProductImageContainer` uses `addSource` to register whichever image URL is currently selected (which depends on the active color swatch). This is where the two-step contract matters: the tile doesn't decide importance, it just registers. The grid's `hasSource` decides.

```jsx
const imageContext = useDynamicImageContext();

// Register the current image URL (resolved from the selected color variant)
currentImageUrl && imageContext?.addSource(currentImageUrl);

// Render with context-provided widths — no prop drilling needed
<ProductImage src={currentImageUrl} widths={imageContext?.widths} />;
```

A more selective container could supply a `hasSource` that checks whether a specific `src` was pre-registered via `addSource`, making only certain images high-priority rather than all of them. The unconditional `() => true` in the product grid is the simplest strategy, but the same mechanism supports arbitrary filtering logic.

## Dynamic Image Utility Functions

The `@/lib/images/dynamic-image` module exports lower-level utilities for working with DIS URLs outside the `<DynamicImage>` component.

### `toImageUrl()`

Converts an image URL to a DIS-optimized URL with graceful fallback. Safe to use with any image URL; returns the original if transformation isn't possible.

```typescript
import { toImageUrl } from "@/lib/images/dynamic-image";

// SFCC URL → DIS WebP
toImageUrl({ src: "https://demo-001.dx.commercecloud.salesforce.com/.../image.jpg", config });
// → 'https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/DEMO_001/.../image.webp?sfrm=jpg&q=70'

// Non-SFCC URL → returned as-is (fallback)
toImageUrl({ src: "https://example.com/image.jpg", config });
// → 'https://example.com/image.jpg'
```

Use this when rendering images outside of `<DynamicImage>`, for example category banners or content slots with raw HTML.

### `toDisImageUrl()`

Strict variant that only handles SFCC URLs. Returns `undefined` if the URL can't be converted (non-SFCC host, missing realm, missing DIS config). Use this when you need to know definitively whether DIS transformation succeeded.

Recognized SFCC hostnames are `*.commercecloud.salesforce.com`, `*.demandware.net`, and `*.my.cc.salesforce.com`. The realm is derived from the first subdomain (for example, `demo-001` → `DEMO_001`).

```typescript
import { toDisImageUrl } from "@/lib/images/dynamic-image";

toDisImageUrl({ src: sfccUrl, options: { width: 720, height: 480, quality: 80 }, config });
// → 'https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/DEMO_001/.../image.webp?sfrm=jpg&sw=720&sh=480&q=80'
```

### `toDisBaseUrl()`

Rewrites a raw SFCC static image URL into a DIS-hosted URL by inserting the `/dw/image/v2/{realm}/` prefix and switching to the configured DIS host. Unlike `toDisImageUrl()`, it **preserves the original file extension and query string**—it does not perform format conversion or append DIS transformation parameters (`sfrm`, `q`, `sw`, `sh`). Use this when downstream code (for example, `getResponsivePictureAttributes`) handles per-breakpoint format/query generation and just needs a clean DIS-hosted base URL.

```typescript
import { toDisBaseUrl } from "@/lib/images/dynamic-image";

toDisBaseUrl({
  src: "https://demo-001.my.cc.salesforce.com/on/demandware.static/-/.../image.jpg",
  config,
});
// → 'https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/DEMO_001/on/demandware.static/-/.../image.jpg'
```

### `transformHtmlImageUrls()`

Batch-transforms all `<img>` tags in an HTML string to use DIS URLs. Useful for rich text content from SCAPI or Page Designer that contains embedded images.

```typescript
import { transformHtmlImageUrls } from "@/lib/images/dynamic-image";

const html = '<p>Text</p><img src="/on/demandware.static/.../banner.jpg" alt="Sale">';
const optimized = transformHtmlImageUrls(html, config);
// All <img> src attributes are transformed to DIS URLs
```

### `replaceImageFormat()`

Replaces the file extension in an image URL and adds the `sfrm` parameter to track the original format. Used internally by the component, but available for custom image handling.

```typescript
import { replaceImageFormat } from "@/lib/images/dynamic-image";

replaceImageFormat("https://example.com/image.jpg?sw=460&q=60");
// → 'https://example.com/image.webp?sw=460&q=60&sfrm=jpg'
```

## Performance Checklist

Follow these guidelines to get the best performance from your storefront images:

- **Above the fold**: Set `priority="high"` and `loading="eager"` on hero and LCP-candidate images. This triggers React 19 SSR preloading.
- **Below the fold**: Use the default `loading="lazy"`. Omit priority or set `priority="low"`.
- **Always set `widths` or `heights`**: Without either, `<DynamicImage>` renders a plain `<img>` with no responsive sources. The browser downloads the full-size image regardless of viewport.
- **Prefer vw for fluid layouts**: Use vw-based widths (for example, `'50vw'`) when the image width scales with the viewport. Use px-based widths when the image has a fixed maximum size (for example, product detail at `'680px'`).
- **Set width/height on non-DynamicImage `<img>` elements**: Always include explicit `width` and `height` attributes on standard `<img>` elements to prevent Cumulative Layout Shift (CLS). `<DynamicImage>` handles this via its responsive `<picture>` and sizing attributes.
- **Use `DynamicImageProvider` for grids**: Wrap product grids in a provider to control priority centrally rather than passing props through every tile.
- **Use WebP as the target format**: The default `formats: ['webp']` config gives 25–35% smaller files than JPEG/PNG. The `fallbackFormat` config (default `'jpg'`) provides automatic fallback for browsers that don't support any of the `<source>` formats.
- **Tune quality per use case**: The default `quality: 70` is a good baseline. Hero banners or product zoom may benefit from higher values (80–85). Thumbnails and carousels can go lower (50–60). Override globally per-environment via `PUBLIC__app__images__quality`, or per-image by adding the URL parameter `q=` to the src URL (for example, `src="https://example.com/image.jpg?q=85"`). A `q` parameter present in the src URL takes priority over the global config.

## Alt Text Strategy

Providing meaningful alt text is essential for accessibility and SEO.

### Source of Truth

For commerce product images, SCAPI image alt text is the source of truth.

### Fallback Order

Use this fallback order for product images.

1. SCAPI image alt (`image.alt`)
2. Product name (`productName` / `name`)
3. Localized generic fallback (for example, `t('common:productImageAlt')`)
4. Non-localized English fallback as a final safety net (for example, `'Product Image'`)

Use explicit `||` fallback chains in components to preserve this order.

### Rules

- Always provide an `alt` attribute on rendered `<img>` elements.
- Use localized strings for generic fallback alt text, then a hardcoded English fallback as the last resort.
- Decorative images must set `alt=""` when the image is purely decorative and has no meaningful text equivalent.

## See Also

- [Dynamic Imaging Service](https://help.salesforce.com/s/articleView?id=cc.b2c_image_transformation_service.htm&type=5) (Official Salesforce DIS documentation)
- [Static Assets](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-static-assets.md) (Serving static files from the public directory)
- [UI Styling](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ui-styling.md) (Tailwind CSS and design tokens)

<!-- document id=0f3ef457bb814c2d374813152238bc91faa2dd89e3f345e1120f32aad01c9ea8 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-implement-overview.md -->

# Implement B2B Commerce Checkout Flow

Build the checkout workflow from adding items to the cart to placing the final order using Salesforce Commerce APIs. Trigger the appropriate background calculators—including pricing, tax, and shipping—based on the current cart status.

![Diagram of the B2B Commerce checkout API flow from cart to order confirmation](https://developer.salesforce.com/media/d2c-commerce/commerce-checkout-apis-flow.png '{"class": "image-lg", "title": "B2B Commerce Checkout Flow"}')

1. [Add to Cart](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-add-to-cart.md)
2. [Start Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-start-checkout.md)
3. [Poll Checkout Status](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-poll-status.md)
4. [Update Checkout Information](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-update-information.md)
5. [Process Payment](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-process-payment.md)
6. [Place Order](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order.md)

<!-- document id=c49929a77f21f8184f4abb9777d06c3b047789a975bb3895ca05c590664a936e url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-custom-self-registration.md -->

# Implement Custom Self-Registration for a B2B Store

Implement automated customer self-registration for Salesforce B2B Commerce storefronts using a custom Lightning Web Component and an Apex controller that orchestrates user provisioning, account creation, buyer access, and permission assignment.

The self-registration solution consists of two primary components:

- Custom web component — Provides the user-facing registration interface with form validation, user feedback, and storefront integration.
- Custom Apex controller — Orchestrates backend operations including user provisioning, account creation, buyer access configuration, and permission management.

## When to Use This Implementation

Use this implementation when you want to:

- Enable customers to register for B2B Commerce stores without administrator intervention.
- Support password-based user authentication.
- Maintain control over user provisioning and account creation workflows.
- Enforce data validation and business rules during registration.
- Automate buyer access setup and permission assignment.
- Streamline the customer onboarding experience.

## Customize the Self-Registration Page

Customize the store’s registration page using custom Lightning Web Components (LWC) and Apex code. For a sample Apex class, see the [CommerceSelfRegistrationController.cls class](#sample-implementation-of-commerceselfregistrationcontroller).

Before you begin:

- [Create a Salesforce DX Project](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-sample-lwc-project.html).
- [Create a sample Lightning web component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-create-sample-lwc.html).
- [Deploy a custom component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-deploy-lwc-component.html).

1. Add the new UI component to your store’s self-registration page.

   a. In the navigation sidebar, select a store from the **Store** dropdown.

   b. Select **Website Design**, and then click **Experience Builder**.

   c. In Experience Builder, go to the Self-registration page.

   d. To view the properties, click the page.

   e. Drag and drop the component on the page.

   f. Configure the component properties.

   g. Publish your store.

2. Grant `CommerceSelfRegistrationController.cls` access to guest users.

> **Note:** Grant guest users access only to the Apex classes required for self-registration. Don't grant access to unrelated classes or classes that expose sensitive operations.

   Don’t grant access to unrelated classes or classes that expose sensitive operations.

   a. In the navigation sidebar, select a store from the **Store** dropdown.

   b. Select **Website Design**, and then click **Experience Builder**.

   c. In Experience Builder, go to **Settings**, and then click **General**.

   d. Click the Guest User Profile.

   e. In the Enabled Apex Class Access section, click **Edit**.

   f. Add the Apex class to the list of enabled classes, and save your changes.

## Sample Implementation of `CommerceSelfRegistrationController`

The `CommerceSelfRegistrationController` class is the core backend component that handles all server-side operations for customer self-registration.

The following sample shows a `CommerceSelfRegistrationController` class implementation.

```apex
/**
 * Self-registration controller for Experience Cloud with B2B Commerce integration
 */
global without sharing class CommerceSelfRegistrationController {

    private static final String LOG_PREFIX = '[CommerceSelfReg]';

    public class RegistrationException extends Exception {}

    global class RegistrationResult {
        @AuraEnabled global Boolean success;
        @AuraEnabled global String message;
        @AuraEnabled global String redirectUrl;
    }

    /**
     * Register a new user with BuyerAccount and auto-login
     * Returns: RegistrationResult with success status, message, and redirect URL
     */
    @AuraEnabled(cacheable=false)
    global static RegistrationResult registerUserAndRedirectForLogin(
        String firstName,
        String lastName,
        String email,
        String phoneNumber,
        String password,
        String confirmPassword,
        String startUrl
    ) {
        RegistrationResult result = new RegistrationResult();
        result.success = false;

        Savepoint sp = Database.setSavepoint();

        try {
            String validationError = validateRegistrationInput(lastName, email, password, confirmPassword);
            if (validationError != null) {
                result.message = validationError;
                return result;
            }

            String permissionSetGroupId = getPermissionSetGroupIdFromNetwork();

            if (String.isBlank(startUrl)) {
                startUrl = '';
            }

            String accountId = createBusinessAccount(firstName, lastName);
            String userId = createUser(firstName, lastName, email, phoneNumber, password, accountId);

            createBuyerAccount(accountId);

            // Add buyer to all default buyer groups from config
            List<String> defaultBuyerGroupIds = getDefaultBuyerGroupsFromConfig();
            if (!defaultBuyerGroupIds.isEmpty()) {
                addBuyerToDefaultGroups(accountId, defaultBuyerGroupIds);
            }

            assignPermissionSetToUserAsync(userId, permissionSetGroupId);
            performAutoLogin(email, password, startUrl, result);

        } catch (Exception ex) {
            Database.rollback(sp);
            result.success = false;
            result.message = 'Registration error: ' + ex.getMessage();
            System.debug(LOG_PREFIX + ' Registration exception: ' + ex.getMessage());
            System.debug(LOG_PREFIX + ' Stack trace: ' + ex.getStackTraceString());
        }

        return result;
    }

    /**
     * Validate registration input fields
     * Returns: Error message if validation fails, null if valid
     */
    private static String validateRegistrationInput(String lastName, String email, String password, String confirmPassword) {
        if (String.isBlank(lastName)) {
            return 'Last name is required';
        }

        if (String.isBlank(email)) {
            return 'Email is required';
        }

        if (String.isBlank(password)) {
            return 'Password is required';
        }

        if (password != confirmPassword) {
            return 'Passwords do not match';
        }

        return null;
    }

    /**
     * Create external user using Site.createExternalUser()
     * Returns: User ID
     */
    private static String createUser(String firstName, String lastName, String email,
        String phoneNumber, String password, String accountId) {
        try {
            User u = new User();
            u.FirstName = firstName;
            u.LastName = lastName;
            u.Email = email;
            u.Username = email;
            u.CommunityNickname = generateNickname(firstName, lastName, email);
            u.EmailEncodingKey = 'UTF-8';
            u.LocaleSidKey = 'en_US';
            u.LanguageLocaleKey = 'en_US';
            u.TimeZoneSidKey = 'America/Los_Angeles';
            u.Alias = generateAlias(firstName, lastName);

            if (!String.isBlank(phoneNumber)) {
                u.Phone = phoneNumber;
            }

            String userId = Site.createExternalUser(u, accountId, password);

            if (userId == null) {
                throw new RegistrationException('Site.createExternalUser returned null - user creation failed');
            }

            System.debug(LOG_PREFIX + ' Created external user: ' + userId);
            return userId;

        } catch (Exception ex) {
            System.debug(LOG_PREFIX + ' Error creating user: ' + ex.getMessage());
            System.debug(LOG_PREFIX + ' Stack trace: ' + ex.getStackTraceString());
            throw ex;
        }
    }

    /**
     * This a sample implementation and customer's need to provider their own implementation
     * Generate unique community nickname
     * Returns: Nickname string (max 40 chars)
     */
    private static String generateNickname(String firstName, String lastName, String email) {
        String nickname = (firstName != null ? firstName : '') + (lastName != null ? lastName : '');
        if (String.isBlank(nickname)) {
            nickname = email.substringBefore('@');
        }
        nickname = nickname.replaceAll('[^a-zA-Z0-9]', '');
        nickname = nickname + String.valueOf(System.now().getTime()).substring(7);
        return nickname.substring(0, Math.min(nickname.length(), 40));
    }

    /**
     * This a sample implementation and customer's need to provider their own implementation
     * Generate user alias.
     * Returns: Alias string (max 8 chars)
     */
    private static String generateAlias(String firstName, String lastName) {
        String alias = '';
        if (firstName != null) alias += firstName.substring(0, Math.min(firstName.length(), 4));
        if (lastName != null) alias += lastName.substring(0, Math.min(lastName.length(), 4));
        if (String.isBlank(alias)) alias = 'user';
        return alias.substring(0, Math.min(alias.length(), 8));
    }

    /**
     * Perform auto-login after successful registration and update result object
     */
    private static void performAutoLogin(String email, String password, String startUrl, RegistrationResult result) {
        try {
            PageReference loginResult = Site.login(email, password, startUrl);
            if (loginResult != null) {
                result.redirectUrl = loginResult.getUrl();
                result.success = true;
                result.message = 'Registration and login successful!';
                System.debug(LOG_PREFIX + ' Auto-login successful, redirect URL: ' + result.redirectUrl);
            } else {
                result.success = true;
                result.redirectUrl = null;
                result.message = 'Registration successful but auto-login failed. Please login manually.';
                System.debug(LOG_PREFIX + ' Auto-login failed - Site.login returned null');
            }
        } catch (Exception loginEx) {
            result.success = true;
            result.redirectUrl = null;
            result.message = 'Registration successful but auto-login failed. Please login manually.';
            System.debug(LOG_PREFIX + ' Auto-login exception: ' + loginEx.getMessage());
        }
    }

    /**
     * Create a business account to be associated with registering user
     * Returns: Business account ID
     */
    private static String createBusinessAccount(String firstName, String lastName) {
        Account account = new Account();
        account.Name = firstName + ' ' + lastName;

        String recordTypeId = getDefaultAccountRecordTypeId();
        if (String.isNotBlank(recordTypeId)) {
            account.RecordTypeId = recordTypeId;
        }

        ID siteAdminId = getSiteAdminId();
        if (siteAdminId != null) {
            account.OwnerId = siteAdminId;
        }

        insert account;
        System.debug(LOG_PREFIX + ' Created business account: ' + account.Id);
        return account.Id;
    }

    /**
     * Get default account record type ID from Commerce configuration
     * Returns: Account record type ID (15 chars), or null
     */
    private static String getDefaultAccountRecordTypeId() {
        String networkId = Network.getNetworkId();

        List<CommerceConfigRelatedRecord> configs = [
            SELECT ConfigReferenceId
            FROM CommerceConfigRelatedRecord
            WHERE ContextId = :networkId
            AND ConfigUseCase = 'SelfRegistration'
            AND ConfigKey = 'AccountRecordType'
            LIMIT 1
        ];

        if (!configs.isEmpty() && String.isNotBlank(configs[0].ConfigReferenceId)) {
            String recordTypeId = configs[0].ConfigReferenceId;
            if (recordTypeId.length() == 18) {
                recordTypeId = recordTypeId.substring(0, 15);
            }
            System.debug(LOG_PREFIX + ' Found account record type ID: ' + recordTypeId);
            return recordTypeId;
        }

        return null;
    }

    /**
     * Get site admin ID
     * Returns: Site admin user ID as ID, or null
     */
    private static ID getSiteAdminId() {
        return Site.getAdminId();
    }

    /**
     * Create BuyerAccount for Commerce integration
     */
    private static void createBuyerAccount(String accountId) {
        BuyerAccount buyerAccount = new BuyerAccount(
            BuyerId = accountId,
            Name = 'Buyer-' + accountId,
            IsActive = true
        );
        insert buyerAccount;
        System.debug(LOG_PREFIX + ' Created BuyerAccount: ' + buyerAccount.Id);
    }

    /**
     * Add buyer to all default buyer groups
     */
    private static void addBuyerToDefaultGroups(String accountId, List<String> defaultBuyerGroupIds) {
        List<BuyerGroupMember> members = new List<BuyerGroupMember>();
        for (String buyerGroupId : defaultBuyerGroupIds) {
            if (String.isNotBlank(buyerGroupId)) {
                members.add(new BuyerGroupMember(
                    BuyerId = accountId,
                    BuyerGroupId = buyerGroupId
                ));
            }
        }

        if (!members.isEmpty()) {
            insert members;
            System.debug(LOG_PREFIX + ' Added account to ' + members.size() + ' default BuyerGroups');
        }
    }

    /**
     * Async wrapper to assign permission set (avoids Mixed DML)
     */
    @future
    private static void assignPermissionSetToUserAsync(String userId, String permissionSetGroupId) {
        assignPermissionSetToUser(userId, permissionSetGroupId);
    }

    /**
     * Assign permission set group to user
     */
    private static void assignPermissionSetToUser(String userId, String permissionSetGroupId) {
        PermissionSetAssignment psa = new PermissionSetAssignment(
            AssigneeId = userId,
            PermissionSetGroupId = permissionSetGroupId
        );
        insert psa;
        System.debug(LOG_PREFIX + ' Assigned permission set group to user: ' + psa.Id);
    }

    /**
     * Get permission set group ID from NetworkSelfRegistration configuration
     * Returns: Permission set group ID
     */
    private static String getPermissionSetGroupIdFromNetwork() {
        String networkId = Network.getNetworkId();
        if (String.isBlank(networkId)) {
            System.debug(LOG_PREFIX + ' No network ID found');
            throw new RegistrationException('No network ID found');
        }

        List<NetworkSelfRegistration> selfRegConfigs = [
            SELECT PermissionSetGroupId
            FROM NetworkSelfRegistration
            WHERE NetworkId = :networkId
            LIMIT 1
        ];

        if (selfRegConfigs.isEmpty() || String.isBlank(selfRegConfigs[0].PermissionSetGroupId)) {
            System.debug(LOG_PREFIX + ' No permission set group configured in NetworkSelfRegistration');
            throw new RegistrationException('No permission set group configured in NetworkSelfRegistration');
        }

        String permSetGroupId = selfRegConfigs[0].PermissionSetGroupId;
        System.debug(LOG_PREFIX + ' Found permission set group ID from NetworkSelfRegistration: ' + permSetGroupId);
        return permSetGroupId;
    }

    /**
     * Get default buyer group IDs from CommerceConfigRelatedRecord
     * This follows Salesforce's official implementation pattern
     * Returns: List of BuyerGroup IDs configured for self-registration
     */
    private static List<String> getDefaultBuyerGroupsFromConfig() {
        String networkId = Network.getNetworkId();
        List<String> buyerGroupIds = new List<String>();

        try {
            List<CommerceConfigRelatedRecord> configs = [
                SELECT ConfigReferenceId
                FROM CommerceConfigRelatedRecord
                WHERE ContextId = :networkId
                AND ConfigUseCase = 'SelfRegistration'
                AND ConfigKey = 'DefaultBuyerGroup'
            ];

            for (CommerceConfigRelatedRecord config : configs) {
                if (String.isNotBlank(config.ConfigReferenceId)) {
                    buyerGroupIds.add(config.ConfigReferenceId);
                }
            }

            System.debug(LOG_PREFIX + ' Found ' + buyerGroupIds.size() + ' default buyer groups: ' + buyerGroupIds);
        } catch (Exception e) {
            System.debug(LOG_PREFIX + ' Error retrieving buyer groups: ' + e.getMessage());
            throw new RegistrationException('Error retrieving buyer groups');
        }

        return buyerGroupIds;
    }
}
```

## See Also

- [Manage Access to a B2B Store](https://help.salesforce.com/s/articleView?id=commerce.comm_buyer_access.htm&type=5)
- [Configure Self-Registration for a B2B Store](https://help.salesforce.com/s/articleView?id=commerce.comm_self_registration.htm&type=5)
- [Website Design for B2B Stores](https://help.salesforce.com/s/articleView?id=commerce.comm_customize_template.htm&type=5)
- [Publish Your Store](https://help.salesforce.com/s/articleView?id=commerce.comm_publish_store.htm&type=5)
- [_Salesforce B2B Commerce_: Configure Self-Registration for a B2B Store](https://help.salesforce.com/s/articleView?id=commerce.comm_self_registration.htm&type=5)
- [_Salesforce B2B Commerce_: Website Design for B2B Stores](https://help.salesforce.com/s/articleView?id=commerce.comm_customize_template.htm&type=5)
- [_Salesforce B2B Commerce_: Publish Your Store](https://help.salesforce.com/s/articleView?id=commerce.comm_publish_store.htm&type=5)

<!-- document id=56f055bf901eada06a66dd5ec3ba3eb33c1a9351859ea0cb768efc25e5e9bfc1 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/hybrid-auth-pwa-kit-v2.md -->

# Implement Hybrid Authentication for PWA Kit v2

**important:** **Who should use this guide:** Only **existing PWA Kit v2.x projects** that want to add Hybrid Auth by upgrading to v2.10.0. PWA Kit v2.10.0 supports **SLAS Public Clients only**.

**Starting a new Hybrid Auth implementation?** Don't use this guide. New implementations must start on **PWA Kit v3**—see [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md) for the supported version and prerequisites.

Use this guide to upgrade your existing PWA Kit application to version 2.10.0 and implement Hybrid Auth. The PWA Kit 2.10.0 release introduces significant changes, such as compatibility with Hybrid Auth and integration with the `@salesforce/commerce-sdk-react` package. For additional details, check out the [complete pwa-kit GitHub diff](https://github.com/SalesforceCommerceCloud/pwa-kit/compare/v2.9.1...v2.10.0) to get a better understanding of the code changes.

## Prerequisites

Before starting the upgrade process, make sure that you have:

- Node.js version 18.x or 20.x (upgraded from 14.x/16.x support)
- NPM version 9.x or 10.x (upgraded from 6.x/7.x/8.x support)
- Enable Hybrid Auth on your Business Manager instance. For details, see [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-shared-setup.md). Then enable cookies on Managed Runtime, as described in [Enable Cookies on Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md#step-5-enable-cookies-on-managed-runtime).

## Authentication System Updates

The most significant update is the introduction of the new Commerce SDK React authentication system.

### New Dependencies

```json
{
  "@salesforce/commerce-sdk-react": "^4.0.0",
  "@tanstack/react-query": "4.28.0"
}
```

## Step-by-Step Upgrade Process

### Step 1\: Prepare Your Environment

1. Check your current Node.js and npm versions.

   ```bash
   node --version
   npm --version
   ```

   If your Node.js version is below 18.x, upgrade it first. If your npm version is below 9.x, upgrade it first.

   #### Before the upgrade (PWA Kit v2.9.x):

   ```json
   {
     "engines": {
       "node": "^14.0.0 || ^16.0.0 || ^18.0.0 || ^20.0.0",
       "npm": "^6.14.4 || ^7.0.0 || ^8.0.0 || ^9.0.0 || ^10.0.0"
     }
   }
   ```

   #### After the upgrade (PWA Kit v2.10.0):

   ```json
   {
     "engines": {
       "node": "^18.0.0 || ^20.0.0",
       "npm": "^9.0.0 || ^10.0.0"
     }
   }
   ```

### Step 2\: Update Dependencies

1. Open your `package.json` file and update the following sections.

   Update the `"engines"` section.

   ```json
   {
     "engines": {
       "node": "^18.0.0 || ^20.0.0",
       "npm": "^9.0.0 || ^10.0.0"
     }
   }
   ```

   Update the `"devDependencies"` section with these new dependencies and version bumps.

   ```json
   {
     "devDependencies": {
       "@salesforce/commerce-sdk-react": "^3.4.0",
       "@tanstack/react-query": "4.28.0",
       "commerce-sdk-isomorphic": "^3.3.0",
       "jwt-decode": "^4.0.0",
       "pwa-kit-dev": "2.10.0",
       "pwa-kit-react-sdk": "2.10.0",
       "pwa-kit-runtime": "2.10.0",
       "@testing-library/react": "^12.1.5",
       "@testing-library/react-hooks": "^8.0.1",
       "@testing-library/user-event": "^14.4.3",
       "ajv": "^8.17.1",
       "ajv-keywords": "^5.1.0"
     }
   }
   ```

2. Save the `package.json` file.

3. Clean install the new dependencies.

   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

**note:** The `@testing-library/*` dependencies are optional and required only if you've implemented unit tests using `react-testing-library`.

### Step 3\: Update the Configuration

1. Open your `config/default.js` file.

2. Find the line that contains `ssrFunctionNodeVersion` and update it.

   ```javascript
   // Change this line:
   ssrFunctionNodeVersion: '18.x', // Or 20.x if you upgraded to Node 20.
   ```

3. Save the `config/default.js` file.

### Step 4\: Authentication Migration

Update your authentication implementation with the new Commerce SDK React system.

1. Remove old authentication files.

   ```bash
   rm app/commerce-api/auth.js
   rm app/commerce-api/pkce.js
   ```

2. Update the `utils.js` file.

   ```bash
   # Open app/commerce-api/utils.js and remove authentication-related functions
   ```

   Remove these imports from the top of the file.

   ```javascript
   // REMOVE these lines from app/commerce-api/utils.js
   import jwtDecode from "jwt-decode";
   import { refreshTokenGuestStorageKey, refreshTokenRegisteredStorageKey } from "./constants";
   ```

   Remove these functions from `app/commerce-api/utils.js`.

   ```javascript
   // REMOVE these functions from app/commerce-api/utils.js
   export function isTokenExpired(token) { ... }
   export function createGetTokenBody(urlString, slasCallbackEndpoint, codeVerifier) { ... }
   export function hasSFRAAuthStateChanged(storage, storageCopy) { ... }
   ```

   Keep all other utility functions, including `keysToCamel` and `createOcapiFetch`, as they're still needed.

3. Update the `useCustomer` hook. Open your `app/hooks/use-customer.js` file and update the authentication methods.

   ```javascript
   // Add these new imports at the top of the file:
   import { AuthHelpers } from '@salesforce/commerce-sdk-react'
   import { useAuthHelper } from '@salesforce/commerce-sdk-react'

   // Find the login and logout methods in useCustomer hook and update them:

   // Old implementation (v2.9.x)
   const login = async (credentials) => {
     const auth = new Auth();
     await auth.login(credentials);
     // ... rest of login logic
   };

   const logout = async () => {
     const auth = new Auth();
     await auth.logout();
     // ... rest of logout logic
   };

   // New implementation (v2.10.0)
   export default function useCustomer() {
    const api = useCommerceAPI()
    const {customer, setCustomer} = useContext(CustomerContext)

    const login = useAuthHelper(AuthHelpers.LoginRegisteredUserB2C)
    const logout = useAuthHelper(AuthHelpers.Logout)

      const getSkeletonCustomer = () => {
          return {
              customerId: api.auth.get('customer_id'),
              authType: api.auth.get('customer_type')
          }
      }

    const self = useMemo(() => {
      return {
        ... customer,

        // Other useCustomer hook functions
        ...
        // The login method is now handled by the useAuthHelper hook
        async login(credentials) {
            await api.auth.ready()
            let skeletonCustomer = getSkeletonCustomer()
            if (credentials) {
                await login.mutateAsync({
                    username: credentials.email,
                    password: credentials.password
                })
                skeletonCustomer = getSkeletonCustomer()
            }
          // ... rest of login logic
          },

          async logout() {
            await logout.mutateAsync()
            await api.auth.ready()
            const skeletonCustomer = getSkeletonCustomer()
            setCustomer(skeletonCustomer)
            // ... rest of logout logic
          }
      }
    })
   ```

**note:** The `useCustomer` hook now uses the new Commerce SDK React authentication methods. Your existing login and registration components don't need any changes since they call the same `login()` and `register()` functions.

### Step 5\: Update the Commerce API Implementation

**note:** The Commerce API implementation has been significantly updated to use the new `transformSDKClient` utility from `@salesforce/commerce-sdk-react` package. See the [README.md](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/commerce-sdk-react/README.md#advanced-customizing-sdk-clients-with-transformsdkclient) for the package to learn more.

1. Open your `app/commerce-api/index.js` file.

2. Update the imports at the top of the file.

   ```javascript
   // Remove these old imports:
   import Auth from "./auth";
   import { isError } from "./utils";

   // Add these new imports:
   import Auth from "@salesforce/commerce-sdk-react/auth";
   import { transformSDKClient } from "@salesforce/commerce-sdk-react/utils";
   import { DWSID_HEADER_KEY } from "./constants";
   ```

3. Update the auth module instantiation.

   ```javascript
   // Old implementation (v2.9.x)

   this._config = { proxy, ...restConfig };

   this.auth = new Auth(this); // Update this with new authConfig
   ```

   Replace with this new code:

   ```javascript
   // Old implementation (v2.9.x)

   this._config = { proxy, ...restConfig };

   // Add new authConfig object
   this._authConfig = {
     redirectURI: `${getAppOrigin()}/callback`,
     proxy,
     locale: this._config.locale,
     currency: this._config.currency,
     ...this._config.parameters,
     ...this._config.headers,
   };

   this.auth = new Auth(this._authConfig); // pass authConfig as param to Auth class constructor.
   ```

4. Find the section where SDK clients are instantiated (around line 100-150) and replace the entire SDK instantiation logic.
   Remove this old code:

   ```javascript
   // Old implementation (v2.9.x) - using Proxy
   const SdkClass = apiConfigs[key].api;
   self._sdkInstances = {
     ...self._sdkInstances,
     [key]: new Proxy(new SdkClass(this._config), {
       get: function (obj, prop) {
         // ... proxy implementation
       },
     }),
   };
   ```

   Replace with this new code:

   ```javascript
   // New implementation (v2.10.0) - using transformSDKClient
   const SdkClass = apiConfigs[key].api;
   const sdkClient = new SdkClass(this._config);
   self._sdkInstances = {
     ...self._sdkInstances,
     [key]: transformSDKClient(sdkClient, {
       props: this._config,
       transformer: async (_, methodName, options) => {
         const { fetchOptions = {} } = options;
         if (fetchOptions.ignoreHooks) {
           return options;
         }

         const { locale, currency } = this._config;

         // Inject the locale and currency to the API call via its parameters.
         const { sendLocale = true, sendCurrency = false } = apiConfigs[key];

         const includeGlobalLocale = Array.isArray(sendLocale)
           ? sendLocale.includes(methodName)
           : !!sendLocale;

         const includeGlobalCurrency = Array.isArray(sendCurrency)
           ? sendCurrency.includes(methodName)
           : !!sendCurrency;

         fetchOptions["parameters"] = {
           ...(includeGlobalLocale ? { locale } : {}),
           ...(includeGlobalCurrency ? { currency } : {}),
           ...fetchOptions?.parameters,
         };

         // Handle auth logic (replacing willSendRequest functionality)
         let dwsidHeader = {};
         const dwsid = self.auth.get("dwsid");
         if (dwsid) {
           dwsidHeader = {
             [DWSID_HEADER_KEY]: dwsid,
           };
         }

         // Special handling for auth methods
         if (
           methodName === "authenticateCustomer" ||
           methodName === "authorizeCustomer" ||
           methodName === "getAccessToken"
         ) {
           return {
             ...options.parameters,
             headers: {
               ...options.headers,
               ...fetchOptions.headers,
             },
             credentials: "same-origin", // Required for SLAS calls to set dwsid cookie
             ...fetchOptions,
           };
         }

         const { access_token: token } = await self.auth.ready();
         return {
           ...options,
           headers: {
             ...options.headers,
             ...dwsidHeader,
             Authorization: `Bearer ${token}`,
           },
           // Add cache breaker for Storefront Preview
           parameters: {
             ...options.parameters,
             ...(this.isStorefrontPreview ? { c_cache_breaker: Date.now() } : {}),
           },
         };
       },
     }),
   };
   ```

5. Find and remove these methods from the CommerceAPI class:

   ```javascript
   // Remove these methods completely:
   async willSendRequest(methodName, ...params) {
       // ... entire method
   }

   didReceiveResponse(response, args) {
       // ... entire method
   }
   ```

6. Update the constants file.
   Add a new constant in `app/commerce-api/constants.js`.

   ```javascript
   export const DWSID_HEADER_KEY = "sfdc_dwsid";
   ```

### Step 6\: Update Commerce API Contexts

**note:** The Commerce API contexts have been updated to integrate with Commerce SDK React and React Query.

1. Open your `app/commerce-api/contexts.js` file.

2. Add these new imports at the top.

   ```javascript
   import { CommerceApiProvider as CommerceSDKReactProvider } from "@salesforce/commerce-sdk-react";
   import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
   import { getAppOrigin } from "pwa-kit-react-sdk/utils/url";
   import { isServer } from "../../pwa-kit-managed-runtime/utils/utils";
   ```

3. Add the `QueryClient` configuration after the imports.

   ```javascript
   const queryClientOptions = {
     queryClientConfig: {
       defaultOptions: {
         queries: {
           retry: false,
           refetchOnWindowFocus: false,
           staleTime: 10 * 1000,
           ...(isServer ? { retryOnMount: false } : {}),
         },
         mutations: {
           retry: false,
         },
       },
     },
     beforeHydrate: (data) => {
       const now = Date.now();
       const updateQueryTimeStamp = ({ state }) => {
         state.dataUpdatedAt = now;
       };
       data?.mutations?.forEach(updateQueryTimeStamp);
       data?.queries?.forEach(updateQueryTimeStamp);
       return data;
     },
   };

   const queryClient = new QueryClient(queryClientOptions);
   ```

4. Replace the existing `CommerceAPIProvider` with this new implementation.

   ```javascript
   export const CommerceAPIProvider = ({ value, children }) => {
     const { api, site, locale } = value;
     const apiClients = api._sdkInstances;

     const { shortCode, clientId, organizationId } = api.getConfig().parameters;
     const { proxy } = api.getConfig();

     return (
       <CommerceAPIContext.Provider value={api}>
         <QueryClientProvider client={queryClient}>
           <CommerceSDKReactProvider
             shortCode={shortCode}
             clientId={clientId}
             organizationId={organizationId}
             siteId={site?.id}
             locale={locale?.id}
             currency={locale?.preferredCurrency}
             redirectURI={`${getAppOrigin()}/callback`}
             proxy={proxy}
             apiClients={apiClients}
             disableAuthInit={true}
           >
             {children}
           </CommerceSDKReactProvider>
         </QueryClientProvider>
       </CommerceAPIContext.Provider>
     );
   };
   ```

5. Save the `app/commerce-api/contexts.js` file.

### Step 7\: Update the App Configuration Provider

**important:** **Critical Change:** The CommerceAPIProvider now requires different `props` structure.

1. Open your `app/components/_app-config/index.jsx` file.

2. Find the `CommerceAPIProvider` component and update it.

   Replace this code:

   ```javascript
   // Old implementation (v2.9.x)
   <CommerceAPIProvider value={locals.api}>
   ```

   With this code:

   ```javascript
   // New implementation (v2.10.0)
   <CommerceAPIProvider value={locals}>
   ```

3. Save the `app/components/_app-config/index.jsx` file.

### Step 8\: Cleanup Auth Initialization

1. Open your `app/components/_app/index.jsx` file.

2. Remove the login call.

   ```javascript
   // Auth initialization is now handled by calling await self.auth.ready() in commerce-api/index.js
   // Remove this line.
   await api.auth.login();
   ```

### Step 9\: Test Your Upgrade

1. Start the development server.

   ```bash
   npm start
   ```

2. Run the build to check for errors.

   ```bash
   npm run build
   ```

## (Optional) Use Commerce SDK React Query Hooks

With PWA Kit v2.10.0, you now have access to powerful query hooks from `@salesforce/commerce-sdk-react` that provide automatic caching, loading states, and error handling for both hybrid and non-hybrid PWA Kit v2.x storefronts. Here's how to use them in your pages.

### Example\: Simple Order List Component

Create a minimal order list component using the new query hooks.

```javascript
import React from "react";
import { useCustomerOrders } from "@salesforce/commerce-sdk-react";
import useCustomer from "../../commerce-api/hooks/useCustomer";

const SimpleOrderList = () => {
  const customer = useCustomer();

  const { data: { data: orders } = {}, isLoading } = useCustomerOrders(
    { parameters: { customerId: customer?.customerId } },
    { enabled: !!customer?.customerId },
  );

  if (isLoading) return <div>Loading orders...</div>;

  return (
    <div>
      <h2>My Orders</h2>
      {orders?.map((order) => (
        <div key={order.orderNo}>
          <p>
            Order #{order.orderNo} - {order.status}
          </p>
          <p>Total: ${order.orderTotal}</p>
        </div>
      ))}
    </div>
  );
};

export default SimpleOrderList;
```

## Key Benefits

Check out the key benefits of the new query hooks.

- Automatic caching—Data is cached and shared.
- Loading states—Built-in loading management.
- Error handling—Automatic error states.
- Optimized fetching—Only fetches when customer is available.
- Simplified code—Less manual state management.

## Additional Resources

- [PWA Kit Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-kit-overview.html)
- [Hybrid Storefront Basket Guidance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-storefront-baskets.md#hybrid-storefront-best-practices-for-working-with-baskets)
- [Commerce SDK React Documentation](https://salesforcecommercecloud.github.io/pwa-kit/)

<!-- document id=058f1180a7d6470e0f87ba086fba08bf395de25a1534780de4b3caee5fb3d00e url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/password-reset.md -->

# Implement Password Reset

PWA Kit provides the option to use password reset for shoppers. With password reset, if shoppers forget their password, they can use a verification code or a link in an email or text to regain access to their account by creating a new password. Include this feature in your [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.html) site for a better shopper experience.

Our [demo site](https://pwa-kit.mobify-storefront.com/) shows the default implementation of password reset.

To enable and configure password reset for your PWA Kit site, follow the steps in this guide. Throughout this guide we use an example storefront with the URL: `https://www.example.com`. Replace `example.com` with your domain name.

**note:** Password reset isn't supported in [hybrid storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.html).

## Prerequisites

- To use password reset, build your site using Composable Storefront and [Retail React App](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/README.md) version 6.0 or later.

**note:** Shoppers must log into your site with their username and password at least once before they can use password reset.

## Configure Password Reset

To configure password reset in your PWA Kit project, update `config/default.js` and set the configuration options.

These configuration options are available for password reset.

- `mode`: The password reset mode determines the method used to deliver the password reset link to the shopper. Valid values include `'email'` and `'callback'`.
- `callbackURI`: Only required in callback mode. The callback URI that SLAS makes an HTTP POST request to when mode is set to `'callback'`. The POST request includes the shoppers contact information and a time-based one-time password (TOTP) that can be used to authenticate the shopper. This can be an absolute URL, including third-party URIs, or a relative path set up by the developer. See more details in [Password Reset with Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html).
- `landingPath`: The landing path is the path the shopper is redirected to change their password.

This example shows a configuration for password reset with email mode.

```
module.exports = {
    app: {
       login: {
            // Configure reset password with email mode.
            resetPassword: {
                mode: 'email',
                landingPath: '/reset-password-landing',
            },

            // More code here...
```

This example shows a configuration for password reset with callback mode.

```
module.exports = {
    app: {
       login: {
            // Configure reset password with an absolute callback URL.
            resetPassword: {
                mode: 'callback',
                callbackURI: RESET_PASSWORD_CALLBACK_URI || 'https://example.com/reset-password-callback'
                landingPath: '/reset-password-landing',
            }

            // More code here...
```

These configuration modes are available for password reset.

- [Configure Email Mode](#configure-email-mode)
- [Configure Callback Mode](#configure-callback-mode)

## Configure Email Mode

With email mode, you use the SLAS native email service for sending a link to shoppers that they use to reset their password.

To configure email mode:

1. [Configure SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset-email.html)
2. [Complete the Email Mode Configuration in Your PWA Kit Project](#complete-the-email-mode-configuration-in-your-pwa-kit-project)

### Complete the Email Mode Configuration in Your PWA Kit Project

If you haven’t already done so, complete the [prerequisites](#prerequisites). After setting up the prerequisites, configure password reset with email mode in `config/default.js` as shown in this example.

```
module.exports = {
    app: {
        login: {

            // Configure reset password with email mode.
            resetPassword: {
                mode: 'email',
                landingPath: '/reset-password-landing',
            },

            // More code here...
```

## Configure Callback Mode

With callback mode, you specify a callback URI to use an external email or SMS service provider for sending the verification code or link to the shopper.

To set up callback mode:

1. [Configure the Callback URL](#1-configure-the-callback-url)
2. [Allowlist the Callback URL](#2-allowlist-the-callback-url)
3. [Complete the Callback Mode Configuration in Your PWA Kit Project](#3-complete-the-callback-mode-configuration-in-your-pwa-kit-project)

**note:** Unlike the Redirect URL field, the Callback URL field doesn’t support wildcards. Always include the full URL for a callback, including the protocol.

### 1. Configure the Callback URL

Provide a callback URL to SLAS. That way, SLAS can send that URL all the information your site needs to create a token (verification code or a link in an email or text) for a shopper. For more background information, see [Password Reset with Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html).

SLAS makes an HTTP POST request to the callback URL to forward the shopper's credentials to a destination of your choosing, typically an email or marketing service provider. By default, PWA Kit generates a secure link and uses Salesforce Agentforce Marketing to forward the link in an email. To customize this functionality, describe the mechanism that you want to use to ensure that shoppers get the eight-digit token generated by SLAS.

These are three possible options for describing the mechanism to provide a callback URL to SLAS. They're described in detail below.

<style>
ul.no-bullets {
    list-style-type: none;
}
</style>

<ul class="no-bullets">
  <li>a. Option 1: Use an External Callback URL</li>
 <li>b. Option 2: Use a Agentforce Marketing Integration</li>
 <li>c. Option 3: Use a Custom POST Endpoint in Your PWA Kit Project</li>
</ul>

#### a. Option 1: Use an External Callback URL

- Provide any publicly accessible external callback URL that can process the token delivery using the shopper’s email.

  Examples of this callback URL are a B2C Commerce instance, a Managed Runtime environment, or your own server.

- [Configure a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client). In the Callback URL field, enter your publicly accessible callback URL.

#### b. Option 2: Use a Agentforce Marketing Integration

If you have a Agentforce Marketing license you can send the token in an email or text (depending on your contract terms). This is the default implementation included in PWA Kit.

**Prerequisites**

For all prerequisites and steps that apply to using a Agentforce Marketing integration, see [Create a Transactional Send Journey](https://help.salesforce.com/s/articleView?id=mktg.mc_jb_create_transactional_journey.htm&type=5).

**Configure Your Integration**

To get the Agentforce Marketing configuration values below, see [Create an OAuth 2.0 API Integration](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/create-integration-enhanced.html).

- Set these environment variables in Managed Runtime.
  - `MARKETING_CLOUD_CLIENT_ID` to your Agentforce Marketing client ID
  - `MARKETING_CLOUD_CLIENT_SECRET` to your Agentforce Marketing client secret
  - `MARKETING_CLOUD_SUBDOMAIN` to your Agentforce Marketing subdomain
  - `MARKETING_CLOUD_RESET_PASSWORD_TEMPLATE` to the unique Event Definition Key for the [Transactional API Event](https://help.salesforce.com/s/articleView?id=mktg.mc_jb_create_transactional_journey.htm&type=5) attached to the email template that you stored in Agentforce Marketing.
    See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html).
- Configure the full callback URL in your SLAS Client. For example, `https://example.com/reset-password-callback`. See [Configure a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client).

If you want to customize the callback path from `/reset-password-callback`, also update it in `ssr.js` where the POST endpoint is set up. See option c. Use a Custom POST Endpoint in Your PWA Kit Project below.

#### c. Option 3: Use a Custom POST Endpoint in Your PWA Kit Project

- Configure a custom POST endpoint in `app/ssr.js` to handle token delivery using your chosen option: email or text. See this Agentforce Marketing implementation in `app/ssr.js` as an example.

```jsx
// Define a POST route for the '/reset-password-callback' endpoint.
app.post(/reset-password-callback, (req, res) => {
        const slasCallbackToken = req.headers['x-slas-callback-token']
        validateSlasCallbackToken(slasCallbackToken).then(() => {
            sendMagicLinkEmail(
                req,
                res,
                RESET_PASSWORD_LANDING_PATH,
                process.env.MARKETING_CLOUD_RESET_PASSWORD_TEMPLATE
            )
        })
    })
```

- [Configure a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client). In the Callback URL field, enter the callback URL that you set up in your custom POST endpoint.

### 2. Allowlist the Callback URL

For any of the three callback URL options, ensure that the callback URL that you configured is allowlisted in the `Callback URL` field of the SLAS client that you’re using. To do so:

- **Access SLAS Admin UI:** Log in to your Salesforce B2C Commerce instance and go to the SLAS Admin section.
- **Create or edit a client:** Select your SLAS client where you want to manage callback URLs.
- **Add allowed URLs:** In the client configuration, provide a list of the valid callback URLs for your site.

### 3. Complete the Callback Mode Configuration in Your PWA Kit Project

**a. Update `config/default.js`**

In your PWA Kit project, use the callback URL that you set up as part of the prerequisites to update `config/default.js` as follows.

```jsx
module.exports = {
    app: {
        login: {

            // Enable password reset with an absolute callback URL.
            resetPassword: {
                mode: 'callback',
                callbackURI: RESET_PASSWORD_CALLBACK_URI || 'https://example.com/reset-password-callback'
            }

            // More code here...
```

This example shows how to enable passwordless login with a relative callback URL.

```jsx
module.exports = {
    app: {
        login: {
            // Enable password reset with a relative callback URL.
            // This example callback URL uses the default Agentforce Marketing implementation.
            // You can customize the behavior of this callback URL endpoint in ssr.js.
            resetPassword: {
                mode: 'callback',
                callbackURI: RESET_PASSWORD_CALLBACK_URI || '/reset-password-callback'

            // More code here...
```

**b. (Optional) Use an Environment Variable to Set the Callback URL**

**note:** The value of the environment variable for password reset overrides any value that you added in `config/default.js`.

Use this environment variable to set the callback URL for password reset.

`RESET_PASSWORD_CALLBACK_URI`

See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

## Best Practices for Password Reset

- Implement rate limiting to prevent abuse of password reset. For example, if you’re using embedded CDN (eCDN), you can apply [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).
- Use robust security measures to protect shopper accounts. For example, if you’re using a third-party content delivery network (CDN) such as Cloudfare, you can [Block requests by Threat Score](https://developers.cloudflare.com/waf/custom-rules/use-cases/block-ip-reputation/).
- Track shopper usage of authentication options and diagnose issues efficiently. For example, use [Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-log-center) to access logs from Managed Runtime (MRT) and your B2C Commerce instance.

## Troubleshoot Password Reset

This section provides a suggested solution for a common error that you can encounter related to password reset.

### Password Reset Email Delivery Failure

**Potential Cause:** The email delivery service takes longer than expected or the shopper didn’t receive the email.

**Suggested Solution:** Include a resend option or allow shoppers to enter a backup contact method. Check for issues with spam filters.

## See Also

- [Password Reset](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html)

<!-- document id=d9feaa706077558affe217019cb5ceafe1dbc8a7ba2063868139a12a4b5fdadc url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-password-reset.md -->

# Implement Password Reset for Storefront Next

Storefront Next provides the option to use password reset for shoppers. With password reset, if shoppers forget their password, they can use a verification code or a link in an email or text to regain access to their account by creating a new password. Include this feature in your Storefront Next site for a better shopper experience.

Our [demo site](https://sfcc-odyssey-production.mobify-storefront.com/ shows the default implementation of password reset. Test the password reset flow on the demo site by clicking **Sign In**, and then **Forgot your password?**.

To enable and configure password reset for your Storefront Next site, follow the steps in this guide. Throughout this guide we use an example storefront with the URL: `https://www.example.com`. Replace `example.com` with your domain name.

**note:** Password reset isn't supported in [hybrid storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid.md).
Shoppers must log into your site with their username and password at least once before they can use password reset.

## Prerequisites

- To use password reset, build your site by using Storefront Next and the [Storefront Next template](https://github.com/SalesforceCommerceCloud/storefront-next-template) version 1.0.0 or later.

## Configure Password Reset

To configure password reset in your Storefront Next project, update `config.server.ts` and set the configuration options.

These configuration options are available for password reset.

- `mode`: The password reset mode determines the method used to deliver the password reset link to the shopper. Valid values include `'email'` and `'callback'`.
- `callbackURI`: Only required in callback mode. The callback URI that the Shopper Login and API Access Service (SLAS) makes an HTTP POST request to when mode is set to `'callback'`. The POST request includes the shoppers contact information and a time-based one-time password (TOTP) that can be used to authenticate the shopper. This can be an absolute URL, including third-party URIs, or a relative path set up by the developer. See more details in [Password Reset with Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html).
- `landingPath`: The landing path is the path the shopper is redirected to change their password.

This example shows a configuration for password reset with email mode.

module.exports = {
app: {
login: {
// Configure reset password with email mode.
resetPassword: {
mode: 'email',
landingPath: '/reset-password-landing',
},

            // More code here...

```

This example shows a configuration for password reset with callback mode.

module.exports = {
    app: {
       login: {
            // Configure reset password with an absolute callback URL.
            resetPassword: {
                mode: 'callback',
                callbackURI: RESET_PASSWORD_CALLBACK_URI || 'https://example.com/reset-password-callback'
                landingPath: '/reset-password-landing',
            }

            // More code here...
```

These configuration modes are available for password reset.

- [Configure Email Mode](#configure-email-mode)
- [Configure Callback Mode](#configure-callback-mode)

## Configure Email Mode

With email mode, you use the SLAS native email service for sending a link to shoppers that they use to reset their password.

To configure email mode:

1. [Configure SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset-email.html)
2. [Complete the Email Mode Configuration in Your Storefront Next Project](#complete-the-email-mode-configuration-in-your-storefront-next-project)

### Complete the Email Mode Configuration in Your Storefront Next Project

If you haven’t already done so, complete the [prerequisites](#prerequisites). After setting up the prerequisites, configure password reset with email mode in `config.server.ts` as shown in this example.

```
module.exports = {
app: {
login: {

            // Configure reset password with email mode.
            resetPassword: {
                mode: 'email',
                landingPath: '/reset-password-landing',
            },

            // More code here...

```

## Configure Callback Mode

With callback mode, you specify a callback URI to use an external email or SMS service provider for sending the verification code or link to the shopper.

To set up callback mode:

1. [Configure the Callback URL](#1-configure-the-callback-url)
2. [Allowlist the Callback URL](#2-allowlist-the-callback-url)
3. [Complete the Callback Mode Configuration in Your Storefront Next Project](#3-complete-the-callback-mode-configuration-in-your-storefront-next-project)

**note:** Unlike the Redirect URL field, the Callback URL field doesn’t support wildcards. Always include the full URL for a callback, including the protocol.

### 1. Configure the Callback URL

Provide a callback URL to SLAS. That way, SLAS can send that URL all the information your site needs to create a token (verification code or a link in an email or text) for a shopper. For more background information, see [Password Reset with Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html).

SLAS makes an HTTP POST request to the callback URL to forward the shopper's credentials to a destination of your choosing, typically an email or marketing service provider. By default, Storefront Next generates a secure link and uses Salesforce Agentforce Marketing to forward the link in an email. To customize this functionality, describe the mechanism that you want to use to ensure that shoppers get the eight-digit token generated by SLAS.

These are three possible options for describing the mechanism to provide a callback URL to SLAS. They're described in detail below.

<style>
ul.no-bullets {
    list-style-type: none;
}
</style>

<ul class="no-bullets">
  <li>a. Option 1: Use an External Callback URL</li>
 <li>b. Option 2: Use an Agentforce Marketing Integration</li>
 <li>c. Option 3: Use a Custom POST Endpoint in Your Storefront Next Project</li>
</ul>

#### a. Option 1: Use an External Callback URL

- Provide any publicly accessible external callback URL that can process the token delivery using the shopper’s email.

  Examples of this callback URL are a B2C Commerce instance, a Managed Runtime environment, or your own server.

- [Configure a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client). In the Callback URL field, enter your publicly accessible callback URL.

#### b. Option 2: Use an Agentforce Marketing Integration

If you have an Agentforce Marketing license you can send the token in an email or text (depending on your contract terms). This is the default implementation included in Storefront Next.

**Prerequisites**

For all prerequisites and steps that apply to using a Agentforce Marketing integration, see [Create a Transactional Send Journey](https://help.salesforce.com/s/articleView?id=mktg.mc_jb_create_transactional_journey.htm&type=5).

**Configure Your Integration**

To get the Agentforce Marketing configuration values below, see [Create an OAuth 2.0 API Integration](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/create-integration-enhanced.html).

- Set these environment variables in Managed Runtime.
  - `PUBLIC__app__features__MARKETING_CLOUD_CLIENT_ID` to your Agentforce Marketing client ID
  - `PUBLIC__app__features__MARKETING_CLOUD_CLIENT_SECRET` to your Agentforce Marketing client secret
  - `PUBLIC__app__features__MARKETING_CLOUD_SUBDOMAIN` to your Agentforce Marketing subdomain
  - `PUBLIC__app__features__MARKETING_CLOUD_RESET_PASSWORD_TEMPLATE` to the unique Event Definition Key for the [Transactional API Event](https://help.salesforce.com/s/articleView?id=mktg.mc_jb_create_transactional_journey.htm&type=5) attached to the email template that you stored in Agentforce Marketing.
    <!-- See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html). -->
- Configure the full callback URL in your SLAS Client. For example, `https://example.com/reset-password-callback`. See [Configure a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client).

If you want to customize the callback path from `/reset-password-callback`, also update it in `ssr.js` where the POST endpoint is set up. See option c. Use a Custom POST Endpoint in Your Storefront Next Project below.

#### c. Option 3: Use a Custom POST Endpoint in Your Storefront Next Project

- Configure a custom POST endpoint in `app/ssr.js` to handle token delivery using your chosen option: email or text. See this Agentforce Marketing implementation in `app/ssr.js` as an example.

```jsx
// Define a POST route for the '/reset-password-callback' endpoint.
app.post(/reset-password-callback, (req, res) => {
        const slasCallbackToken = req.headers['x-slas-callback-token']
        validateSlasCallbackToken(slasCallbackToken).then(() => {
            sendMagicLinkEmail(
                req,
                res,
                RESET_PASSWORD_LANDING_PATH,
                process.env.MARKETING_CLOUD_RESET_PASSWORD_TEMPLATE
            )
        })
    })
```

- [Configure a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client). In the Callback URL field, enter the callback URL that you set up in your custom POST endpoint.

### 2. Allowlist the Callback URL

For any of the three callback URL options, ensure that the callback URL that you configured is allowlisted in the `Callback URL` field of the SLAS client that you’re using. To do so:

- **Access SLAS Admin UI:** Log in to your Salesforce B2C Commerce instance and go to the SLAS Admin section.
- **Create or edit a client:** Select your SLAS client where you want to manage callback URLs.
- **Add allowed URLs:** In the client configuration, provide a list of the valid callback URLs for your site.

### 3. Complete the Callback Mode Configuration in Your Storefront Next Project

**a. Update `config/default.js`**

In your Storefront Next project, use the callback URL that you set up as part of the prerequisites to update `config.server.ts` as follows.

```jsx
module.exports = {
    app: {
        login: {

            // Enable password reset with an absolute callback URL.
            resetPassword: {
                mode: 'callback',
                callbackURI: RESET_PASSWORD_CALLBACK_URI || 'https://example.com/reset-password-callback'
            }

            // More code here...
```

This example shows how to enable passwordless login with a relative callback URL.

```jsx
module.exports = {
    app: {
        login: {
            // Enable password reset with a relative callback URL.
            // This example callback URL uses the default Agentforce Marketing implementation.
            // You can customize the behavior of this callback URL endpoint in ssr.js.
            resetPassword: {
                mode: 'callback',
                callbackURI: RESET_PASSWORD_CALLBACK_URI || '/reset-password-callback'

            // More code here...
```

**b. (Optional) Use an Environment Variable to Set the Callback URL**

**note:** The value of the environment variable for password reset overrides any value that you added in `config.server.ts`.

Use this environment variable to set the callback URL for password reset.

`PUBLIC__app__features__RESET_PASSWORD_CALLBACK_URI`

<!-- Link TDB See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md). -->

## Best Practices for Password Reset

- Implement rate limiting to prevent abuse of password reset. For example, if you’re using embedded CDN (eCDN), you can apply [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).
- Use robust security measures to protect shopper accounts. For example, if you’re using a third-party content delivery network (CDN) such as Cloudfare, you can [Block requests by Threat Score](https://developers.cloudflare.com/waf/custom-rules/use-cases/block-ip-reputation/).
- Track shopper usage of authentication options and diagnose issues efficiently. For example, use [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5).

## Troubleshoot Password Reset

This section provides a suggested solution for a common error that you can encounter related to password reset.

### Password Reset Email Delivery Failure

**Potential Cause:** The email delivery service takes longer than expected or the shopper didn’t receive the email.

**Suggested Solution:** Include a resend option or allow shoppers to enter a backup contact method. Check for issues with spam filters.

## See Also

- [Password Reset](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html)

<!-- document id=06d188a46ac4f29748095538fea510ed934fd953e9dd0480ca5e2cef614ddc9f url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/passwordless-login.md -->

# Implement Passwordless Login

PWA Kit provides the option to use passwordless login for your shoppers. With passwordless login, shoppers can securely log into your site using a verification code or a link in an email or text instead of a password. Include this feature in your [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.html) site for a better shopper experience.

Our [demo site](https://pwa-kit.mobify-storefront.com/) shows the default implementation of passwordless login.

To enable and configure passwordless login for your PWA Kit site, follow the steps in this guide. Throughout this guide we use an example storefront with the URL: `https://www.example.com`. Replace `example.com` with your domain name.

**note:** Passwordless login isn't supported in [hybrid storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.html).

## Prerequisites

To use passwordless login:

- Build your site using Composable Storefront and [Retail React App](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/README.md) version 6.0 or later.
- Configure a Shopper Login and API Access (SLAS) private client. For the specifics involved in configuring a SLAS private client for passwordless login, see [Configure Passwordless Login](#configure-passwordless-login).

**note:** Shoppers must log into your site with their username and password at least once before they can use passwordless login.

## Configure Passwordless Login

To configure passwordless login in your PWA Kit project, update `config/default.js` and set the configuration options.

These configuration options are available for passwordless login.

- `enabled`: Enables or disables passwordless login for the site. Defaults to `false`.
- `mode`: The passwordless login mode that determines the method used to deliver the verification code or login link to the shopper. Valid values include `'email'` and `'callback'`.
- `callbackURI`: Only required in callback mode. The callback URI that SLAS makes an HTTP POST request to when mode is set to `'callback'`. The POST request includes the shoppers contact information and a time-based one-time password (TOTP) that can be used to authenticate the shopper. This can be an absolute URL, including third-party URIs, or a relative path set up by the developer. More details in [Passwordless Login with One-Time Passwords using Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html).
- `landingPath`: The landing path is the path of the magic link. A magic link is a single-use URL that contains the TOTP and that shoppers click to log into the storefront.
- `tokenLength`: The length of the token for passwordless login. Set the token length by using the environment variable `OTP_TOKEN_LENGTH`. Valid values include 6 or 8. Defaults to 8. Make sure that the token length matches with the token length set for the [SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#1-configure-a-slas-private-client).

This example shows a configuration for passwordless login with email mode.

```
module.exports = {
    app: {
        login: {
            tokenLength: validateOtpTokenLength(process.env.OTP_TOKEN_LENGTH),

            // Enable passwordless login with email mode.
            passwordless: {
                enabled: true,
                mode: 'email',
                landingPath: '/passwordless-login-landing',
            },

            // More code here...
```

This example shows a configuration for passwordless login with a callback URL.

```
module.exports = {
    app: {
       login: {
            tokenLength: validateOtpTokenLength(process.env.OTP_TOKEN_LENGTH),

            // Enable passwordless login with an absolute callback URL.
            passwordless: {
                enabled: true,
                mode: 'callback',
                callbackURI: 'https://example.com/passwordless-login-callback'
                landingPath: '/passwordless-login-landing',
            }

            // More code here...
```

These configuration modes are available for passwordless login.

- [Configure Email Mode](#configure-email-mode)
- [Configure Callback Mode](#configure-callback-mode)

## Configure Email Mode

With email mode, you use the SLAS native email service for sending a verification code or magic link to shoppers.

To configure email mode:

1. [Configure SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html)
2. [Complete the Email Mode Configuration in Your PWA Kit Project](#complete-the-email-mode-configuration-in-your-pwa-kit-project)

## Complete the Email Mode Configuration in Your PWA Kit Project

If you haven’t already done so, complete the [prerequisites](#prerequisites). After setting up the prerequisites, configure passwordless login with email mode in `/config/default.js` as shown in this example.

```
module.exports = {
    app: {
        login: {

            // Enable passwordless login with email mode
            passwordless: {
                enabled: true,
                mode: 'email',
                landingPath: '/passwordless-login-landing',
            }

            // More code here...
```

## Configure Callback Mode

With callback mode, you specify a callback URI to use an external email or SMS service provider for sending the verification code or link to the shopper.

To set up callback mode:

1. [Configure the Callback URL](#1-configure-the-callback-url)
2. [Allowlist the Callback URL](#2-allowlist-the-callback-url)
3. [Complete the Call Mode Configuration in Your PWA Kit Project](#3-complete-the-callback-mode-configuration-in-your-pwa-kit-project)

**note:** Unlike the Redirect URL field, the Callback URL field doesn’t support wildcards. Always include the full URL for a callback, including the protocol.

### 1. Configure the Callback URL

Provide a callback URL to SLAS. That way, SLAS can send that URL all the information your site needs to create a login token—a verification code or a link in an email or text—for a shopper. For more background information, see [Passwordless Login with One-Time Passwords using Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html)

SLAS makes an HTTP POST request to the callback URL to forward the shopper's credentials to a destination of your choosing, typically an email or marketing service provider. By default, PWA Kit generates a secure link and uses Salesforce Agentforce Marketing to forward the link in an email. To customize this functionality, describe the mechanism that you want to use to ensure that shoppers get the eight-digit passwordless token generated by SLAS.

These are the possible options for describing the mechanism to provide a callback URL to SLAS. They're described in detail next.

<style>
ul.no-bullets {
    list-style-type: none;
}
</style>

<ul class="no-bullets">
  <li>a. Option 1: Use an External Callback URL</li>
 <li>b. Option 2: Use a Agentforce Marketing Integration</li>
 <li>c. Option 3: Use a Custom POST Endpoint in Your PWA Kit Project</li>
</ul>

#### a. Option 1: Use an External Callback URL

- Provide any publicly accessible external callback URL that can process the token delivery using the shopper’s email.

  Examples of this callback URL are a B2C Commerce instance, a Managed Runtime environment, or your own server.

- [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html?q=passwordless#configure-a-slas-private-client). In the Callback URL field, enter your publicly accessible callback URL.

#### b. Option 2: Use a Agentforce Marketing Integration

If you have a Agentforce Marketing license you can send the token in an email or text (depending on your contract terms). This is the default implementation included in PWA Kit.

**Prerequisites**

For all prerequisites and steps that apply to using a Agentforce Marketing integration, see these guides.

- [Passwordless Login with SMS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-sms.html)
- [Create a Transactional Send Journey](https://help.salesforce.com/s/articleView?id=mktg.mc_jb_create_transactional_journey.htm&type=5)

**Configure Your Integration**

To get the Agentforce Marketing configuration values below, see [Create an OAuth 2.0 API Integration](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/create-integration-enhanced.html).

- Set these environment variables in Managed Runtime.
  - `MARKETING_CLOUD_CLIENT_ID` to your Agentforce Marketing client ID
  - `MARKETING_CLOUD_CLIENT_SECRET` to your Agentforce Marketing client secret
  - `MARKETING_CLOUD_SUBDOMAIN` to your Agentforce Marketing subdomain
  - `MARKETING_CLOUD_PASSWORDLESS_LOGIN_TEMPLATE` to the unique Event Definition Key for the [Transactional API Event](https://help.salesforce.com/s/articleView?id=mktg.mc_jb_create_transactional_journey.htm&type=5) attached to the email template that you stored in Agentforce Marketing.
    See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html).
- Configure the full callback URL in your SLAS Client. For example, `https://example.com/passwordless-login-callback`. See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html?q=passwordless#configure-a-slas-private-client).

If you want to customize the callback path from `/passwordless-login-callback`, also update it in `ssr.js` where the POST endpoint is set up. See option c. Use a Custom POST Endpoint in Your PWA Kit Project below.

#### c. Option 3: Use a Custom POST Endpoint in Your PWA Kit Project

- Configure a custom POST endpoint in `app/ssr.js` to handle token delivery using your chosen option: email or text. See this Agentforce Marketing implementation in `app/ssr.js` as an example.

```jsx
// Define a POST route for the '/passwordless-login-callback' endpoint.
app.post('/passwordless-login-callback', (req, res) => {
        const slasCallbackToken = req.headers['x-slas-callback-token']
        validateSlasCallbackToken(slasCallbackToken).then(() => {
            sendMagicLinkEmail(
                req,
                res,
                PASSWORDLESS_LOGIN_LANDING_PATH,
                process.env.MARKETING_CLOUD_PASSWORDLESS_LOGIN_TEMPLATE
            )
        })
    }
```

- [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html?q=passwordless#configure-a-slas-private-client). In the Callback URL field, enter the callback URL that you set up in your custom POST endpoint.

### 2. Allowlist the Callback URL

For any of the three callback URL options, ensure that the callback URL that you configured is allowlisted in the `Callback URL` field of the SLAS client that you’re using. To do so:

- **Access SLAS Admin UI:** Log in to your Salesforce B2C Commerce instance and go to the SLAS Admin section.
- **Create or edit a client:** Select your SLAS client where you want to manage callback URLs.
- **Add allowed URLs:** In the client configuration, provide a list of the valid callback URLs for your site.

### 3. Complete the Callback Mode Configuration in Your PWA Kit Project

**a. Update `config/default.js`**

If you haven’t already done so, complete the [Prerequisites](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html?q=passwordless#prerequisites).

To configure passwordless login in your PWA Kit project, update `config/default.js` as shown in this example.

In your PWA Kit project, use the callback URL that you set up as part of the prerequisites to update `config/default.js` as follows.

```jsx
module.exports = {
    app: {
        login: {

            // Enable passwordless login with an absolute callback URL.
            passwordless: {
                enabled: true,
                mode: 'callback',
                callbackURI: 'https://example.com/passwordless-login-callback'
            }

            // More code here...
```

This example shows how to enable passwordless login with a relative callback URL.

```jsx
module.exports = {
    app: {
        login: {
            // Enable passwordless login with a relative callback URL.
            // This example callback URL uses the default Agentforce Marketing implementation.
            // You can customize the behavior of this callback URL endpoint in ssr.js.
            passwordless: {
                enabled: true,
                mode: 'callback',
                callbackURI: '/passwordless-login-callback'


            // More code here...
```

**b. Optional: Use an Environment Variable to Set the Callback URL**

**note:** The value of the environment variable for passwordless login overrides any values that you added in `/config/default.js`.

Optionally, you can set the callback URL using an environment variable instead of `config/default.js`. Use `config/default.js` to enable passwordless login. Configure this environment variable to set the callback URL.

`PASSWORDLESS_LOGIN_CALLBACK_URI`

See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

## Best Practices for Passwordless Login

- Implement rate limiting to prevent abuse of the passwordless login feature. For example, if you’re using embedded CDN (eCDN), you can apply [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).
- Use robust security measures to protect shopper accounts. For example, if you’re using a third-party content delivery network (CDN) such as Cloudfare, you can [Block requests by Threat Score](https://developers.cloudflare.com/waf/custom-rules/use-cases/block-ip-reputation/).
- Track shopper usage of authentication options and diagnose issues efficiently. For example, use [Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-log-center) to access logs from Managed Runtime (MRT) and your B2C Commerce instance.

## Troubleshoot Passwordless Login

This section provides a suggested solution for a common error that you can encounter related to passwordless login.

### Unexpected Results with Passwordless Login

**Potential Cause:** The scope or callback URL is incorrect.

**Suggested Solution:** Ensure that the scope and callback URL are properly configured. See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html?q=passwordless#configure-a-slas-private-client).

## See Also

- [Passwordless Login with SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html)
- [Passwordless Login with SMS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-sms.html)

<!-- document id=2a57aca38e6fddeddc7d57380538eb98ad8d01497203132562c38106b61e343e url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/social-login.md -->

# Implement Social Login

PWA Kit comes out of the box with the option to use social login for your shoppers. Include the feature in your [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.html) site to improve the shopper experience. With social login, shoppers can quickly log into your site and create profiles by using their social network accounts.

Our [demo site](https://pwa-kit.mobify-storefront.com/) shows the default implementation of social login.

To enable and configure social login for your PWA Kit site, follow the steps in this guide. Throughout this guide we use an example storefront with the URL: `https://www.example.com`. Replace `example.com` with your domain name.

## Supported IdPs

PWA Kit supports the identity providers (IdPs) listed under [Supported Identity Providers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#supported-identity-providers).

If you meet the [prerequisites](#prerequisites), the Google and Apple social logins are available in the Retail React App by default.

## Prerequisites

To use social login:

- Build your site using Composable Storefront and [Retail React App](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/README.md) version 6.0 or later.
- To add your chosen IdP, complete the steps in [Registering an Identity Provider](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#registering-an-identity-provider).
- [Configure a Shopper Login and API Access (SLAS) Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client). In your client’s Redirect URI field, enter the redirect URI that you want to use in the social login flow. By default, PWA Kit uses `/social-callback` as the path. For example, if your domain is `example.com`, enter: `https://www.example.com/social-callback`. Replace `example.com` with your actual domain.

## Configure Social Login in PWA Kit

**a. Update `template-retail-react-app/config/default.js`**

To configure social login in your PWA Kit project, update `template-retail-react-app/config/default.js` as shown in this example.

Ensure that the redirect URI path configured in your PWA Kit project matches the path configured in your SLAS client. The SLAS client can use a wildcard for the full URI, but the paths must match exactly.

```jsx
module.exports = {
    app: {
        login: {
            social: {

               // Enable social login and add your chosen IdPs and Redirect URI.
                enabled: true,
                idps: ['Google', 'Apple'],
                redirectURI: '/social-callback' // relative path
            }
            // More code here...

         sites,
         commerceAPI: {
            proxyPath: `/mobify/proxy/api`,
            parameters: {

            // Add your clientId, organizationId, short code, and siteId.
                clientId: 'c9c45bfd-0ed3-4aa2-9971-40f88962b836',
                organizationId: 'f_ecom_zzrf_001',
                shortCode: '8o7m175y',
                siteId: 'RefArchGlobal'
            }

           // More code here...
```

**b. Optional: Use an Environment Variable to Set the Redirect URI**

**note:** The value of the environment variable for social login overrides any values that you added in `template-retail-react-app/config/default.js`.

Optionally, you can set the redirect URI using an environment variable instead of `template-retail-react-app/config/default.js`. Use `template-retail-react-app/config/default.js` to enable social login and set the IdPs. Configure this environment variable to set the redirect URI.

`SOCIAL_LOGIN_REDIRECT_URI`

See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

## Add Icons for Supported IdPs

By default, PWA Kit imports and configures the icons for the Google and Apple social logins in the `SocialLogin` component in the `template-retail-react-app/app/components/social-login/index.jsx` file. On your site, you can include icons for other [supported IdPs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#supported-identity-providers). To do so, complete these steps.

**a. Import Icons into the `SocialLogin` Component**

In this example, we import the Facebook icon into the `SocialLogin` component.

```jsx
// Icons
import {
  AppleIcon,
  GoogleIcon,
  FacebookIcon
} from '@salesforce/retail-react-app/app/components/icons'
```

**b. Extend the `IDP_CONFIG` Object**

Use the `IDP_CONFIG` object in the `SocialLogin` component to display buttons for your additional social logins, each with their respective icons and localized messages.

In this example, we add the configuration for Facebook. Ensure that each IdP key matches the lowercase name of your chosen IdP.

```jsx
const IDP_CONFIG = {
  apple: {
    icon: AppleIcon,
    message: defineMessage({
      id: 'login_form.button.apple',
      defaultMessage: 'Apple'
    })
  },
  google: {
    icon: GoogleIcon,
    message: defineMessage({
      id: 'login_form.button.google',
      defaultMessage: 'Google'
    })
  },
  facebook: {
    icon: FacebookIcon,
    message: defineMessage({
      id: 'login_form.button.facebook',
      defaultMessage: 'Facebook'
    })
  }
}
```

## Best Practices for Social Login

- Follow security best practices to protect shopper accounts. For example:
  - If you’re using embedded CDN (eCDN), you can apply [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).
  - If you’re using a third-party content delivery network (CDN) such as Cloudfare, you can [Block requests by Threat Score](https://developers.cloudflare.com/waf/custom-rules/use-cases/block-ip-reputation/).
- Track shopper usage of authentication options and diagnose issues efficiently. For example, use [Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-log-center) to access logs from Managed Runtime (MRT) and your B2C Commerce instance.
- [Merge Shopper Profiles](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html) in Shopper Login and API Access Service (SLAS) to ensure that shoppers with both a B2C Commerce identity and a third-party IdP can log in seamlessly without creating duplicate accounts.

**note:** - If both profiles exist before you configured `loginMergeClaims` and before a shopper logged into your site, no merge is performed. Accounts can't be merged retroactively.
- The steps in the Merge Shopper Profiles guide apply to shoppers who have the same login ID for their B2C Commerce profile and a third-party IdP.

For more details about merging profiles and the supported use cases, see [Merge Shopper Profiles](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html).

## Troubleshoot Social Login

This section provides suggested solutions for a few common errors that you can encounter related to social login.

### Shoppers Can’t Log in

**Potential Cause:** The social login configuration is incorrect.

**Suggested Solution:** Ensure that the redirect URI path configured in your PWA Kit project matches the path configured in your SLAS client. See [Configure Social Login](#configure-social-login-in-pwa-kit).

### Shopper Profile Conflicts Occur

**Potential Cause:** Shoppers have separate profiles for B2C Commerce and third-party IdPs.

**Suggested Solution:** Follow the steps in [Merge Shopper Profiles](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html) to merge records for shoppers registered with B2C Commerce and a third-party IdP.

## See Also

- [SLAS Identity Providers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html)

<!-- document id=8ba393c600df0655053e4f39b29deaa318b1db60300d6337dbdf09c15f9e9fa1 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-social-login.md -->

# Implement Social Login for Storefront Next

Storefront Next offers a native social login feature for your shoppers. Include social login in your Storefront Next site to improve the shopper experience. With social login, shoppers can quickly log into your site and create profiles by using their social network accounts.

Our [demo site](https://sfcc-odyssey-production.mobify-storefront.com/) shows the default implementation of social login. Test the social login flow on the demo site by clicking **Sign In**, and then **Continue with Apple** or **Continue with Google**.

To enable and configure social login for your Storefront Next site, follow the steps in this guide. Throughout this guide we use an example storefront with the URL: `https://www.example.com`. Replace `example.com` with your domain name.

## Supported IdPs

Storefront Next supports the identity providers (IdPs) listed under [Supported Identity Providers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#supported-identity-providers).

If you meet the [prerequisites](#prerequisites), the Google and Apple social logins are available in the Retail React App by default.

## Prerequisites

- To use password reset, build your site by using Storefront Next and the [Storefront Next template](https://github.com/SalesforceCommerceCloud/storefront-next-template) version 1.0.0 or later.
- Add your chosen IdP by completing the steps in [Registering an Identity Provider](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#registering-an-identity-provider).
- [Configure a Shopper Login and API Access (SLAS) Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client). In your client’s Redirect URI field, enter the redirect URI that you want to use in the social login flow. By default, Storefront Next uses `/social-callback` as the path. For example, if your domain is `example.com`, enter: `https://www.example.com/social-callback`. Replace `example.com` with your actual domain.

## Configure Social Login in Storefront Next

### Update `config.server.ts`

To configure social login in your Storefront Next project, update `config.server.ts` as shown in this example.

Ensure that the redirect URI path configured in your Storefront Next project matches the path configured in your SLAS client. The SLAS client can use a wildcard for the full URI, but the paths must match exactly.

```jsx
module.exports = {
    app: {
        login: {
            social: {

               // Enable social login and add your chosen IdPs and Redirect URI.
                enabled: true,
                idps: ['Google', 'Apple'],
                redirectURI: '/social-callback' // relative path
            }
            // More code here...

         sites,
         commerceAPI: {
            proxyPath: `/mobify/proxy/api`,
            parameters: {

            // Add your clientId, organizationId, short code, and siteId.
                clientId: 'c9c45bfd-0ed3-4aa2-9971-40f88962b836',
                organizationId: 'f_ecom_zzrf_001',
                shortCode: '8o7m175y',
                siteId: 'RefArchGlobal'
            }

           // More code here...
```

### Optional: Use an Environment Variable to Set the Redirect URI

**note:** The value of the environment variable for social login overrides any values that you added in `config.server.ts`.

Optionally, you can set the redirect URI using an environment variable instead of `config.server.ts`. Use `config.server.ts` to enable social login and set the IdPs. Configure this environment variable to set the redirect URI.

`PUBLIC__app__features__SOCIAL_LOGIN_REDIRECT_URI`

<!-- See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md). -->

## Add Icons for Supported IdPs

By default, Storefront Next imports and configures the icons for the Google and Apple social logins in the `SocialLogin` component in the `template-retail-react-app/app/components/social-login/index.jsx` file. On your site, you can include icons for other [supported IdPs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html#supported-identity-providers). To do so, complete these steps.

### Import Icons into the `SocialLogin` Component

In this example, we import the Facebook icon into the `SocialLogin` component.

```jsx
// Icons
import {
  AppleIcon,
  GoogleIcon,
  FacebookIcon,
} from "@salesforce/retail-react-app/app/components/icons";
```

### Extend the `IDP_CONFIG` Object

Use the `IDP_CONFIG` object in the `SocialLogin` component to display buttons for your additional social logins, each with their respective icons and localized messages.

In this example, we add the configuration for Facebook. Ensure that each IdP key matches the lowercase name of your chosen IdP.

```jsx
const IDP_CONFIG = {
  apple: {
    icon: AppleIcon,
    message: defineMessage({
      id: "login_form.button.apple",
      defaultMessage: "Apple",
    }),
  },
  google: {
    icon: GoogleIcon,
    message: defineMessage({
      id: "login_form.button.google",
      defaultMessage: "Google",
    }),
  },
  facebook: {
    icon: FacebookIcon,
    message: defineMessage({
      id: "login_form.button.facebook",
      defaultMessage: "Facebook",
    }),
  },
};
```

## Best Practices for Social Login

- Follow security best practices to protect shopper accounts. For example:
  - If you’re using embedded CDN (eCDN), you can apply [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-rate-limiting-rules.html).
  - If you’re using a third-party content delivery network (CDN) such as Cloudfare, you can [Block requests by Threat Score](https://developers.cloudflare.com/waf/custom-rules/use-cases/block-ip-reputation/).
- Track shopper usage of authentication options and diagnose issues efficiently. For example, use [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5) to access logs from Managed Runtime (MRT) and your B2C Commerce instance.
- [Merge Shopper Profiles](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html) in Shopper Login and API Access Service (SLAS) to ensure that shoppers with both a B2C Commerce identity and a third-party IdP can log in seamlessly without creating duplicate accounts.

**note:** - If both profiles exist before you configured `loginMergeClaims` and before a shopper logged into your site, no merge is performed. Accounts can't be merged retroactively.
- The steps in the Merge Shopper Profiles guide apply to shoppers who have the same login ID for their B2C Commerce profile and a third-party IdP.

For more details about merging profiles and the supported use cases, see [Merge Shopper Profiles](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html).

## Troubleshoot Social Login

This section provides suggested solutions for a few common errors that you can encounter related to social login.

### Shoppers Can’t Log in

**Potential Cause:** The social login configuration is incorrect.

**Suggested Solution:** Ensure that the redirect URI path configured in your Storefront Next project matches the path configured in your SLAS client. See [Configure Social Login](#configure-social-login-in-storefront-next).

### Shopper Profile Conflicts Occur

**Potential Cause:** Shoppers have separate profiles for B2C Commerce and third-party IdPs.

**Suggested Solution:** Follow the steps in [Merge Shopper Profiles](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html) to merge records for shoppers registered with B2C Commerce and a third-party IdP.

## See Also

- [SLAS Identity Providers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html)

<!-- document id=63f14ea73f18ca67a2f522e7eafdd417409917a2a7ea1dd4a7a65ad24b3080cb url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-implementation-considerations.md -->

# Implementation Considerations

Use this topic for UCP extensibility architecture and custom hook implementations. If you're still deciding **whether** you need custom work, start with the [Technical Audit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-technical-audit.md).

- [UCP Extensibility Architecture](#ucp-extensibility-architecture) — when hooks fire
- [Extension Hooks Reference](#extension-hooks-reference) — hook catalog
- [UCP Checkout Session Validation](#ucp-checkout-session-validation) — flashes, status, response shaping
- [Payment Configuration](#payment-configuration) — Salesforce Payments vs third-party providers
- [Adyen Webhook Filtering for Shared Merchant Accounts](#adyen-webhook-filtering-for-shared-merchant-accounts) — Salesforce Payments (Adyen) only
- [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md) — how OMS updates become signed UCP snapshots

## UCP Extensibility Architecture

UCP follows the standard [SCAPI extensibility with Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) pattern, including [hook script execution](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#hook-scripts).

**Core concept:** A UCP Checkout Session is a headless "view" on a standard Commerce Cloud [Basket](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/scriptapi/html/index.html?target=class_dw_order_Basket.html). Standard Basket and Order hooks (`calculate`, `calculateTax`, `calculateShipping`, `validateBasket`, `createOrderNo`) run automatically. UCP isn't a second checkout to build—it's an API in front of the basket you already have. Because it's headless, storefront UI/controllers are bypassed, and **hooks registered on other SCAPI resources (Shopper Baskets, Shopper Orders, and similar) don't run**. Remap that logic onto the UCP checkout-session hooks below. The [Technical Audit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-technical-audit.md) has the inventory checklist.

**note:** **Enable Salesforce Commerce API Hook Execution**

This Business Manager feature toggle is **required** for end-to-end UCP checkout. Checkout-session operations depend on default hook execution (`calculate`, `calculateTax`, `calculateShipping`, `validateBasket`, `createOrderNo`, and related payment hooks). If the toggle is off, those hooks don't run and a shopper can't complete a checkout session—custom third-party payment hooks don't run either. Enable it before you test or go live.

### Extensibility Models

These diagrams show how hooks are invoked during each Checkout Session operation. Each diagram shows the sequence of platform operations and hook invocation points:

#### How to Read the Diagrams

- **Boxes with labels:** Platform service operations or hook execution points
- **Flow direction:** Operations proceed left to right
- **Hook names:** Extension points where your custom code can execute
- **Multiple hooks:** May execute in sequence during a single operation

#### POST /checkout-sessions - Create Checkout Session

Opens a new UCP checkout session, creates the underlying basket.

![POST checkout-sessions extensibility model](https://developer.salesforce.com/media/b2c-commerce/ucp-create-checkout-session.png)

#### PUT /checkout-sessions/{id} - Update Checkout Session

Updates/replaces products, buyer information, fulfillment, etc. on the underlying basket.

![PUT checkout-sessions extensibility model](https://developer.salesforce.com/media/b2c-commerce/ucp-update-checkout-session.png)

#### GET /checkout-sessions/{id} - Get Checkout Session

Returns the current basket state as a checkout session.

![GET checkout-sessions extensibility model](https://developer.salesforce.com/media/b2c-commerce/get-checkout-sessions.png)

#### POST /checkout-sessions/{id}/cancel - Cancel Checkout Session

Cancel the checkout session, delete the basket (terminal).

![POST cancel checkout-sessions extensibility model](https://developer.salesforce.com/media/b2c-commerce/cancel-checkout-sessions.png)

#### POST /checkout-sessions/{id}/complete - Complete Checkout Session

Updates the billing address on the basket, creates the order, takes payment, and facilitates order placement. This operation is only available once the checkout session has the `ready_for_complete` status.

Complete uses **more than one** database transaction. Read [Transaction Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-transaction-management.md) before you put callouts or `Transaction.wrap()` in complete-flow hooks.

##### Complete Transaction 1

![POST complete checkout-sessions t1 extensibility model](https://developer.salesforce.com/media/b2c-commerce/ucp-complete-transaction1.png)

##### Complete Transaction 2 - SFP (Default)

![POST complete checkout-sessions sfp t2 extensibility model](https://developer.salesforce.com/media/b2c-commerce/ucp-complete-sfp-transaction2.png)

##### Complete Transaction 2 - Third-Party

![POST complete checkout-sessions 3pp t2 extensibility model](https://developer.salesforce.com/media/b2c-commerce/ucp-complete-3pp-transaction2.png)

#### SFP Adyen Notification — Async Place Order

Salesforce Payments places the order on the gateway webhook, not in `/complete`. This diagram is the Adyen `AUTHORISATION` step. Stripe Salesforce Payments is also webhook-placed (`payment_intent.succeeded`). See [If You Use Salesforce Payments](#if-you-use-salesforce-payments-default).

![Adyen notification async flow](https://developer.salesforce.com/media/b2c-commerce/adyen-notification-flow.png)

## Extension Hooks Reference

This is the hook catalog for UCP. Every Checkout Session hook returns a `dw.system.Status`.

**Transactional** is whether the hook runs inside a platform-managed database transaction:

- **Yes** — persist Script API changes (basket or order). Returning `ERROR` rolls back **that** transaction.
- **No** — the hook isn't in a transaction. Shape the response or payload only. Persisting Script API objects can cause an `ORMTransactionException`.

Complete uses more than one transaction, so **Yes** doesn't mean the whole `/complete` request rolls back. Which transaction a complete-flow hook runs in—and what an `ERROR` actually undoes—is in [Transaction Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-transaction-management.md).

- [Standard Basket and Order Hooks](#standard-basket-and-order-hooks)
- [Lifecycle Hooks: Create, Get, and Update](#lifecycle-hooks-create-get-and-update)
- [Cancel Hooks](#cancel-hooks)
- [Complete Hooks](#complete-hooks)
- [Payment Hooks](#payment-hooks)
- [Business Profile and Order Webhooks](#business-profile-and-order-webhooks)

For the UCP Checkout schema structure, see the [Checkout reference](https://ucp.dev/2026-04-08/specification/reference/#checkout). B2C Commerce 26.9 also serves protocol version `2026-01-23`; see [Protocol Versions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#protocol-versions).

### Standard Basket and Order Hooks

These run automatically on checkout-session mutations. They are not UCP-specific extension points.

| Hook                                  | Arguments                                                                                                                   | Transactional | Typical Use                                      |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------ |
| `dw.order.calculate`                  | [Script Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.html) | Yes           | Pricing and basket totals                        |
| `dw.order.calculateTax`               | [Script Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.html) | Yes           | Tax calculation                                  |
| `dw.order.calculateShipping`          | [Script Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.html) | Yes           | Shipping calculation                             |
| `dw.ocapi.shop.basket.validateBasket` | SCAPI Basket, `onComplete`: Boolean (`true` if called on `/complete`)                                                       | Yes           | Add or remove flashes that drive checkout status |
| `dw.order.createOrderNo`              | —                                                                                                                           | Yes           | Custom order number; runs during complete        |

### Lifecycle Hooks: Create, Get, and Update

Extension point prefix: `sfcc.ucp.shopperCheckouts.v1.checkoutSessions`

| Operation | Hook                           | Transactional | Typical Use                                               |
| --------- | ------------------------------ | ------------- | --------------------------------------------------------- |
| Create    | `beforePOST(basket, request)`  | Yes           | Observe or adjust the basket before it is fully populated |
| Create    | `afterPOST(basket)`            | Yes           | Adjust the basket; the platform runs calculation here     |
| Create    | `modifyPOSTResponse(response)` | No            | Shape the response document only                          |
| Get       | `modifyGETResponse(response)`  | No            | Shape the response document only                          |
| Update    | `beforePUT(basket, request)`   | Yes           | Observe or adjust the basket before the replace           |
| Update    | `afterPUT(basket)`             | Yes           | Adjust the basket; the platform runs calculation here     |
| Update    | `modifyPUTResponse(response)`  | No            | Shape the response document only                          |

`basket` is a [Script Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.html). `request` and `response` are the UCP Checkout document.

### Cancel Hooks

Extension point prefix: `sfcc.ucp.shopperCheckouts.v1.checkoutSessions.cancel`

| Hook                           | Transactional | Typical Use                                             |
| ------------------------------ | ------------- | ------------------------------------------------------- |
| `afterPOST(checkoutSessionId)` | Yes           | React to the cancellation; the session is being deleted |
| `modifyPOSTResponse(response)` | No            | Shape the response document only                        |

### Complete Hooks

Extension point prefix: `sfcc.ucp.shopperCheckouts.v1.checkoutSessions.complete`

| Hook                           | Transactional | Typical Use                                                                                         |
| ------------------------------ | ------------- | --------------------------------------------------------------------------------------------------- |
| `beforePOST(basket, request)`  | Yes           | Final validation or basket adjustment before order creation                                         |
| `afterPOST(order)`             | Yes           | Post-placement work on the Order (for example DIY confirmation email). Doesn't roll back the order. |
| `modifyPOSTResponse(response)` | No            | Shape the response document only                                                                    |

`complete.afterPOST` receives a [Script Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.html). See [Post-Placement Actions](#post-placement-actions).

### Payment Hooks

Extension point prefix: `sfcc.app.ucp.payment`

`beforeOrderCreate` runs on every complete, including Salesforce Payments. `buildPaymentInstrumentRequest` and `authorize` apply to the third-party payment provider path. See [Third-Party Payment Providers](#third-party-payment-providers). Salesforce Payments–only hooks are under [If You Use Salesforce Payments](#if-you-use-salesforce-payments-default).

| Hook                                                                   | Transactional | Typical Use                                                                                   |
| ---------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------- |
| `beforeOrderCreate(basket)`                                            | Yes           | Last chance to adjust the basket after payment instruments are built and before `createOrder` |
| `buildPaymentInstrumentRequest(basket, selectedInstrument, requestWO)` | Yes           | Translate the selected instrument into a payment instrument request (DIY)                     |
| `authorize(order, paymentInstrument)`                                  | Yes           | Authorize payment with a third-party payment service provider (DIY)                           |

### Business Profile and Order Webhooks

| Hook                                                                              | Transactional | Typical Use                                                                             |
| --------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------- |
| `sfcc.ucp.shopperBusinessProfiles.v1.businessProfile.modifyGETResponse(response)` | No            | Replace `payment_handlers` on the well-known profile (DIY). Don't change `ucp.version`. |
| `sfcc.ucp.orderWebhook.v1.modifyEventPayload(payload)`                            | No            | Mutate the signed lifecycle payload immediately before delivery to the platform         |

If `modifyEventPayload` fails or returns a non-OK status, the webhook is retried. See [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md) for how post-processing events become those signed snapshots.

**note:** **Considerations for Business Profile `modifyGETResponse` Hook**

The Business Profile `modifyGETResponse` hook isn't guaranteed to run on every request. B2C Commerce caches the fully resolved, post-hook Business Profile by site and UCP version, and serves that cached copy until the TTL expires. The hook runs once when the cache entry is built, not once per incoming request.

Write `modifyGETResponse` as a pure function. Don't depend on per-request data such as headers or the calling agent. If the hook fails or returns a non-OK status, the result isn't cached, and a later request rebuilds the Business Profile and runs the hook again.

The default TTL for Business Profile cache entries is 10 minutes. This value is only modifiable by Salesforce Support.

## UCP Checkout Session Validation

By default, Checkout Session APIs perform basic validations for:

- Buyer email
- Line items
- Shipping address
- Shipping method

On checkout session complete, these additional validations run:

- Billing address
- Payment method

### Adding and Removing Validation Errors

Add, edit, or remove validation errors in `dw.ocapi.shop.basket.validateBasket`.

**note:** Use [UCP standard error codes](https://developers.google.com/merchant/ucp/guides/checkout/errorcode#error_code_reference) for the `type` field so error handling stays consistent across platforms.

```javascript
exports.validateBasket = function (basketResponse, duringSubmit) {
    // Add a validation error
    basketResponse.addFlash({
        type: "eligibility_invalid",
        message: Resource.msg('error.age.verification', 'checkout', null),
        path: "$"
    });

    // Remove a validation error
    var toRemove = [];
    for each (f in basketResponse.flashes) {
        if (f.type === "InvalidBillingAddress") {
            toRemove.push(f);
        }
    }
    for (var i = 0; i < toRemove.length; i++) {
        basketResponse.removeFlash(toRemove[i]);
    }
}
```

### Flash to Message Mapping

Salesforce automatically maps Flashes to UCP Messages:

| Flash Property  | UCP Message Property |
| --------------- | -------------------- |
| `flash.type`    | `message.code`       |
| `flash.path`    | `message.path`       |
| `flash.message` | `message.content`    |

These properties are always set automatically:

- `message.type` is always `ERROR`
- `message.severity` is always `RECOVERABLE`
- `message.contentType` is always `PLAIN`

### Checkout Status Derivation

If a Basket has one or more Flashes, `Checkout.status` is `INCOMPLETE`. Otherwise, the status is `READY_FOR_COMPLETE`.

To override the standard behavior of mapping Basket and Flashes to Checkout, use any of these hooks:

- `sfcc.ucp.shopperCheckouts.v1.checkoutSessions.modifyPOSTResponse`
- `sfcc.ucp.shopperCheckouts.v1.checkoutSessions.modifyGETResponse`
- `sfcc.ucp.shopperCheckouts.v1.checkoutSessions.modifyPUTResponse`
- `sfcc.ucp.shopperCheckouts.v1.checkoutSessions.cancel.modifyPOSTResponse`
- `sfcc.ucp.shopperCheckouts.v1.checkoutSessions.complete.modifyPOSTResponse`

### Example: Custom Address Verification

Add custom address verification by using a third-party service (Loqate) in `dw.ocapi.shop.basket.validateBasket`.

```javascript
// Hook: dw.ocapi.shop.basket.validateBasket
exports.validateBasket = function (basketResponse, duringSubmit) {
  // Validate shipping address with Loqate
  var address = basketResponse.shipments[0].shippingAddress;
  if (address) {
    var addressForm = {
      Address1: address.address1,
      Address2: address.address2,
      Country: address.countryCode,
      State: address.stateCode,
      City: address.city,
      PostalCode: address.postalCode,
    };
    var response = loqate.validateLoqateAddress(addressForm);
    if (response && response.response) {
      basketResponse.addFlash({
        type: "address_undeliverable",
        message: "Item(s) in your cart can't be shipped to the selected address",
        path: "$.shipments[0].shippingAddress",
      });
    }
  }
};
```

### Filtering Store Pickup Fulfillment Methods

Use the `modifyResponse` hooks to filter out store pickup fulfillment methods when the platform doesn't support store pickup.

**Example: Don't show store pickup fulfillment methods**

```javascript
// sfcc.ucp.shopperCheckouts.v1.checkoutSessions.modifyPOSTResponse
exports.modifyPOSTResponse = function( checkoutSession )
{
    var pickupMethodIds = {};
    for each( m in ShippingMgr.getAllShippingMethods() ) {
        if ( m.custom.ucpStorePickupEnabled === true )
        {
            pickupMethodIds[m.ID] = true;
        }
    }

    for each( method in checkoutSession.fulfillment.methods ) {
        for each( group in method.groups ) {
            var filtered = [];
            for each( option in group.options ) {
                if ( !pickupMethodIds[option.id] )
                {
                    filtered.push( option );
                }
            }
            group.options = filtered;
        }
    }
}
```

## Payment Configuration

A UCP checkout is paid with a single payment instrument. How you process that payment depends on your provider, and the two paths require different work:

- **If you use Salesforce Payments (the default),** the native SFP implementation handles payment for you. See [If You Use Salesforce Payments](#if-you-use-salesforce-payments-default).
- **If you use a third-party provider (DIY),** you register a small set of hooks that advertise your payment handlers and authorize payment with your own payment service provider (PSP). See [Third-Party Payment Providers](#third-party-payment-providers).

The **Payment Provider** setting selects which path applies. See [Payment Provider Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#payment-provider-setup).

### If You Use Salesforce Payments (Default)

The platform assembles the Google Pay / Salesforce Payments handler from Business Manager and authorizes payment for you. You don't register the DIY payment hooks. See [Payment Provider Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#payment-provider-setup).

Authorization starts in Transaction 2, but **placement is asynchronous** for both Salesforce Payments gateways: the order stays in `CREATED` until the webhook arrives. Don't treat a successful `/complete` response as a placed order.

- **Adyen via Salesforce Payments:** placement finishes when Adyen delivers its `AUTHORISATION` webhook.
- **Stripe via Salesforce Payments:** the PaymentIntent is confirmed during Transaction 2, but placement finishes when Stripe delivers `payment_intent.succeeded`.

Optional hooks on this path:

- `dw.extensions.payments.adyenNotification` — Adyen Salesforce Payments only; runs when the Adyen notification is processed.
- `dw.extensions.payments.stripePaymentEvent` — Stripe Salesforce Payments only; runs when the Stripe payment event is processed.
- `dw.extensions.payments.sendOrderConfirmationEmail` — Salesforce Payments (Adyen or Stripe); runs after the webhook places the order.

These hooks don't fire for third-party (DIY) payment.

**note:** **Sharing an Adyen merchant account**

If you use the same Adyen merchant account for both your storefront's own third-party Adyen integration and Salesforce Payments, you must filter webhook notifications so your storefront integration ignores UCP/SFP orders it didn't create. See [Adyen Webhook Filtering for Shared Merchant Accounts](#adyen-webhook-filtering-for-shared-merchant-accounts).

### Adyen Webhook Filtering for Shared Merchant Accounts

**Why:** The Adyen merchant account would have a webhook for both the third-party and SFP configurations. Adyen delivers payment notifications to all webhook endpoints on that account. The Salesforce Payments handler already ignores non-SFP orders; your storefront Adyen integration might not, and can try to process UCP/SFP notifications it didn't create.

**note:** The code snippets here are for a third-party integration using the Adyen-managed [adyen-salesforce-commerce-cloud cartridge](https://github.com/Adyen/adyen-salesforce-commerce-cloud). Your own implementation may vary, but the same principles apply.

#### Required Action

##### 1. Tag Your Third-Party Payments with Adyen Metadata

Where you build the Adyen payment request, add a metadata field. Adyen echoes this field back in webhook notifications.

**File location:** `cartridges/int_adyen_SFRA/cartridge/adyen/utils/adyenHelper.js` (example path for Adyen cartridge)

```javascript
createAdyenRequestObject(orderNo, orderToken, paymentInstrument, customerEmail) {
    // ...
    stateData.applicationInfo = adyenHelperObj.getApplicationInfo();
    stateData.additionalData = {};

    // Tag payments created by this cartridge so webhook notifications
    // can be identified. Adyen echoes this metadata back in webhook
    // additionalData as "metadata.<key>".
    stateData.metadata = {
        paymentSource: 'adyen-sfcc-cartridge'
    };

    return stateData;
}
```

##### 2. Filter on That Metadata Field in Your Webhook Handler

Where you receive webhook events in your third-party flow, check for the metadata tag before taking any action. If absent, return `[accepted]` without doing any processing.

```javascript
function notify(req, res, next) {
  // ...
  var source = req.form["additionalData.metadata.paymentSource"];
  if (source !== "adyen-sfcc-cartridge") {
    // This payment wasn't created from this cartridge
    // Return [accepted] and do no processing
    res.render("/notify");
    return next();
  }

  // This payment had our metadata => was created by this cartridge
  // Continue with typical webhook processing flow
  Transaction.begin();
  // ...
}
```

Using a metadata field as shown here is the simplest path forward, but alternative checks exist to determine if an order was initiated from third-party or SFP, such as checking the payment method of an order. Confirm this for your third-party implementation.

#### Deployment

1. Make the code changes in your local development environment
2. Test webhook filtering with both SFP and third-party payment scenarios
3. Upload the modified cartridge to your Commerce Cloud instance via Business Manager or command-line tools
4. Add the cartridge to your site's cartridge path if not already present
5. Verify webhook handling in both Staging and Production environments

### Third-Party Payment Providers

Register the hooks below to advertise payment handlers and authorize with your own PSP. Set **Payment Provider** to **Third Party Provider (DIY)** so the platform doesn't assemble the Salesforce Payments handler. See [Payment Provider Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#payment-provider-setup).

#### Third-Party Payment Hooks

Register these three hooks. Signatures are in [Extension Hooks Reference](#extension-hooks-reference).

- `sfcc.ucp.shopperBusinessProfiles.v1.businessProfile.modifyGETResponse` — advertise payment handlers on the well-known profile
- `sfcc.app.ucp.payment.buildPaymentInstrumentRequest` — translate the selected instrument (including its `handler_id`) into a payment instrument request
- `sfcc.app.ucp.payment.authorize` — authorize with your PSP. Fires only for a third-party instrument; Salesforce Payments bypasses this hook.

#### Advertising Payment Handlers

Register `sfcc.ucp.shopperBusinessProfiles.v1.businessProfile.modifyGETResponse` to replace the payment handlers on the well-known profile. See [Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#business-profile). The hook argument exposes `ucp` and `signingKeys`. Assign handlers on `ucp.paymentHandlers`. Don't change `ucp.version` or `signingKeys`.

Copy the handler **namespace** (the map key, for example `com.google.pay`) and the handler **`id`** from the payment handler's author — usually the PSP or the platform. That `id` is what comes back on `/complete` as `handler_id`. The rest of the handler object (`config` and related fields) is also defined by that author. Consult the handler's official documentation.

```javascript
// sfcc.ucp.shopperBusinessProfiles.v1.businessProfile.modifyGETResponse
var Status = require("dw/system/Status");

exports.modifyGETResponse = function (businessProfile) {
  businessProfile.ucp.paymentHandlers = {
    "com.google.pay": [
      {
        id: "...", // exact id from the handler author; do not invent one
        config: {
          /* see the handler author's spec */
        },
      },
    ],
  };
  return new Status(Status.OK);
};
```

The checkout mapper reads payment handlers from the business profile, so the handlers you assign here appear in the checkout session response without a separate hook.

#### Authorizing Payment

Register `sfcc.app.ucp.payment.authorize` to authorize the payment instrument with your PSP. The hook receives the `Order` and the `OrderPaymentInstrument`, and returns a `Status`: return `Status.OK` when authorization succeeds, or `Status.ERROR` to fail the order. Read any PSP tokens or handler data from the payment instrument's custom attributes (set earlier by your `buildPaymentInstrumentRequest` hook).

If you already have PSP authorization logic elsewhere, bridge to it from this hook rather than duplicating it:

- **SFRA merchants** call their existing `app.payment.processor.<METHOD>.Authorize` script.
- **Pipeline merchants** call their private `Authorize` start-node.
- **Merchants with an existing `dw.order.payment.authorize` script** delegate to it directly — the signature is the same `(Order, OrderPaymentInstrument)`.

**note:** **No storefront browser in UCP**

UCP checkout runs headless and server-side. There is no merchant-controlled browser, so any PSP logic that assumes client-side setup happened first (for example, a payment intent created in the shopper's browser) must be adapted to complete the full PSP interaction server-side inside the `authorize` hook.

#### Order Placement

Order placement is **synchronous** — it happens inside the `/complete` request. The platform places the order when both of these are true:

- Your `sfcc.app.ucp.payment.authorize` hook returns `Status.OK`.
- The order's _authorized_ amount covers its total.

At the start of `/complete`, the platform creates the order in `CREATED` status and runs your `authorize` hook. **Leave the payment transaction in its created state:** when the hook returns `Status.OK`, the platform promotes the transaction to _authorized_ and places the order for you. (You can set the transaction to _authorized_ yourself if you prefer, but it isn't required.)

If `authorize` returns `Status.ERROR` or throws, the platform fails the order, reopens the basket, and returns an error so the shopper can retry.

**note:** **Don't set the payment transaction to _captured_**

Placement requires the order's _authorized_ amount to cover its total, and a _captured_ transaction doesn't count toward that amount. So if your `authorize` hook captures the payment, the order is never placed — it stays in `CREATED` and is later failed by the `AutoFailOrders` job. Authorize during `/complete`; capture later (for example, at fulfillment).

#### Post-Placement Actions

A browser-based checkout finishes an order in the storefront controller — sending the confirmation email, exporting to an OMS, and so on. UCP checkout is headless, so that controller never runs. How you replace that work depends on the payment path:

- **Salesforce Payments:** use `dw.extensions.payments.sendOrderConfirmationEmail`, which runs after the gateway webhook places the order. Don't send the email from `complete.afterPOST` — the order is still `CREATED`. See [If You Use Salesforce Payments](#if-you-use-salesforce-payments-default).
- **Third-party (DIY):** `complete.afterPOST` receives the Order after `/complete` has placed it. Send the confirmation email there. Send only if the order is already placed (not `CREATED`). Don't return `ERROR` if the email send fails; log it, leave `confirmationStatus` unconfirmed, and let a job retry. A hook failure doesn't un-place the order, but it can still fail the `/complete` response. See [Transaction Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-transaction-management.md#the-complete-transaction-model).

**Recommendation:** whether or not you send the email in `complete.afterPOST`, run a scheduled job as a backstop for the email and for OMS export. Use the order's status attributes as an idempotent work queue — `confirmationStatus` for the email and `exportStatus` for OMS export. Guard each action by its own flag and commit each in its own transaction, so a failure in one action neither undoes the other nor re-fires it on the next run.

```javascript
// Custom job step: run post-placement actions for newly placed orders.
var OrderMgr = require("dw/order/OrderMgr");
var Order = require("dw/order/Order");
var Transaction = require("dw/system/Transaction");

exports.processPlacedOrders = function () {
  OrderMgr.processOrders(
    function (order) {
      if (order.confirmationStatus === Order.CONFIRMATION_STATUS_NOTCONFIRMED) {
        // Send the email server-side (for example, dw.net.Mail or a helper),
        // then mark the order confirmed so later runs skip it.
        Transaction.wrap(function () {
          order.setConfirmationStatus(Order.CONFIRMATION_STATUS_CONFIRMED);
        });
      }
      if (order.exportStatus === Order.EXPORT_STATUS_NOTEXPORTED) {
        // Export the order to your OMS, then mark it exported.
        Transaction.wrap(function () {
          order.setExportStatus(Order.EXPORT_STATUS_EXPORTED);
        });
      }
    },
    "status = {0} AND (confirmationStatus = {1} OR exportStatus = {2})",
    Order.ORDER_STATUS_OPEN,
    Order.CONFIRMATION_STATUS_NOTCONFIRMED,
    Order.EXPORT_STATUS_NOTEXPORTED,
  );
};
```

**note:** **Splitting into separate jobs**

Run the confirmation email and OMS export as two separate jobs instead if you prefer. If they run concurrently, be aware that B2C Commerce guards each order at the object level, not the field level: when both jobs touch the same order at the same moment, one transaction fails with a stale-data error even though they write different fields. Because the status flags make each update idempotent, the loser simply retries on its next run — or stagger the two schedules so they don't overlap. A single job doing all post-placement work avoids the contention entirely.

<!-- document id=972de1eb04cfa777fbab9ddf365df313131f2711345c4df7c4556e8bf34f89e0 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-personas.md -->

# Implementation Lifecycle: Personas

In Salesforce Commerce, implementation is a division of labor based on persona skill sets. The Commerce implementation lifecycle relies on three personas: a developer, an org admin, and a store admin.

Ideally, each persona within the implementation lifecycle has a specialty and completes only certain tasks.

![Integration lifecycle diagram](https://developer.salesforce.com/media/d2c-commerce/integration_lifecycle.png)

## Developer Tasks

Use standard Apex development tools to implement B2B Buyer Experience APIs. Create custom Lightning Web Components to embed payment, product recommendation, and other APIs. Implement or extend the global interfaces included in the Buyer Experience SDK. Create packages and deploy to your org.

## Org and Store Admin Tasks

After your developer creates Apex implementations and packages them, deploy them into your Salesforce org. Configure the standard Salesforce integrations so that they can execute properly.

<!-- document id=9591fe4013794367361b9be40def1e6ff49d29945b40d7b0360325d4dd9fff33 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-import-tokens-overview.md -->

# Import Existing Tokenized Payment Methods into Salesforce

Use this process to import and use your customers’ existing tokenized payment details in Salesforce. When you create Saved Payment Method (SPM) records, these tokens become available for transactions initiated directly from your Salesforce org.

This scenario is ideal for customers you're onboarding who have already tokenized their bank accounts or credit cards outside Salesforce using a payment gateway, including Salesforce native or third-party payment gateways. By mapping the existing tokens and related details to SPM records, Salesforce creates a unique Saved Payment Method ID for each imported record. This makes the payment method ready for future transactions.

There are some important considerations to keep in mind when you use this approach:

- The SavedPaymentMethod object is available as a standard sObject resource, allowing you to create and delete SPM records.
- The SavedPaymentMethod object is customizable. A Salesforce Admin can add custom fields for capturing additional payment gateway details not supported by the standard fields.

## Prerequisites

Before you begin, make sure your Salesforce organization and the user performing the operation meet these requirements:

- Read-write access to the SavedPaymentMethod object.
- Salesforce Payments license and ManageMySavedPaymentMethods user permission.
- ManageSavedPaymentMethods user permission and Revenue Cloud license.

<!-- document id=5bf0f71bddc05c62bd6dfba2650bae3ee1b9d0dd19a8d08db8db9716629f00eb url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/create-a-sitemap.md -->

# Improve SEO with a Sitemap

Sitemaps provide search crawlers with instructions on the pages to index and the site hierarchy, which can improve your SEO rankings. Submitting a sitemap to tools such as Google Search Console can also help identify broken links or duplicate content. B2C Commerce includes sitemap management features for:

- [Storefront Reference Architecture (SFRA)](https://developer.salesforce.com/docs/commerce/sfra/guide/sfra-overview.html) and SiteGenesis (SG) ecommerce sites
- Headless ecommerce applications like those built on [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide)

This guide explains how to create and upload a sitemap for a headless site built on B2C Commerce.

## Supported Implementations

You can use the sitemap feature for headless sites if you built your site on B2C Commerce with any of these storefront implementations:

- Composable Storefront (PWA Kit) for your whole site
- A [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md) (SG/SFRA and PWA Kit)
- Your own bespoke headless implementation

**note:** Unless otherwise stated, the steps in this guide apply to all three implementations.

**tip:** - If your routes are configured in Business Manager, create a sitemap in Business Manager. See [Create a Sitemap](#create-a-sitemap).
- If your routes aren’t configured in Business Manager, create a sitemap or supplement your existing sitemap by using this API endpoint: [uploadCustomSitemapAndTriggerSitemapGeneration](https://developer.salesforce.com/docs/commerce/commerce-api/references/seo?meta=uploadCustomSitemapAndTriggerSitemapGeneration).

## Create a Sitemap

1. If you haven’t done so already, set up a vanity domain in embedded CDN (eCDN).

**note:** If you’re not routing your site traffic directly to eCDN, create a subdomain such as `seo.example.com` to serve your sitemap. Replace `example.com` with your vanity domain name.

2. In Business Manager (BM), [configure a hostname alias](https://help.salesforce.com/s/articleView?id=cc.b2c_configuring_hostname_alias.htm&type=5) for your site that matches your vanity domain.
3. In BM, [generate a sitemap](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_sitemaps.htm&type=5). You can find your sitemap at `example.com/sitemap_index.xml`. Replace “example.com” with your vanity domain name.
4. Update your existing `robots.txt` file in your PWA Kit or headless site with `example.com/sitemap_index.xml`.
5. If you have a hybrid storefront project (SFRA and PWA Kit) then also:
   - [Generate a robots.txt file](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_a_robots_txt_file.htm&type=5).
   - [Verify the robots.txt file](https://help.salesforce.com/s/articleView?id=cc.b2c_verifying_the_robots_txt_location.htm&type=5).
6. [Notify search engines about your B2C Commerce sitemap](https://help.salesforce.com/s/articleView?id=cc.b2c_notifying_search_engines_about_your_sitemap.htm&type=5).

## Upload Your Sitemap to Your Domain's Root

Improve your site's visibility, user experience, and efficiency by uploading your site map to your domain's root. In your PWA Kit project:

1. In [`ssr.template-retail-react-app/app/ssr.js`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/9d645adfcec3a36f7d8aa410a669c150f57aca14/packages/template-retail-react-app/app/ssr.js#L109), add a path to your sitemap. For example:

   `app.get('/sitemap_index.xml', runtime.serveStaticFile('static/sitemap_index.xml'))`

2. Update the `ssrShared` property in [`template-retail-react-app/config/default.js`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/config/default.js#L45-L50) so that your sitemap is available to the server-side rendering system. For example:

```jsx
   ssrShared:[
   'static/sitemap_index.xml'..]
```

3. [Deploy your bundle](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) to your chosen environment.
4. Confirm that your sitemap is available in your domain's root. In this example, replace `test-env.example.com` with the path that applies to your deployed environment:

   `test-env.example.com/sitemap_index.xml`

## Best Practices

- Make sure that your sitemap incorporates all the crucial pages that you want search engines to find and index. This includes product listing pages, product detail pages, blog posts, and other relevant content.
- If your sitemap becomes very large, consider using priority settings in BM. You can use these settings to indicate which pages are most important for search engines to crawl first. See [Generate Sitemaps in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_sitemaps.htm&type=5).
- Schedule a job to update the sitemap regularly so that search engines are aware of these changes and can index them promptly. See [Generate Sitemaps in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_sitemaps.htm&type=5).
- Review and update any crawl directives in the `robots.txt `file to ensure that they align with your SEO strategy and don’t block important parts of the site.
- Regularly test the accessibility of the sitemap URL to ensure that search engines and users can reach it without any issues.

## Troubleshoot Sitemaps

This section provides suggested solutions for a few common errors that you can encounter while using sitemaps.

### Incorrect URL Structure in the Sitemap

**Potential Cause:** Syntax errors or other errors in your sitemap.

**Suggested Solution:** Ensure that all URLs in the sitemap are absolute and correctly formatted. Use the correct protocol (http or https) and don’t include session IDs or other dynamic parameters. See [Generate Sitemaps in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_sitemaps.htm&type=5).

### Sitemap URLs Return Errors (404, 500)

**Potential Cause:** Inaccurate URLs in your sitemap.

**Suggested Solution:** Regularly check the URLs in your sitemap to ensure that they’re accessible and don't return errors. Fix any broken links or server issues. See [Generate Sitemaps in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_sitemaps.htm&type=5).

### Search Engines Unable to Read the robots.txt File

**Potential Cause:** Blocking directives errors or other issues in your `robots.txt` file.

**Suggested Solution:** Test the robots.txt file by using a robots.txt tester. Ensure that there are no blocking directives that prevent search engines from accessing important pages or the sitemap itself. See [Generate a Robots.txt File with Business Manage for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_generating_a_robots_txt_file.htm&type=5).

## See Also

- [SEO API](https://developer.salesforce.com/docs/commerce/commerce-api/references/seo?meta=uploadCustomSitemapAndTriggerSitemapGeneration)
- [Sitemaps in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_sitemap_overview.htm&language=en_US&type=5)
- [Robots.txt Files for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_using_the_robots_txt_file_to_prevent_crawling_of_development_and_staging_instances.htm&type=5)
- [URL Resolution](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-resolution.html)
- [SEO for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_seo_overview.htm&language=en_US&type=5)

<!-- document id=7b33d24cd24ba7b09213c739e3edf1e2509c508640dc96da44a10c566c6520ce url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-install-extension.md -->

# Install and Launch the Commerce Vibes Extension

Install Agentforce Commerce Vibes extension in Visual Studio Code and log in to your Salesforce org.

## Prerequisites

- Visual Studio Code version 1.101.0 or later
- Salesforce B2C Commerce account
- Node.js version 22.15.1 or later
- (Optional) `dw.json` in your workspace root to run the B2C CLI

## Installation Steps

Install the Agentforce Commerce Vibes extension and its dependencies.

1. Open Visual Studio Code.
2. Install the Agentforce Commerce Vibes extension from the VS Code Marketplace.

   a. Click the extensions icon in the Activity Bar, on the left navigation pane, and search for "Agentforce Commerce Vibes".

   b. On the extension's page, click **Install** to install the extension. For more information, see [Use extensions in Visual Studio Code](https://code.visualstudio.com/docs/configure/extensions/extensions) in the Visual Studio Code documentation.

3. Launch the Commerce Vibes extension by clicking the ![Commerce Vibes icon](https://developer.salesforce.com/docs/media/commerce-vibes/cv-com-vibes-icon.png '{"class": "image-icon-sm"}') icon in the Activity Bar.
4. Click the checklist icon on the top right corner of the Agentforce Commerce Vibes panel.
5. In the checklist panel, click **B2C Commerce CLI** to install the B2C CLI to run CLI commands locally.

   This action runs the `npm install -g @salesforce/b2c-cli` command. If you have an earlier version of the B2C CLI, it is updated. The output of the command displays in the Terminal panel. After the installation completes, the status of the **B2C Commerce CLI** dependency is refreshed in the checklist panel.

6. Click **B2C Commerce Extension** to install the Salesforce B2C Commerce extension from the VS Code Marketplace, which is a dependency of Commerce Vibes.

   For more information about the B2C CLI and extension, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md). After the installation completes, the status of the **B2C Commerce Extension** dependency is refreshed in the checklist panel. The B2C Commerce project isn't marked as ready if you haven't created a B2C project yet. For Commerce Org Connection, you enable it in the next step when logging into Salesforce.

   ![Checklist panel shows the status of installed extensions and CLI](https://developer.salesforce.com/docs/media/commerce-vibes/cv-checklist.png '{"class": "image-xl"}')

**note:** The extensions can be disabled if the opened folder in VS Code is untrusted. Make sure you add the folder as a trusted folder in VS Code. See [Workspace Trust](https://code.visualstudio.com/docs/editing/workspaces/workspace-trust) in the Visual Studio Code documentation.

## Launch Commerce Vibes and Log in

After installing the Commerce Vibes extension, launch it to log into your Salesforce org.

1. If you haven't already done so, launch the extension by clicking the Commerce Vibes icon ![Commerce Vibes icon](https://developer.salesforce.com/docs/media/commerce-vibes/cv-com-vibes-icon.png '{"class": "image-icon-sm"}') in the Activity Bar.
2. In the Agentforce Commerce Vibes panel, click the checklist icon in the top right corner.
   A checklist appears showing the status of the prerequisite items.
3. Click the **Commerce Org Connection** step to open the login dialog.
4. Provide the org instance URL.
   The instance URL can be the default login URL, My Domain or custom domain URL, or a sandbox instance.
   The extension opens a terminal to run the Salesforce CLI login command. After authenticating in your browser, click **Check Status** to validate the connection. Examples of org URLs:
   - Production: `login.salesforce.com` or `mycompany.my.salesforce.com`
   - Sandbox: `mycompany--sandbox1.sandbox.my.salesforce.com`
5. Provide the username and password.

### Optional: Log in with the Salesforce CLI

Instead of logging in through the login dialog in VS Code, run the Salesforce CLI command directly in your terminal. See [Install Salesforce CLI](https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_setup_install_cli.htm) in the _Salesforce CLI Setup Guide_.

- For production orgs using default login URL:

  ```bash
  sf org login web --set-default
  ```

- For any other org (sandbox, My Domain, or a custom domain). Replace `<your-org-url>` with the full URL you use to log into Salesforce (for example, `mycompany--dev.sandbox.my.salesforce.com`).

  ```bash
  sf org login web --instance-url https://<your-org-url> --set-default
  ```

## Optional: Configure B2C Commerce Credentials

Administration tasks need credentials for your B2C Commerce instance. A project `dw.json` file is one option; the B2C CLI and MCP also support global configuration and environment variables. For more information about the `dw.json` file content, see [Configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html#configuration-file) in the _Agentic B2C Developer Toolkit_.

1. Create a `dw.json` at your project root folder.
   ```
   {
      "hostname": "abcd-123.dx.commercecloud.salesforce.com",
      "code-version": "<version>",
      "client-id": "<client-id-value>",
      "client-secret": "<client-secret-value>",
      "username": "<your-username>",
      "password": "<your-access-key>"
   }
   ```
2. To provide the `client-id` and `client-secret`, see [Add an API Client in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5).
3. To access the code version in B2C Commerce, go to **Administration > Site Development > Code Deployment**.
4. For WebDav authentication, which is used only for code deployments and file operations, provide a username and password. For the password, use the access key. See [Create an Access Key for Logins for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_access_keys_for_business_manager.htm&type=5) in _Salesforce Help_.
5. To add an OCAPI data permission, go to **Administration > Site Development > Open Commerce API Settings**, add specific permission for the Account Manager client ID. For example, to run B2C jobs, add the value for the client ID: `"resource_id": "/jobs/*/executions"`.

## See Also

- [Get Started with Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cv-build-storefront-next-project.md)

<!-- document id=76994d6078b5bcd4ddc9e342030c8049c276c4ef40dcf63228a58baa1bf69ac6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/install-the-commerce-client.md -->

# Install the Agentforce Commerce Client

Install the Agentforce Commerce Client one of two ways: as a `<script>` tag that loads a UMD bundle from the CDN, or as the `@cimulate/copilot-widget` npm package in a React application.

**note:** On an SFRA storefront, don't embed the client with a `<script>` tag. Install the `plugin_commerce_client` cartridge and configure the widget from Business Manager instead. See [Install the Agentforce Commerce Client on SFRA](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-sfra.md).

On a PWA Kit storefront, don't embed the client with a `<script>` tag either. You enable it through the `COMMERCE_AGENT_SETTINGS` Managed Runtime environment variable. See [Install the Agentforce Commerce Client on PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-pwa-kit.md).

## CDN install

The CDN approach is a drop-in integration for any storefront. Load the bundle, add a container element, and call the injection function.

The bundle URL follows this pattern:

```
https://cdn.search.cimulate.ai/copilot-widget/<version>/messaging.umd.js
```

Pin `<version>` to a specific release (for example, `1.30.0`) so a future release can't change your storefront's behavior without an explicit upgrade. The bundle also ships a matching CSS file at the same path with a `.css` extension. The `messaging.umd.js` bundle exposes the global `window.CimulateMessaging`.

```html
<div id="messaging-widget"></div>
<script src="https://cdn.search.cimulate.ai/copilot-widget/1.30.0/messaging.umd.js"></script>
<script>
  CimulateMessaging.injectMessagingWidget({
    elementId: "messaging-widget",
    messagingConfig: {
      scrt2Url: "https://your-org.my.salesforce-scrt.com",
      orgId: "00Dxx0000000000",
      esDeveloperName: "Your_Messaging_Channel",
    },
  });
</script>
```

`injectMessagingWidget` requires `messagingConfig` with `scrt2Url`, `orgId`, and `esDeveloperName`. If `messagingConfig` is missing, or any of those three fields is missing, the widget logs an error and does not render.

**Container timing**

Both injection functions take an `elementId` that names the container element to render into. If the element already exists when you call the function, the widget renders immediately. If it doesn't exist yet, the widget starts a `MutationObserver` and renders as soon as the element appears, or logs an error after a timeout (5000 ms by default; override with the `timeout` option). This design supports injecting the widget on storefronts where the container is added asynchronously, such as single-page apps and dynamic page builders.

## npm install

For a React application, install the package and import the component and injection helpers for your mode.

```sh
npm install @cimulate/copilot-widget
```

The package requires React 18 (`react` and `react-dom` at `~18.3.1`) as peer dependencies.

import { AgentForceWidget } from "@cimulate/copilot-widget/messaging";

<AgentForceWidget
  messagingConfig={{
    scrt2Url: "https://your-org.my.salesforce-scrt.com",
    orgId: "00Dxx0000000000",
    esDeveloperName: "Your_Messaging_Channel",
  }}
/>;
```

**Import the styles**

Import the widget stylesheet:

```ts
import "@cimulate/copilot-widget/css/messaging";
```

## Pin and track versions

`@cimulate/copilot-widget` follows semantic versioning. Each released version is published on merge and recorded in the package's changelog, newest first. Before you upgrade a pinned version, review the changelog for the releases between your current version and the target so you can account for fixes and additive changes. Both the CDN URL and the npm version range are places to pin a known-good version.

The changelog is public, so you can check what's supported in a release before you upgrade:

1. Open the [`@cimulate/copilot-widget` package page](https://www.npmjs.com/package/@cimulate/copilot-widget) on npm.
2. Select the **Code** tab.
3. Open `changelog.md` in the file list to see what changed, was added, or was fixed in each version.

## Related resources

- [Agentforce Commerce Client Overview](agentforce-commerce-client-overview.md)
- [Install the Agentforce Commerce Client on SFRA](install-on-sfra.md)
- [Install the Agentforce Commerce Client on PWA Kit](install-on-pwa-kit.md)
- [Configure the Agentforce Commerce Client](configure-the-commerce-client.md)
- [Component Override SDK](component-override-sdk.md)

<!-- document id=a3c6200addd3754101b9b26e64f8acb58d4c41203718db335738d08ebd6fdeef url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/install-on-pwa-kit.md -->

# Install the Agentforce Commerce Client on PWA Kit

On a PWA Kit (Composable Storefront) project, you don't embed the client with a hand-written `<script>` tag. You enable and configure it through a single Managed Runtime environment variable, `COMMERCE_AGENT_SETTINGS`. The retail-react-app template reads that variable, selects the Commerce Client provider, and injects the widget for you.

This topic covers enabling the client, the configuration shape, and the developer code path for component overrides. For the override contract itself (slots, payloads, and the API), see [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md).

## Enable the client

Set the `COMMERCE_AGENT_SETTINGS` environment variable on your Managed Runtime environment.

1. Open Runtime Admin (`https://runtime.commercecloud.com/`).
2. Select your project, then the environment.
3. Under **Environment Variables**, add `COMMERCE_AGENT_SETTINGS` with a JSON value.

`COMMERCE_AGENT_SETTINGS` replaces the entire agent configuration object, so include every setting the storefront needs, not just the keys you're changing.

A minimal working configuration selects the Commerce Client provider and sets the three connection fields:

```json
{
  "enabled": "true",
  "provider": "commerce-client",
  "salesforceOrgId": "00DXXXXXXXXXXXXXXX",
  "scrt2Url": "https://your-org.my.salesforce-scrt.com",
  "cc_esDeveloperName": "YOUR_EMBEDDED_SERVICE_DEVELOPER_NAME",
  "cc_cdnVersion": "1.30.0"
}
```

- `provider` must be `commerce-client` to load this widget.
- `salesforceOrgId`, `scrt2Url`, and `cc_esDeveloperName` are the same connection values you get from the Agentforce messaging channel's connection snippet.
- `cc_cdnVersion` pins the widget release loaded from the CDN. This guide documents version `1.30.0`.

The same object accepts the appearance and behavior keys (`cc_headerText`, `cc_disclaimerMarkdown`, `cc_theme`, `cc_searchConfig`, `cc_widgetPosition`, `cc_enableEscalationToAgent`, `cc_enableDownloadTranscript`, and so on). These map to the configuration surface in [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md) and [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md).

**note:** Streaming of agent responses requires a capabilities version of `65` or higher. On PWA Kit this defaults to `65`, so you don't need to set `cc_capabilitiesVersion` explicitly.

## Deploy

From the template project (`packages/template-retail-react-app`), push a bundle to Managed Runtime:

```sh
npm run push -- --projectSlug <project-slug>
```

To push and deploy to a specific target environment, add `--target` and `--wait`:

```sh
npm run push -- --projectSlug <project-slug> --target production --wait
```

## Roll back with config alone

Because the widget is driven entirely by `COMMERCE_AGENT_SETTINGS`, disable or revert it without a redeploy:

| Action | Change |
| --- | --- |
| Disable the widget | Set `"enabled": "false"`. |
| Revert to a prior widget release | Set `cc_cdnVersion` to the previous version. |

## Component overrides on PWA Kit

Use component overrides to replace the widget's built-in product and agent-action rendering with your own custom elements. On PWA Kit, you supply them one of two mutually exclusive ways, both through `COMMERCE_AGENT_SETTINGS`:

| Route | Key | What It Holds |
| --- | --- | --- |
| Inline map | `cc_overrides` | An object mapping override keys to custom-element tag names. |
| Hosted script | `cc_overridesUrl` | An HTTPS URL to a script that defines the elements and assigns `window.CimulateOverrides`. |

Overrides require `provider: "commerce-client"` and `cc_cdnVersion` of `1.30.0` (any release that supports the slots you use).

**note:** The widget's own precedence resolves `overridesUrl` before an inline map. The PWA Kit template inverts this: if you set both `cc_overrides` and `cc_overridesUrl`, it forwards `cc_overrides` and drops the URL with a console warning. Set only one.

### Inline map route

Register the custom element in the browser entry point, then reference its tag name from `cc_overrides`. Registration has to happen in the browser, because `customElements` doesn't exist during server-side rendering.

Author the custom element:

```js
// app/components/shopper-agent/overrides/product-tile-element.js
import { OverrideElement } from "@cimulate/copilot-widget/messaging";

class ProductTileElement extends OverrideElement {
  render() {
    const { payload, api } = this.props || {};
    // Build your DOM here. Escape every agent-supplied value.
  }
}

export function registerProductTile() {
  if (!customElements.get("cx-product-tile")) {
    customElements.define("cx-product-tile", ProductTileElement);
  }
}
```

Call the registration from the browser entry point:

```js
// app/main.jsx
import { registerProductTile } from "./components/shopper-agent/overrides/product-tile-element";

registerProductTile();
```

Then map the override key to the tag name in `COMMERCE_AGENT_SETTINGS`:

```json
{
  "enabled": "true",
  "provider": "commerce-client",
  "cc_cdnVersion": "1.30.0",
  "cc_overrides": {
    "ProductTile": "cx-product-tile"
  }
}
```

### Hosted script route

Host a script on HTTPS that defines your elements and assigns `window.CimulateOverrides`, then point `cc_overridesUrl` at it:

```json
{
  "enabled": "true",
  "provider": "commerce-client",
  "cc_cdnVersion": "1.30.0",
  "cc_overridesUrl": "https://cdn.example.com/commerce-client/overrides.js"
}
```

### Content Security Policy

The template's `app/ssr.js` builds the `script-src` allowlist. It already includes the Cimulate origin, and it adds the origin of a valid `cc_overridesUrl` automatically through the `getCommerceClientOverridesCspSources` helper, so a hosted override script from an allowed origin loads without a manual CSP edit. Confirm these directives permit the widget:

| Directive | Value |
| --- | --- |
| `script-src` | `https://*.cimulate.ai` (plus your `cc_overridesUrl` origin) |
| `connect-src` | `https://*.cimulate.ai` |

## Related resources

- [Agentforce Commerce Client Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/agentforce-commerce-client-overview.md)
- [Install the Agentforce Commerce Client on SFRA](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-on-sfra.md)
- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md)

<!-- document id=7d718a072d220b24198d24f187aa83ee160064fa6030a300726103746ba37f17 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/install-on-sfra.md -->

# Install the Agentforce Commerce Client on SFRA

On a Storefront Reference Architecture (SFRA) storefront, you don't embed the client with a hand-written `<script>` tag. You install the `plugin_commerce_client` cartridge, which renders the widget on every storefront page and reads its configuration from a single Business Manager Site Preference. Merchants can then enable, disable, and customize the widget without a code deploy.

`plugin_commerce_client` is the only cartridge you need. Earlier setups paired it with a separate `plugin_shopper_agent` cartridge; that cartridge is no longer required and must not appear in the site cartridge path.

The cartridge supports two ways to load the widget bundle: from the CDN (the default and most common path) or from static assets bundled into the cartridge. Both are covered below.

## Prerequisites

- Business Manager access with permissions to edit cartridge paths (**Administration > Sites**), import site metadata (**Administration > Site Development**), and edit Site Preferences (**Merchant Tools > Custom Preferences**).
- The server-side Agentforce setup complete, so you have the SCRT2 URL, Organization ID, and Embedded Service developer name from the messaging channel's connection snippet.
- Node.js 18 or later.
- A WebDAV access key (**Administration > Organization > WebDAV Client Permissions**).

## Get access to the cartridge repository

The cartridge source is in the [`plugin_commerce_client`](https://github.com/SalesforceCommerceCloud/plugin_commerce_client) repository in the `SalesforceCommerceCloud` GitHub organization. Access is self-service: any developer with Commerce Cloud Account Manager credentials can join the organization and reach the repository without a manual access request.

Before you request access, set up your GitHub account:

- Enable non-SMS two-factor authentication (2FA) on your GitHub account, using an authenticator app (TOTP), a passkey, or a hardware security key. SMS-based 2FA isn't accepted by the organization's policy and causes silent access failures.
- Have your Commerce Cloud Account Manager credentials ready. These are the same credentials you use for other SFRA plugin repositories.

Then follow the [B2C Commerce repository access guide](https://trailhead.salesforce.com/content/learn/modules/b2c-developer-resources-and-tools/b2c-developer-access-repositories) on Trailhead. After you join the `SalesforceCommerceCloud` organization, you're automatically added to the Community team, which includes `plugin_commerce_client`. If access doesn't work, confirm that you removed SMS as a 2FA method on your GitHub account.

## Install the cartridge

Clone and build the cartridge:

```sh
git clone https://github.com/SalesforceCommerceCloud/plugin_commerce_client.git
cd plugin_commerce_client
npm install
```

Create a `dw.json` file in the project root:

```json
{
  "hostname": "your-instance.dx.commercecloud.salesforce.com",
  "username": "your-email@example.com",
  "password": "your-webdav-access-key",
  "code-version": "version1"
}
```

Use your WebDAV access key as the password, not your Business Manager login. The `hostname` takes no protocol prefix or trailing slash, and `code-version` must match the active code version on the instance. Then upload the cartridge:

```sh
npm run uploadCartridge
```

## Add the cartridge to the site path

Go to **Administration > Sites > Manage Sites > [your site] > Settings** and add `plugin_commerce_client` to the front of the **Cartridges** field, before the base cartridge:

```
plugin_commerce_client:app_storefront_base
```

B2C Commerce resolves templates left to right, so `plugin_commerce_client` has to precede `app_storefront_base` for its page overlay to take effect. If your site path includes other cartridges, keep `plugin_commerce_client` ahead of the base cartridge in the list.

## Import the site metadata

The cartridge ships a site-import archive that creates the Commerce Client preference group and its custom preferences. Without this import, the widget's preferences don't exist and the cartridge can't read its configuration.

Generate the archive:

```sh
npm run siteimport:zip
```

Then import it in Business Manager:

1. Go to **Administration > Site Development > Site Import & Export**.
2. Upload the generated `site_import_commerce_client.zip`.
3. Select the uploaded file, and then select **Import**.

## Configure the widget

The cartridge reads its entire configuration from one JSON Site Preference, **Commerce Client Configuration (JSON)** (`cc_config`). Go to **Merchant Tools > Site Preferences > Custom Preferences > Commerce Client** and set `cc_config` to a JSON object.

A minimal production configuration sets the three connection fields, enables the widget, and passes the routing attributes the agent needs:

```json
{
  "cc_scrt2Url": "https://your-org.my.salesforce-scrt.com",
  "cc_orgId": "00DXXXXXXXXXXXXXXX",
  "cc_esDeveloperName": "YOUR_EMBEDDED_SERVICE_DEVELOPER_NAME",
  "cc_enabled": true,
  "cc_routingAttributes": {
    "isCartMgmtSupported": "true"
  }
}
```

The three connection fields come from your Agentforce messaging channel: `cc_scrt2Url` is the SCRT2 messaging endpoint, `cc_orgId` is the 18-character ID of the Salesforce org that hosts your Agentforce agent, and `cc_esDeveloperName` is the Embedded Service messaging channel developer name. `cc_scrt2Url`, `cc_orgId`, and `cc_esDeveloperName` are required; the widget doesn't render without all three.

The same object accepts optional appearance and behavior keys, including `cc_widgetPosition` (`bottom-left` or `bottom-right`), `cc_isOpen`, `cc_showFab`, `cc_isDevelopment`, `cc_headerText`, `cc_disclaimerMarkdown`, and the nested `cc_theme` and `cc_searchConfig` objects. These map to the same configuration surface described in [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md) and [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md). Omit a key to keep the cartridge default.

A few rules keep the JSON valid:

- Booleans must be real JSON booleans (`true`, not `"true"`), except `isCartMgmtSupported`, which is intentionally the string `"true"`.
- `cc_widgetPosition` must be `bottom-left` or `bottom-right`, and `cc_loadingMode` must be `cdn` or `static`.
- Don't hard code session values such as `SiteId`, `Locale`, `Currency`, or auth tokens. The cartridge supplies those at runtime.

## Choose a bundle loading mode

The `cc_loadingMode` key in `cc_config` selects where the widget bundle comes from.

### CDN mode (default)

In CDN mode (`"cc_loadingMode": "cdn"`), the cartridge loads the bundle from the Cimulate CDN. Set `cc_cdnVersion` to the release you want to run. This guide documents version `1.30.0`. Because the version is a config value, you can move to a newer widget release by changing it, with no cartridge redeploy.

```json
{
  "cc_loadingMode": "cdn",
  "cc_cdnVersion": "1.30.0"
}
```

CDN mode is the recommended path for most storefronts. It requires the storefront to reach the CDN, so if your storefront enforces a Content Security Policy, allowlist the Cimulate origin (see [Content Security Policy](#content-security-policy)).

### Static mode

In static mode, the widget bundle ships inside the cartridge instead of loading from the CDN. Use it when the storefront can't reach an external CDN, for example behind a strict Content Security Policy (CSP) or firewall. Build the static assets and upload the cartridge:

```sh
npm run copy:static
npm run uploadCartridge
```

Then set `"cc_loadingMode": "static"` in `cc_config`.

**note:** In static mode, you own version updates. The bundle is whatever `@cimulate/copilot-widget` version the cartridge's dependencies resolve to, so update that dependency and rerun `npm run copy:static` and `npm run uploadCartridge` to move to a newer widget release. The `cc_cdnVersion` value has no effect in static mode.

## Verify the deployment

1. Open any storefront page and open your browser's developer tools.
2. In the **Network** tab, confirm the widget bundle (`messaging.umd.js`) returns a 200.
3. With `cc_isDevelopment` set to `true`, check the **Console** for `[CommerceClient]` messages.
4. Confirm the chat launcher appears in the configured position.

## Content Security Policy

If your storefront enforces a Content Security Policy, allowlist the Cimulate origin so the bundle, styles, and connection are permitted:

| Directive | Value |
| --- | --- |
| `script-src` | `https://*.cimulate.ai` |
| `style-src` | `https://*.cimulate.ai` |
| `connect-src` | `https://*.cimulate.ai` |

## Related resources

- [Agentforce Commerce Client Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/agentforce-commerce-client-overview.md)
- [Install the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/install-the-commerce-client.md)
- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Style and Theme the Widget](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.md)

<!-- document id=22efa24c0a51cb940340dc35457e1545e8cef55412c7a7b9fd2982ad93286b0e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/install-on-sfnext.md -->

# Install the Agentforce Commerce Client on Storefront Next

For Storefront Next, enable and configure Agentforce Commerce Client through a Managed Runtime environment variable, `PUBLIC__app__cimulateAgent`. The [storefront-next](https://github.com/SalesforceCommerceCloud/storefront-next-template) template reads that variable, selects the Commerce Client provider, and injects the widget for you.

## Prerequisites

The setup is covered in [B2C Shopper Agent Setup](https://help.salesforce.com/s/articleView?id=cc.b2c_shopper_agent_setup_intro.htm&type=5). In particular, these are the prerequisites:

- [Required Licenses for the B2C Shopper Agent](https://help.salesforce.com/s/articleView?id=cc.b2c_shopping_agent_licences.htm&language=en_US&type=5): Make sure your org has the required licenses provisioned for the B2C Shopper Agent.
- [Enable Agentic Commerce Search for the Shopper Agent](https://help.salesforce.com/s/articleView?id=cc.b2c_agentic_comm_search_enable.htm&language=en_US&type=5): Enable Agentic Commerce Search so that Shopper Agent can return relevant product results.
- [Create a B2C Shopper Agent Using the Automated Setup](https://help.salesforce.com/s/articleView?id=cc.b2c_shopper_agent_run_auto_setup.htm&type=5): Run the automated setup to provision and configure the B2C Shopper Agent on your Salesforce org. This includes setting up the Embedded Service deployment, obtaining the org ID, SCRT2 URL, and ES developer name, which are then supplied via the configuration below.

## Enable the Client

Set the `PUBLIC__app__cimulateAgent` environment variable on your Managed Runtime environment, or in your local `.env` file for local development.

To add an environment variable in Runtime Admin:

1. Log in to the Runtime Admin (`https://runtime.commercecloud.com/`).
2. Select your project, then the environment.
3. Under **Environment Variables**, add `PUBLIC__app__cimulateAgent` with this JSON value.

   ```json
   {
     "enabled": "true",
     "provider": "commerce-client",
     "commerceClientScriptSourceUrl": "https://cdn.search.cimulate.ai/copilot-widget/1.36.0/messaging.umd.js",
     "scrt2Url": "https://your-org.salesforce-scrt.com",
     "salesforceOrgId": "00Dxx0000000001",
     "esDeveloperName": "My_Embedded_Service",
     "headerText": "Commerce Assistant",
     "disclaimerMarkdown": "This is AI and can make mistakes.",
     "commerceClientDisplayMode": "panel",
     "commerceClientPanelWidth": "420px",
     "commerceClientMode": "messaging",
     "commerceClientLogoUrl": "https://cimulate.ai/logo.png"
   }
   ```

4. Replace fields in `PUBLIC__app__cimulateAgent` with valid values. In your Salesforce org, go to **Setup > Service > Embedded Service > Embedded Service Deployments**, and then open the deployment for the agent created in the automated setup (see [Create a B2C Shopper Agent Using the Automated Setup](https://help.salesforce.com/s/articleView?id=cc.b2c_shopper_agent_run_auto_setup.htm&type=5). Then click **Install Code Snippet**. Copy these values to the JSON value for `PUBLIC__app__cimulateAgent`:

   - Replace the `esDeveloperName` value with the copied `DeveloperName` value.
   - Replace the `scrt2Url` value with the copied `Url` value. The SCRT2 URL is the endpoint used by the embedded chat widget to communicate with the messaging service backend.
   - Replace the `salesforceOrgId` value with the copied `OrganizationId` value.
   - `commerceClientScriptSourceUrl` refers to the script of the Cimulate NPM package that powers search. We recommend you use the latest version in the URL, which is currently set to `/1.36.0/`. Get the latest version from https://www.npmjs.com/package/@cimulate/copilot-widget.

The Shopper Agent is now configured for your Storefront Next storefront.

## Roll Back Commerce Client

Because the widget is driven entirely by `PUBLIC__app__cimulateAgent`, disable it by setting `"enabled": "false"` or by removing the `PUBLIC__app__cimulateAgent` environment variable.

## Related resources

- [Shopper Agent for Storefront Next](https://developer.salesforce.com/docs/sfnext/guides/sfnext-shopping-agent.md)
- [Agentforce Commerce Client Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/agentforce-commerce-client-overview.md)
- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)

<!-- document id=70350ffe822f6b8401e104b586fdd7c01f6f1e52ddd0b0931668434bfd790a2e url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/page-designer.md -->

# Integrate Page Designer with PWA Kit

With Page Designer, you can create reusable page types and component types for your [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) site. Use the no-code Page Designer visual editor in Business Manager to design, schedule, and publish Page Designer pages for your site. When integrated with a PWA Kit site, Page Designer enables the rendering of dynamic, responsive pages that use React components.

This guide explains how to configure PWA Kit so that your site can show Page Designer pages.

Before running the commands in this topic, replace any placeholders with actual values. Placeholders have this format: `$PLACEHOLDER`.

## Prerequisites

To integrate Page Designer with a PWA Kit site:

- Build your site with either of these implementations:
  - Composable Storefront (PWA Kit version 2.7.0 or later) for your whole site with usage of the [Retail React app template](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/README.md)
  - A [phased headless rollout](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html) ([Storefront Reference Architecture - SFRA](https://developer.salesforce.com/docs/commerce/sfra/guide/sfra-overview.html) and PWA Kit version 2.7.0 or later with usage of the Retail React app template)
- Create or update a SLAS public or private client. Follow the steps in [Create a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client) or use the [registerClient API endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerClient).

  - In the **Scopes** field, include this scope: `sfcc.shopper-experience`.

    A SLAS private client offers several advantages over a public client. See [Use a SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.html).

- [Get a SLAS admin token](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#get-a-slas-admin-token).
- **Single MRT Environment**: Each Business Manager site can only have one MRT environment configured. Multiple MRT environments pointing to the same Business Manager site (n:n assignment) isn't supported.
- Create your Page Designer pages in the Page Designer visual editor. See [Create a Page Using the Page Designer Visual Editor](https://help.salesforce.com/s/articleView?id=cc.b2c_create_page.htm&language=en_US&type=5).

## Considerations

- **Required for all metadata types**: Add `arch_type: "headless"` to **all** Page Designer metadata files—pages, components, and aspect types (PDP, PLP, Search)—for headless rendering to work correctly. Without this field, Business Manager expects ISML components.
- **No ISML required**: With headless Page Designer (`arch_type: "headless"`), you only need React components, not ISML templates. This change is a major advantage, simplifying development and freeing you from maintaining parallel ISML and React implementations.
- **No custom JavaScript in metadata**: Pages and components marked as `arch_type: "headless"` don't run custom JavaScript. Only the page and component metadata (JSON) is evaluated—custom scripts are ignored. You implement all storefront logic in your PWA Kit React code—an intentional architectural change to separate concerns between the storefront (PWA Kit) and server (B2C Commerce).
- You define your components as pure React components with metadata in JSON format, specifying the architecture type, attributes, and regions.
- For pages, you define metadata including the `route` path where the page is accessible.
- Make sure that component metadata matches your React component's props structure.

## Architecture Overview

Understanding the Page Designer architecture helps you build better components and integrate them effectively into your PWA Kit site.

### Understanding Page Designer Components

Page Designer uses a hierarchical architecture with three main concepts: pages, regions, and components.

#### Pages

A **Page** is the top-level container representing a complete web page. It contains:

- Page metadata including name, description, and route
- One or more Regions that organize content
- Architecture type set to `"headless"` for React-only rendering
- A route path that defines where the page is accessible

In PWA Kit, you fetch page data with the `usePage()` hook from `@salesforce/commerce-sdk-react` and render it with the `<Page>` component.

**Page Metadata Example**:

```json
{
  "name": "Home Page",
  "description": "Main landing page with hero carousel and featured products",
  "arch_type": "headless",
  "route": "/",
  "region_definitions": [
    {
      "id": "headerbanner",
      "name": "Header Banner Region",
      "max_components": 3
    },
    {
      "id": "main",
      "name": "Main Content Region",
      "max_components": 5
    }
  ]
}
```

**Key Fields**:

- `arch_type: "headless"` - Enables React-only rendering without ISML (required for headless pages).
  - Set to `"headless"` for PWA Kit React rendering.
  - Set to `"controller"` or omit for traditional ISML rendering.
  - Supports **hybrid storefronts** with both ISML and headless pages, enabling incremental migration.
- `route` - **Critical**: URL path where the page is accessible. Page Designer uses this field to render your storefront in edit mode.
  - Static routes: `"/"` for homepage, `"/about"` for about page
  - Dynamic routes with parameters: `"/product/:productId"`, `"/category/:categoryId"`
  - **Important**: Make sure route parameters (`:productId`, `:categoryId`) match the attribute IDs defined in the page's aspect type
  - Page Designer loads your PWA Kit storefront at this route when editing the page.
- `region_definitions` - Defines the content areas for this page.

**How Page Designer Uses Routes**:

When you edit a headless page in the Page Designer visual editor, Page Designer:

1. Reads the `route` field from the page metadata.
2. Loads your PWA Kit storefront URL (configured as the connected MRT environment in Business Manager).
3. Goes to the route (for example, `/`, `/product/123`, `/category/mens`).
4. Renders your React page in an iframe for live editing.
5. Uses `arch_type: "headless"` to identify which components are headless.

This means:

- **No special page-viewer route needed** - Pages render at their actual routes.
- **Non-breaking change** - ISML pages without `arch_type: "headless"` continue to work.
- **Hybrid storefronts supported** - Mix ISML and headless pages during migration.
- **Accurate preview** - See exactly what customers see on your PWA Kit site.

**Routes in Page Types**:

Different page types require different route configurations:

| Page Type                           | Route Example             | Description                                                                       |
| ----------------------------------- | ------------------------- | --------------------------------------------------------------------------------- |
| Homepage                            | `"/"`                     | Static route for the main landing page                                            |
| Content Page                        | `"/about"`, `"/contact"`  | Static routes for informational pages                                             |
| Product Detail Page (PDP)           | `"/product/:productId"`   | Dynamic route where `:productId` matches the attribute ID in the PDP aspect type  |
| Category/Product Listing Page (PLP) | `"/category/:categoryId"` | Dynamic route where `:categoryId` matches the attribute ID in the PLP aspect type |
| Search Results Page                 | `"/search"`               | Static route for search results                                                   |

**Dynamic Route Parameters**:

For pages with dynamic routes (PDP, PLP), the route parameter name must match the attribute ID defined in the page's aspect type metadata:

```json
{
  "name": "Product Detail Page",
  "arch_type": "headless",
  "route": "/product/:productId",
  "attribute_definitions": [
    {
      "id": "productId",
      "name": "Product ID",
      "type": "product",
      "required": true
    }
  ]
}
```

In this example, the route parameter `:productId` matches the attribute definition `id: "productId"`. When a merchant selects a product in Page Designer, the system uses this attribute to construct the correct URL for preview.

#### Regions

A **Region** is a logical content area within a page or component. Regions:

- Contain an ordered list of components.
- Are nestable within Layout components.
- Are identifiable by unique IDs (for example, 'main', 'header', 'sidebar').
- Can define maximum component limits and restrictions.

The `<Region>` component from `@salesforce/commerce-sdk-react/components` handles rendering regions and their child components.

#### Components

**Components** are the building blocks of your page content. There are two types:

**Leaf Components** (Content Components):

- Render actual content (images, text, products, carousels).
- Do NOT contain nested regions.
- Have `"region_definitions": []` in their metadata.
- Examples: ContentCard, Hero, ProductCarousel.
- Receive their configuration as props directly from Page Designer.

**Layout Components** (Container Components):

- Organize other components with visual layouts (grids, columns, tabs).
- Must contain one or more nested Regions to hold child components.
- Have populated `"region_definitions"` in their metadata.
- Use the `<Region>` component to render their nested content.
- Examples: Grid, Carousel (when used as a container).

**Component Metadata Example (Leaf Component)**:

```json
{
  "name": "Content Card",
  "description": "Flexible card component with optional image, title, description, and CTA",
  "group": "odyssey_base",
  "arch_type": "headless",
  "region_definitions": [],
  "attribute_definition_groups": [
    {
      "id": "contentCard",
      "name": "Content Card",
      "attribute_definitions": [
        {
          "id": "title",
          "name": "Title",
          "type": "string",
          "required": false
        },
        {
          "id": "imageUrl",
          "name": "Image URL",
          "type": "image",
          "required": false
        },
        {
          "id": "buttonText",
          "name": "Button Text",
          "type": "string",
          "required": false
        }
      ]
    }
  ]
}
```

**Component Metadata Example (Layout Component)**:

```json
{
  "name": "Grid",
  "description": "A flexible grid layout component for organizing content in columns",
  "group": "odyssey_base",
  "arch_type": "headless",
  "region_definitions": [
    {
      "id": "main",
      "name": "Main"
    }
  ],
  "attribute_definition_groups": [
    {
      "id": "grid",
      "name": "Grid",
      "attribute_definitions": [
        {
          "id": "columns",
          "name": "Columns",
          "type": "enum",
          "required": false,
          "values": ["1", "2", "3", "4", "5", "6"],
          "default_value": "1"
        }
      ]
    }
  ]
}
```

**Key Fields**:

- `arch_type: "headless"` - Required for React-only components (no ISML).
- `group` - Organizes components in Page Designer.
- `region_definitions` - Empty array for leaf components, populated for layout components.
- `attribute_definitions` - Props that will be passed to your React component.

### Component Lifecycle and Data Flow

Understanding how components are discovered, loaded, and rendered helps you debug issues and optimize performance:

1. **Page Load**: The `<Page>` component receives page data from the Shopper Experience API via `usePage()` hook.
2. **Region Rendering**: The `<Page>` component maps over its regions and renders each using the `<Region>` component.
3. **Component Discovery**: For each component in a region, the `<Component>` wrapper:
   - Looks up the React component in the registry using the component's `typeId`.
   - Lazy-loads the component if needed (triggers React Suspense).
   - Extracts component data from the Page Designer configuration.
4. **Component Rendering**: The resolved React component receives:
   - Props matching the `attribute_definitions` from metadata (title, image, etc.)
   - `regions`: Nested regions (for layout components only)
   - `page`: Reference to the full page object
   - `regionId`: ID of the parent region
   - `designMetadata`: Design mode metadata (for Page Designer editor integration)

### Component Registry

The component registry dynamically loads Page Designer components on-demand using lazy imports. Instead of a simple mapping object, it uses a `ComponentRegistry` class that enables:

- **Lazy loading**: Components are only loaded when needed, reducing initial bundle size.
- **Dynamic imports**: Each component is registered with an importer function.
- **Fallback support**: Optional loading states during component load.
- **Data loaders**: Optional server/client data fetching functions hoisted to the page.

**Registry Initialization Example**:

```jsx
import {registry} from '@salesforce/commerce-sdk-react'

export function initializeRegistry() {
  // Register components with lazy imports
  registry.registerImporter('pwa.contentCard', () => import('./components/content-card'))

  registry.registerImporter('pwa.grid', () => import('./components/grid'))

  // Register component with data loader and fallback
  registry.registerImporter('pwa.productCarousel', () => import('./components/product-carousel'), {
    loader: 'loader',
    fallback: 'fallback'
  })
}
```

**How It Works**:

1. Call `initializeRegistry()` once during app startup.
2. When a page renders, the registry checks if the component is loaded.
3. If not loaded, it calls the importer function (triggers React Suspense).
4. Subsequent uses of the same component are instant.

**Key Benefits**:

- Only components used on the page are downloaded.
- Initial page load is faster.
- Components are shared across pages (loaded one time and cached).
- Eliminates the manual management of imports in page files.

## Building Layout Components

Layout components organize other components using visual layouts. They render nested regions to hold child components.

### React Component Structure

Here's an example of a layout component that shows content in a responsive grid:

```jsx
import React from 'react'
import PropTypes from 'prop-types'
import {SimpleGrid} from '@salesforce/retail-react-app/app/components/shared/ui'
import {Region, regionPropType} from '@salesforce/commerce-sdk-react/components'

/**
 * This layout component displays its children in a 2 row x 1 column grid on mobile
 * and a 1 row x 2 column grid on desktop.
 */
export const MobileGrid2r1c = ({regions, component}) => {
  return (
    <SimpleGrid columns={{base: 1, sm: 2}} gridGap={4}>
      {regions.map((region) => (
        <Region key={region.id} regionId={region.id} component={component} />
      ))}
    </SimpleGrid>
  )
}

MobileGrid2r1c.propTypes = {
  regions: PropTypes.arrayOf(regionPropType).isRequired,
  component: PropTypes.object.isRequired
}

export default MobileGrid2r1c
```

### Component Metadata

Store the metadata in your cartridge at:
`cartridge/experience/components/{group}/{componentId}.json`

```json
{
  "name": "Mobile Grid 2x1",
  "description": "2 row x 1 column grid on mobile, 1 row x 2 column on desktop",
  "group": "odyssey_base",
  "arch_type": "headless",
  "region_definitions": [
    {
      "id": "region1",
      "name": "First Region"
    },
    {
      "id": "region2",
      "name": "Second Region"
    }
  ],
  "attribute_definition_groups": []
}
```

### Key Points for Layout Components

- **arch_type is "headless"**: This tells Business Manager no ISML component is needed.
- **Receive `regions` and `components` prop**: Layout components get an array of region objects and the parent component object.
- **Map over regions**: Each nested region is rendered using the `<Region>` component.
- **Pass required props**: Each `<Region>` needs:
  - `regionId`: The unique identifier for the region
  - `component`: The parent component object (the `Region` finds the region data from `component.regions`)
  - `key`: React key prop for list rendering
- **Metadata region match**: Make sure the `region_definitions` in your metadata match the regions your component expects.

## Building Leaf Components

Leaf components render actual content and do NOT contain nested regions. They're the "content" pieces that get placed inside layout components.

### React Component Structure

Here's an example of a leaf component that displays an image:

```jsx
import React from 'react'
import PropTypes from 'prop-types'
import {Box, Image} from '@salesforce/retail-react-app/app/components/shared/ui'

/**
 * Simple ImageTile component that displays a responsive image.
 * This component can be placed inside any Layout component.
 */
export const ImageTile = ({image}) => {
  return (
    <Box className="image-tile">
      <figure>
        <picture>
          <source srcSet={image?.src?.tablet} media="(min-width: 48em)" />
          <source srcSet={image?.src?.desktop} media="(min-width: 64em)" />
          <Image src={image?.src?.mobile || image?.url} alt={image?.alt} title={image?.alt} />
        </picture>
      </figure>
    </Box>
  )
}

ImageTile.propTypes = {
  image: PropTypes.shape({
    url: PropTypes.string,
    alt: PropTypes.string,
    src: PropTypes.shape({
      mobile: PropTypes.string,
      tablet: PropTypes.string,
      desktop: PropTypes.string
    })
  })
}

export default ImageTile
```

### Component Metadata

Store the metadata in your cartridge at:
`cartridge/experience/components/{group}/{componentId}.json`

```json
{
  "name": "Image Tile",
  "description": "Simple image display component with responsive sources",
  "group": "odyssey_base",
  "arch_type": "headless",
  "region_definitions": [],
  "attribute_definition_groups": [
    {
      "id": "imageTile",
      "name": "Image Tile",
      "attribute_definitions": [
        {
          "id": "image",
          "name": "Image",
          "type": "image",
          "required": true,
          "description": "The image to display"
        }
      ]
    }
  ]
}
```

### Key Points for Leaf Components

- **arch_type is "headless"**: No ISML component needed.
- **region_definitions is empty array**: Leaf components don't have nested regions.
- **Attributes match props**: Each `attribute_definition` becomes a prop passed to your React component.
- **Define PropTypes**: Always define PropTypes to match your metadata attributes.
- **Supported attribute types**: string, text, markup, integer, boolean, product, category, file, page, image, url, enum, custom

## Migrating from PWA Kit with ISML to Headless

The older PWA Kit Page Designer implementation required ISML components. This section describes how to migrate to the new headless metadata approach, which uses React components only.

### Understanding the Transformation

The biggest win: **You no longer need ISML components.** With `arch_type: "headless"`, you only maintain React components.

| Aspect                               | Old PWA Kit Approach (with ISML)                                                                                  | New Approach                                                                                                                                                                             |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Component Definition                 | ISML + React components required                                                                                  | React components only                                                                                                                                                                    |
| Metadata                             | Component metadata in JSON                                                                                        | Component metadata in JSON with `arch_type: "headless"`                                                                                                                                  |
| Maintenance                          | Two implementations (ISML + React)                                                                                | Single React implementation                                                                                                                                                              |
| Component Registry and Bundle Impact | Uses a mapping object that you configure manually to register components. All components loaded. No lazy loading. | Uses a dynamic registry to lazy load components. Only the used components are loaded (code splitting). Loading of non-critical components or resources is deferred until they're needed. |
| Dependencies                         | `@salesforce/commerce-sdk-react`                                                                                  | Requires `@salesforce/storefront-next-runtime` in PWA Kit v3.17 or later, in addition to `@salesforce/commerce-sdk-react`.                                                               |
| Region or Component                  | Basic components                                                                                                  | Enhanced `Region` and `Component` with design mode                                                                                                                                       |
| Page Routing                         | Manual route setup                                                                                                | Automatic via `route` field in metadata                                                                                                                                                  |
| Server-Side Custom JavaScript        | Executed at run time                                                                                              | No server-side JavaScript code. All functionality is implemented in React code.                                                                                                          |
| Preview                              | Preview in Page Designer shows only ISML pages. Storefront Preview needed for PWA live preview.                   | Page Designer can preview PWA Kit storefront.                                                                                                                                            |

### Migration Steps

#### Step 1: Install Required Dependency

Add the `@salesforce/storefront-next-runtime` package to your project:

```bash
npm install @salesforce/storefront-next-runtime
```

Update your `package.json`:

```json
{
  "dependencies": {
    "@salesforce/storefront-next-runtime": "^VERSION",
    "@salesforce/commerce-sdk-react": "^VERSION"
  }
}
```

#### Step 2: Update Component Metadata to Headless

For **each existing component** in your cartridge, update the JSON metadata file to include `arch_type: "headless"`:

**Before** (`cartridge/experience/components/commerce_assets/photoTile.json`):

```json
{
    "name": "Photo Tile",
    "description": "Image display component",
    "group": "commerce_assets",
    "attribute_definition_groups": [...]
}
```

**After**:

```json
{
    "name": "Photo Tile",
    "description": "Image display component",
    "group": "commerce_assets",
    "arch_type": "headless",
    "region_definitions": [],
    "attribute_definition_groups": [...]
}
```

**Required changes for each component**:

- Add `"arch_type": "headless"`.
- Add `"region_definitions": []` for leaf components, or populate with regions for layout components.

#### Step 3: Update Page Metadata with Routes

For **each existing page** in your cartridge, update the JSON metadata to include `arch_type` and `route`:

**Before** (`cartridge/experience/pages/homePage.json`):

```json
{
    "name": "Home Page",
    "description": "Main landing page",
    "region_definitions": [...]
}
```

**After**:

```json
{
    "name": "Home Page",
    "description": "Main landing page",
    "arch_type": "headless",
    "route": "/",
    "region_definitions": [...]
}
```

**Route examples**:

- Homepage: `"route": "/"`
- Static pages: `"route": "/about"`, `"route": "/contact"`
- Product pages: `"route": "/product/:productId"` (`:productId` matches the attribute ID in your aspect type)
- Category pages: `"route": "/category/:categoryId"` (`:categoryId` matches the attribute ID in your aspect type)

#### Step 4: Update Aspect Type Metadata

For **each aspect type** (PDP, PLP, Search), add `arch_type`:

**Before** (`cartridge/experience/aspects/pdp.json`):

```json
{
    "name": "Product detail page",
    "description": "A product detail page",
    "attribute_definitions": [...],
    "supported_object_types": ["product"]
}
```

**After**:

```json
{
    "name": "Product detail page",
    "description": "A product detail page",
    "arch_type": "headless",
    "attribute_definitions": [...],
    "supported_object_types": ["product"]
}
```

#### Step 5: Migrate from Manual Mapping to Registry

Replace the old manual component mapping with the new registry approach.

**Remove** the old mapping pattern from your page-viewer:

```jsx
// OLD - Remove this
const PAGEDESIGNER_TO_COMPONENT = {
    'commerce_assets.photoTile': ImageTile,
    'commerce_layouts.carousel': Carousel,
    // ...
}

<Page page={page} components={PAGEDESIGNER_TO_COMPONENT} />
```

**Create** a registry file at `app/page-designer/registry.js`:

```jsx
import {registry} from '@salesforce/commerce-sdk-react'

export function initializeRegistry() {
  // Commerce Assets
  registry.registerImporter('commerce_assets.imageTile', () => import('./assets/image-tile'))
  registry.registerImporter('commerce_assets.imageAndText', () =>
    import('./assets/image-with-text')
  )
  registry.registerImporter('commerce_assets.productTile', () => import('./assets/product-tile'))

  // Commerce Layouts
  registry.registerImporter('commerce_layouts.carousel', () => import('./layouts/carousel'))
  registry.registerImporter('commerce_layouts.mobileGrid1r1c', () =>
    import('./layouts/mobileGrid1r1c')
  )
  registry.registerImporter('commerce_layouts.mobileGrid2r1c', () =>
    import('./layouts/mobileGrid2r1c')
  )
  registry.registerImporter('commerce_layouts.mobileGrid2r2c', () =>
    import('./layouts/mobileGrid2r2c')
  )
  registry.registerImporter('commerce_layouts.mobileGrid2r3c', () =>
    import('./layouts/mobileGrid2r3c')
  )
  registry.registerImporter('commerce_layouts.mobileGrid3r1c', () =>
    import('./layouts/mobileGrid3r1c')
  )
  registry.registerImporter('commerce_layouts.mobileGrid3r2c', () =>
    import('./layouts/mobileGrid3r2c')
  )
}
```

**Update** your page-viewer to use the registry:

```jsx
// app/pages/page-viewer/index.jsx
import React from 'react'
import {useParams} from 'react-router-dom'
import {Box} from '@salesforce/retail-react-app/app/components/shared/ui'
import {usePage} from '@salesforce/commerce-sdk-react'
import {Page} from '@salesforce/commerce-sdk-react/components'
import {HTTPError, HTTPNotFound} from '@salesforce/pwa-kit-react-sdk/ssr/universal/errors'

const PageViewer = () => {
  const {pageId} = useParams()
  const {data: page, error} = usePage({parameters: {pageId}})

  if (error) {
    let ErrorClass = error.response?.status === 404 ? HTTPNotFound : HTTPError
    throw new ErrorClass(error.response?.statusText)
  }

  return (
    <Box layerStyle={'page'}>
      {/* No components prop needed - registry handles it */}
      <Page page={page} />
    </Box>
  )
}

export default PageViewer
```

#### Step 6: Set Up PageDesignerProvider in App Component

Update your main `_app/index.jsx` to initialize the registry and wrap with PageDesignerProvider:

```jsx
// app/components/_app/index.jsx
import {PageDesignerProvider} from '@salesforce/commerce-sdk-react/components'
import {useUsid} from '@salesforce/commerce-sdk-react'
import {initializeRegistry} from '@salesforce/retail-react-app/app/page-designer/registry'

// Initialize registry synchronously at module load time so components are available during SSR
initializeRegistry()

const App = (props) => {
  const {children} = props
  const {usid} = useUsid()

  // Detect Page Designer mode from URL
  const pageDesignerMode = useMemo(() => {
    const queryParams = location?.search || ''
    if (queryParams.includes('mode=EDIT')) return 'EDIT'
    if (queryParams.includes('mode=PREVIEW')) return 'PREVIEW'
    return undefined
  }, [])

  return (
    <Box className="sf-app">
      {/* Other providers... */}
      <PageDesignerProvider
        clientId="pwa-kit-client"
        targetOrigin="*"
        usid={usid}
        mode={pageDesignerMode}
      >
        {children}
      </PageDesignerProvider>
    </Box>
  )
}
```

**Key setup points**:

1. **Initialize registry at module level** (outside the component) so components are available during SSR.
2. **Pass `usid`** from `useUsid()` hook to the provider for session tracking.
3. **Detect mode from URL** - Page Designer passes `mode=EDIT` or `mode=PREVIEW` as query parameters.
4. **Always wrap with PageDesignerProvider** - it handles both design mode and normal rendering.

#### Step 7: Create PageDesignerInit Component

Create `app/components/page-designer-init/index.jsx` to handle design mode behaviors:

```jsx
import React, {useEffect} from 'react'
import {Prompt} from 'react-router-dom'
import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
import {useGlobalAnchorBlock} from '@salesforce/retail-react-app/app/hooks/use-global-anchor-block'

export function PageDesignerInit() {
  const {isDesignMode} = usePageDesignerMode()

  useGlobalAnchorBlock(isDesignMode)

  useEffect(() => {
    if (isDesignMode) {
      void import('@salesforce/storefront-next-runtime/design/styles.css')
    }
  }, [isDesignMode])

  return <Prompt when={isDesignMode} message={() => false} />
}

export default PageDesignerInit
```

#### Step 8: Create useGlobalAnchorBlock Hook

Create `app/hooks/use-global-anchor-block.js` to prevent link navigation in design mode:

```jsx
import {useEffect} from 'react'

export function useGlobalAnchorBlock(enabled = true) {
  useEffect(() => {
    if (typeof window === 'undefined' || !enabled) return

    function preventAnchorClicks(event) {
      const anchor = event.target.closest('a')
      // Allow links with data-pd-allow-link attribute
      if (anchor && !anchor.hasAttribute('data-pd-allow-link')) {
        event.preventDefault()
      }
    }

    document.addEventListener('click', preventAnchorClicks)
    return () => document.removeEventListener('click', preventAnchorClicks)
  }, [enabled])
}
```

#### Step 9: Add PageDesignerInit to App

In `app/components/_app/index.jsx`, render `PageDesignerInit` inside the provider:

```jsx
import {PageDesignerInit} from '@salesforce/retail-react-app/app/components/page-designer-init'

// Inside your App component's return:
;<PageDesignerProvider
  clientId="pwa-kit-client"
  targetOrigin="*"
  usid={usid}
  mode={pageDesignerMode}
>
  <PageDesignerInit />
  {children}
</PageDesignerProvider>
```

#### Step 10: Deploy and Test

1. Deploy your updated cartridge with headless metadata to your SFCC instance.
2. Restart your PWA Kit development server:
   ```bash
   npm start
   ```
3. Verify in Business Manager:
   - Go to **Merchant Tools > Content > Components**.
   - Your components appear with no ISML requirement.
4. Test page rendering:
   - Go to your pages (homepage, PDP, PLP).
   - Components render using the registry.
5. Test in Page Designer:
   - Open the Page Designer visual editor.
   - Edit a page - your PWA Kit site shows in the preview.
   - Drag components - changes show immediately.

### Common Migration Challenges

**Challenge**: Custom JavaScript no longer runs
**Solution**: Headless components (`arch_type: "headless"`) do **not** run custom JavaScript from Page Designer metadata. Migrate all custom logic to your React components. This approach is intentional—it separates storefront logic (PWA Kit React) from content configuration (Business Manager JSON).

**Example**:

```javascript
// OLD - Custom script in Page Designer (no longer executed)
// This JavaScript will be IGNORED for headless components

// NEW - Implement in your React component
export const MyComponent = ({title, showDiscount}) => {
  // All logic in React code
  const displayPrice = showDiscount ? applyDiscount(price) : price
  return <div>{displayPrice}</div>
}
```

**Challenge**: Forgetting to set `arch_type: "headless"`
**Solution**: Always include `"arch_type": "headless"` in your metadata. Otherwise, Business Manager expects ISML components.

**Challenge**: Metadata attributes don't match React props
**Solution**: Ensure every `attribute_definition` `id` matches a prop name in your React component. Use PropTypes to validate.

**Challenge**: Component typeId mismatch
**Solution**: The typeId format is `{group}.{componentId}`. In your registry, use the same format: `'odyssey_base.myComponent': MyComponent`

**Challenge**: Layout component regions not rendering
**Solution**: Ensure that your metadata includes `region_definitions` and your React component maps over the `regions` prop with `<Region>` components.

**Challenge**: Page route not working
**Solution**: For page metadata, include the `route` field with the URL path (for example, `"route": "/"` for homepage).

**Challenge**: Region not found
**Solution**: Verify `regionId` matches the region ID in your page data. For nested regions, pass `component` not `page`. Use `errorElement` prop to handle missing regions gracefully.

**Challenge**: Visual editing not working
**Solution**: Ensure `PageDesignerProvider` wraps your content. Verify `targetOrigin` matches your Business Manager URL. Check browser console for postMessage errors.

## New Features

The updated Page Designer implementation includes several new features for enhanced visual editing support.

### Design Metadata

Components now receive `designMetadata` with information for visual editing:

```typescript
interface ComponentDesignMetadata {
  id: string // Component instance ID
  name?: string // Display name
  isFragment: boolean // Is this a fragment?
  isVisible: boolean // Is component visible?
  isLocalized: boolean // Is component localized?
}
```

Components also receive additional props:

- `component` - The full component data object
- `regionId` - The parent region's ID

You don't need to use these props, but they're available if needed for custom behavior.

### Design Mode Detection

Use the `usePageDesignerMode` hook to conditionally render content based on design mode:

```jsx
import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'

function MyComponent() {
  const {isDesignMode, isPreviewMode} = usePageDesignerMode()

  return (
    <div>
      {isDesignMode && <span>Editing mode</span>}
      {/* ... */}
    </div>
  )
}
```

Or use the utility functions for checking outside of React components:

```jsx
import {isDesignModeActive, isPreviewModeActive} from '@salesforce/commerce-sdk-react/components'

if (isDesignModeActive()) {
  // In design mode
}
```

### Page Component API

The `Page` component no longer requires a `components` prop. Components are now resolved via the registry.

| Before                                  | After                    |
| --------------------------------------- | ------------------------ |
| `<Page page={data} components={map} />` | `<Page page={data} />`   |
| Required `components` prop              | Components from registry |
| Used `PageContext` internally           | No context needed        |

### Updated Region API

The `Region` component API has changed to support nested regions in layout components:

| Before                          | After                                         |
| ------------------------------- | --------------------------------------------- |
| `<Region region={regionObj} />` | `<Region component={comp} regionId="main" />` |
| Received region object directly | Finds region by ID from component             |
| No fallback support             | `fallbackElement` and `errorElement` props    |

**New Region Props:**

```jsx
// For page-level regions
<Region page={page} regionId="main" fallbackElement={<Loading />} />

// For nested regions in layout components
<Region component={component} regionId="left" errorElement={<Error />} />
```

### Component Registry API

```javascript
import {registry} from '@salesforce/commerce-sdk-react'

// Register with lazy loading
registry.registerImporter('typeId', () => import('./component'))

// Register with fallback for loading state
registry.registerImporter(
  'typeId',
  () => import('./component'),
  () => import('./skeleton')
)

// Get a component
const Component = registry.getComponent('typeId')

// Preload a component
await registry.preload('typeId')
```

### Component (Internal)

The `Component` is now internal and uses the registry. You don't interact with it directly.

| Before                                    | After                          |
| ----------------------------------------- | ------------------------------ |
| Used `usePageContext()` for component map | Uses `registry.getComponent()` |
| Wrapped in `<div className="component">`  | No wrapper div                 |
| Synchronous rendering                     | Suspense-based lazy loading    |

## Complete Migration Example

Here's a consolidated before/after example showing the full transformation:

**Before (Old API):**

```jsx
// page-viewer.jsx
import {Page} from '@salesforce/commerce-sdk-react/components'
import ImageTile from './components/image-tile'
import Banner from './components/banner'
import TwoColumn from './components/two-column'

const components = {
  'commerce_assets.imageTile': ImageTile,
  'commerce_assets.banner': Banner,
  'commerce_layouts.twoColumn': TwoColumn
}

function PageViewer({pageData}) {
  return <Page page={pageData} components={components} />
}

// two-column.jsx
import {Region} from '@salesforce/commerce-sdk-react/components'

function TwoColumn({regions}) {
  return (
    <div>
      <Region region={regions.left} />
      <Region region={regions.right} />
    </div>
  )
}
```

**After (New API):**

```jsx
// registry.js
import {registry} from '@salesforce/commerce-sdk-react'

export function initializeRegistry() {
  registry.registerImporter('commerce_assets.imageTile', () => import('./assets/image-tile'))
  registry.registerImporter('commerce_assets.banner', () => import('./assets/banner'))
  registry.registerImporter('commerce_layouts.twoColumn', () => import('./layouts/two-column'))
}

// _app/index.jsx
import {initializeRegistry} from './page-designer/registry'
initializeRegistry() // At module level, not in useEffect

// page-viewer.jsx
import {Page} from '@salesforce/commerce-sdk-react/components'

function PageViewer({pageData}) {
  return <Page page={pageData} />
}

// two-column.jsx
import {Region} from '@salesforce/commerce-sdk-react/components'

function TwoColumn({component}) {
  return (
    <div>
      <Region component={component} regionId="left" />
      <Region component={component} regionId="right" />
    </div>
  )
}
```

## Configure Page Designer

Follow these steps to set up Page Designer in a new PWA Kit project.

### 1. Install Dependencies

```bash
npm install @salesforce/storefront-next-runtime
```

### 2. Create Component Registry

Create `app/page-designer/registry.js` to register your components with lazy loading:

```jsx
import {registry} from '@salesforce/commerce-sdk-react'

export function initializeRegistry() {
  // Register layout components
  registry.registerImporter('commerce_layouts.carousel', () => import('./layouts/carousel'))
  registry.registerImporter('commerce_layouts.mobileGrid2r1c', () =>
    import('./layouts/mobileGrid2r1c')
  )

  // Register asset components
  registry.registerImporter('commerce_assets.photoTile', () => import('./assets/image-tile'))
  registry.registerImporter('commerce_assets.imageAndText', () =>
    import('./assets/image-with-text')
  )

  // Add all your Page Designer components here
}
```

### 3. Set Up App Integration

Update `app/components/_app/index.jsx` to initialize Page Designer:

```jsx
import {PageDesignerProvider} from '@salesforce/commerce-sdk-react/components'
import {useUsid} from '@salesforce/commerce-sdk-react'
import {initializeRegistry} from '@salesforce/retail-react-app/app/page-designer/registry'
import {PageDesignerInit} from '@salesforce/retail-react-app/app/components/page-designer-init'

// Initialize registry synchronously at module load time so components are available during SSR
initializeRegistry()

const App = (props) => {
  const {children} = props
  const {usid} = useUsid()

  // Detect Page Designer mode from URL
  const pageDesignerMode = useMemo(() => {
    const queryParams = location?.search || ''
    if (queryParams.includes('mode=EDIT')) return 'EDIT'
    if (queryParams.includes('mode=PREVIEW')) return 'PREVIEW'
    return undefined
  }, [])

  return (
    <Box className="sf-app">
      <PageDesignerProvider
        clientId="pwa-kit-client"
        targetOrigin="*"
        usid={usid}
        mode={pageDesignerMode}
      >
        <PageDesignerInit />
        {children}
      </PageDesignerProvider>
    </Box>
  )
}
```

### 4. Create PageDesignerInit Component

Create `app/components/page-designer-init/index.jsx`:

```jsx
import React, {useEffect} from 'react'
import {Prompt} from 'react-router-dom'
import {usePageDesignerMode} from '@salesforce/commerce-sdk-react/components'
import {useGlobalAnchorBlock} from '@salesforce/retail-react-app/app/hooks/use-global-anchor-block'

export function PageDesignerInit() {
  const {isDesignMode} = usePageDesignerMode()

  // Block anchor navigation when in design mode
  useGlobalAnchorBlock(isDesignMode)

  // Load Page Designer styles only in design mode
  useEffect(() => {
    if (isDesignMode) {
      void import('@salesforce/storefront-next-runtime/design/styles.css')
    }
  }, [isDesignMode])

  // Block React Router navigation in design mode
  return <Prompt when={isDesignMode} message={() => false} />
}

export default PageDesignerInit
```

### 5. Create useGlobalAnchorBlock Hook

Create `app/hooks/use-global-anchor-block.js`:

```jsx
import {useEffect} from 'react'

export function useGlobalAnchorBlock(enabled = true) {
  useEffect(() => {
    if (typeof window === 'undefined' || !enabled) return

    function preventAnchorClicks(event) {
      const anchor = event.target.closest('a')
      // Allow links with data-pd-allow-link attribute
      if (anchor && !anchor.hasAttribute('data-pd-allow-link')) {
        event.preventDefault()
      }
    }

    document.addEventListener('click', preventAnchorClicks)
    return () => document.removeEventListener('click', preventAnchorClicks)
  }, [enabled])
}
```

### 6. How It Works

With this setup:

1. **Your existing routes work automatically** - No special page-viewer route needed
2. **Page Designer loads your actual routes** - When you edit a page with `"route": "/"`, Page Designer loads your homepage at `/`
3. **Live editing** - Changes in Page Designer's visual editor appear instantly in your PWA Kit storefront
4. **Hybrid support** - Mix headless and ISML pages during migration

**Example**: If you create a homepage with:

```json
{
    "name": "Home Page",
    "arch_type": "headless",
    "route": "/",
    "region_definitions": [...]
}
```

Page Designer:

- Loads your PWA Kit site's homepage (`/`).
- Renders it in an iframe for editing.
- Applies changes in real-time.

## See Also

- _GitHub:_ [Page Designer Repo for PWA Kit](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/template-retail-react-app/app/page-designer)
- _Salesforce Help:_ [Page Designer Pages](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_pd_pages.htm&type=5)

<!-- document id=9722b57d44828ba1b95a57c8ed2bc4417c9423f1e534dc1fa1cdde766510b73b url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/payment-gateway-spi.md -->

# Integrate Payment Gateways Using the Payment Gateway SPI

Point of Sale's Payment Gateway SPI lets you integrate third-party payment gateway terminals (for example, Worldpay or Stripe Terminal) with POS through a store-local proxy server. Implement the SPI on a proxy that runs on the store's local network and acts as an intermediary between the POS iOS client and the payment gateway terminals. The proxy handles terminal communication, gateway protocol translation, and real-time event streaming so that new gateway integrations can be added without modifying the POS iOS application.

**note:** For endpoint details, see [Payment Gateway SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/payment-spi?meta=Summary) in the Point of Sale reference documentation.

For a comprehensive list of Point of Sale APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Architecture

This diagram shows a payment for a client that uses the WebSocket channel.

![Sequence diagram of a payment: the POS iOS App opens a WebSocket to the Payment SPI Server and receives a CONNECTED event, then POSTs a payment over REST (mTLS + HMAC). The proxy makes a gateway SDK call to the Payment Terminal, then streams real-time terminal events (card inserted, PIN entry, authorization progress) back to the client over the WebSocket while the cardholder interacts with the terminal. Finally, the terminal returns an authorization result to the proxy, which returns the final REST response to the client.](https://developer.salesforce.com/docs/media/retail-cloud/payment-gateway-spi-architecture.png)

The proxy exposes two channels that run side by side:

- **REST over mTLS + HMAC-SHA256** — the command channel. The POS iOS client uses this to start, cancel, and query transactions. The REST response is the source of truth for a transaction's outcome.
- **WebSocket** — the event channel. Long-lived and optional. The client uses events to render real-time UI updates as the cardholder interacts with the terminal (for example, `CARD_INSERTED`, `PIN_ENTRY_STARTED`, `AUTHORIZATION_APPROVED`).

The client generates a `transactionId` (UUID v4) per payment and uses it as the correlation ID across the WebSocket stream, the REST call, and any follow-up operations (cancel, void, capture, status query).

The payment flow, when the client uses the WebSocket channel:

1. The client opens a WebSocket to `WSS /events?transactionId={transactionId}` and waits for a `CONNECTED` event.
2. The client calls `POST /payment` with the same `transactionId`.
3. The proxy drives the terminal and streams events back over the WebSocket.
4. The proxy returns the final authorization result in the REST response.

The WebSocket channel is optional — support clients that skip it and rely on the REST response alone.

## Security Modes

The proxy supports two security modes:

- **Secure mode** (production): Requires mTLS transport and HMAC-SHA256 request signing.
- **Simple mode** (testing only): No mTLS and no HMAC. Self-signed certificates are accepted.

For HMAC message format and required headers, see the Security section of the [Payment Gateway SPI reference](https://developer.salesforce.com/docs/commerce/retail-cloud/references/payment-spi?meta=Summary).

## Date Format

All date and time fields use **ISO 8601** format. The proxy server must accept both:

- Standard format: `2026-03-12T14:04:06Z`
- Fractional seconds: `2026-03-12T14:04:06.206Z`

The server should return dates with fractional seconds for maximum precision.

## Client Timeouts

The POS iOS client enforces per-operation timeouts. If the proxy doesn't respond within the window listed below, the client treats the request as failed.

| Operation                | Timeout |
|--------------------------|---------|
| Initial connection       | 10s     |
| Payment                  | 120s    |
| Payment + recovery       | 300s    |
| Status query             | 30s     |
| Health check             | 5s      |
| Cancel / Void            | 30s     |
| Refund                   | 120s    |
| Gift Card Balance        | 30s     |
| Gift Card Operation      | 60s     |
| Gift Card Payment        | 120s    |
| Card Acquisition         | 120s    |
| Terminal Display         | 10s     |
| Terminal Input           | 120s    |
| PBL Create               | 30s     |
| PBL Expire               | 15s     |
| PBL Status Query         | 15s     |
| PBL Refund/Void          | 120s    |
| SAF Query                | 15s     |
| Offline Validation       | 30s     |
| Terminal Offline Status  | 5s      |

<!-- document id=380ecf8aae4b6834d8aa344252916223197f429434ed089c8b021eff076322e4 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/integrate-data-cloud.md -->

# Integrate PWA Kit with Data Cloud

To unify your customer data on Salesforce, connect your Progressive Web App (PWA) Kit storefront to [Data Cloud](https://help.salesforce.com/s/articleView?id=data.c360_a_data_cloud.htm). After you set your store as a data source, Data Cloud receives engagement events, which are triggered by shopper activities in your storefront.
These engagement events are supported.

- `ViewPage` — A shopper views a page.
- `ViewProduct` — A shopper views a product detail page.
- `ViewCategory` — A shopper views a category or listing page.
- `ViewSearchResults` — A shopper performs a product search.
- `ViewRecommendations` — A shopper views personalized recommendations.

## Prerequisites

To use Data Cloud with PWA Kit, you must first set up your own production instance of Data Cloud. See [Get Started Using Data Cloud](https://help.salesforce.com/s/articleView?id=data.c360_a_product_considerations.htm) in _Salesforce Help_.

## Send PWA Kit Events to Data Cloud

1. To connect your storefront to Data Cloud, complete the instructions from [Connect a Website or Mobile App to Data Cloud](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-set-up-mobile-web-connection.html) in the _Data Cloud Integration Guide_. When the New Connection window asks what you’re connecting to, select **A Custom Website**.
2. To start sending data from your storefront to Data Cloud, complete the instructions from [Create a Web or Mobile App Data Stream](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-mobile-web-datastream.html) in the _Data Cloud Integration Guide_.
3. Get the Data Cloud tenant ID.
   1. In Data Cloud, click ![Setup](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/comm-setup-icon-no-border.png) at the top of the page, and then select **Data Cloud Setup**.
   2. In the Your Home Org Details section, copy and save the tenant ID from the tenant endpoint. The tenant ID is the string preceding the first period. For example, `<tenantId>.c360a.salesforce.com`.
4. Get the Data Cloud app source ID.
   1. Go back to Data Cloud Setup.
   2. In the Set Up Data Cloud section, click **Connect Other Data Sources | Website and Mobile App**.
   3. Select the connection for your PWA Kit storefront.
   4. In the Integration Guide section, copy and save the app source ID from the script. The app source ID is the string preceding /scripts. For example, `https://cdn.pc-rnd.c360a.salesforce.com/beacon/c360a/<appSourceId>scripts/c360a.min.js`.
5. Update your PWA Kit project’s [configuration file](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configuration-options.html) with the Data Cloud tenant and app source IDs from steps 3 and 4. Here’s an example configuration file with the IDs populated:

```javascript
app: {
   dataCloudAPI: {
           appSourceId: 'fb81edab-24c6-4b40-8684-b67334dfdf32',
           tenantId: 'mmyw8zrxhfsg09lfmzrd1zjqmg'
   }
}
```

## Verify Event Retrieval

1. In Data Cloud, click **Data Explorer**.
2. Select a data space.
3. From the Object dropdown list, select **Data Model Object**.
4. In the object field, search for and select **Website Engagement**.
5. To personalize your data view, click **Edit Columns** and select the columns corresponding to the data points you want to view.
6. In your store‘s test environment, try out shopper activities: search for a product, view a product detail page, and so on.
7. Refresh your Data Explorer tab and verify that engagement event data appears.

For more information about how B2C Commerce storefronts can integrate with Data Cloud, see [Sending B2C Commerce Engagement Events to Data Cloud](https://help.salesforce.com/s/articleView?id=cc.b2c_data_cloud_send_engagement_events_container.htm) in _Salesforce Help_.

<!-- document id=44fbef572dc321821fb839e0da7521d9a5a7585ec7967bfe0769e9a6e4e28b0d url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-data-analytics-section.md -->

# Integrate Storefront Next with Analytics and Data Platforms

Storefront Next provides built-in tools for tracking and analyzing shopper activity. Use the analytics hook and events to monitor storefront activity through Einstein and Active Data, or integrate with other analytics systems. To unify your customer data across Salesforce, connect Storefront Next to Data360 so that shopper engagement events, such as product views, searches, and category browsing, are sent to Data360 as a data source.

In this section:

- [Track Storefront Next Activity with Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-analytics.md)
- [Send Storefront Next Analytics Events to Data 360](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data360.md)

<!-- document id=3049eebcbfe6e8d135cf76d7a3ab087959df5b0c895f1e4a45a1f36927057312 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-order-mgmt.md -->

# Integrate Storefront Next with Salesforce Order Management

**note:** **Applies to:** Storefront Next


With the integration with Salesforce Order Management (SOM), Storefront Next displays orders from SOM in the order history page and order detail page. Shoppers can check the status of their orders and manage their orders from Storefront Next. They can track shipment, return items, and cancel an eligible order. The integration keeps storefront orders synchronized with the merchant’s backend order management system. Providing shoppers with self-service order management capabilities from within the storefront enhances the shopper experience and reduces support costs. The integration requires that you set up a connection between the B2C Commerce instance and the Salesforce Order Management (SOM) organization.

![Order history page showing the orders placed for the logged-in shopper](https://developer.salesforce.com/docs/media/sfnext/sfnext-order-history-page.png '{"class": "image-xl"}')

## Prerequisite: Connect Your B2C Commerce Instance and the Order Management Organization

Before the storefront can show SOM orders, perform these steps.

### Step 1: Connect a B2C Commerce Instance to the SOM organization

1. To connect the B2C Commerce instance to SOM, see [Connect B2C Commerce and Order Management](https://help.salesforce.com/s/articleView?id=commerce.om_impl_self_provision.htm&type=5) in _Salesforce Help_.
2. Enable sharing of SOM records. See [Enable Order Management for B2C Commerce](https://help.salesforce.com/s/articleView?id=commerce.om_impl_enable_integration.htm&type=5) in _Salesforce Help_.

### Step 2: Verify the Connection by Placing an Order

After the B2C Commerce instance is connected to SOM, place a test order from the storefront to verify that the order appears in SOM. No Storefront Next code changes are required—the integration is automatic once the B2C–SOM connection is established. If you customized order placement in your B2C Commerce cartridges, make sure that the placeOrder hook calls `OrderMgr.placeOrder(order)` and sets the export and confirmation statuses.

## Storefront Next-SOM Integration Considerations

- Payment methods aren't shown in the storefront because they aren't returned in B2C Commerce API (SCAPI) calls.
- If an order contains multiple shipments, items are grouped by shipment and each group shows its shipping address. Tracking details, such as carrier, status, and tracking number or URL, are shown at the order level rather than per shipping address.

## Getting Orders from SOM

By default, Storefront Next tries to get order data from SOM. It makes these SCAPI calls with the additional `oms` parameters.

- Get order details: The storefront calls `GET orders/{orderNo}` with query parameter `expand=oms,oms_shipments`. For more information, see [getOrder](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=getOrder) in the B2C Commerce API Guide.
- Get order history: The storefront calls `GET customers/{}/orders` with query parameter `expand=oms`. See [getCustomerOrders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=getCustomerOrders) in the B2C Commerce API Guide.
- Get SOM metadata: The storefront calls `GET /orders/oms-meta-data` via `getOmsMetaData`. The response provides `cancelReasonCodes` and `returnReasonCodes` for the cancel and return dialogs. If this endpoint returns a 404, SOM isn't active and the Cancel Order and Return Items actions are hidden.

## Placing Orders in SOM

If the connection is set up between the B2C Commerce instance and SOM, placing an order creates the order in SOM. Place the order using the `placeOrder` hook and by calling `OrderMgr.placeOrder(order)`.

## Managing Orders in SOM

The Salesforce Order Management (SOM) integration in Storefront Next lets registered shoppers manage orders stored in SOM. Storefront Next provides default implementations for the order actions in SOM so you don't have to implement them. The actions available are for shoppers tracking order shipments, canceling an order, and returning order items.

SOM enriches orders with order data, in the `omsData` field that is included in the SCAPI call. The order actions call these SCAPI endpoints:

- [returnOmsOrder](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=returnOmsOrder)
- [cancelOmsOrder](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=cancelOmsOrder)

### Prerequisites

- Managing orders requires that you connect your B2C Commerce instance to the Salesforce Order Management organization. See [this prerequisite step](#prerequisite-connect-your-b2c-commerce-instance-and-the-order-management-organization).

### Accessing the Order Detail Page

A shopper accesses the order management actions in the order detail page. These are the steps for a shopper to access the order detail page.

1. Log in and then click the **My Account** icon.
2. Click **Order History**.
3. Next to an order, click **View Details**.

![Order detail page showing buttons for tracking shipments, canceling an order, and returning items](https://developer.salesforce.com/docs/media/sfnext/sfnext-order-actions.png '{"class": "image-lg"}')

### Tracking Order Shipments

After an order has been fulfilled, a registered shopper can track the order shipments by clicking **Track Shipment** on the order detail page. Clicking **Track Shipment** redirects the shopper to an external site where they can track the shipments.

### Canceling an Order

For orders that haven't been fulfilled yet, registered shoppers can cancel the orders they created by clicking **Cancel Order** on the order detail page. After an order has been fulfilled and shipped, it is no longer cancelable. To be able to cancel an order, every item in the order must be cancelable.

![The cancel order modal with cancellation reasons](https://developer.salesforce.com/docs/media/sfnext/sfnext-confirm-cancellation.png '{"class": "image-lg"}')

### Returning Eligible Items

After an order has been fulfilled, a registered shopper can return eligible items by clicking **Return Items** on the order detail page. In the Return items modal, the shopper can select one or more items to return, their quantity, and the return reason.

![The return item modal with return reasons](https://developer.salesforce.com/docs/media/sfnext/sfnext-return-items.png '{"class": "image-xl"}')

After submitting a return request, the order's status badge reflects the return's progress. This progress includes partial return status, when a return is initiated for a subset of items in an order.

**note:** Return and cancellation reasons come from SOM. They aren't hardcoded in Storefront Next.

### Order Refunds

SOM processes the refunds for order cancellations and returns, and not B2C Commerce or Storefront Next. There is nothing to implement in Storefront Next for refunds. The storefront's responsibility ends at initiating the return or cancellation.

For returns, the automated refund occurs only after the item is physically returned, not when the shopper initiates the return:

1. Shopper requests a return. The `create-return-order` API creates a return order in SOM.
2. The item is physically returned, and the return order is closed manually in the SOM UI or via an API integration.
3. The close event triggers the `EnsureRefunds` API, which makes a callout to the payment service provider (PSP) to process the refund. A credit memo is generated.

For cancellations, the same automated refund process fires on the order's status change.

## Status Badge

The status badge shows the order status for each order. The status badge indicates order placement, fulfillment, cancellation, and return progress.

To customize the display status, override `getOrderFulfillmentStatus` in `src/lib/order/status.ts`. The the display status aggregates item-level SOM statuses into a single display status.

To customize how statuses display, override the relevant helpers in `src/lib/order/status.ts`:

- `getOrderFulfillmentStatus`: Aggregates item-level fulfillment statuses, such as shipped, delivered, and so on.
- `getOrderCancelStatusConfig`: Derives the canceled status from item-level SOM cancel states.
- `getOrderReturnStatus`: Derives return progress, such as partial return and return complete.
- `resolveOrderStatus`: Selects between the B2C Commerce order status and the SOM status.

<!-- document id=18ef1d0d1ccc1ac53433554cd9dc3a05d2745deaa640c714211260aad35355f6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/scriptprogramming/integratingwithapplications.md -->

# Integrating with Applications

Integrate external applications with B2C Commerce using data exchange protocols.

| Data Exchange Protocol                      | Description                                                                                                                                                                                                             |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| WSDL 1.0 (Web Services Definition Language) | XML format that lets service interfaces be described, along with the details of their binds to specific protocols. Used to generate server and client code and for configuration.                                       |
| SOAP 1.1 (Simple Object Access Protocol)    | XML-based, extensible message envelope format, with 'bindings' to underlying protocols (for example, HTTP, SMTP and XMPP).                                                                                              |
| Remote Procedure Calls (RPC)                | Presents a distributed function (or method) call interface. Typically the base unit of RPC Web Services is the WSDL operation.                                                                                          |
| Document style Web Service                  | Supported in the _unwrapped_ mode                                                                                                                                                                                       |
| HTTP or HTTPS protocol                      | B2C Commerce supports many types of URLs and can transfer various content.                                                                                                                                              |
| File Transfer Protocol (FTP)                | Supports upload and download of files on the back-end such as XML and CSV, with B2C Commerce acting as an FTP client.                                                                                                   |
| SMTP                                        | Email can be sent from B2C Commerce to other systems.                                                                                                                                                                   |
| WebDAV                                      | Administrators and developers use WebDAV to manage files and folders on B2C Commerce servers.                                                                                                                           |
| HTML UI                                     | Business Manager provides an HTML user interface to manage system data and to upload and download data feeds, product images, and other static content. More HTML interfaces might be implemented for user interaction. |
| URLs                                        | External systems can call B2C Commerce URLs.                                                                                                                                                                            |

<!-- document id=8888adfe9faaf74e817e70d6bb263a54d9600cd8adf68bf9cf2053ff0f8a2b2f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2c-comm-integration-arch.md -->

# Integration Architecture for B2B Stores (LWR)

A predefined set of flows simplifies package integration for tax, shipping, and payment providers for B2B stores created with an LWR template. The integrations are embedded into the cart and checkout experience, triggered by shopper interactions with the storefront UI.

**note:** In the Winter ‘24 release, we introduced Commerce extensions for pricing, inventory, shipping, taxes, and other services. While the checkout integrations framework is still supported, we recommend extensions over integrations because they offer more targeted customizations for your B2B or B2C store. Plus, they’re available for more Commerce domains. See [Get Started With Salesforce Commerce Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extensions.html).

B2B and B2C stores created with an LWR template support these third-party integration points and flows.

- Shipping—Calculates and writes shipping costs per delivery group.
- Taxes—Calculates and adds tax prices for cart items.
- Payment—Uses the Salesforce Payment Adapter framework to fetch tokens and authorizations (and manage exceptions, such as fraud and insufficient credit) from service providers during checkout via a Payments Gateway. The integrated Salesforce Order Management module handles additional services, including capture and refund.

Here’s how the various components work together to form the integration engine.

![Diagram of B2B2C integration framework.](https://developer.salesforce.com/media/d2c-commerce/b2b2c_integration_architecture.png)

A predefined set of flows manages shipping, inventory, pricing, and tax integrations.

1.  Cart and checkout processing—Entering a delivery address initiates shipping charges and tax calculation. Order placement triggers payment processing. An integrated Salesforce Order Management component processes refund, capture, and more.
2.  Connect REST API—Service for these discrete APIs. Shipping, tax, and payment integrations execute tasks asynchronously and are distinct from the Salesforce B2B Checkout subflows implementation for a store built with the Aura template.
3.  Task handler—The task handler is implemented as an MQ (Message Queue) handler and invoked by the queue manager when the integration task is picked up for processing. The integration handler is responsible for delegating the task to the integration implementation, which the Commerce Admin or Merchandiser specifies when setting up the store.
4.  Handler factory—Responsible for creating an integration handler that maps to the implementation chosen by the Commerce Admin during store setup.
5.  Integration services—Using the store’s configured named credentials, a gateway conveys requests for third-party tax and shipping calculations. The CCS (Core Commerce Services) Adapter and Service Salesforce Payment Adapter request and receive authorizations, tokens, and exceptions from a third-party service via a Payments Gateway.
6.  API responses—Successful results and exceptions with customer-facing help messages are returned to the shopper’s browser.

<!-- document id=b1c693a686f2c73f405a49c854ce090907de5eaabed859754640921c50a24b9d url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/integration-fundamentals.md -->

# Integration Fundamentals

Use standards, error handling, and data schemas to implement the specs found in the [Reference](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html) tab.

## In this section

- [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)
- [SPI Error Handling Codes](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-spi-error-handling.html)
- [JSON Sample Payloads & Schemas](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/json-sample-payloads-schemas.html)
- [Tender Types Attributes in JSON/XML](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tender-types-attributes-in-jsonxml.html)
- [Set Up Callback URL for Payment Gateway Integrations](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/callback-url-for-payment-gateway-integrations.html)
- [Monitoring Webhook and SPI Integration Health](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/monitor-webhook-spi-integration-health.html)
- [Configure Monitoring for SPIs and Webhooks in CMS](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-webhook-monitoring.html)

## See also

- [Set Up Salesforce Integrations](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_sf_int.htm) in _Salesforce Help_
- [Point of Sale eComm Integration Guide](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_pay_gate_integrate_guide.htm) in _Salesforce Help_
- [NetSuite Integration Guide](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_3p_int_erp_netsuite_guide.htm) in _Salesforce Help_

<!-- document id=5ea602098dd138ff21100faeb9525bc22e66a29a2ab93acba0373dcbdcdf7b6f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-integration-architecture.md -->

# Integrations

B2B Commerce integration points are embedded into the cart and checkout experience. The integration services work across B2B stores.

**note:** In the Winter ‘24 release, we introduced Commerce extensions for pricing, inventory, shipping, taxes, and other services. While the checkout integrations framework is still supported, we recommend extensions over integrations because they offer more targeted customizations for your B2B store. Plus, they’re available for more Commerce domains. See [Get Started With Salesforce Commerce Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extensions.html).

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

<!-- document id=9fdf310646a77f28bff9f5100775838664f29bf3b89807aa7c8d2c310b81189f url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-intl.md -->

# Internationalization (i18n)

Storefront Next uses `i18next` with `remix-i18next` to support multiple languages and currencies, with runtime switching that doesn't require a page reload. A server-side instance handles server-side rendering (SSR) with full translation access, while a client-side instance loads translations as static JavaScript chunks, keeping server and client in sync without hydration mismatches.

## Prerequisites

- **Node.js 24+** and **pnpm** installed
- Project dependencies installed (`pnpm install`) — `i18next` and `remix-i18next` are included
- At least one translation file at `src/locales/[locale]/translations.json` (e.g., `src/locales/en-GB/translations.json`)
- For extension translations: run `pnpm dev` or `pnpm build` once to generate the aggregated files under `src/extensions/locales/`. These files are auto-generated and must not be edited manually.

## Quick Start

React components use the `useTranslation` hook. Everything else uses the `getTranslation` function.

For React Components:

```typescript
import { useTranslation } from "react-i18next";

function MyComponent() {
  const { t } = useTranslation("product");
  return <h1>{t("title")}</h1>;
}
```

For everything else (loaders, actions, utilities, helpers, tests):

```typescript
import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";

// Client-side or non-component code
const { t } = getTranslation();
const message = t("product:title");

// Server-side (loaders/actions) - pass the context
export function loader(args: LoaderFunctionArgs) {
  const { t } = getTranslation(args.context);
  return { title: t("product:title") };
}
```

## Architecture Overview

The i18n layer is split between the **SDK** and the **template**:

- **SDK (`@salesforce/storefront-next-runtime/i18n`)** — generic infrastructure: middleware factory, context, shared interpolation config
- **SDK (`@salesforce/storefront-next-runtime/i18n/client`)** — browser-only client initialization
- **Template** — translations (`src/locales/`), configuration, type augmentation, root.tsx wiring

We maintain 2 separate instances of i18next:

1. **Server-side instance**: Has access to _all_ translations for the entire site
2. **Client-side instance**: Dynamically imports translations as static JavaScript chunks

Both instances support **dynamic language switching** at runtime without page reloads.

### Server-side and Client-side Flow

1. Server-side middleware detects the user locale and initializes i18next
2. Server has access to all translations from all locales and renders SSR content with translations
3. Client-side initializes its own i18next instance, reading the language from the HTML `lang` attribute to prevent hydration mismatches
   - The `initI18next()` function in `root.tsx` accepts an optional `{ language }` parameter to ensure consistency between server and client
4. When a translation is first requested, the client dynamically imports ALL translations for the current language
   - This triggers an HTTP request for a JavaScript chunk (e.g., `/assets/locales-en-[hash].js`)
   - The chunk is served as a **static asset** (pre-built, minified, and cached with long-term headers)
   - Much more efficient than an API endpoint: no server processing, CDN-friendly, immutable caching
5. All namespaces for that language are loaded and cached in memory
6. Subsequent translation requests use the cached data (no additional requests)
7. When users switch languages, the client loads the new language's translations dynamically (if not already cached) and updates the UI immediately

## File Structure

```
src/locales/
├── index.ts                # Exports all language resources
├── en-GB/
│   ├── index.ts            # Exports English translations
│   └── translations.json   # All English translations (namespaced)
└── es-MX/
    ├── index.ts            # Exports Spanish translations
    └── translations.json   # All Spanish translations (namespaced)

src/extensions/
├── my-extension/
│   └── locales/
│       ├── en/
│       │   └── translations.json   # Extension translations (English)
│       └── es/
│           └── translations.json   # Extension translations (Spanish)
└── locales/                # Auto-generated (do not edit manually)
    ├── en/
    │   └── index.ts        # Aggregated extension translations
    └── es/
        └── index.ts        # Aggregated extension translations

src/components/
└── locale-switcher/
    └── index.tsx           # Client component for switching languages

src/middlewares/
└── i18next.server.ts       # Thin wrapper around SDK's createI18nMiddleware()

src/routes/
└── action.set-locale.ts    # Server action to persist locale preference
```

The i18n utilities (`getTranslation`, `getLocale`, `mockI18nContext`, `createI18nMiddleware`, `initI18next`) are provided by the SDK and split across two subpaths:

- `@salesforce/storefront-next-runtime/i18n` — server-capable APIs (`getTranslation`, `getLocale`, `mockI18nContext`, `createI18nMiddleware`). Safe to import from server modules, route modules, and components.
- `@salesforce/storefront-next-runtime/i18n/client` — **browser-only** APIs (`initI18next`). This entry pulls in `i18next-browser-languagedetector`, which has no Node support, so it must only be imported from client-side code (e.g. inside `useEffect` in `root.tsx`). Importing it from a `*.server.ts` file will fail to bundle and is blocked by the linter (OxLint `no-restricted-imports`).

They don't live in `src/lib/` anymore.

## Configuration

### Supported Languages and Currencies

Languages and currencies are configured in multiple places that must be kept in sync:

**1. `config.server.ts`** - Application-level configuration:

```typescript
site: {
    locale: 'en-GB',
    currency: 'GBP',
    supportedLocales: [
        {
            id: 'en-GB',
            preferredCurrency: 'GBP',
        },
        {
            id: 'es-MX',
            preferredCurrency: 'MXN',
        },
        // Add more locales here...
    ],
    // Currencies that users can manually select
    supportedCurrencies: ['MXN', 'GBP'],
},
i18n: {
    fallbackLng: 'en-GB',
    supportedLngs: ['es-MX', 'en-GB'], // Your supported languages
}
```

**2. `src/middlewares/i18next.server.ts`** reads `supportedLngs` and `fallbackLng` from config automatically — no additional middleware configuration is needed.

> **⚠️ IMPORTANT**: Keep these configurations in sync. Make sure that:
>
> - The locales in `i18n.supportedLngs` match the `id` values in `site.supportedLocales` (single-site) or across all entries in `commerce.sites[]. supportedLocales` (multi-site).
> - Each locale in `supportedLocales` has a `preferredCurrency` that matches one of the `site.supportedCurrencies` or site's `supportedCurrencies`.
> - Each locale in `i18n.supportedLngs` has a corresponding translation directory under `src/locales/`.
> - If you add a new language, update both places and create the translation files.

**Currency System:**

The application supports independent locale and currency switching:

1. Locale-based currency: Each locale in `commerce.sites[].supportedLocales` has a `preferredCurrency` that's used by default.
2. Manual currency selection: Users can manually select any currency from `commerce.sites[].supportedCurrencies`, which takes precedence over the locale's preferred currency.
3. Currency priority: User's manual selection (cookie) → Locale's preferred currency → Site's default currency.

See the Currency Switcher component in `src/components/currency-switcher/` for the implementation.

### Locale Detection

The middleware automatically detects the user's locale from:

1. The `lng` cookie (if previously set)
2. The `Accept-Language` HTTP header
3. Falls back to the configured `fallbackLng`

### Switching Languages and Currencies at Runtime

#### Language Switching

Users can switch languages dynamically without reloading the page using the `LocaleSwitcher` component. The language change happens in two steps:

1. **Client-side update**: Immediately changes the displayed language using i18next's `changeLanguage()` method
2. **Server-side persistence**: Submits to a server action that sets the `lng` cookie to persist the preference across page reloads

**Using the LocaleSwitcher Component:**

The project includes a pre-built `LocaleSwitcher` component that you can drop into your UI:

```typescript
import LocaleSwitcher from "@/components/locale-switcher";

export function Footer() {
  return (
    <footer>
      {/* Other footer content */}
      <LocaleSwitcher />
    </footer>
  );
}
```

#### Currency Switching

Users can manually select a currency independent of their locale using the `CurrencySwitcher` component. When a new currency is switched:

1. Server submits an server action.
2. Middlewares (client and server) run to update latest currency into context.
3. `updateBasket` is called to SCAPI to update currency accordingly.
4. Loader func will revalidate and update the UI to reflect the selected currency.

**Using the CurrencySwitcher Component:**

```typescript
import CurrencySwitcher from "@/components/currency-switcher";
import LocaleSwitcher from "@/components/locale-switcher";

export function Footer() {
  return (
    <footer>
      <div>
        <h3>Language</h3>
        <LocaleSwitcher />
      </div>
      <div>
        <h3>Currency</h3>
        <CurrencySwitcher />
      </div>
    </footer>
  );
}
```

**Key Points:**

- Currency selection is **independent** of locale
- Manual currency selection **takes precedence** over locale's preferred currency
- The preference persists across locale changes
- Falls back to locale's preferred currency if no manual selection is made

**Building Your Own Language Switcher:**

If you need a custom implementation, here's how to implement language switching:

```typescript
"use client";

import { useTranslation } from "react-i18next";
import { useFetcher } from "react-router";

export function MyLanguageSwitcher() {
  const { i18n } = useTranslation();
  const fetcher = useFetcher();

  const handleLanguageChange = async (newLocale: string) => {
    // Step 1: Change language client-side for immediate UX
    await i18n.changeLanguage(newLocale);

    // Step 2: Persist to server cookie for page reloads
    const formData = new FormData();
    formData.append("locale", newLocale);
    void fetcher.submit(formData, {
      method: "POST",
      action: "/action/set-locale",
    });
  };

  return (
    <select value={i18n.language} onChange={(e) => void handleLanguageChange(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Spanish</option>
    </select>
  );
}
```

**How It Works:**

The `/action/set-locale` server action (located at `src/routes/action.set-locale.ts`) receives the POST request and sets the `lng` cookie using the same cookie object that the middleware uses for detection:

```typescript
import { data, type ActionFunction } from 'react-router';
import { localeCookie } from '@/middlewares/i18next.server';

export const action: ActionFunction = async ({ request }) => {
    const formData = await request.formData();
    const locale = formData.get('locale') as string;

    if (!locale) {
        throw new Response('Locale is required', { status: 400 });
    }

    const cookieHeader = await localeCookie.serialize(locale);

    return data(
        { success: true },
        {
            headers: {
                'Set-Cookie': cookieHeader,
            },
        }
    );
};
```

**Key Points:**

- Language changes are immediate (no page reload required)
- The preference persists across sessions via the `lng` cookie
- All client-side translations are loaded as static assets (one JavaScript chunk per language)
- Switching languages triggers the dynamic import of the new language's translations if not already loaded

## Usage Examples

### In React Components

Use the [`useTranslation`](https://react.i18next.com/latest/usetranslation-hook) hook from `react-i18next`:

```typescript
import { useTranslation } from "react-i18next";

function ProductInfo() {
  // Specify the namespace to load
  const { t } = useTranslation("product");
  // NOTE: without passing in a namespace, the above hook would use `translation` namespace by default.
  // Since we don't have such namespace in our translations, the `t('namespace:key')` would still work,
  // but its autocomplete would no longer work in your IDE.

  return (
    <div>
      <h1>{t("title")}</h1>
      <p>{t("description")}</p>
      <button>{t("addToCart")}</button>
    </div>
  );
}
```

**With multiple namespaces:**

```typescript
import { useTranslation } from "react-i18next";

function ProductPage() {
  // Load multiple namespaces at once
  const { t } = useTranslation(["home", "product"]);

  return (
    <div>
      <h1>{t("home:title")}</h1>
      <p>{t("product:description")}</p>
      <button>{t("product:addToCart")}</button>
    </div>
  );
}
```

**With interpolation:**

```typescript
const { t } = useTranslation("cart");
const message = t("itemCount.other", { count: 5 }); // "Cart (5 items)"
```

**With pluralization:**

```typescript
const { t } = useTranslation("cart");
const text = t("summary.itemsInCart", { count: 1 }); // "1 item in cart"
const text2 = t("summary.itemsInCart", { count: 3 }); // "3 items in cart"
```

### In Non-Component Code

Use the `getTranslation` utility for tests, utilities, or any non-React code:

```typescript
import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";

// In tests
describe("ActionCard", () => {
  const { t } = getTranslation();

  test("shows edit button", () => {
    render(<ActionCard onEdit={vi.fn()} />);
    const button = screen.getByRole("button", { name: t("actionCard:edit") });
    expect(button).toBeInTheDocument();
  });
});

// In utility functions
export function getCountryName(countryCode: string): string {
  const { t } = getTranslation();
  return t(`countries:${countryCode}.name`, { defaultValue: countryCode });
}

// In form schemas (for Zod error messages)
const schema = z.object({
  email: z.string().email(t("error:validation.invalidEmail")),
});
```

### In Route Loaders and Actions (Server-side)

Use `getTranslation` with the context parameter for server-side translations:

```typescript
import { getTranslation, i18nextContext } from "@salesforce/storefront-next-runtime/i18n";
import type { LoaderFunctionArgs } from "react-router";

export function loader(args: LoaderFunctionArgs) {
  // Get translations by passing the context
  const { t } = getTranslation(args.context);
  const translatedTitle = t("product:title");

  // Get the current locale for formatting (if needed)
  const i18nextData = args.context.get(i18nextContext);
  const locale = i18nextData?.getLocale() ?? "en-GB";
  const date = new Date().toLocaleDateString(locale, {
    year: "numeric",
    month: "2-digit",
    day: "2-digit",
  });

  return { translatedTitle, date };
}
```

**In actions with error handling:**

```typescript
import type { ActionFunctionArgs } from "react-router";
import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";

export async function action(args: ActionFunctionArgs) {
  const { t } = getTranslation(args.context);

  try {
    // ... perform action
    return { success: true, message: t("product:addedToCart", { productName: "Widget" }) };
  } catch (error) {
    return { success: false, message: t("error:api.unexpectedError") };
  }
}
```

## Adding New Translations

### Approach: Single JSON File Per Language

All translations are stored in a **single JSON file per language** with namespace-based organization.

#### Understanding Namespaces

i18next uses the concept of **namespaces** to organize translations into logical groups. In our implementation, namespaces are simply the **top-level keys** in each `translations.json` file. For example, `"common"`, `"product"`, `"checkout"`, and `"myNewFeature"` are all namespaces that help organize translations by feature or domain.

Core app namespaces use the camelCase naming convention, for example `checkout` or `miniCart`.

**src/locales/en/translations.json:**

```json
{
  "common": {
    "loading": "Loading",
    "product": "the product"
  },
  "product": {
    "title": "Product Details",
    "addToCart": "Add to Cart",
    "greeting": "Hello, {{name}}!",
    "itemCount": {
      "zero": "No items",
      "one": "{{count}} item",
      "other": "{{count}} items"
    }
  },
  "myNewFeature": {
    "welcome": "Welcome to the new feature"
  }
}
```

**src/locales/es/translations.json:**

```json
{
  "common": {
    "loading": "Cargando",
    "product": "el producto"
  },
  "product": {
    "title": "Detalles del Producto",
    "addToCart": "Agregar al Carrito",
    "greeting": "¡Hola, {{name}}!",
    "itemCount": {
      "zero": "Sin artículos",
      "one": "{{count}} artículo",
      "other": "{{count}} artículos"
    }
  },
  "myNewFeature": {
    "welcome": "Bienvenido a la nueva función"
  }
}
```

### Using Your New Translations

```typescript
// In React components
const { t } = useTranslation('myNewFeature');
<p>{t('welcome')}</p>

// In non-component code
const { t } = getTranslation();
const message = t('myNewFeature:welcome');

// Simple translation
<p>{t('title')}</p>

// With interpolation
<p>{t('greeting', { name: 'John' })}</p>

// With pluralization
<p>{t('itemCount', { count: items.length })}</p>
```

## Extension Translations

Extensions can have their own translation files that are automatically discovered and integrated into the i18n system. This allows extension authors to keep translations co-located with their extension code.

### File Structure for Extensions

Create translation files within your extension directory following this structure:

```
src/extensions/
├── my-extension/
│   ├── components/
│   ├── locales/
│   │   ├── en/
│   │   │   └── translations.json
│   │   └── es/
│   │       └── translations.json
│   └── index.ts
```

### Namespace Convention

Extension translations automatically use the `extPascalCase` naming convention based on the extension folder name:

- `store-locator` → `extStoreLocator`
- `bopis` → `extBopis`
- `my-extension` → `extMyExtension`

This convention prevents namespace collisions between extensions and core application translations.

### How Locale Discovery Works

**Important**: The locale aggregation command (`sfnext locales aggregate-extensions`) is specifically for **extension translations only**. Main app translations in `/src/locales/` are NOT aggregated by this command—they are imported directly.

The command scans **two locations** to discover all supported locales:

1. **Main app locales**: `/src/locales/{locale}/`
2. **Extension locales**: `/src/extensions/{extension-name}/locales/{locale}/`

The command merges locales from both sources and generates **extension-only** aggregation files under `/src/extensions/locales/` for each discovered locale. This means:

- If your main app supports Spanish (`es-MX`) but none of your extensions have Spanish translations, an empty aggregation file is still generated for `es-MX`
- If an extension provides translations for a locale not in the main app, those translations are still aggregated (though the main app won't use them unless configured)
- Extensions without a `locales` folder are automatically skipped - no error is thrown

**Example scenario:**

- Main app: `en-GB`, `es-MX`, `fr-FR` translations
- Extension A: `en-GB`, `es-MX` translations
- Extension B: `en-GB` translations only
- Extension C: No `locales` folder

**Result:** Extension aggregation files generated in `/src/extensions/locales/` for `en-GB`, `es-MX`, and `fr-FR`:

- `en-GB/index.ts`: Contains Extension A + Extension B translations only
- `es-MX/index.ts`: Contains Extension A translations only
- `fr-FR/index.ts`: Empty (no extensions have it)

**Note:** Main app translations remain in `/src/locales/` and are not affected by this aggregation process.

### Adding Translations to an Extension

**1. Create the translation files:**

Create `locales/{lang}/translations.json` within your extension directory for each supported language.

**Example: `src/extensions/bopis/locales/en/translations.json`**

```json
{
  "deliveryOptions": {
    "title": "Delivery:",
    "pickupOrDelivery": {
      "shipToAddress": "Ship to Address",
      "pickUpInStore": "Pick Up in Store"
    }
  },
  "storePickup": {
    "title": "Store Pickup Location",
    "viewButton": "View",
    "closeButton": "Close"
  }
}
```

**2. Translations are automatically aggregated:**

When you run `pnpm dev` or `pnpm build`, the system automatically:

- Discovers all extension translation files
- Aggregates them with the appropriate namespace
- Makes them available to your extension code

No manual configuration is required.

### Using Extension Translations

**In React Components:**

```typescript
import { useTranslation } from "react-i18next";

export function DeliveryOptions() {
  // Use your extension's namespace
  const { t } = useTranslation("extBopis");

  return (
    <div>
      <h3>{t("deliveryOptions.title")}</h3>
      <button>{t("deliveryOptions.pickupOrDelivery.pickUpInStore")}</button>
    </div>
  );
}
```

**In Non-Component Code:**

```typescript
import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";

export function getDeliveryMessage() {
  const { t } = getTranslation();
  // Use namespace prefix with colon
  return t("extBopis:deliveryOptions.title");
}
```

**In Route Loaders/Actions:**

```typescript
import { getTranslation } from "@salesforce/storefront-next-runtime/i18n";
import type { LoaderFunctionArgs } from "react-router";

export function loader(args: LoaderFunctionArgs) {
  const { t } = getTranslation(args.context);
  return {
    message: t("extBopis:storePickup.title"),
  };
}
```

## Using a Different i18n Library

The SDK's i18n support (`@salesforce/storefront-next-runtime/i18n`) is built on i18next. If you prefer a different library (for example, `next-intl`, `formatjs`, `lingui`), you can replace the i18n layer entirely:

1. **Skip the SDK's i18n subpath**: Don't import from `@salesforce/storefront-next-runtime/i18n` or `@salesforce/storefront-next-runtime/i18n/client`.
2. **Locale resolution still works**: The site-context system (`createSiteContextMiddleware`, locale detection from URL/cookie/header, `SiteProvider`) is i18n-library-agnostic and handles determining the active locale.
3. **Write your own middleware**: Replace `src/middlewares/i18next.server.ts` with a middleware that initializes your chosen library, reading the resolved locale from `requestToLocaleMap` (exported from `@salesforce/storefront-next-runtime/site-context`).
4. **Write your own client init**: Replace the `initI18next()` call in `root.tsx` with your library's initialization.
5. **Bridge to SiteProvider**: Pass the current language string to `SiteProvider`'s `language` prop (it accepts a plain `string`, no i18next dependency).
6. **Chunk splitting still works**: The Vite `i18nPlugin` splits any files matching `/src/locales/([^/]+)/` into per-language chunks, regardless of i18n library.

The SDK separates **locale resolution** (which locale is active) from **translation** (turning keys into strings). Only the translation layer is i18next-specific.

## Best Practices

1. **Namespace by Route/Feature**: Organize translations by feature area (e.g., `product`, `checkout`, `account`)
2. **Use the Right Tool**:
   - **React components**: Use `useTranslation()` hook
   - **Everything else**: Use `getTranslation()` function
     - Non-component code (tests, utilities, schemas): `getTranslation()`
     - Server-side loaders/actions: `getTranslation(context)`
3. **Use TypeScript**: The project includes type-safe translations based on the English locale
4. **Interpolation**: Use `{{variable}}` syntax in translation strings (not `{variable}`)
5. **Pluralization**: Use nested objects with `zero`, `one`, `other` keys for count-based translations
6. **Lazy Loading**: Client-side translations are loaded on-demand when first requested
7. **Fallback Chain**: Missing translations fall back to the configured `fallbackLng` (English)

## Type Safety

The project is configured for type-safe translations. TypeScript will autocomplete available keys and warn about missing translations:

```typescript
// ✅ TypeScript knows these keys exist
const { t } = useTranslation("product");
t("title");
t("addToCart");

// With namespace prefix in non-component code
const { t } = getTranslation();
t("product:title");
t("cart:empty.title");

// ❌ TypeScript will warn about this
t("nonexistent.key");
```

Type definitions are generated from the English locale (`resources['en-GB']`) in `src/middlewares/i18next.server.ts`:

```typescript
declare module "i18next" {
  interface CustomTypeOptions {
    resources: typeof resources["en-GB"]; // Use `en-GB` as source of truth for the types
  }
}
```

<!-- document id=8876b1af40f3ed7d725fc010586f85f87a61f9f5fb77a2bae7f3cb4c2cdcbd59 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/d2c-comm-extensions-intro.md -->

# Introduction to Commerce Extensions

The Salesforce Commerce Extensions Developer Guide provides comprehensive documentation and resources for developers looking to extend and customize their Salesforce Commerce solution. With a focus on flexibility and scalability, this guide empowers developers to enhance the functionality of their commerce platform, integrate with services, and tailor the shopping experience to meet specific business needs.

<!-- document id=f17acfe1bb2f31975a294323ac15b5acc1f28f22ae592348caf12328a32e1e02 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/intro.md -->

# Introduction to Composable Storefront

Wondering what our headless solution can do for your site? This section gives you more details about its key features. We'll highlight the functionality that can help you create, customize, and optimize your site. Get ready to discover how Composable Storefront can simplify your ecommerce journey. This section contains the following guides.

- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.md)
- [Headless Commerce with Salesforce Commerce API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-scapi.md)
- [Progressive Web App (PWA) Kit Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-kit-overview.md)
- [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.md)
- [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.md)
  - Tutorial: [Manage Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.html#tutorial)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/developer-workflow.html)
- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)

<!-- document id=319e2c520464b092f88e5571cc83142f102e72497945b2162cea32adce014630 url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-inventory.md -->

Inventory

# Inventory

Inventory is a way to group a seller’s stock. When correctly configured, there should only be 1 inventory per seller, with any others being ignored.

It is recommended that, when configuring the seller, the marketplace should set up the inventory with the correct external ID, but this configuration can be achieved by means of API integration.

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### GET Query

`GET /services/data/v51.0/query`

Operation ID: `Query`. Tags: Inventory. Security: bearerAuth.

To look up information about inventory, use the [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) resource of the main REST API from Salesforce and set the value of the `q` parameter to an SOQL query. The following examples are included in the query parameters section of this page, with corresponding examples in the responses section:

**Example 1 of 2**: `getInventoryBySellerId`

This call allows the seller’s inventory information to be searched. If you do not know the External ID of the inventory, this call can be used to search for this information.

**Example 2 of 2**: `getInventoryRecordsByInventoryId`

This call allows the listing of the stock of all SKUs within a specific inventory using the External ID. Depending on the quantity, the results may require pagination.

#### Parameters

*   `q` (query, string)
    
    _Example: getInventoryBySellerId_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__Inventory__c WHERE Atonit_Mktplace__Seller__r.Atonit_Mktplace__Slug__c= '{{seller-external-id}}' LIMIT 200
    ```
    
    _Example: getInventoryRecordsByInventoryId_
    
    ```
    SELECT Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Inventory__r.Atonit_Mktplace__External_Id__c, Atonit_Mktplace__Product_Variant__r.Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Quantity__c  FROM Atonit_Mktplace__Inventory_Record__c WHERE Atonit_Mktplace__Inventory__r.Atonit_Mktplace__External_Id__c= '{{seller-api-prefix}}-inventory' LIMIT 200
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 19:04:51 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1456/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example: getInventoryBySellerId_
    
    ```
    {
      "totalSize": 1,
      "done": true,
      "records": [
        {
          "Id": "a0A5Y00001JJoqmUAD",
          "Name": "W-0000",
          "CreatedDate": "2021-03-22T21:39:57.000+0000",
          "LastModifiedDate": "2021-04-22T19:22:50.000+0000",
          "Atonit_Mktplace__Name__c": "atonit-vitta-inventory",
          "Atonit_Mktplace__Seller__c": "a0T5Y00000ZE4lFUAT",
          "Atonit_Mktplace__External_Id__c": "atonit-vitta-inventory"
        }
      ]
    }
    ```
    
    _Example: getInventoryRecordsByInventoryId_
    
    ```
    {
      "example": {
        "totalSize": 5,
        "done": true,
        "records": [
          {
            "Atonit_Mktplace__External_Id__c": "atonit-vitta-inventory-atonit-vitta-sku-1",
            "Atonit_Mktplace__Inventory__r": {
              "Atonit_Mktplace__External_Id__c": "atonit-vitta-inventory"
            },
            "Atonit_Mktplace__Product_Variant__r": {
              "Atonit_Mktplace__External_Id__c": "atonit-vitta-sku-1"
            },
            "Atonit_Mktplace__Quantity__c": 88
          }
        ]
      }
    }
    ```
    

### GET Get Inventory by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Inventory__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-inventory`

Operation ID: `Get Inventory by ID`. Tags: Inventory. Security: bearerAuth.

This call will load all available inventory information using the External ID as the key

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 19:08:17 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1458/101002`.
    *   `Last-Modified` (string)  
        Example: `Thu, 22 Apr 2021 19:22:50 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a0A5Y00001JJoqmUAD",
      "Name": "W-0000",
      "CreatedDate": "2021-03-22T21:39:57.000+0000",
      "LastModifiedDate": "2021-04-22T19:22:50.000+0000",
      "Atonit_Mktplace__Name__c": "atonit-vitta-inventory",
      "Atonit_Mktplace__Seller__c": "a0T5Y00000ZE4lFUAT",
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-inventory"
    }
    ```
    

### PATCH Create or Update Inventory

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Inventory__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-inventory`

Operation ID: `Create or Update Inventory`. Tags: Inventory. Security: bearerAuth.

This call allows you both to create and update the seller’s inventory. If an inventory already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

Take care at all times not to create more than 1 inventory for the seller, otherwise the integration will not work properly.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Name__c": "{{seller-api-prefix}}-inventory",
  "Atonit_Mktplace__Seller__r": {
    "Atonit_Mktplace__Slug__c": "{{seller-external-id}}"
  }
}
```

#### Responses

*   **200** Successful response
    
    Media type: `application/json`.
    

### GET Get Inventory Record by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Inventory_Record__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-inventory-{seller-api-prefix}-sku-1`

Operation ID: `Get Inventory Record by ID`. Tags: Inventory. Security: bearerAuth.

This call will load all available stock information for an SKU using the External ID as the key

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 19:13:09 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1461/101002`.
    *   `Last-Modified` (string)  
        Example: `Fri, 23 Apr 2021 19:10:19 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a095Y00001B5JLrQAN",
      "Name": "IR-0015",
      "CreatedDate": "2021-04-22T19:43:03.000+0000",
      "LastModifiedDate": "2021-04-23T19:10:19.000+0000",
      "Atonit_Mktplace__Inventory__c": "a0A5Y00001JJoqmUAD",
      "Atonit_Mktplace__Product_Variant__c": "a0L5Y00000oAUQDUA4",
      "Atonit_Mktplace__Quantity__c": 88,
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-inventory-atonit-vitta-sku-1"
    }
    ```
    

### PATCH Create or Update Inventory Record

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Inventory_Record__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-inventory-{seller-api-prefix}-sku-1`

Operation ID: `Create or Update Inventory Record`. Tags: Inventory. Security: bearerAuth.

This call allows you both to create and update an SKU in the seller’s inventory. If stock already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must be in the format `<id-inventory>-<id-sku>`.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Inventory__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-inventory"
  },
  "Atonit_Mktplace__Product_Variant__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-sku-1"
  },
  "Atonit_Mktplace__Quantity__c": 88
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 19:10:19 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1459/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Inventory_Record__c/a095Y00001B5JLrQAN`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a095Y00001B5JLrQAN",
      "success": true,
      "errors": [],
      "created": false
    }
    ```

<!-- document id=f3ed0b4fccc6e064b4a9e86b542272cce0806fc90b665ffa29d2c5df7c26e397 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/inventory-fulfillment.md -->

# Inventory

Check product availability on the POS, look up inventory on the product detail page, and subscribe to inventory event webhooks.

## In this section

- [Lookup Inventory on PDP via SPIs](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/inventory-lookup-on-pdp-via-spis.html)
- [Confirm Product Inventory (Live Inventory Check)](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-live-inventory-check.html)
- [Inventory Event Webhooks](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/inventory-event-webhooks.html)

<!-- document id=980509044aebae8ab7a4d3a762457c8770a6cae97f8b213634e56bf610555002 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/inventory-availability.md -->

Inventory Availability (OCI)

# Inventory Availability (OCI)

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/inventory-availability/availability-oas-v1-public.yaml)

## API Overview

Inventory Availability APIs enable you to get inventory availability and perform inventory updates within Omnichannel Inventory.

Inventory Availability API can be segregated into the following functional categories:

| Category | Endpoint Description |
| --- | --- |
| Inventory Availability | API endpoints for getting inventory SKU availability for groups and locations. You can query for multiple SKUs either by a single group or by multiple locations |
| Inventory Updates and Deletes | API endpoints for updating and deleting inventory availability for specific SKUs. |
| Deltas | API endpoint for reading the stream of changes that have occurred to SKUs in groups or locations. |

**Note**: Omnichannel Inventory uses the Tenant Group ID in place of the Organization ID. For more information, see [Configuration Values](https://developer.salesforce.com/docs/commerce/commerce-api/guide/commerce-api-configuration-values).

### Rate Limits

For load shedding and rate limiting information, see [Load Shedding and Rate Limiting.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html)

### Authentication and Authorization

Clients calling Omnichannel Inventory can be authenticated in one of two ways.

*   Authenticate using Account Manager with your B2C Commerce credentials.
*   Authenticate using your Salesforce org credentials.

If you are using both B2C Commerce and Salesforce Order Management, you can use either authentication approach. However, we recommend choosing only one to avoid mixing approaches across your integrations. The different authentication approaches do not impact the purpose or performance of the APIs. Each authentication approach uses a unique set of scopes.

| Scopes for Account Manager Authentication | Scopes for Salesforce org Authentication |
| --- | --- |
| sfcc.inventory.impex-graphs | sfcc\_inventory\_impex\_graphs |
| \--- | \--- |
| sfcc.inventory.impex-inventory.rw | sfcc\_inventory\_impex\_inventory\_rw |
| sfcc.inventory.impex-inventory | sfcc\_inventory\_impex\_inventory |
| sfcc.inventory.availability | sfcc\_inventory\_availability |
| sfcc.inventory.availability.rw | sfcc\_inventory\_availability\_rw |
| sfcc.inventory.reservations | sfcc\_inventory\_reservations |
| sfcc.inventory.reservations.rw | sfcc\_inventory\_reservations\_rw |

Calls through the API gateway to Omnichannel Inventory must have a valid OAUTH bearer token. The tenant identifier used by Omnichannel Inventory is supplied in the header of the token. All request and response body entities are composed in JSON.

### Use Cases

#### Inventory Availability

Use these API endpoints to get inventory SKU availability for groups and locations. You can query multiple SKUs either by a single group or by multiple locations.

##### Group Availability

Use this endpoint to retrieve inventory availability for a group identifier and multiple SKUs with the criteria specified as parameters of the URL. A successful response contains the item availability data for the requested group and SKUs

##### Location Availability

Use this endpoint to retrieve inventory availability for multiple location identifiers and SKUs with the criteria specified in the body of the request. A successful response contains the item availability data for the requested locations and SKUs

#### Inventory Updates and Deletes

Use these API endpoints to update and delete inventory availability for specific SKUs.

##### Updates

Use these endpoints to update inventory availability data for a single location or in a batch of locations.

##### Single Location

Use this endpoint to update inventory availability for a specific location identifier and SKU. The data to update is supplied in the body of the request.

##### Batch of Locations

Use this endpoint to update multiple locations and SKUS. The stream of item availability records is supplied in the body of the request.

##### Deletes

The client calls these endpoints to delete inventory availability data. Although the current values are reset, history is maintained.

##### Location

Use this endpoint to delete a SKU at a location with the criteria specified as URL parameters.

##### Group

Use this endpoint to delete a SKU at a group with the criteria specified as URL parameters.

#### Deltas

Use this endpoint to request inventory availability changes by providing a place identifier (for example, group or location) and a token as parameters of the URL. The response contains a stream of inventory availability data with the changes that have occurred since the token was created. Each successful response contains a _new_ token for the next delta call. There are multiple ways that you can generate a delta token. The first is through running an export process. See the Inventory Impex API for details on how to retrieve a delta token from the Inventory Export. A Delta token can also be created using the Create New Delta Token api call. See the Inventory Availability API documentation for details on that call.

It is strongly advised that when implementing the get deltas functionality, the calls for retrieving the delta information are collapsed into two streams. In the first stream, a delta token is created and then processed for all stand alone locations. In the second stream, a delta token is created and then processed for all location groups. These delta tokens are created using the Create New Delta Token API call mentioned above. You, as the caller, can then filter the results to process them and provide optimal performance when using the get deltas functionality.

When using the two-streams method outlined above, there may be times that the location graph is changed and a new delta token is required. In these cases, use the Upadte Delta Token API call outlined in the Inventory Availability API documentation. Using this update delta token call, you can add or remove locations or groups from an existing delta token, eliminating the previous requirement to perform an export to retrieve a new delta token.

#### Futures

Be advised that this API references Future inventory collections as `futures` and `futureStock`. These are the same thing. Also the Inventory Impex API references Future inventory collections as `futures`.

#### attributeSet

The attributeSet is a list of attributes that can be applied to an item to change it's behavior. An example of this is the `groupEligibilityExclusion` attribute, which allows you to apply an array of Groups that are excluded from aggregating the sku for a particular location.

### Common Response Codes

The following error codes apply to all API endpoints. See the API documentation for a complete list of the error codes and response bodies that can be expected on each endpoint.

*   401 - The OATH bearer token is not valid for the tenant or is no longer valid. The response body has the details.
*   403 - The tenant is not provisioned in the system.
*   5XX - There was a server error. The response body has the details.
*   Unknown - If an Unknown error type is returned, it indicates that an unknown internal error occurred.

### External Reference Identifier

Currently, there are a number of places where a consumer can submit an `ExternalRefId` with their request. This allows the consumer to submit user generated data along with their request as a link to other external systems data. For example, if you're pulling data from an order that has an order ID, you can submit that order ID with your reservation request as the `externalRefId`. Then, if there is a problem with the reservation, there is a way to connect it with the order in the external system that generated the error or problem. This is NOT to be confused with `externalRefId` used in Salesforce Core, or any other services. The usage is exclusive to OCI and is not used anywhere else.

### Correlation-ID

To facilitate operations tracking in Omnichannel Inventory, populate a header with the name Correlation-ID which will be passed through the CDN and sent with the request to OCI. This helps trace requests as they move through the service. To be accepted, Correlation-ID must be a valid UUIDv2 or it'll be ignored.

When a web-request is passed through the CDN, the CDN's x-correlation-id header value (which comes from their ray-id) also comes into play. In this case, the correlation-id provided is prepended to the CDN's x-correlation-id and both values are passed through, separated by a comma.

Some services use a header X-Correlation-ID. If this header is used with Omnichannel Inventory, it's overwritten by the CDN with a new value and the initial purpose of the header is defeated. Use the Correlation-ID instead for a consistent result.

**Version:** 1.1.31

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/inventory/availability/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.inventory.availability.rw: Inventory Availability scope
    *   Scope sfcc\_inventory\_availability\_rw: Inventory Availability scope
    *   Scope sfcc.inventory.availability: Inventory Availability scope READONLY
    *   Scope sfcc\_inventory\_availability: Inventory Availability scope READONLY
    *   Scope sfcc.inventory.impex-inventory.rw: Inventory Impex Inventory scope
    *   Scope sfcc\_inventory\_impex\_inventory\_rw: Inventory Impex Inventory scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.inventory.availability.rw: Inventory Availability scope
    *   Scope sfcc\_inventory\_availability\_rw: Inventory Availability scope
    *   Scope sfcc.inventory.availability: Inventory Availability scope READONLY
    *   Scope sfcc\_inventory\_availability: Inventory Availability scope READONLY
    *   Scope sfcc.inventory.impex-inventory.rw: Inventory Impex Inventory scope
    *   Scope sfcc\_inventory\_impex\_inventory\_rw: Inventory Impex Inventory scope

## Operations

### POST Create a new Delta Token.

`POST /organizations/{organizationId}/availability-records/delta-token`

Operation ID: `createNewDeltaToken`. Security: AmOAuth2 (sfcc.inventory.availability.rw, sfcc\_inventory\_availability\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `CreateNewDeltaTokenBody`.

_Example: CreateDeltaTokenGroups_

```
{
  "placeType": "GROUP",
  "places": [
    "UnitedStates"
  ]
}
```

_Example: CreateDeltaTokenLocations_

```
{
  "placeType": "LOCATION",
  "places": [
    "warehouse5"
  ]
}
```

#### Responses

*   **200** New Delta Token was created successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `CreateNewDeltaTokenResponse`.
    
    _Example: createNewDeltaToken200_
    
    ```
    {
      "deltaToken": "e3NoYXJkSWQtMDAwMDAwMDE1NzczOTkxNTc2MDItYmE5MGYxNGE6MDAwMDAwMDAwMDAwMDAwMDAwNDQ0fQ=="
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: createNewDeltaToken400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "places must be of type location or group",
      "parameterName": "places"
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Update a Delta Token stream.

`POST /organizations/{organizationId}/availability-records/delta-token/actions/update`

Operation ID: `updateDeltaToken`. Security: AmOAuth2 (sfcc.inventory.availability.rw, sfcc\_inventory\_availability\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `UpdateDeltaTokenBody`.

_Example: UpdateDeltaTokenGroups_

```
{
  "deltaToken": "e3NoYXJkSWQtMDAwMDAwMDE1NzczOTkxNTc2MDItYmE5MGYxNGE6MDAwMDAwMDAwMDAwMDAwMDAwNDQ0fQ==",
  "places": [
    "UnitedStates",
    "Canada"
  ]
}
```

#### Responses

*   **200** Delta Token stream updated successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `UpdateDeltaTokenResponse`.
    
    _Example: updateDeltaTokenSuccess_
    
    ```
    {
      "deltaToken": "e3NoYXJkSWQtMDAwMDAwMDE1NzczOTkxNTc2MDItYmE5MGYxNGE6MDAwMDAwMDAwMDAwMDAwMDAwNDQ0fQ==",
      "places": [
        "UnitedStates",
        "Canada"
      ]
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: updateDeltaToken400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "The delta token provided is invalid."
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: updateDeltaToken403_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **410** Delta Token link expired.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: updateDeltaToken410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredDeltaLink",
      "message": "The delta token provided has expired."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Update a batch of inventory items with one call.

`POST /organizations/{organizationId}/availability-records/actions/batch-update`

Operation ID: `batchInventoryUpdate`. Security: AmOAuth2 (sfcc.inventory.availability.rw, sfcc\_inventory\_availability\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `BatchInventoryUpdateRequest`.

_Example: BatchUpdateOneRecord_

```
{
  "records": [
    {
      "location": "warehouse5",
      "sku": "sku123",
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "onHand": 1200.35,
      "safetyStockCount": 12.45,
      "effectiveDate": "2025-05-19T21:13:00Z",
      "futureStock": [
        {
          "expectedDate": "2025-05-31T21:13:00Z",
          "quantity": 10.25
        }
      ],
      "attributeSet": {
        "groupEligibilityExclusion": [
          "GroupA"
        ]
      },
      "externalRefId": "7282822-9823-aaa"
    }
  ]
}
```

#### Responses

*   **200** Batch inventory updated successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `BatchInventoryUpdateErrors`.
    
    _Example: batchInventoryUpdate200_
    
    ```
    {
      "errors": [
        {
          "details": {
            "locationId": "warehouse5",
            "sku": "sku123",
            "id": "82251928-8863-488e-840b-2aebd10b57ba",
            "externalRefId": "7282822-9823-aaa"
          },
          "message": "Inventory record update failed",
          "errorCode": "InvalidRequest"
        }
      ]
    }
    ```
    
*   **204** Batch inventory updated successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: batchInventoryUpdate400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "Invalid characters in sku: bad$sku",
      "parameterName": "sku"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: batchInventoryUpdate403_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### PATCH Partially update a batch of inventory items with one call. Only fields that are included in the request will be updated.

`PATCH /organizations/{organizationId}/availability-records/actions/batch-update`

Operation ID: `batchInventoryPatch`. Security: AmOAuth2 (sfcc.inventory.availability.rw, sfcc\_inventory\_availability\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `BatchInventoryUpdateRequest`.

_Example: BatchInventoryPatchRequest_

```
{
  "records": [
    {
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "externalRefId": "7282822-9823-aaa",
      "location": "warehouse5",
      "sku": "sku123",
      "onHand": 1200.35,
      "safetyStockCount": 12.45,
      "effectiveDate": "2025-05-19T21:13:00Z",
      "futureStock": [
        {
          "expectedDate": "2025-05-31T21:13:00Z",
          "quantity": 10.25
        }
      ],
      "attributeSet": {
        "groupEligibilityExclusion": [
          "arizona",
          "utah"
        ]
      }
    },
    {
      "id": "82251928-8863-488e-840b-2aebd10b6666",
      "externalRefId": "7282822-9823-bbb",
      "location": "warehouse6",
      "sku": "sku456",
      "onHand": 500.75,
      "safetyStockCount": 25,
      "effectiveDate": "2025-05-19T21:13:00Z",
      "futureStock": [
        {
          "expectedDate": "2025-06-15T21:13:00Z",
          "quantity": 50
        }
      ],
      "attributeSet": {
        "groupEligibilityExclusion": [
          "california"
        ]
      }
    }
  ]
}
```

#### Responses

*   **200** Batch inventory partially updated with potentially some errors reported.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `BatchInventoryUpdateErrors`.
    
    _Example: batchInventoryPatch200_
    
    ```
    {
      "errors": [
        {
          "details": {
            "locationId": "warehouse5",
            "sku": "sku123",
            "id": "82251928-8863-488e-840b-2aebd10b57ba",
            "externalRefId": "7282822-9823-aaa"
          },
          "message": "Inventory record update failed",
          "errorCode": "InventoryReset"
        },
        {
          "details": {
            "locationId": "warehouse6",
            "sku": "sku456",
            "id": "82251928-8863-488e-840b-2aebd10b6666",
            "externalRefId": "7282822-9823-bbb"
          },
          "message": "Location not found",
          "errorCode": "EntityNotFound"
        }
      ]
    }
    ```
    
*   **204** All batch inventory items updated successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: batchInventoryPatch400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "An invalid request parameter was provided.",
      "parameterName": "location"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: batchInventoryPatch403_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Retrieve changes that have occurred since a given Delta Token. An initial Delta Token is obtained from an export call; subsequent Delta Tokens are returned from this call.

`POST /organizations/{organizationId}/availability-records/actions/get-deltas`

Operation ID: `getAvailabilityDeltas`. Security: AmOAuth2 (sfcc.inventory.availability, sfcc\_inventory\_availability).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `GetAvailabilityDeltasPostBody`.

_Example: getAvailabilityDeltaRequest_

```
{
  "deltaToken": "e3NoYXJkSWQtMDAwMDAwMDE1NzczOTkxNTc2MDItYmE5MGYxNGE6MDAwMDAwMDAwMDAwMDAwMDAwNDQ0fQ=="
}
```

#### Responses

*   **200** Changes are returned in the body with a new Delta Token to use for the next call.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `GetAvailabilityDeltasResponse200`.
    
    _Example: getAvailabilityDeltas200_
    
    ```
    {
      "nextDeltaToken": "e3NoYXJkSWQtMDAwMDAwMDE1NzczOTkxNTc2MDItYmE5MGYxNGE6MDAwMDAwMDAwMDAwMDAwMDAwNDQ0fQ==",
      "shouldQueryAgain": true,
      "records": [
        {
          "sku": "sku123",
          "deltaType": "Change",
          "id": "UnitedStates",
          "effectiveDate": "2019-07-24T21:13:00Z",
          "sequenceNumber": 123,
          "onHand": 1200.35,
          "atf": 1137.65,
          "ato": 1147.9,
          "reserved": 50.25,
          "safetyStockCount": 12.45,
          "futures": [
            {
              "expectedDate": "2019-07-24T21:13:00Z",
              "quantity": 10.25
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: getAvailabilityDeltas400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredDeltaLink",
      "message": "'id' The Delta Link is expired",
      "parameterName": "Delta Link"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: getAvailabilityDeltas403_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **410** Delta Token link expired.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: getAvailabilityDeltas410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredDeltaLink",
      "message": "The delta token provided has expired."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Get SKU availability by location, by group, or by both.

`POST /organizations/{organizationId}/availability-records/actions/get-availability`

Operation ID: `skuAvailabilityByLocationAndOrGroup`. Security: AmOAuth2 (sfcc.inventory.availability, sfcc\_inventory\_availability).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InventoryAvailabilityRequestBody`.

_Example: GetATSAllLocations_

```
{
  "sku": "sku123",
  "group": "Canada"
}
```

_Example: GetATSAllUnassignedLocations_

```
{
  "sku": "sku123"
}
```

_Example: GetATSLocationsAndGroups_

```
{
  "skus": [
    "sku123"
  ],
  "locations": [
    "warehouse5"
  ],
  "groups": [
    "UnitedStates"
  ]
}
```

#### Responses

*   **200** Availability information successfully returned.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `Response200`.
    
    _Example: GetAllLocationsAndGroupsResponse_
    
    ```
    {
      "locations": [
        {
          "id": "warehouse5",
          "records": [
            {
              "sku": "sku123",
              "atf": 1137.65,
              "ato": 1147.9,
              "onHand": 0,
              "reserved": 12.5,
              "safetyStockCount": 0,
              "effectiveDate": "2019-07-24T21:13:00Z",
              "futures": [
                {
                  "expectedDate": "2019-08-24T21:13:00Z",
                  "quantity": 10.25
                }
              ],
              "attributeSet": {
                "groupEligibilityExclusion": [
                  "arizona",
                  "utah"
                ]
              },
              "exists": true
            }
          ]
        }
      ],
      "groups": [
        {
          "id": "UnitedStates",
          "records": [
            {
              "sku": "sku123",
              "atf": 1137.65,
              "ato": 1147.9,
              "onHand": 0,
              "reserved": 12.5,
              "safetyStockCount": 0,
              "effectiveDate": "2019-07-24T21:13:00Z",
              "groupReserved": 10,
              "sharedGroupReserved": 2.5,
              "futures": [
                {
                  "expectedDate": "2019-08-24T21:13:00Z",
                  "quantity": 10.25
                }
              ],
              "exists": true
            }
          ]
        }
      ]
    }
    ```
    
    _Example: GetAllLocationsResponse_
    
    ```
    {
      "locations": [
        {
          "id": "surprise",
          "records": [
            {
              "sku": "sku123",
              "atf": 17,
              "ato": 27.25,
              "reserved": 0,
              "safetyStockCount": 10,
              "effectiveDate": "2020-04-08T14:05:22.790896-07:00",
              "futures": [
                {
                  "quantity": 10.25,
                  "expectedDate": "2019-08-24T21:13:00Z"
                }
              ],
              "attributeSet": {
                "groupEligibilityExclusion": [
                  "arizona",
                  "utah"
                ]
              },
              "onHand": 27,
              "exists": true
            }
          ]
        },
        {
          "id": "wickenburg",
          "records": [
            {
              "sku": "sku123",
              "atf": 30,
              "ato": 40.25,
              "reserved": 0,
              "safetyStockCount": 20,
              "effectiveDate": "2020-04-08T14:05:22.790896-07:00",
              "futures": [
                {
                  "quantity": 10.25,
                  "expectedDate": "2019-08-24T21:13:00Z"
                }
              ],
              "attributeSet": {
                "groupEligibilityExclusion": [
                  "arizona",
                  "utah"
                ]
              },
              "onHand": 50,
              "exists": true
            }
          ]
        }
      ],
      "groups": [
        {
          "id": "arizona",
          "records": [
            {
              "sku": "sku123",
              "atf": 47,
              "ato": 67.5,
              "reserved": 0,
              "safetyStockCount": 30,
              "groupReserved": 0,
              "sharedGroupReserved": 0,
              "effectiveDate": "2020-04-08T14:05:22.790896-07:00",
              "futures": [
                {
                  "quantity": 20.5,
                  "expectedDate": "2019-08-24T21:13:00Z"
                }
              ],
              "onHand": 77,
              "exists": true
            }
          ]
        }
      ]
    }
    ```
    
    _Example: GetAllUnassignedLocationsResponse_
    
    ```
    {
      "locations": [
        {
          "id": "surprise",
          "records": [
            {
              "sku": "sku123",
              "atf": 17,
              "ato": 27.25,
              "reserved": 0,
              "safetyStockCount": 10,
              "effectiveDate": "2020-04-08T14:05:22.790896-07:00",
              "futures": [
                {
                  "quantity": 10.25,
                  "expectedDate": "2019-08-24T21:13:00Z"
                }
              ],
              "attributeSet": {
                "groupEligibilityExclusion": [
                  "GroupA",
                  "GroupB"
                ]
              },
              "onHand": 27,
              "exists": true
            }
          ]
        },
        {
          "id": "wickenburg",
          "records": [
            {
              "sku": "sku123",
              "atf": 30,
              "ato": 40.25,
              "reserved": 0,
              "safetyStockCount": 20,
              "effectiveDate": "2020-04-08T14:05:22.790896-07:00",
              "futures": [
                {
                  "quantity": 10.25,
                  "expectedDate": "2019-08-24T21:13:00Z"
                }
              ],
              "attributeSet": {
                "groupEligibilityExclusion": [
                  "arizona",
                  "utah"
                ]
              },
              "onHand": 50,
              "exists": true
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: skuAvailabilityByLocationAndOrGroup400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "LocationDoesNotExist",
      "message": "A location provided in the request does not exist."
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: skuAvailabilityByLocationAndOrGroup403_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Submit batches of Product Eligibility Segmentations. The body permits requests to append or delete segmentations. For more information on Product Eligibility, see Product Eligibility Segmentation Import in the OCI Impex API.

`POST /organizations/{organizationId}/product-segmentation/actions/batch-update`

Operation ID: `batchProductSegmentationRequest`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ProductSegmentationAppendRequestBody | ProductSegmentationDeleteRequestBody`.

One of: `ProductSegmentationAppendRequestBody`, `ProductSegmentationDeleteRequestBody`.

_Example: ProductSegmentationAppendRequest_

```
{
  "groups": [
    {
      "groupId": "GroupA",
      "mode": "APPEND",
      "skus": [
        "sku123",
        "sku456"
      ]
    }
  ]
}
```

_Example: ProductSegmentationDeleteRequest_

```
{
  "groups": [
    {
      "groupId": "GroupA",
      "mode": "DELETE",
      "skus": [
        "sku123",
        "sku456"
      ]
    }
  ]
}
```

#### Responses

*   **200** Some product segmentations could not be fully processed.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `Errors`.
    
    _Example: DeleteError_
    
    ```
    [
      {
        "error": "Failed to delete product segmentation for group id WarehouseOne and sku DeleteSku1"
      },
      {
        "error": "Failed to delete product segmentation for group id WarehouseOne and sku DeleteSku1"
      }
    ]
    ```
    
    _Example: AppendError_
    
    ```
    [
      {
        "error": "Failed to create product segmentation for group id WarehouseOne and sku AppendNewSku1"
      },
      {
        "error": "to create product segmentation for group id WarehouseOne and sku AppendNewSku2"
      }
    ]
    ```
    
*   **204** Successfully processed all product segmentations.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ErrorInvalidRequestParameterMode_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "An invalid request parameter was provided",
      "parameterName": "mode"
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### PUT Update or create data and quantity information for an item. The PUT call for updating replaces all fields of data. For fields that are not included, the data that currently exists is deleted and everything defaults to 0 (zero).

`PUT /organizations/{organizationId}/locations/{locationId}/availability-records/skus/{sku}/{requestId}`

Operation ID: `replaceSkuLocation`. Security: AmOAuth2 (sfcc.inventory.availability.rw, sfcc\_inventory\_availability\_rw).

#### Parameters

*   `locationId` (path, LocationId, required) The location for the SKU being updated.
*   `sku` (path, SkuId, required) The SKU associated with the inventory record you want to update.
*   `requestId` (path, string, required) The unique request ID associated with the attempt to update an item in inventory.  
    Maximum length: 128. Example: `3678-23456-3456-4567-9999-1232`.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InventoryUpdateRequestBodyPut`.

_Example: InventoryUpdatePutRequest_

```
{
  "externalRefId": "7282822-9823-aaa",
  "onHand": 25,
  "safetyStockCount": 20,
  "effectiveDate": "2019-07-24T21:13:00Z",
  "futureStock": [
    {
      "expectedDate": "2019-07-24T21:13:00Z",
      "quantity": 10.25
    }
  ],
  "attributeSet": {
    "groupEligibilityExclusion": [
      "GroupA"
    ]
  }
}
```

#### Responses

*   **204** Data updated successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ErrorEntityNotFound_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "'EntityId' The provided entity is not found",
      "parameterName": "EntityId"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: tenantNotProvisioned403_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: EntityNotFound_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### DELETE Delete a location SKU. When you call this endpoint, all SKU values are reset and marked for deletion from the system. History is not preservered by this action, and the aggregate for this location SKU is also removed from the group view.

`DELETE /organizations/{organizationId}/locations/{locationId}/availability-records/skus/{sku}/{requestId}`

Operation ID: `deleteLocationSku`. Security: AmOAuth2 (sfcc.inventory.availability.rw, sfcc\_inventory\_availability\_rw).

#### Parameters

*   `locationId` (path, LocationId, required) The location for the SKU being updated.
*   `sku` (path, SkuId, required) The SKU associated with the inventory record you want to update.
*   `requestId` (path, string, required) The unique request ID associated with the attempt to update an item in inventory.  
    Maximum length: 128. Example: `3678-23456-3456-4567-9999-1232`.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Location SKU successfully deleted from the system.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **404** Location SKU not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: SKUNotFound_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "The Location SKU provided was not found in the system."
    }
    ```
    
*   **409** There is an inventory export in progress, deletion is not allowed.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ExportInProgress_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### PATCH Update or patch the data or quantity information for an item. On a PATCH call, most fields are optional, and only fields that are included are updated with the provided values.

`PATCH /organizations/{organizationId}/locations/{locationId}/availability-records/skus/{sku}/{requestId}`

Operation ID: `updateSkuLocation`. Security: AmOAuth2 (sfcc.inventory.availability.rw, sfcc\_inventory\_availability\_rw).

#### Parameters

*   `locationId` (path, LocationId, required) The location for the SKU being updated.
*   `sku` (path, SkuId, required) The SKU associated with the inventory record you want to update.
*   `requestId` (path, string, required) The unique request ID associated with the attempt to update an item in inventory.  
    Maximum length: 128. Example: `3678-23456-3456-4567-9999-1232`.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InventoryUpdateRequestBodyPatch`.

_Example: InventoryUpdatePatchRequest_

```
{
  "externalRefId": "7282822-9823-aaa",
  "onHand": 25
}
```

#### Responses

*   **204** Data updated successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ErrorEntityNotFound_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "'EntityId' The provided entity is not found",
      "parameterName": "EntityId"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: tenantNotProvisioned403_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: EntityNotFound_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the organization the request is being made by

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.

### CreateNewDeltaTokenBody

Whether this is a location or a group

*   `placeType` (_PlaceType_, required)
*   `places` (_Places_, required)

### CreateNewDeltaTokenResponse

The new Delta Token

*   `deltaToken` (_DeltaToken_, required)

### InventoryResponseErrorSchema

*   `errorCode` (_string_, required)  
    Maximum length: 256. Example: `InvalidRequestParameter`.
*   `message` (_string_, required)  
    Maximum length: 256. Example: `An invalid request parameter was provided.`.
*   `type` (_string_, required)  
    Maximum length: 256. Example: `about:blank`.
*   `parameterName` (_string_) When invalid json is passed to the service, this field will indicate which piece of the supplied json was invalid.  
    Maximum length: 256. Example: `location`.

### UpdateDeltaTokenBody

*   `deltaToken` (_DeltaToken_, required)
*   `places` (_Places_, required)

### UpdateDeltaTokenResponse

The updated Delta Token

*   `deltaToken` (_DeltaToken_, required)
*   `places` (_Places_)

### BatchInventoryUpdateRequest

*   `records` (_array of BatchInventoryUpdateRequestRecord_, required) List of records to process in a batch update. The maximum number of entries in the array is 100.  
    Maximum items: 100.

### BatchInventoryUpdateErrors

Errors produced during a batch inventory update

*   `errors` (_array of BatchInventoryUpdateSingleError_, required)

### GetAvailabilityDeltasPostBody

*   `deltaToken` (_DeltaToken_, required)

### GetAvailabilityDeltasResponse200

*   `nextDeltaToken` (_DeltaToken_, required)
*   `shouldQueryAgain` (_ShouldQueryAgain_, required)
*   `records` (_array of DeltaRecordType_, required)

### InventoryAvailabilityRequestBody

The body that is sent requesting the item availability by location and/or group

*   `sku` (_object_) Used for retrieving the data for a single item for all locations that have not been assigned to any specific group(s). If a group Id is specified in the request, then the locations to be returned will be the ones assigned to the specified group.
    
    Includes all fields of `SkuId`.
    
*   `group` (_object_) The group ID that should be used in conjunction with the single sku provided in the request. This will retrieve the information for all locations in this group.
    
    Includes all fields of `GroupId`.
    
*   `skus` (_array of SkuId_) It specifies the skus for which the availability requires to be checked. The array of SKUs is limited by the total combinations of SKU per location plus SKU per group to check, the total cannot be more than 100.
*   `locations` (_array of LocationId_) Query the system for availability at this location. This field does not union with the groups field. The array of locations is limited by the total combinations of SKU per location plus SKU per group to check, the total cannot be more than 100.
*   `groups` (_array of GroupId_) Query the system for availability for this group. This field does not union with the locations field. Array is limited to 0-100 items. This field does not union with the groups field. The array of groups is limited by the total combinations of SKU per location plus SKU per group to check, the total cannot be more than 100.

### Response200

Successful request for item information

*   `locations` (_array of ItemLocationInfo_, required)
*   `groups` (_array of ItemGroupInfo_)

### ProductSegmentationAppendRequestBody

*   `groups` (_array of object_, required)
    *   `groupId` (_GroupId_, required)
    *   `mode` (_string_, required)  
        Allowed values: `APPEND`. Example: `APPEND`.
    *   `skus` (_array of SkuId_, required)
        
        _Example_
        
        ```
        [
          "AppendNewSku1",
          "AppendNewSku2"
        ]
        ```
        

### ProductSegmentationDeleteRequestBody

*   `groups` (_array of object_, required)
    *   `groupId` (_GroupId_, required)
    *   `mode` (_string_, required)  
        Allowed values: `DELETE`. Example: `DELETE`.
    *   `skus` (_array of SkuId_, required)
        
        _Example_
        
        ```
        [
          "DeleteSku1",
          "DeleteSku2"
        ]
        ```
        

### Errors

Array of `object`.

*   `error` (_string_, required)  
    Maximum length: 256. Example: `Failed to delete product segmentation for group id WarehouseOne and sku 13`.

### LocationId

The id of the location of the inventory.

Type: `string`.

Minimum length: 2. Maximum length: 128. Pattern: ^\[a-zA-Z0-9-\_\]\*$. Example: `warehouse5`.

### SkuId

The inventory identifier

Type: `string`.

Minimum length: 2. Maximum length: 250. Pattern: ^\[^\\\\<>;%/\\s\]\*$. Example: `sku123`.

### InventoryUpdateRequestBodyPut

The body of the put request for updating sku/location inventory. All fields are required. If a field is missing or contains a null value then a 400 error will be thrown.

*   `externalRefId` (_ExternalRefId_)
*   `onHand` (_QOH_)
*   `safetyStockCount` (_SafetyStock_)
*   `effectiveDate` (_Date_)
*   `futureStock` (_array of Future_)
*   `attributeSet` (_AttributeSet_)

### InventoryUpdateRequestBodyPatch

The body of the patch request for updating sku/location inventory. All fields are OPTIONAL. If a field is missing or contains a null value then the system doesn't update that field when patching.

*   `externalRefId` (_ExternalRefId_)
*   `onHand` (_QOH_)
*   `safetyStockCount` (_SafetyStock_)
*   `effectiveDate` (_Date_)
*   `futureStock` (_array of Future_)
*   `attributeSet` (_AttributeSet_)

### PlaceType

The type of place associated to the id

Type: `string`.

Maximum length: 256. Example: `{type: location | group}`.

### Places

The list of places

Array of `object`.

Maximum items: 100.

Includes all fields of `GroupId`, `LocationId`.

_Example_

```
{
  "locationExample": [
    "warehouseOne",
    "warehouseTwo"
  ],
  "groupExample": [
    "UnitedStates",
    "Canada"
  ]
}
```

### DeltaToken

The delta token obtained from a full export or a previous request to this API

Type: `string`.

Maximum length: 256. Example: `e3NoYXJkSWQtMDAwMDAwMDE1NzczOTkxNTc2MDItYmE5MGYxNGE6MDAwMDAwMDAwMDAwMDAwMDAwNDQ0fQ==`.

### BatchInventoryUpdateRequestRecord

Record definition used in a batch inventory update request

*   `externalRefId` (_ExternalRefId_)
*   `futureStock` (_array of Future_)
*   `attributeSet` (_AttributeSet_)
*   `location` (_LocationId_, required)
*   `onHand` (_QOH_)
*   `safetyStockCount` (_SafetyStock_)
*   `sku` (_SkuId_, required)
*   `id` (_IdempotenceId_, required)
*   `effectiveDate` (_Date_)

### BatchInventoryUpdateSingleError

Error record information generated during a batch inventory update.

*   `details` (_BatchInventoryUpdateErrorDetail_, required)
*   `message` (_string_, required)  
    Maximum length: 255. Example: `Inventory record update failed`.
*   `errorCode` (_string_, required)  
    Maximum length: 255. Example: `InventoryReset`.

### ShouldQueryAgain

Indicates to the consumer if they should immediately call again to retrieve deltas that are potentially waiting in the stream.

Type: `boolean`.

Example: `true`.

### DeltaRecordType

An availability delta record that is returned from the availability delta calls. All fields that are Required will be reported, however if there is not a value for any particular field, it will be 0, empty or null.

*   `sku` (_SkuId_, required)
*   `deltaType` (_string_, required)  
    Allowed values: `Change`, `Delete`. Example: `Change`.
*   `id` (_PlaceId_, required)
*   `effectiveDate` (_object_) The effective date for the info is provided, but the field is NOT required. The date represents when the onHand value was accurate at the location.
    
    Includes all fields of `Date`.
    
*   `sequenceNumber` (_number_, required) A sequence number to allow the caller to determine if records have been returned out of order.  
    Example: `123`.
*   `onHand` (_QOH_, required)
*   `atf` (_ATF_, required)
*   `ato` (_ATO_, required)
*   `reserved` (_QuantityReserved_, required)
*   `safetyStockCount` (_SafetyStock_, required)
*   `futures` (_array of Future_, required)

### GroupId

An identifier for a collection of locations.

Type: `string`.

Minimum length: 1. Maximum length: 128. Pattern: ^\[a-zA-Z0-9-\_\]\*$. Example: `UnitedStates`.

### ItemLocationInfo

Location information used for availability by location responses

*   `id` (_LocationId_, required)
*   `records` (_array of object_, required) Records returned for the sku/location combination
    
    Each item: A record contained within the lookup results containing details about the item. Those details include the sku, available to fulfill amount, available to order amount, quantity on hand amount, and the safety stock count value.
    
    *   `sku` (_SkuId_, required)
    *   `atf` (_ATF_, required)
    *   `ato` (_ATO_, required)
    *   `onHand` (_QOH_, required)
    *   `reserved` (_Reserved_, required)
    *   `safetyStockCount` (_SafetyStock_, required)
    *   `effectiveDate` (_Date_)
    *   `futures` (_array of Future_)
    *   `attributeSet` (_AttributeSet_)
    *   `exists` (_Exists_)

### ItemGroupInfo

The group info, associated with an item and used in the availability responses.

*   `id` (_GroupId_, required)
*   `records` (_array of object_, required) Records returned for a sku/group combination
    
    Each item: A record contained within the lookup results containing details about the item. Those details include the sku, available to fulfill amount, available to order amount, quantity on hand amount, and the safety stock count value.
    
    *   `sku` (_SkuId_, required)
    *   `atf` (_object_, required) The amount available to fulfill at for the group
        
        Includes all fields of `ATF`.
        
    *   `ato` (_object_, required) The amount available to order at within the group
        
        Includes all fields of `ATO`.
        
    *   `onHand` (_object_, required) Quantity on hand within the group.
        
        Includes all fields of `QOH`.
        
    *   `reserved` (_object_, required) The amount reserved within the group
        
        Includes all fields of `Reserved`.
        
    *   `safetyStockCount` (_SafetyStock_, required)
    *   `groupReserved` (_object_) The total group reservations for the group NOT including shared
        
        Includes all fields of `Reserved`.
        
    *   `sharedGroupReserved` (_object_) The amount of the soft\_reserved count that comes from other groups
        
        Includes all fields of `Reserved`.
        
    *   `effectiveDate` (_Date_)
    *   `futures` (_array of FutureGroup_)
    *   `exists` (_Exists_)

### ExternalRefId

A convenience identifier for the consumer, used for auditing events. This field is NOT used by the service itself, but is intended for the consumer to be able to identify records submitted from their systems that are external to OCI.

Type: `string`.

Maximum length: 250. Example: `7282822-9823-aaa`.

### QOH

Quantity on hand.

Type: `number (double)`.

Minimum: 0. Multiple of: 0.001. Example: `1200.35`.

### SafetyStock

Inventory quantity that a merchant wants to intentionally hold back from availability counts. Precision of the safety stock is four decimal places: 0.001.

Type: `number (double)`.

Minimum: 0. Example: `12.45`.

### Date

The date the future quantity is expected to arrive at the location.

Type: `string (date-time)`.

Example: `2019-07-24T21:13:00Z`.

### Future

The 'future' object contains data that tells us what is expected to arrive for this item in the future, as well as when those amounts of inventory should arrive.

*   `expectedDate` (_Date_, required)
*   `quantity` (_Quantity_, required)

### AttributeSet

A set of attributes that can be applied as attributes in a request.

*   `groupEligibilityExclusion` (_array of GroupEligibilityExclusion_, required)

### IdempotenceId

A unique identifier, used in combination with the SKU, so that future requests with the same combination have the same result.

Type: `string`.

Maximum length: 250. Example: `82251928-8863-488e-840b-2aebd10b57ba`.

### BatchInventoryUpdateErrorDetail

Detail information for errors generated during a batch inventory update.

*   `externalRefId` (_ExternalRefId_)
*   `locationId` (_LocationId_, required)
*   `sku` (_SkuId_, required)
*   `id` (_IdempotenceId_, required)

### PlaceId

The id of a group or location where inventory is located.

Type: `string`.

Maximum length: 128.

_Example_

```
{
  "location": "warehouse5",
  "group": "UnitedStates"
}
```

### ATF

The amount available to fulfill at the location

Type: `number (double)`.

Minimum: 0. Multiple of: 0.001. Example: `1137.65`.

### ATO

The amount available to order at the location

Type: `number (double)`.

Minimum: 0. Multiple of: 0.001. Example: `1147.9`.

### QuantityReserved

Actual quantity reserved. This value can be less than the quantity requested.

Type: `number (double)`.

Minimum: 0. Multiple of: 0.001. Example: `50.25`.

### Reserved

The amount reserved at the location

Type: `number (double)`.

Minimum: 0. Multiple of: 0.001. Example: `12.5`.

### Exists

Indicates whether a record exists for a SKU. This could be helpful since, the Get Availability API returns records with all zero values when the sku does not exist.

Type: `boolean`.

Example: `true`.

### FutureGroup

The 'future' object contains data that tells us what is expected to arrive for this item in the future, as well as when those amounts of inventory should arrive.

*   `expectedDate` (_DateGroup_, required)
*   `quantity` (_Quantity_, required)

### Quantity

The amount that is expected to arrive at a future date

Type: `number`.

Minimum: 0.001. Multiple of: 0.001. Example: `10.25`.

### GroupEligibilityExclusion

The group eligibility exclusion that can be applied in an Attribute Set as part of an item update.

Type: `string`.

Minimum length: 2. Maximum length: 128.

### DateGroup

The date the future quantity is expected to arrive within the group

Includes all fields of `Date`.

Example: `2019-07-24T21:13:00Z`.

<!-- document id=367b47265a466ec79f3f5037d53e580ee17df39365884051d4f27996d2b44ccd url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-inventory.md -->

# Inventory Data Model

The Inventory data model connects objects and relationships that govern how inventories are applied to products and cart items throughout the checkout cycle.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the Inventory data model require the B2B Commerce license.

![Diagram of the Inventory data model](https://developer.salesforce.com/media/d2c-commerce/commerce_cloud_inventory_zh.png)

- [InventoryReservation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstoreinventorysource.htm)
- [ProcessException](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_processexception.htm)
- [OrderSummary](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_ordersummary.htm)
- [WebCart](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webcart.htm)
- [InventoryItemReservation](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_inventoryitemreservation.htm)
- [LocationGroup](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_locationgroup.htm)
- [Location](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_location.htm)
- [CartItem](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_cartitem.htm)
- [Product2](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm)

<!-- document id=b5d9032446f502f69c20d451cbe86f5d13294629a5da7686700698a30d87c707 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/inventory-event-webhooks.md -->

# Inventory Event Webhooks

Point of Sale created Inventory Events webhooks that allow merchants to integrate and interact with inventory management systems programmatically. They can enable real-time data exchange for inventory-related events. These events include transfer, adjustment, cycle count, purchase order, and inventory movements (sales, returns) data.

:::tip

For a comprehensive list of Retail Cloud's API and SPIs, refer to [Retail Cloud API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).


## Inventory Events

**1. Inventory Transfer** - This API sends inventory transfer-related data to an external system. The types of transfers are Advanced Shipping Notice (ASN), Corporate Transfer (CTS), Store to Store (STS), Blind Receivings (BLD), and Return to Vendor (RTV).

```bash
POST/merchant/spi/sample/endpoint/sa/customer/inventory/inventoryTransfer 
```

**2. Inventory Adjustment** - This API sends inventory adjustment-related data to an external system (for example, quantity count, reason for adjustment, reason text, etc.).

```bash
POST/merchant/spi/sample/endpoint/sa/customer/inventory/inventoryAdjustment
```

**3. Cycle Count** - This API sends cycle count-related data to an external system (for example, product information, inventory/counted quantity, variances, etc.).

```bash
POST/merchant/spi/sample/endpoint/sa/customer/inventory/cycleCount
```

**4. Purchase Order** - This API sends purchase order-related data to an external system (for example, product information, order quantity, costs, etc.).

```bash
POST/merchant/spi/sample/endpoint/sa/customer/inventory/purchaseOrder
```

**5. Inventory Movement** - This API sends inventory movement-related data to an external system (for example, sales, returns).

```bash
  POST/merchant/spi/sample/endpoint/sa/customer/inventory/sale
```

```bash
  POST/merchant/spi/sample/endpoint/sa/customer/inventory/return
```

**6. Create ASN** - This API creates an ASN in the inventory management system.

```bash
POST/merchant/{version}/ims/inventory/asn
```

### Example Payload Request and Response

Below, you'll find examples of both the request payload and the response for the Inventory Transfer API.

#### Request

```json
  "eventType": "STS_TRANSFER_STARTED_EVENT",
  "lines": [
    {
      "billOfLadingID": "99865",
      "cancelledOn": 1686608971000,
      "cartonID": "A-4-PS00000001P1C1",
      "color": "Navy",
      "createdOn": 1686607971000,
      "deliveredOn": 1686608971000,
      "description": "Request for transfer from from store 1 to store 2",
      "dueOn": 1686608971000,
      "estimatedDeliveryOn": 1686608971000,
      "exportDate": 1686608971000,
      "externalDocNumber": "4900071859",
      "externalLineNumber": "00010",
      "fromID": "1",
      "gtin": "3661601593970",
      "inventoryTransferID": "ITS00000001",
      "isManualAdd": true,
      "itemStatus": "COMPLETE",
      "itemTrackingNumber": "TrackingIDPS00000001",
      "lastProcessedById": "2036",
      "lastProcessedByName": "Rob",
      "orderID": "OrderPS00000001",
      "palletID": "A-4-PS00000001P1",
      "poNumber": "123456",
      "productCount": 3,
      "productID": "3661601594304",
      "productImageLinks": "https://us.maje.com/dw/image/v2/AAON_PRD/on/demandware.static/-/Sites-maje-catalog-master-H13/default/dwd569bdfb/images/h13/Maje_E18GUMPY-0067_H_1.jpg",
      "productImageURL": "https://us.maje.com/dw/image/v2/AAON_PRD/on/demandware.static/-/Sites-maje-catalog-master-H13/default/dw2b369dcf/images/h13/Maje_E18PERSE-1066_H_1.jpg",
      "productTitle": "Wide-leg checked trousers",
      "quantityOrdered": 3,
      "quantityReceived": 1,
      "quantityTransferred": 2,
      "reasonCode": "1",
      "reasonText": "Damaged",
      "receivedBy": "2036",
      "receivedOn": 1686608971000,
      "shippedOn": 1686608971000,
      "shipper": "UPS",
      "size": "OS",
      "status": "IN_PROGRESS",
      "toID": "2",
      "trackingNumber": "track123",
      "transferID": "409a92a5-834b-4500-b062-cedd89a38602",
      "transferType": "STORE_TO_STORE",
      "updatedOn": 1686608971000,
      "vendorID": "1",
      "vendorNumber": "0607282"
    }
  ]
}
```

#### Response

```json
{
  "message": "Successfully",
  "status": "SUCCESS"
}
```

## CMS - Configuration & Setup

To set up inventory event webhooks in Point of Sale, you'll need to configure custom connectors in CMS for each type of inventory event you want to monitor. This involves creating endpoints, specifying API keys, and configuring the appropriate event subscriptions. The setup process allows you to establish real-time data exchange between Point of Sale and your external inventory management systems.

### Configuring Webhooks

To configure APIs, endpoints must be implemented and provided by the merchant system. Then they must be configured in Point of Sale CMS.

In CMS, go to **Store Management** **>** **Integrations** **>** **Custom Connectors**.

Create a new connector by referring to the table below:

| Inventory Events                      | Used for sending inventory data to external system                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send inventory Transfer data          | **API Key:** This should be one of the following values:<br>• INVENTORY_EXPORT_ASN<br>• INVENTORY_EXPORT_STS<br>• INVENTORY_EXPORT_RTV<br>• INVENTORY_EXPORT_CTS<br>• INVENTORY_EXPORT_BLD<br><br>**Events:** Only the subscribed event's data will be sent out, available events:<br>• ASN_RECEIVED_EVENT<br>• ASN_PARTIALLY_RECEIVED_EVENT<br>• ASN_RECEIVE_COMPLETED_EVENT<br><br>**API Endpoint:** Provide the external endpoint to send the inventory transfer data out. E.g., `https://sample/external/endpoint/merchant/spi/sample/endpoint/sa/customer/inventory/inventoryTransfer`<br><br>**Integration Type:** It should be HTTP_POST.<br><br>**JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes that is, clientId/password.<br>`{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}`<br><br>For a full list of events, see [Retail Cloud API Specifications](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html) and this [guide](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html). |
| Send inventory adjustment data        | **API Key:** This should be one of following values:<br>• INVENTORY_EXPORT_INA<br><br>**Events:** Only the subscribed event's data will be sent out, available events:<br>• INVENTORY_ADJUSTMENT<br>• INVENTORY_BUCKET_ADJUSTMENT<br><br>**API Endpoint:** Provide the external endpoint to send the inventory transfer data out. E.g., `https://sample/external/endpoint/merchant/spi/sample/endpoint/sa/customer/inventory/inventoryAdjustment`<br><br>**Integration Type:** It should be HTTP_POST.<br><br>**JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes that is, clientId/password.<br>`{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}`                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Send inventory bucket adjustment data | **API Key:** This should be one of following values:<br>• INVENTORY_EXPORT_INBA<br><br>**Events:** Only the subscribed event's data will be sent out, available events:<br>• INVENTORY_BUCKET_ADJUSTMENT<br><br>**API Endpoint:** Provide the external endpoint to send the inventory transfer data out. E.g., `https://sample/external/endpoint/merchant/spi/sample/endpoint/sa/customer/inventory/inventoryBucketAdjustment`<br><br>**Integration Type:** It should be HTTP_POST.<br><br>**JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes that is, clientId/password.<br>`{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Send cycle count data                 | **API Key:** This should be one of following values:<br>• INVENTORY_EXPORT_CYC<br><br>**Events:** Only the subscribed event's data will be sent out, available events:<br>• CYC_COUNT_CREATED_EVENT<br>• CYC_COUNT_STARTED_EVENT<br>• CYC_COUNT_COMPLETED_EVENT<br>• CYC_COUNT_CANCELED_EVENT<br><br>**API Endpoint:** Provide the external endpoint to send the inventory transfer data out. E.g., `https://sample/external/endpoint/merchant/spi/sample/endpoint/sa/customer/inventory/cycleCount`<br><br>**Integration Type:** It should be HTTP_POST.<br><br>**JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes that is, clientId/password.<br>`{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}`                                                                                                                                                                                                                                                                                                                                                                                                       |
| Send purchase order data              | **API Key:** This should be one of following values:<br>• INVENTORY_EXPORT_PO<br><br>**Events:** Only the subscribed event's data will be sent out, available events:<br>• PO_TRANSFER_STARTED_EVENT<br>• PO_TRANSFER_COMPLETED_EVENT<br>• PO_TRANSFER_ERRORED_EVENT<br><br>**API Endpoint:** Provide the external endpoint to send the inventory transfer data out. E.g., `https://sample/external/endpoint/merchant/spi/sample/endpoint/sa/customer/inventory/purchaseOrder`<br><br>**Integration Type:** It should be HTTP_POST.<br><br>**JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes that is, clientId/password.<br>`{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}`                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Send sales data                       | This event indicates that an item (or items) has been sold. When this event is triggered, the expectation is that the inventory for the specified item(s) should decrease.<br><br>**API Key:** This should be SALE_INVENTORY.<br><br>**API Endpoint:** Provide the external endpoint to send inventory-related sales data out. E.g., `https://sample/external/endpoint/merchant/spi/sample/endpoint/sa/customer/inventory`<br><br>**Integration Type:** It should be HTTP_POST.<br><br>**JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes that is, clientId/password.<br>`{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Send return data                      | This event indicates that an item (or items) has been returned or exchanged. When this event is triggered, the inventory for the specific item(s) should increase or adjust in some manner if it's an exchange.<br><br>**API Key:** This should be RETURN_INVENTORY.<br><br>**API Endpoint:** Provide the external endpoint to send inventory-related returns data out. E.g., `https://sample/external/endpoint/merchant/spi/sample/endpoint/sa/customer/inventory`<br><br>**Integration Type:** It should be HTTP_POST.<br><br>**JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes that is, clientId/password.<br>`{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}`                                                                                                                                                                                                                                                                                                                                                                                                                                        |


### Reposting Webhooks

Point of Sale offers the ability to manually repost failed webhook events.

1. In CMS, go to **Store Management > Reporting and Analytics > Repost Failed Webhook Events**.
2. Search for the failed webhook event by configuring the search query parameters.
3. Click **View Details** to view the details of the payload inside the selected webhook event.
4. Click **Repost** to manually trigger a webhook event repost.

<!-- document id=cd3e4a9affa199ee2724a8e003fbba92ef0467a2b8429e7a2861b31a1f7914f3 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/inventory-events-spi.md -->

Inventory Events SPI

# Inventory Events SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-events-spi/inventory-events-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send inventory events data.

**Version:** 2.3.4

## Tags

### Inventory Events SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-events-spi/inventory-events-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send inventory events data.

## Operations

### POST Send cycle count events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/cycleCount`

Operation ID: `sendInventoryEventsData`. Tags: Inventory Events SPI.

Sends cycle count data to an external system. **Supported events:**

1.  CYC\_COUNT\_CREATED\_EVENT
2.  CYC\_COUNT\_STARTED\_EVENT
3.  CYC\_COUNT\_COMPLETED\_EVENT
4.  CYC\_COUNT\_CANCELED\_EVENT.

#### Request body

Media type: `application/json`. Schema: `CycleCountPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send inventory adjustment events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/inventoryAdjustment`

Operation ID: `sendInventoryEventsData_1`. Tags: Inventory Events SPI.

Sends inventory adjustment data to an external system. **Supported events:**

1.  INVENTORY\_ADJUSTMENT.

#### Request body

Media type: `application/json`. Schema: `InventoryAdjustmentPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send inventory transfer events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/inventoryTransfer`

Operation ID: `sendInventoryEventsData_2`. Tags: Inventory Events SPI.

Sends inventory transfer data to an external system. The inventory transfer types include: ASN, CORP\_TRANSFER, STORE\_TO\_STORE, BLIND\_RECEIVE, RETURN\_TO\_VENDOR. All related events will use this API. **Supported events:**

1.  ASN\_RECEIVED\_EVENT
2.  ASN\_PARTIALLY\_RECEIVED\_EVENT
3.  ASN\_RECEIVE\_COMPLETED\_EVENT
4.  ASN\_REJECTED\_EVENT
5.  BLIND\_RECEIVE\_STARTED\_EVENT
6.  BLIND\_RECEIVE\_PAUSED\_EVENT
7.  BLIND\_RECEIVE\_IN\_PROGRESS\_EVENT
8.  BLIND\_RECEIVE\_COMPLETED\_EVENT
9.  CTS\_TRANSFER\_STARTED\_EVENT
10.  CTS\_TRANSFER\_COMPLETED\_EVENT
11.  CTS\_TRANSFER\_CANCELLED\_EVENT
12.  CTS\_TRANSFER\_ERRORED\_EVENT
13.  STS\_TRANSFER\_STARTED\_EVENT
14.  STS\_TRANSFER\_COMPLETED\_EVENT
15.  STS\_TRANSFER\_SHIPPED\_EVENT
16.  STS\_TRANSFER\_RECEIVED\_EVENT
17.  STS\_TRANSFER\_CANCELLED\_EVENT
18.  STS\_TRANSFER\_ERRORED\_EVENT
19.  RTV\_CREATED\_EVENT
20.  RTV\_COMPLETED\_EVENT
21.  RTV\_SHIPPED\_EVENT
22.  RTV\_RECEIVED\_EVENT
23.  RTV\_CANCELLED\_EVENT
24.  RTV\_FAILLED\_EVENT.

#### Request body

Media type: `application/json`. Schema: `InventoryTransferPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send purchase order events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/purchaseOrder`

Operation ID: `sendInventoryEventsData_3`. Tags: Inventory Events SPI.

Sends purchase order data to an external system. **Supported events:**

1.  PO\_TRANSFER\_STARTED\_EVENT
2.  PO\_TRANSFER\_COMPLETED\_EVENT
3.  PO\_TRANSFER\_ERRORED\_EVENT.

#### Request body

Media type: `application/json`. Schema: `PurchaseOrderPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send return inventory events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/return`

Operation ID: `sendInventoryEventsData_4`. Tags: Inventory Events SPI.

Sends return inventory details to an external system.

#### Request body

Media type: `application/json`. Schema: `TransactionalReturnPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `TransactionalInventoryWebhookResponse`.
    

### POST Send sale inventory events data.

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/sale`

Operation ID: `sendInventoryEventsData_5`. Tags: Inventory Events SPI.

Send sale inventory detail to external system.

#### Request body

Media type: `application/json`. Schema: `TransactionalSalePayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `TransactionalInventoryWebhookResponse`.
    

## Schemas

### CycleCountPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of CycleCountPayloadLine_, required) Cycle count line items.

### InventoryWebhookResponse

*   `status` (_string_, required)
    
    Status
    
    Status of the inventory webhook processing.
    
      
    Allowed values: `SUCCESS`, `ERROR`. Example: `SUCCESS`.
*   `message` (_string_, required)
    
    Message
    
    Inventory webhook processing result.
    
      
    Example: `Successfully`.

### InventoryAdjustmentPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of InventoryAdjustmentPayloadLine_, required) Inventory adjustment line items.

### InventoryTransferPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of InventoryTransferPayloadLine_, required) Inventory transfer line items.

### PurchaseOrderPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of PurchaseOrderPayloadLine_, required) Purchase order line items.

### TransactionalReturnPayload

*   `orderId` (_string_, required)
    
    orderId
    
    Order ID.
    
      
    Example: `PS00000006`.
*   `products` (_array of TransactionalInventoryProduct_, required)
    
    products
    
    List the products that require inventory adjustment.
    
*   `returnStoreLocation` (_string_, required)
    
    returnStoreLocation
    
    Return order's store ID.
    
      
    Example: `2`.

### TransactionalInventoryWebhookResponse

*   `status` (_string_, required)
    
    Status
    
    Status of the transaction inventory webhook processing.
    
      
    Allowed values: `SUCCESS`, `ERROR`. Example: `SUCCESS`.
*   `message` (_string_, required)
    
    Message
    
    Transaction inventory webhook processing result.
    
      
    Example: `Successfully`.

### TransactionalSalePayload

*   `orderId` (_string_, required)
    
    orderId
    
    Order ID.
    
      
    Example: `PS00000006`.
*   `products` (_array of TransactionalInventoryProduct_, required)
    
    products
    
    List the products that require inventory adjustment.
    
*   `fulfillmentLocation` (_string_, required)
    
    fulfillmentLocation
    
    Sale order's store ID.
    
      
    Example: `2`.
*   `fulfillmentType` (_string_, required)
    
    fulfillmentType
    
    Order fulfillment type.
    
      
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.

### CycleCountPayloadLine

Cycle count line items.

*   `storeID` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `cycleCountID` (_string_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `cycleCountType` (_string_, required, read-only) Below is list of supported cycle count types:  
    1.**Full**: Cycle count for the full inventory of products  
    2.**Partial**: Cycle count for a particular group of products that fall within  
    a selected category, brand, or any other product attribute that is configured  
    3.**Manual**: Cycle count for a specific set of products that are scanned in prior to starting the count.  
    Allowed values: `FULL`, `PARTIAL`, `ADJUSTMENT`, `FULL, PARTIAL, ADJUSTMENT`. Example: `STORE`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch provide this status  
        2\. **CANCELED**: To cancel the existing cycle count batch.  
        3\. **COMPLETED**: Once the batch is created in the POS system,  
        the status will become COMPLETED  
        4\. **PREPARING**: Preparing the cycle count batch  
        5\. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`, `CREATED, PREPARING, IN_PROGRESS, COMPLETED, CANCELED`. Example: `CREATED`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`, `CORPORATE, STORE`. Example: `STORE`.
*   `cycleCountDate` (_integer (int64)_)
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `partialCycleCountProductAttribute` (_string_, required) Product attribute for partial cycle count to perform cycle count by specific product attribute. For example, Brand.  
    Example: `MerchantCategory`.
*   `partialCycleCountProductAttributeValues` (_string_, required) List of product attribute values for partial cycle count. For example, Brand values of Mattel, Disney, etc.  
    Example: `Reserve`.
*   `productCategories` (_string_, deprecated) List of product categories for partial cycle count for specific product categories. Use @partialCycleCountProductAttribute.  
    Example: `Clothing`.
*   `productIDs` (_string_, deprecated) List of product IDs applicable for partial cycle count for specific products. Use @partialCycleCountProductAttributeValues.  
    Example: `productId1,productId2`.
*   `createdBy` (_string_, required) Store associate ID who created the cycle count.  
    Example: `0202`.
*   `updatedBy` (_string_, required) Store associate ID who modified the cycle count.  
    Example: `0202`.
*   `startedByStoreAssociateID` (_string_, required) ID of the Store associate who started this cycle count. This need not be the same as the user who created the cycle count.  
    Example: `0202`.
*   `updatedByStoreAssociateID` (_string_, required) ID of the Store associate who last updated this cycle count.  
    Example: `0202`.
*   `expectedQuantity` (_integer (int32)_, required) Total number of products expected.  
    Example: `5`.
*   `countedQuantity` (_integer (int32)_, required) Total number of products actually counted.  
    Example: `3`.
*   `expectedProductValue` (_number_, required) Total value of the products - expected.  
    Example: `100`.
*   `countedProductValue` (_number_, required) Total value of the products that were actually counted.  
    Example: `60`.
*   `variancePercentageQuantity` (_number_, required) Variance percentage between expected product count vs. actual product count.  
    Example: `-60`.
*   `variancePercentageProductValue` (_number_, required) Variance percentage between expected product value vs. actual product value.  
    Example: `-60`.
*   `varianceQuantity` (_integer (int32)_, required) Variance in quantity between expected product count vs. actual product count.  
    Example: `-2`.
*   `varianceProductValue` (_number_, required) Variance in value between expected product count vs. actual product count.  
    Example: `-40`.
*   `email` (_string_) Email address to which the cycle count report was sent.  
    Example: `predictspring@predictspring.com`.
*   `startTimeStamp` (_integer (int64)_, required) Cycle count start time represented in milliseconds since epoch.  
    Example: `1686608971000`.
*   `productID` (_string_, required) Product ID.  
    Example: `014001`.
*   `gtin` (_string_, required) Product GTIN.  
    Example: `778913800001`.
*   `productTitle` (_string_, required) Product name.  
    Example: `Plat Pinot`.
*   `productImageURL` (_string_) Product Image URL.
*   `color` (_string_) Product Color.  
    Example: `white`.
*   `size` (_string_) Product Size.  
    Example: `0.75`.
*   `unitProductValue` (_number_) Unit Price.  
    Example: `32.99`.
*   `excluded` (_boolean_) Flag indicating if this product was excluded from cycle count. This flag indicates that this product inventory should not be adjusted based on this cycle count. Excluded products are excluded from variance calculations as well.
*   `reasonCode` (_string_) Reason code for excluding the item from cycle count.
*   `createdTimeStamp` (_integer (int64)_, required) Cycle count creation time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `modifiedTimeStamp` (_integer (int64)_, required) Cycle count last modified time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `reasonText` (_string_) Reason text for excluding the item from cycle count.  
    Example: `Lost`.
*   `serialNumbers` (_string_) Scanned Serial numbers.
*   `itemExpectedQuantity` (_integer (int32)_, required) Expected quantity for this item.  
    Example: `70`.
*   `itemCountedQuantity` (_integer (int32)_, required) Actual quantity for this item.  
    Example: `0`.
*   `itemExpectedProductValue` (_number_, required) Expected product value for this item based on expected quantity.  
    Example: `2309.3`.
*   `itemCountedProductValue` (_number_, required) Actual product value for this item based on counted quantity.  
    Example: `0`.
*   `itemVariancePercentageQuantity` (_number_, required) Variance percentage between expected product count vs. actual product count.  
    Example: `-100`.
*   `itemVariancePercentageProductValue` (_number_, required) Variance percentage in value between expected product value vs. actual product value.  
    Example: `-100`.
*   `itemVarianceQuantity` (_integer (int32)_, required) Variance in quantity between expected product count vs. actual product count.  
    Example: `-70`.
*   `itemVarianceProductValue` (_number_, required) Variance in value between expected product value vs. actual product value.  
    Example: `-2309.3`.
*   `itemRecountCount` (_integer (int32)_, required) The number of times the item is recounted within the same cycle count.  
    Example: `1`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.

### InventoryAdjustmentPayloadLine

Inventory adjustment line items.

*   `id` (_string_, required) Inventory adjustment identifier.
*   `storeID` (_string_, required) ID of the store where this inventory adjustment is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `productID` (_string_, required) Product item identifier.
*   `productTitle` (_string_, required) Product title.
*   `productImageURL` (_string_, required) Product image URL.
*   `color` (_string_) Product color.
*   `size` (_string_) Product size.
*   `countedQuantity` (_integer (int32)_, required) Adjusted quantity.  
    Example: `5`.
*   `startedByStoreAssociateID` (_string_, required) ID of the Store associate who started this inventory adjustment. This need not be the same as the user who created the inventory adjustment.  
    Example: `2036`.
*   `updatedByStoreAssociateID` (_string_, required) ID of the Store associate who last updated this inventory adjustment.  
    Example: `2036`.
*   `createdTimeStamp` (_integer (int64)_, required) Inventory adjustment batch item creation time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `modifiedTimeStamp` (_integer (int64)_, required) Inventory adjustment batch item last modified time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `reason` (_string_, required) Adjustment reason code.  
    Example: `MISSING ITEMS`.
*   `reasonText` (_string_, required) Adjustment reason text.  
    Example: `Missing Items`.
*   `gtin` (_string_, required) Product GTIN.  
    Example: `778913800001`.
*   `serialNumbers` (_string_) Scanned Serial numbers.
*   `itemHierarchyId` (_string_, required) Item hierarchy ID for products which have the same product ID but have different reason codes.  
    Example: `1`.

### InventoryTransferPayloadLine

Inventory transfer line items.

*   `transferType` (_string_, required) Inventory transfer type.  
    Allowed values: `ASN`, `CORP_TRANSFER`, `STORE_TO_STORE`, `BLIND_RECEIVE`, `RETURN_TO_VENDOR`, `PO`, `ASN`, `CORP_TRANSFER`, `STORE_TO_STORE`, `BLIND_RECEIVE`, `RETURN_TO_VENDOR`. Example: `STORE_TO_STORE`.
*   `inventoryTransferID` (_string_, required) Inventory transfer identifier.  
    Example: `ITS00000001`.
*   `orderID` (_string_) Inventory transfer order identifier.  
    Example: `OrderPS00000001`.
*   `poNumber` (_string_) Inventory transfer Purchase Order Number.  
    Example: `123456`.
*   `uploadNumber` (_string_) Used to indicate the corporate transfer group.  
    Example: `1, 2`.
*   `billOfLadingID` (_string_) Bill of lading ID.  
    Example: `99865`.
*   `trackingNumber` (_string_, required) Tracking number.  
    Example: `track123`.
*   `fromID` (_string_, required) Inventory transfer origin identifier. For example, Warehouse/Distribution center/Store ID.  
    Example: `1`.
*   `toID` (_string_, required) Inventory transfer recipient identifier. For example, Warehouse/Distribution center/Store ID.  
    Example: `2`.
*   `productCount` (_integer (int32)_, required) Number of products in this inventory transfer.  
    Example: `3`.
*   `productImageLinks` (_string_) List of product images for the items in this inventory transfer.  
    Example: `https://us.maje.com/dw/image/v2/AAON_PRD/on/demandware.static/-/Sites-maje-catalog-master-H13/default/dwd569bdfb/images/h13/Maje_E18GUMPY-0067_H_1.jpg`.
*   `status` (_string_, required) Inventory transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. Example: `IN_PROGRESS`.
*   `createdOn` (_integer (int64)_, required) Date and time when this inventory transfer is created. Represented as milliseconds since epoch.  
    Example: `1686607971000`.
*   `dueOn` (_integer (int64)_) Date and time when this inventory transfer is due. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `lastProcessedById` (_string_, required) ID for the person/entity who processed this inventory transfer.  
    Example: `2036`.
*   `lastProcessedByName` (_string_, required) Name for the person/entity who processed this inventory transfer.  
    Example: `Rob`.
*   `updatedOn` (_integer (int64)_, required) Date and time when this inventory transfer is last updated. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `vendorID` (_string_, required) Vendor ID.  
    Example: `1`.
*   `receivedOn` (_integer (int64)_, required) Date and time when this inventory transfer is received. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `cancelledOn` (_integer (int64)_, required) Date and time when this inventory transfer is cancelled. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `exportDate` (_integer (int64)_) Inventory transfer export time. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `itemStatus` (_string_, required) Inventory transfer item's status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. Example: `COMPLETE`.
*   `transferID` (_string_) Inventory transfer detail identifier.  
    Example: `409a92a5-834b-4500-b062-cedd89a38602`.
*   `palletID` (_string_, required) Pallet ID. Used to lookup specific transfer that has palletId.  
    Example: `A-4-PS00000001P1`.
*   `cartonID` (_string_, required) Carton ID. Used to lookup specific transfer that has cartonId.  
    Example: `A-4-PS00000001P1C1`.
*   `productID` (_string_, required) Product ID.  
    Example: `3661601594304`.
*   `vendorNumber` (_string_) Product vendor number.  
    Example: `607282`.
*   `externalDocNumber` (_string_) Product external doc number.  
    Example: `4900071859`.
*   `externalLineNumber` (_string_) Product external doc number.  
    Example: `00010`.
*   `productTitle` (_string_, required) Product title.  
    Example: `Wide-leg checked trousers`.
*   `productImageURL` (_string_, required) Product image URL.  
    Example: `https://us.maje.com/dw/image/v2/AAON_PRD/on/demandware.static/-/Sites-maje-catalog-master-H13/default/dw2b369dcf/images/h13/Maje_E18PERSE-1066_H_1.jpg`.
*   `quantityOrdered` (_integer (int32)_, required) Ordered quantity for each product in a transfer.  
    Example: `3`.
*   `quantityTransferred` (_integer (int32)_, required) Transferred quantity for each product in a transfer.  
    Example: `2`.
*   `quantityReceived` (_integer (int32)_, required) Received quantity for each product in a transfer.  
    Example: `1`.
*   `shipper` (_string_, required) Shipping supplier.  
    Example: `UPS`.
*   `shippedOn` (_integer (int64)_, required) Date and time when transfer is shipped. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `itemTrackingNumber` (_string_, required) Item tracking number.  
    Example: `TrackingIDPS00000001`.
*   `estimatedDeliveryOn` (_integer (int64)_, required) Date and time when transfer is expected to be delivered. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `deliveredOn` (_integer (int64)_) Date and time when transfer is delivered. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `receivedBy` (_string_, required) Received by ID.  
    Example: `2036`.
*   `reasonCode` (_string_, required) Item receive mismatch reason code.  
    Example: `1`.
*   `reasonText` (_string_, required) Item receive mismatch reason text.  
    Example: `Damaged`.
*   `color` (_string_) Product color.  
    Example: `Navy`.
*   `size` (_string_) Product size.  
    Example: `OS`.
*   `gtin` (_string_) Product gtin.  
    Example: `3661601593970`.
*   `isManualAdd` (_boolean_) Indicates if an item was manually added to the ASN, with true for manual additions and false for the item was existing.
*   `description` (_string_, required) Inventory transfer description.  
    Example: `Request for transfer from from store 1 to store 2`.
*   `serialNumbers` (_string_) Scanned Serial numbers.

### PurchaseOrderPayloadLine

Purchase order line items.

*   `transferType` (_string_, required) Inventory transfer type.  
    Allowed values: `ASN`, `CORP_TRANSFER`, `STORE_TO_STORE`, `BLIND_RECEIVE`, `RETURN_TO_VENDOR`, `PO`, `PO`. Example: `PO`.
*   `inventoryTransferID` (_string_, required) Purchase order identifier.  
    Example: `ITS00000001`.
*   `toID` (_string_, required) Purchase order recipient identifier. For example, Warehouse/Distribution center/Store ID.  
    Example: `1`.
*   `productCount` (_integer (int32)_, required) Total number of products in this inventory transfer.  
    Example: `10`.
*   `createdOn` (_integer (int64)_, required) Date and time when this order is created. Represented as milliseconds since epoch.  
    Example: `1686607971000`.
*   `productID` (_string_, required) Product ID.  
    Example: `3661601594304`.
*   `productTitle` (_string_, required) Product title.  
    Example: `Wide-leg checked trousers`.
*   `quantityOrdered` (_integer (int32)_, required) Ordered quantity for each product in a purchase order.  
    Example: `10`.
*   `costPrice` (_number_, required) Cost price of each item.  
    Example: `12.99`.
*   `casePackQuantity` (_integer (int32)_, required) Number of item per case pack.  
    Example: `8`.
*   `totalCost` (_number_, required) Total price of each item in an order, quantityOrdered \* costPrice.  
    Example: `129.9`.

### TransactionalInventoryProduct

products

List the products that require inventory adjustment.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.

<!-- document id=66fd3db8396607f9434dfb8eaec1b3e90ffcb4ebccef163b18116fcdf43ca823 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/impex.md -->

Inventory Impex (OCI)

# Inventory Impex (OCI)

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/impex/impex-oas-v1-public.yaml)

## API Overview

Inventory Impex APIs enable you to manage imports and exports of inventory availability for Omnichannel Inventory (OCI).

The API can be segregated into the following functional categories.

| Category | Endpoint Description |
| --- | --- |
| Inventory Imports and Exports | API endpoints for importing and exporting inventory availability data. |

**Note**: Omnichannel Inventory uses the Tenant Group ID in place of the Organization ID. For more information, see [Commerce API Configuration Values](https://developer.salesforce.com/docs/commerce/commerce-api/guide/commerce-api-configuration-values.html).

### Rate Limits

For load shedding and rate limiting information, see [Load Shedding and Rate Limiting.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html)

### Best Practices

For best practices information, see [Inventory Impex Best Practices.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/inventory-impex-best-practices.html)

### Authentication and Authorization

Clients calling Omnichannel Inventory can be authenticated in one of two ways.

*   Authenticate using Account Manager with your B2C Commerce credentials.
*   Authenticate using your Salesforce org credentials.

If you’re using both B2C Commerce and Salesforce Order Management, you can use either authentication approach. However, we recommend choosing only one to avoid mixing approaches across your integrations.

The different authentication approaches don’t impact the purpose or performance of the APIs.

Each authentication approach uses a unique set of scopes.

| Scopes for Account Manager Authentication | Scopes for Salesforce org Authentication |
| --- | --- |
| sfcc.inventory.impex-graphs | sfcc\_inventory\_impex\_graphs |
| sfcc.inventory.impex-inventory.rw | sfcc\_inventory\_impex\_inventory\_rw |
| sfcc.inventory.impex-inventory | sfcc\_inventory\_impex\_inventory |
| sfcc.inventory.availability | sfcc\_inventory\_availability |
| sfcc.inventory.availability.rw | sfcc\_inventory\_availability\_rw |
| sfcc.inventory.reservations | sfcc\_inventory\_reservations |
| sfcc.inventory.reservations.rw | sfcc\_inventory\_reservations\_rw |

Calls through the API gateway to Omnichannel Inventory must have a valid OAUTH bearer token. The tenant identifier used by Omnichannel Inventory is supplied in the header of the token.

All request and response body entities are composed in JSON.

### Use Cases

#### Availability Inventory Imports and Exports

Use these API endpoints to import and export item availability data and read deltas (changes).

Omnichannel Inventory stores items for each SKU, keeping a tally of the following item availability properties.

| Availability Property | Description |
| --- | --- |
| `Available to Fulfill` | Inventory that can be fulfilled now (`Quantity on Hand` - `Quantity Reserved`). |
| `Available to Order` | Inventory that can be ordered ((`Quantity on Hand` + `Future Inventory`) - `Quantity Reserved`). |
| `Quantity on Hand` | Inventory available, not counting `Future Inventory` or `Quantity Reserved`. |
| `Quantity Reserved` | Inventory reserved for fulfillment. |
| `Safety Stock Count` | Inventory quantity that is intentionally held back and not included in the counts of `Available to Order` or `Available to Fulfill` inventory. |
| `Future Inventory` | Inventory available for pre-order or backorder only. Inventory isn’t currently available and includes an expected in-stock date. |
| `Attribute Set` | Inventory attributes that can be applied to the item, for example: `groupEligibilityExclusion`. |

Use the availability-records imports _POST_ endpoint to initiate a load of the inventory availability data into Omnichannel Inventory. The details of the data being imported are included in the body of the _POST_ request.

The resulting response body from the initiate call contains a link to submit the actual import data stream/file. If the file being uploaded into the system is larger than 100 MB, the file _must_ be compressed with gzip.

After the file has been successfully uploaded to the OCI system, the status of the import can be checked by making calls to the availability-records imports status endpoint. When using this endpoint in conjunction with the importId used in the file upload, you can see if the import process has completed yet.

After the file has been successfully processed by OCI, the response body includes a status of _COMPLETED_. Other metrics regarding the import are also included, and can be found in the documentation for the _status_ call.

Also included in the _COMPLETED_ status is the _fullResults href_. Using this URI, you can retrieve the detailed results of the completed import process.

When performing an import for item availability records, the following endpoints should be used in this order:

1.  Initiate the import with a call to the imports _POST_ URI. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports`
2.  Use the uploadLink from the response body of step one to upload the data stream/file to OCI using a _POST_ call to the endpoint provided. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/uploadlink/{uploadLinkId}`
3.  After the file has been uploaded into OCI, you can use a _GET_ call to the importStatusLink that was provided in the response body to initiate call (step one) to check on the status of the processing of your import data. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/{importId}/status`
4.  After the status field in the response body returned from step 3 is _COMPLETED_, the import of the availability record data into OCI is complete. The status response includes a _fullResults href_ field that has a URI for retrieving the details about the completed import process. This information is retrieved with a _GET_ call to the provided URI. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/{importId}/file-content`

Following the steps in this order, with the endpoints indicated, allows you to successfully import availability records into OCI.

##### Location Inventory Import File Layout - High-Performance

It’s strongly encouraged that all new customer implementations use this import file layout. Existing customer implementations that use the legacy layout should also migrate to using this new layout so that they can capture the performance improvements. This layout combines the **Location Header** and **Location Inventory** _objects_ of the original specification, into 1 entity. The system doesn’t support mixing content of the original layout and the new one. The import file must be composed entirely using the High-Performance Layout or the Legacy Layout.

**Important**: In order to realize the performance improvement, the file must be constructed such that the SKUs are grouped together, as in the following example.

**Note**: The `mode` is assumed to be `UPDATE` since it's currently the only one supported.

`{"recordId":"0a87539d-f3dd-47bc-91c7-9c752e39dbe0","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"wickenburg"}`

`{"recordId":"3127e2ad-748b-459a-917c-78bef741602c","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"prescott"}`

`{"recordId":"b709e7a8-7d4f-4458-be0c-a88f1e594f1d","onHand":10,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"wickenburg"}`

`{"recordId":"b34c99ea-e659-40f7-bcb4-2a3fdc4a80b0","onHand":10,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]},"locationId":"prescott"}`

`{"recordId":"4bf7b40b-c965-485c-afa0-cc56a8ea70eb","onHand":10,"sku":"sku3","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"wickenburg"}`

`{"recordId":"539d41b7-5f05-4908-831b-3dd0461794fc","onHand":10,"sku":"sku3","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"prescott"}`

There are no other requirements for indicating that you’re using the High-Performance Layout. The system reads the file and automatically determines how to process it.

For information regarding the field contents, see the **Import Field Definitions** section below.

##### Location Inventory Import File Layout - CSV

CSV file imports are also supported. To submit a CSV file, the call to initiate the import must have the fileType field set to CSV. This allows you to submit a file in the following format.

Areas of interest in the CSV formatted import file are the header line, as well as the method for including futures. Because CSV files aren't ideal for handling nested structures like JSON files are, the futures must be represented in the manner shown. Using this format allows for two futures to be applied to each item during the import process.

Location ID,SKU,Quantity On Hand,Safety Stock,Effective Date,Future Date 1,Future Quantity 1,Future Date 2,Future Quantity 2,Group Eligibility Exclusion warehouse,red\_shirt,10,1,2020-04-08T14:05:22.790896-07:00,2020-04-18T14:05:22.781-07:00,10,2020-05-18T14:05:22.781-07:00,100,"\[G1, G2\]" warehouse-2,white\_shirt,200,10,2020-04-08T14:05:22.790896-07:00,,,,,

##### Location Inventory Import File Layout - Legacy

**Note**: The system still supports this import file layout, but due to lower performance, we recommend that users migrate away from using this layout. For more details, see the **Import File Layout High Performance** section.

The import data stream specifies inventory availability data by location and the kind of import operation Omnichannel Inventory should perform (for example, `UPDATE`, `DELETE`, or `REPLACE`). The stream consists of 2 types of json entities separated by line feeds: **Location Header** and **Location Inventory.**

For information regarding the field contents, see the **Import Field Definitions** section.

**Important**: The **Location Header** entity has a one-to-many relationship with the **Location Inventory** entity. For each Location Header, one or more Location Inventory entities should follow for the same location. Although placing a Location Header above each Location Inventory entity is allowed, it leads to _significantly slower_ import processing!

`{"location":"wickenburg","mode":"UPDATE"}`

`{"recordId":"0a87539d-f3dd-47bc-91c7-9c752e39dbe0","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0}`

`{"recordId":"f4bf981e-321e-42bd-851f-3573a3263ab1","onHand":5,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","safetyStockCount":1}`

##### Import Field Definitions

Location Header:

| Field | Description | Required Field |
| --- | --- | --- |
| `location` | The physical location where inventory is housed. | `TRUE` |
| `mode` | The type of system operation to perform. Currently, only `UPDATE` is supported | `TRUE` |

Location Inventory:

| Field | Description | Required Field |
| --- | --- | --- |
| `recordId` | Unique identifier of inventory record. | `TRUE` |
| `sku` | Unique item identifier. Cannot contain : \\ < > ; % / or spaces, tabs, and line breaks. | `TRUE` |
| `onHand` | The current quantity on hand. | `FALSE` |
| `effectiveDate` | The effective date of the `onHand` (ISO format). | `FALSE`, see the additional description below for more detail. |
| `futures` | A collection of future quantity information for the item. (See Future Quantity, below.) Note: the Inventory Availability API references `futures` in a collection called, `futureStock`. These are the same thing. | `FALSE`, If specified see the required fields below. |
| `attributeSet` | Attributes that can be applied to the item. (See Attribute Set, below for available attributes.) | `FALSE`, If specified see the required fields below. |
| `safetyStockCount` | The safety stock count. | `FALSE` |

Future Quantity:

| Field | Description | Required Field |
| --- | --- | --- |
| `quantity` | The quantity that will be arriving in the future. **The value must be greater than 0.** | `TRUE` |
| `expectedDate` | The date the future quantity is expected to arrive (ISO format). | `TRUE` |

Attribute Set:

| Field | Description | Required Field |
| --- | --- | --- |
| `groupEligibilityExclusion` | The groups that are excluded from aggregating the location/sku | `FALSE` |

The response from the call to submit contains a custom endpoint for checking the status and progress of the import. The status response contains a URI for the full result file for any records that failed to load, if there are any. Omnichannel Inventory also provides endpoints for querying and deleting import jobs.

Availability Effective Date:

The `effectiveDate` field represents the time the `onHand` value was accurate at the physical location. It’s used in conjunction with the reservation fulfillment field, `fulfillmentTime` to keep `onHand` in sync with the physical location. For example, if `effectiveDate` is specified on a location record, the system will optionally decrement the value of `onHand` when a Reservation Fulfillment is made. See the [Inventory Reservation API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=inventory-reservation-service:Summary) for more information on how Reservation Fulfillments work.

Example:

Import happens for SKU: `abc` at location: `123`, and the value of `onHand` accounts for a Reservation Fulfillment that hasn't yet processed in OCI.

Note: The JSON is shown formatted here, however in the actual import file it _must_ all be on a single line.

```
   {
    "recordId":"a26fe1fd-c413-4b74-8570-1ec185ca7192",
    "onHand":10,
    "sku":"abc",
    "effectiveDate":"2021-03-09T00:00:00.000000-07:00"
   }
```

Reservation Fulfillment Request happens after the import for SKU: `abc` at location: `123`

```
{
    "records": [
      {
        "id": "82251928-8863-488e-840b-2aebd10b57ba",
        "location": "123",
        "sku": "abc",
        "fulfillmentTime":"2021-03-08T00:00:00.000000-07:00"
        "quantity": 1
      }
    ]
  }
```

The system compares the values of `effectiveDate` and `fulfillmentTime`. Since `fulfillmentTime` is _less_ than `effectiveDate` it does _not_ decrement the value of `onHand`. If the reservation fulfillment happened first, `onHand` would be decremented (assuming the previous value of `effectiveDate` was less than `fulfillmentTime`). Then when the system performed the inventory import, the value of `onHand` would replace the previous value.

##### Location Inventory Import Result File Layout

The result file starts with a status line record.

`{"status": "COMPLETED_WITHOUT_ERRORS"}`

| Result Status | Description |
| --- | --- |
| `COMPLETED_WITHOUT_ERRORS` | Import completed without any errors. |
| `COMPLETED_WITH_PARTIAL_FAILURES` | Some records failed to load. |
| `FAILED` | Failed to load any records. |

Each line following the status line represents an error record.

`{"recordId": "2a3e769c-c981-4d96-ba6a-e0b821a5bbbb","locationId":"location1","sku": "sku1", "message": "Unknown"}`

| Field | Description | Required Field |
| --- | --- | --- |
| `recordId` | Unique identifier of inventory record sent in import file. | `TRUE` |
| `locationId` | Location identifier. | `TRUE` |
| `sku` | Unique item identifier of an item. Cannot contain : \\ < > ; % / or spaces, tabs, and line breaks. | `TRUE` |
| `message` | Message containing details for failure. | `TRUE` |

#### Product Segmentation Import

Use these API endpoints to import product segmentation data. This data allows SKUs to be excluded from a Location Group so customers can remove certain SKUs from a particular selling channel.

Use the product-segmentation imports _POST_ endpoint to initiate a load of the product segmentation data into Omnichannel Inventory. The details of the data being imported are included in the body of the _POST_ request.

The resulting response body from the initiate call contains a link to submit the actual import data stream/file. If the file being uploaded into the system is larger than 100 MB, the file _must_ be compressed with gzip.

After the file has been successfully uploaded to the OCI system, the status of the import can be checked by making calls to the product-segmentation imports status endpoint. When using this endpoint in conjunction with the importId used in the file upload, you can see if the import process has completed yet.

After the file has been successfully processed by OCI, the response body includes a status of _COMPLETED_. Other metrics regarding the import are also included, and can be found in the documentation for the _status_ call.

Also included in the _COMPLETED_ status is the _fullResults href_. Using this URI, you can retrieve the detailed results of the completed import process.

When performing an import for product segmentation data, the following endpoints should be used in this order:

1.  Initiate the import with a call to the imports _POST_ URI. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/imports`
2.  Use the uploadLink from the response body of step one to upload the data stream/file to OCI using a _POST_ call to the endpoint provided. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/imports/uploadlink/{uploadLinkId}`
3.  After the file has been completely uploaded into OCI, you can use a _GET_ call to the importStatusLink that was provided in the response body to initiate call (step one) to check on the status of the processing of your data. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/imports/{importId}/status`
4.  After the status field in the response body returned from step 3 is _COMPLETED_, the import of the product segmentation data into OCI is complete. The status response includes a _fullResults href_ field that has a URI for retrieving the details about the completed import process. This information is retrieved with a _GET_ call to the provided URI. `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/product-segmentation/exports/{exportId}/file-content`

Following the steps in this order, with the endpoints indicated, allows you to successfully import product segmentation records into OCI.

#### Product Segmentation Exclusion Import File Layout

The import data stream specifies the group that is affected by the data, as well as the kind of import operation Omnichannel Inventory should perform on the exclusion (for example, `REPLACE`, `APPEND`, or `REMOVE`). The stream consists of 2 types of json entities separated by line feeds: **Group Header** and **SKU Data.**

**Important:** The **Group Header** entity has a 1-to-many relationship with the **SKU Data** entity, in that for each Group Header, one or more SKU Data entities should follow for the same group. Though placing a Group Header above each SKU Data entity is allowed, it leads to **significantly slower** import processing!

`{"groupId":"G1","mode":"REPLACE"}`

`{"sku":"sku1"}`

`{"sku":"sku2"}`

`{"groupId":"G1","mode":"APPEND"}`

`{"sku":"sku37"}`

#### Exclusion Import Field Definitions

Group Header:

| Field | Description | Required Field |
| --- | --- | --- |
| `groupId` | The group that we’re acting upon for setting exclusions. | `TRUE` |
| `mode` | The type of system operation to perform for the group. `REPLACE` all entries for group, `APPEND` new entries to the group, or `REMOVE` a set of SKUs from the group exclusion. | `TRUE` |

SKU Data:

| Field | Description | Required Field |
| --- | --- | --- |
| `sku` | The unique item identifier for an item in the group that is to be excluded. Cannot contain : \\ < > ; % / or spaces, tabs, and line breaks. | `TRUE` |

#### Product Segmentation Export

The export file is a collection of complete JSON records containing the product segmentation data, one complete entry per line.

Use this endpoint to request a snapshot of the current product segmentation exclusions. You can request a snapshop for a list of groups or all groups by using group "\*". Omnichannel inventory provides another endpoint for checking the status and progress of this operation.

The finished export is retrieved with a link that is supplied in the status check response.  
When retrieving the status for any Export or Import process, the following responses are available.

| Export Status | Description |
| --- | --- |
| `STAGING` | The request is being created. |
| `WAITING` | For imports - waiting for file upload. |
| `EXPIRED` | Request has expired. |
| `SUBMITTED` | Request has been submitted for processing - not yet queued. |
| `PENDING` | Request is queued for processing - not yet started. |
| `RUNNING` | Request is running - not yet complete. |
| `COMPLETED` | Request has finished - results file location included in response. |
| `FAILED` | Request has failed - resubmit a new request to try again. |
| `STOPPED` | Request was stopped - resubmit a new request to try again. |

#### Export Download File Layout

The export file is a collection of complete JSON records, containing one complete element per line.

##### Group Line

`{"groupId":"UnitedStates"}`

| Group Indicator Line | Description |
| --- | --- |
| `groupId` | The group that the following detail records belong to. |

##### SKU Line

`{"sku":"sku121"}`

| Group Indicator Line | Description |
| --- | --- |
| `sku` | A sku identifier that is a member of that product segmentation exclusion group. |

#### Availability Export

The export file is a collection of complete JSON records containing one complete element per line.

Use this endpoint to request a snapshot of the current inventory availability with the criteria (for example, a single group, all groups, a single location, or all locations) specified in the body of the request. Omnichannel Inventory provides another endpoint for checking the status and progress of the operation.

The finished export is retrieved with a link supplied in the status check response. The exported data contains a delta token for getting changes since the export.

When retrieving the status for any Export or Import process, the following responses are available.

| Export Status | Description |
| --- | --- |
| `STAGING` | The request is being created. |
| `WAITING` | For imports - waiting for file upload. |
| `EXPIRED` | Request has expired. |
| `SUBMITTED` | Request has been submitted for processing - not yet queued. |
| `PENDING` | Request is queued for processing - not yet started. |
| `RUNNING` | Request is running - not yet complete. |
| `COMPLETED` | Request has finished - results file location included in response. |
| `FAILED` | Request has failed - resubmit a new request to try again. |
| `STOPPED` | Request was stopped - resubmit a new request to try again. |

#### Export Download File Layout

The export file is a collection of complete JSON records, containing one complete element per line.

**Note**: The Availability Export only supports exporting either groups or locations, but not both at the same time.

##### Group Line

`{"groupId":"UnitedStates"}`

| Group Indicator Line | Description |
| --- | --- |
| `groupId` | The group that the following detail records belong to. |

##### Location Line

`{"locationId":"phoenix"}`

| Group Indicator Line | Description |
| --- | --- |
| `locationId` | The location that the following detail records belong to. |

Item Record Lines - One Complete JSON Entry Per Line:

`{"sku":"123","onHand":10,"reserved":6,"groupReserved":6,"sharedGroupReserved":0,"atf":4,"ato":24,"safetyStockCount":1,"effectiveDate":"2019-07-20T11:04:02Z","futures":[{"quantity":20,"expectedDate":"2019-07-24T21:13:00Z"}]}`

| Field | Description | Required Field |
| --- | --- | --- |
| `sku` | Unique item identifier. Cannot contain : \\ < > ; % / or spaces, tabs, and line breaks. | `TRUE` |
| `onHand` | The current quantity on hand. | `TRUE` |
| `reserved` | The current quantity reserved. | `TRUE` |
| `atf` | The current quantity available to fulfill. | `TRUE` |
| `ato` | The current quantity available to place on order. | `TRUE` |
| `effectiveDate` | The effective date (ISO format. | `FALSE` |
| `groupReserved` | The total group reservations for the group NOT including shared. This field is present only for GROUP lines in the export. | `FALSE` |
| `sharedGroupReserved` | The amount of the soft reserved count that comes from other groups. This field is present only for GROUP lines in the export. | `FALSE` |
| `safetyStockCount` | The safety stock count. | `TRUE` |
| `futures` | A collection of future quantity information for the item, as described below. The Inventory Availability API references `futures` in a collection called `futureStock`. These are the same thing. | `TRUE` |
| `attributeSet` | A collection of attributes that can be applied to the item, for example: `groupEligibilityExclusion` | `FALSE` |

Future Quantity:

| Field | Description | Required Field |
| --- | --- | --- |
| `quantity` | The quantity that will be arriving in the future. | `TRUE` |
| `expectedDate` | The date the future quantity is expected to arrive (ISO format). | `TRUE` |

Delta Token Line:

`{"deltaToken": "dsfljasdflkjasdfkj2381238"}`

The value is used in the call to retrieve deltas. This delta token is valid for 23.5 hours, after which time it expires and a new token must be obtained with another export. See the [Inventory Availability API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=inventory-availability:Summary) for additional details.

#### Event Log Export

The export file is a collection of complete JSON records containing one complete element per line.

Use this endpoint to request the event log for a SKU within a certain set of locations and groups. Omnichannel Inventory provides another endpoint for checking the status and progress of the operation.

The finished export is retrieved with a link supplied in the status check response.

When retrieving the status for any Export or Import process, the following responses are available.

| Export Status | Description |
| --- | --- |
| `STAGING` | The request is being created. |
| `WAITING` | For imports - waiting for file upload. |
| `EXPIRED` | Request has expired. |
| `SUBMITTED` | Request has been submitted for processing - not yet queued. |
| `PENDING` | Request is queued for processing - not yet started. |
| `RUNNING` | Request is running - not yet complete. |
| `COMPLETED` | Request has finished - results file location included in response. |
| `FAILED` | Request has failed - resubmit a new request to try again. |
| `STOPPED` | Request was stopped - resubmit a new request to try again. |

#### Export Download File Layout

The export file is a collection of complete JSON records, containing one complete element per line.

##### Group Line

`{"groupId":"UnitedStates"}`

| Group Indicator Line | Description |
| --- | --- |
| `groupId` | The group that the following detail records belong to. |

##### Location Line

`{"locationId":"phoenix"}`

| Group Indicator Line | Description |
| --- | --- |
| `locationId` | The location that the following detail records belong to. |

Item Record Lines - One Complete JSON Entry Per Line:

`{"locationId":"newbraunfels"}{"eventType":"location_import","location":"newbraunfels","sequenceNumber":0,"quantity":10.0,"newReserved":0.0,`

`"newAto":11.0,"newOnHand":10.0,"newAtf":10.0,"newSoftReserved":0.0,"futureQuantity":1.0,"oldReserved":0.0,`

`"oldAto":0.0,"oldOnHand":0.0,"oldAtf":0.0,"oldSoftReserved":0.0,"createdTime":"2022-01-18T15:58:40.443Z",`

`"effectiveTime":"2020-04-08T14:05:22.795243-07:00","safetyStockCount":0.0}`

| Field | Description | Required Field |
| --- | --- | --- |
| `eventType` | The event type. | `TRUE` |
| `location` | The location associated with this event. | `TRUE` |
| `sequenceNumber` | The internal sequence number associated with the event. | `TRUE` |
| `quantity` | The item quantity. | `TRUE` |
| `newReserved` | The new reserved amount for the SKU and location. | `TRUE` |
| `newAto` | The new ATO for the item. | `TRUE` |
| `newOnHand` | The new on hand amount for the item. | `TRUE` |
| `newAtf` | The new ATF amount for the item. | `TRUE` |
| `newSoftReserved` | The new soft reservation amount for the item. | `TRUE` |
| `futureQuantity` | The future quantity for the item. | `TRUE` |
| `oldReserved` | The old reserved amount for the item, before the event took place. | `TRUE` |
| `oldAto` | The old ATO for the item, before the event took place. | `TRUE` |
| `oldOnHand` | The old on hand amount for the item, before the event took place. | `TRUE` |
| `oldAtf` | The old ATF amount for the item, before the event took place. | `TRUE` |
| `oldSoftReserved` | The old soft reserved amount, before the event took place. | `TRUE` |
| `createdTime` | The time the event was created. | `TRUE` |
| `effectiveTime` | The effective time of the event. | `TRUE` |
| `safetyStockCount` | The safety stock count value for the item. | `TRUE` |

#### Reservations Export

Use this endpoint to request the reservation documents within a certain set of dates and reservation status values. The current supported status values for a reservation are "open" and "closed". Omnichannel Inventory provides endpoints for initiating the export, checking the status and progress of the export, and for downloading the actual export file when it is complete.

The finished export is retrieved with a link supplied in the status check response.

When retrieving the status for any Export or Import process, the following responses are available.

| Export Status | Description |
| --- | --- |
| `STAGING` | The request is being created. |
| `WAITING` | For imports - waiting for file upload. |
| `EXPIRED` | Request has expired. |
| `SUBMITTED` | Request has been submitted for processing - not yet queued. |
| `PENDING` | Request is queued for processing - not yet started. |
| `RUNNING` | Request is running - not yet complete. |
| `COMPLETED` | Request has finished - results file location included in response. |
| `FAILED` | Request has failed - resubmit a new request to try again. |
| `STOPPED` | Request was stopped - resubmit a new request to try again. |

#### Export Download File Layout

The export file is a collection of complete JSON records, containing one reservation record per reservationId.

##### Header Info

{  
    "reservationId" : "5baf4a87-1841-4311-9ca9-601e5d32885b",  
    "externalRefId" : "OCI-1234567",  
    "reservationTime" : 1648718653000,  
    "reservationState" : "CLOSED",  
    "reservationDetails" : \[\]  
}

| Header Field Info | Description |
| --- | --- |
| `reservationId` | The reservationId for the exported reservation. |
| `externalRefId` | The external reference identifier for the exported reservation. This value correlates to a value in an external ordering system. |
| `reservationTime` | The time that was applied to the reservation when it was placed. |
| `reservationState` | The current state of the reservation. Current supported values are "open" and "closed". |
| `reservationDetails` | An array containing the details of the reservation in question. |

##### Reservation Details

The reservationDetails field contains an array of info related to the exported reservation.

"reservationDetails" : {  
    "group": "ACME\_US",  
    "sku" : "white-shirt-40",  
    "quantity" : 5,  
    "reservationDetailActions" \[\]  
}

| Reservation Details Info | Description |
| --- | --- |
| `group or location` | Whether this detail item is associated with a group or a location. |
| `sku` | The SKU identifier associated with this detail line. |
| `quantity` | The quantity applied to the reservation line item. |
| `reservationDetailActions` | An array of actions that have taken place for this line item in the reservation. |

##### Reservation Detail Actions

The reservationDetailActions is an array of entries tracking the actions taken on a particular reservation document. "reservationDetailActions" : \[  
      {  
         "requestId" : "3678-23456-3456-4567-9999-1232",  
         "externalRefId" : "1234561-4949-2345",  
         "quantity" : 5,  
         "action" : Reserverd,  
         timestamp : "16487200010000"  
      }  
    \]

| Reservation Actions Detail | Description |
| --- | --- |
| `requestId` | The request ID associated with this reservation action. |
| `externalRefId` | The external reference identifier for the exported action. This value correlates to a value in an external ordering system. |
| `quantity` | The quantity associated with this reservaiton action. |
| `action` | The action that was taken against this line item. |
| `timestamp` | The time that the action was taken. |

### Common Response Codes

The following error codes apply to all API endpoints. See the API documentation for a complete list of the error codes and response bodies that can be expected on each endpoint.

*   401 - The OATH bearer token isn’t valid for the tenant or is no longer valid. The response body has the details.
*   403 - The tenant isn’t provisioned in the system.
*   5XX - There was a server error. The response body has the details.
*   Unknown - If an Unknown error type is returned, it indicates that an unknown internal error occurred.

### External Reference Identifier

Currently, there are a number of places where a consumer can submit an `ExternalRefId` with their request. This is to allow the consumer to submit user-generated data along with their request as a link to other external systems data. For example, if I'm pulling data from an order that has an order ID, I can submit that order ID with my reservation request as the `externalRefId`. Then, if there is a problem with the reservation, there is a way to connect it with the order in the external system that generated the error or problem. This is NOT to be confused with `externalRefId` used in Salesforce Core, or any other services. The usage is exclusive to OCI and is not used anywhere else.

### Correlation-ID

In order to facilitate tracking of operations in OCI, customers must populate a header with the name Correlation-ID, which will be passed through the CDN and sent with the request to OCI. This will help trace requests as they move throughout our service. To be accepted, the correlation-id must be a valid UUIDv2, otherwise, it will be ignored.

When a web-request is passed through the CDN, the CDN's x-correlation-id header value (which comes from their ray-id) also comes into play. In this case, the correlation-id provided will be prepended to the CDN's x-correlation-id and both values will be passed through, separated by a comma.

Some services use a header X-Correlation-ID. In the case of OCI, if this header is used, it is overwritten by the CDN with a new value and the initial purpose of the header is defeated. Use the Correlation-ID instead for a consistent result.

### NoOp Inventory Records

An import record is considered a NoOp or NoOperation record if it does not change any of the following:

1.  onHand
2.  SafetyStockCount
3.  Futures (any of the values)
4.  AttributeSet (any of the values)

Consequently, NoOp inventory records will be skipped and not be reflected in the event log.

**Version:** 1.1.30

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.inventory.impex-graphs: Impex Graphs READONLY scope
    *   Scope sfcc\_inventory\_impex\_graphs: Impex Graphs READONLY scope
    *   Scope sfcc.inventory.impex-inventory: Impex Inventory READONLY scope
    *   Scope sfcc\_inventory\_impex\_inventory: Impex Inventory READONLY scope
    *   Scope sfcc.inventory.impex-inventory.rw: Impex Inventory scope
    *   Scope sfcc\_inventory\_impex\_inventory\_rw: Impex Inventory scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.inventory.impex-graphs: Impex Graphs READONLY scope
    *   Scope sfcc\_inventory\_impex\_graphs: Impex Graphs READONLY scope
    *   Scope sfcc.inventory.impex-inventory: Impex Inventory READONLY scope
    *   Scope sfcc\_inventory\_impex\_inventory: Impex Inventory READONLY scope
    *   Scope sfcc.inventory.impex-inventory.rw: Impex Inventory scope
    *   Scope sfcc\_inventory\_impex\_inventory\_rw: Impex Inventory scope

## Operations

### POST Exports the entire location graph for the specified organization.

`POST /organizations/{organizationId}/location-graph/exports`

Operation ID: `getLocationGraphExport`. Security: AmOAuth2 (sfcc.inventory.impex-graphs, sfcc\_inventory\_impex\_graphs).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully initiated location graph export.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InitiateLocationGraphExportResponse`.
    
    _Example: initiateLocationGraphExportSuccess_
    
    ```
    {
      "exportId": "a218f4b2-2dc3-4ea8-af6d-c75fafd62323",
      "exportStatusLink": "/inventory/impex/v1/organizations/391e7478-2d3a-414d-92fd-a2735dabfed2/location-graph/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/status"
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: getLocationGraphExport400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "The field 'quantity' is missing from the request body."
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example: getLocationGraphExport403_
    
    ```
    {
      "timestamp": "2020-07-06T18:10:45.927+0000",
      "status": 403,
      "error": "Forbidden",
      "message": "No message available",
      "path": "/inventory/impex/v1/organizations/myOrgId/location-graph/exports"
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### DELETE Delete the location graph export for the specified export ID.

`DELETE /organizations/{organizationId}/location-graph/exports/{exportId}`

Operation ID: `deleteLocationGraphExports`. Security: AmOAuth2 (sfcc.inventory.impex-graphs, sfcc\_inventory\_impex\_graphs).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the location graph.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: EntityNotFoundExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ExportInProcessExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Download the generated location graph export file.

`GET /organizations/{organizationId}/location-graph/exports/{exportId}/file-content`

Operation ID: `downloadLocationGraphExportFile`. Security: AmOAuth2 (sfcc.inventory.impex-graphs, sfcc\_inventory\_impex\_graphs).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully downloaded the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ExportLocationGraphDownloadFile`.
    
    _Example: downloadLocationGraphExportFileSuccess_
    
    ```
    {
      "locations": [
        "l5b39d13d-0426-4349-95cb-93479e2f0166",
        "l4b17f6a0-b4e6-43a1-bfee-a4a2db37b3f2",
        "ld3b3090b-11c0-4c7d-bb5f-0ca88c7da8f8",
        "ld66d773d-42d0-4915-b5c5-4e981132e829",
        "l204d0639-130d-4197-9fff-65d8aa4becc5"
      ],
      "groups": [
        {
          "id": "8ae8b814-0b28-4710-8c3c-8ed95abed62e",
          "locations": [
            "l4b17f6a0-b4e6-43a1-bfee-a4a2db37b3f2",
            "ld3b3090b-11c0-4c7d-bb5f-0ca88c7da8f8"
          ]
        },
        {
          "id": "a218f4b2-2dc3-4ea8-af6d-c75fafd62256",
          "locations": [
            "l5b39d13d-0426-4349-95cb-93479e2f0166",
            "ld66d773d-42d0-4915-b5c5-4e981132e829",
            "l204d0639-130d-4197-9fff-65d8aa4becc5"
          ]
        }
      ]
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** The location graph export ID does not exist.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadLocationGraphExportFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadLocationGraphExportFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **410** The download link is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadLocationGraphExportFile410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredResultLink",
      "message": "The download link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve the status of the location graph export for the organization.

`GET /organizations/{organizationId}/location-graph/exports/{exportId}/status`

Operation ID: `getLocationGraphExportStatus`. Security: AmOAuth2 (sfcc.inventory.impex-graphs, sfcc\_inventory\_impex\_graphs).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved location group export status.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ExportLocationGraphStatusResponse200`.
    
    _Example: getLocationGraphExportStatusSuccess_
    
    ```
    {
      "id": "a218f4b2-2dc3-4ea8-af6d-c75fafd62256",
      "status": "COMPLETED",
      "export": {
        "startTimeUTC": "2020-04-15T21:21:23.675Z",
        "endTimeUTC": "2020-04-15T21:21:23.812Z",
        "recordsProcessedCount": 7,
        "recordsExportedCount": 7
      },
      "download": {
        "downloadLink": "/inventory/impex/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/location-graph/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62256/file-content",
        "downloadLinkExpirationUTC": "2020-04-16T15:21:21.93-06:00"
      },
      "validation": {
        "fileHash": "15fba5d9facf494749b9cfabdc2c8fe1c73d974b9579bc67ab293e607f3c92bb",
        "fileHashType": "SHA-256",
        "fileSize": 607
      }
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: getLocationGraphExportStatus404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve a collection of import job IDs. You can query the list of import jobs and retrieve the full collection in the response body. You can also filter the collection to only include imports where the upload link is valid or invalid (expired).

`GET /organizations/{organizationId}/availability-records/imports`

Operation ID: `getInventoryImport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `available` (query, boolean) Setting available to 'true' causes the response to only include imports where the upload link is still available and has not expired.  
    Example: `true`.

#### Responses

*   **200** Successfully retrieved a JSON array with a collection of import ID values.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `GetRunningImportsResponse`.
    
    _Example: getInventoryImportSuccess_
    
    ```
    {
      "imports": [
        "d88e54c5-23ed-4e33-a6a9-c31dc810662b",
        "da39a3ee-5e6b-4b0d-3255-bfef95601890",
        "a94a8fe5-ccb1-9ba6-1c4c-0873d391e987"
      ]
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: getInventoryImport400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "The field 'quantity' is missing from the request body."
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Submit an inventory import.

`POST /organizations/{organizationId}/availability-records/imports`

Operation ID: `submitInventoryImport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InitiateImportRequestBody`.

_Example: initiateImportRequest_

```
{
  "fileName": "inventory.json",
  "fileFormat": "JSON",
  "fileEncoding": "GZIP",
  "fileHash": "15fba5d9facf494749b9cfabdc2c8fe1c73d974b9579bc67ab293e607f3c92bb",
  "fileHashType": "SHA-256",
  "linkDuration": 60
}
```

#### Responses

*   **200** Successfully submitted import.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InitiateImportResponse200`.
    
    _Example: initiateImportSuccess_
    
    ```
    {
      "importId": "d88e54c5-23ed-4e33-a6a9-c31dc810662b",
      "importStatusLink": "/inventory/impex/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/availability-records/imports/d88e54c5-23ed-4e33-a6a9-c31dc810662b/status",
      "uploadLink": "/inventory/impex/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/availability-records/imports/uploadlink/d88e54c5-23ed-4e33-a6a9-c31dc810662b",
      "uploadMethod": "POST",
      "uploadLinkExpirationUTC": "2019-06-07T15:10:04.357Z"
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: submitInventoryImport400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "The field 'quantity' is missing from the request body."
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### DELETE Mark a single import for deletion.

`DELETE /organizations/{organizationId}/availability-records/imports/{importId}`

Operation ID: `deleteInventoryImport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `importId` (path, UniqueId, required) The import ID to act upon.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the requested import job.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: EntityNotFoundExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Import in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ImportInProgressExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ImportInProgress",
      "message": "Import 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve status for the specified import ID.

`GET /organizations/{organizationId}/availability-records/imports/{importId}/status`

Operation ID: `getAvailabilityImportStatus`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `importId` (path, UniqueId, required) The import ID to act upon.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved import status.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ImportStatusResponse200`.
    
    _Example: getAvailabilityImportStatusSuccess_
    
    ```
    {
      "importId": "a218f4b2-2dc3-4ea8-af6d-c75fafd62256",
      "status": "COMPLETED",
      "validation": {
        "status": "Success",
        "errors": []
      },
      "upload": {
        "fileName": "test.json"
      },
      "import": {
        "startTimeUTC": "2020-02-12T22:53:06.788Z",
        "endTimeUTC": "2020-02-12T22:53:08.423Z",
        "recordsProcessedCount": 4,
        "recordsReadCount": 4,
        "recordsSkippedCount": 0,
        "fullResults": {
          "href": "/v2/tenants/AtsisIntegrationTenant/availability-records/imports/a218f4b2-2dc3-4ea8-af6d-c75fafd62256/file-content",
          "exportResultExpirationUTC": "2020-02-13T15:53:05.005-07:00"
        }
      }
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: EntityNotFoundExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve the import file results for the specified import ID.

`GET /organizations/{organizationId}/availability-records/imports/{importId}/file-content`

Operation ID: `downloadAvailabilityImportResultsFile`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `importId` (path, UniqueId, required) The import ID to act upon.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved availability import results file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/octet-stream`. Schema: `string (binary)`.
    
    Type: `string (binary)`.
    
    _Example: CompletedWithPartialFailures_
    
    ```
    {"recordId": "3dd924fb-2fd5-4f49-80de-6ee49439c1f0",
    "locationId": "wickenburg",
    "sku": 1,
    "message": "'quantity' quantity must be a positive value"}
    ```
    
    _Example: CompletedWithoutErrors_
    
    ```
    {"status": "COMPLETED_WITHOUT_ERRORS"}
    ```
    
    _Example: Failed_
    
    ```
    {"status": "FAILED"}
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadAvailabilityImportResultsFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Import in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadAvailabilityImportResultsFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ImportInProgress",
      "message": "Import 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Upload an import file. <br> The gateway has a filesize limit of 100MB. <br> If the file is larger than 100MB, send it in compressed format. The supported algorithm is GZIP.

`POST /organizations/{organizationId}/availability-records/imports/uploadlink/{uploadLinkId}`

Operation ID: `postUploadImportFile`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `uploadLinkId` (path, UniqueId, required) The ID of the import being uploaded.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `multipart/form-data`. Schema: `object`.

*   `file` (_string (binary)_, required)

_Example: ImportsUploadLinkFileContents_

```
{"location":"wickenburg","mode":"UPDATE"}
{"recordId":"0a87539d-f3dd-47bc-91c7-9c752e39dbe0","onHand":10,"sku":"1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"attributeSet":{"groupEligibilityExclusion":["GroupA","GroupB"]}}
{"recordId":"f4bf981e-321e-42bd-851f-3573a3263ab1","onHand":5,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","safetyStockCount":1,"attributeSet":{"groupEligibilityExclusion":["GroupB","GroupC"]}}
```

#### Responses

*   **200** Successfully started the file upload. Details are available in the response body.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ImportUploadLinkResponse200`.
    
    _Example: importUploadSuccess_
    
    ```
    {
      "status": "COMPLETED",
      "importId": "d88e54c5-23ed-4e33-a6a9-c31dc810662b"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: postUploadImportFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Already received the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: postUploadImportFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ImportInProgress",
      "message": "Import 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **410** The uploadLink URI is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: postUploadImportFile410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredResultLink",
      "message": "The download link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Submit product segmentation data import. Whenever a location graph import removes an existing group that has product segmentation applied, the segmentation data are removed. If the group is put back in place, the product segmentation info must be re-applied with a new import.

`POST /organizations/{organizationId}/product-segmentation/imports`

Operation ID: `submitProductSegmentationImport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InitiateProductSegmentationImportRequestBody`.

_Example: initiateProductSegmentationImportRequest_

```
{
  "fileName": "product_segmentation_data_import.json",
  "linkDuration": 60
}
```

#### Responses

*   **200** Successfully initiated import.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InitiateProductSegmentationImportResponse200`.
    
    _Example: initiateProductSegmentationImportSuccess_
    
    ```
    {
      "importId": "d88e54c5-23ed-4e33-a6a9-c31dc810662b",
      "importStatusLink": "/v2/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/product-segmentation/imports/d88e54c5-23ed-4e33-a6a9-c31dc810662b/status",
      "uploadLink": "/v2/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/product-segmentation/imports/uploadlink/d88e54c5-23ed-4e33-a6a9-c31dc810662b",
      "uploadMethod": "POST",
      "uploadLinkExpirationUTC": "2019-07-24T21:13:00Z"
    }
    ```
    
*   **400** Invalid request
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: submitProductSegmentationImport400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "link duration must be numeric"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### DELETE Mark a single product segmentation data import for deletion.

`DELETE /organizations/{organizationId}/product-segmentation/imports/{importId}`

Operation ID: `deleteProductSegmentationImport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `importId` (path, UniqueId, required) The import ID to act upon.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted the requested SKU exclusion import job.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: EntityNotFoundExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Import in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ImportInProgressExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ImportInProgress",
      "message": "Import 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve the import file results for the specified import ID. The current request limit for each tenant is 40 requests per second.

`GET /organizations/{organizationId}/product-segmentation/imports/{importId}/file-content`

Operation ID: `downloadProductSegmentationImportResults`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `importId` (path, UniqueId, required) The import ID to act upon.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully downloaded the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/octet-stream`. Schema: `string (binary)`.
    
    Type: `string (binary)`.
    
    _Example: downloadProductSegmentationImportResults200_
    
    ```
    {"groupId":"florida"}
    {"groupId":"texas"}
    {"sku":"21"}
    {"sku":"31"}
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadProductSegmentationImportResults404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadProductSegmentationImportResults409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **410** The download link is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadProductSegmentationImportResults410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredResultLink",
      "message": "The download link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve status for the specified import ID.

`GET /organizations/{organizationId}/product-segmentation/imports/{importId}/status`

Operation ID: `getProductSegmentationImportStatus`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `importId` (path, UniqueId, required) The import ID to act upon.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved product segmentation import status.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ProductSegmentationImportStatusResponse`.
    
    _Example: getProductSegmentationImportStatusSuccess_
    
    ```
    {
      "importId": "a218f4b2-2dc3-4ea8-af6d-c75fafd62256",
      "status": "COMPLETED",
      "validation": {
        "status": "Success",
        "errors": []
      },
      "upload": {
        "fileName": "test.json"
      },
      "import": {
        "startTimeUTC": "2020-02-12T22:53:06.788Z",
        "endTimeUTC": "2020-02-12T22:53:08.423Z",
        "recordsProcessedCount": 4,
        "recordsReadCount": 4,
        "recordsSkippedCount": 0,
        "fullResults": {
          "href": "/v2/tenants/8f714039-2808-4104-b444-5e8f9d923d6e/availability-records/imports/a218f4b2-2dc3-4ea8-af6d-c75fafd62256/file-content",
          "exportResultExpirationUTC": "2020-02-13T15:53:05.005-07:00"
        }
      }
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: getProductSegmentationImportStatus404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Upload an import file. <br> The gateway has a filesize limit of 100MB. <br> If the file is larger than 100MB, send it in compressed format. The supported algorithm is GZIP.

`POST /organizations/{organizationId}/product-segmentation/imports/uploadlink/{uploadLinkId}`

Operation ID: `postProductSegmentationUploadImportFile`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `uploadLinkId` (path, UniqueId, required) The ID of the import being uploaded.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `multipart/form-data`. Schema: `object`.

*   `file` (_string (binary)_, required)

_Example: ProductSegmentationUploadImportFileContents_

```
{"groupId":"G1","mode":"REPLACE"}
{"sku":"sku1"}
{"sku":"sku2"}
```

#### Responses

*   **200** Successfully started the file upload. Details are available in the response body.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ImportProductSegmentationUploadLinkResponse200`.
    
    _Example: productSegmentationUploadSuccess_
    
    ```
    {
      "status": "PENDING",
      "importId": "d88e54c5-23ed-4e33-a6a9-c31dc810662b"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: postProductSegmentationUploadImportFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Already received the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: postProductSegmentationUploadImportFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "FileAlreadyReceived",
      "message": "The file for this uploadLink has already been received."
    }
    ```
    
*   **410** The uploadLink URI is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: postProductSegmentationUploadImportFile410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredUploadLink",
      "message": "The upload link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Initiate an export of the Product Segmentation rules in the system.

`POST /organizations/{organizationId}/product-segmentation/exports`

Operation ID: `initiateProductSegmentationExport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InitiateSegmentationExportBody`.

_Example: InitiateInventoryProductSegmentationExportByGroups_

```
{
  "groups": [
    "texas",
    "florida"
  ]
}
```

#### Responses

*   **200** Successfully submitted request to initiate Product Segmentation Export.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InitiateProductSegmentationExportResponse200`.
    
    _Example: initiateProductSegmentationExportSuccess_
    
    ```
    {
      "exportId": "323b0g69-d37d-423a-84f5-8f393fe80459",
      "exportStatusLink": "/inventory/impex/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/product-segmentation/exports/pe-0377a512-d107-40a0-b966-bad5a021d21f/status"
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ProductSegmentationExportInvalidRequestParameter400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "Invalid Group Id Provided."
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### DELETE Delete a single export ID. The current request limit for each tenant is 120 requests per second.

`DELETE /organizations/{organizationId}/product-segmentation/exports/{exportId}`

Operation ID: `deleteProductSegmentationExport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted a single export group ID.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: 404EntityNotFoundError_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: 409ExportInProcessError_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Download the generated Product Segmentation export file. The current request limit for each tenant is 40 requests per second.

`GET /organizations/{organizationId}/product-segmentation/exports/{exportId}/file-content`

Operation ID: `downloadProductSegmentationExportFile`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully downloaded the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/octet-stream`. Schema: `string (binary)`.
    
    Type: `string (binary)`.
    
    _Example: downloadProductSegmentationExportFile_
    
    ```
    {"groupId":"florida"}
    {"groupId":"texas"}
    {"sku":"21"}
    {"sku":"31"}
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadProductSegmentationExportFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadProductSegmentationExportFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **410** The download link is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadProductSegmentationExportFile410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredResultLink",
      "message": "The download link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve status information for a single export ID. The current request limit for each tenant is 120 requests per second.

`GET /organizations/{organizationId}/product-segmentation/exports/{exportId}/status`

Operation ID: `retrieveProductSegmentationExportStatus`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved export status.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ExportProductSegmentationStatusResponse200`.
    
    _Example: retrieveProductSegmentationExportStatusSuccess_
    
    ```
    {
      "id": "323b0g69-d37d-423a-84f5-8f393fe80459",
      "status": "COMPLETED",
      "export": {
        "startTimeUTC": "2019-07-24T21:13:00Z",
        "endTimeUTC": "2019-07-24T21:13:00Z",
        "recordsProcessedCount": 2000,
        "recordsExportedCount": 2000
      },
      "download": {
        "downloadLink": "/inventory/impex/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/product-segmentation/exports/pe-0377a512-d107-40a0-b966-bad5a021d21f/file-content",
        "downloadLinkExpirationUTC": "2019-07-24T21:13:00Z"
      },
      "validation": {
        "fileHashType": "SHA-256",
        "fileHash": "e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922",
        "fileSize": 5231942
      }
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: retrieveProductSegmentationExportStatus404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Initiate an export of group or location level inventory availability. The current request limit for each tenant is 120 requests per second.

`POST /organizations/{organizationId}/availability-records/exports`

Operation ID: `initiateAvailabilityExport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InitiateAvailabilityExportBody`.

_Example: Locations_

```
{
  "objects": {
    "locations": [
      "warehouse5",
      "warehouse6"
    ]
  }
}
```

_Example: Groups_

```
{
  "objects": {
    "groups": [
      "UnitedStates",
      "Germany"
    ]
  }
}
```

#### Responses

*   **200** Successfully submitted request to initiate export.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InitiateGroupExportResponse200`.
    
    _Example: initiateAvailabilityExportSuccess_
    
    ```
    {
      "exportId": "323b0g69-d37d-423a-84f5-8f393fe80459",
      "exportStatusLink": "/inventory/inventory-availability/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/availability-records/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/status"
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: LocationsAndGroupsError_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "Locations and Groups not allowed in the same request."
    }
    ```
    
    _Example: LocationDoesNotExistError_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "LocationDoesNotExist",
      "message": "No location exists with ID 'abc'"
    }
    ```
    
    _Example: GroupDoesNotExistError_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "GroupDoesNotExist",
      "message": "No group exists with ID 'abc'"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### DELETE Delete a single export ID. The current request limit for each tenant is 120 requests per second.

`DELETE /organizations/{organizationId}/availability-records/exports/{exportId}`

Operation ID: `deleteAvailabilityExport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted batches of export group inventory availability.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: NotFound_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ConflictSample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Download the generated inventory availability export file. The current request limit for each tenant is 40 requests per second.

`GET /organizations/{organizationId}/availability-records/exports/{exportId}/file-content`

Operation ID: `downloadAvailabilityExportFile`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully downloaded the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/octet-stream`. Schema: `string (binary)`.
    
    Type: `string (binary)`.
    
    _Example: downloadAvailabilityExportFile_
    
    ```
    {"groupId":"UnitedStates"} 
    {"sku":"123","onHand":10,"reserved":6,"atf":4,"ato":24,"futures":[{"quantity":20,"expectedDate":"2019-07-24T21:13:00Z"}], "groupReserved":4,"sharedGroupReserved":2} 
    {"sku":"456","onHand":100.25,"reserved":50.25,"atf":50,"ato":50, "groupReserved":45.25,"sharedGroupReserved":5.00} 
    {"groupId":"Germany"} 
    {"sku":"789","onHand":1000,"reserved":500,"atf":500,"ato":500, "groupReserved":500,"sharedGroupReserved":500} 
    {"sku":"012","onHand":15000,"reserved":1500,"atf":13500,"ato":13500, "groupReserved":1000,"sharedGroupReserved":500} 
    {"deltaToken":"eyJncm91cHMiOlsiRXhwb3J0LUdyb3VwMSIsIkV4cG9ydC1Hcm91cDIiXSwiaW50ZXJuYWxJZHMiOlsxMzgsMTM3XSwidHlwZSI6IkdST1VQX0VYUE9SVCJ9"}
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadAvailabilityExportFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadAvailabilityExportFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **410** The download link is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadAvailabilityExportFile410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredResultLink",
      "message": "The download link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve status information for a single export ID. The current request limit for each tenant is 120 requests per second.

`GET /organizations/{organizationId}/availability-records/exports/{exportId}/status`

Operation ID: `retrieveGroupExportStatus`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved export status.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ExportGroupStatusResponse200`.
    
    _Example: retrieveGroupExportStatusSuccess_
    
    ```
    {
      "id": "323b0g69-d37d-423a-84f5-8f393fe80459",
      "status": "COMPLETED",
      "export": {
        "startTimeUTC": "2019-07-24T21:13:00Z",
        "endTimeUTC": "2019-07-24T21:13:00Z",
        "recordsProcessedCount": 2000,
        "recordsExportedCount": 2000,
        "groups": [
          "UnitedStates"
        ]
      },
      "download": {
        "downloadLink": "/v2/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/availability-records/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/file-content",
        "downloadLinkExpirationUTC": "2019-07-24T21:13:00Z"
      },
      "validation": {
        "fileHashType": "SHA-256",
        "fileHash": "e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922",
        "fileSize": 5231942
      }
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: retrieveGroupExportStatus404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Submit events activity export.

`POST /organizations/{organizationId}/event-log/exports`

Operation ID: `submitEventsActivityExport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InitiateEventActivityExportRequestBody`.

_Example: initiateEventActivityExportRequest_

```
{
  "endsOn": "2022-04-10T15:41:25.553Z",
  "locations": [
    "warehouse1",
    "warehouse2"
  ],
  "sku": "dcbd797a-73e7-11ec-90d6-0242ac120003",
  "groups": [
    "united-states"
  ],
  "startsOn": "2022-03-19T15:41:25.553Z",
  "fileFormat": "CSV"
}
```

#### Responses

*   **200** Successfully submitted export.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InitiateEventLogExportResponse200`.
    
    _Example: initiateEventActivityExportSuccess_
    
    ```
    {
      "exportId": "e-d88e54c5-23ed-4e33-a6a9-c31dc810662b",
      "exportStatusLink": "/inventory/impex/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/event-log/exports/e-d88e54c5-23ed-4e33-a6a9-c31dc810662b/status"
    }
    ```
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: submitEventsActivityExport400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "'sku' Invalid characters in sku: null"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve status information for a single export ID. The current request limit for each tenant is 120 requests per second.

`GET /organizations/{organizationId}/event-log/exports/{exportId}/status`

Operation ID: `retrieveEventLogExportStatus`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved export status.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ExportEventLogStatusResponse200`.
    
    _Example: retrieveEventLogExportStatusSuccess_
    
    ```
    {
      "id": "323b0g69-d37d-423a-84f5-8f393fe80459",
      "status": "COMPLETED",
      "export": {
        "startTimeUTC": "2019-07-24T21:13:00Z",
        "endTimeUTC": "2019-07-24T21:13:00Z",
        "recordsProcessedCount": 2000,
        "recordsExportedCount": 2000,
        "groups": [
          "UnitedStates"
        ]
      },
      "download": {
        "downloadLink": "/v2/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/event-log/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/file-content",
        "downloadLinkExpirationUTC": "2019-07-24T21:13:00Z"
      },
      "validation": {
        "fileHashType": "SHA-256",
        "fileHash": "e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922",
        "fileSize": 5231942
      }
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: retrieveEventLogExportStatus404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Download the generated events activity export file.

`GET /organizations/{organizationId}/event-log/exports/{exportId}/file-content`

Operation ID: `downloadEventsActivityExportFile`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully downloaded the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/octet-stream`. Schema: `string (binary)`.
    
    Type: `string (binary)`.
    
    _Example: downloadEventsActivityExportFile_
    
    ```
    {"locationId":"weimar"} 
    {"locationId":"newbraunfels"} 
    {"eventType":"location_import","location":"newbraunfels","sequenceNumber":0,"quantity":10.0,"newReserved":0.0,"newAto":11.0,"newOnHand":10.0,"newAtf":10.0,"newSoftReserved":0.0,"futureQuantity":1.0,"oldReserved":0.0,"oldAto":0.0,"oldOnHand":0.0,"oldAtf":0.0,"oldSoftReserved":0.0,"createdTime":"2022-01-18T15:58:40.443Z","effectiveTime":"2020-04-08T14:05:22.795243-07:00","safetyStockCount":0.0}
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** The event activity export ID does not exist.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadEventsActivityExportFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadEventsActivityExportFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **410** The download link is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadEventsActivityExportFile410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredResultLink",
      "message": "The download link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Submit a reservations export request.

`POST /organizations/{organizationId}/reservations/exports`

Operation ID: `submitReservationsExport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory.rw, sfcc\_inventory\_impex\_inventory\_rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `InitiateReservationsExportRequestBody`.

_Example: initiateReservationsExportRequest_

```
{
  "toDate": "2022-04-10T15:41:25.553Z",
  "fromDate": "2022-03-19T15:41:25.553Z",
  "status": "open"
}
```

#### Responses

*   **200** Successfully submitted export request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InitiateReservationsExportResponse200`.
    
    _Example: initiateReservationsExportSuccess_
    
    ```
    {
      "exportId": "60679175-C589-49A9-87FE-DC07F657D7C0",
      "exportStatusLink": "/inventory/impex/v1/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/reservations/exports/60679175-C589-49A9-87FE-DC07F657D7C0/status"
    }
    ```
    
*   **400** Invalid request
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: submitReservationsExport400_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "'sku' Invalid characters in sku: null"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### DELETE Delete a single reservation export ID. The current request limit for each tenenat is 120 requests per second.

`DELETE /organizations/{organizationId}/reservations/exports/{exportId}`

Operation ID: `deleteReservationsExport`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted a single reservations export.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: NotFoundExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: ExportInProcessExample_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Download the generated reservations export file.

`GET /organizations/{organizationId}/reservations/exports/{exportId}/file-content`

Operation ID: `downloadReservationsExportFile`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully downloaded the file.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/octet-stream`. Schema: `string (binary)`.
    
    Type: `string (binary)`.
    
    _Example: downloadReservationsExportFile_
    
    ```
    { 
      "reservationId" : "5baf4a87-1841-4311-9ca9-601e5d32885b", 
      "externalRefId" : "OCI-1234567", 
      "reservationTime" : 1648718653000, 
      "reservationState" : "CLOSED", 
      "reservationDetails" : [ 
        { 
          "group": "ACME_US", 
          "sku" : "white-shirt-40", 
          "quantity": 5, 
          "reservationDetailActions" : [ 
            { 
              "requestId" : "3678-23456-3456-4567-9999-1232", 
              "externalRefId" : "1234561-4949-2345", 
              "quantity" : 5, 
              "action": "Reserved", 
              "group": "ACME_US", 
              "timestamp" : "1648720001000" 
            },
            { 
              "requestId" : "45GF-23456-3456-4567-5678-6F6F", 
              "externalRefId" : "1234561-3574-6B6D", 
              "quantity" : 5, 
              "action": "Moved", 
              "from": 
              { 
                "group": "ACME_US" 
              }, 
              "to": 
              { 
                "location": "warehouse-slc" 
              }, 
              "timestamp" : "1648720001000" 
              }, 
            { 
              "requestId" : "900000-8863-488e-840b-2aebd10b57cd", 
              "externalRefId" : "7282822-9823-eee", 
              "quantity" : 5, 
              "action": "Fulfilled", 
              "location" "warehouse-slc": 
              "timestamp" : "1648721352000" 
            } 
          ] 
        }, 
        { 
          "location": "warehouse-slc", 
          "sku" : "blue-pant-42", 
          "quantity": 8, 
          "reservationDetailActions" : [ 
            { 
              "requestId" : "9876-23456-3456-4567-9999-1232", 
              "externalRefId" : "1234561-4949-2345", 
              "quantity" : 3, 
              "action": "Reserved", 
              "location": "warehouse-slc", 
              "timestamp" : "1648720001000" 
            }, 
          ] 
        } 
      ] 
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** The reservations export file does not exist.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadReservationsExportFile404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **409** Export in progress.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadReservationsExportFile409_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExportInProcess",
      "message": "Export 1234-3456-45678-1234 is in progress."
    }
    ```
    
*   **410** The download link is no longer available at the server.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: downloadReservationsExportFile410_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "ExpiredResultLink",
      "message": "The download link has expired or is no longer valid."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### GET Retrieve status information for a single export ID. The current request limit for each tenant is 120 requests per second.

`GET /organizations/{organizationId}/reservations/exports/{exportId}/status`

Operation ID: `retrieveReservationsExportStatus`. Security: AmOAuth2 (sfcc.inventory.impex-inventory, sfcc\_inventory\_impex\_inventory).

#### Parameters

*   `exportId` (path, UniqueId, required) The ID of the reservations export on which the action is being performed.
*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved export status.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `ExportReservationsStatusResponse200`.
    
    _Example: retrieveReservationsExportStatusSuccess_
    
    ```
    {
      "id": "323b0g69-d37d-423a-84f5-8f393fe80459",
      "status": "COMPLETED",
      "export": {
        "startTimeUTC": "2019-07-24T21:13:00Z",
        "endTimeUTC": "2019-07-24T21:13:00Z",
        "recordsProcessedCount": 2000,
        "recordsExportedCount": 2000,
        "groups": [
          "UnitedStates"
        ]
      },
      "download": {
        "downloadLink": "/v2/organizations/8f714039-2808-4104-b444-5e8f9d923d6e/reservations/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/file-content",
        "downloadLinkExpirationUTC": "2019-07-24T21:13:00Z"
      },
      "validation": {
        "fileHashType": "SHA-256",
        "fileHash": "e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922",
        "fileSize": 5231942
      }
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/json`. Schema: `NotAuthorized`.
    
    _Example getLocationGraphExport403: same as POST /organizations/{organizationId}/location-graph/exports 403 response._
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: retrieveReservationsExportStatus404_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "An invalid entity was provided as part of the request."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the organization the request is being made by

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.

### InitiateLocationGraphExportResponse

Initiate location graph export response

*   `exportId` (_object_, required)  
    Example: `a218f4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
    Includes all fields of `UniqueId`.
    
    Example: `a218f4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
*   `exportStatusLink` (_string_, required)  
    Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/location-graph/exports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/status$. Example: `/inventory/impex/v1/organizations/391e7478-2d3a-414d-92fd-a2735dabfed2/location-graph/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/status`.

### InventoryResponseErrorSchema

*   `errorCode` (_string_, required)  
    Maximum length: 250. Example: `InvalidRequestParameter`.
*   `message` (_string_, required)  
    Maximum length: 250. Example: `An invalid request parameter was provided.`.
*   `type` (_string_, required)  
    Maximum length: 250. Example: `about:blank`.
*   `parameterName` (_string_) When invalid json is passed to the service, this field will indicate which piece of the supplied json was invalid.  
    Maximum length: 250. Example: `location`.

### NotAuthorized

*   `timestamp` (_string_, required)  
    Maximum length: 36. Example: `2020-07-06T17:46:57.492+0000`.
*   `status` (_integer_, required)  
    Example: `403`.
*   `error` (_string_, required)  
    Maximum length: 250. Example: `Forbidden`.
*   `message` (_string_, required)  
    Maximum length: 250. Example: `No message available`.
*   `path` (_string_, required)  
    Maximum length: 250. Example: `/inventory/impex/v1/organizations/myOrgId/location-graph/exports`.

### UniqueId

An id to uniquely identify this operation/request

Type: `string`.

Maximum length: 128. Example: `323b0g69-d37d-423a-84f5-8f393fe80459`.

### ExportLocationGraphDownloadFile

Export location graph download file information

*   `locations` (_array of object_, required)
    
    _Example_
    
    ```
    [
      "l4b17f6a0-b4e6-43a1-bfee-a4a2db37b3f2"
    ]
    ```
    
    Includes all fields of `LocationId`.
    
*   `groups` (_array of object_, required)
    
    Each item: The group array items contained in a location graph export
    
    *   `id` (_object_, required)  
        Example: `8ae8b814-0b28-4710-8c3c-8ed95abed62e`.
        
        Includes all fields of `GroupId`.
        
        Example: `8ae8b814-0b28-4710-8c3c-8ed95abed62e`.
        
    *   `locations` (_array of object_, required)
        
        _Example_
        
        ```
        [
          "l4b17f6a0-b4e6-43a1-bfee-a4a2db37b3f2"
        ]
        ```
        
        Includes all fields of `LocationId`.
        

### ExportLocationGraphStatusResponse200

Export location graph status request response

*   `id` (_object_, required)  
    Example: `a218f4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
    Includes all fields of `UniqueId`.
    
    Example: `a218f4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
*   `status` (_string_, required) Enum allowing indication of a process status  
    Allowed values: `STAGING`, `WAITING`, `EXPIRED`, `SUBMITTED`, `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`. Example: `COMPLETED`.
*   `export` (_object_, required)
    *   `startTimeUTC` (_string (date-time)_, required) The UTC time that the export process was started.  
        Example: `2020-04-15T21:21:23.675Z`.
    *   `endTimeUTC` (_string (date-time)_) The UTC time that the export process completed.  
        Example: `2020-04-15T21:21:23.812Z`.
    *   `recordsProcessedCount` (_integer_, required)  
        Example: `7`.
    *   `recordsExportedCount` (_integer_, required)  
        Example: `7`.
*   `download` (_object_)
    *   `downloadLink` (_string_, required) The URI link to be used for retrieving the event log export file. This link is valid anytime after the status of the export is completed and the link has not expired.  
        Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/location-graph/exports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/file-content$. Example: `/inventory/impex/v1/organizations/391e7478-2d3a-414d-92fd-a2735dabfed2/location-graph/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/file-content`.
    *   `downloadLinkExpirationUTC` (_string (date-time)_, required)  
        Example: `2019-07-24T21:13:00Z`.
*   `validation` (_object_)
    *   `fileHash` (_string_, required)  
        Maximum length: 128. Example: `15fba5d9facf494749b9cfabdc2c8fe1c73d974b9579bc67ab293e607f3c92bb`.
    *   `fileHashType` (_string_, required) Enum containing valid File Hash Types  
        Allowed values: `SHA-256`, `SHA-512`. Example: `SHA-256`.
    *   `fileSize` (_integer_, required)  
        Example: `607`.

### GetRunningImportsResponse

Response generated by a get request for available import ID's.

*   `imports` (_array of object_, required) An array of import job ID's that are currently present in the system.
    
    Includes all fields of `UniqueId`.
    

### InitiateImportRequestBody

The body that is sent requesting an import to be initiated

Includes all fields of `ImportRequestObjects`.

### InitiateImportResponse200

Common response from import initiation calls

*   `importId` (_object_, required) The ID associated with the initiated import  
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    
    Includes all fields of `UniqueId`.
    
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    
*   `importStatusLink` (_string_, required) URI where import status can be acquired  
    Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/availability-records/imports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/status$. Example: `/inventory/impex/v1/organizations/1def0875-f84b-4e19-ac8f-fb8419484299/availability-records/imports/d88e54c5-23ed-4e33-a6a9-c31dc810662b/status`.
*   `uploadLink` (_string_, required) URL to submit the upload file  
    Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/availability-records/imports/uploadlink/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}$. Example: `/inventory/impex/v1/organizations/1def0875-f84b-4e19-ac8f-fb8419484299/availability-records/imports/uploadlink/d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
*   `uploadMethod` (_string_, required) Upload HTTP Method, i.e. Multipart/Form  
    Allowed values: `POST`. Example: `POST`.
*   `uploadLinkExpirationUTC` (_string (date-time)_, required) ISO Time when upload link expires  
    Example: `2019-06-07T15:10:04.357Z`.

### ImportStatusResponse200

Record that is contained in the response array when checking the status of an import.

*   `importId` (_object_, required) Unique identifier for the import  
    Example: `12345-23456-3456-4567-5678`.
    
    Includes all fields of `UniqueId`.
    
    Example: `12345-23456-3456-4567-5678`.
    
*   `status` (_string_, required)  
    Allowed values: `STAGING`, `WAITING`, `SUBMITTED`, `EXPIRED`, `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`. Example: `COMPLETED`.
*   `validation` (_object_, required)
    *   `status` (_string_, required) Validation status  
        Allowed values: `Success`, `Failed`, `Pending`. Example: `Success`.
    *   `errors` (_array of string_, required) Array of error verbiages  
        Items: Maximum length: 250. Example: `Error message`.
*   `upload` (_object_, required)
    *   `fileName` (_string_, required) The name of the upload file.  
        Maximum length: 250. Example: `test.json`.
*   `import` (_object_, required)
    *   `startTimeUTC` (_string (date-time)_) Start time of import  
        Example: `2019-02-12T11:23:23Z`.
    *   `endTimeUTC` (_string (date-time)_) End/completion time of import  
        Example: `2019-02-12T12:34:56Z`.
    *   `recordsProcessedCount` (_integer_, required) Number of records imported/processed  
        Example: `2000`.
    *   `recordsReadCount` (_integer_, required) Number of records read  
        Example: `2000`.
    *   `recordsSkippedCount` (_integer_, required) Number of records skipped  
        Example: `56`.
    *   `fullResults` (_object_, required)
        *   `href` (_string_, required) URL to pull results file. Is available until time indicated in "exportResultExpirationUTC" field.  
            Maximum length: 1024. Example: `https://462437319225-dev-us-east-1.s3.amazonaws.com/d88e54c5-23ed-4e33-a6a9-c31dc810662b?X-Amz- Security-Token=AgoJb3JpZ2luX2VjEB4aCXVzLWVhc3QtMSJ`.
        *   `exportResultExpirationUTC` (_string (date-time)_, required) Expiration time for availability of full result file  
            Example: `2019-03-12T12:34:56Z`.

### ImportUploadLinkResponse200

The file upload has been successfully started. Details about the upload are available in the response body.

*   `status` (_string_, required) The overall status of the import of the file. Can be either PENDING, RUNNING, or COMPLETED.  
    Allowed values: `PENDING`, `RUNNING`, `COMPLETED`. Example: `PENDING`.
*   `importId` (_object_, required) The UUID of the import job.  
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    
    Includes all fields of `UniqueId`.
    
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    

### InitiateProductSegmentationImportRequestBody

The body that is sent requesting an import for product segmentations to be initiated

Includes all fields of `InitiateProductSegmentationImportRequest`.

### InitiateProductSegmentationImportResponse200

*   `importId` (_object_, required)  
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    
    Includes all fields of `UniqueId`.
    
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    
*   `importStatusLink` (_string_, required) The link that should be used to check the status of the Product Segmentation Import  
    Pattern: ^/v2/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/product-segmentation/imports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/status$. Example: `/v2/organizations/14c63be1-aac6-4360-8f33-4ce4f1b01d3e/product-segmentation/imports/d88e54c5-23ed-4e33-a6a9-c31dc810662b/status`.
*   `uploadLink` (_string_, required) The link that should be used for upload the Product Segmentation Data payload to the service  
    Pattern: ^/v2/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/product-segmentation/imports/uploadlink/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}$. Example: `/v2/organizations/14c63be1-aac6-4360-8f33-4ce4f1b01d3e/product-segmentation/imports/uploadlink/d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
*   `uploadMethod` (_string_, required) The http method that should be used when using the uploadLink endpoint  
    Allowed values: `POST`. Example: `POST`.
*   `uploadLinkExpirationUTC` (_string (date-time)_, required) The expiration time for the uploadLink endpoint.  
    Example: `2019-07-24T21:13:00Z`.

### ProductSegmentationImportStatusResponse

Record that is contained in the response array when checking the status of an import.

*   `importId` (_object_, required) Unique identifier for the import  
    Example: `12345-23456-3456-4567-5678`.
    
    Includes all fields of `UniqueId`.
    
    Example: `12345-23456-3456-4567-5678`.
    
*   `status` (_string_, required)  
    Allowed values: `STAGING`, `WAITING`, `EXPIRED`, `SUBMITTED`, `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`. Example: `COMPLETED`.
*   `validation` (_object_, required)
    *   `status` (_string_, required) Validation status  
        Allowed values: `Success`, `Failed`, `Pending`. Example: `Success`.
    *   `errors` (_array of string_, required) Array of error verbiages  
        Items: Maximum length: 250. Example: `Error message`.
*   `upload` (_object_, required)
    *   `fileName` (_string_, required) The name of the upload file.  
        Maximum length: 250. Example: `test.json`.
*   `import` (_object_, required)
    *   `startTimeUTC` (_string (date-time)_) Start time of import  
        Example: `2019-02-12T11:23:23Z`.
    *   `endTimeUTC` (_string (date-time)_) End/completion time of import  
        Example: `2019-02-12T12:34:56Z`.
    *   `recordsProcessedCount` (_integer_, required) Number of records imported/processed  
        Example: `2000`.
    *   `recordsReadCount` (_integer_, required) Number of records read  
        Example: `2000`.
    *   `recordsSkippedCount` (_integer_, required) Number of records skipped  
        Example: `56`.
    *   `fullResults` (_object_, required)
        *   `href` (_string_, required) URL to pull results file. Is available until time indicated in "exportResultExpirationUTC" field.  
            Maximum length: 1024. Example: `https://462437319225-dev-us-east-1.s3.amazonaws.com/d88e54c5-23ed-4e33-a6a9-c31dc810662b?X-Amz- Security-Token=AgoJb3JpZ2luX2VjEB4aCXVzLWVhc3QtMSJ`.
        *   `exportResultExpirationUTC` (_string (date-time)_, required) Expiration time for availability of full result file  
            Example: `2019-03-12T12:34:56Z`.

### ImportProductSegmentationUploadLinkResponse200

The file upload has been successfully started. Details about the upload are available in the response body.

*   `status` (_string_, required) The overall status of the import of the file. Can be either PENDING, RUNNING, or COMPLETED.  
    Allowed values: `PENDING`, `RUNNING`, `COMPLETED`. Example: `PENDING`.
*   `importId` (_object_, required) The UUID of the import job.  
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    
    Includes all fields of `UniqueId`.
    
    Example: `d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
    

### InitiateSegmentationExportBody

*   `groups` (_array of object_, required) An array of group IDs whose product Segmentation information you want to export. Simply use an asterisk to indicate all groups should be exported.
    
    _Example_
    
    ```
    [
      "Germany",
      "UnitedStates"
    ]
    ```
    
    Includes all fields of `GroupId`.
    

### InitiateProductSegmentationExportResponse200

*   `exportId` (_object_, required) The ID associated with the initiated export  
    Example: `pe-0377a512-d107-40a0-b966-bad5a021d21f`.
    
    Includes all fields of `UniqueId`.
    
    Example: `pe-0377a512-d107-40a0-b966-bad5a021d21f`.
    
*   `exportStatusLink` (_string_, required) The URI to be used for accessing the export status. This resource is available immediately.  
    Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/product-segmentation/exports/pe-\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/status$. Example: `/inventory/impex/v1/organizations/99a634c5-1206-43b9-834b-75803f5387a9/product-segmentation/exports/pe-0377a512-d107-40a0-b966-bad5a021d21f/status`.

### ExportProductSegmentationStatusResponse200

*   `id` (_object_, required) The ID associated with this export request.  
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
    Includes all fields of `UniqueId`.
    
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
*   `status` (_string_, required) The current status of the export request  
    Allowed values: `STAGING`, `WAITING`, `EXPIRED`, `SUBMITTED`, `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`. Example: `COMPLETED`.
*   `export` (_object_, required)
    *   `startTimeUTC` (_string (date-time)_) The UTC time that the export process was started.  
        Example: `2019-02-12T12:34:00Z`.
    *   `endTimeUTC` (_string (date-time)_) The UTC time that the export process completed.  
        Example: `2019-02-12T12:52:00Z`.
    *   `recordsProcessedCount` (_number_, required) The total number of records processed during the export request.  
        Example: `2000`.
    *   `recordsExportedCount` (_number_, required) The total number of records exported by the system.  
        Example: `2000`.
*   `download` (_object_, required)
    *   `downloadLink` (_string_, required) The URI link to be used for retrieving the export file. This link is valid anytime after the status of the export is completed and the link has not expired.  
        Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/product-segmentation/exports/pe-\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/file-content$. Example: `/inventory/impex/v1/organizations/99a634c5-1206-43b9-834b-75803f5387a9/product-segmentation/exports/pe-0377a512-d107-40a0-b966-bad5a021d21f/file-content`.
    *   `downloadLinkExpirationUTC` (_string (date-time)_, required) The time at which the download link will expire, in UTC time.  
        Example: `2019-07-24T21:13:00Z`.
*   `validation` (_object_)
    *   `fileHashType` (_string_, required) The file hash type associated with the export file.  
        Allowed values: `SHA-256`, `SHA-512`. Example: `SHA-256`.
    *   `fileHash` (_string_, required) The hash associated with the export file.  
        Maximum length: 128. Example: `e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922`.
    *   `fileSize` (_number_, required) File size in bytes.  
        Example: `5231942`.

### InitiateAvailabilityExportBody

*   `objects` (_object_)
    *   `groups` (_array of object_) An array of group IDs whose availability information you want to export. Cannot be included if 'locations' is included below.
        
        _Example_
        
        ```
        [
          "Germany",
          "UnitedStates"
        ]
        ```
        
        Includes all fields of `GroupId`.
        
    *   `locations` (_array of object_) An array of location IDs whose availability information you want to export. Cannot be included if 'groups' is included above.
        
        _Example_
        
        ```
        [
          "warehouse5",
          "warehouse6"
        ]
        ```
        
        Includes all fields of `LocationId`.
        

### InitiateGroupExportResponse200

*   `exportId` (_object_, required) The ID associated with the initiated export  
    Example: `a218f4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
    Includes all fields of `UniqueId`.
    
    Example: `a218f4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
*   `exportStatusLink` (_string_, required) The URI to be used for accessing the export status. This resource is available immediately.  
    Pattern: ^/inventory/inventory-availability/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/availability-records/exports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/status$. Example: `/inventory/inventory-availability/v1/organizations/391e7478-2d3a-414d-92fd-a2735dabfed2/availability-records/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/status`.

### ExportGroupStatusResponse200

*   `id` (_object_, required) The ID associated with this export request.  
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
    Includes all fields of `UniqueId`.
    
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
*   `status` (_string_, required) The current status of the export request  
    Allowed values: `STAGING`, `WAITING`, `EXPIRED`, `SUBMITTED`, `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`. Example: `COMPLETED`.
*   `export` (_object_, required)
    *   `startTimeUTC` (_string (date-time)_) The UTC time that the export process was started.  
        Example: `2020-04-15T21:21:23.675Z`.
    *   `endTimeUTC` (_string (date-time)_) The UTC time that the export process completed.  
        Example: `2020-04-15T21:21:23.812Z`.
    *   `recordsProcessedCount` (_number_, required) The total number of records processed during the export request.  
        Example: `2000`.
    *   `recordsExportedCount` (_number_, required) The total number of records exported by the system.  
        Example: `2000`.
    *   `groups` (_array of object_) Groups associated with this export request
        
        Includes all fields of `GroupId`.
        
*   `download` (_object_, required)
    *   `downloadLink` (_string_, required) The URI link to be used for retrieving the export file. This link is valid anytime after the status of the export is completed and the link has not expired.  
        Pattern: ^/v2/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/availability-records/exports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/file-content$. Example: `/v2/organizations/391e7478-2d3a-414d-92fd-a2735dabfed2/availability-records/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/file-content`.
    *   `downloadLinkExpirationUTC` (_string (date-time)_, required) The time at which the download link will expire, in UTC time.  
        Example: `2019-07-24T21:13:00Z`.
*   `validation` (_object_)
    *   `fileHashType` (_string_, required) The file hash type associated with the export file.  
        Allowed values: `SHA-256`, `SHA-512`. Example: `SHA-256`.
    *   `fileHash` (_string_, required) The hash associated with the export file.  
        Maximum length: 128. Example: `e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922`.
    *   `fileSize` (_number_, required) File size in bytes.  
        Example: `5231942`.

### InitiateEventActivityExportRequestBody

The body that is sent requesting an export to be initiated

Includes all fields of `GetEventLogRequestBody`.

### InitiateEventLogExportResponse200

Common response from export events activity initiation calls

*   `exportId` (_string_, required) The ID associated with the initiated export  
    Pattern: ^e-\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}$. Example: `e-d88e54c5-23ed-4e33-a6a9-c31dc810662b`.
*   `exportStatusLink` (_string_, required) URI where export status can be acquired  
    Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/event-log/exports/e-\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/status$. Example: `/inventory/impex/v1/organizations/18f32133-f527-46ae-b34f-8abfe518aa4d/event-log/exports/e-d88e54c5-23ed-4e33-a6a9-c31dc810662b/status`.

### ExportEventLogStatusResponse200

*   `id` (_object_, required) The ID associated with this export request.  
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
    Includes all fields of `GroupId`.
    
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
*   `status` (_string_, required) The current status of the export request  
    Allowed values: `STAGING`, `WAITING`, `EXPIRED`, `SUBMITTED`, `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`. Example: `COMPLETED`.
*   `export` (_object_, required)
    *   `startTimeUTC` (_string (date-time)_) The UTC time that the export process was started.  
        Example: `2019-02-12T12:34:00Z`.
    *   `endTimeUTC` (_string (date-time)_) The UTC time that the export process completed.  
        Example: `2019-02-12T12:52:00Z`.
    *   `recordsProcessedCount` (_number_, required) The total number of records processed during the export request.  
        Example: `2000`.
    *   `recordsExportedCount` (_number_, required) The total number of records exported by the system.  
        Example: `2000`.
    *   `groups` (_array of object_) Groups associated with this export request
        
        Includes all fields of `GroupId`.
        
*   `download` (_object_, required)
    *   `downloadLink` (_string_, required) The URI link to be used for retrieving the export file. This link is valid anytime after the status of the export is completed and the link has not expired.  
        Pattern: ^/v2/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/event-log/exports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/file-content$. Example: `/v2/organizations/18f32133-f527-46ae-b34f-8abfe518aa4d/event-log/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/file-content`.
    *   `downloadLinkExpirationUTC` (_string (date-time)_, required) The time at which the download link will expire, in UTC time.  
        Example: `2019-02-12T13:23:51Z`.
*   `validation` (_object_)
    *   `fileHashType` (_string_, required) The file hash type associated with the export file.  
        Allowed values: `SHA-256`, `SHA-512`. Example: `SHA-256`.
    *   `fileHash` (_string_, required) The hash associated with the export file.  
        Maximum length: 128. Example: `e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922`.
    *   `fileSize` (_number_, required) File size in bytes.  
        Example: `5231942`.

### InitiateReservationsExportRequestBody

The body that is sent requesting a reservations export to be initiated

Includes all fields of `GetReservationsRequestBody`.

### InitiateReservationsExportResponse200

Common response from export reservations initiation calls

*   `exportId` (_object_, required) The ID associated with the initiated reservations export  
    Example: `60679175-C589-49A9-87FE-DC07F657D7C0`.
    
    Includes all fields of `UniqueId`.
    
    Example: `60679175-C589-49A9-87FE-DC07F657D7C0`.
    
*   `exportStatusLink` (_string_, required) URI where reservations export status can be acquired  
    Pattern: ^/inventory/impex/v1/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/reservations/exports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/status$. Example: `/inventory/impex/v1/organizations/F75164D4-59B5-4DA2-8429-F5A97EA5CA03/reservations/exports/60679175-C589-49A9-87FE-DC07F657D7C0/status`.

### ExportReservationsStatusResponse200

*   `id` (_object_, required) The ID associated with this reservations export request.  
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
    Includes all fields of `UniqueId`.
    
    Example: `ameff4b2-2dc3-4ea8-af6d-c75fafd62323`.
    
*   `status` (_string_, required) The current status of the export request  
    Allowed values: `STAGING`, `WAITING`, `EXPIRED`, `SUBMITTED`, `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`. Example: `COMPLETED`.
*   `export` (_object_, required)
    *   `startTimeUTC` (_string (date-time)_) The UTC time that the export process was started.  
        Example: `2022-03-19T15:41:25.553Z`.
    *   `endTimeUTC` (_string (date-time)_) The UTC time that the export process completed.  
        Example: `2022-03-19T15:41:25.553Z`.
    *   `recordsProcessedCount` (_number_, required) The total number of records processed during the export request.  
        Example: `2000`.
    *   `recordsExportedCount` (_number_, required) The total number of records exported by the system.  
        Example: `2000`.
    *   `groups` (_array of object_) Groups associated with this export request
        
        Includes all fields of `GroupId`.
        
*   `download` (_object_, required)
    *   `downloadLink` (_string_, required) The URI link to be used for retrieving the export file. This link is valid anytime after the status of the export is completed and the link has not expired.  
        Pattern: ^/v2/organizations/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/reservations/exports/\[0-9a-fA-F\]{8}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{4}-\[0-9a-fA-F\]{12}/file-content$. Example: `/v2/organizations/70d97a6b-6193-4703-a2e3-8870e45caa1f/reservations/exports/a218f4b2-2dc3-4ea8-af6d-c75fafd62323/file-content`.
    *   `downloadLinkExpirationUTC` (_string (date-time)_, required) The time at which the download link will expire, in UTC time.  
        Example: `2022-03-19T15:41:25.553Z`.
*   `validation` (_object_)
    *   `fileHashType` (_string_, required) The file hash type associated with the export file.  
        Allowed values: `SHA-256`, `SHA-512`. Example: `SHA-256`.
    *   `fileHash` (_string_, required) The hash associated with the export file.  
        Maximum length: 128. Example: `e9v2d11298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852c922`.
    *   `fileSize` (_number_, required) File size in bytes.  
        Example: `5231942`.

### LocationId

The id of the location of the inventory.

Type: `string`.

Minimum length: 2. Maximum length: 128. Pattern: ^\[a-zA-Z0-9-\_\]\*$. Example: `warehouse5`.

### GroupId

An identifier for a collection of locations. Can not be the same as any location identifier.

Type: `string`.

Minimum length: 2. Maximum length: 128. Pattern: ^\[a-zA-Z0-9-\_\]\*$. Example: `UnitedStates`.

### ImportRequestObjects

This object will contain the request objects that are being supplied to an initiate import request call

*   `fileName` (_string_, required) Name of the file.  
    Maximum length: 250. Example: `inventory.json`.
*   `fileFormat` (_object_) The file format. If file format is not provided then is assumed to be JSON. Current supported file types are CSV or JSON.
    
    Includes all fields of `ImportFileTypes`.
    
*   `fileEncoding` (_string_) Encoding format desired. Specify "GZIP" if compressed. The gateway has a filesize limit of 100MB. If the file is larger than 100MB, send it in compressed format.  
    Allowed values: `GZIP`. Example: `GZIP`.
*   `fileHash` (_string_)  
    Maximum length: 128. Example: `15fba5d9facf494749b9cfabdc2c8fe1c73d974b9579bc67ab293e607f3c92bb`.
*   `fileHashType` (_string_) Hash algorithm type. If fileHash is specified, this value will be used. If fileHash is specified and this value is not provided, SHA-256 is assumed.  
    Allowed values: `SHA-256`, `SHA-512`. Example: `SHA-256`.
*   `linkDuration` (_integer_) Time-to-live (TTL), in minutes up to 60 minutes max, uploadLink is valid for in response.  
    Example: `60`.

### InitiateProductSegmentationImportRequest

This type contains the structure for the initiate product segmentation data import request body

*   `fileName` (_string_, required) the filename to be imported.  
    Maximum length: 250. Example: `product_segmentation_data_import.json`.
*   `linkDuration` (_number_, required) the duration the uploadLink shall remain active after being created.  
    Example: `60`.

### GetEventLogRequestBody

This object will contain the request objects that are being supplied to initiate export request call

*   `sku` (_SkuId_, required)
*   `startsOn` (_string (date-time)_, required) ISO Date from which OCI will start to query for the sku activity.  
    Example: `2022-03-19T15:41:25.553Z`.
*   `endsOn` (_string (date-time)_) ISO Date that sets the range OCI will use in order to query for the sku activity. This field is optional, in which case, OCI will set the range to be 30 days from the startsOn date. The value that gets set in the endsOn property, cannot be bigger than 30 days from the starsOn date.  
    Example: `2022-04-10T15:41:25.553Z`.
*   `locations` (_array of object_) Lists which locations should be considered while querying the activity around the sku. The total locations to query, combined with total groups (if specified) cannot be more than 10. If no locations or groups are specified, OCI will query all activity related to the sku.
    
    _Example_
    
    ```
    [
      "warehouse1",
      "warehouse2"
    ]
    ```
    
    Includes all fields of `LocationId`.
    
*   `fileFormat` (_string_) An optional field that changes the output format. Default CASE-SENSITIVE (must be all upper-case) value will be JSON.  
    Allowed values: `JSON`, `CSV`. Default: `JSON`. Example: `CSV`.
*   `groups` (_array of object_) Lists which groups should be considered while querying the activity around the sku. The total groups to query, combined with total locations (if specified) cannot be more than 10. If no locations or groups are specified, OCI will query all activity related to the sku.
    
    _Example_
    
    ```
    [
      "united-states"
    ]
    ```
    
    Includes all fields of `GroupId`.
    

### GetReservationsRequestBody

This object will contain the request objects that are being supplied to initiate export reservations request call

*   `status` (_string_, required) The reservations status to query and export for.  
    Allowed values: `open`, `closed`. Example: `open`.
*   `fromDate` (_string (date-time)_, required) ISO Date from which OCI will start to query for the reservation documents.  
    Example: `2022-03-19T15:41:25.553Z`.
*   `toDate` (_string (date-time)_) ISO Date that sets the range OCI will use in order to query for the reservation documents. This field is optional, in which case, OCI will set the to date to the current date if none is provided.  
    Example: `2022-04-10T15:41:25.553Z`.

### ImportFileTypes

Type: `string`.

Allowed values: `JSON`, `CSV`. Example: `JSON`.

### SkuId

The inventory identifier

Type: `string`.

Minimum length: 2. Maximum length: 250. Pattern: ^\[^\\\\<>;%/\\s\]\*$. Example: `sku123`.

<!-- document id=1f8521b673b0d9cd825484b9497b067c63a09cee228452776a8fcbad84845b9e url=/developer/current/en-us/commerce-cloud/commerce-api/guides/inventory-impex-best-practices.md -->

# Inventory IMPEX Best Practices

Use Inventory Impex APIs to manage imports and exports of inventory availability for Omnichannel Inventory (OCI). This document is meant to assist you in following some best practices while implementing your use of the OCI service, as well as provide some information about the service itself.

## Inventory Import

- ALWAYS use the high performant import process. The legacy import process should no longer be used and will be deprecated. The _new_ method has much higher performance and is the method of choice for performing imports. For more information regarding the high-performance changes, refer to "Import File Layout - High Performance" in the Inventory Impex documentation.

- Don’t perform an import of inventory data while location graph changes are in progress. Doing so can cause inventory inconsistencies between the group and the locations that it contains. If you’re running scheduled imports, make sure that they aren’t running during location graph changes, or are paused until those changes are complete. This makes sure that you have an accurate picture of inventory in the system across the locations and groups.

- For updating small batches of data, we recommend using the `batchInventoryUpdate` API call, rather than performing a full import. There’s a limitation of 100 SKUs per batch, however, this is faster than loading the data via file.

- If using the `batchInventoryUpdate` API call, and you find that you’re updating more than 1000 SKUs via multiple calls to the API, this is the time to switch back over and use the inventory file import process.

- For best performance, use _delta_ data imports for updating things that have changed rather than full data imports. Full data imports are more time intensive and shouldn’t be used unless necessary.

- Be _very careful_ in the scheduling of your data imports. Make sure that you’re allowing ample time between full data imports. Multiple customers have had difficult situations arise because they’ve scheduled their imports too closely together (some as close as one minute). Recovery from misusing the service in this way is difficult and can create problems for your go-live and implementation plans.

- When processing large amounts of import data, split your data into multiple files and submit them separately. However, there are rate and concurrency limits within the OCI service and infrastructure. For this reason, it’s best to group inventory imports into fewer files rather than large numbers of smaller files.

## Considerations Regarding The Import File

- Separate the top-level entries in your import file with line feeds, not with commas. Each entry in the file must be on a single line.
- The mode is always assumed to be `UPDATE`.
- Each inventory record entry request has a unique _idempotence_ recordId. Best practice in this case is to use a UUID. The record ID protects against the import of duplicate data.
- Each inventory record imported requires an `effectiveDate` entry.
- Each inventory Future record imported requires a nonzero quantity and `expectedDate`.
- The system only creates or updates entries that are included in the data. It doesn’t delete entries that aren't included. However, if an included entry has an empty value, it will be ignored and reported as an error.
- To avoid overselling during the initial implementation period, we recommend defining safety stock levels.

## Import Process - Best Practice

When performing an import for item availability records, the following endpoints should be used in this order:

1.  Initiate the import with a call to the imports _POST_ URI.
    `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports`

    Use the availability-records imports _POST_ endpoint to initiate a load of the inventory availability data into Omnichannel Inventory. The details of the data being imported are included in the body of the _POST_ request.

2.  Use the uploadLink from the response body of step 1 to upload the data stream/file to OCI using a _POST_ call.
    `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/uploadlink/{uploadLinkId}`

    The resulting response body from the initiate call contains a link to submit the actual import data stream/file. If the file being uploaded into the system is larger than 100 MB, the file _must_ be compressed with gzip.

3.  After the file has been uploaded into OCI, use a _GET_ call to the importStatusLink that was provided in the response body to the initiate call of step 1, to check on the status of the processing of your import data.
    `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/{importId}/status`

    After the file has been successfully uploaded to the OCI system, the status of the import can be checked by making calls to the availability-records imports status endpoint. When using this endpoint in conjunction with the importId used in the file upload, check if the import process has completed yet.

4.  After the status field in the response body returned from step 3 is _COMPLETED_, the import of the availability record data into OCI is complete. The status response includes a _fullResults href_ field that has a URI for retrieving the details about the completed import process. This information is retrieved with a _GET_ call to the provided URI.
    `https://{shortCode}.api.commercecloud.salesforce.com/inventory/impex/v1/organizations/{organizationId}/availability-records/imports/{importId}/file-content`

    After the file has been successfully processed by OCI, the response body includes a status of _COMPLETED_. Other metrics regarding the import are also included, and can be found in the documentation for the _status_ call.

    Also included in the _COMPLETED_ status is the _fullResults href_. Using this URI, retrieve the detailed results of the completed import process.

Following these steps in this order, with the endpoints indicated, successfully imports availability records into OCI.

## Location Inventory Import File Layout

This is the preferred import file layout:

**note:** The `mode` is assumed to be `UPDATE` since it's currently the only one supported.

`{"recordId":"0a87539d-f3dd-47bc-91c7-9c752e39dbe0","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"wickenburg"}`

`{"recordId":"3127e2ad-748b-459a-917c-78bef741602c","onHand":10,"sku":"sku1","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"prescott"}`

`{"recordId":"b709e7a8-7d4f-4458-be0c-a88f1e594f1d","onHand":10,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"wickenburg"}`

`{"recordId":"b34c99ea-e659-40f7-bcb4-2a3fdc4a80b0","onHand":10,"sku":"sku2","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"prescott"}`

`{"recordId":"4bf7b40b-c965-485c-afa0-cc56a8ea70eb","onHand":10,"sku":"sku3","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"wickenburg"}`

`{"recordId":"539d41b7-5f05-4908-831b-3dd0461794fc","onHand":10,"sku":"sku3","effectiveDate":"2020-04-08T14:05:22.790896-07:00","futures":[{"quantity":1,"expectedDate":"2020-04-18T14:05:22.781-07:00"}],"safetyStockCount":0,"locationId":"prescott"}`

There are no other requirements for indicating that you’re using the High-Performance Layout. The system reads the file and automatically determines how to process it.

For information regarding the field contents, see the Import Field Definitions section below.

### Import Field Definitions

Location Header:

| Field      | Description                                                                    | Required Field |
| ---------- | ------------------------------------------------------------------------------ | -------------- |
| `location` | The physical location where inventory is housed.                               | `TRUE`         |
| `mode`     | The type of system operation to perform. Currently, only `UPDATE` is supported | `TRUE`         |

Location Inventory:

| Field              | Description                                                                                                                                                                                                        | Required Field                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| `recordId`         | Unique identifier of inventory record.                                                                                                                                                                             | `TRUE`                                                         |
| `sku`              | Unique item identifier.                                                                                                                                                                                            | `TRUE`                                                         |
| `onHand`           | The current quantity on hand.                                                                                                                                                                                      | `FALSE`                                                        |
| `effectiveDate`    | The effective date of the `onHand` (ISO format).                                                                                                                                                                   | `FALSE`, see the additional description below for more detail. |
| `futures`          | A collection of future quantity information for the item. (See Future Quantity, below.) Note: the Inventory Availability API references `futures` in a collection called, `futureStock`. These are the same thing. | `FALSE`, If specified see the required fields below.           |
| `safetyStockCount` | The safety stock count.                                                                                                                                                                                            | `FALSE`                                                        |

Future Quantity:

| Field          | Description                                                                             | Required Field |
| -------------- | --------------------------------------------------------------------------------------- | -------------- |
| `quantity`     | The quantity that will be arriving in the future. **The value must be greater than 0.** | `TRUE`         |
| `expectedDate` | The date the future quantity is expected to arrive (ISO format).                        | `TRUE`         |

Availability Effective Date:

The `effectiveDate` field represents the time the `onHand` value was accurate at the physical location. It’s used in conjunction with the reservation fulfillment field, `fulfillmentTime` to keep `onHand` in sync with the physical location. For example, if `effectiveDate` is specified on a location record, the system will optionally decrement the value of `onHand` when a Reservation Fulfillment is made. See the [Inventory Reservation API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=inventory-reservation-service:Summary) for more information on how Reservation Fulfillments work.

Example:

Import happens for SKU: `abc` at location: `123`, and the value of `onHand` accounts for a Reservation Fulfillment that hasn't yet processed in OCI.

**note:** The JSON is shown formatted here, however in the actual import file it _must_ all be on a single line.

```json
   {
    "recordId":"a26fe1fd-c413-4b74-8570-1ec185ca7192",
    "onHand":10,
    "sku":"abc",
    "effectiveDate":"2021-03-09T00:00:00.000000-07:00"
   }
```

Reservation Fulfillment Request happens after the import for SKU: `abc` at location: `123`

```{
    "records": [
      {
        "id": "82251928-8863-488e-840b-2aebd10b57ba",
        "location": "123",
        "sku": "abc",
        "fulfillmentTime":"2021-03-08T00:00:00.000000-07:00"
        "quantity": 1
      }
    ]
  }
```

The system compares the values of `effectiveDate` and `fulfillmentTime`. Since `fulfillmentTime` is _less_ than `effectiveDate` it does _not_ decrement the value of `onHand`. If the reservation fulfillment happened first, `onHand` would be decremented (assuming the previous value of `effectiveDate` was less than `fulfillmentTime`). Then when the system performed the inventory import, the value of `onHand` would replace the previous value.

### Location Inventory Import Result File Layout

The result file starts with a status line record.

`{"status": "COMPLETED_WITHOUT_ERRORS"}`

| Result Status                     | Description                          |
| --------------------------------- | ------------------------------------ |
| `COMPLETED_WITHOUT_ERRORS`        | Import completed without any errors. |
| `COMPLETED_WITH_PARTIAL_FAILURES` | Some records failed to load.         |
| `FAILED`                          | Failed to load any records.          |

Each line following the status line represents an error record.

`{"recordId": "2a3e769c-c981-4d96-ba6a-e0b821a5bbbb","locationId":"location1","sku": "sku1", "message": "Unknown"}`

| Field        | Description                                                | Required Field |
| ------------ | ---------------------------------------------------------- | -------------- |
| `recordId`   | Unique identifier of inventory record sent in import file. | `TRUE`         |
| `locationId` | Location identifier.                                       | `TRUE`         |
| `sku`        | Unique item identifier of an item.                         | `TRUE`         |
| `message`    | Message containing details for failure.                    | `TRUE`         |

## Flash Sale and High Volume Transactions

All endpoints have a theoretical limit of approximately 50 requests per second for the same sku/locationGroup combination. For this reason, things like flash sales struggle to perform optimally. When making large numbers of requests for an individual SKU/locationGroup, where possible, it’s recommended that you combine or batch your requests into one for availability, reservation, transfer, fulfill, and so on. That aids in keeping performance optimized across your implementation.

## External Reference Identifier

Currently, there are a number of places where a consumer can submit an `ExternalRefId` with their request. This is to allow the consumer to submit user-generated data along with their request as a link to other external systems data. For example, if I'm pulling data from an order that has an order ID, I can submit that order ID with my reservation request as the `externalRefId`. Then, if there’s a problem with the reservation, there’s an easy way to connect it with the order in the external system that generated the error or problem. This is NOT to be confused with `externalRefId` used in Salesforce Core, or any other services. The usage is exclusive to OCI and isn’t used anywhere else.

## Correlation ID

To facilitate tracking of operations in OCI, customers must populate a header named `correlation-id`, which is used by the CDN to send the request to OCI. This header helps trace requests as they move throughout our service.

Some services use a header named `x-correlation-id`. If this header is used with OCI, it’s overwritten by the CDN with a new value and the initial purpose of the header is defeated. Use the `correlation-id` instead for a consistent result.

<!-- document id=cbcca125a8cc06971f443c563dcf6c8cec82da1dddd6b040187a132039cec9c8 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/inventory-lists.md -->

Inventory Lists

# Inventory Lists

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/inventory-lists/inventory-lists-oas-v1-public.yaml)

## API Overview

The Inventory Lists API provides comprehensive management capabilities for product inventory records within inventory lists. Use this API to:

*   Retrieve current inventory information for products.
*   Create and update inventory records with allocation and availability data.
*   Manage pre-order and backorder configurations.
*   Track stock levels, turnover, and available-to-sell (ATS) quantities.
*   Configure perpetual stock for always-available products.
*   Handle custom inventory attributes.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

The API client must also have at least one of the following OAuth scopes: `sfcc.inventory-lists` scope for read-only operations and `sfcc.inventory-lists.rw` for modifications.

You must include the relevant scope(s) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Key Concepts

#### Product Inventory Record

A product inventory record represents the inventory information for a specific product within an inventory list. Each record contains:

*   Product identification: Product ID and name
*   Stock information: Current stock level, ATS quantity, turnover
*   Allocation: Quantity allocated for sale and reset date
*   Availability dates: Expected in-stock dates
*   Pre-order/backorder handling: Configuration for products not currently in stock
*   Custom attributes: Extensible with custom properties (c\_\* fields)

#### Inventory List

An inventory list is a container for product inventory records. Each inventory list is identified by a unique ID and can contain multiple product inventory records.

#### Available to Sell (ATS)

ATS represents the quantity of items available for purchase. It is calculated as:

```
ATS = Allocation + PreOrderBackOrderAllocation - InventoryTurnover
```

#### Stock Level

Stock level represents the current physical inventory. It is calculated as:

```
Stock Level = Allocation - InventoryTurnover
```

#### Inventory Turnover

Inventory turnover is the sum of all inventory transactions (both increments and decrements) recorded since the allocation reset date. This value can be negative if there are more decrements than increments.

#### Perpetual Stock

Products with the perpetual flag set to `true` are treated as always available, regardless of actual stock levels. This is useful for:

*   Digital products
*   Made-to-order items
*   Products with unlimited availability

#### Pre-order and Backorder Handling

This API supports three modes for handling products that are not currently in stock:

*   **none**: No pre-order or backorder capability
*   **preorder**: Product can be ordered before it becomes available
*   **backorder**: Product can be ordered when temporarily out of stock

### Use Cases

#### Availability & Monitoring

*   Verify product stock status and calculated fields (such as ATS) before displaying items to shoppers.
*   Monitor current stock levels, allocation, and turnover history to determine replenishment needs.

#### Lifecycle Management

*   Perform the first-time setup for new products or execute a complete inventory reset/replacement.
*   Modify specific fields—such as in-stock dates, pre-order/backorder settings, or perpetual stock flags—without affecting the rest of the record.
*   Adjust specific allocation amounts dynamically as stock moves.
*   Permanently remove records for discontinued products or obsolete entries during list reorganization.

### Best Practices

#### Inventory Updates

1.  Use PATCH for partial updates: When only updating specific fields, use PATCH to avoid accidentally clearing other data.
2.  Monitor concurrent updates: Handle 409 Conflict responses appropriately when multiple systems update the same record.
3.  Validate allocations: Ensure allocation amounts are non-negative.
4.  Reset dates: Update the allocation reset date when resetting inventory to accurately track turnover.

#### Stock Management

1.  Regular synchronization: Keep inventory records synchronized with your inventory management system.
2.  ATS monitoring: Monitor ATS values to ensure products don't oversell.
3.  Turnover tracking: Use turnover data to understand inventory movement patterns.
4.  Perpetual stock usage: Use perpetual stock flag only for appropriate product types.

#### Pre-order and Backorder

1.  Clear handling mode: Set appropriate pre-order/backorder handling based on product availability strategy.
2.  Allocation planning: Use preOrderBackOrderAllocation to control how many pre-orders or backorders are accepted.
3.  In-stock dates: Provide accurate in-stock dates for pre-order items to set customer expectations.

#### Security and Access Control

1.  Read vs. Write access: Use `sfcc.inventory-lists` scope for read-only operations and `sfcc.inventory-lists.rw` for modifications.
2.  Organization context: Scope all operations to an organization to ensure proper data isolation.
3.  Global scope: Perform inventory operations at the global level, not site level.

### Custom Attributes

The Product Inventory Record schema supports custom attributes using the `c_*` naming convention. These attributes allow you to extend the standard inventory model with custom business logic and data.

**Example custom attributes:**

*   `c_supplierCode`: Track supplier information.
*   `c_warehouseLocation`: Store warehouse location data.
*   `c_minimumOrderQuantity`: Define minimum order quantities.
*   `c_leadTime`: Track expected lead times.

### Rate Limiting

For load shedding and rate limiting information, see [Load Shedding and Rate Limiting.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html)

### Related APIs

*   Products API: Manage product catalog information.
*   Inventory Availability API: Query real-time inventory availability across locations.
*   Inventory Reservation API: Reserve inventory for orders.
*   Orders API: Process orders with inventory allocation.

**Version:** 1.1.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/inventory-lists/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2)
    
    Account Manager OAuth 2.0 security scheme for admin APIs.
    
    Use the Account Manager to obtain access tokens for making API calls. The scope determines the level of access to inventory list resources.
    
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.inventory-lists: \[object Object\]
    *   Scope sfcc.inventory-lists.rw: \[object Object\]

## Operations

### GET Get a product inventory record.

`GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `getProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists, sfcc.inventory-lists.rw).

Get a product inventory record by product ID and inventory list ID.

Only product inventory records that exist are returned. The response includes:

*   Current stock levels and availability (ATS)
*   Allocation information
*   Pre-order and backorder handling configuration
*   Custom attributes

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    

#### Responses

*   **200** Product inventory record retrieved successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example: ProductInventoryRecordResponse_ Product inventory record retrieved successfully.
    
    Example of a successful product inventory record retrieval
    
    ```
    {
      "productId": "P1234567890",
      "productName": "Sample Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": false,
      "allocation": {
        "amount": 100,
        "resetDate": "2024-01-15T10:00:00.000Z"
      },
      "inStockDate": "2024-02-01T00:00:00.000Z",
      "ats": 95,
      "stockLevel": 95,
      "quantityOnOrder": 5,
      "inventoryTurnover": 5,
      "preOrderBackOrderHandling": "none",
      "preOrderBackOrderAllocation": 0,
      "c_customField": "custom value"
    }
    ```
    
    _Example: ProductInventoryRecordPerpetual_ Product inventory record with perpetual stock
    
    Example of a product inventory record set to always be in stock
    
    ```
    {
      "productId": "P9999999999",
      "productName": "Always Available Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": true,
      "ats": 999999,
      "stockLevel": 999999,
      "quantityOnOrder": 0,
      "inventoryTurnover": 0,
      "preOrderBackOrderHandling": "none",
      "preOrderBackOrderAllocation": 0
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user."
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Your access token is valid, but you don’t have the required permissions to access the resource."
    }
    ```
    
*   **404** Not Found. The specified product inventory record or inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ProductInventoryRecordNotFound_ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-inventory-record-not-found",
      "title": "Product Inventory Record Not Found",
      "detail": "Product inventory record with product ID 'P1234567890' in inventory list 'inventory-list-001' was not found.",
      "productId": "P1234567890",
      "inventoryListId": "inventory-list-001"
    }
    ```
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/inventory-list-not-found",
      "title": "Inventory List Not Found",
      "detail": "Inventory list with ID 'inventory-list-001' was not found.",
      "inventoryListId": "inventory-list-001"
    }
    ```
    

### PUT Create or replace a product inventory record.

`PUT /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `createOrUpdateProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Create a new product inventory record or replace an existing one using the information provided.

When replacing an existing record, the record is replaced with the information provided in the request.

The `preOrderBackOrderHandling` parameter defaults to "none" if not specified.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID

#### Request body (required)

The product inventory record

Media type: `application/json`. Schema: `ProductInventoryRecord`.

_Example: CreateProductInventoryRecordRequest_ Create a new product inventory record.

Example of creating a new product inventory record with allocation

```
{
  "productId": "P1234567890",
  "inventoryListId": "inventory-list-001",
  "perpetualFlag": false,
  "allocation": {
    "amount": 100,
    "resetDate": "2024-01-15T10:00:00.000Z"
  },
  "inStockDate": "2024-02-01T00:00:00.000Z",
  "preOrderBackOrderHandling": "none",
  "preOrderBackOrderAllocation": 0
}
```

_Example: EnablePerpetualStock_ Enable perpetual stock.

Example of setting a product to always be in stock

```
{
  "productId": "P1234567890",
  "perpetualFlag": true
}
```

#### Responses

*   **200** Product inventory record updated successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example: ProductInventoryRecordUpdated_ Product inventory record updated successfully.
    
    Example of a successfully updated product inventory record
    
    ```
    {
      "productId": "P1234567890",
      "productName": "Sample Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": false,
      "allocation": {
        "amount": 150,
        "resetDate": "2024-01-20T10:00:00.000Z"
      },
      "inStockDate": "2024-02-15T00:00:00.000Z",
      "ats": 145,
      "stockLevel": 145,
      "quantityOnOrder": 5,
      "inventoryTurnover": 5,
      "preOrderBackOrderHandling": "preorder",
      "preOrderBackOrderAllocation": 50
    }
    ```
    
*   **201** Product inventory record created successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example: ProductInventoryRecordCreated_ Product inventory record created successfully.
    
    Example of a successfully created product inventory record
    
    ```
    {
      "productId": "P1234567890",
      "productName": "New Product",
      "inventoryListId": "inventory-list-001",
      "perpetualFlag": false,
      "allocation": {
        "amount": 100,
        "resetDate": "2024-01-15T10:00:00.000Z"
      },
      "inStockDate": "2024-02-01T00:00:00.000Z",
      "ats": 100,
      "stockLevel": 100,
      "quantityOnOrder": 0,
      "inventoryTurnover": 0,
      "preOrderBackOrderHandling": "none",
      "preOrderBackOrderAllocation": 0
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### DELETE Delete a product inventory record.

`DELETE /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `deleteProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Delete a product inventory record by product ID and inventory list ID.

This operation permanently removes the inventory record. Once deleted, the record cannot be recovered unless recreated using the PUT operation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID

#### Responses

*   **204** Product inventory record deleted successfully. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified product inventory record or inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ProductInventoryRecordNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: ProductInventoryRecordNotFound_ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### PATCH Update a product inventory record.

`PATCH /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId}`

Operation ID: `updateProductInventoryRecord`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Update the product inventory record with the specified information.

Only the fields provided in the request body are updated. All other fields are unchanged. This is useful for partial updates such as adjusting allocation or changing pre-order/backorder handling.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `productId` (path, ProductId, required) The product ID

#### Request body (required)

The product inventory record to be updated and the fields to update

Media type: `application/json`. Schema: `ProductInventoryRecord`.

_Example: UpdateProductInventoryRecordRequest_ Update an existing product inventory record.

Example of updating allocation and stock information

```
{
  "productId": "P1234567890",
  "allocation": {
    "amount": 150,
    "resetDate": "2024-01-20T10:00:00.000Z"
  },
  "perpetualFlag": false,
  "inStockDate": "2024-02-15T00:00:00.000Z",
  "preOrderBackOrderHandling": "preorder",
  "preOrderBackOrderAllocation": 50
}
```

_Example: UpdateAllocationOnly_ Update only the allocation information.

Example of updating only the allocation amount

```
{
  "productId": "P1234567890",
  "allocation": {
    "amount": 200
  }
}
```

#### Responses

*   **200** Product inventory record updated successfully.
    
    Media type: `application/json`. Schema: `ProductInventoryRecord`.
    
    _Example ProductInventoryRecordUpdated: same as PUT /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 200 response._ Product inventory record updated successfully.
    
    Example of a successfully updated product inventory record
    
    _Example: ProductInventoryRecordUpdated_ Product inventory record updated successfully.
    
    Example of a successfully updated product inventory record
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified product inventory record or inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ProductInventoryRecordNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: ProductInventoryRecordNotFound_ Product Inventory Record Not Found
    
    The specified product inventory record does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### GET Get an inventory list.

`GET /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `getInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists, sfcc.inventory-lists.rw).

Get an inventory list by ID.

Returns the inventory list configuration including:

*   Description
*   Default in-stock behavior
*   Bundle inventory settings
*   On-order inventory settings
*   Creation and last modified dates
*   Assigned sites (computed)

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    

#### Responses

*   **200** Inventory list retrieved successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example: InventoryListResponse_ Inventory list retrieved successfully.
    
    Example of a successful inventory list retrieval
    
    ```
    {
      "id": "inventory-list-001",
      "description": "Main inventory list for warehouse A",
      "defaultInStock": false,
      "useBundleInventoryOnly": false,
      "onOrderInventoryEnabled": false,
      "creationDate": "2024-01-10T08:00:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z",
      "assignedSites": [
        "SiteGenesis",
        "SiteGenesis US"
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### PUT Create or replace an inventory list.

`PUT /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `createOrUpdateInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Create a new inventory list or replace an existing one using the information provided.

When replacing an existing list, the list is replaced with the information provided in the request.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.

#### Request body (required)

The inventory list

Media type: `application/json`. Schema: `InventoryList`.

_Example: CreateInventoryListRequest_ Create a new inventory list.

Example of creating a new inventory list with configuration

```
{
  "id": "inventory-list-001",
  "description": "Main inventory list for warehouse A",
  "defaultInStock": false,
  "useBundleInventoryOnly": false,
  "onOrderInventoryEnabled": false
}
```

#### Responses

*   **200** Inventory list updated successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example: InventoryListUpdated_ Inventory list updated successfully.
    
    Example of a successfully updated inventory list
    
    ```
    {
      "id": "inventory-list-001",
      "description": "Updated inventory list for warehouse A",
      "defaultInStock": true,
      "useBundleInventoryOnly": false,
      "onOrderInventoryEnabled": true,
      "creationDate": "2024-01-10T08:00:00.000Z",
      "lastModified": "2024-02-01T14:00:00.000Z",
      "assignedSites": [
        "SiteGenesis",
        "SiteGenesis US"
      ]
    }
    ```
    
*   **201** Inventory list created successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example: InventoryListCreated_ Inventory list created successfully.
    
    Example of a successfully created inventory list
    
    ```
    {
      "id": "inventory-list-001",
      "description": "Main inventory list for warehouse A",
      "defaultInStock": false,
      "useBundleInventoryOnly": false,
      "onOrderInventoryEnabled": false,
      "creationDate": "2024-01-10T08:00:00.000Z",
      "lastModified": "2024-01-10T08:00:00.000Z",
      "assignedSites": []
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    

### DELETE Delete an inventory list.

`DELETE /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `deleteInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Delete an inventory list by ID.

This operation permanently removes the inventory list. Once deleted, the list cannot be recovered unless recreated using the PUT operation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.

#### Responses

*   **204** Inventory list deleted successfully. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

### PATCH Update an inventory list.

`PATCH /organizations/{organizationId}/inventory-lists/{inventoryListId}`

Operation ID: `updateInventoryList`. Security: AmOAuth2 (sfcc.inventory-lists.rw).

Update the inventory list with the specified information.

Only the fields provided in the request body are updated. All other fields are unchanged. This is useful for partial updates such as changing default in-stock behavior or enabling on-order inventory.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `inventoryListId` (path, string, required) The inventory list ID  
    Minimum length: 1. Maximum length: 256. Example: `inventory-list-001`.

#### Request body (required)

The inventory list fields to update

Media type: `application/json`. Schema: `InventoryList`.

_Example: UpdateInventoryListRequest_ Update an existing inventory list.

Example of updating inventory list configuration

```
{
  "id": "inventory-list-001",
  "description": "Updated inventory list for warehouse A",
  "defaultInStock": true,
  "onOrderInventoryEnabled": true
}
```

#### Responses

*   **200** Inventory list updated successfully.
    
    Media type: `application/json`. Schema: `InventoryList`.
    
    _Example InventoryListUpdated: same as PUT /organizations/{organizationId}/inventory-lists/{inventoryListId} 200 response._ Inventory list updated successfully.
    
    Example of a successfully updated inventory list
    
    _Example: InventoryListUpdated_ Inventory list updated successfully.
    
    Example of a successfully updated inventory list
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 403 response._
    
*   **404** Not Found. The specified inventory list does not exist.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InventoryListNotFound: same as GET /organizations/{organizationId}/inventory-lists/{inventoryListId}/product-inventory-records/{productId} 404 response._ Inventory List Not Found
    
    The specified inventory list does not exist.
    
    _Example: InventoryListNotFound_ Inventory List Not Found
    
    The specified inventory list does not exist.
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### ProductInventoryRecord

Product inventory record

*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product  
    Maximum length: 256. Example: `Sample Product`.
*   `inventoryListId` (_string_) The user-supplied ID of the inventory list.  
    Maximum length: 256. Example: `inventory-list-001`.
*   `perpetualFlag` (_boolean_) The flag that determines if the product is perpetually in stock.  
    Example: `false`.
*   `allocation` (_ProductInventoryRecordAllocation_)
*   `inStockDate` (_string (date-time)_) The date that the item is expected to be in stock.  
    Example: `2024-02-01T00:00:00.000Z`.
*   `ats` (_number (double)_, read-only) The quantity of items available to sell (ATS). This is calculated as the allocation plus the preorderBackorderAllocation minus the turnover.  
    Example: `95`.
*   `stockLevel` (_number (double)_, read-only) The current stock level. This is calculated as the allocation minus the turnover.  
    Example: `95`.
*   `quantityOnOrder` (_number (double)_, read-only) The on order quantity, which is the quantity of all transactions for this record since the allocation reset date.  
    Example: `5`.
*   `inventoryTurnover` (_number (double)_, read-only) The sum of all inventory transactions (decrements and increments) that have been recorded subsequent to the allocation reset date. The value can be negative in the case of a higher quantity of inventory decrements than increments.  
    Example: `5`.
*   `preOrderBackOrderHandling` (_PreorderBackorderHandling_)
*   `preOrderBackOrderAllocation` (_number (double)_) The quantity of items that are allocated for sale, beyond the initial stock allocation.  
    Example: `0`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### InventoryList

Inventory list resource

*   `id` (_string_, required) The user-supplied ID of the inventory list.  
    Maximum length: 256. Example: `inventory-list-001`.
*   `description` (_string_) The user-supplied description of this inventory list.  
    Maximum length: 4000. Example: `Main inventory list for warehouse A`.
*   `defaultInStock` (_boolean_) True if the default for products in the inventory list is to be in stock. The default value is false if not specified.  
    Example: `false`.
*   `useBundleInventoryOnly` (_boolean_) True if the inventory list is used in bundle inventory only. The default value is false if not specified.  
    Example: `false`.
*   `onOrderInventoryEnabled` (_boolean_) True if the on-order flag is enabled. The default value is false if not specified.  
    Example: `false`.
*   `creationDate` (_string (date-time)_, read-only) The date and time the inventory list was created.  
    Example: `2024-01-10T08:00:00.000Z`.
*   `lastModified` (_string (date-time)_, read-only) The date and time the inventory list was last modified.  
    Example: `2024-01-15T10:30:00.000Z`.
*   `assignedSites` (_array of string_, read-only) The list of site display names or site Ids this inventory list is assigned to. This is a computed attribute and cannot be directly modified.  
    Items: Maximum length: 256. Example: `SiteGenesis`.
    
    _Example_
    
    ```
    [
      "SiteGenesis",
      "SiteGenesis US"
    ]
    ```
    

### ProductInventoryRecordAllocation

Product inventory record allocation

*   `amount` (_number (double)_) The allocation quantity that is currently set. The quantity unit matches the product unit.  
    Minimum: 0. Example: `100`.
*   `resetDate` (_string (date-time)_) The date the allocation quantity was initialized or reset.  
    Example: `2024-01-15T10:00:00.000Z`.

### PreorderBackorderHandling

The enum holding the records' configuration before backorder handling. Possible values are:

*   `none` - No pre-order or backorder handling
*   `preorder` - Product available for pre-order
*   `backorder` - Product available for backorder

Type: `string`.

Allowed values: `none`, `preorder`, `backorder`. Example: `none`.

<!-- document id=8f3657b2b17cb5d54a89fa78873480f2fcb6574d0db3381f2c70da35d5618208 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/inventory-management-api.md -->

Inventory Management API

# Inventory Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-management-api/inventory-management-api-oas-public.yaml)

Merchant API to manage inventory in the POS system.

**Version:** 2.3.4

## Tags

### Inventory Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-management-api/inventory-management-api-oas-public.yaml)

Merchant API to manage inventory in the POS system.

## Operations

### PUT Cancel cycle count.

`PUT /merchant/{version}/ims/inventory/cyclecount/cancel`

Operation ID: `cancelCycleCount`. Tags: Inventory Management API.

Cancel the specified cycle count.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `CycleCountCancelRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountCancelResponse`.
    

### POST Create IMS ASN.

`POST /merchant/{version}/ims/inventory/asn`

Operation ID: `createASN`. Tags: Inventory Management API.

Create an ASN in the IMS system.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `AdvanceShippingNotice`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### POST Create full cycle count.

`POST /merchant/{version}/ims/inventory/cyclecount/full`

Operation ID: `createFullCycleCount`. Tags: Inventory Management API.

Create a full cycle count. The complete inventory of products in a store can only be counted through a full cycle count.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `FullCycleCountRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountResponse`.
    

### POST Create manual cycle count.

`POST /merchant/{version}/ims/inventory/cyclecount/manual`

Operation ID: `createManualCycleCount`. Tags: Inventory Management API.

Create a manual cycle count. The manual cycle count allows counting of a specific set of products.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ManualCycleCountRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountResponse`.
    

### POST Create partial cycle count.

`POST /merchant/{version}/ims/inventory/cyclecount/partial`

Operation ID: `createPartialCycleCount`. Tags: Inventory Management API.

Create a partial cycle count. Cycle count for a particular group of products that fall within a selected category, brand, or any other product attribute that is provided in the request.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `PartialCycleCountRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountResponse`.
    

## Schemas

### CycleCountCancelRequest

*   `cycleCountId` (_integer (int64)_) Cycle count ID which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `spring-2023`.
*   `storeId` (_string_, required) Store ID corresponding to cycle count being canceled.  
    Example: `001`.

### CycleCountCancelResponse

*   `cycleCountId` (_integer (int64)_) Cycle count ID which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `spring-2023`.
*   `storeId` (_string_, required) Store ID corresponding to cycle count being canceled.  
    Example: `001`.
*   `errorMessage` (_string_, read-only) If the cycle count request fails, a detailed error message is provided.
*   `errorCode` (_string_, read-only) If the cycle count request fails, an error code is provided.  
    Allowed values: `CYCLE_COUNT_ERROR`.

### AdvanceShippingNotice

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `asnType` (_string_) ASN Type.  
    Allowed values: `ORIGINAL`, `CANCELLATION`, `CANCEL_REISSUE`, `UNKNOWN`.
*   `shipmentId` (_string_) An identifier for the shipment referenced in the ASN.
*   `shippedTimestamp` (_integer (int64)_) The time that the shipment was shipped represented as milliseconds since epoch.
*   `shipment` (_Shipment_, required)
*   `lastProcessedById` (_string_, required) ID for the person or entity who processed this inventory transfer.
*   `lastProcessedByName` (_string_, required) Name for the person/entity who processed this inventory transfer.
*   `createdOn` (_string_) Inventory transfer created date.

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### FullCycleCountRequest

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.

### CycleCountResponse

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.
*   `errorMessage` (_string_, read-only) If the cycle count request fails, a detailed error message is provided.
*   `errorCode` (_string_, read-only) If the cycle count request fails, an error code is provided.  
    Allowed values: `CYCLE_COUNT_ERROR`.

### ManualCycleCountRequest

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.
*   `productIds` (_array of string_, required) List of product IDs applicable for manual cycle count for specific products.
    
    Each item: Product ID applicable for manual cycle count.
    

### PartialCycleCountRequest

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.
*   `criteria` (_PartialCycleCountCriteria_, required)

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### Shipment

Shipment details.

*   `poNumber` (_string_) Purchase Order Number.
*   `uploadNumber` (_string_) Unique identifier for the upload batch, used to group related corporate transfers.
*   `shipFrom` (_IMSAddress_)
*   `shipTo` (_IMSAddress_, required)
*   `orders` (_array of Order_, required) List of orders contained in the shipment.

### PartialCycleCountCriteria

Partial cycle count is done on the products which satisfy the selection criteria. The selection criteria is based on any one of the product attributes.

*   `attribute` (_string_, required, write-only) A product attribute used to determine the products that require cycle count. POS product has multiple attributes like brand, category, color, size, etc. Refer to the create product API (POST /merchant/{version}/products). Note: To utilize any product attribute, it must first be included in the product feed.  
    Example: `brand`.
*   `values` (_array of string_, required, write-only) List of values corresponding to the attribute. The values must match those provided in the product feed.
    
    Each item: Value corresponding to the attribute. The value must match those provided in the product feed.
    
      
    Items: Example: `[Rolex,Timex]`. Example: `[Rolex,Timex]`.

### IMSAddress

IMS-specific address format for inventory management and fulfillment operations. Used for shipFrom and shipTo locations in ASN shipments.

*   `locationId` (_string_) Location identifier.
*   `locationType` (_string_) Type of location (e.g., warehouse, store, distribution center).
*   `name` (_string_) Primary location name.
*   `additionalName` (_string_) Additional location name or identifier.
*   `streetAddress1` (_string_) Street address line 1.
*   `streetAddress2` (_string_) Street address line 2.
*   `city` (_string_) City.
*   `state` (_string_) State or province.
*   `postalCode` (_string_) Postal or ZIP code.
*   `country` (_string_) Country.

### Order

List of orders contained in the shipment.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `pallets` (_array of Pallet_, required) List of pallets contained in the order.

### Pallet

List of pallets contained in the order.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `cartons` (_array of Carton_, required) List of cartons contained in the pallet.

### Carton

List of cartons contained in the pallet.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `items` (_array of IMSInventoryProduct_, required)
*   `hasSerializedProduct` (_boolean_) App uses this boolean to determine the receiving of the entire pallet or carton.
*   `cartonShipments` (_array of Shipment_) List of box shipments contained in the carton.

### IMSInventoryProduct

Specific to inventory product.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `productTitle` (_string_) Product title.
*   `productImageUrl` (_string_) Product image URL.
*   `color` (_string_) Product color.
*   `size` (_string_) Product size.
*   `gtin` (_string_) Product UPC code.
*   `vendorNumber` (_string_) Product vendor number.
*   `quantity` (_integer (int32)_, required) Product quantity being transferred.  
    Minimum: 1.
*   `quantityTransferred` (_integer (int32)_) Actual product quantity transferred.
*   `quantityReceived` (_integer (int32)_) Actual product quantity received.
*   `serialNumberedItems` (_array of ClearanceItem_)
*   `fullPriceSerialNumbers` (_array of string_) Serial numbers.
*   `removedSerialNumbers` (_array of string_) Removed serial numbers. This is for the backend to remove serial numbers from the database.
*   `serialNumberRequired` (_boolean_) Serial number required.
*   `scannedSerialNumbers` (_array of string_) Scanned serial numbers.
*   `externalDocNumber` (_string_) External Doc Number.
*   `externalLineNumber` (_string_) External Line Number.
*   `itemHierarchyId` (_string_) Item hierarchy ID inside a container.
*   `costPrice` (_number (double)_) Cost price of each item.
*   `casePackQuantity` (_integer (int32)_) Quantity of item per case pack.
*   `casePackID` (_string_) ID of case packed products.
*   `inventoryTransferDetailId` (_string_) When a user manually adds an item to transfer, the backend allocates a UUID to the field and returns it in the response. For all subsequent calls from the app, the same UUID is provided in the request and is used by the backend to determine whether to update or insert the item.
*   `salesPrice` (_number_) Sales price of the product.
*   `shipper` (_string_) Carrier name, for example, FedEx or UPS.

### ClearanceItem

Product location within the store.

*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `clearancePrice` (_number_)
*   `itemLocationWithinStore` (_string_)
*   `instructionText` (_string_)

<!-- document id=f71ade9a945b955878bc8a943568557dad3a45ffab1f2b0cc2078328ace4ae63 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/inventory-reservation-service.md -->

Inventory Reservation (OCI)

# Inventory Reservation (OCI)

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/inventory-reservation-service/reservation-oas-v1-public.yaml)

## API Overview

Inventory Reservation APIs enable you to place, manage, and fulfill reservations using Omnichannel Inventory.

Inventory Reservation APIs can be segregated into the following functional categories.

| Category | Endpoint Description |
| --- | --- |
| Reservations Management | API endpoints for creating and editing order reservation data. Reserved amounts affect the quantities that are available to order and fulfill. |

**Note**: Omnichannel Inventory uses the Tenant Group ID in place of the Organization ID. For more information, see [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html).

### Rate Limits

For load shedding and rate limiting information, see [Load Shedding and Rate Limiting.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html)

### Authentication and Authorization

Clients calling Omnichannel Inventory can be authenticated in one of two ways.

*   Authenticate using Account Manager with your B2C Commerce credentials.
*   Authenticate using your Salesforce org credentials.

If you are using both B2C Commerce and Salesforce Order Management, you can use either authentication approach. However, we recommend choosing only one to avoid mixing approaches across your integrations.

The different authentication approaches do not impact the purpose or performance of the APIs.

Each authentication approach uses a unique set of scopes.

| Scopes for Account Manager Authentication | Scopes for Salesforce org Authentication |
| --- | --- |
| sfcc.inventory.impex-graphs | sfcc\_inventory\_impex\_graphs |
| sfcc.inventory.impex-inventory.rw | sfcc\_inventory\_impex\_inventory\_rw |
| sfcc.inventory.impex-inventory | sfcc\_inventory\_impex\_inventory |
| sfcc.inventory.availability | sfcc\_inventory\_availability |
| sfcc.inventory.availability.rw | sfcc\_inventory\_availability\_rw |
| sfcc.inventory.reservations | sfcc\_inventory\_reservations |
| sfcc.inventory.reservations.rw | sfcc\_inventory\_reservations\_rw |

Calls through the API gateway to Omnichannel Inventory must have a valid OAUTH bearer token. The tenant identifier used by Omnichannel Inventory is supplied in the header of the token.

All request and response body entities are composed in JSON.

### Use Cases

#### Reservation Management

Use these API endpoints to create and edit order reservation data. Reserved amounts affect the quantities that are available to order and fulfill.

##### Reserve Inventory

This endpoint contains data representing a client order in the body of the request. The response body contains the items Omnichannel Inventory was able to reserve, _which may be less than what was requested_.

##### Update and Cancel Reservation

This endpoint is used primarily for adding items to an existing reservation. The reservation ID is provided as part of the URL, and will be used to locate the reservation document to update. The response body will contain information regarding which items were able to be added, as well as the items that failed to be added along with the reason for the failure.

This endpoint is also used to cancel a reservation request when you have the Reservation ID that was created at the time of the reservation. This is the preferred method for cancellation, and should always be used if the Reservation ID is available. When using the Cancel Reservation endpoint with the Reservation ID, the reservation document is marked as cancelled and OCI adjusts the reservation and inventory counts based on the reservation document details.

##### Unreserve Quantity

Use this endpoint to unreserve a previously reserved amount with the quantity, SKU, and place identifier (group or location) specified in the body of the request. This endpoint is provided in case you find yourself in any situation where the Reservation ID is unavailable, or if you find it easier to provide the details to unreserve directly (SKU, and Group or Location). The net effect is the same as using the Cancel Reservation endpoint. When performing an Unreserve, the reservation counts are removed from the location or group using the details provided in the call instead of the details in the reservation document.

##### Move Reservation Quantity

Use this endpoint to move reservation quantity between a group and location, a location and a group or between 2 locations, with the quantity and place identifiers specified in the body of the request. A Reservation ID is not required for reservation moves. A reservation move between groups and/or locations is determined in an OMS and only requires that a reserved quantity is moved from one group/location to another. It doesn't need to be aware of or alter the initial reservation document.

##### Fulfill Quantity

Use this endpoint to fulfill a reservation amount at a location with the SKU, quantity, and place identifier (group or location) specified in the body of the request. Fulfilling a reservation occurs when the client ships an order and needs to ensure the reserved and on-hand amounts are correct. This is an atomic operation to ensure that all values are successfully updated.

In the case of a response that includes errors, the caller must ensure that they do NOT resubmit the entire request. Doing so will result in a EntityAlreadyExists error response. The HTTP 200 response should be parsed for the skus with errors and then each SKU handled individually to determine if resubmitting is necessary.

Provided in the table below are a few examples of conditions that may exist in the system and the responses that would be expected from the fulfill call based on those conditions.

| Condition | Request | Result |
| --- | --- | --- |
| On Hand = 0 and Reserved = 1 | requested 1 QTY to fufill | the reservation will be fulfilled with no errors |
| On hand = 1 and Reserved = 0 | requested 1 QTY to fufill | an insufficient quantity exception is thrown and OH remains the same |
| On hand = 2 and Reserved = 1 | requested 2 QTY to fufill | an insufficient quantity exception is thrown and OH remains 2, Reserved remains 1 |
| On hand = 1 and Reserved = 2 | requested 2 QTY to fufill | both reservations are fulfilled and OH is reduced to 0 |

##### The Reservation Document

*   The api consumer creates the reservation document in order to have a reference containing pertinent information associated with the reservation (Reservation ID, SKU, Qty, Location Group or Location).
    
*   The api consumer sends the reservation document to OCI as part of reservation, and to an OMS (SOM or 3rd Party) as part of the order.
    
*   The reservation document is used by OMS to know which Group/Location a reservation was placed against for routing purposes.
    
*   The reservation document is used by OCI/ECOM in the event that the reservation needs to be cancelled with the Cancel endpoint. (The unreserve endpoint can be used as well, which doesn't require the Reservation ID, but does require other pertinent reservation details such as SKU, and Group or Location)
    

#### Group Reservations

Because inventory is only available at locations, group availability reflects the aggregation of all locations in the group. It also includes reservations placed at a group that has not been allocated to a specific location.

##### General Lifecycle of a Group Reservation

*   Place the group reservation using `reservation-documents`.
*   Allocate the reservation to a location in the group using `transfers`.
*   Fulfill the reservation at the location using `fulfillments`.

##### Example flow:

Assume Group A has Location 1 and Location 2.

Given the following state of the group:

| Place | On hand | Reserved | ATO |
| --- | --- | --- | --- |
| Location 1 | 50 | 0 | 50 |
| Location 2 | 50 | 0 | 50 |
| Group A | 100 | 0 | 100 |

→ Place group reservation of 1

| Place | On hand | Reserved | ATO |
| --- | --- | --- | --- |
| Location 1 | 50 | 0 | 50 |
| Location 2 | 50 | 0 | 50 |
| Group A | 100 | 1 | 99 |

→ Allocate reservation to Location 2

| Place | On hand | Reserved | ATO |
| --- | --- | --- | --- |
| Location 1 | 50 | 0 | 50 |
| Location 2 | 50 | 1 | 49 |
| Group A | 100 | 1 | 99 |

→ Fulfill at Location 2

| Place | On hand | Reserved | ATO |
| --- | --- | --- | --- |
| Location 1 | 50 | 0 | 50 |
| Location 2 | 49 | 0 | 49 |
| Group A | 99 | 0 | 99 |

Group Reservations **DO NOT** affect a location’s reported Available to Order (ATO) quantity. Essentially, group reservations are a promise returned by the group that one or more of its locations can satisfy the requested reservation quantity. It’s possible that a reservation made against a location could fail if Omnichannel Inventory determines it would break any such existing promises.

For example, a location with a reported ATO of 3 can fail with an ‘Insufficient Quantity’ response when a reservation quantity of 3 is made against it. This scenario happens when some or all of the location’s inventory is unavailable due to a promise (group reservation) made at one of its associated groups.

Fortunately, Omnichannel Inventory exhausts all possibilities to accommodate a group reservation before resulting in failure.

As shown in the Group A example above, a group reservation is only reflected at the location level when it's allocated to one or more locations.

##### Shared Locations

When groups share locations things get a little more complex. For example, group reservations made at one group could increase the count of reservations at another if they share one or more locations.

Example Scenario:

Assume that Group A has Location 1 and Location 2 and Group B has Location 2 and Location 3.

Thus, Location 2 is **shared**.

Given the following state of the groups:

| Place | On hand | Reserved | ATO |
| --- | --- | --- | --- |
| Location 1 | 5 | 0 | 5 |
| Location 2 | 5 | 0 | 5 |
| Group A | 10 | 0 | 10 |
|  |  |  |  |
| Location 2 | 5 | 0 | 5 |
| Location 3 | 15 | 0 | 15 |
| Group B | 20 | 0 | 20 |

→ Placing a Group B reservation of 17

| Place | On hand | Reserved | ATO |
| --- | --- | --- | --- |
| Location 2 | 5 | 0 | 5 |
| Location 3 | 15 | 0 | 15 |
| Group B | 20 | 17 | 3 |

→ Will increase Group A's reservation count by 2

| Place | On hand | Reserved | ATO |
| --- | --- | --- | --- |
| Location 1 | 5 | 0 | 5 |
| Location 2 | 5 | 0 | 5 |
| Group A | 10 | 2 | 8 |

As stated previously, group reservations are a promise returned by the group that one or more of its locations can satisfy the requested reservation quantity. When determining that promise, group reservations follow a "least shared location" approach in that they first lock inventory in their locations which are least shared with other groups. Consequently, that's why, when a reservation of a quantity of 17 was made at Group B, 15 of them were locked at Location 3 first, and the remaining 2 at shared Location 2. As a result, Group A increased its reservation count by 2 to reflect the fact that those 2 are promised elsewhere.

#### Temporary Reservations

When creating reservations, the **expirationSeconds** value indicates the amount of time (in seconds) a reservation maintains a hold on its inventory before releasing it. This expiration time constitutes an approximate time because there’s typically a delay (up to 60+ seconds, under extreme load) from the specified expiration time and the actual release of inventory reflected in availability counts.

Consequently, we suggest that you use the **expirationSeconds** value as a guarantee of a reservation's eventual release of inventory, in the event the client is unable to cancel the reservation due to unforeseen technical issues. In other words, we encourage you to let the client manage the timely cancellation of reservations rather than relying on a reservation's expiration time to prevent underselling scenarios and optimize the accuracy of real-time availability counts.

### Common Response Codes

The following error codes apply to all API endpoints. See the API documentation for a complete list of the error codes and response bodies that can be expected on each endpoint.

*   401 - The OATH bearer token is not valid for the tenant or is no longer valid. The response body has the details.
*   403 - The tenant is not provisioned in the system.
*   5XX - There was a server error. The response body has the details.
*   Unknown - If an Unknown error type is returned, it indicates that an unknown internal error occurred.

### External Reference Identifier

Currently, there are a number of places where a consumer can submit an `ExternalRefId` with their request. This is to allow the consumer to submit user generated data along with their request as a link to other external systems data. For example, if I'm pulling data from an order that has an order ID, I can submit that order ID with my reservation request as the `externalRefId`. Then, if there is a problem with the reservation, there is a way to connect it with the order in the external system that generated the error or problem. This is NOT to be confused with `externalRefId` used in Salesforce Core, or any other services. The usage is exclusive to OCI and is not used anywhere else.

### Correlation-ID

In order to facilitate tracking of operations in OCI, customers must populate a header with the name Correlation-ID, which will be passed through the CDN and sent with the request to OCI. This will help trace requests as they move throughout our service. To be accepted, the correlation-id must be a valid UUIDv2, otherwise, it will be ignored.

When a web-request is passed through the CDN, the CDN's x-correlation-id header value (which comes from their ray-id) also comes into play. In this case, the correlation-id provided will be prepended to the CDN's x-correlation-id and both values will be passed through, separated by a comma.

Some services use a header X-Correlation-ID. In the case of OCI, if this header is used, it is overwritten by the CDN with a new value and the initial purpose of the header is defeated. Use the Correlation-ID instead for a consistent result.

**Version:** 1.1.23

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/inventory/reservation/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.inventory.reservations.rw: Inventory Reservation scope
    *   Scope sfcc\_inventory\_reservations\_rw: Inventory Reservation scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.inventory.reservations.rw: Inventory Reservation scope
    *   Scope sfcc\_inventory\_reservations\_rw: Inventory Reservation scope

## Operations

### PUT Create or update reservations for a number of location groups, locations, or both. If any of the location groups or locations provided in the request are invalid, nothing is processed.

`PUT /organizations/{organizationId}/reservation-documents/{reservationId}`

Operation ID: `createReservations`. Security: AmOAuth2 (sfcc.inventory.reservations.rw, sfcc\_inventory\_reservations\_rw).

Creates or updates a reservation document for the specified organization and reservation ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `reservationId` (path, string, required)  
    Maximum length: 36. Pattern: ^\[0-9a-fA-F\\-\]{36}$. Example: `12345-23456-3456-4567-5678`.

#### Request body (required)

Media type: `application/json`. Schema: `PlaceReservationRequest`.

_Example: placeReservationRequestBodyLocation_ Example request body for placing a reservation by location

```
{
  "externalRefId": "7282822-9823-aaa",
  "expirationSeconds": 300,
  "allowPartialReservations": true,
  "reservationTime": "2019-07-24T21:13:00Z",
  "locations": [
    {
      "id": "warehouse5",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        }
      ]
    }
  ]
}
```

_Example: placeReservationRequestBodyLocationAllOrNothing_ Example request body for placing a reservation by location with all or nothing reservations

```
{
  "externalRefId": "7282822-9823-aaa",
  "expirationSeconds": 300,
  "allowPartialReservations": true,
  "reservationTime": "2019-07-24T21:13:00Z",
  "locations": [
    {
      "id": "warehouse5",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        }
      ],
      "allOrNothingReservations": [
        {
          "id": "a14s-4b1c-1a3cbd4",
          "reservations": [
            {
              "sku": "sku1234",
              "quantity": 10
            }
          ]
        }
      ]
    }
  ]
}
```

_Example: placeReservationRequestBodyGroups_ Example request body for placing a reservation by group

```
{
  "externalRefId": "7282822-9823-aaa",
  "expirationSeconds": 300,
  "allowPartialReservations": true,
  "reservationTime": "2019-07-24T21:13:00Z",
  "groups": [
    {
      "id": "UnitedStates",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        }
      ]
    }
  ]
}
```

_Example: placeReservationRequestBodyLocationAndGroup_ Example request body for placing a reservation by both location and group

```
{
  "externalRefId": "7282822-9823-aaa",
  "expirationSeconds": 300,
  "allowPartialReservations": true,
  "reservationTime": "2019-07-24T21:13:00Z",
  "groups": [
    {
      "id": "UnitedStates",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        }
      ]
    }
  ],
  "locations": [
    {
      "id": "warehouse5",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        }
      ]
    }
  ]
}
```

_Example: placeReservationAgainstATFBody_ Example request body for placing a reservation against ATF

```
{
  "externalRefId": "7282822-9823-aaa",
  "expirationSeconds": 300,
  "allowPartialReservations": true,
  "fulfillOnly": true,
  "reservationTime": "2019-07-24T21:13:00Z",
  "locations": [
    {
      "id": "warehouse5",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        }
      ]
    }
  ]
}
```

#### Responses

*   **200** Successfully received and processed the request. The consumer is responsible for validating the returned data to ensure that the specified quantity was reserved as requested.
    
    Headers:
    
    *   `Location` (string) URI used to retrieve the recorded reservation document.  
        Maximum length: 255. Example: `/organizations/org123/reservation-documents/2345-23456-3456-4567-5678`.
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `PlaceReservationResponseBody`.
    
    _Example reservationNonPartialSomeItemSuccessSomeFail: same as PUT /organizations/{organizationId}/reservation-documents/{reservationId} 200 response._ Example response with some items succeeded and some failed for groups and locations
    
    _Example reservationNonPartialAllItemsFail: same as PUT /organizations/{organizationId}/reservation-documents/{reservationId} 200 response._ Example response where all items failed for groups and locations
    
    _Example: reservationSuccessExample_ Example response with successful reservation for groups and locations
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": true,
      "groups": [
        {
          "id": "UnitedStates",
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10.1
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10.1
            }
          ]
        }
      ]
    }
    ```
    
    _Example: placeReservationResponseBody_ Example response with partial failure for groups and locations
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": false,
      "groups": [
        {
          "id": "UnitedStates",
          "errors": [
            {
              "sku": "sku5678",
              "errorCode": "Unknown"
            }
          ],
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku5678",
              "errorCode": "Unknown"
            }
          ],
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10
            }
          ]
        }
      ]
    }
    ```
    
    _Example: reservationFail_ Example response with reservation failure due to insufficient quantity
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": false,
      "groups": [
        {
          "id": "UnitedStates",
          "errors": [
            {
              "errorCode": "InsufficientQuantity",
              "sku": "sku1234"
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku1234",
              "errorCode": "InsufficientQuantity"
            }
          ]
        }
      ]
    }
    ```
    
    _Example: reservationPartialQtySuccess_ Example response with partial quantity success for groups and locations
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": false,
      "groups": [
        {
          "id": "UnitedStates",
          "errors": [
            {
              "sku": "sku1234",
              "errorCode": "InsufficientQuantity"
            }
          ],
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10.1
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku1234",
              "errorCode": "InsufficientQuantity"
            }
          ],
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10.1
            }
          ]
        }
      ]
    }
    ```
    
    _Example: reservationPartialItemSuccess_ Example response with partial item success for groups and locations
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": true,
      "groups": [
        {
          "id": "UnitedStates",
          "errors": [
            {
              "sku": "sku1234",
              "errorCode": "InsufficientQuantity"
            }
          ],
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10.1
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku1234",
              "errorCode": "InsufficientQuantity"
            }
          ],
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10.1
            }
          ]
        }
      ]
    }
    ```
    
    _Example: reservationPartialNoItemSuccess_ Example response with no item success for groups and locations
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T21:18:00Z",
      "success": false,
      "groups": [
        {
          "id": "Germany",
          "errors": [
            {
              "sku": "sku1234",
              "errorCode": "InsufficientQuantity"
            },
            {
              "sku": "sku5678",
              "errorCode": "InsufficientQuantity"
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku1234",
              "errorCode": "InsufficientQuantity"
            },
            {
              "sku": "sku5678",
              "errorCode": "InsufficientQuantity"
            }
          ]
        }
      ]
    }
    ```
    
    _Example: reservationNonPartialSomeItemSuccessSomeFail_ Example response with some items succeeded and some failed for groups and locations
    
    _Example: reservationNonPartialAllItemsFail_ Example response where all items failed for groups and locations
    
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InvalidRequestLocOrGroupDoesNotExist`.
    
    _Example: locationGroupNotFound_
    
    ```
    {
      "errorCode": "GroupDoesNotExist",
      "message": "No group exists with ID",
      "type": "about:blank"
    }
    ```
    
    _Example: locationIdNotFound_
    
    ```
    {
      "errorCode": "LocationDoesNotExist",
      "message": "No location exists with ID 'warehouse5'",
      "type": "about:blank"
    }
    ```
    
    _Example: noLocationOrGroupsNotProvided_
    
    ```
    {
      "errorCode": "InvalidRequest",
      "message": "No location or groups provided.",
      "type": "about:blank"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: TenantNotProvisioned_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **409** A reservation with the specified ID is in an invalid state.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `ReservationInvalidState`.
    
    _Example: conflictExample_ Example conflict response
    
    ```
    {
      "errorCode": "ReservationInvalidState",
      "message": "Reservation is in a CLOSED state.",
      "type": "about:blank",
      "parameterName": "sku"
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### PATCH Cancel a reservation or add items to an existing reservation document. This endpoint references the reservation document directly, marking it as cancelled or adding the items, and then adjusting the reservation and inventory counts based on the details of the reservation document.

`PATCH /organizations/{organizationId}/reservation-documents/{reservationId}`

Operation ID: `updateReservation`. Security: AmOAuth2 (sfcc.inventory.reservations.rw, sfcc\_inventory\_reservations\_rw).

Cancels or updates an existing reservation document by ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `reservationId` (path, string, required)  
    Maximum length: 36. Pattern: ^\[0-9a-fA-F\\-\]{36}$. Example: `12345-23456-3456-4567-5678`.

#### Request body (required)

Media type: `application/json`. Schema: `UpdateReservationRequestBody`.

_Example: cancelReservation_

```
{
  "status": "CANCELLED"
}
```

_Example: updateReservation_

```
{
  "externalRefId": "7282822-9823-aaa",
  "allowPartialReservations": true,
  "reservationTime": "2019-07-24T21:13:00Z",
  "id": "b45a0d25-d9e2-419f-a55a-f435c871fe2b",
  "locations": [
    {
      "id": "warehouse5",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        },
        {
          "sku": "sku5678",
          "quantity": 7
        }
      ],
      "allOrNothingReservations": {
        "id": "a14s-4b1c-1a3cbd4",
        "reservations": [
          {
            "sku": "sku1234",
            "quantity": 10
          },
          {
            "sku": "skuABCDE",
            "quantity": 27
          }
        ]
      }
    }
  ],
  "groups": [
    {
      "id": "Arizona",
      "reservations": [
        {
          "sku": "sku1234",
          "quantity": 10
        },
        {
          "sku": "skuHIJKL",
          "quantity": 37
        }
      ],
      "allOrNothingReservations": {
        "id": "a14s-4b1c-1a3cbd4",
        "reservations": [
          {
            "sku": "sku1234",
            "quantity": 10
          },
          {
            "sku": "skuZYX",
            "quantity": 47
          }
        ]
      }
    }
  ]
}
```

#### Responses

*   **200** Reservation update request was received and processed successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `UpdateReservationResponse`.
    
    _Example: successfulReservationUpdateResponse_
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": true,
      "groups": [
        {
          "id": "UnitedStates",
          "details": [
            {
              "sku": "sku1234",
              "quantity": 10,
              "adjustment": 5
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "details": [
            {
              "sku": "sku1234",
              "quantity": 8,
              "adjustment": 4
            }
          ]
        }
      ]
    }
    ```
    
    _Example: partialQuantitySuccessfulReservationUpdateResponse_
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": false,
      "groups": [
        {
          "id": "Germany",
          "errors": [
            {
              "sku": "sku3456",
              "errorCode": "InsufficientQuantity"
            }
          ],
          "details": [
            {
              "sku": "sku1234",
              "quantity": 8,
              "adjustment": 4
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku5678",
              "errorCode": "InsufficientQuantity"
            }
          ],
          "details": [
            {
              "sku": "sku9875",
              "quantity": 8,
              "adjustment": 4
            }
          ]
        }
      ]
    }
    ```
    
    _Example: partialAllItemsFailedReservationUpdateResponse_
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": false,
      "groups": [
        {
          "id": "Germany",
          "errors": [
            {
              "sku": "sku3456",
              "errorCode": "InsufficientQuantity"
            },
            {
              "sku": "sku5678",
              "errorCode": "InsufficientQuantity"
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku6789",
              "errorCode": "InsufficientQuantity"
            },
            {
              "sku": "sku7891",
              "errorCode": "InsufficientQuantity"
            }
          ]
        }
      ]
    }
    ```
    
    _Example: failedUpdateReservationUpdateResponse_
    
    ```
    {
      "reservationTime": "2019-07-24T21:13:00Z",
      "expirationTime": "2019-07-24T22:13:00Z",
      "success": false,
      "groups": [
        {
          "id": "Germany",
          "errors": [
            {
              "sku": "sku3456",
              "errorCode": "InsufficientQuantity"
            }
          ]
        }
      ],
      "locations": [
        {
          "id": "warehouse5",
          "errors": [
            {
              "sku": "sku6789",
              "errorCode": "InsufficientQuantity"
            }
          ]
        }
      ]
    }
    ```
    
*   **202** Reservation marked as cancelled. Inventory levels updated asynchronously.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **204** Reservation cancelled successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: InvalidRequestParameter_
    
    ```
    {
      "errorCode": "InvalidRequestParameter",
      "message": "Reservation ID provided does not exist",
      "parameterName": "reservationId",
      "type": "about:blank"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: TenantNotProvisioned_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **404** Entity not found.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: EntityNotFound_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "EntityNotFound",
      "message": "Reservation ID does not exist."
    }
    ```
    
*   **409** A reservation with the specified ID is in an invalid state.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: conflictExample_ Invalid reservation state
    
    ```
    {
      "errorCode": "ReservationInvalidState",
      "message": "Reservation is in a CLOSED state.",
      "type": "about:blank",
      "parameterName": "sku"
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Move reservation quantities between a group and its locations, or between locations. The system does not support transfers between groups. In the case of All or Nothing movements, only Group to Location movements are allowed.

`POST /organizations/{organizationId}/transfers`

Operation ID: `moveReservationQuantity`. Security: AmOAuth2 (sfcc.inventory.reservations.rw, sfcc\_inventory\_reservations\_rw).

Moves reservation quantities between a group and its locations, or between locations.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `MoveReservationBatchPostBody`.

_Example: MoveReservationBatchPostBodyExample_

```
{
  "allOrNothingTransferId": "a14s-4b1c-1a3cbd4",
  "records": [
    {
      "id": "82251928-8863-488e-840b-2aebd10b35ed",
      "externalRefId": "7282822-9823-aaa",
      "from": {
        "location": "warehouse4"
      },
      "to": {
        "location": "warehouse5"
      },
      "sku": "sku-001",
      "quantity": 2.011
    },
    {
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "externalRefId": "7282822-9823-bbb",
      "from": {
        "group": "UnitedStates"
      },
      "to": {
        "location": "warehouse5"
      },
      "sku": "sku-002",
      "quantity": 7.417,
      "ignoreAvailabilityCheck": true
    },
    {
      "id": "12345-23456-3456-4567-5678-6F6F",
      "externalRefId": "1234561-3574-6B6D",
      "from": {
        "location": "warehouse5"
      },
      "to": {
        "group": "UnitedStates"
      },
      "sku": "sku1000",
      "quantity": 5.417
    }
  ]
}
```

#### Responses

*   **200** Batch reservation transfer partially succeeded with errors reported.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `MoveReservationErrorsResponse`.
    
    _Example: MoveReservationErrorsResponseExample_
    
    ```
    {
      "errors": [
        {
          "details": {
            "id": "82251928-8863-488e-840b-2aebd10b57ba",
            "externalRefId": "7282822-9823-aaa",
            "from": {
              "group": "UnitedStates"
            },
            "to": {
              "location": "warehouse5"
            },
            "sku": "sku-002",
            "quantity": 2.011
          },
          "message": "Insufficient Quantity",
          "errorCode": "InsufficientQuantity"
        }
      ]
    }
    ```
    
*   **204** Reservation quantities moved successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: locationNotFound_
    
    ```
    {
      "errorCode": "LocationDoesNotExist",
      "message": "No location exists with ID 'warehouse5'",
      "type": "about:blank"
    }
    ```
    
    _Example: locationGroupNotFound_
    
    ```
    {
      "errorCode": "GroupDoesNotExist",
      "message": "No group exists with ID",
      "type": "about:blank"
    }
    ```
    
    _Example: groupToGroupNotAllowed_
    
    ```
    {
      "errorCode": "InvalidRequestParameter",
      "message": "Group to Group Transfers are not permitted.",
      "type": "about:blank"
    }
    ```
    
    _Example: locationToLocationNotAllowed_
    
    ```
    {
      "errorCode": "InvalidRequestParameter",
      "message": "'from and to' Transfers between locations is not allowed",
      "type": "about:blank"
    }
    ```
    
    _Example: forceReservationLocationToGroupNotAllowed_
    
    ```
    {
      "errorCode": "InvalidRequestParameter",
      "message": "Forcing a reservation cannot be done from a location to a group",
      "type": "about:blank"
    }
    ```
    
    _Example: invalidTransferAllOrNothing_
    
    ```
    {
      "errorCode": "InvalidRequestParameter",
      "message": "All or nothing transfers are only allowed from Group to Location transfer types. Invalid transfer type for request",
      "type": "about:blank"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: TenantNotProvisioned_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Remove reservations for canceled orders or carts. When using the unreserve/release endpoint, the reservation counts are removed from the location or group using the details provided in the call instead of the details in a reservation document (which isn't provided as part of the call to this endpoint).

`POST /organizations/{organizationId}/releases`

Operation ID: `unreserveReservations`. Security: AmOAuth2 (sfcc.inventory.reservations.rw, sfcc\_inventory\_reservations\_rw).

Removes reservations for canceled orders or carts.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `UnreserveRequestBody`.

_Example: RequestBodyGroupExample_ Example request body for unreserving by group

```
{
  "records": [
    {
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "externalRefId": "7282822-9823-aaa",
      "group": "UnitedStates",
      "sku": "sku1234",
      "quantity": 1200.35
    }
  ]
}
```

_Example: RequestBodyLocationExample_ Example request body for unreserving by location

```
{
  "records": [
    {
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "externalRefId": "7282822-9823-aaa",
      "location": "warehouse5",
      "sku": "sku1234",
      "quantity": 1200.35
    }
  ]
}
```

_Example: RequestBodyGroupAndLocationExample_ Example request body for unreserving by group and location

```
{
  "records": [
    {
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "externalRefId": "7282822-9823-aaa",
      "location": "warehouse5",
      "sku": "sku1234",
      "quantity": 1200.35
    },
    {
      "id": "82251928-8863-488e-840b-2aebd10b6666",
      "externalRefId": "7282822-9823-bbb",
      "group": "UnitedStates",
      "sku": "sku5678",
      "quantity": 1.35
    }
  ]
}
```

#### Responses

*   **200** The request was received and processed successfully. The consumer is responsible for validating the returned data to ensure that the specified quantity was released as requested.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `UnreserveResponseBody`.
    
    _Example: responseBodyGroup_ Example response body for group-level unreserve errors
    
    ```
    {
      "errors": [
        {
          "details": {
            "id": "82251928-8863-488e-840b-2aebd10b6666",
            "externalRefId": "7282822-9823-bbb",
            "group": "UnitedStates",
            "sku": "sku5678",
            "quantity": 0
          },
          "message": "Insufficient Quantity",
          "errorCode": "InsufficientQuantity"
        }
      ]
    }
    ```
    
    _Example: responseBodyLocation_ Example response body for location-level unreserve errors
    
    ```
    {
      "errors": [
        {
          "details": {
            "id": "82251928-8863-488e-840b-2aebd10b57ba",
            "externalRefId": "7282822-9823-aaa",
            "location": "warehouse5",
            "sku": "sku1234",
            "quantity": 0
          },
          "message": "Insufficient Quantity",
          "errorCode": "InsufficientQuantity"
        }
      ]
    }
    ```
    
    _Example: responseBodyGroupAndLocation_ Example response body for group and location-level unreserve errors
    
    ```
    {
      "errors": [
        {
          "details": {
            "id": "82251928-8863-488e-840b-2aebd10b6666",
            "externalRefId": "7282822-9823-bbb",
            "group": "UnitedStates",
            "sku": "sku5678",
            "quantity": 0
          },
          "message": "Insufficient Quantity",
          "errorCode": "InsufficientQuantity"
        },
        {
          "details": {
            "id": "82251928-8863-488e-840b-2aebd10b57ba",
            "externalRefId": "7282822-9823-aaa",
            "location": "warehouse5",
            "sku": "sku1234",
            "quantity": 0
          },
          "message": "Insufficient Quantity",
          "errorCode": "InsufficientQuantity"
        }
      ]
    }
    ```
    
*   **204** Reservations for specified items removed successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: genericErrorMessage_
    
    ```
    {
      "errorCode": "InvalidRequest",
      "message": "The format of the message is incorrect",
      "type": "about:blank"
    }
    ```
    
    _Example: tooManyFieldsProvided_
    
    ```
    {
      "errorCode": "InvalidRequestParameter",
      "message": "User provided locationId AND groupId.  You can only provide one or the other, not both in a single record.",
      "type": "about:blank"
    }
    ```
    
    _Example: locationDoesNotExist_
    
    ```
    {
      "errorCode": "LocationDoesNotExist",
      "message": "No location exists with ID 'warehouse5'",
      "type": "about:blank"
    }
    ```
    
    _Example: locationGroupNotFound_
    
    ```
    {
      "errorCode": "GroupDoesNotExist",
      "message": "No group exists with ID",
      "type": "about:blank"
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: TenantNotProvisioned_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

### POST Adjust quantity for an item after fulfillment.

`POST /organizations/{organizationId}/fulfillments`

Operation ID: `fulfillQuantity`. Security: AmOAuth2 (sfcc.inventory.reservations.rw, sfcc\_inventory\_reservations\_rw).

Adjusts the reserved quantity for an item after fulfillment.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `FulfillQuantityRequestBody`.

_Example: FulfillQuantityRequestBodyExample_ Example request body for fulfill quantity

```
{
  "records": [
    {
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "externalRefId": "7282822-9823-aaa",
      "location": "warehouse5",
      "sku": "sku1234",
      "quantity": 1200.35,
      "fulfillmentTime": "2019-07-24T21:13:00Z"
    },
    {
      "id": "82251928-8863-488e-840b-2aeb567d3a87",
      "externalRefId": "7282822-9823-ddd",
      "location": "warehouse4",
      "sku": "sku5678",
      "quantity": 201.27
    }
  ]
}
```

#### Responses

*   **200** Fulfillment partially succeeded with errors reported.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `FulfillQuantityResponseErrors`.
    
    _Example: locationNotFound_ Example response when a location is not found
    
    ```
    {
      "errors": [
        {
          "details": {
            "id": "82251928-8863-488e-840b-2aebd10b57ba",
            "externalRefId": "7282822-9823-aaa",
            "location": "warehouse5",
            "sku": "sku1234",
            "quantity": 1200.35
          },
          "message": "Failed to fulfill, invalid location provided.",
          "errorCode": "Unknown"
        }
      ]
    }
    ```
    
    _Example: insufficientQty_ Example response when there is insufficient quantity
    
    ```
    {
      "errors": [
        {
          "details": {
            "id": "82251928-8863-488e-840b-2aebd10b57ba",
            "externalRefId": "7282822-9823-aaa",
            "location": "warehouse5",
            "sku": "sku1234",
            "quantity": 1200.35
          },
          "message": "Insufficient Quantity.",
          "errorCode": "Unknown"
        }
      ]
    }
    ```
    
*   **204** Quantity adjusted successfully.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Invalid request.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: MissingParameter_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "MissingParameter",
      "message": "The field 'quantity' is missing from the request body."
    }
    ```
    
*   **403** Organization not authorized.
    
    Media type: `application/problem+json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: TenantNotProvisioned_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "TenantNotProvisioned",
      "message": "The client is not correctly configured to access the system."
    }
    ```
    
*   **409** Reservation ID invalid.
    
    Headers:
    
    *   `X-RateLimit-Limit` (string) The maximum number of requests permitted per minute.
    *   `X-RateLimit-Remaining` (string) The number of requests remaining in the current rate limit window.
    *   `X-RateLimit-Reset` (string) The time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `InventoryResponseErrorSchema`.
    
    _Example: IDDoesNotExist_
    
    ```
    {
      "type": "about:blank",
      "errorCode": "InvalidRequestParameter",
      "message": "ID does not exist."
    }
    ```
    
*   **429** The user has sent too many requests in a given amount of time ("rate limiting")
    
    Headers:
    
    *   `Retry-After` (string)
    
    Media type: `application/problem+json`. Schema: `object`.
    
    *   `title` (_string_) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization.  
        Example: `You do not have enough credit.`.
    *   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `https://example.com/probs/out-of-credit`.
    *   `detail` (_string_) A human-readable explanation specific to this occurrence of the problem.  
        Example: `Your current balance is 30, but that costs 50.`.
    *   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
        Example: `/account/12345/msgs/abc`.
    
    _Example_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-requests",
      "title": "Too Many Requests",
      "detail": "You have performed too many requests in a short period of time."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the organization the request is being made by

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.

### PlaceReservationRequest

Reservation Request

Place a reservation Request

*   `externalRefId` (_ExternalRefId_)
*   `expirationSeconds` (_ExpirationSeconds_)
*   `allowPartialReservations` (_AllowPartialReservations_)
*   `fulfillOnly` (_FulfillOnlyReservations_)
*   `reservationTime` (_ReservationTime_)
*   `groups` (_array of ReservationRequestGroup_) The reservations to request at the specified location groups.
*   `locations` (_array of ReservationRequestLocation_) The reservations to request at the specified locations.

### PlaceReservationResponseBody

The response for a successful reservation placement.

*   `reservationTime` (_string (date-time)_, required)  
    Maximum length: 30. Example: `2019-07-24T21:13:00Z`.
*   `expirationTime` (_ExpirationTime_)
*   `success` (_boolean_, required) Whether or not the reservation was able to be placed successfully.  
    Example: `true`.
*   `groups` (_array of object_) The results for the requested location group reservations.
    *   `id` (_GroupId_, required)
    *   `errors` (_array of ReservationResponseErrorRecord2_)
    *   `details` (_array of ReservedReservationRecord_) Information about the SKU, and the amount of quantity that was successfully reserved.
*   `locations` (_array of object_) The results for the requested location reservations.
    *   `id` (_LocationId_, required)
    *   `errors` (_array of ReservationResponseErrorRecord2_)
    *   `details` (_array of ReservedReservationRecord_) Information about the SKU, and the amount of quantity that was successfully reserved.

### InvalidRequestLocOrGroupDoesNotExist

*   `errorCode` (_InvalidRequestLocOrGroupDoesNotExistEnum_, required)
*   `message` (_string_, required)  
    Maximum length: 250. Example: `An invalid group was provided.`.
*   `type` (_string_, required)  
    Maximum length: 250. Example: `about:blank`.
*   `parameterName` (_string_) When invalid json is passed to the service, this field will indicate which piece of the supplied json was invalid.  
    Maximum length: 250. Example: `sku`.
*   `group` (_string_) Indicates which group was provided that does not exist  
    Maximum length: 250. Example: `UnitedStates`.
*   `location` (_string_) Indicates the location that was provided that does not exist  
    Maximum length: 250. Example: `warehouse5`.

### InventoryResponseErrorSchema

*   `errorCode` (_string_, required)  
    Maximum length: 32. Example: `InvalidRequestParameter`.
*   `message` (_string_, required)  
    Maximum length: 250. Example: `An invalid request parameter was provided.`.
*   `type` (_string_, required)  
    Maximum length: 250. Example: `about:blank`.
*   `parameterName` (_string_) When invalid json is passed to the service, this field will indicate which piece of the supplied json was invalid.  
    Maximum length: 250. Example: `location`.

### ReservationInvalidState

Error generated when attempting to create a reservation with the same ID as an existing one.

Maximum length: 1.

*   `errorCode` (_string_, required)  
    Allowed values: `ReservationInvalidState`, `ReservationAlreadyFinalized`, `ReservationCancelled`, `ReservationOperationInProcess`, `EntityExists`, `ConcurrentModification`, `PreviousRequestAborted`, `PreviousRequestCancelled`. Maximum length: 32. Example: `ReservationInvalidState`.
*   `message` (_string_, required)  
    Maximum length: 250. Example: `Reservation is in a CLOSED state.`.
*   `type` (_string_, required)  
    Maximum length: 250. Example: `about:blank`.
*   `parameterName` (_string_) When invalid json is passed to the service, this field will indicate which piece of the supplied json was invalid.  
    Maximum length: 250. Example: `sku`.

_Example_

```
{
  "errorCode": "ReservationInvalidState",
  "message": "Reservation is in a CLOSED state.",
  "type": "about:blank",
  "parameterName": "sku"
}
```

### UpdateReservationRequestBody

The body that is sent requesting a reservation be cancelled.

*   `status` (_string_) The status to set on the reservation document  
    Allowed values: `CANCELLED`. Example: `CANCELLED`.
*   `externalRefId` (_ExternalRefId_)
*   `allowPartialReservations` (_boolean_) Whether or not to allow partial reservations. The default value is 'true'. If the value sent in is 'true', or no value is sent, the response will only include the quantity that was available to be reserved. There will be no error message. In this case, the response must be verified by the caller.  
    Example: `true`.
*   `reservationTime` (_ReservationTime_)
*   `id` (_IdempotenceId_)
*   `locations` (_UpdateReservationLocationType_)
*   `groups` (_UpdateReservationGroupType_)

### UpdateReservationResponse

*   `reservationTime` (_ReservationTime_)
*   `expirationTime` (_ExpirationTime_)
*   `success` (_boolean_)  
    Example: `false`.
*   `groups` (_array of object_)
    *   `id` (_GroupId_)
    *   `errors` (_GenericErrorsArray_)
    *   `details` (_array of object_)
        *   `sku` (_SkuId_)
        *   `quantity` (_number (float)_)  
            Example: `8`.
        *   `adjustment` (_number (float)_)  
            Example: `4`.
*   `locations` (_array of object_)
    *   `id` (_LocationId_)
    *   `errors` (_GenericErrorsArray_)
    *   `details` (_array of object_)
        *   `sku` (_SkuId_)
        *   `quantity` (_number (float)_)  
            Example: `8`.
        *   `adjustment` (_number (float)_)  
            Example: `4`.

### MoveReservationBatchPostBody

Move Reservations Batch Call

*   `allOrNothingTransferId` (_AllOrNothingId_, required)
*   `records` (_array of MoveReservationBodyRecords_, required) List of records to process in a batch update. The maximum number of entries in the array is 100.

### MoveReservationErrorsResponse

moveReservationsErrorResponse

*   `errors` (_array of MoveReservationError_, required) Errors generated during transfer/move reservation

_Example_

```
{
  "errors": [
    {
      "details": {
        "id": "82251928-8863-488e-840b-2aebd10b57ba",
        "externalRefId": "7282822-9823-aaa",
        "from": {
          "group": "UnitedStates"
        },
        "to": {
          "location": "warehouse5"
        },
        "sku": "sku-002",
        "quantity": 2.011
      },
      "message": "Insufficient Quantity",
      "errorCode": "InsufficientQuantity"
    }
  ]
}
```

### UnreserveRequestBody

Request Body By Location Only

*   `records` (_array of object_, required)
    *   `id` (_IdempotenceId_, required)
    *   `externalRefId` (_ExternalRefId_)
    *   `location` (_LocationId_)
    *   `group` (_GroupId_)
    *   `sku` (_SkuId_, required)
    *   `quantity` (_QuantityOnHand_, required)

### UnreserveResponseBody

Unreserve Response Body

*   `errors` (_array of object_, required)
    
    _Example_
    
    ```
    [
      {
        "details": {
          "id": "82251928-8863-488e-840b-2aebd10b6666",
          "externalRefId": "7282822-9823-bbb",
          "group": "UnitedStates",
          "sku": "sku5678",
          "quantity": 0
        },
        "message": "Insufficient Quantity",
        "errorCode": "InsufficientQuantity"
      }
    ]
    ```
    
    *   `details` (_UnreservedDetail_, required)
    *   `errorCode` (_ErrorCode_)
    *   `message` (_Message_)

### FulfillQuantityRequestBody

Fulfills the given quantity of reservations for a SKU at a given location. The given quantity will be subtracted from the reservation count and the quantity on hand, in an atomic operation.

*   `records` (_array of object_, required) List of records to process in a batch update. The maximum number of entries in the array is 100.
    
    Each item: The records provided in a fulfillment request.
    
    *   `id` (_IdempotenceId_, required)
    *   `externalRefId` (_ExternalRefId_)
    *   `location` (_LocationId_, required)
    *   `sku` (_SkuId_, required)
    *   `quantity` (_QuantityOnHand_, required)
    *   `fulfillmentTime` (_FulfillmentTime_)

_Example_

```
{
  "records": [
    {
      "id": "82251928-8863-488e-840b-2aebd10b57ba",
      "externalRefId": "7282822-9823-aaa",
      "location": "warehouse5",
      "sku": "sku1234",
      "quantity": 1200.35,
      "fulfillmentTime": "2019-07-24T21:13:00Z"
    },
    {
      "id": "82251928-8863-488e-840b-2aeb567d3a87",
      "externalRefId": "7282822-9823-ddd",
      "location": "warehouse4",
      "sku": "sku5678",
      "quantity": 201.27
    }
  ]
}
```

### FulfillQuantityResponseErrors

*   `errors` (_array of object_, required)
    
    Each item: Error message generated after a failed fulfillment.
    
    *   `details` (_object_, required) Reservation fulfillment error detail information
        *   `id` (_IdempotenceId_, required)
        *   `externalRefId` (_ExternalRefId_)
        *   `location` (_LocationId_, required)
        *   `sku` (_SkuId_, required)
        *   `quantity` (_QuantityOnHand_, required)
    *   `message` (_string_, required) Error message  
        Maximum length: 128. Example: `Fulfillment failed - invalid location provided`.
    *   `errorCode` (_ErrorCode_, required)

_Example_

```
{
  "errors": [
    {
      "details": {
        "id": "82251928-8863-488e-840b-2aebd10b57ba",
        "externalRefId": "7282822-9823-aaa",
        "location": "warehouse5",
        "sku": "sku1234",
        "quantity": 1200.35
      },
      "message": "Failed to fulfill, invalid location provided.",
      "errorCode": "err751"
    }
  ]
}
```

### ExternalRefId

A convenience identifier for the consumer, used for auditing events. This field is NOT used by the service itself, but is intended for the consumer to be able to identify records submitted from their systems that are external to OCI.

Type: `string`.

Maximum length: 128. Pattern: ^\[a-zA-Z0-9\\-\]\*$. Example: `7282822-9823-aaa`.

### ExpirationSeconds

The number of seconds until this reservation expires. If not specified, this reservation never expires.

Typically, there's about a 10-15 second delay between the specified expiration time and its reflection on inventory counts under normal load, but usually stays within 60 seconds under higher loads.

Type: `integer`.

Minimum: 1. Maximum: 14400. Example: `300`.

### AllowPartialReservations

Whether or not to allow partial reservations. The default value is 'true'. If the value sent in is 'true', or no value is sent, the response will only include the quantity that was available to be reserved. There will be no error message. In this case, the response must be verified by the caller.

Type: `boolean`.

Example: `true`.

### FulfillOnlyReservations

Whether or not to fulfill a reservation ONLY against the ATF amount. The default value is 'false'. If the value sent in is 'false', or no value is sent, the reservations will apply normally. If the value is sent as 'true', the reservation will ONLY be placed against the ATF amount and will fail if this amount is insufficient to fulfill the reservation request.

Type: `boolean`.

Example: `true`.

### ReservationTime

The time the reservation was placed

Type: `string (date-time)`.

Maximum length: 30. Example: `2019-07-24T21:13:00Z`.

### ReservationRequestGroup

The reservations to request at the location group.

*   `id` (_GroupId_, required)
*   `reservations` (_array of ReservationRequestRecord_, required)

### ReservationRequestLocation

The reservations to request at the location.

*   `id` (_LocationId_, required)
*   `reservations` (_array of ReservationRequestRecord_, required)
*   `allOrNothingReservations` (_array of object_)
    *   `id` (_AllOrNothingId_, required)
    *   `reservations` (_array of ReservationRequestRecord_, required)

### ExpirationTime

The time the reservation expires

Type: `string (date-time)`.

Maximum length: 30. Example: `2019-07-24T21:13:00Z`.

### GroupId

An identifier for a collection of locations

Type: `string`.

Minimum length: 2. Maximum length: 128. Pattern: ^\[a-zA-Z0-9-\_\]\*$. Example: `UnitedStates`.

### ReservationResponseErrorRecord2

Information about any errors that occurred attempting to place the reservation.

Maximum length: 250.

*   `sku` (_SkuId_, required)
*   `errorCode` (_ErrorCode_, required)

_Example_

```
{
  "sku": "sku5678",
  "errorCode": "Unknown"
}
```

### ReservedReservationRecord

*   `sku` (_SkuId_, required)
*   `quantity` (_ReservedQuantity_, required)

### LocationId

The id of the location of the inventory.

Type: `string`.

Minimum length: 2. Maximum length: 128. Pattern: ^\[a-zA-Z0-9-\_\]\*$. Example: `warehouse5`.

### InvalidRequestLocOrGroupDoesNotExistEnum

Type: `string`.

Allowed values: `InvalidRequest`, `LocationDoesNotExist`, `GroupDoesNotExist`. Example: `LocationDoesNotExist`.

### IdempotenceId

A unique identifier, used in combination with the SKU, so that future requests with the same combination have the same result.

Type: `string`.

Maximum length: 128. Pattern: ^\[a-zA-Z0-9\\-\]\*$. Example: `82251928-8863-488e-840b-2aebd10b57ba`.

### UpdateReservationLocationType

The reservations to request at the specified locations.

Array of `object`.

*   `id` (_LocationId_, required)
*   `reservations` (_Reservations_, required)
*   `allOrNothingReservations` (_object_, required)
    *   `id` (_string_, required) The user defined ID of the all or nothing reservation  
        Maximum length: 32. Example: `a14s-4b1c-1a3cbd4`.
    *   `reservations` (_Reservations_, required)

### UpdateReservationGroupType

The reservations to request at the specified location groups.

Array of `object`.

*   `id` (_GroupId_, required)
*   `reservations` (_Reservations_, required)
*   `allOrNothingReservations` (_object_, required)
    *   `id` (_string_, required) The user defined ID of the all or nothing reservation  
        Maximum length: 32. Example: `a14s-4b1c-1a3cbd4`.
    *   `reservations` (_Reservations_, required)

### GenericErrorsArray

Array of `object`.

*   `sku` (_SkuId_)
*   `errorCode` (_string_)  
    Maximum length: 32. Example: `InsufficientQuantity`.

### SkuId

The inventory identifier

Type: `string`.

Minimum length: 1. Maximum length: 250. Pattern: ^\[^\\\\<>;%/\\s\]\*$. Example: `sku1234`.

### AllOrNothingId

The used defined id of the All Or Nothing Reservation.

Type: `string`.

Minimum length: 1. Maximum length: 128. Pattern: ^\[a-zA-Z0-9-\_\]\*$. Example: `a14s-4b1c-1a3cbd4`.

### MoveReservationBodyRecords

Location To Location Move Reservation Records

*   `id` (_IdempotenceId_, required)
*   `externalRefId` (_ExternalRefId_)
*   `from` (_MoveReservationFromLocation | MoveReservationFromGroup_, required) The place from which the reservation quantity is being moved.
    
    One of: `MoveReservationFromLocation`, `MoveReservationFromGroup`.
    
*   `to` (_MoveReservationToLocation | MoveReservationToGroup_, required) The place where the reservation quantity is being moved to.
    
    One of: `MoveReservationToLocation`, `MoveReservationToGroup`.
    
*   `sku` (_SkuId_, required)
*   `quantity` (_number (double)_, required)  
    Minimum: 0.001. Multiple of: 0.001. Example: `2.011`.
*   `ignoreAvailabilityCheck` (_boolean_) It specifies if the reservation should be moved even if there is no inventory at the destination.  
    Default: `false`. Example: `false`.

### MoveReservationError

*   `details` (_MoveReservationErrorDetail_, required)
*   `message` (_Message_, required)
*   `errorCode` (_ErrorCode_, required)

### QuantityOnHand

Quantity on hand.

Type: `number (double)`.

Minimum: 0. Multiple of: 0.001. Example: `1200.35`.

### UnreservedDetail

*   `id` (_IdempotenceId_, required)
*   `externalRefId` (_ExternalRefId_, required)
*   `location` (_LocationId_)
*   `group` (_GroupId_)
*   `sku` (_SkuId_, required)
*   `quantity` (_number_, required)  
    Example: `0`.

### ErrorCode

The error code

Type: `string`.

Allowed values: `InsufficientQuantity`, `Unknown`. Maximum length: 128. Pattern: ^\[a-zA-Z0-9\\-\]\*$. Example: `MoveError`.

### Message

The error message

Type: `string`.

Maximum length: 128. Pattern: ^\[a-zA-Z0-9\\- \]\*$. Example: `MoveError`.

### FulfillmentTime

The time the fulfillment takes place

Type: `string (date-time)`.

Maximum length: 30. Example: `2019-07-24T21:13:00Z`.

### ReservationRequestRecord

Information about the SKU, and quantity to reserve.

*   `sku` (_SkuId_, required)
*   `quantity` (_ReservedQuantity_, required)

### ReservedQuantity

The quantity to reserve

Type: `number (double)`.

Minimum: 0.001. Multiple of: 0.001. Example: `10`.

### Reservations

Array of `object`.

*   `sku` (_SkuId_, required)
*   `quantity` (_ReservedQuantity_, required)

### MoveReservationFromLocation

*   `location` (_LocationId_, required)

### MoveReservationFromGroup

*   `group` (_GroupId_, required)

### MoveReservationToLocation

*   `location` (_LocationId_, required)

### MoveReservationToGroup

*   `group` (_GroupId_, required)

### MoveReservationErrorDetail

*   `id` (_IdempotenceId_, required)
*   `externalRefId` (_ExternalRefId_, required)
*   `from` (_MoveReservationFromGroup | MoveReservationFromLocation_, required)
    
    One of: `MoveReservationFromGroup`, `MoveReservationFromLocation`.
    
*   `to` (_MoveReservationToGroup | MoveReservationToLocation_, required)
    
    One of: `MoveReservationToGroup`, `MoveReservationToLocation`.
    
*   `sku` (_SkuId_, required)
*   `quantity` (_number (double)_, required)  
    Minimum: 0.001. Multiple of: 0.001. Example: `2.011`.

<!-- document id=a35ed74b12b81a9f043770aaee045e279c1a14bb552d37d28143c0facfa94089 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/inventory-service-spi.md -->

Inventory Service SPI

# Inventory Service SPI

[Download API specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-service-spi/inventory-service-spi-oas-public.yaml)

Implement this endpoint per the specification and configure it in CMS under:

**CMS > Store Management > Integration > Custom SPI Connectors > Create**

Ensure the endpoint is created in CMS with the following details:

#### 

1.  SPI Config

*   **SPI Key:** INVENTORY\_SERVICE
    
*   **SPI Endpoint:** Enter the **base SPI URL** in CMS.
    
*   The SPI supports multiple operations by appending specific **verbs** to the base URL.
    

**Example:**

*   **Base SPI URL (Configured in CMS):**  
    [https://your-base-url.com/inventoryService](https://your-base-url.com/inventoryService)
    
*   **Full SPI Endpoints (Handled by Merchant's System):**
    
    *   **Revert Reserved Inventory:** [https://your-base-url.com/inventoryService/revert](https://your-base-url.com/inventoryService/revert)
        

**Merchants must handle the full SPI URL (base + verb) in their system.**

#### 

2.  JSON Config

*   **Integration Type:** Not required
    
*   **JSON Headers:** Provide the necessary authentication headers.
    

**Example:**

{  
 "Content-Type": "application/json",  
 "client\_id": "yourClientId",  
 "client\_secret": "yourClientSecret"  
}

**Version:** 2.3.3

## Tags

### Inventory service SPI

[Download API specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-service-spi/inventory-service-spi-oas-public.yaml)

Implement this endpoint per the specification and configure it in CMS under:

**CMS > Store Management > Integration > Custom SPI Connectors > Create**

Ensure the endpoint is created in CMS with the following details:

#### 

1.  SPI Config

*   **SPI Key:** INVENTORY\_SERVICE
    
*   **SPI Endpoint:** Enter the **base SPI URL** in CMS.
    
*   The SPI supports multiple operations by appending specific **verbs** to the base URL.
    

**Example:**

*   **Base SPI URL (Configured in CMS):**  
    [https://your-base-url.com/inventoryService](https://your-base-url.com/inventoryService)
    
*   **Full SPI Endpoints (Handled by Merchant's System):**
    
    *   **Revert Reserved Inventory:** [https://your-base-url.com/inventoryService/revert](https://your-base-url.com/inventoryService/revert)
        

**Merchants must handle the full SPI URL (base + verb) in their system.**

#### 

2.  JSON Config

*   **Integration Type:** Not required
    
*   **JSON Headers:** Provide the necessary authentication headers.
    

**Example:**

{  
 "Content-Type": "application/json",  
 "client\_id": "yourClientId",  
 "client\_secret": "yourClientSecret"  
}

## Operations

### POST Revert reserved inventory.

`POST /merchant/spi/sample/endpoint/sa/inventoryService/revert`

Operation ID: `revertInventory`. Tags: Inventory service SPI.

Reverts reserved inventory for specified products in a cart. - Used when payment fails or checkout doesn't complete to release reserved inventory. **Structure:** - **Base SPI Endpoint:** /merchant/spi/sample/endpoint/sa/inventoryService (Configured in CMS) - **Verb:** /revert (Handled by the merchant's system when making SPI calls) - **Full Endpoint:** /merchant/spi/sample/endpoint/sa/inventoryService/revert

#### Request body

Media type: `application/json`. Schema: `ExternalCart`.

#### Responses

*   **default** Default response
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### ExternalCart

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `cartItemList` (_array of ExternalProduct_, required) All the items from the cart. Each item has a link to its delivery group via deliveryGroupId.
*   `deliveryGroupList` (_array of ExternalDeliveryGroup_) All delivery groups corresponding to the delivery items from the cart.
*   `billingAddress` (_ExternalAddress_)
*   `profile` (_ExternalCustomerProfile_)
*   `pickUpDetailList` (_array of ExternalPickUpDetail_, nullable) Pickup details

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### ExternalProduct

Products

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item
*   `price` (_number_, required) Price of the item
*   `quantity` (_integer (int32)_, required) Item's Quantity
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc..Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc..  
    Mandatory if any type of price adjustments is applied
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes
*   `externalId` (_string_, nullable) External ID of the product  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.

### ExternalDeliveryGroup

In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.

*   `deliveryGroupId` (_string_, required) Delivery group ID
*   `fulfillmentType` (_string_, required) Fulfillment type  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup, i.e., buy online ship to store |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_ExternalAddress_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `fulfillmentAddress` (_ExternalAddress_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification  
    Maximum length: 128.

### ExternalAddress

Billing address

*   `salutation` (_string_, nullable) Salutation
*   `firstName` (_string_, required, nullable) Customer first name saved for address  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address  
    Maximum length: 64.
*   `addressLine1` (_string_, required, nullable) Address Line 1  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2  
    Maximum length: 256.
*   `city` (_string_, required, nullable) City  
    Maximum length: 64.
*   `state` (_string_, required, nullable) State  
    Maximum length: 32.
*   `postalCode` (_string_, required, nullable) Postal Code  
    Maximum length: 16.
*   `countryCode` (_string_, required, nullable) Country Code  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address
*   `addressType` (_string_, nullable) Address type- Home, Business
*   `emailAddress` (_string_, nullable) Customer Email Address  
    Maximum length: 64.
*   `country` (_string_, nullable) Country

### ExternalCustomerProfile

Customer profile. It is mandatory for customer logged-in during the transaction. It is optional for guest customer.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.  
    Maximum length: 128.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID  
    Maximum length: 128.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix
*   `phoneHome` (_string_, nullable) Phone Home
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business
*   `fax` (_string_, nullable) Fax
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer

### ExternalPickUpDetail

Pickup details

*   `pickupDetailId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `email` (_string_)
*   `phone` (_string_)

### ExternalStoreAssociateAttribution

Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.

*   `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction
*   `contributionPercentage` (_number_, required) Associate's contribution towards sales
*   `attributionNote` (_string_) Note related to attribution
*   `firstName` (_string_, required) Associate's first name
*   `lastName` (_string_, required) Associate's last name

### Reason

Reason for returning the item

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text  
    Maximum length: 256.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request

### ProductFormAttribute

Details about a product form attribute

*   `key` (_string_) The identifier of the attribute  
    Example: `color`.
*   `value` (_string_) The value associated with the key  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### ExternalProductTax

Tax/Vat details

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount

### ExternalPriceAdjustment

Price adjustments applied on the item.  
It includes all the price adjustments like transaction discount, price override etc..  
Mandatory if any type of price adjustments is applied

*   `description` (_string_, required) Price adjustment description
*   `adjustment` (_string_, required) Price adjustment
*   `id` (_string_) Promotion Id for applied coupon or auto promotion
*   `price` (_number_, required) Price adjustment amount
*   `priceAdjustmentType` (_string_, required) Price adjustment type  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reason` (_Reason_)
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied.  
    Not applicable for auto promotions,  
    manual price adjustments like price override & transaction discount
*   `auto` (_boolean_, nullable) Applied promotion is auto or not
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system.  
    If an order is placed directly in the POS, this identifier will not be available.  
    The external system provides this identifier, which will then be replayed to that  
    external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.

### ExternalNote

Notes for the transaction

*   `cartId` (_string_)
*   `noteId` (_string_)
*   `noteText` (_string_)
*   `transactionId` (_string_)

### ShippingMethod

Available shipping methods corresponding to this delivery group

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount
*   `sortOrder` (_integer (int32)_) Display Order  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text
*   `jurisdiction` (_string_, nullable) Jurisdiction  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

<!-- document id=bfd37645886c08b5a9093e049cf2376291c24fa5cd7af76086c0341411c887e2 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/inventory-spi.md -->

Inventory SPI

# Inventory SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-spi/inventory-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get inventory for the provided products. These endpoints must be configured in the POS system so that the POS can use them to check inventory availability.

**Version:** 2.3.4

## Tags

### Inventory SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-spi/inventory-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get inventory for the provided products. These endpoints must be configured in the POS system so that the POS can use them to check inventory availability.

## Operations

### POST Check inventory availability for zip code.

`POST /merchant/spi/sample/endpoint/product/zipcode/getAvailabilityInformation`

Operation ID: `checkInventoryAvailability`. Tags: Inventory SPI.

Check the external system for the availability of a given product against the provided zip code. The response is a single string, the availability text, and any other information related to the product. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `INVENTORY_BY_ZIPCODE`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/product/zipcode/getAvailabilityInformation](https://sample/external/endpoint/product/zipcode/getAvailabilityInformation)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `InventoryAvailabilityRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiInventoryAvailabilityResponse`.
    

### POST Check inventory overview for all stores and warehouses.

`POST /merchant/spi/sample/endpoint/product/getInventoryOverview`

Operation ID: `checkInventoryOverview`. Tags: Inventory SPI.

Check the external system for the availability of a given product. The response is shown on the existing inventory overview widget, showing availability for all stores. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `GET_PRODUCT_INVENTORY_OVERVIEW`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/inventory/from/external/system](https://sample/external/endpoint/to/get/inventory/from/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `InventoryOverviewRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiInventoryOverviewResponse`.
    

### POST Inventory SPI to Check Inventory count

`POST /merchant/spi/sample/endpoint/sa/inventory/to/check/inventory/from/external/system`

Operation ID: `checkInventory`. Tags: Inventory SPI.

The API is to check the external system for the availability of given products by checking their inventory count. Merchant API to receive the Product ID, the type of inventory check to be done (ONLINE or IN\_STORE), optionally Store ID, and the purpose of inventory check (AVAILABILITY).

#### Request body

Media type: `application/json`. Schema: `CheckInventoryRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiInventoryResponse`.
    

## Schemas

### InventoryAvailabilityRequest

*   `zipCode` (_string_, required) The zip code or postal code for which to check product availability.
*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `gtin` (_string_, nullable) Item's GTIN , alternate field to check inventory (Mainly used by SPI).
*   `variantGroupId` (_string_, nullable) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `storeId` (_string_, nullable) Store ID of the current store.

### SpiInventoryAvailabilityResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `availabilityText` (_string_, required) Generic text field that contains information about inventory availability of the product.
*   `error` (_boolean_)

### InventoryOverviewRequest

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `storeId` (_string_, required) Store ID of the current store.
*   `gtin` (_string_, nullable) Item's GTIN, alternate field to check inventory (mainly used by SPI).
*   `variantGroupId` (_string_, nullable) Variant Group ID. All the variants of an item are grouped together under the same variant ID.

### SpiInventoryOverviewResponse

Response object that returns the full inventory overview for all stores.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `storeInventoryDetails` (_array of StoreInventoryDetails_, required) List of all stores and their inventory details for the product sent in the request.
*   `error` (_boolean_)

### CheckInventoryRequest

*   `products` (_array of InventoryProduct_, required) The list of Products for which the Inventory is to be checked.

### SpiInventoryResponse

*   `errorMessage` (_string_, nullable) Placeholder string for any error that occurs when checking inventory.
*   `inventory` (_array of ProductInventory_)

### StoreInventoryDetails

List of all stores and their inventory details for the product sent in the request.

*   `storeId` (_string_, required) Store or warehouse ID.
*   `storeName` (_string_, required) Store name.
*   `storeAddress` (_SpiStoreAddress_, required)
*   `inventory` (_SpiInventory_, required)

### InventoryProduct

The list of Products for which the Inventory is to be checked.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `inventoryType` (_string_, required) Item's inventory check type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).
*   `inventoryAction` (_string_, required) The action to be taken for this inventory check. Current valid values: AVAILABILITY.
*   `storeId` (_string_, required) Check inventory based on given store ID. Will always be sent in the request.

### ProductInventory

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `quantity` (_integer (int32)_, required) The available inventory quantity of the product, 0 when there is no inventory.
*   `storeId` (_string_, nullable) Available inventory based on given store ID. Optional, to be returned when inventoryType is IN\_STORE.
*   `inventoryType` (_string_, required) Item's inventory check type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).

### SpiStoreAddress

The store address.

*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.

### SpiInventory

Inventory details of the product at this store.

*   `availableQuantity` (_integer (int32)_, required) Product quantity available in stock for sale.
*   `quantityOnHand` (_integer (int32)_, required) Product quantity on hand.
*   `allocatedQuantity` (_integer (int32)_, required) Product quantity allocated for shipment or BOPIS orders.
*   `quantityInTransit` (_integer (int32)_, required) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_, required) Product quantity on order for this store.

<!-- document id=70fc5b3227603bdc2cf804e3b3f49f48ef12d069d6a4d2ffdbaf36f49ddf174f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isactivedatacontext.md -->

# isactivedatacontext Element

Use to collect category context from a page for active data.

## Syntax

```
<isactivedatacontext
  category = current_category //required
/>
```

- category

  - : _Allowed data type:_ expression.

    `current_category` specifies the current category of the page being viewed by the customer. An expression that retrieves the current category from the pipeline dictionary is used.

## Purpose

This tag is used to specify the deepest (most specific) category being browsed on the page. If the tag appears multiple times in the same page, due to includes or other reasons, the category provided in the latest tag that appears in the HTML is the one that is counted.

The `<isactivedatacontext/>` tag must be placed somewhere within the `<head>` or `<body>` tags of each site page where `<script>` tags are valid.

It's best practice for this tag to be included in exactly one template used to make up each HTML page. If this tag appears in multiple templates used to make up a single HTML page, the latest template takes precedence. For example, if one tag indicates the "electronics" category, and a later tag indicates the "video" category, the "video" category takes precedence. There is no negative effect if the tag appears in multiple templates with the same category value for the same HTML page, but it's redundant. If this tag doesn't appear in any templates that are used to make up an HTML page, no category context is associated with the page.

## Example

In this example, the category context collected for the product being viewed is taken from the primary category of the product search result. See the `productsearchbreadcrumbs.isml` template in the SiteGenesis Storefront cartridge to see this example.

```
<isactivedatacontext category="${pdict.ProductSearchResult.category}" />
```

<!-- document id=1d10eb57711d4339e634c0948f8b10e4a920fb6925a92eead19b70a4129a7502 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isactivedatahead.md -->

# isactivedatahead Element

Use to configure pages to allow collection of active data from ISML templates that contain an HTML `<head>` tag.

## Syntax

```
<isactivedatahead/>
```

## Purpose

ISML templates without an HTML `<head>` tag don't use the `<isactivedatahead>` tag. Salesforce recommends that you place the tag immediately before the closing head tag `</head>.`

However, you can choose a different location based on the general tag requirements. The tag must appear:

- Before any other analytics data collection ISML tags
- After all references to external JavaScript libraries.
- In a location where \<script> tags are valid.

If this tag appears after any other analytics data collection ISML tags, those tags might fail to collect data. If this tag appears before any references to external JavaScript libraries, those external JavaScript libraries might become incompatible. The tag must appear where `<script>` tags are valid. For example, it can't be placed between two `<tr>` tags for rows of a table or similar structures in a page where a `<script>` tag isn't valid.

If the tag isn't placed in a page or isn't placed in a page correctly, the storefront customer might experience JavaScript errors. Users can be notified of the error or page rendering might be negatively affected.

As a best practice the `<isactivedatahead/>` tag should be placed in all `<head>` tags, unless the template containing the `<head>` tag is used solely for a page or set of pages that is guaranteed to never have data of analytic interest.

## Example

For an example of how to use `<isactivedatahead>,` see the htmlhead_UI.isml template in the SiteGenesis application.

<!-- document id=d44a4a383d3b1b7aeaa53277dd33c4ed4395e684898ef698470c17b83cb0d1fa url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isanalyticsoff.md -->

# isanalyticsoff Element

Each HTML page served by B2C Commerce includes a JavaScript snippet for analytics and active merchandising tracking purposes. If you must disable this tracking because it causes problems with your site, do so for the entire site by entering a Customer Support ticket, or include the `<isanalyticsoff/>` element at the end of one or more templates to disable analytics at the page level.

## Syntax

```
<isanalyticsoff/>
```

## Purpose

**important:** Use this element only for single pages and only for an emergency situation. Although the element is part of the API, it can prevent the correct tracking of analytics and active merchandising data.

## Example

This is an example of a JavaScript snippet added to the end of a template to collect B2C Commerce analytics:

```javascript
<!-- B2C Commerce Analytics code 1.0 -->
<script type="text/javascript"
 src="/on/demandware.static/Sites-BV-Site/-/default/v1315220487813/internal/jscript/dwanalytics.js">
</script>
<script type="text/javascript">
//
<!-- /* <![CDATA[ */
 try{ var trackingUrl = "http://us.dv.dev1.our.customer.bestcustomer.it/on/demandware.store/Sites-BV-Site/default/__Analytics-Tracking";
 var dwAnalytics = dw.__dwAnalytics.getTracker(trackingUrl);
 if (typeof dw.ac == "undefined") { dwAnalytics.trackPageView();
 } else { dw.ac.setDWAnalytics(dwAnalytics);
 } }catch(err) {}; /* ]]> */ // --> </script>
 <isanalyticsoff/>
```

In this case, the tracking code is considered a cross-site scripting threat if you use an HTTPS iframe and generate this iframe via ISML. Add the `<isanalyticsoff/>` element at the end of one or more templates to disable B2C Commerce analytics at the page level, thereby preventing the threat.

<!-- document id=def30d02310d25bb1d96f222ab619b73b8b1160a57a60d58cc5e5ea206c1f8f3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isapplepay.md -->

# isapplepay Element

Use to inject a default black Apple Pay button in the HTML page.

## Syntax

```
<isapplepay
  sku = "${pdict.Product.ID}" | sku //required
  class = "dw-apple-pay-logo-black" | "dw-apple-pay-logo-white dw-apple-pay-border" // required
  id = "apple-pay-button" | "$('add-' + pdict.Product.ID + 'to-cart'}"
/>
```

- sku

  - : _Allowed data type:_ literal or expression.

    `${pdict.Product.ID}` specifies the button adds the Product with the given sku to the basket. Make sure that the Product is of a type that can be added to the basket.

- class

  - : Allowed data type: literal.

    `class` specifies the look of the button, among possible choices. Root DOM element for the button has at least the given CSS classes.

    The following CSS class names are supported for use with Apple Pay on a Salesforce B2C Commerce page when the feature is enabled:

    - `dw-apple-pay-button` added to each Apple Pay button included in the page generated by B2C Commerce. The default look is a black button with the Apple Pay logo and branding provided by Apple.
    - `dw-apple-pay-mini-cart` added to the Apple Pay button injected in the mini cart.
    - `dw-apple-pay-cart` added to the Apple Pay button injected in the cart page.
    - `dw-apple-pay-logo-white` can be used to indicate the alternate look, which is a white button with the Apple Pay logo and branding provided by Apple.
    - dw-apple-pay-border can be used with `dw-apple-pay-logo-white` to add a black border around the white button.

- id

  - : Allowed data type: literal or expression.

    Root DOM element for the button has the given ID attribute.

## Example

```
<isapplepay
  sku = "12345"
  class = "dw-apple-pay-logo-black"
  id = "apple-pay-button"
><isapplepay/>
```

<!-- document id=6efc8965fc6aa0980e1b8c2bbd71db6279201a90419a739019b82dca885513e1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isbreak.md -->

# isbreak Element

Terminate loops unconditionally.

## Syntax

```
<isbreak/>
```

## Purpose

`<isbreak>` can be used within a loop (defined by an `<isloop>` tag) to terminate a loop unconditionally. For more information on creating loops see \<[isloop](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-isloop.md)>. If `<isbreak>` is used in a nested loop, it terminates only the inner loop.

## Example

In this example, `<isbreak/>` terminates the loop after showing three product names; even if the products iterator contains more than three products.

```
<isset name="counter" value="${0}">
<isloop iterator="${pdict.Basket.product}" var="product" status="status">
  <isprint value="${product.name}"> <BR>
  <isif condition="${status.counter >= 3}">
    <isbreak/>
  </isif>
</isloop>
```

<!-- document id=2b78190b88a0198c88ff5d3f758a9cfe99faee6c0f9ed26f21fc09afd89812d6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isbuynow.md -->

# isbuynow Element

Inject code to render express checkout buttons that lets a shopper buy a specific product.

To render express checkout buttons for a shopper to pay for their current basket, see [\<ispayment>](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-ispayment.md).

`<isbuynow>` is only used with B2C Commerce Payments. An associated payments account must be successfully enabled and configured for use on the storefront site where this element appears.

## Syntax

```
<isbuynow
  payment-request = SalesforcePaymentRequest expression \\required
></isbuynow>
```

- payment-request = SalesforcePaymentRequest expression

  - : Specify a `dw.extensions.payments.SalesforcePaymentRequest` as part of an expression for the tag. See [SalesforcePaymentRequest](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_extensions_payments_SalesforcePaymentRequest.html).

## Purpose

The `<isbuynow>` tag injects \<script> code in the page to render express checkout buttons that lets a shopper buy a specific product. See [dw.extensions.payments](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/package_dw_extensions_payments.html) to configure the express checkout buttons and understand how they're rendered.

## Rules of Use

This tag can appear multiple times on the same page, with no limit. The tag must be placed where `<script>` tags are valid, after the closing `</head>` tag in the HTML page.

This tag can't be used in a cached template because it's used for the shopper to pay for their current basket. The options in the `SalesforcePaymentRequest` include line items with amounts that depend on variables such as, currency, prices, promotions, and applicable shipping methods. Consider these when using this tag in a cached template.

Express checkout buttons are only rendered when applicable for the shopper. If the shopper isn't using a supported device or operating system, or hasn't configured them to use the available express checkout buttons, then no button is presented.

## Example

In this example, `<script>` code is injected by `<ispayment>` to render an Apple Pay button configured with Salesforce Payments on the site. The ID of the component is “applepay” and the CSS class name where the component is to be rendered is “apple-pay-button-container”.

A helper function, `COHelpers.calculateBuyNowData`, creates the basket data and payment request options. See [dw.extensions.payments](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/package_dw_extensions_payments.html) for details on how the data prepares a basket when a shopper taps an express checkout button and how the options create line items for the payment request, and then display the browser payment app, such as Apple Pay.

**note:** The script code that creates the `SalesforcePaymentRequest` object can be placed in a controller. `<isscript>` is used here as an example.

```
<isscript>
var SalesforcePaymentRequest = require('dw/extensions/payments/SalesforcePaymentRequest');
var COHelpers = require('*/cartridge/scripts/checkout/checkoutHelpers');

var buyNowData = COHelpers.calculateBuyNowData(pdict.product, pdict.quantity, pdict.price);

var paymentRequest = new SalesforcePaymentRequest('applepay', '.apple-pay-button-container');
 paymentRequest.addInclude(SalesforcePaymentRequest.ELEMENT_TYPE_APPLEPAY);
paymentRequest.setBasketData(buyNowData.basketData);
paymentRequest.setOptions(buyNowData.options);
</isscript>

<ispayment payment-request="${paymentRequest}"></ispayment>
```

<!-- document id=b22a4c6c63908f767dd30fc27de30f835744e514967bc8e9ce5ee44471c58012 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iscache.md -->

# iscache Element

Controls page caching to improve the performance of your storefront.

## Syntax

```
<iscache
  status = "on"
  type   = "relative" | "daily"
  hour   = integer_duration_hr
  minute = integer_duration_min
  varyby = "price_promotion"
  if     = boolean_expression />
```

## Attributes

- `status`

  - : _Allowed data types:_ string

    _Allowed values:_

    - “on” (default)
    - “off” (deprecated)

    The `status="off"` attribute setting, which explicitly disables page caching, is deprecated. To disable page caching, omit the `<iscache/>` element.

    If you specify `<iscache status="off"/>`, the system writes messages to the deprecation log. The messages warn you about the deprecated usage and show the code location for each occurrence. Also, if you set `status="off"`, either in the template or in one of its included templates, you can’t re-enable page caching.

    Disabling page caching by setting `status="off"` can hurt performance, because the server must fetch a new page for each request. If you have a situation where you must disable caching, we recommend using the `if` attribute of the `iscache` element. For example, you can disable caching to allow personalization for an individual shopper.

    Before `<iscache status="off"/>` was deprecated, you had to set `<iscache status="on"/>` to enable page caching. Now, just including an `<iscache/>` element in your template implicitly enables page caching, so you no longer have to set the `status` attribute.

- `type`

  - : _Allowed data types:_ string

    _Allowed values:_

    - "relative"
    - "daily"

    The value “relative” lets you specify a time period, in minutes and hours, after which the page is removed from the cache.

    The value “daily” lets you set a specific time when the page is removed from the cache. When specifying time, the 24-hour clock is used. Therefore, 0 is equal to midnight, 1 is equal to 1:00 AM, 2 is equal to 2:00 AM, up to 2359, which is equal to 11:59 PM. The time zone used is GMT.

    **note:** You must provide either the `type` or the `varyby` attribute. If you omit both, the `iscache` element is invalid and an exception is thrown.

- `hour`

  - : *Allowed data types:*integer, integer expression

    _Allowed values:_

    - If you set the `type` attribute to “daily,” 0—23.
    - If you set the `type` attribute “relative,” 0—unlimited.

    _Default values:_ If you specify the `type` attribute, the default is 0. If you specify the `varyby` attribute and omit the `type` attribute, the default is the next hour.

    Provides the hour value for the time when cache expires daily (`type="daily"`), or the number of hours from current time when cache expires relatively (`type="relative"`). Combined with the value of minute attribute.

- `minute`

  - : *Allowed data types:*integer, integer expression.

    _Allowed values:_

    - If you set the `type` attribute to "daily," 0—59.
    - If you set the `type` attribute to "relative," 0—unlimited.

    _Default values:_ If you specify the `type` attribute, the default is 0. If you specify the `varyby` attribute and omit the `type` attribute, the default is a random value 0–15 minutes (randomized with precision to seconds).

    The `minute` attribute can specify a minute value for the time when the cache expires daily (`type="daily"`). The `minute` attribute can also specify the number of minutes from the current time when cache expires relatively (`type="relative"`). The value of the `minute` attribute is combined with the value of `hour` attribute.

- `varyby`

  - : *Allowed data types:*string

    _Allowed values:_"price_promotion"

    The `varyby` attribute lets you mark a page as personalized. When a page is marked as personalized, Salesforce B2C Commerce uses additional parameters besides the URL string to uniquely identify the page cache. The web adapter stores the different variations of the page in the cache, and then delivers the correct version to the shopper based on these additional parameters.

    For the personalized cache to work properly, the following must be different within the context of the page:

    - The complete set of active promotions.
    - The complete set of active product sorting rules.
    - The complete set of applicable price books.
    - The complete set of active ABTest Groups.

    You can personalize a page by means other than price books, promotions, product sorting rules, or A/B test groups. If you do this type of personalization, don’t cache the page, because some shoppers can see incorrect variations of the page. To turn off caching for these pages, set the `if` attribute. Alternatively, if you link this custom personalization code to promotion objects, for example, use `varyby="price_promotion"` because the set of active promotions is different.

    For performance reasons, only use the `varyby` property if the page has different variations based on the additional parameters described previously. Otherwise, you can degrade performance unnecessarily because multiple identical copies of the same page are stored in the cache, resulting in cache fragmentation.

    A page is either personalized or not personalized. If a page contains multiple `<iscache/>` elements, some with the varyby attribute set and some with this attribute not set, the entire page is treated as personalized.

- `if`

  - : _Allowed data types:_ boolean expression

    Like the deprecated `status="off"` attribute setting, the `if` attribute lets you turn off caching, but it does so based on a condition. You can use this attribute to provide personalization for individual shoppers—for example, when implementing Commerce Einstein Predictive Sort. However, when the `if` condition evaluates to false, page caching is disabled. Therefore, we recommend you use the `if` attribute only for pages with little or no interaction with persisted objects. Otherwise, using this attribute can severely degrade performance. If you can use the `varyby` attribute instead, we recommend using it for personalization instead of the `if` attribute.

## Purpose

Cached pages are returned to the storefront quickly. A cached page is treated more like a static page, and less like a dynamically generated page.

After a page is cached, the system bypasses the controller that renders the page. Consequently, the server doesn’t process any isml templates, and the cached content of the page is delivered to the shopper almost instantaneously.

**note:** Sometimes, you can’t cache a page, or you don’t want to cache a page. For example, you generally don’t want to cache pages that contain shopper-specific data, such as address or basket information. For more information, see [Page Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-working-with-templates.md#page-caching-in-templates).

The first time a page is requested, the server dynamically generates the page. After the page is generated, it can be cached. If you want a storefront page to be cached, you must include the `<iscache>` element in the template. Alternatively, in the controller that renders the page, use one of the `setExpires` methods of the `Response` Script API class.

The `<iscache>` element lets you specify when the cached page expires from the cache. For example, you can expire the cached page after a fixed period.

The `<iscache>` element can be located anywhere in the template, but we recommend that you place the element as near as possible to the beginning of the template.

If you add multiple `<iscache>` elements in your template (or in locally included templates), one element takes precedence over the others. If an element turns caching off, it’s given precedence over the other elements. Otherwise, the element with the shortest cache time is given precedence. In general, when there are multiple `<iscache>` elements, the most restrictive one wins.

**note:** Consider the following when using page caching:

- When caching pages, don't use session information in the same template or in locally included templates. Session information includes shopper login status, basket contents, and so on. Session information is specific to each individual shopper. If session information gets cached and is mistakenly displayed to other shoppers, unexpected results can occur.
- When using templates as decorators (via the `isdecorate` element), display session information only in a remotely included, non-cached request. Otherwise, a template that uses the decorator can mistakenly apply caching to the decorator’s session data as well as its own. If session information gets cached and is mistakenly displayed to other shoppers, unexpected results can occur.
- If you put an `<iscache>` element in a locally included template, the element affects the caching of the whole page that is being produced.
- If you must display dynamic data, reduce the logic to the minimum needed and avoid unnecessary operations with persistent objects. Cache everything you can, leaving only small dynamic snippets on frequently visited pages.
- In cases where `<isscript>` blocks finish with exceptions, or database exceptions occur, the cache time is limited to 5 minutes. Exceptions from script expressions within ISML are excluded. To prevent exceptions and improve performance, review logs and clean up your code.

## Relative Caching Examples

The following lines of code are equivalent. Each line causes the resulting page to expire from the cache after 150 minutes:

```
<iscache type="relative" hour="2" minute="30">
```

```
<iscache type="relative" hour="1" minute="90">
```

```
<iscache type="relative" minute="150">
```

## Daily Caching Examples

The following line of code causes the resulting page to expire from the cache every day at midnight (0:00 AM):

```
<iscache type="daily">
```

The following line of code causes the resulting page to expire from the cache every day at 0630 hours (6:30 AM):

```
<iscache type="daily" hour="6" minute="30">
```

The following line of code causes the resulting page to expire from the cache every day at 2330 hours (11:30 PM):

```
<iscache type="daily" hour="23" minute="30">
```

## If Attribute Example

The following line of code causes the resulting page to turn off caching, allowing for the proper display of predictive sorting results:

```
<iscache hour="2" varyby="price_promotion" if="${!searchModel.isPersonalizedSort()}"/>
```

When used with the `if` attribute, the expression `{!searchModel.isPersonalizedSort()}` lets you control whether a page is cached. Use this technique with Predictive Sort to control the caching of predictive pages at the template level.

When the `if` attribute is used in this way, search requests that use a sorting rule with Predictive Sort are no longer cached. Caching is activated when the expression evaluates to `true` (the sorting isn’t personalized). Caching is deactivated when the expression evaluates to `false` (the sorting is personalized). If the expression evaluates to a non-boolean value, or if you try passing a value instead of an expression, an error is thrown.

## Varyby Example

The following line of code is suitable for a search result page:

```
<iscache type="relative" minute="30" varyby="price_promotion"/>
```

The search result page depends on availability information that can change over time, so we set the caching time to 30 minutes. The page also shows price and promotion information, which can differ by shopper. To instruct B2C Commerce to account for this possibility, we added `varyby="price_promotion".` With this added element, a cached page appears if the shopper has the same eligibility for prices and promotions.

The following line of code causes the resulting page to expire from the cache in a random interval. The random interval falls between 1 second and 15 minutes after the beginning of the next hour.

```
<iscache varyby="price_promotion"/>
```

<!-- document id=c03edef3d8394fb2446a92fa407b5f7a62c672ed6bbce38d3f2900daa7a16b5c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iscomment.md -->

# iscomment Element

Document your templates and include reminders or instructions for yourself and others who work with the system that aren’t available to anyone who "views source" on the page.

## Syntax

```
<iscomment>
  ...
</iscomment>
```

The alternative usage of the following has been deprecated as of 03/06/2009.

```
<!---  --->
```

**note:** We recommend that you use the standard `<iscomment>` syntax. However, using this syntax doesn't cause a failure.

## Purpose

Anything enclosed in an `<iscomment>... </iscomment>` structure isn't parsed by the template processor and doesn't appear in the generated storefront page.

HTML comments created by surrounding the text with the character strings `<!--`and -`->` are now deprecated. This is because this commenting method provides no confidentiality. Anyone can use a browser's **View** > **Source** menu to see the HTML code, including the comments.

## Example

```
<iscomment>
This comment isn't sent to the browser and isn't visible in the page source.
</iscomment>
```

<!-- document id=8f1a9f2eb6c3f6efc9817f58bff592847ed128cd4b9275e8731a1a8b76fddc62 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iscomponent.md -->

# iscomponent Element

Include the output of a pipeline in the page.

## Syntax

```javascript
<iscomponent
  pipeline   = pipeline_name //required
  locale     = locale_name
  parameterN = valueN       //zero or more
/>
```

- pipeline = pipeline_name

  - : _Allowed data type:_ string or expression.

    `pipeline_name` specifies the name of the pipeline, for example, "Product-Show" as a string or as an expression that resolves to the pipeline name.

**note:** SEO URLs can't be included remotely. Use the full syntax for the pipeline.

- locale = locale_name

  - : _Allowed data type:_ string or expression.

    `locale_name` specifies an optional locale for the pipeline call.

- parameterN = valueN

  - : You can define any number of additional parameters to be used by the pipeline.

## Purpose

This tag is similar to a remote include. However, it uses pipeline-related attributes to specify the content generating target and allows for arbitrary attributes.

Technically, the `<iscomponent/>` tag performs the same function as a remote include. The use of remote includes, however, might not be obvious. The `<iscomponent/>` tag, with its direct association to a pipeline, makes its purpose obvious. It's intended to embed reusable functionality, encapsulated in a pipeline, into another template. It also lets the embedded component have a different caching policy than the included page.

## Example

```javascript
<iscomponent pipeline="Product-Show" productid="1234" name="Wide-screen television" />
```

This example shows the inclusion of a product view on a page using the Product-Show pipeline, with a specified product ID and name.

<!-- document id=066705e426512f89f8abdc084dc6380b847c4bcc0710d23e1589fa4a5ae9778f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iscontent.md -->

# iscontent Element

Modify the HTTP header (set the content type) of the generated output stream sent to the browser or email client. The HTTP header is identified by its MIME type.

## Syntax

```
<iscontent
  type     = MIME_type
  charset  = char_set;
  encoding = "on" | "off" | "html" | "xml" | "wml"
  compact  = "true" | "false"
/>
```

- type = MIME_type

  - : _Allowed data type:_ string or expression.

    `MIME_type` specifies the MIME type of the generated output stream. If no type is specified, the `MIME_type` is set to `text/html`. Generally, storefront pages and email output are set to `text/html`.Use an expression for dynamic content types. You can set the encoding explicitly using the `charset` attribute, or determine it implicitly from the content type.

    **note:** It's possible, though rarely helpful, to generate one type of content through the type command and then encode the output with a different content type. Generally, the on and off commands suffice.

- charset = char_set

  - : _Allowed data type:_ string Expressions aren't allowed.

    `char_set` defines the character set of the output stream. The default value is the default encoding of the operating system that runs the Salesforce B2C Commerce application server. The default encoding is UTF8 and shouldn't be changed, unless really necessary.

- encoding = "on" | "off" | "html" | "xml" | "wml"

  - : Naming a content type, for example `html`, has the same affect as using the `on` value and also selects the type of output. All data processed after the first occurrence of the `<iscontent/>` tag is affected by this setting. Encoding converts characters that could cause a syntax conflict. For example, the ampersand symbol is converted to &amp in HTML encoding. The default encoding value is `html`. For more information, see Encoding Expression Results in [isprint](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-isprint.md).

    - `on` turns on encoding for the output stream. This is used in combination with the charset to determine the characters in the output stream.
    - `off` turns off encoding for the output stream.
    - `html` turns on encoding and specifies html as the type of encoding. This is used in combination with the charset to determine the characters in the output stream.
    - `xml` turns on encoding and specifies xml as the type of encoding. This is used in combination with the charset to determine the characters in the output stream.
    - `wml`turns on encoding and specifies xml as the type of encoding. This is used in combination with the charset to determine the characters in the output stream.

- compact = "true" | "false"

  - : _Allowed data type:_ boolean. Expressions aren't allowed.

    HTML code often contains white space that doesn't have any affect on the visual appearance of a page and is primarily used to make the code of a template easier to read. When compact is set to true, unnecessary white space is removed from the output stream. Compact is on by default. See the general examples for an example of how the compact attribute works.

## Purpose

In most cases, you don't need to set the type because this is done automatically by the node or pipelet that calls the template. These nodes set the MIME header as follows:

| Node/Pipelet                                           | MIME Type Setting |
| ------------------------------------------------------ | ----------------- |
| Interaction-continue or interaction-end node           | text/html         |
| SendMail pipelet                                       | text/plain        |
| dw.net.Mail (as part of a script run by a script node) | text/plain        |

To overwrite these defaults, or to have your template generate a different type of output, explicitly specify another MIME type in the type attribute. See also[Sending Email via Scripts or Hooks](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-sending-email-via-scripts-or-hooks.md)

Additionally, the `<iscontent/>` tag:

- Sets the character encoding of the generated output stream
- Allows HTML, XML or WML encoding for the whole template
- Removes unnecessary spaces by means of the compact attribute

  Dynamically select `<iscontent/>` settings. For example, use a dynamic expression to set the MIME type.

## General Example

This example sets the content type and character set of the output stream:

```javascript
<iscontent type="plain/text" charset="iso-8859-1" />
```

The following is a typical formatting of HTML code, with tabs or whitespace to make it more readable:

```html
<table>
  <tr>
    <td>Some text here</td>
    <td>More text here</td>
    <td>text</td>
  </tr>
</table>
```

**note:** Such white spaces increase the size of a file, which potentially increases the time necessary to transmit a page to the client. To optimize the output code of a template don't set compact to `false`. Because compact is set to `true` by default, use:

`<iscontent compact="true">` or `<iscontent/>`

This tag ensures that all extra white space is removed during the template conversion process, for example, converting the previous code into:

```html
<table>
  <tr>
    <td>Some text here</td>
    <td>More text here</td>
    <td>text</td>
  </tr>
</table>
```

The template compacting feature compresses templates before transmitting them to a client's browser. The process eliminates all unnecessary white spaces and can reduce the load time at client browsers.

Compacting can't be toggled within the template. The feature isn't applied to templates included within a calling template using the `<isinclude/>` tag. The statement must be used in each template that is to be compacted.

HTML statements that use formatted content, such as the `<pre>` tag, might not appear properly if used in a template with compacting. If a template uses these tags, avoid using the compacting feature or use dynamic content, created with expressions, for the formatted material. For example, to keep the additional spaces in the statement:

```html
<input type="submit" name=" Button " />
```

Use:

```html
<input type="submit" name="${' Button '}" />
```

To make sure that the `<pre>` tag works in a compacted template:

```html
<pre> This is formatted text .</pre>
```

Use an `<isprint/>` statement:

```html
<pre><isprint value="${' This is formatted text .'}"> </pre>
```

## Dynamic Content Type Examples

The following examples shows the resulting Content-Type: HTTP header for different values of the `type` and `charset` attributes:

| \<iscontent> Usage                                                                                                       | Resulting Content-Type       | Comment                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| \<iscontent type ="text/html" charset="ISO-8859-1" />                                                                    | text/html;charset=ISO-8859-1 |                                                                                                                                 |
| \<iscontent type="text/html" />                                                                                          | text/html;charset=UTF-8      | The charset used is the default encoding for ISML "UTF-8".                                                                      |
| \<iscontent type="plain" />                                                                                              | plain;charset=UTF-8          | The charset used is also the default encoding for ISML, "UTF-8".                                                                |
| \<isscript>pdict.ContentType = 'text/html';\</isscript> \<iscontent type="\${pdict.ContentType}" charset="ISO-8859-1" /> | text/html;charset=ISO-8859-1 |                                                                                                                                 |
| \<isscript>pdict.ContentType = 'text/html';\</isscript> \<iscontent type="\${pdict.ContentType}" />                      | text/html;charset=UTF-8      | The charset used is the default encoding for ISML, "UTF-8".                                                                     |
| \<iscontent charset="UTF-8" />                                                                                           | text/html;charset=UTF-8      | The type used is the default MIME type for ISML, "text/html".                                                                   |
| \<iscontent compact="true" />                                                                                            | text/html;charset=UTF-8      | The type used is the default MIME type for ISML, "text/html". The charset used is the default encoding for ISML pages, "UTF-8". |

**note:** If text of the page appears in the ISML template before the `<iscontent/>` tag, either directly or through a script containing `out.print()` statements, the `type` and `charset` specified in the tag can't be guaranteed to take effect. For best results, the `<iscontent/>` tag should always be first in an ISML template.

<!-- document id=0125de2e16016f766f6d8f3f79aa957c64c2330f458abe77aa59d87ee2def4eb url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iscontinue.md -->

# iscontinue Element

Stop processing the current item in the loop and start the next item in loop.

## Syntax

```
<iscontinue/>
```

## Purpose

The `<iscontinue>` tag differs from the `<isnext>` tag in that isnext just moves the iterator forward one and continues processing next line of code. `<iscontinue>` breaks out of the processing and then moves to top of loop to start processing again, if there are other items to process.

`<iscontinue/>` can be used only within an `<isloop>... </isloop>` loop structure. It's similar to "continue" in Java.

## Example

The following SiteGenesis example shows how to use `<iscontinue/>` to filter out the Gift Certificate payment method that is used later in the checkout process:

```
		<div class="payment-method-options">
			<isloop items="${pdict.CurrentForms.billing.paymentMethods.selectedPaymentMethodID.options}" var="paymentMethodType">

				<iscomment>Ignore GIFT_CERTIFICATE method, GCs are handled separately before other payment methods.</iscomment>
				<isif condition="${paymentMethodType.value.equals(dw.order.PaymentInstrument.METHOD_GIFT_CERTIFICATE)}"><iscontinue/></isif>

				<div class="form-row">
					<isset name="radioID" value="${paymentMethodType.value}" scope="page"/>
					<label for="is-${radioID}"><isprint value="${Resource.msg(paymentMethodType.label,'forms',null)}"/>:</label>

					<isif condition="${paymentMethodType.checked || (!empty(pdict.selectedPaymentID) && paymentMethodType.htmlValue == pdict.selectedPaymentID)}">
						<input type="radio" checked="checked" class="input-radio" name="${pdict.CurrentForms.billing.paymentMethods.selectedPaymentMethodID.htmlName}" value="${paymentMethodType.htmlValue}" id="is-${radioID}" />
					<iselse>
						<input type="radio" class="input-radio" name="${pdict.CurrentForms.billing.paymentMethods.selectedPaymentMethodID.htmlName}" value="${paymentMethodType.htmlValue}" id="is-${radioID}" />
					</isif>
				</div>

			</isloop>
		</div>
```

<!-- document id=2d57c685e5086e36f1718610bb8e4b2462905e942fcb623689dd3cd1dc77ece0 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iscookie.md -->

# iscookie Element

Set a cookie in your system

## Syntax

```
<iscookie
  name    = cookie_name //required
  value   = cookie_value //required
  comment = cookie_use
  domain  = domain_name
  path    = pathname
  maxAge  = cookie_lifetime
  version = cookie_spec
  secure  = "on" | "off"
/>
```

- name = cookie_name

  - : _Allowed data type:_ string or expression.

    `cookie_name` is a string or expression that specifies a name for the cookie. Names starting with "\$" aren't allowed.

- value = cookie_value

  - : _Allowed data type:_ string or expression.

    `cookie_value` is a string or expression that specifies the value stored by the cookie, such as a specific user ID.

- comment = cookie_use

  - : _Allowed data type:_ string or expression.

    Because cookies can contain private information about a user, the comment attribute documents the intended use of the cookie. The user can inspect the information to decide whether to accept or not to accept the cookie.

- domain = domain_name

  - : _Allowed data type:_ string or expression.

    `domain_name` specifies the domain for which the cookie is valid. An explicitly specified domain must always start with a dot. If not specified, the browser sets the attribute domain to the domain that issues the cookie.

- path = pathname

  - : _Allowed data type:_ string or expression.

    `pathname` specifies the subset of URLs to which this cookie applies. Pages outside of that path can't use the cookie.

- maxAge = cookie_lifetime

  - : _Allowed data type:_ integer or expression.

    `cookie_lifetime` defines the lifetime of the cookie in seconds. The value is a non-negative decimal integer. After the specified time elapses, the buyer's browser can discard the cookie. If the value is 0, the cookie will be deleted. If the value is less than 0, the cookie isn't persistent and is deleted when the browser exits. The lifetime of the cookie set by Salesforce B2C Commerce when an anonymous customer enters the site for the first time adheres to certain international data storage regulations. The maximum age of this cookie is 6 months. The lifetime of any cookie set by B2C Commerce is 6 months or less.

- version = cookie_spec

  - : _Allowed data type:_ decimal integer or expression.

    `cookie_spec` is a decimal integer that identifies the version of the specification which the cookie conforms to. A decimal integer contains any of the digits 0 through 9.

- secure = "on" | "off"

  - : The secure attribute indicates that a cookie must only be used with a secure server, such as SSL. Default value is `off`. Expressions aren't allowed.

## Supporting Objects

For programmatically reading and modifying cookies, see the following classes in the Scripting API documentation:

- `dw.system.Request`
- `dw.web.Cookies`
- `dw.web.Cookie`

## Purpose

A cookie is a message given to the web browser by B2C Commerce. A cookie stores user-related information on the buyer's system, such as storefront preferences for a single buyer. Cookies can also be used to simplify the login procedure, so buyers don't have to type in their names and passwords each time they access the storefront. To accomplish this, the cookie would store a unique user ID on the buyer's system. After the cookie is stored, the browser returns it every time the buyer requests the URL of the issuing server.

You can't set a cookie's SameSite attribute using the API. The server sets SameSite to None if either the developer sets the cookie's Secure flag or the global security preference Enforce HTTPS is enabled, in which case the Secure flag is also set. Otherwise, the server doesn't set the SameSite attribute and the browser uses its own default SameSite setting. The SameSite attribute isn't sent with a cookie if the server detects that the client doesn't correctly interpret the attribute.

## Example

The following example shows how to set a cookie that can be used later to identify a customer:

```
<iscookie
name = "UserID"
value = "${pdict.buyer.UUID}"
comment = "your international customer ID"
domain = ".foo.com"
path = "/acme"
maxAge = "10000"
version = "0"
secure = "on"
/>
```

The following example shows how to use a cookie that is sent with the current request.

```
<isif condition = "${request.httpCookies['UserID'] != null)}">
<isredirect location = "${URLUtils.url('LoginPanel')}" />
</isif>
```

<!-- document id=ff5c0a0272f3485f3012e97fdf33a1874eb6ee9d1b8fbf4aa0849fc111869fc0 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isdecorate.md -->

# isdecorate Element

Decorate the enclosed content with the contents of the specified (decorator) template.

## Syntax

```
<isdecorate template = template_name> //required
  ...
</isdecorate>
```

- template = template_name

  - : _Allowed data type:_ string or expression.

    `template_name` is the name of the decorator template that is used to decorate the contents.

## Purpose

The decorator template has the tag `<isreplace/>` identifying where the decorated content shall be included. Typically, only one tag (`<isreplace/>`) is used in the decorator template. However, multiple or zero `<isreplace/>` tags can also be used. If the decorating template doesn't have an `<isreplace/>` tag, the decorated content is omitted from the resultant output. If the decorator template has multiple `<isreplace/>` tags, the content to be decorated will be included for each `<isreplace/>` tag.

A typical use case is to decorate the content body with a header and footer.

## Example

The decorator tags can be nested to an arbitrary depth, for example:

```
<isdecorate template="mytemplate">
	...
	<isdecorate template="mytemplate">
	...
	</isdecorate>
</isdecorate>
```

Different decorator templates can be used in different `<isdecorate/>` tags, both in nested and non-nested scenarios.

<!-- document id=ffd99a2b6f609bcb44513b30a7c113836609b4661725ce39dc5a81874f2eeb1d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iselse.md -->

# iselse Element

Use with `<isif>` to specify what happens if neither the `<isif>` condition nor any `<iselseif>` conditions evaluate to `true`.

## Syntax

```
<isif condition = if_expression>
  ...
 <iselseif condition = elseif_expression> //0 or more
  ...
 </iselseif>
 <iselse>
  ...
</isif>
```

## Example

```
<input type="text" name="${pdict.CurrentForms.cart.couponCode.htmlName}" size="30"/>
<isif condition="${pdict.CurrentForms.cart.couponCodeValid.valid}">
value="${pdict.CurrentForms.cart.couponCode.htmlValue}"
	<iselse>
		value=""
</isif>
```

In this example, a coupon code is entered in the browser. If it's invalid, `<iselse>` returns a value of "".

<!-- document id=1bd720e07933d8461bc12f44d10091a1d9a1f851c57a5d5b1597a0270af3e20b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-iselseif.md -->

# iselseif Element

Use with `<iselseif>` to specify a subcondition off an `<isif>` tag.

## Syntax

```
<isif condition = if_expression>
  ...
<iselseif condition = elseif_expression> //0 or more
  ...
</iselseif>
<iselse>
  ...
</isif>
```

- condition

  - : _Allowed data type:_ string or expression.

    `elseif_expression` evaluates to a boolean value. If the `<isif>` condition is true, the system executes the code immediately following the `<isif` `>` tag, ignoring the enclosed `<iselseif>` and `<iselse>` tags. If the `<isif>` condition is false, the system ignores the code immediately following the `<isif>` tag, and then tests each `<iselseif>` condition in order. When the system finds a true `<iselseif>` condition, the system executes the code immediately following the `<iselseif>` tag and ignores any remaining `<iselseif>` and `<iselse>` tags. If all `<iselseif>` conditions are false, the system executes the code following the `<iselse>` tag.

## Example

In this example, the system determines if the product name equals 'case' or 'bag'. If it does, it shows the word _Monogram._ If it doesn't, it continues processing.

```
<thead>
  <tr>
    <th>Qty.</th>
    <th colspan="2">Description</th>
  <isif condition="${pdict.Product.name == 'case'}">
    <th>Monogram</th>
  <iselseif condition="${pdict.Product.name == 'bag'}">
    <th>Monogram</th>
  <iselse>
    <th>Unit Price</th>
  </isif>
    <th>Item Total</th>
    <th>&nbsp;</th>
  </tr>
</thead>
```

<!-- document id=660eeb9bd951f3eb48222f4ae43c49962f884b3c87e67b5afc830c3c607f5969 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isif.md -->

# isif Element

Create conditional template code and control the flow of business logic.

## Syntax

```
<isif condition = if_expression>
  ...
 <iselseif condition = elseif_expression> //0 or more
  ...
 </iselseif>
 <iselse>
  ...
</isif>
```

- condition = if_expression

  - : _Allowed data type:_ string or expression.

    `if_expression` evaluates to a boolean value. If the `<isif>` condition is true, the system executes the code immediately following the `<isif>` tag, ignoring the enclosed `<iselseif>` and `<iselse>` tags. If the `<isif>` condition is false, the system ignores the code immediately following the `<isif>` tag, and then tests each `<iselseif>` condition in order. When the system finds a true `<iselseif>` condition, the system executes the code immediately following the `<iselseif>` tag and ignores any remaining `<iselseif>` and `<iselse>` tags. If all `<iselseif>` conditions are false, the system executes the code following the `<iselse>` tag.

## Purpose

The `<isif>` tag group lets you create conditional programming constructs using custom tags.

## Supporting Tags

`<isif>` and its supporting tags, `<iselseif>` and `<iselse>`, are some of the most commonly used tags. They contain no business logic, just the conditional visualization of data.

## Rules of Use

Every `<isif>` tag must have a matching `</isif>` tag. You can use any Salesforce B2C Commerce script expression as a condition for the `<isif>` tag. In particular, you can use local variables, Pipeline Dictionary variables and any functions within those expressions.

`<iselse>` and `<iselseif>` are optional. You can use as many `<iselseif>` tags as needed in an `<isif>` statement, but you can only use one `<iselse>`, which must always be the last tag within an `<isif>` group.

## Example

A conditional expression should typically return a boolean which is interpreted appropriately. If condition expression evaluates to non boolean and is not null, it's interpreted as true. When it evaluates to null it's interpreted as false.

```
<isif condition="${pdict.Products.Price == 0}">
Special free gift.
<iselseif condition="${pdict.Products.Price < 100}">
Special deal.
<iselse>
Today's low price.
</isif>
```

This example shows how to toggle continuously between three different colors for the rows of a table. The current color is stored in the user-defined variable, color.

```
<isset name="color" value="${'#00FFFF'}" scope="PAGE">
<table>
<isloop iterator="${pdict.Basket.products} var="product">
<tr>
<td bgcolor="${product.color}">
<isprint value = "${product.name}">
</td>
</tr>
<isif condition="${color == '#00FFFF'}">
<isset name="color" value="${'#00CCFF'}" scope="PAGE">
<iselseif condition="${color == '#00CCFF'}">
<isset name="color" value="${'#0099FF'}" scope="PAGE">
<iselse>
<isset name="color" value="${'#00FFFF'}">
</isif>
</isloop>
</table>
```

<!-- document id=f45aa0d5b84cbd25c933c440c7dc86b28ce9cc5e789ddb4038a36eef5f5123e2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isinclude.md -->

# isinclude Element

Include the contents of one template inside another or the contents of another URL.

## Syntax

```
<isinclude
  (template = template_name) | (url = url_path) //required. template or URL, but not both
  sf-toolkit = on | off //on is default
/>
```

- (template = template_path) | (url = url_path)

  - : You must include either template or URL, but not both:

    - template = template_path

      _Allowed data type:_ string or expression.

      `template_path` specifies the name and location of the included template. Use a fixed value or an expression. This is a local include.

    - url = url_path

      _Allowed data type:_ string or expression.

      `url_path` specifies a URL via a literal string or an expression. This includes the content of this URL, typically a URL from the same server. This is a remote include.

      **note:** SEO URLs can't be included remotely.

- sf-toolkit

  - : _Allowed data type:_ string

    `on` renders the `dwMarker` tag around includes. This can cause Internet Explorer to enter Quirks mode.

    `off` suppresses the `dwMarker` tag around includes. See the section on suppressing the dwMarker tag.

## Purpose

The template being included can be as complex as an entire page template, or as simple as a single line of HTML code.

Iterators used in the including template can be referenced from the included template. This is useful if you want to use an included template in a loop statement. To avoid infinite template processing caused by self-includes, the maximum include depth is fixed to 10.

**note:** Includes from another server aren’t supported.

There are two possibilities when referencing an included template: The ISML code is processes or the ISML code isn't processed

## ISML Code Is Processed

If the template is stored in a Salesforce B2C Commerce cartridge, you can use the template attribute to specify the path and the file name of the template to be included (the specified path has to be relative to your cartridge's `root/templates/default language` directory).

For example:

```
<isinclude template="reporting/ReportABTesting.isml">
```

- The path to the ISML template can only contain slashes. The template name can have the suffix ".isml" or not. If the suffix isn't present, it's appended automatically.
- The template path can be a fixed name or an expression, for example:

  `<isinclude template="reporting/ReportABTesting.isml">` is a fixed name.

  `<isinclude template="${pdict.Content.template}">` is an expression.

- The included template, contained in the Pipeline Dictionary, is determined by the _template_ attribute of the Content object inside of the Pipeline Dictionary.
- The maximum include depth for template includes `<isinclude template="">` is 20.

  This is necessary to protect template processing from recursive includes. If the include depth is reached or exceeded, an error is logged and templates of a higher include depth are omitted. This is because local includes are processed by the application server itself.

Example:

The following example shows a standard include of a template. The template `blueBar.isml` file could be used in a template to show a menu bar on the storefront pages.

This menu bar gives the customer access to different storefront functionality, such as a basket or the search mask. Using `<isinclude>` this way implements server-side frames that give you the full functionality of frames without the caveats of client-side frames due to incompatibilities between different browsers.

```
<isinclude template="inc/blueBar">
```

This example shows a standard include where the included template references an iterator of the including template:

```
<isloop iterator = "${pdict.Basket.product}" var="product">
<isinclude template = "inc/banner">
</isloop>
...
<!-- code of the included template -->

```

## ISML Code Isn't Processed

The second possibility is to reference a remote URL that is located on another server accessible via an HTTP or HTTPS connection. In this case, use the URL attribute to specify a valid URL. Using the URL attribute directs B2C Commerce eCommerce to open an HTTP(S) connection to the specified remote system during run time, and to add the result of this HTTP(S) request to the template. Remote templates are useful if you want to avoid client-side frames in HTML or when combining data in one template that comes from multiple servers.

The included URL can have a different caching policy. Use this to, for example, embed a dynamic snippet of HTML, which isn't cached, into a completely cached surrounding page. Conversely, a fully cached snippet can be embedded into a fully dynamic and uncached page.

for example:

```
<isinclude url="${URLUtils.url('Page-Include','cid', 'COOKIE_TEST')}">
```

- Use the URLUtils helper API class to construct a valid URL string.
- The maximum include depth for recursive URL includes `<isinclude url="">` is 16.
- This is part of the B2C Commerce Web Server configuration, because remote includes are sent back to the Web Adapter, which performs another call to the application server. If the maximum include depth is reached, the B2C Commerce Web Server logs an error and cancels further request processing.

Example:

This example shows an include that combines data into one template. In this case, `<isinclude>` triggers another pipeline to show hot deals on the storefront entry page. The call is executed after the Webserver processes the initial request. Therefore, data in the Pipeline Dictionary is no longer available.

```
<isinclude url="${URLUtils.url('BrowseCatalog-Hotdeals',
'catalogCategoryID','Storefront')}">
```

This example illustrates dynamic template selection. The name of the referenced template is built during run time.

```
<isinclude template = "${'ProductTemplates/Template' + pdict.product.templateNumber}">
```

## Suppressing the DwMarker Tag for Internet Explorer

If you’ve enabled the Storefront Toolkit, the content of every `<isinclude>` tag is surrounded by a dwMarker tag. Under some circumstances, the dwMarker tag causes Internet Explorer to change into Quirks mode.

For example:

```
<!-- dwMarker="linclude" dwTemplateTitle="/default/test/customassets.isml (SiteGenesis Storefront cartridge)" dwTemplateURL="http://localhost:60606/target=/c/sitegenesis_storefront_richUI/t/default/test/customassets.isml" -->
<!DOCTYPE html>
```

You can now add the `sf-toolkit="off"` attribute in your `isinclude` tag to suppress the `dwMarker` tag from being written into your HTML page.

```
<isinclude template="test/customassets" sf-toolkit="off"/>
```

This suppresses the `dwMarker` tag around the content produced by `test/customassets.isml`. The new attribute is only supported by local includes. However, remote includes don't support this attribute.

**note:** The `sf-toolkit="off"` attribute isn’t applied recursively. The dwmarker tag is only suppressed for the include tag itself, and not for any child-"isinclude" inside of that "include" template.

<!-- document id=aee348a47e73226241c5d4a2c2b46cc0c8db8da705ce930ca364d6250cd2fbc6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isloop.md -->

# isloop Element

Create loops for flow control.

## Syntax

```
<isloop
  (items = item_object ) | (iterator = iter_object) //required
  (alias = alias_name) | (var = var_name)
   status = status_name
   begin  = start_index
   end    = stop_index
   step   = increment_index
  ...
</isloop>
```

- (items = item_object ) | (iterator = iter_object)

  - : _Allowed data type:_ expression.

    You must include one of the following but not both:

    - items = item_object

      `item_object` is an expression that returns an object to iterate over. Attributes _iterator_ and _items_ can be used interchangeably.

    - iterator = iter_object

      `iter_object`is an expression that returns an object to iterate over. Attributes _iterator_ and _items_ can be used interchangeably.

    `items`is preferred.

- (alias = alias_name) | (var = var_name)

  - : Name of the variable referencing the object in the iterable collection referenced in the current iteration.

    You must include one of the following but not both:

    - alias = alias_name :

      `alias_name` is the name of a variable referencing the object in the iterable collection referenced in the current iteration.

    - var = var_name :

      `var_name` is the name of a variable referencing the object in the iterable collection referenced in the current iteration.

    `var` is preferred.

- status = status_name

  - : `status_name` is the variable name referencing the loop status object. The loop status is used to query information such as the counter or whether it's the first item.

    If status is specified, a loop status object is assigned to the given variable name. Below are the properties of the loop status object:

    | Attribute | Description                                                   |
    | --------- | ------------------------------------------------------------- |
    | count     | The number of iterations, starting with 1.                    |
    | index     | The current index into the set of items, while iterating.     |
    | first     | True, if this is the first item while iterating (count == 1). |
    | last      | True, if this is the last item while iterating.               |
    | odd       | True, if count is an odd value.                               |
    | even      | True, if count is an even value.                              |

- begin = start_index

  - : _Allowed data type:_ expression.

    `start_index` is an expression specifying a begin index for the loop. If the begin is greater than 0, the \<isloop> skips the first x items and starts looping at the begin index. If begin is smaller than 0, 0 is used as the begin value.

- end = stop_index

  - : _Allowed data type:_ expression.

    `stop_index`is an expression specifying an end index (inclusive). If end is smaller than begin, the `<isloop>` is skipped.

- step = increment_index

  - : _Allowed data type:_ expression.

    `increment_index` is an expression specifying the step used to increase the index. If step is smaller than one, one is used as the step value.

## Purpose

With `<isloop>` you can loop through the elements of a specified iterator. As an example, you can list data like categories, products, shipping, and payment methods. `<isloop>` statements can be nested in one another.

## Supporting Tags

- Use `<isbreak>` to unconditionally terminate a loop.
- Use `<isnext>` to jump forward in a loop

See [isbreak](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-isbreak.md) and <[isnext](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-isnext.md) for more information.

## Example

```
<isloop iterator = "${pdict.Basket.products}" alias = "product">
<isprint value = "${product.name}"> <BR>
</isloop>
```

**note:** The previous pdict.Basket is merely an example of using the Pipeline Dictionary as it relates to the Reference Application. It isn't the same as the Basket class in Salesforce B2C Commerce server-side JavaScript.

<!-- document id=afad4f724f5baed1916115749b9241b7588b44b2779649cc23efc80eba49c663 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isml.md -->

# ISML

B2C Commerce ISML tags are extensions of the tag-based language conforming to SGML standards. They are commands inserted into a document that determine how B2C Commerce embeds live data into a page, and how to format this data together with the regular HTML code.

Each B2C Commerce tag has a specific name that always starts with the prefix "is," such as `<isprint>` or `<isset>`. Tags must be included within angle brackets (`<` and `>`), and can have several attributes that can be set to control the behavior of the tag. All tags and their attribute names are not case sensitive. However, the values of attributes are often case sensitive.

**tip:** Salesforce recommends that you use lower-case as good programming practice.

The syntax shows literal values in quotes and variables without quotes. Unless otherwise noted, each attribute is included exactly one time. You can only use expressions or strings as documented. Using expressions if they are not explicitly allowed causes exceptions.

<table><thead><tr><th>Tag &amp; Location</th><th>Syntax &amp; Notes</th></tr></thead><tbody><tr><td>

`<isactivedatacontext>`

Allowed locations:

- `<head>`
- `<body>`
- Anywhere that script tags are valid.

</td><td>

```
<isactivedatacontext
  category = current_category //req
/>
```

Collects category context from a page for active data.

Should only be in one template used to render a page.

</td></tr><tr><td>

`<isactivedatahead>`

Allowed location:

- `<head>`

</td><td>

```
<isactivedatahead/>
```

Allows collection of active data from pages with a `<head>` tag.

</td></tr><tr><td>

`<isanalyticsoff>`

Allowed locations:

- `<head>`
- `<body>`
- Anywhere that script tags are valid.

</td><td>

```
<isanalyticsoff/>
```

Disables analytics for single pages.

</td></tr><tr><td>

`<isbuynow>`

Allowed locations:

- `<body>`
- Anywhere that script tags are valid.

</td><td>

```
<isbuynow payment-request = SalesforcePaymentRequest expression \\ req>
</isbuynow>
```

Injects `<script>` to render express checkout buttons that lets a shopper buy a specific product.

</td></tr><tr><td>

`<isbreak>`

Allowed locations:

- `<body>`

</td><td>

```
<isbreak/>
```

Only used inside `<isloop>` for terminating loops.

</td>

</td></tr><tr><td>

`<iscache>`

Allowed location:

- Anywhere in the template

</td><td>

```
<iscache
  status = "off" | "on"
  type = "relative" | "daily"     //req
  hour = duration_hr
  minute = duration_min
  varyby = "price_promotion"
/>
```

Cache a page.

The tag can be located anywhere in the template. However, we recommend that caching statements are placed at the beginning of a template.

If the tag occurs several times in one template, the one set to <emph>cache off</emph> or the one with the shortest cache time is used as the cache setting for the resulting page.

</td></tr><tr><td>

`<iscomment>`

Allowed location:

- Anywhere in the template

</td><td>

```
<iscomment>
  ...
</iscomment>
```

Add documentation to the template.

As a best practice, include an initial comment that describes the purpose, the requirements, and the effect of a template from both a business point of view and a technical perspective.

Using `<iscomment>` is preferable to using HTML comments, especially for sensitive information, because the tag is removed automatically by B2C Commerce on rendered pages.

</td></tr><tr><td>

`<iscomponent>`

Allowed location:

- Anywhere in the template

</td><td>

```
<iscomponent
  pipeline = pipeline_name        //req
  locale = locale_name
  parameterN = valueN             //zero or more
/>
```

Include the output of a pipeline in the page.

</td></tr><tr><td>

`<iscontent>`

Allowed location:

- Before the `DOCTYPE` declaration

</td><td>

```
<iscontent
  type = MIME_type
  charset = char_set;
  encoding = "on" | "off" | "html" | "xml"
   | "wml"
  compact = "true" | "false"
/>
```

Define the MIME type of the output document.

Don't specify `<iscontent>` if it isn't needed. The default for pipeline responses is `text/html`, UTF-8, and `compact="false"`.

The default for emails when using the SendMail pipelet is `text/plain`.

To make sure all characters in a document are correctly encoded, the `<iscontent/>` tag should always be first in an ISML template.

</td></tr><tr><td>

`<iscontinue>`

Allowed location:

- `<body>`

</td><td>

```
<iscontinue/>
```

Jump to the beginning of the loop.

Only used inside `<isloop>`.

</td></tr><tr><td>

`<iscookie>`

Allowed location:

- Anywhere in the template

</td><td>

```
<iscookie
  name = cookie_name              //req
  value = cookie_value            //req
  comment = cookie_use
  domain = domain_name
  path = pathname
  maxAge = cookie_lifetime
  version = cookie_spec
  secure = "on" | "off"
/>
```

Set a cookie.

</td></tr><tr><td>

`<isdecorate>`

Allowed location:

- Must wrap all content to be decorated.

</td><td>

```
<isdecorate
  template = template_name        //req
>
  ...
</isdecorate>
```

Template decoration mechanism.

For `<isdecorate>` to render a page, the content it wraps must contain an `<isreplace/>` tag.

</td></tr><tr><td>

`<iselse>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isif condition = if_expression>
  ...
<iselseif condition = elseif_expression>
  //0 or more
  ...
</iselseif>
<iselse>
  ...
</isif>
```

Specify what happens if a condition doesn't evaluate to true.

Must be used with `<ifelse>`.

</td></tr><tr><td>

`<isif>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isif condition = if_expression>
  ...
<iselseif condition = elseif_expression>
  //0 or more
  ...
</iselseif>
<iselse>
  ...
</isif>
```

Create conditional template code.

</td></tr><tr><td>

`<iselseif>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isif condition = if_expression>
  ...
<iselseif condition = elseif_expression>
  //0 or more
  ...
<iselse>
  ...
</isif>
```

Specify a subcondition for an `<isif>` tag in a loop.

</td></tr><tr><td>

`<isinclude>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isinclude
  (template = template_name)
   | (url = url_path)
//req
/>
```

Includes the contents of one template inside another.

As a best practice, add includes that affect the whole page to the top of the template.

</td></tr><tr><td>

`<isloop>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isloop
  (items = item_object )
   | (iterator = iter_object)
    //req
  (alias = alias_name) | (var = var_name)
  status = <var name>
  begin = <expression>
  end = <expression>
  step = <expression>>
  ...
</isloop>
```

Creates a loop.

See also `<isbreak>`, `<iscontinue>`, and `<isnext>`.

</td></tr><tr><td>

`<ismodule>`

Allowed location:

- Anywhere in the template

</td><td>

```
<ismodule
  template = template_path        \\req
  name = tag_name                 \\req
  attribute = attr_name           \\req
/>
```

Declares custom tags.

In SiteGenesis, all `<ismodules>` are declared in one file: `util/modules.isml`.

</td></tr><tr><td>

`<isnext>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isnext/>
```

Jump forward within a loop.

Only used inside `<isloop>`.

</td></tr><tr><td>

`<isobject>`

</td><td>

```
<isobject
  object = name                   \\req
  view = "none" | "searchhit"
   | "recommendation" | "setproduct"
   | "detail" \\req
  ...
</isobject>
```

Collects page impressions or views from the storefront.

Must pass an object of type `ProductHit`.

Must wrap any object you want to record active data for.

</td></tr><tr><td>

`<ispayment>`

Allowed locations:

- `<body>`
- Anywhere that script tags are valid

</td><td>

```
<ispayment
  payment-request = SalesforcePaymentRequest expression \\ req>
</ispayment>
```

Injects `<script>` to render express checkout buttons that lets a shopper pay for items in the current basket.

</td></tr><tr><td>

`<isprint>`

Allowed location:

- `<body>`

</td><td>

```
<isprint
  value = output                  \\req
  (style = style_ID)
   | (formatter = format)
     \\style or formatter, but not both
  timezone = "SITE" | "INSTANCE" | "utc"
  padding = padding_constant
  encoding = "on" | "off"
/>
```

Format and encode output strings.

</td></tr><tr><td>

`<isredirect>`

Allowed location:

- Before the `DOCTYPE` declaration

</td><td>

```
<isredirect
  location = target_url           \\req
  permanent = "true" | "false"
>
```

Redirect to a target URL.

</td></tr><tr><td>

`<isremove>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isremove
  name = var_name                 \\req
  scope = "session" | "pdict"
   | "request" | "page"
>
```

Remove user-defined variables.

</td></tr><tr><td>

`<isreplace>`

Allowed location:

- Must be within `<isdecorate>` tags

</td><td>

```
<isreplace/>
```

The insert content to be decorated.

If a template is going to be remotely included, the `<isdecorate>` tags can be in the including template.

</td></tr><tr><td>

`<isscript>`

Allowed locations:

- `<head>`
- `<body>`
- Anywhere that script tags are valid

</td><td>

```
<isscript>
  ...
</isscript>
```

Create a script within a template.

</td></tr><tr><td>

`<isselect>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isselect
  name = simple_name              \\req
  iterator = loop_var             \\req
  description = box_text          \\req
  value = text_value              \\req
  condition = "true" | "false"
  encoding = "on" | "off"
/>
```

Enhancements to the HTML `<select>` tag.

</td></tr><tr><td>

`<isset>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isset
  name = var_name                 \\req
  value = var_value               \\req
  scope = "session"|"request"
   |"page"                        \\req
/>
```

Set user-defined variables.

</td></tr><tr><td>

`<isslot>`

Allowed location:

- `<body>`
- Usually within `<isdecorate>` tags

</td><td>

```
<isslot
  id = id \\req
  context = "global"
    | "category"                  \\req
  context-object = context-object \\req
  description = description       \\req
  preview-url = url               \\req
>
```

Define slots for content display.

</td></tr><tr><td>

`<isstatus>`

Allowed location:

- Anywhere in the template

</td><td>

```
<isstatus
  value = http_code               \\req
/>
```

Define a status code.

</td></tr></tbody></table>

**See also:**

- The [ispaymentmessages Element](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/isml/b2c-ispaymentmessages.md)

**Parent topic:**

- [Templates](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-working-with-templates.md)

<!-- document id=1512b71036aeda77443d9e8d309b4d90e2ecdfa0aeaad8a7f23f64ce9a78b6ea url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isml-expressions.md -->

# ISML Expressions

ISML expressions let you embed programming logic, using a business API, into a template to generate dynamic content. The syntax and semantics of these expressions is based on JavaScript and similar to those defined for JSP expressions. ISML provides SGML-like extension tags. Along with HTML code, they describe how dynamic data is embedded and formatted.

Script expressions can be embedded directly in the template or used in tag attributes. Template programming via scripting isn’t limited to expressions. Extended programming logic can be expressed via scriptlets (see \<[isscript](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-isscript.md)> for details).

Expressions have the following syntax:

```
 ${...}
```

where `${` is the opening identifier, and `}` is the closing identifier. The content enclosed within is interpreted as an expression.

Given that pages are dynamically generated, you need a way to call and present dynamic data in templates. Any data to be presented within a template must be available via the Pipeline Dictionary. ISML expressions provide access to the pipeline data.

Syntax:

```
${pdict.<KeyAttributeName>}$
```

## Using the \</Body> Tag

The `</body>` tag is a protected keyword in ISML. You _must not_ use the `</body>` tag in ISML comments and JavaScript. If you do, you must obfuscate it in JavaScript, as in this example:

```
var endbdy = data.indexOf("</bo" + "dy>");
```

## Examples

This example shows an expression embedded as an attribute value in an ISML tag:

```
<isprint value="${pdict.Product.name}">
```

This example accesses data (via a get method) that is stored in the Pipeline Dictionary:

```
"${pdict.Product.getLongDescription() != null}"
```

This example includes the special function `URLUtils.continueURL()`:

```
<form action="${URLUtils.continueURL()}" method="post" id="${pdict.CurrentForms.cart.htmlName}">
```

### Additional Examples

| Example                   | Description                 |
| ------------------------- | --------------------------- |
| ${pdict.Product}          | Refers to a product.        |
| ${pdict.Content.template} | Refers to a content object. |
| ${pdict.ProductPrices}    | Refers to product prices.   |
| ${pdict.Order.orderNo}    | Refers to the order number. |

<!-- document id=695a471e6c81d88d7488432872e7ea026c6b90b673711663c6db43260084ac20 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-ismodule.md -->

# ismodule Element

Declare custom tags in your templates.

**note:** For Storefront Reference Architecture (SFRA) implemenations, this tag is primarily used for content assets.

## Syntax

```
<ismodule
  template  = template_path \\required
  name      = tag_name      \\required
  attribute = attr_name     \\0 or more
/>
```

- template = template_path

  - : _Allowed data type:_ string or expression.

    Defines a path and a name for the template implementing the tag. Relative paths are expanded from the server's template root directory.

    Template file names and folder names can't contain spaces.

- name= tag_name

  - : _Allowed data type:_ string. Expression isn't allowed.

    `tag_name` is the name of the custom tag. Custom tags are always declared without the _is_ prefix, for example, _mytag._ However, when using the custom tag in a template, you must include the _is_ prefix like this: `<ismytag>`. Custom tags can use either case.

- attribute = attr_name

  - : _Allowed data type:_ string. Expression isn't allowed.

    Specifies attributes you want your custom tag to have. The number of attributes is unlimited, but attributes aren’t required.

    Because all attribute names stored in the Pipeline Dictionary are lowercase, use lowercase names in the definitions.

## Purpose

The declaration can be located anywhere in the template, as long as it appears before the first usage of the declared tag. Multiple declarations of the same tag don't interrupt template processing, the last one is used. Optionally, define a custom tag in an included template and use it afterward in the including template.

Custom tags can be used like any other tags. In fact, a custom tag is an included template that can have user-defined attributes. Therefore, every custom tag definition is stored in a separate file. This method is similar to an include template.

Custom tag attributes are slightly restricted and generalized in their behavior and syntax, as follows:

- They can be strings or expressions that are converted to strings during run time.
- They’re always optional. During run time, the template processor doesn't check if attributes are missing. If needed, code a check explicitly.
- They can be accessed in the definition template simply by name. This method is similar to how user-defined variables are accessed.

## Examples

This first example demonstrates the declaration, the implementation, and the application of a custom tag `bgcolor`, which is used for inserting colored backgrounds.

Before you can use a custom tag in a template, it must be declared in the same template (`sample1.isml`). The tag declaration must include a reference to a separate template file (`background.isml`) containing the actual code of the tag. In this case, the `background.isml` file has been stored in a separate folder named TagExtension.

Here’s the content of the `sample1.isml` file:

```
<!--- tag declaration --->
<ismodule template = "TagExtension/background.isml"
name = "bgcolor"
attribute = "color">
<!--- tag usage --->
<isbgcolor color = "green">
```

And here, the contents of the background.isml file:

```
<!--- tag implementation --->
<isif condition="${color != null}">
<img src="${URLUtils.webRoot() + 'images/background_' + color + '.gif'}">
<iselse>
<img src="${URLUtils.webRoot() + 'images/background_default.gif'}">
</isif>
```

This second example is from the Reference Application, and uses the Pipeline Dictionary.

Here’s the section within `checkout_address.isml` that references the `step` attribute, which keeps track of a customer's progress during checkout.

```
<ismodule
	template="cart/checkout_progressindicator"
	name="checkoutprogressindicator"
	attribute="step">
```

The template it refers to, containing the actual code of the tag, is `cart/checkout_progressindicator.isml`. This template uses the Pipeline Dictionary to track the step value:

```
<div class="checkoutprogressindicator">
	<isif condition="${pdict.step == '1'}">
		<isset name="step1state" value="active" scope="PAGE">
		<isset name="step2state" value="inactive" scope="PAGE">
		<isset name="step3state" value="inactive" scope="PAGE">
		<isset name="step4state" value="inactive" scope="PAGE">
	<iselseif condition="${pdict.step == '2'}">
		<isset name="step1state" value="inactive" scope="PAGE">
		<isset name="step2state" value="active" scope="PAGE">
		<isset name="step3state" value="inactive" scope="PAGE">
		<isset name="step4state" value="inactive" scope="PAGE">
	<iselseif condition="${pdict.step == '3'}">
		<isset name="step1state" value="inactive" scope="PAGE">
		<isset name="step2state" value="inactive" scope="PAGE">
		<isset name="step3state" value="active" scope="PAGE">
		<isset name="step4state" value="inactive" scope="PAGE">
	<iselseif condition="${pdict.step == '4'}">
		<isset name="step1state" value="inactive" scope="PAGE">
		<isset name="step2state" value="inactive" scope="PAGE">
		<isset name="step3state" value="inactive" scope="PAGE">
		<isset name="step4state" value="active" scope="PAGE">
	<iselse>
		<isset name="step1state" value="inactive" scope="PAGE">
		<isset name="step2state" value="inactive" scope="PAGE">
		<isset name="step3state" value="inactive" scope="PAGE">
		<isset name="step4state" value="inactive" scope="PAGE">
	</isif>
```

<!-- document id=21da5fe365c81f83808ba6c2abad22051da49f5086588a302284323d23d8798d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isnext.md -->

# isnext Element

Jump forward within a loop to the next list element of an iterator.

## Syntax

```
<isnext/>
```

## Purpose

This tag affects only the iterator of the inner loop. If an iterator has already reached its last element, or an iterator is empty when an `<isnext>` is processed, the loop is terminated instantly.

`<isnext>` can be used only within an `<isloop>... </isloop>` loop structure.

## Example

The following example shows how to output the names of two products one after another:

```
<isloop iterator="${pdict.Products}" var="product">
  <isprint value="${product.name}">
  <isnext/>
  <isprint value="${product.name}"> <BR>
</isloop>
```

<!-- document id=684f1881a7d393a99338afc8526482c596b2901c2d7cfe466c257c1c1f3442e1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isobject.md -->

# isobject Element

Collect active data about what products are viewed in the search results, product detail pages, and recommendation.

## Syntax

```
<isobject
  object =  Product \\required
  view   = "none" | "searchhit" |  "recommendation" | "setproduct" | "detail" \\required
  ...
</isobject>
```

- object = Product

  - : You must specify a dw.catalog.Product object as part of an expression for the tag.

    ```
    <isobject object="${pdict.Product}"
    ```

    Specify objects in a loop. In the following example, the item is in a loop as it processes products in a search result.

    ```
    <isobject object="${LoopProductHit}" view="searchhit">
    ```

    When `view = “searchhit”`, the object passed should be of type `ProductHit`.

- view = "none" | "searchhit" | "recommendation" | "setproduct" | "detail"

  - :

    - none - Collects search information for the storefront toolkit but doesn't count the object as a product hit for active merchandising. For example, you might want to use this for templates where no search hits are found. This attribute can be used to collect information for the Storefront Toolkit Search Information Tool even if active merchandising isn't enabled for the instance. The passed object attribute is an instance product search model object. For example,

      ```xml
      <isobject object="${ProductSearchModel}" view="none">
      ```

    - searchhit - Collects one product impression for each time the page is viewed and collection search information for the storefront toolkit search information tool. This attribute can be used to collect information for the Storefront Toolkit Search Information Tool even if active merchandising isn't enabled for the instance.
    - recommendation - Collects one product impression for each time the page is viewed. This attribute never passes search information to the Storefront Toolkit Search Information Tool.
    - setproduct - Collects one product impression for each time the page is viewed. This attribute never passes search information to the Storefront Toolkit Search Information Tool.
    - detail - Collects one product view for each time the page is viewed. This attribute never passes search information to the Storefront Toolkit Search Information Tool.

## Purpose

For specific instructions on implementing this tag for different page types, see [Tagging Pages for Data Collection.](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/active-merchandising/b2c-tagging-pages-for-data-collection.md)

The \<isobject> tag must be placed so it wraps the ISML for HTML components that represent the product: the product name, image, callout, price, swatches, and other components. The tag must be placed where \<script> tags are valid.

This tag can appear any number of times in the same page, with no limit. If the same product appears in multiple tags in the same page, for the same view attribute value, only one is counted.  The same product can be a searchhit and also a recommendation, but can't count as two searchhits.  Because searchhit and setproduct both count for a product impression, if the same product is contained in the same page as both a searchhit and setproduct, only one impression is counted.

It isn't necessary to wrap the HTML content for every representation of every product that appears in the site. For example, it isn't appropriate to wrap products in pages that show the contents of the cart. As of this release the only side effect of not wrapping a product representation in a template is that analytics data isn't collected in that template. The correct placement of this tag is anywhere an ISML template contains a representation of a product with the intent to merchandize that product for sale on the site. If a product representation is tagged but doesn't exactly match one of the view types listed previously, one of the view types must be chosen that captures analytics data which most closely matches the intent.

## Example

In this example, the bonus _bonusproduct.isml_ template is wrapped, so that when a customer views it, the page impression count is incremented.

```
<isobject object="${pdict.Product}" view="setproduct">
	<isinclude template="product/components/subproduct"/>
</isobject>
```

<!-- document id=fbce031122ce61c4b41864a86d8a66322698b5900eb4b0c7170117e8e547cf8a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-ispayment.md -->

# ispayment Element

Inject code to render payment methods or express checkout buttons that let a shopper pay for their current basket.

To render express checkout buttons that lets a shopper buy a specific product, see [\<isbuynow>](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-isbuynow.md).

`<ispayment>` is only used with B2C Commerce Payments. An associated payments account must be successfully enabled and configured for use on the storefront site where this element appears.

## Syntax

```
<ispayments  payment-request = SalesforcePaymentRequest expression \\required
></ispayments>
```

- payment-request = SalesforcePaymentRequest expression

  - : Specify a `dw.extensions.payments.SalesforcePaymentRequest` as part of an expression for the tag. See [SalesforcePaymentRequest](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_extensions_payments_SalesforcePaymentRequest.html).

## Purpose

The `<ispayment>` tag injects `<script>` code in the page to render payment methods or express checkout buttons that let a shopper pay for their current basket. See [dw.extensions.payments](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/package_dw_extensions_payments.html) to configure the payment methods and express checkout buttons, as well as understand how they're rendered.

## Rules of Use

This tag appears multiple times on the same page with no limit. When used to render payment methods for the payment step of a checkout page, it only appears once. The tag must be placed where \<script> tags are valid, after the closing \</head> tag in the HTML page.

This tag can't be used in a cached template because it's used for the shopper to pay for their current basket. However, you can use it in a remote included template referenced by a cached template, similar to a minicart.

Payment methods are only rendered when applicable for the basket. If a potentially available payment method doesn't support the basket currency, it isn't presented.

Express checkout buttons are only rendered when applicable for the shopper. If the shopper isn't using a supported device or operating system, or hasn't configured them to use the available express checkout buttons, then no button is presented.

## Example

In this example, `<script>` code is injected by `<ispayment>` to render all payment methods and express checkout buttons that are configured with Salesforce Payments on the site. The ID of the component is “payment” and the CSS class name where the component is to be rendered is “payment-element”.

**note:** The B2C Commerce script code that creates the `SalesforcePaymentRequest` object can be placed in a controller. `<isscript>` is used here as an example.

```
<isscript>
var SalesforcePaymentRequest = require('dw/extensions/payments/SalesforcePaymentRequest');
var paymentRequest = new SalesforcePaymentRequest('payment', '.payment-element');
</isscript>

<ispayment payment-request="${paymentRequest}"></ispayment>
```

<!-- document id=5942f3fd721404e8da5091361dbe1fe4125548ef697a4d8a8afaf81536b15d9f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-ispaymentmessages.md -->

# ispaymentmessages Element

Injects code to show payment-related messages such as callouts to the shopper about payment methods and available credit options for PayPal, Afterpay, and Klarna. For example, “Pay in 4 interest-free payments of $22.50 with afterpay.”

`<ispaymentmessages>` is used only with Salesforce Payments. An associated payments account must be successfully enabled and payment method configured for use on the storefront site where this element appears.

## Syntax

```
<ispaymentmessages  payment-request = SalesforcePaymentRequest expression \\required
></ispaymentmessages>
```

- payment-request = SalesforcePaymentRequest expression

  - : Specify a `dw.extensions.payments.SalesforcePaymentRequest` as part of an expression for the tag. See [SalesforcePaymentRequest](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_extensions_payments_SalesforcePaymentRequest.html).

## Purpose

The `<ispaymentmessages>` tag injects `<script>` code tag injects `<script>` code that displays messages about the payment method. See [dw.extensions.payments](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/package_dw_extensions_payments.html) to configure the payment methods and to understand how they're rendered.

## Rules of Use

This tag can appear multiple times on the same page with no limit to render payment messages for a product page or a cart page. Payment messages are only rendered when the site is configured to accept payment methods that support them. If a payment method doesn't support messages, they aren’t shown.

To use this element, you need access to the SalesforcePaymentRequest object.

This tag can't be used in a cached template because it's used to display the credit options for the payment method.

## Example

In this example, `<script>` code is injected by `<ispaymentmessages>` to render messages associated with certain payment methods that are configured with Salesforce Payments on the site.

The ID of the component is `paymentrequest-<UUID>-messages` and the CSS class name where the component is to be rendered is `salesforce-payment-messages-element-<UUID>`. UUID is a randomly generated ID.

**note:** The B2C Commerce script code that creates the `SalesforcePaymentRequest` object can be placed in a controller. `<isscript>` is used as an example.

```
<isscript>
var UUIDUtils = require('dw/util/UUIDUtils');
var name = UUIDUtils.createUUID();

var messagesPaymentRequestId = 'paymentrequest-' + name + '-messages';
var messagesElementClass = 'salesforce-payment-messages-element-' + name;

var SalesforcePaymentRequest = require('dw/extensions/payments/SalesforcePaymentRequest');
var messagesPaymentRequest = new SalesforcePaymentRequest(messagesPaymentRequestId, '.' + messagesElementClass);
</isscript>

```

<!-- document id=969de03547587e33a79c5a07e59c347931cc5997b2011768bbf42bdd37e2c33c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isprint.md -->

# isprint Element

`<isprint>` is used to format and encode data for output.

## Syntax

```javascript
<isprint
   value    = output                           \\required
  (style    = style_ID) | (formatter = format) \\one required, but not both
   timezone = "SITE" | "INSTANCE" | "utc"
   padding  = padding_constant
   encoding = "on" | "off" | *context*         \\default is "on"
/>
```

- value = output

  - : _Allowed data type:_ expression only. String isn't allowed

    `output` is an expression that resolves to the text you want to output.

- (style = style_ID) | (formatter = format)

  - : You must include either style or formatter, but not both:

    - style = style_ID

      _Allowed data type:_ string

      `style` specifies a style identifier. Instead of using the style parameter, you can alternatively define a formatter string with the formatter attribute.

    - formatter = format

      _Allowed data type:_ string or expression.

      `formatter` defines a formatting string to control how `<isprint>` outputs expression results. For information on building your own formatter string, refer to Formatting Expression Results (which follows). If formatter is used, style must be omitted.

- timezone = "SITE" | "INSTANCE" | "utc"

  - : - `SITE` lets you print time zones as specified for your site. Defined through the Business Manager via the Site Preferences module, Time Zone section.

    This is the default. If the attribute or value isn't provided, the value for the site is used.

    - `INSTANCE` lets you print time zones as specified for your instance. Defined through the Business Manager via the Global Preferences module, Instance Time Zone Section.
    - `utc` lets you print the date values without time zone conversion.

      In the unique case of _customer.birthday,_ the "utc" time zone reflects the time zone free nature of the date value type. User input for the date attribute is now always interpreted as UTC time in the Business Manager. This timezone value ensures that no time zone conversion occurs for date attributes that are supposed to have no time component. If you require time zone conversion, use the existing value type _datetime_ instead.

Specify a particular time zone for printing dates. This attribute controls whether dates are printed with the instance time zone, the site time zone, or without time zone conversion.

**note:** Time zone identifiers are case insensitive.

Example:

```javascript
<isprint value="${new Date()}" style="DATE_LONG" timezone="SITE">
<isprint value="${new Date()}" style="DATE_LONG" timezone="INSTANCE">
<isprint value="${customer.birthday}" style="DATE_SHORT" timezone="utc"/>
```

- padding = padding_constant

  - : _Allowed data type:_ string or expression.

    `padding_constant` is used only with mail templates, which are templates using `plain` rather than `html` type, to define field width and other spacing issues. For example, when printing a list of product names using a loop statement, you can define a constant field width for every element of the list. The value for padding can be any positive or negative number. The absolute value of `padding_constant` defines the field width. A positive value produces left-aligned output; a negative value produces right-aligned output. If the output string is greater than the field size, the output string is truncated at its right end.

- encoding = "on" | "off" | _context_

  - : Default value is `on`. With this attribute, you can explicitly switch automatic encoding on and off. Salesforce B2C Commerce supports encoding in HTML, XML and WML. Even if encoding is turned off, you an use the `StringUtil` API to encode individual strings.

    A \${} script expression embedded directly into the HTML is similar to the `<isprint/>` tag with encoding on and default styles.

    The _context_ element encodes data to avoid cross-site scripting attacks in areas such as HTML attributes, XML, JavaScript, and JSON. Each value maps to a method in the _SecureEncoder_ Class.

    _context_ can be one of the following values:

    - htmlcontent: encodes a given input for use in a general context.
    - htmlsinglequote: encodes a given input for use in an HTML Attribute guarded by a single quote.
    - htmldoublequote: encodes a given input for use in an HTML Attribute guarded by a double quote.
    - htmlunquote: encodes a given input for use in an HTML Attribute left unguarded.
    - jshtml: encodes a given input for use in JavaScript inside an HTML context.
    - jsattribute: encodes a given input for use in JavaScript inside an HTML attribute.
    - jsblock: encodes a given input for use in JavaScript inside an HTML block.
    - jssource: encodes a given input for use in JavaScript inside a JavaScript source file.
    - jsonvalue: encodes a given input for use in a JSON Object Value to prevent escaping into a trusted context.
    - uricomponent: encodes a given input for use as a component of a URI.
    - uristrict: encodes a given input for use as a component of a URI.
    - xmlcontent: encodes a given input for use in a general XML context.
    - xmlsinglequote: encodes a given input for use in an XML attribute guarded by a single quote.
    - xmldoublequote: encodes a given input for use in an XML attribute guarded by a double quote.
    - xmlcomment: encodes a given input for use in an XML comments.

    These are some examples:

    ```
    <div id="<isprint encoding="htmldoublequote" value="${unsafeData}"/>">
    </div>

    <script type="text/javascript"> var data = "<isprint encoding="jsblock" value="${unsafeData} "/>";
    </script>

    var json = {"trusted_data" : <isprint encoding="jsvalue" value="${unsafeData} "/>};
    return JSON.stringify(json);
    ```

## Purpose

The `<isprint>` tag outputs the result of expressions and template variables. Even though it's possible to output expression results without `<isprint>`, always use it because it contributes to optimizing your template code.

The `<isprint>` tag also takes care of formatting and encoding output strings.

**note:** Encoding is always done after formatting.

## Formatting Expression Results

If the result of an expression appears on an HTML page, first specify how it should be done. For example, a date can be formatted in different ways depending on the store's locale:

- 12 March 1999
- 12.03.1999
- 03/12/99

All formatters are additionally customized by regional settings.

**note:** Objects of classes other than Money, Date, Quantity and Number aren't formatted and the result of formatting these objects isn't standardized.

### Using Styles

Styles are pre-defined formatter strings, which are defined in standard formatter classes. Specify a style via the style attribute of the `<isprint>` tag.

### Money Formatting

This class is used to format the expression results of type Money. The following table shows valid styles.

**note:** Currency symbols are based on the Default Currency, which is set per site, and can be configured in **Administration > Sites > Manage Sites > SiteGenesis - General.**

| Valid Style Identifier | Description                                                        | Example                                    |
| ---------------------- | ------------------------------------------------------------------ | ------------------------------------------ |
| MONEY_SHORT            | Two digits following a decimal separator. No currency symbol.      | Input: 3333 Formatted string: "3,333.00"   |
| MONEY_LONG             | Two digits following a decimal separator. Leading currency symbol. | Input: 3333 Formatted string: "\$3,333.00" |

### Number Formatting

This class is used to format expression results of type Number. The following table lists the valid styles.

| Valid Style Identifier | Description                                              | Example                                       |
| ---------------------- | -------------------------------------------------------- | --------------------------------------------- |
| INTEGER                | No digits after decimal separator. No decimal separator. | Input: 2200.1234 Formatted string: "2,200"    |
| DECIMAL                | Exactly two digits after decimal separator.              | Input: 2200.1234 Formatted string: "2,200.12" |

### Quantity Formatting

This class is used to format expression results of type Quantity. The following table lists the valid styles.

| Valid Style Identifier | Description                                                       | Example                                                                                                                                                                                           |
| ---------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| QUANTITY_SHORT         | 0 to 3 digits after decimal separator. No quantity symbol.        | <ul><li>Input: 3333 kg</li><li>Formatted string: "3,333"</li><li>Input: 3333.1 kg</li><li>Formatted string: "3,333.1"</li><li>Input: 3333.1234 kg</li><li>Formatted string: "3,333.123"</li></ul> |
| QUANTITY_LONG          | 0 to 3 digits after decimal separator. Following quantity symbol. | <ul><li>Input: 3333 kg</li><li>Formatted string: "3,333 kg"</li><li>Input: 3333.1 kg</li><li>Formatted string: "3,333.1 kg"</li><li>Input: 3333.1234 kg</li><li>Formatted string: "3,333.123 kg"  |

Date Formatting

This class is used to format expression results of type Date. The following table lists the valid styles.

| Valid Style Identifier | Description                              | Example                          |
| ---------------------- | ---------------------------------------- | -------------------------------- |
| DATE_SHORT             | Date without clock time in short format. | Formatted string: "9/25/99"      |
| DATE_LONG              | Date without clock time in long format.  | Formatted string: "SEP 25, 1999" |
| DATE_TIME              | Clock time.                              | Formatted string: "7:55:55 PM"   |

### Using the Default Style of a Formatter Class

The default style of a formatter class is used if nothing else has been specified by the user, neither a style, nor a user-defined formatter style. The following table lists the valid styles.

| Data Formatting Type | Default Style  |
| -------------------- | -------------- |
| Money Formatting     | MONEY_LONG     |
| Number Formatting    | DECIMAL        |
| Quantity Formatting  | QUANTITY_SHORT |
| Date Formatting      | DATE_SHORT     |

### Specifying User-defined Formatter Strings

A formatter string is explicitly given by the user via the _formatter_ attribute of `<isprint>`. For more information about valid placeholders, see the B2C Commerce Script API documentation. The following table provides examples of user-defined formatter strings.

| Standard Formatter Class | Example                                                                                                                                                                                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Money Formatting         | <ul><li>Scheme: "\_ #,#00.0#"</li><li>Input: 3</li><li>Formatted string: "$ 03.00"</li><li>Input: 3333.123</li><li>Formatted string: "$ 3,333.12"</li></ul>                                                                                                                                                                      |
| Number Formatting        |                                                                                                                                                                                                                                                                                                                                  |
| Quantity Formatting      | <ul><li>Scheme: "#,#00.0# \_;(-#,#00.0# \*)"</li><li>Input: 3</li><li>Formatted string: "03.0 kg"</li><li>Input: 3333.333</li><li>Formatted string: "3,333.33 kg"</li></ul>                                                                                                                                                      |
| Date Formatting          | <ul><li>Scheme: "EEE, MMM d, 'yy"</li><li>Formatted string: "Wed, July 10, '96"</li><li>Scheme: "h:mm a"</li><li>Formatted string: "12:08 PM"</li><li>Scheme: "K:mm a, z"</li><li>Formatted string: "0:00 PM, PST"</li><li>Scheme: "yyyyy.MMMMM.dd GGG hh:mm aaa"</li><li>Formatted string: "1996.July.10 AD 12:08 PM"</li></ul> |

#### Example

In the following example, the number style, INTEGER is used for the value _sitecount._

```javascript
<isprint value=${pdict.SiteCount} style="INTEGER"/>
```

### Using Formatters

User-defined formatters let you explicitly specify a format via the \<isprint> formatter attribute. You build formatters with placeholders. For example, "\* #,#00.0#", "EEE, MMM d" or "yy".

| Placeholder | Action                                                    |
| ----------- | --------------------------------------------------------- |
| "0"         | Defines required placeholder                              |
| "#"         | Defines option placeholder                                |
| "\*"        | Defines required symbol (for example, currency or weight) |

The following example uses the # placeholder, a page incrementer:

```javascript
<isprint value="${pdict.pagingmodel.start+1}" formatter="#" />
```

The following example uses the placeholders "\* #,#00.0#," which define how decimal places and commas are handled for a list generated by CustomAmount data.

```javascript
<isprint value=${pdict.Custom.Amount} formatter= "* #,#00.0#"/>
```

## Encoding Expression Results

It's possible to use national characters, such as Greek or Cyrillic letters, as well as mathematical symbols and any non-ASCII characters in HTML documents. To make sure that a web browser can interpret and show these characters correctly, they must be encoded using HTML representations. To do this, you must replace characters, such as "\<," ">," or "&" with named character entities as defined in the HTML 4.0 standard or XHTML 1.0/1.1.

Expression output is automatically encoded if the expression is embedded directly in the template or used for an HTML attribute. This ensures that the site isn't subject to cross-site scripting attacks. If the expression is used in an ISML tag attribute, no encoding is applied. Use \<isprint> for more granular control of the expression output especially if the result of the expression is a string that contains a special character.

See the example, which shows the exact string returned by `<isprint>` for a string containing a quote sign. The example assumes that the template variable product:name stores the value Nokia 447X Pro 17" Monitor.

ISML code in template: `<isprint value="${Product.name}">`

generated HTML code: `"Nokia 447X Pro 17&quot; Monitor"`

shown by the browser: `Nokia 447X Pro 17` `" Monitor`

### Example with Deactivation of Encoding

```javascript
<isprint... encoding="off">
```

The default is "on".

### Example

The first example demonstrates how to use \<isprint> to output an expression that returns a string. The returned string is formatted as defined by either the default formatter (first sample), or by using a style (second sample), or by a user-defined formatter string (third sample).

```javascript
<isprint value = "${pdict.Basket.TotalGrossPrice}">
<isprint value = "${pdict.Basket.TotalGrossPrice}" style = "MONEY_SHORT">
<isprint value = "${pdict.Basket.TotalGrossPrice}" formatter = "* #00.0#">
```

The next set of examples show the usage of the padding attribute:

```javascript
<isprint value = "${pdict.product.price}" padding = "-10">
```

string output: " 5.00 USD"

```javascript
<isprint value = "${pdict.product.price}" padding = "+10">
```

string output: "5.00 USD "

```javascript
<isprint value = "#'foolish'#" padding = "+3">
```

string output: "foo"

These examples show usage of the encoding attribute:

```javascript
<isprint value = "${'>new<'}" encoding = "on">
```

string output: "&gt;new&lt;"

```javascript
<isprint value = "${'>new<'}" encoding = "off">
```

string output: ">new\<"

The following example shows a string containing quotation marks, and the corresponding string that is returned by the \<isprint> tag (it's assumed that the template variable product:name has the value Nokia 447X Pro 17" Monitor):

|                     |                                            |
| ------------------- | ------------------------------------------ |
| Tag in the template | \<isprint value="\${pdict.product.price}"> |
| Generated HTML code | "Nokia 447X Pro 17&quot; Monitor"          |
| Browser display     | Nokia 447X Pro 17" Monitor                 |

<!-- document id=4ccf05770317c2415b12e5fd1b79a9a27ae14e7e79634c9e6eabb18b1d5c5d1d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isredirect.md -->

# isredirect Element

Redirect the browser to a specified URL.

## Syntax

```
<isredirect
  location  = target_url        \\required
  permanent = "true" | "false"  \\false is default
>
```

- location = target_url

  - : _Allowed data type:_ string or expression.

    `target_url` specifies a target URL used by the browser to send a new request.

- permanent = "true" | "false"

  - : `false` is the default

    _Allowed data type:_ string or expression.

    - `true` causes the system to generate an HTTP 301 response code.
    - `false` causes system to generate an HTTP 302 response code.

**note:** If the permanent attribute isn't provided, `false` is the default .

## Purpose

**note:** `<isredirect>` appears before `<iscache>` in templates, because it clears the response created up to that point.

## Example

The following example checks whether the buyer has enabled cookies in their browser or not. Depending on the result, the browser is redirected.

```
<isif condition = "${request.httpCookies['UserID']}">
    <isredirect location="${URLUtils.url('LoginPanel-Start')}" permanent="false">
    <iselse>
<!--- cookies are not enabled --->
</isif>
```

Some browsers don't support redirect from HTTP to HTTPS. In such a case use the HTML meta tag "refresh", for example:

```
<html>
<head>
<meta http-equiv="refresh" content="0; URL='${URLUtils.url(...)}'">
```

<!-- document id=fca47197fc88ef480739f46a97468f62b7c27ef06f00e74eec225a9e2f82e9f0 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isremove.md -->

# isremove Element

`<isremove>` supports removing a variable in much the same way that `<isset>` supports defining a variable.

## Syntax

```
<isremove
  name  = var_name \\required
  scope = "session" | "request" | "page"
>
```

- name = var_name

  - : `var_name` is the name of the variable to be removed.

- scope = "session" | "request" | "page"

  - : `var_name` is the name of the variable to be removed.

    - session specifies that variables are available across multiple requests within a session.
    - pdict specifies that variables are available via the Pipeline Dictionary.
    - request specifies that variables are available via the current internal Salesforce B2C Commerce request.
    - page specifies that variables are available on the current ISML page.

**note:** The `pdict` variable has been deprecated. Instead, use request.

<!-- document id=964bc0b2dd6c35ade39be6612724015e02c15c12b2ff2d4b577537021b1b8fcf url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isreplace.md -->

# isreplace Element

The decorator template uses `<isreplace/>` to identify where the decorated content is to be included.

## Syntax

```
<isreplace/>
```

## Purpose

Typically, only one `<isreplace/>` tag is used in the decorator template. However, multiple or zero `<isreplace/>` tags can also be used.

- If the decorating template doesn't have an `<isreplace/>` tag, the decorated content is, effectively, omitted from the resultant output.
- If the decorator template has multiple `<isreplace/>` tags, the content to be decorated is included for each `<isreplace/>` tag.

## Example 1: Rendering Template that Uses Decorator

```
<isset name="DecoratorTemplate" value="folder/pt_mytype" scope="page"/>
<isdecorate template="${DecoratorTemplate}">
    ...content...
</isdecorate>
```

In this example, the page contents of the main portion of the browser are inserted into the HTML file.

## Example 2: Decorator Template

```
<body>
  <div id="pt_mytype">
    <div id="container">
      <div id="main">
        <div id="content">
	  <isreplace/>
	  </div>
      </div> <!-- end main -->
      <isinclude template="components/template">
    </div> <!-- end container -->
  </div> <!-- end pt_mytype -->
</body>
```

<!-- document id=25adb7a146eb607c332dad4afdf17ddf8aa00b7bab1cc1c5cdae06d02d7514e9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isscript.md -->

# isscript Element

Support server-side scripts for scriptlets and inline script expressions, using `${ }`syntax.

## Syntax

```
<isscript>
  ...
</isscript>
```

## Purpose

The script expressions are supported everywhere expressions are supported, including in tags and inline.

These are the top-level variables available to scriptlets:

| Variable | Description                                          | See Also                     |
| -------- | ---------------------------------------------------- | ---------------------------- |
| session  | The current internal Salesforce B2C Commerce session | dw.system.Session            |
| request  | The current internal B2C Commerce request            | dw.system.Request            |
| pdict    | The current Pipeline Dictionary                      | dw.system.PipelineDictionary |
| out      | PrintWriter for the HTML page                        | dw.io.Printwriter            |

Variables set in the template script context are one of two types with respect to their scope:

| Variable   | Scope                                                                                                                                                                                                                                                                                             |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page scope | These are either well-known variables set by the template at run time or those defined in the scriptlet. Variables of this scope are available, once set, through template execution context and can be referenced from multiple scriptlets or expressions in the template or its local includes. |
| Tag scope  | Variables of this type are defined within certain tags. For example, `<isloop... status="safe"/>` defines variable safe of type. Tag scoped variables are available, once declared, in the tag context only.                                                                                      |

## Example

```

<isscript>
        var user = pdict.User;
	  var fullName = user.firstName + " " + user.lastName;
</isscript>

```

Multiple script snippets in one file share the same execution context:

```

<isscript>
        var user = pdict.User;
</isscript>
...
<isscript>
	var fullName = user.firstName + " " + user.lastName;
</isscript>
<isprint value="${fullName}" />

```

<!-- document id=b765f7a7f1c672131a618ebe1f31db9fbbd1ee85f4dad091caf2fdaae58b2bcc url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isselect.md -->

# isselect Element

Implementdrop-down list boxes in an HTML form.

## Syntax

```
<isselect
  name        = simple_name       \\required
  iterator    = loop_var          \\required
  description = box_text          \\required
  value       = text_value        \\required
  condition   = "true" | "false"
  encoding    = "on" | "off"
/>
```

- name = simple_name

  - : _Allowed data type:_ string or expression.

    `simple_name` is a name for your list box. Note that the name you specify here is used when the browser sends the user selection as a key-value pair to the server. Therefore, the specified name must be equal to the input parameter required by the pipeline that processes the form values.

- iterator = loop_var

  - : `loop_var` specifies a loop variable. All elements of the loop variable are added to the list box.

- description = box_text

  - : `box_text` is text that is shown in the drop-down list box.

- value = text_value

  - : `text_value` is text sent back by the browser to the server as the value of a key-value pair. This can be used, for example, to return an internal product ID instead of the product name shown in the drop-down list box. The string specified by value is stored in the pipeline dictionary. The appropriate key is determined by the `<isselect>` attribute name.

- condition = "true" | "false"

  - : _Allowed data type:_ expression. String is not allowed.

    If condition is true, the appropriate list element is preselected. This has its counterpart in the selected attribute of the `<option>` HTML tag. Make sure that only one list element matches the condition to avoid undefined results in the browser.

- encoding = "on" | "off"

  - : _Allowed data type:_ expression. String is not allowed.

    Default value is `on`. With this attribute you can explicitly switch automatic HTML encoding of the output on and off. Encoding means converting any special characters, such as `<,` `>`, `&`, `"`, as well as the named characters of the HTML 3.2 (Unicode 160-255) into their HTML counterparts. For example, the character `>` is converted to the string `&gt;`.

## Purpose

`<isselect>` replaces the HTML tag `<select>` and its supporting tags. With the iterator attribute you can specify an iterator, whose elements appear in the list box. One element in the list box can be preselected by specifying a condition with the condition attribute. Make sure that the specified condition evaluates to true for only one element of the list, otherwise the browser might not show the list properly.

## Example

In this example, `<isselect>` adds all elements of the iterator to an HTML list box that is generated.

```
<form action =... >
<isselect name = "PaymentMethodUserSelection"
iterator = "${PaymentMethodChoices}"
condition = "${PaymentMethod == PaymentMethodChoices}"
value = "${PaymentMethodChoices.UUID}"
description = "${PaymentMethodChoices.description}">
...
</form>
```

<!-- document id=2a89af84d97df2f284c386fc751731033d487fef838ce5f61610d22cd10e2ffc url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isset.md -->

# isset Element

Define and set a user-defined variable.

## Syntax

```
<isset
  name  = var_name                   \\required
  value = var_value                  \\required
  scope = "session"|"request"|"page" \\required
/>
```

- name = var_name

  - : _Allowed data type:_ expression or string.

    `var_name` specifies the name of a user-defined variable. The rules for naming user-defined variables are:

    - The identifier must start with a letter (a-z, A-Z).
    - Any following character can be a letter, number, or underscore.
    - User-defined variables are case-sensitive.

- value = var_value

  - : `var_value` specifies a value to be stored in the variable. It can be any value.

- scope = "session"|"request"|"page"

  - :

    - `session` variables are available across multiple requests within a session.
    - `request` variables are available for the current internal Salesforce B2C Commerce request. The `request` variable isn't available for multiple requests, so it isn't available after an interaction continue node.
    - `page` variables are available for the current ISML page.

    The default scope is the session.

    The `pdict` variable is deprecated. Instead, use the `scope="request"` variable. The `pdict` variable isn't available for multiple requests, so it isn't available after an interaction continue node.

## Purpose

In B2C Commerce, every user-defined variable is of a specific scope, which defines the visibility and lifetime of the variable. B2C Commerce distinguishes between user-defined variables of the request, pdict, session and page scope.

Scope session means that the variable is accessible to all templates during a particular storefront session. The lifetime of a session variable ends with a session. A session variable can be used in expressions`.`

The first occurrence of `<isset>` in a template declares and sets the variable, there is no other special tag needed for declaration. If the variable already exists, `<isset>` resets it to the specified value.

**note:** If no scope is set when setting the variable, the scope is set to session.

## Examples: Using Isset to Create a Custom Variable

Example 1

This example shows how `<isset>` is used to define and initialize the variable color. The value of color is the string #A0CC99.

```
<isset name="color" value="${'#A0CC99'}">
```

Example 2

If a variable was already defined by a former `<isset>` tag (first line), a second `<isset>` resets the value of the variable (second line).

```
<isset name="counter" value="${0}" >
<isset name="counter" value="${counter + 1}">
```

Example 3

In this example `<isloop>` is used to get products from the Pipeline Dictionary.

```
<isloop iterator="${pdict.ProductPagingModel.pageElements}" alias="LoopProduct" begin="0" end="2">
```

Example 4

This example shows how `<isset>` assigns the value of LoopProduct to Product.

```
<isset name="Product" value="${LoopProduct}" scope="request">
```

You can also manipulate a value, as shown here:

```
<isset name="brandsPerCol" value="${Math.floor(numOfBrands/4) + 1}" scope="page">
```

You can print the value with `<isprint>`.

See [isremove](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-isremove.md).

## Examples: Accessing Custom Variables

Example 1: Accessing the Page Scope

In this example, `isset` sets the decorator template to `pt_empty` if the `pdict` format attribute is set to ajax and to the `pt_account` template if it's not. The DecoratorTemplate variable that is set is accessed by `${DecoratorTemplate}`.

```
<isset name="DecoratorTemplate" value="account/pt_account" scope="page"/>
<isif condition="${pdict.CurrentHttpParameterMap.format.stringValue == 'ajax' || pdict.CurrentHttpParameterMap.pwr.stringValue == 'true' || pdict.CurrentHttpParameterMap.source.stringValue == 'search' || pdict.CurrentHttpParameterMap.source.stringValue == 'quickview' || pdict.CurrentHttpParameterMap.source.stringValue == 'cart'}">
	<isset name="DecoratorTemplate" value="util/pt_empty" scope="page"/>
</isif>

<isdecorate template="${DecoratorTemplate}">
```

<!-- document id=762aedb42bc9037cef0a654aa55f7d122611307bbf2c7f423a4d5ace047ada37 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isslot.md -->

# isslot Element

Use a placeholder where content should appear.

## Syntax

```
<isslot
  id             = id                                 \\required
  context        = "global" | "category" | "folder"   \\required
  context-object = context-object                     \\required for category or folder context
  description    = description                        \\required
  preview-url    = url                                \\optional for category or folder context
>
```

- id = id

  - : _Allowed data type:_ string. Expressions aren't allowed.

    `id` identifies the slot in a slot configuration.

- context = "global" | "category" | "folder"

  - : Scope of the slot:

    - `global` sets the scope to every page on the site.
    - `category` corresponds to a specific category landing page.
    - `folder` corresponds to a specific content folder.

- context-object = context-object

  - : _Allowed data type:_ Expressions only.

    `context_object` is an expression that evaluates to a single category or folder object for category or folder scopes. For global scope, this can also evaluate to a single product object, a single basket object, or a collection (`dw.util.Collection`) of up to five products.

- description = description

  - : _Allowed data type:_ string. Expressions aren't allowed.

    `description` describes the slot for the business user who needs to configure it.

- preview-url = url

  - : `url` identifies the URL used within Business Manager to preview the content slot. It you don't specify a value, a default URL is used.

## Purpose

The `id` attribute is used by Business Manager to identify the slot in one or more slot configurations. The `context` attribute specifies the scope of the slot. The `context-object` attribute is required when the scope of the `context` attribute is either `category` or `folder`. The `context-object` attribute is used to lookup the slot configuration for the given slot. It is also used for [Einstein Product Recommendations (Trailhead)](https://trailhead.salesforce.com/content/learn/modules/cc-einstein-product-recommendations) and enables product recommendations based on a single product, a single category, a single folder, a single basket, or a collection of up to five products. Use the `description` attribute to describe the slot.

In Business Manager, slots are grouped by context scope. Global slots are grouped together, category slots are grouped together, and folder slots are grouped together.

For _Global_ slots, Business Manager shows the following values:

- Slot ID
- Description
- Number of slot configurations created

For _Category_ slots, Business Manager shows the following values:

- Category (assuming the category's configuration specifies a template that includes the `<isslot>` tag)
- Category name
- Rendering template name
- Slot ID
- Description
- Number of slot configurations created

For _Folder_ slots, Business Manager shows the following values:

- Folder ID (assuming the folder's configuration specifies a template that includes the `<isslot>` tag)
- Folder name
- Rendering template name
- Slot ID
- Description
- Number of slot configurations created

When no slot is defined in the database for a given slot ID, the `<isslot>` tag doesn't render any content. An entry is written to the log file to identify this occurrence.

## Examples

In this first example, the `<isslot>` tag references the homepage banner and specifies the _global_ context:

```
<isslot id="homepage_banner" description="Home banner 705px x 356px." context="global" />
```

In this next example, the `<isslot>` tag specifies the _category_ context:

```
<isslot id="category_top_featured" context="category" description="Category page top slot."
context-object="${pdict.ProductSearchResult.category}">
```

In this last example, the `<isslot>` tag specifies the _folder_ context:

```
<isslot id="fldr-landing-slotbanner" context="folder" description="Large Folder Landing Banner"
context-object="${pdict.ContentSearchResult.folder}"/>
```

## Using the Slotcontent Variable

The `slotcontent` variable is a TopLevel class system variable that provides access to the public class `dw.campaign.SlotContent`. This class provides access to slotting information. The following shows the mapping between the variable and the methods of this class:

| dw.campaign.SlotContent   | Template implicit objects |
| ------------------------- | ------------------------- |
| getContent() : Collection | slotcontent.content       |
| getSlotID() : String      | slotcontent.slotID        |
| getCallout() : MarkupText | slotcontent.callout       |
| getCustom() : Map         | slotcontent.custom        |

### Examples

In this first example, the rendering template shows products when the results of a slot execution returns a _product_ slot content type. The `slotcontent` variable is predefined in the `TopLevel.global` class and provides access to the SlotContent object. It's available only in ISML templates that are defined as a slot's template.

```
<isif condition="${!empty(slotcontent)}">
    <div class="product">
        <isloop iterator="${slotcontent.content}" alias="product">
            <isprint value="${product.SKU}"><br />
            <isprint value="${product.Name}"><br />
        </isloop>
    </div>
</isif>
```

In this next example, the template shows content assets when the results of a slot execution return a _content asset_ slot content type.

```
<isif condition="${!empty(slotcontent)}">
    <div class="assetlisting">
        <isloop iterator="${slotcontent.content}" alias="asset">
            <isif condition="${asset != null}">
                <div class="asset">
                    <div class="name">
                        <a href="${URLUtils.url('Page-Show','cid', asset.ID)}">
                            <isprint value="${asset.name}">
                        </a>
                    </div>
                </div>
            </isif>
        </isloop>
    </div>
</isif>
```

As this next example shows, you can also check if the `slotcontent` variable has anything in it at all, prior to pulling the information from it, as in the following example:

```
<isif condition="${slotcontent != null}">
<isloop items="${slotcontent.content}" var="contentAsset">
```

In this last example, the template shows products when the result of the Slot Execution returns `Slot Content Type = Product`.

```
<div class="product_1x2">
  <isloop iterator="${slotcontent.content}" alias="product" begin="0" end="1">
  <isset name="Product" value="${product}" scope="PDICT" />
  <div class="product_1x2_slot">
    <div class="image">
      <a title="${Resource.msg('components.common-details.001','components',null)}"  href="${URLUtils.http('Product-Show','pid', product.ID)}"><img src="${product.image.url}"
        alt="${Resource.msg​('components.image-thumbnail.001',​'components',null)}${product.name}" /></a>
    </div>
    <div class="productdetails">
      <h3><a title="${Resource.msg('components.common-details.001','components',null)}"  href="${URLUtils.http('Product-Show','pid', product.ID)}"><isprint value="${product.name}"></a></h3>
        <isinclude template="product/components/pricing">
    </div>
    <div class="clear"><!--  FLOAT CLEAR --></div>
    </div>
  </isloop>
    <div class="clear"><!--  FLOAT CLEAR --></div>
    </div>The following template shows content assets when the results of the Slot Execution returns Slot Content Type = Content Asset.
<iscontent type="text/html" charset="UTF-8" compact="true">

<!--- make sure we have an asset at all --->
<isif condition="${slotcontent != null}">
  <isloop iterator="${slotcontent.content}" alias="contentAsset">
    <isprint value="${contentAsset.custom.body}" encoding="off"/>
  </isloop>
</isif>
```

<!-- document id=1c448d6162717c9f832c5f9c80bf8d255a4c1fdd52605a8b40f2ec04f8e2e9d3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-isstatus.md -->

# isstatus Element

Set the HTTP response status code.

## Syntax

```
<isstatus
 value = http_code \\required
/>
```

- value = http_code

  - : _Allowed data type:_ string or expression.

    `http_code` identifies the HTTP response code. This must be an integer.

## Example

The following sets the response status code to 307, which indicates that the requested resource resides temporarily under a different URI.

```
<isstatus value="307"/>
```

The following sets the response status code to 410, one of the few error codes for which pages are cached in the Salesforce B2C Commerce Web Server.

```
<isstatus value="410"/>
```

**note:** Explicitly supported REDIRECT and GONE are also cached. This means that responses with the response status code 301 (indicating that the resource has permanently moved to a new location), 302 (indicating that the resource has temporarily moved to another location) and 410 (indicating that the resource is no longer available at the server and no forwarding address is known) are also cached by the WebAdapter.

<!-- document id=0a433baff16e85be08f60b48a6afbbb2e365781645163382753771dd01c213ac url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/jobs.md -->

Jobs

# Jobs

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/jobs/jobs-oas-v1-public.yaml)

## API Overview

The Jobs API provides endpoints for managing and monitoring job executions within Salesforce Commerce Cloud.

### Overview

This API allows administrators to search for job executions, trigger new job runs, retrieve execution details, and abort running jobs. Jobs represent scheduled or on-demand tasks that perform operations such as data import/export, indexing, and cleanup.

### Key Features

*   **Job Execution Search**: Use complex queries to search for job executions by various attributes
*   **Job Triggering**: Create new job executions to run jobs on demand
*   **Execution Monitoring**: Retrieve detailed information about job executions including step-level details
*   **Job Abort**: Delete or abort running job executions

### Searchable Attributes

The following attributes can be used in search queries:

*   `id`: The unique identifier of the job execution (String)
*   `jobId`: The identifier of the job (String)
*   `status`: The execution status (String)
*   `startTime`: The start time of the execution (DateTime)
*   `endTime`: The end time of the execution (DateTime)

### Sortable Attributes

Search results can be sorted by:

*   `id`: Sort by execution identifier
*   `jobId`: Sort by job identifier
*   `status`: Sort by execution status
*   `startTime`: Sort by start time
*   `endTime`: Sort by end time

### Use Cases

*   **Monitoring**: Track job execution status and progress
*   **Troubleshooting**: Investigate failed job executions and review step details
*   **Automation**: Trigger job executions programmatically
*   **Reporting**: Generate reports on job execution history and performance

### Authentication

This API requires OAuth 2.0 authentication with the appropriate scopes:

*   `sfcc.jobs` - Read access to job resources
*   `sfcc.jobs.rw` - Read and write access to job resources

### Best Practices

1.  Use specific search queries to find job executions efficiently
2.  Monitor long-running jobs by polling the get execution endpoint
3.  Use pagination for large result sets when searching executions
4.  Check execution status before attempting to abort a job
5.  Review step execution details for debugging failed jobs

**Version:** 1.0.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/operation/jobs/v1`
    *   `shortCode (default 123456gf)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 security scheme for Admin API access using Account Manager. Requires appropriate scopes for job management operations.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.jobs: Read access to job resources
    *   Scope sfcc.jobs.rw: Read and write access to job resources

## Operations

### POST Search Job Executions

`POST /organizations/{organizationId}/job-execution-search`

Operation ID: `searchJobExecutions`. Security: AmOAuth2 (sfcc.jobs, sfcc.jobs.rw).

Searches for job executions.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   id - String
*   jobId - String
*   status - String
*   startTime - DateTime
*   endTime - DateTime

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
*   jobId - String
*   status - String
*   startTime - DateTime
*   endTime - DateTime

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

The search request document for job executions

Media type: `application/json`. Schema: `JobExecutionSearchRequest`.

_Example: SearchByJobId_ Search job executions by job ID

Example of searching for job executions by their job ID using a term query

```
{
  "query": {
    "termQuery": {
      "fields": [
        "jobId"
      ],
      "operator": "is",
      "values": [
        "my-custom-job"
      ]
    }
  },
  "limit": 10,
  "offset": 0
}
```

_Example: SearchByStatus_ Search job executions by status

Example of searching for job executions by their execution status

```
{
  "query": {
    "termQuery": {
      "fields": [
        "status"
      ],
      "operator": "is",
      "values": [
        "running"
      ]
    }
  },
  "limit": 25,
  "offset": 0,
  "sorts": [
    {
      "field": "startTime",
      "sortOrder": "desc"
    }
  ]
}
```

_Example: SearchByStartTime_ Search job executions by start time range

Example of searching for job executions within a specific start time range using a bool query

```
{
  "query": {
    "boolQuery": {
      "must": [
        {
          "termQuery": {
            "fields": [
              "status"
            ],
            "operator": "is",
            "values": [
              "finished"
            ]
          }
        },
        {
          "textQuery": {
            "fields": [
              "jobId"
            ],
            "searchPhrase": "export"
          }
        }
      ]
    }
  },
  "limit": 20,
  "offset": 0,
  "sorts": [
    {
      "field": "startTime",
      "sortOrder": "desc"
    }
  ]
}
```

#### Responses

*   **200** Returns job execution search results
    
    Media type: `application/json`. Schema: `JobExecutionSearchResult`.
    
    _Example: JobExecutionSearchResultSuccess_ Successful job execution search result
    
    Example of a successful job execution search returning multiple results
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "query": {
        "textQuery": {
          "fields": [
            "jobId"
          ],
          "searchPhrase": "JobExecutionTestJob1"
        }
      },
      "hits": [
        {
          "id": "1",
          "jobId": "JobExecutionTestJob1",
          "jobDescription": "Test job for WAPI",
          "clientId": "scapi",
          "status": "OK",
          "executionStatus": "finished",
          "startTime": "2026-02-24T13:47:23.249Z",
          "endTime": "2026-02-24T13:47:23.420Z",
          "creationDate": "2026-02-24T13:47:23.000Z",
          "duration": 171,
          "effectiveDuration": 92,
          "modificationTime": "2026-02-24T13:47:23.433Z",
          "executedServerId": "192.168.1.2-0",
          "executionScopes": [
            "Organization",
            "TestWapi-Customization"
          ],
          "exitStatus": {
            "code": "OK",
            "status": "ok"
          },
          "statusMetadata": {
            "clientId": "scapi",
            "reason": "Completed successfully",
            "userLogin": "admin"
          },
          "isLogFileExisting": true,
          "isRestart": false,
          "logFilePath": "/Sites/LOGS/jobs/JobExecutionTestJob1/Job-JobExecutionTestJob1-02c585c2a242c8eee74bd1ba51.log",
          "parameters": [
            {
              "name": "SiteScope",
              "value": "{\"all_storefront_sites\":true}"
            }
          ],
          "stepExecutions": [
            {
              "id": "4",
              "stepId": "Step1",
              "stepDescription": "A step that executes a pipeline that can be configured via a parameter",
              "stepTypeId": "ExecutePipeline",
              "stepTypeInfo": "TestWAPIJobPipeline-StartEnd",
              "executionScope": "Organization",
              "executionStatus": "finished",
              "status": "OK",
              "startTime": "2026-02-24T13:47:23.311Z",
              "endTime": "2026-02-24T13:47:23.332Z",
              "duration": 21,
              "modificationTime": "2026-02-24T13:47:23.332Z",
              "isChunkOriented": false,
              "exitStatus": {
                "code": "OK",
                "message": "",
                "status": "ok"
              }
            },
            {
              "id": "5",
              "stepId": "Step2",
              "stepDescription": "A step that executes a script module function that can be configured via a parameter",
              "stepTypeId": "ExecuteScriptModule",
              "stepTypeInfo": "test_bc_wapi/cartridge/scripts/test/schedulejob/testScriptModuleStep.ds#execute",
              "executionScope": "Organization",
              "executionStatus": "finished",
              "status": "OK",
              "startTime": "2026-02-24T13:47:23.337Z",
              "endTime": "2026-02-24T13:47:23.359Z",
              "duration": 22,
              "modificationTime": "2026-02-24T13:47:23.359Z",
              "isChunkOriented": false,
              "exitStatus": {
                "code": "OK",
                "message": "",
                "status": "ok"
              }
            }
          ]
        },
        {
          "id": "0",
          "jobId": "JobExecutionTestJob1",
          "jobDescription": "Test job for WAPI",
          "clientId": "scapi",
          "status": "ERROR",
          "executionStatus": "finished",
          "startTime": "2026-02-24T13:46:24.316Z",
          "endTime": "2026-02-24T13:46:25.084Z",
          "creationDate": "2026-02-24T13:46:24.000Z",
          "duration": 768,
          "effectiveDuration": 143,
          "modificationTime": "2026-02-24T13:46:25.101Z",
          "executedServerId": "192.168.1.2-0",
          "executionScopes": [
            "Organization"
          ],
          "exitStatus": {
            "code": "ERROR",
            "message": "Job failed due to an import error.",
            "status": "error"
          },
          "isLogFileExisting": true,
          "isRestart": false,
          "logFilePath": "/Sites/LOGS/jobs/JobExecutionTestJob1/Job-JobExecutionTestJob1-21a391164b090c6c12957a292e.log",
          "retryInformation": {
            "currentRetryAttempt": 1,
            "maxRetries": 3
          },
          "stepExecutions": [
            {
              "id": "0",
              "stepId": "Step1",
              "stepDescription": "A step that executes a pipeline that can be configured via a parameter",
              "stepTypeId": "ExecutePipeline",
              "stepTypeInfo": "TestWAPIJobPipeline-StartEnd",
              "executionScope": "Organization",
              "executionStatus": "finished",
              "status": "ERROR",
              "startTime": "2026-02-24T13:46:24.920Z",
              "endTime": "2026-02-24T13:46:25.084Z",
              "duration": 164,
              "modificationTime": "2026-02-24T13:46:25.084Z",
              "isChunkOriented": true,
              "chunkSize": 100,
              "itemWriteCount": 42,
              "itemFilterCount": 3,
              "totalItemCount": 500,
              "statusMetadata": {
                "clientId": "scapi",
                "reason": "Import file not found",
                "userLogin": "admin"
              },
              "exitStatus": {
                "code": "ERROR",
                "message": "Import file not found",
                "status": "error"
              }
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad Request - Malformed search query or invalid parameters
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MalformedSearchParameter_ Malformed search query
    
    Example of an error when the search query is malformed or invalid
    
    ```
    {
      "title": "Malformed Search Parameter",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-search-parameter",
      "detail": "The search query contains invalid syntax. Please check the query structure and try again."
    }
    ```
    
    _Example: UnqueryableField_ Unqueryable Field
    
    Example of an error when an invalid field name is used in the search query
    
    ```
    {
      "title": "Unqueryable Field",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "detail": "The field 'invalid_field' is not a searchable attribute for job executions. Valid fields are: id, jobId, status, startTime, endTime."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user."
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Your access token is valid, but you don’t have the required permissions to access the resource."
    }
    ```
    

### POST Create Job Execution

`POST /organizations/{organizationId}/jobs/{jobId}/executions`

Operation ID: `createJobExecution`. Security: AmOAuth2 (sfcc.jobs.rw).

Creates a new execution for the specified job. This effectively triggers the job to run. The response contains the details of the newly created job execution.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `jobId` (path, string, required) The identifier of the job.  
    Minimum length: 1. Maximum length: 256. Example: `my-custom-job`.

#### Request body

Optional request body to provide execution parameters

Media type: `application/json`. Schema: `JobExecutionRequest`.

_Example: CreateJobExecution_ Create a job execution with parameters

Example of creating a new job execution with custom parameters

```
{
  "parameters": [
    {
      "name": "exportFormat",
      "value": "XML"
    },
    {
      "name": "targetFolder",
      "value": "/export/catalog"
    }
  ]
}
```

#### Responses

*   **200** The job execution was successfully created
    
    Media type: `application/json`. Schema: `JobExecution`.
    
    _Example: JobExecutionCreated_ Newly created job execution
    
    Example of a successfully created job execution (response from POST)
    
    ```
    {
      "id": "3",
      "jobId": "ScapiParamTest",
      "jobDescription": "SCAPI parameter test job",
      "clientId": "scapi",
      "status": "pending",
      "executionStatus": "pending",
      "isLogFileExisting": false,
      "isRestart": false,
      "duration": 0,
      "modificationTime": "2026-02-24T14:04:45.081Z",
      "startTime": "2026-02-24T14:04:45.081Z",
      "parameters": [
        {
          "name": "GlobalParam1",
          "value": "OverriddenValue1"
        }
      ]
    }
    ```
    
*   **400** Bad Request - Invalid job execution request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidJobExecutionRequest_ Invalid job execution request
    
    Example of an error when the job execution request is invalid
    
    ```
    {
      "title": "Invalid Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-request",
      "detail": "The job execution request is invalid. Please check the request body and try again."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as POST /organizations/{organizationId}/job-execution-search 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as POST /organizations/{organizationId}/job-execution-search 403 response._
    
*   **404** Job not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: JobNotFound_ Job not found
    
    Example of an error when the specified job does not exist
    
    ```
    {
      "title": "Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "detail": "The job with ID 'nonexistent-job' was not found."
    }
    ```
    

### GET Get Job Execution

`GET /organizations/{organizationId}/jobs/{jobId}/executions/{executionId}`

Operation ID: `getJobExecution`. Security: AmOAuth2 (sfcc.jobs, sfcc.jobs.rw).

Retrieves the details of a specific job execution identified by its execution ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `jobId` (path, string, required) The identifier of the job.  
    Minimum length: 1. Maximum length: 256. Example: `my-custom-job`.
*   `executionId` (path, string, required) The identifier of the job execution.  
    Minimum length: 1. Maximum length: 256. Example: `exec-001`.

#### Responses

*   **200** Returns the job execution details
    
    Media type: `application/json`. Schema: `JobExecution`.
    
    _Example: JobExecutionDetails_ Job execution with step details
    
    Example of a completed job execution with step execution details (response from GET)
    
    ```
    {
      "id": "1",
      "jobId": "JobExecutionTestJob1",
      "jobDescription": "Test job for WAPI",
      "clientId": "scapi",
      "status": "OK",
      "executionStatus": "finished",
      "startTime": "2026-02-24T13:47:23.249Z",
      "endTime": "2026-02-24T13:47:23.420Z",
      "creationDate": "2026-02-24T13:47:23.000Z",
      "duration": 171,
      "effectiveDuration": 92,
      "modificationTime": "2026-02-24T13:47:23.433Z",
      "executedServerId": "192.168.1.2-0",
      "executionScopes": [
        "Organization",
        "TestWapi-Customization"
      ],
      "exitStatus": {
        "code": "OK",
        "status": "ok"
      },
      "isLogFileExisting": true,
      "isRestart": false,
      "logFilePath": "/Sites/LOGS/jobs/JobExecutionTestJob1/Job-JobExecutionTestJob1-02c585c2a242c8eee74bd1ba51.log",
      "parameters": [
        {
          "name": "SiteScope",
          "value": "{\"all_storefront_sites\":true}"
        }
      ],
      "stepExecutions": [
        {
          "id": "4",
          "stepId": "Step1",
          "stepDescription": "A step that executes a pipeline that can be configured via a parameter",
          "stepTypeId": "ExecutePipeline",
          "stepTypeInfo": "TestWAPIJobPipeline-StartEnd",
          "executionScope": "Organization",
          "executionStatus": "finished",
          "status": "OK",
          "startTime": "2026-02-24T13:47:23.311Z",
          "endTime": "2026-02-24T13:47:23.332Z",
          "duration": 21,
          "modificationTime": "2026-02-24T13:47:23.332Z",
          "isChunkOriented": false,
          "exitStatus": {
            "code": "OK",
            "message": "",
            "status": "ok"
          }
        },
        {
          "id": "5",
          "stepId": "Step2",
          "stepDescription": "A step that executes a script module function that can be configured via a parameter",
          "stepTypeId": "ExecuteScriptModule",
          "stepTypeInfo": "test_bc_wapi/cartridge/scripts/test/schedulejob/testScriptModuleStep.ds#execute",
          "executionScope": "Organization",
          "executionStatus": "finished",
          "status": "OK",
          "startTime": "2026-02-24T13:47:23.337Z",
          "endTime": "2026-02-24T13:47:23.359Z",
          "duration": 22,
          "modificationTime": "2026-02-24T13:47:23.359Z",
          "isChunkOriented": false,
          "exitStatus": {
            "code": "OK",
            "message": "",
            "status": "ok"
          }
        },
        {
          "id": "6",
          "stepId": "Step3 - Step1",
          "stepDescription": "A step that executes a pipeline that can be configured via a parameter",
          "stepTypeId": "ExecutePipeline",
          "stepTypeInfo": "TestWAPIJobPipeline-StartEnd",
          "executionScope": "TestWapi-Customization",
          "executionStatus": "finished",
          "status": "OK",
          "startTime": "2026-02-24T13:47:23.364Z",
          "endTime": "2026-02-24T13:47:23.387Z",
          "duration": 23,
          "modificationTime": "2026-02-24T13:47:23.387Z",
          "isChunkOriented": false,
          "includeStepsFromJobId": "JobExecutionTestJob2",
          "exitStatus": {
            "code": "OK",
            "message": "",
            "status": "ok"
          }
        },
        {
          "id": "7",
          "stepId": "Step3 - Step2",
          "stepDescription": "",
          "stepTypeId": "ExecuteScriptModule",
          "stepTypeInfo": "test_bc_wapi/cartridge/scripts/test/schedulejob/testScriptModuleStep.ds#testReturnStatusOkWithCodeAndMessage",
          "executionScope": "TestWapi-Customization",
          "executionStatus": "finished",
          "status": "SUCCESS",
          "startTime": "2026-02-24T13:47:23.392Z",
          "endTime": "2026-02-24T13:47:23.418Z",
          "duration": 26,
          "modificationTime": "2026-02-24T13:47:23.418Z",
          "isChunkOriented": false,
          "includeStepsFromJobId": "JobExecutionTestJob2",
          "exitStatus": {
            "code": "SUCCESS",
            "message": "Step was successful!",
            "status": "ok"
          }
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as POST /organizations/{organizationId}/job-execution-search 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as POST /organizations/{organizationId}/job-execution-search 403 response._
    
*   **404** Job execution not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: JobExecutionNotFound_ Job execution not found
    
    Example of an error when the specified job execution does not exist
    
    ```
    {
      "title": "Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "detail": "The job execution with ID 'nonexistent-exec' for job 'my-custom-job' was not found."
    }
    ```
    

### DELETE Delete Job Execution

`DELETE /organizations/{organizationId}/jobs/{jobId}/executions/{executionId}`

Operation ID: `deleteJobExecution`. Security: AmOAuth2 (sfcc.jobs.rw).

Aborts and deletes a specific job execution. This operation can only be performed on executions that are currently in a running or pending state.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `jobId` (path, string, required) The identifier of the job.  
    Minimum length: 1. Maximum length: 256. Example: `my-custom-job`.
*   `executionId` (path, string, required) The identifier of the job execution.  
    Minimum length: 1. Maximum length: 256. Example: `exec-001`.

#### Responses

*   **204** The job execution was successfully deleted
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as POST /organizations/{organizationId}/job-execution-search 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as POST /organizations/{organizationId}/job-execution-search 403 response._
    
*   **404** Job execution not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example JobExecutionNotFound: same as GET /organizations/{organizationId}/jobs/{jobId}/executions/{executionId} 404 response._ Job execution not found
    
    Example of an error when the specified job execution does not exist
    
    _Example: JobExecutionNotFound_ Job execution not found
    
    Example of an error when the specified job execution does not exist
    

## Schemas

### OrganizationId

An identifier for the organization the request is being made by

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.

### JobExecutionSearchRequest

Document representing a search request for retrieving job executions. The query is a potentially complex set of expressions.

Searchable attributes:

*   id - String
*   jobId - String
*   status - String
*   startTime - DateTime
*   endTime - DateTime

Sortable attributes:

*   id - String
*   jobId - String
*   status - String
*   startTime - DateTime
*   endTime - DateTime

Includes all fields of `SearchRequest`.

### JobExecutionSearchResult

Document representing a job execution search result. This includes the query, hits (array of JobExecution objects), and pagination information.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of JobExecution_, required) The sorted array of search hits (JobExecution objects). Can be empty.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### JobExecutionRequest

Document representing a request to create a job execution. Optional parameters can be provided to configure the execution.

*   `parameters` (_array of JobParameter_) The parameters for the job execution.

### JobExecution

Document representing a job execution.

*   `id` (_string_, required) The ID of the job execution.  
    Minimum length: 1. Maximum length: 256. Example: `1`.
*   `jobId` (_string_, required) The ID of the job.  
    Minimum length: 1. Maximum length: 256. Example: `JobExecutionTestJob1`.
*   `jobDescription` (_string_) The description of the job.  
    Maximum length: 4000. Example: `Test job for WAPI`.
*   `clientId` (_string_) The client ID that triggered the job execution.  
    Maximum length: 256. Example: `scapi`.
*   `userLogin` (_string_) The login of the user who started the job execution, if started by a registered user.  
    Maximum length: 256. Example: `admin`.
*   `executionStatus` (_object_) The execution lifecycle status of the job.
    
    Includes all fields of `ExecutionStatus`.
    
*   `status` (_string_, required) The exit status of the job execution.  
    Maximum length: 256. Example: `OK`.
*   `startTime` (_string (date-time)_) The timestamp when the job execution started.  
    Example: `2024-10-14T10:00:00.000Z`.
*   `endTime` (_string (date-time)_) The timestamp when the job execution ended.  
    Example: `2024-10-14T10:10:00.000Z`.
*   `creationDate` (_string (date-time)_) The timestamp when the job execution was created.  
    Example: `2024-10-14T10:00:00.000Z`.
*   `duration` (_integer (int64)_) The duration of the job execution in milliseconds.  
    Example: `171`.
*   `effectiveDuration` (_integer (int64)_) The effective duration of the job execution in milliseconds, excluding any paused time.  
    Example: `92`.
*   `modificationTime` (_string (date-time)_) The timestamp when the job execution was last modified.  
    Example: `2024-10-14T10:10:00.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the job execution was last modified (alias).  
    Example: `2024-10-14T10:10:00.000Z`.
*   `executedServerId` (_string_) The ID of the server that executed the job.  
    Maximum length: 256. Example: `192.168.1.2-0`.
*   `exitStatus` (_object_) The exit status of the job execution.
    
    Includes all fields of `ExitStatus`.
    
*   `statusMetadata` (_object_) Metadata associated with the current status of the job execution.
    
    Includes all fields of `StatusMetadata`.
    
*   `isLogFileExisting` (_boolean_) Indicates whether a log file exists for the job execution.  
    Example: `true`.
*   `isRestart` (_boolean_) Indicates whether the job execution is a restart of a previous execution.  
    Example: `false`.
*   `logFilePath` (_string_) The full WebDAV path of the log file associated with the job execution.  
    Maximum length: 4000. Example: `/Sites/LOGS/jobs/JobExecutionTestJob1/Job-JobExecutionTestJob1-02c585c2a242c8eee74bd1ba51.log`.
*   `parameters` (_array of JobParameter_) The parameters used for the job execution.
*   `executionScopes` (_array of string_) The scopes for which the job was executed.  
    Items: Maximum length: 256. Example: `Organization`.
*   `retryInformation` (_object_) The retry information of this execution if available.
    
    Includes all fields of `JobExecutionRetryInformation`.
    
*   `continueInformation` (_object_) The continuation information of this execution if available.
    
    Includes all fields of `JobExecutionContinueInformation`.
    
*   `stepExecutions` (_array of JobStepExecution_) The step executions that are part of this job execution.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### JobParameter

Document representing a single job parameter as a name-value pair.

*   `name` (_string_, required) The name of the job parameter.  
    Minimum length: 1. Maximum length: 256. Pattern: \\S|(\\S(.\*)\\S). Example: `param1`.
*   `value` (_string_, required) The value of the job parameter.  
    Minimum length: 0. Maximum length: 1000. Pattern: \\S|(\\S(.\*)\\S). Example: `value1`.

### ExecutionStatus

The execution lifecycle status of a job or step execution.

Type: `string`.

Allowed values: `pending`, `running`, `pausing`, `paused`, `resuming`, `resumed`, `restarting`, `restarted`, `retrying`, `retried`, `aborting`, `aborted`, `finished`, `unknown`. Example: `finished`.

### ExitStatus

Document representing the exit status of a job or step execution.

*   `code` (_string_) The exit status code.  
    Maximum length: 256. Example: `OK`.
*   `message` (_string_) The exit status message providing additional details.  
    Maximum length: 4000. Example: `Job completed successfully`.
*   `status` (_string_) The exit status value.  
    Allowed values: `ok`, `error`. Example: `ok`.

### StatusMetadata

Document representing metadata associated with the status of a job execution.

*   `clientId` (_string_) The client ID responsible for the status.  
    Maximum length: 256. Example: `scapi`.
*   `reason` (_string_) The reason for the status.  
    Maximum length: 4000. Example: `Job aborted by user`.
*   `userLogin` (_string_) The user login responsible for the status.  
    Maximum length: 256. Example: `admin`.

### JobExecutionRetryInformation

Document representing retry information for a previous failed job execution.

*   `currentRetryAttempt` (_integer (int32)_) The current attempt to retry the previous failed job execution.  
    Example: `1`.
*   `maxRetries` (_integer (int32)_) The maximum number of retries.  
    Example: `3`.

### JobExecutionContinueInformation

Document representing continuation information for a job execution.

*   `isPending` (_boolean_) True if the continuation of this job execution is pending and will be started soon, false otherwise.  
    Example: `true`.
*   `continueStatus` (_string_) The status this job execution will get on continuation if continuation is pending.  
    Maximum length: 256. Example: `OK`.

### JobStepExecution

Document representing a step execution within a job execution.

*   `id` (_string_) The ID of the step execution.  
    Minimum length: 1. Maximum length: 256. Example: `4`.
*   `stepId` (_string_) The ID of the step.  
    Minimum length: 1. Maximum length: 256. Example: `Step1`.
*   `stepDescription` (_string_) The description of the step.  
    Maximum length: 4000. Example: `A step that executes a pipeline that can be configured via a parameter`.
*   `stepTypeId` (_string_) The type identifier of the step.  
    Maximum length: 256. Example: `ExecutePipeline`.
*   `stepTypeInfo` (_string_) Additional type information about the step.  
    Maximum length: 4000. Example: `TestWAPIJobPipeline-StartEnd`.
*   `executionScope` (_string_) The execution scope of the step.  
    Maximum length: 256. Example: `Organization`.
*   `executionStatus` (_object_) The execution lifecycle status of the step.
    
    Includes all fields of `ExecutionStatus`.
    
*   `status` (_string_) The exit status of the step execution.  
    Maximum length: 256. Example: `OK`.
*   `startTime` (_string (date-time)_) The timestamp when the step execution started.  
    Example: `2024-10-14T10:00:00.000Z`.
*   `endTime` (_string (date-time)_) The timestamp when the step execution ended.  
    Example: `2024-10-14T10:05:00.000Z`.
*   `duration` (_integer (int64)_) The duration of the step execution in milliseconds.  
    Example: `21`.
*   `modificationTime` (_string (date-time)_) The timestamp when the step execution was last modified.  
    Example: `2024-10-14T10:05:00.000Z`.
*   `statusMetadata` (_object_) Metadata associated with the current status of the step execution.
    
    Includes all fields of `StatusMetadata`.
    
*   `exitStatus` (_object_) The exit status of the step execution.
    
    Includes all fields of `ExitStatus`.
    
*   `includeStepsFromJobId` (_string_) The ID of the job whose steps are included in this step execution.  
    Maximum length: 256. Example: `JobExecutionTestJob2`.
*   `isChunkOriented` (_boolean_) Indicates whether the step execution is chunk-oriented.  
    Example: `false`.
*   `chunkSize` (_integer (int32)_) The chunk size used during step execution.  
    Example: `100`.
*   `itemFilterCount` (_integer (int32)_) The number of items filtered during step execution.  
    Example: `0`.
*   `itemWriteCount` (_integer (int32)_) The number of items written during step execution.  
    Example: `500`.
*   `totalItemCount` (_integer (int64)_) The total number of items to process during step execution.  
    Example: `500`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "value": {
    "must": [
      {
        "textQuery": {
          "fields": [
            "couponId"
          ],
          "searchPhrase": "DEAL"
        }
      },
      {
        "textQuery": {
          "fields": [
            "description"
          ],
          "searchPhrase": "Big bargain deal"
        }
      }
    ],
    "mustNot": [
      {
        "termQuery": {
          "fields": [
            "enabled"
          ],
          "operator": "is",
          "values": [
            false
          ]
        }
      }
    ]
  }
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "value": {
    "operator": "and",
    "filters": [
      {
        "termFilter": {
          "field": "id",
          "operator": "is",
          "values": [
            "myId"
          ]
        }
      },
      {
        "termFilter": {
          "field": "couponId",
          "operator": "is",
          "values": [
            "couponOne"
          ]
        }
      }
    ]
  }
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=b405c105d94f8c9c33a629dd72af32d9d8b0923959b62f0f429c8b9df2fb4795 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/json-sample-payloads-schemas.md -->

# JSON Sample Payloads & Schemas

The table provides sample JSON schemas for TLog exports. When mapping your TLog using the JSON format, follow the schema outlined in the table to ensure compatibility with your downstream systems.

**tip:** In the [reference documentation](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html), a JSON property is identified as a collection (List/Array) if, upon expansion, it displays `Any of VARIABLES`, indicating it contains a collection of that specified variable.

## Basic Orders

| **File**                                                                                                | **JSON Field**                                              | **Order Activity Log**                                                                                                                      |
| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Sale Transactions**                                                                                   |                                                             |                                                                                                                                             |
| Single Item Sale <br>_Transaction involving the sale of one specific item in an order_                  | orderProductList                                            | orderActivityLog.TransactionData.orderId                                                                                                    |
| Offline Single Item <br>_Offline transaction involving the sale of one specific item in an order_       | orderProductList                                            | N/A                                                                                                                                         |
| Multi Item Sale <br>_Transaction involving the sale of multiple items in an order_                      | orderProductList                                            | N/A                                                                                                                                         |
| Sale With Customer <br>_Transaction associated with a specific customer_                                | customerProfile                                             | orderActivityLog.transactionData.profile                                                                                                    |
| **Promotions and Discounts**                                                                            |                                                             |                                                                                                                                             |
| Employee Discount <br>_Transaction with employee discount applied_                                      | orderProductList.priceAdjustments                           | orderActivityLog.transactionData.productList.productPriceAdjustment                                                                         |
| Item Level Discount <br>_Discount applied to specific items in an order_                                | orderProductList.priceAdjustments                           | orderActivityLog.transactionData.productList.productPriceAdjustment                                                                         |
| Transaction Level Discount <br>_Discount applied to the total cost of a transaction_                    | orderProductList.priceAdjustments transactionDiscountAmount | orderActivityLog.transactionData.productList.productPriceAdjustment <br>**Additional Field:** "priceAdjustmentType": "TRANSACTION_DISCOUNT" |
| Single Use Promotion Code <br>_Promotional code used once to apply discount to cart_                    | coupons                                                     | N/A                                                                                                                                         |
| Promotion <br>_Promotion applied to items or transactions_                                              | orderProductList.priceAdjustments                           | orderActivityLog.transactionData.productList.productPriceAdjustment <br>**Additional Field:** "priceAdjustmentType": "PROMOTION"            |
| **Gift Card Management**                                                                                |                                                             |                                                                                                                                             |
| Purchase Gift Card <br>_Transaction with a gift card purchase_                                          | N/A                                                         | N/A                                                                                                                                         |
| Issue With Loading Gift Cards <br>_Transaction with issues encountered when adding value to gift cards_ | orderProductList.productClass orderProductList.serialNumber | orderActivityLog.transactionData.productList.productClass                                                                                   |
| **Notes and Adjustments**                                                                               |                                                             |                                                                                                                                             |
| Item Level Note <br>_Transaction with notes applied to individual items_                                | orderProductList.notesList                                  | orderActivityLog.transactionData.productList.notesList                                                                                      |
| Order Level Note <br>_Transaction with notes applied to the entire order_                               | notesList                                                   | N/A                                                                                                                                         |
| Split Sales Attribution <br>_Transaction with sales attribution split among different employees_        | orderProductList.salesAssociateAttribution                  | orderActivityLog.transactionData.tenders                                                                                                    |
| **Tax and Billing**                                                                                     |                                                             |                                                                                                                                             |
| Tax Exempt <br>_Transaction with items that are not subjected to sales tax_                             | taxExemptions                                               | orderActivityLog.transactionData.taxExemptions                                                                                              |
| Billing <br>_Transaction with a recorded billing address_                                               | billingAddress                                              | N/A                                                                                                                                         |

## Omni Orders

| **File**                                                              | **JSON Field**                                                    | **Order Activity Log** |
| --------------------------------------------------------------------- | ----------------------------------------------------------------- | ---------------------- |
| Charge & Send <br>_In-store omni transaction_                         | fulfillmentType fulfillmentSubType shippingAddress billingAddress | N/A                    |
| Ship From Store <br>_Ship to home fom current store omni transaction_ | fulfillmentType fulfillmentsubtype shippingAddress                | N/A                    |

## Tender Payments

| **File**                                                                                            | **JSON Field**                                       | **Order Activity Log**                                                                                      |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Cash Payment <br>_Transaction completed with cash_                                                  | tenders.paymentMethod tenders.cardType               | orderActivityLog.transactionData.tenders <br>**Additional Field:** "paymentMethod": "Cash"                  |
| Credit Card Payment <br>_Transaction completed with credit card_                                    | tenders.paymentMethod tenders.cardType fundingSource | orderActivityLog.transactionData.tenders <br>**Additional Field:** "paymentMethod": "CreditCard "cardType": |
| Debit Card Payment <br>_Transaction completed with debit card_                                      | tenders.paymentMethod tenders.cardType fundingSource | orderActivityLog.transactionData.tenders <br>**Additional Field:** "paymentMethod": "CreditCard "cardType": |
| Gift Card Payment <br>_Transaction completed with gift card_                                        | tenders.paymentMethod tenders.cardType fundingSource | orderActivityLog.transactionData.tenders <br>**Additional Field:** "paymentMethod": "GiftCard"              |
| Tap to Pay <br>_Transaction completed with Tap to Pay_                                              | tenders.paymentMethod tenders.cardType fundingSource | orderActivityLog.transactionData.tenders                                                                    |
| In-Store Pay By Link <br>_Transaction completed with in-store pay by link_                          | tenders.paymentMethod tenders.cardType fundingSource | orderActivityLog.transactionData.tenders                                                                    |
| Remote Pay By Link <br>_Transaction completed with remote pay by link_                              | tenders.paymentMethod tenders.cardType fundingSource | orderActivityLog.transactionData.tenders                                                                    |
| Multi-Tender <br>_Transaction completed with more than one type of payment method_                  | tenders.paymentMethod tenders.cardType fundingSource | orderActivityLog.transactionData.tenders                                                                    |
| Miscellaneous Payment (Goodwill) <br>_Transaction completed with a miscellaneous type of Goodwill_  | tenders.paymentMethod tenders.cardType fundingSource | N/A                                                                                                         |
| Miscellaneous Payment (Deposit) <br>_Transaction completed with a miscellaneous type and a deposit_ | tenders.paymentMethod tenders.cardType fundingSource | N/A                                                                                                         |

## Returns and Exchanges

| **File**                                                                                                                                                                      | **JSON Field**    | **Order Activity Log**                                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Even Exchange (original, exchange) <br>_Transaction where an item is exchanged for another item of equal value, with no additional payment or refund_                         | N/A               | orderActivityLog.transactionData.transactionType <br>originalOrderId                                                                         |
| Exchange With Extra Payment (original, exchange) <br>_Transaction where an item is exchanged for another item of higher value, and the customer pays the difference_          | N/A               | orderActivityLog.transactionData.transactionType <br>originalOrderId                                                                         |
| Exchange With Refund (original, exchange) <br>_Transaction where an item is exchanged for another item of lower value, and the customer receives a refund for the difference_ | N/A               | orderActivityLog.transactionData.transactionType <br>originalOrderId                                                                         |
| Return (gift card cash out, multi-item, single item) <br>_Transaction where a customer returns an item and receives a refund or credit_                                       | returnProductList | orderActivityLog.transactionData.returnProductList.productId                                                                                 |
| Unreferenced Even Exchange (original, new order) <br>_Even exchange transaction that is not linked to a specific previous purchase or reference number_                       | N/A               | orderActivityLog.transactionData.transactionType <br>originalOrderId <br>returnProductList <br>tenders.copiedFromOrderId <br>noReceiptReturn |
| Unreferenced Return (exchange, return) <br>_Return transaction that is not linked to a specific previous purchase or reference number_                                        | returnProductList | N/A                                                                                                                                          |

<!-- ## Unreferenced attachments:

- gift_card_cash_out_json
- single_item_return_json
- multi_item_return_json
- original_json
- new-order_json
- unreferenced_return_json
- unreferenced_exchange_json
- offline_single_item_sale_json
- employee_discount_json
- item_level_discount_json
- single_item_sale_json
- multi_item_sale_json
- sale_with_customer_json
- transaction_level_discount_json
- single_use_promo_code_json
- promotion_json
- purchase_gift_card_json
- issueload_gift_card_json
- item_level_note_json
- order_level_note_json
- split_sales_attribution_json
- tax_exempt_json
- chargesend_json
- shipfromstore_json
- cash_payment_json
- credit_card_payment_json
- debit_card_payment_json
- gift_card_payment_json
- taptopay_json
- instorepaybylink_json
- remotepaybylink_json
- split_payment_json
- original_sale_json
- misc_paymentgoodwill_json
- misc_paymentdeposit_json
- exchange_json
- original_sale_json
- exchange_json
- exchange_json
- original_sale_json
- billing_json -->

<!-- document id=834f8de83d2cc8fcb6d1ecafac8758f8b19c6710f205c06fdb91268e5b7ad42a url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-load-more.md -->

# Keep Shoppers Browsing with Load More Pagination

The Load More button replaces numbered pagination on product listing pages, appending products without page reloads or scroll position loss. Shoppers stay in a continuous discovery flow as they click to load more products. A progress indicator shows "Showing X of Y products" to maintain context while browsing. The load more behavior offers a better shopper experience than numbered pagination, which breaks browsing flow because of full page reloads. The Load More button is enabled by default. Use the `uiConfig.pages.category.pagination` configuration to set pagination properties or switch to numbered pagination.

![Load More button](https://developer.salesforce.com/docs/media/sfnext/sfnext-load-more-button.png '{"class": "image-md"}')

## Configure Pagination

To configure options for the load-more pagination, or to switch to the numbered pagination, modify the `uiConfig.pages.category.pagination` options in `src/lib/config.ui.ts`. This example configuration shows the load-more pagination properties. To switch to the numbered pagination, which shows numbers at the bottom of the page, set `mode` to `traditional`.

``` 
// src/lib/config.ui.ts
 export const uiConfig: UIConfig = {
   pages: {
     category: {
       pagination: {
         mode: 'load-more', // or 'traditional' (numbered pagination)
         batchSize: 24,
         mobileBatchSize: 12,
         maxProducts: 200,
       },
     },
   },
 };
```

To learn more about these config options, see [Configuration Options Reference](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/README-CONFIG-OPTIONS.md) in the storefront-next-template GitHub repository.

<!-- document id=a90d3653e53a0eea261586598ff81bf8486e60eefba304eeadf920ddd0c8dc1f url=/developer/current/en-us/commerce-cloud/lwr-migration/guides/key-differences.md -->

# Key Differences

B2B Commerce Aura and LWR storefronts share many of the same functionalities, but they support different components with varied behavior. To understand the requisites of store migration, consider these distinctions.

## Component Support

A B2B store uses the Lightning Component framework to construct UIs for mobile and desktop devices. As of Spring ’19, you had the option to build these Lightning components, or deploy preconfigured components, using two programming models: the LWC model and the original Aura Components model.

A B2B store on Aura supports Lightning web components and Aura components. A B2B store on LWR only supports Lightning web components. To make sure that migration from B2B Commerce Aura to B2B on LWR is smooth, prepare to update your storefront’s existing UI components.

Many Lightning web components developed to run in Aura function on LWR with no changes or can be easily modified to do so. For more information on store components, see [LWR and Aura Store Templates](https://help.salesforce.com/s/articleView?id=commerce.comm_lwr_aura_comps.htm).

## Styling and Global Attributes

Lightning web components and Aura components differ in their styling capabilities and their response to global HTML attributes and events. For example, an Aura component requires you to create your own classes for custom styling. A Lightning web component prevents custom styling with your own classes because it follows shadow DOM standards, which hide the elements inside the component from the page that contains the component. Instead, modify a base or custom Lightning web component using `--dxp` styling hooks, which map to CSS custom properties in your site’s Theme panel. This functionality makes branding a B2B store on LWR faster, easier, and more consistent. For more information, see [How Branding Works in LWR Sites](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/brand_overview.htm).

Lightning web components also inherit global HTML attributes and events, making them more functional and performant than their Aura counterparts.

## Data Access and Operations

To access a stream of Salesforce data and metadata, Lightning web components use a wire service built on Lightning Data Service. This wire service creates reactive storefronts using data from individual records, lists of records, and object and layout schema. For details, see [Use the Wire Service to Get Data](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.data_wire_service).

Aura components access Lightning Data Service with equivalent but more restrictive form-based components such as lightning:recordForm and force:recordData.

<!-- document id=1f6caee203e282d585f016539447f0c8671b983d4a3a7faac657ad054443997f url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/launching-your-storefront.md -->

# Launch Your Storefront

This guide describes how to launch a Progressive Web App (PWA) Kit storefront and make it accessible from its official, public web address.

Throughout this guide we use an example storefront with the following attributes:

- Production URL: `https://www.example.com`
- Project ID: `example`
- Environment IDs: `staging` and `production`

Before running the commands, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

## When to Use a Third-Party CDN

See [Decide which CDN to Use](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/decide-on-cdn.md).

## Before You Begin

This guide assumes that you have access to the [Runtime Admin](https://runtime.commercecloud.com/) web application and the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary) to perform administrative tasks. To get access to these tools, contact your B2C Commerce administrator and ask them to add either one of the following roles to your account using Account Manager: **Managed Runtime User** or **Managed Runtime Admin**.

To make requests to the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary), you must include an API key in the HTTP request `Authorization` header with the value, `Bearer $API_KEY`. For all the sample requests provided, don’t forget to replace `$API_KEY` with your actual API key.

To find your API key, log in to [Runtime Admin](https://runtime.commercecloud.com/) and go to the [Account Settings](https://runtime.commercecloud.com/account/settings) page.

**Important**: Treat your API key like a password because it allows scripts to complete operations on your behalf.

You need access to your DNS provider to create and update CNAME records, as well as access to your third-party CDN provider (as applicable).

### What Is Mobify?

In this guide, the word “Mobify” appears in a few places. Mobify is the name of the company that originally developed the technology that became PWA Kit and Managed Runtime. In 2020, Salesforce acquired Mobify along with all of its technology.

The Mobify brand name appears in the `mobify-storefront.com` domain used to host your storefront and the `cloud.mobify.com` domain used by the Managed Runtime API.

### Use a Custom Domain for Local Development

If you need to add conditional logic that alters the behavior of your site depending on the domain used, it’s easier to test this logic when your local development server can use a custom domain. Why would you need to add this kind of logic? Consider, for example, the need to look up a different SLAS Client ID depending on the domain.

To run your local development server using a custom domain:

1. Modify your local computer's DNS to resolve your custom domain to `127.0.0.1` (localhost).
2. Edit `ssr.js`.
3. In the `options` passed to `runtime.createHandler`, set the port to `80`.
4. Run `EXTERNAL_DOMAIN_NAME=www.example.com npm start`, replacing the value of `example.com` with your custom domain. _Running the server on port `80` can sometimes require administrative privileges._

Requests from your browser to the custom domain are now resolved and routed to your local development server!

## Launching an Environment

The process for launching an environment is the same for staging and production, with the only difference being the domain name and the Managed Runtime environment used.

**warning:** We strongly recommend going through the launch process on a staging environment first before repeating the process on production. These steps should be completed as soon as you start a PWA Kit project and at least two weeks before your launch date.

For the instructions provided, imagine you’re launching a storefront at `staging.example.com`, your project ID in Managed Runtime is `example`, and your bundle is deployed to an environment called `staging`.

## 1. Create Your Environment

Use [Runtime Admin](https://runtime.commercecloud.com/) or [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/managed-runtime-api?meta=Summary) to create an environment called `staging` to practice launching the storefront.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$API_KEY"

npx @salesforce/b2c-cli mrt env create staging --project my-storefront
```

Alternatively, use the API. Here's a sample request that uses the [projects_target_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_create) endpoint to create an environment. Replace `example` in the request with your actual project ID string and `$API_KEY` with your API key:

```bash
curl 'https://cloud.mobify.com/api/projects/example/target/' \
  --request 'POST' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "name" : "staging" }'
```

For instructions on creating an environment with [Runtime Admin](https://runtime.commercecloud.com/), see our guide to [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#create-an-environment).

## 2. Ensure APIs Are Accessible

Many PWA Kit implementations make requests to OCAPI or controllers in addition to B2C Commerce API.

You must ensure your B2C Commerce instance is reachable by Managed Runtime.

Making the APIs reachable typically involves configuring eCDN to make your B2C Commerce instance available at an alternative domain like `ecom.example.com`. For more information, refer to the [eCDN setup and configuration documentation](https://documentation.b2c.commercecloud.salesforce.com/DOC2/topic/com.demandware.dochelp/content/b2c_commerce/topics/admin/b2c_configure_the_embedded_cdn.html).

After your domain is configured, update your environment’s proxy settings to use it. For more information, see our guide to [Proxying Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md).

## 3. TLS Certificates

**important:** This step is not required when using a third-party CDN or eCDN. Consult your CDN vendor documentation for configuring certs.

If you are routing traffic directly to the Managed Runtime CDN, then Managed Runtime issues and manages TLS certificates on your behalf.

### Certificate Management

Organization Admins and Organization Users with the Managed Certificates permission can now manage TLS certificates directly through Runtime Admin. This provides enhanced control over certificate lifecycle management without requiring support tickets for routine certificate operations.

**Prerequisites for Certificate Management:**

- Organization Admin role OR Organization User with Managed Certificates permission assigned.
- Access to [Runtime Admin](https://runtime.commercecloud.com/).

### Request a TLS Certificate

If you have the appropriate permissions, you can request certificates directly through Runtime Admin. See [Organization Certificate Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#certificate-management)

### Domain Validation Requirements

Make sure that these requirements are met.

- The domain's [`CAA` records](https://letsencrypt.org/docs/caa/) are set to allow [AWS to issue certs](https://docs.aws.amazon.com/acm/latest/userguide/setup-caa.html) by including these values:

```
0 issue "amazon.com"
0 issuewild "amazon.com"
```

- You can create CNAME records for domain validation within **72 hours** of receiving validation details.

### TLS Certificate Renewal Process

Managed Runtime automatically renews TLS certificates as long as:

- The CNAME record remains in place to validate ownership.
- The TLS certificate is in use by at least one environment.
- The domain's [`CAA` records](https://letsencrypt.org/docs/caa/) are set to allow [AWS to issue certs](https://docs.aws.amazon.com/acm/latest/userguide/setup-caa.html) by including these values:

```
0 issue "amazon.com"
0 issuewild "amazon.com"
```

## 4. DNS CNAME

**important:** This step isn't required when using a third-party CDN or eCDN.

Reduce the time to live (TTL) for `staging.example.com` to one minute. _Reducing the TTL speeds up the DNS cutover process, and if something goes wrong, allows you to roll back quickly._

You can verify the TTL using the [`dig`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Dig_(command)>) command:

```sh
dig +nocmd +noall +answer 'staging.example.com'
```

## 5. Configure Your Environment

### Option 1: Use a Third-Party CDN or eCDN

Set an environment’s access control header using Runtime Admin's [Access Control Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#access-control-headers) or the [access_control_header](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_access_control_header_create) API.

In this example, we use the API to set an access control header with the header value `25pn5dec7f1c`:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$TARGET/access-control-header/" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "value" : "25pn5dec7f1c" }'
```

The access control header value will be used during [Perform the Cutover](#6-perform-the-cutover) to prevent direct access to the environment.

### Option 2: Use the Managed Runtime CDN

Configure the environment to receive traffic from the host `staging.example.com`.

**important:** A hostname can be set as the External Hostname for only one environment at a time. If the hostname is already configured on another environment, this step fails until it's removed from that environment.

- Navigate to the Environment Settings page.
- Under Advanced, click **Edit**.
- Select the desired certificate (`staging.example.com` or `*.example.com`).
- Provide a subdomain if using a wildcard certificate.
- Click **Save**.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli mrt env update \
  --project my-storefront --environment staging \
  --external-domain example.com --external-hostname staging.example.com
```

Optionally, you can configure the environment via the API. Update the environment’s `ssr_external_domain` and `ssr_external_hostname` settings using the [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) API.

```bash
curl 'https://cloud.mobify.com/api/projects/example/target/staging/' \
  --request 'PATCH' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "ssr_external_domain": "example.com",
    "ssr_external_hostname": "staging.example.com"
}'
```

**important:** After this step, the environment is no longer accessible at its `mobify-storefront.com` or `exp-delivery.com` default domain.

Verify that the new settings are in effect using a [cURL](https://daniel.haxx.se/blog/2018/04/05/curl-another-host/) command that makes a request with [DNS spoofing](https://daniel.haxx.se/blog/2018/04/05/curl-another-host/):

```bash
curl 'https://staging.example.com' \
    --resolve 'staging.example.com:443:'"$(dig +short 'example-staging-cdn.sfdc-8tgtt5-ecom1.exp-delivery.com' | tail -n1)"
```

## 6. Perform the Cutover

The cutover process is different depending on whether you use a third-party CDN, eCDN, or the Managed Runtime CDN.

### Option 1: Use a Third-Party CDN

Configure your Managed Runtime environment as an origin in your CDN:

- set the `Host` header to match your environment `{{project}}-{{environment}}.sfdc-8tgtt5-ecom1.exp-delivery.com`
- forward the request method
- forward the path (including query string)
- forward the headers
- forward the body
- forward all traffic over HTTPS
- obey HTTP caching headers
- set the `x-sfdc-access-control` header value if configured for your environment

Refer to your CDN provider documentation for detailed guidance.

**note:** Managed Runtime routes requests to environments using the HTTP `Host` header. Requests with an incorrect host are rejected with an HTTP 403 Bad Request response.

Consider adding a handler to reflect HTTP requests and verify that your CDN is configured correctly:

```js
// ssr.js
app.all('/echo', function echoHandler({method, path, headers, body}, res) {
  res.send({method, path, headers, body})
})
```

Also consider adding a [proxy](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.html#configure-managed-runtime-environments) with [httpbin.org/anything](https://httpbin.org/anything) to verify headers passed to proxies are sent correctly.

If you encounter issues, use the techniques described in [Debug PWA Kit Apps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html).

### Option 2: Use eCDN

Update your eCDN routing rules to route traffic to your Managed Runtime environment. Review the [eCDN MRT Rules](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ecdn-rules-for-phased-headless-rollout.html#route-traffic-to-managed-runtime) guide for more information. You can also [Configure MRT Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-mrt-routing-bm.md).

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md) to send the header configured in [step 5](#option-1-use-a-third-party-cdn-or-ecdn):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn zones list --tenant-id abcd_stg

npx @salesforce/b2c-cli ecdn origin-headers set \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --header-value 'example-header-value'
```

Alternatively, call [upsertOriginHeaderModification](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=upsertOriginHeaderModification):

```bash
curl  "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/origin-header-modification/mrt" \
  --request 'PUT' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "headerValue" : "25pn5dec7f1c" }'
```

### Option 3: Use the Managed Runtime CDN

Perform a DNS cutover to point your domain from the old origin to the Managed Runtime CDN.

#### Find Your DNS Configuration Values

To find the correct DNS values for your environment, check the DNS configuration in Environment Settings.

1. In your environment's overview page in [Runtime Admin](https://runtime.commercecloud.com/), click **Environment Settings**.
2. View the **DNS Configuration** section for the exact CNAME record values.

#### Manual DNS Configuration

Alternatively, the Managed Runtime CDN stable domain follows the convention of one of these default domains:

- `{{project}}-{{environment}}-cdn.sfdc-8tgtt5-ecom1.exp-delivery.com`
- `{{project}}-{{environment}}-cdn.mobify-storefront.com`

Where `{{project}}` is your project ID, and `{{environment}}` is your environment ID.

#### Update Your DNS Records

1. Update the DNS CNAME record for `staging.example.com` to the value shown in your DNS configuration (e.g., `example-staging-cdn.sfdc-8tgtt5-ecom1.exp-delivery.com`).
2. Open your web browser and navigate to `staging.example.com`.

Congrats, you’ve completed your launch! 🥳

After completing these instructions for a staging site, you can repeat the same process with the production domain and production environment.

## 7. Site Monitoring

From here, the Customer Success Group assists you in monitoring the site’s traffic to make sure that the launch has succeeded. The goal is to ensure that everything happens as expected during launch!

After launch, customers with a Signature Success Plan receive proactive site monitoring. To take advantage of this increased monitoring service, you must mark your environment as `production`. For more information, see the section on [environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#environments) in the Managed Runtime Overview.

## Technical Limitations

- The `ssr_external_hostname` target setting controls which host the environment receives traffic from. If the HTTP `Host` header of a request doesn’t match this value, the request fails with a 403 error.
- A given hostname can only be set as the `ssr_external_hostname` for one environment at a time. Attempting to set a hostname that's already in use by another environment fails.
- Currently, Salesforce doesn’t support storefront URLs with a bare domain like [`example.com`](http://example.com/) (with no `www` subdomain). To use a bare domain, you must set up a server to redirect requests from the bare domain to your CNAME.

## See Also

- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.md)
- [Monitor Your PWA Kit Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/monitor-site.md)

<!-- document id=87794c5aa22c2b05a2fcb8884ed840691cc4637861d40123717c92ce9a9710cf url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-launch-storefront.md -->

# Launch Your Storefront Next

Launch your new storefront and make it accessible from its official, public web address.

Before running the commands, replace any placeholders with actual values.

## Before You Begin

- To perform administrative tasks, you must have one of these roles and permissions:

  - Managed Runtime roles: **Managed Runtime User** or **Managed Runtime Admin**. To request access, contact your B2C Commerce administrator and ask them to add one of these roles to your account in Account Manager.
  - Business Administrator role in Account Manager or a role for the Business Manager Module and Organization context with read-write access to storefronts. See [Create a Role in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_roles.htm&type=5) in _Salesforce Help_.
  - **Project Developer** or **Project Admin** role on the Managed Runtime project. To request access, contact your B2C Commerce administrator and ask them to add one of these roles to your account for the project in Runtime Admin.

- To make requests to the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary), you must include an API key in the HTTP request `Authorization` header with the value, `Bearer $API_KEY`. For all the sample requests provided, replace `$API_KEY` with your actual API key. To find your API key, log in to [Runtime Admin](https://runtime.commercecloud.com/) and go to the [Account Settings](https://runtime.commercecloud.com/account/settings) page.

  **important:** Treat your API key like a password because it allows scripts to complete operations on your behalf.

  Alternatively, use the [B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html) to make Managed Runtime API calls with your configured credentials.

- Have access to your DNS provider to create and update CNAME records, and access to your third-party CDN provider (as applicable). If you're using a vanity domain, see [Storefront Zone Creation](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones.md#storefront-zone-creation) for how to add an SSL certificate to your zone and configure the CNAME mapping, or [eCDN Automatic Certificates](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones-automatic-certs.md) to have eCDN manage the certificate for you.

- To make requests to the SCAPI CDN Zones API, you must have an API client with the `sfcc.cdn-zones` and `sfcc.cdn-zones.rw` OAuth scopes. See [Authorization for SCAPI Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-admin-apis.md) for steps on creating an API client and assigning scopes. Alternatively, use the [B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/ecdn.html) to make eCDN API calls without constructing requests yourself.

## Launching an Environment

The launch process is the same for staging and production. The only difference is the domain name and Managed Runtime environment.

**warning:** We strongly recommend going through the launch process on a staging environment before running it on production. Complete these steps as soon as you start a Storefront Next project and at least two weeks before your launch date.

## 1. Import the Storefront to the Staging or Production Instance

Before you can launch the storefront in another instance, export it from the sandbox or development instance, and then import it to the staging or production instance. The storefront import creates an initial environment that you can deploy a bundle to from the sandbox or development instance.

The storefront itself must always be imported. No replication path exists for storefronts. How you move the storefront's associated data, such as sites, catalogs, and price books, depends on the target instance:

- **Staging**: Use site import/export to move both the storefront and its associated data.
- **Production**: Use site import/export for the storefront, but use replication to move its associated data.

**note:** You can only export, and therefore import, one storefront at a time. Repeat these steps for each storefront, if necessary.

1. Export the storefront from the sandbox or development instance. If you're launching to staging, also export its associated data, such as sites, catalogs, and price books. Follow the steps in [Site Import/Export to Copy Instances and Development Testing in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_using_site_import_export_to_copy_instances.htm&type=5) in _Salesforce Help_.
2. Import the exported archive file into the staging or production instance.

   - **Staging**: Import the archive in Business Manager, under **Administration > Site Development > Import & Export**.
   - **Production**: Business Manager doesn't offer storefront archives as an importable option in production. Instead, run the import with the [B2C CLI](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/jobs.html) or the equivalent [SCAPI Job Execution API](https://developer.salesforce.com/docs/commerce/commerce-api/references/jobs?meta=Summary). To configure the B2C CLI for your production instance, see [Configuration](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html) in the Agentic B2C Developer Toolkit.

     ```bash
     b2c job import storefront-export.zip
     ```

     ```
     INFO: Importing storefront-export.zip to your-production-instance.demandware.net...
     INFO:   Status: finished (3s elapsed)
     INFO: Import completed: OK (duration: 0.4s)
     ```

   After the storefront import process finishes, the `sfcc-post-import-setup-storefront` job starts. For this instance, the job sets up an Account Manager API client, a SLAS client, a default environment, and an eCDN default domain. These configurations and environment are separate from the sandbox or development instance that the storefront was exported from. Next, the job deploys an initial bundle to the default environment, which sets up the environment and its environment variables.

   Use the B2C CLI to monitor the job's progress. First, find its execution ID:

   ```bash
   b2c job search
   ```

   ```
   INFO: Searching job executions on your-production-instance.demandware.net...
   INFO: Found 2 job execution(s) (showing 25)
   Execution ID  Job ID                                       Status   Start Time
   ────────────────────────────────────────────────────────────────────────────
   23539963      sfcc-post-import-setup-storefront            running  2026-09-01 14:31:45
   23539962      sfcc-site-archive-import                     OK       2026-09-01 14:31:44
   ```

   Then wait for it to complete:

   ```bash
   b2c job wait sfcc-post-import-setup-storefront 23539963
   ```

   ```
   INFO: Waiting for job sfcc-post-import-setup-storefront execution 23539963...
   INFO:   Status: running (3s elapsed)
   INFO:   Status: running (7s elapsed)
   INFO:   Status: OK (12s elapsed)
   ```

   If an error occurs during the job execution, check the job logs in **Administration > Operations > Jobs**. See [Managing Jobs](https://help.salesforce.com/s/articleView?id=cc.b2c_job_management.htm&type=5) in _Salesforce Help_.

3. If you're launching to production, replicate the storefront's associated data, such as sites, catalogs, and price books, from your staging or development instance. See [Granular Data Replication](https://help.salesforce.com/s/articleView?id=cc.b2c_granular_data_replications.htm&type=5) in _Salesforce Help_.
4. Deploy the storefront bundle to the staging or production environment. Then check whether any custom environment variables your storefront relies on are missing from that environment, and add them. See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md).

## 2. Update the SLAS Client Redirect URI

If you're using a vanity domain, add that domain to the `redirectUri` array of the SLAS client used by the storefront. Otherwise, shopper login requests that redirect back to your vanity hostname are rejected. See the `redirectUri` array description in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md#json-data), and append the URI using the [B2C CLI](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md#slas-admin-ui-create-a-slas-client), the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md#advanced-slas-admin-api) or SLAS Admin UI.

## 3. Perform the Cutover

To move your storefront to staging or production, configure eCDN routing only for vanity domains or for new zones.

### Default Domain

Default domains and default zones don't require eCDN configuration. Environments created in Storefront Next are preconfigured with eCDN and a default domain, which is routed to the Managed Runtime domain.

**note:** On production instances, the default domain doesn't resolve because Salesforce blocks it from public traffic by default. To test your production environment before cutover, either remove the block temporarily or allow your corporate VPN's IP addresses instead. See [Default Domain Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_default_domain.htm&type=5) in _Salesforce Help_.

### Vanity Domain or New Zone

If you're using a vanity domain or a new zone:

1. Update your eCDN routing rules to route traffic to your Managed Runtime environment. For more information, see [Traffic Routing for PIG Instances with eCDN](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html#traffic-routing-for-pig-instances-with-ecdn), or [configure MRT Routing Rules in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-routing-bm.md).
2. Update access control headers to allow only trusted traffic from eCDN to your MRT origin. That way, bots and crawlers can't access your MRT origin and negatively impact SEO.

To add a new access control header value for your vanity domain, use [Advanced Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#edit-environment-settings) in Runtime Admin or the [projects_target_access_control_header_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_access_control_header_create) API, and use that value in the upsert API call in the next section.

**note:** Storefront Next environments support up to 4 access control headers, and the header that Salesforce configures for your default domain can't be deleted. Add a separate header value for each vanity domain instead of reusing or replacing the default one. See [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#access-control-headers).

#### Send the Access Control Header from eCDN to the MRT Origin

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md) to set the header value configured in MRT:

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn zones list --tenant-id abcd_stg

npx @salesforce/b2c-cli ecdn origin-headers set \
  --tenant-id abcd_stg \
  --zone stg-abcd-example-com.cc-ecdn.net \
  --header-value 'example-header-value'
```

Alternatively, call [upsertOriginHeaderModification](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=upsertOriginHeaderModification):

```bash
curl  "https://$CODE.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/$ORG/zones/$ZONE/origin-header-modification/mrt" \
  --request 'PUT' \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{ "headerValue" : "25pn5dec7f1c" }'
```

## 4. Finalize the Environment

1. If you're launching to production, mark the environment as `production`. Customers with a Signature Success Plan receive proactive site monitoring for environments marked as production. For more information, see the section on [environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md#environments) in [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md).
2. Enable any additional eCDN configuration you want for the environment, such as HTTP/2 prioritization or TLS 1.3. See [HTTP/2 Prioritization](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones.md#http2-prioritization) and [TLS 1.3 Cipher Suites](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones-cipher-suite-types.md#tls-13-cipher-suites) in the CDN API guides.

## 5. Monitor the Site

Monitor the eCDN and MRT metrics in Log Center, in the [Metrics Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_metrics_dashboard.htm&type=5). See [Embedded Content Delivery Network (eCDN) Metrics](https://help.salesforce.com/s/articleView?id=cc.b2c_metrics_ecdn.htm&type=5) and [Managed Runtime Metrics](https://help.salesforce.com/s/articleView?id=cc.b2c_metrics_managed_runtime.htm&type=5) in _Salesforce Help_.

After you confirm that the launch succeeded, lock down the production default domain to accept traffic only from your corporate VPN, so that public traffic flows only through your vanity hostname. Use an [access control rule](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones.md#ip-access-control) in the CDN API to allowlist your VPN's IP addresses on the zone that fronts the default domain.

<!-- document id=8d542065efaf565795dda827bd5f50213547224a7f6e760bfb7faaa1b3ed38a7 url=/developer/current/en-us/commerce-cloud/solutions/guides/launching-flash-sale-sk.md -->

# Launching a Successful Flash Sale

So you’re interested in quickly generating ecommerce revenue, but you’re not sure where to start? These 10 steps help you plan for and launch a successful flash sale.
A flash sale (also called a hype or high-volume sale) is a short-term marketing strategy that offers a temporary, exclusive discount or promotion on specific products. The combination of scarcity and urgency turns the sale items into must-have commodities.

## 1. Set Goals for Your Flash Sale

Your first objective is to establish what you want to accomplish with your flash sale. Do you want to move inventory that’s becoming a liability? Maximize sales on Black Friday? Launch a new product? Your goals influence what products you decide to market and how.
Start by outlining your goals for the campaign. These might include:

- Encouraging customers to try new products
- Creating “brand buzz” to get more eyes on your store
- Clearing out excess or outdated inventory
- Boosting website traffic and revenue
- Taking advantage of the holidays or a current trend
- Raising brand awareness online

After you determine your goals, you have a better idea of your target audience and how best to market products during your sale.

## 2. Prepare Your Operations Team

Before your flash sale goes live, talk to your site operations team about preparing for the influx of traffic. This important step makes sure that your site can accommodate a spike in traffic without any downtime.
To notify Salesforce, simply submit a Support ticket that provides the date and time of your sale so that the influx of traffic isn’t flagged as suspicious. Communicating with Salesforce in advance helps to make sure that your customers have a seamless shopping experience.
Protecting platform availability is a shared responsibility between Salesforce and your team. When faced with volumetric attacks with impact to availability or performance, or when credential stuffing or account takeover activity is detected, B2C Commerce implements mitigations—such as rate limiting or managed challenges—with as little impact to legitimate shoppers as possible, often none at all. Submitting a Support ticket ahead of your sale helps distinguish your expected traffic from an attack pattern.
Create a virtual waiting room to control site traffic. Waiting rooms limit the number of shoppers allowed to purchase products at a given time. This is a great way to prevent overloading your site. For additional best practices on how to manage site traffic during a flash sale, see [Traffic Management Best Practices for Hype Sales](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/traffic-management-sk.md).

## 3. Identify Your Target Audience

Understanding your audience is the key to launching a flash sale that shoppers eagerly anticipate. Start by determining whether you’re targeting new or existing shoppers, or a certain demographic.
Some businesses do everything they can to make sure that their loyal shoppers can purchase the flash sale items rather than shoppers or bots who are likely to resell the products. This approach helps to create a strong brand identity and amplifies the exclusivity of the products. Conversely, some brands launch a flash sale to create hype about their brand or products, but they don’t necessarily tailor the sale to a particular audience. In this case, the goal is to sell out of the products as quickly as possible.
Consider having a mini flash sale event to test the market. Mini flash sales narrow your target audience by initially testing a few offers to see if they work before you launch a full-scale campaign. If your target audience is existing customers, try to avoid targeting customers who purchased sale products at the regular price. These customers are unhappy seeing others get a massive discount for the products they bought at full price.
To identify your target audience, focus on the following points:

- Find and target customers who haven’t purchased anything in the past six months or who have never purchased the item that’s featured in the flash sale.
- Identify customers who had a prior interest in on-sale products or specific products, such as customers who clicked an ad or visited a product page.
- Select flash sale items that are likely to attract a high volume of traffic.
- Make the flash sale for current customers exclusive and promote it through abandoned cart emails.

If you're targeting new customers, take extra steps to make sure they notice and visit your site.

- Run short-term Google Ads that are triggered by the exact keyword associated with your flash sale products.
- Avoid flooding your current email list with your flash sale promotions.
- Set pay-per-click ad targets to urge customers to opt in to a separate email list in return for early access to the discount.
- Identify shoppers who have shown interest in flash sales or who follow a rival store with similar products.
- Make a list of shoppers’ Twitter or Facebook handles and market to them directly.
- Give a significant discount on seasonal inventory to move it quickly and reduce inventory liability.

Identifying your target audience comes down to understanding buyer behavior and what your shoppers are interested in. With Salesforce’s [Commerce Cloud Einstein Predictive Sort](https://www.salesforce.com/products/commerce-cloud/resources/einstein-predictive-sort-for-commerce-cloud-digital-datasheet/), make AI-powered predictions about what items shoppers might want and are likely to buy. Data about past buyer behavior enables you to personalize the order in which shoppers see products. This data can even help to up-sell or cross-sell products to shoppers on your website.

### The Trend of Purpose-Built Bots

One example that highlights the benefit of thoroughly understanding your target audience is the prevalence of shoppers using bots to snag limited edition or otherwise promoted deals. Bots are software applications that shoppers can use to grab their place “in line” and automate the checkout process. The use of bots is a prevalent issue, particularly when shoppers are scrambling to snag the latest celebrity-inspired items — like makeup lines and sneakers.
For flash sales, bots are typically detrimental for the merchant, because the bots are designed to obtain the sale inventory instead of loyal shoppers. For example, some businesses that are victimized by bots see their inventory sell out, only to realize that someone is reselling the same inventory online elsewhere for two or three times the retail value. To maintain their relationships with loyal shoppers, many businesses aim to block bots from infiltrating their sales.
However, some businesses take a unique view on bots and are willing to allow bots to purchase a certain amount of inventory as long as their sale still creates hype. In this scenario, merchants also tend to reserve inventory for loyal shoppers by implementing a ticket system. With a ticket system, your most valued shoppers are almost always guaranteed access to some amount of sale inventory.

If the storefront runs on Managed Runtime, add these items to the pre-sale checklist:

- Enable **Managed Runtime SCAPI Request Identification** on each instance you want to protect (Development, Staging, and Production), and add the SCAPI-zone block rule in `log` mode. Scope each block rule to that instance's org-specific path segment and to Shopper API paths (`/shopper`), and place it directly after that instance's allow rule.
- Review the logged matches, including scheduled jobs and peak hours, and then switch the rule to `block` before the sale. Don't make that switch during the flash sale, a holiday code freeze, or another peak window.

Enabling the feature switch alone doesn't stop direct Shopper API calls. You write the block rule. Salesforce provides and rotates the secret and the allow rule. See [How do I restrict SCAPI to Managed Runtime traffic?](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-management.md#how-do-i-restrict-scapi-to-managed-runtime-traffic).

For more information about planning for bot mitigation, see [Traffic Management Best Practices for Hype Sales](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/traffic-management-sk.md).

## 4. Track Trends

Stay on top of current trends to find opportunities to direct new traffic to your site. For example, use tools like Google Trends or Twitter to follow what trends are happening in your industry. Some tools, like Mention, even alert you when keywords relating to your brand and business are mentioned. With this knowledge, capitalize on current trends and tailor your flash sale to what your followers are interested in.
Research what organic keywords your competitors are targeting and look for gaps where you can advertise your products with a short-term sale. Your site is more likely to generate traffic from these keywords, and more traffic can result in increased sales.
The key to success is acting on these trends as quickly as possible — and trying to anticipate them ahead of your competitors. The shorter the time frame, the more heightened the excitement is for impulse buyers. If you get there first, your brand is likely to snag the biggest piece of that traffic pie.

## 5. Set Up the Promotion on Your Site

When you set up the promotion on your site, the way you present the offer information matters. Focus on concise messaging so that shoppers can easily understand the promotion, and make the checkout process simple.
Shoppers react better to short-term, percentage-off discounts due to a phenomenon known as loss aversion. Use a percentage discount for products that cost more than $100 and a cash discount for products that cost less than $100.
It’s helpful to be particular with your phrasing. Instead of saying, “Save $3 on every $50 purchase you make,” use statements like “Save $70!” or “Get 40% off!” These promotions are concise and easier to understand. “Get 40% off!” emphasizes the discount, while “Save $70!” emphasizes avoiding a loss.
To reduce the potential of call center inquiries, accurately message the terms of your sale. Include specific guidelines about your promotion, such as the duration of the sale with start and end dates and times (for example, October 20, 2020, 12:01 a.m. ET through October 22, 2020, 11:59 p.m. ET). Also, specify any exclusions that apply for products or geographic regions, and clearly state if items are eligible for return or final sale.
To help promote your sale, consider adding pop-ups or interrupters to alert shoppers of the promotion wherever they enter your site. Depending on the type of flash sale, include the promotional message in the global navigation, too, so shoppers can easily access the promo code and other important details.

## 6. Choose Your Marketing Platforms

Begin marketing your flash sale before it starts by building anticipation on platforms where you can reach new audiences as well as connect with your existing shoppers.
Choose from multiple online platforms and channels for advertising your flash sale, including Instagram, Facebook Ads, Google Ads, Twitter, email lists, and more. Choose the platforms that make the most sense for your audience, and then decide whether you focus on organic traffic or invest in paid ads.
To determine the platform with the highest ROI, you must know:

- Which platforms produce the most engagement
- Which platform yields the lowest customer acquisition cost and the highest return on ad spend
- What percentage of your marketing budget goes to those channels
- Where your target audiences and existing shoppers spend most of their time

## 7. Promote Your Sale

To keep the momentum going, continue to promote the sale across your chosen platforms.
Some methods for promoting your flash sale might include:

- Running an email campaign to your existing lists
- Launching a pay-per-click ad campaign
- Posting about your sale on social media
- Reaching out to influencers or third-party publishers

The goal is for your flash sale to gain momentum online and boost engagement from followers through clicks, likes, retweets, comments, and shares. Start building excitement four to six days before the sale and during the main event. The more eyes on your campaign, the better.
One popular method for promoting a flash sale is through the use of bots — particularly, messenger bots. When shoppers visit your site or subscribe to your email list, often follow up via Facebook Messenger or via bots on your website. This technique is a quick and easy way to promote your latest offer to an audience that has already expressed interest in your brand.

### Pay-Per-Click

A concise and compelling pay-per-click (PPC) campaign can generate traffic for your sale and make sure you have a list of ready-to-buy potential consumers. Use PPC advertising, like Google Ads or Facebook Ads, days before your flash sale to generate sign ups. PPC ads can direct shoppers to a landing page that provides an opt-in to join your waiting list. These shoppers are then the first to know when your flash sale goes live (typically, through an email marketing campaign). To capitalize on the increase in search volume, target and increase ad spend on relevant branded and non-branded keywords during your flash sale.

### Influencer Marketing

Investing in influencer marketing for your flash sale can be a profitable choice if your target audience spends a lot of time on social media. For every unique interest, people follow influencers who share their passion. Influencers can help businesses achieve more brand awareness, reach new customers, and generate more sales by introducing them to their existing, niche audience.
The most important step is finding the right influencer to partner with. Choose a micro-influencer who specializes in a demographic that aligns with your target audience. Tools like Social Audit Pro can help you analyze whether an influencer has a high number of legitimate followers and how fans interact with their content. Loyal followers of an influencer are likely to take the influencer’s recommendations and buy the products advertised during your flash sale.

### Email Nurture Campaigns

An email nurture campaign uses email marketing to turn subscribers into paying customers. This type of campaign typically involves sending a series of emails over the course of a few days with highly-targeted email copy and compelling calls to action.
For flash sale promotions, email campaigns drive the most traffic if you already have an existing email list. What’s better than reaching out to an audience that you know is already interested in your products? Then, you notify subscribers that the sale is live and only available for a short period of time, for example, “Act now to get 50% off!”

## 8. Track the ROI on Your Sale

Monitoring the progress of your flash sale and measuring ROI determines whether your flash sale is a success. If it isn’t, you can make changes and apply the lessons to your next sale. If it’s successful, you can [forecast future sales](https://www.salesforce.com/products/sales-cloud/features/quota-forecasting-software/) before your next launch.
Track the traffic and revenue you generate during the flash sale to assess what’s working (or what isn’t). This includes tracking the percentage of potential shoppers who visited your site and completed a desired action, such as adding an item to their cart.
Identify key performance indicators (KPIs) prior to launching your sale. For example, what are you trying to achieve during this sale? Should you measure the percentage of new customers, the amount of inventory sold, or customer re-engagement? Make sure you know what you are trying to achieve from the very beginning, and what KPIs to measure so that you can determine the ROI on your campaigns. By keeping track of your completed goals and monitoring your conversion rate, you can uncover bottlenecks in your campaign and fix them during your sale to maximize your revenue potential.

## 9. Have Customer Service at the Ready

Over the past few years, more customers are looking for digital customer service compared to support over the phone. This indicates that customers might have shifted to alternative, digital channels of customer service, such as chat or social media.
What does this mean for you? Prepare your business to handle an influx of online customer questions or inquiries during your high-traffic flash sales. For example, you might equip your service team with scripts to help them navigate customer inquiries or provide discount codes to offer to dissatisfied customers. The key is to create a consistent customer experience, even if your team is assisting a higher number of customers than usual.
Do you have a system in place to handle an increase in customer service requests? If not, consider scalable service solutions. Use [Agentforce Service](https://www.salesforce.com/products/service-cloud/overview/) to help more customers faster — even during a high-volume flash sale. Plus, give your customer service team the tools they must handle more inquiries with our service tools, which give agents a single view of the customer across multiple purchasing touch-points. These mobile-ready tools can help your team handle flash sale inquiries from any device, resolving issues faster and preventing cart abandonment during your sale.

## 10. Follow Up with Shoppers

After new shoppers participate in your flash sale, what next? In one word, the goal is retention.
To maximize repeat sales, offer shoppers additional deals on their next purchase. Also consider running retargeting campaigns via paid ads to encourage them to buy new products or opt-in to additional deals.
Finally, send an email post-purchase asking shoppers to write a review and post about their purchase on social media. Be careful not to bombard your shoppers with too many campaigns and offers. Tailor your campaigns to their interests to build brand trust, and turn first-time shoppers into lifelong, loyal customers!

<!-- document id=0e004d595d9d9e36784b5d0c8b578aa876778bec1e879947e9a51b9bb2fce6e3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-layouts.md -->

# Layouts

Define all visible elements in the layout section. The elements are structured in rows spread across a 12-column grid.

There can be:

- Form elements inside an attribute form widget
- Attributes inside a layout widget
- Specialized widgets for certain customizable areas

By using `width` on an element, modify the number of columns this element occupies. Embed widgets inside a layout or form widget, for example, a product_unit_price inside a form widget. For advanced configuration, both rows and cells can also have conditions to show elements based on the value of attributes.

## Layout Row Configuration

The following table describes layout row configuration:

| Name      | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| layout    | array  | As array of layout columns                 |
| condition | string | An expression to switch the row visibility |

## Layout Column Configuration

The following table describes layout column configuration:

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>The widget ID</td></tr><tr><td>attribute</td><td>string</td><td>The attribute reference inside a form or layout widget

```json
"layout": [
{
"attribute": "content1"
}
]
```

</td></tr><tr><td>width</td><td>integer (1 <= width <= 12)</td><td>Number of grid cells the column occupies</td></tr><tr><td>offset</td><td>integer (1 <= width <= 12)</td><td>Number of grid sets to leave empty before this element. Either Offset + Width total 12 or "end".

```json
"layout": [
  {
    "attribute": "content1",
    "width": 6
  },
  {
    "attribute": "content2",
    "width": 6
  },
  {
    "attribute": "content3",
    "width": 6,
    "offset": 6
  }
]
```

</td></tr><tr><td>end</td><td>Boolean</td><td>Specify to leave empty until the end of the row.

```json
"layout": [
  {
    "attribute": "content1",
    "width": 6,
    "end": true
  },
  {
    "attribute": "content2",
    "width": 6
  },
  {
    "attribute": "content3",
    "width": 6
  }
]
```

</td></tr><tr><td>condition</td><td>string</td><td>An expression to switch the row visibility.</td></tr></tbody></table>

## Layout Conditions

Layout conditions include the following:

| Operator | Description                                                                                                                        | Example      |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| >        | Greater than operator. Evaluates to true if the left side is greater that the right side.                                          | 5 > 3        |
| >=       | Greater than or equal to operator. Evaluates to true if the left side is greater than or equal to the right side.                  | 5 >= 5       |
| \<       | Less than operator. Evaluates to true if the left side is less than the right side.                                                | 3 \< 5       |
| \<=      | Less than or equal to operator. Evaluates to true if the left side is less than or equal to the right side.                        | 3 \<= 3      |
| ==       | Equality comparison. Returns true if the left side equals the right side. Does not check type equality.                            | 3 == '3'     |
| !=       | Inequality comparison. Returns true if the left side equals the value and type of the right side. Does not check type inequality.  | 3 != 2       |
| ===      | Strict equality comparison. Returns true if the left side equals the value and type of the right side.                             | 3 === 3      |
| !==      | Strict inequality comparison. Returns true if the left side doesn't equal the value of the right side and both types are the same. | 3 !== '3'    |
| !        | Negation operator. Negates the Boolean value.                                                                                      | !true        |
| &&       | Logical AND operator.                                                                                                              | true && true |

The following sample condition would hide the associated widget until the current product doesn't require variation selection anymore.

```
"condition": "!type.master"
```

## Configuring Width

You use the `width` property to specify how many columns an element spans.

The following is an example of specifying the width. Because of the nested layout, the same result would be achieved without `width`.

```json
{
  "id": "address",
  "layout": [
    {
      "layout": [
        {
          "attribute": "first_name",
          "width": 6
        },
        {
          "attribute": "last_name",
          "width": 6
        }
      ]
    },
    {
      "layout": [
        {
          "attribute": "postal_code",
          "width": 6
        },
        {
          "attribute": "city",
          "width": 6
        }
      ]
    }
  ]
}
```

The following is a sample for `width` without nested layouts:

```json
{
  "id": "address",
  "layout": [
    {
      "attribute": "first_name",
      "width": 6
    },
    {
      "attribute": "last_name",
      "width": 6
    },
    {
      "attribute": "postal_code",
      "width": 6
    },
    {
      "attribute": "city",
      "width": 6
    }
  ]
}
```

It results in a layout like this:

![Example billing address layout with address fields spanning 6 columns using the width property](https://developer.salesforce.com/media/b2c-commerce/b2c_customer_service_center_billing_address_width_6.png)

## Combining Elements

By using the property `suppress_new_column`, combine multiple elements in one cell. Each element with the property `suppress_new_column:true` is added to the cell of the previous element.

```json
{
  "id": "address",
  "layout": [
    {
      "layout": [
        {
          "attribute": "first_name"
        },
        {
          "attribute": "last_name",
          "suppress_new_column": true
        }
      ]
    },
    {
      "layout": [
        {
          "attribute": "postal_code"
        },
        {
          "attribute": "city",
          "suppress_new_column": true
        }
      ]
    }
  ]
}
```

Each element with the property `suppress_new_column:true` is added to the cell of the previous element.

![Example billing address layout showing suppress_new_column combining first name and last name into one cell](https://developer.salesforce.com/media/b2c-commerce/b2c_customer_service_center_billing_address_suppress_column.png)

<!-- document id=651c30f6f7e2eee11c87f4acc57f306c2ae9bdbcf1e8b38997fb06d5a2b081ff url=/developer/current/en-us/commerce-cloud/sfra/guides/sfra-learn-more.md -->

# Learn More

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


- [SFRA Trailhead](https://trailhead.salesforce.com/en/content/learn/modules/cc-digital-for-developers/digital-ref-architecture)
- [B2C Commerce Developer with SFRA](https://trailhead.salesforce.com/en/academy/classes/ccd102-b2c-commerce-developer-with-sfra/) (instructor-led training course)
- [SFRA - UX Deep Dive](https://salesforce.vidyard.com/watch/RC2UL1wr9ht3rdC2Trz7wN)
- [SFRA - Technical Deep Dive](https://salesforce.vidyard.com/watch/ehBFfZBd2PxcbaivjMJHE5)
- SFRA - Developer Fast Path Modules:
  - [Module 1: Kickoff](https://share.vidyard.com/watch/Fb8F2oEzjmhTigF73rQPLD?)
  - [Module 2: Cartridges and Controllers](https://share.vidyard.com/watch/ASVVEWfhkJ2uPDeoxbosL3?)
  - [Module 3: Models, ISML, and Client-Side JavaScript](https://share.vidyard.com/watch/zwNXrskJgzysXJZo7CNaC5?)
  - [Module 4: Forms, Transactions, and Middleware Events](https://share.vidyard.com/watch/XdAJam3xCAMQ7UYrAVxSwW)
  - [Module 5: Page Designer and Job Framework](https://share.vidyard.com/watch/j29VTc9BbqpyH7kkrubW2k?)
  - [Module 6: OCAPI and Web Service Framework](https://share.vidyard.com/watch/JUR9eco8noLmS11dQA1CKt?)

## Find SFRA Tools

- [SFRA Wireframes/Comps with Annotations](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/SFRA_Wireframes_May_2020.pdf) (PDF)
- [SFRA Wireframes/Comps with Annotations](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/SFRA_Wireframes_May_2020.docx) (Word)
- [SFRA Design Document](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/SFRA_Design_Sketch_May_2020.sketch) (Sketch)
- [SFRA GitHub Code Repository](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture) (requires Account Manager credentials)
- [SFRA Setup and GitHub Access Instructions](https://developer.salesforce.com/docs/commerce/sfra/guide/b2c-build-sfra.html)

## Explore Additional Resources

- [Mobile Design Best Practices Guide](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/Mobile_Design_Best_Practice_Guide.pdf) (PDF)
- [Partner Blog by Blue Acorn: SFRA Top Questions Answered](https://blueacorn.com/blog/sfra-top-questions-answered/)
- [Partner Blog by Bluewolf: What to Know About SFRA](https://www.bluewolf.com/bluewolf-now/what-know-about-storefront-reference-architecture)
- [B2C Commerce Continuous Integration and Delivery Implementation](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/CI_CD_Implementation_Guide.pdf)
- [SFRA Live Demo Site](https://production-sitegenesis-dw.demandware.net/s/RefArch/home?lang=en_US)
- [Implement a Progressive Web App (PWA) on Salesforce B2C Commerce](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/Implement_a_Progressive_Web_App.pdf)
- [Caching Strategies for Salesforce B2C Commerce](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/CachingStrategiesforSalesforceB2CCommerce.pdf)

<!-- document id=ae944542066a49af30a698532251bed517ae749558e0bf2a8cff2c81a216204e url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/protect-storefront.md -->

# Limit Access to a Storefront Under Development

To limit access to a storefront under development so that only users from your organization can view it, enable Protected Storefronts in Business Manager for the associated site. The protected storefront's environment requires a basic auth password that organization users provide.

**important:** Protected Storefront is enabled by default for new Managed Runtime environments.

## Enable a Protected Storefront

1. (Optional) For storefronts not created in Business Manager or through storefront export and import, link them to Business Manager.

   Before linking, make sure the correct B2C Commerce instance and site IDs are configured for the MRT environment. To verify these settings in [Runtime Admin](https://runtime.commercecloud.com/login), go to the project and environment, and then click **Environment Settings**.

   For linking steps, see [Link an Existing Storefront to B2C Commerce](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-link-storefront.md).

2. Set the site status and options.

   a. In **Administration > Sites > Manage Sites**, click the site, and then click the Site Status tab.

   b. For the Site Status, select `Online (Protected)`.

   c. Select **Access using shared password**.

   ![Select a site status and shared password for the protected storefront](https://developer.salesforce.com/docs/media/sfnext/sfnext-site-settings-updated.png '{"class": "image-xl"}')

   d. Enter a shared password.

   e. Select **Apply to Composable Storefront and StorefrontNext**. This ensures all environments associated with the site require a password.

   This option is available starting with release 26.8. On earlier releases, this checkbox doesn't appear.

   f. Deselect **Access using user’s password or access key** and **Access using Storefront Toolkit** — these options don’t apply to PWA Kit storefronts or Storefront Next. Click **Apply**.

   Changes can take up to 5 minutes to take effect.

## Limitations

- Protected Storefronts support only the shared password option.
- For multi-site storefronts, enabling Protected Storefront on any one of the associated sites results in the environment requiring a basic auth password. If sites are configured with different passwords, the environment accepts any of the passwords.
- For sites associated with multiple MRT environments, enabling Protected Storefront results in all environments requiring a basic auth password.
- For sites with Protected Storefront enabled before you associated a Managed Runtime environment, disable and re-enable the Protected Storefront settings for the changes to take effect.

<!-- document id=eaeb32e28b26a7da40498c3f70d01c91d346f79bd943aae5c99fc896a6c5f711 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-protect-storefront.md -->

# Limit Access to a Storefront Under Development

To limit access to a storefront under development so that only users from your organization can view it, enable Protected Storefronts in Business Manager for the associated site. The protected storefront's environment requires a basic auth password that organization users provide.

**important:** Protected Storefront is enabled by default for new Managed Runtime environments.

## Enable a Protected Storefront

1. (Optional) For storefronts not created in Business Manager or through storefront export & import, link them to Business Manager.

   Before linking, make sure the correct B2C Commerce instance and site IDs are configured for the MRT environment. To verify these settings in [Runtime Admin](https://runtime.commercecloud.com/login), go to the project and environment, and then click **Environment Settings**.

   For linking steps, see [Link an Existing Storefront to B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-link-storefront.md).

2. Set the site status and options.

   a. In **Administration > Sites > Manage Sites**, click the site, and then click the Site Status tab.

   b. For the Site Status, select `Online (Protected)`.

   c. Select **Access using shared password**.

   ![Select a site status and shared password for the protected storefront](https://developer.salesforce.com/docs/media/sfnext/sfnext-site-settings-updated.png '{"class": "image-xl"}')

   d. Enter a shared password.

   e. Select **Apply to Composable Storefront and StorefrontNext**. This ensures all environments associated with the site require a password.

   This option is available starting with release 26.8. On earlier releases, this checkbox doesn't appear.

   f. Deselect **Access using user’s password or access key** and **Access using Storefront Toolkit** — these options don’t apply to PWA Kit storefronts or Storefront Next. Click **Apply**.

   Changes can take up to 5 minutes to take effect.

## Limitations

- Protected Storefronts support only the shared password option.
- For multi-site storefronts, enabling Protected Storefront on any one of the associated sites results in the environment requiring a basic auth password. If sites are configured with different passwords, the environment accepts any of the passwords.
- For sites associated with multiple MRT environments, enabling Protected Storefront results in all environments requiring a basic auth password.
- For sites with Protected Storefront enabled before you associated a Managed Runtime environment, disable and re-enable the Protected Storefront settings for the changes to take effect.

<!-- document id=206c7fa83516afd2c17cb0df1eb5de81280076524a5a7b4be785be14ad42223b url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-link-storefront.md -->

# Link an Existing Storefront to B2C Commerce

Link storefronts that were created outside Business Manager, such as Composable Storefront (PWA Kit) and Storefront Next storefronts created with the Managed Runtime API or CLI. Linking makes those storefronts available in Page Designer and Storefront Preview. It also protects access while they're in development and syncs their site preferences to the Managed Runtime (MRT) data store. The storefront link makes the MRT environment and storefront data available so that Page Designer and Storefront Preview can identify which environment to associate with the storefront and site.

Use this option only for a Managed Runtime project that isn't already linked to another B2C Commerce instance. To move a storefront that's already linked elsewhere, export and import it instead. See [Site Import/Export to Copy Instances and Development Testing in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_using_site_import_export_to_copy_instances.htm&type=5) in _Salesforce Help_.

## Prerequisites

Business Administrator role in Account Manager or a role for the Business Manager Module and Organization context with read-write access to storefronts. See [Create a Role in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_roles.htm&type=5) in _Salesforce Help_.

## Steps

To link a storefront to B2C Commerce:

1.  In Business Manager, click the App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png), and then select **Administration > Sites > Storefronts**. Click **Add Existing Storefront**, and then select **Link a Storefront from Managed Runtime**.

    Managed Runtime (MRT) projects that aren't already linked to an instance appear.

2.  Select one or more projects to link.

    ![Link an existing project to B2C Commerce](https://developer.salesforce.com/docs/media/sfnext/sfnext-link-existing.png '{"class": "image-lg"}')

3.  Optionally, edit the storefront name and the associated sites.
4.  Click **Link**.

## See Also

- [Managed Runtime (MRT) Data Store](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-data-store.md)

<!-- document id=c23f3a0ddf781d1dd3ac0007f57e43555f25ff4f945f1a106aa909393644514d url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-github-connect.md -->

# Link Your Storefront to a GitHub Repository in Business Manager

Connect a storefront that was set up with the Salesforce CLI option to an existing GitHub repository in Business Manager. Linking a repository to GitHub enables version control, team collaboration, and CI/CD pipelines for your storefront code. Also, it provides the prerequisites required to install Commerce Apps in your storefront.

**note:** This feature links existing repositories only and doesn't create a new one. To create a storefront with a GitHub repository, see [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md).

## Prerequisites

- A GitHub account with the owner role in the GitHub organization. See the GitHub documentation for organization roles in [Permissions of predefined roles](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-predefined-organization-roles#permissions-of-predefined-roles), and [Permission levels for a personal account repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/permission-levels-for-a-personal-account-repository) for personal accounts.
- A GitHub repository created in a GitHub organization for team collaboration or your personal GitHub account.

## Steps

To connect your storefront to a GitHub repository:

1. Complete the storefront setup for the Salesforce CLI option. See [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md).
2. In the storefront detail page, under the **Source Code** section, click **Connect to GitHub**.
3. Select your GitHub account.
4. Select a GitHub organization to share the repository with your team, or select a personal account for your own use. Make sure that you have owner access to the GitHub organization that you select.
5. Log in to GitHub.
6. Grant the GitHub integration app access to all your repositories or specific repositories that you select from the list.
7. If you haven't installed the integration app earlier, click **Install**. If you installed the integration app earlier, click **Save**.
   You return to the storefront detail page.
8. Enter a name for an existing GitHub repository to connect the storefront to.

   ![Storefront setup page in Business Manager with a GitHub organization](https://developer.salesforce.com/docs/media/sfnext/sfnext-github-connect-fields.png '{"class": "image-lg"}')

   The storefront detail page now shows the connected GitHub repository under Source Code.

## See Also

- [Commerce Apps Overview](https://developer.salesforce.com/docs/commerce/sfnext/guide/commerce-apps-overview.html)
- [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md)

<!-- document id=e4aa5f4c48382fdcecb808f47ac321681433130b6357cd622f2b7a63f2f41066 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/throttle-rates.md -->

# Load Shedding and Rate Limiting

In SCAPI, we use different techniques to maximize the availability of your instance:

- Load shedding: APIs intentionally reject incoming requests to prevent the system from becoming overloaded.
- Rate limits: The frequency at which API clients can make requests in a given timeframe is controlled.

With these protection mechanisms, customers have uninterrupted access to your storefront.

## Load Shedding

If the system reaches a load threshold after scaling to maximum capacity, an HTTP 503 status code is returned. Load shedding is not used for checkout-related endpoints, such as the Shopper Baskets and Shopper Orders API families, to ensure that shoppers can complete an in-progress checkout.

Endpoints protected by load shedding include the following HTTP response headers:

- `sfdc_load`: System capacity in use (percentage): 0 to 100
- `sfdc_load_status`: Relative health of the system:
  - **WARN**: returned at 80% system capacity
  - **THROTTLE**: returned at 90% system capacity

When system capacity reaches 80% or 90%, the `sfdc_load_status` header is sent.
**note:** Some API families, such as SLAS and Omnichannel Inventory (OCI) only use rate limiting.

## Rate Limiting

To maintain the quality of service and improve platform stability, some B2C Commerce APIs have rate limits. When the number of requests received reaches the rate limit, the API returns an HTTP 429 response.

Rate limits can be adjusted based on specific customer scenarios or use cases. Contact your Customer Success Manager or Account Executive for questions around rate limits, use cases, and potential adjustments required for these rates.

**important:** All other endpoints not mentioned in this document are **no longer rate limited**.

### How to Read the Numbers

The following tables show the rate limits for different API families. The limit column shows the maximum number of requests allowed for specific endpoints.

### Shopper Login and API Access Service (SLAS)

SLAS enforces rate limits separately for each instance (SLAS tenant):
- Production instances: 24,000 requests per minute (RPM) per instance.
- Non-production instances: 500 RPM per instance. Each non-production instance (for example, a Development and a Staging instance) has its own 500 RPM allowance.
- 25 RPM for these endpoints: `getJwksUri` and `getWellknownOpenidConfiguration`.

When a rate limit is reached, SLAS responds with an HTTP 429 Too Many Requests with an HTTP response header Retry-After. The value in the Retry-After header is set to the time in seconds to wait before retrying the request:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
```

Your client code must be able to handle this response. To make sure that the next request is successful, always wait for the specified time before retrying.

### Omnichannel Inventory API Family

Be aware that the rate limits defined for OCI are rolling rate limits. This means that there’s a maximum number of concurrent requests allowed per time period defined. This helps OCI to prevent denial-of-service attacks by limiting the amount of traffic that can be sent from one organization over that defined period. The limit is measured in seconds and will reset at regular intervals so it's always "rolling" forward. If any organization exceeds its allotted quota for too long, it is blocked until its usage drops below the threshold again. By setting these rules, OCI is able to detect suspicious activity and block the traffic before it becomes a problem for all consumers of the service.

Rate limits are outlined below, by service, by endpoint, and by request type.

The following APIs are included in the omnichannel inventory API family:

#### Inventory Availability

Base URI: `https://{shortCode}.api.commercecloud.salesforce.com` +
`/inventory/availability/v1/organizations/{organizationId}` +

| Endpoint                                                              | Method | Requests | Second(s) |
| --------------------------------------------------------------------- | ------ | -------- | --------- |
| `/availability-records/actions/batch-update`                          | POST   | 100      | 10        |
| `/availability-records/actions/get-deltas`                            | POST   | 500      | 10        |
| `/availability-records/actions/get-availability`                      | POST   | 10,000   | 10        |
| `/locations/{locationId}/availability-records/skus/{sku}/{requestId}` | DELETE | 400      | 10        |
| `/locations/{locationId}/availability-records/skus/{sku}/{requestId}` | PUT    | 100      | 10        |
| `/locations/{locationId}/availability-records/skus/{sku}/{requestId}` | PATCH  | 100      | 10        |
| `/product-segmentation/actions/batch-update`                          | POST   | N/A      | N/A       |

#### Inventory Impex

Base URI: `https://{shortCode}.api.commercecloud.salesforce.com` +
`/inventory/impex/v1/organizations/{organizationId}` +

| Endpoint                                                    | Method | Requests | Second(s) |
| ----------------------------------------------------------- | ------ | -------- | --------- |
| `/availability-records/exports`                             | POST   | 40       | 60        |
| `/availability-records/exports/{exportId}`                  | DELETE | 40       | 60        |
| `/availability-records/exports/{exportId}/file-content`     | GET    | 40       | 60        |
| `/availability-records/exports/{exportId}/status`           | GET    | 20       | 10        |
| `/availability-records/imports`                             | POST   | 2        | 10        |
| `/availability-records/imports`                             | GET    | 2        | 10        |
| `/availability-records/imports/{importId}`                  | DELETE | 2        | 10        |
| `/availability-records/imports/{importId}/status`           | GET    | 20       | 10        |
| `/availability-records/imports/{importId}/file-content`     | GET    | 2        | 10        |
| `/availability-records/imports/uploadlink/{uploadLinkId}`   | POST   | 2        | 10        |
| `/event-log/exports`                                        | POST   | 40       | 60        |
| `/event-log/exports/{exportId}/status`                      | GET    | 40       | 60        |
| `/event-log/exports/{exportId}/file-content`                | GET    | 40       | 60        |
| `/location-graph/exports`                                   | POST   | 2        | 60        |
| `/location-graph/exports/{exportId}`                        | DELETE | 2        | 60        |
| `/location-graph/exports/{exportId}/status`                 | GET    | 20       | 10        |
| `/product-segmentation/imports`                             | POST   | 2        | 60        |
| `/product-segmentation/imports/{importId}`                  | DELETE | 2        | 60        |
| `/product-segmentation/imports/{importId}/file-content`     | GET    | 40       | 60        |
| `/product-segmentation/imports/{importId}/status`           | GET    | 20       | 10        |
| `/product-segmentation/imports/uploadLink/{uploadLinkId}`   | POST   | 2        | 60        |
| `/product-segmentation/exports`                             | POST   | 40       | 60        |
| `/product-segmentation/exports/{exportId}`                  | DELETE | 40       | 60        |
| `/product-segmentation/exports/{exportId}/file-content`     | GET    | 40       | 60        |
| `/product-segmentation/exports/{exportId}/status`           | GET    | 20       | 10        |
| `/transfers/location-graph/exports/{exportId}/file-content` | GET    | 2        | 60        |

#### Inventory Reservation

Base URI: `https://{shortCode}.api.commercecloud.salesforce.com` +
`/inventory/reservation/v1/organizations/{organizationId}` +

| Endpoint                                 | Method | Requests | Second(s) |
| ---------------------------------------- | ------ | -------- | --------- |
| `/fulfillments`                          | POST   | 10,000   | 10        |
| `/releases`                              | POST   | 10,000   | 10        |
| `/reservation-documents/{reservationId}` | PUT    | 10,000   | 10        |
| `/reservation-documents/{reservationId}` | PATCH  | 10,000   | 10        |
| `/transfers`                             | POST   | 10,000   | 10        |

<!-- document id=ccbb70b5c9417c2d76773428c86a57cb10102c9c1e1a1d06a63e3ef808789b05 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-suspense.md -->

# Loading States

Visual stability means that a page’s layout remains predictable and free of unexpected shifts as content loads. Loading states help achieve this and provide users with clear visual feedback about ongoing asynchronous operations, such as data fetching. React Router exposes two distinct mechanisms for managing loading states: declarative and imperative. Both mechanisms serve the same user-facing goal, communicating that an operation is in progress. They differ in where and how the loading state is defined and consumed. The appropriate choice depends on the scope and trigger of the async operation.

**note:** This documentation builds on [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md). In the context of classifying data as critical and non-critical, the term visual stability was mentioned in [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#data-classification), along with its relevance to user-perceived, or psychological, performance characteristics of a web app.

## Declarative Loading States

Declarative loading states are defined structurally in the component tree via React’s [`<Suspense/>`](https://react.dev/reference/react/Suspense) component.

`Suspense` acts as an asynchronous boundary: it intercepts rendering of any child component that isn’t yet ready and renders a `fallback` UI in its place until the operation completes. A child component signals that it’s not ready by throwing a Promise. Native React concepts, such as the [`use()`](https://react.dev/reference/react/use) hook, implement that convention, but so do React Router’s built-in [data streaming](https://reactrouter.com/how-to/suspense) or [`<Await/>`](https://reactrouter.com/api/components/Await) patterns.

`Suspense` integrates with React’s concurrent rendering model, which enables React to pause and resume rendering work without blocking the main thread. This is the foundational mechanism that enables both visual stability and responsive loading states in modern React apps.

### Loading State Fundamentals

To opt into a declarative loading state, a route loader returns a Promise without awaiting it. React Router exposes this unresolved Promise via the route’s loader data, which is then passed downstream for resolution in the component tree. A `Suspense` boundary renders the fallback until that Promise settles. Critical data is awaited in the loader and available immediately. Only non-critical data is deferred to a declarative loading state.

```jsx
// route.tsx
export async function loader() {
  const critical = await fetchCriticalData();
  const nonCritical = fetchNonCriticalData(); // intentionally not awaited
  return { critical, nonCritical };
}

export default function MyRoute() {
  const { critical, nonCritical } = useLoaderData();
  return <Suspense fallback={<Skeleton />}>{/* ... */}</Suspense>;
}
```

### The use() and Suspense Pattern

React 19 introduced the `use()` hook, which reads a Promise directly inside a component. When the Promise isn’t yet settled, `use()` suspends the component, triggering the nearest `Suspense` boundary without requiring any additional abstraction.

```jsx
function NonCriticalContent({ promise }) {
  const data = use(promise);
  return <div>{data}</div>;
}

<Suspense fallback={<Skeleton />}>
  <NonCriticalContent promise={nonCritical} />
</Suspense>;
```

**note:** While `use()` is portable and framework-agnostic, it has two relevant limitations in this context: it requires the consuming logic to be extracted into a separate component, and provides no built-in mechanism for co-locating error handling with the loading boundary.

### The Await and Suspense Pattern

React Router’s `Await` component addresses both limitations. It resolves the Promise inline via a render prop, eliminating the need for a separate component, and accepts an optional `errorElement` prop that catches rejections locally, keeping the loading and error boundary co-located with the async operation. For these reasons, `Await` is the recommended pattern when working within React Router’s data layer.

```jsx
<Suspense fallback={<Skeleton />}>
  <Await resolve={nonCritical}>{(resolved) => <NonCriticalContent data={resolved} />}</Await>
</Suspense>
```

When a Promise passed to `Await` rejects, the error propagates to the nearest error boundary in the tree. For more granular control, `Await` accepts an optional `errorElement` prop that catches rejections locally without affecting the rest of the route.

```jsx
<Suspense fallback={<Skeleton />}>
  <Await resolve={nonCritical} errorElement={<ErrorFallback />}>
    {(resolved) => <NonCriticalContent data={resolved} />}
  </Await>
</Suspense>
```

### Suspense Boundary Granularity

Multiple independent [`<Suspense>`](https://react.dev/reference/react/Suspense) boundaries can coexist within a single route, each encapsulating one async operation. Conceptually, each `<Suspense>` boundary acts like a `try/catch` for async. Everything inside the boundary is treated as a single loading unit, and content outside the boundary isn't affected by the suspensions within it.

This is why each promise **must** be wrapped in its own [`<Suspense>`](https://react.dev/reference/react/Suspense) boundary when a component consumes multiple asynchronous data sources. This applies to React Router's `<Await>`, React's `use()`, and any other suspending mechanism. If multiple promises share a single boundary, the faster promise resolves first and triggers a re-render. The still-pending slower promise then suspends the boundary again. Already-rendered content is torn down, and the fallback reappears. The result is visible content flicker and [layout shift](https://web.dev/articles/cls), which inflates interactivity metrics like [Interaction to Next Paint](https://web.dev/articles/inp) (INP).

With separate boundaries, each promise resolves independently. Fast content streams in and stays visible. Slower content continues loading with its own skeleton. For more details, see the React 18 architecture discussion on GitHub: [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37).

#### Correct: each Await has its own Suspense boundary

```jsx
<>
  <Suspense fallback={<SkeletonA />}>
    <Await resolve={promiseA}>{(resolved) => <ComponentA data={resolved} />}</Await>
  </Suspense>

  <Suspense fallback={<SkeletonB />}>
    <Await resolve={promiseB}>{(resolved) => <ComponentB data={resolved} />}</Await>
  </Suspense>
</>
```

#### Correct: use() wrapper components, each behind its own Suspense

```jsx
function ProductWrapper({ promise }: { promise: Promise<Product> }) {
  const product = use(promise);
  return <ProductContent product={product} />;
}

function ReviewsWrapper({ promise }: { promise: Promise<Reviews> }) {
  const reviews = use(promise);
  return <ReviewsSection reviews={reviews} />;
}

<div>
  <Suspense fallback={<ProductSkeleton />}>
    <ProductWrapper promise={productPromise} />
  </Suspense>
  <Suspense fallback={<ReviewsSkeleton />}>
    <ReviewsWrapper promise={reviewsPromise} />
  </Suspense>
</div>;
```

#### Anti-pattern: multiple promises sharing one boundary

```jsx
// ❌ BAD: Both Await children share a single Suspense boundary.
// When promise1 resolves first, Component1 renders briefly, then
// promise2 (still pending) suspends the boundary again — tearing
// down Component1 and showing <ComponentsSkeleton /> a second time.
<Suspense fallback={<ComponentsSkeleton />}>
  <div>
    <Await resolve={promise1}>{(resolved) => <Component1 resolved={resolved} />}</Await>
    <Await resolve={promise2}>{(resolved) => <Component2 resolved={resolved} />}</Await>
  </div>
</Suspense>
```

#### Anti-pattern: multiple use() calls in one component

```jsx
// ❌ BAD: Both use() calls suspend within the same component,
// which means they share the nearest parent Suspense boundary.
// Resolution of one promise triggers a re-render that re-suspends
// for the other, causing the same fallback thrashing.
function CombinedView({
  promise1,
  promise2,
}: {
  promise1: Promise<Component1Data>,
  promise2: Promise<Component2Data>,
}) {
  const data1 = use(promise1);
  const data2 = use(promise2);
  return (
    <>
      <Component1 resolved={data1} />
      <Component2 resolved={data2} />
    </>
  );
}

<Suspense fallback={<ComponentsSkeleton />}>
  <CombinedView promise1={promise1} promise2={promise2} />
</Suspense>;
```

#### Anti-pattern: nested Await inside one boundary

```jsx
// ❌ BAD: promise2 cannot even begin to resolve until promise1 is done,
// creating an artificial waterfall on top of the shared-boundary problem.
<Suspense fallback={<ComponentsSkeleton />}>
  <Await resolve={promise1}>
    {(resolved1) => (
      <>
        <Component1 resolved={resolved1} />
        <Await resolve={promise2}>{(resolved2) => <Component2 resolved={resolved2} />}</Await>
      </>
    )}
  </Await>
</Suspense>
```

**tip:** **Exception:** Truly dependent promises (for example, fetching details after a list) can share a boundary because they represent one logical loading unit.

### Promise Identity

A [`<Suspense>`](https://react.dev/reference/react/Suspense#reference) boundary identifies a pending promise by its reference, not by its value. When a child suspends, the boundary remembers _that exact promise object_ and waits for it to settle. On the next render, if the child hands back a different promise object — even one that resolves to the same data — the boundary treats it as new pending work, throws away what it just rendered, and shows the fallback again. With a fresh promise on every render, the cycle never ends and the fallback flickers forever. This applies equally to React's [`use()`](https://react.dev/reference/react/use#reference) and React Router's [`<Await>`](https://reactrouter.com/api/components/Await).

So the rule is: _the same logical operation must produce the same promise object across renders_.

Promises returned from a route `loader` satisfy this automatically — React Router preserves their identity for the lifetime of the active route match, whether read via `useLoaderData`, `useRouteLoaderData`, or `useOutletContext`. Anything composed in the component body with `Promise.all`, `Promise.race`, `.then(...)`, or any wrapper expression does not: the expression is evaluated on every render, producing a brand-new Promise object each time.

#### Anti-pattern: composing promises in the component

```jsx
// ❌ BAD: Promise.all returns a new promise every render, even with stable inputs.
// The Suspense boundary never sees the resolved reference and flickers forever.
function CombinedView() {
  const { promise1, promise2 } = useLoaderData();
  const combined = Promise.all([promise1, promise2]);
  return (
    <Suspense fallback={<Skeleton />}>
      <Await resolve={combined}>{([a, b]) => <Content a={a} b={b} />}</Await>
    </Suspense>
  );
}
```

`useMemo(() => Promise.all([p1, p2]), [p1, p2])` **doesn't** fix this: React discards the memo cache when the component suspends on initial mount (see [`useMemo` Caveats](https://react.dev/reference/react/useMemo#caveats), _"a state variable or a ref may be more appropriate"_. Failure mode is confirmed in [remix-run/remix#7392](https://github.com/remix-run/remix/issues/7392)).

#### Fix 1—Primary: Compose in the Loader

If the promises form one logical loading unit, combine them in the loader so `loaderData` exposes a single stable reference.

```jsx
// route.tsx
export async function loader() {
  const critical = await fetchCritical();
  // Created once per request; loaderData preserves identity across renders.
  const combined = Promise.all([fetchA(), fetchB()]);
  return { critical, combined };
}

function CombinedView() {
  const { combined } = useLoaderData();
  return (
    <Suspense fallback={<Skeleton />}>
      <Await resolve={combined}>{([a, b]) => <Content a={a} b={b} />}</Await>
    </Suspense>
  );
}
```

#### Fix 2—Primary: Split into Sibling Boundaries

If the promises don't truly form one loading unit, give each its own `<Suspense>` boundary so they resolve independently (see [Suspense Boundary Granularity](#suspense-boundary-granularity)). No composition needed.

```jsx
function CombinedView({ p1, p2 }) {
  return (
    <>
      <Suspense fallback={<SkeletonA />}>
        <Await resolve={p1}>{(a) => <SectionA data={a} />}</Await>
      </Suspense>
      <Suspense fallback={<SkeletonB />}>
        <Await resolve={p2}>{(b) => <SectionB data={b} />}</Await>
      </Suspense>
    </>
  );
}
```

#### Fix 3—Escape Hatch: Pin the Composed Promise Locally

Use only when neither primary fix applies (for example, the inputs arrive from a parent layout's `useOutletContext`, props, or fetcher hooks, and the consuming component must combine them). The examples assume `p1` and `p2` are already stable references; how they're obtained doesn't matter.

**Variant A — lazy `useState` pin.** Frozen for the component's lifetime; invalidate by remounting via `<Component key={inputIdentity} />`.

```jsx
function CombinedView({ p1, p2 }) {
  // Lazy initializer runs once per component lifetime and survives Suspense throws.
  const [combined] = useState(() => Promise.all([p1, p2]));
  return (
    <Suspense fallback={<Skeleton />}>
      <Await resolve={combined}>{…}</Await>
    </Suspense>
  );
}
```

**Variant B — `useRef` pin with manual re-pin.** Use when the consumer can't be remounted via `key` (for example, inputs change on revalidation while the component stays mounted). Repins when input identity changes. Survives Suspense throws.

```jsx
function CombinedView({ p1, p2 }) {
  const pinRef = useRef(null);
  if (pinRef.current === null || pinRef.current.inputs[0] !== p1 || pinRef.current.inputs[1] !== p2) {
    pinRef.current = { inputs: [p1, p2], combined: Promise.all([p1, p2]) };
  }
  return (
    <Suspense fallback={<Skeleton />}>
      <Await resolve={pinRef.current.combined}>{…}</Await>
    </Suspense>
  );
}
```

**note:** The same rule applies to `use()` wrappers: a child that calls `use(somePromise)` must receive a stable promise reference as a prop. Constructing the promise in the parent's render (for example, `<Child promise={Promise.all([a, b])} />`, `<Child promise={a.then(transform)} />`) re-suspends on every render for the same reason.

## Imperative Loading States

Imperative loading states aren’t defined structurally in the component tree but are read programmatically via hooks. Rather than triggering a `Suspense` boundary, these hooks expose the current state of an async operation as a discrete value that the component consumes conditionally. This makes them the appropriate choice for scenarios where a `Suspense` boundary is either unavailable or insufficient, such as global navigation feedback, out-of-band mutations, or manual revalidation. For details on how these hooks relate to the broader state model, see [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md).

### Summary

| Hook                                                                   | Scope                     | State property        | Triggers navigation |
| ---------------------------------------------------------------------- | ------------------------- | --------------------- | ------------------- |
| [`useNavigation()`](https://reactrouter.com/api/hooks/useNavigation)   | global / route transition | `navigation.state`    | no (reads state)    |
| [`useFetcher()`](https://reactrouter.com/api/hooks/useFetcher)         | component-level           | `fetcher.state`       | no                  |
| [`useFetchers()`](https://reactrouter.com/api/hooks/useFetchers)       | global (all active)       | `fetchers[].state`    | no                  |
| [`useRevalidator()`](https://reactrouter.com/api/hooks/useRevalidator) | current route             | `revalidator.state`   | no                  |
| [`useSubmit()`](https://reactrouter.com/api/hooks/useSubmit)           | component-level           | via `useNavigation()` | yes                 |

### The useNavigation() Hook

[`useNavigation()`](https://reactrouter.com/api/hooks/useNavigation) reflects the state of the current route transition. It covers the full navigation lifecycle, from when a transition is initiated until the destination route has fully loaded. `useNavigation()` is typically consumed in a root or layout component to provide a global loading indicator that covers all route transitions uniformly.

```jsx
const navigation = useNavigation();

return (
  <>
    {navigation.state === "loading" && <GlobalSpinner />}
    <Outlet />
  </>
);
```

`navigation.state` exposes three values:

- `idle` — no navigation in progress
- `loading` — a route transition is in progress and its loader is running
- `submitting` — a form submission or action is in progress

### The useFetcher() Hook

[`useFetcher()`](https://reactrouter.com/api/hooks/useFetcher) enables data fetching and action submissions outside of route transitions, without triggering a navigation. It’s the appropriate mechanism for out-of-band operations such as inline mutations, background data refreshes, or optimistic UI updates. Unlike `useNavigation()`, `useFetcher()` is scoped to the specific operation it initiates, making it suitable for granular, component-level loading feedback.

```jsx
const fetcher = useFetcher();

return (
  <fetcher.Form method="post" action="/api/update">
    <button type="submit">{fetcher.state === "submitting" ? "Saving..." : "Save"}</button>
  </fetcher.Form>
);
```

`fetcher.state` mirrors `useNavigation().state` in structure:

- `idle` — no operation in progress
- `loading` — fetching data from a loader
- `submitting` — submitting to an action

### The useFetchers() Hook

[`useFetchers()`](https://reactrouter.com/api/hooks/useFetchers) returns an array of all in-flight fetchers across the application. While `useFetcher()` is scoped to a single component, `useFetchers()` provides a global view of all active fetcher operations. This is useful for aggregate loading indicators. For example, showing a single "saving" badge when any background mutation is in progress.

```jsx
import { useFetchers } from "react-router";

function GlobalSavingIndicator() {
  const fetchers = useFetchers();
  const isSaving = fetchers.some((f) => f.state !== "idle");

  if (!isSaving) {
    return null;
  }
  return <div className="saving-indicator">Saving…</div>;
}
```

Each entry in the array mirrors the shape of a single `useFetcher()` instance, exposing `state`, `formData`, `data`, and other properties. The mirroring enables patterns, such as counting active operations or building optimistic lists from multiple concurrent mutations.

### The useRevalidator() Hook

[`useRevalidator()`](https://reactrouter.com/api/hooks/useRevalidator) manually triggers revalidation of the current route’s loader data, outside the standard navigation lifecycle. It’s relevant when external events invalidate the current data and a reload is required without a full navigation.

```jsx
const revalidator = useRevalidator();

return (
  <button onClick={() => revalidator.revalidate()} disabled={revalidator.state === "loading"}>
    {revalidator.state === "loading" ? "Refreshing..." : "Refresh"}
  </button>
);
```

`revalidator.state` exposes two values:

- `idle` — no revalidation in progress
- `loading` — revalidation is running

### The useSubmit() Hook

[`useSubmit()`](https://reactrouter.com/api/hooks/useSubmit) programmatically triggers form submissions or action calls without requiring a `<Form>` element. It doesn’t expose its own state. The resulting async operation is reflected in `useNavigation().state`, which transitions to `submitting` for the duration of the action. Because `useSubmit()` delegates state to `useNavigation()`, it’s typically paired with it explicitly when loading feedback is required.

```jsx
const submit = useSubmit();
const navigation = useNavigation();

return (
  <button
    onClick={() => submit({ key: "value" }, { method: "post", action: "/api/update" })}
    disabled={navigation.state === "submitting"}
  >
    {navigation.state === "submitting" ? "Submitting..." : "Submit"}
  </button>
);
```

## Visual Feedback Patterns

Visual feedback patterns determine how loading states are communicated to the user. The goal is twofold: signal that an operation is in progress, and maintain visual stability so that the UI doesn’t shift unexpectedly when content resolves. The appropriate pattern depends on the scope of the operation and the nature of the content being loaded.

### Skeleton Screens vs. Spinners

Spinners communicate that something is happening without making any assumptions about the shape of the incoming content. They’re appropriate for global or indeterminate operations where the layout of the resolved content is unknown or irrelevant.

```jsx
<Suspense fallback={<Spinner />}>
  <Await resolve={promise}>{(resolved) => <Component data={resolved} />}</Await>
</Suspense>
```

Skeleton screens reserve the approximate layout of the incoming content before it resolves. This reduces perceived loading time and prevents layout shift, as the resolved content occupies space that was already allocated.

```jsx
<Suspense fallback={<CardSkeleton />}>
  <Await resolve={promise}>{(resolved) => <Card data={resolved} />}</Await>
</Suspense>
```

Skeleton screens are preferable when the shape of the resolved content is known and stable. Spinners are sufficient for transient, global, or low-visibility operations where layout continuity isn’t a concern.

**tip:** Skeletons, like any other React components, are subject to client-side hydration. If skeleton structures are themselves complex, they can carry a non-trivial rendering cost. For content outside the initial viewport, this cost can outweigh the benefit: users don’t perceive layout shift for content they can’t yet see, and the skeleton itself contributes to the hydration workload without improving the visible experience. In these cases, a spinner or a simpler fallback is the more pragmatic choice, even when the structure of the expected content is known.

### Global vs. Local Loading Indicators

A global loading indicator communicates the state of the app as a whole, typically a progress bar or spinner in the navigation area. It’s appropriate for route transitions where the entire page content is being replaced.

```jsx
// in a root or layout component
const navigation = useNavigation();

return (
  <>
    {navigation.state === "loading" && <ProgressBar />}
    <Outlet />
  </>
);
```

A local loading indicator is scoped to the specific UI region affected by the operation. It’s appropriate for partial updates, such as deferred data within a route or out-of-band mutations via `useFetcher()`, where the rest of the UI remains interactive.

```jsx
const fetcher = useFetcher();

return (
  <section>{fetcher.state === "loading" ? <Skeleton /> : <Content data={fetcher.data} />}</section>
);
```

Global and local indicators aren’t mutually exclusive. A route transition can warrant both a global progress indicator and local skeleton screens for individual content regions.

### Preventing Layout Shift

Layout shift occurs when content renders into a space that wasn’t reserved for it, causing surrounding elements to reposition. Layout shift degrades both visual stability and user-perceived performance. It’s measured by the [Cumulative Layout Shift (CLS)](https://web.dev/articles/cls) metric.

The primary mitigation is to reserve space for loading content before it resolves. Skeleton screens are the most direct approach, but explicit dimension constraints on container elements achieve the same effect when a skeleton isn’t warranted.

```jsx
// reserve space via explicit dimensions
<div style={{ minHeight: "200px" }}>
  <Suspense fallback={null}>
    <Await resolve={data}>{(resolved) => <Component data={resolved} />}</Await>
  </Suspense>
</div>
```

Avoid using `fallback={null}` without reserving space. Rendering nothing during loading and then injecting content will shift the layout. If no visual fallback is desired, the container must still maintain its dimensions.

### Optimistic UI: No Loading States

Optimistic UI skips the loading state entirely by assuming that an operation will succeed and updating the UI immediately. The actual server response either confirms the update or triggers a rollback. This is the most responsive pattern available, but introduces complexity around error handling and state consistency.

Optimistic UI is appropriate when the probability of failure is low and the operation is reversible. It’s not suitable for destructive or irreversible actions where a failed rollback leaves the UI in an inconsistent state.

`useFetcher()` exposes submitted form data via `fetcher.formData` before the action completes, enabling optimistic updates without external state management. For implementation patterns using `fetcher.formData` and `useOptimistic`, see [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md#optimistic-state).

<!-- document id=9d24a82e591b1d2a0428e9fec6189eb973c3286aabc30437c11f6362ddb704f4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-load-task-configuration-ds.md -->

# LoadTaskConfiguration.ds

LoadTaskConfiguration.ds loads the configuration for a task name from a custom object.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/**
 * Loads the configuration for the given task name from a custom object.
 *
 * @input TaskName  : String    Name of the configuration
 * @input sampleLogger  : Object    Sample logger input for Sample logger
 * @output TaskConfiguration  : dw.object.CustomObject    Configuration for the task
 * @output sampleLogger  : Object    Sample logger debug output for Sample logger
 * @output sampleError  : Object    Sample error output for Sample logger */
importPackage(dw.system);
importPackage(dw.object);

// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");

var CUSTOM_OBJECT_NAME = "TASK_CONFIGURATION";

function execute(pdict: PipelineDictionary): Number {
    // Sample Logging var
    var _context: String = new Context("LoadTaskConfiguration.ds");
    var _logger: Log = Log.getLogger(pdict);

    var taskName: String = pdict.TaskName;

    try {
        var taskConfiguration: CustomObject = CustomObjectMgr.getCustomObject(CUSTOM_OBJECT_NAME, taskName);

        _logger.debug(_context, "Loaded task configuration '" + taskName + "'");

        pdict.TaskConfiguration = taskConfiguration;
    } catch (e) {
        // sample Logging wrap error into custom exception
        var exception: sampleException = new sampleException(_context, "Error occurred calling Task configuration ", e);



        // sample Logging call into error handler
        _logger.error(_context, "Error occurred calling Task configuration " + exception);
        pdict.sampleError = exception;



        return PIPELET_ERROR;
    }
    return PIPELET_NEXT;
}
```

<!-- document id=55425b56025d3355512a4bea9adfc8339696427d40223fdeb9c8d1e4cca9117a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/localization/b2c-localization.md -->

# Localization

Salesforce B2C Commerce is localizable, from business objects (for example, catalogs, products, and attributes) to the storefront.

To localize your B2C Commerce site:

1.  Identify which components of your storefront require localization, for example, content assets, products, product attributes, and currency.
2.  Determine how to architect localization for your business: processed using localized templates or properties files, depending on your approach.
3.  Identify which languages you support and how they interrelate. For example, when creating US and Spanish storefront versions, you might want to use the same underlying business objects. When in the storefront, a user can select a location, which specifies to B2C Commerce the file set from which to select. Alternatively, when supporting multiple European languages, you could offer products that are unique for a particular country, thus requiring unique catalog data for each locale.
4.  Configure locale settings at the organization and site level.

There are some situations, however, where localization isn't possible.

**note:** B2C Commerce supports Asian languages.

## Currency

B2C Commerce includes current world currency data. There’s no need to add, edit, or remove currencies through Business Manager. However, define how a currency appears for a locale if needed. For example, the decimal positive pattern is defined as `#,##0.00` for the Default (default) locale.

The appropriate currency is automatically selected in the storefront based on the selected locale. The currency assigned to the default locale is the lead locale of B2C Commerce.

**note:** B2C Commerce uses the $ for United States dollar (USD). For other currencies, the $ symbol is prefixed with letters based on common convention. For example, A\$ denotes the Australian dollar.

## Two-Character Country Codes

B2C Commerce uses country codes for various features, such as:

- Customer address and order address
- Tax jurisdictions
- Store locator
- Rule evaluation of a dynamic customer group
- Shipping address exclusion
- Product lists
- Geolocations

B2C Commerce supports two-character country codes per _ISO 3166-1-alpha-2_ only. B2C Commerce doesn't support other standards, such as 3-letter codes. Using them might result in some features no longer working correctly. For example, if you store 3-letter country codes in order addresses, the export of such orders would fail. Export files would be invalid per the B2C Commerce order.xsd schema.

See the API documentation on the following:

- Package: dw.customer
- Class: CustomerAddress
- Property: countryCode : EnumValue (The customer's country code).

## Locales

A locale represents a specific geographical, political, or cultural region. Salesforce B2C Commerce supports multiple locales for both the Business Manager user interface, and the underlying storefront site data.

B2C Commerce supports language-specific locales, in addition to country-specific locales, with an extended resource lookup sequence for all localized data.

- Language-specific locales are included in Business Manager global preferences.
- Create locale-specific folders for image upload. When you create or manage language-specific image folders in Business Manager, the new locales appear in the locale select box for creating language-specific image folders, as for any other locale.
- The lookup fallback sequence for all localizable resources (business object data, images, templates, messages) is consistent across B2C Commerce.

**note:** If you use the United Arab Emirates Dirham (AED) currency, we recommend that you show the amount value prefixed with the abbreviation currency, for example, (AED) 250. B2C Commerce doesn’t currently handle certain UTF characters that are right-to-left. For example, gift certificates purchased under the AED currency don’t show the amount under the list view. The list view is displayed when you click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Online Marketing** > **Gift Certificates**.

### Configuring Locales

B2C Commerce is structured as an organization containing one or more sites (storefronts). To configure locales:

1.  Use global preferences to configure the organization locales settings (for example, the Business Manager default user interface language, the default data language, and activating/deactivating locales), instance time zones, and store locator data (geolocation).
2.  Use site preferences to configure storefront site currencies, locales, default country codes, and store lookup units (miles versus kilometers).
3.  Configure locale-specific URLs.
4.  Assign preferred locales by user for the Business Manager user interface.
5.  Assign preferred locales for the underlying B2C Commerce data, such as products, content, orders, and customers.

**tip:** If you support multiple languages across sites, you might want to use a second language for your default language. For example, you could use French for the default language for France, Switzerland, and Luxembourg, but use country-specific resources for a portion of the data. In this case, typically you have multiple sites with shared resources and want to localize most of your data based on language rather than region. While sites using the same language (such as _en_), but different country (such as _en_US_, _en_CA_), might use some region or country-specific resources, most of the resources are the same.

**note:** Some Business Manager elements can't be localized.

### Business Manager Locales

Business Manager supports multiple languages in both its user interface and in the underlying data that is created, edited, and shown within it to be used in the storefront. Configure locales separately for:

- Viewing the application
- Managing the data in a target language

For example, a user could view English products and content using a Japanese Business Manager.

There are two ways to select the Business Manager user interface locale:

- Administrator: the administrator selects a preferred locale for the Business Manager display language. The interface shows a list of possible languages. The administrator can assign the preferred locale when creating a user profile, or editing an existing profile.
- User: to select a different Business Manager display language, the user edits their user profile. The new locale appears for that user until the user selects another language.

To set a locale as preselected for all Business Manager pages that include localized attributes, you define the preferred locale (language) in a user profile. This locale (language) must have been previously activated for the instance through global preferences. This sets locales for:

- Product
- Catalog
- Content
- Search
- Promotion rules
- Customers
- Custom objects
- Ordering
- Organization
- Site development

To edit the locale, including specifying localized formats for attributes, dates, currency, quantity, and input settings, click the **Locale ID** link. If you want B2C Commerce to give you default formats, click **Prefill** after you select the locale.

### Dictionary Fallback

Define how linguistic search rules (stop words, category name exclusions, synonyms, hypernyms, compound words, common phrases, search suggestions, and stemming exceptions) are applied in a multi-locale site.

When you’ve configured the required locales, you must build search indexes for those locales. When customers use those locales (languages) in their search criteria, B2C Commerce is able to respond appropriately.

### Locale Fallback

Salesforce B2C Commerce provides you with a locale fallback mechanism to meet your site's multi-locale requirements. By default, the country locale (for example, _en_US_) inherits data from the respective language locale (_en_), and the language locale (_en_) inherits from the locale _default_. Configure locale inheritance as needed.

Configure a locale to skip a locale in its fallback chain, or to not have any fallback. For example, en_US falls back to en and then to default. Configure en_US to fall back directly to default, or configure en_US to not have any fallback.

**note:** The application server uses the locale fallback that you configure only when looking up localizable attributes or properties of objects of subclasses of PersistentObject, such as Product. The application server doesn’t consider the fallback locale when locating ISML templates, web forms, resource files in cartridges, or static content such as images.

If a locale is configured as the fallback for another locale, you can't delete it: an error message appears.

For example:

- You configure en_US > en > default.
- You can't delete en because it's the fallback for en_US.
- Similarly, if you attempt to import en in delete mode, an error message appears in the import log.

**Disabling Locale Fallback**

Disable the fallback behavior for each locale.

For example:

- A product description is in the _en_ locale
- For the _en_ locale, the fallback is disabled and there’s no description for that product
- Nothing is returned

### Localization Considerations

Most elements of the Business Manager user interface are localizable. You see the configured language throughout the application. However, there are some situations where localization isn't possible

The following table describes situations where localization isn't possible.

| Element                                      | Description                                                                                                                                                                                                       |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Attributes used for column titles in grids   | Attributes defined by a customer in the database appear as they were entered. Some column headers in an otherwise localized grid appear untranslated.                                                             |
| Attributes used for section and field labels | Attributes defined by the customer in the database that are used on many pages as field labels, appear untranslated. On a page with many such custom attributes, 90% of the page could appear untranslated.       |
| Site IDs in breadcrumb and other strings     | The site ID on a History tab or in breadcrumbs aren't translated.                                                                                                                                                 |
| Country names used in the Store Locator      | In the Store Locator, country names come from the GeoLocationPO database and aren’t translated.                                                                                                                   |
| Order status                                 | Order status names are customer-defined and aren’t translated.                                                                                                                                                    |
| Tooltips text defined in the database        | Text beneath the dividing line of some tooltips comes from the customer's database and isn't translated.                                                                                                          |
| Permissions managed in the database          | In the Roles & Permissions module, descriptions for the different permissions are defined in the customer database and aren’t translated.                                                                         |
| Third-party data and proper names            | Third-party data and names aren’t translated, for example, the calendar to enter the start or end date of a campaign is in English. It's part of GWT and not accessible for localization.                         |
| Object types from auditing framework:        | On the Customer Groups page, for example, a variable inside the description of a group isn't translated. Such object types can't be translated because they come from inside the auditing framework.              |
| UI elements coming from the browser:         | The browser controls the Browse button. This button isn't localizable from within Business Manager.                                                                                                               |
| Internal exceptions:                         | Errors caused by exceptions outside of Business Manager aren’t translated. For example, an error such as, "Start node not found (ManageCustomGMVReports) for pipeline (ViewCustomizationImpex)." is untranslated. |

### Asian Language Support

Message resources support Asian character sets because property files assume a UTF-8 encoding. As a result, existing property files that are compatible with the ISO-8859-1 (Latin 1) encoding might no longer be supported in their existing form.

UTF-8 encoding supports many more languages than ISO-8859-1, including Greek, Cyrillic, Coptic, Armenian, Hebrew, Arabic, Syriac and Tana alphabets, as well as Chinese, Japanese and Korean ideographs, symbols, and punctuation.

| Location        | Impact                                                                                                                                                                                                                                                                      |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| USA             | UTF-8 encoding, like ISO-8859-1, is a super-set of the US-ASCII format. This means that existing property files containing only letters, numbers and punctuation among the 128 character codes in US-ASCII are inherently compatible with this change.                      |
| Other Countries | Property files containing accented characters and additional punctuation, that are beyond the 128 US-ASCII codes and commonly called _extended ASCII characters,_ aren’t compatible with this change. These files must be converted to UTF-8 format to continue to be used. |

**note:** If you use extended ASCII characters, you must convert your property files to support UTF-8.

**Search Query Processing**

Salesforce B2C Commerce supports search query processing for Chinese and Japanese sites.

### Enable Language Translation

There are tasks required to translate your storefront into the required languages.

#### Source Translation

To enable translation of the source:

1.  Create language-specific folders (for example, _es_US_).
2.  Identify images (for example, buttons) with locale-specific text.
3.  Identify for translation only those templates that are used in the storefront.
4.  Identify the JavaScript files where the locale-specific text is used.
5.  Identify other product, category, or content images where the locale-specific text is used.
6.  Translate these files and store them under the folder previously created (for example, _es_US_).
7.  Run a full regression test and QA for the localized content.
8.  Change the header or sidebar to integrate a select box where the user can select the language to be used for a session.

#### Content Translation:

To enable content translation:

1.  Export content, category, or products.
2.  Translate the content, category, or products.
3.  Import the content and use Business Manager for further editing.
4.  Translate name and description of shipping methods. These values appear in the storefront during checkout.

### Localizing Static Files

Localize static files such as images and CSS.

Images

Localize static files such as images to include images with localized text or locale-specific symbols. Your initial system includes the following structure:

| Location                                                  | Contains                                                                                                                      | Localized          |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| cartridge/web_ch_cust_app/cartridge/static/{default}      | English (or default) images (such as buttons), JavaScript (including English error messages), css files. (all are in the cod) | No                 |
| sites/Sites-cust-Site/1/units/Sites-cust/static/{default} | English (or default) content and category images, category images and homepage images (all are from the content library)      | Yes - text overlay |

**note:** Include an images folder within the locale-specific folder, but note that the SiteGenesis application doesn't use this capability for cartridge images.

If a user calls the URL using locale _es_US,_ the files in folder es_US are loaded first. If they aren’t found, Salesforce B2C Commerce uses the default folder as a fallback. So within a local-specific folder, you need only include files that are truly locale-specific (not background images, for example).

**note:** This logic occurs on a per file basis.

CSS Files

Your file system must have unique, locale-specific folders. For example, to support both English and Spanish (es_US), create a second <em>es_US</em> folder within the /static folder that lets B2C Commerce overwrite the default files. The included files must have the same names as the files under default and the same folder structure.

In the following directory structure, for example, the localized files are stored in language-specific directories (French and German). Use locale-specific directories (for example, fr_FR, fr_CA, en_US) as needed.

```txt
/Cartridge
	/static
		/default
			/css - generic files
				normalize.css
				print.css
				style-responsive.css
				style.css
			/images
				generic images
			/js - generic files
		/fr
			/css
				normalize.css
				print.css
				style-responsive.css
				style.css
			/images
				localized images
			/js
		/de
			/css
				normalize.css
				print.css
				style-responsive.css
				style.css
			/images
				localized images
			/js
```

## Localizing Templates

When developing your storefront application, use one template set or a unique template set for each locale.

When you use one template set, you externalize localizable strings, and translate the strings in resource files. Salesforce recommends this approach as a best practice methodology.

The advantage of using one template set is that templates (which can hold complex logic to visualize dynamic data) don't have to be modified as the storefront is localized. Also, the display logic exists in a single place (the non-language specific template) only. The externalized strings are stored in a simple file format that can be passed to translation service providers. The translation can be integrated back into B2C Commerce simply by copying the translated file into the cartridge, without potentially breaking the logic.

### Using One Template Set to Localize

The Storefront Reference Architecture (SFRA) application provides a simple way to localize any text that appears in the storefront. It uses a single template set for all locales, stored in properties files (called template resource bundles). The template resource bundles are translated, not the templates. The templates reference the localizable text in the template resource bundles by keys. Depending on the locale that is used in the storefront, a different translation (localization) of the properties file is used.

Projects typically start from the SFRA application code, so it's important that you use this approach consistently.

#### Directory Structure

To support multiple languages, create language-specific (for example, en) or locale-specific (for example, en_US) directories within the `templates/resources` directory, as follows:

```txt
/templates
	/default
		/account.isml
		...
		/util.isml
	/resources
		account.properties - default files
		...
		storelocator.properties
		/fr
			account.properties
			...
			storelocator.properties
		/de
		account.properties
			...
			storelocator.properties
```

Salesforce B2C Commerce (and the SFRA application) supports a localization fall-back mechanism. If no locale-specific directory exists, the language-specific directory is used. If there’s no language-specific directory, the default directory is used.

There’s a corresponding template resource bundle for each folder in the templates directory and one for the forms definitions.

#### Localizing Template Resource Bundles

Template resource bundles hold static content for localization. They’re stored for each cartridge within the `/templates/resources` directory. Messages from the bundles are accessible to all templates of the corresponding cartridge via the `msg()`method, available in the `dw.web.Resource` class.

**note:** Content Warning: The content on this page necessarily engages with noninclusive language that can be emotionally and intellectually challenging.

**note:** See the Salesforce B2C Commerce API documentation for more information.

These properties files have already been created for you in the SiteGenesis application. They each contain a list of text that pertains to its corresponding object (template or form). They’re organized as a single properties file per top-level directory.

**tip:** If a valid _localeID_ is set by the SendMail API pipelet, the locale is also used inside an email template to resolve localized messages by the `Resource.msg()` function based on the given locale. If you’re using the `dw.net.Mail` class to send messages, the LocaleID set through `Template.setLocaleId` or the constructor `Template(Template,LocaleID)` is used to look up the template resource before the locale linked to the current request.

**Account Example**

For example, account.properties, which lists the text in the minicartcontent.isml template, looks like this:

```txt
##############################################
# ISML Directory: account/addressbook/
##############################################
editaddress.editaddress=Edit Address
editaddress.addaddress=Add Address
editaddress.defaultaddress=Default Address
editaddress.makedefaultaddress=Make Default
```

**note:** Name the elements anything you want. In the SiteGenesis application, the elements are named after the files in which they’re contained, followed by a descriptive string. For example, a resource bundle referenced in the editaddress.isml template would be _editaddress.discriptivestring,_

For any text to be included in the storefront using this methodology, you must create a line within the corresponding language-specific properties file. These language files are named to correspond to the file directory of the language snippet to be used. Each text snippet has a unique key (unique across resource bundle files).

Comments

Comments are preceded by a # character.

For example, in the account.properties file, the text list is separated by the sub directories within the top-level directories.

```txt
##############################################
# ISML Directory: account/
##############################################
accountoverview.welcome=Hello
accountoverview.welcome2=, Welcome Back
accountoverview.not=Are you not

accountredirect.title=Redirect
accountredirect.permanent=This account has been permanently removed. You can attempt to login with another account or create a new account by going to the
accountredirect.accountlogin=login page.
account.forbidden=This page has timed out.  You must close the window and login to continue.
account.createnew=Create Account
account.editaccount=Edit Account

##############################################
# ISML Directory: account/addressbook/
##############################################
editaddress.editaddress=Edit Address
editaddress.addaddress=Add Address
editaddress.defaultaddress=Default Address
editaddress.makedefaultaddress=Make Default
```

Properties with the sub directory would be separated, as shown previously.

**Form Example**

The following is an example of using properties within a German version of a form (_forms/default/creditcard_de.xml - forms.properties_):

```txt
##############################################
# Template name: forms/default/creditcard_de
##############################################
creditcard.visa=Visa
creditcard.mastercard=Mastercard
creditcard.amex=Amex
creditcard.discover=Discover
creditcard.cvn=CVN
creditcard.savecard=Au�er Dieser Kreditkarte
```

**note:** Use the same pattern of appending the local identifier when creating locale-specific resource bundles (.properties) files. For example:

- account_en_GB.properties
- account_en_US.properties
- account_en.properties

#### Including Text Within a Template or Form

To include your language text within a template or form, reference the corresponding line from the correct file.

**note:** Content Warning: The content on this page necessarily engages with noninclusive language that can be emotionally and intellectually challenging.

**Cart Template Example**

The following example calls resource usage in a template:

<!-- prettier-ignore-start -->
```html
// Reference to resource minicart.viewcart in resource file
<a href="${URLUtils.https('Cart-Show')}"
   title="${Resource.msg('minicart.viewcart','checkout',null)}"
   class="mini-cart-link"></a>
// ${ Resource.msg('minicart.viewcart','checkout',null) } 
// will grab the text = View your cart
```
<!-- prettier-ignore-end -->

This entry is the corresponding entry in _checkout.properties:_

```javascript
minicart.viewcart;
```

**Form Example**

This example shows resource usage in a form:

```html
//Reference to resource forms.properties resource file
<options>
  <option optionid="Visa" value="creditcard.visa" label="creditcard.visa" />
  <option optionid="American Express" value="creditcard.amex" label="creditcard.amex" />
  <option optionid="Main" value="creditcard.mastercard" label="creditcard.mastercard" />
  <option optionid="Discover" value="creditcard.discover" label="creditcard.discover" />
</options>
```

This is the corresponding section in _forms.properties:_

```txt
creditcard.visa=Visa
creditcard.mastercard=Mastercard
creditcard.amex=Amex
creditcard.discover=Discover
```

### Localizing Using Multiple Template Sets

Use language-specific template sets to localize, although using one template set is the preferred approach.

With the multiple template set approach, each locale of a storefront has its own set of templates. The templates are stored in uniquely named folders, with this file structure:

```txt
templates\{locale_folder}\{template_files}
```

By default, Salesforce B2C Commerce provides all templates within the `\default`folder. This folder is used when no template is found for the requested locale. Directory names for locale-specific templates consist of a language and a country code, as specified in the standard ISO 639 (language) and ISO 3166 (country).

This table shows some sample folder names:

| Locale                | Folder Name |
| --------------------- | ----------- |
| English/United States | en_US       |
| English/Ireland       | en_IE       |
| German/Austria        | de_AT       |
| Spanish/Argentina     | es_AR       |
| French/Canada         | fr_CA       |

For example, templates could be stored in this directory structure:

```txt
.../cartridge/templates/default/multiple_template_files
.../cartridge/templates/en_GB/multiple_template_files
.../cartridge/templates/en_IE/multiple_template_files
.../cartridge/templates/en_US/multiple_template_files
```

#### Defaults

Use the following defaults to represent general languages:

| Language | Folder Name |
| -------- | ----------- |
| English  | en          |
| German   | de          |
| French   | fr          |
| Spanish  | es          |

#### Using Locales Beyond a Different Language

Use different templates for different locales, even though the locales share the same language. Share templates between different locales with the same language.

For example, a company set up a multi-site environment with three sites:

- United States
- Great Britain
- Ireland

Select the correct locale for each site: en_US for the US, en_GB for the UK and en_IE for Ireland. All main templates are shared between these locales. Implement country-specific changes to each site, for example, show the different country icons in the top left-hand corner of the Welcome page.

To achieve this effect, use three welcome templates with three different images or logos. Store the welcome.isml template in different folders specific for each locale:

```txt
.../cartridge/templates/en_GB/welcome.isml
.../cartridge/templates/en_IE/welcome.isml
.../cartridge/templates/en_US/welcome.isml
```

**note:** The characters, xx_XX represent a combination of the language and the country. For example, en_US represents the English (en) language spoken in the USA (US), while en_IE represents the English language (en) spoken in Ireland (IE). Likewise, de_DE represents the German language (de) spoken in Germany (DE), while de_AT represents the German language (de) spoken in Austria (AT).

## URLs for Localization

In Salesforce B2C Commerce, URLs can be localized. When you create a site, the URL Rules module automatically formats your URLs according to the module configuration.

**note:** If site URLs are configured with the locale ID as the first element of the URL (for example, /en_US/mens), B2C Commerce doesn't resolve URLs if they don't contain the locale (for example, /mens).

### Standard B2C Commerce URLs

Standard B2C Commerce URLs aren’t enabled by default and aren’t optimized for SEO. This URL structure is important to understand if you’re generating a locale-specific URL programmatically. Standard Demandware URLs have a simple structure for storefront access in the following format:

```txt
http://{instance}-{realm}-{customer}.brand.com/on/demandware.store/
{organization}-{sitename}-Site/{locale}/{pipeline_name}-{startnode_name}
```

Links to this type of address call a public pipeline-start node and can provide parameters such as category or product. Use these additional parameters:

cgid=category ID

pid= product ID (sku)

cid= content ID

Finding the locale in the URL

Find the locale used for a user session in the URL. For single-language installations, there’s always a locale named default. When using multiple locales, use {locale} instead of /default/.

Example:

| URL                                                                       | Locale  |
| ------------------------------------------------------------------------- | ------- |
| http://{domain}/on/demandware.store/Sites-customer-Site/default/... Value | default |
| http://{domain}/on/demandware.store/Sites-customer-Site/en_US/... Value   | en_US   |

The locale is used for the lookup of resources in the file system and in the database.

### Generating a Locale-Specific URL Programmatically

Provide two links so that your users can switch from English to Spanish on the homepage. But these links can't be hardcoded to the production instance URL. The links must also be able to access the staging and sandbox instances for testing purposes.

Access (get or set) the default locale programmatically, as shown in this example:

```html
<isscript>
  var currentLocale : String = pdict.CurrentRequest.getLocale();
</isscript>
<span>${currentLocale}</span>
<isloop items="${dw.system.Site.getCurrent().getAllowedLocales()}" var="locale" status="loopStatus">
  <isscript>
    var localeLanguage : String = new dw.util.Locale.getLocale(locale).getDisplayLanguage();
    if (localeLanguage == '') { // if the default langauge isn't defined, assume it's English localeLanguage = 'English'; }
    localeLanguage = localeLanguage.charAt(0).toUpperCase()+localeLanguage.substring(1);
  </isscript>
  <a href="${URLUtils.http(new dw.web.URLAction('Home-Show',dw.system.Site.getCurrent().getID(),locale))}"><isprint value="${localeLanguage}"></a>
</isloop>
```

**note:** Get the default locale from the site: `dw.system.Site.getCurrent().defaultLocale` (Read Only)

## Displaying Prices in Multiple Currencies

Show product prices in multiple currencies in the storefront using the Salesforce B2C Commerce API.

Use these API methods:

- `ProductPriceModel.getPriceBookPrice(String priceBookID)`
- `ProductPriceModel.getPriceBookPrice(String priceBookID, Quantity quantity)`

If the price book currency is different from the site currency, these methods return a product price.

**note:** This feature is for display purposes on the product details page only. Use this feature to show product prices in another currency, along with the actual sales price in the site currency. This feature doesn't support a multi-currency checkout.

Search result sorting, search refinements, price ranges, and other price-related features are limited to the site currency only.

<!-- document id=5ec9e27387f2dce0af914f0e33287398bc265e5b2608adebedeabb4ad624cc1b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-log-files-overview.md -->

# Log Files

Log files capture information about system resources, performance, errors, and quotas.

## Log File Types

B2C Commerce includes several different types of log files, including system logs, custom logs, import and export logs, a quota log, security logs, and batch processing logs.

To see system and custom application log files, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup**. In the WebDAV Access section, click the Log files links. The Log files home page (Index of /) shows a list of log files in alphabetical order. With the right permission, access the log files via a WebDAV client.

There are two types of log files:

- **System logging**: System information logging is turned on by default. Ask Salesforce Support to change your configuration if you want to change your system's logging configuration.
- **Custom logging**: If you perform programmatic logging using script files, configure custom logging in Business Manager. Custom logging is turned on for certain types of messages. Configure it for the other types of messages. Custom debug and info logs are disabled by default. Enabled or disable them for a specific instance by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Operations** > **Custom Log Settings**. If custom logging is disabled, no messages are logged. Custom log files begin with _custom._

Production and Staging instance log files are captured daily, stored for 30 days, and then automatically deleted. The only exception is security log files, which are automatically deleted after 90 days.

**note:** Log retention only applies to Production and Staging instances. Development and sandbox instances aren't supported.

Delete log files more frequently using WebDAV. After three days, the log files are moved into a `log_archive` directory and compressed into gzip files. If you want to retain log files for more than their retention time, download the files and store them locally.

### Tail and Query Logs with the B2C Commerce CLI

Instead of downloading log files via WebDAV, use the B2C CLI to stream and filter logs directly from your terminal. To install the tool and authenticate, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md).

```bash
# List available log files on the instance
b2c logs list

# Tail all ERROR- and FATAL-level entries in real time
b2c logs tail --level ERROR --level FATAL

# Tail only custominfo log files
b2c logs tail --filter custominfo

# Get the 200 most recent ERROR entries as structured JSON
b2c logs get --count 200 --level ERROR --json

# Search the last hour for a specific string
b2c logs get --since 1h --search "NullPointerException"
```

For the full command reference, see [Logs Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/logs.html) in the Agentic B2C Developer Toolkit documentation.

Allowing files to grow indefinitely can cause performance and storage issues, so files are restricted by size. Each application server can write up to 10 MB per day into the `customdebug`, `custominfo`, `customfatal`, `customerror`, and `customwarn` log files. The same limit applies to the number of fatal, error, warn, debug, and info messages that can be stored in `custom named log files`.

To maintain optimal performance and stability, delete unnecessary log files as soon as possible. Don’t store more than 100,000 files in a single folder. If there are more than 100,000 files in a single folder, files are deleted starting with the oldest first even if the files are newer than the retention period for the folder. The 100,000 limit applies to files in one specific folder, not across subfolders.

A day is 00:00 to 24:00 (12:00 a.m. to midnight next day) in Greenwich Mean Time (GMT). Logging is suspended until the next day (00:00) once the 10 MB limit has been reached. If the maximum possible log size is almost reached, for example, the log file size is 9.9 MB, and the next log message will exceed the limit, the log message is still written, but only up to an additional 100 KB beyond the 100 MB. This uses the log content's full permitted amount. When the log file has reached its maximum size for the day, the following info message is written to the log file:

```txt
+++++++++++ Maximum log file size per day reached, logging suspended. +++++++++++
```

**note:** System log settings have no storage limit.

One log file exists per log level, per application server. Log levels for system and customization include:

- info
- error
- warn
- debug
- fatal

The `debug` log level is always disabled on production instances and enabled for `in memory logging` on non-production instances. In memory logging allows for the `Show Request Log` feature, but doesn't generate log files.

This table describes how different log files work.

<table><col /><col /><col /><col /><thead><tr><th>Log file</th><th>How do I activate/configure this?</th><th>How long is it retained by time or file size?</th><th>Purpose</th></tr></thead><tbody><tr><td>dbinit-sql</td><td>Not configurable</td><td>30 days</td><td>SQL used during dbinit.</td></tr><tr><td>deprecation</td><td>Not configurable</td><td>30 days</td><td>Shows usage of deprecated APIs: date and time, API name, number of times used. If the file is empty, no deprecated APIs were used.</td></tr><tr><td>analytics</td><td>Not configurable</td><td>30 days</td><td>Shows any activity with B2C Commerce analytics. Review these for messages for active merchandising reports or any errors.</td></tr><tr><td>api</td><td>Not configurable</td><td>30 days</td><td>Shows API problems: area (Pipeline Dictionary, Pipeline) date and time, problem type (Error, Info, Template, Warn), path, detail type (Key, Pipelet, Pipeline, Site) and problem details. Review these for script usage and violation messages.</td></tr><tr><td>customdebug</td><td><p><strong>Administration</strong> > <strong>Operations</strong> > <strong>Custom Log Settings</strong></p> <p>Logger.debug in script</p></td><td><p>10 megabytes after clicking the <strong>Log To File</strong> button</p> <p>Repeatable</p> <p>30 days</p></td><td>Review this for debug messages in custom jobs, imports, payment or code that could impact users.</td></tr><tr><td>customerror</td><td><p><strong>Administration</strong> > <strong>Operations</strong> > <strong>Custom Log Settings</strong></p> <p>Logger.error in script</p></td><td><p>10 megabytes after clicking the <strong>Log To File</strong> button</p> <p>Repeatable</p> <p>30 days</p></td><td>Review this for errors in custom jobs, imports, payment or code that could impact users.</td></tr><tr><td>customfatal</td><td><p><strong>Administration</strong> > <strong>Operations</strong> > <strong>Custom Log Settings</strong></p> <p>Receive Email: Enter a comma-separated list of valid email addresses to enable email notification of <emph>Fatal</emph> messages. Email notifications are sent once every minute.</p></td><td><p>10 megabytes after clicking the <strong>Log To File</strong> button</p> <p>Repeatable</p>30 days</td><td>Review this for fatal errors in custom jobs, imports, payment or code.</td></tr><tr><td>custominfo</td><td><p><strong>Administration</strong> > <strong>Operations</strong> > <strong>Custom Log Settings</strong></p> <p>Logger.info in script</p></td><td><p>10 megabytes after clicking the <strong>Log To File</strong> button</p> <p>Repeatable</p> <p>30 days</p></td><td>Review this for informational logs in in custom jobs, imports, payment or code.</td></tr><tr><td>customwarn</td><td><p><strong>Administration</strong> > <strong>Operations/<strong> > <strong>Custom Log Settings</strong></p> <p>Logger.warn in script</p></td><td><p>Always logged to file.</p> <p>Repeatable</p> <p>30 days</p></td><td>Review this for <code>warn</code> messages in custom jobs, imports, payment or code that could impact users.</td></tr><tr><td>debug</td><td>Not configurable</td><td>30 days</td><td>Shows debug information for the entire site if the <emph>Debug</emph> flag is enabled. Use this with SOAP testing.</td></tr><tr><td>error</td><td>Not configurable</td><td>30 days</td><td>Shows errors in B2C Commerce scripts, templates, code and other areas.</td></tr><tr><td>fatal</td><td>Not configurable</td><td>30 days</td><td>Shows fatal errors in B2C Commerce scripts, templates, code and other areas.</td></tr><tr><td>info</td><td>Not configurable</td><td>30 days</td><td>Shows information logs reported on B2C Commerce scripts, templates, code and other areas.</td></tr><tr><td>jobs</td><td>Not configurable</td><td>30 days</td><td>Shows job status information: date and time, area, status (for example, <code>Job Manager Stopped</code>) on all Salesforce B2C Commerce instances and custom jobs.</td></tr><tr><td>migration</td><td>Not configurable</td><td>30 days</td><td>Internal migration data.</td></tr><tr><td>performance</td><td>Not configurable</td><td>30 days</td><td>Internal performance data. Not available in PIG instances.</td></tr><tr><td>quota</td><td>Not configurable</td><td>30 days</td><td><p>Contains B2C Commerce quota details such as: object quotas, object relation quotas and API quotas. Select also <strong>Administration</strong> > <strong>Operations</strong> > <strong>Quota Status</strong> to view status (in addition to logs).</p></td></tr><tr><td>sql</td><td>Not configurable</td><td>30 days</td><td>Review these if you have replication issues.</td></tr><tr><td>staging</td><td>Replication info during replication. Not configurable.</td><td>30 days</td><td>Information on B2C Commerce data and code replication processes (only on production, staging and development instances).</td></tr><tr><td>sysevent</td><td>Not configurable</td><td>30 days</td><td>Shows Appserver registration and cartridge-related logs. Shows date and time, event (for example, Active code version set to mobile).</td></tr><tr><td>syslog</td><td>Not configurable</td><td>30 days</td><td>Shows information that is related to API processing, data staging, and error handling. This file also shows import and export related task info, host information, and code version activation. These logs might provide useful information when troubleshooting import and export related issues.</td></tr><tr><td>console</td><td>Not configurable</td><td>30 days</td><td><p>Internal console log entries. Not available in PIG instances.</p> <p>The name of the console log file follows this pattern:</p> <p>console-hostname-appserver_id-server_name-timestamp.log</p> <p>In this pattern, timestamp is in yyyyMMdd format.</p> <p>Each entry contains: date and time, path, command (init, load, start, log), and message type (Error, Info, Severe, Warning).</p></td></tr><tr><td>warn</td><td><strong>Administration</strong> > <strong>Operations</strong> > <strong>Custom Log Settings</strong></td><td>30 days</td><td>Shows lock status reports (good for job info), slot warnings and warnings for servlets. Shows date and time, WARN, area (RequestHandlerServlet, Rendering, server|application name, message details.</td></tr></tbody></table></sfdocstbl>

### Redundancy Tracking

_Error_ and _Warning_ messages are tracked for redundancy. If a message appears more than 10 times in 3 minutes, it is suppressed if it reappears within the next 3 minutes. When suppression begins, the following text precedes the log message text within the log entry:

```txt
The following message was generated more than 10 times within the last 180 seconds.
It will be suppressed for 180 seconds:
```

Tracking of repeated messages continues while the suppression is in place. After the suppression period has ended, if a new log message appears whose occurrence rate is over the 10 message per 180-second threshold, it is logged with the message described. A new suppression period begins.

### Custom Named Log Files

The method `public static Log getLogger( String fileNamePrefix, String category )` obtains a log instance and writes to a custom log file through that log instance. When you call the method with the given file name prefix the first time, B2C Commerce creates a log instance and a corresponding log file in the usual log directory. When you call the method with the same file name prefix a second time, B2C Commerce returns the same log instance as the first call, and all log messages are stored in the same log file.

The log messages are written with the same pattern as used in system and custom logs, as follows:

```txt
custom - <file name prefix> - <hostname> - appserver - <creation date of the file in GMT>.log
```

This is an example:

```txt
custom-prefix-blade0-1-appserver-20110706.log
```

The file name prefix must follow these rules:

- Cannot be null or an empty string
- Must be at least three characters long
- Can contain characters a-z A-Z 0–9 '-' '\_' only
- Can have up to 25 characters
- Cannot start or end with '-' or '\_'
- Can only start or end with a-z A-Z 0–9

The log categories provided through Business Manager for the custom script log are also applied to this type of logger.

**note:** Governance allows only 200 different log file names (therefore, 200-log instances and log files) per day. This quota is a hard limit and is counted per appserver.

### Quota Log

The quota log contains B2C Commerce quota details such as:

- System object (data) quota status and limits
- System API quotas status and limits
- Sandbox system's database status
- Name of deprecated methods and how often they were used within the last 24 hours

### Security Logs

Security log files are located at `https://<instance name>.demandware.net/on/demandware.servlet/webdav/Sites/Securitylogs`.

Security log entries can look like this:

```
[2015-10-28 02:23:19.139 GMT] [DW-SEC] : User: 'username' (Sites), IP: 100.100.10.100 [LOGIN] : logged in.
```

The security log also includes:

- The session ID to the log entry for Business Manager logins
- Log entries for re-logins (when the Business Manager requires the password due to inactivity). These log entries log both the old and the new session ID.
- The name of the zone where the security event (for example, a login) occurred, appended to the end of each message, after a comma, as `, ZoneName: <zone name>` (for example, `, ZoneName: example.com`)

With the zone name appended, a security log entry looks like this:

```
[2015-10-28 02:23:19.139 GMT] [DW-SEC] : User: 'username' (Sites), IP: 100.100.10.100 [LOGIN] : logged in., ZoneName: example.com
```

Security log files are automatically deleted after 90 days. Users and clients can’t delete security logs, or turn off security logging. If you want to retain log files longer than 90 days, you must download the files and store them locally or in a dedicated storage.

### Import and Export Log

Find import and export specific information in the import and export log files. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup**. In the WebDAV Access section, click the **Import/Export** link to view log details on any activity relative to import and export. This information can provide you with critical insight into job failures or data errors. Use this link or access the data via a WebDAV client when performing import and export functions via Business Manager or programmatically via a pipelet. Import and export can be performed on many types of data.

Analyze the data in these logs as part of daily operations and each time there is an issue with a related process such as catalog import, price book or custom feed.

The Import/Export directory has the following structure on all instances.

#### log/ - Log Directory

This directory contains logs for specific processes such as catalog, customer, or product batch processing, catalog import and export, inventory import, and price book import. It also contains validation logs for Price Book, Promotions, Metadata, Coupon, Inventory, and Catalog.

processlogs_archive/ Archive of logs

#### src/ - B2C Commerce import and export source Files

This directory contains import and export source files, which include processes such as catalog import and custom jobs for feeds such as affiliates and channel advisor.

The following is an example of a subdirectory structure for src/:

```txt
activedata/
affiliatefeeds/
archive/
catalog/
catalog_archive/
channeladvisor/
customer/
customization/
customobject/
export/
instance/
library/
operations/
order/
upload/ (Directory for upload of files before processing)
```

Files in the /Impex folder and files in the /Impex subfolders are automatically deleted after 30 days. The subfolders are saved.

### Batch Processing Logs

Perform batch processing on catalogs, customers, and products. Product/catalog batch processing and customer batch processing aren't combined into the same interface. View the results of either from their respective Business Manager sections. For example, view customer batch processes by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Merchant Tools** > **_site_** > **Customers** > **Batch Processing**, but not by selecting **_site_** > **Merchant Tools** > **Products and Catalogs** > **Batch Processing**.

Batch processing logs can contain error reports as a result of a failed batch process. A log file can contain WARN, ERROR, or FATAL log messages. View the logs from the specific Batch Processing page, or from the Import/Export log directory, for example:

```txt
/Impex/log/Batch-Customer-20100128192425062.log
```

## Access Log Files

Access log files from Business Manager or a WebDAV client.

1.  To access log files from Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup** and scroll to the **WebDAV Acess** section, where you can click links to see the logs.

2.  To access log files from a WebDAV client:

    1.  Set up an SSL connection in Total Commander, using a valid Business Manager user name and password with proper access to connect to the Logs directory.

        Use any WebDAV client but we recommend Total Commander. Make sure to use the Total Commander WebDAV client and not the FTP client, as sFTP isn't supported.

    2.  Use the following URL to access the logs:

        `https://{\<instance name>}/on/demandware.servlet/webdav/Sites/Logs`

        When connected, browse logs, search for error strings, or download to your environment.

## Quota Log Files

Quota log files aggregate quota messages over a set period. Messages are written when the warn threshold or limit of a quota is exceeded.

The code location of the most recent event is written to the log file. The code locations of the aggregated events aren’t exposed. Quota log files show information about the location where a quota-warn threshold or limit was exceeded. The information includes the site name, job name, and top pipeline name. Additional information is sometimes included about the executed pipelet, script, pipeline node, and template.

Quota log files use this general format:

- a timestamp
- the thread name (contains type of request, site, pipeline name, and other parameters)
- the actual message

This format produces log entries such as the following:

```txt
[2012-05-23 13:00:22.577 GMT] [RequestHandlerServlet|14320460|Sites-SiteGenesis-Site|Product-Show|
PipelineCall|pRLNN0PXCp7rqIClq7IcPUvuEEjtkOWUAMBdUWhniPRFlV4Xvim3HwhDw96bRZ7e5BUxhnkC2ExrVYZVBFLJtw==]
Quota api.jsStringLength (enforced, warn 600000, limit 1000000): warn threshold exceeded 1 time(s),
max actual was 600010, current location: request/site Sites-SiteGenesis-Site/top pipeline Product-Show/
interaction node/template refapp.default_.CustomDisplay
```

This section of the entry is the timestamp:

```txt
[2012-05-23 13:00:22.577 GMT]
```

This section of the entry is the internal reference:

```txt
[RequestHandlerServlet|14320460|Sites-SiteGenesis-Site|Product-Show|PipelineCall|
 pRLNN0PXCp7rqIClq7IcPUvuEEjtkOWUAMBdUWhniPRFlV4Xvim3HwhDw96bRZ7e5BUxhnkC2ExrVYZVBFLJtw==]
```

This section of the entry is the message:

```txt
Quota api.jsStringLength (enforced, warn 600000, limit 1000000): warn threshold exceeded 1 time(s),
max actual was 600010, current location: request/site Sites-SiteGenesis-Site/top pipeline
Product-Show/interaction node/template refapp.default_.CustomDisplay
```

The message contains details to help identify problems. See:

- If a quota is _enforced_ or _not enforced_
- If applicable, the _warn_ threshold
- The limit
- The number of times since the last log entry for this quota that the warn threshold or limit was exceeded
- The highest observed reading (max actual)
- The _current location,_ which shows where the warn threshold or limit was exceeded

**note:** Read-only quotas don't have a warn threshold or limit, for example, _Quota object.ProductPO.readonly@SF (enforced)._

<!-- document id=b8d3be16129b5132ae1af840f4128f0ee14f76a3f235515be71eefa6290723ba url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_login.md -->

# Log Into Control Center

To use Control Center, log in with your Account Manager credentials. To log in successfully, your System admin must assign the appropriate roles to your account.

Some Account Manager roles require multi-factor authentication (MFA). To authenticate, make sure that you have a mobile device with the Salesforce Authenticator app installed.

1. In a web browser, go to https://controlcenter.commercecloud.salesforce.com/.
2. Enter your username (email address).
3. Click **LOG IN.**
4. Enter your password.
5. Click **LOG IN.**

After you sign in to Control Center, you see all the realms assigned to your primary organization in Account Manager. To see realms in other organizations you belong to, select an organization from the organization dropdown.

<!-- document id=84ba21df942e7f49cc7898c0d2038663c82762adf8f0617dda85e45d1104670f url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-batch-logout.md -->

# Log Out Multiple Shoppers

Starting with B2C Commerce version 26.9, use the [`batchLogout`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=batchLogout) endpoint of the Shopper Login and API Access Service (SLAS) Admin API to log out up to 50 shoppers across all their sessions. Identify each shopper by their login ID and authenticate the request with a [SLAS admin token](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#get-a-slas-admin-token) or an [Account Manager access token](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html#request-an-access-token) with the appropriate permissions.

For example, use this endpoint to:

- Invalidate every session for shopper accounts affected by a security incident.
- Force reauthentication for a group of shoppers as part of an account-security or support workflow.

For a shopper-initiated logout, use the [`logoutCustomer`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=logoutCustomer) endpoint instead. That endpoint revokes the access token and the refresh token supplied by the shopper's session. Batch logout is an administrative operation and affects every session associated with each successful login ID.

## Understand the Logout Behavior

For each valid login ID, SLAS revokes all active refresh tokens and inactivates all active access tokens issued before the request. The shopper must then authenticate again using their configured login method. Batch logout doesn't change the shopper's password or other account credentials.

## Send a Batch Logout Request

### Authorize the Request

Authenticate the request with a SLAS admin token or Account Manager access token.

- For manual requests or testing, get a [SLAS admin token](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#get-a-slas-admin-token) from the SLAS Admin UI. Your Account Manager user must have the [SLAS Organization Administrator role and the correct instance filters](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#slas-admin-ui-set-up-user-roles-and-filters).
- For automated integrations, configure an [Account Manager API client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html#create-an-api-client) with the Salesforce Commerce API and Sandbox API User [roles](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_roles.htm&type=5) for the target instance, and use the client’s credentials to [request an access token](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html#request-an-access-token).

### Send the Request

Gather the access token, the short code, the tenant ID, and the site ID for the B2C Commerce instance. See [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md#configuration-values).

Send up to 50 shopper login IDs in the `loginIds` array. Login IDs are case-insensitive.

```bash
curl "https://{SHORT_CODE}.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/{TENANT_ID}/batch-logout?channelId={SITE_ID}" \
--request 'POST' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer {ACCESS_TOKEN}" \
--data-raw '{
  "loginIds": [
    "user1@example.com",
    "user2@example.com"
  ]
}'
```

A syntactically valid request returns `200 OK` even when SLAS can't log out one or more shoppers. Check each entry in the `results` array instead of relying on the HTTP status alone. A login ID that doesn't match a shopper returns a `failure` status. Duplicate login IDs return a `not_processed` status.

<!-- document id=547cd45d82dc021e3cd3fb40d429a04ae6b835a96acd621300ff1d6ae0b52846 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-logging.md -->

# Logging in Storefront Next

Storefront Next includes a built-in structured logger that outputs JSON to stdout. The logger automatically enriches each log entry with a correlation ID and request context, making requests easy to trace across your application and search in Log Center.

## Use the Logger

### Server-Side (Loaders, Actions, Middleware)

Use `getLogger(context)` to get a request-scoped logger. It automatically includes the correlation ID, HTTP method, and path in every log entry.

```typescript
import { getLogger } from "@/lib/logger.server";

export async function loader({ context }: LoaderFunctionArgs) {
  const logger = getLogger(context);
  logger.info("Product loaded", { productId: "sku-123" });
  logger.warn("Inventory low", { remaining: 2 });
  logger.error("Payment failed", { error: new Error("timeout") });
}
```

### Client-Side or Without Context

Use `createLogger()` when router context isn't available, such as in client-side code or utility functions.

```typescript
import { createLogger } from "@/lib/logger";

const logger = createLogger();
logger.info("Variant selected", { sku: "var-456" });
```

### Metadata

Pass an optional metadata object as the second argument to any log method. Metadata fields are included as JSON properties in the log output.

```typescript
logger.info("Order placed", {
  orderId: "order-789",
  total: 149.99,
  itemCount: 3,
});
```

The logger automatically serializes error instances with `name`, `message`, and `stack` fields.

## Log Levels

Storefront Next supports four log levels, from most to least severe:

| Level   | Use for                                                                        |
| ------- | ------------------------------------------------------------------------------ |
| `error` | Unrecoverable failures within a request                                        |
| `warn`  | Recoverable problems: fallback paths, retries, degraded behavior               |
| `info`  | Observable outcomes: request completed, action succeeded/failed, state changes |
| `debug` | Internal progress: intermediate steps, useful for local debugging              |

### Configure the Log Level

**On Managed Runtime**, configure the log level in your environment settings:

1. Log in to [Runtime Admin](https://runtime.commercecloud.com).
2. Click your project, then your target environment.
3. Click **Environment Settings**.
4. In the Advanced section, set the **Log Level**.
5. Click **Update** and wait for the bundle to redeploy.

Alternatively, set the log level via the Managed Runtime API. Call [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) with `"log_level"` in the payload.

**For local development**, use the `SFCC_LOG_LEVEL` environment variable:

```bash
SFCC_LOG_LEVEL=debug pnpm dev
```

| Value     | Logs emitted                           |
| --------- | -------------------------------------- |
| `error`   | error only                             |
| `warn`    | error + warn                           |
| `info`    | error + warn + info                    |
| `debug`   | all messages                           |
| (not set) | `warn` in production, `info` otherwise |

## Log Format

In production, logs are output as structured JSON (ndjson). Each entry contains:

| Field           | Description                                          |
| --------------- | ---------------------------------------------------- |
| `level`         | Log severity: `error`, `warn`, `info`, or `debug`    |
| `msg`           | The log message                                      |
| `correlationId` | A unique ID for tracing a request across log entries |
| `method`        | HTTP method (GET, POST, etc.)                        |
| `path`          | URL pathname of the request                          |

Example:

```json
{
  "level": "info",
  "correlationId": "a1b2c3d4",
  "method": "GET",
  "path": "/products/shoes",
  "msg": "Product loaded",
  "productId": "sku-123"
}
```

In development, logs are pretty-printed with colors and timestamps for readability.

### Correlation ID

Every incoming request is assigned a correlation ID — either extracted from the `x-correlation-id` request header or generated automatically. All log entries for that request share the same `correlationId`, which lets you trace a single request end to end.

## View Logs in Log Center

[Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5) lets you search and filter production logs from Managed Runtime and your B2C Commerce instance.

### Prerequisites

To access MRT logs in Log Center:

1. Have the **Log Center User** role in [Account Manager](https://account.demandware.com/). If you don't have the role, ask your Account Manager admin to give you access.
2. Enable Log Center logs and Log Center metrics for the environment. See [Log Center Logs and Metrics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md#log-center-logs-and-metrics).

**note:** MRT logs in Log Center are available for any environment with Log Center logs enabled and a B2C Commerce instance associated. Marking the environment as production isn't required. There can be a delay of up to 15 minutes between an event and the log appearing in Log Center.

### Access MRT Logs

1. [Start Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_start_log_center.htm&type=5).
2. Select a **Region** and **[Realm](https://help.salesforce.com/s/articleView?id=cc.b2c_platform_overview.htm&type=5)**.
3. Click **Show filtered results**.
4. Click **Search > Current Search**.
5. Under Service Type, select **mrt**.
6. Under Request Type, select **SSR** for application logs or **CDN** for CDN logs.
7. Under Host, select your environment (`$PROJECT.$ENVIRONMENT`).

Use the `correlationId` field to filter all log entries for a single request.

### Limitations

- Each MRT log message is limited to 32 KB. Characters beyond 32 KB are truncated.
- For information about log levels and log volumes, see [Configuration for Administrators](https://help.salesforce.com/s/articleView?id=cc.b2c_configuration_for_administrators.htm&type=5).

## See Also

- [Build Tools](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-build-tools.md)

<!-- document id=512a40c1a883ca4a86726a35a866b40e040bc17b6b168dfda2e365fe2d33c0c0 url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-login.md -->

Login

# Login

In this section, you will see the actions necessary for API authentication.

The form of authentication to be used **will depend on the Salesforce licenses provided to the Sellers** who wish to integrate via API.

Most Marketplaces choose **Community licenses**, with more limited access to the resources of the Salesforce org, more directed towards the use of the Atonit Marketplace.

In other cases, **licenses of the Platform** type may be provided to Sellers, which will enable other resources not included in the previous license.

While authentication for **users of the Platform may be performed totally through programming** - without the need for manual input - the authentication of **Community users has an initial step that requires human intervention**. In this case, if you fall under this usage profile, an application may be developed that allows this manual authentication or the same Collection as the Postman may also be used to achieve first access and record your **access tokens** and **refresh tokens**.

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### POST Login (for Platform Users)

`POST /services/oauth2/token`

Operation ID: `Login (for Platform Users)`. Tags: Login.

For **Platform users**, only an authentication call is required to retrieve the access token, which will be used for the other calls.

The Token returned in **access\_token** must be saved and sent as a "Bearer Token" for all other calls, and must be refreshed when indicated with return of 401 for a call.

**Note:** If you are connected to a sandbox environment, it is necessary to change the URL prefix from `login.salesforce...` to `test.salesforce...`

#### Request body

Media type: `application/x-www-form-urlencoded`. Schema: `object`.

*   `grant_type` (_string_)  
    Example: `password`.
*   `client_id` (_string_)  
    Example: `{{client-id}}`.
*   `client_secret` (_string_)  
    Example: `{{client-secret}}`.
*   `username` (_string_)  
    Example: `{{username}}`.
*   `password` (_string_)  
    Example: `{{password}}`.

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 15:55:00 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536000; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Expires` (string)  
        Example: `Thu, 01 Jan 1970 00:00:00 GMT`.
    *   `X-ReadOnlyMode` (boolean)  
        Example: `false`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "access_token": "[example]",
      "instance_url": "https://{MyDomainName}.my.salesforce.com",
      "id": "https://login.salesforce.com/id/[example]/[example]",
      "token_type": "Bearer",
      "issued_at": "1619193301063",
      "signature": "[example]"
    }
    ```
    

### POST Login (for Community Users)

`POST /`

Operation ID: `Login (for Community Users)`. Tags: Login. Security: oauth2Auth.

In the case of **Community users**, a step will be required prior to the generation of the Token itself, which will allow you to log in to the community manually, via OAuth2.

For this, you will need to make an **Authentication call via OAuth2**, of the **Authorization Code** type, using as the domain the **URL of the Community** and passing in as parameters the **Callback URL** of the application, the **Client ID** and the **Client Token**. This information must be provided by the Marketplace to the Seller.

To facilitate this process, it is possible \*\*to download the Postman Collection \*\*for this documentation, where the authentication call is already set up via OAuth2, with just the information for each Seller needing to be included in the environment variables.

This call will open a **browser window**,

where the Seller will log in normally with their Community user name, and **access will be cleared via API for that user**.

Once the login has been performed, both a valid **access token** and a **refresh token** will be retrieved, which may be used subsequently to refresh the Access Token without manual action.

The Token returned in **access\_token** must be saved and sent as a "Bearer Token" for all other calls, and must be refreshed when indicated with a return of 401 for a call.

#### Responses

*   **200** Successful response
    
    Media type: `application/json`.
    

### POST Refresh Token (for Community Users)

`POST /services/oauth2//token`

Operation ID: `Refresh Token (for Community Users)`. Tags: Login. Security: oauth2Auth.

After the initial generation of the Access Token and Refresh Token, or when the **generated Access Token expires**, it is necessary to execute an action to refresh the Token.

To do this, a request of the type **Refresh Token** must be sent, with response type **Token**, together with the **Client ID**, **Client Secret** and **Callback URL** information.

The response to this request will be a new Access Token, which can be used **immediately.**.

**Note:** The **Refresh Token does not have an expiration set**, and will only become invalid if manually revoked.

#### Request body

Media type: `application/x-www-form-urlencoded`. Schema: `object`.

*   `grant_type` (_string_)  
    Example: `refresh_token`.
*   `refresh_token` (_string_)  
    Example: `{{refresh-token}}`.
*   `client_id` (_string_)  
    Example: `{{client-id}}`.
*   `client_secret` (_string_)  
    Example: `{{client-secret}}`.
*   `redirect_uri` (_string_)  
    Example: `{{callback-url}}`.
*   `response_type` (_string_)  
    Example: `token`.

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Thu, 26 Aug 2021 13:57:25 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536004; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Expires` (string)  
        Example: `Thu, 01 Jan 1970 00:00:00 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "access_token": "[example]",
      "refresh_token": "[example]",
      "sfdc_community_url": "https://[example].force.com",
      "sfdc_community_id": "[example]",
      "signature": "[example]",
      "scope": "refresh_token full",
      "id_token": "[example]",
      "instance_url": "https://{MyDomainName}.my.salesforce.com",
      "id": "https://test.salesforce.com/id/00D040000008gAEEAY/00504000001B7dgAAC",
      "token_type": "Bearer",
      "issued_at": "1629986245797"
    }
    ```
    

### GET Query

`GET /services/data/v51.0/query`

Operation ID: `Query`. Tags: Login. Security: bearerAuth.

To look up information about a seller, use the [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) resource of the main REST API from Salesforce and set the value of the `q` parameter to an SOQL query. The following example is included in the query parameters section of this page with a corresponding example in the responses section:

**Example 1 of 1**: `getSellerByExternalId`

The value of seller-external-id must be provided by the marketplace and will be used to identify the Seller and serve as a key for when it is necessary to insert records pointing to the Seller object. The value of the seller-api-prefix must also be provided by the marketplace and will be used several times as the key for IDs. The call below returns the Seller’s basic details and can be used as an authentication test.

#### Parameters

*   `q` (query, string)
    
    _Example: getSellerByExternalId_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__Seller__c WHERE Atonit_Mktplace__External_Id__c = '{{seller-external-id}}' LIMIT 200
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 16:00:05 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1755/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example: getSellerByExternalId_
    
    ```
    {
      "totalSize": 1,
      "done": true,
      "records": [
        {
          "Id": "a0T5Y00000ZE4lFUAT",
          "Name": "S-004",
          "CreatedDate": "2021-03-22T21:38:39.000+0000",
          "LastModifiedDate": "2021-04-13T19:27:22.000+0000",
          "Atonit_Mktplace__Accepts_Marketplace_Shipping__c": false,
          "Atonit_Mktplace__Commercial_Conditions__c": null,
          "Atonit_Mktplace__CommissionPercent__c": 10,
          "Atonit_Mktplace__Delivery_Policy__c": "This is a delivery policy",
          "Atonit_Mktplace__Logo_URL__c": "https://via.placeholder.com/150C.png",
          "Atonit_Mktplace__ReleaseText__c": "This is a release text",
          "Atonit_Mktplace__Return_Policy__c": "This is a return policy",
          "Atonit_Mktplace__Slug__c": "atonit-vitta",
          "Atonit_Mktplace__External_Id__c": "atonit-vitta"
        }
      ]
    }
    ```

<!-- document id=e60e5e79818499bc2f543e05469e020ddcff979a72c023713c8eb7a9c77040ee url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-login.md -->

# Login

### Overview

The login page provides the buyer authentication entry point for the storefront experience.

Salesforce Commerce supports multiple authentication and login integration patterns. Select the approach that best aligns with your organization's security, identity management, and domain requirements.

<!--The reference React storefront implementation uses Custom Apex Authentication to establish a site-scoped buyer session cookie that works across custom storefront domains. The following sections describe the supported login patterns and their implementation considerations.-->

This flow demonstrates how a headless storefront can orchestrate custom Apex-based authentication experiences for buyer access and session management.

![Login Overview Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-login-overview-30-1.png '{"class": "image-lg", "title": "Login Overview Flow"}')

<!--**Choose an Authentication Approach**-->

<!--Select the authentication option that best matches your storefront architecture and security requirements.

- Use Custom Apex REST authentication when you need a site-scoped session cookie under a custom domain.
  OR
- Use OAuth-based authentication when integrating with: External identity providers (IdPs), Mobile applications, Flows that require refresh-token support
-->

**Authentication Approach**

Choose OAuth-based authentication when integrating with external identity providers (IdPs), mobile applications, or workflows that require refresh token support.

### B2B Commerce APIs Used in the Flow

<!--**Apex**

| Operation | HTTP Method | Endpoint                        |
| --------- | ----------- | ------------------------------- |
| Apex auth | POST        | `/services/apexrest/auth/login` |
-->

**OAuth**

| Operation       | HTTP Method | Endpoint                     |
| --------------- | ----------- | ---------------------------- |
| OAuth authorize | GET         | `/services/oauth2/authorize` |
| OAuth token     | POST        | `/services/oauth2/token`     |

### Buyer Journey

<!--**Submit Buyer Credentials Using Custom Apex REST Authentication**

Use this option to authenticate buyers through a custom Apex REST implementation. The reference React storefront uses this approach to establish a site-scoped session cookie under a custom domain.

1. Call the following endpoint to initiate the login flow: `POST /services/data/v68.0/connect/identity/login-or-reg/init`

   Example request body:

   ```json
   {
     "identifier": "<buyer-identifier>",
     "channel": "<email-or-phone>",
     "action": "login"
   }
   ```

2. Allow the platform to send a one-time verification code to the buyer.

3. Call the following endpoint to verify the challenge response: `POST /services/data/v68.0/connect/identity/login-or-reg/verify`

   Example request body:

   ```json
   {
     "challengeId": "<challenge-id>",
     "code": "<verification-code>"
   }
   ```

4. Retrieve the `redirectUrl` value from the verification response.

5. Redirect the buyer to the returned URL to establish the authenticated storefront session.
-->

**Authentication with OAuth**

Use an OAuth-based authentication flow to integrate with an external Identity Provider (IdP). After the buyer session is established, storefront operations are decoupled from the underlying authentication mechanism and rely solely on the active session.

See [Authorization Through External Client Apps or Connected Apps and OAuth 2.0 and Authorize Apps with OAuth](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_authenticate.htm&type=5) for more information.

<!-- document id=6828bf8abf87dcd442483905918a3950ce667d9435dad0fc308f4857700ae958 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-login-support-hybrid.md -->

# Login and Registration Support for Hybrid Storefront Next Storefronts

Check out login, registration, account update and other capabilities that Storefront Next supports when combined with other storefront types in a hybrid app.

## Features Available for Storefront Next and SFRA

These tables show the supported features when the hybrid storefront implements login from Storefront Next and SFRA.

### Login

| Shopper Action                                          | Available for Login in Storefront Next and SFRA | Available When Only Storefront Next Implements Login | Available When Only SFRA Implements Login |
| ------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| Login using password                                    | Yes if password-based login is enabled          | Yes                                                  | Yes if password-based login is enabled    |
| Login using native email OTP                            | Yes for Storefront Next. No for SFRA.           | Yes                                                  | No                                        |
| Login using OTP via callback URI (email/SMS/magic link) | No                                              | No                                                   | No                                        |
| Login using passkey                                     | No                                              | No                                                   | No                                        |
| Login using social sites (Google, Apple)                | Yes                                             | Yes                                                  | Yes                                       |

### Registration

| Shopper Action                                                 | Available for Login in Storefront Next and SFRA | Available When Only Storefront Next Implements Login | Available When Only SFRA Implements Login |
| -------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| Registration using password                                    | Yes if password-based login is enabled          | Yes                                                  | Yes if enabled                            |
| Registration using native email OTP                            | Yes for Storefront Next. No for SFRA.           | Yes                                                  | No                                        |
| Registration using callback URI                                | Yes for Storefront Next. No for SFRA.           | Yes                                                  | No                                        |
| User registers a passkey (requires email OTP for verification) | No                                              | No                                                   | No                                        |

### My Account Update

Shopper must be logged in to update profile.

| Shopper Action                                                        | Available for Login in Storefront Next and SFRA | Available When Only Storefront Next Implements Login | Available When Only SFRA Implements Login |
| --------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| Verification required for email update using native email OTP         | Yes for Storefront Next. No for SFRA.           | Yes                                                  | No                                        |
| Verification required for email update using callback URI (email OTP) | Yes for Storefront Next. No for SFRA.           | Yes                                                  | No                                        |
| Verification required for phone update using callback URI (SMS OTP)   | No                                              | No                                                   | No                                        |
| Password reset/forgot password                                        | Yes                                             | Yes                                                  | Yes                                       |

### Trusted Agent and System on Behalf

| Shopper Action                                                                                                                                                                  | Available for Login in Storefront Next and SFRA | Available When Only Storefront Next Implements Login | Available When Only SFRA Implements Login |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| Trusted Agent on Behalf (TAOB): Enables an agent to perform actions on behalf of a registered or guest shopper.                                                                 | No                                              | No                                                   | No                                        |
| Trusted System on Behalf (TSOB): Login flow designed for system-to-system communication in back office workflows (for example, take action as a system on behalf of a shopper). | No                                              | No                                                   | No                                        |

## Features Available for Storefront Next and SiteGenesis

These tables show the supported features when the hybrid storefront implements login from Storefront Next and SiteGenesis.

### Login

| Shopper Action                                          | Available for Login in Storefront Next and SiteGenesis | Available When Only Storefront Next Implements Login | Available When Only SiteGenesis Implements Login |
| ------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------ |
| Login using password                                    | Yes if password based login is enabled                 | Yes                                                  | Yes if password-based login is enabled           |
| Login using native email OTP                            | Yes for Storefront Next. No for SiteGenesis.           | Yes                                                  | No                                               |
| Login using OTP via callback URI (email/SMS/magic link) | No                                                     | No                                                   | No                                               |
| Login using passkey                                     | No                                                     | No                                                   | No                                               |
| Login using social sites (Google, Apple)                | Yes                                                    | Yes                                                  | No                                               |

### Registration

| Shopper Action                                                 | Available for Login in Storefront Next and SiteGenesis | Available When Only Storefront Next Implements Login | Available When Only SiteGenesis Implements Login |
| -------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------ |
| Registration using password                                    | Yes if password based login is enabled                 | Yes                                                  | Yes                                              |
| Registration using native email OTP                            | Yes for Storefront Next. No for SiteGenesis.           | Yes                                                  | No                                               |
| Registration using callback URI                                | Yes for Storefront Next. No for SiteGenesis.           | No                                                   | No                                               |
| User registers a passkey (requires email OTP for verification) | No                                                     | No                                                   | No                                               |

### My Account Update

Shopper must be logged in to update profile.

| Shopper Action                                                        | Available for Login in Storefront Next and SiteGenesis | Available When Only Storefront Next Implements Login | Available When Only SiteGenesis Implements Login |
| --------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------ |
| Verification required for email update using native email OTP         | Yes for Storefront Next. No for SiteGenesis.           | Yes                                                  | No                                               |
| Verification required for email update using callback URI (email OTP) | Yes for Storefront Next. No for SiteGenesis.           | Yes                                                  | No                                               |
| Verification required for phone update using callback URI (SMS OTP)   | No                                                     | No                                                   | No                                               |
| Password reset/forgot password                                        | Yes                                                    | Yes                                                  | Yes                                              |

### Trusted Agent and System on Behalf

| Shopper Action                                                                                                                                                                  | Available for Login in Storefront Next and SiteGenesis | Available When Only Storefront Next Implements Login | Available When Only SiteGenesis Implements Login |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------ |
| Trusted Agent on Behalf (TAOB): Enables an agent to perform actions on behalf of a registered or guest shopper.                                                                 | No                                                     | No                                                   | No                                               |
| Trusted System on Behalf (TSOB): Login flow designed for system-to-system communication in back office workflows (for example, take action as a system on behalf of a shopper). | No                                                     | No                                                   | No                                               |

## See Also

- [Shopper Login and API Access Service (SLAS) Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guides/slas.md)

<!-- document id=959a84e505e75237548bb96bc4cf11bbbdcaf4676b713f7ee6d1afd34acc9068 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-login-support.md -->

# Login and Registration Support in Storefront Next

Check out login, registration, account update and other capabilities that Storefront Next supports.

## Login

| Shopper Action                                          | Available in Storefront Next                 |
| ------------------------------------------------------- | -------------------------------------------- |
| Login using password                                    | Yes                                          |
| Login using native email OTP                            | Yes                                          |
| Login using OTP via callback URI (email/SMS/magic link) | No                                           |
| Login using passkey                                     | No\*                                         |
| Login using social sites (Google, Apple)                | Yes\*                                        |
| Login using third-party IDP (Okta, Ping, etc.)          | Not out-of-the-box, requires configuration\* |

\*Not available in Storefront Next with One-Click Checkout.

## Registration

| Shopper Action                                                 | Available in Storefront Next     |
| -------------------------------------------------------------- | -------------------------------- |
| Registration using password                                    | Yes (not enabled by default)\*\* |
| Registration using native email OTP                            | Yes                              |
| User registers a passkey (requires email OTP for verification) | No                               |

\*\*For Storefront Next with One-Click Checkout, registration using password is disabled only when the email verification site preference is disabled.

## My Account Update

Shopper must be logged in to update profile.

| Shopper Action                                                        | Available in Storefront Next |
| --------------------------------------------------------------------- | ---------------------------- |
| Verification required for email update using native email OTP         | Yes                          |
| Verification required for email update using callback URI (email OTP) | No                           |
| Verification required for phone update using callback URI (SMS OTP)   | No                           |
| Password reset/forgot password                                        | Yes                          |

## Trusted Agent and System on Behalf

| Shopper Action                                                                                                                                                                  | Available in Storefront Next |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| Trusted Agent on Behalf (TAOB): Enables an agent to perform actions on behalf of a registered or guest shopper.                                                                 | No                           |
| Trusted System on Behalf (TSOB): Login flow designed for system-to-system communication in back office workflows (for example, take action as a system on behalf of a shopper). | No                           |

In this section:

- [Passwordless Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passwordless-login.md)
- [Social Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-social-login.md)
- [Email Verification for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-email-verification.md)
- [Password Reset for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-password-reset.md)
- [Maintain Shopper Sessions Across Subdomains in Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-domain-cookie.md)

## See Also

- [Shopper Login and API Access Service (SLAS) Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guides/slas.md)

<!-- document id=bc3cf16a7aad89291ba60500c3f46911cebadb3631ebd7589b0bfe7d7bfe7732 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/inventory-lookup-on-pdp-via-spis.md -->

# Lookup Inventory on PDP via SPIs in Point of Sale

Use one of two SPIs for the POS Product Detail Page (PDP) to get inventory information from an external system.

One SPI, the Inventory Overview Widget, allows merchants to populate nearby inventory via an SPI (versus using Salesforce inventory records). For details, see [checkInventoryOverview](https://developer.salesforce.com/docs/commerce/retail-cloud/references/inventory-spi?meta=checkInventoryOverview).

The second SPI, Inventory by ZIP code, allows associates to receive inventory information (as a descriptive string) based on a delivery ZIP code. These methods are ideal for merchants who have an external Controller of Record (COR) and don’t want to store inventory data with Salesforce. For details, see [checkInventoryAvailability](https://developer.salesforce.com/docs/commerce/retail-cloud/references/inventory-spi?meta=checkInventoryAvailability).

For a complete list of Point of Sale APIs, SPIs, and webhooks, refer to [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

<!-- document id=1dd762317ac24ea87fa35eb2c33130f1af737fce82403180ecba055d23d10101 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/loyalty-spi.md -->

Loyalty SPI

# Loyalty SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/loyalty-spi/loyalty-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send order details and get loyalty-related information.

**Version:** 2.3.4

## Tags

### Loyalty SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/loyalty-spi/loyalty-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send order details and get loyalty-related information.

## Operations

### POST Retrieve loyalty points earned.

`POST /merchant/spi/sample/endpoint/sa/getLoyaltyPoints`

Operation ID: `postReceipt_1`. Tags: Loyalty SPI.

Retrieve the loyalty points earned for the transaction. When placing an order, if the customer is enrolled in loyalty, this SPI returns the points that will be earned for the order. Merchant must implement this endpoint per this specification and then configure it in CMS.

#### Request body

Media type: `application/json`. Schema: `Cart`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SPILoyaltyPoints`.
    

## Schemas

### Cart

*   `cartId` (_string_)
*   `suspendedCartId` (_string_, nullable) If the cart is created from suspended cart,the suspendedCartId will be populated with the suspended cart's db id. This is nothing but db id of the resumed suspended cart.
*   `suspendedQuoteId` (_string_, nullable) If the cart is created from suspended cart having quote,the suspendedQuoteId will be populated with the suspended cart's quoteId.
*   `suspendedExternalQuoteId` (_string_, nullable) If the cart is created from suspended cart having quote,the suspendedExternalQuoteId will be populated with the suspended cart's external quoteId.
*   `resumedCartDBIds` (_array of string_, nullable) All the resumed cart associated with this current cart. Multiple suspended carts can be resumed in single active cart, all such resumed carts are maintained in this list.  
    Unique items.
*   `cartItemList` (_array of Product_)
*   `subTotal` (_number_)
*   `shippingMethodList` (_array of ShippingMethod_)
*   `session` (_string_)
*   `orderNo` (_string_)
*   `discount` (_number_)
*   `errors` (_array of ProductError_)
*   `productWarnings` (_array of ProductWarning_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `orderPriceAdjustments` (_array of OrderPriceAdjustment_)
*   `originalDiscountData` (_CartDiscountData_)
*   `giftCardList` (_array of GiftCard_)
*   `giftCardAppliedTotal` (_number_)
*   `paymentMerchantId` (_string_)
*   `paymentOrganizationId` (_string_)
*   `token` (_string_)
*   `errorCode` (_string_)
*   `errorMessage` (_string_)
*   `taxCalculationDone` (_boolean_)
*   `hybridCheckoutUrl` (_string_)
*   `rewardList` (_array of Reward_)
*   `rewardTotal` (_number_)
*   `cookieList` (_array of CheckoutCookie_)
*   `tax` (_number_)
*   `valueAddedTax` (_number_)
*   `highPrecisionValueAddedTax` (_number_)
*   `giftCardRemainingTotal` (_number_)
*   `giftWrapTotal` (_number_)
*   `giftMessage` (_string_)
*   `promotions` (_array of Promotion_)
*   `promotionCodes` (_array of string_)
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `taxTotal` (_number_)
*   `taxExemption` (_number_)
*   `shippingTotal` (_number_)
*   `shippingDiscount` (_number_)
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `shippingMethod` (_ShippingMethod_)
*   `priceAdjustmentsComplete` (_boolean_)
*   `redeemPromoCallBackUrl` (_string_)
*   `loyaltyId` (_string_)
*   `customerEmail` (_string_)
*   `orderSource` (_string_)  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `transactionStartDate` (_string (date-time)_)
*   `fullfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `storeId` (_string_)
*   `customerId` (_string_)
*   `taxableAmount` (_number_)
*   `isSplitCart` (_boolean_)
*   `children` (_object_)
    
    Additional properties: `Cart`.
    
*   `transactionDiscountAmount` (_number_)
*   `transactionDiscountReason` (_string_, deprecated) DEPRECATED - Use 'reasons' instead.
*   `offlineMode` (_boolean_)
*   `loyaltyInfo` (_LoyaltyInfo_)
*   `taxRates` (_array of OrderTaxRate_) Sale-side tax rate.
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions.
*   `vatRates` (_array of OrderTaxRate_) Sale-side VAT rate.
*   `netTaxRates` (_array of OrderTaxRate_) Net tax rate calculated based on sale-side tax rate and return-side tax rate.
*   `netVatRates` (_array of OrderTaxRate_) Net VAT rate calculated based on sale-side VAT rate and return-side VAT rate.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the actions performed on the cart. For example, reason for discounts applied to the order.
*   `editOrderId` (_string_, nullable) Order ID for the order being edited.
*   `exchangeItemResponses` (_array of ExchangeItemResponse_) Details about the items that are being returned or exchanged.
*   `returnsTenders` (_array of ReturnsTender_) In case there is refund, refund tender details and options.
*   `amountToBeCharged` (_number_) Amount to be charged.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `orderType` (_string_) Used to indicate if the order is of type Layaway.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow. Maximum transaction discount that can be applied.
*   `minimumPaymentAmount` (_number_) Used for partial payments flow. Represents minimum payment amount due at the time of order placement.
*   `notesList` (_array of OrderNote_)
*   `grandTotal` (_number_) Grand Total of sale transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, Grand Total is to maintain total sale amount. In case of pure returns, the Grand Total will always be zero.
*   `hash` (_string_) Hash corresponding to the current cart content.
*   `saleRoundingAmount` (_number_) The delta amount because of rounding applied on sale portion of the cart.
*   `exchangeItemRequests` (_array of ExchangeItemRequest_) Request for items that are being returned or exchanged.
*   `refundSubTotal` (_number_) Returning item subtotal — subtotal of items in the exchange item list.
*   `refundDiscount` (_number_) Returning item's discount — discount total of items in the exchange item list.
*   `refundTax` (_number_) Returning item's tax — tax total of items in the exchange item list.
*   `refundTariff` (_number_) Returning item's tariff — tariff total of items in the exchange item list.
*   `refundTaxExemption` (_number_) Returning item's tax exemption — tax exemption total of items in the exchange item list.
*   `refundValueAddedTax` (_number_) Returning item's value-added tax — VAT for items in the exchange item list.
*   `refundItemTotal` (_number_) Returning item's total — total of items in the exchange item list.
*   `profile` (_Profile_)
*   `refundFees` (_array of RefundFee_) Refund fees applied when cancelling items from an order during the edit order flow.
*   `taxTransaction` (_TaxTransaction_)
*   `externalSessionId` (_string_)
*   `referenceId` (_string_, nullable) Two phase confirmation reference id corresponding to the order that is being confirmed as part of this request, Two phase commit V2 uses this field.
*   `externalCartId` (_string_)
*   `orderLevelGiftWrap` (_OrderLevelGiftWrap_)
*   `paymentInstallment` (_PaymentInstallment_)
*   `paymentInstallmentOptionsList` (_array of PaymentInstallmentOptions_, nullable) List of Payment Installment options available.
*   `isGift` (_boolean_) Flag indicating if order is a gift.  
    Default: `false`.
*   `pickUpDetail` (_OrderPickUpDetail_)
*   `pickUpDetailList` (_array of OrderPickUpDetail_) Pick Up Details.
*   `deliveryZoneId` (_string_) Zone ID for online items that will be delivered.
*   `deliveryZipCodeId` (_string_) Zip code ID for online items that will be delivered.
*   `availableDate` (_integer (int64)_) Available date for online items.
*   `totalAssembledQty` (_number (double)_) Total Assembled quantity for delivery items.
*   `totalBoxedQty` (_number (double)_) Total Boxed quantity for delivery items.
*   `verifiedTenderInfo` (_array of Tender_) Information which was used to verify the tender is available through this list.
*   `authorizedTenderInfo` (_array of Tender_) Information which was used to authorize the tender is available through this list.
*   `summary` (_CartSummary_)
*   `transactionDiscount` (_Discount_)
*   `shippingDisclaimer` (_string_) Shipping Disclaimer.
*   `employee` (_Employee_)
*   `cartType` (_string_, nullable) Used in the backend to determine if the omni flow is active during cart, order, and order post-processing.  
    Allowed values: `REGULAR`, `OMNI`.
*   `displayMessages` (_array of Flash_) Generic field for display messages. The display message is populated to provide helpful information to user. One of the use cases is eligible coupon code which is not applied.
*   `multiShipmentType` (_string_) Multi shipment types as cart can have multiple shipments either with the same address or different addresses.  
    Allowed values: `ORDER_LEVEL`, `DELIVERY_GROUP_LEVEL`.
*   `auxiliaryItemData` (_array of AuxiliaryItemData_) Auxiliary items details support for edit order.
*   `skipAutoPromotion` (_boolean_) Skip auto promotion when the order is edit order.
*   `currentStoreType` (_string_) Store Type belonging to current store requesting cart.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `customerLoyaltyProfile` (_CustomerLoyaltyProfile_)
*   `pointsEarned` (_integer (int32)_, nullable) The number of loyalty points earned in this transaction.
*   `shippingTaxExemption` (_number_, nullable) The tax exemption applied on the Shipping tax.
*   `originalDepositBalance` (_number_)
*   `depositBalance` (_number_)
*   `depositToOrderBalance` (_number_)
*   `returnCustomerInformation` (_ReturnCustomerInformation_)
*   `deltaCart` (_DeltaCart_)
*   `tariffAmount` (_number_)
*   `tariffRate` (_number_)
*   `taxOrVatOverrideRate` (_number_)
*   `partiallyPaidItemList` (_array of Product_)
*   `isWarrantyStale` (_boolean_)
*   `promotionContext` (_array of Promotion_)
*   `promotionContextV2` (_array of Promotion_)
*   `skipDeliveryGroupSPI` (_boolean_)

### SPILoyaltyPoints

*   `pointsEarned` (_integer (int32)_) The number of loyalty points earned for an order, dedicated SPI will give the value for this post Phase I call.

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### ProductError

*   `productId` (_string_)
*   `errorMessage` (_string_)
*   `errorCode` (_string_)
*   `errorType` (_string_)

### ProductWarning

*   `productId` (_string_)
*   `messages` (_array of Message_)

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### OrderPriceAdjustment

The list of price adjustments done on the total order in the cart.

*   `description` (_string_)
*   `adjustment` (_number_)
*   `discount` (_Discount_)
*   `price` (_number_)
*   `promotionId` (_string_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.

### CartDiscountData

*   `transactionDiscount` (_number_) The transaction discount applied on the original order.
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_) Item level price adjustments applied on the original order. It can be price override, promotion or prorated transaction discount.

### GiftCard

*   `cardId` (_string_)
*   `cardNumber` (_string_)
*   `cardPin` (_string_)
*   `balance` (_number_)
*   `invoiceNumber` (_string_)
*   `token` (_string_)
*   `forcePinValidation` (_boolean_)
*   `approvedAmount` (_number_)
*   `transactionId` (_string_)
*   `returnRelated` (_boolean_)

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### CheckoutCookie

*   `domain` (_string_)
*   `key` (_string_)
*   `value` (_string_)

### Promotion

*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)
*   `promotionId` (_string_)
*   `name` (_string_)
*   `title` (_string_)
*   `description` (_string_)
*   `promoCode` (_string_)
*   `inStorePromoCode` (_string_)
*   `appPromoCode` (_string_)
*   `onlinePromoCode` (_string_)
*   `outletPromoCode` (_string_)
*   `promoFeedSource` (_FeedSource_)
*   `startTimeStamp` (_integer (int64)_)
*   `endTimeStamp` (_integer (int64)_)
*   `combinationTypes` (_array of string_)
*   `channel` (_array of string_)  
    Items: Allowed values: `ALL`, `WEB`, `APP`, `STORE`, `OUTLET`.
*   `priorityOrder` (_integer (int32)_)
*   `active` (_boolean_)
*   `auto` (_boolean_)
*   `redemptionLimit` (_number (double)_)
*   `uniqueCodeUrl` (_string_)
*   `redeems` (_number (double)_)
*   `barCodeType` (_string_)
*   `promotionType` (_string_)  
    Allowed values: `ORDER_PERCENT_OFF`, `ORDER_AMOUNT_OFF`, `FREE_SHIPPING`, `BXGY`, `FREE_SAMPLES`, `X_FOR_Y`, `PRODUCT_FIXED_AMOUNT`, `FREE_SHIPPING_V2`.
*   `percentOff` (_number (double)_)
*   `maxDiscountAmount` (_number (double)_)
*   `maxTotal` (_number_)
*   `amountOff` (_number_)
*   `shippingMethods` (_array of string_)
*   `hasSingleUsePromoCodes` (_boolean_)
*   `imageUrl` (_string_)
*   `discountedQuantity` (_integer (int32)_)
*   `freeSamples` (_array of CombinationGroup_)
*   `merchantPromotionId` (_string_)
*   `amount` (_number_)
*   `promoRules` (_array of PromotionRule_)
*   `qualifyingGroups` (_array of CombinationGroup_)
*   `discountedGroups` (_array of CombinationGroup_)
*   `amountExpression` (_string_)
*   `tierGroups` (_array of TierGroup_)
*   `discountedGroupProration` (_boolean_)
*   `promotionLanguageData` (_array of PromotionLanguageData_) Promotion attributes in additional languages.
*   `bxgyDiscountType` (_string_) Buy X Get Y discount types.  
    Allowed values: `PERCENT_OFF`, `AMOUNT_OFF`, `FIXED_PRICE`.
*   `createdBy` (_string_)
*   `createdOn` (_string (date-time)_)
*   `lastUpdatedOn` (_string (date-time)_)
*   `lastUpdatedBy` (_string_)
*   `promotionMappings` (_array of PromotionMapping_)
*   `isExternallyValidated` (_boolean_)
*   `promotionTypePriority` (_string_)  
    Allowed values: `FREE_SAMPLES`, `BXGY_FIXED_AMOUNT`, `X_FOR_Y`, `BXGY_AMOUNT_OFF`, `BXGY_PERCENT_OFF`, `PRODUCT_FIXED_AMOUNT`, `ORDER_AMOUNT_OFF`, `ORDER_PERCENT_OFF`, `FREE_SHIPPING_V2`, `FREE_SHIPPING`.
*   `promotionCode` (_PromotionCode_)

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### LoyaltyInfo

*   `pointsRedeemValue` (_number (double)_)
*   `pointsEarnValue` (_number (double)_)
*   `pointsClosingBalance` (_number (double)_)

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### ExchangeItemResponse

Details about the items that are being returned or exchanged.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderId` (_string_)
*   `exchangeStatus` (_string_)  
    Allowed values: `EXCHANGED`, `EXCHANGED_WITH_REFUND`, `FAILED`, `SKIPPED`.
*   `refundAmount` (_number_)
*   `refundMedium` (_string_)
*   `refundStatus` (_string_)
*   `orderStatus` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `products` (_array of Product_)
*   `order` (_CustomerOrder_)
*   `amountPendingRefund` (_number_)
*   `refundPaymentData` (_array of PaymentData_)
*   `refundPaymentDataOriginalTender` (_array of PaymentData_)
*   `paymentData` (_array of PaymentData_)
*   `parentOrderId` (_string_)
*   `noReceiptReturns` (_boolean_)
*   `editOrderId` (_string_)
*   `refundFees` (_array of RefundFee_, nullable) Refund fees charged so far.
*   `transactionId` (_string_, nullable) Transaction identifier to identify current exchange transaction.
*   `offlineMode` (_boolean_) Flag to indicate whether returns or exchange is being performed in offline mode or not.
*   `postProcessingPerformed` (_boolean_) Flag to indicate if the post processing webhook is triggered or not.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `orderReturnsPolicy` (_OrderReturnsPolicy_)
*   `employee` (_Employee_)
*   `tipTotal` (_number_) Tip Total to be refunded in case of pure return.
*   `request` (_ExchangeItemRequest_)
*   `refundPerformed` (_boolean_)
*   `returnableItemTotal` (_number_)
*   `paymentDetails` (_array of OrderPaymentDetail_)
*   `exchangeOrderPaymentDetails` (_array of ExchangeOrderPaymentDetail_)
*   `error` (_boolean_)

### ReturnsTender

In case there is refund, refund tender details and options.

*   `returnsTenderId` (_string_)
*   `tenderHeaderText` (_string_)
*   `headerText` (_string_) Display text corresponding to the refund option.
*   `tenders` (_array of PaymentData_)
*   `returnsPolicies` (_array of string_) All the applied returns policies to determine the refund option.  
    Items: Allowed values: `MaxReturnsDays`, `MaxCashReturns`, `RemapRefundTenders`, `StoreCredit`, `GiftCard`, `CustomerNotInPersonRefund`, `CreditCard`, `NoReceiptReturns`, `Check`.
*   `managerOverrideRequired` (_boolean_)
*   `amountToBeCharged` (_number_) Effective amount to be charged to customer based on purchases, any refunds, discounts , taxes, shipping, any additional fee & rounding if any for this return tender.
*   `headerTextForManagerOverride` (_string_, write-only)
*   `approvalPolicyForManagerOverride` (_string_, write-only)  
    Allowed values: `CREATE_TILL`, `MAX_CASH_RETURN_POLICY`, `MAX_RETURN_WINDOW_POLICY`, `NRR`, `TENDER_REMAPPING`, `OFFLINE_MAX_CASH_RETURN_POLICY`, `OFFLINE_MAX_RETURN_WINDOW_POLICY`, `OFFLINE_NRR`, `OFFLINE_TENDER_REMAPPING`, `PAY_IN_OUT`, `EMPLOYEE_SALE`, `LINE_ITEM_DISCOUNT`, `TRANSACTION_DISCOUNT`, `RECONCILE_TILL`, `CASH_PICKUP`, `BUSINESS_CHECK`, `NO_SALE`, `POST_ADJUSTMENT_INVENTORY`, `CYCLE_COUNT_BATCH_SERIALNUMBER`, `SPECIAL_ITEM`, `REUSE_OLD_TILL`, `TAX_MODIFICATION`, `PRICE_CORRECTION`, `SHOW_ASSOCIATE_REVENUE_IN_DASHBOARD`, `VIEW_SAFE_MANAGEMENT`, `VIEW_ALL_TILLS`, `CYCLE_COUNT_LIFECYCLE`, `CYCLE_COUNT_DETAILS`, `VIEW_ALL_CYCLE_COUNT_BATCHES`, `UPDATE_ALL_CYCLE_COUNT_BATCHES`, `MANAGER_OVERRIDE`, `RETURN_EXCHANGE_POLICY`, `CASH_AUDIT`, `APPEASEMENT`, `EDIT_SAFE_MANAGEMENT`, `REMOVE_WARRANTY`.

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ExchangeItemRequest

Request for items that are being returned or exchanged.

*   `storeAssociateId` (_string_, required) ID of the store associate who performs the returns.
*   `storeId` (_string_, required) ID of the store where the return is being performed.
*   `installationId` (_string_, required) Installation ID of the register from where the return is being performed.
*   `noReceiptReturns` (_boolean_, nullable) Flag to indicate returns without receipt.  
    Default: `false`.
*   `receiptType` (_string_, nullable) Receipt type enum.  
    Allowed values: `ORDER`, `QUOTE`, `GIFT`, `GIFT_SKU_LEVEL`, `GIFT_REWARD_CARD`, `INVENTORY_TRANSFER_PACKING_SLIP`, `PO_ORDER`, `STORE_TO_STORE_TRANSFER`, `RETURN_TO_VENDOR_TRANSFER`, `PICK_LIST`.
*   `editOrderId` (_string_, nullable) Set in case of edit order mode. Value will be same as orderId.
*   `refundFees` (_array of RefundFee_) Refund fees applied when cancelling or returning items from an order during the edit order flow.
*   `offlineMode` (_boolean_) Flag to indicate whether returns or exchange is being performed in offline mode or not.
*   `returnProducts` (_array of ReturnProductIdentification_) Returning item's orderItemId and quantity.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakup for return items.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakup for return items.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `storeAttribution` (_StoreAttribution_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `employee` (_Employee_)
*   `orderSource` (_string_, nullable) Order Source - Indicates channel from where the order originated.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariffAmount` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `giftCardCashOut` (_boolean_)
*   `exchangeOrderPaymentDetails` (_array of ExchangeOrderPaymentDetail_)

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### RefundFee

Refund fees applied when cancelling or returning items from an order during the edit order flow.

*   `id` (_string_) Refund fee ID. For example, Restocking or 001.
*   `label` (_string_) Refund fee display name. For example, Restocking Fee.
*   `value` (_number_, nullable) Refund fee amount.

### TaxTransaction

Details related to tax transaction related to a cart. A cart can be modified multiple times and hence it can be sent to tax engine multiple times. All such requests are tagged under single tax transaction id.

*   `cartId` (_string_) Cart ID related to the current tax transaction.
*   `transactionId` (_string_) Tax transaction ID. Multiple requests to the tax engines related to a cart can be tagged with a single tax transaction ID to group together all tax requests related to a single cart.
*   `editOrderId` (_string_) Order ID for the order being edited.

### OrderLevelGiftWrap

Gift Wrap.

*   `giftWrapMode` (_string_)  
    Allowed values: `ALL_ITEMS_TOGETHER`, `EACH_ITEM_SEPARATELY`.
*   `giftFrom` (_string_)
*   `giftTo` (_string_)
*   `giftMessage` (_string_)

### PaymentInstallment

*   `frequency` (_string_)
*   `count` (_integer (int32)_)
*   `amount` (_number_)
*   `text` (_string_)
*   `installments` (_array of PaymentInstallmentItem_)
*   `amountDueToday` (_number_)

### PaymentInstallmentOptions

List of Payment Installment options available.

*   `shippingMethodId` (_string_)
*   `paymentInstallmentList` (_array of PaymentInstallment_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Tender

Tender object with payment details.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `paymentSequenceNumber` (_integer (int32)_, required) Payment sequence indicating the order of payment. For example, if customer pays partially with cash first and remaining with credit card, then cash tender should have paymentSequenceNumber as 1 and credit card tender should have paymentSequenceNumber as 2.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentDevice` (_string_, required) Identifies the payment device through which the payment is made. If payment data is manually entered, this field should be set to NoReader. If payment is made in an external system, payment device should be set to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `rawPaymentPayload` (_string_) Raw payment payload. For future use.
*   `routingNumber` (_string_) Bank routing number.
*   `accountNumber` (_string_) Account number. Used for payment through banking system.
*   `checkNumber` (_string_) Check number. Used for payment through checks.
*   `personalIdType` (_string_) Personal identification type.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_) Issuer of the personal identification.
*   `personalIdNumber` (_string_) Personal identification number.
*   `personalIdExpiryDateMillis` (_integer (int64)_) Personal identification expiry date represented as milliseconds since epoch. Typically expiry date is end of the day and milliseconds since epoch should reflect it accordingly.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry).
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardCvc` (_string_) Card CVC. Used in case of manual credit card data entry.
*   `track1Data` (_string_) Encrypted track1 data. Used in case of client/app side card encryption by readers like Verifone.
*   `track2Data` (_string_) Encrypted track2 data. Used in case of client/app side card encryption by readers like Verifone.
*   `paymentDeviceId` (_string_) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.
*   `operatingMode` (_string_) Operating mode of the app and card reader - ONLINE/OFFLINE. Other values are unused.  
    Allowed values: `ONLINE`, `OFFLINE`, `DEGRADED`, `TWO_PHASE_STAGING`.
*   `encryptedExpiryDate` (_string_) Encrypted expiry date. Used in case of client/app side card encryption by readers like Verifone.
*   `encryptedCardNumber` (_string_) Encrypted card number. Used in case of client/app side card encryption.
*   `encryptedCvv` (_string_) Encrypted card CVV. Used in case of client/app side card encryption.
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `storedCardId` (_string_) Stored Card ID to use in case of card stored for the customer profile.
*   `cardType` (_string_) Card type. For example, Visa, Master, Amex, or Discover.
*   `rawCardType` (_string_) Raw card type, for example, Visa Credit Card, Visa Debit Card, or Master Credit Card. Typically used when an Adyen terminal captures card data for payment.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year.
*   `pin` (_string_) PIN number typically used for gift card.
*   `authorizationToken` (_string_) Payment authorization token.
*   `authorizationDateMillis` (_integer (int64)_) Payment authorization timestamp as number of milliseconds since epoch.
*   `captureToken` (_string_) Payment capture token.
*   `captureDateMillis` (_integer (int64)_) Payment capture timestamp as number of milliseconds since epoch.
*   `requestId` (_string_) Payment request identification issued by payment gateway/terminal. Typically used for referenced refunds. This field maps to pspReference in case of Adyen payments.
*   `alternateRequestId` (_string_) Alternate payment request identification issued by payment terminal. Example, tender reference in case of Adyen terminal is in store and forward mode.
*   `requestToken` (_string_) Payment request token issued by payment gateway/terminal. Typically used for referenced refunds.
*   `firstName` (_string_) First name to use for billing using this tender.
*   `lastName` (_string_) Last name to use for billing using this tender.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.
*   `city` (_string_) City to use for billing using this tender.
*   `state` (_string_) State to use for billing using this tender.
*   `postalCode` (_string_) Postal code to use for billing using this tender.
*   `country` (_string_) Country code to use for billing using this tender.
*   `paypalInvoiceId` (_string_) Invoice ID. Used when payment is done using paypal reader.
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_) External payment reference identifier in case of External tender.
*   `paymentGatewayConfigId` (_string_) Payment Gateway ID - to be used in case of multiple payment gateways are available to process a single tender.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt.
*   `merchantReferenceId` (_string_) Merchant reference ID sent to the payment terminal for this tender. This is required for match response received off asynchronously from payment processor (like Adyen Store and Forward) with the correct payment object for an order.
*   `paymentStatus` (_string_) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `checkType` (_string_) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_) Manual authorization code for a tender. Normally it is received after calling a call center agent of a payment processor. For example, call for auth code after check denial/referral, manual auth code for credit card when offline.
*   `paymentTypeCode` (_string_) Type of payment plan. Used for Tender Type - Finance.
*   `cardPresent` (_boolean_) Indicates if the card is physically present or not. Used in case of Tender Type - Finance.
*   `ssn` (_string_) Customer's Social Security Number for verification purposes. Used in case of Tender Type - Finance.
*   `accountHolders` (_array of AccountHolder_) Account Holders information. Used in case of Tender Type - Finance.
*   `additionalInfo` (_array of string_) List of additional information required to verify the buyer. Used in case of Tender Type - Finance.
*   `cashDrawerUrl` (_string_) Represents custom URL using which cash drawer in the network can be accessed.
*   `roundingAmount` (_number_) The delta amount because of rounding.
*   `authStatus` (_string_) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_) Tip amount to capture on credit card.
*   `captureStatus` (_string_) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_) Refers to finance approval/order/confirmation number in external system.
*   `financeInstruction` (_string_) Refers to finance processing related result or instruction long text from external system.
*   `primaryAccountHolder` (_string_) Primary owner on the account.
*   `tradeType` (_string_) Trade Type. In case of WeChatPay: QuickPay.
*   `bankType` (_string_) Bank Type.
*   `fundingSource` (_string_) Funding source like PREPAID.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `paymentLink` (_string_) Payment Link.
*   `paymentLinkExpiryDate` (_string_) Payment Link expiry date.
*   `paymentId` (_string_) Payment Id from app.
*   `transactionId` (_string_) The transactionId from app's requestId.
*   `paymentReversalStatus` (_string_) Payment Status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi tender and delete by swiping right, ABORTED is used where we internally remove tender from our tender list and add a new tender for eg gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `captureAmount` (_number_) Amount captured for credit card.
*   `requestTokenExpireDate` (_integer (int64)_) Request token expire date.
*   `continueOnPendingOrDecline` (_boolean_) Continue order processing on tender pending or decline status.
*   `termsAndConditions` (_string_) Terms and conditions.
*   `gcBalance` (_number_, nullable) Balance remaining in case of tender type gift card.
*   `cashTenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `cashChangeAmount` (_number_) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response by gateway. In adyen - a value that uniquely represents the shopper's card number (PAN).
*   `paymentEntryMode` (_string_) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `manualCardEntry` (_boolean_)
*   `error` (_boolean_)

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### Discount

Transaction discount applied on the cart with information like discount type and discount value. In online mode it is copied from app's request payload for transaction discount and in case of offline mode it is copied from app's submit order request.

*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`, `AMOUNT, PERCENT`. Default: `AMOUNT`.
*   `discount` (_number_, required) Discount either in percentage or in amount.

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### Flash

Generic field for display messages. The display message is populated to provide helpful information to user. One of the use cases is eligible coupon code which is not applied.

*   `type` (_string_, required) Type of the flash message.  
    Allowed values: `PROMOTION`, `TAX`, `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURN`, `ORDER`, `GIFTCARD`, `CART`, `INVENTORY_RESTRICTION`. Example: `PROMOTION`.
*   `message` (_string_, required) Flash message.  
    Example: `Coupons Spring2023, Max100 are in the cart but not applied`.
*   `resourceName` (_string_, required) Resource or entity for which the message is provided.  
    Allowed values: `COUPON_CODE`, `CART`. Example: `COUPON_CODE`.
*   `resourceValues` (_array of string_, required) Resource values for which the message is provided.  
    Items: Example: `Coupon codes - Spring2023, Max100 etc...`. Example: `Coupon codes - Spring2023, Max100 etc...`.

### AuxiliaryItemData

auxiliary Items details support for edit order.

*   `orderItemId` (_string_) Order item ID.
*   `itemAction` (_string_) Items Action.  
    Allowed values: `NEW`, `MODIFY`.

### CustomerLoyaltyProfile

The loyalty profile of the customer if they are enrolled in Loyalty program.

*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `firstName` (_string_) Customer's first name.
*   `lastName` (_string_) Customer's last name.
*   `accountNumber` (_string_) Customer's loyalty account number.
*   `loyaltyStatusCode` (_string_, nullable) Customer's loyalty status code.
*   `currentPoints` (_integer (int32)_, nullable) Customer's current loyalty points. If provided, it will be used for validation against the individual reward points (If points are sent in reward).
*   `currentStoreCredit` (_number (double)_, nullable) Customer's current store credit.
*   `lifetimePoints` (_integer (int32)_, nullable) Loyalty point accumulated so far by the customer.
*   `nextRewardPoints` (_integer (int32)_, nullable) Loyalty point eligible for next reward cycle.
*   `transactions` (_Transactions_)
*   `rewards` (_array of Reward_, nullable) Earned rewards.
*   `tierLevelLabel` (_string_, nullable) Customer's tier level label.
*   `tierLevelValue` (_string_, nullable) Customer's tier level value.
*   `tierLevelCode` (_string_, nullable) Customer's tier level code.
*   `redemptionType` (_string_)
*   `internalMemberId` (_string_, nullable) Customer's internal member ID.
*   `homePhoneNumber` (_string_, nullable) Customer's home phone number.
*   `mobilePhoneNumber` (_string_, nullable) Customer's mobile phone number.
*   `address` (_Address_)
*   `currentTier` (_Tier_)
*   `nextTier` (_Tier_)
*   `customLoyaltyAttributes` (_CustomAttributes_)
*   `totalRewardsAmount` (_number_, nullable) Total amount value of all the rewards available for the customer. If provided, this will be used for validation when applying the individual rewards.
*   `loyaltyIdBarCodeType` (_string_)

### ReturnCustomerInformation

Return - Customer Information. For return or exchange transactions, use this object to capture information about the person returning the items. Note: This might or might not be the actual customer who purchased the items. This object is exclusively to capture information about the person returning items.

*   `firstName` (_string_, nullable) First Name.
*   `lastName` (_string_, nullable) Last Name.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `email` (_string_, nullable) Email ID.
*   `address` (_Address_)
*   `personalId` (_PersonalID_)

### DeltaCart

*   `scale` (_integer (int32)_)
*   `roundingMode` (_string_)  
    Allowed values: `UP`, `DOWN`, `CEILING`, `FLOOR`, `HALF_UP`, `HALF_DOWN`, `HALF_EVEN`, `UNNECESSARY`.
*   `transactionId` (_string_)
*   `transactionTimeStamp` (_integer (int64)_)
*   `storeAttribution` (_StoreAttribution_)
*   `transactionType` (_string_)  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`.
*   `orderId` (_string_)
*   `productList` (_array of Product_)
*   `cancelProductList` (_array of Product_)
*   `productPriceAdjustmentList` (_array of ProductPriceAdjustment_)
*   `tenderList` (_array of Tender_)
*   `refundTenderList` (_array of RefundTender_)
*   `pickUpDetailList` (_array of OrderPickUpDetail_)
*   `reducedTaxAfterPriceAdjustment` (_number_)
*   `fulfillmentTypeChangeProductList` (_array of Product_)
*   `fulfillmentTypeChangeCancelProductList` (_array of Product_)
*   `secondaryProductList` (_array of Product_)
*   `deliveryGroupChangeList` (_array of ProductDeltaDeliveryGroup_)
*   `deliveryGroupList` (_array of DeliveryGroup_)
*   `secondaryDeliveryGroupList` (_array of DeliveryGroup_)
*   `updatedDeliveryGroupList` (_array of DeliveryGroup_)
*   `summary` (_CartSummary_)
*   `originalProductDeliveryGroupList` (_array of ProductDeliveryGroup_)
*   `notesList` (_array of DeltaOrderNote_)
*   `detailNotesList` (_array of DeltaOrderDetailNote_)
*   `removedDeliveryGroupList` (_array of DeliveryGroup_)
*   `productPickUpDetailList` (_array of ProductPickUpDetail_)

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### Message

*   `message` (_string_)
*   `code` (_string_)
*   `type` (_string_)  
    Allowed values: `ERROR`, `WARN`, `INFO`.

### FeedSource

*   `feedType` (_string_)  
    Allowed values: `PRODUCT`, `PRODUCT_BUNDLE`, `STORE`, `LAYOUT`, `PRODUCT_PROMOTION`, `PRODUCT_CATEGORY`, `PRODUCT_CATEGORY_PROMOTION`, `PROMOTION`, `STORE_INVENTORY_FULL`, `STORE_INVENTORY_DELTA`, `SOCIAL_MEDIA`, `ONE_TIME_PROMOTION_CODE`, `PRODUCT_DELTA`, `CATEGORY`, `ORDER_LIST`, `ORDER_DETAILS`, `RECOMMENDATION`, `TAX_RATE`, `PIPELINE`, `STORE_ASSOCIATES`, `PREDICTSPRING_PROMOTION`, `REWARD`, `CASH_REWARD`, `ASN`, `CORP_TRANSFER`, `POS_PROVISIONING`, `SYNONYM`, `STORE_AREA_GOAL`, `STORE_AREA_HIERARCHY`, `OMS`, `PRODUCT_PRICING`, `PRODUCT_SIZING`, `PRODUCT_INVENTORY`, `PRODUCT_PRICING_DELTA`, `PRODUCT_SIZING_DELTA`, `PRODUCT_INVENTORY_DELTA`, `STORE_DEVICE`, `BOPIS_CANCEL_ORDER`, `PURCHASE_ORDER`, `OFFLINE_PROMOTION`, `PREDICTSPRING_PROMOTION_V2`, `EXPIRED_PAYMENT_LINK_CLEANUP`, `SINGLE_USE_PROMO_CODES`, `STORE_GROUP_FULL`, `STORE_GROUP_DELTA`.
*   `feedSourceName` (_string_)
*   `feedSourceType` (_string_)  
    Allowed values: `URL`, `SFTP`, `FTP`, `S3`, `YEXT`, `AVALARA`, `SABRIX`, `AVALARA_V2`, `VERTEX`, `SPI`, `WEBDAV`.
*   `fileNames` (_array of string_)
*   `feedFileType` (_string_)  
    Allowed values: `CSV`, `TSV`, `SSV`, `PSV`, `XML`, `STORE_XML`, `INVENTORY_XML`, `JSON`, `YEXT`, `ASN_EDI_856`, `OTHER`.
*   `feedPreprocessorClass` (_string_)
*   `feedFileMetadataList` (_array of FeedFileMetadata_)
*   `baseURL` (_string_)
*   `urlRequestParams` (_string_)
*   `folderName` (_string_)
*   `host` (_string_)
*   `port` (_integer (int32)_)
*   `userName` (_string_)
*   `password` (_string_)
*   `s3FeedTimestamp` (_integer (int64)_)
*   `parentTag` (_string_)
*   `multiValueFieldList` (_array of string_)
*   `preserveIfNullFieldList` (_array of string_)
*   `currencyCode` (_string_)
*   `idColumn` (_string_)
*   `multiValueFieldDelimiter` (_string_)
*   `columnNames` (_string_)
*   `promotionId` (_string_)
*   `deleteFeed` (_boolean_)
*   `addFeed` (_boolean_)
*   `updateFeed` (_boolean_)
*   `fullFeed` (_boolean_)
*   `sourceEncoding` (_string_)
*   `maxRecordsToProcess` (_integer (int32)_)
*   `apiKey` (_string_)
*   `version` (_string_)
*   `categoryProductRankColumnName` (_string_)
*   `productIdFieldName` (_string_)
*   `feedName` (_string_)
*   `feedDescription` (_string_)
*   `isProductBundleCategorySource` (_boolean_)
*   `importPromotions` (_boolean_)
*   `hasCategories` (_boolean_)
*   `shouldProcessCategoryCounts` (_boolean_)
*   `skipFields` (_string_)
*   `hasProductMultiPromotions` (_boolean_)
*   `fieldDelimiter` (_string_)
*   `endLineDelimiter` (_string_)
*   `deviceOS` (_string_)
*   `dataSource` (_string_)  
    Allowed values: `NETSUITE`.
*   `accountId` (_string_)
*   `licenseKey` (_string_)
*   `merchantReferenceCode` (_string_)
*   `bulkProcessing` (_boolean_)
*   `backUp` (_boolean_)
*   `continueOnFileError` (_boolean_)
*   `clientId` (_string_)
*   `clientSecret` (_string_)
*   `hasActualInventoryCount` (_boolean_)
*   `oauthHost` (_string_)

### CombinationGroup

Products that receive the discount when the qualifying condition is met.

*   `quantity` (_integer (int32)_)
*   `quantityOperator` (_string_)  
    Allowed values: `EQL`, `GTE`.
*   `productRules` (_array of PromotionRule_)

### PromotionRule

Promotion rule provides the filtering criteria to determine if the order is eligible for promotion.

*   `promotionRuleId` (_string_)
*   `promotionId` (_string_)
*   `operator` (_string_, nullable) Operation to be performed for the rule depending on the value types.  
    Allowed values: `DOES_NOT_CONTAIN`, `CONTAINS`, `GTE`, `LTE`, `EXISTS`, `NOT_EXISTS`.
*   `value` (_array of string_, nullable) Values are based on the value Types. They contain a list and for single value attributes use a list of size 1.  
    Unique items.
*   `valueType` (_string_, nullable) Value Type provides the type of value.

### TierGroup

*   `amountExpression` (_string_)
*   `tierRules` (_array of PromotionRule_)
*   `id` (_string_)
*   `selectedProducts` (_array of string_)

### PromotionLanguageData

Promotion attributes in additional languages.

*   `promotionId` (_string_)
*   `language` (_string_) The language/locale of properties for this object.
*   `name` (_string_) The name used for internal identification of the promotion. This field can also be used to assign a locale/language-specific name for the promotion.
*   `title` (_string_) The locale/language-specific title used for external display of the promotion on the presentation layer.
*   `description` (_string_) The locale/language-specific description used for external display of the promotion on the presentation layer. This contains the disclaimer and other information.

### PromotionMapping

*   `quantityOperator` (_string_)  
    Allowed values: `EQL`, `GTE`.
*   `merchantId` (_string_)
*   `type` (_string_)  
    Allowed values: `QUALIFYING_GROUP`, `DISCOUNTED_GROUP`, `TIER_GROUP`, `FREE_SAMPLES`.
*   `promotionRulesGroupId` (_string_)
*   `promotionMappingId` (_string_)
*   `promotionId` (_string_)
*   `amountExpression` (_string_)
*   `quantity` (_integer (int32)_)
*   `locale` (_string_)
*   `region` (_string_)

### PromotionCode

*   `merchantId` (_string_)
*   `region` (_string_)
*   `promotionId` (_string_)
*   `oneTimeCode` (_string_)
*   `oneTimeCodeCS` (_string_)
*   `codeType` (_string_)
*   `externalId` (_string_)
*   `codeAssignedDate` (_string (date-time)_)
*   `codeRedeemed` (_boolean_)
*   `codeRedeemedDate` (_string (date-time)_)
*   `storeCode` (_string_)
*   `promotionValidDate` (_string (date-time)_)
*   `type` (_string_)
*   `message` (_string_)
*   `validFrom` (_string (date-time)_)
*   `validTo` (_string (date-time)_)
*   `updatedOn` (_string (date-time)_)

### CustomerOrder

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128. Example: `PS00027533`.
*   `quoteId` (_string_, nullable) Quote reference identifier. Links the order to a quote. Available when the order is based on a quote.  
    Maximum length: 128.
*   `externalQuoteId` (_string_, nullable) External quote reference identifier. Quote ID from the external system. Available when the order is based on a quote.  
    Maximum length: 128.
*   `orderStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `status` (_string_, read-only, nullable, deprecated)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderType` (_string_, nullable) Type of order. It is used in case of order fulfilled by the stores,  
    E.g. BOPIS, BOFIS, BOSS orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `email` (_string_, nullable) Customer Email ID.  
    It is available for signed-in customers or when email is captured in the  
    shipping address for guest customers.  
    Maximum length: 128.
*   `totalAmount` (_number_, required) Order total.
*   `shippingSubTotal` (_number_, nullable) Shipping sub total.
*   `shippingDiscount` (_number_, nullable) Shipping discount.
*   `shippingMethod` (_ShippingMethod_)
*   `shippingTax` (_number_, nullable) Shipping method tax.
*   `shippingTaxClass` (_string_, nullable) Shipping method tax class.
*   `taxSubTotal` (_number_, nullable) Total tax amount for this order.  
    It is applicable for regions/countries where Tax is supported. For countries where VAT is applicable, refer to valueAddedTax.  
    
*   `taxExemption` (_number_, nullable) The tax exemption amount for this order.  
    It is applicable whenever an associate applies a tax exemption to the order in store.  
    
*   `shippingTaxExemption` (_number_, nullable) Total Shipping tax exemption amount for this order. This does not include any product price or shipping cost. It includes only the tax exemption on Shipping.
*   `valueAddedTax` (_number_, nullable) Total VAT amount for this order.  
    It is applicable for regions/countries where VAT is supported. For countries where tax is applicable, refer to taxSubTotal.  
    
*   `orderSubTotal` (_number_, required) Order total excluding discounts, shipping costs and taxes but  
    inclusive of VAT.
*   `tenders` (_array of OrderPaymentDetail_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.  
    When importing an order paid with a credit card from an external system, make sure to include all required fields as well as the following fields:  
    1\. requestId  
    2\. cardType  
    For a **referenced refund** on the credit card, all the above fields and CMS configuration are necessary. Set the below CMS property to **Default** to initiate a referenced refund.  
    **CMS** > **Store Management** > **Store Settings** > **Refund Mode for External Order**.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products.  
    The list doesn't include returned products. While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `orderProductList` (_array of OrderProduct_, required) A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.
*   `returnProductList` (_array of ReturnedProduct_, nullable) List of items that have been returned.  
    While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `discount` (_number_, nullable) Order discount amount. Total discount applied using promo coupons and/or item level price override.  
    It doesn't include transaction discount. For transaction discount, refer to transactionDiscountAmount.  
    Mandatory: If any promo coupon is applied or any item level price override is applied.
*   `externalOrderId` (_string_, nullable) The reference ID of the order that corresponds to the external system. This is relevant in cases where the external downstream system or ERP system uses its own ID instead of the POS order ID for further processing. It is necessary to provide this reference ID while importing the order in POS, especially when updates like returns are required.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store where the order is captured. For BOPIS orders placed via a website,  
    this field contains the store ID for pickup.  
    Maximum length: 128.
*   `storeAssociateId` (_string_, required) The logged-in store associate's ID.  
    Maximum length: 256.
*   `orderSource` (_string_, required) This is the channel or source of an order or transaction. It must be IN\_STORE for all orders placed in store. It must be WEB for all orders placed on the website. When importing an order from an external system, ensure to provide: 1. IN\_STORE for orders placed in store, otherwise the order will not be available in CMS under successful order report. 2. WEB for orders placed on the website to skip its entry from successful order report.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `paymentSource` (_string_, nullable) Payment source. If an order is paid with a single tender,  
    it has the payment method of that tender. The following payment methods  
    are supported: CreditCard, Unknown, External, GiftCard, MixedMode, Cash, Miscellaneous,  
    Finance, StoreCredit, PayByLink, RemotePayByLink, Reward, and Check.  
    In the case of multi-tender payment, the payment source should be MixedMode.
*   `shippingMethodId` (_string_, nullable) Shipping method ID.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `installationId` (_string_, nullable) The device identifier is required for IN\_STORE purchases.  
    If not provided, it defaults to EXTERNAL for orders from external systems.  
    Default: `EXTERNAL`. Maximum length: 128.
*   `lastDateToReturnTimeStamp` (_integer (int64)_, nullable) Last date to return. The return window policy sets the last date for a return.  
    For example, if the policy is one month long and a sale occurs on April 1st,  
    the lastDateToReturnTimeStamp will be set to May 1st.  
    When an order is imported from an external system,  
    the system will determine the order's eligibility for return based on the provided date.  
    If the date is not provided, the item can be returned without any time limitation.  
    Note: Represented as number of milliseconds since epoch.  
    .  
    Example: `1653078974310`.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown. Mandatory if tax engine is configured along with tax rates.  
    For VAT countries, refer to vatRates.
*   `taxExemptions` (_array of TaxExemptionRequest_, nullable) List of tax exemptions, if any, applied to order.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown. Mandatory if tax engine is configured along with VAT rates. For TAX countries, refer to taxRates.
*   `shippingName` (_string_, nullable) Shipping name  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.name from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingDescription` (_string_, nullable) Shipping description.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.description from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingCarrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Required for delivery orders.  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.carrier from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingServiceLevel` (_string_, nullable) Shipping service level, for example, 3-5 Days, 1-Day, Express, Standard, or Overnight.  
    Required for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.serviceLevel from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `phoneNumber` (_string_, nullable) Customer phone number. Mandatory for signed-in customers  
    or when phone number is captured in the shipping address for guest customers.  
    
*   `orderDate` (_integer (int64)_, required) Date when order was placed.  
    Represented as number of milliseconds since epoch.
*   `coupons` (_array of string_, nullable) List of coupon codes applied for this order.
*   `customerProfile` (_Profile_)
*   `updateDate` (_integer (int64)_, required) Date when the order was last updated. Represented as number of milliseconds since epoch.
*   `taxableAmount` (_number_, nullable) Taxable amount.  
    Mandatory if the tax engine is configured along with tax rates.
*   `fulfillmentType` (_string_, required, deprecated) Order fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `rewardAmount` (_number_, nullable) Reward amount applied to this order if any.
*   `transactionDiscountAmount` (_number_, nullable) Transaction discount applied to this order if any.
*   `canReturn` (_boolean_, write-only, nullable) Flag indicating if this order can be returned.  
    During order import in POS, if it is not provided,the order remains returnable.
*   `paymentDetails` (_array of OrderPaymentDetail_, nullable, deprecated) Deprecated. Use 'tenders' instead.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Order refund payment details.  
    If an order is returned, it will have all refunded tenders.  
    
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `failedReasonCode` (_string_, read-only, nullable) Failed order reason code corresponding to payment.  
    Possible values are CANCELED, PAYMENT\_DECLINED, and PAYMENT\_REVERTED.  
    Applicable only if the order fails. Not required when importing an order from an external system.  
      
    Allowed values: `CANCELED`, `PAYMENT_DECLINED`, `PAYMENT_REVERTED`, `PAYMENT_REVERSAL_FAILED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_NOT_FOUND`.
*   `twoPhaseCommitReferenceId` (_string_, read-only, nullable, deprecated) Used for internal processing. Don't use in external systems.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `partiallyPaid` (_boolean_) Flag indicating if this order is partially paid for.
*   `orderActivityLog` (_array of OrderActivityLog_, nullable) The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.
*   `storeAttribution` (_StoreAttribution_)
*   `tipTotal` (_number_, nullable) Total tip added to the order.
*   `orderFiscalData` (_array of OrderFiscalData_, nullable) All fiscal data for this order if any.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `offlineMode` (_boolean_, nullable) Flag indicating if the order got created in offline mode.  
    If not mentioned, it is considered as false.
*   `employee` (_Employee_)
*   `originalOrderId` (_string_) Order ID of the original order if the order is an exchange order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method and other delivery details.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    2\. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `rewardList` (_array of Reward_, read-only, nullable) The list of loyalty rewards applied in this transaction.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `returnCustomerInformationList` (_array of OrderReturnCustomerInformation_, nullable) List of customer/person who returned the items.  
    Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.  
    
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `taxFreeDocument` (_TaxFreeDocument_)
*   `orderRefundFeeDetailList` (_array of OrderRefundFeeDetail_, nullable) List of Refund fee like restocking fee on returned or canceled items.  
    Applicable when item is returned or canceled and refund fee is configured.  
    For more detail on refund fee,
*   `error` (_boolean_)

### PaymentData

*   `paymentType` (_string_)
*   `paymentCard` (_Card_)
*   `paymentCardToken` (_string_)
*   `paypalData` (_PaypalData_)
*   `squareData` (_SquareData_)
*   `adyenData` (_AdyenData_)
*   `authorizationCode` (_string_)
*   `reasonCode` (_integer (int32)_)
*   `transactionId` (_string_)
*   `transactionHash` (_string_)
*   `referenceTransactionId` (_string_)
*   `avsResultCode` (_string_)
*   `requestToken` (_string_)
*   `transactionToken` (_string_)
*   `subscriptionId` (_string_)
*   `paymentToken` (_PaymentToken_)
*   `method` (_string_)  
    Allowed values: `Cash`, `Credit`, `External`, `MixedMode`, `PaypalExpress`, `GiftCard`, `Braintree`, `StoreCredit`, `OrderCredit`, `AfterPay`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`, `CreditCard`, `Check`.
*   `paymentNetworkTransactionId` (_string_)
*   `cashTotal` (_number_)
*   `paymentCards` (_array of Card_)
*   `savePaymentData` (_boolean_)
*   `amount` (_number_)
*   `authenticationResponse` (_string_)
*   `returnsGiftCardProduct` (_Product_)
*   `decision` (_string_)
*   `installmentToken` (_string_)
*   `orderPaymentDetail` (_ExchangeOrderPaymentDetail_)
*   `originalTenders` (_array of ExchangeOrderPaymentDetail_)
*   `performUnreferencedRefunds` (_boolean_, deprecated) Use refundMode instead.
*   `orderDate` (_integer (int64)_)
*   `cashDrawerUrl` (_string_)
*   `disclaimerText` (_string_)
*   `roundingAmount` (_number_)
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.
*   `refundMode` (_string_, nullable) Provides the refund mode that requires special handling. Possible values: Unreferenced for unreferenced refund and ExternalAuth for call for auth refund. These refunds are to be issued by the app. If refund mode is empty, regular refund flow will be followed.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `paymentTransactionId` (_string_, nullable) Payment Transaction ID. Used in cases where payment transaction ID is pre-generated and used as reference number by the app side payment gateway integration. Used in case of Elavon.

### OrderReturnsPolicy

All applied return policies.

*   `maxCashRefundAllowed` (_number_)
*   `managerOverrideAllowed` (_boolean_)
*   `applicableReturnsPolicyTypes` (_array of string_)  
    Items: Allowed values: `MaxReturnsDays`, `MaxCashReturns`, `RemapRefundTenders`, `StoreCredit`, `GiftCard`, `CustomerNotInPersonRefund`, `CreditCard`, `NoReceiptReturns`, `Check`.

### OrderPaymentDetail

Deprecated. Use 'tenders' instead.

*   `transactionId` (_string_, required) The unique identifier for a transaction that completes the order. - This is particularly helpful in cases where a payment is made in multiple transactions, such as in the case of a deposit. - In POS, the transaction ID corresponds to the sale transaction when you place an order. - However, if you import an order from an external system, the transaction ID should correspond to the order in the external system and can be the same as the Order ID.  
    Maximum length: 128.
*   `paymentId` (_string_, required) The unique identifier for a payment/tender. As the order can have multiple payments, each payment will have a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method. Required for BOPIS and BOFIS. Not applicable for ROPIS.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. Possible values are: - `UNPROCESSED` is used internally by cloud services as a transient state. - `DISCARDED` is used when cash tender is part of a multi-tender payment and is deleted by swiping right. - `ABORTED` is used when we internally remove a tender from the tender list and add a new tender (e.g., for gift cards).  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device. If the payment is made in an external system, set the payment device to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards and gift cards through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender. Applicable for credit cards. for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal. Typically used for referenced refunds that are performed automatically by the POS without the customer presenting the card during a refund. In the case of Adyen payments, this field maps to `pspReference`. Required for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode, it generates a temporary payment ID, which is provided in the alternate payment request ID attribute. For example, the Adyen terminal generates a temporary ID called a "tender reference" whenever it goes into store and forward mode. This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund payment request ID issued by the payment gateway/terminal. Required for refund on credit cards.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item, and the original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried forward to the new order. This attribute provides the original order ID if the tender is carried over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item. The original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried over to the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and the tender is carried over to the new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Required for credit card payments using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment. For example, if a customer pays with cash first and the remaining amount with a credit card, the cash tender should have a paymentSequenceNumber of 1, and the credit card tender should have a paymentSequenceNumber of 2.
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number. Applicable when payment method is 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check' and 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.
*   `cardToken` (_string_) This field contains the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment** Gateways > Adyen > Payment Tokenization Events).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender. Normally, it is received after calling a call center agent of a payment processor. For example: call for authorization code after check denial or referral, or manual authorization code for a credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Required for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee. Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to finance approval/order/confirmation number in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### ExchangeOrderPaymentDetail

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `refundAmount` (_number_)
*   `amountToBeAppliedForExchange` (_number_)
*   `refundTransactionId` (_number_)
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use refundMode instead.
*   `refundRoundingAmount` (_number_)
*   `refundMode` (_string_, nullable) If the tender requires special handling when performing a refund, provide the specific refund mode here. Supported modes are Unreferenced and ExternalAuth. For example, during a credit card authorization call, provide the refund mode ExternalAuth when the app issues the refund instead of the regular flow.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `splitRefund` (_boolean_) If an original tender is split into multiple refunds during return and if the current refund tender is one of the split refunds of the original tender. Used in MaxCashReturn policy where original tender might get split into two during returns.
*   `validRefundTender` (_boolean_)
*   `remapped` (_boolean_)
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### ReturnProductIdentification

Returning item's orderItemId and quantity.

*   `orderItemId` (_string_, required) Order item ID of returning product obtained from original order. It provides the returning item's line item number from the original order.
*   `quantity` (_integer (int32)_, required) Total quantity being returned.
*   `reason` (_Reason_)
*   `epc` (_string_) Electronic Product Code/RFID.
*   `serialNumbers` (_array of string_, nullable) Provide serial numbers for returning product if applicable and captured by store associate.  
    Unique items.

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### PaymentInstallmentItem

*   `amount` (_number_)
*   `text` (_string_)

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### AccountHolder

Account Holders information. Used in case of Tender Type - Finance.

*   `name` (_string_)
*   `primary` (_boolean_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### Transactions

Loyalty transactions.

*   `nextStartMonth` (_integer (int32)_)
*   `txnActivity` (_array of TransactionActivity_)

### Tier

Customer's next tier details.

*   `name` (_string_) Tier name.
*   `minPoints` (_number_) Minimum points required for the tier.
*   `display` (_string_)
*   `points` (_integer (int32)_)
*   `memberSince` (_integer (int64)_) Member since, of this tier.
*   `title` (_string_)
*   `subTitle` (_string_)
*   `imageUrl` (_string_)
*   `expiryDate` (_integer (int64)_) Expiry date of the customer's membership.

### CustomAttributes

Custom attributes.

*   `customLabel` (_string_)
*   `customValues` (_array of CustomValue_)

### PersonalID

Customer/Person Identification Information.

*   `type` (_string_, nullable) ID type, for example, State ID, Military ID, or Driving License.
*   `value` (_string_, nullable) ID Number/Value.
*   `expiry` (_string (date-time)_, nullable) ID Expiration Date.
*   `issuedBy` (_string_, nullable) Issued by state.

### RefundTender

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `paymentSequenceNumber` (_integer (int32)_, required) Payment sequence indicating the order of payment. For example, if customer pays partially with cash first and remaining with credit card, then cash tender should have paymentSequenceNumber as 1 and credit card tender should have paymentSequenceNumber as 2.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentDevice` (_string_, required) Identifies the payment device through which the payment is made. If payment data is manually entered, this field should be set to NoReader. If payment is made in an external system, payment device should be set to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `rawPaymentPayload` (_string_) Raw payment payload. For future use.
*   `routingNumber` (_string_) Bank routing number.
*   `accountNumber` (_string_) Account number. Used for payment through banking system.
*   `checkNumber` (_string_) Check number. Used for payment through checks.
*   `personalIdType` (_string_) Personal identification type.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_) Issuer of the personal identification.
*   `personalIdNumber` (_string_) Personal identification number.
*   `personalIdExpiryDateMillis` (_integer (int64)_) Personal identification expiry date represented as milliseconds since epoch. Typically expiry date is end of the day and milliseconds since epoch should reflect it accordingly.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry).
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardCvc` (_string_) Card CVC. Used in case of manual credit card data entry.
*   `track1Data` (_string_) Encrypted track1 data. Used in case of client/app side card encryption by readers like Verifone.
*   `track2Data` (_string_) Encrypted track2 data. Used in case of client/app side card encryption by readers like Verifone.
*   `paymentDeviceId` (_string_) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.
*   `operatingMode` (_string_) Operating mode of the app and card reader - ONLINE/OFFLINE. Other values are unused.  
    Allowed values: `ONLINE`, `OFFLINE`, `DEGRADED`, `TWO_PHASE_STAGING`.
*   `encryptedExpiryDate` (_string_) Encrypted expiry date. Used in case of client/app side card encryption by readers like Verifone.
*   `encryptedCardNumber` (_string_) Encrypted card number. Used in case of client/app side card encryption.
*   `encryptedCvv` (_string_) Encrypted card CVV. Used in case of client/app side card encryption.
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `storedCardId` (_string_) Stored Card ID to use in case of card stored for the customer profile.
*   `cardType` (_string_) Card type. For example, Visa, Master, Amex, or Discover.
*   `rawCardType` (_string_) Raw card type, for example, Visa Credit Card, Visa Debit Card, or Master Credit Card. Typically used when an Adyen terminal captures card data for payment.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year.
*   `pin` (_string_) PIN number typically used for gift card.
*   `authorizationToken` (_string_) Payment authorization token.
*   `authorizationDateMillis` (_integer (int64)_) Payment authorization timestamp as number of milliseconds since epoch.
*   `captureToken` (_string_) Payment capture token.
*   `captureDateMillis` (_integer (int64)_) Payment capture timestamp as number of milliseconds since epoch.
*   `requestId` (_string_) Payment request identification issued by payment gateway/terminal. Typically used for referenced refunds. This field maps to pspReference in case of Adyen payments.
*   `alternateRequestId` (_string_) Alternate payment request identification issued by payment terminal. Example, tender reference in case of Adyen terminal is in store and forward mode.
*   `requestToken` (_string_) Payment request token issued by payment gateway/terminal. Typically used for referenced refunds.
*   `firstName` (_string_) First name to use for billing using this tender.
*   `lastName` (_string_) Last name to use for billing using this tender.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.
*   `city` (_string_) City to use for billing using this tender.
*   `state` (_string_) State to use for billing using this tender.
*   `postalCode` (_string_) Postal code to use for billing using this tender.
*   `country` (_string_) Country code to use for billing using this tender.
*   `paypalInvoiceId` (_string_) Invoice ID. Used when payment is done using paypal reader.
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_) External payment reference identifier in case of External tender.
*   `paymentGatewayConfigId` (_string_) Payment Gateway ID - to be used in case of multiple payment gateways are available to process a single tender.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt.
*   `merchantReferenceId` (_string_) Merchant reference ID sent to the payment terminal for this tender. This is required for match response received off asynchronously from payment processor (like Adyen Store and Forward) with the correct payment object for an order.
*   `paymentStatus` (_string_) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `checkType` (_string_) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_) Manual authorization code for a tender. Normally it is received after calling a call center agent of a payment processor. For example, call for auth code after check denial/referral, manual auth code for credit card when offline.
*   `paymentTypeCode` (_string_) Type of payment plan. Used when the tender type is Finance.
*   `cardPresent` (_boolean_) Indicates if the card is physically present or not. Used in case of Tender Type - Finance.
*   `ssn` (_string_) Customer's Social Security Number for verification purposes. Used in case of Tender Type - Finance.
*   `accountHolders` (_array of AccountHolder_) Account Holders information. Used in case of Tender Type - Finance.
*   `additionalInfo` (_array of string_) List of additional information required to verify the buyer. Used in case of Tender Type - Finance.
*   `cashDrawerUrl` (_string_) Represents custom URL using which cash drawer in the network can be accessed.
*   `roundingAmount` (_number_) The delta amount because of rounding.
*   `authStatus` (_string_) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_) Tip amount to capture on credit card.
*   `captureStatus` (_string_) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_) Refers to the finance approval/order/confirmation number in the external system.
*   `financeInstruction` (_string_) Refers to finance processing related result or instruction long text from external system.
*   `primaryAccountHolder` (_string_) Primary owner on the account.
*   `tradeType` (_string_) Trade Type. In case of WeChatPay: QuickPay.
*   `bankType` (_string_) Bank Type.
*   `fundingSource` (_string_) Funding source like PREPAID.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `paymentLink` (_string_) Payment Link.
*   `paymentLinkExpiryDate` (_string_) Payment Link expiry date.
*   `paymentId` (_string_) Payment Id from app.
*   `transactionId` (_string_) The transactionId from app's requestId.
*   `paymentReversalStatus` (_string_) Payment Status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi tender and delete by swiping right, ABORTED is used where we internally remove tender from our tender list and add a new tender for eg gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `captureAmount` (_number_) Amount captured for credit card.
*   `requestTokenExpireDate` (_integer (int64)_) Request token expire date.
*   `continueOnPendingOrDecline` (_boolean_) Continue order processing on tender pending or decline status.
*   `termsAndConditions` (_string_) Terms and conditions.
*   `gcBalance` (_number_, nullable) Balance remaining in case of tender type gift card.
*   `cashTenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `cashChangeAmount` (_number_) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response by gateway. In adyen - a value that uniquely represents the shopper's card number (PAN).
*   `paymentEntryMode` (_string_) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `refundRequestId` (_string_) Refund ID provided by the payment processor after issuing the refund. For example, pspReference in case of Adyen.
*   `refundDate` (_integer (int64)_) Date and time of the refund.
*   `refundedAmount` (_number_) Total amount refunded.
*   `performedUnreferencedRefunds` (_boolean_) Deprecated. Use refundMode instead.
*   `refundedAsPartOfOrderId` (_string_) Order that involves returning an item along with purchase and still refund is issued.
*   `originalTenders` (_array of ExchangeOrderPaymentDetail_) Original tenders associated with the refund.
*   `refundMode` (_string_, nullable) If the tender requires special handling when performing a refund, provide the appropriate refund mode here.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `refundIssued` (_boolean_, read-only, nullable) Flag to indicate refund issued by backend for tenders which are collected by app.  
    Example: `false`.
*   `manualCardEntry` (_boolean_)
*   `error` (_boolean_)

### ProductDeltaDeliveryGroup

List of delivery groups for product.  
, corresponding order item id and new delivery group id.  
It is used for edit order only when changing the delivery group for existing item.

*   `deliveryGroupId` (_string_, required) Delivery group id. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ProductDeliveryGroup

*   `orderItemId` (_string_)
*   `deliveryGroup` (_DeliveryGroup_)

### DeltaOrderNote

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `noteStatus` (_string_, nullable) Note Status for Edit Order, only used in transaction data, Will not persist to Database.  
    Allowed values: `ADD`, `UPDATE`.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### DeltaOrderDetailNote

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `noteStatus` (_string_, nullable) Note Status for Edit Order, only used in transaction data, Will not persist to Database.  
    Allowed values: `ADD`, `UPDATE`.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductPickUpDetail

List of product pickup detail.  
Applicable if the order is edit order.

*   `orderItemId` (_string_)
*   `pickupDetailId` (_string_)
*   `pickupLocation` (_Store_)
*   `dateTimeSlot` (_DateTimeSlot_)

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### FeedFileMetadata

*   `fileName` (_string_)
*   `feedFileType` (_string_)  
    Allowed values: `CSV`, `TSV`, `SSV`, `PSV`, `XML`, `STORE_XML`, `INVENTORY_XML`, `JSON`, `YEXT`, `ASN_EDI_856`, `OTHER`.
*   `feedPreprocessorClass` (_string_)
*   `parentTag` (_string_)
*   `multiValueFieldList` (_array of string_)
*   `preserveIfNullFieldList` (_array of string_)
*   `idColumn` (_string_)
*   `multiValueFieldDelimiter` (_string_)
*   `columnNames` (_string_)
*   `sourceEncoding` (_string_)

### OrderProduct

A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orignalQuantity` (_integer (int32)_)
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ReturnedProduct

List of items that have been returned. While importing an order from an external system, it is optional as the products and return products both can be provided in orderProductList.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `refundDate` (_integer (int64)_, required) The date and time, in milliseconds since epoch, when the item was returned.  
    Example: `1617222000000`.
*   `exchangedForOrderId` (_string_, nullable) The order ID for which the item was exchanged. Applicable for exchange.  
    Maximum length: 128.
*   `returnedAtStoreId` (_string_, required) The store ID where the item was returned.  
    Maximum length: 256.
*   `returnProcessedByAssociateId` (_string_, required) ID of the store associate who performed the return.  
    Maximum length: 256.
*   `returnedAtStoreRegisterId` (_string_, required) The register ID where the item was returned.  
    Maximum length: 128.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `offlineMode` (_boolean_, nullable) Specifies whether the item is returned in offline mode. If not provided, it is considered to be in online mode.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderRefundPaymentDetail

Refund payments.  
For return or exchange transactions, this contains the refund payments.  

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) A transaction ID is a unique identifier corresponding to the return  
    transaction. It is especially useful in situations where a refund is issued in multiple  
    return transactions. When importing an order from an external system and it has a refund,  
    the transaction ID should match the return transaction that carried out the refund.  
    In case the external system doesn't have a return transaction ID, you can use the order  
    ID in its place.  
    Maximum length: 128.
*   `paymentId` (_string_, required) It is a unique identifier for refund payments.  
    It must be unique within an order. When multiple refunds are issued for a single payment,  
    a unique ID is necessary to differentiate each refund.  
    Maximum length: 128.
*   `cardNumber` (_string_, nullable) Card Number to which refund was applied. Last 4 digits in case of refund to CreditCard. Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardType` (_string_, nullable) Card type, for example, mastercard, interac\_card, or visa.  
    Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `originalPaymentId` (_string_, required) A refund is issued against a original payment.  
    This ID provides a reference to the original payment.  
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Reference to original transaction that performs the payment.  
    This ID provides a reference to the original transaction.
*   `paymentMethod` (_string_, required) Refund payment method, for example, Cash or CreditCard.  
    For possible values, see the tenders.paymentMethod attribute.
*   `refundDate` (_string (date-time)_, required, nullable) Timestamp when refund payment was processed.Format: yyyy-MM-dd HH:mm:ss.
*   `refundedAmount` (_number_, required) Refund Amount.  
    Example: `100`.
*   `refundedAsPartOfOrderId` (_string_, nullable) Original Order Id for which this refund payment is processed.  
    Maximum length: 128.
*   `refundRequestId` (_string_, nullable) Refund request identification issued by the payment gateway/terminal.  
    In the case of Adyen payments, this field maps to pspReference of a refund.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use RefundMode instead.
*   `paymentDevice` (_string_, nullable) Device using which payment was refunded. For possible values, please refer to tenders.paymentDevice attribute. Applicable for CreditCard refund only.  
    Maximum length: 32.
*   `paymentDeviceId` (_string_, nullable) Payment Device Identifier. Applicable for CreditCard refund only.  
    Maximum length: 128.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt lines for refund payment.  
    Available in case of unreferenced refunds using CreditCard.  
    Unreferenced refunds are refunds that are not associated with a original payment and  
    customer is prompted to swipe/tap CreditCard during refund.  
    When an order is imported from an external system, it is optional.  
    
*   `cardExpirationMonth` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration month of the card to which payment was refunded.
*   `cardExpirationYear` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration year of the card to which payment was refunded.
*   `roundingAmount` (_number_, nullable) Rounding amount during refund using cash. Applicable for cash refund  
    in regions where rounding is applicable.
*   `refundMode` (_string_, nullable) Refund Mode. It is applicable for CreditCard refunds. The modes are:  
    1\. Unreferenced: Refund is not associated to original payment and is issued on different credit card  
    2\. External: Refund is initiated externally and not by POS  
    3\. Default: Regular refund. It is initiated by POS against original CreditCard  
    It is not necessary to provide this while importing an order from external system.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `fundingSource` (_string_, nullable) Funding source, for example, CREDIT, DEBIT, or CHARGED.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `tip` (_number_) Refunded Tip.
*   `tenderBalance` (_number_) Gift Card balance after refund. Available in case of Gift Card refund.
*   `cardAlias` (_string_, nullable) Card alias of the card to which payment was refunded.
*   `externalPaymentSystemId` (_string_, nullable) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_, nullable) External payment reference identifier in case of External tender.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderActivityLog

The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) The unique Id identifying the transaction.  
    Maximum length: 128. Example: `2808-10-20240419131925-2-7`.
*   `amount` (_number_, nullable) The total transaction amount value.
*   `associateSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `data` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `installationId` (_string_, required, read-only) Unique ID of the register.  
    Maximum length: 128.
*   `productId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `storeAssociateId` (_string_, nullable) The Id of the particular associate at a store.
*   `storeId` (_string_, nullable) The identifier of the store where the order is taking place.  
    Maximum length: 128.
*   `transactionDate` (_string (date-time)_, required) Transaction time, that is, the time when the transaction was executed.
*   `transactionType` (_string_, nullable) The type of transaction. Three types of transactions can be done on an order: SALE, RETURN, and EXCHANGE.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.
*   `userSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `appTransactionId` (_string_, nullable) Unique sequence number generated by POS App. It is reset after daily or relaunch of the App.  
    Maximum length: 48. Example: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ...`.
*   `transactionData` (_Transaction_, required)
*   `manualReceiptId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `s3KeyTransactionData` (_string_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `transactionStartDate` (_string (date-time)_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `receiptPrintCount` (_integer (int32)_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderFiscalData

All fiscal data for this order if any.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier which lead to this payment capture/refund.
*   `transactionType` (_string_) Transaction Type.
*   `fiscalData` (_string_) Fiscalization Data.
*   `printData` (_array of PrintData_) Fiscalization Data that needs to be printed on receipt.
*   `fiscalTransactionId` (_string_) Fiscal Transaction ID.
*   `receiptPrintCount` (_integer (int32)_) Combined Count of transaction paper/e-receipts.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderReturnCustomerInformation

List of customer/person who returned the items. Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier.
*   `firstName` (_string_) First name of the person.
*   `lastName` (_string_) Last name of the person.
*   `email` (_string_) Email of the person.
*   `phone` (_string_) Phone number of the person.
*   `addressLine1` (_string_) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_) City.
*   `state` (_string_) State.
*   `postalCode` (_string_) Postal Code.
*   `country` (_string_) Country.
*   `idType` (_string_) ID Type.
*   `idValue` (_string_) ID Value.
*   `idIssuedBy` (_string_) ID Issued By.
*   `idExpiry` (_string (date-time)_) ID Expiry Date.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### TaxFreeDocument

Tax-free document associated with this order.

*   `docId` (_string_) Global Blue tax-free document identifier.
*   `status` (_string_) Current status of the tax-free document (ISSUED or VOIDED).  
    Allowed values: `ISSUED`, `VOIDED`.

### OrderRefundFeeDetail

List of Refund fee like restocking fee on returned or canceled items.  
Applicable when item is returned or canceled and refund fee is configured.  
For more detail on refund fee,

*   `orderId` (_string_) OrderID towards the refund fees are applied.
*   `transactionId` (_string_) Refund transactionId during which refund fees are applied.
*   `storeId` (_string_) Store where the refund is performed.
*   `refundFeeId` (_string_) Refund fee id Eg. Restocking, Miscellaneous.
*   `refundFeeLabel` (_string_) Refund fee display name Eg. Restocking Fee, Miscellaneous Fee.
*   `refundFeeAmount` (_number_) Refund fee amount.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Card

Use the card number in the card object to search. Typically by the last four digits of the card customer used to make payment.

*   `paymentId` (_string_) Payment ID/Card ID.
*   `cardOwner` (_string_) Card Owner.
*   `cardType` (_string_) Card Type.
*   `cardNumber` (_string_) Card Number.
*   `cardCvc` (_string_) Card CVC.
*   `cardExpirationMonth` (_integer (int32)_) Card Expiration Month.
*   `cardExpirationYear` (_integer (int32)_) Card Expiration Year.
*   `rawCardType` (_string_, nullable) Raw Card Type.
*   `billingAddressId` (_string_) Billing address ID.
*   `cardNickName` (_string_, nullable) Card Nick Name.
*   `track1Data` (_string_, nullable) Track1 Data if payment is done by app.
*   `track2Data` (_string_, nullable) Track2 Data if payment is done by app.
*   `deviceId` (_string_, nullable) Device ID.
*   `authAmount` (_number_, nullable) Amount to be authorized.
*   `authCode` (_string_, nullable) Authorization code.
*   `captureCode` (_string_, nullable) Capture code.
*   `cardToken` (_string_, nullable) Card token.
*   `cardId` (_string_)
*   `requestId` (_string_, nullable) Request ID used in POS.
*   `requestToken` (_string_, nullable) Request Token.
*   `encryptedCardNumber` (_string_, nullable) Encrypted Card Number.
*   `encryptedCvv` (_string_, nullable) Encrypted Cvv.
*   `paymentMethod` (_string_, nullable) Payment Method.
*   `transactionId` (_string_, nullable) Transaction Id.
*   `encryptedExpiryDate` (_string_, nullable) Encrypted Expiry Date.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt Lines.
*   `paypalData` (_PaypalData_)
*   `squareData` (_SquareData_)
*   `adyenData` (_AdyenData_)
*   `thirdPartyToken` (_string_, nullable) Third party token. Used in case of aurus tokenization.
*   `manualCardEntry` (_boolean_)

### PaypalData

PayPal details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `payerId` (_string_)
*   `token` (_string_)
*   `email` (_string_)
*   `payPalInvoiceId` (_string_)
*   `referenceTransactionId` (_string_)
*   `authTransactionId` (_string_)
*   `payPalTokenTimestamp` (_string_)

### SquareData

Square Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `clientId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)

### AdyenData

Adyen Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `pspAuthCode` (_string_)
*   `pspReference` (_string_)
*   `cardType` (_string_)
*   `cardHolderName` (_string_)
*   `cardExpiryYear` (_string_)
*   `cardExpiryMonth` (_string_)
*   `cardString` (_string_)
*   `tenderReference` (_string_)
*   `terminalId` (_string_)
*   `cardNumber` (_string_)
*   `operatingMode` (_string_)
*   `threeds2Details` (_string_)

### PaymentToken

*   `data` (_string_)
*   `header` (_PaymentTokenHeader_)
*   `signature` (_string_)
*   `version` (_string_)

### TransactionActivity

*   `orderId` (_string_)
*   `date` (_integer (int64)_)
*   `description` (_string_)
*   `points` (_integer (int32)_)
*   `amount` (_number_)
*   `pointStatus` (_string_)  
    Allowed values: `EARNED`, `PENDING`, `REWARD`, `REDEEMED`.
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    

### CustomValue

*   `laabel` (_string_)
*   `value` (_string_)
*   `iconType` (_string_)

### Transaction

The transaction details.

*   `transactionTimeStamp` (_integer (int64)_, required) Timestamp from when the transaction was executed. Epoch time in milliseconds.  
    Example: `1714112491`.
*   `transactionType` (_TransactionType_)
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128.
*   `summary` (_CartSummary_, required)
*   `storeAttribution` (_StoreAttribution_)
*   `receiptPrintCount` (_integer (int32)_, nullable) Receipt print count — the number of original and duplicate receipts.  
    Default: `1`.
*   `fiscalData` (_OrderFiscalData_)
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions. Applicable for tax countries and if the sale is tax exempted.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `tenders` (_array of OrderPaymentDetails_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Refund payments. If it is a return or exchange transaction, it will have refund payments.
*   `shippingAddress` (_Address_)
*   `shippingMethod` (_ShippingMethod_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products in this order. The list doesn't include returned products. Required for sale transactions. For returns where all items were returned, the list is empty.
*   `returnProductList` (_array of Product_, nullable) List of items that have been returned. It is mandatory for return and exchange transaction.
*   `numberOfLineItems` (_integer (int32)_, read-only) Total number of line items.
*   `receiptId` (_string_, read-only, nullable) Receipt ID for the transaction. Applicable for fiscal reporting.
*   `store` (_Store_, required)
*   `profile` (_Profile_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `returnProductPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `customerEmail` (_string_, nullable) Customer email ID. Available for signed-in customers or when email is captured in the shipping address for guest customers.  
    Maximum length: 128.
*   `manualReceiptId` (_string_, nullable) Manual receipt ID. Required in some countries like Portugal where a pre-printed paper receipt with its own receipt ID needs to be issued for offline transactions.
*   `offlineMode` (_boolean_, nullable) Flag indicating if the transaction was executed in offline mode or not.  
    Default: `false`.
*   `referenceReceiptId` (_string_, nullable) Reference receipt ID. Populated for return and exchange transactions. This field provides original sale's receipt ID for reference.
*   `storeAssociate` (_Associate_)
*   `duplicateReceiptText` (_string_) For internal use only. Don't use in external systems. Duplicate receipt text printed on the receipt, for example, 'Duplicata' or 'Copy of Original Document'.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `productNotesList` (_array of OrderDetailNote_, nullable) List of product notes for this transaction if any.
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `employee` (_Employee_)
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method, and other delivery details. This field is used for item level shipping method and address. Mandatory for all delivery items if item level shipping method or item level shipping address is enabled. For more details, see:.
*   `deliveryGroupChangeList` (_ProductDeltaDeliveryGroup_)
*   `nafCode` (_string_, nullable) NAF code. NAF codes in France are used to identify the type of business of an enterprise. For example, 4772A means retail sale of footwear.
*   `rewardList` (_array of Reward_, read-only, nullable, deprecated) Deprecated. Use `orderProductList.priceAdjustments` instead.
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `productPickUpDetailList` (_array of ProductPickUpDetail_, nullable) List of product pickup detail.  
    Applicable if the order is edit order.
*   `returnCustomerInformation` (_ReturnCustomerInformation_)
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Fulfillment type for the order. For example, IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `removedDeliveryGroups` (_array of DeliveryGroup_, nullable) The removed delivery group during the edit order mode.

### PrintData

Print Data object. Used to print fiscalization related information on receipts.

*   `name` (_string_) Name of the field which holds this value.
*   `value` (_string_) Actual value that will be printed.
*   `label` (_string_) Label against which this value will be printed.
*   `type` (_string_) Indicates type of data to be printed, for example, TEXT or QRCode.  
    Allowed values: `Text`, `QRCode`.

### PaymentTokenHeader

*   `applicationData` (_string_)
*   `ephemeralPublicKey` (_string_)
*   `publicKeyHash` (_string_)
*   `transactionId` (_string_)

### TransactionType

The type of transaction. Three types of transactions can be done on an order: SALE, RETURN and EXCHANGE.

Type: `string`.

Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`, `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.

### OrderPaymentDetails

Payment information: The system supports multiple payment options.  
Whenever an order is purchased using payment instrument/s,  
the order will have this list of tenders. However, there are some exceptional scenarios  
where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.

### Associate

Store associate.

*   `storeAssociateID` (_string_) ID of the store associate (POS login ID for the associate).
*   `storeID` (_string_, nullable) Store ID of the associate.
*   `merchantUserID` (_string_, nullable) Merchant's underlying system's user ID for the store associates. For example, LoginId for underlying OMS or Salseforce Commerce.
*   `paymentDeviceMerchantID` (_string_, nullable) Merchant ID of a payment device assigned to the associate.
*   `paymentDeviceID` (_string_, nullable) ID of a payment device, like terminal ID, assigned to the associate.
*   `storeAssociatePassword` (_string_) Store associate's password (POS Login Password for the associate).
*   `merchantPassword` (_string_, nullable) Merchant's underlying system's password for the associate.
*   `storeAssociatePasswordPin` (_string_, nullable) Password hint for the associate's POS login.
*   `firstName` (_string_, nullable) First name of the associate.
*   `lastName` (_string_, nullable) Last name of the associate.
*   `storeType` (_string_) Type of the store where the associate works. Possible values include: Regular, Popup, Outlet or eComm.
*   `role` (_string_) The associate's role in the store. Possible values include: STORE\_ASSOCIATE, STORE\_MANAGER or AREA\_MANAGER.
*   `passwordSetOn` (_integer (int64)_, nullable) Date when password was set last time. Represented as the number of milliseconds since epoch.
*   `storeAssociatePasswordFlag` (_boolean_) Flag indicating that the store associate password is updated during associate update operation. Used only during update operation.
*   `merchantPasswordFlag` (_boolean_) Flag indicating that the merchant password is updated during associate update operation. Used only during update operation.
*   `storeAssociateSecretFlag` (_boolean_, nullable) Flag indicating that the store associate secret is updated during associate update operation. Used only during update operation.
*   `imageUrl` (_string_, nullable) The associate's image URL.
*   `active` (_boolean_) Specifies whether the status of the associate is active (true) or removed/deactivated (false).
*   `emailId` (_string_, nullable) Email ID of the associate.
*   `mobilePhoneNumber` (_string_, nullable) Mobile phone number of the associate.
*   `additionalStoreIDs` (_array of string_, nullable) Additional store IDs where the associate can log in.
*   `gender` (_string_) Gender of the store associate.  
    Allowed values: `Male`, `Female`, `Neutral`, `Unknown`.
*   `hireDate` (_integer (int64)_, nullable) Date when the associate is hired or can start work in the store.
*   `terminationDate` (_integer (int64)_, nullable) Termination date for the associate.
*   `firstLoginPasswordReset` (_boolean_) Flag indicating that the password is set on the first login.
*   `mobileConfigID` (_string_, nullable) Mobile configuration ID.  
    Maximum length: 128. Example: `134ac374-0f49-4239-a161-ccfe4d3d7686`.

<!-- document id=a7c6e2bd4c3222f11427f5fa82a6d7c88097d62dedfb8cb263f8974a6734a5db url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-domain-cookie.md -->

# Maintain Shopper Sessions Across Subdomains in Storefront Next

Configure a shared parent cookie domain to keep shoppers logged in with their baskets preserved when navigating between different subdomains. The domain-level cookie applies to storefronts that use multiple subdomains, such as `www.` and `shop.` on the `example.com` domain. It also applies to hybrid PWA Kit and SFRA storefronts that serve different paths under one parent domain. Without this configuration, shoppers lose their login status and shopping baskets when crossing subdomain boundaries. The loss of login status happens because browsers isolate cookies to individual hosts by default. Prevent frustration and abandoned carts by setting up domain-level cookies.

## Prerequisite

Storefront Next version 1.1 or later. See the [storefront-next-template](https://github.com/SalesforceCommerceCloud/storefront-next-template) GitHub repository.

## Configure a Shared Parent Cookie domain

1. In Business Manager, go to **Merchant Tools > _Your Site_ > Site Preferences > Hybrid Auth Settings**.
2. Under Site Settings, set the domain scope for hybrid auth cookies. To scope cookies to the current host only, enter 0 for the cookie domain level. To share cookies across across subdomains, set the level to 2.
   ![Hybrid auth cookie domain scope setting](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-cookie-domain.png)

## See Also

- [GitHub: Hybrid Cookie Domain Configuration](https://github.com/SalesforceCommerceCloud/storefront-next-template/tree/latest/docs/README-COOKIE-DOMAIN.md)

<!-- document id=4b119451dfedf4eda2871b1d6b9a1213e1d35068dac76c35e2251529af04abfa url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-domain-cookie.md -->

# Maintain Shopper Sessions Across Subdomains in Your Composable Storefront

Configure a shared parent cookie domain to keep shoppers logged-in with their baskets preserved when navigating between different subdomains. The domain-level cookie applies to storefronts that use multiple subdomains, such as `www.` and `shop.` on the `example.com` domain. It also applies to hybrid PWA Kit and SFRA storefronts that serve different paths under one parent domain. Without this configuration, shoppers lose their login status and shopping baskets when crossing subdomain boundaries. The loss of login status happens because browsers isolate cookies to individual hosts by default. Prevent frustration and abandoned carts by setting up domain-level cookies.

## Prerequisite

PWA Kit version 3.19 or later. See the [pwa-kit](https://github.com/SalesforceCommerceCloud/pwa-kit) GitHub repository.

## Configure a Shared Parent Cookie domain

1. In Business Manager, go to **Merchant Tools > _Your Site_ > Site Preferences > Hybrid Auth Settings**.
2. Under Site Settings, set the domain scope for hybrid auth cookies. To scope cookies to the current host only, enter 0 for the cookie domain level. To share cookies across across subdomains, set the level to 2.
   ![Hybrid auth cookie domain scope setting](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-cookie-domain.png)

## See Also

- [GitHub: Hybrid Cookie Domain Configuration](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/hybrid-cookie-domain-configuration.md)

<!-- document id=f7959d2d42385abdd8e4eaa601f4f9b86295f14d8ad1a5210bb8bec8d3aacd2b url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/maintain.md -->

# Maintain Your Site

Learn how to perform essential maintenance tasks to keep your Progressive Web App (PWA) Kit site running smoothly after launch. Stay informed about new features. This section contains the following documentation.

- [Upgrade Node Version](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-node-version.md)
- [Upgrade to v2](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v2.md)
- [Upgrade to v2.3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v2-3.md)
- [Upgrade to v3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.md)
- [Composable Storefront Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html)

### See Also

- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)

<!-- document id=f75a0a6d3c55489f8b64b304e824f98a73515ab0b9bb5213767b97fa40280de2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/admin/b2c-maintenance-pages.md -->

# Maintenance Pages

If your site is undergoing maintenance, upload custom maintenance pages that are shown to the customer. We support one custom maintenance page per FQDN (Fully Qualified Domain Name).

An FQDN is a complete domain name. For example, `www.mystore.com` is an FQDN. `www` is the host; `mystore` is the second-level domain; and .`com` is the top-level domain.

**note:** This task requires permissions for the **Administration** > **Custom Maintenance Pages** module and the **Merchant Tools** > **SEO** > **Aliases** module on the Production instance.

## Create Your Maintenance Page

Download a .zip file with an example of the required maintenance page structure and best practices on any instance.

1.  Select **Administration** > **Site Development** > **Custom Maintenance Pages**.
2.  On the Custom Maintenance Pages page, click **Download**.
3.  Select **_site_** > **Merchant Tools** > **Aliases**. Identify the domain names that you want to create maintenance pages for.

    **note:** Any site you want to create a maintenance page for must have its domain name configured in the hostname aliases file. The default file for an instance shows a sample of text, but the entries are commented out.

4.  Create a .zip file and maintenance page that follows the following constraints:

    - The top level of the .zip file must contain one or more folders with your site name, as defined on the Aliases page.
    - If you have sites with more than one public domain or want the maintenance page used for more than one site, create an aliases.json file. Put the file at the top of the .zip file.
    - Use a single HTML page to render the entire maintenance page.
    - The HTML page must be named `index.html` and placed at the top of the site folder.

    - Make the HTML code as simple as possible. If you must use JavaScript, keep it to a minimum and don't use ISML includes or other web-based languages at all.
    - Images and other page assets must be located in the top directory or a single subdirectory only.

    - All HTML references to images, CSS, and JavaScript must include the FQDN.

      Image syntax:

      ```html
      <img src="/www.mystore.com/spacer.gif" />
      ```

      `www.mystore.com` is the site FQDN.

      CSS syntax

      ```html
      <href ="/www.mystore.com/styles.css" rel="stylesheet"></href>
      ```

      `www.mystore.com` is the site FQDN.

    - Relative links aren't allowed. Child files and directories of the FQDN are allowed, but any link must refer to the absolute path within the .zip file. So given `www.mystore.com/index.html` and `www.mystore.com/images/logo.gif`, the link to the gif from the HTML must be `/www.mystore.com/images/logo.gif`. A relative path of `images/logo.gif` isn't supported.
    - Use lowercase characters for links only.
    - Links between domains aren't allowed. So `/www.mystore.com/index.html` can't refer to `/shop.mystore.com/logo.gif`.

## Create an aliases.json File

The aliases.json file uses the name of the site defined in the Manage Sites page for a key and the name of the folder to upload that contains the maintenance page for the site. This file is optional and used when you want to define the relationship between one or more sites and a maintenance page.

The syntax of the file is:

```json
{
  "hostname": "foldername",
  "hostname": "foldername"
}
```

Example 1: aliases.json File

This example shows a simple aliases.json file.

```json
{
  "luxbrand.eu": "www.luxbrand.eu",
  "luxbrand-store.at": "www.luxbrand.eu",
  "luxbrand-store.de": "www.luxbrand.eu",
  "luxbrand-store.eu": "www.luxbrand.eu",
  "shoebrand.com": "www.shoebrand.com",
  "kidsshoebrand.com": "www.shoebrand.com",
  "nonoprofit.net": "www.nonoprofit.net",
  "drinkbrand.com": "www.drinkbrand.com",
  "drinkbrand.event.com": "www.drinkbrand.com",
  "intlbrand.at": "www.intlbrand.at",
  "intlbrand.ch": "www.intlbrand.ch",
  "intlbrand.com": "www.intlbrand.com",
  "intlbrand.de": "www.intlbrand.de",
  "intlbrand.eu": "www.intlbrand.eu",
  "intlbrand.fr": "www.intlbrand.fr",
  "intlbrand.nl": "www.intlbrand.nl",
  "intlbrand-online.be": "www.intlbrand-online.be",
  "intlbrand.si": "www.intlbrand.si"
}
```

## Maintenance Page Scenarios

If necessary, adjust your `index.html` or `aliases.json` file for different scenarios.

Maintenance Pages and Multiple Locales

If you have multiple sites for different languages, such as `mysite.de` and `mysite.fr`, then each FQDN can have a separate maintenance page uploaded, regardless of what B2C Commerce site the FQDN actually points to. For example, `mystore.de` and `mystore.fr` might both point to `Sites-mystore-Site`.

However, if you have only one FQDN then you can't upload multiple maintenance pages for each language the site supports. Instead, add all the language text to appear on a single HTML page. Optionally, create a simple language selector dropdown that shows the selected language text to the user.

See an example of how to specify separate maintenance pages for different locales in the `intlbrand` site in the aliases.json code example.

See an example of how to specify the same maintenance page for multiple locales in the `luxbrand` site in the aliases.json code example.

Sharing maintenance pages between Sites

Specify a single maintenance page to be shared by multiple sites, by adding multiple site keys with the same folder value in the aliases.json file.

See an example of how to specify the same maintenance page for multiple domain names in the `kidsshoebrand` and `shoebrand` sites in the aliases.json code example.

Sites Without Configured Custom Pages

Any public name for a site must be configured to use a custom page. Otherwise, the B2C Commerce default maintenance page appears. For example, assume you have a site name of `Sites-mystore-Site` with public names `mystore.com` and `shop.mystore.com`. If `mystore.com` is configured to use a custom page , but `shop.mystore.com` isn't. Any shopper hitting the sites when the maintenance page is enabled, sees the following:

- mystore.com: The custom page.
- shop.mystore.com: The B2C Commerce default maintenance page.

The default maintenance page isn't the page available for sample download, but an internal page that can't be edited.

You can see an example of how to specify the same maintenance page for multiple domain names in the `drankbrand` site in the aliases.json code example. In the example, both the main site and an event branded site name should use the same maintenance page.

Maintenance pages per channel Type

If you want to provide a separate experience for the maintenance page, based on the device or channel type used to access the page, create an index.html that uses responsive design and takes channel type into account.

## Upload

Upload the page as one .zip file that includes the following:

- `index.html` at the top level of the .zip file
- a single folder, containing CSS files or images
- (optional) an `aliases.json` file

Sample structure

```txt
<zip>
	+-- aliases.json
	+-- www.mystore.com
		+-- index.html
		+-- files (folder)
			+-- logo.png
			+-- mystore.css
```

See this structure by downloading the sample file available from the page.

**note:** Don't include operating system files, such as the .DS_store on the mac in your .zip file.

The uploaded .zip file can have any name.

**important:** The zip file name determines which files are affected by publishing the maintenance page. Any sites that aren't included in subsequent uploads are deleted when you publish the pages.

For example, assume you upload and publish `Realm1SiteABC.zip`, containing maintenance pages for site A, B, and C. If you then upload `Realm1SiteABC.zip` again, this time containing maintenance pages for site A and B; the maintenance page for site C is deleted.

However, assume you upload and publish `Realm1SiteABC.zip`, containing maintenance pages for site A, B, and C and then upload and publish `Realm2SiteDEF.zip`, containing maintenance pages for site D, E, and F. In this case, sites A-F have maintenance pages and none are deleted, because the .zip files they were uploaded from have different names.

To upload your file:

1.  Select **Administration** > **Site Development** > **Maintenance Pages**.
2.  On the Custom Maintenance Pages page, in the Upload section, click **Browse**.
3.  Navigate to the .zip file you want to upload.
4.  Click **Upload**.

After you upload successfully, the zip file is automatically extracted and the content is on the web server. If you receive errors when uploading, see the Troubleshooting section in this topic.

## Preview

Preview maintenance pages on Sandbox or Production instances after you have successfully uploaded your template.

1.  Select **Administration** > **Site Development** > **Maintenance Pages**.
2.  On the Custom Maintenance Pages page, click **Preview**.

    The page appears as it appears during site maintenance.

## Publish

Publish maintenance pages on Production instances only. It isn't possible to undo publishing a maintenance page. Salesforce recommends keeping an older version of the page available to publish in case you decide to roll back changes.

**note:** You must publish the maintenance page at least 2 hours before you intend to use it for your site maintenance window.

1.  Select **Administration** > **Site Development** > **Maintenance Pages**.
2.  On the Custom Maintenance Pages page, click **Publish**.

## Troubleshoot

Both warnings and errors can be significant enough to prevent the maintenance page from appearing successfully. Be sure to resolve all warnings or errors. In general, it might be a good idea to run your JSON through a debugger, such as [http://www.jsonlint.com/](http://www.jsonlint.com/).

Usually, the warnings or errors that you receive contain information that you need to resolve the problem.

Cannot resolve URLs

Make sure that the left-hand key values in your alias.json file are present in your hostname and not commented out. The default hostname file for a new instance contains sample information which is entirely commented out.

Bad Alias

If the domain in the hostname alias file and the folder name are identical, you don't have to include a value and key. Including such an entry causes an error. For example, don't create an alias file that looks like the following:

```json
{
  "www.sitegenesis.com": "www.sitegenesis.com"
}
```

Instead, remove the line if it's in a file with multiple lines or don't include the aliases.json file if it's the only line in the file.

## Maintenance Pages for Separate Realms or Sites

Depending on your site architecture and the teams maintaining it, you might need to have multiple administrators uploading maintenance pages for one or more sites.

Maintenance pages are available to the organization as a whole. Any administrator can upload maintenance pages for any site. However, B2C Commerce informs you if you are uploading a duplicate of an existing page. This is true even if you have a different alias assigned to the site in your aliases.json file.

Maintenance Pages and PODs

Maintenance pages are not POD-specific. They are maintained for all PODs. For example, if the maintenance page was first installed here: `http://maintenance.pod29.demandware.net/www.mysite.com/index.html`, but the realm moved PODs, the maintenance page is maintained on the next POD. For example, this would show the same maintenance page as well: `http://maintenance.pod17.demandware.net/www.mysite.com/index.html`.

<!-- document id=06a97f0c578bfeec0fe4eed7d44ce3c32c01054ee6728b028b296a97c3a88d3d url=/developer/current/en-us/commerce-cloud/commerce-api/guides/response-handling.md -->

# Maintenance Response Codes

When your B2C Commerce instance is updated as part of a system deployment, or you set the associated site's Site Status to Maintenance, B2C Commerce API returns a maintenance HTTP response.

## System Maintenance

This includes system-wide updates, such as a B2C Commerce release or database upgrade. This status is typically set by B2C Commerce. For additional information, refer to the [B2C Commerce Deployment Schedule.](https://help.salesforce.com/s/articleView?id=commerce.b2c_deploy_schedule_24.htm&type=5)

Additional HTTP response header:

```text
sfdc_maintenance: system
```

Example of the error response body:

```json
{
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/system-under-maintenance",
  "title": "System Under Maintenance",
  "detail": "The request could not be processed as the system is currently under maintenance."
}
```

## Site Maintenance

When the Site Status of a B2C Commerce Site is set to Maintenance in Business Manager's Manage Sites panel, an HTTP 503 response is returned with an additional HTTP response header:

```text
sfdc_maintenance: site
```

Example of the error response body:

```json
{
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-under-maintenance",
  "title": "Site Under Maintenance",
  "detail": "The request could not be processed as the site is currently under maintenance."
}
```

<!-- document id=0b34c2c910e75ee223f86deb26cb4e1c4e4ee9064bf31c70235fd0d09261607c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_manage_instances.md -->

# Manage B2C Commerce Instances in Control Center

In Control Center, view the status of instances in your organization and perform actions against those instances, provided you have sufficient permissions. When you log in to Control Center, see your organization, your realms, and your instances:

Instance types include:

- **First Party Instance**
  - Primary Instance Group (PIG)–Production, Staging, and Development
  - Secondary Instance Group (SIG)–Sandbox
- **On-Demand Sandbox (ODS)**–Sandbox

When you view a realm, you see the aggregated statuses of the instances contained in the realm.

Search for a specific instance by entering an instance name in the search field.

The following table describes the PIG and SIG statuses shown in Control Center:

| Status                | Description                                                                                                                                                                               | Available actions in Control Center                                  |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| System up and running | The instance is running normally.                                                                                                                                                         | PIG–restart the instance; SIG–restart, stop, or reset the instance   |
| System down           | The instance is down due to a technical problem, not because a user intentionally stopped the instance.                                                                                   | PIG–restart the instance; SIG–start or reset the instance            |
| Administratively down | The instance is down because it was manually stopped by an administrator or by a user with permission to stop the instance. (You can check the audit log to see who stopped an instance.) | PIG–you can start the instance; SIG–start or initialize the instance |
| Starting              | The instance is currently starting.                                                                                                                                                       | PIG–no actions available; SIG–no actions available                   |
| System running Reset  | The instance is in the process of being initialized.                                                                                                                                      | PIG–no actions available; SIG–no actions available                   |
| System running reset  | The instance is in the process of restarting.                                                                                                                                             | PIG–no actions available; SIG–no actions available                   |
| Maintenance           | The label "Maintenance" appears in addition to the instance status when B2C Commerce performs maintenance. No action can be performed by the user during this time.                     | PIG–no actions available; SIG–no actions available                   |

The following table describes the ODS statuses shown in Control Center:

| Status           | Description                                                                           | Available actions in Control Center |
| ---------------- | ------------------------------------------------------------------------------------- | ----------------------------------- |
| Is being deleted | The instance is being deleted. This status is only used with ODS instances.           | ODS–no actions available            |
| Creating         | The ODS instance is being created. This status is only used with SIG ODS instances.   | ODS–no actions available            |
| Stopping         | The ODS instance is being stopped. This status is only used with SIG ODS instances.   | ODS–no actions available            |
| Deleting         | The ODS instance is being Deleted. This status is only used with SIG ODS instances.   | ODS–no actions available            |
| Restarting       | The ODS instance is being Restarted. This status is only used with SIG ODS instances. | ODS–no actions available            |
| New              | The ODS instance is Newly created. This status is only used with SIG ODS instances.   | ODS–start or reset a new instance   |
| Deleted          | The ODS instance is deleted. This status is only used with ODS instances.             | ODS–no actions available            |
| Failed           | The ODS instance failed. This status is only used with ODS instances.                 | ODS–no actions available            |
| Upgrading        | The ODS instance is upgrading. This status is only used with ODS instances.           | ODS–no actions available            |

<!-- document id=b7c373ee6a36e49ff11aac5af8602c471b5cd1ad3b84c7222368cae36d4f0765 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-page-designer-content-blocks.md -->

# Manage Content for Site-Wide Regions in Storefront Next with Content Blocks

Manage content consistently across your entire storefront by creating content blocks in site-wide regions, which include headers, the mega menu, and announcement banners. Instead of recreating content that appears across your entire storefront for each individual page, create the content once and apply it everywhere. Maintain brand consistency and save time when updating promotional messages or navigation elements that appear site-wide. Preview your changes directly from Page Designer without switching user interfaces.

## Enable Site-Wide Regions for Content Blocks

To enable site-wide regions for content blocks, first turn on a feature switch. If you have a version of Storefront Next template that's lower than v1.1, update the Storefront Next template to include new fields generate. Finally, deploy the cartridge containing the Page Designer metadata to your B2C Commerce instance.

### Use New Fields from the Storefront Next Template

The Site-Wide Regions for Content Blocks feature requires [Storefront Next template](https://github.com/SalesforceCommerceCloud/storefront-next-template) v1.1 or later, which includes new fields that this feature uses. If you built your storefront with v1.1 or later of the template, your storefront contains the new fields. Otherwise, add the new fields manually.

The new fields are:

- `embedded`: This field indicates whether the header component can contain a content block.
- `component_id`: This field identifies the header and is required for calling the `getComponent` B2C Commerce API (SCAPI) call to get the embedded content block in a page that's not in Page Designer—a page that's not a product detail or listing, about us, or home page. The get Component API endpoint is: `GET /experience/shopper-experience/v1/organizations/{organizationId}/components/{componentId}`. See [Shopper Experience](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience?meta=Summary) endpoints.
- `@RegionDefinition([ ])`: This decorator enables the addition of a content block inside the header or mega menu.

If you built with a version prior to v1.1 of [Storefront Next template](https://github.com/SalesforceCommerceCloud/storefront-next-template), add the new fields manually to the storefront.

1. In `/src/components/header/index.tsx`, add the `embedded` and `component_id` field to the header and megaMenu components. Also, add the `@RegionDefinition` decorators below the components, as follows.

   ```tsx
   @Component('header', {
       name: 'Header',
       group: 'Layout',
       description: 'Global site header with navigation, search, and cart',
       embedded: true,
       component_id: 'header',
   })
   @RegionDefinition([{ id: 'announcement', name: 'Announcement' }])

   @Component('megaMenu', {
    name: 'Mega Menu',
    group: 'Layout',
    description: 'Site-wide mega menu with per-category dropdown panel content slots',
    embedded: true,
    component_id: 'mega-menu',
    })
    @RegionDefinition([
        // One region per top-level category, keyed by category id via the `region_<id>` convention.
        // Edit this list to match your catalog's top-level category ids. Must stay an array literal —
        // the cartridge generator extracts regions via AST and only handles array-literal arguments.
        { id: 'region_women', name: 'Women' },
        { id: 'region_men', name: 'Men' },
        { id: 'region_kids', name: 'Kids' },
    ])
   ```

2. After you add the new fields, generate the cartridge for the Page Designer metadata. See [Generate Cartridges](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer.md#generate-cartridges).

3. Deploy the cartridge to your B2C Commerce instance. See [Deploy Cartridges](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer.md#deploy-cartridges).

## Add a Content Block in a Site-Wide Region

Add a content block to site-wide regions in the Content Block Editor. Site-wide regions include the header, the mega menu, and the announcement banner. To create a content block and assign it to a site-wide region:

1. In Business Manager, click App Launcher and then select **Merchant Tools > Your Site > Content > Content Blocks**.
2. Click **New** to create a content block, and specify a name for the content block.
3. Select the type of content to include and then click **Create**.
4. Set the content block properties, and then click **Apply**.
5. Click **Settings**, and then click **Add Site-Wide Region** to assign the content block to a site-wide region, such as a header, a mega menu, or an announcement banner. Based on the component type, you see which site-wide regions are available for assignment.
   The content block is now saved and assigned to a site-wide region. If you view the affected page in Page Designer, it shows the content block that you added to the site-wide region embedded in the page's component.

This example shows a content block for an announcement banner. It contains the **Add Site-Wide Region** button that provides the site-wide region locations where to place the content block.

![Content block contains the Set Site-Wide Region button that places it in a site-wide region](https://developer.salesforce.com/docs/media/sfnext/sfnext-pd-cblock-settings_annotated2.png '{"class": "image-md"}')

The example announcement banner is added to the header. After selecting a site-wide region of "Header – Announcement" for the content block, the announcement banner component is added in the header for all pages.

![The announcement banner component is now added in the header for all pages](https://developer.salesforce.com/docs/media/sfnext/sfnext-pd-cblock-banner-result2.png '{"class": "image-xl"}')

**See Also**

- [Salesforce Help: Page Designer Content Blocks](https://help.salesforce.com/s/articleView?id=cc.b2c_content_blocks.htm&type=5)

<!-- document id=6a2eadb014f5fc584d9e9850f0ad70434fa1030a17fd90184232a2ec63993871 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/manage-orders-with-spis.md -->

# Manage Orders with Point of Sale SPIs

Configure Point of Sale SPIs to manage orders when an external order management system isn't available. Improve order processing and management capabilities. Gain the benefits of a robust order management system directly within Point of Sale. Efficiently handle order workflows, track order status, and streamline fulfillment processes.

## Configure SPIs

Create and configure two SPIs in CMS: Search Order and Order Details.

![The CMS shows details of two SPI configurations.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-process-spi-order-master-config.png)

### Search Order SPI

1.  In CMS, go to **Integrations** | **Custom Connectors**.

2.  Click **Create**.

3.  For Connector Type, select **SPI**.

4.  For Endpoint Name, select **SEARCH_ORDER**.

5.  Configure the rest of the fields by referring to [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

6.  Save your changes.

### Order Details SPI

1.  In CMS, go to **Integrations** | **Custom Connectors**.

2.  Click **Create**.

3.  For Connector Type, select **SPI**.

4.  For Endpoint Name, select **GET_ORDER_DETAIL**.

5.  Configure the rest of the fields by referring to [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

6.  Save your changes.

## Enhanced Search Functionality

Turn on the updated order search service (orderSearchV2) in CMS to leverage Point of Sale latest order search capabilities. The sequence of these calls begins with populating the order history section in the customer profile using the Order Search API. If the SEARCH_ORDER SPI is configured and orderSearchV2 is enabled, the customer's orders are retrieved from an external system and displayed in this section.

**important:** The SPIs must be configured.

1.  In CMS, go to **Store Management** | **Store Settings** | **System**.

2.  Expand **Rollout**.

3.  Turn on the setting "Use new order search service (useOrderSearchV2)."
    ![The CMS shows the use new order search service flag.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-orders-process-spi-order-master-search.png)

## Known Issues & Restrictions

**Status & Returns**

Point of Sale enforces a check that prevents orders from being returned unless they have a status of Completed, Exchanged, Partially Exchanged, Fulfilled, or Partially Refunded. Orders with a status of, for example, Shipped can't be returned.

<!-- document id=aaeb8695d333d8f3d314e0fe7a892090211029c7a32c085ee51301089fd135fd url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-users.md -->

# Manage Roles and Permissions for Your Storefront in Business Manager (Beta)

With storefront-scoped permissions in Business Manager, specify the access for each role on one storefront, separate from other storefronts. For example, a developer for one brand manages environments for that brand's storefront only. Each role is a named set of permissions that you assign to one or more users.

**important:** Developer Workspace is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

## Prerequisites

- The Business Manager Administrator role.

## Set Business Manager Permissions

Set storefront permissions for an existing or a new role in **Administration > Organization > Roles > _Role Name_**, and then click **Storefronts**. Select one or more storefronts, and then assign the permissions. A permission grid shows the capabilities for that role and those storefronts, and the Read, Write, and Delete state for each capability. Apply **Read**, **Write**, and **Delete** for one storefront, or apply the same permissions to all storefronts.

See [Roles and Permissions in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_roles_and_permissions.htm&type=5) in _Salesforce Help_.

The Administrator role has full access to all storefronts. Its permissions are fixed and can't be changed from this page.

### Global

| Capability | Description                                 | Permissions                                                                                        |
| ---------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Storefront | Access this storefront in Business Manager. | Read: View the storefront. Write: Create and update the storefront. Delete: Delete the storefront. |

### Runtime and Configuration

| Capability                       | Description                                                             | Permissions                                                                                                             |
| -------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Storefront Environments          | Create and manage the Managed Runtime environments for this storefront. | Read: View environments. Write: Create, configure, set as primary, and clone environments. Delete: Delete environments. |
| Storefront Environment Variables | Create and manage environment variables for the deployed storefronts.   | Read: View environment variables. Write: Edit and delete environment variables. Delete: Delete environment variables.   |

### Deployment and Delivery

| Capability               | Description                                                                            | Permissions                                                                                             |
| ------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Storefront Deployments   | Upload, manage, and deploy Managed Runtime bundles for this storefront's environments. | Read: View deployments and download the deployed bundle. Write: Deploy bundles. Delete: Delete bundles. |
| Storefront URL Redirects | Manage URL redirects served from Managed Runtime.                                      | Read: View redirects. Write: Create and edit redirects. Delete: Delete redirects.                       |

### Admin and API Interface

| Capability        | Description                                                                                                                                                                                                               | Permissions                                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| UI and API Access | Select the user interface and the API for the storefront. This permission sets the admin interface that users in the role use (Business Manager or Runtime Admin) and the Storefront APIs (SCAPI, SCAPI and MRT, or MRT). | Read: View admin user interface and API configurations. Write: Assign and change admin user interface and API configurations. |

## How Business Manager Permissions Differ from Runtime Admin

In Managed Runtime, users log in to Runtime Admin through Account Manager, and Account Manager grants one of the predefined roles. See [Users, Abilities, and Roles](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#users-abilities-and-roles) in the Composable Storefront guide. In the Developer Workspace beta, users log in to Business Manager. You assign storefront permissions through a role for that Business Manager instance.

|                      | Managed Runtime                                                  | Developer Workspace                                                                                                                                                                                                               |
| :------------------- | :--------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Admin interface      | [Runtime Admin](https://runtime.commercecloud.com)               | Business Manager, on the B2C Commerce instance                                                                                                                                                                                    |
| Account Manager role | Managed Runtime User or Managed Runtime Administrator            | Business Manager User or Business Manager Administrator                                                                                                                                                                           |
| Permission model     | Predefined project roles: Admin, Developer, Marketer, and Viewer | Custom Business Manager roles built from storefront permissions                                                                                                                                                                   |
| Scope                | Per project                                                      | Per one or more storefronts on a single B2C Commerce instance. Because roles are instance-specific, assign the role in every B2C Commerce instance where the user works, and then recreate or import the role into each instance. |

## Permission Considerations for the Developer Workspace Migration

These considerations apply when you migrate from Runtime Admin to the Developer Workspace beta in Business Manager.

- Each Managed Runtime project corresponds to one storefront in Business Manager. The permissions that a user has for a project become the permissions that you grant on the corresponding storefront.
- Recreate each Managed Runtime role in Business Manager, and grant Business Manager access. The roles don't transfer automatically.
- During the Developer Workspace beta, grant each user a Managed Runtime project role in addition to the Business Manager permissions.

## Before You Begin

Before you can grant Business Manager and Managed Runtime permissions to users, you must have these permissions.

- **Account Manager:** The **User Administrator** or **Account Administrator** role, to add Business Manager access for your users.
- **Business Manager:** The **Administrator** role, or a role with access to the **Roles & Permissions** and **Users** modules on the B2C Commerce instance where you set up storefront roles.

After you turn on Developer Workspace for the B2C Commerce instance, the **Storefronts** tab appears on the **Administration > Organization > Roles & Permissions** page in Business Manager. If the **Storefronts** tab doesn't appear, confirm that Developer Workspace is turned on for the instance.

## Step 1: Give Users Business Manager Access

Grant each Managed Runtime user access to Business Manager for the B2C Commerce instance. Use Account Manager.

1. Log in to Account Manager at [https://account.demandware.com](https://account.demandware.com).
2. Select **User** and open the user's account, or add a new user.
3. In the **Roles** section, add the **Business Manager User** role. To give a user full Business Manager control of the storefront, assign **Business Manager Administrator** instead of **Business Manager User**.
4. Click the filter icon next to the role, and then select **Add Instance Filters**. Select the organization and the instances (for example, development, staging, and production) where the user works.
5. Click **Add**, and then save the user.

**note:** The **Business Manager User** role lets a user log in to the instance. It doesn't grant storefront permissions in Business Manager. You assign the storefront role separately in [Step 2: Create Storefront Roles in Business Manager](#step-2-add-storefront-permissions-in-business-manager).

**note:** Keep the user's **Managed Runtime User** or **Managed Runtime Administrator** role during the transition. During the beta, storefront operations require this role. Runtime Admin stays available until end of life.

## Step 2: Add Storefront Permissions in Business Manager

Create a role for each set of storefront permissions, and then assign it to users. Repeat for each role. For example, use a role for each user group: admin, developer, marketer, and viewer.

1. In Business Manager, select **Administration > Organization > Roles & Permissions**.
2. Click **New**, enter a name for the role (for example, `Storefront Developer`), and then click **Apply**.
3. Set Business Manager module permissions. Click **Business Manager Module**, and then set the **Storefronts** module to **Read** or **Write** so that a user in that role opens the Storefronts section. Use **Write** for roles that edit the storefront, and select **Read** for view-only roles.
4. Set storefront permissions. Click **Storefronts**, and then click **Select Storefront**.
   - Select the storefronts that this role applies to: one storefront, a subset of storefronts, or all storefronts.
   - For each permission, select the level for the role: **Read** for view-only, **Write** to manage, or **Delete** for full control, including deletion.
5. Click **Update**.
6. On the **Users** tab, select the users to assign to this role, and then click **Assign**.

**note:** The Storefronts module permission shows **Sites > Storefronts** in the Business Manager navigation. Grant this permission to every Developer Workspace user. The **Sites** menu group appears after the user has the Storefronts permission.

## Recommended Business Manager Storefront Roles

Check out these role recommendations to create roles in Business Manager that map the Managed Runtime roles.

| Permission                       | Storefront Admin | Storefront Developer | Storefront Marketer | Storefront Viewer |
| :------------------------------- | :--------------- | :------------------- | :------------------ | :---------------- |
| Storefront                       | Delete           | Read                 | Read                | Read              |
| Storefront Environments          | Delete           | Write                | Read                | Read              |
| Storefront Environment Variables | Delete           | Write                | No access           | No access         |
| Storefront Deployments           | Delete           | Write                | Read                | Read              |
| Storefront URL Redirects         | Delete           | Write                | Write               | Read              |
| UI and API Access                | Write            | No access            | No access           | No access         |

## See Also

- [Salesforce Help: Account Manager Overview](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_overview.htm)
- [Salesforce Help: Account Manager Roles](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_roles.htm)
- [Salesforce Help: Create a User in Account Manager](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_create_user.htm)
- [Salesforce Help: Roles and Permissions in Business Manager](https://help.salesforce.com/s/articleView?id=cc.b2c_roles_and_permissions.htm)
- [Salesforce Help: Create a Role in Business Manager](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_roles.htm)
- [Link an Existing Storefront to B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-link-storefront.md)

<!-- document id=f613de68bf347b955833e2035b95d835b65ebdbecc2b0d0e69617cb9fd684b17 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/sandboxes/b2c-manage-sandboxes-from-control-center.md -->

# Manage Sandboxes from Control Center

To learn how to use Control Center to view the status of instances in your organization, and to perform appropriate action on those instances, see [Control Center](https://help.salesforce.com/s/articleView?id=cc.b2c_cc_manage_instances.htm&type=5).

<!-- document id=a6808682874f84e19a284d77d140ce7048e212d2b7a1fd3e89572c1a8ac4661c url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-shopper-identity-section.md -->

# Manage Shopper Identity

Configure how shoppers log in, register, and maintain their sessions in Storefront Next. This section covers standard login and registration, passwordless and social login options, email verification and password reset flows, and session continuity across subdomains.

In this section:

- [Login and Registration Support](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-login-support.md)
- [Passwordless Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passwordless-login.md)
- [Social Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-social-login.md)
- [Email Verification for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-email-verification.md)
- [Password Reset for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-password-reset.md)
- [Maintain Shopper Sessions Across Subdomains in Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-domain-cookie.md)

<!-- document id=f4ee6dc94baee0cb0caf9b1059fcf1fb1e8715d18475a263daef564faaf8e078 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-tracking-preferences.md -->

# Manage Shopper Tracking Preferences

In compliance with Salesforce’s core value of trust and respecting user privacy, the B2C Commerce platform offers a comprehensive mechanism for shoppers to control tracking preferences. Our Do Not Track (DNT) support provides compliance with local laws while giving shoppers control over how their data is used. Developers can seamlessly incorporate tracking preferences into their applications and respect shoppers’ choices.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


With SCAPI, when you get a SLAS token using [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken), you specify a tracking preference. The tracking preference is respected for all requests using that token.

## User Activity Tracking

When you get an access token for a shopper, provide the query parameter `dnt=true` to disable tracking. When a shopper opts out of tracking, the shopper's activity is no longer utilized to enhance strategy recommendations, and analytics tracking is disabled for services such as recently viewed and real-time personalized recommendations. For additional details, refer to B2C Commerce [Do Not Track Impact](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_dnt_feature_impact.htm&type=5) and [Set Privacy Preferences for B2C Commerce.](https://help.salesforce.com/s/articleView?id=cc.b2c_setting_privacy_preferences.htm&type=5)

SCAPI provides the following capabilities for managing user tracking preferences:

- SLAS JWTs include the DNT claim, which, by default, is set to:
  - 0 (tracking is enabled) for all requests except Trusted Agent on Behalf (TAOB). When `dnt=false` is provided, then the JWT contains the claim `dnt:0`.
  - 1 (tracking is disabled) for TAOB requests. When `dnt=true` is provided, then the JWT contains the claim `dnt:1`.
- SCAPI responses include a DNT HTTP response header reflecting the shopper's preference that was passed: `dnt:1` (disable tracking) or `dnt:0` (enable tracking).
- Tracking preferences are stored, so refreshing returns the same information unless you change the preference.
- If a shopper changes their tracking preference, use their refresh token to request a new token, and pass the new preference.
- For hooks and custom APIs, use session.isTrackingAllowed() to respect shoppers’ tracking preferences. For details, see the [B2C Commerce Script API Documentation.](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/scriptapi/html/api/class_dw_system_Session.html#dw_system_Session_isTrackingAllowed_DetailAnchor)

**note:** Allow tracking by default to maximize the quality of CommerceCloud report data. When tracking is disabled, personal identifiable information (PII) is stripped from collected data, which removes those records from appearing in select reports and dashboards.

## Set DNT Preference

To opt out of tracking, provide `dnt=true`:

```bash
RESPONSE=$(
    curl "$BASE_AUTH/oauth2/token" \
        -sS --fail-with-body \
        -u "$CLIENT:$SECRET" \
        -d "dnt=true" \
        -d "channel_id=$SITE" \
        -d 'grant_type=client_credentials'
)
TOKEN=$(echo $RESPONSE | jq -r '.access_token')

# DNT preference is included in the JWT:
echo $TOKEN | jq -rR 'split(".") | .[1] | @base64d | fromjson | {dnt}'
REFRESH=$(echo $RESPONSE | jq -r '.refresh_token')

# DNT preferences are stored, so using the refresh token without providing
# a new preference returns whatever was previously chosen:
RESPONSE=$(
    curl "$BASE_AUTH/oauth2/token" \
        -sS --fail-with-body \
        -u "$CLIENT:$SECRET" \
        -d 'grant_type=refresh_token' \
        -d "refresh_token=$REFRESH"
)
TOKEN=$(echo $RESPONSE | jq -r '.access_token')
echo $TOKEN | jq -rR 'split(".") | .[1] | @base64d | fromjson | {dnt}'
```

## Integrate with Custom APIs

With custom APIs and hooks, use an external tracking service for orders and pass DNT preferences:

- Use session.isTrackingAllowed().
- Make sure that the DNT setting is passed on to third-party integrations or analytics components when making calls.

```javascript
// dw.ocapi.shop.order.afterPOST
exports.afterPOST = function (order) {
  if (session.isTrackingAllowed()) {
    sendAnalyticsToExternalTrackingService();
  }
};
```

```text
window.addEventListener('load', function() {
	const accessToken = getAccessToken();
	const isTrackingAllowed = getTrackingFromAccessToken(accessToken);

	if (isTrackingAllowed) {
		const currentPageUrl = window.location.href;
		trackPageView(currentPageUrl);
	}
});
```

## Additional Notes

- B2C Commerce [Privacy settings](https://help.salesforce.com/s/articleView?id=cc.b2c_setting_privacy_preferences.htm&type=5) only impact controller behavior, not SCAPI behavior.
- You can use Business Manager to change the default tracking behavior in [Controllers.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-working-with-controllers.html?q=controllers) For additional details, refer to B2C Commerce [Do Not Track Impact](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_dnt_feature_impact.htm&type=5) and [Set Privacy Preferences for B2C Commerce.](https://help.salesforce.com/s/articleView?id=cc.b2c_setting_privacy_preferences.htm&type=5)

<!-- document id=f99393e86ae38da42594cd3e0da610bbb8ac848a3c03af7c1457d46ebe50a03c url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-manage-sites.md -->

# Manage Sites for Storefront Next in Business Manager

Change the sites assigned to a provisioned storefront after Storefront Next is set up in Business Manager. Add sites for new locales, brands, or markets, or remove sites you no longer need. Site changes propagate to Shopper Login and API Access Service (SLAS) for authentication to B2C Commerce API (SCAPI), and to Managed Runtime (MRT) for environment variable updates. Site management provides a straightforward way to evolve your storefront's site list while keeping all other setup configurations intact. Starting in Storefront Next 1.2, site assignments in the storefront detail page in Business Manager are synchronized live to the storefront from the [MRT Data Store](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-data-store.md) without requiring configuration changes in `config.server.ts`. Before Storefront Next 1.2, the storefront accessed sites in `commerce.sites`, which the MRT Data Store replaces for site assignment retrieval.

For more information, see [MRT Data Store Sites]() in [Configure Multisite URLs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-multi-site.md).

## Prerequisites

- Use or upgrade to [storefront-next-template](https://github.com/SalesforceCommerceCloud/storefront-next-template) version 1.2 or later.

## Assign or Remove Sites from a Storefront

After storefront setup completes in Business Manager, change the sites assigned to the storefront.

1. In **Administration > Sites > Storefronts**, click **_Storefront Name_**.
2. In the storefront detail page, click **Manage Sites**.

   ![Manage sites modal for changing site assignments for the storefront](https://developer.salesforce.com/docs/media/sfnext/manage-sites.png '{"class": "image-lg"}')

3. In Manage Sites, perform these tasks.

   a. To assign a storefront, select it.

   A site that's already assigned to a storefront is greyed out because it can't be reused for another storefront.

   b. To remove a site assignment from the storefront, deselect it.

   You can only delete site assignments if there are more than one site assigned to the storefront.

   c. Save your changes.

The new site assignments take effect in the storefront deployment on MRT immediately without any setup required.

## Assign or Remove Sites from a Storefront in the Developer Workspace (Beta)

If your B2C org is enrolled in the Developer Workspace beta, change storefront site assignments in storefront settings.

1. In **Administration > Sites > Storefronts**, click **_Storefront Name_**.
2. In the storefront detail page, click **Storefront Settings**.
3. In the Associated Sites section, click **Assign**.

   ![Assign sites section for changing site assignments for the storefront](https://developer.salesforce.com/docs/media/sfnext/sfnext-storefront-sites.png '{"class": "image-lg"}')

   a. To assign a storefront, select it.

   A site that's already assigned to a storefront is greyed out because it can't be reused for another storefront.

   b. To remove a site assignment from the storefront, deselect it.

   You can only delete site assignments if there are more than one site assigned to the storefront.

   c. Save your changes.

The new site assignments take effect in the storefront deployment on MRT immediately without any setup required.

<!-- document id=38f3038b1bd557de57ca7e90b4c13b99b4b506a182c9b41d5953026c64f9349d url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-developer-workspace.md -->

# Manage the Storefront Development Workflow in Business Manager (Beta)

Manage storefronts in one place with the Developer Workspace beta. Handle storefront environments, environment variables, redirects, and bundle deployments from the storefront's page in Business Manager. Manage these Managed Runtime resources in Business Manager instead of Runtime Admin as part of the storefront development lifecycle. Monitor the performance of staging and production environments for real-world usage, including Core Web Vitals. Admins assign read, write, and delete permissions for each storefront's resources, such as environments, environment variables, deployments, and redirects. On the Management Interface page, admins select the user interface and the API for that storefront. Admins select the legacy Runtime Admin interface or the new Business Manager interface.

**important:** Developer Workspace is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

## Manage Environments from the Storefront

View the environments for your storefront in **Administration > Sites > Storefronts > _Your Storefront_**. Create, update, and delete environments in your B2C Commerce instance. Update settings for each environment. View and manage environment variables for your deployed storefronts.

![Storefront detail page showing available environments](https://developer.salesforce.com/docs/media/sfnext/sfnext-storefront-overview-tab.png '{"class": "image-xl"}')

## Manage Deployments

View uploaded bundles in the storefront's **Bundles** tab, start deployments, track deployment progress, and review deployment history.

![Bundles tab for a storefront](https://developer.salesforce.com/docs/media/sfnext/sfnext-bundles.png '{"class": "image-xl"}')

## Monitor Storefront Performance

For an environment that's marked as production, analyze Core Web Vitals and identify bottlenecks and ways to improve storefront performance. To view performance metrics, add a zone and a hostname. See [Production Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md#production-environments).

![Monitoring tab for a storefront environment](https://developer.salesforce.com/docs/media/sfnext/sfnext-monitoring-tab.png '{"class": "image-xl"}')

## User Roles and Permissions

In Business Manager, go to **Administration > Organization > Roles & Permissions** and set permissions for a role and one or more storefronts. These permissions specify the actions that a role can take. Permissions apply to environments, environment variables, bundle deployments, URL redirects, and UI and API selection.

![Storefront roles and permissions](https://developer.salesforce.com/docs/media/sfnext/sfnext-roles-perms.png '{"class": "image-xl"}')

## Access to Runtime Admin

During the beta, Developer Workspace in Business Manager and Runtime Admin are both available. Use either interface to manage storefront operations, such as environments and deployments. Runtime Admin will be deprecated in a future release.

## See Also

- [Migrate to the Storefront Developer Workspace (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-migration.md)
- [Manage Roles and Permissions for Your Storefront in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-users.md)
- [Manage Your Environments in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-environments.md)
- [Deploy Your Storefront from Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-deployments.md)

<!-- document id=fd64d4769cdd22d28939095fac33ac7c43299426d25a5baf65eac498b37c4443 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-environments.md -->

# Manage Your Environments in Business Manager (Beta)

Managed Runtime environments are isolated deployments of your Storefront Next app. Use an environment while you develop your storefront. Test your app in a development environment, host the storefront in a staging environment after you test it, and move it to production when you release it. Each environment has its own URL, bundle deployment, environment variables, and eCDN configuration. Manage environments in Business Manager from the **Storefronts** page for your storefront.

**important:** Developer Workspace is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

Every storefront has one primary environment and can have additional environments for development, staging, or other purposes.

## Prerequisites

- To manage an environment, you must have the "Storefront Environments" Business Manager permission for a specific storefront with appropriate read, write, and delete rights.
- To manage URL redirects, you must have the "Storefront URL Redirects" Business Manager permission for a specific storefront with appropriate read, write, and delete rights.

## Primary Environment

The primary environment is the default environment for your storefront. Use it as the target for:

- Page Designer: Content previews and layout editing.
- Environments list: The first environment shown for your storefront.
- Storefront Preview: Live preview in the Storefront Toolkit.

### Change the Primary Environment

Change the primary environment at any time from **Storefront Settings**. The change doesn't affect your storefront or active deployments.

1. In Business Manager, go to **Administration > Storefronts > _Your Storefront_**.
2. Click **Storefront Settings**.
3. Under **Primary Environment**, select the environment to set as primary.

The primary environment change takes effect immediately.

**note:** You can't delete the primary environment while it is set as primary. Before deleting it, set a different environment as primary from **Storefront Settings**.

## Create Environments

Create additional environments for development, testing, staging, or other deployment workflows alongside your primary environment. Each environment has the same capabilities as the primary environment: bundle deployments, environment variables, eCDN zones, and routing rules.

To create an environment:

1. In Business Manager, go to **Administration > Storefronts > _Your Storefront_**.
2. Click **Storefront Settings**.
3. Click **Environments**, and then click **Create**.
4. Enter a name.

Environment creation can take up to 30 minutes. Business Manager sends an email when the environment is ready.

## Clone or Delete an Environment

A clone copies an existing environment's name and, optionally, its redirects and environment variables. A clone doesn't copy the production status. Deleting an environment removes all related resources and system configurations from Managed Runtime. You can't undo this action. Clone or delete an environment from the **Environments** page.

## Edit Environment Settings

Edit environment settings, including production settings, deployment settings such as the deployment region, and logging settings. Rename an environment from the same page.

1. In Business Manager, go to **Administration > Storefronts > _Your Storefront_**.
2. Under Primary or Additional Environments, next to the environment, open the dropdown menu, and then select **Environment Settings**.
3. Click **Edit** next to the setting section, and then modify the setting.
4. Save your changes.

## Environment Constraints

- Each storefront has a limit on the number of environments. When you reach the limit, you must delete an existing environment before creating a new one. To request a higher limit, contact [Salesforce Customer Support](https://help.salesforce.com).
- For environments not created in Business Manager, they only respond to requests whose HTTP `Host` header matches their External Hostname set in Runtime Admin. For environments created in Business Manager, which have eCDN default domains, the host header is automatically set.
- The path `/` only accepts HTTP GET requests.
- Request and response size can’t exceed 6 MB.
- The maximum size of the HTTP request line and headers is 10,240 bytes. Requests exceeding this size return an [HTTP 413 Content Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413).
  - Of the 10,240 bytes, 1,500 bytes are reserved for internal use, 1,800 bytes for authorization headers, and 1,000 bytes for Salesforce B2C Commerce API (SCAPI). 5,940 bytes are left for custom request headers, including cookies.
- Requests with headers that start with `_` aren’t supported. These requests are dropped.
- HTTP requests originating from Managed Runtime environments don't use fixed IP addresses. To allowlist requests from the app server, use the [AWS IP Range](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html) for `EC2`.
- The path prefix `/mobify` is reserved for managed endpoints. These endpoints include:
  - `/mobify/ping`: Returns an HTTP 200 response code when the environment is operating correctly.
  - `/mobify/redirect/$path`: Returns a similar response as [projects_target_redirect_retrieve](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_retrieve).
- Storefront Next preconfigures access control headers for the default domain. For vanity domains, configure them manually. For more information, see [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#access-control-headers) in the _Composable Storefront Guide_. Storefront Next environments support up to 4 access control headers. Each header:
  - Can contain up to 128 characters.
  - Can be a combination of alphanumeric characters and - and \_ characters.

## Access Control Headers

Access control headers limit incoming traffic to trusted sources, such as a CDN or your development team. An environment that has access control headers accepts only requests that include the `x-sfdc-access-control` HTTP header with a valid value. This blocks bots that bypass CDN security, and it blocks search crawlers from indexing non-production environments.

In Storefront Next, access control headers are read-only in Business Manager. View the headers for an environment in Business Manager. Add or remove them with the Managed Runtime API.

**note:** Server-side code in the environment can't read access control header values. The infrastructure layer enforces the headers before requests reach your storefront.

### Header Value Requirements

Each access control header value meets these requirements:

- **Minimum length:** 9 characters
- **Maximum length:** 128 characters
- **Allowed characters:** alphanumeric characters, hyphens, and underscores

Storefront Next environments support up to four access control header values. Use multiple values to rotate headers without downtime.

### Rotate Headers

To rotate an access control header value without downtime:

1. Add the new header value with the Managed Runtime API.
2. Wait for the deployment to complete.
3. Update your CDN or proxy to send the new header value.
4. Verify that the environment accepts requests with the new value.
5. Remove the old header value with the Managed Runtime API.

See [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#access-control-headers) in the Managed Runtime Administration guide.

## Server-Side Cookies

Storefront Next enables server-side cookies. You can't configure them. Storefront Next uses `HttpOnly` cookies for all authentication tokens. See [Cookie Architecture](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-storage-sessions.html#cookie-architecture).

## Source Maps

Production builds generate source maps by default with Vite's `build.sourcemap` option. Source maps connect minified code to your original source files, so stack traces stay readable when errors occur.

Storefront Next environments turn on source maps by default. If the setting is off, turn it on in Business Manager:

1. Go to **Administration > Storefronts > _Your Storefront_**.
2. From the dropdown menu next to an environment, select **Environment Settings**.
3. Click **Edit**, and then turn on **Source Maps**.

**note:** When you turn on source maps, the MRT server starts with the Node.js `--enable-source-maps` flag. This flag can affect performance.

Set up source map generation in `vite.config.ts`. See [Source Maps](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-build-tools.html#source-maps).

## Environment Variables

Environment variables are key-value pairs stored outside your application code that configure your storefront's runtime behavior per environment. Use them to supply secrets, API endpoints, feature flags, and other settings that differ between development, staging, and production without changing your codebase.

For more information, see [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md).

## URL Redirects

URL redirects forward site visitors and search engines from an old URL to a new URL. Use redirects to preserve SEO rankings and to maintain the shopper experience during storefront changes such as campaign transitions, URL restructuring, or content moves.

**warning:** Redirects can have significant security consequences if misconfigured. Avoid redirecting to untrusted external URLs.

Redirects are configured per environment. Each environment maintains its own set of redirects independently.

### Manage URL Redirects

1. In Business Manager, go to **Merchant Tools > Storefronts > _Your Storefront_**.
2. From the dropdown menu next to an environment, select **Environment Settings**.
3. Click **URL Redirects**.

### Create a Redirect

**tip:** Before creating a redirect in a production environment, we recommend that you create it and test it in a staging environment. Then clone it to production.

1. On the **URL Redirects** tab, click **New**.
2. In the **From** field, enter the relative path to redirect from (for example, `/winter`). Use `*` at the end of the path to match all paths with that prefix.
3. In the **To** field, enter the destination path or full URL.
4. Select the HTTP status code: **301** for a permanent redirect or **302** for a temporary redirect.
5. Optionally enable forwarding rules:
   - **Forward Query Parameters**: Includes query parameters from the source URL in the redirect.
   - **Forward Wildcard**: Appends the matched path segment to the destination URL when using a wildcard source path.
6. Click **Save**.

New redirects have a **Publishing** status while they propagate. After a redirect is active, the status changes to **Active**.

Create one or more redirects with the [projects_target_redirect_create](/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_create) API endpoint.

#### Paths

The value that you enter in the **Redirect From** field is always a **relative** path. The **Redirect To** field is a relative path or a full URL. For example, to redirect visitors from `www.example.com/spring` to `www.example.com/summer`, enter `/spring` in **Redirect From**. Enter `/summer` or `www.example.com/summer` in **Redirect To**.

#### Wildcards

Add an asterisk (`*`) to the end of the **Redirect From** URL to indicate a wildcard. A wildcard matches zero or more characters in the URL. For example, a redirect from `/a/*` matches `/a/`, `/a/b`, and `/a/b/c`.

Use a wildcard only at the end of the **Redirect From** URL.

Standard redirects are processed first by Managed Runtime, followed by redirects with wildcards.

#### HTTP Status Codes

Most redirects use the Permanent 301 status code. Select Temporary 302 for a temporary redirect. If you aren't sure which HTTP status code to use, see this [status code explainer](https://moz.com/learn/seo/redirection) from Moz.

#### Forwarding Query Parameters

Some requests contain query string parameters to include in the redirected request. For example, append a query string for analytics tracking to `/spring-landing-page`, such as `/spring-landing-page?gclid=123`.

To turn on query parameter forwarding, go to the **Forward** section of the form, and then select **Query Parameters**. Otherwise, the redirect URL omits query string parameters from the source URL.

When **Redirect From** and **Redirect To** both include query strings and forwarding is on, the redirect URL combines the two query strings. Managed Runtime appends the query parameters from **Redirect To** to the query string in the request. For example, the app receives a request for `/spring?year=2019`. If you redirect `/spring` to `/summer?year=2020` and forwarding is on, the redirect URL is `/summer?year=2019&year=2020`.

#### Forwarding Wildcard Path

You can automatically include any path that comes after the wildcard portion of the **Redirect From** URL in the **Redirect To** URL. For example: if `/a/*` matches `/a/b/c` in the **Redirect From** URL, and the **Redirect To** URL is `/z/`, the redirect URL is `/z/b/c`.

To enable wildcard path forwarding, go to the **Forward** section of the form and select **Wildcard Path**.

**warning:** When you clone redirects, you’re replacing _all_ the redirects in the destination environment with _all_ the redirects from the source environment.

### Edit, Delete, or Clone Redirects to Another Environment

Edits and deletes are only available while a redirect has **Active** status. Cloning copies all redirects from one environment to another. Cloning useful when promoting a set of redirects from staging to production.

**warning:** Cloning replaces all existing redirects in the destination environment with the redirects from the source environment.

### Troubleshooting Redirects

If a redirect doesn't work as expected, try these steps:

- [Clear your browser cache](https://support.google.com/accounts/answer/32050) because redirects are cached.
- Verify that you're viewing the settings for the correct environment.
- Edit the redirect and verify that you entered the correct values in the **Redirect From** and **Redirect To** fields.

### Technical Limitations with Redirects

Redirects have these technical limitations:

- Each environment supports up to 10,000 redirects. To request a higher limit, contact [Salesforce Customer Support](https://help.salesforce.com/s/).
- Each environment has its own redirects. Clone redirects to keep them in sync across environments.
- The redirects feature supports simple redirects from one path to another. For complex redirects with conditionals, use Express.js's [redirect support](http://expressjs.com/en/api.html#res.redirect) in `ssr.js`.
- Local development environments don't run redirects that you create in the UI or the API.
- Page transitions in the Storefront Next app don't trigger redirects. Only an HTTP request triggers a redirect.
- To load a redirect in the context of a storefront, use the managed endpoint `/mobify/redirect/$path`.

<!-- document id=4aca7af87c504c5bdf14e3cf860d38e8e6e09147e58fabb12dafe34e1b6914ab url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-data-store.md -->

# Managed Runtime (MRT) Data Store

The MRT data store stores B2C Commerce settings, such as site preferences and Page Designer changes, and makes those settings available to Storefront Next. Your Storefront Next app accesses settings from the data store, which makes settings retrieval faster and more performant because there is no need for B2C Commerce API (SCAPI) calls to get those settings. Also, page descriptions for changed Page Designer pages are stored in the data store where the storefront gets them, eliminating the need to build page layouts for each shopper request.

In this section:

- [Access Site Preferences from the MRT Data Store](#access-site-preferences-from-the-mrt-data-store)
- [Page Designer Change Deployment to Storefront Next](#page-designer-change-deployment-to-storefront-next)

## Access Site Preferences from the MRT Data Store

Use the Managed Runtime (MRT) data store to get site preferences that administrators set in Business Manager. Access site preferences in different contexts within your Storefront Next app.

**important:** Sensitive values, such as passwords, are masked when stored in the MRT Data Store. When you retrieve sensitive values in the Storefront Next app, the returned values are masked.

### Configuration

The data store middleware is bundled and exported as `dataStoreMiddlewareLazy`. It is an array of React Router middleware functions that load site preferences, global preferences, and other preferences into the router context on every request. It defers retrieving the preferences until a loader actually requests the value. Register it in `src/root.tsx`. Make sure that `siteContextMiddleware` runs first so that the site-preferences middleware can resolve the current site ID. The `siteContextMiddleware` runs on every request to resolve the current site, locale, and currency from the request, checking path, query string, cookie, and header in priority order. It stores the resolved values in the router context so they're accessible to loaders, actions, and components via `useSite()`, then sets the appropriate cookies on the response if the values changed. It also skips overwriting any site, locale, and currency cookies that an action or loader already set earlier in the response.

**note:** The Storefront Next retail template configures the data store middleware for you.

```typescript
// src/root.tsx

import { dataStoreMiddlewareLazy } from "@salesforce/storefront-next-runtime/data-store";

export const middleware: MiddlewareFunction[] = [
  siteContextMiddleware,
  ...dataStoreMiddlewareLazy,
  // ... rest of middleware
];
```

MRT sets these required environment variables in production:

- `AWS_REGION`
- `MOBIFY_PROPERTY_ID`
- `DEPLOY_TARGET`

Optionally, set `SFNEXT_DATA_STORE_UNAVAILABLE_MODE = throw` to fail the request instead of returning an empty object when the data store is unreachable. The default value is `fallback`, which returns an empty object.

### Usage in root.tsx (Server Middleware)

```typescript
// src/root.tsx
import {
  getCustomGlobalPreferencesLazy,
  getSitePreferencesLazy,
} from "@salesforce/storefront-next-runtime/data-store";

const maintenanceMiddleware: MiddlewareFunction = async ({ context }, next) => {
  const sitePrefs = (await getSitePreferencesLazy(context)) ?? {};
  const globalPrefs = (await getCustomGlobalPreferencesLazy(context)) ?? {};

  if (sitePrefs.maintenanceMode || globalPrefs.maintenanceMode) {
    return new Response("Maintenance", { status: 503 });
  }

  return next();
};
```

### Usage in Route Loaders

Use the async getters in any server loader or action. Both getters return a `Promise` that resolves to `Record<string, unknown> | null`. Use `?? {}` or a similar fallback to handle the `null` case when the entry is missing or the data store is unavailable.

```typescript
// src/routes/home.tsx
import {
  getCustomGlobalPreferencesLazy,
  getSitePreferencesLazy,
} from "@salesforce/storefront-next-runtime/data-store";

export async function loader({ context }: Route.LoaderArgs) {
  const sitePrefs = (await getSitePreferencesLazy(context)) ?? {};
  const globalPrefs = (await getCustomGlobalPreferencesLazy(context)) ?? {};

  return {
    showBanner: Boolean(sitePrefs.showBanner),
    enableChat: Boolean(globalPrefs.enableChat),
  };
}
```

### Usage in React Components

To access site preferences in React components, read them in the route loader and pass them to components via `useLoaderData`. There is no client-side hook for site preferences.

```typescript
// src/routes/home.tsx
export default function Home({ loaderData }: Route.ComponentProps) {
  const { showBanner, enableChat } = loaderData;

  return (
    <div>
      {showBanner && <HeroBanner />}
      {enableChat && <ChatWidget />}
    </div>
  );
}
```

### Local Development

Use `MRT_DATA_STORE_DEFAULTS` to seed values without a real data store. Prefix site preference keys with the site ID.

```bash
MRT_DATA_STORE_DEFAULTS='{ "custom-global-preferences": {"enableChat": true},
  "RefArch-custom-site-preferences": {"productsPerPage": 24} }' pnpm dev
```

Data Store Keys:

- Global: `custom-global-preferences`
- Site: `{siteId}-custom-site-preferences`

### Site Preferences Sync Frequency

A system job syncs site preferences to the data store based on the B2C Target Info and Site IDs configured for the Managed Runtime environment. Site preferences can take up to 5 minutes to take effect.

## Page Designer Change Deployment to Storefront Next

When a merchant makes a change to Page Designer pages and components in staging, a system job deploys the page and component metadata, and content to Managed Runtime (MRT). B2C Commerce prebuilds each Page Designer page and sends it to the MRT data store. The storefront reads the page metadata from the data store instead of assembling the page on every shopper request. This approach improves storefront performance by eliminating the need to build page layouts dynamically for each shopper.

You don't author manifests manually. The system automatically builds them from your Page Designer pages without any changes required from you in Business Manager.

**note:** The Page Designer update mechanism described here applies only to Storefront Next. It doesn't apply to other storefront types, including PWA Kit, SFRA, or Site Genesis.

## How Changes in Page Designer Reach Storefront Next

Two preconfigured system jobs deliver manifests to your storefront.

- `sfcc-push-page-manifests`: The system runs this job automatically on production after replication every 5 minutes. This job picks up the manifests that have been replicated from staging and pushes them to the MRT data store.
- `sfcc-generate-and-push-page-manifests`: Run this job manually on production or development instances to push changes to the data store immediately. From Business Manager, go to **Administration > Operations > Jobs**, locate the job, and run it. This job generates manifests from the current instance and pushes them to the data store.

After either job runs, check the results in Business Manager at **Administration > Operations > Job History**. A successful job shows a status of **OK** or **Finished**. If the job fails, review the log details to identify the issue.

### Typical Page Update Flow

Follow this workflow to publish Page Designer changes to your storefront:

1. Author content: A merchant authors page content in Page Designer on the staging instance.
2. Replicate to production: An administrator replicates the changes from staging to production.
3. Wait for automatic sync: The system automatically runs the `sfcc-push-page-manifests` job on production after replication completes.
4. Verify on storefront: Shoppers see the updated content on the storefront. Verify the changes by viewing the affected pages.

### Update Pages Changed Directly on Production

If you make changes directly on production without replicating from staging, the automatic job doesn't pick them up. To push these changes immediately:

1. From Business Manager, go to **Administration > Operations > Jobs**.
2. Locate the `sfcc-generate-and-push-page-manifests` job.
3. Click **Run** to execute the job.
4. Verify that the job completed successfully in **Administration > Operations > Job History**.
5. Check the affected pages on your storefront to confirm the changes appear.

## See Also

- [Page Designer Content Management for Merchants](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer-customize-sf.md)

<!-- document id=a8caa2f9201e02422ff6aebb0d931190a8f4f6e90d2df3049685db71ff10fe01 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/managed-runtime-administration.md -->

# Managed Runtime Administration

Managed Runtime makes it easy to manage your organizations, projects, environments, and bundles associated with your PWA Kit storefront. This guide describes the growing list of administration tasks that are possible in the web-based [Runtime Admin](https://runtime.commercecloud.com/) tool. All of the administration tasks described in this guide, and many more, can also be done using the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary).

**important:** Before you continue, make sure that you have access to Managed Runtime and [Runtime Admin](https://runtime.commercecloud.com/). To provision Managed Runtime, contact your Success Manager. For Runtime Admin, contact your B2C Commerce administrator and ask them to add either one of the following roles to your account using Account Manager: **Managed Runtime User** or **Managed Runtime Admin**.

## Organization

Organization-level administration allows you to manage users and certificates across all projects within your organization. These tasks are typically performed by organization admins or users with specific organizational permissions.

### Managing Organization Users

Organization admins can manage user access and permissions at the organization level, which affects user access across all projects within the organization.

#### Add Organization Users

To add a user at the organization level:

1. Log in to [Account Manager](https://account.demandware.com/).
2. Find the users in your organization that need access.
3. Add the **Managed Runtime Admin** or **Managed Runtime User** role and save.
   Users should now be able to log into [Runtime Admin](https://runtime.commercecloud.com/) for your organization.

**note:** Users added at the organization level still need to be assigned specific project roles to access individual projects.

#### Edit Organization User Permissions

To modify a user's organization-level permissions:

1. Navigate to **Organization Users**.
2. Click **Edit** next to the user's name.
3. Modify the permissions as needed.
   - **Certificates**: Allows the user to view, request, manage, and renew TLS certificates.
   - **View All Projects**: Allows read-only access to all projects within the organization.
4. Click **Save**.

#### Remove Organization Users

To remove a user from the organization:

1. Log in to [Account Manager](https://account.demandware.com/).
2. Find the users in your organization that need access.
3. Remove the **Managed Runtime Admin** or **Managed Runtime User** role and save.

**warning:** Removing a user from Managed Runtime revokes their access to all projects within the organization.

### Certificate Management

Organization admins and users with the **Manage Certificates** permission can manage TLS certificates for environments using the Managed Runtime CDN.

#### Prerequisites for Certificate Management

- Organization Admin role OR **Manage Certificates** permission.
- Access to [Runtime Admin](https://runtime.commercecloud.com/).

#### Request a Certificate

To request a new TLS certificate:

1. Log in to [Runtime Admin](https://runtime.commercecloud.com/).
2. Navigate to **Certificates** for an organization.
3. Click **Request Certificate**.
4. Enter the domains you want to include in the certificate.
   - Fully qualified domains (e.g., `www.example.com`, `staging.example.com`)
   - Wildcard domains (e.g., `*.example.com`)
5. Click **Send Request**.

The certificate request will be processed, and you'll receive domain validation instructions.

#### Domain Validation

After requesting a certificate, you must validate domain ownership.

1. Navigate to **Certificate** and click on the pending certificate.
2. Copy the CNAME records provided for domain validation.
3. Add these CNAME records to your DNS configuration.
4. Validation records must be created within **72 hours** of receiving the validation details.
5. After the DNS records are in place, the certificate request will be validated and available to use with any environments within the organization.

Example validation record:

```
_xyz.example.com    CNAME    _abc.acm-validations.aws
```

#### Monitor Certificate Status

To view the status of your certificates:

1. Navigate to **Certificates**.
2. View the certificate list with validation status indicators.
   - **In Progress**: Awaiting domain validation.
   - **Validation Completed**: Certificate is validated and ready for use.
   - **Failed**: Validation failed because the provided CNAME record wasn't added on time.

#### Certificate Renewal

Managed Runtime automatically renews certificates as long as:

- The domain validation CNAME records remain in place.
- The certificate is actively used by at least one environment.

Members of the certificate's organization receive email notifications as a certificate approaches expiration, unless they've opted out in their email preferences: a renewal-pending notification 40 days before expiry, and expiration reminders at 30, 15, 7, and 2 days before expiry.

#### Associate Certificates with Environments

To use a certificate with an environment:

1. Go to the project's Overview page.
2. Click the environment name.
3. Click **Environment Settings**.
4. Under **Advanced** settings, click **Edit**.
5. Select the appropriate certificate from the **Certificate** dropdown.
6. For wildcard certificates, provide a valid subdomain.
7. Click **Update**.
8. Follow the instructions in [Launching Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md#6-perform-the-cutover).

**important:** - Users must have the **Project Admin** or **Project Developer** role and the organization **View** or **Manage** certificate permission to change certificates.
- Certificates can only be used with environments in the same organization.
- Changes to certificate associations require environment redeployment.

#### Certificate Troubleshooting

If you encounter issues with certificates:

- **Domain Validation Fails**: Verify CNAME records are correctly configured and propagated with the validation window.

## Projects

Projects help you manage multiple environments within an organization. Every PWA Kit project needs a corresponding project within Managed Runtime for deploying and hosting the storefront code on Salesforce’s public cloud infrastructure.

**note:** Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md) for Managed Runtime administration:

```bash
export MRT_API_KEY='your-runtime-admin-api-key'

# List projects.
npx @salesforce/b2c-cli mrt project list

# Deploy a bundle.
npx @salesforce/b2c-cli mrt bundle deploy 12345 --project my-storefront --environment staging

# List environments, variables, and redirects.
npx @salesforce/b2c-cli mrt env list --project my-storefront
npx @salesforce/b2c-cli mrt env var list --project my-storefront --environment staging
npx @salesforce/b2c-cli mrt env redirect list --project my-storefront --environment staging
```

See [MRT commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html).

### Create a Project

To create a project in Runtime Admin:

1.  Log in to [Runtime Admin](https://runtime.commercecloud.com).
2.  Click **New Project**.
3.  Under **Add New Project Details**, enter a name for the project.
4.  Under **Set Environment Defaults**, review the default settings that apply to new environments in the project. Server-Side Cookie Access is enabled by default for new projects, which lets your storefront access and manage cookies from server-side code. To turn it off, clear the setting.
5.  Click **Create Project**.

**note:** When you first create a project, your site isn’t accessible on the web until after the necessary cloud infrastructure is deployed. This deployment process can take up to 40 minutes.

### Find a Project in Runtime Admin

The instructions for the rest of the administration tasks in this guide all assume that you’re starting from a project Overview page in Runtime Admin.

To find an existing project and open its Overview page:

1.  Log in to [Runtime Admin](https://runtime.commercecloud.com/).
2.  Select an organization from the organization menu (top left), if necessary.
3.  Click the name of the project. (To see the project, you must be assigned one of the project roles described previously.)

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin-1.png)

To find a project quickly, use the project search box to filter across all the projects in your organization, not just the ones on the current page. You can also choose how many projects to show per page (20, 50, or 100). Your search term and page size are saved in the page URL, so you can bookmark or share a filtered view.

To quickly switch between projects, use the project menu at the top of the page.

### View and Edit Project Settings

The Project Settings page is where you can do the following tasks:

- Look up the project ID and ensure that it matches a PWA Kit configuration.
- Edit the project ID.
- View and edit the project’s name and URL.
- Set environment defaults, including the default server architecture and proxy user agent for new environments.
- Delete the project.
- Manage deployment notifications. (See next section.)

To access the Project Settings page:

1.  Go to a project’s Overview page.
2.  Click Project Settings from the left navigation.

To edit the settings, click **Edit**, make your edits, and click **Update**. To discard your edits, click **Cancel**.

To delete a project, click **Delete**, enter the project name to confirm, and click **Yes, Delete**. To keep the project, click **No, Keep**.

## Deployment Notifications

You can choose to be notified by email whenever any of the following deployment events happen:

- Start Deployment
- Successful Deployment
- Failed Deployment

### Add a Notification

To add a notification:

1.  Go to a project’s Overview page.
2.  Click **Project Settings** from the left navigation.
3.  Click **Add Notification**.
4.  Select one or more environments to be notified about.
5.  Select one or more deployment events.
6.  Enter email addresses for all notification recipients.
7.  Click **Add Notification**.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin-5.png)

### Edit a Notification

To edit a notification:

1.  Go to a project’s Overview page.
2.  Click **Project Settings** from the left navigation.
3.  Click the **...** button next to the notification.
4.  Click **Edit**.
5.  Change any of the notification settings.
6.  Click **Update Notification**.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin-6.png)

### Remove a Notification

To remove a notification:

1.  Go to a project’s Overview page.
2.  Click **Project Settings** from the left navigation.
3.  Click the **...** button next to the notification.
4.  Click **Remove**.
5.  Click **Yes, Remove**.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin-7.png)

## Environments

Environments are used to separate your production storefront from other storefronts that are deployed for other purposes, such as development or testing. To learn more about environments and other related concepts, see the [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.md).

### Create an Environment

To create an environment in Runtime Admin:

1.  Go to a project’s Overview page.
2.  Click **New Environment**
3.  Enter a name for the environment.
4.  Select a [region](#supported-regions) for deploying to Salesforce’s public cloud infrastructure.
5.  If the environment is a production environment:

    - Mark it as production. If you have reached your limit of production environments, contact Support. For more information, see [Production Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#production-environments).
    - Add one or more site IDs to associate with the environment.

6.  Select a B2C Commerce instance to connect to the environment.
7.  Click **Complete Setup**.

**note:** - The default region for new environments is US East (N. Virginia) because it’s located closest to on-demand sandboxes, which are commonly associated with development and testing environments.
- If you previously created an environment, you can [Edit Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html?#edit-environment-settings) to connect it to a B2C Commerce instance and one or more site IDs.
- Non-production environments have lower capacity limits, reflecting their use for development and testing traffic. Production environments also receive additional internal monitoring by Salesforce. For details, see [Production Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#production-environments).

### Supported Regions

All supported regions have a paired backup region for failovers. You're responsible for ensuring that your application runs correctly in the selected primary and backup regions:

<table>
  <thead>
    <tr>
      <th colspan="1" rowspan="1">Primary Region</th>
      <th colspan="1" rowspan="1">Backup Region</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="1" rowspan="1"><code>us-east-1</code> - US East (N. Virginia)</td>
      <td colspan="1" rowspan="1"><code>us-east-2</code> - US East (Ohio)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>us-east-2</code> - US East (Ohio)</td>
      <td colspan="1" rowspan="1"><code>us-east-1</code> - US East (N. Virginia)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>us-west-1</code> - US West (N. California)</td>
      <td colspan="1" rowspan="1"><code>us-west-2</code> - US West (Oregon)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>us-west-2</code> - US West (Oregon)</td>
      <td colspan="1" rowspan="1"><code>us-west-1</code> - US West (N. California)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ca-central-1</code> - Canada (Central)</td>
      <td colspan="1" rowspan="1"><code>us-east-2</code> - US East (Ohio)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>sa-east-1</code> - South America (São Paulo)</td>
      <td colspan="1" rowspan="1"><code>us-east-1</code> - US East (Northern Virginia)</td>
    </tr>    
    <tr>
      <td colspan="1" rowspan="1"><code>ap-south-1</code> - Asia Pacific (Mumbai)</td>
      <td colspan="1" rowspan="1"><code>ap-south-2</code> - Asia Pacific (Hyderabad)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-south-2</code> - Asia Pacific (Hyderabad)</td>
      <td colspan="1" rowspan="1"><code>ap-south-1</code> - Asia Pacific (Mumbai)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
      <td colspan="1" rowspan="1"><code>ap-northeast-2</code> - Asia Pacific (Seoul)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-southeast-2</code> - Asia Pacific (Sydney)</td>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-southeast-3</code> - Asia Pacific (Jakarta)</td>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-northeast-2</code> - Asia Pacific (Seoul)</td>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
    </tr>     
    <tr>
      <td colspan="1" rowspan="1"><code>ap-northeast-1</code> - Asia Pacific (Tokyo)</td>
      <td colspan="1" rowspan="1"><code>ap-northeast-3</code> - Asia Pacific (Osaka)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-northeast-3</code> - Asia Pacific (Osaka)</td>
      <td colspan="1" rowspan="1"><code>ap-northeast-1</code> - Asia Pacific (Tokyo)</td>
    </tr>    
    <tr>
      <td colspan="1" rowspan="1"><code>eu-west-1</code> - EU (Ireland)</td>
      <td colspan="1" rowspan="1"><code>eu-west-3</code> - EU (Paris)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-west-2</code> - EU (London)</td>
      <td colspan="1" rowspan="1"><code>eu-west-1</code> - EU (Ireland)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-west-3</code> - EU (Paris)</td>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
      <td colspan="1" rowspan="1"><code>eu-west-3</code> - EU (Paris)</td>
    </tr>    
    <tr>
      <td colspan="1" rowspan="1"><code>eu-central-2</code> - EU (Zurich)</td>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-south-1</code> - EU (Milan)</td>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>me-central-1</code> - Middle East (United Arab Emirates)</td>
      <td colspan="1" rowspan="1"><code>eu-west-2</code> - EU (London)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>il-central-1</code> - Israel (Tel Aviv)</td>
      <td colspan="1" rowspan="1"><code>eu-west-2</code> - EU (London)</td>
    </tr>         
  </tbody>
</table>

### Deploy a Bundle

For any site that uses PWA Kit and Managed Runtime, you can only designate **one bundle at a time** as deployed for each environment.

1.  Go to a project’s overview page.
2.  Click the name of the environment you want to deploy to. For example: **production**.
3.  Under the heading **Bundles**, click the **Deploy** button next to the bundle you want to deploy.
4.  Click **Confirm Deploy**.
5.  Wait until the deployment is complete.

When the deployment has successfully completed, the bundle appears underneath the heading **Deployed Bundle**. (For your first deployment to a new environment, the process can take up to an hour to complete.)

### Delete a Bundle

For any site that uses PWA Kit and Managed Runtime, you can delete only non-deployed bundles form a project.

1.  In the project’s overview page, click an environment.
2.  Select one or more bundles that aren't currently deployed.
3.  Click **Delete**.
4.  When asked to confirm, click **Delete**.
5.  Wait until the deletion is completed.

Deletions are handled asynchronously and can take time to process.

### Edit Environment Settings

The Environment Settings page is where you can do many administration tasks in one place, including:

- Rename an environment or environment ID.
- Change the deployment region.
- Enable or disable server-side cookies. New projects have Server-Side Cookie Access enabled by default. Existing projects continue to have server-side cookies turned off by default. See [Personalize with Cookies](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/personalize-with-cookies.md).
- Enable or disable [Source Maps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#source-maps).
- Allow traffic with specific IP addresses or a trusted access control header to access an environment. See [Access Control Headers](#access-control-headers).
- Configure proxies for an environment. See [Proxying Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md) for more information.
- Control whether proxied requests forward the shopper's original user agent or replace it with the Amazon CloudFront infrastructure user agent. See [Proxying Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md#request-modifications).
- Mark an environment as production.
- Enable or disable Log Center logs and metrics under Observability settings. See [Log Center Logs and Metrics](#log-center-logs-and-metrics).
- Add, edit, or remove site IDs associated with an environment.
- Add or edit an environment’s connection to a B2C Commerce instance.
- Delete an environment.

To access the Environment Settings page:

1.  Go to a project’s Overview page
2.  Click the name of the environment whose settings you want to edit.
3.  Click **Environment Settings** from the left navigation.

To make edits, click the **Edit** button next to either the **General** settings or the **Advanced** settings. After making your edits, click **Update** to save your changes or click **Cancel** to discard your changes.

### Server-Side Rendering Architecture

Managed Runtime supports two processor architectures for Server-Side Rendering (SSR): ARM and x86. The architecture determines the underlying compute infrastructure used to render your storefront.

#### ARM Architecture (Default for New Projects)

ARM architecture is the default for all new projects created in Managed Runtime. ARM processors offer several advantages.

- **Enhanced Performance**: ARM architecture provides efficient processing capabilities optimized for modern web workloads.
- **Modern Infrastructure**: Built on the latest cloud computing technologies.

**Who Can Use It**: All new Managed Runtime projects automatically use ARM architecture.

#### x86 Architecture (Scheduled for Retirement)

**warning:** The x86 architecture is retiring on **January 31, 2027**. After that date, environments running on x86 can't be deployed. Environments aren't deleted and continue to respond to requests. Switch your environments to ARM before this date to avoid deployment disruptions.

The x86 architecture is available for existing customers until its retirement on January 31, 2027.

**Who**: Existing customers with projects created before ARM architecture was introduced can continue using x86 until January 31, 2027.

#### Choosing an Architecture

- **New Projects**: ARM architecture is automatically selected and is the recommended choice for all new projects.
- **Existing projects**: x86 architecture is retiring on January 31, 2027. Switch your environments to ARM before this date to avoid deployment disruptions. Admins can switch existing environments to ARM at any time in Runtime Admin under environment settings. Most projects require no code changes. If your project uses architecture-specific native modules, test in a non-production environment before switching production.

#### Project-Level Default Architecture

You can set a default architecture at the project level that automatically applies to all new environments created within that project. This setting streamlines environment creation by eliminating the need to select an architecture for each new environment.

How to Set Project-Level Default:

1. Go to a project's Overview page.
2. Click **Project Settings** from the left navigation.
3. Under **Environment Defaults** and **Server Architecture**, select either **ARM** or **x86**.
4. Click **Update**.

All new environments created in the project automatically use the selected default architecture. Existing environments aren't affected by changes to the project-level default.

### Clear an Environment's CDN Cache

You can clear some or all of an environment's cached content in the content delivery network (CDN). Clearing the CDN cache helps to ensure that shoppers see the most recent and accurate version of content on your site.

Use the [projects_target_invalidation_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_invalidation_create) API to clear all cached content, specific URLs, or directories.

It's not possible to clear the CDN cache in Runtime Admin. However, when you redeploy a bundle, that clears all cached content for the associated environment.

**note:** Invalidation of the CDN cache temporarily results in slower performance for the first shoppers accessing the site after the invalidation.

## Environment Variables

See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

## Log Center Logs and Metrics

Log Center logs and Log Center metrics are independently configurable for any environment, as long as the environment is associated with a B2C Commerce instance. Unlike production monitoring, enabling Log Center logs or metrics doesn't require marking the environment as production.

### Usage

Enable Log Center logs and Log Center metrics under **Observability** in [Environment Settings](#edit-environment-settings). You can enable either setting independently.

**note:** An environment must be associated with a B2C Commerce instance before you can enable Log Center logs or metrics. See [Edit Environment Settings](#edit-environment-settings).

**See Also**

- [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.md#debug-using-log-center)

## Access Control Headers

Access control headers allow you to restrict access to an environment so that only trusted traffic coming from your content delivery network (CDN) or development team is allowed. Restricting access is important to ensure that bots don't go around your CDN perimeter security settings and to ensure that search crawlers don’t index content from the wrong domain or environment.

If Allowed IP addresses are also set, requests with either a valid IP address or an access control header are allowed through.

**note:** Access control headers secure traffic arriving at MRT from your CDN. To secure traffic from MRT to the B2C Commerce API (SCAPI), see [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-request-identification.md).

### Usage

Set access control headers by using the [Advanced Environment Settings](#edit-environment-settings) or the [projects_target_access_control_header_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_access_control_header_create) API.

Incoming requests are allowed only if an `x-sfdc-access-control` request header is present with a valid value.

### Constraints

A header value is made up of your chosen set of characters. Each header value:

- Must be at least 9 characters long
- Can contain up to 128 characters
- Can be a combination of alphanumeric characters and `-` and `_` characters

Access control headers are not available to code running in a Managed Runtime environment.

### Rotate Access Control Headers

You’re responsible for ensuring that the access control header value is securely stored and shared only with trusted individuals. We strongly recommend rotating the access control header on a regular basis.

To rotate an access control header:

- Add an access control header value to the Managed Runtime environment by using the [Advanced Environment Settings](#edit-environment-settings) or the [projects_target_access_control_header_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_access_control_header_create) API.
- Wait for the Environment redeploy to complete successfully. Verify requests to the environment with the new header value succeed with a command such as:

```bash
curl https://myproject-mytarget.mobify-storefront.com/ -H "x-sfdc-access-control: 123456789" -o /dev/null
```

- Update your CDN or browser to send the `x-sfdc-access-control` request header with the updated value.
- Test that traffic is being allowed through as expected.
- Remove the original access control header value by using the [Advanced Environment Settings](#edit-environment-settings) or the [projects_target_access_control_header_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_access_control_header_create) API.

**See Also**

- [Configure Your Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md#5-configure-your-environment)

## Redirects

A redirect allows you to forward a request from the requested URL to a different URL. Redirects can help avoid disruptions to the user experience caused by changes to your storefront. For example, consider a seasonal campaign page for spring. When the spring campaign ends and is replaced with a summer campaign, you can redirect from the spring URL to the summer URL.

Redirects is a powerful feature that can have significant security consequences on your storefront, including redirecting to malicious URLs or assets. Please be careful when assigning roles to your users that give them Redirect access.

### Create a Redirect

**tip:** Before creating a redirect in a production environment, we recommend that you create it in a staging environment first.

You can also create one or more redirects using the [projects_target_redirect_create](/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_create) API endpoint.

To create a redirect using Runtime Admin:

1.  Go to a project’s Overview page.
2.  Click the name of the environment where you want to create the redirect.
3.  Click **URL Redirects** from the left navigation.
4.  Click **Create Redirect**.
5.  In the **Redirect From** field, enter a relative URL path. For example, to redirect visitors from the URL `www.example.com/winter`, enter `/winter`.
6.  In the **Redirect To** field, enter a relative URL path.
7.  If needed, enable forwarding of query parameters and the wildcard path. (More information on forwarding settings in a moment.)
8.  From the **Redirect Type** dropdown menu, select a redirect type based on the HTTP status code. (More information on status codes in a moment.)
9.  Click **Create Redirect**.

Let’s look at the options for creating a redirect in more detail.

#### Paths

The value that you enter in the **Redirect From** field must always be a _relative_ path. The **Redirect To** field can be either a relative path or a full URL. For example, imagine that we want to redirect visitors from `www.example.com/spring` to `www.example.com/summer`. The **Redirect From** field must be `/spring`. The **Redirect To** field can be either `/summer` or `www.example.com/summer`.

#### Wildcards

You can add an asterisk character (`*`) to the end of the **Redirect From** URL to indicate a wildcard. A wildcard matches any (0 or more) characters in the URL. For example, a redirect from `/a/*` would match `/a/`, `/a/b`, and `/a/b/c`.

A wildcard character can only be used at the end of the **Redirect From** URL.

Standard redirects are processed first by Managed Runtime, followed by redirects with wildcards.

#### HTTP Status Codes

Most redirects use the Permanent 301 status code, but you can also select Temporary 302. If you’re unsure which HTTP status code to use, consult this [status code explainer](https://moz.com/learn/seo/redirection) from MOZ.com.

#### Forwarding Query Parameters

Some requests contain query string parameters that you also want to include in the redirected request. For example, the relative path `/spring-landing-page` can be appended with a query string for analytics tracking, such as `/spring-landing-page?gclid=123`.

To enable query parameter forwarding, go to the **Forward** section of the form and select **Query Parameters**. Otherwise, query string parameters from the source URL aren’t included in the redirect URL.

What happens when both the **Redirect From** and **Redirect To** URLs both have query strings and forwarding is enabled? In this case, the redirect URL includes a combination of the two query strings. The query parameters from the **Redirect To** URL are appended to the query string in the request. For example, imagine your application receives a request for the relative path `/spring?year=2019`. If you’ve chosen to redirect `/spring` to `/summer?year=2020`, the redirect URL is `/summer?year=2019&year=2020` when forwarding is enabled.

#### Forwarding Wildcard Path

You can automatically include any path that comes after the wildcard portion of the **Redirect From** URL in the **Redirect To** URL. For example: if `/a/*` matches `/a/b/c` in the **Redirect From** URL, and the **Redirect To** URL is `/z/`, the redirect URL is `/z/b/c`.

To enable wildcard path forwarding, go to the **Forward** section of the form and select **Wildcard Path**.

### Clone Redirects

**tip:** We recommend that you always create redirects in a staging environment and clone them into production after testing them.

You can copy all the redirects from one environment to another using the clone redirects feature.

You can also clone redirects using the [projects_target_redirect_clone_create ](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_clone_create) API endpoint.

To clone redirects using Runtime Admin:

1.  Go to a project’s Overview page.
2.  Click the name of the environment that contains the redirects that you want to clone.
3.  Click **URL Redirects** from the left navigation.
4.  Click **Clone Redirects**. The **Clone Redirects** form appears. The current environment is listed under **From Environment** (the source).
5.  Under **To Environment**, select the environment that you want to clone the redirects into (the destination).
6.  Click **Clone n Redirects**. (Where n is the number of redirects to be cloned.)

**warning:** When you clone redirects, you’re replacing _all_ the redirects in the destination environment with _all_ the redirects from the source environment.

### Edit a Redirect

You can also edit a redirect using the [projects_target_redirect_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_partial_update) API endpoint.

To edit the settings for an existing redirect using Runtime Admin:

1.  Go to a project’s Overview page.
2.  Click the name of the environment that contains the redirect that you want to edit.
3.  Click **URL Redirects** from the left navigation.
4.  Click the ellipsis button (...) next to the redirect.
5.  Click **Edit**.
6.  Update the settings.
7.  Click **Update Redirect**.

### Delete a Redirect

You can also delete a redirect using the [projects_target_redirect_destroy](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_destroy) API endpoint.

To delete a redirect using Runtime Admin:

1.  Go to a project’s Overview page.
2.  Click the name of the environment that contains the redirect that you want to delete.
3.  Click **URL Redirects** from the left navigation.
4.  Click the ellipsis button (...) next to the redirect.
5.  Click **Delete**.
6.  Click **Yes, Delete Redirect**.

### Troubleshooting Redirects

If a redirect isn’t working as expected, try these troubleshooting steps:

- [Clear your browser cache](https://support.google.com/accounts/answer/32050?co=GENIE.Platform%3DDesktop&hl=en) because redirects are cached.
- Verify that you’re viewing the settings for the correct environment.
- Edit the redirect and verify that the correct values are entered in the **Redirect From** and **Redirect To** fields.

### Technical Limitations with Redirects

Redirects have the following technical limitations:

- Each environment can have a maximum of 10,000 redirects.
- Each environment has its own set of redirects. It is your responsibility to keep them in sync using cloning.
- The redirects feature supports simple redirects from one path to another. For complex redirects with conditionals use Express.js' [redirects support](http://expressjs.com/en/api.html#res.redirect) in `ssr.js`.
- Redirects created with the Runtime Admin tool or the Managed Runtime API are not run on local development environments.
- Redirects are not triggered by page transitions in the PWA Kit application; they can only be triggered by an HTTP request.
- To load a redirect in the context of a storefront, use the managed endpoint `/mobify/redirect/$path`.

## Users

Here’s how to manage your users.

### Add a User

To add a user to a project:

1.  Go to a project’s Overview page.
2.  Click **Users & Permissions** from the left navigation.
3.  Click **New User**.
4.  Enter the user’s email address. (Make sure that the user is part of your organization and has either one of the following roles in Account Manager: **Managed Runtime User** or **Managed Runtime Admin**.)
5.  Select a role.
6.  Click **Add User**.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin-2.png)

### Change a User’s Role

To change a user’s role:

1.  Go to a project’s Overview page.
2.  Click **Users & Permissions** from the left navigation.
3.  Click the **...** button next to the user’s name.
4.  Click **Edit**.
5.  Select a role.
6.  Click the popup menu that appears.
7.  Select a new role.
8.  Click **Save**.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin-3.png)

For a list of user abilities associated with each role, see the [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.md).

### Remove a User

To remove a user from a project:

1.  Go to a project’s Overview page.
2.  Click **Users & Permissions** from the left navigation.
3.  Click the **...** button next to the user’s name.
4.  Click **Remove**.
5.  Click **Yes, Remove User**.

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin-4.png)

<!-- document id=3ebe94bc2bf5663a12426b1d071fa933625dc3d863767545758bb88f071f48af url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-administration.md -->

# Managed Runtime Administration in Runtime Admin and Business Manager

Manage your organizations, projects, environments, and bundles associated with your Storefront Next storefront or a linked Composable storefront with various tools, including the [Runtime Admin](https://runtime.commercecloud.com/) console, Business Manager, and Account Manager.

To automate these tasks, use the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/storefront-next/references/mrt-admin?meta=Summary).

## Which Interface to Use

Use these interfaces to manage your storefront development resources.

- **Business Manager with the Developer Workspace Beta:** Environments, environment settings, deployments, environment variables, and redirects are accessible in Business Manager from the storefront page.
- **Business Manager without the Developer Workspace Beta:** Environments are accessible in Business Manager from the storefront page. Deployments, environment settings, environment variables, redirects are in Runtime Admin.
- **Runtime Admin:** The storefront uses Runtime Admin. Open [Runtime Admin](https://runtime.commercecloud.com/) and select the project for the storefront.

**note:** During the beta, deployment notifications stay in Runtime Admin even when the storefront uses Business Manager.

## Permissions

Grant access in the interface the storefront uses.

- **Runtime Admin:** Ask a B2C Commerce administrator to add the **Managed Runtime User** or **Managed Runtime Admin** role in Account Manager. To assign organization and project roles, see [Organization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#organization) and [Users](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#users) in [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md).
- **Business Manager:** Create roles and assign storefront permissions. See [Manage Roles and Permissions for Your Storefront in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-users.md). A Business Manager admin needs the **Business Administrator** role in Account Manager, or a role for the Business Manager module and organization context with read-write access to storefronts. During the beta, a user who works in Business Manager also needs a matching Managed Runtime project role. See [Create a Role in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_roles.htm&type=5) in _Salesforce Help_.

## Environments

An environment is the cloud infrastructure and configuration for one deployed storefront. When you create a storefront in Business Manager, the storefront includes the embedded content delivery network (eCDN) and a default domain. The default domain maps to the Managed Runtime site.

For environment concepts, including production environments, see the [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md).

### Create an Environment in Business Manager

See [Create an Environment in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-create-environment.md).

### Supported Regions

All supported regions have a paired backup region for failovers. The region list is the same in Runtime Admin and Business Manager. Make sure that your application runs correctly in the selected primary and backup regions:

<table>
  <thead>
    <tr>
      <th colspan="1" rowspan="1">Primary Region</th>
      <th colspan="1" rowspan="1">Backup Region</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan="1" rowspan="1"><code>us-east-1</code> - US East (N. Virginia)</td>
      <td colspan="1" rowspan="1"><code>us-east-2</code> - US East (Ohio)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>us-east-2</code> - US East (Ohio)</td>
      <td colspan="1" rowspan="1"><code>us-east-1</code> - US East (N. Virginia)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>us-west-1</code> - US West (N. California)</td>
      <td colspan="1" rowspan="1"><code>us-west-2</code> - US West (Oregon)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>us-west-2</code> - US West (Oregon)</td>
      <td colspan="1" rowspan="1"><code>us-west-1</code> - US West (N. California)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ca-central-1</code> - Canada (Central)</td>
      <td colspan="1" rowspan="1"><code>us-east-2</code> - US East (Ohio)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>sa-east-1</code> - South America (São Paulo)</td>
      <td colspan="1" rowspan="1"><code>us-east-1</code> - US East (Northern Virginia)</td>
    </tr>    
    <tr>
      <td colspan="1" rowspan="1"><code>ap-south-1</code> - Asia Pacific (Mumbai)</td>
      <td colspan="1" rowspan="1"><code>ap-south-2</code> - Asia Pacific (Hyderabad)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-south-2</code> - Asia Pacific (Hyderabad)</td>
      <td colspan="1" rowspan="1"><code>ap-south-1</code> - Asia Pacific (Mumbai)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
      <td colspan="1" rowspan="1"><code>ap-northeast-2</code> - Asia Pacific (Seoul)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-southeast-2</code> - Asia Pacific (Sydney)</td>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-southeast-3</code> - Asia Pacific (Jakarta)</td>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-northeast-2</code> - Asia Pacific (Seoul)</td>
      <td colspan="1" rowspan="1"><code>ap-southeast-1</code> - Asia Pacific (Singapore)</td>
    </tr>     
    <tr>
      <td colspan="1" rowspan="1"><code>ap-northeast-1</code> - Asia Pacific (Tokyo)</td>
      <td colspan="1" rowspan="1"><code>ap-northeast-3</code> - Asia Pacific (Osaka)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>ap-northeast-3</code> - Asia Pacific (Osaka)</td>
      <td colspan="1" rowspan="1"><code>ap-northeast-1</code> - Asia Pacific (Tokyo)</td>
    </tr>    
    <tr>
      <td colspan="1" rowspan="1"><code>eu-west-1</code> - EU (Ireland)</td>
      <td colspan="1" rowspan="1"><code>eu-west-3</code> - EU (Paris)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-west-2</code> - EU (London)</td>
      <td colspan="1" rowspan="1"><code>eu-west-1</code> - EU (Ireland)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-west-3</code> - EU (Paris)</td>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
      <td colspan="1" rowspan="1"><code>eu-west-3</code> - EU (Paris)</td>
    </tr>    
    <tr>
      <td colspan="1" rowspan="1"><code>eu-central-2</code> - EU (Zurich)</td>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>eu-south-1</code> - EU (Milan)</td>
      <td colspan="1" rowspan="1"><code>eu-central-1</code> - EU (Frankfurt)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>me-central-1</code> - Middle East (United Arab Emirates)</td>
      <td colspan="1" rowspan="1"><code>eu-west-2</code> - EU (London)</td>
    </tr>
    <tr>
      <td colspan="1" rowspan="1"><code>il-central-1</code> - Israel (Tel Aviv)</td>
      <td colspan="1" rowspan="1"><code>eu-west-2</code> - EU (London)</td>
    </tr>         
  </tbody>
</table>

### Deploy a Bundle

- **Runtime Admin:** See [Deploy a Bundle](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#deploy-a-bundle).
- **Business Manager:** See [Deploy Your Storefront from Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-deployments.md).

### Edit Environment Settings

- **Business Manager (Developer Workspace Beta):** Edit settings on the storefront page in Business Manager. See [Edit Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-environments.md#edit-environment-settings).
- **Business Manager:** Go to **Administration > Sites > Storefronts**, click the storefront, and then next to the environment, click the caret and click Edit. Log in to Runtime Admin opens in a new tab and access Environment Settings.
- **Runtime Admin:** Log in to [Runtime Admin](https://runtime.commercecloud.com/). From the project, click the environment, and then click **Environment Settings**. Click **Edit** next to **General** settings or **Advanced** settings.

From environment settings, you can complete these tasks:

- Rename an environment or environment ID.
- Change the deployment region. See [Supported Regions](#supported-regions).
- Enable or disable source maps. See [Source Maps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-environments.md#source-maps).
- Mark an environment as production. See [Production Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md#production-environments).
- Enable or disable Log Center logs and metrics. In Runtime Admin, the controls are under **Observability**. See [Log Center Logs and Metrics](#log-center-logs-and-metrics).
- Add, edit, or remove site IDs associated with an environment.

**note:** Cookies are always enabled for Storefront Next and can't be disabled. See [Storage and Sessions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storage-sessions.md).

### Server-Side Rendering Architecture

Managed Runtime supports the ARM processor architecture for Server-Side Rendering (SSR) for Storefront Next. The ARM architecture represents the underlying compute infrastructure used to render your storefront.

ARM processors offer several advantages.

- **Enhanced Performance**: ARM architecture provides efficient processing capabilities optimized for modern web workloads.
- **Modern Infrastructure**: Built on the latest cloud computing technologies.

## Environment Variables

See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md). That topic has the steps for Runtime Admin and for Business Manager.

## Redirects

Use a redirect to forward a request from one URL to another. Redirects can help avoid disruptions to the user experience caused by changes to your storefront. For example, consider a seasonal campaign page for spring. When the spring campaign ends and is replaced with a summer campaign, you can redirect from the spring URL to the summer URL.

Redirects is a powerful feature that can have significant security consequences on your storefront, including redirecting to malicious URLs or assets. Be careful when assigning roles to users that give them Redirect access.

**tip:** Before creating a redirect in a production environment, we recommend that you create it in a staging environment first.

- **Runtime Admin:** See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#redirects) in [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md).
- **Business Manager:** See [URL Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-environments.md#url-redirects).

## Log Center Logs and Metrics

Log Center provides a single location to access logs from Managed Runtime (MRT) and your B2C Commerce instance. Log Center logs and Log Center metrics are independently configurable for any environment, as long as the environment is associated with a B2C Commerce instance. Unlike uptime monitoring, enabling Log Center logs or metrics doesn't require marking the environment as production. See [Debug Your Storefront in Production Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug-log-center.md).

Enable Log Center logs and Log Center metrics independently in Environment Settings, under **Observability**.

**note:** An environment must be associated with a B2C Commerce instance before you can enable Log Center logs or metrics. See [Edit Environment Settings](#edit-environment-settings).

**See Also**

- [View Logs in Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-logging.md#view-logs-in-log-center)
- [Debug Your Storefront Next Site Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug-log-center.md)

<!-- document id=269c010f0ff0d4dc4597d8ca7159e69ab41d4e3ccb51db445403349ca2ab4c8e url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/using-the-managed-runtime-api.md -->

# Managed Runtime API

Use the Managed Runtime API to control applications deployed to B2C Commerce’s Managed Runtime. You can create custom tooling that has the same functionality as the [Runtime Admin](https://runtime.commercecloud.com/) web application, but you get even more administration abilities and configuration options.

**note:** Instead of Managed Runtime API, use the B2C Commerce API (SCAPI) endpoints to manage storefront environments and deployments. SCAPI authorization is based on Account Manager and is suitable for automating storefront tasks by using a bot user. See [Automate Storefront Administration with APIs](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-mrt-api.md).

## Considerations

**warning:** **The Managed Runtime API is for administration purposes only.** Do _not_ make requests to the API in your storefront code. Requests that exceed [rate limits](#rate-limits) are blocked.

- To read [environment variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md) from the storefront, use [`process.env`](https://nodejs.org/api/process.html#processenv).
- To read and load [redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#redirects) use the managed endpoint `/mobify/redirects/$path`.

## Before You Begin

This guide assumes that you're already familiar with Managed Runtime and related concepts, such as: projects, environments, bundles, and deployments. To learn more, see the [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.md).

**note:** The Mobify brand name still appears in the `mobify.com` domain in the base URL for the Managed Runtime API. Although new Salesforce domains will eventually take the place of the Mobify domain, support for the Mobify domain will continue.

To make API requests, you must include an API key in the HTTP request `Authorization` header with the value, `Bearer $API_KEY`.

To find your API key, log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool and go to the [Account Settings](https://runtime.commercecloud.com/account/settings) page.

**note:** Treat your API key like a password because it allows scripts to perform operations on your behalf.

## Tutorial

We’re about to show you how to use the API with a brief tutorial based on some sample requests, which are formatted as `curl` commands.

Before running the commands, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

For most requests, you must replace `$PROJECT_ID` with your actual project ID. To look up your project ID, log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool and go to your project’s settings page.

Project IDs can be up to 20 characters long and must be unique globally.

### List Environments

Our first request to the Managed Runtime API lists all the environments (or "targets" as they're called in the API) that belong to a project:

Call the [projects_target_list](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_list) API endpoint to list the environments:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$API_KEY"

npx @salesforce/b2c-cli mrt env list --project "$PROJECT_ID"
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
  --header "Authorization: Bearer $API_KEY"
```

### Create an Environment

Now let’s create an environment called `staging` that we can use to verify changes before deploying them to `production`:

First call the [projects_target_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_create) API endpoint. If you’re creating a project, you can call the [projects_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_create) API endpoint to also create an environment:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli mrt env create staging --project "$PROJECT_ID"
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/" \
  --request 'POST' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name": "staging"}'
```

Then call the [cc_b2c_target_info_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=cc_b2c_target_info_update) API endpoint to connect a B2C Commerce instance and one or more sites to the environment.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
npx @salesforce/b2c-cli mrt env b2c \
  --project "$PROJECT_ID" --environment staging \
  --instance-id aaaa_stg --sites DemoSite1,DemoSite2
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/cc/b2c/projects/$PROJECT_ID/b2c-target-info/staging/" \
  --request 'PUT' \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"instance_id": "aaaa_stg", "sites": ["DemoSite1", "DemoSite2"]}'
```

_To use your new environment, you must [*deploy a bundle*](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) to it._

Let’s call the [projects_target_retrieve](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_retrieve) API endpoint to review the details of the `staging` environment that we created:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
  --header "Authorization: Bearer $API_KEY"
```

### Modify Proxy Configuration

Finally, let’s call the [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) API endpoint to modify the proxy configuration for `staging`:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/staging/" \
  --request 'PATCH'  \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"ssr_proxy_configs": [{"path": "api", "host": "kv7kzm78.api.commercecloud.salesforce.com"}]}'
```

_Changing the configuration redeploys the deployed bundle so that the configuration update takes effect._

## Troubleshooting

If you’re having trouble using the API, try these troubleshooting steps.

- Add the `--fail` argument to your `curl` command.
- Check your API key.
- Check your project’s ID.

The API endpoints also work in a browser. Log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool then open the endpoint you’re using directly in your browser.

## Automation Users 🤖

To support continuous integration and deployment using the Managed Runtime API, create an Account Manager user for automation:

- Create a user account in Account Manager using a shared email address like a Google Group. _Store the associated credentials and MFA code in a password manager like LastPass._
- Give the user the `Managed Runtime User` role.
- Assign the user the required permissions in Runtime Admin. _The user's Managed Runtime API key can only access what is allowed by the user's permissions. Keep them specific to the projects that CI/CD needs to interact with._
- Create the API key for the user and save it in your continuous integration system.

To keep the Managed Runtime API key active, you must keep the related Account Manager account active by updating its password as required by your organization's Account Manager configuration. If the user is deactivated, reactivate it by resetting the password to re-enable the API key.

## Rate Limits

The Managed Runtime API has rate limits in place for the number of requests allowed per unit of time. Rate limits are applied on a per-user basis, and help ensure fair access for all users.

If your request exceeds a rate limit, the API returns an HTTP `429 Too Many Requests` error, and a `Retry-After` HTTP header that indicates the number of seconds to wait until you can retry.

Rate limits cannot be adjusted.

### How to Read the Numbers

The tables below indicate the rate limits for different API families.

**important:** Some endpoints have cumulative rate limits, which means they are not throttled on a per-endpoint basis. Instead, cumulative rate limits throttle the combined number of requests across multiple endpoints. All GET requests have a cumulative rate limit. Similarly, all POST, PATCH, and DELETE requests for endpoints that are not individually called out in the following tables have a cumulative rate limit. These limits are described [below](#default-rate-limits).

### Projects and Environments

| Method | Endpoint                           |
| ------ | ---------------------------------- |
| POST   | `/api/projects/`                   |
| PATCH  | `/api/projects/*/`                 |
| DELETE | `/api/projects/*/`                 |
| POST   | `/api/projects/*/builds/*/`        |
| POST   | `/api/projects/*/target/`          |
| PATCH  | `/api/projects/*/target/*/`        |
| DELETE | `/api/projects/*/target/*/`        |
| POST   | `/api/projects/*/target/*/deploy/` |

| Cumulative 1 Minute Limit | Cumulative 1 Hour Limit |
| ------------------------- | ----------------------- |
| 10                        | 100                     |

### Cache Invalidations

| Method | Endpoint                                 | 5 Minute Limit | 1 Hour Limit |
| ------ | ---------------------------------------- | -------------- | ------------ |
| POST   | `/api/projects/*/target/*/invalidation/` | 15             | 100          |

### Default Rate Limits

| Method              | Endpoint                          | 1 Minute Limit | 1 Hour Limit |
| ------------------- | --------------------------------- | -------------- | ------------ |
| GET                 | All endpoints combined.           | 1000           | N/A          |
| POST, PATCH, DELETE | All remaining endpoints combined. | 100            | N/A          |

## Read-Only Mode During Maintenance

During planned maintenance windows, the Managed Runtime API rejects write requests (POST, PUT, PATCH, DELETE) with an HTTP `503 Service Unavailable` response and error code `service_read_only`. Read requests (GET) continue to work normally. Retry write requests after the maintenance window concludes.

## Next Steps

Now you’re familiar with what the API can do—and even made some sample requests!

To learn more about the API, refer to the [API Specification](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=Summary).

The Open API schemas for the API are available at:

- **MRT Admin:** https://cloud.mobify.com/api/schema.json
- **MRT B2C Config:** https://cloud.mobify.com/api/cc/b2c/schema.json

<!-- document id=9e9a8b095f548ec019d25438a9bf19f37512d9466b0c28268e40c318aeded824 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/mrt-overview.md -->

# Managed Runtime Overview

[Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md) provides the infrastructure to deploy, host, and monitor your PWA Kit storefront.

**important:** Managed Runtime only supports applications created from a PWA Kit template. The source code for the available templates can be found in the `template-*` folders in the [PWA Kit repository](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages) on GitHub.

This guide covers the main parts of Managed Runtime and how to access it.

**important:** Before you can use Managed Runtime and Runtime Admin, ask your B2C Commerce administrator to add one of these roles to your account in Account Manager: **Managed Runtime User** or **Managed Runtime Admin**.


## Environments

An **environment** is the term used to describe all of the cloud infrastructure and configuration values for a particular storefront hosted by Managed Runtime. Environments are used to separate your production storefront from other storefronts that are deployed for other purposes, such as development or testing.

**note:** In the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary), environments are called “targets,” but both terms refer to the same thing.

Because environments run on highly efficient microservices that automatically scale up and down, you can create as many environments as you need at no additional cost. For example, you could create a short-lived environment dedicated to a single agile development sprint or for a single user story within that sprint. When you no longer need an environment, we encourage you to delete them.

### Production Environments

Environments marked as production are prioritized for monitoring by the Salesforce Support team and receive additional internal monitoring. Non-production environments have lower capacity limits, reflecting their use for development and testing traffic rather than live storefront traffic. To mark an environment as a production, you have two choices:

1. Use the Runtime Admin tool. Step-by-step instructions for creating an environment or editing an existing environment are found in the [Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#environments) section of the Administration guide.
2. Use the Managed Runtime API. The [projects_target_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_create) and [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) endpoints both feature the `is_production` parameter. To mark an environment as production with these endpoints, set `is_production` to `true`.

**important:** By default, organizations have a production environment limit of 0. Before going live, contact Support to increase your production environment limit.

Marking an environment as production automatically turns on two additional features. These features can't be enabled or disabled independently of the production flag:

- **Production Tier Capacity**: Higher concurrency limits and traffic capacity for production-scale shopper load.
- **Uptime Monitoring & Alerts**: Continuous monitoring across all serving regions, with alerts when issues are detected.

Starting September 29, 2026, an environment can be marked as production only if it's associated with a Staging or Production B2C Commerce instance. Associate your production environments with a Staging or Production instance now to avoid disruption. See [Edit Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#edit-environment-settings).

Marking an environment as production doesn't affect access to Log Center logs and metrics. Log Center logs and metrics can be enabled for any environment associated with a B2C Commerce instance, regardless of the production flag. See [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.md#debug-using-log-center).

## Bundles

The storefront code that runs on an environment is called a **bundle**. Use the developer tools included in PWA Kit to generate a bundle and push it to Managed Runtime.

**note:** A bundle is a snapshot of your code at a specific point in time. It’s _immutable_: After a bundle has been created, it can’t be changed. Having this complete and accurate history of bundles makes troubleshooting deployments easier.

After pushing the bundle, you can use the Runtime Admin or Managed Runtime API to designate that bundle as “deployed.” Each project can have multiple bundles, but each environment can have only one bundle that's designated as deployed. You can change which bundle is designated as deployed at any time. For more information, see [Push and Deploy Bundles](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.md).

## Projects and Organizations

To help you manage multiple environments, each environment also belongs to a **project** and each project belongs to an **organization**. An organization can contain multiple projects for multiple storefronts and each project can contain multiple environments. A Managed Runtime user can belong to multiple organizations to separate different work streams.

Each organization can have a maximum of 100 total environments. By default, organizations have a production environment limit of 0. To raise these limits, contact your Salesforce Support representative.

Organizations and user organization membership is determined by settings in Account Manager. A user can belong to an organization as either a member or an admin. Members can only interact with the projects in Managed Runtime that they’ve been assigned a project role to. Admins can interact with all the projects within an organization.

**important:** To assign a user the admin organization membership, contact Salesforce Support.

## Users, Abilities, and Roles

All users must be assigned the `Managed Runtime User` or `Managed Runtime Admin` via [Account Manager](https://account.demandware.com) for accessing Managed Runtime.

### Organization Roles and Permissions

Any user can have the following capabilities for a Managed Runtime organization:

- **Browse:** View all projects for an Organization.
- **Certificate:** View or manage TLS Certificates for an organization.

### Project Roles and Permissions

Any user can have the following capabilities for a Managed Runtime project:

- **Browse:** View the project in Runtime Admin.
- **Manage Redirects:** Manage redirects for the project. Please review the [Redirects documentation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html?q=Redirects#redirects) to learn more.
- **Deploy:** Deploy new bundles or revert the deployment to an older bundle.
- **Manage Team:** View, add, invite, remove, and edit the roles of team members for the project.
- **Access Logs:** Tail logs across all environments.
- **View and Manage Environment Variables:** See and manage environment variables in each environment. See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

Each user is assigned a project role that determines which abilities they have. (A user can only have _one_ role.) Project roles can be assigned to any user within an organization.

The following table shows which abilities are associated with each project role:

| Project Role | Browse | Manage Redirects | Deploy | Manage Team | Access Logs | View and Manage Environment Variables |
| :----------- | :----- | :--------------- | :----- | :---------- | :---------- | :------------------------------------ |
| Admin        | Yes    | Yes              | Yes    | Yes         | Yes         | Yes                                   |
| Developer    | Yes    | Yes              | Yes    | No          | Yes         | Yes                                   |
| Marketer     | Yes    | Yes              | No     | No          | No          | No                                    |
| Viewer       | Yes    | No               | No     | No          | No          | No                                    |

## App Server

Within each Managed Runtime environment, the [React](https://reactjs.org/) app in the published bundle runs inside a [Node.js](https://nodejs.org/) environment. To respond to page requests and render the results, we use the [Express](https://expressjs.com/) web framework with the help of PWA Kit’s [rendering](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/rendering.md) and [routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.md) systems. We call this combination of React, Node, and Express the **App Server**. (Although, technically speaking, the App Server runs on “serverless” technology.) The App Server is optimized to run on cloud infrastructure that offers low computing costs, high availability, fast rendering, and massive scaling capacity.

Because PWA Kit’s rendering and routing system handles the differences between local development environments and Managed Runtime environments, your code runs in a predictable way when you deploy it. This predictability unlocks your development team’s productivity by encouraging them to deploy bundles more frequently.

Currently, the App Server supports Transport Layer Security (TLS) versions 1.2 and greater.

### Environment Variables

Code running on the App Server has access to the following environment variables:

- `DEPLOY_TARGET`: ID of the environment.
- `EXTERNAL_DOMAIN_NAME`: The domain name set on the environment.
- `MOBIFY_PROPERTY_ID`: ID of the project that the environment belongs to.

## Edge Services

Supporting the app server are several edge services, including:

- A web application firewall (WAF) to protect your environments from attackers
- A proxy server to speed up API requests
- A content delivery network (CDN) to cache requests and speed up page loading
- Edge functions that process requests and handle redirects

The proxy server and CDN are covered in detail in our guide to [Proxying Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md). The edge function called the request processor is covered in our guide to [Maximizing Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.md).

Managed Runtime’s edge services are strategically distributed throughout our public cloud infrastructure. Each service is located as close to the user as possible for faster performance.

## Admin Tools

To manage the settings for your organizations, projects, environments, and bundles, we offer two different tools:

1.  The [Managed Runtime Admin](https://runtime.commercecloud.com/), a web-based UI.
2.  The [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references?meta=managed-runtime-api:Summary), a REST API that offers the same functionality as the web-based tool and some additional capabilities.

Use the Runtime Admin tool for routine tasks, such as deploying a new code bundle to an environment. Use the API whenever you need programmatic control, such as automatically creating an environment as part of a continuous integration script.

The admin tools give you a self-serve way to configure many settings, including:

- Allowed IP addresses
- Allowed access control headers
- Currently deployed bundle
- Deployment region
- Proxies
- Redirects
- User permissions
- Production environment flag

Access to the admin tools is controlled with Account Manager roles and an API key. For continuous integration (CI) and continuous delivery (CD) processes, dedicated bot users with their own API keys are typically provisioned by your organization.

Fun fact: Like your storefront, the Runtime Admin tool is a headless React app that is deployed to Managed Runtime.

## Constraints

While building your storefront, keep the following constraints of Managed Runtime environments in mind:

### Environments

- Environments only respond to requests whose HTTP `Host` header matches their External Hostname set in Runtime Admin.
- A hostname can be set as the External Hostname for only one environment at a time. Setting a hostname that's already in use by another environment fails.
- The path `/` only accepts HTTP GET requests.
- Request and response size can’t exceed 6 MB.
- The maximum size of the HTTP request line and headers is 10240 bytes. Requests exceeding this size return an [HTTP 413 Content Too Large](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413).
  - Of the 10,240 bytes, 1,500 bytes are reserved for internal use, 1,800 bytes for authorization headers, and 1,000 bytes for Salesforce B2C Commerce API (SCAPI). 5,940 bytes are left for custom request headers, including cookies.
- Cookies, including the HTTP request `Cookie` and HTTP response `Set-Cookie` header aren't supported by default. They can be enabled by setting the `allow_cookies` attribute on an environment with the [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) endpoint. You can also enable cookies in the [Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#edit-environment-settings) in [Runtime Admin](https://runtime.commercecloud.com/). Cookies are supported in PWA Kit version 3.1.0 or greater. See [Personalize with Cookies](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/personalize-with-cookies.md).
- Requests with headers that start with `_` are not supported. These requests will be dropped.
- HTTP requests originating from Managed Runtime environments don't use fixed IP addresses. To allow list requests from the App Server use the [AWS IP Range](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html) for `EC2`. To allow list requests from Proxies, use `CLOUDFRONT_ORIGIN_FACING`.
- The path prefix `/mobify` is reserved for managed endpoints. These endpoints include:
  - `/mobify/ping`: Returns an HTTP 200 response code when the environment is operating correctly.
  - `/mobify/redirect/$path`: Returns a similar response as [projects_target_redirect_retrieve](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_retrieve).
  - `/mobify/proxy/$name`: Returns a response from a [proxy](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md).
- You can bypass the CDN cache using the HTTP request header: `x-mobify-cachebreaker: 1`
- Environment IP Allowlists support up to 250 IP addresses. This limit can't be raised.
- Environment access control headers support up to 2 headers, or up to 4 for Storefront Next environments. Each header:
  - Can contain up to 128 characters.
  - Can be a combination of alphanumeric characters and - and \_ characters
  - See [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#access-control-headers).

### Rendering

- The execution time for App Server requests is limited to 20 seconds for production environments and 16 seconds for non-production environments. After this time, an HTTP 502 is returned.
- Unhandled promise rejections break app rendering.

### Deployments

- The maximum size for bundles is 400 MB and the maximum size of all `ssr_only` and `ssr_shared` files within the bundle is 249 MB.
- Static assets that can be uploaded and served are limited to the following content types: `application/javascript`, `application/json`, `image/png` ,`image/gif`, `image/jpeg`, `image/svg+xml`, `image/webp`, `text/css`, `text/plain` and fonts (`ttf`, `woff`, `woff2`, `otf`, etc). All other content types need to be served by an external system.

### Proxies

Managed Runtime Proxies have different [constraints](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.html#constraints).

## Availability

You can subscribe to updates regarding the availability of Managed Runtime services on [Salesforce Status](https://status.salesforce.com/products/B2C_Commerce_Cloud).

During some maintenance windows, Managed Runtime enters a read-only mode: write requests to the Managed Runtime API are rejected while read requests continue to work normally. See [Read-Only Mode During Maintenance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.md#read-only-mode-during-maintenance).

## Next Steps

Now that you have an overview of the main parts of Managed Runtime, it’s time to get hands-on! A good place to start is the [Push and Deploy Bundles](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.md) guide.

**important:** Before you can use Managed Runtime and Runtime Admin, ask your B2C Commerce administrator to add one of these roles to your account in Account Manager: **Managed Runtime User** or **Managed Runtime Admin**.


## See Also

- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md)
- [Managed Runtime API guide](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.md)
- [Managed Runtime API reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary)
- [Video: How to Use the Managed Runtime Admin Tool | Configure PWA Kit](https://www.youtube.com/watch?v=zxE1SD3FuzM)

<!-- document id=8c6d8dd0f5ddd5f6cd8b373b2254b8e11a97717c9690d1e6389b2b65c35996ef url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-overview.md -->

# Managed Runtime Overview for Business Manager

Managed Runtime provides the cloud infrastructure to deploy, host, and monitor Storefront Next. Managed Runtime organizes storefronts into projects and environments for testing code in isolation before promoting to production. Managed Runtime also includes a scalable serverless app server, a web application firewall, and admin tools for managing bundles, deployments, redirects, and user permissions.

**important:** Managed Runtime only supports applications created from a Storefront Next template and the Retail React App template for Composable Storefronts. The source code for the Storefront Next template is in the [storefront-next-template](https://github.com/SalesforceCommerceCloud/storefront-next-template/tree/latest/src) GitHub repository.

## App Server

The app server on Managed Runtime is a scalable serverless Node.js runtime environment for your storefront. Each published bundle, which contains a Storefront Next app, runs within a Managed Runtime environment on the app server. The Storefront Next app is a [React](https://reactjs.org/) app that's built on [React Router 7](https://reactrouter.com/) in framework mode.

Because the Storefront Next rendering and routing system handles the differences between local development and Managed Runtime environments, your code runs predictably when you deploy it. This predictability helps your development team deploy bundles more frequently.

The app server supports Transport Layer Security (TLS) version 1.2 and later.

## Web Application Firewall (WAF)

The eCDN that serves the storefront includes a web application firewall (WAF). WAF protects the storefront environments against malicious traffic, bot attacks, and vulnerabilities such as SQL injection and cross-site scripting (XSS). WAF filters, monitors, and blocks HTTP or HTTPS traffic to and from a web application.

## Storefronts vs Projects

When you create Storefront Next in Business Manager, or when you link an existing Storefront Next or Composable Storefront, the storefront in Business Manager represents the collection of resources that are required to develop, deploy, and run the storefront on B2C Commerce. These resources include the auto-generated Shopper Login and API Access Service (SLAS) credentials that are used for the B2C Commerce API (SCAPI), the Account Manager credentials that are used for B2C clients, such as the B2C CLI. Other resources include the storefront primary and any additional environments, storefront settings, and deployments. In Runtime Admin, a project groups multiple environments within an organization. The storefront maps to a corresponding project in Managed Runtime for deploying and hosting the storefront code on Salesforce public cloud infrastructure. The storefront setup in Business Manager automatically creates a project for the storefront.

## Environments

An _environment_ describes all the cloud infrastructure and configuration values for a storefront hosted by Managed Runtime. Environments separate your production storefront from storefronts deployed for other purposes, such as development or testing. The Storefront Next setup flow in Business Manager creates an environment for the new storefront. Admins can also create more environments for the storefront in Business Manager. Environments created in Business Manager are behind an embedded content delivery network (eCDN).

**note:** In the [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary), environments are called _targets_.

Because environments run on highly efficient microservices that automatically scale up and down, create as many environments as you need at no additional cost. For example, create a short-lived environment dedicated to a single agile sprint or user story. When you no longer need an environment, delete it.

### Production Environments

Environments marked as production are prioritized for monitoring by the Salesforce Support team and receive additional internal monitoring. Production environments get higher concurrency and capacity limits than non-production environments used for development and testing. The higher limits ensure that the production environment can handle the volume of live storefront traffic. To mark an environment as production, choose one of these methods:

- Use the Runtime Admin tool. For instructions on creating or editing an environment, see [Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md#environments) in [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md).
- Use the Managed Runtime API. The [projects_target_create](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_create) and [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) endpoints both include the `is_production` parameter. To mark an environment as production with these endpoints, set `is_production` to `true`.
- If your B2C org is enrolled in the Developer Workspace Beta, mark the environment as production by clicking **Production Status** in environment settings. When you turn on Mark as Production, dependent settings are automatically enabled: Production Tier Capacity, Uptime Monitoring & Alerts and Real User Monitoring (RUM) Dashboard Display.

**important:** Before going live, contact Salesforce Support to get a production environment allocation. By default, organizations aren't allocated any production environments.

Marking an environment as production turns on two more features. The production setting controls these features and you can't manage them independently.

- **Production-Tier Capacity**: Higher concurrency limits and traffic capacity for production-scale shopper load.
- **Uptime Monitoring and Alerts**: Continuous monitoring across all serving regions, with alerts when issues are detected.

**important:** Starting September 29, 2026, you can mark an environment as production only if it's associated with a staging or production B2C Commerce instance. Associate your production environments with a staging or production instance now to avoid disruption. See [Edit Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md#edit-environment-settings).

Marking an environment as production doesn't affect access to Log Center logs and metrics. Log Center logs and metrics can be enabled for any environment associated with a B2C Commerce instance, regardless of the production flag. See [View Logs in Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-logging.md#view-logs-in-log-center).

### Environment Variables

Code running on the app server has access to these environment variables:

- `DEPLOY_TARGET`: ID of the environment.
- `EXTERNAL_DOMAIN_NAME`: The domain name set on the environment.
- `MOBIFY_PROPERTY_ID`: ID of the project that the environment belongs to.

For more information, see [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md).

## Bundles

The storefront code that runs on an environment is called a _bundle_. When you create a storefront in Business Manager, the storefront is bundled and deployed to a default MRT environment. Alternatively, use the CLI to deploy a bundle. A bundle is a snapshot of your code at a specific point in time. It’s _immutable_: After a bundle is created, it can’t be changed. A complete and accurate history of bundles makes troubleshooting deployments easier.

To deploy a bundle with the `sfnext` CLI, see [Deploy Storefront Next to Managed Runtime (MRT) with Business Manager Resources](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md). To deploy a bundle with the B2C CLI, see [Deploy](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/storefront-next.html#step-5-deploy) in the Agentic B2C Developer Toolkit documentation.

After pushing the bundle, use the Runtime Admin or Managed Runtime API to designate the bundle as “deployed.” Each project can have multiple bundles, but each environment can have only one bundle that's designated as deployed. Change which bundle is designated as deployed at any time.

## Administration Tools

To manage the settings for your organizations, projects, environments, and bundles, use the Runtime Admin tool for routine tasks, such as deploying a code bundle to an environment. Use the B2C CLI or the Managed Runtime API for programmatic control, such as automatically creating an environment as part of a continuous integration script.

- The [Managed Runtime Admin](https://runtime.commercecloud.com/), a web-based UI.
- The B2C CLI, which offers commands for scripted automation. See [MRT Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html) in the Agentic B2C Developer Toolkit.
- The Managed Runtime API, [mrt-admin](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary) and [mrt-b2c-config](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=Summary), is a collection of REST APIs that offer the same functionality as the web-based tool and some additional capabilities.

Use the admin tools to configure many settings, including:

- Currently deployed bundle
- Redirects
- User permissions
- [Production environment flag](#production-environments)

Access to the admin tools is controlled with Account Manager roles and an API key. For continuous integration (CI) and continuous delivery (CD) processes, dedicated bot users with their own API keys are typically provisioned by your organization.

## Constraints

While building your storefront, keep these constraints in mind.

### Rendering Constraints

- The execution time for App Server requests is limited to 20 seconds for production environments and 16 seconds for non-production environments. After this time, an HTTP 502 is returned.
- Unhandled promise rejections break app rendering.

### Deployment Constraints

- The maximum size for bundles is 400 MB and the maximum size of all `ssr_only` and `ssr_shared` files within the bundle is 249 MB.
- Static assets that can be uploaded and served are limited to these content types: `application/javascript`, `application/json`, `image/png`, `image/gif`, `image/jpeg`, `image/svg+xml`, `image/webp`, `text/css`, `text/plain` and fonts (`ttf`, `woff`, `woff2`, `otf`, etc). All other content types need to be served by an external system.

### Environment Constraints

See [Environment Constraints](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-environments.md).

### Cookies

Cookies, including the HTTP request `Cookie` and the HTTP response `Set-Cookie` header, are enabled by default.

## Availability

To be informed of the availability of Managed Runtime services, subscribe to service updates on [Salesforce Status](https://status.salesforce.com/products/B2C_Commerce_Cloud).

During some maintenance windows, Managed Runtime enters a read-only mode: write requests to the Managed Runtime API are rejected while read requests continue to work normally. See [Read-Only Mode During Maintenance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-api.md#read-only-mode-during-maintenance).

## See Also

- [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md)
- [Managed Runtime API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-api.md)
- Managed Runtime API reference: [mrt-admin](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=Summary) and [mrt-b2c-config](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-b2c-config?meta=Summary)
- Agentic B2C Developer Toolkit: [MRT Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html)

<!-- document id=54c466fdb2e744c6bf25a31f4b729aa6b5ac9484e671e12f927796dbec407922 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-release-notes.md -->

# Managed Runtime Release Notes

Learn about Managed Runtime (MRT) features.

**tip:** To check out Storefront Next release notes, see [Storefront Next Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-release-notes.md).

<!--
TEMPLATE FOR RELEASE NOTE

## <Date> - vx.y.z

### <Release note title>

<Intro paragraph introduces the what and why>

**Where**: (Optional) Indicate where your feature or change is available in case it requires other products or features turned on, for example, if a feature is available in a specific template.
**When**: (Optional) If your feature or change won't be available as soon as the release rolls out, note that here..
**Who**: (Optional) If your feature is available only to users with certain licenses or perms, include that info in the Who section.
**Why**: (Optional) Use this section to go into more detail about your feature or change and why it matters to customers. The Why section is a great place for content like examples and screenshots. Including a screenshot? Be sure to add some introductory text. *NOTE*: If you’ve said everything you need to about your feature’s benefits and use cases in your intro, simply delete this section.
**How**: (Optional) Provide a brief, high-level overview of the steps involved in getting your feature up and running. Or, if you're writing about an admin- or dev-focused feature or change, you can include a brief, high-level overview of how to use that feature. Don’t include comprehensive, step-by-step instructions here. Put that info in the topic and link to it in your See Also section.

-->

## 10/6/2026 - B2C Commerce 26.10

### Manage the Storefront Development Workflow in Business Manager (Beta)

With the Developer Workspace beta, manage storefronts in one place. Handle storefront environments, environment variables, redirects, and bundle deployments from the storefront's page in Business Manager. Manage these Managed Runtime resources in Business Manager instead of Runtime Admin as part of the storefront development lifecycle. Monitor the performance of staging and production environments for real-world usage, including Core Web Vitals. Admins assign read, write, and delete permissions for each storefront's resources, such as environments, environment variables, deployments, and redirects. On the Management Interface page, admins select the user interface and the API for that storefront. Admins select the legacy Runtime Admin interface or the new Business Manager interface.

**important:** Developer Workspace is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

**Where**: This feature applies to Storefront Next and Composable Storefront that are linked to Business Manager for B2C Commerce.

**When**: This feature is available in B2C Commerce 26.10.

**How**: To turn on the Developer Workspace beta in Business Manager, in the Search box, enter `Feature Switches`, and then select **Feature Switches** from the suggested result. Click **Enable Developer Workspace (Beta)**, and then click **Apply**.

![Storefront detail page showing available environments](https://developer.salesforce.com/docs/media/sfnext/sfnext-storefront-overview-tab.png '{"class": "image-xl"}')

## Automate Your Storefront Administration with the New B2C Commerce API (SCAPI)

The Managed Runtime SCAPI-based APIs offer expanded administration tasks for managing Storefront Next and Composable Storefront (PWA Kit). Provision Storefront Next, update, edit, and delete storefronts. Create and manage environments, environment variables, access control headers, and redirects. Also, upload bundles and start deployments. The new APIs offer ease of setup because you use the same Account Manager API authorization as other SCAPI endpoints that you're already familiar with. No need for creating a separate Managed Runtime API key. Also, they streamline your storefront development lifecycle and CI/CD by enabling automation with a bot user with SCAPI authentication.

**Where**: This feature applies to Storefront Next and Composable Storefront for B2C Commerce.

**When**: This feature is available in B2C Commerce 26.10.

**See Also**

- [B2C Commerce API: Storefronts](https://developer.salesforce.com/docs/commerce/commerce-api/references/storefronts?meta=Summary)
- [B2C Commerce API: Environments](https://developer.salesforce.com/docs/commerce/commerce-api/references/environments?meta=Summary)
- [B2C Commerce API: Deployments](https://developer.salesforce.com/docs/commerce/commerce-api/references/deployments?meta=Summary)

### Restrict SCAPI Access to Managed Runtime Traffic

Available starting with B2C Commerce 26.10, the **Managed Runtime SCAPI Request Identification** feature switch locks down the Salesforce B2C Commerce API (SCAPI) so that it accepts requests only from your Managed Runtime (MRT) environments. Enabling the switch attaches a shared secret header to every request MRT forwards to SCAPI, so SCAPI's eCDN zone can distinguish genuine MRT traffic from a direct request sent to SCAPI from anywhere else, including one that spoofs MRT's IP range or user agent. The SCAPI Identity Header (SIH) applies at the MRT platform level and protects Storefront Next automatically, without Storefront Next configuration. After you enable the switch, add your own custom firewall rule to block or log direct SCAPI traffic that doesn't carry the header.

**Where:** This change applies to Managed Runtime with Storefront Next.

**See Also**

- [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-scapi-request-identification.md)

## 10/1/2026

### Managed Runtime Read-Only APIs During Maintenance

During planned maintenance windows, Managed Runtime APIs reject write requests (POST, PUT, PATCH, and DELETE) with an `HTTP 503` response, error code `service_read_only`, and detail message `Service is in READ_ONLY mode`. Read requests (GET) continue to work normally.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

## 8/25/2026

### 20-Second Rendering Timeout Now Strictly Enforced

The execution time for App Server requests has always been documented as limited to 20 seconds, but this limit wasn't strictly enforced, and requests could previously run for up to 30 seconds. Managed Runtime now enforces the documented 20-second limit. After this time, Managed Runtime returns an HTTP 502. This protects your storefront from slow or hung backend calls that would otherwise tie up rendering capacity. If your backend integrations typically respond in under 20 seconds, this change requires no action.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

### Non-Production Environments Now Have Lower Capacity Limits

Non-production Managed Runtime environments now have lower capacity limits, reflecting their use for development and testing traffic rather than live storefront traffic. Environments marked as production continue to receive full capacity and additional internal monitoring by Salesforce. Previously, there was no difference in capacity between production and non-production environments.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

**See Also**

- [Composable Storefront: Production Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/mrt-overview.md#production-environments)

### Log Center Logs and Metrics No Longer Require the Production Flag

Log Center logs and Log Center metrics no longer require an environment to be marked as production. Enable either setting independently for any environment associated with a B2C Commerce instance, under **Observability** in Environment Settings.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

**See Also**

- [Storefront Next: Log Center Logs and Metrics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#log-center-logs-and-metrics)
- [Composable Storefront: Log Center Logs and Metrics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#log-center-logs-and-metrics)

### Coming September 29, 2026: Production Flag Will Require a Staging or Production B2C Commerce Instance

Starting September 29, 2026, you can mark an environment as production only if it's associated with a Staging or Production B2C Commerce instance. Environments associated with a development or sandbox instance, or with no instance association, can't be marked as production after this date.

Associate your production environments with a Staging or Production B2C Commerce instance now, ahead of the deadline.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

**See Also**

- [Storefront Next: Edit Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-administration.md#edit-environment-settings)
- [Composable Storefront: Production Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/mrt-overview.md#production-environments)
- [Composable Storefront: Edit Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#edit-environment-settings)

### Access Control Headers Limit Raised to 4 for Storefront Next Environments

Storefront Next environments can now have up to 4 access control headers, up from 2. This gives you more headroom to support vanity domains, because each domain typically needs its own header. The limit for other Managed Runtime environments remains 2. The header Salesforce configures for your default domain can't be deleted; add a separate header for each vanity domain instead.

**Where:** This change applies to Managed Runtime with Storefront Next.

**See Also**

- [Composable Storefront: Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/managed-runtime-administration.md#access-control-headers)

### Protected Storefront Now Enabled by Default

Protected Storefront is now enabled by default for new Managed Runtime environments, so you no longer need to contact Salesforce Support to turn it on before restricting access to a storefront under development. Existing environments are unaffected.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

**See Also**

- [Storefront Next: Limit Access to a Storefront Under Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-protect-storefront.md)
- [Composable Storefront: Limit Access to a Storefront Under Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/protect-storefront.md)

### On-Demand Sandbox Instances Now Get Default eCDN Security Rules for Storefront Next

When you create a Storefront Next storefront on an On-Demand Sandbox (ODS) instance, Business Manager now adds default security rules to the instance's default eCDN zone: custom firewall rules that block known AI crawlers and common vulnerability-probe paths, plus a rate limiting rule that blocks IP addresses sending excessive requests. The default zone is shared across every storefront on the instance, so these rules apply to all storefronts hosted there, not only the one that triggered their creation. ODS instances have less capacity than production, and these rules keep them responsive during development by limiting automated bot and crawler traffic.

**Where:** This change applies to On-Demand Sandbox (ODS) instances with Storefront Next.

**How:** If a rule blocks traffic you expect to allow, adjust its exclusions or rate limit rather than disabling it — see [Adjust or Disable a Rule](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ods-security-rules.md#adjust-or-disable-a-rule).

## 7/28/2026

### SSR Bundle Size Limit Lowered to 247 MB

The maximum combined size of `ssr_only` and `ssr_shared` files in an Server-Side Rendering (SSR) bundle is now 247 MB, down from 249 MB. This reserves headroom for the fixed overhead Managed Runtime adds to every bundle, so bundles near the previous limit don't fail during publish after upload. Check your bundle size before pushing if you're close to the limit.

**Where:** This change applies to Managed Runtime with Composable Storefront and Storefront Next.

**See Also**

- [Deploy Storefront Next to Managed Runtime (MRT)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-push-mrt-auto.md)

<!-- document id=3ac9e88c294070989ada51930908fba42e2d92aabb4909f892d553a8006bfb94 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/hybrid-auth-manual-setup.md -->

# Manual Hybrid Auth Setup (PWA Kit, SFRA/SiteGenesis)

Use manual setup for PWA Kit (Composable Storefront), SFRA/SiteGenesis, headless storefronts, or any storefront where you provision Managed Runtime (MRT), SLAS, and eCDN yourself.

**note:** Storefront Next storefronts can use [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-quick-start.md) instead, which provisions MRT and eCDN for you.

Complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) (SLAS, session bridging, and Business Manager) before you begin.

## Are You Starting Fresh or Coming from an Existing Setup?

### Fresh Setup

Set up the storefront and its supporting services from scratch:

1. **Set up Managed Runtime (MRT).** Create a project and environment for your headless storefront.
2. **Set up SLAS.** Create a SLAS client and add the `sfcc.session_bridge` scope (see [Shared Hybrid Auth Setup, Steps 1–2](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-1-set-up-a-slas-client)).
3. **Set up SFRA/SiteGenesis.** Deploy your SFRA or SiteGenesis cartridges.
4. **Link Business Manager to MRT.** Connect your Business Manager instance to the MRT environment.

Then follow the implementation guide for your architecture:

- PWA Kit / Composable Storefront: [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md)
- Headless storefront: [Headless Storefront + SFRA Hybrid Setup](#headless-storefronts--sfrasitegenesis)

### Existing Setup

If MRT, SLAS, and SFRA/SiteGenesis are already in place:

1. **Link Business Manager to MRT.** Connect your existing Business Manager instance to the MRT environment, then continue with the instance-type steps below.

For an SFRA/SiteGenesis-only storefront, see [SFRA and SiteGenesis Hybrid Setup (Existing Customers)](#sfrasitegenesis-proper--hybrid-auth-session-extension-and-slas-setup).

## Set Up by Instance Type

Across all instance types, the Hybrid Auth configuration is the same: enable Hybrid Auth in Business Manager (see [Shared Hybrid Auth Setup, Step 4](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-4-configure-business-manager)) and set the hybrid environment variables for your Managed Runtime (MRT) or local runtime. Only the routing setup differs by environment. Configure each instance type as follows.

**note:** These instance-type steps apply to storefronts that include a headless or Managed Runtime (MRT) app (Storefront Next, PWA Kit, or a custom headless storefront). For an **SFRA/SiteGenesis-only** storefront, you don't need MRT environment variables or eCDN routing—the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) is your complete configuration. See [SFRA/SiteGenesis Proper + Hybrid Auth](#sfrasitegenesis-proper--hybrid-auth-session-extension-and-slas-setup).

### PIG (Primary Instance Group)

1. Enable Hybrid Auth in Business Manager.
2. Enable the hybrid environment variables for MRT.
3. Configure eCDN routing using the Business Manager UI. See [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md).

### ODS (On-Demand Sandbox)

1. Enable Hybrid Auth in Business Manager.
2. Enable the hybrid environment variables for MRT.
3. Configure eCDN routing using the Business Manager UI. See [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guides/ecdn-rules-for-phased-headless-rollout.md).

### Localhost (Local Development)

1. Enable Hybrid Auth in Business Manager for the target sandbox/site.
2. Enable the hybrid environment variables for the local runtime.
3. Configure routing with the local hybrid proxy instead of eCDN, which isn't available locally. For PWA Kit, see [Set Up Hybrid Locally for Local Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md#set-up-hybrid-locally-for-local-development).

For the per-environment routing deltas and the step-by-step guide for your architecture and instance type, see [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-environment-matrix.md).

## SFRA/SiteGenesis Proper + Hybrid Auth (Session Extension and SLAS Setup)

Use Hybrid Auth on an SFRA or SiteGenesis storefront for SLAS benefits—such as longer sessions and federated login—without a headless runtime.

**important:** This guide is for existing SFRA/SiteGenesis customers only. For new (greenfield) implementations, use Storefront Next with [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-quick-start.md), or PWA Kit with [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

Use this path when maintaining or incrementally modernizing an existing SFRA or SiteGenesis storefront.

For an SFRA/SiteGenesis-only storefront, the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) is the complete instruction set—the steps below are just the SFRA/SiteGenesis-specific sequence and map to those shared steps. You don't need the other Manual Setup sections ([Fresh or Existing Setup](#are-you-starting-fresh-or-coming-from-an-existing-setup) Managed Runtime provisioning and the [Set Up by Instance Type](#set-up-by-instance-type) routing steps) unless you later add a headless runtime.

### Scope

- Keep existing SFRA/SiteGenesis storefront operational.
- Enable Hybrid Auth to replace Plugin SLAS.
- Prepare for phased migration to headless storefront components over time.

### High-Level Steps

1. Enable Hybrid Auth in Business Manager for the site. (Shared Hybrid Auth Setup, Step 4)
2. Configure the SLAS client and session bridging scope. (Shared Hybrid Auth Setup, Steps 1–2)
3. Remove Plugin SLAS-specific configuration where applicable. (Shared Hybrid Auth Setup, Steps 5–6)
4. Validate cross-site session extension and token synchronization.
5. Introduce headless routes gradually using eCDN rules. (Only when adding a headless runtime.)

Steps 1–3 map to the architecture-neutral [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md). For the legacy Plugin SLAS phased-rollout approach, see [Configure a Hybrid Storefront with Plugin SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/phased-headless-rollouts.md).

**note:** For an **SFRA/SiteGenesis-only** storefront—using Hybrid Auth for SLAS benefits such as longer sessions and federated login, without a headless runtime—the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) is your complete configuration. No headless runtime configuration or eCDN routing is required. Step 5 applies only when you start moving routes to a headless storefront.

### Validate the Setup

After you complete the shared setup, confirm that Hybrid Auth is working on your SFRA/SiteGenesis storefront:

1. Log in as a registered shopper and confirm the session persists across SFRA/SiteGenesis pages without a re-login prompt.
2. Confirm session extension: registered and guest sessions persist for the refresh token TTL you configured in Business Manager, rather than expiring at the default storefront session timeout.
3. If you configured a third-party IDP or Social Login, complete a federated login and confirm the shopper is recognized on SFRA/SiteGenesis pages.
4. Confirm the SLAS authorization (JWT) and the B2C Commerce session (`dwsid`) stay synchronized—the shopper isn't logged out or forced to reauthenticate while browsing.

If you hit issues, see [Hybrid Auth Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-troubleshooting.md).

### Migration Recommendation

Treat this setup as a transitional state. As you modernize, adopt headless storefront components and follow the implementation guide for your target architecture:

- Storefront Next: [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid.md)
- PWA Kit / Composable Storefront: [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md)

For an intermediate step that keeps cart and checkout on SFRA while moving other routes to a headless runtime, see [Headless Storefronts + SFRA/SiteGenesis](#headless-storefronts--sfrasitegenesis).

## Headless Storefronts + SFRA/SiteGenesis

<!-- REVIEW(SME/eng): As of this writing there is no authoritative engineering source doc for the Headless + SFRA/SiteGenesis step-by-step instructions (confirmed as a TODO by the Hybrid Auth team). The steps below are synthesized from related guidance and are pending verification. Confirm the SLAS authentication flow, Set-Cookie/dwsid handling, the sfdc_dwsid header usage on SCAPI calls, and the route-ownership steps against the forthcoming source. -->

For transitional architectures where a custom headless storefront and SFRA/SiteGenesis both serve shopper traffic.

### When to Use This Path

- You are in a phased migration from SFRA/SiteGenesis to a custom headless storefront.
- You are not yet ready to move cart/checkout off SFRA/SiteGenesis.

This path is for headless storefronts that you build and host yourself (not Storefront Next or PWA Kit). If you use one of those frameworks, or you're starting a greenfield implementation, follow its dedicated guide instead:

- Storefront Next: [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid.md). For a greenfield build, use [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-quick-start.md).
- PWA Kit / Composable Storefront: [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md).

### Supported Scenario

- The headless storefront handles top-of-funnel and selected experiences.
- SFRA/SiteGenesis continues to serve cart, checkout, or other controller-based flows.
- Hybrid Auth synchronizes authentication and session state across both runtimes.

### Before You Begin

Complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) before configuring your headless storefront. These steps are the same for every architecture and instance type:

1. Create a SLAS client and add the `sfcc.session_bridge` scope. See [Shared Hybrid Auth Setup, Step 1](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-1-set-up-a-slas-client).
2. Enable session bridging. See [Shared Hybrid Auth Setup, Step 2](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-2-enable-session-bridging).
3. Enable Hybrid Auth in Business Manager. See [Shared Hybrid Auth Setup, Step 4](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-4-configure-business-manager).

### Step-by-Step Setup

#### Step 1: Authenticate Shoppers with SLAS

In your headless storefront, use SLAS to obtain shopper access and refresh tokens. Store them as cookies so that they're shared with SFRA/SiteGenesis when the shopper crosses runtimes.

For the authentication flows and token handling, see the [Session Bridging Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guides/slas-session-bridge-overview.md).

#### Step 2: Respect SLAS Set-Cookie Responses

SLAS session-bridge token responses return cookies—including a `dwsid`—through the `Set-Cookie` header. Make sure your headless storefront applies these cookies to the shopper's browser so that B2C Commerce and SLAS sessions stay linked across SFRA/SiteGenesis and your headless pages.

#### Step 3: Send the `sfdc_dwsid` Header on SCAPI Calls

For non-PWA Kit headless storefronts, when the `dwsid` cookie exists, include the `sfdc_dwsid` header with the `dwsid` cookie value on all SCAPI calls. This header keeps the shopper's B2C Commerce session aligned with SCAPI requests from your headless runtime.

#### Step 4: Configure Route Ownership Between Headless and SFRA

Decide which paths your headless storefront serves and which stay on SFRA/SiteGenesis: route headless-owned paths to your headless origin, and keep the remaining paths on SFRA/SiteGenesis.

- If your headless app runs on Managed Runtime (MRT), apply the split using the per-instance routing in [Set Up by Instance Type](#set-up-by-instance-type): eCDN MRT routing rules via the Business Manager UI for PIG and ODS, or the local proxy for localhost.
- If your headless app runs on a different origin, use your CDN's origin-routing equivalent with the same path split.

For the per-environment routing mechanics, see [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-environment-matrix.md). For ready-to-use split patterns you can adapt, see [Canonical Routing Rules](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-environment-matrix.md#canonical-routing-rules).

#### Step 5: (Optional) Basket Merge and Shopper Context

- Review basket handling across runtimes in [Hybrid Storefront Basket Guidance](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-storefront-baskets.md#hybrid-storefront-best-practices-for-working-with-baskets).
- To carry shopper context (such as source code or geolocation) across runtimes, see [Shared Hybrid Auth Setup, Step 7](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-7-optional-set-shopper-context).

#### Step 6: Validate Cross-Runtime Navigation

1. Navigate from a headless page to an SFRA/SiteGenesis page (and back) and confirm the shopper stays logged in.
2. Confirm the session cookies (including `dwsid`) are shared across both runtimes.
3. Confirm SCAPI calls from the headless runtime include the `sfdc_dwsid` header that matches the `dwsid` cookie value.

If you hit issues, see [Hybrid Auth Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-troubleshooting.md).

## Next Steps

- If you added a headless or Managed Runtime (MRT) app, split routes between it and SFRA/SiteGenesis, and review the environment-specific deltas, in [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-environment-matrix.md).
- For an SFRA/SiteGenesis-only storefront (no headless runtime), no eCDN routing is required—the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) is your complete configuration.
- If you hit issues, see [Hybrid Auth Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-troubleshooting.md).

**See also:** Storefront Next storefronts can use [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-quick-start.md) instead. For how Hybrid Auth and its setup paths fit together, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md).

<!-- document id=a17ac75a250882842fa27af68303882abe781badd487607d471535c74f18b27f url=/developer/current/en-us/commerce-cloud/marketplace/guides/marketplace-toolkit-config.md -->

# Marketplace Integration Toolkit Configuration

We recommend creating a separate user for the integration to the Salesforce Org. You must follow the instructions on the Marketplace Managed Packaged documentation to correctly set up the permissions. You must also create a connected app in the org so you can authorize the toolkit.

The app must meet the following requirements:

- OAuth Settings enabled.
- Callback URL with `https://[url].herokuapp.com/Tenant/AuthorizeCallback` (dependent on your Heroku app).
- API, `refresh_token`, and `offline_access` OAuth Scopes.
- The value for "Refresh Token Policy" is "Refresh token is valid until revoked" when you click Manage.

Configuration instructions:

1. Access the Marketplace toolkit, and log in with your Admin user.

2. To add a Tenant, navigate to the "Tenants" page and click **Create New**.

3. Populate the Create Tenant form with the following required information:

   - Name: a name to identify this tenant.
   - IsEnabled: if the tenant is active or not.
   - Login: username of the user used to check the integration logs of this tenant inside the toolkit.
   - Password: tenant user password.
   - SFDCConsumentKey: The connected app Consumer Key.
   - SFDCConsumerSecret: The connected app Consumer Secret.
   - SFDCIsSandbox: If the app is in a Sandbox environment or not.

4. After creating your tenant, you're redirected to an Authorization page. Select **Authorize**, and follow the procedure to give the app permission (make sure that you log in to the org using the integration user).

   **tip:** For existing tenants, access this page from the option Authorize/ReAuthorize Salesforce App if you must refresh the access token.

5. Click **Authorize** to be redirected to the login page for Salesforce. Make sure to use the desired integration user login.

   You’re asked to authorize the app and redirected back to the toolkit, informing you that access is OK.

6. From the detail page of the tenant, retrieve the API User and API Password that is used to configure API Access in B2C Commerce.

7. With the Authorization in place, log out as the admin user and log in to the dashboard with the newly created tenant user.

   Here you can manage the integrations and force some actions like searching for updates to sync.

   **note:** Be aware that abusing this could lead to overcalling the SFDC API, and reaching governor limits.

<!-- document id=670d285094de047e9d0a377f08cae9bf8a367f2eaf19af39bdcc13a9a9a8472c url=/developer/current/en-us/commerce-cloud/marketplace/guides/marketplace-initial-setup.md -->

# Marketplace Integration Toolkit Initial Setup

The Marketplace Integration Toolkit is a tool used to connect a Salesforce org that has the marketplace managed package installed and a B2C Commerce instance to act as storefront. The Toolkit was built using .NET 6, and uses a Heroku Instance to host the app.

Besides the Heroku Instance, add-ons must be installed for Postgres and RabbitMQ. For deployment of the source code, a local Docker runtime and Heroku CLI are needed.

**important:** Salesforce does not provide support for the Commerce Marketplace Integration Toolkit. The Toolkit is provided as a technical reference that demonstrates how to integrate Commerce Marketplace with B2C Commerce. Adapt the Toolkit to work with other platforms.

## Heroku Setup

A new Heroku app must be created. Be advised that the dyno type can’t be Eco because the worker must be up 24/7.

The following add-ons must be added:

- CloudAMQP
- Heroku Postgres
- Heroku Scheduler (free)

  **note:** We don't recommend using the Eco tier due to [dyno sleeping](https://devcenter.heroku.com/articles/eco-dyno-hours#dyno-sleeping). Choose your dyno based on your expected load.

## Code Deploy

1. With the source code in hand, configure the Heroku CLI logging in with your account.
   [https://devcenter.heroku.com/articles/heroku-cli](https://devcenter.heroku.com/articles/heroku-cli)

2. Log in to the repository using `heroku container:login`.

3. To deploy the code, open a terminal in the root of the project and run the following commands:

   `heroku container:push web release worker_sfcc --recursive --context-path . --app <your_app>`

   `heroku container:release web release worker_sfcc —app <your_app>`

   If configured correctly, there are now 2 dynos in the Heroku app.

## Heroku Configuration

1. To obtain a passphrase, in the terminal run the following command:

   `heroku run tools/Atonit.Marketplace.Heroku.CommandLineTools create_encryption_key --app <your_app>`

2. Copy the passphrase, and create a Heroku Config Var with the name `ENCRYPTION_KEY`.

   This is your secret key for encryption. _DO NOT SHARE THIS PUBLICLY IN ANY SHAPE OR FORM_. Ideally, this value is only stored in the Heroku Config Var and can’t be changed without a database data clear after it’s in use.

3. Open the app in Heroku, and check if you successfully see the login page.

   **note:** Don’t proceed before configuring the Heroku Scheduler and creating the Admin SuperUser.

## Heroku Scheduler

Inside the Heroku Scheduler create the following configurations:

- `tools/Atonit.Marketplace.Heroku.CommandLineTools clean_logs <hours>` - deletes all logs from the database older than X hours, so the log doesn’t grow indefinitely. We recommend also having a database backup strategy.
- `curl [https://<your_app>.herokuapp.com/api/ping](https://atonit-marketplace-v2.herokuapp.com/api/ping)` - pings the website every 10 minutes ensuring the process doesn’t sleep and is always responsive.

## Create Admin SuperUser

The admin superuser must be created with the Heroku CLI.

Open a terminal and run the following command:

`heroku run "tools/Atonit.Marketplace.Heroku.CommandLineTools insert_admin_user '<user_name>' '<password>'" --app <your_app>`

The password must meet the following criteria:

- Passwords must be at least 12 characters.
- Passwords must have at least one non-alphanumeric character.
- Passwords must have at least one digit ('0'-'9').
- Passwords must have at least one uppercase ('A'-'Z').

**warning:** Keep this password in a secure location as it isn’t retrievable.

## Accessing the Environment

Make sure all dynos are active and running. Open the web app and log in using the admin user credentials.
If you ‘re able to log in, the setup finished correctly and you can proceed with the configuration.

## Logging

Logging is configured to store a subset of logs in the database so they can be easily displayed on dashboards for the integrations. All logs also go through the default Heroku log pipeline.

For security audit reasons, it’s recommended to contract a logging add-on for Heroku and save it for audits.

For more information, see [Heroku Add-ons](https://elements.heroku.com/addons#logging).

## Google reCAPTCHA

For added security to the login page, we recommend configuring Google reCAPTCHA to prevent password testing bots.

1. Create a reCAPTCHA V2 account and add your `[app].herokuapp.com` domain.

   **note:** Be advised that Terms & Conditions and pricing from Google apply. It is your responsibility to monitor usage.

2. Copy the values of the Site Key and Secret Key, and add them as separate Heroku Config Vars with the names `GOOGLE_RECAPTCHA_SITE_KEY` and `GOOGLE_RECAPTCHA_SECRET_KEY`.

3. Refresh the Heroku app, and test if the reCAPTCHA successfully appears in the login page.

<!-- document id=9ce553a3281cf54eff00e0dc15b21f4626ab98dc0ac9a555c5332d4e2129487a url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/mask-customer-data.md -->

Mask Customer Data

# Mask Customer Data

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/mask-customer-data/mask-customer-data-oas-public.yaml)

Request to mask customer data by email or customer ID identifiers.

**Version:** 2.3.4

## Tags

### Mask Customer Data

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/mask-customer-data/mask-customer-data-oas-public.yaml)

Request to mask customer data by email or customer ID identifiers.

## Operations

### POST Mask customer data.

`POST /merchant/{version}/customer/mask`

Operation ID: `maskCustomerData`. Tags: Mask Customer Data, Customer API.

Administrative API to mask specific customer data to satisfy CCPA/GDPR requirements. Customer records are identified by customer ID or email address, and PII fields are replaced with mask characters across all relevant data stores.

The following categories of customer data are masked:

*   **Names** — first name, last name, middle name, initials
*   **Contact information** — email addresses, phone numbers
*   **Addresses** — billing and shipping addresses, including street, city, state/province, ZIP/postal code, and country
*   **Demographic information** — gender, age, date of birth
*   **Payment information** — credit card numbers, card type, expiration dates, billing address
*   **Loyalty and consent** — loyalty enrollment data and related consents
*   **Identification numbers** — driver's license, national ID, and similar identifiers

Masking is applied across relational databases (MySQL), NoSQL databases (DynamoDB), caches (Redis), and data warehouses (Redshift). Object storage (S3) is covered by TTL policies.

Masking is asynchronous. The response returns a `requestId` and an `IN_PROGRESS` status. Use the request ID to poll for completion.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerMaskResponse`.
    

## Schemas

### CustomerMaskResponse

*   `requestId` (_string_) Unique identifier for this masking request.  
    Example: `e7966181-88a6-4247-9261-0ef0f35eb336`.
*   `customerCount` (_integer (int32)_) Number of customer records included in the masking request.  
    Example: `2`.
*   `status` (_string_)
    
    Current status of the masking request.
    
    *   `IN_PROGRESS` — Masking is running asynchronously.
    *   `SUCCESSFUL` — All specified customer records have been masked.
    *   `FAILED` — Masking failed. See `errorCode` and `errorMessage` for details.
    
      
    Allowed values: `IN_PROGRESS`, `SUCCESSFUL`, `FAILED`.
*   `requestedOn` (_integer (int64)_) Unix timestamp (milliseconds) indicating when the masking request was submitted.  
    Example: `1746136132000`.
*   `errorCode` (_string_) Machine-readable error code. Present only when `status` is `FAILED`.  
    Example: `MISSING_ID`.
*   `errorMessage` (_string_) Human-readable error message. Present only when `status` is `FAILED`.  
    Example: `No customer identifier(s) provided`.

<!-- document id=30cc8c64b42740182c217f107fbf20de4433ce56e14d20181732f6ca86005519 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/maximizing-your-cache-hit-ratio.md -->

# Maximize Your Cache Hit Ratio

One of the best ways to improve the performance of your storefront is to maximize your cache hit ratio. Any request that can be fulfilled from Managed Runtime’s CDN cache counts as a cache hit. With each cache hit, you speed up page loading for the user because you save the cost of rendering that page on the server side and making any requests to back-end systems and APIs.

This guide covers three different techniques for maximizing your cache hits: setting optimal cache lifetimes, conditional rendering, and filtering query strings. Let’s go through each technique in detail.

## Set Optimal Cache Lifetimes

The optimal amount of time to cache an HTTP request depends on what’s being requested. A request to load a content page that rarely changes can be safely cached for a long time. In contrast, a product listing page that’s frequently updated with new products might require a short cache lifetime, such as fifteen minutes. Whenever possible, choose long cache lifetimes in order to maximize the cache hit rate.

A cache-control header in the HTTP response determines the length of time that a response to a page request is stored in the CDN cache. The cache lifetime for page responses in a PWA Kit project is 600 seconds (or 10 minutes) by default. You can customize the cache lifetime on a page-by-page basis, or you can customize it for all pages.

**tip:** To learn more about caching in general, we recommend this article from Google: [Prevent unnecessary network requests with the HTTP Cache](https://web.dev/http-cache/).

### Set the Cache Lifetime for a Page

The `getProps` function of any page component allows you to customize the HTTP response using an object that is passed in called `res`. To set the cache lifetime for a page, use the `set` method of the `res` object to set a `Cache-Control` header and specify a value in seconds for the `max-age` directive.

For example, this `ProductList` component extends the cache lifetime from the default of 600 seconds to 900 seconds:

```javascript
ProductList.getProps = async ({res, params, location, api}) => {
    const {categoryId} = params
    const urlParams = new URLSearchParams(location.search)

    // Set the cache-control header values to align with the Commerce API settings.
    if (res) {
        res.set('Cache-Control', 'public, must-revalidate, max-age=900')
    }

    // The rest of the getProps function, including the return statement, goes here.
}
```

**note:** We don’t recommend that you set a cache-control header within the `getProps` function that belongs to the `App` special component defined in `app/components/_app/index.jsx`. The `getProps` functions for both the `App` component and the current page component are executed at the same time. This parallel execution leads to unpredictable results if you set the same response header in both functions.

### Set the Cache Lifetime for All Pages

You can set the cache lifetime for all pages in `app/ssr.js`. You can change the default cache lifetime by setting a new value for `defaultCacheTimeSeconds`. If you need more fine-grained control over the HTTP header, add an Express handler that sets a custom header, like this:

```javascript
app.get('/*', (req, res) => {
    res.set('Cache-Control', 'public, max-age=3600')
    render(req, res)
})
```

### Test the Response

You can test that your cache controls are present in the response headers by inspecting your network requests with Chrome’s DevTools in the **Network** tab. Alternatively, you can run the following `curl` command in your terminal, which outputs all response headers. Replace `<URL>` in the example command with the full URL that you want to test, including any required query strings.

```bash
curl --dump-header - --silent --output /dev/null <URL>
```

## Conditional Rendering

To ensure that a page is suitable for caching by the CDN, you must add conditional code to avoid rendering the following types of content on the server side:

-   **Personalized content**, such as a user’s name, the number of items in the cart, and preferred payment method. Personalized content is inappropriate for and irrelevant to anyone other than a single user. Caching responses for a single user doesn’t increase your cache hits.
-   **Frequently changing content**, such as a product’s price, remaining inventory, or sales promotions. This content is unsuitable for caching because there’s a risk of confusing the user when the page contains information that is already out-of-date.

Think of the page that is rendered on server side as a generic foundation for the client to build on. After quickly loading the server-side version of the page onto the user’s device, the browser takes over to render the personalized and frequently changing content.

To determine whether rendering is happening on the client side or server side, check for the presence of the `window` object, which is only present on the client side. The following example uses this technique to render a price only on the client side:

```javascript
<div>
    {/* The price is only rendered on the client side,
     * because it changes frequently */}
    {typeof window != 'undefined' && <p>Price: ${price}</p>}
</div>
```

**tip:** To preview the version of the page that is rendered on the server side in your browser, append `?__server_only` to the URL. This query parameter stops the [hydration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Hydration_(web_development)>) process so that the browser won’t take over rendering, leaving the page unchanged after server-side rendering.

## Filter Query Strings

Most storefront apps use the [query string](https://developer.mozilla.org/en-US/docs/Web/API/URL/search) of a URL to store parameters and values that represent aspects of the app’s state. For example, when a user searches for “sweaters,” you can include the search term in the query string like this: `?search=sweaters`. Query strings are also commonly used to track user actions. For example, we can append a unique query string to each link in an email to track interactions with it: `user=juanita&source=email`.

Not all query string parameters are relevant when it comes to caching. Managed Runtime includes an edge function called the **request processor** that allows you to modify the query string of a request before it looks for cached responses. You can increase your cache hits by using the request processor to map similar URLs to the same cached response.

To customize the request processor, edit the `processRequest` function defined in `app/request-processor.js`.

The following example defines a request processor that filters out the parameters `gclid` and `utm_campaign` from the query string. These parameters are commonly associated with Google marketing campaigns and are only useful on the client side. To simplify working with query strings, it imports the `QueryParameters` class from the PWA Kit React SDK.

```javascript
import {QueryParameters} from 'pwa-kit-react-sdk/utils/ssr-request-processing'

const filterQueryStringKeys = (querystring, filteredKeys) =>
    QueryParameters.from(
        new QueryParameters(querystring).parameters.filter(({key}) => !filteredKeys.includes(key))
    ).toString()

export const processRequest = ({path, querystring}) => ({
    path,
    querystring: filterQueryStringKeys(querystring, ['gclid', 'utm_campaign']),
})
```

The full URL that is used to look up the corresponding object in the cache includes the version of the query string that is returned by the request processor. If no response is cached for that URL, this same modified version of the URL is passed to the Express app.

Beware of two gotchas when using this approach:

First, be sure that your app doesn’t rely on any filtered parameters for rendering! For example, if you filtered the `search` parameter from above, you’d have a hard time displaying the correct search results.

Second, be cautious when filtering parameters from requests that you expect to redirect. If your code can’t access a filtered parameter, that parameter can’t be used for the redirect either. Consider a request a home page component that redirects a request for `www.example.com?lang=en` to a locale-specific path like `www.example.com/en`. If you filter out the `lang` parameter, you can’t redirect to the right locale.

Consider this sequence:

1.  The request processor handles a request for `www.example.com/?gclid=123`.
2.  The request processor filters the `gclid` query string parameter.
3.  The request is forwarded to the application with the full URL `www.example.com`.
4.  The application returns a redirect to `www.example.com/en`.

Notice that on this last step, we’ve lost the original `gclid` parameter, so it won’t be available to the browser after the user is redirected. To work around this challenge, avoid filtering query strings of requests you expect to redirect.

## Next Steps

Now you know how to improve your cache hits for page requests using a variety of techniques.

Read our guide to [Proxying Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md) to learn about caching API requests and other benefits of proxying.

<!-- document id=c533ca00f1aac7f09fc9137e4a9da2b77a43e83cce5647184731a954a0492471 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/search-and-navigation/b2c-merchandising-the-no-results-page.md -->

# Merchandise the No Results Page

Add custom selected content to the No Results page.

The following example describes how to merchandise the no results page by changing an existing SiteGenesis content that already appears on the no results page. In addition to what is described here, add links to other catalogs or seasonally appropriate products, and embed graphic files within a content asset.

1.  In UX Studio, open the nohits.isml templates in the SiteGenesis Storefront Core cartridge.

2.  Locate lines 27–32 in the text. This is where SiteGenesis shows the search results page.

    ```html
    <p> ${Resource.msg('nohits.didyoumean','search',null)}
    <a class="no-hits-search-term-suggest"
    title="${pdict.ProductSearchResult.suggestedSearchPhrase}"
    href="Search-Show?q=<isprint value="${pdict.ProductSearchResult.suggestedSearchPhrase}"/>">
    <isprint value="${pdict.ProductSearchResult.suggestedSearchPhrase}"/> </a> ? </p>
    ```

3.  Locate line 50–52. This is where SiteGenesis shows the noresults-help content asset.

    ```html
    <div class="no-hits-help">
      <iscontentasset aid="noresults-help" />
    </div>
    ```

4.  Select **_site_** > **Merchant Tools** > **Content** > **Content Assets** for the SiteGenesis site.

5.  Open the `noresults-help` content asset.

6.  Modify this file as follows:

    1.  Change:

        ```html
        <p>Try your search again using these tips:</p>
        <ul class="grayarrow">
          <li>Double check the spelling. Try varying the spelling.</li>
          <li>Limit the search to one or two words.</li>
          <li>
            Be less specific in your wording. Sometimes a more general term will lead you to the
            similar products.
          </li>
        </ul>
        ```

    2.  To:

        ```html
        <p>Don't give up now, you're almost there. Try again using these tips:</p>
        <ul class="bluearrow">
          <li>Double check your spelling. Try changing a few letters.</li>
          <li>Try one word at a time.</li>
          <li>Be more vague. Maybe a more general term will help you find what you want.</li>
        </ul>
        ```

7.  Open the storefront site for the SiteGenesis application and search for `GADZUK`.

    The no results page contains the new text.

<!-- document id=557306276c5a15579ad16fca3ed593f3e18bbcd7a7c42be6255a8d0d75aa4d53 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/merge-shopper-profiles.md -->

# Merge Shopper Profiles

B2C Commerce provides multiple ways for customers to implement shopper login functionality. Today, shoppers can log in via:

1. SFRA/Site Genesis based login for shoppers registered with B2C Commerce (first-party IDP).
2. Headless login via SLAS for shoppers registered with B2C Commerce or a third-party IDP.
3. SFRA/Site Genesis based login for shoppers registered via B2C Commerce third-party IDP, configuring external OAuth2.0 providers.

Shoppers having the same login ID across use cases 1 and 2 can now be merged to one single customer/shopper record. This enables the shoppers logging with SLAS-based login to preserve (or merge with) their existing baskets, orders, and wishlists.

**note:** Currently, we don’t support merging logins between B2C Commerce’s external OAuth2.0 providers and SLAS federating to third-party IDPs (that is, we don’t support merges between 2 and 3).

## Configure IDP within SLAS with loginMergeClaims

For details on configuring IDP with `loginMergeClaims`, see [`registerIdentityProvider`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider).

## Use Cases

The following sections describe common use cases.

### Merge an Existing B2C Commerce Profile with Federated Login via SLAS

John Doe is a registered shopper with Northern Trail Outfitters SFRA app. John’s login ID is [`john.doe@gmail.com`](mailto:john.doe@gmail.com). Northern Trail Outfitters implements a federated login to the third-party IDP (for example, Google) for their new headless app.

**Seller Action:** Configure Google IDP within SLAS with “loginMergeClaims” : “email”.

![Step 1 of shopper basket merge process diagram showing initial basket states](https://developer.salesforce.com/docs/media/commerce-api/shopper-merge-1.png)

As you can see, when John logs in with SLAS, the external profile that is created is linked to John’s existing customer profile in B2C Commerce and John is able to get the same customer ID, merging his basket from before.

### Merge an Existing B2C Commerce Profile with a Social Profile

When a B2C Commerce profile exists as well as an externally authenticated social profile (Facebook, Google):

- If both profiles exist before configuring a `loginMergeClaims` and before logging in through SLAS, no merge is performed.
- If both profiles exist and login through SLAS occurs with a third-party login with `loginMergeClaims` turned on, the account that was created last is merged.

### Merge Logins across Two Third-Party IDPs (Same Login ID)

John Doe is a registered shopper with Northern Trail Outfitters SFRA app. John’s login ID is [`john.doe@gmail.com``](mailto:john.doe@gmail.com). Northern Trail Outfitters wants to implement a federated login to 2 or more third-party IDPs (for example, Google and Facebook) for their new headless app.

**Seller Action :** Configure Google & Facebook IDPs within SLAS with “loginMergeClaims” : “email”.

![Step 2 of shopper basket merge process diagram showing merge operation](https://developer.salesforce.com/docs/media/commerce-api/shopper-merge-2.png)

As you can see, when John logs in with SLAS with Google and Facebook for the same app, the two logins map to the same customer profile in B2C Commerce and John is able to get the same customer ID, merging the baskets between the two sessions.

### Merge Logins across Two Login IDs (Same External IDP Profile)

John Doe is a registered shopper with Northern Trail Outfitters SFRA app, and logs in with either his email or his phone number. Northern Trail Outfitters wants to implement a federated login to 2 or more third-party IDPs (for example, Google or Facebook), providing shoppers flexibility in logging in with their preferred IDP for their new headless app.

**Seller Action:** Configure Google or Facebook IDP within SLAS with “loginMergeClaims” : “email, phone”.

![Step 3 of shopper basket merge process diagram showing final merged basket state](https://developer.salesforce.com/docs/media/commerce-api/shopper-merge-3.png)

As you can see, when John logs in with SLAS with Facebook first with his email and then with his phone number, the two logins map to the same customer profile in B2C Commerce, and John is able to get the same customer ID, resulting in merging the baskets between the two sessions.

<!-- document id=02f529bb744a3cdf4d90196e56dae661e21846f64309c8c29ff51803be09cd5c url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/metrics.md -->

Metrics

# Metrics

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/metrics/metrics-oas-v1-public.yaml)

## API Overview

The Metrics API provides programmatic access to time-series operational metrics for Salesforce Commerce Cloud organizations. It exposes the same metrics available in the LogCenter UI, organized by functional category, so that data can be ingested into third-party BI and monitoring tools (such as Tableau or Grafana) and into agentic-observability workflows.

This is an Admin API: it is intended for operators, SRE teams, and machine clients (BI tools, monitoring agents) acting on behalf of a customer organization, not for storefront shoppers.

> **Note:** The Metrics API is currently in a closed beta. To request access, please contact your account manager.

### Endpoints

The API exposes nine pre-aggregated metric categories, each accessible through its own typed path:

*   **`/metrics/overall`** — Overall application performance metrics
*   **`/metrics/sales`** — Sales and commerce metrics
*   **`/metrics/ecdn`** — eCDN performance and caching metrics
*   **`/metrics/third-party`** — Third-party service integration metrics
*   **`/metrics/scapi`** — SCAPI request and performance metrics
*   **`/metrics/scapi-hooks`** — SCAPI hooks execution metrics
*   **`/metrics/mrt`** — Managed Runtime metrics
*   **`/metrics/controller`** — Controller and pipeline metrics
*   **`/metrics/ocapi`** — OCAPI request and performance metrics

Each request returns a single time-series document for the requested category, organization, and time window.

### Key Features

*   **Time-series data retrieval** with Unix epoch time-range parameters (in seconds)
*   **Multiple metric categories** covering all aspects of Commerce Cloud performance
*   **Organization-scoped access** with proper authentication and authorization
*   **Filtering capabilities** for specific APIs, services, and OCAPI sub-categories
*   **Standardized response format** with comprehensive metadata

### Authentication & Authorization

This API uses standard SCAPI authentication mechanisms:

*   **OAuth 2.0** (`AmOAuth2`) with the SCAPI gateway
*   **Organization-scoped access** — callers can only retrieve metrics for organizations they are authorized to access

Required OAuth scope:

*   `sfcc.metrics` — read access to metrics

### Time-Range Constraints

Two backend-enforced constraints bound every request:

*   **Maximum lookback:** `from` must not resolve to a time more than 30 days ago. This matches the configured retention of the underlying metrics store; older data is not retained.
*   **Maximum window:** `to - from` must not exceed 1 day. Requests that exceed this return `400 Bad Request`.

### Use Cases

#### Overall application monitoring

Monitor total platform requests, sessions, and response times.

```
GET /organizations/{orgId}/metrics/overall?from=1672531200&to=1672534800
```

#### Sales performance tracking

Track order creation and basket activity.

```
GET /organizations/{orgId}/metrics/sales?from=1672488000&to=1672531200
```

#### eCDN performance analysis

Monitor CDN performance, cache hit rates, and bandwidth usage.

```
GET /organizations/{orgId}/metrics/ecdn?from=1672509600&to=1672531200
```

#### SCAPI performance monitoring

Monitor SCAPI request latency and response counts, optionally filtered by API family and / or API name.

```
GET /organizations/{orgId}/metrics/scapi?from=1672527600&to=1672531200&apiFamily=shopper&apiName=products
```

#### Third-party service monitoring

Track third-party service call performance and error rates, optionally filtered to a single named service.

```
GET /organizations/{orgId}/metrics/third-party?from=1672488000&to=1672531200&thirdPartyServiceId=apple-pay-gateway.apple.com
```

#### SCAPI Hooks performance monitoring

Track SCAPI hook execution time and error rates.

```
GET /organizations/{orgId}/metrics/scapi-hooks?from=1672527600&to=1672531200
```

#### Managed Runtime monitoring

Monitor MRT request volume, cache hit rates, error rates, and Lambda invocations.

```
GET /organizations/{orgId}/metrics/mrt?from=1672488000&to=1672531200
```

#### Controller performance monitoring

Track controller invocation volume and processing duration.

```
GET /organizations/{orgId}/metrics/controller?from=1672527600&to=1672531200
```

#### OCAPI performance monitoring

Monitor OCAPI metrics, optionally filtered by OCAPI category and / or OCAPI API endpoint.

```
GET /organizations/{orgId}/metrics/ocapi?from=1672527600&to=1672531200&ocapiCategory=shop&ocapiApi=baskets
```

### Metric Categories

#### Overall Application

*   Total Platform Requests — Overall request volume
*   Storefront Requests — Customer-facing request volume
*   Sessions — Active user sessions
*   Response Time — Average response latency
*   Emails Sent — Email delivery volume
*   System Workload — Overall system utilization

#### Sales

*   Orders — Order creation rate
*   Basket Creations — Shopping basket creation rate
*   Basket Updates — Basket modification rate

#### eCDN

*   Success and Errors — Request success / failure rates
*   Cache Hit Percentage — CDN cache effectiveness
*   Total Requests — Overall CDN request volume
*   Total Bandwidth — Data-transfer volume
*   Total Pageviews — Page view metrics
*   Unique Visitors — Unique visitor tracking

#### Third-Party Services

*   Call Counts — API call volume to external services
*   Call Duration p95 — 95th-percentile response times
*   Remote Exceptions — Error rates from external services

#### SCAPI

*   Request Latency — API response times
*   Response Count — SCAPI response volume by API family and HTTP status class (2xx/3xx/4xx/5xx)
*   Cache Hit Statistics — API-level caching metrics

#### SCAPI Hooks

*   Hook Execution Times — Hook processing duration
*   Hook Errors — Hook execution error rates

#### Managed Runtime

*   Request Count — MRT request volume
*   Cache Hit Rates — MRT caching performance
*   Error Rates — MRT error percentages
*   Lambda Invocations — Serverless function executions
*   Request Times — MRT processing duration

#### Controller

*   Total Calls — Controller invocation count
*   Average Duration — Controller processing time

#### OCAPI

*   Total Calls — OCAPI request volume
*   Average Duration — OCAPI response times
*   Total Errors — OCAPI error counts

**Version:** 1.0.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/observability/metrics/v1`
    *   `shortCode (default shortCode) Tenant-specific short code`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.metrics: metrics READONLY

## Operations

### GET Get Overall Application metrics

`GET /organizations/{organizationId}/metrics/overall`

Operation ID: `getOverallMetrics`. Tags: Overall Application. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all overall application performance metrics including total platform requests, storefront requests, sessions, response time, emails sent, and system workload.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.

#### Responses

*   **200** Successfully retrieved overall application metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: OverallMetricsResponseExample_ Overall Application metrics response
    
    ```
    {
      "data": [
        {
          "metricId": "totalCalls",
          "title": "Total Platform Requests",
          "description": "Total number of platform requests per minute.",
          "unit": "requests/min",
          "dataSeries": [
            {
              "id": "realm1.totalCalls",
              "name": "realm1 Total Calls",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 1250.5
                },
                {
                  "timestamp": 1640995260,
                  "value": 1275.2
                },
                {
                  "timestamp": 1640995320,
                  "value": 1201.8
                }
              ]
            }
          ]
        },
        {
          "metricId": "sessions",
          "title": "Sessions",
          "description": "Number of active sessions across all sites per minute.",
          "unit": "sessions/min",
          "dataSeries": [
            {
              "id": "realm1.sessions",
              "name": "realm1 Sessions",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 45.2
                },
                {
                  "timestamp": 1640995260,
                  "value": 47.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 44.8
                }
              ]
            }
          ]
        },
        {
          "metricId": "responseTime",
          "title": "Response Time",
          "description": "Average response time across all requests.",
          "unit": "ms",
          "dataSeries": [
            {
              "id": "realm1.responseTime",
              "name": "realm1 Response Time",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 156.3
                },
                {
                  "timestamp": 1640995260,
                  "value": 148.7
                },
                {
                  "timestamp": 1640995320,
                  "value": 162.1
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`.
    
    _Example: InvalidTimeParameterExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Invalid time parameter 'from'. Must be a Unix epoch timestamp in seconds (e.g., 1672531200).",
      "parameter": "from"
    }
    ```
    
    _Example: InvalidTimeRangeExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Invalid time range: 'from' (1672534800) must be earlier than 'to' (1672531200).",
      "fromValue": 1672534800,
      "toValue": 1672531200
    }
    ```
    
    _Example: InvalidTimeParameterErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-time-parameter",
      "detail": "Invalid time parameter 'from'. Must be a Unix epoch timestamp in seconds (e.g., 1672531200).",
      "title": "Invalid Time Parameter"
    }
    ```
    
    _Example: InvalidTimeRangeErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-time-range",
      "detail": "Invalid time range: 'from' (1672534800) must be earlier than 'to' (1672531200).",
      "title": "Invalid Time Range"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example: CategoryNotFoundExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "title": "Not Found",
      "detail": "Metrics category 'unknown-category' not found or not available for organization 'f_ecom_zzxy_prd'.",
      "category": "unknown-category",
      "organizationId": "f_ecom_zzxy_prd"
    }
    ```
    
    _Example: CategoryNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/category-not-found",
      "detail": "Metrics category 'unknown-category' not found or not available for organization 'f_ecom_zzxy_prd'.",
      "title": "Category Not Found"
    }
    ```
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example: MetricsUnavailableExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/service-unavailable",
      "title": "Service Unavailable",
      "detail": "Metrics data is temporarily unavailable for organization 'f_ecom_zzxy_prd'. Please try again later.",
      "organizationId": "f_ecom_zzxy_prd"
    }
    ```
    
    _Example: MetricsNotAvailableErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/metrics-not-available",
      "detail": "Metrics data is temporarily unavailable for organization 'f_ecom_zzxy_prd'. Please try again later.",
      "title": "Metrics Not Available"
    }
    ```
    

### GET Get Sales metrics

`GET /organizations/{organizationId}/metrics/sales`

Operation ID: `getSalesMetrics`. Tags: Sales. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all sales metrics including orders, basket creations, and basket updates.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.

#### Responses

*   **200** Successfully retrieved sales metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: SalesMetricsResponseExample_ Sales metrics response
    
    ```
    {
      "data": [
        {
          "metricId": "orders",
          "title": "Orders",
          "description": "Number of orders created across all sites per minute.",
          "unit": "orders/min",
          "dataSeries": [
            {
              "id": "realm1.orders",
              "name": "realm1 Orders",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 25.3
                },
                {
                  "timestamp": 1640995260,
                  "value": 27.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 23.8
                }
              ]
            }
          ]
        },
        {
          "metricId": "basketCreations",
          "title": "Basket Creations",
          "description": "Number of baskets created across all sites per minute.",
          "unit": "baskets/min",
          "dataSeries": [
            {
              "id": "realm1.basketCreations",
              "name": "realm1 Basket Creations",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 85.2
                },
                {
                  "timestamp": 1640995260,
                  "value": 89.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 82.5
                }
              ]
            }
          ]
        },
        {
          "metricId": "basketUpdates",
          "title": "Basket Updates",
          "description": "Number of basket updates across all sites per minute.",
          "unit": "updates/min",
          "dataSeries": [
            {
              "id": "realm1.basketUpdates",
              "name": "realm1 Basket Updates",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 142.7
                },
                {
                  "timestamp": 1640995260,
                  "value": 138.9
                },
                {
                  "timestamp": 1640995320,
                  "value": 156.3
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

### GET Get eCDN metrics

`GET /organizations/{organizationId}/metrics/ecdn`

Operation ID: `getEcdnMetrics`. Tags: eCDN. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all eCDN metrics including success and errors, cache hit percentage, total requests, total bandwidth, total pageviews, and unique visitors.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.

#### Responses

*   **200** Successfully retrieved eCDN metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: EcdnMetricsResponseExample_ eCDN metrics response
    
    ```
    {
      "data": [
        {
          "metricId": "successAndError",
          "title": "Success and Errors",
          "description": "Total success and error requests per minute.",
          "unit": "requests/min",
          "dataSeries": [
            {
              "id": "realm1.successAndError",
              "name": "realm1 Success and Errors",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 8945.2
                },
                {
                  "timestamp": 1640995260,
                  "value": 9103.7
                },
                {
                  "timestamp": 1640995320,
                  "value": 8876.1
                }
              ]
            }
          ]
        },
        {
          "metricId": "cacheHits",
          "title": "Cache Hit Percentage",
          "description": "Percentage of requests served from cache.",
          "unit": "percentage",
          "dataSeries": [
            {
              "id": "realm1.cacheHits",
              "name": "realm1 Cache Hit Percentage",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 87.3
                },
                {
                  "timestamp": 1640995260,
                  "value": 89.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 85.7
                }
              ]
            }
          ]
        },
        {
          "metricId": "totalBandwidth",
          "title": "Total Bandwidth",
          "description": "Total bandwidth usage per minute.",
          "unit": "bytes/min",
          "dataSeries": [
            {
              "id": "realm1.totalBandwidth",
              "name": "realm1 Total Bandwidth",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 2048576000
                },
                {
                  "timestamp": 1640995260,
                  "value": 2156789123
                },
                {
                  "timestamp": 1640995320,
                  "value": 1987654321
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

### GET Get Third Party Service metrics

`GET /organizations/{organizationId}/metrics/third-party`

Operation ID: `getThirdPartyMetrics`. Tags: Third Party Services. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all third party service metrics including call counts, call duration percentiles, and remote exceptions.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.
*   `thirdPartyServiceId` (query, ThirdPartyServiceId) Filter by a specific third party service identifier (typically a hostname, e.g. `apple-pay-gateway.apple.com`). The list of services is customer-configured; omit this parameter to get one data series per (realm, third party service).

#### Responses

*   **200** Successfully retrieved third party service metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: ThirdPartyMetricsResponseExample_ Third Party Services metrics response
    
    ```
    {
      "data": [
        {
          "metricId": "callCounts",
          "title": "Call Counts",
          "description": "Number of calls to third party services per minute.",
          "unit": "calls/min",
          "dataSeries": [
            {
              "id": "realm1.apple-pay-gateway.apple.com",
              "name": "realm1 apple-pay-gateway.apple.com Call Counts",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 156
                },
                {
                  "timestamp": 1640995260,
                  "value": 163
                },
                {
                  "timestamp": 1640995320,
                  "value": 149
                }
              ]
            }
          ]
        },
        {
          "metricId": "callDurationP95",
          "title": "Call Duration P95",
          "description": "95th percentile of call duration to third party services.",
          "unit": "ms",
          "dataSeries": [
            {
              "id": "realm1.apple-pay-gateway.apple.com",
              "name": "realm1 apple-pay-gateway.apple.com Call Duration P95",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 425.7
                },
                {
                  "timestamp": 1640995260,
                  "value": 398.2
                },
                {
                  "timestamp": 1640995320,
                  "value": 467.3
                }
              ]
            }
          ]
        },
        {
          "metricId": "remoteExceptions",
          "title": "Remote Exceptions",
          "description": "Number of exceptions from third party services per minute.",
          "unit": "exceptions/min",
          "dataSeries": [
            {
              "id": "realm1.apple-pay-gateway.apple.com",
              "name": "realm1 apple-pay-gateway.apple.com Remote Exceptions",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 2
                },
                {
                  "timestamp": 1640995260,
                  "value": 1
                },
                {
                  "timestamp": 1640995320,
                  "value": 3
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters or third party service filter
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse | InvalidThirdPartyServiceErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`, `InvalidThirdPartyServiceErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example: InvalidThirdPartyServiceExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Third party service 'unknown-service.example.com' not found for organization 'f_ecom_zzxy_prd'.",
      "thirdPartyServiceId": "unknown-service.example.com",
      "organizationId": "f_ecom_zzxy_prd"
    }
    ```
    
    _Example: InvalidThirdPartyServiceErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-third-party-service",
      "detail": "Third party service 'apple-pay-gateway.apple.com' not found for organization 'f_ecom_zzxy_prd'.",
      "title": "Invalid Third Party Service"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

### GET Get SCAPI metrics

`GET /organizations/{organizationId}/metrics/scapi`

Operation ID: `getScapiMetrics`. Tags: SCAPI. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all SCAPI metrics including request latency, response counts, and cache hit statistics.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.
*   `apiFamily` (query, string) Filter by SCAPI family name  
    Minimum length: 1. Maximum length: 100. Example: `shopper`.
*   `apiName` (query, string) Filter by specific SCAPI name  
    Minimum length: 1. Maximum length: 100. Example: `products`.

#### Responses

*   **200** Successfully retrieved SCAPI metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: ScapiMetricsResponseExample_ SCAPI metrics response with filters
    
    ```
    {
      "data": [
        {
          "metricId": "requestLatency",
          "title": "Request Latency",
          "description": "Average request latency for SCAPI calls.",
          "unit": "ms",
          "dataSeries": [
            {
              "id": "realm1.shopper.products.requestLatency",
              "name": "realm1 Shopper Products Request Latency",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 245.7
                },
                {
                  "timestamp": 1640995260,
                  "value": 231.2
                },
                {
                  "timestamp": 1640995320,
                  "value": 267.8
                }
              ]
            }
          ]
        },
        {
          "metricId": "responseCount",
          "title": "Response Count",
          "description": "Number of SCAPI responses per minute.",
          "unit": "responses/min",
          "dataSeries": [
            {
              "id": "realm1.shopper.products.responseCount",
              "name": "realm1 Shopper Products Response Count",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 1456
                },
                {
                  "timestamp": 1640995260,
                  "value": 1523
                },
                {
                  "timestamp": 1640995320,
                  "value": 1389
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters or SCAPI filter value
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse | InvalidApiFilterErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`, `InvalidApiFilterErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example: InvalidApiFamilyExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Invalid value 'invalid-family' for filter 'apiFamily'.",
      "filterName": "apiFamily",
      "filterValue": "invalid-family"
    }
    ```
    
    _Example: InvalidApiNameExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Invalid value 'unknown-api' for filter 'apiName'.",
      "filterName": "apiName",
      "filterValue": "unknown-api"
    }
    ```
    
    _Example: InvalidApiFilterErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-api-filter",
      "detail": "Invalid value 'invalid-family' for filter 'apiFamily'.",
      "title": "Invalid Api Filter"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

### GET Get SCAPI Hooks metrics

`GET /organizations/{organizationId}/metrics/scapi-hooks`

Operation ID: `getScapiHooksMetrics`. Tags: SCAPI Hooks. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all SCAPI hooks metrics including hook execution times and hook errors.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.

#### Responses

*   **200** Successfully retrieved SCAPI hooks metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: ScapiHooksMetricsResponseExample_ SCAPI Hooks metrics response
    
    ```
    {
      "data": [
        {
          "metricId": "hookExecutionTimes",
          "title": "Hook Execution Times",
          "description": "Average execution time for SCAPI hooks.",
          "unit": "ms",
          "dataSeries": [
            {
              "id": "realm1.hookExecutionTimes",
              "name": "realm1 Hook Execution Times",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 45.3
                },
                {
                  "timestamp": 1640995260,
                  "value": 52.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 38.7
                }
              ]
            }
          ]
        },
        {
          "metricId": "hookErrors",
          "title": "Hook Errors",
          "description": "Number of hook execution errors per minute.",
          "unit": "errors/min",
          "dataSeries": [
            {
              "id": "realm1.hookErrors",
              "name": "realm1 Hook Errors",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 0.5
                },
                {
                  "timestamp": 1640995260,
                  "value": 1
                },
                {
                  "timestamp": 1640995320,
                  "value": 0
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

### GET Get Managed Runtime metrics

`GET /organizations/{organizationId}/metrics/mrt`

Operation ID: `getMrtMetrics`. Tags: Managed Runtime. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all Managed Runtime metrics including request counts, cache hit rates, error rates, Lambda invocations, and request times.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.

#### Responses

*   **200** Successfully retrieved Managed Runtime metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: MrtMetricsResponseExample_ Managed Runtime metrics response
    
    ```
    {
      "data": [
        {
          "metricId": "requestCount",
          "title": "Request Count",
          "description": "Number of MRT requests per minute.",
          "unit": "requests/min",
          "dataSeries": [
            {
              "id": "realm1.requestCount",
              "name": "realm1 Request Count",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 789.2
                },
                {
                  "timestamp": 1640995260,
                  "value": 823.4
                },
                {
                  "timestamp": 1640995320,
                  "value": 756.1
                }
              ]
            }
          ]
        },
        {
          "metricId": "cacheHitRates",
          "title": "Cache Hit Rates",
          "description": "Percentage of requests served from MRT cache.",
          "unit": "percentage",
          "dataSeries": [
            {
              "id": "realm1.cacheHitRates",
              "name": "realm1 Cache Hit Rates",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 92.3
                },
                {
                  "timestamp": 1640995260,
                  "value": 94.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 89.7
                }
              ]
            }
          ]
        },
        {
          "metricId": "errorRates",
          "title": "Error Rates",
          "description": "Percentage of MRT requests that resulted in errors.",
          "unit": "percentage",
          "dataSeries": [
            {
              "id": "realm1.errorRates",
              "name": "realm1 Error Rates",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 0.8
                },
                {
                  "timestamp": 1640995260,
                  "value": 1.2
                },
                {
                  "timestamp": 1640995320,
                  "value": 0.5
                }
              ]
            }
          ]
        },
        {
          "metricId": "lambdaInvocations",
          "title": "Lambda Invocations",
          "description": "Number of Lambda function invocations per minute.",
          "unit": "invocations/min",
          "dataSeries": [
            {
              "id": "realm1.lambdaInvocations",
              "name": "realm1 Lambda Invocations",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 234
                },
                {
                  "timestamp": 1640995260,
                  "value": 267
                },
                {
                  "timestamp": 1640995320,
                  "value": 201
                }
              ]
            }
          ]
        },
        {
          "metricId": "requestTimes",
          "title": "Request Times",
          "description": "Average request processing time in MRT.",
          "unit": "ms",
          "dataSeries": [
            {
              "id": "realm1.requestTimes",
              "name": "realm1 Request Times",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 123.4
                },
                {
                  "timestamp": 1640995260,
                  "value": 118.7
                },
                {
                  "timestamp": 1640995320,
                  "value": 134.2
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

### GET Get Controller metrics

`GET /organizations/{organizationId}/metrics/controller`

Operation ID: `getControllerMetrics`. Tags: Controller. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all controller/pipeline metrics including total calls and average duration.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.

#### Responses

*   **200** Successfully retrieved controller metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: ControllerMetricsResponseExample_ Controller metrics response
    
    ```
    {
      "data": [
        {
          "metricId": "totalCalls",
          "title": "Total Calls",
          "description": "Number of controller invocations per minute.",
          "unit": "calls/min",
          "dataSeries": [
            {
              "id": "realm1.totalCalls",
              "name": "realm1 Total Calls",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 456.3
                },
                {
                  "timestamp": 1640995260,
                  "value": 489.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 423.7
                }
              ]
            }
          ]
        },
        {
          "metricId": "averageDuration",
          "title": "Average Duration",
          "description": "Average controller processing time.",
          "unit": "ms",
          "dataSeries": [
            {
              "id": "realm1.averageDuration",
              "name": "realm1 Average Duration",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 67.8
                },
                {
                  "timestamp": 1640995260,
                  "value": 72.3
                },
                {
                  "timestamp": 1640995320,
                  "value": 61.4
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

### GET Get OCAPI metrics

`GET /organizations/{organizationId}/metrics/ocapi`

Operation ID: `getOcapiMetrics`. Tags: OCAPI. Security: AmOAuth2 (sfcc.metrics).

Retrieve time series data for all Open Commerce API metrics including total calls, average duration, and total errors.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `from` (query, integer (int64))
    
    Start time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to one hour before `to`.
    
    Constraints:
    
    *   `from` must not resolve to a time more than 30 days before the request (matches the configured retention of the underlying metrics store).
    *   `to` minus `from` must not exceed 1 day.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672531200`.
*   `to` (query, integer (int64))
    
    End time for the query window, expressed as a Unix epoch timestamp in seconds.
    
    If not specified, defaults to the current time (now).
    
    Constraints:
    
    *   `to` minus `from` must not exceed 1 day.
    *   `from` must not resolve to a time more than 30 days before the request.
    
    Requests violating either constraint return `400 Bad Request`.
    
      
    Minimum: 1. Example: `1672534800`.
*   `ocapiCategory` (query, string) Filter by Open Commerce API category. Common values include `shop`, `data` and `mercury`. Queries with values that don't match any series return 200 with empty data.  
    Minimum length: 1. Maximum length: 100. Example: `shop`.
*   `ocapiApi` (query, string) Filter by specific Open Commerce API endpoint (e.g. `baskets`).  
    Minimum length: 1. Maximum length: 100. Example: `baskets`.

#### Responses

*   **200** Successfully retrieved OCAPI metrics for the requested time window
    
    Media type: `application/json`. Schema: `MetricsDataResponse`.
    
    _Example: OcapiMetricsResponseExample_ OCAPI metrics response with filters
    
    ```
    {
      "data": [
        {
          "metricId": "totalCalls",
          "title": "Total Calls",
          "description": "Number of OCAPI calls per minute.",
          "unit": "calls/min",
          "dataSeries": [
            {
              "id": "realm1.shop.baskets.totalCalls",
              "name": "realm1 Shop Baskets Total Calls",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 234.5
                },
                {
                  "timestamp": 1640995260,
                  "value": 251.2
                },
                {
                  "timestamp": 1640995320,
                  "value": 218.9
                }
              ]
            }
          ]
        },
        {
          "metricId": "averageDuration",
          "title": "Average Duration",
          "description": "Average OCAPI response time.",
          "unit": "ms",
          "dataSeries": [
            {
              "id": "realm1.shop.baskets.averageDuration",
              "name": "realm1 Shop Baskets Average Duration",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 89.3
                },
                {
                  "timestamp": 1640995260,
                  "value": 94.7
                },
                {
                  "timestamp": 1640995320,
                  "value": 82.1
                }
              ]
            }
          ]
        },
        {
          "metricId": "totalErrors",
          "title": "Total Errors",
          "description": "Number of OCAPI errors per minute.",
          "unit": "errors/min",
          "dataSeries": [
            {
              "id": "realm1.shop.baskets.totalErrors",
              "name": "realm1 Shop Baskets Total Errors",
              "data": [
                {
                  "timestamp": 1640995200,
                  "value": 3.2
                },
                {
                  "timestamp": 1640995260,
                  "value": 4.1
                },
                {
                  "timestamp": 1640995320,
                  "value": 2.7
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request — invalid time parameters or OCAPI filter value
    
    Media type: `application/problem+json`. Schema: `InvalidTimeParameterErrorResponse | InvalidTimeRangeErrorResponse | InvalidApiFilterErrorResponse`.
    
    One of: `InvalidTimeParameterErrorResponse`, `InvalidTimeRangeErrorResponse`, `InvalidApiFilterErrorResponse`.
    
    _Example InvalidTimeParameterExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeParameterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidTimeRangeErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 400 response._
    
    _Example InvalidApiFilterErrorResponseExample: same as GET /organizations/{organizationId}/metrics/scapi 400 response._
    
    _Example: InvalidOcapiApiExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Invalid value 'unknown-api' for filter 'ocapiApi'.",
      "filterName": "ocapiApi",
      "filterValue": "unknown-api"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Metrics category not available for the organization
    
    Media type: `application/problem+json`. Schema: `CategoryNotFoundErrorResponse`.
    
    _Example CategoryNotFoundExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
    _Example CategoryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 404 response._
    
*   **503** Metrics data temporarily unavailable
    
    Media type: `application/problem+json`. Schema: `MetricsNotAvailableErrorResponse`.
    
    _Example MetricsUnavailableExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    
    _Example MetricsNotAvailableErrorResponseExample: same as GET /organizations/{organizationId}/metrics/overall 503 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### MetricsDataResponse

Response containing metrics data for a requested category

*   `data` (_array of Metric_, required) Array of metrics for the requested category

_Example_

```
{
  "data": [
    {
      "metricId": "totalCalls",
      "title": "Total Platform Requests",
      "description": "Total number of platform requests per minute.",
      "unit": "requests/min",
      "dataSeries": [
        {
          "id": "realm1.totalCalls",
          "name": "realm1 Total Calls",
          "data": [
            {
              "timestamp": 1640995200,
              "value": 1250.5
            }
          ]
        }
      ]
    }
  ]
}
```

### InvalidTimeParameterErrorResponse

Returned when an invalid time parameter format is provided

Includes all fields of `ErrorResponse`.

*   `parameter` (_string_, required) The invalid parameter name that caused the error  
    Maximum length: 100. Example: `from`.

### InvalidTimeRangeErrorResponse

Returned when the from parameter is later than the to parameter

Includes all fields of `ErrorResponse`.

*   `fromValue` (_integer (int64)_, required) The from parameter value that caused the error  
    Example: `1672534800`.
*   `toValue` (_integer (int64)_, required) The to parameter value that caused the error  
    Example: `1672531200`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CategoryNotFoundErrorResponse

Returned when a metrics category is not found or not available

Includes all fields of `ErrorResponse`.

*   `category` (_string_) The requested category that was not found  
    Maximum length: 50. Example: `unknown-category`.
*   `organizationId` (_OrganizationId_)

### MetricsNotAvailableErrorResponse

Returned when metrics data is temporarily unavailable

Includes all fields of `ErrorResponse`.

*   `organizationId` (_OrganizationId_)

### ThirdPartyServiceId

Third party service identifier, typically a hostname (e.g. `apple-pay-gateway.apple.com`). The list of services is customer-configured.

Type: `string`.

Minimum length: 1. Maximum length: 255. Example: `apple-pay-gateway.apple.com`.

### InvalidThirdPartyServiceErrorResponse

Returned when an invalid third party service filter is provided

Includes all fields of `ErrorResponse`.

*   `thirdPartyServiceId` (_ThirdPartyServiceId_, required)
*   `organizationId` (_OrganizationId_, required)

### InvalidApiFilterErrorResponse

Returned when an invalid SCAPI or OCAPI filter value is provided (apiFamily, apiName, ocapiApi)

Includes all fields of `ErrorResponse`.

*   `filterName` (_string_, required) The filter parameter name that received an invalid value  
    Maximum length: 100. Example: `apiFamily`.
*   `filterValue` (_string_, required) The invalid value provided for the filter  
    Maximum length: 100. Example: `invalid-family`.

### Metric

A single metric with its metadata and time series data

*   `metricId` (_MetricId_, required)
*   `title` (_string_, required) Human-readable title of the metric  
    Minimum length: 1. Maximum length: 200. Example: `Total Platform Requests`.
*   `description` (_string_, required) Description of what this metric measures  
    Minimum length: 1. Maximum length: 500. Example: `Total number of platform requests per minute.`.
*   `unit` (_string_, nullable) Unit of measurement for the metric values. Optional: omitted (or empty) when the unit is implied by the metric title (e.g. "Number of Calls", "Storefront Requests" — count metrics).  
    Minimum length: 0. Maximum length: 50. Example: `requests/min`.
*   `dataSeries` (_array of DataSeries_, required) Data series for this metric across different realms/filters

### MetricId

Unique identifier for a metric type

Type: `string`.

Minimum length: 1. Maximum length: 100. Pattern: ^\[a-zA-Z0-9\_-\]+$. Example: `totalCalls`.

### DataSeries

Time series data for a specific realm/filter combination

*   `id` (_DataSeriesId_, required)
*   `name` (_string_, required) Human-readable name of the data series  
    Minimum length: 1. Maximum length: 200. Example: `realm1 Total Calls`.
*   `data` (_array of DataPoint_, required) Array of time series data points

### DataSeriesId

Unique identifier for a data series within a metric

Type: `string`.

Minimum length: 1. Maximum length: 200. Example: `realm1.totalCalls`.

### DataPoint

A single time series data point

*   `timestamp` (_integer_, required) Unix timestamp of the data point  
    Minimum: 0. Example: `1640995200`.
*   `value` (_number_, required, nullable) Metric value at the timestamp  
    Example: `1250.5`.

<!-- document id=019702c31a0fcfe215cb1c8f03bdaf8e8ae72806aac502636158265c9ebfadde url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-page-designer-content-slots.md -->

# Migrate Content Slots from SFRA to Storefront Next

In Storefront Next, React components replace ISML templates. If you're migrating from Salesforce Storefront Reference Architecture (SFRA) and rely on content slots, use this workaround until the planned Embedded Content feature becomes available.

## Content Slot Workaround Overview

This workaround lets you manage reusable HTML content, such as shipping policies, disclaimers, or promotional blocks, in Page Designer and embed it across your storefront. It provides:

- A "Content Slot Page" page type with a single `content` region.
- A "Markup Content" component type with a `markup` attribute for HTML.
- A React component that renders the markup using the `HtmlFragment` component.

**important:** This workaround is temporary. It is replaced by Site-Wide Regions for Content Blocks, which is currently in beta. See [Manage Content for Site-Wide Regions in Storefront Next with Content Blocks (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer-content-blocks.md).

## Step 1: Create the Markup Content Component

Create the markup content in `src/components/markup-content/index.tsx`.

```tsx
import { Component } from "@/lib/decorators/component";
import { AttributeDefinition } from "@/lib/decorators/attribute-definition";
import { RegionDefinition } from "@/lib/decorators/region-definition";
import HtmlFragment from "@/components/html-fragment";
import type { ComponentType } from "@/components/region";

@Component("markupContent", {
  name: "Markup Content",
  description: "Displays HTML markup content - use for reusable content blocks",
})
@RegionDefinition([])
export class MarkupContentMetadata {
  @AttributeDefinition({ type: "markup", name: "Markup" })
  markup?: string;
}

interface MarkupContentProps {
  markup?: string;
  component?: ComponentType;
}

export default function MarkupContent({ markup, component }: MarkupContentProps) {
  const content = markup || (component?.data?.markup as string) || "";

  if (!content) return null;

  return <HtmlFragment content={content} />;
}
```

## Step 2: Create the Content Slot Page Type JSON

Create the content slot page. Add the `contentSlotPage.json` file in `cartridges/app_storefrontnext_base/cartridge/experience/pages/` and add this content.

```json
{
  "name": "Content Slot Page",
  "description": "Minimal page type for reusable content - single content region",
  "arch_type": "headless",
  "region_definitions": [
    {
      "id": "content",
      "name": "Content Region",
      "description": "Add Markup Content components here",
      "max_components": 5
    }
  ],
  "supported_aspect_types": [],
  "route": "/content-slot"
}
```

## Step 3: Create a Preview Route for Page Designer

Content slot pages need a preview route to be editable in Page Designer's design mode. Create the `_app.content-slot.tsx` file in `src/routes/_app.content-slot.tsx` and add this content.

```tsx
import { Region } from "@/components/region";
import { fetchPageWithComponentData } from "@/lib/util/pageLoader";
import type { LoaderFunctionArgs } from "react-router";

export function loader(args: LoaderFunctionArgs) {
  return {
    // Replace {content-id} with the ID of the page you create in Page Designer
    page: fetchPageWithComponentData(args, { pageId: "{content-id}" }),
  };
}

export default function ContentSlotPreviewPage({ loaderData }) {
  return (
    <div className="max-w-7xl mx-auto px-4 py-8">
      <Region page={loaderData.page} regionId="content" />
    </div>
  );
}
```

## Step 4: Generate and Deploy Metadata

Use these commands to generate and deploy the metadata.

```bash
pnpm cartridge:generate
pnpm push
pnpm cartridge:deploy
```

## Step 5: Set Up a Content Slot in Business Manager

**important:** To be able to bind content assets to components in Page Designer, turn on a feature switch. In **Administration > Global Preferences > Feature Switches**, turn on **Enable Page Designer Data Binding**.

1. Create a content slot page in **Merchant Tools > Content > Page Designer > New Page**.
2. Select **Content Slot Page** as the page type.
3. Add **Markup Content** components to the "content" region.
4. Configure markup by entering HTML directly or by using data binding to bind to Content Assets.
5. Assign a page ID (for example, `shipping-policy` or `legal-disclaimer`). You reference this ID when fetching the page.

## Populate the Content

You can populate content in two ways.

#### Option 1: Direct HTML entry

Enter HTML directly in the Markup field of a Markup Content component. This approach is best for content that is specific to your Storefront Next storefront.

#### Option 2: Data binding to content assets

Bind the Markup field to a content asset's HTML attribute. This approach is best for content that must be shared across multiple storefront technologies (SFRA and Storefront Next). Content assets are platform-agnostic, so you can update content once and have it reflected across all storefronts.

## Embed Content in Your Storefront

Use `fetchPageWithComponentData` and the `Region` component to load and render content slot page data anywhere in your storefront.

```tsx
import { Region } from "@/components/region";
import { fetchPageWithComponentData } from "@/lib/util/pageLoader";
import type { LoaderFunctionArgs } from "react-router";

export function loader(args: LoaderFunctionArgs) {
  return {
    basket: fetchBasket(args.context),
    // Load content slot page data
    shippingInfo: fetchPageWithComponentData(args, { pageId: "checkout-shipping-info" }),
  };
}

export default function CheckoutPage({ loaderData }) {
  return (
    <div>
      <h1>Checkout</h1>
      {/* Your page content */}

      {/* Embedded content from Page Designer */}
      <aside className="mt-8">
        <Region page={loaderData.shippingInfo} regionId="content" />
      </aside>
    </div>
  );
}
```

Content updates in Business Manager are reflected immediately without code changes.

## Content Slot Workaround Limitations

- No dedicated APIs for content slot management—uses the same `fetchPageWithComponentData` as regular pages.
- No caching or CDN strategies specific to embedded content.
- Merchants must navigate to Page Designer to edit content—no inline editing where it's embedded.
- You must create a "page" in Business Manager for content that isn't actually a full page.

When the "Embedded Content" feature ships, migrate your content slot pages to the new system and update component references to the new API.

## Quick Reference

### Component Checklist

- [ ] `@Component` decorator with `id`, `name`, `group`, `description`
- [ ] `@AttributeDefinition` for each configurable prop
- [ ] `@RegionDefinition` if component contains nested regions
- [ ] `export function fallback()` - lightweight loading state
- [ ] `export default` - main component
- [ ] `export const loader` - if data loading needed

### Page Checklist

- [ ] `@PageType` decorator with `name`, `description`, `supportedAspectTypes`
- [ ] `@RegionDefinition` for each region in the page
- [ ] `export class [Name]Metadata {}` - metadata class
- [ ] `<Region>` components with matching `regionId`

### Commands

| Command                   | Purpose                                   |
| ------------------------- | ----------------------------------------- |
| `pnpm build`              | Build the app and generate cartridge.     |
| `pnpm cartridge:generate` | Generate cartridge metadata only.         |
| `pnpm push`               | Deploy cartridge to MRT and B2C Commerce. |

<!-- document id=cc6880c4ec73ec12bdaf8985c8dcb94b3bec988a77dc75a7580aed3b2ab2372a url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-overview.md -->

# Migrate from PWA Kit to Storefront Next

If you're a PWA Kit developer and are building a Storefront Next storefront, learn about the differences in the technologies and architecture used in PWA Kit and Storefront Next. Storefront Next keeps the same B2C Commerce backend model as PWA Kit (SCAPI, SLAS, and Managed Runtime), but it shifts implementation patterns across the stack. The storefront architecture shifts from a client-heavy, hook-driven architecture in PWA Kit to a server-first architecture built on React Router 7, Vite, and TypeScript in Storefront Next.

## Differences in Project Configuration and the Development Workflow

The PWA Kit and Storefront Next are structured, configured, built, and deployed differently. Migrate a custom Webpack-based workflow in PWA Kit to a more convention-driven Vite and TypeScript workflow in Storefront Next.

### Project Structure

PWA Kit organizes most app code under `app/` with centralized route definitions and explicit runtime entry files. Storefront Next shifts to `src/`, file-based routes, and framework conventions around root and route modules. The outcome is a more convention-driven layout with clearer boundaries for routes, providers, middleware, and adapters.

→ [Project Structure Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-project-structure.md)

### Project Configuration

PWA Kit uses JavaScript configuration with looser runtime validation and flatter structures. Storefront Next introduces typed config definitions, structured namespaces, and an environment-variable override model designed for safer server-client separation. Access patterns also become more context-aware on the server and hook-based in React components.

→ [Project Configuration Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-project-config.md)

### Build Tools

PWA Kit relies on Webpack, Babel, and Jest with multiple build concerns split across separate configs. PWA Kit supports TypeScript optionally through Babel while Storefront Next has TypeScript as a first-class citizen with strict mode enabled. Storefront Next standardizes on Vite, Vitest, and TypeScript-first configuration, which reduces config complexity and speeds up local iteration through faster startup and hot updates. Code splitting and bundle analysis also become more route- and chunk-oriented by default.

→ [Build System Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-build-tools.md)

### Development Workflow

PWA Kit development is driven by Webpack dev tooling and JavaScript-centric config. Storefront Next uses Vite and TypeScript for a faster, more integrated workflow with tighter feedback loops and stronger type safety. Operationally, teams typically see faster local startup, faster HMR, and more consistent tooling across dev/build/test tasks.

→ [Development Workflow Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-dev-workflow.md)

### Deployment

PWA Kit uses a traditional Webpack-based development server with configuration spread across multiple files. Storefront Next leverages Vite for faster development with native ESM, instant HMR, and type-safe configuration. The shift to Vite provides a more modern developer experience with faster feedback loops and better tooling integration.

→ [Deployment Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-deployment.md)

## Differences in Data Fetching, State Management, Storage, and Rendering

The runtime data and app state in PWA Kit is a client-heavy model while it’s a server-first model in Storefront Next. Learn about the rendering, caching, and session handling changes in Storefront Next that affect performance, security, and migration strategy.

### Data Fetching, Suspense, and Loading States

PWA Kit follows a fetch-on-render model where hooks request data during component render and expose manual loading flags. Storefront Next follows fetch-then-render with route loaders that gather data before component rendering, enabling Suspense and streaming patterns more naturally. This moves data concerns out of presentation components and simplifies loading orchestration.

PWA Kit typically handles loading imperatively with `isLoading` checks and manual fallbacks. Storefront Next uses React Suspense and promise-based route data consumption for declarative loading boundaries. This mechanism enables finer-grained streaming and less repetitive loading logic. To migrate to Storefront Next, refactor conditional loading branches into an explicit boundary or fallback design.

→ [Data Fetching and Loading States Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-data-fetching.md)

### State Management

While PWA Kit employs a stateless server architecture paired with TanStack Query for client-side caching, Storefront Next uses HTTP cookies for session persistence.

PWA Kit is stateless on the server side — all pages are server-rendered from the perspective of an unauthenticated (guest) shopper. On the client side, PWA Kit relies on TanStack Query (formerly React Query) as its primary mechanism for caching API responses and managing asynchronous state, supplemented by React Context for local state propagation.

Storefront Next uses HTTP cookies to persist authentication and basket state across requests, and React Context for client-side state management. The framework is unopinionated about state management beyond these defaults; developers are free to integrate the state management solution of their choice and customize the project to fit their requirements.

→ [State Management Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-state-management.md)

### Basket Management

PWA Kit and Storefront Next both use SCAPI baskets, but they differ in where basket state is managed and when full basket data is hydrated. Storefront Next emphasizes middleware-driven basket snapshots and loader/action-based updates with lazy hydration by default.

→ [Basket Management Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-basket-management.md)

### Rendering

PWA Kit SSR is Express-oriented with React Query hydration and optional island-style hydration controls. Storefront Next uses React Router framework SSR with loader-driven data flow, middleware chains, and native streaming/Suspense patterns. This rendering model reduces SSR boilerplate and aligns rendering behavior more directly with route modules.

→ [Server-Side Rendering (SSR) Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-rendering.md)

<!-- ### Caching

PWA Kit is optimized for broad CDN cache reuse by serving mostly non-personalized server-side rendering (SSR) and applying personalization after hydration. Storefront Next enables more server-side personalization by using cookie context in loaders, which improves first-view relevance for users but can reduce shared CDN cacheability for personalized responses. Cache-control logic also moves from component/server-context patterns to explicit response handling in loaders and middleware.

→ [Caching Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-caching.md) -->

### Storage and Sessions

PWA Kit auth/session data often spans both server and client, including localStorage token usage in common patterns. Storefront Next centralizes auth on the server and uses `httpOnly` cookies as the primary session/token mechanism. This mechanism improves security posture and SSR consistency by reducing client-side token handling.

→ [Storage and Sessions Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-storage-sessions.md)

## Differences in API Integration and Routing

Find out how API calls, server handlers, and route definitions are organized in each storefront architecture. Transition from component-level hooks and centralized routing in PWA Kit to loader and action patterns, and file-based routing.

### API Integration

In PWA Kit, API usage is centered on `@salesforce/commerce-sdk-react` hooks and provider-based auth/caching inside components. In Storefront Next, API calls move into route loaders and actions through generated Salesforce B2C Commerce API (SCAPI) clients based on OpenAPI specs. The APIs are provided in the `@salesforce/storefront-next-runtime/scapi` package. Auth is applied through middleware and cache behavior controlled by router revalidation. The result is a thinner client runtime and clearer separation between read and write operations.

→ [API Integration Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-api-integration.md)

### Server Routes

PWA Kit server routes are typically centralized as Express handlers in SSR server code. Storefront Next replaces that with file-based resource routes, and loader and action handlers using standard Web `Request`/`Response` APIs. This routing approach distributes server behavior across route modules and aligns API endpoints with routing conventions.

→ [Server Routes Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-server-routes.md)

### Routing

PWA Kit uses React Router 5 with programmatic route arrays and manual splitting patterns. Storefront Next uses React Router 7 file-based routing with native nested layouts, typed loaders and actions, and automatic route-level splitting. Migrating generally means converting centralized route configuration into route files and moving route data logic into exports.

→ [Routing Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-routing.md)

## Differences in Styling, Components, Static Assets, and SEO

Check out front-end implementation differences between PWA Kit and Storefront Next, including UI composition, styling systems, asset handling, and metadata patterns. Map Chakra and PropTypes-era patterns in PWA Kit to the TypeScript-first and utility-class approach in Storefront Next.

### Styling

PWA Kit styling is largely Chakra CSS-in-JS with prop-based responsive and variant systems. Storefront Next styling centers on Tailwind utility classes, CSS variables, and class-variant composition. The migration is primarily a syntax and architecture shift from style props/theme objects to utility classes and typed variant helpers.

→ [Styling Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-styling.md)

### Components

PWA Kit components are typically JavaScript + PropTypes with Chakra primitives and style props. Storefront Next components are TypeScript-first and composed from Radix/shadcn patterns with utility-class styling and CVA-based variants. The main shift is from runtime styling and theme objects to compile-time class composition and typed component contracts.

→ [Component Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-components.md)

### Static Assets

PWA Kit uses Webpack-era asset helpers, sprite-based icon patterns, and custom responsive image utilities. Storefront Next adopts Vite-native asset resolution, direct public paths and imports, and component-based responsive image handling with modern preload behavior. Teams typically replace helper-heavy patterns with simpler import and path conventions.

→ [Static Assets Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-static-assets.md)

### SEO and Metadata

PWA Kit commonly uses `react-helmet` and supports dynamic API-driven meta tags in current implementations. Storefront Next uses the built-in React Router head/meta capabilities.

→ [SEO and Metadata Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-seo-metadata.md)

<!-- document id=4f878e9c4544560f7d10109e2c09450dc198c4a1e805ad45498b3de69bf03069 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/migrate-mulesoft-http-connector.md -->

# Migrate to the MuleSoft HTTP Connector

The Salesforce B2C Commerce Data Connector and Salesforce B2C Commerce Shop Connector are deprecated and replaced with the MuleSoft HTTP Connector.

If you have existing Mule apps that currently use the Salesforce B2C Commerce Connectors, use the following steps as a blueprint to migrate to the MuleSoft HTTP Connector.

## Salesforce B2C Commerce Data Connector - Mule 4

The Salesforce B2C Commerce Data Connector has two main elements. Both need to be migrated to the MuleSoft HTTP Connector `request` operation:

- B2C Commerce Data Connector global configuration
- Message flow containing the Salesforce B2C Commerce Data Connector operation

### Migrate the B2C Commerce Data Connector Global Configuration

You must migrate the `am-oauth2-configuration` to the `mule-oauth-module` extension of the HTTP Connector.

For details, see [Configure OAuth2 Client Credentials Grant Type Authentication](https://docs.mulesoft.com/http-connector/latest/http-authentication#oauth2-client-authentication).

1. Make sure the **HTTP Connector** is a dependency in your project, for example:

```xml
<dependency>
    <groupId>org.mule.connectors</groupId>
    <artifactId>mule-http-connector</artifactId>
    <version>1.10.3</version>
    <classifier>mule-plugin</classifier>
</dependency>
```

2. Add the **mule-oauth-module extension** to your project, for example:

```xml
<dependency>
    <groupId>org.mule.modules</groupId>
    <artifactId>mule-oauth-module</artifactId>
    <version>1.1.21</version>
    <classifier>mule-plugin</classifier>
</dependency>
```

3. Create an **HTTP Request configuration** as a global configuration element. This is used in all flows.

   ![MuleSoft Data connector HTTP configuration settings](https://developer.salesforce.com/docs/media/commerce-api/mule-data-connector-http-config.png '{"class": "image-lg image-framed"}')

4. For **Authentication**, select **Client credentials grant type**.

   ![MuleSoft Data connector global properties configuration for client credentials grant type](https://developer.salesforce.com/docs/media/commerce-api/mule-data-connector-global-props1.png '{"class": "image-lg image-framed"}')

5. Specify **Protocol** and **Host** properties.

   ![MuleSoft Data connector global properties configuration for protocol and host](https://developer.salesforce.com/docs/media/commerce-api/mule-data-connector-global-props2.png '{"class": "image-lg image-framed"}')

6. Configure the new **`http:request-config` properties** with the following values from your existing **am-oauth2-config**.

**note:** Make sure `scopes` contains the scope for your instance, for example: `SALESFORCE_COMMERCE_API:bjms_dev`.

| `http:request-config` property name | Value        | Copy from `am-oauth2-config` |
| ----------------------------------- | ------------ | ---------------------------- |
| host                                | baseUri      | Yes                          |
| protocol                            | HTTPS        | No, static value             |
| clientId                            | clientId     | Yes                          |
| clientSecret                        | clientSecret | Yes                          |
| scopes                              | scopes       | Yes                          |
| tokenUrl                            | tokenUrl     | Yes                          |

The global HTTP Request Configuration with OAuth authentication is now fully configured.

#### XML Views Before and After Migration

Before migration:

```xml
<commerce-cloud-dataapi:am-oauth2-config
    name="Commerce_Cloud_B2C_Data_Connector_Am_oauth_2_config"
    doc:name="Commerce Cloud B2C Data Connector Am oauth 2 config"
    doc:id="11bc93bc-e1aa-4004-bae3-f8570173fdf2"
>
    <commerce-cloud-dataapi:am-oauth2-connection baseUri="<url>">
        <commerce-cloud-dataapi:oauth-client-credentials
            clientId="<clientID>"
            clientSecret="<clientSecret>"
            scopes="SALESFORCE_COMMERCE_API:bjms_dev sfcc.example sfcc.products.rw sfcc.products"
            tokenUrl="<tokenURL>"
       />
    </commerce-cloud-dataapi:am-oauth2-connection>
</commerce-cloud-dataapi:am-oauth2-config>
```

After migration:

```xml
<http:request-config name="HTTP_Request_configuration" >
    <http:request-connection host="<url>" protocol="HTTPS>
    <http:authentication>
        <oauth:client-credentials-grant-type
        clientId="<clientID>"
        clientSecret="<clientSecret>"
        tokenUrl="<tokenURL>"
        scopes="SALESFORCE_COMMERCE_API:bjms_dev sfcc.example sfcc.products.rw sfcc.products" />
    </http:authentication>
    </http:request-connection>
</http:request-config>
```

### Migrate the Message Flow Containing the Salesforce B2C Commerce Data Connector Operation

All `commerce-cloud-dataapi` operations have an `organizationId`, `config-ref`, `version_ property`, and various additional properties corresponding to the operation, for example, `get-product` has a `productId`:

```xml
<flow name="DataConnectorMigrationFlow"
    doc:id="adf832b2-733e-4e18-8fb9-c35570c81083"
>
    <http:listener
        doc:name="Listener"
        doc:id="b381c6c5-b5c8-4f12-bed7-f0e0df1d6076"
        config-ref="HTTP_Listener_config"
        path="/test" />
    <commerce-cloud-dataapi:get-product-products-organizations-products-by-version-organization-id-product-id
        doc:name="Get Product"
        doc:id="6b1b33d9-86c8-458f-89fe-9b35272bd6fe"
        config-ref="Commerce_Cloud_B2C_Data_Connector_Config"
        version="v1"
        organizationId="f_ecom_bjms_dev"
        productId="apple-ipod-classic"
    />
</flow>
```

Migrate all flows in your application using the following steps:

1. Copy your existing flow.
2. In the copy of the flow, remove the **commerce-cloud-dataapi** operation.
3. Add the **http:request** operation to the corresponding place in the flow.
4. In the **Mule Palette** view, select **HTTP > Request**.
5. Drag **Request** to the Studio canvas and the flow.
6. Select the plus sign (+) next to the **Connector configuration** field to configure the previously created global HTTP Request Configuration with OAuth authentication, as shown in the following example. For details, see: [Migrate to global configuration using mule-oauth-module extension](#migrate-the-b2c-commerce-data-connector-global-configuration).

```xml
<flow name="HTTPConnectorFlow"
    doc:id="23142ccf-73ed-4711-8ae0-322d8996d374"
>
    <http:listener
      doc:name="Listener"
      doc:id="ac5d6ce1-260e-4147-a0bb-8e1fa0d430ec"
      config-ref="HTTP_Listener_config"
      path="/test2"
   />
    <http:request
      method="GET"
      doc:name="Request"
      doc:id="8825fb47-cb94-4b9d-a2e6-5afd927389c1"
      config-ref="HTTP_Request_configuration"
      path="/product/products/v1/organizations/f_ecom_bjms_dev/products/apple-ipod-classic"/>
</flow>
```

7. Configure the new **http:request properties** with the following values from your existing `commerce-cloud-dataapi` operation. You can get API details for your operation from [SCAPI Reference documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), for example: [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/products?meta=getProduct).

![MuleSoft Data connector API flow configuration details](https://developer.salesforce.com/docs/media/commerce-api/mule-data-connector-flow-api-details.png '{"class": "image-lg image-framed"}')

8. Copy the method and path with placeholders from the applicable documentation, for example: `/product/products/v1/organizations/{organizationId}/products/{productId}`.

9. Add URI parameter, query parameter, body, and header to the **HTTP Connector** **request operation**.

| `http:request` property name        | Value                                                                                                                                                              |                                                                                                                                                                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| config-ref                          | HTTP_Request_configuration                                                                                                                                         | See: [Migrate to global configuration using mule-oauth-module extension](#migrate-the-b2c-commerce-data-connector-global-configuration) for the previously created `http:request-config` property name. |
| method                              | Copy operation from [**SCAPI documentation**](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html) \*\*\*\* (GET) | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)                                                                                   |
| path                                | Copy path with placeholder from [**SCAPI documentation**](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)    | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)                                                                                   |
| base URI parameter {organizationId} | commerce-cloud-dataapi : organizationId                                                                                                                            | Copy from commerce-cloud-dataapi operation property `organizationId`.                                                                                                                                         |
| additional URI parameter            |                                                                                                                                                                    | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable                                                                    |
| Query parameter                     |                                                                                                                                                                    | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable                                                                    |
| Body                                |                                                                                                                                                                    | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable                                                                    |
| Header                              |                                                                                                                                                                    | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable                                                                    |

For details, see the following documentation:

- [Configure URI Parameters](https://docs.mulesoft.com/http-connector/latest/http-request-ref#configure-uri-parameters)
- [Configure Dynamic Parameters and Headers](https://docs.mulesoft.com/http-connector/latest/http-request-ref#configure-dynamic-parameters-and-headers)
- [Send Form Parameters](https://docs.mulesoft.com/http-connector/latest/http-request-ref#send-form-parameters)

![MuleSoft Data connector API parameter configuration details](https://developer.salesforce.com/docs/media/commerce-api/mule-data-connector-flow-api-parm-details.png '{"class": "image-lg image-framed"}')

10. If required, add additional configuration according to **HTTP Connector** capabilities:

- [Configure HTTP Request Operation](https://docs.mulesoft.com/http-connector/latest/http-request-ref)
- [HTTP Request Attributes Reference](https://docs.mulesoft.com/http-connector/latest/http-documentation#HttpRequestAttributes)
- [Mule 4 Thread Pools and Tuning apps](https://docs.mulesoft.com/mule-runtime/latest/intro-engine#thread-pools-and-tuning-apps)

#### App Flow Before and After Migration

| Commerce Data Connector                                                                                                                                              | HTTP Connector                                                                                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>Listener</li><li>Get Product (Commerce Data Connector operation)</li></ul>                                                                                   | <ul><li>Listener</li><li>Get Product (HTTP Connector Request operation)</li></ul>                                                                               |
| ![MuleSoft application flow diagram for Data API connector integration](https://developer.salesforce.com/docs/media/commerce-api/mule-data-connector-app-flow.png '{"class": "image-lg image-framed"}') | ![MuleSoft HTTP flow diagram for Data connector processing](https://developer.salesforce.com/docs/media/commerce-api/mule-data-connector-http-flow.png '{"class": "image-lg image-framed"}') |

#### XML Views Before and After Migration

Before migration:

```xml
<flow name="DataConnectorMigrationFlow"
    doc:id="adf832b2-733e-4e18-8fb9-c35570c81083"
>
    <http:listener
        doc:name="Listener"
        doc:id="b381c6c5-b5c8-4f12-bed7-f0e0df1d6076"
        config-ref="HTTP_Listener_config"
        path="/test" />
    <commerce-cloud-dataapi:get-product-products-organizations-products-by-version-organization-id-product-id
        doc:name="Get Product"
        doc:id="6b1b33d9-86c8-458f-89fe-9b35272bd6fe"
        config-ref="Commerce_Cloud_B2C_Data_Connector_Config"
        version="v1"
        organizationId="f_ecom_bjms_dev"
        productId="apple-ipod-classic"
    />
</flow>
```

After migration:

```xml
<flow name="HTTPConnectorFlow"
    doc:id="23142ccf-73ed-4711-8ae0-322d8996d374"
>
    <http:listener
        doc:name="Listener"
        doc:id="ac5d6ce1-260e-4147-a0bb-8e1fa0d430ec"
        config-ref="HTTP_Listener_config"
        path="/test" />

    <http:request
        method="GET"
        doc:name="Request"
        doc:id="8825fb47-cb94-4b9d-a2e6-5afd927389c1"
        config-ref="HTTP_Request_configuration"
        path="/product/products/v1/organizations/{organizationId}/products/{productId}"
    >
        <http:uri-params >
            <![CDATA[#[output application/java
            ---
            {
            "productId" : "apple-ipod-classic",
            "organizationId" : "f_ecom_bjms_dev"
            }]]]>
       </http:uri-params>
    </http:request>
</flow>
```

## Salesforce B2C Commerce Shop Connector - Mule 4

You must migrate all elements of the Salesforce B2C Commerce Shop Connector to the MuleSoft HTTP Connector `request` operation.

**note:** The Salesforce B2C Commerce Shop Connector uses a deprecated auth call, which is no longer supported. For details, see [B2C Commerce API Release Notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html?q=customers%2Factions%2Flogin#09142022) and [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).

### Migrate the B2C Commerce Shop Connector Global Configuration

You must migrate the shopper-token-config objects **shopper-token-connection** and **customer-auth-config** to the HTTP Connector.

![MuleSoft Shop connector general configuration settings](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-general-config.png '{"class": "image-lg image-framed"}')

1. Make sure the **HTTP Connector** is a dependency in your project, for example:

```xml
<dependency>
    <groupId>org.mule.connectors</groupId>
    <artifactId>mule-http-connector</artifactId>
    <version>1.10.3</version>
    <classifier>mule-plugin</classifier>
</dependency>
```

2. Create an **HTTP Request Configuration** as a global configuration element to be used in all flows.

![MuleSoft Shop connector HTTP configuration settings](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-http-config.png '{"class": "image-lg image-framed"}')

**note:** Although the `mule-oauth-module` allows `client-credentials-grant-type`, the configuration does not allow additional parameters that SCAPI requires. Therefore, an additional HTTP Connector Configuration for OAuth is used. For details, see: https://docs.mulesoft.com/http-connector/1.5/http-authentication#oauth2cc.

3. Configure the new `http:request-config` properties with the following values from your existing `shopper-token-connection` and `customer-auth-config`:

| `http:request-config` property name | Value        | Copy from `shopper-token-connection` and `customer-auth-config`? |
| ----------------------------------- | ------------ | ---------------------------------------------------------------- |
| host                                | baseUri      | Yes                                                              |
| protocol                            | HTTPS        | No, static value                                                 |
| clientId                            | clientId     | Yes                                                              |
| clientSecret                        | clientSecret | Yes                                                              |

![MuleSoft Shop connector token configuration and authentication setup](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-token-config.png '{"class": "image-lg image-framed"}')
![MuleSoft Shop connector authentication configuration interface](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-auth-config.png '{"class": "image-lg image-framed"}')

#### XML View

```xml
    <http:request-config
        name="HTTP_Request_Auth_configuration"
        doc:name="HTTP Request configuration"
        doc:id="5be8a127-4b2f-42f3-b1bf-d29b5f0611ac" >
        <http:request-connection
            protocol="HTTPS"
            host="sandbox-001.api.commercecloud.salesforce.com"
        >
            <http:authentication >
                <http:basic-authentication
                    # basic credentials from commerce-cloud-shopper-api:create-shopper-auth-organizations-oauth2-token-by-version-organization-id
                    username="<your username>"
                    password="<your password>" />
            </http:authentication>
        </http:request-connection>
    </http:request-config>

    <http:request-config
        name="HTTP_Request_configuration"
    >
        <http:request-connection
            host="sandbox-001.api.commercecloud.salesforce.com"
            protocol="HTTPS">
        </http:request-connection>
    </http:request-config>
```

### Migrate B2C Commerce Shop Connector Message Flows

All `commerce-cloud-shopper-api` operations have an `organizationId`, `config-ref`, `siteId`, `version_ property` and various additional properties corresponding to the operation, for example: `get-product` has a `productId`.

Migrate these in a manner similar using the previous steps, for example:

```xml
<flow name="ShopConnectorMigrationFlow"
    doc:id="4dc8dc1d-7cd3-4423-9240-1ce3b4e95a0f"
>
    <http:listener
        doc:name="Listener"
        doc:id="ff006824-2ac9-494b-9403-9786fd285734"
        config-ref="HTTP_Listener_config"
        path="/test"
   />
   # Get access token for guest customer
    <commerce-cloud-shopper-api:create-shopper-auth-organizations-oauth2-token-by-version-organization-id
        doc:name="Get Access Token"
        doc:id="347fcaa3-639e-451a-ae7f-5f5c6ce49c35"
        config-ref="Commerce_Cloud_B2C_Shop_Connector_Shopper_token_config"
        version="v1"
        organizationId="f_ecom_bjms_dev"
        authorization="Basic <your basic credentials>"
    >
        <commerce-cloud-shopper-api:custom-query-params >
            <![CDATA[#[output application/java
                ---
                {
                    "grant_type" : "client_credentials",
                    "channel_id" : "SiteGenesis"
            }]]]>
        </commerce-cloud-shopper-api:custom-query-params>
        <commerce-cloud-shopper-api:custom-headers >
            <![CDATA[#[output application/java
                ---
                {
                "Content-Type" : "application/x-www-form-urlencoded"
            }]]]>
       </commerce-cloud-shopper-api:custom-headers>
    </commerce-cloud-shopper-api:create-shopper-auth-organizations-oauth2-token-by-version-organization-id>
    # set authorization access token to variable authorization
    <set-variable
        value='#[&quot;Bearer &quot; ++ payload.access_token]'
        doc:name="Set Authorization"
        doc:id="2afa706f-0569-4c37-a748-cdd5a6abdf60"
        variableName="authorization"
    />
    <commerce-cloud-shopper-api:get-product-shopper-products-organizations-products-by-version-organization-id-id
        doc:name="Get Product"
        doc:id="8cd547ef-1ffc-4719-961e-39a49109004a"
        version="v1"
        config-ref="Commerce_Cloud_B2C_Shop_Connector_Customer_auth_config"
        organizationId="f_ecom_bjms_dev"
        siteId="SiteGenesis"
        id="apple-ipod-classic"
    />
</flow>
```

For a registered shopper, there might be similar flow operation objects containing authorization and authentication, for example:

```xml
<commerce-cloud-shopper-api:create-shopper-auth-organizations-oauth2-login-by-version-organization-id
    doc:name="Authenticate Customer"
    doc:id="432892fb-c84b-44a6-8407-2df7dad561e3"
    config-ref="Commerce_Cloud_B2C_Shop_Connector_Shopper_token_config"
    version="${shopper.version}"
    organizationId="${shopper.orgId}"
    authorization="#[attributes.headers.Authorization]">
            <commerce-cloud-shopper-api:content >
                <![CDATA[#[%dw 2.0
                    output application/x-www-form-urlencoded
                    ---
                    {
                    "grant_type":"authorization_code_pkce",
                    "client_id":"3a15f34e-fecd-4fcc-8235-86b70978e629",
                    "redirect_uri":"http://localhost:9010/callback",
                    "code_challenge": attributes.queryParams.code_challenge,
                    "channel_id": "SiteGenesis"
                   }]]]>
            </commerce-cloud-shopper-api:content>
</commerce-cloud-shopper-api:create-shopper-auth-organizations-oauth2-login-by-version-organization-id>
```

#### App Flow Before and After Migration

| Commerce Shop Connector                                                                                                                                                                                                                              | HTTP Connector                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <ul><li>Listener</li><li>Get Access token (for guest/unregistered customer) (Commerce Shop Connector operation)</li><li>Set variable for jwt-token</li><li>Logger (optional)</li><li>Get Product (Commerce Shop Connector operation)</li></ul> | <ul><li>Listener</li><li>Get Access token (for guest/unregistered customer) (Commerce Shop Connector operation)</li><li>Set variable for jwt-token</li><li>Logger (optional)</li><li>Get Product (HTTP Connector request operation)</li></ul> |
| ![MuleSoft application flow diagram for Shop API connector integration](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-app-flow.png '{"class": "image-lg image-framed"}')                                                                                 | ![MuleSoft HTTP flow diagram for Shop connector data processing](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-http-flow.png '{"class": "image-lg image-framed"}')                                                                                |

Migrate all flows in your application to a flow utilizing the HTTP Connector:

1. Copy your existing flow.
2. In the copy of the flow, remove the `commerce-cloud-dataapi` operation.
3. Add the `http:request` operation to the corresponding place in the flow.
4. In the **Mule Palette** view, select **HTTP > Request**.
5. Drag **Request** to the Studio canvas and the flow.
6. Click the plus sign (+) next to the **Connector configuration** field to configure the previously created global **HTTP Request Configuration**. For details, see: [Global configuration containing the Shop_Connector_Customer_auth_config and Shop_Connector_Shopper_token_config](#migrate-the-b2c-commerce-shop-connector-global-configuration).
7. Configure the new **http:request properties** with the following values from your existing **commerce-cloud-shopapi operation.**

![MuleSoft Shop connector global properties configuration](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-global-props1.png '{"class": "image-lg image-framed"}')
![MuleSoft Shop connector global properties configuration](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-global-props2.png '{"class": "image-lg image-framed"}')

8. Get API details for your operation from the [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), for example:

- [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken)

![MuleSoft Shop connector API flow configuration details](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-flow-api-details.png '{"class": "image-lg image-framed"}')

- [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProduct)

![MuleSoft Shop connector API parameter configuration details](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-flow-api-parm-details.png '{"class": "image-lg image-framed"}')

9. Copy the method and path with placeholders from the applicable documentation, for example:

- /shopper/auth/v1/organizations/{organizationId}/oauth2/token
- /product/products/v1/organizations/{organizationId}/products/{productId}

10. Add URI parameter, query parameter, body and header to the HTTP Connector request operation.

![MuleSoft Shop connector API parameter configuration options](https://developer.salesforce.com/docs/media/commerce-api/mule-shop-connector-flow-api-parm-details2.png '{"class": "image-lg image-framed"}')

For Get Access token (**HTTP Connector** request operation)

| `http:request` property name        | Value                                                                                                                                                       | Notes                                                                                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| config-ref                          | HTTP_Request_Auth_configuration                                                                                                                             | See the previously created `http:request-config` property name, which contains the Basic credentials for Basic auth.                       |
| method                              | Copy operation from [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html) (GET)       | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)                |
| path                                | Copy path with placeholder from [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html) | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)                |
| base URI parameter {organizationId} | `commerce-cloud-shopapi : organizationId`                                                                                                                   | Copy from `commerce-cloud-shopapi` operation property `organizationId`.                                                                    |
| additional URI parameter            |                                                                                                                                                             | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |
| Query parameter                     | `commerce-cloud-shopper-api:custom-query-params` `"grant_type" : "client_credentials", "channel_id" : "SiteGenesis"`                                        | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |
| Body                                |                                                                                                                                                             | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |
| Header                              | `commerce-cloud-shopper-api:custom-headers` `"Content-Type":"application/x-www-form-urlencoded"`                                                            | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |

For Get Product (**HTTP Connector** request operation)

| `http:request` property name        | Value                                                                                                                                                       | Notes                                                                                                                                      |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| config-ref                          | HTTP_Request_configuration                                                                                                                                  | See the previously created `http:request-config` property name.                                                                            |
| method                              | Copy operation from [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html) (GET)       | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)                |
| path                                | Copy path with placeholder from [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html) | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html)                |
| base URI parameter {organizationId} | `commerce-cloud-shopapi` : `organizationId`                                                                                                                 | Copy from `commerce-cloud-shopapi` operation property `organizationId`.                                                                    |
| additional URI parameter            | `commerce-cloud-shopper-api:get-product-shopper-products-organizations-products-by-version-organization-id-id → id`                                         | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |
| Query parameter                     | `commerce-cloud-shopper-api:get-product-shopper-products-organizations-products-by-version-organization-id-id → siteId`                                     | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |
| Body                                |                                                                                                                                                             | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |
| Header                              |                                                                                                                                                             | [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), if applicable |

For additional details, see the following documentation:

- [Configure URI Parameters](https://docs.mulesoft.com/http-connector/latest/http-request-ref#configure-uri-parameters)
- [Configure Dynamic Parameters and Headers](https://docs.mulesoft.com/http-connector/latest/http-request-ref#configure-dynamic-parameters-and-headers)
- [Send Form Parameters](https://docs.mulesoft.com/http-connector/latest/http-request-ref#send-form-parameters)

11. If required, add additional configuration according to **HTTP Connector** capabilities. For details, see the following documentation:

- [Configure HTTP Request Operation](https://docs.mulesoft.com/http-connector/latest/http-request-ref)
- [HTTP Request Attributes Reference](https://docs.mulesoft.com/http-connector/latest/http-documentation#HttpRequestAttributes)
- [Mule 4 Thread Pools and Tuning apps](https://docs.mulesoft.com/mule-runtime/latest/intro-engine#thread-pools-and-tuning-apps)

#### XML Views Before and After Migration

Before migration:

```xml
<flow name="ShopConnectorMigrationFlow"
    doc:id="4dc8dc1d-7cd3-4423-9240-1ce3b4e95a0f"
>
    <http:listener
        doc:name="Listener"
        doc:id="ff006824-2ac9-494b-9403-9786fd285734"
        config-ref="HTTP_Listener_config"
        path="/test"
   />
   # Get jwt-token for guest customer
    <commerce-cloud-shopper-api:create-shopper-auth-organizations-oauth2-token-by-version-organization-id
        doc:name="Get Access Token"
        doc:id="347fcaa3-639e-451a-ae7f-5f5c6ce49c35"
        config-ref="Commerce_Cloud_B2C_Shop_Connector_Shopper_token_config"
        version="v1"
        organizationId="f_ecom_bjms_dev"
        authorization="Basic <your basic credentials>"
    >
        <commerce-cloud-shopper-api:custom-query-params >
            <![CDATA[#[output application/java
                ---
                {
                    "grant_type" : "client_credentials",
                    "channel_id" : "SiteGenesis"
            }]]]>
        </commerce-cloud-shopper-api:custom-query-params>
        <commerce-cloud-shopper-api:custom-headers >
            <![CDATA[#[output application/java
                ---
                {
                "Content-Type" : "application/x-www-form-urlencoded"
            }]]]>
       </commerce-cloud-shopper-api:custom-headers>
    </commerce-cloud-shopper-api:create-shopper-auth-organizations-oauth2-token-by-version-organization-id>

    # set authorization access token to variable authorization
    <set-variable
        value='#[&quot;Bearer &quot; ++ payload.access_token]'
        doc:name="Set Authorization"
        doc:id="2afa706f-0569-4c37-a748-cdd5a6abdf60"
        variableName="authorization"
    />
    # commerce-cloud-shopper-api:shopper-connection
    # configuration parameter > authorization
    <commerce-cloud-shopper-api:get-product-shopper-products-organizations-products-by-version-organization-id-id
        doc:name="Get Product"
        doc:id="8cd547ef-1ffc-4719-961e-39a49109004a"
        version="v1"
        config-ref="Commerce_Cloud_B2C_Shop_Connector_Customer_auth_config"
        organizationId="f_ecom_bjms_dev"
        siteId="SiteGenesis"
        id="apple-ipod-classic"
    />
</flow>
```

After migration:

```xml
<flow name="HTTPConnectorFlow"
    doc:id="aba98309-f8c4-43fd-bf2e-7936738057c6"
>
    <http:listener
        doc:name="Listener"
        doc:id="df9c1b70-ee7e-4497-9504-a2db7dbfedf6"
        config-ref="HTTP_Listener_config"
        path="/test"
   />
   # get jwt-token for guest customer
    <http:request
        method="POST"
        doc:name="Get Access token"
        doc:id="49cc1ca2-4900-4c42-b704-7f0a98923229"
        # http config with basic credentials
        config-ref="HTTP_Request_Auth_configuration"
        path="/shopper/auth/v1/organizations/{organizationId}/oauth2/token">
        <http:headers >
            <![CDATA[#[output application/java
                ---
                {
                    "Content-type" : "application/x-www-form-urlencoded"
                }
            ]]]>
        </http:headers>
        <http:uri-params >
            <![CDATA[#[output application/java
                ---
                {
                    "organizationId" : "f_ecom_bjms_dev"
                }
            ]]]>
        </http:uri-params>
        <http:query-params >
            <![CDATA[#[output application/java
                ---
                {
                    "grant_type" : "client_credentials",
                    "channel_id" : "SiteGenesis"
                }
            ]]]>
        </http:query-params>
    </http:request>
   # set authorization access token to variable authorization
    <set-variable
        value='#["Bearer " ++ payload.access_token]'
        doc:name="Set Authorization"
        doc:id="ab79d83f-4726-4b52-b3eb-8fb23b936a16"
        variableName="authorization"
    />


    <http:request
        method="GET"
        doc:name="Request Get Product"
        doc:id="d6f30c66-0767-4d90-9553-3edd692667e6"
        config-ref="HTTP_Request_configuration"
        path="/product/shopper-products/v1/organizations/{organizationId}/products/{productId}" >
        <http:headers >
            <![CDATA[#[output application/java
                ---
                {
                "Authorization" : "$(vars.authorization)",
                "Content-type" : "application/json"
                }]]]>
       </http:headers>
        <http:uri-params >
            <![CDATA[#[output application/java
                ---
                {
                "organizationId" : "f_ecom_bjms_dev",
                "productId" : "apple-ipod-classic"
                }]]]>
       </http:uri-params>
        <http:query-params >
            <![CDATA[#[output application/java
                ---
                {
                "siteId" : "SiteGenesis"
                }]]]>
            </http:query-params>
    </http:request>
</flow>
```

<!-- document id=1966df4fc5f192bba5680e632c96ed316cba667526a61fe9097d3f79dcb708be url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-migration.md -->

# Migrate to the Storefront Developer Workspace (Beta)

To manage the storefront development lifecycle in one interface, enroll in the Developer Workspace beta. Developer Workspace includes Managed Runtime resources in Business Manager for Storefront Next and Composable Storefront projects that are linked from Managed Runtime. For each storefront, the admin selects Business Manager or Runtime Admin as the tool to use to manage storefront development. Also, the admin also selects the API for that storefront: the SCAPI-based API or the MRT API.

**important:** Developer Workspace is a pilot or beta service that is subject to the Beta Services Terms at [Agreements - Salesforce.com](https://www.salesforce.com/company/legal/agreements/) or a written Unified Pilot Agreement if executed by Customer, and applicable terms in the [Product Terms Directory](https://ptd.salesforce.com/). Use of this pilot or beta service is at the Customer's sole discretion.

## Step 1: Enroll in the Developer Workspace Beta

To turn on the Developer Workspace beta in Business Manager:

1. In the Search box, enter `Feature Switches`, and then select **Feature Switches** from the suggested result.
2. Click **Enable Developer Workspace (Beta)**, and then click **Apply**.

## Step 2: Set Up Admin Permissions

The storefront admin must have write access for the **UI and API Access** permission for the storefront. The Administrator role has this permission by default. During the beta, the admin must also have admin permissions for the corresponding Managed Runtime project. See [Users, Abilities, and Roles](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#users-abilities-and-roles) in [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html). Set up these permissions before you manage the storefront.

## Step 3: Choose an Admin User Interface and API

1. In Business Manager, select **Administration > Sites > Storefronts**, and then click your storefront.
2. Click **Storefront Settings > Management Interface**, and then click **Edit**.

   **important:** This user interface and API selection applies to the whole storefront and to its Managed Runtime project, if the storefront has one. The selection also applies to every environment and to the B2C Commerce instance.

3. Select the admin user interface for the storefront.
   - To use the developer tools in Business Manager as part of the beta, select **Business Manager**.
   - To switch a storefront from Business Manager back to Runtime Admin, select **Runtime Admin**.
4. Under **Storefront APIs**, select the option for your setup. Follow the on-screen instructions to create a SCAPI client and to update your continuous integration and continuous delivery (CI/CD) tools to use the new credentials.
   - **SCAPI**: Select this option to use the SCAPI-based API for Managed Runtime. This option uses the same B2C Commerce (SCAPI) authentication as other B2C Commerce APIs.
   - **SCAPI and MRT**: **(Recommended)** Select this option when you migrate an existing storefront. This option uses the MRT API and the SCAPI-based API. The SCAPI-based API uses SCAPI authentication. If your CI/CD tools use the MRT API, keep both APIs enabled so that automation keeps working while you move that automation to SCAPI.
   - **MRT**: To turn off SCAPI access and use only the MRT API, select this option.
5. Save your changes.

## Step 4: Grant Storefront Permissions to Users

Grant these permissions before users work with storefront environments and deployments.

- Business Manager access to the B2C Commerce instance. An admin grants this access in Account Manager. Add the Business Manager role that includes a filter for the B2C Commerce instance. See [Step 1: Give Users Business Manager Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-users.md#step-1-give-users-business-manager-access).
- Storefront module permissions in Business Manager, and per-storefront management permissions for environments, deployments, environment variables, and URL redirects. See [Step 2: Add Storefront Permissions in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-users.md#step-2-add-storefront-permissions-in-business-manager).
- A Managed Runtime project role for the corresponding Managed Runtime project during the beta. See [Users, Abilities, and Roles](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#users-abilities-and-roles) in [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html).

## Step 5: Create a SCAPI Client and Update Automation

If you chose an API option that includes SCAPI:

1. In Account Manager, create an API client with the `SALESFORCE_COMMERCE_API` role and the `sfcc.storefront.*` scopes. See [Add an API Client in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5) in _Salesforce Help_.
2. Update your CI/CD pipelines, scripts, and developer access to use the API that you selected. Point `b2c mrt` commands at that API. See [Automate Environment Administration with the Managed Runtime API](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-api.html).
3. Configure the `b2c mrt` commands to use SCAPI mode. See [MRT Commands: Authentication](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/mrt.html#authentication).

## Frequently Asked Questions

**Is switching the management interface to Business Manager reversible?** Yes. Switch a storefront back to Runtime Admin, or change the API option, at any time. Runtime Admin always stays available.

**Is this a per-storefront choice or an all-or-nothing switch?** Per storefront. Each storefront is one Managed Runtime project, so the selection applies to every environment for that storefront (development, staging, and production). It doesn't apply to your other storefronts. Move one storefront at a time.

**Do I log in to Runtime Admin?** Yes. Some capabilities remain in Runtime Admin. See the next question.

**What remains in Runtime Admin during the beta?** These stay in Runtime Admin:

- Managed Runtime CDN certificates and hostname (custom domain) management
- Project notifications
- User, API key, and notification management

Everything else (environments, deployments and history, environment variables, URL redirects, and performance monitoring) is available in Business Manager.

**Are Managed Runtime (Account Manager) roles still needed during the beta?** Yes. Business Manager permissions control which actions a user takes in Business Manager. Managed Runtime runs the operation, so assign each user a Managed Runtime project role in Runtime Admin that matches their Business Manager storefront role. Storefront operations require that Managed Runtime role in addition to the Business Manager permissions. This dependency is expected to be removed at GA.

**Who can change a storefront's management interface?** During the beta, a user with **UI and API Access (Write)** in Business Manager and the Admin role on the Managed Runtime project can change the management interface. Business Manager Administrator status in the user's own instance isn't enough. This dependency is expected to be removed at GA.

**Will opting in break my existing CI/CD or scripts?** Existing CI/CD and scripts keep working if the MRT API stays enabled. Select `SCAPI and MRT` so that existing automation keeps working. After your pipelines use SCAPI, switch to `SCAPI`. Only the APIs that you enable can change the storefront, so a pipeline that targets a disabled API stops working.

**Is there an automated way to migrate my Managed Runtime roles to Business Manager?** No. Recreate each role as a Business Manager role. Use the permission model in [Set Up Roles and Permissions for Developer Workspace](https://docs.google.com/document/d/1Ekj9xADPUPoHOTufK8O3WMrYjDsEtDgbrttBP8DtCmM/edit?tab=t.0#heading=h.nu71dd9j2ecr).

**Can I limit a user's access to a single environment?** No. Storefront permissions apply to every environment for a storefront. Scope a role to one storefront or to a group of storefronts in an instance. You can't scope a role to one environment in a storefront. This matches Managed Runtime, where roles apply to the whole project. Scope roles and API clients per instance. For example, withhold production so that a user can't reach its environments.

**Why can't a user see the full storefront list?** The all-storefronts context controls whether a user lists every storefront. Grant the `Storefront` permission (Read) with the context set to all storefronts for roles that browse the complete list. A role scoped only to specific storefronts shows only those storefronts.

## See Also

- [Manage Roles and Permissions for Your Storefront in Business Manager (Beta)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-users.md)
- [Salesforce Help: Roles and Permissions in Business Manager](https://help.salesforce.com/s/articleView?id=cc.b2c_roles_and_permissions.htm)
- [Link an Existing Storefront to B2C Commerce](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-link-storefront.html)
- [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html)

<!-- document id=9b31b0a621ee903018b4ab4f3db9f793035751b3bb42949ef9c0f197869cfc31 url=/developer/current/en-us/commerce-cloud/lwr-migration/guides/store-migration.md -->

# Migrate Your Store

After you create a store using the B2B Commerce (LWR) template, migrate your components and refactor them as necessary. If you invested in LWC, restructured data operations, and implemented wire adapters, you have minimal work to do before your new store is up and running.

1. **Copy Aura components to a new space.** [Create an SFDX project](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_create_sample_lwc_project.htm) and add your Aura component files. A separate project space makes it easier to refactor and change components for LWR. This step also ensures that your existing B2B Commerce Aura store is preserved throughout the migration process.
2. **Replace Aura components with Lightning web components.** This process ideally involves a small number of top-level Aura components handling data access and a few Aura-specific functionalities. Replacement LWC wrappers have the same responsibilities and can use the same LWC child components. For further instruction, see the [Migrate from Aura to Lightning Web Components](https://trailhead.salesforce.com/en/content/learn/trails/migrate-from-aura-to-lightning-web-components) trail. Common changes include:
   1. Shift to wire adapters for data operations. Wire adapters provide easy access to Commerce Connect REST API data. For more information, see [Use the Wire Service to Get Data](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.data_wire_service).
   2. Convert metadata from Aura component design files to the js-meta.xml format of Lightning web components.
   3. Remove references to Aura-specific libraries and components.
   4. Revise nested component structure by consolidating data operations in top-level components and propagating information up component trees using events. This structure follows the data down, events up communication model of LWC.
3. **Adjust references to the Cart page.** To provide a more consistent experience, the Cart page changed from a record page in B2B Commerce Aura to a named page in LWR. As a result, you must update components using the [lightning/navigation library](https://developer.salesforce.com/docs/component-library/bundle/lightning-navigation/documentation) to navigate the cart or generate links to it.

```
// Go to the Cart Page
navigate(this.navContext, {
    type: 'comm__namedPage',
    attributes: {
        name: 'Current_Cart',
    },
});
```

4. **Upgrade component branding and CSS (optional).** Running atop LWR, your B2B store supports more branding and override options using CSS custom properties. Custom components can use more brand-aware values to respond to global changes automatically, and they can more easily expose new customizations. To get started, see [How Branding Works in LWR Sites](https://developer.salesforce.com/docs/atlas.en-us.exp_cloud_lwr.meta/exp_cloud_lwr/brand_overview.htm).
5. **Migrate your B2B Commerce Aura store configuration.** Transfer metadata from your old B2B Commerce Aura store to your new LWR store by creating a change set and applying the store configuration. To complete this step, see [Migrate Your Store Configuration](https://help.salesforce.com/s/articleView?id=commerce.comm_migrate_store.htm&type=5&language=en_US).
6. **Deploy and publish your store.** After you update your store's components, deploy them from Visual Studio Code and place them in your store with Experience Builder. Before publishing your site from Experience Builder, click **Preview** to see how the storefront looks in a desktop browser window and on a mobile device.

<!-- document id=f2602c6ad42126515082880bea63829596696712bc0ba8782db6736e2e520c2e url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/mock-the-base-apex-class.md -->

# Mock the Base Apex Class in Tests

When writing unit tests for an extension provider class, sometimes we want to mock the `super()` method in the extension provider class. However, the Apex test framework does not support mocking objects or methods in a namespace that is different from where test classes are defined. This tutorial provides a workaround to allow us to mock `super()` in the extension provider class. To learn more about Apex’s namespace, refer to [Default Namespaces in Apex](https://developer.salesforce.com/blogs/developer-relations/2012/08/default-namespaces-in-apex) on the Salesforce Developers blog.

The idea is to separate the logic for calling the `super()` default logic so that it can be mocked in the test.

Let’s walk through an example for testing the extension provider class.

Assume we have an extension provider class called `Custom_Inventory` that extends a Base Apex class `CommerceDxSampleapp.CommerceDx_Inventory`.

**note:** The Base Apex Class has its own namespace and is different from the org of the extension provider class.

## Base Apex Class

The base Apex class looks like this:

```java
global virtual class CommerceDxSampleapp.CommerceDx_Inventory {
    global virtual Integer calculateInventoryLevel (String webstoreId, String eventId){
        // Default Logic
        return 0;
    }
}
```

## Extension Provider Class

**note:** The `Custom_Inventory` class belongs to current org's namespace.\_

To create an extension provider, add a class that extends the base Apex class:

```java
public class Custom_Inventory extends CommerceDxSampleapp.CommerceDx_Inventory {
    public override Integer calculateInventoryLevel(String webstoreId, String eventId){
       // Invoke Base Class's default logic
       super.calculateInventoryLevel(webstoreId, eventId);
    }
}
```

## 1. Add "Virtual" to Extension Provider Classes

To make sure that we can mock the default logic, add a method that only calls `super()` and make it overridable by marking it as `virtual`. We also need to mark the class as `virtual`.

```java
public virtual class Custom_Inventory extends CommerceDxSampleapp.CommerceDx_Inventory {
    public override Integer calculateInventoryLevel(String webstoreId, String eventId){
        return callDefault(webstoreId, eventId);
    }

    @TestVisible
    private virtual Integer callDefault(String webstoreId, String eventId){
        // Invoke Base Class's default logic
        return super.calculateInventoryLevel(webstoreId, eventId);
    }
}
```

## 2. Define the Test Class

Next, define the test class. (See [Salesforce Developers](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing_unit_tests.htm) to learn how to write an Apex test.)

### MyTestClass

```java
@isTest
public class MyTestClass {
    @isTest
    public static void testCalculateInventory(){

    }
}
```

## 3. Define the Inner Mock Class

Finally, define an inner mock class called `Fake_Custom_Inventory` to override the logic for the `super()` method that belongs to the base Apex class. Then the test method can use the mock class to return the expected result for the `super()` logic.

```java
@isTest
public class MyTestClass {
    @isTest
    public static void testCalculateInventory(){
        Fake_Custom_Inventory fake_Custom_Inventory = new Fake_Custom_Inventory();
        // Assert the result is the same as mocked result defined below
        String webstoreId = 'fakeWebstoreId';
        String eventId = 'fakeEventId';
        System.assertEquals(-1, fake_Custom_Inventory.calculateInventoryLevel(webstoreId, eventId));
    }

    // Create a mock private class in the test class
    private class Fake_Custom_Inventory extends Custom_Inventory{
        public override Integer callDefault(String webstoreId, String eventId) {
            // Return a mocked result for testing
            return -1;
        }
    }
}
```

<!-- document id=d8a5acca4110201fe02dbfc03c28549d7f667a3ce78bd137b9afd9d4a76ab934 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-modern-exp.md -->

# Modernized Storefront Experience in Storefront Next

Storefront Next delivers a modernized ecommerce experience through the Market Street template. The Product Listing Page (PLP), Product Detail Page (PDP), and My Account page provide an enterprise-grade default interface with comprehensive core commerce capabilities, rich media galleries, advanced discovery controls, AI assistance, and omnichannel integrations.

For implementers, these pages establish a full-feature blueprint that accelerates implementation for the broader integration ecosystem—ratings providers, loyalty programs, Buy Now Pay Later (BNPL) services, store inventory systems, and AI conversational assistants.

## Benefits

- Strong first impression for shoppers: The modern PDP and PLP experiences match the expectations set by flagship brands. A new Storefront Next storefront immediately presents a credible, polished experience, which increases the overall conversion rate.

- Fast time to value: Implementers and merchants start with a proven blueprint instead of rebuilding standard patterns. Because the basic UX scaffolding is already in place, project teams can focus on brand differentiation and integration rather than basic page construction.

- UI components for ecosystem integrations: The storefront exposes standard, stable UI components for ratings, loyalty programs, BNPL providers, and store inventory. These shells give independent software vendors (ISVs) consistent placements to target, minimizing one-off custom front-end work.

- Vertical storefront foundation: A comprehensive but generic PDP and PLP create a reusable base across industries. Implementers can specialize and configure this foundation for verticals like luxury beauty, fashion, or electronics with minimal duplication of effort.

**note:** Some components, such as delivery estimate, ratings, and reviews, are a prototype of the intended storefront experience. They aren't connected to B2C Commerce for data persistence. Although these components render in the UI, their data is temporary and is lost when the page refreshes. To connect these prototyped components to a third-party service, modify their corresponding extensions. See [Extend Storefront Next with Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-extend.md) and [Prototyped UI Components](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-prototyped-cmp.md).

## Product Listing Page (PLP) Features

The PLP offers a rich browsing interface that enables shoppers to find products quickly, increasing conversion rates.

### Discovery

- Enriched product tiles: Display ratings, review counts (provided by a ratings service), and badges that identify items that are new, on sale, online-only, limited editions, or on promotion.
- Filtering: Filter by a store selected in Store Locator and by specific product criteria.
- Sorting: Sort products by best matches, price, top sellers, and so on.
- Omnichannel: If a store inventory integration is active, view store availability and in-store pickup badges on product tiles.
- Merchandising: Use defined content slots above and within the product grid for banners, quizzes, and editorial content.
- Shopper Agent: Access an AI-assisted shopping experience that helps shoppers discover products through a conversational chat interface. Enable and configure Shopper Agent before it's available in Storefront Next. See [Agentforce Shopper Agent for B2C Storefronts](https://help.salesforce.com/s/articleView?id=cc.b2c_agent_guided_shopping.htm&type=5) in _Salesforce Help_.

### Purchasing

- Quick add: View a mini-PDP popup to add a product to the cart without navigating to the full detail page.

![Product listing page in Storefront Next showing products available at a store and badges for in-store pickup](https://developer.salesforce.com/docs/media/sfnext/sfnext-modern-exp.png)

## Product Detail Page (PDP) Features

The PDP gives shoppers detailed product information and flexible purchasing options, which implementers can provide by using payment providers.

### Discovery

- View ratings summary and review count, and an optional AI-generated summary review using provider data. The ratings and reviews section supports pagination or load-more behavior.
- View product recommendations. Implementers can provide data sources for recommendations through adapters.
- View recently viewed items displayed as product tiles.
- Check availability and inventory status: in stock, low stock, out of stock, backorder, and pre-order states.

### Purchasing

- Add the product to the wishlist.
- View a delivery estimate.
- Choose delivery or in-store pickup, or split an order across both fulfillment methods.
- Select a payment option, including payment plans and express payments such as Apple Pay, Google Pay, and Venmo. Implementers can provide payment services through adapters for payment providers, including BNPL providers.

## My Account Page Features

The My Account page is a one-stop shop for managing all aspects of the shopping experience. From this page, shoppers can:

- View recent orders and product recommendations from the overview page.
- View and manage their wishlist.
- View full order history.
- Manage saved addresses.
- Add and manage payment methods.
- View store preferences, including their preferred store and authorized pickup contacts.

![The account menu in Storefront Next](https://developer.salesforce.com/docs/media/sfnext/sfnext-my-account.png '{"class": "image-xs"}')

## Buy Online, Pick Up in Store and Multiple Shipments

Storefront Next supports multiple fulfillment options. Shoppers can mix delivery and in-store pickup, and can ship items to multiple addresses in a single order. Both options are available in the checkout page.

The buy online pick up in-store feature requires store locator. These two features are default extensions in Storefront Next, along with multiple shipments. They're available when you create a storefront with the default extensions. See [Enhance Shopper Experience with Store Locator and In-Store Pickup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-instore-pickup.md).

## Adapters for Implementing Data Sources

With the adapter design pattern, implementers can provide or replace data source implementations of Product Detail Page (PDP), Product List Page (PLP), and My Account page features with third-party services. Examples of such features are loyalty and product reviews. Features don't have to be tightly coupled to specific services or have concrete implementations. Implementers provide adapters by implementing an interface and adding data source implementations, and then packaging adapters in custom cartridges. Admins can install the cartridges in a B2C Commerce instance.

See [Provide Data Source Implementations with Adapters](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-adapters.md).

<!-- document id=ef9e650dfe7a278f816539db3e0e85497708a63b79b0bc1bdeccd7ee0bf62232 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/monitor-maintain.md -->

# Monitor and Maintain

Learn how to perform essential maintenance tasks to keep your site running smoothly after launch. This section contains these guides.

- [Log Files](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-log-files-overview.md): Capture information about system resources, performance, errors, and quotas.
- [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&language=en_US&type=5): Review site errors and metrics.
- [Control Center](https://help.salesforce.com/s/articleView?id=cc.b2c_cc.htm&language=en_US&type=5): Monitor the state of your B2C Commerce instances.
- [Configure Alerts](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_alerts_for_your_site.htm&type=5): Set up notifications about information such as security vulnerabilities or campaign and promotion updates.
- [Maintenance Pages](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/admin/b2c-maintenance-pages.md): If your site is under maintenance, upload custom maintenance pages to show to your shoppers.

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=489502dd271dabad59871dad3788146283d193de59f31f42153ca94783ca37ad url=/developer/current/en-us/commerce-cloud/commerce-api/guides/code-profiler.md -->

# Monitor Code

Use the Code Profiler Business Manager feature to monitor SCAPI API performance and determine where performance bottlenecks are in your custom code. With B2C Commerce 24.4, two new trace types are provided:

- `REST_SCAPI`: For SCAPI system APIs, including Shopper, Admin, and Custom APIs.
- `REST_SCAPI_SCRIPT`: Specifically for the Custom API Scripts. Use this trace type to trace script execution and debug Custom APIs.

Both of these new trace types provide API path information and execution time.

For implementation details, see [Use Code Profiler.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-site-performance.html#use-code-profiler)

<!-- document id=c0eb5b609a2a55cfa7bb3bbe5ac54b8de06e6ec7270948a27bcfcdc00a096ce8 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_monitor_clone.md -->

# Monitor the Cloning Process

Track the progress of clone operations and view details about cloned sandboxes in Control Center.

## View Source Sandbox Status

Once the clone is initiated:

1. The **source sandbox** shows status **Cloning** in the instance list.
2. All actions for the source sandbox are temporarily disabled.
3. The cloning process includes these stages:
   - **Prep Instance**: Validation and preparation
   - **Data Backup**: Creating consistent snapshot
   - **Data Restore**: Provisioning and restoring data
   - **Post Validation**: Configuration and activation
4. When cloning completes, the source sandbox returns to its previous state (Running or Stopped) and all actions are re-enabled.

## View Cloned Sandbox

As the cloned sandbox is created:

1. The **target sandbox** appears in the instance list with status **Setting Up**.
2. When setup completes, the status changes to **Running** (if clone succeeds) or **Failed** (if clone fails).
3. A **Clone** badge appears next to the cloned instance. Click the badge to view clone details:
   - Source instance identifier
   - Target instance identifier
   - Clone timestamp
   - Storefront count
   - Custom code version
   - Database size
   - File system size

<!-- document id=5ea622cb9a5075c9bb05eb9eb8aa7d1fe7f5490e687baeaf5365b1ebc802b978 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-perf-tools.md -->

# Monitor the Performance of Storefront Next

Monitor the performance of Storefront Next at different stages of the app lifecycle, including in-house lab test performance and real-world usage. Create a performance benchmark to use as a future comparison basis.

## Lab Data vs. Field (Real-World) Data

Collect lab data when you develop the app, and field (real-world) data after the app is deployed.

- Lab data is collected from performance tests in a controlled environment. During app development, run performance tests and collect lab data to make sure the app's performance meets performance benchmarks before it's released to customers. For performance tools to use, see [Performance Tools](#performance-tools).
- Field data captures real-world user experiences. After the app is released to production, collect field data, or Real User Monitoring (RUM), from active user sessions, to understand how your app performs in production. For more information, see [Real User Monitoring](#real-user-monitoring).

## Real User Monitoring

To understand real user experience and measure field data, enable RUM data collection using third-party monitoring tools like Datadog, Akamai, or CrUX. With these tools, gain insights into your site's performance, including [Core Web Vitals](#what-are-core-web-vitals).

### Datadog

Datadog provides an SDK that runs in the user's browser after a storefront page loads, collecting data client-side and sending it to Datadog. Datadog RUM injects a lightweight JavaScript SDK (`@datadog/browser-rum`) into your storefront. After it's initialized with your Datadog Application ID and Client Token, the SDK runs in the user's browser and automatically captures performance metrics, user interactions, and resource timings. The SDK then sends that data directly to Datadog's intake servers.

For more information about setting up the Datadog SDK, see [RUM Browser Monitoring](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/) in Datadog Docs.

### Akamai

Akamai mPulse injects a JavaScript library, called Boomerang, into your storefront pages to collect RUM data. If your storefront is already behind Akamai's content delivery network (CDN), this injection can happen automatically at the edge, meaning no code changes are required on the storefront itself. After it loads in the user's browser, Boomerang captures Core Web Vitals, page load timings, and user interactions, then sends the data back to Akamai's mPulse platform for analysis. If your storefront doesn't use Akamai's CDN, add the Boomerang script manually via a script tag or npm package.

For more information about setting up Akamai's mPulse, see [Welcome to mPulse](https://techdocs.akamai.com/mpulse/docs).

### CrUX

CrUX is a public dataset from Google that provides real-world metrics from actual Chrome users and serves as the official source for Google's Web Vitals program. CrUX data includes Chrome web browsers only and doesn't include iOS devices. CrUX data is a 28-day rolling average, meaning performance improvements take time to reflect. CrUX evaluates site performance based on the 75th percentile, requiring 75% of pageviews to meet the "Good" mark for a given metric. It primarily focuses on hard navigations (initial page loads), not soft navigations within Single-Page Applications (SPAs). See [Overview of CrUX](https://developer.chrome.com/docs/crux) in the Google Chrome documentation.

Google uses field data from CrUX for page experience ranking, not lab-based Lighthouse scores. The ultimate goal is to ensure at least 75% of real users pass Core Web Vitals thresholds.

**note:** Users must meet certain criteria to have their experiences aggregated in the CrUX dataset. To learn more, see [User](https://developer.chrome.com/docs/crux/methodology#user-eligibility) in [CrUX methodology](https://developer.chrome.com/docs/crux/methodology) in the Chrome for Developers documentation.

## What Are Core Web Vitals?

Core Web Vitals is a set of metrics that measure real-world user experience for three key aspects of the page: loading performance, interactivity, and visual stability.

- **Largest Contentful Paint (LCP):** Measures how long it takes for the largest image or text block to appear. The goal is 2.5 seconds or less. See [Largest Contentful Paint](https://web.dev/articles/lcp).
- **Interaction to Next Paint (INP):** Measures page responsiveness to user input. The goal is 200 milliseconds or less. See [Interaction to Next Paint (INP)](https://web.dev/articles/inp).
- **Cumulative Layout Shift (CLS):** Measures unexpected content shifts during loading. The goal is 0.1 or less. See [Cumulative Layout Shift](https://web.dev/articles/cls).

**See Also**

- [Understanding Core Web Vitals and Google search results](https://developers.google.com/search/docs/appearance/core-web-vitals)

## Benchmarking and Regression Detection

During app development, perform initial performance testing to create a benchmark that you can compare future performance test results against.

To set up a performance test that simulates your customers' experience, know your customers' setup and choose settings that represent your average customer. Define performance goals, for example, [LCP](#what-are-core-web-vitals) < 2.5 seconds, and track them throughout app development. If future test results show slower performance, your app has regressed. Investigate which change introduced the regression.

Use continuous integration practices to catch and fix regressions early before release. With continuous integration, code changes get merged frequently to a shared source code repository, triggering automated builds and tests. Add these tools to your development workflow, such as [Google Chrome Lighthouse](https://github.com/GoogleChrome/lighthouse-ci) or [WebPageTest](https://www.webpagetest.org/).

## Performance Tools

Use these commonly used tools to measure the performance of your app.

- **(Recommended)** If your B2C organization is enrolled in the Developer Workspace Beta, view Core Web Vitals and other metrics in Business Manager in the storefront's Monitoring page. Go to **Administrations > Sites > Storefronts > _Your Storefront_ > Monitoring**. For an environment that's marked as production, analyze Core Web Vital metrics and identify any bottlenecks and opportunities to improve the storefront performance. Add a zone and hostname to be able to view performance metrics. See [Monitor Storefront Performance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-developer-workspace.md#monitor-storefront-performance).
- **(Recommended)** [WebPageTest](http://webpagetest.org/). A web performance testing tool with AI-powered analytics, dashboards, and real user monitoring (RUM).
- [Google Lighthouse](https://developers.google.com/web/tools/lighthouse): Open-source, automated tool to help you improve the quality of web pages. It has audits for performance, accessibility, SEO, and more. To run Lighthouse during continuous integration (CI) and continuous delivery (CD) with the CLI, first run a production build with `pnpm build` and then run Lighthouse with `pnpm lighthouse:ci`. Running this command can help warn or block builds if a quality threshold isn't met.
- [PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/): Reports on the user experience of a page on both mobile and desktop devices, and provides suggestions on how that page can be improved.
- Browser developer tools. For example, for Chrome dev tools, see [Coverage: Find unused JavaScript and CSS](https://developer.chrome.com/docs/devtools/coverage) and [Performance panel: Analyze your website's performance](https://developer.chrome.com/docs/devtools/performance/overview).
- [Chrome User Experience Report (CrUX)](https://developer.chrome.com/docs/crux/): Publicly available performance data per user in Chrome.

## Debugging Tips and Metrics

To effectively audit and monitor performance, use these metrics and debugging tips.

### Performance Metrics

- Core Web Vitals
  - Largest Contentful Paint (LCP)
  - Interaction to Next Paint (INP)
  - Cumulative Layout Shift (CLS)
- Time to First Byte (TTFB)
- Total Blocking Time (TBT)
- CDN cache hit ratio

For a description of performance metrics, see [What Are Core Web Vitals?](#what-are-core-web-vitals) and [Time to First Byte (TTFB)](https://web.dev/articles/ttfb). To learn more about TBT, see [Total Blocking Time (TBT)](https://web.dev/articles/tbt) in [web.dev](https://web.dev/).

### B2C Commerce Metrics Dashboard for Managed Runtime (MRT)

Use the [Metrics Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_metrics_dashboard.htm&type=5) in your B2C Commerce instance to monitor MRT metrics collected while the app is running. For example, monitor the Request Time and Cache Hits (Ratio) metric.

To access the Metrics Dashboard, in App Launcher ![App launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png '{"class": "image-icon-sm"}'), select **Log Center**, and then click **Metrics**.

<!-- document id=9285c1235ea4891b2e48b53d61c30f43bcf5d193a746cbf1b56ad4b132b3d4dd url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/perf-monitor.md -->

# Monitor the Performance of Your Storefront

Monitor the performance of your PWA kit-based storefront at different stages of the app lifecycle, including in-house lab test performance and real-world usage. Create a performance benchmark to use as a future comparison basis.

## Lab Data vs. Field (Real-World) Data

Collect lab data when you develop the app, and field (real-world) data after the app is deployed.

- Lab data is collected from performance tests in a controlled environment. During app development, run performance tests and collect lab data to make sure the app's performance meets performance benchmarks before it's released to customers. For performance tools to use, see [Performance Tools](#performance-tools).
- Field data captures real-world user experiences. After the app is released to production, collect field data, or Real User Monitoring (RUM), from active user sessions, to get an idea of how your app is performing in the real world on the web. See the next section for more information about Chrome User Experience Report and Google's Core Web Vitals.

## Real World Monitoring

To understand real user experience, measure field data using some common monitoring tools, such as Chrome User Experience Report (CrUX), or other third-party tools, such as Datadog or Akamai.

## What Is CrUX?

CrUX is a public dataset from Google that provides real-world metrics from actual Chrome users and serves as the official source for Google's Web Vitals program. CrUX data is a 28-day rolling average, meaning performance improvements take time to reflect. CrUX evaluates site performance based on the 75th percentile, requiring 75% of pageviews to meet the "Good" mark for a given metric. It primarily focuses on hard navigations (initial page loads), not soft navigations within Single-Page Applications (SPAs). CrUX doesn't include iOS devices. See [Overview of CrUX](https://developer.chrome.com/docs/crux) in the Google Chrome documentation.

Google uses field data from CrUX for page experience ranking, not lab-based Lighthouse scores. The ultimate goal is to ensure at least 75% of real users pass Core Web Vitals thresholds.

**note:** Users must meet certain criteria to have their experiences aggregated in the CrUX dataset. To learn more, see [User](https://developer.chrome.com/docs/crux/methodology#user-eligibility) in [CrUX methodology](https://developer.chrome.com/docs/crux/methodology) in the Chrome for Developers documentation.

## What Are Core Web Vitals?

Core Web Vitals is a set of metrics that measure real-world user experience for three key aspects of the page: loading performance, interactivity, and visual stability.

- **Largest Contentful Paint (LCP):** Measures how long it takes for the largest image or text block to appear. The goal is 2.5 seconds or less. See [Largest Contentful Paint](https://web.dev/articles/lcp).
- **Interaction to Next Paint (INP):** Measures page responsiveness to user input. The goal is 200 milliseconds or less. See [Interaction to Next Paint (INP)](https://web.dev/articles/inp).
- **Cumulative Layout Shift (CLS):** Measures unexpected content shifts during loading. The goal is 0.1 or less. See [Cumulative Layout Shift](https://web.dev/articles/cls).

**See Also**

- [Understanding Core Web Vitals and Google search results](https://developers.google.com/search/docs/appearance/core-web-vitals)

## Benchmarking and Regression Detection

During app development, perform initial performance testing to create a benchmark that you can compare future performance test results against.

To set up a performance test that simulates your customers' experience, it is important to know your customers' setup and choose settings that represent your average customer. Define performance goals, for example, [LCP](#what-are-core-web-vitals) < 2.5 seconds, and track them throughout app development. If future test results show slower performance, this means that your app regressed and you can investigate which change introduced the performance regression.

We recommend you use continuous integration practices to catch and fix regressions early before release. With continuous integration, code changes get merged frequently to a shared source code repository, triggering automated builds and tests. Integrate continuous integration tools in your development workflow, such as [Google Chrome Lighthouse](https://github.com/GoogleChrome/lighthouse-ci) or [WebPageTest](https://www.webpagetest.org/).

## Performance Tools

Here are some commonly used tools to measure the performance of your app.

- **(Recommended)** [WebPageTest](http://webpagetest.org/). A web performance testing tool with AI-powered analytics, dashboards, and real user monitoring (RUM).
- [Google Lighthouse](https://developers.google.com/web/tools/lighthouse): Open-source, automated tool to help you improve the quality of web pages.
- [PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights/): Reports on the user experience of a page on both mobile and desktop devices, and provides suggestions on how that page can be improved.
- Browser developer tools. For example, for Chrome dev tools, check out [Coverage: Find unused JavaScript and CSS](https://developer.chrome.com/docs/devtools/coverage) and [Performance panel: Analyze your website's performance](https://developer.chrome.com/docs/devtools/performance/overview).
- [Chrome User Experience Report (CrUX)](https://developer.chrome.com/docs/crux/): Publicly available performance data per user in Chrome.

## Debugging Tips and Metrics

To effectively audit and monitor performance, use these metrics and debugging tips.

### Performance Metrics

- Core Web Vitals
  - Largest Contentful Paint (LCP)
  - Interaction to Next Paint (INP)
  - Cumulative Layout Shift (CLS)
- Time to First Byte (TTFB)
- Total Blocking Time (TBT)
- CDN cache hit ratio

For a description of performance metrics, see [What are Core Web Vitals?](#what-are-core-web-vitals) and [Time to First Byte (TTFB)](https://web.dev/articles/ttfb). To learn more about TBT, see [Total Blocking Time (TBT)](https://web.dev/articles/tbt) in [web.dev](https://web.dev/).

### B2C Commerce Metrics Dashboard

Use the [Metrics Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_metrics_dashboard.htm&type=5) in your B2C Commerce instance to gather field data and monitor the performance of the app while it's running. For example, you can check out these metrics.

- Managed Runtime metrics: Request Time and Cache Hits (Ratio)
- Overall Application Metrics: Storefront requests

To access the Metrics Dashboard, in App Launcher ![App launcher](https://developer.salesforce.com/content/media/shared/appLauncher.png '{"class": "image-icon-sm"}'), select **Log Center**, and then click **Metrics**.

### PWA Kit-Specific Debugging Tips

- Append `?__server_timing=true` to your URL to get a Server-Timing header breaking down SSR process times.
- Append `?__server_only` to view the pure, server-rendered version of a page without client-side JavaScript.

<!-- document id=beaff557fdfe4879779392be838e2209d5f963af9775a8300246591f94e53099 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/monitor-site.md -->

# Monitor Your PWA Kit Site

Use observability tools to monitor the performance of your Progressive Web App (PWA) Kit site. Site performance is a shared responsibility model: you're responsible for the performance of project customizations and Salesforce is responsible for the performance of the B2C Commerce platform.

This guide summarizes how to use platform and third-party tools to monitor the performance of your PWA Kit site.

## Key Monitoring Tools

Here are the main tools that we recommend you use to monitor your PWA Kit site.

- [B2C Commerce Reports & Dashboards](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reports-and-dashboards.html) provide data that you can use to identify trends over time and to make smarter business decisions based on your B2C Commerce data. Use Reports & Dashboards to understand general trends in your API response times.
  - To see the load on your B2C Commerce instance, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Reports & Dashboards > Real Time > Sales & Performance**.
  - Get insights into your site’s Salesforce Commerce API (SCAPI) requests, by checking the [Technical SCAPI Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_technical_scapi_dashboard.htm&type=5).
  - To get insights into your site’s Open Commerce API (OCAPI) requests, check the [Technical OCAPI Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_technical_ocapi_dashboard.htm&type=5).

**note:** Data appears in Reports & Dashboards 24 hours after any corresponding event happens.

- With [Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5), you can review error logs and metrics.

  - Search for and view logs generated by Managed Runtime (MRT) and PWA Kit projects. See [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-log-center).
  - Set up [notifications](https://help.salesforce.com/s/articleView?id=cc.b2c_save_a_search_rule.htm&type=5) so you can find out when your storefront is functioning abnormally and investigate. Consider setting up a [Search with Notifications](https://help.salesforce.com/s/articleView?id=cc.b2c_search_for_issues_in_log_center.htm&type=5) for the [`HookInvocationException`](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) in Log Center.
  - For detailed information about hook timing, [collect request/response details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/collect-request-details.html) by adding the HTTP request header `sfdc_verbose: true`. Hook timing is logged to Log Center.
  - Set up [Log Center Streaming](https://help.salesforce.com/s/articleView?id=cc.b2c_set_up_log_streaming.htm&type=5) to turn on enterprise-scale monitoring and automation and to stream logs to third-party log aggregation tools.
  - [View Shopper Login and API Access Service (SLAS) Error Logs in Log Center](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#view-slas-error-logs-in-log-center).

- You can resolve performance issues in your custom pipelines and code by using [Pipeline Profiler](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-troubleshooting-platform-performance.html) and [Code Profiler](https://developer.salesforce.com/docs/commerce/commerce-api/guide/code-profiler.html).

## More Monitoring Tools

Here are additional tools that you can optionally use to monitor the performance of your PWA Kit site.

### Understand the Performance of API Hooks

If your hooks make external service calls, monitor the availability of downstream services by using [Web Service Performance and Incident Analysis](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html#web-service-performance-and-incident-analysis).

You can also review the logs generated from your services. See [Web Service Logging and Troubleshooting](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html#web-service-logging-and-troubleshooting). Then you can [build notifications](https://help.salesforce.com/s/articleView?id=cc.b2c_save_a_search_rule.htm&type=5) in Log Center for your chosen logs.

### Understand the Performance of Backend Jobs

Check the [Job Statistics](https://help.salesforce.com/s/articleView?id=cc.b2c_monitor_job_stats.htm&type=5) page in Business Manager. See [Jobs](https://help.salesforce.com/s/articleView?id=cc.b2c_job_creation_management.htm&type=5).

Production jobs are usually order export, async operations and sometimes high-scale price book imports.

Staging jobs are usually catalog and price book. Remember to also monitor jobs in staging.

### Integrate your Site with Your Application Performance Monitoring (APM) Tool

Poll the OCAPI Admin API [Search Job Executions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-job-execution-search?meta=Search%2BJob%2BExecutions) and push the output data to an APM.

Set up [Embedded Content Delivery Network (eCDN) Log Push](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-logpush.html).

### Set up Real-time Performance and Error Alerts

If you have the Signature Success Plan, turn on [Proactive Services](https://help.salesforce.com/s/articleView?id=000392833&type=1).

### Identify the Root Cause of a SCAPI Request Timeout

Follow the steps in [Troubleshoot Request Timeouts](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeout-troubleshoot.html).

Include the `correlationID` identified in [Troubleshoot Request Timeouts](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeout-troubleshoot.html) if you need to open a support case.

## See Also

- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.html)
- [Debug PWA Kit Apps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html)

<!-- document id=3ae52bd11387953951280b851712fe3d5792843d9d5ca8ad964660824635442d url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/monitor-webhook-spi-integration-health.md -->

# Monitoring Webhook and SPI Integration Health in Point of Sale

Configure a monitoring webhook to track the health and performance of your SPI and webhook integrations in Point of Sale.

This proactive monitoring can help you detect issues early and maintain integration reliability. The webhook sends alerts if:

- An SPI or webhook returns an HTTP 4xx or 5xx status code.
- Response time exceeds a defined latency threshold.

## Known Issues and Restrictions

- Point of Sale doesn’t process multiple monitoring requests simultaneously. If monitoring is enabled for multiple SPIs or webhooks, any failures are added to a queue and handled asynchronously.
- Latency monitoring won't trigger if the POS times out before reaching the defined latency threshold.
- This feature doesn't support order exports configured in CMS through **Store Management** | **Store Settings** | **OMS** | **Export**.

## See Also

- [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)
- [Configure Monitoring for SPIs and Webhooks in Point of Sale CMS](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-webhook-monitoring.html)

<!-- document id=3ac5b81e0396811164cc83d58ad6589135c033c1d6dc3d0bbdd947e5e05110ec url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/references/generated-api-specs/mrt-admin.md -->

MRT Admin

# MRT Admin

Set up how a storefront or other headless commerce application is deployed to Managed Runtime.  
  
Note: Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

**Version:** v1

## Servers

*   `https://cloud.mobify.com`

## Security

*   `Basic` (http) A basic authentication scheme for Managed Runtime API endpoints. To make an API request, concatenate your email address and API key separated by a colon (`:`). Base64 encode the concatenated string and include it in the HTTP request Authorization header.  
      
    Example:  
      
    `Authorization: Basic $B64_ENCODED_VALUE`
    *   HTTP scheme: basic
*   `BearerToken` (http) A bearer token authentication scheme for Managed Runtime API endpoints. To make an API request, include your API key in the HTTP request Authorization header.  
      
    Example:  
      
    `Authorization: Bearer $API_KEY`
    *   HTTP scheme: bearer (Bearer .\*)

## Operations

### GET organizations\_list

`GET /api/organizations/`

Operation ID: `organizations_list`. Tags: organizations. Security: Basic; BearerToken.

List organizations.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedAPIOrganizationList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "uuid": "58c8da00-a596-4e62-9b93-dfc26a73528e",
          "name": "my org",
          "slug": "my-org",
          "has_mobify_tag_project": false,
          "can_configure_ssr_architecture": false,
          "created_at": "2020-07-14T19:33:21.197800Z",
          "updated_at": "2020-07-21T17:02:38.745978Z",
          "permissions": {
            "browse": true,
            "create_project": true,
            "delete_organization": true,
            "edit_organization": true
          }
        }
      ]
    }
    ```
    

### GET organizations\_certificates\_list

`GET /api/organizations/{organization_slug}/certificates/`

Operation ID: `organizations_certificates_list`. Tags: organizations. Security: Basic; BearerToken.

List certificates for an organization with filtering and search

#### Parameters

*   `custom_only` (query, boolean) If true, returns only custom domain certificates created by the customer.
*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `organization_slug` (path, string, required) The organization identifier.
*   `search` (query, string) A search term.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedCertificateListCreateList`.
    
    _Example: ListCertificates_ List certificates
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "count": 2,
          "next": null,
          "previous": null,
          "results": [
            {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "domain_name": "*.example.com",
              "validation_status": "PENDING_VALIDATION",
              "validation_record": {
                "name": "_acme-challenge.example.com",
                "value": "validation123.example.com"
              },
              "aws_arns": [
                "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"
              ],
              "created_at": "2023-10-28T10:00:00Z",
              "updated_at": "2023-10-28T10:00:00Z",
              "validation_requested_at": "2023-10-28T10:00:00Z",
              "validation_requested_by": "user@example.com",
              "expires_at": "2024-10-28T10:00:00Z",
              "targets": [],
              "created_by": "user@example.com"
            }
          ],
          "limits": {
            "max_certificates": {
              "limit": 10,
              "used": 2
            }
          },
          "customer_action_needed": true
        }
      ]
    }
    ```
    

### POST organizations\_certificates\_create

`POST /api/organizations/{organization_slug}/certificates/`

Operation ID: `organizations_certificates_create`. Tags: organizations. Security: Basic; BearerToken.

Create a new certificate for an organization

#### Parameters

*   `organization_slug` (path, string, required) The organization identifier.

#### Request body (required)

Media type: `application/json`. Schema: `CertificateListCreate`.

_Example: CreateCertificateRequest_ Create certificate request

```
{
  "domain_name": "*.example.com"
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `CertificateListCreate`.

Media type: `multipart/form-data`. Schema: `CertificateListCreate`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `CertificateListCreate`.
    
    _Example: CreateCertificateResponse_ Create certificate response
    
    ```
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "domain_name": "*.example.com",
      "validation_status": "PENDING_VALIDATION",
      "validation_record": {
        "name": "_acme-challenge.example.com",
        "value": "validation123.example.com"
      },
      "aws_arns": [
        "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"
      ],
      "created_at": "2023-10-28T10:00:00Z",
      "updated_at": "2023-10-28T10:00:00Z",
      "validation_requested_at": "2023-10-28T10:00:00Z",
      "validation_requested_by": "user@example.com",
      "targets": []
    }
    ```
    

### GET organizations\_certificates\_retrieve

`GET /api/organizations/{organization_slug}/certificates/{cert_id}/`

Operation ID: `organizations_certificates_retrieve`. Tags: organizations. Security: Basic; BearerToken.

Retrieve a specific certificate for an organization

#### Parameters

*   `cert_id` (path, string, required) The certificate's id
*   `organization_slug` (path, string, required) The organization identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `CertificateBase`.
    
    _Example GetCertificateResponse: same as POST /api/organizations/{organization\_slug}/certificates/ 201 response._ Get certificate response
    
    _Example: GetCertificateResponse_ Get certificate response
    

### DELETE organizations\_certificates\_destroy

`DELETE /api/organizations/{organization_slug}/certificates/{cert_id}/`

Operation ID: `organizations_certificates_destroy`. Tags: organizations. Security: Basic; BearerToken.

Delete a specific certificate for an organization

#### Parameters

*   `cert_id` (path, string, required) The certificate's id
*   `organization_slug` (path, string, required) The organization identifier.

#### Responses

*   **204** No response body

### PUT organizations\_certificates\_restart\_validation\_update

`PUT /api/organizations/{organization_slug}/certificates/{cert_id}/restart-validation/`

Operation ID: `organizations_certificates_restart_validation_update`. Tags: organizations. Security: Basic; BearerToken.

Restart validation for a certificate. Creates a new certificate in AWS and updates the existing certificate record. Only works for certificates that are not yet validated.

#### Parameters

*   `cert_id` (path, string, required) Certificate ID
*   `organization_slug` (path, string, required) The organization identifier.

#### Request body (required)

Media type: `application/json`. Schema: `CertificateBase`.

Media type: `application/x-www-form-urlencoded`. Schema: `CertificateBase`.

Media type: `multipart/form-data`. Schema: `CertificateBase`.

#### Responses

*   **200** Certificate validation restarted successfully
    
    Media type: `application/json`. Schema: `CertificateBase`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "id": "uuid",
      "domain_name": "shop.example.com",
      "validation_status": "pending_validation",
      "validation_record": {
        "name": "_abc.shop.example.com",
        "value": "_xyz.acm-validations.aws"
      },
      "validation_requested_at": "2025-10-16T12:00:00Z",
      "deletion_status": "ACTIVE"
    }
    ```
    
*   **400** Certificate is already validated or cannot be restarted

### PATCH organizations\_certificates\_restart\_validation\_partial\_update

`PATCH /api/organizations/{organization_slug}/certificates/{cert_id}/restart-validation/`

Operation ID: `organizations_certificates_restart_validation_partial_update`. Tags: organizations. Security: Basic; BearerToken.

Restart validation for a specific certificate for an organization.

#### Parameters

*   `cert_id` (path, string, required)  
    Pattern: ^\[\\w-\]+$.
*   `organization_slug` (path, string, required)  
    Pattern: ^\[\\w-\]+$.

#### Request body

Media type: `application/json`. Schema: `PatchedCertificateBase`.

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedCertificateBase`.

Media type: `multipart/form-data`. Schema: `PatchedCertificateBase`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `CertificateBase`.
    

### GET list\_organization\_members

`GET /api/organizations/{organization_slug}/members/`

Operation ID: `list_organization_members`. Tags: organizations. Security: Basic; BearerToken.

List all the members of an organization.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `organization_slug` (path, string, required) The organization identifier.
*   `search` (query, string) A search term.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedAPIOrganizationMemberList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        [
          {
            "user": "user1@example.com",
            "role": {
              "name": "Owner",
              "value": 0
            },
            "first_name": "John",
            "last_name": "Doe",
            "can_view_all_projects": true,
            "custom_domain_cert_permission": {
              "name": "Manage",
              "value": 0
            }
          },
          {
            "user": "user2@example.com",
            "role": {
              "name": "Member",
              "value": 1
            },
            "first_name": "Jane",
            "last_name": "Smith",
            "can_view_all_projects": false,
            "custom_domain_cert_permission": {
              "name": "View Only",
              "value": 1
            }
          }
        ]
      ]
    }
    ```
    

### POST organizations\_members\_create

`POST /api/organizations/{organization_slug}/members/`

Operation ID: `organizations_members_create`. Tags: organizations. Security: Basic; BearerToken.

Add a new member to an organization.

#### Parameters

*   `organization_slug` (path, string, required) The organization identifier.

#### Request body (required)

Media type: `application/json`. Schema: `APIOrganizationMemberCreate`.

_Example: RequestExample1_

```
{
  "user": "newuser@example.com",
  "role": 1,
  "can_view_all_projects": false,
  "custom_domain_cert_permission": 2
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APIOrganizationMemberCreate`.

Media type: `multipart/form-data`. Schema: `APIOrganizationMemberCreate`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `APIOrganizationMemberCreate`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "user": "newuser@example.com",
      "role": {
        "name": "Member",
        "value": 1
      },
      "first_name": "New",
      "last_name": "User",
      "can_view_all_projects": false,
      "custom_domain_cert_permission": {
        "name": "No Access",
        "value": 2
      }
    }
    ```
    

### GET organizations\_members\_retrieve

`GET /api/organizations/{organization_slug}/members/{email}/`

Operation ID: `organizations_members_retrieve`. Tags: organizations. Security: Basic; BearerToken.

Read data about an organization member's permissions.

#### Parameters

*   `email` (path, string, required) The email address of the organization member.
*   `organization_slug` (path, string, required) The organization identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIOrganizationMember`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "user": "user@example.com",
      "role": {
        "name": "Owner",
        "value": 0
      },
      "first_name": "John",
      "last_name": "Doe",
      "can_view_all_projects": true,
      "custom_domain_cert_permission": {
        "name": "Manage",
        "value": 0
      }
    }
    ```
    

### DELETE organizations\_members\_destroy

`DELETE /api/organizations/{organization_slug}/members/{email}/`

Operation ID: `organizations_members_destroy`. Tags: organizations. Security: Basic; BearerToken.

Remove a member from an organization.

#### Parameters

*   `email` (path, string, required) The email address of the organization member.
*   `organization_slug` (path, string, required) The organization identifier.

#### Responses

*   **204** No response body

### PATCH organizations\_members\_partial\_update

`PATCH /api/organizations/{organization_slug}/members/{email}/`

Operation ID: `organizations_members_partial_update`. Tags: organizations. Security: Basic; BearerToken.

Update an organization member's permissions.

#### Parameters

*   `email` (path, string, required) The email address of the organization member.
*   `organization_slug` (path, string, required) The organization identifier.

#### Request body

Media type: `application/json`. Schema: `PatchedAPIOrganizationMemberUpdate`.

_Example: RequestExample1_

```
{
  "role": {
    "name": "Member",
    "value": 1
  },
  "can_view_all_projects": false,
  "custom_domain_cert_permission": 1
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedAPIOrganizationMemberUpdate`.

Media type: `multipart/form-data`. Schema: `PatchedAPIOrganizationMemberUpdate`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIOrganizationMemberUpdate`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "user": "user@example.com",
      "role": {
        "name": "Member",
        "value": 1
      },
      "first_name": "John",
      "last_name": "Doe",
      "can_view_all_projects": false,
      "custom_domain_cert_permission": {
        "name": "View Only",
        "value": 1
      }
    }
    ```
    

### GET projects\_list

`GET /api/projects/`

Operation ID: `projects_list`. Tags: projects. Security: Basic; BearerToken.

List projects.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `organization` (query, string) An organization to search within.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedAPIProjectV2CreateList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "name": "Progressive SSR project",
          "url": "https://www.example.com/",
          "slug": "project-slug",
          "organization": "my-organization",
          "permissions": {
            "browse": true,
            "deploy": true,
            "delete_bundle": true,
            "delete_project": true,
            "edit_redirect": true,
            "edit_roles": true,
            "edit_settings": true,
            "validate_tag": true,
            "edit_environment": true,
            "create_environment": true,
            "delete_environment": true,
            "create_notification": true,
            "list_notifications": true,
            "retrieve_notification": true,
            "edit_notification": true,
            "delete_notification": true,
            "create_jwt": true,
            "upload_bundle": true,
            "edit_environment_variable": true,
            "edit_access_control_header": true
          },
          "deletion_status": "ACTIVE",
          "created_at": "2025-07-24T07:30:22.288165Z",
          "updated_at": "2025-07-24T08:30:22.288165Z"
        }
      ]
    }
    ```
    

### POST projects\_create

`POST /api/projects/`

Operation ID: `projects_create`. Tags: projects. Security: Basic; BearerToken.

Create a project.

#### Request body (required)

Media type: `application/json`. Schema: `APIProjectV2Create`.

_Example: RequestExample1_

```
{
  "organization": "my-org",
  "name": "My project",
  "slug": "my-project"
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APIProjectV2Create`.

Media type: `multipart/form-data`. Schema: `APIProjectV2Create`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `APIProjectV2Create`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "name": "My project",
      "url": "https://www.mobify.com",
      "slug": "my-project",
      "organization": "my-organization",
      "permissions": {
        "browse": true,
        "deploy": true,
        "delete_bundle": true,
        "delete_project": true,
        "edit_redirect": true,
        "edit_roles": true,
        "edit_settings": true,
        "validate_tag": true,
        "edit_environment": true,
        "create_environment": true,
        "delete_environment": true,
        "create_notification": true,
        "list_notifications": true,
        "retrieve_notification": true,
        "edit_notification": true,
        "delete_notification": true,
        "create_jwt": true,
        "upload_bundle": true,
        "edit_environment_variable": true,
        "edit_access_control_header": true
      },
      "deletion_status": "ACTIVE",
      "created_at": "2025-07-24T07:30:22.288165Z",
      "updated_at": "2025-07-24T07:30:22.288165Z"
    }
    ```
    

### GET projects\_retrieve

`GET /api/projects/{project_slug}/`

Operation ID: `projects_retrieve`. Tags: projects. Security: Basic; BearerToken.

Read data about a project.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIProjectV2Update`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "name": "test project",
      "url": "https://www.google.com",
      "slug": "test-project",
      "organization": "my-organization",
      "permissions": {
        "browse": true,
        "deploy": true,
        "delete_bundle": true,
        "delete_project": true,
        "edit_redirect": true,
        "edit_roles": true,
        "edit_settings": true,
        "validate_tag": true,
        "edit_environment": true,
        "create_environment": true,
        "delete_environment": true,
        "create_notification": true,
        "list_notifications": true,
        "retrieve_notification": true,
        "edit_notification": true,
        "delete_notification": true,
        "create_jwt": true,
        "upload_bundle": true,
        "edit_environment_variable": true,
        "edit_access_control_header": true
      },
      "deletion_status": "ACTIVE",
      "created_at": "2025-07-24T07:30:22.288165Z",
      "updated_at": "2025-07-24T07:30:22.288165Z"
    }
    ```
    

### DELETE projects\_destroy

`DELETE /api/projects/{project_slug}/`

Operation ID: `projects_destroy`. Tags: projects. Security: Basic; BearerToken.

Delete a project.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **204** No response body

### PATCH projects\_partial\_update

`PATCH /api/projects/{project_slug}/`

Operation ID: `projects_partial_update`. Tags: projects. Security: Basic; BearerToken.

Update a project.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Request body

Media type: `application/json`. Schema: `PatchedAPIProjectV2Update`.

_Example: RequestExample1_

```
{
  "name": "new name",
  "url": "https://www.mobify.com",
  "organization": "my-organization"
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedAPIProjectV2Update`.

Media type: `multipart/form-data`. Schema: `PatchedAPIProjectV2Update`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIProjectV2Update`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "name": "test project",
      "url": "https://www.google.com",
      "slug": "test-project",
      "organization": "my-organization",
      "permissions": {
        "browse": true,
        "deploy": true,
        "delete_bundle": true,
        "delete_project": true,
        "edit_redirect": true,
        "edit_roles": true,
        "edit_settings": true,
        "validate_tag": true,
        "edit_environment": true,
        "create_environment": true,
        "delete_environment": true,
        "create_notification": true,
        "list_notifications": true,
        "retrieve_notification": true,
        "edit_notification": true,
        "delete_notification": true,
        "create_jwt": true,
        "upload_bundle": true,
        "edit_environment_variable": true,
        "edit_access_control_header": true
      },
      "deletion_status": "ACTIVE",
      "created_at": "2025-07-24T07:30:22.288165Z",
      "updated_at": "2025-07-24T08:30:22.288165Z"
    }
    ```
    

### POST projects\_builds\_create

`POST /api/projects/{project_slug}/builds/`

Operation ID: `projects_builds_create`. Tags: projects. Security: Basic; BearerToken.

Upload a bundle.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Request body (required)

Media type: `application/json`. Schema: `Bundle`.

Media type: `application/x-www-form-urlencoded`. Schema: `Bundle`.

Media type: `multipart/form-data`. Schema: `Bundle`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `object`.
    
    Additional properties: `any`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "message": "Successfully pushed bundle for 'my-project'",
      "bundle_id": 2
    }
    ```
    

### POST projects\_builds\_create\_and\_deploy

`POST /api/projects/{project_slug}/builds/{target_slug}/`

Operation ID: `projects_builds_create_and_deploy`. Tags: projects. Security: Basic; BearerToken.

Upload a bundle and deploy it to an environment asynchronously.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body (required)

Media type: `application/json`. Schema: `Bundle`.

Media type: `application/x-www-form-urlencoded`. Schema: `Bundle`.

Media type: `multipart/form-data`. Schema: `Bundle`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `object`.
    
    Additional properties: `any`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "message": "Successfully pushed bundle for 'my-project'",
      "bundle_id": 2
    }
    ```
    

### GET projects\_bundles\_list

`GET /api/projects/{project_slug}/bundles/`

Operation ID: `projects_bundles_list`. Tags: projects. Security: Basic; BearerToken.

List bundles of a project

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `project_slug` (path, string, required) The project identifier.
*   `search` (query, string) A search term.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedBundleListList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "id": 3,
          "message": "Bundle 2",
          "status": 0,
          "deletion_status": "ACTIVE",
          "user": "fixture+progressive.ssr@test.com",
          "created_at": "2020-05-27T22:45:35.781615Z",
          "updated_at": "2020-07-09T04:59:37.733245Z",
          "is_uploaded": true,
          "is_ssr_bundle": true,
          "ssr_runtime": "12.x",
          "ssr_runtime_description": "NodeJS 12.x",
          "in_use": true,
          "in_use_by": [
            "production",
            "staging"
          ]
        }
      ]
    }
    ```
    
    _Example: ResponseExample2_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "id": 2,
          "message": "Bundle 1",
          "status": 0,
          "deletion_status": "ACTIVE",
          "user": "fixture+progressive.ssr@test.com",
          "created_at": "2020-05-27T22:45:35.703516Z",
          "updated_at": "2020-07-09T04:57:02.399510Z",
          "is_uploaded": true,
          "is_ssr_bundle": true,
          "ssr_runtime": "10.x",
          "ssr_runtime_description": "NodeJS 10.x",
          "in_use": false,
          "in_use_by": []
        }
      ]
    }
    ```
    
    _Example: ResponseExample3_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "id": 1,
          "message": "Bundle 0",
          "status": 0,
          "deletion_status": "ACTIVE",
          "user": "fixture+progressive.ssr@test.com",
          "created_at": "2020-05-27T22:45:35.646125Z",
          "updated_at": "2020-07-09T06:12:19.633249Z",
          "is_uploaded": true,
          "is_ssr_bundle": true,
          "ssr_runtime": "8.10",
          "ssr_runtime_description": "NodeJS 8.10",
          "in_use": true,
          "in_use_by": [
            "development"
          ]
        }
      ]
    }
    ```
    

### DELETE projects\_bundles\_destroy

`DELETE /api/projects/{project_slug}/bundles/{bundle_id}/`

Operation ID: `projects_bundles_destroy`. Tags: projects. Security: Basic; BearerToken.

Request deletion of a bundle. The bundle will be asynchronously deleted. This operation can only be performed by project admins.

#### Parameters

*   `bundle_id` (path, string, required) The bundle's id
*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **202** Bundle deletion request accepted. The bundle will be asynchronously deleted.
*   **403** Bundle deployed to one or more target, cannot delete.
*   **404** Bundle not found.
*   **409** Bundle cannot be deleted (in progress, in failed state).

### GET projects\_bundles\_download\_retrieve

`GET /api/projects/{project_slug}/bundles/{bundle_id}/download/`

Operation ID: `projects_bundles_download_retrieve`. Tags: projects. Security: Basic; BearerToken.

Get a presigned URL (active for one hour) to download a bundle archive.

#### Parameters

*   `bundle_id` (path, string, required) The bundle's id
*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `BundleDownload`.
    
    _Example: ResponseExample_
    
    ```
    {
      "download_url": "https://bundles.s3.amazonaws.com/build_archives/build_archive_id_1.tgz"
    }
    ```
    

### POST projects\_bundles\_bulk\_delete\_create

`POST /api/projects/{project_slug}/bundles/bulk-delete/`

Operation ID: `projects_bundles_bulk_delete_create`. Tags: projects. Security: Basic; BearerToken.

Request deletion for multiple bundles. Bundles are deleted asynchronously. Only project admins can perform this call. The response indicates which bundles were successfully queued for deletion and which failed validation.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Request body (required)

Media type: `application/json`. Schema: `BundleBulkDelete`.

_Example: RequestExample1_

```
{
  "bundle_ids": [
    1,
    2,
    3
  ]
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `BundleBulkDelete`.

Media type: `multipart/form-data`. Schema: `BundleBulkDelete`.

#### Responses

*   **202** Bundle deletion was requested. Check the response body for details about the bundles that were queued and that failed deletion.
    
    Media type: `application/json`. Schema: `BundleBulkDeleteResponse`.
    
    _Example: ResponseExample1-AllSuccessful_ ResponseExample1 - All Successful
    
    ```
    {
      "bundles_queued_for_cleanup": [
        1,
        2,
        3
      ]
    }
    ```
    
    _Example: ResponseExample2-PartialSuccess_ ResponseExample2 - Partial Success
    
    ```
    {
      "bundles_queued_for_cleanup": [
        1,
        3
      ],
      "rejected_bundles": [
        {
          "bundle_id": 2,
          "detail": "We can't delete this bundle because it's in use by 1 target(s)."
        }
      ]
    }
    ```
    
    _Example: ResponseExample2-PartialSuccess2_ ResponseExample2 - Partial Success 2
    
    ```
    {
      "bundles_queued_for_cleanup": [
        1
      ],
      "rejected_bundles": [
        {
          "bundle_ids": [
            9999
          ],
          "detail": "Bundles not found in project testproject."
        },
        {
          "bundle_id": 2,
          "detail": "We can't delete this bundle because it's in use by 3 target(s)."
        },
        {
          "bundle_id": 3,
          "detail": "We can't delete this bundle because bundle deletion is in progress."
        },
        {
          "bundle_id": 4,
          "detail": "We can't delete this bundle because bundle deletion is in progress."
        },
        {
          "bundle_id": 5,
          "detail": "We can't delete this bundle because bundle deletion is in progress."
        },
        {
          "bundle_id": 6,
          "detail": "Bundle deletion failed. We've been notified of this error and are working to resolve it."
        }
      ]
    }
    ```
    
    _Example: ResponseExample3-AllFailed_ ResponseExample3 - All Failed
    
    ```
    {
      "rejected_bundles": [
        {
          "bundle_id": 1,
          "detail": "We can't delete this bundle because bundle deletion is in progress."
        },
        {
          "bundle_id": 2,
          "detail": "We can't delete this bundle because it's in use by 1 target(s)."
        }
      ]
    }
    ```
    

### GET projects\_members\_list

`GET /api/projects/{project_slug}/members/`

Operation ID: `projects_members_list`. Tags: projects. Security: Basic; BearerToken.

List a project's members.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `project_slug` (path, string, required) The project identifier.
*   `role` (query, integer)
    
    *   `0` - Admin
        
    *   `1` - Developer
        
    *   `2` - Marketer
        
    *   `3` - Read Only
        
    *   `0` - Admin
        
    *   `1` - Developer
        
    *   `2` - Marketer
        
    *   `3` - Read Only
        
    
      
    Allowed values: `0`, `1`, `2`, `3`.
*   `role` (path, string, required) A role to filter on. Admin=0, Developer=1, Marketer=2, Read Only=3.
*   `search` (query, string) A search term.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedAPIProjectMemberList`.
    

### POST projects\_members\_create

`POST /api/projects/{project_slug}/members/`

Operation ID: `projects_members_create`. Tags: projects. Security: Basic; BearerToken.

Create a new project member.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Request body (required)

Media type: `application/json`. Schema: `APIProjectMember`.

Media type: `application/x-www-form-urlencoded`. Schema: `APIProjectMember`.

Media type: `multipart/form-data`. Schema: `APIProjectMember`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `APIProjectMember`.
    

### GET projects\_members\_retrieve

`GET /api/projects/{project_slug}/members/{email}/`

Operation ID: `projects_members_retrieve`. Tags: projects. Security: Basic; BearerToken.

Read data about a project member's permissions.

#### Parameters

*   `email` (path, string, required) The project member's email address.
*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIProjectMember`.
    

### DELETE projects\_members\_destroy

`DELETE /api/projects/{project_slug}/members/{email}/`

Operation ID: `projects_members_destroy`. Tags: projects. Security: Basic; BearerToken.

Delete a project member.

#### Parameters

*   `email` (path, string, required) The project member's email address.
*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **204** No response body

### PATCH projects\_members\_partial\_update

`PATCH /api/projects/{project_slug}/members/{email}/`

Operation ID: `projects_members_partial_update`. Tags: projects. Security: Basic; BearerToken.

Update a project member's permissions.

#### Parameters

*   `email` (path, string, required) The project member's email address.
*   `project_slug` (path, string, required) The project identifier.

#### Request body

Media type: `application/json`. Schema: `PatchedAPIProjectMember`.

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedAPIProjectMember`.

Media type: `multipart/form-data`. Schema: `PatchedAPIProjectMember`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIProjectMember`.
    

### GET projects\_notifications\_list

`GET /api/projects/{project_slug}/notifications/`

Operation ID: `projects_notifications_list`. Tags: projects. Security: Basic; BearerToken.

List notifications for a project

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `project_slug` (path, string, required) The project identifier.
*   `targets__slug` (query, string)

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedPolymorphicNotificationList`.
    

### POST projects\_notifications\_create

`POST /api/projects/{project_slug}/notifications/`

Operation ID: `projects_notifications_create`. Tags: projects. Security: Basic; BearerToken.

Create notification for a Project

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Request body

Media type: `application/json`. Schema: `PolymorphicNotification`.

Media type: `application/x-www-form-urlencoded`. Schema: `PolymorphicNotification`.

Media type: `multipart/form-data`. Schema: `PolymorphicNotification`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `PolymorphicNotification`.
    

### GET projects\_notifications\_retrieve

`GET /api/projects/{project_slug}/notifications/{id}/`

Operation ID: `projects_notifications_retrieve`. Tags: projects. Security: Basic; BearerToken.

Read data about a notification.

#### Parameters

*   `id` (path, string, required) The notification's unique UUID
*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PolymorphicNotification`.
    

### DELETE projects\_notifications\_destroy

`DELETE /api/projects/{project_slug}/notifications/{id}/`

Operation ID: `projects_notifications_destroy`. Tags: projects. Security: Basic; BearerToken.

Delete a notification.

#### Parameters

*   `id` (path, string, required) The notification's unique UUID
*   `project_slug` (path, string, required) The project identifier.

#### Responses

*   **204** No response body

### PATCH projects\_notifications\_partial\_update

`PATCH /api/projects/{project_slug}/notifications/{id}/`

Operation ID: `projects_notifications_partial_update`. Tags: projects. Security: Basic; BearerToken.

Update a project's notification.

#### Parameters

*   `id` (path, string, required) The notification's unique UUID
*   `project_slug` (path, string, required) The project identifier.

#### Request body

Media type: `application/json`. Schema: `PatchedPolymorphicNotification`.

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedPolymorphicNotification`.

Media type: `multipart/form-data`. Schema: `PatchedPolymorphicNotification`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PolymorphicNotification`.
    

### GET projects\_target\_list

`GET /api/projects/{project_slug}/target/`

Operation ID: `projects_target_list`. Tags: projects. Security: Basic; BearerToken.

List a project's targets.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `project_slug` (path, string, required) The project identifier.
*   `search` (query, string) A search term.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedAPITargetV2CreateList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "slug": "production",
          "name": "Production",
          "state": "CREATE_IN_PROGRESS",
          "deletion_status": "ACTIVE",
          "hostname": null,
          "current_deploy": {
            "status": "queued",
            "is_ssr_deploy": false,
            "updated_at": "2018-07-25T21:35:24.312882+00:00",
            "bundle": {
              "status": 0,
              "deletion_status": "ACTIVE",
              "api_bundle_preview_email_url": "/api/projects/project-slug/bundle/0/preview-email/",
              "go_preview_url": null,
              "updated_at": "2018-07-25T21:35:24.311809+00:00",
              "app_preview_url": null,
              "message": "Reset Bundle. Disables adaptation.",
              "id": 0,
              "is_uploaded": true,
              "created_at": "2018-07-25T21:35:24.311775+00:00",
              "preview_url": null,
              "is_ssr_bundle": false,
              "user_email": ""
            },
            "is_in_progress": true,
            "deploy_settings": null,
            "deploy_type": "reset_bundle",
            "created_at": "2018-07-25T21:35:24.312855+00:00",
            "deploy_duration": 778590.636166,
            "applied_deploy_settings": false,
            "status_message": "Queueing Bundle"
          },
          "ssr_external_hostname": "www-testing.example.com",
          "ssr_external_domain": "example.com",
          "ssr_region": "eu-central-1",
          "ssr_architecture": "x86",
          "ssr_whitelisted_ips": "103.12.25.0/24",
          "ssr_proxy_configs": [
            {
              "host": "www.proxyhost1.com",
              "protocol": "https"
            },
            {
              "host": "www.proxyhost2.com"
            }
          ],
          "allow_cookies": false,
          "enable_source_maps": false,
          "log_level": "INFO",
          "certificate_id": 0,
          "certificate_domain": "*.example.com"
        }
      ]
    }
    ```
    

### POST projects\_target\_create

`POST /api/projects/{project_slug}/target/`

Operation ID: `projects_target_create`. Tags: projects. Security: Basic; BearerToken.

Create a new target.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.

#### Request body (required)

Media type: `application/json`. Schema: `APITargetV2Create`.

_Example: RequestExample1_

```
{
  "name": "Testing EU",
  "slug": "testing-eu",
  "ssr_external_hostname": "www-testing.example.com",
  "ssr_external_domain": "example.com",
  "ssr_region": "eu-central-1",
  "ssr_architecture": "x86",
  "ssr_whitelisted_ips": "103.12.25.0/24",
  "ssr_proxy_configs": [
    {
      "host": "www.proxyhost1.com",
      "protocol": "https"
    },
    {
      "host": "www.proxyhost2.com"
    }
  ],
  "allow_cookies": false,
  "enable_source_maps": false,
  "log_level": "INFO",
  "certificate_id": 0
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APITargetV2Create`.

Media type: `multipart/form-data`. Schema: `APITargetV2Create`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `APITargetV2Create`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "name": "Testing EU",
      "slug": "testing-eu",
      "ssr_external_hostname": "www-testing.example.com",
      "ssr_external_domain": "example.com",
      "ssr_region": "eu-central-1",
      "ssr_architecture": "x86",
      "ssr_whitelisted_ips": "103.12.25.0/24",
      "ssr_proxy_configs": [
        {
          "host": "www.proxyhost1.com",
          "protocol": "https"
        },
        {
          "host": "www.proxyhost2.com"
        }
      ],
      "allow_cookies": true,
      "enable_source_maps": false,
      "log_level": "INFO",
      "certificate_id": 0,
      "certificate_domain": "*.example.com"
    }
    ```
    

### GET projects\_target\_retrieve

`GET /api/projects/{project_slug}/target/{target_slug}/`

Operation ID: `projects_target_retrieve`. Tags: projects. Security: Basic; BearerToken.

Read data about a target.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APITargetV2Update`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "slug": "ssr-target-successful",
      "name": "Testing EU",
      "state": "ACTIVE",
      "deletion_status": "ACTIVE",
      "hostname": "www0.somewhere.com",
      "current_deploy": {
        "status": "queued",
        "is_ssr_deploy": true,
        "updated_at": "2018-08-10T16:54:38.871068+00:00",
        "bundle": {
          "status": 0,
          "deletion_status": "ACTIVE",
          "api_bundle_preview_email_url": "/api/projects/project-slug/bundle/2/preview-email/",
          "go_preview_url": null,
          "updated_at": "2018-07-25T21:35:24.801637+00:00",
          "app_preview_url": null,
          "description": "NodeJS 16.x",
          "ssr_runtime_state": "available",
          "message": "SSR Bundle 1 (failed deploy 81)",
          "id": 2,
          "is_uploaded": true,
          "created_at": "2018-07-25T21:35:24.762928+00:00",
          "preview_url": null,
          "is_ssr_bundle": true,
          "user_email": "fixture+progressive.ssr@test.com"
        },
        "external_publish_id": "None",
        "external_progress_update": null,
        "external_progress_percentage": null,
        "is_in_progress": true,
        "deploy_settings": null,
        "external_progress_status": null,
        "deploy_type": "publish",
        "created_at": "2018-08-10T16:54:38.871027+00:00",
        "deploy_duration": 2.356207,
        "external_progress_message": null,
        "applied_deploy_settings": false,
        "status_message": "Queueing Bundle",
        "user_email": "fixture+tag.page.staff@test.com",
        "external_progress_description": null
      },
      "ssr_external_hostname": "www-testing.example.com",
      "ssr_external_domain": "example.com",
      "ssr_region": "eu-central-1",
      "ssr_architecture": "x86",
      "ssr_whitelisted_ips": "103.12.25.0/24",
      "ssr_proxy_configs": [
        {
          "host": "www.proxyhost1.com",
          "protocol": "http"
        },
        {
          "host": "www.proxyhost2.com",
          "protocol": "https"
        }
      ],
      "allow_cookies": false,
      "enable_source_maps": false,
      "log_level": "INFO",
      "certificate_id": 0,
      "certificate_domain": "*.example.com"
    }
    ```
    

### DELETE projects\_target\_destroy

`DELETE /api/projects/{project_slug}/target/{target_slug}/`

Operation ID: `projects_target_destroy`. Tags: projects. Security: Basic; BearerToken.

Delete a target.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **204** No response body

### PATCH projects\_target\_partial\_update

`PATCH /api/projects/{project_slug}/target/{target_slug}/`

Operation ID: `projects_target_partial_update`. Tags: projects. Security: Basic; BearerToken.

Update a target. Important: This endpoint automatically re-deploys the current bundle if any of the SSR-related properties are changed.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body

Media type: `application/json`. Schema: `PatchedAPITargetV2Update`.

_Example: RequestExample1_

```
{
  "name": "Testing EU",
  "ssr_external_hostname": "www-testing.example.com",
  "ssr_external_domain": "example.com",
  "ssr_region": "eu-central-1",
  "ssr_architecture": "arm64",
  "ssr_whitelisted_ips": "103.12.25.0/24",
  "ssr_proxy_configs": [
    {
      "host": "www.proxyhost1.com",
      "protocol": "http"
    },
    {
      "host": "www.proxyhost2.com",
      "protocol": "https"
    }
  ],
  "allow_cookies": true,
  "enable_source_maps": true,
  "log_level": "INFO",
  "certificate_id": 123
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedAPITargetV2Update`.

Media type: `multipart/form-data`. Schema: `PatchedAPITargetV2Update`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APITargetV2Update`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "slug": "ssr-target-successful",
      "name": "Testing EU",
      "state": "ACTIVE",
      "deletion_status": "ACTIVE",
      "hostname": "www0.somewhere.com",
      "current_deploy": {
        "status": "queued",
        "is_ssr_deploy": true,
        "updated_at": "2018-08-10T16:54:38.871068+00:00",
        "bundle": {
          "status": 0,
          "deletion_status": "ACTIVE",
          "api_bundle_preview_email_url": "/api/projects/project-slug/bundle/2/preview-email/",
          "go_preview_url": null,
          "updated_at": "2018-07-25T21:35:24.801637+00:00",
          "app_preview_url": null,
          "message": "SSR Bundle 1 (failed deploy 81)",
          "id": 2,
          "is_uploaded": true,
          "created_at": "2018-07-25T21:35:24.762928+00:00",
          "preview_url": null,
          "is_ssr_bundle": true,
          "user_email": "fixture+progressive.ssr@test.com"
        },
        "external_publish_id": "None",
        "external_progress_update": null,
        "external_progress_percentage": null,
        "is_in_progress": true,
        "deploy_settings": null,
        "external_progress_status": null,
        "deploy_type": "publish",
        "created_at": "2018-08-10T16:54:38.871027+00:00",
        "deploy_duration": 2.356207,
        "external_progress_message": null,
        "applied_deploy_settings": false,
        "status_message": "Queueing Bundle",
        "user_email": "fixture+tag.page.staff@test.com",
        "external_progress_description": null
      },
      "ssr_external_hostname": "www-testing.example.com",
      "ssr_external_domain": "example.com",
      "ssr_region": "eu-central-1",
      "ssr_architecture": "arm64",
      "ssr_whitelisted_ips": "103.12.25.0/24",
      "ssr_proxy_configs": [
        {
          "host": "www.proxyhost1.com",
          "protocol": "http"
        },
        {
          "host": "www.proxyhost2.com",
          "protocol": "https"
        }
      ],
      "allow_cookies": true,
      "enable_source_maps": true,
      "log_level": "INFO",
      "certificate_id": 0,
      "certificate_domain": "*.example.com"
    }
    ```
    

### GET projects\_target\_access\_control\_header\_list

`GET /api/projects/{project_slug}/target/{target_slug}/access-control-header/`

Operation ID: `projects_target_access_control_header_list`. Tags: projects. Security: Basic; BearerToken.

List a target's access control headers.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `project_slug` (path, string, required) The project identifier.
*   `search` (query, string) A search term.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedAPIAccessControlHeaderV2CreateList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "id": "ff832a9e-0e55-11ef-8f23-0242ac110002",
          "value": "****************by0z",
          "user_email": "jane.doe@mobify.com",
          "created_at": "2024-04-28T09:23:28.872916Z",
          "publishing_status": 0,
          "publishing_status_description": "Pending"
        }
      ]
    }
    ```
    

### POST projects\_target\_access\_control\_header\_create

`POST /api/projects/{project_slug}/target/{target_slug}/access-control-header/`

Operation ID: `projects_target_access_control_header_create`. Tags: projects. Security: Basic; BearerToken.

Create an access control header to restrict access to an environment so that only trusted traffic coming from your content delivery network (CDN) or development team is allowed. Requests to this environment must contain the header `x-sfdc-access-control` with the value provided or they will be rejected. Accepts an object with a value for a single access control header. See [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html?q=access%20control%20header#access-control-headers).

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body (required)

Media type: `application/json`. Schema: `APIAccessControlHeaderV2Create`.

_Example: RequestExample1_

```
{
  "value": "jfoWikeaby0z"
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APIAccessControlHeaderV2Create`.

Media type: `multipart/form-data`. Schema: `APIAccessControlHeaderV2Create`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `APIAccessControlHeaderV2Create`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "id": "ff832a9e-0e55-11ef-8f23-0242ac110002",
      "value": "****************by0z",
      "user_email": "jane.doe@mobify.com",
      "created_at": "2024-04-28T09:23:28.872916Z",
      "publishing_status": 0,
      "publishing_status_description": "Pending"
    }
    ```
    

### GET projects\_target\_access\_control\_header\_retrieve

`GET /api/projects/{project_slug}/target/{target_slug}/access-control-header/{id}/`

Operation ID: `projects_target_access_control_header_retrieve`. Tags: projects. Security: Basic; BearerToken.

Read data about an access control header by its id.

#### Parameters

*   `id` (path, string, required) The access control header's id.
*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIAccessControlHeaderV2Create`.
    
    _Example ResponseExample1: same as POST /api/projects/{project\_slug}/target/{target\_slug}/access-control-header/ 201 response._
    

### DELETE projects\_target\_access\_control\_header\_destroy

`DELETE /api/projects/{project_slug}/target/{target_slug}/access-control-header/{id}/`

Operation ID: `projects_target_access_control_header_destroy`. Tags: projects. Security: Basic; BearerToken.

Delete an access control header by its id.

#### Parameters

*   `id` (path, string, required) The access control header's id.
*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **204** No response body

### GET projects\_target\_deploy\_list

`GET /api/projects/{project_slug}/target/{target_slug}/deploy/`

Operation ID: `projects_target_deploy_list`. Tags: projects. Security: Basic; BearerToken.

Get the deployment history of a target.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedDeployListList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "user": "fixture+progressive.ssr@test.com",
          "duration": "00:01:16.867967",
          "bundle": {
            "id": 2,
            "message": "Bundle 1 (failed deploy 242)",
            "status": 0,
            "deletion_status": "ACTIVE",
            "user": "fixture+progressive.ssr@test.com",
            "created_at": "2020-10-13T23:09:39.309698Z",
            "updated_at": "2020-10-13T23:09:39.344068Z",
            "is_uploaded": true,
            "is_ssr_bundle": true,
            "ssr_runtime": "10.x",
            "ssr_runtime_description": "NodeJS 10.x"
          },
          "created_at": "2020-10-14T23:36:35.238529Z",
          "updated_at": "2020-10-15T00:14:34.227033Z",
          "status": "Finished",
          "deploy_type": "Publish",
          "external_publish_id": "b035a4d7-ec6b-4dcd-af8f-3a847b10fed8",
          "deploy_settings": null
        }
      ]
    }
    ```
    
    _Example: ResponseExample2_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "user": "fixture+progressive.ssr@test.com",
          "duration": "00:01:16.867967",
          "bundle": {
            "id": 1,
            "message": "Reset Bundle. Disables adaptation.",
            "status": 0,
            "deletion_status": "ACTIVE",
            "user": null,
            "created_at": "2020-10-13T23:09:39.285998Z",
            "updated_at": "2020-10-13T23:09:39.286030Z",
            "is_uploaded": true,
            "is_ssr_bundle": false,
            "ssr_runtime": null,
            "ssr_runtime_description": null
          },
          "created_at": "2020-10-14T23:26:44.018200Z",
          "updated_at": "2020-10-14T23:36:26.168594Z",
          "status": "Finished",
          "deploy_type": "Reset Bundle",
          "external_publish_id": "b035a4d7-ec6b-4dcd-af8f-3a847b10fed8",
          "deploy_settings": null
        }
      ]
    }
    ```
    

### POST projects\_target\_deploy\_create

`POST /api/projects/{project_slug}/target/{target_slug}/deploy/`

Operation ID: `projects_target_deploy_create`. Tags: projects. Security: Basic; BearerToken.

Deploys a bundle to a target. Returns the status of the deploy. Deployment details are not immediately available in the response as this endpoint is asynchronous. Request the target for progress updates.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body (required)

Media type: `application/json`. Schema: `DeployCreate`.

_Example: RequestExample1_

```
{
  "bundle_id": "22"
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `DeployCreate`.

Media type: `multipart/form-data`. Schema: `DeployCreate`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `DeployCreate`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "status": "queued",
      "is_ssr_deploy": true,
      "updated_at": "2019-10-09T19:43:04.108157+00:00",
      "bundle_id": 3,
      "bundle": {
        "status": 0,
        "deletion_status": "ACTIVE",
        "api_bundle_preview_email_url": "/api/projects/project-slug/bundle/3/preview-email/",
        "go_preview_url": null,
        "updated_at": "2019-10-09T17:31:00.418509+00:00",
        "app_preview_url": null,
        "message": "SSR Bundle 2 (running deploy 83)",
        "id": 3,
        "is_uploaded": true,
        "created_at": "2019-10-09T17:31:00.383617+00:00",
        "preview_url": null,
        "is_ssr_bundle": true,
        "user_email": "fixture+progressive.ssr@test.com"
      },
      "external_publish_id": "None",
      "external_progress_update": null,
      "external_progress_percentage": null,
      "is_in_progress": true,
      "deploy_settings": null,
      "external_progress_status": null,
      "deploy_type": "publish",
      "created_at": "2019-10-09T19:43:04.108107+00:00",
      "deploy_duration": 0.305502,
      "external_progress_message": null,
      "external_publish_details": {},
      "applied_deploy_settings": false,
      "status_message": "Queueing Bundle",
      "user_email": "fixture+progressive.ssr@test.com",
      "external_progress_description": null
    }
    ```
    

### GET projects\_target\_env\_var\_list

`GET /api/projects/{project_slug}/target/{target_slug}/env-var/`

Operation ID: `projects_target_env_var_list`. Tags: projects. Security: Basic; BearerToken.

List a target's environment variables.

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `project_slug` (path, string, required) The project identifier.
*   `search` (query, string) A search term.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedEnvironmentVariableListList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "SUPER_SECRET_API_KEY": {
            "value": "****************6dIR",
            "created_by": "john.doe@mobify.com",
            "created_at": "2020-02-26T18:05:28.873516Z",
            "updated_at": "2020-02-26T18:05:35.625877Z",
            "updated_by": "john.doe@mobify.com",
            "publishing_status": 0,
            "publishing_status_description": "Pending"
          }
        }
      ]
    }
    ```
    

### PATCH projects\_target\_env\_var\_partial\_update

`PATCH /api/projects/{project_slug}/target/{target_slug}/env-var/`

Operation ID: `projects_target_env_var_partial_update`. Tags: projects. Security: Basic; BearerToken.

Create, update, or delete environment variables. Accepts an object with values for single or multiple environment variables. If the variable does not exist, it is created. If the variable exists, it is updated. And if the variable exists and the value is null, it is deleted.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body

Media type: `application/json`. Schema: `object`.

Additional properties: `any`.

_Example: RequestExample1_

```
{
  "CREATE-ENV-VAR": {
    "value": "new-value"
  },
  "UPDATE-ENV-VAR": {
    "value": "updated-value"
  },
  "DELETE-ENV-VAR": {
    "value": null
  }
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `object`.

Additional properties: `any`.

Media type: `multipart/form-data`. Schema: `object`.

Additional properties: `any`.

#### Responses

*   **204** No response body. The request was processed successfully.

### POST projects\_target\_invalidation\_create

`POST /api/projects/{project_slug}/target/{target_slug}/invalidation/`

Operation ID: `projects_target_invalidation_create`. Tags: projects. Security: Basic; BearerToken.

Invalidate a target's cached objects in the CDN. Cache invalidations are asynchronous and usually complete within two minutes.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body (required)

Media type: `application/json`. Schema: `APITargetV2CreateInvalidation`.

_Example: RequestExample1_

```
{
  "pattern": "/path/to/products/*/"
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APITargetV2CreateInvalidation`.

Media type: `multipart/form-data`. Schema: `APITargetV2CreateInvalidation`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `APITargetV2CreateInvalidation`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "result": "Cache invalidation is in progress.",
      "slug": "testing-eu"
    }
    ```
    

### GET projects\_target\_redirect\_list

`GET /api/projects/{project_slug}/target/{target_slug}/redirect/`

Operation ID: `projects_target_redirect_list`. Tags: projects. Security: Basic; BearerToken.

List a target's redirects. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).

#### Parameters

*   `limit` (query, integer) Number of results to return per page.
*   `offset` (query, integer) The initial index from which to return the results.
*   `ordering` (query, string) Which field to use when ordering the results.
*   `project_slug` (path, string, required) The project identifier.
*   `search` (query, string) A search term.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `PaginatedAPIRedirectV2CreateUpdateList`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "count": 123,
      "next": "http://api.example.org/accounts/?offset=400&limit=100",
      "previous": "http://api.example.org/accounts/?offset=200&limit=100",
      "results": [
        {
          "from_path": "/spring",
          "to_url": "/summer",
          "forward_querystring": false,
          "http_status_code": 301,
          "publishing_status": "Pending",
          "user_email": "john.doe@mobify.com",
          "updated_by": "john.doe@mobify.com",
          "created_at": "2020-02-26T18:05:28.873516Z",
          "updated_at": "2020-02-26T18:05:35.625877Z"
        }
      ]
    }
    ```
    

### POST projects\_target\_redirect\_create

`POST /api/projects/{project_slug}/target/{target_slug}/redirect/`

Operation ID: `projects_target_redirect_create`. Tags: projects. Security: Basic; BearerToken.

Create one or more redirects. This endpoint accepts either an object with values for a single redirect, or an array of objects for bulk creation. For example, consider a seasonal campaign page for spring. When the spring campaign ends and is replaced with a summer campaign, you can redirect from the spring URL to the summer URL. We recommend that you always create redirects in your staging target (environment) and then [clone](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_clone_create) them to your production target. This allows you to test the redirects and verify that they work as expected. Changes may take up to 20 minutes to take effect on your site. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body (required)

Media type: `application/json`. Schema: `APIRedirectV2CreateUpdate`.

_Example: RequestExample1-BulkRedirectCreation_ RequestExample1 - Bulk Redirect Creation

```
[
  {
    "from_path": "/spring/category1",
    "to_url": "/summer/category1",
    "forward_querystring": false,
    "forward_wildcard": true
  },
  {
    "from_path": "/spring/category2",
    "to_url": "/summer/category2",
    "forward_querystring": false,
    "forward_wildcard": true
  },
  {
    "from_path": "/spring/category3",
    "to_url": "/summer/category3",
    "forward_querystring": false,
    "forward_wildcard": true
  }
]
```

_Example: RequestExample2-SingleRedirectCreation_ RequestExample2 - Single Redirect Creation

```
{
  "from_path": "/spring/*",
  "to_url": "/summer",
  "forward_querystring": false,
  "forward_wildcard": true
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APIRedirectV2CreateUpdate`.

Media type: `multipart/form-data`. Schema: `APIRedirectV2CreateUpdate`.

#### Responses

*   **201** The request was processed successfully.
    
    Media type: `application/json`. Schema: `APIRedirectV2CreateUpdate`.
    
    _Example: ResponseExample1-BulkRedirectCreation_ ResponseExample1 - Bulk Redirect Creation
    
    ```
    // No response body. The request was processed successfully.
    ```
    
    _Example: ResponseExample2-SingleRedirectCreation_ ResponseExample2 - Single Redirect Creation
    
    ```
    {
      "from_path": "/spring/*",
      "to_url": "/summer",
      "forward_querystring": false,
      "forward_wildcard": true,
      "http_status_code": 301,
      "publishing_status": "Pending",
      "user_email": "john.doe@example.com",
      "updated_by": "john.doe@example.com",
      "created_at": "2024-05-23T00:00:00.000Z",
      "updated_at": "2024-05-23T00:00:00.000Z"
    }
    ```
    

### GET projects\_target\_redirect\_retrieve

`GET /api/projects/{project_slug}/target/{target_slug}/redirect/{from_path}`

Operation ID: `projects_target_redirect_retrieve`. Tags: projects. Security: Basic; BearerToken.

Read data about a redirect by `from_path`. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).

#### Parameters

*   `from_path` (path, string, required) The redirect's `from_path`.
*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIRedirectV2CreateUpdate`.
    

### DELETE projects\_target\_redirect\_destroy

`DELETE /api/projects/{project_slug}/target/{target_slug}/redirect/{from_path}`

Operation ID: `projects_target_redirect_destroy`. Tags: projects. Security: Basic; BearerToken.

Delete a redirect by `from_path`. For example, you can delete a redirect that's no longer needed because a seasonal campaign is over, you removed a page, or you want to streamline your redirect structure and improve search engine ranking. We recommend that you always delete redirects in your staging target (environment), and then [clone](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_clone_create) the changes to your production target. Changes may take up to 20 minutes to take effect on your site. When you delete a redirect, you no longer see it in Runtime Admin. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).

#### Parameters

*   `from_path` (path, string, required) The redirect's `from_path`.
*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **204** No response body. The request was processed successfully.

### PATCH projects\_target\_redirect\_partial\_update

`PATCH /api/projects/{project_slug}/target/{target_slug}/redirect/{from_path}`

Operation ID: `projects_target_redirect_partial_update`. Tags: projects. Security: Basic; BearerToken.

Update a redirect by `from_path`. For example, you can change a redirect if your content moved or you rebranded with new pages. We recommend that you always change redirects in your staging target (environment), and then [clone](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_redirect_clone_create) the changes to your production target. Changes may take up to 20 minutes to take effect on your site. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).

#### Parameters

*   `from_path` (path, string, required) The redirect's `from_path`.
*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body

Media type: `application/json`. Schema: `PatchedAPIRedirectV2CreateUpdate`.

_Example: RequestExample1_

```
{
  "from_path": "/spring",
  "to_url": "/summer-newbranding",
  "http_status_code": 301
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedAPIRedirectV2CreateUpdate`.

Media type: `multipart/form-data`. Schema: `PatchedAPIRedirectV2CreateUpdate`.

#### Responses

*   **200** The request was processed successfully.
    
    Media type: `application/json`. Schema: `APIRedirectV2CreateUpdate`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "from_path": "/spring",
      "to_url": "/summer-newbranding",
      "http_status_code": 301,
      "publishing_status": "Pending",
      "user_email": "john.doe@example.com",
      "updated_by": "john.doe@example.com",
      "created_at": "2024-05-23T00:00:00.000Z",
      "updated_at": "2024-05-23T00:00:00.000Z"
    }
    ```
    

### POST projects\_target\_redirect\_clone\_create

`POST /api/projects/{project_slug}/target/{to_target_slug}/redirect/clone/`

Operation ID: `projects_target_redirect_clone_create`. Tags: projects. Security: Basic; BearerToken.

Clone redirects from one target to another. Important: when you clone redirects, you're replacing all the redirects in one target with all the redirects in the other. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `to_target_slug` (path, string, required) The destination target identifier for the clone operation.

#### Request body (required)

Media type: `application/json`. Schema: `APIRedirectV2Clone`.

_Example: RequestExample1_

```
{
  "from_target_slug": "staging"
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APIRedirectV2Clone`.

Media type: `multipart/form-data`. Schema: `APIRedirectV2Clone`.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `APIRedirectV2Clone`.
    

### POST users\_me\_api\_key\_create

`POST /api/users/me/api_key/`

Operation ID: `users_me_api_key_create`. Tags: users. Security: Basic; BearerToken.

Generate or reset the API key.

#### Responses

*   **201**
    
    Media type: `application/json`. Schema: `object`.
    
    Additional properties: `any`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "api_key": "qLh_IRpIh59..."
    }
    ```
    

### GET users\_me\_email\_preferences\_retrieve

`GET /api/users/me/email-preferences/`

Operation ID: `users_me_email_preferences_retrieve`. Tags: users. Security: Basic; BearerToken.

Get email notification preferences for the authenticated user.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `UserEmailPreferences`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "node_deprecation_notifications": true,
      "custom_domain_certificate_notifications": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
    ```
    

### PATCH users\_me\_email\_preferences\_partial\_update

`PATCH /api/users/me/email-preferences/`

Operation ID: `users_me_email_preferences_partial_update`. Tags: users. Security: Basic; BearerToken.

Update email notification preferences for the authenticated user.

#### Request body

Media type: `application/json`. Schema: `PatchedUserEmailPreferences`.

_Example: RequestExample1_

```
{
  "node_deprecation_notifications": false,
  "custom_domain_certificate_notifications": false
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedUserEmailPreferences`.

Media type: `multipart/form-data`. Schema: `PatchedUserEmailPreferences`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `UserEmailPreferences`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "node_deprecation_notifications": false,
      "custom_domain_certificate_notifications": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z"
    }
    ```
    

### GET users\_me\_profile\_retrieve

`GET /api/users/me/profile/`

Operation ID: `users_me_profile_retrieve`. Tags: users. Security: Basic; BearerToken.

Get the profile information for the authenticated user.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIUserProfile`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "firstname": "thomas",
      "lastname": "berko",
      "email": "thomas.berko@example.com"
    }
    ```
    

## Schemas

### PaginatedAPIOrganizationList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of APIOrganization_, required)

### PaginatedCertificateListCreateList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of CertificateListCreate_, required)

### CertificateListCreate

Base serializer for certificate serializers with common fields and methods.

*   `id` (_integer_, read-only) An ID unique within a business.
*   `domain_name` (_string_, required) The domain for the certificate (e.g. shop.example.com)  
    Maximum length: 255.
*   `validation_requested_at` (_string (date-time)_, read-only)
*   `validation_status` (_object_, read-only)
    
    Current validation status of the certificate
    
    *   `pending_validation` - Pending Validation
    *   `validation_succeeded` - Validation Succeeded
    *   `validation_failed` - Validation Failed
    
    Includes all fields of `ValidationStatusEnum`.
    
*   `validation_record` (_string_, read-only)
*   `expires_at` (_string (date-time)_, read-only, nullable)
    
    Certificate Expiry Date
    
    Expiry date of the certificate from ACM.
    
*   `renewal_status` (_RenewalStatusEnum | NullEnum_, read-only, nullable)
    
    Current status of certificate renewal.
    
    *   `PENDING_AUTO_RENEWAL` - Pending Auto Renewal
    *   `FAILED` - Failed
    
    One of: `RenewalStatusEnum`, `NullEnum`.
    
*   `renewal_eligibility` (_RenewalEligibilityEnum | NullEnum_, read-only, nullable)
    
    Whether the certificate is eligible for renewal.
    
    *   `ELIGIBLE` - Eligible
    *   `INELIGIBLE` - Ineligible
    
    One of: `RenewalEligibilityEnum`, `NullEnum`.
    
*   `targets` (_string_, read-only)
*   `created_by` (_string_, read-only)
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `is_mrt_managed` (_string_, read-only)
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    

### CertificateBase

Base serializer for certificate serializers with common fields and methods.

*   `id` (_integer_, read-only) An ID unique within a business.
*   `domain_name` (_string_, required)
    
    Certificate domain
    
    The domain for the certificate either wildcard (e.g. \*.example.com) or single domain (e.g. sub.example.com)
    
      
    Maximum length: 255.
*   `validation_requested_at` (_string (date-time)_, read-only, nullable) Timestamp when the validation was requested.
*   `validation_status` (_object_, read-only)
    
    Current validation status of the certificate
    
    *   `pending_validation` - Pending Validation
    *   `validation_succeeded` - Validation Succeeded
    *   `validation_failed` - Validation Failed
    
    Includes all fields of `ValidationStatusEnum`.
    
*   `validation_record` (_string_, read-only)
*   `expires_at` (_string (date-time)_, read-only, nullable)
    
    Certificate Expiry Date
    
    Expiry date of the certificate from ACM.
    
*   `renewal_status` (_RenewalStatusEnum | NullEnum_, read-only, nullable)
    
    Current status of certificate renewal.
    
    *   `PENDING_AUTO_RENEWAL` - Pending Auto Renewal
    *   `FAILED` - Failed
    
    One of: `RenewalStatusEnum`, `NullEnum`.
    
*   `renewal_eligibility` (_RenewalEligibilityEnum | NullEnum_, read-only, nullable)
    
    Whether the certificate is eligible for renewal.
    
    *   `ELIGIBLE` - Eligible
    *   `INELIGIBLE` - Ineligible
    
    One of: `RenewalEligibilityEnum`, `NullEnum`.
    
*   `targets` (_string_, read-only)
*   `created_by` (_string_, read-only)
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `is_mrt_managed` (_string_, read-only)
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    

### PatchedCertificateBase

Base serializer for certificate serializers with common fields and methods.

*   `id` (_integer_, read-only) An ID unique within a business.
*   `domain_name` (_string_)
    
    Certificate domain
    
    The domain for the certificate either wildcard (e.g. \*.example.com) or single domain (e.g. sub.example.com)
    
      
    Maximum length: 255.
*   `validation_requested_at` (_string (date-time)_, read-only, nullable) Timestamp when the validation was requested.
*   `validation_status` (_object_, read-only)
    
    Current validation status of the certificate
    
    *   `pending_validation` - Pending Validation
    *   `validation_succeeded` - Validation Succeeded
    *   `validation_failed` - Validation Failed
    
    Includes all fields of `ValidationStatusEnum`.
    
*   `validation_record` (_string_, read-only)
*   `expires_at` (_string (date-time)_, read-only, nullable)
    
    Certificate Expiry Date
    
    Expiry date of the certificate from ACM.
    
*   `renewal_status` (_RenewalStatusEnum | NullEnum_, read-only, nullable)
    
    Current status of certificate renewal.
    
    *   `PENDING_AUTO_RENEWAL` - Pending Auto Renewal
    *   `FAILED` - Failed
    
    One of: `RenewalStatusEnum`, `NullEnum`.
    
*   `renewal_eligibility` (_RenewalEligibilityEnum | NullEnum_, read-only, nullable)
    
    Whether the certificate is eligible for renewal.
    
    *   `ELIGIBLE` - Eligible
    *   `INELIGIBLE` - Ineligible
    
    One of: `RenewalEligibilityEnum`, `NullEnum`.
    
*   `targets` (_string_, read-only)
*   `created_by` (_string_, read-only)
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `is_mrt_managed` (_string_, read-only)
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    

### PaginatedAPIOrganizationMemberList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of APIOrganizationMember_, required)

### APIOrganizationMemberCreate

Serializer for creating organization members.

*   `user` (_string (email)_, required) Email address
*   `role` (_RoleEnum_, required)
*   `can_view_all_projects` (_boolean_)
*   `custom_domain_cert_permission` (_Status1d2Enum_)

### APIOrganizationMember

*   `user` (_string (email)_, read-only) Email address
*   `email` (_string_, read-only)
*   `role` (_RoleEnum_, required)
*   `first_name` (_string_, read-only)
*   `last_name` (_string_, read-only)
*   `can_view_all_projects` (_boolean_, read-only)
*   `custom_domain_cert_permission` (_object_, read-only)
    
    Includes all fields of `Status1d2Enum`.
    

### PatchedAPIOrganizationMemberUpdate

Serializer for updating organization role permissions. Allows updating can\_view\_all\_projects and custom\_domain\_cert\_permission.

*   `user` (_string (email)_, read-only) Email address
*   `role` (_object_, read-only)
    
    Includes all fields of `RoleEnum`.
    
*   `first_name` (_string_, read-only)
*   `last_name` (_string_, read-only)
*   `can_view_all_projects` (_boolean_)
*   `custom_domain_cert_permission` (_Status1d2Enum_)

### APIOrganizationMemberUpdate

Serializer for updating organization role permissions. Allows updating can\_view\_all\_projects and custom\_domain\_cert\_permission.

*   `user` (_string (email)_, read-only) Email address
*   `role` (_object_, read-only)
    
    Includes all fields of `RoleEnum`.
    
*   `first_name` (_string_, read-only)
*   `last_name` (_string_, read-only)
*   `can_view_all_projects` (_boolean_)
*   `custom_domain_cert_permission` (_Status1d2Enum_)

### PaginatedAPIProjectV2CreateList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of APIProjectV2Create_, required)

### APIProjectV2Create

*   `name` (_string_, required) User-friendly name for this project  
    Maximum length: 64.
*   `url` (_string (uri)_)  
    Maximum length: 2000.
*   `slug` (_string_)  
    Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$.
*   `organization` (_string_, required) User-friendly identifier for this instance.
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    
*   `project_type` (_object_, read-only)
    
    Includes all fields of `ProjectTypeEnum`.
    
*   `permissions` (_object_, read-only)
    *   `browse` (_boolean_)
    *   `deploy` (_boolean_)
    *   `delete_bundle` (_boolean_)
    *   `delete_project` (_boolean_)
    *   `edit_redirect` (_boolean_)
    *   `edit_roles` (_boolean_)
    *   `edit_settings` (_boolean_)
    *   `validate_tag` (_boolean_)
    *   `edit_environment` (_boolean_)
    *   `create_environment` (_boolean_)
    *   `delete_environment` (_boolean_)
    *   `create_notification` (_boolean_)
    *   `list_notifications` (_boolean_)
    *   `retrieve_notification` (_boolean_)
    *   `edit_notification` (_boolean_)
    *   `delete_notification` (_boolean_)
    *   `create_jwt` (_boolean_)
    *   `upload_bundle` (_boolean_)
    *   `edit_environment_variable` (_boolean_)
    *   `edit_access_control_header` (_boolean_)
*   `ssr_region` (_object_)
    
    SSR AWS Region
    
    The default AWS region for newly created targets
    
    *   `us-east-1` - US East (N. Virginia)
    *   `us-east-2` - US East (Ohio)
    *   `us-west-1` - US West (N. California)
    *   `us-west-2` - US West (Oregon)
    *   `ap-south-1` - Asia Pacific (Mumbai)
    *   `ap-south-2` - Asia Pacific (Hyderabad)
    *   `ap-northeast-2` - Asia Pacific (Seoul)
    *   `ap-southeast-1` - Asia Pacific (Singapore)
    *   `ap-southeast-2` - Asia Pacific (Sydney)
    *   `ap-southeast-3` - Asia Pacific (Jakarta)
    *   `ap-northeast-1` - Asia Pacific (Tokyo)
    *   `ap-northeast-3` - Asia Pacific (Osaka)
    *   `ca-central-1` - Canada (Central)
    *   `eu-central-1` - EU (Frankfurt)
    *   `eu-central-2` - EU (Zurich)
    *   `eu-west-1` - EU (Ireland)
    *   `eu-west-2` - EU (London)
    *   `eu-west-3` - EU (Paris)
    *   `eu-north-1` - EU (Stockholm)
    *   `eu-south-1` - EU (Milan)
    *   `il-central-1` - Israel (Tel Aviv)
    *   `me-central-1` - Middle East (UAE)
    *   `sa-east-1` - South America (Sao Paulo)
    
    Includes all fields of `SsrRegionEnum`.
    
*   `ssr_architecture` (_SsrArchitectureEnum | NullEnum_, nullable)
    
    Default Server-Side Rendering architecture (x86 or arm64) for targets under this project.
    
    *   `x86` - x86
    *   `arm64` - ARM64
    
    One of: `SsrArchitectureEnum`, `NullEnum`.
    
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `source` (_SourceEnum | NullEnum_, read-only, nullable)
    
    Source of the project. One of: ecom, core, direct.
    
    *   `ecom` - ecom
    *   `core` - core
    *   `direct` - direct
    
    One of: `SourceEnum`, `NullEnum`.
    

### APIProjectV2Update

*   `name` (_string_, required) User-friendly name for this project  
    Maximum length: 64.
*   `url` (_string (uri)_)  
    Maximum length: 2000.
*   `slug` (_string_, read-only)  
    Pattern: ^\[-a-zA-Z0-9\_\]+$.
*   `organization` (_string_) User-friendly identifier for this instance.
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    
*   `project_type` (_object_, read-only)
    
    Includes all fields of `ProjectTypeEnum`.
    
*   `permissions` (_object_, read-only)
    *   `browse` (_boolean_)
    *   `deploy` (_boolean_)
    *   `delete_bundle` (_boolean_)
    *   `delete_project` (_boolean_)
    *   `edit_redirect` (_boolean_)
    *   `edit_roles` (_boolean_)
    *   `edit_settings` (_boolean_)
    *   `validate_tag` (_boolean_)
    *   `edit_environment` (_boolean_)
    *   `create_environment` (_boolean_)
    *   `delete_environment` (_boolean_)
    *   `create_notification` (_boolean_)
    *   `list_notifications` (_boolean_)
    *   `retrieve_notification` (_boolean_)
    *   `edit_notification` (_boolean_)
    *   `delete_notification` (_boolean_)
    *   `create_jwt` (_boolean_)
    *   `upload_bundle` (_boolean_)
    *   `edit_environment_variable` (_boolean_)
    *   `edit_access_control_header` (_boolean_)
*   `ssr_region` (_object_)
    
    SSR AWS Region
    
    The default AWS region for newly created targets
    
    *   `us-east-1` - US East (N. Virginia)
    *   `us-east-2` - US East (Ohio)
    *   `us-west-1` - US West (N. California)
    *   `us-west-2` - US West (Oregon)
    *   `ap-south-1` - Asia Pacific (Mumbai)
    *   `ap-south-2` - Asia Pacific (Hyderabad)
    *   `ap-northeast-2` - Asia Pacific (Seoul)
    *   `ap-southeast-1` - Asia Pacific (Singapore)
    *   `ap-southeast-2` - Asia Pacific (Sydney)
    *   `ap-southeast-3` - Asia Pacific (Jakarta)
    *   `ap-northeast-1` - Asia Pacific (Tokyo)
    *   `ap-northeast-3` - Asia Pacific (Osaka)
    *   `ca-central-1` - Canada (Central)
    *   `eu-central-1` - EU (Frankfurt)
    *   `eu-central-2` - EU (Zurich)
    *   `eu-west-1` - EU (Ireland)
    *   `eu-west-2` - EU (London)
    *   `eu-west-3` - EU (Paris)
    *   `eu-north-1` - EU (Stockholm)
    *   `eu-south-1` - EU (Milan)
    *   `il-central-1` - Israel (Tel Aviv)
    *   `me-central-1` - Middle East (UAE)
    *   `sa-east-1` - South America (Sao Paulo)
    
    Includes all fields of `SsrRegionEnum`.
    
*   `ssr_architecture` (_SsrArchitectureEnum | NullEnum_, nullable)
    
    Default Server-Side Rendering architecture (x86 or arm64) for targets under this project.
    
    *   `x86` - x86
    *   `arm64` - ARM64
    
    One of: `SsrArchitectureEnum`, `NullEnum`.
    
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `source` (_SourceEnum | NullEnum_, read-only, nullable)
    
    Source of the project. One of: ecom, core, direct.
    
    *   `ecom` - ecom
    *   `core` - core
    *   `direct` - direct
    
    One of: `SourceEnum`, `NullEnum`.
    

### PatchedAPIProjectV2Update

*   `name` (_string_) User-friendly name for this project  
    Maximum length: 64.
*   `url` (_string (uri)_)  
    Maximum length: 2000.
*   `slug` (_string_, read-only)  
    Pattern: ^\[-a-zA-Z0-9\_\]+$.
*   `organization` (_string_) User-friendly identifier for this instance.
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    
*   `project_type` (_object_, read-only)
    
    Includes all fields of `ProjectTypeEnum`.
    
*   `permissions` (_object_, read-only)
    *   `browse` (_boolean_)
    *   `deploy` (_boolean_)
    *   `delete_bundle` (_boolean_)
    *   `delete_project` (_boolean_)
    *   `edit_redirect` (_boolean_)
    *   `edit_roles` (_boolean_)
    *   `edit_settings` (_boolean_)
    *   `validate_tag` (_boolean_)
    *   `edit_environment` (_boolean_)
    *   `create_environment` (_boolean_)
    *   `delete_environment` (_boolean_)
    *   `create_notification` (_boolean_)
    *   `list_notifications` (_boolean_)
    *   `retrieve_notification` (_boolean_)
    *   `edit_notification` (_boolean_)
    *   `delete_notification` (_boolean_)
    *   `create_jwt` (_boolean_)
    *   `upload_bundle` (_boolean_)
    *   `edit_environment_variable` (_boolean_)
    *   `edit_access_control_header` (_boolean_)
*   `ssr_region` (_object_)
    
    SSR AWS Region
    
    The default AWS region for newly created targets
    
    *   `us-east-1` - US East (N. Virginia)
    *   `us-east-2` - US East (Ohio)
    *   `us-west-1` - US West (N. California)
    *   `us-west-2` - US West (Oregon)
    *   `ap-south-1` - Asia Pacific (Mumbai)
    *   `ap-south-2` - Asia Pacific (Hyderabad)
    *   `ap-northeast-2` - Asia Pacific (Seoul)
    *   `ap-southeast-1` - Asia Pacific (Singapore)
    *   `ap-southeast-2` - Asia Pacific (Sydney)
    *   `ap-southeast-3` - Asia Pacific (Jakarta)
    *   `ap-northeast-1` - Asia Pacific (Tokyo)
    *   `ap-northeast-3` - Asia Pacific (Osaka)
    *   `ca-central-1` - Canada (Central)
    *   `eu-central-1` - EU (Frankfurt)
    *   `eu-central-2` - EU (Zurich)
    *   `eu-west-1` - EU (Ireland)
    *   `eu-west-2` - EU (London)
    *   `eu-west-3` - EU (Paris)
    *   `eu-north-1` - EU (Stockholm)
    *   `eu-south-1` - EU (Milan)
    *   `il-central-1` - Israel (Tel Aviv)
    *   `me-central-1` - Middle East (UAE)
    *   `sa-east-1` - South America (Sao Paulo)
    
    Includes all fields of `SsrRegionEnum`.
    
*   `ssr_architecture` (_SsrArchitectureEnum | NullEnum_, nullable)
    
    Default Server-Side Rendering architecture (x86 or arm64) for targets under this project.
    
    *   `x86` - x86
    *   `arm64` - ARM64
    
    One of: `SsrArchitectureEnum`, `NullEnum`.
    
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `source` (_SourceEnum | NullEnum_, read-only, nullable)
    
    Source of the project. One of: ecom, core, direct.
    
    *   `ecom` - ecom
    *   `core` - core
    *   `direct` - direct
    
    One of: `SourceEnum`, `NullEnum`.
    

### Bundle

Serializer to validate a bundle upload payload.

*   `message` (_string_, required)  
    Maximum length: 2048.
*   `data` (_string_, required)
*   `encoding` (_EncodingEnum_, required)
*   `ssr_only` (_array of string_)
*   `ssr_shared` (_array of string_)
*   `ssr_parameters` (_object_)
    
    Additional properties: `any`.
    
*   `bundle_metadata` (_object_)
    
    Additional properties: `any`.
    

### PaginatedBundleListList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of BundleList_, required)

### BundleDownload

*   `download_url` (_string (uri)_, required)

### BundleBulkDelete

*   `bundle_ids` (_array of integer_, required)

### BundleBulkDeleteResponse

*   `rejected_bundles` (_array of BundleBulkDeleteFailedRequest_) Bundles that failed validation and couldn't be queued for deletion.
*   `bundles_queued_for_cleanup` (_array of integer_) Bundle IDs for bundles that were queued for deletion.

### PaginatedAPIProjectMemberList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of APIProjectMember_, required)

### APIProjectMember

*   `user` (_string (email)_, required) Email address
*   `role` (_object_, required)
    *   `name` (_string_)
    *   `value` (_integer_)  
        Allowed values: `0`, `1`, `2`, `3`.

### PatchedAPIProjectMember

*   `user` (_string (email)_) Email address
*   `role` (_object_)
    *   `name` (_string_)
    *   `value` (_integer_)  
        Allowed values: `0`, `1`, `2`, `3`.

### PaginatedPolymorphicNotificationList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of PolymorphicNotification_, required)

### PolymorphicNotification

Discriminator: `resourcetype` selects the concrete type. Mapping: `EmailNotification` → `EmailNotificationTyped`.

One of: `EmailNotificationTyped`.

### PatchedPolymorphicNotification

Discriminator: `resourcetype` selects the concrete type. Mapping: `EmailNotification` → `PatchedEmailNotificationTyped`.

One of: `PatchedEmailNotificationTyped`.

### PaginatedAPITargetV2CreateList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of APITargetV2Create_, required)

### APITargetV2Create

This is the serializer for target create/list APIs.

*   `slug` (_string_)  
    Maximum length: 64. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$.
*   `name` (_string_, required) User-friendly name for this target  
    Maximum length: 64.
*   `state` (_object_, read-only)
    
    Target State
    
    *   `CREATE_IN_PROGRESS` - Create in Progress
    *   `PUBLISH_IN_PROGRESS` - Publish in Progress
    *   `ACTIVE` - Active
    *   `CREATE_FAILED` - Create Failed
    *   `PUBLISH_FAILED` - Publish Failed
    
    Includes all fields of `StateEnum`.
    
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    
*   `hostname` (_string_, nullable) Hostname (literal or JavaScript regular expression between / characters) on which this target should be loaded by the V8 Tag  
    Maximum length: 128.
*   `current_deploy` (_object_, read-only)
    
    Additional properties: `any`.
    
*   `ssr_external_hostname` (_string_, nullable) Full hostname to be used by the environment eg. [www.customer.com](http://www.customer.com).  
    Maximum length: 128.
*   `ssr_external_domain` (_string_, nullable) The domain to be used for a Universal PWA SSR deployment (e.g. customer.com)  
    Maximum length: 128.
*   `ssr_region` (_SsrRegionEnum | BlankEnum_)
    
    SSR AWS Region
    
    The AWS region to which a Universal PWA SSR should be deployed (e.g. us-east-1)
    
    *   `us-east-1` - US East (N. Virginia)
    *   `us-east-2` - US East (Ohio)
    *   `us-west-1` - US West (N. California)
    *   `us-west-2` - US West (Oregon)
    *   `ap-south-1` - Asia Pacific (Mumbai)
    *   `ap-south-2` - Asia Pacific (Hyderabad)
    *   `ap-northeast-2` - Asia Pacific (Seoul)
    *   `ap-southeast-1` - Asia Pacific (Singapore)
    *   `ap-southeast-2` - Asia Pacific (Sydney)
    *   `ap-southeast-3` - Asia Pacific (Jakarta)
    *   `ap-northeast-1` - Asia Pacific (Tokyo)
    *   `ap-northeast-3` - Asia Pacific (Osaka)
    *   `ca-central-1` - Canada (Central)
    *   `eu-central-1` - EU (Frankfurt)
    *   `eu-central-2` - EU (Zurich)
    *   `eu-west-1` - EU (Ireland)
    *   `eu-west-2` - EU (London)
    *   `eu-west-3` - EU (Paris)
    *   `eu-north-1` - EU (Stockholm)
    *   `eu-south-1` - EU (Milan)
    *   `il-central-1` - Israel (Tel Aviv)
    *   `me-central-1` - Middle East (UAE)
    *   `sa-east-1` - South America (Sao Paulo)
    
    One of: `SsrRegionEnum`, `BlankEnum`.
    
*   `ssr_architecture` (_SsrArchitectureEnum | NullEnum_, nullable)
    
    The architecture for the Server-Side Rendering function (x86 or ARM64). If not specified, the ssr\_architecture that's set in the project is used.
    
    *   `x86` - x86
    *   `arm64` - ARM64
    
    One of: `SsrArchitectureEnum`, `NullEnum`.
    
*   `ssr_whitelisted_ips` (_string_, nullable) Optional space-separated list of IP addresses (CIDR blocks) that can access this target. Leave blank to allow all IPs.
*   `ssr_proxy_configs` (_array of object_, nullable)
    *   `host` (_string_, required)
    *   `protocol` (_string_)
*   `cdn_domain_name` (_string_, read-only) The Managed Runtime CDN origin domain name.
*   `is_production` (_boolean_)
    
    Production
    
    Treat this target as a production environment.
    
*   `allow_cookies` (_boolean_, nullable) Set true to forward the HTTP cookie header sent by clients to your origin and ensure the Set-Cookie header sent by your app is respected and not stripped.
*   `enable_source_maps` (_boolean_, nullable) Set true to enable source map support. This will set the NODE\_OPTIONS environment variable to "--enable-source-maps" in your MRT environment.
*   `log_level` (_LogLevelEnum | NullEnum_, nullable)
    
    The minimum log level that will be emitted for this target
    
    *   `TRACE` - TRACE
    *   `DEBUG` - DEBUG
    *   `INFO` - INFO
    *   `WARN` - WARN
    *   `ERROR` - ERROR
    *   `FATAL` - FATAL
    
    One of: `LogLevelEnum`, `NullEnum`.
    
*   `certificate_id` (_integer_, write-only, nullable) The ID of the certificate to associate with this target's custom domain. Must be an integer unique within the organization.  
    Minimum: 0.
*   `certificate_domain` (_string_, read-only) The certificate domain used by this target. For MRT default domains, returns wildcard format (e.g., \*.mobify-storefront-staging.com). For custom domains, returns the certificate domain name.
*   `configured_cdn` (_ConfiguredCdnEnum | NullEnum_, read-only, nullable)
    
    The content delivery network used for content, traffic, and security. A B2C instance must be connected to this environment to select eCDN.
    
    *   `unknown` - unknown
    *   `mrt_cdn` - mrt\_cdn
    *   `ecdn` - ecdn
    *   `stacked_cdn` - stacked\_cdn
    
    One of: `ConfiguredCdnEnum`, `NullEnum`.
    
*   `cdn_public_hostname` (_string_, read-only, nullable) Add a publicly visible hostname. Enter a subdomain if one is not already provided with your organization’s certified domain.
*   `source` (_SourceEnum | NullEnum_, read-only, nullable)
    
    Source of the environment. One of: ecom, core, direct.
    
    *   `ecom` - ecom
    *   `core` - core
    *   `direct` - direct
    
    One of: `SourceEnum`, `NullEnum`.
    

### APITargetV2Update

This is the base Target serializer.

*   `slug` (_string_, read-only)  
    Pattern: ^\[-a-zA-Z0-9\_\]+$.
*   `name` (_string_, required) User-friendly name for this target  
    Maximum length: 64.
*   `state` (_object_, read-only)
    
    Target State
    
    *   `CREATE_IN_PROGRESS` - Create in Progress
    *   `PUBLISH_IN_PROGRESS` - Publish in Progress
    *   `ACTIVE` - Active
    *   `CREATE_FAILED` - Create Failed
    *   `PUBLISH_FAILED` - Publish Failed
    
    Includes all fields of `StateEnum`.
    
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    
*   `hostname` (_string_, nullable) Hostname (literal or JavaScript regular expression between / characters) on which this target should be loaded by the V8 Tag  
    Maximum length: 128.
*   `current_deploy` (_object_, read-only)
    
    Additional properties: `any`.
    
*   `ssr_external_hostname` (_string_, nullable) Full hostname to be used by the environment eg. [www.customer.com](http://www.customer.com).  
    Maximum length: 128.
*   `ssr_external_domain` (_string_, nullable) The domain to be used for a Universal PWA SSR deployment (e.g. customer.com)  
    Maximum length: 128.
*   `ssr_region` (_SsrRegionEnum | BlankEnum_)
    
    SSR AWS Region
    
    The AWS region to which a Universal PWA SSR should be deployed (e.g. us-east-1)
    
    *   `us-east-1` - US East (N. Virginia)
    *   `us-east-2` - US East (Ohio)
    *   `us-west-1` - US West (N. California)
    *   `us-west-2` - US West (Oregon)
    *   `ap-south-1` - Asia Pacific (Mumbai)
    *   `ap-south-2` - Asia Pacific (Hyderabad)
    *   `ap-northeast-2` - Asia Pacific (Seoul)
    *   `ap-southeast-1` - Asia Pacific (Singapore)
    *   `ap-southeast-2` - Asia Pacific (Sydney)
    *   `ap-southeast-3` - Asia Pacific (Jakarta)
    *   `ap-northeast-1` - Asia Pacific (Tokyo)
    *   `ap-northeast-3` - Asia Pacific (Osaka)
    *   `ca-central-1` - Canada (Central)
    *   `eu-central-1` - EU (Frankfurt)
    *   `eu-central-2` - EU (Zurich)
    *   `eu-west-1` - EU (Ireland)
    *   `eu-west-2` - EU (London)
    *   `eu-west-3` - EU (Paris)
    *   `eu-north-1` - EU (Stockholm)
    *   `eu-south-1` - EU (Milan)
    *   `il-central-1` - Israel (Tel Aviv)
    *   `me-central-1` - Middle East (UAE)
    *   `sa-east-1` - South America (Sao Paulo)
    
    One of: `SsrRegionEnum`, `BlankEnum`.
    
*   `ssr_architecture` (_SsrArchitectureEnum | NullEnum_, nullable)
    
    The architecture for the Server-Side Rendering function (x86 or ARM64). If not specified, the ssr\_architecture that's set in the project is used.
    
    *   `x86` - x86
    *   `arm64` - ARM64
    
    One of: `SsrArchitectureEnum`, `NullEnum`.
    
*   `ssr_whitelisted_ips` (_string_, nullable) Optional space-separated list of IP addresses (CIDR blocks) that can access this target. Leave blank to allow all IPs.
*   `ssr_proxy_configs` (_array of object_, nullable)
    *   `host` (_string_, required)
    *   `protocol` (_string_)
*   `cdn_domain_name` (_string_, read-only) The Managed Runtime CDN origin domain name.
*   `is_production` (_boolean_)
    
    Production
    
    Treat this target as a production environment.
    
*   `allow_cookies` (_boolean_, nullable) Set true to forward the HTTP cookie header sent by clients to your origin and ensure the Set-Cookie header sent by your app is respected and not stripped.
*   `enable_source_maps` (_boolean_, nullable) Set true to enable source map support. This will set the NODE\_OPTIONS environment variable to "--enable-source-maps" in your MRT environment.
*   `log_level` (_LogLevelEnum | NullEnum_, nullable)
    
    The minimum log level that will be emitted for this target
    
    *   `TRACE` - TRACE
    *   `DEBUG` - DEBUG
    *   `INFO` - INFO
    *   `WARN` - WARN
    *   `ERROR` - ERROR
    *   `FATAL` - FATAL
    
    One of: `LogLevelEnum`, `NullEnum`.
    
*   `certificate_id` (_integer_, write-only, nullable) The ID of the certificate to associate with this target's custom domain. Must be an integer unique within the organization. Set to null to remove the certificate association.  
    Minimum: 0.
*   `certificate_domain` (_string_, read-only) The certificate domain used by this target. For MRT default domains, returns wildcard format (e.g., \*.mobify-storefront-staging.com). For custom domains, returns the certificate domain name.
*   `configured_cdn` (_ConfiguredCdnEnum | NullEnum_, read-only, nullable)
    
    The content delivery network used for content, traffic, and security. A B2C instance must be connected to this environment to select eCDN.
    
    *   `unknown` - unknown
    *   `mrt_cdn` - mrt\_cdn
    *   `ecdn` - ecdn
    *   `stacked_cdn` - stacked\_cdn
    
    One of: `ConfiguredCdnEnum`, `NullEnum`.
    
*   `cdn_public_hostname` (_string_, read-only, nullable) Add a publicly visible hostname. Enter a subdomain if one is not already provided with your organization’s certified domain.
*   `source` (_SourceEnum | NullEnum_, read-only, nullable)
    
    Source of the environment. One of: ecom, core, direct.
    
    *   `ecom` - ecom
    *   `core` - core
    *   `direct` - direct
    
    One of: `SourceEnum`, `NullEnum`.
    

### PatchedAPITargetV2Update

This is the base Target serializer.

*   `slug` (_string_, read-only)  
    Pattern: ^\[-a-zA-Z0-9\_\]+$.
*   `name` (_string_) User-friendly name for this target  
    Maximum length: 64.
*   `state` (_object_, read-only)
    
    Target State
    
    *   `CREATE_IN_PROGRESS` - Create in Progress
    *   `PUBLISH_IN_PROGRESS` - Publish in Progress
    *   `ACTIVE` - Active
    *   `CREATE_FAILED` - Create Failed
    *   `PUBLISH_FAILED` - Publish Failed
    
    Includes all fields of `StateEnum`.
    
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    
*   `hostname` (_string_, nullable) Hostname (literal or JavaScript regular expression between / characters) on which this target should be loaded by the V8 Tag  
    Maximum length: 128.
*   `current_deploy` (_object_, read-only)
    
    Additional properties: `any`.
    
*   `ssr_external_hostname` (_string_, nullable) Full hostname to be used by the environment eg. [www.customer.com](http://www.customer.com).  
    Maximum length: 128.
*   `ssr_external_domain` (_string_, nullable) The domain to be used for a Universal PWA SSR deployment (e.g. customer.com)  
    Maximum length: 128.
*   `ssr_region` (_SsrRegionEnum | BlankEnum_)
    
    SSR AWS Region
    
    The AWS region to which a Universal PWA SSR should be deployed (e.g. us-east-1)
    
    *   `us-east-1` - US East (N. Virginia)
    *   `us-east-2` - US East (Ohio)
    *   `us-west-1` - US West (N. California)
    *   `us-west-2` - US West (Oregon)
    *   `ap-south-1` - Asia Pacific (Mumbai)
    *   `ap-south-2` - Asia Pacific (Hyderabad)
    *   `ap-northeast-2` - Asia Pacific (Seoul)
    *   `ap-southeast-1` - Asia Pacific (Singapore)
    *   `ap-southeast-2` - Asia Pacific (Sydney)
    *   `ap-southeast-3` - Asia Pacific (Jakarta)
    *   `ap-northeast-1` - Asia Pacific (Tokyo)
    *   `ap-northeast-3` - Asia Pacific (Osaka)
    *   `ca-central-1` - Canada (Central)
    *   `eu-central-1` - EU (Frankfurt)
    *   `eu-central-2` - EU (Zurich)
    *   `eu-west-1` - EU (Ireland)
    *   `eu-west-2` - EU (London)
    *   `eu-west-3` - EU (Paris)
    *   `eu-north-1` - EU (Stockholm)
    *   `eu-south-1` - EU (Milan)
    *   `il-central-1` - Israel (Tel Aviv)
    *   `me-central-1` - Middle East (UAE)
    *   `sa-east-1` - South America (Sao Paulo)
    
    One of: `SsrRegionEnum`, `BlankEnum`.
    
*   `ssr_architecture` (_SsrArchitectureEnum | NullEnum_, nullable)
    
    The architecture for the Server-Side Rendering function (x86 or ARM64). If not specified, the ssr\_architecture that's set in the project is used.
    
    *   `x86` - x86
    *   `arm64` - ARM64
    
    One of: `SsrArchitectureEnum`, `NullEnum`.
    
*   `ssr_whitelisted_ips` (_string_, nullable) Optional space-separated list of IP addresses (CIDR blocks) that can access this target. Leave blank to allow all IPs.
*   `ssr_proxy_configs` (_array of object_, nullable)
    *   `host` (_string_, required)
    *   `protocol` (_string_)
*   `cdn_domain_name` (_string_, read-only) The Managed Runtime CDN origin domain name.
*   `is_production` (_boolean_)
    
    Production
    
    Treat this target as a production environment.
    
*   `allow_cookies` (_boolean_, nullable) Set true to forward the HTTP cookie header sent by clients to your origin and ensure the Set-Cookie header sent by your app is respected and not stripped.
*   `enable_source_maps` (_boolean_, nullable) Set true to enable source map support. This will set the NODE\_OPTIONS environment variable to "--enable-source-maps" in your MRT environment.
*   `log_level` (_LogLevelEnum | NullEnum_, nullable)
    
    The minimum log level that will be emitted for this target
    
    *   `TRACE` - TRACE
    *   `DEBUG` - DEBUG
    *   `INFO` - INFO
    *   `WARN` - WARN
    *   `ERROR` - ERROR
    *   `FATAL` - FATAL
    
    One of: `LogLevelEnum`, `NullEnum`.
    
*   `certificate_id` (_integer_, write-only, nullable) The ID of the certificate to associate with this target's custom domain. Must be an integer unique within the organization. Set to null to remove the certificate association.  
    Minimum: 0.
*   `certificate_domain` (_string_, read-only) The certificate domain used by this target. For MRT default domains, returns wildcard format (e.g., \*.mobify-storefront-staging.com). For custom domains, returns the certificate domain name.
*   `configured_cdn` (_ConfiguredCdnEnum | NullEnum_, read-only, nullable)
    
    The content delivery network used for content, traffic, and security. A B2C instance must be connected to this environment to select eCDN.
    
    *   `unknown` - unknown
    *   `mrt_cdn` - mrt\_cdn
    *   `ecdn` - ecdn
    *   `stacked_cdn` - stacked\_cdn
    
    One of: `ConfiguredCdnEnum`, `NullEnum`.
    
*   `cdn_public_hostname` (_string_, read-only, nullable) Add a publicly visible hostname. Enter a subdomain if one is not already provided with your organization’s certified domain.
*   `source` (_SourceEnum | NullEnum_, read-only, nullable)
    
    Source of the environment. One of: ecom, core, direct.
    
    *   `ecom` - ecom
    *   `core` - core
    *   `direct` - direct
    
    One of: `SourceEnum`, `NullEnum`.
    

### PaginatedAPIAccessControlHeaderV2CreateList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of APIAccessControlHeaderV2Create_, required)

### APIAccessControlHeaderV2Create

*   `id` (_string (uuid)_, read-only) Id for this Access Control Header.
*   `value` (_string_, required) Value to be encrypted. A header value is made up of your chosen set of characters. For the constraints that apply to the value, see [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html?q=access%20control%20header#access-control-headers).
*   `user_email` (_string (email)_, read-only) Email address
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `publishing_status` (_object_, read-only)
    
    Includes all fields of `Status1d2Enum`.
    
*   `publishing_status_description` (_string_, read-only)

### PaginatedDeployListList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of DeployList_, required)

### DeployCreate

This is the serializer for create deploy API endpoint.

*   `bundle_id` (_any_, required) Integer ID of the bundle to deploy or the string `current`, which re-deploys the currently deployed bundle

### PaginatedEnvironmentVariableListList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of EnvironmentVariableList_, required)

### APITargetV2CreateInvalidation

This is the serializer for cache invalidation API endpoint.

*   `pattern` (_string_, required) Path pattern to invalidate on the CDN. This must start with a forward slash (`/`).
*   `items` (_array of string_, nullable, deprecated) \[Deprecated\] Items to invalidate in the application cache.  
    Default: `[]`. Maximum items: 50000.
*   `namespace` (_string_, deprecated) \[Deprecated\] Namespace of items to invalidate in the application cache.

### PaginatedAPIRedirectV2CreateUpdateList

*   `count` (_integer_, required)  
    Example: `123`.
*   `next` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=400&limit=100`.
*   `previous` (_string (uri)_, nullable)  
    Example: `http://api.example.org/accounts/?offset=200&limit=100`.
*   `results` (_array of APIRedirectV2CreateUpdate_, required)

### APIRedirectV2CreateUpdate

*   `from_path` (_string_, required) A relative URL. For example, the `from_path` value `/spring` redirects shoppers from the URL `www.example.com/spring`. An asterisk (`*`) at the end of the `from_path` indicates a wildcard. For example, a redirect from `/a/*` matches `/a/`, `/a/b`, and `/a/b/c`.  
    Maximum length: 2000.
*   `to_url` (_string_, required) A relative or absolute URL. For example, the `to_url` value `/summer` redirects shoppers to the URL `www.example.com/summer`.  
    Maximum length: 2000.
*   `forward_querystring` (_boolean_, nullable) Some requests contain query string parameters to include in the redirected request. For example, the relative path `/spring-landing-page` can be appended with a query string for analytics tracking, such as `/spring-landing-page?gclid=123`. The `true` value includes query string parameters in the redirect. The `false` value excludes query string parameters from the redirect. The default value is `false`.
*   `forward_wildcard` (_boolean_, nullable) The `true` value automatically includes any path that comes after the wildcard portion of the `from_path` in the `to_url`. For example: if `/a/*` matches `/a/b/c` in the `from_path` and the `to_url` is `/z/`, the redirect URL is `/z/b/c`. The `false` value excludes the wildcard portion. The default value is `false`.
*   `http_status_code` (_object_)
    
    The HTTP status code to be returned in the response. 301 (Moved Permanently) is the recommended and default value. 302 (Found or Moved Temporarily) is another allowable value. For more information about HTTP status codes, see this [status code explainer](https://moz.com/learn/seo/redirection).
    
    *   `301` - Permanent 301
    *   `302` - Temporary 302
    
    Includes all fields of `HttpStatusCodeEnum`.
    
*   `publishing_status` (_string_, read-only) The status of the redeployment that happens after you call this API. Allowable values: Pending, Completed, Failed. If the request failed, you can [redeploy the environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) specified in your request.
*   `user_email` (_string (email)_, read-only)
    
    Email address
    
    Email of the user who created the redirect.
    
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `updated_by` (_string (email)_, read-only)
    
    Email address
    
    Email of the user who last updated the redirect.
    

### PatchedAPIRedirectV2CreateUpdate

*   `from_path` (_string_) A relative URL. For example, the `from_path` value `/spring` redirects shoppers from the URL `www.example.com/spring`. An asterisk (`*`) at the end of the `from_path` indicates a wildcard. For example, a redirect from `/a/*` matches `/a/`, `/a/b`, and `/a/b/c`.  
    Maximum length: 2000.
*   `to_url` (_string_) A relative or absolute URL. For example, the `to_url` value `/summer` redirects shoppers to the URL `www.example.com/summer`.  
    Maximum length: 2000.
*   `forward_querystring` (_boolean_, nullable) Some requests contain query string parameters to include in the redirected request. For example, the relative path `/spring-landing-page` can be appended with a query string for analytics tracking, such as `/spring-landing-page?gclid=123`. The `true` value includes query string parameters in the redirect. The `false` value excludes query string parameters from the redirect. The default value is `false`.
*   `forward_wildcard` (_boolean_, nullable) The `true` value automatically includes any path that comes after the wildcard portion of the `from_path` in the `to_url`. For example: if `/a/*` matches `/a/b/c` in the `from_path` and the `to_url` is `/z/`, the redirect URL is `/z/b/c`. The `false` value excludes the wildcard portion. The default value is `false`.
*   `http_status_code` (_object_)
    
    The HTTP status code to be returned in the response. 301 (Moved Permanently) is the recommended and default value. 302 (Found or Moved Temporarily) is another allowable value. For more information about HTTP status codes, see this [status code explainer](https://moz.com/learn/seo/redirection).
    
    *   `301` - Permanent 301
    *   `302` - Temporary 302
    
    Includes all fields of `HttpStatusCodeEnum`.
    
*   `publishing_status` (_string_, read-only) The status of the redeployment that happens after you call this API. Allowable values: Pending, Completed, Failed. If the request failed, you can [redeploy the environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) specified in your request.
*   `user_email` (_string (email)_, read-only)
    
    Email address
    
    Email of the user who created the redirect.
    
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `updated_by` (_string (email)_, read-only)
    
    Email address
    
    Email of the user who last updated the redirect.
    

### APIRedirectV2Clone

*   `from_target_slug` (_string_, required)  
    Pattern: ^\[-a-zA-Z0-9\_\]+$.

### UserEmailPreferences

*   `node_deprecation_notifications` (_boolean_) Receive email notifications about Node.js runtime deprecations
*   `custom_domain_certificate_notifications` (_boolean_) Receive email notifications about custom domain certificate changes
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.

### PatchedUserEmailPreferences

*   `node_deprecation_notifications` (_boolean_) Receive email notifications about Node.js runtime deprecations
*   `custom_domain_certificate_notifications` (_boolean_) Receive email notifications about custom domain certificate changes
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.

### APIUserProfile

*   `first_name` (_string_)  
    Maximum length: 255.
*   `last_name` (_string_)  
    Maximum length: 255.
*   `email` (_string (email)_, read-only) Email address
*   `is_staff` (_boolean_, read-only)
    
    Staff status
    
    Designates whether the user can log into this admin site.
    
*   `date_joined` (_string (date-time)_, read-only)
*   `uuid` (_string (uuid)_, read-only)
*   `highest_account_manager_role` (_string_, read-only)

### APIOrganization

*   `uuid` (_string (uuid)_, read-only)
*   `name` (_string_, required)  
    Maximum length: 128.
*   `slug` (_string_, required)  
    Maximum length: 64. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$.
*   `deletion_status` (_object_, read-only)
    
    Includes all fields of `DeletionStatusEnum`.
    
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `permissions` (_object_, read-only)
    *   `create_project` (_boolean_)
*   `has_mobify_tag_project` (_boolean_, read-only)
*   `limits` (_object_, read-only)
    
    Includes all fields of `OrganizationLimits`.
    
*   `auto_delete` (_object_, read-only)
    
    Includes all fields of `OrganizationAutoDelete`.
    
*   `can_configure_ssr_architecture` (_boolean_, read-only) Enable SSR architecture selection (x86 or arm64) for this organization

### ValidationStatusEnum

*   `pending_validation` - Pending Validation
*   `validation_succeeded` - Validation Succeeded
*   `validation_failed` - Validation Failed

Type: `string`.

Allowed values: `pending_validation`, `validation_succeeded`, `validation_failed`.

### RenewalStatusEnum

*   `PENDING_AUTO_RENEWAL` - Pending Auto Renewal
*   `FAILED` - Failed

Type: `string`.

Allowed values: `PENDING_AUTO_RENEWAL`, `FAILED`.

### NullEnum

Type: `any`.

### RenewalEligibilityEnum

*   `ELIGIBLE` - Eligible
*   `INELIGIBLE` - Ineligible

Type: `string`.

Allowed values: `ELIGIBLE`, `INELIGIBLE`.

### DeletionStatusEnum

*   `ACTIVE` - Active
*   `CLEANUP_REQUESTED` - Cleanup Requested
*   `CLEANUP_IN_PROGRESS` - Cleanup in Progress
*   `CLEANUP_COMPLETE` - Cleanup Complete
*   `CLEANUP_FAILED` - Cleanup Failed

Type: `string`.

Allowed values: `ACTIVE`, `CLEANUP_REQUESTED`, `CLEANUP_IN_PROGRESS`, `CLEANUP_COMPLETE`, `CLEANUP_FAILED`.

### RoleEnum

*   `0` - Owner
*   `1` - Member

Type: `integer`.

Allowed values: `0`, `1`.

### Status1d2Enum

*   `0` - Pending
*   `1` - Completed
*   `2` - Failed

Type: `integer`.

Allowed values: `0`, `1`, `2`.

### ProjectTypeEnum

*   `MOBIFY_STUDIO` - MOBIFY\_STUDIO
*   `MOBIFYJS_CLIENT` - MOBIFYJS\_CLIENT
*   `MOBIFY_ADAPTIVEJS` - MOBIFY\_ADAPTIVEJS
*   `MOBIFY_TAG_BASED_PWA` - MOBIFY\_TAG\_BASED\_PWA
*   `SSR` - SSR

Type: `string`.

Allowed values: `MOBIFY_STUDIO`, `MOBIFYJS_CLIENT`, `MOBIFY_ADAPTIVEJS`, `MOBIFY_TAG_BASED_PWA`, `SSR`.

### SsrRegionEnum

*   `us-east-1` - US East (N. Virginia)
*   `us-east-2` - US East (Ohio)
*   `us-west-1` - US West (N. California)
*   `us-west-2` - US West (Oregon)
*   `ap-south-1` - Asia Pacific (Mumbai)
*   `ap-south-2` - Asia Pacific (Hyderabad)
*   `ap-northeast-2` - Asia Pacific (Seoul)
*   `ap-southeast-1` - Asia Pacific (Singapore)
*   `ap-southeast-2` - Asia Pacific (Sydney)
*   `ap-southeast-3` - Asia Pacific (Jakarta)
*   `ap-northeast-1` - Asia Pacific (Tokyo)
*   `ap-northeast-3` - Asia Pacific (Osaka)
*   `ca-central-1` - Canada (Central)
*   `eu-central-1` - EU (Frankfurt)
*   `eu-central-2` - EU (Zurich)
*   `eu-west-1` - EU (Ireland)
*   `eu-west-2` - EU (London)
*   `eu-west-3` - EU (Paris)
*   `eu-north-1` - EU (Stockholm)
*   `eu-south-1` - EU (Milan)
*   `il-central-1` - Israel (Tel Aviv)
*   `me-central-1` - Middle East (UAE)
*   `sa-east-1` - South America (Sao Paulo)

Type: `string`.

Allowed values: `us-east-1`, `us-east-2`, `us-west-1`, `us-west-2`, `ap-south-1`, `ap-south-2`, `ap-northeast-2`, `ap-southeast-1`, `ap-southeast-2`, `ap-southeast-3`, `ap-northeast-1`, `ap-northeast-3`, `ca-central-1`, `eu-central-1`, `eu-central-2`, `eu-west-1`, `eu-west-2`, `eu-west-3`, `eu-north-1`, `eu-south-1`, `il-central-1`, `me-central-1`, `sa-east-1`.

### SsrArchitectureEnum

*   `x86` - x86
*   `arm64` - ARM64

Type: `string`.

Allowed values: `x86`, `arm64`.

### SourceEnum

*   `ecom` - ecom
*   `core` - core
*   `direct` - direct

Type: `string`.

Allowed values: `ecom`, `core`, `direct`.

### EncodingEnum

*   `base64` - base64

Type: `string`.

Allowed values: `base64`.

### BundleList

*   `id` (_integer_, required) A ID unique within a project.  
    Minimum: 0. Maximum: 2147483647.
*   `message` (_string_, required)  
    Maximum length: 2048.
*   `status` (_object_)  
    Minimum: -2147483648. Maximum: 2147483647.
    
    Includes all fields of `Status1d2Enum`.
    
    Minimum: -2147483648. Maximum: 2147483647.
    
*   `deletion_status` (_DeletionStatusEnum_)
*   `user` (_string (email)_, read-only) Email address
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.

### BundleBulkDeleteFailedRequest

*   `bundle_id` (_integer_, required) The ID of the bundle that failed validation.
*   `errors` (_string_, required) Error message that explains why the bundle can't be queued for deletion.

### EmailNotificationTyped

Includes all fields of `EmailNotification`.

*   `resourcetype` (_string_, required)

### PatchedEmailNotificationTyped

Includes all fields of `PatchedEmailNotification`.

*   `resourcetype` (_string_)

### StateEnum

*   `CREATE_IN_PROGRESS` - Create in Progress
*   `PUBLISH_IN_PROGRESS` - Publish in Progress
*   `ACTIVE` - Active
*   `CREATE_FAILED` - Create Failed
*   `PUBLISH_FAILED` - Publish Failed

Type: `string`.

Allowed values: `CREATE_IN_PROGRESS`, `PUBLISH_IN_PROGRESS`, `ACTIVE`, `CREATE_FAILED`, `PUBLISH_FAILED`.

### BlankEnum

Type: `any`.

Allowed values: .

### LogLevelEnum

*   `TRACE` - TRACE
*   `DEBUG` - DEBUG
*   `INFO` - INFO
*   `WARN` - WARN
*   `ERROR` - ERROR
*   `FATAL` - FATAL

Type: `string`.

Allowed values: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`.

### ConfiguredCdnEnum

*   `unknown` - unknown
*   `mrt_cdn` - mrt\_cdn
*   `ecdn` - ecdn
*   `stacked_cdn` - stacked\_cdn

Type: `string`.

Allowed values: `unknown`, `mrt_cdn`, `ecdn`, `stacked_cdn`.

### DeployList

*   `user` (_string (email)_, read-only) Email address
*   `bundle` (_BundleList_, required)
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `status` (_object_, read-only)
    
    Includes all fields of `DeployListStatusEnum`.
    
*   `deploy_type` (_object_, read-only)
    
    Includes all fields of `DeployTypeEnum`.
    
*   `external_publish_id` (_string (uuid)_, nullable) Id for an external publishing operation for this Deploy
*   `deploy_settings` (_integer_, nullable)
*   `duration` (_string_, required)

### EnvironmentVariableList

*   `name` (_string_, required) Name of the Environment Variable.  
    Maximum length: 512.
*   `value` (_string_, required) Value to be encrypted.
*   `created_by` (_string (email)_, read-only) Email address
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `updated_by` (_string (email)_, read-only) Email address
*   `publishing_status` (_object_, read-only)
    
    Includes all fields of `Status1d2Enum`.
    
*   `publishing_status_description` (_string_, read-only)

### HttpStatusCodeEnum

*   `301` - Permanent 301
*   `302` - Temporary 302

Type: `integer`.

Allowed values: `301`, `302`.

### OrganizationLimits

*   `max_environments` (_ResourceLimit_, required)
*   `max_production_environments` (_ResourceLimit_, required)

### OrganizationAutoDelete

*   `enabled` (_boolean_, required)
*   `threshold` (_integer_, required)

### EmailNotification

*   `id` (_string (uuid)_, read-only)
*   `targets` (_array of string_, required)
    
    Each item: User-friendly identifier for this target.
    
*   `recipients` (_array of string (email)_, required)  
    Items: Maximum length: 254.
*   `deployment_start` (_boolean_) Trigger this notification when a deployment starts for a target
*   `deployment_success` (_boolean_) Trigger this notification when a deployment succeeds for a target
*   `deployment_failed` (_boolean_) Trigger this notification when a deployment fails for a target
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `updated_by` (_string (email)_, read-only) Email address

### PatchedEmailNotification

*   `id` (_string (uuid)_, read-only)
*   `targets` (_array of string_)
    
    Each item: User-friendly identifier for this target.
    
*   `recipients` (_array of string (email)_)  
    Items: Maximum length: 254.
*   `deployment_start` (_boolean_) Trigger this notification when a deployment starts for a target
*   `deployment_success` (_boolean_) Trigger this notification when a deployment succeeds for a target
*   `deployment_failed` (_boolean_) Trigger this notification when a deployment fails for a target
*   `created_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was created.
*   `updated_at` (_string (date-time)_, read-only) Timestamp in the extended ISO 8601 format for when the object was last updated.
*   `updated_by` (_string (email)_, read-only) Email address

### DeployListStatusEnum

*   `Queued` - Queued
*   `In Progress` - In Progress
*   `Failed` - Failed
*   `Finished` - Finished

Type: `string`.

Allowed values: `Queued`, `In Progress`, `Failed`, `Finished`.

### DeployTypeEnum

*   `Publish` - Publish
*   `Reset Bundle` - Reset Bundle
*   `Push` - Push
*   `Deploy Settings` - Deploy Settings
*   `Redeploy` - Redeploy

Type: `string`.

Allowed values: `Publish`, `Reset Bundle`, `Push`, `Deploy Settings`, `Redeploy`.

### ResourceLimit

*   `limit` (_integer_, required)
*   `used` (_integer_, required)

<!-- document id=361e532939fc73cb9202a408f6a28bf236f68c71de66a3529764ca08a37f8eea url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/references/generated-api-specs/mrt-b2c-config.md -->

MRT B2C Config

# MRT B2C Config

Set up how a storefront or other headless commerce application is deployed to Managed Runtime.  
  
Note: Where possible, we changed noninclusive terms to align with our company value of Equality. We maintained certain terms to avoid any effect on customer implementations.

**Version:** v1

## Servers

*   `https://cloud.mobify.com/api/cc/b2c/`

## Security

*   `Basic` (http) A basic authentication scheme for Managed Runtime API endpoints. To make an API request, concatenate your email address and API key separated by a colon (:). Base64 encode the concatenated string and include it in the HTTP request Authorization header.  
      
    Example:  
      
    `Authorization: Basic $B64_ENCODED_VALUE`
    *   HTTP scheme: basic
*   `BearerToken` (http) A bearer token authentication scheme for Managed Runtime API endpoints. To make an API request, include your API key in the HTTP request Authorization header.  
      
    Example:  
      
    `Authorization: Bearer $API_KEY`
    *   HTTP scheme: bearer (Bearer .\*)

## Operations

### GET cc\_b2c\_organization\_info\_retrieve

`GET /b2c-organization-info/{organization_slug}/`

Operation ID: `cc_b2c_organization_info_retrieve`. Tags: b2c-organization-info. Security: Basic; BearerToken.

Get the list of B2C Commerce instances connected to a specified organization. This allows you to track the integrations between your Managed Runtime targets (environments) and Commerce Cloud.

#### Parameters

*   `organization_slug` (path, string, required) The organization identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIB2COrgInfo`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "is_b2c_customer": true,
      "instances": [
        "aaaa_prd",
        "aaaa_stg",
        "aaaa_dev",
        "aaaa_001"
      ]
    }
    ```
    

### GET cc\_b2c\_target\_info\_retrieve

`GET /projects/{project_slug}/b2c-target-info/{target_slug}/`

Operation ID: `cc_b2c_target_info_retrieve`. Tags: projects. Security: Basic; BearerToken.

Get the B2C Commerce instance and sites connected to a specified target (environment). This allows you to track the integrations between your Managed Runtime targets and Commerce Cloud.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIB2CTargetInfo`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "instance_id": "aaaa_prd",
      "sites": [
        "DemoSite1",
        "DemoSite2"
      ]
    }
    ```
    

### PUT cc\_b2c\_target\_info\_update

`PUT /projects/{project_slug}/b2c-target-info/{target_slug}/`

Operation ID: `cc_b2c_target_info_update`. Tags: projects. Security: Basic; BearerToken.

Create B2C information for a target.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body (required)

Media type: `application/json`. Schema: `APIB2CTargetInfo`.

_Example: RequestExample1_

```
{
  "instance_id": "aaaa_prd",
  "sites": [
    "DemoSite1",
    "DemoSite2"
  ]
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `APIB2CTargetInfo`.

Media type: `multipart/form-data`. Schema: `APIB2CTargetInfo`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIB2CTargetInfo`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "instance_id": "aaaa_prd",
      "sites": [
        "DemoSite1",
        "DemoSite2"
      ]
    }
    ```
    

### PATCH cc\_b2c\_target\_info\_partial\_update

`PATCH /projects/{project_slug}/b2c-target-info/{target_slug}/`

Operation ID: `cc_b2c_target_info_partial_update`. Tags: projects. Security: Basic; BearerToken.

Edit a specified target's (environment's) connection to a B2C Commerce instance. If you pass in a list of site IDs, that list replaces the existing sites connected to the target.

#### Parameters

*   `project_slug` (path, string, required) The project identifier.
*   `target_slug` (path, string, required) The target identifier.

#### Request body

Media type: `application/json`. Schema: `PatchedAPIB2CTargetInfo`.

_Example: RequestExample1_

```
{
  "instance_id": "aaaa_prd",
  "sites": [
    "DemoSite1",
    "DemoSite2"
  ]
}
```

Media type: `application/x-www-form-urlencoded`. Schema: `PatchedAPIB2CTargetInfo`.

Media type: `multipart/form-data`. Schema: `PatchedAPIB2CTargetInfo`.

#### Responses

*   **200**
    
    Media type: `application/json`. Schema: `APIB2CTargetInfo`.
    
    _Example: ResponseExample1_
    
    ```
    {
      "instance_id": "aaaa_prd",
      "sites": [
        "DemoSite1",
        "DemoSite2"
      ]
    }
    ```
    

## Schemas

### APIB2COrgInfo

*   `is_b2c_customer` (_boolean_, required) Specifies whether the organization is a B2C customer account. Returns true if the organization is a B2C customer account. Returns false if the organization isn't a B2C customer account.
*   `instances` (_array of string_, required)
    
    Each item: List of B2C Commerce instances.
    
      
    Items: Maximum length: 8.

### APIB2CTargetInfo

*   `instance_id` (_string_, required) ID of the B2C Commerce instance associated with the target  
    Maximum length: 8.
*   `sites` (_array of string_, nullable)
    
    Each item: List of site IDs associated with the B2C Commerce instance
    
      
    Items: Maximum length: 32.

### PatchedAPIB2CTargetInfo

*   `instance_id` (_string_) ID of the B2C Commerce instance associated with the target  
    Maximum length: 8.
*   `sites` (_array of string_, nullable)
    
    Each item: List of site IDs associated with the B2C Commerce instance
    
      
    Items: Maximum length: 32.

<!-- document id=004891633a453d3072a549281775c408084dc00f4fb13106aed5b24a9c4ef0af url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/multiple-sites.md -->

# Multiple Sites

When a PWA Kit project is created with the Retail React App template, it is configured by default for a single locale and a single site. However, it can be extended to run multiple sites with a single code base.

## Site Configuration

The `config/sites.js` file contains a definition of the sites that you configured in Business Manager. The following example shows the configuration for the `RefArch` and `RefArchGlobal` sites:

```javascript
// /config/sites.js

module.exports = [
  {
    id: "RefArch",
    l10n: {
      supportedCurrencies: ["USD"],
      defaultCurrency: "USD",
      defaultLocale: "en-US",
      supportedLocales: [
        {
          id: "en-US",
          alias: "us",
          preferredCurrency: "USD",
        },
        {
          id: "en-CA",
          preferredCurrency: "USD",
        },
      ],
    },
  },
  {
    id: "RefArchGlobal",
    l10n: {
      supportedCurrencies: ["GBP", "EUR", "JPY"],
      defaultCurrency: "GBP",
      supportedLocales: [
        {
          id: "de-DE",
          alias: "de",
          preferredCurrency: "EUR",
        },
        {
          id: "en-GB",
          preferredCurrency: "GBP",
        },
        {
          id: "ja-JP",
          preferredCurrency: "JPY",
        },
      ],
      defaultLocale: "en-GB",
    },
  },
];
```

## Default Site and Aliases

In the `/config/default.js` file, you can set the default site and optionally, map the site IDs with aliases. If no alias is defined for the site, then IDs are used in URLs. The following example sets the default site to `RefArchGlobal` and defines three aliases for it.

```javascript
// /config/default.js

defaultSite: 'RefArchGlobal',
siteAliases: {
    RefArch: 'us',
    RefArchGlobal: 'global',
    NTOManaged: 'nto'
},
```

If you set `url.showDefault` to `true` in the `/config/default.js` file, the default locale and site are displayed in your application URLs. In addition to the site alias, you can also configure aliases for your locale in the `sites.js` file. If you configured an alias for a locale, the URL displays the alias instead of your locale ID.

**note:** Application URLs are constructed using canonical site and locale IDs and are still valid URLs even when aliases are used.

## Deployment for Multiple Domains

With environment-specific configuration files, you can manage multiple B2C sites defined in Business Manager and deploy them over different domains using multiple Managed Runtime environments.

For example, your site can be accessed from `customer.ca` and `customer.uk`, or `customer-a.com` and `customer-b.ca`. You can also customize the URL patterns further. For example, your URLs can be formatted as `customer-1.com/us` or `customer-2.com/?locale=en_US`.

You can deploy bundles to work with multiple domains using different Managed Runtime environments, each configured for a separate domain. The configuration mapping is done by creating a separate configuration file for each Managed Runtime environment.

For example, to deploy `customer-1.com` to the `env-customer-1` environment, and `customer-2.com` to the `env-customer-2` environment, you need to create the following files in place of `config/default.js`:

- `config/env-customer-1.js`
- `config/env-customer-2.js`

For more information on environment-specific configurations, see the [Configuration Files](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configuration-options.md) guide.

## See Also

- [Localization](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-localization.html)
- [Translations](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/translations/README.md#translations)

<!-- document id=5710a76cf9590cda666ac38c989508aee6b7461e9f6fbb3d930e8387ec3a20e5 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-node-version.md -->

# Node Version Support

Customers control which version of Node.js is used to run a Managed Runtime environment for Storefront Next. Every two years, customers must upgrade Node.js versions, as support for older versions is removed to maintain security.

## Supported Node Versions

**Support date definitions**

- **End of Life**: After this date, customers can no longer deploy bundles that use this version of Node.js.
- **Deprecation**: Customers start seeing a warning that a Node.js version upgrade is required for uninterrupted deployments.
- **Availability**: When this version of Node.js was first supported.

**The current recommended version is Node.js 24.**

| Version | Availability date | Deprecation date | End of Life date |
| ------- | ----------------- | ---------------- | ---------------- |
| 24.x    | June 9, 2026      |                  |                  |

## Opt Out of Email Notifications

By default, project teams receive automated email notifications when their environments are using deprecated or end-of-life Node.js versions. These notifications help ensure timely upgrades and avoid deployment disruptions.

To opt out of these notifications:

1. Log in to [Runtime Admin](https://runtime.commercecloud.com) and then click **Account Settings**.
2. In the **Email Notifications** section, deselect the notification you want to opt out of.

**note:** Keep these notifications enabled to ensure your team stays informed about required Node.js upgrades. Opting out may result in unexpected deployment failures when Node.js versions reach end of life.

<!-- document id=f02aee9c136b056e154296629cb5ff2cc81fa0200e7b49ae4b0d8de56aca0404 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/notification-api.md -->

Notification API

# Notification API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/notification-api/notification-api-oas-public.yaml)

POS Merchant API to upload notifications to be sent to target devices.

**Version:** 2.3.4

## Tags

### Notification API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/notification-api/notification-api-oas-public.yaml)

POS Merchant API to upload notifications to be sent to target devices.

## Operations

### POST Upload notifications for target devices.

`POST /merchant/{version}/notifications`

Operation ID: `scheduleNotifications`. Tags: Notification API.

Schedule immediate notifications to be sent to specified target devices.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `MerchantNotificationResponse`.
    

## Schemas

### MerchantNotificationResponse

*   `statusMessage` (_string_)
*   `notificationJobId` (_string_)

<!-- document id=1e93da8210079bb47c152bbb7a960b2dbb20efae18d2b89cdf80cf2783e3573e url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/object-definitions.md -->

Object Definitions

# Object Definitions

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/object-definitions/object-definitions-oas-v1-public.yaml)

## API Overview

Use the Object Definitions API to search for and manage attribute definitions for object types in B2C Commerce. Discover and inspect the metadata structure of objects such as Product, Customer, and Order.

Use this API to:

*   Search attribute definitions with complex queries
*   Filter by attribute properties (type, searchability, visibility, etc.)
*   Retrieve detailed metadata about attribute definitions
*   Discover available values for enum-type attributes

### Authentication & Authorization

The Object Definitions API requires valid authentication and authorization to be accessed. It uses an Account Manager OAuth 2.0 bearer token for authentication.

The necessary scope for accessing the Object Definitions API is:

*   `sfcc.object-definitions.rw`: Provides read-write access.

You must include the relevant scope in the client ID used to generate the token. For details, see [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

**Version:** 1.1.3

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/dx/object-definitions/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) Account Manager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.object-definitions: System Object Definitions Read SCOPE
    *   Scope sfcc.object-definitions.rw: System Object Definitions Read and Write SCOPE
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Get system object types

`GET /organizations/{organizationId}/system/object-types`

Operation ID: `getSystemObjectTypes`. Security: AmOAuth2 (sfcc.object-definitions, sfcc.object-definitions.rw).

Retrieves a paginated list of all system object type definitions.

Use the `select` parameter to specify which properties to include in the response. Use `offset` and `limit` for pagination.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Successfully returned system object types
    
    Media type: `application/json`. Schema: `ObjectTypeDefinitionResult`.
    
    _Example: SystemObjectTypeResultExample_ List of system object types
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 85,
      "data": [
        {
          "objectType": "Product",
          "displayName": {
            "default": "Product"
          },
          "description": {
            "default": "Object type representing products."
          },
          "readOnly": false,
          "queryable": false,
          "contentObject": true,
          "attributeDefinitionCount": 166,
          "attributeGroupCount": 8
        },
        {
          "objectType": "Order",
          "displayName": {
            "default": "Order"
          },
          "description": {
            "default": "Object type representing orders."
          },
          "readOnly": false,
          "queryable": true,
          "contentObject": false,
          "attributeDefinitionCount": 120,
          "attributeGroupCount": 5
        },
        {
          "objectType": "Customer",
          "displayName": {
            "default": "Customer"
          },
          "description": {
            "default": "Object type representing customers."
          },
          "readOnly": false,
          "queryable": true,
          "contentObject": false,
          "attributeDefinitionCount": 45,
          "attributeGroupCount": 3
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ObjectTypeNotFoundExample_
    
    ```
    {
      "title": "Object Type Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/object-type-not-found",
      "detail": "No object type with ID 'InvalidObjectType' could be found.",
      "objectType": "InvalidObjectType"
    }
    ```
    

### POST Search system object types

`POST /organizations/{organizationId}/system/object-types-search`

Operation ID: `searchSystemObjectTypes`. Security: AmOAuth2 (sfcc.object-definitions, sfcc.object-definitions.rw).

Searches system object type definitions based on the provided query criteria.

**Searchable fields:**

*   objectType (String)
*   display\_name\* (Localized String)
*   description\* (Localized String)
*   read\_only (boolean)

**Sortable fields:**

*   objectType
*   display\_name
*   description
*   read\_only

\*Note: Localized fields are searched across all locales.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

The search request for system object types

Media type: `application/json`. Schema: `SearchRequest`.

_Example: SearchSystemObjectTypes_ Search system object types by object type

```
{
  "query": {
    "textQuery": {
      "fields": [
        "objectType"
      ],
      "searchPhrase": "Customer"
    }
  }
}
```

#### Responses

*   **200** Successfully returned system object type search results
    
    Media type: `application/json`. Schema: `ObjectTypeDefinitionSearchResult`.
    
    _Example: SystemObjectTypeSearchResultExample_ System object type search result
    
    ```
    {
      "limit": 1,
      "offset": 0,
      "total": 1,
      "hits": [
        {
          "objectType": "Customer",
          "displayName": {
            "default": "Customer"
          },
          "description": {
            "default": "Object type representing customers."
          },
          "readOnly": false,
          "queryable": true,
          "contentObject": false,
          "attributeDefinitionCount": 45,
          "attributeGroupCount": 3
        }
      ]
    }
    ```
    
*   **400** Field Not Sortable
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: FieldNotSortableExample_
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'link' can't be used to sort the results."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get system object type

`GET /organizations/{organizationId}/system/object-types/{objectType}`

Operation ID: `getSystemObjectType`. Security: AmOAuth2 (sfcc.object-definitions, sfcc.object-definitions.rw).

Retrieves a single system object type definition by its identifier.

Use the `select` parameter to specify which properties to include in the response. Use the `expand` parameter to include related resources.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.

#### Responses

*   **200** Successfully returned the system object type
    
    Media type: `application/json`. Schema: `ObjectTypeDefinition`.
    
    _Example: SystemObjectTypeExample_ Single system object type
    
    ```
    {
      "objectType": "Product",
      "displayName": {
        "default": "Product"
      },
      "description": {
        "default": "Object type representing products."
      },
      "readOnly": false,
      "queryable": false,
      "searchable": true,
      "contentObject": true,
      "attributeDefinitionCount": 166,
      "attributeGroupCount": 8
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    

### POST Search attribute definitions for system object

`POST /organizations/{organizationId}/system/object-types/{objectType}/attribute-definition-search`

Operation ID: `searchAttributeDefinitionForSystemObject`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Searches the attribute definitions of the specified system object type.

The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets:

**Main bucket:**

*   id (String)
*   display\_name\* (Localized String)
*   description\* (Localized String)
*   key (boolean)
*   mandatory (boolean)
*   searchable (boolean)
*   system (boolean)
*   visible (boolean)

**Definition version bucket:**

*   localizable (boolean)
*   site\_specific (boolean)
*   value\_type (enum)

**Group bucket:**

*   group (String)

\*Note: These attributes are not searchable or sortable for built-in system attributes. They work normally for non-system attributes.

Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining localizable and description, only a conjunction is allowed (AND).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.

#### Request body (required)

The search request for attribute definitions

Media type: `application/json`. Schema: `SearchRequest`.

_Example: SearchByValueType_ Search by value type using term query

```
{
  "query": {
    "termQuery": {
      "fields": [
        "value_type"
      ],
      "operator": "is",
      "values": [
        "string"
      ]
    }
  },
  "limit": 25,
  "offset": 0
}
```

_Example: SearchWithSorting_ Search all with sorting by ID

```
{
  "query": {
    "matchAllQuery": {}
  },
  "limit": 100,
  "offset": 0,
  "sorts": [
    {
      "field": "id",
      "sortOrder": "asc"
    }
  ]
}
```

#### Responses

*   **200** Successfully returned attribute definition search results
    
    Media type: `application/json`. Schema: `ObjectAttributeDefinitionSearchResult`.
    
    _Example: ObjectAttributeDefinitionSearchResultExample_ Successful attribute definition search result
    
    ```
    {
      "limit": 2,
      "hits": [
        {
          "id": "color",
          "effectiveId": "c_color",
          "displayName": {
            "default": "Color"
          },
          "description": {
            "default": "The color of the product"
          },
          "key": false,
          "mandatory": false,
          "localizable": false,
          "siteSpecific": false,
          "searchable": true,
          "queryable": true,
          "valueType": "enum_of_string",
          "visible": true,
          "system": false,
          "multiValueType": false,
          "setValueType": false,
          "externallyManaged": false,
          "externallyDefined": false,
          "orderRequired": false,
          "requiresEncoding": false,
          "readOnly": false,
          "valueDefinitions": [
            {
              "id": "red",
              "value": "red",
              "displayValue": {
                "default": "Red"
              },
              "position": 1
            },
            {
              "id": "blue",
              "value": "blue",
              "displayValue": {
                "default": "Blue"
              },
              "position": 2
            }
          ]
        },
        {
          "id": "size",
          "effectiveId": "c_size",
          "displayName": {
            "default": "Size"
          },
          "description": {
            "default": "The size of the product"
          },
          "key": false,
          "mandatory": true,
          "localizable": false,
          "siteSpecific": false,
          "searchable": true,
          "queryable": true,
          "valueType": "string",
          "visible": true,
          "system": false,
          "multiValueType": false,
          "setValueType": false,
          "externallyManaged": false,
          "externallyDefined": false,
          "orderRequired": false,
          "requiresEncoding": false,
          "readOnly": false
        }
      ],
      "offset": 0,
      "total": 2
    }
    ```
    
*   **400** Field Not Sortable
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example FieldNotSortableExample: same as POST /organizations/{organizationId}/system/object-types-search 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    

### POST Search attribute groups for system object

`POST /organizations/{organizationId}/system/object-types/{objectType}/attribute-group-search`

Operation ID: `searchAttributeGroupsForSystemObject`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Searches the attribute groups of the specified system object type.

**Searchable fields:**

*   id (String)
*   display\_name (Localized String)
*   description (Localized String)
*   internal (boolean)
*   position (number)

**Sortable fields:**

*   id
*   display\_name
*   description
*   internal
*   position

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.

#### Request body (required)

The search request for attribute groups

Media type: `application/json`. Schema: `SearchRequest`.

_Example: SearchAttributeGroups_ Search attribute groups

```
{
  "query": {
    "matchAllQuery": {}
  },
  "limit": 25,
  "offset": 0
}
```

_Example: SearchAttributeGroupsByDisplayName_ Search attribute groups by display name

```
{
  "query": {
    "textQuery": {
      "fields": [
        "display_name"
      ],
      "searchPhrase": "custom"
    }
  },
  "limit": 25,
  "offset": 0
}
```

#### Responses

*   **200** Successfully returned attribute group search results
    
    Media type: `application/json`. Schema: `ObjectAttributeGroupSearchResult`.
    
    _Example: ObjectAttributeGroupSearchResultExample_ Attribute group search result
    
    ```
    {
      "limit": 1,
      "offset": 0,
      "total": 1,
      "hits": [
        {
          "id": "SiteMap",
          "displayName": {
            "default": "Site Map"
          },
          "description": {
            "default": "Site map attributes"
          },
          "position": 3,
          "internal": false,
          "attributeDefinitionsCount": 3
        }
      ]
    }
    ```
    
*   **400** Field Not Sortable
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example MalformedSearchParameterExample: same as POST /organizations/{organizationId}/system/object-types-search 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    

### GET Get attribute groups

`GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups`

Operation ID: `getAttributeGroups`. Security: AmOAuth2 (sfcc.object-definitions, sfcc.object-definitions.rw).

Retrieves a paginated list of attribute groups for the specified system object type.

Use the `select` parameter to specify which properties to include in the response. Use the `expand` parameter with value `definition` to include attribute definitions. Use `offset` and `limit` for pagination.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `expand` (query, string) Specifies which related resources to include in the response. For attribute groups, use `definition` to include attribute definitions.  
    Maximum length: 256. Example: `definition`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Successfully returned attribute groups
    
    Media type: `application/json`. Schema: `ObjectAttributeGroupResult`.
    
    _Example: ObjectAttributeGroupResultExample_ List of attribute groups
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 8,
      "data": [
        {
          "id": "custom-attributes",
          "displayName": {
            "default": "Custom Attributes"
          },
          "description": {
            "default": "Custom attributes for the object"
          },
          "position": 1,
          "internal": false,
          "attributeDefinitionsCount": 5
        },
        {
          "id": "marketing",
          "displayName": {
            "default": "Marketing"
          },
          "description": {
            "default": "Marketing related attributes"
          },
          "position": 2,
          "internal": false,
          "attributeDefinitionsCount": 10
        },
        {
          "id": "SiteMap",
          "displayName": {
            "default": "Site Map"
          },
          "description": {
            "default": "Site map attributes"
          },
          "position": 3,
          "internal": false,
          "attributeDefinitionsCount": 3
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    

### GET Get attribute group

`GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id}`

Operation ID: `getAttributeGroup`. Security: AmOAuth2 (sfcc.object-definitions, sfcc.object-definitions.rw).

Retrieves a single attribute group by its identifier.

Use the `select` parameter to specify which properties to include in the response. Use the `expand` parameter with value `definition` to include attribute definitions.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute group.  
    Minimum length: 1. Maximum length: 256. Example: `custom-attributes`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `expand` (query, string) Specifies which related resources to include in the response. For attribute groups, use `definition` to include attribute definitions.  
    Maximum length: 256. Example: `definition`.

#### Responses

*   **200** Successfully returned the attribute group
    
    Media type: `application/json`. Schema: `ObjectAttributeGroup`.
    
    _Example: ObjectAttributeGroupExample_ Single attribute group
    
    ```
    {
      "id": "custom-attributes",
      "displayName": {
        "default": "Custom Attributes",
        "en": "Custom Attributes",
        "de": "Benutzerdefinierte Attribute"
      },
      "description": {
        "default": "Custom attributes for the object"
      },
      "position": 1,
      "internal": false,
      "attributeDefinitionsCount": 5
    }
    ```
    
    _Example: ObjectAttributeGroupWithDefinitionsExample_ Attribute group with expanded attribute definitions
    
    ```
    {
      "id": "custom-attributes",
      "displayName": {
        "default": "Custom Attributes"
      },
      "description": {
        "default": "Custom attributes for the object"
      },
      "position": 1,
      "internal": false,
      "attributeDefinitionsCount": 2,
      "attributeDefinitions": [
        {
          "id": "color",
          "displayName": {
            "default": "Color"
          },
          "valueType": "enum_of_string",
          "visible": true,
          "system": false
        },
        {
          "id": "size",
          "displayName": {
            "default": "Size"
          },
          "valueType": "string",
          "visible": true,
          "system": false
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Attribute Group Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: AttributeGroupNotFoundExample_
    
    ```
    {
      "title": "Attribute Group Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/attribute-group-not-found",
      "detail": "No attribute group with ID 'invalid_group' could be found."
    }
    ```
    

### PUT Create or replace attribute group

`PUT /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id}`

Operation ID: `createOrReplaceAttributeGroup`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Creates a new attribute group or replaces an existing one with the specified identifier.

Returns 201 if a new attribute group was created, or 200 if an existing one was replaced.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute group.  
    Minimum length: 1. Maximum length: 256. Example: `custom-attributes`.

#### Request body (required)

The attribute group data

Media type: `application/json`. Schema: `ObjectAttributeGroup`.

_Example: CreateAttributeGroup_ Create an attribute group

```
{
  "displayName": {
    "default": "New Attribute Group",
    "en": "New Attribute Group",
    "de": "Neue Attributgruppe"
  },
  "description": {
    "default": "A new group for custom attributes"
  },
  "position": 5
}
```

_Example: CreateAttributeGroupWithInternal_ Create an internal attribute group

```
{
  "displayName": {
    "default": "Internal Group"
  },
  "description": {
    "default": "An internal attribute group"
  },
  "position": 10
}
```

#### Responses

*   **200** Successfully replaced the attribute group
    
    Media type: `application/json`. Schema: `ObjectAttributeGroup`.
    
    _Example ObjectAttributeGroupExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id} 200 response._ Single attribute group
    
    _Example: ObjectAttributeGroupExample_ Single attribute group
    
*   **201** Successfully created the attribute group
    
    Media type: `application/json`. Schema: `ObjectAttributeGroup`.
    
    _Example: ObjectAttributeGroupCreatedExample_ Attribute group created successfully
    
    ```
    {
      "id": "new-group",
      "displayName": {
        "default": "New Group",
        "en": "New Group"
      },
      "description": {
        "default": "A new attribute group"
      },
      "position": 6,
      "internal": false,
      "attributeDefinitionsCount": 0
    }
    ```
    
*   **400** Invalid Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: IdConflictExample_
    
    ```
    {
      "title": "Id Conflict",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the request body ('attributegroupId') doesn't match the ID in the URL ('differentId')."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    

### DELETE Delete attribute group

`DELETE /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id}`

Operation ID: `deleteAttributeGroup`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Deletes an attribute group by its identifier.

This operation cannot be undone. All attribute definitions will be unassigned from the group but will not be deleted.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute group.  
    Minimum length: 1. Maximum length: 256. Example: `custom-attributes`.

#### Responses

*   **204** Successfully deleted the attribute group
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Attribute Group Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example AttributeGroupNotFoundExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id} 404 response._
    

### PATCH Update attribute group

`PATCH /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id}`

Operation ID: `updateAttributeGroup`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Partially updates an existing attribute group.

Only the properties provided in the request body will be updated.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute group.  
    Minimum length: 1. Maximum length: 256. Example: `custom-attributes`.

#### Request body (required)

The attribute group data to update

Media type: `application/json`. Schema: `ObjectAttributeGroup`.

_Example: UpdateAttributeGroup_ Update an attribute group

```
{
  "displayName": {
    "default": "Updated Group Name"
  },
  "description": {
    "default": "Updated description"
  },
  "position": 3
}
```

_Example: UpdateAttributeGroupPosition_ Update attribute group position

```
{
  "position": 1
}
```

#### Responses

*   **200** Successfully updated the attribute group
    
    Media type: `application/json`. Schema: `ObjectAttributeGroup`.
    
    _Example ObjectAttributeGroupExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id} 200 response._ Single attribute group
    
    _Example: ObjectAttributeGroupExample_ Single attribute group
    
*   **400** Invalid Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MalformedRequestBodyExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "An error occurred while decoding the request, the body was '{ invalid json }'."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Attribute Group Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example AttributeGroupNotFoundExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id} 404 response._
    

### PUT Assign attribute definition to group

`PUT /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{groupId}/attribute-definitions/{defId}`

Operation ID: `assignAttributeDefinitionToGroup`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Assigns an attribute definition to an attribute group.

The attribute definition must exist for the specified system object type. An attribute definition can be assigned to multiple groups.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `groupId` (path, string, required) The unique identifier of the attribute group.  
    Minimum length: 1. Maximum length: 256. Example: `custom-attributes`.
*   `defId` (path, string, required) The unique identifier of the attribute definition to assign or unassign.  
    Minimum length: 1. Maximum length: 256. Example: `color`.

#### Responses

*   **204** Successfully assigned the attribute definition to the group
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Resource Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    
    _Example AttributeGroupNotFoundExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id} 404 response._
    
    _Example: AttributeDefinitionNotFoundExample_
    
    ```
    {
      "title": "Attribute Definition Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/attribute-definition-not-found",
      "detail": "No attribute definition with ID 'invalid_attribute' for object 'Product' could be found.",
      "attributeDefinitionId": "invalid_attribute",
      "objectType": "Product"
    }
    ```
    

### DELETE Unassign attribute definition from group

`DELETE /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{groupId}/attribute-definitions/{defId}`

Operation ID: `unassignAttributeDefinitionFromGroup`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Removes an attribute definition from an attribute group.

This operation only removes the assignment; the attribute definition itself is not deleted.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `groupId` (path, string, required) The unique identifier of the attribute group.  
    Minimum length: 1. Maximum length: 256. Example: `custom-attributes`.
*   `defId` (path, string, required) The unique identifier of the attribute definition to assign or unassign.  
    Minimum length: 1. Maximum length: 256. Example: `color`.

#### Responses

*   **204** Successfully unassigned the attribute definition from the group
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Resource Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    
    _Example AttributeGroupNotFoundExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id} 404 response._
    
    _Example AttributeDefinitionNotFoundExample: same as PUT /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{groupId}/attribute-definitions/{defId} 404 response._
    

### GET Get attribute definitions

`GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-definitions`

Operation ID: `getAttributeDefinitions`. Security: AmOAuth2 (sfcc.object-definitions, sfcc.object-definitions.rw).

Retrieves a paginated list of attribute definitions for the specified system object type.

Use the `select` parameter to specify which properties to include in the response. Use `offset` and `limit` for pagination.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Successfully returned attribute definitions
    
    Media type: `application/json`. Schema: `ObjectAttributeDefinitionResult`.
    
    _Example: ObjectAttributeDefinitionResultExample_ List of attribute definitions
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 50,
      "data": [
        {
          "id": "color",
          "effectiveId": "c_color",
          "displayName": {
            "default": "Color"
          },
          "description": {
            "default": "The color of the product"
          },
          "key": false,
          "mandatory": false,
          "localizable": false,
          "siteSpecific": false,
          "searchable": true,
          "queryable": true,
          "valueType": "enum_of_string",
          "visible": true,
          "system": false
        },
        {
          "id": "size",
          "effectiveId": "c_size",
          "displayName": {
            "default": "Size"
          },
          "description": {
            "default": "The size of the product"
          },
          "key": false,
          "mandatory": true,
          "localizable": false,
          "siteSpecific": false,
          "searchable": true,
          "queryable": true,
          "valueType": "string",
          "visible": true,
          "system": false
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    

### GET Get attribute definition

`GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-definitions/{id}`

Operation ID: `getAttributeDefinition`. Security: AmOAuth2 (sfcc.object-definitions, sfcc.object-definitions.rw).

Retrieves a single attribute definition by its identifier.

Use the `select` parameter to specify which properties to include in the response. Use the `expand` parameter to include related resources.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute definition.  
    Minimum length: 1. Maximum length: 256. Example: `color`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `expand` (query, string) Specifies which related resources to include in the response. For attribute groups, use `definition` to include attribute definitions.  
    Maximum length: 256. Example: `definition`.

#### Responses

*   **200** Successfully returned the attribute definition
    
    Media type: `application/json`. Schema: `ObjectAttributeDefinition`.
    
    _Example: ObjectAttributeDefinitionExample_ Single attribute definition
    
    ```
    {
      "id": "color",
      "effectiveId": "c_color",
      "displayName": {
        "default": "Color",
        "en": "Color"
      },
      "description": {
        "default": "The color of the product",
        "en": "The color of the product"
      },
      "key": false,
      "mandatory": false,
      "localizable": true,
      "siteSpecific": false,
      "searchable": true,
      "queryable": true,
      "valueType": "enum_of_string",
      "visible": true,
      "system": false,
      "multiValueType": false,
      "setValueType": false,
      "externallyManaged": false,
      "externallyDefined": false,
      "orderRequired": false,
      "requiresEncoding": false,
      "readOnly": false,
      "valueDefinitions": [
        {
          "id": "red",
          "value": "red",
          "displayValue": {
            "default": "Red"
          },
          "position": 1
        },
        {
          "id": "blue",
          "value": "blue",
          "displayValue": {
            "default": "Blue"
          },
          "position": 2
        }
      ],
      "creationDate": "2024-01-15T10:30:00Z",
      "lastModified": "2024-01-15T10:30:00Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Attribute Definition Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example AttributeDefinitionNotFoundExample: same as PUT /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{groupId}/attribute-definitions/{defId} 404 response._
    

### PUT Create or replace attribute definition

`PUT /organizations/{organizationId}/system/object-types/{objectType}/attribute-definitions/{id}`

Operation ID: `createOrReplaceAttributeDefinition`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Creates a new attribute definition or replaces an existing one with the specified identifier.

Returns 201 if a new attribute definition was created, or 200 if an existing one was replaced.

**Important:** The `valueType` property is required when creating a new attribute definition and cannot be changed after creation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute definition.  
    Minimum length: 1. Maximum length: 256. Example: `color`.

#### Request body (required)

The attribute definition data

Media type: `application/json`. Schema: `ObjectAttributeDefinition`.

_Example: CreateAttributeDefinitionString_ Create a string attribute definition

```
{
  "id": "c_customString",
  "displayName": {
    "default": "Custom String Attribute",
    "en": "Custom String Attribute"
  },
  "description": {
    "default": "A custom string attribute"
  },
  "localizable": true,
  "siteSpecific": false,
  "searchable": true,
  "visible": true,
  "valueType": "string"
}
```

_Example: CreateAttributeDefinitionEnum_ Create an enum attribute definition

```
{
  "id": "c_productStatus",
  "displayName": {
    "default": "Product Status",
    "en": "Product Status"
  },
  "description": {
    "default": "The status of the product"
  },
  "localizable": false,
  "siteSpecific": false,
  "searchable": true,
  "visible": true,
  "valueType": "enum_of_string"
}
```

_Example: CreateAttributeDefinitionNumber_ Create a numeric attribute definition

```
{
  "id": "c_weight",
  "displayName": {
    "default": "Weight"
  },
  "description": {
    "default": "The weight of the product"
  },
  "localizable": false,
  "siteSpecific": false,
  "searchable": true,
  "visible": true,
  "valueType": "double",
  "unit": {
    "default": "kg"
  }
}
```

_Example: CreateAttributeDefinitionImage_ Create an image attribute definition

```
{
  "id": "c_customImage",
  "displayName": {
    "default": "Custom Image",
    "en": "Custom Image"
  },
  "description": {
    "default": "A custom image attribute"
  },
  "localizable": true,
  "siteSpecific": false,
  "visible": true,
  "valueType": "image"
}
```

#### Responses

*   **200** Successfully replaced the attribute definition
    
    Media type: `application/json`. Schema: `ObjectAttributeDefinition`.
    
    _Example ObjectAttributeDefinitionExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-definitions/{id} 200 response._ Single attribute definition
    
    _Example: ObjectAttributeDefinitionExample_ Single attribute definition
    
*   **201** Successfully created the attribute definition
    
    Media type: `application/json`. Schema: `ObjectAttributeDefinition`.
    
    _Example: ObjectAttributeDefinitionCreatedExample_ Attribute definition created successfully
    
    ```
    {
      "id": "custom-attribute",
      "effectiveId": "c_custom-attribute",
      "displayName": {
        "default": "Custom Attribute"
      },
      "description": {
        "default": "A custom attribute for the product"
      },
      "key": false,
      "mandatory": false,
      "localizable": true,
      "siteSpecific": false,
      "searchable": true,
      "queryable": true,
      "valueType": "string",
      "visible": true,
      "system": false,
      "multiValueType": false,
      "setValueType": false,
      "externallyManaged": false,
      "externallyDefined": false,
      "orderRequired": false,
      "requiresEncoding": false,
      "readOnly": false,
      "creationDate": "2024-01-15T10:30:00Z",
      "lastModified": "2024-01-15T10:30:00Z"
    }
    ```
    
*   **400** Invalid Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidValueTypeExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "An error occurred while decoding the request. There's an unknown property 'internal' in document 'ObjectAttributeDefinition'."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Object Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ObjectTypeNotFoundExample: same as GET /organizations/{organizationId}/system/object-types 404 response._
    

### DELETE Delete attribute definition

`DELETE /organizations/{organizationId}/system/object-types/{objectType}/attribute-definitions/{id}`

Operation ID: `deleteAttributeDefinition`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Deletes an attribute definition by its identifier.

This operation cannot be undone. The attribute definition will be removed from all attribute groups and all values for this attribute will be deleted.

**Important:** System attributes cannot be deleted.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute definition.  
    Minimum length: 1. Maximum length: 256. Example: `color`.

#### Responses

*   **204** Successfully deleted the attribute definition
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Attribute Definition Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example AttributeDefinitionNotFoundExample: same as PUT /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{groupId}/attribute-definitions/{defId} 404 response._
    

### PATCH Update attribute definition

`PATCH /organizations/{organizationId}/system/object-types/{objectType}/attribute-definitions/{id}`

Operation ID: `updateAttributeDefinition`. Security: AmOAuth2 (sfcc.object-definitions.rw).

Partially updates an existing attribute definition.

Only the properties provided in the request body will be updated.

**Important:** The `valueType` property cannot be changed after creation. System attributes have limited modifiable properties.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `objectType` (path, string, required) The system object type identifier (e.g., Product, Order, Customer)  
    Minimum length: 1. Maximum length: 256. Example: `Product`.
*   `id` (path, string, required) The unique identifier of the attribute definition.  
    Minimum length: 1. Maximum length: 256. Example: `color`.

#### Request body (required)

The attribute definition data to update

Media type: `application/json`. Schema: `ObjectAttributeDefinition`.

_Example: UpdateAttributeDefinition_ Update an attribute definition

```
{
  "id": "c_customString",
  "displayName": {
    "default": "Updated Display Name"
  },
  "description": {
    "default": "Updated description"
  },
  "searchable": false,
  "visible": false
}
```

#### Responses

*   **200** Successfully updated the attribute definition
    
    Media type: `application/json`. Schema: `ObjectAttributeDefinition`.
    
    _Example ObjectAttributeDefinitionExample: same as GET /organizations/{organizationId}/system/object-types/{objectType}/attribute-definitions/{id} 200 response._ Single attribute definition
    
    _Example: ObjectAttributeDefinitionExample_ Single attribute definition
    
*   **400** Invalid Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example MalformedRequestBodyExample: same as PATCH /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{id} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Attribute Definition Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example AttributeDefinitionNotFoundExample: same as PUT /organizations/{organizationId}/system/object-types/{objectType}/attribute-groups/{groupId}/attribute-definitions/{defId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### ObjectTypeDefinitionResult

Document representing a paginated collection of object type definition

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of ObjectTypeDefinition_) List of system object types

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### ObjectTypeDefinitionSearchResult

Document representing a system object type search result

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ObjectTypeDefinition_, required) List of system object types matching the search criteria

### ObjectTypeDefinition

Document representing a system object type definition

*   `objectType` (_string_) The unique identifier of the system object type  
    Maximum length: 256. Example: `Product`.
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Product",
      "de": "Produkt",
      "en": "Product"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `readOnly` (_boolean_, read-only) Flag indicating if this object type is read-only  
    Example: `false`.
*   `queryable` (_boolean_) Flag indicating if this object type can be queried  
    Example: `true`.
*   `searchable` (_boolean_) Flag indicating if this object type is searchable  
    Example: `true`.
*   `contentObject` (_boolean_) Flag indicating if this is a content object  
    Example: `true`.
*   `attributeDefinitionCount` (_integer (int32)_, read-only) The number of attribute definitions for this object type  
    Example: `150`.
*   `attributeGroupCount` (_integer (int32)_, read-only) The number of attribute groups for this object type  
    Example: `8`.

### ObjectAttributeDefinitionSearchResult

Document representing an attribute definition search result

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ObjectAttributeDefinition_, required) List of object attribute definitions

### ObjectAttributeGroupSearchResult

Document representing an attribute group search result

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ObjectAttributeGroup_, required) List of object attribute groups

### ObjectAttributeGroupResult

Document representing a paginated collection of attribute groups

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of ObjectAttributeGroup_) List of object attribute groups

### ObjectAttributeGroup

Document representing an attribute group

*   `id` (_string_) The unique identifier of the attribute group  
    Minimum length: 1. Maximum length: 256. Example: `custom-attributes`.
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Product",
      "de": "Produkt",
      "en": "Product"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `position` (_number (double)_) The position of the attribute group  
    Example: `1`.
*   `internal` (_boolean_, read-only) Flag indicating if this is an internal attribute group  
    Example: `false`.
*   `attributeDefinitionsCount` (_integer (int32)_, read-only) The number of attribute definitions in this group  
    Example: `5`.
*   `attributeDefinitions` (_array of ObjectAttributeDefinition_) The attribute definitions in this group. Only populated when expand=definition is specified.
*   `creationDate` (_string (date-time)_, read-only) The date/time when the attribute definition was created  
    Example: `2024-01-15T10:30:00Z`.
*   `lastModified` (_string (date-time)_, read-only) The date/time when the attribute definition was last modified  
    Example: `2024-01-15T11:00:00Z`.

### ObjectAttributeDefinitionResult

Document representing a paginated collection of attribute definitions

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of ObjectAttributeDefinition_) List of object attribute definitions

### ObjectAttributeDefinition

Document representing an attribute definition

*   `id` (_string_, required) The user supplied ID of the attribute  
    Minimum length: 1. Maximum length: 256. Example: `color`.
*   `effectiveId` (_string_, read-only) The effective ID, which is c\_id if the attribute is custom, and just the id otherwise  
    Maximum length: 256. Example: `c_color`.
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Product",
      "de": "Produkt",
      "en": "Product"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `key` (_boolean_) Flag indicating if this is a key attribute  
    Example: `false`.
*   `mandatory` (_boolean_) Flag indicating if a value is mandatory for the attribute  
    Example: `false`.
*   `localizable` (_boolean_) Flag indicating if this attribute can be localized  
    Example: `false`.
*   `siteSpecific` (_boolean_) Flag indicating if this attribute is site-specific  
    Example: `false`.
*   `searchable` (_boolean_) Flag indicating if this attribute is searchable  
    Example: `true`.
*   `queryable` (_boolean_, read-only) Returns true if the attribute definition is explicitly marked queryable or if the attribute value type belongs to a queryable type. Computed and read-only.  
    Example: `true`.
*   `valueType` (_ValueType_)
*   `visible` (_boolean_) Flag indicating if this attribute is visible  
    Example: `true`.
*   `system` (_boolean_) Flag indicating if this attribute is a system attribute  
    Example: `false`.
*   `unit` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "General unit",
      "de": "Allgemeine Einheit",
      "en": "General unit"
    }
    ```
    
*   `requiresEncoding` (_boolean_, read-only) Flag indicating if this attribute can be encoded using the encoding='off' flag in ISML templates  
    Example: `false`.
*   `multiValueType` (_boolean_) True if the attribute can have multiple values. Applicable to set\_of\_\* and enum\_of\_\* types.  
    Example: `false`.
*   `setValueType` (_boolean_, read-only) Flag indicating if this attribute is of type 'Set of'  
    Example: `false`.
*   `externallyManaged` (_boolean_) Flag indicating if this attribute is externally managed  
    Example: `false`.
*   `externallyDefined` (_boolean_) Flag indicating if this attribute is externally defined  
    Example: `false`.
*   `orderRequired` (_boolean_) Flag indicating if this attribute is required for order of the attribute model's product  
    Example: `false`.
*   `regularExpression` (_string_, read-only) A regular expression that defines the legal values for this attribute  
    Maximum length: 4000. Example: `^[a-zA-Z]+$`.
*   `fieldLength` (_integer (int32)_, read-only) The length of the field for this attribute in the editor  
    Example: `50`.
*   `fieldHeight` (_integer (int32)_, read-only) The height of the field for this attribute in the editor  
    Example: `1`.
*   `minLength` (_integer (int32)_, read-only) The minimum length of the field for this attribute  
    Example: `1`.
*   `readOnly` (_boolean_, read-only) Flag indicating if this attribute is read-only  
    Example: `false`.
*   `minValue` (_number (double)_, read-only) The minimum possible value for this attribute  
    Example: `0`.
*   `maxValue` (_number (double)_, read-only) The maximum possible value for this attribute  
    Example: `100`.
*   `scale` (_integer (int32)_, read-only) The minimum number of fraction digits for a value of this attribute  
    Example: `2`.
*   `defaultValue` (_object_) The default value of this attribute. It can be updated, but not created.
    
    Includes all fields of `ObjectAttributeValueDefinition`.
    
*   `valueDefinitions` (_array of ObjectAttributeValueDefinition_, read-only) A set of values that are possible for this attribute
*   `creationDate` (_string (date-time)_, read-only) The date/time when the attribute definition was created  
    Example: `2024-01-15T10:30:00Z`.
*   `lastModified` (_string (date-time)_, read-only) The date/time when the attribute definition was last modified  
    Example: `2024-01-15T11:00:00Z`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### ValueType

The type of an attribute value

Type: `string`.

Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `image`, `boolean`, `money`, `quantity`, `datetime`, `email`, `password`, `set_of_string`, `set_of_int`, `set_of_double`, `enum_of_string`, `enum_of_int`. Example: `string`.

### ObjectAttributeValueDefinition

An attribute definition value

*   `id` (_string_, read-only) The ID of the attribute value  
    Maximum length: 256. Example: `value-1`.
*   `value` (_string_, read-only) The value of the attribute  
    Maximum length: 4000. Example: `1`.
*   `displayValue` (_object_, read-only) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "One",
      "de": "Eins",
      "en": "One"
    }
    ```
    
*   `description` (_object_, read-only) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `position` (_number (double)_, read-only) The position of the attribute value within the set of attribute values  
    Example: `1`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=4877747c4f47108e42c7bb9ca5d2cf3e55765f8defa7a4cb29df16b51903aeb7 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/batchrequests.md -->

# OCAPI Batch Requests

An OCAPI batch request is a multipart HTTP request that can contain up to 50 subrequests. Each subrequest (part) must operate on a single resource; subrequests that specify multiple ids (for example, `'/products/(p1,p2...)'`) are forbidden.

Batch requests reduce network overhead by reducing the overall amount of information transmitted and by reducing the number of calls you have to make. For example, to build an application screen, you can construct a single large multipart batch request instead of constructing numerous smaller individual OCAPI requests.

The HTTP method used for the batch request as a whole must be POST or OPTIONS. Each subrequest can specify a different HTTP method if necessary.

## Batch Request Format

Each batch request has a main header section. In this section, you must include a `Content-Type` header that specifies a type (_multipart/mixed_) and a boundary separator that is used to delimit each subrequest. For example:

```txt
Content-Type: multipart/mixed; boundary=23dh3f9f4
```

Every header included in the main header section of the batch request is implicitly inherited by each subrequest. The query parameters of the main batch request are also implicitly inherited by each subrequest.

Each subrequest, however, is conceptually a complete OCAPI request with its own resource path, header section, and request body. If needed, a subrequest can override its inherited headers and its inherited query parameters.

To specify the behavior of subrequests and to define the mapping between requests and responses, you must specify the following headers where appropriate:

| Header name                    | Location                | Description                                                                                                                                                                                          |
| ------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-dw-http-method`             | request, subrequest     | Specifies the HTTP method used to access the resource.                                                                                                                                               |
| `x-dw-resource-path`           | request, subrequest     | Specifies the base resource path. The value of this header is combined with value of the `x-dw-resource-path-extension` header to provide a complete resource path.                                  |
| `x-dw-resource-path-extension` | request, subrequest     | Specifies an extension for the value of the base path, as specified by the `x-dw-resource-path` header. This header is optional if the base resource path already represents a valid OCAPI resource. |
| `x-dw-content-id`              | subrequest, subresponse | Specifies an ID of the subrequest. This header value is used to map a subrequest to a subresponse.                                                                                                   |
| `x-dw-status-code`             | subresponse             | Specifies the status code of a single subresponse.                                                                                                                                                   |

## CORS Support

Batch requests are supporting [CORS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/cors.md). Allowed expose headers and origins are mentioned in OCAPI settings for each client ID. To access them, it’s mandatory to send a batch request for a specific client in a context, either of a specific site or global. There are several possibilities to pass a [client identification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/clientapplicationidentification.md):

1.  Client ID as query parameter
2.  Client ID as _x-dw-client-id_ header
3.  OAuth access token via _Authorization_ header
4.  JWT via _Authorization_ header

## Formatting of Multipart Sub Requests

Subrequests in a batch request body adhering to the standard defined in [Multipart Media Type](https://tools.ietf.org/html/rfc2046#section-5.1). This approach means that the header section in a Multipart subrequest has to follow directly after the Multipart boundary. The header section and the Multipart body section have to be separated by two subsequent newline characters.

Example 1

Correct formatted subrequest.

```txt
    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/
    --23dh3f9f4\n
    x-dw-content-id: realCount\n
    \n
    {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
    --23dh3f9f4--
    ...
```

Example 2

Wrong formatted subrequest. Only one newline after header section.

```txt

    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/
    -23dh3f9f4\n
    x-dw-content-id: realCount\n
    {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
    --23dh3f9f4--
    ...
```

Example 3

Wrong formatted subrequest. Two newlines after boundary lead to an empty header section.

```txt
    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/
    --23dh3f9f4\n
    \n
    x-dw-content-id: realCount\n
    {"query":{"filtered_query":{"query":{"bool_query":{"must":[{"term_query":{"fields":["product_items.product_id"],"operator":"one_of","values":["S20273_100"]}},{"term_query":{"fields":["status"],"operator":"one_of","values":["new"]}}]}},"filter":{"range_filter":{"field":"creation_date","from":"2020-04-01"}}}},"select":"(total)"}\n
    --23dh3f9f4--
    ...

```

## Example Batch Requests

Example 1

This example shows how you can access multiple resources of the same type:

```txt
    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    Authorization: Bearer f9f34f43rfdf0isadjf93059j4
    x-dw-http-method: DELETE
    x-dw-resource-path: /s/-/dw/data/v24_5/libraries/SiteGenesis/content/

    --23dh3f9f4
    x-dw-content-id: req1
    x-dw-resource-path-extension: content_asset_1
    --23dh3f9f4
    ...
    x-dw-content-id: req50
    x-dw-resource-path-extension: content_asset_50
    --23dh3f9f4--

    RESPONSE:
    HTTP/1.1 200 OK
    Content-Type: multipart/mixed; boundary=23dh3f9f4

    --23dh3f9f4
    x-dw-content-id: req1
    x-dw-status-code: 204
    --23dh3f9f4
    ...
    x-dw-content-id: req50
    x-dw-status-code: 204
    --23dh3f9f4--
```

Example 2

This example shows how you can access resources of different types:

```txt
    REQUEST:
    POST /batch HTTP 1.1
    Host: example.com
    Content-Type: multipart/mixed; boundary=23dh3f9f4
    x-dw-client-id: [your_own_client_id]
    x-dw-http-method: GET
    x-dw-resource-path: /s/SiteGenesis/dw/shop/v24_5/

    --23dh3f9f4
    x-dw-content-id: req_addr_create
    x-dw-http-method: PUT
    x-dw-resource-path-extension: account/this/addresses

    {
      "address1":"10 Somewhere St.",
      "city":"Boston",
      "last_name":"Lebowski",
      "country_code":"US",
      "postal_code":"98765",
      "state_code":"MA"
    }
    --23dh3f9f4
    x-dw-content-id: req_prod_get
    x-dw-resource-path-extension: products/creative-zen-v
    --23dh3f9f4--

    RESPONSE:
    HTTP/1.1 200 OK
    Content-Type: multipart/mixed; boundary=23dh3f9f4

    --23dh3f9f4
    x-dw-content-id: req_addr_create
    x-dw-status-code: 200

    {
      "_v" : "24.5",
      "_type":"customer_address",
      "address1":"10 Somewhere St.",
      "address_id":"84619.10625703718",
      "city":"Boston",
      "country_code":"US",
      "last_name":"Lebowski",
      "postal_code":"98765",
      "state_code":"MA"
    }
    --23dh3f9f4
    x-dw-content-id: req_prod_get
    x-dw-status-code: 404

    {
      "_v" : "24.5",
      "fault":{
        "type":"ProductNotFoundException",
        "message":"No product with id 'creative-zen-v' for site 'SiteGenesis' found."
      }
    }
    --23dh3f9f4--

```

## Request Site Context

The site context for each request can be defined in `x-dw-resource-path` or `x-dw-resource-path-extension`. If no site context is given in these headers, the one from the main request is taken. This implies, that the site context from the main request can be overwritten by the resource path headers.

## Limitations

The size of the batch request body is limited to 5 MB. The maximum number of subrequests is 50.

## Exceptions

| Exeption name                         | Status code | Description                                                                                                     |
| ------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| `IllegalContentTypeException`         | 400         | Thrown if the request content type isn’t multipart/mixed or specifies no boundary.                              |
| `IllegalQueryStringException`         | 400         | Thrown if the query string for the request or a subrequest is invalid.                                          |
| `InvalidAuthorizationHeaderException` | 401         | Thrown if the authorizarion header has not the format _Authorization: Bearer ..._                               |
| `InvalidHttpMethodException`          | 400         | Thrown if the HTTP method in the request header or subrequest header is invalid.                                |
| `InvalidRequestBodyException`         | 400         | Thrown if the request body is invalid.                                                                          |
| `InvalidTokenException`               | 401         | The token sent via _Authorization: Bearer_ header is invalid or expired.                                        |
| `MethodNotAllowedException`           | 405         | Thrown if the batch request was sent with an HTTP method other than POST or OPTIONS.                            |
| `MissingClientIdException`            | 400         | Thrown if no client identification was sent with the main request (either as client ID or authorization token). |
| `MissingHttpMethodException`          | 400         | Thrown if at least one subrequest has no HTTP method.                                                           |
| `MissingResourcePathException`        | 400         | Thrown if at least one subrequest has no resource path.                                                         |
| `QuotaExceededException`              | 400         | Thrown if the batch request contains more than 50 subrequests.                                                  |
| `RequestEntityTooLargeException`      | 400         | Thrown if the batch request body is larger than 5 MB.                                                           |
| `ResourcePathNotAllowedException`     | 400         | Thrown if at least one subrequest is a multiple-ID resource call.                                               |
| `UnauthorizedOriginException`         | 401         | Thrown if the given origin isn’t mentioned in the OCAPI settings for the accessing client.                      |
| `UnknownClientIdException`            | 401         | Thrown if the given client identification isn’t known to the account manager.                                   |
| `UnknownSiteIdException`              | 400         | Thrown if the request was sent in the context of an unknown site name.                                          |

<!-- document id=ad727787cfcc46437234d7f9e7d288df0a8745274482516f3a699b2ff5810444 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/bestpractices.md -->

# OCAPI Best Practices 24.5

These tips help you develop scalable, high-performance OCAPI applications.

## Choosing OCAPI Instead of Controllers or Pipelines

OCAPI requests and storefront requests (Controllers or Pipelines) have different resource costs and platform overhead. The information here can help you make the right choice for your application.

- What are the key differences?

  - :
    - OCAPI requests have their own application tier cache. It follows similar clearing behavior to that of the web tier cache, but the web tier doesn’t cache OCAPI requests.
    - Because the web tier doesn't cache OCAPI requests, they always incur the same application-tier overhead as uncached storefront requests, regardless of cache status. Therefore, OCAPI requests have a higher resource cost than storefront requests that are cached by the web tier.
    - An OCAPI request that retrieves multiple response documents applies the minimum cache TTL among those documents to all of them. A storefront request, on the other hand, respects the individual cache TTLs of each element of remote-include content.

- What is the effect on thread behavior?

  - : Thread behavior is the same for OCAPI and storefront requests: each request generates a new thread to handle the response. The appropriate request payload size can vary, based on the situation.

    - Remember that a long-running request keeps a thread occupied.
    - To determine the appropriate balance between payload size and request time, monitor your application's performance and tune it as needed. This balance is specific to each application. For example, one case calls for a single request that returns 50 responses, while ten requests returning five responses each offer better performance for another case.
    - Use [batch requests](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/batchrequests.md) appropriately.

- How does poor OCAPI performance affect the customer experience?

  - : OCAPI requests, storefront requests, and scheduled jobs all share the platform resource pool. Therefore, poor performance in one area not only adds its own wait time to the customer experience, but also affects performance in other areas.

## OCAPI Cache Management

Here we expand on the many considerations related to [caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/caching.md) OCAPI requests.

- What types of OCAPI requests can be cached?

  - :

    - Data API: No
    - Meta API: Yes
    - Shop API: Yes (most requests)

**note:** Each Data API request incurs real-time application-tier overhead. Try to minimize the number of Data API calls made by your application.

- How are Meta API requests cached?

  - : Meta API resources are always cached for one day. You can't configure their TTL. To clear the Meta API instance cache, [invalidate the entire Business Manager page cache](https://developer.salesforce.com/docs/commerce/guides/site-development/b2c-content-cache.md). (Invalidating only a cache partition doesn’t clear the Meta API cache.)

**note:** Clearing the page cache can create a heavy load on the application servers. Only clear the page cache manually when necessary, and avoid clearing it during times of high traffic.

- How are Shop API requests cached?

  - : You configure caching of individual Shop resources in the [OCAPI Settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md) using two properties. Minimize cache misses by configuring appropriate TTLs and eliminate cache stores (duplicate cache content) with a good request URL strategy.

    - `cache_time` (Integer): Lifetime of the cached response document, in seconds. The default value is 60, and the valid range is from 0 through 86,400 (24 hours).
    - `personalized_caching_enabled` (Boolean): Specifies whether response documents are cached per customer context (JWT). The default value is true. Disabling personalized caching can improve performance, but can only be done if the response document is customer-agnostic and isn’t needed for any customer-specific processing.

- How are cache keys generated for Shop API responses?

  - : OCAPI cache keys are similar to storefront page cache keys. They’re generated from the following request elements.

    - hostname
    - siteId
    - clientId
    - expansion parameters
    - custom request URL parameters

- How does a request URL affect cache performance?

  - : The structure of a request URL affects the generated cache key. Matching requests that include the same parameters, but combine them in a different order, generate multiple cache entries. For example, these three requests result in three different cache entries for the same response data:

    - `dw/shop/v18_8/products/123?client_id=[your_own_client_id]&expand=availability,variations`
    - `dw/shop/v18_8/products/123?expand=availability,variations&client_id=[your_own_client_id]`
    - `dw/shop/v18_8/products/123?expand=variations,availability&client_id=[your_own_client_id]`

    Duplicate entries can significantly degrade cache performance. To prevent them, always build request URLs with the query parameters and parameter values in alphabetical order.

- What types of OCAPI data exist in the cache?

  - : OCAPI data is cached in two ways: individual document entries, and composite entries that combine multiple documents (an object document plus documents representing expansions included in the request).

    - Individual documents are stored in and retrieved from cache individually. For example, a request that returns multiple Product documents, with no expansions, checks the cache for individual matching Product documents.
    - Composite data that includes expansion documents is only retrieved from the cache if an entry exists that matches the requested combination of documents. (Remember that the cache key includes the requested expansions.) If no matching entry exists, then the requested documents are all retrieved from the database and stored together as a single combined cache entry. This cache entry is in turn only available to requests for the same combination of documents. For example, consider a request that returns a Product document, plus expansions for Inventory and Promotion documents. It only retrieves data from cache if it finds a combined entry that includes matching Product, Inventory, and Promotion documents. Because such an entry is only available to a matching request, a request for only the Product document with no expansions ignores it.

**note:** When a composite entry is stored in cache, its TTL is equal to the shortest configured TTL of the included document types. This behavior differs from the behavior of storefront pipeline and page caching, where different elements of a page can be cached separately. For example, consider a Product document with a TTL of 86,400 seconds, and an Inventory document with a TTL of 300 seconds. A request for a Product document with the availability expansion (which returns an Inventory document) generates a cache entry with a TTL of 300 seconds. For this reason, use requests that group documents with similar cache times when possible. Also, when planning, be aware of requests that retrieve data from the database more frequently than expected for that data.

- Are cache entries based on requests or responses?

  - : Cache entries are based on responses, not requests. Therefore, every OCAPI request incurs the application-tier overhead to parse it and retrieve documents from the cache or database.

- How does replication affect OCAPI caching?

  - : Replication clears the entire OCAPI cache along with the site cache.

- How can I clear the OCAPI cache?

  - : To clear the OCAPI cache, invalidate the site page cache. Doing so invalidates both caches, which can’t be cleared separately. See [Invalidate a Page Cache Partition](https://developer.salesforce.com/docs/commerce/guides/site-development/b2c-content-cache.md).

**note:** Clearing the page cache can create a heavy load on the application servers. Only clear the page cache manually when necessary, and avoid clearing it during times of high traffic.

- Are there tools for monitoring OCAPI cache performance?

  - : The platform doesn’t provide direct visibility to the OCAPI cache. The Reports and Dashboards in Business Manager describe cache behavior only for storefront pipeline requests.

## Improving OCAPI Request Performance Using Cache-Control Headers

Some Shop API GET and HEAD request responses include [`Cache-Control` headers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/http-headers.md) that reflect the configured cache times for the retrieved documents. You can use this header data to effectively cache the documents outside of the B2C Commerce platform by retaining data and timing your OCAPI requests accordingly. The `max-age` argument in the header specifies how long to use the returned document before retrieving it again.

- How can I use the `max-age` argument in the `Cache-Control` header to cache OCAPI response data?

  - : The `max-age` argument represents the remaining TTL of the data in the OCAPI cache. For example, consider a resource with a configured `cache-time` of 900 seconds.

    - A GET request is made for the resource and retrieves a document that isn’t yet in cache. The response header includes a `max-age` value of 900. The document is stored in cache.
    - Another GET request is made to retrieve the same document 120 seconds later. This response header includes a `max-age` value of 780. This value is calculated by subtracting the document's current time in cache (120) from the configured resource cache time (900). Your application can use the data without retrieving the document again until its effective TTL of 780 seconds has elapsed.

- Which Shop API resources include `Cache-Control` headers?

  - : The following resources include `Cache-Control` headers in their GET and HEAD request responses.

    - Categories
    - Content
    - ContentSearch
    - CustomObjects
    - Folders
    - Products
    - ProductSearch
    - Promotions
    - SearchSuggestion
    - Site
    - Stores

    Because they’re tied to sensitive data (such as customer or order processing data), the following resources don’t include `Cache-Control` headers.

    - Ai
    - Baskets
    - Customers
    - GiftCertificate
    - OrderSearch
    - Orders
    - PriceAdjustmentLimits
    - ProductLists
    - Sessions

- Can I use an external Content Delivery Network (CDN) to improve OCAPI performance?

  - : If you use an external CDN to manage content, you can configure it to broker OCAPI requests and manage external caching based on the `Cache-Control` headers.

    - You can treat some OCAPI responses as static content, and provide default minimum cache times.
    - Depending on the features of the CDN, you can create multiple cache partitions, and associate specific OCAPI requests with specific partitions. Then you can customize cache behavior for each partition to apply to its set of requests.
    - You can manage an external OCAPI cache separately from the storefront page cache, effectively decoupling them.

<!--TODO: Fix link post migration -->
<!-- - Can I use an external Content Delivery Network (CDN) to improve OCAPI performance?

  - : If you use an [external CDN](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/admin/b2c-configuring-an-external-cdn.md) to manage content, you can configure it to broker OCAPI requests and manage external caching based on the `Cache-Control` headers.

    - You can treat some OCAPI responses as static content, and provide default minimum cache times.
    - Depending on the features of the CDN, you can create multiple cache partitions, and associate specific OCAPI requests with specific partitions. Then you can customize cache behavior for each partition to apply to its set of requests.
    - You can manage an external OCAPI cache separately from the storefront page cache, effectively decoupling them. -->

- Can I use the embedded B2C Commerce CDN to improve OCAPI performance?

  - : No. The embedded CDN doesn't include a reverse proxy that can manage OCAPI requests.

## Extending and Customizing OCAPI

Here are some general tips on maximizing OCAPI performance.

- What are some good practices when using custom hooks?

  - :
    - Hooks introduce dependencies and extra request overhead. Use them only when the benefits outweigh these costs.
    - When modifying an OCAPI response, use the web object whenever possible. Use the Script API only when necessary, and keep the hook business logic simple.
    - Avoid requesting persistent objects within a hook (such as `ProductMgr.getProduct()` or `product.getVariations()`).

- How do cache time configurations affect custom hooks?

  - : Custom hook logic attached to an OCAPI resource only executes when the data is retrieved from the database. Retrieving documents from cache doesn’t trigger a custom hook.

- What should I know about creating custom API endpoints that leverage custom controllers?

  - : Controllers are stateful. Every time you access a controller endpoint, you spawn a new request object and, potentially, a new session. To continue using a session, client applications must accept the cookie embedded in the initial response and include it in subsequent requests. Failing to do so creates and abandons a new session with every request. The resulting flood of orphaned sessions can severely impact performance.

- Is there a preferred way to make OCAPI requests from different clients, such as browsers or mobile applications?

  - : Retrieve the [JSON Web Token (JWT)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jwt.md) and use it to make requests. Using it conserves platform resources and provides other benefits.

    - You can reuse a session instead of creating one for each request.
    - It enables ORM caching for OCAPI requests.
    - It enables personalized caching.

<!-- document id=724b22cc9b3e7a203cb6809986a7440b4f0864f7bbfa2bec7e605ccf74783815 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/caching.md -->

# OCAPI Caching

As a REST API based on HTTP, the Open Commerce API enables developers to build client application caches or to leverage Proxy caches. The API delivers standard HTTP cache header information.

In Business Manager, you can configure maximum cache times (or max ages) for some Open Commerce API resources. At the moment, you can only configure the cache settings for the Shop API.

**note:** Site Page Caching _must_ be enabled in Business Manager for caching functionality.

The max age determines how long (in seconds) a response document remains in the cache. At runtime, the configured max age is used to calculate a value that is added to the cache control header of the HTTP response. For example, suppose that you configure a max age of 900 seconds for the categories resource. After an initial GET request, the value included in the HTTP header would be 900. If a second GET request for the same document arrived 120 seconds later, the HTTP header value would be 780.

**note:** Response cache headers are only delivered for GET and HEAD requests in the Shop API for the `categories`, `content`, `content_search`, `custom_objects`, `folders`, `products`, `product_search`, `promotions`, `search_suggestions`, `site`, and `stores` resources.

## Cache Time Configuration

Configure cache times per resource in the [Open Commerce API settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md). The integer property `cache_time` defines the cache time in seconds. If you don't specify a cache time, the default is 60 seconds. The minimum configurable cache time is 0 seconds, and the maximum is 86,400 seconds (24 hours).

Following is a sample cache time configuration:

```json
{
  "_v" : "24.5",
  "clients":
  [
    {
      "client_id":"[your_own_client_id]",
      "resources":
      [
        {
          "resource_id":"/categories/*",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":900
        },
        {
          "resource_id":"/products/*",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":900
        },
        {
          "resource_id":"/products/*/availability",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":60
        },
        {
          "resource_id":"/products/*/prices",
          "methods":["get"],
          "read_attributes":"(**)",
          "write_attributes":"(**)",
          "cache_time":300
        },
        ...
      ]
    }
  ]
}

```

## HTTP Response Cache Headers

The API returns the cache time as the `*Cache-Control: max-age*` header, as in the following examples:

Example 1: Request product availability information:

```txt
REQUEST:
GET /dw/shop/v24_5/products/123/availability HTTP/1.1

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=48,must-revalidate

{
  "id":"123",
  "name":"Shirt",
  "orderable":true
}
```

Example 2: Request product price information:

```txt
REQUEST:
GET /dw/shop/v24_5/products/123/prices HTTP/1.1

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=240,must-revalidate

{
  "id":"123",
  "name":"Shirt",
  "price":100.00
}
```

Example 3: Request product availability and price information using the _expand_ parameter:

```txt
REQUEST:
GET /dw/shop/v24_5/products/123?expand=availability,prices HTTP/1.1

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate

{
  "id":"123",
  "name":"Shirt",
  "price":100.00,
  "orderable":true
}
```

For a single request using the _expand_ parameter, the Open Commerce API populates the _Cache-Control_ header with the lowest caching time of the requested resources.

## Query Parameters

Query parameters are part of the key of web caches like proxy or browser caches. OCAPI self-generated URLs always have the query parameters sorted alphabetically. This deterministic sorting order ensures a better cache hit rate.

**note:** To ensure better cache hit rates, improving performance, always build OCAPI URLs in client applications with the query parameters in alphabetic sorting order.

## Caching in the Meta API

The Meta API also has caching enabled. The default cache time for the resources is 1 day, and can’t be configured. To clear the instance cache for Meta API documents, you have to invalidate the Business Manager page cache.

<!-- document id=8dd52018f7c2c57bb46b2ce4afd5cc6b5fd7bc2f88307e8350571e5144ed97d1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/clientapplicationidentification.md -->

# OCAPI Client Application Identification

The Open Commerce API requires that all client applications identify themselves using a client ID.

You can obtain a client ID in Account Manager as explained in Adding a client ID for the Open Commerce API. After you obtain an ID, verify that it’s enabled.

<!--TODO: Fix link post migration -->
<!-- You can obtain a client ID in Account Manager as explained in [Adding a client ID for the Open Commerce API.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/account-manager/b2c-account-manager-add-api-client-id.md) After you obtain an ID, verify that it is enabled.
 -->

**note:** You can see a list of all client IDs in your organization by selecting **API Client** in the left navigation menu in Account Manager.

Include the client ID in every API request. It can be passed in several ways:

1.  For requests requiring an **Authorization:Bearer token**, the client ID is determined from the provided token:

    ```txt
    GET https://.../shop/v24_5/baskets
    Authorization:Bearer *token*
    ```

    1.  JWT: the _client ID_ is embedded within the token payload as the 'issuer' claim
    2.  OAuth: the _client ID_ is resolved from the Account Manager using the token

2.  You can pass a client ID in the `client_id` request parameter:

    ```txt
    GET https://example.com/dw/shop/v24_5/products/123456?client_id=[your_own_client_id]
    ```

3.  You can pass a client ID in the `x-dw-client-id` HTTP header:

    ```txt
    GET https://example.com/dw/shop/v24_5/products/123456
    x-dw-client-id:[your_own_client_id]
    ```

If more than one mechanism is used to provide a client ID, it’s resolved using the following order of precedence.

1.  Bearer token
2.  Request parameter
3.  HTTP Header

If you don’t provide a client ID, the server returns an HTTP status 400 (Bad Request).

**note:** Your client ID must be enabled in Account Manager. Because client IDs are cached for a time before being revalidated, when you enable or disable a client ID, its status doesn’t change immediately.

<!-- document id=527e3aeb96716958cbb3465775930cb4ec9ae82cd49b671c5fe3f4b7778fd86b url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/customproperties.md -->

# OCAPI Custom Properties

The Open Commerce API allows you to set custom properties of business objects in input documents and to read custom properties in output documents. Whether a business object supports custom properties can be found in the [tables below](#document-types-supporting-custom-properties).
Custom properties are always marked with the prefix `c_` and have therefore their own namespace.

## Custom Properties Example

The example below shows a document response including some custom properties in OCAPI:

```txt
REQUEST: GET /dw/shop/v24_5/products/creative-zen-v HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE: HTTP/1.1 200 OK
Content-Type:  application/json; charset=UTF-8
Cache-Control:  max-age=900,must-revalidate
{
   ...
   "c_mediaFormat" : [ "0010", "0020", "0030", "0040" ],
   "c_memorySize" : "1GB",
   "c_tabDescription" : "The ZEN V player was designed for people like you those who walk a step or two ahead of the pack."
}
```

## Custom Properties Value Types

The following value types are supported in OCAPI for input and output of custom properties.

- Text
- String
- Enum of Strings
- Set of Strings
- Integer
- Enum of Integers
- Set of Integers
- Double
- Set of Doubles
- Boolean
- EMail
- Password
- Date
- Date+Time

**note:** The value types **HTML** and **Image** are only supported as output, but not as input value type for custom properties in OCAPI.

## Document Types Supporting Custom Properties

The tables below lists the document types that support custom properties in OCAPI SHOP and DATA APIs. OCAPI `modify...` hooks that used the referenced document types can
add custom properties using the `c_` prefix. See [Customization With Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html), [Hooks for SHOP API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hooks-shop.html), and [Hooks for DATA API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hooks-data.html) for more information.

### SHOP API

The following shop API documents support custom properties.

| Document Type                    | Reference                                                                                                                                                                          |
| -------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ApproachingDiscount              | [approaching_discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aapproaching_discount)                                 |
| Basket                           | [basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Abasket)                                                             |
| BasketPaymentInstrumentRequest   | [basket_payment_instrument_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Abasket_payment_instrument_request)       |
| BonusDiscountLineItem            | [bonus_discount_line_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Abonus_discount_line_item)                         |
| BundledProductItem               | [bundled_product_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Abundled_product)                                    |
| Category                         | [category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-categories?meta=type%3Acategory)                                                      |
| Content                          | [content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-content?meta=type%3Acontent)                                                           |
| ContentFolder                    | [content_folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-folders?meta=type%3Acontent_folder)                                             |
| CouponItem                       | [coupon_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Acoupon_item)                                                   |
| CustomObject                     | [custom_object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-custom-objects?meta=type%3Acustom_object)                                        |
| Customer                         | [customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer)                                                       |
| CustomerAddress                  | [customer_address](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer_address)                                       |
| CustomerInfo                     | [customer_info](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer_info)                                             |
| CustomerPaymentInstrument        | [customer_payment_instrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer_payment_instrument)                 |
| CustomerPaymentInstrumentRequest | [customer_payment_instrument_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer_payment_instrument_request) |
| CustomerProductList              | [customer_product_list](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer_product_list)                             |
| CustomerProductListItem          | [customer_product_list_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer_product_list_item)                   |
| CustomerProductListItemPurchase  | [customer_product_list_item_purchase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer_product_list_item_purchase) |
| GiftCertificate                  | [gift_certificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-gift-certificate?meta=type%3Agift_certificate)                                |
| GiftCertificateItem              | [gift_certificate_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Agift_certificate_item)                               |
| OptionItem                       | [option_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aoption_item)                                                   |
| Order                            | [order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-orders?meta=type%3Aorder)                                                                |
| OrderAddress                     | [order_address](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-orders?meta=type%3Aorder_address)                                                |
| OrderPaymentInstrument           | [order_payment_instrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-orders?meta=type%3Aorder_payment_instrument)                          |
| OrderPaymentInstrumentRequest    | [order_payment_instrument_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-orders?meta=type%3Aorder_payment_instrument_request)          |
| PathRecord                       | [path_record](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-categories?meta=type%3Apath_record)                                                |
| PaymentCardSpec                  | [payment_card_spec](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Apayment_card_spec)                                       |
| PaymentMethod                    | [payment_method](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Apayment_method)                                             |
| PriceAdjustment                  | [price_adjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aprice_adjustment)                                         |
| PriceAdjustmentRequest           | [price_adjustment_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aprice_adjustment_request)                         |
| Product                          | [product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-products?meta=type%3Aproduct)                                                          |
| ProductItem                      | [product_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aproduct_item)                                                 |
| ProductListItem                  | [product_list_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aproduct_list_item_reference)                                       |
| ProductListItemReference         | [product_list_item_reference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aproduct_list_item_reference)             |
| ProductListLink                  | [product_list_link](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Aproduct_list_link)                                 |
| ProductSearchHit                 | [product_search_hit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-product-search?meta=type%3Aproduct_search_hit)                              |
| Promotion                        | [promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-promotions?meta=type%3Apromotion)                                                    |
| PublicProductList                | [public_product_list](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-product-lists?meta=type%3Apublic_product_list)                             |
| PublicProductListItem            | [public_product_list_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-product-lists?meta=type%3Apublic_product_list_item)                   |
| PublicProductListLink            | [public_product_list_link](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-product-lists?meta=type%3Apublic_product_list_link)                   |
| Recommendation                   | [recommendation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-products?meta=type%3Arecommendation)                                            |
| Shipment                         | [shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Ashipment)                                                         |
| ShippingItem                     | [shipping_item](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Ashipping_item)                                               |
| ShippingMethod                   | [shipping_method](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Ashipping_method)                                           |
| ShippingPromotion                | [shipping_promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-baskets?meta=type%3Ashipping_promotion)                                     |
| Store                            | [store](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-stores?meta=type%3Astore)                                                                |
| SuggestedCategory                | [suggested_category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-search-suggestion?meta=type%3Asuggested_category)                           |
| SuggestedContent                 | [suggested_content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-search-suggestion?meta=type%3Asuggested_content)                             |
| SuggestedPhrase                  | [suggested_phrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-search-suggestion?meta=type%3Asuggested_phrase)                               |
| SuggestedProduct                 | [suggested_product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-search-suggestion?meta=type%3Asuggested_product)                             |
| Suggestion                       | [suggestion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-search-suggestion?meta=type%3Asuggestion)                                           |

### DATA API

The following DATA API documents support custom properties.

| Document Type                   | Reference                                                                                                                                                                     |
| ------------------------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Campaign                        | [campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-campaigns?meta=type%3Acampaign)                                                  |
| Catalog                         | [catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-catalogs?meta=type%3Acatalog)                                                     |
| Category                        | [category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-catalogs?meta=type%3Acategory)                                                   |
| ContentAsset                    | [content_asset](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-libraries?meta=type%3Acontent_asset)                                        |
| ContentFolder                   | [content_folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-libraries?meta=type%3Acontent_folder)                                      |
| Coupon                          | [coupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-coupons?meta=type%3Acoupon)                                                        |
| CustomObject                    | [custom_object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-custom-objects?meta=type%3Acustom_object)                                   |
| Customer                        | [customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-customer-lists?meta=type%3Acustomer)                                             |
| CustomerAddress                 | [customer_address](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-customer-lists?meta=type%3Acustomer_address)                             |
| CustomerGroup                   | [customer_group](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-customer-group-search?meta=type%3Acustomer_group)                          |
| GiftCertificate                 | [gift_certificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-gift-certificates?meta=type%3Agift_certificate)                          |
| OrderUpdateRequest              | [order_update_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-orders?meta=type%3Aorder_update_request)                             |
| OrganizationPreferences         | [organization_preferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-global-preferences?meta=type%3Aorganization_preferences)         |
| PathRecord                      | [path_record](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-catalogs?meta=type%3Apath_record)                                             |
| PaymentInstrumentUpdateRequest  | [payment_instrument_update_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-orders?meta=type%3Apayment_instrument_update_request)   |
| PaymentTransactionUpdateRequest | [payment_transaction_update_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-orders?meta=type%3Apayment_transaction_update_request) |
| Product                         | [product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-products?meta=type%3Aproduct)                                                     |
| ProductInventoryRecord          | [product_inventory_record](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-inventory-lists?meta=type%3Aproduct_inventory_record)            |
| Promotion                       | [promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-promotions?meta=type%3Apromotion)                                               |
| PromotionCampaignAssignment     | [promotion_campaign_assignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-promotions?meta=type%3Apromotion_campaign_assignment)       |
| RedemptionLimitPerPeriod        | [redemption_limit_per_period](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-coupons?meta=type%3Aredemption_limit_per_period)              |
| RedemptionLimits                | [redemption_limits](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-coupons?meta=type%3Aredemption_limits)                                  |
| ShippingAddressUpdateRequest    | [shipping_address_update_request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-orders?meta=type%3Ashipping_address_update_request)       |
| SitePreferences                 | [site_preferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-site-preferences?meta=type%3Asite_preferences)                           |
| SlotConfiguration               | [slot_configuration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-slot-configurations?meta=type%3Aslot_configuration)                    |
| SortingRule                     | [sorting_rule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-sorting-rule-search?meta=type%3Asorting_rule)                                |
| SortingRuleStep                 | [sorting_rule_step](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-sorting-rule-search?meta=type%3Asorting_rule_step)                      |
| Store                           | [store](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-stores?meta=type%3Astore)                                                           |

<!-- document id=c40ae14ea1a3676cca81500dff1f2509eb1d503c93f33d63a355d5c329f73397 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/customization.md -->

# OCAPI Customization

You can customize Shop API resources that perform a modification on the server side, such as the `Customer` and `Basket` resources. These resources provide extension points, or hooks, that enable you to augment server-side logic with your own script code.

Each customizable resource provides `before`, `after`, and `modifyResponse` hooks. Use the `before` and `after` hooks to execute custom code before or after the server performs its processing. Use the `modifyResponse` hook to apply changes to the response document. In addition, convenience hooks allow you to perform actions like basket calculations or checkout steps. These convenience hooks let you place your basket-calculation code in a single place, instead of including duplicate code in multiple `after` hooks.

For information on hooks and supported resources, see [OCAPI Hooks for Data API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hooks-data.md) and [OCAPI Hooks for Shop API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hooks-shop.md).

## Customization Processing

The processing flow is as follows:

![API Customization Details](https://developer.salesforce.com/media/b2c-commerce/api-hooks.png)

| Processing Step                                | Comment                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Server receives a request to modify a resource | The server checks for registered `before` hooks.                                                                                                                                                                                                                                                                                                                                  |
| Server calls registered `before` hook          | The server passes the request document and a Script API object representing the resource that it will modify. Your custom code can manipulate both, but typically performs input validation on the request document.                                                                                                                                                              |
| Server modifies the resource                   | The server uses the request document processed by the `before` hook, applying it to the Script API object.                                                                                                                                                                                                                                                                        |
| Server calls registered `after` hook           | The server passes the request document, after any modifications by the `before` hook, and the Script API object. Your custom code can do some change tracking here, or you can modify the Script API object. For example, you can recalculate the basket. Don't modify the request document, because it isn't processed again. It's provided here for informational purposes.     |
| Server applies system logic                    | For certain resources, the server performs additional system processing after the `after` hook. For example, with order creation, this includes database commits, inventory locking and booking, coupon locking and redemption, and other order-specific operations. The time spent in this step can vary depending on the resource and the complexity of the operations.         |
| Server creates the response document           | The server copies values from the Script API object, after any modifications by the `after` hook and system processing, into the response document.                                                                                                                                                                                                                               |
| Server calls registered `modifyResponse` hook  | The server passes the previous response document, after any modifications by the `after` hook, and the Script API object. This hook type is meant to make final changes to the response document only. Don't modify a Script API object in this hook type, because it isn’t executed in a transactional context. It can cause an `ORMTransactionException` and an HTTP 500 fault. |
| Server sends the response to the caller        | The server renders the response document, after any modifications by the `after` hook, into the requested format. Then the server returns the response to the caller.                                                                                                                                                                                                             |

**note:** For state-changing HTTP methods like DELETE, PATCH, POST and PUT, the server executes any `before` and `after` hook logic, plus the system logic, in the context of one database transaction. The transaction ensures that everything (or nothing) is committed into the database.

**note:** Don’t modify a Script API object in an HTTP GET request or a `modifyResponse` hook, because they are not executed in a transaction.. It can cause an `ORMTransactionException` and an HTTP 500 fault response.

For each hook, your code **SHOULD** return a `Status` object to the server. If the status is `OK`, the server continues processing. If the status is `ERROR`, representing a handled exception, the server stops further processing, **rolls back the transaction and** responds with an HTTP 400 Bad Request fault. When an `ERROR` occurs, the server returns an OCAPI fault to the caller, containing information like the error code, message, and details from the `Status` object. Uncaught exceptions in your code including the errors you throw cause an HTTP 500 Internal Error fault; in this case, the server rolls back the transaction.

If your hook code does not return a `Status` object, **multiple registered hook scripts might be executed**, including the overridden base implementation. The `Status` object or value returned by these hooks will then be returned instead.

## The Modify <HTTP Method> Response Hooks

Starting in 18.3, modify <HTTP Method> Response customization hooks are provided for the Shop API. These hooks support POST, PUT, PATCH, and GET methods, and replace the previous afterGET hooks.

Modify response hooks have the following characteristics:

- They support GET, POST, PUT, and PATCH methods to enrich the response document with custom information.
- They enable your customization code to change and unset document attributes and add, delete, and change custom attributes in the return document.
- They disallow database transactions within your customized script code, making it impossible for your code to change persistent data.
- If there’s caching, they’re only executed if the cache is empty or stale. But they aren’t executed for every GET or HEAD call.

The following example shows customization script code for the Shop API category method:

```js
const Status = require("dw/system/Status");

exports.modifyGETResponse = function (scriptCategory, categoryWO) {
  if (!scriptCategory.online) {
    categoryWO.c_modify_response_data = "modifyResponseData";
  }
  return new Status(Status.OK);
};
```

<!-- Used by both OCAPI + SCAPI hooks -->

## Register Hooks

1. Place a `package.json` file in the top-level directory of your cartridge.
2. In the `package.json` file, define the `hooks` property to the path of the `hooks.json` configuration file. This path is relative to the directory containing the `package.json` file:
   ```json
   {
     "hooks": "./cartridge/scripts/hooks.json"
   }
   ```
3. In the `hooks.json` file, configure an array with the mappings of hooks to their script files with paths relative to the `hooks.json` file:
   ```json
   {
     "hooks": [
       {
         "name": "dw.ocapi.shop.basket.billing_address.beforePUT",
         "script": "./basket_hook_scripts.js"
       },
       {
         "name": "dw.ocapi.shop.basket.billing_address.afterPUT",
         "script": "./basket_hook_scripts.js"
       }
     ]
   }
   ```
4. For site specific use, register the cartridge to each appropriate site in Business Manager. To customize organization-level resources across _all_ sites, such as libraries, register the cartridge to the Business Manager site.

### Hook Scripts

Hook scripts are loaded as CommonJS modules. Hook functions must be exported. The exported name must match the name of the hook, without the package qualification. For example, the `dw.ocapi.shop.basket.billing_address.beforePUT` hook is exported as `beforePUT`:

```javascript
//  basket_hook_scripts.js
var Status = require("dw/system/Status");
var HookManager = require("dw/system/HookMgr");

exports.beforePUT = function (basket, doc) {
  // Detect whether the address is valid.
  var isValidAddress = true;
  if (isValidAddress) {
    return new Status(Status.OK);
  }
  return new Status(Status.ERROR);
};

exports.afterPUT = function (basket, doc) {
  // Calculate the basket by calling the convenience hook, which returns a status object.
  var status = HookManager.callHook("dw.order.calculate", "calculate", basket);
  return status;
};

exports.calculate = function (basket) {
  return new Status(Status.OK);
};
```

For each hook, your code **SHOULD** return a `Status` object to the server. If the status is `OK`, the server continues processing. If the status is `ERROR`, representing a handled exception, the server stops further processing, **rolls back the transaction and** responds with an HTTP 400 Bad Request fault. When an `ERROR` occurs, the server returns a fault to the caller, containing information like the error code, message, and details from the `Status` object. Uncaught exceptions in your code including the errors you throw cause an HTTP 500 Internal Error fault; in this case, the server rolls back the transaction.

When an `ERROR` occurs, the server returns an [RFC IETF rfc7807](https://datatracker.ietf.org/doc/html/rfc7807) **ErrorResponse** to the caller, containing information like the error code, message, and details from the `Status` object.

If your hook code does not return a `Status` object, **multiple registered hook scripts might be executed**, including the overridden base implementation. The `Status` object or value returned by these hooks will then be returned instead.

#### Passing Data Between Hooks

A single request can call multiple hooks. For example: adding a new [payment instrument to a basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=addPaymentInstrumentToBasket) calls:
* `dw.ocapi.shop.basket.payment_instrument.beforePOST`
* `dw.ocapi.shop.basket.payment_instrument.afterPOST`
* `dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse`

To pass data between hooks, use [`request.custom`](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_Request.html). JavaScript objects added to the request are available in subsequent hooks.

For example, to call a 3rd party payment processor **inside the transaction** of adding a new payment instrument to the basket, you can make this call within the `dw.ocapi.shop.basket.payment_instrument.afterPOST` hook (to ensure any errors rollback the transaction). After calling the payment service provider to initialize the payment request, you can return the relevant data to the client in the `dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse` hook. To do this, add relevant data to the `request.custom` container to be handled by the `modifyPOSTResponse` hook.

```javascript
// dw.ocapi.shop.basket.payment_instrument.afterPOST
exports.afterPOST = function (order, paymentInstrumentRequest) {
   //...
   request.custom.paymentIntentID = callPaymentService();
};

// dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse
exports.modifyPOSTResponse = function (basket, basketResponse, paymentInstrumentRequest) {
   // retrieve payment instrument created in this hook execution
   var addedPayment = basketResponse.paymentInstruments.toArray().filter(function (instr) {
      return instr.paymentMethodId === paymentInstrumentRequest.paymentMethodId;
   })[0];

   addedPayment.c_paymentIntentID = request.custom.paymentIntentID;
};
```

## Hook Circuit Breaker

The Hook Circuit Breaker protects the system from excessive hook execution failures. For more information, see [Hook Circuit Breaker](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hookcircuitbreaker.html).

## Calculate Hook

The Calculate hook, `dw.order.calculate`, enables you to implement customized basket calculation logic. It can be used as the single place for basket calculation and recalculation. This hook provides a default implementation, can be overridden. The default logic of the following hooks implicitly call this hook:

- dw.ocapi.baskets.actions.afterMerge
- dw.ocapi.baskets.actions.afterTransfer
- dw.ocapi.shop.basket.afterPATCH
- dw.ocapi.shop.basket.afterPOST
- dw.ocapi.shop.basket.agent.afterPUT
- dw.ocapi.shop.basket.billing_address.afterPUT
- dw.ocapi.shop.basket.coupon.afterDELETE
- dw.ocapi.shop.basket.coupon.afterPOST
- dw.ocapi.shop.basket.customer.afterPUT
- dw.ocapi.shop.basket.gift_certificate_item.afterDELETE
- dw.ocapi.shop.basket.gift_certificate_item.afterPATCH
- dw.ocapi.shop.basket.gift_certificate_item.afterPOST
- dw.ocapi.shop.basket.item.afterDELETE
- dw.ocapi.shop.basket.item.afterPATCH
- dw.ocapi.shop.basket.items.afterPOST
- dw.ocapi.shop.basket.payment_instrument.afterDELETE
- dw.ocapi.shop.basket.payment_instrument.afterPATCH
- dw.ocapi.shop.basket.payment_instrument.afterPOST
- dw.ocapi.shop.basket.price_adjustment.afterDELETE
- dw.ocapi.shop.basket.price_adjustment.afterPATCH
- dw.ocapi.shop.basket.price_adjustment.afterPOST
- dw.ocapi.shop.basket.reference.afterPOST
- dw.ocapi.shop.basket.shipment.afterDELETE
- dw.ocapi.shop.basket.shipment.afterPATCH
- dw.ocapi.shop.basket.shipment.afterPOST
- dw.ocapi.shop.basket.shipment.shipping_address.afterPUT
- dw.ocapi.shop.basket.shipment.shipping_method.afterPUT
- dw.ocapi.shop.basket.storefront.afterPUT
- dw.ocapi.shop.order.beforePOST
- dw.ocapi.shop.order.beforePUT

The following code snippet shows a sample call:

```javascript
dw.system.HookMgr.callHook("dw.order.calculate", "calculate", basket);
```

In this sample call, the parameters are:

- `"dw.order.calculate"` - the extension point to call
- `"calculate"` - the script function to call
- `basket` - the basket to be calculated

**note:** SiteGenesis uses the default implementation of the `dw.order.calculate` hook for basket calculation logic.

<!-- document id=3edbe44dd9d8419ef7071f04d76cf7dcf937672eb397f3a5a088999bd272fef9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/expansions.md -->

# OCAPI Expansions

To minimize network traffic and server CPU usage, the Open Commerce API sometimes uses a technique called _expansion_. This technique intentionally omits parts of a selected resource, reducing the size of the overall response. However, if you want to include the parts that are omitted by default, you can explicitly request the omitted parts by using the _expand_ query parameter. This parameter specifies a comma-separated list of entities that you want expanded, identifying each of them by name.

The _`products`_ and _`product_search`_ resources support the expansion technique. A resource type that enables expansions is structured into a base resource and one or more subresources. For the `*products*` resource, the base resource is `*/products/{id}*`, and two of its subresources are `*/products/{id}/prices*` and `*/products/{id}/variations*`.

By default, the base resource returns only a basic subset of properties. A subresource returns not only the base properties but also subresource specific properties (for example, price properties). The name of the subresource is used as the _expand_ query parameter value.

The examples below show how expansion works.

## Base Resource

Request to base resource without _expand_ parameter specified. Response document contains only some basic properties.

```txt
REQUEST:
GET /dw/shop/v24_5/products/123 HTTP/1.1

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate

{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL"
}
```

## Sub Resource

Two requests to separate subresources. A subresource response document contains the basic properties plus subresource specific properties.

```txt
REQUEST 1:
GET /dw/shop/v24_5/products/123/availability HTTP/1.1

RESPONSE 1:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate

{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL",
  "orderable":true
}
```

```txt
REQUEST 2:
GET /dw/shop/v24_5/products/123/prices HTTP/1.1

RESPONSE 2:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate

{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL",
  "price":14.65
}
```

## Base Resource With Expand

Single request with _expand_ parameter. The response document contains the basic properties plus the specific properties of each subresource named in _expand_ parameter values.

```txt
REQUEST:
GET /dw/shop/v24_5/products/123?expand=availability,prices HTTP/1.1

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=60,must-revalidate

{
  "id":"123",
  "name":"Ultimate T-Shirt XXXL",
  "orderable":true,
  "price":14.65
}
```

<!-- document id=bcc05cdffb91c6f412e4eefb0699d24649f615ab121a391533bd89671c6811fa url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/filtering.md -->

# OCAPI Filtering

After you specify a resource type and relationship type (see [URL schema](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/urlschema.md)), you can specify a filter parameter to further reduce the number of resource instances in the result set. Filter parameters differ for each `resource_type` and `relationship_type` pair. In the following example, the first filter parameter `type` specifies a value of `cross_sell`, eliminating from the result set all resource instances whose type isn’t equal to `cross_sell`. The second filter parameter `direction` specifies the value `out`, eliminating all resource instances whose direction is different.

```txt

REQUEST:
GET /dw/shop/v24_5/products/123/links?type=cross_sell&direction=out HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 351
Content-Type: application/json; charset=UTF-8

{
  "_v" : "24.5",
  ...
  "product_links":
  [{
    "source_product_id":"123",
    "source_product_link":"http://example.com/dw/shop/v24_5/product/123",
    "target_product_id":"456",
    "target_product_link":"http://example.com/dw/shop/v24_5/product/456",
    "type":"cross_sell",
    "direction":"out"
  },
  {
    "source_product_id":"123",
    "source_product_link":"http://example.com/dw/shop/v24_5/product/123",
    "target_product_id":"789",
    "target_product_link":"http://example.com/dw/shop/v24_5/product/789",
    "type":"cross_sell",
    "direction":"out"
  }]

```

<!-- document id=ea086feda6373e5c6f8f74c0573b220d6803bc9f5d46c8a48a62216d7e1efdcc url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/flash.md -->

# OCAPI Flash

Flash is a property of documents and contains special information about the document.

<!--TODO: Fix link post migration -->
<!-- [Flash](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/shop/documents/flash-d.md) is a property of documents and contains special information about the document.
 -->

Such information could be:

- a message that the basket contains a product that is no more available.
- a message that the basket contains a product that has no price.
- ... and so on.

It’s currently only used at the basket document. The presence of a flash indicates a reason why the basket can’t yet be submitted. See examples of basket resource.

<!--TODO: Fix link post migration -->
<!-- It is currently only used at the basket document. The presence of a flash indicates a reason why the basket cannot yet be submitted. See examples of [basket resource](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/shop/resources/baskets.md).
 -->

In the Scripting API, flashes can be read from, added to or removed from a document using the methods addFlash, removeFlash, and flashes or getFlashes(). Flashes can be added to any object within the structure of the document - for example a flash may be added to the baskets billing address with the path `$.post_code` or to one of the baskets product items with path `$.adjusted_price`. Before sending the response to the client, such flashes are aggregated to the document and their paths are adjusted appropriately, in our example to `$.billing_address.post_code` and `$.product_items[0].adjusted_price`.

Example usage showing addition, listing, and removal of flashes:

```javascript
exports.validateBasket = function(basketResponse) {
     basketResponse.addFlash({
       type: "MyType",
       message: "My message",
       path: "my_path",
       details: {
           "k1": "v1",
           "k2": "v2"
       }
    });
    var flashToRemove;
    for each(f in basketResponse.flashes) {
      if (f.type == "SomeOtherType") {
        flashToRemove = f;
      }
    }
    if (flashToRemove != null) {
       basketResponse.removeFlash(flashToRemove);
    }
}

```

<!-- document id=a53b950de9ce7c5435afc2e995d197aae8fdd605c5d5c40e77e0fff44df3bf0e url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/exceptions.md -->

# OCAPI Global Exceptions

The following table lists all OCAPI global exceptions:

<table><col /><col /><col /><col /><thead><tr><th>Status</th><th>Type</th><th>Arguments</th><th>Description</th></tr></thead><tbody><tr><td>400</td><td><code>BodyDecodingException</code></td><td><p>body (String)</p></td><td>The request document (body) couldn’t be decoded.</td></tr><tr><td>400</td><td><code>EnumConstraintViolationException</code></td><td><p>document (String)</p><p>enumValue (String)</p></td><td>Invalid enum value provided.</td></tr><tr><td>400</td><td><code>FieldNotSortableException</code></td><td><p>field (String)</p></td><td>The specified field isn’t sortable.</td></tr><tr><td>400</td><td><code>HookStatusException</code></td><td><p>extensionPoint (String)</p><p>statusCode (String)</p><p>statusMsg (String)</p><p>statusDetails (Map)</p></td><td>An OCAPI server-side extension point returned a status of type error. The exception contains details like extension point name, status code, status message, and custom status details.</td></tr><tr><td>400</td><td><code>IllegalEnumerationValueException</code></td><td><p>value (String)</p><p>type (String)</p></td><td>Illegal enum value provided for field type.</td></tr><tr><td>400</td><td><code>IllegalHttpMethodOverrideException</code></td><td><p>method (String)</p></td><td>The HTTP method provided via <emph>x-dw-http-method-override</emph> header or <emph>method</emph> query parameter isn’t allowed. HTTP methods 'PUT', 'PATCH', 'DELETE', 'HEAD' and 'OPTIONS' are supported as override method.</td></tr><tr><td>400</td><td><code>InvalidClientIdException</code></td><td><p>clientId (String)</p></td><td>The provided client id isn’t the expected one for this token request.</td></tr><tr><td>400</td><td><code>InvalidCustomPropertyException</code></td><td></td><td>Can’t write custom property. Value is either invalid or type doesn't support modification.</td></tr><tr><td>400</td><td><code>InvalidExpandValueException</code></td><td><p>expandValue (String)</p></td><td>The specified expand value isn’t allowed.</td></tr><tr><td>400</td><td><code>InvalidHostHeaderException</code></td><td><p>host (String)</p></td><td>The host name is invalid. Not contained in the server allow list.</td></tr><tr><td>400</td><td><code>InvalidSearchFieldTypeException</code></td><td><p>field (String)</p><p>value (String)</p><p>type (String)</p></td><td>The type of the search value doesn’t match the expected field type.</td></tr><tr><td>400</td><td><code>InvalidVersionException</code></td><td></td><td>Version is missing or malformed in request URL.</td></tr><tr><td>400</td><td><code>MalformedLocaleException</code></td><td><p>locale (String)</p></td><td>The specified locale is malformed.</td></tr><tr><td>400</td><td><code>MalformedMediaTypeException</code></td><td><p>mediaType (String)</p></td><td>The media type in <emph>Content-Type</emph> header is malformed.</td></tr><tr><td>400</td><td><code>MalformedParameterException</code></td><td><p>parameter (String)</p><p>value (String)</p></td><td>A query, header, or path parameter value is malformed.</td></tr><tr><td>400</td><td><code>MalformedSelectorException</code></td><td><p>selector (String)</p></td><td>The syntax of the specified selector is malformed.</td></tr><tr><td>400</td><td><code>MissingClientIdException</code></td><td></td><td>No client id was provided, neither as query nor as header parameter.</td></tr><tr><td>400</td><td><code>NullConstraintViolationException</code></td><td><p>parameter (String)</p></td><td>The query or path parameter value is required, but value was null.</td></tr><tr><td>400</td><td><code>PropertyConstraintViolationException</code></td><td><p>document (String)</p><p>path (String)</p></td><td>The value constraint of a document property is violated.</td></tr><tr><td>400</td><td><code>PropertyNotPermittedException</code></td><td><p>property (String)</p><p>document (String)</p></td><td>A property in the given request document isn’t permitted to be modified.</td></tr><tr><td>400</td><td><code>QuerySearchTypesNomatchException</code></td><td><p>field1 (String)</p><p>field2 (String)</p><p>type1 (String)</p><p>type2 (String)</p></td><td>The fields in the specified query don't have the same type.</td></tr><tr><td>400</td><td><code>QuotaExceededException</code></td><td><p>msg (String)</p></td><td>A platform quota constraint is violated.</td></tr><tr><td>400</td><td><code>RangeFilterTypeException</code></td><td><p>field (String)</p><p>type (String)</p></td><td>The specified field type isn’t comparable in a range expression.</td></tr><tr><td>400</td><td><code>RangeFilterValueException</code></td><td><p>field (String)</p><p>value (String)</p></td><td>The specified value isn’t comparable in a range expression.</td></tr><tr><td>400</td><td><code>ResourcePathException</code></td><td><p>message (String)</p></td><td>The resource path was incorrect.</td></tr><tr><td>400</td><td><code>SearchOperatorNotApplicableException</code></td><td><p>operator (String)</p><p>field (String)</p></td><td>The specified search operator isn’t applicable for the search field.</td></tr><tr><td>400</td><td><code>StartAfterEndException</code></td><td><p>document (String)</p><p>resourceId (String)</p><p>startDate (DateTime)</p><p>endDate (DateTime)</p></td><td>The specified start date is greater than the end date.</td></tr><tr><td>400</td><td><code>StringConstraintViolationException</code></td><td><p>parameter (String)</p><p>expected (String)</p></td><td>The value constraint of a String query or path parameter is violated.</td></tr><tr><td>400</td><td><code>TermOperatorMismatchValuesException</code></td><td><p>field (String)</p><p>operator (String)</p></td><td>The search operator doesn't match the specified values.</td></tr><tr><td>400</td><td><code>TypeDecodingException</code></td><td><p>path (String)</p><p>expectedTypes (String)</p><p>actualType (String)</p></td><td>The type of a document property is invalid.</td></tr><tr><td>400</td><td><code>UnexpectedVersionException</code></td><td><p>version (String)</p></td><td>The version of the request document is invalid. It has to be the URL version.</td></tr><tr><td>400</td><td><code>UnknownLocaleException</code></td><td><p>locale (String)</p></td><td>The specified locale is unknown.</td></tr><tr><td>400</td><td><code>UnknownPropertyException</code></td><td><p>property (String)</p><p>document (String)</p></td><td>A property in the given request document is unknown.</td></tr><tr><td>400</td><td><code>UnknownSearchFieldException</code></td><td><p>field (String)</p></td><td>The search field is unknown.</td></tr><tr><td>400</td><td><code>UnknownSearchOperatorException</code></td><td><p>operator (String)</p></td><td>The specified search operator is unknown.</td></tr><tr><td>400</td><td><code>UnknownSiteIdException</code></td><td><p>siteId (String)</p></td><td>The site id provided for a site-specific property is unknown.</td></tr><tr><td>400</td><td><code>UnqueryableFieldException</code></td><td><p>field (String)</p></td><td>The specified search field in not queryable.</td></tr><tr><td>400</td><td><code>UnsupportedCurrencyException</code></td><td><p>currency (String)</p></td><td>The specified currency is invalid (must be ISO 4217) or not supported.</td></tr><tr><td>400</td><td><code>UnsupportedLocaleException</code></td><td><p>locale (String)</p></td><td>The specified locale isn’t supported/activated.</td></tr><tr><td>400</td><td><code>ValueConstraintViolationException</code></td><td><p>parameter (String)</p><p>expected (String)</p></td><td>The value constraint of a Non-String query or path parameter is violated.</td></tr><tr><td>401</td><td><code>AuthorizationHeaderMissingException</code></td><td></td><td><emph>Authorization</emph> header is missing.</td></tr><tr><td>401</td><td><code>DemoClientIdException</code></td><td><p>clientId (String)</p></td><td>Demo client ids aren’t allowed to be used on development, staging, or production instances. Demo client ids are permitted on sandbox instances only.</td></tr><tr><td>401</td><td><code>InvalidAccessTokenException</code></td><td><p>accessToken (String)</p></td><td>The OAuth access token sent via <emph>Authorization: Bearer</emph> header is invalid.</td></tr><tr><td>401</td><td><code>InvalidAuthorizationHeaderException</code></td><td></td><td>Invalid <emph>Authorization</emph> header. Value should be something like 'Bearer {access_token}'.</td></tr><tr><td>401</td><td><code>InvalidSecureTokenException</code></td><td></td><td>The session secure token is invalid. Session may have been hijacked.</td></tr><tr><td>401</td><td><code>UnauthorizedOriginException</code></td><td><p>origin (String)</p></td><td>The request origin isn’t authorized to perform the request.</td></tr><tr><td>401</td><td><code>UnauthorizedReadAccessException</code></td><td><p>method (String)</p><p>path (String)</p></td><td>The client application has no READ privileges for the resource.</td></tr><tr><td>401</td><td><code>UnauthorizedWriteAccessException</code></td><td><p>method (String)</p><p>path (String)</p></td><td>The client application has no WRITE privileges for the resource.</td></tr><tr><td>401</td><td><code>UnknownClientIdException</code></td><td><p>clientId (String)</p></td><td>No client application found for specified client id.</td></tr><tr><td>403</td><td><code>AccessWithoutUserForbiddenException</code></td><td></td><td>To access the resource an authenticated user is required.</td></tr><tr><td>403</td><td><code>ClientAccessForbiddenException</code></td><td><p>method (String)</p><p>path (String)</p></td><td>The current client isn’t authorized to access the resource.</td></tr><tr><td>403</td><td><code>OrganizationAccessForbiddenException</code></td><td></td><td>Global access via "/s/-/" is forbidden. Expected site-specific access via "/s/{site-id}/".</td></tr><tr><td>403</td><td><code>SecureCommunicationRequiredException</code></td><td></td><td>The request requires a secure connection (HTTPS).</td></tr><tr><td>403</td><td><code>SiteAccessForbiddenException</code></td><td><p>siteId (String)</p></td><td>Site-specific access via "/s/{site-id}/" is forbidden. Expected global access via "/s/-/".</td></tr><tr><td>403</td><td><code>SiteOfflineException</code></td><td><p>siteId (String)</p></td><td>Access to the offline site is forbidden.</td></tr><tr><td>403</td><td><code>UserAccessForbiddenException</code></td><td><p>method (String)</p><p>path (String)</p></td><td>The current user isn’t authorized to access the resource.</td></tr><tr><td>404</td><td><code>CurrencyNotFoundException</code></td><td><p>currencyId (String)</p></td><td>No currency found for specified mnemonic. Expected ISO 4217 mnemonic code.</td></tr><tr><td>404</td><td><code>ResourcePathNotFoundException</code></td><td><p>path (String)</p></td><td>The resource couldn’t be found in specified API and version.</td></tr><tr><td>404</td><td><code>UnknownSiteException</code></td><td><p>siteId (String)</p></td><td>No site found for specified site id.</td></tr><tr><td>404</td><td><code>VersionNotFoundException</code></td><td><p>version (String)</p></td><td>Version specified in URL is either unknown.</td></tr><tr><td>405</td><td><code>MethodNotAllowedException</code></td><td><p>method (String)</p></td><td>The HTTP method isn’t allowed.</td></tr><tr><td>406</td><td><code>CharsetNotAcceptableException</code></td><td><p>charset (String)</p></td><td>Unsupported charset in <emph>Accept-Charset</emph> header. Only UTF-8 is allowed.</td></tr><tr><td>409</td><td><code>IfMatchRequiredException</code></td><td></td><td><emph>If-Match</emph> header is required, but no one was provided.</td></tr><tr><td>409</td><td><code>ObjectInDeletionConflictException</code></td><td><p>objectId (String)</p></td><td>Object is already in (asynchronous) deletion.</td></tr><tr><td>409</td><td><code>ResourceStateConflictException</code></td><td><p>client (String)</p><p>server (String)</p></td><td>A state token was sent with the request and doesn’t match the object's state on server side.</td></tr><tr><td>412</td><td><code>InvalidIfMatchException</code></td><td><p>ifMatch (String)</p></td><td>The If-Match header entity tag is invalid or out-dated.</td></tr><tr><td>413</td><td><code>RequestEntityTooLargeException</code></td><td></td><td>Request body size limit of 5 MB has been exceeded.</td></tr><tr><td>415</td><td><code>UnsupportedContentTypeException</code></td><td><p>contentType (String)</p></td><td>Unsupported media type in <emph>Content-Type</emph> header. Only 'application/json', 'application/xml' and 'text/xml' are allowed.</td></tr><tr><td>415</td><td><code>UnsupportedFormatException</code></td><td><p>format (String)</p></td><td>Unsupported format in <emph>format</emph> query parameter. Only 'json' and 'xml' are allowed.</td></tr></tbody></table></sfdocstbl>

<!-- document id=c1bb13e5ff5b6b7b66202dfa249fb0908739fa62a339efc75afaf28dd59febf3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/http-headers.md -->

# OCAPI Global HTTP Headers

The following table lists all OCAPI global HTTP headers:

<table>
<thead>
<tr>
<th>Header Name</th>
<th>Type</th>
<th>Syntax</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Accept-Charset</td>
<td>Request</td>
<td>

```txt
Accept-Charset: {charset} Accept-Charset: utf-8
```

</td>
<td>Indicates which character set the client is able to understand. See <a href="https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.3">RFC 7231, section 5.3.3: Accept-Charset</a>. </td>
</tr>
<tr>
<td>Access-Control-Allow-Credentials</td>
<td>Response</td>
<td>

```txt
Access-Control-Allow-Credentials: {boolean}
Access-Control-Allow-Credentials: true
```

</td>
<td>Used in the context of a CORS request. Indicates whether or not the actual request can be made using credentials. See <a href="https://fetch.spec.whatwg.org/#http-access-control-allow-credentials">Fetch, http-access-control-allow-credentials</a>. </td>
</tr>
<tr>
<td>Access-Control-Allow-Headers</td>
<td>Response</td>
<td>

```txt
Access-Control-Allow-Headers: {header-name}, {header-name}, ...
```

</td>
<td>Used in the context of a CORS pre-flight request. Indicates which HTTP headers can be used during the actual request. See <a href="https://fetch.spec.whatwg.org/#http-access-control-allow-headers">Fetch, http-access-control-allow-headers</a>. </td>
</tr>
<tr>
<td>Access-Control-Allow-Methods</td>
<td>Response</td>
<td>

```txt
Access-Control-Allow-Methods: {http-method}, {http-method}, ...
```

</td>
<td>Used in the context of a CORS pre-flight request. Specifies the method or methods allowed in the actual request. See <a href="https://fetch.spec.whatwg.org/#http-access-control-allow-methods">Fetch, http-access-control-allow-methods</a>. </td>
</tr>
<tr>
<td>Access-Control-Allow-Origin</td>
<td>Response</td>
<td>

```txt
Access-Control-Allow-Origin: {origin}
```

</td>
<td>Used in the context of a CORS pre-flight request. Indicates whether the response can be shared with resources with the given origin. See <a href="https://fetch.spec.whatwg.org/#http-access-control-allow-origin">Fetch, http-access-control-allow-origin</a>. </td>
</tr>
<tr>
<td>Access-Control-Expose-Headers</td>
<td>Response</td>
<td>

```txt
Access-Control-Expose-Headers: {header-name}, {header-name}, ...
```

</td>
<td>Used in the context of a CORS request. Indicates which HTTP headers can be exposed as part of the response. See <a href="https://fetch.spec.whatwg.org/#http-access-control-expose-headers">Fetch, http-access-control-expose-headers</a>. </td>
</tr>
<tr>
<td>Access-Control-Max-Age</td>
<td>Response</td>
<td>

```txt
Access-Control-Max-Age: {delta-seconds}
```

</td>
<td>Used in the context of a CORS pre-flight request. Indicates how long the results of a pre-flight request can be cached on the client side. See <a href="https://fetch.spec.whatwg.org/#http-access-control-max-age">Fetch, http-access-control-max-age</a>. </td>
</tr>
<tr>
<td>Access-Control-Request-Headers</td>
<td>Request</td>
<td>

```txt
Access-Control-Request-Headers: {header-name}, {header-name}, ...
```

</td>
<td>Used in the context of a CORS pre-flight request. Lets the server know which HTTP headers is used when the actual request is made. See <a href="https://fetch.spec.whatwg.org/#http-access-control-request-headers">Fetch, http-access-control-request-headers</a>. </td>
</tr>
<tr>
<td>Access-Control-Request-Method</td>
<td>Request</td>
<td>

```txt
Access-Control-Request-Method: {http-method}
```

</td>
<td>Used in the context of a CORS pre-flight request. Lets the server know which HTTP method is used when the actual request is made. See <a href="https://fetch.spec.whatwg.org/#http-access-control-request-method">Fetch, http-access-control-request-method</a>. </td>
</tr>
<tr>
<td>Allow</td>
<td>Response</td>
<td>

```txt
Allow: {http-methods}
```

</td>
<td>Lists the HTTP methods supported by an OCAPI resource. See <a href="http://tools.ietf.org/html/7231#section-7.4.1">RFC 7231, section 7.4.1: Allow</a>. </td>
</tr>
<tr>
<td>Authorization</td>
<td>Request</td>
<td>

```txt
Authorization: {type} {credentials}
```

</td>
<td>Contains the credentials to authenticate a user and/or client application with a server. See <a href="http://tools.ietf.org/html/7235#section-4.2">RFC 7235, section 4.2: Authorization</a>. </td>
</tr>
<tr>
<td>Cache-Control</td>
<td>Request</td>
<td>

```txt
Cache-Control: no-cache, no-store, must-revalidate
Cache-Control: max-age= {seconds}
```

</td>
<td>Specifies directives for caching mechanisms in both requests and responses. See <a href="http://tools.ietf.org/html/7234">Hypertext Transfer Protocol (HTTP/1.1): Caching</a>. </td>
</tr>
<tr>
<td>Content-Length</td>
<td>Request, Response</td>
<td>

```txt
Content-Length: {length}
```

</td>
<td>Indicates the size of the entity-body, in bytes. See <a href="http://tools.ietf.org/html/7230#section-3.3.2">RFC 7231, section 3.3.2: Content-Length</a>. </td>
</tr>
<tr>
<td>Content-Type</td>
<td>Request, Response</td>
<td>

```txt
Content-Type: application/json; charset=utf-8
Content-Type: application/xml;
```

</td>
<td>Indicates the request or response message media type. See <a href="https://tools.ietf.org/html/rfc7231#section-3.1.1.5">RFC 7231, section 3.1.1.5: Content-Type</a>. </td>
</tr>
<tr>
<td>DNT</td>
<td>Request, Response</td>
<td>

```txt
DNT: 0
DNT: 1
```

</td>
<td>Controls shopper tracking. See <a href="https://tools.ietf.org/html/draft-mayer-do-not-track-00">IETF: Draft Do-Not-Track</a>. </td>
</tr>
<tr>
<td>Location</td>
<td>Response</td>
<td>

```txt
Location: <url>
```

</td>
<td>Indicates the URL of a new created resource via HTTP 201 (created) status. See <a href="http://tools.ietf.org/html/7231#section-7.1.2">RFC 7231, section 7.1.2: Location</a>. </td>
</tr>
<tr>
<td>Origin</td>
<td>Request</td>
<td>

```txt
Origin: {scheme} "://" {hostname} [ ":" {port} ]
Origin: https://api-explorer.commercecloud.salesforce.com
```

</td>
<td>Used in the context of a CORS request. Indicates the origin of a fetch. See <a href="http://tools.ietf.org/html/6454#section-7">RFC 6454, section 7: Origin</a>. </td>
</tr>
<tr>
<td>x-dw-client-id</td>
<td>Request</td>
<td>

```txt
x-dw-client-id: {client-id}
```

</td>
<td>Informs the OCAPI server about the client application making the request.</td>
</tr>
<tr>
<td>x-dw-http-method-override</td>
<td>Request</td>
<td>

```txt
x-dw-http-method-override: <http-method>
```

</td>
<td>Overrides the actual HTTP method. <!-- See <a href="https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/OCAPI/current/usage/HttpMethods.html#HttpMethods24.5__OverrideHTTPmethod">Override HTTP method</a>. --></td>
</tr>
<tr>
<td>x-dw-pretty-print</td>
<td>Request</td>
<td>

```txt
x-dw-pretty-print: {boolean}
x-dw-pretty-print: true
```

</td>
<td>Indicates whether the server should format the response payload in nice way.</td>
</tr>
<tr>
<td>x-dw-resource-state</td>
<td>Request, Response</td>
<td>

```txt
x-dw-resource-state: {resource-state}
```

</td>
<td>In the context of a request, indicates the expected state of a resource. In the context of a response, indicates the last known state of a resource. Used for optimistic locking. <!-- See <a href="https://www.salesforce.com/">Resource States</a>. --> </td>
</tr>
<tr>
<td>x-dw-version-status</td>
<td>Response</td>
<td>

```txt
x-dw-version-status: [current|deprecated|obsolete]
```

</td>
<td>Indicates the version status of the requested OCAPI resource.</td>
</tr>

</tbody>
</table>

<!-- document id=82f33b1fb907560b3b82cd3342ab05be91c3e83d31e3dc48451e2087463ae4bd url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/hookcircuitbreaker.md -->

# OCAPI Hook Circuit Breaker

The Hook Circuit Breaker feature improves stability and saves processing time by protecting the system from high rates of hook failures. It tracks calls to each hook type individually.

## How It Works

Each extension point type has its own circuit breaker instance that tracks the rate of failed executions for that hook. The circuit breaker can be in one of three states: closed, open, or half-open. Normally, it's closed. If at any time, the 100 most recent calls to the hook include more than 50 failures, the following process is triggered:

1.  The circuit breaker's status changes to `open`. This change is logged.
2.  For 60 seconds, any calls to the failing extension point return an HTTP Status Code `503 (Service Unavailable)` with the fault type `HookCircuitBreakerException`.
3.  After 60 seconds, the circuit breaker's status changes to `half-open`. This change is logged.
4.  The circuit breaker tracks the next 10 calls to the failing extension point. If more than 5 of them fail, return to step 1.
5.  The circuit breaker's status changes to `closed` and it resumes tracking calls to the hook. This change is logged.

## Troubleshooting Hook Failures

If your hook calls return `503 (Service Unavailable)` errors, use Log Center to investigate the cause.

<!--TODO: Fix link post migration -->
<!-- If your hook calls return `503 (Service Unavailable)` errors, use [Log Center](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/site-development/b2c-log-center.md) to investigate the cause.
 -->

1.  In Business Manager, navigate to **Administration** > **Site Development** > **Development Setup**.
2.  In the Log Files section, click **Log Center**.
3.  Select the Day of Year.
4.  In the **LCQL** field, enter `HookCircuitBreaker`.
5.  In the query hits, look for a HookInvocationException entry and click its **Stack Trace UUID** link.
6.  In the stack trace, find the `Caused by` section. It can contain information about the cause of the hook failures. Some possible causes include:
    - The hook contains a remote call that never returns a response, causing the hook to time out. In this case, try making an asynchronous OCAPI call instead.
    - The hook script contains errors. Fix the code and consider adding error handling measures.

For information on extension points and supported resources, see [OCAPI Hooks for Data API 24.5](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hooks-data.md) and [OCAPI Hooks for Shop API 24.5](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hooks-shop.md).

<!-- document id=9b11b307b328d18824361835082d8c8d7d41b5e42a8f735d425c7d194276ea0b url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/hooks-data.md -->

# OCAPI Hooks for Data API

The following hooks exist in OCAPI version 24.5.

## Content

Content hooks for Data API.

---

**dw.ocapi.data.content.content.afterCreate**

`PUT /libraries/{library_id}/content/{content_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterCreate</b> (library : <i>dw.content.Library</i>, content : <i>dw.content.Content</i>, create : <i>ContentAsset</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the new content asset was created.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>content - the new content asset.</dd>
    <dd>create - the content asset create document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.content.afterDelete**

`DELETE /libraries/{library_id}/content/{content_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterDelete</b> (library : <i>dw.content.Library</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the content asset was deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.content.afterUpdate**

`PATCH /libraries/{library_id}/content/{content_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterUpdate</b> (library : <i>dw.content.Library</i>, content : <i>dw.content.Content</i>, update : <i>ContentAsset</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the content asset is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>content - the content asset to update.</dd>
    <dd>update - the update document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.content.beforeCreate**

`PUT /libraries/{library_id}/content/{content_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeCreate</b> (library : <i>dw.content.Library</i>, create : <i>ContentAsset</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the content asset is created with the given document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>create - the content asset create document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.content.beforeDelete**

`DELETE /libraries/{library_id}/content/{content_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeDelete</b> (library : <i>dw.content.Library</i>, content : <i>dw.content.Content</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the content asset is deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>content - the content asset to be deleted.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.content.beforeUpdate**

`PATCH /libraries/{library_id}/content/{content_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeUpdate</b> (library : <i>dw.content.Library</i>, content : <i>dw.content.Content</i>, update : <i>ContentAsset</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the content asset is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>content - the content asset to update.</dd>
    <dd>update - the update document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Content Folder

Content folder hooks for Data API.

---

**dw.ocapi.data.content.folder.afterCreate**

`PUT /libraries/{library_id}/folders/{folder_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterCreate</b> (library : <i>dw.content.Library</i>, folder : <i>dw.content.Folder</i>, create : <i>ContentFolder</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the new content folder was created.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>folder - the new content folder.</dd>
    <dd>create - the content folder create document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.folder.afterDelete**

`DELETE /libraries/{library_id}/folders/{folder_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterDelete</b> (library : <i>dw.content.Library</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the content folder was deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.folder.afterUpdate**

`PATCH /libraries/{library_id}/folders/{folder_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterUpdate</b> (library : <i>dw.content.Library</i>, folder : <i>dw.content.Folder</i>, update : <i>ContentFolder</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the content folder is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>folder - the content folder to update.</dd>
    <dd>update - the update document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.folder.beforeCreate**

`PUT /libraries/{library_id}/folders/{folder_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeCreate</b> (library : <i>dw.content.Library</i>, create : <i>ContentFolder</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the content folder is created with the given document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>folder - the content folder create document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.folder.beforeDelete**

`DELETE /libraries/{library_id}/folders/{folder_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeDelete</b> (library : <i>dw.content.Library</i>, folder : <i>dw.content.Folder</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the content folder is deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>folder - the content folder to be deleted.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.content.folder.beforeUpdate**

`PATCH /libraries/{library_id}/folders/{folder_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeUpdate</b> (library : <i>dw.content.Library</i>, folder : <i>dw.content.Folder</i>, update : <i>ContentFolder</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the content folder is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>library - the library in the actual context</dd>
    <dd>folder - the content folder to update.</dd>
    <dd>update - the update document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer

Customer hooks for Data API.

---

**dw.ocapi.data.customer_list.customer.afterDELETE**

`DELETE /customer_lists/{list_id}/customers/{customer_no}`

<details>
<summary>Method details</summary>

<p>
  <b>afterDelete</b> (customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer was deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customer.afterPATCH**

`PATCH /customer_lists/{list_id}/customers/{customer_no}`

<details>
<summary>Method details</summary>

<p>
  <b>afterPatch</b> (customer : <i>dw.customer.Customer</i>, update : <i>Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer to update.</dd>
    <dd>update - the update document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customer.beforeDELETE**

`DELETE /customer_lists/{list_id}/customers/{customer_no}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeDelete</b> (customer : <i>dw.customer.Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer is deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer to be deleted.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customer.beforePATCH**

`PATCH /customer_lists/{list_id}/customers/{customer_no}`

<details>
<summary>Method details</summary>

<p>
  <b>beforePatch</b> (customer : <i>dw.customer.Customer</i>, update : <i>Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer to update.</dd>
    <dd>update - the update document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customers

Customers hooks for Data API.

---

**dw.ocapi.data.customer_list.customers.afterPOST**

`POST /customer_lists/{list_id}/customers`

<details>
<summary>Method details</summary>

<p>
  <b>afterPost</b> (customer : <i>dw.customer.Customer</i>, create : <i>Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the new customer was created.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the new customer.</dd>
    <dd>create - the customer create document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customers.afterPUT**

`PUT /customer_lists/{list_id}/customers/{customer_no}`

<details>
<summary>Method details</summary>

<p>
  <b>afterPut</b> (customer : <i>dw.customer.Customer</i>, create : <i>Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the new customer was created.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the new customer.</dd>
    <dd>create - the customer create document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customers.beforePOST**

`POST /customer_lists/{list_id}/customers`

<details>
<summary>Method details</summary>

<p>
  <b>beforePost</b> (create : <i>Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer is created with the given document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>create - the customer create document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customers.beforePUT**

`PUT /customer_lists/{list_id}/customers/{customer_no}`

<details>
<summary>Method details</summary>

<p>
  <b>beforePut</b> (create : <i>Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer is created with the given document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>create - the customer create document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer Address

Customer address hooks for Data API.

---

**dw.ocapi.data.customer_list.customer.address.afterDELETE**

`DELETE /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterDelete</b> (customer : <i>dw.customer.Customer</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer address was deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the address should be deleted for.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customer.address.afterPATCH**

`PATCH /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}`

<details>
<summary>Method details</summary>

<p>
  <b>afterPatch</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, update : <i>CustomerAddress</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer address is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the address should be updated for.</dd>
    <dd>update - the update document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customer.address.beforeDELETE**

`DELETE /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeDelete</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer is deleted.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the address should be deleted for.</dd>
    <dd>customerAddress - the customer address to be deleted.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customer.address.beforePATCH**

`PATCH /customer_lists/{list_id}/customers/{customer_no}/addresses/{address_id}`

<details>
<summary>Method details</summary>

<p>
  <b>beforePatch</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, update : <i>CustomerAddress</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer address is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the address should be updated for.</dd>
    <dd>customerAddress - the customer address to update.</dd>
    <dd>update - the update document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer Addresses

Customer addresses hooks for Data API.

---

**dw.ocapi.data.customer_list.customer.addresses.afterPOST**

`POST /customer_lists/{list_id}/customers/{customer_no}/addresses`

<details>
<summary>Method details</summary>

<p>
  <b>afterPost</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, create : <i>CustomerAddress</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the new customer address was created.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the address should be created for.</dd>
    <dd>customerAddress - the new customer address.</dd>
    <dd>create - the customer address create document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.customer_list.customer.addresses.beforePOST**

`POST /customer_lists/{list_id}/customers/{customer_no}/addresses`

<details>
<summary>Method details</summary>

<p>
  <b>beforePost</b> (customer : <i>dw.customer.Customer</i>, create : <i>CustomerAddress</i>, customerListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a customer address is created with the given document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the address should be created for.</dd>
    <dd>create - the customer address create document.</dd>
    <dd>customerListId - the id of the customerlist the customer is assigned to</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Object

Object hooks for Data API.

---

**dw.ocapi.data.object.afterDelete**

`DELETE /custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>afterDelete</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the custom object was deleted.
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.afterDelete**

`DELETE /sites/{site_id}/custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>afterDelete</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the custom object was deleted.
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.afterPatch**

`PATCH /custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>afterPatch</b> (customObject : <i>dw.object.CustomObject</i>, create : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the custom object was updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customObject - the updated custom object</dd>
    <dd>update - the update document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.afterPatch**

`PATCH /sites/{site_id}/custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>afterPatch</b> (customObject : <i>dw.object.CustomObject</i>, create : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the custom object was updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customObject - the updated custom object</dd>
    <dd>update - the update document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.afterPut**

`PUT /custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>afterPut</b> (customObject : <i>dw.object.CustomObject</i>, create : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the custom object was created with create document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customObject - the created custom object</dd>
    <dd>create - the create document, may be <code>null</code></dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.afterPut**

`PUT /sites/{site_id}/custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>afterPut</b> (customObject : <i>dw.object.CustomObject</i>, create : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the custom object was created with create document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customObject - the created custom object</dd>
    <dd>create - the create document, may be <code>null</code></dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.beforeDelete**

`DELETE /custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeDelete</b> (customObject : <i>dw.object.CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the custom object is removed.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>create - the create document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.beforeDelete**

`DELETE /sites/{site_id}/custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>beforeDelete</b> (customObject : <i>dw.object.CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the custom object is removed.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>create - the create document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.beforePatch**

`PATCH /custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>beforePatch</b> (customObject : <i>dw.object.CustomObject</i>, update : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the custom object is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>update - the update document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.beforePatch**

`PATCH /sites/{site_id}/custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>beforePatch</b> (customObject : <i>dw.object.CustomObject</i>, update : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the custom object is updated with update document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>update - the update document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.beforePut**

`PUT /custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>beforePut</b> (create : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the custom object is created with create document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>create - the create document, may be <code>null</code></dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.data.object.beforePut**

`PUT /sites/{site_id}/custom_objects/{object_type}/{key}`

<details>
<summary>Method details</summary>

<p>
  <b>beforePut</b> (create : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the custom object is created with create document.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>create - the create document, may be <code>null</code></dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Users

Users hooks for Data API.

---

**dw.ocapi.data.users.afterPATCH**

`PATCH /users/this/password`

<details>
<summary>Method details</summary>

<p>
  <b>afterPatch</b> (login : <i>String</i>, email : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the user's password is updated.
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>login - The login of the user.</dd>
    <dd>email - The email of the user.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>

<!-- document id=cbd14599cca0481431c1cec571ebbfbdc3e9a5e779dcff8f312f49c6e0cec06b url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/hooks-shop.md -->

# OCAPI Hooks for Shop API

The following hooks exist in OCAPI.

## Auth

Auth hooks for Shop API.

---

**dw.ocapi.shop.auth.afterPOST**

`POST /customers/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, authRequestType : <i>dw.value.EnumValue</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the authenticated customer</dd>
    <dd>authRequestType - does the request specify a guest, login or refresh authentication</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.auth.beforePOST**

`POST /customers/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (authorizationHeader : <i>String</i>, authRequestType : <i>dw.value.EnumValue</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>authorizationHeader - the authorization header. Differs depending on the type: 
      <ul>
        <li>guest - no content relevant to the authentication.</li>
        <li>credentials - Base64 encoded username and password. For example Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=. It is possible to extract the username or password: <codeblock>var credentials = authHeader.substr(6); // cut out Basic var base64decoded : String = StringUtils.decodeBase64(credentials, "UTF-8"); var userName : String = base64decoded.split(":")[0]; var password : String = base64decoded.split(":")[1];</codeblock></li>
        <li>refresh - A refresh token, for example Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXX</li>
        <li>session - no content relevant to the authentication. Authentication based on cookies.</li>
      </ul>
    </dd>
    <dd>authRequestType - does the request specify a guest, login or refresh authentication</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.auth.modifyPOSTResponse**

`POST /customers/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i>Customer</i>, authRequestType : <i>dw.value.EnumValue</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the auth customer</dd>
    <dd>customerResponse - customer response object</dd>
    <dd>authRequestType - auth request type enum</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Basket

Basket hooks for Shop API.

---

**dw.ocapi.shop.basket.afterDELETE**

`DELETE /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the identifier of the removed basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.afterPATCH**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, basketInput : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket that was updated</dd>
    <dd>basketInput - the basket delta containing the desired changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.afterPOST**

`POST /baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the basket was created. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the created basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.agent.afterPUT**

`PUT /baskets/{basket_id}/agent`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a put of a basket as an agent basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.agent.beforePUT**

`PUT /baskets/{basket_id}/agent`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.agent.modifyPUTResponse**

`PUT /baskets/{basket_id}/agent`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.approaching_discounts.beforeGET**

`GET /baskets/{basket_id}/approaching_discounts`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.approaching_discounts.modifyGETResponse**

`GET /baskets/{basket_id}/approaching_discounts`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (approachingDiscountResultResponse : <i>ApproachingDiscountResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>approachingDiscountResultResponse - approaching discount result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforeDELETE**

`DELETE /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforeGET**

`GET /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforePATCH**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, basketInput : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to be updated</dd>
    <dd>basketInput - the basket delta containing the desired changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.beforePOST_v2**

`POST /baskets`

<details>
<summary>Method details</summary>

<p>
  <b>beforePOST_v2</b> (basketRequest : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketRequest - the basket request</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.billing_address.afterPUT**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, billingAddress : <i>OrderAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of the billing address to the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>billingAddress - the billing address that was set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.billing_address.beforePUT**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, billingAddress : <i>OrderAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of the billing address to the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>billingAddress - the billing address to be set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.billing_address.modifyPUTResponse**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, addressRequest : <i>OrderAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>addressRequest - address request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.afterDELETE**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, couponItemID : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a coupon from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get removed from</dd>
    <dd>couponItemID - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.afterPOST**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, couponItem : <i>CouponItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding a coupon to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get added to</dd>
    <dd>couponItem - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.beforeDELETE**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, couponItemID : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a coupon from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get removed from</dd>
    <dd>couponItemID - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.beforePOST**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, couponItem : <i>CouponItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding a coupon to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the coupon get added to</dd>
    <dd>couponItem - the coupon information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, couponItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>couponItemId - coupon item id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.coupon.modifyPOSTResponse**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, couponRequest : <i>CouponItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>couponRequest - coupon request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.customer.afterPUT**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, customerInfo : <i>CustomerInfo</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of customer information for the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>customerInfo - the customer information that were set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.customer.beforePUT**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, customerInfo : <i>CustomerInfo</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of customer information for the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>customerInfo - the customer information to be set to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.customer.modifyPUTResponse**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, customerRequest : <i>CustomerInfo</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>customerRequest - customer request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.afterDELETE**

`DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after deleting a gift certificate item from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the deleted gift certificate item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.afterPATCH**

`PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>, item : <i>GiftCertificateItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating a gift certificate item of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the updated gift certificate item</dd>
    <dd>item - the new gift certificate item data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.afterPOST**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, item : <i>GiftCertificateItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding a gift certificate item to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the gift certificate item to add</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.beforeDELETE**

`DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before deleting a gift certificate item from a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the gift certificate item to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.beforePATCH**

`PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, giftCertificateItemId : <i>String</i>, item : <i>GiftCertificateItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a gift certificate item of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>giftCertificateItemId - the id of the gift certificate item to be updated</dd>
    <dd>item - the new gift certificate item data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.beforePOST**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, item : <i>GiftCertificateItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding a gift certificate item to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the gift certificate item to add</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>giftCertificateItemId - the id of the deleted gift certificate item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, giftCertificateItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>giftCertificateItemId - the id of the updated gift certificate item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.gift_certificate_item.modifyPOSTResponse**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, certificateItemRequest : <i>GiftCertificateItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>certificateItemRequest - certificateItem request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.afterDELETE**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a basket item is removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>productItemId - the id of the removed product item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.afterPATCH**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, item : <i>ProductItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating of the basket's item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the product item delta containing the desired changes to the product item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.beforeDELETE**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a basket item is removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>productItemId - the id of the product item to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.beforePATCH**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, item : <i>ProductItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating of the basket's item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>item - the product item delta containing the desired changes to the product item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>productItemId - productItemId request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.item.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, productItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>productItemId - productItemId request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.afterPATCH**

`PATCH /baskets/{basket_id}/items`

<details>
<summary>Method details</summary>
<p>
<b>afterPATCH</b> (basket: <i>Basket</i>, items: <i>ProductItem[]</i>) : <i>dw.system.Status</i>
</p>
<p>
The function is called by extension point  {@value #extensionPointAfterPatch}  after the patch basket items.
</p>

<div>
<dl>
<dt><b>Parameters:</b></dt>
<dd>basket - the target basket</dd>
<dd>items - productItems array of product items</dd>
</dl>
<dl>
<dt><b>Returns:</b></dt>
<dd>a non-null Status ends the hook execution</dd>
</dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.afterPOST**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, items : <i>ProductItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>items - productItems array of product items</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.beforePATCH**

`PATCH /baskets/{basket_id}/items`

<details>
<summary>Method details</summary>
<p>
<b>beforePATCH</b> (basket: <i>Basket</i>, items: <i>ProductItem[]</i>) : <i>dw.system.Status</i>
</p>
<p>
The function is called by extension point  {@value #extensionPointBeforePatch}  before the patch basket items.
</p>

<div>
<dl>
<dt><b>Parameters:</b></dt>
<dd>basket - the target basket</dd>
<dd>items - productItems array of product items</dd>
</dl>
<dl>
<dt><b>Returns:</b></dt>
<dd>a non-null Status ends the hook execution</dd>
</dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.beforePOST**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, items : <i>ProductItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>items - productItems array of product items</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/items`

<details>
<summary>Method details</summary>
<p>
<b>modifyPATCHResponse</b> (basket: <i>Basket</i>, productItems: <i>ProductItem[]</i>, basketResponse: <i>Basket</i>) : <i>dw.system.Status</i>
</p>
<p>
The function is called to modify the response by extension point  {@value #extensionPointModifyPATCHResponse} 
 after the patch basket items.
</p>

<div>
<dl>
<dt><b>Parameters:</b></dt>
<dd>basket - the target basket</dd>
<dd>productItems - productItems array of product items</dd>
<dd>basketResponse - basket response object</dd>
</dl>
<dl>
<dt><b>Returns:</b></dt>
<dd>a non-null Status ends the hook execution</dd>
</dl>
</div>
</details>

---

**dw.ocapi.shop.basket.items.modifyPOSTResponse**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, productItems : <i>ProductItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>productItems - productItems array of product items</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.modifyGETResponse**

`GET /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.modifyPATCHResponse**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.modifyPOSTResponse**

`POST /baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the created basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.note.afterDELETE**

`DELETE /baskets/{basket_id}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, note : <i>dw.object.Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a note is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>note - the note to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.note.afterPOST**

`POST /baskets/{basket_id}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basketId : <i>String</i>, note : <i>Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a note is added. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>note - the note to be added</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.note.beforeDELETE**

`DELETE /baskets/{basket_id}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, note : <i>dw.object.Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a note is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>note - the note to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.note.beforePOST**

`POST /baskets/{basket_id}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basketId : <i>String</i>, note : <i>Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a note is added. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket</dd>
    <dd>note - the note to be added</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.note.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, noteId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>noteId - deleted note id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.note.modifyPOSTResponse**

`POST /baskets/{basket_id}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, noteRequest : <i>Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>noteRequest - note request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.notes.beforeGET**

`GET /baskets/{basket_id}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket id the notes result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.notes.modifyGETResponse_v2**

`GET /baskets/{basket_id}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (basket : <i>dw.order.Basket</i>, notesResponse : <i>NotesResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the notes result retrieved for.</dd>
    <dd>notesResponse - notes response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.afterDELETE**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  It is called after the <i>order payment instrument</i> is removed from the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the payment instrument was removed from</dd>
    <dd>paymentInstrument - the payment instrument to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.afterPATCH**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, paymentInstrumentRequest : <i>BasketPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating a payment instrument of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the updated payment instrument</dd>
    <dd>paymentInstrumentRequest - the new payment instrument data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.afterPOST**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i>BasketPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after payment instrument adding to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the payment instrument added to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.beforeDELETE**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, delete : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  It is called before the <i>order payment instrument</i> is removed from the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to remove the payment instrument from</dd>
    <dd>delete - the order payment instrument document.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.beforePATCH**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, newPaymentInstrument : <i>BasketPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a payment instrument of a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the payment instrument to be updated</dd>
    <dd>newPaymentInstrument - the new payment instrument data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.beforePOST**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, paymentInstrument : <i>BasketPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before payment instrument adding to a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>paymentInstrument - the payment instrument to be added to the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>paymentInstrumentRequest - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>paymentInstrumentRequest - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_instrument.modifyPOSTResponse**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, paymentInstrumentRequest : <i>BasketPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>paymentInstrumentRequest - payment instrument request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_methods.afterGET**

`GET /baskets/{basket_id}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>afterGET</b> (basket : <i>dw.order.Basket</i>, paymentMethods : <i>PaymentMethodResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Called before returning the list of available payment methods to the customer. Allowing modifications of the result. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>paymentMethods - the available payment methods</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_methods.beforeGET**

`GET /baskets/{basket_id}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the basket id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.payment_methods.modifyGETResponse_v2**

`GET /baskets/{basket_id}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (basket : <i>dw.order.Basket</i>, paymentMethodResultResponse : <i>PaymentMethodResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket the payment method result retrieved for.</dd>
    <dd>paymentMethodResultResponse - paymentMethodResult response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.afterDELETE**

`DELETE /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, priceAdjustmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a custom price adjustment was removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>priceAdjustmentId - the id of the deleted price adjustment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.afterPATCH**

`PATCH /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, priceAdjustmentId : <i>String</i>, priceAdjustmentWO : <i>PriceAdjustment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a custom price adjustment was updated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>priceAdjustmentId - the id of the updated price adjustment</dd>
    <dd>priceAdjustmentWO - the new price adjustment data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.afterPOST**

`POST /baskets/{basket_id}/price_adjustments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, request : <i>PriceAdjustmentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a custom price adjustment was added. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>request - The request for the price adjustment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.beforeDELETE**

`DELETE /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, priceAdjustmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a custom price adjustment is removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>priceAdjustmentId - the id of the price adjustment to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.beforePATCH**

`PATCH /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, priceAdjustmentId : <i>String</i>, priceAdjustmentWO : <i>PriceAdjustment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a custom price adjustment is updated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>priceAdjustmentId - the id of the price adjustment to be updated</dd>
    <dd>priceAdjustmentWO - the new price adjustment data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.beforePOST**

`POST /baskets/{basket_id}/price_adjustments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, request : <i>PriceAdjustmentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a custom price adjustment is added. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
    <dd>request - The request for the price adjustment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, priceAdjustmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>priceAdjustmentId - price adjustment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, priceAdjustmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>priceAdjustmentId - price adjustment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.price_adjustment.modifyPOSTResponse**

`POST /baskets/{basket_id}/price_adjustments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, priceAdjustmentRequest : <i>PriceAdjustmentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>priceAdjustmentRequest - price adjustment request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.reference.afterPOST**

`POST /baskets/reference`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (sourceBasket : <i>dw.order.Basket</i>, basket : <i>dw.order.Basket</i>, request : <i>BasketReference</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>sourceBasket - the basket to copy the data from</dd>
    <dd>basket - the created basket</dd>
    <dd>basketReferenceRequest - the basket reference input document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.reference.beforePOST**

`POST /baskets/reference`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (sourceBasket : <i>dw.order.Basket</i>, request : <i>BasketReference</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>sourceBasket - the basket to copy the data from</dd>
    <dd>basketReferenceRequest - the basket reference input document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.reference.modifyPOSTResponse**

`POST /baskets/reference`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, basketReferenceRequest : <i>BasketReference</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the created basket</dd>
    <dd>basketResponse - the basket response object</dd>
    <dd>basketReferenceRequest - the basket reference input document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.afterDELETE**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (basket : <i>dw.order.Basket</i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Called after the basket's shipment was removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket that was updated</dd>
    <dd>shipmentId - the id of the deleted shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.afterPATCH**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shipmentInfo : <i>Shipment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after patching of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment was changed</dd>
    <dd>shipment - the shipment that has been updated</dd>
    <dd>shipmentInfo - the shipment information for the shipment update</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.afterPOST**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (basket : <i>dw.order.Basket</i>, shipment : <i>Shipment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the creation of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment was created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.beforeDELETE**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Called before the basket's shipment is removed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket to be updated</dd>
    <dd>shipment - the shipment to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.beforePATCH**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shipmentInfo : <i>Shipment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before changing of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment will be updated</dd>
    <dd>shipment - the current shipment to be updated</dd>
    <dd>shipmentInfo - the shipment information for the shipment update (update data)</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.beforePOST**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>, shipment : <i>Shipment</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the creation of a shipment for a basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the shipment will be created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.modifyDELETEResponse**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shipmentId - shipment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.modifyPATCHResponse**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shipmentId - shipment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.modifyPOSTResponse**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, shipmentRequest : <i>Shipment</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shipmentRequest - shipment request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_address.afterPUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingAddress : <i>OrderAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of the shipping address to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingAddress - the shipping address that was set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_address.beforePUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingAddress : <i>OrderAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of the shipping address to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingAddress - the shipping address to be set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_address.modifyPUTResponse**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, orderAddressRequest : <i>OrderAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>orderAddressRequest - order address request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_method.afterPUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingMethod : <i>ShippingMethod</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after setting of the shipping method to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingMethod - the shipping method that was set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_method.beforePUT**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basket : <i>dw.order.Basket</i>, shipment : <i>dw.order.Shipment</i>, shippingMethod : <i>ShippingMethod</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before setting of the shipping method to a certain shipment of the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
    <dd>shipment - the shipment information for the shipment creation</dd>
    <dd>shippingMethod - the shipping method to be set to the shipment</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipment.shipping_method.modifyPUTResponse**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>, shippingMethodRequest : <i>ShippingMethod</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
    <dd>shippingMethodRequest - shipping method request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipments.shipping_methods.beforeGET**

`GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (basketId : <i>String</i>, shipmentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketId - the target basket id</dd>
    <dd>shipmentId - the shipment id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.shipments.shipping_methods.modifyGETResponse_v2**

`GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (shipment : <i>dw.order.Shipment</i>, shippingMethodResult : <i>ShippingMethodResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>shipment - the shipment the shipping methods result retrieved for.</dd>
    <dd>shippingMethodResult - shipping method result object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.storefront.afterPUT**

`PUT /baskets/{basket_id}/storefront`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a put of a basket as storefront basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.storefront.beforePUT**

`PUT /baskets/{basket_id}/storefront`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (basketId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.storefront.modifyPUTResponse**

`PUT /baskets/{basket_id}/storefront`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (basket : <i>dw.order.Basket</i>, basketResponse : <i>Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the target basket</dd>
    <dd>basketResponse - basket response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`GET /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/coupons`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/gift_certificate_items`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PATCH /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/price_adjustments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /baskets/{basket_id}/shipments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/billing_address`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/customer`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.basket.validateBasket**

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

<details>  
<summary>Method details</summary>

<p>
  <b>validateBasket</b> (basketResponse : <i>Basket</i>, duringSubmit : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows the addition of custom flashes or removal of internal flashes. The presence of a flash indicates that the basket cannot yet be submitted. Parameter <code>duringSubmit</code> indicates the current call is during the basket submit process. Default implementation returns ERROR if duringSubmit and any flash exists.
</p>
<p>
  Example showing addition, listing, and removal of flashes: 
</p>
<div>

```javascript
exports.validateBasket = function(basketResponse, duringSubmit) {
  basketResponse.addFlash({
    type: "MyType",
    message: "My message",
    path: "my_path",
    details: {
      "k1": "v1",
      "k2": "v2"
    }
  });
  var flashToRemove;
  for each(f in basketResponse.flashes) {
    if (f.type == "SomeOtherType") {
      flashToRemove = f;
    }
  }
  if (flashToRemove != null) {
    basketResponse.removeFlash(flashToRemove);
  }
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basketResponse - the basket response to be validated, before any OCAPI property selection is applied</dd>
    <dd>duringSubmit - should the basket be checked for submit</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Category

Category hooks for Shop API.

---

**dw.ocapi.shop.category.beforeGET**

`GET /categories/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (categoryId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>categoryId - the id of the category</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.category.beforeGET**

`GET /categories/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (categoryId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>categoryId - the id of the category</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.category.modifyGETResponse**

`GET /categories/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptCategory : <i>dw.catalog.Category</i>, doc : <i>Category</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptCategory - an instance of dw.catalog.Category</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.category.modifyGETResponse**

`GET /categories/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptCategory : <i>dw.catalog.Category</i>, doc : <i>Category</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptCategory - an instance of dw.catalog.Category</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Content

Content hooks for Shop API.

---

**dw.ocapi.shop.content.beforeGET**

`GET /content/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (contentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>contentId - the id of the content assert</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.content.beforeGET**

`GET /content/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (contentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>contentId - the id of the content assert</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.content.modifyGETResponse**

`GET /content/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptContent : <i>dw.content.Content</i>, doc : <i>Content</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptContent - an instance of dw.content.Content</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.content.modifyGETResponse**

`GET /content/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptContent : <i>dw.content.Content</i>, doc : <i>Content</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptContent - an instance of dw.content.Content</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Content Search

Content search hooks for Shop API.

---

**dw.ocapi.shop.content_search.beforeGET**

`GET /content_search`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.content_search.modifyGETResponse**

`GET /content_search`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>ContentSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Custom Object

Custom object hooks for Shop API.

---

**dw.ocapi.shop.custom_object.beforeGET**

`GET /custom_objects/{object_type}/{key}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (objectType : <i>String</i>, key : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>objectType - the ID of the object type</dd>
    <dd>key - the key attribute value of the custom object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.custom_object.modifyGETResponse**

`GET /custom_objects/{object_type}/{key}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptCustomObject : <i>dw.object.CustomObject</i>, doc : <i>CustomObject</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptCustomObject - an instance of dw.object.CustomObject</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer

Customer hooks for Shop API.

---

**dw.ocapi.shop.customer.afterPATCH**

`PATCH /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, customerInput : <i>Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a customer was updated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer to be updated</dd>
    <dd>customerInput - the input customer containing the patch changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.afterPOST**

`POST /customers`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, registration : <i>CustomerRegistration</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a new customer registration. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the registered customer</dd>
    <dd>registration - the customer registration information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.auth.afterPOST**

`POST /customers/{customer_id}/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer that is authenticated</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.auth.beforePOST**

`POST /customers/{customer_id}/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the customer has been authenticated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer that is authenticated</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.auth.modifyPOSTResponse**

`POST /customers/{customer_id}/auth`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i>Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.baskets.beforeGET**

`GET /customers/{customer_id}/baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the baskets result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.baskets.modifyGETResponse_v2**

`GET /customers/{customer_id}/baskets`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, customerBasketsResultResponse : <i>BasketsResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the baskets result retrieved for.</dd>
    <dd>customerBasketsResultResponse - customer basket result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.beforeGET**

`GET /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - The customer id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.beforePATCH**

`PATCH /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, customerInput : <i>Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a customer is updated. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer to be updated</dd>
    <dd>customerInput - the input customer containing the patch changes</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.beforePOST**

`POST /customers`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (registration : <i>CustomerRegistration</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a new customer registration. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>registration - the customer registration information</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.modifyGETResponse**

`GET /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i>Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.modifyPATCHResponse**

`PATCH /customers/{customer_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i>Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.modifyPOSTResponse**

`POST /customers`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerResponse : <i>Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - created customer</dd>
    <dd>customerResponse - customer response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.orders.beforeGET**

`GET /customers/{customer_id}/orders`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the orders are retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.orders.modifyGETResponse_v2**

`GET /customers/{customer_id}/orders`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, customerOrderResultResponse : <i>CustomerOrderResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the orders are retrieved for.</dd>
    <dd>customerOrderResultResponse - customer order result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.password_reset.afterPOST**

`POST /customers/{customer_id}/password_reset`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, resetToken : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows resetting a customer password. See the example below sending an email with a password reset link.
</p>

<div>

```javascript
var variables: Map = new dw.util.HashMap();
variables.put("Customer", customer);
variables.put("ResetPasswordToken", token);
var template: Template = new dw.util.Template("mail/resetpasswordemail.isml");
var content: MimeEncodedText = template.render(variables);
var mail: Mail = new Mail()
  .setSubject("Password Reset")
  .setContent(content)
  .setFrom("noreply@salesforce.com")
  .addTo(customer.profile.email);
mail.send();
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to reset the password</dd>
    <dd>resetToken - the token generated by the system to be used for the reset</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.password_reset.beforePOST**

`POST /customers/{customer_id}/password_reset`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to reset the password</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.afterDELETE**

`DELETE /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a payment instrument of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to delete the payment instrument</dd>
    <dd>paymentInstrumentId - the id of the payment instrument that was deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.afterPOST**

`POST /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, paymentInstrument : <i>CustomerPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a payment instrument was added to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to add the payment instrument</dd>
    <dd>paymentInstrument - the payment instrument that was added</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.beforeDELETE**

`DELETE /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a payment instrument of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to delete the payment instrument</dd>
    <dd>paymentInstrumentId - the id of the payment instrument to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.beforeGET**

`GET /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - target customer id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.beforePOST**

`POST /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, paymentInstrument : <i>CustomerPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a payment instrument is added to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to add the payment instrument</dd>
    <dd>paymentInstrument - the payment instrument to be added</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.modifyGETResponse**

`GET /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, customerPaymentInstrument : <i>dw.customer.CustomerPaymentInstrument</i>, customerPaymentInstrumentResponse : <i>CustomerPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerPaymentInstrument - payment instrument</dd>
    <dd>customerPaymentInstrumentResponse - customer payment instrument response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instrument.modifyPOSTResponse**

`POST /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerPaymentInstrument : <i>dw.customer.CustomerPaymentInstrument</i>, customerPaymentInstrumentResponse : <i>CustomerPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>Customer - target customer</dd>
    <dd>customerPaymentInstrument - payment instrument</dd>
    <dd>customerPaymentInstrumentResponse - customer payment instrument response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instruments.beforeGET**

`GET /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, paymentMethodId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the customer payment instruments result retrieved for.</dd>
    <dd>paymentMethodId - the id of the payment method, if null - all payment instruments are retrieved</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.payment_instruments.modifyGETResponse_v2**

`GET /customers/{customer_id}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, customerPaymentInstrumentResultResponse : <i>CustomerPaymentInstrumentResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the customer payment instruments result retrieved for.</dd>
    <dd>customerPaymentInstrumentResultResponse - customer payment instrument result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.afterDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, productListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a customer product list is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productListId - the product list id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.afterPATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>CustomerProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after modifying a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.beforeDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a customer product list is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, productListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - The customer id.</dd>
    <dd>productListId - The product list id.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.beforePATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>CustomerProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before modifying a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.afterDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, itemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after deleting an item from a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>itemId - the id of the deleted item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.afterPATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i>CustomerProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating an item of a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the updated item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.beforeDELETE**

`DELETE /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i>dw.customer.ProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before deleting an item from a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the product list item to delete</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, productListId : <i>String</i>, productListItemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - target customer id</dd>
    <dd>productListId - the customers product list id the product list item purchase result retrieved for.</dd>
    <dd>productListItemId - the product list id item the product list item purchase result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.beforePATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i>CustomerProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating an item of a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the product list item to update</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.modifyGETResponse**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, productListItem : <i>dw.customer.ProductListItem</i>, customerProductListItemResponse : <i>CustomerProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productListItem - target product list item</dd>
    <dd>customerProductListItemResponse - customer product list item response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.modifyPATCHResponse**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListItemResponse : <i>CustomerProductListItem</i>, customerProductListItemRequest : <i>CustomerProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListItemRequest - customer product list item request object</dd>
    <dd>customerProductListItemResponse - customer product list item response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.modifyPOSTResponse**

`POST /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListItemResponse : <i>CustomerProductListItem</i>, customerProductListItemRequest : <i>CustomerProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListItemResponse - customer product list item response object</dd>
    <dd>customerProductListItemRequest - customer product list item request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchase.afterPATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, purchase : <i>CustomerProductListItemPurchase</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating a purchase of a customer product list item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>productListItem - the product list item</dd>
    <dd>purchase - the updated purchase</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchase.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - target customer id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchase.beforePATCH**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, purchase : <i>CustomerProductListItemPurchase</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a purchase of a customer product list item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>productListItem - the product list item</dd>
    <dd>purchase - the product list item purchase to update</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchase.modifyGETResponse**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, productListItemPurchase : <i>dw.customer.ProductListItemPurchase</i>, customerProductListItemPurchaseResponse : <i>CustomerProductListItemPurchase</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productListItemPurchase - target product list item purchase</dd>
    <dd>customerProductListItemPurchaseResponse - customer product list item purchase response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchase.modifyPATCHResponse**

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, customerProductListItemPurchaseResponse : <i>CustomerProductListItemPurchase</i>, customerProductListItemPurchaseRequest : <i>CustomerProductListItemPurchase</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>productListItem - target product list item</dd>
    <dd>customerProductListItemPurchaseRequest - customer product list item purchase request object</dd>
    <dd>customerProductListItemPurchaseResponse - customer product list item purchase response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchases.afterPOST**

`POST /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, purchase : <i>CustomerProductListItemPurchase</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding a purchase to a customer product list item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>productListItem - the product list item</dd>
    <dd>purchase - the item added to the customer product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchases.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, listId : <i>String</i>, itemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the product list item purchase result retrieved for.</dd>
    <dd>listId - the customers product list id the product list item purchase result retrieved for.</dd>
    <dd>itemId - the product list id item the product list item purchase result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchases.beforePOST**

`POST /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, purchase : <i>CustomerProductListItemPurchase</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding a purchase to a customer product list item. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>productListItem - the product list item</dd>
    <dd>purchase - the purchase to add to the customer product list item</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchases.modifyGETResponse_v2**

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, customerProductListItemPurchaseResultResponse : <i>CustomerProductListItemPurchaseResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the product list item purchase result retrieved for.</dd>
    <dd>productList - the customers product list the product list item purchase result retrieved for.</dd>
    <dd>productListItem - the product list item the product list item purchase result retrieved for.</dd>
    <dd>customerProductListItemPurchaseResultResponse - customer product list item purchase result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.item.purchases.modifyPOSTResponse**

`POST /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, customerProductListItemPurchaseResponse : <i>CustomerProductListItemPurchase</i>, customerProductListItemPurchaseRequest : <i>CustomerProductListItemPurchase</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>productListItem - target product list item</dd>
    <dd>customerProductListItemPurchaseResponse - customer product list item purchase response object</dd>
    <dd>customerProductListItemPurchaseRequest - customer product list item purchase request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.afterPOST**

`POST /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i>CustomerProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding an item to a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the item added to the customer product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.beforeGET**

`GET /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, productListId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the customer product list items result retrieved for.</dd>
    <dd>productListId - the product list id the customer product list items result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.beforePOST**

`POST /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, item : <i>CustomerProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding an item to a customer product list. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list</dd>
    <dd>item - the item to add to the customer product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.items.modifyGETResponse_v2**

`GET /customers/{customer_id}/product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListItemResultResponse : <i>CustomerProductListItemResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the customer product list items result retrieved for.</dd>
    <dd>productList - the product list the customer product list items result retrieved for.</dd>
    <dd>customerProductListItemResultResponse - customer product list item result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.modifyGETResponse**

`GET /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListResponse : <i>CustomerProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListResponse - customer product list response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.modifyPATCHResponse**

`PATCH /customers/{customer_id}/product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListResponse : <i>CustomerProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - target product list</dd>
    <dd>customerProductListResponse - customer product list response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_list.modifyPOSTResponse**

`POST /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, productList : <i>dw.customer.ProductList</i>, customerProductListResponse : <i>CustomerProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>productList - product list</dd>
    <dd>customerProductListResponse - customer product list response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.afterPOST**

`POST /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>CustomerProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after creating a new product list for the specified customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the created product list</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.beforeGET**

`GET /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id the customer product lists result retrieved for.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.beforePOST**

`POST /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, productList : <i>CustomerProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before creating a new product list for the specified customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer</dd>
    <dd>productList - the product list to create</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.product_lists.modifyGETResponse_v3**

`GET /customers/{customer_id}/product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v3</b> (customer : <i>dw.customer.Customer</i>, customerProductListResultResponse : <i>CustomerProductListResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer the customer product lists result retrieved for.</dd>
    <dd>customerProductListResultResponse - customer product list pageable result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customers

Customers hooks for Shop API.

---

**dw.ocapi.shop.customers.password_reset.afterPOST**

`POST /customers/password_reset`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, resetToken : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows resetting a customer's password. See the example below sending an email with a password reset link.
</p>
<div>

```javascript
var variables: Map = new dw.util.HashMap();
variables.put("Customer", customer);
variables.put("ResetPasswordToken", token);
var template: Template = new dw.util.Template("mail/resetpasswordemail.isml");
var content: MimeEncodedText = template.render(variables);
var mail: Mail = new Mail()
  .setSubject("Password Reset")
  .setContent(content)
  .setFrom("noreply@salesforce.com")
  .addTo(customer.profile.email);
mail.send();
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to reset the password</dd>
    <dd>resetToken - the token generated by the system to be used for the reset</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customers.password_reset.beforePOST**

`POST /customers/password_reset`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (passwordReset : <i>PasswordReset</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Allows resetting a customer's password. The validation of the customer information provided in the the password reset document is done after this hook is called. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer Address

Customer address hooks for Shop API.

---

**dw.ocapi.shop.customer.address.afterDELETE**

`DELETE /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was deleted</dd>
    <dd>addressName - the name of the address that was deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.afterPATCH**

`PATCH /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i>CustomerAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was updated</dd>
    <dd>addressName - the name of the address that was updated</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.beforeDELETE**

`DELETE /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to delete the address</dd>
    <dd>addressName - the name of the address to be deleted</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.beforeGET**

`GET /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>, addressName : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerAddress - target customer address</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.beforePATCH**

`PATCH /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i>CustomerAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating an address of a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to update the address</dd>
    <dd>addressName - the name of the address to be updated</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.modifyGETResponse**

`GET /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, customerAddressResponse : <i>CustomerAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - target customer</dd>
    <dd>customerAddress - target customer address</dd>
    <dd>customerAddressResponse - customer address response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.modifyPATCHResponse**

`PATCH /customers/{customer_id}/addresses/{address_name}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, customerAddressResponse : <i>CustomerAddress</i>, customerAddressRequest : <i>CustomerAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerAddress - target customer address</dd>
    <dd>customerAddressResponse - customer address response object</dd>
    <dd>customerAddressRequest - customer address request object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.address.modifyPOSTResponse**

`POST /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (customer : <i>dw.customer.Customer</i>, customerAddress : <i>dw.customer.CustomerAddress</i>, customerAddressResponse : <i>CustomerAddress</i>, customerAddressRequest : <i>CustomerAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before returning response. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was added.</dd>
    <dd>customerAddress - created customer address</dd>
    <dd>customerAddressResponse - customer address response object.</dd>
    <dd>customerAddressRequest - the customer address request object.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Customer Addresses

Customer addresses hooks for Shop API.

---

**dw.ocapi.shop.customer.addresses.afterPOST**

`POST /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i>CustomerAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after adding an address to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom the address was added</dd>
    <dd>addressName - the name of the address that was added</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.addresses.beforeGET**

`GET /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (customerId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerId - the customer id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.addresses.beforePOST**

`POST /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (customer : <i>dw.customer.Customer</i>, addressName : <i>String</i>, customerAddress : <i>CustomerAddress</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before adding an address to a customer. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customer - the customer for whom to add the address</dd>
    <dd>addressName - the name of the address to be added</dd>
    <dd>customerAddress - the customer address request data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.customer.addresses.modifyGETResponse**

`GET /customers/{customer_id}/addresses`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (customerAddressResultResponse : <i>CustomerAddressResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>customerAddressResultResponse - customer addresses result response</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Folder

Folder hooks for Shop API.

---

**dw.ocapi.shop.folder.beforeGET**

`GET /folders/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (id : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>id - The id of the requested content folder.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.folder.beforeGET**

`GET /folders/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (id : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>id - The id of the requested content folder.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.folder.modifyGETResponse**

`GET /folders/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptFolder : <i>dw.content.Folder</i>, doc : <i>ContentFolder</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptFolder - an instance of dw.content.Folder</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.folder.modifyGETResponse**

`GET /folders/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptFolder : <i>dw.content.Folder</i>, doc : <i>ContentFolder</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptFolder - an instance of dw.content.Folder</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Gift Certificate

Gift certificate hooks for version 24.5.

**dw.ocapi.shop.gift_certificate.beforePOST**

`POST /gift_certificate`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (giftCertificateRequest : <i>GiftCertificateRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>giftCertificateRequest - The request containing the gift certificate code.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.gift_certificate.modifyPOSTResponse**

`POST /gift_certificate`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (giftCertificate : <i>dw.order.GiftCertificate</i>, giftCertificateResponse : <i>GiftCertificate</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>giftCertificate - the target gift certificate</dd>
    <dd>giftCertificateResponse - gift certificate response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order

Order hooks for Shop API.

---

**dw.ocapi.shop.order.afterPATCH**

`PATCH /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (order : <i>dw.order.Order</i>, orderInput : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after an order was patched. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order that was changed</dd>
    <dd>orderInput - the input data from the REST call</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.afterPOST**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (order : <i>dw.order.Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after an order was created from the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order that was created for the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.afterPUT**

`PUT /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPUT</b> (order : <i>dw.order.Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after an order is created for the basket with the caller supplying the order number. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order that was created for the basket</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.beforeGET**

`GET /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (orderNo : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderNo - the order number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.beforePATCH**

`PATCH /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (order : <i>dw.order.Order</i>, orderInput : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before an order is patched. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order that will be changed</dd>
    <dd>orderInput - the input data from the REST call</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.beforePOST**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (basket : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before an order is created for the basket. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.beforePUT**

`PUT /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePUT</b> (ctor : <i>dw.order.Basket</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before an order is created for the basket with the caller supplying the order number. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>basket - the basket based on which the order is created</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.modifyGETResponse**

`GET /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.modifyPATCHResponse**

`PATCH /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.modifyPOSTResponse**

`POST /orders`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.modifyPUTResponse**

`PUT /orders/{order_no}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPUTResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Payment

Order payment hooks for Shop API.

---

**dw.order.payment.authorize**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>authorize</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.order.payment.authorize**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>authorize</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.order.payment.authorizeCreditCard**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>authorizeCreditCard</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>, cvn : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization of a credit card - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
    <dd>cvn - the credit card verification number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.order.payment.authorizeCreditCard**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>authorizeCreditCard</b> (order : <i>dw.order.Order</i>, paymentDetails : <i>dw.order.OrderPaymentInstrument</i>, cvn : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Custom payment authorization of a credit card - modify the order as needed. 
  <ul>
    <li>Prerequisite: An order has been created using the data api or via the storefront.</li>
    <li>Return Status.OK: Corresponding payment transaction is marked as authorized (usually a custom property is used for this).</li>
    <li>Return Status.ERROR: Order is held, authorization needs to be repeated.</li>
  </ul>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>paymentDetails - specified payment details</dd>
    <dd>cvn - the credit card verification number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd> 
      <ul>
        <li>Status.OK successful authorization.</li>
        <li>Status.ERROR authorization failed.</li>
      </ul>
    </dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.validateOrder**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateOrder</b> (order : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes:
</p>
<div>
  
```javascript
exports.validateBasket = function() {
  order.addFlash({
    type: "PaymentAuthorizationFailure",
    message: "Order was not successfully authorized.",
    path: "authorizations",
    details: {
      "result": "reject",
      "reason": "invalid_credit_card"
    }
  });
}
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.validateOrder**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>validateOrder</b> (order : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes:
</p>
<div>

```javascript
exports.validateBasket = function () {
  order.addFlash({
    type: "PaymentAuthorizationFailure",
    message: "Order was not successfully authorized.",
    path: "authorizations",
    details: {
      result: "reject",
      reason: "invalid_credit_card",
    },
  });
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.validateOrder**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>validateOrder</b> (order : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
  Validate an order after the order has been updated. The hook is called outside a database transaction, so modifications to the order are not possible. Allows the addition of custom flashes to convey information to the client. Example showing addition of flashes:
</p>
<div>

```javascript
exports.validateBasket = function () {
  order.addFlash({
    type: "PaymentAuthorizationFailure",
    message: "Order was not successfully authorized.",
    path: "authorizations",
    details: {
      result: "reject",
      reason: "invalid_credit_card",
    },
  });
};
```

</div>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Note

Order note hooks for Shop API.

---

**dw.ocapi.shop.order.note.afterDELETE**

`DELETE /orders/{order_no}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (order : <i>dw.order.Order</i>, note : <i>dw.object.Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a note is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>note - the note to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.note.beforeDELETE**

`DELETE /orders/{order_no}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (order : <i>dw.order.Order</i>, note : <i>dw.object.Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a note is deleted. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order</dd>
    <dd>note - the note to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.note.beforePOST**

`POST /orders/{order_no}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (orderNo : <i>String</i>, note : <i>Note</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderNo - The id of the order from which you want to retrieve notes.</dd>
    <dd>note - The note to be added.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.note.modifyDELETEResponse**

`DELETE /orders/{order_no}/notes/{note_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>, noteId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
    <dd>noteId - note id to delete</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.note.modifyPOSTResponse**

`POST /orders/{order_no}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Notes

Order notes hooks for Shop API.

---

**dw.ocapi.shop.order.notes.beforeGET**

`GET /orders/{order_no}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (orderNo : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderNo - The id of the order from which you want to retrieve notes.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.notes.modifyGETResponse_v2**

`GET /orders/{order_no}/notes`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (order : <i>dw.order.Order</i>, notesResultResponse : <i>NotesResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order the notes result retrieved for.</dd>
    <dd>notesResultResponse - notes result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Payment Instruments

Order payment instruments hooks for Shop API.

---

**dw.ocapi.shop.order.payment_instrument.afterDELETE**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterDELETE</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after removing a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the removed payment instrument</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.afterPATCH**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPATCH</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, newPaymentInstrument : <i>OrderPaymentInstrumentRequest</i>, successfullyAuthorized : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after updating a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the updated payment instrument</dd>
    <dd>newPaymentInstrument - the new payment instrument data</dd>
    <dd>successfullyAuthorized - was the payment instrument successfully authorized.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.afterPOST**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>afterPOST</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>OrderPaymentInstrumentRequest</i>, successfullyAuthorized : <i>boolean</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after a payment instrument was added to the order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument that was added to the order</dd>
    <dd>successfullyAuthorized - was the payment instrument successfully authorized.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.beforeDELETE**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeDELETE</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before removing a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument to be removed</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.beforePATCH**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePATCH</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>dw.order.OrderPaymentInstrument</i>, newPaymentInstrument : <i>OrderPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before updating a payment instrument of an order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument to be updated</dd>
    <dd>newPaymentInstrument - the new payment instrument data</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.beforePOST**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>beforePOST</b> (order : <i>dw.order.Order</i>, paymentInstrument : <i>OrderPaymentInstrumentRequest</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before a payment instrument is added to the order. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the modified order</dd>
    <dd>paymentInstrument - the payment instrument to be added to the order</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.modifyDELETEResponse**

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyDELETEResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
    <dd>paymentInstrumentId - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.modifyPATCHResponse**

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPATCHResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>, paymentInstrumentId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
    <dd>paymentInstrumentId - payment instrument id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_instrument.modifyPOSTResponse**

`POST /orders/{order_no}/payment_instruments`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (order : <i>dw.order.Order</i>, orderResponse : <i>Order</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - target order</dd>
    <dd>orderResponse - order response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Payment Methods

Order payment methods hooks for Shop API.

---

**dw.ocapi.shop.order.payment_methods.beforeGET**

`GET /orders/{order_no}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (orderNumber : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderNumber - the order number</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.order.payment_methods.modifyGETResponse_v2**

`GET /orders/{order_no}/payment_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (order : <i>dw.order.Order</i>, paymentMethodResultResponse : <i>PaymentMethodResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>order - the order the payment method result retrieved for.</dd>
    <dd>paymentMethodResultResponse - payment method result response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Order Search

Order search hooks for Shop API.

---

**dw.ocapi.shop.order_search.modifyPOSTResponse**

`POST /order_search`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyPOSTResponse</b> (orderSearchResultResponse : <i>OrderSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>orderSearchResultResponse - order search result response object.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Price Adjustment Limits Hooks

Price adjustment limits hooks for Shop API.

---

**dw.ocapi.shop.price_adjustment_limits.beforeGET**

`GET /price_adjustment_limits`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.price_adjustment_limits.modifyGETResponse**

`GET /price_adjustment_limits`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (priceAdjLimitResponse : <i>PriceAdjustmentLimits</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>priceAdjLimitResponse - the PriceAdjustmentLimit response object</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Product

Product hooks for Shop API.

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/availability`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/bundled_products`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/images`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/links`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/options`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/prices`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/promotions`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/recommendations`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/set_products`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.beforeGET**

`GET /products/{id}/variations`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the incoming product id from the URL.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/availability`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/bundled_products`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/images`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/links`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/options`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/prices`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/promotions`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/recommendations`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/set_products`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.modifyGETResponse**

`GET /products/{id}/variations`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptProduct : <i>dw.catalog.Product</i>, doc : <i>Product</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
    <dd>scriptProduct - an instance of dw.catalog.Product</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Product Shipping

Product shipping hooks for Shop API.

---

**dw.ocapi.shop.product.shipping_methods.beforeGET**

`GET /products/{id}/shipping_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (productId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productId - the requested product id</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product.shipping_methods.modifyGETResponse_v2**

`GET /products/{id}/shipping_methods`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (product : <i>dw.catalog.Product</i>, shippingMethodResultResponse : <i>ShippingMethodResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>product - the product the shipping methods result retrieved for.</dd>
    <dd>shippingMethodResultResponse - shipping method result response</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Product List

Product list hooks for Shop API.

---

**dw.ocapi.shop.product_list.beforeGET**

`GET /product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (listId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>listId - The id of the list.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_list.item.beforeGET**

`GET /product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (listId : <i>String</i>, itemId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>listId - The id of the list.</dd>
    <dd>itemId - The id of the item.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_list.item.modifyGETResponse**

`GET /product_lists/{list_id}/items/{item_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (productList : <i>dw.customer.ProductList</i>, productListItem : <i>dw.customer.ProductListItem</i>, publicProductListItemResponse : <i>PublicProductListItem</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productList - product list.</dd>
    <dd>productListItem - product list item.</dd>
    <dd>publicProductListItemResponse - public product list item response object.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_list.items.beforeGET**

`GET /product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (listId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>listId - The id of the list.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_list.items.modifyGETResponse**

`GET /product_lists/{list_id}/items`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse_v2</b> (productList : <i>dw.customer.ProductList</i>, publicProductListItemResultResponse : <i>PublicProductListItemResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productList - the product list the items are retrieved for.</dd>
    <dd>publicProductListItemResultResponse - public product list item result response object.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_list.modifyGETResponse**

`GET /product_lists/{list_id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (productList : <i>dw.customer.ProductList</i>, publicProductListResponse : <i>PublicProductList</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>productList - product list.</dd>
    <dd>publicProductListResponse - public product list response object.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Product Lists

Product lists hooks for Shop API.

---

**dw.ocapi.shop.product_lists.beforeGET**

`GET /product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (email : <i>String</i>, firstName : <i>String</i>, lastName : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>email - The email address of the customer, the product lists belong to.</dd>
    <dd>firstName - The first name of the customer, the product lists belong to.</dd>
    <dd>lastName - The last name of the customer, the product lists belong to.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_lists.modifyGETResponse**

`GET /product_lists`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (publicProductListResultResponse : <i>PublicProductListResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>publicProductListResultResponse - public product list result response object.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Product Search

Product search hooks for Shop API.

---

**dw.ocapi.shop.product_search.beforeGET**

`GET /product_search`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.beforeGET**

`GET /product_search/availability`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.beforeGET**

`GET /product_search/images`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.beforeGET**

`GET /product_search/prices`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.beforeGET**

`GET /product_search/represented_products`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.beforeGET**

`GET /product_search/variations`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.modifyGETResponse**

`GET /product_search`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>ProductSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.modifyGETResponse**

`GET /product_search/availability`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>ProductSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.modifyGETResponse**

`GET /product_search/images`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>ProductSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.modifyGETResponse**

`GET /product_search/prices`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>ProductSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.modifyGETResponse**

`GET /product_search/represented_products`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>ProductSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.product_search.modifyGETResponse**

`GET /product_search/variations`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>ProductSearchResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Promotion

Promotion hooks for Shop API.

---

**dw.ocapi.shop.promotion.beforeGET**

`GET /promotions/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (id : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>id - The id of the requested promotion.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.promotion.beforeGET**

`GET /promotions/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (id : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>id - The id of the requested promotion.</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.promotion.modifyGETResponse**

`GET /promotions/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptPromotion : <i>dw.campaign.Promotion</i>, doc : <i>Promotion</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptPromotion - an instance of dw.campaign.Promotion</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.promotion.modifyGETResponse**

`GET /promotions/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptPromotion : <i>dw.campaign.Promotion</i>, doc : <i>Promotion</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptPromotion - an instance of dw.campaign.Promotion</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Promotions

Promotions hooks for Shop API.

---

**dw.ocapi.shop.promotions.beforeGET**

`GET /promotions`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (campaignId : <i>String</i>, startDate : <i>String</i>, endDate : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>campaignId - Find the promotions assigned to this campaign (mandatory)</dd>
    <dd>startDate - The start date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ</dd>
    <dd>endDate - The end date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.promotions.modifyGETResponse**

`GET /promotions`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>PromotionResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Search Suggestions

Search suggestions hooks for Shop API.

---

**dw.ocapi.shop.search_suggestion.beforeGET**

`GET /search_suggestion`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> () : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.search_suggestion.modifyGETResponse**

`GET /search_suggestion`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>SuggestionResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Site

Site hooks for Shop API.

---

**dw.ocapi.shop.site.beforeGET**

`GET /site`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (siteId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.site.modifyGETResponse**

`GET /site`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>Site</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Store

Store hooks for Shop API.

---

**dw.ocapi.shop.store.beforeGET**

`GET /stores/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (id : <i>String</i>, siteId : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>id - The id of the requested store.</dd>
    <dd>siteId - The ID of the site to get the store from</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.store.modifyGETResponse**

`GET /stores/({id},...,{id})`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptStore : <i>dw.catalog.Store</i>, doc : <i>Store</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptStore - an instance of dw.catalog.Store</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.store.modifyGETResponse**

`GET /stores/{id}`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (scriptStore : <i>dw.catalog.Store</i>, doc : <i>Store</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>scriptStore - an instance of dw.catalog.Store</dd>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

## Stores

Stores hooks for Shop API.

---

**dw.ocapi.shop.stores.beforeGET**

`GET /stores`

<details>  
<summary>Method details</summary>

<p>
  <b>beforeGET</b> (latitude : <i>Double</i>, longitude : <i>Double</i>, countryCode : <i>String</i>, postalCode : <i>String</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called before the request will be processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>latitude - The geo coordinate latitude to search for stores (value range -90.00 .. 90.00).</dd>
    <dd>longitude - The geo coordinate longitude to search for stores (value range -180.00 .. 180.00).</dd>
    <dd>countryCode - The two letter ISO country code e.g. "US".</dd>
    <dd>postalCode - The postal code e.g. "01801".</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

**dw.ocapi.shop.stores.modifyGETResponse**

`GET /stores`

<details>  
<summary>Method details</summary>

<p>
  <b>modifyGETResponse</b> (doc : <i>StoreResult</i>) : <i>dw.system.Status</i> 
</p>
<p>
  The function is called after the request has been processed. 
</p>
<div>
  <dl> 
    <dt><b>Parameters:</b></dt>
    <dd>doc - the document</dd>
  </dl>
  <dl> 
    <dt><b>Returns:</b></dt>
    <dd>a non-null Status ends the hook execution</dd>
  </dl>
</div>
</details>

---

<!-- document id=87fb5da179bffd398a83afcaa7ca09342aff11e067f11dafc386c72c1165264e url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/httpmethods.md -->

# OCAPI HTTP Methods

A key characteristic of a RESTful Web API is the explicit use of HTTP methods, as defined by RFC 2616. The Open Commerce API supports these methods, as described in the following sections.

## GET

The GET method retrieves resources on the server. The GET method is a _safe method,_ which means that it should never change the state of the server or have side effects. Consequently, a GET request never initiates transactions on the server.

A typical GET request and its response look like this:

```txt
REQUEST:
GET /dw/shop/v24_5/products/123 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8

{"sku":"123","name":"foo","brand":"bar","online":true}

```

This sample shows a typical GET request retrieving a `Product` resource using the `Identifier` "123". The response has HTTP status code 200, which indicates the resource was found and is contained in response body. The response contains the "Content-Type" header, which is set to "application/json" plus the charset definition ("UTF-8").

## DELETE

The DELETE method removes one or more resources on the server. DELETE is an _idempotent_ method, which means repeating a request always results in the same server state as making the request once. The server returns HTTP status code 204 (NO CONTENT) if the resource has been deleted or 404 (NOT FOUND) if the resource doesn’t exist (anymore).

The following example shows how to remove a resource that is addressed by an `Identifier` in the URL:

```txt
REQUEST:
DELETE /dw/shop/v24_5/baskets/12345abcdfe12345 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 204 NO CONTENT
Content-Length: 0

```

The request is similar to the previous GET request, except the HTTP method changed. The response status code is 204, which means the server successfully fulfilled the request but returned no content.

## PUT (Dev and Sandbox Instances Only)

The PUT method is used to _create_, _update_, or _replace_ a resource. It’s also an _idempotent_ method. If a resource is created, the method returns a 201 status code with a _Location_ header, pointing to the created resource. Otherwise, it returns a 200 status code.

**note:** For security reasons, the HTTP PUT method is blocked from making direct calls against production or staging instances. Instead, use the workaround described in [Override HTTP Method](#override-http-method) to perform a logical PUT call via the POST method. If you make PUT calls in your development or sandbox instance, you can’t use the same code in staging or production.

PUT allows you to create a resource with the identifier specified in the URL. POST, on the other hand, is used when the identifier is provided by the server.

If the resource exists, PUT "cleans" the resource and then applies all the properties specified in the request document. So, unlike PATCH, PUT also touches/cleans properties that aren’t part of the request document. The PUT replace logic touches only the resource itself, not its relations to other resources.

The example shows how to set a billing address on a basket using the PUT method:

```txt
REQUEST:
PUT /dw/shop/v24_5/baskets/cdTwMiWbOhGJgaaadkIKbj5op9/billing_address HTTP/1.1
Host: example.com
Authorization: Bearer af7f5c90-ffc1-4ea4-9613-f5b375b7dc19
Content-Type: application/json
{
  "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
  "first_name":"John",
  "last_name":"Smith",
  "city":"Boston",
  "country_code":"US",
  "c_strValue":"c25"
}

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
   "_v" : "24.5",
   "_resource_state" : "t9ccde3040519cce439cd99e209f8a87c3ad0b7e2"
...
   "billing_address" :
   {
      "_type" : "order_address",
      "city" : "Boston",
      "country_code" : "US",
      "first_name" : "John",
      "full_name" : "John Smith",
      "last_name" : "Smith",
      "c_strValue" : "c25"
   },
...
}
```

## PATCH

The PATCH method allows partial resource modification by sending a delta document. The method is neither _safe_ nor _idempotent._ A PATCH document contains information describing how to modify a server resource to produce a new version; in contrast, a PUT request completely replaces the existing document.

The Open Commerce API uses the PATCH method to provide partial updates. The following table compares PUT and PATCH regarding their create and update behavior:

| Method | Resource doesn’t exist     | Resource exists                                                                                                                               |
| ------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| PUT    | Creates a resource.        | Updates the resource by completely replacing it. UUIDs and relations aren’t touched. Properties that aren’t provided in the request are lost. |
| PATCH  | Doesn’t create a resource. | Updates the resource partially. The server only updates properties that are provided in the request; other properties aren’t touched.         |

The example shows how you can use a PATCH to partially update a baskets resource. The server updates only the properties in the delta document; other properties are untouched:

```txt
REQUEST:
#
# Example: Update Option Value
#
REQUEST:
PATCH /dw/shop/v24_5/baskets/cd6HwiWbLaZuUaaadgtglhMTrG/items/cdheYiWbLasNkaaadgwMthMTrG HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0dxxxxxx.423f234ff24fxxxxx.124f1f133fxxxxx

{
  "_resource_state" : "t9ccde3040519cce439cd99e209f8a87c3ad0b7e2"
  "product_id": "IPad2",
  "quantity": 1,
  "option_items": [
    {
      "option_id": "Warranty",
      "option_value_id": "oneYear"
    }
  ]
}

# Success Response:
RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
   "_v" : "24.5",
   "_resource_state" : "125e1319918776a043fcef2b0e2fce7906abbdea7f5f2f19.10ff0ba0fc46de88"
...
   "basket_id" : "cd6HwiWbLaZuUaaadgtglhMTrG",
   "product_items" : [
      {
...
         "item_text" : "IPad 2",
         "option_items" : [
            {
               "item_text" : "Warranty One Year",
               "option_id" : "Warranty",
               "option_value_id" : "oneYear",
...
            }
         ],
         "product_id" : "IPad2",
         "item_id" : "cdheYiWbLasNkaaadgwMthMTrG"
      }
   ],
   ...
}

```

## POST

The POST method is neither _safe_ (because requests can affect the server state) nor _idempotent_ (because multiple requests potentially return different results).

The Open Commerce API uses POST only for three purposes:

- Create a resource. Unlike PUT, the resource identifier is provided by the server.
- Override an HTTP method; see [Override HTTP method.](#override-http-method)
- Execute special actions that are hard to map to a RESTful request (for example, password reset requests).

## HEAD

The HEAD method is similar to the GET method, but returns headers only, not content (body). The headers are identical to those of the GET request. The HEAD method is a _safe method:_ it doesn’t change the state of the server.

```txt
REQUEST:
HEAD /dw/shop/v24_5/products/123 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 204 NO CONTENT
Content-Length: 67
Content-Type: application/json; charset=UTF-8

```

## OPTIONS

The OPTIONS method lists the supported HTTP methods for the specified URL in the `Allow` header. It isn’t cache-able and returns no content. The OPTIONS method is also a _safe_ method, which means that it will never change the state of the server.

```txt
REQUEST:
OPTIONS /dw/shop/v24_5/products HTTP/1.1
Host: http://example.com

RESPONSE:
HTTP/1.1 204 NO CONTENT
Allow: GET, HEAD, POST

```

## Override HTTP Method

Some web frameworks (for example, AJAX frameworks) only support the HTTP methods GET and POST. The Open Commerce API works around this limitation by supporting POST requests that can override the HTTP method. The methods DELETE, HEAD, OPTIONS, PUT and PATCH are supported override methods.

You can do this by specifying the explicit request/form parameter **method** with the value of the overriding method in upper case. The following example shows how you can simulate a DELETE:

```txt
REQUEST:
POST /dw/shop/v24_5/products/123?method=DELETE HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 204 NO CONTENT

```

Another way you can override the HTTP method is to specify the B2C Commerce Digital HTTP header `x-dw-http-method-override` with the value of the overriding method in upper case. The following example shows how you can simulate a DELETE:

```txt
REQUEST:
POST /dw/shop/v24_5/products/123 HTTP/1.1
Host: example.com
Accept: application/json
x-dw-http-method-override: DELETE

RESPONSE:
HTTP/1.1 204 NO CONTENT

```

**note:** The request parameter has precedence over the header parameter.

## PATCH, POST, PUT With Empty Request Body

Some of the PATCH, POST, and PUT OCAPIs might not require a request body. Making these calls with empty request bodies can cause problems (i.e. HTTP 500 responses) with proxies in between. Please ensure that you provide the `Content-Length` request header with the value '0'.

```txt
REQUEST:
POST /dw/shop/v24_5/sessions HTTP/1.1
Host: example.com
Content-Length: 0

```

<!-- document id=c1d6428c0eb8d24e04bcf1ce9b30df8aac7e8b2eb31ef1c292a60a4ed0ca635e url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/httpstatuscodesandfaults.md -->

# OCAPI HTTP Status Codes and Faults

To help you handle errors and special cases, the Open Commerce API returns HTTP status codes and faults.

## HTTP Status Codes

The following table lists the HTTP status codes and their typical use cases:

| HTTP status code             | Cases                                                                                                                                       |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| 200 (OK)                     | GET, PUT, or POST request successfully completed.                                                                                           |
| 201 (Created)                | POST or PUT request successfully created a resource or relationship resource.                                                               |
| 204 (No Content)             | DELETE, HEAD, or OPTIONS (or less typically a POST, PUT, or PATCH) request successfully completed and returned no content.                  |
| 400 (Bad Request)            | Request contains invalid information, such as malformed parameters, malformed header values, or a malformed body.                           |
| 401 (Unauthorized)           | Request isn’t authorized to be processed.                                                                                                   |
| 403 (Forbidden)              | Request is declined by the server.                                                                                                          |
| 404 (Not Found)              | Requested resource doesn’t exist.                                                                                                           |
| 405 (Method Not Allowed)     | Resource doesn’t support supplied HTTP method.                                                                                              |
| 409 (Conflict)               | The request couldn’t be completed due to a conflict with the current state of the resource.                                                 |
| 412 (Precondition Failed)    | PATCH request provided an outdated last-known base point, which means the resource was changed on server, possibly by a concurrent request. |
| 415 (Unsupported Media Type) | Media type specified in "format" request parameter (or Accept header) isn’t supported.                                                      |
| 500 (Internal Server Error)  | Request can’t be fulfilled because of an unexpected condition on the server.                                                                |

## Fault Document

For status codes greater than or equal to 400, the API returns a fault document:

```json
{
  "fault": {
    "type": "NotFoundException",
    "message": "Unknown resource '/dw/shop/v24_5/incognito'. Please provide a valid resource.",
    "arguments": {
      "path": {
        "type": "string",
        "value": "/dw/shop/v24_5/incognito"
      }
    }
  }
}
```

The fault document contains a _type_ identifier, a readable _message_ and a _arguments_ map listing the values integrated into the message. The _keys_ used in the map follow the sequence '0', '1', '2' unless otherwise specified in the documentation. The value can be `null`. The possible values of the _type_ property are listed below with details of the format used for each value:

| Value type | Value format                                                                                                                                                                                | Example                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `boolean`  | true/false                                                                                                                                                                                  | `{"type":"boolean","value":true}`                             |
| `date`     | String format 'YYYY-mm-DD' where Y=year, m=month, D=day                                                                                                                                     | `{"type":"date","value":"2015-07-01"}`                        |
| `datetime` | String format 'YYYY-mm-DDTHH:MM:SS.mmmZ' where Y=year, m=month, D=day, H=hours, M=minutes, S=seconds, m=millis and Z is timezone, one of 'Z' for UTC or the offset such as +01:00 or -03:00 | `{"type":"datetime","value":"2015-07-01T08:22:15.000+02:00"}` |
| `decimal`  | Numeric decimal                                                                                                                                                                             | `{"type":"decimal","value":256.78}`                           |
| `integer`  | Numeric integer                                                                                                                                                                             | `{"type":"integer","value":141}`                              |
| `string`   | Plain string                                                                                                                                                                                | `{"type":"string","value":"A fox flew"}`                      |
| `time`     | String format 'HH:MM:SS.mmm' where H=hours, M=minutes, S=seconds and m=millis                                                                                                               | `{"type":"time","value":"08:15:24.500"}`                      |

The following sections provide detailed information about faults returned for different HTTP status codes.

## 400 (Bad Request)

| Fault type                                | Sample fault message                                                                                                                                                         |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ConstraintViolationException`            | 'count' value constraint violated. Expected value is between '(1..200)'.                                                                                                     |
| `IllegalHttpMethodOverrideException`      | Only HTTP methods 'PUT', 'PATCH', 'DELETE' can be overwritten.                                                                                                               |
| `InvalidBillingAddressException`          | Invalid billing address.                                                                                                                                                     |
| `InvalidBundledProductItemCountException` | Number of update bundled product items doesn't match number of server bundled product items.                                                                                 |
| `InvalidCouponItemException`              | Coupon code 'SUMMER2012' is invalid.                                                                                                                                         |
| `InvalidCustomerInformationException`     | Invalid customer info 'email' address.                                                                                                                                       |
| `InvalidCustomPropertyException`          | Invalid custom property in request.                                                                                                                                          |
| `InvalidExpandParameterException`         | Invalid expand parameter 'foo' found.                                                                                                                                        |
| `InvalidMessageException`                 | Mandatory attribute 'email' must not be null or empty                                                                                                                        |
| `InvalidOptionItemException`              | Product option 'warranty' isn’t supported.                                                                                                                                   |
| `InvalidPasswordException`                | Password doesn't match acceptance criteria.                                                                                                                                  |
| `InvalidPaymentMethodException`           | Payment method with id 'Paypal' is unknown or not applicable to basket.                                                                                                      |
| `InvalidProductItemException`             | Product '0815' is unknown, offline or not assigned to site catalog.                                                                                                          |
| `InvalidShippingAddressException`         | Invalid shipping address.                                                                                                                                                    |
| `InvalidShippingMethodIdException`        | Shipping method with id 'UPS' is unknown or not applicable to basket.                                                                                                        |
| `InvalidUsernameException`                | Username doesn't match acceptance criteria.                                                                                                                                  |
| `MalformedLocaleException`                | Malformed locale value 'en+US'.                                                                                                                                              |
| `MalformedMediaTypeException`             | Malformed Content-Type 'foo' in header.                                                                                                                                      |
| `MalformedParameterException`             | Malformed value '10p' for parameter 'count'.                                                                                                                                 |
| `MalformedPathVariableException`          | Malformed path variable '(123,456'. The correct syntax for multiple ids is: (id1,id2,id3). If the characters `( ) ,` are part of the id itself, they have to be URL encoded. |
| `MalformedPriceRefinementException`       | Malformed price refinement '(0..5x)'. Expected something like '(0..100)'.                                                                                                    |
| `MalformedSelectorException`              | Malformed property selector '(name,id'.                                                                                                                                      |
| `MissingClientIdException`                | Missing client id.                                                                                                                                                           |
| `MissingParameterException`               | Missing parameter 'campaign_id'.                                                                                                                                             |
| `ProductItemNotAvailableException`        | Product '017845724321' isn’t available for quantity '5'.                                                                                                                     |
| `QuotaExceededException`                  | Maximum number of product items per basket exceeded.                                                                                                                         |
| `UnknownLocaleException`                  | The locale 'foo is unknown.                                                                                                                                                  |
| `UnknownParameterException`               | Unknown parameter 'foo'.                                                                                                                                                     |
| `UnsupportedLocaleException`              | The locale 'de-DE' isn’t supported/activated for this site.                                                                                                                  |
| `UsernameAlreadyInUseException`           | Username is already in use.                                                                                                                                                  |

## 401 (Unauthorized)

| Fault type                    | Sample fault message                                                                                                             |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `InvalidSecureTokenException` | Session may have been hijacked.                                                                                                  |
| `UnauthorizedException`       | Unauthorized request for resource '/s/SiteGenesis/dw/shop/v24_5/basket/this/checkout/submit' from client '[your_own_client_id]'. |
| `UnauthorizedOriginException` | Unauthorized origin 'foo.com' from client '[your_own_client_id]'.                                                                |
| `UnknownClientIdException`    | Unknown client id 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'.                                                                              |

## 403 (Forbidden)

| Fault type                             | Sample fault message                                     |
| -------------------------------------- | -------------------------------------------------------- |
| `SecureCommunicationRequiredException` | Secure communication required.                           |
| `SiteOfflineException`                 | The site 'SiteGenesis' is offline and can't be accessed. |

## 404 (Not Found)

| Fault type                      | Sample fault message                                                                                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `InvalidVersionException`       | Invalid version syntax 'v24.5'. Provide a valid version like 'v24_5'.                                                                           |
| `NotFoundException`             | No product with id '0815' for site 'SiteGenesis' found.                                                                                         |
| `ResourcePathNotFoundException` | If the requested URL matches the B2C Commerce Digital Rest URL pattern, but the resource path is unknown that is, /dw/shop/v24_5/unknown/123. |
| `UnknownVersionException`       | Unknown version 'v33.33'. Provide a valid version.                                                                                              |

## 405 (Method Not Allowed)

| Fault type                  | Sample fault message         |
| --------------------------- | ---------------------------- |
| `MethodNotAllowedException` | Method 'DELETE' not allowed. |

## 406 (Not Acceptable)

| Fault type               | Sample fault message                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| `NotAcceptableException` | Unsupported charset 'iso-8859-1' in Accept-Charset header. Note: Only UTF-8 charset is supported. |

## 413 (Request Entity Too Large)

| Fault type                       | Sample fault message                               |
| -------------------------------- | -------------------------------------------------- |
| `RequestEntityTooLargeException` | Request body size limit of 5 MB has been exceeded. |

## 414 (Request URI Too Long)

| Fault type                   | Sample fault message                                           |
| ---------------------------- | -------------------------------------------------------------- |
| `RequestUriTooLongException` | Request URL length limit of 2000 characters has been exceeded. |

## 415 (Unsupported Media Type)

| Fault type                      | Sample fault message               |
| ------------------------------- | ---------------------------------- |
| `UnsupportedMediaTypeException` | Unsupported document format 'pdf'. |

## 500 (Internal Server Error)

| Fault type               | Sample fault message   |
| ------------------------ | ---------------------- |
| `InternalErrorException` | Internal Server Error. |

<!-- document id=fcf48987e3d07cfa52b32d1376477dfb56b72dbb06756f644bda61fe3af821ab url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/images.md -->

# OCAPI Images

The Open Commerce API returns URLs to images. The Shop API returns only absolute URLs. For example:

```json

{
  "_v" : "24.5",
  ...
  "categories" : [ {
    "id" : "mens-clothing",
    "image" : "http://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites-storefront-catalog-en/default/v1345174669086/images/slot/sub_banners/mens-clothing-accessories.jpg"
  } ]
}

```

<!-- document id=a8789651577935e4bb87e8686e4982a19eaa46ac0d9417c15135556b4139cb41 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/jsonp.md -->

# OCAPI JSONP

JSONP (JSON with padding) allows a browser page to request data from a server in a different domain. Normally, a Web API request returns a plain JSON document, which requires the client to parse the JSON document. There are some Browser JavaScript cases where it’s much more efficient to respond with JavaScript code instead of with a JSON document. The response is directly evaluated by the JavaScript interpreter and isn’t parsed by a JSONParser. The response, in these cases, is merely a JSON document with a JavaScript function call wrapped around it.

The Open Commerce API offers the URL request parameter `callback`. The value of this parameter is the name of the JavaScript function that is wrapped around the JSON document.

```txt

REQUEST:
GET /dw/shop/v24_5/products/99225?client_id=[your_own_client_id]&pretty_print=true&callback=parseResponse HTTP/1.1
Host: example.com

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 351
Content-Type: text/javascript;charset=UTF-8
X-Content-Type-Options: nosniff

/**/parseResponse({
  "_v" : "24.5",
  "brand" : "Apparelstore",
  "id" : "99225",
  "name" : "Boot Sauce™ Brown Cream"
})

```

<!-- document id=73bf04ad44268fad15080e76e859f9abeda1483d9d0d9a190c03948138b67f17 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/jwt.md -->

# OCAPI JWT

JSON Web Token (JWT) is an authentication mechanism required by several Shop API resources. You don’t have to be familiar with JWT to use these resources; however, for more information about JWT, see the [JSON Web Token (JWT) IETF specification](http://tools.ietf.org/html/rfc7519).

Your client application is responsible for keeping customer credentials and authentication tokens (JWTs) secure. Your application must use these JWTs to interact with the Shop API on behalf of the purchasing customer (registered or guest).

If B2C Commerce manages your customer credentials, your client application can obtain a JWT for a customer using the `/customers/auth` resource.

If your client application manages your customer credentials, it can obtain a JWT for a registered customer using the `/customers/auth/trustedsystem` resource. Because this API uses an OAuth token to identify the client application, we strongly recommend that you only use it in a system-to-system integration, where the client application keeps its own OAuth token secret.

## Preparation

Before you can use JWTs for authentication, you must register your client application using Account Manager. See Adding a client ID for the Open Commerce API.

<!--TODO: Fix link post migration -->
<!-- Before you can use JWTs for authentication, you must register your client application using Account Manager. See [Adding a client ID for the Open Commerce API.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/account-manager/b2c-account-manager-add-api-client-id.md)
 -->

Account Manager provides you with a client ID that is known to both B2C Commerce and your client application. The client ID is required when you request an authentication token. On sandboxes, for testing, you can use the demo client ID: [your_own_client_id].

In addition to obtaining the authentication token, you must configure [Open Commerce API Settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md) to grant your client application access to the Open Commerce APIs.

## Authentication Steps

To use JWTs for authentication, your client application must perform the following steps:

1.  Request a JWT using the `/customers/auth` resource.

2.  Include the JWT in subsequent Shop API requests.

3.  Refresh the JWT if needed.

When you request a JWT using the `/customers/auth` resource, you must specify your client ID as a URL or header parameter. You must also specify the type of customer:

1.  Specify `"type":"guest"` to request a JWT for a _guest_ customer.
2.  Specify `"type":"credentials"` to request a JWT for a _registered_ customer. (For a registered customer, you must also include the customer login and password in the HTTP Basic Authentication scheme.)
3.  Specify `"type":"session"` to request a JWT for a customer (_guest_ or _registered_) associated with a session. (You have to provide valid _dwsid_ and _dwsecuretoken_ cookies.)

If the request succeeds, the response includes a JWT in the `Authentication:Bearer` response header. The response also includes a description of the customer in the response body. Your application must include the JWT in the `Authentication:Bearer` header of subsequent requests.

The JWT is signed. This means that the JWT's _header_ and _payload_ sections are JSON-formatted strings. Your client application can therefore easily read the various claims in the payload section, such as `exp` (the token expiration-time) and `iat` (the token issued-at-time).

A JWT has a lifetime of 30 minutes. Before the token expires, you must exchange it for a new token if you want to extend the total lifetime. You can use the `/customers/auth` resource to obtain a new token in exchange for an existing one. You must include the current token in the `Authentication:Bearer` request header, and you must specify the customer type as `"type":"refresh"`.

The `/customers/auth` request is based on an HTTP POST operation, which uses transport layer security; the request body must be URL encoded. For registered customers, the client Id must be passed in the initial request to obtain the authentication token, but isn’t needed in subsequent requests.

## External Authentication

External client applications don't have to authenticate customers through B2C Commerce. A client application can authenticate customers itself or through an Identification Provider (IDP) such as Google or Facebook.

To authenticate a registered customer, don't request a JWT using `/customers/auth`. Instead, use `/customers/auth/trustedsystem` as follows:

1.  First, register the client application with Account Manager and obtain an OAuth token for it. When calling the `trustedsystem` API, include that token in the authorization header.
2.  Use HTTP POST to call `/customers/auth/trustedsystem`. In the request body, include the customer login ID and your application's client ID.

If the request succeeds, the JWT is included in the `Authentication:Bearer` response header. The response body includes a customer object.

If your external client application authenticates customers via an external IDP, each customer needs an external profile in order to retrieve cart information or order history. The first time your app authenticates each customer, create a customer record with an external profile as follows:

1.  Obtain a guest JWT using `/customers/auth` with type `guest`. If you use a registered customer JWT, the call throws an exception.
2.  Use HTTP POST to call `/customers/ext_profile` with the guest JWT. In the request body, include the authentication provider ID, the ID used to log in to the external IDP, and (if different from the login ID) the customer's email address.

If the request succeeds, the response includes a customer ID.

## JSON Web Token Details

The JSON Web Token specification stipulates that a JWT contains three sections in the following order:

- The _header_ section specifies the token type and algorithm used.
- The _payload_ section contains customer information, the client id, and issue and expiration time.
- The _signature_ section records the token signature.

The system returns the JWT as a Base64-encoded string. In this string, the _header_, _payload_, and _signature_ sections are delimited by periods(.).

B2C Commerce uses a subset of the claims defined in the JSON Web Token specification. You can decode the _payload_ section to access the values of the `exp`, `iat`, `sub`, and `iss` claims. For example:

```json
{
      "exp": 1300819380,
      "iat": 1300819000,
      "sub": ... ,
      "iss": "[your_own_client_id]"
}
```

- **exp:** Token expiration-time as seconds from 1970-01-01T00:00:00Z
- **iat:** Token issued-at-time as seconds from 1970-01-01T00:00:00Z
- **sub:** Token subject (see below)
- **iss:** Token issuer (client ID)

The value of the `sub` claim is a JSON string. For example:

```json
{
  "customer_id": "12a4567f9123",
  "guest": false
}
```

## Common JWT Scenario: Transferring a Basket From a Guest to a Registered Customer

A typical storefront enables a user to create and use a basket as a guest customer, and then continue to use the "same" basket after logging in as a registered customer. The Open Commerce API enables you to achieve this effect by copying the guest basket and using the new copy for the registered customer.

How you do this is described below:

1.  Request a JWT using the `/shop/v24_5/customers/auth` resource.

    In the body of the request, specify "guest" as the value of the "type" property: `{ "type" : "guest" }`.

2.  Request a basket using the `/shop/v24_5/baskets` resource.

    In the request, include the JWT you obtained in the previous step.

3.  After performing additional OCAPI requests against the guest basket (for example, to create items, set a billing address, and so on) retain the last JSON response (a Basket document) in a variable.
    <!--TODO: Fix link post migration -->
    <!-- 3.  After performing additional OCAPI requests against the guest basket (for example, to create items, set a billing address, and so on) retain the last JSON response (a [Basket document](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/shop/documents/basket.md)) in a variable.
     -->
4.  When the customer tries to log in as a registered customer, request a new JWT using the `/shop/v24_5/customers/auth` resource.

    In the request, specify "credentials" as the value of the "type" property: `{ "type" : "credentials" }`.

    Also, in the request's `Authorization` header, specify the registered customer's login credentials.

5.  Request a new basket using the `/shop/v24_5/baskets` resource.

    In the request, include the basket document retained in step 3; also include the JWT obtained in the step 4.

    **note:** The basket document must not be modified after it was last saved; it must be the same as it was after the last request, with the same order of properties.

The new basket for the registered customer can now be modified and submitted as needed.

When creating baskets with a JWT, there’s a limit of one _open_ basket per registered customer. Exceeding this limit results in `a CustomerBasketsQuotaExceededException` fault response.

## JWT Examples

The following examples show sample requests and responses using JWTs for authentication (additional examples are provided within the resource documentation):

The first example request obtains a token for a registered customer. The credentials are `username:password` (Base64-encoded), passed via HTTP Basic Auth.

If the server finds a customer with the given credentials, it returns a newly created token (a JWT) in the Authorization:Bearer response header. The value of the `auth_type` property is "registered" because the `type` property was set to "credentials" in the request.

```txt
REQUEST:
POST /dw/shop/v24_5/customers/auth?client_id=[your_own_client_id]
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
  "type" : "credentials"
}


RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json;charset=UTF-8
{
   "_v" : "24.5",
   "_type" : "customer",
   "auth_type" : "registered",
   "customer_id" : "abdtkZzH6sqInJGIHNR1yUw90A",
   "preferred_locale" : "default"
   ...
}
```

All subsequent requests include the token in the `Authorization:Bearer` header. For example, the following request asks the server to create a basket for the registered customer. The client ID isn’t required.

The server returns information for the newly created basket.

```txt
REQUEST:
POST /dw/shop/v24_5/baskets HTTP/1.1
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Host: example.com
Content-Type: application/json


RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
Content-Type:application/json;charset=UTF-8
{
   "_v" : "24.5",
   "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
   "_type" : "basket",
   "basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
   "currency" : "USD",
   ....
}

```

<!-- document id=5744acecd4ad126e4022b42ea17cd74737146d9b147bd762a49d9d53e5b8042c url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/localization.md -->

# OCAPI Localization

The Open Commerce API supports localized content.

## Shop API

The Shop API supports a single locale at a time. You can specify the locale by setting the `*locale*` parameter, which takes values in the format _\<language code>-\<country code>._ Otherwise, the Shop API uses the default locale of the site. Note: In Shop API the following locale fallback is performed: _Locale (en-US) > Language Locale (en) > Default locale (default)_. The following example shows how you can explicitly specify a locale:

```txt
REQUEST:
GET /dw/shop/v24_5/content/about_us?locale=en-US HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 351
Content-Type: application/json; charset=UTF-8

{
  "_v" : "24.5",
  "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
  "description" : "It all started with a series of observations...",
  "id" : "about-us",
  "name" : "About Us",
  "c_body" : "<h1 class=\"content-header\">About Us</h1><h2>It all started with a series of observations:</h2> ...",
  "c_greeting" : "How are you?"
}

```

## Data API

The Data API supports multiple locales at the same time. By default, localizable properties are returned as a map of all available localized values keyed by the locale identifier. However, you can explicitly specify a single locale by setting the `locale` parameter, which takes values in the format _\<language code>-\<country code>._ If you explicitly specify a locale, localizable properties are returned as a single map entry. Note: In Data API no locale fallback is performed.

The first example shows the default behavior, which returns a map of multiple localized values:

```txt
REQUEST:
GET /dw/data/v24_5/library/SiteGenesis/content/about-us HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 569
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
  "_v" : "24.5",
  "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
  "description" : {
    "default" : "It all started with a series of observations..."
  },
  "id" : "about-us",
  "link" : "https://example.com/s/-/dw/data/v24_5/libraries/SiteGenesis/content/about-us",
  "name" : {
    "default" : "About Us"
  },
  "c_body" : {
    "default" : "<h1 class=\"content-header\">About Us</h1><h2>It all started with a series of observations:</h2> ...",
    "de-DE" : "<h1 class=\"content-header\">Über uns</h1><h2>Alles begann mit einer Reihe von Untersuchungen:</h2> ..."
  },
  "c_greeting" :
  {
    "default" : "hello",
    "en" : "Good day",
    "en-US" : "How are you?",
    "en-GB" : "How do you do?",
    "de" : "Hallo",
    "de-DE" : "Guten Tag",
    "fr" : "Bonjour"
  }
}

```

The second example shows a response for an explicitly specified locale:

```txt
REQUEST:
GET /dw/data/v24_5/library/SiteGenesis/content/about-us?locale=en-US HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 569
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
Content-Type: application/json;charset=UTF-8

{
  "_v" : "24.5",
  "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
  "id" : "about-us",
  "link" : "https://example.com/s/-/dw/data/v24_5/libraries/SiteGenesis/content/about-us",
  "c_greeting" :
  {
    "en-US" : "How are you?"
  }
}

```

<!-- document id=ca98bee67447b967f30bf064e1672de3c4321846b77092a01576707db66c4ee3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/metadata.md -->

# OCAPI Metadata

The Open Commerce API provides data about itself (metadata). You can obtain API metadata by accessing an own API, the _meta_ API. This API can be accessed like the shop and the data API, but with version 1 as API version. The meta API provides information about

- [A list of available APIs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/metadata.md#list-of-apis)
- [A list of available versions for an API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/metadata.md#list-of-versions)
- [A list of resources and their descriptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/metadata.md#list-of-resource-descriptions)
- [A list of accessible documents](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/metadata.md#list-of-documents)
- [A description for a single document](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/metadata.md#show-document-information)

To access the Meta API, you have to send an _Authorization: Bearer_ [OAuth token](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/oauth.md) with every request, which is obtained via Account Manager. With the client ID, used to create the access token, the access to all resources via OCAPI settings is proofed and only the available resources and documents are shown. The results may differ, depending on the context used to access the metadata. In the context of a specific site, the OCAPI settings of the site are used to check the access rights for the requesting client and show him only the resources he’s allowed to access. The same applies to accessing the metadata in a global context, where the global OCAPI settings are used to retrieve only the metadata the client is allowed to access.

The Meta API responses are cached in the page cache for 24 hours. This means that the cache for the metadata is automatically cleared with page cache clearing.

## List of APIs

The following example lists which APIs are available:

```txt
REQUEST:
GET /dw/meta/v1/rest HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "apis": [
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data",
        "name": "data"
    },
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/meta",
        "name": "meta"
    },
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/shop",
        "name": "shop"
    }]
}
```

## List of Versions

The following example lists which API versions are available:

```txt
REQUEST:
GET /dw/meta/v1/rest/data HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "versions": [
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_2",
        "name": "14.2",
        "status": "deprecated"
    },
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v14_6",
        "name": "14.6",
        "status": "deprecated"
    },
    ...
    {
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1",
        "name": "24.5",
        "status": "current"
    }
    ]
}
```

## List of Resource Descriptions

The retrieved document is for using with _swagger_ in version [2.0](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md) and lists all resource paths with their input-parameters and return type descriptions. The following example lists supported resource URIs:

```txt
REQUEST:
GET /dw/meta/v1/rest/data/v23_1 HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 5981
{
    "info":
    {
        "version": "24.5",
        "title": "Data API"
    },
    "swagger": "2.0",
    "basePath": "https://example.com/s/-/dw/data/v23_1",
    "paths":
    {
        "/customer_search":
        {
            "post":
            {
                "operationId": "customerSearchcustomer_search",
                "responses":
                {
                    "default":
                    {
                        "schema":
                        {
                            "$ref": "#/definitions/customer_search_result"
                        }
                    }
                },
                "tags": [
                    "customer_search"
                ],
                "parameters": [
                {
                    "in": "body",
                    "required": true,
                    "schema":
                    {
                        "$ref": "#/definitions/customer_search_request"
                    },
                    "name": "body"
                }]
            }
        },
        ...
    },
    "definitions":
    {
        ...,
        "customer_search_result":
        {
            "properties":
            {
                "count":
                {
                    "format": "int32",
                    "type": "integer"
                },
                "hits":
                {
                    "items":
                    {
                        "$ref": "customer_search_hit"
                    },
                    "type": "array"
                },
                ...
            },
            "id": "customer_search_result"
        },
        ...
    }
}
```

## List of Documents

The following example lists all available documents for an API in a specific version:

```txt
REQUEST:
GET /dw/meta/v1/rest/data/v23_1/documents HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "data": [
    {
        "id": "credentials",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/credentials"
    },
    {
        "id": "customer",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/customer"
    },
    {
        "id": "customer_address",
        "link": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/customer_address"
    },
    ...]
}
```

## Show Document Information

The following example shows the metadata for a requested document for an API in a specific version:

```txt
REQUEST:
GET /dw/meta/v1/rest/data/v23_1/documents/customer_address_result HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>
x-dw-pretty-print: true

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "properties":
    {
        "count":
        {
            "format": "int32",
            "type": "integer"
        },
        "data":
        {
            "items":
            {
                "$ref": "https://example.com/s/-/dw/meta/v1/rest/data/v23_1/documents/customer_address"
            },
            "type": "array"
        },
        "next":
        {
            "type": "string"
        },
        ...
    }
}

```

Also it’s possible to include the child document definitions by adding a query parameter _children=embedded_:

```txt
REQUEST:
GET /dw/meta/v1/rest/data/v23_1/documents/customer_address_result?children=embedded HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Bearer <access_token>

RESPONSE:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=900,must-revalidate
Content-Length: 741
{
    "properties":
    {
        "count":
        {
            "format": "int32",
            "type": "integer"
        },
        "data":
        {
            "items":
            {
                "customer_address":
                {
                    "required": [
                        "address_id",
                        "country_code",
                        "last_name"
                    ],
                    "properties":
                    {
                        "address1":
                        {
                            "maxLength": 256,
                            "type": "string"
                        },
                        ...
                    }
                }
            },
            "type": "array"
        },
        ...
    },
    "id": "customer_address_result"
}
```

<!-- document id=5ff0e73aca799664f00474a98e2ded2970e35d64add57c2118999ca3ebcc8587 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/oauth.md -->

# OCAPI OAuth 2.0

The OAuth 2.0 protocol is used for authentication and authorization where the shopping customer context provided by [JWT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jwt.md) doesn’t fit. When using the Data API in a server-to-server scenario, OAuth is used to authenticate requests in the context of a client ID, also known as a _Client Credentials Grant_. When using the Shop API or Data API in a scenario in which a _Business Manager user_ interacts with the system, OAuth is used to authenticate requests in the context of the user.

**note:** This topic assumes that you’re familiar with OAuth 2.0. For more information, see the [OAuth 2.0 Authorization Framework](http://tools.ietf.org/html/rfc6749) IETF specification.

## Supported Grant Types

- In a _server-to-server scenario_, one system, such as a CRM (Customer Relationship Management) application, interacts directly with the Data API: no end user interaction is required. In this scenario, the system requesting access functions as the OAuth 2.0 client application. This client application must be able to keep its client password secure. The OAuth 2.0 specification describes several authorization grant types. The server-to-server scenario makes use of the _client credentials grant_, used when the client application needs to access resources that aren’t owned by a specific resource owner or user. For more information, see the [Client Credentials Grant](http://tools.ietf.org/html/rfc6749#section-4.4) section in the IETF specification.
- In other scenarios, requests must be authenticated for a _Business Manager user_, for which OCAPI supports a _Business Manager user grant_. This grant type is used by the Shop API for use cases in which a user does something on behalf of a shopping customer, for example the creation and submission of a basket. The Shop API allows such a user to do more than a customer authenticated with [JWT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jwt.md), such as adding price adjustments to the basket. This grant type can also be used to authenticate requests to the Data API. The authenticated user needs to be authorized by assigning permissions in the Business Manager permissions module. Additionally the OAuth 2.0 Authorization Code Grant can be used for this scenario. For more information, see the [Authorization Code Grant](http://tools.ietf.org/html/rfc6749#section-1.3.1) section in the IETF specification.

## Basic Steps for Authentication and Authorization

Perform the following steps:

1.  **Register your client application using Account Manager:**

    All client applications that access the Open Commerce API must be registered through the Account Manager. See Adding a client ID for the Open Commerce API. The result of this process is a set of values (a client ID and client password) that are known to both Commerce Cloud Digital and your client application.

    <!--TODO: Fix link post migration -->
    <!--   All client applications that access the Open Commerce API must be registered through the Account Manager. See [Adding a client ID for the Open Commerce API.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/account-manager/b2c-account-manager-add-api-client-id.md) The result of this process is a set of values (a client ID and client password) that are known to both Commerce Cloud Digital and your client application.
     -->

**note:** Digital doesn’t keep a copy of your client password; instead, it stores a one-way hash.

2.  **Request an access token:**

    The Digital Authorization server is a central server (account.demandware.com) that functions as an OAuth 2.0 authorization server from which the client can obtain an access token. The mechanism to obtain an access token depends on which sort of grant type you need. In the case of a Business Manager user grant the _Digital Application Server_ forwards the request for a token to the Authorization server.

3.  **Include the access token in the OCAPI request:**

    After your client application obtains an access token, it sends the token in each Open Commerce API request as part of the HTTP Authorization header.

## Requesting an Access Token With the Client ID and Password

Before your client application can request an access token, you must first register with the Account Manager. When the registration is complete, the Account Manager provides you with a client ID. You need this client ID and your associated password (which you provided during registration) when coding your confidential web application. On sandboxes you can use the demo client ID "[your_own_client_id]" with client password "[your_own_client_id]".

After registration, you can construct a request for the access token. Your client application then sends the token request to the Digital Authorization Server. Assuming the request succeeds, the Digital Authorization Server returns an access token. Your client application uses this token in following requests.

When the access token expires, the client application repeats the process.

**note:** In addition to obtaining the access token, you must configure [client permissions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md) in order to grant your client application access to the Open Commerce APIs. When using a Business Manager user grant the user will also be checked against the Business Manager permissions set.

As described in the OAuth 2.0 specification, any access token request is an HTTP POST using transport layer security and the body is URL encoded.

- **Obtain a Client Credentials grant:** in a request directed to the _Digital Authorization server_, the _Client ID_ and _client password_ are included in the _Authorization_ header as required by the [HTTP Basic Authentication mechanism (RFC 2617)](http://www.ietf.org/rfc/rfc2617.txt). (The client ID and client password, joined by a ':' are encoded using the base-64 encoding scheme.) The parameter _grant_type_ is required and must be set to 'client_credentials'. See the sample below:

  ```txt
  REQUEST:
  POST /dwsso/oauth2/access_token HTTP/1.1
  Host: account.demandware.com
  Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
  Content-Type: application/x-www-form-urlencoded

  grant_type=client_credentials
  ```

- **Obtain a Business Manager user grant:** in a request directed to the _Digital Application Server_, the _Client ID_ is included as a URL Parameter and the _User Login_, _User Password_ and _client password_ are included in the _Authorization_ header as required by the [HTTP Basic Authentication mechanism (RFC 2617)](http://www.ietf.org/rfc/rfc2617.txt). The joined

  ```txt
  User Login:User Password:Client Password
  ```

  is encoded using the base-64 encoding scheme. The parameter _grant_type_ is required and must be set to

  ```txt
  urn:demandware:params:oauth:grant-type:client-id:dwsid:dwsecuretoken
  ```

  See the sample below:

  ```txt
  REQUEST:
  POST /dw/oauth2/access_token?client_id=[your_own_client_id] HTTP/1.1
  Host: example.com
  Authorization: Basic TXlMb2dpbjpNeVBhc3N3cmQ6TXlDbGllbnRTZWNyZXQ=
  Content-Type: application/x-www-form-urlencoded

  grant_type=urn:demandware:params:oauth:grant-type:client-id:dwsid:dwsecuretoken
  ```

**note:** If the [Access Setting](https://help.salesforce.com/s/articleView?id=cc.b2c_ip_address_settings.htm&type=5) is configured in B2C Commerce Business Manager for **IP Range Allowlist**, it affects the OAuth grant type **Business Manager user grant**. An **unauthorized_client** error is returned when a request to `/access_token` is made from an origin that is not in the allowlist. Any origin that wants to use OAuth must be in the allowlist.

- **Obtain a Authorization Code Grant:**
  Login into the Digital Authorization server with the following request:

```txt
REQUEST:
GET /dwsso/oauth2/authorize?client_id=abcdef&amp;redirect_uri=http://myserver.com&amp;response_type=code HTTP/1.1
Host: account.demandware.com
```

Note:

1. Your user on the Digital Authorization server need to have the role Business Manager Administrator or Business Manager User assigned together with a tenant filter, which matches the Digital Application Server instance you will use the OAuth token for.

2. Please make sure, that the redirect URI given in your request matches the one defined at your client id, you are using at the Digital Authorization server.

As a result you will be redirected to the URL:

```txt
RESPONSE:
http://myserver.com&amp;code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3
```

The redirect call will give you back the code created by the Digital Authorization server. In a second request directed to the Digital Authorization server, the the client ID and client password are included in the Authorization header, according to the HTTP Basic Authentication mechanism. The parameter `grant_type` is requiredand must be set to `authorization_code`. Additionally the code parameter value, returned from the first call and the `redirect_uri` needs to be provided. See the sample below:

```txt
REQUEST:

POST /dwsso/oauth2/access_token HTTP/1.1
Host: account.demandware.com
Authorization: Basic YWJjZGVmOm9wZW4gc2VzYW1l
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&amp;code=g0ZGZmNjVmOWIjNTk2NTk4ZTYyZGI3&amp;redirect_uri=http://myserver.com>
```

## Requesting an Access Token Using a JWT and Key Pair

You can authenticate a client application using a signed JWT instead of an ID and password. Because the client password isn’t transferred, it isn’t vulnerable to interception. The signed JWT can’t be tampered with. This method is based on the [JWT Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://tools.ietf.org/html/rfc7523).

1.  Generate a private and public key pair.
2.  Log into Account Manager and create an API Client. See Adding a client ID for the Open Commerce API.
    <!--TODO: Fix link post migration -->
    <!-- 2.  Log into Account Manager and create a new API Client. See [Adding a client ID for the Open Commerce API.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/account-manager/b2c-account-manager-add-api-client-id.md)
     -->
3.  Generate a X.509 certificate with the following command:

    ```txt
    openssl req -x509 -newkey rsa:4096 -keyout key.pem -out
            cert.pem -days 365 -nodes
    ```

4.  Upload either a base64-encoded X.509 certificate containing the public key, or the Base64-encoded public key itself, to the **JWT (Client JWT Bearer Public Key)** section.
5.  For **Token Endpoint Auth Method**, select `private_key_jwt`.
6.  Create the JWT for requesting access tokens and sign it with the private key. The JWT format is described in the JWT Profile specification. Here's an example.

    ```json
    # header
    {
      "alg": "RS256",
      "typ": "JWT"
    }

    # payload
    {
      "iss": "[your_own_client_id]",           // string identifying the issuing client app
      "sub": "[your_own_client_id]",   // string identifying the issuing client app
      "exp": 1548407254, // must be not more than 30 minutes in future
      "aud": "https://account.demandware.com:443/dwsso/oauth2/access_token"
    }
    ```

Use the JWT to obtain a client credentials grant via the `access_token` endpoint. Set the parameter `grant_type` to `client_credentials` and include the JWT in the `client_assertion` as in the example.

```txt
REQUEST:
POST /dwsso/oauth2/access_token HTTP/1.1
Host: account.demandware.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
  eyJhdWQ[...omitted for brevity...].
  SmyAXw2[...omitted for brevity...]
```

**note:** Using a Bearer JWT as an authorization grant with '`grant_type`' value '`urn:ietf:params:oauth:grant-type:jwt-bearer`' as described in [Using JWTs as Authorization Grants](https://tools.ietf.org/html/rfc7523#section-2.1) isn’t supported.

## Token Response

When your client application requests an access token, the Digital Authorization Server returns a JSON document. If your request is valid, the client authentication succeeds, and the server's response includes the access token:

```txt
RESPONSE:
HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store

{
 "access_token": "eyJhbG[...omitted for brevity]",
 "expires_in": 1800,
 "refresh_expires_in": 0,
 "token_type": "Bearer",
 "not-before-policy": 0,
 "scope": "mail"
}
```

## Token Expiration

An access token obtained with Client Credentials grant expires after 30 minutes. In contrast, a token obtained with a Business Manager user grant expires after only 15 minutes. When an access token obtained using the client credentials grant expires, the client application has to request another access token.

**note:** In order to ensure optimal client application performance an access token should be reused by the client application until it expires.

## Calling the Shop or Data API

In your OCAPI request, include the access token as an _Authorization_ header '`Bearer`' token:

```txt
REQUEST:
GET /dw/data/v24_5/customers/dude0815 HTTP/1.1
Host: example.com
Authorization: Bearer 5294ed7a-18dd-4ce7-ab9e-3ecda4c54f28
```

<!-- document id=48649c944f2ecf5409758e337664f7db89f33164c8aac005ec734ec4adddef94 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/optimisticlocking.md -->

# OCAPI Optimistic Locking

OCAPI supports two independent levels of optimistic locking for data consistency. The first level is embedded in the Commerce Cloud Digital data layer itself. The second level is an optional feature of the Open Commerce API.

## Data Layer

Digital uses optimistic locking for a wide range of resources in the data layer. This functionality can’t be adjusted or disabled, and it prevents concurrent threads from accidentally overwriting each other's changes (lost update problem).

In the data layer, each concurrent thread operates on the base of a known object state. If one thread changes the object state while another thread simultaneously changes the object state and then attempts to commit the changes within a transaction, an exception occurs.

This exception is exposed by various Commerce APIs (for example, the Digital Script API and OCAPI). OCAPI specifically exposes this exception as an HTTP 409 (Conflict) `ConcurrentModificationException` fault.

The easiest way for your client application to react to this fault is to simply retry the OCAPI call, because in most cases the fault is caused by bad timing.

However, a simple retry may not work for more complex cases, especially cases where an operation on one resource implicitly touches another resource. For example:

- Updates of ProductCategoryAssignments, BundledProducts, Variations, VariationGroups, and ProductSets resources implicitly touch the parent Product resource.
- Updates of a Profile resource implicitly touch the Customer resource.
- Updates of ProductListItem, Registrant, and Address resources implicitly touch the ProductList resource.

For such complex cases, you might have to conduct a broader examination of your jobs and storefront/applications, including their customizations (for example, hooks) to find a solution.

Typical scenarios where optimistic locking exceptions occur:

- Concurrent OCAPI requests
- Concurrent Script API pipeline/controller requests
- Concurrent OCAPI and Script API requests
- Concurrent OCAPI requests, Script API requests, and job executions

## Open Commerce API Layer

The [Resource States](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/resourcestates.md) concept allows optimistic locking via conditional requests in OCAPI. If your client application has to explicitly support concurrent updates of the same resources, you should make use of [Resource States](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/resourcestates.md). Instead of only a database transaction, this concept covers the whole HTTP request/response flow. Resource states reduce the possibility of `ConcurrentModificationExceptions`, but can’t completely prevent them.

<!-- document id=797373ea683ae30ef7eae522377986c31da4eeda7bee875e67f5f96e0c8e6e47 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/pagination.md -->

# OCAPI Pagination

The Open Commerce API uses paging whenever it accesses a collection of resource instances. Paging enables the API to return data in chunks, instead of returning a complete collection all at once. Each chunk, depending on its position, links to the previous chunk and to the next chunk. You can explicitly configure paging by providing values for the `start` and `count` parameters:

- `start`: Specifies the start location of the chunk within the collection of resource elements. Valid values range from 0 to 999; the default value is 0. The start location isn’t a page number; it’s the position of the start element within the entire collection.
- `count`: Specifies the number of resource instances to return in each chunk. Valid values range from 0 to 200; the default value is 25.

In the following example, a product search yields a collection of 99 total resource instances (shoes). The `start` property specifies that the requested chunk should start at position 10, and the `count` element specifies that the chunk should contain at most 5 resource instances. In the response, you can see the presence of the `next` and `previous` links; these links enable your application to navigate through the entire collection one chunk at a time.

```txt

REQUEST:
GET /dw/shop/v24_5/product_search?q=shoes&start=10&count=5 HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 351
Content-Type: application/json; charset=UTF-8

{
  "_v" : "24.5",
  "query":"shoes",
  "total":99,
  "start":10,
  "count":5,
  "next":"http://example.com/dw/shop/v24_5/product_search?q=shoes&start=15&count=5",
  "previous":"http://example.com/dw/shop/v24_5/product_search?q=shoes&start=5&count=5",
  "hits":[{
    "product_id":123",
    "link":"http://example.com/dw/shop/v24_5/product/123",
    "name":"My Ultimate Shoe",
    ...
    },
    ...
  ]}

```

<!-- document id=45c385b4ed38ee10f05d8c97cdd957b16ab43126c4b30fe3a1c34848b36eba2f url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/propertyselection.md -->

# OCAPI Property Selection

Property selectors reduce the number of resource properties retrieved by the API, so you can get only those properties you care about, while reducing network bandwidth.

You can specify property selectors for all resource types; to do so, you set the `select` parameter on the request. The actual selector value must be enclosed within parentheses. The following table lists the different capabilities of property selectors for different `select` parameter values:

| Capability                                                                                                                                                         | Value of select parameter                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| Include properties of all levels, including complex properties.                                                                                                    | `(**)`                                                            |
| Include properties of top level, except complex properties.                                                                                                        | `(*)`                                                             |
| Include a single property.                                                                                                                                         | (price) (+price)                                                  |
| Exclude a single property.                                                                                                                                         | (-price)                                                          |
| Include the child document properties.                                                                                                                             | (variation_attributes.(\*\*))                                     |
| Return only the first document in array. Index starts with 0.                                                                                                      | (variation_attributes[0].(\*\*))                                  |
| Return only the first 5 documents in array. Index starts with 0.                                                                                                   | (variation_attributes[0:4].(\*\*))                                |
| Return only the second, fourth, and sixth document in array. Index starts with 0.                                                                                  | (variation_attributes[1,3,5].(\*\*))                              |
| Return only documents in array that match the filter. Filter expression syntax is `?(_boolean_expression_)`. Supported Operators: `==`, `!=`, `<=`, `>=`, `<`, `>` | (variation_attributes[?(@.name=='color')].(\*\*))                 |
| Combine OR (\|\|) and AND (&&) in a filter.                                                                                                                        | (variation_attributes[?(@.name=='color' && @.id=='size')].(\*\*)) |

You can specify a single property name or a comma-separated list of property names enclosed by parentheses. The following example shows how you can select the `name`, `id`, and `variation_attributes` properties of the product resource instance:

```txt
REQUEST:
GET /dw/shop/v24_5/products/123/variations?select=(name,id,variation_attributes.(**)) HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 29
Content-Type: application/json; charset=UTF-8

{
  "_v" : "24.5",
  "name":"foo",
  "id":"123",
  "variation_attributes":[{
    "id":"color",
    "name":"Color",
    "values":[{
       "value":"red",
       "name":"Red",
       "description":""
    },
    {
       "value":"blue",
       "name":"Blue",
       "description":""
    }]
  },
  {
    "id":"size",
    "name":"Size",
    "values":[{
       "value":"M",
       "name":"Medium",
       "description":""
    },
    {
       "value":"L",
       "name":"Large",
       "description":""
    }]
  }]
}

```

To select a child property, remember to accurately specify all of the result levels. The following example shows a filtered order search with a select that goes three levels deep to select and sort by fields on the retrieved order records.

```txt
REQUEST:
POST /dw/shop/v24_5/order_search HTTP/1.1
Host: example.com
Accept: application/json
{
  "query" : {
    "filtered_query": {
      "filter": {
        "range_filter": {
          "field": "creation_date",
          "from": "2020-03-08T00:00:00.000Z",
          "to": "2020-03-10T00:00:00.000Z"
        }
      },
      "query" : {
        "match_all_query": {}
      }
    }
  },
  "select" : "(hits.(data.(creation_date,confirmation_status,total)))",
  "sorts" : [{"field":"creation_date", "sort_order":"asc"}]
}


RESPONSE:
HTTP/1.1 200 OK
Content-Length: 29
Content-Type: application/json; charset=UTF-8

{
  "_v":"24.5",
  "_type":"order_search_result",
  "hits": [
    {
      "_type":"order_search_hit",
      "data": {
        "_type":"order",
        "creation_date":"2020-03-08T04:15:00.000Z",
        "confirmation_status":"confirmed",
        "total":19.95
      }
    },
    {
      "_type":"order_search_hit",
      "data": {
        "_type":"order",
        "creation_date":"2020-03-08T07:30:00.000Z",
        "confirmation_status":"confirmed",
        "total":75.29
      }
    }
  ]
}

```

## Localized and SiteSpecific Properties

There are two types of properties, where an extra selector element is required: _Localized<?>_ and _SiteSpecific<?>_.

Values of _Localized_ properties depend on the locale, therefore a valid locale has to be included in the selector. An example of such a property is a product name. Whether a property is localized is typically noted in the property description.

For instance, this selector chooses all results with a certain name in the _default_ locale.

```
(data[?(@.name.default=='Product+Name')].(**))
```

_SiteSpecific_ properties are attributes where a value of the property depends on the selected site. The site-specific value is to be accessed with _default@Site._ As an example, a product’s validity dates are a site-specific date-time property.

This is an example of a selector that queries for results with a site-specific property being equal to a value for the site _SiteGenesis_:

```
(data[?(@.valid_from.default@SiteGenesis=='2016-02-21T04:00:00.000Z')].(**))
```

<!-- document id=1e510895015913e0c8255b06dd829344f31391374210b2ac4b1d0d9ae006f6f4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/dataformats.md -->

# OCAPI Resource Data Formats

The Open Commerce API currently supports one data format for resources: JSON. JSON is the default format. XML is not supported as data format for resources any longer.

How you specify a format depends on the underlying HTTP method. For GET requests, you provide a value for the URL request parameter `format` (valid value is json). For POST, PUT, and PATCH requests, you provide a value for the HTTP header `content-type` (valid value is application/json). The HTTP header `content-type` has precedence over the URL request parameter `format`.

**note:** The Open Commerce API supports character encoding in UTF-8 only.

<!-- document id=c1c4164999e24e1a816d6ed26bdfe1f934157f08d0722f288bdc7bb1995656f6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/resourcestates.md -->

# OCAPI Resource States

A resource state represents the server-side state of a specific resource, for example, a basket or a customer. It’s a string token, baked on all the resource property information.

OCAPI exposes resource state information via the _\_resource_state_ property in the response payload (body). The response contains either a single resource state or multiple resource states in case calling collection or search resources. In case of body-less responses (for example, HEAD) the resource state is exposed via _x-dw-resource-state_ response header.

## What Is It Used For?

Resource states provide an OPTIONAL mechanism to implement _Optimistic Locking_ in your client. They can be used to prevent collisions between concurrent requests, for example, to overcome the "lost update" problem.

## Resource State vs. Etag

A strong Etag covers not only the server-side resource state itself, but also the whole HTTP response on bit level. Means, it covers also the fact that compression (for example, gzip) is used or not. In scenarios where proxies are in between this might lead to unforeseen behaviours. E.g in case the client doesn't request compression, but there’s compression between the proxy and the server: Some proxies append "-gzip" to the Etag value, others absorb the Etag completely.

**note:** OCAPI uses the term "resource_state" to clearly differentiate the concept from Etags. OCAPI isn’t supporting Etags anymore.

## How Does It Work?

To use the resource state for optimistic locking you have to include the resource state from the last server response in your next state changing (DELETE, PATCH, POST, PUT) request. You should always prefer to use the _\_resource_state_ property in the body. In case the requested API doesn't have a body use the _x-dw-resource-state_ header. Whenever a resource state is part of a client's request, OCAPI verifies it by comparing the given value with the server resource state. If both resource states are equal the operation is executed, otherwise an HTTP 409 _ResourceStateConflictException_ fault is returned. In case of a create request (for example, with PUT) where the resource isn’t expected to be existing (with _not_exists_ state), the returned fault is an HTTP 409 _ResourceAlreadyExistsException_ instead.

**note:** Whenever your application performs state changing (DELETE, PATCH, POST, PUT) operations and there’s a likelihood of concurrent requests, we recommend leveraging optimistic locking on base of resource states.

## Samples

OCAPI exposes the resource state as _\_resource_state_ property in response body and as _x-dw-resource-state_ header.

```txt
# Create a new basket in the Shop API:
REQUEST:
POST /dw/shop/v24_5/baskets
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json

# in case of success, response contains new created basket with the resource state in response
# header and also as single property in response body
RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
x-dw-resource-state:ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36
Content-Type:application/json;charset=UTF-8
{
   "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36",
   ...
   "basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
   ...
}

# Search for stores in the Data API:
REQUEST:
POST /s/-/dw/data/v24_5/sites/SiteGenesis/store_search HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
...

# in case of success, response contains multiple resource states - one per search hit
RESPONSE:
HTTP/1.1 200 OK
{
   ...
   "hits" : [{
      "_resource_state" : "12ab34cd",
      "id" : ...
   },{
      "_resource_state" : "ef56gh78",
      "id" : ...
   }]
}

```

A resource state can be passed to any state changing method (DELETE, PATCH, POST, PUT). If no resource state is passed, the resource is overwritten, updated, or deleted without any further notice on base of the default HTTP method behavior. If a resource state is passed, it’s verified against the server resource state. If both states don’t match, a _ResourceStateConflictException_ or _ResourceAlreadyExistsException_ fault is responded. When the API user expects a resource not to exist (for example, during resource creation), the resource state **not_exists** can be passed. This prevents existing resources from being accidentally overwritten.

For every writing operation on a resource, a resource state token can be passed, but doesn’t have to. If no token is passed, the resource is overwritten, updated, or deleted without any further notice. If a resource state is passed, it’s checked against the server state of the resource. If both states don’t match, a _409_ status code is retrieved. When the API user expects a resource not to exist, a resource state **not_exists** must be passed (for a create request).

```txt
# add an item to the basket, the resource state from the response header is given as x-dw-resource-state
# header ...
REQUEST:
POST /dw/shop/v24_5/baskets/bczFTaOjgEqUkaaadkvHwbgrP5/items?client_id=af123-456....
Host: example.com
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
x-dw-resource-state:ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36
Content-Type: application/json
{
...
}

# ... or as _resource_state property in the body

# Add an item to the basket, send resource state via body

REQUEST:
POST /dw/shop/v24_5/baskets/bczFTaOjgEqUkaaadkvHwbgrP5/items
Host: example.com
Authorization: Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type: application/json
{
   "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
   ...
}

# in case of success, the next response header contains a new resource state
RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
x-dw-resource-state: ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36
Content-Type:application/json;charset=UTF-8
{
   "_resource_state" : "ba4e84383e1790597e49eeee34b201633d80ed3f499992f5af11d639dd903a36"
   ...
   "basket_id" : "bczFTaOjgEqUkaaadkvHwbgrP5",
   ...
}

# Delete an item from the basket, resource state is send via header

REQUEST:
DELETE /dw/shop/v24_5/baskets/bczFTaOjgEqUkaaadkvHwbgrP5/items/te352d63gdh62hd6hd
Host: example.com
Authorization: Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
x-dw-resource-state: 100001
Content-Length: 0

# in case of creating a not existent customer

REQUEST:
PUT /s/-/dw/data/v24_5/customer_lists/4711/customers/0815 HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8
{
   "_resource_state" : "not_exists",
   "email" : "dude@salesforce.com",
   ...
}

# when a customer with that ID already exists

RESPONSE:
HTTP/1.1 409 CONFLICT
Content-Type: application/json;charset=UTF-8
{
  "_v" : "24.5",
   "_type" : "fault",
  "fault" : {
    "type" : "ResourceAlreadyExistsException",
    "message" : "Resource already exists, state is 'ab12cd34'."
  }
}

```

<!-- document id=49385e511811c25d66e4ac39448c01bd0adca3dca2e664cc33ba24b04da38078 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/sessionbridge.md -->

# OCAPI Session Bridge

To allow seamless interaction between OCAPI and your session-based storefront we offer the OCAPI session bridge. It allows you to obtain a JWT for a session and vice versa without having to reauthenticate the customer.

Technically the bridge consists of two resources:

1.  Request a JWT for a session via `/customers/auth` resource.

2.  Request a session for a JWT via `/sessions` resource.

## Obtain JWT

To obtain a JWT for a _guest_ or _registered_ customer you have to pass a valid _dwsid_ cookie to `/customers/auth` resource. You have to use `"type":"session"`. If you haven't enabled the global security preference Enforce HTTPS, you must also pass a valid _dwsecuretoken_ in the request. If successful, you get the JWT back as _Authorization:Bearer_ response header.

The following sample shows how this approach works when the global security preference Enforce HTTPS isn't enabled and the `dwsecuretoken` is included in the request.

```txt
REQUEST:
POST /dw/shop/v24_5/customers/auth
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
x-dw-client-id: [your_own_client_id]
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==;
        dwsecuretoken_9727b83e8e864fa4b6902a37bc70a12d=5Kx5-2P7jj5WoxeTiWwHNBJ6QV39Io5SNA==;

{
  "type" : "session"
}

RESPONSE:
HTTP/1.1 200 OK
Content-Length:124
Authorization:Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX
Content-Type:application/json;charset=UTF-8

{
   "_v" : "24.5",
   "_type" : "customer",
   "auth_type" : "guest",
   "customer_id" : "abdtkZzH6sqInJGIHNR1yUw90A",
   "preferred_locale" : "default"
}
```

When the global security preference Enforce HTTPS is enabled, the request would be similar to this example, which doesn't include a `dwsecuretoken`:

```txt
REQUEST:
POST /dw/shop/v24_5/customers/auth
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
x-dw-client-id: [your_own_client_id]
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==

{
  "type" : "session"
}
```

Note: There’s no tight coupling between session and JWT. You get different tokens for multiple requests with the same session. Therefore, you should make only one call per session.

For more details see /customers/auth resource.

<!--TODO: Fix link post migration -->
<!-- For more details see [/customers/auth](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/shop/resources/customers.md) resource.
 -->

## Obtain Session

To obtain a session for a _guest_ or _registered_ customer you have to pass a valid JWT to `/sessions` resource. The JWT has to be passed as _Authorization:Bearer_ request header. If successful, you get the session cookies back.

If you haven't enabled the global security preference Enforce HTTPS, the response includes a Set-Cookie header for a `dwsecuretoken`. The Set-Cookie header for a _dwsecuretoken_ isn't included in the response if the global security preference Enforce HTTPS is enabled.

The following sample shows how this approach works when the global security preference Enforce HTTPS isn't enabled and the `dwsecuretoken` is included as a Set-Cookie header in the response.

```txt
REQUEST:
POST /dw/shop/v24_5/sessions HTTP/1.1
Host: example.com
x-dw-client-id: [your_own_client_id]
Authorization: Bearer eyJfdiI6IjXXXXXX.eyJfdiI6IjEiLCJleHAXXXXXXX.-d5wQW4c4O4wt-Zkl7_fiEiALW1XXXX

RESPONSE:
HTTP/1.1 204 NO CONTENT
Set-Cookie : dwsecuretoken_a85a5236a2e852d714eb6f1585efb61c=""; Expires=Thu, 01-Jan-1970 00:00:10 GMT;
Set-Cookie : dwsid=eXv5R3FZGI4BBfbK1Opk5s1mJ-41Aw7ZuaMKxeye5xa16fJMX--AnNkXsvmakbi1UZSzP1zoPmUILgoom1_jKg==;
Set-Cookie : dwanonymous_a85a5236a2e852d714eb6f1585efb61c=bdjalnzmfrkJ0FtYliwud5db67; Max-Age=15552000;
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
```

When the global security preference Enforce HTTPS is enabled, the response would be similar to this example, which doesn't include a Set-Cookie header for a _dwsecuretoken_.

```txt
REQUEST:
POST /dw/shop/v24_5/customers/auth
Host: example.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
x-dw-client-id: [your_own_client_id]
Cookie: dwsid=pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==

{
  "type" : "session"
}
```

Note: There’s no tight coupling between session and JWT. You get different sessions for multiple requests with the same JWT. Means, you should make only one call per JWT.

For more details see /sessions resource.

<!--TODO: Fix link post migration -->
<!-- For more details see [/sessions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/shop/resources/sessions.md) resource.
 -->

<!-- document id=9149386924cb63fac026b89f972c445e7ba07fa47e6dd3dca082d417bc18df8a url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/ocapisettings.md -->

# OCAPI Settings

**note:** Starting September 1, 2026, OCAPI settings will no longer be made available for realms provisioned for new customers. New customers should use [SCAPI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/why-use-scapi.html) (the Salesforce Commerce API) as the REST API of choice for all custom implementations. Existing customers who provision a new realm after this date and need OCAPI settings enabled can file a support ticket to request access.

OCAPI settings manage various features, for example, to control OCAPI client permissions, and to control [OCAPI caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/caching.md).

You configure OCAPI settings in Business Manager. To specify OCAPI settings, you edit one or more JSON documents that conform to the format described later in this topic.

## Configuring OCAPI Settings in Business Manager

To configure OCAPI settings, perform the following steps:

1.  In Business Manager: **Administration > Site Development > Open Commerce API Settings**.
2.  In the **Select type** field, select the API type for the configuration.
3.  In the **Select context** field, select the context for the configuration: Global for the configuration to affect all sites in the organization, or the name of a site for the configuration to affect only that site.
4.  In the text field, edit the JSON document.
5.  Click **Save**.

**note:** You can override global settings for specific sites. Your settings are cached for up to three minutes until they become effective.

## Site-Specific Vs. Global Settings:

Client settings and permissions can be defined for a single site (site-specific) or for all sites (global). You can override global settings for Client ID per site.

**note:** Most Data API resources are organization-specific, so they support only global client permissions.

## Client Permissions:

To use OCAPI, you must first configure client permissions. These permissions control read and write access to specified resources. By default, no permission is granted. OCAPI declines any client application request that doesn’t have the appropriate permissions, returning an HTTP status of 401 (Unauthorized).

## JSON Document Format

The following example shows the format of the JSON document:

**note:** The "\_v" property indicates the version of the configuration file structure. It’s independent of the OCAPI version, and thus allows the configuration of resources in any OCAPI version.

```json
{
  "_v": "24.5",
  "clients": [
    {
      "allowed_origins": ["http://www.sitegenesis.com", "https://secure.sitegenesis.com"],
      "client_id": "[your_own_client_id]",
      "response_headers": {
        "x-foo": "bar",
        "P3P": "CP=\"NOI ADM DEV PSAi COM NAV OUR OTR STP IND DEM\""
      },
      "resources": [
        {
          "resource_id": "/product_search",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(**)",
          "cache_time": 900,
          "version_range": { "from": "24.5" }
        },
        {
          "resource_id": "/products/*/bundled_products",
          "methods": ["get"],
          "read_attributes": "(c_name,c_street)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/baskets/*/items",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(product_id, quantity)"
        }
      ]
    }
  ]
}
```

## Configuration Document

Use this document to configure Open Commerce API permissions for multiple client applications in the context of a single site.

| Property  | Type                                         | Constraints | Description                                                                                                                                                                                                                           |
| --------- | -------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_v`      | String                                       | N/A         | Version number of the configuration file structure. New versions are created when JSON properties are added or the behavior of a property changes. Use the most recent version of the configuration file structure whenever possible. |
| `clients` | [[Client](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md#client-document)] | N/A         | Array of client-specific permission documents.                                                                                                                                                                                        |

## Client Document

Use this document to view the Open Commerce API permissions for a client application.

| Property           | Type                                             | Constraints                    | Description                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allowed_origins`  | [String]                                         | N/A                            | Array of allowed origins used in [CORS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/cors.md) requests.                                                                                                                                    |
| `client_id`        | String                                           | mandatory=true, nullable=false | Client application id.                                                                                                                                                                        |
| `response_headers` | Map&lt;String,String&gt;                         | N/A                            | Map of custom response header name/value pairs. Supported headers are 'P3P' and custom headers starting with 'X-'. Custom Commerce Cloud Digital headers starting with 'X-DW' aren’t allowed. |
| `resources`        | [[Resource](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md#resource-document)] | N/A                            | Array of resource-specific permission documents.                                                                                                                                              |

## Resource Document

Use this document to configure resource-specific permissions and settings.

| Property                       | Type                                                     | Constraints                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------ | -------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cache_time`                   | Integer                                                  | N/A                            | Time period in seconds before the response document becomes stale. The minimum cache time is 0 seconds; the maximum is 86,400 seconds (24 hours). If no value is specified, the default is 60 seconds. For more information, see [caching.](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/caching.md)                                                                                                                                                                                                                                       |
| `config`                       | Map&lt;String,String&gt;                                 | N/A                            | Map that determines which values are returned for some special response document properties. You control this map by configuring reserved key/value pairs. For more information, see [Customization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md#customization).                                                                                                                                                                                                                                                         |
| `methods`                      | [String]                                                 | mandatory=true, nullable=false | Open Commerce API HTTP method filter. For example, the filter `["get","patch"]` allows access to the _GET_ and _PATCH_ method for the specified resource path. You can specify methods that are supported for a resource. You can list all available resources and methods for the Shop API, version 24.5, with the following metadata call: `http://{your-domain}/dw/meta/rest/shop/v24_5?client_id={your-client-id}`                                                                        |
| `personalized_caching_enabled` | Boolean                                                  | N/A                            | Flag that determines the personalized caching behavior of a cacheable Shop API resource. By default, the system caches personalized resources when a customer context (JWT) is given. You can use this property to explicitly disable personalized caching (for example, for performance improvements). Disable personalized caching only if responses are guaranteed to be the same for any customer and no further personalization logic (for example, in hooks) applies.                   |
| `read_attributes`              | String                                                   | N/A                            | String that controls which properties are included in the response document. The configuration value must be specified using [property selection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/propertyselection.md) syntax.                                                                                                                                                                                                                                                                                                               |
| `resource_id`                  | String                                                   | mandatory=true, nullable=false | OCAPI resource identifier. For example: `/products/*/images` or `/products/specific_id/images`. This property supports Ant path style to describe resource IDs. You can specify wildcards or specific product IDs; you can also specify the pattern `/products/**` to access to all available subresources. You can list all resource identifiers for the Shop API, version 24.5, with the following metadata call: `http://{your-domain}/dw/meta/rest/shop/v24_5?client_id={your-client-id}` |
| `version_range`                | [[VersionRange](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md#versionrange-document)] | N/A                            | Array of VersionRange documents granting permissions only to a subset of OCAPI versions.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `write_attributes`             | String                                                   | N/A                            | String that controls which properties can be included in the request document. The configuration value must be specified using [property selection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/propertyselection.md) syntax.                                                                                                                                                                                                                                                                                                             |

## VersionRange Document

Use this document to grant resource permissions only to a subset of Open Commerce API versions. You can use the properties `from` and `until` to define the range. At least one must be specified.

| Property | Type   | Constraints | Description                                                                                                                                                                                                                                                                                |
| -------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `from`   | String | N/A         | From version (for example, _24.5_). If you don't specify the `from` version, all versions earlier than the `until` version are accessible.                                                                                                                                                 |
| `until`  | String | N/A         | Until version (for example, _24.5_). The `until` version isn’t included in the range. (For example, if the `until` version is 19.3, then 19.1 is the latest included version.) If you don't specify the `until` version, then all versions, including the most recent one, are accessible. |

## Expansions

Resources that support expansion technique are handled as any other resource. Therefore, if you want to restrict access to product image information, configure independent client permissions for each resource: the products base resource `/products/*`, and the images subresource `/products/*/images`.

## Customization

The Open Commerce API enables you to customize how some data is returned. You can set properties for the following resources:

- `/product_search/images` (Shop API)
- `/products/*/availability` (Shop API)
- `/products/*/prices` (Shop API)
- `/search_suggestion` (Shop API)

`/product_search/images` (Shop API)

You can customize how image information is returned by configuring the image view types for certain image properties. There are three reserved key/value pairs for this resource:

- "`search_result.hits.image:view_type":"detail"`
- `"search_result.variation_attributes.values.image:view_type":"thumbnail"`
- `"search_result.variation_attributes.values.image_swatch:view_type":"swatch"`

Those properties define the actual image view types. Based on the view type, the Shop API returns the desired image information. If the view_type isn’t set or if the view_type is unknown, the image properties aren’t part of the response. For example:

```json
...
{
    "resource_id":"/product_search/images",
    "methods":["get"],
    "read_attributes":"(**)",
    "write_attributes":"(**)",
    "config":{
        "search_result.hits.image:view_type":"detail",    // use view type "detail" for property "image" in document "ProductSearchHit"
        "search_result.variation_attributes.values.image:view_type":"detail",
        "search_result.variation_attributes.values.image_swatch:view_type":"swatch"
    }
},
...
```

`/products/*/availability` (Shop API)

You can configure max thresholds (returned by the Shop API) to hide real ATS and stock levels. There are two reserved key/value pairs for this resource:

- "`product.inventory.ats.max_threshold":"100"`
- `"product.inventory.stock_level.max_threshold":"50"`

ATS and stock levels are sensitive information for merchants. If these properties aren’t set, the API response properties have the default value 999999.

`/products/*/prices` (Shop API)

You can configure which price book prices are exposed in the `product.prices` property. There’s one reserved key/value pair for this resource:

- "`product.prices.price_book_ids":"usd-list-prices,usd-sale-prices"`

If no price book is defined, the property isn’t part of the response.

`/search_suggestion` (Shop API)

You can customize how image information is returned by configuring the image view types for certain image properties. There are three reserved key/value pairs for this resource:

- "`suggestion.product.image:view_type":"small"`

Those properties define the actual image view types. Based on the view type, the Shop API returns the desired image information. If the view_type isn’t set or if the view_type is unknown, the image properties aren’t part of the response. For example:

```json
...
{
    "resource_id":"/search_suggestion",
    "methods":["get"],
    "read_attributes":"(**)",
    "write_attributes":"(**)",
    "cache_time":900,
    "config":{
        "suggestion.product.image:view_type":"small"
    }
},
...
```

<!-- document id=24cce34eb9be753c6fe44f62d6aaa5cab9e7f57ae2ffc85ef35b83e536164554 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/systemjobs.md -->

# OCAPI System Jobs

System jobs are predefined jobs called via the following OCAPI request:

```txt
POST dw/data/v24_5/jobs/{job_id}/executions
```

Calling this resource triggers a background job and retrieves a response document containing information about the job's status. Different System Jobs can use different request payloads.

The job ID always starts with `sfcc-`. This prefix is a namespace specific to B2C Commerce System Jobs. You can’t use it in custom job IDs.

Currently available system jobs can be found in [Global Jobs](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/globaljobs.md).

A System Job request looks like a basic OCAPI Data API request, but can have its own request document. An example is shown here for the site archive import job:

```txt
REQUEST:
      POST /dw/data/v24_5/jobs/sfcc-site-archive-import/executions HTTP/1.1
      Host: example.com
      Accept: application/json
      Authorization: Bearer <access_token>
      {
          "file_name": "siteGenesis.zip",
          "mode": "merge"
      }

      RESPONSE:
      HTTP/1.1 202 ACCEPTED
      Content-Type: application/json;charset=UTF-8
      Content-Length: 741
      {
          "_v" : "24.5",
          _type": "job_execution",
          "client_id": "[your_own_client_id]",
          "execution_status": "pending",
          "id": "42",
          "is_log_file_existing": false,
          "is_restart": false,
          "job_id": "sfcc-site-archive-import",
          "log_file_name": "Job-sfcc-site-archive-import-20170512142357242.log",
          "modification_time": "2017-05-12T14:23:57.316Z",
          "parameters": [ {
            "_type": "job_execution_parameter",
            "name": "ImportMode",
            "value": "merge"
          }, {
            "_type": "job_execution_parameter",
            "name": "ImportFile",
            "value": "siteGenesis.zip"
          } ],
          "status": "PENDING"
      }
```

<!-- document id=c7ac7b9759804b2c0887fbc396674451b6cd3a06476a7e5d0e3be47d58a30a59 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/urlschema.md -->

# OCAPI URL Syntax

The Open Commerce API uses a specialized schema for its URLs, and each URL consists of a base URL and an extended URL. The base URL is the same for all API requests; the extended URL changes depending on the resource and the operation. To access the Open Commerce API's functionality, you construct URLs as described below.

## Base URL

The base URL has a different structure depending on whether you’re using a production instance or a non-production instance (including staging, development, and sandboxes). For a production instance, the base URL has the following structure:

```txt
http(s)://{public_domain}[/s/site_id]/dw/{api_type}/
```

For more information about aliases, see Hostname Aliases. For a non-production instance, the base URL has the following structure:

<!--TODO: Fix link post migration -->
<!-- For more information about aliases, see [Hostname Aliases](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/search-engine-optimization/b2c-hostname-aliases.md). For a non-production instance, the base URL has the following structure:
 -->

```txt
http(s)://{domain}/s/{site_id}/dw/{api_type}/
```

where `{api_type}` is either `shop`, `data`, or `meta`; `{public_domain}` is the DNS name mapped to the Commerce Cloud Digital site (for example, www.example.com); and `{site_id}` is the ID of the actual site to be used (for example, SiteGenesis).

## Extended URL

The base URL provides the main access point of the Open Commerce API. You extend the base URL to access specific resources. When you extend the base URL, you must conform to the following patterns. The variables shown in these patterns are described below.

The first pattern addresses multiple resources of a resource type:

```txt
{base_url}/{version_id}/{resource_type}
```

The second addresses a single resource using an identifier:

```txt
{base_url}/{version_id}/{resource_type}/{identifier}
```

The third addresses resource information by specifying an action:

```txt
base_url/{version_id}/{resource_type}/{action}
```

The fourth addresses multiple instances of dependent resources:

```txt
base_url/{version_id}/{resource_type}/{identifier}/{relationship_type}
```

The fifth addresses information from a dependent resource by specifying an identifier:

```txt
base_url/{version_id}/{resource_type}/{identifier}/{relationship_type}/{relationship_type_identifier}
```

The sixth addresses information from a dependent resource by specifying an action:

```txt
base_url/{version_id}/{resource_type}/{identifier}/{relationship_type}/{action}
```

**note:** Use only ASCII characters in your URLs; escape any reserved ASCII characters by using the common "%" notation.

### Version ID

The `{version_id}` specifies the API version. Each API version supports a set of resource types (`{resource_type}`), resource properties, relation types (`{relationship_type}`), and actions (`{action}`). A new API version can add new resource types, add properties to existing resource types, deprecate previously supported resource types, and introduce new semantics or behaviors without introducing structural changes.

The `{version_id}` starts with the character "v" (lowercase) followed by the actual version number, separated by an underscore. For example:

```txt
http://example.com/dw/shop/v24_5/{resource_type}/{identifier}

```

### Resource Type

Resource types (`{resource_type}`) are fundamental to the Open Commerce API, as they’re to any RESTful API. Each resource type has a corresponding set of data: properties, relationship types (`{relationship_type}`), and actions (`{action}`). An instance of a resource type is analogous to a Digital object, such as `Product` or `Basket`.

The Open Commerce API provides a fixed set of system resource types for each API version. Resource types that provide access to multiple resources are given plural names (for example, "products"). Resource types that provide access to only one resource are given singular names (for example, "site"). The following example URL retrieves resources of type `products` using an identifier (`{identifier}`):

```txt
http://example.com/dw/shop/v24_5/products/{identifier}

```

### Identifier

Unique identifiers (`{identifier}`) enable you to request specific resource instances. The following URL searches for product resources using an ID (typically a SKU):

```txt
GET http://example.com/dw/shop/v24_5/products/123FOO456bar

```

The `{identifier}` must be URL encoded. The following encoded URL escapes a reserved ASCII character (the "#" character in "foo#bar"):

`GET http://example.com/dw/shop/v24_5/products/foo%23bar`

When you specify a value for `{identifier}`, make sure the value conforms to the following restriction:

- All values for `{identifier}` are case-sensitive.

### Multiple Identifiers

Some resource types, like products, support the request of multiple resources by specifying multiple identifiers in the request URL. When responding to such a request, the Open Commerce API returns a result object that includes an array of the requested resource documents.

The following example shows how to request multiple product resources:

```txt
GET http://example.com/dw/shop/v24_5/products/(123,456,789)
```

You must enclose the comma-delimited list of identifiers within parentheses.

### Action

Actions (`{action}`) operate on specific resource types (`{resource_type}`) and relationship types (`{relationship_type}`). Actions aren’t generally available across all resource types and relationship types. Actions perform special operations (for example, customer login).

The following example URL uses an action to authenticate a customer (this action is specific to the customers resource type):

```txt
POST http://example.com/dw/shop/v24_5/customers/auth
```

### Relationship Type

A relationship type (`{relationship_type}`) represents a resource type that depends on another resource type (`{resource_type}`). Relationship types enable the API to model one-to-many relationships between a single resource (for example, a `Product`) and multiple dependent resources (for example, `ProductLinks`). Each resource type can define a subset of relationship types, which are unique to the resource type.

The following example URL requests items for a basket:

```txt
GET http://example.com/dw/shop/v24_5/baskets/12345/items
```

This request returns all items for the basket with the ID "12345".

<!-- document id=9cf0e38d1f165fe376d95b79bb3b832d205a17cb95040b761c527bc77ff8ac6a url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/apiusage.md -->

# OCAPI Usage

Detailed information about using the Open Commerce API:

| Topic                                                                   | Description                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [API Explorer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/apiexplorer.md)                                          | You can interactively explore the Open Commerce APIs with API Explorer.                                                                                                                                                                                                                                           |
| [Batch requests](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/batchrequests.md)                                      | You can sometimes use a batch request (a multipart HTTP request that can contain up to 50 subrequests) instead of issuing multiple separate requests.                                                                                                                                                             |
| [Best practices](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/bestpractices.md)                                      | Useful tips for working with OCAPI.                                                                                                                                                                                                                                                                               |
| [Caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/caching.md)                                                   | You can build client-side application caches or leverage Proxy caches.                                                                                                                                                                                                                                            |
| [Client application identification](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/clientapplicationidentification.md) | You must ensure that your client application identifies itself for security and tracking purposes.                                                                                                                                                                                                                |
| [CORS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/cors.md)                                                         | You can take advantage of Cross-Origin Resource Sharing (CORS).                                                                                                                                                                                                                                                   |
| [Customization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/customization.md)                                       | You can customize OCAPI resources on server-side.                                                                                                                                                                                                                                                                 |
| [Custom properties](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/customproperties.md)                                | You can get access to customer properties of business objects.                                                                                                                                                                                                                                                    |
| [Expansions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/expansions.md)                                             | You can minimize network traffic and conserve server CPU usage by using a technique called expansion.                                                                                                                                                                                                             |
| [ExportDataUnitsConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/exportdataunitsconfiguration.md)         | Document representing a configuration for the data units which a site export needs to identify what exactly should be exported. All unit types (site specific, global, ...) which should be exported need to be set to ‘true‘. Units set to 'false' are simply ignored with this version and can also be skipped. |
| [ExportGlobalDataConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/exportglobaldataconfiguration.md)       | Document representing a configuration for the global data units which should be exported.                                                                                                                                                                                                                         |
| [ExportSitesConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/exportsitesconfiguration.md)                 | Document representing a configuration for the site specific data units which should be exported.                                                                                                                                                                                                                  |
| [Filtering](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/filtering.md)                                               | You can specify a filter on an API request to limit the number of items in the response.                                                                                                                                                                                                                          |
| [Flash](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/flash.md)                                                       | Document contains special information.                                                                                                                                                                                                                                                                            |
| [Global Exceptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/exceptions.md)                                      | Global exceptions thrown by OCAPI.                                                                                                                                                                                                                                                                                |
| [Global HTTP headers](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/http-headers.md)                                  | HTTP headers globally used by OCAPI.                                                                                                                                                                                                                                                                              |
| [Hook Circuit Breaker](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hookcircuitbreaker.md)                           | The Hook Circuit Breaker feature improves stability and saves processing time by protecting the system from high rates of hook failures.                                                                                                                                                                          |
| [HTTP methods](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/httpmethods.md)                                          | You create requests based on standard HTTP methods (as defined by RFC 2616).                                                                                                                                                                                                                                      |
| [HTTP status codes and faults](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/httpstatuscodesandfaults.md)             | You can diagnose problems or failures by examining HTTP status codes and faults.                                                                                                                                                                                                                                  |
| [Images](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/images.md)                                                     | You can retrieve images using absolute URLs.                                                                                                                                                                                                                                                                      |
| [Jobs: Global](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/globaljobs.md)                                           | You can run various global jobs.                                                                                                                                                                                                                                                                                  |
| [Jobs: System](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/systemjobs.md)                                           | Predefined jobs that can be called with an OCAPI request.                                                                                                                                                                                                                                                         |
| [JSONP](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jsonp.md)                                                       | You can request that the server returns a JSON document with a JavaScript function call wrapped around it.                                                                                                                                                                                                        |
| [JWT (JSON Web Token)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/jwt.md)                                          | The stateless Shop API uses JSON Web Tokens in its authentication mechanism.                                                                                                                                                                                                                                      |
| [Localization](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/localization.md)                                         | You can use the API in different locales.                                                                                                                                                                                                                                                                         |
| [Metadata](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/metadata.md)                                                 | You can request metadata about the API itself, such as the current version.                                                                                                                                                                                                                                       |
| [OAuth 2.0](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/oauth.md)                                                   | You have to authorize your Data API requests using the OAuth 2.0 protocol.                                                                                                                                                                                                                                        |
| [OCAPI settings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/ocapisettings.md)                                      | You can configure OCAPI settings in Business Manager by modifying a JSON data structure, enabling you to control client permissions, caching, and other resource-specific behaviors.                                                                                                                              |
| [Optimistic locking](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/optimisticlocking.md)                              | Describes the two optimistic locking mechanisms supported by OCAPI.                                                                                                                                                                                                                                               |
| [Pagination](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/pagination.md)                                             | You can use pagination to break up large responses into smaller chunks.                                                                                                                                                                                                                                           |
| [Property selection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/propertyselection.md)                              | You can use property selectors to limit which resource properties are returned.                                                                                                                                                                                                                                   |
| [Queries](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/queries.md)                                                   | You can use queries to be selective about data returned by OCAPI, which reduces network bandwidth.                                                                                                                                                                                                                |
| [Resource Data formats](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/dataformats.md)                                 | You can specify a preferred data format for resources (JSON or XML).                                                                                                                                                                                                                                              |
| [Resource States](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/resourcestates.md)                                    | Resource States can be used for Optimistic Locking, which prevents collisions of concurrent requests, for example, the "lost update" problem.                                                                                                                                                                     |
| [SearchIndexUpdatConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/searchindexupdateconfiguration.md)      | Configuration document for updating the search index.                                                                                                                                                                                                                                                             |
| [Session bridge](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/sessionbridge.md)                                      | Allows seamless interaction between OCAPI and a session-based storefront.                                                                                                                                                                                                                                         |
| [SiteArchiveExportConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/sitearchiveexportconfiguration.md)     | Input document for site archive export system job.                                                                                                                                                                                                                                                                |
| [SiteArchiveImportConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/sitearchiveimportconfiguration.md)     | Input document for site archive import system job.                                                                                                                                                                                                                                                                |
| [URL syntax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/urlschema.md)                                              | You must create appropriately constructed URLs to operate on resources.                                                                                                                                                                                                                                           |
| [Versioning and deprecation policy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/versioninganddeprecationpolicy.md)  | You must ensure that your application conforms to the versioning and deprecation policy.                                                                                                                                                                                                                          |

<!-- document id=f39552c6bc7ef1d787e44ac3fdf7a732c33738d0db9a73d2c07b51f37566f18d url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/versioninganddeprecationpolicy.md -->

# OCAPI Versioning and Deprecation Policy

This document describes the versioning and deprecation policy for the Open Commerce API (OCAPI). This policy is designed to

- Be easy for customers and developers to understand
- Allow Commerce Cloud Digital to make design changes to the API without affecting existing client applications
- Allow Digital to delete outdated or unsupported features

## Version Creation and Deprecation

A new OCAPI version is created whenever Digital:

- Adds a new document property, resource parameter, or resource.
- Modifies the type of a document property, resource parameter, or resource.
- Modifies the name of a document property, resource parameter, or resource.
- Deletes a document property, resource parameter, or resource.

Whenever Digital creates a new OCAPI version, it also deprecates the former OCAPI version. This encourages customers and developers to:

- Implement new client applications on top of the current OCAPI version.
- Upgrade existing applications on a regular basis.

## Version Numbers

Digital constructs OCAPI version numbers by taking the last two digits of the current year ("24" for 2024), adding a period (.), and adding consecutive numbers, starting with 1. For example, "24.1" is the first version of 2024.

Depending on the context, the version number is specified differently:

- In URLs, the following syntax is used: `v<year>_<consecutive number>`. For example: "v24_5".
- In documents, the following syntax is used:`<year>.<consecutive number>`. For example: "24.5".

**note:** Starting with B2C Commerce version 26.2, the platform provides a feature that strictly validates OCAPI version numbers.
Any OCAPI request using a version number with leading zeros is now rejected with a 400 Bad Request response
and an `InvalidVersionException` fault. Previously, version numbers containing leading zeros, for example: `v024_05` instead of `v24_5`, were accepted.
To enable this feature, contact your B2C Commerce Support representative.

## OCAPI Deprecation

OCAPI is deprecated as of April 2026. Salesforce continues to accept support requests and to provide bug fixes and security updates where applicable. OCAPI doesn't receive further innovations, consistent with the approach in place for the past 18 months.

Salesforce isn't establishing an end-of-life (EOL) date to retire OCAPI. This decision is subject to annual review. Salesforce sets any designated EOL date no earlier than two years from the date it formally decides to retire OCAPI.

## Version Metadata

OCAPI version metadata currently provides a list of version numbers, along with a `state` enum set to one of the following values: `current`, `deprecated`, `obsolete`

<!-- document id=7bb8c3d764e7b3cd33d059510de9b7c83ae5a34cd7861f80f40787e826e9886b url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/retrieve-delivery-pickup-dates-via-spi.md -->

# OmniChannel: Retrieving Delivery and Pickup Dates via SPI

Use the Point of Sale SPI so merchants can integrate delivery or pickup date retrieval with the Point of Sale app.

The POS app calls the SPI, requesting a list of available dates and including details such as cart products, fulfillment methods, shipping addresses, and addresses for each applicable item. The response provides an array of dates or an error message to be shown in the POS. Delivery and pickup dates can be set at the order level or for individual items in the cart.

## Prerequisites

- **Modern POS App Build:** 10.0.1 or greater
- **Platform Support:** iPad & iPhone
- **Offline Support:** No

**note:** For details on this SPI, see [DateTimeSlot SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/datetimeslot-spi?meta=Summary) in the Point of Sale reference documentation.

For a comprehensive list of Point of Sale APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Configure Point of Sale CMS for Retrieving Delivery Dates with SPI

Integrate Point of Sale CMS with a date picker using a custom connector and SPI. In CMS, create a custom connector by specifying the endpoint name, API endpoint, integration type, and JSON headers.

1. In CMS, go to **Integrations** | **Custom Connectors**.
2. Click **Create**.
3. For Connector Type, select **SPI**.
4. For Endpoint Name, select **DATE_PICKER**.
5. For API Endpoint, enter the URL endpoint.
6. For Integration Type, select **HTTP_POST**.
7. Specify any JSON headers that must be passed.
8. Save your changes.

## Example Payload Request & Response

`POST/merchant/spi/sample/endpoint/sa/datetime/slots/from/external/system`

### Request

For single delivery or pickup dates in a cart, the SPI is called when the date picker is tapped in the cart. This call requests a list of available dates and includes details of the cart products, fulfillment methods, shipping addresses (if enabled), and addresses for each applicable item.

```java
{
  "address": {
  "addressLine1": "string",
  "addressLine2": "string",
  "city": "string",
  "countryCode": "string",
  "emailAddress": "string",
  "firstName": "string",
  "lastName": "string",
  "phone": "string",
  "postalCode": "string",
  "state": "string",
  "storeId": "string"
  },
  "datePickerType": "DELIVERY",
  "products": [
  {
  "productId": "string",
  "gtin": "string",
  "quantity": 0
  }
  ],
  "shippingMethodId": "string"
}
```

### Response

For single delivery or pickup dates in a cart, the response includes an array of dates or an error message to be shown in the POS. Times are optional; if none are sent, they aren't displayed in the app. If only one date is available, it's automatically selected. Merchants can also specify will-call for items that do not have a date available.

For multiple delivery or pickup dates in a cart, if selecting a date for all items in the cart, the app sends the full cart details to the SPI and return available dates to be applied to all items. Once a date is selected, it applies to all current line items in the cart. If selecting a date for just a single item in the cart, the app sends the full quantity of that item and return available dates that can be selected for that specific item.

```java
{
  "availableDate": 0,
  "dateTimeSlotType": "Delivery",
  "dateTimeSlots": [
  {
  "availableTimeSlots": [
  "string"
  ],
  "selectedTimeSlot": "09:00 - 12:00",
  "shippingMethodId": "string",
  "slotDate": 0,
  "slotId": "string"
  }
  ],
  "error": true,
  "errorCode": "INTERNAL_ERROR",
  "errorMessage": "Invalid request. Please check the request and try again.",
  "willCallDate": {
  "availableTimeSlots": [
  "string"
  ],
  "selectedTimeSlot": "09:00 - 12:00",
  "shippingMethodId": "string",
  "slotDate": 0,
  "slotId": "string"
  }
}
```

<!-- document id=05075fb3d4eb621c99ed2aa4a6906a7d30161530b6640e83fff1fb12d7d26490 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_ods_scheduler_intro.md -->

# On-Demand Sandbox Operation Scheduler

The Operation Scheduler gives you control over how many on-demand sandboxes (ODS) are active and for how long. Because ODS instances are based on usage, the scheduler helps manage consumption in the form of credits available to you. Define realm-level and instance-level stop and start schedulers.

Realm-level schedulers apply to any sandbox in a realm, provided you turn on the schedule for each sandbox. Individual sandbox schedulers control individual sandbox availability, which gives you granular control over resource management beyond the existing realm-level scheduling.

Review the differences of each ODS scheduler type.

| Feature  | Realm Scheduler                                                                                                              | Individual Sandbox Scheduler                                                                                                                                       |
| -------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Scope    | Applies to all on-demand sandboxes in a realm where the schedule is active.                                                  | Applies only to a single, specific on-demand sandbox instance.                                                                                                     |
| Control  | Sets a global start and stop schedule across a group of sandboxes.                                                           | Sets specific time, day, and operation settings for one instance.                                                                                                  |
| Override | Superseded by any individual sandbox schedule.                                                                               | Any individual sandbox level overrides the corresponding realm scheduler settings for that specific sandbox.                                                       |
| Use      | Ideal for setting a company-wide or department-wide standard schedule. For example, stop all instances after business hours. | Ideal for creating exceptions to the realm schedule for teams in different time zones or for mission-critical sandboxes that require specific operational windows. |

<!-- document id=b74c56fad301d17856f2f779d8da9a9d0e22d970271d0e9c10d2536e73772aa3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/sandboxes/b2c-developer-sandboxes.md -->

# On-Demand Sandboxes

Create and manage your own sandbox environments as you need them.

## What Is an On-Demand Sandbox?

An on-demand sandbox is a public-cloud-based sandbox. When you use on-demand sandboxes, expand your sandbox usage when required and roll back usage during slow periods.

To access an on-demand sandbox, you must purchase sandbox credits, enable appropriate permissions and users, and configure a client API ID. Then use the self-service API to create the sandbox environments yourself. Using the API, control how many on-demand sandboxes you use and how long the on-demand sandboxes are active.

Permissions for creating and managing on-demand sandboxes are integrated with B2C Commerce Account Manager. When you create an on-demand sandbox, specify Open Commerce API and WebDav permissions. Specify a time-to-live (TTL) value to automatically delete a sandbox after a specified time interval.

When you create an on-demand sandbox, it's empty, but use the standard import and export tools to import data.

You can't directly migrate from a POD-based sandbox to an on-demand sandbox. But you can export data and code from a POD sandbox, and then import the data and code into an on-demand sandbox.

## Use On-Demand Sandbox Credits Efficiently

The credit system provides flexibility so you can use the credits that you purchase the way you want. For example, depending on your needs, keep just a few sandboxes running for an extended period or create many short-term sandboxes.

Users assigned to the Sandbox API User role can control how credits are spent. When managing sandboxes and sandbox credits, keep these considerations in mind:

- When created or started, a sandbox begins consuming uptime in credits per minute. The number of credits a sandbox consumes per minute depends on which resource profile option a sandbox uses. For example, by default, sandboxes use a medium resource profile. A sandbox using the medium resource profile consumes 1 credit per minute or portion of a minute. A sandbox using a large or extra large resource profile consumes uptime credits at a higher rate.
- Stopped sandboxes consume fewer credits per minute. When stopped, regardless of which resource profile they use, all sandboxes consume downtime credits at a rate of 0.3 credits per minute or portion of a minute.
- When you delete a sandbox, it stops consuming credits.
- Sandboxes that are down due to technical issues, do _not_ consume credits.

Because sandboxes consume credits while in a stopped state, make sure to delete sandboxes you don't need. Then create them again when you want to use them.

Stop and restart sandboxes only when you want to retain the exact set of data that you created for the sandbox. To better manage sandboxes in a realm, set the sandbox `autoScheduled` parameter to `yes` and create an Operation Scheduler to automatically start and stop the sandboxes.

If you need a sandbox repeatedly for the same purpose, consider using APIs to automate creating a sandbox and importing the applicable data and code. Then quickly recreate the sandbox environment after it's deleted.

Import Storefront Reference Architecture (SFRA) into a sandbox using Business Manager. It isn’t necessary to keep a sandbox in the stopped state just to maintain an environment that uses SFRA.

## Time-to-Live (TTL) for On-Demand Sandboxes

When you create an on-demand sandbox, configure an optional Time-to-Live (TTL) value that specifies how many hours the sandbox lasts. For example, if the sandbox has a TTL of 24, the sandbox lasts for 24 hours and then is automatically deleted.

### TTL for a Sandbox

The maximum TTL for a sandbox is 2160 hours. A sandbox with a TTL value of 0 or less lasts until it is deleted.

**important:** When the TTL value for a sandbox is reached, the sandbox is permanently deleted. Data from the sandbox is no longer available.

This snippet from the JSON body of a `POST/sandboxes` API call to create a sandbox sets the TTL value of the sandbox to 100 hours.

```
{
  "realm": "{\<your realm id>}",
  "ttl": 100,

      }

```

After a sandbox is created, change its TTL value using a `PATCH/sandboxes` API call. This snippet from the JSON body of a `PATCH/sandboxes{sandboxId}` API call updates the TTL to 0, specifying that the sandbox lasts until it is deleted using a `DELETE /sandboxes/{sandboxId}` call.

```
{

  "ttl": 0,

      }

```

In the [B2C Commerce Developer Sandbox REST API](https://admin.dx.commercecloud.salesforce.com/) Swagger UI, the example to create a sandbox with a `POST/sandboxes` API call uses a TTL value of 24. If you don't change the TTL in the example request body, the sandbox is created with a TTL of 24 hours. To use a different TTL, update the `ttl` value in the example before clicking **Try it out**.

![Sandbox API Swagger UI showing a POST/sandboxes request body with a TTL value of 24 hours](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_swagger_u_ipost.png)

### TTL for the Realm

Every realm has settings for default TTL and maximum TTL for all sandboxes in the realm. The default TTL for the realm is 24 hours. To change the default TTL for the realm, use a `PATCH/realms/{realm}/configuration` API call. Override the realm default for any sandbox in the realm by setting the TTL for that sandbox to a different value.

The default maximum TTL setting for a realm is 0, indicating that no maximum has been set. Set a maximum TTL, up to 2160 hours, for all sandboxes in the realm using a `PATCH/realms/{realm}/configuration` API call. When a default maximum TTL is set for the realm, you get an error if you try to create a sandbox in the realm with a TTL higher than the maximum.

### Best Practices for TTL

If you need a sandbox for a short-term use, specify a TTL that covers only the time required. If your project has an uncertain end date, configure the TTL as 0 or less so that the sandbox lasts until you delete it. As an alternative, use a large TTL, such as 2100 hours, but then manually delete the sandbox when the project is completed.

In the [B2C Commerce Developer Sandbox REST API](https://admin.dx.commercecloud.salesforce.com/) Swagger UI, the example to create a sandbox with a `POST/sandboxes` API call uses a TTL value of 24. If you use the **Try it out** feature to create a sandbox from the Swagger UI and don't change the TTL in the example request body, the sandbox has a TTL of 24 hours. To use a different TTL, update the `ttl` value in the Example before clicking **Try it out**.

## On-Demand Sandbox Maintenance Window

To keep sandbox environments stable and reliable, we reserved two fixed maintenance windows for deployments and maintenance operations that can cause short interruption of operation to On-Demand Sandboxes.

- Tuesday or Thursday, 5:00 AM to 7:00 AM CET - B2C Commerce Preview and Preview Update releases.
- Thursday, 7:00 AM to 9:00 AM CET - CCDX Sandbox infrastructure and platform updates.

We don't use the maintenance window every week. When we plan to make updates during the maintenance window, we post advanced notification in the Salesforce Trust Center.

## On-Demand Sandbox Storage

On-demand sandbox storage size can vary depending on the resource profile that the sandbox uses.

By default, each on-demand sandbox has 10 GB of storage and an extra 10 GB of storage available on the realm that all on-demand sandboxes can share. However, assign one of the following discrete profiles to each on-demand sandbox according to your performance needs. This table describes the storage settings for each resource profile.

**note:** Sandboxes without login activity for 150 days might be deleted. We will notify you before a sandbox and its data are scheduled to be deleted.

| Resource Profile   | Storage |
| ------------------ | ------- |
| `medium` (Default) | 10 GB   |
| `large`            | 20 GB   |
| `xlarge`           | 50 GB   |
| `xxlarge`.         | 100 GB  |

## On-Demand Sandbox Log Files

Log messages for on-demand sandboxes are collected in a dedicated log center.

View the logs for the realms that you have access to based on your role.

## Additional On-Demand Sandboxes Resources

We've prepared some resources to help you optimize your experience with On-Demand Sandboxes.

- [On-Demand Sandboxes Webinar Slide Deck](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/B2CCommerceOn-DemandSandboxesCustomerWebinarSlides.pdf): Use this webinar slide deck to learn more about Salesforce B2C Commerce On-Demand Sandboxes.
- [B2C Commerce On-Demand Sandboxes FAQ](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/B2CCommerceOn-DemandSandboxesFAQ-Customers_new.pdf): Use this FAQ to get answers to common questions about On-Demand Sandboxes.
- [B2C Commerce On-Demand Sandbox Demo Videos](https://salesforce.vidyard.com/watch/vd55yAHz6s4VsxK9foP5CC): Watch On-Demand Sandbox REST API Swagger UI and On-Demand Sandbox Salesforce Commerce Cloud Command Line Interface (SFCC-CI) demos.
- [B2C Commerce On-Demand Sandbox Credits Calculator](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/B2CCommerceOn-DemandSandboxCreditsCalculator.xlsx): This Microsoft Excel spreadsheet provides an example for calculating On-Demand Sandbox credits. Download the file, make a copy, and use it for your own calculations.

<!-- document id=02575aebec5b05be6843d5851c53b65ca2179e1ab9b40a875479900e847d02d5 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-perf-section.md -->

# Optimize the Performance of Storefront Next

Optimize the performance of Storefront Next using best practices. Track Storefront Next performance during development and after it's deployed using monitoring tools.

In this section:

- [Performance Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-performance.md)
- [Monitor the Performance of Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-perf-tools.md)
- [SEO URL Rules Best Practices for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-seo-url-rules-best-practices.md)

<!-- document id=006014f2aea3946baf10380d6e735c585f0f2ddec6c72b6fce686aca1170eccd url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-order-calculation.md -->

# Order Calculation

Customer Service Center uses the same order calculation routines for pricing, taxes, shipping charges, and promotions as B2C Commerce. The current SiteGenesis application contains a registration for basket (order) calculation.

The calculation logic location depends on the version of SiteGenesis Storefront Core cartridge used by the B2C Commerce site.

If you're using the current SiteGenesis version, the calculation logic is in the hook and the script calls:

```
dw.system.HookMgr.callHook( "dw.ocapi.shop.basket.calculate", "calculate", pdict.Basket );
```

If you're using an older version of SiteGenesis, you register the calculate hook to call the CalculateCart.ds file.

```json
{
  "hooks": [{ "name": "dw.ocapi.shop.basket.calculate", "script": "./cart/CalculateCart.ds" }]
}
```

See dw.order/hooks in the Infocenter's B2C Commerce Scripts main topic.

<!-- document id=00049f7647e532f5031d31ffc8a7f0800a3957f135f2ca57d8a8618da3e83cf9 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-order-confirmation.md -->

# Order Confirmation

### Overview

The Order Confirmation page is shown immediately after a successful checkout and order placement. The page presents a summary of the completed order, including:

- Order number
- Purchased line items
- Pricing totals
- Shipping address
- Payment summary

The storefront retrieves the order summary using either the order reference number or the order summary ID, both of which are supported by the Order Summary APIs.

This flow demonstrates how a headless storefront can render order confirmation experiences, including order summaries, purchased items, pricing totals, shipping details, and payment information, using B2B Commerce Order Summary APIs.

![Order Confirmation Buyer Journey](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-order-confirmation-buyer-journey-26-1.png '{"class": "image-lg", "title": "Order Confirmation Buyer Journey"}')

### B2B Commerce APIs Used in the Flow

| Operation         | HTTP Method | Endpoint                                                                                                                                                                                                       |
| ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get order summary | POST        | [`/commerce/webstores/{webstoreId}/order-summaries/actions/lookup`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_lookup.htm) |

Some storefront implementations retrieve order data through multiple API calls, such as:

- GET [`/order-summaries/{orderSummaryId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary.htm)
- GET [`/order-summaries/{orderSummaryId}/items`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_shipment_items.htm)
- GET [`/order-summaries/{orderSummaryId}/delivery-groups`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_delivery_groups.htm)
- GET [`/order-summaries/{orderSummaryId}/adjustments-aggregates`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_adjustment_aggregates.htm)

A single call to POST [`/commerce/webstores/{webstoreId}/order-summaries/actions/lookup`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_lookup.htm) returns the complete order summary payload required by the Order Confirmation page in a single round trip. Prefer the lookup API approach to reduce network requests and improve page load performance.

### Buyer Journey

#### Render the Order Confirmation Page

1. Load the order confirmation page.

2. Call the following endpoint to retrieve the order summary:

   POST [`/commerce/webstores/{webstoreId}/order-summaries/actions/lookup`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_lookup.htm)

   Example request body:

   ```json
   {
     "orderSummaryIdOrRefNumber": "<order-id>"
   }
   ```

3. Pass either of the following values in `orderSummaryIdOrRefNumber`:

   - Order summary ID
   - Order reference number

4. Use the POST variant of the lookup endpoint for both authenticated and guest order lookup flows. The endpoint also supports a GET request with the identifier passed as a query parameter, but the POST request provides a consistent implementation path across buyer types.

5. Use the response to retrieve:

   - Order line items from `deliveryGroups[].lineItems`
   - Payment details from `payments[].paymentMethod.fields`
   - Currency information from `currencyIsoCode`
   - Order totals from the `totals` field map

6. Render the order confirmation experience using the response data.

7. Display the following sections on the page:
   - Ordered items
   - Order totals
   - Ship-to address
   - Payment information

### Extend the Flow

This flow allows buyers to recreate a previous order by adding items from the original order to an active cart.

- Add a View Order Details action to retrieve richer order item metadata using:

  GET [`/commerce/webstores/{webstoreId}/order-summaries/{orderSummaryId}/items?fields=...`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_items.htm) This endpoint requires a valid `orderSummaryId` rather than an order reference number. Resolve the summary ID from the initial order lookup response before calling the order items API.

- Add a Reorder action using:

  POST [`/commerce/webstores/{webstoreId}/order-summaries/actions/add-order-to-cart`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_add_order_to_cart_action.htm?q=add-order-to-cart)

  Example request body:

  ```json
  {
    "orderSummaryId": "<orderSummaryId>",
    "cartId": "<optionalCartId>"
  }
  ```

## See Also

- [_B2B Commerce Developer Guide_: B2B Commerce Order Summary APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-order-summaries-apis.html)

<!-- document id=502cfc8cc15cbb877fd62a978147e86d067e96b8ddcee06b7258837c7870dc90 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/order-details-data-mapping.md -->

# Order Details Data Mapping

The article below provides a data mapping table for the Order History and Order Refund pages in the POS app. It documents attributes displayed on both pages, listing the fields retrieved via the [GET Order SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) (ordersearchv2) for reference in the Return Workflow and Order History.

## Order History Data Mapping

| Subsection                | Label           | Data Mapping Key                                                                                                                    |
| ------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Order details cell        | Order Placed    | order.orderDate                                                                                                                     |
| Order details cell        | Order Status    | order.orderStatusText                                                                                                               |
| Order details cell        | Order Number    | order.displayOrderId                                                                                                                |
| Customer information cell | Store Associate | order.productList.salesAssociateAttribution.storeAssociateId <br>**Note:** Multiple store associate attributions are joined by ", " |
| Customer information cell | Phone           | order.customerProfile.phoneMobile <br>**Note:** Formatted to phone number format                                                    |
| Customer information cell | Address         | order.customerProfile.address.addressLine1                                                                                          |
| Customer information cell | Customer        | order.customerProfile.firstName order.customerProfile.lastName <br>**Note:** First name and last name joined by " "                 |
| Customer information cell | Email           | order.customerProfile.email                                                                                                         |
| Product cell              | Product Name    | order.productList[n].name                                                                                                           |
| Product cell              | Product ID      | order.productList[n].productId                                                                                                      |
| Product cell              | Product Image   | order.productList[n].imageURL                                                                                                       |
| Product cell              | Color           | order.productList[n].color                                                                                                          |
| Product cell              | Size            | order.productList[n].size                                                                                                           |
| Product cell              | Unit Price      | order.productList[n].price <br>**Note:** Key may change depending if store price and/or sale price is present                       |
| Product cell              | Quantity        | order.productList[n].quantity                                                                                                       |
| Product cell              | Subtotal        | order.productList[n].subtotal                                                                                                       |
| Product cell              | Status          | order.productList[n].orderStatusText                                                                                                |
| Order summary cell        | Subtotal        | order.orderSubTotal                                                                                                                 |
| Order summary cell        | Discount        | order.transactionDiscountAmount                                                                                                     |
| Order summary cell        | Net Subtotal    | order.taxableAmount                                                                                                                 |
| Order summary cell        | Shipping Costs  | order.shippingSubTotal                                                                                                              |
| Order summary cell        | Tax             | order.taxSubTotal <br>**Note:** If multiple taxes are applied, order.taxRates is used to list taxes                                 |
| Order summary cell        | Tax Exemption   | order.taxExemption                                                                                                                  |
| Order summary cell        | Rounding        | order.tenders[n].roundingAmount                                                                                                     |
| Order summary cell        | Tip             | order.tipTotal                                                                                                                      |
| Order summary cell        | Order Total     | order.totalAmount                                                                                                                   |
| Order status cell         | Order Status    | order.orderStatusText                                                                                                               |
| Payment method cell       | Tender Type     | order.tenders[n].paymentMethod                                                                                                      |
| Payment method cell       | Tender Amount   | order.tenders[n].amountAuthorized                                                                                                   |
| Notes                     | Notes           | order.notesList                                                                                                                     |

![Order History](https://developer.salesforce.com/docs/media/retail-cloud/screenshot-2024-01-25-at-4-20-51-pm.png)

## Order Refund Data Mapping

|                     |                |                                                                    |
| ------------------- | -------------- | ------------------------------------------------------------------ |
| Subsection          | Label          | Data Mapping Key                                                   |
| Order details cell  | Order Number   | order.orderID                                                      |
| Order details cell  | Shipped To     | order.billingName                                                  |
| Order details cell  | Payment method | order.tenders[n].paymentMethod                                     |
| Order details cell  | Address        | order.shippingAddress                                              |
| Order details cell  | Order Date     | order.orderDate                                                    |
| Return product cell | Product Name   | order.productList[n].name                                          |
| Return product cell | Product ID     | order.productList[n].productId                                     |
| Return product cell | Product Image  | order.productList[n].imageURL                                      |
| Return product cell | Color          | order.productList[n].color                                         |
| Return product cell | Size           | order.productList[n].size                                          |
| Return product cell | Unit price     | order.productList[n].price                                         |
| Return product cell | Quantity       | order.productList[n].quantity                                      |
| Return product cell | Subtotal       | order.productList[n].subtotal                                      |
| Refund summary cell | Subtotal       | subTotal **Note:** Sum of each selected refund products            |
| Refund summary cell | Discount       | discount **Note:** Sum of each selected refund products            |
| Refund summary cell | Net Subtotal   | subTotal - discount **Note:** Sum of each selected refund products |
| Refund summary cell | Tax            | tax **Note:** Sum of each selected refund products                 |
| Refund summary cell | Tax Exemption  | taxExemption **Note:** Sum of each selected refund products        |
| Refund summary cell | Refund Total   | total **Note:** Sum of each selected refund products               |

![Order Refund](https://developer.salesforce.com/docs/media/retail-cloud/screenshot-2024-01-25-at-4-22-12-pm.png)

<!-- document id=f6e98d109b9ff7ce88003eecbc1b935fc7d3f445a8cf16d35681f2d58e675972 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/order-management.md -->

# Order Management

Look up orders, manage order workflows with SPIs, and configure external order controllers for returns.

## In this section

- [Get Order SPI Reference](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/get-order-spi-reference.html)
- [Order Details Data Mapping](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/order-details-data-mapping.html)
- [Manage Orders with SPIs](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/manage-orders-with-spis.html)
- [Configure BORIS Order Controller](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/configure-boris-order-controller.html)

<!-- document id=053136efa9c3fa2f442564dd297cb2de88ddaaf401543024095de3f1aa115e8e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ordering/b2c-order-management-for-developers.md -->

# Order Management (Deprecated)

Using the Salesforce B2C Commerce APIs, customize your order processing functionality and payment processor methods. B2C Commerce also supports asynchronous payment methods.

Use the pipelet, GetPaymentProcessor, to establish the workflow to connect the payment method chosen by the customer (for example, credit card, bill-me-later, or bank card) to the payment processor defined through Business Manager. Use Studio to edit the pipelet.

Configure multiple payment instruments per basket/order. For example, an order can be associated with multiple credit cards, gift certificates, or other payment methods. The SiteGenesis application implements a scenario where customers can redeem multiple gift certificates and pay the remaining amount with a credit card or BillMeLater.

## Order Post-Processing APIs Deprecated

The order post-processing APIs, including the Gillian package, are inactive by default, except for merchants who are already using them. Attempting to use them when they’re inactive throws an exception. Merchants who are already using them, can contact [Salesforce B2C Commerce Support](https://help.salesforce.com/s/articleView?id=000383522&type=1) to activate these APIs. Since the APIs are deprecated, they are no longer supported and can only be used as is.

**note:** These APIs are unrelated to [Salesforce Order Management](https://help.salesforce.com/s/articleView?id=commerce.om_order_management.htm&type=5).

The following objects and APIs are inactive by default. The APIs are also at End of Adoption, and aren't enabled for new instances.

### Objects

- Appeasement
- AppeasementItem
- Invoice
- InvoiceItem
- Return
- ReturnCase
- ReturnCaseItem
- ReturnHooks
- ReturnItem
- ShippingOrder
- ShippingOrderHooks
- ShippingOrderItem
- dw.order.OrderItem
- dw.order.TrackingInfo
- dw.order.TrackingRef

### APIs

- dw.order.Order.getShippingOrders()
- dw.order.ProductLineItem.getOrderItem()
- dw.order.ShippingLineItem.getOrderItem()
- dw.order.Order.setOrderStatus(int)
- dw.order.Order.getShippingOrders()
- dw.order.Order.getShippingOrders()
- dw.order.Order.getShippingOrder(String)
- dw.order.Order.getShippingOrderItem(String)
- dw.order.Order.getShippingOrderItems()
- dw.order.Order.getReturnCases()
- dw.order.Order.getReturns()
- dw.order.Order.getReturn(String)
- dw.order.Order.getReturnItems()
- dw.order.Order.getReturnItem(String)
- dw.order.Order.getReturnCase(String)
- dw.order.Order.getReturnCaseItems()
- dw.order.Order.getReturnCaseItem(String)
- dw.order.Order.createReturnCase(String, boolean)
- dw.order.Order.createReturnCase(boolean)
- dw.order.Order.createServiceItem(String, String)
- dw.order.Order.createAppeasement(String)
- dw.order.Order.createAppeasement()
- dw.order.Order.createShippingOrder(String)
- dw.order.Order.createShippingOrder()
- dw.order.OrderMgr.createShippingOrders(Order)
- dw.order.Order.getInvoices()
- dw.order.Order.getInvoice(String)
- dw.order.Order.getInvoiceItems()
- dw.order.Order.getInvoiceItem(String)

### Create a Shipping Order

The Shipping Order Creation API has been optimized, making it possible to create `ShippingOrder`s and `ShippingOrderItems` with the B2C Commerce Script API. The allocation of inventory is now decoupled from the shipping order creation process. It's also possible to trigger the shipping order creation process from the B2C Commerce Script API by calling OrderMgr#createShippingOrders(Order order).

### Obsolete Basket Cleanup

Baskets have a _refID_ that stores customerID, agentID, or NULL. If the refID is NULL, the basket can be removed from B2C Commerce via a basket cleanup job. The basket ID is stored in the session dictionary to help differentiate between baskets restored and baskets restored previously.

### Update Orders After Placement Using the APIs

You might want to let an order management system cancel or open orders using the B2C Commerce APIs. When you cancel an order using the API, an entry is created in the order history, just as it is when you cancel an order through Business Manager. When you replace an order via the API, an entry is created in history that specifies the replacement's document number; while the replacement order contains information about the replaced order. If you cancel or replace an order via the API, the inventory availability for that order is updated.

**note:** The Gillian cartridge contains specific support for product bundles. All 'sent' notifications include information for the product bundle only, the bundled products are skipped.

## Asynchronous Payment Methods

Salesforce B2C Commerce uses specific APIs and order status to support order checkout processes that integrate with asynchronous payment method such as PayPal, iDeal, GlobalCollect, and many others.

Using an asynchronous method means that during order submission, the customer leaves the storefront and is redirected to the payment site. After successful payment completion, the customer is redirected to B2C Commerce where the order is created.

Order creation is separate from order placement using two pipelets: CreateOrder and PlaceOrder. The FailOrder pipelet is used to set the order status to FAILED.

Typical order processing is as follows:

1.  Order creation: CreateOrder
2.  Payment authorization
3.  Order placement: PlaceOrder

**note:** The basket is removed when the order is placed.

### Order Status: CANCELLED

The order can be canceled via the _CancelOrder_ pipelet and in Business Manager. This is what happens:

- Order status is set to CANCELLED
- Coupon redemptions are removed
- Product list purchases are removed
- Order history entry is created
- Inventory is released

### Order Status: CREATED

The order record is saved in B2C Commerce with the status CREATED before the payment is authorized. If the shopper doesn't return to the online store to complete order processing, a customer service representative (CSR), at the shopper's request, can use Business Manager to update the status of the order to NEW, which causes the order to move on to the fulfillment process.

**note:** The GMV for an order is calculated when the order is _processed_.

If a shopper continually navigates, invoking this part of the checkout process, B2C Commerce won't fill up with CREATED orders. Instead, an order is associated with a basket when it is created and is used if the customer returns to the beginning of the checkout process.

### Order Status: FAILED

When an order fails, the following occurs:

1.  Order status is set to FAILED.
2.  Coupon redemptions that were created are removed.
3.  Inventory reservations are canceled.

The FAILED status means that an order didn't successfully complete payment authorization and could not be placed. Although the order exists, it's marked as FAILED because a problem occurred that could not be recovered.

Orders with the FAILED status can't be reopened or canceled. The CancelOrder pipelet will abort on the error exit when it is executed on an order with the FAILED status. The pipelet returns the error status code: OrderProcessStatusCode.ORDER_ALREADY_FAILED.

However, a new order to replace the failed one can be placed. Using the FAILED status value, a customer service representative (CSR) can search in the Business Manager Ordering module to identify and manage failed orders.

### Order Journal

For asynchronous payment methods, the following pipelets create the corresponding action in B2C Commerce's order journal.

| Pipelet      | Action                         |
| ------------ | ------------------------------ |
| CreateOrder  | CREATE_FOR_AUTHORIZATIONCREATE |
| CreateOrder2 | CREATE_FOR_AUTHORIZATION       |
| FailOrder    | FAILED                         |

## APIs for Payment Processors/Methods

Access payment processor or method information using Salesforce B2C Commerce APIs and import/export this information using schemas. See the B2C Commerce API documentation for more information.

### Pipelets

Use these pipelets for payment-related transactions.

- AddPaymentInstrumentTobasket
- CreateBasketPaymentInstrument
- CreateCustomerPaymentInstrument
- CreatePaymentTransaction
- GetCustomerPaymentInstruments
- GetPaymentProcessor
- RemoveBasketPaymentInstrument
- RemoveCustomerPaymentInstrument
- VerifyCreditCard
- VerifyCreditCardExpirationDate
- VerifyCreditCardNumber
- VerifyPaymentCard
- VSAuthorizeCreditCard

### Scripting

Use these APIs from the **dw.order** package to process payment-related transactions.

- PaymentCard
- PaymentInstrument
- PaymentMethod
- PaymentMgr
- PaymentProcessor
- PaymentStatusCodes
- PaymentTransaction

## Basic Order Management Integration Framework

Certain system pipelines and API objects, along with the Gillian cartridge, available in the Salesforce Commerce Cloud GitHub repository, enable you to integrate automated order routing and payment processing capabilities into Salesforce B2C Commerce. You create the business logic that uses the objects.

**note:** Most of the functionality described in this topic isn't available in most implementations.

Use this functionality to:

- Create and export `ShippingOrders`
- Use an import to update the status of `ShippingOrders`

  When an error exists in an import file, the shipping order or the return imports fail. A file is created, using the original file name with a .BAD extension. Fix the error in the order import, rename the file with the original .xml extension, and then rerun the import. Properties unknown to the import specification (XSD) aren't included in the .BAD files; however, custom properties are included.

- Capture or refund payments
- Provide a self-service return merchandise authorization (RMA) and refund items once received
- Support partial delivery and capture based on either B2C Commerce inventory tables or an external inventory

Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Orders** > **order**. Track changes made by custom jobs or imports on shipping orders, invoices, or returns by clicking the Shipping Orders, Invoices, or Returns tabs, respectively. The information on these tabs is read-only. The tabs only appear when an order contains a shipping order, invoice, or return.

## Pipelines

The GillianJobs pipeline contains `CreateShippingOrders`, `ImportReturn`, and `UpdateShippingOrders`. You set up system job schedules to call the GillianJobs pipeline by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Operations** > **Schedules**. Configure the schedules with an Execution Scope of Sites (click **Sites**), with scheduled execution from between once every 30 minutes to once every 2 hours.

### API Objects

Use the following API objects to customize your order management processes:

| API object    | Description                                                                                                                                                                                                                                                                                                                                                 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ShippingOrder | Group of items that are shipped together. The content of a `ShippingOrder` is a subset of items of one `dw.order.Shipment`, and depends on inventory and custom code extensions such as warehouse optimization and dropship settings. Due to ShippingOrder update feeds, certain items of a ShippingOrder can be marked as shipped, canceled, or warehouse. |
| TrackingInfo  | TrackingInfo: contains a tracking#, shipping date, and carrier name, by default. Add custom attributes, for example, a tracking link. Link all shipped items of a `ShippingOrder` to one or more tracking details by calling the `addTrackingRef` method in ShippingOrderItem. This associates a shipped item with one or more `TrackingInfos.`             |
| Invoice       | Monetary representation of either a ShippingOrder, Return, or Appeasement. It's the base of any payment transaction (capture / refund).                                                                                                                                                                                                                     |
| ReturnCase    | Abstraction of an RMA. Every return without a ReturnCase reference is assigned to a new ReturnCase.                                                                                                                                                                                                                                                         |
| Return        | Container of items that were returned to the merchant. Depending on custom code implementations, certain actions such as a refund or an even exchange can be done.                                                                                                                                                                                          |

### Import

The file naming pattern for the import feeds for shipping order updates is:

`{Impex}/src/feeds/shippingorder/shipping_order_update_feed_SiteGenesis_20131101141905769_23.xml`

For the return import, the file naming pattern is:

`{Impex}/src/feeds/return/return_import_feed_SiteGenesis_20131101141905768_11.xml`

Appended to the file name are:

- The timestamp, precise to milliseconds
- An underscore
- An arbitrary number that represents a feed ID

### Export

When running a ShippingOrder export, define an XML structure of your own. Exports are handled in the sample code of createShippingOrder.ds.

In the Gillian sample script that creates shipping orders, a new shipping order is exported to a file. The export includes shipping order items, such as option and bundle items, in a hierarchical structure, with reference between the parent and child items. Use the new item type attribute to specify the child or parent type, as follows:

- PRODUCT
- OPTION
- BUNDLED_PRODUCT

<!-- document id=f1fcc0ed2a5efb3bff27c7f669341613b863ba4b079bef4a02a0d6df7d97c180 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/order-management-api.md -->

Order Management API

# Order Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/order-management-api/order-management-api-oas-public.yaml)

POS Merchant API to create, search, and retrieve orders from the POS system, and repost orders to external systems.

**Version:** 2.3.4

## Tags

### Order Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/order-management-api/order-management-api-oas-public.yaml)

POS Merchant API to create, search, and retrieve orders from the POS system, and repost orders to external systems.

## Operations

### POST Create order.

`POST /merchant/{version}/sa/orders`

Operation ID: `createOrder`. Tags: Order Management API. **Deprecated**.

Use POST merchant/v3/sa/orders instead. Create order data based on customer order data in payload. This adds only into POS and does not proxy to external OMS services.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required)  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `CustomerOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### GET Retrieve order details.

`GET /merchant/{version}/sa/orders/{id}`

Operation ID: `getOrder`. Tags: Order Management API.

Retrieve order data based on order ID.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required)  
    Pattern: v1|v2.
*   `id` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### POST Repost orders.

`POST /merchant/{version}/sa/orders/repost`

Operation ID: `orderReposting`. Tags: Order Management API.

Repost orders to external system for a given list of order IDs. The order IDs must be provided in the request body in a JSON array format. The maximum number of order IDs that can be processed in a single request is limited to 100.

#### Parameters

*   `version` (path, string, required)  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `OrderRepostRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OrderRepostResponse`.
    

### POST Search and retrieve orders.

`POST /merchant/{version}/sa/orders/search`

Operation ID: `searchOrders`. Tags: Order Management API.

Search and retrieve orders based on input parameters.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required)  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `OrderSearchRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OrderSearchResponse`.
    

### POST Create order V3.

`POST /merchant/v3/sa/orders`

Operation ID: `createOrder_1`. Tags: Order Management API.

Create order in POS system. **Prerequisite:** Make sure that CMS is configured to support the lean input model by setting the property 'enableTransactionExport' to 'true' in the CMS configuration. **CMS Configuration:** **CMS** > **Store Management** > **Store Settings** > **Advanced** > **Enable Transaction Export**.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `ExternalTransaction`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### CustomerOrder

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128. Example: `PS00027533`.
*   `quoteId` (_string_, nullable) Quote reference identifier. Links the order to a quote. Available when the order is based on a quote.  
    Maximum length: 128.
*   `externalQuoteId` (_string_, nullable) External quote reference identifier. Quote ID from the external system. Available when the order is based on a quote.  
    Maximum length: 128.
*   `orderStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `status` (_string_, read-only, nullable, deprecated)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderType` (_string_, nullable) Type of order. It is used in case of order fulfilled by the stores,  
    E.g. BOPIS, BOFIS, BOSS orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `email` (_string_, nullable) Customer Email ID.  
    It is available for signed-in customers or when email is captured in the  
    shipping address for guest customers.  
    Maximum length: 128.
*   `totalAmount` (_number_, required) Order total.
*   `shippingSubTotal` (_number_, nullable) Shipping sub total.
*   `shippingDiscount` (_number_, nullable) Shipping discount.
*   `shippingMethod` (_ShippingMethod_)
*   `shippingTax` (_number_, nullable) Shipping method tax.
*   `shippingTaxClass` (_string_, nullable) Shipping method tax class.
*   `taxSubTotal` (_number_, nullable) Total tax amount for this order.  
    It is applicable for regions/countries where Tax is supported. For countries where VAT is applicable, refer to valueAddedTax.  
    
*   `taxExemption` (_number_, nullable) The tax exemption amount for this order.  
    It is applicable whenever an associate applies a tax exemption to the order in store.  
    
*   `shippingTaxExemption` (_number_, nullable) Total Shipping tax exemption amount for this order. This does not include any product price or shipping cost. It includes only the tax exemption on Shipping.
*   `valueAddedTax` (_number_, nullable) Total VAT amount for this order.  
    It is applicable for regions/countries where VAT is supported. For countries where tax is applicable, refer to taxSubTotal.  
    
*   `orderSubTotal` (_number_, required) Order total excluding discounts, shipping costs and taxes but  
    inclusive of VAT.
*   `tenders` (_array of OrderPaymentDetail_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.  
    When importing an order paid with a credit card from an external system, make sure to include all required fields as well as the following fields:  
    1\. requestId  
    2\. cardType  
    For a **referenced refund** on the credit card, all the above fields and CMS configuration are necessary. Set the below CMS property to **Default** to initiate a referenced refund.  
    **CMS** > **Store Management** > **Store Settings** > **Refund Mode for External Order**.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products.  
    The list doesn't include returned products. While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `orderProductList` (_array of OrderProduct_, required) A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.
*   `returnProductList` (_array of ReturnedProduct_, nullable) List of items that have been returned.  
    While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `discount` (_number_, nullable) Order discount amount. Total discount applied using promo coupons and/or item level price override.  
    It doesn't include transaction discount. For transaction discount, refer to transactionDiscountAmount.  
    Mandatory: If any promo coupon is applied or any item level price override is applied.
*   `externalOrderId` (_string_, nullable) The reference ID of the order that corresponds to the external system. This is relevant in cases where the external downstream system or ERP system uses its own ID instead of the POS order ID for further processing. It is necessary to provide this reference ID while importing the order in POS, especially when updates like returns are required.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store where the order is captured. For BOPIS orders placed via a website,  
    this field contains the store ID for pickup.  
    Maximum length: 128.
*   `storeAssociateId` (_string_, required) The logged-in store associate's ID.  
    Maximum length: 256.
*   `orderSource` (_string_, required) This is the channel or source of an order or transaction. It must be IN\_STORE for all orders placed in store. It must be WEB for all orders placed on the website. When importing an order from an external system, ensure to provide: 1. IN\_STORE for orders placed in store, otherwise the order will not be available in CMS under successful order report. 2. WEB for orders placed on the website to skip its entry from successful order report.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `paymentSource` (_string_, nullable) Payment source. If an order is paid with a single tender,  
    it has the payment method of that tender. The following payment methods  
    are supported: CreditCard, Unknown, External, GiftCard, MixedMode, Cash, Miscellaneous,  
    Finance, StoreCredit, PayByLink, RemotePayByLink, Reward, and Check.  
    In the case of multi-tender payment, the payment source should be MixedMode.
*   `shippingMethodId` (_string_, nullable) Shipping method ID.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `installationId` (_string_, nullable) The device identifier is required for IN\_STORE purchases.  
    If not provided, it defaults to EXTERNAL for orders from external systems.  
    Default: `EXTERNAL`. Maximum length: 128.
*   `lastDateToReturnTimeStamp` (_integer (int64)_, nullable) Last date to return. The return window policy sets the last date for a return.  
    For example, if the policy is one month long and a sale occurs on April 1st,  
    the lastDateToReturnTimeStamp will be set to May 1st.  
    When an order is imported from an external system,  
    the system will determine the order's eligibility for return based on the provided date.  
    If the date is not provided, the item can be returned without any time limitation.  
    Note: Represented as number of milliseconds since epoch.  
    .  
    Example: `1653078974310`.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown. Mandatory if tax engine is configured along with tax rates.  
    For VAT countries, refer to vatRates.
*   `taxExemptions` (_array of TaxExemptionRequest_, nullable) List of tax exemptions, if any, applied to order.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown. Mandatory if tax engine is configured along with VAT rates. For TAX countries, refer to taxRates.
*   `shippingName` (_string_, nullable) Shipping name  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.name from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingDescription` (_string_, nullable) Shipping description.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.description from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingCarrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Required for delivery orders.  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.carrier from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingServiceLevel` (_string_, nullable) Shipping service level, for example, 3-5 Days, 1-Day, Express, Standard, or Overnight.  
    Required for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.serviceLevel from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `phoneNumber` (_string_, nullable) Customer phone number. Mandatory for signed-in customers  
    or when phone number is captured in the shipping address for guest customers.  
    
*   `orderDate` (_integer (int64)_, required) Date when order was placed.  
    Represented as number of milliseconds since epoch.
*   `coupons` (_array of string_, nullable) List of coupon codes applied for this order.
*   `customerProfile` (_Profile_)
*   `updateDate` (_integer (int64)_, required) Date when the order was last updated. Represented as number of milliseconds since epoch.
*   `taxableAmount` (_number_, nullable) Taxable amount.  
    Mandatory if the tax engine is configured along with tax rates.
*   `fulfillmentType` (_string_, required, deprecated) Order fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `rewardAmount` (_number_, nullable) Reward amount applied to this order if any.
*   `transactionDiscountAmount` (_number_, nullable) Transaction discount applied to this order if any.
*   `canReturn` (_boolean_, write-only, nullable) Flag indicating if this order can be returned.  
    During order import in POS, if it is not provided,the order remains returnable.
*   `paymentDetails` (_array of OrderPaymentDetail_, nullable, deprecated) Deprecated. Use 'tenders' instead.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Order refund payment details.  
    If an order is returned, it will have all refunded tenders.  
    
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `failedReasonCode` (_string_, read-only, nullable) Failed order reason code corresponding to payment.  
    Possible values are CANCELED, PAYMENT\_DECLINED, and PAYMENT\_REVERTED.  
    Applicable only if the order fails. Not required when importing an order from an external system.  
      
    Allowed values: `CANCELED`, `PAYMENT_DECLINED`, `PAYMENT_REVERTED`, `PAYMENT_REVERSAL_FAILED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_NOT_FOUND`.
*   `twoPhaseCommitReferenceId` (_string_, read-only, nullable, deprecated) Used for internal processing. Don't use in external systems.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `partiallyPaid` (_boolean_) Flag indicating if this order is partially paid for.
*   `orderActivityLog` (_array of OrderActivityLog_, nullable) The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.
*   `storeAttribution` (_StoreAttribution_)
*   `tipTotal` (_number_, nullable) Total tip added to the order.
*   `orderFiscalData` (_array of OrderFiscalData_, nullable) All fiscal data for this order if any.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `offlineMode` (_boolean_, nullable) Flag indicating if the order got created in offline mode.  
    If not mentioned, it is considered as false.
*   `employee` (_Employee_)
*   `originalOrderId` (_string_) Order ID of the original order if the order is an exchange order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method and other delivery details.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    2\. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `rewardList` (_array of Reward_, read-only, nullable) The list of loyalty rewards applied in this transaction.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `returnCustomerInformationList` (_array of OrderReturnCustomerInformation_, nullable) List of customer/person who returned the items.  
    Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.  
    
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `taxFreeDocument` (_TaxFreeDocument_)
*   `orderRefundFeeDetailList` (_array of OrderRefundFeeDetail_, nullable) List of Refund fee like restocking fee on returned or canceled items.  
    Applicable when item is returned or canceled and refund fee is configured.  
    For more detail on refund fee,
*   `error` (_boolean_)

### OrderRepostRequest

*   `orderIds` (_array of string_) List of order IDs for reposting.
    
    Each item: List of order Ids for reposting.
    

### OrderRepostResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderRepostStatusList` (_array of OrderRepostStatus_) A list of Reposting status for each order that was part of the request.
*   `error` (_boolean_)

### OrderSearchRequest

*   `firstName` (_string_) Customer first name.
*   `lastName` (_string_) Customer last name.
*   `email` (_string_) Customer email address.
*   `orderId` (_string_) Order ID.
*   `postalCode` (_string_) Postal code or Zip code.
*   `start` (_integer (int32)_) Order search offset. Used for paginating across multiple orders.  
    Default: `0`.
*   `limit` (_integer (int32)_) Number of orders to return. Used for paginating across multiple orders.  
    Default: `20`.
*   `bopisOrders` (_boolean_) Flag indicating whether to search BOPIS orders.
*   `storeId` (_string_) Store ID. Find order placed in this store.
*   `customerId` (_string_) Customer ID. Find orders placed by this customer ID.
*   `accountNumber` (_string_) Customer's account number. It can be alternate customer ID or external account number of the customer.
*   `storeOrderStatus` (_string_) Store Order Status. Find orders in this status. Applies to BOPIS/BOFIS orders.
*   `paymentCard` (_Card_)
*   `productId` (_string_) Product ID. Find orders containing this product ID.
*   `searchForReturn` (_boolean_, deprecated) DEPRECATED. Flag indicating if this search is for return purpose. Find only those orders eligible for returns.
*   `storeAssociateId` (_string_) Store Associate ID. Find orders placed by specific store associate.
*   `storeRegisterId` (_string_) Store Register ID. Find orders placed from specific store register.
*   `orderTotal` (_number_) Order Total. Find orders having specific order total.
*   `paymentMethod` (_string_) Payment method. Find orders placed using specific payment method.
*   `amountRange` (_BigDecimalRange_)
*   `orderDateTimeStampStart` (_integer (int64)_) Find orders placed on or after this timestamp - represented as milliseconds since epoch.
*   `orderDateTimeStampEnd` (_integer (int64)_) Find orders placed on or before this timestamp - represented as milliseconds since epoch.
*   `orderStatus` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `manualReceiptId` (_string_) Manual Receipt ID based search.
*   `advancedSearchId` (_string_) Advanced search ID from response.
*   `serialNumber` (_string_) Serial Number. Find orders containing items with this serial number.
*   `workbench` (_boolean_)

### OrderSearchResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderList` (_array of OrderSearchResponseEntry_) List of searched orders.
*   `advancedSearchId` (_string_) Response from NetSuite advanced search.
*   `error` (_boolean_)

### ExternalTransaction

*   `transactionId` (_string_, required) Transaction Id.
*   `transactionType` (_string_, required) Transaction type.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`.
*   `orderId` (_string_, required) Order ID corresponding to the transaction.
*   `externalOrderId` (_string_, nullable) External reference ID if the transaction is captured externally and has a different identifier than orderId.  
    Maximum length: 128.
*   `storeAttribution` (_ExternalStoreAttribution_, required)
*   `tenderList` (_array of ExternalTender_, required) Payment method used towards the sale transaction.
*   `refundTenderList` (_array of ExternalRefundTender_, nullable) Payment method used towards the return transaction.
*   `productList` (_array of ExternalProduct_, required) Products.
*   `returnProductList` (_array of ExternalReturnProduct_, nullable) Returned products.
*   `profile` (_ExternalCustomerProfile_)
*   `deliveryGroupList` (_array of ExternalDeliveryGroup_) In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.
*   `pickUpDetailList` (_array of ExternalPickUpDetail_, nullable) Pickup details.
*   `billingAddress` (_ExternalAddress_)
*   `lastDateToReturn` (_integer (int64)_, nullable) The last date by which the item(s) from the transaction can be returned. If not provided, the item can be returned without any time limitation. The date is in milliseconds since epoch.  
    Example: `1653078974310`.
*   `saleSummary` (_ExternalTransactionSummary_, required)
*   `orderSource` (_string_, required) Channel of the transaction.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `orderType` (_string_, nullable) Order type. It is needed if the order is fulfilled by store. For example, BOPIS, BOFIS.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `status` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`.
*   `noteList` (_array of ExternalNote_, nullable) Notes for the transaction.
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxExemptionList` (_array of ExternalTaxExemption_, nullable) Applied tax exemptions.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### OrderPaymentDetail

Deprecated. Use 'tenders' instead.

*   `transactionId` (_string_, required) The unique identifier for a transaction that completes the order. - This is particularly helpful in cases where a payment is made in multiple transactions, such as in the case of a deposit. - In POS, the transaction ID corresponds to the sale transaction when you place an order. - However, if you import an order from an external system, the transaction ID should correspond to the order in the external system and can be the same as the Order ID.  
    Maximum length: 128.
*   `paymentId` (_string_, required) The unique identifier for a payment/tender. As the order can have multiple payments, each payment will have a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method. Required for BOPIS and BOFIS. Not applicable for ROPIS.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. Possible values are: - `UNPROCESSED` is used internally by cloud services as a transient state. - `DISCARDED` is used when cash tender is part of a multi-tender payment and is deleted by swiping right. - `ABORTED` is used when we internally remove a tender from the tender list and add a new tender (e.g., for gift cards).  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device. If the payment is made in an external system, set the payment device to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards and gift cards through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender. Applicable for credit cards. for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal. Typically used for referenced refunds that are performed automatically by the POS without the customer presenting the card during a refund. In the case of Adyen payments, this field maps to `pspReference`. Required for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode, it generates a temporary payment ID, which is provided in the alternate payment request ID attribute. For example, the Adyen terminal generates a temporary ID called a "tender reference" whenever it goes into store and forward mode. This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund payment request ID issued by the payment gateway/terminal. Required for refund on credit cards.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item, and the original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried forward to the new order. This attribute provides the original order ID if the tender is carried over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item. The original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried over to the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and the tender is carried over to the new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Required for credit card payments using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment. For example, if a customer pays with cash first and the remaining amount with a credit card, the cash tender should have a paymentSequenceNumber of 1, and the credit card tender should have a paymentSequenceNumber of 2.
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number. Applicable when payment method is 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check' and 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.
*   `cardToken` (_string_) This field contains the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment** Gateways > Adyen > Payment Tokenization Events).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender. Normally, it is received after calling a call center agent of a payment processor. For example: call for authorization code after check denial or referral, or manual authorization code for a credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Required for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee. Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to finance approval/order/confirmation number in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderProduct

A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orignalQuantity` (_integer (int32)_)
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ReturnedProduct

List of items that have been returned. While importing an order from an external system, it is optional as the products and return products both can be provided in orderProductList.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `refundDate` (_integer (int64)_, required) The date and time, in milliseconds since epoch, when the item was returned.  
    Example: `1617222000000`.
*   `exchangedForOrderId` (_string_, nullable) The order ID for which the item was exchanged. Applicable for exchange.  
    Maximum length: 128.
*   `returnedAtStoreId` (_string_, required) The store ID where the item was returned.  
    Maximum length: 256.
*   `returnProcessedByAssociateId` (_string_, required) ID of the store associate who performed the return.  
    Maximum length: 256.
*   `returnedAtStoreRegisterId` (_string_, required) The register ID where the item was returned.  
    Maximum length: 128.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `offlineMode` (_boolean_, nullable) Specifies whether the item is returned in offline mode. If not provided, it is considered to be in online mode.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderRefundPaymentDetail

Refund payments.  
For return or exchange transactions, this contains the refund payments.  

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) A transaction ID is a unique identifier corresponding to the return  
    transaction. It is especially useful in situations where a refund is issued in multiple  
    return transactions. When importing an order from an external system and it has a refund,  
    the transaction ID should match the return transaction that carried out the refund.  
    In case the external system doesn't have a return transaction ID, you can use the order  
    ID in its place.  
    Maximum length: 128.
*   `paymentId` (_string_, required) It is a unique identifier for refund payments.  
    It must be unique within an order. When multiple refunds are issued for a single payment,  
    a unique ID is necessary to differentiate each refund.  
    Maximum length: 128.
*   `cardNumber` (_string_, nullable) Card Number to which refund was applied. Last 4 digits in case of refund to CreditCard. Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardType` (_string_, nullable) Card type, for example, mastercard, interac\_card, or visa.  
    Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `originalPaymentId` (_string_, required) A refund is issued against a original payment.  
    This ID provides a reference to the original payment.  
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Reference to original transaction that performs the payment.  
    This ID provides a reference to the original transaction.
*   `paymentMethod` (_string_, required) Refund payment method, for example, Cash or CreditCard.  
    For possible values, see the tenders.paymentMethod attribute.
*   `refundDate` (_string (date-time)_, required, nullable) Timestamp when refund payment was processed.Format: yyyy-MM-dd HH:mm:ss.
*   `refundedAmount` (_number_, required) Refund Amount.  
    Example: `100`.
*   `refundedAsPartOfOrderId` (_string_, nullable) Original Order Id for which this refund payment is processed.  
    Maximum length: 128.
*   `refundRequestId` (_string_, nullable) Refund request identification issued by the payment gateway/terminal.  
    In the case of Adyen payments, this field maps to pspReference of a refund.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use RefundMode instead.
*   `paymentDevice` (_string_, nullable) Device using which payment was refunded. For possible values, please refer to tenders.paymentDevice attribute. Applicable for CreditCard refund only.  
    Maximum length: 32.
*   `paymentDeviceId` (_string_, nullable) Payment Device Identifier. Applicable for CreditCard refund only.  
    Maximum length: 128.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt lines for refund payment.  
    Available in case of unreferenced refunds using CreditCard.  
    Unreferenced refunds are refunds that are not associated with a original payment and  
    customer is prompted to swipe/tap CreditCard during refund.  
    When an order is imported from an external system, it is optional.  
    
*   `cardExpirationMonth` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration month of the card to which payment was refunded.
*   `cardExpirationYear` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration year of the card to which payment was refunded.
*   `roundingAmount` (_number_, nullable) Rounding amount during refund using cash. Applicable for cash refund  
    in regions where rounding is applicable.
*   `refundMode` (_string_, nullable) Refund Mode. It is applicable for CreditCard refunds. The modes are:  
    1\. Unreferenced: Refund is not associated to original payment and is issued on different credit card  
    2\. External: Refund is initiated externally and not by POS  
    3\. Default: Regular refund. It is initiated by POS against original CreditCard  
    It is not necessary to provide this while importing an order from external system.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `fundingSource` (_string_, nullable) Funding source, for example, CREDIT, DEBIT, or CHARGED.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `tip` (_number_) Refunded Tip.
*   `tenderBalance` (_number_) Gift Card balance after refund. Available in case of Gift Card refund.
*   `cardAlias` (_string_, nullable) Card alias of the card to which payment was refunded.
*   `externalPaymentSystemId` (_string_, nullable) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_, nullable) External payment reference identifier in case of External tender.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### OrderActivityLog

The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) The unique Id identifying the transaction.  
    Maximum length: 128. Example: `2808-10-20240419131925-2-7`.
*   `amount` (_number_, nullable) The total transaction amount value.
*   `associateSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `data` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `installationId` (_string_, required, read-only) Unique ID of the register.  
    Maximum length: 128.
*   `productId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `storeAssociateId` (_string_, nullable) The Id of the particular associate at a store.
*   `storeId` (_string_, nullable) The identifier of the store where the order is taking place.  
    Maximum length: 128.
*   `transactionDate` (_string (date-time)_, required) Transaction time, that is, the time when the transaction was executed.
*   `transactionType` (_string_, nullable) The type of transaction. Three types of transactions can be done on an order: SALE, RETURN, and EXCHANGE.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.
*   `userSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `appTransactionId` (_string_, nullable) Unique sequence number generated by POS App. It is reset after daily or relaunch of the App.  
    Maximum length: 48. Example: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ...`.
*   `transactionData` (_Transaction_, required)
*   `manualReceiptId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `s3KeyTransactionData` (_string_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `transactionStartDate` (_string (date-time)_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `receiptPrintCount` (_integer (int32)_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### OrderFiscalData

All fiscal data for this order if any.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier which lead to this payment capture/refund.
*   `transactionType` (_string_) Transaction Type.
*   `fiscalData` (_string_) Fiscalization Data.
*   `printData` (_array of PrintData_) Fiscalization Data that needs to be printed on receipt.
*   `fiscalTransactionId` (_string_) Fiscal Transaction ID.
*   `receiptPrintCount` (_integer (int32)_) Combined Count of transaction paper/e-receipts.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### OrderReturnCustomerInformation

List of customer/person who returned the items. Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier.
*   `firstName` (_string_) First name of the person.
*   `lastName` (_string_) Last name of the person.
*   `email` (_string_) Email of the person.
*   `phone` (_string_) Phone number of the person.
*   `addressLine1` (_string_) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_) City.
*   `state` (_string_) State.
*   `postalCode` (_string_) Postal Code.
*   `country` (_string_) Country.
*   `idType` (_string_) ID Type.
*   `idValue` (_string_) ID Value.
*   `idIssuedBy` (_string_) ID Issued By.
*   `idExpiry` (_string (date-time)_) ID Expiry Date.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### TaxFreeDocument

Tax-free document associated with this order.

*   `docId` (_string_) Global Blue tax-free document identifier.
*   `status` (_string_) Current status of the tax-free document (ISSUED or VOIDED).  
    Allowed values: `ISSUED`, `VOIDED`.

### OrderRefundFeeDetail

List of Refund fee like restocking fee on returned or canceled items.  
Applicable when item is returned or canceled and refund fee is configured.  
For more detail on refund fee,

*   `orderId` (_string_) OrderID towards the refund fees are applied.
*   `transactionId` (_string_) Refund transactionId during which refund fees are applied.
*   `storeId` (_string_) Store where the refund is performed.
*   `refundFeeId` (_string_) Refund fee id Eg. Restocking, Miscellaneous.
*   `refundFeeLabel` (_string_) Refund fee display name Eg. Restocking Fee, Miscellaneous Fee.
*   `refundFeeAmount` (_number_) Refund fee amount.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderRepostStatus

A list of Reposting status for each order that was part of the request.

*   `orderId` (_string_) The unique identifier for the order.
*   `status` (_string_) Status of the individual order reposting. Also please note that the status displayed below solely pertains to the outcome of the asynchronous reposting initiation process. A "SUCCESS" status denotes that the initiation was successful, but it does not guarantee that the order was sent to the external endpoint without issue. Conversely, a "FAIL" status indicates that the reposting initiation was not successful.  
    Allowed values: `SUCCESS`, `FAIL`.
*   `failureDescription` (_string_) Provides a description of the failure if the status is set to FAIL.

### Card

Use the card number in the card object to search. Typically by the last four digits of the card customer used to make payment.

*   `paymentId` (_string_) Payment ID/Card ID.
*   `cardOwner` (_string_) Card Owner.
*   `cardType` (_string_) Card Type.
*   `cardNumber` (_string_) Card Number.
*   `cardCvc` (_string_) Card CVC.
*   `cardExpirationMonth` (_integer (int32)_) Card Expiration Month.
*   `cardExpirationYear` (_integer (int32)_) Card Expiration Year.
*   `rawCardType` (_string_, nullable) Raw Card Type.
*   `billingAddressId` (_string_) Billing address ID.
*   `cardNickName` (_string_, nullable) Card Nick Name.
*   `track1Data` (_string_, nullable) Track1 Data if payment is done by app.
*   `track2Data` (_string_, nullable) Track2 Data if payment is done by app.
*   `deviceId` (_string_, nullable) Device ID.
*   `authAmount` (_number_, nullable) Amount to be authorized.
*   `authCode` (_string_, nullable) Authorization code.
*   `captureCode` (_string_, nullable) Capture code.
*   `cardToken` (_string_, nullable) Card token.
*   `cardId` (_string_)
*   `requestId` (_string_, nullable) Request ID used in POS.
*   `requestToken` (_string_, nullable) Request Token.
*   `encryptedCardNumber` (_string_, nullable) Encrypted Card Number.
*   `encryptedCvv` (_string_, nullable) Encrypted Cvv.
*   `paymentMethod` (_string_, nullable) Payment Method.
*   `transactionId` (_string_, nullable) Transaction Id.
*   `encryptedExpiryDate` (_string_, nullable) Encrypted Expiry Date.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt Lines.
*   `paypalData` (_PaypalData_)
*   `squareData` (_SquareData_)
*   `adyenData` (_AdyenData_)
*   `thirdPartyToken` (_string_, nullable) Third party token. Used in case of aurus tokenization.
*   `manualCardEntry` (_boolean_)

### BigDecimalRange

Find orders within this order total range.

*   `from` (_number_, read-only, nullable) From or starting filter criteria for amount/BigDecimal values.
*   `to` (_number_, nullable) To or ending filter criteria for amount/BigDecimal values.

### OrderSearchResponseEntry

List of searched orders.

*   `orderID` (_string_) Order ID.
*   `storeID` (_string_) Store ID. Order placed in this store.
*   `billingName` (_string_) Billing name used to place order.
*   `emailID` (_string_) Email ID used to place order.
*   `total` (_number_) Order total.
*   `orderDate` (_string_) Order Date.
*   `orderDateTimeStamp` (_integer (int64)_) Order Date Time.
*   `count` (_integer (int32)_) Order count.
*   `imageLinks` (_array of string_) Order Product Images.
*   `orderStatus` (_string_, nullable)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderStatusText` (_string_) Order Status Text.
*   `orderType` (_string_, nullable) Type of order. Used in case of BOPIS (STORE\_PICKUP) or BOFIS/BOSS (STORE\_FULFILLMENT) orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `bopisOrderStatus` (_string_, read-only, nullable) BOPIS/BOSS/BOFIS Order status. This is shared enum used for OrderStatus.
*   `status` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `isSplitCart` (_boolean_, nullable) Flag indicating if this order is part of a split cart order.  
    Default: `false`.
*   `fulfillmentType` (_string_) Fulfillment Type-IN\_STORE, ONLINE, MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `parentOrderId` (_string_, nullable) Parent order ID in case this order is part of a split/mixed order. For example, this order is IN\_STORE order which is part of an order that had IN\_STORE and ONLINE orders.
*   `orderAttribution` (_OrderAttribution_)
*   `paymentStatus` (_string_, nullable) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `currency` (_string_, nullable) Currency code. 3 letter currency code.  
    Example: `USD`.
*   `manualReceiptId` (_string_) Manual Receipt ID.
*   `externalOrderID` (_string_)

### ExternalStoreAttribution

Store details.

*   `storeAssociateId` (_string_, required) Store associate ID who is ringing the transaction.
*   `storeId` (_string_, required) Store ID.  
    Maximum length: 128.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.  
    Maximum length: 128.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `tillSessionId` (_string_, required) Till session ID.
*   `tillId` (_string_, required) Till ID.
*   `installationId` (_string_, nullable) Device identifier which was used to place the order. It is mandatory for transactions performed in the store. For external transactions, it will be defaulted to 'EXTERNAL' if it is not provided.  
    Maximum length: 128.
*   `registerMode` (_string_, required) The mode of the register operation.  
    Allowed values: `ONLINE`, `OFFLINE`. Default: `ONLINE`.

### ExternalTender

Payment method used towards the sale transaction.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Identifies the payment device through which the payment is made. If payment data is manually entered, this field should be set to NoReader. If payment is made in an external system, payment device should be set to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry). Mandatory for CreditCard, GiftCard.  
    Maximum length: 128.
*   `cardType` (_string_) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_) Payment authorization token.  
    Maximum length: 128.
*   `authorizationDate` (_integer (int64)_) Payment authorization timestamp in EPOCH millis.
*   `captureToken` (_string_) Payment capture token.  
    Maximum length: 128.
*   `captureDate` (_integer (int64)_) Payment capture timestamp in EPOCH millis.
*   `firstName` (_string_) First name to use for billing using this tender.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.
*   `country` (_string_) Country code to use for billing using this tender.  
    Maximum length: 16.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) Total Refunded Amount if any which is already paid back due to returns + exchanges. Not applicable, if no refund issued yet.  
    Default: `0`.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.  
    Default: `0`.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int32)_, required) Payment sequence indicating the order of payment. For example, if customer pays partially with cash first and remaining with credit card, then cash tender should have paymentSequenceNumber as 1 and credit card tender should have paymentSequenceNumber as 2.
*   `paymentDeviceId` (_string_) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_) Bank routing number.  
    Maximum length: 32.
*   `accountNumber` (_string_) Account number. Used for payment through banking system.  
    Maximum length: 32.
*   `checkNumber` (_string_) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).  
    Maximum length: 128.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_) Authority that issued the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_integer (int64)_) Personal identification expiry date represented as milliseconds since epoch. Typically expiry date is end of the day and milliseconds since epoch should reflect it accordingly. Applicable for Check and Finance.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year. Applicable for credit card.
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.  
    Maximum length: 32.
*   `externalPaymentReferenceId` (_string_) External payment reference identifier in case of External tender.  
    Maximum length: 32.
*   `checkType` (_string_) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_) Refers to Finance processing related result/instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_) Primary owner on the account.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `paymentLink` (_string_) Payment Link.  
    Maximum length: 128.
*   `paymentLinkExpiryDate` (_integer (int64)_) Payment link expiry timestamp in EPOCH millis.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `requestTokenExpireDate` (_integer (int64)_) Request token expire date in EPOCH millis.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response by gateway. In adyen - a value that uniquely represents the shopper's card number (PAN).
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.

### ExternalRefundTender

Payment method used towards the return transaction.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Transaction identifier as part of which this payment was initiated originally and now being refunded.
*   `originalPaymentId` (_string_, required) Payment Identifier as part of which this payment was initiated originally and now being refunded.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry). Mandatory for CreditCard, GiftCard.  
    Maximum length: 128.
*   `cardType` (_string_) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `refundRequestId` (_string_, required) Refund ID issued by the payment gateway. Mandatory for refund on credit card.
*   `refundedAmount` (_number_, required) Amount refunded.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year.
*   `cashDrawerUrl` (_string_) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `cardAlias` (_string_, nullable) Card alias associated with Refund Tender. In adyen - a value that uniquely represents the shopper's card number (PAN).

### ExternalProduct

Products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.

### ExternalReturnProduct

Returned products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `exchangedForOrderId` (_string_, nullable) Applicable for exchange of the item. A separate order will be generated for the new item when an exchange occurs. The order ID corresponding to the new item related to the exchange will be provided here.  
    Maximum length: 128.
*   `exchangedForProductId` (_string_, nullable) Applicable for exchange of the item. A separate order will be generated for the new item when an exchange occurs. Please provide the order ID for the new item related to the exchange.  
    Maximum length: 128.

### ExternalCustomerProfile

Customer profile. It is mandatory for customer logged-in during the transaction. It is optional for guest customer.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.  
    Maximum length: 128.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.  
    Maximum length: 128.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.

### ExternalDeliveryGroup

In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.

*   `deliveryGroupId` (_string_, required) Delivery group ID.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup, i.e., buy online ship to store |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_ExternalAddress_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `fulfillmentAddress` (_ExternalAddress_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ExternalPickUpDetail

Pickup details.

*   `pickupDetailId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `email` (_string_)
*   `phone` (_string_)

### ExternalAddress

Billing address.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, required, nullable) Customer first name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `addressLine1` (_string_, required, nullable) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required, nullable) City.  
    Maximum length: 64.
*   `state` (_string_, required, nullable) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required, nullable) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, required, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `addressType` (_string_, nullable) Address type- Home, Business.
*   `emailAddress` (_string_, nullable) Customer Email Address.  
    Maximum length: 64.
*   `country` (_string_, nullable) Country.

### ExternalTransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required) Total Item price.
*   `discount` (_number_, nullable) Total price override and promo coupons applied. Applicable if any item level price override applied or any promotion (auto or coupon) applied.
*   `transactionDiscountAmount` (_number_, nullable) Total transaction discount. Applicable if any transaction discount is applied.
*   `rewardAmount` (_number_, nullable) Total reward amount. Applicable if any reward coupon is applied.
*   `tax` (_number_, nullable) Total Tax.
*   `taxExemption` (_number_, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, nullable) Total shipping charges.
*   `total` (_number_, required) Item total inclusive of all charges like taxes and discounts and exclusive of tip amount.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.

### ExternalNote

Notes for the transaction.

*   `cartId` (_string_)
*   `noteId` (_string_)
*   `noteText` (_string_)
*   `transactionId` (_string_)

### ExternalTaxExemption

Applied tax exemptions.

*   `taxExemptCode` (_string_, required) Tax exemption code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for an individual who has tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer's tax-exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption entered during checkout on the POS.  
    Maximum length: 128.
*   `taxExemptionRate` (_number_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### Transaction

The transaction details.

*   `transactionTimeStamp` (_integer (int64)_, required) Timestamp from when the transaction was executed. Epoch time in milliseconds.  
    Example: `1714112491`.
*   `transactionType` (_TransactionType_)
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128.
*   `summary` (_CartSummary_, required)
*   `storeAttribution` (_StoreAttribution_)
*   `receiptPrintCount` (_integer (int32)_, nullable) Receipt print count — the number of original and duplicate receipts.  
    Default: `1`.
*   `fiscalData` (_OrderFiscalData_)
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions. Applicable for tax countries and if the sale is tax exempted.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `tenders` (_array of OrderPaymentDetails_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Refund payments. If it is a return or exchange transaction, it will have refund payments.
*   `shippingAddress` (_Address_)
*   `shippingMethod` (_ShippingMethod_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products in this order. The list doesn't include returned products. Required for sale transactions. For returns where all items were returned, the list is empty.
*   `returnProductList` (_array of Product_, nullable) List of items that have been returned. It is mandatory for return and exchange transaction.
*   `numberOfLineItems` (_integer (int32)_, read-only) Total number of line items.
*   `receiptId` (_string_, read-only, nullable) Receipt ID for the transaction. Applicable for fiscal reporting.
*   `store` (_Store_, required)
*   `profile` (_Profile_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `returnProductPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `customerEmail` (_string_, nullable) Customer email ID. Available for signed-in customers or when email is captured in the shipping address for guest customers.  
    Maximum length: 128.
*   `manualReceiptId` (_string_, nullable) Manual receipt ID. Required in some countries like Portugal where a pre-printed paper receipt with its own receipt ID needs to be issued for offline transactions.
*   `offlineMode` (_boolean_, nullable) Flag indicating if the transaction was executed in offline mode or not.  
    Default: `false`.
*   `referenceReceiptId` (_string_, nullable) Reference receipt ID. Populated for return and exchange transactions. This field provides original sale's receipt ID for reference.
*   `storeAssociate` (_Associate_)
*   `duplicateReceiptText` (_string_) For internal use only. Don't use in external systems. Duplicate receipt text printed on the receipt, for example, 'Duplicata' or 'Copy of Original Document'.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `productNotesList` (_array of OrderDetailNote_, nullable) List of product notes for this transaction if any.
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `employee` (_Employee_)
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method, and other delivery details. This field is used for item level shipping method and address. Mandatory for all delivery items if item level shipping method or item level shipping address is enabled. For more details, see:.
*   `deliveryGroupChangeList` (_ProductDeltaDeliveryGroup_)
*   `nafCode` (_string_, nullable) NAF code. NAF codes in France are used to identify the type of business of an enterprise. For example, 4772A means retail sale of footwear.
*   `rewardList` (_array of Reward_, read-only, nullable, deprecated) Deprecated. Use `orderProductList.priceAdjustments` instead.
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `productPickUpDetailList` (_array of ProductPickUpDetail_, nullable) List of product pickup detail.  
    Applicable if the order is edit order.
*   `returnCustomerInformation` (_ReturnCustomerInformation_)
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Fulfillment type for the order. For example, IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `removedDeliveryGroups` (_array of DeliveryGroup_, nullable) The removed delivery group during the edit order mode.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### PrintData

Print Data object. Used to print fiscalization related information on receipts.

*   `name` (_string_) Name of the field which holds this value.
*   `value` (_string_) Actual value that will be printed.
*   `label` (_string_) Label against which this value will be printed.
*   `type` (_string_) Indicates type of data to be printed, for example, TEXT or QRCode.  
    Allowed values: `Text`, `QRCode`.

### PaypalData

PayPal details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `payerId` (_string_)
*   `token` (_string_)
*   `email` (_string_)
*   `payPalInvoiceId` (_string_)
*   `referenceTransactionId` (_string_)
*   `authTransactionId` (_string_)
*   `payPalTokenTimestamp` (_string_)

### SquareData

Square Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `clientId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)

### AdyenData

Adyen Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `pspAuthCode` (_string_)
*   `pspReference` (_string_)
*   `cardType` (_string_)
*   `cardHolderName` (_string_)
*   `cardExpiryYear` (_string_)
*   `cardExpiryMonth` (_string_)
*   `cardString` (_string_)
*   `tenderReference` (_string_)
*   `terminalId` (_string_)
*   `cardNumber` (_string_)
*   `operatingMode` (_string_)
*   `threeds2Details` (_string_)

### OrderAttribution

Order attributions corresponding to this order.

*   `orderId` (_string_, read-only) Order Id.
*   `notificationId` (_string_, read-only, nullable) Notification sent corresponding to the order.
*   `messageId` (_string_, read-only, nullable) Message triggered corresponding to the order.
*   `geofenceId` (_string_, read-only, nullable) Geofence ID corresponding to the order.
*   `branchId` (_string_, read-only, nullable) Branch ID corresponding to the order.
*   `storeAreaLevel1Id` (_string_, read-only, nullable) Store Area level 1 corresponding to the order.
*   `storeAreaLevel2Id` (_string_, read-only, nullable) Store Area level 2 corresponding to the order.
*   `storeAreaLevel3Id` (_string_, read-only, nullable) Store Area level 3 corresponding to the order.
*   `storeAreaLevel4Id` (_string_, read-only, nullable) Store Area level 4 corresponding to the order.
*   `storeAreaLevel5Id` (_string_, read-only, nullable) Store Area level 5 corresponding to the order.
*   `storeRegisterId` (_string_, read-only, nullable) Store register corresponding to the order.
*   `registerTransactionId` (_string_, read-only, nullable) Register transaction ID corresponding to the order.

### ExternalStoreAssociateAttribution

Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.

*   `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction.
*   `contributionPercentage` (_number_, required) Associate's contribution towards sales.
*   `attributionNote` (_string_) Note related to attribution.
*   `firstName` (_string_, required) Associate's first name.
*   `lastName` (_string_, required) Associate's last name.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item.
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request.

### ExternalProductTax

Tax/Vat details.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption.
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates.
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates.
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### ExternalPriceAdjustment

Price adjustments applied on the item.  
It includes all the price adjustments like transaction discount, price override etc...  
Mandatory if any type of price adjustments is applied.

*   `description` (_string_, required) Price adjustment description.
*   `adjustment` (_string_, required) Price adjustment.
*   `id` (_string_) Promotion Id for applied coupon or auto promotion.
*   `price` (_number_, required) Price adjustment amount.
*   `priceAdjustmentType` (_string_, required) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reason` (_Reason_)
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied.  
    Not applicable for auto promotions,  
    manual price adjustments like price override & transaction discount.
*   `auto` (_boolean_, nullable) Applied promotion is auto or not.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system.  
    If an order is placed directly in the POS, this identifier will not be available.  
    The external system provides this identifier, which will then be replayed to that  
    external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### TransactionType

The type of transaction. Three types of transactions can be done on an order: SALE, RETURN and EXCHANGE.

Type: `string`.

Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`, `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### OrderPaymentDetails

Payment information: The system supports multiple payment options.  
Whenever an order is purchased using payment instrument/s,  
the order will have this list of tenders. However, there are some exceptional scenarios  
where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### Associate

Store associate.

*   `storeAssociateID` (_string_) ID of the store associate (POS login ID for the associate).
*   `storeID` (_string_, nullable) Store ID of the associate.
*   `merchantUserID` (_string_, nullable) Merchant's underlying system's user ID for the store associates. For example, LoginId for underlying OMS or Salseforce Commerce.
*   `paymentDeviceMerchantID` (_string_, nullable) Merchant ID of a payment device assigned to the associate.
*   `paymentDeviceID` (_string_, nullable) ID of a payment device, like terminal ID, assigned to the associate.
*   `storeAssociatePassword` (_string_) Store associate's password (POS Login Password for the associate).
*   `merchantPassword` (_string_, nullable) Merchant's underlying system's password for the associate.
*   `storeAssociatePasswordPin` (_string_, nullable) Password hint for the associate's POS login.
*   `firstName` (_string_, nullable) First name of the associate.
*   `lastName` (_string_, nullable) Last name of the associate.
*   `storeType` (_string_) Type of the store where the associate works. Possible values include: Regular, Popup, Outlet or eComm.
*   `role` (_string_) The associate's role in the store. Possible values include: STORE\_ASSOCIATE, STORE\_MANAGER or AREA\_MANAGER.
*   `passwordSetOn` (_integer (int64)_, nullable) Date when password was set last time. Represented as the number of milliseconds since epoch.
*   `storeAssociatePasswordFlag` (_boolean_) Flag indicating that the store associate password is updated during associate update operation. Used only during update operation.
*   `merchantPasswordFlag` (_boolean_) Flag indicating that the merchant password is updated during associate update operation. Used only during update operation.
*   `storeAssociateSecretFlag` (_boolean_, nullable) Flag indicating that the store associate secret is updated during associate update operation. Used only during update operation.
*   `imageUrl` (_string_, nullable) The associate's image URL.
*   `active` (_boolean_) Specifies whether the status of the associate is active (true) or removed/deactivated (false).
*   `emailId` (_string_, nullable) Email ID of the associate.
*   `mobilePhoneNumber` (_string_, nullable) Mobile phone number of the associate.
*   `additionalStoreIDs` (_array of string_, nullable) Additional store IDs where the associate can log in.
*   `gender` (_string_) Gender of the store associate.  
    Allowed values: `Male`, `Female`, `Neutral`, `Unknown`.
*   `hireDate` (_integer (int64)_, nullable) Date when the associate is hired or can start work in the store.
*   `terminationDate` (_integer (int64)_, nullable) Termination date for the associate.
*   `firstLoginPasswordReset` (_boolean_) Flag indicating that the password is set on the first login.
*   `mobileConfigID` (_string_, nullable) Mobile configuration ID.  
    Maximum length: 128. Example: `134ac374-0f49-4239-a161-ccfe4d3d7686`.

### ProductDeltaDeliveryGroup

List of delivery groups for product.  
, corresponding order item id and new delivery group id.  
It is used for edit order only when changing the delivery group for existing item.

*   `deliveryGroupId` (_string_, required) Delivery group id. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.

### ProductPickUpDetail

List of product pickup detail.  
Applicable if the order is edit order.

*   `orderItemId` (_string_)
*   `pickupDetailId` (_string_)
*   `pickupLocation` (_Store_)
*   `dateTimeSlot` (_DateTimeSlot_)

### ReturnCustomerInformation

Return - Customer Information. For return or exchange transactions, use this object to capture information about the person returning the items. Note: This might or might not be the actual customer who purchased the items. This object is exclusively to capture information about the person returning items.

*   `firstName` (_string_, nullable) First Name.
*   `lastName` (_string_, nullable) Last Name.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `email` (_string_, nullable) Email ID.
*   `address` (_Address_)
*   `personalId` (_PersonalID_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### PersonalID

Customer/Person Identification Information.

*   `type` (_string_, nullable) ID type, for example, State ID, Military ID, or Driving License.
*   `value` (_string_, nullable) ID Number/Value.
*   `expiry` (_string (date-time)_, nullable) ID Expiration Date.
*   `issuedBy` (_string_, nullable) Issued by state.

<!-- document id=436854b0d7b537618257d44afb00997a07ca1e8c46937b60f8244568eb2525f4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-order-post-processing-events.md -->

# Order Post-Processing Events in the UCP Order Lifecycle

An **agentic-commerce channel** is an AI assistant such as Google Gemini that transacts through the **Universal Commerce Protocol (UCP)**. When a shopper places an order through that channel, the agent platform keeps its own current-state copy of the order, which it can surface to the shopper. To keep that copy accurate after checkout, B2C Commerce must tell the agent platform whenever the order changes.

Most changes happen **after the purchase**, in your **Order Management System (OMS)**: the order is shipped, delivered, cancelled, or returned. This guide explains how those **order post-processing events drive UCP order-lifecycle updates**—how a shipment, cancellation, or return becomes a fresh, **full-order snapshot**—carrying a cryptographic signature—delivered to the agent platform so the shopper always sees an up-to-date order.

How those events *reach* B2C Commerce depends on which OMS manages the order. There are two models:

- **[Salesforce Order Management](https://help.salesforce.com/s/articleView?id=commerce.om_impl_self_provision.htm&type=5)** (Salesforce OMS)—updates are detected and forwarded **automatically**. You do nothing beyond your normal order operations.
- **[A third-party OMS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/commerce-apps/connect-third-party-oms.md)**—your OMS **posts** each event to a dedicated B2C Commerce API.

Whichever model you use, the outcome is identical: a full-order snapshot carrying a cryptographic signature, delivered asynchronously to the agent platform.

**note:** **Applies to UCP orders.** These updates are sent only for orders that originated on an agentic-commerce (UCP) channel. Orders on other channels are unaffected.

## Key Concept: Every Update Is a Full-Order Snapshot

UCP requires each update to be a **complete, current-state snapshot of the order**—not an incremental delta. So for every post-processing event, B2C Commerce **re-fetches the whole order**, **attaches the new entry**, and **sends the entire order** to the agent platform.

Two kinds of entry can be attached, and the agent surface renders them differently:

| Entry kind            | Where it lives          | Represents                  | Example event types                                                          |
| --------------------- | ----------------------- | --------------------------- | ---------------------------------------------------------------------------- |
| **Fulfillment event** | `fulfillment.events[]` | A delivery-state progression | `processing`, `shipped`, `in_transit`, `delivered`, `canceled`               |
| **Adjustment**        | `adjustments[]`         | A money movement            | `cancellation`, `return`, `refund`, `credit`                                 |

Both are **append-only logs**: each event adds an entry; earlier entries are never removed. The `fulfillment` object is always present on every snapshot.

**note:** **Values on adjustments carry a sign (+/−).** For a cancellation, return, or refund, the money returned to the buyer and the units removed are **negative**—`totals[].amount` and `line_items[].quantity` are negative. Fulfillment-event quantities are always **non-negative** (goods delivered *to* the buyer). The sign (+/−) is **intrinsic to the value**, not something the reader derives from the `type`.

## What the Platform Does vs. What You Do

| Concern                                                                                                                          | Salesforce OMS                                                                 | Third-party OMS                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Detect that a UCP order was shipped / cancelled / returned                                                                       | **Platform** (automatic)                                                       | **You** (via SCAPI)                                                                                                                                                          |
| Decide the event's type, values, and sign (+/−) convention                                                                       | **Platform** (derives them from the operation)                                 | **You** (via SCAPI)                                                                                                                                                          |
| Re-fetch the full, current order—this becomes the snapshot                                                                       | **Platform** (from Salesforce OMS)                                             | **Platform** (via your retrieval hook)                                                                                                                                       |
| Build the UCP entry and attach it to that snapshot                                                                               | **Platform**                                                                   | **Shared**—you supply the event's content and signs (+/−) via SCAPI; the platform validates, maps them to the UCP entry, and appends it to the snapshot                      |
| Deliver a full-order snapshot with a cryptographic signature to the agent platform                                               | **Platform**                                                                   | **Platform**                                                                                                                                                                 |
| Retry-free, asynchronous delivery that never blocks order operations                                                             | **Platform**                                                                   | **Platform**                                                                                                                                                                 |
| **Fulfillment operations** (ship, mark delivered, …) that produce fulfillment events                                             | **You** (fulfillment / operations)                                             | **You** (fulfillment / operations)                                                                                                                                           |
| **Adjustment actions** (cancel, return, refund) that produce adjustments—may be initiated by the **shopper**, a service rep, or your operations | **You, service rep, or shopper**                                              | **You, service rep, or shopper**                                                                                                                                            |

## Model A — Salesforce OMS (Automatic)

When your UCP orders are managed in **Salesforce OMS**, there is **nothing to build or configure** for these updates. As you ship, cancel, and process returns in Salesforce OMS, B2C Commerce detects each change and forwards it to the agent platform automatically.

The event kind and sign (+/−) are **derived from the order-management operation**:

| Order Management operation                         | UCP entry                                              | Sign (+/−)                          |
| -------------------------------------------------- | ------------------------------------------------------ | ----------------------------------- |
| An order (or part of it) **ships**                 | `shipped` fulfillment event on `fulfillment.events[]` | Quantities **positive**             |
| Units are **canceled**                            | `cancellation` adjustment on `adjustments[]`           | Quantities and amount **negative**  |
| Units are **returned** (or a return is initiated)  | `return` adjustment on `adjustments[]`                 | Quantities and amount **negative**  |

Notes on behavior:

- **The initiator doesn't matter.** A cancellation or return may be initiated by the **shopper** (self-service through the storefront or the agent platform), a service rep, or your operations team. In every case the resulting Salesforce OMS state change is what drives the UCP update—it is detected and forwarded automatically.
- **The platform fills in the details.** Timestamps come straight from the Order Management event, and cancellations and returns are reported as settled (completed) money movements—you don't author any of this.
- **Each action produces its own update.** When an order ships, you get a shipment update; when it is canceled or returned, you get an adjustment update. So a shipment and a cancellation on the same order arrive as two updates. But when several line items change together in one action—for example, a fulfillment that ships multiple items at once—that is a single update for the order, not one per line item. An order shipped in several parts produces one shipment update per part; because every update carries the full order, the fulfillment events accumulate in the log.

### Example — Shipment (Salesforce OMS)

A fulfillment ships two of the order's lines together. Even though multiple items ship, this is one action, so it produces a **single** UCP update—one `shipped` event listing all the shipped line items:

```json
{
  "fulfillment": {
    "events": [
      {
        "type": "shipped",
        "occurred_at": "2026-01-15T10:30:00Z",
        "line_items": [
          { "id": "10uVF0000002fn4YAA", "quantity": 1 },
          { "id": "10uVF0000002fn5ZBB", "quantity": 2 }
        ]
      }
    ]
  }
}
```

This shipment ships three units across two lines but arrives as one webhook—not three, and not one per line.

### Example — Return / Refund (Salesforce OMS)

Two lines are returned together—one unit at $30.00 and two units at $20.00 each—for a $70.00 refund. As with the shipment, this is one action, so it produces a **single** UCP update—one `return` adjustment listing all the returned lines:

```json
{
  "id": "adj_return_10uVF0000002fn4YAA",
  "type": "return",
  "occurred_at": "2026-01-15T10:30:00Z",
  "status": "completed",
  "line_items": [
    { "id": "10uVF0000002fn4YAA", "quantity": -1 },
    { "id": "10uVF0000002fn5ZBB", "quantity": -2 }
  ],
  "totals": [
    { "type": "total", "amount": -7000 }
  ]
}
```

Note the negative `amount` (`-7000`, that is, −$70.00 in cents) and negative quantities—money and units flowing back to the shopper. Both returned lines arrive as one webhook, not one per line. A **cancellation** looks the same with `"type": "cancellation"`.

## Model B — Third-Party OMS (the OMS Status Events API)

When your UCP orders are managed by a **third-party OMS**, B2C Commerce can't observe your OMS's internal changes. Instead, your OMS calls a dedicated API to **notify** B2C Commerce of each post-processing event. B2C Commerce then reassembles the current order (through your OMS retrieval integration), attaches the event you posted, and delivers the snapshot—carrying a cryptographic signature—to the agent platform.

Unlike the Salesforce OMS model—where B2C Commerce *derives* the event—**your OMS supplies the fully-formed event**: its type, timestamp, affected line items, tracking, totals, and signs (+/−).

**note:** **Your OMS must post every event, whatever initiated it.** A cancellation or return may be initiated by the shopper (self-service through the storefront or the agent platform), a service rep, or your operations. When a shopper cancels or returns through B2C Commerce, the platform runs your **cancel or return order hook** against your OMS—but that hook only executes the operation; it does **not** by itself notify the agent platform. Your OMS is responsible for posting the corresponding adjustment to this API so the UCP snapshot is updated.

### How to Post Events

The API, its authorization, request schema, response codes, and sample request bodies are documented in **[Connect a Third-Party Order Management System (OMS)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/commerce-apps/connect-third-party-oms.md#push-status-updates-to-the-platform)**, under *Push Status Updates to the Platform*, with the endpoint reference at **[`createOmsStatusEvent`](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=createOmsStatusEvent)**. That guide is the authoritative reference for the endpoint; this page doesn't repeat it.

The essentials, for orientation:

- You `POST` **exactly one** `fulfillmentEvent` **or** `adjustment` per call to `oms-status-events`.
- A `fulfillmentEvent` becomes an entry in `fulfillment.events[]`; an `adjustment` becomes an entry in `adjustments[]`.
- **You author the whole event**—its type, timestamp, affected line items, tracking, totals, and **signs (+/−)**. Follow the sign (+/−) convention: quantities and amounts flowing back to the buyer are **negative**; fulfillment quantities are **non-negative**. This is the one place the platform can't derive intent for you, so the correctness of the UCP snapshot depends on the values you send.
- The endpoint is available only when your third-party OMS integration is **active for the site** (feature enabled and all order hooks registered); otherwise it returns **`409 Conflict`**.

**note:** **Inbound API vs UCP snapshot field names.** The `oms-status-events` request body uses camelCase (`occurredAt`, `lineItems`). The signed UCP snapshot uses snake_case (`occurred_at`, `line_items`). Don't copy one shape into the other.

### From Your API Call to the UCP Snapshot

What is specific to *this* topic—and not covered by the OMS connection guide—is what B2C Commerce does with the event after it accepts it:

1. It **reassembles the current order** by calling your OMS `retrieve` hook (the same hook used for order look-ups), so the snapshot reflects your OMS's live state.
2. It **appends the event you posted**—the `fulfillmentEvent` to `fulfillment.events[]`, the `adjustment` to `adjustments[]`. Entries your retrieval hook already returns are preserved.
3. It **applies the cryptographic signature and delivers** the full-order snapshot to the agent platform—the same signature-protected payload the Salesforce OMS model produces.

Because the reassembly runs through your retrieval hook, the snapshot is only as current as what that hook returns; the posted event is layered on top of it.

## What Arrives at the Agent Platform

Every update is one delivery containing the **full order**, with:

- the always-present **`fulfillment`** object (including any `events[]` such as `shipped`), and
- the **`adjustments[]`** log (any cancellations, returns, or refunds to date).

Delivery is:

- **Signature-protected**—each webhook carries a cryptographic signature (HTTP Message Signatures, RFC 9421) so the agent platform can verify it came from B2C Commerce. Saving UCP settings in Business Manager generates the signing keys advertised on the [business profile](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#security).
- **Asynchronous**—sending happens off to the side and never blocks or slows your order operations.

To mutate the payload immediately before signed delivery, implement `sfcc.ucp.orderWebhook.v1.modifyEventPayload`. If that hook fails or returns a non-OK status, the webhook is retried. See [Business Profile and Order Webhooks](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#business-profile-and-order-webhooks).

## Related Reading

- [Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md)—Business Manager UCP settings, OMS options, and signing keys
- [Implementation Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#business-profile-and-order-webhooks)—order webhook hook, including `modifyEventPayload`
- [Connect a Third-Party Order Management System (OMS)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/commerce-apps/connect-third-party-oms.md)—building and registering the order hooks the third-party model depends on, and the `oms-status-events` API
- [UCP order specification](https://ucp.dev/latest/specification/order/)

<!-- document id=5c552e6586f520efac342afc97247124fd002a535f5e9b1d7cfd165c55d5300d url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/order-spi.md -->

Order SPI

# Order SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/order-spi/order-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them during multiple scenarios like BORIS, BOPIS, BOFIS, and others.

**Version:** 2.3.4

## Tags

### Order SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/order-spi/order-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them during multiple scenarios like BORIS, BOPIS, BOFIS, and others.

## Operations

### POST Order SPI to Export Return

`POST /merchant/spi/sample/endpoint/sa/orders/to/export/return/order/to/external/system`

Operation ID: `exportReturnOrder`. Tags: Order SPI.

The specification provides details for external endpoint to consume the POS return transaction. It also describes on how to configure an external endpoint in POS system to export the sale transaction to the external system. **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with following details

1.  Under **API Config**
    
    *   **API Key:** `RETURN`
    *   **API Endpoint:** Provide the external endpoint to get the order eg.[https://sample/external/to/export/return/order/to/external/system](https://sample/external/to/export/return/order/to/external/system)
2.  Under **JSON Config**
    
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the api. Headers can be Content-Type, Authorization attributes like clientId/password eg. {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}
    *   The endpoint with Oauth athorization is supported. For more details refer to documentation

**Use Case**: The endpoint will be used to post the return transaction to external system/OMS .

#### Request body

Media type: `application/json`. Schema: `CustomerOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `HttpResponse`.
    

### POST Export sale order.

`POST /merchant/spi/sample/endpoint/sa/orders/to/export/sale/order/to/external/system`

Operation ID: `exportSaleOrder`. Tags: Order SPI.

Export the POS sale transaction to an external endpoint. This specification provides details for the external endpoint to consume the POS sale transaction and describes how to configure an external endpoint in the POS system to export the sale transaction to the external system. Configure the endpoint in CMS under **CMS** > **Store Management** > **Integration** > **Custom Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **Endpoint Name:** `ORDER`
    *   **API Endpoint:** Provide the external endpoint to export the sale order, for example: [https://sample/external/to/export/sale/order/to/external/system](https://sample/external/to/export/sale/order/to/external/system)
    *   **API Authorization Key:** Provide the authorization key for the API
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes like clientId/password, for example: `{"Content-Type":"application/json","client_id":"myClientId","client_secret":"myClientSecret"}`
3.  The endpoint with OAuth authorization is supported. For more details, refer to documentation. **Use Case:** The endpoint is used to post the sale transaction to external system or OMS.

#### Request body

Media type: `application/json`. Schema: `CustomerOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `HttpResponse`.
    

### GET Retrieve BORIS order.

`GET /merchant/spi/sample/endpoint/sa/orders/to/get/boris/order/from/external/system/{orderId}`

Operation ID: `getBorisOrder`. Tags: Order SPI.

Retrieve a specifically BORIS order from merchant's system in the form of CustomerOrder object. Make sure orderId is provided as a path parameter. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BORIS_GET_ORDER_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from an external system during BORIS flow for merchants that use POS.

****Note:**** For a BORIS order, if the customer initiates the return with an external or alternate receipt ID, this SPI is expected to return the POS Order ID in the field 'borisOrderId'. Either a full Order object is expected or just 'borisOrderId' in the response.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### GET Retrieve order.

`GET /merchant/spi/sample/endpoint/sa/orders/to/get/order/from/external/system/{orderId}`

Operation ID: `getOrder_1`. Tags: Order SPI.

Retrieve order from merchant's system in the form of CustomerOrder object. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `GET_ORDER_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from an external system during BORIS flow for merchants that use POS OMS as a master of record for in-store orders and external OMS as master of record for web orders.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### POST Search orders.

`POST /merchant/spi/sample/endpoint/sa/orders/to/search/orders/from/external/system`

Operation ID: `searchOrders_1`. Tags: Order SPI.

Search orders from merchant's system based on provided filter criteria. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SEARCH_ORDERS`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample.com/external/endpoint/to/search/orders/from/external/system](https://sample.com/external/endpoint/to/search/orders/from/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To search orders in external system and show them in the order-history screen of POS.

#### Request body

Media type: `application/json`. Schema: `OrderSearchRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OrderSearchResponse`.
    

## Schemas

### CustomerOrder

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128. Example: `PS00027533`.
*   `quoteId` (_string_, nullable) Quote reference identifier. Links the order to a quote. Available when the order is based on a quote.  
    Maximum length: 128.
*   `externalQuoteId` (_string_, nullable) External quote reference identifier. Quote ID from the external system. Available when the order is based on a quote.  
    Maximum length: 128.
*   `orderStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `status` (_string_, read-only, nullable, deprecated)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderType` (_string_, nullable) Type of order. It is used in case of order fulfilled by the stores,  
    E.g. BOPIS, BOFIS, BOSS orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `email` (_string_, nullable) Customer Email ID.  
    It is available for signed-in customers or when email is captured in the  
    shipping address for guest customers.  
    Maximum length: 128.
*   `totalAmount` (_number_, required) Order total.
*   `shippingSubTotal` (_number_, nullable) Shipping sub total.
*   `shippingDiscount` (_number_, nullable) Shipping discount.
*   `shippingMethod` (_ShippingMethod_)
*   `shippingTax` (_number_, nullable) Shipping method tax.
*   `shippingTaxClass` (_string_, nullable) Shipping method tax class.
*   `taxSubTotal` (_number_, nullable) Total tax amount for this order.  
    It is applicable for regions/countries where Tax is supported. For countries where VAT is applicable, refer to valueAddedTax.  
    
*   `taxExemption` (_number_, nullable) The tax exemption amount for this order.  
    It is applicable whenever an associate applies a tax exemption to the order in store.  
    
*   `shippingTaxExemption` (_number_, nullable) Total Shipping tax exemption amount for this order. This does not include any product price or shipping cost. It includes only the tax exemption on Shipping.
*   `valueAddedTax` (_number_, nullable) Total VAT amount for this order.  
    It is applicable for regions/countries where VAT is supported. For countries where tax is applicable, refer to taxSubTotal.  
    
*   `orderSubTotal` (_number_, required) Order total excluding discounts, shipping costs and taxes but  
    inclusive of VAT.
*   `tenders` (_array of OrderPaymentDetail_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.  
    When importing an order paid with a credit card from an external system, make sure to include all required fields as well as the following fields:  
    1\. requestId  
    2\. cardType  
    For a **referenced refund** on the credit card, all the above fields and CMS configuration are necessary. Set the below CMS property to **Default** to initiate a referenced refund.  
    **CMS** > **Store Management** > **Store Settings** > **Refund Mode for External Order**.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products.  
    The list doesn't include returned products. While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `orderProductList` (_array of OrderProduct_, required) A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.
*   `returnProductList` (_array of ReturnedProduct_, nullable) List of items that have been returned.  
    While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `discount` (_number_, nullable) Order discount amount. Total discount applied using promo coupons and/or item level price override.  
    It doesn't include transaction discount. For transaction discount, refer to transactionDiscountAmount.  
    Mandatory: If any promo coupon is applied or any item level price override is applied.
*   `externalOrderId` (_string_, nullable) The reference ID of the order that corresponds to the external system. This is relevant in cases where the external downstream system or ERP system uses its own ID instead of the POS order ID for further processing. It is necessary to provide this reference ID while importing the order in POS, especially when updates like returns are required.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store where the order is captured. For BOPIS orders placed via a website,  
    this field contains the store ID for pickup.  
    Maximum length: 128.
*   `storeAssociateId` (_string_, required) The logged-in store associate's ID.  
    Maximum length: 256.
*   `orderSource` (_string_, required) This is the channel or source of an order or transaction. It must be IN\_STORE for all orders placed in store. It must be WEB for all orders placed on the website. When importing an order from an external system, ensure to provide: 1. IN\_STORE for orders placed in store, otherwise the order will not be available in CMS under successful order report. 2. WEB for orders placed on the website to skip its entry from successful order report.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `paymentSource` (_string_, nullable) Payment source. If an order is paid with a single tender,  
    it has the payment method of that tender. The following payment methods  
    are supported: CreditCard, Unknown, External, GiftCard, MixedMode, Cash, Miscellaneous,  
    Finance, StoreCredit, PayByLink, RemotePayByLink, Reward, and Check.  
    In the case of multi-tender payment, the payment source should be MixedMode.
*   `shippingMethodId` (_string_, nullable) Shipping method ID.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `installationId` (_string_, nullable) The device identifier is required for IN\_STORE purchases.  
    If not provided, it defaults to EXTERNAL for orders from external systems.  
    Default: `EXTERNAL`. Maximum length: 128.
*   `lastDateToReturnTimeStamp` (_integer (int64)_, nullable) Last date to return. The return window policy sets the last date for a return.  
    For example, if the policy is one month long and a sale occurs on April 1st,  
    the lastDateToReturnTimeStamp will be set to May 1st.  
    When an order is imported from an external system,  
    the system will determine the order's eligibility for return based on the provided date.  
    If the date is not provided, the item can be returned without any time limitation.  
    Note: Represented as number of milliseconds since epoch.  
    .  
    Example: `1653078974310`.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown. Mandatory if tax engine is configured along with tax rates.  
    For VAT countries, refer to vatRates.
*   `taxExemptions` (_array of TaxExemptionRequest_, nullable) List of tax exemptions, if any, applied to order.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown. Mandatory if tax engine is configured along with VAT rates. For TAX countries, refer to taxRates.
*   `shippingName` (_string_, nullable) Shipping name  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.name from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingDescription` (_string_, nullable) Shipping description.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.description from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingCarrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Required for delivery orders.  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.carrier from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingServiceLevel` (_string_, nullable) Shipping service level, for example, 3-5 Days, 1-Day, Express, Standard, or Overnight.  
    Required for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.serviceLevel from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `phoneNumber` (_string_, nullable) Customer phone number. Mandatory for signed-in customers  
    or when phone number is captured in the shipping address for guest customers.  
    
*   `orderDate` (_integer (int64)_, required) Date when order was placed.  
    Represented as number of milliseconds since epoch.
*   `coupons` (_array of string_, nullable) List of coupon codes applied for this order.
*   `customerProfile` (_Profile_)
*   `updateDate` (_integer (int64)_, required) Date when the order was last updated. Represented as number of milliseconds since epoch.
*   `taxableAmount` (_number_, nullable) Taxable amount.  
    Mandatory if the tax engine is configured along with tax rates.
*   `fulfillmentType` (_string_, required, deprecated) Order fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `rewardAmount` (_number_, nullable) Reward amount applied to this order if any.
*   `transactionDiscountAmount` (_number_, nullable) Transaction discount applied to this order if any.
*   `canReturn` (_boolean_, write-only, nullable) Flag indicating if this order can be returned.  
    During order import in POS, if it is not provided,the order remains returnable.
*   `paymentDetails` (_array of OrderPaymentDetail_, nullable, deprecated) Deprecated. Use 'tenders' instead.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Order refund payment details.  
    If an order is returned, it will have all refunded tenders.  
    
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `failedReasonCode` (_string_, read-only, nullable) Failed order reason code corresponding to payment.  
    Possible values are CANCELED, PAYMENT\_DECLINED, and PAYMENT\_REVERTED.  
    Applicable only if the order fails. Not required when importing an order from an external system.  
      
    Allowed values: `CANCELED`, `PAYMENT_DECLINED`, `PAYMENT_REVERTED`, `PAYMENT_REVERSAL_FAILED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_NOT_FOUND`.
*   `twoPhaseCommitReferenceId` (_string_, read-only, nullable, deprecated) Used for internal processing. Don't use in external systems.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `partiallyPaid` (_boolean_) Flag indicating if this order is partially paid for.
*   `orderActivityLog` (_array of OrderActivityLog_, nullable) The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.
*   `storeAttribution` (_StoreAttribution_)
*   `tipTotal` (_number_, nullable) Total tip added to the order.
*   `orderFiscalData` (_array of OrderFiscalData_, nullable) All fiscal data for this order if any.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `offlineMode` (_boolean_, nullable) Flag indicating if the order got created in offline mode.  
    If not mentioned, it is considered as false.
*   `employee` (_Employee_)
*   `originalOrderId` (_string_) Order ID of the original order if the order is an exchange order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method and other delivery details.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    2\. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `rewardList` (_array of Reward_, read-only, nullable) The list of loyalty rewards applied in this transaction.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `returnCustomerInformationList` (_array of OrderReturnCustomerInformation_, nullable) List of customer/person who returned the items.  
    Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.  
    
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `taxFreeDocument` (_TaxFreeDocument_)
*   `orderRefundFeeDetailList` (_array of OrderRefundFeeDetail_, nullable) List of Refund fee like restocking fee on returned or canceled items.  
    Applicable when item is returned or canceled and refund fee is configured.  
    For more detail on refund fee,
*   `error` (_boolean_)

### HttpResponse

*   `statusLine` (_StatusLine_)
*   `statusCode` (_integer (int32)_, write-only)
*   `reasonPhrase` (_string_, write-only)
*   `entity` (_HttpEntity_)
*   `locale` (_object_)
    *   `language` (_string_)
    *   `script` (_string_)
    *   `country` (_string_)
    *   `variant` (_string_)
    *   `unicodeLocaleAttributes` (_array of string_)  
        Unique items.
    *   `unicodeLocaleKeys` (_array of string_)  
        Unique items.
    *   `displayLanguage` (_string_)
    *   `displayScript` (_string_)
    *   `displayCountry` (_string_)
    *   `displayVariant` (_string_)
    *   `displayName` (_string_)
    *   `extensionKeys` (_array of string_)  
        Unique items.
    *   `iso3Language` (_string_)
    *   `iso3Country` (_string_)
*   `protocolVersion` (_ProtocolVersion_)
*   `allHeaders` (_array of Header_)
*   `headers` (_array of Header_, write-only)
*   `header` (_Header_)
*   `params` (_HttpParams_)

### OrderSearchRequest

*   `firstName` (_string_) Customer first name.
*   `lastName` (_string_) Customer last name.
*   `email` (_string_) Customer email address.
*   `orderId` (_string_) Order ID.
*   `postalCode` (_string_) Postal code or Zip code.
*   `start` (_integer (int32)_) Order search offset. Used for paginating across multiple orders.  
    Default: `0`.
*   `limit` (_integer (int32)_) Number of orders to return. Used for paginating across multiple orders.  
    Default: `20`.
*   `bopisOrders` (_boolean_) Flag indicating whether to search BOPIS orders.
*   `storeId` (_string_) Store ID. Find order placed in this store.
*   `customerId` (_string_) Customer ID. Find orders placed by this customer ID.
*   `accountNumber` (_string_) Customer's account number. It can be alternate customer ID or external account number of the customer.
*   `storeOrderStatus` (_string_) Store Order Status. Find orders in this status. Applies to BOPIS/BOFIS orders.
*   `paymentCard` (_Card_)
*   `productId` (_string_) Product ID. Find orders containing this product ID.
*   `searchForReturn` (_boolean_, deprecated) DEPRECATED. Flag indicating if this search is for return purpose. Find only those orders eligible for returns.
*   `storeAssociateId` (_string_) Store Associate ID. Find orders placed by specific store associate.
*   `storeRegisterId` (_string_) Store Register ID. Find orders placed from specific store register.
*   `orderTotal` (_number_) Order Total. Find orders having specific order total.
*   `paymentMethod` (_string_) Payment method. Find orders placed using specific payment method.
*   `amountRange` (_BigDecimalRange_)
*   `orderDateTimeStampStart` (_integer (int64)_) Find orders placed on or after this timestamp - represented as milliseconds since epoch.
*   `orderDateTimeStampEnd` (_integer (int64)_) Find orders placed on or before this timestamp - represented as milliseconds since epoch.
*   `orderStatus` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `manualReceiptId` (_string_) Manual Receipt ID based search.
*   `advancedSearchId` (_string_) Advanced search ID from response.
*   `serialNumber` (_string_) Serial Number. Find orders containing items with this serial number.
*   `workbench` (_boolean_)

### OrderSearchResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderList` (_array of OrderSearchResponseEntry_) List of searched orders.
*   `advancedSearchId` (_string_) Response from NetSuite advanced search.
*   `error` (_boolean_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### OrderPaymentDetail

Deprecated. Use 'tenders' instead.

*   `transactionId` (_string_, required) The unique identifier for a transaction that completes the order. - This is particularly helpful in cases where a payment is made in multiple transactions, such as in the case of a deposit. - In POS, the transaction ID corresponds to the sale transaction when you place an order. - However, if you import an order from an external system, the transaction ID should correspond to the order in the external system and can be the same as the Order ID.  
    Maximum length: 128.
*   `paymentId` (_string_, required) The unique identifier for a payment/tender. As the order can have multiple payments, each payment will have a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method. Required for BOPIS and BOFIS. Not applicable for ROPIS.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. Possible values are: - `UNPROCESSED` is used internally by cloud services as a transient state. - `DISCARDED` is used when cash tender is part of a multi-tender payment and is deleted by swiping right. - `ABORTED` is used when we internally remove a tender from the tender list and add a new tender (e.g., for gift cards).  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device. If the payment is made in an external system, set the payment device to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards and gift cards through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender. Applicable for credit cards. for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal. Typically used for referenced refunds that are performed automatically by the POS without the customer presenting the card during a refund. In the case of Adyen payments, this field maps to `pspReference`. Required for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode, it generates a temporary payment ID, which is provided in the alternate payment request ID attribute. For example, the Adyen terminal generates a temporary ID called a "tender reference" whenever it goes into store and forward mode. This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund payment request ID issued by the payment gateway/terminal. Required for refund on credit cards.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item, and the original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried forward to the new order. This attribute provides the original order ID if the tender is carried over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item. The original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried over to the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and the tender is carried over to the new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Required for credit card payments using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment. For example, if a customer pays with cash first and the remaining amount with a credit card, the cash tender should have a paymentSequenceNumber of 1, and the credit card tender should have a paymentSequenceNumber of 2.
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number. Applicable when payment method is 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check' and 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.
*   `cardToken` (_string_) This field contains the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment** Gateways > Adyen > Payment Tokenization Events).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender. Normally, it is received after calling a call center agent of a payment processor. For example: call for authorization code after check denial or referral, or manual authorization code for a credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Required for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee. Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to finance approval/order/confirmation number in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderProduct

A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orignalQuantity` (_integer (int32)_)
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ReturnedProduct

List of items that have been returned. While importing an order from an external system, it is optional as the products and return products both can be provided in orderProductList.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `refundDate` (_integer (int64)_, required) The date and time, in milliseconds since epoch, when the item was returned.  
    Example: `1617222000000`.
*   `exchangedForOrderId` (_string_, nullable) The order ID for which the item was exchanged. Applicable for exchange.  
    Maximum length: 128.
*   `returnedAtStoreId` (_string_, required) The store ID where the item was returned.  
    Maximum length: 256.
*   `returnProcessedByAssociateId` (_string_, required) ID of the store associate who performed the return.  
    Maximum length: 256.
*   `returnedAtStoreRegisterId` (_string_, required) The register ID where the item was returned.  
    Maximum length: 128.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `offlineMode` (_boolean_, nullable) Specifies whether the item is returned in offline mode. If not provided, it is considered to be in online mode.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderRefundPaymentDetail

Refund payments.  
For return or exchange transactions, this contains the refund payments.  

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) A transaction ID is a unique identifier corresponding to the return  
    transaction. It is especially useful in situations where a refund is issued in multiple  
    return transactions. When importing an order from an external system and it has a refund,  
    the transaction ID should match the return transaction that carried out the refund.  
    In case the external system doesn't have a return transaction ID, you can use the order  
    ID in its place.  
    Maximum length: 128.
*   `paymentId` (_string_, required) It is a unique identifier for refund payments.  
    It must be unique within an order. When multiple refunds are issued for a single payment,  
    a unique ID is necessary to differentiate each refund.  
    Maximum length: 128.
*   `cardNumber` (_string_, nullable) Card Number to which refund was applied. Last 4 digits in case of refund to CreditCard. Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardType` (_string_, nullable) Card type, for example, mastercard, interac\_card, or visa.  
    Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `originalPaymentId` (_string_, required) A refund is issued against a original payment.  
    This ID provides a reference to the original payment.  
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Reference to original transaction that performs the payment.  
    This ID provides a reference to the original transaction.
*   `paymentMethod` (_string_, required) Refund payment method, for example, Cash or CreditCard.  
    For possible values, see the tenders.paymentMethod attribute.
*   `refundDate` (_string (date-time)_, required, nullable) Timestamp when refund payment was processed.Format: yyyy-MM-dd HH:mm:ss.
*   `refundedAmount` (_number_, required) Refund Amount.  
    Example: `100`.
*   `refundedAsPartOfOrderId` (_string_, nullable) Original Order Id for which this refund payment is processed.  
    Maximum length: 128.
*   `refundRequestId` (_string_, nullable) Refund request identification issued by the payment gateway/terminal.  
    In the case of Adyen payments, this field maps to pspReference of a refund.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use RefundMode instead.
*   `paymentDevice` (_string_, nullable) Device using which payment was refunded. For possible values, please refer to tenders.paymentDevice attribute. Applicable for CreditCard refund only.  
    Maximum length: 32.
*   `paymentDeviceId` (_string_, nullable) Payment Device Identifier. Applicable for CreditCard refund only.  
    Maximum length: 128.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt lines for refund payment.  
    Available in case of unreferenced refunds using CreditCard.  
    Unreferenced refunds are refunds that are not associated with a original payment and  
    customer is prompted to swipe/tap CreditCard during refund.  
    When an order is imported from an external system, it is optional.  
    
*   `cardExpirationMonth` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration month of the card to which payment was refunded.
*   `cardExpirationYear` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration year of the card to which payment was refunded.
*   `roundingAmount` (_number_, nullable) Rounding amount during refund using cash. Applicable for cash refund  
    in regions where rounding is applicable.
*   `refundMode` (_string_, nullable) Refund Mode. It is applicable for CreditCard refunds. The modes are:  
    1\. Unreferenced: Refund is not associated to original payment and is issued on different credit card  
    2\. External: Refund is initiated externally and not by POS  
    3\. Default: Regular refund. It is initiated by POS against original CreditCard  
    It is not necessary to provide this while importing an order from external system.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `fundingSource` (_string_, nullable) Funding source, for example, CREDIT, DEBIT, or CHARGED.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `tip` (_number_) Refunded Tip.
*   `tenderBalance` (_number_) Gift Card balance after refund. Available in case of Gift Card refund.
*   `cardAlias` (_string_, nullable) Card alias of the card to which payment was refunded.
*   `externalPaymentSystemId` (_string_, nullable) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_, nullable) External payment reference identifier in case of External tender.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### OrderActivityLog

The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) The unique Id identifying the transaction.  
    Maximum length: 128. Example: `2808-10-20240419131925-2-7`.
*   `amount` (_number_, nullable) The total transaction amount value.
*   `associateSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `data` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `installationId` (_string_, required, read-only) Unique ID of the register.  
    Maximum length: 128.
*   `productId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `storeAssociateId` (_string_, nullable) The Id of the particular associate at a store.
*   `storeId` (_string_, nullable) The identifier of the store where the order is taking place.  
    Maximum length: 128.
*   `transactionDate` (_string (date-time)_, required) Transaction time, that is, the time when the transaction was executed.
*   `transactionType` (_string_, nullable) The type of transaction. Three types of transactions can be done on an order: SALE, RETURN, and EXCHANGE.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.
*   `userSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `appTransactionId` (_string_, nullable) Unique sequence number generated by POS App. It is reset after daily or relaunch of the App.  
    Maximum length: 48. Example: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ...`.
*   `transactionData` (_Transaction_, required)
*   `manualReceiptId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `s3KeyTransactionData` (_string_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `transactionStartDate` (_string (date-time)_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `receiptPrintCount` (_integer (int32)_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### OrderFiscalData

All fiscal data for this order if any.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier which lead to this payment capture/refund.
*   `transactionType` (_string_) Transaction Type.
*   `fiscalData` (_string_) Fiscalization Data.
*   `printData` (_array of PrintData_) Fiscalization Data that needs to be printed on receipt.
*   `fiscalTransactionId` (_string_) Fiscal Transaction ID.
*   `receiptPrintCount` (_integer (int32)_) Combined Count of transaction paper/e-receipts.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### OrderReturnCustomerInformation

List of customer/person who returned the items. Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier.
*   `firstName` (_string_) First name of the person.
*   `lastName` (_string_) Last name of the person.
*   `email` (_string_) Email of the person.
*   `phone` (_string_) Phone number of the person.
*   `addressLine1` (_string_) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_) City.
*   `state` (_string_) State.
*   `postalCode` (_string_) Postal Code.
*   `country` (_string_) Country.
*   `idType` (_string_) ID Type.
*   `idValue` (_string_) ID Value.
*   `idIssuedBy` (_string_) ID Issued By.
*   `idExpiry` (_string (date-time)_) ID Expiry Date.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### TaxFreeDocument

Tax-free document associated with this order.

*   `docId` (_string_) Global Blue tax-free document identifier.
*   `status` (_string_) Current status of the tax-free document (ISSUED or VOIDED).  
    Allowed values: `ISSUED`, `VOIDED`.

### OrderRefundFeeDetail

List of Refund fee like restocking fee on returned or canceled items.  
Applicable when item is returned or canceled and refund fee is configured.  
For more detail on refund fee,

*   `orderId` (_string_) OrderID towards the refund fees are applied.
*   `transactionId` (_string_) Refund transactionId during which refund fees are applied.
*   `storeId` (_string_) Store where the refund is performed.
*   `refundFeeId` (_string_) Refund fee id Eg. Restocking, Miscellaneous.
*   `refundFeeLabel` (_string_) Refund fee display name Eg. Restocking Fee, Miscellaneous Fee.
*   `refundFeeAmount` (_number_) Refund fee amount.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### StatusLine

*   `reasonPhrase` (_string_)
*   `protocolVersion` (_ProtocolVersion_)
*   `statusCode` (_integer (int32)_)

### HttpEntity

*   `repeatable` (_boolean_)
*   `streaming` (_boolean_)
*   `chunked` (_boolean_)
*   `content` (_object_)
*   `contentLength` (_integer (int64)_)
*   `contentType` (_Header_)
*   `contentEncoding` (_Header_)

### ProtocolVersion

*   `protocol` (_string_)
*   `major` (_integer (int32)_)
*   `minor` (_integer (int32)_)

### Header

*   `name` (_string_)
*   `value` (_string_)
*   `elements` (_array of HeaderElement_)

### HttpParams

### Card

Use the card number in the card object to search. Typically by the last four digits of the card customer used to make payment.

*   `paymentId` (_string_) Payment ID/Card ID.
*   `cardOwner` (_string_) Card Owner.
*   `cardType` (_string_) Card Type.
*   `cardNumber` (_string_) Card Number.
*   `cardCvc` (_string_) Card CVC.
*   `cardExpirationMonth` (_integer (int32)_) Card Expiration Month.
*   `cardExpirationYear` (_integer (int32)_) Card Expiration Year.
*   `rawCardType` (_string_, nullable) Raw Card Type.
*   `billingAddressId` (_string_) Billing address ID.
*   `cardNickName` (_string_, nullable) Card Nick Name.
*   `track1Data` (_string_, nullable) Track1 Data if payment is done by app.
*   `track2Data` (_string_, nullable) Track2 Data if payment is done by app.
*   `deviceId` (_string_, nullable) Device ID.
*   `authAmount` (_number_, nullable) Amount to be authorized.
*   `authCode` (_string_, nullable) Authorization code.
*   `captureCode` (_string_, nullable) Capture code.
*   `cardToken` (_string_, nullable) Card token.
*   `cardId` (_string_)
*   `requestId` (_string_, nullable) Request ID used in POS.
*   `requestToken` (_string_, nullable) Request Token.
*   `encryptedCardNumber` (_string_, nullable) Encrypted Card Number.
*   `encryptedCvv` (_string_, nullable) Encrypted Cvv.
*   `paymentMethod` (_string_, nullable) Payment Method.
*   `transactionId` (_string_, nullable) Transaction Id.
*   `encryptedExpiryDate` (_string_, nullable) Encrypted Expiry Date.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt Lines.
*   `paypalData` (_PaypalData_)
*   `squareData` (_SquareData_)
*   `adyenData` (_AdyenData_)
*   `thirdPartyToken` (_string_, nullable) Third party token. Used in case of aurus tokenization.
*   `manualCardEntry` (_boolean_)

### BigDecimalRange

Find orders within this order total range.

*   `from` (_number_, read-only, nullable) From or starting filter criteria for amount/BigDecimal values.
*   `to` (_number_, nullable) To or ending filter criteria for amount/BigDecimal values.

### OrderSearchResponseEntry

List of searched orders.

*   `orderID` (_string_) Order ID.
*   `storeID` (_string_) Store ID. Order placed in this store.
*   `billingName` (_string_) Billing name used to place order.
*   `emailID` (_string_) Email ID used to place order.
*   `total` (_number_) Order total.
*   `orderDate` (_string_) Order Date.
*   `orderDateTimeStamp` (_integer (int64)_) Order Date Time.
*   `count` (_integer (int32)_) Order count.
*   `imageLinks` (_array of string_) Order Product Images.
*   `orderStatus` (_string_, nullable)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderStatusText` (_string_) Order Status Text.
*   `orderType` (_string_, nullable) Type of order. Used in case of BOPIS (STORE\_PICKUP) or BOFIS/BOSS (STORE\_FULFILLMENT) orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `bopisOrderStatus` (_string_, read-only, nullable) BOPIS/BOSS/BOFIS Order status. This is shared enum used for OrderStatus.
*   `status` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `isSplitCart` (_boolean_, nullable) Flag indicating if this order is part of a split cart order.  
    Default: `false`.
*   `fulfillmentType` (_string_) Fulfillment Type-IN\_STORE, ONLINE, MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `parentOrderId` (_string_, nullable) Parent order ID in case this order is part of a split/mixed order. For example, this order is IN\_STORE order which is part of an order that had IN\_STORE and ONLINE orders.
*   `orderAttribution` (_OrderAttribution_)
*   `paymentStatus` (_string_, nullable) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `currency` (_string_, nullable) Currency code. 3 letter currency code.  
    Example: `USD`.
*   `manualReceiptId` (_string_) Manual Receipt ID.
*   `externalOrderID` (_string_)

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### Transaction

The transaction details.

*   `transactionTimeStamp` (_integer (int64)_, required) Timestamp from when the transaction was executed. Epoch time in milliseconds.  
    Example: `1714112491`.
*   `transactionType` (_TransactionType_)
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128.
*   `summary` (_CartSummary_, required)
*   `storeAttribution` (_StoreAttribution_)
*   `receiptPrintCount` (_integer (int32)_, nullable) Receipt print count — the number of original and duplicate receipts.  
    Default: `1`.
*   `fiscalData` (_OrderFiscalData_)
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions. Applicable for tax countries and if the sale is tax exempted.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `tenders` (_array of OrderPaymentDetails_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Refund payments. If it is a return or exchange transaction, it will have refund payments.
*   `shippingAddress` (_Address_)
*   `shippingMethod` (_ShippingMethod_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products in this order. The list doesn't include returned products. Required for sale transactions. For returns where all items were returned, the list is empty.
*   `returnProductList` (_array of Product_, nullable) List of items that have been returned. It is mandatory for return and exchange transaction.
*   `numberOfLineItems` (_integer (int32)_, read-only) Total number of line items.
*   `receiptId` (_string_, read-only, nullable) Receipt ID for the transaction. Applicable for fiscal reporting.
*   `store` (_Store_, required)
*   `profile` (_Profile_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `returnProductPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `customerEmail` (_string_, nullable) Customer email ID. Available for signed-in customers or when email is captured in the shipping address for guest customers.  
    Maximum length: 128.
*   `manualReceiptId` (_string_, nullable) Manual receipt ID. Required in some countries like Portugal where a pre-printed paper receipt with its own receipt ID needs to be issued for offline transactions.
*   `offlineMode` (_boolean_, nullable) Flag indicating if the transaction was executed in offline mode or not.  
    Default: `false`.
*   `referenceReceiptId` (_string_, nullable) Reference receipt ID. Populated for return and exchange transactions. This field provides original sale's receipt ID for reference.
*   `storeAssociate` (_Associate_)
*   `duplicateReceiptText` (_string_) For internal use only. Don't use in external systems. Duplicate receipt text printed on the receipt, for example, 'Duplicata' or 'Copy of Original Document'.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `productNotesList` (_array of OrderDetailNote_, nullable) List of product notes for this transaction if any.
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `employee` (_Employee_)
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method, and other delivery details. This field is used for item level shipping method and address. Mandatory for all delivery items if item level shipping method or item level shipping address is enabled. For more details, see:.
*   `deliveryGroupChangeList` (_ProductDeltaDeliveryGroup_)
*   `nafCode` (_string_, nullable) NAF code. NAF codes in France are used to identify the type of business of an enterprise. For example, 4772A means retail sale of footwear.
*   `rewardList` (_array of Reward_, read-only, nullable, deprecated) Deprecated. Use `orderProductList.priceAdjustments` instead.
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `productPickUpDetailList` (_array of ProductPickUpDetail_, nullable) List of product pickup detail.  
    Applicable if the order is edit order.
*   `returnCustomerInformation` (_ReturnCustomerInformation_)
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Fulfillment type for the order. For example, IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `removedDeliveryGroups` (_array of DeliveryGroup_, nullable) The removed delivery group during the edit order mode.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### PrintData

Print Data object. Used to print fiscalization related information on receipts.

*   `name` (_string_) Name of the field which holds this value.
*   `value` (_string_) Actual value that will be printed.
*   `label` (_string_) Label against which this value will be printed.
*   `type` (_string_) Indicates type of data to be printed, for example, TEXT or QRCode.  
    Allowed values: `Text`, `QRCode`.

### HeaderElement

*   `name` (_string_)
*   `value` (_string_)
*   `parameterCount` (_integer (int32)_)
*   `parameters` (_array of NameValuePair_)

### PaypalData

PayPal details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `payerId` (_string_)
*   `token` (_string_)
*   `email` (_string_)
*   `payPalInvoiceId` (_string_)
*   `referenceTransactionId` (_string_)
*   `authTransactionId` (_string_)
*   `payPalTokenTimestamp` (_string_)

### SquareData

Square Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `clientId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)

### AdyenData

Adyen Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `pspAuthCode` (_string_)
*   `pspReference` (_string_)
*   `cardType` (_string_)
*   `cardHolderName` (_string_)
*   `cardExpiryYear` (_string_)
*   `cardExpiryMonth` (_string_)
*   `cardString` (_string_)
*   `tenderReference` (_string_)
*   `terminalId` (_string_)
*   `cardNumber` (_string_)
*   `operatingMode` (_string_)
*   `threeds2Details` (_string_)

### OrderAttribution

Order attributions corresponding to this order.

*   `orderId` (_string_, read-only) Order Id.
*   `notificationId` (_string_, read-only, nullable) Notification sent corresponding to the order.
*   `messageId` (_string_, read-only, nullable) Message triggered corresponding to the order.
*   `geofenceId` (_string_, read-only, nullable) Geofence ID corresponding to the order.
*   `branchId` (_string_, read-only, nullable) Branch ID corresponding to the order.
*   `storeAreaLevel1Id` (_string_, read-only, nullable) Store Area level 1 corresponding to the order.
*   `storeAreaLevel2Id` (_string_, read-only, nullable) Store Area level 2 corresponding to the order.
*   `storeAreaLevel3Id` (_string_, read-only, nullable) Store Area level 3 corresponding to the order.
*   `storeAreaLevel4Id` (_string_, read-only, nullable) Store Area level 4 corresponding to the order.
*   `storeAreaLevel5Id` (_string_, read-only, nullable) Store Area level 5 corresponding to the order.
*   `storeRegisterId` (_string_, read-only, nullable) Store register corresponding to the order.
*   `registerTransactionId` (_string_, read-only, nullable) Register transaction ID corresponding to the order.

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### TransactionType

The type of transaction. Three types of transactions can be done on an order: SALE, RETURN and EXCHANGE.

Type: `string`.

Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`, `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### OrderPaymentDetails

Payment information: The system supports multiple payment options.  
Whenever an order is purchased using payment instrument/s,  
the order will have this list of tenders. However, there are some exceptional scenarios  
where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### Associate

Store associate.

*   `storeAssociateID` (_string_) ID of the store associate (POS login ID for the associate).
*   `storeID` (_string_, nullable) Store ID of the associate.
*   `merchantUserID` (_string_, nullable) Merchant's underlying system's user ID for the store associates. For example, LoginId for underlying OMS or Salseforce Commerce.
*   `paymentDeviceMerchantID` (_string_, nullable) Merchant ID of a payment device assigned to the associate.
*   `paymentDeviceID` (_string_, nullable) ID of a payment device, like terminal ID, assigned to the associate.
*   `storeAssociatePassword` (_string_) Store associate's password (POS Login Password for the associate).
*   `merchantPassword` (_string_, nullable) Merchant's underlying system's password for the associate.
*   `storeAssociatePasswordPin` (_string_, nullable) Password hint for the associate's POS login.
*   `firstName` (_string_, nullable) First name of the associate.
*   `lastName` (_string_, nullable) Last name of the associate.
*   `storeType` (_string_) Type of the store where the associate works. Possible values include: Regular, Popup, Outlet or eComm.
*   `role` (_string_) The associate's role in the store. Possible values include: STORE\_ASSOCIATE, STORE\_MANAGER or AREA\_MANAGER.
*   `passwordSetOn` (_integer (int64)_, nullable) Date when password was set last time. Represented as the number of milliseconds since epoch.
*   `storeAssociatePasswordFlag` (_boolean_) Flag indicating that the store associate password is updated during associate update operation. Used only during update operation.
*   `merchantPasswordFlag` (_boolean_) Flag indicating that the merchant password is updated during associate update operation. Used only during update operation.
*   `storeAssociateSecretFlag` (_boolean_, nullable) Flag indicating that the store associate secret is updated during associate update operation. Used only during update operation.
*   `imageUrl` (_string_, nullable) The associate's image URL.
*   `active` (_boolean_) Specifies whether the status of the associate is active (true) or removed/deactivated (false).
*   `emailId` (_string_, nullable) Email ID of the associate.
*   `mobilePhoneNumber` (_string_, nullable) Mobile phone number of the associate.
*   `additionalStoreIDs` (_array of string_, nullable) Additional store IDs where the associate can log in.
*   `gender` (_string_) Gender of the store associate.  
    Allowed values: `Male`, `Female`, `Neutral`, `Unknown`.
*   `hireDate` (_integer (int64)_, nullable) Date when the associate is hired or can start work in the store.
*   `terminationDate` (_integer (int64)_, nullable) Termination date for the associate.
*   `firstLoginPasswordReset` (_boolean_) Flag indicating that the password is set on the first login.
*   `mobileConfigID` (_string_, nullable) Mobile configuration ID.  
    Maximum length: 128. Example: `134ac374-0f49-4239-a161-ccfe4d3d7686`.

### ProductDeltaDeliveryGroup

List of delivery groups for product.  
, corresponding order item id and new delivery group id.  
It is used for edit order only when changing the delivery group for existing item.

*   `deliveryGroupId` (_string_, required) Delivery group id. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.

### ProductPickUpDetail

List of product pickup detail.  
Applicable if the order is edit order.

*   `orderItemId` (_string_)
*   `pickupDetailId` (_string_)
*   `pickupLocation` (_Store_)
*   `dateTimeSlot` (_DateTimeSlot_)

### ReturnCustomerInformation

Return - Customer Information. For return or exchange transactions, use this object to capture information about the person returning the items. Note: This might or might not be the actual customer who purchased the items. This object is exclusively to capture information about the person returning items.

*   `firstName` (_string_, nullable) First Name.
*   `lastName` (_string_, nullable) Last Name.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `email` (_string_, nullable) Email ID.
*   `address` (_Address_)
*   `personalId` (_PersonalID_)

### NameValuePair

*   `name` (_string_)
*   `value` (_string_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### PersonalID

Customer/Person Identification Information.

*   `type` (_string_, nullable) ID type, for example, State ID, Military ID, or Driving License.
*   `value` (_string_, nullable) ID Number/Value.
*   `expiry` (_string (date-time)_, nullable) ID Expiration Date.
*   `issuedBy` (_string_, nullable) Issued by state.

<!-- document id=ef84ed453d881b11b5a8a28ecbaa8bb99905722bf36da797c655fbd1c632d4b1 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/orders.md -->

Orders

# Orders

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/orders/orders-oas-v1-public.yaml)

## API Overview

Use the Orders API to update order status and order payment status, edit shipping addresses and custom order properties, manage order payment instruments, and get order information.

### Authentication & Authorization

The client requesting the order information must have access to the Orders resource. The API requests pass a system-to-system bearer token in the header of the request. The `POST /orders` endpoint uses the [ShopperTokenTsob](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=security%3AShopperTokenTsob) security scheme.

You must include `sfcc.orders` or `sfcc.orders.rw` in the client ID used to generate the OAuth token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

#### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Update Order Statuses

An order uses several status properties to define its workflow state. Some of them are used to trigger internal processes, such as inventory allocation. Others have no default function, but are available for use with customizations.

##### Order Status

The Order status reflects the overall status of the order. Transitions between order statuses trigger actions such as invoice generation and release of inventory reservations.

Order status can have one of the following values:

*   `created` - Default value; denotes that the order was created in the system but is not yet placed.
*   `new` - Set this value to place the order. When you set this value, the system generates shipment and invoice numbers. After the order is placed, you can’t change the order status to `created` or `failed`.
*   `failed` - Set this value to fail the order, for example, when you reject the order or when its payment fails. When you set this value, the system releases the order’s inventory reservations and removes any coupon redemptions. You can only set this value if the current order status is `created`. If you change the order status from `failed` to `created`, the system tries to revert the actions taken when it was set to `failed`. If inventory isn’t available, the reversion can fail.
*   `failed_with_reopen` - Set this value to fail the order and reopen the basket, if applicable. The order status is set to `failed`.
*   `completed` - Set this value to mark the order as complete, based on your business process, for example: when the order is fully paid, exported, and shipped.
*   `cancelled` - Set this value to cancel the order, for example: when the shopper requests it. When you set this value, the system releases the order’s inventory reservations, restores any wishlist items, and removes any coupon redemptions. If you change the order status from `cancelled` to `completed` or `new`, the system tries to revert the actions taken when it was set to `cancelled`. If inventory isn’t available, the reversion can fail.

##### Confirmation Status

An order confirmation is a document the vendor sends to the shopper. It confirms that the order has been received and accepted. You can use confirmation status to reflect the state of the document, or for other customizations. This field is provided for use in customizations. It isn’t associated with any default functionality.

Confirmation status can have one of the following values:

*   `not_confirmed` - Default value.
*   `confirmed` - Set this value when the order confirmation is sent to the shopper.

##### Export Status

After an order is placed, it must be fulfilled. If your process includes an external fulfillment system, such as a Warehouse Management System, you can use export status to manage the export of order data to the external system. For example, after using the GET /orders endpoint to get order data to export, set the order’s export status to `exported`. When identifying orders to export, your query can include orders with export status `ready` and exclude orders with export status `exported`.

Export status can have one of the following values:

*   `not_exported` - Default value.
*   `ready` - (custom purpose) Set this value when the order is ready for export.
*   `exported` - Set this value when the order has been exported. When you set this value, the system finalizes the order’s inventory transactions.
*   `failed` - (custom purpose) Set this value when the order export fails.

##### External Status

The external status field can hold any string value. For example, you can use it for values related to an external fulfillment system. This field is provided for use in customizations, and isn’t associated with any default functionality.

##### Payment Status

Use payment status to denote whether an order is partially or fully paid. This field is provided for use in customizations, and isn’t associated with any default functionality.

Payment status can have one of the following values:

*   `not_paid` - Default value.
*   `part_paid` - Set this value when the order is partially paid.
*   `paid` - Set this value when the order is fully paid.

##### Shipping Status

Use shipping status to denote whether an order is partially or fully shipped. This field is provided for use in customizations, and isn’t associated with any default functionality.

Shipping status can have one of the following values:

*   `not_shipped` - Default value.
*   `part_shipped` - Set this value when the order is partially shipped.
*   `shipped` - Set this value when the order is fully shipped.

Example scenarios:

*   After a successful fraud check and payment authorization, set the order status to `new`.
*   After a failed fraud check or payment authorization, set the order status to `failed`.
*   After an order’s information is exported to the warehouse system, set the export status to `exported`.
*   After the warehouse ships an order, set the shipping status to `shipped`.

#### Change Shipping Address

Use the Orders API to update the shipping address on an order.

For example, a shopper places an order, and then sends a request to change the shipping address on that order.

#### Get Order Data

Use the Orders API system-to-system integration use cases for order retrieval, reporting, dashboards, and so on. You can get information about a single order by specifying the order number, or get information about multiple orders by searching with attribute filters.

You can use the following attribute filters:

*   order status
*   export status
*   external status
*   confirmation status
*   payment status
*   shipping status
*   creation date to/from
*   last modified date to/from
*   offset
*   limit

You can sort the results in ascending or descending order using the following attributes (default: descending):

*   creation date
*   last modified date

#### Create Orders

Use the createOrders endpoint to create orders from a third-party system, such as a social media platform. Before using the endpoint, you must first complete the checkout process: apply all sanity checks, reserve inventory, authorize payment, apply promotions, and calculate the full cost of the order. Orders made by third-party systems are treated the same as orders made directly through the B2C Commerce platform, including how status updates and exports are handled.

#### Update Orders

Use the updateOrder endpoint to make changes to custom order attributes.

### Related APIs

*   [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) — Create orders from baskets during the checkout flow.

**Version:** 1.6.4

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/checkout/orders/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.orders: Scope granting read access to order endpoints
    *   Scope sfcc.orders.rw: Scope granting read and write access to order endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
*   `ShopperTokenTsob` (oauth2) `ShopperTokenTsob` (TSOB = trusted system on behalf) is a child of the `ShopperToken` security scheme and extends the functionality of `ShopperToken` for specific use cases. A token of type `ShopperTokenTsob` allows you to access Shopper API endpoints, including OCAPI and B2C Commerce API for headless applications. Other than endpoints that require this specific subtype, you can access all other endpoints secured by the `ShopperToken` parent scheme with a `ShopperTokenTsob`. To learn how to get a `ShopperTokenTsob` token, see [getTrustedSystemAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:getTrustedSystemAccessToken).
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/trusted-system/token)
    *   Scope sfcc.orders: Scope granting read access to order endpoints
    *   Scope sfcc.orders.rw: Scope granting read and write access to order endpoints

## Operations

### GET Return order details that match the query filters. By default, calling this API with no filter returns the 100 most recently created orders. To return up to 200 orders, use the limit parameter. To return a page of results past the first page, use a resource offset. \*Note\* : The sum of the offset and limit parameters cannot be greater than 10000.

`GET /organizations/{organizationId}/orders`

Operation ID: `getOrders`. Security: AmOAuth2 (sfcc.orders, sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `sortBy` (query, string) Sort results by creation date or last modified date. The default is creation date.  
    Allowed values: `creation_date`, `last_modified_date`. Default: `creation_date`.
*   `sortOrder` (query, string) Sort results in ascending or descending order. The default is descending.  
    Allowed values: `asc`, `desc`. Default: `desc`.
*   `status` (query, string) Filter results by status. Valid statuses are 'new', 'completed', and 'cancelled'. You can include up to two statuses as a comma-separated string.
*   `exportStatus` (query, array of object, style: form, explode: false) Filter results by export status. Valid export statuses are 'not\_exported', 'exported', 'ready', and 'failed'. You can include up to three export statuses as a comma-separated string.  
    Maximum items: 3.
    
    _Example_
    
    ```
    not_exported,ready,failed
    ```
    
    _Example_
    
    ```
    [
      "not_exported",
      "ready",
      "failed"
    ]
    ```
    
*   `externalStatus` (query, string) Filter results by external status.
*   `confirmationStatus` (query, string) Filter results by confirmation status. Valid confirmation statuses are 'confirmed' and 'not\_confirmed'.
    
    The order confirmation status.
    
      
    Allowed values: `confirmed`, `not_confirmed`. Example: `confirmed`.
*   `paymentStatus` (query, array of object, style: form, explode: false) Filter results by payment status. Valid payment statuses are 'not\_paid', 'part\_paid', and 'paid'. You can include up to two payment statuses as a comma-separated string.  
    Maximum items: 3.
    
    _Example_
    
    ```
    not_paid,part_paid
    ```
    
    _Example_
    
    ```
    [
      "not_paid",
      "part_paid"
    ]
    ```
    
*   `shippingStatus` (query, array of object, style: form, explode: false) Filter results by shipping status. Valid shipping statuses are 'not\_shipped', 'part\_shipped', and 'shipped'. You can include up to two shipping statuses as a comma-separated string.  
    Maximum items: 3.
    
    _Example_
    
    ```
    not_shipped,part_shipped
    ```
    
    _Example_
    
    ```
    [
      "not_shipped",
      "part_shipped"
    ]
    ```
    
*   `creationDateFrom` (query, string (date-time)) If passed, will return records where the `creationDate` is equal to or greater than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `creationDateTo` (query, string (date-time)) If passed, will return records where the `creationDate` is less than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModifiedDateFrom` (query, string (date-time)) If passed, will return records where the `lastModifiedDate` is equal to or greater than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModifiedDateTo` (query, string (date-time)) If passed, will return records where the `lastModifiedDate` is less than the passed `date-only`.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 100.  
    Default: `100`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Order details returned successfully.
    
    Media type: `application/json`. Schema: `OrdersResponse`.
    
    _Example: Order_
    
    ```
    {
      "data": [
        {
          "adjustedMerchandizeTotalTax": 4.95,
          "adjustedShippingTotalTax": 0.3,
          "billingAddress": {
            "address1": "45 Main Rd.",
            "city": "Burlington",
            "countryCode": "US",
            "firstName": "Max",
            "fullName": "Max Mustermann",
            "lastName": "Mustermann",
            "phone": "6175555555",
            "postalCode": "05408",
            "stateCode": "MA"
          },
          "confirmationStatus": "confirmed",
          "createdBy": "storefront",
          "creationDate": "2015-05-19T15:23:18.000Z",
          "currency": "USD",
          "customerInfo": {
            "customerId": "abMKqMaNYOBMnNdDNzyC5oNTi5",
            "customerName": "Max Mustermann",
            "customerNo": "0002352",
            "email": "no-reply@salesforce.com",
            "guest": true
          },
          "customerLocale": "en_US",
          "exportStatus": "not_exported",
          "invoiceNo": "00000001",
          "lastModified": "2020-11-04T14:13:31.061Z",
          "merchandizeTotalTax": 4.95,
          "orderNo": "00000410",
          "orderTotal": 110.24,
          "paymentInstruments": [
            {
              "paymentCard": {
                "cardType": "Visa",
                "creditCardExpired": true,
                "expirationMonth": 1,
                "expirationYear": 2020,
                "holder": "Max Mustermann",
                "maskedNumber": "***************1111",
                "numberLastDigits": "1111",
                "validFromMonth": 1,
                "validFromYear": 2018
              },
              "paymentInstrumentId": "21052ad719a076cdc83637851e",
              "paymentMethodId": "CREDIT_CARD",
              "paymentTransaction": {
                "amount": 110.24,
                "transactionId": "40f07907428e23c4bbc6fb0446",
                "c_authResult": "AUTHORIZED"
              },
              "c_issuerBank": "JPMORGAN CHASE BANK, N.A."
            }
          ],
          "paymentStatus": "not_paid",
          "placeDate": "2015-05-19T15:23:18.000Z",
          "productItems": [
            {
              "adjustedTax": 4.95,
              "basePrice": 99,
              "bonusProductLineItem": false,
              "gift": false,
              "grossPrice": 103.95,
              "itemId": "99e96c7f8b46b98de2bae5d778",
              "itemText": "Flat Front Pant",
              "netPrice": 99,
              "position": 1,
              "priceAfterItemDiscount": 99,
              "priceAfterOrderDiscount": 99,
              "productId": "701643632930",
              "productName": "Flat Front Pant",
              "quantity": 1,
              "shipmentId": "me",
              "tax": 4.95,
              "taxBasis": 99,
              "taxRate": 0.05
            }
          ],
          "productSubTotal": 99,
          "productTotal": 99,
          "remoteHost": "127.0.0.1",
          "shipments": [
            {
              "adjustedMerchandizeTotalTax": 4.95,
              "adjustedShippingTotalTax": 0.3,
              "gift": false,
              "merchandizeTotalTax": 99,
              "productSubTotal": 99,
              "productTotal": 99,
              "shipmentId": "me",
              "shipmentNo": "00000001",
              "shipmentTotal": 110.24,
              "shippingAddress": {
                "address1": "45 Main Rd.",
                "city": "Burlington",
                "countryCode": "US",
                "firstName": "Max",
                "fullName": "Max Mustermann",
                "lastName": "Mustermann",
                "phone": "6175555555",
                "postalCode": "05408",
                "stateCode": "MA"
              },
              "shippingMethod": {
                "id": "DefaultShippingMethod"
              },
              "shippingStatus": "not_shipped",
              "shippingTotal": 5.99,
              "shippingTotalTax": 0.3,
              "taxTotal": 5.25
            }
          ],
          "shippingItems": [
            {
              "adjustedTax": 0.3,
              "basePrice": 5.99,
              "grossPrice": 6.29,
              "itemId": "23ace383d9355c881f1c00417a",
              "itemText": "Shipping",
              "netPrice": 5.99,
              "priceAfterItemDiscount": 5.99,
              "shipmentId": "me",
              "tax": 0.3,
              "taxBasis": 5.99,
              "taxRate": 0.05,
              "type": "fixed_price"
            }
          ],
          "shippingStatus": "not_shipped",
          "shippingTotal": 5.99,
          "shippingTotalTax": 0.3,
          "siteId": "ShoppingSite",
          "status": "new",
          "taxation": "net",
          "taxTotal": 5.25
        }
      ]
    }
    ```
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### POST Create an order.

`POST /organizations/{organizationId}/orders`

Operation ID: `createOrders`. Security: ShopperTokenTsob (sfcc.orders.rw).

Use this endpoint whenever a fully calculated and paid or authorized order is created in any third-party system.

The endpoint can create an order on-the-fly in the Commerce Cloud platform by passing the order as JSON payload in the body of the POST request.

Other than the Basket API, this endpoint decouples any relation to other system domains, such as:

*   Products
*   Inventory
*   Promotions
*   Gift certificates
*   Coupons

The order isn't treated differently than any other orders in the Commerce Cloud platform, including status updates and order exports.

**Note**: For the custom attribute to be available for orders, configure it in Business Manager for both Basket and Order objects.

**Important**: This endpoint uses the `ShopperTokenTsob` security scheme. Always check the Security section of the endpoint documentation, which, by default, is hidden.

### Preconditions

The checkout must happen before making a request to this endpoint. That means that all sanity checks _are_ applied, the inventory _is_ reserved, the payment _is_ authorized, and the Basket _is_ fully calculated (including all promotions).

After meeting these conditions, it's possible to create the order in the Commerce Cloud platform.

### Decoupling

This endpoint can create an order with unknown products, different pricing for known products, unplanned price-adjustments (unrelated to the system's configured promotions), and passing unknown payment and shipping methods.

**Note**: There's no lookup or calculation, even if the passed object is configured in the platform.

### Still Coupled

The endpoint is still coupled to:

*   the taxation policy (gross or net) specified in the site's preferences.
*   the passed currency, which must be defined in the site.

### Calculation

The platform does not perform multiplying or dividing operations on this order.

The following fields are summed during runtime on the platform:

**Order Level**

*   `adjustedMerchandizeTotalTax`
*   `adjustedShippingTotalTax`
*   `merchandizeTotalTax`
*   `adjustedTax`
*   `productSubTotal`
*   `productTotal`
*   `shippingTotalTax`
*   `orderTotal`
*   `taxTotal`

**Line Item Level**

*   `priceAfterItemDiscount`
*   `priceAfterOrderDiscount`
*   `adjustedTax`

**Shipment**

*   `merchandizeTotalTax`
*   `productSubTotal`
*   `productTotal`
*   `shippingTotalTax`

To make sure the fields are summed correctly, the passed `orderTotal` and `taxTotal` are compared to the platform's summed `orderTotal` and `taxTotal`.

An `InvalidOrderTotalException` or `InvalidTaxTotalException` is thrown if the calculation doesn't match.

The `orderTotal` and `taxTotal` are calculated as follows:

*   `orderTotal` = sum(`ProductLineItems.grossPrice`) + sum(`Shipments.shipmentTotal`) - sum(`ProductLineItems.PriceAdjustments.grossPrice` + `Order.PriceAdjustments.grossPrice`)
*   `taxTotal` = sum (`ProductLineItems.tax`) + sum(`Shipments.taxTotal`) - sum(`ProductLineItems.PriceAdjustments.tax` + `Order.PriceAdjustments.tax`)

### Order Status

The order is automatically placed after creation.

The payment status can be set via payload.

All other status can be set via PATCH `orders/{orderNo}/status`.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `CreateOrderRequest`.

_Example: minimalExample_

```
{
  "billingAddress": {
    "address1": "43 Main Rd.",
    "city": "Burlington",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "channelType": "instagramcommerce",
  "currency": "USD",
  "orderNo": "0000019373",
  "orderTotal": 66.91,
  "paymentInstruments": [
    {
      "paymentMethodId": "PAYPAL",
      "paymentTransaction": {
        "amount": 66.91,
        "transactionId": "abc13384ajsgdk1"
      }
    }
  ],
  "productItems": [
    {
      "basePrice": 30.98,
      "grossPrice": 61.96,
      "netPrice": 49.57,
      "productId": "black-shoe_29347-38",
      "productName": "special edition shoe women 38",
      "quantity": 2,
      "shipmentId": "shipment1",
      "tax": 12.39
    }
  ],
  "shipments": [
    {
      "shipmentId": "shipment1",
      "shippingAddress": {
        "address1": "43 Main Rd.",
        "city": "Burlington",
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "shippingMethod": "EXPRESS",
      "shippingTotal": 4.95,
      "taxTotal": 0
    }
  ],
  "taxTotal": 12.39
}
```

_Example: fullExample_

```
{
  "billingAddress": {
    "address1": "45 Main Rd.",
    "city": "Burlington",
    "countryCode": "US",
    "firstName": "John",
    "fullName": "John Doe",
    "jobTitle": "Product Manager",
    "lastName": "Doe",
    "phone": "6175555555",
    "postalCode": "01803-2336",
    "secondName": "Jr.",
    "stateCode": "MA",
    "suffix": "Jr.",
    "suite": "suite",
    "title": "M.Sc."
  },
  "businessType": "b2c",
  "channelType": "instagramcommerce",
  "currency": "USD",
  "customerLocale": "en_US",
  "orderNo": "00000041",
  "orderPriceAdjustments": [
    {
      "amount": 5,
      "basePrice": -6,
      "grossPrice": -6,
      "itemText": "5 off",
      "netPrice": -5,
      "reasonCode": "registered",
      "tax": -1,
      "taxBasis": 6
    }
  ],
  "orderTotal": 113.24,
  "paymentInstruments": [
    {
      "paymentMethodId": "CREDITCARD",
      "paymentTransaction": {
        "amount": 113.24,
        "transactionId": "abc13384ajsgdk1"
      }
    }
  ],
  "paymentStatus": "paid",
  "productItems": [
    {
      "basePrice": 99,
      "brand": "brand",
      "grossPrice": 103.95,
      "itemText": "Flat Front Pant",
      "netPrice": 99,
      "priceAdjustments": [
        {
          "amount": 5,
          "grossPrice": -6,
          "itemText": "5 off",
          "netPrice": -5,
          "reasonCode": "registered",
          "tax": -1
        }
      ],
      "productId": "701643632930",
      "productName": "Flat Front Pant",
      "quantity": 1,
      "shipmentId": "00000001",
      "tax": 4.95,
      "taxBasis": 99,
      "taxRate": 0.05
    }
  ],
  "shipments": [
    {
      "shipmentId": "00000001",
      "shippingAddress": {
        "address1": "45 Main Rd.",
        "address2": "road 2",
        "city": "Burlington",
        "companyName": "Salesforce",
        "countryCode": "US",
        "firstName": "John",
        "fullName": "John Doe",
        "jobTitle": "Product Manager",
        "lastName": "Doe",
        "phone": "6175555555",
        "postBox": "none",
        "postalCode": "01803-2336",
        "salutation": "Mr.",
        "stateCode": "MA",
        "suffix": "Jr.",
        "suite": "suite",
        "title": "M.Sc."
      },
      "shippingMethod": "EXPRESS",
      "shippingTotal": 21.29,
      "taxTotal": 4.95
    }
  ],
  "taxTotal": 7.9
}
```

_Example: multiShipmentExample_

```
{
  "billingAddress": {
    "address1": "43 Main Rd.",
    "city": "Burlington",
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "channelType": "instagramcommerce",
  "currency": "USD",
  "orderNo": "000028376",
  "orderTotal": 75.86,
  "paymentInstruments": [
    {
      "paymentMethodId": "PAYPAL",
      "paymentTransaction": {
        "amount": 75.86,
        "transactionId": "abc13384ajsgdk1"
      }
    }
  ],
  "productItems": [
    {
      "basePrice": 30.98,
      "grossPrice": 30.98,
      "netPrice": 24.79,
      "productId": "black-shoe_081273-38",
      "productName": "special edition shoe women 38",
      "quantity": 1,
      "shipmentId": "shipment1",
      "tax": 6.19
    },
    {
      "basePrice": 30.98,
      "grossPrice": 30.98,
      "netPrice": 24.79,
      "productId": "red-shirt_2937298-xl",
      "productName": "t shirt XL",
      "quantity": 1,
      "shipmentId": "shipment2",
      "tax": 6.19
    }
  ],
  "shipments": [
    {
      "shipmentId": "shipment1",
      "shippingAddress": {
        "address1": "43 Main Rd.",
        "city": "Burlington",
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "shippingMethod": "GROUND",
      "shippingTotal": 4.95,
      "taxTotal": 0
    },
    {
      "shipmentId": "shipment2",
      "shippingAddress": {
        "address1": "45 Main Rd.",
        "city": "Burlington",
        "firstName": "John",
        "lastName": "Doe"
      },
      "shippingMethod": "EXPRESS",
      "shippingTotal": 8.95,
      "taxTotal": 0
    }
  ],
  "taxTotal": 12.38
}
```

_Example: fullPaymentInstrumentExample_

```
{
  "billingAddress": {
    "address1": "45 Main Rd.",
    "city": "Burlington",
    "firstName": "John",
    "lastName": "Doe"
  },
  "channelType": "instagramcommerce",
  "currency": "USD",
  "orderNo": "0000091837",
  "orderTotal": 66.91,
  "paymentInstruments": [
    {
      "paymentMethodId": "CREDITCARD",
      "paymentTransaction": {
        "amount": 30,
        "authorizationStatus": {
          "code": "0",
          "message": "credit card successfully authorized",
          "status": 0
        },
        "transactionId": "abc13384ajsgdk1"
      }
    },
    {
      "paymentMethodId": "PAYPAL",
      "paymentTransaction": {
        "amount": 36.91,
        "authorizationStatus": {
          "code": "0",
          "message": "paypal authorized",
          "status": 0
        },
        "transactionId": "abceou98463"
      }
    }
  ],
  "paymentStatus": "paid",
  "productItems": [
    {
      "basePrice": 30.98,
      "grossPrice": 61.96,
      "netPrice": 49.57,
      "productId": "black-shoe_97253-38",
      "productName": "special edition shoe women 38",
      "quantity": 2,
      "shipmentId": "shipment1",
      "tax": 12.39
    }
  ],
  "shipments": [
    {
      "shipmentId": "shipment1",
      "shippingAddress": {
        "address1": "45 Main Rd.",
        "city": "Burlington",
        "firstName": "John",
        "lastName": "Doe"
      },
      "shippingMethod": "GROUND",
      "shippingTotal": 4.95,
      "taxTotal": 0
    }
  ],
  "taxTotal": 12.39
}
```

#### Responses

*   **201** Order created successfully. No content returned.
    
    Headers:
    
    *   `Location` (string) The location for accessing the created order.
*   **400** The passed taxTotal is not equal to the calculated taxTotal.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidOrderTotal_
    
    ```
    {
      "title": "Invalid Order Total",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-order-total",
      "detail": "The passed order total '72.96' does not match the calculated order total '74.96'."
    }
    ```
    
    _Example: InvalidTaxTotal_
    
    ```
    {
      "title": "Invalid Tax Total",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-tax-total",
      "detail": "The passed tax total '2.95' does not match the calculated tax total '5.56'."
    }
    ```
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'."
    }
    ```
    
*   **404** The given shipment ID does not reference an existing shipment.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ShipmentNotFound_
    
    ```
    {
      "title": "Shipment Not Found,",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found,",
      "detail": "No shipment with ID 'express_shipment' could be found."
    }
    ```
    

### GET Return order details for the specified order number.

`GET /organizations/{organizationId}/orders/{orderNo}`

Operation ID: `getOrder`. Security: AmOAuth2 (sfcc.orders, sfcc.orders.rw).

#### Parameters

*   `orderNo` (path, OrderNo, required) The order number.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Order details returned successfully.
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example: Order_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 4.95,
      "adjustedShippingTotalTax": 1.3,
      "billingAddress": {
        "address1": "45 Main Rd.",
        "city": "Burlington",
        "countryCode": "US",
        "firstName": "Max",
        "fullName": "Max Mustermann",
        "lastName": "Mustermann",
        "phone": "6175555555",
        "postalCode": "05408",
        "stateCode": "MA"
      },
      "confirmationStatus": "confirmed",
      "createdBy": "storefront",
      "creationDate": "2015-05-19T15:23:18.000Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "cdrjZ5iQeOQjpqKldaSzbvg2E8",
        "customerName": "Max Mustermann",
        "customerNo": "0002352",
        "email": "no-reply@salesforce.com",
        "guest": true
      },
      "customerLocale": "en_US",
      "exportStatus": "not_exported",
      "invoiceNo": "00000001",
      "lastModified": "2020-11-05T13:08:05.588Z",
      "merchandizeTotalTax": 4.95,
      "orderNo": "00000410",
      "orderTotal": 110.24,
      "paymentInstruments": [
        {
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": true,
            "expirationMonth": 1,
            "expirationYear": 2020,
            "holder": "Max Mustermann",
            "maskedNumber": "***************1111",
            "numberLastDigits": "1111",
            "validFromMonth": 1,
            "validFromYear": 2018
          },
          "paymentInstrumentId": "2c36f04e453a2512fba74ae1ea",
          "paymentMethodId": "CREDIT_CARD",
          "paymentTransaction": {
            "amount": 110.24,
            "transactionId": "40f07907428e23c4bbc6fb0446",
            "c_authResult": "AUTHORIZED"
          },
          "c_issuerBank": "JPMORGAN CHASE BANK, N.A."
        }
      ],
      "paymentStatus": "not_paid",
      "placeDate": "2015-05-19T15:23:18.000Z",
      "productItems": [
        {
          "adjustedTax": 4.95,
          "basePrice": 99,
          "bonusProductLineItem": false,
          "gift": false,
          "grossPrice": 103.95,
          "itemId": "3390171e44271bad9c36592049",
          "itemText": "Flat Front Pant",
          "netPrice": 99,
          "position": 1,
          "priceAfterItemDiscount": 99,
          "priceAfterOrderDiscount": 99,
          "productId": "701643632930",
          "productName": "Flat Front Pant",
          "quantity": 1,
          "shipmentId": "me",
          "shippingItemId": "a46294cffd6945a511cb6fce05",
          "tax": 4.95,
          "taxBasis": 99,
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 99,
      "productTotal": 99,
      "remoteHost": "127.0.0.1",
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 4.95,
          "adjustedShippingTotalTax": 1.3,
          "gift": false,
          "merchandizeTotalTax": 99,
          "productSubTotal": 99,
          "productTotal": 99,
          "shipmentId": "me",
          "shipmentNo": "00000001",
          "shipmentTotal": 110.24,
          "shippingAddress": {
            "address1": "45 Main Rd.",
            "city": "Burlington",
            "countryCode": "US",
            "firstName": "Max",
            "fullName": "Max Mustermann",
            "lastName": "Mustermann",
            "phone": "6175555555",
            "postalCode": "05408",
            "stateCode": "MA"
          },
          "shippingMethod": {
            "id": "DefaultShippingMethod"
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 25.99,
          "shippingTotalTax": 1.3,
          "taxTotal": 5.25
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.3,
          "basePrice": 5.99,
          "grossPrice": 6.29,
          "itemId": "4c3d46056d49226904ee61946c",
          "itemText": "Shipping",
          "netPrice": 5.99,
          "priceAfterItemDiscount": 5.99,
          "shipmentId": "me",
          "tax": 0.3,
          "taxBasis": 5.99,
          "taxRate": 0.05,
          "type": "fixed_price"
        },
        {
          "adjustedTax": 1,
          "basePrice": 10,
          "grossPrice": 21,
          "itemId": "a46294cffd6945a511cb6fce05",
          "itemText": "Item Shipping Cost (Surcharge)",
          "netPrice": 20,
          "priceAfterItemDiscount": 20,
          "shipmentId": "me",
          "tax": 1,
          "taxBasis": 20,
          "taxRate": 0.05,
          "type": "surcharge"
        }
      ],
      "shippingStatus": "not_shipped",
      "shippingTotal": 25.99,
      "shippingTotalTax": 1.3,
      "siteId": "ShoppingSite",
      "status": "new",
      "taxation": "net",
      "taxTotal": 5.25
    }
    ```
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PATCH Update an order.

`PATCH /organizations/{organizationId}/orders/{orderNo}`

Operation ID: `updateOrder`. Security: AmOAuth2 (sfcc.orders.rw); ShopperTokenTsob (sfcc.orders.rw).

#### Parameters

*   `orderNo` (path, OrderNo, required) The order number.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderUpdateRequest`.

_Example: OrderUpdateRequest_

```
{
  "c_carrierCode": "DHL",
  "c_weight": 2.4,
  "c_review": null
}
```

#### Responses

*   **204** Order updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order confirmation status.

`PUT /organizations/{organizationId}/orders/{orderNo}/confirmation-status`

Operation ID: `updateOrderConfirmationStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderConfirmationStatusUpdateRequest`.

_Example: OrderConfirmationStatusUpdate_

```
{
  "status": "confirmed"
}
```

#### Responses

*   **204** Order confirmation status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order export status. If on-order inventory is enabled for the associated inventory list, then setting the export status to EXPORTED finalizes on-order inventory transactions for this order by changing their type from on-order to final.

`PUT /organizations/{organizationId}/orders/{orderNo}/export-status`

Operation ID: `updateOrderExportStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderExportStatusUpdateRequest`.

_Example: OrderExportStatus_

```
{
  "status": "exported"
}
```

#### Responses

*   **204** Order export status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order external status.

`PUT /organizations/{organizationId}/orders/{orderNo}/external-status`

Operation ID: `updateOrderExternalStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderExternalStatusUpdateRequest`.

_Example: OrderExportStatus_

```
{
  "status": "external status"
}
```

#### Responses

*   **204** Order external status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order payment status.

`PUT /organizations/{organizationId}/orders/{orderNo}/payment-status`

Operation ID: `updateOrderPaymentStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderPaymentStatusUpdateRequest`.

_Example: PaymentStatus_

```
{
  "status": "paid"
}
```

#### Responses

*   **204** Order payment status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PUT Update order shipping status.

`PUT /organizations/{organizationId}/orders/{orderNo}/shipping-status`

Operation ID: `updateOrderShippingStatus`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderShippingStatusUpdateRequest`.

_Example: ShippingStatus_

```
{
  "status": "shipped"
}
```

#### Responses

*   **204** Order shipping status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### POST Submit a third-party OMS status event for an order.

`POST /organizations/{organizationId}/orders/{orderNo}/oms-status-events`

Operation ID: `createOmsStatusEvent`. Security: AmOAuth2 (sfcc.orders.rw).

Accepts a single fulfillment or adjustment event from an external OMS and forwards it to the configured order event subscribers. Exactly one of fulfillmentEvent or adjustment must be present. The event is processed asynchronously; the endpoint returns 202 Accepted once the event is validated and queued.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `OmsStatusEventRequest`.

_Example: OmsFulfillmentStatusEvent_

```
{
  "omsOrderId": "MAN-9988",
  "fulfillmentEvent": {
    "id": "ship-001",
    "occurredAt": "2026-06-03T10:15:00.000Z",
    "type": "shipped",
    "lineItems": [
      {
        "id": "pli-001",
        "quantity": 2
      },
      {
        "id": "pli-002",
        "quantity": 1
      }
    ],
    "trackingNumber": "1Z999AA10123456784",
    "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "carrier": "UPS",
    "description": "Handed to carrier"
  }
}
```

_Example: OmsAdjustmentStatusEvent_

```
{
  "omsOrderId": "MAN-9988",
  "adjustment": {
    "id": "ret-7788",
    "type": "return",
    "occurredAt": "2026-06-03T10:15:00.000Z",
    "status": "completed",
    "lineItems": [
      {
        "id": "pli-001",
        "quantity": -1
      }
    ],
    "totals": [
      {
        "type": "total",
        "amount": -1999,
        "displayText": "Refund"
      },
      {
        "type": "tax",
        "amount": -160
      }
    ],
    "description": "Customer requested — defective item"
  }
}
```

#### Responses

*   **202** The status event was accepted and queued for forwarding to order event subscribers. No content returned.
*   **400** The request body or path violates required syntax (for example, neither or both event objects present, or a required field/enum constraint is violated).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **409** Order Management (OMS) is not active for this site. The site does not have an OMS integration enabled, so the status event cannot be forwarded.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OmsNotActive_
    
    ```
    {
      "title": "Oms Not Active",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/oms-not-active",
      "detail": "Order Management (OMS) is not active for this site."
    }
    ```
    

### PUT Update order status.

`PUT /organizations/{organizationId}/orders/{orderNo}/status`

Operation ID: `updateOrderStatus`. Security: AmOAuth2 (sfcc.orders.rw).

Orders in status NEW, COMPLETED or CANCELLED can't be changed to status CREATED or FAILED.

Changing the status causes different actions on inventory, coupons, wishlists, and the order itself:

*   Fail Order: Release inventory and remove coupon redemptions. (CREATED -> FAILED)
*   Fail Order With Reopen Basket: Release inventory, remove coupon redemptions, and reopen the basket, if applicable. A basket can only be reopened if no other basket for the customer exists at the moment of failing the order since a customer is limited to 1 storefront basket. (CREATED -> FAILED)
*   Undo Fail Order: Reserve inventory and recreate coupon redemptions. (FAILED -> CREATED)
*   Place Order: Generate Shipment and invoice numbers. (CREATED -> NEW, COMPLETED or CANCELLED)
*   Cancel Order: Release inventory, remove wishlist purchases, and remove coupon redemptions. (NEW, COMPLETED -> CANCELLED)
*   Undo Cancel Order: Reserve inventory, add wishlist purchases, and recreate coupon redemptions. (CANCELLED -> NEW, COMPLETED)

Actions can fail, for example: when inventory is no longer available.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `OrderStatusUpdateRequest`.

_Example: OrderStatus_

```
{
  "status": "new"
}
```

#### Responses

*   **201** Order status updated successfully. No content returned.
    
    Headers:
    
    *   `Location` (string) The location for accessing the reopened basket.
*   **204** Order status updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given site ID does not reference an existing site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    
*   **409** The failed order can't be reopened.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: UndoFailOrder_
    
    ```
    {
      "title": "Undo Fail Order",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/undo-fail-order",
      "detail": "The failed order with number '00020029’ cannot be reopened."
    }
    ```
    

### PATCH Update the payment instrument of an order.

`PATCH /organizations/{organizationId}/orders/{orderNo}/payment-instruments/{paymentInstrumentId}`

Operation ID: `updateOrderPaymentInstrument`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `paymentInstrumentId` (path, string, required) ID of the payment instrument.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `PaymentInstrumentUpdateRequest`.

_Example: OrderPaymentInstrument_

```
{
  "c_giftCardNumber": "12kH5DSkfsaErrRjKheWqqZ"
}
```

#### Responses

*   **204** Order payment instrument updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given payment instrument ID does not reference an existing payment instrument.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ShipmentNotFound: same as POST /organizations/{organizationId}/orders 404 response._
    

### PATCH Update the transaction of an order payment instrument.

`PATCH /organizations/{organizationId}/orders/{orderNo}/payment-instruments/{paymentInstrumentId}/transaction`

Operation ID: `updateOrderPaymentTransaction`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `paymentInstrumentId` (path, string, required) ID of the payment instrument.  
    Minimum length: 1.
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `PaymentTransactionUpdateRequest`.

_Example: OrderStatus_

```
{
  "c_externalReferenceCode": "dfg73DsFgH93Lkj2SaArePos",
  "c_processedDate": "2019-10-07",
  "c_additionalInformation": "Brunch enim ligula congue eu tempus craft beer tellus amet non urna sapien you probably haven’t heard of them eros ornare massa massa. Duis craft beer mattis pellentesque nulla risus arcu San Francisco adipiscing proin lorem sapien integer wire-rimmed glasses auctor ipsum cursus eget nam. Toms bibendum donec vivamus molestie vulputate fixie cursus amet eget nibh integer craft beer pellentesque odio mauris porttitor sodales."
}
```

#### Responses

*   **204** Payment instrument transaction updated successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given payment instrument ID does not reference an existing payment instrument.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ShipmentNotFound: same as POST /organizations/{organizationId}/orders 404 response._
    

### PUT Create or replace a shipping address.

`PUT /organizations/{organizationId}/orders/{orderNo}/shipments/{shipmentId}/shipping-address`

Operation ID: `updateOrderShippingAddress`. Security: AmOAuth2 (sfcc.orders.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, string, required) ID of the shipment.  
    Minimum length: 1.
*   `orderNo` (path, OrderNo, required) The order number.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `ShippingAddressUpdateRequest`.

_Example: Shipment_

```
{
  "address1": "100 Presidential Way",
  "address2": "100 Presidential Way 2",
  "city": "Woburn",
  "lastName": "Smith",
  "title": "Prof. Dr.",
  "countryCode": "US",
  "phone": "+1 123 456789",
  "companyName": "DWRE",
  "secondName": "Daniel",
  "salutation": "Mr.",
  "stateCode": "MA",
  "postalCode": "01801",
  "firstName": "John",
  "jobTitle": "Director",
  "c_district": "South End",
  "c_floor": 2,
  "c_note": "Engineering"
}
```

#### Responses

*   **204** Shipping address created or replaced successfully. No content returned.
*   **400** Request body or path violate required syntax.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The given shipment ID does not reference an existing shipment.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ShipmentNotFound: same as POST /organizations/{organizationId}/orders 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### OrderExportStatus

The order export status.

Type: `string`.

Allowed values: `exported`, `not_exported`, `ready`, `failed`. Example: `exported`.

### OrderPaymentStatus

The order payment status.

Type: `string`.

Allowed values: `paid`, `part_paid`, `not_paid`. Example: `paid`.

### OrderShippingStatus

The order shipping status.

Type: `string`.

Allowed values: `shipped`, `part_shipped`, `not_shipped`. Example: `shipped`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### OrdersResponse

Document representing an orders result.

*   `data` (_array of Order_, required) The orders data.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CreateOrderRequest

Document representing the order create request.

*   `billingAddress` (_object_, required) The billing address. The name from the billing address is required and is used as the customer's name (for guest customer).
    
    Includes all fields of `Address`.
    
*   `businessType` (_string_) The business type.  
    Allowed values: `b2c`, `b2b`. Example: `b2c`.
*   `channelType` (_string_) The sales channel.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`. Example: `instagramcommerce`.
*   `currency` (_CurrencyCode_, required)
*   `customerLocale` (_string_) The locale of the customer who created the order.  
    Maximum length: 256. Example: `en_US`.
*   `orderNo` (_object_) The order number. This must be unique in the site and is generated if no orderNo is passed in payload.  
    Example: `ORDER_000000001`.
    
    Includes all fields of `OrderNo`.
    
    Example: `ORDER_000000001`.
    
*   `orderPriceAdjustments` (_array of CreateOrderPriceAdjustment_) The order-level price adjustments.  
    Maximum items: 20.
*   `orderTotal` (_number (double)_, required) The total price, including products, shipping, and tax. If this value does not match the calculated value (sum of all grossPrices minus PriceAdjustments), an InvalidOrderTotalException is thrown.  
    Example: `39.27`.
*   `paymentInstruments` (_array of CreateOrderPaymentInstrument_, required) The payment instruments list.  
    Maximum items: 20.
*   `paymentStatus` (_string_) The payment status from the order.  
    Allowed values: `paid`, `not_paid`. Example: `paid`.
*   `productItems` (_array of CreateOrderProductItems_, required) The product items.  
    Minimum items: 1. Maximum items: 200.
*   `shipments` (_array of CreateOrderShipment_, required) The shipments.  
    Minimum items: 1. Maximum items: 10.
*   `taxTotal` (_number (double)_, required) The total tax amount.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderNo

The order number

Type: `string`.

Minimum length: 1. Maximum length: 50. Example: `00000410`.

### Order

Document representing an order.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the order, including price adjustments, but not including service charges such as shipping.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the order, including shipping price adjustments.  
    Example: `0.3`.
*   `affiliatePartnerId` (_string_) The affiliate partner ID.  
    Maximum length: 256. Example: `PARTNER_US_001`.
*   `affiliatePartnerName` (_string_) The affiliate partner name.  
    Maximum length: 256. Example: `PARTNER_US_001`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `Address`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `businessType` (_string_) The business type.  
    Allowed values: `b2c`, `b2b`. Example: `b2c`.
*   `cancelCode` (_string_) The cancellation code.  
    Maximum length: 256. Example: `canceled`.
*   `cancelDescription` (_string_) The cancellation description.  
    Maximum length: 4000. Example: `Ordered by mistake.`.
*   `channelType` (_string_) The sales channel.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`. Example: `storefront`.
*   `confirmationStatus` (_OrderConfirmationStatus_)
*   `couponItems` (_array of CouponItem_) The coupon items.
*   `createdBy` (_string_) This value depends on how the order was created. If a shopper created the order, this value is Customer. If a job created the order, this value is System. Otherwise, this value is the name of the user who created the order.  
    Maximum length: 256. Example: `Customer`.
*   `creationDate` (_string (date-time)_) The timestamp when the order was created.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `customerLocale` (_string_) The locale of the customer who created the order.  
    Maximum length: 256. Example: `en_US`.
*   `currency` (_CurrencyCode_)
*   `customerInfo` (_CustomerInfo_)
*   `customerOrderReference` (_string_) The customer-specific reference information.  
    Maximum length: 256. Example: `REF_US_143`.
*   `exportStatus` (_OrderExportStatus_)
*   `externalOrderNo` (_string_) The external order number associated with the order.  
    Maximum length: 256. Example: `00000410`.
*   `externalOrderStatus` (_string_) The status from an external order associated with this order.  
    Maximum length: 256. Example: `Submitted`.
*   `externalOrderText` (_string_) The text from an external order associated with this order.  
    Maximum length: 4000. Example: `Order is being prepared`.
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items.
*   `globalPartyId` (_string_) The Customer 360 Global Party ID associated with the shopper.  
    Maximum length: 256.
*   `invoiceNo` (_string_) The invoice number.  
    Maximum length: 256. Example: `00000410`.
*   `lastModified` (_string (date-time)_) The timestamp when the order was last modified.  
    Example: `2020-11-04T14:13:31.061Z`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the order, not including price adjustments or service charges such as shipping.  
    Example: `4.95`.
*   `orderNo` (_OrderNo_, required)
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments.
*   `orderTotal` (_number (double)_) The total price, including products, shipping and, tax.  
    Example: `110.24`.
*   `paymentInstruments` (_array of PaymentInstrument_) The payment instruments list.
*   `paymentStatus` (_OrderPaymentStatus_)
*   `placeDate` (_string (date-time)_) The timestamp when the order was placed.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `productItems` (_array of ProductItem_) The product items.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products including adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `99`.
*   `remoteHost` (_string_) The IP of the host that placed this order. You can turn IP logging on or off for your site.  
    Maximum length: 40. Example: `127.0.0.1`.
*   `shipments` (_array of Shipment_) The shipments.
*   `shippingItems` (_array of ShippingItem_) The shipping items.
*   `shippingStatus` (_OrderShippingStatus_)
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments.  
    Example: `0.3`.
*   `siteId` (_SiteId_)
*   `sourceCode` (_string_) The source code assigned to the basket from which this order was created.  
    Maximum length: 256.
*   `sourceCodeGroupId` (_string_) The group ID of the source code assigned to the basket from which this order was created.  
    Minimum length: 1. Maximum length: 256.
*   `status` (_OrderStatus_)
*   `taxTotal` (_number (double)_) The total tax amount.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net).  
    Allowed values: `gross`, `net`. Example: `net`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderUpdateRequest

Request body to create an order and set custom attributes on the order. Please note that the custom attribute definition have to be configured both on the Basket and Order object in the platform.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderConfirmationStatusUpdateRequest

Request body to update the order confirmation status.

*   `status` (_OrderConfirmationStatus_, required)

### OrderExportStatusUpdateRequest

Request body to update the order export status.

*   `status` (_OrderExportStatus_, required)

### OrderExternalStatusUpdateRequest

Request body to update the order external status.

*   `status` (_string_, required) The new external status.  
    Minimum length: 1. Maximum length: 256. Example: `in_delivery`.

### OrderPaymentStatusUpdateRequest

Request body to update the order payment status.

*   `status` (_OrderPaymentStatus_, required)

### OrderShippingStatusUpdateRequest

Request body to update the order shipping status.

*   `status` (_OrderShippingStatus_, required)

### OmsStatusEventRequest

A single OMS-originated status event for an order. Exactly one of fulfillmentEvent or adjustment must be present.

One of: `any`, `any`.

*   `omsOrderId` (_string_) Optional external OMS identifier. Echoed back in forwarded order event payloads.  
    Minimum length: 1. Maximum length: 256. Example: `MAN-9988`.
*   `fulfillmentEvent` (_OmsFulfillmentEvent_)
*   `adjustment` (_OmsAdjustment_)

### OrderStatusUpdateRequest

Request body to update the order status.

*   `status` (_string_, required) The new status.  
    Allowed values: `created`, `new`, `completed`, `cancelled`, `failed`, `failed_with_reopen`. Example: `new`.

### PaymentInstrumentUpdateRequest

Request body to update custom properties.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentTransactionUpdateRequest

Request body to update custom properties.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingAddressUpdateRequest

Request body to update the shipping address.

Includes all fields of `Address`.

### Address

Document representing an order address.

*   `address1` (_string_) The first address line.  
    Maximum length: 256. Example: `45 Main Rd.`.
*   `address2` (_string_) The second address line.  
    Maximum length: 256. Example: `Apartment 204`.
*   `city` (_string_) The city.  
    Maximum length: 256. Example: `Burlington`.
*   `companyName` (_string_) The company name.  
    Maximum length: 256. Example: `Salesforce`.
*   `countryCode` (_CountryCode_)
*   `firstName` (_string_) The first name.  
    Maximum length: 256. Example: `Max`.
*   `fullName` (_string_) The full name.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `jobTitle` (_string_) The job title.  
    Maximum length: 256. Example: `Software Engineer`.
*   `lastName` (_string_) The last name.  
    Maximum length: 256. Example: `Mustermann`.
*   `phone` (_string_) The phone number.  
    Maximum length: 256. Example: `6175555555`.
*   `postBox` (_string_) The post office box.  
    Maximum length: 256. Example: `PO BOX 109`.
*   `postalCode` (_string_) The postal code.  
    Maximum length: 256. Example: `05408`.
*   `salutation` (_string_) The salutation.  
    Maximum length: 256. Example: `Mr`.
*   `secondName` (_string_) The second name.  
    Maximum length: 256.
*   `stateCode` (_string_) The state code.  
    Maximum length: 256. Example: `MA`.
*   `suffix` (_string_) The suffix.  
    Maximum length: 256. Example: `Sr`.
*   `suite` (_string_) The suite.  
    Maximum length: 256.
*   `title` (_string_) The title.  
    Maximum length: 256. Example: `Dr`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### CreateOrderPriceAdjustment

The Price Adjustment without Promotion and Coupon references - handled as `AdHocPriceAdjustments` internally.

The following fields are set:

*   manual = true
*   custom = true
*   promotionId = AD\_HOC\_PRICE\_ADJUSTMENT

*   `amount` (_number (double)_) Amount to deduct from the applied line item's price. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `6`.
*   `basePrice` (_number (double)_) The adjustment amount. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `-6`.
*   `grossPrice` (_number (double)_, required) The adjustment amount, including tax.  
    Example: `-6`.
*   `itemText` (_string_) The text describing the price adjustment.  
    Example: `6 Dollar off.`.
*   `netPrice` (_number (double)_, required) The adjustment amount, not including tax.  
    Example: `-5`.
*   `reasonCode` (_string_) The reason code why this price adjustment was made.  
    Example: `Special Offer.`.
*   `tax` (_number (double)_, required) The tax on the adjustment amount.  
    Example: `1`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this adjustment.  
    Example: `-5`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderPaymentInstrument

Document representing a payment instrument.

*   `paymentMethodId` (_string_, required) The payment method ID.  
    Maximum length: 256. Example: `PAYPAL`.
*   `paymentTransaction` (_object_) The payment transaction.
    
    Includes all fields of `CreateOrderPaymentTransaction`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderProductItems

Document representing a product item for an order.

*   `basePrice` (_number (double)_, required) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `34.32`.
*   `brand` (_string_) The brand of the line item.  
    Maximum length: 256. Example: `brand0001`.
*   `grossPrice` (_number (double)_, required) The gross price of the line item before applying any adjustments.  
    Example: `34.32`.
*   `itemText` (_string_) The text describing the item.  
    Example: `Green Umbrella`.
*   `netPrice` (_number (double)_, required) The net price of the line item before applying any adjustments.  
    Example: `30.32`.
*   `optionItems` (_array of CreateOrderOptionItem_) The array of option items. This array can be empty.  
    Maximum items: 10.
*   `priceAdjustments` (_array of CreateOrderPriceAdjustment_) The price adjustments on product line item.  
    Maximum items: 20.
*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product.  
    Maximum length: 256. Example: `green umbrella`.
*   `quantity` (_number (double)_, required) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `3`.
*   `shipmentId` (_string_, required) The ID of the shipment to which this item belongs. Shipment 'me' is reserved for the system and is not valid to pass.  
    Minimum length: 1. Maximum length: 256. Example: `shipment00001`.
*   `tax` (_number (double)_, required) The tax on the line item before applying any adjustments.  
    Example: `4`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `30.32`.
*   `taxItems` (_array of TaxItem_) The individual tax items for this product line item (e.g. state tax, county tax). When omitted, only the aggregated tax/taxRate values are persisted.  
    Maximum items: 10.
*   `taxRate` (_number (double)_) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1. Just for display. No calculation or sanity checks are applied.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderShipment

Document representing a shipment for an order.

*   `shipmentId` (_string_, required) The order-specific ID of the shipment. The field shipmentId from line items refers to this value. The first shipment always become the standard shipment and is named 'me'. The ID 'me' is reserved for the standard shipment and it is not allowed to be used by the API caller.  
    Minimum length: 1. Maximum length: 256. Example: `shipment00001`.
*   `shippingMethod` (_string_, required) The shipping method. This has no reference to any shipments configured in the platform.  
    Example: `EXPRESS`.
*   `shippingAddress` (_object_, required) The shipping address.
    
    Includes all fields of `Address`.
    
*   `shippingTotal` (_number (double)_, required) The total price of all shipping charges in the shipment. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `4.95`.
*   `taxTotal` (_number (double)_, required) The total tax on the shipment.  
    Example: `0.75`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### BonusDiscountLineItem

Document representing a bonus discount line item.

*   `bonusProducts` (_array of ProductReference_) The bonus products from which the customer can choose.
*   `couponCode` (_string_) The coupon code that triggered the promotion, if applicable.  
    Maximum length: 256. Example: `5ties`.
*   `id` (_string_) The ID of the line item.  
    Minimum length: 1. Maximum length: 256. Example: `91f4dd8bfa0653d58b7783b04f`.
*   `maxBonusItems` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotionId` (_string_) The ID of the promotion that triggered the creation of the line item.  
    Maximum length: 256. Example: `Buy1Get2`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderConfirmationStatus

The order confirmation status.

Type: `string`.

Allowed values: `confirmed`, `not_confirmed`. Example: `confirmed`.

### CouponItem

Document representing a coupon item.

*   `code` (_string_) The coupon code.  
    Maximum length: 256. Example: `5ties`.
*   `couponItemId` (_string_) The coupon item ID.  
    Minimum length: 1. Maximum length: 256. Example: `d4c9c0141e9c74c150225580f3`.
*   `statusCode` (_string_) The status of the coupon item.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`. Example: `no_applicable_promotion`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is "applied" or "no\_applicable\_promotion".  
    Example: `true`.

### CustomerInfo

Document representing a guest or logged-in customer.

*   `customerId` (_string_) The customer ID.  
    Maximum length: 100. Example: `abMKqMaNYOBMnNdDNzyC5oNTi5`.
*   `customerName` (_string_) The customer name.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `customerNo` (_string_) The customer number.  
    Maximum length: 100. Example: `0002352`.
*   `email` (_string_) The customer email address.  
    Maximum length: 256. Example: `no-reply@salesforce.com`.
*   `guest` (_boolean_) A flag indicating if the order was placed by a guest.  
    Example: `false`.

### GiftCertificateItem

A gift certificate item.

*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `50`.
*   `grossPrice` (_number (double)_) The gross price of the line item before applying any adjustments.  
    Example: `50`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Nintendo eShop gift card.`.
*   `netPrice` (_number (double)_) The net price of the line item before applying any adjustments.  
    Example: `50`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments.  
    Example: `0`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `50`.
*   `giftCertificateMerchantId` (_string_) The ID used to identify the certificate merchant.  
    Minimum length: 1. Maximum length: 256. Example: `Nintendo`.
*   `giftCertificateItemId` (_string_) The item ID.  
    Minimum length: 1. Maximum length: 256. Example: `629dea6e7b61e58da629b57b21`.
*   `message` (_string_) The gift certificate message.  
    Maximum length: 4000. Example: `Birthday present.`.
*   `recipientEmail` (_string_) The recipient email.  
    Maximum length: 256. Example: `no-reply@salesforce.com`.
*   `recipientName` (_string_) The recipient name.  
    Maximum length: 256. Example: `Daniel Mustermann`.
*   `senderName` (_string_) The sender name.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `shipmentId` (_string_) The ID of the shipment to which this item belongs.  
    Minimum length: 1. Maximum length: 256. Example: `me`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceAdjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level.

*   `basePrice` (_number (double)_) The adjustment amount. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `12`.
*   `grossPrice` (_number (double)_) The adjustment amount, including tax.  
    Example: `50`.
*   `itemText` (_string_) The text describing the adjustment.  
    Maximum length: 256. Example: `Employee discount applied.`.
*   `netPrice` (_number (double)_) The adjustment amount, not including tax.  
    Example: `38`.
*   `tax` (_number (double)_) The tax on the adjustment amount.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this adjustment.  
    Example: `50`.
*   `abTestSegment` (_object_) The AB testing segment, if enabled for the site and applicable to this price adjustment.
    
    Includes all fields of `ABTestSegment`.
    
*   `appliedDiscount` (_object_) Details describing the discount on which this price adjustment is based. For adjustments not based on a discount, this value is null.
    
    Includes all fields of `Discount`.
    
*   `campaignId` (_string_) The campaign ID of the promotion on which this price adjustment is based. For adjustments not based on a promotion, this value is null. For adjustments based on an AB test promotion, this value is not null, but isn't meaningful.  
    Minimum length: 1. Maximum length: 256. Example: `FreeShipping24`.
*   `couponCode` (_string_) The coupon code of the coupon on which this price adjustment is based. For adjustments not based on a coupon, this value is null.  
    Minimum length: 1. Maximum length: 256. Example: `5ties`.
*   `createdBy` (_string_) The user who created the price adjustment.  
    Maximum length: 256. Example: `Customer`.
*   `creationDate` (_string (date-time)_) The timestamp when the price adjustment was created.  
    Example: `2021-02-25T09:58:04.691Z`.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.  
    Example: `false`.
*   `lastModified` (_string (date-time)_) The timestamp when the price adjustment was last modified.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `manual` (_boolean_) A flag indicating whether this price adjustment was created by a manual process. If the price adjustment was created by the promotion engine, this value is always false.  
    Example: `false`.
*   `priceAdjustmentId` (_string_) The price adjustment ID.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3eee797f062161f8b`.
*   `promotionId` (_string_, required) The promotion ID of the promotion on which this price adjustment is based. Custom price adjustment can assign an arbitrary promotion ID, but it must not be used by the promotion engine. If no promotion ID is specified, then the system assigns a generated ID.  
    Minimum length: 1. Maximum length: 256. Example: `FreeShipping24`.
*   `reasonCode` (_string_) The reason code why this price adjustment was made.  
    Minimum length: 1. Maximum length: 256. Example: `Employee discount was applied.`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentInstrument

Document representing an order payment instrument.

*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `6784532`.
*   `maskedGiftCertificateCode` (_string_) The gift certificate code with the last 4 characters not masked.  
    Maximum length: 256. Example: `******Gzzy`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `PaymentCard`.
    
*   `paymentInstrumentId` (_string_) The payment instrument ID.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3eee797f062162f8b`.
*   `paymentMethodId` (_string_) The payment method ID.  
    Maximum length: 256. Example: `CREDIT_CARD`.
*   `paymentTransaction` (_object_) The payment transaction.
    
    Includes all fields of `PaymentTransaction`.
    
*   `paymentDetails` (_object_) The normalized payment details for the order payment instrument. It is read only. Omitted when no details are available for the payment.
    
    Includes all fields of `PaymentDetails`.
    
*   `fraudDecisions` (_object_) The normalized fraud decisions for the order payment instrument. It is read only. Omitted when no decisions are returned.
    
    Includes all fields of `FraudDecisions`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductItem

Document representing a product item.

*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `99.99`.
*   `grossPrice` (_number (double)_) The gross price of the line item before applying any adjustments.  
    Example: `99.99`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Nintendo DS Game Console`.
*   `netPrice` (_number (double)_) The net price of the line item before applying any adjustments.  
    Example: `80.99`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments.  
    Example: `19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `99.99`.
*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments.  
    Example: `19`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item to which this bonus product relates.  
    Minimum length: 1. Maximum length: 256. Example: `ba248414e3eee797f062162f8b`.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether this item is a bonus product.  
    Example: `false`.
*   `brand` (_string_)  
    Maximum length: 256. Example: `Nintendo`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `externalLineItemStatus` (_string_) The external line item status.  
    Maximum length: 256. Example: `Available`.
*   `externalLineItemText` (_string_) The external line item text.  
    Example: `The item is available`.
*   `gift` (_boolean_) Returns true if the item is a gift.  
    Example: `false`.
*   `giftMessage` (_string_) The gift message.  
    Maximum length: 4000. Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_string_) The product item ID. Use this to identify this item when updating its quantity or creating a custom price adjustment for it.  
    Minimum length: 1. Maximum length: 256. Example: `430ef5aad3a24de59378458434`.
*   `minOrderQuantity` (_number (double)_) The minimum order quantity for this product.  
    Example: `1`.
*   `optionItems` (_array of OptionItem_) The option items.
*   `position` (_number (double)_) The position of the product line item.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.
*   `productId` (_ProductId_, required)
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Maximum length: 4000. Example: `Nintendo DS Game Console`.
*   `quantity` (_number (double)_) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_, required) The ID of the shipment to which this item belongs.  
    Minimum length: 1. Maximum length: 256. Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is the shipping item ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method.  
    Minimum length: 1. Maximum length: 256. Example: `006490dcc338feeafc71c964bf`.
*   `stepQuantity` (_number (double)_)  
    Example: `1`.
*   `taxItems` (_array of TaxItem_) The individual tax items for this product line item (e.g. state tax, county tax).  
    Maximum items: 10.
*   `taxRate` (_number (double)_, required) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1.  
    Example: `0.19`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Shipment

Document representing a shipment.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments.  
    Example: `1.5`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments.  
    Example: `0.3`.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Maximum length: 4000. Example: `Happy Birthday`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, not including price adjustments or service charges such as shipping.  
    Example: `1.5`.
*   `productSubTotal` (_number (double)_) The total price of all products in the shipment, including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `29.99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `29.99`.
*   `shipmentId` (_string_, required) The order-specific ID of the shipment. The default value is 'me'.  
    Minimum length: 1. Maximum length: 256.
*   `shipmentNo` (_string_, required) The shipment number of this shipment. This number is automatically generated.  
    Maximum length: 256.
*   `shipmentTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments, shipping charges, and tax.  
    Example: `39.99`.
*   `shippingAddress` (_object_) The shipping address.
    
    Includes all fields of `Address`.
    
*   `shippingMethod` (_object_) The shipping method.
    
    Includes all fields of `ShippingMethodReference`.
    
*   `shippingStatus` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges in the shipment, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, not including shipping price adjustments.  
    Example: `0.3`.
*   `taxTotal` (_number (double)_) The total tax on the shipment, including item-level price adjustments and service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. This field value must match the summed up taxTotal, and an InvalidTaxTotalException is thrown if the values do not match.  
    Example: `1.8`.
*   `trackingNumber` (_string_) The tracking number of the shipment.  
    Maximum length: 256. Example: `1Z204E380338943508`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingItem

Document representing a shipping item.

*   `basePrice` (_number (double)_) The base price of the shipping item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `5.99`.
*   `grossPrice` (_number (double)_) The gross price of the shipping item before applying any adjustments.  
    Example: `5.99`.
*   `itemText` (_string_) The text describing the shipping item.  
    Maximum length: 256. Example: `Shipping`.
*   `netPrice` (_number (double)_) The net price of the shipping item before applying any adjustments.  
    Example: `5.99`.
*   `tax` (_number (double)_) The tax for the shipping item, not including price adjustments.  
    Example: `0.3`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this shipping item.  
    Example: `5.99`.
*   `adjustedTax` (_number (double)_) The tax for the shipping item, including price adjustments.  
    Example: `0`.
*   `itemId` (_string_) The shipping item ID. Use this value to identify this shipping item when updating its quantity or creating a custom price adjustment for it.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3eee798f062162f8b`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the shipping item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `4.99`.
*   `shipmentId` (_string_) The ID of the shipment to which this item belongs.  
    Minimum length: 1. Maximum length: 256. Example: `me`.
*   `taxRate` (_number (double)_, required) The tax rate applicable to this shipping line item. For a 10% tax rate, the value is 0.1.  
    Example: `0.19`.
*   `type` (_string_) The type of shipping charge applicable to this shipping item.  
    Allowed values: `fixed_price`, `surcharge`. Default: `fixed_price`. Example: `fixed_price`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderStatus

The order status.

Type: `string`.

Allowed values: `created`, `new`, `completed`, `cancelled`, `failed`. Example: `completed`.

### OmsFulfillmentEvent

A fulfillment event reported by an external OMS (for example, shipped, delivered, canceled).

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `ship-001`.
*   `occurredAt` (_string (date-time)_, required) RFC 3339 timestamp when the event occurred.  
    Example: `2026-06-03T10:15:00.000Z`.
*   `type` (_string_, required) Fulfillment event type. Common values: processing, shipped, in\_transit, delivered, failed\_attempt, canceled, undeliverable, returned\_to\_sender. Additional values are permitted.  
    Minimum length: 1. Maximum length: 256. Example: `shipped`.
*   `lineItems` (_array of OmsLineItemReference_, required)  
    Minimum items: 1. Maximum items: 200.
*   `trackingNumber` (_string_) Required when type is not "processing". Otherwise, a 400 Bad Request is returned.  
    Minimum length: 1. Maximum length: 256. Example: `1Z999AA10123456784`.
*   `trackingUrl` (_string (uri)_) Required when type is not "processing". Otherwise, a 400 Bad Request is returned.  
    Minimum length: 1. Maximum length: 2048. Example: `https://www.ups.com/track?tracknum=1Z999AA10123456784`.
*   `carrier` (_string_) The carrier handling the shipment (for example, UPS, FedEx, DHL).  
    Minimum length: 1. Maximum length: 256. Example: `UPS`.
*   `description` (_string_) Free-form note about the event provided by the OMS. Shown to support agents and forwarded to order event subscribers.  
    Minimum length: 1. Maximum length: 256. Example: `Handed to carrier`.

### OmsAdjustment

A post-order adjustment reported by an external OMS (for example, refund, return, cancellation).

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `ret-7788`.
*   `type` (_string_, required) Adjustment type (open string, for example, refund, return, credit, cancellation).  
    Minimum length: 1. Maximum length: 256. Example: `return`.
*   `occurredAt` (_string (date-time)_, required)  
    Example: `2026-06-03T10:15:00.000Z`.
*   `status` (_string_, required)  
    Allowed values: `pending`, `completed`, `failed`. Example: `completed`.
*   `lineItems` (_array of OmsAdjustmentLineItem_)  
    Maximum items: 200.
*   `totals` (_array of OmsAdjustmentTotal_)  
    Maximum items: 200.
*   `description` (_string_) Free-form note about the adjustment provided by the OMS. Shown to support agents and forwarded to order event subscribers.  
    Minimum length: 1. Maximum length: 256. Example: `Customer requested — defective item`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### CreateOrderPaymentTransaction

Document representing an order payment transaction.

*   `amount` (_number (double)_, required) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction.
    
    Includes all fields of `Status`.
    
*   `transactionId` (_string_, required) The payment service specific transaction ID.  
    Maximum length: 256. Example: `3226f0a3bc4b4f244d70dd1c2b`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CreateOrderOptionItem

An option item represents an optional purchase related to a product item, and is always associated with that parent product item. For example, a refrigerator item can have a set of option items representing different warranties on the refrigerator. A shopper can only purchase one of the warranty option items together with the parent refrigerator item.

*   `basePrice` (_number (double)_, required) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `49.99`.
*   `grossPrice` (_number (double)_, required) The gross price of the line item before applying any adjustments.  
    Example: `99.99`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Extended Warranty - None`.
*   `netPrice` (_number (double)_, required) The net price of the line item before applying any adjustments.  
    Example: `49.99`.
*   `tax` (_number (double)_, required) The tax on the line item before applying any adjustments.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `50`.
*   `optionId` (_string_, required) The ID of the option.  
    Minimum length: 1. Maximum length: 256. Example: `consoleWarranty`.
*   `optionValueId` (_string_, required) The ID of the option value.  
    Minimum length: 1. Maximum length: 256. Example: `000`.
*   `priceAdjustments` (_array of CreateOrderPriceAdjustment_) The price adjustments.  
    Maximum items: 20.
*   `productId` (_ProductId_, required)

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### TaxItem

A specific tax item for a line item (e.g. state tax, county tax).

*   `id` (_string_, required) The tax item identifier (e.g. STATE, COUNTY).  
    Minimum length: 1. Maximum length: 256. Example: `STATE`.
*   `rate` (_number (double)_, required) The tax rate for this tax item. For a 7% tax rate, the value is 0.07.  
    Example: `0.07`.
*   `value` (_number (double)_) The tax value (amount) for this tax item.  
    Example: `13.99`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductReference

Document representing a product.

*   `productId` (_ProductId_)
*   `productName` (_string_) The name of the product.  
    Maximum length: 4000. Example: `Nintendo DS Game Console`.

### ABTestSegment

Document representing an AB test segment. In an AB test that compares different customer experiences, a segment defines the customers who receive a particular experience.

*   `testId` (_string_, required) The ID of the associated AB test.  
    Minimum length: 1. Maximum length: 40.
*   `segmentId` (_string_, required) The ID of the segment.  
    Minimum length: 1. Maximum length: 40.

### Discount

Document representing a discount.

*   `amount` (_number (double)_) The discount amount for discount types that define specific discount amounts.  
    Example: `5`.
*   `percentage` (_number (double)_) The discount percent for discount types that define percentage discounts.  
    Example: `0.19`.
*   `priceBookId` (_string_) The ID of the price book for discount types that use a price book.  
    Maximum length: 256. Example: `usd-sale-prices`.
*   `type` (_string_, required) The type of discount.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`. Example: `fixed_price`.

### PaymentCard

Document representing a payment card.

*   `cardType` (_string_) The payment card type (for example: Visa).  
    Maximum length: 256. Example: `Visa`.
*   `creditCardExpired` (_boolean_) A flag indicating if the credit card is expired.  
    Example: `false`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.  
    Maximum length: 256. Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Minimum: 1. Maximum: 12. Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number. There may be a maximum of first 6 and last 4 digits.  
    Maximum length: 256. Example: `*********4422`.
*   `numberLastDigits` (_string_) The last digits of payment card number.  
    Maximum length: 4. Example: `4422`.
*   `validFromMonth` (_integer (int32)_) The month from which the payment card is valid.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year from which the payment card is valid.  
    Example: `2019`.

### PaymentTransaction

Document representing an order payment transaction.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction.
    
    Includes all fields of `Status`.
    
*   `transactionId` (_string_) The payment service specific transaction ID.  
    Maximum length: 256. Example: `3226f0a3bc4b4f244d70dd1c2b`.
*   `transactionDetails` (_object_) The normalized transaction details for the order payment transaction. It is read only. Omitted when no details are available.
    
    Includes all fields of `TransactionDetails`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentDetails

Normalized payment details for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no details are available for the payment. The values remain readable for historical orders.

*   `type` (_string_) The normalized payment method type. Expected values are `bancontact`, `card`, `gift_card`, `eps`, `ideal`, `klarna`, `sepa_debit`, `paypal`, `venmo`, `afterpay_clearpay`, `amazon_pay`, and `twint`. A custom value may also be returned. It is read only.  
    Maximum length: 256. Example: `card`.
*   `brand` (_string_) The normalized card brand. Expected values are `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, and `unknown`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `visa`.
*   `last4` (_string_) The last four digits of the payment instrument. It is read only.  
    Maximum length: 4. Example: `4242`.
*   `walletType` (_string_) The normalized digital wallet used for the payment. Expected values are `apple_pay` and `google_pay`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `apple_pay`.
*   `expirationMonth` (_integer (int32)_) The month when the payment instrument expires. It is read only.  
    Minimum: 1. Maximum: 12. Example: `12`.
*   `expirationYear` (_integer (int32)_) The year when the payment instrument expires. It is read only.  
    Example: `2028`.
*   `token` (_string_) The reference token representing the payment instrument. This is an opaque identifier, not the card number (PAN). It is read only.  
    Maximum length: 40. Example: `pm_abc123`.
*   `tokenType` (_string_) The type of token backing the reference token. Expected values are `NETWORK` and `GATEWAY`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `GATEWAY`.
*   `accountHolderName` (_string_) The name of the payment instrument account holder. It is read only.  
    Maximum length: 256. Example: `Alex Shopper`.
*   `bin` (_string_) The bank identification number (BIN) of the payment card. It is read only.  
    Maximum length: 8. Example: `424242`.
*   `dpanLast4` (_string_) The last four digits of the device primary account number for a wallet-tokenized card. It is read only.  
    Maximum length: 4. Example: `4242`.
*   `issuingCountry` (_string_) The ISO 3166-1 alpha-2 country code of the issuing bank. It is read only.  
    Maximum length: 2. Example: `US`.
*   `fundingType` (_string_) The normalized card funding type. Expected values are `CREDIT`, `DEBIT`, and `PREPAID`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `CREDIT`.

### FraudDecisions

Normalized fraud decisions for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no decisions are returned. The values remain readable for historical orders.

*   `preAuthorization` (_string_)
    
    The pre-authorization fraud decision used by the client to orchestrate checkout. Expected values are:
    
    *   `NOT_REVIEWED`: the payment instrument was not reviewed pre-authorization.
    *   `APPROVED`: the payment authorization can proceed.
    *   `CHALLENGE`: the payment authorization should be challenged with additional verification (for example, a 3D Secure challenge) before it can proceed.
    *   `DECLINED`: the payment authorization is declined.
    
    A custom value may also be returned. It is read only.
    
      
    Maximum length: 256. Example: `APPROVED`.
*   `postAuthorization` (_string_)
    
    The post-authorization fraud decision indicating whether the transaction is covered by a fraud guarantee. Expected values are:
    
    *   `NOT_REVIEWED`: the transaction was not reviewed for a fraud guarantee.
    *   `GUARANTEED`: the transaction is covered by a fraud guarantee.
    *   `NOT_GUARANTEED`: the transaction is not covered by a fraud guarantee.
    *   `PENDING`: the post-authorization fraud decision is still pending.
    
    A custom value may also be returned. It is read only.
    
      
    Maximum length: 256. Example: `GUARANTEED`.

### OptionItem

An option item represents an optional purchase related to a product item, and is always associated with the parent product item. For example, a refrigerator item can have a set of option items representing different warranties on the refrigerator. A shopper can only purchase one of the warranty option items together with the parent refrigerator item.

*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax.  
    Example: `49.99`.
*   `grossPrice` (_number (double)_) The gross price of the line item before applying any adjustments.  
    Example: `99.99`.
*   `gift` (_boolean_) Returns true if the item is a gift.  
    Example: `false`.
*   `itemText` (_string_) The text describing the item.  
    Maximum length: 256. Example: `Extended Warranty - None`.
*   `netPrice` (_number (double)_) The net price of the line item before applying any adjustments.  
    Example: `49.99`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item.  
    Example: `50`.
*   `optionId` (_string_) The ID of the option.  
    Minimum length: 1. Maximum length: 256. Example: `consoleWarranty`.
*   `optionValueId` (_string_) The ID of the option value.  
    Minimum length: 1. Maximum length: 256. Example: `000`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `productId` (_ProductId_, required)

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductListItemReference

Document representing product list item details.

*   `id` (_string_) The ID of the product list item.  
    Minimum length: 1. Maximum length: 256. Example: `ba248424e3fee797f062162f8b`.
*   `priority` (_integer (int32)_) The priority of the product list item.
*   `product` (_object_) A reference to the associated product.
    
    Includes all fields of `ProductReference`.
    
*   `productList` (_object_) A reference to the associated product list.
    
    Includes all fields of `ProductListReference`.
    
*   `public` (_boolean_)  
    Example: `false`.
*   `purchasedQuantity` (_number (double)_, required) The total quantity of this item purchased from the product list.  
    Example: `0`.
*   `quantity` (_number (double)_) The number of products or gift certificates that get shipped when purchasing this product list item.  
    Minimum: 0. Example: `1`.
*   `type` (_string_) Specifies whether the item is a product or a gift certificate.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### ShippingMethodReference

Document representing a reference to a shipping method.

*   `id` (_string_) The shipping method ID.  
    Maximum length: 256. Example: `0000457`.

### OmsLineItemReference

A reference to an order line item affected by a fulfillment event, with the fulfilled quantity.

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `pli-001`.
*   `quantity` (_integer_, required) Fulfillment line-item quantity. Zero is allowed.  
    Minimum: 0. Example: `2`.

### OmsAdjustmentLineItem

A reference to an order line item affected by an adjustment, with a signed quantity (negative for reductions/returns).

*   `id` (_string_, required)  
    Minimum length: 1. Maximum length: 256. Example: `pli-001`.
*   `quantity` (_integer_, required) Signed quantity; negative for reductions or returns.  
    Example: `-1`.

### OmsAdjustmentTotal

A signed monetary total for an adjustment, broken down by cost category, in minor currency units (for example, cents for EUR or USD; decimal places follow the order's currency).

*   `type` (_string_, required) Cost category. Well-known values: subtotal, items\_discount, discount, fulfillment, tax, fee, total. Additional values are permitted.  
    Minimum length: 1. Maximum length: 256. Example: `total`.
*   `amount` (_integer_, required) Signed amount in minor currency units (for example, cents for EUR or USD); the number of decimal places follows the order's currency. Negative for money returned to the buyer.  
    Example: `-1999`.
*   `displayText` (_string_) Text describing the adjustment total for display.  
    Minimum length: 1. Maximum length: 256. Example: `Refund`.

### Status

Document representing a status of an object.

*   `code` (_string_) The status code.  
    Maximum length: 256. Example: `OK`.
*   `message` (_string_) The message corresponding to the status.  
    Maximum length: 256. Example: `Credit Card successfully authorized.`.
*   `status` (_integer (int32)_) A constant corresponding to the status code. The value is 0 for OK, 1 for ERROR, and 2 for WARN.  
    Minimum: 0. Maximum: 2. Example: `0`.

### TransactionDetails

Normalized transaction details for the order payment transaction. Specific fields are populated depending on the `paymentDetails.type` value. All properties are optional and read only. The object is omitted entirely when no details are available.

*   `cvcResult` (_string_) The card verification code check result. Expected values are `MATCH`, `NO_MATCH`, `NOT_PROCESSED`, and `UNAVAILABLE`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `MATCH`.
*   `avsResult` (_string_) The address verification service result. Expected values are `Y` (full match), `N` (no match), `A` (address only), `Z` (postal code only), `U` (unavailable), `S` (unsupported), and `R` (retry). A custom value may also be returned. It is read only.  
    Maximum length: 1. Example: `Y`.
*   `threeDSResult` (_string_) The 3D Secure authentication result. Expected values are `AUTHENTICATED`, `ATTEMPTED`, `FAILED`, `REJECTED`, and `UNAVAILABLE`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `AUTHENTICATED`.
*   `threeDSVersion` (_string_) The 3D Secure protocol version. Expected values are `V1` and `V2`. A custom value may also be returned. It is read only.  
    Maximum length: 2. Example: `V2`.
*   `threeDSTransactionId` (_string_) The 3D Secure transaction identifier. It is read only.  
    Maximum length: 40. Example: `f25084f0-5b16-4c0a-ae5d-b24e4f`.
*   `electronicCommerceIndicator` (_string_) The electronic commerce indicator (ECI) value returned by the processor. It is read only.  
    Maximum length: 3. Example: `05`.
*   `approvalCode` (_string_) The approval code returned by the provider on a successful gift card capture. It is read only.  
    Maximum length: 256. Example: `A1B2C3`.
*   `reasonCode` (_string_) The reason code returned by the provider on a failed gift card capture. Expected values are `DECLINED` and `INSUFFICIENT_FUNDS`. A custom value may also be returned. It is read only.  
    Maximum length: 256. Example: `INSUFFICIENT_FUNDS`.
*   `processorResponseText` (_string_) The human-readable gift card processor response text. The language and localization of this text are provider-defined and may vary by provider integration. It is read only.  
    Maximum length: 256. Example: `Insufficient funds`.

### ProductListReference

Document representing a product list.

*   `description` (_string_) The description of this product list.  
    Maximum length: 256.
*   `name` (_string_) The name of this product list.  
    Maximum length: 256.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers.  
    Example: `false`.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `wish_list`.

<!-- document id=83873944ce2652b546ad60aeb673f7c4283d113745436f0b56ab0828f6dbc3ce url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-orders.md -->

Orders

# Orders

Calls to download order data and make status changes.

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### GET Query

`GET /services/data/v51.0/query`

Operation ID: `Query`. Tags: Order. Security: bearerAuth.

To look up information about orders, use the [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) resource of the main REST API from Salesforce and set the value of the `q` parameter to an SOQL query. The following examples are included in the query parameters section of this page, with corresponding examples in the responses section:

**Example 1 of 4**: `listAllOrders`

This call allows all orders made to the seller to be listed. If the item limit is exceeded, pagination may be necessary, in which case please refer to the following [documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm#retrieve_remaining_results_title).

**Example 2 of 4**: `listAllOrdersByCreateDate`

This call allows all orders made to the seller to be listed , filtered by order date. If you have more than the permissible number of items, pagination may be necessary, in which case please refer to the following [documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm#retrieve_remaining_results_title).

**Example 3 of 4**: `listAllOrdersByUpdateDate`

This call allows all orders made to the seller to be listed , filtered by order update date. If the item limit is exceeded, pagination may be necessary, in which case please refer to the following [documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm#retrieve_remaining_results_title).

**Example 4 of 4**: `getOrderByExternalId`

This call allows the listing of all order data using the external ID.

#### Parameters

*   `q` (query, string)
    
    _Example: listAllOrders_
    
    ```
    SELECT FIELDS(ALL), Atonit_Mktplace__Campaign__r.Id, Atonit_Mktplace__Campaign__r.Atonit_Mktplace__Marketplace_Id__c, Atonit_Mktplace__Campaign__r.Name, (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Line_Items__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Seller_Shipments__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Billed_Tickets__r LIMIT 200) FROM Atonit_Mktplace__Seller_Order__c WHERE Atonit_Mktplace__Seller__r.Atonit_Mktplace__Slug__c= '{{seller-external-id}}'  LIMIT 200
    ```
    
    _Example: listAllOrdersByCreateDate_
    
    ```
    SELECT FIELDS(ALL), Atonit_Mktplace__Campaign__r.Id, Atonit_Mktplace__Campaign__r.Atonit_Mktplace__Marketplace_Id__c, Atonit_Mktplace__Campaign__r.Name, (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Line_Items__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Seller_Shipments__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Billed_Tickets__r LIMIT 200)  FROM Atonit_Mktplace__Seller_Order__c WHERE Atonit_Mktplace__Seller__r.Atonit_Mktplace__Slug__c= '{{seller-external-id}}' AND Atonit_Mktplace__Order_Date__c > 2021-04-13T19:25:00.000+00:00 LIMIT 200
    ```
    
    _Example: listAllOrdersByUpdateDate_
    
    ```
    SELECT FIELDS(ALL), Atonit_Mktplace__Campaign__r.Id, Atonit_Mktplace__Campaign__r.Atonit_Mktplace__Marketplace_Id__c, Atonit_Mktplace__Campaign__r.Name, (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Line_Items__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Seller_Shipments__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Billed_Tickets__r LIMIT 200)  FROM Atonit_Mktplace__Seller_Order__c WHERE Atonit_Mktplace__Seller__r.Atonit_Mktplace__Slug__c= '{{seller-external-id}}' AND SystemModstamp > 2021-04-13T19:25:00.000+00:00 LIMIT 200
    ```
    
    _Example: getOrderByExternalId_
    
    ```
    SELECT FIELDS(ALL), Atonit_Mktplace__Campaign__r.Id, Atonit_Mktplace__Campaign__r.Atonit_Mktplace__Marketplace_Id__c, Atonit_Mktplace__Campaign__r.Name, (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Line_Items__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Seller_Shipments__r LIMIT 200), (SELECT FIELDS(ALL) FROM Atonit_Mktplace__Billed_Tickets__r LIMIT 200)  FROM Atonit_Mktplace__Seller_Order__c WHERE Atonit_Mktplace__Seller__r.Atonit_Mktplace__Slug__c='{{seller-external-id}}' AND Atonit_Mktplace__External_Id__c = '00000103-atonit-vitta' LIMIT 200
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Thu, 29 Apr 2021 11:58:14 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1713/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example getOrderByExternalId: same as GET /services/data/v51.0/query 200 response._
    
    _Example: listAllOrders_
    
    ```
    {
      "totalSize": 2,
      "done": true,
      "records": [
        {
          "Atonit_Mktplace__Campaign__r": {
            "Id": "a0f5Y00000GCTwhQAH",
            "Atonit_Mktplace__Marketplace_Id__c": "b14d96de-1669-4775-a757-629d1b74a015",
            "Name": "Campanha de Pré Venda Bombom"
          },
          "Atonit_Mktplace__Line_Items__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0B5Y00000gO1qAUAS",
                "Name": "LI-0002",
                "CreatedDate": "2021-04-13T19:27:23.000+0000",
                "LastModifiedDate": "2021-04-13T19:27:23.000+0000",
                "Atonit_Mktplace__Discount__c": 1.05,
                "Atonit_Mktplace__External_ID__c": "00000103-atonit-vitta-00000103-00000506-atonit-vitta-0",
                "Atonit_Mktplace__Notes__c": null,
                "Atonit_Mktplace__Product_Name__c": "Mini Bombom com Banana 60g - Flormel",
                "Atonit_Mktplace__Product_Variant_Marketplace_Id__c": "at_mini-bombom",
                "Atonit_Mktplace__Product_Variant__c": "a0L5Y00000o8qTQUAY",
                "Atonit_Mktplace__Quantity__c": 1,
                "Atonit_Mktplace__Seller_Shipment__c": "a0R5Y00000Sx7oeUAB",
                "Atonit_Mktplace__Total_Price__c": 9.49,
                "Atonit_Mktplace__Unit_Price__c": 10.54
              }
            ]
          },
          "Atonit_Mktplace__Seller_Shipments__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0R5Y00000Sx7oeUAB",
                "Name": "00000103-00000506-atonit-vitta",
                "CreatedDate": "2021-04-13T19:27:22.000+0000",
                "LastModifiedDate": "2021-04-13T19:27:22.000+0000",
                "Atonit_Mktplace__External_ID__c": "00000103-00000506-atonit-vitta",
                "Atonit_Mktplace__Shipping_City__c": "Test City",
                "Atonit_Mktplace__Shipping_Country__c": "US",
                "Atonit_Mktplace__Shipping_Method_Marketplace_Id__c": "004",
                "Atonit_Mktplace__Shipping_Method__c": "Super Saver",
                "Atonit_Mktplace__Shipping_Rate__c": 1.99,
                "Atonit_Mktplace__Shipping_State_Province__c": "IL",
                "Atonit_Mktplace__Shipping_Street__c": "Test Adress",
                "Atonit_Mktplace__Shipping_Type__c": "Seller",
                "Atonit_Mktplace__Shipping_Zip_Postal_Code__c": "12345",
                "Atonit_Mktplace__Custom_Shipment_Note1__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note2__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note3__c": null
              }
            ]
          },
          "Atonit_Mktplace__Billed_Tickets__r": null,
          "Id": "a0Q5Y00000UcHjMUAV",
          "Name": "00000103-atonit-vitta",
          "CreatedDate": "2021-04-13T19:27:22.000+0000",
          "LastModifiedDate": "2021-04-13T19:27:22.000+0000",
          "Atonit_Mktplace__Billing_City__c": "Test City",
          "Atonit_Mktplace__Billing_Country__c": "US",
          "Atonit_Mktplace__Billing_State_Province__c": "IL",
          "Atonit_Mktplace__Billing_Street__c": "Test Adress",
          "Atonit_Mktplace__Billing_Zip_Postal_Code__c": "12345",
          "Atonit_Mktplace__External_ID__c": "00000103-atonit-vitta",
          "Atonit_Mktplace__Notes__c": null,
          "Atonit_Mktplace__Order_Date__c": "2021-04-13T19:26:35.000+0000",
          "Atonit_Mktplace__Status__c": "Created",
          "Atonit_Mktplace__Custom_Status__c": "Order Completed",
          "Atonit_Mktplace__Total_Price__c": 11.48,
          "Atonit_Mktplace__Total_Shipping_Rate__c": 1.99,
          "Atonit_Mktplace__Custom_Order_Note1__c": "teste 1",
          "Atonit_Mktplace__Custom_Order_Note2__c": "teste 2",
          "Atonit_Mktplace__Custom_Order_Note3__c": "teste 3"
        },
        {
          "Atonit_Mktplace__Line_Items__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0B5Y00000gO1q5UAC",
                "Name": "LI-0000",
                "CreatedDate": "2021-04-13T19:20:40.000+0000",
                "LastModifiedDate": "2021-04-13T19:21:40.000+0000",
                "Atonit_Mktplace__Discount__c": 1.05,
                "Atonit_Mktplace__External_ID__c": "00000101-atonit-vitta-00000101-00000502-atonit-vitta-0",
                "Atonit_Mktplace__Notes__c": null,
                "Atonit_Mktplace__Product_Name__c": "Mini Bombom com Banana 60g - Flormel",
                "Atonit_Mktplace__Product_Variant_Marketplace_Id__c": "at_mini-bombom",
                "Atonit_Mktplace__Product_Variant__c": "a0L5Y00000o8qTQUAY",
                "Atonit_Mktplace__Quantity__c": 1,
                "Atonit_Mktplace__Seller_Shipment__c": "a0R5Y00000Sx7oZUAR",
                "Atonit_Mktplace__Total_Price__c": 9.49,
                "Atonit_Mktplace__Unit_Price__c": 10.54
              }
            ]
          },
          "Atonit_Mktplace__Seller_Shipments__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0R5Y00000Sx7oZUAR",
                "Name": "00000101-00000502-atonit-vitta",
                "CreatedDate": "2021-04-13T19:20:40.000+0000",
                "LastModifiedDate": "2021-04-13T19:21:40.000+0000",
                "Atonit_Mktplace__External_ID__c": "00000101-00000502-atonit-vitta",
                "Atonit_Mktplace__Shipping_City__c": "Test City",
                "Atonit_Mktplace__Shipping_Country__c": "US",
                "Atonit_Mktplace__Shipping_Method_Marketplace_Id__c": "004",
                "Atonit_Mktplace__Shipping_Method__c": "Super Saver",
                "Atonit_Mktplace__Shipping_Rate__c": 1.99,
                "Atonit_Mktplace__Shipping_State_Province__c": "IL",
                "Atonit_Mktplace__Shipping_Street__c": "Test Adress",
                "Atonit_Mktplace__Shipping_Type__c": "Seller",
                "Atonit_Mktplace__Shipping_Zip_Postal_Code__c": "12345",
                "Atonit_Mktplace__Custom_Shipment_Note1__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note2__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note3__c": null
              }
            ]
          },
          "Atonit_Mktplace__Billed_Tickets__r": {
            "totalSize": 2,
            "done": true,
            "records": [
              {
                "Id": "a0b5Y00000RBaRKQA1",
                "Name": "101 Atonit Vitta 1",
                "CreatedDate": "2021-05-28T12:50:54.000+0000",
                "LastModifiedDate": "2021-05-28T12:50:54.000+0000",
                "Atonit_Mktplace__Condition__c": "2",
                "Atonit_Mktplace__DocumentURL__c": "http://www.example.com",
                "Atonit_Mktplace__Document_Number__c": "43222",
                "Atonit_Mktplace__Duplicate__c": "1/2",
                "Atonit_Mktplace__Expiration_Date__c": "2021-08-26",
                "Atonit_Mktplace__Number__c": "123555",
                "Atonit_Mktplace__Order_Number__c": "00000101",
                "Atonit_Mktplace__Seller_Name__c": "Atonit Vitta",
                "Atonit_Mktplace__Serial_Number__c": "3234324234234",
                "Atonit_Mktplace__Status__c": "20-Open",
                "Atonit_Mktplace__Value__c": 34.4,
                "Atonit_Mktplace__External_Id__c": null
              },
              {
                "Id": "a0b5Y00000RBZe3QAH",
                "Name": "101 Atonit Vitta 2",
                "CreatedDate": "2021-05-24T19:33:11.000+0000",
                "LastModifiedDate": "2021-05-28T13:32:17.000+0000",
                "Atonit_Mktplace__Condition__c": "15",
                "Atonit_Mktplace__DocumentURL__c": "http://www.example.com",
                "Atonit_Mktplace__Document_Number__c": "43222",
                "Atonit_Mktplace__Duplicate__c": "1/15",
                "Atonit_Mktplace__Expiration_Date__c": "2021-05-26",
                "Atonit_Mktplace__Number__c": "123555",
                "Atonit_Mktplace__Order_Number__c": "00000101",
                "Atonit_Mktplace__Seller_Name__c": "Atonit Vitta",
                "Atonit_Mktplace__Serial_Number__c": "3234324234234",
                "Atonit_Mktplace__Status__c": "30-Paid",
                "Atonit_Mktplace__Value__c": 34.4,
                "Atonit_Mktplace__External_Id__c": null
              }
            ]
          },
          "Id": "a0Q5Y00000UcHjHUAV",
          "Name": "00000101-atonit-vitta",
          "CreatedDate": "2021-04-13T19:20:40.000+0000",
          "LastModifiedDate": "2021-04-13T19:21:40.000+0000",
          "Atonit_Mktplace__Billing_City__c": "Test City",
          "Atonit_Mktplace__Billing_Country__c": "US",
          "Atonit_Mktplace__Billing_State_Province__c": "IL",
          "Atonit_Mktplace__Billing_Street__c": "Test Adress",
          "Atonit_Mktplace__Billing_Zip_Postal_Code__c": "12345",
          "Atonit_Mktplace__External_ID__c": "00000101-atonit-vitta",
          "Atonit_Mktplace__Notes__c": null,
          "Atonit_Mktplace__Order_Date__c": "2021-04-13T19:20:03.000+0000",
          "Atonit_Mktplace__Status__c": "Created",
          "Atonit_Mktplace__Custom_Status__c": "Order Completed",
          "Atonit_Mktplace__Total_Price__c": 11.48,
          "Atonit_Mktplace__Total_Shipping_Rate__c": 1.99,
          "Atonit_Mktplace__Custom_Order_Note1__c": "teste order note 1",
          "Atonit_Mktplace__Custom_Order_Note2__c": "teste order note 2",
          "Atonit_Mktplace__Custom_Order_Note3__c": "teste order note 3"
        }
      ]
    }
    ```
    
    _Example: listAllOrdersByCreateDate_
    
    ```
    {
      "totalSize": 1,
      "done": true,
      "records": [
        {
          "Atonit_Mktplace__Campaign__r": {
            "Id": "a0f5Y00000GCTwhQAH",
            "Atonit_Mktplace__Marketplace_Id__c": "b14d96de-1669-4775-a757-629d1b74a015",
            "Name": "Campanha de Pré Venda Bombom"
          },
          "Atonit_Mktplace__Line_Items__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0B5Y00000gO1qAUAS",
                "Name": "LI-0002",
                "CreatedDate": "2021-04-13T19:27:23.000+0000",
                "LastModifiedDate": "2021-04-13T19:27:23.000+0000",
                "Atonit_Mktplace__Discount__c": 1.05,
                "Atonit_Mktplace__External_ID__c": "00000103-atonit-vitta-00000103-00000506-atonit-vitta-0",
                "Atonit_Mktplace__Notes__c": null,
                "Atonit_Mktplace__Product_Name__c": "Mini Bombom com Banana 60g - Flormel",
                "Atonit_Mktplace__Product_Variant_Marketplace_Id__c": "at_mini-bombom",
                "Atonit_Mktplace__Product_Variant__c": "a0L5Y00000o8qTQUAY",
                "Atonit_Mktplace__Quantity__c": 1,
                "Atonit_Mktplace__Seller_Shipment__c": "a0R5Y00000Sx7oeUAB",
                "Atonit_Mktplace__Total_Price__c": 9.49,
                "Atonit_Mktplace__Unit_Price__c": 10.54
              }
            ]
          },
          "Atonit_Mktplace__Seller_Shipments__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0R5Y00000Sx7oeUAB",
                "Name": "00000103-00000506-atonit-vitta",
                "CreatedDate": "2021-04-13T19:27:22.000+0000",
                "LastModifiedDate": "2021-04-13T19:27:22.000+0000",
                "Atonit_Mktplace__External_ID__c": "00000103-00000506-atonit-vitta",
                "Atonit_Mktplace__Shipping_City__c": "Test City",
                "Atonit_Mktplace__Shipping_Country__c": "US",
                "Atonit_Mktplace__Shipping_Method_Marketplace_Id__c": "004",
                "Atonit_Mktplace__Shipping_Method__c": "Super Saver",
                "Atonit_Mktplace__Shipping_Rate__c": 1.99,
                "Atonit_Mktplace__Shipping_State_Province__c": "IL",
                "Atonit_Mktplace__Shipping_Street__c": "Test Adress",
                "Atonit_Mktplace__Shipping_Type__c": "Seller",
                "Atonit_Mktplace__Shipping_Zip_Postal_Code__c": "12345",
                "Atonit_Mktplace__Custom_Shipment_Note1__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note2__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note3__c": null
              }
            ]
          },
          "Atonit_Mktplace__Billed_Tickets__r": null,
          "Id": "a0Q5Y00000UcHjMUAV",
          "Name": "00000103-atonit-vitta",
          "CreatedDate": "2021-04-13T19:27:22.000+0000",
          "LastModifiedDate": "2021-04-13T19:27:22.000+0000",
          "Atonit_Mktplace__Billing_City__c": "Test City",
          "Atonit_Mktplace__Billing_Country__c": "US",
          "Atonit_Mktplace__Billing_State_Province__c": "IL",
          "Atonit_Mktplace__Billing_Street__c": "Test Adress",
          "Atonit_Mktplace__Billing_Zip_Postal_Code__c": "12345",
          "Atonit_Mktplace__External_ID__c": "00000103-atonit-vitta",
          "Atonit_Mktplace__Notes__c": null,
          "Atonit_Mktplace__Order_Date__c": "2021-04-13T19:26:35.000+0000",
          "Atonit_Mktplace__Status__c": "Created",
          "Atonit_Mktplace__Custom_Status__c": "Order Completed",
          "Atonit_Mktplace__Total_Price__c": 11.48,
          "Atonit_Mktplace__Total_Shipping_Rate__c": 1.99,
          "Atonit_Mktplace__Custom_Order_Note1__c": "teste 1",
          "Atonit_Mktplace__Custom_Order_Note2__c": "teste 2",
          "Atonit_Mktplace__Custom_Order_Note3__c": "teste 3"
        }
      ]
    }
    ```
    
    _Example: listAllOrdersByUpdateDate_
    
    ```
    {
      "totalSize": 1,
      "done": true,
      "records": [
        {
          "Atonit_Mktplace__Campaign__r": {
            "Id": "a0f5Y00000GCTwhQAH",
            "Atonit_Mktplace__Marketplace_Id__c": "b14d96de-1669-4775-a757-629d1b74a015",
            "Name": "Campanha de Pré Venda Bombom"
          },
          "Atonit_Mktplace__Line_Items__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0B5Y00000gO1qAUAS",
                "Name": "LI-0002",
                "CreatedDate": "2021-04-13T19:27:23.000+0000",
                "LastModifiedDate": "2021-04-13T19:27:23.000+0000",
                "Atonit_Mktplace__Discount__c": 1.05,
                "Atonit_Mktplace__External_ID__c": "00000103-atonit-vitta-00000103-00000506-atonit-vitta-0",
                "Atonit_Mktplace__Notes__c": null,
                "Atonit_Mktplace__Product_Name__c": "Mini Bombom com Banana 60g - Flormel",
                "Atonit_Mktplace__Product_Variant_Marketplace_Id__c": "at_mini-bombom",
                "Atonit_Mktplace__Product_Variant__c": "a0L5Y00000o8qTQUAY",
                "Atonit_Mktplace__Quantity__c": 1,
                "Atonit_Mktplace__Seller_Shipment__c": "a0R5Y00000Sx7oeUAB",
                "Atonit_Mktplace__Total_Price__c": 9.49,
                "Atonit_Mktplace__Unit_Price__c": 10.54
              }
            ]
          },
          "Atonit_Mktplace__Seller_Shipments__r": {
            "totalSize": 1,
            "done": true,
            "records": [
              {
                "Id": "a0R5Y00000Sx7oeUAB",
                "Name": "00000103-00000506-atonit-vitta",
                "CreatedDate": "2021-04-13T19:27:22.000+0000",
                "LastModifiedDate": "2021-04-13T19:27:22.000+0000",
                "Atonit_Mktplace__External_ID__c": "00000103-00000506-atonit-vitta",
                "Atonit_Mktplace__Shipping_City__c": "Test City",
                "Atonit_Mktplace__Shipping_Country__c": "US",
                "Atonit_Mktplace__Shipping_Method_Marketplace_Id__c": "004",
                "Atonit_Mktplace__Shipping_Method__c": "Super Saver",
                "Atonit_Mktplace__Shipping_Rate__c": 1.99,
                "Atonit_Mktplace__Shipping_State_Province__c": "IL",
                "Atonit_Mktplace__Shipping_Street__c": "Test Adress",
                "Atonit_Mktplace__Shipping_Type__c": "Seller",
                "Atonit_Mktplace__Shipping_Zip_Postal_Code__c": "12345",
                "Atonit_Mktplace__Custom_Shipment_Note1__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note2__c": null,
                "Atonit_Mktplace__Custom_Shipment_Note3__c": null
              }
            ]
          },
          "Atonit_Mktplace__Billed_Tickets__r": null,
          "Id": "a0Q5Y00000UcHjMUAV",
          "Name": "00000103-atonit-vitta",
          "CreatedDate": "2021-04-13T19:27:22.000+0000",
          "LastModifiedDate": "2021-04-13T19:27:22.000+0000",
          "SystemModstamp": "2021-04-13T19:27:22.000+0000",
          "Atonit_Mktplace__Billing_City__c": "Test City",
          "Atonit_Mktplace__Billing_Country__c": "US",
          "Atonit_Mktplace__Billing_State_Province__c": "IL",
          "Atonit_Mktplace__Billing_Street__c": "Test Adress",
          "Atonit_Mktplace__Billing_Zip_Postal_Code__c": "12345",
          "Atonit_Mktplace__External_ID__c": "00000103-atonit-vitta",
          "Atonit_Mktplace__Notes__c": null,
          "Atonit_Mktplace__Order_Date__c": "2021-04-13T19:26:35.000+0000",
          "Atonit_Mktplace__Status__c": "Created",
          "Atonit_Mktplace__Custom_Status__c": "Order Completed",
          "Atonit_Mktplace__Total_Price__c": 11.48,
          "Atonit_Mktplace__Total_Shipping_Rate__c": 1.99,
          "Atonit_Mktplace__Custom_Order_Note1__c": "teste 1",
          "Atonit_Mktplace__Custom_Order_Note2__c": "teste 2",
          "Atonit_Mktplace__Custom_Order_Note3__c": "teste 3"
        }
      ]
    }
    ```
    

### PATCH Update Order Status

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Seller_Order__c/Atonit_Mktplace__External_Id__c/00000103-atonit-vitta`

Operation ID: `Update Order Status`. Tags: Order. Security: bearerAuth.

This call allows the status of an existing order to be updated using its External\_Id.

The possible default values are:

*   Order Completed
*   Order under review
*   Unauthorized Order
*   Order confirmed
*   Approved Order
*   Partially billed order
*   Order billed
*   Dispatched Order
*   Order Ready to Withdraw
*   Order resubmitted
*   Order Declined
*   Order Withdrawn
*   Order Delivered
*   Order canceled
*   Order in Transit
*   Delivery Problem

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Custom_Status__c": "Order billed"
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Thu, 29 Apr 2021 12:28:34 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1724/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Seller_Order__c/a0Q5Y00000UcHjMUAV`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0Q5Y00000UcHjMUAV",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### PATCH Update Shipment Info

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Seller_Shipment__c/Atonit_Mktplace__External_Id__c/00000103-00000506-atonit-vitta`

Operation ID: `Update Shipment Info`. Tags: Order. Security: bearerAuth.

This call allows the delivery details of an existing order to be updated using its External\_Id.

The document URL fields may be an external URL with the file or a URL originating from the AWS S3 endpoint, if integrated.

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Tracking_URL__c": "http://www.example.com/tracking",
  "Atonit_Mktplace__Additional_Tracking_Info__c": "info",
  "Atonit_Mktplace__ReceiptPDFUrl__c": "http://www.example.com/receipt.pdf",
  "Atonit_Mktplace__ReceiptXMLUrl__c": "http://www.example.com/receipt.xml",
  "Atonit_Mktplace__CTEUrl__c": "http://www.example.com/cte.pdf",
  "Atonit_Mktplace__PackingListUrl__c": "http://www.example.com/packinglist.pdf"
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 07 Jun 2021 18:57:56 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1947/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Seller_Shipment__c/a0R5Y00000SxEnTUAV`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0R5Y00000SxEnTUAV",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### PATCH Create or Update Billed Ticket

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Billed_Ticket__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-billed-ticket-001-1`

Operation ID: `Create or Update Billed Ticket`. Tags: Order. Security: bearerAuth.

This call allows you both to create and update a payment slip invoiced from an order. If a payment slip already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

The DocumentURL fields may be an external URL with the file or a URL originating from the AWS S3 endpoint, if integrated.

For the Atonit\_Mktplace\_\_Status\_\_field, the possible default values are:

*   10-Expired
*   20-Open
*   30-Paid
*   40-Canceled

Only payment slips with the status 20-Open can be updated. After this status, the update is blocked.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Name": "00000103 1/15",
  "Atonit_Mktplace__Condition__c": "15",
  "Atonit_Mktplace__DocumentURL__c": "http://www.example.com",
  "Atonit_Mktplace__Document_Number__c": "43222",
  "Atonit_Mktplace__Duplicate__c": "1/15",
  "Atonit_Mktplace__Expiration_Date__c": "2021-09-26",
  "Atonit_Mktplace__Number__c": "123555",
  "Atonit_Mktplace__Serial_Number__c": "3234324234234",
  "Atonit_Mktplace__Status__c": "20-Open",
  "Atonit_Mktplace__Value__c": 34.4,
  "Atonit_Mktplace__Seller__r": {
    "Atonit_Mktplace__Slug__c": "{{seller-external-id}}"
  },
  "Atonit_Mktplace__Seller_Order__r": {
    "Atonit_Mktplace__External_ID__c": "00000103-atonit-vitta"
  }
}
```

#### Responses

*   **201** Created
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 28 May 2021 18:41:50 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1785/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Billed_Ticket__c/a0b5Y00000RBaUUQA1`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0b5Y00000RBaUUQA1",
      "success": true,
      "errors": [],
      "created": true
    }
    ```
    

### GET Get Info for Fulfillment

`GET /services/apexrest/Atonit_Mktplace/v1/cancelledItems`

Operation ID: `Get Info for Fulfillment`. Tags: Order. Security: bearerAuth.

This call allows all data to be listed to complete the fulfillment of an order using its external ID.

#### Parameters

*   `orderId` (query, string)
    
    _Example_
    
    ```
    00000101-atonit-vitta
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 04 Jun 2021 18:45:48 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    [
      {
        "UpdatedPrice": 9.49,
        "UnitPrice": 10.54,
        "TotalPrice": 9.49,
        "SKU": "at_mini-bombom",
        "RowSelected": null,
        "RequestedQuantity": 1,
        "Order": "a0Q5Y00000UcHjHUAV",
        "Name": "Mini Bombom com Banana 60g - Flormel",
        "Index": 0,
        "Id": "a0B5Y00000gO1q5UAC",
        "AvailableQuantity": 1
      }
    ]
    ```
    

### POST Create or Update Order and relateds

`POST /services/apexrest/Atonit_Mktplace/v1/orders/`

Operation ID: `Create or Update Order and relateds`. Tags: Order. Security: bearerAuth.

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 04 Jun 2021 19:01:27 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Content-Length` (integer)  
        Example: `20`.
    
    Media type: `application/json`. Schema: `object`.
    

### POST Cancel or Fulfill an Order Copy

`POST /services/apexrest/Atonit_Mktplace/v1/cancelledItems//`

Operation ID: `Cancel or Fulfill an Order Copy`. Tags: Order. Security: bearerAuth.

#### Parameters

*   `orderId` (query, string)
    
    _Example_
    
    ```
    00000101-atonit-vitta
    ```
    
*   `mode` (query, string)
    
    _Example_
    
    ```
    full
    ```
    

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
[
  {
    "Id": "a0B5Y00000gO1q5UAC",
    "AvailableQuantity": 1
  }
]
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 04 Jun 2021 19:14:09 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Content-Length` (integer)  
        Example: `20`.
    
    Media type: `application/json`. Schema: `object`.
    

### POST Partially Fulfill an Order

`POST /services/apexrest/Atonit_Mktplace/v1/cancelledItems///`

Operation ID: `Partially Fulfill an Order`. Tags: Order. Security: bearerAuth.

#### Parameters

*   `orderId` (query, string)
    
    _Example_
    
    ```
    00000101-atonit-vitta
    ```
    
*   `mode` (query, string)
    
    _Example_
    
    ```
    partial
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 04 Jun 2021 19:07:36 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Content-Length` (integer)  
        Example: `20`.
    
    Media type: `application/json`. Schema: `object`.
    

### POST Cancel an Order

`POST /services/apexrest/Atonit_Mktplace/v1/cancelledItems////`

Operation ID: `Cancel an Order`. Tags: Order. Security: bearerAuth.

#### Parameters

*   `orderId` (query, string)
    
    _Example_
    
    ```
    00000101-atonit-vitta
    ```
    
*   `mode` (query, string)
    
    _Example_
    
    ```
    cancel
    ```
    

#### Request body

Media type: `application/json`. Schema: `object`.

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 04 Jun 2021 19:07:36 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Content-Length` (string)  
        Example: `20`.
    
    Media type: `application/json`. Schema: `object`.

<!-- document id=d429dccaf0de140f7c17bd5628f7117e4e25e4a6b7dfd88152cbb3716b6a2196 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-orders-history.md -->

# Orders (History)

### Overview

The Orders page displays a list of the buyer’s recent orders, including the order number, ordered date, order status, and order total for each entry. This page provides buyers with a centralized view of their order history and order status information.

This flow demonstrates how a headless storefront can render order history experiences using B2B Commerce Order Summary APIs.

![Orders History Buyer Journey](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-orders-history-buyer-journey-28-1.png '{"class": "image-lg", "title": "Orders History Buyer Journey"}')

### B2B Commerce APIs Used in the Flow

| Operation   | HTTP Method | Endpoint                                                                                                                                                                                   |
| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| List orders | GET         | [`/commerce/webstores/{webstoreId}/order-summaries`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries.htm) |

### Buyer Journey

#### Render Order History

1. Call the following endpoint to retrieve the buyer’s order history:

   GET [`/commerce/webstores/{webstoreId}/order-summaries?ownerScope=My&pageSize=50&fields=OrderNumber,OrderedDate,Status,TotalAmount,GrandTotalAmount,CurrencyIsoCode`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries.htm)

2. Pass the fields query parameter explicitly. Some org configurations omit Grand Total Amount from the default response projection. Specifying the required fields explicitly ensures that the storefront receives all values needed for the order history page.

3. Use the response to retrieve the `orderSummaries` collection. The response returns order summaries sorted from newest to oldest.

4. Handle `403` and `404` responses as empty order-history states. Buyers without existing orders can receive these responses instead of an empty collection.

5. Read order summary fields defensively when rendering the response. Depending on org configuration, field values can appear in either of the following shapes:

   Flat field structure:

   ```json
   { "OrderNumber": "00001001" }
   ```

   Wrapped field structure:

   ```json
   { "fields": { "OrderNumber": { "text": "00001001" } } }
   ```

6. Check for both response shapes when rendering table cells to avoid displaying blank values for order details.

7. Use the response data to render:
   - Order number
   - Ordered date
   - Order status
   - Total amount
   - Grand total amount
   - Currency information

### Extend the Flow

- To add date-based filtering, pass the public `earliestDate` and `latestDate` query parameters in the [Order Summaries API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries.htm) request.
- To add server-side pagination support, read the `pagination.nextPageToken` value returned in the API response and use it to retrieve the next set of order summaries.

## See Also

- [_B2B Commerce Developer Guide_: B2B Commerce Order Summary APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-order-summaries-apis.html)

<!-- document id=72ec0482e9df0978460e611ed74e881c1d57baadfa7c31e488fc68a46a451080 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/orders-and-inventory.md -->

# Orders & Inventory

Handle order data flow and real time inventory updates.

## In this section

- [Order Management](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/order-management.html)
- [Checkout and Fulfillment](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/checkout-fulfillment.html)
- [Inventory](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/inventory-fulfillment.html)

<!-- document id=b4e0c718bd2166432ff8381265f58da4ea2abfd9466ce5a34f2abc839b0aaa90 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-otp-email-verification.md -->

# OTP Email Verification with SLAS

Starting with B2C Commerce 26.6, use the Shopper Login and API Access Service (SLAS) to verify registered shopper identities by using a one-time password (OTP). This feature enables email verification during shopper registration, email updates, and other identity confirmation flows. Integrate OTP email verification with SLAS from any headless application. Currently, only registered user flows support SLAS OTP email verification.

OTPs provide a time-limited, single-use code delivered to a shopper's email address. When `/otp/request` is called, SLAS fetches the shopper's profile from B2C Commerce, checks the `emailVerified` status, and, if verification is valid, generates an OTP and delivers it by email. After the shopper submits the code, a call to `/otp/verify` causes SLAS to validate it and mark the shopper's email as verified in B2C Commerce.

**note:** SLAS doesn't support SMS delivery of OTP. To have the OTP sent by SMS you will need to use `mode=callback` and manage the SMS delivery from your callback. See [Passwordless Login with One-Time Passwords Using Callback URI](https://sfdocs-commercecloud-pr-2334.herokuapp.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html). OTP Email verification only supports `mode=email`.

For SLAS to have the required shopper information to send to the callback, the shopper must have logged in at least one time before attempting OTP email verification.

## Prerequisites

Before you integrate OTP-based email verification, make sure that you have:

- **Email verification site preference enabled**: The B2C Commerce **Enable Email Verification** preference must be turned on from Business Manager. When disabled, `emailVerified` is null on all profiles.

  To enable email verification in Business Manager:

  1. Click **App Launcher**, and then select **Merchant Tools** | **_site_** | **Storefront Login Preferences**.
  2. Turn on **Enable Email Verification**.
  3. Click **Apply**.

  ![Email verification preference toggle in Business Manager](https://developer.salesforce.com/docs/media/commerce-api/slas-email-verification.png)

- **A SLAS private client configured for passwordless login**: OTP email verification requires a SLAS private client. If you don't have one, create it before proceeding. See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#1-configure-a-slas-private-client). Configure the client with `sfcc.pwdless_login` in its allowed scopes (configured in SLAS Admin under **Clients** → **Scopes**). Requests from clients that lack this scope are rejected with a 403.

- **A client channel**: The `channel_id` must be registered to the client. The `channel_id` in every OTP request must match a channel registered to the authenticating client. Configure in the SLAS Admin UI at `https://{short-code}.api.commercecloud.salesforce.com/shopper/auth-admin/v1/ui/`. Go to **Clients** and click **Edit** next to the channel you want to configure.

- **An OTP email template**: Configure an OTP email template for the client channel. The template receives the shopper's first name and the OTP code. See [Configure Email Templates](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#3-configure-email-templates).

- **A valid shopper access token**: Before you call the OTP email verification endpoints, obtain a SLAS shopper JSON Web Token (JWT) by using the standard authorization code or guest token flow. All OTP endpoints require a SLAS shopper bearer JWT in the authorization header. For more information, see [Private SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html).

## SLAS OTP Email Verification End-to-End Flow

This diagram shows the end-to-end sequence for email verification after shopper registration.

![Complete end-to-end OTP email verification flow from registration through validation](https://developer.salesforce.com/docs/media/commerce-api/slas-otp-email-verification-flow.png '{"class": "image-full"}')

## Request and Verification Flows

The SLAS OTP email verification process has two primary flows: **OTP request** and **OTP verification**.

### OTP Request Flow

The OTP request flow initiates delivery of a one-time password to the shopper. SLAS handles the `emailVerified` check internally — the caller doesn't need to inspect this field before calling the endpoint.

![OTP request flow showing SLAS generating and sending the one-time password](https://developer.salesforce.com/docs/media/commerce-api/slas-otp-request-flow.png '{"class": "image-full"}')

1. Call POST /organizations/{organizationId}/oauth2/otp/request, passing the shopper's `user_id`, `channel_id`, `client_id`, `email`, and a valid shopper bearer token in the authorization header.
2. SLAS authenticates the OAuth client and validates the bearer JWT, confirming that `client_id`, `channel_id`, and `user_id` all match the token's subject claims. A mismatch results in HTTP 400\.
3. SLAS verifies the client has the sfcc.pwdless_login permission scope.
4. SLAS applies a bot-backoff and per-user rate limiting to prevent OTP flooding.
5. SLAS fetches the shopper's customer profile from B2C Commerce and reads the `emailVerified` field:
   - **`null`** — The email verification site preference is disabled. SLAS treats the email as verified, proceeds to generate and send the OTP, and returns 202\.
   - **`true`** — The email is already verified. SLAS proceeds to generate and send the OTP and returns 202\.
   - **`false`** — The email is explicitly unverified. SLAS doesn't send the OTP and returns 400\.
6. SLAS generates an OTP token and computes a hash verifier. The entry expires after 10 minutes.
7. SLAS sends the OTP to the shopper's email address by using an email service with the configured email template.

**note:** SLAS automatically extracts the `usid` (unique shopper ID) from the bearer token's subject claims. You don't need to include it in the request body.

### OTP Verification Flow

The OTP verification flow confirms that the shopper received and submitted the correct code.

![OTP verification flow showing validation and profile update in B2C Commerce](https://developer.salesforce.com/docs/media/commerce-api/slas-otp-verify-flow.png '{"class": "image-full"}')

1. Call POST /organizations/{organizationId}/oauth2/otp/verify, passing the `pwd_action_token` (the code the shopper received), `client_id`, `channel_id`, `user_id`, `usid`, and the shopper bearer token.

2. SLAS authenticates the OAuth client and validates the bearer JWT, confirming that the `client_id`, `channel_id`, and `user_id` match the token claims.
3. SLAS applies a bot-backoff rate limiting to guard against brute-force guessing.
4. SLAS verifies the client has the `sfcc.pwdless_login` permission scope.
5. SLAS looks up the OTP entry by reconstructing the key from the supplied fields. The entry is atomically consumed (deleted) on first successful lookup — the token cannot be reused.
6. SLAS validates the hash verifier. A mismatch results in HTTP 400\.
7. SLAS makes an internal call to the B2C Commerce `update-profile` endpoint to set `emailVerified` to `true`. This call is best-effort: a failure does not block the 204 response from being returned.
8. SLAS responds with **HTTP 204 No Content**.
   - If the hash verifier fails or any parameters are invalid, SLAS responds with **HTTP 400 Bad Request**.
   - If the authorization header, shopper JWT fails validation, or token validation fails**,** SLAS responds with **HTTP 401 Unauthorized.**
   - If the scope validation fails, SLAS responds with **HTTP 403 Forbidden.**

## Sample API Calls

### Obtain a Shopper Access Token

Before calling the OTP endpoints, obtain a SLAS shopper bearer JWT. The shopper must authenticate before making any OTP requests.

Use the `access_token` from the shopper authentication response as the bearer token in the OTP calls below.

### Request an OTP

| Bash                                                                                                                                                                                                                                                                                                                                                  |
| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| curl \-X POST \\ "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/otp/request" \\ -H "Authorization: Bearer {shopper_access_token}" \\ -H "Content-Type: application/x-www-form-urlencoded" \\ -d "client_id={client_id}\&channel_id={channel_id}\&user_id=shopper.example.com\&mode=email |

**Response: 202 Accepted**  
No response body is returned. If emailVerified is true or null on the shopper profile, the OTP is sent to the shopper's email. If emailVerified is false, no email is sent.

### Verify an OTP

| Bash                                                                                                                                                                                                                                                                                                                                                                |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| curl \-X POST \\ "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/otp/verify" \\ -H "Authorization: Bearer {shopper_access_token}" \\ -H "Content-Type: application/x-www-form-urlencoded" \\ -d "pwd_action_token=85353215\&client_id={client_id}\&channel_id={channel_id}\&user_id=shopper.example.com |

**Response: 204 No Content**  
No response body is returned. The OTP is valid and the shopper's emailVerified status is updated to true in B2C Commerce.

## Request Field Reference

### POST /otp/request

| Field        | Required | Constraints                                 | Notes                                                                                                                                                       |
| :----------- | :------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id`  | Yes      | Exactly 36 chars, base64url characters only | Must match a client registered for the tenant                                                                                                               |
| `channel_id` | Yes      | Max 100 chars                               | Must be a channel registered to the client                                                                                                                  |
| `user_id`    | Yes      | Max 128 chars                               | The shopper's login ID or email address. If user_id is an email then user_id will be used to send the email, if not the email query parameter will be used. |
| `mode`       | Yes      | —                                           | Must be set to email                                                                                                                                        |
| `email`      | No       | —                                           | The email address to deliver the OTP to. This email address will be used if the user_id isn't a valid email address.                                        |
| `locale`     | No       | —                                           | Defaults to `en-us`; controls the email template locale                                                                                                     |

### POST /otp/verify

| Field              | Required | Constraints                                 | Notes                                              |
| :----------------- | :------- | :------------------------------------------ | :------------------------------------------------- |
| `pwd_action_token` | Yes      | Passwordless token format                   | The OTP code received by the shopper               |
| `client_id`        | Yes      | Exactly 36 chars, base64url characters only | Must match the `client_id` used in `/otp/request`  |
| `channel_id`       | Yes      | Max 100 chars, base64url characters only    | Must match the `channel_id` used in `/otp/request` |
| `user_id`          | Yes      | Max 128 chars                               | Must match the `user_id` used in `/otp/request`    |

## Security

### Authorization

Both endpoints require a SLAS shopper bearer JWT in the authorization header. All values in the request body must exactly match the corresponding claims in the token. Any mismatch results in HTTP 400\. SLAS also checks that the shopper session hasn't been revoked before proceeding.

### Hash Verifier

After a successful OTP lookup, SLAS validates a hash verifier to confirm the token wasn't tampered with. The verifier is computed during /otp/request and re-validated during /otp/verify using a key. A mismatch results in HTTP 400\.

### Bot Backoff

Both endpoints enforce per-tenant bot-backoff rate limiting to prevent automated flooding and brute-force OTP guessing. When the threshold is exceeded, SLAS returns HTTP 429\.

### OTP Rate Limiting

SLAS checks per-user OTP request rate limits before generating a new code. This prevents resource exhaustion from repeated delivery attempts for the same user.

### OTP Token Expiration

OTP tokens are stored in Redis with a configurable time to live (TTL). The default TTL is 600 seconds (10 minutes). Tokens not consumed within this window expire automatically. Attempting to verify an expired token results in HTTP 403\. Requesting a new OTP token invalidates any pending, unverified tokens for that user.

## Error Responses

| HTTP Status           | Scenario                                                                                                                 |
| :-------------------- | :----------------------------------------------------------------------------------------------------------------------- |
| 400 Bad Request       | Invalid or missing request parameters; `emailVerified` is false; JWT claims mismatch between request body and token      |
| 401 Unauthorized      | Client authentication failed; invalid JWT (expired); OTP validation failed (expired, already used); failed hash verifier |
| 403 Forbidden         | Client doesn't have the sfcc.pwdless_login permission scope                                                              |
| 429 Too Many Requests | Bot-backoff threshold exceeded for the tenant                                                                            |

**warning:** To prevent information leakage, SLAS returns a generic 400 for all OTP verification failures, regardless of the specific reason (invalid/missing parameters, hash mismatch, and emailValidate is false). SLAS returns a generic 401 for client authenticate failure, expired token, failed hash verifier, and expired Shopper JWT. Don't attempt to differentiate failure reasons based on the error response message.

<!-- document id=8dc21d971366da3b413c2e81edb0f17e18298d48b3d692b4ff68ab86bac7e01e url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-storefront-apis-parent.md -->

# Overview of B2B Commerce APIs

The B2B Commerce APIs enable users to effortlessly handle their commerce data. These APIs offer extensive support for various commerce tasks such as address management, cart management, checkout processing, order management, product handling, pricing, promotions, tax management, wishlist management, and search settings. Leveraging these APIs, users can streamline their commerce operations to deliver seamless experiences to their customers.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Here’s a list of the B2B Commerce resources:

- [Salesforce Commerce Address Management API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-address-mgmt-apis.md)
- [Salesforce Commerce Cart API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-cart-apis.md)
- [Salesforce Commerce Checkout API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-checkout-apis.md)
- [Salesforce Commerce Import API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-import-apis.md)
- [Salesforce Commerce My Profile API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-checkout-apis.md)
- [Salesforce Commerce Order Summary API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-order-summaries-apis.md)
- [Salesforce Commerce Pricing and Promotions API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-pricing-promotions-apis.md)
- [Salesforce Commerce Search Settings API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-search-settings-apis.md)
- [Salesforce Commerce Tax API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-tax-apis.md)
- [Salesforce Commerce Wishlists API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/d2c-commerce/b2b-d2c-comm-wishlists-apis.md)

<!-- document id=9aa5b0652ce3a55aa52da51ce67aaf8c7fe44132200eeb94221a506f2807538c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/understand-b2c.md -->

# Overview of B2C Commerce

Ready to delve into the inner workings of B2C Commerce? This section provides a comprehensive breakdown of the architecture, explaining how the pieces work together to help you build a robust and performant site. This section contains these guides.

- [B2C Commerce Architecture](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/get-started.md)
- [Get Started with Business Manager](https://trailhead.salesforce.com/content/learn/modules/cc-digital-for-developers/cc-business-manager?trail_id=develop-for-commerce-cloud), which is the command center for your B2C Commerce merchandising, administration, and site development capabilities.
- Storefront Reference Architecture (SFRA) only: Understand [Development Components](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-dev-components.md), which are the building blocks for your B2C Commerce site.
- [Code Deployment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-code-deployment.md): Learn how to manage code versions during site development.
- [Localization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/localization/b2c-localization.md)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=97136ea005b4206a7b1be164f6cb2bb71082400a80968d20fa871f958427627a url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.alert.md -->

# Package dw.alert

## Classes

| Class                        | Description                                                                                                         |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [Alert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alert.md)   | This class represents a single system alert to be shown to a Business Manager user.                                 |
| [Alerts](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.alert.Alerts.md) | <p>Allow creation, removal, re-validation and retrieval of alerts that might get visible to Business Manager users. |

<!-- document id=dcce6bdee62cb428dcca98ae1df023288cf8e175607de403d234d8befc992979 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.campaign.md -->

# Package dw.campaign

## Classes

| Class                                                                   | Description                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ABTest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTest.md)                                         | Object representing an AB-test in Commerce Cloud Digital.                                                                                                                                                                                                                                                                                          |
| [ABTestMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestMgr.md)                                   | Manager class used to access AB-test information in the storefront.                                                                                                                                                                                                                                                                                |
| [ABTestSegment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ABTestSegment.md)                           | Object representing an AB-test segment in the Commerce Cloud Digital.                                                                                                                                                                                                                                                                              |
| [AmountDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.AmountDiscount.md)                         | Represents an _amount-off_ discount in the discount plan, for example "$10 off all orders $100 or more".                                                                                                                                                                                                                                           |
| [ApproachingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.ApproachingDiscount.md)               | Transient class representing a discount that a [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md) "almost" qualifies for based on the amount of merchandise in it.                                                                                                                                                                                           |
| [BonusChoiceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md)               | Represents a _choice of bonus products_ discount in the discount plan, for example "Choose 3 DVDs from a list of 20 options with your purchase of any DVD player."                                                                                                                                                                                 |
| [BonusDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusDiscount.md)                           | Represents a _bonus_ discount in the discount plan, for example "Get a free DVD with your purchase of any DVD player."                                                                                                                                                                                                                             |
| [Campaign](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Campaign.md)                                     | A Campaign is a set of experiences (or site configurations) which may be deployed as a single unit for a given time frame.                                                                                                                                                                                                                         |
| [CampaignMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignMgr.md)                               | CampaignMgr provides static methods for managing campaign-specific operations such as accessing promotions or updating promotion line items.                                                                                                                                                                                                       |
| [CampaignStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CampaignStatusCodes.md)               | Deprecated.                                                                                                                                                                                                                                                                                                                                        |
| [Coupon](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Coupon.md)                                         | Represents a coupon in Commerce Cloud Digital.                                                                                                                                                                                                                                                                                                     |
| [CouponMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponMgr.md)                                   | Manager to access coupons.                                                                                                                                                                                                                                                                                                                         |
| [CouponRedemption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponRedemption.md)                     | Represents a redeemed coupon.                                                                                                                                                                                                                                                                                                                      |
| [CouponStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.CouponStatusCodes.md)                   | Helper class containing status codes for why a coupon code cannot be added to cart or why a coupon code already in cart is not longer valid for redemption.                                                                                                                                                                                        |
| [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)                                     | Superclass of all specific discount classes.                                                                                                                                                                                                                                                                                                       |
| [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md)                             | DiscountPlan represents a set of [Discount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Discount.md)s.                                                                                                                                                                                                                                                                             |
| [FixedPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceDiscount.md)                 | Represents a _fix price_ discount in the discount plan, for example "Shipping only 0.99 all orders \$25 or more."                                                                                                                                                                                                                                  |
| [FixedPriceShippingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FixedPriceShippingDiscount.md) | Represents a _fixed price shipping_ discount in the discount plan, for example "Shipping only 0.99 for iPods."                                                                                                                                                                                                                                     |
| [FreeDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FreeDiscount.md)                             | Represents a _free_ discount in the discount plan, for example "Free shipping on all orders \$25 or more."                                                                                                                                                                                                                                         |
| [FreeShippingDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.FreeShippingDiscount.md)             | Represents a _free shipping_ discount in the discount plan, for example "Free shipping on all iPods."                                                                                                                                                                                                                                              |
| [PercentageDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageDiscount.md)                 | Represents a _percentage-off_ discount in the discount plan, for example "10% off all T-Shirts".                                                                                                                                                                                                                                                   |
| [PercentageOptionDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PercentageOptionDiscount.md)     | Represents a _percentage-off options_ discount in the discount plan, for example "50% off monogramming on shirts".                                                                                                                                                                                                                                 |
| [PriceBookPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PriceBookPriceDiscount.md)         | Discount representing that a product's price has been calculated from a separate sales price book other than the standard price book assigned to the site.                                                                                                                                                                                         |
| [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md)                                   | This class represents a promotion in Commerce Cloud Digital.                                                                                                                                                                                                                                                                                       |
| [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md)                             | [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) is used to access campaigns and promotion definitions, display active or upcoming promotions in a storefront, and to calculate and apply promotional discounts to line item containers.                                                                                                                |
| [PromotionPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionPlan.md)                           | PromotionPlan represents a set of [Promotion](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.Promotion.md) instances and is used to display active or upcoming promotions on storefront pages, or to pass it to the [PromotionMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.PromotionMgr.md) to calculate a [DiscountPlan](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.DiscountPlan.md) and subsequently apply discounts to a line item container. |
| [SlotContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SlotContent.md)                               | Represents content for a slot.                                                                                                                                                                                                                                                                                                                     |
| [SourceCodeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeGroup.md)                       | A source code group defines a collection of source codes.                                                                                                                                                                                                                                                                                          |
| [SourceCodeInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeInfo.md)                         | Class representing a code (i.e.                                                                                                                                                                                                                                                                                                                    |
| [SourceCodeStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.SourceCodeStatusCodes.md)           | Helper class which contains error result codes returned by the SetSourceCode pipelet.                                                                                                                                                                                                                                                              |
| [TotalFixedPriceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.TotalFixedPriceDiscount.md)       | Represents a _total fix price_ discount on a group of products in the discount plan.                                                                                                                                                                                                                                                               |

<!-- document id=b3efc07ff71127503dae770804ac9dcffa3c7a2dd8535bafa63720872e5e20bb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.catalog.md -->

# Package dw.catalog

## Classes

| Class                                                                                | Description                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md)                                                     | Represents a Commerce Cloud Digital Catalog.                                                                                                                                                                                                                                                                                                                           |
| [CatalogMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CatalogMgr.md)                                               | Provides helper methods for getting categories.                                                                                                                                                                                                                                                                                                                        |
| [Category](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Category.md)                                                   | Represents a category in a product catalog.                                                                                                                                                                                                                                                                                                                            |
| [CategoryAssignment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryAssignment.md)                               | Represents a category assignment in Commerce Cloud Digital.                                                                                                                                                                                                                                                                                                            |
| [CategoryLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.CategoryLink.md)                                           | A CategoryLink represents a directed relationship between two catalog categories.                                                                                                                                                                                                                                                                                      |
| [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md)                                                 | Represents a price book.                                                                                                                                                                                                                                                                                                                                               |
| [PriceBookMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBookMgr.md)                                           | Price book manager provides methods to access price books.                                                                                                                                                                                                                                                                                                             |
| [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md)                                                     | Represents a product in Commerce Cloud Digital.                                                                                                                                                                                                                                                                                                                        |
| [ProductActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductActiveData.md)                                 | Represents the active data for a [Product](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Product.md) in Commerce Cloud Digital.                                                                                                                                                                                                                                                                           |
| [ProductAttributeModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAttributeModel.md)                         | Class representing the complete attribute model for products in the system.                                                                                                                                                                                                                                                                                            |
| [ProductAvailabilityLevels](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityLevels.md)                 | Encapsulates the quantity of items available for each availability status.                                                                                                                                                                                                                                                                                             |
| [ProductAvailabilityModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductAvailabilityModel.md)                   | The ProductAvailabilityModel provides methods for retrieving all information on availability of a single product.                                                                                                                                                                                                                                                      |
| [ProductInventoryList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryList.md)                           | The ProductInventoryList provides access to ID, description and defaultInStockFlag of the list.                                                                                                                                                                                                                                                                        |
| [ProductInventoryMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryMgr.md)                             | This manager provides access to inventory-related objects.                                                                                                                                                                                                                                                                                                             |
| [ProductInventoryRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductInventoryRecord.md)                       | The ProductInventoryRecord holds information about a Product's inventory, and availability.                                                                                                                                                                                                                                                                            |
| [ProductLink](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductLink.md)                                             | The class represents a link between two products.                                                                                                                                                                                                                                                                                                                      |
| [ProductMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductMgr.md)                                               | Provides helper methods for getting products based on Product ID or [Catalog](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Catalog.md).                                                                                                                                                                                                                                                                  |
| [ProductOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOption.md)                                         | Represents a product option.                                                                                                                                                                                                                                                                                                                                           |
| [ProductOptionModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionModel.md)                               | This class represents the option model of a specific product and for a specific currency.                                                                                                                                                                                                                                                                              |
| [ProductOptionValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductOptionValue.md)                               | Represents the value of a product option.                                                                                                                                                                                                                                                                                                                              |
| [ProductPriceInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceInfo.md)                                   | Simple class representing a product price point.                                                                                                                                                                                                                                                                                                                       |
| [ProductPriceModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceModel.md)                                 | ProductPriceModel provides methods to access all the [PriceBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.PriceBook.md) information of a product.                                                                                                                                                                                                                                                    |
| [ProductPriceTable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductPriceTable.md)                                 | A ProductPriceTable is a map of quantities to prices representing the potentially tiered prices of a product in Commerce Cloud Digital.                                                                                                                                                                                                                                |
| [ProductSearchHit](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchHit.md)                                   | ProductSearchHit is the result of a executed search query and wraps the actual product found by the search.                                                                                                                                                                                                                                                            |
| [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md)                               | The class is the central interface to a product search result and a product search refinement.                                                                                                                                                                                                                                                                         |
| [ProductSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementDefinition.md) | This class provides an interface to refinement options for the product search.                                                                                                                                                                                                                                                                                         |
| [ProductSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinements.md)                   | This class provides an interface to refinement options for the product search.                                                                                                                                                                                                                                                                                         |
| [ProductSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchRefinementValue.md)           | Represents the value of a product search refinement.                                                                                                                                                                                                                                                                                                                   |
| [ProductVariationAttribute](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttribute.md)                 | Represents a product variation attribute                                                                                                                                                                                                                                                                                                                               |
| [ProductVariationAttributeValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationAttributeValue.md)       | Represents a product variation attribute                                                                                                                                                                                                                                                                                                                               |
| [ProductVariationModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductVariationModel.md)                         | Class representing the complete variation information for a master product in the system.                                                                                                                                                                                                                                                                              |
| [Recommendation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Recommendation.md)                                       | Represents a recommendation in Commerce Cloud Digital.                                                                                                                                                                                                                                                                                                                 |
| [SearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchModel.md)                                             | Common search model base class.                                                                                                                                                                                                                                                                                                                                        |
| [SearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementDefinition.md)               | Common search refinement definition base class.                                                                                                                                                                                                                                                                                                                        |
| [SearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinements.md)                                 | Common search refinements base class.                                                                                                                                                                                                                                                                                                                                  |
| [SearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SearchRefinementValue.md)                         | Represents the value of a product or content search refinement.                                                                                                                                                                                                                                                                                                        |
| [SortingOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingOption.md)                                         | Represents an option for how to sort products in storefront search results.                                                                                                                                                                                                                                                                                            |
| [SortingRule](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.SortingRule.md)                                             | Represents a product sorting rule for use with the [ProductSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md).                                                                                                                                                                                                                                                             |
| [Store](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Store.md)                                                         | Represents a store in Commerce Cloud Digital.                                                                                                                                                                                                                                                                                                                          |
| [StoreGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreGroup.md)                                               | Represents a store group.                                                                                                                                                                                                                                                                                                                                              |
| [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md)                           | <p> This class represents a store inventory filter, which can be used at [ProductSearchModel.setStoreInventoryFilter(StoreInventoryFilter)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setstoreinventoryfilterstoreinventoryfilter) to filter the search result by one or more store inventories.                                                                                |
| [StoreInventoryFilterValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilterValue.md)                 | <p> This class represents a store inventory filter value, which can be used for a [StoreInventoryFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreInventoryFilter.md) to filter the search result by one or more store inventory list IDs via [ProductSearchModel.setStoreInventoryFilter(StoreInventoryFilter)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.md#setstoreinventoryfilterstoreinventoryfilter). |
| [StoreMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.StoreMgr.md)                                                   | Provides helper methods for getting stores based on id and querying for stores based on geolocation.                                                                                                                                                                                                                                                                   |
| [Variant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.Variant.md)                                                     | Represents a variant of a product variation.                                                                                                                                                                                                                                                                                                                           |
| [VariationGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.VariationGroup.md)                                       | Class representing a group of variants within a master product who share a common value for one or more variation attribute values.                                                                                                                                                                                                                                    |

<!-- document id=880c640f043f88310d866c217b37e586dda79a352722e5953244289b617374cc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.commerceapps.md -->

# Package dw.commerceapps

## Classes

| Class                                                                         | Description                                                                                                                                                                        |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ConnectionHealthStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.ConnectionHealthStatusCodes.md) | Status codes and detail keys returned by the [ConnectionHealthCheckHooks.checkConnectionHealth()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.hooks.ConnectionHealthCheckHooks.md#checkconnectionhealth) hook. |

<!-- document id=7ae0a31977bb8adc2d16da5507409a448faebfc9214fb954126aa471d6e856df url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.commerceapps.hooks.md -->

# Package dw.commerceapps.hooks

## Classes

| Class                                                                             | Description                                                                                                |
| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [ConnectionHealthCheckHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.commerceapps.hooks.ConnectionHealthCheckHooks.md) | This interface represents the optional connection health check extension point for Commerce App providers. |

<!-- document id=f96f12dc8d5faa26ad23736597c249cefeb1a3bf54c5a6e2c2fc8afa9e2728f4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.content.md -->

# Package dw.content

## Classes

| Class                                                                                | Description                                                                                                                                                 |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md)                                                     | Class representing a Content asset in Commerce Cloud Digital.                                                                                               |
| [ContentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentMgr.md)                                               | Provides helper methods for getting content assets, library folders and the content library of the current site.                                            |
| [ContentSearchModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchModel.md)                               | The class is the central interface to a content search result and a content search refinement.                                                              |
| [ContentSearchRefinementDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementDefinition.md) | This class provides an interface to refinement options for content search.                                                                                  |
| [ContentSearchRefinements](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinements.md)                   | This class provides an interface to refinement options for the content asset search.                                                                        |
| [ContentSearchRefinementValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.ContentSearchRefinementValue.md)           | Represents the value of a content search refinement.                                                                                                        |
| [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md)                                                       | Class representing a folder for organizing content assets in Commerce Cloud Digital.                                                                        |
| [Library](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Library.md)                                                     | Class representing a collection of [Content](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Content.md) assets, and a [Folder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.Folder.md) hierarchy organizing these content assets. |
| [MarkupText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MarkupText.md)                                               | The class represents a content snippet with markup.                                                                                                         |
| [MediaFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.content.MediaFile.md)                                                 | This class represents references to media content (such as images) located within Commerce Cloud Digital or on external systems.                            |

<!-- document id=044a426f9e036f5df3a3190144eedd33acf2f4c2333bfcf30182c7aa65ed9eeb url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.crypto.md -->

# Package dw.crypto

## Classes

| Class                                               | Description                                                                                                      |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [CertificateRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateRef.md)       | This class is used as a reference to a certificate or public key.                                                |
| [CertificateUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.CertificateUtils.md)   | Utilities for managing certificates and keys.                                                                    |
| [Cipher](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Cipher.md)                       | This class allows access to encryption services offered through the Java Cryptography Architecture (JCA).        |
| [Encoding](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Encoding.md)                   | Utility class which handles several common character encodings.                                                  |
| [JWE](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWE.md)                             | This class represents a JSON Web Encryption (JWE) object.                                                        |
| [JWEHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWEHeader.md)                 | This class represents an immutable header of a JWE (JSON Web Encryption) object.                                 |
| [JWS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWS.md)                             | This class represents a JSON Web Signature (JWS) object.                                                         |
| [JWSHeader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.JWSHeader.md)                 | This class represents an immutable header of a JWS (JSON Web Signature) object.                                  |
| [KeyRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.KeyRef.md)                       | This class is used as a reference to a private key in the keystore which can be managed in the Business Manager. |
| [Mac](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Mac.md)                             | This class provides the functionality of a "Message Authentication Code" (MAC) algorithm.                        |
| [MessageDigest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.MessageDigest.md)         | This class provides the functionality of a message digest algorithm, such as MD5 or SHA.                         |
| [SecureRandom](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.SecureRandom.md)           | The SecureRandom class provides a cryptographically strong random number generator (RNG).                        |
| [Signature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.Signature.md)                 | <p>This class allows access to signature services offered through the Java Cryptography Architecture (JCA).      |
| [WeakCipher](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakCipher.md)               | This API provides access to Deprecated algorithms.                                                               |
| [WeakMac](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMac.md)                     | This API provides access to Deprecated algorithms.                                                               |
| [WeakMessageDigest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakMessageDigest.md) | This API provides access to Deprecated algorithms.                                                               |
| [WeakSignature](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.WeakSignature.md)         | This API provides access to Deprecated algorithms.                                                               |
| [X509Certificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.crypto.X509Certificate.md)     | Represents an X.509 public key certificate as defined in RFC 5280.                                               |

<!-- document id=d74d4c1378121bfe1f03031cbd50092db8961619f7a7fcfd9528bbcb7d1de46e url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.md -->

# Package dw.customer

## Classes

| Class                                                                     | Description                                                                                                                                                                                        |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AddressBook](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AddressBook.md)                                 | Represents a set of addresses associated with a specific customer.                                                                                                                                 |
| [AgentUserMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserMgr.md)                               | Provides helper methods for handling agent user functionality (login and logout) Pay attention to appropriate legal and regulatory requirements related to this functionality.                     |
| [AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AgentUserStatusCodes.md)               | AgentUserStatusCodes contains constants representing status codes that can be used with a [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) object to indicate the success or failure of the agent user login process. |
| [AuthenticationStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.AuthenticationStatus.md)               | Holds the status of an authentication process.                                                                                                                                                     |
| [Credentials](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Credentials.md)                                 | Represents the credentials of a customer.                                                                                                                                                          |
| [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md)                                       | Represents a customer.                                                                                                                                                                             |
| [CustomerActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerActiveData.md)                   | Represents the active data for a [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) in Commerce Cloud Digital.                                                                                                    |
| [CustomerAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerAddress.md)                         | The Address class represents a customer's address.                                                                                                                                                 |
| [CustomerCDPData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerCDPData.md)                         | Represents the read-only Customer's Salesforce CDP (Customer Data Platform) data for a [Customer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Customer.md) in Commerce Cloud.                                                      |
| [CustomerContextMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerContextMgr.md)                   | Provides helper methods for managing customer context, such as the Effective Time for which the customer is shopping at                                                                            |
| [CustomerGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerGroup.md)                             | CustomerGroups provide a means to segment customers by various criteria.                                                                                                                           |
| [CustomerList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerList.md)                               | Object representing the collection of customers who are registered for a given site.                                                                                                               |
| [CustomerMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerMgr.md)                                 | Provides helper methods for managing customers and customer profiles.                                                                                                                              |
| [CustomerPasswordConstraints](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPasswordConstraints.md) | Provides access to the constraints of customer passwords.                                                                                                                                          |
| [CustomerPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerPaymentInstrument.md)     | Represents any payment instrument stored in the customers profile, such as credit card or bank transfer.                                                                                           |
| [CustomerStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.CustomerStatusCodes.md)                 | CustomerStatusCodes contains constants representing status codes that can be used with a Status object to indicate the success or failure of an operation.                                         |
| [EncryptedObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.EncryptedObject.md)                         | Defines a API base class for classes containing encrypted attributes like credit cards.                                                                                                            |
| [ExternalProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ExternalProfile.md)                         | Represents the credentials of a customer.                                                                                                                                                          |
| [OrderHistory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.OrderHistory.md)                               | The class provides access to past orders of the customer.                                                                                                                                          |
| [ProductList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductList.md)                                 | Represents a list of products (and optionally a gift certificate) that is typically maintained by a customer.                                                                                      |
| [ProductListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItem.md)                         | An item in a product list.                                                                                                                                                                         |
| [ProductListItemPurchase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListItemPurchase.md)         | A record of the purchase of an item contained in a product list.                                                                                                                                   |
| [ProductListMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListMgr.md)                           | ProductListMgr provides methods for retrieving, creating, searching for, and removing product lists.                                                                                               |
| [ProductListRegistrant](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.ProductListRegistrant.md)             | A ProductListRegistrant is typically associated with an event related product list such as a gift registry.                                                                                        |
| [Profile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Profile.md)                                         | The class represents a customer profile.                                                                                                                                                           |
| [Wallet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.Wallet.md)                                           | Represents a set of payment instruments associated with a registered customer.                                                                                                                     |

<!-- document id=54bccea8d7655b5bb7501e37a441e0f4d7b759e871871a6761d79750b27139bd url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.consent.md -->

# Package dw.customer.consent

## Classes

| Class                                                                               | Description                                                                                                                                                    |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ConsentStatusEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ConsentStatusEntry.md)                     | Represents the consent status for a specific channel and contact point.                                                                                        |
| [MarketingConsentSubscription](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.MarketingConsentSubscription.md) | Represents a marketing consent subscription for a shopper.                                                                                                     |
| [ShopperConsentErrorCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentErrorCodes.md)         | Error codes for [ShopperConsentException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentException.md).                                                                     |
| [ShopperConsentException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentException.md)           | This exception is thrown by [ShopperConsentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentMgr.md) methods when an error occurs during consent subscription operations. |
| [ShopperConsentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.consent.ShopperConsentMgr.md)                       | Provides static helper methods for managing shopper marketing consent subscriptions.                                                                           |

<!-- document id=18f7d5b2098849baced72ae036fa342180f9ee1b45de24f29e9bbca31740c55c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.oauth.md -->

# Package dw.customer.oauth

## Classes

| Class                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md) | Contains OAuth-related artifacts from the HTTP response from the third-party OAuth server when requesting an access token                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [OAuthFinalizedResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthFinalizedResponse.md)     | Contains the combined responses from the third-party OAuth server when finalizing the authentication.<br/><br/> Contains both the [OAuthAccessTokenResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthAccessTokenResponse.md) <br/> and the [OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [OAuthLoginFlowMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md)               | The OAuthLoginFlowMgr encapsulates interactions with third party OAuth providers to support the Authorization Code Flow.<br/> The way to use is: <ul> <li>call [initiateOAuthLogin(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#initiateoauthloginstring)</li> <li>redirect the user to the returned link</li> <li>when the user authenticates there the server will call back to a URL configured on the provider's web site</li> <li>when processing the request made from the provider's web site you have two choices - either call the [obtainAccessToken()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainaccesstoken) and [obtainUserInfo(String, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#obtainuserinfostring-string) methods one after another separately (gives you more flexibility), or call the [finalizeOAuthLogin()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthLoginFlowMgr.md#finalizeoauthlogin) method which internally calls the other two (simpler to use).</li> </ul> Sample code for using it: |
| [OAuthUserInfoResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.oauth.OAuthUserInfoResponse.md)       | Contains the response from the third-party OAuth server when requesting user info.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

<!-- document id=72f5ff2ca3859dd352ad827878b7e205506f6b765224c01d9dae434871adfa89 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.customer.shoppercontext.md -->

# Package dw.customer.shoppercontext

## Classes

| Class                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [ShopperContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContext.md)                     | The class represents Shopper Context.                                                                                                                                                                                                                                                                                                                                                                                                            |
| [ShopperContextErrorCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextErrorCodes.md) | Helper class containing error codes to indicate why a Shopper Context cannot be accessed, set or modified.                                                                                                                                                                                                                                                                                                                                       |
| [ShopperContextException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextException.md)   | This exception could be thrown by [ShopperContextMgr.setShopperContext(ShopperContext, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#setshoppercontextshoppercontext-boolean), [ShopperContextMgr.getShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#getshoppercontext) and [ShopperContextMgr.removeShopperContext()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md#removeshoppercontext) when an error occurs. |
| [ShopperContextMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.customer.shoppercontext.ShopperContextMgr.md)               | <p> Provides static helper methods for managing Shopper Context.                                                                                                                                                                                                                                                                                                                                                                                 |

<!-- document id=41a91482508c4b32b8751bb3d9c5835df456dade80973979de072a9080985ad6 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.md -->

# Package dw.experience

## Classes

| Class                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AspectAttributeValidationException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.AspectAttributeValidationException.md) | This APIException is thrown by method [PageMgr.renderPage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#renderpagestring-map-string) and [PageMgr.serializePage(String, Map, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md#serializepagestring-map-string) to indicate that the passed aspect attributes failed during validation against the definition provided through the aspect type of the page. |
| [Component](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md)                                                   | This class represents a page designer managed component as part of a page.                                                                                                                                                                                                                                                                                                                  |
| [ComponentRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentRenderSettings.md)                       | A config that drives how the component is rendered.                                                                                                                                                                                                                                                                                                                                         |
| [ComponentScriptContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md)                         | This is the context that is handed over to the `render` and `serialize` function of the respective component type script.                                                                                                                                                                                                                                                                   |
| [CustomEditor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditor.md)                                             | This class represents a custom editor for component attributes of type `custom`.                                                                                                                                                                                                                                                                                                            |
| [CustomEditorResources](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.CustomEditorResources.md)                           | This class represents the resources of a custom editor, i.e.                                                                                                                                                                                                                                                                                                                                |
| [Page](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Page.md)                                                             | <p> This class represents a page designer managed page.                                                                                                                                                                                                                                                                                                                                     |
| [PageMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageMgr.md)                                                       | Provides functionality for getting, rendering and serializing page designer managed pages.                                                                                                                                                                                                                                                                                                  |
| [PageScriptContext](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.PageScriptContext.md)                                   | This is the context that is handed over to the `render` and `serialize` function of the respective page type script.                                                                                                                                                                                                                                                                        |
| [Region](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Region.md)                                                         | This class represents a region which serves as container of components.                                                                                                                                                                                                                                                                                                                     |
| [RegionRenderSettings](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.RegionRenderSettings.md)                             | A config that drives how the region is rendered.                                                                                                                                                                                                                                                                                                                                            |

<!-- document id=71788f9c08358d09726de8f37445308d321294c9398dbaa567eef8328992721b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.cms.md -->

# Package dw.experience.cms

## Classes

| Class                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [CMSRecord](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md) | This class represents a Salesforce CMS record, exposing its: <ul> <li>`id`, see [getID()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#getid)</li> <li>`type`, see [getType()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#gettype)</li> <li>`attributes`, see [getAttributes()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.cms.CMSRecord.md#getattributes)</li> </ul> The `attributes` are key value pairs: <ul> <li>the key being the attribute id as given in the `type.attribute_definitions` entries</li> <li>the value being a DWScript API object resolved from the raw attribute value based on the attribute type as given in the `type.attribute_definitions` entries (similar to how [ComponentScriptContext.getContent()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.ComponentScriptContext.md#getcontent) exposes the raw attribute value of a [Component.getAttribute(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.Component.md#getattributestring) in shape of a DWScript API object based on the attribute type)</li> </ul> |

<!-- document id=090b5285cd9d697b4276a22bf6ea0972612cd1444360d4d866e32fc58584e177 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.experience.image.md -->

# Package dw.experience.image

## Classes

| Class                                                 | Description                                                                     |
| ----------------------------------------------------- | ------------------------------------------------------------------------------- |
| [FocalPoint](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.FocalPoint.md)       | This class represents an image focal point.                                     |
| [Image](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.Image.md)                 | This class represents an image with additional configuration capabilities (e.g. |
| [ImageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.experience.image.ImageMetaData.md) | This class represents the image meta data, e.g.                                 |

<!-- document id=5a6a110134ee8006b5f2e5296194c5c1f9a2fbc5ac4f9ffcb3ac75a70e208492 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.applepay.md -->

# Package dw.extensions.applepay

## Classes

| Class                                                              | Description                                                                    |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| [ApplePayHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHookResult.md) | <p> Result of a hook handling an Apple Pay request.                            |
| [ApplePayHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.applepay.ApplePayHooks.md)           | ApplePayHooks interface containing extension points for customizing Apple Pay. |

<!-- document id=06164220e0d9cfc4615adceb57aa6c8e26c78eaf68fd5f67bd15b63a0a3c1409 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.facebook.md -->

# Package dw.extensions.facebook

## Classes

| Class                                                            | Description                                                                                    |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| [FacebookFeedHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookFeedHooks.md) | FacebookFeedHooks interface containing extension points for customizing Facebook export feeds. |
| [FacebookProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.facebook.FacebookProduct.md)     | Represents a row in the Facebook catalog feed export.                                          |

<!-- document id=efdc24282456163a55fb9fbfe6d5e6457d75db4897dc45163611bae94d4e5e41 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.paymentapi.md -->

# Package dw.extensions.paymentapi

## Classes

| Class                                                          | Description                                                                                                                        |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [PaymentApiHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentapi.PaymentApiHooks.md) | PaymentApiHooks interface containing extension points for customizing Payment API requests for authorization, and their responses. |

<!-- document id=447af4660d182d1a6850fcbf8643fe41fbeaee6fe6c5dcddbf5b42f4db719e04 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.paymentrequest.md -->

# Package dw.extensions.paymentrequest

## Classes

| Class                                                                                | Description                                                                                 |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| [PaymentRequestHookResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHookResult.md) | Result of a hook handling a Payment Request request                                         |
| [PaymentRequestHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.paymentrequest.PaymentRequestHooks.md)           | PaymentRequestHooks interface containing extension points for customizing Payment Requests. |

<!-- document id=d18ecd6af1cdec1d881d89660723b6411c42d45de7a7b4026666d12120e0f070 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.payments.md -->

# Package dw.extensions.payments

## Classes

| Class                                                                                                                      | Description                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [SalesforceAdyenPaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenPaymentIntent.md)                                     | <p> Salesforce Payments representation of an Adyen payment intent object.                                                                                          |
| [SalesforceAdyenSavedPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceAdyenSavedPaymentMethod.md)                           | <p> Salesforce Payments representation of an Adyen saved payment method object.                                                                                    |
| [SalesforceBancontactPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceBancontactPaymentDetails.md)                         | <p> Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_BANCONTACT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_bancontact). |
| [SalesforceCardPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceCardPaymentDetails.md)                                     | <p> Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_CARD](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_card).             |
| [SalesforceEpsPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceEpsPaymentDetails.md)                                       | <p> Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_EPS](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_eps).               |
| [SalesforceIdealPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceIdealPaymentDetails.md)                                   | <p> Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_IDEAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_ideal).           |
| [SalesforceKlarnaPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceKlarnaPaymentDetails.md)                                 | <p> Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_KLARNA](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_klarna).         |
| [SalesforcePaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentDetails.md)                                             | <p> Base class details to a Salesforce Payments payment.                                                                                                           |
| [SalesforcePaymentIntent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentIntent.md)                                               | <p> Salesforce Payments representation of a Stripe payment intent object.                                                                                          |
| [SalesforcePaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md)                                               | <p> Salesforce Payments representation of a payment method object.                                                                                                 |
| [SalesforcePaymentRequest](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentRequest.md)                                             | <p> Salesforce Payments request for a shopper to make payment.                                                                                                     |
| [SalesforcePaymentsHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsHooks.md)                                               | <p> This interface represents all script hooks that can be registered to customize the Salesforce Payments functionality.                                          |
| [SalesforcePaymentsMerchantAccount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccount.md)                           | Contains information about a merchant account configured for use with Salesforce Payments.                                                                         |
| [SalesforcePaymentsMerchantAccountPaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMerchantAccountPaymentMethod.md) | Contains information about a payment method to be presented to a payer, as configured for a Salesforce Payments merchant account.                                  |
| [SalesforcePaymentsMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsMgr.md)                                                   | Contains functionality for use with Salesforce Payments.                                                                                                           |
| [SalesforcePaymentsSiteConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsSiteConfiguration.md)                       | <p> Salesforce Payments representation of a payment site configuration object.                                                                                     |
| [SalesforcePaymentsZone](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentsZone.md)                                                 | <p> Salesforce Payments representation of a payments zone.                                                                                                         |
| [SalesforcePayPalOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md)                                                   | <p> Salesforce Payments representation of a PayPal order object.                                                                                                   |
| [SalesforcePayPalOrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderAddress.md)                                     | <p> Salesforce Payments representation of a PayPal order address object.                                                                                           |
| [SalesforcePayPalOrderPayer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrderPayer.md)                                         | <p> Salesforce Payments representation of a PayPal order's payer object.                                                                                           |
| [SalesforcePayPalPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalPaymentDetails.md)                                 | <p> Details to a Salesforce Payments payment of type [SalesforcePayPalOrder.TYPE_PAYPAL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_paypal).             |
| [SalesforceSepaDebitPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceSepaDebitPaymentDetails.md)                           | <p> Details to a Salesforce Payments payment of type [SalesforcePaymentMethod.TYPE_SEPA_DEBIT](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePaymentMethod.md#type_sepa_debit). |
| [SalesforceVenmoPaymentDetails](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforceVenmoPaymentDetails.md)                                   | <p> Details to a Salesforce Payments payment of type [SalesforcePayPalOrder.TYPE_VENMO](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.payments.SalesforcePayPalOrder.md#type_venmo).               |

<!-- document id=3d47e236ff968fe153e0015abfd44b157f6fddde8dfb2104058378bdd9010d47 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.extensions.pinterest.md -->

# Package dw.extensions.pinterest

## Classes

| Class                                                                     | Description                                                                                       |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [PinterestAvailability](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestAvailability.md) | Represents a row in the Pinterest availability feed export file.                                  |
| [PinterestFeedHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestFeedHooks.md)       | PinterestFeedHooks interface containing extension points for customizing Pinterest export feeds.  |
| [PinterestOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrder.md)               | An order that was placed through Pinterest.                                                       |
| [PinterestOrderHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestOrderHooks.md)     | PinterestOrderHooks interface containing extension points for customizing Pinterest order status. |
| [PinterestProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.extensions.pinterest.PinterestProduct.md)           | Represents a row in the Pinterest catalog feed export.                                            |

<!-- document id=b01a17ea002b06665eb79b2ec94d06a9a121b323e949972cbad8e09efd1c284b url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.io.md -->

# Package dw.io

## Classes

| Class                                                         | Description                                                                      |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [CSVStreamReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamReader.md)                   | The class supports reading a CSV file.                                           |
| [CSVStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.CSVStreamWriter.md)                   | The class writes a CSV file.                                                     |
| [File](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.File.md)                                         | Represents a file resource accessible from scripting.                            |
| [FileReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileReader.md)                             | File reader class.                                                               |
| [FileWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.FileWriter.md)                             | Convenience class for writing character files.                                   |
| [InputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.InputStream.md)                           | The class represent a stream of bytes that can be read from the application.     |
| [OutputStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.OutputStream.md)                         | The class represent a stream of bytes that can be written from the application.  |
| [PrintWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.PrintWriter.md)                           | Template output stream writer.                                                   |
| [RandomAccessFileReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.RandomAccessFileReader.md)     | Instances of this class support reading from a random access file.               |
| [Reader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Reader.md)                                     | The class supports reading characters from a stream.                             |
| [StringWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.StringWriter.md)                         | A Writer that can be used to generate a String.                                  |
| [Writer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.Writer.md)                                     | The class supports writing characters to a stream.                               |
| [XMLIndentingStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLIndentingStreamWriter.md) | A XMLIndentingStreamWriter writes the XML output formatted for good readability. |
| [XMLStreamConstants](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamConstants.md)             | Useful constants for working with XML streams.                                   |
| [XMLStreamReader](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamReader.md)                   | The XMLStreamReader allows forward, read-only access to XML.                     |
| [XMLStreamWriter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.io.XMLStreamWriter.md)                   | The XMLStreamWriter can be used to write small and large XML feeds.              |

<!-- document id=169eb9baa2472b13c8b9a4acb8b3c09a491c7af78692b47942021c94a6186475 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.job.md -->

# Package dw.job

## Classes

| Class                                          | Description                                              |
| ---------------------------------------------- | -------------------------------------------------------- |
| [JobExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobExecution.md)         | Represents an execution of a job.                        |
| [JobStepExecution](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.job.JobStepExecution.md) | Represents an execution of a step that belongs to a job. |

<!-- document id=7068ebddf0e3ae2df5f845a85881dd20b5159f5d387f87342526b785e7c988dc url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.net.md -->

# Package dw.net

## Classes

| Class                                                        | Description                                                                                                  |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| [FTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPClient.md)                             | The FTPClient class supports the FTP commands CD, GET, PUT, DEL, MKDIR, RENAME, and LIST.                    |
| [FTPFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.FTPFileInfo.md)                         | The class is used to store information about a remote file.                                                  |
| [HTTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClient.md)                           | The HTTPClient class supports the HTTP methods GET, POST, HEAD, PUT, PATCH, OPTIONS, and DELETE.             |
| [HTTPClientLoggingConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPClientLoggingConfig.md) | Script API for configuring HTTP client logging and sensitive data redaction.                                 |
| [HTTPRequestPart](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.HTTPRequestPart.md)                 | This represents a part in a multi-part HTTP POST request.                                                    |
| [Mail](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.Mail.md)                                       | This class is used to send an email with either plain text or MimeEncodedText content.                       |
| [SFTPClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPClient.md)                           | The SFTPClient class supports the SFTP commands GET, PUT, DEL, MKDIR, RENAME, and LIST.                      |
| [SFTPFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.SFTPFileInfo.md)                       | The class is used to store information about a remote file.                                                  |
| [WebDAVClient](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVClient.md)                       | The WebDAVClient class supports the WebDAV methods GET, PUT, MKCOL, MOVE, COPY, PROPFIND,OPTIONS and DELETE. |
| [WebDAVFileInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.net.WebDAVFileInfo.md)                   | Simple class representing a file on a remote WebDAV location.                                                |

<!-- document id=dc992fb7f1f7c1a772fe256d8ebf459a7272db9e9e6a5127a12f32c1f302ee3f url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.object.md -->

# Package dw.object

## Classes

| Class                                                                         | Description                                                                                                                         |
| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [ActiveData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ActiveData.md)                                         | Represents the active data for an object in Commerce Cloud Digital.                                                                 |
| [CustomAttributes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomAttributes.md)                             | This class is used together with other classes that contain custom attributes and is used to read and write these attributes.       |
| [CustomObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObject.md)                                     | Represents a custom object and its corresponding attributes.                                                                        |
| [CustomObjectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.CustomObjectMgr.md)                               | Manager class which provides methods for creating, retrieving, deleting, and searching for custom objects.                          |
| [Extensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Extensible.md)                                         | Base class alternative to ExtensibleObject for objects customizable through the metadata system.                                    |
| [ExtensibleObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ExtensibleObject.md)                             | Base class for all persistent business objects in Commerce Cloud Digital that are customizable through the metadata system.         |
| [Note](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.Note.md)                                                     | Represents a note that can be attached to any persistent object that supports this feature.                                         |
| [ObjectAttributeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeDefinition.md)           | Represents the definition of an object's attribute.                                                                                 |
| [ObjectAttributeGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeGroup.md)                     | Represents a group of object attributes.                                                                                            |
| [ObjectAttributeValueDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectAttributeValueDefinition.md) | Represents the value definition associated with an object attribute.                                                                |
| [ObjectTypeDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.ObjectTypeDefinition.md)                     | The class provides access to the meta data of a system object or custom object.                                                     |
| [PersistentObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.PersistentObject.md)                             | Common base class for all objects in Commerce Cloud Digital that have an identity and can be stored and retrieved.                  |
| [SimpleExtensible](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SimpleExtensible.md)                             | Base class alternative to ExtensibleObject for customizable objects which do not rely on the metadata system.                       |
| [SystemObjectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.object.SystemObjectMgr.md)                               | Manager class which provides methods for querying of system objects with meta data using the Commerce Cloud Digital query language. |

<!-- document id=be47ebc1e5ad35d97579c2abfdce8a4f4acaa9aeb2a81b03855cfdda4fe25f44 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.md -->

# Package dw.order

## Classes

| Class                                                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AbstractItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItem.md)                                                               | An item which references, or in other words is based upon, an [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [AbstractItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md)                                                       | Basis for item-based objects stemming from a single [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md), with these common properties (Invoice is used as an example): <ul> <li> The object has been created from an Order accessible using [getOrder()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getorder)</li> <li>Contains a collection of [items](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AbstractItemCtnr.md#getitems), each item related to exactly one [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) which in turn represents an extension to one of the order [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md) or one [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md). |
| [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md)                                                                 | The Appeasement represents a shopper request for an order credit.<br/> Example: The buyer finds any problem with the products but he agrees to preserve them, if he would be compensated, rather than return them.<br/> <br/> The Appeasement contains 1..n appeasement items.                                                                                                                                                                                                                                                                                                                 |
| [AppeasementItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.AppeasementItem.md)                                                         | Represents an item of an [Appeasement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md) which is associated with one [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md) usually representing an [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md).                                                                                                                                                                                                                                                                                                                                                             |
| [Basket](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Basket.md)                                                                           | The Basket class represents a shopping cart.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [BasketMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md)                                                                     | Provides static helper methods for managing baskets.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [BonusDiscountLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BonusDiscountLineItem.md)                                             | Line item representing an applied [BonusChoiceDiscount](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.campaign.BonusChoiceDiscount.md) in a LineItemCtnr.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [CouponLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CouponLineItem.md)                                                           | The CouponLineItem class is used to store redeemed coupons in the Basket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [CreateAgentBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateAgentBasketLimitExceededException.md)         | This exception is thrown by [BasketMgr.createAgentBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createagentbasket) to indicate that the open agent basket limit for the current session customer is already reached, and therefore no new agent basket could be created.                                                                                                                                                                                                                                                                                                                                     |
| [CreateBasketFromOrderException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateBasketFromOrderException.md)                           | This APIException is thrown by method [BasketMgr.createBasketFromOrder(Order)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createbasketfromorderorder) to indicate no Basket could be created from the Order.                                                                                                                                                                                                                                                                                                                                                                                                        |
| [CreateCouponLineItemException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateCouponLineItemException.md)                             | This exception could be thrown by [LineItemCtnr.createCouponLineItem(String, Boolean)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md#createcouponlineitemstring-boolean) when the provided coupon code is invalid.                                                                                                                                                                                                                                                                                                                                                                                                  |
| [CreateOrderException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateOrderException.md)                                               | This APIException is thrown by method [OrderMgr.createOrder(Basket, String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md#createorderbasket-string) to indicate no Order could be created from the Basket.                                                                                                                                                                                                                                                                                                                                                                                                             |
| [CreateTemporaryBasketLimitExceededException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.CreateTemporaryBasketLimitExceededException.md) | This exception is thrown by [BasketMgr.createTemporaryBasket()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.BasketMgr.md#createtemporarybasket) to indicate that the open temporary basket limit for the current session customer is already reached, and therefore no new temporary basket could be created.                                                                                                                                                                                                                                                                                                                     |
| [GiftCertificate](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificate.md)                                                         | Represents a Gift Certificate that can be used to purchase products.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [GiftCertificateLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateLineItem.md)                                         | Represents a Gift Certificate line item in the cart.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [GiftCertificateMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateMgr.md)                                                   | The GiftCertificateMgr class contains a set of static methods for interacting with GiftCertificates.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [GiftCertificateStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.GiftCertificateStatusCodes.md)                                   | Helper class containing status codes for the various errors that can occur when redeeming a gift certificate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md)                                                                         | The Invoice can be a debit or credit invoice, and is created from custom scripts using one of the methods [ShippingOrder.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createinvoicestring), [Appeasement.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Appeasement.md#createinvoicestring), [ReturnCase.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createinvoicestring) or [Return.createInvoice(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createinvoicestring).                                                                                                                                                    |
| [InvoiceItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.InvoiceItem.md)                                                                 | Represents a specific item in an [Invoice](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Invoice.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [LineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.md)                                                                       | Common line item base class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [LineItemCtnr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemCtnr.md)                                                               | A container for line items, such as ProductLineItems, CouponLineItems, GiftCertificateLineItems.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [LineItemTax](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.md)                                                                 | A tax on a line item: tax identifier, rate, and optional amount.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md)                                                                             | The Order class represents an order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [OrderAddress](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderAddress.md)                                                               | The Address class represents a customer's address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [OrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderItem.md)                                                                     | Defines _extensions_ to [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)s and [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)s belonging to an [order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md).                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [OrderMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderMgr.md)                                                                       | <p> Provides static helper methods for managing orders.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [OrderPaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderPaymentInstrument.md)                                           | Represents any payment instrument used to pay orders, such as credit card or bank transfer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [OrderProcessStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.OrderProcessStatusCodes.md)                                         | Contains constants representing different status codes for interacting with an order, such as cancelling or editing an order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [PaymentCard](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentCard.md)                                                                 | Represents payment cards and provides methods to access the payment card attributes and status.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [PaymentInstrument](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentInstrument.md)                                                     | Base class for payment instrument either stored in the customers profile or related to an order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [PaymentMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMethod.md)                                                             | The PaymentMethod class represents a logical type of payment a customer can make in the storefront.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [PaymentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md)                                                                   | [PaymentMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentMgr.md) is used to access payment methods and payment cards of the current site.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [PaymentProcessor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentProcessor.md)                                                       | A PaymentProcessor represents an entity that processes payments of one or more types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [PaymentStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentStatusCodes.md)                                                   | Helper class containing status codes for the various errors that can occur when validating a payment card.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [PaymentTransaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PaymentTransaction.md)                                                   | The PaymentTransaction class represents a payment transaction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [PriceAdjustment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustment.md)                                                         | The PriceAdjustment class represents an adjustment to the price of an order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [PriceAdjustmentLimitTypes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.PriceAdjustmentLimitTypes.md)                                     | Helper class containing price adjustment limit types.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [ProductLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductLineItem.md)                                                         | Represents a specific product line item.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [ProductShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingCost.md)                                                 | Instances of ProductShippingCost represent product specific shipping costs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [ProductShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingLineItem.md)                                         | Represents a specific line item in a shipment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [ProductShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ProductShippingModel.md)                                               | Instances of ProductShippingModel provide access to product-level shipping information, such as applicable or inapplicable shipping methods and shipping cost defined for the product for a specified shipping method.                                                                                                                                                                                                                                                                                                                                                                         |
| [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md)                                                                           | The Return represents a physical customer return, and contains 1..n [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)s.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md)                                                                   | All returns exist in the context of a ReturnCase, each [Order](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Order.md) can have any number of ReturnCases.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [ReturnCaseItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCaseItem.md)                                                           | An item of a [ReturnCase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md), created using method [ReturnCase.createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnCase.md#createitemstring).                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [ReturnItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ReturnItem.md)                                                                   | An item of a [Return](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md), created using [Return.createItem(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Return.md#createitemstring).                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| [Shipment](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.Shipment.md)                                                                       | Represents an order shipment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [ShipmentShippingCost](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingCost.md)                                               | Represents shipping cost applied to shipments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [ShipmentShippingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShipmentShippingModel.md)                                             | Instances of ShipmentShippingModel provide access to shipment-level shipping information, such as applicable and inapplicable shipping methods and shipping cost.                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [ShippingLineItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLineItem.md)                                                       | Represents a specific line item in a shipment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [ShippingLocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingLocation.md)                                                       | Represents a specific location for a shipment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [ShippingMethod](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMethod.md)                                                           | ShippingMethod represents how the shipment will be shipped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [ShippingMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingMgr.md)                                                                 | Provides methods to access the shipping information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md)                                                             | A shipping order is used to specify items that should be shipped, and is typically exported to, and updated by a back-office warehouse management system.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md)                                                     | One or more ShippingOrderItems are contained in a [ShippingOrder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md), created using [ShippingOrder.createShippingOrderItem(OrderItem, Quantity)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#createshippingorderitemorderitem-quantity) and can be retrieved by [ShippingOrder.getItems()](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrder.md#getitems).                                                                                                                                                                                                                                                          |
| [SumItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.SumItem.md)                                                                         | Container used to represent an subtotal or grandtotal item which contains various prices and a tax breakdown held in a collection of tax-items.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)                                                                       | Contains the formal definition of a tax including a type (it's just the key), a [percentage value](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getrate) if provided, a [caption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getcaption) and a [description](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md#getdescription).                                                                                                                                                                                                                                                                                                                                           |
| [TaxItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxItem.md)                                                                         | An item containing tax information allowing a tax breakdown between a number of [TaxGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxGroup.md)s.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [TaxMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TaxMgr.md)                                                                           | Provides methods to access the tax table.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md)                                                               | Provides basic information about a tracking info.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [TrackingRef](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingRef.md)                                                                 | Provides basic information about the [TrackingInfo](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.TrackingInfo.md) a [ShippingOrderItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.ShippingOrderItem.md) is contained.                                                                                                                                                                                                                                                                                                                                                                                                                                               |

<!-- document id=4a39c8dca81591840f7de2db0373a8a7718e30993cdb7993f462bcf57d26a2e8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.order.hooks.md -->

# Package dw.order.hooks

## Classes

| Class                                                      | Description                                                                                                                    |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [BasketMergeHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.BasketMergeHooks.md)     | This interface represents all script hooks that can be registered to merge baskets.                                            |
| [CalculateHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CalculateHooks.md)         | This interface represents all script hooks that can be registered to customize the order and basket calculation functionality. |
| [CheckoutHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.CheckoutHooks.md)           | This interface represents script hooks that can be registered to populate customer details into a basket.                      |
| [OrderHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.OrderHooks.md)                 | This interface represents all script hooks that can be registered to customize the order logic.                                |
| [PaymentHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.PaymentHooks.md)             | This interface represents all script hooks that can be registered to customize the order center payment functionality.         |
| [ReturnHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ReturnHooks.md)               | This interface represents all script hooks that can be registered to customizing the order center return resource.             |
| [ShippingHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingHooks.md)           | This interface represents shipping extension points for Commerce App shipping providers.                                       |
| [ShippingOrderHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.ShippingOrderHooks.md) | This interface represents all script hooks that can be registered around shipping order lifecycle.                             |
| [TaxHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.hooks.TaxHooks.md)                     | This interface represents tax extension points for Commerce App tax providers.                                                 |

<!-- document id=212013702a1325b4b693f6f52ff8f6dac9844031dbfbc1165589f7da26651c65 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.rpc.md -->

# Package dw.rpc

## Classes

| Class                                  | Description                                                                            |
| -------------------------------------- | -------------------------------------------------------------------------------------- |
| [SOAPUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.SOAPUtil.md)         | Utility class for working with SOAP web services.                                      |
| [Stub](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.Stub.md)                 | This is the base class for all service stubs accessible through a WebReference object. |
| [WebReference](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.rpc.WebReference.md) | Represents a web service defined in a WSDL file.                                       |

<!-- document id=8e9b68f58732a979e17bae2a8746f4a2604763afb9a8b78707ee988e5b40f33c url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.sitemap.md -->

# Package dw.sitemap

## Classes

| Class                                    | Description                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| [SitemapFile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapFile.md) | Instances of this class represent sitemap files located in the appservers shared file system. |
| [SitemapMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md)   | [SitemapMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.sitemap.SitemapMgr.md) is used to access and modify custom sitemap files.     |

<!-- document id=d6a0f580088f2e4dfb58da0f1c662f34a39f5c0dd72a9d42757983f3fbe4d9f4 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.suggest.md -->

# Package dw.suggest

## Classes

| Class                                                            | Description                                                                                                                                                                                                                             |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [BrandSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.BrandSuggestions.md)               | The brands suggestion container provides access to brands found using the suggested terms.                                                                                                                                              |
| [CategorySuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CategorySuggestions.md)         | The category suggestion container provides access to categories found using the suggested terms as search criteria.                                                                                                                     |
| [ContentSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ContentSuggestions.md)           | The content suggestion container provides access to content pages found using the suggested terms as search criteria.                                                                                                                   |
| [CustomSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.CustomSuggestions.md)             | The custom suggestion container provides access to merchant provided search phrases found using the suggested terms as search criteria.                                                                                                 |
| [ProductSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.ProductSuggestions.md)           | The product suggestion container provides access to products found using the suggested terms.                                                                                                                                           |
| [SearchPhraseSuggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SearchPhraseSuggestions.md) | The search phrase suggestions contain a list of suggested search phrases (see [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md)) as well as, for each of the search phrase terms, a list with corrected and completed alternative terms. |
| [SuggestedCategory](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedCategory.md)             | This class represents a suggested catalog category.                                                                                                                                                                                     |
| [SuggestedContent](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedContent.md)               | This class represents a suggested content page.                                                                                                                                                                                         |
| [SuggestedPhrase](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedPhrase.md)                 | This class represents a suggested phrase.                                                                                                                                                                                               |
| [SuggestedProduct](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedProduct.md)               | This class represents a suggested product.                                                                                                                                                                                              |
| [SuggestedTerm](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerm.md)                     | A single suggested term.                                                                                                                                                                                                                |
| [SuggestedTerms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestedTerms.md)                   | This container represents a list of suggested terms, all belonging to a particular single original term of the users input search phrase.                                                                                               |
| [Suggestions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.Suggestions.md)                         | This is the base class for suggestions containers.                                                                                                                                                                                      |
| [SuggestModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.suggest.SuggestModel.md)                       | The Suggest model provides methods and functions to access search suggestions.                                                                                                                                                          |

<!-- document id=b76571ed52ad8d30171816422812ed96e9f3c3d8e78d56fff1fa8621e1a43f09 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.svc.md -->

# Package dw.svc

## Classes

| Class                                                            | Description                                                                                |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| [FTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPService.md)                               | Represents an FTP or SFTP Service.                                                         |
| [FTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.FTPServiceDefinition.md)           | Represents an FTP or SFTP Service Definition.                                              |
| [HTTPFormService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormService.md)                     | Represents an HTTP Form POST Service.                                                      |
| [HTTPFormServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPFormServiceDefinition.md) | Represents an HTTP Form POST Service Definition.                                           |
| [HTTPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPService.md)                             | Represents an HTTP Service.                                                                |
| [HTTPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.HTTPServiceDefinition.md)         | Represents an HTTP Service Definition.                                                     |
| [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md)           | The LocalServiceRegistry is responsible for managing Service instances.                    |
| [Result](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Result.md)                                       | Represents the result of a service call.                                                   |
| [Service](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.Service.md)                                     | Base class of Services.                                                                    |
| [ServiceCallback](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCallback.md)                     | Defines callbacks for use with the [LocalServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.LocalServiceRegistry.md). |
| [ServiceConfig](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceConfig.md)                         | Configuration object for Services.                                                         |
| [ServiceCredential](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceCredential.md)                 | Configuration object for Service Credentials.                                              |
| [ServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceDefinition.md)                 | Base class of Service Definitions.                                                         |
| [ServiceProfile](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceProfile.md)                       | Configuration object for Service Profiles.                                                 |
| [ServiceRegistry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.ServiceRegistry.md)                     | The ServiceRegistry is responsible for managing Service definitions and their instances.   |
| [SOAPService](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPService.md)                             | Represents a SOAP WebService.                                                              |
| [SOAPServiceDefinition](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.svc.SOAPServiceDefinition.md)         | Represents a SOAP WebService definition.                                                   |

<!-- document id=cb64f3fda35ad4b2e5e3e175aa55aeee0bd99ecc55c6452daf80005fc92f9f37 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.system.md -->

# Package dw.system

## Classes

| Class                                                           | Description                                                                                                                                                                                        |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AgentUserStatusCodes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.AgentUserStatusCodes.md)       | AgentUserStatusCodes contains constants representing status codes that can be used with a [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md) object to indicate the success or failure of the agent user login process. |
| [Cache](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Cache.md)                                     | The Cache class represents a custom cache.                                                                                                                                                         |
| [CacheMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.CacheMgr.md)                               | The CacheMgr class is the entry point for using custom caches.                                                                                                                                     |
| [HookMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.HookMgr.md)                                 | This class provides functionality to call hooks.                                                                                                                                                   |
| [InternalObject](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.InternalObject.md)                   | Class used to wrap internal objects to hide them from B2C Commerce Script code.                                                                                                                    |
| [JobProcessMonitor](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.JobProcessMonitor.md)             | **_Reserved for future use_**.                                                                                                                                                                     |
| [Log](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Log.md)                                         | A log4j like logger instance.                                                                                                                                                                      |
| [Logger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Logger.md)                                   | The Logger class provides logging utility methods.                                                                                                                                                 |
| [LogNDC](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.LogNDC.md)                                   | A Nested Diagnostic Context, or NDC in short, is an instrument to distinguish interleaved log output from different sources.                                                                       |
| [OrganizationPreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.OrganizationPreferences.md) | OrganizationPreferences is a container for custom global (i.e.                                                                                                                                     |
| [Pipeline](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Pipeline.md)                               | A helper for executing pipelines from JavaScript.                                                                                                                                                  |
| [PipelineDictionary](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.PipelineDictionary.md)           | The class provides access to the values in the pipeline dictionary.                                                                                                                                |
| [RemoteInclude](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RemoteInclude.md)                     | The class represents a remote include value that can be assigned to JSON Object properties.                                                                                                        |
| [Request](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Request.md)                                 | Represents a request in Commerce Cloud Digital.                                                                                                                                                    |
| [RequestHooks](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RequestHooks.md)                       | This class represents all script hooks that can be registered to receive notifications about storefront requests.                                                                                  |
| [Response](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Response.md)                               | Represents an HTTP response in Commerce Cloud Digital.                                                                                                                                             |
| [RESTErrorResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTErrorResponse.md)             | This class represents a REST error response that is compliant with [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).                                                                             |
| [RESTResponseMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTResponseMgr.md)                 | This class provides helper methods for creating REST error and success responses.                                                                                                                  |
| [RESTSuccessResponse](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.RESTSuccessResponse.md)         | This class represents a REST success response that is compliant with the RFC standards.                                                                                                            |
| [SearchStatus](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SearchStatus.md)                       | A SearchStatus is used for communicating a Search API status back to a client.                                                                                                                     |
| [Session](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Session.md)                                 | Represents a session in B2C Commerce.                                                                                                                                                              |
| [Site](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Site.md)                                       | This class represents a site in Commerce Cloud Digital and provides access to several site-level configuration values which are managed from within the Business Manager.                          |
| [SitePreferences](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.SitePreferences.md)                 | SitePreferences is a container for custom site-level attributes.                                                                                                                                   |
| [Status](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Status.md)                                   | A Status is used for communicating an API status code back to a client.                                                                                                                            |
| [StatusItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.StatusItem.md)                           | A StatusItem holds all the status information.                                                                                                                                                     |
| [System](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.System.md)                                   | Represents the Commerce Cloud Digital server instance.                                                                                                                                             |
| [Transaction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.system.Transaction.md)                         | Represents the current transaction.                                                                                                                                                                |

<!-- document id=9a861a48c2dcebc5db951d7635d9d4ad6f4f510902c9d94aea6cf1b4d9d236d8 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.template.md -->

# Package dw.template

## Classes

| Class                               | Description                                               |
| ----------------------------------- | --------------------------------------------------------- |
| [ISML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.ISML.md)         | This class provides support for rendering ISML templates. |
| [Velocity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.template.Velocity.md) | This class renders an Apache Velocity template.           |

<!-- document id=f79a0968b796328e0767f67c74e61f94bc9ba2c96b640adfe7a5851174d63a18 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.util.md -->

# Package dw.util

## Classes

| Class                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ArrayList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.ArrayList.md)                     | The ArrayList class is a container for a list of objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [Assert](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Assert.md)                           | The Assert class provides utility methods for assertion events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [BigInteger](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.BigInteger.md)                   | The BigInteger class is a helper class to represent an arbitrary long integer number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [Bytes](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Bytes.md)                             | A simple immutable class representing an array of bytes, used for working with binary data in a scripting context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [Calendar](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Calendar.md)                       | Represents a Calendar and is based on the java.util.Calendar class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md)                   | Represents a collection of objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [Currency](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Currency.md)                       | Represents a currency supported by the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [DateUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.DateUtils.md)                     | A class with several utility methods for Date objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| [Decimal](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Decimal.md)                         | The Decimal class is a helper class to perform decimal arithmetic in scripts and to represent a decimal number with arbitrary length.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) | [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) is an extension of [Collection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Collection.md) which provides possibilities to <ul> <li>_filter_ the elements to return a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) with a filtered set of elements</li> <li>_sort_ the elements to return a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) with a defined sort order</li> <li>_transform_ the elements to return a new [FilteringCollection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.FilteringCollection.md) containing related elements</li> <li>_provide a map_ of the elements against a predefined key</li> </ul> |
| [Geolocation](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Geolocation.md)                 | Read-only class representing a position on the earth (latitude and longitude) and information associated with that location (e.g.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [HashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashMap.md)                         | Represents a hash map of objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [HashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.HashSet.md)                         | Represents a HashSet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Iterator.md)                       | The Iterator class allows you to access items in a collection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| [LinkedHashMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashMap.md)             | This class implements a HashMap, which guarantees a iteration order according the put-order of the elements in the map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| [LinkedHashSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.LinkedHashSet.md)             | The class LinkedHashSet implements a hash set with a guaranteed iteration order.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [List](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.List.md)                               | An ordered collection of objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| [Locale](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Locale.md)                           | Represents a Locale supported by the system.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Map.md)                                 | Represents a Map of objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [MapEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MapEntry.md)                       | The class represent an entry within a Map.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [MappingKey](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingKey.md)                   | Encapsulates the key for a mapping read in with the ImportKeyValueMapping job step.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [MappingMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.MappingMgr.md)                   | Used to manage and interface with mappings loaded into the system via the ImportKeyValueMapping job step.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [PropertyComparator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.PropertyComparator.md)   | This comparator can be used for the List sort() methods and for the SortSet and SortedMap classes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [SecureEncoder](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureEncoder.md)             | SecureEncoder contains many methods for manipulating untrusted data Strings into RFC-Compliant Strings for a given context by encoding "bad" data into the proper format.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [SecureFilter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SecureFilter.md)               | SecureFilter contains many methods for manipulating untrusted data Strings into RFC-Compliant Strings for a given context by removing "bad" data from the untrusted data.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| [SeekableIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SeekableIterator.md)       | A special Iterator, which is returned by the system to iterate through large sets of data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Set.md)                                 | Represents a set of objects.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| [SortedMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedMap.md)                     | A map that further guarantees that it will be in ascending key order, sorted according to the natural ordering of its keys, or by a comparator provided at sorted map creation time.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| [SortedSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.SortedSet.md)                     | A set that further guarantees that its iterator will traverse the set in ascending element order, sorted according to the natural ordering of its elements (only supported for Number, String, Date, Money and Quantity), or by a comparator provided at sorted set creation time.                                                                                                                                                                                                                                                                                                                                              |
| [StringUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.StringUtils.md)                 | String utility class.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [Template](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.Template.md)                       | Reads an ISML template from the file system and renders it into a [MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md) object.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [UUIDUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.util.UUIDUtils.md)                     | Utility methods around generating unique IDs.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

<!-- document id=952bfa0211ae3630dccf42af3063b480cfcb103dedcfa17f83a41abac37066f9 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.value.md -->

# Package dw.value

## Classes

| Class                                          | Description                                                        |
| ---------------------------------------------- | ------------------------------------------------------------------ |
| [EnumValue](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.EnumValue.md)             | The class represents a single value for an Enumeration type.       |
| [MimeEncodedText](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.MimeEncodedText.md) | Container for an arbitrary text string its mime type, and encoding |
| [Money](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Money.md)                     | Represents money in Commerce Cloud Digital.                        |
| [Quantity](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.value.Quantity.md)               | Represents the quantity of an item.                                |

<!-- document id=958a9491b0fd1d96bec3d6cfd6642227e9b5aed2fff47b94d4570af9bfc31a40 url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.web.md -->

# Package dw.web

## Classes

| Class                                                                | Description                                                                                                                                                                  |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ClickStream](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStream.md)                                 | Represents the click stream in the session.                                                                                                                                  |
| [ClickStreamEntry](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.ClickStreamEntry.md)                       | Represent an entry in the click stream.                                                                                                                                      |
| [Cookie](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookie.md)                                           | Represents an HTTP cookie used for storing information on a client browser.                                                                                                  |
| [Cookies](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Cookies.md)                                         | The class provides an index and associative array like access to the Cookies of the current request.                                                                         |
| [CSRFProtection](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.CSRFProtection.md)                           | Used to generate and validate CSRF tokens.                                                                                                                                   |
| [Form](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Form.md)                                               | The class is the top level element in the form instance hierachy.                                                                                                            |
| [FormAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormAction.md)                                   | The FormAction class represents the action in form instance hierarchy.                                                                                                       |
| [FormElement](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElement.md)                                 | Represents a form element.                                                                                                                                                   |
| [FormElementValidationResult](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormElementValidationResult.md) | Represents a form element validation result.                                                                                                                                 |
| [FormField](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormField.md)                                     | Represents a field in a form.                                                                                                                                                |
| [FormFieldOption](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOption.md)                         | Represents an option for a form field.                                                                                                                                       |
| [FormFieldOptions](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormFieldOptions.md)                       | The class represents the list of options for a field.                                                                                                                        |
| [FormGroup](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormGroup.md)                                     | The class is the central class within the whole form handling.                                                                                                               |
| [FormList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormList.md)                                       | Represents a list of forms.                                                                                                                                                  |
| [FormListItem](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.FormListItem.md)                               | Represents an item in a form list.                                                                                                                                           |
| [Forms](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Forms.md)                                             | The Forms object provides access to all current forms in the session.                                                                                                        |
| [HttpParameter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameter.md)                             | Represents an HTTP parameter.                                                                                                                                                |
| [HttpParameterMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.HttpParameterMap.md)                       | A map of HTTP parameters.                                                                                                                                                    |
| [LoopIterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.LoopIterator.md)                               | Iterator used in <ISLOOP> implementation.                                                                                                                                    |
| [PageMetaData](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaData.md)                               | Contains meta data about the page.                                                                                                                                           |
| [PageMetaTag](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PageMetaTag.md)                                 | Page meta tags are used in HTML documents to provide structured data about a web page.                                                                                       |
| [PagingModel](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.PagingModel.md)                                 | A page model is a helper class to apply a pages to a collection of elements or an iterator of elements and supports creating URLs for continued paging through the elements. |
| [Resource](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.Resource.md)                                       | Library class which provides methods for retrieving messages from properties resource bundles which contain locale-specific strings.                                         |
| [URL](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URL.md)                                                 | Represents a URL in Commerce Cloud Digital.                                                                                                                                  |
| [URLAction](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLAction.md)                                     | The class is needed for the URL creation within template processing.                                                                                                         |
| [URLParameter](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLParameter.md)                               | This class represents a key-value-pair for URL parameters.                                                                                                                   |
| [URLRedirect](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirect.md)                                 | Represents a URLRedirect in Commerce Cloud Digital.                                                                                                                          |
| [URLRedirectMgr](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLRedirectMgr.md)                           | URLRedirect manager class.                                                                                                                                                   |
| [URLUtils](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.web.URLUtils.md)                                       | URL utility class.                                                                                                                                                           |

<!-- document id=e0fb48a612d3bcf8059ccd610a5cda5ed839b4cd2128ce76fa97503d9d125f0d url=/developer/current/en-us/commerce-cloud/script-api/references/current/dw.ws.md -->

# Package dw.ws

## Classes

| Class                                   | Description                                                                                                                 |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [Port](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.Port.md)                   | This class represents a port to a Service Endpoint Interface.                                                               |
| [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md) | Represents a web service defined in a WSDL file.                                                                            |
| [WSUtil](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WSUtil.md)               | A utility class for performing SOAP-based operations for Web Services for use with [WebReference2](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.ws.WebReference2.md). |

<!-- document id=99b1a4494a12564b4510fbd029c1a7bbd656261f20d3d9450cd966ca1019837d url=/developer/current/en-us/commerce-cloud/script-api/references/current/TopLevel.md -->

# Package TopLevel

## Classes

| Class                                              | Description                                                                                                                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [APIException](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.APIException.md)           | This error indicates an exceptional outcome of some business logic.                                                                                                                               |
| [arguments](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.arguments.md)                 | The arguments of a function.                                                                                                                                                                      |
| [Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Array.md)                         | An Array of items.                                                                                                                                                                                |
| [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md)             | The ArrayBuffer represents a generic array of bytes with fixed length.                                                                                                                            |
| [BigInt](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.BigInt.md)                       | A BigInt object is a wrapper for a primitive `bigint` value.                                                                                                                                      |
| [Boolean](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Boolean.md)                     | Provides support for boolean values.                                                                                                                                                              |
| [ConversionError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ConversionError.md)     | Represents a conversion error.                                                                                                                                                                    |
| [DataView](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.DataView.md)                   | The DataView provides low level access to [ArrayBuffer](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ArrayBuffer.md).                                                                                                                 |
| [Date](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Date.md)                           | A Date object contains a number indicating a particular instant in time to within a millisecond.                                                                                                  |
| [Error](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Error.md)                         | Error represents a generic exception.                                                                                                                                                             |
| [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md)             | This isn't a built-in type.                                                                                                                                                                       |
| [EvalError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.EvalError.md)                 | Represents an evaluation error.                                                                                                                                                                   |
| [Fault](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Fault.md)                         | This error indicates an RPC related error in the system.                                                                                                                                          |
| [Float32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float32Array.md)           | An optimized array to store 32-bit floating point numbers.                                                                                                                                        |
| [Float64Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Float64Array.md)           | An optimized array to store 64-bit floating point numbers.                                                                                                                                        |
| [Function](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Function.md)                   | The Function class represent a JavaScript function.                                                                                                                                               |
| [Generator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Generator.md)                 | A generator is a special type of function that works as a factory for iterators and it allows you to define an iterative algorithm by writing a single function which can maintain its own state. |
| [global](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md)                       | The global object is a pre-defined object that serves as a placeholder for the global properties and functions of JavaScript.                                                                     |
| [Int16Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int16Array.md)               | An optimized array to store 16-bit signed integer numbers.                                                                                                                                        |
| [Int32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int32Array.md)               | An optimized array to store 32-bit signed integer numbers.                                                                                                                                        |
| [Int8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Int8Array.md)                 | An optimized array to store 8-bit signed integer numbers.                                                                                                                                         |
| [InternalError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.InternalError.md)         | Represents the an internal error.                                                                                                                                                                 |
| [IOError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.IOError.md)                     | This error indicates an I/O related error in the system.                                                                                                                                          |
| [Iterable](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterable.md)                   | All objects containing the property @@iterator with a function returning an [ES6Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ES6Iterator.md) are said to be an Iterable.                                                    |
| [Iterator](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Iterator.md)                   | An Iterator is a special object that lets you access items from a collection one at a time, while keeping track of its current position within that sequence.                                     |
| [JSON](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.JSON.md)                           | The JSON object is a single object that contains two functions, parse and stringify, that are used to parse and construct JSON texts.                                                             |
| [Map](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Map.md)                             | Map objects are collections of key/value pairs where both the keys and values may be arbitrary ECMAScript language values.                                                                        |
| [Math](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Math.md)                           | Mathematical functions and constants.                                                                                                                                                             |
| [Module](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Module.md)                       | CommonJS modules are JavaScript files that are loaded using the [require(String)](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.global.md#requirestring) function.                                                                     |
| [Namespace](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Namespace.md)                 | Namespace objects represent XML namespaces and provide an association between a namespace prefix and a Unique Resource Identifier (URI).                                                          |
| [Number](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Number.md)                       | A Number object represents any numerical value, whether it is an integer or floating-point number.                                                                                                |
| [Object](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Object.md)                       | The _Object_ object is the foundation of all native JavaScript objects.                                                                                                                           |
| [QName](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.QName.md)                         | QName objects are used to represent qualified names of XML elements and attributes.                                                                                                               |
| [RangeError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RangeError.md)               | Represents a range error.                                                                                                                                                                         |
| [ReferenceError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.ReferenceError.md)       | Represents a reference error.                                                                                                                                                                     |
| [RegExp](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.RegExp.md)                       | The RegExp object is a static object that generates instances of a regular expression for pattern matching and monitors all regular expressions in the current window or frame.                   |
| [Set](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Set.md)                             | A Set can store any kind of element and ensures that no duplicates exist.                                                                                                                         |
| [StopIteration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.StopIteration.md)         | A special type of exception that is thrown when an Iterator or Generator sequence is exhausted.                                                                                                   |
| [String](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.String.md)                       | The String object represents any sequence of zero or more characters that are to be treated strictly as text.                                                                                     |
| [Symbol](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Symbol.md)                       | Symbol is a primitive data type that can serve as object properties.                                                                                                                              |
| [SyntaxError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.SyntaxError.md)             | Represents a syntax error.                                                                                                                                                                        |
| [SystemError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.SystemError.md)             | This error indicates an error in the system, which doesn't fall into any of the other error categories like for example IOError.                                                                  |
| [TypeError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.TypeError.md)                 | Represents a type error.                                                                                                                                                                          |
| [Uint16Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint16Array.md)             | An optimized array to store 16-bit unsigned integer numbers.                                                                                                                                      |
| [Uint32Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint32Array.md)             | An optimized array to store 32-bit unsigned integer numbers.                                                                                                                                      |
| [Uint8Array](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8Array.md)               | An optimized array to store 8-bit unsigned integer numbers.                                                                                                                                       |
| [Uint8ClampedArray](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.Uint8ClampedArray.md) | An optimized array to store 8-bit unsigned integer numbers.                                                                                                                                       |
| [URIError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.URIError.md)                   | Represents a URI error.                                                                                                                                                                           |
| [WeakMap](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakMap.md)                     | The WeakMap is map whose entries are subject to garbage collection if there are no more references to the keys.                                                                                   |
| [WeakSet](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.WeakSet.md)                     | The WeakSet is set whose elements are subject to garbage collection if there are no more references to the elements.                                                                              |
| [XML](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XML.md)                             | The XML object contains functions and properties for working with XML instances.                                                                                                                  |
| [XMLList](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLList.md)                     | An XMLList object is an ordered collection of properties.                                                                                                                                         |
| [XMLStreamError](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/TopLevel.XMLStreamError.md)       | This error indicates an XML streaming related error in the system.                                                                                                                                |

<!-- document id=192d462e898ee346368cdf740d69ffccca09f7997f693b080f9fd5390a94b98e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/packaging.md -->

# Packaging Your Commerce App

Package your Commerce App into a CAP (Commerce App Package) for distribution.

## CAP Structure Requirements

Your packaged Commerce App must conform to the CAP structure defined in [Architecture Overview](/docs/commerce/b2c-commerce/guide/architecture.md#commerce-app-package-cap-structure). The ZIP must contain a single root directory named `commerce-{app-name}-app-v{version}/` and contain only the recognized subdirectories.

## Required Files

- `commerce-app.json` at the root of the package (see [commerce-app.json Schema](/docs/commerce/b2c-commerce/guide/reference.md#commerce-appjson-schema))
- `README.md` at the root of the package
- `app-configuration/tasksList.json` defining the setup wizard
- `icons/` directory with at least one icon file named `{isv-name}.{ext}` (PNG, SVG, JPG, or JPEG)
- At least one of: `cartridges/` (back-end logic), `storefront-next/` (frontend extensions), or `impex/` (configuration data)

## Optional Files

- `app-configuration/adminComponents.json` — declares Business Manager admin UI components shown to merchants after install. Use this to ship `storefrontComponentVisibility` toggles that let merchants enable or disable individual UI targets. See [adminComponents.json Schema](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reference.md#admincomponentsjson-schema) for the field reference and a complete example.
- `app-configuration/translations/<locale>.json` — localized strings for `tasksList.json` and (when shipped) `adminComponents.json`. See [App-shipped string localization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reference.md#app-shipped-string-localization).

## The tasksList.json

This file defines the post-install configuration steps that appear in the Business Manager setup wizard. Each task has a stable `taskKey`, a task number, name, description, a deep link to the relevant BM page, and an initial status. The `taskKey` must be a unique snake_case identifier (matching `^[a-z][a-z0-9_]*$`); locale files reference it to translate the `name` and `description` fields. See [App-shipped string localization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reference.md#app-shipped-string-localization).

Example:

```json
[
  {
    "taskKey": "enable_tax_service",
    "taskNumber": 1,
    "name": "Enable Tax Service",
    "description": "Navigate to Site Preferences and enable the tax calculation service",
    "link": "/on/demandware.store/Sites-Site/default/ViewApplication-BM?..."
  },
  {
    "taskKey": "configure_api_credentials",
    "taskNumber": 2,
    "name": "Configure API Credentials",
    "description": "Enter your account ID and license key in site preferences",
    "link": "/on/demandware.store/Sites-Site/default/ViewApplication-BM?..."
  }
]
```

## Localizing app-shipped strings

To render `tasksList.json` and `adminComponents.json` strings in additional locales, ship locale files under `app-configuration/translations/`. Each locale file uses two reserved top-level namespaces — `tasks` (keyed by `taskKey`) and `adminComponents` (keyed by `componentKey`) — and Business Manager falls back to literal English when no translation is shipped. `en-US.json` is required if the directory exists. See [App-shipped string localization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reference.md#app-shipped-string-localization) for the full schema, supported locales, fallback chain, and CI validation rules.

## IMPEX Structure

The `impex/` directory contains site-scoped XML organized into `install/` and `uninstall/` subdirectories. The `install/` directory is processed during app installation; the `uninstall/` directory during removal.

Within `install/`, use standard Commerce Cloud IMPEX conventions:

- `jobs.xml` for job definitions
- `services.xml` for service credentials, profiles, and definitions
- `meta/system-objecttype-extensions.xml` for system object attribute extensions
- `meta/custom-objecttype-definitions.xml` for custom object type definitions
- `sites/SITEID/preferences.xml` for site preferences

### Placeholder Replacement

The install job automatically replaces `SITEID` and `LIBRARYID` placeholders in both **file paths** and **file content** during processing. Placeholder replacement applies to the following text file types: `.xml`, `.csv`, `.txt`, `.json`, `.properties`, `.js`. Binary files are copied as-is without replacement.

- Use `SITEID` in directory paths (for example, `sites/SITEID/preferences.xml`) and inside XML content for site-scoped data.
- Use `LIBRARYID` for content library references. The library ID is resolved from the target site's content library at install time.
- Empty text files are skipped during processing.

**Example placeholder usage in `preferences.xml`:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<preferences xmlns="http://www.demandware.com/xml/impex/preferences/2007-12-31">
    <custom-preferences>
        <custom-preference preference-id="myAppEnabled"
            site-id="SITEID">true</custom-preference>
    </custom-preferences>
</preferences>
```

### Install IMPEX

Install IMPEX files are processed via Site Import in **merge mode**, meaning they add or update data without deleting existing resources. Use placeholder credentials in service definitions — merchants configure real credentials during the post-install setup tasks.

**Example `impex/install/services.xml`:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<services xmlns="http://www.demandware.com/xml/impex/services/2014-09-26">
    <service-credential service-credential-id="myapp.api.cred">
        <url>https://api.example.com</url>
        <user-id>YOUR_API_KEY</user-id>
        <password>YOUR_API_SECRET</password>
    </service-credential>
    <service-profile service-profile-id="myapp.api.profile">
        <timeout-millis>5000</timeout-millis>
        <rate-limit-enabled>true</rate-limit-enabled>
        <rate-limit-calls>10</rate-limit-calls>
        <rate-limit-millis>1000</rate-limit-millis>
    </service-profile>
    <service service-id="myapp.api">
        <service-type>HTTP</service-type>
        <enabled-flag>true</enabled-flag>
        <service-credential service-credential-id="myapp.api.cred"/>
        <service-profile service-profile-id="myapp.api.profile"/>
    </service>
</services>
```

> **Important:** Use dotted notation for service IDs (for example, `myapp.api`) and camelCase with an app prefix for attribute IDs (for example, `myAppEnabled`). Don't hardcode production credentials.

### Uninstall IMPEX

The `impex/uninstall/` directory contains XML files that clean up resources when the app is removed. Use `mode="delete"` in uninstall IMPEX files to remove services, profiles, and credentials.

During installation, the platform serializes the contents of `impex/uninstall/` and persists them in the `CommerceFeatureState` record. At uninstall time, the platform reconstructs these files from persisted state — **the original CAP archive isn't needed for uninstall**.

**Deletion order matters:** Delete in this order to respect foreign key relationships: credential → profile → service.

**Example `impex/uninstall/services.xml`:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<services xmlns="http://www.demandware.com/xml/impex/services/2014-09-26">
    <service-credential service-credential-id="myapp.api.cred" mode="delete"/>
    <service-profile service-profile-id="myapp.api.profile" mode="delete"/>
    <service service-id="myapp.api" mode="delete"/>
</services>
```

> **Note:** Uninstall IMPEX only runs when the last site uninstalls the app, because services and custom object definitions are instance-scoped resources shared across all sites. See [Multi-Site Behavior](/docs/commerce/b2c-commerce/guide/reference.md#multi-site-behavior) for details.

### Naming Conventions

| Resource          | Convention                | Example                   |
| :---------------- | :------------------------ | :------------------------ |
| Service IDs       | Dotted notation           | `avalara.tax.api`         |
| Attribute IDs     | camelCase with app prefix | `avalaraTaxEnabled`       |
| Custom object IDs | camelCase with app prefix | `avalaraTaxConfig`        |
| Credential IDs    | Dotted notation           | `avalara.tax.api.cred`    |
| Profile IDs       | Dotted notation           | `avalara.tax.api.profile` |

## Packaging and Validation Workflow

### Using Claude Code Skills (Recommended)

The Commerce Apps repository includes Claude Code skills that automate packaging and validation. See the full skill catalog in [Development Environment Setup — Claude Code Skills](/docs/commerce/b2c-commerce/guide/development-environment.md#claude-code-skills).

**Typical packaging workflow:**

1. `/scaffold-app` — Generate initial app structure
2. Build your app code and logic
3. `/generate-service-impex`, `/generate-site-preferences-impex` — Generate IMPEX files
4. `/validate-impex` — Validate IMPEX files during development
5. `/package-app` — Package app into ZIP
6. `/validate-app` — Comprehensive package validation
7. **ISVs only:** `/submit-pr` — Submit to the registry (targets the appropriate release branch, such as `release/26.8`)

### Manual Workflow

If you aren't using Claude Code, follow these steps:

1. Organize your project into the CAP directory structure.

2. Ensure `commerce-app.json` fields (`id`, `version`, `domain`) describe the package. For an ISV registry update, ensure they match the App Registry root manifest entry.

3. Run `b2c cap validate` to verify basic manifest fields and CAP structure. Validate IMPEX content separately.

4. Run `b2c cap package` to produce the `.zip` artifact. The ZIP must contain a single root directory: `commerce-{app-name}-app-v{version}/`.

5. Verify the ZIP contains no junk files (`.DS_Store`, `__MACOSX`, hidden files). Use exclusion flags when creating the ZIP manually:

   ```bash
   zip -r my-app-v1.0.0.zip commerce-my-app-app-v1.0.0/ \
     -x "*.DS_Store" -x "__MACOSX/*" -x "*/.*" -x "Thumbs.db"
   ```

6. Compute the SHA256 hash. For a registry submission, verify it matches the root manifest:

   ```bash
   shasum -a 256 my-app-v1.0.0.zip
   ```

7. Test the packaged `.zip` on a sandbox before distribution.

8. **ISVs only:** Open a pull request against the appropriate release branch in the App Registry (for example, `release/26.8` or `release/26.9`). Do **not** target `main` — submissions must target a release branch. Private apps skip this step.

<!-- document id=bdac0eaac38af2ba6676adea2398aa86097d36b132330bb10b72f18e4d2fedcb url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/page-designer/b2c-dev-for-page-designer.md -->

# Page Designer

Developers create page types and component types. Merchants then use these types to create Page Designer pages in the visual editor in Business Manager.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Developing for Page Designer

Developers play an important role in implementing Page Designer. Developers work with the ecommerce marketing director to determine the pages, components, layouts, and assets required for the storefront. The developer then creates and uploads custom cartridges. These cartridges contain reusable page types, component types, and visual editor artifacts that help merchants quickly create custom pages.

### What Is Page Designer?

Page Designer is a B2C Commerce feature that supports standard development processes and tools for creating reusable page types and component types. Merchants use a visual editor in Business Manager to design, schedule, and publish custom storefront pages. They create pages by dragging page and component types on to the canvas. Merchants can use the same page and component types to create various pages independently, without going back to the developer for updates. This topic applies to B2C Commerce.

The typical Page Designer implementation process includes these steps.

- The ecommerce marketing director meets with the developer to discuss the pages, components, layouts, and assets required for the storefront.
- The developer creates the reusable page types and component types that support the ecommerce marketing director's requirements.
- The developer uploads two custom cartridges to a site: one containing page and component types, and another containing supporting UI artifacts.
- The merchant uses the Page Designer visual editor in Business Manager to build storefront pages. They use the page and component types that the developer implemented.

### Get the Page Designer Reference Examples

We provide example page types and component types to help you quickly get started with Page Designer.

1.  If you don’t have a GitHub account, see [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-github-repo-access.md).

2.  Search for the `storefront-reference-architecture` or `page-designer-reference` repository.

    - Storefront Reference Architecture (SFRA) includes Page Designer page types and component types optimized for use with SFRA. The latest version of SFRA is in the [SFRA repository](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture).
    - Page Designer reference cartridges for SiteGenesis are in the [SiteGenesis repository](https://github.com/SalesforceCommerceCloud/page-designer-reference).

3.  Click **Clone or download** to copy the repository to your local system.

4.  If you downloaded the repository, expand the .zip file.

    **note:** On macOS, use the command-line **unzip** utility to expand the files.

    For information about how to get started with the SiteGenesis page-designer-reference repository, see [SiteGenesis README](https://github.com/SalesforceCommerceCloud/page-designer-reference/blob/master/README.md).

    For details about the Page Designer example pages and components for the SiteGenesis page-designer-reference repository, see [SiteGenesis Implementation Guide](https://github.com/SalesforceCommerceCloud/page-designer-reference/blob/master/documentation/Implementation.md).

### Page Designer Development Recommendations

In addition to following standard B2C Commerce development guidelines, follow these Page Designer-specific recommendations.

- Do as much planning and requirements gathering upfront as possible. Work with the merchant and ecommerce director before developing page types and component types.
- Create self-contained components so any region can handle them as independent units. To support self-containment, give each component its own default styling, although at times you can adjust the styling by specifying custom render settings.
- Be careful when changing meta definitions after merchants have created page and component instances. Don't make incompatible changes. For example, changing the `type` value for a component attribute creates an inconsistency between the meta definition and database data. In this case, create a component type and deprecate the old one.
- For sites that share libraries, assign the same data and the same set of cartridges with the same set of page and component types to each site. Sharing data and code makes sure that there aren’t inconsistencies between meta definitions and data. For example, you can have a page that was known in one site but not another, or two sites that use the same ID for different component types with different sets of attributes, which would result in validation errors. Keep in mind that data and code are shared with different mechanisms that can have multiple relationships to sites, as follows:

  | Entity        | Can Be Assigned To |
  | ------------- | ------------------ |
  | Cartridge     | 1...n sites        |
  | Library       | 1...n sites        |
  | Content Asset | 1 library          |
  | Page          | 1 library          |
  | Component     | 1 library          |
  | Catalog       | 1...n sites        |

- Implement anchor tags on your Page Designer pages.

  For example, you can build a page with anchors to each section. You can also create a component at the top with images or links that anchor to sections below. Follow these steps:

  1.  In each component, use a string attribute that defines a tag.

      `<a name="string_attribute_value"/>`

  2.  When creating the links, reference the tag.

      `<a href="#string_attribute_value">Link to the string_attribute_value section</a>`

- Dynamically pull a profile attribute into a Page Designer component.

  For example, to display `firstName` or `companyName` in a component on the homepage after a customer logs in, such as "Welcome back, {firstName}", use:

  `Request.getSession().getCustomer()` .

  **note:** Be sure it isn't cached.

- Duplicate a Page Designer page to a new library.

  Using the Shared Library Page Designer, pages are automatically duplicated within the shared library. They’re also created offline allowing the merchandiser to determine if the page is available within the other locations.

- Caching for Page Designer pages is similar to other pages. For more information, see [Page Caching](#page-caching).
- Check the Page Designer page cache time to live.

  There’s no Page Designer-owned cache time to live, only what the customer developers set in their scripts. Use the "cache information" tool in SFTK to check how long a given page is cached. Select the top or page level cache icon, and look for a remote include of the pipeline "Internal - Page Designer".

### Page Designer General Troubleshooting

The following tips have been found to quickly discover and help solve many common errors.

- Refer to the browser developer console to determine if there are errors shown.
  - Check for general javascript errors, induced by either the storefront itself or Page Designer.
  - Check the network tab in the browser console and monitor the XHR requests (for example, see any API request going back and forth).
- Refer to the server logs to determine if there are errors shown.
  - In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup**.
  - Browse the log files checking especially the error logs for any related entries, such as script exceptions.
- Work within Page Designer Optimal Performance.

  Page Designer Pages within Business Manager aren’t cached allowing Content Editors and Merchandisers to see their updates immediately. For optimal performance, we recommend you make sure the nesting within components is kept to 5 or under.

- If you’re experiencing a 'Service Unavailable Error - 500', this is _not_ a Page Designer specific issue. Check the error logs to determine the issue.

### Optimal Page Performance

Page caching is skipped in Page Designer editing or previewing mode. This makes changes immediately visible to the user. In the plain storefront, customer page cache instrumentations apply as coded. Slow rendering typically results from the page not being cached yet or a low-performing page implementation.

For slow performing pages, we recommend you check to see if the implementation has to be revised:

- In the storefront, use the Storefront Toolkit.
- Enable the Cache Info tool.
- Look for the cache symbol for pipeline “Internal - Page Designer”, and check its caching status.

For uncached occurrences that must be revisited for an implementation change, we recommend you:

- Use page caching unless it’s ultimately necessary to not cache the given page. See [Page Caching](#page-caching) for more information.
- Refactor the business logic of the page avoiding costly operations, or mass amounts of operations, during one request.

## Create Page and Component Types

To implement page types and component types, you must include a meta definition file and a script file for each page type and component type in a custom cartridge.

### Page Designer Meta Definition Files

Each page type and component type requires a JSON meta definition file. For page types, the file describes regions where merchants can place components. For component types, the file describes merchant-configurable attributes and can also define regions.

Put the meta definition file in one of the following directories of the custom cartridge, or any arbitrary subdirectory within these directories:

- Page types: `{your_cartridge}/cartridge/experience/pages`
- Component types: `{your_cartridge}/cartridge/experience/components`

The meta definition file name can include only alphanumeric or underscore characters. If you use a subdirectory within `/experience/pages` or `/experience/components`, subdirectory names must also use only alphanumeric or underscore characters.

To view schema files that describe the JSON formatting for the meta definition file, see [Page Designer JSON Schemas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/content/).

## Page Designer and Storefront Next

Storefront Next is a modern headless storefront built with React and React Router. For Storefront Next storefronts, you can use Page Designer to build pages and components as React components instead of as ISML templates.

Here are the key features of Page Designer in Storefront Next.

- **React Components with Decorators**: In Storefront Next, you can build Page Designer components as React components decorated with metadata using TypeScript decorators (`@Component`, `@AttributeDefinition`, `@RegionDefinition`).
- **Automatic Cartridge Generation**: The build process automatically generates B2C Commerce cartridge metadata from your decorated components.
- **File-Based Routing**: Page routes are automatically extracted from your file-based routing structure (for example, `src/routes/category.$categoryId.tsx` → `/category/:categoryId`).
- **Component Loaders**: Components can export data loaders for server-side or client-side data fetching, with automatic Promise resolution.

To build and deploy Page Designer pages and components:

1. **Define Components**: Create React components with decorators that define attributes, regions, and metadata.
2. **Build**: Run `pnpm build` to automatically generate cartridge JSON metadata from decorators.
3. **Deploy**: Push the generated cartridge to B2C Commerce and deploy the storefront to Managed Runtime.
4. **Configure**: Merchants use the Page Designer visual editor in Business Manager to build pages using your components.

For details about using Page Designer with Storefront Next, including component patterns, loaders, regions, and deployment, see [Page Designer Integration with Storefront Next](https://developer.salesforce.com/docs/sfnext/guides/sfnext-page-designer.md).

## Page Designer and PWA Kit

For PWA Kit implementations, you can create pages and components that render using React instead of ISML. This requires two additional fields in your meta definition files:

**note:** For PWA Kit storefronts, Page Designer works only for pages deployed to Managed Runtime (MRT) with the corresponding Business Manager configuration. You must configure your MRT URL in Business Manager under **Administration** > **Sites** > **Manage Sites** > **Your Site** > **MRT Configuration**.

**`arch_type` field:**

- Set to `"headless"` for PWA Kit React-only rendering (no ISML required)
- Set to `"controller"` or omit for traditional ISML rendering
- Enables hybrid storefronts with both ISML and headless pages, supporting incremental migration
- When set to `"headless"`, custom JavaScript in Page Designer metadata is NOT executed—all logic must be in your React components

**`route` field (pages only):**

- Specifies the URL path where the page is accessible (e.g., `"/"` for homepage, `"/about"` for about page)
- Page Designer uses this route to load your PWA Kit storefront in edit mode
- Supports dynamic routes with parameters (e.g., `"/product/:productId"`, `"/category/:categoryId"`)
- Route parameters must match the attribute IDs defined in the page's aspect type

**Example headless page:**

```json
{
    "name": "Home Page",
    "description": "Main landing page",
    "arch_type": "headless",
    "route": "/",
    "region_definitions": [...]
}
```

**Example headless component:**

```json
{
    "name": "Content Card",
    "description": "Flexible card component",
    "group": "commerce_assets",
    "arch_type": "headless",
    "region_definitions": [],
    "attribute_definition_groups": [...]
}
```

For more information about using Page Designer with PWA Kit, see [Page Designer for PWA Kit](https://developer.salesforce.com/docs/pwa-kit-managed-runtime/guides/page-designer.md).

#### Example: Traditional ISML Page

This example promotion page type meta definition file, named `promopage.json`, defines three regions for the promotions page: header, main, and footer. The header and footer regions can display only one component at a time, as specified by `max_components = 1`. The `region_definition` for the main region doesn’t include a `max_components` value, indicating that the main region can display any number of components. The main region uses `component_type_exclusion` to specify that components of type banner aren’t allowed in the main region.

The `max_components` value restricts the number of components _rendered_ for a region at a time, but the region can contain any number of components. Therefore, display different components for different customers or on different schedules. For example, you could have a banner region that displays one component in winter and a different component in summer.

```json
{
    "name":"Promopage",
    "description":"A promotional page.",
    "region_definitions":[
      {
        "id":"header",
        "name":"Name",
        "description":"Header of the promopage",
		"max_components":1
      },
      {
        "id":"main",
        "name":"Main",
        "description":"Main area of the promopage",
        "component_type_exclusions":[
           {"type_id":"banner"}
        ]
      },
      {
        "id":"footer",
        "name":"Footer",
        "description":"Footer of the promopage",
        "max_components":1
      }
    ]
}
```

This example banner component meta definition file (`banner.json`) defines four merchant-configurable attributes: image file, alt text, size, and Magic Unicorns. The Magic Unicorns attribute uses a custom UI control (`com.sfcc.magical`) to let merchants select a unicorn. In the visual editor, attributes appear in groups. These four attributes appear in a group labeled _Banner Image Configuration._

The `default_value` setting for an attribute is used only for rendering the page in the storefront or previewing in the visual editor. The `default_value` isn’t shown as preselected in the visual editor that the merchant uses to configure the component. Rendering behavior based on settings for `required` and `default_value` is as follows:

- **`Required` is true and a `default_value` is configured**: The `default_value` is assigned to the attribute for rendering the page, but isn’t shown as preselected in the visual editor. If the merchant doesn’t configure a value for the attribute and saves the component, no error message is presented.
- **`Required` is false and a `default_value` is configured**: The `default_value` is assigned to the attribute for rendering the page, but isn’t shown as preselected in the visual editor. If the merchant doesn’t configure a value for the attribute and saves the component, no error message is presented.
- **`Required` is true and no `default_value` is configured**: If the merchant doesn’t configure a value for the attribute and saves the component, an error message is presented.
- **`Required` is false and no `default_value` is configured**: If the merchant doesn’t configure a value for the attribute and saves the component, no error message is presented.

```json
{
  "name": "Banner",
  "description": "A banner.",
  "group": "content",
  "attribute_definition_groups": [
    {
      "id": "image",
      "name": "Banner Image Configuration",
      "description": "You can define the image file, size and alt text for the banner image.",
      "attribute_definitions": [
        {
          "id": "image",
          "name": "Banner Image",
          "description": "The image shown by the banner.",
          "type": "file",
          "required": true
        },
        {
          "id": "alt",
          "name": "Banner Image Alt Text",
          "description": "The image alt text shown by the banner.",
          "type": "string",
          "required": false
        },
        {
          "id": "size",
          "name": "Size",
          "description": "The banner size.",
          "type": "enum",
          "values": [
            "small",
            "medium",
            "large"
          ],
          "required": true,
          "default_value": "medium"
        },
        {
          "id": "magic",
          "name": "Magic Unicorns",
          "type": "custom",
          "required": true,
          "editor_definition": {
            "type": "com.sfcc.magical",
            "configuration": {
              "options": {
                "config": [
                  "Auris",
                  "Chant",
                  "Elmas",
                  "Majesty",
                  "Moriba",
                  "Mystery",
                  "Mystic",
                  "Snowflake",
                  "Solstice",
                  "Sunshine"
                ]
              }
            }
          }
        }
      ],
      "region_definitions": []
    }
  ]
}
```

The `3column.json` meta definition file is for a component type that represents a layout of three columns. Each column is a region in the meta definition file.

```json
{
  "name": "1 Row, 3 Column, Landscape",
  "group": "layouts",
  "attribute_definition_groups": [],
  "region_definitions": [
      {
        "id":"column1",
        "name":"Column 1",
        "max_components":1
      },
      {
        "id":"column2",
        "name":"Column 2",
        "max_components":1
      },
      {
        "id":"column3",
        "name":"Column 3",
        "max_components":1
      }
  ]
}
```

### Page-Level Custom Attributes

Define custom page-level attributes for a page type. For example, define custom attributes for title, Image, and Description. Merchants can use those attributes to specify the image and text that appears in the search results for a page.

Define the page-level attributes in the meta definition file for the page type. This example shows three attributes defined for a Search Results Title, Search Results Image, and Search Results Description.

```json
{
	"name": "Promopage",
	"description": "A promotional page.",

	"attribute_definition_groups": [{
		"id": "search",
		"name": "Search Results Display",
		"description": "Define the title, image, and description returned in search results for the page.",
		"attribute_definitions": [{
				"id": "title",
				"name": "Search Results Title",
				"description": "The page title displayed in search results.",
				"type": "text",
				"required": false
			},
			{
				"id": "image",
				"name": "Search Results Image",
				"description": "The image displayed in search results.",
				"type": "file",
				"required": false
			},
			{
				"id": "description",
				"name": "Search Results Description",
				"description": "The page description displayed in search results.",
				"type": "text",
				"required": false,
			}
		],
		"region_definitions": [{
				"id": "header",
				"name": "Name",
				"description": "Header of the promopage",
				"max_components": 1
			},
			{
				"id": "main",
				"name": "Main",
				"description": "Main area of the promopage",
				"component_type_exclusions": [{
					"type_id": "banner"
				}]
			},
			{
				"id": "footer",
				"name": "Footer",
				"description": "Footer of the promopage",
				"max_components": 1
			}
		]
	}]
}
```

### Initialize a Region with a Component Already Populated

Prepopulating a region with default components is a best practice that guides a merchant in creating a page. To specify that a region contains specific components by default, use the `default_component_constructors` property in the meta definition file for a page type. Use this property in the meta definition file for a component type that includes a region. When the merchant creates a page in the Visual Editor using the page type or component type, the default components are already populated in the region. The merchant can delete the components if necessary.

The following example specifies that the main region of the page is prepopulated with a default component. The component has id `commerce_layouts.productDetail`and name `Product Detail Layout`.

```json
{
  "name": "Product Detail Page",
  "description": "Product detail page with 3 regions",
  "region_definitions": [
    {
      "id": "top",
      "name": "Top Region",
      "component_type_exclusions": [{ "type_id": "commerce_assets.campaignBanner" }]
    },
    {
      "id": "main",
      "name": "Main Region",
      "default_component_constructors": [
        {
          "type_id": "commerce_layouts.productDetail",
          "name": "Product Detail Layout"
        }
      ],
      "component_type_exclusions": [{ "type_id": "commerce_assets.campaignBanner" }]
    },
    {
      "id": "bottom",
      "name": "Bottom Region",
      "component_type_exclusions": [{ "type_id": "commerce_assets.campaignBanner" }]
    }
  ],
  "supported_aspect_types": ["pdp"]
}
```

### Page Designer Script Files

Each page type or component type requires a corresponding script file. The script file must have the same name as the meta definition file but with a `.js` extension. For example, `promopage.json` requires a script file named `promopage.js`.

The script file name can include only alphanumeric or underscore characters. Put the script file at the same location as its meta definition file. For a component type named headlinebanner, the files would be at:

`mycartridge/cartridge/experience/components/assets/headlinebanner.json`

`mycartridge/cartridge/experience/components/assets/headlinebanner.js`

The script file must include a `render` function that returns the markup for the page. Assemble the markup using any process you want, as long as the result is a string. In many cases, the `render` function calls an ISML template to which it passes information about the page or component type and its content. If you use an ISML template, you must use the `dw.util.Template` API to render the markup from the template. Don’t use `dw.template.ISML` because it doesn't return a string, and it writes the markup to the response stream right away.

In this promotion page script file, named `promopage.js`, the context object that is passed to the `render` function is of type `dw.experience.PageScriptContext`. It provides access to:

- `context.page`—Currently rendered page
- `context.renderParameters`—Parameters passed to PageMgr.renderPage(pageID, parameters)
- `context.content`—Attributes set in the custom logic (not defined by the merchant)

```javascript
'use strict';
var Template = require('dw/util/Template');
var HashMap = require('dw/util/HashMap');

/**
 * Render logic for the page.
 */
module.exports.render = function (context) {
    var model = new HashMap();
    // add paramters to model as required for rendering based on the given context (dw.experience.PageScriptContext):
    //   * context.page (dw.experience.Page)
    //   * context.renderParameters (String)
    //   * context.content (dw.util.Map)

    return new Template('experience/pages/promopage').render(model).text;
};
```

In this banner script file, named `banner.js`, the context object that is passed to the render function is of type `dw.experience.ComponentScriptContext`. It provides access to:

- `context.component`—The currently rendered component.
- `context.componentRenderSettings`—Render settings provided by the hosting region. Optionally override these render settings that are passed in from the region with settings specific to the component.
- `context.content`—Attributes as defined in the meta definition file for the component and then configured by the merchant in the Page Designer visual editor, or as defined in the custom logic.

```javascript
'use strict';
var Template = require('dw/util/Template');
var HashMap = require('dw/util/HashMap');

/**
 * Render logic for the component.
 */
module.exports.render = function (context) {
    var model = new HashMap();
    // add paramters to model as required for rendering based on the given context (dw.experience.ComponentScriptContext):
    //   * context.component (dw.experience.Component)
    //   * context.content (dw.util.Map)

    return new Template('experience/assets/banner').render(model).text;
};
```

### Component Attribute Types and UI Controls

Each attribute in the meta definition file has an assigned type. The type determines how merchants set the value in the visual editor. For example, a `file` type displays a file selection modal for browsing library files. An `enum` type displays a single select box for choosing from allowed values.

This table describes the type options for component attributes and how those options are displayed in the Page Designer visual editor.

| Component Attribute Type | Attribute Semantics                                                | Visual Editor UI Control                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| boolean                  | Boolean                                                            | Check box                                                                                                                                                                                                                                                                                                                                |
| category                 | String representing a catalog category ID                          | Category picker                                                                                                                                                                                                                                                                                                                          |
| cms_record               | Record from the Salesforce CMS (Content Management System)         | User is presented with a modal window to select the CMS record. After the user selects the CMS record, the edit panel displays the UI controls necessary to configure the attributes of the slected CMS record.                                                                                                                          |
| custom                   | String enclosed in curly brackets {} that represents a JSON object | Text area or custom UI control                                                                                                                                                                                                                                                                                                           |
| enum                     | Enumeration of either string or integer values.                    | Select box (single select)                                                                                                                                                                                                                                                                                                               |
| file                     | String representing a file path within a library                   | File picker                                                                                                                                                                                                                                                                                                                              |
| image                    | String representing a configurable image JSON                      | Image picker that lets users select an image and specify a focal point on that image. The image dimensions are also stored and can be accessed, along with the image name and focal point, using the Image API.                                                                                                                          |
| integer                  | Integer                                                            | Input field                                                                                                                                                                                                                                                                                                                              |
| markup                   | String representing HTML markup                                    | A rich text editor that allows semantic formatting options to produce HTML markup                                                                                                                                                                                                                                                        |
| page                     | String representing a page ID                                      | Page picker                                                                                                                                                                                                                                                                                                                              |
| product                  | String representing a product SKU                                  | Product picker                                                                                                                                                                                                                                                                                                                           |
| string                   | String                                                             | Input field                                                                                                                                                                                                                                                                                                                              |
| text                     | String                                                             | Text area                                                                                                                                                                                                                                                                                                                                |
| url                      | String representing a URL                                          | URL picker                                                                                                                                                                                                                                                                                                                               |
| image                    | String representing a configurable image JSON                      | Image picker that lets users select an image and specify a focal point on that image. The image dimensions are also stored and can be accessed, along with the image name and focal point, using the [Image API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/package_dw_experience_image.html) |

### Component Attribute Types and Resolved Value Objects

The content attributes from the `context` object (the content dictionary) are defined in a map. Attribute IDs are keys, and resolved values are values. A resolved value has been converted to B2C Commerce API objects when needed. For example, a product attribute (product SKU) becomes a `dw.catalog.Product` instance. Strings don't need conversion. The following table lists content attribute types and their B2C Commerce API objects.

| Content Attribute Type | B2C Commerce API Value    |
| ---------------------- | ------------------------- |
| category               | dw.catalog.Category       |
| cms_record             | dw.experience.CMSRecord   |
| custom                 | dw.util.Map               |
| file                   | dw.content.MediaFile      |
| image                  | dw.experience.image.Image |
| page                   | dw.experience.Page        |
| product                | dw.catalog.Product        |

### Page Designer HTML

The `render` function of a page type creates the page's HTML markup. Typically, the page type's `render` function calls an ISML template that uses `PageMgr.renderRegion()` to render each region of the page.

In this example, a page calls an ISML template. This ISML template renders three regions: header, main, and footer.

```html
<html>
  ...
  <isprint value="${PageMgr.renderRegion( pdict.page.getRegion('header') )}" encoding="off" />
  ...
  <isprint value="${PageMgr.renderRegion( pdict.page.getRegion('main') )}" encoding="off" />
  ...
  <isprint value="${PageMgr.renderRegion( pdict.page.getRegion('footer') )}" encoding="off" />
  ...
</html>
```

Each `PageMgr.renderRegion()` function in the page ISML finds all assigned and visible components in each region and calls each component’s `render` function, which in turn calls its own ISML template, as in the following example:

```html
...
<img
  width="<!-- calculate it in your component controller using ${pdict.content.size} -->"
  src="${pdict.content.image.getAbsURL()}"
  alt="${pdict.content.alt}"
/>
<!--
   // if the 'assets.banner' component type had a region 'foobar' we could render it here
   <isprint value="${PageMgr.renderRegion( pdict.component.getRegion('foobar') )}" encoding="off"/>
-->
...
```

As each region and component is rendered, Page Designer creates an HTML element to wrap the content. Specify which HTML element to use as the wrapper and which attributes to assign to the wrapper using the `dw.experience.RegionRenderSettings` and `dw.experience.ComponentRenderSettings` APIs. For more information, see:

- [RegionRenderSettings API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_experience_RegionRenderSettings.html)
- [ComponentRenderSettings API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_experience_ComponentRenderSettings.html)

By default, the HTML wrapper for regions and components is `div`. The default CSS class for regions is `experience-region experience-<{region_definition_id}>`. The default CSS class for components is `experience-component experience-<{componenttype_id}>`.

**note:** Component type ID values include dots, for example, `assets.productile`. When used in the CSS class name, the dot is replaced with a hyphen, for example, `experience-component experience-assets-productile`.

For example, for a region with id my_region and three components, two of type my_component_type_1 and one of type my_component_type_2, the default HTML wrapper is:

```html
<div class="experience-region experience-my_region">
  <div class="experience-component experience-my_component_type_1">
    content of first component (type my_component_type_1) goes here
  </div>
  <div class="experience-component experience-my_component_type_1">
    content of second component (type my_component_type_1) goes here
  </div>
  <div class="experience-component experience-my_component_type_2">
    content of third component (type my_component_type_2) goes here
  </div>
</div>
```

Sometimes you want a component styled differently based on its containing region. For example, you have a product tile component with default render settings. You also have a carousel component that scrolls through other components. When the product tile appears in the carousel, you want it to use carousel-specific styling.

You could use a custom CSS class `item` for the first and second components. Then use `item active` for the third component to mark it as active. Here's the HTML wrapper for the carousel.

```html
<div class="carousel-inner">
  <div class="item">
    content of first component (type my_component_type_1) goes here
  </div>
  <div class="item">
    content of second component (type my_component_type_1) goes here
  </div>
  <div class="item active">
    content of third component (type my_component_type_2) goes here
  </div>
</div>
```

Here's the code to set the custom render settings for the carousel. You could include this code in the `render` function of the script file for the component.

**note:** The Page Designer reference implementation available in GitHub includes helper functionality to streamline this code.

```javascript
var carousel = component.getRegion("carousel");

// set styling for carousel region
var carouselRenderSettings = new dw.experience.RegionRenderSettings();
carouselRenderSettings.setTagName("div");
carouselRenderSettings.setAttributes({ class: "carousel-inner" });

// set carousel item styling (default)
var defaultCarouselComponentRenderSettings = new dw.experience.ComponentRenderSettings();
defaultCarouselComponentRenderSettings.setTagName("div");
defaultCarouselComponentRenderSettings.setAttributes({ class: "item" });
carouselRenderSettings.setDefaultComponentRenderSettings(defaultCarouselComponentRenderSettings);

// set carousel item styling (active one)
var activeCarouselComponent = carousel.visibleComponents[0]; // init the first one as being active
var activeCarouselComponentRenderSettings = new dw.experience.ComponentRenderSettings();
activeCarouselComponentRenderSettings.setTagName("div");
activeCarouselComponentRenderSettings.setAttributes({ class: "item active" });
carouselRenderSettings.setComponentRenderSettings(
  activeCarouselComponent,
  activeCarouselComponentRenderSettings,
);

// render the carousel region
return dw.experience.PageMgr.renderRegion(carousel, carouselRenderSettings);
```

### Page Type, Component Type, and Custom Attribute Editor IDs

A page type, component type, or custom attribute editor ID combines the subdirectory path and file name without extension. Separate directory levels and the file name with periods. For example, a page type named `homepage` directly under `cartridge/experience/pages` has ID `homepage`. If the files are in `storefront/campaigns` subdirectory, the ID is `storefront.campaigns.homepage`.

### Length Restrictions for Page Type and Component Type IDs

When component types and page types are persisted in the database, their IDs are prepended with the prefixes `page.` or `component.`. Those prefixes, plus the IDs of the page types and component types, can’t exceed 256 characters, or else errors occur. Adjust the file names or move the meta definition file and script file to a higher level in the directory structure to shorten the ID.

| Location of Page Type, Component Type, or Custom Control                         | ID                            |
| -------------------------------------------------------------------------------- | ----------------------------- |
| `mycartridge/cartridge/experience/components/assets/headlinebanner.json`         | assets.headlinebanner         |
| `mycartridge/cartridge/experience/components/assets/banners/headlinebanner.json` | assets.banners.headlinebanner |
| `mycartridge/cartridge/experience/pages/promopage.json`                          | promopage                     |
| `mycartridge/cartridge/experience/pages/promotions/promopage.json`               | promotions.promopage          |
| `mycartridge/cartridge/experience/editors/com/sfcc/magical.json`                 | com.sfcc.magical              |

### Using Decorators with Page Designer Pages

Implement various strategies for using decorators with Page Designer pages. For example, write the script file for a page type so that you can pass in a custom decorator as a parameter when the page is rendered, or fall back to a default decorator defined in the script. Optionally, write the controller that renders the page so that a different decorator is used based on the value of a certain condition.

In this snippet, the constant `DEFAULT_DECORATOR` defines the default decorator location. If a different decorator is passed as a parameter, it's used instead. The following line uses the passed `decorator` parameter if it exists, otherwise it uses `DEFAULT_DECORATOR`.

`model.decorator = renderParameters.decorator || DEFAULT_DECORATOR;`

```javascript
...
const DEFAULT_DECORATOR = 'decoration/styling';
...
module.exports.render = function (context) {
   var model = new HashMap();
   ...
   var renderParameters = getRenderParameters(context.renderParameters);
   model.decorator = renderParameters.decorator || DEFAULT_DECORATOR;
   return new Template('experience/pages/dynamiclayout').render(model).text;
}
```

When pages are displayed in the visual editor, the default decorator from the script file is used. To optimize page creation, define `DEFAULT_DECORATOR` to point to a lightweight decorator that loads quickly. When the controller renders the page in the storefront, pass in the full decorator location.

Choose which decorator to use based on the state of a condition. For example, in the following snippet from a storefront controller, the decorator at `decoration/ajax` is used if the format of the page is based on AJAX (Asynchronous Javascript and XML), but the decorator at `decoration/full` is used if the page isn’t based on AJAX.

```javascript
exports.Show = function () {
   var params = request.httpParameterMap;
   var cid = params.cid.stringValue;
   var format = params.format.stringValue;
   ...
   var page = PageMgr.getPage(cid);
   ...
   var params = {
   decorator: format === 'ajax' ? 'decoration/ajax' || 'decoration/full';
   };
   response.writer.print(PageMgr.renderPage(page.ID, JSON.stringify(params)));
...
}
```

### Develop a Dynamic Page

A dynamic page uses dynamic attributes passed at runtime to determine storefront content. Typically, the developer creates an aspect type for a business use (like Product List or Product Details). The developer assigns the aspect type to a page type defining the layout. The merchant creates a template page and assigns it to categories. When the storefront needs a page for an assigned category, the template displays. Content is populated based on the category dynamic attribute.

For an example of how a merchant implements a Product List or Product Details template, see [Create a Product List or Product Detail Page Template for Page Designer](https://help.salesforce.com/s/articleView?id=cc.b2c_create_plp_pdp_templates.htm).

#### Aspect Types

To implement a dynamic page, create an aspect type meta definition file. This file defines required attributes for a business use. It also defines the business object type that merchants can bind to pages. In the page type's meta definition file, specify which aspect types are supported.

To view the schema file that describes the JSON formatting for the aspect type meta definition file, see [Page Designer JSON Schemas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/content/).

Put the aspect type meta definition file in the following directory of the custom cartridge, or any arbitrary subdirectory within this directory:

`{your_cartridge}/cartridge/experience/aspects`

Valid values for `supported_object_types` are 'category' or 'product'.

Using 'category' lets merchants assign pages to categories in the Page Designer UI. Developers can retrieve them using [PageMgr.getPageByCategory](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_experience_PageMgr.html#dw_experience_PageMgr_getPageByCategory_Category_Boolean_String_DetailAnchor).

Using 'product' lets merchants assign pages to products in the UI. Developers can retrieve them using [PageMgr.getPageByProduct](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_experience_PageMgr.html#dw_experience_PageMgr_getPageByProduct_Product_Boolean_String_DetailAnchor).

Create an aspect type with no `supported_object_type` declared. For example, you could implement a Product List page that depends on the results of a query, not the assignment of a category, to determine which products to display on the page.

The 'attribute_definitions' of the aspect type define which attributes should be passed in when rendering the page using [PageMgr.renderPage](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_experience_PageMgr.html#dw_experience_PageMgr_renderPage_String_Map_String_DetailAnchor).

The following examples show aspect meta definition files for Product List and Product Detail pages. The Product List page aspect type has one category attribute and supports the category object type. The Product Detail page aspect type has product and category attributes. Both support the category object type, which merchants assign during page creation. All products in assigned categories use the Product Detail page.

```json
{
  "name": "Product List Page",
  "description": "The product list page for a given category.",
  "attribute_definitions": [
      {
          "id": "category",
          "name": "Category",
          "type": "category"
      }
  ],
  "supported_object_types": [
      "category"
  ]
}
```

```json
{
  "name": "Product Details Page",
  "description": "The product details page for a given product.",
  "attribute_definitions": [
      {
          "id": "product",
          "name": "Product",
          "description": "The product to render the pdp for.",
          "type": "product",
          "required": true
      },
      {
          "id": "breadcrumb_category",
          "name": "Breadcrumb Category",
          "description": "The optional category context of the pdp, for breadcrumb purposes.",
          "type": "category",
          "required": false
      }
  ],
  "supported_object_types": [
      "category"
  ]
}
```

Specify supported aspect types in the page definition file. This example page type supports the `plp` aspect type and requires its category attribute. The controller or script uses this category attribute to render the page.

```json
{
	"name": "Product List Page Layout",
	"description": "A layout for a product list page with a region to contain a product grid component.",
	"supported_aspect_types": [
		"plp"
	],
	"region_definitions": [{
		"id": "main",
		"name": "Main Region"
	}]
}
```

Create a page type that supports more than one aspect type. During page creation, the merchant selects which aspect type to use for the page by selecting a Page Purpose in the page creation wizard.

```json
{
	"name": "Dynamic Layout",
	"description": "A generic layout whose region can use any kind of component.",
	"supported_aspect_types": [
		"plp",
		"pdp"
	],
	"region_definitions": [{
		"id": "main",
		"name": "Main Region"
	}]
}
```

#### Components with Dynamic Attributes

A component attribute can include a `dynamic_lookup` property. The `dynamic_lookup` property specifies an attribute of the aspect. The component attribute gets its value from the aspect attribute specified.

In the following example, the component attribute named `Category` includes a`dynamic_lookup` property. The `dynamic_lookup` property specifies the aspect attribute `category`. At runtime, component attribute `Category` gets its value from aspect attribute `category`.

```json
{
  "name": "Product Listing Layout",
  "description": "Product Listing Grid Layout",
  "group": "commerce_layouts",
  "attribute_definition_groups": [
    {
      "id": "productList",
      "name": "Settings",
      "description": "Product List Settings",
      "attribute_definitions": [
        {
          "id": "category",
          "name": "Category",
          "type": "category",
          "required": false,
          "dynamic_lookup":{
              "aspect_attribute_alias": "category"
          }
        }
      ]
    },

	"region_definitions": [...]
}
```

In the Visual Editor, merchants can override the page's category and assign a different one to the component. In the SFRA reference implementation, the dynamic banner uses the page's category by default. It displays the banner image and text assigned to that category in Business Manager.

![Dynamic Banner Component showing category assigned to page](https://developer.salesforce.com/media/b2c-commerce/b2c_dyn_component.png)

The merchant can edit the category value and assign it to something other than the value the page is using. For example, the merchant can specify that the banner component uses the category mens-clothing regardless of the category assigned to the page.

![Dynamic Banner Component showing mens-clothing category](https://developer.salesforce.com/media/b2c-commerce/b2c_dyn_comp_override.png)

Merchants can also override component attributes separately from the dynamic category. For example, the banner can always display an image for women's shoes and handbags regardless of category.

![Dynamic Banner Component showing specific image](https://developer.salesforce.com/media/b2c-commerce/b2c_dyn_comp_image_override.png)

#### Render a Dynamic Page

Aspect attributes are passed to the page through the `Page.renderPage()` method that takes`aspectAttributes`.

The following code snippet passes aspect attributes to the page during rendering:

```javascript
var aspectAttributes = new HashMap();
aspectAttributes.put("category", category);
res.print(PageMgr.renderPage(page.ID, aspectAttributes, ""));
```

The following code snippet checks to see if a page is assigned to the given category for a given aspect type and returns that page. If there’s no page assigned, the code walks up the category hierarchy until it either finds a category with the page assigned or it reaches root. If no page is found even for root, it returns null.

```javascript
var ignoreInvisiblePages = true;
var anAspectTypeID = "plp";

PageMgr.getPage(aCategory, ignoreInvisiblePages, anAspectTypeID);
```

#### Best Practices for Developing a Dynamic Page

Follow best practices when developing a dynamic page.

- Use the `default_component_constructors` property in the page meta definition file to populate a region on the page with a component. For example, specify that the main region of a Product List page contains a Product List grid component. When the merchant creates a Product List page in the Visual Editor, the main region is already populated with the Product List grid component. This approach helps the merchant to quickly create pages that use the appropriate components.
- Be specific when naming a component, clearly indicating what kind of page the component is intended for. For example, name a component intended for a Product Detail page, `Product Detail Grid`. If the merchant uses a component that has attributes not specified by the aspect type assigned to the page, the component doesn't render correctly. By naming the components carefully, help merchants create pages with the appropriate components.
- Be careful when creating a page type that supports more than one aspect type. Merchants must complete the extra and potentially confusing step of selecting a page type purpose during creation. Also, a page type generic enough to accommodate more than one aspect type can make only limited use of prepopulated components, providing the merchant less guidance during page design.

## Create a Custom Cartridge for Page Designer UI Artifacts

To localize page and component types or display thumbnail images, create a custom cartridge. Include resource bundles for localization and thumbnail image files. Upload the cartridge to the Business Manager site.

### Create Page Designer Localization Resource Bundles

A resource bundle contains the localized names and descriptions for each page type, component type, and component type group that you want to localize. Including a resource bundle is optional. If you don’t provide them, the visual editor uses information in the meta definition files.

Each page type, component type group, and component type requires a separate resource bundle.

Name the resource bundle files using this pattern:

`{componenttype/pagetype/componenttypegroup}__{locale}_.properties`

Put the resource bundles for page types and component types in this location in the cartridge:

`{your_cartridge}/cartridge/templates/resources/experience/pages`

`{your_cartridge}/cartridge/templates/resources/experience/components`

Put resource bundles for component type groups within a componentgroup subdirectory: `{your_cartridge}/cartridge/templates/resources/experience/componentgroups`

If type files are in a subdirectory of `../experience/pages` or `../experience/components`, resource bundles must be in a corresponding `resources` subdirectory.

| Page Type, Component Type, Component Group                                | Resource Bundle in Cartridge                                                                                |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `mycartridge/cartridge/experience/components/banners/headlinebanner.json` | `myBMcartridge/cartridge/templates/resources/experience/components/banners/headlinebanner_de_DE.properties` |
| `mycartridge/cartridge/experience/pages/promopage.json`                   | `myBMcartridge/cartridge/templates/resources/experience/pages/promopage_fr.properties`                      |
| `mycartridge/cartridge/experience/pages/promotions/promopage.json`        | `myBMcartridge/cartridge/templates/resources/experience/pages/promotions/promopage_en.properties`           |
| `content`                                                                 | `myBMcartrige/cartridge/templates/resources/experience/componentgroups/content_en.properties`               |

#### Example Resource Bundle for a Page Type

```json
name=Promotional Page
description=A promotional page with header, main area and footer.
region.header.name=Header
region.main.name=Main
region.footer.name=Footer
```

#### Example Resource Bundle for a Component Type

```json
name=Banner
description=A banner that allows to configure which image to show in a sizable manner.
attribute_definition_group.image.name=Banner Image Configuration
attribute_definition_group.image.description=You can define the image file, size and alt text for the banner image.
attribute_definition.image.name=Image
attribute_definition.image.description=The image shown by the banner.
attribute_definition.alt.name=Image Alt Text
attribute_definition.alt.description=The image alt text.
attribute_definition.size.name=Size
attribute_definition.size.description=The banner size.
```

#### Example Resource Bundle for a Component Type Group

The resource bundle for a component type group contains only the `name` value of the group.

```json
name=Content
```

### Page Designer Thumbnail Images

In the Page Designer visual editor, thumbnail images assist the merchant in determining which page or component to select. If you don't provide thumbnail images, generic images are displayed.

The file name for a thumbnail images (without the extension) must match the name of the respective page type or component type, for example, `promopage.png` or `promopage.svg`. Page Designer doesn't support a different thumbnail image for different locales.

#### Thumbnail Images for Pages

Put thumbnail images for page types in this location.

`{your_cartridge}/cartridge/static/default/images/experience/pages/{subdirectory}/{id}`

The optional `{subdirectory}` must match the subdirectory where the pages are in the `../experience/pages` directory.

For example if the page type is located in `mycartridge/cartridge/experience/pages/promotions/promopage.json`, the image file must be located here:

`myBMcartridge/cartridge/static/default/images/experience/pages/promotions/promopage.png`

#### Thumbnail Images for Components

Put thumbnail images for component types at this location in your cartridge:

`{your_cartridge}/cartridge/static/default/experience/components/{sudirectory}/{id}`

The optional `{subdirectory}` must match the subdirectory where the component types are in the `../experience/components` directory.

For example if the component type is located in `mycartridge/cartridge/experience/components/banners/headlinebanner.json`, the image file must be located here:

`mycartridge/cartridge/static/default/experience/components/banners/headlinebanner.png`

## Use Salesforce CMS Content with Page Designer

Use Salesforce CMS to manage all your content in a single repository. Merchants can use the CMS content on a Page Designer page. For example, you develop a component type that displays a headline banner. Create and manage different options for the content of the headline banner in Salesforce CMS. When merchants add the component type to a page, they select which content to use for the headline banner from Salesforce CMS.

### Get Access to Salesforce CMS

To use CMS content with Page Designer components, make sure your Salesforce org includes Salesforce CMS.

Contact your Salesforce Account Executive or Success Manager for information about pricing and packaging. For information about Salesforce CMS, see [Salesforce Content Management System (CMS)](https://help.salesforce.com/articleView?id=community-managed-content-overview.htm).

### Connect Salesforce CMS to Page Designer

Connect your B2C Commerce instance to a CMS channel and assign the channel to your site library.

1.  Open a support ticket and request a trust relationship between your Salesforce org and your B2C Commerce instance.

2.  In Salesforce CMS, add a CMS workspace to host the Page Designer content or use an existing CMS workspace.

    For information about creating CMS workspaces, see [Create a CMS Workspace in Salesforce CMS](https://help.salesforce.com/articleView?id=xcloud.cms_cmsworkspace-create.htm).

    ![Add CMS workspace](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_create_cms_workspace.jpg)

3.  In Salesforce CMS, create a B2C Commerce channel.

    For information about creating a CMS channel, see [Create a CMS Channel](https://help.salesforce.com/articleView?id=xcloud.cms_channel_create.htm).

    ![Create CMS channel](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_create_cms_channel.jpg)

4.  In the CMS workspace, add the B2C Commerce channel.

    For information about adding CMS channels, see [Add a Channel to a CMS Workspace](https://help.salesforce.com/articleView?id=xcloud.cms_channel_add.htm).

    ![Add channel](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_add_cms_channel.jpg)

5.  In B2C Commerce Business Manager, go to **Administration** > **Sites** > **Content Libraries** > **_site_** > **General**. Scroll to the bottom and assign the CMS channel to your site library.

    ![Assign channel to site library](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_cms_channel_selection.jpg)

### Develop a Component Type to Use CMS Content

Define a component type with an attribute assigned to Salesforce CMS content.

1.  Determine the content required to configure the component type attribute.

    For example, you want merchants to be able to include a headline banner on their Page Designer page by selecting a CMS record. Use the news content type, which already exists in Salesforce CMS, to create and manage the content for the headline banner.

    If the content type you want to use in the Page Designer page doesn't already exist in the CMS, create it. See [Custom Content Types.](https://developer.salesforce.com/docs/platform/cms/guide/cms-dev-custom-content-types.html)

2.  Create a component type that includes attributes assigned to type `cms_record`, with the `content_type` specified in the `editor_definition` element.

    For example, the following meta definition file and script files for component type CMS Headline Banner use a Headline Content attribute of type `cms_record`, with `content_type` news.

    ```json
{
        "name": "CMS Headline Banner",
        "description": "Image, text overlay from CMS that links user to a B2C target using the markup editor",
        "group": "assets",
        "attribute_definition_groups": [{
                "id": "headlineContent",
                "name": "Headline Content",
                "description": "The presentation of the headline",
                "attribute_definitions": [{
                    "id": "cmsItem",
                    "name": "Headline Content",
                    "type": "cms_record",
                    "required": true,
                    "editor_definition": {
                        "content_type": "news"
                    }
                }]
            },
            {
                "id": "calltoaction",
                "name": "Call to Action Button",
                "description": "Label and target for the call to cation button",
                "attribute_definitions": [{
                        "id": "ctaTitle",
                        "name": "Button Title",
                        "type": "string",
                        "required": true
                    },
                    {
                        "id": "ctaLink",
                        "name": "Button Link",
                        "type": "url",
                        "required": true
                    }
                ]
            }
        ],
        "region_definitions": []
    }
```

    ```javascript
'use strict';

    var Template = require('dw/util/Template');
    var HashMap = require('dw/util/HashMap');
    var ImageTransformation = require('~/cartridge/experience/utilities/ImageTransformation.js');

    /**
     * Render logic for the assets.headlinebanner.
     */
    module.exports.render = function(context) {
        var model = new HashMap();
        var content = context.content;

        if (content.cmsItem) {
            model.bannerTitle = content.cmsItem.attributes.title;
            model.bannerCopy = content.cmsItem.attributes.body;

            if (content.cmsItem.attributes.bannerImage) {
                model.bannerImg = {
                    src: {
                        mobile: ImageTransformation.url(content.cmsItem.attributes.bannerImage, { device: 'mobile' }),
                        desktop: ImageTransformation.url(content.cmsItem.attributes.bannerImage, { device: 'desktop' })
                    },
                    alt: content.cmsItem.attributes.excerpt
                };
            }
        }

        model.callToAction = {
            title: content.ctaTitle,
            link: content.ctaLink
        }

        return new Template('experience/components/assets/headlinebanner').render(model).text;
    };
```

### Use Salesforce CMS Content to Configure a Component Attribute

Configure the component attribute by selecting the Salesforce CMS content and then configuring the attributes for that content.

When you select CMS content for a component attribute, it's copied into the page. CMS updates don't automatically appear in the component. To get updated content, reconfigure the attribute and select the content again.

The default locale for the Page Designer page isn't necessarily the same as the default locale for the CMS content.

1.  Add the component that uses Salesforce CMS content to the page.

    In this example, the CMS Headline Banner component type uses CMS content to configure the Headline Content attribute. ![CMS headline banner component](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_cms_component_screen.jpg)

2.  In the attribute editor window, click **Select CMS Content**.

    ![Select CMS content](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_new_2_cms_modal_select_screen.jpg)

    A list of the CMS content available to configure the attribute is displayed.

3.  Choose the CMS content you want to use and click Select.

    ![Set properties for CMS Headline Banner component](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_cms_attrs_screen.jpg)

    The CMS content is copied to the page. Any attributes for the CMS content that require configuration are presented in the editing pane. The CMS content for the Headline Banner in the example requires that you enter a Title, Body, and Banner Image.

4.  Configure at least the required attributes for the component click **Save** or **Save & Close**.

## Develop a Custom Attribute Editor

Create a custom attribute editor for configuring component attributes. Merchants use the custom attribute editor when setting a value for the component attribute in the Business Manager visual editor.

### Why Implement a Custom Attribute Editor?

When you create a component type, you specify merchant-configurable attributes. For example, a headline banner component might have an Image attribute. Merchants must configure this attribute to select the displayed image. The type value in the meta definition file determines the UI control (check box, file picker, etc.).

Page Designer provides preconfigured `type` options. The `file` type presents a file picker. The `boolean` type presents a checkbox. The `enum` type presents a selection list.

If none of the preconfigured Page Designer UI controls are appropriate for your situation, create your own custom attribute editor. For example, you might want a custom attribute editor to let merchants select store locations on a map or choose a color for the text or background. Or, you want to let merchants place a Favorite icon on a product tile or select which Shop Now button to use.

A custom attribute editor doesn’t conflict with the platform code for Page Designer, and you can create more than one custom attribute editor for a single component type.

### How Does a Custom Attribute Editor Work?

A custom attribute editor uses a meta definition file, script, and JavaScript/CSS resources. It operates in a self-contained client-side environment. Merchants use it in the Page Designer visual editor to configure attribute values.

In the meta definition file for the component type, define the attribute's type as `custom`. If information is passed to the custom attribute editor, include that information in an `editor_definition` element for the attribute. In the meta definition file for the custom attribute editor, list the CSS and JavaScript resources that the custom attribute editor requires. Optionally add server-side logic or resources to initialize the custom attribute editor in the script file for the custom attribute editor. You include the meta definition file and script file for the custom attribute editor, along with the JavaScript and CSS resources, in a custom cartridge assigned to the Business Manager site.

On the client side, each custom attribute editor is wrapped in a host component containing an `<iframe>`. The iframe encapsulates the editor's code and style. This sandbox environment prevents different editors on the same page from interfering.

The host and editor communicate on a dedicated channel. Page Designer adds management code to the iframe with `subscribe` and `emit` methods. These send predefined events with serializable payloads between host and editor.

For information about the messaging channel implemented for Page Designer custom attribute editors, see [Channel Messaging](https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API).

### Custom Attribute in the Component Meta Definition File

In the component meta definition file, set the attribute `type` to `custom` and include an `editor_definition` element. The `editor_definition` includes the custom editor ID and optional configuration information.

This example banner meta definition includes three standard attributes: image (`file`), alt (`string`), and size (`enum`). It also includes a Magic Unicorns custom attribute using editor ID `com.sfcc.magical`. Unicorn options (Auris, Chant, etc.) are passed via the `configuration` element.

To view schema files that describe the JSON formatting for the meta definition file, see [Page Designer JSON Schemas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/content/).

```json
{
  "name": "Banner",
  "description": "A banner.",
  "group": "content",
  "attribute_definition_groups": [
    {
      "id": "image",
      "name": "Banner Image Configuration",
      "description": "You can define the image file, size and alt text for the banner image.",
      "attribute_definitions": [
        {
          "id": "magic",
          "name": "Magic Unicorns",
          "type": "custom",
          "required": true,
          "editor_definition": {
            "type": "com.sfcc.magical",
            "configuration": {
              "options": {
                "config": [
                  "Auris",
                  "Chant",
                  "Elmas",
                  "Majesty",
                  "Moriba",
                  "Mystery",
                  "Mystic",
                  "Snowflake",
                  "Solstice",
                  "Sunshine"
                ]
              }
            }
          }
        },
{
          "id": "image",
          "name": "Banner Image",
          "description": "The image shown by the banner.",
          "type": "file",
          "required": true
        },
        {
          "id": "alt",
          "name": "Banner Image Alt Text",
          "description": "The image alt text shown by the banner.",
          "type": "string",
          "required": false
        },
        {
          "id": "size",
          "name": "Size",
          "description": "The banner size.",
          "type": "enum",
          "values": [
            "small",
            "medium",
            "large"
          ],
          "required": true,
          "default_value": "medium"
        }
      ],
      "region_definitions": []
    }
  ]
}
```

### Custom Attribute Editor Meta Definition File

The meta definition file for a custom attribute editor references the JavaScript and CSS resources that the custom attribute editor requires.

Put the meta definition file in this directory of the cartridge or any subdirectory under this directory:

- `{your_bm_ cartridge}/cartridge/experience/editors`

**important:** The cartridge that contains the custom attribute editor meta definition file, script file, and client-side code must be added to the cartridge path for the Business Manager site.

Use only alphanumeric or underscore characters for the file name. If you put the meta definition file in a subdirectory of `/experience/editors`, the subdirectory name must also use only alphanumeric or underscore characters.

To view the schema file that describes the JSON formatting for the meta definition file, see [Page Designer JSON Schemas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/content/).

This example meta definition file describes a custom attribute editor that lets the user select a unicorn. Use fully qualified URLs or relative URLs in the meta definition file. Page Designer resolves relative URLs to point to the `/static/default` directory of the cartridge. For example, this meta definition file uses relative URLs to reference the JavaScript file `magical_editor.js` and the CSS file `magical.css`, which are in the `/static/default/experience/editors/com/sfcc` directory of the cartridge.

```json
{
  "name": "Magical Custom Editor",
  "description": "A new magical editor with flying unicorns!",
  "resources": {
    "scripts": [
      "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.0/jquery.min.js",
      "/experience/editors/com/sfcc/magical_editor.js"
    ],
    "styles": [
      "https://cdnjs.cloudflare.com/ajax/libs/design-system/2.8.3/styles/salesforce-lightning-design-system.min.css",
      "/experience/editors/com/sfcc/magical.css"
    ]
  }
}
```

### Custom Attribute Editor Script File

Each custom attribute editor requires a script file. The script file has the same name as the corresponding meta definition file but with a `.js` extension. For example, if the meta definition file for the control is `magical.json`, name the script `magical.js`.

Use only alphanumeric or underscore characters for the file name. Put the script file with its meta definition file. For a custom attribute editor named magical:

`my_bm_cartridge/cartridge/experience/editors/com/sfcc/magical.json`

`my_bm_cartridge/cartridge/experience/editors/com/sfcc/magical.js`

**important:** The cartridge that contains the custom attribute editor meta definition file, script file, and client-side code must be added to the cartridge path for the Business Manager site.

In the script file, optionally implement the `init` function to initialize the custom attribute editor with server-side logic or resources.

**note:** Every custom attribute editor requires a script file. If you don't use the script file to implement the `init` function, you must include an empty script file in the cartridge.

This example script adds options not in the component's `editor_definition`. It also includes localization and CSS resources for lists over 10 items. The editor object passed to `init` is type `dw.experience.CustomEditor`. It provides access to:

- `configuration`—Map that contains entries passed to the client-side scripts, populated with the values provided by the `editor_definition` of the attribute in the component's meta definition file. To extend the map, use only serializable entries, primitive types (number string, boolean), `dw.util.HashMap`, or JavaScript arrays. Native JavaScript objects (in curly braces) aren’t supported nor are other complex B2C Commerce script objects, such as `dw.catalog.Product`.
- `dw.experience.CustomEditorResources`—Collection of JavaScript and CSS URLs that the client-side iframe uses to display the custom attribute editor.

```javascript
'use strict';

var Resource = require('dw/web/Resource');
var HashMap = require('dw/util/HashMap');

module.exports.init = function (editor) {
  // add some more options programmatically
  editor.configuration.options.put('init', [
    'Wynstar',
    'Jasper',
    'Joshi',
    'Rainbow',
    'Blythe',
    'Mika',
    'Nightwind',
    'Cadillac',
    'Julius',
    'Calimerio'
  ]);

  // add some localizations
  var localization = {
    placeholder: 'Select your favorite unicorn',
    description: 'Unicorns are magical creatures you want for every component. Select the one of your choice now!',
    group1: 'Unicorns from JSON Config',
    group2: 'Unicorns from init()',
    group3: 'Unicorns from OCAPI request'
  };
  editor.configuration.put('localization', Object.keys(localization).reduce(function (acc, key) {
    acc.put(key, Resource.msg(key, 'experience.editors.com.sfcc.magical', localization[key]));
    return acc;
  }, new HashMap()));

  // add some resources only required for a lot of unicorns
  if ((editor.configuration.options.config.length + editor.configuration.options.init.length) > 10) {
     editor.resources.styles.push("/experience/editors/com/sfcc/magical-extreme.css");
  }
}
```

### Client-Side JavaScript and CSS for a Custom Attribute Editor

Put client-side JavaScript and CSS files in the cartridge's `static/default` directory. The location should correspond to the meta definition and script file location.

For example, let's say the meta definition file and script file for the custom attribute editor are in the following location:

`my_bm_cartridge/cartridge/experience/editors/com/sfcc/magical.json`

`my_bm_cartridge/cartridge/experience/editors/com/sfcc/magical.js`

Put the JavaScript and CSS files here:

`my_bm_cartridge/cartridge/static/default/experience/editors/com/sfcc`

**important:** The cartridge that contains the custom attribute editor meta definition file, script file, and client-side code must be added to the cartridge path for the Business Manager site.

This client-side JavaScript example uses a `<select>` element for user interaction. It displays unicorn types in two `<optgroup>` elements from two different sources:

- `group1`—Unicorn types entered into the `configuration` element of the `editor_definition` for the attribute in the component's meta definition file.
- `group2`—Unicorn types passed to the custom attribute editor from the `init` function of the editor's script file.

In this example, the editor subscribes to `sfcc:ready`. When the host emits this event, the editor initializes its DOM using configuration from the server-side `init` function. It assigns unicorns to their `<optgroup>`. When users change the `<select>` value, the editor sends `sfcc:value` to the host.

```javascript
(() => {
  subscribe('sfcc:ready', async ({ value, config, isDisabled, isRequired, dataLocale, displayLocale }) => {
    console.log('sfcc:ready', dataLocale, displayLocale, value, config);

    const selectedValue = typeof value === 'object' && value !== null && typeof value.value === 'string' ? value.value : null;
    const { options = {}, localization = {} } = config;
    let isValid = true;

    // Append basic DOM
    const template = obtainTemplate(localization);
    const clone = document.importNode(template.content, true);
    document.body.appendChild(clone);

    // Set props
    const selectEl = document.querySelector('select');
    selectEl.required = isRequired;
    selectEl.disabled = isDisabled;

    // Set <options> from JSON config
    const optgroupEls = selectEl.querySelectorAll('optgroup');
    setOptions(options.config || [], optgroupEls[0], selectedValue);

    // Set <options> from init()
    setOptions(options.init || [], optgroupEls[1], selectedValue);

    // Apply change listener
    selectEl.addEventListener('change', event => {
      const val = event.target.value;
      emit({
        type: 'sfcc:value',
        payload: val ? { value: val } : null
      });
    });
  });

  function obtainTemplate({ placeholder, description, group1, group2 }) {
    const template = document.createElement('template');
    template.innerHTML = `
<div style="display: flex; justify-content: space-between; align-items: center;">
  <div class="slds-select_container" title="${description}">
    <select class="slds-select">
      <option value="">-- ${placeholder} --</option>
      <optgroup label="${group1}"></optgroup>
      <optgroup label="${group2}"></optgroup>
    </select>
  </div>
</div>`;
    return template;
  }

  function setOptions(options, optgroupEl, selectedValue) {
    options.forEach(option => {
      const optionEl = document.createElement('option');
      optionEl.text = option;
      optionEl.value = option;
      optionEl.selected = option === selectedValue;

      optgroupEl.appendChild(optionEl);
    });
  }
})();
```

### Custom Attribute Editor Events

Each custom attribute editor is wrapped in a host component that contains an HTML `iframe` element. The iframe encapsulates the code and styling of the editor and represents a self-contained sandbox environment in which the editor runs so that different custom attribute editors on the same page don't interfere with each other. The host and the custom attribute editor in the iframe communicate by passing events back and forth on a special messaging channel.

For information about the messaging channel implemented for Page Designer custom attribute editors, see [Channel Messaging](https://developer.mozilla.org/en-US/docs/Web/API/Channel_Messaging_API). For information about the messaging API used to send and receive the events, see [Messaging API](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel). Page Designer adds some management code to the iframe that includes a `subscribe` method and an `emit` method that send predefined events with serializable payloads back and forth between the host and the editor.

#### subscribe()

Subscribes to events sent from the host to the editor. Subscribe for a certain event type. When that event is sent from the host, a callback is invoked that uses a payload and optional context.

```typescript
type SandboxSubscribe = (type: string, callback: (payload?: any, context?: SandboxContext) => void, source?: any) => () => void;

interface SandboxContext {
  transfer?: Transferable[]; // @see https://developer.mozilla.org/en-US/docs/Web/API/Transferable
  source?: any; // Event sourcing should only be required in rare cases
}
```

```javascript
subscribe('sfcc:ready', (payload, context) => {
  // ...
});
```

#### emit()

Sends events from the editor to the host.

```typescript
type SandboxEmit = (message: SandboxMessage, callback?: (payload: any) => void) => void;

interface SandboxMessage {
  type: string;
  payload?: any;
  source?: any;
  transfer?: Transferable | Transferable[];
```

```javascript
emit({
  type: 'sfcc:breakout',
  payload: {
    id: 'myBreakoutId',
    title: '
  }
}, ({ type, value }) => { // ... });
```

<table>
<caption>
Table 1. Events Emitted by the Host
</caption>
<thead>
<tr>
<th>
Event
</th>
<th>
Meaning
</th>
<th>
Payload
</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>sfcc:ready</code>
</td>
<td>
The custom attribute editor is initialized. All the scripts and styles have been loaded into the editor's environment. When the host emits this event, it doesn't necessarily mean that all asynchronously loaded assets and code have finished loading. For some components, you might need to manually listen to browser events, such as load or DOMContentLoaded, to get more information. The
<code>sfcc:ready</code>
event includes information required to display the editor, such as initial value, configuration data, data locale, display locale, and initial validity.
</td>
<td>

```json
{
value: { OBJECT_OF_ARBITRARY_STRUCTURE };
config: { OBJECT_OF_ARBITRARY_STRUCTURE };
isRequired: boolean;
isDisabled: boolean;
isValid: boolean;
dataLocale: string;
displayLocale: string;
}
```

</td>
</tr>
<tr>
<td>
<code>sfcc:value</code>
</td>
<td>
The value of the attribute. Not sent on the initial load. Sent only when the value changes because of external modifications.
</td>
<td>
<code>{ OBJECT_OF_ARBITRARY_STRUCTURE }
</code>
</td>
</tr>
<tr>
<td>
<code>sfcc:required</code>
</td>
<td>
Indicates whether this attribute is required. Not sent on the initial load. Sent only when the required status changes after the initialization ready phase. The custom attribute editor might use this information to display certain styling or indicators in the editor.
</td>
<td>
<code>boolean</code>
</td>
</tr>
<tr>
<td>
<code>sfcc:disabled</code>
</td>
<td>
Indicates whether this attribute is disabled. Not sent on the initial load. Sent only when the disabled status changes after the initialization ready phase. The custom attribute editor might use this information to render elements differently or display certain styling or indicators in the editor.
</td>
<td>
<code>boolean</code>
</td>
</tr>
<tr>
<td>
<code>sfcc:valid</code>
</td>
<td>
Indicates whether the value of the attribute is valid. Not sent on the initial load. Sent only when the validity status changes after the initialization ready phase.
</td>
<td>
<code>boolean</code>
</td>
</tr>
</tbody>
</table>

| Event             | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Payload                               |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| `sfcc:value`      | The value of the attribute. Sent when the value changes inside the editor. Page Designer requires that the value be a plain JavaScript object.                                                                                                                                                                                                                                                                                                                                                                                                   | `(OBJECT_OF_ARBITRARY_STRUCTURE)`     |
| `sfcc:valid`      | Indicates whether the value of the attribute is valid. Can include an error message.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `{ valid: boolean, message: string }` |
| `sfcc:interacted` | Indicates that the user has interacted with the custom attribute editor. The editor is implicitly marked as interacted when it’s blurred, for example, when the editor's `contentWindow` loses focus. Page Designer supports an interacted (or touched) state for form elements. This state marks a field that a user already interacted with, for example, by tabbing through it. Being able to mark a field as touched allows for error messages in forms to be hidden initially and only display for fields with which a user has interacted. | `void`                                |

### Create a Breakout Custom Attribute Editor That Displays in a Modal Window

Create a custom attribute editor sized to fit your content with the breakout custom attribute feature.

#### What Is a Breakout Editor?

The right pane of the Page Designer visual editor provides only limited space for merchants to configure component attributes. To provide more space, create a trigger editor to display a breakout editor inside a separate modal window.

For example, you want the merchant to select which unicorn image to use on the storefront, but the right pane doesn't have enough space to display all the available unicorn images. So you create a trigger editor that appears in the right pane and includes a Select button.

![Editor for selecting a unicorn](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_unicorn_ca_enoselection.png)

When the merchant clicks Select, the breakout editor opens in a modal window where the merchant can see all the available images.

![Figure showing images of unicorns, none selected.](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_unicorn_cae_modal_no_selection.png)

The merchant selects an image, and clicks Apply.

![List of unicorn images, one selected.](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_unicorn_cae_modal_selection.png)

The modal closes, and the selected image appears in the right pane next to the Select button.

![Editor for selecting a unicorn, showing the new selection.](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_unicorn_cae_selection.png)

Implementing a breakout editor involves these high-level steps:

1.  Create server-side meta definition and script files for the trigger editor and the breakout editor.
2.  In the script file for the trigger editor, define the breakout editor as a dependency.
3.  Develop client-side UI code that implements the trigger and breakout editors, opens and closes the breakout modal window, and passes a value from the breakout editor to the trigger editor to Page Designer when the merchant clicks Apply.

#### Trigger Editor Meta Definition and Script Files

To create a trigger custom attribute editor, define the attribute as type `custom` in the component meta definition file. Then create a meta definition JSON file and a script file for the trigger editor. In the script file, instantiate the breakout editor using the `PageMgr.getCustomEditor` method. This method takes the ID of the breakout editor and an optional configuration object. Then add the breakout editor as a dependency.

This trigger editor script file example specifies a breakout editor with ID `com.sfcc.magicalBreakout`. The script creates a `breakoutEditorConfig` configuration object that contains the localization information defined for the trigger editor. It also includes the options defined in the `attribute_definitions` section of the component meta definition file for the trigger editor, obtained from `editor.configuration.options.config`.

The localization information and options in the `breakoutEditorConfig` object are passed from the trigger editor to the breakout editor using the `PageMgr.getCustomEditor` method, which instantiates the breakout editor with the given ID. The script then adds the breakout editor as a dependency using `editor.dependencies.put`. The ID included in `editor.dependencies`, in this case `magical_breakout`, is used in the client-side code for the trigger and breakout editors to access the breakout editor.

```javascript
'use strict';

var HashMap = require('dw/util/HashMap');
var Resource = require('dw/web/Resource');
var PageMgr = require('dw/experience/PageMgr');

module.exports.init = function(editor) {
  // Default values for L10N properties
  var l10nDefaults = {
    buttonBreakout: 'Select',
    titleBreakout: 'Breakout Content Title',
    placeholder: 'Select your favorite unicorn',
    description: 'Unicorns are magical creatures you want for every component. Select the one of your choice now!',
    group1: 'Unicorns from JSON Config',
    group2: 'Unicorns from init()'
  };

  // Add some localizations
  var localization = Object.keys(l10nDefaults).reduce(function (acc, key) {
    acc.put(key, Resource.msg(key, 'experience.editors.com.sfcc.magical', l10nDefaults[key]));
    return acc;
  }, new HashMap());
  editor.configuration.put('localization', localization);

  // Pass through property `options.config` from the `attribute_definition` to be used in a breakout editor
  var options = new HashMap();
  options.put('config', editor.configuration.options.config);

  // Create a configuration for a custom editor to be displayed in a modal breakout dialog (breakout editor)
  var breakoutEditorConfig = new HashMap();
  breakoutEditorConfig.put('localization', localization);
  breakoutEditorConfig.put('options', options);

  // Add a dependency to the configured breakout editor
  var breakoutEditor = PageMgr.getCustomEditor('com.sfcc.magicalBreakout', breakoutEditorConfig);
  editor.dependencies.put('magical_breakout', breakoutEditor);
};
```

#### Breakout Editor Meta Definition and Script Files

The breakout custom attribute editor requires its own JSON meta definition file and script file.

The meta definition file references the JavaScript and CSS resources that the editor requires, as in this example.

```json
{
  "name": "Magical Custom Editor Breakout",
  "description": "An editor with unicorn images",
  "resources": {
    "scripts": [
      "/experience/editors/com/sfcc/magical_breakout.js"
    ],
    "styles": [
      "https://cdnjs.cloudflare.com/ajax/libs/design-system/2.9.4/styles/salesforce-lightning-design-system.min.css",
      "/experience/editors/com/sfcc/magical.css"
    ]
  }
}
```

The script file implements the `init` function to initialize the custom attribute editor with server-side logic or resources. This example adds options for the breakout editor not included in the `editor_definition` of the component's meta definition file. It also includes a reference to CSS resources that are required if the list of unicorns includes more than 20 items.

```javascript
'use strict';

var URLUtils = require('dw/web/URLUtils');

module.exports.init = function(editor) {
 var optionsConfig = editor.configuration.options.config;
 var optionsInit = [
  'Blythe',
  'Cadillac',
  'Calimerio',
  'Jasper',
  'Joshi',
  'Julius',
  'Mika',
  'Nightwind',
  'Rainbow',
  'Wynstar'
 ];

 // Add more unicorns programmatically
 editor.configuration.options.put('init', optionsInit);

 // Provide `baseUrl` to the static assets/content
 editor.configuration.put('baseUrl', URLUtils.staticURL('/experience/editors/com/sfcc/').https().toString());

 // Conditionally add a resource which is only required in case of a lot of unicorns
 if ((optionsConfig.length + optionsInit.length) > 20) {
  editor.resources.styles.push('/experience/editors/com/sfcc/magical_extreme.css');
 }
};
```

#### Open and Close a Breakout Editor

To open the modal window for the breakout editor, we recommend using a callback on event emission approach, which manages the asynchronous breakout editor process. If you have multiple breakout editors, the callback on event emission approach makes it easier to keep track of open breakout editors because a callback is related to only one breakout process.

This example opens the breakout editor from the trigger editor, waits for the user to close the breakout editor, and then gets the selected value.

```javascript
// Code in the client-side JavaScript file for the trigger editor
(() => {
  // 1)
  subscribe("sfcc:ready", () => {
    // Once the editor is ready, a `sfcc:breakout` event is sent. Usually
    // this happens when a user clicks on a certain <button> or interacts with the trigger editor in some way
    const openButtonEl = document.querySelector("#myOpenBtn");
    openButtonEl.addEventListener("click", handleBreakoutOpen);
  });

  function handleBreakoutOpen() {
    // 2)
    // The user interacted with the <button> and the triggering editor requests that Page Designer
    // open a breakout on its behalf using an editor ID. This ID refers
    // to the key under which an editor has been put into the "dependencies" key-
    // value store of the triggering editor's configuration. A callback is provided
    // along with the event emission to be invoked once the breakout editor gets
    // closed.
    emit(
      {
        type: "sfcc:breakout",
        payload: {
          id: "myCustomEditorId",
          title: "The title to be displayed in the modal",
        },
      },
      handleBreakoutClose,
    );
  }

  function handleBreakoutClose({ type, value }) {
    // 5)
    // When the breakout is closed (either programmatically, or via the
    // built-in action <button>s), the callback is invoked, containing
    // information about the "type" of action that caused the invocation.
    // A breakout can be closed with the intent to either "Cancel" or "Apply"
    // an editing process. The intent can be derived from the "type" information
    // that comes as part of the callback reponse (either `sfcc:breakoutCancel`
    // or `sfcc:breakoutApply`). In case of an "Apply" intent will also include
    // a "value" available as part of the response, reflecting the value that has
    // last been set via `sfcc:value` in the breakout editor.

    // Now the "value" can be passed back to Page Designer
    if (type === "sfcc:breakoutApply") {
      handleBreakoutApply(value);
    } else {
      handleBreakoutCancel();
    }
  }

  function handleBreakoutCancel() {
    // ...
  }

  function handleBreakoutApply(value) {
    // ...

    // Emit value update to Page Designer host application
    emit({
      type: "sfcc:value",
      payload: value,
    });
  }
})();
```

```javascript
// Code in the client-side JavaScript file for the breakout editor
(() => {
  // 3)
  subscribe("sfcc:ready", () => {
    // Once the breakout editor is ready, the custom code is able to select or create
    // a value. Any meaningful change to a value/selection needs to be reflected
    // back into the host container via a `sfcc:value` event.
    const selectEl = document.querySelector("#mySelect");
    selectEl.addEventListener("change", handleSelect);
  });

  function handleSelect({ target }) {
    // 4)
    // The value changed and the breakout editor's host is informed about the
    // value update via a `sfcc:value` event.
    const selectedValue = target.value;
    emit({
      type: "sfcc:value",
      payload: selectedValue ? { value: selectedValue } : null,
    });
  }
})();
```

Another way to open and close the breakout modal is to use only events. However, this approach is more difficult because it requires that you correctly implement a cascade of subscribers and emitters based on the messaging API. This example illustrates a trigger editor that manages multiple parallel breakout editors.

**note:** If you leave the ID portion of an event payload blank, Page Designer closes the first open breakout editor related to the requesting trigger editor. `

```javascript
// Code in the client-side JavaScript file for the trigger editor
(() => {
  // 1)
  subscribe("sfcc:ready", () => {
    // Once the editor is ready, a `sfcc:breakout` event can be sent. Usually
    // this happens when a user clicks on a certain <button> or interacts with the trigger editor in some way
    const openButtonEl = document.querySelector("#myOpenBtn");
    openButtonEl.addEventListener("click", handleBreakoutOpen);
  });

  // 3b)
  subscribe("sfcc:breakout", ({ id }) => {
    // Once the Page Designer host application opens a breakout on the trigger editor's behalf,
    // it informs the trigger about its newly created breakout via a `sfcc:breakout`
    // event. The important property of the payload is the "id" which can be stored
    // to be used later to explicitly close a certain breakout component. There is
    // no hard requirement listening to this event in case the custom code inside
    // the triggering editor doesn't have to explicitly close a certain breakout
    // programmatically. Usually a breakout will be closed by the breakout itself,
    // either via the custom code inside the breakout CAE, or via user interaction
    // with a built-in <button> in a breakout's footer section.
  });

  // 6a)
  subscribe("sfcc:breakoutCancel", ({ id }) => {
    // ...
  });

  // 6b)
  subscribe("sfcc:breakoutApply", ({ id, value }) => {
    // ...

    // Emit value update to Page Designer
    emit({
      type: "sfcc:value",
      payload: value,
    });
  });

  function handleBreakoutOpen() {
    // 2)
    // The user interacted with the <button> and the triggering CAE requests that Page Designer
    // open a breakout on its behalf using a certain editor ID. This ID refers
    // to the key under which an editor has been put into the "dependencies" key-
    // value store of the triggering editor's configuration. This time no callback
    // is provided along with the event emission.
    emit({
      type: "sfcc:breakout",
      payload: {
        id: "myCustomEditorId",
        title: "The title to be displayed in the modal",
      },
    });
  }
})();
```

```javascript
// Code in the client-side JavaScript file for the breakout editor
(() => {
  // 3a)
  subscribe("sfcc:ready", ({ breakout }) => {
    // Along with the `sfcc:ready` event, some meta information about the breakout is
    // passed to the breakout editor. The important property in the "breakout" data
    // is the "id" which can be stored to be used later to explicitly close a
    // certain breakout component.

    // Once the breakout editor is ready, the custom code is able to select or create
    // a value. Any meaningful change to a value or selection must be reflected
    // back into the host container via a `sfcc:value` event.

    // 3)
    // Apply event handlers to elements inside the component's DOM.
    // It's not required to have action buttons inside the editor itself as the
    // surrounding breakout element's footer section already contains <button>
    // elements for both "Cancel" and "Apply" actions.
    const cancelButtonEl = document.querySelector("#myCancelBtn");
    const applyButtonEl = document.querySelector("#myApplyBtn");
    const selectEl = document.querySelector("#mySelect");
    const { id } = breakout;
    cancelButtonEl.addEventListener("click", () => handleBreakoutCancel(id));
    applyButtonEl.addEventListener("click", () => handleBreakoutApply(id));
    selectEl.addEventListener("change", handleSelect);
  });

  function handleSelect({ target }) {
    // 4)
    // The value changed and the breakout editor's host gets informed about the
    // value update via a `sfcc:value` event.
    const selectedValue = target.value;
    emit({
      type: "sfcc:value",
      payload: selectedValue ? { value: selectedValue } : null,
    });
  }

  function handleBreakoutCancel(id) {
    // 5a)
    // Explicitly request that the Page Designer host application close a certain breakout with
    // the intent to cancel the editing process.
    emit({
      type: "sfcc:breakoutCancel",
      payload: { id },
    });
  }

  function handleBreakoutApply(id) {
    // 5b)
    // Explicitly request that the Page Designer host application close a certain breakout with
    // the intent to apply the current value/selection of the editing process.
    emit({
      type: "sfcc:breakoutApply",
      payload: { id },
    });
  }
})();
```

#### Enable and Disable the Breakout Editor Apply Button

Emit an `sfcc:valid` event from the breakout editor to indicate whether the value that the user selected in the breakout editor is valid. If the value is valid, Page Designer enables the Apply button in the breakout modal window footer. If the value is invalid, Page Designer disables the Apply button and optionally displays an error message.

In this example, if the value is valid, an `sfcc:valid` event with payload `true` is emitted, and the Apply button is enabled. If the value is invalid, an `sfcc:valid` event is issued with a polymorphic payload that includes a valid key set to `false` and a message set to `This value is invalid`. The Apply button is disabled, and an error icon is displayed showing the error message `This value is invalid` in a tooltip.

```javasript
// Code in the client-side JavaScript file for the breakout editor
(() => {
  // ...

  if (isValid) {
    emit({
      type: 'sfcc:valid',
      payload: {
        valid: false,
        message: 'This value is invalid.'
      }
    });
  } else {
    emit({
      type: 'sfcc:valid',
      payload: true
    });
  }

  // ...
})();
```

#### Trigger and Breakout Editor Client-Side UI Code

The trigger editor and the breakout editor require client-side script files. Incorporate any of the custom attribute editor events in the script files. The trigger editor file opens and closes the breakout editor and emits the `sfcc:value` event to Page Designer. The breakout editor file includes the code to implement the editor, and emits `sfcc:valid` and `sfcc:value` events to the trigger editor.

This example of a client-side script for a trigger editor, `magical_trigger.js`, uses callbacks and event emissions to open and close the breakout editor. When the merchant clicks Apply in the breakout editor, the `handleBreakoutApply(value)` function passes the value selected in the breakout editor to Page Designer using an `sfcc:value` event.

The client-side script example for the corresponding breakout editor, `magical_breakout.js`, includes the logic that displays the unicorns. The list of unicorns to display is retrieved from two different sources. The first source is the `attribute_definitions` in the component's meta definition file (`options.config`). Refer to [Custom Attribute Editor Meta Definition File](#custom-attribute-editor-meta-definition-file) for an example of the component's meta definition file where these unicorn options are configured. The second source is the `init` method in the server-side script file (`options.init`).

The example uses `function updateValidity(value)` to check whether the currently selected value. When the merchant selects a valid value, `function updateSelectedValue(value)` emits an `sfcc:value` event to the dedicated host component for the breakout editor.

**note:** The code in these examples conforms to the ECMAScript 2015 specification. It isn't appropriate if you’re targeting legacy browsers such as Internet Explorer 11.

```javascript
(() => {
  let localization;
  let inputEl;
  let buttonEl;

  subscribe('sfcc:ready', async ({ value, config, isDisabled, isRequired, dataLocale, displayLocale }) => {
    console.log('magical-trigger::sfcc:ready', dataLocale, displayLocale, isDisabled, isRequired, value, config);

    // Extract `localization` data from `config`
    ({ localization = {} } = config);

    // Initialize the DOM
    const template = obtainTemplate();
    const clone = document.importNode(template.content, true);
    document.body.appendChild(clone);

    // Obtain DOM elements and apply event handlers
    inputEl = document.querySelector('input');
    buttonEl = document.querySelector('button');
    buttonEl.addEventListener('click', handleBreakoutOpen);

    // Update <input> value
    inputEl.value = obtainDisplayValue(value);
  });

  function obtainTemplate() {
    const { placeholder, buttonBreakout } = localization;
    const template = document.createElement('template');
    template.innerHTML = `
<div class="slds-grid slds-grid_vertical-align-center">
  <div class="slds-col slds-grow">
    <input type="text" disabled class="slds-input" placeholder="${placeholder}">
  </div>
  <div class="slds-col slds-grow-none">
    <button type="button" class="slds-button slds-button_neutral">${buttonBreakout}</button>
  </div>
</div>`;
    return template;
  }

  function obtainDisplayValue(value) {
    return typeof value === 'object' && value != null && typeof value.value === 'string' ? value.value : null;
  }

  function handleBreakoutOpen() {
    const { titleBreakout } = localization;

    emit({
      type: 'sfcc:breakout',
      payload: {
        id: 'magical_breakout',
        title: titleBreakout
      }
    }, handleBreakoutClose);
  }

  function handleBreakoutClose({ type, value }) {
    if (type === 'sfcc:breakoutApply') {
      handleBreakoutApply(value);
    } else {
      handleBreakoutCancel();
    }
  }

  function handleBreakoutCancel() {
    console.log('magical-trigger::sfcc:breakoutCancel');

    // Grab focus
    buttonEl && buttonEl.focus();
  }

  function handleBreakoutApply(value) {
    console.log('magical-trigger::sfcc:breakoutApply');

    // Update <input> value
    inputEl.value = obtainDisplayValue(value);

    // Emit value update to Page Designer
    emit({
      type: 'sfcc:value',
      payload: value
    });

    // Grab focus
    buttonEl && buttonEl.focus();
  }
})();
```

```javascript
(() => {
  let baseUrl;
  let localization;
  let options;
  let gridEl;

  subscribe('sfcc:ready', async ({ value, config, isDisabled, isRequired, dataLocale, displayLocale }) => {
    console.log('magical-breakout::sfcc:ready', dataLocale, displayLocale, isDisabled, isRequired, value, config);

    // Extract essential data from `config`
    ({ baseUrl = './', options = {}, localization = {} } = config);

    // Initialize the DOM
    const template = obtainTemplate();
    const clone = document.importNode(template.content, true);
    document.body.appendChild(clone);

    // Update initial validity
    const selectedValue = obtainDisplayValue(value);
    updateValidity(selectedValue);

    // Init and append unicorn DOM
    const { group1, group2 } = localization;
    gridEl = document.querySelector('.slds-grid');
    options.config.forEach(appendItems(group1, selectedValue));
    options.init.forEach(appendItems(group2, selectedValue));

    // If applicable, focus the link element that represents the currently selected unicorn
    // --> 100ms delay due to an SLDS transition interference
    const selectedEl = document.querySelector(`a[data-value="${selectedValue}"]`);
    selectedEl && setTimeout(() => {
      selectedEl.scrollIntoView(false);
    }, 100);
  });

  function obtainTemplate() {
    const template = document.createElement('template');
    template.innerHTML = `
<div class="slds-grid slds-grid_vertical"></div>`.trim();
    return template;
  };

  function obtainItemHeadTemplate(title) {
    const template = document.createElement('template');
    template.innerHTML = `
<div class="slds-col slds-box">${title}</div>`.trim();
    return template;
  }

  function obtainItemTemplate(option) {
    // Choose a random unicorn image -> Generate a number between 1 and 20
    const unicornImageId  = Math.floor(Math.random() * 20) + 1;

    const template = document.createElement('template');
    template.innerHTML = `
<div class="slds-col">
  <a href="javascript:void(0);" tabindex="-1" title="${option}" class="slds-box slds-box_link slds-box_x-small slds-media" data-value="${option}">
    <div class="slds-media__figure slds-media__figure_fixed-width slds-align_absolute-center slds-m-left_xx-small">
      <span class="slds-avatar slds-avatar_large">
        <img src="${baseUrl}images/unicorn_${unicornImageId}.jpg" alt="${option}" loading="lazy">
      </span>
    </div>
    <div class="slds-media__body slds-border_left slds-p-around_small">
      <h2 class="slds-truncate slds-text-heading_small" title="Share the knowledge">${option}</h2>
      <p class="slds-m-top_small">Lorem ipsum dolor sit amet, consectetur adipisicing elit. Fugiat minus molestias reprehenderit consequuntur sapiente. Modi veritatis totam accusantium numquam assumenda.</p>
    </div>
  </a>
</div>`.trim();
    return template;
  }

  function appendItems(title, selectedValue) {
    const itemHeadTemplate = obtainItemHeadTemplate(title);
    const itemHeadEl = document.importNode(itemHeadTemplate.content, true);
    gridEl.appendChild(itemHeadEl);

    return option => {
      // Init a media object inside a grid column to represent a unicorn
      const itemTemplate = obtainItemTemplate(option);
      const itemEl = document.importNode(itemTemplate.content, true);

      // Init the link inside the media object
      const isSelected = selectedValue === option;
      const linkEl = itemEl.querySelector('a');
      linkEl.addEventListener('click', handleSelect);
      isSelected && linkEl.classList.add('slds-is-selected');

      // Append the grid column to the DOM
      gridEl.appendChild(itemEl);
    };
  }

  function handleSelect({ currentTarget }) {
    const { value } = currentTarget.dataset;
    updateSelectedValue(value);
  }

  function updateValidity(value) {
    const isValid = typeof value !== 'undefined' && value != null;
    const { description } = localization;
    const payload = isValid ? isValid : { valid: isValid, message: description };

    emit({
      type: 'sfcc:valid',
      payload
    });

    return isValid;
  }

  function updateSelectedValue(value) {
    const oldSelectedEl = document.querySelector('a.slds-is-selected');
    oldSelectedEl && oldSelectedEl.classList.remove('slds-is-selected');

    const isValid = updateValidity(value);
    if (isValid) {
      const newSelectedEl = document.querySelector(`a[data-value="${value}"]`);
      newSelectedEl && newSelectedEl.classList.add('slds-is-selected');

      emit({
        type: 'sfcc:value',
        payload: {
          value
        }
      });
    }
  }

  function obtainDisplayValue(value) {
    return typeof value === 'object' && value != null && typeof value.value === 'string' ? value.value : null;
  }
})();
```

### Use a Prebuilt Editor in a Custom Attribute Editor

Create custom attribute editors faster and more efficiently with prebuilt attribute editors. Use the prebuilt editors as building blocks when you create custom attribute editors.

This table lists the prebuilt editors that are available. We provide multiple IDs for each prebuilt editor to use the style you prefer. All the prebuilt editors open in a separate breakout modal window.

<table><caption>Table 1. Prebuilt Editors</caption><col /><col /><col /><col /><col /><thead><tr><th>Prebuilt Editor</th><th>Purpose</th><th>ID</th><th>Return Value Type</th><th>Return Value Example</th></tr></thead><tbody><tr><td>Category Picker</td><td>Allows merchant to select a category</td><td><code>sfcc:categoryPicker</code> or <code>sfcc\:category-picker</code></td><td>Category ID <code>&lt;string&gt;</code></td><td>

<pre>{
type: "sfcc:categoryPicker",
value: "1234567890"
}</pre>

</td></tr><tr><td>Link Builder</td><td>Builds a link to the element selected by the merchant</td><td><code>sfcc:linkBuilder</code> or <code>sfcc:link-builder</code></td><td>Absolute URL or URL portions <code>&lt;string | string[]&gt;</code> <p>Depending on the link type the user created using the Link Builder, the return value is either a single string or an array of strings.</p> <p>A single string indicates that the value is an absolute URL that can be used as-is. An array of strings indicates that the URL must be assembled using the <code>URLUtils.url</code> method.</p></td><td>

<pre>{
type: "sfcc:linkBuilder",
value: "https://salesforce.com"
}</pre>

or

<pre>{
type: "sfcc:linkBuilder",
value: ["Page-Show", "cid", "1234567890"]
}</pre></td></tr><tr><td>Page Picker</td><td>Allows merchant to select a page</td><td><code>sfcc:pagePicker</code> or <code>sfcc:page-picker</code></td><td>Page ID <code>&lt;string&gt;</code></td><td>

<pre>{
type: "sfcc:pagePicker",
value: "1234567890"
}</pre>

</td></tr><tr><td>Product Picker</td><td>Allows merchant to select a product</td><td><code>sfcc:productPicker</code> or <code>sfcc:product-picker</code></td><td>Product ID <code>&lt;string&gt;</code></td><td>
<pre>{
type: "sfcc:productPicker",
value: "1234567890"
}</pre>
</td></tr></tbody></table></sfdocstbl>

The following examples show a custom attribute editor that uses the prebuilt editor for Category Picker. In the meta definition file for the component type, designate the attribute for the Category Picker as type `custom`.

```json
{
	"name": "Category Selection Tile",
	"description": "A tile that lets the mercant select a category to display.",
	"group": "content",
	"attribute_definition_groups": [{
		"id": "category",
		"name": "Category",
		"description": "You can select the category.",
		"attribute_definitions": [{
			"id": "category",
			"name": "Category",
			"type": "custom",
			"required": true,
			"editor_definition": {
				"type": "com.sfcc.categoryPicker"
			}
		}],
```

On the server side, create a meta definition JSON file and a .js file for the custom attribute editor just as you would for any custom attribute editor.

```json
{
  "name": "Category Editor",
  "description": "A prebuilt editor that allows you to select a category.",
  "resources": {
    "scripts": [
      "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.4.0/jquery.min.js",
      "/experience/editors/com/sfcc/categoryPicker_trigger.js"
    ],
    "styles": [
      "https://cdnjs.cloudflare.com/ajax/libs/design-system/2.8.3/styles/salesforce-lightning-design-system.min.css",
      "/experience/editors/com/sfcc/category.css"
    ]
  }
}
```

```javascript
'use strict';

var HashMap = require('dw/util/HashMap');
var Resource = require('dw/web/Resource');

module.exports.init = function (editor) {
    // Default values for L10N properties
    var l10nDefaults = {
        buttonBreakout: 'Select',
        titleBreakout: 'Category',
        placeholderInput: 'Select the category',
    };

    // Add some localizations
    var localization = Object.keys(l10nDefaults).reduce(function (acc, key) {
        acc.put(key, Resource.msg(key, 'experience.editors.sfcc.categoryPicker', l10nDefaults[key]));
        return acc;
    }, new HashMap());

    if (!editor.configuration) {
      editor.configuration = new HashMap();
    }
    editor.configuration.put('localization', localization);
};
```

On the client side, create a JavaScript file that runs the prebuilt editor, as in this example. Set the payload ID in the `sfcc:breakout` event to the ID of the prebuilt editor, in this case `sfcc:categoryPicker`.

```javascript
(() => {
  let localization;
  let inputEl;
  let buttonEl;
​
  /**
   * This listener subscribes to the creation/initialization event of the sandbox component. This event gets fired when a Page Designer user
   * first opens a component of a certain type in the component settings panel (and that component type contains the custom editor).
   * **Note:** This event won't fire when the user switches between components of the same type in the canvas. In that case the existing
   * attribute editor components will be reused which results in a value update event (`sfcc:value`), therefore no new initialization
   * happens.
   */
  subscribe('sfcc:ready', ({ value, config, isDisabled, isRequired, dataLocale, displayLocale }) => {
    console.log('category-trigger::sfcc:ready', { dataLocale, displayLocale, isDisabled, isRequired, value, config });
​
    // Extract data from `config`
    ({ localization = {} } = config);
​
    // Initialize the DOM
    const template = obtainTemplate();
    const clone = document.importNode(template.content, true);
    document.body.appendChild(clone);
​
    // Obtain DOM elements and apply event handlers
    inputEl = document.querySelector('input');
    buttonEl = document.querySelector('button');
    buttonEl.addEventListener('click', handleBreakoutOpen);
​
    // Update <input> value
    inputEl.value = obtainDisplayValue(value);
  });
​
  /**
   * This listener subscribes to external value updates. As stated above, this event also gets fired when the user switches between
   * different components of the same type in the canvas. As in that case already existing custom editor instances get reused, it
   * technically means that switching between components of the same type is just an external value update.
   */
  subscribe('sfcc:value', value => {
    console.log('category-trigger::sfcc:value', { value });
​
     // Update <input> value
    inputEl.value = obtainDisplayValue(value);
  });
​
  function obtainTemplate() {
    const { placeholderInput, buttonBreakout } = localization;
    const template = document.createElement('template');
    template.innerHTML = `
<div class="slds-grid slds-grid_vertical-align-start">
  <div class="slds-col slds-grow">
    <input type="text" disabled class="slds-input" placeholder="${placeholderInput}">
  </div>
  <div class="slds-col slds-grow-none slds-m-left_xx-small">
    <button type="button" class="slds-button slds-button_neutral">${buttonBreakout}</button>
  </div>
</div>`;
    return template;
  }
​
  function obtainDisplayValue(value) {
    return typeof value === 'object' && value != null && typeof value.value === 'string' ? value.value : null;
  }
​
  function handleBreakoutOpen() {
    const { titleBreakout } = localization;
​
    emit({
      type: 'sfcc:breakout',
      payload: {
        id: 'sfcc:categoryPicker',
        title: titleBreakout
      }
    }, handleBreakoutClose);
  }
​
  function handleBreakoutClose({type, value}) {
    if (type === 'sfcc:breakoutApply') {
      handleBreakoutApply(value);
    } else {
      handleBreakoutCancel();
    }
  }
​
  function handleBreakoutCancel() {
    // Grab focus
    buttonEl && buttonEl.focus();
  }
​
  function handleBreakoutApply(value) {
    // Update <input> value
    inputEl.value = obtainDisplayValue(value);
​
    // Emit value update to the PD host application
    emit({
      type: 'sfcc:value',
      payload: value
    });
​
    // Grab focus
    buttonEl && buttonEl.focus();
  }
})();
```

## Search Configuration for Page Designer Pages

Configure searching for Page Designer pages and attribute content.

### Enable Search and Search Suggestions for Page Designer Pages

Page Designer pages and components are content assets that can optionally be assigned to folders. In order to also make pages that aren’t assigned to folders searchable, you must extend the `ContentSearchModel` to remove the folder filter. The same applies to content suggestions, so you want to apply the same adjustment to the `SuggestModel` as well.

For example, in the Storefront Reference Architecture (SFRA) `searchHelpers.js` file, we could add the following line to the `setupContentSearch` function so that searching can find content assets that aren’t in folders:

`apiContentSearchModel.setFilteredByFolder(false);`

The modified `setupContentSearch` function is as follows:

```javascript
function setupContentSearch(params) {
    var ContentSearchModel = require('dw/content/ContentSearchModel');
    var ContentSearch = require('*/cartridge/models/search/contentSearch');
    var apiContentSearchModel = new ContentSearchModel();

    apiContentSearchModel.setRecursiveFolderSearch(true);
    apiContentSearchModel.setSearchPhrase(params.q);
    **apiContentSearchModel.setFilteredByFolder(false);**
    apiContentSearchModel.search();
    var contentSearchResult = apiContentSearchModel.getContent();
    var count = Number(apiContentSearchModel.getCount());
    var contentSearch = new ContentSearch(contentSearchResult, count, params.q, params.startingPage, null);

    return contentSearch;
}
```

In the Storefront Reference Architecture (SFRA) `SearchServices.js` file, we could set the `setFilteredByFolder` attribute of the `SuggestModel` to false so that content assets that aren’t in folders can be found using content suggestions:

`suggestions.setFilteredByFolder(false);`

The modified code is as follows:

```javascript
if (searchTerms && searchTerms.length >= minChars) {
        suggestions = new SuggestModel();
        **suggestions.setFilteredByFolder(false);**
        suggestions.setSearchPhrase(searchTerms);
        suggestions.setMaxSuggestions(maxSuggestions);
        categorySuggestions = new CategorySuggestions(suggestions, maxSuggestions);
}
```

### Enable Indexing for Attribute Content

Specify that component or page attributes are indexed and searchable. When attributes are searchable, users can find pages by searching for the attribute value. For example, users can search for the text configured for a rich text attribute.

Add `searching` to the definition of the attribute in the page or component meta definition file, as in the following example for a page attribute:

```json
{
  "id": "heading",
  "name": "Banner Heading",
  "required": true,
  "type": "text",
  "searching": {
    "searchable": true,
    "refinable": true,
    "boost_factor": 2.0
    "sortable": true
  }
},
```

Designate the following types as `searchable`. If the `searchable` value isn’t specified, the default is false.

- string
- text
- markup
- product
- category
- cms_record
- custom
- enum-of-string

The `refinable` value indicates whether a user can further refine search results based on the content of this attribute. Designate all `searchable` attribute types as `refinable` except cms_record and custom.

The `boost_factor` value influences the placement of the page in the search results. Specify any value from 0.01 to 100.00 for the boost factor. A boost factor of 1.00 is the default and doesn’t change the order of search results. Specify a boost factor less than 1.00 to indicate that text in the attribute is less relevant than other terms in the index. Specify a boost factor greater than 1.00 to increase the relevance of attribute text. For example, including a boost factor of 2.00 makes the field twice as relevant in relation to other fields in the index. We recommend that you use boost factors less than or equal to 5.00.

For page attributes, include the `sorting` property set to `true` to indicate that search results can be sorted using this attribute.

**note:** The `sorting` property is applicable only for page-level attributes. Don’t use the sorting property for component attributes.

**note:** You can’t use the `sorting` property with attributes of type markup.

For attributes of type custom, all elements of the attribute are considered text for purposes of indexing. For attributes of type cms_record, only attributes of the cms_record that are supported as searchable are added to the index. For example, if the cms_record includes an attribute of type image, the image isn’t indexed.

### Use SEO Page Meta Tag Rules for Dynamic Pages

When you render dynamic Product Detail or Product List pages, use Page Meta Tag Rules that merchants configured to create meta tags in the HTML markup. Include a decorator that creates the HTML `<head>` section of the page. When rendering the page, get the data from the Page Meta Tag Rules, and pass it to the decorator.

For example, if you’re working with SFRA pages and components, include the following code in the implementation of your page, after all regions and all components are rendered, but before the decorator.

```javascript
pdict.CurrentPageMetaData = PageRenderHelper.getPageMetaData(pdict.page);
```

The template `htmlHead.isml`, which is included indirectly in the SFRA decorator templates, uses `pdict.CurrentPageMetaData` to create the appropriate HTML meta tags.

## Pages and Components as Content Assets

Pages and components are persisted in the database as content assets, but they aren't displayed in the content asset list in Business Manager and you can't edit them directly from Business Manager. Generally, processes like replication and indexing work the same for pages and components as they do for content assets. But pages and components are different from content assets in some ways.

### Pages and Components and OCAPI SHOP and DATA API

Page Designer doesn't support using the OCAPI SHOP and DATA resources to access pages and components as content assets.

### Page and Component Content Asset Attributes

Pages and components share the same attributes as content assets. But in some cases, the content asset attributes have special meaning or behavior when they’re applied to pages and components.

| Content Asset Attribute  | Pages                    | Components            | Localizable?                                                                                                          | Site Specific? |
| ------------------------ | ------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------- |
| id                       | id                       | id                    |                                                                                                                       |                |
| type                     | type                     | type                  |                                                                                                                       |                |
| online                   | online                   | online                |                                                                                                                       | X              |
| config                   | visibility definition    | visibility definition |                                                                                                                       |                |
| data                     |                          | content attributes    | X                                                                                                                     |                |
| content links            | components per region    | components per region |                                                                                                                       |                |
| name                     | name                     | name                  | X (For components, the name is technically localizable, but the localized name isn’t displayed in the visual editor.) |                |
| description              | description              |                       | X                                                                                                                     |                |
| page title               | seo title                |                       | X                                                                                                                     |                |
| page description         | seo description          |                       | X                                                                                                                     |                |
| page keywords            | seo keywords             |                       | X                                                                                                                     |                |
| page url                 | seo url prefix           |                       | X                                                                                                                     |                |
| searchable               | searchable               |                       |                                                                                                                       | X              |
| searchwords              | searchwords              |                       | X                                                                                                                     |                |
| sitemap included         | sitemap included         |                       |                                                                                                                       | X              |
| sitemap change frequency | sitemap change frequency |                       |                                                                                                                       | X              |
| sitemap priority         | sitemap priority         |                       |                                                                                                                       | X              |

### Import and Export for Page Designer Pages and Components

Import pages and components as content assets using the standard library import and export functionality. The `type` attribute distinguishes pages and components in the library from other content assets.

Pages use the following format for the `type` attribute:

page.{page_type_id}

For example, this snippet from a library import file includes a page named fixedlayout identified as `type` page.fixedlayout.

```xml
<content content-id="finishedsamplepage">
   <display-name xml:lang="x-default">Finished Sample Page</display-name>
   <display-name xml:lang="en-US">Finished Sample Page</display-name>
   <type>page.fixedlayout</type>
   <config>{
     "visibility" : [ ]
   }</config>
   <online-flag>true</online-flag>
   <searchable-flag>false</searchable-flag>
   <page-attributes/>
   <content-links>
       <content-link content-id="headlinebanner_newarrivals-womens"
        type="page.fixedlayout.region1">
           <position>0.0</position>
       </content-link>
   </content-links>
   <sitemap-included-flag>false</sitemap-included-flag>
</content>

```

Components use the following format for the `type` attribute:

component.{component_type_id}

For example, this snippet from a library import file includes a component named producttile identified as `type` component.assets.producttile.

```xml
<content content-id="producttile_25696677">
        <display-name xml:lang="x-default">Product Tile 25696677</display-name>
        <type>component.assets.producttile</type>
        <config>{
          "visibility" : [ ]
        }</config>
        <data xml:lang="x-default">{
          "product" : "25696677"
        }</data>
        <data xml:lang="en-US">{
          "product" : "25696677"
        }</data>
        <online-flag>true</online-flag>
        <page-attributes/>
    </content>

```

Both pages and components need a `config` attribute describing visibility rules. Components also need a `data` attribute with merchant-set attributes. Define `config` and `data` as JSON snippets. See the JSON schemas for details:

[Page Designer JSON Schemas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/content/)

In the following situations, the import is allowed to proceed, but might issue multiple warning messages:

- You haven’t yet uploaded the cartridge that contains the page and component types.
- The imported data is in conflict with the meta definitions for existing page and component types, for example, if an imported component has attributes that aren’t defined in the corresponding meta definition file.

## Page Designer Caching

It’s important to understand how page caching works with Page Designer pages and the cache times for pages, components, and custom attribute editors.

### Page Caching

#### Page Rendering and Serialization

Caching for Page Designer pages is similar to other pages, with some nuances.

#### Controller Pagecache Lifecycle

Rendering or serialization starts with a top-level request from the web adapter invoking a custom controller like `Page-Show`. The SFRA `Page.js` controller uses this snippet to check page visibility. Only pages without visibility rules are pagecached.

```javascript
server.get('Show', cache.applyDefaultCache, consentTracking.consent, function (_req_, res, next) {
   ...
   var page = PageMgr.getPage(req.querystring.cid);

   if (page != null && page.isVisible()) {
      if (page.hasVisibilityRules()) {
         res.cachePeriod = 0; // pages with visibility rules should not be cached
         res.cachePeriodUnit = 'hours';
      }

      res.page(page.ID, {}); // invokes PageMgr.renderPage()
   } else {
      ...
   }

   next();
}, pageMetaData.computedPageMetaData);
```

Deciding if you want to apply pagecaching in your controller, and how to do so, is effectively a case by case decision. Don’t create pagecache conditions in your code that are subject to the request context, thus not pagecacheable in a global manner.

#### Page Rendering and Serialization Using Nested Remote Includes to Handle Visibility Rules

Parallel to the first pagecache lifecycle constructed around the controller, there’s a second pagecache lifecycle constructed around the actual contents of the page that is initiated by two nested remote includes.

When `PageMgr.renderPage()` renders or `PageMgr.serializePage()` serializes a page:

- The first-level remote include is the system controller `__SYSTEM__Page-Include`. This remote include determines a visibility fingerprint of the page and its components, which are visible for the current request context (based on schedules, customer groups, or other visibility settings). Remote includes can only be pagecached if the page and its components don't have a visibility rule defined. This is due to the context evaluation. The duration of such pagecaching is configurable via Business Manager.

  1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Merchant Tools > Manage Sites**.
  2. Select a site.
  3. Select the **Cache** tab.
  4. Locate the Time to Live (TTL) of Page Designer Fingerprint.
     The option is configured in seconds. The default is 24 hours (84000 seconds).

  The presence of a visibility rule ‌leaves this first-level remote include uncached. After this calculation, the fingerprint is attached to a second-level remote include. Then the second-level remote include is invoked.

- The second-level remote include is the system controller `__SYSTEM__Page-Render` (rendering) or `__SYSTEM__Page-Serialize` (serialization), which is pagecachable based on the attached visibility fingerprint. This remote include invokes the custom scripts of the render function to render the page, or the serialize function to serialize the page. The response created is configured with pagecache settings through the previously mentioned scripts that are invoked for the page and all its processed visible components. If none of these provide pagecache instrumentation, this second-level remote include remains uncached.

Each variation of the page showing a different set of visible components results in a separate pagecache entry because the visibility fingerprint calculation yields a different result.

**note:** The more a page varies (in terms of different components shown for different request contexts) the more pagecache fragmentation for this page occurs.

For `__SYSTEM__Page-Include`, pages with visibility rules appear uncached. The second-level include (`__SYSTEM__Page-Render` or `__SYSTEM__Page-Serialize`) maintains caching statistics for all Page Designer pages combined. You can't track caching separately for individual pages.

#### SCAPI Based Page Serialization

Caching for Page Designer pages through SCAPI clients is similar to the DWScript-based approach. However, there are some small differences. The shopper experience SCAPI exposes two endpoints. Use them to fetch Page Designer pages by ID, or category or product. For more information, see the [SCAPI documentation](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-experience).

The client starts serialization by calling a shopper experience endpoint. The request goes to the web adapter, which calls a system controller. The controller gets pages by ID, category, or product.

- get page by id:

  `__SYSTEM__ShopperExperience-GetPagesIdV1`

- get pages by category or product:

  `__SYSTEM__ShopperExperience-GetPagesV1`

The system controller calculates a fingerprint. Then it delegates to the serialization of the pages.

#### #### Page Rendering and Serialization Using Nested Remote Includes to Handle Visibility Rules

A pagecache lifecycle is built around the page content. This includes fingerprint calculation and a nested remote include. The include performs the serialization.

- The top-level request covers the two endpoint system controllers used in the SCAPI-based page serialization. These retrieve a single page by ID or multiple pages by category or product. Then, they create a visibility fingerprint from the page and its components. These are visible for the current request context. This is based on schedules, customer groups, or other visibility settings. For multiple pages by category or/ product the final fingerprint is the concatenation of the fingerprints of each page. The top-level request can only be page cached if the page and its components don't have a visibility rule defined. This is due to the context evaluation. The duration of such pagecaching is configurable via Business Manager.

  1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Merchant Tools > Manage Sites**.
  2. Select a site.
  3. Select the Cache tab.
  4. Locate the Time to Live (TTL) of Page Designer Fingerprint.

     The option is configured in seconds. The default is 24 hours (84000 seconds).

  The presence of a visibility rule ‌leaves this top-level request uncached. After this calculation, the fingerprint is attached to a second-level remote include. Then the second-level remote include is invoked.

- The second-level request is a remote include to the system controller `__SYSTEM__ShopperExperience-SerializePageV1`, which is pagecachable based on the attached visibility fingerprint. This remote include invokes the custom scripts of the serialize function to serialize the page. The response created is configured with pagecache settings through the previously mentioned scripts that are invoked for the page(s) and all its processed visible components. If none of these provide pagecache instrumentation, this remote include remains uncached.

Each variation of the page showing a different set of visible components results in a separate pagecache entry. This is because the visibility fingerprint calculation yields a different result.

**note:** When a page varies, pagecache fragmentation increases. This happens when different components are shown for different request contexts.

#### Page and Component Pagecache Lifecycle

TThe pagecache lifecycle of the page contents beyond the fingerprint calculation is induced through a separate request. If you configure pagecaching for the page itself, or any component within that page, the setting is applied for:

- the response of the `__SYSTEM__Page-Render` and `__SYSTEM__Page-Serialize` request in case of DWScript based rendering.

- the response of the `__SYSTEM__ShopperExperience-SerializePageV1` request in case of SCAPI based rendering

Thus this setting affects the pagecaching for the whole page, and anything within it, but doesn’t affect anything outside of it like the controller that initiated the rendering. The concept of page and component pagecaching applies for both DWScript and SCAPI based rendering and serialization.

If different pagecache settings are supplied for different components of the page, the response takes on the shortest of the pagecache settings. For example, if you have a page where:

- Component A has a 1-minute relative pagecaching.
- Component B has a 1-hour relative pagecaching.
- Component C has a 1-day relative pagecaching.

The final calculated relative pagecaching is the minimum of these three values (1 minute).

Let’s look at an excerpt of the component type implementation that corresponds to component B to see how it instruments the response for a 1-hour pagecaching. Assuming this component presents personalized information (for example, based on a combination of pricebook, promotion, sorting rule, and A/B test segments), then you must account for that by instrumenting the response with the corresponding vary-by. For more information, refer to the [B2C Commerce Script documentation](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-working-with-scripts.html).

```javascript
module.exports.render = function(context) {
   // do your business logic
   ...

   // instruct 1 hour personalized relative pagecache
   var expiry = new Date();
   expiry.setHours(expiry.getHours() + 1);
   response.setExpires(expiry);
   response.setVaryBy('price_promotion');

   // create markup
   return ...;
}
```

If using `dw.util.Template.render()` like SFRA, don't use `<iscache>` in your template. Use `response.setExpires()` instead. The `dw.util.Template` class is for markup generation, not response modification.

If you don’t supply any pagecache setting for your page and none of its components (for example, neither the page type implementation itself nor component A, B, or C related component type implementations configure a pagecache setting) then the page isn’t going to be pagecached at all. As soon as at least one of these building blocks within a page supplies a pagecache setting, pagecaching happens.

Because the visibility fingerprint is also factored in to the pagecache key of a page rendering or serialization (in shape of a query parameter `vf` of the cacheable `__SYSTEM__Page-Render`, `__SYSTEM__Page-Serialize`, and `__SYSTEM__ShopperExperience-SerializePageV1`), there’s no need for the page or component type implementation to care about page or component visibility rules, that take for example customer groups into consideration, as this is already automatically handled for you.

#### Best Practices

If your page or component requires a minimum pagecache setting, supply it in your page or component type implementation. Component types require extra care as this pagecache setting is affecting the pagecache of the entire page and not just the component alone.

If your page or component doesn’t strictly need any specific pagecache setting - don’t supply it in your page or component type implementation because it relies on the pagecache instrumentation supplied by the other components that reside on the page.

**note:** This is subject to change as your merchant adjusts which components are plugged into a page over time.

For a page type that doesn’t supply a pagecache setting, carefully think about this decision as this means that a page’s components determine if the page is pagecached or not.

If the content of a component can’t be affected by the pagecache settings of the page, other components, or must not be pagecached at all, you must move such content into a remote include to separate it from the rest of the page. The remotely included controller (and its respective template) can then use a pagecache setting as it fits its business purpose. For example, a product tile component that renders the product’s inventory would likely want to include this inventory state in a remote include manner so that the current inventory can always be shown while the remainder of this component can still be pagecached.

Keep in mind that the level which calculates the fingerprint remains uncached unless the page and all its components don’t have any visibility rule. To improve caching, separate cacheable pieces into their own includes. Keeping the page and its components free of visibility rules allows for more efficient caching. This especially holds true if the structure of the page isn't tied to visibility rules, but only the actual content shown by the components. Consider these two facets separately. They have different implications at design and runtime.

### Page Type, Component Type, and Custom Attribute Editor Cache Times

How long page types, component types, and custom attribute editors are cached in memory depends on whether the environment is sandbox, development, staging, or production.

To refresh the page types, component types, and custom attribute editors on a production environment, or to refresh them immediately on other environments, a code version switch must occur. When you develop new page types, component types, or custom attribute editors, or modify existing ones, and then replicate them to a production environment, a best practice is to issue an event for a code version switch so that the page types, component types, and custom attribute editors are immediately refreshed.

| Environment | Cache Refresh Interval              |
| ----------- | ----------------------------------- |
| Sandbox     | 5 seconds or on code version switch |
| Development | 5 seconds or on code version switch |
| Staging     | 5 seconds or on code version switch |
| Production  | On code version switch              |

## Publish a Page Designer Page

Page Designer pages are rendered from a controller and incorporated into the storefront.

### Render Page Designer Pages from a Controller

Use the `dw.experience.PageMgr` API to render pages.

For more information, see [PageMgr API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_experience_PageMgr.html)

Pages are rendered together with their components. You can’t render components separately.

This is the basic code for the page rendering process:

```javascript
...
var content = PageMgr.renderPage(cid, null);
// emit content (for example, write to response)
...
```

Put the call to `PageMgr.renderPage()` in its own controller or add it to an existing controller. To take advantage of SEO URL features, a best practice is to add it to the `Page-Show` controller.

Page rendering occurs within a nested remote include. If you want to use external parameters in the rendering process, for example, parameters accessible by the controller that calls `PageMgr.renderPage()`, pass the parameters to the rendering process using a parameters string. For example:

```javascript
...var params = { /* add your custom parameters here */ };
var content = PageMgr.renderPage(cid, JSON.stringify(params));
// emit content (e.g. write to response)
...
```

The remote include that does the rendering doesn't allow passing response headers or cookies set during rendering to the request that called `PageMgr.renderPage()`. If you need to adjust the response, do so outside of the page rendering process.

### Incorporate a Page Designer Page into the Storefront

Use a storefront controller to create a URL to Page Designer pages. Use the URL, for example, to link to a page from a marketing email. Use the URL to add a link to the page from the global header or footer or main navigation of the storefront.

Create the storefront controller using the `dw.experience` API. The following example controller, `PDPage.js`, exports a `Show` function that passes in the ID of the Page Designer page. The controller checks whether to make the page visible based on schedule and customer group. If the page is visible, the controller renders it. Otherwise, the user is redirected to the home page.

**note:** For clarity, this example shows a separate controller dedicated to rendering Page Manager pages. A best practice is to include the call to `PageMgr.renderPage` in the `Page-Show` controller to take advantage of SEO URL features.

```javascript
'use strict';

var PageMgr = require('dw/experience/PageMgr');
var URLUtils = require('dw/web/URLUtils');

exports.Show = function ()
{
    var page = PageMgr.getPage(request.httpParameterMap.cid.stringValue);

    // Render only if the page is currently visible (as driven by the
    // online flag for scheduling and customer segmentation that the merchant
    // configured for the page)
    if (page != null && page.isVisible())
    {
        response.writer.print(PageMgr.renderPage(page.ID, ""));
    }
    else
    {
        response.redirect(URLUtils.httpsHome().toString());
    }
};
exports.Show.public = true;
```

When this controller is uploaded to the site, any Page Designer page can be accessed by passing in its page ID in a URL as follows:

`{\<urlToTheStorefront>}/PDPage-Show?cid={\<pageID>}`

For example, if you have a page with ID loyalty-rewards, the following URL accesses that page:

`{\<urlToTheStorefront>}/PDPage-Show?cid=loyalty-rewards`

To add a link to your page from the storefront's global header or footer, add the URL to the ISML file for the header or footer. For example:

`<a href=$url('PDPage-Show','cid','loyalty-rewards')"title="Loyalty Program">Loyalty Program</a>`

You could also add a link to the page from the storefront main navigation using the Business Manager to set up a new category. Configure the alternative URL for the category as follows:

`$url('PDPage-Show','cid','loyalty-rewards')$`

### Mock Component Placeholders

When a merchant drags a component onto a Page Designer page in edit mode, a mock component placeholder displays until the merchant configures the component attributes. Mock component placeholders are also used when a merchant creates a localized page based on another page or when a page doesn't render because it's missing attributes.

The mock component placeholder signals to the merchant that the component isn’t yet fully configured or has an error condition. The merchant can move the mock component and edit it like a regular component. The mock component displays only in edit mode.

A mock component uses the following values:

- The `name` of the component type as configured in its meta definition file.
- The thumbnail image for the component type provided in a custom cartridge for Page Designer UI artifacts or, if no custom thumbnail image is provided, the generic Page Designer component thumbnail image.

This example shows what a page looks like with four mock components, one for a headline banner and three for product tiles.

![Screen showing four mock components.](https://developer.salesforce.com/media/b2c-commerce/b2c_page_designer_mocks.png "Mock Component Placeholders on a Page")

The HTML wrapper is always `div`. Mock components use the following two classes:

- `sfdc-component-mock`
- `sfdc-component-{typeID}-mock`, where `{typeID}` is the ID of the component type. Component type ID values include dots, for example, `assets.banner`. When used in the class name, the dot is replaced with a hyphen, for example, `assets-banner`. For example, for a component type with ID `assets.banner`, the class is `sfdc-component-assets-banner-mock`.

To customize how a mock component placeholder displays, apply custom CSS to the mock component class. For example, this CSS file, named `banner-mock.css`, specifies that mock components using the class `sfdc-component-assets-banner-mock` have a `background-color` of `lightblue`.

```css
**banner-mock.css** .sfdc-component-assets-banner-mock {
  background-color: lightblue;
}
```

### Render a JSON View of a Page Designer Page

Expose the data assembled by a page and its components in JSON format. This process can be useful if you want to expose the page to external services to implement native mobile apps or custom heads.

Use the `serializePage` method of the `dw.experience.PageMgr` API to render the page in JSON. For more information about PageMgr, see [PageMgr API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_experience_PageMgr.html).

The method to expose JSON has the following signatures:

```javascript
String : serializePage(String pageID, String parameters)
String : serializePage(String pageID, Map<String,Object> aspectAttributes, String parameters)
```

For example, the following code uses the `serializePage` method to render a page in JSON.

```javascript
function json() {
   response.setContentType('application/json');

   var page = PageMgr.getPage(request.httpParameterMap.cid.value);

   if (page == null)
   {
      response.setStatus(404);
   }
   else
   {
      if (!page.hasVisibilityRules())
      {
         var ONE_WEEK = new Date().getTime() + 7 * 24 * 60 * 60 * 1000;
         response.setExpires(ONE_WEEK);
      }

      if (page.isVisible())
      {
         response.writer.print(PageMgr.serializePage(page.ID, null));
       }
       else
       {
         response.setStatus(404);
       }
    }
}
```

In this example, the page has three regions:

- Header: banner
- Main: category tile and a 2x2 layout grid that holds product and category tiles
- Footer: banner

The resulting JSON includes content structured as follows:

- id: String: The ID of the page or component.
- data: Map\<String, Object>: Content attributes.
- custom: Map \<String, Object>: Additional data that custom code assembles.
- regions: Region: The region model representing the component hierarchy:
  - id: String: The ID of the region.
  - components: List\<StructuredContent>: All visible components assigned to the region in order.

```json
{
  "id": "mypage",
  "data": {
    "attr1": "foo"
  },
  "regions": [
    {
      "id": "header",
      "components": [
        {
          "id": "j2q3eö9fl3inil",
          "data": {
            "title": "New Arrivals",
            "bannerimage": "/catalog/newarrivals.jpg"
          }
        }
      ]
    },
    {
      "id": "main",
      "components": [
        {
          "id": "4wso9j3fwohj3o8",
          "data": {
            "category": "new-arrivals",
            "image": "hotstuff.png"
          }
        },
        {
          "id": "e4g5vuftzue457z4",
          "data": {
            "layout": "2x2"
          },
          "regions": [
            {
              "id": "tiles",
              "components": [
                {
                  "id": "3gfn3w820uz4",
                  "data": {
                    "product": "9237918273"
                  }
                },
                {
                  "id": "3v5zb5r7i547u",
                  "data": {
                    "product": "2374984579"
                  }
                },
                {
                  "id": "ev5z45z3z34235",
                  "data": {
                    "category": "mens-shoes"
                  }
                },
                {
                  "id": "vurz3tv35zu34z",
                  "data": {
                    "category": "womens-shoes"
                  }
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "footer",
      "components": [
        {
          "id": "87wa3tr897g38s",
          "data": {
            "title": "Autumn Collection",
            "bannerimage": "/promo/autumn/collection.jpg"
          }
        }
      ]
    }
  ]
}
```

If your page type or component types have custom code that you want to include in the exposed JSON, use the `serialize(context)` function in addition to the `render(context)` function in the JavaScript for the page or component, as in the following example.

```javascript
module.exports.serialize = function (context) {
    var product = context.content.product;
    var images = product.getImages('large');
    var productImage = null;
    if (images.iterator() && images.iterator().hasNext()) {
        productImage = images.iterator().next();
    }

    return {
        "url" : URLUtils.url('Product-Show', 'pid', product.ID).toString(),
        "image" : productImage.getAbsURL().toString();
    };
}
```

The JSON returned includes the output of the custom code as a custom property of the page or component as in this example.

```json
{
    "id": "mypage",
    "data": {
        "attr1": "foo"
    },
    "regions": [
        {
            "id": "header",
            "components": [
                {
                    "id": "j2q3eö9fl3inil",
                    "data": {
                        "title": "New Arrivals",
                        "bannerimage": "/catalog/newarrivals.jpg"
                    }
                }
            ]
        },
        {
            "id": "main",
            "components" : [
                {
                    "id": "4wso9j3fwohj3o8",
                    "data": {
                        "category": "new-arrivals",
                        "image": "hotstuff.png"
                    }
                },
                {
                    "id": "e4g5vuftzue457z4",
                    "data": {
                        "layout": "2x2"
                    },
                    "regions": [
                        {
                            "id": "tiles",
                            "components": [
                                {
                                    "id": "3gfn3w820uz4",
                                    "data": {
                                        "product": "9237918273"
                                    },
                      **  "custom": {
                                        "url" : "https://.../Product-Show?pid=9237918273",
                                        "image" : "https://.../iphone6.jpg"
                                    }
**                             },
                                {
                                    "id": "3v5zb5r7i547u",
                                    "data": {
                                        "product": "2374984579"
                                    },
                          **"custom": {
                                        "url" : "https://.../Product-Show?pid=2374984579",
                                        "image" : "https://.../galaxyS8.jpg"
                                    }**
                                },
                                {
                                    "id": "ev5z45z3z34235",
                                    "data": {
                                        "category": "mens-shoes"
                                    }
                                },
                                {
                                    "id": "vurz3tv35zu34z",
                                    "data": {
                                        "category": "womens-shoes"
                                    }
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "id": "footer",
            "components" : [
                {
                    "id": "87wa3tr897g38s",
                    "data": {
                        "title": "Autumn Collection",
                        "bannerimage": "/promo/autumn/collection.jpg"
                    }
                }
            ]
        }
    ]
}
```

<!-- document id=9707d9a6d1726bd89c713b948cf662c98b4cdd6cfe647647393574569be5d0e8 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-page-designer-customize-sf.md -->

# Page Designer Content Management for Merchants

Page Designer contains Storefront Next template pages that merchants can add and customize out of the box with new content and components. Merchants can connect Page Designer to a site's storefront, and then customize the storefront and publish live updates.

Storefront Next provides a Home Page, About Us Page, Product Detail Page (PDP), and Product Listing Page (PLP). These pages include layout components and other content components. After an administrator has set up the storefront in Business Manager, merchants select the site associated with the storefront to access and customize its pages in Page Designer.

**note:** There can be a delay between when you make changes in Page Designer in staging and when those changes appear in the storefront in production. See [Page Designer Change Deployment to Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-data-store.md#page-designer-change-deployment-to-storefront-next).

## Before You Begin

Create a storefront in Business Manager. See [Quick Start: Create Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-choice.md). For existing storefronts created outside of Business Manager via the CLI or the MRT API, link them to Business Manager. See [Link an Existing Storefront to B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-link-storefront.md).

## Customize the Storefront in Page Designer

To customize your storefront in Page Designer:

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Merchant Tools**, select a site, then click **Content > Page Designer**.
   The selected site maps Page Designer to your storefront because each site can have only one storefront.

![Page Designer shows Storefront Next pages](https://developer.salesforce.com/docs/media/sfnext/sfnext-pd-page.png '{"class": "image-lg"}')

2. In Page Designer, click one of the listed pages to customize it.
3. To add a page, click **New** and select a page to add.
4. To add components, drag a component from the Components panel and set component properties.

![Page Designer shows Storefront Next pages](https://developer.salesforce.com/docs/media/sfnext/sfnext-pd-components.png '{"class": "image-lg"}')g

5. To preview the changes, click **Preview**, and then select the desired locale, device sizes, and resolution.
6. To publish the changes to the live site, click **Publish**.

## Target Campaigns and Promotions

See how the storefront looks when specific campaigns and promotions are applied.

### Prerequisites

- Make sure that shopper context is enabled. For storefronts created in Business Manager, shopper context is enabled. For other storefronts, enable shopper context. In Business Manager, select **Administration > Global Preferences > Feature Switches**, and select **Enable Shopper Context**. For more information, see [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md).
- (Optional) To target a customer group, enable the `effectiveDateTime`, `customerGroupIds`, `clientIp`, and `geoLocation` qualifiers in the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=type%3AShopperContext). See [Qualifier Support](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md#qualifier-support) in the Shopper Context documentation.
- (Optional) To target campaigns and promotions, set up your site based on the functionality you want to validate in Storefront Preview. Examples:
  - Set up [custom qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_using_session_custom_attributes.htm&type=5) and [customer group IDs](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_customer_group.htm&type=5) using customer groups in Business Manager to apply rules for personalized pricing, products, or promotions.
  - To see a personalized shopper experience, set up source code that calls the [Shopper Context endpoints](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html). This is required because Storefront Preview uses context information for personalization.
  - Set up the pricing that you want to offer on a particular date. That way your specified pricing appears when you select that date in Storefront Preview. See [Personalized Promotions, Shipping, and Payment Methods](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-personalized.html).

### Steps

1. In Page Designer, open a page, and then select a component.
   The properties panel appears.
2. In the properties panel, click **Settings**.
3. To apply a campaign, click **Add to Campaign** and select a preconfigured campaign.
4. To apply a promotion, click **Add to Promotion** and select a preconfigured promotion.
5. To apply custom targeting, click **Custom Targeting** and fill out the fields. This option requires that you set up a customer group. See the [Prerequisites](#prerequisites) section.

![Page Designer shows targeting options for campaigns and promotions](https://developer.salesforce.com/docs/media/sfnext/sfnext-pd-targeting.png '{"class": "image-lg"}')

## Locale Fallback

Locale fallback for Page Designer content follows the storefront's locale fallback chain. Typically: requested locale → parent locale → site default). The manifest carries content for every site locale, and the storefront picks the right one by using its own locale configuration. Verify that your storefront's locale settings produce the desired fallback path.

<!-- document id=721594b87daae2a4a76b49e78e9b85fb30d84dc7ba63dd74bc84b91e462a4502 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-page-designer.md -->

# Page Designer Integration with Storefront Next

Page Designer is a visual, drag-and-drop content management tool for B2C Commerce that business users use to create, schedule, and publish personalized storefront pages without extensive developer intervention. It provides a low-code environment where merchants can build engaging consumer experiences, such as homepages, campaign landing pages, and product highlights, by using a library of reusable functional components. Developers build the reusable components that merchants use.

In Storefront Next, developers build Page Designer components as React components instead of ISML templates. ISML pages and templates aren't used in Storefront Next.

## How It Works for Developers

Developers build the underlying building blocks that business users later manipulate. To learn more about how to build reusable pages and components in Page Designer, see [Page Designer Readme in GitHub](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/main/README-PAGE-DESIGNER.md).

## Core Architecture

The Page Designer system is built on these fundamental concepts that define how content is structured and rendered.

- Pages: Top-level containers fetched via the ShopperExperience API that serve as the foundation for the storefront experience.
- Regions: Named areas within a page or component that act as placeholders where components can be nested.
- Components: Reusable UI elements, such as heroes, carousels, and grids, that contain specific functional logic and styling.
- Component Data: Asynchronous data retrieved by component-specific loaders to populate the UI elements.

## Implement Page Designer Components

Page Designer components are React components that you can decorate with metadata. You can configure the metadata in Business Manager.

### Component Structure

Every Page Designer component follows this structure.

```
src/components/my-component/
├── index.tsx          # Main component with decorators
```

### Metadata Decorators

Components use three decorators to define their metadata.

| Decorator              | Purpose                                          |
| ---------------------- | ------------------------------------------------ |
| `@Component`           | Registers the component with Page Designer.      |
| `@AttributeDefinition` | Defines configurable attributes.                 |
| `@RegionDefinition`    | Defines nested regions for container components. |

### Basic Component Example

This code example defines a Hero Banner Page Designer component. `@Component` registers the banner, and `@AttributeDefinition` on `HeroMetadata` declares optional configurable fields, such as `Title`, `Image`, and `CTA link`, a call-to-action link. A fallback export renders a loading skeleton. The default export is the main Hero that shows the image, title, and optional CTA. You can configure the Hero Banner in Page Designer.

```tsx
// src/components/hero/index.tsx
import { Component } from "@/lib/decorators/component";
import { AttributeDefinition } from "@/lib/decorators/attribute-definition";

@Component("hero", {
  name: "Hero Banner",
  group: "odyssey_base",
  description: "Prominent banner section with title, image, and CTA",
})
export class HeroMetadata {
  @AttributeDefinition({
    name: "Title",
    type: "string",
    required: false,
  })
  title?: string;

  @AttributeDefinition({
    name: "Image",
    type: "image",
    required: false,
  })
  imageUrl?: string;

  @AttributeDefinition({
    name: "CTA Link",
    type: "url",
    required: false,
  })
  ctaLink?: string;
}

// Fallback component (shown while loading)
export function fallback({ title }: Partial<HeroProps>) {
  return (
    <div className="h-64 bg-gray-200 animate-pulse">
      {title && <span className="sr-only">{title}</span>}
    </div>
  );
}

// Main component (default export required)
export default function Hero({ title, imageUrl, ctaLink, ctaText }: HeroProps) {
  return (
    <section className="hero">
      <img src={imageUrl} alt={title} />
      <h1>{title}</h1>
      {ctaLink && <a href={ctaLink}>{ctaText}</a>}
    </section>
  );
}
```

### Attribute Types

These attribute types are available for `@AttributeDefinition`.

| Type         | Description           |
| ------------ | --------------------- |
| `string`     | Single-line text      |
| `text`       | Multi-line text       |
| `markup`     | Rich text/HTML        |
| `integer`    | Whole numbers         |
| `boolean`    | True or false toggle  |
| `image`      | Image picker          |
| `url`        | URL input             |
| `product`    | Product picker        |
| `category`   | Category picker       |
| `page`       | Page reference        |
| `enum`       | Dropdown selection    |
| `cms_record` | CMS content reference |

### Component Patterns: Fallbacks and Loaders

#### Fallback Components

We recommend that every Page Designer component exports a `fallback` function. The fallback skeleton is shown while the component loads.

```tsx
// Lightweight skeleton - no heavy logic
export function fallback({ title }: Partial<MyComponentProps>) {
  return (
    <div className="h-48 bg-gray-200 animate-pulse rounded">
      {title && <span className="sr-only">Loading {title}</span>}
    </div>
  );
}
```

**Best Practices:**

- Keep fallbacks lightweight (no state, effects, or data fetching).
- Match the approximate dimensions of the real component.
- Use CSS animations for loading indication.

#### Data Loaders

Export a `loader` object for components that need dynamic data.

This code example defines a `ProductCarousel` that gets its list from a dual loader. A server loader calls `fetchProducts` using `component.data?.categoryId` and returns products. The component loads data on the server only, therefore the client loader returns null. The component receives already-resolved data and title as props—no Promise handling in the component. It renders the title and a list of products as `ProductCard`s.

```tsx
// Server-side data loading
export const loader = {
  server: async ({ component, request, context }) => {
    // Fetch data on the server
    const products = await fetchProducts(component.data?.categoryId);
    return { products };
  },
  client: async ({ component, request }) => {
    // Optional: Client-side data loading
    return null;
  },
};

export default function ProductCarousel({ data, title }: ProductCarouselProps) {
  // `data` is already resolved - not a Promise!
  return (
    <div>
      <h2>{title}</h2>
      {data?.products.map((product) => (
        <ProductCard key={product.id} product={product} />
      ))}
    </div>
  );
}
```

**Key Points:**

- The `data` prop is **always resolved** when your component receives it.
- The internal Component wrapper handles Promise resolution.
- Your fallback is shown while data loads.
- Multiple components load data **in parallel**.

#### Components with Regions

Container components can define the regions where other components can be placed.

This code example defines a Grid Layout Page Designer component that acts as a container with two regions. `@Component` registers it and `@RegionDefinition` declares Main Content with up to 6 components, and Sidebar with up to 3 components. `GridMetadata` adds an optional `Columns` attribute. A fallback export renders a simple loading grid. The default `Grid` component renders a two-column layout and uses the `Region` component to render the nested content for main and sidebar. That way, you can place other components in each region in Page Designer.

```tsx
import { Component } from "@/lib/decorators/component";
import { RegionDefinition } from "@/lib/decorators/region-definition";
import { Region } from "@/components/region";

@Component("grid", {
  name: "Grid Layout",
  group: "odyssey_base",
  description: "A flexible grid container for arranging components",
})
@RegionDefinition([
  {
    id: "main",
    name: "Main Content",
    maxComponents: 6,
  },
  {
    id: "sidebar",
    name: "Sidebar",
    maxComponents: 3,
  },
])
export class GridMetadata {
  @AttributeDefinition({
    name: "Columns",
    type: "integer",
    defaultValue: 2,
  })
  columns?: number;
}

export function fallback() {
  return <div className="grid gap-4 animate-pulse" />;
}

export default function Grid({ component, columns = 2 }: GridProps) {
  return (
    <div className={`grid grid-cols-${columns} gap-4`}>
      <div className="col-span-1">
        {/* Nested region - uses component mode */}
        <Region component={component} regionId="main" />
      </div>
      <div className="col-span-1">
        <Region component={component} regionId="sidebar" />
      </div>
    </div>
  );
}
```

#### Region Definition Options

These options are available for the region definition metadata.

```tsx
@RegionDefinition([
    {
        id: 'content',                    // Required: Unique region ID
        name: 'Content Area',             // Required: Display name in Business Manager
        maxComponents: 5,                 // Optional: Maximum components allowed
        minComponents: 1,                 // Optional: Minimum components required
        componentTypeInclusions: [        // Optional: Only allow these component types
            'sfnext.hero',
            'sfnext.productCarousel',
        ],
        componentTypeExclusions: [        // Optional: Disallow these component types
            'sfnext.grid',                // Prevent nested grids
        ],
    },
])
```

## Implement Page Designer Pages

A Page is the route-level definition that defines where Page Designer content can be placed.

### Page Structure

This code example defines a Category Page with `@PageType` and two page regions: `banner` and `promoContent`. The route loader loads page and category data via `fetchPageWithComponentData`. The page component renders, in order: the banner region (with a skeleton fallback), a fixed `ProductGrid` for the category, and the `promoContent` region. Banner and promo slots are configurable in Page Designer. The route’s category defines the product grid.

```tsx
// src/routes/category.$categoryId.tsx
import { PageType } from "@/lib/decorators/page-type";
import { RegionDefinition } from "@/lib/decorators/region-definition";
import { Region } from "@/components/region";

@PageType({
  name: "Category Page",
  description: "Category listing page with product grid",
  supportedAspectTypes: ["category"],
})
@RegionDefinition([
  {
    id: "banner",
    name: "Category Banner",
    maxComponents: 1,
  },
  {
    id: "promoContent",
    name: "Promotional Content",
    maxComponents: 3,
  },
])
export class CategoryPageMetadata {}

export async function loader({ params, context }: LoaderFunctionArgs) {
  const page = await fetchPageWithComponentData({
    pageId: "category",
    categoryId: params.categoryId,
  });

  return { page };
}

export default function CategoryPage({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      {/* Page-level region */}
      <Region page={loaderData.page} regionId="banner" fallbackElement={<BannerSkeleton />} />

      {/* Main category content */}
      <ProductGrid categoryId={loaderData.categoryId} />

      {/* Additional promotional content */}
      <Region page={loaderData.page} regionId="promoContent" />
    </div>
  );
}
```

### Page Metadata Options

| Option                 | Description                                           |
| ---------------------- | ----------------------------------------------------- |
| `name`                 | Display name in Business Manager                      |
| `description`          | Page description                                      |
| `supportedAspectTypes` | The B2C Commerce aspect types that this page supports |

### Supported Aspect Types

| Aspect Type | Use Case             | Valid Assignments       |
| ----------- | -------------------- | ----------------------- |
| `pdp`       | Product Detail Pages | Categories and Products |
| `plp`       | Category Pages       | Categories              |

### Region Usage in Pages

Use **page mode** for top-level regions.

```tsx
<Region
  page={loaderData.page} // Page data from loader
  regionId="main" // Region ID matching @RegionDefinition
  fallbackElement={<Skeleton />} // Optional: Loading state
  errorElement={<ErrorMessage />} // Optional: Error state
/>
```

Use **component mode** for nested regions inside container components.

```tsx
<Region
  component={component} // Component object (synchronous)
  regionId="content" // Region ID
/>
```

**important:** Don't mix `page` and `component` props. Use one or the other.

## Generate Cartridges

The build process automatically generates B2C Commerce cartridge metadata from your decorated components and pages.

### Automatic Generation on Build

```bash
pnpm build
```

This runs `pnpm cartridge:generate` as part of the build process and does these steps.

1. Scans `src/` for `@Component` and `@PageType` decorators.
2. Extracts metadata from decorators.
3. Generates JSON files in `cartridges/app_storefrontnext_base/cartridge/experience/`.

### Manual Generation

```bash
pnpm cartridge:generate
```

### Generated Output Structure

```
cartridges/app_storefrontnext_base/cartridge/experience/
├── components/
│   └── odyssey_base/
│       ├── hero.json
│       ├── productCarousel.json
│       └── grid.json
├── pages/
│   ├── homePage.json
│   ├── productDetailPage.json
│   └── categoryPage.json
└── aspects/
    └── (aspect definitions)
```

### Generated Metadata Format

**Component metadata** (`hero.json`):

```json
{
  "name": "Hero Banner",
  "description": "Prominent banner section with title, image, and CTA",
  "group": "odyssey_base",
  "arch_type": "headless",
  "region_definitions": [],
  "attribute_definition_groups": [
    {
      "id": "hero",
      "name": "Hero Banner",
      "attribute_definitions": [
        {
          "id": "title",
          "name": "Title",
          "type": "string",
          "required": false
        }
      ]
    }
  ]
}
```

**Page metadata** (`homePage.json`):

```json
{
  "name": "Home Page",
  "description": "Main landing page",
  "arch_type": "headless",
  "region_definitions": [
    {
      "id": "main",
      "name": "Main Content Region",
      "max_components": 5
    }
  ],
  "supported_aspect_types": [],
  "route": "/"
}
```

### Key Notes

- **`arch_type: "headless"`**: All generated metadata includes `arch_type: "headless"`. This flag tells Page Designer that the page or component is rendered by the headless storefront (Storefront Next) rather than by a B2C Commerce controller. When Page Designer opens a page marked as headless, it loads the Managed Runtime (MRT) storefront URL in the editor iframe instead of a classic B2C Commerce controller-based page. This behavior enables Page Designer to render and edit React components directly.
- **`route`**: Automatically extracted from your file-based routing structure (for example, `src/routes/category.$categoryId.tsx` → `/category/:categoryId`). When Page Designer loads a page, the `{page_route}` variable in the iframe URL is resolved using the `route` field from the page type metadata.
- **Manual additions**: If you must add metadata manually, place JSON files in the `cartridges/` directory structure.

---

## Deploy Cartridges

Deploy the generated cartridge to your B2C Commerce instance.

### Prerequisites

Create a `dw.json` file in the `storefront-next-dev` package directory.

```json
{
  "hostname": "your-instance.demandware.net",
  "username": "your-username",
  "password": "your-password",
  "code-version": "version1"
}
```

**note:** For more detailed steps for setting up the `dw.json` file and deploying the cartridge, see [Deploy the Storefront Next Cartridge for Page Designer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pd-deploy-cartridge.md).

### Deploy the Cartridge with the `push` Command

To deploy the cartridge, run this command.

```bash
pnpm push
```

The command:

1. Generates cartridge metadata if `GENERATE_AND_DEPLOY_CARTRIDGE_ON_MRT_PUSH` is enabled.
2. Deploys the cartridge to B2C Commerce via WebDAV.
3. Pushes the storefront bundle to Managed Runtime.

### Manual Cartridge Deployment

To deploy only the cartridge without pushing to Managed Runtime (MRT), use these commands.

```bash
# Generate metadata
pnpm cartridge:generate

# Deploy to B2C Commerce
pnpm cartridge:deploy
```

### Deployment Process

1. **ZIP Creation**: Cartridge directory is zipped.
2. **Upload**: ZIP uploaded to B2C Commerce via WebDAV.
3. **Unzip**: Archive extracted on the server.
4. **Cleanup**: Temporary ZIP file deleted.

## Business Manager Setup

### Prerequisites

1. **Cartridge Path**: Add `app_storefrontnext_base` to your site's cartridge path in Business Manager.

   - Go to **Administration > Sites > Manage Sites > [Your Site] > Settings**.
   - Add `app_storefrontnext_base` to the cartridge path.

2. **MRT Linking**: Make sure that your MRT environment is linked to your B2C Commerce instance. The MRT environment is linked if the storefront was set up in Business Manager, or you can link it in MRT's Environment Settings page. The MRT storefront URL in Page Designer is automatically configured when exactly one MRT environment is linked to the specific B2C Commerce instance and site ID. No manual URL configuration is required. Page Designer uses this URL to populate the `headless_url` object, (containing `edit_url`, `preview_url`, and `info_url`) that controls where the editor iframe points.

   If the Page Designer iframe appears blank, verify that your MRT environment is correctly linked to your B2C Commerce instance and site.

### Using Page Designer

1. Go to **Merchant Tools > Content > Page Designer**.
2. Create a page or edit an existing one.
3. Select a page type that matches your Storefront Next page types.
4. Add components to regions using the visual editor.
5. Configure component attributes in the properties panel.
6. Publish the page.

### Page Assignment

You can assign pages to:

- **Specific entities** - A particular product, category, or content asset
- **Default pages** - Fallback for all entities of a type

### Live Preview

When editing in Page Designer:

1. Business Manager reads the `route` from page metadata.
2. Loads your storefront in an iframe with the appropriate URL.
3. Shows live preview as you configure components.

For the storefront to load inside the Page Designer iframe, the `frame-ancestors` Content Security Policy directive must allow both `'self'` and your Business Manager hostname (for example, `https://your-instance.commercecloud.salesforce.com`). The default value of `'self'` isn't sufficient. Extend the directive in `config.server.ts`. See [Security Response Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-security-headers.md).

**note:** Previewing a local development environment in Page Designer isn't supported. To use Page Designer's live preview, deploy your storefront to a Managed Runtime environment. For a local development workaround, see [Local Development](#local-development).

### Shopper Context Preview

To preview a page in the context of a specific Customer Group or on a specific date:

1. **Enable the feature toggle in Business Manager**: Turn on the "Shopper Context" feature toggle in Business Manager.
2. **Configure MRT environment variable**: Set `PUBLIC__app__features__shopperContext__enabled` to `true` in your Managed Runtime environment.

### Known Limitations

- **No live editing without saving**: Changes made in the Page Designer properties panel aren't reflected in the preview iframe in real time. You must save changes to see them in the preview.
- **Hybrid storefronts — link builder restriction**: In hybrid deployments (SFRA and Storefront Next running together), the Page Designer link builder can only link to pages within the same technology stack. Headless pages can link to other headless pages, and SFRA pages can link to other SFRA pages, but cross-stack linking isn't supported.

### Local Development

Local development with Page Designer using `localhost` URLs isn't supported. To test Page Designer integration, deploy your storefront to an MRT environment.

As a temporary workaround, use a local development cartridge to redirect Page Designer to your local server. Download the cartridge from [Local Dev Cartridge (ZIP)](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/pd_sfnext_local_dev.zip).

#### Setup Steps

1. Deploy the cartridge to your B2C Commerce instance.
2. Add the cartridge to your Business Manager cartridge path.
3. In Business Manager, go to **Administration > SF Next Local Dev**.
4. Enter your local development URL (for example, `http://localhost:3000`).
5. Run the service worker.
6. Click **Enable Headless URL Override**.

**important:** Click the checkbox only once. Due to a known UI limitation, the checkbox doesn't reflect the correct state after toggling.

### Troubleshooting

| Issue                          | Solution                                                                                                                                                                                                                                             |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Components don't appear        | Verify that the cartridge is in the cartridge path and deployed.                                                                                                                                                                                     |
| Page doesn't load              | Check that `route` in page metadata matches your routing.                                                                                                                                                                                            |
| Attributes aren't configurable | Make sure that `@AttributeDefinition` decorators are correct.                                                                                                                                                                                        |
| Region is empty                | Verify that `regionId` matches between code and metadata.                                                                                                                                                                                            |
| PD iframe is blank             | Verify that your MRT environment is linked to the correct B2C Commerce instance and site ID. See [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html). |
| Preview flickering/refreshing  | Ensure that the "cookies enabled" setting is configured in your MRT environment. See [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html).             |

## Merchant Storefront Next Customization

Page Designer contains Storefront Next template pages that merchants can add and customize. Page Designer can connect to the storefront associated with a site. See
[Page Designer Content Management for Merchants](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer-customize-sf.md).

## Content Slot Migration from SFRA

If you're migrating from Salesforce Storefront Reference Architecture (SFRA) to Storefront Next and use content slots, follow this workaround until the planned Embedded Content feature becomes available. See [Migrate Content Slots from SFRA to Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer-content-slots.md).

<!-- document id=da95540447ff658eba808ffb464b50c689fd5dbd9fd66240038d76cd6f788659 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-password-reset.md -->

# Password Reset with Callback URI

Learn to implement password reset for B2C Commerce with the Shopper Login and API Access Service (SLAS). This allows shoppers to update their passwords and keep their accounts secure.

The password reset flow for both public and private clients uses two SLAS endpoints, one to get a password reset token and one to reset the password using the token.
The two SLAS endpoints, [`shopper-login:getPasswordResetToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getPasswordResetToken) and [`shopper-login:resetPassword`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=resetPassword), provide a callback URL for the SLAS service to send the password reset token.

SLAS password reset tokens expire after 10 minutes.

## Overview

1. Set up a publicly accessible callback URL to receive webhook requests from the SLAS service and send reset tokens to shoppers via email, SMS, or other means.
2. Configure your SLAS Client with that callback URL.
3. Generate a unique code challenge and code verifier.
4. Create a reset form that calls `shopper-login:getPasswordResetToken` with your callback URL, beginning the process.
5. To avoid the need for a PKCE code_challenge or code_verifier, use the `hint` query parameter with a value of `cross_device`.
6. Create an update form that the shopper arrives at following the link your server sent them. The shopper provides their new password as well as the token, and their password is updated. They can then login using their new password.

## Prerequisites

- A publicly accessible callback URL, such as an ECOM instance, Managed Runtime environment, or your own server.
  **tip:** If you don't currently have a callback URL, use a public service such as [Webhook.site](https://www.webhook.site) for testing purposes.

- A SLAS Client configured with your callback URL.

## SLAS Password Reset Flow

1. Call the SLAS endpoint `shopper-login:getPasswordResetToken` to begin the password reset process.
   1. Provide your publicly accessible `callback_uri` that receives the webhook request from the SLAS web service with the password reset payload.
   <!-- 2. Generate a unique code challenge and code verifier and store the code verifier in a secure location.
   :::note
   If you use a `code_challenge`, you must complete the SLAS password reset flow with a `code_verifier`. If you mix the request with a hint parameter, a validation error is returned.
   ::: -->
2. The `callback_uri` is validated against the SLAS Client's allowed callback URLs.
3. If the `callback_uri` is valid, SLAS sends a POST request to the callback URL with the password reset token, for example:

```json
{
  "email_id": "shopper@example.com",
  "login_id": "shopper@example.com",
  "phone": "123-555-1212",
  "customer_id": "abq96kjBGjQhBEgYHNWmemnL8l",
  "token": "95107856"
}
```

- The SLAS web service makes an HTTP POST request with `Content-Type: application/json` to your callback URL. The payload contains the `token`, which is an eight-digit numeric value needed to reset the password, along with potential ways to contact the shopper, including the email address and phone number associated with their profile if available. Commonly, the shopper’s `email_id` and `login_id` is the same, but in B2C Commerce, it is possible for a shopper's email address to be different than the value they use to log in, which is the `login_id`.

4. The server hosting the callback URL sends the token to the shopper via email, SMS, or other means. Typically the token is sent as part of a link that a shopper can click or as a value that the shopper needs to enter in a form.
5. The shopper provides the token to the SLAS endpoint `shopper-login:resetPassword` along with their new password to complete the process.
   **note:** The new password must meet password complexity requires set on the B2C Commerce site, otherwise the request is rejected.

![SLAS password reset login process without PKCE](https://developer.salesforce.com/docs/media/commerce-api/slas-password-reset-login-flow-non-pkce.png)

## Validate the Callback Payload

Refer to the steps in [Verify SLAS Callback Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md#verify-the-slas-password-action-callback).

## Examples

To reset a password both public and private clients, two separate requests are made:

1. Request a password reset token.
2. After the reset token is provided by the customer, request a password reset using the reset token.

### SLAS Public Client

1. Request a password reset token:

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/bgvn_stg/oauth2/password/reset' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'mode=callback' \
--data-urlencode 'channel_id=SiteGenesis' \
--data-urlencode 'client_id={public_client_id}' \
--data-urlencode 'callback_uri=http://localhost:9003/callback' \
--data-urlencode 'hint=cross_device'
```

2. After the reset token is provided by the customer, request a password reset using the reset token:

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/bgvn_stg/oauth2/password/action' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'pwd_action_token=60045027' \
--data-urlencode 'client_id={public_client_id}' \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'new_password={new_password}' \
--data-urlencode 'channel_id=SiteGenesis'
```

### SLAS Private Client

1. Request a password reset token:

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/bgvn_stg/oauth2/password/reset' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: {base64_client_credentials} \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'mode=callback' \
--data-urlencode 'channel_id=SiteGenesis' \
--data-urlencode 'callback_uri=https://localhost:9010/callback' \
--data-urlencode 'hint=cross_device'
```

2. After the reset token is provided by the customer, request a password reset using the reset token:

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/bgvn_stg/oauth2/password/action' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: {base64_client_credentials}' \
--data-urlencode 'pwd_action_token=19362888' \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'new_password=Salesforce3!' \
--data-urlencode 'channel_id=SiteGenesis'
```

## Constraints

Your callback URL _must_ be accessible to the SLAS webservice. That means it cannot use an authentication mechanism for incoming requests. As a specific example, you can’t use B2C Commerce Storefront Protection with SLAS Password Reset.

<!-- document id=2b617e8db0f1675dc7e4541bea7a64fbee63d5b17f8cf91f7c0e92903f2a1a71 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-password-reset-email.md -->

# Password Reset with Email

Use the Shopper Login and API Access Service (SLAS) to send a password reset email to a registered shopper. The shopper can then update their password after verifying a one-time password (OTP) contained in the email.

The implementation described in this guide requires no third-party integration. For instructions on password reset using a callback URI instead, see [Password Reset with Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html).

## Considerations

- Registration: The shopper’s email must be registered with B2C Commerce.
- Volume limits: The monthly quota limit for the `getPasswordResetToken` endpoint with `mode` set to `email` is 1,000 requests per non-production tenant instance. The `getPasswordResetToken` endpoint also has a maximum of 3 requests per user for every 10-minute window.
- SLAS client: Your site must have a SLAS client. Both private and public clients are supported. See [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.html).
- DMARC policies: Support is currently limited to email sender domains with relaxed DMARC policies (`p=none`).

## 1\. Add an Email Sender to the SLAS Client

An email sender specifies the sender address that SLAS uses to deliver passwordless login emails, including password reset emails. Use the SLAS Admin UI to add an email sender to an existing SLAS client. Follow the steps to [Add an Email Sender](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#2-add-an-email-sender) as described in the [Password Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#2-add-an-email-sender) guide.

## 2\. Create a Password Action Template

SLAS uses password action templates to construct the emails used for password resets, as well as [passwordless login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#3-configure-email-templates).

To create the password action template for password reset emails, make a PUT request to the [registerPwdlessTemplate](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerPwdlessTemplate) endpoint. Set the `actionType` parameter to `PWD_RESET_ACTION` and the `templateType` parameter to `EMAIL`. Alternatively, the `PWD_RESET_CROSS_DEVICE_ACTION` is used if the `hint` parameter in the `getPasswordResetToken` call is `cross_device`.

In the `link` parameter, use `${token}`, `${name}`, and `${user_id}` substitutions. In the `template` parameter, use the above and the `${link}` substitution.

Emails with OTP that use the SLAS APIs for `getPasswordResetToken` will use this template to send emails to shoppers.

Here’s an example request body for creating a password reset email template:

```json
{
  "channelId": "SiteGenesis",
  "name": "Password Reset Email Template",
  "subject": "Password Reset Token Request",
  "link": "https://store.com/reset-password?token=${token}&email=${user_id}",
  "locale": "en-us",
  "actionType": "PWD_RESET_ACTION",
  "templateType": "EMAIL",
  "template": "Password Reset Request\n\nHello ${name},\n\nYou're receiving this because you requested a password reset for your account.\n${link}\n\nThis link will expire shortly. Do not share it with anyone."
}
```

## 3\. Implement the Password Reset Token Flow

1. Call the [getPasswordResetToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getPasswordResetToken) endpoint to trigger the email with the OTP. Setting the mode to email instructs SLAS to send the numeric token directly to the shopper's registered email address.
2. Then, call the [resetPassword](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=resetPassword) endpoint with the shopper’s numeric token to complete the password reset flow.

### SLAS Private Client Example:

1. Request a password reset token

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/password/reset' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {base64_client_credentials}' \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'mode=email' \
--data-urlencode 'channel_id=SiteGenesis' \
--data-urlencode 'code_challenge=si9PvGgxix3wYge5GrPJO-EPJ9JxLhn6y2_fb8PlUwg'
```

2. After the customer provides the reset token, use it to request a password reset:

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/password/action' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {base64_client_credentials}' \
--data-urlencode 'pwd_action_token=12345678' \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'new_password=NewSecurePassword123!' \
--data-urlencode 'channel_id=SiteGenesis' \
--data-urlencode 'code_verifier=WyGUskLWv5rRF_-jQdMnKcm48xJzo_CQoMGMKtyQfTh-vhMfPUfGGGesHCP2bQsZ5F07p08QJIJOFlcFAtEMBA'
```

### SLAS Public Client Example

1. Request a password reset token:

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/password/reset' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=12345678-1234-1234-1234-123456789012' \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'mode=email' \
--data-urlencode 'channel_id=SiteGenesis' \
--data-urlencode 'code_challenge=si9PvGgxix3wYge5GrPJO-EPJ9JxLhn6y2_fb8PlUwg'
```

2. After the customer provides the reset token, use it to request a password reset:

```bash
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/password/action' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=12345678-1234-1234-1234-123456789012' \
--data-urlencode 'pwd_action_token=12345678' \
--data-urlencode 'user_id=darth.vader' \
--data-urlencode 'new_password=NewSecurePassword123!' \
--data-urlencode 'channel_id=SiteGenesis' \
--data-urlencode 'code_verifier=WyGUskLWv5rRF_-jQdMnKcm48xJzo_CQoMGMKtyQfTh-vhMfPUfGGGesHCP2bQsZ5F07p08QJIJOFlcFAtEMBA'
```

## Troubleshooting

To diagnose issues with password reset emails, use Log Center. For details, see [Troubleshooting with Log Center](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html#troubleshooting-with-log-center).

<!-- document id=37fe91a14bdd2087bab4a77aa3989550f1a58358aaf3ef15d444c7e0aba13a34 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-passwordless-login-overview.md -->

# Passwordless Login

Passwordless login is a way to verify a shopper’s identity without using a password. It offers protection against cyberattacks, such as phishing and brute-force password cracking. Passwordless login systems use authentication methods that are more secure than regular passwords, including one-time passwords (OTPs) and passkeys.

The Shopper Login and API Access Service (SLAS) supports multiple passwordless login methods:

- [Passwordless Login with One-Time Passwords using Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html): Send an 8-digit, time-based OTP to your shopper for authentication. To use this method, you must have:
  - A publicly accessible callback URL, such as a B2C Commerce instance, Managed Runtime environment, or your own server.
  - A mechanism to share the passwordless token with the shopper, such as email or SMS.
  - A SLAS private client configured to work with passwordless login.

**note:** The OTP Callback URI method also supports shopper registration. See [Register a Customer with Passwordless Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-registration.html).

- [Passwordless Login with SMS Service Provider](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-sms.html): Send a verification code to shoppers via SMS. To use this method, you must have an SMS service provider such as Agentforce Marketing or Amazon SNS.
- [Passwordless Login with Passkeys](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html): Authenticate your shoppers using Fast IDentity Online 2 (FIDO2) credentials, also known as passkeys. To use this method, you must have a client-side implementation to serve as the interface for calling the browser's WebAuthn API. SLAS private and public clients both support passkeys.
- [Passwordless Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html): Send registered shoppers an OTP via email. To use this method, you must configure a SLAS private client to work with passwordless login. No third-party integration is required.

## Choosing a Passwordless Method

Select the passwordless authentication method that best fits your implementation requirements, infrastructure, and user experience goals.

Use this section to choose a SLAS passwordless pattern first, then confirm storefront-specific support in the feature support section and Storefront Next support pages.

For current storefront support and minimum-version requirements, use the [Passwordless Login Feature Support](#passwordless-login-feature-support) section in this topic as the source of truth.

### Decision Guidance

**Choose OTP with Callback URI when:**
- You need flexibility in OTP delivery channels (email, SMS, or custom)
  - If you already use Agentforce Marketing or Amazon SNS, you can use them to handle SMS OTP delivery with callback URI.

- You want to control the entire authentication flow
- You already have a notification infrastructure

**Choose Passkeys when:**
- You want the highest security level
- Your users expect biometric authentication
- You want to eliminate passwords entirely

**Choose Email OTP when:**
- You want the fastest implementation with no third-party dependencies
- Email delivery is sufficient for your use case
- You want to minimize infrastructure complexity

## Passwordless Login Feature Support

Headless storefront implementations can support all Passwordless Login features:

- [Passwordless Login with One-Time Passwords using Callback URI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html)
- [Passwordless Login with Passkeys](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html)
- [Passwordless Login with SMS Service Provider](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-sms.html)
- [Passwordless Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html)
- [Register a Customer with Passwordless Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-registration.html)

Storefront Next has storefront-specific support constraints. To review feature availability, see:

- [Login and Registration Support in Storefront Next](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-login-support.html)
- [Login and Registration Support for Hybrid Storefront Next Storefronts](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-login-support-hybrid.html)

**note:** Passwordless Login isn't supported for SFRA, SFRA with Hybrid Auth, or PWA Kit with Hybrid Auth.

<!-- document id=ab03308d9a0a60c75cdbfc65d73c3515ef07d59080c12647868c011d50a2dbcb url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-passwordless-login.md -->

# Passwordless Login for Storefront Next

Storefront Next supports passwordless login by using the Shopper Login and API Access Service (SLAS). Shoppers can securely log in by using a one-time passcode (OTP) or a magic link delivered by email or SMS.

If enabled, passwordless login is the default login mode. Hybrid storefronts don’t support passwordless login.

## Prerequisites

- Configure a SLAS private client with passwordless login enabled. For instructions, see [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html?q=passwordless#configure-a-slas-private-client) in the _B2C Commerce API Developer Guide_.
- In `config.server.ts`, set `commerce.api.privateKeyEnabled` to true. If false, passwordless login is disabled at run time, regardless of the `features.passwordlessLogin.enabled` flag.
- Shoppers must log in to your site with their username and password at least once before they can use passwordless login.

## Configure Settings

To control passwordless login settings, update `features.passwordlessLogin` in `config.server.ts`.

```typescript
passwordlessLogin: {
    enabled: false,
    mode: 'email',
    callbackUri: '/passwordless-login-callback',
    landingUri: '/login',
}
```

- `enabled`: Specifies whether passwordless login is enabled (`true`) or not.
- `mode`: The mode used to deliver the OTP or magic link to the shopper (`email`, `callback`, or `sms`).
- `callbackUri`: The relative or absolute URI that SLAS posts shopper credentials to. Required when `mode` is set to `callback`.
- `landingUri`: An additional path to `/login` that’s embedded in the magic link that shoppers click to authenticate.

The OTP code length is a shared auth setting. Valid values are 6 or 8. The value must match the OTP length configured in your SLAS client.

```typescript
auth: {
    otpLength: 8,
}
```

You can override configuration options by using MRT environment variables with the `PUBLIC__` prefix.

```bash
PUBLIC__app__features__passwordlessLogin__enabled=true
PUBLIC__app__features__passwordlessLogin__mode=callback
PUBLIC__app__features__passwordlessLogin__callbackUri=https://www.example.com/passwordless-login-callback
PUBLIC__app__auth__otpLength=8
```

### Configuration Options

This table lists the environment variables that override the passwordless login defaults in `config.server.ts`. Each variable is optional—omit it to keep the default.

| Variable                                                | Default                        | Purpose                                                                                                    |
| ------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `PUBLIC__app__features__passwordlessLogin__enabled`     | `false`                        | Turns passwordless login on or off.                                                                        |
| `PUBLIC__app__features__passwordlessLogin__mode`        | `email`                        | Delivery mode: `email`, `callback`, or `sms`.                                                              |
| `PUBLIC__app__features__passwordlessLogin__callbackUri` | `/passwordless-login-callback` | Path or absolute URL that SLAS posts shopper credentials to. Required when `mode` is `callback`.           |
| `PUBLIC__app__features__passwordlessLogin__landingUri`  | `/login`                       | Path embedded in the magic link that shoppers click to authenticate.                                       |
| `PUBLIC__app__features__otpRequest__mode`               | `email`                        | Delivery mode for OTP codes during email verification: `email` or `callback`.                              |
| `PUBLIC__app__features__otpRequest__callbackUri`        | —                              | Absolute URL of the external service that delivers the OTP. Required when `otpRequest.mode` is `callback`. |
| `PUBLIC__app__features__resetPassword__mode`            | `email`                        | Delivery mode for reset password: `email` or `callback`.                                                   |
| `PUBLIC__app__features__resetPassword__callbackUri`     | `/reset-password-callback`     | Path or absolute URL for the reset password callback. Required when `resetPassword.mode` is `callback`.    |
| `PUBLIC__app__features__resetPassword__landingUri`      | `/reset-password`              | Path where shoppers create a new password after requesting a reset.                                        |
| `PUBLIC__app__auth__otpLength`                          | `6`                            | OTP code length. Valid values are `6` or `8`. Must match the SLAS client.                                  |

## Delivery Modes

### Email Mode (SLAS Native Email Service)

When `mode` is set to `email`, SLAS sends the OTP or magic link email without third-party integration. This passwordless login method doesn’t require a callback URI.

1. To use this method, configure SLAS for passwordless login with email. See [Passwordless Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html) in the _B2C Commerce API Developer Guide_.
2. Then, in `config.server.ts`, enable passwordless login.

```typescript
   passwordlessLogin: {
        enabled: true,
        mode: 'email',
        landingUri: '/login',
    }
```

3. Set `commerce.api.privateKeyEnabled` to `true`

### Callback Mode (Custom Delivery)

When `mode` is set to `callback`, SLAS makes an HTTP POST to your callback URI. The POST request includes the shopper's email and a token. Your server must then send the token to the shopper by using email, SMS, or any other channel. You can use this mode with an external callback URL or a custom POST endpoint in your storefront.

After setting `callbackUri` in `config.server.ts`, you must also allowlist the full callback URL in the SLAS client configuration:

1. Access SLAS Admin UI: Log in to your Salesforce B2C Commerce instance and go to the SLAS Admin section.
2. Create or edit a client: Select your SLAS client where you want to manage callback URLs.
3. Add allowed URLs: In the client configuration, provide a list of the valid callback URLs for your site.

#### Option 1 — External Callback URL

Set `callbackUri` to any publicly accessible external endpoint that can process the token and deliver it to the shopper. Examples include a B2C Commerce instance, a Managed Runtime environment, or your own server.

1. Set the full external URL directly in `config.server.ts` or by using an MRT environment variable.

```typescript
PUBLIC__app__features__passwordlessLogin__callbackUri =
  "https://external-service.example.com/passwordless-callback";
```

2. Register the same URL in the SLAS Admin UI Callback URL field.

#### Option 2 — Custom POST Endpoint in Your Storefront

Storefront Next includes a callback handler at the path configured in `callbackUri` (default: /passwordless-login-callback). Replace the logic inside `handlePasswordlessCallback` in `src/lib/passwordless-login.ts`. The function receives the validated `email_id` and token from SLAS. Build and send your own message with a service provider.

<!--
#### Option 3 – Use Marketing Cloud as the Service Provider

The built-in `handlePasswordlessCallback` contains a template integration with Salesforce Marketing Cloud as a reference implementation.

Set these variables to integrate Salesforce Marketing Cloud as the provider.

```typescript
MARKETING_CLOUD_CLIENT_ID=<your-client-id>
MARKETING_CLOUD_CLIENT_SECRET=<your-client-secret>
MARKETING_CLOUD_SUBDOMAIN=<your-subdomain>
MARKETING_CLOUD_PASSWORDLESS_LOGIN_TEMPLATE=<event-definition-key>
```
-->

## Best Practices for Passwordless Login

- Implement rate limiting to prevent abuse of the passwordless login feature. For example, if you use embedded CDN (eCDN), you can apply eCDN Rate Limiting Rules.
- Use security measures to protect shopper accounts. For example, if you use a third-party content delivery network (CDN) such as Cloudfare, you can block requests by Threat Score.
- Track shopper usage of authentication options and diagnose issues efficiently. For example, use Log Center to access logs from Managed Runtime (MRT) and your B2C Commerce instance.

<!-- document id=1e82a428b2f77e10f47952fb7c1f71512cccfd1016b88c67824af82f8a14d44d url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-passwordless-login-email.md -->

# Passwordless Login with Email

Use the Shopper Login and API Access Service (SLAS) to send a registered shopper a one-time password (OTP) through email. No third-party integration is required for passwordless login with email.

## Considerations

- Registration: The shopper’s email must be registered with B2C Commerce.
- Volume limits: Sending emails for passwordless login counts towards your overall volume. The monthly quota limit for email mode for each `getPasswordResetToken`, `authorizePasswordlessCustomer`, `authorizeWebauthnRegistration` endpoint is 1,000 requests per non-production tenant instance. There’s also a maximum of 6 requests per user for every 10-minute window for the `authorizePasswordlessCustomer` and `authorizeWebauthnRegistration` endpoint, and 3 requests per user for every 10-minute window for the `getPasswordResetToken` endpoint.
- OTP Expiration: Generating a new OTP immediately invalidates any previously issued OTPs. The shopper must use the most recently generated code for passwordless login.
- DMARC policies: Support is currently limited to email sender domains with relaxed DMARC policies (`p=none`).

## 1. Configure a SLAS Private Client

If you haven’t already created a SLAS private client, follow the instructions in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client) to create one and return to this guide. Only private clients can be used for passwordless login.

To configure a private client for passwordless login, follow these steps in the SLAS Admin UI:

1. From the top navigation, click **Clients**.
2. Click the **Edit** link next to the client ID that you created earlier.
3. In the Scopes field, add `sfcc.pwdless_login`.
4. To use 6-digit OTPs, select **Six Digit TOTP?**. If unselected, the default OTP length is 8 digits. This setting can only be configured for an existing client.

![Edit client screen with Six Digit TOTP setting selected](https://developer.salesforce.com/docs/media/commerce-api/slas-six-digit-totp.png)

5. Save the client.

## 2. Configure a Domain Identity

Use a domain identity to send passwordless login and password reset emails from a delegated subdomain that you own (for example, `mail.merchant.com`). The delegated subdomain uses DMARC (Domain-based Message Authentication, Reporting, and Conformance) to ensure alignment between the domain your customers see in their inbox and the underlying Sender Policy Framework (SPF) and DomainKeys Identified Mail (DKIM) security checks managed by SLAS.

By handling these technical authentications through your delegated subdomain, SLAS verifies its status as an authorized sender to receiving mail servers. This verification enables the enforcement of a strict security policy, with the policy tag set to `reject`.

```
v=DMARC1; p=reject;
```

The `p=reject` DMARC policy tag instructs Internet Service Providers (ISPs) to discard mail from your delegated subdomain that doesn’t authenticate properly. This policy blocks any fraudulent emails attempting to spoof your domain, while allowing your legitimate account-related business communications to reach your customers reliably.

### Domain Identity Prerequisites

Before you create a domain identity, make sure that you:

- Own the domain or subdomain that you want to use (for example, `mail.example.com`).  
- Have access to your domain registrar's DNS settings so you can add NS (nameserver) delegation records.  
- Have a configured SLAS private client.

### Domain Identity Limits

- You can create a maximum of 2 domain identities per tenant instance.  
- Subdomains must be globally unique across all SLAS tenants. If your desired subdomain is used by another tenant in the same realm, you receive an error.  
- Domain identities can be shared across multiple channels within the same client.

### 2a. Create a Domain Identity

1. From the [SLAS Admin UI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html), navigate to your client and click **Add Domain Identity**.

![New Domain Identity button in the SLAS Admin UI](https://developer.salesforce.com/docs/media/commerce-api/slas-add-domain-identity.png)

2. In the Subdomain field, enter the subdomain you want SLAS to send emails from (for example, `mail.example.com`).  
3. For From Address Prefix, enter the local part of the sender address (for example, `noreply`). This value defaults to `noreply` if left blank. The final sender address is `\<prefix\>@\<subdomain\>` (for example, `noreply@mail.example.com`).

![New Domain Identity details in the SLAS Admin UI](https://developer.salesforce.com/docs/media/commerce-api/slas-new-domain-identity.png)

4. Click **Submit**.

**important:** The domain identity shows a Pending verification status immediately after creation. Verification is completed after DNS delegation is in place and SLAS has confirmed the DKIM records.

### 2b. Delegate DNS to SLAS

After you create the domain identity, SLAS provides a set of NS (nameserver) records for your subdomain's hosted zone. Add these NS records to your domain registrar's DNS configuration as a delegation for the subdomain.

To allow SLAS to manage the technical authentication (DKIM/SPF) for your subdomain, you must **delegate authority** for that specific subdomain to SLAS. Add **four NS (Name Server) records** to your **parent domain's** DNS zone. This configuration acts as a pointer, telling the internet: *"If you are looking for mail.example.com, go ask these servers."*

* **NS values:** After you create the domain identity, the SLAS Admin UI displays the NS values.  
* **Where to add:** Add these records to your **root domain** (for example, `example.com`), not within a new zone for the subdomain itself.  
* **Record name:** The record name/host should be your subdomain (for example, `mail`).  
* **Record type:** The record type must be NS. Do not use CNAME or A records for delegation.

For example, if your subdomain is `mail.example.com`, add these NS records to the DNS zone for `example.com` at your registrar. 

```
mail.example.com.  NS  ns1.awsdns-01.org.
mail.example.com.  NS  ns2.awsdns-02.co.uk.
mail.example.com.  NS  ns3.awsdns-03.com.
mail.example.com.  NS  ns4.awsdns-04.net.
```

After delegation is in place, AWS SES automatically verifies the DKIM CNAME records. This process typically completes within a few minutes to 72 hours depending on DNS propagation.

### 2c. Verify the Domain Identity

Check the domain identity verification status in the SLAS Admin UI. Each time you view the domain identity detail page, the verification status refreshes. 

* A status of Verified means  the domain identity is ready to use for sending emails. The DKIM status returned by SES is SUCCESS.  
* A status of Pending means DNS propagation is still in progress. Continue checking back until the status changes. No action is required unless 72 hours have passed without verification.

![List of domain identities with status column showing verified or unverivied.](https://developer.salesforce.com/docs/media/commerce-api/slas-domain-identity-status.png)

### 2d. Assign the Domain Identity to a Channel

Domain identities are assigned to channels, not directly to clients. This enables multiple channels to either share a single domain identity or use different domain identities. 

1. From the SLAS Admin UI, navigate to your client and click **Edit** next to the channel you want to configure.  
2. In the Domain Identity dropdown, select the domain identity you created.  
3. (Optional) To use this domain identity as a fallback for channels that don’t have a domain identity assigned, select **Cross Channel**. When a channel has no domain identity configured and a cross-channel is set separately, SLAS falls back to the cross-channel's domain identity.  
4. Save the channel.

![Edit Site Configuration page with domain identity dropdown highlighted.](https://developer.salesforce.com/docs/media/commerce-api/slas-domain-identity-channel.png)

### Manage Domain Identities

#### View All Domain Identities for a Tenant

To view all domain identities associated with your tenant, check the client detail page in the SLAS Admin UI. Click **Details** to show more information on the domain identity. The domain identity details include:

- Tenant Id: The tenant to which this domain identity belongs  
- Subdomain: The registered subdomain (for example, `mail.example.com`)  
- Sender Address: The full From address used in emails (for example, `noreply@mail.example.com`)  
- Verification Status:  Specifies whether the domain identity has been verified  
- NS Records: The nameserver records required for DNS delegation

Domain identities can't be edited after creation. To change the subdomain or from-address prefix, delete the existing domain identity and create a new one.

#### Delete a Domain Identity

**warning:** Deleting a domain identity removes the DNS record for the subdomain in SLAS. The four NS records that you pointed to will no longer host your delegated subdomain, so make sure to remove the NS records after domain identity deletion.

If the domain identity is used by any channel, you must remove it from all channels before deletion is allowed.

To delete a domain identity:

1. From the SLAS Admin UI, navigate to the domain identity detail page.  
2. Click **Delete**.  
3. A confirmation page lists all channels currently using the domain identity. If any channels are listed, remove the domain identity from those channels first.  
4. Once no channels are using it, confirm the deletion.

## 3. Configure Email Templates

Make a PUT request to the [registerPwdlessTemplate](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerPwdlessTemplate) endpoint. Set the `actionType` parameter to `PWDLESS_LOGIN` and the `templateType` parameter to `EMAIL`. In the `link` parameter, use `${token}`, `${name}`, and `${user_id}` substitutions. In the `template` parameter, use the above and the `${link}` substitution.

Emails with OTP that use the SLAS APIs for `authorizePasswordlessCustomer` will use these templates to send emails to shoppers. To send emails for the `authorizeWebauthnRegistration` endpoint, configure an additional email template with `actionType` as `WEBAUTHN_AUTHORIZE_USER`.

Here’s an example request body for creating a password login email template:

```json
{
  "channelId": "SiteGenesis",
  "name": "Passwordless Login Email Template",
  "subject": "Passwordless Login Token Request",
  "link": "https://store.com/login?token=${token}",
  "locale": "en-us",
  "actionType": "PWDLESS_LOGIN",
  "templateType": "EMAIL",
  "template": "Passwordless Login Request\n\nHello ${name},\n\nYou're receiving this e-mail because you requested a passwordless login token for your account.\n Use this link to login ${link}\n or copy and paste this code: ${token}\nThis code will expire shortly. Do not share it with anyone."
}
```

## 4. Use the API to Send and Receive OTP by Email

Finally, set the `mode` in the body of the request to `email` when using passwordless login or password reset to consume the out-of-the-box email OTP feature.

Example:

```sh
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/passwordless/login' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic *******' \
--data-urlencode 'user_id={user_email}' \
--data-urlencode 'mode=email' \
--data-urlencode 'channel_id={channel_id}' \
--data-urlencode 'locale=en-us'
```

## Troubleshooting with Log Center

If a shopper reports that an email wasn’t received, Log Center can provide insights into what happened.

- General Search: Query for “Email send from SLAS encountered an issue” in Log Center for your tenant ID. Make sure that the time period includes the estimated email send time.
- Shopper-Specific Search: To look for a specific log event related to a shopper, use one of these options:
  - Masked Email Address: Query for the masked shopper email address, of which a queryable form is usually the first three letters and an asterisk (for example, johndoe@gmail.com → query for `joh*`) or the first letter and an asterisk (for example, joe@gmail.com → query for `j*`).
  - Correlation ID: If you’ve logged the [correlation-Id](https://engineering.salesforce.com/investigate-issues-with-ease-by-adding-a-correlation-id-to-your-api-7a689413ff44/) when calling passwordless login for the shopper, directly search for the correlation ID in Log Center.

After finding the log event, examine the Type field to determine the issue:

| Type          | Description                                                                                                                                                                                          | Diagnostic Information                                                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Complaint     | The email successfully reached the recipient's mail server, but the recipient marked the message as spam.                                                                                            | `ComplaintFeedbackType` gives feedback provided by the ISP.             |
| Reject        | Email wasn’t attempted to be delivered, typically because a virus was detected.                                                                                                                      | The `reason` field can provide more detail for the flag.                |
| Bounce        | The email was permanently rejected (a hard bounce), typically meaning the mailbox address doesn’t exist. (Soft bounces are included when delivery attempts stop.)                                    | `DiagnosticCode` field provides more specific information if it exists. |

Here’s an example of a Bounce event in Log Center.  
![DeliveryDelay event in Log Center](https://developer.salesforce.com/docs/media/commerce-api/slas-bounce.png '{"class": "image-xl"}')

<!-- document id=a8102f248b70790e03023e4111182bb2118ec0784492fef1f20d1ff2126497f0 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-passwordless-login.md -->

# Passwordless Login with One-Time Passwords using Callback URI

Use the Shopper Login and API Access Service (SLAS) to send 8-digit, time-based one-time passwords (OTPs) to your shoppers for authentication. For an overview of other passwordless login methods, see [Passwordless Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-overview).

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


SLAS passwordless login tokens expire after 10 minutes.

## Overview

To understand how passwordless login with SLAS works, let’s look at an overview of the process.

**note:** The shopper must have an existing B2C Commerce or third-party IDP account, and must log in with a username and password prior to using passwordless login. Otherwise, you can call the [`authorizePasswordlessCustomer`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizePasswordlessCustomer) endpoint with the `register_customer` query parameter set to `true`. See [Register a Customer with Passwordless Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-registration.html).

![SLAS passwordless login authentication process and token exchange](https://developer.salesforce.com/docs/media/commerce-api/slas-passwordless-login-flow.png)

1. The shopper opens the app and logs in.
2. The shopper requests a passwordless login.
3. Your app calls the [authorizePasswordlessCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizePasswordlessCustomer) endpoint and provides a callback URI.
4. SLAS makes an HTTP POST request to your callback URI, including the shopper's contact information and an eight-digit time-based one-time password (TOTP) that can be used to authenticate the shopper.
5. The app sends TOTP to the shopper over email, SMS or another mechanism.
6. The shopper provides the TOTP to the app either by clicking a link or entering the it manually.
7. Your app calls the [getPasswordLessAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getPasswordLessAccessToken) endpoint to authenticate the shopper and get a SLAS access and refresh token.

**note:** After a successful passwordless login (including TOTP validation), SLAS updates the last-login timestamp on the shopper's B2C Commerce customer profile and increments the version of the customer profile object. This behavior applies starting with the 26.6 B2C Commerce release.

8. The access token can be used to make authorized requests on behalf of the shopper.

## Prerequisites

1. A publicly accessible callback URL, such as an B2C Commerce instance, Managed Runtime environment, or your own server. If you don't have a public callback URL, use a service like [Webhook.site](https://webhook.site/) for testing purposes.
2. A mechanism to share the passwordless token to the shopper, such as email or SMS.
3. A SLAS private client configured to work with passwordless login.

:::import
Include a secret value, such as an unguessable query string parameter, in your callback URL to validate that requests are from the SLAS web service.
:::

### Configure a SLAS Private Client

If you haven’t already created a SLAS private client, follow the instructions in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client) to create one and return to this guide. Only private clients can be used for passwordless login.

To configure a private client for passwordless login, follow these steps in the SLAS Admin UI:

1. From the top navigation, click **Clients**.
2. Click the **Edit** link next to the client ID that you created earlier.
3. In the Scopes field, add `sfcc.pwdless_login`.
4. In the Callback URL field, enter the callback URI that you prepared earlier.

**note:** Unlike the Redirect URL field, the Callback URL field doesn’t support wildcards. Always include the full URL for a callback, including the protocol.

5. To use 6-digit TOTPs for passwordless login, password reset, and WebAuthn authorization, select **Six Digit TOTP?**. If unselected, the default TOTP length is 8 digits. This setting can only be configured for an existing client.

![Edit client screen with Six Digit TOTP setting selected](https://developer.salesforce.com/docs/media/commerce-api/slas-six-digit-totp.png)

6. Save your changes.

## Passwordless Login Implementation

Imagine you’re building passwordless login flow for a storefront hosted at `www.example.com`. The shopper begins the flow by entering their username and requesting a passwordless login over email.

### Authorize the Customer

Request the [authorizePasswordlessCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizePasswordlessCustomer) endpoint:

```bash
#!/bin/bash
set -euo pipefail

# Update these values with your configuration:
CODE='qw1ert23'
ORG='f_ecom_abcd_001'
CLIENT='my-slas-private-client-id'
SECRET='my-slas-private-client-secret'
SITE='my-ecom-site'
CALLBACK='https://www.example.com/my-callback-url?secret=open-sesame'
LOGIN='testuser@salesforce.com'

BASE="https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG"
curl "$BASE/oauth2/passwordless/login" \
    --user "$CLIENT:$SECRET" \
    --data "channel_id=$SITE" \
    --data 'mode=callback' \
    --data "callback_uri=$CALLBACK" \
    --data-urlencode "user_id=$LOGIN"
```

The `user_id` parameter must be the shopper’s actual login credential, `profile.credentials.login`. Although the login credential can be an email address, it is not guaranteed to be the same as `profile.email`.

### Receive the Callback

SLAS makes a HTTP POST request to the provided callback URI. The request body is a JSON payload:

```json
{
  "email_id": "shopper@salesforce.com",
  "login_id": "shopper@salesforce.com",
  "phone": "4155550123",
  "customer_id": "acCpPMFESaiAKjETZajoQbO3TS",
  "token": "12345678",
  "locale": "en-us"
}
```

It contains both an email address and a phone number that belongs to the customer. The value of `phone` is set to the value of `phoneMobile` in the B2C Commerce system. If `phoneMobile` is not available, SLAS uses the value of `phoneHome` or `phoneBusiness` instead.

The value of `token` is the TOTP to send to the shopper.

**important:** - Your callback must validate that the secret value is present in the requested URL.
- SLAS makes the POST call to the given `callback_uri` without adding additional headers or parameters. If the `callback_uri` needs additional headers, such as an authorization header, you must have a “proxy” in place between SLAS and the `callback_uri` that can add any additional headers or parameters as needed.

If you don't receive the callback from SLAS:

- Verify that your callback URL is publicly accessible. You must use a publically accessible URL because SLAS can't reach localhost or private IP addresses.
- Verify that your firewall allows requests from SLAS. Requests from `*.demandware.net` URLs are blocked.
- If your callback URL is a B2C Commerce instance with site status set to `Online (Protected)`, verify that you have disabled the protection to get the callback.

### Validate the Callback Payload

Refer to the steps in [Verify the SLAS Password Action Callback](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#verify-the-slas-password-action-callback).

### Send the TOTP to the Shopper

Your app should send the TOTP to the shopper over email or SMS.

**note:** The token is good for up to ten minutes. _If the token expires, you must restart the passwordless login flow._

### Exchange the TOTP for an Access Token

The shopper must provide the TOTP to your app, either by following a link or manually entering it.

Request the [getPasswordLessAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getPasswordLessAccessToken) endpoint to exchange the TOTP for an access token:

```bash
#!/bin/bash
set -euo pipefail

# Update these values with your configuration:
CODE='qw1ert23'
ORG='f_ecom_abcd_001'
CLIENT='my-slas-private-client-id'
SECRET='my-slas-private-client-secret'
TOKEN='12345678'

BASE="https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG"
curl "$BASE/oauth2/passwordless/token" \
    --user "$CLIENT:$SECRET" \
    --data 'grant_type=client_credentials' \
    --data 'hint=pwdless_login' \
    --data "pwdless_login_token=$TOKEN"
```

The optional `login_id` and `channel_id` parameters are used for stronger validation using `login_id` + `channel_id` + `pwdless_login_token` (TOTP).

The access token (Shopper JWT) returned by SLAS can now be used to make calls to the Shopper APIs!

<!-- document id=012bad8c9b00a0ee58522590c30efa06c7a66fb3d7ad663caa404fa4553af2b5 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-passwordless-login-passkey.md -->

# Passwordless Login with Passkeys

Use the Shopper Login and API Access Service (SLAS) to authenticate shoppers securely without passwords using Fast IDentity Online 2 (FIDO2) credentials, also known as passkeys. This feature supports hardware and software-based authenticators such as TouchID, FaceID, and YubiKeys.

Passkeys replace traditional, static passwords with public key cryptography, offering enhanced security against phishing and credential stuffing while providing a faster, smoother login experience.

## Before You Begin

To integrate passwordless login with passkeys, you must have:

- **An active B2C Commerce license.**
- **A SLAS client configured for passkeys:** You can use either a public or private client. The client ID must be set with site configuration for a WebAuthn Replying Party ID and WebAuthn allowed origins:
  - Relying Party ID: The browser's origin. For example, `example.com`.
  - Allowed Origins: A comma-delimited set of accepted origins. For example, `https://example.com, https://example.com:8080`.
- **Client-side implementation:** A frontend application serves as the interface for calling the browser's WebAuthn API during registration and login flows.

## Other Considerations

- **Shopper Verification:** Before a user can register a passkey, their identity must be verified. For example, they can use a one-time password (OTP) email.
- **Browser Support:** Passkeys rely on FIDO2 standards, which are supported by major browsers like Chrome, Edge, and Safari.
- **Migration Strategy:** You can support a hybrid approach where users continue using passwords while optionally registering Passkeys, or require OTP verification before Passkey registration.

## Overview

To understand how passwordless login with Passkeys works, let’s consider the three primary workflows: shopper verification, registration, and authentication.

## 1. Shopper Verification (Pre-Registration)

Before a user can register a Passkey, their identity must be verified.

1. The shopper logs in or creates an account and requests to register a device (passkey).
2. SLAS sends a one-time-password (OTP) to the shopper (for example, via email) .
3. The shopper enters the OTP. Upon successful validation, the system proceeds to the WebAuthn registration flow.

## 2. Registration

The registration process generates a unique key pair on the shopper's device. The private key remains securely on the authenticator, while the public key is registered with SLAS.

![Passkey registration flow](https://developer.salesforce.com/docs/media/commerce-api/slas-passkey-registration.png '{"class": "image-xl"}')

1. The shopper initiates registration. For example, they click “Register FaceID.”
2. The browser (client) requests a registration challenge from SLAS via `POST /webauthn/register/start`.
3. SLAS verifies the tenant/client, generates a random challenge, and returns credential options.

**note:** The cryptographic challenge is a random string generated by the server to prevent replay attacks. The client must sign this data to prove possession of the private key.

4. The browser uses the options returned by SLAS to invoke the authenticator, calling `navigator.credentials.create()`.
5. The authenticator prompts the shopper for verification (biometric/PIN).
6. The shopper verifies their presence (for example, by providing FaceID).
7. The authenticator generates and returns a new public key credential.
8. The browser sends the credential response to SLAS via `POST /webauthn/register/finish`.
9. SLAS verifies the challenge, origin, and signature before storing the public key. If successful, returns status 204 to the browser.

## 3. Authentication

Authentication allows a returning user to log in without a password by signing a challenge with their private key.

![Passkey authentication flow](https://developer.salesforce.com/docs/media/commerce-api/slas-passkey-authentication.png '{"class": "image-xl"}')

1. The shopper clicks "Sign In."
2. The browser (client) requests the login challenge via POST /webauthn/authenticate/start. The request includes the tenant, SLAS public client_id, and username.
3. After verifying the tenant and client_id, SLAS returns the authentication options, including the challenge, allowCredentials list, and rpId.
4. The browser uses the options returned by SLAS to invoke the authenticator, calling `navigator.credentials.get()`.
5. The authenticator prompts the shopper for verification (biometric/PIN).
6. The shopper verifies their presence (for example, by providing FaceID).
7. After signing the challenge using the stored private key, the authenticator returns the assertion. The assertion response includes the credentialId, authenticatorData, signature, and clientDataJSON.

**note:** The assertion is a digital signature that proves the user is present and controls the private key.

8. The browser sends the signature and assertion response to SLAS via POST /webauthn/authenticate/finish.
9. SLAS verifies the signature against the stored public key. Upon success, SLAS issues a Shopper JWT (access token).

## WebAuthn Flow Data

Here’s a sample of what to expect when making the SLAS WebAuthn calls for passwordless login with passkeys.

### 1. Authorize - Get the OTP

#### Make a POST request to `/webauthn/register/authorize`.

Body:

```sh
user_id=luke.skywalke@endor.org&mode=callback&
callback_uri=https://redirect-url-capture-4b12a4f41b0f.herokuapp.com/redirect
&channel_id=RefArch
```

The OTP will be sent to the callback:

```js
{
  "email_id": "luke.skywalker@endor.org",
  "login_id": "luke.skywalker@endor.org",
  "phone": "",
  "token": "70699743"
}
```

Response: 204

### 2. Passkey User Registration

#### Make a POST request to `/webauthn/register/start`.

Body:

```sh
user_id=luke.skywalker@endor.org&pwd_action_token=68592438
&display_name=Luke Skywalker&channel_id=RefArch
```

Response:

```js
{
  "extensions": {},
  "attestation": "none",
  "challenge": "WiiN442Q7aQkHHTflyZ8G7DnnP5WXQAyrU-X54M3aAY",
  "authenticatorSelection": {
    "userVerification": "preferred",
    "requireResidentKey": false,
    "residentKey": "preferred"
  },
  "user": {
    "name": "luke.skywalker@endor.org",
    "displayName": "Luke Skywalker",
    "id": "Kdex2X54z1PGbw49rcJjPenx17YnbXNIix9ME9uVGPk"
  },
  "rp": {
    "id": "sandbox-001.api.commercecloud.salesforce.com",
    "name": "SLAS Service"
  },
  "timeout": 60000,
  "excludeCredentials": [
    {
      "type": "public-key",
      "id": "ucUhwmQzPMdg9FC3yrcrtAds92D4ZU8ZD1X4svPROJ0"
    },
    {
      "type": "public-key",
      "id": "OtTgAyl9BQNsF8eIajHm1DO426DYmtZyLWL1wXysafE"
    },
    {
      "type": "public-key",
      "id": "Tc79vh4RaZEu6eX7Xc0AjgaNq1JzCqLGy8OPxbJc9YU"
    }
  ],
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    },
    {
      "type": "public-key",
      "alg": -8
    },
    {
      "type": "public-key",
      "alg": -35
    },
    {
      "type": "public-key",
      "alg": -36
    },
    {
      "type": "public-key",
      "alg": -257
    },
    {
      "type": "public-key",
      "alg": -258
    },
    {
      "type": "public-key",
      "alg": -259
    }
  ]
}
```

#### Make a POST request to `/webauthn/register/finish`.

Body:

```js
{
  "credential": {
    "id": "YciKgFc6MfSIbH5_AodvuhRYXVYYNQo1Rw2fP6BM64w",
    "rawId": "YciKgFc6MfSIbH5_AodvuhRYXVYYNQo1Rw2fP6BM64w",
    "type": "public-key",
    "response": {
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiV2lpTjQ0MlE3YVFrSEhUZmx5WjhHN0RublA1V1hRQXlyVS1YNTRNM2FBWSIsIm9yaWdpbiI6Imh0dHBzOi8vc2FuZGJveC0wMDEuYXBpLmNvbW1lcmNlY2xvdWQuc2FsZXNmb3JjZS5jb20iLCJjcm9zc09yaWdpbiI6ZmFsc2V9",
      "attestationObject": "o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVik74xNzygcgA3r7qGK8VXzyEJS-hXWYB_uRiq7dWNE_tRFAAAAAQECAwQFBgcIAQIDBAUGBwgAIGHIioBXOjH0iGx-fwKHb7oUWF1WGDUKNUcNnz-gTOuMpQECAyYgASFYIJ9yvOeDFnWL8OIZCpDU8n_yKzolKCf2KXiJW0fDOJ07Ilgg2jovS7RyJIkyZgDJu-d3pXitPruz0HwdqQzpA6wTcyI",
      "transports": [
        "internal"
      ]
    },
    "clientExtensionResults": {}
  },
  "username": "luke.skywalker@endor.org",
  "pwd_action_token": "68592438",
  "channel_id": "RefArch",
  "client_id": "db0f2332-9b35-40fa-b863-06cecefdb831"
}
```

Response:

```js
{
  "nickname": "nickname",
  "username": "luke.skywalker@endor.org",
  "success": true // Check this. If false, an error is returned.
}

```

```text
Verifying registration...

✓ Registration verified

✅ Registration complete
```

### 3. Passkey Authorization

#### Make a POST request to `/webauthn/authenticate/start`.

Body: `user_id=luke.skywalker@endor.org&channel_id=RefArch`

Response:

```js
{
  "publicKey": {
    "challenge": "cSpYLgP3YEagwpfi_Fo4cKUi3cUBHDTXAP9ebn7hEy0",
    "timeout": 60000,
    "rpId": "sandbox-001.api.commercecloud.salesforce.com",
    "allowCredentials": [
      {
        "type": "public-key",
        "id": "cAi0lk_jM2QSMUf8e9d81CafxfuTAIAwFcQwnSbqccU"
      },
      {
        "type": "public-key",
        "id": "OtTgAyl9BQNsF8eIajHm1DO426DYmtZyLWL1wXysafE"
      },
      {
        "type": "public-key",
        "id": "Tc79vh4RaZEu6eX7Xc0AjgaNq1JzCqLGy8OPxbJc9YU"
      },
      {
        "type": "public-key",
        "id": "xwTrRcaMr3wJTf79ku1HOH-GBQembpsl72ye40GdOM0"
      },
      {
        "type": "public-key",
        "id": "oOM5a2kj-MUvd9xwsiwuMyIIE47LbZj8ymocLA3RJdw"
      },
      {
        "type": "public-key",
        "id": "oceCHEwJqd-o4CV5CSJZlx7HAxkeR9pXbayvvFdgiKU"
      },
      {
        "type": "public-key",
        "id": "ucUhwmQzPMdg9FC3yrcrtAds92D4ZU8ZD1X4svPROJ0"
      },
      {
        "type": "public-key",
        "id": "YciKgFc6MfSIbH5_AodvuhRYXVYYNQo1Rw2fP6BM64w"
      }
    ],
    "extensions": {}
  }
}
```

#### Make a POST request to `/webauthn/authenticate/finish`.

Body:

```js
{
  "credential": {
    "id": "i8btf3FFPSWGHlmsWBxb34-Tk4B_XwHf3eeu0DgJf_Y",
    "rawId": "i8btf3FFPSWGHlmsWBxb34-Tk4B_XwHf3eeu0DgJf_Y",
    "type": "public-key",
    "response": {
      "clientDataJSON": "eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiSExzSFkxT3dMdklTYjN2eG02TTZtbGZyS2RJRVNQR2o4RFQxY1JZaXZVQSIsIm9yaWdpbiI6Imh0dHBzOi8vc2FuZGJveC0wMDEuYXBpLmNvbW1lcmNlY2xvdWQuc2FsZXNmb3JjZS5jb20iLCJjcm9zc09yaWdpbiI6ZmFsc2V9",
      "authenticatorData": "74xNzygcgA3r7qGK8VXzyEJS-hXWYB_uRiq7dWNE_tQFAAAAAw",
      "signature": "MEQCICbTxeDJo94GT2ckDBZUdyaBbaGh1D5GayZ8L3sCh8XZAiAbExKEiUdQzC7q8j77SAcY4iwCXczhO1ZRJF6Dr6yi9w",
      "userHandle": "Kdex2X54z1PGbw49rcJjPenx17YnbXNIix9ME9uVGPk"
    },
    "clientExtensionResults": {}
  },
  "user_id": "luke.skywalker@endor.org",
  "channel_id": "RefArch",
  "client_id": "db0f2332-9b35-40fa-b863-06cecefdb831"
}
```

Response: SLAS `tokenResponse`

```js
{
  "credentialId": "i8btf3FFPSWGHlmsWBxb34-Tk4B_XwHf3eeu0DgJf_Y",
  "username": "luke.skywalker@endor.org",
  "success": true, // Check this. If false, an error is returned.
  "tokenResponse": {
    "access_token": "eyJ2ZXIiOiIxLjAiLCJqa3UiOiJzbGFzL2Rldi9ibGRtX3N0ZyIsImtpZCI6IjM1MzFlMTJjLTYyMzktNGIwNy1hNzUwLWQ2MTRmMjFiNWM0NiIsInR5cCI6Imp3dCIsImNsdiI6IkoyLjMuNCIsImFsZyI6IkVTMjU2In0.eyJhdXQiOiJHVUlEIiwic2NwIjoic2ZjYy5zaG9wcGVyLW15YWNjb3VudC5iYXNrZXRzIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzIHNmY2Muc2hvcHBlci1jdXN0b21lcnMubG9naW4gc2ZjYy5zaG9wcGVyLW1jcGFnZW50IHNmY2Muc2hvcHBlci1teWFjY291bnQub3JkZXJzIHNmY2Muc2hvcHBlci1wcm9kdWN0bGlzdHMgc2ZjYy5zaG9wcGVyLXByb21vdGlvbnMgb2ZmbGluZSBzZmNjLnNlc3Npb25fYnJpZGdlIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzLnJ3IG9mZmxpbmVfYWNjZXNzIHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzIHNmY2Muc2hvcHBlci1jYXRlZ29yaWVzIGVtYWlsIHNmY2Muc2hvcHBlci1teWFjY291bnQgZnVuY3Rpb25hbF90ZXN0IHNmY2Muc2hvcHBlci1teWFjY291bnQuYWRkcmVzc2VzIHNmY2Muc2hvcHBlci1wcm9kdWN0cyBzZmNjLnRhX2V4dF9vbl9iZWhhbGZfb2Ygc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5ydyBvcGVuaWQgc2ZjYy5wd2RsZXNzX2xvZ2luIHNmY2Muc2hvcHBlci1jb250ZXh0LnJ3IHNmY2Muc2hvcHBlci1jb250ZXh0IHNmY2Muc2hvcHBlci1jdXN0b21lcnMucmVnaXN0ZXIgc2ZjYy5zaG9wcGVyLWJhc2tldHMtb3JkZXJzIHNmY2Muc2hvcHBlci1teWFjY291bnQuYWRkcmVzc2VzLnJ3IHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzLnJ3IHNmY2Muc2hvcHBlci1iYXNrZXRzLW9yZGVycy5ydyBzZmNjLnNob3BwZXItZ2lmdC1jZXJ0aWZpY2F0ZXMgc2ZjYy5zaG9wcGVyLXByb2R1Y3Qtc2VhcmNoIHNmY2MudHNfZXh0X29uX2JlaGFsZl9vZiIsInN1YiI6ImNjLXNsYXM6OmJsZG1fc3RnOjpzY2lkOmRiMGYyMzMyLTliMzUtNDBmYS1iODYzLTA2Y2VjZWZkYjgzMTo6dXNpZDoxYjUzZjEwMi02NjhmLTQ2YmUtOGJkMC1kZWZlMzFlYzQ3ZGQiLCJzc2MiOiJzYW5kYm94LTAwMSIsImN0eCI6InNsYXMiLCJpc3MiOiJzbGFzL2Rldi9ibGRtX3N0ZyIsImlzdCI6MSwiZG50IjoiMCIsImF1ZCI6ImNvbW1lcmNlY2xvdWQvZGV2L2JsZG1fc3RnIiwibmJmIjoxNzY3NjQxMDQ0LCJzdHkiOiJVc2VyIiwiaXNiIjoidWlkbzplY29tOjp1cG46bHVrZS5za3l3YWxrZXJAZW5kb3Iub3JnOjp1aWRuOmx1a2Uuc2t5d2Fsa2VyQGVuZG9yLm9yZzo6Z2NpZDphYmt1Z1prMHdWa2JnUmxIdzJ4R1lZbEtoSjo6cmNpZDphYmI5MmxWSkR1cDR2VVVsOTNJejg5bUNtcDo6bG9naW46cHdkbGVzczo6Y2hpZDpSZWZBcmNoIiwiZXhwIjoxNzY3NjQyODc0LCJpYXQiOjE3Njc2NDEwNzQsImp0aSI6IkMyQzE4MjEwNjY4MDAtMTY5NTY2MzQ0NzU2ODgxOTM4MzAzNzUwMCJ9.LuBtso5cdR3EtlMFGzwokbZnP7qMGk9GhuScTf0dMZeI5jimM9FN57cuzCgnQFJ2nsrQKYJNxG8eE76Wg68www",
    "id_token": "eyJraWQiOiI3NGU2YjMxZS1lYTczLTQ3OTYtOWRkYi1jMDJmZGI4ZDgwYmUiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJjYy1zbGFzOjpibGRtX3N0Zzo6c2NpZDpkYjBmMjMzMi05YjM1LTQwZmEtYjg2My0wNmNlY2VmZGI4MzE6OnVzaWQ6MWI1M2YxMDItNjY4Zi00NmJlLThiZDAtZGVmZTMxZWM0N2RkIiwiYXVkIjoiZGIwZjIzMzItOWIzNS00MGZhLWI4NjMtMDZjZWNlZmRiODMxIiwiaXNzIjoicWEudXMuc2hvcHBlci5jYy5zYWxlc2ZvcmNlLmNvbSIsIm5hbWUiOiJlY29tIiwiZXhwIjoxNzY3NjQyODc0LCJpYXQiOjE3Njc2NDEwNzQsImVtYWlsIjoiZWNvbSJ9.bQ9af4jmn0tXoXvydYA0nzw3_7WwIckZ_4q9d597GeK5cmIDLXSKXu3gNV-ffnkwhR3OXkf6HfTwgachmFz2X3rqqLgeZ2oeXfpw_pvSc-K4o8GyXGycwQmNqYQzU8wL2DIIxRlfLcNhZxJ2MLp8QVxHLoz7pFAzemzuwzB7rC98gx6b4XLSdccBv4n9jG-J4qI8jh_qfuFQXWfKLnDz-WgUv3Jk7V4R39hqIKwN5D-jz7YtItgj9-2pSM7pMtHjg0CnhGYrNJhtyJ1e0hsAR0BizQVXOK5vCxz4KYhmfhVaTW7dnbRm3Jd-ooVn7c42Z311G56dzaHXPNw8RZkttw",
    "refresh_token": "llsjyBbKk0E0U_H1fUbBc64i9s7cKzE7sf-azPV9nZA",
    "expires_in": 1800,
    "refresh_token_expires_in": 7776000,
    "token_type": "BEARER",
    "usid": "1b53f102-668f-46be-8bd0-defe31ec47dd",
    "customer_id": "abb92lVJDup4vUUl93Iz89mCmp",
    "enc_user_id": "2b01dab863d4bf9885031cf4f552f24e",
    "idp_access_token": null,
    "idp_refresh_token": null,
    "dnt": 0
  }
}
```

```text
Verifying authentication...

✓ Authentication verified

✅ Authentication Successful
```

<!-- document id=2bea831743ac0846812ac01576efe911fee2036396e3b696fbbf480b1bc60018 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-passkey-login.md -->

# Passwordless Login with Passkeys for Storefront Next

Storefront Next supports passwordless login with passkeys, letting shoppers sign in with a device biometric or security key instead of a password. Passkeys are built on the WebAuthn and FIDO2 standards and use public key cryptography: the shopper's device holds a private key that never leaves the authenticator, and Shopper Login and API Access Service (SLAS) stores only the corresponding public key.

When you enable passkeys, a signed-in shopper can:

- Register a passkey on a device with an authenticator.
- Manage (view and delete) their registered passkeys from their account.

Passkeys build on SLAS passwordless login. For the underlying API contract, request and response shapes, and server-side behavior, see [Passwordless Login with Passkeys](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html) in the _B2C Commerce API Developer Guide_.

**note:** Hybrid storefronts that use Storefront Next don't currently support passkeys.

## Prerequisites

- A SLAS client configured for passkeys, with WebAuthn configuration (Relying Party ID and Allowed Origins) set through the SLAS Admin UI. See [Before You Begin](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html#before-you-begin) in the _B2C Commerce API Developer Guide_.
- An OTP delivery method for authorizing registration. Registering a passkey requires the shopper to be signed in and to confirm a one-time passcode (OTP). The delivery method is controlled by `features.passkey.mode` (see [Configure Settings](#configure-settings)).

## Configure Settings

To control passkey settings, update the `features.passkey` object in `config.server.ts`.

```ts
// config.server.ts
const config = {
  // ...
  features: {
    passkey: {
      enabled: false,
      mode: "email", // 'email' | 'callback'
      callbackUri: "", // required only when mode is 'callback'
    },
  },
};
```

- `features.passkey.enabled`: Specifies whether passkey registration and login are enabled (`true`) or not. Type: boolean. Defaults to `false`.
- `features.passkey.mode`: The mode used to deliver the OTP that authorizes passkey registration. Type: `'email' | 'callback'`. Defaults to `'email'`.
  - `email`: SLAS emails the OTP to the shopper.
  - `callback`: SLAS POSTs the OTP to your `callbackUri` instead of emailing the shopper. Requires `callbackUri` to be set and registered for your SLAS client. Useful when you deliver the code through your own email or SMS provider.
- `features.passkey.callbackUri`: The callback URI sent to SLAS when authorizing registration. Type: string. Required when `mode` is `'callback'`. Must be an absolute URL pointing to an external service, for example `https://example.com/passkey-callback`.

**note:** The OTP length isn't set on the `features.passkey` object. Instead, it comes from the shared `auth.otpLength` setting, which must match your SLAS client. For Storefront Next, the default value is `6`. See [Passwordless Login for Storefront Next](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-passwordless-login.html#configure-settings).

To override configuration options, use Managed Runtime (MRT) environment variables with the `PUBLIC__` prefix.

```shell
PUBLIC__app__features__passkey__enabled=true
PUBLIC__app__features__passkey__mode=callback
PUBLIC__app__features__passkey__callbackUri=https://www.example.com/webauthn-login-callback
PUBLIC__app__auth__otpLength=8
```

The `rpId` and Allowed Origins aren't set in the storefront config. They live on the SLAS client (see [Prerequisites](#prerequisites)). SLAS returns these values to the browser during the WebAuthn ceremony.

## How Passkeys Work in Storefront Next

Storefront Next calls the browser WebAuthn API and relays the results to SLAS through server-side route actions. There are two flows: registration (a signed-in shopper enrolls a passkey) and authentication (a returning shopper signs in with a passkey).

### Register a Passkey

A shopper must be signed in (a registered user) to register a passkey. Registration is authorized with a one-time passcode.

1. The signed-in shopper chooses to add a passkey. The storefront authorizes registration, and SLAS delivers an OTP according to `features.passkey.mode`.
2. The shopper enters the OTP.

   ![Passkey OTP verification modal](https://developer.salesforce.com/docs/media/sfnext/sfnext-passkey-verify-otp.png '{"class": "image-md"}')

3. The storefront starts registration, passing the `pwdActionToken` and an optional passkey nickname (up to 128 characters). SLAS returns WebAuthn credential-creation options, including a random challenge.
4. The storefront passes the options to `navigator.credentials.create()`. The browser prompts the shopper's authenticator (biometric or PIN).
5. The authenticator generates a public/private key pair and returns a public key credential.
6. The storefront finishes registration, sending the credential and `pwdActionToken`. SLAS verifies the challenge, origin, and signature, then stores the public key.

**note:** The `pwdActionToken` ties the WebAuthn ceremony to a verified OTP. Start a fresh authorization if it expires. Don't reuse a token or challenge across attempts.

### Sign In with a Passkey

Authentication signs a returning shopper in without a password.

1. The shopper chooses to sign in with a passkey. The storefront starts authentication. It can omit the shopper identifier to request a discoverable-credential challenge (the browser or autofill lets the shopper choose which passkey to use), or pass a `userId` to scope the challenge to a specific login.
2. SLAS returns authentication options, including the challenge, the `allowCredentials` list, and the `rpId`.
3. The storefront passes the options to `navigator.credentials.get()`. The browser prompts the shopper's authenticator.
4. The authenticator returns an assertion, a digital signature proving the shopper controls the private key.
5. The storefront finishes authentication, sending the assertion and the current guest `usid` so the guest basket and wishlist are linked to the shopper. SLAS verifies the signature and returns a shopper access token in JSON Web Token (JWT) format.
6. The shopper is signed in. The storefront merges and recalculates the guest basket and merges any guest wishlist.

For full request and response schemas, see [Passwordless Login with Passkeys](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html) in the _B2C Commerce API Developer Guide_.

### Manage Passkeys

When passkeys are enabled, the account area can show whether a shopper has a registered passkey and let them remove one. The storefront queries passkey status for the signed-in shopper and can delete a specific credential by its ID. Provide this UI so shoppers can revoke access from lost or retired devices.

![Manage passkeys in the account area](https://developer.salesforce.com/docs/media/sfnext/sfnext-passkey-manage.png '{"class": "image-md"}')

## Best Practices

- Keep `rpId` and Allowed Origins aligned with your deployment. When you add a domain, staging origin, or port, update the SLAS client's WebAuthn configuration before shoppers reach it.
- Match `auth.otpLength` to your SLAS client. The value sets the OTP modal's slot count and the "we sent an N-digit code" copy. SLAS issues 6- or 8-digit codes.
- Offer a fallback. Keep another sign-in method (email OTP or password) available for shoppers on unsupported browsers or new devices without a registered passkey.
- Use callback mode only when you own the delivery. Set `mode` to `'callback'` with a registered absolute callback URI when routing the OTP through your own email or SMS provider. Otherwise, keep the default email mode.

## Troubleshoot Passkeys

**Passkey registration or login fails silently in the browser**

_Potential cause:_ The storefront origin doesn't match the SLAS client's `rpId` or isn't listed in Allowed Origins. The browser blocks the WebAuthn ceremony before any request reaches SLAS.

_Suggested solution:_ In the SLAS Admin UI (or via the SLAS Admin API), confirm that `rpId` is the registrable domain of the storefront (for example, `example.com`) and that every origin the storefront runs on, including ports used in local or staging environments, is listed in Allowed Origins.

**Passkey routes return 404 Not Found**

_Potential cause:_ `features.passkey.enabled` is `false`. Every passkey route returns 404 when the feature is turned off.

_Suggested solution:_ Set `features.passkey.enabled` to `true` in `config.server.ts` (or via the `PUBLIC__app__features__passkey__enabled` environment variable) and redeploy.

**Registration OTP never arrives**

_Potential cause:_ In callback mode, `callbackUri` is missing, not an absolute URL, or not registered for the SLAS client, so SLAS has nowhere to POST the OTP.

_Suggested solution:_ Set `features.passkey.callbackUri` to an absolute URL (for example, `https://example.com/passkey-callback`) and register it for your SLAS client, or switch to email mode to have SLAS email the OTP directly.

**Registration fails after the shopper enters the OTP**

_Potential cause:_ The `pwdActionToken` expired or was reused, or the challenge or origin didn't validate on the SLAS side.

_Suggested solution:_ Restart the flow so the shopper receives a fresh OTP and a new `pwdActionToken`. Don't reuse a token or challenge. Confirm the browser-reported origin matches the SLAS client's Allowed Origins.

**Login starts but no passkey is offered**

_Potential cause:_ The shopper has no passkey registered for the account (or on the current device), so the `allowCredentials` list is empty.

_Suggested solution:_ Route the shopper to registration or an alternative sign-in method. A passkey must be registered on the account and available on the device before it can be used to sign in.

**Passkey login intermittently returns no options**

_Potential cause:_ SLAS is briefly throttling repeated authentication starts (HTTP 412). The storefront treats this as a silent no-op rather than an error.

_Suggested solution:_ This is expected rate-limiting. Have the shopper retry after a short wait. Avoid triggering authentication starts in a tight loop.

## See Also

- [Passwordless Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passwordless-login.md)
- [Passwordless Login with Passkeys](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html)
- [Passwordless Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-overview.html)
- [Shopper Login and API Access Service (SLAS) Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html)
- [Shopper Login API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login)

<!-- document id=d7c09ec696196840e0c6244b9447b3c34f92bbd102e27ab26c81c2781a871577 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-passwordless-sms.md -->

# Passwordless Login with SMS Service Provider

Use SMS to send verification codes to authenticate shoppers with the [passwordless login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html) feature of the Shopper Login and API Access Service (SLAS).

This guide includes instructions for integrating passwordless login with SMS by using either Agentforce Marketing or Amazon Simple Notification Service (SNS). SLAS doesn't support SMS delivery of one-time passwords (OTPs). To have an OTP sent by SMS, use `mode=callback` and manage the SMS delivery from your callback.

## Before You Begin

To complete the instructions in this guide, you must have:

- An active B2C Commerce license.
- An SMS service provider. For example, Agentforce Marketing or Amazon SNS.
- Provisioned SMS short or long codes for each country where you have SMS recipients.

## Other Considerations

- **Prior login:** A shopper must log in via SLAS at least one time before requesting a passwordless login.
- **Registration:** The shopper’s phone number must be registered with B2C Commerce.
- **Volume limits:** Sending SMS message for passwordless login counts towards your overall volume.

## Example A: Agentforce Marketing

![SLAS passwordless login flow with Agentforce Marketing for SMS integration](https://developer.salesforce.com/docs/media/commerce-api/slas-passwordless-sms-marketing-cloud.png '{"class": "image-xl"}')

This diagram illustrates the complete lifecycle of a passwordless login request. It begins when the storefront app calls SLAS with `mode=callback`. SLAS then delegates the OTP delivery to your backend server. Finally, your server authenticates with Agentforce Marketing to dispatch the SMS before returning a success response to SLAS.

### Agentforce Marketing Prerequisites

- An active Agentforce Marketing license with an SMS subscription.
- Admin access for your Agentforce Marketing instance with permission to install apps.
- An SMS country code and short code for your Agentforce Marketing instance.

👉 To provision an SMS short code, contact your Agentforce Marketing account representative.

### Agentforce Marketing Configuration

#### 1. Set Up Agentforce Marketing Server-to-Server Integration

Set up a server-to-server integration in Agentforce Marketing. This allows your backend to make API calls to Agentforce Marketing to send SMS messages. See [Server-to-Server Integrations with Client Credentials Grant Type](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/integration-s2s-client-credentials.html) in _Agentforce Marketing Engagement APIs and Programmatic Languages._

#### 2. Set Up a Transactional SMS Send Definition

Create a send definition that contains the message template and delivery configuration.

a. Use your Cilent ID and secret to request an access token for Agentforce Marketing. See [Access Token for Server-to-Server Integrations](https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/access-token-s2s.html) in _Agentforce Marketing Engagement APIs and Programmatic Languages._ For example:

```sh
curl "https://$MARKETING_CLOUD_SUBDOMAIN.auth.marketingcloudapis.com/v2/token" \
--request POST \
--header "Content-Type: application/json" `\`
--data '{
    "grant_type": "client_credentials",
    "client_id": "2bfe9d72a4aae8f06a31025b7536be80",
    "client_secret": "9d667c2b7fae7a329f32b6df17926154",
    "scope": "sms_read sms_write sms_send"
}'
```

b. Create the SMS definition using the access token received in step 2a. See [POST /messaging/v1/sms/definitions](https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_transactional_messaging_sms/createSMSSendDefinition.html) in _Agentforce Marketing Engagement APIs and Programmatic Languages._

```sh
curl "https://$MARKETING_CLOUD_SUBDOMAIN.rest.marketingcloudapis.com/messaging/v1/sms/definitions/" \
--request POST \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--data '{
  "definitionKey": "pwdless_login",
  "name": "pwdless_login",
  "content": {
    "message": "Your login code is: %%token%%"
  },
  "subscriptions": {
    "shortCode": "8201221",
    "countryCode": "US",
    "keyword": "PASSWORDLESS_LOGIN"
  }
}'
```

#### 3. Create a Backend Server to Host the Callback URI

This sample code shows how to configure a backend server for Agentforce Marketing integration. The code handles the HTTP POST request from SLAS and uses Marketing Cloud to send the SMS with the OTP to the user.

**note:** This sample code is provided for guidance and isn't production-ready. Make sure that your code is properly tested before deployment.

```text
import { randomUUID } from 'node:crypto'

const MC_SUBDOMAIN = // MARKETING_CLOUD_SUBDOMAIN
const MC_CLIENT_ID = // MARKETING_CLOUD_CLIENT_ID
const MC_CLIENT_SECRET = // MARKETING_CLOUD_ORG_CLIENT_SECRET

export const handler = async (event) => {
  try {
    const body = JSON.parse(event.body || '{}')
    console.log('Received event:', body)
    const { phone, token, login_id } = body

    // Step 1: Get access token
    const tokenRes = await fetch(`https://${MC_SUBDOMAIN}.auth.marketingcloudapis.com/v2/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        grant_type: 'client_credentials',
        client_id: MC_CLIENT_ID,
        client_secret: MC_CLIENT_SECRET,
        scope: 'sms_read sms_write sms_send'
      })
    })

    const { access_token } = await tokenRes.json()

    // Step 2: Send SMS
    const messageKey = randomUUID()
    const smsRes = await fetch(`https://${MC_SUBDOMAIN}.rest.marketingcloudapis.com/messaging/v1/sms/messages/${messageKey}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${access_token}`
      },
      body: JSON.stringify({
        definitionKey: 'pwdless_login_us',
        recipient: {
          to: phone,
          contactKey: login_id,
          attributes: { token }
        }
      })
    })

    const smsText = await smsRes.text().catch(() => '')

    return {
      statusCode: 200,
      body: JSON.stringify({ message: 'SMS request submitted', messageKey, marketingCloudResponse: JSON.parse(smsText)})
    }
  } catch (err) {
    console.error('Error:', err)
    return { statusCode: 500, body: JSON.stringify({ error: err?.message || 'Unknown error' }) }
  }
}
```

#### 4. Add the Callback URL to Your SLAS Private Client

After creating the backend server, add the URI to the Callback URL list for your SLAS Private Client. See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html#configure-a-slas-private-client).

Next, continue to [Authorize with SMS](#authorize-with-sms).

## Example B: Amazon SNS

![SLAS passwordless login flow with Amazon SNS for SMS integration](https://developer.salesforce.com/docs/media/commerce-api/slas-passwordless-login-sms-amazon.png '{"class": "image-xl"}')

This diagram shows the delivery flow using Amazon SNS. The process starts when the storefront app requests a login. SLAS forwards the token to your backend server, which uses the AWS SDK to publish the message directly to the shopper. Because the SDK handles authentication via configuration, no separate token request is required.

#### Amazon SNS Prerequisites

To integrate passwordless login with Amazon SNS, you must have:

- Amazon SNS with production access.
- Provisioned SMS short or long codes in Amazon SNS for each country where you have SMS recipients.

#### 1. Create a Backend Server to Host the Callback URI

This sample code shows how to configure a backend server for Amazon SNS integration. The code handles the HTTP POST request from SLAS and uses Amazon SNS to send the SMS with the one-time password to the user.

**note:** This sample code is provided for guidance and isn't production-ready. Make sure that your code is properly tested before deployment.

```text
import { SNSClient, PublishCommand } from '@aws-sdk/client-sns'

const snsClient = new SNSClient({ region: 'us-east-1' })

export const handler = async (event) => {
  try {
    const body = JSON.parse(event.body || '{}')
    const { phone, token } = body

    await snsClient.send(new PublishCommand({
      Message: `Your login code is: ${token}`,
      PhoneNumber: phone // Must be E.164 format
    }))

    return {
      statusCode: 200,
      body: JSON.stringify({ message: 'SMS sent successfully' })
    }
  } catch (err) {
    console.error('Error sending SMS:', err)
    return {
      statusCode: 500,
      body: JSON.stringify({ error: 'Failed to send SMS' })
    }
  }
}
```

#### 2. Add the Callback URL to Your SLAS Private Client

After creating the backend server, add the URI to the Callback URL list for your SLAS Private Client. See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html#configure-a-slas-private-client).

Next, continue to [Authorize with SMS](#authorize-with-sms).

## Authorize with SMS

### 1. Set Environment Variables

To form requests to the SLAS APIs correctly, it helps to set some environment variables first:

| Variable                | Example Value                                               | Description                                                                                                                                                                                                           |
| ----------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$SFCC_SCAPI_SHORTCODE` | `kv7kzm78`                                                  | [Short code](https://developer.salesforce.com/docs/commerce/commerce-api/guide/commerce-api-configuration-values.html) for your B2C Commerce instance, not the short code that is provisioned for Agentforce Marketing SMS |
| `$ORGANIZATION_ID`      | `abcd_s01`                                                  | [Organization ID](https://developer.salesforce.com/docs/commerce/commerce-api/guide/commerce-api-configuration-values.html) for your B2C Commerce instance                                                            |
| `$CHANNEL_ID`           | `SiteGenesis`                                               | Site name (also known as channel name) in Business Manager                                                                                                                                                            |
| `$CALLBACK_URI`         | `https://webhook.site/9f44093b-d129-42be-84d3-2f17254df04b` | URI for redirection after authorization                                                                                                                                                                               |
| `$CLIENT_ID`            | `872daaa2-412e-40c8-a48a-5a56daaef868`                      | The SLAS client ID                                                                                                                                                                                                    |
| `$USER_ID`              | `pia.larson`                                                | The user ID for logging in the shopper                                                                                                                                                                                |
| `$ACCESS_TOKEN`         | (not provided for security reasons)                         | Access token from SLAS                                                                                                                                                                                                |

**note:** If you’re not using a Unix-based operating system, manually replace the variables later in the `curl` command provided.

### 2. Request Authorization

This sample request uses the environment variables set earlier and the [authorizePasswordlessCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizePasswordlessCustomer) endpoint of the SLAS API (not the same as the SLAS Admin API) to authorize a customer via SMS:

```sh
curl "https://$SFCC_SCAPI_SHORTCODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORGANIZATION_ID/oauth2/passwordless/login" \
--request 'POST' \
--header "Authorization: Basic $ACCESS_TOKEN"
--data "channel_id=$CHANNEL_ID" \
--data 'mode=callback' \
--data "callback_uri=$CALLBACK_URI \
--data "client_id=$CLIENT_ID \
--data "user_id=$USER_ID \
--data 'locale=en-us'
```

For more details on making API requests for shopper authorization, see the [Passwordless Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html) guide and the [SLAS API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizePasswordlessCustomer).

<!-- document id=2fc982d6eeaea76d08980ba9c45c2e1286f9ad22507e7d81cb49f4b1471b2918 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payment-flow-apis.md -->

# Payment APIs

B2B Commerce implements a group of payment APIs to support tokenizing shopper credit cards without storing that information natively.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Shopper actions trigger payment API calls to a third-party service provider via the Payment Adapter framework. The APIs support tokenizing shopper credit cards so that no personal information is stored natively. Together with the licensed Salesforce Order Management (SOM) or 1C OM, the Payment Adapter framework exposes additional APIs. SOM manages the capture and refund flows and provides an integrated customer order lifecycle, including fulfillment and service.

These APIs initiate payments processing.

- **SetPaymentMethod** tokenizes the shopper’s credit card and returns a token.
- **PlaceOrder** (returns Auth Code) validates the cart, reserves inventory, converts cart to order, authorizes payment, and activates the order in SOM. The payment authorization reserves funds from the available credit of the credit card, but it’s not a payment. To the shopper, it can display as pending.

After the transaction is tokenized and the order placed, any of these APIs and corresponding transactions can occur.

![Diagram summarizing API calls](https://developer.salesforce.com/media/d2c-commerce/payment_som_apis.png)

- Authorization reversals release the funds reserved by the payment authorization, removing them from pending transactions.
- Capture consumes the funds reserved by the payment authorization.
- Sale is a transaction type where Authorization and Capture are executed as part of a single request. If successful, the order is fulfilled immediately.
- Void cancels the transfer of funds to the merchant account before settlement. When a payment is processed, funds are held. The balance is deducted from the customer’s credit limit, but not yet transferred to the merchant account. At a later point, all transactions are batched for settlement, and the funds are transferred to the merchant’s account. A transaction can be voided after purchase but before settlement.
- Refund is a transaction request that transfers the amount from the merchant’s account to the customer’s account.

**note:** In addition, A PostAuth API is required for client-side payment component implementations. The gateway adapter reads fields from the PostAuth Request class to validate the client-side transaction with the payment gateway. For more on the PostAuth objects, see [PostAuthorizationRequest Class](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_class_commercepayments_PostAuthorizationRequest.htm)

For more information on the other payment APIs, see [Commerce Connect REST Payment APIs](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_payments.htm).

<!-- document id=2c05a93d325370002d4c9d28c76616e360c3172bbf488f276c0fac2031018b97 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payment-integration.md -->

# Payment Architecture

The Salesforce Payment Adapter framework fetches tokens and authorizations from service providers during checkout.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

A shopper UI action triggers the SetPaymentMethod, which interacts with an integrated third-party payment provider to reserve funds.

![Diagram of payment integration flow](https://developer.salesforce.com/media/d2c-commerce/payment_tokenizatino.png)

After the shopper reviews and approves the order, the PlaceOrder API completes the sale.

![Diagram of place order flow.](https://developer.salesforce.com/media/d2c-commerce/place_order.png)

Integration packages for payment providers are interoperable across the B2B Commerce solution and Salesforce Order Management.

![Diagarm of payment gateway flows.](https://developer.salesforce.com/media/d2c-commerce/payment_gateway_flows.png)

<!-- document id=13664ed78d6f51c208e222aa0c8b1dbbff9135975176dd3fe77a85f9cbab4c23 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/payment-spi.md -->

Payment Gateway SPI

# Payment Gateway SPI

Integrate third-party payment gateway terminals (for example, Worldpay or Stripe Terminal) with Point of Sale (POS) through a store-local proxy server. The proxy translates gateway protocols and streams real-time terminal events over WebSockets, so new gateway integrations can be added without modifying the POS iOS application.

For architecture, security modes, date-format requirements, and client-side timeouts, see [Integrate Payment Gateways Using the Payment Gateway SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/payment-gateway-spi.html).

**Version:** 1.3.0

## Security

*   `hmacAuth` (apiKey)
    
    HMAC-SHA256 request signing. Required for all POST endpoints.
    
    ### HMAC Message Format
    
    The HMAC signature is computed over a pipe-delimited message string using a pre-shared secret stored in the device Keychain.
    
    **For requests WITH an amount** (payment, capture, refund):
    
    ```
    {storeId}|{registerId}|{transactionId}|{amount}|{ISO8601-timestamp}|{nonce}
    ```
    
    Example:
    
    ```
    STORE-001|REG-01|550e8400-e29b-41d4-a716-446655440000|49.99|2026-03-12T14:04:06Z|abc123-nonce
    ```
    
    **For requests WITHOUT an amount** (cancel, void):
    
    ```
    {storeId}|{registerId}|{transactionId}|{ISO8601-timestamp}|{nonce}
    ```
    
    Example:
    
    ```
    STORE-001|REG-01|550e8400-e29b-41d4-a716-446655440000|2026-03-12T14:05:00Z|def456-nonce
    ```
    
    ### Required Headers
    
    All HMAC-signed requests MUST include these four headers:
    
    | Header | Description |
    | --- | --- |
    | `X-HMAC` | HMAC-SHA256 hex digest of the message |
    | `X-Nonce` | Unique nonce for replay protection |
    | `X-Store-ID` | Store identifier |
    | `X-Register-ID` | Register/terminal identifier |
    
    ### Response Signing
    
    The proxy MUST include an `X-HMAC` response header on all **2xx POST responses**. The client validates this signature against the raw response body to ensure response integrity. The signing key is the same pre-shared HMAC secret.
    
    ### Nonce Requirements
    
    *   Each nonce MUST be unique per request
    *   The server SHOULD reject requests with previously seen nonces (replay protection)
    *   Nonce format: UUID string or equivalent unique token
    
    *   API key in header: X-HMAC
*   `mtls` (mutualTLS)
    
    Mutual TLS (mTLS) transport security. The SPI server verifies the client certificate presented by the iOS device, and the client pins the server certificate by SHA256 hash.
    
    **Client certificate**: Installed in the iOS Keychain during device provisioning. **Server certificate pinning**: The client validates the server cert's SHA256 hash against a pinned value from the store configuration.
    

## Tags

### Payments

Initiate a sale or pre-authorization, capture a pre-authorized payment, void an authorized payment, cancel an in-progress transaction, and query transaction status. This is the core cardholder-present payment flow. When the client uses the WebSocket channel, it opens a WebSocket to receive real-time terminal events, then calls `POST /payment` to start the transaction. The proxy forwards the request to the terminal, waits for cardholder interaction, and returns the authorization result.

### Refund

Process referenced refunds (against a prior transaction) and unreferenced refunds (standalone, without an original transaction to reference). The proxy translates the refund request into the gateway's native protocol and returns the settlement result. Unreferenced refunds typically require elevated cashier permissions in the POS.

### Terminal

Discover terminals registered with the SPI server, retrieve the status of a specific terminal, and check the health of the SPI server itself. Use these endpoints at POS startup to enumerate available terminals, before a transaction to verify a terminal is online, and periodically to detect connectivity or configuration problems.

### Gift Cards

Perform gift card lifecycle operations (activate, load, unload, balance, cashout, reversal, refund, verify) through a single dispatch endpoint, and process gift card payments through a dedicated endpoint that mirrors the standard payment flow with WebSocket event streaming. Gift card payment operations behave like card-present payments and support the same partial-authorization and split-tender scenarios.

### Card Acquisition

Tokenize a customer's payment card without capturing funds. Use for card-on-file enrollment, saved-payment-method setup, and any workflow that needs a reusable token without a live transaction. Returns a gateway-issued token, masked PAN, and card brand.

### Terminal Display

Push content to the terminal's customer-facing screen (for example, a virtual receipt, an order summary, or a signature-capture prompt) and clear the display when the interaction is complete. Use to keep the customer informed during multi-step transactions and to display order details for confirmation.

### Terminal Input

Prompt the terminal to collect customer input — free-text (for example, email for a digital receipt), numeric digits (for example, a loyalty number), or a yes/no confirmation — and cancel any pending input prompt when the workflow changes. Input responses are returned to the POS through the same request/response cycle.

### Pay By Link

Create Pay By Link (PBL) payment links to send to customers via email, SMS, or QR code; expire an unused link; query link status; and process a refund or void against a completed PBL payment. Use for remote payment, deposit collection, and in-store scenarios where the customer prefers to pay from their own device.

### Health

Verify that the SPI server is reachable and healthy. The POS client calls the health endpoint on startup and at configurable intervals to detect proxy outages, network partitions, or configuration drift before they surface as failed transactions.

### Offline

Retrieve store-and-forward (SAF) transactions from a terminal's offline queue, validate and complete offline payment payloads captured by partial-offline gateways (for example, Elavon) once connectivity returns, and query a terminal's offline status. Use during and after network outages to reconcile transactions that were captured while the terminal was disconnected from the gateway.

## Operations

### POST Initiate a sale or pre-authorization payment

`POST /api/v1/payment`

Operation ID: `initiatePayment`. Tags: Payment. Security: hmacAuth.

Sends a payment request to the specified terminal via the configured gateway. The proxy forwards the request to the terminal, waits for the cardholder interaction, and returns the authorization result.

When the client uses the WebSocket channel, it opens a connection to `WSS /events?transactionId={transactionId}` before calling this endpoint to receive real-time terminal events (card inserted, PIN entry, authorization progress). The WebSocket channel is optional — support clients that skip it and rely on the REST response alone.

**HMAC signed**: Yes (with amount)

#### Parameters

*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `PaymentRequest`.

_Example_

```
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 49.99,
  "currency": "USD",
  "gateway": "worldpay",
  "terminalId": "T-001",
  "paymentType": "sale",
  "metadata": {
    "orderId": "ORD-12345",
    "cashierId": "C-42"
  },
  "timestamp": "2026-03-12T14:04:06.000Z"
}
```

#### Responses

*   **200** Payment processed successfully
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body for integrity verification
    
    Media type: `application/json`. Schema: `PaymentResponse`.
    
    _Example_
    
    ```
    {
      "transactionId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "APPROVED",
      "authCode": "AUTH123456",
      "requestId": "PSP-REF-789",
      "alternateRequestId": "TX-REF-456",
      "gatewayContext": {
        "pspReference": "8535516979155668",
        "merchantAccount": "PSRetailUS"
      },
      "receiptData": {
        "merchantCopy": [
          {
            "key": "pan",
            "display": "Card Number",
            "value": "****1234"
          },
          {
            "key": "authCode",
            "display": "Auth Code",
            "value": "AUTH123456"
          }
        ],
        "customerCopy": [
          {
            "key": "pan",
            "display": "Card Number",
            "value": "****1234"
          }
        ]
      },
      "cardDetails": {
        "maskedPan": "****1234",
        "cardBrand": "VISA",
        "entryMethod": "CHIP",
        "fundingSource": "CREDIT"
      },
      "timestamp": "2026-03-12T14:04:12.206Z"
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### GET Query the current status of a payment transaction

`GET /api/v1/payment/{transactionId}`

Operation ID: `queryTransactionStatus`. Tags: Payment.

Returns the current state of a previously initiated payment transaction. Useful for recovery scenarios where the client lost connectivity during the original payment flow.

**HMAC signed**: No

#### Parameters

*   `transactionId` (path, string (uuid), required) UUID v4 of the payment transaction. Must match a transaction previously submitted via POST /api/v1/payment.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.

#### Responses

*   **200** Transaction status retrieved
    
    Media type: `application/json`. Schema: `PaymentResponse`.
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### POST Cancel an in-progress payment transaction

`POST /api/v1/payment/{transactionId}/cancel`

Operation ID: `cancelPayment`. Tags: Payment. Security: hmacAuth.

Cancels a payment that is currently being processed on the terminal. This is used when the operator or customer wants to abort before the transaction is authorized.

**HMAC signed**: Yes (without amount)

#### Parameters

*   `transactionId` (path, string (uuid), required) UUID v4 of the payment transaction. Must match a transaction previously submitted via POST /api/v1/payment.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `CancellationRequest`.

_Example_

```
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "customer_requested",
  "timestamp": "2026-03-12T14:05:00.000Z"
}
```

#### Responses

*   **200** Cancellation result
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `CancellationResponse`.
    
    _Example_
    
    ```
    {
      "transactionId": "550e8400-e29b-41d4-a716-446655440000",
      "cancelled": true,
      "message": "Transaction cancelled successfully"
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### POST Void a previously authorized payment

`POST /api/v1/payment/{transactionId}/void`

Operation ID: `voidPayment`. Tags: Payment. Security: hmacAuth.

Voids a payment that has been authorized but not yet settled. Must be called before the settlement batch is processed.

**HMAC signed**: Yes (without amount)

#### Parameters

*   `transactionId` (path, string (uuid), required) UUID v4 of the payment transaction. Must match a transaction previously submitted via POST /api/v1/payment.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `VoidRequest`.

_Example_

```
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "operator_void",
  "timestamp": "2026-03-12T14:06:00.000Z",
  "gatewayContext": {
    "pspReference": "8535516979155668",
    "merchantAccount": "PSRetailUS"
  }
}
```

#### Responses

*   **200** Void result
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `VoidResponse`.
    
    _Example_
    
    ```
    {
      "transactionId": "550e8400-e29b-41d4-a716-446655440000",
      "voided": true,
      "message": "Transaction voided successfully"
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### POST Capture a previously pre-authorized payment

`POST /api/v1/payment/{transactionId}/capture`

Operation ID: `capturePayment`. Tags: Payment. Security: hmacAuth.

Captures (settles) a payment that was initiated with `paymentType: "pre_authorization"`. The capture amount may be less than or equal to the original authorization amount.

**HMAC signed**: Yes (with amount)

#### Parameters

*   `transactionId` (path, string (uuid), required) UUID v4 of the payment transaction. Must match a transaction previously submitted via POST /api/v1/payment.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `CaptureRequest`.

_Example_

```
{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 45,
  "currency": "USD"
}
```

#### Responses

*   **200** Capture result
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `CaptureResponse`.
    
    _Example_
    
    ```
    {
      "transactionId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "APPROVED",
      "authCode": "CAP789012",
      "timestamp": "2026-03-12T14:07:00.206Z"
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### POST Process a referenced or unreferenced refund

`POST /api/v1/refund`

Operation ID: `processRefund`. Tags: Refund. Security: hmacAuth.

Sends a refund request to the terminal via the proxy.

*   **Referenced refund**: Include `originalTransactionId` and set `refundType: "referenced"`. The gateway links the refund to the original payment for reconciliation.
*   **Unreferenced refund**: Omit `originalTransactionId` and set `refundType: "unreferenced"`. The refund is processed as a standalone credit to the card presented at the terminal.

**HMAC signed**: Yes (with amount)

#### Parameters

*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `RefundRequest`.

_Example: referenced_ Referenced refund

```
{
  "transactionId": "660e8400-e29b-41d4-a716-446655440001",
  "originalTransactionId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 10,
  "currency": "USD",
  "gateway": "worldpay",
  "terminalId": "T-001",
  "refundType": "referenced",
  "timestamp": "2026-03-12T15:00:00.000Z",
  "gatewayContext": {
    "pspReference": "8535516979155668",
    "merchantAccount": "PSRetailUS"
  }
}
```

_Example: unreferenced_ Unreferenced refund

```
{
  "transactionId": "770e8400-e29b-41d4-a716-446655440002",
  "amount": 25,
  "currency": "USD",
  "gateway": "worldpay",
  "terminalId": "T-001",
  "refundType": "unreferenced",
  "timestamp": "2026-03-12T15:01:00.000Z"
}
```

#### Responses

*   **200** Refund processed
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `RefundResponse`.
    
    _Example_
    
    ```
    {
      "transactionId": "660e8400-e29b-41d4-a716-446655440001",
      "status": "APPROVED",
      "authCode": "REF456789",
      "timestamp": "2026-03-12T15:00:05.206Z"
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### GET Check SPI server health

`GET /api/v1/health`

Operation ID: `checkHealth`. Tags: Health.

Returns the SPI server's health status, including connectivity to downstream gateways and certificate expiry information.

**HMAC signed**: No

#### Responses

*   **200** Proxy is healthy
    
    Media type: `application/json`. Schema: `HealthResponse`.
    
    _Example_
    
    ```
    {
      "status": "ok",
      "version": "1.2.0",
      "uptime": 86400.5,
      "timestamp": "2026-03-12T14:04:06.206Z",
      "checks": {
        "database": "ok",
        "gateway": "ok",
        "terminal_connectivity": "ok"
      },
      "certificateExpiry": "2027-03-12T00:00:00Z"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### GET Get the status of a specific terminal

`GET /api/v1/terminal/{terminalId}/status`

Operation ID: `getTerminalStatus`. Tags: Terminal.

Returns the online/offline status and last heartbeat time for a terminal registered with the proxy.

**HMAC signed**: No

#### Parameters

*   `terminalId` (path, string, required) Device ID of the terminal as registered with the SPI server. Must exactly match the terminalId used during terminal registration/discovery.  
    Example: `T-001`.

#### Responses

*   **200** Terminal status retrieved
    
    Media type: `application/json`. Schema: `TerminalStatus`.
    
    _Example_
    
    ```
    {
      "terminalId": "T-001",
      "online": true,
      "lastSeen": "2026-03-12T14:03:55.000Z",
      "gateway": "worldpay"
    }
    ```
    
*   **404** Terminal not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### GET List all terminals registered with the proxy

`GET /api/v1/terminals`

Operation ID: `listTerminals`. Tags: Terminal.

Returns an array of all terminal devices registered with the SPI server. Used by the POS client for terminal discovery during setup and for displaying available terminals in the UI.

**HMAC signed**: No

#### Responses

*   **200** Terminal list retrieved
    
    Media type: `application/json`. Schema: `array of TerminalInfo`.
    
    Array of `TerminalInfo`.
    
    _Example_
    
    ```
    [
      {
        "terminalId": "T-001",
        "name": "Register 1 Terminal",
        "ipAddress": "192.168.1.100",
        "online": true,
        "gateway": "worldpay",
        "modelNumber": "VX820",
        "serialNumber": "SN-123456"
      },
      {
        "terminalId": "T-002",
        "name": "Register 2 Terminal",
        "online": false,
        "gateway": "worldpay"
      }
    ]
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### POST Perform a gift card operation

`POST /api/v1/giftcard/{operation}`

Operation ID: `giftCardOperation`. Tags: Gift Cards.

Performs a gift card operation (activate, load, unload, balance, cashout, reversal, refund, verify). Gift card payment uses a separate endpoint with WebSocket streaming.

HMAC signing: Operations with amounts include amount in HMAC message. Operations without amounts (activate, balance, verify) use signWithoutAmount.

#### Parameters

*   `operation` (path, string, required)  
    Allowed values: `activate`, `load`, `unload`, `balance`, `cashout`, `reversal`, `refund`, `verify`.

#### Request body (required)

Media type: `application/json`. Schema: `ProxyGiftCardRequest`.

#### Responses

*   **200** Gift card operation completed
    
    Media type: `application/json`. Schema: `ProxyGiftCardResponse`.
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### POST Process gift card payment with WebSocket events

`POST /api/v1/giftcard/payment`

Operation ID: `giftCardPayment`. Tags: Gift Cards.

Processes a gift card payment. When the client uses the WebSocket channel, it opens the connection first, then calls this endpoint — mirroring the standard payment flow. The WebSocket channel is optional; when the client skips it, the payment completes via the REST response alone.

#### Request body (required)

Media type: `application/json`. Schema: `ProxyGiftCardRequest`.

#### Responses

*   **200** Gift card payment completed
    
    Media type: `application/json`. Schema: `ProxyGiftCardResponse`.
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### POST Tokenize card without payment

`POST /api/v1/card/acquire`

Operation ID: `acquireCard`. Tags: Card Acquisition.

Acquires card details (token, masked PAN, brand) without processing a payment. When the client uses the WebSocket channel, it receives real-time terminal feedback over that connection. The WebSocket channel is optional; when the client skips it, the operation completes via the REST response alone. Use cases: save card on file, loyalty enrollment, pre-authorization.

#### Request body (required)

Media type: `application/json`. Schema: `ProxyCardAcquisitionRequest`.

#### Responses

*   **200** Card acquired successfully
    
    Media type: `application/json`. Schema: `ProxyCardAcquisitionResponse`.
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### POST Display content on terminal screen

`POST /api/v1/terminal/{terminalId}/display`

Operation ID: `displayOnTerminal`. Tags: Terminal Display.

Sends virtual receipt or other display content to the terminal screen. This is an unsigned POST (no HMAC headers) as display operations are low-risk.

#### Parameters

*   `terminalId` (path, string, required)

#### Request body (required)

Media type: `application/json`. Schema: `ProxyDisplayRequest`.

#### Responses

*   **200** Display updated successfully
    
    Media type: `application/json`. Schema: `ProxyDisplayResponse`.
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    

### POST Clear terminal display

`POST /api/v1/terminal/{terminalId}/display/clear`

Operation ID: `clearDisplay`. Tags: Terminal Display.

Resets the terminal screen to idle state. Unsigned POST (no HMAC headers).

#### Parameters

*   `terminalId` (path, string, required)

#### Responses

*   **200** Display cleared
    
    Media type: `application/json`. Schema: `ProxyDisplayResponse`.
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    

### POST Collect input from terminal

`POST /api/v1/terminal/{terminalId}/input`

Operation ID: `collectInput`. Tags: Terminal Input.

Prompts the terminal to collect customer input (text, digit string, or confirmation). Unsigned POST. Timeout is 120s to allow for customer interaction.

#### Parameters

*   `terminalId` (path, string, required)

#### Request body (required)

Media type: `application/json`. Schema: `ProxyInputRequest`.

#### Responses

*   **200** Input collected
    
    Media type: `application/json`. Schema: `ProxyInputResponse`.
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    

### POST Cancel pending terminal input

`POST /api/v1/terminal/{terminalId}/input/cancel`

Operation ID: `cancelTerminalInput`. Tags: Terminal Input.

Cancels any pending input collection on the terminal. Unsigned POST.

#### Parameters

*   `terminalId` (path, string, required)

#### Responses

*   **200** Input cancelled
    
    Media type: `application/json`. Schema: `ProxyInputResponse`.
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    

### POST Create a Pay By Link payment link

`POST /api/v1/paybylink`

Operation ID: `createPaymentLink`. Tags: Pay By Link. Security: hmacAuth.

Creates a payment link that can be sent to a customer via email, SMS, or QR code. The customer opens the link in a browser to complete payment without a physical terminal.

After creating the link, the client may subscribe to WebSocket events for real-time status updates (PBL\_LINK\_CREATED, PBL\_PAYMENT\_STARTED, PBL\_PAYMENT\_APPROVED, etc.).

**HMAC signed**: Yes (with amount)

#### Parameters

*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `PBLCreateRequest`.

_Example_

```
{
  "transactionId": "pbl-550e8400-e29b-41d4-a716-446655440000",
  "amount": 49.99,
  "currency": "USD",
  "gateway": "worldpay",
  "shopperEmail": "shopper@example.com",
  "merchantReference": "PS-ORDER-001",
  "tokenize": true,
  "captureNow": false,
  "timestamp": "2026-03-23T10:00:00.000Z"
}
```

#### Responses

*   **201** Payment link created
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `PBLCreateResponse`.
    
    _Example_
    
    ```
    {
      "paymentLinkId": "PL-12345",
      "url": "https://pay.example.com/link/PL-12345",
      "expiresAt": "2026-03-24T10:00:00Z",
      "status": "ACTIVE",
      "gatewayContext": {
        "checkoutSessionId": "CS-789"
      }
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### POST Expire an active payment link

`POST /api/v1/paybylink/{paymentLinkId}/expire`

Operation ID: `expirePaymentLink`. Tags: Pay By Link. Security: hmacAuth.

Expires a payment link that has not yet been used. After expiration, the link URL returns an error page and no payment can be made.

**HMAC signed**: Yes (without amount)

#### Parameters

*   `paymentLinkId` (path, string, required) Unique identifier of the payment link, as returned by the createPaymentLink endpoint.  
    Example: `PL-12345`.
*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `object`.

*   `transactionId` (_string_, required) Unique ID for this expire request
*   `originalTransactionId` (_string_) The payment link ID being expired
*   `currency` (_string_)
*   `timestamp` (_string (date-time)_, required)
*   `gatewayContext` (_GatewayContext_)

#### Responses

*   **200** Payment link expired
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `PBLExpireResponse`.
    
    _Example_
    
    ```
    {
      "paymentLinkId": "PL-12345",
      "status": "EXPIRED"
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### GET Check the status of a payment link

`GET /api/v1/paybylink/{paymentLinkId}/status`

Operation ID: `checkPaymentLinkStatus`. Tags: Pay By Link.

Returns the current status of a payment link including payment details if the link has been used. No HMAC signing required for GET requests.

**HMAC signed**: No

#### Parameters

*   `paymentLinkId` (path, string, required) Unique identifier of the payment link, as returned by the createPaymentLink endpoint.  
    Example: `PL-12345`.

#### Responses

*   **200** Payment link status retrieved
    
    Media type: `application/json`. Schema: `PBLStatusResponse`.
    
    _Example_
    
    ```
    {
      "paymentLinkId": "PL-12345",
      "status": "APPROVED",
      "amount": 49.99,
      "cardDetails": {
        "maskedPan": "****1234",
        "cardBrand": "VISA",
        "entryMethod": "ECOMMERCE",
        "fundingSource": "CREDIT"
      }
    }
    ```
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    

### POST Refund or void a PBL payment

`POST /api/v1/paybylink/{paymentLinkId}/refund`

Operation ID: `refundPaymentLink`. Tags: Pay By Link. Security: hmacAuth.

Processes a refund or void for a payment made via a payment link. The SPI server decides whether to perform a refund or void based on the settlement state of the original transaction.

*   **Refund** (amount present): Refunds the specified amount. May be a partial refund (amount less than original) or full refund.
*   **Void** (amount absent/null): Voids the pre-settlement authorization. The server determines internally whether a void is possible.

**HMAC signed**: Yes (with amount when present, without amount when absent)

#### Parameters

*   `paymentLinkId` (path, string, required) Unique identifier of the payment link, as returned by the createPaymentLink endpoint.  
    Example: `PL-12345`.
*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `PBLRefundRequest`.

_Example: refund_ Refund with amount (partial or full refund)

```
{
  "transactionId": "rfnd-001",
  "originalTransactionId": "txn-001",
  "amount": 10.5,
  "currency": "USD",
  "timestamp": "2026-03-23T12:00:00.000Z"
}
```

_Example: void_ Void (no amount — server performs void)

```
{
  "transactionId": "void-001",
  "originalTransactionId": "txn-001",
  "currency": "USD",
  "timestamp": "2026-03-23T12:00:00.000Z"
}
```

#### Responses

*   **200** Refund/void processed
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `PBLRefundResponse`.
    
    _Example: refunded_ Successful refund
    
    ```
    {
      "transactionId": "rfnd-001",
      "status": "REFUNDED",
      "refundId": "ref-gateway-001",
      "amount": 10.5
    }
    ```
    
    _Example: voided_ Successful void
    
    ```
    {
      "transactionId": "void-001",
      "status": "VOIDED",
      "message": "Authorization voided successfully"
    }
    ```
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **503**
    
    **503 Proxy Unavailable**
    
    The SPI server itself is not available (e.g., starting up, shutting down, or experiencing an internal error).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "SPI_UNAVAILABLE",
      "message": "Payment SPI server is unavailable"
    }
    ```
    
*   **504**
    
    **504 Gateway Timeout**
    
    The SPI server did not receive a response from the payment gateway or terminal within the expected time window.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "GATEWAY_TIMEOUT",
      "message": "Payment gateway did not respond in time"
    }
    ```
    

### GET Query offline (SAF) transactions from the terminal

`GET /api/v1/offline/transactions`

Operation ID: `queryOfflineTransactions`. Tags: Offline.

Retrieves stored-and-forwarded transactions from the terminal's SAF queue. The SPI server proxies this request to the terminal hardware — it does not independently track SAF state. Not all terminals support SAF query; gated by `DeviceCapabilities.supportsOfflineSAFQuery`.

**HMAC signed**: No

#### Parameters

*   `terminalId` (query, string, required) Terminal to query SAF queue for  
    Example: `T-001`.
*   `gateway` (query, string, required) Gateway identifier  
    Example: `worldpay`.
*   `startTime` (query, number (double)) Unix timestamp (seconds since epoch). Only return transactions after this time.  
    Example: `1774537200`.

#### Responses

*   **200** SAF transactions retrieved
    
    Media type: `application/json`. Schema: `SAFQueryResponse`.
    
    _Example: withTransactions_ Queue with transactions
    
    ```
    {
      "transactions": [
        {
          "transactionId": "txn-001",
          "status": "APPROVED",
          "amount": 49.99,
          "currency": "USD",
          "maskedPan": "****1234",
          "cardBrand": "VISA",
          "entryMethod": "CHIP",
          "timestamp": "2026-03-23T10:00:00Z",
          "gatewayContext": {}
        }
      ],
      "terminalId": "T-001",
      "queryTimestamp": "2026-03-23T11:00:00Z"
    }
    ```
    
    _Example: empty_ Empty queue
    
    ```
    {
      "transactions": [],
      "terminalId": "T-001",
      "queryTimestamp": "2026-03-23T11:00:00Z"
    }
    ```
    
*   **400** Missing required parameters
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **404**
    
    **404 Transaction Not Found**
    
    The specified transaction ID does not exist on the proxy. The response body SHOULD include the transaction ID in `details.transactionId`.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TRANSACTION_NOT_FOUND",
      "message": "Transaction not found",
      "details": {
        "transactionId": "550e8400-e29b-41d4-a716-446655440000"
      }
    }
    ```
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    

### POST Validate and complete a partial offline payment payload

`POST /api/v1/payment/validate-offline`

Operation ID: `validateOfflinePayment`. Tags: Offline. Security: hmacAuth.

Accepts an incomplete payment payload captured offline by a partial-offline gateway (e.g., Elavon) and sends it to the gateway for server-side completion. Used when `DeviceCapabilities.offlinePaymentMode == .partialOffline` and `DeviceCapabilities.requiresOfflinePayloadValidation == true`.

**HMAC signed**: Yes (with amount)

#### Parameters

*   `X-HMAC` (header, string, required) HMAC-SHA256 hex digest computed over the pipe-delimited message string using the pre-shared secret. See the Security section for the exact message format.
*   `X-Nonce` (header, string, required) Unique single-use token for replay protection. The server SHOULD reject requests with previously seen nonces. Format: UUID string or equivalent unique token.
*   `X-Store-ID` (header, string, required) Identifier of the store making the request. Included as a component of the HMAC message to scope signatures to a specific store.
*   `X-Register-ID` (header, string, required) Identifier of the POS register/device making the request. Included as a component of the HMAC message to scope signatures to a specific register within the store.

#### Request body (required)

Media type: `application/json`. Schema: `ValidateOfflineRequest`.

_Example_

```
{
  "transactionId": "txn-offline-001",
  "amount": 49.99,
  "currency": "USD",
  "gateway": "elavon",
  "terminalId": "T-001",
  "offlinePayload": {
    "cardData": "<encrypted-partial-payload>",
    "captureTimestamp": "2026-03-23T09:30:00Z",
    "terminalSequenceNumber": 42
  },
  "timestamp": "2026-03-23T11:00:00Z"
}
```

#### Responses

*   **200** Offline payment validated
    
    Headers:
    
    *   `X-HMAC` (string) HMAC-SHA256 signature of the response body
    
    Media type: `application/json`. Schema: `ValidateOfflineResponse`.
    
    _Example: approved_ Validation approved
    
    ```
    {
      "transactionId": "txn-offline-001",
      "status": "APPROVED",
      "authCode": "AUTH123",
      "receiptData": {
        "merchantCopy": [
          {
            "key": "authCode",
            "display": "Auth Code",
            "value": "AUTH123"
          }
        ],
        "customerCopy": [
          {
            "key": "authCode",
            "display": "Auth Code",
            "value": "AUTH123"
          }
        ]
      },
      "timestamp": "2026-03-23T11:00:05Z",
      "gatewayContext": {}
    }
    ```
    
    _Example: declined_ Validation declined
    
    ```
    {
      "transactionId": "txn-offline-001",
      "status": "DECLINED",
      "timestamp": "2026-03-23T11:00:05Z",
      "gatewayContext": {}
    }
    ```
    
*   **400** Missing or malformed offline payload
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **401**
    
    **401 Authentication Failed**
    
    The client certificate was rejected or missing (mTLS failure), or HMAC credentials are invalid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "AUTHENTICATION_FAILED",
      "message": "Client certificate rejected or missing"
    }
    ```
    
*   **409**
    
    **409 HMAC Validation Failed**
    
    The HMAC signature in the `X-HMAC` header does not match the expected value computed from the request body and headers. This may indicate a replay attack, clock skew, or misconfigured shared secret.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "HMAC_VALIDATION_FAILED",
      "message": "Request signature validation failed"
    }
    ```
    
*   **502** Gateway unreachable (retry later)
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    

### GET Query terminal offline status (optional — Nice to Have)

`GET /api/v1/terminal/{terminalId}/offline-status`

Operation ID: `getTerminalOfflineStatus`. Tags: Offline.

Returns whether the terminal is currently operating in offline mode. The SPI server proxies this query to the terminal hardware — it does not independently track terminal state. Not all terminals expose their offline status; gated by `DeviceCapabilities.supportsTerminalOfflineStatus`.

**HMAC signed**: No

#### Parameters

*   `terminalId` (path, string, required) Device ID of the terminal as registered with the SPI server. Must exactly match the terminalId used during terminal registration/discovery.  
    Example: `T-001`.
*   `gateway` (query, string, required) Gateway identifier  
    Example: `worldpay`.

#### Responses

*   **200** Terminal offline status retrieved
    
    Media type: `application/json`. Schema: `TerminalOfflineStatus`.
    
    _Example_
    
    ```
    {
      "terminalId": "T-001",
      "isOffline": true,
      "safQueueDepth": 5,
      "lastOnlineTimestamp": "2026-03-23T09:00:00Z",
      "timestamp": "2026-03-23T11:00:00Z"
    }
    ```
    
*   **404** Terminal not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **501** Terminal/gateway does not support offline status query
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
*   **502**
    
    **502 Terminal Offline**
    
    The proxy cannot reach the payment terminal. The terminal may be powered off, disconnected from the network, or unresponsive.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example_
    
    ```
    {
      "error": "TERMINAL_OFFLINE",
      "message": "Payment terminal is offline or unreachable"
    }
    ```
    

## Schemas

### PaymentRequest

*   `transactionId` (_string (uuid)_, required) Unique identifier for this transaction, generated by the client. Used as the correlation ID across WebSocket events, logs, status queries, and subsequent operations (cancel, void, capture). Must be a valid UUID v4 string.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `amount` (_number (decimal)_, required) Payment amount with decimal precision (e.g., 49.99). Represents the total charge to the cardholder. For pre-authorizations, this is the hold amount. Implementations MUST preserve at least 2 decimal places.  
    Example: `49.99`.
*   `currency` (_string_, required) ISO 4217 three-letter currency code (e.g., "USD", "EUR", "GBP"). Must be exactly 3 characters.  
    Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `gateway` (_string_, required) Identifier of the payment gateway configured on the SPI server (e.g., "worldpay", "stripe\_terminal", "adyen"). The proxy uses this to route the request to the correct gateway SDK.  
    Example: `worldpay`.
*   `terminalId` (_string_, required) Device ID of the payment terminal registered with the proxy server (e.g., "T-001"). Identifies which physical terminal should process the transaction.  
    Example: `T-001`.
*   `paymentType` (_PaymentType_, required)
*   `metadata` (_object_, nullable) Optional key-value pairs (string keys, string values) forwarded to the gateway. Use for passing order IDs, cashier IDs, or other context the gateway may need for reconciliation or reporting.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "orderId": "ORD-12345",
      "cashierId": "C-42"
    }
    ```
    
*   `timestamp` (_string (date-time)_, required) Creation timestamp of the request in ISO 8601 format. Included in the HMAC signature so the server can detect stale or replayed requests.  
    Example: `2026-03-12T14:04:06.000Z`.

### PaymentResponse

*   `transactionId` (_string (uuid)_, required) Echo of the transaction ID from the request. Confirms which transaction this response belongs to.
*   `status` (_PaymentStatus_, required)
*   `authCode` (_string_, nullable) Authorization code issued by the payment processor when the transaction is approved. Null/absent when status is not "APPROVED".  
    Example: `AUTH123456`.
*   `requestId` (_string_, nullable) The acquirer's transaction identifier (e.g., Adyen pspReference, Worldpay transaction reference). This is the primary reference used for reconciliation with the payment processor. The POS maps this to its internal TenderData.requestId.  
    Example: `PSP-REF-789`.
*   `alternateRequestId` (_string_, nullable) A secondary transaction reference from the gateway (e.g., Adyen txRef from receipt data). Provides an additional reconciliation point. The POS maps this to its internal TenderData.alternateRequestId.  
    Example: `TX-REF-456`.
*   `receiptData` (_ReceiptData_)
*   `cardDetails` (_CardDetails_)
*   `timestamp` (_string (date-time)_, required) Timestamp when the proxy generated this response. ISO 8601 format.
*   `gatewayContext` (_GatewayContext_)

### ErrorResponse

Standard error response body returned for all non-2xx HTTP responses. Provides both a machine-readable error code for programmatic handling and a human-readable message for logging.

*   `error` (_string_) Machine-readable error code. Use this for programmatic error handling. Values: "AUTHENTICATION\_FAILED", "TRANSACTION\_NOT\_FOUND", "HMAC\_VALIDATION\_FAILED", "TERMINAL\_OFFLINE", "SPI\_UNAVAILABLE", "GATEWAY\_TIMEOUT".  
    Example: `TRANSACTION_NOT_FOUND`.
*   `message` (_string_) Human-readable error description for logging and debugging. Not intended for display to end users.  
    Example: `Transaction 550e8400-... not found`.
*   `details` (_object_) Additional context about the error. Currently supports transactionId to identify which transaction triggered the error.
    *   `transactionId` (_string_) The transaction ID related to the error, when applicable. Included in 404 responses to confirm which transaction was not found.

### CancellationRequest

*   `transactionId` (_string (uuid)_, required) The transaction ID of the in-progress payment to cancel. Must match the path parameter.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `reason` (_string_, nullable) Human-readable reason for the cancellation. Forwarded to the gateway for logging/reconciliation. Suggested values: "customer\_requested", "timeout", "operator\_cancelled".  
    Example: `customer_requested`.
*   `timestamp` (_string (date-time)_, required) Request creation timestamp in ISO 8601 format. Included in the HMAC signature (without-amount format for cancel operations).  
    Example: `2026-03-12T14:05:00.000Z`.
*   `gatewayContext` (_GatewayContext_)

### CancellationResponse

*   `transactionId` (_string (uuid)_, required) The transaction ID of the payment that was the target of the cancellation request.
*   `cancelled` (_boolean_, required) true if the cancellation was successfully processed by the terminal/gateway; false if the cancellation could not be applied (e.g., transaction already authorized).
*   `message` (_string_, nullable) Human-readable message providing additional context from the proxy or gateway. Example: "Transaction cancelled successfully" or "Cannot cancel - transaction already authorized".

### VoidRequest

*   `transactionId` (_string (uuid)_, required) The transaction ID of the authorized payment to void. Must match the path parameter. The transaction must not yet be settled.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `reason` (_string_, nullable) Human-readable reason for the void. Forwarded to the gateway for logging/reconciliation. Suggested values: "operator\_void", "duplicate", "customer\_requested".  
    Example: `operator_void`.
*   `timestamp` (_string (date-time)_, required) Request creation timestamp in ISO 8601 format. Included in the HMAC signature (without-amount format for void operations).  
    Example: `2026-03-12T14:06:00.000Z`.
*   `gatewayContext` (_GatewayContext_)

### VoidResponse

*   `transactionId` (_string (uuid)_, required) The transaction ID of the payment that was the target of the void request.
*   `voided` (_boolean_, required) true if the void was successfully processed by the gateway; false if the void could not be applied (e.g., transaction already settled in the gateway batch).
*   `message` (_string_, nullable) Human-readable message from the proxy or gateway providing additional context about the void result.
*   `gatewayContext` (_GatewayContext_)

### CaptureRequest

*   `transactionId` (_string (uuid)_, required) The transaction ID of the pre-authorized payment to capture. Must match the path parameter and reference a transaction that was initiated with paymentType "pre\_authorization".  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `amount` (_number (decimal)_, required) Capture amount with decimal precision. Must be less than or equal to the original pre-authorization amount. For a full capture, use the same amount. For a partial capture, use a smaller amount.  
    Example: `45`.
*   `currency` (_string_, required) ISO 4217 three-letter currency code. Must match the currency of the original pre-authorization.  
    Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `gatewayContext` (_GatewayContext_)

### CaptureResponse

*   `transactionId` (_string (uuid)_, required) The transaction ID of the pre-authorized payment that was captured.
*   `status` (_PaymentStatus_, required)
*   `authCode` (_string_, nullable) Authorization code from the payment processor for the capture operation. Null when the capture was not approved.
*   `timestamp` (_string (date-time)_, required) Timestamp when the proxy generated this response. ISO 8601 format.
*   `gatewayContext` (_GatewayContext_)

### RefundRequest

*   `transactionId` (_string (uuid)_, required) Unique identifier for this refund transaction, generated by the client. Distinct from any original payment transaction ID.  
    Example: `660e8400-e29b-41d4-a716-446655440001`.
*   `originalTransactionId` (_string (uuid)_, nullable) The transaction ID of the original payment being refunded. Required when refundType is "referenced" -- the gateway uses this to link the refund to the original charge for reconciliation. Omit or set to null for unreferenced refunds.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `amount` (_number (decimal)_, required) Refund amount with decimal precision. For referenced refunds, may be less than or equal to the original payment amount (partial refund). For unreferenced refunds, this is the credit amount.  
    Example: `10`.
*   `currency` (_string_, required) ISO 4217 three-letter currency code. For referenced refunds, must match the original payment's currency.  
    Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `gateway` (_string_, required) Gateway identifier configured on the proxy. Must match the gateway used for the original payment (referenced) or the desired gateway (unreferenced).  
    Example: `worldpay`.
*   `terminalId` (_string_, nullable) Terminal device ID. The refund is processed at this terminal, which prompts the cardholder to present their card. Nullable for PBL refunds routed through the standard refund endpoint (no terminal involved).  
    Example: `T-001`.
*   `refundType` (_RefundType_, required)
*   `metadata` (_object_, nullable) Optional key-value pairs (string keys, string values) forwarded to the gateway for reconciliation or reporting.
    
    Additional properties: `string`.
    
*   `timestamp` (_string (date-time)_, required) Request creation timestamp in ISO 8601 format. Included in the HMAC signature so the server can detect stale requests.  
    Example: `2026-03-12T15:00:00.000Z`.
*   `gatewayContext` (_GatewayContext_)

### RefundResponse

*   `transactionId` (_string (uuid)_, required) The refund transaction ID matching the original request. Confirms which refund this response belongs to.
*   `status` (_PaymentStatus_, required)
*   `authCode` (_string_, nullable) Authorization code from the payment processor for the refund, if approved. Null when status is not "APPROVED".
*   `timestamp` (_string (date-time)_, required) Timestamp when the proxy generated this response. ISO 8601 format.
*   `gatewayContext` (_GatewayContext_)

### HealthResponse

*   `status` (_string_, required) Overall server health status. Expected values: "ok" (all systems operational) or "degraded" (some checks failing but server is responding).  
    Example: `ok`.
*   `version` (_string_, nullable) Proxy server software version string. Useful for diagnostics and support.  
    Example: `1.2.0`.
*   `uptime` (_number_, nullable) Server uptime in seconds since the proxy process started. Decimal value for sub-second precision.  
    Example: `86400.5`.
*   `timestamp` (_string (date-time)_, nullable) Server response timestamp in ISO 8601 format.
*   `checks` (_object_, nullable) Named health check results as key-value pairs. Each key is a subsystem name, each value is its status string. Used to identify which specific component is unhealthy.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "database": "ok",
      "gateway": "ok"
    }
    ```
    
*   `certificateExpiry` (_string (date-time)_, nullable) Expiry date of the SPI server's TLS certificate in ISO 8601 format. The POS client uses this for proactive alerting before certificate expiration causes outages.  
    Example: `2027-03-12T00:00:00Z`.

### TerminalStatus

*   `terminalId` (_string_, required) The terminal device ID, echoed back for confirmation.  
    Example: `T-001`.
*   `online` (_boolean_, required) true if the proxy can reach the terminal and it is responding to heartbeats; false if the terminal is unreachable, powered off, or has not sent a heartbeat within the expected window.
*   `lastSeen` (_string (date-time)_, nullable) Timestamp of the last successful heartbeat or communication from this terminal. Null if the terminal has never been seen by the proxy.
*   `gateway` (_string_, nullable) The payment gateway this terminal is configured for (e.g., "worldpay", "stripe\_terminal").  
    Example: `worldpay`.

### TerminalInfo

*   `terminalId` (_string_, required) Unique device ID of the terminal as registered with the proxy.  
    Example: `T-001`.
*   `name` (_string_, required) Human-readable display name for the terminal. Shown in the POS terminal selection UI.  
    Example: `Register 1 Terminal`.
*   `ipAddress` (_string_, nullable) IP address of the terminal on the store LAN. Null if the terminal communicates via a non-IP protocol.  
    Example: `192.168.1.100`.
*   `online` (_boolean_, required) Whether the terminal is currently online and reachable by the proxy.
*   `gateway` (_string_, required) The payment gateway this terminal is configured for (e.g., "worldpay", "stripe\_terminal").  
    Example: `worldpay`.
*   `modelNumber` (_string_, nullable) Terminal hardware model number (e.g., "VX820", "Lane/3000"). Useful for support and diagnostics.  
    Example: `VX820`.
*   `serialNumber` (_string_, nullable) Terminal serial number. Useful for support and asset tracking.  
    Example: `SN-123456`.

### ProxyGiftCardRequest

*   `transactionId` (_string (uuid)_, required) Unique transaction identifier
*   `operationType` (_string_, required) The gift card operation to perform  
    Allowed values: `activate`, `load`, `unload`, `balance`, `cashout`, `payment`, `reversal`, `refund`, `verify`.
*   `cardNumber` (_string_, nullable) Gift card number (null if terminal reads it)
*   `amount` (_number_, nullable) Amount in minor units. Required for load, unload, cashout, payment, reversal, refund
*   `currency` (_string_, required) ISO 4217 currency code  
    Example: `USD`.
*   `gateway` (_string_, required) Gateway identifier from proxy configuration
*   `terminalId` (_string_, required) Terminal identifier
*   `originalTransactionId` (_string_, nullable) Required for reversal and verify operations
*   `metadata` (_object_, nullable)
    
    Additional properties: `string`.
    
*   `timestamp` (_string (date-time)_)
*   `gatewayContext` (_GatewayContext_)

### ProxyGiftCardResponse

*   `transactionId` (_string_, required)
*   `status` (_PaymentStatus_, required)
*   `balance` (_number_, nullable) Current card balance
*   `authCode` (_string_, nullable) Authorization code from gateway
*   `cardNumber` (_string_, nullable) Card number (may differ from request if terminal read card)
*   `timestamp` (_string (date-time)_, required)
*   `gatewayContext` (_GatewayContext_)

### ProxyCardAcquisitionRequest

*   `transactionId` (_string (uuid)_, required)
*   `terminalId` (_string_, required)
*   `gateway` (_string_, required)
*   `paymentAmount` (_number_, nullable) Optional amount for $0 auth verification
*   `metadata` (_object_, nullable)
    
    Additional properties: `string`.
    
*   `timestamp` (_string (date-time)_, required)

### ProxyCardAcquisitionResponse

*   `transactionId` (_string_, required)
*   `status` (_PaymentStatus_, required)
*   `paymentToken` (_string_, nullable) Tokenized card reference for future use
*   `paymentBrand` (_string_, nullable) Card brand (e.g., visa, mastercard)
*   `maskedPan` (_string_, nullable) Masked card number (e.g., \*\*\*\*1234)
*   `first6` (_string_, nullable) First 6 digits (BIN)
*   `last4` (_string_, nullable) Last 4 digits
*   `entryMethod` (_string_, nullable)  
    Allowed values: `chip`, `contactless`, `swipe`, `manual`.
*   `timestamp` (_string (date-time)_, required)

### ProxyDisplayRequest

*   `lines` (_array of ProxyDisplayLine_, required)
*   `terminalId` (_string_, required)

### ProxyDisplayResponse

*   `success` (_boolean_, required)
*   `message` (_string_, nullable)

### ProxyInputRequest

*   `inputType` (_string_, required)  
    Allowed values: `text`, `digitString`, `getConfirmation`.
*   `promptLines` (_array of string_, required)
*   `terminalId` (_string_, required)

### ProxyInputResponse

*   `success` (_boolean_, required)
*   `value` (_string_, nullable) Text/digit value (for text and digitString types)
*   `confirmed` (_boolean_, nullable) Confirmation result (for getConfirmation type)
*   `message` (_string_, nullable)

### PBLCreateRequest

*   `transactionId` (_string_, required) Unique identifier for this PBL transaction, generated by the client.  
    Example: `pbl-550e8400-e29b-41d4-a716-446655440000`.
*   `amount` (_number (decimal)_, required) Payment amount with decimal precision.  
    Example: `49.99`.
*   `currency` (_string_, required) ISO 4217 three-letter currency code.  
    Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `gateway` (_string_, required) Gateway identifier configured on the proxy (e.g., "worldpay").  
    Example: `worldpay`.
*   `shopperEmail` (_string_, nullable) Email address of the shopper. Used by some gateways to send the payment link directly to the customer.  
    Example: `shopper@example.com`.
*   `merchantReference` (_string_, nullable) Merchant-defined reference for the payment (e.g., order ID).  
    Example: `PS-ORDER-001`.
*   `tokenize` (_boolean_, nullable) Whether to tokenize the card used for payment. Default: false.
*   `captureNow` (_boolean_, nullable) If true, capture immediately on authorization. If false, authorize only (requires separate capture). Default determined by gateway config.
*   `timestamp` (_string (date-time)_, required) Request creation timestamp in ISO 8601 format. Included in the HMAC signature.  
    Example: `2026-03-23T10:00:00.000Z`.

### PBLCreateResponse

*   `paymentLinkId` (_string_, required) Unique identifier for the created payment link. Used in subsequent expire, status, and refund calls.  
    Example: `PL-12345`.
*   `url` (_string (uri)_, required) The payment link URL to send to the customer. Can be rendered as a QR code or sent via email/SMS.  
    Example: `https://pay.example.com/link/PL-12345`.
*   `expiresAt` (_string (date-time)_, nullable) When the payment link expires in ISO 8601 format. After this time the link is no longer usable.  
    Example: `2026-03-24T10:00:00Z`.
*   `status` (_string_, required) Initial status of the link. Should be "ACTIVE" on successful creation.  
    Example: `ACTIVE`.
*   `gatewayContext` (_GatewayContext_)

### GatewayContext

Opaque gateway-specific context for transaction round-tripping. Returned by the SPI server in responses that create or modify transactions. The client stores this verbatim and passes it back in subsequent operations (void, capture, refund). The client MUST NOT parse or modify this object. When absent in a request, the server falls back to stateful lookup by transactionId. Size SHOULD be kept under 4KB.

_Example_

```
{
  "pspReference": "8535516979155668",
  "merchantReference": "ORD-12345"
}
```

### PBLExpireResponse

*   `paymentLinkId` (_string_, required) The payment link ID that was expired.  
    Example: `PL-12345`.
*   `status` (_string_, required) Status after expiration. Should be "EXPIRED".  
    Example: `EXPIRED`.

### PBLStatusResponse

*   `paymentLinkId` (_string_, required) The payment link ID.  
    Example: `PL-12345`.
*   `status` (_PBLStatus_, required)
*   `amount` (_number (decimal)_, nullable) Payment amount, present when a payment has been attempted.  
    Example: `49.99`.
*   `cardDetails` (_CardDetails_)
*   `additionalData` (_object_, nullable) Gateway-specific additional data returned with the status.
*   `gatewayContext` (_GatewayContext_)

### PBLRefundRequest

*   `transactionId` (_string_, required) Unique identifier for this refund/void transaction.  
    Example: `rfnd-001`.
*   `originalTransactionId` (_string_, required) The original payment transaction ID being refunded/voided.  
    Example: `txn-001`.
*   `amount` (_number (decimal)_, nullable) Refund amount. When present, a refund is performed for the specified amount (may be partial). When absent or null, the server performs a void of the pre-settlement authorization.  
    Example: `10.5`.
*   `currency` (_string_, required) ISO 4217 three-letter currency code.  
    Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `timestamp` (_string (date-time)_, required) Request creation timestamp in ISO 8601 format. Included in HMAC.  
    Example: `2026-03-23T12:00:00.000Z`.
*   `gatewayContext` (_GatewayContext_)

### PBLRefundResponse

*   `transactionId` (_string_, required) Echo of the refund/void transaction ID from the request.  
    Example: `rfnd-001`.
*   `status` (_string_, required) Result status. "REFUNDED" for successful refunds, "VOIDED" for successful voids, "DECLINED" or "ERROR" for failures.  
    Allowed values: `REFUNDED`, `VOIDED`, `DECLINED`, `ERROR`. Example: `REFUNDED`.
*   `refundId` (_string_, nullable) Gateway-assigned refund reference ID. Present for successful refunds.  
    Example: `ref-gateway-001`.
*   `amount` (_number (decimal)_, nullable) The refunded amount. Present for refunds, absent for voids.  
    Example: `10.5`.
*   `message` (_string_, nullable) Human-readable message providing additional context, especially for void responses or error details.  
    Example: `Authorization voided successfully`.
*   `gatewayContext` (_GatewayContext_)

### SAFQueryResponse

*   `transactions` (_array of SAFTransaction_, required) List of offline transactions from the terminal's SAF queue. Empty array if no transactions are queued.
*   `terminalId` (_string_, required) The terminal that was queried.  
    Example: `T-001`.
*   `queryTimestamp` (_string (date-time)_, required) When the query was executed (ISO 8601).

### ValidateOfflineRequest

*   `transactionId` (_string_, required) Unique identifier for this offline transaction.  
    Example: `txn-offline-001`.
*   `amount` (_number (decimal)_, required) Payment amount with decimal precision.  
    Example: `49.99`.
*   `currency` (_string_, required) ISO 4217 currency code.  
    Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `gateway` (_string_, required) Gateway identifier.  
    Example: `elavon`.
*   `terminalId` (_string_, required) Terminal that captured the offline payment.  
    Example: `T-001`.
*   `offlinePayload` (_object_, required) Gateway-specific partial payment payload captured offline by the terminal. Opaque to the iOS client — passed through to the SPI server which forwards it to the gateway for completion.
*   `timestamp` (_string (date-time)_, required) Request creation timestamp (ISO 8601). Included in HMAC.

### ValidateOfflineResponse

*   `transactionId` (_string_, required) Echo of the transaction ID from the request.  
    Example: `txn-offline-001`.
*   `status` (_PaymentStatus_, required)
*   `authCode` (_string_, nullable) Authorization code from the gateway, if approved.  
    Example: `AUTH123`.
*   `receiptData` (_ReceiptData_)
*   `timestamp` (_string (date-time)_, required) When the server generated this response (ISO 8601).
*   `gatewayContext` (_GatewayContext_)

### TerminalOfflineStatus

Terminal offline status. Only available when the terminal/gateway supports reporting this information. The SPI server proxies to the terminal.

*   `terminalId` (_string_, required) The terminal device ID.  
    Example: `T-001`.
*   `isOffline` (_boolean_, required) true if the terminal is currently operating in offline mode; false if operating normally with gateway connectivity.
*   `safQueueDepth` (_integer_, nullable) Number of transactions in the terminal's SAF queue. Null if the terminal does not report queue depth.  
    Example: `5`.
*   `lastOnlineTimestamp` (_string (date-time)_, nullable) When the terminal was last online (ISO 8601). Null if not reported.
*   `timestamp` (_string (date-time)_, required) When the server generated this response (ISO 8601).

### PaymentType

The type of payment transaction:

*   "sale": Standard transaction that settles immediately in the gateway's next batch.
*   "pre\_authorization": Hold placed on the cardholder's account. Requires a separate capture call before settlement. The hold amount may be partially or fully captured.

Type: `string`.

Allowed values: `sale`, `pre_authorization`. Example: `sale`.

### PaymentStatus

Terminal payment authorization result:

*   "APPROVED": Payment authorized by the card issuer.
*   "DECLINED": Payment declined by the card issuer.
*   "CANCELLED": Payment cancelled by operator or customer before authorization completed.
*   "ERROR": An error occurred during processing on the terminal or gateway.
*   "TIMEOUT": The terminal or card issuer did not respond within the expected time window.
*   "PENDING": Partial authorization received (split-tender scenario where the issuer approved less than requested).

Type: `string`.

Allowed values: `APPROVED`, `DECLINED`, `CANCELLED`, `ERROR`, `TIMEOUT`, `PENDING`. Example: `APPROVED`.

### ReceiptData

Structured receipt data returned after a successful payment. Contains separate arrays for merchant and customer receipt copies. Null when the terminal does not return receipt data (e.g., declined transactions).

*   `merchantCopy` (_array of ReceiptLine_, nullable) Structured line items for the merchant's receipt copy. May contain additional fields not present in the customer copy (e.g., cardholder verification method). Null when the gateway does not provide structured receipt data.
*   `customerCopy` (_array of ReceiptLine_, nullable) Structured line items for the customer's receipt copy. Typically a subset of the merchant copy.

### CardDetails

Masked card information returned by the terminal after a payment. Null when no card was presented (e.g., transaction cancelled before card insert).

*   `maskedPan` (_string_, required) Masked Primary Account Number. Only the last 4 digits are visible (e.g., "\*\*\*\*1234"). The terminal/gateway handles masking; the proxy passes it through.  
    Example: `****1234`.
*   `cardBrand` (_string_, required) Card network brand. Common values: "VISA", "MASTERCARD", "AMEX", "DISCOVER", "JCB", "UNIONPAY", "DINERS".  
    Example: `VISA`.
*   `entryMethod` (_string_, required) How the card was presented at the terminal: "CHIP" (EMV chip inserted), "CONTACTLESS" (NFC tap -- card or mobile wallet), "SWIPE" (magnetic stripe), "MANUAL" (manually keyed).  
    Allowed values: `CHIP`, `CONTACTLESS`, `SWIPE`, `MANUAL`. Example: `CHIP`.
*   `cardTypeVariant` (_string_, nullable) Card type variant as reported by the gateway. Common values: "CREDIT", "DEBIT". Null if the gateway does not distinguish card types.  
    Example: `CREDIT`.
*   `fundingSource` (_string_, nullable) Funding source of the card. Common values: "CREDIT", "DEBIT", "PREPAID". Null if not reported by the gateway.  
    Example: `CREDIT`.
*   `cardBin` (_string_, nullable) Bank Identification Number -- the first 6-8 digits of the PAN. Used for card identification and routing rules. Null if not reported by the gateway.  
    Example: `411111`.
*   `accountType` (_string_, nullable) Account type selected by the cardholder (for debit cards). Common values: "CHECKING", "SAVINGS". Null for credit cards or if not reported by the gateway.
*   `cardAlias` (_string_, nullable) Shopper reference or tokenized card alias from the gateway. Used for card-on-file or recurring payment scenarios. Null if the gateway does not provide a token.
*   `cardExpirationMonth` (_string_, nullable) Card expiration month as a two-digit string ("01" through "12"). Null if not reported by the gateway.  
    Example: `12`.
*   `cardExpirationYear` (_string_, nullable) Card expiration year. May be two-digit ("27") or four-digit ("2027") depending on the gateway. Null if not reported.  
    Example: `2027`.

### RefundType

Whether the refund is linked to an original transaction:

*   "referenced": Linked to an original payment via originalTransactionId. The gateway matches the refund to the original charge for reconciliation and reporting.
*   "unreferenced": Standalone credit to the card presented at the terminal, not linked to any prior transaction.

Type: `string`.

Allowed values: `referenced`, `unreferenced`. Example: `referenced`.

### ProxyDisplayLine

*   `type` (_string_, required)  
    Allowed values: `title`, `product`, `summary`, `total`, `taxItem`, `taxTotal`.
*   `content` (_string_, required)
*   `quantity` (_number_, nullable)
*   `amount` (_number_, nullable)

### PBLStatus

Status of a Pay By Link payment link:

*   "ACTIVE": Link created and awaiting payment.
*   "APPROVED": Payment completed successfully via the link.
*   "DECLINED": Payment attempted but declined by the issuer.
*   "EXPIRED": Link expired without payment.
*   "REFUNDED": Completed payment was refunded.
*   "VOIDED": Pre-settlement authorization was voided.
*   "ERROR": An error occurred during processing.

Type: `string`.

Allowed values: `ACTIVE`, `APPROVED`, `DECLINED`, `EXPIRED`, `REFUNDED`, `VOIDED`, `ERROR`. Example: `ACTIVE`.

### SAFTransaction

A single offline transaction from the terminal's Store and Forward queue. Contains only masked card data — no PAN, CVV, or PCI-scoped fields.

*   `transactionId` (_string_, required) Unique transaction identifier.
*   `status` (_PaymentStatus_, required)
*   `amount` (_number (decimal)_, required) Transaction amount with decimal precision.  
    Example: `49.99`.
*   `currency` (_string_, required) ISO 4217 currency code.  
    Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `maskedPan` (_string_, nullable) Masked card number (e.g., "\*\*\*\*1234").  
    Example: `****1234`.
*   `cardBrand` (_string_, nullable) Card network brand (e.g., "VISA", "MASTERCARD").  
    Example: `VISA`.
*   `entryMethod` (_string_, nullable) How the card was presented (CHIP, CONTACTLESS, SWIPE, MANUAL).  
    Example: `CHIP`.
*   `timestamp` (_string (date-time)_, required) When the transaction was captured on the terminal.
*   `gatewayContext` (_GatewayContext_)

### ReceiptLine

A single line item in a structured receipt. Maps 1:1 to the POS CardReaderReceiptLine model used by existing payment integrations.

*   `key` (_string_, required) Machine-readable identifier for this receipt field. Used programmatically to extract specific values (e.g., for mapping to POS tender data). Common keys: "pan", "aid", "authCode", "cardholderName", "transactionType".  
    Example: `pan`.
*   `display` (_string_, required) Human-readable label suitable for printing on a receipt. This is what appears to the left of the value on the printed receipt (e.g., "Card Number", "Auth Code", "AID").  
    Example: `Card Number`.
*   `value` (_string_, required) The data value for this receipt line. Always a string, even for numeric values. Sensitive data should already be masked by the terminal/gateway (e.g., PAN shown as "\*\*\*\*1234").  
    Example: `****1234`.

### PaymentEventType

Types of real-time payment events streamed via WebSocket. Maps to terminal state transitions during a payment flow:

*   "CONNECTED": WebSocket handshake complete, proxy ready.
*   "CARD\_INSERTED": Card inserted or tapped on terminal.
*   "PIN\_ENTRY\_STARTED": Terminal prompting for PIN entry.
*   "PIN\_ENTRY\_COMPLETED": Customer finished entering PIN.
*   "AUTHORIZATION\_STARTED": Terminal sending auth request to issuer.
*   "AUTHORIZATION\_APPROVED": Issuer approved the authorization.
*   "AUTHORIZATION\_DECLINED": Issuer declined the authorization.
*   "ERROR": An error occurred on the terminal.
*   "CANCELLED": Payment was cancelled.
*   "PBL\_LINK\_CREATED": Pay By Link URL generated and ready.
*   "PBL\_PAYMENT\_STARTED": Customer opened the payment link.
*   "PBL\_PAYMENT\_APPROVED": Payment completed via the link.
*   "PBL\_PAYMENT\_DECLINED": Payment attempted via link but declined.
*   "PBL\_LINK\_EXPIRED": Payment link expired without payment.

Type: `string`.

Allowed values: `CONNECTED`, `CARD_INSERTED`, `PIN_ENTRY_STARTED`, `PIN_ENTRY_COMPLETED`, `AUTHORIZATION_STARTED`, `AUTHORIZATION_APPROVED`, `AUTHORIZATION_DECLINED`, `ERROR`, `CANCELLED`, `PBL_LINK_CREATED`, `PBL_PAYMENT_STARTED`, `PBL_PAYMENT_APPROVED`, `PBL_PAYMENT_DECLINED`, `PBL_LINK_EXPIRED`.

### PaymentEvent

A real-time event received via the WebSocket connection during a payment flow. Events provide terminal status updates as the cardholder interacts with the terminal (card insert, PIN entry, authorization progress).

*   `eventType` (_PaymentEventType_, required)
*   `transactionId` (_string (uuid)_, required) The transaction this event belongs to. Matches the transactionId query parameter used to open the WebSocket connection.
*   `timestamp` (_string (date-time)_, required) When the event occurred on the proxy/terminal side, in ISO 8601 format.
*   `data` (_object_, nullable) Optional event-specific key-value data. Keys and structure vary by event type. Values may be strings, numbers, or booleans -- the iOS client coerces all values to strings internally. Common keys by event type: CARD\_INSERTED -> "terminalMessage"; ERROR -> "errorCode", "errorMessage"; AUTHORIZATION\_APPROVED -> "authCode"; CANCELLED -> "reason".
    
    _Example_
    
    ```
    {
      "terminalMessage": "Please insert card",
      "remainingRetries": 3
    }
    ```

<!-- document id=9a87ec3a4cfee82c647d6ecc8e1d8310ae3f8567dde6cd4c304041105813733f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payment-integration-container.md -->

# Payment Integration

The Commerce app payment architecture combines checkout APIs, the Payment Gateway, and an integrated payment package for B2B and B2C stores. Choose from a variety of Payment Gateway integration options and payment components. Commerce B2B payment integration does not yet support multiple payment methods or sale transactions.

Payment Integration for checkout is built on the foundation of the Commerce payment framework in Salesforce that is also used by other products in the Salesforce portfolio such as Revenue Cloud and Order Management. The Commerce payment framework allows you to author an Apex class that acts as an Payment Adapter between Salesforce and the payment gateway. Secure and PCI compliant, the framework handles the creation of payment specific records in the Salesforce system, logging calls to the gateway for auditing, and idempotency.

**note:** In the Winter ‘24 release, we introduced Commerce extensions for pricing, inventory, shipping, taxes, and other services. While the checkout integrations framework is still supported, we recommend extensions over integrations because they offer more targeted customizations for your B2B or B2C store. Plus, they’re available for more Commerce domains. See [Get Started With Salesforce Commerce Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extensions.html).

<!-- document id=c93aef9618a6ff14b1cfbaf8fa2446598ce351b9d355cd1b92bf798180d551de url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-psp.md -->

# Payment Service Provider

For the Payment Service Provider (PSP) integration to work properly in Customer Service Center, Shop API interactions require code to connect Customer Service Center with the B2C Commerce PSP cartridge. To add or update a payment method after each event in Customer Service Center, “dw.order.hooks.PaymentHooks” is called within an encapsulated transaction.

To register a payment hook, complete the following registration.

```json
{
  "hooks": [
    { "name": "dw.order.payment.authorize", "script": "./authorize.js" },
    { "name": "dw.order.payment.authorizeCreditCard", "script": "./authorize.js" }
  ]
}
```

## Example

To initiate the authorize logic in the PSP cartridge, include the code in `authorize.js`.

```javascript
importPackage(dw.system);
importPackage(dw.order);
importPackage(dw.value);
importPackage(dw.util);

function authorize(order: Order, paymentDetails: OrderPaymentInstrument) {
  //link your payment cartridge here...
  Logger.info("auth for order {0}", order.orderNo);
  var gcCode: String = paymentDetails.getGiftCertificateCode();
  Logger.info("GC Code {0}", paymentDetails.getGiftCertificateCode());

  if (gcCode == "bad") {
    return new Status(
      Status.ERROR,
      "ERR_BAD",
      "The Gift Certificate {0} could not authorized successfully.",
      gcCode,
    );
  }

  return new Status(Status.OK);
}

function authorizeCreditCard(order: Order, paymentDetails: OrderPaymentInstrument, cvn: String) {
  //link your payment cartridge here...
  var ccno: String = paymentDetails.getCreditCardNumber();
  Logger.info(
    "CC payment auth for order {0} - {1}",
    order.orderNo,
    "************" + ccno.substr(12),
  );

  if (ccno == "4111111111112222") {
    Logger.info(
      "=====================================ERROR===========================================",
    );
    return new Status(
      Status.ERROR,
      "ERR_2222",
      "Creditcard ending with {0} could not be authorized. Error code: {1}.",
      ccno.substr(12),
      "ERR_2222",
    );
  }

  return new Status(Status.OK);
}

module.exports = {
  authorize: authorize,
  authorizeCreditCard: authorizeCreditCard,
};
```

<!-- document id=5778fc75a1b0730bd03895c6c212a43fe83296af17ab7ee3c04b5a2a20d6a196 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-payments-reference-package.md -->

# Payments Reference Packages

A reference payments integration package supports both B2B Commerce implementations. You can use it as a template to create your own payments package.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Clone or download the package: [Payments Reference Integration Package](https://github.com/forcedotcom/commerce-on-lightning/tree/main/examples/b2c/checkout/payment-gateway-integration)

This guide describes how to set up development environments and provides step-by-step procedures for creating and deploying a payments package to your store.

<!-- document id=76834d2173cbc6e793338e574659051207902af6e226248f4fc2dd428e82a401 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-performance.md -->

# Performance Best Practices

Use optimization strategies to build fast storefronts. Follow performance best practices for web fonts, resource hints, bundle optimization, and third-party scripts.

**note:** This document is the entry point for performance topics. For in-depth documentation, see the topics listed next.

| Topic                                                                                                | Key Areas                                                                                               |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md)                                                              | Server-load everything, data classification, loaders, actions, fetchers, SCAPI request shape            |
| [Loading States](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md)                                                                 | Suspense boundary granularity, skeleton vs. spinner, visual feedback patterns                           |
| [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md)                                                       | URL state, context selector pattern, optimistic UI, avoiding derived state                              |
| [Images](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-images.md)                                                                           | DIS integration, `<DynamicImage>`, `DynamicImageProvider`, responsive sources, alt text                 |
| [Content Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-caching-content.md)                                                         | Static content, metadata, SCAPI response caching, HTML documents                                        |
| [Classify Non-Personalized Responses](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md#classify-non-personalized-responses) | Non-personalized response classification and cache-status verification                                  |
| [Monitor the Performance of Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-perf-tools.md)                                   | Use performance tools to monitor the performance of Storefront Next and create a performance benchmark. |

## Optimize Web Fonts

To achieve optimal performance during page load, use system fonts or minimize the size of web fonts and improve their discovery. Large web font files take longer to download and negatively affect [First Contentful Paint](https://web.dev/articles/fcp) (FCP). An incorrect `font-display` value can cause layout shifts that contribute to [Cumulative Layout Shift](https://web.dev/articles/cls) (CLS).

### Font Hosting

Self-host web fonts instead of loading them from third-party CDNs like Google Fonts. Self-hosting eliminates cross-origin DNS lookups and connection setup, avoids browser cache partitioning (browsers isolate third-party CDN caches per site), and is required for GDPR compliance because loading fonts from external CDNs transmits the visitor's IP address to that third party on every page load. A [2022 ruling by the Munich Regional Court](https://gdprhub.eu/index.php?title=LG_M%C3%BCnchen_-_3_O_17493/20) established this as a GDPR violation applicable across the EU. The alternative of gating external font loading behind a consent manager preserves CDN delivery but degrades the experience for users who haven't consented and adds implementation complexity. For details, see [Google Fonts and GDPR](https://www.cookieyes.com/documentation/google-fonts-and-gdpr/).

### Font Discovery

Browsers use `@font-face` to find fonts. Help the browser discover fonts earlier by inlining the `@font-face` declaration in the `<head>` and adding a `<link rel="preload">` directive. Without preload, the browser doesn't request the font until it computes a style that references it, adding a waterfall delay.

### Font Download

Use the WOFF2 format for its superior compression. Prefer variable fonts because a single file covers multiple weights, reducing the number of requests and preload hints. Subset fonts to include only necessary characters when the full Unicode range isn't needed.

### Font Rendering

The `font-display` CSS property controls how text is shown while a font loads. Use `swap` to immediately show a system fallback font and swap in the web font once loaded, avoiding Flash of Invisible Text (FOIT). Use `optional` to eliminate the swap-induced layout shift entirely. The web font is used only if it arrives before first render, otherwise the system font persists.

### System Fonts

Using system fonts avoids the font download entirely and eliminates render-blocking. For examples of system fonts, see [Fonts for Apple platforms](https://developer.apple.com/fonts/) and [Windows 11 font list](https://learn.microsoft.com/en-us/typography/fonts/windows_11_font_list).

For more detail, see [Optimize web fonts](https://web.dev/learn/performance/optimize-web-fonts) on web.dev.

## Resource Hints

Resource hints tell the browser to start DNS lookups, TCP connections, or resource downloads before they're needed, reducing latency when those resources are eventually requested.

The template renders resource hints in the `<head>` based on configuration values in `config.server.ts`, so they can be tuned per environment without code changes (`src/root.tsx`).

- `appConfig.links.preconnect`: Origins the browser should open early connections to (DNS + TCP + TLS). Use for services that will definitely be contacted on every page, such as the image CDN. The template preconnects to the DIS host by default.
- `appConfig.links.prefetchDns`: Origins for DNS-only prefetching. Lighter than `preconnect`, appropriate for services that may or may not be contacted (for example, analytics, optional third-party APIs).
- `appConfig.links.prefetch`: Specific resources to fetch and cache in the background. Use sparingly, as prefetched resources consume bandwidth regardless of whether the user navigates to them.

```bash
# Override via environment variables
PUBLIC__app__links__preconnect='["https://edge.dis.commercecloud.salesforce.com"]'
PUBLIC__app__links__prefetchDns='["https://analytics.example.com"]'
```

**warning:** Only `preconnect` to origins that are actually used on every page. Each preconnect opens a TCP and TLS connection eagerly, so unused preconnects waste the browser's connection budget and can delay more important requests. Performance audits, such as Lighthouse's "Avoid unnecessary preconnects", flag this. If an origin is only used on some pages (for example, a payment provider on checkout), prefer `dns-prefetch` instead. DNS lookups are cheaper and don't trigger warnings when unused.

## Bundle Optimization

Vite handles tree-shaking, minification, and chunk splitting automatically. Follow these practices help keep bundles small.

- Split your code. Vite automatically splits each route into its own chunk, so that users only download the JavaScript for the page they're visiting. For components that aren't needed on initial render, for example modals, drawers, rich editors, or heavy off-screen content, use [`React.lazy()`](https://react.dev/reference/react/lazy) with deferred mounting, split them into separate chunks that are loaded on demand. See [Lazy Loading for Overlays](#lazy-loading-for-overlays-modals-drawers-and-dialogs) for the pattern. For large route-specific component groups, use `manualChunks` in `vite.config.ts` to control how Rollup groups modules. The template uses this to split checkout components and per-locale translation files into dedicated chunks that are only loaded when needed.
- Analyze and monitor bundle size. Run `pnpm bundlesize:analyze` to generate an interactive visualization of client and server bundles (opens `build/client-bundle-size.html` and `build/ssr-bundle-size.html`). Run `pnpm bundlesize:test` to verify against configured size limits—CI enforces these checks on every PR.
- Avoid large dependencies for small tasks. Before adding a library, check its bundle size (for example, via [bundlephobia](https://bundlephobia.com)). A 50 KB utility library for a function you could write in 10 lines is not a good tradeoff.
- Compression is handled automatically. Managed Runtime applies Gzip/Brotli compression to responses at the edge—no application-level configuration is needed.

## React Rendering

Unnecessary re-renders inflate [Interaction to Next Paint](https://web.dev/articles/inp) (INP) and degrade responsiveness. Here are the most impactful optimizations.

- Split React Contexts by concern. One context per domain (theme, locale, and user). A single large context re-renders all consumers on every value change—even consumers that don't use the changed value. See [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md#context-selector-pattern).
- Memoize expensive computations. Use `useMemo` for derivations that are genuinely expensive. Don't memoize everything because the overhead of memoization exceeds the cost of cheap computations.
- Stabilize callback references. When passing callbacks to memoized child components, wrap them in `useCallback` to prevent the child from re-rendering on every parent render.
- Use `React.memo` selectively. Wrap components that re-render often with unchanged props. Don't apply it broadly because it adds comparison overhead and obscures the component tree.

### Lazy Loading for Overlays (Modals, Drawers, and Dialogs)

Overlay components that are hidden on initial render, such as modals, drawers, and dialogs, must use [`React.lazy()`](https://react.dev/reference/react/lazy) with deferred mounting. Mount the `<Suspense>` subtree only after the first user interaction, not on page load. This keeps the overlay's code out of the main chunk entirely until it's actually needed, reducing page load size and [Total Blocking Time](https://web.dev/articles/tbt) (TBT).

Conditionally render the components based on the overlay's `open` state so that the subtree unmounts when the overlay closes. Use `useDeferredUnmount(open)` to keep them mounted for a short window after close—long enough for the exit animation to play—then unmount. `React.lazy` memoizes the resolved chunk at module scope, so re-opening after unmount doesn't re-download the JavaScript. Only the closed overlay's in-memory state, and any resource fetchers it holds, is released.

```jsx
import { useDeferredUnmount } from "@/hooks/use-deferred-unmount";
const MyModal = lazy(() => import("@/components/my-modal").then((m) => ({ default: m.MyModal })));

function MyComponent() {
  const [open, setOpen] = useState(false);
  // Mounted while open, then unmounts shortly after close so the exit animation plays.
  const mounted = useDeferredUnmount(open);

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open</Button>
      {mounted && (
        <Suspense fallback={null}>
          <MyModal open={open} onOpenChange={setOpen} />
        </Suspense>
      )}
    </>
  );
}
```

- The first open triggers the lazy import and mounts the subtree. `React.lazy` caches the chunk so subsequent opens are instant without keeping the subtree alive.
- `open` controls whether the overlay should be visible. `mounted` becomes true immediately when opening, but stays true briefly after open becomes false—long enough for the exit animation to complete before unmounting.

**important:** **Anti-pattern:** When you import overlay components synchronously (non-lazy), they're bundled into the main chunk, increasing page load size and TBT.

**Anti-pattern:** Don't use a `loaded` flag that flips to true on first open and never resets, such as `const [loaded, setLoaded] = useState(false)` that gates `{loaded && <Suspense>…}`. This keeps the overlay mounted forever, causing its data fetchers, such as (`fetcher.load()`, `useScapiFetcher`), to rerun on every revalidation even after the user closes the overlay. Examples on when revalidations run are when currency, locale, or site change, or when a store is selected. Gate on open with `useDeferredUnmount` instead.

**Discouraged:** `<Suspense><LazyComponent /></Suspense>` without a guard—the chunk is separate but still fetched and parsed on mount, adding to TBT during page startup.

### Deferred Rendering with `useDeferredRender`

Mounting a `<Suspense>` boundary at the top of the component tree forces React to retain the entire fallback subtree in memory and process it during initial render, even if the user hasn't scrolled near that content. For large grids or heavy off-screen sections, this unconditional top-level mounting inflates [Total Blocking Time](https://web.dev/articles/tbt) (TBT) and competes for the main thread with [LCP](https://web.dev/articles/lcp) candidates in the initial viewport.

The `useDeferredRender` hook solves this main-thread contention by delaying the mount of a `<Suspense>` boundary until the browser reports an idle frame via [`requestIdleCallback`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestIdleCallback). During that idle window, the component renders a lightweight skeleton placeholder instead of a live `<Suspense>` tree.

**Three-Phase Rendering:**

| Phase                   | When                         | What renders                                                                         |
| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------ |
| **Pre-Idle**            | Immediately after page paint | Critical content and static skeleton placeholders. No `<Suspense>` boundary mounted. |
| **Post-Idle (Pending)** | After idle callback fires    | `<Suspense>` boundary mounts with skeleton fallback. Stream begins.                  |
| **Resolved**            | After Promise settles        | Full content replaces skeleton.                                                      |

```jsx
import { useDeferredRender } from "@/hooks/use-deferred-render";

function MySection({ criticalItems, nonCriticalPromise, placeholderCount }) {
  const shouldRender = useDeferredRender(placeholderCount > 0);

  return (
    <>
      {/* Critical, initial-viewport content always renders synchronously */}
      <ItemGrid items={criticalItems} />

      {/* Phase 1: no Suspense boundary — minimal render cost */}
      {!shouldRender ? (
        <SkeletonGrid count={placeholderCount} />
      ) : (
        /* Phase 2 & 3: Suspense boundary mounts after idle */
        <Suspense fallback={<SkeletonGrid count={placeholderCount} />}>
          <Await resolve={nonCriticalPromise}>{(items) => <ItemGrid items={items} />}</Await>
        </Suspense>
      )}
    </>
  );
}
```

### Client-Side Transform Anti-Patterns

A common source of unnecessary CPU work is data computation that runs on every render when it should happen once in the server loader. Identify and move these transforms before they compound across component trees.

**Anti-patterns to avoid:**

- Building lookup maps from arrays in the component body. Variation matrices, facet lookups, and category trees constructed via `reduce` or nested loops are the most common offender—the work scales with input size and repeats on every render, compounding across every tile in a grid.
- Nested passes over the same data. `items.filter(...).map(...).sort(...)` or `items.map(item => other.find(...))` are O(n²) when repeated per render over larger collections. Derive the shape you need once, and index once.
- Deep spreads and clones. `items.map(item => ({ ...item, children: item.children.map(c => ({ ...c })) }))` allocates a fresh object tree every render and breaks prop equality for every child downstream.
- Repeated string normalization. Slug construction, URL parsing, or locale formatting that doesn't depend on client-only state belongs in the loader.

```jsx
// ❌ BAD: lookup map rebuilt, and nested find/sort repeated on every render
function Grid({ items, categories }) {
  const byCategory = items.reduce((acc, item) => {
    (acc[item.categoryId] ??= []).push(item);
    return acc;
  }, {});
  const rows = categories
    .map((c) => ({ ...c, items: byCategory[c.id] ?? [] }))
    .sort((a, b) => a.label.localeCompare(b.label));
  return (
    <>
      {rows.map((row) => (
        <Row key={row.id} row={row} />
      ))}
    </>
  );
}

// ✅ GOOD: derive once in the loader; component just renders
export async function loader({ params }) {
  const [items, categories] = await Promise.all([fetchItems(params.id), fetchCategories()]);
  const rows = buildRows(items, categories); // group + sort once, server-side
  return { rows };
}

function Grid() {
  const { rows } = useLoaderData();
  return (
    <>
      {rows.map((row) => (
        <Row key={row.id} row={row} />
      ))}
    </>
  );
}
```

## Promotional Pricing on Product Listing Pages

When displaying promotional pricing on a product listing page (PLP) or search results page, you have two options: use `expand=promotions` on SCAPI search calls, or pre-compute promotional prices into a custom sortable attribute via a scheduled job. The right choice depends on whether you sort results by promotional price.

**Key point:** `expand=promotions` calculates promotional prices at response time, after search results have already been sorted and returned. It cannot be used to sort results by promotional price.

### Displaying Promotional Pricing with `expand=promotions`

To show promotional pricing information (promotional price, callout message, promotion ID) on your PLP alongside search results, use `expand=promotions`. It's straightforward and requires no additional setup, but it only enriches results — it doesn't influence their order.

On high-traffic PLPs, using `expand=promotions` adds per-request calculation overhead. If showing promotion details (such as callout messages) is the only requirement, this trade-off is generally acceptable.

### Sorting by Promotional Price with a Custom Attribute

To sort search results by promotional price on high-traffic PLPs, use a custom sortable attribute populated by a scheduled job. This approach pre-computes promotional prices ahead of time so the search engine can sort by them natively with no per-request cost.

### Combining Both Approaches

Combine both approaches if you sort by promotional price on a PLP and also want to show promotion details such as callout messages in the results. Use the custom sortable attribute to drive sort order, and `expand=promotions` to enrich the returned results with display data.

## Third-Party Scripts

Third-party scripts, such as analytics, tag managers, A/B testing, chat widgets, and consent banners, are a common source of performance degradation. Each script adds to [Total Blocking Time](https://web.dev/articles/tbt) (TBT) and can delay [Interaction to Next Paint](https://web.dev/articles/inp) (INP).

Keep these tips in mind for best performance results.

- Audit regularly. Every external script must justify its performance cost. Remove scripts that aren't actively used.
- Never load synchronously. Always use `async` or `defer`. A synchronous `<script>` blocks HTML parsing entirely.
- Lazy-load interaction-driven widgets. Chat widgets, social buttons, and similar components should load only when the user scrolls near them or clicks a placeholder—not on page load. See [Lazy Loading for Overlays](#lazy-loading-for-overlays-modals-drawers-and-dialogs) for the deferred mounting pattern.
- Use a Consent Management Platform (CMP). Integrate with a tag manager to prevent marketing and analytics tags from loading before user consent. This method satisfies privacy regulations and improves performance for users who haven't consented.
- Measure impact. Use the Chrome DevTools [Coverage tab](https://developer.chrome.com/docs/devtools/coverage) to identify unused JavaScript and CSS from third-party scripts.

<!-- document id=1bbb51bdafc24242d0df26ad98bf3b39826a8bff8844b31dfec41b94dec67e63 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/perf-tips.md -->

# Performance Best Practices for Writing PWA Kit-Based Storefronts

When designing your PWA kit app, take into account these performance best practices to make sure your storefront site provides an optimal user experience, loads quickly, and is responsive to user interactions.

## Optimize Data Retrieval

Efficient data fetching is vital for a rapid [LCP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals) and a responsive user experience.

- **For new projects (PWA Kit v3+):** Leverage [`withReactQuery`](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/pwa-kit-react-sdk/src/ssr/universal/components/with-react-query/index.js). This tool streamlines data fetching on both the server and client, cleverly preventing redundant client-side requests for already-retrieved server data. This means cleaner code and better performance.
- **For older projects (optimizing `getProps`):**
  - **Be selective:** Only return the precise data your component needs for its initial display. Avoid sending entire API responses to keep your HTML payload lean.
  - **Fetch in parallel:** If a page requires data from multiple APIs, use `Promise.all` to initiate these requests simultaneously, which is much faster than sequential fetching.
  - **Graceful error handling:** For critical issues (for example, product not found), throw an `HTTPError` to show a proper error page. For minor issues, pass an error flag via props for component-level handling, preventing crashes.
  - **Client-side non-essentials:** Any data not crucial for the initial, above-the-fold view (like reviews or related items) should be fetched on the client using a `useEffect` hook. This accelerates initial page load, boosting TTFB and LCP.
- **Server-side data fetching:** Fetch critical data during SSR to ensure the initial HTML contains all necessary content.
- **API caching:** Implement robust caching for API responses, both on the server and client-side (for example using stale-while-revalidate strategies).
- **Batching/debouncing:** Batch multiple small API requests into one where possible, or debounce rapid requests.
- **Small payload size from API calls or queries**: For APIs and queries, such as GraphQL queries, make sure sure you only get the data you need and the payload is as small as possible. For example, for B2C Commerce API (SCAPI), check out these tips in [Shopper API Performance and Best Practices](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html) to reduce the [response size](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html#response-size).

## Refine Your JavaScript and Components

Your client-side React code heavily influences [INP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals). Check out these tips to fine-tune it.

- **Analyze bundle size:** Use tools like [Webpack Bundle Analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) to identify large modules and dependencies.
- **Split your code.**
  - The PWA Kit is preconfigured for code splitting with Webpack. Use the **`loadable`** utility to dynamically load page-level components. For example, product detail page code only downloads when visited, reducing initial bundle size.
  - Implement dynamic imports (`React.lazy(`) and `Suspense`) to split your application into smaller chunks that are loaded on demand.
- **Lazy-load hidden content:** For substantial components located "below the fold" or within modals, implement lazy loading.
- **Eliminate redundant renders:** Unnecessary rerenders are a primary cause of poor INP. Master React's memoization hooks:
  - **`React.memo`**: Wrap components to prevent rerendering if their props haven't changed, ideal for simple display components.
  - **`useCallback`**: When passing functions to memoized child components, wrap them in`useCallback`. This maintains function reference stability, preventing needless child re-renders.
  - **`useMemo`**: Use `useMemo` for expensive computations, caching results to avoid recalculation on every render.
- **Smart state management:** While the Context API is useful, be cautious; any update to a context re-renders all components using it. For complex states, divide your contexts into smaller, logical units (e.g., `UserContext`, `CartContext`) to limit rerenders.
- **Tree shaking**: Ensure your build process (Webpack/Rollup) effectively removes unused code.
- **Minification and compression**: Minify JavaScript (JS) files. To further help with compression, the Managed Runtime CDN uses Gzip/Brotli compression for serving files if the browser supports it.
- **Reduce the JavaScript payload**: All JS scripts, including third-party scripts, use compression to reduce the size of the JS files. We recommend that the server use compression as well behind the CDN, or behind your own CMS or another system. We also recommend that third-party systems also use compression.

## Manage Client-Side Hydration

- **Progressive hydration:** Prioritize hydration of critical components first.
- **Optimize hydration:** Use the `<Island/>` component in PWA Kit 3.11 to control which components to hydrate on the client. By deferring hydration to only essential components, you benefit from server-rendering at scale without the overhead of hydrating the entire page at once. See the [Island component release notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html#pwa-kit---control-the-hydration-behavior-of-your-composable-storefront-and-boost-your-sites-performance) and the [Islands](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/template-retail-react-app/app/components/island) readme on GitHub.
- **Minimize initial interactive components:** Reduce the number of complex, interactive components loaded on the initial page view.

## Perform Caching with Managed Runtime

Maximizing your CDN cache hit ratio is the most effective way to enhance LCP for most users.

- **Set precise cache-control headers.**
  - **Per-page control:** Within a page's `getProps` function, define custom cache durations. A static "About Us" page might cache for days, while a product page could refresh every 15-30 minutes.
  - **`stale-while-revalidate` Magic:** This header (`Cache-Control: s-maxage=600, stale-while-revalidate=3600`) instructs the CDN to serve cached content for 10 minutes. If a request arrives afterward, it instantly delivers the older content, ensuring a fast user response, while fetching a fresh version in the background. It's the perfect balance of speed and content freshness.
- **Create cache-friendly components:** For server-rendered HTML to be cached broadly, it must be generic. Personalized content (like a user's name or cart quantity) must only render on the client. A simple method is to wrap it in a conditional check: `typeof window !== 'undefined' && <MyPersonalizedComponent />`, ensuring it renders solely in the browser.
- **Clean up query parameters:** Marketing URLs often contain "unnecessary" parameters (e.g., `gclid, utm_tags`) that create unique URLs, hindering caching effectiveness. Modify the `processRequest` function in `app/request-processor.js` to strip these parameters **before** the cache check, allowing many different URLs to access the same cached page.
- **Cache your APIs:** By default, proxied requests aren't CDN-cached. If you want a proxied request to be cached, simply change its path prefix from `proxy` to `caching`.

  **note:** Caching proxies isn't suitable for the B2C Commerce API; use its [SCAPI Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) feature instead.

- **Perform browser caching:** Leverage HTTP caching headers, for example, `Cache-Control`, and `Expires`, for static assets (JS, CSS, images).

## Manage Third-Party Scripts

Third-party scripts are notorious performance drains. Manage them effectively.

- **Audit and justify:** Inspect your Network panel in Chrome DevTools. List all external scripts. For each, ask: "Is this essential?" Eliminate any whose value doesn't outweigh their performance cost.
- **Load asynchronously:** Never load external scripts synchronously. Always use the `async` or `defer` attribute. `async` allows downloads without blocking the page, while `defer` ensures execution only after the page has fully parsed.
- **Lazy-load widgets:** For elements like chat widgets or social media buttons, avoid initial loading. Use JavaScript to load the script only when the user scrolls nearby or clicks a placeholder.
- **Utilize a Consent Management Platform (CMP):** A robust CMP integrated with Google Tag Manager (GTM) is crucial. It prevents marketing and ad tags from loading until user consent is given, benefiting both privacy and performance.
- **Check your service worker:** Your PWA's service worker might block requests to unapproved domains. When adding new external scripts, ensure their domains are correctly configured in your service worker to prevent blocking.
- **Analyze unused JavaScript and CSS**: Use Chrome development tools to find JavaScript code and CSS that's not being used. Removing unused code can improve page load performance and helps reduce mobile data usage for users. For more information, see [Coverage: Find unused JavaScript and CSS](https://developer.chrome.com/docs/devtools/coverage) in the Chrome documentation.

## Optimize Web Fonts

To achieve optimal performance during page load, use system fonts, or minimize the size of web fonts and improve their discovery. Large web font files can slow a page's performance during load time and rendering. Large web font files take longer to download in the browser and negatively affect First Contentful Paint (FCP). The incorrect font-display value could cause undesirable layout shifts that contribute to a page's Cumulative Layout Shift (CLS).

- Font Discovery: Browsers use @font-face to find fonts. You can help them discover fonts earlier with the preload directive or by inlining the @font-face declaration.
- System Fonts: Using system fonts improves the page performance by avoiding the need to download fonts and reducing render-blocking. For examples of system fonts, see [Fonts for Apple platforms](https://developer.apple.com/fonts/) and [Windows 11 font list](https://learn.microsoft.com/en-us/typography/fonts/windows_11_font_list).
- Font Download: If you use custom web fonts, it's recommended to self-host your web fonts. Use the WOFF2 format for its superior compression and subset fonts to reduce file size by including only the necessary characters.
- Font Rendering: The font-display CSS property controls how text is shown while a font loads. The swap value is often recommended because it immediately shows a fallback font and then swaps in the web font once it's loaded, which helps prevent a flash of unstyled text.

For more details, see [Optimize web fonts](https://web.dev/learn/performance/optimize-web-fonts) in web.dev.

## Craft Robust, Blazing-Fast Images

Images typically form the largest part of a page. Optimizing them is mandatory.

- **Use the Dynamic Imaging Service**: Use the [Dynamic Imaging Service](https://help.salesforce.com/s/articleView?id=cc.b2c_image_transformation_service.htm&type=5) for image optimization, resizing, and format conversion. Optimizing images with the Dynamic Imaging Service, together with using responsive image formats, is one of the main ways you can gain the largest performance boost for your web pages.
- **Serve responsive images:** Use the `<picture>` element or the `srcset` and `sizes` attributes on your `<img>` tags. This enables the browser to select the ideal image size for the device based on screen size and device pixel ratio, preventing phones from downloading massive desktop images.
- **Use the `<DynamicImage/>` Component**: Create responsive images with the `<DynamicImage/>` component, which enables responsive preloading for images. Also, the response image sizes on Product Listing Pages (PLPs) consider the impact of the search refinements panel, reducing unnecessary image fetches. See the [DynamicImage release notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html#pwa-kit---support-art-direction-and-responsive-preloading-in-dynamicimage-components).
- **Use Modern Formats:**

  - Prioritize modern image formats like the WebP format for images, which offers significantly better compression than JPEG or PNG, often reducing file size by 25-35% with no perceptible quality loss.

  **note:** Cloudflare only supports WebP. If using a third-party image provider, check for more modern options like AVIF.

  - Provide fallbacks for older browsers.

- **Compress aggressively:** Use an image optimization service or build tools to compress your images. A JPEG quality of 85 usually strikes a great balance.
- **Prevent layout shifts with dimensions:** This is a simple yet effective fix for CLS. Always include width and height attributes on your `<img>` and `<video>` tags. This allows the browser to reserve the correct space before the media loads, preventing annoying content jumps.
- **Lazy-load offscreen images:** For any image not within the initial view, add the native `loading="lazy"` attribute or Intersection Observer API. This instructs the browser to defer loading these images until the user scrolls into their vicinity, substantially enhancing performance. This tip applies to videos as well.

## See Also

- [Monitor the Performance of Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md)

<!-- document id=2433c87e7eae8c708f1cf248c01fbca276d308c44c3d09ecc1721ad0e6c32504 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/perf-guide.md -->

# Performance Guide for Composable Storefronts

This guide covers why it's important to consider the performance of a PWA kit-based ecommerce storefront during development and after it's deployed. It provides tips about how to develop a site that has optimal performance and how to measure the site's performance.

## Speed Matters! But Why?

Storefront performance has a direct impact on shopper conversion and revenue. Imagine the shopper experience on your ecommerce storefront. A shopper who wants to purchase a product browses a product listing page, which takes seconds to load. Then they refine their search to specific criteria, like size and price, but the filter causes additional delay for the page to load. Would this shopper continue browsing on your storefront, or will they lose patience and leave? A study from Cloudflare shows that if a page loading time increases from 2.4 seconds to over 4.2 seconds, the conversion rate drops by about 50%, from 1.9% to less than 1%. (1) Conversely, another study shows that a tiny 0.1-second improvement can elevate conversion rates by 8% and keep shoppers from abandoning their purchases. (2) Hence, every second counts, every click matters, and every user experience is a potential sale won or lost. Today's consumers expect seamless, app-like interactions. If you don't provide a smooth and fast shopping experience, customers will likely move on. It's essential that you make sure that your storefront website has fast performance to maximize sales!

![Graph shows the performance of an ecommerce site based on metrics](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-perf-graph.png '{"class": "image-lg"}')

Sources:

1. How website performance affects conversion rates. Cloudflare. https://www.cloudflare.com/learning/performance/more/website-performance-conversion-rates/
2. Milliseconds make Millions. A study on how improvements in mobile site speed positively affect a brand’s bottom line. Deloitte Digital. https://www.thinkwithgoogle.com/_qs/documents/9757/Milliseconds_Make_Millions_report_hQYAbZJ.pdf

## See Also

- [PWA Kit Architecture: How Your PWA Kit App Delivers a Page](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-pwa-arch.md)
- [Performance Best Practices for Writing PWA Kit-Based Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-tips.md)
- [Monitor the Performance of Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md)

<!-- document id=328af4c578291a0a9caf139b90762fb0fb77295ae09bf1091d0f2a55da6340ac url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/personalize-with-cookies.md -->

# Personalize with Cookies

In this tutorial you’ll learn how to use server-side cookies for personalization. For example, you can show different content depending on whether a shopper is new or returning such as a welcome offer banner to new shoppers and a promotional offer banner to returning shoppers.

We recommend testing the steps in a non-production environment before deploying your changes to production.

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

## Prerequisites

To complete this tutorial:

- Use PWA Kit version 3.1.0 or later.
- On your local machine, enable server-side cookies by completing either of these steps:

  - Set the environment variable `MRT_ALLOW_COOKIES=true`.

    or

  - Pass `localAllowCookies` to the options of `runtime.CreateHandler` in `ssr.js`.

- For your chosen environment, enable server-side cookies. New projects have Server-Side Cookie Access enabled by default, so this step may already be done. Existing projects have server-side cookies turned off by default, so you must enable them by using the Managed Runtime (MRT) API or Runtime Admin:
  - **MRT API:** Call the [projects_target_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) API endpoint and set `allow_cookies` to true.
  - [**Runtime Admin**](https://runtime.commercecloud.com/): Enable cookies in the [Environment Settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#edit-environment-settings).
- In `app/pages/home/index.jsx`, create your chosen content for new and returning shoppers. Or create other content that applies to different categories of shoppers.

## Show Different Content to New or Returning Shoppers

1. Add this JavaScript code to the homepage file in your project `app/pages/home/index.jsx`:

```jsx
import React, { useState, useEffect } from 'react';
import Cookies from 'js-cookie'

const Home = () => {
    const [isNewShopper, setIsNewShopper] = useState();

    useEffect(() => {

        // Find out if the site visitor is a new shopper by checking for the isNewShopper cookie.
        const isNewShopperCookie = Cookies.get('isNewShopper');

        // If the cookie isn't found, set it on the server and treat the site visitor as a new shopper.
        setIsNewShopper(isNewShopperCookie != null ? isNewShopperCookie === 'true' : true);
    }, []);

    return (
        {isNewShopper ? (

        // Show this message to a new shopper.
            <h1>Welcome! We're glad you're here.</h1>
        ) : (

        // Show this message to a returning shopper.
            <h1>Welcome back!</h1>
        )}

        // ... Code for the rest of your homepage
    )
}
```

2. [Deploy your bundle](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html).

## Cookies and Caching

Cookies aren't part of the Managed Runtime CDN cache key, so the same cached response is served to all shoppers regardless of cookie value. Because Managed Runtime doesn't strip the `Set-Cookie` header from cacheable origin responses, a cacheable server-side rendered (SSR) response that sets a per-user cookie can be cached and replayed to other shoppers. When that happens, multiple shoppers share one cookie value, which can lead to incorrect personalization or unexpected behavior for shoppers who receive the shared cookie.

To avoid this problem, prevent any response that sets a per-user cookie from being cached with that cookie:

- Set `Cache-Control: private` or `Cache-Control: no-store` on the response. The CDN doesn't cache the response, but the browser still keeps it.
- Set `Cache-Control: no-cache="Set-Cookie"`. The CDN caches the response but excludes the `Set-Cookie` header from the cached copy.

Marking responses as `private` or `no-store` reduces your cache hit ratio, so scope these directives to the responses that actually set per-user cookies. For more information about cache lifetimes, see [Maximizing Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.html).

## Best Practices

- Thoroughly test cookie functionality across different browsers and devices.
- Always obtain shopper consent before storing any personal information in server-side cookies.
- Ensure that your approach to personalization complies with relevant data privacy regulations such as General Data Protection Regulation (GDPR) or California Consumer Privacy Act (CCPA).
- Carefully evaluate the impact of personalization on different shopper segments to avoid unintended consequences.
- Set appropriate security attributes for your cookie, such as the HttpOnly flag to prevent client-side JavaScript access and the Secure flag for HTTPS connections.
- Set a reasonable expiration time for the cookie based on your needs. For `isNewShopper`, a long expiry time is suitable. For example, a year.

## Troubleshoot Common Errors

This section provides suggested solutions for common errors that you might encounter while using server-side cookies.

### Unexpected Results

You didn’t get the expected site behavior after you deployed code that involves server-side cookies.

**Cause:** You didn’t enable server-side cookies.

**Suggested Solution:** Enable server-side cookies as described in the [Prerequisites](#prerequisites).

### Cookie Expiration or Deletion

There are disruptions in user sessions or preferences.

**Cause:** Cookies expired or were deleted prematurely.

**Suggested Solution:**

- Review your cookies’ expiration settings and adjust them as needed to align with your desired session or persistence requirements.
- Implement mechanisms to detect and handle expired or deleted cookies gracefully, such as re-authenticating shoppers or prompting them to re-establish their preferences.
- Monitor shopper feedback and behavior to identify any patterns or issues related to cookie expiration or deletion and address them proactively.

### Inconsistent Cookie Behavior Across Pages

Sometimes cookies behave differently across different pages or components of your site, leading to inconsistencies in shopper experience.

**Cause:** Inconsistent or decentralized cookie-related logic.

**Suggested Solution:**

- Ensure that cookie-related logic, including setting and reading cookies, is applied consistently across all relevant pages and components.
- Review the flow of your application to identify any discrepancies or inconsistencies in how cookies are handled.
- Consider centralizing cookie-related logic or using a dedicated library or middleware for managing cookies to ensure uniform behavior.

## See Also

- [Conditional Rendering](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.html#conditional-rendering)
- [Personalize with Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/personalize-with-shopper-context.md)
- [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html)
- [Storefront Preview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html)
- [Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/active-data.html)

<!-- document id=84dd8bc1ade032aae8442d0236c81f837d9415fb70c12e5a61b8112826e7682e url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/personalize-with-shopper-context.md -->

# Personalize with Shopper Context

With Shopper Context, you can personalize shopping experiences by tailoring your promotions, pricing, product recommendations, and content delivered to your site based on shopper behavior. For example, if shoppers visit your site from a mobile device, offer them a 10% discount.

The hook named `useUpdateShopperContext` is used to set the Shopper Context in a [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) site. The default implementation of Shopper Context in PWA Kit is a demonstration of personalization capabilities. In the [demo implementation](#demo-implementation-of-shopper-context) described in this guide, we use query parameters to activate a personalization scheme that changes product listing page (PLP) content and promotions. Extend our implementation with custom code to match your own personalization strategy.

This guide explains our demo implementation of Shopper Context and how to configure and extend it to power the personalization strategy for your PWA Kit site. The functionality described in this guide isn’t supported in a [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md).

We recommend testing personalization in a non-production environment before deploying your changes to production. You can also preview your personalization using [Storefront Preview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md).

Before running the commands in this guide, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

## Sample Usage

This video shows an example of how to personalize content and promotions with the demo implementation of Shopper Context.

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/tRLVE69bmVyFsNAWv4LSfo" title="Shopper Context in PWA Kit" type="vidyard"}

## Prerequisites

To use personalization with Shopper Context:

- Build your site with:
  - The [Retail React App template](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/README.md)
  - Retail React App version 5.0.0 or later
- Have the Account Manager role of Business Manager Administrator. If you don’t have this role, ask your Account Manager Administrator to assign it to you. See [Managing Account Manager for Salesforce B2C Commerce Users](https://help.salesforce.com/s/articleView?id=000391212&type=1).
- If you haven’t done so already, set up [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).
- Set up your site based on the types of personalization that you want to use. For example, set up [customer groups](https://help.salesforce.com/s/articleView?id=cc.b2c_using_dynamic_customer_groups_for_active_merchandising.htm&type=5) in Business Manager to apply rules for personalized pricing, products, or promotions.

## Configure Shopper Context

### 1. Create a SLAS Private Client

- In the Shopper Login and API Access (SLAS) Admin UI, create a SLAS private client. See [Create a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client).

### 2. Enable Shopper Context and Hooks

In Business Manager:

- Enable Shopper Context. See [Set and Retrieve Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html#set-and-retrieve-shopper-context).
- Complete these [Hooks Prerequisites](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html?_ga=2.255637128.1234409611.1725201953-590114715.1724343723#hooks-prerequisites).

### 3. Upload the shopper_context_hooks Cartridge

The `shopper_context_hooks` cartridge acts as an allowlist to ensure that only the context you want to use for personalization campaigns can be set from the client. In Business Manager:

- Add `shopper_context_hooks` to your site’s cartridge path. This step ensures site security by preventing unauthorized members of your site development team from setting all Shopper Context scopes.
  - Go to **Administration > Sites > Manage Sites**.
  - Select the site where you want to use this cartridge. Example site identifier: `RefArch`.
  - Click the **Settings** tab.
  - In the Cartridges field, add the new cartridge path `shopper_context_hooks`. Add the new cartridge path before the path for `app_storefront_base`.
    For example: `shopper_context_hooks:app_storefront_base`
- Install and upload the cartridge.

  - Clone the [Shopper Context hooks repository](https://github.com/SalesforceCommerceCloud/shopper_context_hooks). The name of the top-level directory is `shopper_context_hooks`.
  - To install package dependencies, from the `shopper_context_hooks` directory, run:

    `npm install`

  - Configure client IDs by updating `CLIENT_REGISTRY` in `cartridges/shopper_context_hooks/cartridge/scripts/config/clientRegistry.js`
  - Create a `dw.json` file in the `shopper_context_hooks` directory. Replace the `$` strings in this example with actual values or set the corresponding environment variables.

  ```jsx
  {
    "hostname": "$HOST.demandware.net",
    "username": "$USERNAME",
    "password": "$PASSWORD",
    "code-version": "$VERSION"
  }
  ```

  - From the `shopper_context_hooks` directory, run:

    `npm run uploadCartridge`

For more information about uploading the cartridge, see [Upload Code for Storefront Reference Architecture (SFRA)](https://developer.salesforce.com/docs/commerce/sfra/guide/b2c-build-sfra.html#upload-code-for-sfra).

### 4. Configure Custom Site Preferences

Configure the client registry by adding a custom site preference. To do so, import the `system-objecttype-extensions.xml` in Business Manager.

- Go to **Administration** > **Site Development** > **Import & Export**.
- Under **Import & Export Files**, click **Upload**.
- Click **Choose File**.
- Go to `meta/meta`.
- Select `system-objecttype-extensions.xml`.
- Click **Upload**.
- After the file is uploaded, click **Back**.
- Under **Meta Data**, click **Import**.
- Select `system-objecttype-extensions.xml` and click **Next**.
- After the file is validated, click **Import**.

### 5. Update the shopper_context_hooks Cartridge CLIENT_REGISTRY from Site Preferences

To update your configuration, in Business Manager:

- Go to **Merchant Tools** > **Site Preferences** > **Custom Preferences** > **Shopper Context Hooks Preferences**.
- Update the Client Registry field with a JSON configuration. Enter your client ID that you set up in step 1 and the Shopper Context keys that the client can set. You can enter any of the keys available in the [ShopperContext type](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=type%3AShopperContext). For client IDs that require permissions to set all Shopper Context keys, such as the [client ID used for Storefront Preview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html), use the key `all`.

In this example, we set Shopper Context keys for two different client IDs.

- Requests from client ID `aaaaaaaa-8536-4a39-acbb-8e7f1759f901` can set only the 3 specified keys in Shopper Context.
- Requests from client ID `bbbbbbbb-b5e9-efbc-42f6-584f60fd54ff` can set all keys in Shopper Context.

```json
{
  "aaaaaaaa-8536-4a39-acbb-8e7f1759f901": ["sourceCode", "geoLocation", "deviceType"],
  "bbbbbbbb-b5e9-efbc-42f6-584f60fd54ff": ["all"]
}
```

### 6. Add the Shopper Context Scope

- Add this Shopper Context scope to the SLAS Private Client: `sfcc.shopper-context.rw`. See [Create a SLAS Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html#create-a-slas-client).

## Demo Implementation of Shopper Context

Our demo of Shopper Context uses the `sourceCode` set through a query parameter to trigger content changes on a PLP and new promotions for a specific customer group. You can see the demo in action on a PLP by adding `&sourcecode=instagram` to the URL.

In our demo we utilize the `useUpdateShopperContext` hook to trigger a personalization campaign. In your project, add or remove Shopper Context query parameters in the `SHOPPER_CONTEXT_SEARCH_PARAMS` constant in `app/constants.js` to achieve your own personalizations triggered by query parameters.

For example, if you added [custom attributes](https://help.salesforce.com/s/articleView?id=cc.b2c_using_session_custom_attributes.htm&type=5) that you want to be set using query parameters, include them as custom query parameters in `app/constants.js`. In this example, we add these parameters: `deviceType` and `storeId`.

```jsx
export const SHOPPER_CONTEXT_SEARCH_PARAMS = {
   // These are the default query parameters.
    sourceCode: {paramName: 'sourceCode'},
    geoLocation: {
        city: {paramName: 'city'},
        country: {paramName: 'country'},
        countryCode: {paramName: 'countryCode'},
        latitude: {paramName: 'latitude', type: SHOPPER_CONTEXT_FIELD_TYPES.DOUBLE},
        longitude: {paramName: 'longitude', type: SHOPPER_CONTEXT_FIELD_TYPES.DOUBLE},
        metroCode: {paramName: 'metroCode'},
        postalCode: {paramName: 'postalCode'},
        region: {paramName: 'region'},
        regionCode: {paramName: 'regionCode'}
    },
    // These are examples of custom query parameters that you can optionally add.
    customQualifiers: {
        deviceType: {paramName: 'deviceType'}
    },
    assignmentQualifiers: {
        storeId: {paramName: 'storeId'}
    }
}, // More code here...
```

## Extend Shopper Context

Optionally, you can add personalization beyond what's in the [Demo Implementation of Shopper Context](#demo-implementation-of-shopper-context). For example, you can personalize content based on a shopper’s geolocation.

In this sample code, we get a shopper's geolocation. After you get the geolocation, you can apply your chosen personalization. For example:

- For New York, USA: 20% discount on women's tops.
- For Boston, USA: 15% discount on women's tops.

```jsx
// ... Default imports in the hook
import {useEffect, useState} from 'react'

export const useUpdateShopperContext = () => {
    // ... Default code in the hook
    const [location, setLocation] = useState({latitude: null, longitude: null})

     // Get the latitude and longitude of the shopper's geolocation using the browser's navigator.geolocation API.
    const fetchLocation = () => {
        if (typeof navigator !== 'undefined' && navigator.geolocation) {
            navigator.geolocation.getCurrentPosition(
                (position) => {
                    setLocation({
                        latitude: position.coords.latitude,
                        longitude: position.coords.longitude
                    })
                },
                (err) => {
                    console.error(err.message) // Handle errors gracefully
                },
                {
                    enableHighAccuracy: true, // Try to get the most accurate location
                    timeout: 10000, // Time in milliseconds before timing out
                    maximumAge: 60000 // Cache the location for 1 minute
                }
            )
        } else {
            console.error('Geolocation is not supported by this browser.')
        }
    }

    fetchLocation()

    // Update the Shopper Context when the latitude and/or longitude changes.
    useEffect(() => {
        if (location.latitude && location.longitude) {
            const newShopperContext = {
                geoLocation: {
                    latitude: location.latitude,
                    longitude: location.longitude
                }
            }
            handleShopperContextUpdate(shopperContext, newShopperContext)
        }
    }, [location.latitude, location.longitude])
}
```

## Troubleshoot Shopper Context

This section provides a suggested solution for a common error that you can encounter while using Shopper Context.

### Incorrect or Missing Personalization

**Potential Cause:** Personalization in Business Manager isn’t configured correctly.

**Suggested Solution:** Ensure that the context trigger you set is assigned to a personalization campaign in Business Manager.

## See Also

- [Shopper Context API Documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html)
- [Personalize with Cookies](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/personalize-with-cookies.html)
- [Conditional Rendering](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.html#conditional-rendering)
- [Integrate Page Designer with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.md)

<!-- document id=287adce8531b5a109953701d2f283523fbe228e779f909d7842c9e13afc353f0 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-api-personalized.md -->

# Personalized Promotions, Shipping, and Payment Methods

Use the Shopper Context API with other B2C Commerce APIs, such as Basket, Shipping, Payment, and Product, to set up personalized and customized promotions.

## Example: Personalize Products for Device Type

Consider a scenario where you want to personalize the products page based on a shopper’s device type by displaying certain products for shoppers whose device type is mobile.

1. Follow the instructions in [Set and Retrieve Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md#set-and-retrieve-shopper-context).
2. The response of GET products has a new property, “Product Promotion”, which lists all the promotions associated with the product and matching the shopper context criteria, for example: the response might have a discounted price based on the shopper context.

- The merchant can set the effective date in Shopper Context to trigger special price books.
- The merchant can have a dynamic session-based customer group (for example, deviceType = mobile), which can trigger a promotion, such as a 10% discount.

```bash
#!/bin/bash
# Shopper Context Custom Qualifers: https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-context:Summary
set -euo pipefail

SHORTCODE='kv7kzm78'
ORG='f_ecom_zzrf_006'
SLAS_CLIENT_ID='d4f49c7a-b037-4561-91d9-5c7d547e71b5'
SLAS_CLIENT_SECRET=$SLAS_CLIENT_SECRET
SITE='RefArchGlobal'

# 1. Get Guest Token & USID
BASE="https://$SHORTCODE.api.commercecloud.salesforce.com"
RESPONSE=$(curl "$BASE/shopper/auth/v1/organizations/$ORG/oauth2/token" \
    -su "$SLAS_CLIENT_ID:$SLAS_CLIENT_SECRET" \
    -d 'grant_type=client_credentials')

TOKEN=$(echo $RESPONSE | jq -r '.access_token')
USID=$(echo $RESPONSE | jq -r '.usid')

# 2. Set Shopper Context
curl "$BASE/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID" \
    -sX 'PUT' \
    -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{
        "customQualifiers": {
            "deviceType": "mobile"
        }
    }'

# 3. Get a Product with a Promotion
curl "$BASE/product/shopper-products/v1/organizations/$ORG/products/25493613M?siteId=$SITE" \
    -sH "Authorization: Bearer $TOKEN" \
    | jq -r '.productPromotions'
```

## Example: Personalized Shipping and Payment Method

Consider a scenario where you want to personalize your products page based on a shopper’s device type, for example: for shoppers using a mobile device, create a promotion that provides 10% off with free shipping and the option to pay using Google pay:

![Visualization showing personalized shopper context data and targeting](https://developer.salesforce.com/docs/media/commerce-api/shopper-context-personalized.png)

1. Follow the instructions in [Set and Retrieve Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md#set-and-retrieve-shopper-context).
2. Create Session-based Customer Groups:

- The Shopper Context API works with session-based customer groups.
- Create a session-based customer group and make sure the attribute used in the customer group matches the shopper context qualifier.

![Diagram showing shopper context session data management and synchronization](https://developer.salesforce.com/docs/media/commerce-api/shopper-context-session.png)

**note:** The custom attribute set in the dynamic customer group in Business Manager and the custom qualifier set in the API must match. As a best practice, use only those qualifiers that exist in dynamic session-based customer groups and assignments. In this example, `deviceType` is the attribute used in customer group and shopper context. This Shopper Context data is then used to retrieve customer groups to which a particular shopper belongs, and activates any experiences that are mapped to a particular customer group.

3. Set Shopper Context Parameters

To set the context, use `PUT` `https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/{organizationId}/shopper-context/{usid}`

```json
{
  "customQualifiers": {
    "deviceType": "mobile",
    "countryCode": "EU"
  }
}
```

## See Also

- [createShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=createShopperContext)
- [Shopper Login (SLAS)](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=Summary)
- [Assign a Price Book or Promotion to a Specific Store in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_assigning_a_pricebook_or_promotion_specific.htm&type=5) in _Salesforce Help_

<!-- document id=5ef2c4a169d64991854c02de96051e40c6001bb7ef8d27919aa4942345f0b2d6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jobs/b2c-pipelet-to-script-conversion.md -->

# Pipelet to Script Method or Job Step Conversion

Some pipelets have a script method or job step equivalent. We recommend using the script method or job step instead of the pipelet. Any pipelet can be called directly from a controller.

## Pipelets a-Z

| Pipelet                          | Group                    | Script Method or Job Step                                                                                                                                                                        |
| -------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ABCTest                          | Analytics                | This can be replaced with plain JavaScript                                                                                                                                                       |
| AcceptForm                       | Forms                    | dw.web.FormGroup.accept                                                                                                                                                                          |
| AddBonusProductToBasket          | Basket                   | dw.order.LineItemCtnr.createBonusProductLineItem                                                                                                                                                 |
| AddCouponToBasket                | Basket                   | dw.order.LineItemCtnr.createCouponLineItem                                                                                                                                                       |
| AddCouponToBasket2               | Basket                   | dw.order.LineItemCtnr.createCouponLineItem                                                                                                                                                       |
| AddGiftCertificateToBasket       | Basket                   | dw.order.LineItemCtnr.createGiftCertificateLineItem, and also use setReceipientName, setSenderName, setMessage, and in some cases setProductList item to add the gift certificate to the basket. |
| AddGiftCertificateToProductList  | ProductList              | dw.customer.ProductList.createGiftCertificateItem                                                                                                                                                |
| AddPaymentInstrumentToBasket     | Basket                   | dw.order.LineItemCtnr.createPaymentInstrument                                                                                                                                                    |
| AddProductToBasket               | Basket                   | dw.order.LineItemCtnr.createProductLineItem and setQuantityValue                                                                                                                                 |
| AddProductToProductList          | ProductList              | dw.customer.ProductList.createProductItem                                                                                                                                                        |
| Assign                           | Common                   | This is replaced by assignment of variables in JavaScript                                                                                                                                        |
| CancelOrder                      | Order                    | dw.order.OrderMgr.cancelOrder                                                                                                                                                                    |
| ClearFormElement                 | Forms                    | dw.web.FormElement.clearFormElement                                                                                                                                                              |
| CreateBasketForOrderEdit         | Basket                   | dw.order.BasketMgr.createBasketFromOrder                                                                                                                                                         |
| CreateBasketPaymentInstrument    | Basket (deprecated)      | dw.order.LineItemCtnr.createPaymentInstrument                                                                                                                                                    |
| CreateBillingAddress             | Basket                   | dw.order.LineItemCtnr.createBillingAddress                                                                                                                                                       |
| CreateCustomer                   | Customer                 | dw.customer.CustomerMgr.createCustomer                                                                                                                                                           |
| CreateCustomerAddress            | Customer                 | dw.customer.AddressBook.createAddress                                                                                                                                                            |
| CreateCustomerPaymentInstrument  | Customer                 | dw.customer.Wallet.createPaymentInstrument                                                                                                                                                       |
| CreateCustomerProfile            | Customer (deprecated)    | (deprecated)                                                                                                                                                                                     |
| CreateCustomObject               | CustomObject             | dw.object.CustomObjectMgr.createCustomObject                                                                                                                                                     |
| CreateGiftCertificate            | Order                    | dw.order.GiftCertificateMgr.createGiftCertificate, setRecipientEmail, setRecipientName, setSenderName, setMessage, and setOrderNo.                                                               |
| CreateOrder                      | Order                    | dw.order.OrderMgr.createOrder, dw.order.OrderMgr.placeOrder                                                                                                                                      |
| CreateOrder2                     | Order                    | dw.order.OrderMgr.createOrder                                                                                                                                                                    |
| CreateOrderNo                    | Order                    | dw.order.OrderMgr.createOrderNo                                                                                                                                                                  |
| CreatePaymentTransaction         | Basket (deprecated)      | (deprecated)                                                                                                                                                                                     |
| CreateProductList                | ProductList              | dw.customer.ProductListMgr.createProductList                                                                                                                                                     |
| CreateProductListRegistrant      | ProductList              | dw.customer.ProductList.createRegistration, createCoRegistrant                                                                                                                                   |
| CreateShipment                   | Basket                   | dw.order.LineItemCtnr.createShipment                                                                                                                                                             |
| CreateShippingAddress            | Basket                   | dw.order.Shipping.createShippingAddress                                                                                                                                                          |
| CreateShippingOrders             | Order Center             | (job)                                                                                                                                                                                            |
| Eval                             | Common                   | This can be replaced with plain JavaScript                                                                                                                                                       |
| ExportABTests                    | ImpEx                    | Job step ExportABTests                                                                                                                                                                           |
| ExportCatalog                    | ImpEx                    | Job step ExportCatalog                                                                                                                                                                           |
| ExportContent                    | ImpEx                    | Job step ExportContent                                                                                                                                                                           |
| ExportCouponCodes                | ImpEx                    | Job step ExportCouponCodes                                                                                                                                                                       |
| ExportCoupons                    | ImpEx                    | Job step ExportCoupons                                                                                                                                                                           |
| ExportCustomerGroups             | ImpEx                    | Job step ExportCustomerGroups                                                                                                                                                                    |
| ExportCustomerList               | ImpEx                    | Job step ExportCustomerList                                                                                                                                                                      |
| ExportCustomers                  | ImpEx                    | Job step ExportCustomers                                                                                                                                                                         |
| ExportCustomObjects              | ImpEx                    | Job step ExportCustomObjects                                                                                                                                                                     |
| ExportGiftCertificates           | ImpEx                    | Job step ExportGiftCertificates                                                                                                                                                                  |
| ExportInventoryLists             | ImpEx                    | Job step ExportInventoryLists                                                                                                                                                                    |
| ExportMetaData                   | ImpEx                    | Job step ExportMetaData                                                                                                                                                                          |
| ExportOrders                     | ImpEx                    | Job step ExportOrders                                                                                                                                                                            |
| ExportPriceBooks                 | ImpEx                    | Job step ExportPriceBook                                                                                                                                                                         |
| ExportProductLists               | ImpEx                    | Job step ExportProductLists                                                                                                                                                                      |
| ExportPromotions                 | ImpEx                    | Job step ExportPromotions                                                                                                                                                                        |
| ExportShippingMethods            | ImpEx                    | Job step ExportShippingMethods                                                                                                                                                                   |
| ExportSlots                      | ImpEx                    | Job step ExportContentSlots                                                                                                                                                                      |
| ExportSourceCodes                | ImpEx                    | Job step ExportSourceCodeGroups                                                                                                                                                                  |
| ExportStores                     | ImpEx                    | Job step ExportStores                                                                                                                                                                            |
| ExportTaxTable                   | ImpEx                    | Job step ExportTaxTable                                                                                                                                                                          |
| ExportToOrderCenter              | Order                    | (deprecated)                                                                                                                                                                                     |
| FailOrder                        | Order                    | dw.order.OrderMgr.failOrder                                                                                                                                                                      |
| FinalizeOAuthLogin               | Customer                 | dw.customer.oauth.OAuthLoginFlowMgr.finalizeOAuthLogin                                                                                                                                           |
| GenerateResetPasswordToken       | Customer                 | dw.customer.Credentials.createResetPasswordToken                                                                                                                                                 |
| GetBasket                        | Basket                   | dw.order.BasketMgr.getBasket or dw.order.BasketMgr.getCurrentBasket()                                                                                                                            |
| GetBrands                        | Catalog                  | search for attribute brand using dw.catalog.ProductSearchModel                                                                                                                                   |
| GetCategory                      | Catalog                  | dw.catalog.CatalogMgr.getCategory                                                                                                                                                                |
| GetContent                       | Content                  | dw.content.ContentMgr.getContent                                                                                                                                                                 |
| GetCustomer                      | Customer                 | dw.customer.CustomerMgr.getCustomerByLogin                                                                                                                                                       |
| GetCustomerAddress               | Customer                 | customer.addressBook.getAddress(addressID)                                                                                                                                                       |
| GetCustomerPaymentInstruments    | Customer                 | dw.customer.Wallet.getPaymentInstruments                                                                                                                                                         |
| GetCustomerProfile               | Customer (deprecated)    | (deprecated)                                                                                                                                                                                     |
| GetGiftCertificate               | Order                    | dw.order.GiftCertificateMgr.getGiftCertificate                                                                                                                                                   |
| GetLastVisitedProducts           | Catalog                  | session.clickStream...                                                                                                                                                                           |
| GetNearestStores                 | Store                    | dw.catalog.StoreMgr.searchStoresBy\*                                                                                                                                                             |
| GetOrder                         | Order                    | dw.order.OrderMgr.getOrder                                                                                                                                                                       |
| GetPaymentProcessor              | Payment                  | dw.order.PaymentMethod.getPaymentProcessor                                                                                                                                                       |
| GetProduct                       | Catalog                  | dw.customer.ProductListMgr.getProduct and dw.catalog.Product.isOnline (isOnline is used for products being previewed on the storefront)                                                          |
| GetProductList                   | ProductList              | dw.customer.ProductListMgr.getProductList                                                                                                                                                        |
| GetProductLists                  | ProductList              | dw.customer.ProductListMgr.getProductLists                                                                                                                                                       |
| GetReplicationStatus             | Replication (deprecated) | (deprecated)                                                                                                                                                                                     |
| GetSearchSuggestions             | Search                   | dw.suggest.SuggestModel                                                                                                                                                                          |
| ImportABTests                    | ImpEx                    | Job step ImportABTests                                                                                                                                                                           |
| ImportActiveData                 | ImpEx                    | Job step ImportActiveData                                                                                                                                                                        |
| ImportCampaigns                  | ImpEx (deprecated)       | (deprecated)                                                                                                                                                                                     |
| ImportCatalog                    | ImpEx                    | Job step ImportCatalog                                                                                                                                                                           |
| ImportContent                    | ImpEx                    | Job step ImportContent                                                                                                                                                                           |
| ImportCoupons                    | ImpEx                    | Job step ImportCoupons                                                                                                                                                                           |
| ImportCustomerGroups             | ImpEx                    | Job step ImportCustomerGroups                                                                                                                                                                    |
| ImportCustomerList               | ImpEx                    | Job step ImportCustomerList                                                                                                                                                                      |
| ImportCustomers                  | ImpEx                    | Job step ImportCustomers                                                                                                                                                                         |
| ImportCustomObjects              | ImpEx                    | Job step ImportCustomObjects                                                                                                                                                                     |
| ImportGiftCertificates           | ImpEx                    | Job step ImportGiftCertificates                                                                                                                                                                  |
| ImportInventoryLists             | ImpEx                    | Job step ImportInventoryLists                                                                                                                                                                    |
| ImportKeyValueMapping            | ImpEx                    | ImportKeyValueMapping                                                                                                                                                                            |
| ImportPriceBooks                 | ImpEx                    | Job step ImportPriceBook                                                                                                                                                                         |
| ImportProductLists               | ImpEx                    | Job step ImportProductlists                                                                                                                                                                      |
| ImportPromotions                 | ImpEx                    | Job step ImportPromotions                                                                                                                                                                        |
| ImportShippingMethods            | ImpEx                    | Job step ImportShippingMethods                                                                                                                                                                   |
| ImportSlots                      | ImpEx                    | Job step ImportContentSlots                                                                                                                                                                      |
| ImportSourceCodes                | ImpEx                    | Job step ImportSourceCodeGroups                                                                                                                                                                  |
| ImportStores                     | ImpEx                    | Job step ImportStores                                                                                                                                                                            |
| ImportTaxTable                   | ImpEx                    | Job step ImportTaxTable                                                                                                                                                                          |
| InitiateOAuthLogin               | Customer                 | dw.customer.oauth.OAuthLoginFlowMgr                                                                                                                                                              |
| InvalidateFormElement            | Forms                    | dw.web.FormElement.invalidateFormElement                                                                                                                                                         |
| InvalidateWebCache               | Util                     | Job step InvalidateCache                                                                                                                                                                         |
| LoginAgentUser                   | Customer                 | dw.customer.AgentUserMgr.loginAgentUser                                                                                                                                                          |
| LoginCustomer                    | Customer                 | dw.customer.CustomerMgr.loginCustomer                                                                                                                                                            |
| LoginOnBehalfCustomer            | Customer                 | dw.customer.AgentUserMgr.loginOnBehalfCustomer                                                                                                                                                   |
| LogoutAgentUser                  | Customer                 | dw.customer.AgentUserMgr.logoutAgentUser                                                                                                                                                         |
| LogoutCustomer                   | Customer                 | dw.customer.CustomerMgr.logoutCustomer                                                                                                                                                           |
| Paging                           | Common                   | dw.web.PagingModel.\*                                                                                                                                                                            |
| PlaceOrder                       | Order                    | dw.order.OrderMgr.placeOrder                                                                                                                                                                     |
| RedeemGiftCertificate            | Order                    | dw.order.GiftCertificateMgr.redeemGiftCertificate                                                                                                                                                |
| RedirectURL                      | Util                     | dw.web.URLRedirectMgr                                                                                                                                                                            |
| RemoveBasketPaymentInstrument    | Basket                   | dw.order.LineItemCtnr.removePaymentInstrument                                                                                                                                                    |
| RemoveCouponLineItem             | Basket                   | dw.order.LineItemCtnr.removeCouponLineItem                                                                                                                                                       |
| RemoveCustomer                   | Customer                 | dw.customer.CustomerMgr.removeCustomer                                                                                                                                                           |
| RemoveCustomerAddress            | Customer                 | dw.customer.AddressBook.removeAddress                                                                                                                                                            |
| RemoveCustomerPaymentInstrument  | Customer                 | dw.customer.Wallet.removePaymentInstrument                                                                                                                                                       |
| RemoveCustomObject               | CustomObject             | dw.object.CustomObjectMgr.remove                                                                                                                                                                 |
| RemoveGiftCertificateLineItem    | Basket                   | dw.order.LineItemCtnr.removeGiftCertificateLineItem                                                                                                                                              |
| RemoveProductLineItem            | Basket                   | dw.order.LineItemCtnr.removeProductLineItem                                                                                                                                                      |
| RemoveProductList                | ProductList              | dw.customer.ProductListMgr.removeProductList                                                                                                                                                     |
| RemoveProductListItem            | ProductList              | dw.customer.ProductList.removeItem                                                                                                                                                               |
| ReplaceLineItemProduct           | Basket                   | dw.order.ProductLineItem.replaceProduct                                                                                                                                                          |
| ReserveInventoryForOrder         | Order                    | dw.order.Basket.reserveInventory                                                                                                                                                                 |
| ResetCustomerPassword            | Customer                 | dw.customer.Credentials.setPasswordWithToken                                                                                                                                                     |
| ResetCustomerPasswordWithToken   | Customer                 | dw.customer.Credentials.setPasswordWithToken                                                                                                                                                     |
| ReturnImport                     | Order Center             | (job)                                                                                                                                                                                            |
| RunJobNow                        | Job                      | (job)                                                                                                                                                                                            |
| Script                           | Scripting                | Use require to import the script                                                                                                                                                                 |
| Search                           | Search                   | dw.catalog.ProductSearchModel.search, ContentSearchModel                                                                                                                                         |
| SearchCustomObject               | CustomObject             | dw.object.CustomObjectMgr.queryCustomObjects                                                                                                                                                     |
| SearchProductLists               | ProductList              | dw.customer.ProductListMgr.queryProductLists                                                                                                                                                     |
| SearchRedirectURL                | Search                   | dw.catalog.SearchModel.getRedirectURL                                                                                                                                                            |
| SearchSystemObject               | Search                   | Basically, whatever _Mgr class you are using should have a query method you can use. If it does not, use SystemObjectMgr._ or CustomObjectMgr.\* query methods                                   |
| SendGoogleSiteMap                | SiteMap                  | dw.sitemap.SitemapMgr.getSitemap                                                                                                                                                                 |
| SendMail                         | Common                   | dw.net.Mail.send                                                                                                                                                                                 |
| SetApplicablePriceBooks          | Catalog                  | Call the pipelet directly from the controller.                                                                                                                                                   |
| SetCustomerPassword              | Customer                 | dw.customer.Credentials.setPassword                                                                                                                                                              |
| SetFormOptions                   | Forms                    | dw.web.FormField.setOptions                                                                                                                                                                      |
| SetRequestLocale                 | Util                     | dw.system.Request.setLocale                                                                                                                                                                      |
| SetSessionCurrency               | Util                     | dw.system.Session.setCurrency                                                                                                                                                                    |
| SetShippingMethod                | Basket                   | dw.order.Shipping.setShippingMethod                                                                                                                                                              |
| SetSourceCode                    | SourceCode               | dw.system.Session.setSourceCode                                                                                                                                                                  |
| SourceCodeRedirectURL            | SourceCode               | session.SourceCodeInfo.Redirect.location                                                                                                                                                         |
| StartCheckout                    | Basket                   | dw.order.Basket.startCheckout                                                                                                                                                                    |
| TriggerReplication               | Replication (deprecated) | Job step ExcecuteDataReplication                                                                                                                                                                 |
| UpdateFormWithObject             | Forms                    | dw.web.FormGroup.copyFrom                                                                                                                                                                        |
| UpdateObjectWithForm             | Forms                    | dw.web.FormGroup.copyTo                                                                                                                                                                          |
| UpdatePageMetaData               | Common                   | dw.system.Request.getPageMetaData                                                                                                                                                                |
| UpdateProductLineItemQuantity    | Basket                   | dw.order.ProductLineItem.updateQuantity                                                                                                                                                          |
| UpdateProductOptionSelections    | Catalog                  | dw.catalog.ProductOptionModel.\*                                                                                                                                                                 |
| UpdateProductVariationSelections | Catalog                  | dw.catalog.ProductVariationModel.\*                                                                                                                                                              |
| UpdateSearchIndex                | Search                   | (job)                                                                                                                                                                                            |
| UpdateShippingOrders             | Order Center             | (job)                                                                                                                                                                                            |
| UpdateStockLevel                 | Order (deprecated)       | (deprecated)                                                                                                                                                                                     |
| ValidateActiveDataFile           | ImpEx                    | (deprecated)                                                                                                                                                                                     |
| ValidateResetPasswordToken       | Customer                 | dw.customer.CustomerMgr.getCustomerByToken                                                                                                                                                       |
| ValidateXMLFile                  | ImpEx                    | (deprecated)                                                                                                                                                                                     |
| VerifyCreditCard                 | Basket (deprecated)      | (deprecated)                                                                                                                                                                                     |
| VerifyCreditCardExpirationDate   | Basket (deprecated)      | dw.order.PaymentMgr.verifyCreditCardExpirationDate                                                                                                                                               |
| VerifyCreditCardNumber           | Basket (deprecated)      | dw.order.PaymentMgr.verifyCreditCardNumber                                                                                                                                                       |
| VerifyPaymentCard                | Basket                   | dw.order.PaymentCard.verify                                                                                                                                                                      |
| VSAuthorizeCreditCard            | VeriSign                 | (deprecated)                                                                                                                                                                                     |

## Pipelets by Pipelet Group

| Group                    | Pipelet                          | Script Method or Job Step                                                                                                                                                                        |
| ------------------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Analytics                | ABCTest                          | This can be replaced with plain JavaScript                                                                                                                                                       |
| Basket                   | AddBonusProductToBasket          | dw.order.LineItemCtnr.createBonusProductLineItem                                                                                                                                                 |
|                          | AddCouponToBasket                | dw.order.LineItemCtnr.createCouponLineItem                                                                                                                                                       |
|                          | AddCouponToBasket2               | dw.order.LineItemCtnr.createCouponLineItem                                                                                                                                                       |
|                          | AddGiftCertificateToBasket       | dw.order.LineItemCtnr.createGiftCertificateLineItem, and also use setReceipientName, setSenderName, setMessage, and in some cases setProductList item to add the gift certificate to the basket. |
|                          | AddPaymentInstrumentToBasket     | dw.order.LineItemCtnr.createPaymentInstrument                                                                                                                                                    |
|                          | AddProductToBasket               | dw.order.LineItemCtnr.createProductLineItem and setQuantityValue                                                                                                                                 |
|                          | CreateBasketForOrderEdit         | dw.order.BasketMgr.createBasketFromOrder                                                                                                                                                         |
|                          | CreateBillingAddress             | dw.order.LineItemCtnr.createBillingAddress                                                                                                                                                       |
|                          | CreateShipment                   | dw.order.LineItemCtnr.createShipment                                                                                                                                                             |
|                          | CreateShippingAddress            | dw.order.Shipping.createShippingAddress                                                                                                                                                          |
|                          | GetBasket                        | dw.order.BasketMgr.getBasket or dw.order.BasketMgr.getCurrentBasket()                                                                                                                            |
|                          | RemoveBasketPaymentInstrument    | dw.order.LineItemCtnr.removePaymentInstrument                                                                                                                                                    |
|                          | RemoveCouponLineItem             | dw.order.LineItemCtnr.removeCouponLineItem                                                                                                                                                       |
|                          | RemoveGiftCertificateLineItem    | dw.order.LineItemCtnr.removeGiftCertificateLineItem                                                                                                                                              |
|                          | RemoveProductLineItem            | dw.order.LineItemCtnr.removeProductLineItem                                                                                                                                                      |
|                          | ReplaceLineItemProduct           | dw.order.ProductLineItem.replaceProduct                                                                                                                                                          |
|                          | SetShippingMethod                | dw.order.Shipping.setShippingMethod                                                                                                                                                              |
|                          | StartCheckout                    | dw.order.Basket.startCheckout                                                                                                                                                                    |
|                          | UpdateProductLineItemQuantity    | dw.order.ProductLineItem.updateQuantity                                                                                                                                                          |
|                          | VerifyPaymentCard                | dw.order.PaymentCard.verify                                                                                                                                                                      |
| Basket (deprecated)      | CreateBasketPaymentInstrument    | dw.order.LineItemCtnr.createPaymentInstrument                                                                                                                                                    |
|                          | CreatePaymentTransaction         | (deprecated)                                                                                                                                                                                     |
|                          | VerifyCreditCard                 | (deprecated)                                                                                                                                                                                     |
|                          | VerifyCreditCardExpirationDate   | dw.order.PaymentMgr.verifyCreditCardExpirationDate                                                                                                                                               |
|                          | VerifyCreditCardNumber           | dw.order.PaymentMgr.verifyCreditCardNumber                                                                                                                                                       |
| Catalog                  | GetBrands                        | search for attribute brand using dw.catalog.ProductSearchModel                                                                                                                                   |
|                          | GetCategory                      | dw.catalog.CatalogMgr.getCategory                                                                                                                                                                |
|                          | GetLastVisitedProducts           | session.clickStream...                                                                                                                                                                           |
|                          | GetProduct                       | dw.customer.ProductListMgr.getProduct and dw.catalog.Product.isOnline (isOnline is used for products being previewed on the storefront)                                                          |
|                          | SetApplicablePriceBooks          | Call the pipelet directly from the controller.                                                                                                                                                   |
|                          | UpdateProductOptionSelections    | dw.catalog.ProductOptionModel.\*                                                                                                                                                                 |
|                          | UpdateProductVariationSelections | dw.catalog.ProductVariationModel.\*                                                                                                                                                              |
| Common                   | Assign                           | This is replaced by assignment of variables in JavaScript                                                                                                                                        |
|                          | Eval                             | This can be replaced with plain JavaScript                                                                                                                                                       |
|                          | Paging                           | dw.web.PagingModel.\*                                                                                                                                                                            |
|                          | SendMail                         | dw.net.Mail.send                                                                                                                                                                                 |
|                          | UpdatePageMetaData               | dw.system.Request.getPageMetaData                                                                                                                                                                |
| Content                  | GetContent                       | dw.content.ContentMgr.getContent                                                                                                                                                                 |
| Customer                 | CreateCustomer                   | dw.customer.CustomerMgr.createCustomer                                                                                                                                                           |
|                          | CreateCustomerAddress            | dw.customer.AddressBook.createAddress                                                                                                                                                            |
|                          | CreateCustomerPaymentInstrument  | dw.customer.Wallet.createPaymentInstrument                                                                                                                                                       |
|                          | FinalizeOAuthLogin               | dw.customer.oauth.OAuthLoginFlowMgr.finalizeOAuthLogin                                                                                                                                           |
|                          | GenerateResetPasswordToken       | dw.customer.Credentials.createResetPasswordToken                                                                                                                                                 |
|                          | GetCustomer                      | dw.customer.CustomerMgr.getCustomerByLogin                                                                                                                                                       |
|                          | GetCustomerAddress               | customer.addressBook.getAddress(addressID)                                                                                                                                                       |
|                          | GetCustomerPaymentInstruments    | dw.customer.Wallet.getPaymentInstruments                                                                                                                                                         |
|                          | InitiateOAuthLogin               | dw.customer.oauth.OAuthLoginFlowMgr                                                                                                                                                              |
|                          | LoginAgentUser                   | dw.customer.AgentUserMgr.loginAgentUser                                                                                                                                                          |
|                          | LoginCustomer                    | dw.customer.CustomerMgr.loginCustomer                                                                                                                                                            |
|                          | LoginOnBehalfCustomer            | dw.customer.AgentUserMgr.loginOnBehalfCustomer                                                                                                                                                   |
|                          | LogoutAgentUser                  | dw.customer.AgentUserMgr.logoutAgentUser                                                                                                                                                         |
|                          | LogoutCustomer                   | dw.customer.CustomerMgr.logoutCustomer                                                                                                                                                           |
|                          | RemoveCustomer                   | dw.customer.CustomerMgr.removeCustomer                                                                                                                                                           |
|                          | RemoveCustomerAddress            | dw.customer.AddressBook.removeAddress                                                                                                                                                            |
|                          | RemoveCustomerPaymentInstrument  | dw.customer.Wallet.removePaymentInstrument                                                                                                                                                       |
|                          | ResetCustomerPassword            | dw.customer.Credentials.setPasswordWithToken                                                                                                                                                     |
|                          | ResetCustomerPasswordWithToken   | dw.customer.Credentials.setPasswordWithToken                                                                                                                                                     |
|                          | SetCustomerPassword              | dw.customer.Credentials.setPassword                                                                                                                                                              |
|                          | ValidateResetPasswordToken       | dw.customer.CustomerMgr.getCustomerByToken                                                                                                                                                       |
| Customer (deprecated)    | CreateCustomerProfile            | (deprecated)                                                                                                                                                                                     |
|                          | GetCustomerProfile               | (deprecated)                                                                                                                                                                                     |
| CustomObject             | CreateCustomObject               | dw.object.CustomObjectMgr.createCustomObject                                                                                                                                                     |
|                          | RemoveCustomObject               | dw.object.CustomObjectMgr.remove                                                                                                                                                                 |
|                          | SearchCustomObject               | dw.object.CustomObjectMgr.queryCustomObjects                                                                                                                                                     |
| Forms                    | AcceptForm                       | dw.web.FormGroup.accept                                                                                                                                                                          |
|                          | ClearFormElement                 | dw.web.FormElement.clearFormElement                                                                                                                                                              |
|                          | InvalidateFormElement            | dw.web.FormElement.invalidateFormElement                                                                                                                                                         |
|                          | SetFormOptions                   | dw.web.FormField.setOptions                                                                                                                                                                      |
|                          | UpdateFormWithObject             | dw.web.FormGroup.copyFrom                                                                                                                                                                        |
|                          | UpdateObjectWithForm             | dw.web.FormGroup.copyTo                                                                                                                                                                          |
| ImpEx                    | ExportABTests                    | Job step ExportABTests                                                                                                                                                                           |
|                          | ExportCatalog                    | Job step ExportCatalog                                                                                                                                                                           |
|                          | ExportContent                    | Job step ExportContent                                                                                                                                                                           |
|                          | ExportCouponCodes                | Job step ExportCouponCodes                                                                                                                                                                       |
|                          | ExportCoupons                    | Job step ExportCoupons                                                                                                                                                                           |
|                          | ExportCustomerGroups             | Job step ExportCustomerGroups                                                                                                                                                                    |
|                          | ExportCustomerList               | Job step ExportCustomerList                                                                                                                                                                      |
|                          | ExportCustomers                  | Job step ExportCustomers                                                                                                                                                                         |
|                          | ExportCustomObjects              | Job step ExportCustomObjects                                                                                                                                                                     |
|                          | ExportGiftCertificates           | Job step ExportGiftCertificates                                                                                                                                                                  |
|                          | ExportInventoryLists             | Job step ExportInventoryLists                                                                                                                                                                    |
|                          | ExportMetaData                   | Job step ExportMetaData                                                                                                                                                                          |
|                          | ExportOrders                     | Job step ExportOrders                                                                                                                                                                            |
|                          | ExportPriceBooks                 | Job step ExportPriceBook                                                                                                                                                                         |
|                          | ExportProductLists               | Job step ExportProductLists                                                                                                                                                                      |
|                          | ExportPromotions                 | Job step ExportPromotions                                                                                                                                                                        |
|                          | ExportShippingMethods            | Job step ExportShippingMethods                                                                                                                                                                   |
|                          | ExportSlots                      | Job step ExportContentSlots                                                                                                                                                                      |
|                          | ExportSourceCodes                | Job step ExportSourceCodeGroups                                                                                                                                                                  |
|                          | ExportStores                     | Job step ExportStores                                                                                                                                                                            |
|                          | ExportTaxTable                   | Job step ExportTaxTable                                                                                                                                                                          |
|                          | ImportABTests                    | Job step ImportABTests                                                                                                                                                                           |
|                          | ImportActiveData                 | Job step ImportActiveData                                                                                                                                                                        |
|                          | ImportCatalog                    | Job step ImportCatalog                                                                                                                                                                           |
|                          | ImportContent                    | Job step ImportContentSlots                                                                                                                                                                      |
|                          | ImportCoupons                    | Job step ImportCoupons                                                                                                                                                                           |
|                          | ImportCustomerGroups             | Job step ImportCustomerGroups                                                                                                                                                                    |
|                          | ImportCustomerList               | Job step ImportCustomerList                                                                                                                                                                      |
|                          | ImportCustomers                  | Job step ImportCustomers                                                                                                                                                                         |
|                          | ImportCustomObjects              | Job step ImportCustomObjects                                                                                                                                                                     |
|                          | ImportGiftCertificates           | Job step ImportGiftCertificates                                                                                                                                                                  |
|                          | ImportInventoryLists             | Job step ImportInventoryLists                                                                                                                                                                    |
|                          | ImportKeyValueMapping            | ImportKeyValueMapping                                                                                                                                                                            |
|                          | ImportPriceBooks                 | Job step ImportPriceBook                                                                                                                                                                         |
|                          | ImportProductLists               | Job step ImportProductLists                                                                                                                                                                      |
|                          | ImportPromotions                 | Job step ImportPromotions                                                                                                                                                                        |
|                          | ImportShippingMethods            | Job step ImportShippingMethods                                                                                                                                                                   |
|                          | ImportSlots                      | Job step ImportContentSlots                                                                                                                                                                      |
|                          | ImportSourceCodes                | Job step ImportSourceCodeGroups                                                                                                                                                                  |
|                          | ImportStores                     | Job step ImportStores                                                                                                                                                                            |
|                          | ImportTaxTable                   | Job step ImportTaxTable                                                                                                                                                                          |
|                          | ValidateActiveDataFile           | (deprecated)                                                                                                                                                                                     |
|                          | ValidateXMLFile                  | (deprecated)                                                                                                                                                                                     |
| ImpEx (deprecated)       | ImportCampaigns                  | (deprecated)                                                                                                                                                                                     |
| Job                      | RunJobNow                        | (job)                                                                                                                                                                                            |
| Order                    | CancelOrder                      | dw.order.OrderMgr.cancelOrder                                                                                                                                                                    |
|                          | CreateGiftCertificate            | dw.order.GiftCertificateMgr.createGiftCertificate, setRecipientEmail, setRecipientName, setSenderName, setMessage, and setOrderNo.                                                               |
|                          | CreateOrder                      | dw.order.OrderMgr.createOrder, dw.order.OrderMgr.placeOrder                                                                                                                                      |
|                          | CreateOrder2                     | dw.order.OrderMgr.createOrder                                                                                                                                                                    |
|                          | CreateOrderNo                    | dw.order.OrderMgr.createOrderNo                                                                                                                                                                  |
|                          | ExportToOrderCenter              | (deprecated)                                                                                                                                                                                     |
|                          | FailOrder                        | dw.order.OrderMgr.failOrder                                                                                                                                                                      |
|                          | GetGiftCertificate               | dw.order.GiftCertificateMgr.getGiftCertificate                                                                                                                                                   |
|                          | GetOrder                         | dw.order.OrderMgr.getOrder                                                                                                                                                                       |
|                          | PlaceOrder                       | dw.order.OrderMgr.placeOrder                                                                                                                                                                     |
|                          | RedeemGiftCertificate            | dw.order.GiftCertificateMgr.redeemGiftCertificate                                                                                                                                                |
|                          | ReserveInventoryForOrder         | dw.order.Basket.reserveInventory                                                                                                                                                                 |
| Order (deprecated)       | UpdateStockLevel                 | (deprecated)                                                                                                                                                                                     |
| Order Center             | CreateShippingOrders             | (job)                                                                                                                                                                                            |
|                          | ReturnImport                     | (job)                                                                                                                                                                                            |
|                          | UpdateShippingOrders             | (job)                                                                                                                                                                                            |
| Payment                  | GetPaymentProcessor              | dw.order.PaymentMethod.getPaymentProcessor                                                                                                                                                       |
| ProductList              | AddGiftCertificateToProductList  | dw.customer.ProductList.createGiftCertificateItem                                                                                                                                                |
|                          | AddProductToProductList          | dw.customer.ProductList.createProductItem                                                                                                                                                        |
|                          | CreateProductList                | dw.customer.ProductListMgr.createProductList                                                                                                                                                     |
|                          | CreateProductListRegistrant      | dw.customer.ProductList.createRegistration, createCoRegistrant                                                                                                                                   |
|                          | GetProductList                   | dw.customer.ProductListMgr.getProductList                                                                                                                                                        |
|                          | GetProductLists                  | dw.customer.ProductListMgr.getProductLists                                                                                                                                                       |
|                          | RemoveProductList                | dw.customer.ProductListMgr.removeProductList                                                                                                                                                     |
|                          | RemoveProductListItem            | dw.customer.ProductList.removeItem                                                                                                                                                               |
|                          | SearchProductLists               | dw.customer.ProductListMgr.queryProductLists                                                                                                                                                     |
| Replication (deprecated) | GetReplicationStatus             | (deprecated)                                                                                                                                                                                     |
|                          | TriggerReplication               | Job step ExecuteDataReplication                                                                                                                                                                  |
| Scripting                | Script                           | Use require to import the script                                                                                                                                                                 |
| Search                   | GetSearchSuggestions             | dw.suggest.SuggestModel                                                                                                                                                                          |
|                          | Search                           | dw.catalog.ProductSearchModel.search, ContentSearchModel                                                                                                                                         |
|                          | SearchRedirectURL                | dw.catalog.SearchModel.getRedirectURL                                                                                                                                                            |
|                          | SearchSystemObject               | dw.order.GiftCertificateMgr.query*, dw.catalog.StoreMgr.query*, dw.campaign.CampaignMgr.querySource\*                                                                                            |
|                          | UpdateSearchIndex                | (job)                                                                                                                                                                                            |
| SiteMap                  | SendGoogleSiteMap                | dw.sitemap.SitemapMgr.getSitemap                                                                                                                                                                 |
| SourceCode               | SetSourceCode                    | dw.system.Session.setSourceCode                                                                                                                                                                  |
|                          | SourceCodeRedirectURL            | session.SourceCodeInfo.Redirect.location                                                                                                                                                         |
| Store                    | GetNearestStores                 | dw.catalog.StoreMgr.searchStoresBy\*                                                                                                                                                             |
| Util                     | InvalidateWebCache               | Job step InvalidateCache                                                                                                                                                                         |
|                          | RedirectURL                      | dw.web.URLRedirectMgr                                                                                                                                                                            |
|                          | SetRequestLocale                 | dw.system.Request.setLocale                                                                                                                                                                      |
|                          | SetSessionCurrency               | dw.system.Session.setCurrency                                                                                                                                                                    |
| VeriSign                 | VSAuthorizeCreditCard            | (deprecated)                                                                                                                                                                                     |

<!-- document id=47bc390f5fe2eca62816c4eae51f96a78fec932972186468c49868841782d300 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-orders-for-guests-admin.md -->

# Place an Order on Behalf of a User in a B2B Store

Store admins can place an order for a B2B Commerce store checkout on behalf of a user. This enhancement is specifically to complete checkouts that the user has already initiated. This enhancement allows store admins to complete checkouts where the payment is successful but the initial place order call failed.

For example, when a user's payment is successful but the initial order creation fails, the store admin can re-trigger the order placement using the same payment reference, ensuring all successful payments result in a corresponding order.

**Resource**

`/commerce/webstores/{webstoreId}/checkouts/{checkoutId}/orders`

Make a POST request to the [Commerce Webstore Checkout Orders](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order.htm) resource for the order placement.

**Request Parameters**

| Parameter Name     | Type   | Description                                                                               | Required or Optional |
| ------------------ | ------ | ----------------------------------------------------------------------------------------- | -------------------- |
| webstoreId         | String | Specify the webstore ID.                                                                  | Required             |
| checkoutId         | String | Specify the checkout ID. The value `active` isn’t supported for this field.               | Required             |
| effectiveAccountId | String | Specify the ID of the buyer account or guest buyer profile for which the request is made. | Required             |

**Considerations for Admin Order Placements**

- Only store admins can perform this operation.
- Existing validations, business logic, and permissions remain enforced.
- Orders created through this operation retain the user's ownership details.
- Best practice:
  - Perform thorough validation and testing in a sandbox environment, ensuring all related customizations and automations work as expected.
  - Use this operation only under controlled administrative conditions to specifically recover orders where a payment succeeded but the original order creation failed..

<!-- document id=7f8d017a24c3ed47e9e049098d41ce4da87a21dec633634251da5403a050e43e url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-place-order.md -->

# Place Order

Convert the checkout session into a permanent order. Choose between two implementations:

**Option 1: Commerce Webstore Checkout Orders API**

- Single-step order placement
- Best for simple, synchronous scenarios
- Minimal customization needed
- Endpoint: POST [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}/orders`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order.htm)

**Option 2: Commerce Webstore Checkout Place Order Action API**

- Two-step process (Prepare + Submit)
- Better control and extensibility
- Staged workflow with webhook support
- Endpoint: POST [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm)

See [Understanding B2B Checkout Place Order APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order-apis-overview.md) for detailed comparison.

<!-- document id=186c7478dd8b80aaa1f2baa48c63b2dc1bfaf389e0e1645bc945c337bffa3522 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/plugin-slas-setup.md -->

# Plugin SLAS Setup

With B2C Commerce version 25.3, [hybrid auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md) replaces Plugin SLAS. Hybrid storefronts that use Plugin SLAS are still supported.

**note:** We highly recommend migrating to Hybrid Auth so that you can take advantage of the improved performance and streamlined workflow.

Here are the guides that apply to only Plugin SLAS.

- [Configure a Hybrid Storefront with Plugin SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md)
- [Hybrid Stability Upgrade for PWA Kit Version 3.8.0](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-upgrade-v3.x.md)
- [Hybrid Stability Upgrade for PWA Kit Version 2.x](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-upgrade-v2.x.md)

### See Also

- [Use Composable Storefront in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md)
- [Configure a Hybrid Storefront with Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md)
- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)

<!-- document id=990836310c10388bee9ee296586b6ee8220a184eb77cd0cef105f9c926ce2500 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/external-api-access-guide-for-hyperforce-users.md -->

# Point of Sale API Developer Guide for Hyperforce Users

Accessing Point of Sale APIs externally from Hyperforce involves a secure, token-based authentication process. This guide outlines the steps required to generate a JSON Web Token (JWT) and invoke the Point of Sale API.

**note:** For a comprehensive list of APIs and SPIs, see [Point of Sale API Specifications](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html).

## Configuration and Setup

### Step 1: Configure External Client App

Create an External Client App with OAuth and JWT enabled. See [Create a Local External Client App](https://help.salesforce.com/s/articleView?id=xcloud.create_a_local_external_client_app.htm) in _Salesforce Help_.

#### Required OAuth Scopes

When you create the External Client App, select these OAuth scopes:

- **Manage user data via APIs (api)** - Provides access to user data
- **Perform requests at any time (refresh_token, offline_access)** - Allows obtaining OAuth access tokens
- **Access the Salesforce API Platform (sfap_api)** - Enables REST API platform access

#### Required OAuth Settings

Select these additional OAuth settings:

- **Enable Client Credentials Flow** - Permits the app to exchange client credentials for access tokens
- **Issue JSON Web Token (JWT)-based access tokens for named users** - Allows token issuance for named users

#### Policies Configuration

After creating the app, configure the Policies tab:

1. Navigate to the **Policies** tab of your External Client App and click **Edit**.
2. Select the **Enable Client Credentials Flow** checkbox.
3. Set a **Run As** user.
4. Select the **Issue JSON Web Token (JWT)-based access tokens** checkbox. By default, this token expires in 30 minutes.

### Step 2: Retrieve Key Values

JWT generation requires the domain, consumer key, and consumer secret, all sourced from the Salesforce Org where the merchant is configured.

**important:** The API token must come from the same Salesforce Org as the merchant. Tokens from a different Org fail authentication.

1. Log into the Organization or Sandbox Organization where the merchant was created.
2. From Setup, in the Quick Find box, enter "External Client Apps", and then select **External Client Apps Manager**.
3. Select the merchant's app, and click the **Settings** tab.
4. Expand the **OAuth Settings** section.
5. Click the **Consumer Key** and **Secret** button, and copy the key and secret. Save these values in a secure location.
6. From Setup, in the Quick Find box, enter "My Domain", and then select **My Domain**.
7. Copy the value shown in the Current My Domain URL field. Save this value in a secure location.

![mceclip0.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip0a.png)

### Step 3: Request JWT

Request a JWT from Salesforce. Use this example POST request as a starting point. Replace the domain, client ID, and client Secret with the values you copied from Step 1.

**Sample Token Request**

```bash
curl -X POST https://{my_domain}/services/oauth2/token -d "grant_type=client_credentials&client_id={consumer_key}&client_secret={consumer_secret}"
```

**Sample Response**

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlNBTVBMRSBKV1QgRk9SIERFTU8gUFVSUE9TRVMiLCJpYXQiOjE1MTYyMzkwMjJ9.XYwlhE_q0-yVwswgaXuOx2nbXRFpEbagcScXnjWt2yo",
  "signature": "uSs/SAlD/i+pL93EdLVUUY4F8uqfHHtteFii2E3zkhc=",
  "token_format": "jwt",
  "scope": "sfap_api einstein_gpt_api api",
  "instance_url": "https://sample-company.my.salesforce.com",
  "id": "https://login.pc-rnd.salesforce.com/id/XYZ/ABC",
  "token_type": "Bearer",
  "issued_at": "1713195676742",
  "api_instance_url": "https://api.salesforce.com"
}
```

Extract the access token value from the response. This token is used for the Authorization header in the API requests.

**Sample Authorization Header**

```json
Authorization: Bearer {access_token}
```

### Step 4: Make a Request

API requests require the headers in this list. The x-locale and x-region headers are merchant-specific, not Org-specific. A single Org (or Sandbox Org) can contain multiple merchants. These headers help route the request to the correct merchant within the Org.

- x-salesforce-region
- Content-Type
- x-locale
- x-region
- Authorization

**important:** Make sure that Content-Type is set to `application/json` in all requests.

#### Environment-Specific API Endpoints

The base URL and x-salesforce-region header value depend on the merchant's environment. Use the correct values for successful API requests. Make sure that the region and locale values match the region and locale for the merchant.

| **Environment** | **Production Endpoint (Non-Sandbox)**                            | **Sandbox Endpoint**                                                     | **Required x-salesforce-region Value**                        |
| --------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
| Production      | https://api.salesforce.com/commerce/retailcloud/v1-alpha.1       | https://api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox       | US: us-east-2<br/>EU/EMEA: eu-north-1<br/>APAC: ap-southeast-2 |
| Staging         | https://stage.api.salesforce.com/commerce/retailcloud/v1-alpha.1 | https://stage.api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox | us-east-2                                                     |
| Test            | https://test.api.salesforce.com/commerce/retailcloud/v1-alpha.1  | https://test.api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox  | us-west-2                                                     |
| Dev             | https://dev.api.salesforce.com/commerce/retailcloud/v1-alpha.1   | https://dev.api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox   | us-west-2                                                     |

In Production, use the `x-salesforce-region` value that matches the region where the merchant is hosted (US, EU/EMEA, or APAC).

**Example Request**

This example targets a Production Sandbox environment.

```bash
curl --location 'https://api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox/merchant/v2/users' \
--header 'x-salesforce-region: us-east-1' \
--header 'Content-Type: application/json' \
--header 'x-locale: en_US' \
--header 'x-region: US' \
--header 'Authorization: Bearer <NEW_TOKEN_GENERATED_FROM_CORRECT_ORG>'
```

<!-- document id=6d6640f0bc219af06271b0cb28fcbd13e4d9c0d05699b53706b9391fd3155777 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/about/about.md -->

# Point of Sale API Release Notes

Use Point of Sale (POS) APIs, Service Provider Interfaces (SPIs), and webhooks to extend your retail operations.

- To learn about using POS APIs, see the [Guides](/docs/commerce/retail-cloud/guide).
- To browse the API endpoints, use the left navigation. POS APIs are broken into three main groups: APIs, SPIs, and webhooks.
- To download the full specification, see [POS API (Full Specification)](https://developer.salesforce.com/docs/commerce/retail-cloud/references/pos-oas?meta=Summary).

## 08/17/2026

### API Updates

- [Fulfillment Order API](https://developer.salesforce.com/docs/commerce/retail-cloud/references/fulfillment-order-api?meta=Summary): New cancellation endpoint and request field added:
  - **Cancel BOPIS Items** (`POST /merchant/v1/sa/fulfillment/orders/{bopisOrderId}/stores/{storeId}/bopis/cancel`): Cancel BOPIS (Buy Online, Pick up in Store) items for a specific order and store, with support for cancellation reasons.
  - **`lastPickupDate`** (optional field on `FulfillmentOrder` request): Specifies the deadline for BOPIS order pickup in ISO_LOCAL_DATE format (`yyyy-MM-dd`). Used for display purposes and automated cancellation logic.

## 07/14/2026

### New SPI: Payment Gateway SPI (Beta)

- [Payment Gateway SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/payment-spi?meta=Summary): **Beta.** Integrate third-party payment gateway terminals (for example, Worldpay or Stripe Terminal) with POS. A store-local proxy server acts as an intermediary between the POS iOS client and payment gateway terminals, handling terminal communication, gateway protocol translation, and real-time event streaming over WebSockets so that new gateway integrations can be added without modifying the iOS application. For architecture, security modes, and client-side timeouts, see [Integrate Payment Gateways Using the Payment Gateway SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/payment-gateway-spi.html). This SPI is maintained in its own specification, outside of the [POS API (Full Specification)](https://developer.salesforce.com/docs/commerce/retail-cloud/references/pos-oas?meta=Summary). Use of this beta service is subject to the [Beta Services Terms](https://www.salesforce.com/company/legal/agreements/).

## 05/28/2026

### Point of Sale API Version 2.3.4 Release

#### New APIs and SPIs

- [Fiscal SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/fiscal-spi?meta=Summary): New SPI for fiscal integration operations. This SPI enables POS to delegate fiscal operations (SALE, RETURN, LOGIN, LOGOUT, etc.) to a merchant-provided SI connector and includes three endpoints:
  - **Fiscal Health Check SPI**: Verify fiscal middleware/service availability before processing operations.
  - **Fiscal Control Transaction SPI**: Handle control transactions such as LOGIN, LOGOUT, ABORT_TRANSACTION, CASH_IN, CASH_OUT, STORE_CLOSE, ZERO_RECEIPT, and DELETE_CART_ITEM.
  - **Fiscal Transaction SPI**: Handle fiscal transactions for SALE, RETURN, EXCHANGE, and DUPLICATE_PRINT operations.
  - Configure in CMS under **Store Management** | **Integration** | **Custom API Connectors** with API Key `FISCAL_SERVICE`.

- [Visual Search SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/visual-search-spi?meta=Summary): New SPI for visual product search that uses external image recognition providers. This SPI enables store associates to search products by photographing them with the POS device camera and includes two endpoints:
  - **Visual Search API** (`POST /products/upload`): Uploads an image for visual product search using multipart/form-data. Maps to `VISUAL_SEARCH_UPLOAD` connector. **Required.**
  - **Product Filter API** (`POST /products`): Filters, sorts, or paginates visual search results using JSON body with searchId. Maps to `VISUAL_SEARCH` connector. **Optional** - only required if supporting pagination, filtering, or sorting.
  - Configure in CMS under **Store Management** | **Integration** | **Custom API Connectors** with API Keys `VISUAL_SEARCH_UPLOAD` and `VISUAL_SEARCH`.
  - Enable in **Modules** | **Search** | **Visual Search** to show camera icon in Retail Cloud POS.

- [Wishlist SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/wishlist-spi?meta=Summary): New SPI to perform wishlist operations via a customer-managed provider adapter. This SPI enables retailers to integrate any wishlist provider without Retail Cloud engineering involvement and includes one endpoint with three operations:
  - **Get Customer Wishlist** (`GET`): Retrieves customer wishlist as a list of product IDs.
  - **Add Products to Wishlist** (`POST`): Adds one or more products to customer wishlist. Supports bulk operations.
  - **Remove Product from Wishlist** (`DELETE`): Removes a product from customer wishlist using query parameter.
  - The API returns product IDs only; POS enriches them with full product details from Solr.
  - Configure in CMS under **Store Management** | **Integration** | **Custom API Connectors** with API Key `WISHLIST`.

#### API Updates

- [Fulfillment Order API](https://developer.salesforce.com/docs/commerce/retail-cloud/references/fulfillment-order-api?meta=Summary): New cancellation endpoints added:
  - **Cancel BOFIS Items** (`POST /merchant/v1/sa/fulfillment/orders/{bofisOrderId}/stores/{storeId}/bofis/cancel`): Cancel BOFIS (Buy Online, Fulfill In Store) items.
  - **Cancel ROPIS Items** (`POST /merchant/v1/sa/fulfillment/orders/{orderId}/stores/{storeId}/ropis/cancel`): Cancel ROPIS (Reserve Online, Pick In Store) items.


---

## 04/20/2026

### Point of Sale API Version 2.3.3 Release

#### New APIs and SPIs

- [Gift Card SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/gift-card-spi?meta=Summary): New SPI for gift card operations including balance check, activation, adding funds, redemption, and void/reversal operations. Configure in CMS under **Store Management** | **Integrations** | **Custom Connectors** with API Key `GIFT_CARD_SERVICE`.
- [Warranty SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/warranty-spi?meta=Summary): New SPI for warranty eligibility checks. Implement this endpoint to retrieve eligible warranty products for merchandise items in the cart. Configure in CMS with API Key `WARRANTY_LOOKUP`.
- [Quote SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/quote-spi?meta=Summary): New SPI for quote management operations.
- [Promotion Events Webhook](https://developer.salesforce.com/docs/commerce/retail-cloud/references/promotion-events-webhook?meta=Summary): New webhook for promotion event notifications.

#### API Updates

- Merchant API endpoints now document v1 as the only supported version.
- [Store Group Management API](https://developer.salesforce.com/docs/commerce/retail-cloud/references/store-group-management-api?meta=Summary): Request bodies are now documented.

#### SPI Updates

- [Clienteling SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/clienteling-spi?meta=Summary) (Create/Update Customer):
  - `addressList` deprecated in requests only (still returned in responses).
  - `customerLoyaltyProfile` field deprecated from spec (use `loyaltyProfile` instead).
- Customer Profile and Wallet: New fields added to support card-on-file and payment imprint functionality.

#### Documentation Updates

- Full [Point of Sale API specification](https://developer.salesforce.com/docs/commerce/retail-cloud/references/pos-oas?meta=Summary) is now available for download.

<!-- document id=b372f677f925a18507a57af9218fd402570a80fdab411821dfc9effe4f5ea616 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/retail-cloud-api-spi-webhook-specs.md -->

# Point of Sale API, SPI, and Webhook Overview

Point of Sale supports common POS workflows with APIs, SPIs, and webhooks. It provides a set of APIs for merchants to provide, update, or read data in the Point of Sale system. Backend systems hook into these APIs to complete POS integration. Point of Sale SPIs provide extensibility and the opportunity to use external systems for POS workflows.

**note:** See [Point of Sale API Specifications](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html) for all Point of Sale APIs, SPIs, and webhooks.

## Prerequisites

- **Environment:** Used to determine URLs for OAuth2 and Point of Sale API. Possible values: Production, Staging
- **Point of Sale secret:** Used as header `PredictSpring-Secret` while calling Point of Sale API
- **x-api-key:** Used as header x-api-key while calling Point of Sale API
- **OAuth2 client ID:** Used for OAuth2 token generation
- **OAuth2 client secret:** Used for OAuth2 token generation

## Error Handling

See [Point of Sale SPI Error Handling](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-spi-error-handling.html).

## Application Programming Interface (API)

### Point of Sale API Summary

These tables list Point of Sale API endpoints and their usage descriptions.

#### CMS User Management

Create, search, update, and delete CMS users from Point of Sale.

| **API**                                   | **Description**                 |
| ----------------------------------------- | ------------------------------- |
| **GET**/merchant/{version}/users          | Retrieves all CMS users.        |
| **PUT**/merchant/{version}/users          | Updates a CMS user.             |
| **POST**/merchant/{version}/users         | Creates CMS users.              |
| **DELETE**/merchant/{version}/users       | Deletes a CMS user.             |
| **GET**/merchant/{version}/users/{userId} | Retrieves CMS user by `userID`. |

#### Inventory Management

Manage inventory in Point of Sale, including interactions related to cycle counts and receivings.

| **API**                                                       | **Description**                                                                                                                                      |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST**/merchant/{version}/ims/inventory/asn                 | Creates ASN in the Inventory Management System (IMS).                                                                                                |
| **PUT**/merchant/{version}/ims/inventory/cyclecount/cancel | Cancels a specified cycle count.                                                                                                                     |
| **POST**/merchant/{version}/ims/inventory/cyclecount/full  | Creates a full cycle count (a complete inventory of products in a store can be counted only through a full cycle count).                               |
| **POST**/merchant/{version}/ims/inventory/cyclecount/manual   | Creates a manual cycle count (allows counting of a specific set of products).                                                                        |
| **POST**/merchant/{version}/ims/inventory/cyclecount/partial  | Creates a partial cycle count for a particular group of products included in a category, brand, or other product attribute specified in the request. |

#### Notification

Send notifications directly to specific app users.

| **API**                                   | **Description**                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST**/merchant/{version}/notifications | Schedules immediate notifications of certain events (for example, an order ships or a cart is abandoned) to send to one or more specified target devices. App users of target devices can be referenced in the API via installation ID or email address, which maps to an installation ID in Point of Sale if captured when the user logged in to the app. |

#### Product Management

Create, update, and delete products in Point of Sale.

| **API**                                | **Description**   |
| -------------------------------------- | ----------------- |
| **PUT**/merchant/{version}/products    | Updates products. |
| **POST**/merchant/{version}/products   | Creates products. |
| **DELETE**/merchant/{version}/products | Deletes products. |

#### Promotion Management

Create, update, retrieve, and delete promotions in Point of Sale.

| **API**                                                       | **Description**                                                                                 |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **GET**/merchant/{version}/promotions                         | Retrieves all promotions.                                                                       |
| **PUT**/merchant/{version}/promotions                         | Updates promotions.                                                                             |
| **POST**/merchant/{version}/promotions                        | Creates promotions.                                                                             |
| **GET**/merchant/{version}/promotions/download/report         | Downloads a report of all CMS-created promotions (inactive and active).                         |
| **POST**/merchant/{version}/promotions/upload                 | Uploads promotions via JSON file.                                                               |
| **GET**/merchant/{version}/promotions/{promotionId}           | Retrieves a promotion by its promotion ID.                                                      |
| **DELETE**/merchant/{version}/promotions/{promotionId}        | Deletes a promotion by its promotion ID.                                                        |
| **GET**/merchant /{version} /promotions /{promotionId} /supc  | Retrieves list of Single Use Promotion Codes (SUPC) in a promotion from Point of Sale.          |
| **PUT** /merchant /{version} /promotions /{promotionId} /supc | Updates the redemption status of SUPCs in a promotion that were redeemed by an external system. |
| **POST**/merchant/{version}/promotions/{promotionId}/supc     | Creates/sends new valid SUPCs in a promotion to Point of Sale.                                  |

#### Store Associate Management

Create, search, update, and deactivate store associates from Point of Sale.

| **API**                                             | **Description**                                                                                                                                |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **GET**/merchant/{version}/associates               | Retrieves active/inactive store associates based on query parameters `storeId` and `associateId`.                                              |
| **PUT**/merchant/{version}/associates               | Updates a store associate in Point of Sale.                                                                                                    |
| **POST**/merchant/{version}/associates              | Creates a store associate in Point of Sale.                                                                                                    |
| **DELETE**/merchant/{version}/associates            | Deactivates the store associate specified by the `associateId` query parameter. This method sets the `active` field on the associate to false. |
| **GET**/merchant/{version}/associates/{associateId} | Retrieves store associate details by `associateId`.                                                                                            |

#### Store Product Management

Manage store inventory.

| **API**                                                      | **Description**                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **PUT**/merchant/{version}/storeproducts                     | Updates store product details by updating item's list price, sale price, quantity and promo banner text.                                                                                                                                                                                                                                                                  |
| **GET**/merchant/{version}/storeproducts/inventory           | Returns store inventory details for queried store and product ID(s). This endpoint accepts multiple product or store IDs in a single call. <br>- `productIds`: (required): Comma-separated list of up to 20 product IDs.<br>- `storeIds`: Comma-separated list of up to 1,000 store IDs. If empty or null, defaults to all stores.                                        |
| **PUT**/merchant/{version}/storeproducts/inventory           | Updates store or E-comm inventory of products.                                                                                                                                                                                                                                                                                                                            |
| **POST**/merchant/{version}/storeproducts/inventory          | Creates store or E-comm inventory of products.<br>**Note:** This endpoint performs an incremental inventory upload to Point of Sale. For a full inventory, use a feed instead. For more information, see [Store Inventory & Pricing Feed](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_data_feeds_specs_store_inv_price.htm) in _Salesforce Help_. |
| **GET**/merchant/{version}/storeproducts/inventory/{storeId} | Provides the URL for a CSV file containing store inventory.                                                                                                                                                                                                                                                                                                               |

#### Order Management

Create, search, retrieve, and repost orders from Point of Sale.

| **API**                                      | **Description**                                                           |
| -------------------------------------------- | ------------------------------------------------------------------------- |
| **POST**/merchant/{version}/sa/orders        | Creates order data based on customer order data in payload.               |
| **POST**/merchant/{version}/sa/orders/repost | Reposts orders to an external system as specified by a list of order IDs. |
| **POST**/merchant/{version}/sa/orders/search | Searches and retrieves orders based on input parameters.                  |
| **GET**/merchant/{version}/sa/orders/{id}    | Retrieves order data based on order ID.                                   |

## Service Provider Interface (SPI)

SPIs are outbound API calls made from Point of Sale that expect a response from the customer system and alter the behavior of the transaction journey for an associate. On the merchant side, a web server listens to this API request and handles the call. In response, Point of Sale expects a full JSON response that updates cart or customer data (for example, Clienteling API and promotion calculation).

### Environments

To implement the Point of Sale SPI, provide both a staging (sandbox) environment for testing and a production environment.
Requests to the SPI APIs take these forms.

#### Staging

<!-- prettier-ignore -->
`https://<staging_path>/<api_version>/<api_path>?api_key={API_KEY}&<additional_request_parameters>`

Example:

`https://**staging.mycompany.com/spi**/1.0/customer/1234?api_key=ibafw4ehb2vhibdsih3vbadv`

#### Production

<!-- prettier-ignore -->
`https://<production_path>/<api_version>/<api_path>?api_key={API_KEY}&<additional_request_parameters>`

Example:

`https://**www.mycompany.com/spi**/1.0/customer/1234?api_key=zmcnv9lzjkxn2vcl8nzcx`

**note:** `api_version` is appended to the path for each request, and is based on the version of the Point of Sale SPI APIs that are implemented. `api_version` must be consistent across all API requests made to a particular SPI implementation. For example, you can make all requests with `api_version` 1.0 or 1.1, but not a mix of 1.0 and 1.1.

### Authentication

To implement the Point of Sale SPI, provide an authentication mechanism for accessing the SPI APIs with an API key. Point of Sale provides API keys (one for staging and one for production) to validate, and all SPI API requests contain an `api_key` request parameter.

If an invalid API key is supplied, the API responds with a `401 Unauthorized` response containing an empty response body.

##### Sample Request with Authentication

```bash
GET /customer/1234?api_key={API_KEY}
```

##### Sample Authentication Failure Response

```bash
HTTP/1.1 401 Unauthorized
{ }
```

### Configuration and Setup

1. In CMS, go to **Store Management** | **Integrations** | **Custom Connectors**.
2. Click **Create**.
3. For Connector Type, select **SPI**.
4. For Endpoint Name, select an endpoint. For example, **CREATE_CUSTOMER**.
5. Set the API Endpoint to an external endpoint for the SPI. For example, `https://sample/external/endpoint/to/create/customer`.
6. Select or enter the integration type. For example, **HTTP_POST**.
7. Set the header for the API in **JSON Headers**. Headers can be Content-Type or Authorization attributes (`clientId` or `password`). For example:

```json
Headers:{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}
```

### NetSuite OAuth Setup

Point of Sale Custom Connection supports NetSuite OAuth authentication, ensuring secure access and synchronization of customer data while reducing the risk of authentication errors. This setup is configured directly in CMS.

**important:** Before proceeding, make sure that an ERP configuration is set up in CMS. Without this configuration, the SPI fails to process and results in an error within CMS.

1. In CMS, go to **Store Management** | **Integrations** | **Custom Connectors**.
2. Edit an existing configuration or create a new one.
3. Turn on **NetSuite OAuth** for the OAuth Config. This automatically retrieves the necessary OAuth credentials from the ERP configuration.
4. Save your changes.

![blobid0.png](https://developer.salesforce.com/docs/media/retail-cloud/blobid0.png)

### Define Custom Attributes

Define custom attributes to pass in a product's SPI response. For example, when integrating with the [Delivery Group SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/delivery-group-spi?meta=Summary), define custom attributes in the `spiCustomProductAttributes` setting, and these attributes are included in the SPI response.

1. In CMS, go to **Store Management** | **Store Settings** | **Product**.
2. Go to **Merchant-specific product attributes to be provided in SPI request** (`spiCustomProductAttributes`) and enter a comma-separated list of case-insensitive attributes from the product collection (for example, `variantGroupId`, `salePrice`, `manufacturer`, `brand`).

![mceclip0b.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip0b.png)

### Headers Sent by Point of Sale

Point of Sale automatically injects these headers when the `populateNewCustomAPIHeaders` toggle is enabled.

**Toggle location (CMS):** Store Management | Store Settings | Search Settings | Advanced | Populate New Custom API Headers

When enabled, every request to the SPI provider includes these headers:

| Header | Description |
| ------ | ----------- |
| `x-merchant-id` | Merchant identifier (tenant) |
| `x-locale` | Locale code (for example, `en_US`, `en_GB`) |
| `x-store-id` | Store identifier where the search is performed |
| `x-register-id` | Register identifier |
| `x-associate-id` | Associate performing the search |

**important:** These headers are available only when the `populateNewCustomAPIHeaders` store setting is enabled. Without this setting, no contextual headers are sent.

### Point of Sale SPI Summary

These tables list Point of Sale SPIs and their usage descriptions.

#### Clienteling

Create, search, update, and retrieve details of a specific customer from an external system rather than from the Point of Sale system of record.

| **SPI**                                                        | **Details**                                                                                                                                                                                                                      |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST**/merchant/spi/sample/endpoint/sa/customers             | Creates a customer based on customer data entered in the POS<br><br>**Endpoint Name:** CREATE_CUSTOMER<br>**Integration Type:** HTTP_POST                                                                                        |
| **GET**/merchant/spi/sample/endpoint/sa/customers              | Retrieves customer's interaction history<br><br>**Endpoint Name:** CUSTOMER_INTERACTION_HISTORY<br>**Integration Type:** HTTP_GET<br><br>**Important:** This is a legacy custom connector. Do not use.                           |
| **PUT**/merchant/spi/sample/endpoint/sa/customers              | Updates an existing customer. The existing customer ID is provided under the object labeled 'profile.customerId'<br><br>**Endpoint Name:** UPDATE_CUSTOMER<br>**Integration Type:** HTTP_PUT                                     |
| **GET**/merchant/spi/sample/endpoint/sa/customers/{customerId} | Retrieves customer data based on the customer ID<br><br>**Endpoint Name:** GET_CUSTOMER<br>**Integration Type:** HTTP_GET                                                                                                        |
| **GET**/merchant/spi/sample/endpoint/sa/customers              | Retrieves customer's order history<br><br>**Endpoint Name:** GET_ORDER_LIST<br>**Integration Type:** HTTP_GET<br><br>**Important:** This is a legacy custom connector. Do not use.                                               |
| **GET**/merchant/spi/sample/endpoint/sa/customers              | Searches and retrieves customers based on the input parameters. For details and examples on utilizing this SPI, refer to SPI Customer Search Layout<br><br>**Endpoint Name:** SEARCH_CUSTOMERS<br>**Integration Type:** HTTP_GET |

<!--

Paul DiSabito (8/1/25): I removed the link in the final row of this table, so that I can build the topic without errors.

This is what it originally looked like:

| **GET**/merchant/spi/sample/endpoint/sa/customers              | Searches and retrieves customers based on the input parameters. For details and examples on utilizing this SPI, please refer to [SPI Customer Search Layout](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-customer-search-layout.html)<br><br>**Endpoint Name:** SEARCH_CUSTOMERS<br>**Integration Type:** HTTP_GET |

The


-->

**Customer Address**

**_Used to create, search, update, and delete a customer's address from an external system rather than from the Point of Sale system of record_**

| **SPI**                                                      | **Details**                                                                                                                                    |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **GET**/merchant/spi/sample/endpoint/sa /customer/address    | Retrieves a list of addresses for a customer by customer ID<br><br>**Endpoint Name:** GET_CUSTOMER_ADDRESSES<br>**Integration Type:** HTTP_GET |
| **PUT**/merchant/spi/sample/endpoint/sa /customer/address    | Updates a customer address by customer ID and address ID.<br><br>**Endpoint Name:** UPDATE_CUSTOMER_ADDRESS<br>**Integration Type:** HTTP_PUT     |
| **POST**/merchant/spi/sample/endpoint/sa /customer/address   | Adds a new address for a customer.<br><br>**Endpoint Name:** CREATE_CUSTOMER_ADDRESS<br>**Integration Type:** HTTP_POST                            |
| **DELETE**/merchant/spi/sample/endpoint/sa /customer/address | Deletes a customer address by customer ID and address ID.<br><br>**Endpoint Name:** DELETE_CUSTOMER_ADDRESS<br>**Integration Type:** HTTP_DELETE   |

**Inventory**

**_Used for retrieving inventory count of products online or in-store from an external system rather than from the Point of Sale system of record, and for reverting reserved inventory_**

| **SPI**                                                                                     | **Details**                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST**/merchant/spi/sample/endpoint/sa /inventoryService/revert                           | Reverts reserved inventory for the specified products in the provided cart. Implement this endpoint to ensure reserved inventory is properly reverted in scenarios such as a payment failure during checkout.<br><br>**Endpoint Name:** INVENTORY_SERVICE<br>**Integration Type:** HTTP_POST                |
| **POST**/merchant/spi/sample/endpoint/sa/inventory /to/check/inventory/from/external/system | Checks the external system for the availability of given products by checking their inventory count (online only, not applicable for in-store). The merchant receives the product ID or GTIN in the response.<br><br>**Endpoint Name:** ONLINE_ITEM_INVENTORY_CHECK<br>**Integration Type:** HTTP_POST                                                       |
| **POST**/merchant/spi/sample/endpoint /product/getInventoryOverview                         | Checks the external system for the availability of a given product. The response appears on the existing inventory overview widget, showing availability for all stores or a text indicating availability when a ZIP code is included in the request.<br><br>**Endpoint Name:** GET_PRODUCT_INVENTORY_OVERVIEW<br>**Integration Type:** HTTP_POST |

**Loyalty**

**_Used for retrieving loyalty points redeemed in a transaction and the available rewards for a customer._**

| **SPI**                                                    | **Details**                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **POST**/merchant/spi/sample/endpoint/sa /getLoyaltyPoints | Retrieves the number of loyalty points redeemed in a transaction from an external system at the time of tendering, for printing on receipts.<br><br>**Important:** This applies only to orders placed by customers with loyalty profiles.<br><br>**Endpoint Name:** LOYALTY_POINTS_EARNED<br>**Integration Type:** HTTP_POST |
| **POST**/merchant/spi/sample/endpoint /reward/lookup       | Retrieves the available rewards for a customer that can be applied as a tender. Reward lookup is based on the Customer Account (`CustomerId`, Card Acquisition Token, and so on).<br><br>**Endpoint Name:** REWARD_LOOKUP<br>**Integration Type:** HTTP_POST                                                                                     |

**Orders**

**_Used to retrieve, search, and export orders from an external system rather than from the Point of Sale system of record_**

## Order SPIs

**important:** Starting in June 2024, Point of Sale updated the order SPIs. The JSON schema uses the transaction data model for exporting and importing store transactions, including sales, returns, and exchanges. For details, see [Point of Sale API Specifications](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html).

| SPI                                                                                              | Details                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **GET**/merchant/spi/sample/endpoint/sa/orders/to/get/order/from/external/system/{orderId}       | Fetches a specified order from an external system during BORIS flow with SPI as the order master for all orders. The merchant's system is expected to handle the return processing.<br><br>**Important:** If enabling delivery grouping with this SPI, you'll need to send "DeliveryGroup" list in the SPI response. Learn More<br><br>**Endpoint Name:** GET_ORDER_DETAIL<br>**Integration Type:** HTTP_GET | --> |
| **GET**/merchant/spi/sample/endpoint/sa/orders/to/get/order/from/external/system/{orderId}       | Fetches a specified order from an external system during BORIS flow with SPI as the order master for all orders. The merchant's system is expected to handle the return processing.<br><br>**Important:** If enabling delivery grouping with this SPI, you'll need to send "DeliveryGroup" list in the SPI response.<br><br>**Endpoint Name:** GET_ORDER_DETAIL<br>**Integration Type:** HTTP_GET            |
| **GET**/merchant/spi/sample/endpoint/sa/orders/to/get/boris/order/from/external/system/{orderId} | Fetches a specified order from an external system during BORIS flow with Point of Sale as the order master for in-store placed orders. The merchant's system is expected to handle the return processing.<br><br>**Endpoint Name:** BORIS_GET_ORDER_DETAIL<br>**Integration Type:** HTTP_GET                                                                                                                  |
| **POST**/merchant/spi/sample/endpoint/sa/orders/to/search/orders/from/external/system            | Searches orders from the merchant's system based on the provided filter criteria and then display it on the Order History screen of Point of Sale<br><br>**Endpoint Name:** SEARCH_ORDERS<br>**Integration Type:** HTTP_POST                                                                                                                                                                              |
| **POST**/merchant/spi/sample/endpoint/sa/orders/to/export/return/order/to/external/system        | Posts the sale transaction to the merchant's external system (for example, BORIS). This will also pull online orders if this endpoint is connected to a system that has online orders. The aim of this SPI is to provide an interface where merchants can choose what orders to send back.<br><br>**Endpoint Name:** RETURN<br>**Integration Type:** HTTP_POST                                               |

<!-- Paul (8-26-25): In the above table, "Learn More" pointed to ../../cms-store-management/omnichannel/omnichannel-configuring-shipping-methods-on-pos-app.md. I removed the link to get the content to build. I'll have to replace the link to a migrated topic later. -->

**Other**

**_Used to verify employee status, retrieve delivery/pickup dates, validate cart, etc._**

| **SPI**                                                                                                 | **Details**                                                                                                                                                        |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **POST**/merchant/spi/sample/endpoint/sa/cartValidation                                                 | Used to perform custom cart validations and can also be utilized to reserve inventory<br><br>**Endpoint Name:** CART_VALIDATION<br>**Integration Type:** HTTP_POST |
| **POST**/merchant/spi/sample/endpoint/sa/datetime/ slots/from/external/system                           | Retrieves delivery/pickup dates and time slots for applicable items in an order<br><br>**Endpoint Name:** DATE_PICKER<br>**Integration Type:** HTTP_POST           |
| **POST**/merchant/spi/sample/endpoint/sa/employee /verification/to/verify/employee/from/external/system | Verifies employee information when applying employee discounts on POS app<br><br>**Endpoint Name:** VERIFY_EMPLOYEE<br>**Integration Type:** HTTP_POST             |

**Visual Search**

**_Used to perform visual product search by sending an image to an external recognition provider and optionally refining results with filters, sorting, and pagination_**

| **SPI**                                                                    | **Details**                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST**/merchant/spi/sample/endpoint/sa/visualSearch/upload               | Uploads a captured image to an external provider for image recognition. Returns a `searchId` and a ranked list of matching product IDs. Optionally returns filters, sort options, and pagination.<br><br>**Endpoint Name:** VISUAL_SEARCH_UPLOAD<br>**Integration Type:** MULTIPART_FORM_POST                   |
| **POST**/merchant/spi/sample/endpoint/sa/visualSearch                      | Refines visual search results by applying filters, sort criteria, or pagination to a previously uploaded image's result set (identified by `searchId`).<br><br>**Endpoint Name:** VISUAL_SEARCH<br>**Integration Type:** HTTP_POST                                                                   |

**Shipping Methods**

**_Used for receiving applicable shipping methods from an external system rather than from the Point of Sale system of record_**

| **SPI**                                                   | **Details**                                                                                                                                                                                                                                                                                           |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST**/merchant/spi/sample/endpoint/sa/shipping/methods | Merchant-provided SPI that takes in cart items that are marked for shipping/delivery, customerId, address, etc. as input and provides applicable shipping options<br><br>**Endpoint Name:** Dependent on the implementation and should be provided by the merchant<br>**Integration Type:** HTTP_POST |

**Taxes**

**_Used to calculate taxes, retrieve tax exemptions, and download tax rates_**

| **SPI**                                                               | **Details**                                                                                                                                     |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST**/merchant/spi/sample/endpoint/taxEngine/calculateTax          | Calculates the tax based on the rules defined in the merchant's system<br><br>**Endpoint Name:** TAX_SERVICE<br>**Integration Type:** HTTP_POST |
| **GET**/merchant/spi/sample/endpoint/taxEngine/downloadTaxRates       | Retrieves a list of tax rates to be used for offline transactions<br><br>**Endpoint Name:** TAX_SERVICE<br>**Integration Type:** HTTP_GET       |
| **POST**/merchant/spi/sample/endpoint/taxEngine/finalizeTaxSubmission | Used to finalize the taxes applied to sale transactions<br><br>**Endpoint Name:** TAX_SERVICE<br>**Integration Type:** HTTP_POST                |
| **GET**/merchant/spi/sample/endpoint/taxEngine/getTaxExemptions       | Retrieves a list of tax exemptions supported on the merchant's side<br><br>**Endpoint Name:** TAX_SERVICE<br>**Integration Type:** HTTP_GET     |

### SPI Order Export Endpoints

- For product details, there are two fields: `orderProductList` and `productList`. `orderProductList` contains a list of products sold, while `productList` is a subset (if there have been any returns or exchanges) that contains products sold with returned products and quantities removed or adjusted. For example, `productList` gives you the remaining products in the order that aren't returned. If mapping to an ERP system, use `orderProductList` and `returnProductList` instead of `productList` to simplify the ingestion logic.
- For fulfillment details, there are two fields: `omniFulfillmentType` and `fulfillmentType`. If mapping to an ERP system for cash/carry/charge, use `fulfillmentType` and `fulfillmentSubType` instead of `omniFulfillmentType`.

## Webhooks

Webhooks are _outbound_ API calls made from Point of Sale to an external system when specified events are triggered on POS.

### Configuration and Setup

1. In CMS, go to **Store Management** | **Integrations** | **Custom Connectors**.
2. Click **Create** in the upper right.
3. For **Connector Type**, select **Webhook**.
4. For **Endpoint Name**, select an endpoint (for example, **CREATE_CUSTOMER**).
5. For **API Endpoint**, provide an external endpoint for the webhook (for example, `https://sample/external/endpoint/to/create/customer`).
6. For **Integration Type**, select or enter the type of integration (for example, **HTTP_POST**).
7. For **JSON Headers**, provide the header for the API. Headers can be Content-Type or Authorization attributes (`clientId` or `password`). For example:

```
Headers:{"Content-Type":"application/json","client_id":"myClientId", "client_secret":"myClientSecret"}
```

### NetSuite OAuth Setup

Point of Sale Custom Connection supports NetSuite OAuth authentication, ensuring secure access and synchronization of customer data while reducing the risk of authentication errors. Configure this setup directly in CMS.

**important:** Before proceeding, make sure that an ERP configuration is set up in CMS. Without this configuration, the SPI fails to process and results in an error within CMS.

1. In CMS, go to **Store Management** | **Integrations** | **Custom Connectors**.
2. Edit an existing configuration or create a new one.
3. For **OAuth Config**, enable **NetSuite OAuth**. This automatically retrieves the necessary OAuth credentials from the ERP configuration.
4. Save your changes.

![blobid0a.png](https://developer.salesforce.com/docs/media/retail-cloud/blobid0a.png)

### Reposting Webhooks

You can manually repost failed webhook events in Point of Sale.

1. In CMS, go to **Store Management** | **Reporting and Analytics** | **Repost Failed Webhook Events**.
2. Search for the failed webhook event by configuring the search query parameters.
3. Click **View Details** to view the details of the payload inside the selected webhook event.
4. Click **Repost** to manually trigger a webhook event repost.

#### Point of Sale Webhook Summary

This table lists all available Point of Sale webhooks and their usage descriptions.

**E-Receipt**

_Used for sending order details for email purposes_

| **Webhook**      | **Details**                                                                                                                                                                                                               |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Receive eReceipt | Instead of using Point of Sale email service, merchants can use their own email service by providing an endpoint to receive order details.<br><br>**Endpoint Name:** ERECEIPT_CUSTOMER<br>**Integration Type:** HTTP_POST |

**Inventory Events**

_Used for sending inventory data to an external system_

| **Webhook**                           | **Details**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send inventory Transfer data          | **Endpoint Name:** Select one of the following values:<br>• INVENTORY_EXPORT_ASN<br>• INVENTORY_EXPORT_STS<br>• INVENTORY_EXPORT_RTV<br>• INVENTORY_EXPORT_CTS<br>• INVENTORY_EXPORT_BLD<br><br>**Events:** Select the subscribed event's data to be sent out, available events:<br>• ASN_RECEIVED_EVENT<br>• ASN_PARTIALLY_RECEIVED_EVENT<br>• ASN_RECEIVE_COMPLETED_EVENT<br><br>**Integration Type:** HTTP_POST<br><br>For a full list of events, see [Point of Sale API Specifications](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html) |
| Send inventory adjustment data        | **Endpoint Name:** INVENTORY_EXPORT_INA<br><br>**Events:**<br>• INVENTORY_ADJUSTMENT<br>• INVENTORY_BUCKET_ADJUSTMENT<br><br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Send inventory bucket adjustment data | **Endpoint Name:** INVENTORY_EXPORT_INBA<br><br>**Events:** INVENTORY_BUCKET_ADJUSTMENT<br><br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Send cycle count data                 | **Endpoint Name:** INVENTORY_EXPORT_CYC<br><br>**Events:** Select the subscribed event's data to be sent out, available events:<br>• CYC_COUNT_CREATED_EVENT<br>• CYC_COUNT_STARTED_EVENT<br>• CYC_COUNT_COMPLETED_EVENT<br>• CYC_COUNT_CANCELED_EVENT<br><br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                                                                        |
| Send purchase order data              | **Endpoint Name:** INVENTORY_EXPORT_PO<br><br>**Events:** Select the subscribed event's data to be sent out, available events:<br>• PO_TRANSFER_STARTED_EVENT<br>• PO_TRANSFER_COMPLETED_EVENT<br>• PO_TRANSFER_ERRORED_EVENT<br><br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                                                                                                 |
| Send sales data                       | Indicates that an item (or items) has been sold. When this event is triggered, the expectation is that the inventory for the specified item(s) should decrease.<br><br>**Endpoint Name:** SALE_INVENTORY<br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                                                                                                                          |
| Send return data                      | Indicates that an item (or items) has been returned or exchanged. When this event is triggered, the inventory for the specific item(s) should increase or adjust in some manner if it's an exchange.<br><br>**Endpoint Name:** RETURN_INVENTORY<br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                                                                                   |

**Orders**

_Used for sending order posting-related data to an external system_

| **Webhook**   | **Details**                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Export Sale   | Provides export details of sale transactions to an external system.<br><br>**Endpoint Name:** ORDER<br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                                            |
| Order Update  | Provides export details of updated sale transactions to an external system.<br><br>**Endpoint Name:** ORDER_UPDATE<br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                                             |
| BOPIS Export  | Provides export details of Buy Online Pickup In Store (BOPIS) transactions to an external system.<br><br>**Endpoint Name:** BOPIS_EXPORT<br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                       |
| BOFIS Export  | Provides export details of Buy Online Fulfill In Store (BOFIS) transactions to an external system.<br><br>**Endpoint Name:** BOFIS_EXPORT<br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                      |
| ROPIS Export  | Provides export details of Reserve Online Pickup in Store (ROPIS) transactions to an external system.<br><br>**Endpoint Name:** ROPIS_EXPORT<br>**Integration Type:** HTTP_POST                                                                                                                                                                                                                                   |
| Return Export | Posts the sale transaction to the merchant's external system (for example, BORIS). This also pulls online orders if this endpoint is connected to a system that has online orders. This SPI provides an interface where merchants can choose what orders to send back.<br><br>**Learn More:** Return Export Documentation<br><br>**Endpoint Name:** RETURN<br>**Integration Type:** HTTP_POST |

<!-- Paul(8-26-25): In the above table, "Return Export Documentation" used to link to ../../cms-store-management/omnichannel/omnichannel-configuring-shipping-methods-on-pos-app.md. I removed the link to get the content to build. I'll have to replace this later after migration. -->

**Others**

_Used for sending non-categorized data (for example, void carts) to an external system_

| **Webhook**          | **Details**                                                                                                                                                                                                                                                                                                                                          |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Void Cart            | Provides real-time details when a cart is voided, which can be used to store and refer to in Loss Prevention audits.<br><br>**Endpoint Name:** VOID_CART<br>**Integration Type:** HTTP_POST<br><br>**Note:** When the app is in offline mode, voided carts are queued and pushed to Point of Sale services once the app regains online connectivity. |
| Suspend Cart         | Provides real-time details when a cart is suspended, which can be used to store and refer to in Loss Prevention audits.<br><br>**Endpoint Name:** SUSPEND_CART<br>**Integration Type:** HTTP_POST                                                                                                                                                    |
| Register Crashes     | Provides real-time details of register crashes, covering: relevant app, device, and store information such as version numbers, OS, device model, store and register IDs, installation ID, environment, and region.<br><br>**Endpoint Name:** POS_CRASH_DATA<br>**Integration Type:** HTTP_POST                                                       |
| Register Vitals      | Provides real-time details of register vitals, covering: network connectivity, associate sign-in/out, peripheral device status and connectivity, order syncs, and offline data feed syncs.<br><br>**Endpoint Name:** POS_VITALS<br>**Integration Type:** HTTP_POST                                                                                   |
| Monitor Integrations | Provides real-time monitoring of integration health, covering: SPI and webhook errors (HTTP 4xx/5xx), latency threshold breaches, and overall performance issues.<br><br>**Endpoint Name:** EXPORT_MONITORING_EVENTS<br>**Integration Type:** HTTP_POST or HTTP_PUT                                                                                  |

## Frequently Asked Questions (FAQs)

**The API spec schema indicates that dates are represented with an integer data type. What is the expected date format we should use when passing dates to the API? Additionally, can you provide a sample date along with its transformed value as an example?**

Dates are expected in epoch times, represented as integers (measured in milliseconds). Epoch time is the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC. See example:

- Example Date: 2023-01-15 08:30:00
- Epoch Time (in milliseconds): 1642246200000

See example with `currentLoyaltyProfile.currentTier.expiryDate`:

```json
"loyaltyProfile": {
  "currentTier": {
    "expiryDate": 1703782830000
  }
},
```

**Can Multi-Region Feeds Be Managed Through the Product API?**

<!-- Paul (8-19-25) Have to fix the link in the following paragraph, commenting out for now:

The platform supports Multi-Region Feeds ../feeds/multi-region-feeds.md, allowing the master region to run the product feed while enabling other countries to inherit the product metadata, with specific pricing and sizing data provided for each country. However, this capability doesn't extend directly through the Product API. -->

The platform supports Multi-Region Feeds, allowing the primary region to run the product feed while enabling other countries to inherit the product metadata, with specific pricing and sizing data provided for each country. However, this capability doesn't extend directly through the Product API.

- For Multi-Region Pricing Updates: There's no dedicated pricing API. For multi-region operations, pricing updates must be conducted through the CMS feed mechanism, allowing for regional-level adjustments.

- For Single-Region Pricing Updates: In a single-region setup, the Product API can update pricing information. However, for multi-region scenarios, the Product API lacks a `region` field in its specifications (as observed in this guide).

- Workaround for Pricing Updates: Given the absence of a pricing API, pricing information must be included within POST and PUT calls when managing product data. If operating with a single instance per region, the Product API can facilitate pricing updates effectively.

**Do you offer GraphQL for precise querying?**

GraphQL isn't available externally. It's used exclusively for the POS app and CMS, and isn't accessible to customers via the API specification.

**How can I search by credit card number using the search order SPI?**

To search by credit card number using the search order SPI, map the card number to the appropriate fields in the payload. Include the card number under the payment card section. HotWax then reads this information, searches for orders, and returns the results.

**Does Point of Sale support query parameters for all SPIs?**

No, Point of Sale doesn't support dynamically populating query parameters. However, you can set up endpoints with static query parameters.

When Point of Sale calls an endpoint, it uses the provided URL exactly as configured. This means that merchants can receive the configured locale (for example, `cb-en-us`) and store type (for example, `stores`) as part of the URL. No special handling or logic is applied to these static query parameters — the URL is called as-is.

If merchants are comfortable with the static nature of the query parameters, they can configure them accordingly. This allows them to add conditional processing on their side. Additionally, merchants can use static query parameters to receive authentication codes.

**note:** Dynamically populating query parameters isn't supported.

**For all SPIs, when error fields are returned with a 200 HTTP response code, should non-nullable fields still be included in the response? For example, in the customer detail API response, the `loyaltyProfile` field is not nullable and the `profile` field, while nullable, is required. Please confirm the expected behavior.**

Non-nullable fields or any fields not needed in the response should be left out of the response entirely. Instead of inserting a null value for any field not being passed, exclude the field from the response.

**In scenarios where a resource is not found and you'd normally return a 404 status, should you return a 200 with error fields populated instead? For instance, if an associate tries to look up a return item based on a registry ID, and the registry ID is invalid, should you return a 200 with an error message instead of a 404?**

If returning a 200 status code in a scenario with an empty result string and an error message, Point of Sale displays no results and the error message. If returning a 400 status code, a generic error message is displayed in the app, and the specific error message is captured in the logs.

**What is the expected response payload for the order webhook when the status code indicates success? What HTTP status code should I return, and what values should be included in the response fields as indicated in the Swagger documentation?**

The current schema doesn't indicate any required fields. As of now, only a status code response is expected.

**If the Address SPI is set up, does the POS always trigger the endpoint and disregard the data in the customer SPI addressList object?**

The POS uses the `POST` address SPI (`CREATE_CUSTOMER_ADDRESS`) to add an address from the cart's **Select Shipping Address** screen. Once the address is added, the POS relies on the `addressList` provided by `CREATE_CUSTOMER_ADDRESS` for the checkout process.

**What triggers an Order to flow into the Repost Failed Webhook Report?**

An order is categorized as a failure and appears in the Repost Failed Webhook report if specific criteria are met during the order export process:

1. **HTTP Response Status Code:** The order export fails if the HTTP response status code is in the 4xx or 5xx range, indicating a client or server error.
2. **HTTP Response Payload:** Even with a successful HTTP status code in the 2xx range, the order export is still considered a failure if the response payload includes either or both of these attributes:
   - `errorMessage`
   - `errorCode`
   - **Example:** If the HTTP status code is 200, but the payload contains an error message like the following, the order is marked as a failure:

**Is the eReceipt webhook queued in offline mode so that it can be sent once the POS returns to online mode?**  
The eReceipt webhook is triggered when the app calls the eReceipt API. No emails are sent when an order is synced. However, if automatic receipt emails are configured in the store settings, eReceipts are sent for all orders, even in offline mode. Currently, no customer has automatic receipt emails enabled.

**What happens if automatic eReceipts are enabled in offline mode?**  
If automatic eReceipt emails are configured, the system generates and sends eReceipts during offline sync for every transaction. In this case, remove the email CTA from the order confirmation layout.

**Which settings should be enabled to ensure eReceipts are sent automatically in both online and offline modes?**  
Enable these settings in CMS:

- `sendOrderConfirmationEmailAutomatically`
- `sendRefundEmailAutomatically`
- `HideReceiptEmailShare`

**note:** There's no option to send an email only when requested by the customer in offline mode once these settings are enabled.

<!-- document id=c93d5215a33531fbf0036945aca0765f3efb3a0d0f911eb0d0fa9d473ad5b2c3 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/data-exports.md -->

# Point of Sale Data Exports

Get details of the events that Point of Sale can stream.

## Orders/Transactions

Data Artifact: POS Transactions

Integration Patterns supported: Webhook / API export, SFTP (XML), Connector to SF OM, Connector to NetSuite.

Examples of events supported:

- Order created
- Order canceled
- Order returned
- Payment captured
- Payment refunded

This table lists the request webhook details for different transaction scenarios:

<table>
<col />
<col />
<thead>
  <tr>
    <th>
      Transaction
    </th>
    <th>
      Webhook Request
    </th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>
      Sale
    </td>
    <td>
      Single post for sale event
    </td>
  </tr>
  <tr>
    <td>
      Return
    </td>
    <td>
      Single post for a return event
    </td>
  </tr>
  <tr>
    <td>
      Exchange
    </td>
    <td>
      <p>
        1. Single post for return event on old order
      </p>
      <p>
        1. Single post for a sale event on new order
      </p>
    </td>
  </tr>
</tbody>
</table>

**tip:** Failed webhooks can be reposted in CMS by going to **Reporting** and **Analytics** | **Repost Failed Webhook Events**.

## Inventory Management

Data Artifact: Inventory Movements

Integration Patterns supported: SFTP (CSV / TSV), Webhook is on the roadmap.

Examples of events supported:

- ASN Receiving, Store to Store Transfer, Corp Transfer

## Customers

Data Artifact: Not Applicable (customer profiles not stored in Point of Sale)

Integration Patterns supported: API, we have a pre-built connector to SFSC / SFCC / Netsuite to use these systems as Master of Record for customer data.

Examples of events supported:

- Customer created
- Customer updated
- Customer search

## Store Ops (Sales Audit, Loss Prevention, Financial Reconciliation)

Data Artifact: Electronic Journal

Integration Patterns supported: SFTP (CSV / TSV)

Examples of events supported:

- Login
- Bank deposit
- Cash drawer open

<!-- document id=233de1dd691c13e616c3c5f98e45d44d54f161e60a16d1691c951294fb105405 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/retail-cloud-api-developer-guide.md -->

# Point of Sale Developer Guide for Non Hyperforce Users

Invoking Point of Sale APIs is a two-step process. This topic describes the steps and includes sample responses.

For a comprehensive list of APIs and SPIs, see [Point of Sale API Specifications](https://developer.salesforce.com/docs/commerce/retail-cloud/references/about-retail-cloud-api/about.html).

**note:** In 2024, Salesforce acquired PredictSpring, a provider of modern retail point-of-sale (POS) software built natively in the cloud. PredictSpring was renamed Retail Cloud and is now called Point of Sale. You may still see references to PredictSpring or Retail Cloud in the Point of Sale app and in our documentation (for example, in API header names).

## API Keys

Find the keys needed to use Point of Sale APIs in CMS by going to **Advanced > Merchant Configuration > Developer Credentials**.

<!--For more information, please refer to Merchant Configurations ../../third-party-connectors/general-guides/managing-merchant-configuration-api-integration.md.

Paul DiSabito (7/31/2025): Commenting out this link for now. It looks like the target content will be moved to a DITA file, rt_adv_config_pay_gate_merch_config.xml -->

![predictspring-api-developer-guide-sc1.png](https://developer.salesforce.com/docs/media/retail-cloud/predictspring-api-developer-guide-sc1.png)

## Base URL

- Staging API Base URL: <https://api.predictspring.com/staging/service>
- Production API Base URL: <https://api.predictspring.com/prod/service>
- Staging OAuth2 URL: <https://staging-oauth2.predictspring.com/oauth2/token>
- Production OAuth2 URL: <https://prod-oauth2.predictspring.com/oauth2/token>

## API Inbound Rate Limits

- Production: 10 requests per second and 100,000 requests per month.
- Staging: 10,000 requests per month.

For additional API volume, contact Salesforce Customer Support.

## Configuration and Setup

To use Point of Sale APIs, complete a two-step authentication process. First, obtain an OAuth token. Then, use that token to make API calls.

### Step 1: Get OAuth token

```bash
curl -X POST \
  '<OAuth2 URL>?grant_type=client_credentials' \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Authorization: Basic <BASE64 ENCODED ClientID:ClientSecret>' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Content-Length: ' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache'
```

Sample Response:

```json
{
  "access_token": "<access token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}
```

Extract the access token value. This token is required for Step 2 to invoke the Point of Sale API.  
The token is valid for the expiry period as specified in `expired_in` in seconds.

Pass the access token as **PredictSpring-Token** when invoking the Point of Sale API.

### Step 2: Invoke API

**note:** Make sure that Content-Type is set to `application/json` in all the requests.

Invoke Point of Sale API with the below headers:

1. PredictSpring-Secret (this is an encrypted string you get from Point of Sale)
2. PredictSpring-Token
3. X-api-key
4. Content-Type: application/json

**note:** x-api-key is the **Merchant API Key** in the UI.

Here's a sample request to create promotions in a **staging** environment.

```bash
curl -X POST \
  https://api.predictspring.com/staging/service/merchant/v1/promotions \
  -H 'Content-Type: application/json' \
  -H 'PredictSpring-Secret: <PredictSpring-Secret>' \
  -H 'PredictSpring-Token: <Access-Token>' \
  -H 'x-api-key: <x-api-key>' \
  -d '{
    "hasSingleUsePromoCodes": false,
    "active": true,
    "promotionType": "ORDER_AMOUNT_OFF",
    "name": "Special Promo",
    "amountOff": 0.99,
    "title": "Special Promo for you!",
    "description": "Special promo test",
    "imageUrl": "<image url>",
    "startTimeStamp": 1567321200000,
    "endTimeStamp": 1567494000000,
    "merchantPromotionId": "ext-special-promo-1",
    "auto": true,
    "redemptionLimit": 1,
    "rules": [
        {
            "promotionRuleType": "PRODUCT",
            "operator": "INCLUSIVE",
            "value": [
                "1366160159739842"
            ]
        },
        {
            "promotionRuleType": "CATEGORY",
            "operator": "INCLUSIVE",
            "value": [
                "Clothing"
            ]
        },
        {
            "promotionRuleType": "PRODUCT",
            "operator": "EXCLUSIVE",
            "value": [
                "1366160159794742"
            ]
        }
    ],
    "channel": [
        "APP",
        "STORE",
        "OUTLET"
    ],
    "combinationTypes": [
        "ORDER_PERCENT_OFF",
        "ORDER_AMOUNT_OFF",
        "FREE_SHIPPING",
        "BOGO",
        "FREE_SAMPLES",
        "PRODUCT_FIXED_AMOUNT",
        "X_FOR_Y"
    ]
}'
```

<!-- document id=941a91fa00f35cfa05e42be4f477152c783a504b783d41205a27ec39c0ec37c0 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/retail-cloud-spi-error-handling.md -->

# Point of Sale SPI Error Handling

In case of an error, the APIs should return an error response in JSON format consisting of error code and error message. Supported error types for each of the SPI APIs are outlined in the following sections. Also, the HTTP response status code for all error responses should be set accordingly.

Valid Error Responses - Error messages should be i18n version of the string based on region and local of the app request.

HTTP/1.1 400 Exception Condition

## Account

```json
{
  "errorType": "CREATE_ACCOUNT_FAILURE",
  "errorMessage": "USer Registraion failed"
}

{
  "errorType": "INVALID_LOGIN",
  "errorMessage": "Invalid Credentials"
}

{
  "errorType": "SESSION_EXPIRED",
  "errorMessage": "User session expired"
}

{
  "errorType": "UPDATE_ACCOUNT_FAILURE",
  "errorMessage": "Updating user account failed"
}
```

## Cart

```json
{
  "errorType": "PRODUCT_UNAVAILABLE",
  "errorMessage": "{ProductID} : Product 1234567890 is unavailable"
}

{
  "errorType": "CART_CREATE_FAILURE,
  "errorMessage": "Cart creation failed due to {}"
}

{
  "errorType": "CART_READ_FAILURE",
  "errorMessage": "Cart {} could not be retrieved"
}
```

## Checkout

```json
{
  "errorType": "INVALID_COUPON_CODE",
  "errorMessage": "Invalid coupon code"
}

{
  "errorType": "SHIPPING_TO_COUNTRY_NOT_ALLOWED",
  "errorMessage": "Cannot ship to country {CountryName}"
}

{
  "errorType": "CHECKOUT_FAILURE",
  "errorMessage": "Checkout failure due to {}"
}

{
  "errorType": "BILLING_TO_COUNTRY_NOT_ALLOWED",
  "errorMessage": "Cannot bill country {}"
}

{
  "errorType": "CARD_VALIDATION_FAILURE",
  "errorMessage": "Credit card validation failed"
}

{
  "errorType": "PAYMENT_NOT_AUTHORIZED",
  "errorMessage": "Credit card authorization failed"
}

{
  "errorType": "INVALID_SHIPPING_ADDRESS",
  "errorMessage": "Invalid shipping address. Please correct {}"
}

{
  "errorType": "INVALID_BILLING_ADDRESS",
  "errorMessage": "Invalid billing address. Please correct {}"
}

{
  "errorType": "MULTIPLE_PROMO_CODE",
  "errorMessage": "Multiple promotion codes not allowed. Please correct {}"
}
```

## Clienteling

```json
{
  "error": true,
  "errorCode": 400,
  "errorMessage": "Segment is not valid"
}
```

## General Catch All

```json
{
  "errorType": "SERVER_EXCEPTION",
  "errorMessage": "Server unavailable. Please try again later"
}
```

<!-- document id=40bc61fbb2597738331fea328dc3830b137faf3d7814a85622e1bff23bd1edb6 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-poll-status.md -->

# Poll Checkout Status

Check the current status of an ongoing checkout process.

**Endpoint:** GET [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)

**When to use:**

- After receiving 202 response from PUT or PATCH requests
- Before proceeding to the next checkout step
- To verify all calculators completed successfully

**Response codes:**

- 200 OK – Processing complete, data ready
- 202 Accepted – Still processing, continue polling
- 422 Unprocessable Entity – Calculator failure, check error details

<!-- document id=7496ea7c0f623203e6779c99b735ac0a882c6be2c591a3bda4709d101722f2cb url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/pos-oas.md -->

POS API (Full Specification)

# POS API (Full Specification)

**Partial reference:** 10 operation(s) were omitted because their source references could not be resolved.

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/pos-oas/pos-oas-public.yaml)

Full API specification for Point of Sale (POS) APIs, SPIs, and webhooks. This monolithic specification includes all endpoints for managing retail operations including inventory, orders, customers, promotions, and integrations.

**Version:** 2.3.4

## Tags

### CMS User Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cms-user-management-api/cms-user-management-api-oas-public.yaml)

Merchant API to create, search, update, and delete CMS users from the POS system.

### Mask Customer Data

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/mask-customer-data/mask-customer-data-oas-public.yaml)

Request to mask customer data by email or customer ID identifiers.

### Customer API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/customer-api/customer-api-oas-public.yaml)

Merchant API to manage customer data in the POS system.

### Inventory Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-management-api/inventory-management-api-oas-public.yaml)

Merchant API to manage inventory in the POS system.

### Notification API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/notification-api/notification-api-oas-public.yaml)

POS Merchant API to upload notifications to be sent to target devices.

### Product Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/product-management-api/product-management-api-oas-public.yaml)

POS Merchant API to perform CRUD operations on Product objects in the POS system. The APIs do not support field mapping and transformation logic available in CMS.

### Promotion Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-management-api/promotion-management-api-oas-public.yaml)

POS Merchant API to perform CRUD operations on promotions in the POS system.

### Store Associate Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-associate-management-api/store-associate-management-api-oas-public.yaml)

POS Merchant API to create, search, update, and deactivate store associates from the POS system.

### Store Group Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-group-management-api/store-group-management-api-oas-public.yaml)

Store Group Management API to create, search, update, and delete store groups from the POS system.

### Store Product Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-product-management-api/store-product-management-api-oas-public.yaml)

POS Merchant API to manage store inventory.

### Fulfillment Order API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/fulfillment-order-api/fulfillment-order-api-oas-public.yaml)

APIs for in-store fulfillment of orders (BOPIS, BOFIS, ROPIS) imported into the POS from other channels.

### Order Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/order-management-api/order-management-api-oas-public.yaml)

POS Merchant API to create, search, and retrieve orders from the POS system, and repost orders to external systems.

### Activation Code SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/activation-code-spi/activation-code-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to get activation codes and details.

### Cart Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-validation-spi/cart-validation-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations.

### Clienteling SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/clienteling-spi/clienteling-spi-oas-public.yaml)

Merchant SPI to create, search, and retrieve customers from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in Point of Sale (POS) CMS for the POS to use during clienteling operations. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

### Customer Address SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/customer-address-spi/customer-address-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to modify customer addresses.

### DateTimeSlot SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/datetimeslot-spi/datetimeslot-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to get delivery/pickup dates and time slots for applicable items in the order. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable delivery and pickup dates via their endpoint.

### Delivery Group SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/delivery-group-spi/delivery-group-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are configured in CMS so that the POS can use them during all cart operations to obtain the relevant delivery groups.

### Employee Verification SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/employee-verification-spi/employee-verification-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to verify employee status and details.

### EReceipt SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/ereceipt-spi/ereceipt-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send order eReceipts.

### Fiscal SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/fiscal-spi/fiscal-spi-oas-public.yaml)

Merchant SPI endpoints for fiscal integration. These are sample endpoints that provide specifications for merchants on how to implement fiscal API on their end and then configure them in CMS. The fiscal SPI enables Point of Sale to delegate fiscal operations (SALE, RETURN, LOGIN, LOGOUT, etc.) to a merchant-provided SI connector.

### Gift Card SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-card-spi/gift-card-spi-oas-public.yaml)

Merchant SPI to perform gift card operations via a customer-managed provider adapter. Enables retailers to integrate any gift card provider without Point of Sale engineering involvement.

APIs include balance check, card activation, loading funds, redemption, and void/reversal.

### Configuration

1.  **Store Management** > **Integration** > **Custom API Connectors** > **Create**
    *   **API KEY:** GIFT\_CARD\_SERVICE with authentication details and URL Base.
    *   All the APIs defined below will use this URL base; only the operation-specific path suffix will change.
2.  Set **Store Management** > **Integration** > **Gift Card** > **Service** to `SPI`
3.  **Store Management** > **Integration** > **Gift Card** > **PIN Setting** controls whether cardPin is required or optional in requests.

### Gift Registry SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-registry-spi/gift-registry-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for POS to perform Gift registry actions such as registry lookup, buy / return registry items.

Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**.

Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    
    *   **API Key:** `GIFT_REGISTRY`
    *   **API Endpoint:** Provide the common external endpoint for registry APIs, for example: [https://sample/external/endpoint/giftregistry](https://sample/external/endpoint/giftregistry)
2.  Under **JSON Config**:
    
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: `{"Content-Type":"application/json","client_id":"myClientId","client_secret":"myClientSecret"}`

Merchant to implement below APIs and use the same ending keyword for the individual APIs.

### Inventory Events SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-events-spi/inventory-events-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send inventory events data.

### Inventory Service SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-service-spi/inventory-service-spi-oas-public.yaml)

Implement this endpoint per the specification and configure it in CMS under _**CMS** > **Store Management** > **Integration** > **Custom SPI Connectors** > **Create**_.

Make sure the endpoint is created in CMS with the following details:

### 1\. SPI Config

*   **SPI Key:** INVENTORY\_SERVICE
*   **SPI Endpoint:** Enter the **base SPI URL** in CMS.
*   The SPI supports multiple operations by appending specific **verbs** to the base URL.

**Example:**

*   **Base SPI URL (Configured in CMS):** [https://your-base-url.com/inventoryService](https://your-base-url.com/inventoryService)
*   **Full SPI Endpoints (Handled by Merchant's System):**
    *   **Revert Reserved Inventory:** [https://your-base-url.com/inventoryService/revert](https://your-base-url.com/inventoryService/revert)

**Merchants must handle the full SPI URL (base + verb) in their system.**

### 2\. JSON Config

*   **Integration Type:** Not required
*   **JSON Headers:** Provide the necessary authentication headers.

**Example:**

```json
{
  "Content-Type": "application/json",
  "client_id": "yourClientId",
  "client_secret": "yourClientSecret"
}
```

### Inventory SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/inventory-spi/inventory-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get inventory for the provided products. These endpoints must be configured in the POS system so that the POS can use them to check inventory availability.

### Loyalty SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/loyalty-spi/loyalty-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send order details and get loyalty-related information.

### Order SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/order-spi/order-spi-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them during multiple scenarios like BORIS, BOPIS, BOFIS, and others.

### Promotion Code Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-code-validation-spi/promotion-code-validation-spi-oas-public.yaml)

Merchant SPI to validate promotion codes from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in POS CMS for the POS to use when applying promotion codes.

### Quote SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/quote-spi/quote-spi-oas-public.yaml)

Merchant SPI to search and retrieve quotes from external ERP/quote management systems. APIs include searching quotes, retrieving quote details, and verifying connectivity.

### Prerequisites

Enable these settings in **CMS** > **Store Management** > **Store Settings** > **Advanced**.

1.  **Quote Master of Record is external ERP system** - Set to true
2.  **Keep same Quote ID when quote is resumed as cart and then converted back to quote** - Set to true

### Configuration in CMS

1.  Go to **Store Management** > **Integration** > **Custom API Connectors** > **Create**.
    
    *   Set **API Key** to QUOTE\_SERVICE.
    *   Set **API Endpoint** to your base URL. For example, [https://your-system.com/api/quotes](https://your-system.com/api/quotes).
2.  Under **JSON Config**:
    
    *   Set **Integration Type** to HTTP\_POST.
    *   Set **JSON Headers:** `{"Content-Type":"application/json"}`

**Note:** For exporting quotes from POS to external systems, configure the **QUOTE\_EXPORT** webhook separately. The QUOTE\_EXPORT and QUOTE\_SERVICE endpoints should share the same domain for proper integration.

### Available Endpoints

*   **/search** - Search quotes from external system
*   **/{quoteId}** - Get a specific quote by ID
*   **/{quoteId}** - Delete a quote by ID (DELETE)
*   **/verify** - Verify SPI connectivity

### Quote Source Identification

Quotes created in POS will have a 'source' field indicating origin. External quotes from the merchant's system will be labeled accordingly in the POS quote list.

### Reward SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/reward-spi/reward-spi-oas-public.yaml)

Sample reward-related APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system.

### Shipment Spi

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipment-spi/shipment-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping options and shipping labels. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint.

### Shipping Method SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipping-method-spi/shipping-method-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping methods with respect to items and shipping address of a particular cart. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint.

### Tax Calculation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/tax-calculation-spi/tax-calculation-spi-oas-public.yaml)

Merchant SPI to calculate taxes for a transaction according to the rules defined in the tax engine of the merchant's system. APIs include tax calculation, getting tax exemptions, and downloading tax rates for offline transactions.

### Configuration

1.  **Store Management** > **Integration** > **Custom API Connectors** > **Create**
    *   **API KEY:** TAX\_SERVICE with authentication details and URL Base.
    *   All the APIs defined below will use this URL base; only the last keyword will change.
2.  Set **Store Management** > **Store Settings** > **Tax** > **valueAddedTaxEnabled** to `true` to enable VAT.

For more details, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html).

### Transaction SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/transaction-spi/transaction-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are based on lean payload and must be configured in the POS system. These endpoints are the best alternative to the 'Order SPI' as they are based on lean payload.

**Prerequisite:** Make sure that CMS is configured to support the lean input model by setting the property `enableTransactionExport` to `true` in the CMS configuration.

**CMS Configuration:** **CMS** > **Store Management** > **Store Settings** > **Advanced** > **Enable Transaction Export**

### Visual Search SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/visual-search-spi/visual-search-spi-oas-public.yaml)

Merchant SPI for visual product search powered by an external image recognition provider. Enables store associates to search products by photographing them with the POS device camera. The Retail Cloud backend forwards the image and search parameters to this SPI endpoint and expects matching product IDs in return.

### Warranty SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/warranty-spi/warranty-spi-oas-public.yaml)

Merchant SPI for warranty eligibility checks. Merchants implement this endpoint and configure it in CMS so the POS can retrieve eligible warranty products for merchandise items in the cart.

### Wishlist SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/wishlist-spi/wishlist-spi-oas-public.yaml)

Merchant SPI to perform wishlist operations via a customer-managed provider adapter. This SPI allows retailers to integrate any wishlist provider without Retail Cloud engineering involvement. APIs include get wishlist, add products, and remove products. The API returns product IDs only; POS enriches them with full details from Solr.

### POSCrashData Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/poscrashdata-webhook/poscrashdata-webhook-oas-public.yaml)

This API sends POS crash data to external systems.

### POSVitals Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/posvitals-webhook/posvitals-webhook-oas-public.yaml)

This API sends POS vitals to external systems.

### Cart Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/cart-events-webhook/cart-events-webhook-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system so that the POS can use them to send cart events data.

### Promotion Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-events-webhook/promotion-events-webhook-oas-public.yaml)

Sample API that demonstrates how to implement a webhook endpoint by the merchant's system. This endpoint is then to be configured in the Point of Sale (POS) CMS system, so that the POS platform can use it to send promotion lifecycle events' data (CREATE, UPDATE, and DELETE). The event type is indicated by the `promotionEventType` field in the payload.

### Quote Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/quote-events-webhook/quote-events-webhook-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the CMS system so that Salesforce POS can use them to send quote events data.

### Store Fulfillment Event Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-fulfillment-event-webhook/store-fulfillment-event-webhook-oas-public.yaml)

The specification to implement a webhook in the merchant's system to export store fulfillment events from the POS to the merchant's downstream system.

The store fulfillment events are listed below and are related to BOPIS and BOFIS orders:

1.  BOPIS Order
    
    1.  PACK: Order is ready and items are packed by store associate.
    2.  DELIVERED: Items are picked up by the pickup person.
    3.  CANCELED: Items are canceled by store associate.
2.  BOFIS Order
    
    1.  PACK: Order is ready and items are packed by store associate.
    2.  SHIPPED: Items are shipped by store associate from the store.
    3.  CANCELED: Items are canceled by store associate.

### Webhook Monitoring Event Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/webhook-monitoring-event-webhook/webhook-monitoring-event-webhook-oas-public.yaml)

The specification to implement a webhook in the merchant's system to export webhook monitoring events from Salesforce POS to the merchant's downstream system.

The Webhook Monitoring events are listed below and are related to Custom SPI and Webhook:

1.  Received Error
    
    1.  Webhook/SPI Response Error: Webhook/SPI response 4xx/5xx error.
    2.  Webhook/SPI Response contains errors: Webhook/SPI response contains error messages with 200 status code.
2.  Threshold Exceed
    
    1.  Webhook/SPI response timeout: Webhook/SPI response times out.
    2.  Webhook/SPI response time exceeded: Webhook/SPI response time exceeds latency config in Custom Webhook/SPI.

## Operations

### GET Get CMS users.

`GET /merchant/{version}/users`

Operation ID: `getUsers`. Tags: CMS User Management API.

Retrieve all CMS users.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### PUT Update a CMS user.

`PUT /merchant/{version}/users`

Operation ID: `updateUser`. Tags: CMS User Management API.

Update a CMS user. If the user is updated successfully, the successful response includes a list of all users. Otherwise, the response includes ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `EditUserRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### POST Create CMS users.

`POST /merchant/{version}/users`

Operation ID: `createUsers`. Tags: CMS User Management API.

Create CMS users. If the users are created successfully, the response includes all users. Otherwise, the response includes ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `CreateCMSUsersRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### DELETE Delete a CMS user.

`DELETE /merchant/{version}/users`

Operation ID: `deleteUser`. Tags: CMS User Management API.

Delete the provided CMS user. On successful deletion, the response includes a list of all remaining users. Otherwise, it contains ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `userId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### PATCH Update CMS users.

`PATCH /merchant/{version}/users`

Operation ID: `patchUsers`. Tags: CMS User Management API.

Update the CMS users in the request. If all users are updated successfully, the successful response includes a list of all users. Otherwise, the response includes ErrorMessage and ErrorCode corresponding to the failure.

**Limit:** 100 users per request.

Validation includes:

1.  Empty or null request
2.  Valid existing CMS users.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `UpdatesCMSUsersRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ListUserAccountsResponse`.
    

### GET Get CMS user.

`GET /merchant/{version}/users/{userId}`

Operation ID: `getUserByUserId`. Tags: CMS User Management API.

Retrieve CMS user details.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `userId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UserAccount`.
    

### POST Mask customer data.

`POST /merchant/{version}/customer/mask`

Operation ID: `maskCustomerData`. Tags: Mask Customer Data, Customer API.

Administrative API to mask specific customer data to satisfy CCPA/GDPR requirements. Customer records are identified by customer ID or email address, and PII fields are replaced with mask characters across all relevant data stores.

The following categories of customer data are masked:

*   **Names** — first name, last name, middle name, initials
*   **Contact information** — email addresses, phone numbers
*   **Addresses** — billing and shipping addresses, including street, city, state/province, ZIP/postal code, and country
*   **Demographic information** — gender, age, date of birth
*   **Payment information** — credit card numbers, card type, expiration dates, billing address
*   **Loyalty and consent** — loyalty enrollment data and related consents
*   **Identification numbers** — driver's license, national ID, and similar identifiers

Masking is applied across relational databases (MySQL), NoSQL databases (DynamoDB), caches (Redis), and data warehouses (Redshift). Object storage (S3) is covered by TTL policies.

Masking is asynchronous. The response returns a `requestId` and an `IN_PROGRESS` status. Use the request ID to poll for completion.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerMaskResponse`.
    

### PUT Cancel cycle count.

`PUT /merchant/{version}/ims/inventory/cyclecount/cancel`

Operation ID: `cancelCycleCount`. Tags: Inventory Management API.

Cancel the specified cycle count.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `CycleCountCancelRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountCancelResponse`.
    

### POST Create IMS ASN.

`POST /merchant/{version}/ims/inventory/asn`

Operation ID: `createASN`. Tags: Inventory Management API.

Create an ASN in the IMS system.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `AdvanceShippingNotice`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### POST Create full cycle count.

`POST /merchant/{version}/ims/inventory/cyclecount/full`

Operation ID: `createFullCycleCount`. Tags: Inventory Management API.

Create a full cycle count. The complete inventory of products in a store can only be counted through a full cycle count.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `FullCycleCountRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountResponse`.
    

### POST Create manual cycle count.

`POST /merchant/{version}/ims/inventory/cyclecount/manual`

Operation ID: `createManualCycleCount`. Tags: Inventory Management API.

Create a manual cycle count. The manual cycle count allows counting of a specific set of products.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ManualCycleCountRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountResponse`.
    

### POST Create partial cycle count.

`POST /merchant/{version}/ims/inventory/cyclecount/partial`

Operation ID: `createPartialCycleCount`. Tags: Inventory Management API.

Create a partial cycle count. Cycle count for a particular group of products that fall within a selected category, brand, or any other product attribute that is provided in the request.

**Note:** Provide version as v1.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `PartialCycleCountRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CycleCountResponse`.
    

### POST Upload notifications for target devices.

`POST /merchant/{version}/notifications`

Operation ID: `scheduleNotifications`. Tags: Notification API.

Schedule immediate notifications to be sent to specified target devices.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `MerchantNotificationResponse`.
    

### PUT Update products.

`PUT /merchant/{version}/products`

Operation ID: `updateProducts`. Tags: Product Management API.

Update products. The request must include all properties of the product along with properties to be modified.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ProductRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ProductResponse`.
    

### POST Create products.

`POST /merchant/{version}/products`

Operation ID: `addProducts`. Tags: Product Management API.

Create products. The request must include all properties of a product. Do not use this API to update existing products, as any updates using this API are not effective. Use the PUT API to update existing products.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ProductRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ProductResponse`.
    

### DELETE Delete products.

`DELETE /merchant/{version}/products`

Operation ID: `deleteProducts`. Tags: Product Management API.

Delete products. The request must contain variantGroupID and product IDs. Product IDs can be a single product ID or multiple product IDs separated by commas.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `variantGroupId` (query, string)
*   `productIds` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### PATCH Patch products.

`PATCH /merchant/{version}/products`

Operation ID: `patchProducts`. Tags: Product Management API.

Update products. The request can include any or all properties of a product. Full product details are not needed.

**Limit:** 100 products per request.

If all products are updated successfully, a successful response is returned. Otherwise, error details are provided.

Validation includes:

1.  Empty or null product list
2.  Valid existing product ID
3.  Invalid product class, product title length.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ProductRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ProductResponse`.
    

### GET Promotion management - get promotions

`GET /merchant/{version}/promotions`

Operation ID: `getPromotions`. Tags: Promotion Management API.

Retrieve promotions by ID, status, channel, or promotion code.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (query, string)
*   `active` (query, boolean)
*   `availableType` (query, string)  
    Allowed values: `EXPIRED`, `NOW`, `FUTURE`.
*   `channel` (query, string)
*   `promoCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of Promotion`.
    
    Array of `Promotion`.
    

### PUT Promotion management - Create or update promotion

`PUT /merchant/{version}/promotions`

Operation ID: `updatePromotion`. Tags: Promotion Management API.

The request must include all properties of a promotion for the upsert operation to succeed.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Promotion`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Promotion`.
    

### POST Create or update promotion.

`POST /merchant/{version}/promotions`

Operation ID: `addPromotion`. Tags: Promotion Management API.

Create or update a promotion. The request must include all properties of a promotion so that the upsert operation succeeds.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Promotion`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Promotion`.
    

### PATCH Update promotions.

`PATCH /merchant/{version}/promotions`

Operation ID: `patchPromotions`. Tags: Promotion Management API.

Update promotions. The request can include any property of a promotion, but must include the promotion ID so that the update can be performed.

**Limit:** 100 promotions per request.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `UpdatePromotionsRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UpdatePromotionsResponse`.
    

### GET Get promotion.

`GET /merchant/{version}/promotions/{promotionId}`

Operation ID: `getPromotion`. Tags: Promotion Management API.

Retrieve a promotion.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Promotion`.
    

### DELETE Delete promotion.

`DELETE /merchant/{version}/promotions/{promotionId}`

Operation ID: `deletePromotion`. Tags: Promotion Management API.

Delete a promotion.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### GET Download promotions report.

`GET /merchant/{version}/promotions/download/report`

Operation ID: `downloadPromotions`. Tags: Promotion Management API.

Download a report of promotions.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (query, string)
*   `active` (query, boolean)
*   `channel` (query, string)
*   `promoCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DownloadFileResponse`.
    

### GET Get promotion codes.

`GET /merchant/{version}/promotions/{promotionId}/supc`

Operation ID: `getOneTimePromotionCode`. Tags: Promotion Management API.

Retrieve a list of Single Use Promotion Codes (SUPC) in a promotion from the POS.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)
*   `promotionCode` (query, string)
*   `redeem` (query, boolean)
*   `start` (query, integer (int32))
*   `limit` (query, integer (int32))

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PageOneTimePromotionCodeResponse`.
    

### PUT Update one-time promotion codes.

`PUT /merchant/{version}/promotions/{promotionId}/supc`

Operation ID: `updateOneTimePromotionCode`. Tags: Promotion Management API.

Update the redemption status of SUPCs in a promotion that were redeemed by an external system.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)
*   `redeem` (query, boolean)

#### Request body

Media type: `application/json`. Schema: `UpsertOneTimePromotionRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OneTimeCodeDataUploadResult`.
    

### POST Insert one-time promotion codes.

`POST /merchant/{version}/promotions/{promotionId}/supc`

Operation ID: `insertOneTimePromotionCode`. Tags: Promotion Management API.

Create and send new valid SUPCs in a promotion to the POS system.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `UpsertOneTimePromotionRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OneTimeCodeDataUploadResult`.
    

### GET Retrieve promotions.

`GET /merchant/{version}/promotions/pagination`

Operation ID: `getPromotionsPagination`. Tags: Promotion Management API.

Retrieve a list of promotions based on the provided query parameters. The parameters include:

1.  `promotionId`: A query parameter to filter promotions by ID. (Optional)
2.  `active`: A query parameter to filter promotions by their active status. (Optional)
3.  `availableType`: A query parameter to filter promotions by their availability type. (Optional)
4.  `channel`: A query parameter to filter promotions by channel. (Optional)
5.  `promoCode`: A query parameter to filter promotions by promo code. (Optional)
6.  `start`: A query parameter with a default value of 0, indicating the starting point for pagination.
7.  `limit`: A query parameter with a default value of 200, indicating the maximum number of promotions to return.

**Note:** Due to API Gateway limitations, responses exceeding 10MB will result in a 500 error.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (query, string)
*   `active` (query, boolean)
*   `availableType` (query, string)  
    Allowed values: `EXPIRED`, `NOW`, `FUTURE`.
*   `channel` (query, string)
*   `promoCode` (query, string)
*   `start` (query, integer (int32))  
    Default: `0`.
*   `limit` (query, integer (int32))  
    Default: `200`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `GetPromotionsResponse`.
    

### POST Look up one-time promotion codes.

`POST /merchant/{version}/promotions/supc/lookup`

Operation ID: `oneTimePromotionCodeLookup`. Tags: Promotion Management API.

Return information about one-time promotion codes based on input codes. The maximum size of an input list is 100.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OneTimePromotionCodeLookupResponse`.
    

### POST Upload promotion by JSON file.

`POST /merchant/{version}/promotions/upload`

Operation ID: `uploadPromotionByJsonFile`. Tags: Promotion Management API.

Upload a promotion by JSON file. Refer to [Single-Use Promotion Code](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/single-use-promotion-code.html) for file specification.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `multipart/form-data`. Schema: `object`.

*   `File` (_FormDataBodyPart_)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PromotionFileUploadResponse`.
    

### PUT Create or update store associates.

`PUT /merchant/{version}/associates/bulk`

Operation ID: `bulkUpsertStoreAssociate`. Tags: Store Associate Management API.

Create or update a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. All mandatory fields are required for each associate being created or updated. If any non-mandatory field is set to null, it overwrites the existing data with null. Update and create validation rules are applied to each associate in the request. If all associates are created or updated successfully, a successful response is returned; otherwise, the response contains error messages corresponding to the failures. ErrorMessage and code are populated for validation failures. General Validation includes:

1.  Ensuring the associateList is not empty or null.
2.  Performing mobile configuration ID validation. Update Validation includes:
3.  Verifying that all associates to be updated exist in the system.
4.  Checking for mismatches between the number of updating associates and existing associates.
5.  Validating that all associate IDs in the update list exist in the system. Create Validation includes:
6.  Verifying that all associates to be created do not exist in the system.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `StoreAssociateBulkRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### POST Create store associates.

`POST /merchant/{version}/associates/bulk`

Operation ID: `bulkCreateStoreAssociate`. Tags: Store Associate Management API.

Create a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. All mandatory fields are required for each associate being created. If any non-mandatory field is set to null, it overwrites the existing data with null. If all associates are created successfully, a successful response is returned. Otherwise, the response contains an errorMessage and errorCode corresponding to the failure. ErrorMessage and code are populated for validation failures. Validation includes:

1.  Ensuring the associateList is not empty or null.
2.  Verifying that all associates to be created do not exist in the system.
3.  Performing mobile configuration ID validation.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `StoreAssociateBulkRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### PATCH Update store associates.

`PATCH /merchant/{version}/associates/bulk`

Operation ID: `bulkUpdateStoreAssociate`. Tags: Store Associate Management API.

Update a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. The update only requires the store associate ID field. Only the fields provided in the request are updated. If all associates are updated successfully, a successful response is returned. Otherwise, the response contains an errorMessage and errorCode corresponding to the failure. ErrorMessage and code are populated for validation failures. Validation includes:

1.  Ensuring the associateList is not empty or null.
2.  Verifying that all associates to be updated exist in the system.
3.  Checking for mismatches between the number of updating associates and existing associates.
4.  Validating that all associate IDs in the update list exist in the system.
5.  Performing mobile configuration ID validation.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `StoreAssociateBulkRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### GET Retrieve store associates.

`GET /merchant/{version}/associates`

Operation ID: `getStoreAssociates`. Tags: Store Associate Management API.

Retrieve active or inactive store associates based on query parameters storeId and associateId. Both query parameters are optional.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `storeId` (query, string)
*   `associateId` (query, string)
*   `active` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### PUT Update store associate.

`PUT /merchant/{version}/associates`

Operation ID: `updateStoreAssociate`. Tags: Store Associate Management API.

Update a store associate in the POS system. If the associate is updated successfully, the same associate details are returned. Otherwise, the response contains ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Associate`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### POST Create store associate.

`POST /merchant/{version}/associates`

Operation ID: `createStoreAssociate`. Tags: Store Associate Management API.

Create a store associate in the POS system. If the associate is created successfully, the same associate details are returned. Otherwise, the response contains ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Associate`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### DELETE Deactivate store associate.

`DELETE /merchant/{version}/associates`

Operation ID: `deleteStoreAssociate`. Tags: Store Associate Management API.

Deactivate a store associate from the POS system corresponding to the associateId query parameter. On successful deactivation, the active field on the associate is set to false, and the response contains the deactivated associate details. If unsuccessful, the response contains the ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `associateId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### GET Retrieve store associate.

`GET /merchant/{version}/associates/{associateId}`

Operation ID: `getStoreAssociate`. Tags: Store Associate Management API.

Retrieve store associate details by associateId.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `associateId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Associate`.
    

### GET Retrieve all store group prices.

`GET /merchant/v1/admin/storegroup`

Operation ID: `getAllStoreGroupPrices`. Tags: Store Group Management API.

Retrieve all store group prices.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `start` (query, integer (int32))
*   `limit` (query, integer (int32))

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PageStoreGroupResponse`.
    

### PUT Update store group price.

`PUT /merchant/v1/admin/storegroup`

Operation ID: `updateStoreGroupPrice`. Tags: Store Group Management API.

Update a store group price.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `StoreGroupRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

### POST Add store group price for product.

`POST /merchant/v1/admin/storegroup`

Operation ID: `addStoreGroupPrice`. Tags: Store Group Management API.

Add a store group price for a product.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `StoreGroupRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

### PATCH Update store group prices.

`PATCH /merchant/v1/admin/storegroup`

Operation ID: `patchStoreGroups`. Tags: Store Group Management API.

Update store group prices or other attributes. **Limit:** 100 store groups per request. The store groups in the request are updated in batch. Only if all store groups are updated successfully, a successful response is returned. Validation includes:

1.  Empty request
2.  Valid store group ID and product ID.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `UpdateStoreGroupsRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PageStoreGroupResponse`.
    

### GET Get store group price for product by productId and storeGroupId

`GET /merchant/v1/admin/storegroup/{storeGroupId}/{productId}`

Operation ID: `getStoreGroupPriceByStoreGroupIdProductId`. Tags: Store Group Management API.

API to get store group price for product by productId and storGroupId.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `storeGroupId` (path, string, required)
*   `productId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

### DELETE Delete store group price by storeGroupId and productId

`DELETE /merchant/v1/admin/storegroup/{storeGroupId}/{productId}`

Operation ID: `deleteStoreGroupPrice`. Tags: Store Group Management API.

API to delete store group price.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `storeGroupId` (path, string, required)
*   `productId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

### GET Retrieve store inventory.

`GET /merchant/{version}/storeproducts/inventory`

Operation ID: `getMultiStoreInventory`. Tags: Store Product Management API.

Return store inventory details for queried store and product ID. This API accepts multiple product IDs and store IDs in one call. - **productIds** (Required): Product IDs to search. Use commas to separate values. Number of IDs range is 0 to 20. - **storeIds**: Store IDs to search. Number of store IDs: 0 to 1000. Use commas to separate values. If empty or null, search in all stores by default.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `storeIds` (query, string)
*   `productIds` (query, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### PUT Update inventory.

`PUT /merchant/{version}/storeproducts/inventory`

Operation ID: `updateStoreInventory`. Tags: Store Product Management API.

Update store or ecommerce inventory of products.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of InventoryAdjustRequest`.

Array of `InventoryAdjustRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of InventoryAdjustResponse`.
    
    Array of `InventoryAdjustResponse`.
    

### POST Create inventory.

`POST /merchant/{version}/storeproducts/inventory`

Operation ID: `addStoreInventory`. Tags: Store Product Management API.

Create store or ecommerce inventory of products.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of InventoryAdjustRequest`.

Array of `InventoryAdjustRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of InventoryAdjustResponse`.
    
    Array of `InventoryAdjustResponse`.
    

### DELETE Delete store inventory.

`DELETE /merchant/{version}/storeproducts/inventory`

Operation ID: `deleteStoreInventory`. Tags: Store Product Management API.

Delete store inventory with last updated date older than the given date. This API deletes store inventory records that have not been updated for a long time.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `lastUpdated` (query, integer (int64))

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### GET Retrieve store inventory CSV.

`GET /merchant/{version}/storeproducts/inventory/{storeId}`

Operation ID: `getStoreInventory`. Tags: Store Product Management API.

Provide the URL for a CSV file containing store inventory. - **delimiter**: Optional query parameter that accepts two values: csv and tsv. - **fullInventory**: Optional (true/false) to get full inventory. Default is false. If fullInventory is false, inventory updates that happened in a day are provided.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `storeId` (path, string, required)
*   `delimiter` (query, string)  
    Default: `csv`.
*   `fullInventory` (query, boolean)  
    Default: `false`.
*   `useMapping` (query, boolean)  
    Default: `false`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DownloadResponse`.
    

### PUT Update store product details.

`PUT /merchant/{version}/storeproducts`

Operation ID: `updateStoreProducts`. Tags: Store Product Management API.

Update store product details including item's list price, sale price, quantity, and promo banner text.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of StoreProductDetails`.

Array of `StoreProductDetails`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of StoreProductUpdateResponse`.
    
    Array of `StoreProductUpdateResponse`.
    

### PATCH Update store product details.

`PATCH /merchant/{version}/storeproducts`

Operation ID: `patchStoreProducts`. Tags: Store Product Management API.

Update store product details. The request can include any or all details of the store inventory product. **Limit:** 100 store products per request.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of StoreProductDetails`.

Array of `StoreProductDetails`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreInventoryProductsUpdateResponse`.
    

### POST Create BOFIS order.

`POST /merchant/v1/sa/fulfillment/orders/bofis`

Operation ID: `createBofisOrder`. Tags: Fulfillment Order API.

Create a BOFIS order in the POS system and allocate inventory for store fulfillment.

#### Request body

Media type: `application/json`. Schema: `FulfillmentOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Create BOPIS order.

`POST /merchant/v1/sa/fulfillment/orders/bopis`

Operation ID: `createBopisOrder`. Tags: Fulfillment Order API.

Create a BOPIS order in the POS system and allocate inventory for store fulfillment.

#### Request body

Media type: `application/json`. Schema: `FulfillmentOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Cancel BOPIS Items.

`POST /merchant/v1/sa/fulfillment/orders/{bopisOrderId}/stores/{storeId}/bopis/cancel`

Operation ID: `cancelBopisItems`. Tags: Fulfillment Order API.

Cancels BOPIS items for a specific order and store.

#### Parameters

*   `bopisOrderId` (path, string, required)
*   `storeId` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `ExternalBopisCancellationRequest`.

#### Responses

*   **default** default response
    
    Media type: `application/json`. Schema: `FulfillmentEvent`.
    

### POST Create ROPIS order.

`POST /merchant/v1/sa/fulfillment/orders/ropis`

Operation ID: `createRopisOrder`. Tags: Fulfillment Order API.

Create a ROPIS order in the POS system and allocate inventory for store fulfillment.

#### Request body

Media type: `application/json`. Schema: `FulfillmentOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Create order.

`POST /merchant/{version}/sa/orders`

Operation ID: `createOrder`. Tags: Order Management API. **Deprecated**.

Use POST merchant/v3/sa/orders instead. Create order data based on customer order data in payload. This adds only into POS and does not proxy to external OMS services.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required)  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `CustomerOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### GET Retrieve order details.

`GET /merchant/{version}/sa/orders/{id}`

Operation ID: `getOrder`. Tags: Order Management API.

Retrieve order data based on order ID.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required)  
    Pattern: v1|v2.
*   `id` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### POST Repost orders.

`POST /merchant/{version}/sa/orders/repost`

Operation ID: `orderReposting`. Tags: Order Management API.

Repost orders to external system for a given list of order IDs. The order IDs must be provided in the request body in a JSON array format. The maximum number of order IDs that can be processed in a single request is limited to 100.

#### Parameters

*   `version` (path, string, required)  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `OrderRepostRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OrderRepostResponse`.
    

### POST Search and retrieve orders.

`POST /merchant/{version}/sa/orders/search`

Operation ID: `searchOrders`. Tags: Order Management API.

Search and retrieve orders based on input parameters.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required)  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `OrderSearchRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OrderSearchResponse`.
    

### POST Create order V3.

`POST /merchant/v3/sa/orders`

Operation ID: `createOrder_1`. Tags: Order Management API.

Create order in POS system. **Prerequisite:** Make sure that CMS is configured to support the lean input model by setting the property 'enableTransactionExport' to 'true' in the CMS configuration. **CMS Configuration:** **CMS** > **Store Management** > **Store Settings** > **Advanced** > **Enable Transaction Export**.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `ExternalTransaction`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Retrieve activation code.

`POST /merchant/spi/sample/endpoint/sa/activation/code/activation/code/from/external/system`

Operation ID: `getActivationCode`. Tags: Activation Code SPI.

Retrieve activation code from merchant's system based on provided input. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `ACTIVATION_CODE`
    *   **API Endpoint:** Provide the external endpoint to get activation code and details, for example: /merchant/spi/sample/endpoint/sa/activation/code
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"contentType": "application/json"} **Invoke:** The SPI is invoked during the order checkout flow or submit order only if the order has a product that needs population of activation code from the external service (i.e., **CMS** > **Product Class** > **Requires Activation Code via External Source is enabled**). **Response:** If the SPI has an empty response or error, the order checkout or submit order flow is not completed and the associate sees an error. For more details, refer to [Point of Sale SPI Error Handling](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-spi-error-handling.html)

#### Request body

Media type: `application/json`. Schema: `ActivationCodeRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ActivationCodeResponse`.
    

### POST Validate cart.

`POST /merchant/spi/sample/endpoint/sa/cartValidation`

Operation ID: `cartValidation`. Tags: Cart Validation SPI.

This SPI endpoint enables POS to send a cart to the merchant's external system for validation. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `CART_VALIDATION`
    *   **API Endpoint:** Provide the external endpoint to get the cart validation, for example: [https://sample/external/endpoint/cartValidation](https://sample/external/endpoint/cartValidation)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `*/*`. Schema: `ExternalCart`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CartValidationResponse`.
    

### GET Search and retrieve customers.

`GET /merchant/spi/sample/endpoint/sa/customers`

Operation ID: `searchCustomers`. Tags: Clienteling SPI.

Search and retrieve customers based on input parameters. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Parameters

*   `start` (query, integer (int32))  
    Default: `0`.
*   `count` (query, integer (int32))  
    Default: `20`.
*   `firstName` (query, string)
*   `lastName` (query, string)
*   `phone` (query, string)
*   `email` (query, string)
*   `id` (query, string)
*   `postalCode` (query, string)
*   `searchString` (query, string)
*   `countryCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SearchCustomersResponse`.
    

### PUT Update customer.

`PUT /merchant/spi/sample/endpoint/sa/customers`

Operation ID: `updateCustomer`. Tags: Clienteling SPI.

Update the existing customer. The existing customerId is provided under 'profile.customerId'. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Request body

Media type: `application/json`. Schema: `UpdateCustomerRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UpdateCustomerResponse`.
    

### POST Create customer.

`POST /merchant/spi/sample/endpoint/sa/customers`

Operation ID: `createCustomer`. Tags: Clienteling SPI.

Create customer based on customer data entered in POS. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Request body

Media type: `application/json`. Schema: `CreateCustomerRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CreateCustomerResponse`.
    

### GET Retrieve customer details.

`GET /merchant/spi/sample/endpoint/sa/customers/{customerId}`

Operation ID: `getCustomer`. Tags: Clienteling SPI.

Retrieve customer data based on customer ID. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html)

#### Parameters

*   `customerId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `GetCustomerResponse`.
    

### GET Retrieve customer address list.

`GET /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `getCustomerAddresses`. Tags: Customer Address SPI.

Retrieve a list of addresses for a customer by customer ID.

#### Parameters

*   `customerId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `GetCustomerAddressesResponse`.
    

### PUT Update customer address.

`PUT /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `updateCustomerAddress`. Tags: Customer Address SPI.

Update customer address by customer ID and address ID.

#### Request body

Media type: `application/json`. Schema: `UpdateCustomerAddressRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UpdateCustomerAddressResponse`.
    

### POST Add new customer address.

`POST /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `addCustomerAddress`. Tags: Customer Address SPI.

Add a new address for a customer.

#### Request body

Media type: `application/json`. Schema: `AddCustomerAddressRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `AddCustomerAddressResponse`.
    

### DELETE Delete customer address.

`DELETE /merchant/spi/sample/endpoint/sa/customer/address`

Operation ID: `deleteCustomerAddress`. Tags: Customer Address SPI.

Delete customer address by customer ID and address ID.

#### Parameters

*   `customerId` (query, string)
*   `addressId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DeleteCustomerAddressResponse`.
    

### POST Retrieve date-time slots.

`POST /merchant/spi/sample/endpoint/sa/datetime/slots/from/external/system`

Operation ID: `getDeliveryDates`. Tags: DateTimeSlot SPI.

Retrieve delivery or pickup dates and time slots from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `DATE_PICKER`
    *   **API Endpoint:** Provide the external endpoint
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `SpiDeliveryDatesRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiDateTimesResponse`.
    

### POST Retrieve delivery group list.

`POST /merchant/spi/sample/endpoint/sa/deliveryGroup`

Operation ID: `getDeliveryGroupList`. Tags: Delivery Group SPI.

Retrieve delivery group from merchant's system. This SPI also provides shipping options for each delivery group. This SPI is used by POS to get delivery groups corresponding to cart and is triggered if the cart has a delivery item. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `DELIVERY_GROUP`
    *   **API Endpoint:** Provide the external endpoint to get the delivery group, for example: [https://sample/external/endpoint/to/get/deliveryGroup/from/external/system/456709](https://sample/external/endpoint/to/get/deliveryGroup/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `*/*`. Schema: `SPIShipmentProcessorRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SPIShipmentProcessorResponse`.
    

### POST Receive eReceipt.

`POST /merchant/spi/sample/endpoint/sa/orderEmail`

Operation ID: `postReceipt`. Tags: EReceipt SPI.

Receive order's detail. Merchant must implement this endpoint per this specification and then configure it in CMS. See SA\_ORDER\_INTIMATION.

#### Request body

Media type: `application/json`. Schema: `EReceiptRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### POST Verify employee.

`POST /merchant/spi/sample/endpoint/sa/employee/verification/to/verify/employee/from/external/system`

Operation ID: `verifyEmployee`. Tags: Employee Verification SPI.

Verify employee details from merchant's system based on provided input. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `VERIFY_EMPLOYEE`
    *   **API Endpoint:** Provide the external endpoint to verify employee, for example: [https://sample.com/external/endpoint/to/verify/employee/from/external/system](https://sample.com/external/endpoint/to/verify/employee/from/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"contentType": "application/json"} **Response:** If response is NULL or empty, or has ErrorCode or ErrorMessage, employee verification fails. **Use Case:** If an employee makes the purchase, authenticate their details when they are added to the cart.

#### Request body

Media type: `application/json`. Schema: `EmployeeVerificationRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `EmployeeVerificationResponse`.
    

### POST Activate Gift Card

`POST /merchant/spi/sample/endpoint/spiGiftCard/activateGiftCard`

Operation ID: `activateGiftCard`. Tags: Gift Card SPI.

Activates a new or inactive gift card at the provider with the specified amount. Called when a store associate sells a new gift card or issues a refund to a new card (step 1 of a two-step flow). The response `cardNumber` should echo back the card number from the request. The `providerTransactionId` returned must be stored by the platform and passed back in any subsequent void request. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardActivateRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardActivateResponse`.
    

### POST Add Balance to Gift Card

`POST /merchant/spi/sample/endpoint/spiGiftCard/addBalance`

Operation ID: `addBalance`. Tags: Gift Card SPI.

Loads funds onto an existing active gift card. Used during gift card purchase (step 2 after activation) or when issuing a refund to an existing card. The `providerTransactionId` returned must be stored by the platform and passed back in any subsequent void request. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardAddBalanceRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardAddBalanceResponse`.
    

### POST Check Gift Card Balance

`POST /merchant/spi/sample/endpoint/spiGiftCard/checkBalance`

Operation ID: `checkBalance`. Tags: Gift Card SPI.

Checks the current balance and active status of a gift card. This single endpoint serves two platform operations:

*   **getBalance()** — platform reads `balance` and `cardNumber` from the response
*   **isInactive()** — platform reads `isActive` from the response The response must always include both `balance` and `isActive` so either operation can be served. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardBalanceRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardBalanceResponse`.
    

### POST Redeem Gift Card

`POST /merchant/spi/sample/endpoint/spiGiftCard/redeemGiftCard`

Operation ID: `redeemGiftCard`. Tags: Gift Card SPI.

Deducts funds from a gift card. Used for two scenarios:

*   **Payment tender** — deducts the requested amount during checkout
*   **Cash out** — platform validates the balance is at or below the configured threshold, then calls this endpoint with the full balance to bring the card to $0 On success (no errorCode), the full requested amount is redeemed. Partial redemption is not supported. The `providerTransactionId` is stored as the capture token and the `providerReferenceId` is stored as the requestId on the tender — both are required for reconciliation and void operations. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardRedeemRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardRedeemResponse`.
    

### POST Void Gift Card Transaction

`POST /merchant/spi/sample/endpoint/spiGiftCard/voidGiftCard`

Operation ID: `voidGiftCard`. Tags: Gift Card SPI.

Reverses a previous gift card operation (redeem or addBalance). Called when an order fails after a gift card charge was captured, or when an explicit reversal is needed. The `originalProviderTransactionId` in the request must match the `providerTransactionId` returned by the original operation so the provider can identify which transaction to reverse. The `amount` must match the `approvedAmount` from the original operation. The `providerReferenceId` returned is stored by the platform as the paymentReversalRequestId on the tender. On error, set `errorCode` and `errorMessage` inherited from SpiPSResponse and leave the data fields unset.

#### Request body

Media type: `application/json`. Schema: `SpiGiftCardVoidRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGiftCardVoidResponse`.
    

### GET Retrieve products for registry ID.

`GET /merchant/spi/sample/endpoint/giftregistry/{identifier}`

Operation ID: `getRegistryProducts`. Tags: Gift Registry SPI.

Retrieve the list of all products belonging to the particular registry ID. The list is available for the customer to select from. The identifier is the registryId, which is a path parameter.

#### Parameters

*   `identifier` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiRegistryDetailResponse`.
    

### POST Return gift registry product.

`POST /merchant/spi/sample/endpoint/giftregistry/returnRegistryItem`

Operation ID: `searchGiftRegistry`. Tags: Gift Registry SPI.

Retrieve a gift registry product based on the registryId, productId, and quantity passed in the request, which can be added to cart to initiate the NRR flow.

#### Request body

Media type: `application/json`. Schema: `ReturnRegistryRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiRegistryReturnResponse`.
    

### POST Search gift registries.

`POST /merchant/spi/sample/endpoint/giftregistry/searchRegistries`

Operation ID: `searchGiftRegistry_1`. Tags: Gift Registry SPI.

Fetch the list of gift registries from the external system based on the search criteria, allowing customers to select products from the registry to add to the order. Please provide one or more query parameters.

#### Request body

Media type: `application/json`. Schema: `SearchRegistryRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiGiftRegistryResponse`.
    

### POST Check inventory availability for zip code.

`POST /merchant/spi/sample/endpoint/product/zipcode/getAvailabilityInformation`

Operation ID: `checkInventoryAvailability`. Tags: Inventory SPI.

Check the external system for the availability of a given product against the provided zip code. The response is a single string, the availability text, and any other information related to the product. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `INVENTORY_BY_ZIPCODE`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/product/zipcode/getAvailabilityInformation](https://sample/external/endpoint/product/zipcode/getAvailabilityInformation)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `InventoryAvailabilityRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiInventoryAvailabilityResponse`.
    

### POST Check inventory overview for all stores and warehouses.

`POST /merchant/spi/sample/endpoint/product/getInventoryOverview`

Operation ID: `checkInventoryOverview`. Tags: Inventory SPI.

Check the external system for the availability of a given product. The response is shown on the existing inventory overview widget, showing availability for all stores. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `GET_PRODUCT_INVENTORY_OVERVIEW`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/inventory/from/external/system](https://sample/external/endpoint/to/get/inventory/from/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `InventoryOverviewRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiInventoryOverviewResponse`.
    

### POST Revert reserved inventory.

`POST /merchant/spi/sample/endpoint/sa/inventoryService/revert`

Operation ID: `revertInventory`. Tags: Inventory service SPI.

Reverts reserved inventory for specified products in a cart. - Used when payment fails or checkout doesn't complete to release reserved inventory. **Structure:** - **Base SPI Endpoint:** /merchant/spi/sample/endpoint/sa/inventoryService (Configured in CMS) - **Verb:** /revert (Handled by the merchant's system when making SPI calls) - **Full Endpoint:** /merchant/spi/sample/endpoint/sa/inventoryService/revert.

#### Request body

Media type: `application/json`. Schema: `ExternalCart`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Inventory SPI to Check Inventory count

`POST /merchant/spi/sample/endpoint/sa/inventory/to/check/inventory/from/external/system`

Operation ID: `checkInventory`. Tags: Inventory SPI.

The API is to check the external system for the availability of given products by checking their inventory count. Merchant API to receive the Product ID, the type of inventory check to be done (ONLINE or IN\_STORE), optionally Store ID, and the purpose of inventory check (AVAILABILITY).

#### Request body

Media type: `application/json`. Schema: `CheckInventoryRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiInventoryResponse`.
    

### POST Send cycle count events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/cycleCount`

Operation ID: `sendInventoryEventsData`. Tags: Inventory Events SPI.

Sends cycle count data to an external system. **Supported events:**

1.  CYC\_COUNT\_CREATED\_EVENT
2.  CYC\_COUNT\_STARTED\_EVENT
3.  CYC\_COUNT\_COMPLETED\_EVENT
4.  CYC\_COUNT\_CANCELED\_EVENT.

#### Request body

Media type: `application/json`. Schema: `CycleCountPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send inventory adjustment events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/inventoryAdjustment`

Operation ID: `sendInventoryEventsData_1`. Tags: Inventory Events SPI.

Sends inventory adjustment data to an external system. **Supported events:**

1.  INVENTORY\_ADJUSTMENT.

#### Request body

Media type: `application/json`. Schema: `InventoryAdjustmentPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send inventory transfer events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/inventoryTransfer`

Operation ID: `sendInventoryEventsData_2`. Tags: Inventory Events SPI.

Sends inventory transfer data to an external system. The inventory transfer types include: ASN, CORP\_TRANSFER, STORE\_TO\_STORE, BLIND\_RECEIVE, RETURN\_TO\_VENDOR. All related events will use this API. **Supported events:**

1.  ASN\_RECEIVED\_EVENT
2.  ASN\_PARTIALLY\_RECEIVED\_EVENT
3.  ASN\_RECEIVE\_COMPLETED\_EVENT
4.  ASN\_REJECTED\_EVENT
5.  BLIND\_RECEIVE\_STARTED\_EVENT
6.  BLIND\_RECEIVE\_PAUSED\_EVENT
7.  BLIND\_RECEIVE\_IN\_PROGRESS\_EVENT
8.  BLIND\_RECEIVE\_COMPLETED\_EVENT
9.  CTS\_TRANSFER\_STARTED\_EVENT
10.  CTS\_TRANSFER\_COMPLETED\_EVENT
11.  CTS\_TRANSFER\_CANCELLED\_EVENT
12.  CTS\_TRANSFER\_ERRORED\_EVENT
13.  STS\_TRANSFER\_STARTED\_EVENT
14.  STS\_TRANSFER\_COMPLETED\_EVENT
15.  STS\_TRANSFER\_SHIPPED\_EVENT
16.  STS\_TRANSFER\_RECEIVED\_EVENT
17.  STS\_TRANSFER\_CANCELLED\_EVENT
18.  STS\_TRANSFER\_ERRORED\_EVENT
19.  RTV\_CREATED\_EVENT
20.  RTV\_COMPLETED\_EVENT
21.  RTV\_SHIPPED\_EVENT
22.  RTV\_RECEIVED\_EVENT
23.  RTV\_CANCELLED\_EVENT
24.  RTV\_FAILLED\_EVENT.

#### Request body

Media type: `application/json`. Schema: `InventoryTransferPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send purchase order events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/purchaseOrder`

Operation ID: `sendInventoryEventsData_3`. Tags: Inventory Events SPI.

Sends purchase order data to an external system. **Supported events:**

1.  PO\_TRANSFER\_STARTED\_EVENT
2.  PO\_TRANSFER\_COMPLETED\_EVENT
3.  PO\_TRANSFER\_ERRORED\_EVENT.

#### Request body

Media type: `application/json`. Schema: `PurchaseOrderPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `InventoryWebhookResponse`.
    

### POST Send return inventory events data out

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/return`

Operation ID: `sendInventoryEventsData_4`. Tags: Inventory Events SPI.

Sends return inventory details to an external system.

#### Request body

Media type: `application/json`. Schema: `TransactionalReturnPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `TransactionalInventoryWebhookResponse`.
    

### POST Send sale inventory events data.

`POST /merchant/spi/sample/endpoint/sa/customer/inventory/sale`

Operation ID: `sendInventoryEventsData_5`. Tags: Inventory Events SPI.

Send sale inventory detail to external system.

#### Request body

Media type: `application/json`. Schema: `TransactionalSalePayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `TransactionalInventoryWebhookResponse`.
    

### POST Retrieve loyalty points earned.

`POST /merchant/spi/sample/endpoint/sa/getLoyaltyPoints`

Operation ID: `postReceipt_1`. Tags: Loyalty SPI.

Retrieve the loyalty points earned for the transaction. When placing an order, if the customer is enrolled in loyalty, this SPI returns the points that will be earned for the order. Merchant must implement this endpoint per this specification and then configure it in CMS.

#### Request body

Media type: `application/json`. Schema: `Cart`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SPILoyaltyPoints`.
    

### POST Order SPI to Export Return

`POST /merchant/spi/sample/endpoint/sa/orders/to/export/return/order/to/external/system`

Operation ID: `exportReturnOrder`. Tags: Order SPI.

The specification provides details for external endpoint to consume the POS return transaction. It also describes on how to configure an external endpoint in POS system to export the sale transaction to the external system. **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with following details

1.  Under **API Config**
    
    *   **API Key:** `RETURN`
    *   **API Endpoint:** Provide the external endpoint to get the order eg.[https://sample/external/to/export/return/order/to/external/system](https://sample/external/to/export/return/order/to/external/system)
2.  Under **JSON Config**
    
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the api. Headers can be Content-Type, Authorization attributes like clientId/password eg. {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}
    *   The endpoint with Oauth athorization is supported. For more details refer to documentation

**Use Case**: The endpoint will be used to post the return transaction to external system/OMS .

#### Request body

Media type: `application/json`. Schema: `CustomerOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `HttpResponse`.
    

### POST Export sale order.

`POST /merchant/spi/sample/endpoint/sa/orders/to/export/sale/order/to/external/system`

Operation ID: `exportSaleOrder`. Tags: Order SPI.

Export the POS sale transaction to an external endpoint. This specification provides details for the external endpoint to consume the POS sale transaction and describes how to configure an external endpoint in the POS system to export the sale transaction to the external system. Configure the endpoint in CMS under **CMS** > **Store Management** > **Integration** > **Custom Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **Endpoint Name:** `ORDER`
    *   **API Endpoint:** Provide the external endpoint to export the sale order, for example: [https://sample/external/to/export/sale/order/to/external/system](https://sample/external/to/export/sale/order/to/external/system)
    *   **API Authorization Key:** Provide the authorization key for the API
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type or Authorization attributes like clientId/password, for example: `{"Content-Type":"application/json","client_id":"myClientId","client_secret":"myClientSecret"}`
3.  The endpoint with OAuth authorization is supported. For more details, refer to documentation. **Use Case:** The endpoint is used to post the sale transaction to external system or OMS.

#### Request body

Media type: `application/json`. Schema: `CustomerOrder`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `HttpResponse`.
    

### GET Retrieve BORIS order.

`GET /merchant/spi/sample/endpoint/sa/orders/to/get/boris/order/from/external/system/{orderId}`

Operation ID: `getBorisOrder`. Tags: Order SPI.

Retrieve a specifically BORIS order from merchant's system in the form of CustomerOrder object. Make sure orderId is provided as a path parameter. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BORIS_GET_ORDER_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from an external system during BORIS flow for merchants that use POS.

****Note:**** For a BORIS order, if the customer initiates the return with an external or alternate receipt ID, this SPI is expected to return the POS Order ID in the field 'borisOrderId'. Either a full Order object is expected or just 'borisOrderId' in the response.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### GET Retrieve order.

`GET /merchant/spi/sample/endpoint/sa/orders/to/get/order/from/external/system/{orderId}`

Operation ID: `getOrder_1`. Tags: Order SPI.

Retrieve order from merchant's system in the form of CustomerOrder object. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `GET_ORDER_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from an external system during BORIS flow for merchants that use POS OMS as a master of record for in-store orders and external OMS as master of record for web orders.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `CustomerOrder`.
    

### POST Search orders.

`POST /merchant/spi/sample/endpoint/sa/orders/to/search/orders/from/external/system`

Operation ID: `searchOrders_1`. Tags: Order SPI.

Search orders from merchant's system based on provided filter criteria. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SEARCH_ORDERS`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample.com/external/endpoint/to/search/orders/from/external/system](https://sample.com/external/endpoint/to/search/orders/from/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To search orders in external system and show them in the order-history screen of POS.

#### Request body

Media type: `application/json`. Schema: `OrderSearchRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OrderSearchResponse`.
    

### POST Export POSCrashData.

`POST /merchant/spi/sample/endpoint/sa/posCrashData`

Operation ID: `exportPOSCrashData`. Tags: POSCrashData Webhook.

Export POSCrashData to external system.

#### Request body

Media type: `application/json`. Schema: `POSCrashDataRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export POSVitals.

`POST /merchant/spi/sample/endpoint/sa/posvitals`

Operation ID: `exportPOSVitals`. Tags: POSVitals Webhook.

Export POSVitals to external system.

#### Request body

Media type: `application/json`. Schema: `POSVitalsDto`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Validate promotion code.

`POST /merchant/spi/sample/endpoint/sa/promotionCodeValidation`

Operation ID: `validatePromoCode`. Tags: Promotion Code Validation SPI.

Validate a provided promotion code by checking its validity and returning the associated promotion ID. If the promotion code is valid, the response returns the corresponding promotion ID. If the promotion code is invalid, the response returns an empty promotion ID. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SUPC_PROMOTION_CODE_VALIDATION`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `PromoCodeValidationRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PromoCodeValidationResponse`.
    

### GET Get Quote Details

`GET /merchant/spi/sample/endpoint/quote/{quoteId}`

Operation ID: `getQuoteDetails`. Tags: Quote SPI.

Retrieve detailed information for a specific quote from the merchant's external ERP system. This API is called when a store associate views or resumes a specific quote in POS.

### Use Cases

*   View complete quote details including items, pricing, and customer information
*   Resume a quote to cart for editing or conversion to order
*   Retrieve quote information for reporting or analysis

### Request Parameters

*   **quoteId**: The ID of the quote to retrieve (required, path parameter)

**Response (GetQuoteResponse):**

*   **quote**: SavedCart object containing complete quote details
*   **quoteId**: Unique quote identifier
*   **externalQuoteId**: External system quote ID if different
*   **customerId**: Associated customer ID
*   **status**: Quote status (e.g., Suspended, Active)
*   **cartItemList**: List of items in the quote
*   **subTotal**: Subtotal amount
*   **tax**: Tax amount
*   **total**: Total amount
*   **createdTs**: Quote creation timestamp
*   **source**: Origin of the quote (e.g., "external", "pos")
*   **associateSessionId**: Session identifier for the associate

**Example Response:**

{
"status": "success",
"quote": {
"quoteId": "Q-001",
"externalQuoteId": "EXT-Q-001",
"customerId": "CUST-123",
"status": "Suspended",
"source": "external",
"cartItemList": \[
{
"productId": "PROD-456",
"quantity": 2,
"price": 49.99
}
\],
"subTotal": 99.98,
"tax": 8.00,
"total": 107.98,
"createdTs": 1701619200000
},
"associateSessionId": "session-123"
}

.

#### Parameters

*   `quoteId` (path, string, required)

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGetQuoteResponse`.
    

### DELETE Delete Quote

`DELETE /merchant/spi/sample/endpoint/quote/{quoteId}`

Operation ID: `deleteQuote`. Tags: Quote SPI.

Delete a quote from the merchant's external ERP system. This API is called when a store associate deletes a quote in POS.

### Use Cases

*   Delete a quote that is no longer needed
*   Remove expired or cancelled quotes
*   Clean up duplicate quotes

### Request Parameters

*   **quoteId**: The ID of the quote to delete (required, path parameter)

**Response (SpiPSResponse):**

*   **status**: success/failure
*   **statusMessage**: Descriptive message

**Example Response:**

{
"status": "success",
"statusMessage": "Quote deleted successfully"
}

.

#### Parameters

*   `quoteId` (path, string, required)

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Search Quotes

`POST /merchant/spi/sample/endpoint/quote/search`

Operation ID: `searchQuotes`. Tags: Quote SPI.

Search quotes from the merchant's external ERP system based on various criteria. This API is called when a store associate searches for quotes in POS.

### Use Cases

*   Search quotes created in POS that were exported to external system
*   Search quotes created on merchant's external website/system
*   Resume a quote to cart for updates

**Request Parameters (SpiQuoteRequest):**

*   **quoteId**: Search by specific quote ID
*   **customerId**: Filter by customer ID
*   **firstName/lastName/name**: Filter by customer name
*   **email**: Filter by customer email
*   **phone**: Filter by customer phone
*   **storeId**: Filter by store
*   **storeAssociateId**: Filter by associate who created the quote
*   **storeRegisterId**: Filter by register
*   **productId**: Find quotes containing this product
*   **quoteDateTimeStampStart/End**: Filter by date range (epoch ms)
*   **start**: Pagination offset (default: 0)
*   **limit**: Max results to return (default: 20)
*   **advanceSearchId**: For pagination across multiple pages
*   **source**: Filter quotes by origin (POS, EXTERNAL, ALL)

**Response (QuoteSearchResponse):**

*   **quoteList**: List of SavedCart objects representing quotes
*   **advanceSearchId**: Token for fetching next page of results

**Example Response:**

{
"status": "success",
"quoteList": \[
{
"quoteId": "Q-001",
"externalQuoteId": "EXT-Q-001",
"customerId": "CUST-123",
"status": "Suspended",
"source": "external",
"cartItemList": \[.\],
"subTotal": 99.99,
"createdTs": 1701619200000
}
\],
"advanceSearchId": "next-page-token"
}

.

#### Request body

Media type: `application/json`. Schema: `SpiQuoteRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiQuoteSearchResponse`.
    

### POST Look up rewards.

`POST /merchant/sample/endpoint/reward/lookup`

Operation ID: `lookupRewards`. Tags: Reward SPI.

Fetch the available rewards for a customer that can be applied as a tender. Reward lookup is done based on the customer account (CustomerId, Card Acquisition Token, etc.). Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `REWARD_LOOKUP`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/lookupRewards](https://sample/external/endpoint/lookupRewards)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `*/*`. Schema: `SpiRewardLookupRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiRewardLookupResponse`.
    

### POST Retrieve shipping label.

`POST /merchant/spi/sample/endpoint/sa/shipping/to/get/shippingLabel/from/external/system`

Operation ID: `getShippingLabel`. Tags: Shipment Spi.

Retrieve shipping label from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SHIPPING_LABEL`
    *   **API Endpoint:** Provide the external endpoint
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the shipping label from an external system during BOFIS fulfillment or Inventory Transfer flows.

#### Request body

Media type: `application/json`. Schema: `ShipmentSpiRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ShipmentLabelSpiResponse`.
    

### POST Retrieve shipping options.

`POST /merchant/spi/sample/endpoint/sa/shipping/to/get/shippingOptions/from/external/system`

Operation ID: `getShippingOptions`. Tags: Shipment Spi.

Retrieve shipping options from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SHIPPING_OPTIONS`
    *   **API Endpoint:** Provide the external endpoint
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the shipping options from an external system during BOFIS fulfillment or Inventory Transfer flows.

#### Request body

Media type: `application/json`. Schema: `ShipmentSpiRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ShipmentOptionSpiResponse`.
    

### POST Return applicable shipping methods.

`POST /merchant/spi/sample/endpoint/sa/shipping/methods`

Operation ID: `shippingMethods`. Tags: Shipping Method SPI.

Return applicable shipping options. This merchant-provided API takes in cart items that are marked for shipping or delivery, customerId, address, etc. as input and provides applicable shipping options. **Note:** Only the items marked for shipping or delivery are sent in the request. In-store or Pick Up Later items are not sent as part of this request.

#### Request body

Media type: `application/json`. Schema: `ShippingMethodsRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ShippingMethodsResponse`.
    

### POST Calculate tax.

`POST /merchant/spi/sample/endpoint/taxEngine/calculateTax`

Operation ID: `calculateTax`. Tags: Tax Calculation SPI.

Calculate the tax based on the rules defined in the merchant's system. The request includes a list of products, tax exemptions to be applied if any, and the addresses (originating and destination) so that the correct tax rates can be applied.

#### Request body

Media type: `application/json`. Schema: `SpiTaxCalculationRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiTaxResponse`.
    

### GET Download tax rates.

`GET /merchant/spi/sample/endpoint/taxEngine/downloadTaxRates`

Operation ID: `downloadTaxRates`. Tags: Tax Calculation SPI.

Download tax and VAT rates into the POS system. This integration enables POS to retrieve accurate tax and VAT rates for offline transactions. The SPI supports optional query parameters such as `countryCode`, `state`, `city`, and `postalCode`, which allow for precise tax rate retrieval. The expected response format is a plain string in CSV, containing the relevant tax and VAT rates. For more detailed information, including sample requests and responses, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html)

#### Parameters

*   `countryCode` (query, string)
*   `state` (query, string)
*   `city` (query, string)
*   `postalCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DownloadTaxRatesResponse`.
    

### POST Finalize tax submission.

`POST /merchant/spi/sample/endpoint/taxEngine/finalizeTaxSubmission`

Operation ID: `finalizeTaxSubmission`. Tags: Tax Calculation SPI.

Finalize the taxes applied to sale transactions. This is an optional SPI. It provides a list of products and applied taxes to the tax engine, and the orderId associated with the transaction.

#### Request body

Media type: `application/json`. Schema: `SpiTaxSubmissionRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### GET Retrieve tax exemptions.

`GET /merchant/spi/sample/endpoint/taxEngine/getTaxExemptions`

Operation ID: `getTaxExemptionList`. Tags: Tax Calculation SPI.

Retrieve the list of tax exemptions supported on the merchant's side. This is an optional SPI and applicable only for tax regions and not applicable for VAT. The following optional fields can be provided in the response: TaxClasses, CountryCode, State, City, and Postal Code, such that the tax exemption is applicable as per the provided values. For example: If a tax exemption is provided with State = CA, then that tax exemption is assumed to be applied only for CA state. If an exemption can be applied regardless of state, country, or particular tax class, these fields in the response don't need to be populated. We mark them as 'ANY' denoting it can be applied without any rules or restrictions.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiTaxExemptionResponse`.
    

### GET Verify tax engine.

`GET /merchant/spi/sample/endpoint/taxEngine/verify`

Operation ID: `verify`. Tags: Tax Calculation SPI.

Verify that the SPI Tax Engine is available and requests can be sent. If the verify API is implemented, it is checked when verifying the feed source for offline taxes. If it is not implemented, we let it pass through and try to download tax rates.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export transaction.

`POST /merchant/spi/sample/endpoint/sa/orders/transaction/to/export/sale/order/to/external/system`

Operation ID: `exportTransaction`. Tags: Transaction SPI.

Export the POS sale transaction to an external endpoint. This specification provides details for the external endpoint to consume the POS sale transaction. **Prerequisite:** Make sure to configure CMS setting mentioned below: **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `TRANSACTION`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/to/export/sale/order/to/external/system](https://sample/external/to/export/sale/order/to/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}
    *   The endpoint with OAuth authorization is supported. For more details, refer to documentation. **Use Case:** The endpoint is used to post the recent transaction to external system or OMS.

#### Request body

Media type: `application/json`. Schema: `ExternalTransaction`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `HttpResponse`.
    

### GET Retrieve BORIS transaction.

`GET /merchant/spi/sample/endpoint/sa/orders/transaction/to/get/boris/order/from/external/system/{orderId}`

Operation ID: `getBorisOrder_1`. Tags: Transaction SPI.

Retrieve a specifically BORIS order from merchant's system in the form of lean payload. Make sure orderId is provided as a path parameter. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BORIS_GET_TRANSACTION_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from an external system during BORIS flow for merchants that use POS.

****Note:**** For a BORIS order, if the customer initiates the return with an external or alternate receipt ID, this SPI is expected to return the POS Order ID in the field 'borisOrderId'. Either a full Order object is expected or just 'borisOrderId' in the response.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ExternalTransaction`.
    

### GET Retrieve transaction.

`GET /merchant/spi/sample/endpoint/sa/orders/transaction/{orderId}`

Operation ID: `getOrder_2`. Tags: Transaction SPI.

Retrieve order from merchant's system using lean payload. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `GET_TRANSACTION_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from merchant's system during return flow if merchant's system is master of record.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ExternalTransaction`.
    

### POST Warranty Lookup SPI

`POST /merchant/spi/sample/endpoint/sa/warranty`

Operation ID: `checkWarrantyEligibility`. Tags: Warranty SPI.

Checks warranty eligibility for merchandise items in the cart.

The POS sends cart context (store address, shipping address, customer profile, and merchandise items) to the merchant's warranty engine. The engine evaluates eligibility rules (jurisdiction, product category, loyalty tier, etc.) and returns a list of available warranty products.

Merchants must implement this endpoint per this specification and configure it in CMS under: **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**

Make sure to create the endpoint in CMS with following details

1.  Under **API Config**
    
    *   **API Key:** WARRANTY\_LOOKUP
    *   **API Endpoint:** Provide the external endpoint URL
2.  Under **JSON Config**
    
    *   **Integration Type:** HTTP\_POST
    *   **JSON Headers:** Provide the header for the api. Headers can be Content-Type eg.{"contentType": "application/json"}

**Invoke:** Called when the associate taps 'Check Warranties' on the POS cart screen. Only merchandise items are sent; warranty SKUs already in the cart are filtered out.

**Response:**

*   Return `eligibleWarrantyList` with warranty products when warranties apply
*   Return empty `eligibleWarrantyList` when no warranties apply
*   Return `errorMessage` and `errorCode` on failure (POS will surface the error)

**Notes:**

*   `warrantyProductId` must match a product in CMS configured with ProductClass rule WARRANTY\_SKU
*   `coveredProductIds` must reference `productId` values from the request's `cartItemList`
*   For CATEGORY\_BASED pricing (MVP), `quantity` should always be 1.

#### Request body

Media type: `application/json`. Schema: `SpiWarrantyCheckRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiWarrantyCheckResponse`.
    

### POST Send suspended cart information.

`POST /merchant/spi/sample/endpoint/sa/customer/cart/suspendCart`

Operation ID: `suspendCartWebhook`. Tags: Cart Events Webhook.

Send the cart details as payload to the external system whenever the cart is suspended on the app.

#### Request body

Media type: `application/json`. Schema: `CartPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Send voided cart information.

`POST /merchant/spi/sample/endpoint/sa/customer/cart/voidCart`

Operation ID: `voidCartWebhook`. Tags: Cart Events Webhook.

Send the cart details as payload to the external system when a void cart operation is done on the app.

#### Request body

Media type: `application/json`. Schema: `CartPayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Receive promotion lifecycle event details

`POST /merchant/spi/sample/endpoint/sa/customer/promotion/promotionExport`

Operation ID: `promotionExportWebhook`. Tags: Promotion Events Webhook.

Webhook to export promotion events (CREATE, UPDATE, DELETE) to the merchant's system. The payload contains the promotion details as a `PromotionWebhookPayload`. For all the events the `promotions` list is populated. The `promotionEventType` field indicates which lifecycle event occurred.

Merchants should implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details

1.  Under **API Config**
    
    *   **API Key:** This should be `PROMOTION_EXPORT`
    *   **API Endpoint:** Provide the external endpoint URL to receive the promotion payload
2.  Under **JSON Config**
    
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the headers for the API. Headers can include Content-Type, Authorization attributes like clientId/password eg. {"Content-Type":"application/json"}.

#### Request body

Media type: `application/json`. Schema: `PromotionWebhookPayload`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export quote details for email.

`POST /merchant/spi/sample/endpoint/sa/customer/quote/quoteEmail`

Operation ID: `eReceiptQuoteSPI`. Tags: Quote Events Webhook.

Export the quote details to merchants, and the merchant system sends the quote email to the customer. This SPI shares created Quote events to merchant's system for email. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `ERECEIPT_QUOTE`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `application/json`. Schema: `EReceiptQuoteRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export quote details.

`POST /merchant/spi/sample/endpoint/sa/customer/quote/quoteExport`

Operation ID: `quoteExportWebhook`. Tags: Quote Events Webhook.

Export the created or updated quote details. This webhook exports Quote events to merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `QUOTE_EXPORT`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `application/json`. Schema: `QuotePayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export BOFIS events.

`POST /merchant/webhook/sa/sample/endpoint/to/export/bofis/events/to/external/system`

Operation ID: `exportBofis`. Tags: Store Fulfillment Event Webhook.

Export BOFIS events from merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BOFIS_EXPORT`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `FulfillmentEvent`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export BOPIS events.

`POST /merchant/webhook/sa/sample/endpoint/to/export/bopis/events/to/external/system`

Operation ID: `exportBopis`. Tags: Store Fulfillment Event Webhook.

Export BOPIS events from merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BOPIS_EXPORT`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `FulfillmentEvent`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export webhook monitoring events.

`POST /merchant/webhook/monitoring/sa/sample/endpoint/to/export/webhook/monitoring/events/to/external/system`

Operation ID: `exportMessage`. Tags: Webhook Monitoring Event Webhook.

Export ExternalWebhookMonitoringMessage to merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `MONITORING`
    *   **API Endpoint:** Provide the external endpoint to receive the message
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST` or HTTP\_PUT.

#### Request body

Media type: `application/json`. Schema: `ExternalWebhookMonitoringMessage`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

## Schemas

### ListUserAccountsResponse

Payload that contains the list of CMS users.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `users` (_array of UserAccount_) List of CMS users.
*   `error` (_boolean_)

### EditUserRequest

*   `oldUserId` (_string_, required) The existing user ID.
*   `newUserId` (_string_, nullable) New user ID. Must be a valid Google account.
*   `role` (_string_, nullable) New Role.
*   `timeZoneId` (_string_, nullable) New timezone ID. Don't use a timezone abbreviation.  
    Example: `America/Los_Angeles`.
*   `userType` (_string_, nullable) New user type.  
    Allowed values: `GLOBAL`, `REGIONAL`. Example: `GLOBAL`.

### CreateCMSUsersRequest

Request payload to create the CMS users.

*   `userAccounts` (_array of UserAccount_) List of users for CMS account creation.

### UpdatesCMSUsersRequest

*   `userRequestList` (_array of EditUserRequest_)

### UserAccount

Payload that contains information about CMS user.

*   `userId` (_string_, required) User ID. Must be a valid Google account.
*   `merchantId` (_string_, required) Merchant ID.
*   `permissions` (_string_, nullable) User's permission in CMS in the JSON form.  
    Example: `{"role":"CMS POWER USER","permissions":[{"LAYOUTS":["EDIT"]},{"FEEDS":["EDIT"]}]}`.
*   `role` (_string_, nullable) User's role.  
    Default: `CMS POWER USER`.
*   `timeZoneId` (_string_, nullable) User's timezone ID. Don't use a timezone abbreviation.  
    Default: `UTC`. Example: `America/Los_Angeles`.
*   `userType` (_string_) User Type.  
    Allowed values: `GLOBAL`, `REGIONAL`. Default: `GLOBAL`.

### CustomerMaskResponse

*   `requestId` (_string_) Unique identifier for this masking request.  
    Example: `e7966181-88a6-4247-9261-0ef0f35eb336`.
*   `customerCount` (_integer (int32)_) Number of customer records included in the masking request.  
    Example: `2`.
*   `status` (_string_)
    
    Current status of the masking request.
    
    *   `IN_PROGRESS` — Masking is running asynchronously.
    *   `SUCCESSFUL` — All specified customer records have been masked.
    *   `FAILED` — Masking failed. See `errorCode` and `errorMessage` for details.
    
      
    Allowed values: `IN_PROGRESS`, `SUCCESSFUL`, `FAILED`.
*   `requestedOn` (_integer (int64)_) Unix timestamp (milliseconds) indicating when the masking request was submitted.  
    Example: `1746136132000`.
*   `errorCode` (_string_) Machine-readable error code. Present only when `status` is `FAILED`.  
    Example: `MISSING_ID`.
*   `errorMessage` (_string_) Human-readable error message. Present only when `status` is `FAILED`.  
    Example: `No customer identifier(s) provided`.

### CycleCountCancelRequest

*   `cycleCountId` (_integer (int64)_) Cycle count ID which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `spring-2023`.
*   `storeId` (_string_, required) Store ID corresponding to cycle count being canceled.  
    Example: `001`.

### CycleCountCancelResponse

*   `cycleCountId` (_integer (int64)_) Cycle count ID which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count which needs to be canceled. Note: Provide either of cycleCountId or externalReferenceId to cancel.  
    Example: `spring-2023`.
*   `storeId` (_string_, required) Store ID corresponding to cycle count being canceled.  
    Example: `001`.
*   `errorMessage` (_string_, read-only) If the cycle count request fails, a detailed error message is provided.
*   `errorCode` (_string_, read-only) If the cycle count request fails, an error code is provided.  
    Allowed values: `CYCLE_COUNT_ERROR`.

### AdvanceShippingNotice

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `asnType` (_string_) ASN Type.  
    Allowed values: `ORIGINAL`, `CANCELLATION`, `CANCEL_REISSUE`, `UNKNOWN`.
*   `shipmentId` (_string_) An identifier for the shipment referenced in the ASN.
*   `shippedTimestamp` (_integer (int64)_) The time that the shipment was shipped represented as milliseconds since epoch.
*   `shipment` (_Shipment_, required)
*   `lastProcessedById` (_string_, required) ID for the person or entity who processed this inventory transfer.
*   `lastProcessedByName` (_string_, required) Name for the person/entity who processed this inventory transfer.
*   `createdOn` (_string_) Inventory transfer created date.

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### FullCycleCountRequest

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.

### CycleCountResponse

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.
*   `errorMessage` (_string_, read-only) If the cycle count request fails, a detailed error message is provided.
*   `errorCode` (_string_, read-only) If the cycle count request fails, an error code is provided.  
    Allowed values: `CYCLE_COUNT_ERROR`.

### ManualCycleCountRequest

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.
*   `productIds` (_array of string_, required) List of product IDs applicable for manual cycle count for specific products.
    
    Each item: Product ID applicable for manual cycle count.
    

### PartialCycleCountRequest

*   `storeId` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `startTimestamp` (_string_, required) Cycle count start time in ISO-8601 format. The timestamp can include a timezone offset, for example: '2011-12-18T10:15:30+01:00'. If no timezone offset is provided, the value is assumed to be in UTC.  
    Example: `2011-12-18T10:15:30+01:00`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch, provide this status 2. **CANCELED**: To cancel the existing cycle count batch 3. **COMPLETED**: Once the batch is created in the POS system, the status becomes COMPLETED 4. **PREPARING**: Preparing the cycle count batch 5. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`.
*   `cycleCountId` (_integer (int64)_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.
*   `criteria` (_PartialCycleCountCriteria_, required)

### MerchantNotificationResponse

*   `statusMessage` (_string_)
*   `notificationJobId` (_string_)

### ProductRequest

*   `products` (_array of MerchantProduct_) List of products.

### ProductResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `products` (_array of MerchantProduct_, read-only) List of products.
*   `error` (_boolean_)

### Promotion

*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)
*   `promotionId` (_string_)
*   `name` (_string_)
*   `title` (_string_)
*   `description` (_string_)
*   `promoCode` (_string_)
*   `inStorePromoCode` (_string_)
*   `appPromoCode` (_string_)
*   `onlinePromoCode` (_string_)
*   `outletPromoCode` (_string_)
*   `promoFeedSource` (_FeedSource_)
*   `startTimeStamp` (_integer (int64)_)
*   `endTimeStamp` (_integer (int64)_)
*   `combinationTypes` (_array of string_)
*   `channel` (_array of string_)  
    Items: Allowed values: `ALL`, `WEB`, `APP`, `STORE`, `OUTLET`.
*   `priorityOrder` (_integer (int32)_)
*   `active` (_boolean_)
*   `auto` (_boolean_)
*   `redemptionLimit` (_number (double)_)
*   `uniqueCodeUrl` (_string_)
*   `redeems` (_number (double)_)
*   `barCodeType` (_string_)
*   `promotionType` (_string_)  
    Allowed values: `ORDER_PERCENT_OFF`, `ORDER_AMOUNT_OFF`, `FREE_SHIPPING`, `BXGY`, `FREE_SAMPLES`, `X_FOR_Y`, `PRODUCT_FIXED_AMOUNT`, `FREE_SHIPPING_V2`.
*   `percentOff` (_number (double)_)
*   `maxDiscountAmount` (_number (double)_)
*   `maxTotal` (_number_)
*   `amountOff` (_number_)
*   `shippingMethods` (_array of string_)
*   `hasSingleUsePromoCodes` (_boolean_)
*   `imageUrl` (_string_)
*   `discountedQuantity` (_integer (int32)_)
*   `freeSamples` (_array of CombinationGroup_)
*   `merchantPromotionId` (_string_)
*   `amount` (_number_)
*   `promoRules` (_array of PromotionRule_)
*   `qualifyingGroups` (_array of CombinationGroup_)
*   `discountedGroups` (_array of CombinationGroup_)
*   `amountExpression` (_string_)
*   `tierGroups` (_array of TierGroup_)
*   `discountedGroupProration` (_boolean_)
*   `promotionLanguageData` (_array of PromotionLanguageData_) Promotion attributes in additional languages.
*   `bxgyDiscountType` (_string_) Buy X Get Y discount types.  
    Allowed values: `PERCENT_OFF`, `AMOUNT_OFF`, `FIXED_PRICE`.
*   `createdBy` (_string_)
*   `createdOn` (_string (date-time)_)
*   `lastUpdatedOn` (_string (date-time)_)
*   `lastUpdatedBy` (_string_)
*   `promotionMappings` (_array of PromotionMapping_)
*   `isExternallyValidated` (_boolean_)
*   `promotionTypePriority` (_string_)  
    Allowed values: `FREE_SAMPLES`, `BXGY_FIXED_AMOUNT`, `X_FOR_Y`, `BXGY_AMOUNT_OFF`, `BXGY_PERCENT_OFF`, `PRODUCT_FIXED_AMOUNT`, `ORDER_AMOUNT_OFF`, `ORDER_PERCENT_OFF`, `FREE_SHIPPING_V2`, `FREE_SHIPPING`.
*   `promotionCode` (_PromotionCode_)

### UpdatePromotionsRequest

*   `promotions` (_array of Promotion_)

### UpdatePromotionsResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `promotions` (_array of Promotion_)
*   `error` (_boolean_)

### DownloadFileResponse

*   `status` (_string_)
*   `statusMessage` (_string_)
*   `fileName` (_string_)
*   `url` (_string (url)_)

### PageOneTimePromotionCodeResponse

*   `totalPages` (_integer (int32)_)
*   `totalElements` (_integer (int64)_)
*   `pageable` (_Pageable_)
*   `numberOfElements` (_integer (int32)_)
*   `first` (_boolean_)
*   `number` (_integer (int32)_)
*   `size` (_integer (int32)_)
*   `content` (_array of OneTimePromotionCodeResponse_)
*   `sort` (_Sort_)
*   `last` (_boolean_)
*   `empty` (_boolean_)

### UpsertOneTimePromotionRequest

*   `promotionCodes` (_array of PromotionCode_) List of one-time promotion entities.

### OneTimeCodeDataUploadResult

*   `unprocessedCodes` (_array of OneTimePromotionCodeUpsertVO_)
*   `totalProcessed` (_integer (int32)_)
*   `totalError` (_integer (int32)_)
*   `entriesUpdated` (_integer (int32)_)
*   `entriesInactive` (_integer (int32)_)
*   `errors` (_array of object_)
    *   `cause` (_object_)
        *   `stackTrace` (_array of object_)
            *   `classLoaderName` (_string_)
            *   `moduleName` (_string_)
            *   `moduleVersion` (_string_)
            *   `methodName` (_string_)
            *   `fileName` (_string_)
            *   `lineNumber` (_integer (int32)_)
            *   `nativeMethod` (_boolean_)
            *   `className` (_string_)
        *   `message` (_string_)
        *   `localizedMessage` (_string_)
    *   `stackTrace` (_array of object_)
        *   `classLoaderName` (_string_)
        *   `moduleName` (_string_)
        *   `moduleVersion` (_string_)
        *   `methodName` (_string_)
        *   `fileName` (_string_)
        *   `lineNumber` (_integer (int32)_)
        *   `nativeMethod` (_boolean_)
        *   `className` (_string_)
    *   `message` (_string_)
    *   `suppressed` (_array of object_)
        *   `stackTrace` (_array of object_)
            *   `classLoaderName` (_string_)
            *   `moduleName` (_string_)
            *   `moduleVersion` (_string_)
            *   `methodName` (_string_)
            *   `fileName` (_string_)
            *   `lineNumber` (_integer (int32)_)
            *   `nativeMethod` (_boolean_)
            *   `className` (_string_)
        *   `message` (_string_)
        *   `localizedMessage` (_string_)
    *   `localizedMessage` (_string_)
*   `processedFile` (_DataFeedFile_)

### GetPromotionsResponse

*   `totalCount` (_integer (int64)_) The total number of promotions available.
*   `promotions` (_array of Promotion_) A list of promotions returned in the response.

### OneTimePromotionCodeLookupResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `totalCount` (_integer (int32)_)
*   `oneTimePromotionCodeResponse` (_array of OneTimePromotionCodeResponse_)
*   `error` (_boolean_)

### FormDataBodyPart

*   `contentDisposition` (_ContentDisposition_)
*   `entity` (_object_)
*   `headers` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of string`.
    
*   `mediaType` (_MediaType_)
*   `messageBodyWorkers` (_MessageBodyWorkers_)
*   `parent` (_MultiPart_)
*   `providers` (_Providers_)
*   `formDataContentDisposition` (_FormDataContentDisposition_)
*   `simple` (_boolean_)
*   `name` (_string_)
*   `value` (_string_)
*   `content` (_object_)
*   `fileName` (_string_)
*   `parameterizedHeaders` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of ParameterizedHeader`.
    

### PromotionFileUploadResponse

*   `statuses` (_array of PromotionUploadStatus_) List of promotion status.
*   `successCount` (_integer (int32)_) Number of successfully uploaded promotions.
*   `count` (_integer (int32)_) Number of total promotions.

### StoreAssociateBulkRequest

*   `associateList` (_array of Associate_, required) List of associates to create, update, or upsert in the POS System. This list must contain at least 1 associate and no more than 100 associates.  
    Minimum items: 1. Maximum items: 100.

### StoreAssociateSearchResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `storeAssociates` (_array of Associate_) List of the store associates. It can have a single associate, the associates from a store, or all associates.
*   `error` (_boolean_)

### Associate

Store associate.

*   `storeAssociateID` (_string_) ID of the store associate (POS login ID for the associate).
*   `storeID` (_string_, nullable) Store ID of the associate.
*   `merchantUserID` (_string_, nullable) Merchant's underlying system's user ID for the store associates. For example, LoginId for underlying OMS or Salseforce Commerce.
*   `paymentDeviceMerchantID` (_string_, nullable) Merchant ID of a payment device assigned to the associate.
*   `paymentDeviceID` (_string_, nullable) ID of a payment device, like terminal ID, assigned to the associate.
*   `storeAssociatePassword` (_string_) Store associate's password (POS Login Password for the associate).
*   `merchantPassword` (_string_, nullable) Merchant's underlying system's password for the associate.
*   `storeAssociatePasswordPin` (_string_, nullable) Password hint for the associate's POS login.
*   `firstName` (_string_, nullable) First name of the associate.
*   `lastName` (_string_, nullable) Last name of the associate.
*   `storeType` (_string_) Type of the store where the associate works. Possible values include: Regular, Popup, Outlet or eComm.
*   `role` (_string_) The associate's role in the store. Possible values include: STORE\_ASSOCIATE, STORE\_MANAGER or AREA\_MANAGER.
*   `passwordSetOn` (_integer (int64)_, nullable) Date when password was set last time. Represented as the number of milliseconds since epoch.
*   `storeAssociatePasswordFlag` (_boolean_) Flag indicating that the store associate password is updated during associate update operation. Used only during update operation.
*   `merchantPasswordFlag` (_boolean_) Flag indicating that the merchant password is updated during associate update operation. Used only during update operation.
*   `storeAssociateSecretFlag` (_boolean_, nullable) Flag indicating that the store associate secret is updated during associate update operation. Used only during update operation.
*   `imageUrl` (_string_, nullable) The associate's image URL.
*   `active` (_boolean_) Specifies whether the status of the associate is active (true) or removed/deactivated (false).
*   `emailId` (_string_, nullable) Email ID of the associate.
*   `mobilePhoneNumber` (_string_, nullable) Mobile phone number of the associate.
*   `additionalStoreIDs` (_array of string_, nullable) Additional store IDs where the associate can log in.
*   `gender` (_string_) Gender of the store associate.  
    Allowed values: `Male`, `Female`, `Neutral`, `Unknown`.
*   `hireDate` (_integer (int64)_, nullable) Date when the associate is hired or can start work in the store.
*   `terminationDate` (_integer (int64)_, nullable) Termination date for the associate.
*   `firstLoginPasswordReset` (_boolean_) Flag indicating that the password is set on the first login.
*   `mobileConfigID` (_string_, nullable) Mobile configuration ID.  
    Maximum length: 128. Example: `134ac374-0f49-4239-a161-ccfe4d3d7686`.

### PageStoreGroupResponse

*   `totalPages` (_integer (int32)_)
*   `totalElements` (_integer (int64)_)
*   `pageable` (_Pageable_)
*   `numberOfElements` (_integer (int32)_)
*   `first` (_boolean_)
*   `number` (_integer (int32)_)
*   `size` (_integer (int32)_)
*   `content` (_array of StoreGroupResponse_)
*   `sort` (_Sort_)
*   `last` (_boolean_)
*   `empty` (_boolean_)

### StoreGroupRequest

Store group pricing request.

*   `storeGroupId` (_string_, required) Store group identifier.  
    Example: `SG-001`.
*   `productId` (_string_, required) Product identifier.  
    Example: `PROD-12345`.
*   `storeGroupPrice` (_number_, required) Store group specific price for the product.  
    Example: `99.99`.
*   `customString0` (_string_, nullable) Custom string field 0 for additional attributes.
*   `customString1` (_string_, nullable) Custom string field 1 for additional attributes.

### StoreGroupResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `storeGroupId` (_string_)
*   `productId` (_string_)
*   `storePrice` (_number_)
*   `customString0` (_string_)
*   `customString1` (_string_)
*   `error` (_boolean_)

### UpdateStoreGroupsRequest

Batch update request for store group prices.

*   `storeGroups` (_array of StoreGroupRequest_, required) List of store group pricing updates. Maximum 100 store groups per request.

### InventoryAdjustRequest

*   `productId` (_string_, required)
    
    productId
    
    Product ID.
    
      
    Example: `123456`.
*   `storeId` (_string_, required)
    
    storeId
    
    Store ID.
    
      
    Example: `1`.
*   `quantity` (_integer (int32)_, required)
    
    quantity
    
    Quantity adjustment for the product.
    
      
    Example: `10`.
*   `reason` (_string_, required)
    
    reason
    
    Adjustment reason.
    
      
    Example: `Restock`.
*   `overlay` (_boolean_)
    
    overlay
    
    Specifies whether to adjust inventory as a delta (incremental change) or an absolute value. If the value is missing or false, the adjustment will be made as a delta; if the value is true, the adjustment will be made as an absolute value.
    
      
    Example: `true`.

### InventoryAdjustResponse

*   `productId` (_string_, required)
    
    productId
    
    Product ID.
    
      
    Example: `123456`.
*   `storeId` (_string_, required)
    
    storeId
    
    Store ID.
    
      
    Example: `1`.
*   `quantity` (_integer (int32)_, required)
    
    quantity
    
    Quantity adjustment for the product.
    
      
    Example: `10`.
*   `reason` (_string_, required)
    
    reason
    
    Adjustment reason.
    
      
    Example: `Restock`.
*   `overlay` (_boolean_)
    
    overlay
    
    Specifies whether to adjust inventory as a delta (incremental change) or an absolute value. If the value is missing or false, the adjustment will be made as a delta; if the value is true, the adjustment will be made as an absolute value.
    
      
    Example: `true`.
*   `inventoryAdjustStatus` (_string_)  
    Allowed values: `COMPLETE`, `FAILED`.
*   `errorMessage` (_string_)

### DownloadResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `url` (_string_) URL for the artifact to be downloaded.
*   `fileName` (_string_) File location for the artifact to be downloaded.
*   `error` (_boolean_)

### StoreProductDetails

Provide details about products in the store. This includes store-level inventory, store level pricing, store level promotions, etc. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).

*   `storeId` (_string_) Store or warehouse ID.
*   `productId` (_string_) Product ID.
*   `storeInventory` (_integer (int32)_) Product sellable quantity.
*   `storePrice` (_number_) Product price at the store.
*   `storePromoText` (_string_) Product promotion text applicable to this store.
*   `listPrice` (_number_) Product list price.
*   `salesPrice` (_number_) Product sale price.
*   `storePromoBanner` (_string_) Product promotion banner text.
*   `clearanceItems` (_array of ClearanceItem_) Product location within the store.
*   `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders.
*   `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity.
*   `quantityOnHand` (_integer (int32)_) Product quantity on hand.
*   `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store.
*   `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that isn't for sale.
*   `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that isn't for sale.
*   `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that isn't for sale.
*   `fullPriceSerialNumbers` (_array of string_) Full price serial numbers.
*   `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in store.
*   `customString0` (_string_) Custom string attribute of the product for the store.
*   `customString1` (_string_) Custom string attribute of the product for the store.
*   `quantity` (_integer (int32)_)

### StoreProductUpdateResponse

*   `storeId` (_string_) Store or warehouse ID.
*   `productId` (_string_) Product ID.
*   `storeInventory` (_integer (int32)_) Product sellable quantity.
*   `storePrice` (_number_) Product price at the store.
*   `storePromoText` (_string_) Product promotion text applicable to this store.
*   `listPrice` (_number_) Product list price.
*   `salesPrice` (_number_) Product sale price.
*   `storePromoBanner` (_string_) Product promotion banner text.
*   `clearanceItems` (_array of ClearanceItem_) Product location within the store.
*   `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders.
*   `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity.
*   `quantityOnHand` (_integer (int32)_) Product quantity on hand.
*   `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store.
*   `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that's not for sale.
*   `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that's not for sale.
*   `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that's not for sale.
*   `fullPriceSerialNumbers` (_array of string_) Full price serial numbers.
*   `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in the store.
*   `customString0` (_string_) Custom string attribute of the product for the store.
*   `customString1` (_string_) Custom string attribute of the product for the store.
*   `quantity` (_integer (int32)_)

### StoreInventoryProductsUpdateResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `products` (_array of StoreProductUpdateResponse_)
*   `error` (_boolean_)

### FulfillmentOrder

*   `orderId` (_string_, required) Order ID. In the case of ROPIS, the orderID serves as the uspendedCartId as POS generates a brand new orderId for the ROPIS order during checkout.
*   `orderType` (_string_, required) Order Type. BOPIS = STORE\_PICKUP, BOFIS = STORE\_FULFILLMENT,ROPIS = ONLINE\_RESERVE.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `orderSource` (_string_, required) OrderSource must be WEB for BOPIS, BOFIS and ROPIS orders.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `storeId` (_string_, required) StoreId which is going to fulfill the order.
*   `status` (_string_, required) Store fulfillment status. Possible values include: 1. PACK: BOPIS, BOFIS OR ROPIS item is packed by store associate. 2. DELIVERED: BOPIS item is picked up by the customer or pickup person. 3. CANCELED: BOPIS or BOFIS item is canceled by store associate. 4. SHIPPED: BOFIS item is shipped by store associate. 5. READY: When importing a fulfillment order into POS, it must have a 'READY' status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`.
*   `orderDate` (_integer (int64)_, required) Date when order was placed. Represented as number of milliseconds since epoch.
*   `totalAmount` (_number_, required) Order total.
*   `taxSubTotal` (_number_, nullable) Total tax amount for this order. Excludes any product price or shipping cost. Includes only the sum of taxes. Mandatory: If taxes are applicable, refer to valueAddedTax for VAT.
*   `valueAddedTax` (_number_, nullable) Value added tax amount for this order. Mandatory: If VAT is applicable, refer to taxSubTotal for taxes.
*   `taxableAmount` (_number_, nullable) Taxable amount.
*   `orderSubTotal` (_number_, required) Order total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `installationId` (_string_)
*   `shipmentList` (_array of ShipmentDetail_) List of shipments. Each shipment has shipping details for a BOFIS order. The shipping details consist of shipping address, shipping method, expected delivery date, and products corresponding to the shipment. **Note:** This field should be provided if the CMS property `Allow multiple shipments per cart/order` is enabled. This CMS setting can be found at: - **CMS** > **Store Management** > **Store Setting** > **Store fulfillment** > **Omni settings If this** flag is disabled, the shipping details should instead be provided in the following attributes: - `shippingMethodId` - `shippingCarrier` - `shippingCost` - `shippingAddress` - `deliveryDate` - `deliveryTimeSlot`.
*   `tenders` (_array of OrderPaymentDetail_, nullable) Representation of list of payments for this order. Required for BOPIS and BOFIS. Not applicable for ROPIS.
*   `customerProfile` (_CustomerProfile_)
*   `pickUpDetail` (_PickupDetail_)
*   `shippingAddress` (_Address_)
*   `shippingMethodId` (_string_, nullable) Shipping method ID. Refer to shipmentList for more details on when to provide shippingMethodId.
*   `shippingCarrier` (_string_) Shipping carrier code. Refer to shipmentList for more details on when to provide shippingCarrier.  
    Example: `UPS`.
*   `shippingCost` (_number_) Shipping cost. Refer to shipmentList for more details on when to provide shippingCost.
*   `deliveryDate` (_integer (int64)_) Delivery date in epoch.
*   `deliveryTimeSlot` (_string_) Expected delivery time slot. Refer to shipmentList for more details on when to provide deliveryTimeSlot.
*   `expectedShippingDate` (_integer (int64)_) Expected shipping date in epoch. Used for SLA calculation in BOFIS orders.
*   `lastPickupDate` (_string_) Last pickup date in ISO\_LOCAL\_DATE format (yyyy-MM-dd). Specifies the deadline for BOPIS order pickup, used for display purposes and automated cancellation logic.  
    Example: `2026-08-20`.
*   `productList` (_array of FulfillmentProduct_, required) List of products in the order.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### ExternalBopisCancellationRequest

Request to cancel BOPIS items.

*   `productList` (_array of CancelItem_, required) List of products to cancel.
*   `orderId` (_string_, required) Order ID.
*   `storeId` (_string_, required) Store ID.

### FulfillmentEvent

*   `orderId` (_string_, required) Order Id.
*   `orderType` (_string_, required) Order type. It can be either: 1. Store Fulfillment: order is fulfilled by a store. 2. Store Pickup: order is available for pickup at a store.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `productList` (_array of FulfillmentProduct_, required) Item list.
*   `status` (_string_, required) Store Fulfillment Status. 1. PACK: BOPIS, BOFIS, or ROPIS item is packed by store associate. 2. DELIVERED: BOPIS item is picked up by the customer or pickup person. 3. CANCELED: BOPIS or BOFIS item is canceled by store associate. 4. SHIPPED: BOFIS item is shipped by store associate. 5. READY: When importing a fulfillment order into POS, it must have a 'READY' status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`.
*   `storeId` (_string_, required) Store ID from where the item(s) are picked or fulfilled.
*   `deliveryGroupList` (_array of ShipmentDetail_, nullable) The shipping details of the items for store fulfillment order. Each delivery group has shipping address and corresponding shipping method. Each delivery item from productList is associated with its delivery group using productList\[\].deliveryGroupId. Note: It is available only if the CMS Property - 'Allow multiple shipments per cart/order' is enabled. This is a CMS setting and can be found in **CMS** > **Store Management** > **Store Setting** > **Store** fulfillment > Omni settings. If the property is disabled, refer to shipment.
*   `shipment` (_ShipmentDetail_)
*   `pickupDetail` (_PickupDetail_)
*   `note` (_string_) Note provided by associate during pack, pick, or shipment.

### CustomerOrder

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128. Example: `PS00027533`.
*   `quoteId` (_string_, nullable) Quote reference identifier. Links the order to a quote. Available when the order is based on a quote.  
    Maximum length: 128.
*   `externalQuoteId` (_string_, nullable) External quote reference identifier. Quote ID from the external system. Available when the order is based on a quote.  
    Maximum length: 128.
*   `orderStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `status` (_string_, read-only, nullable, deprecated)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderType` (_string_, nullable) Type of order. It is used in case of order fulfilled by the stores,  
    E.g. BOPIS, BOFIS, BOSS orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `email` (_string_, nullable) Customer Email ID.  
    It is available for signed-in customers or when email is captured in the  
    shipping address for guest customers.  
    Maximum length: 128.
*   `totalAmount` (_number_, required) Order total.
*   `shippingSubTotal` (_number_, nullable) Shipping sub total.
*   `shippingDiscount` (_number_, nullable) Shipping discount.
*   `shippingMethod` (_ShippingMethod_)
*   `shippingTax` (_number_, nullable) Shipping method tax.
*   `shippingTaxClass` (_string_, nullable) Shipping method tax class.
*   `taxSubTotal` (_number_, nullable) Total tax amount for this order.  
    It is applicable for regions/countries where Tax is supported. For countries where VAT is applicable, refer to valueAddedTax.  
    
*   `taxExemption` (_number_, nullable) The tax exemption amount for this order.  
    It is applicable whenever an associate applies a tax exemption to the order in store.  
    
*   `shippingTaxExemption` (_number_, nullable) Total Shipping tax exemption amount for this order. This does not include any product price or shipping cost. It includes only the tax exemption on Shipping.
*   `valueAddedTax` (_number_, nullable) Total VAT amount for this order.  
    It is applicable for regions/countries where VAT is supported. For countries where tax is applicable, refer to taxSubTotal.  
    
*   `orderSubTotal` (_number_, required) Order total excluding discounts, shipping costs and taxes but  
    inclusive of VAT.
*   `tenders` (_array of OrderPaymentDetail_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.  
    When importing an order paid with a credit card from an external system, make sure to include all required fields as well as the following fields:  
    1\. requestId  
    2\. cardType  
    For a **referenced refund** on the credit card, all the above fields and CMS configuration are necessary. Set the below CMS property to **Default** to initiate a referenced refund.  
    **CMS** > **Store Management** > **Store Settings** > **Refund Mode for External Order**.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products.  
    The list doesn't include returned products. While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `orderProductList` (_array of OrderProduct_, required) A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.
*   `returnProductList` (_array of ReturnedProduct_, nullable) List of items that have been returned.  
    While importing an order from an external system,  
    it is optional as the products and return products both can be provided in orderProductList.  
    
*   `discount` (_number_, nullable) Order discount amount. Total discount applied using promo coupons and/or item level price override.  
    It doesn't include transaction discount. For transaction discount, refer to transactionDiscountAmount.  
    Mandatory: If any promo coupon is applied or any item level price override is applied.
*   `externalOrderId` (_string_, nullable) The reference ID of the order that corresponds to the external system. This is relevant in cases where the external downstream system or ERP system uses its own ID instead of the POS order ID for further processing. It is necessary to provide this reference ID while importing the order in POS, especially when updates like returns are required.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store where the order is captured. For BOPIS orders placed via a website,  
    this field contains the store ID for pickup.  
    Maximum length: 128.
*   `storeAssociateId` (_string_, required) The logged-in store associate's ID.  
    Maximum length: 256.
*   `orderSource` (_string_, required) This is the channel or source of an order or transaction. It must be IN\_STORE for all orders placed in store. It must be WEB for all orders placed on the website. When importing an order from an external system, ensure to provide: 1. IN\_STORE for orders placed in store, otherwise the order will not be available in CMS under successful order report. 2. WEB for orders placed on the website to skip its entry from successful order report.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `paymentSource` (_string_, nullable) Payment source. If an order is paid with a single tender,  
    it has the payment method of that tender. The following payment methods  
    are supported: CreditCard, Unknown, External, GiftCard, MixedMode, Cash, Miscellaneous,  
    Finance, StoreCredit, PayByLink, RemotePayByLink, Reward, and Check.  
    In the case of multi-tender payment, the payment source should be MixedMode.
*   `shippingMethodId` (_string_, nullable) Shipping method ID.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `installationId` (_string_, nullable) The device identifier is required for IN\_STORE purchases.  
    If not provided, it defaults to EXTERNAL for orders from external systems.  
    Default: `EXTERNAL`. Maximum length: 128.
*   `lastDateToReturnTimeStamp` (_integer (int64)_, nullable) Last date to return. The return window policy sets the last date for a return.  
    For example, if the policy is one month long and a sale occurs on April 1st,  
    the lastDateToReturnTimeStamp will be set to May 1st.  
    When an order is imported from an external system,  
    the system will determine the order's eligibility for return based on the provided date.  
    If the date is not provided, the item can be returned without any time limitation.  
    Note: Represented as number of milliseconds since epoch.  
    .  
    Example: `1653078974310`.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown. Mandatory if tax engine is configured along with tax rates.  
    For VAT countries, refer to vatRates.
*   `taxExemptions` (_array of TaxExemptionRequest_, nullable) List of tax exemptions, if any, applied to order.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown. Mandatory if tax engine is configured along with VAT rates. For TAX countries, refer to taxRates.
*   `shippingName` (_string_, nullable) Shipping name  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.name from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingDescription` (_string_, nullable) Shipping description.  
    Mandatory for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,  
    use the shippingMethod.description from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingCarrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Required for delivery orders.  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.carrier from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `shippingServiceLevel` (_string_, nullable) Shipping service level, for example, 3-5 Days, 1-Day, Express, Standard, or Overnight.  
    Required for delivery order  
    Note: If item level shipping method or item level shipping address is enabled,use the shippingMethod.serviceLevel from deliveryGroups.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `phoneNumber` (_string_, nullable) Customer phone number. Mandatory for signed-in customers  
    or when phone number is captured in the shipping address for guest customers.  
    
*   `orderDate` (_integer (int64)_, required) Date when order was placed.  
    Represented as number of milliseconds since epoch.
*   `coupons` (_array of string_, nullable) List of coupon codes applied for this order.
*   `customerProfile` (_Profile_)
*   `updateDate` (_integer (int64)_, required) Date when the order was last updated. Represented as number of milliseconds since epoch.
*   `taxableAmount` (_number_, nullable) Taxable amount.  
    Mandatory if the tax engine is configured along with tax rates.
*   `fulfillmentType` (_string_, required, deprecated) Order fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `rewardAmount` (_number_, nullable) Reward amount applied to this order if any.
*   `transactionDiscountAmount` (_number_, nullable) Transaction discount applied to this order if any.
*   `canReturn` (_boolean_, write-only, nullable) Flag indicating if this order can be returned.  
    During order import in POS, if it is not provided,the order remains returnable.
*   `paymentDetails` (_array of OrderPaymentDetail_, nullable, deprecated) Deprecated. Use 'tenders' instead.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Order refund payment details.  
    If an order is returned, it will have all refunded tenders.  
    
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `failedReasonCode` (_string_, read-only, nullable) Failed order reason code corresponding to payment.  
    Possible values are CANCELED, PAYMENT\_DECLINED, and PAYMENT\_REVERTED.  
    Applicable only if the order fails. Not required when importing an order from an external system.  
      
    Allowed values: `CANCELED`, `PAYMENT_DECLINED`, `PAYMENT_REVERTED`, `PAYMENT_REVERSAL_FAILED`, `PAYMENT_STATUS_UNKNOWN`, `PAYMENT_NOT_FOUND`.
*   `twoPhaseCommitReferenceId` (_string_, read-only, nullable, deprecated) Used for internal processing. Don't use in external systems.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `partiallyPaid` (_boolean_) Flag indicating if this order is partially paid for.
*   `orderActivityLog` (_array of OrderActivityLog_, nullable) The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.
*   `storeAttribution` (_StoreAttribution_)
*   `tipTotal` (_number_, nullable) Total tip added to the order.
*   `orderFiscalData` (_array of OrderFiscalData_, nullable) All fiscal data for this order if any.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `offlineMode` (_boolean_, nullable) Flag indicating if the order got created in offline mode.  
    If not mentioned, it is considered as false.
*   `employee` (_Employee_)
*   `originalOrderId` (_string_) Order ID of the original order if the order is an exchange order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method and other delivery details.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    2\. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `rewardList` (_array of Reward_, read-only, nullable) The list of loyalty rewards applied in this transaction.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `returnCustomerInformationList` (_array of OrderReturnCustomerInformation_, nullable) List of customer/person who returned the items.  
    Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.  
    
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `taxFreeDocument` (_TaxFreeDocument_)
*   `orderRefundFeeDetailList` (_array of OrderRefundFeeDetail_, nullable) List of Refund fee like restocking fee on returned or canceled items.  
    Applicable when item is returned or canceled and refund fee is configured.  
    For more detail on refund fee,
*   `error` (_boolean_)

### OrderRepostRequest

*   `orderIds` (_array of string_) List of order IDs for reposting.
    
    Each item: List of order Ids for reposting.
    

### OrderRepostResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderRepostStatusList` (_array of OrderRepostStatus_) A list of Reposting status for each order that was part of the request.
*   `error` (_boolean_)

### OrderSearchRequest

*   `firstName` (_string_) Customer first name.
*   `lastName` (_string_) Customer last name.
*   `email` (_string_) Customer email address.
*   `orderId` (_string_) Order ID.
*   `postalCode` (_string_) Postal code or Zip code.
*   `start` (_integer (int32)_) Order search offset. Used for paginating across multiple orders.  
    Default: `0`.
*   `limit` (_integer (int32)_) Number of orders to return. Used for paginating across multiple orders.  
    Default: `20`.
*   `bopisOrders` (_boolean_) Flag indicating whether to search BOPIS orders.
*   `storeId` (_string_) Store ID. Find order placed in this store.
*   `customerId` (_string_) Customer ID. Find orders placed by this customer ID.
*   `accountNumber` (_string_) Customer's account number. It can be alternate customer ID or external account number of the customer.
*   `storeOrderStatus` (_string_) Store Order Status. Find orders in this status. Applies to BOPIS/BOFIS orders.
*   `paymentCard` (_Card_)
*   `productId` (_string_) Product ID. Find orders containing this product ID.
*   `searchForReturn` (_boolean_, deprecated) DEPRECATED. Flag indicating if this search is for return purpose. Find only those orders eligible for returns.
*   `storeAssociateId` (_string_) Store Associate ID. Find orders placed by specific store associate.
*   `storeRegisterId` (_string_) Store Register ID. Find orders placed from specific store register.
*   `orderTotal` (_number_) Order Total. Find orders having specific order total.
*   `paymentMethod` (_string_) Payment method. Find orders placed using specific payment method.
*   `amountRange` (_BigDecimalRange_)
*   `orderDateTimeStampStart` (_integer (int64)_) Find orders placed on or after this timestamp - represented as milliseconds since epoch.
*   `orderDateTimeStampEnd` (_integer (int64)_) Find orders placed on or before this timestamp - represented as milliseconds since epoch.
*   `orderStatus` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `manualReceiptId` (_string_) Manual Receipt ID based search.
*   `advancedSearchId` (_string_) Advanced search ID from response.
*   `serialNumber` (_string_) Serial Number. Find orders containing items with this serial number.
*   `workbench` (_boolean_)

### OrderSearchResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderList` (_array of OrderSearchResponseEntry_) List of searched orders.
*   `advancedSearchId` (_string_) Response from NetSuite advanced search.
*   `error` (_boolean_)

### ExternalTransaction

*   `transactionId` (_string_, required) Transaction Id.
*   `transactionType` (_string_, required) Transaction type.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`.
*   `orderId` (_string_, required) Order ID corresponding to the transaction.
*   `externalOrderId` (_string_, nullable) External reference ID if the transaction is captured externally and has a different identifier than orderId.  
    Maximum length: 128.
*   `storeAttribution` (_ExternalStoreAttribution_, required)
*   `tenderList` (_array of ExternalTender_, required) Payment method used towards the sale transaction.
*   `refundTenderList` (_array of ExternalRefundTender_, nullable) Payment method used towards the return transaction.
*   `productList` (_array of ExternalProduct_, required) Products.
*   `returnProductList` (_array of ExternalReturnProduct_, nullable) Returned products.
*   `profile` (_ExternalCustomerProfile_)
*   `deliveryGroupList` (_array of ExternalDeliveryGroup_) In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.
*   `pickUpDetailList` (_array of ExternalPickUpDetail_, nullable) Pickup details.
*   `billingAddress` (_ExternalAddress_)
*   `lastDateToReturn` (_integer (int64)_, nullable) The last date by which the item(s) from the transaction can be returned. If not provided, the item can be returned without any time limitation. The date is in milliseconds since epoch.  
    Example: `1653078974310`.
*   `saleSummary` (_ExternalTransactionSummary_, required)
*   `orderSource` (_string_, required) Channel of the transaction.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `orderType` (_string_, nullable) Order type. It is needed if the order is fulfilled by store. For example, BOPIS, BOFIS.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `status` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`.
*   `noteList` (_array of ExternalNote_, nullable) Notes for the transaction.
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxExemptionList` (_array of ExternalTaxExemption_, nullable) Applied tax exemptions.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.

### ActivationCodeRequest

*   `orderId` (_string_, required) The order ID of the customer order.
*   `storeId` (_string_, required) The store ID of the store where the transaction is happening.
*   `transactionId` (_string_, required) Sale transaction ID.  
    Example: `1-test-20240612131829-4-1`.
*   `productList` (_array of ExternalProduct_, required) List of products that need serialized-unit attributes. For example, activation code, context code, etc.

### ActivationCodeResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `serializedUnitDetailList` (_array of ExternalSerializedUnitDetail_) The list of attributes about a serialized unit, for example, activation code or context code.
*   `error` (_boolean_)

### ExternalCart

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `cartItemList` (_array of ExternalProduct_, required) All the items from the cart. Each item has a link to its delivery group via deliveryGroupId.
*   `deliveryGroupList` (_array of ExternalDeliveryGroup_) All delivery groups corresponding to the delivery items from the cart.
*   `billingAddress` (_ExternalAddress_)
*   `profile` (_ExternalCustomerProfile_)
*   `pickUpDetailList` (_array of ExternalPickUpDetail_, nullable) Pickup details.

### CartValidationResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `displayMessage` (_string_, nullable) This message is for informational purposes only and is intended for display to users or associates. Please ensure it is not used in error scenarios. For error messages, use 'errorMessage' instead, as this will trigger the creation of a new cart and the execution of tax and other SPI calls.
*   `error` (_boolean_)

### SearchCustomersResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `customers` (_array of CustomerData_, nullable) List of Customers.
*   `associateSessionId` (_string_, nullable) Store associate session ID.
*   `error` (_boolean_)

### UpdateCustomerRequest

*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable, deprecated) Deprecated. Not supported in create or update customer requests. Use profile.address instead. To add additional addresses, use the Customer Address SPI (CREATE\_CUSTOMER\_ADDRESS or UPDATE\_CUSTOMER\_ADDRESS). The complete address collection is returned in responses only.
*   `consents` (_Consents_)
*   `storeAttribution` (_SpiStoreAttribution_)
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)

### UpdateCustomerResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system, contains the complete address collection, including the primary address from profile.address.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)
*   `error` (_boolean_)

### CreateCustomerRequest

*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable, deprecated) Deprecated. Not supported in create or update customer requests. Use profile.address instead. To add additional addresses, use the Customer Address SPI (CREATE\_CUSTOMER\_ADDRESS or UPDATE\_CUSTOMER\_ADDRESS). The complete address collection is returned in responses only.
*   `consents` (_Consents_)
*   `storeAttribution` (_SpiStoreAttribution_)

### CreateCustomerResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system, contains the complete address collection, including the primary address from profile.address.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)
*   `error` (_boolean_)

### GetCustomerResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `sessionId` (_string_) Active session ID.
*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system: contains the complete address collection, including the primary address from profile.address.
*   `cartProductList` (_array of ClientelingCartProduct_, nullable) List of products saved in customer cart.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)
*   `error` (_boolean_)

### GetCustomerAddressesResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_, nullable) List of customer addresses.
*   `error` (_boolean_)

### UpdateCustomerAddressRequest

*   `customerId` (_string_) Customer ID.
*   `address` (_Address_)
*   `addressId` (_string_) Address ID of address to update.

### UpdateCustomerAddressResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_) List of customer addresses.
*   `error` (_boolean_)

### AddCustomerAddressRequest

*   `customerId` (_string_) Customer ID.
*   `address` (_Address_)

### AddCustomerAddressResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_) List of customer addresses.
*   `error` (_boolean_)

### DeleteCustomerAddressResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `addressList` (_array of Address_, nullable) List of customer addresses.
*   `error` (_boolean_)

### SpiDeliveryDatesRequest

Request object to get delivery/pickup dates for products belonging to the same group, that is, products with the same shipping address, delivery group, or fulfillment type.

*   `products` (_array of SpiProduct_, required) The list of products in this group for which the delivery / pickup dates are to be returned in the response.
*   `datePickerType` (_string_, required) The type of action for which the dates are to be selected. Valid values: DELIVERY & PICKUP.  
    Allowed values: `DELIVERY`, `PICKUP`.
*   `shippingMethodId` (_string_, nullable) The shipping method ID in case the shipping method is selected for delivery items.
*   `address` (_SPIAddress_)

### SpiDateTimesResponse

Response object that contains a set of delivery/pickup date and time slots for the products sent in the request.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `dateTimeSlots` (_array of SpiDateTimeSlot_, required) The list of delivery/pickup date time slots for the products.
*   `availableDate` (_integer (int64)_, required) The first available date in epoch milliseconds that is eligible for delivery/pickup.
*   `dateTimeSlotType` (_string_, required) The type of date time slots provided. Valid values: Delivery & Pickup.  
    Allowed values: `Delivery`, `Pickup`.
*   `willCallDate` (_SpiDateTimeSlot_)
*   `error` (_boolean_)

### SPIShipmentProcessorRequest

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `cartItemList` (_array of SPIShipmentProcessorRequestProduct_, required) All the items from the cart. Each item has a link to its delivery group via deliveryGroupId.
*   `deliveryGroupList` (_array of SPIShipmentProcessorRequestDeliveryGroup_, required) All delivery groups corresponding to the delivery items from the cart.

### SPIShipmentProcessorResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cartItemList` (_array of SPIShipmentProcessorResponseProduct_, required) All items from the cart are associated with a deliveryGroupId, enabling linkage to the corresponding deliveryGroup within the deliveryGroupList. Additionally, each item may possess custom attributes.
*   `deliveryGroupList` (_array of SPIShipmentProcessorResponseDeliveryGroup_, required) All delivery groups corresponding to the delivery items from the cart.
*   `error` (_boolean_)

### EReceiptRequest

*   `type` (_string_) Receipt's type.  
    Allowed values: `TRANSACTION_PRINT_RECEIPT`, `ORDER_PRINT_RECEIPT`, `CUSTOMER_ORDER_CONFIRMATION`, `GIFT_RECEIPT`, `REFUND_CONFIRMATION`, `SA_ORDER_INTIMATION`.
*   `emailTo` (_array of string_) Emails to receive order.
*   `customerOrder` (_CustomerOrder_)
*   `receiptPrintCount` (_integer (int32)_) Receipt print count (number of original and duplicate receipts).
*   `receiptLanguage` (_string_)
    
    Language selected for the receipt template. This field is optional.
    
    The language value is resolved using the following priority order:
    
    1.  **Thank You Page language** — Uses the language option configured on the Thank You Page.
    2.  **Store Setting languages default** — If no Thank You Page language is configured, uses the default language from the languages Store Setting.
    3.  **Mobile Config defaultSupportedLanguage** — If neither of the above is set, falls back to Receipt Configuration > defaultSupportedLanguage in the Mobile Config.
    4.  **iPad locale** — If none of the above are populated, defaults to the associated iPad's locale.

### EmployeeVerificationRequest

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)
*   `storeId` (_string_) Store ID provided for employee verification.
*   `associateId` (_string_) Associate ID provided for employee verification.

### EmployeeVerificationResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `employeeId` (_string_) Identification of employee.
*   `firstName` (_string_) Employee's first name.
*   `lastName` (_string_) Employee's last name.
*   `email` (_string_) Employee's email.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `error` (_boolean_)

### SpiGiftCardActivateRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Activation amount (gift card purchase price); non-negative.

### SpiGiftCardActivateResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations.
*   `error` (_boolean_)

### SpiGiftCardAddBalanceRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Amount to load onto the card; non-negative.

### SpiGiftCardAddBalanceResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations.
*   `error` (_boolean_)

### SpiGiftCardBalanceRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.

### SpiGiftCardBalanceResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `isActive` (_boolean_) True if the card is active and usable; defaults to true.
*   `cardNumber` (_string_) Echoed card number from the request.
*   `error` (_boolean_)

### SpiGiftCardRedeemRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Amount to deduct from the card; non-negative.

### SpiGiftCardRedeemResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `balance` (_number_, required) Current balance on the gift card; non-negative.
*   `providerTransactionId` (_string_, required) Provider's transaction identifier; stored by platform for future void or reversal operations.
*   `providerReferenceId` (_string_, required) Provider's reference identifier; stored by platform as requestId on the tender for reconciliation.
*   `error` (_boolean_)

### SpiGiftCardVoidRequest

*   `cardNumber` (_string_, required) Gift card PAN (primary account number).
*   `cardPin` (_string_) PIN for card verification, driven by **Store Management** > **Integration** > **Gift Card** > **PIN Setting**: non-null when pinSetting is REQUIRED, or OPTIONAL and the user provided a PIN; null when pinSetting is NONE or OPTIONAL without user-provided PIN.
*   `transactionId` (_string_, required) Platform-generated transaction reference for idempotency and tracing.
*   `amount` (_number_, required) Amount to reverse; must match the approvedAmount from the original operation.
*   `originalProviderTransactionId` (_string_, required) Provider's transaction identifier from the original operation being voided.

### SpiGiftCardVoidResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `cardNumber` (_string_, required) Echoed card number from the request.
*   `providerReferenceId` (_string_, required) Provider's reference identifier for the void; stored by platform as paymentReversalRequestId.
*   `error` (_boolean_)

### SpiRegistryDetailResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `registryId` (_string_, required) The unique ID of the registry.
*   `firstName` (_string_, required) The First name of the Registrant.
*   `lastName` (_string_, required) The last name of the Registrant.
*   `coRegistrantName` (_string_, nullable) The Co-Registrant name for the registry if available.
*   `eventType` (_string_, required) The event type for which the registry was created. For example, Wedding, Engagement, Housewarming.
*   `eventDate` (_integer (int64)_, required) The event date in epoch milliseconds, to be shown in a suitable format on the app.
*   `preEventAddress` (_SPIAddress_, required)
*   `postEventAddress` (_SPIAddress_, required)
*   `productList` (_array of SpiRegistryProduct_, required) The list of gift products that are present with this registry, with all the availability details.
*   `error` (_boolean_)

### ReturnRegistryRequest

*   `registryId` (_string_, required) The unique ID of the registry.
*   `productId` (_string_, required) Product Identifier.
*   `gtin` (_string_, nullable) Item's GTIN, alternate field to product ID.
*   `storeId` (_string_, nullable) Store ID of the current store.
*   `quantity` (_integer (int32)_, required) Quantity of the product to be returned. The response returns an error if the requested quantity isn't available.  
    Default: `1`.

### SpiRegistryReturnResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `items` (_array of RegistryLineItem_, required) The list of line items corresponding to the product Id sent in request, where each line can be of differing prices, quantities, belonging to different orders.
*   `error` (_boolean_)

### SearchRegistryRequest

*   `registryId` (_string_, nullable) The unique ID of the registry.
*   `firstName` (_string_, nullable) The First name of the Registrant.
*   `lastName` (_string_, nullable) The last name of the Registrant.
*   `storeId` (_string_, nullable) Store ID of the current store.
*   `email` (_string_, nullable) The email ID of the registrant.
*   `phone` (_string_, nullable) The Phone number of the Registrant.

### SpiGiftRegistryResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `giftRegistries` (_array of GiftRegistry_, required) The list of gift registries matching the search.
*   `error` (_boolean_)

### InventoryAvailabilityRequest

*   `zipCode` (_string_, required) The zip code or postal code for which to check product availability.
*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `gtin` (_string_, nullable) Item's GTIN , alternate field to check inventory (Mainly used by SPI).
*   `variantGroupId` (_string_, nullable) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `storeId` (_string_, nullable) Store ID of the current store.

### SpiInventoryAvailabilityResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `availabilityText` (_string_, required) Generic text field that contains information about inventory availability of the product.
*   `error` (_boolean_)

### InventoryOverviewRequest

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `storeId` (_string_, required) Store ID of the current store.
*   `gtin` (_string_, nullable) Item's GTIN, alternate field to check inventory (mainly used by SPI).
*   `variantGroupId` (_string_, nullable) Variant Group ID. All the variants of an item are grouped together under the same variant ID.

### SpiInventoryOverviewResponse

Response object that returns the full inventory overview for all stores.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `storeInventoryDetails` (_array of StoreInventoryDetails_, required) List of all stores and their inventory details for the product sent in the request.
*   `error` (_boolean_)

### CheckInventoryRequest

*   `products` (_array of InventoryProduct_, required) The list of Products for which the Inventory is to be checked.

### SpiInventoryResponse

*   `errorMessage` (_string_, nullable) Placeholder string for any error that occurs when checking inventory.
*   `inventory` (_array of ProductInventory_)

### CycleCountPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of CycleCountPayloadLine_, required) Cycle count line items.

### InventoryWebhookResponse

*   `status` (_string_, required)
    
    Status
    
    Status of the inventory webhook processing.
    
      
    Allowed values: `SUCCESS`, `ERROR`. Example: `SUCCESS`.
*   `message` (_string_, required)
    
    Message
    
    Inventory webhook processing result.
    
      
    Example: `Successfully`.

### InventoryAdjustmentPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of InventoryAdjustmentPayloadLine_, required) Inventory adjustment line items.

### InventoryTransferPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of InventoryTransferPayloadLine_, required) Inventory transfer line items.

### PurchaseOrderPayload

*   `eventType` (_string_, required) Inventory transfer event type.  
    Allowed values: `ASN_RECEIVED_EVENT`, `ASN_PARTIALLY_RECEIVED_EVENT`, `ASN_RECEIVE_COMPLETED_EVENT`, `ASN_REJECTED_EVENT`, `BLIND_RECEIVE_STARTED_EVENT`, `BLIND_RECEIVE_PAUSED_EVENT`, `BLIND_RECEIVE_IN_PROGRESS_EVENT`, `BLIND_RECEIVE_COMPLETED_EVENT`, `CTS_TRANSFER_STARTED_EVENT`, `CTS_TRANSFER_COMPLETED_EVENT`, `CTS_TRANSFER_CANCELLED_EVENT`, `CTS_TRANSFER_ERRORED_EVENT`, `STS_TRANSFER_STARTED_EVENT`, `STS_TRANSFER_COMPLETED_EVENT`, `STS_TRANSFER_SHIPPED_EVENT`, `STS_TRANSFER_RECEIVED_EVENT`, `STS_TRANSFER_CANCELLED_EVENT`, `STS_TRANSFER_ERRORED_EVENT`, `PO_TRANSFER_STARTED_EVENT`, `PO_TRANSFER_COMPLETED_EVENT`, `PO_TRANSFER_SHIPPED_EVENT`, `PO_TRANSFER_RECEIVED_EVENT`, `PO_TRANSFER_CANCELLED_EVENT`, `PO_TRANSFER_ERRORED_EVENT`, `RTV_CREATED_EVENT`, `RTV_COMPLETED_EVENT`, `RTV_SHIPPED_EVENT`, `RTV_RECEIVED_EVENT`, `RTV_CANCELLED_EVENT`, `RTV_FAILLED_EVENT`, `CYC_COUNT_CREATED_EVENT`, `CYC_COUNT_STARTED_EVENT`, `CYC_COUNT_COMPLETED_EVENT`, `CYC_COUNT_CANCELED_EVENT`, `INVENTORY_ADJUSTMENT`, `INVENTORY_BUCKET_ADJUSTMENT`. Example: `STS_TRANSFER_STARTED_EVENT`.
*   `lines` (_array of PurchaseOrderPayloadLine_, required) Purchase order line items.

### TransactionalReturnPayload

*   `orderId` (_string_, required)
    
    orderId
    
    Order ID.
    
      
    Example: `PS00000006`.
*   `products` (_array of TransactionalInventoryProduct_, required)
    
    products
    
    List the products that require inventory adjustment.
    
*   `returnStoreLocation` (_string_, required)
    
    returnStoreLocation
    
    Return order's store ID.
    
      
    Example: `2`.

### TransactionalInventoryWebhookResponse

*   `status` (_string_, required)
    
    Status
    
    Status of the transaction inventory webhook processing.
    
      
    Allowed values: `SUCCESS`, `ERROR`. Example: `SUCCESS`.
*   `message` (_string_, required)
    
    Message
    
    Transaction inventory webhook processing result.
    
      
    Example: `Successfully`.

### TransactionalSalePayload

*   `orderId` (_string_, required)
    
    orderId
    
    Order ID.
    
      
    Example: `PS00000006`.
*   `products` (_array of TransactionalInventoryProduct_, required)
    
    products
    
    List the products that require inventory adjustment.
    
*   `fulfillmentLocation` (_string_, required)
    
    fulfillmentLocation
    
    Sale order's store ID.
    
      
    Example: `2`.
*   `fulfillmentType` (_string_, required)
    
    fulfillmentType
    
    Order fulfillment type.
    
      
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.

### Cart

*   `cartId` (_string_)
*   `suspendedCartId` (_string_, nullable) If the cart is created from suspended cart,the suspendedCartId will be populated with the suspended cart's db id. This is nothing but db id of the resumed suspended cart.
*   `suspendedQuoteId` (_string_, nullable) If the cart is created from suspended cart having quote,the suspendedQuoteId will be populated with the suspended cart's quoteId.
*   `suspendedExternalQuoteId` (_string_, nullable) If the cart is created from suspended cart having quote,the suspendedExternalQuoteId will be populated with the suspended cart's external quoteId.
*   `resumedCartDBIds` (_array of string_, nullable) All the resumed cart associated with this current cart. Multiple suspended carts can be resumed in single active cart, all such resumed carts are maintained in this list.  
    Unique items.
*   `cartItemList` (_array of Product_)
*   `subTotal` (_number_)
*   `shippingMethodList` (_array of ShippingMethod_)
*   `session` (_string_)
*   `orderNo` (_string_)
*   `discount` (_number_)
*   `errors` (_array of ProductError_)
*   `productWarnings` (_array of ProductWarning_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `orderPriceAdjustments` (_array of OrderPriceAdjustment_)
*   `originalDiscountData` (_CartDiscountData_)
*   `giftCardList` (_array of GiftCard_)
*   `giftCardAppliedTotal` (_number_)
*   `paymentMerchantId` (_string_)
*   `paymentOrganizationId` (_string_)
*   `token` (_string_)
*   `errorCode` (_string_)
*   `errorMessage` (_string_)
*   `taxCalculationDone` (_boolean_)
*   `hybridCheckoutUrl` (_string_)
*   `rewardList` (_array of Reward_)
*   `rewardTotal` (_number_)
*   `cookieList` (_array of CheckoutCookie_)
*   `tax` (_number_)
*   `valueAddedTax` (_number_)
*   `highPrecisionValueAddedTax` (_number_)
*   `giftCardRemainingTotal` (_number_)
*   `giftWrapTotal` (_number_)
*   `giftMessage` (_string_)
*   `promotions` (_array of Promotion_)
*   `promotionCodes` (_array of string_)
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `taxTotal` (_number_)
*   `taxExemption` (_number_)
*   `shippingTotal` (_number_)
*   `shippingDiscount` (_number_)
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `shippingMethod` (_ShippingMethod_)
*   `priceAdjustmentsComplete` (_boolean_)
*   `redeemPromoCallBackUrl` (_string_)
*   `loyaltyId` (_string_)
*   `customerEmail` (_string_)
*   `orderSource` (_string_)  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `transactionStartDate` (_string (date-time)_)
*   `fullfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `storeId` (_string_)
*   `customerId` (_string_)
*   `taxableAmount` (_number_)
*   `isSplitCart` (_boolean_)
*   `children` (_object_)
    
    Additional properties: `Cart`.
    
*   `transactionDiscountAmount` (_number_)
*   `transactionDiscountReason` (_string_, deprecated) DEPRECATED - Use 'reasons' instead.
*   `offlineMode` (_boolean_)
*   `loyaltyInfo` (_LoyaltyInfo_)
*   `taxRates` (_array of OrderTaxRate_) Sale-side tax rate.
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions.
*   `vatRates` (_array of OrderTaxRate_) Sale-side VAT rate.
*   `netTaxRates` (_array of OrderTaxRate_) Net tax rate calculated based on sale-side tax rate and return-side tax rate.
*   `netVatRates` (_array of OrderTaxRate_) Net VAT rate calculated based on sale-side VAT rate and return-side VAT rate.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the actions performed on the cart. For example, reason for discounts applied to the order.
*   `editOrderId` (_string_, nullable) Order ID for the order being edited.
*   `exchangeItemResponses` (_array of ExchangeItemResponse_) Details about the items that are being returned or exchanged.
*   `returnsTenders` (_array of ReturnsTender_) In case there is refund, refund tender details and options.
*   `amountToBeCharged` (_number_) Amount to be charged.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `orderType` (_string_) Used to indicate if the order is of type Layaway.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow. Maximum transaction discount that can be applied.
*   `minimumPaymentAmount` (_number_) Used for partial payments flow. Represents minimum payment amount due at the time of order placement.
*   `notesList` (_array of OrderNote_)
*   `grandTotal` (_number_) Grand Total of sale transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, Grand Total is to maintain total sale amount. In case of pure returns, the Grand Total will always be zero.
*   `hash` (_string_) Hash corresponding to the current cart content.
*   `saleRoundingAmount` (_number_) The delta amount because of rounding applied on sale portion of the cart.
*   `exchangeItemRequests` (_array of ExchangeItemRequest_) Request for items that are being returned or exchanged.
*   `refundSubTotal` (_number_) Returning item subtotal — subtotal of items in the exchange item list.
*   `refundDiscount` (_number_) Returning item's discount — discount total of items in the exchange item list.
*   `refundTax` (_number_) Returning item's tax — tax total of items in the exchange item list.
*   `refundTariff` (_number_) Returning item's tariff — tariff total of items in the exchange item list.
*   `refundTaxExemption` (_number_) Returning item's tax exemption — tax exemption total of items in the exchange item list.
*   `refundValueAddedTax` (_number_) Returning item's value-added tax — VAT for items in the exchange item list.
*   `refundItemTotal` (_number_) Returning item's total — total of items in the exchange item list.
*   `profile` (_Profile_)
*   `refundFees` (_array of RefundFee_) Refund fees applied when cancelling items from an order during the edit order flow.
*   `taxTransaction` (_TaxTransaction_)
*   `externalSessionId` (_string_)
*   `referenceId` (_string_, nullable) Two phase confirmation reference id corresponding to the order that is being confirmed as part of this request, Two phase commit V2 uses this field.
*   `externalCartId` (_string_)
*   `orderLevelGiftWrap` (_OrderLevelGiftWrap_)
*   `paymentInstallment` (_PaymentInstallment_)
*   `paymentInstallmentOptionsList` (_array of PaymentInstallmentOptions_, nullable) List of Payment Installment options available.
*   `isGift` (_boolean_) Flag indicating if order is a gift.  
    Default: `false`.
*   `pickUpDetail` (_OrderPickUpDetail_)
*   `pickUpDetailList` (_array of OrderPickUpDetail_) Pick Up Details.
*   `deliveryZoneId` (_string_) Zone ID for online items that will be delivered.
*   `deliveryZipCodeId` (_string_) Zip code ID for online items that will be delivered.
*   `availableDate` (_integer (int64)_) Available date for online items.
*   `totalAssembledQty` (_number (double)_) Total Assembled quantity for delivery items.
*   `totalBoxedQty` (_number (double)_) Total Boxed quantity for delivery items.
*   `verifiedTenderInfo` (_array of Tender_) Information which was used to verify the tender is available through this list.
*   `authorizedTenderInfo` (_array of Tender_) Information which was used to authorize the tender is available through this list.
*   `summary` (_CartSummary_)
*   `transactionDiscount` (_Discount_)
*   `shippingDisclaimer` (_string_) Shipping Disclaimer.
*   `employee` (_Employee_)
*   `cartType` (_string_, nullable) Used in the backend to determine if the omni flow is active during cart, order, and order post-processing.  
    Allowed values: `REGULAR`, `OMNI`.
*   `displayMessages` (_array of Flash_) Generic field for display messages. The display message is populated to provide helpful information to user. One of the use cases is eligible coupon code which is not applied.
*   `multiShipmentType` (_string_) Multi shipment types as cart can have multiple shipments either with the same address or different addresses.  
    Allowed values: `ORDER_LEVEL`, `DELIVERY_GROUP_LEVEL`.
*   `auxiliaryItemData` (_array of AuxiliaryItemData_) Auxiliary items details support for edit order.
*   `skipAutoPromotion` (_boolean_) Skip auto promotion when the order is edit order.
*   `currentStoreType` (_string_) Store Type belonging to current store requesting cart.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `customerLoyaltyProfile` (_CustomerLoyaltyProfile_)
*   `pointsEarned` (_integer (int32)_, nullable) The number of loyalty points earned in this transaction.
*   `shippingTaxExemption` (_number_, nullable) The tax exemption applied on the Shipping tax.
*   `originalDepositBalance` (_number_)
*   `depositBalance` (_number_)
*   `depositToOrderBalance` (_number_)
*   `returnCustomerInformation` (_ReturnCustomerInformation_)
*   `deltaCart` (_DeltaCart_)
*   `tariffAmount` (_number_)
*   `tariffRate` (_number_)
*   `taxOrVatOverrideRate` (_number_)
*   `partiallyPaidItemList` (_array of Product_)
*   `isWarrantyStale` (_boolean_)
*   `promotionContext` (_array of Promotion_)
*   `promotionContextV2` (_array of Promotion_)
*   `skipDeliveryGroupSPI` (_boolean_)

### SPILoyaltyPoints

*   `pointsEarned` (_integer (int32)_) The number of loyalty points earned for an order, dedicated SPI will give the value for this post Phase I call.

### HttpResponse

*   `statusLine` (_StatusLine_)
*   `statusCode` (_integer (int32)_, write-only)
*   `reasonPhrase` (_string_, write-only)
*   `entity` (_HttpEntity_)
*   `locale` (_object_)
    *   `language` (_string_)
    *   `script` (_string_)
    *   `country` (_string_)
    *   `variant` (_string_)
    *   `unicodeLocaleAttributes` (_array of string_)  
        Unique items.
    *   `unicodeLocaleKeys` (_array of string_)  
        Unique items.
    *   `displayLanguage` (_string_)
    *   `displayScript` (_string_)
    *   `displayCountry` (_string_)
    *   `displayVariant` (_string_)
    *   `displayName` (_string_)
    *   `extensionKeys` (_array of string_)  
        Unique items.
    *   `iso3Language` (_string_)
    *   `iso3Country` (_string_)
*   `protocolVersion` (_ProtocolVersion_)
*   `allHeaders` (_array of Header_)
*   `headers` (_array of Header_, write-only)
*   `header` (_Header_)
*   `params` (_HttpParams_)

### POSCrashDataRequest

*   `data` (_array of POSCrashData_)

### POSVitalsDto

*   `storeId` (_string_) Store ID.
*   `storeAssociateId` (_string_) Store Associate ID.
*   `installationId` (_string_) Unique Installation ID.
*   `storeRegisterId` (_string_) Store Register ID.
*   `lastSeenOn` (_integer (int64)_) Last time this register was online. Represented as milliseconds since epoch.
*   `lastWentOfflineOn` (_integer (int64)_) Last time when register went offline represented as milliseconds since epoch.
*   `lastOnlineOrderPlacedOn` (_integer (int64)_) Last time when an online order was placed. Represented as milliseconds since epoch.
*   `lastOfflineOrderPlacedOn` (_integer (int64)_) Last time when an offline order was placed. Represented as milliseconds since epoch.
*   `buildNumber` (_string_) Build Number.
*   `lastOfflineProductFeedDownloadedOn` (_integer (int64)_) Last time when offline product feed was downloaded. Represented as milliseconds since epoch.
*   `lastOfflineProductFeedItemCount` (_string_) Number of records in offline product feed download.
*   `numberOfOfflineProducts` (_string_) Number of records that were successfully stored in offline product DB stored in the app.
*   `lastOfflineTaxFeedDownloadedOn` (_integer (int64)_) Last time when offline tax feed was downloaded. Represented as milliseconds since epoch.
*   `lastOfflineTaxFeedItemCount` (_string_) Number of records in offline product feed download.
*   `numberOfTaxEntriesInOfflineDB` (_string_) Number of records that were successfully stored in offline tax DB table stored in the app.
*   `numberOfOrdersInOfflineDB` (_string_) Number of orders in offline order DB table stored in the app.
*   `lastOfflineOrderSyncedOn` (_integer (int64)_) Last time when an offline order sync was done. Represented as milliseconds since epoch.
*   `wifiStrength` (_number_) WiFi Signal Strength.
*   `lastNetworkFailureOccurredOn` (_integer (int64)_) Last time when a network failure happened. Represented as milliseconds since epoch.
*   `lastAssociateSignInOccurredOn` (_integer (int64)_) Last time when a store associate signed in to this register. Represented as milliseconds since epoch.
*   `lastAssociateSignOutOccurredOn` (_integer (int64)_) Last time when store associate signed out to this register. Represented as milliseconds since epoch.
*   `lastAssociateToSignIn` (_string_) Last store associate who signed in to this register.
*   `lastAssociateToSignOut` (_string_) Last store associate who signed out of this register.
*   `deviceName` (_string_) POS Register device name.
*   `deviceType` (_string_) POS device type. For example, iPad.
*   `ipAddress` (_string_) POS register IP address.
*   `cashDrawerSerialNumber` (_string_) Serial number of the cash drawer connected to this POS register.
*   `cashDrawerModel` (_string_) Model number of the cash drawer connected to this POS register.
*   `cashDrawerConnectionType` (_string_) Connection type of the cash drawer connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `scannerSerialNumber` (_string_) Serial number of the scanner connected to this POS register.
*   `scannerModel` (_string_) Model number of the scanner connected to this POS register.
*   `scannerConnectionType` (_string_) Connection type of the scanner connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `cardReaderSerialNumber` (_string_) Serial number of the payment card reader connected to this POS register.
*   `cardReaderModel` (_string_) Model number of the payment card reader connected to this POS register.
*   `cardReaderIpAddress` (_string_) IP address of the payment card reader connected to this POS register.
*   `cardReaderConnectionType` (_string_) Connection type of the payment card reader connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `cardReaderIntegrationType` (_string_) Integration type of the payment card reader connected to this POS register, for example, Terminal API or SDK.
*   `receiptPrinterSerialNumber` (_string_) Serial number of the receipt printer connected to this POS register.
*   `receiptPrinterModel` (_string_) Model number of the receipt printer connected to this POS register.
*   `receiptPrinterIPAddress` (_string_) IP address of the receipt printer connected to this POS register.
*   `receiptPrinterConnectionType` (_string_) Connection type of the receipt printer connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `cashDrawerConnected` (_string_) Flag indicating whether cash drawer is connected to this POS register.
*   `cashDrawerConnectedOn` (_integer (int64)_) Last time when cash drawer was connected to this register. Represented as milliseconds since epoch.
*   `cashDrawerConnectionIssue` (_string_) Details about any connect issues related to cash drawer.
*   `printerConnected` (_string_) Flag indicating whether receipt printer is connected to this POS register.
*   `printerLastConnectedOn` (_integer (int64)_) Last time when receipt printer was connected to this register. Represented as milliseconds since epoch.
*   `printerConnectionIssue` (_string_) Details about any connect issues related to receipt printer.
*   `paymentTerminalConnected` (_string_) Flag indicating whether payment terminal is connected to this POS register.
*   `paymentTerminalLastConnectedOn` (_integer (int64)_) Last time when payment terminal was connected to this register. Represented as milliseconds since epoch.
*   `paymentTerminalConnectionIssue` (_string_) Details about any connect issues related to payment terminal.
*   `scannerConnected` (_string_) Flag indicating whether scanner is connected to this POS register.
*   `scannerLastConnectedOn` (_integer (int64)_) Last time when scanner was connected to this register. Represented as milliseconds since epoch.
*   `scannerConnectionIssue` (_string_) Details about any connect issues related to scanner.
*   `lastOfflineAssociatesFeedDownloadedOn` (_integer (int64)_) Last time when offline store associates feed was downloaded to this register. Represented as milliseconds since epoch.
*   `lastOfflineAssociatesItemCount` (_integer (int32)_) Number of offline store associates that were downloaded to this register. This is just the number of records in the download.
*   `numberOfOfflineAssociates` (_integer (int32)_) Number of offline store associates. This is the successfully imported offline associate count.
*   `lastOfflineLoginErrorOccurredOn` (_integer (int64)_) Last time when offline store associate login failed. Represented as milliseconds since epoch.
*   `numberOfPendingOnlineOrders` (_integer (int32)_) Number of pending online orders. This is just to track phase 2 order submission failure.
*   `lastOnlineOrderSyncedOn` (_integer (int64)_) Last time when online orders were synced. Represented as milliseconds since epoch. This is just to track phase 2 order submission failure.
*   `upcScanFailureIssue` (_string_) UPC Scan failure related details. This is different from scanner connection issues.
*   `cardPaymentFailureIssue` (_string_) Card payment failure related details. This is different from payment terminal connection issues.
*   `lastOfflineLoginError` (_string_) Last offline login error details.
*   `offlinePOSVitalsLog` (_OfflinePOSVitalsLog_)
*   `offlineTaxFeedLastUpdatedOn` (_integer (int64)_) Last time when offline tax feed was updated. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline tax feed was last stored. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastDownloadedOn` (_integer (int64)_) Timestamp when the offline tax feed was last downloaded. Represented as milliseconds since epoch.
*   `offlineTaxFeedDbRecordCount` (_integer (int32)_) Number of records in the offline tax feed database.
*   `offlineTaxFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline tax feed.
*   `offlineStoreCredentialsLastStoredOn` (_integer (int64)_) Timestamp when offline store credentials were last stored. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastUpdatedOn` (_integer (int64)_) Timestamp when offline store credentials were last updated. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastDownloadedOn` (_integer (int64)_) Timestamp when offline store credentials were last downloaded. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsDbRecordCount` (_integer (int32)_) Number of records in the offline store credentials database.
*   `offlineStoreCredentialsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline store credentials.
*   `offlineProductFeedLastDownloadedOn` (_integer (int64)_) Last time when offline product feed was downloaded. Represented as milliseconds since epoch.
*   `offlineProductFeedLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product feed was created. Represented as milliseconds since epoch.
*   `offlineProductFeedLastProcessedFileName` (_string_) Name of the last processed file for offline product feed.
*   `offlineProductFeedLastUpdatedOn` (_integer (int64)_) Timestamp when the offline product feed was last updated. Represented as milliseconds since epoch.
*   `offlineProductFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline product feed was last stored. Represented as milliseconds since epoch.
*   `offlineProductFeedDbRecordCount` (_integer (int32)_) Number of records in the offline product feed database.
*   `offlineProductFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product feed.
*   `offlineProductDeltaLastStoredOn` (_integer (int64)_) Timestamp when offline product delta data was last stored. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastUpdatedOn` (_integer (int64)_) Timestamp when offline product delta data was last updated. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedOn` (_integer (int64)_) Timestamp when offline product delta data was last downloaded. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastProcessedFileName` (_string_) Name of the last processed file for offline product delta data.
*   `offlineProductDeltaLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product delta data was created. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product delta data.
*   `offlinePromotionsLastProcessedFileName` (_string_) Name of the last processed file for offline promotions.
*   `offlinePromotionsLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline promotions was created. Represented as milliseconds since epoch.
*   `offlinePromotionsLastDownloadedOn` (_integer (int64)_) Timestamp when offline promotions data was last downloaded. Represented as milliseconds since epoch.
*   `offlinePromotionsLastStoredOn` (_integer (int64)_) Timestamp when offline promotions data was last stored. Represented as milliseconds since epoch.
*   `offlinePromotionsLastUpdatedOn` (_integer (int64)_) Timestamp when offline promotions data was last updated. Represented as milliseconds since epoch.
*   `offlinePromotionsDbRecordCount` (_integer (int32)_) Number of records in the offline promotions database.
*   `offlinePromotionsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline promotions data.

### PromoCodeValidationRequest

*   `promotionCode` (_string_, required) Promotion code to validate.

### PromoCodeValidationResponse

*   `promotionId` (_string_, nullable) If the promotion code is valid, return the promotion ID; otherwise, return empty.
*   `merchantPromotionId` (_string_, nullable) If the promotion code is valid, return the merchant's identifier for the relevant promotion; otherwise, return empty. This is the merchantPromotionId which should have been sent/used during promotion creation/updates.

### SpiGetQuoteResponse

SPI Response object for Get Quote Details operations.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `quote` (_QuotePayload_)
*   `associateSessionId` (_string_, nullable) Associate Session Id.
*   `error` (_boolean_)

### SpiQuoteRequest

Request object for Quote SPI operations.

*   `firstName` (_string_) Customer first name.
*   `lastName` (_string_) Customer last name.
*   `name` (_string_) Customer full name.
*   `email` (_string_) Customer email address.
*   `phone` (_string_) Customer phone.
*   `quoteId` (_string_) Quote ID.
*   `start` (_integer (int32)_) Quote search offset. Used for paginating across multiple quotes.  
    Default: `0`.
*   `limit` (_integer (int32)_) Number of quotes to return. Used for paginating across multiple quotes.  
    Default: `20`.
*   `storeId` (_string_) Store ID. Find quote placed in this store.
*   `customerId` (_string_) Customer ID. Find quotes placed by this customer ID.
*   `productId` (_string_) Product ID. Find quotes containing this product ID.
*   `storeAssociateId` (_string_) Store Associate ID. Find quotes placed by specific store associate.
*   `storeRegisterId` (_string_) Store Register ID. Find quotes placed from specific store register.
*   `quoteDateTimeStampStart` (_integer (int64)_) Find quotes placed on or after this timestamp - represented as milliseconds since epoch.
*   `quoteDateTimeStampEnd` (_integer (int64)_) Find quotes placed or or before this timestamp - represented as milliseconds since epoch.
*   `advanceSearchId` (_string_) Advanced Search Id for changing the page.
*   `source` (_string_) Optional. Only used/expected when Quote SPI (QUOTE\_SERVICE) is configured. Filters quotes by origin.  
    Allowed values: `POS`, `EXTERNAL`, `ALL`, `POS`, `EXTERNAL`, `ALL`.

### SpiQuoteSearchResponse

SPI Response object for Quote search operations.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `quoteList` (_array of QuotePayload_) List of searched quotes.
*   `advanceSearchId` (_string_)
*   `error` (_boolean_)

### SpiRewardLookupRequest

Request to look up rewards based on customer details such as Customer ID or Token value. At least one of the fields is required.

*   `customerId` (_string_) Customer ID.
*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `alias` (_string_) Card Alias/Token Value from the customer card acquisition response.
*   `issuerCountry` (_string_) The Card issuer country.
*   `cardCountryCode` (_string_) The country code present in card acquisition response.

### SpiRewardLookupResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `rewards` (_array of Reward_, required) List of applicable/available rewards earned by the customer. Response is mandatory for a successful response, can be an empty list.
*   `error` (_boolean_)

### ShipmentSpiRequest

*   `shipmentContext` (_string_, required) Shipment context. Provides the context of the request, indicating whether it is related to a BOFIS order or inventory transfer.  
    Allowed values: `ORDER`, `RETURN_TO_VENDOR`, `STORE_TO_STORE_TRANSFER`, `CORP_TRANSFER`.
*   `requestTime` (_integer (int64)_, required) Request time in epoch milliseconds.
*   `storeId` (_string_, required) ID of the store that fulfills the shipment.
*   `storeAssociateId` (_string_, required) ID of the store associate.
*   `orderId` (_string_) Order number of BOFIS order or inventory transfer.
*   `customerName` (_string_) Customer name.
*   `fromAddress` (_SPIAddress_, required)
*   `shippingAddress` (_SPIAddress_, required)
*   `store` (_Store_)
*   `packageDimension` (_PackageDimension_)
*   `itemWeight` (_number_) Total weight of all items in the package.
*   `items` (_array of ShipmentItem_) Items in the package.
*   `packageValue` (_number_) Cost of the package (item total).

### ShipmentLabelSpiResponse

*   `errorMessage` (_string_) Error Message.
*   `errorCode` (_string_) Error Code.
*   `shippingLabelLink` (_string_, required) Link to shipping label image. The image must be in PNG format.
*   `trackingNumber` (_string_) Tracking number corresponding to the shipping label link.
*   `shippingMethod` (_ShippingOption_, required)
*   `packageDimension` (_PackageDimension_, required)
*   `itemWeight` (_number_, required) Replay the provided item weight.

### ShipmentOptionSpiResponse

*   `errorMessage` (_string_) Error Message.
*   `errorCode` (_string_) Error Code.
*   `shippingMethodList` (_array of ShippingOption_, required) Shipping method options.

### ShippingMethodsRequest

*   `customerId` (_string_) Identifier of the customer associated with this cart.
*   `cartItemList` (_array of ShippingSPIProduct_, required) List of items in cart which require shipping to a particular address.

### ShippingMethodsResponse

*   `shippingMethods` (_array of ShippingMethod_) List of all shipping methods that can be applied to cart.

### SpiTaxCalculationRequest

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `taxBuckets` (_array of SpiTaxBucket_, required) All products that require tax calculations are grouped based on their origin and destination addresses, and provided in these tax buckets, along with any applicable tax exemptions.

### SpiTaxResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `taxItems` (_array of TaxOrVatRecord_, required) List of products and their tax rates.
*   `error` (_boolean_)

### DownloadTaxRatesResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `taxRates` (_string_, required) Contains the tax or VAT rates in CSV format. The first line must contain the column headers, and subsequent lines must have the corresponding tax or VAT rate values. Column names are case-sensitive and must adhere to the specified format. All required columns, their specifications, and a sample response are available in the documentation: [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html).
*   `error` (_boolean_)

### SpiTaxSubmissionRequest

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `orderId` (_string_) The order ID corresponding to the transaction which involved the tax calculations with the merchant's tax engine.
*   `taxBuckets` (_array of SpiBucket_) The list of tax buckets which include products , their tax rates, source and destination addresses and tax exemptions if any.

### SpiTaxExemptionResponse

*   `taxExemptions` (_array of SpiTaxExemption_) List of tax exemptions that are supported by the Merchant's tax engine and can be used for tax calculations.Tax exemptions are optional, can have empty response.

### SpiWarrantyCheckRequest

*   `cartId` (_string_, required) Unique identifier for the active cart session.
*   `storeAddress` (_ExternalAddress_, required)
*   `shippingAddress` (_ExternalAddress_)
*   `profile` (_ExternalCustomerProfile_)
*   `cartItemList` (_array of ExternalProduct_, required) Merchandise items currently in the cart. Warranty items (warrantySKU=true) are filtered out before this payload is sent.

### SpiWarrantyCheckResponse

*   `eligibleWarrantyList` (_array of SpiWarrantyCheckResponseItem_) Array of eligible warranty products. Empty array if no warranties apply.
*   `errorMessage` (_string_) Human-readable error message. Presence causes POS to surface an error and abort warranty application.
*   `errorCode` (_string_) Machine-readable error code, for example, SERVICE\_UNAVAILABLE or INVALID\_REQUEST.
*   `error` (_boolean_)

### CartPayload

*   `cartId` (_string_) Cart ID.
*   `suspendedCartId` (_string_, nullable) Unique UUID value present for suspended carts. The value is different from the Cart ID.
*   `storeId` (_string_, nullable) Store ID.
*   `transactionId` (_string_) The unique identifier for this transaction, for example, Void cart.
*   `storeRegisterId` (_string_) Store Register ID. Local to each store.
*   `associateId` (_string_, nullable) Store Associate ID.
*   `cartType` (_string_) The type of cart payload ( Void cart or suspended cart).
*   `cartItemList` (_array of Product_) The list of products added to the cart.
*   `subTotal` (_number_) The subtotal amount of the products added to the cart.
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_) The list of price adjustments done on the items in cart.
*   `orderPriceAdjustments` (_array of OrderPriceAdjustment_) The list of price adjustments done on the total order in the cart.
*   `promotionCodes` (_array of string_) The list of promotion codes applied to the items in cart.
*   `taxTotal` (_number_) The total tax amount for the items in cart.
*   `taxExemption` (_number_) The tax exemption applicable on the items in cart.
*   `transactionDiscountAmount` (_number_) The transaction discount amount for the items in cart.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `shippingTotal` (_number_) The total Shipping amount in case of online orders.
*   `customerEmail` (_string_) The email address of the customer.
*   `profile` (_Profile_)
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the actions performed on the cart. For example, reason for discounts applied to the order.
*   `fullfillmentType` (_string_) The fulfillment type of the order: IN\_STORE or ONLINE.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxRates` (_array of OrderTaxRate_) Sale-side tax rate.
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions.
*   `vatRates` (_array of OrderTaxRate_) Sale-side VAT rate.
*   `netTaxRates` (_array of OrderTaxRate_) Net tax rate calculated based on sale-side tax rate and return-side tax rate.
*   `netVatRates` (_array of OrderTaxRate_) Net VAT rate calculated based on sale-side VAT rate and return-side VAT rate.
*   `amountToBeCharged` (_number_) Amount to be charged.
*   `transactionDiscount` (_Discount_)
*   `exchangeItemRequests` (_array of ExchangeItemRequest_) Request for items that are being returned or exchanged.
*   `summary` (_CartSummary_)
*   `notesList` (_array of OrderNote_, nullable) The order-level notes.
*   `employee` (_Employee_)
*   `transactionStartDate` (_string (date-time)_) The timestamp when the cart was created.
*   `transactionDate` (_string (date-time)_) The timestamp when the cart was voided or suspended.
*   `rewardList` (_array of Reward_, nullable) List of rewards applied to the cart.
*   `tariffAmount` (_number_, nullable) Tariff amount applied to the cart.
*   `tariffRate` (_number_, nullable) Tariff rate applied to the cart.
*   `customerLoyaltyProfile` (_CustomerLoyaltyProfile_)
*   `loyaltyId` (_string_, nullable) Loyalty ID of the customer.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup details for the cart.
*   `shippingMethod` (_ShippingMethod_)
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

### PromotionWebhookPayload

Payload delivered to external systems via the promotion webhook for CREATE, UPDATE, and DELETE events.

*   `promotionEventType` (_string_, required) Type of promotion lifecycle event: CREATE, UPDATE, or DELETE.  
    Allowed values: `CREATE`, `UPDATE`, `DELETE`.
*   `promotions` (_array of SpiPromotion_, required) List of promotions included in this event.
*   `user` (_string_, nullable) CMS user ID who triggered this event (create, update, or delete).
*   `eventTimestamp` (_integer (int64)_, required) Unix epoch timestamp (milliseconds) indicating when this event was generated.

### EReceiptQuoteRequest

*   `emailTo` (_array of string_) Emails to receive quote.
*   `quotePayload` (_QuotePayload_)

### QuotePayload

*   `cartId` (_string_) Cart ID.
*   `suspendedCartId` (_string_, nullable) Unique UUID value present for suspended carts. The value is different from the Cart ID.
*   `storeId` (_string_, nullable) Store ID.
*   `transactionId` (_string_) The unique identifier for this transaction, for example, Void cart.
*   `storeRegisterId` (_string_) Store Register ID. Local to each store.
*   `associateId` (_string_, nullable) Store associate ID.
*   `cartType` (_string_) The type of cart payload ( Void cart or suspended cart).
*   `cartItemList` (_array of Product_) The list of products added to the cart.
*   `subTotal` (_number_) The subtotal amount of the products added to the cart.
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_) The list of price adjustments done on the items in cart.
*   `orderPriceAdjustments` (_array of OrderPriceAdjustment_) The list of price adjustments done on the total order in the cart.
*   `promotionCodes` (_array of string_) The list of promotion codes applied to the items in cart.
*   `taxTotal` (_number_) The total tax amount for the items in cart.
*   `taxExemption` (_number_) The tax exemption applicable on the items in cart.
*   `transactionDiscountAmount` (_number_) The transaction discount amount for the items in cart.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `shippingTotal` (_number_) The total Shipping amount in case of online orders.
*   `customerEmail` (_string_) The email address of the customer.
*   `profile` (_Profile_)
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the actions performed on the cart. For example, reason for discounts applied to the order.
*   `fullfillmentType` (_string_) The fulfillment type of the order: IN\_STORE or ONLINE.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxRates` (_array of OrderTaxRate_) Sale-side tax rate.
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions.
*   `vatRates` (_array of OrderTaxRate_) Sale-side VAT rate.
*   `netTaxRates` (_array of OrderTaxRate_) Net tax rate calculated based on sale-side tax rate and return-side tax rate.
*   `netVatRates` (_array of OrderTaxRate_) Net VAT rate calculated based on sale-side VAT rate and return-side VAT rate.
*   `amountToBeCharged` (_number_) Amount to be charged.
*   `transactionDiscount` (_Discount_)
*   `exchangeItemRequests` (_array of ExchangeItemRequest_) Request for items that are being returned or exchanged.
*   `summary` (_CartSummary_)
*   `notesList` (_array of OrderNote_, nullable) The order-level notes.
*   `employee` (_Employee_)
*   `transactionStartDate` (_string (date-time)_) The timestamp when the cart was created.
*   `transactionDate` (_string (date-time)_) The timestamp when the cart was voided or suspended.
*   `rewardList` (_array of Reward_, nullable) List of rewards applied to the cart.
*   `tariffAmount` (_number_, nullable) Tariff amount applied to the cart.
*   `tariffRate` (_number_, nullable) Tariff rate applied to the cart.
*   `customerLoyaltyProfile` (_CustomerLoyaltyProfile_)
*   `loyaltyId` (_string_, nullable) Loyalty ID of the customer.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup details for the cart.
*   `shippingMethod` (_ShippingMethod_)
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address and corresponding shipping method.
*   `quoteId` (_string_) Quote ID.
*   `externalQuoteId` (_string_, nullable) External quote ID.
*   `customerId` (_string_, nullable) Customer ID.
*   `customerName` (_string_, nullable) Customer Name.
*   `customerPhone` (_string_, nullable) Customer Phone.
*   `createdTs` (_integer (int64)_) Created timestamp in epoch milliseconds.
*   `lastUpdatedTs` (_integer (int64)_) Last updated timestamp in epoch milliseconds.

### ExternalWebhookMonitoringMessage

*   `monitoringEvent` (_string_)  
    Allowed values: `THRESHOLD_EXCEED`, `RECEIVED_ERROR`.
*   `latencyThreshold` (_integer (int64)_)
*   `responseTime` (_integer (int64)_)
*   `httpErrorCode` (_integer (int32)_)
*   `integrationType` (_string_)  
    Allowed values: `FORM_POST`, `HTTP_GET`, `HTTP_PUT`, `HTTP_POST`, `HTTP_DELETE`.
*   `url` (_string_)
*   `apiKey` (_string_)

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### Shipment

Shipment details.

*   `poNumber` (_string_) Purchase Order Number.
*   `uploadNumber` (_string_) Unique identifier for the upload batch, used to group related corporate transfers.
*   `shipFrom` (_IMSAddress_)
*   `shipTo` (_IMSAddress_, required)
*   `orders` (_array of Order_, required) List of orders contained in the shipment.

### PartialCycleCountCriteria

Partial cycle count is done on the products which satisfy the selection criteria. The selection criteria is based on any one of the product attributes.

*   `attribute` (_string_, required, write-only) A product attribute used to determine the products that require cycle count. POS product has multiple attributes like brand, category, color, size, etc. Refer to the create product API (POST /merchant/{version}/products). Note: To utilize any product attribute, it must first be included in the product feed.  
    Example: `brand`.
*   `values` (_array of string_, required, write-only) List of values corresponding to the attribute. The values must match those provided in the product feed.
    
    Each item: Value corresponding to the attribute. The value must match those provided in the product feed.
    
      
    Items: Example: `[Rolex,Timex]`. Example: `[Rolex,Timex]`.

### MerchantProduct

List of products.

*   `productId` (_string_, required) Distinct product ID for each combination of variations, for example, size or color.  
    Example: `3661601595547`.
*   `title` (_string_, required) Product title.  
    Example: `E18PENDANT1`.
*   `description` (_string_, required) Product description.  
    Example: `Number 1 medallion`.
*   `productClass` (_string_, required) Product class of the item.  
    Example: `Merchandise`.
*   `categories` (_array of string_) Merchant categories of the product. A pipe-separated list of category names belongs to this product.  
    Items: Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`.
*   `googleCategory` (_string_) Product categories for Google search.  
    Example: `Accessories > Categories > Jewelry`.
*   `imageUrl` (_string_) Image url of the product.  
    Example: `https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html`.
*   `additionalImageUrls` (_array of string_) Additional image urls of the product.  
    Items: Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`.
*   `condition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`, `NEW, USED, REFURBISHED` . Example: `NEW`.
*   `availability` (_string_) Free text value that provides information about the availability of the product.  
    Example: `Available`.
*   `listPrice` (_number (double)_, required) Listing price of the product.  
    Example: `60`.
*   `salePrice` (_number (double)_, required) Sale price of the product. It can be same as listing price.  
    Example: `60`.
*   `storePrice` (_number (double)_) Store specific price of the product.  
    Example: `55`.
*   `currencyCode` (_string_) ISO currency code.  
    Default: `USD`. Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `brand` (_string_) Brand of the product.  
    Example: `Gucci`.
*   `gtin` (_string_) Product's GTIN. Possible values are: UPC, EAN, JAN, ISBN, and ITF-14.  
    Minimum length: 12. Maximum length: 14. Example: `065100004327`.
*   `mpn` (_string_) Manufacturer part number.  
    Example: `100-440-0.750-3434-A`.
*   `gender` (_string_) Free text to provide gender related to the product.  
    Example: `Unisex`.
*   `ageGroup` (_string_) Free text to provide age group related to the product.  
    Example: `10-45`.
*   `subVariantGroupId` (_string_) ID of the subvariant group.
*   `variantGroupId` (_string_, required) Group ID of the product. All the different variations of the product are grouped together under a single group ID.  
    Example: `E18PENDANT1`.
*   `color` (_string_) Product color.  
    Example: `Silver`.
*   `colorSwatchUrl` (_string_) The image link for color swatches.
*   `size` (_string_) Product size.  
    Example: `M`.
*   `pattern` (_string_) Free text to provide the product pattern.  
    Example: `Oval`.
*   `sku` (_string_) SKU Id of the product. It can be same as product Id and unique per variation of the product.  
    Example: `3661601595547`.
*   `isOnSale` (_boolean_, required) Specifies whether the product is on sale.  
    Example: `false`.
*   `promotionTitle` (_string_, nullable) Promotion title applicable to the product.  
    Example: `Summer22`.
*   `promotionPrice` (_number (double)_, nullable) Discounted price after applying promotion corresponding to the promotion title.  
    Example: `55`.
*   `customString0` (_string_, nullable) Custom field of type String.
*   `customString1` (_string_, nullable) Custom field of type String.
*   `customString2` (_string_, nullable) Custom field of type String.
*   `customString3` (_string_, nullable) Custom field of type String.
*   `customString4` (_string_, nullable) Custom field of type String.
*   `customString5` (_string_, nullable) Custom field of type String.
*   `customString6` (_string_, nullable) Custom field of type String.
*   `customString7` (_string_, nullable) Custom field of type String.
*   `customString8` (_string_, nullable) Custom field of type String.
*   `customString9` (_string_, nullable) Custom field of type String.
*   `customString10` (_string_, nullable) Custom field of type String.
*   `customString11` (_string_, nullable) Custom field of type String.
*   `customString12` (_string_, nullable) Custom field of type String.
*   `customInt0` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customInt1` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customDecimal0` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDecimal1` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDateTime0` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `customDateTime1` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `onlineInventory` (_integer (int32)_, nullable) The current online inventory. You must provide a value if online inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `material` (_string_, nullable) Product material.  
    Example: `Metal`.
*   `manufacturer` (_string_, nullable) Manufacturer of the product.  
    Example: `ABC Jewellers`.
*   `sizeGuideUrl` (_string_, nullable) Image URL of the size guide.
*   `manufacturerDetails` (_string_, nullable) Manufacturer details.
*   `manufacturerLocation` (_string_, nullable) Location of product manufacturer.
*   `productLocation` (_string_, nullable) Product manufacturing location.
*   `banner` (_string_, nullable) Banner text. If provided, banner text is shown on PLP and PDP screens.
*   `availableStores` (_array of string_, nullable) List of stores where the product is available.
*   `lastUpdate` (_string (date-time)_)
*   `storeInventory` (_integer (int32)_, nullable) The current store inventory. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `isVirtual` (_boolean_, nullable) Specifies whether the product is available only in online mode.
*   `multipleGTINs` (_array of string_, nullable) If the product supports multiple GTINs, provide all of them.
*   `storeProductDetails` (_StoreProductDetails_)
*   `onlineAvailableStores` (_array of string_, nullable) List of stores where online products are available.
*   `costPrice` (_number (double)_, nullable) Cost per item.
*   `casePackQuantity` (_integer (int32)_, nullable) Number of items per case pack.
*   `additionalCharges` (_string_, nullable) Additional charges for CA, FR.
*   `casePackID` (_string_, nullable) Identifier for case pack.
*   `availabilityStartTime` (_string (date-time)_, nullable) Start time, when product is visible on POS.
*   `availabilityEndTime` (_string (date-time)_, nullable) End time, when product will not be visible on POS.

### FeedSource

*   `feedType` (_string_)  
    Allowed values: `PRODUCT`, `PRODUCT_BUNDLE`, `STORE`, `LAYOUT`, `PRODUCT_PROMOTION`, `PRODUCT_CATEGORY`, `PRODUCT_CATEGORY_PROMOTION`, `PROMOTION`, `STORE_INVENTORY_FULL`, `STORE_INVENTORY_DELTA`, `SOCIAL_MEDIA`, `ONE_TIME_PROMOTION_CODE`, `PRODUCT_DELTA`, `CATEGORY`, `ORDER_LIST`, `ORDER_DETAILS`, `RECOMMENDATION`, `TAX_RATE`, `PIPELINE`, `STORE_ASSOCIATES`, `PREDICTSPRING_PROMOTION`, `REWARD`, `CASH_REWARD`, `ASN`, `CORP_TRANSFER`, `POS_PROVISIONING`, `SYNONYM`, `STORE_AREA_GOAL`, `STORE_AREA_HIERARCHY`, `OMS`, `PRODUCT_PRICING`, `PRODUCT_SIZING`, `PRODUCT_INVENTORY`, `PRODUCT_PRICING_DELTA`, `PRODUCT_SIZING_DELTA`, `PRODUCT_INVENTORY_DELTA`, `STORE_DEVICE`, `BOPIS_CANCEL_ORDER`, `PURCHASE_ORDER`, `OFFLINE_PROMOTION`, `PREDICTSPRING_PROMOTION_V2`, `EXPIRED_PAYMENT_LINK_CLEANUP`, `SINGLE_USE_PROMO_CODES`, `STORE_GROUP_FULL`, `STORE_GROUP_DELTA`.
*   `feedSourceName` (_string_)
*   `feedSourceType` (_string_)  
    Allowed values: `URL`, `SFTP`, `FTP`, `S3`, `YEXT`, `AVALARA`, `SABRIX`, `AVALARA_V2`, `VERTEX`, `SPI`, `WEBDAV`.
*   `fileNames` (_array of string_)
*   `feedFileType` (_string_)  
    Allowed values: `CSV`, `TSV`, `SSV`, `PSV`, `XML`, `STORE_XML`, `INVENTORY_XML`, `JSON`, `YEXT`, `ASN_EDI_856`, `OTHER`.
*   `feedPreprocessorClass` (_string_)
*   `feedFileMetadataList` (_array of FeedFileMetadata_)
*   `baseURL` (_string_)
*   `urlRequestParams` (_string_)
*   `folderName` (_string_)
*   `host` (_string_)
*   `port` (_integer (int32)_)
*   `userName` (_string_)
*   `password` (_string_)
*   `s3FeedTimestamp` (_integer (int64)_)
*   `parentTag` (_string_)
*   `multiValueFieldList` (_array of string_)
*   `preserveIfNullFieldList` (_array of string_)
*   `currencyCode` (_string_)
*   `idColumn` (_string_)
*   `multiValueFieldDelimiter` (_string_)
*   `columnNames` (_string_)
*   `promotionId` (_string_)
*   `deleteFeed` (_boolean_)
*   `addFeed` (_boolean_)
*   `updateFeed` (_boolean_)
*   `fullFeed` (_boolean_)
*   `sourceEncoding` (_string_)
*   `maxRecordsToProcess` (_integer (int32)_)
*   `apiKey` (_string_)
*   `version` (_string_)
*   `categoryProductRankColumnName` (_string_)
*   `productIdFieldName` (_string_)
*   `feedName` (_string_)
*   `feedDescription` (_string_)
*   `isProductBundleCategorySource` (_boolean_)
*   `importPromotions` (_boolean_)
*   `hasCategories` (_boolean_)
*   `shouldProcessCategoryCounts` (_boolean_)
*   `skipFields` (_string_)
*   `hasProductMultiPromotions` (_boolean_)
*   `fieldDelimiter` (_string_)
*   `endLineDelimiter` (_string_)
*   `deviceOS` (_string_)
*   `dataSource` (_string_)  
    Allowed values: `NETSUITE`.
*   `accountId` (_string_)
*   `licenseKey` (_string_)
*   `merchantReferenceCode` (_string_)
*   `bulkProcessing` (_boolean_)
*   `backUp` (_boolean_)
*   `continueOnFileError` (_boolean_)
*   `clientId` (_string_)
*   `clientSecret` (_string_)
*   `hasActualInventoryCount` (_boolean_)
*   `oauthHost` (_string_)

### CombinationGroup

Products that receive the discount when the qualifying condition is met.

*   `quantity` (_integer (int32)_)
*   `quantityOperator` (_string_)  
    Allowed values: `EQL`, `GTE`.
*   `productRules` (_array of PromotionRule_)

### PromotionRule

Promotion rule provides the filtering criteria to determine if the order is eligible for promotion.

*   `promotionRuleId` (_string_)
*   `promotionId` (_string_)
*   `operator` (_string_, nullable) Operation to be performed for the rule depending on the value types.  
    Allowed values: `DOES_NOT_CONTAIN`, `CONTAINS`, `GTE`, `LTE`, `EXISTS`, `NOT_EXISTS`.
*   `value` (_array of string_, nullable) Values are based on the value Types. They contain a list and for single value attributes use a list of size 1.  
    Unique items.
*   `valueType` (_string_, nullable) Value Type provides the type of value.

### TierGroup

*   `amountExpression` (_string_)
*   `tierRules` (_array of PromotionRule_)
*   `id` (_string_)
*   `selectedProducts` (_array of string_)

### PromotionLanguageData

Promotion attributes in additional languages.

*   `promotionId` (_string_)
*   `language` (_string_) The language/locale of properties for this object.
*   `name` (_string_) The name used for internal identification of the promotion. This field can also be used to assign a locale/language-specific name for the promotion.
*   `title` (_string_) The locale/language-specific title used for external display of the promotion on the presentation layer.
*   `description` (_string_) The locale/language-specific description used for external display of the promotion on the presentation layer. This contains the disclaimer and other information.

### PromotionMapping

*   `quantityOperator` (_string_)  
    Allowed values: `EQL`, `GTE`.
*   `merchantId` (_string_)
*   `type` (_string_)  
    Allowed values: `QUALIFYING_GROUP`, `DISCOUNTED_GROUP`, `TIER_GROUP`, `FREE_SAMPLES`.
*   `promotionRulesGroupId` (_string_)
*   `promotionMappingId` (_string_)
*   `promotionId` (_string_)
*   `amountExpression` (_string_)
*   `quantity` (_integer (int32)_)
*   `locale` (_string_)
*   `region` (_string_)

### PromotionCode

*   `merchantId` (_string_)
*   `region` (_string_)
*   `promotionId` (_string_)
*   `oneTimeCode` (_string_)
*   `oneTimeCodeCS` (_string_)
*   `codeType` (_string_)
*   `externalId` (_string_)
*   `codeAssignedDate` (_string (date-time)_)
*   `codeRedeemed` (_boolean_)
*   `codeRedeemedDate` (_string (date-time)_)
*   `storeCode` (_string_)
*   `promotionValidDate` (_string (date-time)_)
*   `type` (_string_)
*   `message` (_string_)
*   `validFrom` (_string (date-time)_)
*   `validTo` (_string (date-time)_)
*   `updatedOn` (_string (date-time)_)

### Pageable

*   `pageSize` (_integer (int32)_)
*   `pageNumber` (_integer (int32)_)
*   `paged` (_boolean_)
*   `unpaged` (_boolean_)
*   `offset` (_integer (int64)_)
*   `sort` (_Sort_)

### OneTimePromotionCodeResponse

*   `oneTimeCode` (_string_)
*   `status` (_string_)  
    Allowed values: `VALID`, `REDEEMED`, `NOT_FOUND`.
*   `promoName` (_string_)
*   `promotionId` (_string_)
*   `orderId` (_string_)
*   `codeRedeemedDate` (_integer (int64)_)
*   `storeId` (_string_)

### Sort

*   `unsorted` (_boolean_)
*   `sorted` (_boolean_)
*   `empty` (_boolean_)

### OneTimePromotionCodeUpsertVO

*   `errorMessage` (_string_)
*   `errorCode` (_string_)
*   `oneTimePromotionCode` (_string_)

### DataFeedFile

*   `dataStream` (_object_)
*   `fileName` (_string_)
*   `originalFileName` (_string_)
*   `length` (_integer (int64)_)
*   `contentType` (_string_)
*   `s3Reference` (_string_)

### ContentDisposition

*   `type` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    
*   `fileName` (_string_)
*   `creationDate` (_string (date-time)_)
*   `modificationDate` (_string (date-time)_)
*   `readDate` (_string (date-time)_)
*   `size` (_integer (int64)_)

### MediaType

*   `type` (_string_)
*   `subtype` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    
*   `wildcardType` (_boolean_)
*   `wildcardSubtype` (_boolean_)

### MessageBodyWorkers

### MultiPart

*   `contentDisposition` (_ContentDisposition_)
*   `entity` (_object_)
*   `headers` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of string`.
    
*   `mediaType` (_MediaType_)
*   `messageBodyWorkers` (_MessageBodyWorkers_)
*   `parent` (_MultiPart_)
*   `providers` (_Providers_)
*   `bodyParts` (_array of BodyPart_)
*   `parameterizedHeaders` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of ParameterizedHeader`.
    

### Providers

### FormDataContentDisposition

*   `type` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    
*   `fileName` (_string_)
*   `creationDate` (_string (date-time)_)
*   `modificationDate` (_string (date-time)_)
*   `readDate` (_string (date-time)_)
*   `size` (_integer (int64)_)
*   `name` (_string_)

### ParameterizedHeader

*   `value` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    

### PromotionUploadStatus

List of promotion status.

*   `promotionId` (_string_) The ID of the promotion passed by CMS.
*   `status` (_string_) The upload status of the related promotion ID: Success or Failure.  
    Allowed values: `SUCCESS`, `FAILURE`.
*   `exception` (_string_) Exception messages.
*   `promotionTitle` (_string_) The title of the promotion.
*   `errors` (_array of string_) List of errors.

### ClearanceItem

Product location within the store.

*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `clearancePrice` (_number_)
*   `itemLocationWithinStore` (_string_)
*   `instructionText` (_string_)

### ShipmentDetail

Shipping details applicable for store fulfillment order. If CMS flag 'Allow multiple shipments per cart/order' is enabled, the shipment will be populated. Refer to deliveryGroupList for more details on this CMS flag.

*   `shipmentId` (_string_, required) Shipment ID. Unique number.
*   `trackingNumber` (_string_, required) Shipment tracking number entered by store associate during fulfillment from the store.
*   `shippingMethodId` (_string_, required) Shipping method ID used during placing order. Mandatory.
*   `shippingName` (_string_) Shipping name. Optional.  
    Example: `Express shipping`.
*   `shippingDescription` (_string_) Shipping description. Optional.  
    Example: `Express shipping arrives in 2-3 business days`.
*   `shippingCarrier` (_string_, required) Shipping carrier code. Mandatory.  
    Example: `UPS`.
*   `shippingServiceLevel` (_string_) Shipping service level. Optional.  
    Example: `3 Business Days`.
*   `price` (_number_, required) Shipping Cost. Mandatory.
*   `deliveryDate` (_integer (int64)_) Delivery date in epoch.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.
*   `items` (_array of DeliveryItem_) List of items in this shipment. This can be a subset of the product list provided at the order level.
*   `shippingAddress` (_Address_, required)
*   `expectedShippingDate` (_integer (int64)_) Expected shipping date in epoch. Used for SLA calculation in BOFIS orders.

### OrderPaymentDetail

Deprecated. Use 'tenders' instead.

*   `transactionId` (_string_, required) The unique identifier for a transaction that completes the order. - This is particularly helpful in cases where a payment is made in multiple transactions, such as in the case of a deposit. - In POS, the transaction ID corresponds to the sale transaction when you place an order. - However, if you import an order from an external system, the transaction ID should correspond to the order in the external system and can be the same as the Order ID.  
    Maximum length: 128.
*   `paymentId` (_string_, required) The unique identifier for a payment/tender. As the order can have multiple payments, each payment will have a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method. Required for BOPIS and BOFIS. Not applicable for ROPIS.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. Possible values are: - `UNPROCESSED` is used internally by cloud services as a transient state. - `DISCARDED` is used when cash tender is part of a multi-tender payment and is deleted by swiping right. - `ABORTED` is used when we internally remove a tender from the tender list and add a new tender (e.g., for gift cards).  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device. If the payment is made in an external system, set the payment device to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards and gift cards through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender. Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender. Applicable for credit cards. for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal. Typically used for referenced refunds that are performed automatically by the POS without the customer presenting the card during a refund. In the case of Adyen payments, this field maps to `pspReference`. Required for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode, it generates a temporary payment ID, which is provided in the alternate payment request ID attribute. For example, the Adyen terminal generates a temporary ID called a "tender reference" whenever it goes into store and forward mode. This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund payment request ID issued by the payment gateway/terminal. Required for refund on credit cards.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item, and the original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried forward to the new order. This attribute provides the original order ID if the tender is carried over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item. The original order is updated to a returned or exchanged status. Additionally, the tender value of the replacement item's cost is carried over to the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and the tender is carried over to the new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Required for credit card payments using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment. For example, if a customer pays with cash first and the remaining amount with a credit card, the cash tender should have a paymentSequenceNumber of 1, and the credit card tender should have a paymentSequenceNumber of 2.
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number. Applicable when payment method is 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check' and 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.
*   `cardToken` (_string_) This field contains the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment** Gateways > Adyen > Payment Tokenization Events).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender. Normally, it is received after calling a call center agent of a payment processor. For example: call for authorization code after check denial or referral, or manual authorization code for a credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Required for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee. Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to finance approval/order/confirmation number in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### CustomerProfile

Profile for the customer.

*   `customerId` (_string_, required) Customer ID.
*   `email` (_string_, required) Customer Email ID.
*   `firstName` (_string_, required) Customer first name.
*   `lastName` (_string_, required) Customer last name.
*   `phoneMobile` (_string_, nullable) Customer's Phone#.

### PickupDetail

Pickup information for store pickup order.

*   `storeId` (_string_) Store Id.
*   `firstName` (_string_) First name of pickup person.
*   `lastName` (_string_) Last name of pickup person.
*   `email` (_string_, nullable) Email of pickup person.
*   `phone` (_string_, nullable) Phone of pickup person.
*   `pickupDate` (_integer (int64)_, nullable) Customer pickup date & time. Milliseconds since epoch.

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### FulfillmentProduct

Item list.

*   `productId` (_string_, required) Product Id.  
    Example: `N0345123`.
*   `orderItemId` (_string (The value should be numeric in string format)_, required) Item sequence/system generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `itemStatus` (_string_, required) Store fulfillment status. Possible values are: 1. **PACK**: The BOPIS, BOFIS, or ROPIS item is packed by a store associate. 2. **DELIVERED**: The BOPIS item is picked up by the customer or a designated pickup person. 3. **CANCELED**: The BOPIS or BOFIS item is canceled by a store associate. 4. **SHIPPED**: The BOFIS item is shipped by a store associate. 5. **READY**: When importing a fulfillment order into POS, it must have a **READY** status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`. Example: `PACK`.
*   `name` (_string_, required) Item name.  
    Example: `White Shirt`.
*   `quantity` (_integer (int32)_, required) Item quantity. This represents the original quantity. If the store setting `treatEachItemInCartAsSeparateLineItem` is enabled in CMS, then the quantity should be 1 per line item. This setting can be found in: **CMS** > **Store Management** > **Store Settings** > **OMS** > **Advanced**.  
    Example: `1`.
*   `price` (_number_, required) Item price.  
    Example: `12.05`.
*   `total` (_number_, required) Item total after discount and taxes.  
    Example: `14`.
*   `adjustedQuantity` (_integer (int32)_, required, read-only) Packed quantity for a PACK event, picked-up quantity for a DELIVERED event, and shipped quantity for a SHIPPED event.

### CancelItem

Item to be canceled in an order.

*   `productId` (_string_, required) Product ID.  
    Example: `PROD-123`.
*   `orderItemId` (_string_, required) Order Item ID.  
    Example: `1`.
*   `quantity` (_integer (int32)_, required) Quantity to cancel.  
    Example: `2`.
*   `reasons` (_array of Reason_) List of reasons for cancellation.

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderProduct

A list of products in this order, including returned and non-returned items. It also provides details of price adjustments, if any, applied to the items.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orignalQuantity` (_integer (int32)_)
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ReturnedProduct

List of items that have been returned. While importing an order from an external system, it is optional as the products and return products both can be provided in orderProductList.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `refundDate` (_integer (int64)_, required) The date and time, in milliseconds since epoch, when the item was returned.  
    Example: `1617222000000`.
*   `exchangedForOrderId` (_string_, nullable) The order ID for which the item was exchanged. Applicable for exchange.  
    Maximum length: 128.
*   `returnedAtStoreId` (_string_, required) The store ID where the item was returned.  
    Maximum length: 256.
*   `returnProcessedByAssociateId` (_string_, required) ID of the store associate who performed the return.  
    Maximum length: 256.
*   `returnedAtStoreRegisterId` (_string_, required) The register ID where the item was returned.  
    Maximum length: 128.
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `offlineMode` (_boolean_, nullable) Specifies whether the item is returned in offline mode. If not provided, it is considered to be in online mode.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderRefundPaymentDetail

Refund payments.  
For return or exchange transactions, this contains the refund payments.  

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) A transaction ID is a unique identifier corresponding to the return  
    transaction. It is especially useful in situations where a refund is issued in multiple  
    return transactions. When importing an order from an external system and it has a refund,  
    the transaction ID should match the return transaction that carried out the refund.  
    In case the external system doesn't have a return transaction ID, you can use the order  
    ID in its place.  
    Maximum length: 128.
*   `paymentId` (_string_, required) It is a unique identifier for refund payments.  
    It must be unique within an order. When multiple refunds are issued for a single payment,  
    a unique ID is necessary to differentiate each refund.  
    Maximum length: 128.
*   `cardNumber` (_string_, nullable) Card Number to which refund was applied. Last 4 digits in case of refund to CreditCard. Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardType` (_string_, nullable) Card type, for example, mastercard, interac\_card, or visa.  
    Applicable for CreditCard refunds only.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `originalPaymentId` (_string_, required) A refund is issued against a original payment.  
    This ID provides a reference to the original payment.  
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Reference to original transaction that performs the payment.  
    This ID provides a reference to the original transaction.
*   `paymentMethod` (_string_, required) Refund payment method, for example, Cash or CreditCard.  
    For possible values, see the tenders.paymentMethod attribute.
*   `refundDate` (_string (date-time)_, required, nullable) Timestamp when refund payment was processed.Format: yyyy-MM-dd HH:mm:ss.
*   `refundedAmount` (_number_, required) Refund Amount.  
    Example: `100`.
*   `refundedAsPartOfOrderId` (_string_, nullable) Original Order Id for which this refund payment is processed.  
    Maximum length: 128.
*   `refundRequestId` (_string_, nullable) Refund request identification issued by the payment gateway/terminal.  
    In the case of Adyen payments, this field maps to pspReference of a refund.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use RefundMode instead.
*   `paymentDevice` (_string_, nullable) Device using which payment was refunded. For possible values, please refer to tenders.paymentDevice attribute. Applicable for CreditCard refund only.  
    Maximum length: 32.
*   `paymentDeviceId` (_string_, nullable) Payment Device Identifier. Applicable for CreditCard refund only.  
    Maximum length: 128.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt lines for refund payment.  
    Available in case of unreferenced refunds using CreditCard.  
    Unreferenced refunds are refunds that are not associated with a original payment and  
    customer is prompted to swipe/tap CreditCard during refund.  
    When an order is imported from an external system, it is optional.  
    
*   `cardExpirationMonth` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration month of the card to which payment was refunded.
*   `cardExpirationYear` (_integer (int32)_, nullable, deprecated) Deprecated: Expiration year of the card to which payment was refunded.
*   `roundingAmount` (_number_, nullable) Rounding amount during refund using cash. Applicable for cash refund  
    in regions where rounding is applicable.
*   `refundMode` (_string_, nullable) Refund Mode. It is applicable for CreditCard refunds. The modes are:  
    1\. Unreferenced: Refund is not associated to original payment and is issued on different credit card  
    2\. External: Refund is initiated externally and not by POS  
    3\. Default: Regular refund. It is initiated by POS against original CreditCard  
    It is not necessary to provide this while importing an order from external system.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `fundingSource` (_string_, nullable) Funding source, for example, CREDIT, DEBIT, or CHARGED.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `tip` (_number_) Refunded Tip.
*   `tenderBalance` (_number_) Gift Card balance after refund. Available in case of Gift Card refund.
*   `cardAlias` (_string_, nullable) Card alias of the card to which payment was refunded.
*   `externalPaymentSystemId` (_string_, nullable) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_, nullable) External payment reference identifier in case of External tender.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderActivityLog

The list of transactions that have happened so far on the order in descending form. It is used to track the order activities like order creation, order update, order return, etc. It is mandatory while exporting order from POS to external system and optional while importing order from external system to POS. If it is not provided during order import from external system, POS system generates it using other available attributes from the order.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_, required) The unique Id identifying the transaction.  
    Maximum length: 128. Example: `2808-10-20240419131925-2-7`.
*   `amount` (_number_, nullable) The total transaction amount value.
*   `associateSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `data` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `installationId` (_string_, required, read-only) Unique ID of the register.  
    Maximum length: 128.
*   `productId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `storeAssociateId` (_string_, nullable) The Id of the particular associate at a store.
*   `storeId` (_string_, nullable) The identifier of the store where the order is taking place.  
    Maximum length: 128.
*   `transactionDate` (_string (date-time)_, required) Transaction time, that is, the time when the transaction was executed.
*   `transactionType` (_string_, nullable) The type of transaction. Three types of transactions can be done on an order: SALE, RETURN, and EXCHANGE.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.
*   `userSessionId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `appTransactionId` (_string_, nullable) Unique sequence number generated by POS App. It is reset after daily or relaunch of the App.  
    Maximum length: 48. Example: `1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ...`.
*   `transactionData` (_Transaction_, required)
*   `manualReceiptId` (_string_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `s3KeyTransactionData` (_string_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `transactionStartDate` (_string (date-time)_, nullable, deprecated) Legacy attribute not in-use anymore.
*   `receiptPrintCount` (_integer (int32)_, nullable, deprecated) Internal attribute. Don't use in external systems.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### OrderFiscalData

All fiscal data for this order if any.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier which lead to this payment capture/refund.
*   `transactionType` (_string_) Transaction Type.
*   `fiscalData` (_string_) Fiscalization Data.
*   `printData` (_array of PrintData_) Fiscalization Data that needs to be printed on receipt.
*   `fiscalTransactionId` (_string_) Fiscal Transaction ID.
*   `receiptPrintCount` (_integer (int32)_) Combined Count of transaction paper/e-receipts.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### OrderReturnCustomerInformation

List of customer/person who returned the items. Applicable if the order has returned items and if the merchant is configured to capture returning customer's details.

*   `orderId` (_string_) Order Identifier.
*   `transactionId` (_string_) Transaction Identifier.
*   `firstName` (_string_) First name of the person.
*   `lastName` (_string_) Last name of the person.
*   `email` (_string_) Email of the person.
*   `phone` (_string_) Phone number of the person.
*   `addressLine1` (_string_) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_) City.
*   `state` (_string_) State.
*   `postalCode` (_string_) Postal Code.
*   `country` (_string_) Country.
*   `idType` (_string_) ID Type.
*   `idValue` (_string_) ID Value.
*   `idIssuedBy` (_string_) ID Issued By.
*   `idExpiry` (_string (date-time)_) ID Expiry Date.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### TaxFreeDocument

Tax-free document associated with this order.

*   `docId` (_string_) Global Blue tax-free document identifier.
*   `status` (_string_) Current status of the tax-free document (ISSUED or VOIDED).  
    Allowed values: `ISSUED`, `VOIDED`.

### OrderRefundFeeDetail

List of Refund fee like restocking fee on returned or canceled items.  
Applicable when item is returned or canceled and refund fee is configured.  
For more detail on refund fee,

*   `orderId` (_string_) OrderID towards the refund fees are applied.
*   `transactionId` (_string_) Refund transactionId during which refund fees are applied.
*   `storeId` (_string_) Store where the refund is performed.
*   `refundFeeId` (_string_) Refund fee id Eg. Restocking, Miscellaneous.
*   `refundFeeLabel` (_string_) Refund fee display name Eg. Restocking Fee, Miscellaneous Fee.
*   `refundFeeAmount` (_number_) Refund fee amount.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderRepostStatus

A list of Reposting status for each order that was part of the request.

*   `orderId` (_string_) The unique identifier for the order.
*   `status` (_string_) Status of the individual order reposting. Also please note that the status displayed below solely pertains to the outcome of the asynchronous reposting initiation process. A "SUCCESS" status denotes that the initiation was successful, but it does not guarantee that the order was sent to the external endpoint without issue. Conversely, a "FAIL" status indicates that the reposting initiation was not successful.  
    Allowed values: `SUCCESS`, `FAIL`.
*   `failureDescription` (_string_) Provides a description of the failure if the status is set to FAIL.

### Card

Use the card number in the card object to search. Typically by the last four digits of the card customer used to make payment.

*   `paymentId` (_string_) Payment ID/Card ID.
*   `cardOwner` (_string_) Card Owner.
*   `cardType` (_string_) Card Type.
*   `cardNumber` (_string_) Card Number.
*   `cardCvc` (_string_) Card CVC.
*   `cardExpirationMonth` (_integer (int32)_) Card Expiration Month.
*   `cardExpirationYear` (_integer (int32)_) Card Expiration Year.
*   `rawCardType` (_string_, nullable) Raw Card Type.
*   `billingAddressId` (_string_) Billing address ID.
*   `cardNickName` (_string_, nullable) Card Nick Name.
*   `track1Data` (_string_, nullable) Track1 Data if payment is done by app.
*   `track2Data` (_string_, nullable) Track2 Data if payment is done by app.
*   `deviceId` (_string_, nullable) Device ID.
*   `authAmount` (_number_, nullable) Amount to be authorized.
*   `authCode` (_string_, nullable) Authorization code.
*   `captureCode` (_string_, nullable) Capture code.
*   `cardToken` (_string_, nullable) Card token.
*   `cardId` (_string_)
*   `requestId` (_string_, nullable) Request ID used in POS.
*   `requestToken` (_string_, nullable) Request Token.
*   `encryptedCardNumber` (_string_, nullable) Encrypted Card Number.
*   `encryptedCvv` (_string_, nullable) Encrypted Cvv.
*   `paymentMethod` (_string_, nullable) Payment Method.
*   `transactionId` (_string_, nullable) Transaction Id.
*   `encryptedExpiryDate` (_string_, nullable) Encrypted Expiry Date.
*   `receiptLines` (_array of PaymentReceiptLine_, nullable) Receipt Lines.
*   `paypalData` (_PaypalData_)
*   `squareData` (_SquareData_)
*   `adyenData` (_AdyenData_)
*   `thirdPartyToken` (_string_, nullable) Third party token. Used in case of aurus tokenization.
*   `manualCardEntry` (_boolean_)

### BigDecimalRange

Find orders within this order total range.

*   `from` (_number_, read-only, nullable) From or starting filter criteria for amount/BigDecimal values.
*   `to` (_number_, nullable) To or ending filter criteria for amount/BigDecimal values.

### OrderSearchResponseEntry

List of searched orders.

*   `orderID` (_string_) Order ID.
*   `storeID` (_string_) Store ID. Order placed in this store.
*   `billingName` (_string_) Billing name used to place order.
*   `emailID` (_string_) Email ID used to place order.
*   `total` (_number_) Order total.
*   `orderDate` (_string_) Order Date.
*   `orderDateTimeStamp` (_integer (int64)_) Order Date Time.
*   `count` (_integer (int32)_) Order count.
*   `imageLinks` (_array of string_) Order Product Images.
*   `orderStatus` (_string_, nullable)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `orderStatusText` (_string_) Order Status Text.
*   `orderType` (_string_, nullable) Type of order. Used in case of BOPIS (STORE\_PICKUP) or BOFIS/BOSS (STORE\_FULFILLMENT) orders.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `bopisOrderStatus` (_string_, read-only, nullable) BOPIS/BOSS/BOFIS Order status. This is shared enum used for OrderStatus.
*   `status` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `isSplitCart` (_boolean_, nullable) Flag indicating if this order is part of a split cart order.  
    Default: `false`.
*   `fulfillmentType` (_string_) Fulfillment Type-IN\_STORE, ONLINE, MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `parentOrderId` (_string_, nullable) Parent order ID in case this order is part of a split/mixed order. For example, this order is IN\_STORE order which is part of an order that had IN\_STORE and ONLINE orders.
*   `orderAttribution` (_OrderAttribution_)
*   `paymentStatus` (_string_, nullable) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `currency` (_string_, nullable) Currency code. 3 letter currency code.  
    Example: `USD`.
*   `manualReceiptId` (_string_) Manual Receipt ID.
*   `externalOrderID` (_string_)

### ExternalStoreAttribution

Store details.

*   `storeAssociateId` (_string_, required) Store associate ID who is ringing the transaction.
*   `storeId` (_string_, required) Store ID.  
    Maximum length: 128.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.  
    Maximum length: 128.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `tillSessionId` (_string_, required) Till session ID.
*   `tillId` (_string_, required) Till ID.
*   `installationId` (_string_, nullable) Device identifier which was used to place the order. It is mandatory for transactions performed in the store. For external transactions, it will be defaulted to 'EXTERNAL' if it is not provided.  
    Maximum length: 128.
*   `registerMode` (_string_, required) The mode of the register operation.  
    Allowed values: `ONLINE`, `OFFLINE`. Default: `ONLINE`.

### ExternalTender

Payment method used towards the sale transaction.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Identifies the payment device through which the payment is made. If payment data is manually entered, this field should be set to NoReader. If payment is made in an external system, payment device should be set to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry). Mandatory for CreditCard, GiftCard.  
    Maximum length: 128.
*   `cardType` (_string_) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_) Payment authorization token.  
    Maximum length: 128.
*   `authorizationDate` (_integer (int64)_) Payment authorization timestamp in EPOCH millis.
*   `captureToken` (_string_) Payment capture token.  
    Maximum length: 128.
*   `captureDate` (_integer (int64)_) Payment capture timestamp in EPOCH millis.
*   `firstName` (_string_) First name to use for billing using this tender.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.
*   `country` (_string_) Country code to use for billing using this tender.  
    Maximum length: 16.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) Total Refunded Amount if any which is already paid back due to returns + exchanges. Not applicable, if no refund issued yet.  
    Default: `0`.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.  
    Default: `0`.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int32)_, required) Payment sequence indicating the order of payment. For example, if customer pays partially with cash first and remaining with credit card, then cash tender should have paymentSequenceNumber as 1 and credit card tender should have paymentSequenceNumber as 2.
*   `paymentDeviceId` (_string_) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_) Bank routing number.  
    Maximum length: 32.
*   `accountNumber` (_string_) Account number. Used for payment through banking system.  
    Maximum length: 32.
*   `checkNumber` (_string_) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).  
    Maximum length: 128.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_) Authority that issued the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_integer (int64)_) Personal identification expiry date represented as milliseconds since epoch. Typically expiry date is end of the day and milliseconds since epoch should reflect it accordingly. Applicable for Check and Finance.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year. Applicable for credit card.
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.  
    Maximum length: 32.
*   `externalPaymentReferenceId` (_string_) External payment reference identifier in case of External tender.  
    Maximum length: 32.
*   `checkType` (_string_) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_) Refers to Finance processing related result/instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_) Primary owner on the account.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `paymentLink` (_string_) Payment Link.  
    Maximum length: 128.
*   `paymentLinkExpiryDate` (_integer (int64)_) Payment link expiry timestamp in EPOCH millis.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `requestTokenExpireDate` (_integer (int64)_) Request token expire date in EPOCH millis.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response by gateway. In adyen - a value that uniquely represents the shopper's card number (PAN).
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.

### ExternalRefundTender

Payment method used towards the return transaction.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Transaction identifier as part of which this payment was initiated originally and now being refunded.
*   `originalPaymentId` (_string_, required) Payment Identifier as part of which this payment was initiated originally and now being refunded.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry). Mandatory for CreditCard, GiftCard.  
    Maximum length: 128.
*   `cardType` (_string_) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `refundRequestId` (_string_, required) Refund ID issued by the payment gateway. Mandatory for refund on credit card.
*   `refundedAmount` (_number_, required) Amount refunded.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year.
*   `cashDrawerUrl` (_string_) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `cardAlias` (_string_, nullable) Card alias associated with Refund Tender. In adyen - a value that uniquely represents the shopper's card number (PAN).

### ExternalProduct

Products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.

### ExternalReturnProduct

Returned products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `exchangedForOrderId` (_string_, nullable) Applicable for exchange of the item. A separate order will be generated for the new item when an exchange occurs. The order ID corresponding to the new item related to the exchange will be provided here.  
    Maximum length: 128.
*   `exchangedForProductId` (_string_, nullable) Applicable for exchange of the item. A separate order will be generated for the new item when an exchange occurs. Please provide the order ID for the new item related to the exchange.  
    Maximum length: 128.

### ExternalCustomerProfile

Customer profile. It is mandatory for customer logged-in during the transaction. It is optional for guest customer.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.  
    Maximum length: 128.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.  
    Maximum length: 128.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.

### ExternalDeliveryGroup

In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.

*   `deliveryGroupId` (_string_, required) Delivery group ID.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup, i.e., buy online ship to store |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_ExternalAddress_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `fulfillmentAddress` (_ExternalAddress_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ExternalPickUpDetail

Pickup details.

*   `pickupDetailId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `email` (_string_)
*   `phone` (_string_)

### ExternalAddress

Billing address.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, required, nullable) Customer first name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `addressLine1` (_string_, required, nullable) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required, nullable) City.  
    Maximum length: 64.
*   `state` (_string_, required, nullable) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required, nullable) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, required, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `addressType` (_string_, nullable) Address type- Home, Business.
*   `emailAddress` (_string_, nullable) Customer Email Address.  
    Maximum length: 64.
*   `country` (_string_, nullable) Country.

### ExternalTransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required) Total Item price.
*   `discount` (_number_, nullable) Total price override and promo coupons applied. Applicable if any item level price override applied or any promotion (auto or coupon) applied.
*   `transactionDiscountAmount` (_number_, nullable) Total transaction discount. Applicable if any transaction discount is applied.
*   `rewardAmount` (_number_, nullable) Total reward amount. Applicable if any reward coupon is applied.
*   `tax` (_number_, nullable) Total Tax.
*   `taxExemption` (_number_, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, nullable) Total shipping charges.
*   `total` (_number_, required) Item total inclusive of all charges like taxes and discounts and exclusive of tip amount.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.

### ExternalNote

Notes for the transaction.

*   `cartId` (_string_)
*   `noteId` (_string_)
*   `noteText` (_string_)
*   `transactionId` (_string_)

### ExternalTaxExemption

Applied tax exemptions.

*   `taxExemptCode` (_string_, required) Tax exemption code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for an individual who has tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer's tax-exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption entered during checkout on the POS.  
    Maximum length: 128.
*   `taxExemptionRate` (_number_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### ExternalSerializedUnitDetail

The list of attributes about a serialized unit, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### CustomerData

List of Customers.

*   `profile` (_Profile_, required)
*   `addressList` (_array of Address_) Customer's addresses.
*   `cartProductList` (_array of ClientelingCartProduct_) Wish list or products from customer's abandoned cart.
*   `loyaltyProfile` (_CustomerLoyaltyProfile_)
*   `consents` (_Consents_)

### Consents

Consents for different types of sign ups.

*   `smsSignUp` (_boolean_, nullable) Consent for SMS signup.
*   `newsLetterSignUp` (_boolean_, nullable) Consent for news letter signup.
*   `agreeToTC` (_boolean_, nullable) Consent for terms and conditions.
*   `directMailSignUp` (_boolean_, nullable) Consent for direct mail signup.
*   `phoneSignUp` (_boolean_, nullable) Consent for phone signup.
*   `loyaltySignUp` (_boolean_, nullable) Consent for loyalty signup.
*   `eReceipt` (_boolean_, nullable) Consent for eReceipt signup.

### SpiStoreAttribution

Store ID and associate details of created customer.

*   `storeAssociateId` (_string_, nullable) ID of the store associate who creates customer account and rings the transaction.
*   `storeId` (_string_, nullable) Store Id.

### CustomerLoyaltyProfile

The loyalty profile of the customer if they are enrolled in Loyalty program.

*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `firstName` (_string_) Customer's first name.
*   `lastName` (_string_) Customer's last name.
*   `accountNumber` (_string_) Customer's loyalty account number.
*   `loyaltyStatusCode` (_string_, nullable) Customer's loyalty status code.
*   `currentPoints` (_integer (int32)_, nullable) Customer's current loyalty points. If provided, it will be used for validation against the individual reward points (If points are sent in reward).
*   `currentStoreCredit` (_number (double)_, nullable) Customer's current store credit.
*   `lifetimePoints` (_integer (int32)_, nullable) Loyalty point accumulated so far by the customer.
*   `nextRewardPoints` (_integer (int32)_, nullable) Loyalty point eligible for next reward cycle.
*   `transactions` (_Transactions_)
*   `rewards` (_array of Reward_, nullable) Earned rewards.
*   `tierLevelLabel` (_string_, nullable) Customer's tier level label.
*   `tierLevelValue` (_string_, nullable) Customer's tier level value.
*   `tierLevelCode` (_string_, nullable) Customer's tier level code.
*   `redemptionType` (_string_)
*   `internalMemberId` (_string_, nullable) Customer's internal member ID.
*   `homePhoneNumber` (_string_, nullable) Customer's home phone number.
*   `mobilePhoneNumber` (_string_, nullable) Customer's mobile phone number.
*   `address` (_Address_)
*   `currentTier` (_Tier_)
*   `nextTier` (_Tier_)
*   `customLoyaltyAttributes` (_CustomAttributes_)
*   `totalRewardsAmount` (_number_, nullable) Total amount value of all the rewards available for the customer. If provided, this will be used for validation when applying the individual rewards.
*   `loyaltyIdBarCodeType` (_string_)

### ClientelingCartProduct

Summary of a product line in the customer's saved cart. Current implementation only supports productId as the details are fetched from the product catalog.

*   `productId` (_string_, required) Product / SKU identifier of the product.

### SpiProduct

The list of products in this group for which the delivery/pickup dates are to be returned in the response.

*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Product Quantity.
*   `gtin` (_string_) Product GTIN.

### SPIAddress

The full address of the destination of transaction.

*   `firstName` (_string_) Customer first name saved for address.
*   `lastName` (_string_) Customer last name saved for address.
*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.
*   `phone` (_string_) Phone.
*   `storeId` (_string_) Store ID if it is store address.
*   `emailAddress` (_string_) Customer Email Address.

### SpiDateTimeSlot

The backup delivery/pickup date in case slots are not available or unknown. (Default value can also be set in Store settings using property 'deliveryDatePickerWillCall' ).

*   `slotId` (_string_, required) Slot ID, unique value for this delivery/pickup day/date.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) The default selected time slot for the delivery/pickup date.  
    Example: `09:00 - 12:00`.
*   `availableTimeSlots` (_array of string_, nullable) The list of other time slots available for delivery/pickup.
*   `shippingMethodId` (_string_, nullable) Shipping Method ID for this slot in case of delivery item.

### SPIShipmentProcessorRequestProduct

All the items from the cart. Each item has a link to its delivery group via deliveryGroupId.

*   `orderItemId` (_string_, required, write-only) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `parentOrderItemId` (_string_, write-only) Indicates the parent order item ID for add-on items, pointing to the main item's order item ID. For example, values like 1, 2, or 3 represent the line item number of the parent item.  
    Example: `1, 2, 3`.
*   `deliveryGroupId` (_string_, write-only) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `productId` (_string_, required, write-only) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required, write-only) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `customAttributeList` (_array of ProductFormAttribute_) Custom attributes related to the product. The products have custom attributes  
    like customString0,customString1. etc. Merchants can map their custom attributes to  
    these fields in field mapping and provide the values in the product feed.  
    For more details, see:  
    [Clienteling SPI Field Mapping](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-field-mapping.html)  
    If merchants want custom attributes to be exported in Order Export and also here in  
    this SPI request, they need to configure CMS's store settings as below  
    **CMS** > **Store Management** > **Store Setting** > **Oms** > **Order** export > tLogCustomProductAttributes >  
    customString0,customString1.. etc.  
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `name` (_string_, required, write-only) Name of the item.
*   `price` (_number_, required, write-only) Price of the item.
*   `quantity` (_integer (int32)_, required, write-only) Item's Quantity.
*   `imageURL` (_string_, required, write-only) Image URL of the item.
*   `subTotal` (_number_, required, write-only) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_, write-only) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required, write-only) Item's total (final amount charged for this item), inclusive of tax/VAT and discounts.
*   `productTax` (_ExternalProductTax_)
*   `size` (_string_, write-only) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required, write-only) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required, write-only)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, write-only) Item's GTIN.
*   `fulfillmentType` (_string_, required, write-only) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required, write-only)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `productClass` (_string_, required, write-only) Product class of the item.
*   `serialNumber` (_string_, write-only) Serial number of the item (if applicable).
*   `productCondition` (_string_, write-only) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `registryId` (_string_, write-only, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.

### SPIShipmentProcessorRequestDeliveryGroup

All delivery groups corresponding the delivery items from the cart.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Unique ID in alphanumeric format.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_SPIShipmentProcessorShippingMethod_)
*   `shippingAddress` (_ExternalAddress_)
*   `dateTimeSlot` (_ExternalDateTimeSlot_)
*   `availableDateTimeSlotList` (_array of ExternalAvailableDateTimeSlot_, read-only) Available delivery date time slots.
*   `deliveryDatePickerOption` (_string_, read-only) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `sortOrder` (_integer (int32)_, required) PS POS uses sort order to display delivery groups in a specific sequence. If not provided, the display order becomes unpredictable.
*   `fulfillmentAddress` (_ExternalAddress_)

### SPIShipmentProcessorResponseProduct

All items from the cart are associated with a deliveryGroupId,  
enabling linkage to the corresponding deliveryGroup within the deliveryGroupList.  
Additionally, each item may possess custom attributes.

*   `orderItemId` (_string_, required, read-only) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `deliveryGroupId` (_string_, read-only) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available in order export JSON at item level under attribute:  
    tLogCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    

### SPIShipmentProcessorResponseDeliveryGroup

All delivery groups corresponding the delivery items from the cart.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Unique ID in alphanumeric format.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_SPIShipmentProcessorShippingMethod_)
*   `shippingAddress` (_ExternalAddress_)
*   `dateTimeSlot` (_ExternalDateTimeSlot_)
*   `availableDateTimeSlotList` (_array of ExternalAvailableDateTimeSlot_, read-only) Available delivery date time slots.
*   `deliveryDatePickerOption` (_string_, read-only) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `sortOrder` (_integer (int32)_, required) PS POS uses sort order to display delivery groups in a specific sequence. If not provided, the display order becomes unpredictable.
*   `fulfillmentAddress` (_ExternalAddress_)
*   `shippingMethodList` (_array of SPIShipmentProcessorShippingMethod_) Available shipping method options corresponding to the delivery group. It is optional and must be provided if an address is provided for the delivery group.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### SpiRegistryProduct

The list of gift products that are present with this registry, with all the availability details.

*   `productId` (_string_, required) Product Identifier.
*   `quantityWanted` (_integer (int32)_, required) The quantity of this item that the registrant is looking for.
*   `quantityPurchased` (_integer (int32)_, required) Quantity of the item that have already been purchased as a gift.
*   `preEventAvailability` (_boolean_, required) Flag indicating whether item is available for Ship to the Pre event address.
*   `postEventAvailability` (_boolean_, required) Flag indicating whether item is available for Ship to the Post event address.
*   `inStoreAvailability` (_boolean_, required) Flag indicating whether item is available to take with / In Store order.
*   `quantity` (_integer (int32)_, required) Quantity of the product that is available to purchase.

### RegistryLineItem

The list of line items corresponding to the product Id sent in request, where each line can be of differing prices, quantities, belonging to different orders.

*   `eligibleForReturn` (_boolean_, required) Flag to indicate whether product is eligible for return.
*   `productId` (_string_, required) Product Identifier.
*   `price` (_number_, required) Product price inclusive of quantity.
*   `quantity` (_integer (int32)_, required) Quantity of the product.
*   `taxAmount` (_number_, required) Tax amount inclusive of quantity.
*   `externalReferenceId` (_string_, required) The orderId or reference ID associated with the registry item being returned. Pass this when adding the item to the cart for NRR.

### GiftRegistry

The list of gift registries matching the search.

*   `imageUrl` (_string_, required) The URL of the image to be shown along with the Registry details.
*   `registryId` (_string_, required) The unique ID of the registry.
*   `firstName` (_string_, required) The First name of the Registrant.
*   `lastName` (_string_, required) The last name of the Registrant.
*   `coRegistrantName` (_string_, nullable) The Co-Registrant name for the registry if available.
*   `state` (_string_, required) The state where the event is taking place.
*   `eventType` (_string_, required) The event type for which the registry was created. For example, Wedding, Engagement, Housewarming.
*   `eventDate` (_integer (int64)_, required) The event date in epoch milliseconds, to be shown in a suitable format on the app.

### StoreInventoryDetails

List of all stores and their inventory details for the product sent in the request.

*   `storeId` (_string_, required) Store or warehouse ID.
*   `storeName` (_string_, required) Store name.
*   `storeAddress` (_SpiStoreAddress_, required)
*   `inventory` (_SpiInventory_, required)

### InventoryProduct

The list of Products for which the Inventory is to be checked.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `inventoryType` (_string_, required) Item's inventory check type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).
*   `inventoryAction` (_string_, required) The action to be taken for this inventory check. Current valid values: AVAILABILITY.
*   `storeId` (_string_, required) Check inventory based on given store ID. Will always be sent in the request.

### ProductInventory

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `quantity` (_integer (int32)_, required) The available inventory quantity of the product, 0 when there is no inventory.
*   `storeId` (_string_, nullable) Available inventory based on given store ID. Optional, to be returned when inventoryType is IN\_STORE.
*   `inventoryType` (_string_, required) Item's inventory check type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).

### CycleCountPayloadLine

Cycle count line items.

*   `storeID` (_string_, required) ID of the store where this cycle count is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `cycleCountID` (_string_, required, read-only) Cycle count identifier. Unique POS ID assigned when the cycle count is created.  
    Example: `10001`.
*   `cycleCountType` (_string_, required, read-only) Below is list of supported cycle count types:  
    1.**Full**: Cycle count for the full inventory of products  
    2.**Partial**: Cycle count for a particular group of products that fall within  
    a selected category, brand, or any other product attribute that is configured  
    3.**Manual**: Cycle count for a specific set of products that are scanned in prior to starting the count.  
    Allowed values: `FULL`, `PARTIAL`, `ADJUSTMENT`, `FULL, PARTIAL, ADJUSTMENT`. Example: `STORE`.
*   `cycleCountStatus` (_string_, required, read-only)
    
    1.  **CREATED**: While creating a new batch provide this status  
        2\. **CANCELED**: To cancel the existing cycle count batch.  
        3\. **COMPLETED**: Once the batch is created in the POS system,  
        the status will become COMPLETED  
        4\. **PREPARING**: Preparing the cycle count batch  
        5\. **IN\_PROGRESS**: Cycle count in progress.
    
      
    Allowed values: `CREATED`, `CANCELED`, `COMPLETED`, `PREPARING`, `IN_PROGRESS`, `CREATED, PREPARING, IN_PROGRESS, COMPLETED, CANCELED`. Example: `CREATED`.
*   `createdFrom` (_string_, required) Origin of this cycle count - triggered by the corporate or from the store itself.  
    Allowed values: `CORPORATE`, `STORE`, `CORPORATE, STORE`. Example: `STORE`.
*   `cycleCountDate` (_integer (int64)_)
*   `name` (_string_, required) Logical name for this cycle count.  
    Example: `Spring 2020 cycle count`.
*   `description` (_string_) Detailed description for the cycle count.  
    Example: `Spring 2020 cycle count to be completed before 4/30`.
*   `partialCycleCountProductAttribute` (_string_, required) Product attribute for partial cycle count to perform cycle count by specific product attribute. For example, Brand.  
    Example: `MerchantCategory`.
*   `partialCycleCountProductAttributeValues` (_string_, required) List of product attribute values for partial cycle count. For example, Brand values of Mattel, Disney, etc.  
    Example: `Reserve`.
*   `productCategories` (_string_, deprecated) List of product categories for partial cycle count for specific product categories. Use @partialCycleCountProductAttribute.  
    Example: `Clothing`.
*   `productIDs` (_string_, deprecated) List of product IDs applicable for partial cycle count for specific products. Use @partialCycleCountProductAttributeValues.  
    Example: `productId1,productId2`.
*   `createdBy` (_string_, required) Store associate ID who created the cycle count.  
    Example: `0202`.
*   `updatedBy` (_string_, required) Store associate ID who modified the cycle count.  
    Example: `0202`.
*   `startedByStoreAssociateID` (_string_, required) ID of the Store associate who started this cycle count. This need not be the same as the user who created the cycle count.  
    Example: `0202`.
*   `updatedByStoreAssociateID` (_string_, required) ID of the Store associate who last updated this cycle count.  
    Example: `0202`.
*   `expectedQuantity` (_integer (int32)_, required) Total number of products expected.  
    Example: `5`.
*   `countedQuantity` (_integer (int32)_, required) Total number of products actually counted.  
    Example: `3`.
*   `expectedProductValue` (_number_, required) Total value of the products - expected.  
    Example: `100`.
*   `countedProductValue` (_number_, required) Total value of the products that were actually counted.  
    Example: `60`.
*   `variancePercentageQuantity` (_number_, required) Variance percentage between expected product count vs. actual product count.  
    Example: `-60`.
*   `variancePercentageProductValue` (_number_, required) Variance percentage between expected product value vs. actual product value.  
    Example: `-60`.
*   `varianceQuantity` (_integer (int32)_, required) Variance in quantity between expected product count vs. actual product count.  
    Example: `-2`.
*   `varianceProductValue` (_number_, required) Variance in value between expected product count vs. actual product count.  
    Example: `-40`.
*   `email` (_string_) Email address to which the cycle count report was sent.  
    Example: `predictspring@predictspring.com`.
*   `startTimeStamp` (_integer (int64)_, required) Cycle count start time represented in milliseconds since epoch.  
    Example: `1686608971000`.
*   `productID` (_string_, required) Product ID.  
    Example: `014001`.
*   `gtin` (_string_, required) Product GTIN.  
    Example: `778913800001`.
*   `productTitle` (_string_, required) Product name.  
    Example: `Plat Pinot`.
*   `productImageURL` (_string_) Product Image URL.
*   `color` (_string_) Product Color.  
    Example: `white`.
*   `size` (_string_) Product Size.  
    Example: `0.75`.
*   `unitProductValue` (_number_) Unit Price.  
    Example: `32.99`.
*   `excluded` (_boolean_) Flag indicating if this product was excluded from cycle count. This flag indicates that this product inventory should not be adjusted based on this cycle count. Excluded products are excluded from variance calculations as well.
*   `reasonCode` (_string_) Reason code for excluding the item from cycle count.
*   `createdTimeStamp` (_integer (int64)_, required) Cycle count creation time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `modifiedTimeStamp` (_integer (int64)_, required) Cycle count last modified time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `reasonText` (_string_) Reason text for excluding the item from cycle count.  
    Example: `Lost`.
*   `serialNumbers` (_string_) Scanned Serial numbers.
*   `itemExpectedQuantity` (_integer (int32)_, required) Expected quantity for this item.  
    Example: `70`.
*   `itemCountedQuantity` (_integer (int32)_, required) Actual quantity for this item.  
    Example: `0`.
*   `itemExpectedProductValue` (_number_, required) Expected product value for this item based on expected quantity.  
    Example: `2309.3`.
*   `itemCountedProductValue` (_number_, required) Actual product value for this item based on counted quantity.  
    Example: `0`.
*   `itemVariancePercentageQuantity` (_number_, required) Variance percentage between expected product count vs. actual product count.  
    Example: `-100`.
*   `itemVariancePercentageProductValue` (_number_, required) Variance percentage in value between expected product value vs. actual product value.  
    Example: `-100`.
*   `itemVarianceQuantity` (_integer (int32)_, required) Variance in quantity between expected product count vs. actual product count.  
    Example: `-70`.
*   `itemVarianceProductValue` (_number_, required) Variance in value between expected product value vs. actual product value.  
    Example: `-2309.3`.
*   `itemRecountCount` (_integer (int32)_, required) The number of times the item is recounted within the same cycle count.  
    Example: `1`.
*   `externalReferenceId` (_string_) External cycle count or batch ID.  
    Example: `spring-2023`.

### InventoryAdjustmentPayloadLine

Inventory adjustment line items.

*   `id` (_string_, required) Inventory adjustment identifier.
*   `storeID` (_string_, required) ID of the store where this inventory adjustment is performed. Provide a valid store ID that's already configured in POS, either through CMS or Store Feed.  
    Example: `001`.
*   `productID` (_string_, required) Product item identifier.
*   `productTitle` (_string_, required) Product title.
*   `productImageURL` (_string_, required) Product image URL.
*   `color` (_string_) Product color.
*   `size` (_string_) Product size.
*   `countedQuantity` (_integer (int32)_, required) Adjusted quantity.  
    Example: `5`.
*   `startedByStoreAssociateID` (_string_, required) ID of the Store associate who started this inventory adjustment. This need not be the same as the user who created the inventory adjustment.  
    Example: `2036`.
*   `updatedByStoreAssociateID` (_string_, required) ID of the Store associate who last updated this inventory adjustment.  
    Example: `2036`.
*   `createdTimeStamp` (_integer (int64)_, required) Inventory adjustment batch item creation time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `modifiedTimeStamp` (_integer (int64)_, required) Inventory adjustment batch item last modified time represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `reason` (_string_, required) Adjustment reason code.  
    Example: `MISSING ITEMS`.
*   `reasonText` (_string_, required) Adjustment reason text.  
    Example: `Missing Items`.
*   `gtin` (_string_, required) Product GTIN.  
    Example: `778913800001`.
*   `serialNumbers` (_string_) Scanned Serial numbers.
*   `itemHierarchyId` (_string_, required) Item hierarchy ID for products which have the same product ID but have different reason codes.  
    Example: `1`.

### InventoryTransferPayloadLine

Inventory transfer line items.

*   `transferType` (_string_, required) Inventory transfer type.  
    Allowed values: `ASN`, `CORP_TRANSFER`, `STORE_TO_STORE`, `BLIND_RECEIVE`, `RETURN_TO_VENDOR`, `PO`, `ASN`, `CORP_TRANSFER`, `STORE_TO_STORE`, `BLIND_RECEIVE`, `RETURN_TO_VENDOR`. Example: `STORE_TO_STORE`.
*   `inventoryTransferID` (_string_, required) Inventory transfer identifier.  
    Example: `ITS00000001`.
*   `orderID` (_string_) Inventory transfer order identifier.  
    Example: `OrderPS00000001`.
*   `poNumber` (_string_) Inventory transfer Purchase Order Number.  
    Example: `123456`.
*   `uploadNumber` (_string_) Used to indicate the corporate transfer group.  
    Example: `1, 2`.
*   `billOfLadingID` (_string_) Bill of lading ID.  
    Example: `99865`.
*   `trackingNumber` (_string_, required) Tracking number.  
    Example: `track123`.
*   `fromID` (_string_, required) Inventory transfer origin identifier. For example, Warehouse/Distribution center/Store ID.  
    Example: `1`.
*   `toID` (_string_, required) Inventory transfer recipient identifier. For example, Warehouse/Distribution center/Store ID.  
    Example: `2`.
*   `productCount` (_integer (int32)_, required) Number of products in this inventory transfer.  
    Example: `3`.
*   `productImageLinks` (_string_) List of product images for the items in this inventory transfer.  
    Example: `https://us.maje.com/dw/image/v2/AAON_PRD/on/demandware.static/-/Sites-maje-catalog-master-H13/default/dwd569bdfb/images/h13/Maje_E18GUMPY-0067_H_1.jpg`.
*   `status` (_string_, required) Inventory transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. Example: `IN_PROGRESS`.
*   `createdOn` (_integer (int64)_, required) Date and time when this inventory transfer is created. Represented as milliseconds since epoch.  
    Example: `1686607971000`.
*   `dueOn` (_integer (int64)_) Date and time when this inventory transfer is due. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `lastProcessedById` (_string_, required) ID for the person/entity who processed this inventory transfer.  
    Example: `2036`.
*   `lastProcessedByName` (_string_, required) Name for the person/entity who processed this inventory transfer.  
    Example: `Rob`.
*   `updatedOn` (_integer (int64)_, required) Date and time when this inventory transfer is last updated. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `vendorID` (_string_, required) Vendor ID.  
    Example: `1`.
*   `receivedOn` (_integer (int64)_, required) Date and time when this inventory transfer is received. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `cancelledOn` (_integer (int64)_, required) Date and time when this inventory transfer is cancelled. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `exportDate` (_integer (int64)_) Inventory transfer export time. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `itemStatus` (_string_, required) Inventory transfer item's status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`. Example: `COMPLETE`.
*   `transferID` (_string_) Inventory transfer detail identifier.  
    Example: `409a92a5-834b-4500-b062-cedd89a38602`.
*   `palletID` (_string_, required) Pallet ID. Used to lookup specific transfer that has palletId.  
    Example: `A-4-PS00000001P1`.
*   `cartonID` (_string_, required) Carton ID. Used to lookup specific transfer that has cartonId.  
    Example: `A-4-PS00000001P1C1`.
*   `productID` (_string_, required) Product ID.  
    Example: `3661601594304`.
*   `vendorNumber` (_string_) Product vendor number.  
    Example: `607282`.
*   `externalDocNumber` (_string_) Product external doc number.  
    Example: `4900071859`.
*   `externalLineNumber` (_string_) Product external doc number.  
    Example: `00010`.
*   `productTitle` (_string_, required) Product title.  
    Example: `Wide-leg checked trousers`.
*   `productImageURL` (_string_, required) Product image URL.  
    Example: `https://us.maje.com/dw/image/v2/AAON_PRD/on/demandware.static/-/Sites-maje-catalog-master-H13/default/dw2b369dcf/images/h13/Maje_E18PERSE-1066_H_1.jpg`.
*   `quantityOrdered` (_integer (int32)_, required) Ordered quantity for each product in a transfer.  
    Example: `3`.
*   `quantityTransferred` (_integer (int32)_, required) Transferred quantity for each product in a transfer.  
    Example: `2`.
*   `quantityReceived` (_integer (int32)_, required) Received quantity for each product in a transfer.  
    Example: `1`.
*   `shipper` (_string_, required) Shipping supplier.  
    Example: `UPS`.
*   `shippedOn` (_integer (int64)_, required) Date and time when transfer is shipped. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `itemTrackingNumber` (_string_, required) Item tracking number.  
    Example: `TrackingIDPS00000001`.
*   `estimatedDeliveryOn` (_integer (int64)_, required) Date and time when transfer is expected to be delivered. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `deliveredOn` (_integer (int64)_) Date and time when transfer is delivered. Represented as milliseconds since epoch.  
    Example: `1686608971000`.
*   `receivedBy` (_string_, required) Received by ID.  
    Example: `2036`.
*   `reasonCode` (_string_, required) Item receive mismatch reason code.  
    Example: `1`.
*   `reasonText` (_string_, required) Item receive mismatch reason text.  
    Example: `Damaged`.
*   `color` (_string_) Product color.  
    Example: `Navy`.
*   `size` (_string_) Product size.  
    Example: `OS`.
*   `gtin` (_string_) Product gtin.  
    Example: `3661601593970`.
*   `isManualAdd` (_boolean_) Indicates if an item was manually added to the ASN, with true for manual additions and false for the item was existing.
*   `description` (_string_, required) Inventory transfer description.  
    Example: `Request for transfer from from store 1 to store 2`.
*   `serialNumbers` (_string_) Scanned Serial numbers.

### PurchaseOrderPayloadLine

Purchase order line items.

*   `transferType` (_string_, required) Inventory transfer type.  
    Allowed values: `ASN`, `CORP_TRANSFER`, `STORE_TO_STORE`, `BLIND_RECEIVE`, `RETURN_TO_VENDOR`, `PO`, `PO`. Example: `PO`.
*   `inventoryTransferID` (_string_, required) Purchase order identifier.  
    Example: `ITS00000001`.
*   `toID` (_string_, required) Purchase order recipient identifier. For example, Warehouse/Distribution center/Store ID.  
    Example: `1`.
*   `productCount` (_integer (int32)_, required) Total number of products in this inventory transfer.  
    Example: `10`.
*   `createdOn` (_integer (int64)_, required) Date and time when this order is created. Represented as milliseconds since epoch.  
    Example: `1686607971000`.
*   `productID` (_string_, required) Product ID.  
    Example: `3661601594304`.
*   `productTitle` (_string_, required) Product title.  
    Example: `Wide-leg checked trousers`.
*   `quantityOrdered` (_integer (int32)_, required) Ordered quantity for each product in a purchase order.  
    Example: `10`.
*   `costPrice` (_number_, required) Cost price of each item.  
    Example: `12.99`.
*   `casePackQuantity` (_integer (int32)_, required) Number of item per case pack.  
    Example: `8`.
*   `totalCost` (_number_, required) Total price of each item in an order, quantityOrdered \* costPrice.  
    Example: `129.9`.

### TransactionalInventoryProduct

products

List the products that require inventory adjustment.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.

### ProductError

*   `productId` (_string_)
*   `errorMessage` (_string_)
*   `errorCode` (_string_)
*   `errorType` (_string_)

### ProductWarning

*   `productId` (_string_)
*   `messages` (_array of Message_)

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### OrderPriceAdjustment

The list of price adjustments done on the total order in the cart.

*   `description` (_string_)
*   `adjustment` (_number_)
*   `discount` (_Discount_)
*   `price` (_number_)
*   `promotionId` (_string_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.

### CartDiscountData

*   `transactionDiscount` (_number_) The transaction discount applied on the original order.
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_) Item level price adjustments applied on the original order. It can be price override, promotion or prorated transaction discount.

### GiftCard

*   `cardId` (_string_)
*   `cardNumber` (_string_)
*   `cardPin` (_string_)
*   `balance` (_number_)
*   `invoiceNumber` (_string_)
*   `token` (_string_)
*   `forcePinValidation` (_boolean_)
*   `approvedAmount` (_number_)
*   `transactionId` (_string_)
*   `returnRelated` (_boolean_)

### CheckoutCookie

*   `domain` (_string_)
*   `key` (_string_)
*   `value` (_string_)

### LoyaltyInfo

*   `pointsRedeemValue` (_number (double)_)
*   `pointsEarnValue` (_number (double)_)
*   `pointsClosingBalance` (_number (double)_)

### ExchangeItemResponse

Details about the items that are being returned or exchanged.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `orderId` (_string_)
*   `exchangeStatus` (_string_)  
    Allowed values: `EXCHANGED`, `EXCHANGED_WITH_REFUND`, `FAILED`, `SKIPPED`.
*   `refundAmount` (_number_)
*   `refundMedium` (_string_)
*   `refundStatus` (_string_)
*   `orderStatus` (_string_)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `products` (_array of Product_)
*   `order` (_CustomerOrder_)
*   `amountPendingRefund` (_number_)
*   `refundPaymentData` (_array of PaymentData_)
*   `refundPaymentDataOriginalTender` (_array of PaymentData_)
*   `paymentData` (_array of PaymentData_)
*   `parentOrderId` (_string_)
*   `noReceiptReturns` (_boolean_)
*   `editOrderId` (_string_)
*   `refundFees` (_array of RefundFee_, nullable) Refund fees charged so far.
*   `transactionId` (_string_, nullable) Transaction identifier to identify current exchange transaction.
*   `offlineMode` (_boolean_) Flag to indicate whether returns or exchange is being performed in offline mode or not.
*   `postProcessingPerformed` (_boolean_) Flag to indicate if the post processing webhook is triggered or not.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `orderReturnsPolicy` (_OrderReturnsPolicy_)
*   `employee` (_Employee_)
*   `tipTotal` (_number_) Tip Total to be refunded in case of pure return.
*   `request` (_ExchangeItemRequest_)
*   `refundPerformed` (_boolean_)
*   `returnableItemTotal` (_number_)
*   `paymentDetails` (_array of OrderPaymentDetail_)
*   `exchangeOrderPaymentDetails` (_array of ExchangeOrderPaymentDetail_)
*   `error` (_boolean_)

### ReturnsTender

In case there is refund, refund tender details and options.

*   `returnsTenderId` (_string_)
*   `tenderHeaderText` (_string_)
*   `headerText` (_string_) Display text corresponding to the refund option.
*   `tenders` (_array of PaymentData_)
*   `returnsPolicies` (_array of string_) All the applied returns policies to determine the refund option.  
    Items: Allowed values: `MaxReturnsDays`, `MaxCashReturns`, `RemapRefundTenders`, `StoreCredit`, `GiftCard`, `CustomerNotInPersonRefund`, `CreditCard`, `NoReceiptReturns`, `Check`.
*   `managerOverrideRequired` (_boolean_)
*   `amountToBeCharged` (_number_) Effective amount to be charged to customer based on purchases, any refunds, discounts , taxes, shipping, any additional fee & rounding if any for this return tender.
*   `headerTextForManagerOverride` (_string_, write-only)
*   `approvalPolicyForManagerOverride` (_string_, write-only)  
    Allowed values: `CREATE_TILL`, `MAX_CASH_RETURN_POLICY`, `MAX_RETURN_WINDOW_POLICY`, `NRR`, `TENDER_REMAPPING`, `OFFLINE_MAX_CASH_RETURN_POLICY`, `OFFLINE_MAX_RETURN_WINDOW_POLICY`, `OFFLINE_NRR`, `OFFLINE_TENDER_REMAPPING`, `PAY_IN_OUT`, `EMPLOYEE_SALE`, `LINE_ITEM_DISCOUNT`, `TRANSACTION_DISCOUNT`, `RECONCILE_TILL`, `CASH_PICKUP`, `BUSINESS_CHECK`, `NO_SALE`, `POST_ADJUSTMENT_INVENTORY`, `CYCLE_COUNT_BATCH_SERIALNUMBER`, `SPECIAL_ITEM`, `REUSE_OLD_TILL`, `TAX_MODIFICATION`, `PRICE_CORRECTION`, `SHOW_ASSOCIATE_REVENUE_IN_DASHBOARD`, `VIEW_SAFE_MANAGEMENT`, `VIEW_ALL_TILLS`, `CYCLE_COUNT_LIFECYCLE`, `CYCLE_COUNT_DETAILS`, `VIEW_ALL_CYCLE_COUNT_BATCHES`, `UPDATE_ALL_CYCLE_COUNT_BATCHES`, `MANAGER_OVERRIDE`, `RETURN_EXCHANGE_POLICY`, `CASH_AUDIT`, `APPEASEMENT`, `EDIT_SAFE_MANAGEMENT`, `REMOVE_WARRANTY`.

### ExchangeItemRequest

Request for items that are being returned or exchanged.

*   `storeAssociateId` (_string_, required) ID of the store associate who performs the returns.
*   `storeId` (_string_, required) ID of the store where the return is being performed.
*   `installationId` (_string_, required) Installation ID of the register from where the return is being performed.
*   `noReceiptReturns` (_boolean_, nullable) Flag to indicate returns without receipt.  
    Default: `false`.
*   `receiptType` (_string_, nullable) Receipt type enum.  
    Allowed values: `ORDER`, `QUOTE`, `GIFT`, `GIFT_SKU_LEVEL`, `GIFT_REWARD_CARD`, `INVENTORY_TRANSFER_PACKING_SLIP`, `PO_ORDER`, `STORE_TO_STORE_TRANSFER`, `RETURN_TO_VENDOR_TRANSFER`, `PICK_LIST`.
*   `editOrderId` (_string_, nullable) Set in case of edit order mode. Value will be same as orderId.
*   `refundFees` (_array of RefundFee_) Refund fees applied when cancelling or returning items from an order during the edit order flow.
*   `offlineMode` (_boolean_) Flag to indicate whether returns or exchange is being performed in offline mode or not.
*   `returnProducts` (_array of ReturnProductIdentification_) Returning item's orderItemId and quantity.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakup for return items.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakup for return items.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `storeAttribution` (_StoreAttribution_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `employee` (_Employee_)
*   `orderSource` (_string_, nullable) Order Source - Indicates channel from where the order originated.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariffAmount` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `giftCardCashOut` (_boolean_)
*   `exchangeOrderPaymentDetails` (_array of ExchangeOrderPaymentDetail_)

### RefundFee

Refund fees applied when cancelling or returning items from an order during the edit order flow.

*   `id` (_string_) Refund fee ID. For example, Restocking or 001.
*   `label` (_string_) Refund fee display name. For example, Restocking Fee.
*   `value` (_number_, nullable) Refund fee amount.

### TaxTransaction

Details related to tax transaction related to a cart. A cart can be modified multiple times and hence it can be sent to tax engine multiple times. All such requests are tagged under single tax transaction id.

*   `cartId` (_string_) Cart ID related to the current tax transaction.
*   `transactionId` (_string_) Tax transaction ID. Multiple requests to the tax engines related to a cart can be tagged with a single tax transaction ID to group together all tax requests related to a single cart.
*   `editOrderId` (_string_) Order ID for the order being edited.

### OrderLevelGiftWrap

Gift Wrap.

*   `giftWrapMode` (_string_)  
    Allowed values: `ALL_ITEMS_TOGETHER`, `EACH_ITEM_SEPARATELY`.
*   `giftFrom` (_string_)
*   `giftTo` (_string_)
*   `giftMessage` (_string_)

### PaymentInstallment

*   `frequency` (_string_)
*   `count` (_integer (int32)_)
*   `amount` (_number_)
*   `text` (_string_)
*   `installments` (_array of PaymentInstallmentItem_)
*   `amountDueToday` (_number_)

### PaymentInstallmentOptions

List of Payment Installment options available.

*   `shippingMethodId` (_string_)
*   `paymentInstallmentList` (_array of PaymentInstallment_)

### Tender

Tender object with payment details.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `paymentSequenceNumber` (_integer (int32)_, required) Payment sequence indicating the order of payment. For example, if customer pays partially with cash first and remaining with credit card, then cash tender should have paymentSequenceNumber as 1 and credit card tender should have paymentSequenceNumber as 2.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentDevice` (_string_, required) Identifies the payment device through which the payment is made. If payment data is manually entered, this field should be set to NoReader. If payment is made in an external system, payment device should be set to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `rawPaymentPayload` (_string_) Raw payment payload. For future use.
*   `routingNumber` (_string_) Bank routing number.
*   `accountNumber` (_string_) Account number. Used for payment through banking system.
*   `checkNumber` (_string_) Check number. Used for payment through checks.
*   `personalIdType` (_string_) Personal identification type.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_) Issuer of the personal identification.
*   `personalIdNumber` (_string_) Personal identification number.
*   `personalIdExpiryDateMillis` (_integer (int64)_) Personal identification expiry date represented as milliseconds since epoch. Typically expiry date is end of the day and milliseconds since epoch should reflect it accordingly.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry).
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardCvc` (_string_) Card CVC. Used in case of manual credit card data entry.
*   `track1Data` (_string_) Encrypted track1 data. Used in case of client/app side card encryption by readers like Verifone.
*   `track2Data` (_string_) Encrypted track2 data. Used in case of client/app side card encryption by readers like Verifone.
*   `paymentDeviceId` (_string_) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.
*   `operatingMode` (_string_) Operating mode of the app and card reader - ONLINE/OFFLINE. Other values are unused.  
    Allowed values: `ONLINE`, `OFFLINE`, `DEGRADED`, `TWO_PHASE_STAGING`.
*   `encryptedExpiryDate` (_string_) Encrypted expiry date. Used in case of client/app side card encryption by readers like Verifone.
*   `encryptedCardNumber` (_string_) Encrypted card number. Used in case of client/app side card encryption.
*   `encryptedCvv` (_string_) Encrypted card CVV. Used in case of client/app side card encryption.
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `storedCardId` (_string_) Stored Card ID to use in case of card stored for the customer profile.
*   `cardType` (_string_) Card type. For example, Visa, Master, Amex, or Discover.
*   `rawCardType` (_string_) Raw card type, for example, Visa Credit Card, Visa Debit Card, or Master Credit Card. Typically used when an Adyen terminal captures card data for payment.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year.
*   `pin` (_string_) PIN number typically used for gift card.
*   `authorizationToken` (_string_) Payment authorization token.
*   `authorizationDateMillis` (_integer (int64)_) Payment authorization timestamp as number of milliseconds since epoch.
*   `captureToken` (_string_) Payment capture token.
*   `captureDateMillis` (_integer (int64)_) Payment capture timestamp as number of milliseconds since epoch.
*   `requestId` (_string_) Payment request identification issued by payment gateway/terminal. Typically used for referenced refunds. This field maps to pspReference in case of Adyen payments.
*   `alternateRequestId` (_string_) Alternate payment request identification issued by payment terminal. Example, tender reference in case of Adyen terminal is in store and forward mode.
*   `requestToken` (_string_) Payment request token issued by payment gateway/terminal. Typically used for referenced refunds.
*   `firstName` (_string_) First name to use for billing using this tender.
*   `lastName` (_string_) Last name to use for billing using this tender.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.
*   `city` (_string_) City to use for billing using this tender.
*   `state` (_string_) State to use for billing using this tender.
*   `postalCode` (_string_) Postal code to use for billing using this tender.
*   `country` (_string_) Country code to use for billing using this tender.
*   `paypalInvoiceId` (_string_) Invoice ID. Used when payment is done using paypal reader.
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_) External payment reference identifier in case of External tender.
*   `paymentGatewayConfigId` (_string_) Payment Gateway ID - to be used in case of multiple payment gateways are available to process a single tender.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt.
*   `merchantReferenceId` (_string_) Merchant reference ID sent to the payment terminal for this tender. This is required for match response received off asynchronously from payment processor (like Adyen Store and Forward) with the correct payment object for an order.
*   `paymentStatus` (_string_) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `checkType` (_string_) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_) Manual authorization code for a tender. Normally it is received after calling a call center agent of a payment processor. For example, call for auth code after check denial/referral, manual auth code for credit card when offline.
*   `paymentTypeCode` (_string_) Type of payment plan. Used for Tender Type - Finance.
*   `cardPresent` (_boolean_) Indicates if the card is physically present or not. Used in case of Tender Type - Finance.
*   `ssn` (_string_) Customer's Social Security Number for verification purposes. Used in case of Tender Type - Finance.
*   `accountHolders` (_array of AccountHolder_) Account Holders information. Used in case of Tender Type - Finance.
*   `additionalInfo` (_array of string_) List of additional information required to verify the buyer. Used in case of Tender Type - Finance.
*   `cashDrawerUrl` (_string_) Represents custom URL using which cash drawer in the network can be accessed.
*   `roundingAmount` (_number_) The delta amount because of rounding.
*   `authStatus` (_string_) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_) Tip amount to capture on credit card.
*   `captureStatus` (_string_) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_) Refers to finance approval/order/confirmation number in external system.
*   `financeInstruction` (_string_) Refers to finance processing related result or instruction long text from external system.
*   `primaryAccountHolder` (_string_) Primary owner on the account.
*   `tradeType` (_string_) Trade Type. In case of WeChatPay: QuickPay.
*   `bankType` (_string_) Bank Type.
*   `fundingSource` (_string_) Funding source like PREPAID.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `paymentLink` (_string_) Payment Link.
*   `paymentLinkExpiryDate` (_string_) Payment Link expiry date.
*   `paymentId` (_string_) Payment Id from app.
*   `transactionId` (_string_) The transactionId from app's requestId.
*   `paymentReversalStatus` (_string_) Payment Status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi tender and delete by swiping right, ABORTED is used where we internally remove tender from our tender list and add a new tender for eg gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `captureAmount` (_number_) Amount captured for credit card.
*   `requestTokenExpireDate` (_integer (int64)_) Request token expire date.
*   `continueOnPendingOrDecline` (_boolean_) Continue order processing on tender pending or decline status.
*   `termsAndConditions` (_string_) Terms and conditions.
*   `gcBalance` (_number_, nullable) Balance remaining in case of tender type gift card.
*   `cashTenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `cashChangeAmount` (_number_) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response by gateway. In adyen - a value that uniquely represents the shopper's card number (PAN).
*   `paymentEntryMode` (_string_) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `manualCardEntry` (_boolean_)
*   `error` (_boolean_)

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### Discount

Transaction discount applied on the cart with information like discount type and discount value. In online mode it is copied from app's request payload for transaction discount and in case of offline mode it is copied from app's submit order request.

*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`, `AMOUNT, PERCENT`. Default: `AMOUNT`.
*   `discount` (_number_, required) Discount either in percentage or in amount.

### Flash

Generic field for display messages. The display message is populated to provide helpful information to user. One of the use cases is eligible coupon code which is not applied.

*   `type` (_string_, required) Type of the flash message.  
    Allowed values: `PROMOTION`, `TAX`, `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURN`, `ORDER`, `GIFTCARD`, `CART`, `INVENTORY_RESTRICTION`. Example: `PROMOTION`.
*   `message` (_string_, required) Flash message.  
    Example: `Coupons Spring2023, Max100 are in the cart but not applied`.
*   `resourceName` (_string_, required) Resource or entity for which the message is provided.  
    Allowed values: `COUPON_CODE`, `CART`. Example: `COUPON_CODE`.
*   `resourceValues` (_array of string_, required) Resource values for which the message is provided.  
    Items: Example: `Coupon codes - Spring2023, Max100 etc...`. Example: `Coupon codes - Spring2023, Max100 etc...`.

### AuxiliaryItemData

auxiliary Items details support for edit order.

*   `orderItemId` (_string_) Order item ID.
*   `itemAction` (_string_) Items Action.  
    Allowed values: `NEW`, `MODIFY`.

### ReturnCustomerInformation

Return - Customer Information. For return or exchange transactions, use this object to capture information about the person returning the items. Note: This might or might not be the actual customer who purchased the items. This object is exclusively to capture information about the person returning items.

*   `firstName` (_string_, nullable) First Name.
*   `lastName` (_string_, nullable) Last Name.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `email` (_string_, nullable) Email ID.
*   `address` (_Address_)
*   `personalId` (_PersonalID_)

### DeltaCart

*   `scale` (_integer (int32)_)
*   `roundingMode` (_string_)  
    Allowed values: `UP`, `DOWN`, `CEILING`, `FLOOR`, `HALF_UP`, `HALF_DOWN`, `HALF_EVEN`, `UNNECESSARY`.
*   `transactionId` (_string_)
*   `transactionTimeStamp` (_integer (int64)_)
*   `storeAttribution` (_StoreAttribution_)
*   `transactionType` (_string_)  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`.
*   `orderId` (_string_)
*   `productList` (_array of Product_)
*   `cancelProductList` (_array of Product_)
*   `productPriceAdjustmentList` (_array of ProductPriceAdjustment_)
*   `tenderList` (_array of Tender_)
*   `refundTenderList` (_array of RefundTender_)
*   `pickUpDetailList` (_array of OrderPickUpDetail_)
*   `reducedTaxAfterPriceAdjustment` (_number_)
*   `fulfillmentTypeChangeProductList` (_array of Product_)
*   `fulfillmentTypeChangeCancelProductList` (_array of Product_)
*   `secondaryProductList` (_array of Product_)
*   `deliveryGroupChangeList` (_array of ProductDeltaDeliveryGroup_)
*   `deliveryGroupList` (_array of DeliveryGroup_)
*   `secondaryDeliveryGroupList` (_array of DeliveryGroup_)
*   `updatedDeliveryGroupList` (_array of DeliveryGroup_)
*   `summary` (_CartSummary_)
*   `originalProductDeliveryGroupList` (_array of ProductDeliveryGroup_)
*   `notesList` (_array of DeltaOrderNote_)
*   `detailNotesList` (_array of DeltaOrderDetailNote_)
*   `removedDeliveryGroupList` (_array of DeliveryGroup_)
*   `productPickUpDetailList` (_array of ProductPickUpDetail_)

### StatusLine

*   `reasonPhrase` (_string_)
*   `protocolVersion` (_ProtocolVersion_)
*   `statusCode` (_integer (int32)_)

### HttpEntity

*   `repeatable` (_boolean_)
*   `streaming` (_boolean_)
*   `chunked` (_boolean_)
*   `content` (_object_)
*   `contentLength` (_integer (int64)_)
*   `contentType` (_Header_)
*   `contentEncoding` (_Header_)

### ProtocolVersion

*   `protocol` (_string_)
*   `major` (_integer (int32)_)
*   `minor` (_integer (int32)_)

### Header

*   `name` (_string_)
*   `value` (_string_)
*   `elements` (_array of HeaderElement_)

### HttpParams

### POSCrashData

*   `merchantId` (_string_) Merchant ID.
*   `locale` (_string_) Locale.
*   `region` (_string_) Region.
*   `installationId` (_string_) Unique Installation ID.
*   `storeId` (_string_) Store ID.
*   `storeAssociateId` (_string_) Store Associate ID.
*   `storeRegisterId` (_string_) Store Register ID.
*   `crashTimeStamp` (_integer (int64)_) Timestamp of when the crash occurred. Represented as milliseconds since epoch.
*   `crashId` (_string_) Crash ID.
*   `crashDataRecordId` (_string_) Unique ID for the crash data record.
*   `appVersion` (_string_) App Version.
*   `buildVersion` (_string_) Build Version.
*   `deviceType` (_string_) POS device type. For example, iPad.
*   `osVersion` (_string_) Device OS Version.

### OfflinePOSVitalsLog

Offline vital details.

*   `offlinePOSVitalsStartTime` (_integer (int64)_) Record of offline POS Vital Start Time.
*   `offlinePOSVitalsEndTime` (_integer (int64)_) Record of offline POS Vital End Time.
*   `offlineReason` (_string_, nullable) Record of offline reason.
*   `description` (_string_, nullable) Description of offline reason.
*   `lastOnlineOrderPlacedOn` (_integer (int64)_) Last time when an online order was placed. Represented as milliseconds since epoch.
*   `lastOfflineOrderPlacedOn` (_integer (int64)_) Last time when an offline order was placed. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastUpdatedOn` (_integer (int64)_) Last time when offline tax feed was updated. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline tax feed was last stored. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastDownloadedOn` (_integer (int64)_) Timestamp when the offline tax feed was last downloaded. Represented as milliseconds since epoch.
*   `offlineTaxFeedDbRecordCount` (_integer (int32)_) Number of records in the offline tax feed database.
*   `offlineTaxFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline tax feed.
*   `offlineStoreCredentialsLastStoredOn` (_integer (int64)_) Timestamp when offline store credentials were last stored. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastUpdatedOn` (_integer (int64)_) Timestamp when offline store credentials were last updated. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastDownloadedOn` (_integer (int64)_) Timestamp when offline store credentials were last downloaded. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsDbRecordCount` (_integer (int32)_) Number of records in the offline store credentials database.
*   `offlineStoreCredentialsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline store credentials.
*   `offlineProductFeedLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product feed was created. Represented as milliseconds since epoch.
*   `offlineProductFeedLastProcessedFileName` (_string_) Name of the last processed file for offline product feed.
*   `offlineProductFeedLastUpdatedOn` (_integer (int64)_) Timestamp when the offline product feed was last updated. Represented as milliseconds since epoch.
*   `offlineProductFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline product feed was last stored. Represented as milliseconds since epoch.
*   `offlineProductFeedDbRecordCount` (_integer (int32)_) Number of records in the offline product feed database.
*   `offlineProductFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product feed.
*   `offlineProductDeltaLastStoredOn` (_integer (int64)_) Timestamp when offline product delta data was last stored. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastUpdatedOn` (_integer (int64)_) Timestamp when offline product delta data was last updated. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedOn` (_integer (int64)_) Timestamp when offline product delta data was last downloaded. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastProcessedFileName` (_string_) Name of the last processed file for offline product delta data.
*   `offlineProductDeltaLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product delta data was created. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product delta data.
*   `offlinePromotionsLastProcessedFileName` (_string_) Name of the last processed file for offline promotions.
*   `offlinePromotionsLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline promotions was created. Represented as milliseconds since epoch.
*   `offlinePromotionsLastDownloadedOn` (_integer (int64)_) Timestamp when offline promotions data was last downloaded. Represented as milliseconds since epoch.
*   `offlinePromotionsLastStoredOn` (_integer (int64)_) Timestamp when offline promotions data was last stored. Represented as milliseconds since epoch.
*   `offlinePromotionsLastUpdatedOn` (_integer (int64)_) Timestamp when offline promotions data was last updated. Represented as milliseconds since epoch.
*   `offlinePromotionsDbRecordCount` (_integer (int32)_) Number of records in the offline promotions database.
*   `offlinePromotionsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline promotions data.
*   `merchantId` (_string_)
*   `installationId` (_string_)
*   `storeId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### PackageDimension

Dimension of package being shipped.

*   `length` (_number_, required) Length of the package.  
    Example: `12.2`.
*   `height` (_number_, required) Height of the package.  
    Example: `12.2`.
*   `width` (_number_, required) Width of the package.  
    Example: `12.2`.

### ShipmentItem

Items in the package.

*   `productId` (_string_) Product ID.
*   `quantity` (_integer (int32)_) Number of items.
*   `orderItemId` (_string_) Item sequence or system-generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `shippingMethodId` (_string_) Unique Identifier for the Shipping Method.
*   `shippingCarrier` (_string_) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.
*   `deliveryDate` (_integer (int64)_) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_) Expected delivery time slot.  
    Example: `09:00 - 12:00`.

### ShippingOption

Shipping method options.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.
*   `name` (_string_) Shipping Method Name.
*   `description` (_string_) Description.
*   `shippingCarrier` (_string_, required) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.
*   `serviceLevel` (_string_) Service-level description. This is shown on the POS app. For example, 3-5 Days, 1-Day, Express, Standard, Overnight.
*   `price` (_number_, required) Shipping Method Price.
*   `sortOrder` (_integer (int32)_, required) Display rank. Helps determine display sequence of shipping methods on screen. For example, a shipping method with display rank of 1 will be displayed beforea method with display rank 2 and so on.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.

### ShippingSPIProduct

Details of an item available in the cart. Includes mandatory and optional item attributes. The optional attributes are provided only if they are configured with product field mapping. Product field mapping is available under **CMS** > **Feeds** > **Field Mappings** > **Products**. To learn more about field mapping, salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-field-mapping.html.

*   `productId` (_string_, required) Distinct product ID for each combination of variations, for example, size or color.  
    Example: `3661601595547`.
*   `title` (_string_, required) Product title.  
    Example: `E18PENDANT1`.
*   `description` (_string_, required) Product description.  
    Example: `Number 1 medallion`.
*   `productClass` (_string_, required) Product class of the item.  
    Example: `Merchandise`.
*   `categories` (_array of string_) Merchant categories of the product. A pipe-separated list of category names belongs to this product.  
    Items: Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`.
*   `googleCategory` (_string_) Product categories for Google search.  
    Example: `Accessories > Categories > Jewelry`.
*   `imageUrl` (_string_) Image url of the product.  
    Example: `https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html`.
*   `additionalImageUrls` (_array of string_) Additional image urls of the product.  
    Items: Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`.
*   `condition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`, `NEW, USED, REFURBISHED` . Example: `NEW`.
*   `availability` (_string_) Free text value that provides information about the availability of the product.  
    Example: `Available`.
*   `listPrice` (_number (double)_, required) Listing price of the product.  
    Example: `60`.
*   `salePrice` (_number (double)_, required) Sale price of the product. It can be same as listing price.  
    Example: `60`.
*   `storePrice` (_number (double)_) Store specific price of the product.  
    Example: `55`.
*   `currencyCode` (_string_) ISO currency code.  
    Default: `USD`. Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `brand` (_string_) Product's brand.  
    Example: `Gucci`.
*   `gtin` (_string_) Product's GTIN. It can be one of UPC, EAN, JAN, ISBN, or ITF-14.  
    Minimum length: 12. Maximum length: 14. Example: `065100004327`.
*   `mpn` (_string_) Manufacturer part number.  
    Example: `100-440-0.750-3434-A`.
*   `gender` (_string_) Free text to provide gender related to the product.  
    Example: `Unisex`.
*   `ageGroup` (_string_) Free text to provide age group related to the product.  
    Example: `10-45`.
*   `subVariantGroupId` (_string_) Sub variant group id.
*   `variantGroupId` (_string_, required) Group id of the product. All the different variations of the product are grouped together under a single group id.  
    Example: `E18PENDANT1`.
*   `color` (_string_) Product color.  
    Example: `Silver`.
*   `colorSwatchUrl` (_string_) The image link for color swatches.
*   `size` (_string_) Product size.  
    Example: `M`.
*   `pattern` (_string_) Free text to provide the product pattern.  
    Example: `Oval`.
*   `sku` (_string_) SKU Id of the product. It can be same as product Id and unique per variation of the product.  
    Example: `3661601595547`.
*   `isOnSale` (_boolean_, required) Specifies whether the product is on sale.  
    Example: `false`.
*   `promotionTitle` (_string_, nullable) Promotion title applicable to the product.  
    Example: `Summer22`.
*   `promotionPrice` (_number (double)_, nullable) Discounted price after applying promotion corresponding to the promotion title.  
    Example: `55`.
*   `customString0` (_string_, nullable) Custom field of type String.
*   `customString1` (_string_, nullable) Custom field of type String.
*   `customString2` (_string_, nullable) Custom field of type String.
*   `customString3` (_string_, nullable) Custom field of type String.
*   `customString4` (_string_, nullable) Custom field of type String.
*   `customString5` (_string_, nullable) Custom field of type String.
*   `customString6` (_string_, nullable) Custom field of type String.
*   `customString7` (_string_, nullable) Custom field of type String.
*   `customString8` (_string_, nullable) Custom field of type String.
*   `customString9` (_string_, nullable) Custom field of type String.
*   `customString10` (_string_, nullable) Custom field of type String.
*   `customString11` (_string_, nullable) Custom field of type String.
*   `customString12` (_string_, nullable) Custom field of type String.
*   `customInt0` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customInt1` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customDecimal0` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDecimal1` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDateTime0` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `customDateTime1` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `onlineInventory` (_integer (int32)_, nullable) The current online inventory. Provide a value if online inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `material` (_string_, nullable) Product material.  
    Example: `Metal`.
*   `manufacturer` (_string_, nullable) Manufacturer of the product.  
    Example: `ABC Jewellers`.
*   `sizeGuideUrl` (_string_, nullable) Image url of the size guide.
*   `manufacturerDetails` (_string_, nullable) Manufacturer details.
*   `manufacturerLocation` (_string_, nullable) Location of product manufacturer.
*   `productLocation` (_string_, nullable) Product manufacturing location.
*   `banner` (_string_, nullable) Banner text. If provided, it will be shown on PLP and PDP screens.
*   `availableStores` (_array of string_, nullable) List of stores where the product is available.
*   `lastUpdate` (_string (date-time)_)
*   `storeInventory` (_integer (int32)_, nullable) The current store inventory. Provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `isVirtual` (_boolean_, nullable) Specifies whether the product is available only in online mode (true) or not (false).
*   `multipleGTINs` (_array of string_, nullable) If the product supports multiple GTINs, provide all of them.
*   `storeProductDetails` (_StoreProductDetails_)
*   `onlineAvailableStores` (_array of string_, nullable) List of stores where online products are available.
*   `costPrice` (_number (double)_, nullable) Cost of per item.
*   `casePackQuantity` (_integer (int32)_, nullable) Number of items per case pack.
*   `additionalCharges` (_string_, nullable) Additional charges for CA, FR.
*   `casePackID` (_string_, nullable) Identifier for case pack.
*   `availabilityStartTime` (_string (date-time)_, nullable) Start time, when product is visible on POS.
*   `availabilityEndTime` (_string (date-time)_, nullable) End time, when product will not be visible on POS.
*   `price` (_number_, required) Unit price of this line item.
*   `quantity` (_integer (int32)_, required) Quantity of this line item.
*   `fulfillmentLocation` (_Store_, required)
*   `shippingAddress` (_SPIAddress_)
*   `deliveryDate` (_integer (int64)_) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_) Expected delivery time slot.  
    Example: `09:00 - 12:00`.

### SpiTaxBucket

All products that require tax calculations are grouped based on their origin and destination addresses, and provided in these tax buckets, along with any applicable tax exemptions.

*   `products` (_array of TaxProduct_, required) List of Products that have the same originating and destination address.
*   `taxExemptions` (_array of SpiTaxExemptionRequest_, nullable) The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT.
*   `originStoreId` (_string_, nullable) The originating store ID where the transaction is occurring.
*   `fromAddress` (_SPIAddress_, required)
*   `toAddress` (_SPIAddress_, required)

### TaxOrVatRecord

List of products and their tax rates.

*   `amount` (_number_, required) Product Amount.
*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Product Quantity.
*   `orderItemId` (_string_, required) Order item ID of the product. This must match the orderItemId sent in the request. Used as a line identifier to resolve conflicts when two line items have the same productId.
*   `description` (_string_, nullable) Product name.
*   `taxClass` (_string_, nullable) Tax class of this product. Can be used for tax calculation. It will be sent if the product feed has it.
*   `taxRecord` (_SpiTax_)
*   `vatRecord` (_SpiVat_)

### SpiBucket

The list of tax buckets which include products, their tax rates, source and destination addresses, and tax exemptions if any.

*   `products` (_array of TaxProduct_, required) List of Products that have the same originating and destination address.
*   `taxExemptions` (_array of SpiTaxExemptionRequest_, nullable) The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT.
*   `originStoreId` (_string_, nullable) The originating store ID where the transaction is occurring.
*   `fromAddress` (_SPIAddress_, required)
*   `toAddress` (_SPIAddress_, required)
*   `records` (_array of TaxOrVatRecord_, required) List of products and their tax rates.

### SpiTaxExemption

List of tax exemptions that are supported by the merchant's tax engine and can be used for tax calculations. Tax exemptions are optional and can have an empty response.

*   `taxExemptCode` (_string_, required) Tax exemption code to be applied, for example, 100, 05, A, or CED.
*   `taxExemptName` (_string_, required) Tax exemption long name, for example, RESALE or TRIBAL GOVERNMENT.
*   `taxExemptionRate` (_number_, required) Tax exemption rate percentage.
*   `taxType` (_string_, nullable) Tax Type.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`.
*   `taxClasses` (_array of string_, nullable) Tax classes to which the exemption applies.
*   `countryCode` (_string_, nullable) Country Code where the exemption is applicable.
*   `state` (_string_, nullable) State where the exemption is applicable.
*   `city` (_string_, nullable) City where the exemption is applicable.
*   `postalCode` (_string_, nullable) Postal Code where the exemption is applicable.

### SpiWarrantyCheckResponseItem

Array of eligible warranty products. Empty array if no warranties apply.

*   `warrantyProductId` (_string_) Product ID of the warranty SKU. Must match a product configured in CMS.
*   `name` (_string_) Display name of the warranty shown in the warranty panel and on the receipt.
*   `price` (_number_) Total warranty price for this item.
*   `description` (_string_) Entitlement/terms text shown in the warranty panel and printed on the receipt.
*   `coveredProductIds` (_array of string_) One or more productId values from cartItemList covered by this warranty.
*   `pricingType` (_string_) Pricing type: CATEGORY\_BASED (MVP).
*   `quantity` (_integer (int32)_) Quantity. For CATEGORY\_BASED always 1.

### SpiPromotion

Promotion attributes included in a promotion webhook event. Represents a curated view of the Promotion for external consumers.

*   `promotionId` (_string_, required) Unique identifier assigned to the promotion.
*   `name` (_string_, required) Internal name used to identify the promotion.
*   `title` (_string_, required) Display title shown on the presentation layer.
*   `description` (_string_, required) Detailed description including disclaimer and other information shown on the presentation layer.
*   `inStorePromoCode` (_string_) Promo code entered by the customer for in-store (STORE channel) sales.
*   `appPromoCode` (_string_) Promo code entered by the customer for in-app (APP channel) sales.
*   `onlinePromoCode` (_string_) Promo code entered by the customer for online (WEB channel) sales.
*   `outletPromoCode` (_string_) Promo code entered by the customer for outlet store (OUTLET channel) sales.
*   `startTimeStamp` (_integer (int64)_, required) Promotion start time in Unix epoch milliseconds.
*   `endTimeStamp` (_integer (int64)_, required) Promotion end time in Unix epoch milliseconds.
*   `combinationTypes` (_array of string_) List of promotion types this promotion can be combined with, for example, ORDER\_PERCENT\_OFF or FREE\_SHIPPING.
*   `channel` (_array of string_, required) Sales channels this promotion applies to (ALL, WEB, APP, STORE, OUTLET). Not applicable for auto promotions.
    
    Each item: Different Channel Types supported by the Promotion Engine.
    
      
    Items: Allowed values: `ALL`, `WEB`, `APP`, `STORE`, `OUTLET`.
*   `priorityOrder` (_integer (int32)_) Priority order for promotion application. Lower number means higher priority.
*   `active` (_boolean_, required) Whether the promotion is active. Only active promotions are evaluated by the promo engine.
*   `auto` (_boolean_, required) Whether the promotion is applied automatically without requiring a promo code.
*   `redemptionLimit` (_number (double)_) Maximum number of times this promotion can be redeemed.
*   `promotionType` (_string_, required) Different promotion Types supported by the Promotion Engine.  
    Allowed values: `ORDER_PERCENT_OFF`, `ORDER_AMOUNT_OFF`, `FREE_SHIPPING`, `BXGY`, `FREE_SAMPLES`, `X_FOR_Y`, `PRODUCT_FIXED_AMOUNT`, `FREE_SHIPPING_V2`.
*   `redeems` (_number (double)_) Current number of times this promotion has been redeemed.
*   `percentOff` (_number (double)_) Percentage discount applied by this promotion.
*   `amountOff` (_number_) Fixed amount discounted by this promotion.
*   `freeShippingMethods` (_array of string_) List of shipping method codes eligible for free shipping under this promotion.
*   `hasSingleUsePromoCodes` (_boolean_) Whether this promotion uses single-use (one-time) promo codes.
*   `imageUrl` (_string_) URL of the image associated with this promotion.
*   `freeSamples` (_array of CombinationGroup_) Free sample products awarded when this promotion is applied.
*   `merchantPromotionId` (_string_) Merchant-defined identifier for this promotion.
*   `amount` (_number_) Fixed promotional amount applied to qualifying items.
*   `qualifyingProducts` (_array of CombinationGroup_) Products that must be purchased to qualify for this promotion (used in BXGY and combination promotions).
*   `discountedProducts` (_array of CombinationGroup_) Products that receive the discount when the qualifying condition is met.
*   `discountedGroupProration` (_boolean_) Whether the discount is prorated across items in the discounted product group.
*   `productRules` (_array of PromotionRule_) Rules applied to specific products to determine promotion eligibility.
*   `customerRules` (_array of PromotionRule_) Rules applied to customer attributes to determine promotion eligibility.
*   `locationRules` (_array of PromotionRule_) Rules applied to store location attributes to determine promotion eligibility.
*   `orderRules` (_array of PromotionRule_) Rules applied to order-level attributes to determine promotion eligibility.
*   `bxgyDiscountType` (_string_) Buy X Get Y Discount Types.  
    Allowed values: `PERCENT_OFF`, `AMOUNT_OFF`, `FIXED_PRICE`.

### IMSAddress

IMS-specific address format for inventory management and fulfillment operations. Used for shipFrom and shipTo locations in ASN shipments.

*   `locationId` (_string_) Location identifier.
*   `locationType` (_string_) Type of location (e.g., warehouse, store, distribution center).
*   `name` (_string_) Primary location name.
*   `additionalName` (_string_) Additional location name or identifier.
*   `streetAddress1` (_string_) Street address line 1.
*   `streetAddress2` (_string_) Street address line 2.
*   `city` (_string_) City.
*   `state` (_string_) State or province.
*   `postalCode` (_string_) Postal or ZIP code.
*   `country` (_string_) Country.

### Order

List of orders contained in the shipment.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `pallets` (_array of Pallet_, required) List of pallets contained in the order.

### FeedFileMetadata

*   `fileName` (_string_)
*   `feedFileType` (_string_)  
    Allowed values: `CSV`, `TSV`, `SSV`, `PSV`, `XML`, `STORE_XML`, `INVENTORY_XML`, `JSON`, `YEXT`, `ASN_EDI_856`, `OTHER`.
*   `feedPreprocessorClass` (_string_)
*   `parentTag` (_string_)
*   `multiValueFieldList` (_array of string_)
*   `preserveIfNullFieldList` (_array of string_)
*   `idColumn` (_string_)
*   `multiValueFieldDelimiter` (_string_)
*   `columnNames` (_string_)
*   `sourceEncoding` (_string_)

### BodyPart

*   `contentDisposition` (_ContentDisposition_)
*   `entity` (_object_)
*   `headers` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of string`.
    
*   `mediaType` (_MediaType_)
*   `messageBodyWorkers` (_MessageBodyWorkers_)
*   `parent` (_MultiPart_)
*   `providers` (_Providers_)
*   `parameterizedHeaders` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of ParameterizedHeader`.
    

### DeliveryItem

List of items in this shipment. This can be a subset of the product list provided at the order level.

*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Number of items.
*   `orderItemId` (_string_) Item sequence/system generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### Transaction

The transaction details.

*   `transactionTimeStamp` (_integer (int64)_, required) Timestamp from when the transaction was executed. Epoch time in milliseconds.  
    Example: `1714112491`.
*   `transactionType` (_TransactionType_)
*   `orderId` (_string_, required) Order Identifier.  
    Maximum length: 128.
*   `summary` (_CartSummary_, required)
*   `storeAttribution` (_StoreAttribution_)
*   `receiptPrintCount` (_integer (int32)_, nullable) Receipt print count — the number of original and duplicate receipts.  
    Default: `1`.
*   `fiscalData` (_OrderFiscalData_)
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions. Applicable for tax countries and if the sale is tax exempted.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakdown corresponding to the transaction. This includes all tax rates applied on the transaction. Applicable for tax countries. If all items are not taxable, this list will be empty.
*   `tenders` (_array of OrderPaymentDetails_, nullable) Payment information: The system supports multiple payment options.  
    Whenever an order is purchased using payment instrument/s,  
    the order will have this list of tenders. However, there are some exceptional scenarios  
    where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.
*   `refundPaymentDetails` (_array of OrderRefundPaymentDetail_, nullable) Refund payments. If it is a return or exchange transaction, it will have refund payments.
*   `shippingAddress` (_Address_)
*   `shippingMethod` (_ShippingMethod_)
*   `billingAddress` (_Address_)
*   `productList` (_array of Product_, nullable) List of products in this order. The list doesn't include returned products. Required for sale transactions. For returns where all items were returned, the list is empty.
*   `returnProductList` (_array of Product_, nullable) List of items that have been returned. It is mandatory for return and exchange transaction.
*   `numberOfLineItems` (_integer (int32)_, read-only) Total number of line items.
*   `receiptId` (_string_, read-only, nullable) Receipt ID for the transaction. Applicable for fiscal reporting.
*   `store` (_Store_, required)
*   `profile` (_Profile_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `returnProductPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `customerEmail` (_string_, nullable) Customer email ID. Available for signed-in customers or when email is captured in the shipping address for guest customers.  
    Maximum length: 128.
*   `manualReceiptId` (_string_, nullable) Manual receipt ID. Required in some countries like Portugal where a pre-printed paper receipt with its own receipt ID needs to be issued for offline transactions.
*   `offlineMode` (_boolean_, nullable) Flag indicating if the transaction was executed in offline mode or not.  
    Default: `false`.
*   `referenceReceiptId` (_string_, nullable) Reference receipt ID. Populated for return and exchange transactions. This field provides original sale's receipt ID for reference.
*   `storeAssociate` (_Associate_)
*   `duplicateReceiptText` (_string_) For internal use only. Don't use in external systems. Duplicate receipt text printed on the receipt, for example, 'Duplicata' or 'Copy of Original Document'.
*   `notesList` (_array of OrderNote_, nullable) List of notes for this order if any.
*   `productNotesList` (_array of OrderDetailNote_, nullable) List of product notes for this transaction if any.
*   `noReceiptReturns` (_boolean_, nullable) Flag indicating if this is an order returned without any receipt.
*   `employee` (_Employee_)
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the order. Eg. Reason details for discounts applied on order.
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address, corresponding shipping method, and other delivery details. This field is used for item level shipping method and address. Mandatory for all delivery items if item level shipping method or item level shipping address is enabled. For more details, see:.
*   `deliveryGroupChangeList` (_ProductDeltaDeliveryGroup_)
*   `nafCode` (_string_, nullable) NAF code. NAF codes in France are used to identify the type of business of an enterprise. For example, 4772A means retail sale of footwear.
*   `rewardList` (_array of Reward_, read-only, nullable, deprecated) Deprecated. Use `orderProductList.priceAdjustments` instead.
*   `loyaltyId` (_string_, nullable) The loyalty Id of the customer in case they are enrolled in the loyalty program.
*   `pointsEarned` (_integer (int32)_, read-only, nullable) The number of loyalty points earned in this transaction.Applicable for order with customer enrolled in the loyalty program.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup persons.  
    Applicable if the order has items that need pickup from a store  
    Each item can have separate pickup person  
    and the each item will have link to its pickup person.  
    
*   `productPickUpDetailList` (_array of ProductPickUpDetail_, nullable) List of product pickup detail.  
    Applicable if the order is edit order.
*   `returnCustomerInformation` (_ReturnCustomerInformation_)
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Fulfillment type for the order. For example, IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `removedDeliveryGroups` (_array of DeliveryGroup_, nullable) The removed delivery group during the edit order mode.

### PrintData

Print Data object. Used to print fiscalization related information on receipts.

*   `name` (_string_) Name of the field which holds this value.
*   `value` (_string_) Actual value that will be printed.
*   `label` (_string_) Label against which this value will be printed.
*   `type` (_string_) Indicates type of data to be printed, for example, TEXT or QRCode.  
    Allowed values: `Text`, `QRCode`.

### PaypalData

PayPal details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `payerId` (_string_)
*   `token` (_string_)
*   `email` (_string_)
*   `payPalInvoiceId` (_string_)
*   `referenceTransactionId` (_string_)
*   `authTransactionId` (_string_)
*   `payPalTokenTimestamp` (_string_)

### SquareData

Square Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `clientId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)

### AdyenData

Adyen Details.

*   `transactionId` (_string_)
*   `cardLastFourDigits` (_string_)
*   `correlationId` (_string_)
*   `receiptLines` (_array of PaymentReceiptLine_)
*   `pspAuthCode` (_string_)
*   `pspReference` (_string_)
*   `cardType` (_string_)
*   `cardHolderName` (_string_)
*   `cardExpiryYear` (_string_)
*   `cardExpiryMonth` (_string_)
*   `cardString` (_string_)
*   `tenderReference` (_string_)
*   `terminalId` (_string_)
*   `cardNumber` (_string_)
*   `operatingMode` (_string_)
*   `threeds2Details` (_string_)

### OrderAttribution

Order attributions corresponding to this order.

*   `orderId` (_string_, read-only) Order Id.
*   `notificationId` (_string_, read-only, nullable) Notification sent corresponding to the order.
*   `messageId` (_string_, read-only, nullable) Message triggered corresponding to the order.
*   `geofenceId` (_string_, read-only, nullable) Geofence ID corresponding to the order.
*   `branchId` (_string_, read-only, nullable) Branch ID corresponding to the order.
*   `storeAreaLevel1Id` (_string_, read-only, nullable) Store Area level 1 corresponding to the order.
*   `storeAreaLevel2Id` (_string_, read-only, nullable) Store Area level 2 corresponding to the order.
*   `storeAreaLevel3Id` (_string_, read-only, nullable) Store Area level 3 corresponding to the order.
*   `storeAreaLevel4Id` (_string_, read-only, nullable) Store Area level 4 corresponding to the order.
*   `storeAreaLevel5Id` (_string_, read-only, nullable) Store Area level 5 corresponding to the order.
*   `storeRegisterId` (_string_, read-only, nullable) Store register corresponding to the order.
*   `registerTransactionId` (_string_, read-only, nullable) Register transaction ID corresponding to the order.

### ExternalStoreAssociateAttribution

Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.

*   `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction.
*   `contributionPercentage` (_number_, required) Associate's contribution towards sales.
*   `attributionNote` (_string_) Note related to attribution.
*   `firstName` (_string_, required) Associate's first name.
*   `lastName` (_string_, required) Associate's last name.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item.
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request.

### ExternalProductTax

Tax/Vat details.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption.
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates.
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates.
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### ExternalPriceAdjustment

Price adjustments applied on the item.  
It includes all the price adjustments like transaction discount, price override etc...  
Mandatory if any type of price adjustments is applied.

*   `description` (_string_, required) Price adjustment description.
*   `adjustment` (_string_, required) Price adjustment.
*   `id` (_string_) Promotion Id for applied coupon or auto promotion.
*   `price` (_number_, required) Price adjustment amount.
*   `priceAdjustmentType` (_string_, required) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reason` (_Reason_)
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied.  
    Not applicable for auto promotions,  
    manual price adjustments like price override & transaction discount.
*   `auto` (_boolean_, nullable) Applied promotion is auto or not.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system.  
    If an order is placed directly in the POS, this identifier will not be available.  
    The external system provides this identifier, which will then be replayed to that  
    external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.

### Transactions

Loyalty transactions.

*   `nextStartMonth` (_integer (int32)_)
*   `txnActivity` (_array of TransactionActivity_)

### Tier

Customer's next tier details.

*   `name` (_string_) Tier name.
*   `minPoints` (_number_) Minimum points required for the tier.
*   `display` (_string_)
*   `points` (_integer (int32)_)
*   `memberSince` (_integer (int64)_) Member since, of this tier.
*   `title` (_string_)
*   `subTitle` (_string_)
*   `imageUrl` (_string_)
*   `expiryDate` (_integer (int64)_) Expiry date of the customer's membership.

### CustomAttributes

Custom attributes.

*   `customLabel` (_string_)
*   `customValues` (_array of CustomValue_)

### SPIShipmentProcessorShippingMethod

This selected or default shipping method must be chosen from the shippingMethodList if an address is provided for the delivery group. Refer to other attributes address and shippingMethodList for more details. It is optional.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `price` (_number_, required) Shipping cost.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `itemLevelCharges` (_array of SPIShipmentProcessorItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### ExternalDateTimeSlot

Delivery date time. It is optional. It must be provided if associate/customer has entered the delivery date for the delivery group.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `date` (_integer (int64)_, required) Delivery date in epoch.
*   `timeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ExternalAvailableDateTimeSlot

Available delivery date time slots.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `date` (_integer (int64)_, required) Delivery date in epoch.
*   `availableTimeSlots` (_array of string_) Available time slots.  
    Items: Example: `["12:00 - 14:00"]`.
    
    _Example_
    
    ```
    [
      "12:00 - 14:00"
    ]
    ```
    
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### SpiStoreAddress

The store address.

*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.

### SpiInventory

Inventory details of the product at this store.

*   `availableQuantity` (_integer (int32)_, required) Product quantity available in stock for sale.
*   `quantityOnHand` (_integer (int32)_, required) Product quantity on hand.
*   `allocatedQuantity` (_integer (int32)_, required) Product quantity allocated for shipment or BOPIS orders.
*   `quantityInTransit` (_integer (int32)_, required) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_, required) Product quantity on order for this store.

### Message

*   `message` (_string_)
*   `code` (_string_)
*   `type` (_string_)  
    Allowed values: `ERROR`, `WARN`, `INFO`.

### PaymentData

*   `paymentType` (_string_)
*   `paymentCard` (_Card_)
*   `paymentCardToken` (_string_)
*   `paypalData` (_PaypalData_)
*   `squareData` (_SquareData_)
*   `adyenData` (_AdyenData_)
*   `authorizationCode` (_string_)
*   `reasonCode` (_integer (int32)_)
*   `transactionId` (_string_)
*   `transactionHash` (_string_)
*   `referenceTransactionId` (_string_)
*   `avsResultCode` (_string_)
*   `requestToken` (_string_)
*   `transactionToken` (_string_)
*   `subscriptionId` (_string_)
*   `paymentToken` (_PaymentToken_)
*   `method` (_string_)  
    Allowed values: `Cash`, `Credit`, `External`, `MixedMode`, `PaypalExpress`, `GiftCard`, `Braintree`, `StoreCredit`, `OrderCredit`, `AfterPay`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`, `CreditCard`, `Check`.
*   `paymentNetworkTransactionId` (_string_)
*   `cashTotal` (_number_)
*   `paymentCards` (_array of Card_)
*   `savePaymentData` (_boolean_)
*   `amount` (_number_)
*   `authenticationResponse` (_string_)
*   `returnsGiftCardProduct` (_Product_)
*   `decision` (_string_)
*   `installmentToken` (_string_)
*   `orderPaymentDetail` (_ExchangeOrderPaymentDetail_)
*   `originalTenders` (_array of ExchangeOrderPaymentDetail_)
*   `performUnreferencedRefunds` (_boolean_, deprecated) Use refundMode instead.
*   `orderDate` (_integer (int64)_)
*   `cashDrawerUrl` (_string_)
*   `disclaimerText` (_string_)
*   `roundingAmount` (_number_)
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.
*   `refundMode` (_string_, nullable) Provides the refund mode that requires special handling. Possible values: Unreferenced for unreferenced refund and ExternalAuth for call for auth refund. These refunds are to be issued by the app. If refund mode is empty, regular refund flow will be followed.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `paymentTransactionId` (_string_, nullable) Payment Transaction ID. Used in cases where payment transaction ID is pre-generated and used as reference number by the app side payment gateway integration. Used in case of Elavon.

### OrderReturnsPolicy

All applied return policies.

*   `maxCashRefundAllowed` (_number_)
*   `managerOverrideAllowed` (_boolean_)
*   `applicableReturnsPolicyTypes` (_array of string_)  
    Items: Allowed values: `MaxReturnsDays`, `MaxCashReturns`, `RemapRefundTenders`, `StoreCredit`, `GiftCard`, `CustomerNotInPersonRefund`, `CreditCard`, `NoReceiptReturns`, `Check`.

### ExchangeOrderPaymentDetail

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `refundAmount` (_number_)
*   `amountToBeAppliedForExchange` (_number_)
*   `refundTransactionId` (_number_)
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use refundMode instead.
*   `refundRoundingAmount` (_number_)
*   `refundMode` (_string_, nullable) If the tender requires special handling when performing a refund, provide the specific refund mode here. Supported modes are Unreferenced and ExternalAuth. For example, during a credit card authorization call, provide the refund mode ExternalAuth when the app issues the refund instead of the regular flow.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `splitRefund` (_boolean_) If an original tender is split into multiple refunds during return and if the current refund tender is one of the split refunds of the original tender. Used in MaxCashReturn policy where original tender might get split into two during returns.
*   `validRefundTender` (_boolean_)
*   `remapped` (_boolean_)
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### ReturnProductIdentification

Returning item's orderItemId and quantity.

*   `orderItemId` (_string_, required) Order item ID of returning product obtained from original order. It provides the returning item's line item number from the original order.
*   `quantity` (_integer (int32)_, required) Total quantity being returned.
*   `reason` (_Reason_)
*   `epc` (_string_) Electronic Product Code/RFID.
*   `serialNumbers` (_array of string_, nullable) Provide serial numbers for returning product if applicable and captured by store associate.  
    Unique items.

### PaymentInstallmentItem

*   `amount` (_number_)
*   `text` (_string_)

### AccountHolder

Account Holders information. Used in case of Tender Type - Finance.

*   `name` (_string_)
*   `primary` (_boolean_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### PersonalID

Customer/Person Identification Information.

*   `type` (_string_, nullable) ID type, for example, State ID, Military ID, or Driving License.
*   `value` (_string_, nullable) ID Number/Value.
*   `expiry` (_string (date-time)_, nullable) ID Expiration Date.
*   `issuedBy` (_string_, nullable) Issued by state.

### RefundTender

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `paymentSequenceNumber` (_integer (int32)_, required) Payment sequence indicating the order of payment. For example, if customer pays partially with cash first and remaining with credit card, then cash tender should have paymentSequenceNumber as 1 and credit card tender should have paymentSequenceNumber as 2.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentDevice` (_string_, required) Identifies the payment device through which the payment is made. If payment data is manually entered, this field should be set to NoReader. If payment is made in an external system, payment device should be set to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `rawPaymentPayload` (_string_) Raw payment payload. For future use.
*   `routingNumber` (_string_) Bank routing number.
*   `accountNumber` (_string_) Account number. Used for payment through banking system.
*   `checkNumber` (_string_) Check number. Used for payment through checks.
*   `personalIdType` (_string_) Personal identification type.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_) Issuer of the personal identification.
*   `personalIdNumber` (_string_) Personal identification number.
*   `personalIdExpiryDateMillis` (_integer (int64)_) Personal identification expiry date represented as milliseconds since epoch. Typically expiry date is end of the day and milliseconds since epoch should reflect it accordingly.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry).
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardCvc` (_string_) Card CVC. Used in case of manual credit card data entry.
*   `track1Data` (_string_) Encrypted track1 data. Used in case of client/app side card encryption by readers like Verifone.
*   `track2Data` (_string_) Encrypted track2 data. Used in case of client/app side card encryption by readers like Verifone.
*   `paymentDeviceId` (_string_) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.
*   `operatingMode` (_string_) Operating mode of the app and card reader - ONLINE/OFFLINE. Other values are unused.  
    Allowed values: `ONLINE`, `OFFLINE`, `DEGRADED`, `TWO_PHASE_STAGING`.
*   `encryptedExpiryDate` (_string_) Encrypted expiry date. Used in case of client/app side card encryption by readers like Verifone.
*   `encryptedCardNumber` (_string_) Encrypted card number. Used in case of client/app side card encryption.
*   `encryptedCvv` (_string_) Encrypted card CVV. Used in case of client/app side card encryption.
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `storedCardId` (_string_) Stored Card ID to use in case of card stored for the customer profile.
*   `cardType` (_string_) Card type. For example, Visa, Master, Amex, or Discover.
*   `rawCardType` (_string_) Raw card type, for example, Visa Credit Card, Visa Debit Card, or Master Credit Card. Typically used when an Adyen terminal captures card data for payment.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year.
*   `pin` (_string_) PIN number typically used for gift card.
*   `authorizationToken` (_string_) Payment authorization token.
*   `authorizationDateMillis` (_integer (int64)_) Payment authorization timestamp as number of milliseconds since epoch.
*   `captureToken` (_string_) Payment capture token.
*   `captureDateMillis` (_integer (int64)_) Payment capture timestamp as number of milliseconds since epoch.
*   `requestId` (_string_) Payment request identification issued by payment gateway/terminal. Typically used for referenced refunds. This field maps to pspReference in case of Adyen payments.
*   `alternateRequestId` (_string_) Alternate payment request identification issued by payment terminal. Example, tender reference in case of Adyen terminal is in store and forward mode.
*   `requestToken` (_string_) Payment request token issued by payment gateway/terminal. Typically used for referenced refunds.
*   `firstName` (_string_) First name to use for billing using this tender.
*   `lastName` (_string_) Last name to use for billing using this tender.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.
*   `city` (_string_) City to use for billing using this tender.
*   `state` (_string_) State to use for billing using this tender.
*   `postalCode` (_string_) Postal code to use for billing using this tender.
*   `country` (_string_) Country code to use for billing using this tender.
*   `paypalInvoiceId` (_string_) Invoice ID. Used when payment is done using paypal reader.
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.
*   `externalPaymentReferenceId` (_string_) External payment reference identifier in case of External tender.
*   `paymentGatewayConfigId` (_string_) Payment Gateway ID - to be used in case of multiple payment gateways are available to process a single tender.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt.
*   `merchantReferenceId` (_string_) Merchant reference ID sent to the payment terminal for this tender. This is required for match response received off asynchronously from payment processor (like Adyen Store and Forward) with the correct payment object for an order.
*   `paymentStatus` (_string_) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `checkType` (_string_) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_) Manual authorization code for a tender. Normally it is received after calling a call center agent of a payment processor. For example, call for auth code after check denial/referral, manual auth code for credit card when offline.
*   `paymentTypeCode` (_string_) Type of payment plan. Used when the tender type is Finance.
*   `cardPresent` (_boolean_) Indicates if the card is physically present or not. Used in case of Tender Type - Finance.
*   `ssn` (_string_) Customer's Social Security Number for verification purposes. Used in case of Tender Type - Finance.
*   `accountHolders` (_array of AccountHolder_) Account Holders information. Used in case of Tender Type - Finance.
*   `additionalInfo` (_array of string_) List of additional information required to verify the buyer. Used in case of Tender Type - Finance.
*   `cashDrawerUrl` (_string_) Represents custom URL using which cash drawer in the network can be accessed.
*   `roundingAmount` (_number_) The delta amount because of rounding.
*   `authStatus` (_string_) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_) Tip amount to capture on credit card.
*   `captureStatus` (_string_) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_) Refers to the finance approval/order/confirmation number in the external system.
*   `financeInstruction` (_string_) Refers to finance processing related result or instruction long text from external system.
*   `primaryAccountHolder` (_string_) Primary owner on the account.
*   `tradeType` (_string_) Trade Type. In case of WeChatPay: QuickPay.
*   `bankType` (_string_) Bank Type.
*   `fundingSource` (_string_) Funding source like PREPAID.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `paymentLink` (_string_) Payment Link.
*   `paymentLinkExpiryDate` (_string_) Payment Link expiry date.
*   `paymentId` (_string_) Payment Id from app.
*   `transactionId` (_string_) The transactionId from app's requestId.
*   `paymentReversalStatus` (_string_) Payment Status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi tender and delete by swiping right, ABORTED is used where we internally remove tender from our tender list and add a new tender for eg gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `captureAmount` (_number_) Amount captured for credit card.
*   `requestTokenExpireDate` (_integer (int64)_) Request token expire date.
*   `continueOnPendingOrDecline` (_boolean_) Continue order processing on tender pending or decline status.
*   `termsAndConditions` (_string_) Terms and conditions.
*   `gcBalance` (_number_, nullable) Balance remaining in case of tender type gift card.
*   `cashTenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `cashChangeAmount` (_number_) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response by gateway. In adyen - a value that uniquely represents the shopper's card number (PAN).
*   `paymentEntryMode` (_string_) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `refundRequestId` (_string_) Refund ID provided by the payment processor after issuing the refund. For example, pspReference in case of Adyen.
*   `refundDate` (_integer (int64)_) Date and time of the refund.
*   `refundedAmount` (_number_) Total amount refunded.
*   `performedUnreferencedRefunds` (_boolean_) Deprecated. Use refundMode instead.
*   `refundedAsPartOfOrderId` (_string_) Order that involves returning an item along with purchase and still refund is issued.
*   `originalTenders` (_array of ExchangeOrderPaymentDetail_) Original tenders associated with the refund.
*   `refundMode` (_string_, nullable) If the tender requires special handling when performing a refund, provide the appropriate refund mode here.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `refundIssued` (_boolean_, read-only, nullable) Flag to indicate refund issued by backend for tenders which are collected by app.  
    Example: `false`.
*   `manualCardEntry` (_boolean_)
*   `error` (_boolean_)

### ProductDeltaDeliveryGroup

List of delivery groups for product.  
, corresponding order item id and new delivery group id.  
It is used for edit order only when changing the delivery group for existing item.

*   `deliveryGroupId` (_string_, required) Delivery group id. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.

### ProductDeliveryGroup

*   `orderItemId` (_string_)
*   `deliveryGroup` (_DeliveryGroup_)

### DeltaOrderNote

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `noteStatus` (_string_, nullable) Note Status for Edit Order, only used in transaction data, Will not persist to Database.  
    Allowed values: `ADD`, `UPDATE`.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### DeltaOrderDetailNote

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `noteStatus` (_string_, nullable) Note Status for Edit Order, only used in transaction data, Will not persist to Database.  
    Allowed values: `ADD`, `UPDATE`.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductPickUpDetail

List of product pickup detail.  
Applicable if the order is edit order.

*   `orderItemId` (_string_)
*   `pickupDetailId` (_string_)
*   `pickupLocation` (_Store_)
*   `dateTimeSlot` (_DateTimeSlot_)

### HeaderElement

*   `name` (_string_)
*   `value` (_string_)
*   `parameterCount` (_integer (int32)_)
*   `parameters` (_array of NameValuePair_)

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### TaxProduct

List of Products that have the same originating and destination address.

*   `amount` (_number_, required) Product Amount.
*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Product Quantity.
*   `orderItemId` (_string_, required) Order item ID of the product. This must match the orderItemId sent in the request. Used as a line identifier to resolve conflicts when two line items have the same productId.
*   `description` (_string_, nullable) Product name.
*   `taxClass` (_string_, nullable) Tax class of this product. Can be used for tax calculation. It will be sent if the product feed has it.

### SpiTaxExemptionRequest

The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT.

*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.
*   `cardNumber` (_string_, required) Customer tax exemption card number.
*   `taxExemptCode` (_string_, required) Tax exemption code to be applied, for example, 100, 05, A, or CED.
*   `taxExemptName` (_string_, required) Tax exemption long name, for example, RESALE or TRIBAL GOVERNMENT.
*   `taxType` (_string_, nullable) Tax Type.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`.

### SpiTax

Tax details for this product. Populate either tax or VAT.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries. Maps to productList.productTax.totalTax in Order TLOG JSON.
*   `taxRates` (_array of ItemTax_, required) Tax rates. Maps to productList.productTax.taxRates\[\] in Order TLOG JSON.
*   `totalExemptionAmount` (_number_) Total tax exemption amount that was applied. Maps to productList.productTax.taxExemption in Order TLOG JSON.

### SpiVat

VAT details for this product. Populate either tax or VAT.

*   `totalVat` (_number_, required) Total VAT. Required in case of VAT countries. Maps to productList.productTax.valueAddedTax in Order/Cart.
*   `vatRates` (_array of ItemTax_, required) VAT rates. Maps to productList.productTax.vatRates\[\] in Order TLOG JSON.
*   `totalExemptionAmount` (_number_, required) Total tax exemption amount that was applied. Maps to productList.productTax.taxExemption in Order TLOG JSON.

### Pallet

List of pallets contained in the order.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `cartons` (_array of Carton_, required) List of cartons contained in the pallet.

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### TransactionType

The type of transaction. Three types of transactions can be done on an order: SALE, RETURN and EXCHANGE.

Type: `string`.

Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`, `SALE`, `RETURN`, `EXCHANGE`. Maximum length: 64. Example: `SALE`.

### OrderPaymentDetails

Payment information: The system supports multiple payment options.  
Whenever an order is purchased using payment instrument/s,  
the order will have this list of tenders. However, there are some exceptional scenarios  
where this list may not be available, which are mentioned below: 1. Partial payment where no minimum payment is required. 2. If a 100% manual or promotional discount is applied.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.

### TransactionActivity

*   `orderId` (_string_)
*   `date` (_integer (int64)_)
*   `description` (_string_)
*   `points` (_integer (int32)_)
*   `amount` (_number_)
*   `pointStatus` (_string_)  
    Allowed values: `EARNED`, `PENDING`, `REWARD`, `REDEEMED`.
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    

### CustomValue

*   `laabel` (_string_)
*   `value` (_string_)
*   `iconType` (_string_)

### SPIShipmentProcessorItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### PaymentToken

*   `data` (_string_)
*   `header` (_PaymentTokenHeader_)
*   `signature` (_string_)
*   `version` (_string_)

### NameValuePair

*   `name` (_string_)
*   `value` (_string_)

### ItemTax

Individual tax rates and their details. After the sale transaction, the TLog JSON will contain the product's tax rates corresponding to this class in productList\[\].productTax.taxRates and orderProductList\[\].productTax.taxRates.

*   `taxRate` (_number_, required) % tax/vat rate.
*   `taxAmount` (_number_, required) Sum of tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) at the time of purchase. This represents the total line tax and should be calculated considering the quantity sent in the request.
*   `taxType` (_string_, required) Indicates tax type, such as COUNTRY, CITY, or STATE.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`.
*   `taxCode` (_string_, required) Tax identifier. This is a unique identifier for tax rate per item.
*   `taxClass` (_string_, required) Tax class to which this tax rate belongs, for example, 1025 or T1C.
*   `perUnitTaxAmount` (_number_, required) The tax amount per unit in the case of multiple quantities of the product.
*   `highPrecisionTaxAmount` (_number_, nullable) Tax amount of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) at the time of purchase with high precision (Scale / Number of decimal digits = 5). Required for Portugal region.
*   `taxName` (_string_, nullable) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.
*   `isExempt` (_boolean_) Indicates whether tax is exempted.  
    Default: `false`.
*   `taxExemptCode` (_string_, nullable) Tax Exemption Identifier to be provided in case this tax was exempted.
*   `taxExemptionAmount` (_number_, nullable) The tax amount value that was exempted.
*   `countryCode` (_string_, required) Country code.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, required) Postal code.

### Carton

List of cartons contained in the pallet.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `items` (_array of IMSInventoryProduct_, required)
*   `hasSerializedProduct` (_boolean_) App uses this boolean to determine the receiving of the entire pallet or carton.
*   `cartonShipments` (_array of Shipment_) List of box shipments contained in the carton.

### PaymentTokenHeader

*   `applicationData` (_string_)
*   `ephemeralPublicKey` (_string_)
*   `publicKeyHash` (_string_)
*   `transactionId` (_string_)

### IMSInventoryProduct

Specific to inventory product.

*   `id` (_string_, required) ID of the entity being transferred.
*   `status` (_string_) Transfer status.  
    Allowed values: `OPEN`, `NEW`, `IN_PROGRESS`, `PARTIAL`, `COMPLETE`, `SHIPPED`, `PARTIAL_SHIPPED`, `DELIVERED`, `RECEIVED`, `CANCELLED`, `PAUSED`, `PARTIAL_PAUSED`.
*   `description` (_string_) Transfer description.
*   `processedBy` (_string_) Processed by ID.
*   `receivedBy` (_string_) Received by ID.
*   `receivedOn` (_integer (int64)_) Received on time represented as milliseconds since epoch.
*   `deliveredTimestamp` (_integer (int64)_) Delivered on time represented as milliseconds since epoch.
*   `scheduledDeliveryTimestamp` (_integer (int64)_) Estimated delivery on time represented as milliseconds since epoch (if not delivered yet).
*   `reasonCode` (_string_, nullable, deprecated) Use reasons instead. Reason code for declining entity transfer.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to declining entity transfer. In general, it has a single reason for any declining entity transfer.
*   `trackingNumber` (_string_, nullable) Item level tracking number.
*   `productTitle` (_string_) Product title.
*   `productImageUrl` (_string_) Product image URL.
*   `color` (_string_) Product color.
*   `size` (_string_) Product size.
*   `gtin` (_string_) Product UPC code.
*   `vendorNumber` (_string_) Product vendor number.
*   `quantity` (_integer (int32)_, required) Product quantity being transferred.  
    Minimum: 1.
*   `quantityTransferred` (_integer (int32)_) Actual product quantity transferred.
*   `quantityReceived` (_integer (int32)_) Actual product quantity received.
*   `serialNumberedItems` (_array of ClearanceItem_)
*   `fullPriceSerialNumbers` (_array of string_) Serial numbers.
*   `removedSerialNumbers` (_array of string_) Removed serial numbers. This is for the backend to remove serial numbers from the database.
*   `serialNumberRequired` (_boolean_) Serial number required.
*   `scannedSerialNumbers` (_array of string_) Scanned serial numbers.
*   `externalDocNumber` (_string_) External Doc Number.
*   `externalLineNumber` (_string_) External Line Number.
*   `itemHierarchyId` (_string_) Item hierarchy ID inside a container.
*   `costPrice` (_number (double)_) Cost price of each item.
*   `casePackQuantity` (_integer (int32)_) Quantity of item per case pack.
*   `casePackID` (_string_) ID of case packed products.
*   `inventoryTransferDetailId` (_string_) When a user manually adds an item to transfer, the backend allocates a UUID to the field and returns it in the response. For all subsequent calls from the app, the same UUID is provided in the request and is used by the backend to determine whether to update or insert the item.
*   `salesPrice` (_number_) Sales price of the product.
*   `shipper` (_string_) Carrier name, for example, FedEx or UPS.

### CustomerMaskRequest

*   `idType` (_string_)  
    Allowed values: `CUSTOMER_ID`, `CUSTOMER_EMAIL`, `CUSTOMER_ORDER_ID`, `MASKED_FIELD`.
*   `ids` (_array of string_)
*   `maskRunType` (_string_)  
    Allowed values: `REPORT_ONLY`, `REPORT_AND_MASK`.

### MerchantNotification

*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)
*   `notificationId` (_string_)
*   `notificationJobId` (_string_)
*   `recipients` (_RecipientData_)
*   `notificationDetail` (_MerchantNotificationDetail_)
*   `status` (_string_)  
    Allowed values: `CREATED`, `READY_TO_SEND`, `SENDING`, `PARTIALLY_SENT`, `SENT`, `NOT_SENT`, `FAILED`, `TERMINATED`.
*   `sentOn` (_integer (int64)_)
*   `sentCount` (_integer (int32)_)
*   `failedCount` (_integer (int32)_)

### MerchantNotificationDetail

*   `notificationId` (_string_)
*   `title` (_string_)
*   `message` (_string_)
*   `icon` (_string_)  
    Allowed values: `PROMOTION`, `CART`, `WISHLIST`.
*   `mediaUrl` (_string_)
*   `deepLink` (_string_)
*   `sendToInbox` (_string_)

### MerchantNotificationRequest

*   `notifications` (_array of MerchantNotification_)

### RecipientData

*   `emails` (_array of string_)
*   `installationIds` (_array of string_)

### SingleUsePromoCodesUploadSchedule

Promotion feed source for one-time use promo code.

*   `schedule` (_string_)
*   `feedSourceParams` (_FeedSource_)
*   `jobId` (_string_)
*   `startDate` (_string_)
*   `endDate` (_string_)
*   `region` (_string_)
*   `locale` (_string_)
*   `nodeExecuteOn` (_string_)
*   `merchantId` (_string_)
*   `feedType` (_string_)  
    Allowed values: `PRODUCT`, `PRODUCT_BUNDLE`, `STORE`, `LAYOUT`, `PRODUCT_PROMOTION`, `PRODUCT_CATEGORY`, `PRODUCT_CATEGORY_PROMOTION`, `PROMOTION`, `STORE_INVENTORY_FULL`, `STORE_INVENTORY_DELTA`, `SOCIAL_MEDIA`, `ONE_TIME_PROMOTION_CODE`, `PRODUCT_DELTA`, `CATEGORY`, `ORDER_LIST`, `ORDER_DETAILS`, `RECOMMENDATION`, `TAX_RATE`, `PIPELINE`, `STORE_ASSOCIATES`, `PREDICTSPRING_PROMOTION`, `REWARD`, `CASH_REWARD`, `ASN`, `CORP_TRANSFER`, `POS_PROVISIONING`, `SYNONYM`, `STORE_AREA_GOAL`, `STORE_AREA_HIERARCHY`, `OMS`, `PRODUCT_PRICING`, `PRODUCT_SIZING`, `PRODUCT_INVENTORY`, `PRODUCT_PRICING_DELTA`, `PRODUCT_SIZING_DELTA`, `PRODUCT_INVENTORY_DELTA`, `STORE_DEVICE`, `BOPIS_CANCEL_ORDER`, `PURCHASE_ORDER`, `OFFLINE_PROMOTION`, `PREDICTSPRING_PROMOTION_V2`, `EXPIRED_PAYMENT_LINK_CLEANUP`, `SINGLE_USE_PROMO_CODES`, `STORE_GROUP_FULL`, `STORE_GROUP_DELTA`.
*   `active` (_boolean_)
*   `backUp` (_boolean_)

### OneTimePromotionCodeLookupRequest

*   `promotionCodes` (_array of string_)

### MultivaluedMapStringParameterizedHeader

*   `empty` (_boolean_)

Additional properties: `array of ParameterizedHeader`.

### MultivaluedMapStringString

*   `empty` (_boolean_)

Additional properties: `array of string`.

### FulfillmentLocation

Store details for the item's fulfillment location. This field is required if an item is SHIP\_TO\_HOME or SHIP\_TO\_STORE.

*   `storeId` (_string_) Store ID.

<!-- document id=6f63fb3050e323bee0a0ab8eee1b90a160a29fb3f2945dcfd94a1d8fa346c6d0 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/poscrashdata-webhook.md -->

POSCrashData Webhook

# POSCrashData Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/poscrashdata-webhook/poscrashdata-webhook-oas-public.yaml)

This API sends POS crash data to external systems.

**Version:** 2.3.4

## Tags

### POSCrashData Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/poscrashdata-webhook/poscrashdata-webhook-oas-public.yaml)

This API sends POS crash data to external systems.

## Operations

### POST Export POSCrashData.

`POST /merchant/spi/sample/endpoint/sa/posCrashData`

Operation ID: `exportPOSCrashData`. Tags: POSCrashData Webhook.

Export POSCrashData to external system.

#### Request body

Media type: `application/json`. Schema: `POSCrashDataRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### POSCrashDataRequest

*   `data` (_array of POSCrashData_)

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### POSCrashData

*   `merchantId` (_string_) Merchant ID.
*   `locale` (_string_) Locale.
*   `region` (_string_) Region.
*   `installationId` (_string_) Unique Installation ID.
*   `storeId` (_string_) Store ID.
*   `storeAssociateId` (_string_) Store Associate ID.
*   `storeRegisterId` (_string_) Store Register ID.
*   `crashTimeStamp` (_integer (int64)_) Timestamp of when the crash occurred. Represented as milliseconds since epoch.
*   `crashId` (_string_) Crash ID.
*   `crashDataRecordId` (_string_) Unique ID for the crash data record.
*   `appVersion` (_string_) App Version.
*   `buildVersion` (_string_) Build Version.
*   `deviceType` (_string_) POS device type. For example, iPad.
*   `osVersion` (_string_) Device OS Version.

<!-- document id=629f9d392af1c8f55f8007a62daf0b091ff1d842712632b1c51fbf74e2b3ab22 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/post-publication.md -->

# Post-Install Maintenance

Manage updates, replication, and support after a Commerce App is installed — whether it was published to the registry or installed privately from WebDAV.

## Updating Your App

Package and test every update as a new CAP. ISVs publish the new version through the App Registry; private-app producers deliver the new `.zip` directly to the merchant. Compare updates with the producer's retained release artifact. For registry apps, `b2c cap pull <app-name> --site-id <site-id>` can retrieve the registry package. Private WebDAV packages can be pulled only when the installed record has a persisted version and the uploaded archive was retained. Include versioned migration directories in `impex/` (for example, `v1.1.0/`) for schema changes that need to run on upgrade.

## Replication Compatibility

### Recommended Merchant Workflow

The expected lifecycle for promoting a Commerce App from staging to production:

1. **Install on staging.** Use Business Manager or `b2c cap install` to install the app on the staging instance for the target site.
2. **Configure and test on staging.** Complete every task in the app's `tasksList.json` (entering API credentials, setting site preferences, running test transactions). Validate end-to-end behavior on the staging storefront before promoting.
3. **Replicate code to production.** Run Code Replication first to move cartridges to the production realm. The app won't function on production until cartridges are present.
4. **Replicate supported site data to production.** Select the applicable site preferences and metadata, including the separate `CommerceFeatureState` replication task. Replicate the cartridge path only after the cartridges are present.
5. **Configure non-replicated resources.** Import or configure service definitions and profiles separately, and enter production credentials on the target instance. Re-run any `tasksList.json` step required for that instance.
6. **Integrate storefront code.** Merge or otherwise deploy Storefront Next code separately; B2C code replication doesn't deploy the merchant's storefront repository.
7. **Verify on production.** Confirm the cartridge path, `CommerceFeatureState`, services, credentials, storefront code, and end-to-end behavior before opening to live traffic.

### How Replication Moves a Commerce App

Commerce Apps are designed to be replication-friendly. An app installed on a staging instance can be promoted to production using standard Commerce Cloud replication:

- Code Replication moves cartridges (realm-scoped)
- Data Replication moves selected supported site data; select `CommerceFeatureState` as its own replication task
- Service definitions and profiles require separate import or target-instance configuration
- Storefront Next code follows the merchant's storefront source-control and deployment process

> **Important:** Code replication must complete before data replication. If the cartridge path is updated before the cartridges exist on the production realm, the storefront fails to initialize the feature.

> **Important:** Standard Data Replication doesn't move service configurations or credentials. Import or configure the required service metadata separately, and enter API keys, passwords, and other secrets on the target instance. Include a credential configuration step in your app's `tasksList.json` for every instance where the app is activated.

See: [Web Services in B2C Commerce](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html)

## Multi-Site Considerations

Commerce Apps support installation across multiple sites within the same realm. For the full mechanism — cartridge sharing, per-site state, deferred cleanup on the last-site uninstall, and feature toggle handling — see [Multi-Site Behavior](/docs/commerce/b2c-commerce/guide/reference.md#multi-site-behavior).

> **Tip for ISVs:** If your app stores site-specific data in custom objects, make sure your uninstall IMPEX handles per-site data cleanup. Instance-scoped resources (service definitions, custom object type definitions) are removed only by the last-site uninstall, which the platform handles automatically.

## Version Management

Version tracking in `catalog.json` applies to **ISVs** publishing to the App Registry. Private apps have no registry entry; ship a new `.zip` and reinstall.

When publishing a new version to the App Registry:

- Update the ZIP and root manifest entry (`version`, `zip`, `sha256` fields). Do **not** manually add new version entries to `catalog.json` — CI generates those automatically when your PR merges. Allow up to 15 minutes after merge for the new version to appear in existing Business Manager sessions; see [Manifest and Catalog Cache TTL](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reference.md#manifest-and-catalog-cache-ttl).
- To deprecate a previous version, add `"deprecated": true` to the **existing** version entry in `catalog.json`. This is the only manual edit to `catalog.json` that is expected. Use deprecation for versions with critical bugs or known issues that should prevent new installations.
- Version upgrades are currently a manual process: merchants uninstall the old version and install the new one. Automated in-place upgrades are planned for a future release (Wave 3).

## Monitoring and Support

For the initial release, implement your own logging within your cartridge scripts and monitor through standard Commerce Cloud mechanisms:

- **Job execution logs:** Installation, uninstallation, and IMPEX processing results are logged in Business Manager under **Administration** > **Operations** > **Job Schedules**. The install job writes detailed step-by-step progress to the job log.
- **Custom script logging:** Use the `dw.system.Logger` API in your hook implementations. Log at appropriate levels: `debug` for detailed flow, `info` for key operations, `warn` for recoverable issues, `error` for failures.
- **CommerceFeatureState:** Query the `CommerceFeatureState` system object to check installation status, configuration progress, and error messages for a specific site. The `InstallationMetadata` JSON field contains the job execution ID, cartridge names, and any error details.

<!-- document id=675a33edf14dc4c96d03cdf34bcaf336d048705986344b5197015be7e0030bed url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/posvitals-webhook.md -->

POSVitals Webhook

# POSVitals Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/posvitals-webhook/posvitals-webhook-oas-public.yaml)

This API sends POS vitals to external systems.

**Version:** 2.3.4

## Tags

### POSVitals Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/posvitals-webhook/posvitals-webhook-oas-public.yaml)

This API sends POS vitals to external systems.

## Operations

### POST Export POSVitals.

`POST /merchant/spi/sample/endpoint/sa/posvitals`

Operation ID: `exportPOSVitals`. Tags: POSVitals Webhook.

Export POSVitals to external system.

#### Request body

Media type: `application/json`. Schema: `POSVitalsDto`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### POSVitalsDto

*   `storeId` (_string_) Store ID.
*   `storeAssociateId` (_string_) Store Associate ID.
*   `installationId` (_string_) Unique Installation ID.
*   `storeRegisterId` (_string_) Store Register ID.
*   `lastSeenOn` (_integer (int64)_) Last time this register was online. Represented as milliseconds since epoch.
*   `lastWentOfflineOn` (_integer (int64)_) Last time when register went offline represented as milliseconds since epoch.
*   `lastOnlineOrderPlacedOn` (_integer (int64)_) Last time when an online order was placed. Represented as milliseconds since epoch.
*   `lastOfflineOrderPlacedOn` (_integer (int64)_) Last time when an offline order was placed. Represented as milliseconds since epoch.
*   `buildNumber` (_string_) Build Number.
*   `lastOfflineProductFeedDownloadedOn` (_integer (int64)_) Last time when offline product feed was downloaded. Represented as milliseconds since epoch.
*   `lastOfflineProductFeedItemCount` (_string_) Number of records in offline product feed download.
*   `numberOfOfflineProducts` (_string_) Number of records that were successfully stored in offline product DB stored in the app.
*   `lastOfflineTaxFeedDownloadedOn` (_integer (int64)_) Last time when offline tax feed was downloaded. Represented as milliseconds since epoch.
*   `lastOfflineTaxFeedItemCount` (_string_) Number of records in offline product feed download.
*   `numberOfTaxEntriesInOfflineDB` (_string_) Number of records that were successfully stored in offline tax DB table stored in the app.
*   `numberOfOrdersInOfflineDB` (_string_) Number of orders in offline order DB table stored in the app.
*   `lastOfflineOrderSyncedOn` (_integer (int64)_) Last time when an offline order sync was done. Represented as milliseconds since epoch.
*   `wifiStrength` (_number_) WiFi Signal Strength.
*   `lastNetworkFailureOccurredOn` (_integer (int64)_) Last time when a network failure happened. Represented as milliseconds since epoch.
*   `lastAssociateSignInOccurredOn` (_integer (int64)_) Last time when a store associate signed in to this register. Represented as milliseconds since epoch.
*   `lastAssociateSignOutOccurredOn` (_integer (int64)_) Last time when store associate signed out to this register. Represented as milliseconds since epoch.
*   `lastAssociateToSignIn` (_string_) Last store associate who signed in to this register.
*   `lastAssociateToSignOut` (_string_) Last store associate who signed out of this register.
*   `deviceName` (_string_) POS Register device name.
*   `deviceType` (_string_) POS device type. For example, iPad.
*   `ipAddress` (_string_) POS register IP address.
*   `cashDrawerSerialNumber` (_string_) Serial number of the cash drawer connected to this POS register.
*   `cashDrawerModel` (_string_) Model number of the cash drawer connected to this POS register.
*   `cashDrawerConnectionType` (_string_) Connection type of the cash drawer connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `scannerSerialNumber` (_string_) Serial number of the scanner connected to this POS register.
*   `scannerModel` (_string_) Model number of the scanner connected to this POS register.
*   `scannerConnectionType` (_string_) Connection type of the scanner connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `cardReaderSerialNumber` (_string_) Serial number of the payment card reader connected to this POS register.
*   `cardReaderModel` (_string_) Model number of the payment card reader connected to this POS register.
*   `cardReaderIpAddress` (_string_) IP address of the payment card reader connected to this POS register.
*   `cardReaderConnectionType` (_string_) Connection type of the payment card reader connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `cardReaderIntegrationType` (_string_) Integration type of the payment card reader connected to this POS register, for example, Terminal API or SDK.
*   `receiptPrinterSerialNumber` (_string_) Serial number of the receipt printer connected to this POS register.
*   `receiptPrinterModel` (_string_) Model number of the receipt printer connected to this POS register.
*   `receiptPrinterIPAddress` (_string_) IP address of the receipt printer connected to this POS register.
*   `receiptPrinterConnectionType` (_string_) Connection type of the receipt printer connected to this POS register, for example, WiFi, LAN, or Bluetooth.
*   `cashDrawerConnected` (_string_) Flag indicating whether cash drawer is connected to this POS register.
*   `cashDrawerConnectedOn` (_integer (int64)_) Last time when cash drawer was connected to this register. Represented as milliseconds since epoch.
*   `cashDrawerConnectionIssue` (_string_) Details about any connect issues related to cash drawer.
*   `printerConnected` (_string_) Flag indicating whether receipt printer is connected to this POS register.
*   `printerLastConnectedOn` (_integer (int64)_) Last time when receipt printer was connected to this register. Represented as milliseconds since epoch.
*   `printerConnectionIssue` (_string_) Details about any connect issues related to receipt printer.
*   `paymentTerminalConnected` (_string_) Flag indicating whether payment terminal is connected to this POS register.
*   `paymentTerminalLastConnectedOn` (_integer (int64)_) Last time when payment terminal was connected to this register. Represented as milliseconds since epoch.
*   `paymentTerminalConnectionIssue` (_string_) Details about any connect issues related to payment terminal.
*   `scannerConnected` (_string_) Flag indicating whether scanner is connected to this POS register.
*   `scannerLastConnectedOn` (_integer (int64)_) Last time when scanner was connected to this register. Represented as milliseconds since epoch.
*   `scannerConnectionIssue` (_string_) Details about any connect issues related to scanner.
*   `lastOfflineAssociatesFeedDownloadedOn` (_integer (int64)_) Last time when offline store associates feed was downloaded to this register. Represented as milliseconds since epoch.
*   `lastOfflineAssociatesItemCount` (_integer (int32)_) Number of offline store associates that were downloaded to this register. This is just the number of records in the download.
*   `numberOfOfflineAssociates` (_integer (int32)_) Number of offline store associates. This is the successfully imported offline associate count.
*   `lastOfflineLoginErrorOccurredOn` (_integer (int64)_) Last time when offline store associate login failed. Represented as milliseconds since epoch.
*   `numberOfPendingOnlineOrders` (_integer (int32)_) Number of pending online orders. This is just to track phase 2 order submission failure.
*   `lastOnlineOrderSyncedOn` (_integer (int64)_) Last time when online orders were synced. Represented as milliseconds since epoch. This is just to track phase 2 order submission failure.
*   `upcScanFailureIssue` (_string_) UPC Scan failure related details. This is different from scanner connection issues.
*   `cardPaymentFailureIssue` (_string_) Card payment failure related details. This is different from payment terminal connection issues.
*   `lastOfflineLoginError` (_string_) Last offline login error details.
*   `offlinePOSVitalsLog` (_OfflinePOSVitalsLog_)
*   `offlineTaxFeedLastUpdatedOn` (_integer (int64)_) Last time when offline tax feed was updated. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline tax feed was last stored. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastDownloadedOn` (_integer (int64)_) Timestamp when the offline tax feed was last downloaded. Represented as milliseconds since epoch.
*   `offlineTaxFeedDbRecordCount` (_integer (int32)_) Number of records in the offline tax feed database.
*   `offlineTaxFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline tax feed.
*   `offlineStoreCredentialsLastStoredOn` (_integer (int64)_) Timestamp when offline store credentials were last stored. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastUpdatedOn` (_integer (int64)_) Timestamp when offline store credentials were last updated. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastDownloadedOn` (_integer (int64)_) Timestamp when offline store credentials were last downloaded. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsDbRecordCount` (_integer (int32)_) Number of records in the offline store credentials database.
*   `offlineStoreCredentialsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline store credentials.
*   `offlineProductFeedLastDownloadedOn` (_integer (int64)_) Last time when offline product feed was downloaded. Represented as milliseconds since epoch.
*   `offlineProductFeedLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product feed was created. Represented as milliseconds since epoch.
*   `offlineProductFeedLastProcessedFileName` (_string_) Name of the last processed file for offline product feed.
*   `offlineProductFeedLastUpdatedOn` (_integer (int64)_) Timestamp when the offline product feed was last updated. Represented as milliseconds since epoch.
*   `offlineProductFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline product feed was last stored. Represented as milliseconds since epoch.
*   `offlineProductFeedDbRecordCount` (_integer (int32)_) Number of records in the offline product feed database.
*   `offlineProductFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product feed.
*   `offlineProductDeltaLastStoredOn` (_integer (int64)_) Timestamp when offline product delta data was last stored. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastUpdatedOn` (_integer (int64)_) Timestamp when offline product delta data was last updated. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedOn` (_integer (int64)_) Timestamp when offline product delta data was last downloaded. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastProcessedFileName` (_string_) Name of the last processed file for offline product delta data.
*   `offlineProductDeltaLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product delta data was created. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product delta data.
*   `offlinePromotionsLastProcessedFileName` (_string_) Name of the last processed file for offline promotions.
*   `offlinePromotionsLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline promotions was created. Represented as milliseconds since epoch.
*   `offlinePromotionsLastDownloadedOn` (_integer (int64)_) Timestamp when offline promotions data was last downloaded. Represented as milliseconds since epoch.
*   `offlinePromotionsLastStoredOn` (_integer (int64)_) Timestamp when offline promotions data was last stored. Represented as milliseconds since epoch.
*   `offlinePromotionsLastUpdatedOn` (_integer (int64)_) Timestamp when offline promotions data was last updated. Represented as milliseconds since epoch.
*   `offlinePromotionsDbRecordCount` (_integer (int32)_) Number of records in the offline promotions database.
*   `offlinePromotionsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline promotions data.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### OfflinePOSVitalsLog

Offline vital details.

*   `offlinePOSVitalsStartTime` (_integer (int64)_) Record of offline POS Vital Start Time.
*   `offlinePOSVitalsEndTime` (_integer (int64)_) Record of offline POS Vital End Time.
*   `offlineReason` (_string_, nullable) Record of offline reason.
*   `description` (_string_, nullable) Description of offline reason.
*   `lastOnlineOrderPlacedOn` (_integer (int64)_) Last time when an online order was placed. Represented as milliseconds since epoch.
*   `lastOfflineOrderPlacedOn` (_integer (int64)_) Last time when an offline order was placed. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastUpdatedOn` (_integer (int64)_) Last time when offline tax feed was updated. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline tax feed was last stored. Represented as milliseconds since epoch.
*   `offlineTaxFeedLastDownloadedOn` (_integer (int64)_) Timestamp when the offline tax feed was last downloaded. Represented as milliseconds since epoch.
*   `offlineTaxFeedDbRecordCount` (_integer (int32)_) Number of records in the offline tax feed database.
*   `offlineTaxFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline tax feed.
*   `offlineStoreCredentialsLastStoredOn` (_integer (int64)_) Timestamp when offline store credentials were last stored. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastUpdatedOn` (_integer (int64)_) Timestamp when offline store credentials were last updated. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsLastDownloadedOn` (_integer (int64)_) Timestamp when offline store credentials were last downloaded. Represented as milliseconds since epoch.
*   `offlineStoreCredentialsDbRecordCount` (_integer (int32)_) Number of records in the offline store credentials database.
*   `offlineStoreCredentialsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline store credentials.
*   `offlineProductFeedLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product feed was created. Represented as milliseconds since epoch.
*   `offlineProductFeedLastProcessedFileName` (_string_) Name of the last processed file for offline product feed.
*   `offlineProductFeedLastUpdatedOn` (_integer (int64)_) Timestamp when the offline product feed was last updated. Represented as milliseconds since epoch.
*   `offlineProductFeedLastStoredOn` (_integer (int64)_) Timestamp when the offline product feed was last stored. Represented as milliseconds since epoch.
*   `offlineProductFeedDbRecordCount` (_integer (int32)_) Number of records in the offline product feed database.
*   `offlineProductFeedLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product feed.
*   `offlineProductDeltaLastStoredOn` (_integer (int64)_) Timestamp when offline product delta data was last stored. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastUpdatedOn` (_integer (int64)_) Timestamp when offline product delta data was last updated. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedOn` (_integer (int64)_) Timestamp when offline product delta data was last downloaded. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastProcessedFileName` (_string_) Name of the last processed file for offline product delta data.
*   `offlineProductDeltaLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline product delta data was created. Represented as milliseconds since epoch.
*   `offlineProductDeltaLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline product delta data.
*   `offlinePromotionsLastProcessedFileName` (_string_) Name of the last processed file for offline promotions.
*   `offlinePromotionsLastDownloadedFileCreatedTime` (_integer (int64)_) Timestamp when the last downloaded file for offline promotions was created. Represented as milliseconds since epoch.
*   `offlinePromotionsLastDownloadedOn` (_integer (int64)_) Timestamp when offline promotions data was last downloaded. Represented as milliseconds since epoch.
*   `offlinePromotionsLastStoredOn` (_integer (int64)_) Timestamp when offline promotions data was last stored. Represented as milliseconds since epoch.
*   `offlinePromotionsLastUpdatedOn` (_integer (int64)_) Timestamp when offline promotions data was last updated. Represented as milliseconds since epoch.
*   `offlinePromotionsDbRecordCount` (_integer (int32)_) Number of records in the offline promotions database.
*   `offlinePromotionsLastDownloadedRecordCount` (_integer (int32)_) Number of records in the last downloaded offline promotions data.
*   `merchantId` (_string_)
*   `installationId` (_string_)
*   `storeId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

<!-- document id=29fd26e65a349ff926ece8d187ebe8ff555eb40ee18d9e60e31636a1b05a1237 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-best-practices.md -->

# Pre-Build and Go-Live Best Practices Checklist

Welcome to the start of your Composable Storefront journey! This checklist summarizes key points that can have a major impact on your project timeline. By focusing on these four best practices, you'll be better equipped to navigate the complexities of building, launching, and monitoring a successful Progressive Web App (PWA) Kit site and avoid common pitfalls. Use this checklist to plan for a smooth and successful deployment!

**note:** Unless otherwise stated, all of the points in this checklist apply to sites that are either built 100% on Composable Storefront or [phased headless rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html).

## 1. Know the Scope of Your Customization Needs

You're in the driver's seat when it comes to customization. Understand the scope of the customization required to meet your business needs. Just remember, a highly customized site requires more effort, as described in these examples.

- Familiarize yourself with the design and functionality available in our [Retail React App](https://pwa-kit.mobify-storefront.com/). You need to build any functionality that isn’t available in the Retail React App.
- Use existing React components as much as possible. PWA Kit uses React, so you have access to the React ecosystem of components. If you’re doing something custom, see if there’s a Chakra component for it. If there isn’t, look for an open source version. If there isn't an open source version, build the component yourself.
- Verify that our APIs support your required custom functionality and return the data that you need. If our APIs don’t, you can:
  - Create a custom API to return the data; or
  - Extend the API response using a hook
- Confirm that your site’s cartridges and integrations work with a headless implementation. To use them in a PWA Kit site, you can expose their functionality using custom APIs or hooks.

### Resources

- [Skills for Success](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/skills-for-success.md)
- [Get Started with B2C Commerce API](https://developer.salesforce.com/docs/commerce/commerce-api/guide)
- [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html)
- [Customization with Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)
- [B2C Developer Documentation Resources](https://salesforcecommercecloud.github.io/b2c-dev-doc/)

## 2. Make Architecture Decisions

Lay a solid foundation for a stable and scalable site by following these steps.

- Decide how many production Managed Runtime (MRT) environments you’ll have. Having more environments gives you more control. But the more environments you have, the more operationally complicated it is to manage them all. For example, if you have five brands that are all served from the same MRT environment, you always need to update them together. Having fewer environments means less operational overhead. See [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html).
- Decide whether to use our embedded content delivery network (eCDN) or a third-party CDN. See [Decide which CDN to Use](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/decide-on-cdn.md). If you decide to use a third-party CDN, see your vendor’s documentation for details.
- To optimize site performance, factor in recommended practices and rate limits when you make API calls. See the [Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.md#considerations) for using the Managed Runtime API.
- Decide on your URL strategy. Most customers choose to keep their existing URLs. Make a plan to redirect any of your current URLs that won’t exist on your new site. Sign up for Google Search Console tools or other ranking tools to monitor the effect of your rollout on your SEO ranking. See [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.html).
- Decide on the goals, scope, and timeline for your hybrid (phased headless) rollout. Keep in mind that the longer your site is in hybrid mode, the more time you have to spend on the operating complexity involved. Set a due date for transitioning to a 100% Composable site. See [Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html).

## 3. Implement Performance Best Practices and Continuous Integration

Apply these techniques to optimize your site's efficiency and user experience.

- Implement performance best practices to optimize your site's efficiency. Manage third-party scripts, optimize web fonts, serve responsive images, perform client-side hydration, and cache data with Managed Runtime. Monitor performance metrics of your site for real-world user experience as well as lab tests. Learn about Core Web Vitals metrics that measure real-world user experience for three key aspects of the page: loading performance, interactivity, and visual stability. For overall performance guidance, see, [Performance Guide for Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-guide.md).
- Review the server-side rendering of entry pages (homepage, category listing pages, product listing pages, and product detail pages) by appending the `?__server_only` parameter to your URLs. Confirm that your server-rendered pages have enough data for crawlers and that the layout shift between server and client is small (ideally non-existent). This can help to improve your SEO ranking, confirm that your entry pages can load quickly on mobile devices, and improve shopper experience.
- Set up performance testing using [Lighthouse CI](https://github.com/GoogleChrome/lighthouse-ci). Start performance testing mid-way through your implementation. This allows you to identify and correct any performance regressions (compared to your current site) long before your PWA Kit site launch.
- Set up continuous [code deployment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) to a non-production MRT environment. From early on in your development work, start testing your code deployed to MRT to confirm that your site functionality works as expected. That way you can avoid costly rework later. See [Automation Users](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/using-the-managed-runtime-api.html#automation-users-).

## 4. Use Observability Tools

Plan to use any of these tools to consistently monitor your site performance. Also verify that the data generated by these tools is correct based on your expected results.

- With [Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debug-using-log-center), you can review errors and metrics. Set up [notifications](https://help.salesforce.com/s/articleView?id=cc.b2c_save_a_search_rule.htm&type=5) so you can find out when your storefront is functioning abnormally and investigate.
- Use [Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/active-data.html) to monitor your site’s metrics. This can help you analyze shopper behavior so you can enhance the shopper experience and optimize product offerings to drive sales growth.
- [B2C Commerce Reports & Dashboards](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reports-and-dashboards.md) provide data that you can use to identify trends over time and to make smarter business decisions based on your B2C Commerce data.

## Next Steps

Review the rest of the recommended developer workflow for building a site on Composable Storefront. See [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.html).

## See Also

- [Performance Guide for Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-guide.md)
- [Track Performance with \_\_server_timing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.md#__server_timing)
- [Monitor Your PWA Kit Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/monitor-site.md)
- [Shopper API Performance and Best Practices](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html)
- [Troubleshoot Request Timeouts](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeout-troubleshoot.html)

<!-- document id=11ddc3f8d2d8f988b9ffee796202b88a0287e64a020816822238da6f47432e23 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/preferences.md -->

Preferences

# Preferences

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/preferences/preferences-oas-v1-public.yaml)

## API Overview

B2C Commerce teams must regularly configure site and environment-specific settings to support changing business needs and technical integrations. In many instances, Storefront Reference Architecture (SFRA)/SiteGenesis implementations rely on declarative Custom Site Preferences to alter these settings without the need for deployment or significant engineering support. Site preferences allow teams to adapt their sites with minimal effort.

The following Preferences API endpoints retrieve preference-related information:

*   Global custom preferences: Retrieves all custom preferences at the organization level.
    
*   Site custom prefererences: Retrieves all custom preferences at the site level.
    

The Preferences API first checks to see if custom values have been set, and if so, returns the custom settings. Otherwise, the Preferences API returns the default values provided in Business Manager.

Note: The Preferences API sets custom preferences. For details on working with non-custom preferences, see [Global Preferences for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_global_preferences.htm&type=5) and [Site Preferences in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_site_preferences.htm&type=5).

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.preferences` in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Global Custom Preference:

A prominent private equity firm manages a diverse portfolio of brands, each operating its own site. Despite the individuality of these brands, they leverage shared third-party integrations for critical functionalities, such as payments and content management. Through a centralized approach, the firm establishes specifications for key components like the payments portal, ensuring consistency and efficiency across all sites. These specifications are meticulously crafted and undergo infrequent modifications to accommodate evolving needs while maintaining operational stability.

#### Site Custom Preference:

Site operators might have numerous tests or features tailored to their specific site. To facilitate streamlined control over these functionalities, they need a user-friendly mechanism for their merchant team to effortlessly toggle them on or off as needed. The site Preference API provides this mechanism.

#### Caching

Caching capabilities are available for the Preferences APIs. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

**Version:** 1.2.3

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/configuration/preferences/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.preferences: Preferences read scope
    *   Scope sfcc.preferences.rw: Preferences read/write scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Retrieves the Global Custom Preferences.

`GET /organizations/{organizationId}/global-custom-preferences`

Operation ID: `getGlobalCustomPreferenceList`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `maskPassword` (query, boolean) Whether to mask password or not.  
    Default: `false`. Example: `true`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 200.  
    Default: `200`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Retrieved Global Custom Preferences successfully.
    
    Media type: `application/json`. Schema: `CustomPreferenceList`.
    
    _Example: GlobalCustomPreferenceExample_
    
    ```
    {
      "limit": 10,
      "data": [
        {
          "groupId": "PreferenceGroup1",
          "id": "booleanValue",
          "value": true
        },
        {
          "groupId": "PreferenceGroup1",
          "id": "htmlValue",
          "value": {
            "markup": "<h1>HTML Value</h1>",
            "source": "<h1>HTML Value</h1>"
          }
        },
        {
          "groupId": "PreferenceGroup1",
          "id": "dateValue",
          "value": "2007-06-20T00:00:00.000Z"
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "integerValueValue",
          "value": 12345
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "stringValueList",
          "value": "s1"
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "imageValue",
          "value": {
            "abs_url": "https://localhost/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "dis_base_url": "https://image.demandware.com/dw/image/v2/zzzz_s02/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "path": "/img/value.jpg"
          }
        }
      ],
      "offset": 0,
      "total": 100
    }
    ```
    
*   **400** Returned if the query is ill-formed.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidAccessToken_
    
    ```
    {
      "title": "Invalid Access Token",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token",
      "detail": "The request is unauthorized, the access token is invalid.",
      "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp"
    }
    ```
    

### GET Retrieves the Custom Preferences for a specified siteId.

`GET /organizations/{organizationId}/site-custom-preferences`

Operation ID: `getSiteCustomPreferenceList`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `maskPassword` (query, boolean) Whether to mask password or not.  
    Default: `false`. Example: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 200.  
    Default: `200`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Retrieved Site Custom Preferences successfully.
    
    Media type: `application/json`. Schema: `CustomPreferenceList`.
    
    _Example: SiteCustomPreferenceExample_
    
    ```
    {
      "limit": 10,
      "data": [
        {
          "groupId": "PreferenceGroup1",
          "id": "booleanValue",
          "value": true
        },
        {
          "groupId": "PreferenceGroup1",
          "id": "htmlValue",
          "value": {
            "markup": "<h1>HTML Value</h1>",
            "source": "<h1>HTML Value</h1>"
          }
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "integerValueValue",
          "value": 12345
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "imageValue",
          "value": {
            "abs_url": "https://localhost/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "dis_base_url": "https://image.demandware.com/dw/image/v2/zzzz_s02/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "path": "/img/value.jpg"
          }
        }
      ],
      "offset": 0,
      "total": 100
    }
    ```
    
*   **400** Returned if the query is ill-formed.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InvalidAccessToken: same as GET /organizations/{organizationId}/global-custom-preferences 401 response._
    

### GET Read the custom preferences in a global preference group for a given instance type.

`GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType}`

Operation ID: `getGlobalPreferenceGroup`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

For the specified instance, read the custom preferences in the preference group at the global (organization) level. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.

**Note:** If instance type sandbox is used, the preference values of development instance type will be returned as fallback.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `expand` (query, array of string, style: form, explode: false) Expands the result document to include additional information. For global preference groups, the expansion "sites" retrieves the custom preferences for all the available sites.  
    Items: Allowed values: `sites`. Example: `sites`.

#### Responses

*   **200** Custom preferences retrieved successfully.
    
    Media type: `application/json`. Schema: `OrganizationPreferences`.
    
    _Example: GetGlobalPreferencesExample_ Global preferences with custom attributes.
    
    ```
    {
      "c_WapiStringAttr": "MyString",
      "c_WapiLocalizedStringAttr": "MyLocalizedString",
      "c_WapiSitespecificStringAttr": "MySiteSpecificString",
      "c_WapiSetOfStringAttr": [
        "value1",
        "value2"
      ],
      "c_WapiEnumOfStringAttr": "WapiEnumOfStringValue1",
      "c_WapiEnumOfStringMSAttr": [
        "WapiEnumOfStringMSValue1",
        "WapiEnumOfStringMSValue2"
      ]
    }
    ```
    
    _Example: GetGlobalPreferencesWithSitesExample_ Global preferences with site-specific expansions.
    
    ```
    {
      "c_WapiStringAttr": "MyString",
      "c_WapiLocalizedStringAttr": {
        "default": "MyLocalizedString",
        "de-DE": "MeineLokalisierteZeichenkette"
      },
      "c_WapiSitespecificStringAttr": "MySiteSpecificString",
      "c_WapiSetOfStringAttr": [
        "value1",
        "value2"
      ],
      "c_WapiEnumOfStringAttr": "WapiEnumOfStringValue1",
      "c_WapiEnumOfStringMSAttr": [
        "WapiEnumOfStringMSValue1",
        "WapiEnumOfStringMSValue2"
      ],
      "c_WapiBooleanAttr": true,
      "c_WapiIntAttr": 42,
      "sitePreferences": [
        {
          "site": {
            "id": "RefArch"
          },
          "c_WapiStringAttr": "SiteSpecificStringRefArch",
          "c_WapiLocalizedStringAttr": {
            "default": "SiteLocalizedString",
            "de-DE": "StandortLokalisierteZeichenkette"
          },
          "c_WapiSitespecificStringAttr": "SiteSpecificValue",
          "c_WapiSetOfStringAttr": [
            "siteValue1",
            "siteValue2"
          ],
          "c_WapiEnumOfStringAttr": "WapiEnumOfStringValue1",
          "c_WapiBooleanAttr": false,
          "c_WapiIntAttr": 10
        },
        {
          "site": {
            "id": "RefArchGlobal"
          },
          "c_WapiStringAttr": "AnotherSiteValue",
          "c_WapiLocalizedStringAttr": {
            "default": "AnotherSiteLocalizedString"
          },
          "c_WapiSitespecificStringAttr": "AnotherSiteSpecificValue",
          "c_WapiSetOfStringAttr": [
            "anotherValue1"
          ],
          "c_WapiBooleanAttr": true,
          "c_WapiIntAttr": 99
        }
      ]
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: IllegalEnumerationValue_
    
    ```
    {
      "title": "Illegal Enumeration Value",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/illegal-enumeration-value",
      "detail": "The value 'bad' for type 'InstanceType' is invalid.",
      "value": "bad"
    }
    ```
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomPreferenceGroupNotFound_
    
    ```
    {
      "title": "Custom Preference Group Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-preference-group-not-found",
      "detail": "No preference group with ID 'Bad' could be found.",
      "preferenceGroupId": "Bad"
    }
    ```
    

### PATCH Update the custom preferences in a global preference group for a given instance type.

`PATCH /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType}`

Operation ID: `updateGlobalPreferenceGroup`. Security: AmOAuth2 (sfcc.preferences.rw).

For the specified instance, update one or more custom preferences in the preference group at the global (organization) level.

**Note:** If instance type sandbox is used, the preference values of development instance type will be returned as fallback.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.

#### Request body (required)

The preferences to update. Custom preference attributes use the "c\_" prefix.

Media type: `application/json`. Schema: `OrganizationPreferences`.

_Example: UpdateGlobalPreferencesRequest_ Update global custom preferences.

```
{
  "c_WapiStringAttr": "UpdatedString",
  "c_WapiIntAttr": 42,
  "c_WapiBooleanAttr": true,
  "c_WapiSetOfStringAttr": [
    "newValue1",
    "newValue2"
  ]
}
```

#### Responses

*   **200** Custom preferences updated successfully.
    
    Media type: `application/json`. Schema: `OrganizationPreferences`.
    
    _Example: UpdateGlobalPreferencesExample_ Updated global preferences response.
    
    ```
    {
      "c_WapiStringAttr": "UpdatedString",
      "c_WapiLocalizedStringAttr": "UpdatedLocalizedString",
      "c_WapiSetOfStringAttr": [
        "newValue1",
        "newValue2"
      ]
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### GET Read the custom preferences in a site preference group for a given instance type.

`GET /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}`

Operation ID: `getSitePreferenceGroup`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Custom site preferences retrieved successfully.
    
    Media type: `application/json`. Schema: `SitePreferences`.
    
    _Example: GetSitePreferencesExample_ Site preferences with custom attributes.
    
    ```
    {
      "site": {
        "id": "RefArch"
      },
      "c_WapiStringAttr": "MyString",
      "c_WapiLocalizedStringAttr": "MyLocalizedString",
      "c_WapiPasswordAttr": "************"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### PATCH Update the custom preferences in a site preference group for a given instance type.

`PATCH /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}`

Operation ID: `updateSitePreferenceGroup`. Security: AmOAuth2 (sfcc.preferences.rw).

For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "\*\*\*\*\*\*\*\*\*\*\*\*" since it is a reserved value.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

The site preferences to update. Custom preference attributes use the "c\_" prefix.

Media type: `application/json`. Schema: `SitePreferences`.

_Example: UpdateSitePreferencesRequest_ Update site custom preferences.

```
{
  "c_WapiStringAttr": "UpdatedString",
  "c_WapiLocalizedStringAttr": {
    "default": "UpdatedLocalizedString",
    "de-DE": "AktualisierteLokalisierteZeichenkette"
  },
  "c_WapiIntAttr": 42,
  "c_WapiBooleanAttr": true,
  "c_WapiSetOfStringAttr": [
    "newValue1",
    "newValue2"
  ]
}
```

#### Responses

*   **200** Custom site preferences updated successfully.
    
    Media type: `application/json`. Schema: `SitePreferences`.
    
    _Example: UpdateSitePreferencesExample_ Updated site preferences response.
    
    ```
    {
      "site": {
        "id": "RefArch"
      },
      "c_WapiStringAttr": "UpdatedString",
      "c_WapiLocalizedStringAttr": "UpdatedLocalizedString"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### POST Search preferences across sites in a preference group for a given instance type.

`POST /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preference-search`

Operation ID: `searchSitePreferences`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

Search preferences across sites in the specified preference group and instance. The query attribute specifies a complex query that can be used to narrow down the search.

The following is a list of searchable fields:

| Field | Type |
| --- | --- |
| id | String |
| display\_name | Localized String |
| description | Localized String |
| value\_type | Enum (see below) |

Allowed value\_type values: string, int, double, text, html, date, image, boolean, money, quantity, datetime, email, password, set\_of\_string, set\_of\_int, set\_of\_double, enum\_of\_string, enum\_of\_int.

**Note:** value\_type can only be joined with other attributes using a conjunction (AND). Only searchable attributes can be used in sorting.

**Note:** If instance type sandbox is used, the preference values of development instance type will be returned as fallback.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `expand` (query, array of string, style: form, explode: false) Expands the result document to include additional information. For preference search, the expansion "value" retrieves the value definitions of the attribute definition.  
    Items: Allowed values: `value`. Example: `value`.

#### Request body (required)

The search request document.

Media type: `application/json`. Schema: `SearchRequest`.

_Example: SearchSitePreferencesRequest_ Search preferences by ID and value type.

```
{
  "query": {
    "boolQuery": {
      "must": [
        {
          "textQuery": {
            "fields": [
              "id"
            ],
            "searchPhrase": "WapiString"
          }
        },
        {
          "termQuery": {
            "fields": [
              "valueType"
            ],
            "operator": "is",
            "values": [
              "string"
            ]
          }
        }
      ]
    }
  },
  "sorts": [
    {
      "field": "id",
      "sortOrder": "asc"
    }
  ],
  "limit": 25,
  "offset": 0
}
```

#### Responses

*   **200** Preference search executed successfully.
    
    Media type: `application/json`. Schema: `PreferenceValueSearchResult`.
    
    _Example: PreferenceSearchExample_ Search result for preferences across sites.
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "hits": [
        {
          "id": "WapiStringAttr",
          "displayName": {
            "default": "String Attribute"
          },
          "description": {
            "default": "String Attribute"
          },
          "valueType": "string",
          "attributeDefinition": {
            "id": "WapiStringAttr",
            "displayName": {
              "default": "String Attribute"
            },
            "description": {
              "default": "String Attribute"
            },
            "valueType": "string"
          },
          "siteValues": {
            "RefArch": "MyString-RefArch-Staging",
            "RefArchGlobal": "MyString-RefArchGlobal-Staging"
          }
        },
        {
          "id": "WapiLocalizedStringAttr",
          "displayName": {
            "default": "Localized String Attribute"
          },
          "description": {
            "default": "Localized String Attribute"
          },
          "valueType": "string",
          "attributeDefinition": {
            "id": "WapiLocalizedStringAttr",
            "displayName": {
              "default": "Localized String Attribute"
            },
            "description": {
              "default": "Localized String Attribute"
            },
            "valueType": "string"
          },
          "siteValues": {
            "RefArch": "MyLocalizedString-RefArch-Staging"
          }
        }
      ],
      "query": {
        "matchAllQuery": {}
      },
      "sorts": [
        {
          "field": "id",
          "sortOrder": "asc"
        }
      ]
    }
    ```
    
    _Example: PreferenceSearchWithExpandValueExample_ Search result with expanded value definitions.
    
    ```
    {
      "limit": 1,
      "offset": 0,
      "total": 1,
      "hits": [
        {
          "id": "WapiEnumOfStringAttr",
          "displayName": {
            "default": "Enum Of String Attribute"
          },
          "description": {
            "default": "Enum Of String Attribute"
          },
          "valueType": "enum_of_string",
          "attributeDefinition": {
            "id": "WapiEnumOfStringAttr",
            "displayName": {
              "default": "Enum Of String Attribute"
            },
            "description": {
              "default": "Enum Of String Attribute"
            },
            "valueType": "enum_of_string",
            "valueDefinitions": [
              {
                "id": "WapiEnumOfStringValue1",
                "displayValue": {
                  "default": "Value 1"
                },
                "position": 0,
                "value": "WapiEnumOfStringValue1"
              },
              {
                "id": "WapiEnumOfStringValue2",
                "displayValue": {
                  "default": "Value 2"
                },
                "position": 1,
                "value": "WapiEnumOfStringValue2"
              }
            ]
          },
          "siteValues": {
            "RefArch": "WapiEnumOfStringValue1"
          }
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id"
          ],
          "searchPhrase": "WapiEnumOfStringAttr"
        }
      }
    }
    ```
    
*   **400** The request is malformed. This can be caused by an invalid instance type, an ill-formed search query, or attempting to sort by a non-sortable field.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
    _Example: FieldNotSortable_
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'attributeDefinition' can't be used to sort the results.",
      "field": "attributeDefinition"
    }
    ```
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### GET Read a single preference value across sites in a preference group for a given instance type.

`GET /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId}`

Operation ID: `getSitePreference`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

Read a specific preference value identified by its ID within the given preference group and instance type. Returns the preference value for all sites.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `preferenceId` (path, string, required) The preference attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringAttr`.
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.

#### Responses

*   **200** Preference value retrieved successfully.
    
    Media type: `application/json`. Schema: `PreferenceValue`.
    
    _Example: GetPreferenceValueExample_ A single preference value.
    
    ```
    {
      "id": "WapiStringAttr",
      "displayName": {
        "default": "String Attribute",
        "de-DE": "Zeichenkettenattribut"
      },
      "description": {
        "default": "A custom string preference attribute",
        "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
      },
      "valueType": "string",
      "siteValues": {
        "RefArch": "MyString-RefArch-Sandbox",
        "RefArchGlobal": "MyString-RefArchGlobal-Sandbox"
      },
      "attributeDefinition": {
        "id": "WapiStringAttr",
        "effectiveId": "c_WapiStringAttr",
        "displayName": {
          "default": "String Attribute",
          "de-DE": "Zeichenkettenattribut"
        },
        "description": {
          "default": "A custom string preference attribute",
          "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
        },
        "valueType": "string",
        "key": false,
        "mandatory": false,
        "localizable": true,
        "siteSpecific": true,
        "searchable": false,
        "queryable": true,
        "visible": true,
        "system": false,
        "unit": {
          "default": ""
        },
        "requiresEncoding": false,
        "multiValueType": false,
        "setValueType": false,
        "externallyManaged": false,
        "externallyDefined": false,
        "orderRequired": false,
        "readOnly": false,
        "regularExpression": "^[a-zA-Z0-9]*$",
        "fieldLength": 256,
        "fieldHeight": 1,
        "minLength": 1,
        "minValue": 0,
        "maxValue": 100,
        "scale": 2,
        "defaultValue": {
          "id": "defaultVal",
          "value": "defaultString",
          "position": 1,
          "displayValue": {
            "default": "Default Value"
          },
          "description": {
            "default": "The default value"
          }
        },
        "valueDefinitions": []
      }
    }
    ```
    
    _Example: GetPreferenceValueMultiSiteExample_ A single preference value with multiple site values.
    
    ```
    {
      "id": "WapiSetOfStringAttr",
      "displayName": {
        "default": "Set Of String Attribute"
      },
      "description": {
        "default": "Set Of String Attribute"
      },
      "siteValues": {
        "RefArch": [
          "value1-RefArch-Sandbox"
        ],
        "RefArchGlobal": [
          "value1-RefArchGlobal-Sandbox"
        ]
      },
      "valueType": "set_of_string"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group or preference was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    
    _Example: PreferenceNotFound_
    
    ```
    {
      "title": "Preference Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/preference-not-found",
      "detail": "No preference with ID 'noExists' could be found.",
      "preferenceId": "noExists"
    }
    ```
    

### PATCH Update a single preference value across sites in a preference group for a given instance type.

`PATCH /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId}`

Operation ID: `updateSitePreference`. Security: AmOAuth2 (sfcc.preferences.rw).

Update a specific preference value identified by its ID within the given preference group and instance type. The siteValues map specifies the new values per site.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `preferenceId` (path, string, required) The preference attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringAttr`.
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.

#### Request body (required)

The preference value to update with site-specific values.

Media type: `application/json`. Schema: `PreferenceValue`.

_Example: UpdateSitePreferenceValueRequest_ Update a preference value for multiple sites.

```
{
  "id": "WapiStringAttr",
  "valueType": "string",
  "displayName": {
    "default": "My String Attribute",
    "de-DE": "Mein Zeichenkettenattribut"
  },
  "description": {
    "default": "A custom string preference attribute",
    "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
  },
  "siteValues": {
    "RefArch": "new value for RefArch",
    "RefArchGlobal": "new value for RefArchGlobal"
  },
  "attributeDefinition": {
    "id": "WapiStringAttr",
    "displayName": {
      "default": "My String Attribute",
      "de-DE": "Mein Zeichenkettenattribut"
    },
    "description": {
      "default": "A custom string preference attribute",
      "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
    },
    "valueType": "string",
    "key": false,
    "mandatory": false,
    "localizable": true,
    "siteSpecific": true,
    "searchable": false,
    "visible": true,
    "unit": {
      "default": "kg"
    },
    "multiValueType": false,
    "externallyManaged": false,
    "externallyDefined": false,
    "orderRequired": false
  }
}
```

#### Responses

*   **200** Preference value updated successfully.
    
    Media type: `application/json`. Schema: `PreferenceValue`.
    
    _Example: UpdatePreferenceValueExample_ Updated preference value response.
    
    ```
    {
      "id": "WapiLocalizedStringAttr",
      "displayName": {
        "default": "Localized String Attribute"
      },
      "description": {
        "default": "Localized String Attribute"
      },
      "siteValues": {
        "RefArch": "value for RefArch",
        "RefArchGlobal": "value for RefArchGlobal"
      },
      "valueType": "string"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group or preference was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    
    _Example PreferenceNotFound: same as GET /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### CustomPreferenceList

Document representing a Custom Preference result.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of CustomPreference_, required) The list of custom preferences in the search result.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### OrganizationPreferences

Represents custom preferences at the global (organization) level within a preference group. Custom preference attributes are returned with the "c\_" prefix.

*   `sitePreferences` (_array of SitePreferences_) The list of site-specific preferences, returned when expand=sites.

### SitePreferences

Represents custom preferences at the site level within a preference group. Custom preference attributes are returned with the "c\_" prefix.

*   `site` (_Site_)

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PreferenceValueSearchResult

Document representing a preference value search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of PreferenceValue_) The sorted array of search hits. Can be empty.

### PreferenceValue

Represents a single preference value with its attribute definition and site-specific values.

*   `id` (_string_, required) The preference attribute ID  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringAttr`.
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Preference Description`.
    
    _Example_
    
    ```
    {
      "default": "Preference Description",
      "en-US": "Preference Description",
      "de-DE": "Einstellungsbeschreibung",
      "ja-JP": "設定の説明"
    }
    ```
    
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Preference Display Name`.
    
    _Example_
    
    ```
    {
      "default": "Preference Display Name",
      "en-US": "Preference Display Name",
      "de-DE": "Anzeigename der Einstellung",
      "ja-JP": "設定の表示名"
    }
    ```
    
*   `attributeDefinition` (_ObjectAttributeDefinition_)
*   `siteValues` (_object_) A mapping of site IDs to their preference values.
*   `valueType` (_ValueType_)

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### CustomPreference

Preference object

*   `groupId` (_string_, required) The ID of the preference group.
*   `id` (_string_, required) The Preference Id.
*   `value` (_any_, required) The value for the Preference Id.

### Site

*   `id` (_object_, required)
    
    ID
    
    The ID of the site.
    
    Includes all fields of `SiteId`.
    
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Site Display Name`.
    
    _Example_
    
    ```
    {
      "default": "Site Display Name",
      "en-US": "Site Display Name",
      "de-DE": "Site-Anzeigename",
      "ja-JP": "サイト表示名"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Site Description`.
    
    _Example_
    
    ```
    {
      "default": "Site Description",
      "en-US": "Site Description",
      "de-DE": "Site-Beschreibung",
      "ja-JP": "サイトの説明"
    }
    ```
    
*   `customerListLink` (_object_) The link to the customer list
    
    Includes all fields of `CustomerListLink`.
    
*   `inDeletion` (_boolean_) Specifies whether the site status is in deletion (true) or not (false)  
    Example: `false`.
*   `storefrontStatus` (_string_) Status of the storefront  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`. Example: `online`.
*   `siteCatalogId` (_string_) The catalog bound to the given site.  
    Minimum length: 1. Maximum length: 256. Example: `storefront-catalog-m-en`.
*   `cartridges` (_string_, read-only) The effective cartridge path for the site, delimited by ':'. Includes both system cartridges and the site's custom cartridges (see `customCartridges`).  
    Maximum length: 4000. Example: `app_storefront_base:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core`.
*   `customCartridges` (_string_) The custom cartridge path assigned to the site, delimited by ':'. Does not include system cartridges. This is the subset of `cartridges` that can be configured for the site.  
    Maximum length: 4000. Example: `app_storefront_base`.
*   `creationDate` (_string (date-time)_) The timestamp when the site was created.  
    Example: `2024-01-15T10:00:00.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the site was last modified.  
    Example: `2024-10-14T15:30:00.000Z`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### ObjectAttributeDefinition

Document representing an attribute definition

*   `id` (_string_, required) The user supplied ID of the attribute  
    Minimum length: 1. Maximum length: 256. Example: `color`.
*   `effectiveId` (_string_, read-only) The effective ID, which is c\_id if the attribute is custom, and just the id otherwise  
    Maximum length: 256. Example: `c_color`.
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Product",
      "de": "Produkt",
      "en": "Product"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `key` (_boolean_) Flag indicating if this is a key attribute  
    Example: `false`.
*   `mandatory` (_boolean_) Flag indicating if a value is mandatory for the attribute  
    Example: `false`.
*   `localizable` (_boolean_) Flag indicating if this attribute can be localized  
    Example: `false`.
*   `siteSpecific` (_boolean_) Flag indicating if this attribute is site-specific  
    Example: `false`.
*   `searchable` (_boolean_) Flag indicating if this attribute is searchable  
    Example: `true`.
*   `queryable` (_boolean_, read-only) Returns true if the attribute definition is explicitly marked queryable or if the attribute value type belongs to a queryable type. Computed and read-only.  
    Example: `true`.
*   `valueType` (_ValueType_)
*   `visible` (_boolean_) Flag indicating if this attribute is visible  
    Example: `true`.
*   `system` (_boolean_) Flag indicating if this attribute is a system attribute  
    Example: `false`.
*   `unit` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "General unit",
      "de": "Allgemeine Einheit",
      "en": "General unit"
    }
    ```
    
*   `requiresEncoding` (_boolean_, read-only) Flag indicating if this attribute can be encoded using the encoding='off' flag in ISML templates  
    Example: `false`.
*   `multiValueType` (_boolean_) True if the attribute can have multiple values. Applicable to set\_of\_\* and enum\_of\_\* types.  
    Example: `false`.
*   `setValueType` (_boolean_, read-only) Flag indicating if this attribute is of type 'Set of'  
    Example: `false`.
*   `externallyManaged` (_boolean_) Flag indicating if this attribute is externally managed  
    Example: `false`.
*   `externallyDefined` (_boolean_) Flag indicating if this attribute is externally defined  
    Example: `false`.
*   `orderRequired` (_boolean_) Flag indicating if this attribute is required for order of the attribute model's product  
    Example: `false`.
*   `regularExpression` (_string_, read-only) A regular expression that defines the legal values for this attribute  
    Maximum length: 4000. Example: `^[a-zA-Z]+$`.
*   `fieldLength` (_integer (int32)_, read-only) The length of the field for this attribute in the editor  
    Example: `50`.
*   `fieldHeight` (_integer (int32)_, read-only) The height of the field for this attribute in the editor  
    Example: `1`.
*   `minLength` (_integer (int32)_, read-only) The minimum length of the field for this attribute  
    Example: `1`.
*   `readOnly` (_boolean_, read-only) Flag indicating if this attribute is read-only  
    Example: `false`.
*   `minValue` (_number (double)_, read-only) The minimum possible value for this attribute  
    Example: `0`.
*   `maxValue` (_number (double)_, read-only) The maximum possible value for this attribute  
    Example: `100`.
*   `scale` (_integer (int32)_, read-only) The minimum number of fraction digits for a value of this attribute  
    Example: `2`.
*   `defaultValue` (_object_) The default value of this attribute. It can be updated, but not created.
    
    Includes all fields of `ObjectAttributeValueDefinition`.
    
*   `valueDefinitions` (_array of ObjectAttributeValueDefinition_, read-only) A set of values that are possible for this attribute
*   `creationDate` (_string (date-time)_, read-only) The date/time when the attribute definition was created  
    Example: `2024-01-15T10:30:00Z`.
*   `lastModified` (_string (date-time)_, read-only) The date/time when the attribute definition was last modified  
    Example: `2024-01-15T11:00:00Z`.

### ValueType

The type of an attribute value

Type: `string`.

Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `image`, `boolean`, `money`, `quantity`, `datetime`, `email`, `password`, `set_of_string`, `set_of_int`, `set_of_double`, `enum_of_string`, `enum_of_int`. Example: `string`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CustomerListLink

Document representing a link to a customer list.

*   `customerListId` (_string_) The customer list identifier  
    Minimum length: 1. Maximum length: 256. Example: `customer-list-1`.
*   `title` (_string_) The title of the customer list link  
    Maximum length: 256. Example: `Default Customer List`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### ObjectAttributeValueDefinition

An attribute definition value

*   `id` (_string_, read-only) The ID of the attribute value  
    Maximum length: 256. Example: `value-1`.
*   `value` (_string_, read-only) The value of the attribute  
    Maximum length: 4000. Example: `1`.
*   `displayValue` (_object_, read-only) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "One",
      "de": "Eins",
      "en": "One"
    }
    ```
    
*   `description` (_object_, read-only) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `position` (_number (double)_, read-only) The position of the attribute value within the set of attribute values  
    Example: `1`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=8f6c19f4614a496cfddc5b3794da230a02875f655d233fed22b3c1c9310f0228 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-prepare-einstein-custom-comps.md -->

# Prepare Commerce Einstein to Use Custom Components

Before creating custom Commerce Einstein Recommendations components, deploy Commerce Einstein and enable activity tracking.

1.  [Deploy Commerce Einstein](https://help.salesforce.com/s/articleView?id=commerce.comm_einstein_deploy.htm).

2.  Enable [Activity Tracking](https://help.salesforce.com/s/articleView?id=commerce.comm_einstein_activity_tracking_top.htm).

3.  [Commerce SFDX Environment Setup](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_set_up_dev_env.htm).

**note:** Make sure to install all recommended software and plug-ins.

**See Also**

- [Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_apis.htm)
- [Create a Custom Recommendations Component for B2C Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_create_b2c_cust_ein_reco_comp.htm)
- [Create a Custom Recommendations Component for B2B Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_create_b2b_cust_ein_reco_comp.htm)
- [Experience Cloud Cookies](https://help.salesforce.com/s/articleView?id=experience.networks_cookies.htm)
- [Deploy Commerce Einstein](https://help.salesforce.com/s/articleView?id=commerce.comm_einstein_deploy.htm)
- [Activity Tracking](https://help.salesforce.com/s/articleView?id=commerce.comm_einstein_activity_tracking_top.htm)

<!-- document id=b1d478d4f3bfe541df30f46de4d9f9c27fa8b8097db9e0c36663fc5d9b237224 url=/developer/current/en-us/commerce-cloud/lwr-migration/guides/prepare-for-migration.md -->

# Prepare for Store Migration

Before creating your B2B Commerce on LWR storefront, ease the transition by refactoring existing components. Apply these guidelines to Aura components in B2B stores.

## Invest in LWC

Before you begin, assess the component makeup of your B2B Commerce Aura storefront. From Setup, in the Quick Find box, enter **Lightning Components**, and then select **Lightning Components**. From this page, view your Lightning web components and Aura components.

Identify Aura components and make plans to replace them with Lightning web components where possible. Lightning web components function in Aura and LWR, often with no alterations required. To map base components from Aura to Lightning web components, see [Base Components: Aura Vs Lightning Web Components](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.migrate_map_aura_lwc_components). For B2B store components, see [LWR and Aura Store Templates](https://help.salesforce.com/s/articleView?id=commerce.comm_lwr_aura_comps.htm)(can be outdated or unavailable during release preview).

From Experience Builder, copy Aura components to a new workspace and then replace them with their Lightning web component equivalents. If an Aura component can’t be replaced, limit it to a thin, outer wrapper layer. In a tree of nested components, an Aura component can contain Lightning web components. Lightning web components can’t contain nested Aura components. This cross-compatibility means that you can migrate child components in a complex Aura component to LWC without replacing the parent Aura component. To complete your store’s migration to LWR, all Aura components must be replaced eventually.

For more information on how to replace Aura components with Lightning web components, see the [Migrate from Aura to Lightning Web Components](https://trailhead.salesforce.com/en/content/learn/trails/migrate-from-aura-to-lightning-web-components) trail.

## Consolidate Data Operations in Top-Level Components

Because of differences in how Aura and Lightning web components access Salesforce data, migration involves modifications to data layers. If you consolidate data operations to outermost components, you can later replace or alter the data layer in one central component rather than throughout a component tree. This structure also makes the lower-level nested components more portable and reusable, giving you more flexibility after migration to LWR.

When possible, use a Lightning web component for these top-level data operations. But this step still makes for a smoother migration if you must use an Aura component. As mentioned, you can only use top-level Lightning web components if the rest of the nested component tree also uses LWC.

To check your store’s component trees, from Experience Builder, open the page that you want to edit, and then click the Page Structure icon.

![A nested Commerce Header component in Experience Builder.](https://developer.salesforce.com/docs/media/lwr-migration/nested_comp.png)

## Restructure Component Events

The LWC and Aura Components programming models use events-driven programming to communicate data between components. In the Aura Components programming model, events are declared by the aura:event tag in an .evt resource. By contrast, Lightning web components use DOM Events, a collection of APIs and objects available in every browser. In nested components, Lightning web components can propagate information up the component hierarchy using events and event listeners.

If your store uses events in Aura components, restructure these events to function in Lightning web components. For more information, see [Migrate Events](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.migrate_events).

## Implement Wire Adapters

To access Salesforce data, Lightning web components use a reactive wire service built on Lightning Data Service. When centralizing your data operations in outermost components, consider implementing this wire service. Avoid using Aura components and actions such as force:recordData to retrieve data or interact with a storefront.

Lightning web components use @wire in their JavaScript class to read data from one of the wire adapters in the lighning/ui\*Api namespace. The wire service provides an easy, low-code way to work with data that simplifies your store’s components. For example, see the adapters available in the Commerce namespace in [Custom Component APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_display_lwc_apis.htm).

If an Aura component uses custom Apex classes that you want to preserve, you can also import methods from these Apex classes into Lightning web components. For more information, see [Use the Wire Service to Get Data](https://developer.salesforce.com/docs/component-library/documentation/en/lwc/lwc.data_wire_service).

<!-- document id=94c8cea042a2aad25cb40d3fdfb2c5e85a2b527a9d09deb9c660482f3f815ab3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-present-content-section.md -->

# Present Content and Merchandise

Build the content and merchandising layer of your Storefront Next storefront. This section covers Page Designer integration for visual content management, cartridge deployment, search engine optimization, AI-driven answer engine and generative engine optimization, UI styling, and image and static asset handling.

In this section:

- [Page Designer Integration with Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-page-designer.md)
- [Deploy the Storefront Next Cartridge for Page Designer](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pd-deploy-cartridge.md)
- [SEO and Metadata](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-seo-metadata.md)
- [AEO and GEO](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-aeo-geo.md)
- [UI Styling](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ui-styling.md)
- [Images](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-images.md)
- [Static Assets](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-static-assets.md)

<!-- document id=b097ed3228dbda537306d05b9fccd355871b3bc6555cf8f773ae369307cf26b9 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-prevent-concurrency.md -->

# Prevent Concurrency Conflicts

Checkout orchestrates multiple background operations (called calculators) on your cart. These operations modify the Cart data model—a set of related objects including WebCart, CartCheckoutSession, CartItem, and CartDeliveryGroup.

Understand concurrency to avoid errors. When multiple processes modify the Cart data model simultaneously, the result can be data inconsistencies or failed transactions.

The Cart data model uses optimistic concurrency control. Each cart has a version number that increments with every update. When an operation saves changes, the system compares the current version with the version at retrieval time. If they don't match, the operation fails—preventing stale data from overwriting recent updates.

See [B2B Commerce Checkout Calculators](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-calculators.md) for how calculators work and [Cart Data Model](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-cart.html) for complete entity details.

<!-- document id=1e64c506853dfe8f6ec43797e36a06afc23df4e2d2dd7e0361e177e76553a726 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/storefront-preview-bm.md -->

# Preview Your Storefront in Business Manager

Preview you PWA Kit storefront in Business Manager to verify how it looks based on shopper context including customer groups, date and time, source code triggers, and qualifiers. Use it to test changes to products, pricing, and marketing strategies in a staging environment before deploying to production, ensuring your site displays correctly for specific scenarios like upcoming sales or seasonal campaigns.

## Prerequisites

### PWA Kit Version

A recent PWA Kit version. We recommend using [PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) version 3.18 or later.

### Prerequisite Setup

- Link your PWA Kit storefront to B2C Commerce in Business Manager. The storefront link makes the MRT environment and storefront data available so that Storefront Preview can identify which environment to associate with the storefront and site. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration > Sites > Storefronts**. Click **Add Existing**, and then select **Link a Storefront from Managed Runtime**.
- The Storefront Preview feature requires the same headless design that Page Designer uses even if you aren't using Page Designer. Perform these steps from [Migration Steps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.html#migration-steps):
  - [Step 1: Install Required Dependency](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.html#step-1-install-required-dependency)
  - [Step 6: Set Up PageDesignerProvider in App Component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/page-designer.html#step-6-set-up-pagedesignerprovider-in-app-component)
- [Enable shopper context](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-personalized.html#enable-shopper-context) in Business Manager.
- Set up your site based on the functionality you want to validate in Storefront Preview. Examples:
  - Set up [custom qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_using_session_custom_attributes.htm&type=5) and [customer group IDs](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_customer_group.htm&type=5) using customer groups in Business Manager to apply rules for personalized pricing, products, or promotions.
  - To see a personalized shopper experience, set up source code that calls the [Shopper Context endpoints](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html). This is required because Storefront Preview uses context information for personalization.
  - Set up the pricing that you want to offer on a particular date. That way your specified pricing appears when you select that date in Storefront Preview.
- Configure your browser to allow third-party cookies on `https://runtime.commercecloud.com`.

### Supported Browsers

You can use Storefront Preview with the latest versions of Chrome or Safari. Your browser **must** allow `https://runtime.commercecloud.com` to access third-party cookies. Storefront Preview **won't work** if you don't enable third-party cookies.

**tip:** Learn how to enable third-party cookies for [Chrome](https://support.google.com/accounts/answer/61416?hl=en&co=GENIE.Platform%3DDesktop) and [Safari](https://support.apple.com/guide/safari/enable-cookies-ibrw850f6c51/mac).

## Considerations

- Data and experiences shown in Storefront Preview don't necessarily reflect the shopper experience. Shopper personalization requires the use of the Shopper Context API within your PWA Kit project. Learn more about [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html).
- Storefront Preview works on PWA Kit pages and not on Storefront Reference Architecture (SFRA) pages. However, you can use [Storefront Toolkit Site Preview Tool in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_using_the_site_preview_tool.htm) to preview SFRA pages.

## Preview Your Storefront

To use Storefront Preview:

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Merchant Tools**, select the site associated with your storefront, and then click **Preview**.

   A new tab opens showing the storefront, with the Storefront Preview form on the left sidebar.

2. To view the storefront based on various settings, select preview settings by clicking the preview button on the banner of the preview site.

   ![Preview settings on the preview site](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/preview-settings.png '{"class": "image-md"}')

   Enter preview settings for the site. All the preview settings are optional.

   a. To view the site for a specific customer group, select a customer group from the picklist.

   b. To see how the site looks on a specific date and time, select the effective **date** and **time** using the date picker in `On Date`. The date and time displayed is based on your computer's time zone and then converted to UTC time before sending the request that sets the context. If you don't specify a date and time, the preview reflects the current date and time.

   c. To trigger the promotion or campaign assignment and price books, which are assigned to a source code group, select the triggering source code from the picklist.

   d. To view the personalized prices, products, or promotions set up in Business Manager, enter the custom qualifiers as key and value pairs. The custom qualifier keys must be unique. You can define up to 20 custom qualifiers.

3. Click **Apply**.

   You can now view with the storefront using the context you want to preview. Interact with the storefront to verify the applied context. For example, select a particular size for a merchandise to see any available discounted price.

## Debug Storefront Preview

If you experience any issues with Storefront Preview, you can enable Storefront Preview logs in your MRT environment.
This prints extra logs when you click the **Preview** button to help you debug the issues.

To enable Storefront Preview logs, add the MRT [environment variable](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#environment-variables) `STOREFRONT_PREVIEW_DEBUG=1` to your MRT environment.

You can use [MRT tail logs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#tail-logs-on-managed-runtime) to read the Storefront Preview logs.

<!-- document id=28121c9c0463ace7bff56688b11fcf0501091e2c4b564ba0f59fdb337601987e url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-storefront-preview.md -->

# Preview Your Storefront in Business Manager with Shopper Context

Preview your storefront to verify how it looks based on shopper context including customer groups, date and time, source code triggers, and qualifiers. Use it to test changes to products, pricing, and marketing strategies in a staging environment before deploying to production so that your site displays correctly for specific scenarios like upcoming sales or seasonal campaigns.

## Prerequisites

- Create a storefront in Business Manager. See [Quick Start: Create Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-choice.md). For existing storefronts created outside of Business Manager via the CLI or the MRT API, link them to Business Manager. See [Link an Existing Storefront to B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-link-storefront.md).
- Make sure that shopper context is enabled. For storefronts created in Business Manager, shopper context is enabled. For other storefronts, enable shopper context. In Business Manager, select **Administration > Global Preferences > Feature Switches**, and select **Enable Shopper Context**. For more information, see [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md).
- Enable shopper context qualifiers in the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=type%3AShopperContext): `effectiveDateTime`, `customerGroupIds`, `clientIp`, and `geoLocation` qualifiers. See [Qualifier Support](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md#qualifier-support) in the Shopper Context documentation.
- Set up your site based on the functionality you want to validate in Storefront Preview. Examples:
  - Set up [custom qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_using_session_custom_attributes.htm&type=5) and [customer group IDs](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_customer_group.htm&type=5) using customer groups in Business Manager to apply rules for personalized pricing, products, or promotions.
  - To see a personalized shopper experience, set up source code that calls the [Shopper Context endpoints](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html). This is required because Storefront Preview uses context information for personalization.
  - Set up the pricing that you want to offer on a particular date. That way your specified pricing appears when you select that date in Storefront Preview. See [Personalized Promotions, Shipping, and Payment Methods](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-personalized.html).

## Considerations

- Data and experiences shown in Storefront Preview don't necessarily reflect the shopper experience. Shopper personalization uses the shopper context integration in Storefront Next, which wraps the Shopper Context API. Learn more about [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md).
- Storefront Preview loads your storefront inside a Business Manager iframe. For Storefront Preview to work, the `frame-ancestors` Content Security Policy directive must allow both `'self'` and your Business Manager hostname (for example, `https://your-instance.commercecloud.salesforce.com`). The default value of `'self'` isn't sufficient. Extend the directive in `config.server.ts`. See [Security Response Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-security-headers.md).
- Previewing a local development environment isn't supported. To use Storefront Preview, deploy your storefront to a Managed Runtime environment.

## Preview Your Storefront

To use Storefront Preview:

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Merchant Tools**, select the site associated with your storefront, and then click **Preview**.

   The storefront page opens in a new tab.

2. To view the storefront based on various settings, click the preview button on the banner of the preview site.

   ![Preview settings on the preview site](https://developer.salesforce.com/docs/media/sfnext/sfnext-preview-settings.png '{"class": "image-md"}')

   Enter preview settings for the site. All the preview settings are optional.

   a. To view the site for a specific customer group, select a customer group from the picklist.

   b. To see how the site looks on a specific date and time, select the effective **date** and **time** using the date picker in `On Date`. The date and time displayed is based on your computer's time zone and then converted to UTC time before sending the request that sets the context. If you don't specify a date and time, the preview reflects the current date and time.

   c. To trigger the promotion or campaign assignment and price books, which are assigned to a source code group, select the triggering source code from the picklist.

   d. To view the personalized prices, products, or promotions set up in Business Manager, enter the custom qualifiers as key and value pairs. The custom qualifier keys must be unique. You can define up to 20 custom qualifiers.

3. Click **Apply**.

   You can now view the storefront using the context you want to preview. Interact with the storefront to verify the applied context. For example, select a particular size for a product to see any available discounted price.

<!-- document id=b89f61339271182498f595a41992849b3aaf880b730fc8f8b5eced857c4e68cf url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-test-debug-section.md -->

# Preview, Test, and Debug Storefront Next

Use Storybook to view, test, and document React UI components. Also, run automated tests with the end-to-end test suite built with CodeceptJS and Playwright. Debug your storefront by checking out the debugging and troubleshooting tips.

In this section:

- [Preview Your Storefront in Business Manager with Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storefront-preview.md)
- [Build and Test Components with Storybook](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storybook.md)
- [End-to-End Testing with CodeceptJS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-e2e-testing.md)
- [Debug Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-debug.md)

<!-- document id=6626aea206356f8c75a431ca7be7bc1d52ea7aa3c6a8e4c7e14f16174669e522 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-price-book-limits.md -->

# Price Book Data Limits

| Object                            | Limit B2B Except Where Indicated | Store or Org | Notes                                                                                                                                                                                                                             |
| --------------------------------- | -------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Price Books                       | 300,000<sup>\*</sup>             | Org          | Not enforced for Agentforce Sales                                                                                                                                                                                                      |
| Price Book Entries                | 50 million<sup>\*</sup>          | Org          | Not enforced for Agentforce Sales                                                                                                                                                                                                      |
| Buyer Group Price books           | 100,000<sup>\*</sup> B2B Only    | Org          | Total number of buyer group price books. There is a limit to the number of price books you can assign to a buyer group.                                                                                                           |
| Price Book Assigned to a Store    | 5 per Store. B2B Only            | Store        | Applies to the store. You can assign up to 25 price books to a buyer group and assign the buyer group to a store.                                                                                                                 |
| Price Book Entries per Price Book | B2B: 350,000<sup>\*</sup>        | N/A          | Because this is a price book limit, you can assign it at the store, buyer group, or org level.                                                                                                                                    |
| Price Books per Buyer Group       | B2B: 50<sup>\*</sup>             |              | The number of price books that you can associate with a buyer group.                                                                                                                                                              |
| Buyer Groups per Price Book       | 100<sup>\*</sup>                 | N/A          | The number of buyer groups that you can associate with a price book.                                                                                                                                                              |
| Price Books per Pricing Call      | 25                               | N/A          | The number of valid price books the system evaluates for a single pricing call. Price books above the 25 limit are not included in the price evaluation. A valid price book is an active price that matches the buyer's currency. |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce customer support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

Salesforce recommends you manage pricing data within the scope of the established limits. To optimize a pricing strategy that works within the pricing limits, plan and adapt your pricing strategy within the limits.

Familiarize yourself with the Salesforce B2B limits on pricing objects. To organize and structure your pricing data, and to ensure that you make the most of the available limits, utilize pricing data relationships and dependencies to design an efficient pricing model that makes the most of the available limits.

Regularly audit and clean up pricing data. For example, over time a complex pricing strategy implementation can result in duplicate and irrelevant pricing. With regularly scheduled pricing audits, you can identify and remove duplicates and irrelevant information. Pricing audits help you keep your stores and org within the pricing data limits.

Avoid exceeding limits to irrelevant levels. For example, always keep the number of price books per call at or below 25 price books. Price books above the limit are not included in price call evaluations and result in unused data resources.

Consider customization carefully. Only add customizations when they add significant value. Salesforce recommends you manage pricing data within the scope of the established limits. If you have requirements that exceed the limits, consider the impact on performance and data storage limits.

- Does the additional data push the related data objects beyond their limits?
- Can you offset a data increase by decreasing data requirements in other store functions?

After you assess the impact of a data increase, if you still want to request an increase, contact Support.

<!-- document id=52b649ed1579933ad9a533a3b9b9d2409f95a52f1e322a6aa0f249375e4d4378 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/price-books.md -->

Price Books

# Price Books

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/price-books/price-books-oas-v1-public.yaml)

## API Overview

The Price Books API provides full CRUD (Create, Read, Update, Delete) functionality for price books and price book entries within an organization.

Price books in Salesforce Commerce Cloud contain the pricing information for products. They can be organized in hierarchies where one price book can inherit from another (parent) price book. Each price book is associated with a specific currency and can be assigned to one or more sites.

Price book entries define the actual prices for products within a price book. Each entry carries one or more price scale tables, and each table has its own validity window and a set of quantity-based tiers (as absolute monetary amounts or percentage discounts). Entries have a composite identity of (priceBookId, productId).

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.price-books` (read-only access) or `sfcc.price-books.rw` (read-write access) in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the Authorization for Admin APIs guide.

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Key Constraints

*   **Currency Immutability**: The currency code of a price book is immutable after creation. PATCH attempts to change it will be rejected.
*   **Parent Cycles**: Parent price book relationships that would create a cycle are rejected server-side.
*   **Site Assignments**: The `siteAssignments` field on a price book is read-only. Assignments are managed via the site-assignment endpoints on this API (`PUT`/`DELETE /price-books/{priceBookId}/site-assignments/{siteId}`).
*   **Price Tables**: The `priceTables` array in price book entries is replaced wholesale on PATCH; individual tables and their tiers cannot be updated independently.
*   **Price Book Type**: A price book with `type: feed_based` has its price entries sourced from an external feed pipeline. The price book container itself remains editable via this API, but price book entry write operations against a feed-based price book are rejected.

### Use Cases

#### Create a Price Book

Create a new price book with a specific currency. The price book ID is client-supplied and immutable, so creation uses `PUT` with the ID in the path (create-or-replace upsert); there is no `POST` collection endpoint:

```json
PUT /organizations/{organizationId}/price-books/USD-list-prices
{
  "id": "USD-list-prices",
  "displayName": "USD List Prices",
  "currencyCode": "USD",
  "online": true,
  "validFrom": "2024-01-01T00:00:00.000Z",
  "validTo": "2024-12-31T23:59:59.999Z"
}
```

#### Add a Price to a Product

Create or update a price book entry with a single amount tier:

```json
PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}
{
  "productId": "product-001",
  "priceTables": [
    {
      "tiers": [
        { "type": "amount", "quantity": 1, "amount": { "currencyMnemonic": "USD", "value": 99.99 } }
      ]
    }
  ],
  "online": true
}
```

#### Configure Tiered Pricing

Set up time-scoped quantity-based pricing, mixing absolute amounts and percentage discounts:

```json
PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}
{
  "productId": "product-002",
  "priceTables": [
    {
      "validFrom": "2026-11-25T00:00:00.000Z",
      "validTo": "2026-11-28T23:59:59.999Z",
      "tiers": [
        { "type": "amount", "quantity": 1,  "amount": { "currencyMnemonic": "USD", "value": 39.99 } },
        { "type": "amount", "quantity": 10, "amount": { "currencyMnemonic": "USD", "value": 34.99 } }
      ]
    },
    {
      "validFrom": "2026-12-01T00:00:00.000Z",
      "tiers": [
        { "type": "amount",     "quantity": 1,  "amount": { "currencyMnemonic": "USD", "value": 49.99 } },
        { "type": "percentage", "quantity": 10, "percentage": 15.0 }
      ]
    }
  ],
  "online": true
}
```

#### Find Active Price Books

Search for price books that are currently active (online) and valid:

```json
{
  "query": {
    "boolQuery": {
      "must": [
        {
          "termQuery": {
            "fields": ["online"],
            "operator": "is",
            "values": [true]
          }
        }
      ]
    }
  }
}
```

#### Search by Currency

Find all price books for a specific currency:

```json
{
  "query": {
    "termQuery": {
      "fields": ["currencyCode"],
      "operator": "is",
      "values": ["USD"]
    }
  },
  "sorts": [
    {
      "field": "displayName",
      "sortOrder": "asc"
    }
  ]
}
```

#### Text Search

Search for price books by name or description:

```json
{
  "query": {
    "textQuery": {
      "fields": ["id", "displayName", "description"],
      "searchPhrase": "sale"
    }
  }
}
```

### Related Resources

*   [Pricing and Price Books in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_pricing_and_price_books.htm)
*   [Price Books for Developers in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_price_books_for_developers.htm)

### Related APIs

*   [Products (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/products?meta=Summary) — Manage products associated with price books.

**Version:** 1.1.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/price-books/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 security scheme for Account Manager authentication. Required for all admin API endpoints.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.price-books: Read access to price books
    *   Scope sfcc.price-books.rw: Read and write access to price books
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Get a list of price books.

`GET /organizations/{organizationId}/price-books`

Operation ID: `getPriceBooks`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw).

Get a paginated list of price books for the organization.

Returns all price books with their basic metadata. Use the search endpoint for filtered queries.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Price books retrieved successfully.
    
    Media type: `application/json`. Schema: `PriceBooks`.
    
    _Example: PriceBooksListResult_ Successful price books list retrieval
    
    Example of a paginated list of price books returned by GET /price-books.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 2,
      "data": [
        {
          "id": "USD-list-prices",
          "displayName": "USD List Prices",
          "description": "Standard list prices for USD currency",
          "currencyCode": "USD",
          "online": true,
          "creationDate": "2024-01-01T00:00:00.000Z",
          "lastModified": "2024-01-15T10:30:00.000Z"
        },
        {
          "id": "EUR-list-prices",
          "displayName": "EUR List Prices",
          "currencyCode": "EUR",
          "online": true,
          "creationDate": "2024-01-01T00:00:00.000Z",
          "lastModified": "2024-01-01T00:00:00.000Z"
        }
      ]
    }
    ```
    
*   **400** Bad Request. Returned when a specified parameter value is invalid.
    
    Media type: `application/problem+json`. Schema: `InvalidQueryParameterErrorResponse`.
    
    _Example: InvalidQueryParameterErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter",
      "detail": "Invalid query parameter.",
      "title": "Invalid Query Parameter"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get a price book.

`GET /organizations/{organizationId}/price-books/{priceBookId}`

Operation ID: `getPriceBook`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw).

Get a price book by ID.

Returns the price book with its metadata, including computed site assignments. The `siteAssignments` field is a read-only projection; assignments are managed via the site-assignment endpoints (PUT/DELETE /price-books/{priceBookId}/site-assignments/{siteId}).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.

#### Responses

*   **200** Price book retrieved successfully.
    
    Media type: `application/json`. Schema: `PriceBook`.
    
    _Example: PriceBookRetrieved_ Price book retrieved successfully
    
    Example of a price book returned by GET /price-books/{priceBookId}, including site assignments.
    
    ```
    {
      "id": "USD-list-prices",
      "displayName": "USD List Prices",
      "description": "Standard list prices for USD currency",
      "currencyCode": "USD",
      "type": "standard",
      "parent": "base-prices",
      "online": true,
      "validFrom": "2024-01-01T00:00:00.000Z",
      "validTo": "2024-12-31T23:59:59.999Z",
      "siteAssignments": [
        {
          "id": "RefArch",
          "displayName": "RefArch Store"
        },
        {
          "id": "RefArchGlobal",
          "displayName": "RefArch Global"
        }
      ],
      "creationDate": "2024-01-01T00:00:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`.
    
    _Example: PriceBookNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/price-book-not-found",
      "detail": "The price book with ID 'USD-list-prices' was not found.",
      "title": "Price Book Not Found"
    }
    ```
    

### PUT Create or replace a price book.

`PUT /organizations/{organizationId}/price-books/{priceBookId}`

Operation ID: `createOrUpdatePriceBook`. Security: AmOAuth2 (sfcc.price-books.rw).

Create a new price book or replace an existing one using the information provided.

When replacing an existing price book, the entire price book is replaced with the information in the request. The currency code is immutable and must match the existing value. Attempts to change the currency code will be rejected.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.

#### Request body (required)

The price book

Media type: `application/json`. Schema: `PriceBook`.

_Example: CreatePriceBookRequest_ Create a new price book

Example request body for creating a new price book with a currency code and validity window. Currency is immutable after creation.

```
{
  "id": "USD-list-prices",
  "displayName": "USD List Prices",
  "description": "Standard list prices for USD currency",
  "currencyCode": "USD",
  "online": true,
  "validFrom": "2024-01-01T00:00:00.000Z",
  "validTo": "2024-12-31T23:59:59.999Z"
}
```

#### Responses

*   **200** Price book replaced successfully.
    
    Media type: `application/json`. Schema: `PriceBook`.
    
    _Example: PriceBookReplaced_ Price book replaced successfully
    
    Example of a price book returned after a successful replace via PUT /price-books/{priceBookId}, where the entire resource is replaced with the request body.
    
    ```
    {
      "id": "USD-list-prices",
      "displayName": "USD List Prices",
      "description": "Standard list prices for USD currency",
      "currencyCode": "USD",
      "type": "standard",
      "online": true,
      "validFrom": "2024-01-01T00:00:00.000Z",
      "validTo": "2024-12-31T23:59:59.999Z",
      "creationDate": "2024-01-01T00:00:00.000Z",
      "lastModified": "2024-06-15T14:25:00.000Z"
    }
    ```
    
*   **201** Price book created successfully.
    
    Media type: `application/json`. Schema: `PriceBook`.
    
    _Example: PriceBookCreated_ Price book created successfully
    
    Example of a price book returned after successful creation via PUT /price-books/{priceBookId}.
    
    ```
    {
      "id": "USD-list-prices",
      "displayName": "USD List Prices",
      "description": "Standard list prices for USD currency",
      "currencyCode": "USD",
      "type": "standard",
      "online": true,
      "validFrom": "2024-01-01T00:00:00.000Z",
      "validTo": "2024-12-31T23:59:59.999Z",
      "creationDate": "2024-01-01T00:00:00.000Z",
      "lastModified": "2024-01-01T00:00:00.000Z"
    }
    ```
    
*   **400** Bad Request. Returned when attempting to change an immutable field or create a parent cycle.
    
    Media type: `application/problem+json`. Schema: `CurrencyImmutableErrorResponse | ParentCycleDetectedErrorResponse`.
    
    One of: `CurrencyImmutableErrorResponse`, `ParentCycleDetectedErrorResponse`.
    
    _Example: CurrencyImmutableErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/currency-immutable",
      "detail": "The currency code of a price book cannot be changed after creation.",
      "title": "Currency Immutable"
    }
    ```
    
    _Example: ParentCycleDetectedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/parent-cycle-detected",
      "detail": "The specified parent price book would create a cycle in the price book hierarchy.",
      "title": "Parent Cycle Detected"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### DELETE Delete a price book.

`DELETE /organizations/{organizationId}/price-books/{priceBookId}`

Operation ID: `deletePriceBook`. Security: AmOAuth2 (sfcc.price-books.rw).

Delete a price book by ID.

This operation permanently removes the price book and all its price book entries. Once deleted, the price book cannot be recovered.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.

#### Responses

*   **204** Price book deleted successfully. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    

### PATCH Update a price book.

`PATCH /organizations/{organizationId}/price-books/{priceBookId}`

Operation ID: `updatePriceBook`. Security: AmOAuth2 (sfcc.price-books.rw).

Update a price book with the specified information.

Only the fields provided in the request body are updated. All other fields remain unchanged. The currency code is immutable and cannot be changed via PATCH.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.

#### Request body (required)

The price book fields to update

Media type: `application/json`. Schema: `PriceBook`.

_Example: UpdatePriceBookRequest_ Update an existing price book

Example request body for updating an existing price book. The currencyCode must match the existing value; attempts to change it are rejected.

```
{
  "id": "USD-list-prices",
  "currencyCode": "USD",
  "displayName": "USD List Prices - Updated",
  "description": "Updated standard list prices for USD currency",
  "online": false
}
```

#### Responses

*   **200** Price book updated successfully.
    
    Media type: `application/json`. Schema: `PriceBook`.
    
    _Example: PriceBookUpdated_ Price book updated successfully
    
    Example of a price book returned after a successful partial update via PATCH /price-books/{priceBookId}.
    
    ```
    {
      "id": "USD-list-prices",
      "displayName": "USD List Prices - Updated",
      "description": "Updated standard list prices for USD currency",
      "currencyCode": "USD",
      "online": false,
      "creationDate": "2024-01-01T00:00:00.000Z",
      "lastModified": "2024-06-15T14:25:00.000Z"
    }
    ```
    
*   **400** Bad Request. Returned when attempting to change an immutable field or create a parent cycle.
    
    Media type: `application/problem+json`. Schema: `CurrencyImmutableErrorResponse | ParentCycleDetectedErrorResponse`.
    
    One of: `CurrencyImmutableErrorResponse`, `ParentCycleDetectedErrorResponse`.
    
    _Example CurrencyImmutableErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId} 400 response._
    
    _Example ParentCycleDetectedErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    

### GET Get price book entries.

`GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries`

Operation ID: `getPriceBookEntries`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw).

Get a paginated list of price book entries for the specified price book.

Returns all entries with their pricing information. Use the search endpoint for filtered queries.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50.  
    Default: `50`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Price book entries retrieved successfully.
    
    Media type: `application/json`. Schema: `PriceBookEntries`.
    
    _Example: PriceBookEntriesListResult_ Successful price book entries list retrieval
    
    Example of a paginated list of price book entries, showing both simple and tiered pricing.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 150,
      "data": [
        {
          "productId": "product-001",
          "priceTables": [
            {
              "tiers": [
                {
                  "type": "amount",
                  "quantity": 1,
                  "amount": {
                    "currencyMnemonic": "USD",
                    "value": 99.99
                  }
                }
              ]
            }
          ],
          "creationDate": "2024-01-01T00:00:00.000Z",
          "lastModified": "2024-01-01T00:00:00.000Z"
        },
        {
          "productId": "product-002",
          "priceTables": [
            {
              "validFrom": "2026-11-25T00:00:00.000Z",
              "validTo": "2026-11-28T23:59:59.999Z",
              "tiers": [
                {
                  "type": "amount",
                  "quantity": 1,
                  "amount": {
                    "currencyMnemonic": "USD",
                    "value": 39.99
                  }
                },
                {
                  "type": "amount",
                  "quantity": 10,
                  "amount": {
                    "currencyMnemonic": "USD",
                    "value": 34.99
                  }
                }
              ]
            }
          ],
          "creationDate": "2024-01-01T00:00:00.000Z",
          "lastModified": "2024-02-15T10:00:00.000Z"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    

### GET Get a price book entry.

`GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}`

Operation ID: `getPriceBookEntry`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw).

Get a price book entry by product ID and price book ID.

Returns the pricing information for a specific product in the price book, including tiered pricing if configured.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.
*   `productId` (path, ProductId, required) The product ID.

#### Responses

*   **200** Price book entry retrieved successfully.
    
    Media type: `application/json`. Schema: `PriceBookEntry`.
    
    _Example: PriceBookEntryRetrieved_ Price book entry retrieved successfully
    
    Example of a price book entry returned by GET /price-books/{priceBookId}/price-book-entries/{productId}.
    
    ```
    {
      "productId": "product-001",
      "priceTables": [
        {
          "tiers": [
            {
              "type": "amount",
              "quantity": 1,
              "amount": {
                "currencyMnemonic": "USD",
                "value": 99.99
              }
            }
          ]
        }
      ],
      "creationDate": "2024-01-01T00:00:00.000Z",
      "lastModified": "2024-01-15T10:30:00.000Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book entry or price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookEntryNotFoundErrorResponse | PriceBookNotFoundErrorResponse`.
    
    One of: `PriceBookEntryNotFoundErrorResponse`, `PriceBookNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    
    _Example: PriceBookEntryNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/price-book-entry-not-found",
      "detail": "The price book entry for product 'apple-ipod-classic' in price book 'USD-list-prices' was not found.",
      "title": "Price Book Entry Not Found"
    }
    ```
    

### PUT Create or replace a price book entry.

`PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}`

Operation ID: `createOrUpdatePriceBookEntry`. Security: AmOAuth2 (sfcc.price-books.rw).

Create a new price book entry or replace an existing one using the information provided.

When replacing an existing entry, the entire entry is replaced with the information in the request. The priceTables array, if provided, replaces any existing tiered pricing.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.
*   `productId` (path, ProductId, required) The product ID.

#### Request body (required)

The price book entry

Media type: `application/json`. Schema: `PriceBookEntry`.

_Example: CreatePriceBookEntryRequest_ Create or update a price book entry

Example request body for creating or replacing a price book entry via PUT upsert with a single amount tier.

```
{
  "productId": "product-001",
  "priceTables": [
    {
      "tiers": [
        {
          "type": "amount",
          "quantity": 1,
          "amount": {
            "currencyMnemonic": "USD",
            "value": 99.99
          }
        }
      ]
    }
  ]
}
```

_Example: CreatePriceBookEntryWithTiersRequest_ Create a price book entry with tiered pricing

Example request body creating an entry with time-scoped price tables and both absolute and percentage tiers. On PATCH, the priceTables array is replaced wholesale.

```
{
  "productId": "product-002",
  "priceTables": [
    {
      "validFrom": "2026-11-25T00:00:00.000Z",
      "validTo": "2026-11-28T23:59:59.999Z",
      "tiers": [
        {
          "type": "amount",
          "quantity": 1,
          "amount": {
            "currencyMnemonic": "USD",
            "value": 39.99
          }
        },
        {
          "type": "amount",
          "quantity": 10,
          "amount": {
            "currencyMnemonic": "USD",
            "value": 34.99
          }
        }
      ]
    },
    {
      "validFrom": "2026-12-01T00:00:00.000Z",
      "tiers": [
        {
          "type": "amount",
          "quantity": 1,
          "amount": {
            "currencyMnemonic": "USD",
            "value": 49.99
          }
        },
        {
          "type": "percentage",
          "quantity": 10,
          "percentage": 15
        }
      ]
    }
  ]
}
```

#### Responses

*   **200** Price book entry replaced successfully.
    
    Media type: `application/json`. Schema: `PriceBookEntry`.
    
    _Example: PriceBookEntryReplaced_ Price book entry replaced successfully
    
    Example of a price book entry returned after a successful replace via PUT /price-books/{priceBookId}/price-book-entries/{productId}, where the entire entry is replaced with the request body.
    
    ```
    {
      "productId": "product-001",
      "priceTables": [
        {
          "tiers": [
            {
              "type": "amount",
              "quantity": 1,
              "amount": {
                "currencyMnemonic": "USD",
                "value": 89.99
              }
            }
          ]
        }
      ],
      "creationDate": "2024-01-01T00:00:00.000Z",
      "lastModified": "2024-06-15T14:35:00.000Z"
    }
    ```
    
*   **201** Price book entry created successfully.
    
    Media type: `application/json`. Schema: `PriceBookEntry`.
    
    _Example: PriceBookEntryCreated_ Price book entry created successfully
    
    Example of a price book entry returned after successful creation via PUT upsert.
    
    ```
    {
      "productId": "product-001",
      "priceTables": [
        {
          "tiers": [
            {
              "type": "amount",
              "quantity": 1,
              "amount": {
                "currencyMnemonic": "USD",
                "value": 99.99
              }
            }
          ]
        }
      ],
      "creationDate": "2024-06-15T14:30:00.000Z",
      "lastModified": "2024-06-15T14:30:00.000Z"
    }
    ```
    
*   **400** Bad Request. Returned when the request contains invalid data. Beyond generic schema validation, the following business-logic validations return distinct error types: an invalid time range (validTo before validFrom), a tier currency that does not match the price book currency, and duplicate tier quantities within a single price table.
    
    Media type: `application/problem+json`. Schema: `ValidationErrorResponse | InvalidTimeRangeErrorResponse | TierCurrencyMismatchErrorResponse | DuplicateTierQuantityErrorResponse`.
    
    One of: `ValidationErrorResponse`, `InvalidTimeRangeErrorResponse`, `TierCurrencyMismatchErrorResponse`, `DuplicateTierQuantityErrorResponse`.
    
    _Example: ValidationErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The request body is malformed or contains invalid data.",
      "title": "Validation"
    }
    ```
    
    _Example: InvalidTimeRangeErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-time-range",
      "detail": "The time range is invalid: 'validTo' must not be before 'validFrom'.",
      "title": "Invalid Time Range"
    }
    ```
    
    _Example: TierCurrencyMismatchErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/tier-currency-mismatch",
      "detail": "The tier currency 'USD' does not match the price book currency 'USD'.",
      "title": "Tier Currency Mismatch"
    }
    ```
    
    _Example: DuplicateTierQuantityErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/duplicate-tier-quantity",
      "detail": "Duplicate tier quantity '10' within a single price table. Each tier in a price table must have a distinct quantity.",
      "title": "Duplicate Tier Quantity"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book or product does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse | ProductNotFoundErrorResponse`.
    
    One of: `PriceBookNotFoundErrorResponse`, `ProductNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    
    _Example: ProductNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found",
      "detail": "The product with ID 'apple-ipod-classic' was not found.",
      "title": "Product Not Found"
    }
    ```
    
*   **422** Unprocessable Entity. Price book entry write operations are not supported for a `feed_based` price book, whose entries are sourced from an external feed pipeline. The price book container itself remains editable.
    
    Media type: `application/problem+json`. Schema: `FeedBasedPriceBookNotSupportedErrorResponse`.
    
    _Example: FeedBasedPriceBookNotSupportedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/feed-based-price-book-not-supported",
      "detail": "Price book entry write operations are not supported for the feed-based price book 'USD-list-prices'. Its price entries are sourced from an external feed pipeline.",
      "title": "Feed Based Price Book Not Supported"
    }
    ```
    

### DELETE Delete a price book entry.

`DELETE /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}`

Operation ID: `deletePriceBookEntry`. Security: AmOAuth2 (sfcc.price-books.rw).

Delete a price book entry by product ID and price book ID.

This operation permanently removes the price book entry. Once deleted, the entry is not recoverable; a subsequent PUT for the same product creates a new entry rather than restoring the deleted one.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.
*   `productId` (path, ProductId, required) The product ID.

#### Responses

*   **204** Price book entry deleted successfully. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book entry or price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookEntryNotFoundErrorResponse | PriceBookNotFoundErrorResponse`.
    
    One of: `PriceBookEntryNotFoundErrorResponse`, `PriceBookNotFoundErrorResponse`.
    
    _Example PriceBookEntryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 404 response._
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    
*   **422** Unprocessable Entity. Price book entry write operations are not supported for a `feed_based` price book, whose entries are sourced from an external feed pipeline. The price book container itself remains editable.
    
    Media type: `application/problem+json`. Schema: `FeedBasedPriceBookNotSupportedErrorResponse`.
    
    _Example FeedBasedPriceBookNotSupportedErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 422 response._
    

### PATCH Update a price book entry.

`PATCH /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId}`

Operation ID: `updatePriceBookEntry`. Security: AmOAuth2 (sfcc.price-books.rw).

Update a price book entry with the specified information.

Only the fields provided in the request body are updated. All other fields remain unchanged. The priceTables array, if provided, replaces the existing tiered pricing wholesale.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.
*   `productId` (path, ProductId, required) The product ID.

#### Request body (required)

The price book entry fields to update

Media type: `application/json`. Schema: `PriceBookEntry`.

_Example: UpdatePriceBookEntryRequest_ Update a price book entry

Example partial update via PATCH; the priceTables array provided replaces the entry's existing tables wholesale.

```
{
  "productId": "product-001",
  "priceTables": [
    {
      "tiers": [
        {
          "type": "amount",
          "quantity": 1,
          "amount": {
            "currencyMnemonic": "USD",
            "value": 89.99
          }
        }
      ]
    }
  ]
}
```

#### Responses

*   **200** Price book entry updated successfully.
    
    Media type: `application/json`. Schema: `PriceBookEntry`.
    
    _Example PriceBookEntryUpdated: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 200 response._ Price book entry updated successfully
    
    Example of a price book entry returned after a successful partial update via PATCH /price-books/{priceBookId}/price-book-entries/{productId}.
    
    _Example: PriceBookEntryUpdated_ Price book entry updated successfully
    
    Example of a price book entry returned after a successful partial update via PATCH /price-books/{priceBookId}/price-book-entries/{productId}.
    
*   **400** Bad Request. Returned when the request contains invalid data. Beyond generic schema validation, the following business-logic validations return distinct error types: an invalid time range (validTo before validFrom), a tier currency that does not match the price book currency, and duplicate tier quantities within a single price table.
    
    Media type: `application/problem+json`. Schema: `ValidationErrorResponse | InvalidTimeRangeErrorResponse | TierCurrencyMismatchErrorResponse | DuplicateTierQuantityErrorResponse`.
    
    One of: `ValidationErrorResponse`, `InvalidTimeRangeErrorResponse`, `TierCurrencyMismatchErrorResponse`, `DuplicateTierQuantityErrorResponse`.
    
    _Example InvalidTimeRangeErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 400 response._
    
    _Example TierCurrencyMismatchErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 400 response._
    
    _Example DuplicateTierQuantityErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 400 response._
    
    _Example: ValidationErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The request body is malformed or contains invalid data.",
      "title": "Validation"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book entry or price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookEntryNotFoundErrorResponse | PriceBookNotFoundErrorResponse`.
    
    One of: `PriceBookEntryNotFoundErrorResponse`, `PriceBookNotFoundErrorResponse`.
    
    _Example PriceBookEntryNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 404 response._
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    
*   **422** Unprocessable Entity. Price book entry write operations are not supported for a `feed_based` price book, whose entries are sourced from an external feed pipeline. The price book container itself remains editable.
    
    Media type: `application/problem+json`. Schema: `FeedBasedPriceBookNotSupportedErrorResponse`.
    
    _Example FeedBasedPriceBookNotSupportedErrorResponseExample: same as PUT /organizations/{organizationId}/price-books/{priceBookId}/price-book-entries/{productId} 422 response._
    

### GET Get price book site assignments.

`GET /organizations/{organizationId}/price-books/{priceBookId}/site-assignments`

Operation ID: `getPriceBookSiteAssignments`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw).

Get the list of sites the specified price book is assigned to.

A price book resolves prices only on the sites it is assigned to, so this is the set of sites on which the book is live. The list is bounded and is not paginated. The same information is also available as the read-only `siteAssignments` field on the price book itself.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.

#### Responses

*   **200** Site assignments retrieved successfully.
    
    Media type: `application/json`. Schema: `SiteAssignments`.
    
    _Example: SiteAssignmentsListResult_ Site assignments retrieved successfully
    
    Example of the list of sites a price book is assigned to, returned by GET /price-books/{priceBookId}/site-assignments.
    
    ```
    {
      "limit": 2,
      "total": 2,
      "data": [
        {
          "id": "RefArch",
          "displayName": "RefArch Store"
        },
        {
          "id": "RefArchGlobal",
          "displayName": "RefArch Global"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    

### PUT Assign a price book to a site.

`PUT /organizations/{organizationId}/price-books/{priceBookId}/site-assignments/{siteId}`

Operation ID: `createOrUpdatePriceBookSiteAssignment`. Security: AmOAuth2 (sfcc.price-books.rw).

Assign the specified price book to the specified site, making the book live on that site.

The assignment is idempotent and fully specified by the path, so no request body is required. Returns `201 Created` when the price book was not previously assigned to the site, and `200 OK` when the assignment already existed. This is a container-level operation and is therefore permitted for both `standard` and `feed_based` price books.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.
*   `siteId` (path, SiteId, required) The ID of the site the price book is assigned to.

#### Responses

*   **200** The price book was already assigned to the site.
    
    Media type: `application/json`. Schema: `SiteAssignment`.
    
    _Example: SiteAssignmentUpdated_ Price book site assignment confirmed
    
    Example of a site assignment returned when the price book was already assigned to the site (200) via PUT /price-books/{priceBookId}/site-assignments/{siteId}.
    
    ```
    {
      "id": "RefArch",
      "displayName": "RefArch Store"
    }
    ```
    
*   **201** The price book was assigned to the site successfully.
    
    Media type: `application/json`. Schema: `SiteAssignment`.
    
    _Example: SiteAssignmentCreated_ Price book assigned to site successfully
    
    Example of a site assignment returned after binding a price book to a site that was not previously assigned (201) via PUT /price-books/{priceBookId}/site-assignments/{siteId}.
    
    ```
    {
      "id": "RefArch",
      "displayName": "RefArch Store"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book or site does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse | SiteNotFoundErrorResponse`.
    
    One of: `PriceBookNotFoundErrorResponse`, `SiteNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    
    _Example: SiteNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found",
      "detail": "The site with ID 'RefArch' was not found.",
      "title": "Site Not Found"
    }
    ```
    

### DELETE Unassign a price book from a site.

`DELETE /organizations/{organizationId}/price-books/{priceBookId}/site-assignments/{siteId}`

Operation ID: `deletePriceBookSiteAssignment`. Security: AmOAuth2 (sfcc.price-books.rw).

Remove the assignment of the specified price book from the specified site, so the book is no longer live on that site.

This is a container-level operation and is therefore permitted for both `standard` and `feed_based` price books. No content is returned.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `priceBookId` (path, PriceBookId, required) The price book ID.
*   `siteId` (path, SiteId, required) The ID of the site the price book is assigned to.

#### Responses

*   **204** Site assignment removed successfully. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Not Found. The specified price book or site does not exist.
    
    Media type: `application/problem+json`. Schema: `PriceBookNotFoundErrorResponse | SiteNotFoundErrorResponse`.
    
    One of: `PriceBookNotFoundErrorResponse`, `SiteNotFoundErrorResponse`.
    
    _Example PriceBookNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/price-books/{priceBookId} 404 response._
    
    _Example: SiteNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found",
      "detail": "The site with ID 'RefArch' was not found.",
      "title": "Site Not Found"
    }
    ```
    

### POST Search for price books.

`POST /organizations/{organizationId}/price-book-search`

Operation ID: `searchPriceBooks`. Security: AmOAuth2 (sfcc.price-books, sfcc.price-books.rw).

Searches for price books.

The query attribute specifies a complex query that can be used to narrow down the search. These are the searchable attributes:

*   id - String
*   displayName - String
*   description - String
*   currencyCode - String
*   parent - String
*   validFrom - DateTime
*   validTo - DateTime
*   online - Boolean
*   siteId - String

The output of the query can also be sorted. These are the sortable attributes:

*   id - String
*   displayName - String
*   description - String
*   currencyCode - String
*   parent - String
*   validFrom - DateTime
*   validTo - DateTime
*   online - Boolean

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

The search request document

Media type: `application/json`. Schema: `PriceBookSearchRequest`.

_Example: PriceBookSearchRequestBody_ Basic price book search request

Example of a text-query search that returns price books whose id or displayName contains "USD", sorted by id ascending.

```
{
  "limit": 10,
  "offset": 0,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "displayName"
      ],
      "searchPhrase": "USD"
    }
  },
  "sorts": [
    {
      "field": "id",
      "sortOrder": "asc"
    }
  ]
}
```

_Example: PriceBookSearchRequestWithFilter_ Price book search with term query filter

Example of a boolean-query search combining term filters for currencyCode and online, sorted by displayName ascending.

```
{
  "limit": 25,
  "offset": 0,
  "query": {
    "boolQuery": {
      "must": [
        {
          "termQuery": {
            "fields": [
              "currencyCode"
            ],
            "operator": "is",
            "values": [
              "USD"
            ]
          }
        },
        {
          "termQuery": {
            "fields": [
              "online"
            ],
            "operator": "is",
            "values": [
              true
            ]
          }
        }
      ]
    }
  },
  "sorts": [
    {
      "field": "displayName",
      "sortOrder": "asc"
    }
  ]
}
```

#### Responses

*   **200** Price books searched successfully.
    
    Media type: `application/json`. Schema: `PriceBookSearchResult`.
    
    _Example: PriceBookSearchResult_ Successful price book search result
    
    Example of a successful price book search response with pagination, sorting, and multiple hits.
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 10,
      "query": {
        "textQuery": {
          "fields": [
            "id",
            "displayName"
          ],
          "searchPhrase": "USD"
        }
      },
      "sorts": [
        {
          "field": "id",
          "sortOrder": "asc"
        }
      ],
      "hits": [
        {
          "id": "USD-list-prices",
          "displayName": "USD List Prices",
          "description": "Standard list prices for USD currency",
          "currencyCode": "USD",
          "online": true,
          "validFrom": "2024-01-01T00:00:00.000Z",
          "validTo": "2024-12-31T23:59:59.999Z",
          "creationDate": "2024-01-01T00:00:00.000Z",
          "lastModified": "2024-01-15T10:30:00.000Z"
        },
        {
          "id": "USD-sale-prices",
          "displayName": "USD Sale Prices",
          "description": "Promotional sale prices for USD currency",
          "currencyCode": "USD",
          "parent": "USD-list-prices",
          "online": true,
          "validFrom": "2024-06-01T00:00:00.000Z",
          "validTo": "2024-08-31T23:59:59.999Z",
          "creationDate": "2024-05-15T00:00:00.000Z",
          "lastModified": "2024-06-01T08:00:00.000Z"
        },
        {
          "id": "USD-vip-prices",
          "displayName": "USD VIP Prices",
          "description": "Special prices for VIP customers in USD",
          "currencyCode": "USD",
          "parent": "USD-list-prices",
          "online": true,
          "creationDate": "2024-02-01T00:00:00.000Z",
          "lastModified": "2024-02-10T14:20:00.000Z"
        }
      ]
    }
    ```
    
*   **400** Bad Request. Returned when the search query is malformed or contains invalid fields.
    
    Media type: `application/problem+json`. Schema: `MalformedSearchParameterErrorResponse | UnqueryableFieldErrorResponse | FieldNotSortableErrorResponse`.
    
    One of: `MalformedSearchParameterErrorResponse`, `UnqueryableFieldErrorResponse`, `FieldNotSortableErrorResponse`.
    
    _Example: MalformedSearchParameterErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-search-parameter",
      "detail": "The search query contains invalid syntax. Please check the query structure and try again.",
      "title": "Malformed Search Parameter"
    }
    ```
    
    _Example: UnqueryableFieldErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "detail": "The field 'invalid_field' is not a searchable attribute for price books. Valid fields are: id, displayName, description, currencyCode, parent, validFrom, validTo, online, siteId.",
      "title": "Unqueryable Field"
    }
    ```
    
    _Example: FieldNotSortableErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'invalid_sort' is not a sortable attribute for price books. Valid sortable fields are: id, displayName, description, currencyCode, parent, validFrom, validTo, online.",
      "title": "Field Not Sortable"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### PriceBooks

Document representing a paginated list of price books.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of PriceBook_, required) The collection of price books.  
    Maximum items: 50.

### InvalidQueryParameterErrorResponse

Returned when a specified query parameter value is invalid.

Includes all fields of `ErrorResponse`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### PriceBookId

The ID of the price book.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `USD-list-prices`.

### PriceBook

Document representing a price book.

*   `id` (_object_, required)
    
    Includes all fields of `PriceBookId`.
    
*   `displayName` (_string_) The display name of the price book.  
    Maximum length: 256. Example: `USD List Prices`.
*   `description` (_string_) The detailed description of the price book.  
    Maximum length: 4000. Example: `Standard list prices for USD currency`.
*   `currencyCode` (_object_, required) The currency used by the price book. This can be specified only on create.
    
    Includes all fields of `CurrencyCode`.
    
*   `type` (_string_, read-only) The price book type. 'standard' price books are fully editable via this API. For 'feed\_based' price books, the price entries are sourced from an external feed pipeline: the price book container itself (its metadata, such as displayName, description, online, and validity dates) remains editable via this API, but price book entry write operations against a feed\_based price book are rejected. This is a read-only, server-assigned attribute; price books created via this API are always 'standard'.  
    Allowed values: `standard`, `feed_based`. Example: `standard`.
*   `parent` (_object_) The ID of another price book which is the base for this price book.
    
    Includes all fields of `PriceBookId`.
    
*   `validFrom` (_string (date-time)_) The validity start date and time of the price book.  
    Example: `2024-01-01T00:00:00.000Z`.
*   `validTo` (_string (date-time)_) The validity end date and time of the price book.  
    Example: `2024-12-31T23:59:59.999Z`.
*   `online` (_boolean_) Specifies whether the price book is online (true) or not (false). If unspecified on create, the default value is false.  
    Example: `true`.
*   `siteAssignments` (_array of SiteAssignment_, read-only) The list of sites to which the price book is assigned. This is a read-only computed attribute; assignments are managed via the site-assignment endpoints on this price book (PUT/DELETE /price-books/{priceBookId}/site-assignments/{siteId}).  
    Maximum items: 100.
*   `creationDate` (_string (date-time)_, read-only) The date and time the price book was created.  
    Example: `2024-01-01T00:00:00.000Z`.
*   `lastModified` (_string (date-time)_, read-only) The date and time the price book was last modified.  
    Example: `2024-01-15T10:30:00.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceBookNotFoundErrorResponse

Returned when the specified price book does not exist.

Includes all fields of `ErrorResponse`.

*   `priceBookId` (_PriceBookId_)

### CurrencyImmutableErrorResponse

Returned when attempting to change the currency code of an existing price book.

Includes all fields of `ErrorResponse`.

### ParentCycleDetectedErrorResponse

Returned when a price book parent relationship would create a cycle.

Includes all fields of `ErrorResponse`.

### PriceBookEntries

Document representing a paginated list of price book entries.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of PriceBookEntry_, required) The collection of price book entries.  
    Maximum items: 200.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### PriceBookEntry

Document representing a price book entry. A price book entry has a composite identity of (priceBookId, productId); there is no standalone POST endpoint, use PUT for upsert.

*   `productId` (_object_, required) The product ID for this price book entry.
    
    Includes all fields of `ProductId`.
    
*   `priceTables` (_array of PriceScaleTable_) The list of price scale tables for this product. Each table carries its own validity window and a set of quantity-based tiers. Multiple tables let a merchandiser define overlapping schedules (for example, Black Friday prices alongside regular prices) for the same product in the same price book.  
    Maximum items: 10.
*   `creationDate` (_string (date-time)_, read-only) The date and time the price book entry was created.  
    Example: `2024-01-01T00:00:00.000Z`.
*   `lastModified` (_string (date-time)_, read-only) The date and time the price book entry was last modified.  
    Example: `2024-01-15T10:30:00.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceBookEntryNotFoundErrorResponse

Returned when the specified price book entry does not exist.

Includes all fields of `ErrorResponse`.

*   `priceBookId` (_PriceBookId_)
*   `productId` (_ProductId_)

### ValidationErrorResponse

Returned when the request body fails validation.

Includes all fields of `ErrorResponse`.

### InvalidTimeRangeErrorResponse

Returned when a time range is invalid because its end (validTo) precedes its start (validFrom); for example, a price scale table's validity window.

Includes all fields of `ErrorResponse`.

### TierCurrencyMismatchErrorResponse

Returned when a price scale tier specifies a currency that differs from the enclosing price book's currency.

Includes all fields of `ErrorResponse`.

*   `tierCurrency` (_CurrencyCode_)
*   `priceBookCurrency` (_CurrencyCode_)

### DuplicateTierQuantityErrorResponse

Returned when two or more tiers in the same price scale table declare the same quantity, which the backend keys tiers by.

Includes all fields of `ErrorResponse`.

*   `quantity` (_integer (int32)_) The duplicated tier quantity.  
    Minimum: 1. Maximum: 1000000. Example: `10`.

### ProductNotFoundErrorResponse

Returned when the specified product does not exist.

Includes all fields of `ErrorResponse`.

*   `productId` (_ProductId_)

### FeedBasedPriceBookNotSupportedErrorResponse

Returned when attempting a price book entry write against a feed\_based price book.

Includes all fields of `ErrorResponse`.

*   `priceBookId` (_PriceBookId_)

### SiteAssignments

Document representing the list of site assignments on a price book. The list is bounded (a price book is live on a small set of sites) and is not paginated.

Includes all fields of `ResultBase`.

*   `data` (_array of SiteAssignment_, required) The collection of sites the price book is assigned to.  
    Maximum items: 100.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SiteAssignment

Document representing a site assignment on a price book.

*   `id` (_object_, required)
    
    Includes all fields of `SiteId`.
    
*   `displayName` (_string_) The display name of the site.  
    Maximum length: 256. Example: `RefArch Store`.

### SiteNotFoundErrorResponse

Returned when the site referenced by a site-assignment operation does not exist.

Includes all fields of `ErrorResponse`.

*   `siteId` (_SiteId_)

### PriceBookSearchRequest

Document representing a search request for price books. The query is a potentially complex set of expressions.

Searchable attributes:

*   id (String)
*   displayName (String)
*   description (String)
*   currencyCode (String)
*   parent (String)
*   validFrom (DateTime)
*   validTo (DateTime)
*   online (Boolean)
*   siteId (String)

Sortable attributes:

*   id (String)
*   displayName (String)
*   description (String)
*   currencyCode (String)
*   parent (String)
*   validFrom (DateTime)
*   validTo (DateTime)
*   online (Boolean)

Includes all fields of `SearchRequest`.

_Example_

```
{
  "limit": 2,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "USD"
    }
  },
  "offset": 0
}
```

### PriceBookSearchResult

Document representing a price book search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of PriceBook_, required) The sorted array of price book search hits. The array can be empty if there are no hits.  
    Maximum items: 200.

_Example_

```
{
  "limit": 2,
  "offset": 0,
  "total": 10,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "displayName"
      ],
      "searchPhrase": "USD"
    }
  },
  "hits": [
    {
      "id": "USD-list-prices",
      "displayName": "USD List Prices",
      "currencyCode": "USD",
      "online": true
    },
    {
      "id": "USD-sale-prices",
      "displayName": "USD Sale Prices",
      "currencyCode": "USD",
      "online": true
    }
  ]
}
```

### MalformedSearchParameterErrorResponse

Returned when the search query is malformed or invalid.

Includes all fields of `ErrorResponse`.

### UnqueryableFieldErrorResponse

Returned when a search query uses a field that is not searchable.

Includes all fields of `ErrorResponse`.

*   `field` (_string_) The field name that is not searchable.  
    Maximum length: 256. Example: `invalid_field`.

### FieldNotSortableErrorResponse

Returned when a search query sorts on a field that is not sortable.

Includes all fields of `ErrorResponse`.

*   `field` (_string_) The field name that is not sortable.  
    Maximum length: 256. Example: `invalid_sort`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### PriceScaleTable

A price scale table associates a validity window with a set of quantity tiers. A single price book entry can have multiple tables to express overlapping pricing schedules for the same product.

*   `validFrom` (_string (date-time)_) The start of the validity window during which this price scale table applies. If omitted, the table is valid immediately.  
    Example: `2026-11-25T00:00:00.000Z`.
*   `validTo` (_string (date-time)_) The end of the validity window during which this price scale table applies. If omitted, the table is valid indefinitely.  
    Example: `2026-11-28T23:59:59.999Z`.
*   `tiers` (_array of PriceScaleEntry_, required) The quantity-based tiers for this table. On PUT the table is replaced wholesale; individual tiers cannot be updated independently.  
    Minimum items: 1. Maximum items: 20.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PriceScaleEntry

A single quantity tier within a price scale table. A tier is either an absolute monetary amount or a percentage discount, discriminated by the 'type' property.

Discriminator: `type` selects the concrete type. Mapping: `amount` → `PriceScaleAmount`, `percentage` → `PriceScalePercentage`.

One of: `PriceScaleAmount`, `PriceScalePercentage`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### PriceScaleAmount

A quantity tier priced as an absolute monetary amount.

*   `type` (_string_, required) Discriminator value identifying this tier as an absolute monetary amount.  
    Allowed values: `amount`. Example: `amount`.
*   `quantity` (_integer (int32)_, required) The minimum quantity required for this tier.  
    Minimum: 1. Maximum: 1000000. Example: `10`.
*   `amount` (_object_, required) The tier price as a Money object (amount and currency). The value must not be negative. The currency must match the enclosing price book's currency.
    
    Includes all fields of `NonNegativeMoney`.
    

### PriceScalePercentage

A quantity tier priced as a percentage discount.

*   `type` (_string_, required) Discriminator value identifying this tier as a percentage discount.  
    Allowed values: `percentage`. Example: `percentage`.
*   `quantity` (_integer (int32)_, required) The minimum quantity required for this tier.  
    Minimum: 1. Maximum: 1000000. Example: `10`.
*   `percentage` (_number (double)_, required) The percentage discount for this tier, expressed as a number between 0 and 100.  
    Minimum: 0. Maximum: 100. Example: `15`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### NonNegativeMoney

A combination of a currency and a non-negative amount of that currency.

*   `currencyMnemonic` (_CurrencyCode_)
*   `value` (_number (double)_, required) The amount of money for the given currency. Must not be negative.  
    Minimum: 0. Example: `1234.56`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=fef0637acde3542a21aefe22daa3523eac5d502c856e959badfa4645bed182be url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-price-books.md -->

Price Books

# Price Books

Price Book is a way to group the seller’s prices

There are 3 types of Price Book:

*   Simple: Price Book with the default value of the SKUs. Only 1 per seller.
*   Sale: Price Book with the “promotional” value (“to” price) of the SKUs. Only 1 per seller.
*   Customer Group: Price Book active only for a specific user group. Various Price Books of this type can be set up per seller, but only 1 for each Customer Group.

It is recommended that, when configuring the seller, the marketplace should set up the Simple and Sale Price Book with the correct external ID, but this configuration can be achieved by means of API integration.

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### GET Query

`GET /services/data/v51.0/query`

Operation ID: `Query`. Tags: Price Book. Security: bearerAuth.

To look up information about price books, use the [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) resource of the main REST API from Salesforce and set the value of the `q` parameter to an SOQL query. The following examples are included in the query parameters section of this page, with corresponding examples in the responses section:

**Example 1 of 4**: `getSimplePriceBookBySellerId`

This call allows the searching of information about the seller’s simple price book. If you do not know the external ID of the price book, this call can be used to search for that information.

**Example 2 of 4**: `getPriceBookEntryByPriceBookId`

This call allows the listing of the price of all SKUs within a specific price book using the external ID. Depending on the quantity, the results may require pagination.

**Example 3 of 4**: `getSalePriceBookBySellerId`

This call allows the searching of the seller’s sale price book information. If you do not know the external ID of the price book, this call can be used to search for that information.

**Example 4 of 4**: `getAllCustomerGroups`

For customer group price books, a connection needs to be made with a customer group. This value must be one of the values from the marketplace (if none of them apply, contact the marketplace to check whether a new one can be inserted). In order to insert this relationship, you must first request an export of the data to the marketplace or access the APU directly and save the list. If the item limit is exceeded, pagination may be necessary, in which case please refer to the following [documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm#retrieve_remaining_results_title).

#### Parameters

*   `q` (query, string)
    
    _Example: getSimplePriceBookBySellerId_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__PriceBook__c WHERE Atonit_Mktplace__Seller__r.Atonit_Mktplace__Slug__c= '{{seller-external-id}}' AND RecordType.Name = 'Default PriceBook' LIMIT 200
    ```
    
    _Example: getPriceBookEntryByPriceBookId_
    
    ```
    SELECT Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Price_Book__r.Atonit_Mktplace__External_Id__c, Atonit_Mktplace__Product_Variant__r.Atonit_Mktplace__External_Id__c,Atonit_Mktplace__Quantity__c,Atonit_Mktplace__Price__c  FROM Atonit_Mktplace__Price_Book_Entry__c WHERE Atonit_Mktplace__Price_Book__r.Atonit_Mktplace__External_Id__c= '{{seller-api-prefix}}-pricebook' LIMIT 200
    ```
    
    _Example: getSalePriceBookBySellerId_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__PriceBook__c WHERE Atonit_Mktplace__Seller__r.Atonit_Mktplace__Slug__c= '{{seller-external-id}}' AND RecordType.Name = 'Sale PriceBook' LIMIT 200
    ```
    
    _Example: getAllCustomerGroups_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__Customer_Group__c   LIMIT 200
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 19:03:24 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1456/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example: getSimplePriceBookBySellerId_
    
    ```
    {
      "totalSize": 1,
      "done": true,
      "records": [
        {
          "Id": "a0H5Y00001JDrCiUAL",
          "Name": "PB-0004",
          "CreatedDate": "2021-03-23T16:43:00.000+0000",
          "LastModifiedDate": "2021-04-23T14:57:46.000+0000",
          "Atonit_Mktplace__Name__c": "atonit-vitta PriceBook Default",
          "Atonit_Mktplace__Seller__c": "a0T5Y00000ZE4lFUAT",
          "Atonit_Mktplace__External_Id__c": "atonit-vitta-pricebook"
        }
      ]
    }
    ```
    
    _Example: getPriceBookEntryByPriceBookId_
    
    ```
    {
      "totalSize": 6,
      "done": true,
      "records": [
        {
          "Atonit_Mktplace__External_Id__c": "atonit-vitta-pricebook-atonit-vitta-sku-1-1",
          "Atonit_Mktplace__Price_Book__r": {
            "Atonit_Mktplace__External_Id__c": "atonit-vitta-pricebook"
          },
          "Atonit_Mktplace__Product_Variant__r": {
            "Atonit_Mktplace__External_Id__c": "atonit-vitta-sku-1"
          },
          "Atonit_Mktplace__Quantity__c": 1,
          "Atonit_Mktplace__Price__c": 45.33
        }
      ]
    }
    ```
    
    _Example: getSalePriceBookBySellerId_
    
    ```
    {
      "totalSize": 1,
      "done": true,
      "records": [
        {
          "Id": "a0H5Y00001JEngLUAT",
          "Name": "PB-0009",
          "CreatedDate": "2021-04-23T13:58:09.000+0000",
          "LastModifiedDate": "2021-04-23T14:57:25.000+0000",
          "Atonit_Mktplace__Name__c": "atonit-vitta PriceBook Sale",
          "Atonit_Mktplace__Seller__c": "a0T5Y00000ZE4lFUAT",
          "Atonit_Mktplace__Parent_Price_Book__c": "a0H5Y00001JDrCiUAL",
          "Atonit_Mktplace__External_Id__c": "atonit-vitta-pricebook-sale"
        }
      ]
    }
    ```
    

### GET Get Price Book by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook`

Operation ID: `Get Price Book by ID`. Tags: Price Book. Security: bearerAuth.

This call will load all the available price book information using the external ID as the key. Any type of price book can be used.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 12:13:19 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1397/101002`.
    *   `Last-Modified` (string)  
        Example: `Mon, 26 Apr 2021 12:12:25 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a0H5Y00001JDrCiUAL",
      "Name": "PB-0004",
      "CreatedDate": "2021-03-23T16:43:00.000+0000",
      "LastModifiedDate": "2021-04-26T12:12:25.000+0000",
      "Atonit_Mktplace__Active__c": true,
      "Atonit_Mktplace__Currency__c": "USD",
      "Atonit_Mktplace__Name__c": "atonit-vitta PriceBook Default",
      "Atonit_Mktplace__Seller__c": "a0T5Y00000ZE4lFUAT",
      "Atonit_Mktplace__Valid_From__c": null,
      "Atonit_Mktplace__Valid_To__c": null,
      "Atonit_Mktplace__Parent_Price_Book__c": null,
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-pricebook"
    }
    ```
    

### PATCH Create or Update Simple Price Book

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook`

Operation ID: `Create or Update Simple Price Book`. Tags: Price Book. Security: bearerAuth.

This call allows you both to create and update the seller’s simple price book. If a price book already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

Take care at all times not to create more than 1 simple price book for the seller, otherwise the integration will not work properly.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Name__c": "{{seller-api-prefix}} PriceBook Default",
  "RecordType": {
    "Name": "Default PriceBook"
  },
  "Atonit_Mktplace__Seller__r": {
    "Atonit_Mktplace__Slug__c": "{{seller-external-id}"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 12:12:25 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1391/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook__c/a0H5Y00001JDrCiUAL`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0H5Y00001JDrCiUAL",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### GET Get Price Book Entry by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Price_Book_Entry__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook-{seller-api-prefix}-sku-1-1`

Operation ID: `Get Price Book Entry by ID`. Tags: Price Book. Security: bearerAuth.

This call will load all available price information for an SKU using the external ID as the key.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 12:26:01 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1401/101002`.
    *   `Last-Modified` (string)  
        Example: `Mon, 26 Apr 2021 12:16:19 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a0I5Y000017PI2nUAG",
      "Name": "PBE-0211",
      "CreatedDate": "2021-04-23T14:29:30.000+0000",
      "LastModifiedDate": "2021-04-26T12:16:19.000+0000",
      "Atonit_Mktplace__Price_Book__c": "a0H5Y00001JDrCiUAL",
      "Atonit_Mktplace__Price__c": 45.33,
      "Atonit_Mktplace__Product_Variant__c": "a0L5Y00000oAUQDUA4",
      "Atonit_Mktplace__Quantity__c": 1,
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-pricebook-atonit-vitta-sku-1-1"
    }
    ```
    

### DELETE Remove Price Book Entry

`DELETE /services/data/v51.0/sobjects/Atonit_Mktplace__Price_Book_Entry__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook-{seller-api-prefix}-sku-1-1`

Operation ID: `Remove Price Book Entry`. Tags: Price Book. Security: bearerAuth.

This call allows the price of an SKU to be removed from a price book. If successful, 204 is returned. If the ID no longer exists, 404 will be returned.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **204** No Content
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 13:28:18 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Content-Security-Policy` (string)  
        Example: `upgrade-insecure-requests` .
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1442/101002`.
    
    Media type: `text/plain`. Schema: `string`.
    
    Type: `string`.
    

### PATCH Create or Update Price Book Entry

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Price_Book_Entry__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook-{seller-api-prefix}-sku-1-1`

Operation ID: `Create or Update Price Book Entry`. Tags: Price Book. Security: bearerAuth.

This call allows you both to create and update the price of an SKU in a seller’s price book. If a price already exists with the ID provided in the URL, it will be updated, otherwise it will be created. If it is greater than 1, the quantity value will be the price when this quantity of the product is in the cart. The rule for the id is that it must be in the format `<id-price-book>-<id-sku>-<qtd>`. This call can be used for any type of price book.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Price_Book__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-pricebook"
  },
  "Atonit_Mktplace__Product_Variant__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-sku-1"
  },
  "Atonit_Mktplace__Quantity__c": 1,
  "Atonit_Mktplace__Price__c": 45.33
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 12:16:18 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1399/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Price_Book_Entry__c/a0I5Y000017PI2nUAG`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0I5Y000017PI2nUAG",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### PATCH Create or Update Sale Price Book

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook-sale`

Operation ID: `Create or Update Sale Price Book`. Tags: Price Book. Security: bearerAuth.

This call allows you both to create and update the seller’s sale price book. If a price book already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

Take care at all times not to create more than 1 sale price book for the seller, otherwise the integration will not work properly.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Name__c": "{{seller-api-prefix}} PriceBook Sale",
  "RecordType": {
    "Name": "Sale PriceBook"
  },
  "Atonit_Mktplace__Seller__r": {
    "Atonit_Mktplace__Slug__c": "{{seller-external-id}"
  },
  "Atonit_Mktplace__Parent_Price_Book__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-pricebook"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 13:23:28 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1427/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook__c/a0H5Y00001JEngLUAT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0H5Y00001JEngLUAT",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### PATCH Create or Update Customer Group Price Book

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook-customergroup-1`

Operation ID: `Create or Update Customer Group Price Book`. Tags: Price Book. Security: bearerAuth.

This call allows you both to create and update a seller’s customer group price book. If a price book already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Name__c": "{{seller-api-prefix}} Clientes Platina",
  "RecordType": {
    "Name": "Customer Group PriceBook"
  },
  "Atonit_Mktplace__Seller__r": {
    "Atonit_Mktplace__Slug__c": "{{seller-external-id}}"
  },
  "Atonit_Mktplace__Parent_Price_Book__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-pricebook"
  },
  "Atonit_Mktplace__Active__c": true,
  "Atonit_Mktplace__Currency__c": "BRL",
  "Atonit_Mktplace__Valid_From__c": "2021-04-23T00:00:00.000+0000",
  "Atonit_Mktplace__Valid_To__c": "2021-06-23T00:00:00.000+0000"
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 13:35:28 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1454/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook__c/a0H5Y00001JEngcUAD`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0H5Y00001JEngcUAD",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### DELETE Remove Link from Price Book to Customer Group

`DELETE /services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook_CustomerGroup_Association__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook-customergroup-1-clientes-platina`

Operation ID: `Remove Link from Price Book to Customer Group`. Tags: Price Book. Security: bearerAuth.

This call allows an association between a price book and customer group to be deleted. If successful, 204 is returned. If the ID no longer exists, 404 will be returned.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **204** No Content
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 13:38:10 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Content-Security-Policy` (string)  
        Example: `upgrade-insecure-requests` .
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1458/101002`.
    
    Media type: `text/plain`. Schema: `string`.
    
    Type: `string`.
    

### PATCH Link Price Book to Customer Group

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook_CustomerGroup_Association__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-pricebook-customergroup-1-clientes-platina`

Operation ID: `Link Price Book to Customer Group`. Tags: Price Book. Security: bearerAuth.

This call allows a price book of the customer group type to be linked to a customer group from the marketplace. The external ID must be in the format `<id-price-book>-<id-customergroup>`.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Price_Book__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-pricebook-customergroup-1"
  },
  "Atonit_Mktplace__Customer_Group__r": {
    "Atonit_Mktplace__MArketplace_Id__c": "clientes-platina"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Mon, 26 Apr 2021 13:37:32 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1457/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__PriceBook_CustomerGroup_Association__c/a0G5Y00000e4LuxUAE`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0G5Y00000e4LuxUAE",
      "success": true,
      "errors": [],
      "created": false
    }
    ```

<!-- document id=1a4d96c2134305da58e1833b0e88ed8d7df0a9d20b72f64df9fdff8168481e34 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-pricing.md -->

# Pricing Data Model

The Pricing data model connects objects and relationships that support pricing definitions. These attributes determine how pricing appears to the customer in places like the Product Listing Page, Product Details Page, Product Recommendations, and Cart.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the cart data model require at least one of the following licenses: B2B Commerce, Salesforce Order Management, or Salesforce Payments.

![Diagram of the Pricing data model](https://developer.salesforce.com/media/d2c-commerce/pricing_data_model_2.png)

- [Account](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_account.htm)
- [Buyer Group](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergroup.htm)
- [Buyer Group Member](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergroupmember.htm)
- [Buyer Group Price Book](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergrouppricebook.htm)
- [Price Book 2](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebook2.htm)
- [Web Store Price Book](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorepricebook.htm)
- [Web Store](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)
- [Price Book Entry](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebookentry.htm)
- [Product Selling Model](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productsellingmodel.htm)
- [Price Book Entry Adjustment](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebookentryadjustment.htm)
- [Price Adjustment Schedule](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_priceadjustmentschedule.htm)
- [Price Adjustment Tier](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_priceadjustmenttier.htm)

<!-- document id=1988828e030b031f9291eb0361447c0a1f0eeef03af1638fbc053512979104bd url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-private-client.md -->

# Private SLAS Client Use Cases

**note:** Setting up SLAS and making your first request is covered in the Get Started guides. See [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).

These use cases show how SLAS authorizes access to a Shopper API for private clients under different login scenarios.

Remember that any shopping app that is able to securely store a client secret is a private client. Full stack web apps and all shopping apps with a backend-for-frontend (BFF) must be provisioned as private clients.

## Prerequisites

- A SLAS private client created in the SLAS Admin UI (with a client secret). See [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).
- Your short code, organization ID, and site ID. See [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md).
- The relevant scopes assigned to your SLAS client. See [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/auth-z-scope-catalog.md).

## Use Cases

Each use case demonstrates a different login scenario: guest user (no login), federated login, and B2C login.

Although all three use cases feature the Open Commerce API (OCAPI)’s `/baskets` endpoint, remember that a SLAS access token can be used with _any_ Shopper API endpoint.

Each step in the authentication flow is numbered and described in detail for all three use cases. The numbered steps are also illustrated with a diagram to help you visualize the process.

See the [Shopper Login and API Access Service (SLAS) API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary) for full details on how to make your API requests.

Explore these use cases interactively with a Postman collection: [Salesforce Commerce B2C SLAS Use Cases](https://www.postman.com/salesforce-developers/salesforce-developers/folder/zjwouu1/slas).

## Guest User

This use case describes what happens when the shopper adds a product to their basket without logging in first. It follows the [client credentials grant](https://tools.ietf.org/html/rfc6749#section-4.4) flow as defined by the OAuth 2.1 standard.

![Flow diagram showing SLAS private client authentication process for guest users](https://developer.salesforce.com/docs/media/commerce-api/slas-private-client-guest-user.png)

1. A shopper opens a B2C Commerce shopping app and starts interacting with it.
2. The shopping app requests an access token using the `/token` endpoint of the SLAS API.

   - The request must include an authorization header that contains a [Base64](https://en.wikipedia.org/wiki/Base64) encoded version of the following string: `<clientID>:<clientSecret>`. (Don’t forget to replace `<clientID>` and `<clientSecret>` with actual values before encoding the string.)
   - Example header value: `Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.
   - The client ID and client secret must be provisioned for the app by a SLAS Organization Administrator. See the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary) for more information.
   - Required query parameter: `grant_type=client_credentials`.
   - Recommended query parameter (**will be required in the future**): `channel_id`.
   - Optional query parameter: `usid`. If you already have a Unique Shopper Identifier (USID) for the guest user, you can pass it in. Otherwise, a USID is generated for you by SLAS.
   - Best practice: reuse the USID for a shopper from the previous guest login so that you can tie that user to all the previous login attempts and enable personalization.

3. The endpoint responds with an access token in the form of a JSON Web Token (JWT), a `customer_id` string, a USID, and a refresh token.
4. The guest shopper adds a product to their basket.
5. The shopping app makes a request to the `/baskets` endpoint of OCAPI and provides a SLAS access token in the header.
6. The Baskets API saves a shopping basket with a `customer_id` string that is associated with the guest user.

## Registered User (Federated Login)

This use case describes what happens when a shopper logs in using a third-party identity provider before adding a product to their basket. It follows the [authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1) flow as defined by the OAuth 2.1 standard.

![SLAS private client authentication for federated registered users](https://developer.salesforce.com/docs/media/commerce-api/slas-private-client-registered-user-federated.png)

1. A shopper logs in to a B2C Commerce shopping app and chooses a third-party identity provider (IDP) to perform the authentication.
2. The shopping app makes a request to the `/authorize` endpoint of the SLAS API.

   - Required query parameters: `hint`, `response_type=code`, `client_id`, and `redirect_uri`.
   - The `hint` parameter specifies the name of the identity provider.
   - The `redirect_uri` parameter specifies what app route to redirect to when the login is complete.

3. The SLAS API redirects to the identity provider’s login page.
4. The shopper enters their credentials and consents.
5. If login is successful, the SLAS API responds with an authorization code and redirects to the shopping app.
6. The shopping app requests an access token using the `/token` endpoint of the SLAS API.

   - The request must include an authorization header that contains a [Base64](https://en.wikipedia.org/wiki/Base64) encoded version of the following string: `<clientID>:<clientSecret>`. (Don’t forget to replace `<clientID>` and `<clientSecret>` with actual values before encoding the string.)
   - Example header value: `Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.
   - The client ID and client secret must be provisioned for the app by a SLAS Organization Administrator. See the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary) for more information.
   - Required query parameter: `grant_type=authorization_code`.

7. The endpoint responds with an access token in the form of a JSON Web Token (JWT), a `customer_id` string, a USID, and a refresh token.
8. The shopper adds a product to their basket.
9. The shopping app makes a request to the `/baskets` endpoint of OCAPI and provides a SLAS access token in the header.
10. The Baskets API saves a shopping basket with a `customer_id` string that is associated with the registered user.

## Registered User (B2C Commerce Login)

This use case describes what happens when a shopper logs in with credentials that are managed by a B2C Commerce instance before adding a product to their basket. It follows the [authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1) flow as defined by the OAuth 2.1 standard. It also uses a [proof key for code exchange](https://tools.ietf.org/html/rfc7636) (PKCE), as defined by RFC 7636.

![SLAS private client authentication for registered B2C Commerce users](https://developer.salesforce.com/docs/media/commerce-api/slas-private-client-registered-user-b2c.png)

1. A shopper logs in to a B2C Commerce shopping app and chooses to authenticate directly through the shopping app.
2. The shopping app generates two strings: `code_verifier` and `code_challenge`.

   - The `code_verifier` string is a random string.
   - The `code_challenge` is an encoded version of the `code_verifier` string using an SHA-256 hash.

3. The shopping app makes a request to the `/login` endpoint of the SLAS API.

   - The request must include an authorization header that contains a [Base64](https://en.wikipedia.org/wiki/Base64) encoded version of the following string: `<shopperUserID>:<shopperPassword>`. (Don’t forget to replace `<shopperUserID>` and `<shopperPassword>` with actual values before encoding the string.)
   - Example header value: `Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.
   - Required query parameters: `code_challenge`, `usid`, `channel_id`, `client_id`, and `redirect_uri`.

4. The SLAS API validates the user credentials, redirects to the redirect URI, and returns an authorization code.
5. The shopping app makes a request to the `/token` endpoint of the SLAS API.

   - The request must include an authorization header that contains a [Base64](https://en.wikipedia.org/wiki/Base64) encoded version of the following string: `<clientID>:<clientSecret>`. (Don’t forget to replace `<clientID>` and `<clientSecret>` with actual values before encoding the string.)
   - Example header value: `Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.
   - The client ID and client secret must be provisioned for the app by a SLAS Organization Administrator. See the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary) for more information.
   - Required query parameters: `grant_type=authorization_code_pkce`, `code_verifier`, `code`, `client_id`, and `redirect_uri`.

6. The endpoint responds with an access token in the form of a JSON Web Token (JWT), a `customer_id` string, a USID, and a refresh token.

   - The response also includes an `enc_user_id` string that can be used to call Einstein APIs.

7. The shopper adds a product to their basket.
8. The shopping app makes a request to the `/baskets` endpoint of OCAPI and provides a SLAS access token in the header.
9. The Baskets API saves a shopping basket with a `customer_id` string that is associated with the registered user.

## Next Steps

Now that you’re familiar with the use cases with private clients, check out the [Public SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-public-client.md).

When you’re ready to incorporate SLAS into your app, explore the [API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary) for the complete technical specifications for the SLAS endpoints.

<!-- document id=630c1f83eb445d05215fb7cbb6125135b7025f2a9cf5ecbfe6f2960509141541 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-process-payment.md -->

# Process Payment

To place an order, submit a tokenized payment from a payment provider. Use this resource for:

- Salesforce Payments
- Custom payment adapters

**Endpoint:** POST [`/commerce/webstores/{webstoreId}/checkouts/{cartId}/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm)

**Note:** If you modify the cart after setting the billing address, the system invalidates the payment and clears the billing address.

<!-- document id=8acf973fcb419d96b868305cee5d8e8be1ceefccfcc5cee67b9d64f5cdd04101 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-product-catalog.md -->

# Product and Catalog Data Model

The Product and Catalog data model connects objects used to support product, catalog, and category organization in a B2B or B2C store.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

A product is assigned to a product category, and each product category is assigned to a product catalog. A store can be associated with only one catalog, but a catalog can be associated with multiple stores.

Commerce standard objects in the Product and Catalogs data model require at least one of the following licenses: B2B Commerce.

![Diagram of the Product and Catalog data model](https://developer.salesforce.com/media/d2c-commerce/product_catalog_data_model.png)

- [Product (Product2)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm)
- [Product Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-product-limits.md)
- [Product Catalog (ProductCatalog)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcatalog.htm)
- [Product Category (ProductCategory)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcategory.htm)
- [Product Category Product (ProductCategoryProduct)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcategoryproduct.htm)
- Sales Store (SalesStore)
- [Sales Store Catalog (SalesStoreCatalog)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_salesstorecatalog.htm)
- [Store (WebStore)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)
- [Store Catalog (WebStoreCatalog)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorecatalog.htm)

<!-- document id=6f44dabb3e1f93059a3a581e1851cec598d3e4dda9f22c0dcbd62ae88de14af8 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-product-category-media.md -->

# Product and Category Media Data Model

The Product and Category Media data model connects objects and relationships that support adding images and other attachments to provide more information to customers.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the Product and Category Media data model require at least one of the following licenses: B2B Commerce.

![Diagram of the Product Category Media data model](https://developer.salesforce.com/media/d2c-commerce/product_category_media_data_model.png)

- [Product (Product2)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm)
- [Product Category (ProductCategory)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcategory.htm)
- [Product Media (ProductMedia)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productmedia.htm)
- Product Category Media (ProductCategoryMedia)
- [Electronic Media Use (ElectronicMediaUse)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_electronicmediause.htm)
- [Electronic Media Group (ElectronicMediaGroup)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_electronicmediagroup.htm)
- [Managed Content Info (ManagedContentInfo)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_managedcontentinfo.htm)

<!-- document id=52cab41aeea62aa1e849c7a0a344cd1f6171312bd2aa95679c7a5fee5461c966 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-product-limits.md -->

# Product and Product Category Limits

| Object                             | Limit B2B Except Where Indicated | Store or Org | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------------------------- | -------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Products                           | 4 million                        | Store        | Applies to B2B stores. Products in Commerce rely on standard core entities shared across Sales, Service, and other clouds. <ul><li>Merchants can add up to 4 million products to the catalog; however, only up to 1 million products are supported for search.</li></ul> <ul><li>Contact your account representative if you need to upload more than a million SKUs to your store. If you work with a third-party search provider, for example, Coveo, Algolia, or Bloomreach, the 4 million limit doesn’t apply.</li></ul> |
| Variation Parent Products          | 500,000                          | Store        | This is specific to parent products. It doesn't include child products.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| Variation Products                 | 3 million                        | Store        | Includes the variation parent and child products.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Variants per Parent                | 200                              | Store        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Products per entitlement policy    | 3 million                        | N/A          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Products per Product Category      | 1.8 million                      | N/A          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Products Catalogs per Store        | 1                                | Store        | Only one product catalog is supported per store.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Products per Catalog               | 3 million                        | Store        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Images per Product                 | 9                                | N/A          | You can also add up to 5 file attachments per product.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Attributes per Set                 | 5<sup>\*</sup>                   | N/A          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Product Categories per Catalog     | 15,000<sup>\*</sup>              | N/A          | The total number of top-level and subcategories in a product catalog.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Product Subcategories per Category | 100<sup>\*</sup>                 | N/A          | The number of subcategories for each top-level category.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Total Top-Level Categories         | 100<sup>\*</sup>                 | N/A          | The number of top-level categories.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Category Depth (Levels)            | 5<sup>\*</sup>                   | N/A          | The number of levels in a category hierarchy.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce customer support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

Salesforce recommends you keep product data within the scope of the established limits. If you have requirements that exceed the limits, consider how the increase impacts other data limits across your stores and org. For example, you’re adding new product lines to your store and want to increase the total number of products to 300,500. Before requesting the increase from Support, assess the impact the increase has on related data limits. For each additional product, consider the additional data the product generates.

Configure product categories to enhance customer navigation and hierarchy optimization.

- Keep the category hierarchy as simple as possible while still meeting your business needs.
- Avoid overly deep or complex hierarchies that can impact performance and make maintenance challenging.
- Focus on critical fields and attributes that impact product categorization and customer navigation.

If you have requirements that exceed the limits, consider the impact on performance and data limits.

- Does the additional data push the related data objects beyond their limits?
- Can you offset a data increase in data volume by decreasing data requirements in other store functions?

After you assess the impact of a data increase, if you still want to request an increase, contact Support.

<!-- document id=60515092a013cf627c42e8b99c4205e533019bf7b4c0838594452a3e11a07218 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-product-attributes.md -->

# Product Attributes Data Model

The Product Attributes data model connects objects and relationships that support product attribute definitions. These attributes determine how products appear to the customer in places like the product details page and search.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the Product Attributes data model require at least one of the following licenses: B2B Commerce.

![Diagram of the ProductAttributes data model](https://developer.salesforce.com/media/d2c-commerce/product_attributes_data_model.png)

- [Product (Product2)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm)
- [ProductAttribute](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productattribute.htm)
- [ProductAttributeSet](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productattributeset.htm)
- [ProductAttributeSetItem](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productattributesetitem.htm)
- [ProductAttributeSetProduct](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productattributesetproduct.htm)

<!-- document id=fef05f260bc0ce66fe1e1b495d14d8caaea783f95b3ac8d5509148068a307423 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-product-detail-page.md -->

# Product Detail Page (PDP)

### Overview

The Product Detail Page (PDP) shows product details, including product image, name, description, pricing, quantity selector, and an Add-to-Cart action. The page performs two parallel API requests — one to retrieve product details and another to retrieve buyer-entitled pricing information.

### Buyer Journey

This flow demonstrates how a headless storefront can render product detail experiences, including buyer-entitled pricing and add-to-cart functionality, using B2B Commerce Product APIs.

![Product Detail Page API Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-product-detail-page-pdp-b2b-commerce-apis-used-in-the-flow-11-1.png '{"class": "image-lg", "title": "Product Detail Page API Flow"}')

### B2B Commerce APIs Used in the Flow

| Purpose           | HTTP Method | Endpoint                                                                                                                                                                                              |
| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get product       | GET         | [`/commerce/webstores/{webstoreId}/products/{productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product.htm)               |
| Get product price | GET         | [`/commerce/webstores/{webstoreId}/pricing/products/{productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_price.htm) |
| Add to cart       | POST        | [`/commerce/webstores/{webstoreId}/carts/current/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemCollection)                |

**Render Product Details**

1. Load the product detail page.

2. Call the following endpoint to retrieve product details:

   GET [`/commerce/webstores/{webstoreId}/products/{productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product.htm)

3. In parallel, call the following endpoint to retrieve buyer-entitled pricing information:

   GET [`/commerce/webstores/{webstoreId}/pricing/products/{productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_price.htm)

4. Use the responses to render:

   - Product image
   - Product name
   - Product description
   - Product pricing
   - Quantity selector
   - Add-to-Cart action

5. Handle pricing entitlement failures gracefully. If the pricing endpoint returns `403` or `404`, display an unavailable pricing placeholder instead of failing the entire page load.

**Change Product Quantity**

1. Update the quantity selector to change the desired purchase quantity.

2. Store the selected quantity in local UI state. No API request is required until the buyer adds the product to the cart.

**Add a Product to the Cart**

1. Select Add to Cart to add the product to the active cart.

2. Call the following endpoint:

   POST [`/commerce/webstores/{webstoreId}/carts/current/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemCollection)

   Example request body:

   ```json
   { "productId": "<product-id>", "quantity": 1, "type": "Product" }
   ```

3. After the request succeeds, refresh the cart summary by calling:

   GET [`/commerce/webstores/{webstoreId}/carts/compact-summary`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartBadge).

4. Refresh the cart item collection by calling:

   GET [`/commerce/webstores/{webstoreId}/carts/current/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartItemCollection).

5. Use the updated cart responses to synchronize:

   - Global cart badge
   - Cart summary state
   - Cached cart views

6. Show a confirmation message or toast notification indicating that the product was added to the cart successfully.

### Extend the Flow

1. To add a variant selector, call:

   GET [`/commerce/webstores/{webstoreId}/products/{productId}/children`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_children.htm)

   Render the returned child variants as a swatch list or variant selector above the quantity selector to enable buyers to switch between product variations.

2. To add wishlist functionality, send:

   POST [`/commerce/webstores/{webstoreId}/wishlists/{wishlistId}/wishlist-items`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_items.htm)

   Enable buyers to save products to a wishlist directly from the product detail page.

   **note:** Wishlist APIs and buyer wishlist flows are outside the scope of this storefront page set.

## See Also

- [_B2B Commerce Developer Guide_: B2B Commerce Product and Category APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-product-category-apis.html)

<!-- document id=4261b6f7685f1a548e7d4987996c199fcbb217769a134e6ea06ec2243f251a5c url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-product-list-page.md -->

# Product List Page (Category/PLP)

### Overview

The Product List Page shows products for a selected category, including pagination controls and product result counts. The page automatically re-executes the product search whenever the category ID, pagination state, or selected refinement filters change.

This flow demonstrates how a headless storefront can render category-based product experiences using B2B Commerce Product APIs.

![Product List Page API Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-product-list-page-category-plp-b2b-commerce-apis-used-in-the-flow-9-1.png '{"class": "image-lg", "title": "Product List Page API Flow"}')

### B2B Commerce APIs Used in the Flow

| Purpose                            | HTTP Method | Endpoint                                                                                                                                                                                        |
| ---------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search by category and refinements | GET         | [`/commerce/webstores/{webstoreId}/search/product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm) |

**note:** The endpoint GET [`/commerce/webstores/{webstoreId}/search/products`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm) is also supported. However, prefer the POST-based search API because it supports the complete request body schema, including refinements, field selection, and `includePrices`. The POST approach also avoids URL length limitations that can occur when multiple refinement filters are applied.

### Buyer Journey

**Render Products for a Category**

1. Load the category product listing page.

2. Build the product search request using the following parameters:

   - `categoryId`
   - `page=0`
   - `pageSize=12`
   - No refinements

3. Call the following endpoint to retrieve products for the selected category:

   POST [`/commerce/webstores/{webstoreId}/search/product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)

4. Use the response to render:

   - Product grid
   - Results count
   - Pagination controls

   The response includes:

   - `productsPage`—Contains the product list and total result count

5. Re-run the product search whenever the following values change:

   - `categoryId`
   - Page index
   - Refinement set

**Paginate Product Results**

1. Select Previous or Next to navigate between result pages.

2. Update the page index in the product search request.

3. Call the following endpoint again with the updated page parameter:

   POST [`/commerce/webstores/{webstoreId}/search/product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)

4. Use the updated response to render the next set of products.

### Extend the Flow

- Modify the `pageSize` parameter in the search request to control pagination behavior, and the number of products returned per page.
- To add sorting support, include a `sortRuleId` in the search request body.
- Retrieve available sorting rules using:

  [GET `/commerce/webstores/{webstoreId}/search/sort-rules`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_sort_rules.htm)

## See Also

- [_B2B Commerce Developer Guide_: B2B Commerce Product and Category APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-product-category-apis.html)

<!-- document id=ddad9bd61a566a9f8a256cb50b5ee844681f2734c35f8aba56751fba253575f4 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/product-management-api.md -->

Product Management API

# Product Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/product-management-api/product-management-api-oas-public.yaml)

POS Merchant API to perform CRUD operations on Product objects in the POS system. The APIs do not support field mapping and transformation logic available in CMS.

**Version:** 2.3.4

## Tags

### Product Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/product-management-api/product-management-api-oas-public.yaml)

POS Merchant API to perform CRUD operations on Product objects in the POS system. The APIs do not support field mapping and transformation logic available in CMS.

## Operations

### PUT Update products.

`PUT /merchant/{version}/products`

Operation ID: `updateProducts`. Tags: Product Management API.

Update products. The request must include all properties of the product along with properties to be modified.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ProductRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ProductResponse`.
    

### POST Create products.

`POST /merchant/{version}/products`

Operation ID: `addProducts`. Tags: Product Management API.

Create products. The request must include all properties of a product. Do not use this API to update existing products, as any updates using this API are not effective. Use the PUT API to update existing products.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ProductRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ProductResponse`.
    

### DELETE Delete products.

`DELETE /merchant/{version}/products`

Operation ID: `deleteProducts`. Tags: Product Management API.

Delete products. The request must contain variantGroupID and product IDs. Product IDs can be a single product ID or multiple product IDs separated by commas.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `variantGroupId` (query, string)
*   `productIds` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### PATCH Patch products.

`PATCH /merchant/{version}/products`

Operation ID: `patchProducts`. Tags: Product Management API.

Update products. The request can include any or all properties of a product. Full product details are not needed.

**Limit:** 100 products per request.

If all products are updated successfully, a successful response is returned. Otherwise, error details are provided.

Validation includes:

1.  Empty or null product list
2.  Valid existing product ID
3.  Invalid product class, product title length.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `ProductRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ProductResponse`.
    

## Schemas

### ProductRequest

*   `products` (_array of MerchantProduct_) List of products.

### ProductResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `products` (_array of MerchantProduct_, read-only) List of products.
*   `error` (_boolean_)

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### MerchantProduct

List of products.

*   `productId` (_string_, required) Distinct product ID for each combination of variations, for example, size or color.  
    Example: `3661601595547`.
*   `title` (_string_, required) Product title.  
    Example: `E18PENDANT1`.
*   `description` (_string_, required) Product description.  
    Example: `Number 1 medallion`.
*   `productClass` (_string_, required) Product class of the item.  
    Example: `Merchandise`.
*   `categories` (_array of string_) Merchant categories of the product. A pipe-separated list of category names belongs to this product.  
    Items: Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`.
*   `googleCategory` (_string_) Product categories for Google search.  
    Example: `Accessories > Categories > Jewelry`.
*   `imageUrl` (_string_) Image url of the product.  
    Example: `https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html`.
*   `additionalImageUrls` (_array of string_) Additional image urls of the product.  
    Items: Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`.
*   `condition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`, `NEW, USED, REFURBISHED` . Example: `NEW`.
*   `availability` (_string_) Free text value that provides information about the availability of the product.  
    Example: `Available`.
*   `listPrice` (_number (double)_, required) Listing price of the product.  
    Example: `60`.
*   `salePrice` (_number (double)_, required) Sale price of the product. It can be same as listing price.  
    Example: `60`.
*   `storePrice` (_number (double)_) Store specific price of the product.  
    Example: `55`.
*   `currencyCode` (_string_) ISO currency code.  
    Default: `USD`. Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `brand` (_string_) Brand of the product.  
    Example: `Gucci`.
*   `gtin` (_string_) Product's GTIN. Possible values are: UPC, EAN, JAN, ISBN, and ITF-14.  
    Minimum length: 12. Maximum length: 14. Example: `065100004327`.
*   `mpn` (_string_) Manufacturer part number.  
    Example: `100-440-0.750-3434-A`.
*   `gender` (_string_) Free text to provide gender related to the product.  
    Example: `Unisex`.
*   `ageGroup` (_string_) Free text to provide age group related to the product.  
    Example: `10-45`.
*   `subVariantGroupId` (_string_) ID of the subvariant group.
*   `variantGroupId` (_string_, required) Group ID of the product. All the different variations of the product are grouped together under a single group ID.  
    Example: `E18PENDANT1`.
*   `color` (_string_) Product color.  
    Example: `Silver`.
*   `colorSwatchUrl` (_string_) The image link for color swatches.
*   `size` (_string_) Product size.  
    Example: `M`.
*   `pattern` (_string_) Free text to provide the product pattern.  
    Example: `Oval`.
*   `sku` (_string_) SKU Id of the product. It can be same as product Id and unique per variation of the product.  
    Example: `3661601595547`.
*   `isOnSale` (_boolean_, required) Specifies whether the product is on sale.  
    Example: `false`.
*   `promotionTitle` (_string_, nullable) Promotion title applicable to the product.  
    Example: `Summer22`.
*   `promotionPrice` (_number (double)_, nullable) Discounted price after applying promotion corresponding to the promotion title.  
    Example: `55`.
*   `customString0` (_string_, nullable) Custom field of type String.
*   `customString1` (_string_, nullable) Custom field of type String.
*   `customString2` (_string_, nullable) Custom field of type String.
*   `customString3` (_string_, nullable) Custom field of type String.
*   `customString4` (_string_, nullable) Custom field of type String.
*   `customString5` (_string_, nullable) Custom field of type String.
*   `customString6` (_string_, nullable) Custom field of type String.
*   `customString7` (_string_, nullable) Custom field of type String.
*   `customString8` (_string_, nullable) Custom field of type String.
*   `customString9` (_string_, nullable) Custom field of type String.
*   `customString10` (_string_, nullable) Custom field of type String.
*   `customString11` (_string_, nullable) Custom field of type String.
*   `customString12` (_string_, nullable) Custom field of type String.
*   `customInt0` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customInt1` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customDecimal0` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDecimal1` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDateTime0` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `customDateTime1` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `onlineInventory` (_integer (int32)_, nullable) The current online inventory. You must provide a value if online inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `material` (_string_, nullable) Product material.  
    Example: `Metal`.
*   `manufacturer` (_string_, nullable) Manufacturer of the product.  
    Example: `ABC Jewellers`.
*   `sizeGuideUrl` (_string_, nullable) Image URL of the size guide.
*   `manufacturerDetails` (_string_, nullable) Manufacturer details.
*   `manufacturerLocation` (_string_, nullable) Location of product manufacturer.
*   `productLocation` (_string_, nullable) Product manufacturing location.
*   `banner` (_string_, nullable) Banner text. If provided, banner text is shown on PLP and PDP screens.
*   `availableStores` (_array of string_, nullable) List of stores where the product is available.
*   `lastUpdate` (_string (date-time)_)
*   `storeInventory` (_integer (int32)_, nullable) The current store inventory. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `isVirtual` (_boolean_, nullable) Specifies whether the product is available only in online mode.
*   `multipleGTINs` (_array of string_, nullable) If the product supports multiple GTINs, provide all of them.
*   `storeProductDetails` (_StoreProductDetails_)
*   `onlineAvailableStores` (_array of string_, nullable) List of stores where online products are available.
*   `costPrice` (_number (double)_, nullable) Cost per item.
*   `casePackQuantity` (_integer (int32)_, nullable) Number of items per case pack.
*   `additionalCharges` (_string_, nullable) Additional charges for CA, FR.
*   `casePackID` (_string_, nullable) Identifier for case pack.
*   `availabilityStartTime` (_string (date-time)_, nullable) Start time, when product is visible on POS.
*   `availabilityEndTime` (_string (date-time)_, nullable) End time, when product will not be visible on POS.

### StoreProductDetails

Provide details about products in the store. This includes store-level inventory, store level pricing, store level promotions, etc. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).

*   `storeId` (_string_) Store or warehouse ID.
*   `productId` (_string_) Product ID.
*   `storeInventory` (_integer (int32)_) Product sellable quantity.
*   `storePrice` (_number_) Product price at the store.
*   `storePromoText` (_string_) Product promotion text applicable to this store.
*   `listPrice` (_number_) Product list price.
*   `salesPrice` (_number_) Product sale price.
*   `storePromoBanner` (_string_) Product promotion banner text.
*   `clearanceItems` (_array of ClearanceItem_) Product location within the store.
*   `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders.
*   `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity.
*   `quantityOnHand` (_integer (int32)_) Product quantity on hand.
*   `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store.
*   `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that isn't for sale.
*   `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that isn't for sale.
*   `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that isn't for sale.
*   `fullPriceSerialNumbers` (_array of string_) Full price serial numbers.
*   `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in store.
*   `customString0` (_string_) Custom string attribute of the product for the store.
*   `customString1` (_string_) Custom string attribute of the product for the store.
*   `quantity` (_integer (int32)_)

### ClearanceItem

Product location within the store.

*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `clearancePrice` (_number_)
*   `itemLocationWithinStore` (_string_)
*   `instructionText` (_string_)

<!-- document id=91dbf10d4e0149facfff039484f64779a7c9213a807ccaa272e99b2928f6fff6 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/products.md -->

Products

# Products

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/products/products-oas-v1-public.yaml)

## API Overview

The Products API enables you to build merchandising apps that merchandisers use to add products to catalogs, configure products for your storefront, and manage products in their ecommerce channels.

For more information, see [Products](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_products.html) in the Salesforce B2C Commerce Infocenter.

### Authentication & Authorization

The client managing product information must have access to the Products resource. This API requires a bearer token in the header of the request. The client accessing the API must first authenticate against Account Manager to get the bearer token.

You must include the relevant scope(s) in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Use Cases

#### Add Products

Use the Products API to add new products to a catalog. You can add or update product details like attributes, variations, variation attributes, and images. You can also use the API to change a product’s catalog assignment.

If you are adding products from an external product information management (PIM) system, use the Mulesoft Accelerator component created for Commerce Cloud.

For more detail, see [Variation Groups](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_variation_groups.html) in the Salesforce B2C Commerce Infocenter.

![b2c-commerce-products-screenshot-1.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-1.png)

#### Create & Validate Variation Groups

Use the API to enable a shopper to switch between different variants on a product page. You can group variation products into variation groups or group master products by one or more attributes. The variants within a variation group are linked. Linked variants allow a shopper to switch between different variants.

For more detail, see [Variation Groups](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_variation_groups.html) in the Salesforce B2C Commerce Infocenter.

![b2c-commerce-products-screenshot-2.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-2.png)

#### Search for Variants

Use the Product API to enable merchants to use a set of filtering and sorting criteria to search for variants assigned to a master product, or variation group.

For more detail, see [Product Variations](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_product_variations.html) in the Salesforce B2C Commerce Infocenter.

![b2c-commerce-products-screenshot-3.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-3.png)

#### Manage Product Options

Use the API to view and manage product options for a given product so that optional accessories, upgrades, or services can be sold with the product. For example, a product warranty or monogramming.

For more detail, see [Product Options](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/content/b2c_commerce/topics/products/b2c_product_options.html) in the Salesforce B2C Commerce Infocenter.

![b2c-commerce-products-screenshot-4.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-products-screenshot-4.png)

**Version:** 1.2.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/products/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.products: Product scope READONLY
    *   Scope sfcc.products.rw: Product scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.products: Product scope READONLY
    *   Scope sfcc.products.rw: Product scope

## Operations

### GET Get product information.

`GET /organizations/{organizationId}/products/{productId}`

Operation ID: `getProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Retrieve detailed information about a specific product.

#### Parameters

*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.

#### Responses

*   **200** Retrieved product information successfully.
    
    Media type: `application/json`. Schema: `Product`.
    
    _Example: DataProductExpand_
    
    ```
    {
      "assignedCategories": [
        {
          "catalogId": "apparel-catalog",
          "categoryId": "mens-accessories"
        },
        {
          "catalogId": "storefront-catalog-en",
          "categoryId": "top-seller"
        },
        {
          "catalogId": "storefront-catalog-en",
          "categoryId": "electronics-gaming"
        }
      ],
      "brand": "Apple",
      "classificationCategory": {
        "catalogId": "storefront-catalog-en",
        "categoryId": "top-seller"
      },
      "creationDate": "2019-02-21T22:10:02.000Z",
      "id": "apple-ipod-classic",
      "image": {
        "absUrl": "https://example.com/images/large/ipod-classic-silver.jpg",
        "alt": {
          "default": "Apple iPod Classic, , large"
        },
        "path": "large/ipod-classic-silver.jpg",
        "title": {
          "default": "Apple iPod Classic, "
        }
      },
      "imageGroups": [
        {
          "images": [
            {
              "absUrl": "https://example.com/images/large/ipod-classic-silver.jpg",
              "alt": {
                "default": "Apple iPod Classic, , large"
              },
              "path": "large/ipod-classic-silver.jpg",
              "title": {
                "default": "Apple iPod Classic, "
              }
            }
          ],
          "viewType": "large"
        },
        {
          "images": [
            {
              "absUrl": "https://example.com/images/medium/ipod-classic-silver.jpg",
              "alt": {
                "default": "Apple iPod Classic, , medium"
              },
              "path": "medium/ipod-classic-silver.jpg",
              "title": {
                "default": "Apple iPod Classic, "
              }
            }
          ],
          "viewType": "medium"
        },
        {
          "images": [
            {
              "absUrl": "https://example.com/images/small/ipod-classic-silver.jpg",
              "alt": {
                "default": "Apple iPod Classic, , small"
              },
              "path": "small/ipod-classic-silver.jpg",
              "title": {
                "default": "Apple iPod Classic, "
              }
            }
          ],
          "viewType": "small"
        }
      ],
      "lastModified": "2019-08-28T18:49:09.000Z",
      "localizedTaxClassId": {
        "de": "exempt",
        "default": "standard",
        "en-US": "exempt"
      },
      "longDescription": {
        "default": {
          "markup": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats",
          "source": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats"
        }
      },
      "name": {
        "default": "Apple iPod Classic"
      },
      "onlineFlag": {
        "default": true
      },
      "owningCatalogId": "electronics-catalog",
      "owningCatalogName": {
        "default": "Electronics Master Catalog"
      },
      "pageDescription": {
        "default": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go."
      },
      "pageKeywords": {
        "default": "Apple, iPod, iPod Classic, MP3, Music Player"
      },
      "pageTitle": {
        "default": "Apple iPod Nano"
      },
      "primaryCategories": [
        {
          "catalogId": "apparel-catalog",
          "categoryId": "mens-accessories"
        },
        {
          "catalogId": "storefront-catalog-en",
          "categoryId": "top-seller"
        }
      ],
      "primaryCategoryId": "top-seller",
      "searchable": {
        "default": true
      },
      "shortDescription": {
        "default": {
          "markup": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go.",
          "source": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go."
        }
      },
      "taxClassId": "standard",
      "type": {
        "master": true
      },
      "validFrom": {
        "default": "1998-05-03T00:00:00.000Z",
        "default@SiteGenesis": "1998-05-11T00:00:00.000Z"
      },
      "validTo": {
        "default": "2028-07-03T00:00:00.000Z",
        "default@SiteGenesis": "2028-05-30T00:03:00.000Z"
      },
      "variants": [
        {
          "productId": "apple-ipod-classic-silver-120g",
          "variationValues": {
            "color": "Silver",
            "memorySize": "120 GB"
          }
        },
        {
          "productId": "apple-ipod-classic-black-120g",
          "variationValues": {
            "color": "Black",
            "memorySize": "120 GB"
          }
        }
      ],
      "variationAttributes": [
        {
          "attributeDefinitionId": "color",
          "attributeDefinitionName": {
            "default": "Color"
          },
          "id": "color",
          "name": {
            "default": "Color"
          },
          "shared": true,
          "slicing": false,
          "values": [
            {
              "name": {
                "default": "Silver"
              },
              "position": 1,
              "value": "Silver"
            },
            {
              "name": {
                "default": "Black"
              },
              "position": 2,
              "value": "Black"
            },
            {
              "name": {
                "default": "Purple"
              },
              "position": 3,
              "value": "Purple"
            },
            {
              "name": {
                "default": "Blue"
              },
              "position": 4,
              "value": "Blue"
            },
            {
              "name": {
                "default": "Green"
              },
              "position": 5,
              "value": "Green"
            },
            {
              "name": {
                "default": "Yellow"
              },
              "position": 6,
              "value": "Yellow"
            },
            {
              "name": {
                "default": "Orange"
              },
              "position": 7,
              "value": "Orange"
            },
            {
              "name": {
                "default": "Red"
              },
              "position": 8,
              "value": "Red"
            },
            {
              "name": {
                "default": "Fuscia"
              },
              "position": 9,
              "value": "Fuscia"
            }
          ],
          "variationAttributeType": "string"
        },
        {
          "attributeDefinitionId": "memorySize",
          "attributeDefinitionName": {
            "default": "Memory Size"
          },
          "id": "memorySize",
          "name": {
            "default": "Memory Size"
          },
          "shared": true,
          "slicing": false,
          "values": [
            {
              "name": {
                "default": "1 GB"
              },
              "position": 1,
              "value": "1 GB"
            },
            {
              "name": {
                "default": "2 GB"
              },
              "position": 2,
              "value": "2 GB"
            },
            {
              "name": {
                "default": "8 GB"
              },
              "position": 3,
              "value": "8 GB"
            },
            {
              "name": {
                "default": "16 GB"
              },
              "position": 4,
              "value": "16 GB"
            },
            {
              "name": {
                "default": "32 GB"
              },
              "position": 5,
              "value": "32 GB"
            },
            {
              "name": {
                "default": "120 GB"
              },
              "position": 6,
              "value": "120 GB"
            }
          ],
          "variationAttributeType": "string"
        }
      ]
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getProduct400_
    
    ```
    {
      "title": "Unqueryable Field",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "detail": "The field 'link' can't be queried.",
      "field": "link"
    }
    ```
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getProduct401_
    
    ```
    {
      "title": "Invalid Access Token",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token",
      "detail": "The request is unauthorized, the access token is invalid.",
      "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp"
    }
    ```
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getProduct404_
    
    ```
    {
      "title": "Product Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found",
      "detail": "No product with ID '1585183329877' could be found.",
      "productId": "1585183329877"
    }
    ```
    

### PUT Create or overwrite a product with provided data.

`PUT /organizations/{organizationId}/products/{productId}`

Operation ID: `createProduct`. Security: AmOAuth2 (sfcc.products.rw).

Create a product using the information provided. If a product with the same unique identifier exists, it is overwritten.

#### Parameters

*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Product`.

_Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._

#### Responses

*   **200** Product was updated successfully.
    
    Media type: `application/json`. Schema: `Product`.
    
    _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._
    
*   **201** Product was created successfully.
    
    Media type: `application/json`. Schema: `Product`.
    
    _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### DELETE Deletes the product by ID.

`DELETE /organizations/{organizationId}/products/{productId}`

Operation ID: `deleteProduct`. Security: AmOAuth2 (sfcc.products.rw).

Permanently remove a product by ID.

#### Parameters

*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted the product successfully.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PATCH Partially update fields of an existing product.

`PATCH /organizations/{organizationId}/products/{productId}`

Operation ID: `updateProduct`. Security: AmOAuth2 (sfcc.products.rw).

Update a product using the information provided. Fields that can be updated: name, pageDescription, longDescription, pageTitle, pageKeywords, brand, ean, upc, manufactureSku, manufactureName, searchable, unit, searchable, onlineFlag, defaultVariantId. Custom attributes are used to extend a standard Product system object. This endpoint can be used to update custom attribute values for a particular product SKU. If you try to update a non-existent custom attribute, the request won't fail, but no changes are made and the attribute is not created.

#### Parameters

*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Product`.

_Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._

#### Responses

*   **200** Updated the product successfully.
    
    Media type: `application/json`. Schema: `Product`.
    
    _Example DataProductExpand: same as GET /organizations/{organizationId}/products/{productId} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### POST Search product variations using complex queries and filters.

`POST /organizations/{organizationId}/products/{productId}/variant-search`

Operation ID: `searchProductVariations`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Search product variations for master product or variation group product. The query attribute specifies a complex query that can be used to narrow down the search.

This is the list of searchable attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| productId | String |
| name | String |
| online | SiteSpecific Boolean |
| inStock | Boolean |
| searchable | SiteSpecific Boolean |
| ats - Available quantity to sell | Double |
| variationAttribute.ATTRIBUTE\_ID (Ex:variation\_attribute.color) | String |

Sortable Fields:

| Attribute | Type |
| --- | --- |
| id | String |
| productId | String |
| name | String |
| online | SiteSpecific Boolean |
| inStock | Boolean |
| searchable | SiteSpecific Boolean |
| ats - Available quantity to sell | Double |

Note: The calculated value of "online" and "searchable" is used in the search/sort. A search/sort by the site-specific attributes require the Site ID query parameter to be set. They are "online", "inStock", "searchable" and "ats". We assume that every field that starts with variationAttribute. is searchable and dot is followed by "ATTRIBUTE\_ID".

The list of expansions to retrieve product information. The expand values available are:

*   \_base - Basic product information is retrieved. This expand is included by default.
    
*   all - All product information, including the following properties are retrieved:
    
    *   image
    *   price - siteId must be provided to see this property
    *   priceCurrency - siteId must be provided to see this property
*   availability - Information related to the availability of the product variation. This expand is not included by default.
    
    *   ats - siteId must be provided to see this property
    *   inStock - siteId must be provided to see this property
    *   online - siteId must be provided to see this property
    *   searchable
*   variations - Information related to product variations is retrieved. This expand is included by default.
    
*   attributes - Information related to product variation attributes is retrieved. This expand is not included by default.
    

#### Parameters

*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.

#### Request body (required)

Media type: `application/json`. Schema: `VariantSearchRequest`.

_Example: VariantSearchRequestBody_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "id"
      ],
      "searchPhrase": "ipod"
    }
  },
  "expand": [
    "variations"
  ]
}
```

#### Responses

*   **200** Search results returned.
    
    Media type: `application/json`. Schema: `VariantSearchResult`.
    
    _Example: VariantSearchResult_
    
    ```
    {
      "limit": 2,
      "hits": [
        {
          "defaultProductVariation": false,
          "productId": "apple-ipod-classic-silver-120g",
          "variationValues": {
            "color": "Silver",
            "memorySize": "120 GB"
          }
        },
        {
          "defaultProductVariation": false,
          "productId": "apple-ipod-classic-black-120g",
          "variationValues": {
            "color": "Black",
            "memorySize": "120 GB"
          }
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id"
          ],
          "searchPhrase": "ipod"
        }
      },
      "offset": 0,
      "total": 2
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET List all variation groups of a product.

`GET /organizations/{organizationId}/products/{masterProductId}/variation-groups`

Operation ID: `getVariationGroupsForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

List all variation groups of a product.

#### Parameters

*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Get VariationGroups for a product was successful.
    
    Media type: `application/json`. Schema: `VariationGroups`.
    
    _Example: VariationGroupsResult_
    
    ```
    {
      "limit": 1,
      "data": [
        {
          "productId": "apple-ipod-classic-1",
          "variationValues": {
            "color": "Silver",
            "memorySize": "120 GB"
          }
        }
      ],
      "offset": 0,
      "total": 1
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Get a specific variation group.

`GET /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}`

Operation ID: `getVariationGroupForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Read a variation group for a product.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.

#### Responses

*   **200** Get VariationGroup by Id for a product was successful.
    
    Media type: `application/json`. Schema: `VariationGroup`.
    
    _Example: VariationGroupsIdResult_
    
    ```
    {
      "productId": "apple-ipod-classic-1",
      "variationValues": {
        "color": "Silver",
        "memorySize": "120 GB"
      }
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PUT Assign or create a variation group for a product.

`PUT /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}`

Operation ID: `assignVariationGroupToMasterProduct`. Security: AmOAuth2 (sfcc.products.rw).

Assign a variation group for a product. If the variation group product does not initially exist, one is created using the body passed in.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `VariationGroup`.

_Example: VariationGroupsIdRequestBody_

```
{
  "orderable": true,
  "price": 500,
  "productId": "apple-ipod-classic-1",
  "variationValues": {
    "color": "Silver",
    "memorySize": "120 GB"
  }
}
```

#### Responses

*   **200** Successfully assigned a variation group for given product.
    
    Media type: `application/json`. Schema: `VariationGroup`.
    
    _Example: VariationGroupsIdResult_
    
    ```
    {
      "productId": "apple-ipod-classic-1",
      "variationValues": {
        "color": "Silver",
        "memorySize": "120 GB"
      }
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### DELETE Unassign a variation group (product not deleted).

`DELETE /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}`

Operation ID: `unassignVariationGroupFromMasterProduct`. Security: AmOAuth2 (sfcc.products.rw).

Unassign a variation group product from a product. The variation group product is not deleted: it remains as a typical product after unassign.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted the variation group successfully.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PATCH Update an existing variation group.

`PATCH /organizations/{organizationId}/products/{masterProductId}/variation-groups/{id}`

Operation ID: `updateVariationGroupForMasterProduct`. Security: AmOAuth2 (sfcc.products.rw).

Update a variation group for a product master.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `VariationGroup`.

_Example: VariationGroupsIdRequestBody_

```
{
  "orderable": true,
  "price": 500,
  "productId": "apple-ipod-classic-1",
  "variationValues": {
    "color": "Silver",
    "memorySize": "120 GB"
  }
}
```

#### Responses

*   **200** Update was successful.
    
    Media type: `application/json`. Schema: `VariationGroup`.
    
    _Example: VariationGroupsIdResult_
    
    ```
    {
      "productId": "apple-ipod-classic-1",
      "variationValues": {
        "color": "Silver",
        "memorySize": "120 GB"
      }
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET List all variations of a master product.

`GET /organizations/{organizationId}/products/{masterProductId}/variations`

Operation ID: `getVariationsForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

List all variations of a master product.

#### Parameters

*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Get variation by ID successful.
    
    Media type: `application/json`. Schema: `Variants`.
    
    _Example: getProduct400_
    
    ```
    {
      "limit": 4,
      "data": [
        {
          "productId": "apple-ipod-classic-silver-120g"
        },
        {
          "productId": "apple-ipod-classic-black-120g"
        },
        {
          "productId": "apple-ipod-classic-2"
        },
        {
          "productId": "apple-ipod-classic-blue-32g"
        }
      ],
      "offset": 0,
      "total": 4
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Get details of a specific variation.

`GET /organizations/{organizationId}/products/{masterProductId}/variations/{id}`

Operation ID: `getVariationForMasterProduct`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Get details of a specific variation.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.

#### Responses

*   **200** Get variation by ID successful.
    
    Media type: `application/json`. Schema: `Variant`.
    
    _Example: VariationsIdResult_
    
    ```
    {
      "defaultProductVariation": false,
      "productId": "apple-ipod-classic-blue-32g",
      "variationValues": {
        "color": "Blue",
        "memorySize": "32 GB"
      }
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PUT Assign a variation to a master product (creates if not exists).

`PUT /organizations/{organizationId}/products/{masterProductId}/variations/{id}`

Operation ID: `assignVariationForMasterProduct`. Security: AmOAuth2 (sfcc.products.rw).

Assign a variation for a product master. If the variation product does not initially exist, one is created using the body that is passed.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Variant`.

_Example: VariationsIdRequestBody_

```
{
  "orderable": true,
  "price": 500,
  "productId": "apple-ipod-classic-blue-32g",
  "variationValues": {
    "color": "Blue",
    "memorySize": "32 GB"
  }
}
```

#### Responses

*   **200** Updated the variation product successfully.
    
    Media type: `application/json`. Schema: `Variant`.
    
    _Example: VariationsIdResult_
    
    ```
    {
      "defaultProductVariation": false,
      "productId": "apple-ipod-classic-blue-32g",
      "variationValues": {
        "color": "Blue",
        "memorySize": "32 GB"
      }
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### DELETE Unassign a variation from a product (does not delete it).

`DELETE /organizations/{organizationId}/products/{masterProductId}/variations/{id}`

Operation ID: `unassignVariationFromMasterProduct`. Security: AmOAuth2 (sfcc.products.rw).

Unassign a variation product from a product. The variation product is not deleted: it remains as a typical product after unassign.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted the variation group successfully.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PATCH Update a specific product variation.

`PATCH /organizations/{organizationId}/products/{masterProductId}/variations/{id}`

Operation ID: `updateVariationForMasterProduct`. Security: AmOAuth2 (sfcc.products.rw).

Update a variation for a product.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `masterProductId` (path, string, required) The ID of the master product that contains the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `Variant`.

_Example: VariationsIdRequestBody_

```
{
  "orderable": true,
  "price": 500,
  "productId": "apple-ipod-classic-blue-32g",
  "variationValues": {
    "color": "Blue",
    "memorySize": "32 GB"
  }
}
```

#### Responses

*   **200** Variation updated successfully.
    
    Media type: `application/json`. Schema: `Variant`.
    
    _Example: VariationsIdResult_
    
    ```
    {
      "defaultProductVariation": false,
      "productId": "apple-ipod-classic-blue-32g",
      "variationValues": {
        "color": "Blue",
        "memorySize": "32 GB"
      }
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Retrieve product options for a product.

`GET /organizations/{organizationId}/products/{productId}/product-options`

Operation ID: `getProductOptions`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Read local and shared product options for a specified product.

#### Parameters

*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Retrieved product options successfully.
    
    Media type: `application/json`. Schema: `ProductOptions`.
    
    _Example: ProductOptionsResult_
    
    ```
    {
      "limit": 1,
      "data": [
        {
          "id": "digitalCameraWarranty",
          "values": [
            {
              "id": "001",
              "optionPrices": [
                {
                  "currencyMnemonic": "USD",
                  "value": 9.99
                }
              ],
              "value": {
                "default": "1 Year Warranty"
              }
            },
            {
              "id": "003",
              "optionPrices": [
                {
                  "currencyMnemonic": "USD",
                  "value": 29.99
                }
              ],
              "value": {
                "default": "5 Year Warranty"
              }
            },
            {
              "id": "000",
              "optionPrices": [
                {
                  "currencyMnemonic": "USD",
                  "value": 39.99
                }
              ],
              "value": {
                "default": "None"
              }
            },
            {
              "id": "002",
              "optionPrices": [
                {
                  "currencyMnemonic": "USD",
                  "value": 49.99
                }
              ],
              "value": {
                "default": "3 Year Warranty"
              }
            }
          ]
        }
      ],
      "offset": 0,
      "total": 1
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Retrieve a specific product option.

`GET /organizations/{organizationId}/products/{productId}/product-options/{id}`

Operation ID: `getProductOption`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Read a local or shared product option for a specified product.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    

#### Responses

*   **200** Retrieved product options successfully.
    
    Media type: `application/json`. Schema: `ProductOption`.
    
    _Example: ProductOptionsIdResult_
    
    ```
    {
      "customName": {
        "default": "My Option"
      },
      "description": {
        "default": "Description for my option."
      },
      "id": "my-option",
      "image": {
        "absUrl": "https://example.com/on/demandware.static/-/Sites-XMaster/default/aaaaaaaabbbbbbbbbabababba/option.jpg",
        "disBaseUrl": "https://example.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-XMaster/default/aaaaaaaabbbbbbbbbabababba/option.jpg",
        "path": "option.jpg"
      },
      "name": "option",
      "shared": false,
      "sortingMode": "byoptionprice"
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PUT Create or bind a product option.

`PUT /organizations/{organizationId}/products/{productId}/product-options/{id}`

Operation ID: `createProductOption`. Security: AmOAuth2 (sfcc.products.rw).

Creates a local product option using the information provided or binds a shared product option to the product.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ProductOption`.

_Example: ProductOptionsIdRequestBody_

```
{
  "id": "my-option",
  "customName": {
    "default": "My Option"
  },
  "description": {
    "default": "Description for my option."
  },
  "image": {
    "path": "option.jpg"
  }
}
```

#### Responses

*   **200** Updated product option successfully.
    
    Media type: `application/json`. Schema: `ProductOption`.
    
    _Example ProductOptionsIdResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{id} 200 response._
    
*   **201** Created or binded product option successfully.
    
    Media type: `application/json`. Schema: `ProductOption`.
    
    _Example ProductOptionsIdResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{id} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### DELETE Delete or unbind a product option.

`DELETE /organizations/{organizationId}/products/{productId}/product-options/{id}`

Operation ID: `deleteProductOption`. Security: AmOAuth2 (sfcc.products.rw).

Delete a local product option or unbind a shared product option from the product.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted product option successfully.
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PATCH Update a product option.

`PATCH /organizations/{organizationId}/products/{productId}/product-options/{id}`

Operation ID: `updateProductOption`. Security: AmOAuth2 (sfcc.products.rw).

Update a local product option with the information provided.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ProductOption`.

_Example: ProductOptionsIdRequestBody_

```
{
  "id": "my-option",
  "customName": {
    "default": "My Option"
  },
  "description": {
    "default": "Description for my option."
  },
  "image": {
    "path": "option.jpg"
  }
}
```

#### Responses

*   **200** Updated product option successfully.
    
    Media type: `application/json`. Schema: `ProductOption`.
    
    _Example ProductOptionsIdResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{id} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Retrieve a product option value.

`GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}`

Operation ID: `getProductOptionValue`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Read a local product option value for a specified product.

#### Parameters

*   `productId` (path, ProductId, required)
*   `optionId` (path, string, required) The ID of the local product option.  
    Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully retrieved product option value.
    
    Media type: `application/json`. Schema: `ProductOptionValue`.
    
    _Example: ProductOptionsValuesResult_
    
    ```
    {
      "defaultProductOptionValue": false,
      "id": "value1",
      "optionPrices": [
        {
          "currencyMnemonic": "USD",
          "value": 100
        }
      ],
      "skuExtension": "s10",
      "value": {
        "default": "value 1",
        "en-US": "value 1(en-US)",
        "en": "value 1(en)"
      }
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PUT Create a product option value.

`PUT /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}`

Operation ID: `createProductOptionValue`. Security: AmOAuth2 (sfcc.products.rw).

Create a local product option value using the information provided.

#### Parameters

*   `productId` (path, ProductId, required)
*   `optionId` (path, string, required) The ID of the local product option.  
    Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ProductOptionValue`.

_Example: ProductOptionsValuesRequestBody_

```
{
  "id": "my-option",
  "value": {
    "default": "value 1",
    "en": "value 1(en)",
    "en-US": "value 1(en-US)"
  },
  "optionPrices": [
    {
      "currencyMnemonic": "USD",
      "value": 100
    }
  ],
  "skuExtension": "s10"
}
```

#### Responses

*   **200** Updated product option value successfully.
    
    Media type: `application/json`. Schema: `ProductOptionValue`.
    
    _Example ProductOptionsValuesResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} 200 response._
    
*   **201** Created product option value successfully.
    
    Media type: `application/json`. Schema: `ProductOptionValue`.
    
    _Example ProductOptionsValuesResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### DELETE Delete a product option value.

`DELETE /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}`

Operation ID: `deleteProductOptionValue`. Security: AmOAuth2 (sfcc.products.rw).

Delete a local product option value by ID.

#### Parameters

*   `productId` (path, ProductId, required)
*   `optionId` (path, string, required) The ID of the local product option.  
    Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted product option value successfully.
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PATCH Update a product option value.

`PATCH /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id}`

Operation ID: `updateProductOptionValue`. Security: AmOAuth2 (sfcc.products.rw).

Update a local product option value using the information provided.

#### Parameters

*   `productId` (path, ProductId, required)
*   `optionId` (path, string, required) The ID of the local product option.  
    Minimum length: 1. Maximum length: 256. Example: `sony-ps3-bundle`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `ProductOptionValue`.

_Example ProductOptionsValuesRequestBody: same as PUT /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} request._

#### Responses

*   **200** Product option value updated successfully.
    
    Media type: `application/json`. Schema: `ProductOptionValue`.
    
    _Example ProductOptionsValuesResult: same as GET /organizations/{organizationId}/products/{productId}/product-options/{optionId}/values/{id} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Retrieve a variation attribute value.

`GET /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}`

Operation ID: `getVariationAttributeValue`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Get product variation attribute information.

#### Parameters

*   `productId` (path, ProductId, required)
*   `attributeId` (path, string, required) The variation attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `siteId` (query, SiteId) The site context.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Retrieved variation attribute value successfully.
    
    Media type: `application/json`. Schema: `VariationAttributeValue`.
    
    _Example: VariationAttributeValuesIdResult_
    
    ```
    {
      "description": {
        "default": "desc of 8 (default)",
        "en-US": "desc of 8 (en-US)",
        "en": "desc of 8 (en)"
      },
      "position": 1,
      "value": "8"
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PUT Create a variation attribute value.

`PUT /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}`

Operation ID: `createVariationAttributeValue`. Security: AmOAuth2 (sfcc.products.rw).

Create a product variation attribute value.

#### Parameters

*   `productId` (path, ProductId, required)
*   `attributeId` (path, string, required) The variation attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `VariationAttributeValue`.

_Example: VariationAttributeValuesIdRequestBody_

```
{
  "value": "8",
  "description": {
    "default": "desc of 8 (default)",
    "en": "desc of 8 (en)",
    "en-US": "desc of 8 (en-US)"
  }
}
```

#### Responses

*   **200** Created product variation attribute value successfully.
    
    Media type: `application/json`. Schema: `VariationAttributeValue`.
    
    _Example: VariationAttributeValuesIdResult_
    
    ```
    {
      "description": {
        "default": "desc of 8 (default)",
        "en-US": "desc of 8 (en-US)",
        "en": "desc of 8 (en)"
      },
      "position": 1,
      "value": "8"
    }
    ```
    
*   **201** Created product variation attribute value successfully.
    
    Media type: `application/json`. Schema: `VariationAttributeValue`.
    
    _Example: VariationAttributeValuesIdResult_
    
    ```
    {
      "description": {
        "default": "desc of 8 (default)",
        "en-US": "desc of 8 (en-US)",
        "en": "desc of 8 (en)"
      },
      "position": 1,
      "value": "8"
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### DELETE Delete a variation attribute value.

`DELETE /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}`

Operation ID: `deleteVariationAttributeValue`. Security: AmOAuth2 (sfcc.products.rw).

Delete the variation attribute value of a variation attribute bound to a product.

#### Parameters

*   `productId` (path, ProductId, required)
*   `attributeId` (path, string, required) The variation attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted variation attribute value successfully.
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PATCH Update a variation attribute value.

`PATCH /organizations/{organizationId}/products/{productId}/variation-attributes/{attributeId}/values/{id}`

Operation ID: `updateVariationAttributeValue`. Security: AmOAuth2 (sfcc.products.rw).

Update the variation attribute value of a variation attribute of a product.

#### Parameters

*   `productId` (path, ProductId, required)
*   `attributeId` (path, string, required) The variation attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `VariationAttributeValue`.

_Example: VariationAttributeValuesIdRequestBody_

```
{
  "value": "8",
  "description": {
    "default": "desc of 8 (default)",
    "en": "desc of 8 (en)",
    "en-US": "desc of 8 (en-US)"
  }
}
```

#### Responses

*   **200** Updated variation attribute value successfully.
    
    Media type: `application/json`. Schema: `VariationAttributeValue`.
    
    _Example: VariationAttributeValuesIdResult_
    
    ```
    {
      "description": {
        "default": "desc of 8 (default)",
        "en-US": "desc of 8 (en-US)",
        "en": "desc of 8 (en)"
      },
      "position": 1,
      "value": "8"
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Retrieve variation attributes of a product.

`GET /organizations/{organizationId}/products/{productId}/variation-attributes`

Operation ID: `getVariationAttributes`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Read variation attributes of a product of type variant, variation master, or variation group.

#### Parameters

*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Retrieved the list of VariationAttributes for the product ID successfully.
    
    Media type: `application/json`. Schema: `VariationAttributes`.
    
    _Example: VariationAttributesResult_
    
    ```
    {
      "limit": 3,
      "data": [
        {
          "attributeDefinitionId": "color",
          "attributeDefinitionName": {
            "default": "Color"
          },
          "id": "color",
          "name": {
            "default": "Color"
          },
          "shared": true,
          "slicing": false,
          "values": [
            {
              "name": {
                "default": "Silver"
              },
              "position": 1,
              "value": "Silver"
            },
            {
              "name": {
                "default": "Black"
              },
              "position": 2,
              "value": "Black"
            },
            {
              "name": {
                "default": "Purple"
              },
              "position": 3,
              "value": "Purple"
            },
            {
              "name": {
                "default": "Blue"
              },
              "position": 4,
              "value": "Blue"
            },
            {
              "name": {
                "default": "Green"
              },
              "position": 5,
              "value": "Green"
            },
            {
              "name": {
                "default": "Yellow"
              },
              "position": 6,
              "value": "Yellow"
            },
            {
              "name": {
                "default": "Orange"
              },
              "position": 7,
              "value": "Orange"
            },
            {
              "name": {
                "default": "Red"
              },
              "position": 8,
              "value": "Red"
            },
            {
              "name": {
                "default": "Fuscia"
              },
              "position": 9,
              "value": "Fuscia"
            }
          ],
          "variationAttributeType": "string"
        },
        {
          "attributeDefinitionId": "memorySize",
          "attributeDefinitionName": {
            "default": "Memory Size"
          },
          "id": "memorySize",
          "name": {
            "default": "Memory Size"
          },
          "shared": true,
          "slicing": false,
          "values": [
            {
              "name": {
                "default": "1 GB"
              },
              "position": 1,
              "value": "1 GB"
            },
            {
              "name": {
                "default": "2 GB"
              },
              "position": 2,
              "value": "2 GB"
            },
            {
              "name": {
                "default": "8 GB"
              },
              "position": 3,
              "value": "8 GB"
            },
            {
              "name": {
                "default": "16 GB"
              },
              "position": 4,
              "value": "16 GB"
            },
            {
              "name": {
                "default": "32 GB"
              },
              "position": 5,
              "value": "32 GB"
            },
            {
              "name": {
                "default": "120 GB"
              },
              "position": 6,
              "value": "120 GB"
            }
          ],
          "variationAttributeType": "string"
        },
        {
          "attributeDefinitionId": "size",
          "attributeDefinitionName": {
            "default": "Size"
          },
          "id": "screenSize",
          "name": {
            "default": "Size"
          },
          "shared": false,
          "slicing": false,
          "values": [
            {
              "description": {
                "default": "desc of 8 (default)",
                "en-US": "desc of 8 (en-US)",
                "en": "desc of 8 (en)"
              },
              "position": 1,
              "value": "8"
            }
          ],
          "variationAttributeType": "string"
        }
      ],
      "offset": 0,
      "total": 3
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Retrieve a specific variation attribute.

`GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id}`

Operation ID: `getVariationAttribute`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Get variation attribute information only for master product.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Retrieved the VariationAttribute for the product ID successfully.
    
    Media type: `application/json`. Schema: `VariationAttribute`.
    
    _Example: VariationAttributeResult_
    
    ```
    {
      "attributeDefinitionId": "size",
      "attributeDefinitionName": {
        "default": "Size"
      },
      "id": "screenSize",
      "name": {
        "default": "Size"
      },
      "shared": false,
      "slicing": false,
      "variationAttributeType": "string"
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PUT Create a variation attribute.

`PUT /organizations/{organizationId}/products/{productId}/variation-attributes/{id}`

Operation ID: `createVariationAttribute`. Security: AmOAuth2 (sfcc.products.rw).

Create a variation attribute using the information provided.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `VariationAttribute`.

_Example: VariationAttributeRequestBody_

```
{
  "attributeDefinitionId": "size",
  "attributeDefinitionName": {
    "default": "Screen Size"
  }
}
```

#### Responses

*   **200** Created variation attribute successfully.
    
    Media type: `application/json`. Schema: `VariationAttribute`.
    
    _Example VariationAttributeResult: same as GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id} 200 response._
    
*   **201** Created variation attribute successfully.
    
    Media type: `application/json`. Schema: `VariationAttribute`.
    
    _Example VariationAttributeResult: same as GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### DELETE Remove a variation attribute.

`DELETE /organizations/{organizationId}/products/{productId}/variation-attributes/{id}`

Operation ID: `deleteVariationAttribute`. Security: AmOAuth2 (sfcc.products.rw).

Delete the variation attribute by ID.

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Deleted variation attribute successfully.
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### PATCH Update a variation attribute.

`PATCH /organizations/{organizationId}/products/{productId}/variation-attributes/{id}`

Operation ID: `updateVariationAttribute`. Security: AmOAuth2 (sfcc.products.rw).

Update the variation attribute with the specified information. name slicing

#### Parameters

*   `id` (path, string, required) The ID of the variation attribute to create.  
    Minimum length: 1. Maximum length: 256. Example: `colour`.
*   `productId` (path, ProductId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `VariationAttribute`.

_Example: VariationAttributeRequestBody_

```
{
  "attributeDefinitionId": "size",
  "attributeDefinitionName": {
    "default": "Screen Size"
  }
}
```

#### Responses

*   **200** Updated variation attribute successfully.
    
    Media type: `application/json`. Schema: `VariationAttribute`.
    
    _Example VariationAttributeResult: same as GET /organizations/{organizationId}/products/{productId}/variation-attributes/{id} 200 response._
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    
*   **404** Resource requested not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct404: same as GET /organizations/{organizationId}/products/{productId} 404 response._
    

### GET Get allowed attributes, values, and operators for creating rule-based categorization conditions.

`GET /organizations/{organizationId}/categorization-attribute-definitions`

Operation ID: `getCategorizationAttributeDefinitions`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Get the list of allowed attributes, values, and operators for creating rule-based categorization conditions.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Responses

*   **200** Categorization attribute definitions retrieved successfully.
    
    Media type: `application/json`. Schema: `CategorizationAttributeDefinitionsResult`.
    
    _Example: CategorizationAttributeDefinitionResult_
    
    ```
    {
      "limit": 1,
      "data": [
        {
          "id": "ProductType",
          "attributeName": "Categorization Product Type",
          "allowedOperators": [
            "equals",
            "not_equals"
          ],
          "allowedValues": [
            "Item",
            "Master",
            "BundledProduct",
            "ProductSet",
            "SetProduct",
            "VariationGroup",
            "VariationProduct"
          ],
          "allowedDisplayValues": [
            "Item",
            "Master",
            "BundledProduct",
            "ProductSet",
            "SetProduct",
            "VariationGroup",
            "VariationProduct"
          ],
          "attributeType": "categorization",
          "valueType": "enum-of-string"
        },
        {
          "id": "CategoryId",
          "attributeName": "Categorization Category Id",
          "allowedOperators": [
            "equals"
          ],
          "attributeType": "categorization",
          "valueType": "string"
        },
        {
          "id": "OwningCatalogId",
          "attributeName": "Categorization Owning Catalog Id",
          "allowedOperators": [
            "equals"
          ],
          "attributeType": "categorization",
          "valueType": "string"
        },
        {
          "id": "brand",
          "attributeName": "Brand",
          "allowedOperators": [
            "equals",
            "not_equals",
            "contains",
            "starts_with",
            "is_defined",
            "is_not_defined",
            "is_one_of",
            "not_one_of"
          ],
          "attributeType": "system",
          "valueType": "string"
        },
        {
          "id": "RelevanceAttribute1",
          "attributeName": "RelevanceAttribute1",
          "allowedOperators": [
            "equals",
            "not_equals",
            "contains",
            "starts_with",
            "is_defined",
            "is_not_defined",
            "is_one_of",
            "not_one_of"
          ],
          "attributeType": "custom",
          "valueType": "string"
        }
      ],
      "total": 5
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    

### POST Search products.

`POST /organizations/{organizationId}/product-search`

Operation ID: `searchProducts`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Search for products. The query attribute specifies a complex query that can be used to narrow down the search. Attributes are grouped into different buckets.

The following is a list of searchable attributes with their corresponding buckets:

Main:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| online | SiteSpecific Boolean |
| searchable | SiteSpecific Boolean |
| validFrom | SiteSpecfic DateTime |
| validTo | SiteSpecfic DateTime |
| type | ProductType |
| creationDate | DateTime |
| lastModified | DateTime |

Catalog:

| Attribute | Type |
| --- | --- |
| catalogId | String |

Category:

| Attribute | Type |
| --- | --- |
| categoryId | String |

Special:

type - {"item", "set, "bundle", "master", "partOfProductSet", "bundled", "variant", "variationGroup", "option", "retailSet", "partOfRetailSet"}

The sortable properties are:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| creationDate | DateTime |

Note that catalogId is the ID of the catalog to which products are assigned

Only attributes in the same bucket can be joined using a disjunction (OR). For instance, when joining id and catalogId, only a conjunction is allowed (AND), whereas id and searchable can be joined using a disjunction because they are in the same bucket. If an attribute is used in a disjunction (OR) that violates this rule, an exception is thrown. The product search retrieves additional properties of the product when expansions are used.

The available expand attribute values are:

*   ‘all' retrieves all product properties. This is the default when no expand value is included in the request.
    
*   'none' retrieves no expansion properties.
    
*   ‘availability' retrieves the following properties:
    
    *   ats
    *   inStock
    *   online
*   ‘categories' retrieves the assignedCategories property.
    
*   ‘images' retrieves the image property.
    
*   ‘allImages' when used with images retrieves the following properties:
    
    *   image
    *   imageGroups
*   'prices' retrieves the following properties:
    
    *   price
    *   priceCurrency
*   ‘sets' retrieves the following properties:
    
    *   setProducts
    *   productSets
*   ‘bundles' retrieves the following properties:
    
    *   productBundles
    *   bundledProduct

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.

#### Request body (required)

Media type: `application/json`. Schema: `ProductSearchRequest`.

_Example: ProductSearchRequestBody_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "id"
      ],
      "searchPhrase": "apple-ipod-classic"
    }
  }
}
```

#### Responses

*   **200** Product search completed successfully.
    
    Media type: `application/json`. Schema: `ProductSearchResult`.
    
    _Example: ProductSearchResult_
    
    ```
    {
      "limit": 2,
      "hits": [
        {
          "brand": "Apple",
          "creationDate": "2019-02-21T22:10:02.000Z",
          "id": "apple-ipod-classic",
          "lastModified": "2019-09-17T19:13:39.000Z",
          "longDescription": {
            "default": {
              "markup": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats",
              "source": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats"
            }
          },
          "name": {
            "default": "Apple iPod Classic"
          },
          "onlineFlag": {
            "default": true
          },
          "owningCatalogId": "electronics-catalog",
          "owningCatalogName": {
            "default": "Electronics Master Catalog"
          },
          "pageDescription": {
            "default": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go."
          },
          "pageKeywords": {
            "default": "Apple, iPod, iPod Classic, MP3, Music Player"
          },
          "pageTitle": {
            "default": "Apple iPod Nano"
          },
          "searchable": {
            "default": true
          },
          "shortDescription": {
            "default": {
              "markup": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go.",
              "source": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go."
            }
          },
          "type": {
            "master": true
          }
        },
        {
          "brand": "Apple",
          "creationDate": "2019-09-04T16:07:43.000Z",
          "id": "apple-ipod-classic-1",
          "lastModified": "2019-09-04T16:19:03.000Z",
          "longDescription": {
            "default": {
              "markup": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats",
              "source": "Supports MP3, MP3 VBR, AAC, Protected AAC, Audible 2, 3 and 4, Apple Lossless and AIFF audio formats; also supports JPEG, BMP, GIF, TIFF, PSD (Mac only) and PNG image formats and H.264 (high-definition), MPEG-4 and MPEG-4 video formats"
            }
          },
          "name": {
            "default": "Apple iPod Classic"
          },
          "onlineFlag": {
            "default": false
          },
          "owningCatalogId": "electronics-catalog",
          "owningCatalogName": {
            "default": "Electronics Master Catalog"
          },
          "pageDescription": {
            "default": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go."
          },
          "pageKeywords": {
            "default": "Apple, iPod, iPod Classic, MP3, Music Player"
          },
          "pageTitle": {
            "default": "Apple iPod Nano"
          },
          "searchable": {
            "default": false
          },
          "shortDescription": {
            "default": {
              "markup": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go.",
              "source": "This iPod delivers everything you love about iPod with added features all wrapped in a tiny 4.9 oz. package. With 120GB of storage and up to 36 hours music playback, iPod classic lets you enjoy up to 30,000 songs or 150 hours of video — or a combination — wherever you go."
            }
          },
          "type": {
            "variationGroup": true,
            "master": false
          }
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id"
          ],
          "searchPhrase": "apple-ipod-classic"
        }
      },
      "offset": 0,
      "total": 2
    }
    ```
    
*   **400** Bad Request. Thrown when a specified expand parameter value is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct400: same as GET /organizations/{organizationId}/products/{productId} 400 response._
    
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getProduct401: same as GET /organizations/{organizationId}/products/{productId} 401 response._
    

### POST Search for unassigned products.

`POST /organizations/{organizationId}/unassigned-product-search`

Operation ID: `searchUnassignedProducts`. Security: AmOAuth2 (sfcc.products, sfcc.products.rw).

Search for products that are not assigned to a specific category within a catalog. This endpoint helps identify products that exist in the catalog but are not categorized under the specified category.

The query attribute specifies a complex query that can be used to narrow down the search. The catalogId and categoryId are required parameters to identify the catalog and category context.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId) The site context.

#### Request body (required)

Media type: `application/json`. Schema: `UnassignedProductSearchRequest`.

_Example: UnassignedProductSearchRequestBody_

```
{
  "catalogId": "electronics-catalog",
  "categoryId": "electronics-gaming",
  "query": {
    "textQuery": {
      "fields": [
        "id"
      ],
      "searchPhrase": "ipod"
    }
  },
  "limit": 10,
  "offset": 0
}
```

#### Responses

*   **200** Unassigned product search completed successfully.
    
    Media type: `application/json`. Schema: `UnassignedProductSearchResult`.
    
    _Example: UnassignedProductSearchResult_
    
    ```
    {
      "catalogId": "electronics-catalog",
      "categoryId": "electronics-gamingx",
      "limit": 1,
      "hits": [
        {
          "brand": "Apple",
          "creationDate": "2019-02-21T22:10:02.000Z",
          "id": "apple-ipod-nano",
          "lastModified": "2019-09-17T19:13:39.000Z",
          "longDescription": {
            "default": {
              "markup": "The iPod nano is a stylish and compact music player with a sleek design.",
              "source": "The iPod nano is a stylish and compact music player with a sleek design."
            }
          },
          "name": {
            "default": "Apple iPod Nano"
          },
          "onlineFlag": {
            "default": true
          },
          "owningCatalogId": "electronics-catalog",
          "owningCatalogName": {
            "default": "Electronics Master Catalog"
          },
          "pageDescription": {
            "default": "Experience music on the go with the Apple iPod Nano."
          },
          "pageKeywords": {
            "default": "Apple, iPod, Nano, MP3, Music Player"
          },
          "pageTitle": {
            "default": "Apple iPod Nano"
          },
          "searchable": {
            "default": true
          },
          "shortDescription": {
            "default": {
              "markup": "The iPod nano is a stylish and compact music player.",
              "source": "The iPod nano is a stylish and compact music player."
            }
          },
          "type": {
            "item": true,
            "master": false
          }
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id"
          ],
          "searchPhrase": "ipod"
        }
      },
      "sorts": [
        {
          "field": "id",
          "sortOrder": "asc"
        }
      ],
      "offset": 0,
      "total": 10
    }
    ```
    
*   **400** Bad Request. Returned when a specified query parameter is invalid or when required fields are missing.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: invalidExpandValue400_
    
    ```
    {
      "title": "Invalid Expand Value",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-expand-value",
      "detail": "The expand value 'does_not_exist' is invalid.",
      "expandValue": "does_not_exist"
    }
    ```
    
    _Example: fieldNotSortable400_
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'unsortableField' can't be used to sort the results.",
      "field": "unsortableField"
    }
    ```
    
    _Example: malformedSelector400_
    
    ```
    {
      "title": "Malformed Selector",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector",
      "detail": "The property selector '**)' is malformed.",
      "selector": "**)"
    }
    ```
    
*   **404** Not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: catalogNotFound404_
    
    ```
    {
      "title": "Catalog Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/catalog-not-found",
      "detail": "No catalog with ID 'DoesnotExist' could be found.",
      "catalogId": "DoesnotExist"
    }
    ```
    
    _Example: categoryNotFound404_
    
    ```
    {
      "title": "Category Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/category-not-found",
      "detail": "No category with ID 'DoesnotExist' for catalog 'WapiCatalog' could be found.",
      "categoryId": "DoesnotExist"
    }
    ```
    

## Schemas

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### Product

Any product that is sold, shown alone, and does not have variations such as different sizes or colors. Product that has no reliance on any other product for inheritance. _A product has a SKU and can have a product option, which has a different SKU_.

*   `assignedCategories` (_array of CatalogCategoryId_) The catalog categories that the product is assigned to. It is read only.
*   `ats` (_number (double)_) The Available To Sell (ATS) inventory value of the product. This is a calculated value.  
    Example: `15`.
*   `brand` (_string_) The brand of the product.  
    Example: `Apple`.
*   `bundledProducts` (_array of Product_) The array of bundled products which the product includes. It is read only.
*   `classificationCategory` (_CatalogCategoryId_)
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'. It is read only.  
    Example: `253402214400`.
*   `defaultVariantId` (_string_) The ID of the product's default variant. It is read only.  
    Example: `apple-ipod-classic-8gb-black`.
*   `ean` (_string_) The European Article Number of the product.  
    Example: `ksdf69w4`.
*   `id` (_ProductId_, required)
*   `image` (_MediaFile_)
*   `imageGroups` (_array of ImageGroup_) The array of product image groups. It is read only.
*   `inStock` (_boolean_) The flag that indicates if the product is in stock, or not. This is a calculated value.  
    Example: `true`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'. It is read only.  
    Example: `253402214400`.
*   `localizedTaxClassId` (_object_) The localized tax class identifier of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "exempt"
    }
    ```
    
*   `longDescription` (_object_) The localized long description of the product.
    
    Additional properties: `MarkupText`.
    
*   `manufacturerName` (_string_) The name of the product's manufacturer.  
    Example: `Apple`.
*   `manufacturerSku` (_string_) The SKU of the product's manufacturer.  
    Example: `HSD68J`.
*   `master` (_Master_)
*   `name` (_object_) The localized name of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Apple Ipod Classic"
    }
    ```
    
*   `online` (_boolean_) The flag that indicates if the product is online, or not. This is a calculated value.  
    Example: `true`.
*   `onlineFlag` (_object_) The site-specific online status of the product.
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "Site1": true
    }
    ```
    
*   `owningCatalogId` (_string_) The ID of the catalog that owns the product.  
    Example: `apple-master-catalog`.
*   `owningCatalogName` (_object_) The localized name of the catalog that owns the product. It is read only.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Apple Master Catalog"
    }
    ```
    
*   `pageDescription` (_object_) The localized page description of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Page Description"
    }
    ```
    
*   `pageKeywords` (_object_) The localized page keywords of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Keywords"
    }
    ```
    
*   `pageTitle` (_object_) The localized page title of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Page Title"
    }
    ```
    
*   `price` (_number (double)_) The price of the product.  
    Example: `219.99`.
*   `priceCurrency` (_string_) The currency code for a product's price.  
    Example: `USD`.
*   `pricePerUnit` (_number (double)_) The price per unit of the product. This is a read only field.  
    Example: `1`.
*   `primaryCategories` (_array of CatalogCategoryId_) The primary catalog categories that the product is assigned to. It is read only.
*   `primaryCategoryId` (_string_) The ID of the products primary category. This is a read only field. It is read only.  
    Example: `electronics-media-players`.
*   `productBundles` (_array of Product_) The array of product bundles which the product belongs to. It is read only.
*   `productOptions` (_array of ProductOption_) The array of product options. This is applicable for products of type "option". It is read only.
*   `productSets` (_array of Product_) The array of product sets which the product belongs to. It is read only.
*   `searchable` (_object_) The site-specific searchable status of the product.
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "Site1": true
    }
    ```
    
*   `setProducts` (_array of Product_) The array of set products which the product includes. It is read only.
*   `shortDescription` (_object_) The localized short description of the product.
    
    Additional properties: `MarkupText`.
    
*   `taxClassId` (_string_) The tax class identifier of the product.  
    Example: `standard`.
*   `type` (_ProductType_)
*   `unit` (_string_) The sales unit of the product.  
    Example: `single`.
*   `unitMeasure` (_string_) The unitMeasure of the product.  
    Example: `each`.
*   `unitQuantity` (_number (double)_) The unitQuantity of the product.  
    Example: `15`.
*   `upc` (_string_) The Universal Product Code (UPC) of the product.  
    Example: `66JSD88JASD`.
*   `validFrom` (_object_) The valid/online from date of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default@SiteGenesis": "2000-05-11T00:00:00.000Z"
    }
    ```
    
*   `validTo` (_object_) The valid/online to date of the product.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "default@SiteGenesis": "2050-05-11T00:00:00.000Z"
    }
    ```
    
*   `variants` (_array of Variant_) The array of variants of the product. This is applicable for product types "master" and "variationGroup" only. It is read only.
*   `variationAttributes` (_array of VariationAttribute_) The sorted array of variation attributes assigned to the product. This is applicable for product types "master", "variationGroup" and "variant" only. It is read only.
*   `variationGroups` (_array of VariationGroup_) The array of variation groups in the product. This is applicable for product type "master" only. It is read only.
*   `variationValues` (_object_) The variation values selected for the product in variation attribute id and value pairs. This is applicable for product types "Variant" and "VariationGroup" only. It is read only.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "red",
      "size": "8gb"
    }
    ```
    

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### VariantSearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

Includes all fields of `SearchRequest`.

_Example_

```
{
  "limit": 4,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "campaign"
    }
  },
  "offset": 2
}
```

### VariantSearchResult

Document that represents a search on certificates and keys.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Variant_, required) An array of search hits (`Variant` objects).

### VariationGroups

Document representing an unfiltered list of variation groups.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of VariationGroup_, required) The array of variation group objects.

### VariationGroup

Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for it's product variants, and is used for navigation. _Doesn't have a SKU._

*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The sales price of the variation group.  
    Example: `229.99`.
*   `productId` (_string_, required) The ID (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic-black`.
*   `variationValues` (_object_) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "red"
    }
    ```
    

### Variants

Document representing an unfiltered list of variants.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Variant_, required) An array of variants.

### Variant

A product which is a variation within a master product that describes different colors, sizes, or other variation attributes. _Has a SKU_

*   `ats` (_number (double)_) The Available To Sell (ATS) inventory value of the product. This is a calculated value.  
    Example: `10`.
*   `defaultProductVariation` (_boolean_) A flag indicating whether the variant is a default variant.  
    Example: `true`.
*   `image` (_MediaFile_)
*   `inStock` (_boolean_) True if the product is in stock, false if not.  
    Example: `true`.
*   `online` (_boolean_) If the product is currently online. True if online, false if not.  
    Example: `true`.
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The sales price of the variant.  
    Example: `29.99`.
*   `priceCurrency` (_string_) Currency code for the price of the product.  
    Example: `USD`.
*   `productId` (_ProductId_, required)
*   `searchable` (_object_) A flag indicating whether the variant is searchable.
    
    Additional properties: `boolean`.
    
    _Example_
    
    ```
    {
      "Site1": true
    }
    ```
    
*   `variationAttributes` (_array of VariationAttribute_) Variation attributes.
*   `variationValues` (_object_) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "black"
    }
    ```
    

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### ProductOptions

Document representing an unfiltered list of product options.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of ProductOption_, required) The array of product option objects.

### ProductOption

Product options enable you to sell configurable products that have optional accessories, upgrades, or additional services. Options are always purchased with a product and can't be purchased separately.

*   `customName` (_object_) The localized custom name of the product option.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Warranty"
    }
    ```
    
*   `defaultProductOptionValue` (_string_) The default product option value.  
    Example: `5-years`.
*   `description` (_object_) The localized description of the product option.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Option Description"
    }
    ```
    
*   `id` (_string_, required) The object attribute definition ID which is also the identifier for the product option.  
    Minimum length: 1. Example: `warranty`.
*   `image` (_MediaFile_)
*   `name` (_string_) The name of the object attribute definition.  
    Example: `Warranty`.
*   `selectedOptionValue` (_string_) The selected option value of the product option.  
    Example: `2-years`.
*   `shared` (_boolean_) The flag that indicates if the product option is shared or local.  
    Example: `false`.
*   `sortingMode` (_string_) The sorting mode for the product option values.  
    Allowed values: `byexplicitorder`, `byoptionprice`. Example: `byoptionprice`.
*   `values` (_array of ProductOptionValue_) The sorted array of values of the product option.

### ProductOptionValue

Document representing a product option Value

*   `defaultProductOptionValue` (_boolean_) Flag indicating if the product option value is the default value for the product option.  
    Example: `true`.
*   `id` (_string_, required) The ID of the product option value.  
    Minimum length: 1. Example: `5-year`.
*   `optionPrices` (_array of Money_) The list of prices in the product option value.
*   `skuExtension` (_string_) The SKU extension of the product option value.  
    Example: `extension`.
*   `value` (_object_, required) The localized value of the product option.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "5 Year Warranty"
    }
    ```
    

### VariationAttributeValue

Document representing a variation attribute value.

*   `description` (_object_) The localized description of the variation value.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Red"
    }
    ```
    
*   `image` (_MediaFile_)
*   `imageSwatch` (_MediaFile_)
*   `name` (_object_) The localized display name of the variation value.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "color": "Red"
    }
    ```
    
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.  
    Example: `true`.
*   `position` (_number (double)_) The position of the value among all values of a variation attribute.  
    Example: `2`.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1. Example: `red`.

### VariationAttributes

Document representing an unfiltered list of variation attributes.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of VariationAttribute_, required) The array of variation attribute objects.

### VariationAttribute

Document representing a variation attribute.

*   `attributeDefinitionId` (_string_, required) The id of the requested attribute definition.  
    Example: `color`.
*   `attributeDefinitionName` (_object_) The localized display name of the variation attribute definition.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Color"
    }
    ```
    
*   `defaultValue` (_string_) Default variation attribute value.  
    Example: `black`.
*   `id` (_string_) The ID of the variation attribute.  
    Minimum length: 1. Example: `color`.
*   `name` (_object_) The localized display name of the variation attribute.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "Color"
    }
    ```
    
*   `shared` (_boolean_) Returns the value of attribute 'shared' if attribute is local or shared.  
    Example: `false`.
*   `slicing` (_boolean_) Returns the value of attribute 'slicing'.  
    Example: `true`.
*   `values` (_array of VariationAttributeValue_) The sorted array of variation values. This array can be empty.
*   `variationAttributeType` (_string_) Variation attribute type.  
    Allowed values: `string`, `int`, `unknown`. Example: `string`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### CategorizationAttributeDefinitionsResult

The list of categorization attributes supported for rule based categorization.

Includes all fields of `ResultBase`.

*   `data` (_array of CategorizationAttributeDefinition_, required) The list of the categorization attribute definitions. This can be empty.

### ProductSearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

Includes all fields of `SearchRequest`.

_Example_

```
{
  "limit": 4,
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "campaign"
    }
  },
  "offset": 2
}
```

### ProductSearchResult

Document representing a product search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Product_, required) A sorted array of search hits (`Product` objects). The array can be empty.

### UnassignedProductSearchRequest

Document representing an unassigned product search request. This search finds products that are not assigned to a specific category within a catalog.

Includes all fields of `SearchRequest`.

*   `catalogId` (_string_, required) The ID of the catalog to which the specified category belongs.  
    Minimum length: 1. Maximum length: 256. Example: `electronics-catalog`.
*   `categoryId` (_string_, required) The ID of the category to which products are not assigned.  
    Minimum length: 1. Maximum length: 256. Example: `electronics-gaming`.

_Example_

```
{
  "catalogId": "electronics-catalog",
  "categoryId": "electronics-gaming",
  "limit": 10,
  "query": {
    "textQuery": {
      "fields": [
        "id"
      ],
      "searchPhrase": "ipod"
    }
  },
  "offset": 0
}
```

### UnassignedProductSearchResult

Document representing an unassigned product search result. Contains products that are not assigned to the specified category.

Includes all fields of `PaginatedSearchResult`.

*   `catalogId` (_string_) The ID of the catalog to which the specified category belongs.  
    Minimum length: 1. Maximum length: 256. Example: `electronics-catalog`.
*   `categoryId` (_string_) The ID of the category to which products are not assigned.  
    Minimum length: 1. Maximum length: 256. Example: `electronics-gaming`.
*   `hits` (_array of Product_, required) A sorted array of search hits (`Product` objects). If there are no hits, the array can be empty.

### CatalogCategoryId

Document representing a catalog category ID.

*   `catalogId` (_CatalogId_, required)
*   `categoryId` (_CategoryId_, required)

### MediaFile

Document representing media file.

*   `absUrl` (_string_) The absolute URL with request protocol.  
    Example: `https://www.example-image.com/images/apple-ipod-classic.jpg`.
*   `alt` (_object_) The alternative image text.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "iPod"
    }
    ```
    
*   `disBaseUrl` (_string_) The Dynamic Image Service (DIS) base URL for product images only.  
    Example: `https://www.dis-base-url/images/apple-ipod-clasic.jpg`.
*   `path` (_string_, required) The raw media file path.  
    Example: `/images/apple-ipod-classic.jpg`.
*   `title` (_object_) The image title.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "iPod"
    }
    ```
    

### ImageGroup

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of MediaFile_, required) The images of the image group.
*   `variationAttributes` (_array of VariationAttribute_) Returns a list of variation attributes applying to this image group.
*   `viewType` (_string_, required) The image view type.  
    Example: `hi-res`.

### MarkupText

Document representing markup text.

*   `markup` (_string_, required) The rendered HTML.
*   `source` (_string_, required) The raw markup text.

### Master

Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for it's product variants, and is used for navigation. _Does'nt have a SKU._

*   `masterId` (_ProductId_, required)
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The minimum sales price of the related variants.  
    Example: `199.99`.
*   `priceMax` (_number (double)_) The maximum sales of related variants.  
    Example: `219.99`.
*   `prices` (_object_) prices
    
    Additional properties: `number (double)`.
    

### ProductType

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.  
    Example: `false`.
*   `bundled` (_boolean_) A flag indicating whether the product is bundled.  
    Example: `false`.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.  
    Example: `false`.
*   `master` (_boolean_, required) A flag indicating whether the product is a master.  
    Example: `true`.
*   `option` (_boolean_) A flag indicating whether the product is an option.  
    Example: `false`.
*   `partOfProductSet` (_boolean_) A flag indicating whether the product is part of product set.  
    Example: `false`.
*   `partOfRetailSet` (_boolean_) A flag indicating whether the product is part of retail set.  
    Example: `false`.
*   `retailSet` (_boolean_) A flag indicating whether the product is a retail set.  
    Example: `false`.
*   `set` (_boolean_) A flag indicating whether the product is a set.  
    Example: `false`.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.  
    Example: `false`.
*   `variationGroup` (_boolean_) A flag indicating whether the product is a variation group.  
    Example: `false`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Money

A combination of a Currency and an amount of that Currency.

*   `currencyMnemonic` (_CurrencyCode_)
*   `value` (_number (double)_) The amount of money for the given currency.  
    Example: `1234.56`.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CategorizationAttributeDefinition

The categorization attribute definition.

*   `id` (_string_, required) The ID of the supported attribute.  
    Maximum length: 256. Example: `producttype`.
*   `attributeName` (_string_) The display name of the supported attribute.  
    Maximum length: 4000. Example: `Product Type`.
*   `attributeType` (_string_, required) The type of the attribute (custom/system/categorization). "system" indicates the System Attribute of the Product in ECOM, "custom" indicates the Custom Attribute of the Product in ECOM defined by merchant and "categorization" indicates the attribute used for categorization purposes ONLY and is not a defined attribute on the Product Object.  
    Allowed values: `custom`, `system`, `categorization`. Example: `categorization`.
*   `valueType` (_string_, required) The value type of the attribute.  
    Allowed values: `string`, `int`, `double`, `text`, `html`, `date`, `datetime`, `image`, `boolean`, `money`, `quantity`, `email`, `password`, `set-of-string`, `set-of-int`, `set-of-double`, `enum-of-string`, `enum-of-int`. Example: `string`.
*   `allowedOperators` (_array of string_, required) The list of allowed operators for this attribute based on its value type.  
    Items: Allowed values: `starts_with`, `contains`, `equals`, `not_equals`, `greater_than`, `less_than`, `is_one_of`, `not_one_of`, `is_defined`, `is_not_defined`. Example: `equals`.
    
    _Example_
    
    ```
    [
      "equals",
      "notEquals"
    ]
    ```
    
*   `allowedValues` (_array of string_) The list of allowed values for this attribute IF its attributeType is an ENUM.  
    Items: Maximum length: 4000. Example: `1`.
    
    _Example_
    
    ```
    [
      1,
      2
    ]
    ```
    
*   `allowedDisplayValues` (_array of string_) The list of allowed Localized Display values for this attribute IF its attributeType is an ENUM based on the locale query param requested. If no locale query param value is provided "default" locale is assumed.  
    Items: Maximum length: 4000. Example: `One`.
    
    _Example_
    
    ```
    [
      "One",
      "Two"
    ]
    ```
    

### CatalogId

The ID of the catalog.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `apparel-catalog`.

### CategoryId

The ID of the category.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `mens`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "value": {
    "must": [
      {
        "textQuery": {
          "fields": [
            "couponId"
          ],
          "searchPhrase": "DEAL"
        }
      },
      {
        "textQuery": {
          "fields": [
            "description"
          ],
          "searchPhrase": "Big bargain deal"
        }
      }
    ],
    "mustNot": [
      {
        "termQuery": {
          "fields": [
            "enabled"
          ],
          "operator": "is",
          "values": [
            false
          ]
        }
      }
    ]
  }
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "value": {
    "operator": "and",
    "filters": [
      {
        "termFilter": {
          "field": "id",
          "operator": "is",
          "values": [
            "myId"
          ]
        }
      },
      {
        "termFilter": {
          "field": "couponId",
          "operator": "is",
          "values": [
            "couponOne"
          ]
        }
      }
    ]
  }
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=7a906538f50a4d71636d20e418302c54cd961ab9e082cc9e26dc52be035eface url=/developer/current/en-us/commerce-cloud/marketplace/references/generated-api-specs/marketplace-seller-products.md -->

Products

# Products

Products are the information necessary to enable the listing of your products in the e-commerce environment. Each product must have at least one associated variant/SKU, which will be the item that will actually be added to the cart in the e-commerce environment.

**Version:** 1.0.0

## Servers

*   `https://login.salesforce.com`
*   `http://mydomainname.my.site.com`
*   `http://{{community-url}}`
*   `http://{{base-url}}`

## Security

*   `oauth2Auth` (http)
    *   HTTP scheme: oauth2
*   `bearerAuth` (http)
    *   HTTP scheme: bearer

## Operations

### GET Query

`GET /services/data/v51.0/query`

Operation ID: `Query`. Tags: Product. Security: bearerAuth.

To look up information about products, use the [Query](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) resource of the main REST API from Salesforce and set the value of the `q` parameter to an SOQL query. The following examples are included in the query parameters section of this page, with corresponding examples in the responses section:

**Example 1 of 3**: `getAllManufacturers`

One piece of information that can be completed on a product is its make/manufacturer. This value must be one of the values from the marketplace (if none of them apply, contact the marketplace to check whether a new one can be inserted). In order to insert this relationship, you must first request an export of the data to the marketplace or access the API directly and save the list. If the item limit is exceeded, pagination may be necessary, in which case please refer to the [following documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm#retrieve_remaining_results_title).

**Example 2 of 3**: `getAllSpecs`

Specs consist of all the extra information that can be associated with the products and SKUs. This includes both merely descriptive information, such as "book author", "musical genre",... and also information on variations of SKUs, such as "color" and "size", which define an SKU and need to be chosen in order to complete the purchase. Sellers may fill in the specs within the products with any value (red, blue,...), but the specs themselves (color) must be one of the specs configured by the marketplace. A request for this export may be submitted to the marketplace or this API may be used to create a full list. Some specs may be subject to restrictions during completion (boolean, specific values, only numbers). Please confirm any queries with the marketplace as you fill in each type. If you have more than the permissible number of items, you may need pagination, in which case please refer to the following [documentation](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm#retrieve_remaining_results_title).

**Example 3 of 3**: `getAllProductImagesByProductId`

This call uses the External Product ID to list all its images

#### Parameters

*   `q` (query, string)
    
    _Example: getAllManufacturers_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__Manufacturer__c  LIMIT 200
    ```
    
    _Example: getAllSpecs_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__Specs__c WHERE Atonit_Mktplace__Is_Deleted__c = false LIMIT 200
    ```
    
    _Example: getAllProductImagesByProductId_
    
    ```
    SELECT FIELDS(ALL) FROM Atonit_Mktplace__Image__c WHERE Atonit_Mktplace__Product__r.Atonit_Mktplace__External_Id__c= '{{seller-api-prefix}}-product-1' LIMIT 200
    ```
    

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 17:37:15 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1688/101002`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example: getAllManufacturers_
    
    ```
    {
      "totalSize": 31,
      "done": true,
      "records": [
        {
          "Id": "a0C5Y00001sGTZlUAO",
          "Name": "Samsung",
          "CreatedDate": "2021-03-22T19:24:42.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:42.000+0000",
          "Atonit_Mktplace__Description__c": null,
          "Atonit_Mktplace__Marketplace_Id__c": "Samsung"
        },
        {
          "Id": "a0C5Y00001sGTZmUAO",
          "Name": "Apple",
          "CreatedDate": "2021-03-22T19:24:42.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:42.000+0000",
          "Atonit_Mktplace__Description__c": null,
          "Atonit_Mktplace__Marketplace_Id__c": "Apple"
        },
        {
          "Id": "a0C5Y00001sGTZnUAO",
          "Name": "Atari",
          "CreatedDate": "2021-03-22T19:24:42.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:42.000+0000",
          "Atonit_Mktplace__Description__c": null,
          "Atonit_Mktplace__Marketplace_Id__c": "Atari"
        }
      ]
    }
    ```
    
    _Example: getAllSpecs_
    
    ```
    {
      "totalSize": 59,
      "done": true,
      "records": [
        {
          "Id": "a0Y5Y00000nTXSSUA4",
          "Name": "Available for In Store Pickup",
          "CreatedDate": "2021-03-22T21:13:23.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:11.000+0000",
          "Atonit_Mktplace__Is_Deleted__c": false,
          "Atonit_Mktplace__Marketplace_Id__c": "availableForInStorePickup",
          "Atonit_Mktplace__Set_of_Text__c": false,
          "Atonit_Mktplace__Update_Timestamp__c": "2021-04-12T18:04:57.000+0000"
        },
        {
          "Id": "a0Y5Y00000nTXSTUA4",
          "Name": "Battery Life",
          "CreatedDate": "2021-03-22T21:13:23.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:11.000+0000",
          "Atonit_Mktplace__Is_Deleted__c": false,
          "Atonit_Mktplace__Marketplace_Id__c": "batteryLife",
          "Atonit_Mktplace__Set_of_Text__c": false,
          "Atonit_Mktplace__Update_Timestamp__c": "2021-04-12T18:04:57.000+0000"
        },
        {
          "Id": "a0Y5Y00000nTXSUUA4",
          "Name": "Battery Type",
          "CreatedDate": "2021-03-22T21:13:23.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:11.000+0000",
          "Atonit_Mktplace__Is_Deleted__c": false,
          "Atonit_Mktplace__Marketplace_Id__c": "batteryType",
          "Atonit_Mktplace__Set_of_Text__c": false,
          "Atonit_Mktplace__Update_Timestamp__c": "2021-04-12T18:04:57.000+0000"
        },
        {
          "Id": "a0Y5Y00000nTXSXUA4",
          "Name": "Color",
          "CreatedDate": "2021-03-22T21:13:23.000+0000",
          "LastModifiedDate": "2021-04-12T18:05:11.000+0000",
          "Atonit_Mktplace__Is_Deleted__c": false,
          "Atonit_Mktplace__Marketplace_Id__c": "color",
          "Atonit_Mktplace__Set_of_Text__c": false,
          "Atonit_Mktplace__Update_Timestamp__c": "2021-04-12T18:04:57.000+0000"
        }
      ]
    }
    ```
    
    _Example: getAllProductImagesByProductId_
    
    ```
    {
      "totalSize": 2,
      "done": true,
      "records": [
        {
          "Id": "a085Y00001AhajFQAR",
          "Name": "I-9353",
          "CreatedDate": "2021-04-22T18:39:01.000+0000",
          "LastModifiedDate": "2021-04-23T18:35:05.000+0000",
          "Atonit_Mktplace__Product__c": "a0M5Y00000csztLUAQ",
          "Atonit_Mktplace__Order__c": 1,
          "Atonit_Mktplace__Spec_Value__c": "Vermelho",
          "Atonit_Mktplace__Spec__c": "a0Y5Y00000nTXSXUA4",
          "Atonit_Mktplace__URL__c": "https://via.placeholder.com/150.png",
          "Atonit_Mktplace__View_Type__c": "swatch-small-medium-large",
          "Atonit_Mktplace__External_Id__c": "atonit-vitta-product-1-sku-image-1"
        },
        {
          "Id": "a085Y00001AhajPQAR",
          "Name": "I-9354",
          "CreatedDate": "2021-04-22T18:59:02.000+0000",
          "LastModifiedDate": "2021-04-23T18:31:40.000+0000",
          "Atonit_Mktplace__Product__c": "a0M5Y00000csztLUAQ",
          "Atonit_Mktplace__Order__c": 1,
          "Atonit_Mktplace__Spec_Value__c": null,
          "Atonit_Mktplace__Spec__c": null,
          "Atonit_Mktplace__URL__c": "https://via.placeholder.com/150.png",
          "Atonit_Mktplace__View_Type__c": "swatch-small-medium-large",
          "Atonit_Mktplace__External_Id__c": "atonit-vitta-product-1-image-1"
        }
      ]
    }
    ```
    

### GET Get Product by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Product__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1`

Operation ID: `Get Product by ID`. Tags: Product. Security: bearerAuth.

This call will load all the available product information using the external ID as the key.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:15:16 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1577/101002`.
    *   `Last-Modified` (string)  
        Example: `Fri, 23 Apr 2021 18:14:13 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a0M5Y00000csztLUAQ",
      "Name": "P-1512",
      "CreatedDate": "2021-04-22T17:29:01.000+0000",
      "LastModifiedDate": "2021-04-23T18:14:13.000+0000",
      "Atonit_Mktplace__Category_Name__c": "a005Y00002HSIoMQAX",
      "Atonit_Mktplace__Full_description__c": "Chave de Fenda para ser usada em diversos projetos pessoais",
      "Atonit_Mktplace__Image_URL__c": null,
      "Atonit_Mktplace__Is_Deleted__c": false,
      "Atonit_Mktplace__Manufacturer__c": "a0C5Y00001sGTa9UAG",
      "Atonit_Mktplace__Matched_Product__c": null,
      "Atonit_Mktplace__Name__c": "Chave de Fenda",
      "Atonit_Mktplace__Product_type__c": "Simple",
      "Atonit_Mktplace__Short_description__c": "Chave de Fenda Marca própria",
      "Atonit_Mktplace__Status__c": null,
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-product-1"
    }
    ```
    

### PATCH Create or Update Product

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Product__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1`

Operation ID: `Create or Update Product`. Tags: Product. Security: bearerAuth.

This call allows you both to create and update a seller’s product. If a product already exists with the ID provided in the URL, it will be updated, otherwise, it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

The value of `Atonit_Mktplace__Product_type__c` may be "Simple" (product has only 1 SKU, without variation) or "Grouped" (product has variations such as color and size). To configure the make/manufacturer of the product and its main category, the corresponding External ID must be used.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Name__c": "Chave de Fenda",
  "Atonit_Mktplace__Is_Deleted__c": false,
  "Atonit_Mktplace__Short_description__c": "Chave de Fenda Marca própria",
  "Atonit_Mktplace__Full_description__c": "Chave de Fenda para ser usada em diversos projetos pessoais",
  "Atonit_Mktplace__Product_type__c": "Simple",
  "Atonit_Mktplace__Category_Name__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-category-2"
  },
  "Atonit_Mktplace__Manufacturer__r": {
    "Atonit_Mktplace__Marketplace_Id__c": "Toshiba"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:14:13 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1571/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Product__c/a0M5Y00000csztLUAQ`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0M5Y00000csztLUAQ",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### GET Get Product Variant by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Product_Variant__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-sku-1`

Operation ID: `Get Product Variant by ID`. Tags: Product. Security: bearerAuth.

This call will load all the available SKU information using the external ID as the key.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:18:56 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1587/101002`.
    *   `Last-Modified` (string)  
        Example: `Fri, 23 Apr 2021 18:18:23 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a0L5Y00000oAUQDUA4",
      "Name": "atonit-vitta-sku-1",
      "CreatedDate": "2021-04-22T18:23:59.000+0000",
      "LastModifiedDate": "2021-04-23T18:18:23.000+0000",
      "Atonit_Mktplace__Depth__c": 23.3,
      "Atonit_Mktplace__Display_Name__c": "Chave de Fenda",
      "Atonit_Mktplace__EAN__c": "3839590768017",
      "Atonit_Mktplace__Full_Description__c": "Chave de Fenda para ser usada em diversos projetos pessoais",
      "Atonit_Mktplace__Height__c": 23.3,
      "Atonit_Mktplace__Image_Link__c": null,
      "Atonit_Mktplace__Is_Deleted__c": false,
      "Atonit_Mktplace__Main_Product__c": "a0M5Y00000csztLUAQ",
      "Atonit_Mktplace__Matched_Variant__c": null,
      "Atonit_Mktplace__Short_Description__c": "Chave de Fenda Marca própria",
      "Atonit_Mktplace__Weight__c": 23.3,
      "Atonit_Mktplace__Width__c": 23.3,
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-sku-1"
    }
    ```
    

### PATCH Create or Update Product Variant

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Product_Variant__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-sku-1`

Operation ID: `Create or Update Product Variant`. Tags: Product. Security: bearerAuth.

This call allows you to both create and update a seller’s product variant (SKU). If an SKU already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

The value of the `Main_Product` is required and must be an External ID of a product already registered.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Name": "{{seller-api-prefix}}-sku-1",
  "Atonit_Mktplace__Display_Name__c": "Chave de Fenda",
  "Atonit_Mktplace__Is_Deleted__c": false,
  "Atonit_Mktplace__Short_description__c": "Chave de Fenda Marca própria",
  "Atonit_Mktplace__Full_description__c": "Chave de Fenda para ser usada em diversos projetos pessoais",
  "Atonit_Mktplace__EAN__c": "3839590768017",
  "Atonit_Mktplace__Height__c": 23.3,
  "Atonit_Mktplace__Width__c": 23.3,
  "Atonit_Mktplace__Depth__c": 23.3,
  "Atonit_Mktplace__Weight__c": 23.3,
  "Atonit_Mktplace__Main_Product__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-product-1"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:18:23 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1587/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Product_Variant__c/a0L5Y00000oAUQDUA4`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0L5Y00000oAUQDUA4",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### GET Get Product Image by ID

`GET /services/data/v51.0/sobjects/Atonit_Mktplace__Image__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-image-1`

Operation ID: `Get Product Image by ID`. Tags: Product. Security: bearerAuth.

This call will upload all the available image information using the external ID as the key.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:36:11 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1612/101002`.
    *   `Last-Modified` (string)  
        Example: `Fri, 23 Apr 2021 18:31:40 GMT`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Vary` (string)  
        Example: `Accept-Encoding`.
    *   `Content-Encoding` (string)  
        Example: `gzip`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "Id": "a085Y00001AhajPQAR",
      "Name": "I-9354",
      "CreatedDate": "2021-04-22T18:59:02.000+0000",
      "LastModifiedDate": "2021-04-23T18:31:40.000+0000",
      "Atonit_Mktplace__Product__c": "a0M5Y00000csztLUAQ",
      "Atonit_Mktplace__Order__c": 1,
      "Atonit_Mktplace__Spec_Value__c": null,
      "Atonit_Mktplace__Spec__c": null,
      "Atonit_Mktplace__URL__c": "https://via.placeholder.com/150.png",
      "Atonit_Mktplace__View_Type__c": "swatch-small-medium-large",
      "Atonit_Mktplace__External_Id__c": "atonit-vitta-product-1-image-1"
    }
    ```
    

### DELETE Delete Product Image by ID

`DELETE /services/data/v51.0/sobjects/Atonit_Mktplace__Image__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-image-1`

Operation ID: `Delete Product Image by ID`. Tags: Product. Security: bearerAuth.

This call allows the deletion of a product image. If successful, 204 is returned. If the ID no longer exists, 404 will be returned.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **204** No Content
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:38:46 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Content-Security-Policy` (string)  
        Example: `upgrade-insecure-requests` .
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1614/101002`.
    
    Media type: `text/plain`. Schema: `string`.
    
    Type: `string`.
    

### PATCH Create or Update Product Image

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Image__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-image-1`

Operation ID: `Create or Update Product Image`. Tags: Product. Security: bearerAuth.

This call allows you to both create and update a product image. If an image already exists with the ID provided in the URL, it will be updated, otherwise it will be created. The rule for the ID is that it must start with the seller-api-prefix and contain only letters, numbers and `-`.

To synchronize a product image, it must be available on a public URL. The Product is configured using its External ID, which must have been inserted previously. With the Order parameter, the order of various images can be controlled. The field `View_Type__c` must have the value: swatch, small, medium, large or swatch-small-medium-large. The latter option will upload all possible formats of the image.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__URL__c": "https://via.placeholder.com/150.png",
  "Atonit_Mktplace__Order__c": 1,
  "Atonit_Mktplace__View_Type__c": "swatch-small-medium-large",
  "Atonit_Mktplace__Product__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-product-1"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:31:39 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1608/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Image__c/a085Y00001AhajPQAR`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a085Y00001AhajPQAR",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### PATCH Create or Update Product Variant Image

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Image__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-sku-image-1`

Operation ID: `Create or Update Product Variant Image`. Tags: Product. Security: bearerAuth.

Images of variants (SKU) are also added directly to the product, but an optional Spec and Spec\_Value value is configured so that the image is associated with a specific variation.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__URL__c": "https://via.placeholder.com/150.png",
  "Atonit_Mktplace__Order__c": 1,
  "Atonit_Mktplace__View_Type__c": "swatch-small-medium-large",
  "Atonit_Mktplace__Product__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-product-1"
  },
  "Atonit_Mktplace__Spec__r": {
    "Atonit_Mktplace__Marketplace_Id__c": "color"
  },
  "Atonit_Mktplace__Spec_Value__c": "Vermelho"
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:35:05 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1611/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Image__c/a085Y00001AhajFQAR`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a085Y00001AhajFQAR",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### DELETE Remove Link from Product to Category

`DELETE /services/data/v51.0/sobjects/Atonit_Mktplace__Product_to_Related_Category__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-{seller-api-prefix}-category-1`

Operation ID: `Remove Link from Product to Category`. Tags: Product. Security: bearerAuth.

This call allows the deletion of an association between product and category. If successful, 204 is returned. If the ID no longer exists, 404 will be returned.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **200** Successful response
    
    Media type: `application/json`.
    

### PATCH Link Product to Category

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Product_to_Related_Category__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-{seller-api-prefix}-category-1`

Operation ID: `Link Product to Category`. Tags: Product. Security: bearerAuth.

For the product to appear in the e-commerce environment it must be associated with one or more categories. This call allows a product to be linked to a category that has already been registered. The external ID must be in the format `<id-product>-<id-category>`.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Product__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-product-1"
  },
  "Atonit_Mktplace__Category__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-category-1"
  }
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:43:21 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1617/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Product_to_Related_Category__c/a0N5Y00000ZsrClUAJ`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0N5Y00000ZsrClUAJ",
      "success": true,
      "errors": [],
      "created": false
    }
    ```
    

### DELETE Delete Product Spec

`DELETE /services/data/v51.0/sobjects/Atonit_Mktplace__Spec_Product_Association__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-kidsAge`

Operation ID: `Delete Product Spec`. Tags: Product. Security: bearerAuth.

This call allows deletion of the value of a product spec. If successful, 204 is returned. If the ID no longer exists, 404 will be returned.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **204** No Content
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:47:17 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Content-Security-Policy` (string)  
        Example: `upgrade-insecure-requests` .
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1633/101002`.
    
    Media type: `text/plain`. Schema: `string`.
    
    Type: `string`.
    

### PATCH Create or Update Product Spec

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Spec_Product_Association__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-product-1-kidsAge`

Operation ID: `Create or Update Product Spec`. Tags: Product. Security: bearerAuth.

This call allows configuration of the value of a product spec. The spec must be one of those listed by "Get All Specs". The external ID must be in the format `<id-product>-<id-spec>`.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Product__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-product-1"
  },
  "Atonit_Mktplace__Spec__r": {
    "Atonit_Mktplace__Marketplace_Id__c": "kidsAge"
  },
  "Atonit_Mktplace__Value__c": "10+"
}
```

#### Responses

*   **201** Created
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:46:45 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1633/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Spec_Product_Association__c/a0W5Y00000V7BtYUAV`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0W5Y00000V7BtYUAV",
      "success": true,
      "errors": [],
      "created": true
    }
    ```
    

### DELETE Delete Product Variant Spec

`DELETE /services/data/v51.0/sobjects/Atonit_Mktplace__Spec_Product_Variant_Association__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-sku-1-color`

Operation ID: `Delete Product Variant Spec`. Tags: Product. Security: bearerAuth.

This call allows deletion of the value of an SKU spec. If successful, 204 is returned. If the ID no longer exists, 404 will be returned.

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Responses

*   **204** No Content
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:50:07 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `Content-Security-Policy` (string)  
        Example: `upgrade-insecure-requests` .
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1637/101002`.
    
    Media type: `text/plain`. Schema: `string`.
    
    Type: `string`.
    

### PATCH Create or Update Product Variant Spec

`PATCH /services/data/v51.0/sobjects/Atonit_Mktplace__Spec_Product_Variant_Association__c/Atonit_Mktplace__External_Id__c/{seller-api-prefix}-sku-1-color`

Operation ID: `Create or Update Product Variant Spec`. Tags: Product. Security: bearerAuth.

This call allows configuration of the value of an SKU spec. The spec must be one of those listed by "Get All Specs". The external ID must be in the format `<id-sku>-<id-spec>`. The value of `Atonit_Mktplace__Variation_Attribute__c` is true if this spec is a variant of the SKU, which must be selected on the product page (color, size, etc.). So that the product is correctly registered, all its SKUs must be completed with the same specs with this value (it is incorrect to register one product SKY with color as a variant, and another without).

#### Parameters

*   `seller-api-prefix` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `object`.

_Example_

```
{
  "Atonit_Mktplace__Product_Variant__r": {
    "Atonit_Mktplace__External_Id__c": "{{seller-api-prefix}}-sku-1"
  },
  "Atonit_Mktplace__Spec__r": {
    "Atonit_Mktplace__Marketplace_Id__c": "color"
  },
  "Atonit_Mktplace__Value__c": "Vermelho",
  "Atonit_Mktplace__Variation_Attribute__c": false
}
```

#### Responses

*   **200** OK
    
    Headers:
    
    *   `Date` (string)  
        Example: `Fri, 23 Apr 2021 18:49:57 GMT`.
    *   `Strict-Transport-Security` (string)  
        Example: `max-age=31536002; includeSubDomains`.
    *   `X-Content-Type-Options` (string)  
        Example: `nosniff`.
    *   `X-XSS-Protection` (string)  
        Example: `1; mode=block`.
    *   `X-Robots-Tag` (string)  
        Example: `none`.
    *   `Cache-Control` (string)  
        Example: `no-cache,must-revalidate,max-age=0,no-store,private`.
    *   `Sforce-Limit-Info` (string)  
        Example: `api-usage=1637/101002`.
    *   `Location` (number)  
        Example: `/services/data/v51.0/sobjects/Atonit_Mktplace__Spec_Product_Variant_Association__c/a0X5Y00001OKK54UAH`.
    *   `Content-Type` (string)  
        Example: `application/json;charset=UTF-8`.
    *   `Transfer-Encoding` (string)  
        Example: `chunked`.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example_
    
    ```
    {
      "id": "a0X5Y00001OKK54UAH",
      "success": true,
      "errors": [],
      "created": false
    }
    ```

<!-- document id=112277026f4dfb84b44373a29b35258c21f211587eeea091f47e32fd7cacbcc0 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-profile.md -->

# Profile

### Overview

The Profile page allows authenticated buyers to view and update their account profile information. The page reads from and updates the underlying Salesforce User record, including fields such as:

- First name
- Last name
- Phone number
- Primary address information

The buyer’s email address is displayed as a read-only field and cannot be modified through the storefront profile experience.

This flow demonstrates how a headless storefront can render buyer profile experiences, including account information and profile management workflows.

![Profile Buyer Journey](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-profile-buyer-journey-37-1.png '{"class": "image-lg", "title": "Profile Buyer Journey"}')

### B2B Commerce APIs Used in the Flow

| Operation      | HTTP Method | Endpoint                                                                                                                                            |
| -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Get profile    | GET         | [`/services/data/v68.0/sobjects/User/{userId}`](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_retrieve.htm) |
| Update profile | PATCH       | [`/services/data/v68.0/sobjects/User/{userId}`](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_update_fields.htm)    |

### Buyer Journey

**Load the Buyer Profile**

1. Call the following endpoint when the profile page loads:

   GET `/services/data/v68.0/sobjects/User/{userId}?fields=FirstName,LastName,Email,Phone,Street,City,State,PostalCode,Country`

2. Use the response to populate the buyer profile form.

3. Handle missing fields gracefully. Some fields can be omitted from the response because of field-level security (FLS). Default missing values to empty strings or null values instead of treating them as application errors.

4. Use the retrieved profile data to render:
   - First name
   - Last name
   - Email address
   - Phone number
   - Address information

**Save Profile Changes**

1. Update the editable profile fields.

2. Submit the profile update request by calling:

   PATCH `/services/data/v68.0/sobjects/User/{userId}`

3. Include only modified fields in the request body.

4. After the update succeeds, merge the submitted field values with the response payload. Some fields can be omitted from the response because of field-level security (FLS). Merging the submitted values prevents masked or restricted fields from disappearing from the profile form after the update.

5. Refresh the profile state using the merged field values.

6. Display a confirmation message indicating that the profile was updated successfully.

**Choose a Profile API Approach**

The storefront can retrieve and update buyer profile information using either SObject REST APIs or Commerce Connect APIs.

- Use SObject REST APIs when the storefront requires access to a broader set of User fields. <!--The reference React storefront uses SObject REST APIs directly to read and update the User record while respecting buyer field-level security (FLS).-->
- Use Connect REST APIs with GET [`/commerce/webstores/{webstoreId}/myprofile`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_myprofile.htm) when the available Commerce profile fields satisfy your storefront requirements.

### Extend the Flow

- To add support for additional buyer profile attributes, integrate with the Salesforce Contact record instead of the User record. This pattern is commonly used for B2C storefront implementations where customer profile data is primarily managed on the Contact object.

## See Also

- [_REST API Developer Guide_: Get Field Values from a Standard Object Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_get_field_values.htm)
- [_REST API Developer Guide_: Working with Records](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/using_resources_working_with_records.htm)
- [_Connect REST API Developer Guide_: When to Use Connect REST API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/intro_using_chatter_connect.htm)

<!-- document id=e6b2f8d84cdb49a90d723d4bd58bc0615f24ec2e969628db874c225a9464304e url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-project-config.md -->

# Project Configuration

Storefront Next uses a centralized, type-safe configuration system that gives you:

- IDE autocomplete: Full TypeScript support with suggestions as you type.
- Environment overrides: Customize settings per environment without code changes.
- Validation: Catch configuration errors at startup, not at run time.
- Security by design: Clear separation between public and server-only values.

All configuration lives in a single file (`config.server.ts`) with defaults that you can override by using environment variables.

## Quick Start

Storefront Next provides two APIs for accessing configuration.

### For Loaders, Actions, Utilities: `getConfig()`

```typescript
import { getConfig } from "@salesforce/storefront-next-runtime/config";

// Server loader/action - pass context
export function loader({ context }: LoaderFunctionArgs) {
  const config = getConfig(context);
  return { limit: config.search.products.hits.limit };
}

// Client loader - no context needed
export function clientLoader() {
  const config = getConfig();
  return { limit: config.search.products.hits.limit };
}
```

### For React Components: `useConfig()`

```typescript
import { useConfig } from "@salesforce/storefront-next-runtime/config";

function ProductGrid() {
  const config = useConfig();
  return <div>Showing {config.search.products.hits.limit} products</div>;
}
```

**note:** `getConfig()` returns the full `AppConfig` when called with context on the server. `useConfig()` returns a narrowed `Omit<AppConfig, 'serverExtension'>` so client-side reads can't reach server-only namespaces. This type narrowing happens automatically through the template's configuration in `src/types/config.ts`.

## Configuration File

The main configuration file is `config.server.ts` in your project root.

```typescript
// config.server.ts
import { defineConfig } from "@salesforce/storefront-next-runtime/config";
import type { Config } from "./src/types/config";

export default defineConfig<Config>({
  metadata: {
    projectName: "My Storefront",
    projectSlug: "my-storefront",
  },
  runtime: {
    ssrOnly: [],
    ssrParameters: { ssrFunctionNodeVersion: "24.x" },
  },
  app: {
    commerce: {
      /* Commerce API settings */
    },
    defaultSiteId: "RefArch",
    /* Locale, currency, features */
    pages: {
      /* Page-specific settings */
    },
    global: {
      /* Branding, product listing defaults */
    },
    images: {
      /* Image optimization */
    },
    performance: {
      /* Caching */
    },
    engagement: {
      /* Analytics adapters */
    },
  },
});
```

For detailed descriptions of all configuration options, see the [Configuration Options Reference](#configuration-options-reference) section below.

The configuration is organized into three main sections.

| Section    | Purpose                                       | Client Access     |
| ---------- | --------------------------------------------- | ----------------- |
| `metadata` | Project name and slug for deployment          | Server only       |
| `runtime`  | SSR and deployment settings                   | Server only       |
| `app`      | Application settings (commerce, features, UI) | Server and client |

The `app` section is automatically made available to client-side code. The `metadata` and `runtime` sections remain server-only.

The `runtime.ssrOnly` option accepts an array of glob patterns for files that must be available on the server but aren't publicly accessible from the client. Use this option for server-side resources that aren't exposed via public URLs.

**warning:** Don't import `config.server.ts` directly in your app code. The `.server.ts` suffix prevents the file from being bundled into client-side code (a React Router framework feature). Always use `getConfig()` or `useConfig()` to access configuration values. These APIs ensure that the configuration is properly loaded and available in the correct context.

## How Configuration Works

The configuration system follows this flow:

1. **Types defined** in `src/types/config.ts` — `AppConfig` defines all app fields, `Config = BaseConfig<AppConfig>`
2. **Defaults defined** in `config.server.ts` — clean, with no `process.env` references
3. **Environment variables** with `PUBLIC__` prefix are automatically merged by `defineConfig()` — this happens at server startup
4. **Final config** is made available via:
   - `getConfig(context)` for server loaders/actions (returns full `AppConfig`)
   - `getConfig()` for client loaders (returns narrowed config without server-only namespaces)
   - `useConfig()` for React components (returns narrowed config)
   - `window.__APP_CONFIG__` for client code

The type narrowing is automatic because the template fills two augmentation slots in `src/types/config.ts`:

```typescript
declare module "@salesforce/storefront-next-runtime/config" {
  interface AppConfigShape extends AppConfig {}
  interface ClientFacingAppConfigShape extends ClientAppConfig {}
}
```

`ClientAppConfig` is `Omit<AppConfig, ServerOnlyNamespace>`, which keeps server-only configuration off the client at both runtime and type level.

**note:** Multi-template caveat
If you build two templates in the same TypeScript program (rare), only one `extends` per slot wins. Fall back to explicit per-call generics: `getConfig<MyAppConfig>(context)` and `useConfig<MyClientAppConfig>()`.

## Required vs Optional Variables

Every variable the storefront recognizes is listed in this guide. Set the **Required** variables in `.env`. Everything else has a working default in `config.server.ts`.

### Required for the app to start

Copy `.env.default` to `.env` and set these required B2C Commerce credentials:

| Variable                                     | Purpose                                                                |
| -------------------------------------------- | ---------------------------------------------------------------------- |
| `PUBLIC__app__commerce__api__clientId`       | SLAS client ID provisioned in B2C Commerce                             |
| `PUBLIC__app__commerce__api__organizationId` | B2C Commerce organization or realm ID (for example, `f_ecom_zzrf_001`) |
| `PUBLIC__app__commerce__api__shortCode`      | SCAPI short code for your tenant (for example, `kv7kzm78`)             |

```bash
PUBLIC__app__commerce__api__clientId=your-client-id
PUBLIC__app__commerce__api__organizationId=your-org-id
PUBLIC__app__commerce__api__shortCode=your-short-code
```

### Required for `pnpm push` (Managed Runtime deploy)

| Variable      | Default                           | Notes                                                         |
| ------------- | --------------------------------- | ------------------------------------------------------------- |
| `MRT_PROJECT` | falls back to `package.json#name` | MRT project slug. Owned by the MRT/Fast Setup team.           |
| `MRT_TARGET`  | —                                 | MRT deploy target (for example, `development`, `production`). |

For more information, see [Storefront Next CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-cli.md).

### Server-only secrets (never prefix with `PUBLIC__`)

| Variable                                                                                                                       | Used by                                                                  | Notes                                                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COMMERCE_API_SLAS_SECRET`                                                                                                     | `src/lib/api-clients.server.ts`, `e2e/src/utils/scapi-helper.ts`         | Required only with private-client SCAPI auth.                                                                                                                                                                    |
| `GUEST_ORDER_LOOKUP_COOKIE_SECRET`                                                                                             | `src/lib/order/session.server.ts`                                        | Signs the guest order lookup state cookie. Required when `guestOrderLookup.enabled` is `true`. Falls back to `CLIENT_SECRET` if unset; if neither is set, the feature fails closed with a `CONFIGURATION_ERROR`. |
| `MARKETING_CLOUD_CLIENT_ID`, `MARKETING_CLOUD_CLIENT_SECRET`, `MARKETING_CLOUD_AUTH_BASE_URL`, `MARKETING_CLOUD_REST_BASE_URL` | Passwordless login email delivery                                        | Required only when `passwordlessLogin.mode = 'email'` and you ship your own MC tenant.                                                                                                                           |
| `SCAPI_PROXY_HOST`                                                                                                             | `vite-plugins/env-validation.ts`, `src/middlewares/app-config.server.ts` | Internal-developer-only override (workspace proxy).                                                                                                                                                              |

**warning:** Don't add server-only secrets to `config.server.ts` and don't give them a `PUBLIC__` prefix. Read them directly from `process.env` in server-side code, such as loaders, actions, and middleware. Anything with the `PUBLIC__` prefix is bundled into the browser-visible JavaScript.

For SLAS private client setup in B2C Commerce, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).

### Optional `PUBLIC__*` overrides (defaults in `config.server.ts`)

For a comprehensive list of optional environment variables with their defaults and effects, see the [Optional Configuration Variables](#optional-configuration-variables) section below.

### Optional non-`PUBLIC__` runtime/deploy variables

| Variable               | Default                          | Effect                                                 |
| ---------------------- | -------------------------------- | ------------------------------------------------------ |
| `HYBRID_PROXY_ENABLED` | `false`                          | Enable Vite hybrid proxy                               |
| `HYBRID_ROUTING_RULES` | —                                | Cloudflare-style routing expression for hybrid proxy   |
| `HYBRID_PROXY_LOCALE`  | falls back to `i18n.fallbackLng` | Locale for SFRA path transformation                    |
| `SFCC_ORIGIN`          | —                                | SFCC origin URL (required when hybrid proxy enabled)   |
| `SFCC_LOG_LEVEL`       | `warn` (prod) / `info` (dev)     | Log verbosity (`error` \| `warn` \| `info` \| `debug`) |

For feature-specific configuration, see the dedicated guides:

- [Configure Multisite URLs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-multi-site.md) — sites, locales, currencies, and URL patterns
- [Set Up Hybrid Proxy Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-proxy-local-dev.md) — `HYBRID_PROXY_*`, `SFCC_ORIGIN`, routing rules
- [Passwordless Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passwordless-login.md) — passwordless login, OTP request, and reset password modes
- [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md) — qualifier-based personalization
- [Shopping Agent for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopping-agent.md) — embedded chat configuration

## Environment Variable Overrides

Override any configuration value by using environment variables with the `PUBLIC__` prefix. With environment variables, you can customize settings per environment (development, staging, production) without modifying code.

### Understanding the Path Syntax

The double underscore (`__`) lets you navigate nested config paths. Think of it as replacing the dot (`.`) in JavaScript object notation:

```bash
# This environment variable:
PUBLIC__app__commerce__api__clientId=abc123

# Maps to this config path:
config.app.commerce.api.clientId

# Which creates this structure:
{
  app: {
    commerce: {
      api: {
        clientId: 'abc123'
      }
    }
  }
}
```

### Value Types

Values are automatically parsed to the correct type:

```bash
PUBLIC__app__myFeature__count=42           # → number
PUBLIC__app__myFeature__enabled=true       # → boolean
PUBLIC__app__myFeature__items=["a","b"]    # → array
PUBLIC__app__myFeature__data='{"x":1}'     # → object
PUBLIC__app__myFeature__name=hello         # → string
PUBLIC__app__myFeature__value=             # → empty string
```

You can also set entire nested objects at once using JSON:

```bash
# Instead of setting each value separately:
PUBLIC__app__myFeature__option1=value1
PUBLIC__app__myFeature__option2=value2
PUBLIC__app__myFeature__nested__enabled=true

# Use a single JSON value:
PUBLIC__app__myFeature='{"option1":"value1","option2":"value2","nested":{"enabled":true}}'
```

### Important Notes

**Case doesn't matter:** You can use any casing (lowercase, UPPERCASE, or MixedCase), and it will normalize to match your `config.server.ts`:

```bash
PUBLIC__app__commerce__api__clientId=abc123    # ✅ Works
PUBLIC__APP__COMMERCE__API__CLIENTID=abc123    # ✅ Also works
PUBLIC__App__Commerce__Api__ClientId=abc123    # ✅ Also works
```

**Paths must exist in config:** You can only override paths that are already defined in `config.server.ts`. This prevents typos from silently failing:

```bash
PUBLIC__app__site__local=en-GB  # ❌ Error: "local" doesn't exist (did you mean "locale"?)
```

**More specific paths win:** When paths overlap, deeper paths take precedence:

```bash
PUBLIC__app__myFeature='{"setting1":500,"setting2":1000}'
PUBLIC__app__myFeature__setting1=999  # ← This wins (more specific)
# Result: setting1=999, setting2=1000
```

**Depth limit:** Paths are limited to 10 levels deep. For deeper structures, use JSON values instead:

```bash
# ❌ Too deep (11 levels):
PUBLIC__a__b__c__d__e__f__g__h__i__j__k=value

# ✅ Use JSON instead:
PUBLIC__app__myFeature='{"deep":{"nested":{"structure":{"works":"fine"}}}}'
```

### Security: PUBLIC\_\_ vs Non-Prefixed

**`PUBLIC__` prefix** → Exposed to the browser (bundled into client JavaScript)

- ✅ Use for: Client IDs, site IDs, locales, feature flags, public API endpoints
- ❌ Never use for: API secrets, passwords, private keys, authentication tokens

**No prefix** → Server-only (never exposed to client)

- ✅ Use for: SLAS secrets, database credentials, private tokens

```bash
# ✅ Safe to expose to client:
PUBLIC__app__commerce__api__clientId=abc123

# ✅ Server-only secret (no PUBLIC__ prefix):
COMMERCE_API_SLAS_SECRET=your-secret-here
```

Read server-only secrets directly from `process.env` in your server code—never add them to config.

### Merge Behavior

Environment variables are **deep merged** into defaults from `config.server.ts`:

```typescript
// config.server.ts (defaults)
export default defineConfig({
  app: {
    myFeature: {
      debounce: 750,
      maxItems: 999,
      enabled: true,
    }
  }
});

// With env var:
// PUBLIC__app__myFeature__debounce=1000

// Final result:
{
  app: {
    myFeature: {
      debounce: 1000,        // ← overridden
      maxItems: 999,         // ← preserved
      enabled: true,         // ← preserved
    }
  }
}
```

## Adding Configuration

### 1. Update the type (`src/types/config.ts`)

The template defines its own `AppConfig` type with all the fields it needs — SCAPI credentials,
pages, features, and any custom domain fields. `BaseConfig<AppConfig>` wraps it with `metadata`
and `runtime` sections:

```typescript
import type { BaseConfig } from "@salesforce/storefront-next-runtime/config";
import type { Site, Url } from "@salesforce/storefront-next-runtime/config";

// Define all app fields in one flat type
export type AppConfig = {
  commerce: { api: { clientId: string /* ... */ }; sites: Array<Site> };
  defaultSiteId: string;
  url?: Url;
  myFeature: {
    enabled: boolean;
    maxItems: number;
  };
  // ...other template-specific fields (pages, features, global, etc.)
};

// Full config type used by config.server.ts
export type Config = BaseConfig<AppConfig>;
```

### 2. Add default value (`config.server.ts`)

```typescript
import { defineConfig } from "@salesforce/storefront-next-runtime/config";
import type { Config } from "./src/types/config";

export default defineConfig<Config>({
  metadata: { projectName: "My Store", projectSlug: "my-store" },
  app: {
    // SCAPI fields
    commerce: { api: { clientId: "", organizationId: "", siteId: "", shortCode: "" }, sites: [] },
    defaultSiteId: "RefArch",
    // Template-specific fields
    myFeature: {
      enabled: false, // Just the default - no process.env needed!
      maxItems: 10,
    },
  },
});
```

### 3. Override via environment variables

```bash
# No code changes needed - just use the PUBLIC__ prefix!
PUBLIC__app__myFeature__enabled=true
PUBLIC__app__myFeature__maxItems=20
```

### 4. Use it in your code

**In React components:**

```typescript
import { useConfig } from "@salesforce/storefront-next-runtime/config";

export function MyComponent() {
  const config = useConfig();

  if (config.myFeature.enabled) {
    const maxItems = config.myFeature.maxItems;
    // Your feature code here
  }
}
```

**In loaders/actions:**

```typescript
import { getConfig } from "@salesforce/storefront-next-runtime/config";

export function loader({ context }: LoaderFunctionArgs) {
  const config = getConfig(context);

  if (config.myFeature.enabled) {
    // Your loader code here
  }
}
```

### 5. Add a new config value during app creation

**In config-meta.json:**

- Add the name and key value to the config array
- This will cause the create-storefront script to ask for user input, using the value in `.env.default` as default value

```json
{
  "configs": [
    {
      "name": "SLAS Client ID",
      "key": "PUBLIC__app__commerce__api__clientId"
    },
    {
      "name": "Organization ID",
      "key": "PUBLIC__app__commerce__api__organizationId"
    },
    {
      "name": "Short Code",
      "key": "PUBLIC__app__commerce__api__shortCode"
    }
  ]
}
```

## Security: Public vs. Private Configuration

The `PUBLIC__` prefix indicates values that are **safe to expose to the browser**. These values are bundled into client-side JavaScript.

**important:** Don't use `PUBLIC__` for secrets, API keys, passwords, or authentication tokens. These values are visible to anyone who uses your site.

| Use `PUBLIC__` For     | Use Non-Prefixed For  |
| ---------------------- | --------------------- |
| Client IDs             | API secrets           |
| Site IDs               | Private keys          |
| Locales and currencies | Database credentials  |
| Feature flags          | Authentication tokens |
| Public API endpoints   | SLAS secrets          |

For server-only secrets, use environment variables without the `PUBLIC__` prefix and read them directly from `process.env`.

```bash
# .env - Server-only secret (no PUBLIC__ prefix)
COMMERCE_API_SLAS_SECRET=your-secret-here
```

```typescript
// In server-side code only
const slasSecret = process.env.COMMERCE_API_SLAS_SECRET;
```

## Commerce Sites Configuration

Site-level settings (default locale, default currency, supported locales/currencies, cookie domain) come from the **`commerce.sites`** config array. You can override it with the environment variable **`PUBLIC__app__commerce__sites`**, set to a JSON array.

```bash
# Example: one site with multiple locales and currencies (single line)
PUBLIC__app__commerce__sites='[{"cookies":{"domain":null},"id":"RefArchGlobal","defaultLocale":"en-GB","defaultCurrency":"USD","supportedLocales":[{"id":"en-GB","preferredCurrency":"USD"},{"id":"de-DE","preferredCurrency":"EUR"}],"supportedCurrencies":["EUR","USD"]}]'
```

Multi-line JSON is supported in `.env` files:

```bash
# Multi-line format (easier to read and edit)
PUBLIC__app__commerce__sites='[
  {
    "id": "RefArchGlobal",
    "defaultLocale": "en-GB",
    "defaultCurrency": "GBP",
    "cookies": {"domain": null},
    "supportedLocales": [
      {"id": "en-US", "preferredCurrency": "USD"},
      {"id": "de-DE", "preferredCurrency": "EUR"},
      {"id": "en-GB", "preferredCurrency": "GBP"}
    ],
    "supportedCurrencies": ["EUR", "GBP", "USD"]
  }
]'
```

### Per-Site Cookie Domain Override

Each site can specify its own `cookies.domain` to override the global `app.cookies.domain` setting. This is useful when different sites need different cookie scoping:

```bash
PUBLIC__app__commerce__sites='[
  {
    "id": "SiteA",
    "cookies": {"domain": ".example.com"},
    ...
  },
  {
    "id": "SiteB",
    "cookies": {"domain": ".other-domain.com"},
    ...
  }
]'
```

For the full schema, all properties, and troubleshooting, see [Configure Multisite URLs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-multi-site.md).

## Accessing Configuration

### In Loaders and Actions

Use `getConfig()` with the router context.

```typescript
import { getConfig } from "@salesforce/storefront-next-runtime/config";

export function loader({ context }: LoaderFunctionArgs) {
  const config = getConfig(context);
  const { clientId, siteId } = config.commerce.api;
  return { siteId };
}

export async function action({ context, request }: ActionFunctionArgs) {
  const config = getConfig(context);
  // Use config values...
}
```

### In React Components

Use the `useConfig()` hook:

```typescript
import { useConfig } from "@salesforce/storefront-next-runtime/config";

function Header() {
  const config = useConfig();
  return <h1>{config.global.branding.name}</h1>;
}
```

### In Client Loaders

Client loaders don't have access to router context. Call `getConfig()` without arguments.

```typescript
export function clientLoader() {
  const config = getConfig(); // Uses window.__APP_CONFIG__
  return { limit: config.search.products.hits.limit };
}
```

### In Custom Middleware

Custom middleware can read the resolved app config from `appConfigContext`:

```typescript
import { appConfigContext } from "@salesforce/storefront-next-runtime/config";

const config = context.get(appConfigContext);
```

## Adding New Configuration

To add a new configuration value, follow these steps.

### 1. Update the Type

The template defines its own `AppConfig` type with all the fields it needs. Update `src/types/config.ts`:

```typescript
import type { BaseConfig } from "@salesforce/storefront-next-runtime/config";
import type { Site, Url } from "@salesforce/storefront-next-runtime/config";

// Define all app fields in one flat type
export type AppConfig = {
  commerce: { api: { clientId: string /* ... */ }; sites: Array<Site> };
  defaultSiteId: string;
  url?: Url;
  myFeature: {
    enabled: boolean;
    maxItems: number;
  };
  // ...other template-specific fields (pages, features, global, etc.)
};

// Full config type used by config.server.ts
export type Config = BaseConfig<AppConfig>;
```

### 2. Add Default Value

Add the default in `config.server.ts`:

```typescript
import { defineConfig } from "@salesforce/storefront-next-runtime/config";
import type { Config } from "./src/types/config";

export default defineConfig<Config>({
  metadata: { projectName: "My Store", projectSlug: "my-store" },
  app: {
    // SCAPI fields
    commerce: { api: { clientId: "", organizationId: "", siteId: "", shortCode: "" }, sites: [] },
    defaultSiteId: "RefArch",
    // Template-specific fields
    myFeature: {
      enabled: false, // Just the default - no process.env needed!
      maxItems: 10,
    },
  },
});
```

### 3. Override via Environment Variables

No code changes needed. Use the `PUBLIC__` prefix:

```bash
PUBLIC__app__myFeature__enabled=true
PUBLIC__app__myFeature__maxItems=20
```

### 4. Use in Your Code

**In React components:**

```typescript
import { useConfig } from "@salesforce/storefront-next-runtime/config";

export function MyComponent() {
  const config = useConfig();

  if (config.myFeature.enabled) {
    const maxItems = config.myFeature.maxItems;
    // Your feature code here
  }
}
```

**In loaders/actions:**

```typescript
import { getConfig } from "@salesforce/storefront-next-runtime/config";

export function loader({ context }: LoaderFunctionArgs) {
  const config = getConfig(context);

  if (config.myFeature.enabled) {
    // Your loader code here
  }
}
```

### 5. Add to config-meta.json (Optional)

If you want the create-storefront script to prompt for this value during app creation:

```json
{
  "configs": [
    {
      "name": "SLAS Client ID",
      "key": "PUBLIC__app__commerce__api__clientId"
    },
    {
      "name": "My Feature Max Items",
      "key": "PUBLIC__app__myFeature__maxItems"
    }
  ]
}
```

This causes the create-storefront script to ask for user input, using the value in `.env.default` as the default value.

## Extension Configuration

Extensions add configuration without editing `src/types/config.ts` or `config.server.ts`.

### Extension Config Auto-Discovery

Drop a `config.ts` in your extension folder that default-exports a plain object. The build prestep (`pnpm dev` / `pnpm build`) discovers it, merges it into `config.app.extension.<camelCaseFolder>`, and derives the type automatically.

```typescript
// src/extensions/my-feature/config.ts
export default {
  enabled: false,
  timeout: 5000,
};
```

Merchants override per environment with `PUBLIC__app__extension__<key>__<setting>`:

```bash
PUBLIC__app__extension__myFeature__enabled=true
PUBLIC__app__extension__myFeature__timeout=3000
```

No core-file edits needed. Extension keys are set via `PUBLIC__` env vars / `.env`; they are not added to `config-meta.json`, so they don't appear in create-storefront prompts.

### Server-Only Extension Config

`config.ts` reaches the browser by design. For values an extension needs at runtime that must **never** be serialized into `window.__APP_CONFIG__` (vendor-side SCAPI service overrides, retry budgets, internal-only endpoints), drop a `server-config.ts` next to `config.ts`:

```typescript
// src/extensions/loqate-address-verification/server-config.ts
export default {
  scapiOverride: "",
  retryBudget: 3,
};
```

Read the value from a server loader, action, or middleware:

```typescript
import { getConfig } from "@salesforce/storefront-next-runtime/config";

export function loader({ context }: LoaderFunctionArgs) {
  const { scapiOverride } = getConfig(context).serverExtension?.loqateAddressVerification ?? {};
  // …
}
```

The build prestep aggregates every extension's `server-config.ts` into `src/extensions/config/server.ts` (auto-generated, do not edit) and merges it into `config.app.serverExtension.<camelCaseFolder>`.

**Three structural guarantees keep the values off the client:**

1. The client config extractor (`src/lib/app-config-client.ts`) strips `app.serverExtension` before writing `window.__APP_CONFIG__`.
2. A Vite plugin (`vite-plugins/server-only-config-guard.ts`) fails the build if any client chunk imports `src/extensions/config/server`.
3. `useConfig()` and `getConfig()`'s client-facing overloads (no-arg and `getConfig(ctx | undefined)`) are type-narrowed to omit `app.serverExtension`, so reading `.serverExtension` from any of them is a TypeScript error in client code. The server `getConfig(context)` overload still returns the full shape.

There is no `PUBLIC__` override path by design — the AST validator runs on `server-config.ts`, so a `process.env.X` read throws at discovery time. For true secrets that _must_ vary per environment (SLAS secrets, Marketing Cloud credentials), keep using `process.env` from a server route — never put them in `server-config.ts`.

For more information, see the [Extensions documentation](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/src/extensions/README.md) in the template GitHub repo.

## Testing

The template provides shared test utilities for components and hooks that depend on config:

```typescript
import {
  mockConfig,
  mockBuildConfig,
  ConfigWrapper,
  createConfigWrapper,
} from "@/test-utils/config";

// Use the default wrapper
renderHook(() => useConfig(), { wrapper: ConfigWrapper });

// Use a wrapper with custom overrides (deep merged)
const CustomWrapper = createConfigWrapper({
  app: {
    pages: {
      cart: {
        maxQuantityPerItem: 5,
      },
    },
  },
});
renderHook(() => useConfig(), { wrapper: CustomWrapper });
```

- `mockBuildConfig` — a full `Config` object with realistic test values
- `mockConfig` — the `app` section (i.e., `mockBuildConfig.app`)
- `ConfigWrapper` — a ready-to-use wrapper component for `renderHook` / `render`
- `createConfigWrapper(overrides?)` — creates a wrapper with custom config (deep-merges nested overrides)

For tests that need all providers (config + currency + store locator), use `AllProvidersWrapper` from `@/test-utils/context-provider`.

## Marketing Cloud Configuration (Server-Only)

Marketing Cloud is used for sending emails in features like passwordless login and password reset. The configuration is optional and only required if you're using these features.

### Environment Variables

```bash
# Marketing Cloud API Configuration (Server-only - NO PUBLIC__ prefix)
MARKETING_CLOUD_CLIENT_ID=your-client-id
MARKETING_CLOUD_CLIENT_SECRET=your-client-secret
MARKETING_CLOUD_SUBDOMAIN=your-subdomain
MARKETING_CLOUD_PASSWORDLESS_LOGIN_TEMPLATE=your-passwordless-template-id
MARKETING_CLOUD_RESET_PASSWORD_TEMPLATE=your-reset-password-template-id
```

**Important Security Notes:**

- ❌ These variables do NOT have the `PUBLIC__` prefix - they are **server-only**
- ❌ They are NOT included in `config.server.ts` or exposed to the client
- ✅ Read them directly from `process.env` in server-side code

## Deployment

When deploying to Managed Runtime (MRT), set your environment variables in the Runtime Admin.

1. Log in to the Runtime Admin.
2. Navigate to your project → Environment Variables.
3. Add the required `PUBLIC__` variables.
4. Add any server-only secrets without the `PUBLIC__` prefix.
5. Deploy your app.

All the same rules apply: use the `PUBLIC__` prefix for client-safe values, use the `__` path syntax for nested config, and read server-only secrets directly from `process.env`.

**MRT limits:** Variable names max 512 characters, total `PUBLIC__` values max 32 KB. Use JSON to consolidate related settings if needed.

[Learn more about MRT environment variables →](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html)

## Common Issues

### Changed `.env` but Nothing Happened?

Restart your dev server. Environment variables are loaded at startup.

### Environment Variable Not Working?

- Verify the variable name starts with `PUBLIC__` (double underscore after PUBLIC)
- Check the `.env` file is in the project root
- Ensure that the path exists in `config.server.ts`—you can only override existing paths
- For booleans, use string `"true"` not bare `true`

### Type Errors After Adding Configuration?

Update both `src/types/config.ts` (types) and `config.server.ts` (defaults) to match.

### App Won't Start—Missing Credentials?

Copy `.env.default` to `.env` and set the required B2C Commerce credentials. See [Required for the app to start](#required-for-the-app-to-start).

### Path Validation Error?

The configuration system validates that environment variable paths exist in your config. If you see an error like `"local" doesn't exist`, check for typos. The system suggests similar valid paths when possible.

### Locale or Translation Not Working?

If a locale or translation is missing at runtime, verify:

1. The locale is included in both `supportedLocales` for the relevant site in `commerce.sites` and in `i18n.supportedLngs`.
2. Translation files exist for the locale (for example, `public/locales/de-DE/translation.json`).
3. The locale ID uses BCP 47 hyphen format (`en-US`, not `en_US`).
4. Review `src/middlewares/i18next.ts` to confirm the locale is listed in the server-side i18next configuration.

## Optional Configuration Variables

The following optional `PUBLIC__*` environment variables can override the defaults in `config.server.ts`:

### Commerce API Settings

| Variable                                                          | Default             | Effect                                |
| ----------------------------------------------------------------- | ------------------- | ------------------------------------- |
| `PUBLIC__app__commerce__api__proxy`                               | `/mobify/proxy/api` | SCAPI proxy path                      |
| `PUBLIC__app__commerce__api__callback`                            | `/callback`         | OAuth callback path                   |
| `PUBLIC__app__commerce__api__privateKeyEnabled`                   | `false`             | Use private SLAS client               |
| `PUBLIC__app__commerce__api__guestRefreshTokenExpirySeconds`      | from API response   | Override guest refresh-token TTL      |
| `PUBLIC__app__commerce__api__registeredRefreshTokenExpirySeconds` | from API response   | Override registered refresh-token TTL |

### Feature Flags

| Variable                                                | Default              | Effect                              |
| ------------------------------------------------------- | -------------------- | ----------------------------------- |
| `PUBLIC__app__hybrid__enabled`                          | `false`              | Hybrid PWA mode                     |
| `PUBLIC__app__auth__otpLength`                          | `6`                  | OTP length (6 or 8)                 |
| `PUBLIC__app__features__passwordlessLogin__mode`        | `email`              | `email` \| `callback`               |
| `PUBLIC__app__features__otpRequest__mode`               | `email`              | `email` \| `callback`               |
| `PUBLIC__app__features__resetPassword__mode`            | `email`              | `email` \| `callback`               |
| `PUBLIC__app__features__mrtBasedPageDesignerResolution` | `false`              | Resolve PD pages via MRT Data Store |
| `PUBLIC__app__features__socialLogin__enabled`           | `true`               | Apple/Google login button           |
| `PUBLIC__app__features__socialLogin__callbackUri`       | `/social-callback`   | Social login callback path          |
| `PUBLIC__app__features__socialLogin__providers`         | `["Apple","Google"]` | Provider list                       |
| `PUBLIC__app__features__shopperContext__enabled`        | `false`              | Shopper context API                 |
| `PUBLIC__app__features__googleCloudAPI__apiKey`         | —                    | Google Address Autocomplete         |

### Site Configuration

| Variable                       | Default               | Effect                                                                                                                      |
| ------------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `PUBLIC__app__defaultSiteId`   | (single-site default) | Override default site                                                                                                       |
| `PUBLIC__app__commerce__sites` | (single-site default) | Multi-site JSON config                                                                                                      |
| `PUBLIC__app__cookies__domain` | host-only             | Global default cookie domain for all cookies (e.g. `.example.com`); per-site `commerce.sites[].cookies.domain` overrides it |

### Security

| Variable                                    | Default | Effect                           |
| ------------------------------------------- | ------- | -------------------------------- |
| `PUBLIC__app__security__turnstile__enabled` | `false` | Turnstile bot protection         |
| `PUBLIC__app__security__turnstile__sites`   | —       | Turnstile per-site configuration |

### Engagement Adapters

**note:** Engagement adapter settings (Einstein, Data 360, Active Data) cannot be overridden with `PUBLIC__` environment variables. To change adapter settings, update `config.server.ts` directly. This restriction exists because engagement configuration affects build-time validation for analytics instrumentation.

## Enabling Optional Features

Each block in this section is a copy-pasteable env snippet. Drop it into your `.env` and uncomment to enable the feature.

### Multi-site / `commerce.sites`

Single-site is the default. To enable multiple sites, define them as a JSON array:

```bash
# Single-site override
# PUBLIC__app__defaultSiteId=RefArchGlobal

# Multi-site (single-line — works for MRT and local .env)
# PUBLIC__app__commerce__sites=[{"id":"RefArch","defaultLocale":"en-US","defaultCurrency":"USD","supportedLocales":[{"id":"en-US","preferredCurrency":"USD"}],"supportedCurrencies":["USD"]}]

# Multi-site (multi-line — local .env only, easier to read)
# PUBLIC__app__commerce__sites='[
#  {
#    "id": "RefArchGlobal",
#    "defaultLocale": "en-GB",
#    "defaultCurrency": "GBP",
#    "cookies": {"domain": null},
#    "supportedLocales": [
#      {"id": "en-US", "preferredCurrency": "USD"},
#      {"id": "de-DE", "preferredCurrency": "EUR"},
#      {"id": "en-GB", "preferredCurrency": "GBP"}
#    ],
#    "supportedCurrencies": ["EUR", "GBP"]
#  }
# ]'
```

See [Configure Multisite URLs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-multi-site.md) for site-context routing details.

**note:** For MRT environment variables, convert to a single line and remove the surrounding quotes. Multi-line format works only in local `.env` files.

### Live Sites from the Data Access Layer (`commerce.sitesFromDal`)

By default, Storefront Next syncs site, locale, and currency data from Business Manager per request via the Data Access Layer (DAL). This means you don't need to edit `config.server.ts` or redeploy to pick up new sites or locale changes — Business Manager is the source of truth.

To disable DAL-sourced sites and fall back to the static `commerce.sites` array in `config.server.ts`:

```bash
# PUBLIC__app__commerce__sitesFromDal=false
```

When `sitesFromDal` is enabled (the default) and the DAL is unavailable, the storefront automatically falls back to the static `commerce.sites` configuration. See [Configure Multisite URLs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-multi-site.md) for DAL-sourced site fallback rules.

### Hybrid Proxy (local development only)

Silent HTTP proxying with cookie rewriting for a unified storefront experience. Local-dev only — production routing should use Cloudflare eCDN. Requires `SFCC_ORIGIN` and `PUBLIC__app__defaultSiteId`.

```bash
# HYBRID_PROXY_ENABLED=true
# HYBRID_PROXY_LOCALE=en-GB
# HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/product.*")'
# SFCC_ORIGIN=https://zzrf-001.dx.commercecloud.salesforce.com
```

See [Set Up Hybrid Proxy Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-proxy-local-dev.md).

### Passwordless Login (Marketing Cloud)

```bash
# PUBLIC__app__features__passwordlessLogin__mode=email
# PUBLIC__app__features__passwordlessLogin__callbackUri='/passwordless-login-callback'
# PUBLIC__app__features__passwordlessLogin__landingUri='/login'
# PUBLIC__app__features__otpRequest__mode=email
# PUBLIC__app__features__otpRequest__callbackUri='https://example.com/otp-callback'
# PUBLIC__app__features__resetPassword__mode=email
# PUBLIC__app__features__resetPassword__callbackUri='/reset-password-callback'
# PUBLIC__app__features__resetPassword__landingUri='/reset-password'
```

When using `mode=email`, also set the server-only Marketing Cloud secrets (see [Marketing Cloud Configuration](#marketing-cloud-configuration-server-only)). See [Passwordless Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passwordless-login.md).

### Turnstile Bot Protection

Cloudflare Turnstile is disabled by default. The test site key below always passes — production sites must set their own keys via MRT env vars.

```bash
# PUBLIC__security__turnstile__enabled=true
# PUBLIC__security__turnstile__sites={"local-dev":[{"siteKey":"1x00000000000000000000BB","domains":["localhost","127.0.0.1"]}]}
```

### Commerce Client (Cimulate)

```bash
# PUBLIC__app__cimulateAgent='{"enabled":true,"provider":"commerce-client","commerceClientScriptSourceUrl":"https://...","scrt2Url":"https://...","salesforceOrgId":"...","esDeveloperName":"..."}'
```

Set as a single JSON string. Required fields: `enabled`, `commerceClientScriptSourceUrl`, `scrt2Url`, `salesforceOrgId`, `esDeveloperName`. See `src/components/cimulate/README.md` for setup.

See [Shopping Agent for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopping-agent.md) for environment-specific setup.

### Cookie Domain

Sets the default `Domain` on every cookie the storefront writes — auth/session and site-context (`site_id`, locale, currency). A per-site `commerce.sites[].cookies.domain` overrides it for that site. Unset = host-only scoping; setting a domain is opt-in.

```bash
# PUBLIC__app__cookies__domain=.example.com
```

See the [Cookie Domain Configuration guide](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/README-COOKIE-DOMAIN.md) for the full guide, including the matching Business Manager setting and rollout guidance.

### Refresh-Token Expiry Overrides

If unset, the storefront uses the expiry returned by SCAPI.

```bash
# PUBLIC__app__commerce__api__guestRefreshTokenExpirySeconds=2592000        # ~30 days
# PUBLIC__app__commerce__api__registeredRefreshTokenExpirySeconds=7776000   # ~90 days
```

### Google Cloud API Key (Address Autocomplete)

```bash
# PUBLIC__app__features__googleCloudAPI__apiKey=
```

### Logging

```bash
# SFCC_LOG_LEVEL=info   # error | warn | info | debug
```

Shared with the SDK logger (`storefront-next-dev`) for unified control.

### Managed Runtime deployment vars

Already in `.env.default` — listed here for completeness.

```bash
MRT_PROJECT=my-project-slug
MRT_TARGET=development
```

### Server-Only SLAS Secret

```bash
# COMMERCE_API_SLAS_SECRET=your-secret-here
```

Read directly from `process.env` in server-side code (loaders, actions, middleware). Never prefix with `PUBLIC__`.

### JSON configuration pattern

Complex values can be encoded as JSON strings—the merge mechanism parses any value that looks like JSON.

```bash
# Override multiple cart configuration values at once
# PUBLIC__app__pages__cart='{"quantityUpdateDebounce":1000,"maxQuantityPerItem":500,"enableSaveForLater":true}'
```

## Configuration Options Reference

This section provides detailed documentation for all configuration options available in `config.server.ts`. For the complete reference with all options, descriptions, defaults, and examples, see the [Configuration Options Reference](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/README-CONFIG-OPTIONS.md) in the template GitHub repo.

Key configuration categories include:

- **metadata** - Project identification and metadata
- **runtime** - Runtime deployment settings for MRT
- **app** - Application-specific configuration
  - **pages** - Page-specific settings (navigation, cart, search, home)
  - **commerce** - B2C Commerce API details and site configuration
  - **hybrid** - Hybrid mode configuration
  - **auth** - Authentication configuration (OTP length, etc.)
  - **security** - Security headers and Turnstile configuration
  - **features** - Feature flags (passwordless login, social login, etc.)
  - **i18n** - Internationalization settings
  - **global** - Global UI and component settings (branding, badges, recommendations)
  - **links** - Link hints for browser resource loading
  - **images** - Dynamic Imaging Service settings
  - **search** - Search-specific settings
  - **performance** - Performance optimization settings
  - **engagement** - Analytics and engagement adapters
  - **commerceAgent** - Shopper Agent (Embedded Messaging / Agentforce)
  - **development** - Development tools and features

### Notable Configuration Options

The following options are commonly needed but not covered elsewhere in this guide.

#### Passkey (WebAuthn) Feature Flags

| Option                         | Type                    | Default | Notes                                                         |
| ------------------------------ | ----------------------- | ------- | ------------------------------------------------------------- |
| `features.passkey.enabled`     | `boolean`               | `false` | Requires `sfcc.pwdless_login` scope on your SLAS client.      |
| `features.passkey.mode`        | `'email' \| 'callback'` | `email` | SLAS does not support `'sms'` mode for passkey authorization. |
| `features.passkey.callbackUri` | `string`                | —       | Callback URI for passkey authorization redirect flow.         |

#### Guest Checkout

| Option                   | Type      | Default | Notes                          |
| ------------------------ | --------- | ------- | ------------------------------ |
| `features.guestCheckout` | `boolean` | `true`  | Allow unauthenticated checkout |

#### Social Share

| Option                           | Type       | Default                                        | Notes                         |
| -------------------------------- | ---------- | ---------------------------------------------- | ----------------------------- |
| `features.socialShare.enabled`   | `boolean`  | `true`                                         | Enable product social sharing |
| `features.socialShare.providers` | `string[]` | `['Twitter', 'Facebook', 'LinkedIn', 'Email']` | List of share provider names  |

#### Shopper Context Source Code Suffix

| Option                                             | Type     | Default | Notes                                                                  |
| -------------------------------------------------- | -------- | ------- | ---------------------------------------------------------------------- |
| `features.shopperContext.dwsourcecodeCookieSuffix` | `string` | —       | Cookie suffix for campaign attribution via shopper context source code |

#### Category Page Pagination (`src/lib/config.ui.ts`)

The PLP (Product Listing Page) pagination is configured in `src/lib/config.ui.ts` rather than `config.server.ts` and cannot be overridden via `PUBLIC__` env vars.

| Option                                               | Type                           | Default       | Notes                             |
| ---------------------------------------------------- | ------------------------------ | ------------- | --------------------------------- |
| `uiConfig.pages.category.pagination.mode`            | `'load-more' \| 'traditional'` | `'load-more'` | Pagination UI mode                |
| `uiConfig.pages.category.pagination.batchSize`       | `number`                       | `25`          | Products per page/load-more batch |
| `uiConfig.pages.category.pagination.mobileBatchSize` | `number`                       | `25`          | Products per batch on mobile      |
| `uiConfig.pages.category.pagination.maxProducts`     | `number`                       | `200`         | Maximum total products rendered   |

#### Engagement Adapter Options

Engagement adapter settings must be configured directly in `config.server.ts`. They cannot be overridden via `PUBLIC__` environment variables because engagement configuration affects build-time validation for analytics instrumentation.

| Option                                  | Notes                                          |
| --------------------------------------- | ---------------------------------------------- |
| `engagement.adapters[].consentCategory` | Consent category required before firing events |
| `engagement.adapters[].eventToggles`    | Per-event on/off switches                      |
| `engagement.adapters[].webStoreId`      | Web store ID required for Data 360 adapter     |

**See Also**

- [Security Response Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-security-headers.md)

<!-- document id=baca79c805c2bee45d1163e437f56faae1aed7b39ffc2263dff03f9913db4351 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-project-config-build-tools.md -->

# Project Configuration and Build Tools

Learn how to structure, configure, and build your Storefront Next project. This section covers the file and folder organization of a Storefront Next app, the configuration options that control runtime and build behavior, and the build tools that power the development and deployment process.

In this section:

- [Project Structure](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-structure.md)
- [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md)
- [Build Tools](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-build-tools.md)

<!-- document id=142f6503d2f4b0bfdc1a7613d825109a914a821ae3250ce46d24b166b240d52b url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-project-config.md -->

# Project Configuration Differences with PWA Kit

PWA Kit uses JavaScript configuration with looser runtime validation and flatter structures. Storefront Next introduces typed config definitions, structured namespaces, and an environment-variable override model designed for safer server-client separation. Access patterns also become more context-aware on the server and hook-based in React components.

## Configuration Definition

| Aspect            | PWA Kit                  | Storefront Next                         |
| ----------------- | ------------------------ | --------------------------------------- |
| Language          | JavaScript               | TypeScript                              |
| Type Safety       | None (runtime)           | Full type definitions                   |
| Location          | `config/default.js`      | `config.server.ts`                      |
| Helper Function   | None                     | `defineConfig()` for IDE autocomplete   |
| Multi-site Config | Separate `sites.js` file | Simplified (single locale and currency) |

## Environment Variable Support

| Aspect            | PWA Kit                      | Storefront Next                 |
| ----------------- | ---------------------------- | ------------------------------- |
| Override System   | Limited (specific vars only) | Full path-based override system |
| Naming Convention | Custom per variable          | `PUBLIC__path__to__config`      |
| JSON Parsing      | Manual                       | Automatic                       |
| Validation        | None                         | Strict schema validation        |
| Client Exposure   | N/A                          | `PUBLIC__` prefix = client-safe |

## Accessing Configuration

| Aspect           | PWA Kit       | Storefront Next                |
| ---------------- | ------------- | ------------------------------ |
| Server Access    | `getConfig()` | `getConfig(context)`           |
| Client Access    | `getConfig()` | `getConfig()` or `useConfig()` |
| React Components | `getConfig()` | `useConfig()` hook required    |
| Type Inference   | None          | Full TypeScript types          |
| Context Required | No            | Yes (server-side)              |

## Configuration Scope

| Feature       | PWA Kit                               | Storefront Next               |
| ------------- | ------------------------------------- | ----------------------------- |
| Commerce API  | `app.commerceAPI.parameters`          | `app.commerce.api`            |
| Feature Flags | Top-level booleans                    | `app.site.features` namespace |
| Analytics     | `app.einsteinAPI`, `app.dataCloudAPI` | `app.engagement.adapters`     |
| UI Settings   | N/A                                   | `app.pages`, `app.global`     |
| Performance   | N/A                                   | `app.performance`             |
| i18n          | In `sites.js`                         | `app.i18n`                    |

## Example: Accessing Commerce API Config

PWA Kit:

```javascript
import { getConfig } from "@salesforce/pwa-kit-runtime/utils/ssr-config";

const { clientId, siteId } = getConfig().app.commerceAPI.parameters;
```

Storefront Next:

```typescript
import { getConfig } from "@/config";

// In a loader
export function loader({ context }: LoaderFunctionArgs) {
  const { clientId, siteId } = getConfig(context).commerce.api;
}

// In a component
function MyComponent() {
  const { clientId, siteId } = useConfig().commerce.api;
}
```

## Example: Feature Flag Check

PWA Kit:

```javascript
const storeLocatorEnabled = getConfig()?.app?.storeLocatorEnabled ?? true;
const { passwordless = {} } = getConfig().app.login || {};
```

Storefront Next:

```typescript
const config = useConfig();
const passwordlessEnabled = config.site.features.passwordlessLogin.enabled;
const socialLoginProviders = config.site.features.socialLogin.providers;
```

---

## Key Differences

1. Type Safety: Storefront Next provides full TypeScript type definitions, while PWA Kit uses plain JavaScript with no type checking.

2. Environment Variables: Storefront Next has a sophisticated environment variable override system with validation, while PWA Kit relies on hardcoded values or manually-implemented env var handling.

3. Context Requirement: Storefront Next requires passing router context to access config in server-side code, enabling proper isolation between requests. PWA Kit uses a global singleton.

4. React Integration: Storefront Next requires using `useConfig()` hook in React components (proper React Context pattern), while PWA Kit allows calling `getConfig()` anywhere.

5. Configuration Scope: Storefront Next organizes configuration into clear namespaces (`pages`, `commerce`, `site`, `global`, `performance`, `engagement`), while PWA Kit uses a flatter structure with mixed concerns.

6. Multi-Site: PWA Kit has built-in multi-site configuration in `sites.js` with complex locale and currency mappings. Storefront Next simplifies this with single locale and currency values. Multi-site can be handled differently.

## Storefront Conversion Considerations

## Configuration File Changes

| PWA Kit                               | Storefront Next                   |
| ------------------------------------- | --------------------------------- |
| `config/default.js`                   | `config.server.ts`                |
| `config/sites.js`                     | Locale and currency in `app.site` |
| `app.commerceAPI.parameters.clientId` | `app.commerce.api.clientId`       |
| `app.storeLocatorEnabled`             | Move to extension config          |
| `app.multishipEnabled`                | Move to extension config          |

## Code Conversion

Before (PWA Kit):

```javascript
import { getConfig } from "@salesforce/pwa-kit-runtime/utils/ssr-config";

function ProductDetail() {
  const storeLocatorEnabled = getConfig()?.app?.storeLocatorEnabled ?? true;
  const { clientId } = getConfig().app.commerceAPI.parameters;
  // ...
}
```

After (Storefront Next):

```typescript
import { useConfig } from "@/config";

function ProductDetail() {
  const config = useConfig();
  const { clientId } = config.commerce.api;
  // storeLocatorEnabled is now in extension config
  // ...
}
```

## Environment Variables

Before (PWA Kit):

```bash
# Limited environment variable support
# Most values hardcoded in config/default.js
```

After (Storefront Next):

```bash
# Required Commerce API credentials
PUBLIC__app__commerce__api__clientId=your-client-id
PUBLIC__app__commerce__api__organizationId=your-org-id
PUBLIC__app__commerce__api__siteId=your-site-id
PUBLIC__app__commerce__api__shortCode=your-short-code

# Optional feature toggles
PUBLIC__app__site__features__socialLogin__enabled=true
PUBLIC__app__pages__cart__maxQuantityPerItem=10
```

## Server-Only Secrets

In Storefront Next, server-only secrets (like SLAS private key) should NOT use the `PUBLIC__` config system:

```typescript
// In server-side code only
const slasSecret = process.env.COMMERCE_API_SLAS_SECRET;
```

<!-- document id=8451515e9f68e91940a5681b90f56ec9f21daaf3df0de024b69ca03faa891fe9 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-project-structure.md -->

# Project Structure

Learn about the Storefront Next project structure to navigate code quickly and follow conventions that keep your codebase maintainable as it grows.

## Overview

A Storefront Next project is built on [React Router 7](https://reactrouter.com/) in framework mode, and uses [Vite](https://vitejs.dev/) as the build tool. The structure separates your app code (`src/`) from configuration files at the project root.

```
my-storefront/
├── src/                        # Application code
│   ├── routes/                 # Page components (file-based routing)
│   ├── components/             # Reusable UI components
│   ├── lib/                    # Utilities and API clients
│   ├── hooks/                  # Custom React hooks
│   ├── providers/              # React context providers
│   ├── middlewares/            # Request/response middleware
│   ├── locales/                # Translation files
│   ├── root.tsx                # Application shell and layout
│   ├── routes.ts               # Route configuration
│   └── app.css                 # Global styles (Tailwind)
├── public/                     # Static assets (images, fonts)
├── types/                      # TypeScript type definitions
├── config.server.ts            # Commerce API and site configuration
├── vite.config.ts              # Build configuration
├── react-router.config.ts      # React Router settings
└── package.json                # Dependencies and scripts
```

## Application Code in `src/`

### Routes

The `routes/` directory contains your page components. Storefront Next uses React Router's [file-based routing](https://reactrouter.com/how-to/file-route-conventions), where file names determine URL paths.

```
src/routes/
├── _index.tsx                  # Home page (/)
├── category.$.tsx              # Category pages (/category/*)
├── product.$productId.tsx      # Product pages (/product/:productId)
├── cart.tsx                    # Cart page (/cart)
├── checkout.tsx                # Checkout (/checkout)
├── account.tsx                 # Account layout
├── account._index.tsx          # Account home (/account)
├── account.orders.tsx          # Order history (/account/orders)
└── action.cart-item-add.tsx    # Server action for adding to cart
```

## File Naming Conventions

| Pattern            | Example                    | URL                   | Purpose                               |
| ------------------ | -------------------------- | --------------------- | ------------------------------------- |
| `_index.tsx`       | `_index.tsx`               | `/`                   | Index route (renders at parent path)  |
| `name.tsx`         | `cart.tsx`                 | `/cart`               | Static route                          |
| `$param`           | `product.$productId.tsx`   | `/product/:productId` | Dynamic segment that captures a value |
| `$.tsx`            | `category.$.tsx`           | `/category/*`         | Splat/catch-all route                 |
| `parent.child.tsx` | `account.orders.tsx`       | `/account/orders`     | Nested route                          |
| `action.*`         | `action.cart-item-add.tsx` | —                     | Server action (not a navigable page)  |

**note:** Files starting with underscore (`_`) have special meaning. `_index.tsx` renders at the parent path, while a `_layout.tsx` file creates a layout wrapper without adding a URL segment.

The `routes.ts` file configures routing behavior. The `flatRoutes()` function scans your `src/routes/` directory and generates route configuration automatically based on file names. You rarely have to modify this file.

```typescript
// src/routes.ts
import { type RouteConfig } from '@react-router/dev/routes';
import { flatRoutes } from '@react-router/fs-routes';

export default flatRoutes() satisfies RouteConfig;
```

<!-- For more details on routing patterns, see [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-routing.md). -->

### Components

The `components/` directory contains reusable UI elements organized by feature area.

```
src/components/
├── ui/                         # Base UI primitives (buttons, inputs, dialogs)
├── header/                     # Site header and navigation
├── footer/                     # Site footer
├── product-view/               # Product display components
├── product-tile/               # Product cards for listings
├── cart/                       # Cart components
└── ...
```

The `ui/` subdirectory contains [shadcn/ui](https://ui.shadcn.com/) components—accessible, customizable primitives that you can modify directly.

Create a component when:

- The UI element is used in multiple places.
- The component encapsulates complex logic or state.
- You want to test the UI in isolation (via Storybook).

<!-- For more on the component library, see [Components](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-components.md). -->

### Lib

The `lib/` directory contains utilities, API clients, and business logic that isn't tied to React.

```
src/lib/
├── api/                        # Commerce API client functions
├── utils/                      # General utilities (formatting, validation)
└── ...
```

Place code here when it:

- Doesn't use React hooks or components.
- Could be shared across multiple routes or components.
- Handles data transformation or business logic.

### Hooks

Custom React hooks extract reusable stateful logic from components.

```
src/hooks/
├── use-product.ts              # Product data access
├── use-cart.ts                 # Cart operations
├── use-navigation.ts           # Navigation utilities
└── ...
```

**When to create a custom hook:**

- Multiple components need the same stateful logic.
- You want to encapsulate complex operations (like API calls with loading states).
- You must share behavior across routes.

### Providers

React context providers supply data and functionality throughout the app.

```
src/providers/
├── cart-provider.tsx           # Cart state and operations
├── locale-provider.tsx         # Internationalization context
└── ...
```

Providers wrap the app in `root.tsx` and make data available to any nested component without prop drilling.

### Middlewares

Request and response middleware that runs before route loaders:

```
src/middlewares/
├── auth-middleware.server.ts   # Authentication (server-side)
├── auth-middleware.client.ts   # Authentication (client-side)
├── i18n-middleware.ts          # Locale detection and setup
└── ...
```

Middleware is registered in `root.tsx` and executes in order for each request. Use middleware to:

- Parse authentication tokens
- Detect user locale
- Set up shared context that loaders need

For details on implementing middleware, see [Storage and Sessions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storage-sessions.md).

### Locales

Translation files for internationalization:

```
src/locales/
├── en-US.json
├── fr-FR.json
└── ...
```

See [Internationalization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-intl.md) for setup and usage.

## Root File (`root.tsx`)

The `root.tsx` file is your app's entry point. It exports several key pieces that define your app's behavior:

| Export             | Purpose                                                                  |
| ------------------ | ------------------------------------------------------------------------ |
| `middleware`       | Server middleware chain (auth, locale detection)                         |
| `clientMiddleware` | Client middleware chain (runs during client navigation)                  |
| `loader`           | Root data loader (fetches data needed by all pages)                      |
| `Layout`           | HTML document structure (`<html>`, `<head>`, `<body>`)                   |
| `default` (App)    | Application shell with header, footer, and `<Outlet />` for page content |

Most customization happens in middleware and the App component. Typically, you only need to modify Layout when changing document-level meta tags or adding scripts.

## Configuration Files

| File                                                                                                 | Purpose                                                                                                      |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `config.server.ts`                                                                                   | Commerce API connection and storefront settings. See [Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md).              |
| `vite.config.ts`                                                                                     | Build plugins, path aliases, Server-Side Rendering (SSR) settings. See [Build Tools](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-build-tools.md). |
| [`react-router.config.ts`](https://reactrouter.com/api/framework-conventions/react-router.config.ts) | React Router framework options                                                                               |
| `tsconfig.json`                                                                                      | TypeScript compiler options                                                                                  |
| `package.json`                                                                                       | Dependencies and npm scripts                                                                                 |

## Where to Put Code Elements

| You want to...                            | Put it in...                         |
| ----------------------------------------- | ------------------------------------ |
| Add a new page                            | `src/routes/` (file name = URL path) |
| Create a reusable component               | `src/components/`                    |
| Add a server action                       | `src/routes/action.*.tsx`            |
| Add a utility function                    | `src/lib/`                           |
| Create a custom hook                      | `src/hooks/`                         |
| Add translations                          | `src/locales/`                       |
| Add static assets (images)                | `public/`                            |
| Add global styles                         | `src/app.css`                        |
| Configure commerce or storefront settings | `config.server.ts`                   |

## Example: Adding a Wishlist Feature

Here's how the project structure guides you when adding a new feature:

```
src/
├── routes/
│   ├── wishlist.tsx              # 1. Page at /wishlist
│   └── action.wishlist-add.tsx   # 2. Server action for adding items
├── components/
│   └── wishlist/
│       ├── wishlist-item.tsx     # 3. UI components
│       └── wishlist-empty.tsx
├── hooks/
│   └── use-wishlist.ts           # 4. Hook for wishlist operations
└── lib/
    └── api/
        └── wishlist.ts           # 5. API client functions
```

This separation keeps your code organized.

- Routes define what URLs exist and load data.
- Components handle presentation.
- Hooks manage stateful logic.
- Lib contains pure functions and API calls.

## Customizing Entry Files

React Router provides default entry files for client hydration and server rendering. These entry files are hidden by default but can be revealed for advanced customization.

```bash
npx react-router reveal
```

This command creates `entry.client.tsx` and `entry.server.tsx` in your `src/` directory.

When to customize:

- Initialize client libraries before hydration
- Add custom error reporting (for example, Sentry)
- Modify server response headers
- Customize streaming behavior

For most projects, the default entry files work without modification.

## See Also

- [_React Router API Reference:_ React Router File Route Conventions](https://reactrouter.com/how-to/file-route-conventions)
- [_React Router API Reference:_ React Router root.tsx](https://reactrouter.com/api/framework-conventions/root.tsx)
- [\_Vite:\_Vite Configuration](https://vitejs.dev/config/)

<!-- document id=c983b6483dde11d09d14a727cae89615bdfe58fb134829c5085fdb8002c2d5ba url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-project-structure.md -->

# Project Structure Differences with PWA Kit

PWA Kit organizes most app code under `app/` with centralized route definitions and explicit runtime entry files. Storefront Next shifts to `src/`, file-based routes, and framework conventions around root and route modules. The outcome is a more convention-driven layout with clearer boundaries for routes, providers, middleware, and adapters.

## Directory Structure

| Aspect           | PWA Kit                      | Storefront Next          |
| ---------------- | ---------------------------- | ------------------------ |
| Source Directory | `app/`                       | `src/`                   |
| Page Components  | `app/pages/`                 | `src/routes/`            |
| Configuration    | `config/` (JS)               | `config.server.ts` file  |
| Translations     | `translations/` (JSON)       | `src/locales/`           |
| Static Assets    | `app/static/`, `app/assets/` | `public/`                |
| Theme/Styles     | `app/theme/` (Chakra)        | `src/app.css` (Tailwind) |
| Type Definitions | N/A (JavaScript)             | `types/`                 |

## Entry Points

| Aspect       | PWA Kit                   | Storefront Next                         |
| ------------ | ------------------------- | --------------------------------------- |
| Client Entry | `app/main.jsx` (explicit) | `entry.client.tsx` (hidden, revealable) |
| Server Entry | `app/ssr.js` (Express)    | `entry.server.tsx` (hidden, revealable) |
| Root Layout  | `app/components/_app/`    | `src/root.tsx`                          |
| Routes       | `app/routes.jsx` (array)  | `src/routes.ts` + `src/routes/` (files) |
| Config       | `config/default.js`       | `config.server.ts`                      |

## Configuration Approach

PWA Kit uses CommonJS modules:

```javascript
// config/default.js
module.exports = {
  app: {
    url: { site: "path", locale: "path" },
    commerceAPI: { clientId: "...", organizationId: "..." },
  },
};
```

Storefront Next uses TypeScript with `defineConfig`:

```typescript
// config.server.ts
import { defineConfig } from "@salesforce/storefront-next-dev";

export default defineConfig({
  app: {
    commerce: {
      api: { clientId: "...", organizationId: "..." },
    },
  },
});
```

## Key Differences

1. Language: PWA Kit uses JavaScript. Storefront Next uses TypeScript throughout.

2. Build Tool Integration: PWA Kit has separate config files for each tool. Storefront Next centralizes build config in `vite.config.ts`.

3. Server Architecture: PWA Kit uses Express with explicit route handlers. Storefront Next uses React Router's middleware pattern.

4. Entry Point Pattern: PWA Kit has separate client/server entry files. Storefront Next consolidates into `root.tsx` with exports.

5. Asset Handling: PWA Kit uses `getAssetUrl()` helper. Storefront Next uses Vite's native import system.

6. Testing: PWA Kit uses Jest; Storefront Next uses Vitest with integrated Storybook.

7. Code Organization: Storefront Next introduces `middlewares/`, `providers/`, `adapters/` directories for cleaner separation.

## Storefront Conversion Considerations

1. Move source code from `app/` to `src/`.

2. Convert pages from `app/pages/` to file-based routes in `src/routes/`.

3. Migrate configuration from `config/default.js` to `config.server.ts`.

4. Update translations from `translations/*.json` to `src/locales/`.

5. Convert JavaScript to TypeScript-add type annotations throughout.

6. Replace Express routes with middleware exports in `root.tsx` or resource routes.

7. Update static asset imports to use Vite's import system instead of `getAssetUrl()`.

8. Entry file customization: If needed, run `npx react-router reveal` to customize client/server entry points.

## References

- [React Router entry.client.tsx](https://reactrouter.com/api/framework-conventions/entry.client.tsx)
- [React Router entry.server.tsx](https://reactrouter.com/api/framework-conventions/entry.server.tsx)
- [React Router root.tsx](https://reactrouter.com/api/framework-conventions/root.tsx)

<!-- document id=ba082987f1c5a861eed544b5e2aae70eb25897f14e88a72fb95916941ab8257f url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/promotion-code-validation-spi.md -->

Promotion Code Validation SPI

# Promotion Code Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-code-validation-spi/promotion-code-validation-spi-oas-public.yaml)

Merchant SPI to validate promotion codes from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in POS CMS for the POS to use when applying promotion codes.

**Version:** 2.3.4

## Tags

### Promotion Code Validation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-code-validation-spi/promotion-code-validation-spi-oas-public.yaml)

Merchant SPI to validate promotion codes from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in POS CMS for the POS to use when applying promotion codes.

## Operations

### POST Validate promotion code.

`POST /merchant/spi/sample/endpoint/sa/promotionCodeValidation`

Operation ID: `validatePromoCode`. Tags: Promotion Code Validation SPI.

Validate a provided promotion code by checking its validity and returning the associated promotion ID. If the promotion code is valid, the response returns the corresponding promotion ID. If the promotion code is invalid, the response returns an empty promotion ID. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SUPC_PROMOTION_CODE_VALIDATION`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `PromoCodeValidationRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PromoCodeValidationResponse`.
    

## Schemas

### PromoCodeValidationRequest

*   `promotionCode` (_string_, required) Promotion code to validate.

### PromoCodeValidationResponse

*   `promotionId` (_string_, nullable) If the promotion code is valid, return the promotion ID; otherwise, return empty.
*   `merchantPromotionId` (_string_, nullable) If the promotion code is valid, return the merchant's identifier for the relevant promotion; otherwise, return empty. This is the merchantPromotionId which should have been sent/used during promotion creation/updates.

<!-- document id=4295722fdd6dd9e21b0303e79b3b2fe9d1739fbcac06e8ee08085d0ed65010d6 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/promotion-events-webhook.md -->

Promotion Events Webhook

# Promotion Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-events-webhook/promotion-events-webhook-oas-public.yaml)

Sample API that demonstrates how to implement a webhook endpoint by the merchant's system. This endpoint is then to be configured in the Point of Sale (POS) CMS system, so that the POS platform can use it to send promotion lifecycle events' data (CREATE, UPDATE, and DELETE). The event type is indicated by the `promotionEventType` field in the payload.

**Version:** 2.3.4

## Tags

### Promotion Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-events-webhook/promotion-events-webhook-oas-public.yaml)

Sample API that demonstrates how to implement a webhook endpoint by the merchant's system. This endpoint is then to be configured in the Point of Sale (POS) CMS system, so that the POS platform can use it to send promotion lifecycle events' data (CREATE, UPDATE, and DELETE). The event type is indicated by the `promotionEventType` field in the payload.

## Operations

### POST Receive promotion lifecycle event details

`POST /merchant/spi/sample/endpoint/sa/customer/promotion/promotionExport`

Operation ID: `promotionExportWebhook`. Tags: Promotion Events Webhook.

Webhook to export promotion events (CREATE, UPDATE, DELETE) to the merchant's system. The payload contains the promotion details as a `PromotionWebhookPayload`. For all the events the `promotions` list is populated. The `promotionEventType` field indicates which lifecycle event occurred.

Merchants should implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details

1.  Under **API Config**
    
    *   **API Key:** This should be `PROMOTION_EXPORT`
    *   **API Endpoint:** Provide the external endpoint URL to receive the promotion payload
2.  Under **JSON Config**
    
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the headers for the API. Headers can include Content-Type, Authorization attributes like clientId/password eg. {"Content-Type":"application/json"}.

#### Request body

Media type: `application/json`. Schema: `PromotionWebhookPayload`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### PromotionWebhookPayload

Payload delivered to external systems via the promotion webhook for CREATE, UPDATE, and DELETE events.

*   `promotionEventType` (_string_, required) Type of promotion lifecycle event: CREATE, UPDATE, or DELETE.  
    Allowed values: `CREATE`, `UPDATE`, `DELETE`.
*   `promotions` (_array of SpiPromotion_, required) List of promotions included in this event.
*   `user` (_string_, nullable) CMS user ID who triggered this event (create, update, or delete).
*   `eventTimestamp` (_integer (int64)_, required) Unix epoch timestamp (milliseconds) indicating when this event was generated.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### SpiPromotion

Promotion attributes included in a promotion webhook event. Represents a curated view of the Promotion for external consumers.

*   `promotionId` (_string_, required) Unique identifier assigned to the promotion.
*   `name` (_string_, required) Internal name used to identify the promotion.
*   `title` (_string_, required) Display title shown on the presentation layer.
*   `description` (_string_, required) Detailed description including disclaimer and other information shown on the presentation layer.
*   `inStorePromoCode` (_string_) Promo code entered by the customer for in-store (STORE channel) sales.
*   `appPromoCode` (_string_) Promo code entered by the customer for in-app (APP channel) sales.
*   `onlinePromoCode` (_string_) Promo code entered by the customer for online (WEB channel) sales.
*   `outletPromoCode` (_string_) Promo code entered by the customer for outlet store (OUTLET channel) sales.
*   `startTimeStamp` (_integer (int64)_, required) Promotion start time in Unix epoch milliseconds.
*   `endTimeStamp` (_integer (int64)_, required) Promotion end time in Unix epoch milliseconds.
*   `combinationTypes` (_array of string_) List of promotion types this promotion can be combined with, for example, ORDER\_PERCENT\_OFF or FREE\_SHIPPING.
*   `channel` (_array of string_, required) Sales channels this promotion applies to (ALL, WEB, APP, STORE, OUTLET). Not applicable for auto promotions.
    
    Each item: Different Channel Types supported by the Promotion Engine.
    
      
    Items: Allowed values: `ALL`, `WEB`, `APP`, `STORE`, `OUTLET`.
*   `priorityOrder` (_integer (int32)_) Priority order for promotion application. Lower number means higher priority.
*   `active` (_boolean_, required) Whether the promotion is active. Only active promotions are evaluated by the promo engine.
*   `auto` (_boolean_, required) Whether the promotion is applied automatically without requiring a promo code.
*   `redemptionLimit` (_number (double)_) Maximum number of times this promotion can be redeemed.
*   `promotionType` (_string_, required) Different promotion Types supported by the Promotion Engine.  
    Allowed values: `ORDER_PERCENT_OFF`, `ORDER_AMOUNT_OFF`, `FREE_SHIPPING`, `BXGY`, `FREE_SAMPLES`, `X_FOR_Y`, `PRODUCT_FIXED_AMOUNT`, `FREE_SHIPPING_V2`.
*   `redeems` (_number (double)_) Current number of times this promotion has been redeemed.
*   `percentOff` (_number (double)_) Percentage discount applied by this promotion.
*   `amountOff` (_number_) Fixed amount discounted by this promotion.
*   `freeShippingMethods` (_array of string_) List of shipping method codes eligible for free shipping under this promotion.
*   `hasSingleUsePromoCodes` (_boolean_) Whether this promotion uses single-use (one-time) promo codes.
*   `imageUrl` (_string_) URL of the image associated with this promotion.
*   `freeSamples` (_array of CombinationGroup_) Free sample products awarded when this promotion is applied.
*   `merchantPromotionId` (_string_) Merchant-defined identifier for this promotion.
*   `amount` (_number_) Fixed promotional amount applied to qualifying items.
*   `qualifyingProducts` (_array of CombinationGroup_) Products that must be purchased to qualify for this promotion (used in BXGY and combination promotions).
*   `discountedProducts` (_array of CombinationGroup_) Products that receive the discount when the qualifying condition is met.
*   `discountedGroupProration` (_boolean_) Whether the discount is prorated across items in the discounted product group.
*   `productRules` (_array of PromotionRule_) Rules applied to specific products to determine promotion eligibility.
*   `customerRules` (_array of PromotionRule_) Rules applied to customer attributes to determine promotion eligibility.
*   `locationRules` (_array of PromotionRule_) Rules applied to store location attributes to determine promotion eligibility.
*   `orderRules` (_array of PromotionRule_) Rules applied to order-level attributes to determine promotion eligibility.
*   `bxgyDiscountType` (_string_) Buy X Get Y Discount Types.  
    Allowed values: `PERCENT_OFF`, `AMOUNT_OFF`, `FIXED_PRICE`.

### CombinationGroup

Products that receive the discount when the qualifying condition is met.

*   `quantity` (_integer (int32)_)
*   `quantityOperator` (_string_)  
    Allowed values: `EQL`, `GTE`.
*   `productRules` (_array of PromotionRule_)

### PromotionRule

Promotion rule provides the filtering criteria to determine if the order is eligible for promotion.

*   `promotionRuleId` (_string_)
*   `promotionId` (_string_)
*   `operator` (_string_, nullable) Operation to be performed for the rule depending on the value types.  
    Allowed values: `DOES_NOT_CONTAIN`, `CONTAINS`, `GTE`, `LTE`, `EXISTS`, `NOT_EXISTS`.
*   `value` (_array of string_, nullable) Values are based on the value Types. They contain a list and for single value attributes use a list of size 1.  
    Unique items.
*   `valueType` (_string_, nullable) Value Type provides the type of value.

<!-- document id=52420fe166a5fb278a13a4c6ace432f83ba1f971c3f82a1f116f8264cb0ccde4 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/promotion-management-api.md -->

Promotion Management API

# Promotion Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-management-api/promotion-management-api-oas-public.yaml)

POS Merchant API to perform CRUD operations on promotions in the POS system.

**Version:** 2.3.4

## Tags

### Promotion Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-management-api/promotion-management-api-oas-public.yaml)

POS Merchant API to perform CRUD operations on promotions in the POS system.

## Operations

### GET Promotion management - get promotions

`GET /merchant/{version}/promotions`

Operation ID: `getPromotions`. Tags: Promotion Management API.

Retrieve promotions by ID, status, channel, or promotion code.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (query, string)
*   `active` (query, boolean)
*   `availableType` (query, string)  
    Allowed values: `EXPIRED`, `NOW`, `FUTURE`.
*   `channel` (query, string)
*   `promoCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of Promotion`.
    
    Array of `Promotion`.
    

### PUT Promotion management - Create or update promotion

`PUT /merchant/{version}/promotions`

Operation ID: `updatePromotion`. Tags: Promotion Management API.

The request must include all properties of a promotion for the upsert operation to succeed.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Promotion`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Promotion`.
    

### POST Create or update promotion.

`POST /merchant/{version}/promotions`

Operation ID: `addPromotion`. Tags: Promotion Management API.

Create or update a promotion. The request must include all properties of a promotion so that the upsert operation succeeds.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Promotion`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Promotion`.
    

### PATCH Update promotions.

`PATCH /merchant/{version}/promotions`

Operation ID: `patchPromotions`. Tags: Promotion Management API.

Update promotions. The request can include any property of a promotion, but must include the promotion ID so that the update can be performed.

**Limit:** 100 promotions per request.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `UpdatePromotionsRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `UpdatePromotionsResponse`.
    

### GET Get promotion.

`GET /merchant/{version}/promotions/{promotionId}`

Operation ID: `getPromotion`. Tags: Promotion Management API.

Retrieve a promotion.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Promotion`.
    

### DELETE Delete promotion.

`DELETE /merchant/{version}/promotions/{promotionId}`

Operation ID: `deletePromotion`. Tags: Promotion Management API.

Delete a promotion.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### GET Download promotions report.

`GET /merchant/{version}/promotions/download/report`

Operation ID: `downloadPromotions`. Tags: Promotion Management API.

Download a report of promotions.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (query, string)
*   `active` (query, boolean)
*   `channel` (query, string)
*   `promoCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DownloadFileResponse`.
    

### GET Get promotion codes.

`GET /merchant/{version}/promotions/{promotionId}/supc`

Operation ID: `getOneTimePromotionCode`. Tags: Promotion Management API.

Retrieve a list of Single Use Promotion Codes (SUPC) in a promotion from the POS.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)
*   `promotionCode` (query, string)
*   `redeem` (query, boolean)
*   `start` (query, integer (int32))
*   `limit` (query, integer (int32))

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PageOneTimePromotionCodeResponse`.
    

### PUT Update one-time promotion codes.

`PUT /merchant/{version}/promotions/{promotionId}/supc`

Operation ID: `updateOneTimePromotionCode`. Tags: Promotion Management API.

Update the redemption status of SUPCs in a promotion that were redeemed by an external system.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)
*   `redeem` (query, boolean)

#### Request body

Media type: `application/json`. Schema: `UpsertOneTimePromotionRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OneTimeCodeDataUploadResult`.
    

### POST Insert one-time promotion codes.

`POST /merchant/{version}/promotions/{promotionId}/supc`

Operation ID: `insertOneTimePromotionCode`. Tags: Promotion Management API.

Create and send new valid SUPCs in a promotion to the POS system.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `UpsertOneTimePromotionRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OneTimeCodeDataUploadResult`.
    

### GET Retrieve promotions.

`GET /merchant/{version}/promotions/pagination`

Operation ID: `getPromotionsPagination`. Tags: Promotion Management API.

Retrieve a list of promotions based on the provided query parameters. The parameters include:

1.  `promotionId`: A query parameter to filter promotions by ID. (Optional)
2.  `active`: A query parameter to filter promotions by their active status. (Optional)
3.  `availableType`: A query parameter to filter promotions by their availability type. (Optional)
4.  `channel`: A query parameter to filter promotions by channel. (Optional)
5.  `promoCode`: A query parameter to filter promotions by promo code. (Optional)
6.  `start`: A query parameter with a default value of 0, indicating the starting point for pagination.
7.  `limit`: A query parameter with a default value of 200, indicating the maximum number of promotions to return.

**Note:** Due to API Gateway limitations, responses exceeding 10MB will result in a 500 error.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `promotionId` (query, string)
*   `active` (query, boolean)
*   `availableType` (query, string)  
    Allowed values: `EXPIRED`, `NOW`, `FUTURE`.
*   `channel` (query, string)
*   `promoCode` (query, string)
*   `start` (query, integer (int32))  
    Default: `0`.
*   `limit` (query, integer (int32))  
    Default: `200`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `GetPromotionsResponse`.
    

### POST Look up one-time promotion codes.

`POST /merchant/{version}/promotions/supc/lookup`

Operation ID: `oneTimePromotionCodeLookup`. Tags: Promotion Management API.

Return information about one-time promotion codes based on input codes. The maximum size of an input list is 100.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `OneTimePromotionCodeLookupResponse`.
    

### POST Upload promotion by JSON file.

`POST /merchant/{version}/promotions/upload`

Operation ID: `uploadPromotionByJsonFile`. Tags: Promotion Management API.

Upload a promotion by JSON file. Refer to [Single-Use Promotion Code](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/single-use-promotion-code.html) for file specification.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `multipart/form-data`. Schema: `object`.

*   `File` (_FormDataBodyPart_)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PromotionFileUploadResponse`.
    

## Schemas

### Promotion

*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)
*   `promotionId` (_string_)
*   `name` (_string_)
*   `title` (_string_)
*   `description` (_string_)
*   `promoCode` (_string_)
*   `inStorePromoCode` (_string_)
*   `appPromoCode` (_string_)
*   `onlinePromoCode` (_string_)
*   `outletPromoCode` (_string_)
*   `promoFeedSource` (_FeedSource_)
*   `startTimeStamp` (_integer (int64)_)
*   `endTimeStamp` (_integer (int64)_)
*   `combinationTypes` (_array of string_)
*   `channel` (_array of string_)  
    Items: Allowed values: `ALL`, `WEB`, `APP`, `STORE`, `OUTLET`.
*   `priorityOrder` (_integer (int32)_)
*   `active` (_boolean_)
*   `auto` (_boolean_)
*   `redemptionLimit` (_number (double)_)
*   `uniqueCodeUrl` (_string_)
*   `redeems` (_number (double)_)
*   `barCodeType` (_string_)
*   `promotionType` (_string_)  
    Allowed values: `ORDER_PERCENT_OFF`, `ORDER_AMOUNT_OFF`, `FREE_SHIPPING`, `BXGY`, `FREE_SAMPLES`, `X_FOR_Y`, `PRODUCT_FIXED_AMOUNT`, `FREE_SHIPPING_V2`.
*   `percentOff` (_number (double)_)
*   `maxDiscountAmount` (_number (double)_)
*   `maxTotal` (_number_)
*   `amountOff` (_number_)
*   `shippingMethods` (_array of string_)
*   `hasSingleUsePromoCodes` (_boolean_)
*   `imageUrl` (_string_)
*   `discountedQuantity` (_integer (int32)_)
*   `freeSamples` (_array of CombinationGroup_)
*   `merchantPromotionId` (_string_)
*   `amount` (_number_)
*   `promoRules` (_array of PromotionRule_)
*   `qualifyingGroups` (_array of CombinationGroup_)
*   `discountedGroups` (_array of CombinationGroup_)
*   `amountExpression` (_string_)
*   `tierGroups` (_array of TierGroup_)
*   `discountedGroupProration` (_boolean_)
*   `promotionLanguageData` (_array of PromotionLanguageData_) Promotion attributes in additional languages.
*   `bxgyDiscountType` (_string_) Buy X Get Y discount types.  
    Allowed values: `PERCENT_OFF`, `AMOUNT_OFF`, `FIXED_PRICE`.
*   `createdBy` (_string_)
*   `createdOn` (_string (date-time)_)
*   `lastUpdatedOn` (_string (date-time)_)
*   `lastUpdatedBy` (_string_)
*   `promotionMappings` (_array of PromotionMapping_)
*   `isExternallyValidated` (_boolean_)
*   `promotionTypePriority` (_string_)  
    Allowed values: `FREE_SAMPLES`, `BXGY_FIXED_AMOUNT`, `X_FOR_Y`, `BXGY_AMOUNT_OFF`, `BXGY_PERCENT_OFF`, `PRODUCT_FIXED_AMOUNT`, `ORDER_AMOUNT_OFF`, `ORDER_PERCENT_OFF`, `FREE_SHIPPING_V2`, `FREE_SHIPPING`.
*   `promotionCode` (_PromotionCode_)

### UpdatePromotionsRequest

*   `promotions` (_array of Promotion_)

### UpdatePromotionsResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `promotions` (_array of Promotion_)
*   `error` (_boolean_)

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### DownloadFileResponse

*   `status` (_string_)
*   `statusMessage` (_string_)
*   `fileName` (_string_)
*   `url` (_string (url)_)

### PageOneTimePromotionCodeResponse

*   `totalPages` (_integer (int32)_)
*   `totalElements` (_integer (int64)_)
*   `pageable` (_Pageable_)
*   `numberOfElements` (_integer (int32)_)
*   `first` (_boolean_)
*   `number` (_integer (int32)_)
*   `size` (_integer (int32)_)
*   `content` (_array of OneTimePromotionCodeResponse_)
*   `sort` (_Sort_)
*   `last` (_boolean_)
*   `empty` (_boolean_)

### UpsertOneTimePromotionRequest

*   `promotionCodes` (_array of PromotionCode_) List of one-time promotion entities.

### OneTimeCodeDataUploadResult

*   `unprocessedCodes` (_array of OneTimePromotionCodeUpsertVO_)
*   `totalProcessed` (_integer (int32)_)
*   `totalError` (_integer (int32)_)
*   `entriesUpdated` (_integer (int32)_)
*   `entriesInactive` (_integer (int32)_)
*   `errors` (_array of object_)
    *   `cause` (_object_)
        *   `stackTrace` (_array of object_)
            *   `classLoaderName` (_string_)
            *   `moduleName` (_string_)
            *   `moduleVersion` (_string_)
            *   `methodName` (_string_)
            *   `fileName` (_string_)
            *   `lineNumber` (_integer (int32)_)
            *   `nativeMethod` (_boolean_)
            *   `className` (_string_)
        *   `message` (_string_)
        *   `localizedMessage` (_string_)
    *   `stackTrace` (_array of object_)
        *   `classLoaderName` (_string_)
        *   `moduleName` (_string_)
        *   `moduleVersion` (_string_)
        *   `methodName` (_string_)
        *   `fileName` (_string_)
        *   `lineNumber` (_integer (int32)_)
        *   `nativeMethod` (_boolean_)
        *   `className` (_string_)
    *   `message` (_string_)
    *   `suppressed` (_array of object_)
        *   `stackTrace` (_array of object_)
            *   `classLoaderName` (_string_)
            *   `moduleName` (_string_)
            *   `moduleVersion` (_string_)
            *   `methodName` (_string_)
            *   `fileName` (_string_)
            *   `lineNumber` (_integer (int32)_)
            *   `nativeMethod` (_boolean_)
            *   `className` (_string_)
        *   `message` (_string_)
        *   `localizedMessage` (_string_)
    *   `localizedMessage` (_string_)
*   `processedFile` (_DataFeedFile_)

### GetPromotionsResponse

*   `totalCount` (_integer (int64)_) The total number of promotions available.
*   `promotions` (_array of Promotion_) A list of promotions returned in the response.

### OneTimePromotionCodeLookupResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `totalCount` (_integer (int32)_)
*   `oneTimePromotionCodeResponse` (_array of OneTimePromotionCodeResponse_)
*   `error` (_boolean_)

### FormDataBodyPart

*   `contentDisposition` (_ContentDisposition_)
*   `entity` (_object_)
*   `headers` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of string`.
    
*   `mediaType` (_MediaType_)
*   `messageBodyWorkers` (_MessageBodyWorkers_)
*   `parent` (_MultiPart_)
*   `providers` (_Providers_)
*   `formDataContentDisposition` (_FormDataContentDisposition_)
*   `simple` (_boolean_)
*   `name` (_string_)
*   `value` (_string_)
*   `content` (_object_)
*   `fileName` (_string_)
*   `parameterizedHeaders` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of ParameterizedHeader`.
    

### PromotionFileUploadResponse

*   `statuses` (_array of PromotionUploadStatus_) List of promotion status.
*   `successCount` (_integer (int32)_) Number of successfully uploaded promotions.
*   `count` (_integer (int32)_) Number of total promotions.

### FeedSource

*   `feedType` (_string_)  
    Allowed values: `PRODUCT`, `PRODUCT_BUNDLE`, `STORE`, `LAYOUT`, `PRODUCT_PROMOTION`, `PRODUCT_CATEGORY`, `PRODUCT_CATEGORY_PROMOTION`, `PROMOTION`, `STORE_INVENTORY_FULL`, `STORE_INVENTORY_DELTA`, `SOCIAL_MEDIA`, `ONE_TIME_PROMOTION_CODE`, `PRODUCT_DELTA`, `CATEGORY`, `ORDER_LIST`, `ORDER_DETAILS`, `RECOMMENDATION`, `TAX_RATE`, `PIPELINE`, `STORE_ASSOCIATES`, `PREDICTSPRING_PROMOTION`, `REWARD`, `CASH_REWARD`, `ASN`, `CORP_TRANSFER`, `POS_PROVISIONING`, `SYNONYM`, `STORE_AREA_GOAL`, `STORE_AREA_HIERARCHY`, `OMS`, `PRODUCT_PRICING`, `PRODUCT_SIZING`, `PRODUCT_INVENTORY`, `PRODUCT_PRICING_DELTA`, `PRODUCT_SIZING_DELTA`, `PRODUCT_INVENTORY_DELTA`, `STORE_DEVICE`, `BOPIS_CANCEL_ORDER`, `PURCHASE_ORDER`, `OFFLINE_PROMOTION`, `PREDICTSPRING_PROMOTION_V2`, `EXPIRED_PAYMENT_LINK_CLEANUP`, `SINGLE_USE_PROMO_CODES`, `STORE_GROUP_FULL`, `STORE_GROUP_DELTA`.
*   `feedSourceName` (_string_)
*   `feedSourceType` (_string_)  
    Allowed values: `URL`, `SFTP`, `FTP`, `S3`, `YEXT`, `AVALARA`, `SABRIX`, `AVALARA_V2`, `VERTEX`, `SPI`, `WEBDAV`.
*   `fileNames` (_array of string_)
*   `feedFileType` (_string_)  
    Allowed values: `CSV`, `TSV`, `SSV`, `PSV`, `XML`, `STORE_XML`, `INVENTORY_XML`, `JSON`, `YEXT`, `ASN_EDI_856`, `OTHER`.
*   `feedPreprocessorClass` (_string_)
*   `feedFileMetadataList` (_array of FeedFileMetadata_)
*   `baseURL` (_string_)
*   `urlRequestParams` (_string_)
*   `folderName` (_string_)
*   `host` (_string_)
*   `port` (_integer (int32)_)
*   `userName` (_string_)
*   `password` (_string_)
*   `s3FeedTimestamp` (_integer (int64)_)
*   `parentTag` (_string_)
*   `multiValueFieldList` (_array of string_)
*   `preserveIfNullFieldList` (_array of string_)
*   `currencyCode` (_string_)
*   `idColumn` (_string_)
*   `multiValueFieldDelimiter` (_string_)
*   `columnNames` (_string_)
*   `promotionId` (_string_)
*   `deleteFeed` (_boolean_)
*   `addFeed` (_boolean_)
*   `updateFeed` (_boolean_)
*   `fullFeed` (_boolean_)
*   `sourceEncoding` (_string_)
*   `maxRecordsToProcess` (_integer (int32)_)
*   `apiKey` (_string_)
*   `version` (_string_)
*   `categoryProductRankColumnName` (_string_)
*   `productIdFieldName` (_string_)
*   `feedName` (_string_)
*   `feedDescription` (_string_)
*   `isProductBundleCategorySource` (_boolean_)
*   `importPromotions` (_boolean_)
*   `hasCategories` (_boolean_)
*   `shouldProcessCategoryCounts` (_boolean_)
*   `skipFields` (_string_)
*   `hasProductMultiPromotions` (_boolean_)
*   `fieldDelimiter` (_string_)
*   `endLineDelimiter` (_string_)
*   `deviceOS` (_string_)
*   `dataSource` (_string_)  
    Allowed values: `NETSUITE`.
*   `accountId` (_string_)
*   `licenseKey` (_string_)
*   `merchantReferenceCode` (_string_)
*   `bulkProcessing` (_boolean_)
*   `backUp` (_boolean_)
*   `continueOnFileError` (_boolean_)
*   `clientId` (_string_)
*   `clientSecret` (_string_)
*   `hasActualInventoryCount` (_boolean_)
*   `oauthHost` (_string_)

### CombinationGroup

Products that receive the discount when the qualifying condition is met.

*   `quantity` (_integer (int32)_)
*   `quantityOperator` (_string_)  
    Allowed values: `EQL`, `GTE`.
*   `productRules` (_array of PromotionRule_)

### PromotionRule

Promotion rule provides the filtering criteria to determine if the order is eligible for promotion.

*   `promotionRuleId` (_string_)
*   `promotionId` (_string_)
*   `operator` (_string_, nullable) Operation to be performed for the rule depending on the value types.  
    Allowed values: `DOES_NOT_CONTAIN`, `CONTAINS`, `GTE`, `LTE`, `EXISTS`, `NOT_EXISTS`.
*   `value` (_array of string_, nullable) Values are based on the value Types. They contain a list and for single value attributes use a list of size 1.  
    Unique items.
*   `valueType` (_string_, nullable) Value Type provides the type of value.

### TierGroup

*   `amountExpression` (_string_)
*   `tierRules` (_array of PromotionRule_)
*   `id` (_string_)
*   `selectedProducts` (_array of string_)

### PromotionLanguageData

Promotion attributes in additional languages.

*   `promotionId` (_string_)
*   `language` (_string_) The language/locale of properties for this object.
*   `name` (_string_) The name used for internal identification of the promotion. This field can also be used to assign a locale/language-specific name for the promotion.
*   `title` (_string_) The locale/language-specific title used for external display of the promotion on the presentation layer.
*   `description` (_string_) The locale/language-specific description used for external display of the promotion on the presentation layer. This contains the disclaimer and other information.

### PromotionMapping

*   `quantityOperator` (_string_)  
    Allowed values: `EQL`, `GTE`.
*   `merchantId` (_string_)
*   `type` (_string_)  
    Allowed values: `QUALIFYING_GROUP`, `DISCOUNTED_GROUP`, `TIER_GROUP`, `FREE_SAMPLES`.
*   `promotionRulesGroupId` (_string_)
*   `promotionMappingId` (_string_)
*   `promotionId` (_string_)
*   `amountExpression` (_string_)
*   `quantity` (_integer (int32)_)
*   `locale` (_string_)
*   `region` (_string_)

### PromotionCode

*   `merchantId` (_string_)
*   `region` (_string_)
*   `promotionId` (_string_)
*   `oneTimeCode` (_string_)
*   `oneTimeCodeCS` (_string_)
*   `codeType` (_string_)
*   `externalId` (_string_)
*   `codeAssignedDate` (_string (date-time)_)
*   `codeRedeemed` (_boolean_)
*   `codeRedeemedDate` (_string (date-time)_)
*   `storeCode` (_string_)
*   `promotionValidDate` (_string (date-time)_)
*   `type` (_string_)
*   `message` (_string_)
*   `validFrom` (_string (date-time)_)
*   `validTo` (_string (date-time)_)
*   `updatedOn` (_string (date-time)_)

### Pageable

*   `pageSize` (_integer (int32)_)
*   `pageNumber` (_integer (int32)_)
*   `paged` (_boolean_)
*   `unpaged` (_boolean_)
*   `offset` (_integer (int64)_)
*   `sort` (_Sort_)

### OneTimePromotionCodeResponse

*   `oneTimeCode` (_string_)
*   `status` (_string_)  
    Allowed values: `VALID`, `REDEEMED`, `NOT_FOUND`.
*   `promoName` (_string_)
*   `promotionId` (_string_)
*   `orderId` (_string_)
*   `codeRedeemedDate` (_integer (int64)_)
*   `storeId` (_string_)

### Sort

*   `unsorted` (_boolean_)
*   `sorted` (_boolean_)
*   `empty` (_boolean_)

### OneTimePromotionCodeUpsertVO

*   `errorMessage` (_string_)
*   `errorCode` (_string_)
*   `oneTimePromotionCode` (_string_)

### DataFeedFile

*   `dataStream` (_object_)
*   `fileName` (_string_)
*   `originalFileName` (_string_)
*   `length` (_integer (int64)_)
*   `contentType` (_string_)
*   `s3Reference` (_string_)

### ContentDisposition

*   `type` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    
*   `fileName` (_string_)
*   `creationDate` (_string (date-time)_)
*   `modificationDate` (_string (date-time)_)
*   `readDate` (_string (date-time)_)
*   `size` (_integer (int64)_)

### MediaType

*   `type` (_string_)
*   `subtype` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    
*   `wildcardType` (_boolean_)
*   `wildcardSubtype` (_boolean_)

### MessageBodyWorkers

### MultiPart

*   `contentDisposition` (_ContentDisposition_)
*   `entity` (_object_)
*   `headers` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of string`.
    
*   `mediaType` (_MediaType_)
*   `messageBodyWorkers` (_MessageBodyWorkers_)
*   `parent` (_MultiPart_)
*   `providers` (_Providers_)
*   `bodyParts` (_array of BodyPart_)
*   `parameterizedHeaders` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of ParameterizedHeader`.
    

### Providers

### FormDataContentDisposition

*   `type` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    
*   `fileName` (_string_)
*   `creationDate` (_string (date-time)_)
*   `modificationDate` (_string (date-time)_)
*   `readDate` (_string (date-time)_)
*   `size` (_integer (int64)_)
*   `name` (_string_)

### ParameterizedHeader

*   `value` (_string_)
*   `parameters` (_object_)
    
    Additional properties: `string`.
    

### PromotionUploadStatus

List of promotion status.

*   `promotionId` (_string_) The ID of the promotion passed by CMS.
*   `status` (_string_) The upload status of the related promotion ID: Success or Failure.  
    Allowed values: `SUCCESS`, `FAILURE`.
*   `exception` (_string_) Exception messages.
*   `promotionTitle` (_string_) The title of the promotion.
*   `errors` (_array of string_) List of errors.

### FeedFileMetadata

*   `fileName` (_string_)
*   `feedFileType` (_string_)  
    Allowed values: `CSV`, `TSV`, `SSV`, `PSV`, `XML`, `STORE_XML`, `INVENTORY_XML`, `JSON`, `YEXT`, `ASN_EDI_856`, `OTHER`.
*   `feedPreprocessorClass` (_string_)
*   `parentTag` (_string_)
*   `multiValueFieldList` (_array of string_)
*   `preserveIfNullFieldList` (_array of string_)
*   `idColumn` (_string_)
*   `multiValueFieldDelimiter` (_string_)
*   `columnNames` (_string_)
*   `sourceEncoding` (_string_)

### BodyPart

*   `contentDisposition` (_ContentDisposition_)
*   `entity` (_object_)
*   `headers` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of string`.
    
*   `mediaType` (_MediaType_)
*   `messageBodyWorkers` (_MessageBodyWorkers_)
*   `parent` (_MultiPart_)
*   `providers` (_Providers_)
*   `parameterizedHeaders` (_object_)
    
    *   `empty` (_boolean_)
    
    Additional properties: `array of ParameterizedHeader`.

<!-- document id=e65744c014cfb6f64f66b929577197c01d757ee0450d9fd9df4188b1341c95fd url=/developer/current/en-us/commerce-cloud/commerce-api/guides/promotion-details.md -->

# Promotion Types and Requirements

Promotions provide discounts to shoppers when they meet certain purchase requirements.

For the [Shopper Products](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products) and [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search) APIs, promotion information includes both pricing and callout message information. However, the specific pricing and callout information that is fetched is determined by:

- Promotion Type
- Product Type
- Product Purchase Requirements

## Promotion Types

Promotions are categorized into types:

- Product: a discount on an individual product, or on a product with specific purchasing options (size, color, or style), for example:
  - 10% off shirts when you buy 2
  - Buy 3 ties for $10
  - $5 off a TV when purchasing a 1-year warranty
  - Get 10% off Sony PlayStation with source code wii100. (Source codes can be set in the Shopper context.)
- Order: a discount on the total cost of the basket, for example:
  - $10 off for shoppers who are members of the gold membership customer group
- Shipment: a discounted shipping cost, for example:
  - Free shipping on orders over $50 with coupon code “freeship”

## Product Types

A product, which is only applicable to product promotions, is classified as one of the following:

- Qualifying Product

  - Product used to trigger a discount, for example:

    - In a “Buy 3 of product X, and get 10% off of up to 4 of product Y” promotion, the qualifying product is product X.
    - **Important**: Qualifying products can have variants, which are different purchasing options, such as size or color. The specific product buying option that is specified for the promotion is known as the master or primary product. Variant products might or might not be included in the promotion.

      - If the product is master, the response includes::

      ```text
      "type": {
      "master": true
      }
      ```

      - If the product is a variant, the response includes:

      ```text
      "type": {
      "variant": true
      }
      ```

- Discounted Product
  - Product that receives a monetary discount, for example:
    - In a “Buy 3 of product X, and get 10% off of up to 4 of product Y” promotion, the discounted product is product Y.
- Bonus Product
  - A free product, for example:
    - In a “Buy 3 of product X, and get one product Y for free” promotion, the bonus product is product Y.

## Product Purchase Requirements

Promotions can, but are not required to, have specific product purchase requirements, such as purchasing a set quantity or a specific item:

- Non-conditional:
  - No additional purchase criteria, such as discounts, free samples, or other offers, for example:
    - “$10 Off of product X”, "50% Off All Items," or "Free Gift with Purchase."
- Conditional:
  - Customers must fulfill additional conditions to qualify for the offer, such as making a minimum purchase, signing up for a membership or loyalty program, or participating in a specific activity, for example:
    - "Spend $50 and Get 20% Off," "Buy 2, Get 1 Free," “Buy an 80” TV and Receive a Free Streaming Device”, or "Get a Discount Coupon for Your Next Purchase When You Sign Up for Our Newsletter."
  - **Important**: Conditional product purchase requirements only apply to product promotions, not order or shipment promotions.
- Bonus:
  - Involves offering customers an additional item or service for free or at a discounted rate when they purchase a specified product or meet certain conditions. The bonus item is typically related to a primary product, serving as an incentive to encourage customers to make a purchase, for example:
    - "Buy a Laptop and Get a Free Mouse," "Purchase a Shampoo and Conditioner Set and Receive a Travel-sized Hair Serum for Free," or "Buy a Gaming Console and Get a Free Game."
  - **Important**: Bonus product purchase requirements only apply to product promotions, not order or shipment promotions.

## Response Contents

Based on the promotion type, product type, and product purchase requirements, The content of the response includes the following information:

- Pricing
- Callout Message

### Pricing Information

Pricing information is only returned for qualifying products with non-conditional purchase requirements in product level promotions, for example: Buy product X and get $10 off or Buy product X and get 10% off. For other promotion types, product types, and product purchase requirements, pricing is impacted by shopper-driven actions, and cannot be calculated until the shopper makes additional purchasing decisions.

In addition:

- Promotional pricing is only returned for variant products that are included in a promotion when the primary product is the qualifying product for the promotion.
- The priceRange returned in the response per price book returns the min and max price across variants, for example: if an ipod-classic-silver costs $219 and an ipod-classic-black costs $200, the minprice is : 200 and max is 219.

### Callout Message Information

Callout messages provide details about the qualifying, discounted, or bonus product, as applicable, and what the shopper must do to qualify for the promotion.

The callout message is returned in the `productPromotions[].calloutMsg` attribute of the response body.

For example, the following code includes a non-conditional purchase callout message for a $10 discount when purchasing a women's shirt:

```text
"productPromotions": [
{
"calloutMsg": "$10 Fixed on Women's Shirt",
"promotionalPrice": 89.99,
"promotionId": "$10FixedProductsOnWomensShirt"
}
]
```

The following example provides a conditional purchase callout message for a $50 discount when purchasing a man's suit that costs more than $400:

```text
"productPromotions": [
{
"calloutMsg": "$50 off Mens Suits Over 400",
"promotionId": "$50offSuitsOver400"
}]
```

<!-- document id=e9e4f561bc6d84e35f3e552a3f29cdd5de909ebb5cba98eeaf5db03351e5b6a9 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/promotions.md -->

Promotions

# Promotions

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/promotions/promotions-oas-v1-public.yaml)

## API Overview

Use the Promotions API to create, update, delete, and search for promotion information on your site. Promotions are configured with rules that define the type of promotion, conditions, and discounts.

This API can be used to synchronize promotion data in the commerce platform with third-party promotion management systems. This API can also be called from a custom promotion management application. In sandbox environments, the Promotions API is useful for creating and updating test data, for example, with integration testing or as part of a continuous integration or continuous deployment process.

For more information, see [Campaigns and Promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_campaigns_and_promotions.htm&type=5) in the B2C Commerce documentation.

### Authentication & Authorization

The client requesting the promotion information must have access to the Promotion resource. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account Manager to log in.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

**Note**: A promotion can be created, enabled, and assigned exclusivity using the API, but qualifier and discounted criteria must be assigned in Business Manager.

#### Shipping Promotions

Use the Promotions API to configure shipping promotions.

You can configure shipping promotions based on an order and on individual products or product combinations. You can also configure product-specific shipping cost (fixed or surcharge).

**Note**: Product-related shipping discounts are considered product promotions.

In a multiple ship-to scenario, B2C Commerce determines which shipments use any of the discounted shipping methods and applies the discount from most expensive to least expensive until meeting the maximum applications limit, if specified.

For example, create a shipping promotion that gives the customer free shipping when their purchase exceeds $50.

For more detail, see [Shipping Promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_shipping_promotions.htm&type=5) in the B2C Commerce documentation.

#### Product Promotions

Use the Promotions API to configure product promotions.

You can define product promotions for specific products, groups of products or brands, or amounts of products purchased. You can define conditions that require customers to purchase from a set of products.

A product promotion is prorated, calculated, and rounded once per product in the order. A product promotion is different than an order promotion, which is calculated once at the order level, and rounded off once, if necessary.

For example, create a product promotion that discounts a second item by 50% when the customer buys two.

For more detail, see [Product Promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_product_promotions.htm&type=5) in the B2C Commerce documentation.

#### Order Promotions

Use the Promotions API to configure order promotions.

You can configure order promotions for percentage discounts, fixed price discounts, and free shipping. You can offer a bonus product or a choice of bonus products, and you can tier order discounts.

An order promotion is calculated once at the order level, and rounded off once, if necessary. An order promotion is different than a product promotion, where the promotion is prorated, calculated, and rounded per product in the order.

For example, create an order promotion that discounts an entire order when the customer buys 3 qualifying items.

For more detail, see [Order Promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_order_promotions.htm&type=5) in the B2C Commerce documentation.

### Related APIs

*   [Shopper Promotions](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-promotions?meta=Summary) — Retrieve active promotions visible to shoppers.
*   [Campaigns](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns?meta=Summary) — Manage campaigns that group promotions.
*   [Assignments](https://developer.salesforce.com/docs/commerce/commerce-api/references/assignments?meta=Summary) — Assign promotions and discounts to campaigns.

**Version:** 1.2.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/promotions/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.promotions: promotions READONLY
    *   Scope sfcc.promotions.rw: promotions read/write
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### POST Search for promotions.

`POST /organizations/{organizationId}/promotions`

Operation ID: `promotionsSearch`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

The SearchRequest document contains a search object that allows you to filter using various attributes.

Use the following searchable query attributes to narrow down the search:

| Attribute | Type |
| --- | --- |
| id | String |
| name | String |
| currecyCode | String |
| exclusivity | String |
| enabled | Boolean |

Note that only searchable attributes can be used in sorting. Additionally, the following attribute can be used to sort:

| Attribute | Type |
| --- | --- |
| promotionClass | String |

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SearchRequest`.

#### Responses

*   **200** Promotions information searched successfully.
    
    Media type: `application/json`. Schema: `PromotionSearchResult`.
    
*   **400** Returned when the query is ill-formed.

### GET Retrieve promotion information.

`GET /organizations/{organizationId}/promotions/{id}`

Operation ID: `getPromotion`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Retrieved promotion information successfully.
    
    Media type: `application/json`. Schema: `Promotion`.
    
    _Example: GetPromotion_
    
    ```
    {
      "archived": false,
      "assignmentInformation": {
        "active": true,
        "activeCampaignAssignments": [
          {
            "campaignId": "coupon-campaign",
            "coupons": [
              "shipping-promotion-coupon"
            ],
            "description": "Coupon Shipping Promotion",
            "enabled": true,
            "promotionId": "my-shipping-promotion",
            "schedule": {}
          }
        ],
        "campaignId": "coupon-campaign",
        "enabled": true,
        "schedule": {},
        "scheduleType": "none"
      },
      "creationDate": "2020-01-09T16:50:32.000Z",
      "disableGloballyExcluded": false,
      "enabled": true,
      "exclusivity": "no",
      "id": "my-shipping-promotion",
      "lastModified": "2020-01-09T16:50:32.000Z",
      "name": {
        "default": "Coupon Shipping Promotion"
      },
      "promotionClass": "shipping",
      "c_customString": "Custom Value"
    }
    ```
    
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: getPromotion404_
    
    ```
    {
      "title": "Promotion Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/promotion-not-found",
      "detail": "No promotion with ID 'not-existing-promotion' in site 'SiteGenesis' could be found.",
      "promotionId": "not-existing-promotion",
      "siteId": "SiteGenesis"
    }
    ```
    

### PUT Create a promotion using the information provided.

`PUT /organizations/{organizationId}/promotions/{id}`

Operation ID: `createPromotion`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `Promotion`.

_Example: PutPromotion_

```
{
  "enabled": true,
  "name": {
    "default": "__PROMOTION_ID__"
  },
  "exclusivity": "class",
  "promotionClass": "order",
  "c_customString": "Custom Value"
}
```

#### Responses

*   **200** Promotion created successfully.
    
    Media type: `application/json`. Schema: `Promotion`.
    
    _Example: PutPromotion_
    
    ```
    {
      "archived": false,
      "assignmentInformation": {
        "active": false,
        "activeCampaignAssignments": [],
        "campaignId": "coupon-campaign",
        "enabled": true,
        "schedule": {},
        "scheduleType": "none"
      },
      "creationDate": "2020-01-13T20:22:09.189Z",
      "disableGloballyExcluded": false,
      "enabled": true,
      "exclusivity": "class",
      "id": "my-promotion",
      "lastModified": "2020-01-13T20:22:09.199Z",
      "name": {
        "default": "__PROMOTION_ID__"
      },
      "promotionClass": "order",
      "c_customString": "Custom Value"
    }
    ```
    
*   **400** Returned when the ID in the request does not match the ID in the document.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict400_
    
    ```
    {
      "title": "Id Conflict",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the request body ('his-promotion') doesn't match the ID in the URL ('my-promotion').",
      "bodyID": "his-promotion",
      "urlID": "my-promotion"
    }
    ```
    

### DELETE Delete a promotion for a specified ID.

`DELETE /organizations/{organizationId}/promotions/{id}`

Operation ID: `deletePromotion`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Deleted the promotion successfully.

### PATCH Update a promotion with the specified information.

`PATCH /organizations/{organizationId}/promotions/{id}`

Operation ID: `updatePromotion`. Security: AmOAuth2 (sfcc.promotions.rw).

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `Promotion`.

_Example: PromotionsPatch_

```
{
  "enabled": false,
  "name": {
    "default": "__PROMOTION_ID__"
  },
  "exclusivity": "class",
  "promotionClass": "order",
  "c_customString": "Custom Value"
}
```

#### Responses

*   **200** Updated the promotion using the information provided. Fields that can be updated: name, ID, enabled
    
    Media type: `application/json`. Schema: `Promotion`.
    
    _Example: PutPromotion_
    
    ```
    {
      "archived": false,
      "assignmentInformation": {
        "active": false,
        "activeCampaignAssignments": [],
        "campaignId": "coupon-campaign",
        "enabled": false,
        "schedule": {},
        "scheduleType": "none"
      },
      "creationDate": "2020-01-13T20:22:09.189Z",
      "disableGloballyExcluded": false,
      "enabled": false,
      "exclusivity": "class",
      "id": "my-promotion",
      "lastModified": "2020-01-13T20:31:25.795Z",
      "name": {
        "default": "__PROMOTION_ID__"
      },
      "promotionClass": "order",
      "c_customString": "Custom Value"
    }
    ```
    
*   **404** Returned when there is no promotion found with the given ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example GetPromotion: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

### GET Retrieve the discount rule for a promotion.

`GET /organizations/{organizationId}/promotions/{id}/discount-rule`

Operation ID: `getPromotionDiscountRule`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

Returns the discount rule, product qualifiers, and payment-method qualifiers for the promotion.

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Retrieved the discount rule successfully.
    
    Media type: `application/json`. Schema: `DiscountRule`.
    
    _Example: GetPromotionDiscountRule_
    
    ```
    {
      "promotionRule": {
        "promotionClass": "order",
        "discount": {
          "type": "amount",
          "amount": {
            "currencyMnemonic": "USD",
            "value": 15
          }
        },
        "tiers": [
          {
            "threshold": 100,
            "conditionType": "order_total",
            "discount": {
              "type": "amount",
              "amount": {
                "currencyMnemonic": "USD",
                "value": 15
              }
            }
          }
        ],
        "discountOnlyQualifyingProducts": false,
        "disableGlobalExcludedProducts": false
      },
      "qualifyingProducts": {
        "includedProducts": [
          {
            "conditions": [
              {
                "type": "category",
                "operator": "is_equal",
                "catalogId": "storefront-catalog-m-en",
                "values": [
                  "electronics"
                ]
              }
            ]
          }
        ]
      },
      "paymentMethodQualifiers": {
        "methodIds": [
          "CREDIT_CARD.Visa"
        ]
      }
    }
    ```
    
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example getPromotionDiscountRule404: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

### PUT Create or replace the discount rule for a promotion.

`PUT /organizations/{organizationId}/promotions/{id}/discount-rule`

Operation ID: `createPromotionDiscountRule`. Security: AmOAuth2 (sfcc.promotions.rw).

Replaces the entire discount rule, product qualifiers, and payment-method qualifiers for the promotion.

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `DiscountRule`.

_Example: PutPromotionDiscountRule_

```
{
  "promotionRule": {
    "promotionClass": "order",
    "discount": {
      "type": "amount",
      "amount": {
        "currencyMnemonic": "USD",
        "value": 15
      }
    },
    "tiers": [
      {
        "threshold": 100,
        "conditionType": "order_total",
        "discount": {
          "type": "amount",
          "amount": {
            "currencyMnemonic": "USD",
            "value": 15
          }
        }
      }
    ]
  },
  "qualifyingProducts": {
    "includedProducts": [
      {
        "conditions": [
          {
            "type": "category",
            "operator": "is_equal",
            "catalogId": "storefront-catalog-m-en",
            "values": [
              "electronics"
            ]
          }
        ]
      }
    ]
  }
}
```

#### Responses

*   **200** Discount rule replaced successfully.
    
    Media type: `application/json`. Schema: `DiscountRule`.
    
    _Example PutPromotionDiscountRule: same as GET /organizations/{organizationId}/promotions/{id}/discount-rule 200 response._
    
*   **201** Discount rule created successfully.
    
    Media type: `application/json`. Schema: `DiscountRule`.
    
    _Example PutPromotionDiscountRule: same as GET /organizations/{organizationId}/promotions/{id}/discount-rule 200 response._
    
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example putPromotionDiscountRule404: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

### DELETE Delete the discount rule for a promotion.

`DELETE /organizations/{organizationId}/promotions/{id}/discount-rule`

Operation ID: `deletePromotionDiscountRule`. Security: AmOAuth2 (sfcc.promotions.rw).

Removes the discount rule and its qualifiers from the promotion, resetting it to a shell with no discount configuration.

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** Deleted the discount rule successfully.
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example deletePromotionDiscountRule404: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

### PATCH Update the discount rule for a promotion.

`PATCH /organizations/{organizationId}/promotions/{id}/discount-rule`

Operation ID: `updatePromotionDiscountRule`. Security: AmOAuth2 (sfcc.promotions.rw).

Updates the discount rule, product qualifiers, or payment-method qualifiers for the promotion. The merge is at top-level-section granularity: any of promotionRule, qualifyingProducts, discountedProducts, excludedProducts, or paymentMethodQualifiers that is omitted is left unchanged, and any that is supplied fully replaces that section. In particular a supplied promotionRule replaces the entire rule - send the complete rule (including all tiers) to preserve tiers, since a promotionRule that omits tiers clears them. It is not a field-level (deep) merge.

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `DiscountRule`.

_Example: PatchPromotionDiscountRule_

```
{
  "promotionRule": {
    "promotionClass": "order",
    "discount": {
      "type": "percentage",
      "percentage": 10
    },
    "discountOnlyQualifyingProducts": false,
    "disableGlobalExcludedProducts": false
  }
}
```

#### Responses

*   **200** Discount rule updated successfully.
    
    Media type: `application/json`. Schema: `DiscountRule`.
    
    _Example PatchPromotionDiscountRule: same as GET /organizations/{organizationId}/promotions/{id}/discount-rule 200 response._
    
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example patchPromotionDiscountRule404: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

### GET Retrieve the compatibility settings for a promotion.

`GET /organizations/{organizationId}/promotions/{id}/compatibility`

Operation ID: `getPromotionCompatibility`. Security: AmOAuth2 (sfcc.promotions, sfcc.promotions.rw).

Returns the stacking / exclusivity settings that control how this promotion combines with other promotions.

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Retrieved the compatibility settings successfully.
    
    Media type: `application/json`. Schema: `PromotionCompatibility`.
    
    _Example: GetPromotionCompatibility_
    
    ```
    {
      "exclusivity": "class",
      "exclusivityGroup": "SummerSale",
      "combinablePromotions": [
        "10%offOrder"
      ],
      "mutuallyExclusivePromotions": [
        "20%offOrder"
      ]
    }
    ```
    
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example getPromotionCompatibility404: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

### PUT Create or replace the compatibility settings for a promotion.

`PUT /organizations/{organizationId}/promotions/{id}/compatibility`

Operation ID: `createPromotionCompatibility`. Security: AmOAuth2 (sfcc.promotions.rw).

Replaces the stacking / exclusivity settings for the promotion.

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `PromotionCompatibility`.

_Example: PutPromotionCompatibility_

```
{
  "exclusivity": "class",
  "exclusivityGroup": "SummerSale",
  "combinablePromotions": [
    "10%offOrder"
  ],
  "mutuallyExclusivePromotions": [
    "20%offOrder"
  ]
}
```

#### Responses

*   **200** Compatibility settings replaced successfully.
    
    Media type: `application/json`. Schema: `PromotionCompatibility`.
    
    _Example: PutPromotionCompatibility_
    
    ```
    {
      "exclusivity": "class",
      "exclusivityGroup": "SummerSale",
      "combinablePromotions": [
        "10%offOrder"
      ],
      "mutuallyExclusivePromotions": [
        "20%offOrder"
      ]
    }
    ```
    
*   **201** Compatibility settings created successfully.
    
    Media type: `application/json`. Schema: `PromotionCompatibility`.
    
    _Example: PutPromotionCompatibility_
    
    ```
    {
      "exclusivity": "class",
      "exclusivityGroup": "SummerSale",
      "combinablePromotions": [
        "10%offOrder"
      ],
      "mutuallyExclusivePromotions": [
        "20%offOrder"
      ]
    }
    ```
    
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example putPromotionCompatibility404: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

### PATCH Update the compatibility settings for a promotion.

`PATCH /organizations/{organizationId}/promotions/{id}/compatibility`

Operation ID: `updatePromotionCompatibility`. Security: AmOAuth2 (sfcc.promotions.rw).

Partially updates the stacking / exclusivity settings for the promotion. Each field (exclusivity, exclusivityGroup, combinablePromotions, mutuallyExclusivePromotions) that is omitted is left unchanged. A supplied combinablePromotions or mutuallyExclusivePromotions replaces that list wholesale - the entries are not merged into the existing list, so send the complete list.

#### Parameters

*   `id` (path, string, required) The ID of the promotion to create.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `PromotionCompatibility`.

_Example: PatchPromotionCompatibility_

```
{
  "exclusivity": "class",
  "exclusivityGroup": "SummerSale",
  "combinablePromotions": [
    "10%offOrder"
  ],
  "mutuallyExclusivePromotions": [
    "20%offOrder"
  ]
}
```

#### Responses

*   **200** Compatibility settings updated successfully.
    
    Media type: `application/json`. Schema: `PromotionCompatibility`.
    
    _Example: PatchPromotionCompatibility_
    
    ```
    {
      "exclusivity": "class",
      "exclusivityGroup": "SummerSale",
      "combinablePromotions": [
        "10%offOrder"
      ],
      "mutuallyExclusivePromotions": [
        "20%offOrder"
      ]
    }
    ```
    
*   **404** Returned when there is no promotion found for the specified ID for the requested site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example patchPromotionCompatibility404: same as GET /organizations/{organizationId}/promotions/{id} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PromotionSearchResult

Document representing a promotion search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Promotion_, required) The sorted array of promotion search hits. Can be empty.

### Promotion

Document representing a promotion. Unless otherwise stated, attributes of this document are not supported when using the Open Commerce API to update multiple promotions at once.

*   `archived` (_boolean_) Determines if this promotion is archived. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Example: `true`.
*   `assignmentInformation` (_object_) Information about the assignments and assignment schedules of this promotion.
    
    Includes all fields of `PromotionAssignmentInformation`.
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.
*   `currencyCode` (_string_) The ISO 4217 mnemonic code of the currency this promotion is restricted to. If not populated, then there is no currency restriction on the promotion.  
    Maximum length: 3.
*   `disableGloballyExcluded` (_boolean_) Determines if this promotion ignores the global product exclusions for promotions.  
    Example: `true`.
*   `enabled` (_boolean_) Determines if this promotion is enabled. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Example: `true`.
*   `exclusivity` (_string_) Determines if the promotion can be combined with other promotions of the same promotion class or if it cannot be combined with any other promotions. This attribute is allowed to be updated when using the Open Commerce API to update multiple promotions at once.  
    Allowed values: `no`, `class`, `global`.
*   `id` (_string_) The ID for the promotion.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.
*   `name` (_object_) The user supplied name of this promotion, which can be localized.
    
    Additional properties: `string`.
    
*   `promotionClass` (_string_) The class of the promotion. If the promotion class is modified, then the promotion rule and all of its values, such as whether or not to disable global product exclusions, are reset.  
    Allowed values: `product`, `shipping`, `order`.
*   `tags` (_array of Tag_) Returns the list of tags assigned to this promotion. If used to set the tags on a promotion, the promotion will only have the tags passed in the input. Any existing tags are removed.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### DiscountRule

The discount-rule document for a promotion, managed as a sub-resource at /promotions/{id}/discount-rule. It holds the discount rule (shape selected by promotionClass), the product qualifiers, and the payment-method qualifiers. The promotion shell (id, name, enabled, promotionClass) is managed separately on the parent /promotions/{id} resource.

*   `promotionRule` (_object_) The discount rule for this promotion. Its shape is selected by the parent promotion's promotionClass (product, order, or shipping) and holds the discount, tiers, BOGO, thresholds, max-applications, and class-specific flags.
    
    Includes all fields of `PromotionRule`.
    
*   `qualifyingProducts` (_object_) The products a customer must purchase for the promotion to apply.
    
    Includes all fields of `ProductSpecification`.
    
*   `discountedProducts` (_object_) The products that receive the discount. Valid only for a product-class promotion; supplying it for an order or shipping promotion is rejected with a 400.
    
    Includes all fields of `ProductSpecification`.
    
*   `excludedProducts` (_object_) The products excluded from both qualifying for and receiving the discount. Valid only for an order-class promotion; supplying it for a product or shipping promotion is rejected with a 400.
    
    Includes all fields of `ProductSpecification`.
    
*   `paymentMethodQualifiers` (_object_) The payment methods the promotion is restricted to.
    
    Includes all fields of `PromotedPaymentMethods`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PromotionCompatibility

The compatibility (stacking / exclusivity) document for a promotion, managed as a sub-resource at /promotions/{id}/compatibility. It controls how this promotion combines with other promotions of the same class.

*   `exclusivity` (_string_) Determines if the promotion can be combined with other promotions of the same promotion class, cannot be combined with any other promotion, or has no exclusivity restriction.  
    Allowed values: `no`, `class`, `global`. Example: `class`.
*   `exclusivityGroup` (_string_) The ID of the exclusivity group this promotion belongs to. Only meaningful when exclusivity restricts combination to promotions within the same group.  
    Maximum length: 256. Example: `SummerSale`.
*   `combinablePromotions` (_array of string_) The set of promotion or promotion-group IDs this promotion can be combined with.  
    Items: Maximum length: 256. Example: `10%offOrder`.
*   `mutuallyExclusivePromotions` (_array of string_) The set of promotion or promotion-group IDs this promotion cannot be combined with.  
    Items: Maximum length: 256. Example: `20%offOrder`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### PromotionAssignmentInformation

*   `abtestId` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the ID of the A/B test the segment belongs to. Otherwise, empty.
*   `abtestSegmentId` (_string_) If there is only one assignment, and that assignment is an A/B test segment, the ID of the A/B test segment. Otherwise, empty.
*   `active` (_boolean_, required) True if the individual assignment or the multiple assignments are currently active.  
    Example: `true`.
*   `activeAbtestAssignments` (_array of PromotionAbtestGroupAssignment_) A list of currently active A/B tests this is assigned to.
*   `activeCampaignAssignments` (_array of PromotionCampaignAssignment_, required) A list of currently active campaigns this is assigned to.
*   `campaignId` (_string_, required) If there is only one assignment, and that assignment is a campaign, the ID of the campaign. Otherwise, empty.
*   `enabled` (_boolean_, required)  
    Example: `true`.
*   `endDate` (_string (date-time)_) The end date of the container of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null. Also, a null date returns null.
*   `schedule` (_object_, required) The schedule of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null.
    
    Includes all fields of `Schedule`.
    
*   `scheduleType` (_string_, required) If there is only one active assignment, or no active assignments and one upcoming assignment, this is that type of assignment (scheduleType : "campaign" or scheduleType : "abtest"). If there are no assignments, it is scheduleType : "none", otherwise, scheduleType : "multiple".  
    Allowed values: `none`, `campaign`, `abtest`, `multiple`.
*   `startDate` (_string (date-time)_) The start date of the container of the assignment (a Campaign or ABTest). If scheduleType is scheduleType : "multiple" or scheduleType : "none", then then result is null. Also, a null date returns null.
*   `upcomingAbtestAssignments` (_array of PromotionAbtestGroupAssignment_) A list of upcoming A/B tests this is assigned to.
*   `upcomingCampaignAssignments` (_array of PromotionCampaignAssignment_) A list of upcoming campaigns this is assigned to.

### Tag

Document representing a tag

*   `tagId` (_string_, required) The ID of the tag.

### PromotionRule

The discount rule for a promotion. The concrete shape is selected by promotionClass: a product promotion uses ProductPromotionRule, an order promotion uses OrderPromotionRule, and a shipping promotion uses ShippingPromotionRule.

Discriminator: `promotionClass` selects the concrete type. Mapping: `product` → `ProductPromotionRule`, `order` → `OrderPromotionRule`, `shipping` → `ShippingPromotionRule`.

One of: `ProductPromotionRule`, `OrderPromotionRule`, `ShippingPromotionRule`.

### ProductSpecification

A set of product conditions. A product matches when it satisfies the included-products groups and none of the excluded-products groups.

*   `includedProducts` (_array of ProductConditionGroup_) The condition groups a product must match.
*   `excludedProducts` (_array of ProductConditionGroup_) The condition groups that exclude a product.

### PromotedPaymentMethods

The payment methods a promotion is restricted to.

*   `methodIds` (_array of string_) The payment method IDs. Each is either a payment method ID or a credit card type prefixed with CREDIT\_CARD (for example CREDIT\_CARD.Visa).  
    Items: Maximum length: 256. Example: `CREDIT_CARD.Visa`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### PromotionAbtestGroupAssignment

*   `abtestDescription` (_string_, required)
*   `abtestId` (_string_, required)
*   `enabled` (_boolean_, required)  
    Example: `true`.
*   `schedule` (_Schedule_, required)
*   `segmentDescription` (_string_, required)
*   `segmentId` (_string_, required)

### PromotionCampaignAssignment

Document representing a promotion campaign assignment.

*   `campaign` (_object_) The campaign.
    
    Includes all fields of `Campaign`.
    
*   `campaignId` (_string_, required) The ID of the campaign.  
    Minimum length: 1. Maximum length: 256.
*   `coupons` (_array of string_) The sorted array of assigned coupon IDs.
*   `customerGroups` (_array of string_) The sorted array of assigned customer groups.
*   `description` (_string_, required) The description of the promotion campaign assignment.  
    Maximum length: 4000.
*   `enabled` (_boolean_, required) True if the assignment resource is enabled.  
    Example: `true`.
*   `promotion` (_object_) The promotion.
    
    Includes all fields of `Promotion`.
    
*   `promotionId` (_string_, required) The ID of the promotion.  
    Minimum length: 1. Maximum length: 256.
*   `rank` (_integer (int32)_) The rank of promotion campaign assignment.
*   `schedule` (_object_, required) The schedule of the assignment resource.
    
    Includes all fields of `Schedule`.
    
*   `sourceCodeGroups` (_array of string_) The sorted array of assigned source code groups.

### Schedule

Document representing a time schedule. Defines an optional validity window (startDate/endDate) and an optional recurrence. Omitting a bound leaves that side of the window open (unbounded).

*   `startDate` (_string (date-time)_) The date to start validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_) The date to end of validity. ISO8601 date time format: yyyy-MM-dd'T'HH:mm:ssZ.  
    Example: `2026-01-31T23:59:59.000Z`.
*   `recurrence` (_object_) The recurrence of the schedule by day of week and time of day. Not all schedules support a recurrence.
    
    Includes all fields of `Recurrence`.
    

### ProductPromotionRule

The discount rule for a product promotion.

*   `promotionClass` (_string_, required) The promotion class discriminator. Always product for a product promotion rule.  
    Allowed values: `product`. Example: `product`.
*   `discount` (_object_) The discount applied by this rule.
    
    Includes all fields of `Discount`.
    
*   `tiers` (_array of TieredDiscount_) The tiered discounts, applied by threshold. Empty or absent for a non-tiered rule.
*   `bogo` (_object_) The buy-one-get-one discount. Present only for a buy-X-get-Y product promotion.
    
    Includes all fields of `BogoDiscount`.
    
*   `maxApplications` (_integer (int32)_) The maximum number of times the discount can be applied.  
    Minimum: 1. Example: `1`.
*   `identicalProducts` (_boolean_) Determines if the qualifying and discounted products must all be identical.  
    Example: `false`.
*   `prorate` (_boolean_) Determines if the discount is prorated across the eligible items.  
    Example: `false`.
*   `disableGlobalExcludedProducts` (_boolean_) Determines if this rule ignores the site-level global product exclusions. Distinct from the promotion-level disableGloballyExcluded flag.  
    Default: `false`. Example: `false`.

### OrderPromotionRule

The discount rule for an order promotion.

*   `promotionClass` (_string_, required) The promotion class discriminator. Always order for an order promotion rule.  
    Allowed values: `order`. Example: `order`.
*   `discount` (_object_) The discount applied by this rule.
    
    Includes all fields of `Discount`.
    
*   `tiers` (_array of TieredDiscount_) The tiered discounts, applied by threshold. Empty or absent for a non-tiered rule.
*   `discountOnlyQualifyingProducts` (_boolean_) Determines if only the qualifying products are discounted.  
    Example: `false`.
*   `excludeDiscountedProducts` (_boolean_) Determines if products that already received a product-level discount are excluded.  
    Example: `false`.
*   `disableGlobalExcludedProducts` (_boolean_) Determines if this rule ignores the site-level global product exclusions. Distinct from the promotion-level disableGloballyExcluded flag.  
    Default: `false`. Example: `false`.
*   `enableUpsells` (_boolean_) Determines if the promotion is returned as an approaching promotion to encourage upsell.  
    Example: `false`.
*   `upsellThreshold` (_object_) The amount by which the merchandise total may fall short of the purchase condition and still upsell.
    
    Includes all fields of `Money`.
    

### ShippingPromotionRule

The discount rule for a shipping promotion.

*   `promotionClass` (_string_, required) The promotion class discriminator. Always shipping for a shipping promotion rule.  
    Allowed values: `shipping`. Example: `shipping`.
*   `discount` (_object_) The discount applied by this rule.
    
    Includes all fields of `Discount`.
    
*   `tiers` (_array of TieredDiscount_) The tiered discounts, applied by threshold. Empty or absent for a non-tiered rule.
*   `shippingMethodQualifiers` (_object_) The shipping methods the promotion applies to. Shipping-class only.
    
    Includes all fields of `PromotedShippingMethods`.
    
*   `prohibitNonqualifyingProducts` (_boolean_) Determines if the shipment must contain only qualifying products for the discount to apply.  
    Example: `false`.
*   `disableGlobalExcludedProducts` (_boolean_) Determines if this rule ignores the site-level global product exclusions. Distinct from the promotion-level disableGloballyExcluded flag.  
    Default: `false`. Example: `false`.
*   `maxApplications` (_integer (int32)_) The maximum number of times the discount can be applied.  
    Minimum: 1. Example: `1`.

### ProductConditionGroup

A group of product conditions.

*   `conditions` (_array of ProductCondition_) The conditions in this group.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Campaign

Document representing a campaign.

*   `campaignId` (_CampaignId_, required)
*   `coupons` (_array of string_) The array of assigned coupon IDs, not sorted.
    
    _Example_
    
    ```
    [
      "20%offOrder",
      "10%offWelcomeNewUser"
    ]
    ```
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `customerGroups` (_array of string_) The array of assigned customer groups, not sorted.
    
    _Example_
    
    ```
    [
      "BigShoppers",
      "NorthAmericanShoppers"
    ]
    ```
    
*   `description` (_string_) The description of the campaign.  
    Maximum length: 4000.
*   `enabled` (_boolean_) The enabled flag for campaign.  
    Example: `true`.
*   `endDate` (_string (date-time)_) The date the scenario ends.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `2019-10-03T19:36:56.000Z`.
*   `sourceCodeGroups` (_array of string_) The array of assigned source code groups, not sorted.
    
    _Example_
    
    ```
    [
      "affiliate-email",
      "gaming-email"
    ]
    ```
    
*   `startDate` (_string (date-time)_) The date the scenario begins.  
    Example: `2019-10-03T19:36:56.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Recurrence

Document representing a schedule recurrence.

*   `dayOfWeek` (_array of string_) The days of week for recurrence.  
    Items: Allowed values: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`. Example: `monday`.
*   `timeOfDay` (_object_) The time of the day for recurrence.
    
    Includes all fields of `TimeOfDay`.
    

### Discount

A discount value object. The type determines which value field applies: amount, fixed\_price, total\_fixed\_price, and fixed\_price\_shipping use amount; percentage and percent\_off\_options use percentage; price\_book\_price uses priceBookId; bonus and bonus\_choice use bonusProducts; free\_shipping carries no value. Valid types depend on the enclosing promotion class - the schema does not enforce this, so the backend rejects an out-of-class type: product rules accept amount, percentage, fixed\_price, total\_fixed\_price, price\_book\_price, bonus, bonus\_choice, free\_shipping, fixed\_price\_shipping, percent\_off\_options; order rules accept amount, percentage, bonus, bonus\_choice; shipping rules accept fixed\_price, percentage, amount. A BOGO discount is a stricter product subset: fixed\_price, price\_book\_price, percentage, amount.

*   `type` (_string_, required) The kind of discount.  
    Allowed values: `amount`, `percentage`, `fixed_price`, `total_fixed_price`, `price_book_price`, `bonus`, `bonus_choice`, `free_shipping`, `fixed_price_shipping`, `percent_off_options`. Example: `amount`.
*   `amount` (_object_) The monetary value, for amount, fixed\_price, total\_fixed\_price, and fixed\_price\_shipping discounts.
    
    Includes all fields of `Money`.
    
*   `percentage` (_object_) The percentage off, for percentage and percent\_off\_options discounts.
    
    Includes all fields of `Percentage`.
    
*   `priceBookId` (_string_) The price book the discounted price is taken from, for a price\_book\_price discount.  
    Maximum length: 256. Example: `usd-list-prices`.
*   `bonusProducts` (_array of ProductId_) The bonus products offered, for bonus and bonus\_choice discounts.

### TieredDiscount

A single discount tier - a threshold and the discount applied once the threshold is met. All tiers in the same rule MUST carry the same conditionType - the backend applies one condition-type to the whole tier set and rejects mixed values.

*   `threshold` (_number (double)_, required) The threshold at which this tier's discount applies.  
    Minimum: 0. Example: `100`.
*   `conditionType` (_string_, required) The kind of threshold. All tiers in the same rule MUST send the same value. Valid values depend on the promotion class - product: product\_quantity, product\_amount; order: order\_total, product\_quantity, product\_combination; shipping: shipment\_total, product\_quantity, product\_combination.  
    Allowed values: `product_quantity`, `product_amount`, `order_total`, `product_combination`, `shipment_total`. Example: `order_total`.
*   `discount` (_object_, required) The discount applied at this tier.
    
    Includes all fields of `Discount`.
    

### BogoDiscount

A buy-one-get-one discount. In Business Manager the Type selector (Buy X / Get Y) is Product-class only.

*   `threshold` (_number (double)_) The quantity of eligible products required.  
    Minimum: 0. Example: `1`.
*   `discount` (_object_) The discount applied to the bonus product; typically fixed\_price, percentage, or amount.
    
    Includes all fields of `Discount`.
    
*   `eligibleQuantity` (_integer (int32)_) The number of eligible products that earn the bonus.  
    Minimum: 1. Example: `1`.
*   `requireExactEligibleQuantity` (_boolean_) Determines if exactly the eligible quantity is required, rather than at least.  
    Example: `false`.

### Money

A combination of a Currency and an amount of that Currency.

*   `currencyMnemonic` (_CurrencyCode_)
*   `value` (_number (double)_) The amount of money for the given currency.  
    Example: `1234.56`.

### PromotedShippingMethods

The shipping methods a shipping promotion applies to.

*   `methodIds` (_array of string_) The shipping method IDs.  
    Items: Maximum length: 256. Example: `001`.

### ProductCondition

A single product condition - a condition type, a comparison operator, and one or more values. Each condition type supports a specific operator (for example, category supports is\_equal, is\_exactly, is\_child\_of; brand and attribute add exists / does\_not\_exist).

*   `type` (_string_, required) The kind of product condition.  
    Allowed values: `brand`, `product_id`, `category`, `price`, `inventory`, `attribute`, `product_set`, `price_book`, `option`. Example: `category`.
*   `operator` (_string_) The comparison operator, as a lower\_snake\_case token. The valid set depends on the condition type: category: is\_equal, is\_exactly, is\_direct\_child\_of, is\_child\_of, is\_direct\_parent\_of, is\_parent\_of, is\_sibling\_of; brand: exists, does\_not\_exist, is\_equal, is\_not\_equal, starts\_with, ends\_with, contains, does\_not\_contain; product\_id: is\_equal, is\_not\_equal, starts\_with, ends\_with, contains, does\_not\_contain; price: less\_than, greater\_than, ends\_with; inventory: less\_than, greater\_than; attribute: less\_than, greater\_than, equals, is\_not\_equal, exists, does\_not\_exist, starts\_with, ends\_with, contains, does\_not\_contain; product\_set: is\_equal, exists; price\_book: storefront\_price\_in\_recursive, storefront\_price\_in, price\_in; option: is\_equal, exists, does\_not\_exist.  
    Maximum length: 256. Example: `is_equal`.
*   `values` (_array of string_) The values compared against.  
    Items: Maximum length: 256. Example: `electronics`.
*   `catalogId` (_string_) The id of the catalog that owns the categories listed in `values`. Required when `type` is \`category; ignored for every other condition type.  
    Maximum length: 256. Example: `storefront-catalog-m-en`.
*   `attributeId` (_string_) The id of the custom product attribute to compare. Required when `type` is `attribute`; ignored for every other condition type.  
    Maximum length: 256. Example: `color`.
*   `optionId` (_string_) The id of the product option to compare. Required when `type` is `option`; ignored for every other condition type.  
    Maximum length: 256. Example: `memorySize`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### CampaignId

The ID of the campaign.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `NewYearCampaign`.

### TimeOfDay

Document representing a time schedule within a single day.

*   `timeFrom` (_string_) The time to start from. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `09:00:00`.
*   `timeTo` (_string_) The time to end on. Time format: HH:mm or HH:mm:ss. Seconds are ignored and set to 0.  
    Pattern: ^(\[01\]\[0-9\]|2\[0-3\]):\[0-5\]\[0-9\](https://developer.salesforce.com/docs/commerce/commerce-api/references/:/[0-5/]/[0-9/])?$. Example: `17:00:00`.

### Percentage

A percentage value, from 0 to 100.

Type: `number (double)`.

Minimum: 0. Maximum: 100. Example: `10`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

<!-- document id=2a9e477935dd0e584165a3e8001b0eddfbb3efeecd4f8828a6ee7883e1bd97a9 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-promotions-limits.md -->

# Promotions Data Limits

| Object                                     | Limit for B2B                                                              | Store or Org | Notes                                                                                                                                                   |
| ------------------------------------------ | -------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Total Promotions per Org                   | 5,000                                                                      | Org          | This limit includes both active and inactive promotions.                                                                                                |
| Total Coupons per Org                      | 1 million                                                                  | Org          |                                                                                                                                                         |
| Total Active Promotions Evaluated per Cart | 50<sup>\*</sup> Automatic Promotions <br>50<sup>\*</sup> Coupon Promotions | N/A          | You can’t have more than a combined 100 automatic and coupon promotions evaluated per cart. Promotions beyond this combined 100 limit aren't evaluated. |
| Total Promotions applied per Cart          | 24 Product Promotions<br> 6 Order Promotions                               | N/A          | If you set exclusivity to None, you can have all 24 product level and all 6 order promotions applied to a single cart.                                  |
| Number of Coupons per Cart                 | 5                                                                          | N/A          |                                                                                                                                                         |
| Header Level Promotions per Cart           | 6                                                                          | N/A          | The header-level promotion with the highest priority is applied to a cart.                                                                              |
| Line Item Level Promotions per Cart        | 24                                                                         | N/A          | The line item level promotion with the highest priority is applied to a cart.                                                                           |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce Customer Support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

To moderate the use of promotion data, focus on key promotions that align with your business goals and marketing strategies. Prioritize promotions that are likely to have the most significant impact on customer engagement and sales. Consider limiting the number of active promotions to those that are most relevant and impactful. Avoid having an excessive number of active promotions to stay within data limits.

Conduct regular reviews of existing promotions. Remove any outdated or unused promotions, and make sure that the information within each promotion is accurate and up-to-date.

Use expiration dates for promotions to automatically deactivate them when they expire. This helps prevent the accumulation of outdated or inactive promotions in the system.

Before implementing changes or introducing new promotions in the production environment, thoroughly test them in a sandbox environment. Make sure that the data generated during testing doesn't contribute to unnecessary storage consumption.

If you have promotion data requirements that exceed the limits, consider the impact on checkout performance and the promotion data storage limits.

- Does the additional data push any related data objects beyond their limits?
- Can you offset a data increase by decreasing data requirements in other store functions?

After you assess the impact of a data increase, if you still want to request an increase, contact Support.

<!-- document id=5e41b1d4871a816d042dc8d5fadc1eed264a4c73f4b03fcd9b5d8ab849816e69 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-promotions.md -->

# Promotions Data Model

The Promotions data model connects objects with relationships that govern how promotions are applied to products and cart items throughout the checkout cycle.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the Promotions data model require at least one of the following licenses: B2B Commerce.

![Diagram of the Promotions Data Model](https://developer.salesforce.com/media/d2c-commerce/commerce_cloud_promotion_zh.png)

- [Promotion](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotion.htm?q=promotion)
- [Coupon](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_coupon.htm)
- [CouponCodeRedemption](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_couponcoderedemption.htm)
- [PromotionSegmentSalesStore](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotionsegmentsalesstore.htm)
- [PromotionSegmentBuyerGroup](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotionsegmentbuyergroup.htm)
- [PromotionSegment](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotionsegment.htm)
- [PromotionMarketSegment](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotionmarketsegment.htm)
- [PromotionTier](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotiontier.htm)
- [PromotionQualifier](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotionqualifier.htm)
- [PromotionTarget](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotiontarget.htm)
- [PromotionLineItemRule](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_promotionlineitemrule.htm)
- [BuyerGroup](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergroup.htm)
- [SalesStore (WebStore)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)
- [OrderSummary](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_ordersummary.htm)
- [OrderItemSummary](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_orderitemsummary.htm)
- [OrderItemAdjustmentLineSummary](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_orderitemadjustmentlinesummary.htm)
- [Promotions Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-promotions.md)

<!-- document id=b468b5baa442bd976aea6d7fe7548c8ee3293e1854b8e8854625b93c516df03e url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/tracking-consent.md -->

# Protect Privacy with a Tracking Consent Banner

Preserve shopper trust with a tracking consent banner on your [Progressive Web App (PWA) Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) site. With the banner, your shoppers can opt in or out of the default activity tracking included in PWA Kit.

This guide explains the default implementation and customization options for the tracking consent banner.

**note:** The functionality described in this guide isn’t supported in a [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md).

## Prerequisites

To configure and use the tracking consent banner, build your site with [Retail React App](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/README.md) version 6.0 or later.

## Default Tracking Consent Implementation

### Banner UI

The tracking consent banner is available in `template-retail-react-app/app/components/_app/index.jsx`, so you can display it on any page on your site. The banner is defined in `template-retail-react-app/app/hooks/use-dnt-notification.js`.

By default, the banner looks similar to this example.

![Tracking Consent Process](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/tracking-consent-ui.png)

### Do Not Track Values

These are the two values that define what the DNT state is set to:

- `effectiveDnt`: Is set to the default DNT state that you configured or is set to `false` if you didn't configure a default DNT state. This value is set to `false` if the shopper consented to tracking or `true` if the shopper opted out of tracking.
- `selectedDnt`: Is undefined until the shopper interacts with the consent banner. This value is set to `false` if the shopper consented to tracking or `true` if the shopper opted out of tracking.

### Banner and DNT Workflow

If a shopper closes the banner or doesn’t make a selection in the banner, the default DNT state is set to `false` (track activity). To change that behavior, see [Configure the Default DNT State](#configure-the-default-dnt-state). The banner reappears the next time the shopper visits your site after they take any of these actions:

- Close the browser
- Refresh site data
- Clear their cookies

The tracking preference is represented by the `dw_dnt` cookie. The cookie value is `0` if tracking is consented to and `1` if it isn’t. This value is synced with the backend through the DNT claim in the SLAS access token. The use of the SLAS access token is currently the way to pass the DNT preference to SCAPI. For more information about the use of the DNT claim in SLAS and the use of APIs and hooks, see [Manage Shopper Tracking Preferences](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-tracking-preferences.html).

This diagram summarizes the behavior of the tracking consent banner and how shoppers’ DNT state is set when they visit your site. Unless otherwise stated, all of the steps in the diagram apply to both guest shoppers and known shoppers.

![Tracking Consent Process](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/tracking-consent-process.png)

## Configure the Default DNT State

Optionally, you can specify a default DNT state that applies if a shopper closes the tracking consent banner or doesn’t make a selection in the banner. To do so, set the `defaultDNT` property in this file in your project: `{overridesDir}/app/components/_app-config/index.jsx`.

- `defaultDnt={true}`: Indicates that shopper activity isn’t tracked.
- `defaultDnt={false}`: Indicates that shopper activity is tracked.

In this example, `defaultDnt` is set to `false`.

```jsx
   // More code here...

   <CommerceApiProvider
            shortCode={commerceApiConfig.parameters.shortCode}
            clientId={commerceApiConfig.parameters.clientId}
            organizationId={commerceApiConfig.parameters.organizationId}
            siteId={locals.site?.id}
            locale={locals.locale?.id}
            currency={locals.locale?.preferredCurrency}
            redirectURI={`${appOrigin}/callback`}
            proxy={`${appOrigin}${commerceApiConfig.proxyPath}`}
            headers={headers}
            // Add your chosen default DNT state.
            defaultDnt={false}
            // Uncomment 'enablePWAKitPrivateClient' to use SLAS private client login flows.
            // Make sure to also enable useSLASPrivateClient in ssr.js when enabling this setting.
            // enablePWAKitPrivateClient={true}
            logger={createLogger({packageName: 'commerce-sdk-react'})}
        >
            <MultiSiteProvider site={locals.site} locale={locals.locale} buildUrl={locals.buildUrl}>
                <ChakraProvider theme={theme}>{children}</ChakraProvider>
            </MultiSiteProvider>
            <ReactQueryDevtools />
   </CommerceApiProvider>

   // More code here...
```

## Customize the Tracking Consent Banner

Optionally, you can customize the tracking consent banner by changing parts of it such as the appearance or text. [Override the banner file in the base template](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html) by completing these steps.

1.  If you haven’t done so already, in your PWA Kit project, create a folder called `hooks` in `{overridesDir}/app`.
2.  Create a file called `use-dnt-notification.js` in the `hooks` folder.
3.  Copy and paste this code into `use-dnt-notification.js`. In this example, we use `selectedDnt` to render a customized banner that's controlled by the `DntNotification` component. Also, we use the `updateDnt` function to apply a shopper's tracking preference as a boolean. See [Do Not Track Values](#do-not-track-values).

```jsx
import React, {useEffect} from 'react'
import PropTypes from 'prop-types'
import {FormattedMessage, useIntl} from 'react-intl'
import {
    Button,
    Modal,
    ModalContent,
    ModalBody,
    ModalCloseButton,
    useDisclosure,
    Heading,
    Stack,
    Text,
    Flex
} from '@salesforce/retail-react-app/app/components/shared/ui'
import {useDNT} from '@salesforce/commerce-sdk-react'
import {useLocation} from 'react-router-dom'

export const DntNotification = ({isOpen, onOpen, onClose}) => {
    const {selectedDnt, updateDNT} = useDNT()
    const {formatMessage} = useIntl()
    const location = useLocation()

    useEffect(() => {
        if (selectedDnt === undefined) {
            onOpen()
        } else {
            onClose()
        }
    }, [location, selectedDnt])

    const onCloseNotification = () => {
        updateDNT(null)
        onClose()
    }

    return (
        <Modal
            size="sm"
            data-testid="sf-dnt-notification"
            blockScrollOnMount={false}
            closeOnOverlayClick={false}
            trapFocus={false}
            isOpen={isOpen}
            onOpen={onOpen}
            onClose={onCloseNotification}
        >
            <ModalContent
                position="fixed"
                bottom="4"
                right="4"
                maxW="400px"
                pointerEvents="all"
                containerProps={{
                    pointerEvents: 'none'
                }}
                border="2px solid"
            >
                <ModalCloseButton
                    aria-label={formatMessage({
                        id: 'dnt_notification.button.assistive_msg.close',
                        defaultMessage: 'Close consent tracking form'
                    })}
                />
                <ModalBody pb={8} bg="white" marginTop={4}>
                    <Heading as="h3" fontSize={25} width="100%" marginBottom={5}>
                        <FormattedMessage
                            defaultMessage="Your Privacy Matters to Us"
                            id="dnt_notification.title"
                        />
                    </Heading>
                    <Flex direction="column">
                        <Text>
                            <FormattedMessage
                                defaultMessage="We collect data to improve your experience, deliver personalized content or ads, and better understand how our site is used. By selecting 'Accept,' you agree to our use of tracking technologies. "
                                id="dnt_notification.description"
                            />
                        </Text>
                        <Stack direction="column" spacing={4} mt={4} align="flex-end">
                        <>
                            <Button
                                onClick={() => {
                                    updateDNT(true)
                                    onClose()
                                }}
                                width="100%"
                            >
                                <FormattedMessage defaultMessage="Decline" id="dnt_notification.button.decline" />
                            </Button>
                            <Button
                                onClick={() => {
                                    updateDNT(false)
                                    onClose()
                                }}
                                width="100%"
                            >
                                <FormattedMessage defaultMessage="Accept" id="dnt_notification.button.accept" />
                            </Button>
                        </>
                        </Stack>
                    </Flex>
                </ModalBody>
            </ModalContent>
        </Modal>
    )
}

DntNotification.propTypes = {
    isOpen: PropTypes.bool.isRequired,
    onOpen: PropTypes.func.isRequired,
    onClose: PropTypes.func.isRequired
}

/**
 *
 * @returns {Object} - Object props to be passed into the DntNotification component
 */
export const useDntNotification = () => {
    const {isOpen, onOpen, onClose} = useDisclosure()

    return {
        isOpen,
        onOpen,
        onClose
    }
}
```

- If you overrode the `app/components/_app/index.jsx` file in your PWA Kit project, utilize the `useDntNotification` hook to display your customized tracking consent banner.

```jsx
import {
    DntNotification,
    useDntNotification
} from '{overridesDir}/app/hooks/use-dnt-notification'

const App = (props) => {
   ...
   const dntNotification = useDntNotification()
   ...

   return (
        ...
        // Put the consent tracking banner in your chosen location in your code by adding the dntNotification component.
        <DntNotification {...dntNotification} />
        ...
   )
}
```

## Suppress Tracking Based on DNT State

Optionally, you can add code in your PWA Kit project to trigger or prevent actions based on a shopper's tracking preference or your default DNT state.

Use `effectiveDnt` to trigger or prevent actions such as API calls. For example, API calls to access Google Analytics. See [Do Not Track Values](#do-not-track-values).

In this example, we use `effectiveDnt` to trigger an analytics API call with the goal of gathering data based on a shopper's interactions with a site. The data can provide insights about factors such as shopper behavior, website traffic, or sales performance.

```jsx
import {
    useDNT
} from '@salesforce/commerce-sdk-react'
function reportClickTracking() {
  const {effectiveDnt} = useDNT()
  if (effectiveDnt) {
    return
  }
  return fetch('https://tracking.example.com/collect')
}
```

## Considerations

- If a shopper opts out of tracking (the DNT state is set to `true`) or the DNT state isn’t set:

  - Einstein events are suppressed. This means that a shopper’s activity on your site isn’t included in [Reports & Dashboards](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/reports-and-dashboards.md).
  - Active Data metrics are collected if you enabled the feature as described in [Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/active-data.md). However, all shopper data is anonymized.

- PWA Kit overrides any default tracking configuration that you set under [privacy preferences](https://help.salesforce.com/s/articleView?id=cc.b2c_setting_privacy_preferences.htm&type=5) in Business Manager. Your PWA Kit site applies either of these configurations:
  - **PWA Kit:** The default or custom tracking configuration described in this guide.
  - **Shopper Login and API Access Service(SLAS):** If you customized the tracking consent banner using SLAS, your site applies the tracking configuration described in [Manage Shopper Tracking Preferences](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-tracking-preferences.html).

## Troubleshoot Tracking Consent

This section provides a suggested solution for a common error that you can encounter while using the tracking consent banner.

### Banner Doesn’t Appear or Behavior is Unexpected

**Cause:** CSS or JavaScript issues can hamper functionality or cause the banner to display incorrectly or not at all on certain devices or browsers.

**Suggested Solution:** Test the banner in multiple browsers and devices to ensure consistent functionality. Pay particular attention to browsers with stricter cookie policies (for example, Safari’s Intelligent Tracking Prevention). Test different screen sizes and resolutions to ensure that the banner is responsive and user-friendly. Confirm that the banner doesn’t interfere with any site functionality or shopper interactions.

## See Also

- [Manage Shopper Tracking Preferences](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-tracking-preferences.html)
- _Salesforce Help:_
  - [Commerce Einstein Do-Not-Track Impact](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_dnt_feature_impact.htm&type=5)
  - [Set Privacy Preferences for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_setting_privacy_preferences.htm&type=5)
  - [Data Protection and Privacy](https://help.salesforce.com/s/articleView?id=cc.b2c_data_protection_and_privacy.htm&language=en_US&type=5)

<!-- document id=8a82ec879a6f2375437cff803d734bff3b4bfe428bd2f53dd68b81f5282cb232 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-prototyped-cmp.md -->

# Prototyped UI Components

Some Storefront Next components are representative of the intended storefront experience and they aren't connected to B2C Commerce for data persistence. Although these components render in the UI, their data is temporary and is lost when the page refreshes. These prototyped components require that you set up third-party data sources through extensions before production use. See [Extend Storefront Next with Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-extend.md)

## Account Page Features

These account pages persist data to localStorage or in-memory only.

- Pickup Preferences
- Customer Interests
- Product Category Preferences
- Shopping Preferences
- Size Preferences
- Room Measurements

## Product Detail Page (PDP) Content Sections

These PDP page sections have hardcoded sample data.

- Size guide
- Returns & warranty info
- Buy Now, Pay Later messaging
- Estimated delivery
- Extended product description
- Ingredients list
- Usage instructions
- Care instructions
- Tech specs
- FAQ / Q&A
- Reviews summary
- Reviews list
- Write a Review form
- Shipping estimates

These reviews features have sample data.

- Stars
- AI Summary
- Sort Order
- Search Box
- Name
- Location
- Verified Purchase
- Review
- Helpful
- Report

## Order Confirmation Page

The order confirmation page has help links and a newsletter signup form that are placeholders.

- FAQ link
- Contact Us link
- Returns link
- Newsletter signup

## Contact Form on the About Us Page

The contact form shows a sample success toast and discards the message.

## See Also

- [Provide Data Source Implementations with Adapters](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-adapters.md)

<!-- document id=3531612a92e083833ae867bf9a82496bf002211d8d56bd727b81f6c182410e5c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/search-and-navigation/b2c-providing-a-view-all-button-for-search-results.md -->

# Provide a View All Button for Search Results

Create a View All button for search results.

## To Create a View All Button for Search Results:

1.  Create the resource messages for the View All link.

    To the pagingcomponents.properties file, add a `pagecomponents.paging.viewall=View All` resource message.

2.  In the **pt_global.css,** add a `.pagination li.viewall`style. This can be the same as the `.pagination li.nextpage` style.
3.  In the Search pipeline, click the **Paging (bc_api)** pipelet and change the value of the PageSize property to CurrentHttpParameterMap.sz.intValue. This causes the pipelet to derive the value of the paging size from the value passed into the pipeline if it's present. The name of the property is set by the PagingModel class AppendPaging method.
4.  To the pagingbar.isml file, you need to add the following in the first \<sscript>in the file:

    ```javascript
    if (pdict.pagingmodel.pageSize == null) {
      pageSize = 9;
    } else {
      pageSize = pdict.pagingmodel.pageSize;
    }
    ```

5.  After the next page control, add:

    ```javascript
    <isif condition="${totalCount > pageSize}">
      <isscript>dict.pagingmodel.setPageSize(totalCount); </isscript>
      <li>
        <a href="${pdict.pagingmodel.appendPaging( pageURL, 0)}">
          ${Resource.msg("pagecomponents.paging.viewall", "pagecomponents", null)}
        </a>
      </li>
      <isscript>pdict.pagingmodel.setPageSize(pageSize); </isscript>
    </isif>
    ```

**note:** When you have made this change, you can't change the default paging size directly from the pipeline. Instead, you have to change the pageSize = 9 line in the pagingbar.isml file to the desired value.

<!-- document id=b0fcf882ec67567151bbd071985556d599b777ec1aaece1e330abbc432956b95 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/order-mgmt.md -->

# Provide Orders from Salesforce Order Management

Starting in PWA Kit 3.16, Composable Storefront orders are integrated with Salesforce Order Management (SOM). Also, starting in PWA Kit 3.19, registered shoppers can manage their SOM orders in Composable Storefront. The storefront shows customer order details and order history from SOM, if available. The integration requires that you set up a connection between the B2C Commerce instance and the SOM organization. Providing shoppers with a real-time view of their past and current orders from SOM empowers them to check their order status and history, which reduces support costs. This integration keeps storefront orders synchronized with the merchant’s backend order management system.

## Prerequisite: Connect Your B2C Commerce Instance and the Order Management Organization

Before the storefront can show SOM orders, perform these steps.

### Step 1: Connect a B2C Commerce Instance to the SOM organization

1. To connect the B2C Commerce instance to SOM, see [Connect B2C Commerce and Order Management](https://help.salesforce.com/s/articleView?id=commerce.om_impl_self_provision.htm&type=5) in _Salesforce Help_.
2. Enable sharing of SOM records. See [Enable Order Management for B2C Commerce](https://help.salesforce.com/s/articleView?id=commerce.om_impl_enable_integration.htm&type=5) in _Salesforce Help_.

### Step 2: Test the Connection by Placing an Order

To test the integration, place an order from the storefront to SOM by using the `placeOrder` hook. After the connection is set up, call `OrderMgr.placeOrder(order)` to create an order in SOM.

This code snippet shows one way to place an order and handle the order placement flow. It places an order in SOM via the `placeOrder` hook. Next, it gets the export and confirmation status if the order placement was successful. You can implement additional logic to satisfy your specific requirements.

```javascript
// Validate user, Validate Payment etc
var orderStatus = OrderMgr.placeOrder(order)
if (!orderStatus.error) {
  order.setExportStatus(Order.EXPORT_STATUS_READY)
  order.setConfirmationStatus(Order.CONFIRMATION_STATUS_CONFIRMED)
}
```

## Composable Storefront-SOM Integration Considerations

- Payment methods aren't shown in the storefront because they aren't returned in B2C Commerce API (SCAPI) calls.
- If an order contains multiple shipments, items are grouped by shipment and each group shows its shipping address. Tracking details, such as carrier, status, and tracking number or URL, are shown separately and aren't tied to a specific shipping address because Order Management shipment data can't be reliably correlated to the delivery address.

## Getting Orders from SOM

By default, Composable Storefront tries to get order data from SOM. It makes these SCAPI calls with the additional `oms` parameters.

- Get order details: The storefront calls `GET orders/{orderNo}` with query parameter `expand=oms,oms_shipments`. For more information, see [getOrder](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=getOrder) in the B2C Commerce API Guide.
- Get order history: The storefront calls `GET customers/{}/orders` with query parameter `expand=oms`. See [getCustomerOrders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=getCustomerOrders) in the B2C Commerce API Guide.

## Placing Orders in SOM

If the connection is set up between the B2C Commerce instance and SOM, placing an order creates the order in SOM. Place the order using the `placeOrder` hook and by calling `OrderMgr.placeOrder(order)`.

## Managing Orders in SOM

Starting with PWA Kit 3.19, the Salesforce Order Management (SOM) integration in your Composable Storefront lets registered shoppers manage orders stored in SOM. PWA Kit provides default implementations for the order actions in SOM so you don't have to implement them. The actions available are for shoppers tracking order shipments, canceling an order, and returning order items.

SOM enriches orders with order data, in the `omsData` field that is included in the SCAPI call. The order actions call these SCAPI endpoints:

- [returnOmsOrder](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=returnOmsOrder)
- [cancelOmsOrder](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=cancelOmsOrder)

### Prerequisites

- Managing orders requires that you connect your B2C Commerce instance to the Salesforce Order Management organization. See [this prerequisite step](#prerequisite-connect-your-b2c-commerce-instance-and-the-order-management-organization).

### Accessing the Order Detail Page

A shopper accesses the order management actions in the order detail page. These are the steps for a shopper to access the order detail page.

1. Log in and then click the **My Account** icon.
2. Click **Order History**.
3. Next to an order, click **View Details**.

![Order detail page showing buttons for tracking shipments, canceling an order, and returning items](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-order-action-buttons.png '{"class": "image-xl"}')

### Tracking Order Shipments

After an order has been fulfilled, a registered shopper can track the order shipments by clicking **Track Shipment** on the order detail page. Clicking **Track Shipment** redirects the shopper to an external site where they can track the shipments.

### Canceling an Order

For orders that haven't been fulfilled yet, registered shoppers can cancel the orders they created by clicking **Cancel Order** on the order detail page. After an order has been fulfilled and shipped, it is no longer cancelable. To be able to cancel an order, every item in the order must be cancelable.

![The cancel order modal with cancellation reasons](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-cancel-order-modal.png '{"class": "image-lg"}')

### Returning Eligible Items

After an order has been fulfilled, a registered shopper can return eligible items by clicking **Return Items** on the order detail page. In the Return items modal, the shopper can select one or more items to return, their quantity, and the return reason.

![The return item modal with return reasons](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-return-item-modal.png '{"class": "image-xl"}')

After submitting a return request, the order's status badge reflects the return's progress. This progress includes partial return status, when a return is initiated for a subset of items in an order.

**note:** Return and cancellation reasons come from SOM. They aren't hardcoded in PWA Kit.

### Order Refunds

SOM processes the refunds for order cancellations and returns, and not B2C Commerce or PWA Kit. There is nothing to implement in PWA Kit for refunds. The storefront's responsibility ends at initiating the return or cancellation.

For returns, the automated refund occurs only after the item is physically returned, not when the shopper initiates the return:

1. Shopper requests a return. The `create-return-order` API creates a return order in SOM.
2. The item is physically returned, and the return order is closed manually in the SOM UI or via an API integration.
3. The close event triggers the `EnsureRefunds` API, which makes a callout to the payment service provider (PSP) to process the refund. A credit memo is generated.

For cancellations, the same automated refund process fires on the order's status change.

## Status Badge

The status badge shows the order status for each order. The status badge indicates order placement, fulfillment, cancellation, and return progress.

To customize the display status, override `getOrderDisplayStatus(order)` in `app/utils/order-status-utils.js`, which aggregates item-level SOM statuses into a single display status.

<!-- document id=d911147c381542ef0306b0fdcdb31560fadf015caa5fc4746b37de0e4646f1be url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/proxying-requests.md -->

# Proxy Requests

Managed Runtime's [proxy](https://en.wikipedia.org/wiki/Proxy_server) feature allows you to route requests to APIs hosted on different domains through the same domain as your storefront.  
![Associated diagram](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/proxying-requests-diagram.png)

Why use the same domain as your storefront? Imagine your storefront is hosted at `www.northerntrailoutfitters.com` and you want to request B2C Commerce API from `api.commercecloud.salesforce.com`. Making this request without proxying involves extra configuration steps and isn’t as fast and observable as it could be with proxying. Let’s compare the two approaches:

| Without Proxying                                                                                                  | With Proxying                                                                              |
| :---------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- |
| You must configure the API server to respond with cross-origin resource sharing (CORS) headers.                   | No extra configuration required for CORS.                                                  |
| API requests require an extra preflight request, slowing performance.                                             | No extra network requests made.                                                            |
| If the API server doesn’t cache responses, you lose an opportunity to boost performance significantly.            | You can instruct Managed Runtime’s CDN to cache specific requests.                         |
| If you don’t have access to the logs for the API server, it’s hard to measure how it affects overall performance. | All API requests that are routed through Managed Runtime’s CDN through proxies are logged. |

Now that you understand the value of using proxies, let’s explore the various methods for configuring them.

## Configure the Local Development Environment

During local development proxies can be configured by editing the `mobify.ssrParameters.proxyConfigs` array in `<PROJECT_DIR>/config/default.js`. For example, to configure a proxy for the B2C Commerce API:

```json
{
  "proxyConfigs": [
    {
      "host": "<SHORT_CODE>.api.commercecloud.salesforce.com",
      "path": "api"
    }
  ]
}
```

The `proxyConfigs` array contains objects that define a proxy configuration with the following properties:

- `host`: the origin host that receives your requests.
- `path`: the name used in the request path to identify this proxy.

To make a proxy request in your application code, follow this pattern when building request paths: `/mobify/proxy/<PROXY_PATH>`.

**tip:** Choose proxy paths that make it easy to recognize which APIs you’re using.

Let’s look at an example request that uses `api` as the `path` value. By default, projects created with PWA Kit include proxy configuration that associates the `api` path with the B2C Commerce API.

```javascript
import {getAppOrigin} from 'pwa-kit-react-sdk/utils/url'

// `getAppOrigin` returns the correct origin for both local development and Managed Runtime environments.
fetch(`${getAppOrigin()}/mobify/proxy/api/categories/bikes`)
```

When you change proxy configuration during local development, you _must_ restart your local development server for the changes to take effect.

## Configure Managed Runtime Environments

**warning:** Support for HTTP proxy configurations is scheduled for retirement on **August 31, 2026**. After that date, only HTTPS proxy configurations are supported. Update any existing HTTP proxy configurations to use HTTPS before this date to avoid disruptions.

Managed Runtime ignores the proxy settings in configuration files. Instead, proxies must be configured using Runtime Admin or the Managed Runtime API.

### Use Runtime Admin

To configure proxies for a Managed Runtime environment using our web-based admin tool, follow these steps:

1.  Log in to the [Runtime Admin](https://runtime.commercecloud.com).
2.  Click your project.
3.  Click an environment.
4.  Click **Environment Settings** from the left navigation menu.
5.  In the **Advanced** section, click **Edit**.
6.  Under **Proxy Configs**, click **Add New Proxy**.
7.  Enter the path, protocol, and host.
8.  Repeat for up to 8 proxy configurations.
9.  Go back to the start of the **Advanced** section and click **Update**.
10. Wait for the bundle to finish redeploying.
11. Verify that the proxy configuration is working as expected.

![Screenshot of Runtime Admin](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/runtime-admin.png)

### Use the Managed Runtime API

You can also configure proxies for Managed Runtime environments programmatically using the [`projects_target_partial_update`](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_partial_update) endpoint. _The Managed Runtime API often uses the term “target” instead of “environment,” but both terms refer to the same thing._

Here’s an example request that updates an environment to include a proxy configurations for the `api` and `ocapi` paths:

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$API_KEY"

npx @salesforce/b2c-cli mrt env update \
  --project "$PROJECT" --environment "$ENVIRONMENT" \
  --proxy api=api.commercecloud.salesforce.com \
  --proxy ocapi=aaaa-001.dx.commercecloud.salesforce.com
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/" \
  --request 'PATCH' \
  --header "Authorization: Bearer $API_KEY" \
  --data '{
            "ssr_proxy_configs": [
                {
                    "host": "api.commercecloud.salesforce.com",
                    "path": "api",
                },
                {
                    "host": "aaaa-001.dx.commercecloud.salesforce.com",
                    "path": "ocapi"
                }
            ]
          }'
```

When creating or updating environments, the JSON request body accepts an array of proxy configuration objects from a field called `ssr_proxy_configs`. Proxy configuration objects include `host` and `path`, like in [configuration files](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configuration-options.md).

## Avoid Downtime in Production

To avoid downtime, the steps for adding or removing proxies in a production environment must be done in a specific order.

To **add a proxy** to a production environment:

1. Edit the environment settings for the production environment using Runtime Admin or the Managed Runtime API. (Follow the instructions described earlier.)
2. Add the new proxy to the environment settings and save your edits.
3. Update your PWA Kit code to use the new proxy.
4. Push a new bundle of your PWA Kit code to Managed Runtime.
5. Deploy the new bundle.

To **remove a proxy** from a production environment:

1. Update your PWA Kit code to use the new proxy.
2. Push a new bundle of your PWA Kit code to Managed Runtime.
3. Deploy the new bundle.
4. Edit the environment settings for the production environment using Runtime Admin or the Managed Runtime API. (Follow the instructions described earlier.)
5. Remove the new proxy from the environment settings and save your edits.

## Override Local Proxy Configurations with Environment Variables

In local development, you can override the proxy configurations using environment variables.

Set an environment variable called `SSR_PROXY1` to override the first element in the `proxyConfigs` array, set one called `SSR_PROXY2` to override the second element, and so on.

Here's how it works: If the environment variable `SSR_PROXY1` is set to `https://api-staging.example.com/api`, it replaces the first element in the `proxyConfigs` array with the following proxy configuration object:

```json
{
  "host": "api-staging.example.com",
  "path": "api"
}
```

These environment variables are commonly used with the `npm start` command during local development to use different instances of the API host, such as staging or production. Here’s an example that overrides the first proxy configuration object so that the `api` path routes requests to a staging instance:

```bash
SSR_PROXY1=https://api-staging.example.com/api npm start
```

## Look Up the Current Proxy Configuration

After proxy settings have been configured, you can look them up using the utility function `getProxyConfigs` from the PWA Kit React SDK. For example, you can use a different client ID, depending on the environment that your code is running in:

```javascript
import {getProxyConfigs} from 'pwa-kit-react-sdk/ssr/universal/utils.js'

const HOST_TO_CLIENT_ID = {
  'api-staging.example.com': 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
  default: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
}

const CLIENT_ID = (function getClientId() {
  const {host} = getProxyConfigs().find((c) => c.path === 'api')
  return HOST_TO_CLIENT_ID[host] || HOST_TO_CLIENT_ID['default']
})()
```

## Request and Response Modifications

When a request is proxied, both the request to the origin and the response from the origin are both modified to make them work transparently with your application code.

**note:** The examples provided in this section assume that the app is hosted at `www.northerntrailoutfitters.com` and that it’s configured to proxy requests to `api.commercecloud.com.`

### Request Modifications

The following modifications are applied to the request before sending it to the host:

- Remove the `/mobify/proxy/<PROXY_PATH>/` prefix.
- Add an HTTP header of `X-Mobify: true`.

Proxied requests forward all query string parameters and headers, including cookies. This includes `x-sfdc-access-control` headers, which are forwarded to SCAPI origins. The `x-forwarded-for` header is preserved and not modified by the proxy.

The `User-Agent` header forwarded to your backend depends on the **Proxy User Agent** setting for the environment:

- **Browser** (default): The shopper's original User-Agent header is forwarded, including device and browser details. Use this if your backend personalizes responses or enforces policies based on the client device or browser.
- **Infrastructure**: The User-Agent is replaced with the Amazon CloudFront infrastructure value, hiding shopper device details from your backend.

You can set the default Proxy User Agent for new environments in **Project Settings**, or override it per environment in **Environment Settings > Advanced**. See [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md) for steps.

### Response Modifications

The following modifications are applied to the response before sending it to the client:

- Add an HTTP header of `X-Request-Url: <URL>` with the URL that was requested.
- If the response is a redirect and the response’s `Location` header whose `host` matches the proxy’s `host`, then `host` is prefixed with `/mobify/proxy/<PROXY_PATH>/`.
- If the response contains `Set-Cookie` headers whose `domain` matches the `host` of the proxy, they’re updated to match it. For example, `Set-Cookie: key=val; domain=api.commercecloud.com` is updated to `Set-Cookie: key=val; domain=www.northerntrailoutfitters.com`.
- If the response contains an `Access-Control-Allow-Origin` header whose value matches the proxy’s `host`, it’s updated to `Access-Control-Allow-Origin: https://www.northerntrailoutfitters.com`.

To test your modifications, configure a proxy configuration with [httpbin.org](http://httpbin.org/) as the host. When you make a request to through that proxy, it echoes back any headers that it receives.

## Improve Proxy Performance with Caching

By default, proxied requests are uncached by the CDN. This default allows proxies requests to be used transparently in your code, without having to worry about incorrectly caching responses.

When you _do_ want a proxied request to be cached by the CDN, change the path prefix used in your request from `proxy` to `caching`.

**note:** Caching proxies aren’t suitable for use with the B2C Commerce API. Instead use its [SCAPI Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) feature.

### Caching Details

Cached proxy requests differ from standard proxy requests in the following way:

- The `Cookie` HTTP header is removed.

Cached responses differ from standard responses in the following way:

- Any `Set-Cookie` HTTP headers are removed.

Cached responses include the following HTTP headers so that when the values of these headers vary, the responses are cached separately:

- `Accept`
- `Accept-Charset`
- `Accept-Encoding`
- `Accept-Language`
- `Authorization`
- `Range`

Responses that include other HTTP headers are _not_ cached separately when their values vary.

## Constraints

Proxies have different constraints than the [App Server](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#constraints).

- Proxy configurations must use HTTPS. HTTP proxy support is scheduled for retirement on **August 31, 2026**.
- The execution time for proxy requests is limited to 30 seconds. If a response from the origin doesn’t complete in this time, a [HTTP 504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) is returned.
- The origin must provide a valid certificate and support using [TLS 1.2](https://en.wikipedia.org/wiki/Transport_Layer_Security) or greater otherwise a [HTTP 502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) is returned. You can check whether your origins TLS support using [SSL Labs](https://www.ssllabs.com/ssltest/) tool.
- There is no limit to request or response sizes.
- Proxied requests can use the `Cookie` header. Proxied responses can include the `Set-Cookie` header.
- The proxied host must be publically addressable. If the proxied host is only accessible from within a private network or blocked like demandware.net hosts, then an HTTP error will be returned.
- The caching proxy only supports `HEAD`, `GET`, and `OPTIONS` methods. `POST` requests aren't supported.

## Next Steps

Now that you understand how and why to use proxies in your commerce app, keep exploring the [PWA Kit documentation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.md).

<!-- document id=6a6160b5502d694292a7d621b743f9a0571b2563a0bfd09c741b98e753e83390 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-public-lwr-library.md -->

# Public Commerce LWR Library

Accelerate the development process with ready-to-use Lightning web components that help you customize your Commerce storefronts.

The Public Commerce LWR Library in GitHub is an open repository of components that look and function like the product components available in Experience Builder. Clone and customize these public components to streamline your workflow and build outstanding Commerce storefronts.

The library is organized as an SFDX (Salesforce DX) project, and the components in this library are continually updated.

Contents include:

- Buttons, links, and windows with styling options
- Product Detail Page (PDP) items such as pricing displays, discount tiers, product variant selectors, and pricing quantity rules
- Add to Cart and item quantity selector controls
- Search results and filters

The PDP and search components in the reference library employ a versatile API to update data in component properties. These Builder-supported component APIs use expressions and data binding to achieve continuous data flows. The expressions and data bindings serve as input for `@api` properties in the reference LWCs.

**See Also**

- [Public Commerce LWR Library GitHub Repository](https://github.com/forcedotcom/commerce-on-lightning-components)

<!-- document id=12dee7c48dac060da3da11994e75671e09ab80053db9d4a1182010ea59a8b53c url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-public-client.md -->

# Public SLAS Client Use Cases

**note:** Setting up SLAS and making your first request is covered in the Get Started guides. See [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).

The following use cases show how SLAS enables authorized access to the Shopper APIs for public clients under different login scenarios.

Remember that any shopping app that is _not_ able to securely store a client secret for a registered user is a public client. Single-page apps, such as those built with [PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime), Android or iOS apps, and mobile apps without a gateway must be provisioned as public clients.

## Prerequisites

- A SLAS public client created in the SLAS Admin UI. See [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).
- Your short code, organization ID, and site ID. See [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md).
- The relevant scopes assigned to your SLAS client. See [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/auth-z-scope-catalog.md).

## Use Cases

Each use case demonstrates a different login scenario: guest user (no login), federated login, and B2C login.

Although all three use cases feature the Open Commerce API (OCAPI)’s `/baskets` endpoint, remember that a SLAS access token can be used with _any_ Shopper API endpoint.

Each step in the authentication flow is numbered and described in detail for all three use cases. The numbered steps are also illustrated with a diagram.

See the API specification for full details on how to make your API requests.

You can explore these use cases interactively with a Postman collection: [Salesforce Commerce B2C SLAS Use Cases](https://www.postman.com/salesforce-developers/salesforce-developers/folder/zjwouu1/slas).

## Guest User

This use case describes what happens when the shopper adds a product to their basket without logging in first. It follows the [authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1) flow as defined by the OAuth 2.1 standard. It also uses a [proof key for code exchange](https://tools.ietf.org/html/rfc7636) (PKCE), as defined by RFC 7636.

![SLAS public client authentication process for guest users](https://developer.salesforce.com/docs/media/commerce-api/slas-public-client-guest-user.png)

1. A shopper opens a B2C Commerce shopping app and starts interacting with it.
2. The shopping app generates two strings: `code_verifier` and `code_challenge`.

   - The `code_verifier` string is a random string.
   - The `code_challenge` is a base64 encoded version of the `code_verifier` string using an SHA-256 hash.

3. The shopping app makes a request to the `/authorize` endpoint of the SLAS API.

   - Required query parameters: `hint=guest`, `response_type=code`, `client_id`, `code_challenge`, and `redirect_uri`.
   - The `redirect_uri` parameter specifies what app route to redirect to when the login is complete.
   - Optional query parameter: `usid`. If you already have a Unique Shopper Identifier (USID) for the guest user, pass it in. Otherwise, a USID is generated for you by SLAS.
   - Best practice: reuse the USID for a shopper from the previous guest login so that you can tie that user to all the previous login attempts and enable personalization.

4. The endpoint responds with an authorization code and redirects to the shopping app via the `redirect_uri`. If necessary, the USID is returned through a query parameter.
5. The shopping app makes a request to the `/token` endpoint of the SLAS API.

   - No authorization header is required.
   - Required query parameters: `grant_type=authorization_code_pkce`, `code_verifier`, `code,client_id`, and `redirect_uri`.
   - Recommended query parameter (**will be required in the future**): `channel_id`.

6. The endpoint responds with an access token in the form of a JSON Web Token (JWT), a `customer_id` string, a USID, and a refresh token.

   - The JWT also includes an `enc_user_id` string that can be used to call Einstein tracking APIs. For guest users, use a USID instead.

7. The shopping app makes a request to the `/getJwksUri` endpoint of the SLAS API to retrieve the keys for validating the JWT issued by the SLAS API.
8. The endpoint responds with a JSON Web Key Set (JWKS) containing the current, past, and future public keys.
9. The shopping app uses the key set to validate the Shopper JWT issued by the SLAS API.
10. The guest shopper adds a product to their basket.
11. The shopping app makes a request to the `/baskets` endpoint of OCAPI and provides a SLAS access token in the header.
12. The Baskets API saves a shopping basket with a `customer_id` string that is associated with the guest user.

## Registered User (Federated Login)

This use case describes what happens when a shopper logs in using a third-party identity provider before adding a product to their basket. It follows the [authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1) flow as defined by the OAuth 2.1 standard. It also uses a [proof key for code exchange](https://tools.ietf.org/html/rfc7636) (PKCE), as defined by RFC 7636.

![SLAS public client authentication for federated registered users](https://developer.salesforce.com/docs/media/commerce-api/slas-public-client-registered-user-federated.png)

1. A shopper logs in to a B2C Commerce shopping app and chooses a third-party identity provider (IDP) to perform the authentication.
2. The shopping app generates two strings: `code_verifier` and `code_challenge`.

   - The `code_verifier` string is a random string.
   - The `code_challenge` is a base64 encoded version of the `code_verifier` string using an SHA-256 hash.

3. The shopping app makes a request to the `/authorize` endpoint of the SLAS API.

   - Required query parameters: `hint`, `response_type=code`, `client_id`, `code_challenge`, and `redirect_uri`.
   - The `hint` parameter specifies the name of the identity provider.
   - The `redirect_uri` parameter specifies what app route to redirect to when the login is complete.

4. The SLAS API redirects to the identity provider’s login page.
5. The shopper enters their credentials and consents.
6. If login is successful, the SLAS API responds with an authorization code and redirects to the shopping app.
7. The shopping app makes a request to the `/token` endpoint of the SLAS API.

   - No authorization header is required.
   - Required query parameters: `grant_type=authorization_code_pkce`, `code_verifier`, `code`, `client_id`, and `redirect_uri`.

8. The endpoint responds with an access token in the form of a JSON Web Token (JWT), a `customer_id` string, a USID, and a refresh token.

   - The JWT also includes an `enc_user_id` string that can be used to call Einstein tracking APIs.

9. The shopping app makes a request to the `/getJwksUri` endpoint of the SLAS API to retrieve the keys for validating the JWT issued by the SLAS API.
10. The endpoint responds with a JSON Web Key Set (JWKS) containing the current, past, and future public keys.
11. The shopping app uses the key set to validate the Shopper JWT issued by the SLAS API.
12. The registered shopper adds a product to their basket.
13. The shopping app makes a request to the `/baskets` endpoint of OCAPI and provides a SLAS access token in the header.
14. The Baskets API saves a shopping basket with a `customer_id` string that is associated with the registered shopper.

## Registered User (B2C Login)

This use case describes what happens when a shopper logs in with credentials that are managed by a B2C Commerce instance before adding a product to their basket. It follows the [authorization code grant](https://tools.ietf.org/html/rfc6749#section-4.1) flow as defined by the OAuth 2.1 standard. It also uses a [proof key for code exchange](https://tools.ietf.org/html/rfc7636) (PKCE), as defined by RFC 7636.

![SLAS public client authentication for registered B2C Commerce users](https://developer.salesforce.com/docs/media/commerce-api/slas-public-client-registered-user-b2c.png)

1. A shopper logs in to a B2C Commerce shopping app and chooses to authenticate directly through the shopping app.
2. The shopping app generates two strings: `code_verifier` and `code_challenge`.

   - The `code_verifier` string is a random string.
   - The `code_challenge` is a base64 encoded version of the `code_verifier` string using an SHA-256 hash.

3. The shopping app makes a request to the `/login` endpoint of the SLAS API.

   - The request must include an authorization header that contains a [Base64](https://en.wikipedia.org/wiki/Base64) encoded version of the following string: `<shopperUserID>:<shopperPassword>`. (Don’t forget to replace `<shopperUserID>` and `<shopperPassword>` with actual values before encoding the string.)
   - Example header value: `Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`
   - Required query parameters: `code_challenge`, `usid`, `channel_id`, `client_id`, and `redirect_uri`.

4. The SLAS API redirects to the redirect URI and returns an authorization code.
5. The shopping app makes a request to the `/token` endpoint of the SLAS API.

   - No authorization header is required.
   - Required query parameters: `grant_type=authorization_code_pkce`, `code_verifier`, `code`, `client_id`, and `redirect_uri`.

6. The endpoint responds with an access token in the form of a JSON Web Token (JWT), a `customer_id` string, a USID, and a refresh token.

   - The JWT also includes an `enc_user_id` string that can be used to call Einstein tracking APIs.

7. The shopping app makes a request to the `/getJwksUri` endpoint of the SLAS API to retrieve the keys for validating the JWT issued by the SLAS API.
8. The endpoint responds with a JSON Web Key Set (JWKS) containing the current, past, and future public keys.
9. The shopping app uses the key set to validate the Shopper JWT issued by the SLAS API.
10. The registered shopper adds a product to their basket.
11. The shopping app makes a request to the `/baskets` endpoint of OCAPI and provides a SLAS access token in the header.
12. The Baskets API saves a shopping basket with a `customer_id` string that is associated with the registered shopper.

## User with External Profile

This use case describes what happens when a shopper logs in with an external profile that is managed by a third-party IDP.

![SLAS public client authentication with external profile integration](https://developer.salesforce.com/docs/media/commerce-api/slas-public-client-external-profile.png)

1. A shopper logs in to a B2C Commerce shopping app using credentials managed by a third-party IDP.
2. The shopping app makes a request to the `/authorize` endpoint.
3. The SLAS API redirects to the third-party IDP.
4. The third-party IDP makes a callback to the SLAS login API on successful login.
5. The SLAS service makes a request to the third-party IDP to get the IDP token and `shopper/user` info.
6. The SLAS service makes a request to the external profile endpoint to create a record with the shopper's third-party credentials on B2C Commerce.
7. After successful external profile creation on B2C Commerce, a corresponding user entry is persisted on SLAS.

## Next Steps

Now that you’re familiar with the use cases for public clients, check out the [Private SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-private-client.md).

When you’re ready to incorporate SLAS into your app, explore the [API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary) for the complete technical specifications for the SLAS endpoints.

<!-- document id=c53e05deedcec12b5d379319c0a9093944a68893ccb275c9b3a540a06ac2a81c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/submission-review.md -->

# Publish to the App Registry

This topic is for **ISVs** who want merchants to discover and install the app from Business Manager. Submit your Commerce App to the registry for review and publication.

SIs developing a merchant-specific private app should **not** open a registry PR. Install with WebDAV instead. See [Develop a Private Commerce App](/docs/commerce/b2c-commerce/guide/private-commerce-apps.md).

## Submission Process

Submit your validated CAP to the [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps).

1. Ensure `b2c cap validate` passes with no errors

2. Produce your final `.zip` via `b2c cap package`

3. Issue a Pull Request against the [Commerce App Registry](https://github.com/SalesforceCommerceCloud/commerce-apps) to submit the package along with required metadata (app name, version, description, supported platform versions, documentation)

4. The review team will evaluate your submission and collaborate with your team against your PR before approving.

## Review Process and States

After submission, your app moves through the following states:

**Draft:** Initial submission received, not yet in review.

**In Review:** The review team is evaluating your app.

**Feedback:** Issues found; you need to address review comments and resubmit.

**Approved:** Your app is approved and published to the registry.

**Published:** Available for merchant installation.

<!-- document id=09a1c80143c7eb107bcdb7478231e6c2b81d9d342e7e7f5fab5f3b4467e94496 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/compatibility-matrix.md -->

# PWA Compatibility Matrix

With the release of Progressive Web App (PWA) Kit version 3.0, we introduced two new independently versioned packages to the platform, [retail-react-app](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/template-retail-react-app) and [commerce-sdk-react](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/commerce-sdk-react).

In addition, depending on your project's build, your storefront may have additional dependencies on the [commerce-sdk-isomorphic](https://github.com/SalesforceCommerceCloud/commerce-sdk-isomorphic) package or the [plugin_slas](https://github.com/SalesforceCommerceCloud/plugin_slas) Storefront Reference Architecture (SFRA) cartridge.

Check this table to make sure you're using compatible versions of PWA Kit, `retail-react-app`, `commerce-sdk-react`, `commerce-sdk-isomorphic`, and `plugin_slas`.

|     **PWA Kit**     | **retail-react-app** | **commerce-sdk-react** | **commerce-sdk-isomorphic** | **plugin_slas** | Notable Changes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| :-----------------: | :------------------: | :--------------------: | :-------------------------: | :-------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|     **v3.10.x**     |        v6.1.x        |     v3.3 or later      |        v3.3 or later        |      v7.4       | **Retail react app**<br/><ul><li>Source maps support for both client and server on Managed Runtime. See [Debug Using Source Maps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.md#debug-using-source-maps).</li><li>Data Cloud integration with PWA Kit events.</li><li>Page meta data tags from Business Manager now supported on Product Detail Pages (PDP) and Product List Pages (PLP).</li><li>Improved password management with Confirm New Password field in Reset & Change Password flows.</li><li>Enhanced performance logging for server-timing headers.</li><li>Fixed `hreflang` alternate links and accessibility issues.</li></ul>**Commerce-sdk-react**<ul><li>Fixed guest login token handling with hybrid authentication.</li><li>Improved cache management during logout.</li><li>Added support for custom parameters in SLAS authorization calls.</li>See [v3.10.0 (retail-react-app@6.1.0 and commerce-sdk-react@3.3.0)](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/v3.10.0) on GitHub. |
|     **v3.9.x**      |         v6.x         |     v3.2 or later      |        v3.2 or later        |      v7.4       | **Retail react app**<br/><ul><li>Passwordless and social login support.</li><li>Password reset support.</li><li>Do not track support.</ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
|     **v3.8.x**      |         v5.x         |     v3.1 or later      |        v3.1 or later        |      v7.4       | **Retail react app**<ul><li>Shopper context integration</li><li>Active data tracking set to `true` by default.</li></ul><br/>**Commerce-sdk-react**<br/><ul><li>Attach dwsid to SCAPI requests</li><li>Remove OCAPI session bridging.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
|     **v3.7.x**      |         v4.x         |          v3.x          |            v3.x             |      v7.3       | **Commerce-sdk-react**<ul><li>SLAS now requires `channel_id`.</li><li>Shopper context now requires `siteId`.</li><li>Upgrade to commerce-sdk-isomorphic v3.x</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|     **v3.6.x**      |         v3.x         |          v2.x          |            v2.x             |      v7.3       | **Retail react app**<br/><ul><li>Product tile rework.</li></ul><br/>**Commerce-sdk-react**<ul><li>Upgrade to commerce-sdk-isomorphic v2.x</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
|     **v3.5.x**      |         v2.x         |     v1.4.0 < v2.x      |            v1.10            |      v7.3       | **Commerce-sdk-react**<ul><li>SLAS private client support.</li><li>Reworks how sessions are transferred between SFRA and PWA so OCAPI /sessions call is not required on the PWA</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **v3.1.1 - v3.4.x** |         v2.x         |    v1.0.2 < v1.4.0     |            v1.10            |   v7.0 - v7.2   | **Retail react app**<ul><li>Page designer types migrated to commerce-sdk-react</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **v3.0.0 - v3.1.0** |         v1.x         |    v1.0.0 - v1.0.1     |            v1.10            |   v7.0 - v7.2   | Initial release of PWA Kit 3.x                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |

For more information about the features available in various versions of PWA Kit and retail-react-app, see the [Composable Storefront Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html).

**note:** Projects on PWA Kit v2 are not compatible with retail-react-app.

Projects on PWA Kit v2 may consume commerce-sdk-react as a customization. See the [Upgrade to v3 guide](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.md#optional-consume-the-commerce-sdk-react-hooks-library) for more information

<!-- document id=8ca3fd3d4ff4138099131512093fa62fa045715256f71aa10f041e9dfd62a980 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/perf-pwa-arch.md -->

# PWA Kit Architecture: How Your PWA Kit App Delivers a Page

Ever wonder how your site goes from "loading..." to "wow!" in a flash? It's all thanks to some clever tech working behind the scenes. Check out this overview of the PWA Kit architecture and how a page renders on the server and the client.

## Your Site's Grand Entrance: Server-Side Rendering (SSR)

With server-side rendering, users immediately see meaningful content instead of a blank screen and a large JavaScript file the page has to figure out. Your Largest Contentful Paint ([LCP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals)) receives a significant boost. Imagine unwrapping a perfectly assembled gift instead of a box of LEGOs. That's what Server-Side Rendering (SSR) does for your site's first impression!

**note:** This section mentions performance metrics that are part of Web Core Vitals. To learn more about these metrics, see [What Are Core Web Vitals?](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals).

Here's the quick rundown.

1. A user requests a page.
2. The request is sent to Salesforce Managed Runtime (MRT).
3. On that app server, your React components transform into a complete, ready-to-view HTML page, grabbing all the necessary data from the B2C Commerce APIs.
4. The assembled page then goes straight to the user's browser!

![The flow of a page request to the assembled page](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-perf-flow.png '{"class": "image-xl"}')

The Managed Runtime boosts page loading times. It includes an integrated Content Delivery Network (CDN) capable of caching the server-generated pages. If another user requests an identical page, the CDN can deliver the cached version instantaneously, completely bypassing the server. A cached HTML response represents the swiftest possible delivery, contributing to outstanding LCP and Time to First Byte (TTFB) scores!

## The Interactive Action: Hydration and Client-Side Power

Once the initial visual appears, hydration begins. Your site's client-side code loads and executes, transforming the static display into a vibrant, responsive experience by attaching all the event listeners and managing its internal state. From this point forward, your digital storefront operates as a Single-Page Application (SPA). All subsequent navigation and user interface changes are handled by client-side rendering (CSR). When a visitor selects a link, JavaScript takes command, retrieves fresh data, and updates only the necessary portions of the page, all without a complete page reload.

CSR delivers a seamless, application-like feel, yet it's also where you frequently encounter performance bottlenecks that negatively affect your Interaction to Next Paint ([INP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals)) score.

## Dual Approach for Backend and Frontend Performance

It's entirely possible to achieve an excellent [LCP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals) score on the server and still provide a poor user experience due to high [INP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals) and [TBT](https://web.dev/articles/tbt) on the client due to cumbersome client-side programming. PWA Kit projects are powerful React apps, and they can become JavaScript-intensive if not managed carefully. Even foundational libraries can add to the complexity of this endeavor. Therefore, you must balance performance on both sides to achieve a highly performant site.

- Optimize [LCP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals) performance on the server through efficient content generation and aggressive data caching.
- Optimize [INP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals) and [TBT](https://web.dev/articles/tbt) performance on the client to deal with large and inefficient JavaScript code.

## The Usual Suspects: Common PWA Kit Slowdowns

Every PWA Kit developer likely encounters these prevalent performance obstacles. Here's a list of the most frequent culprits.

![Frustrated user staring at a slow ecommerce site loading](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-perf-frustrated-user.png '{"class": "image-md"}')

- **Large JavaScript payloads:** The Retail React App template is a solid foundation, but if not carefully managed, your JavaScript bundles can swell significantly. Each new capability adds bulk, slowing down the time it takes for your page to become interactive and negatively impacting [INP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals).
- **Inefficient data retrieval:** Regardless of whether you're employing older data fetching methods or the contemporary `withReactQuery`, pitfalls can occur. Obtaining information one piece at a time instead of in parallel, requesting far more data than is required, or refetching data on the client device that the server has already provided are all typical ways to hamper both [TTFB](https://web.dev/articles/ttfb) and [LCP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals).
- **Unruly third-party scripts:** These pose a major challenge. Code snippets for analytics, advertising, A/B testing, and customer support chats can create performance issues. They often occupy the main processing thread, diminishing your [INP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals) scores, and can even interfere with your service worker's caching mechanisms.
- **Suboptimally constructed custom components:** A single custom React component that isn't performance-tuned can considerably affect your [INP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md#what-are-core-web-vitals). This generally happens through demanding computations on every render or by initiating a cascade of redundant rerenders in its subordinate elements.
- **Flawed caching implementations:** The Managed Runtime's CDN is potent, but it must be configured properly. Configure your cache control headers correctly, filter out unnecessary URL parameters, and set up your API proxies correctly. Incorrect configurations result in a poor cache hit rate and cancel all the benefits of swift server-side rendering. See [Maximize Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.md).

## See Also

- [Performance Best Practices for Writing PWA Kit-Based Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-tips.md)
- [Monitor the Performance of Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-monitor.md)

<!-- document id=19a138a028f3cbd3daebed7c3fdb14278c70b1f6e0ee80d3e153bf4a4c922bbf url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-framework.md -->

# PWA Kit Framework

**note:** **Applies to:** Composable Storefront (PWA Kit and Managed Runtime)


Ready to delve into the inner workings of Progressive Web App (PWA) Kit? This section provides a comprehensive breakdown of the architecture, explaining how the pieces work together to help you build a robust and performant site. This section contains the following guides.

- [Configuration Files](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configuration-options.md)
- [Proxy Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md)
- [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md)
- [Rendering](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/rendering.md)
- [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.md)
- [Special Components](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/special-components.md)
- [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managing-global-state.md)

### See Also

- [PWA Kit Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-kit-overview.md)
- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)

<!-- document id=00009d90e664e93ad77c9c4fa13ec16dcb2d9d7eba3fc3bc5a08276d8c1f7010 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-kit-overview.md -->

# PWA Kit Overview

This overview briefly introduces the main parts of the Progressive Web App (PWA) Kit architecture and provides you with helpful context for the rest of the product documentation.

## Retail React App

The Retail React App is a server-side rendered React app that’s optimized for ecommerce. It gives you a starting point for building your storefront that already includes key features, such as:

- Code bundling, code splitting, and transpilation
- Component library with theming
- JavaScript-based styling system (CSS in JS)
- Scripts for automating routine development tasks
- Service worker and manifest for Progressive Web App (PWA) features
- Test suites

The Retail React App’s storefront includes standard ecommerce pages and functionality, such as product listing page (PLP), product details page (PDP), cart, and checkout. Every aspect of the storefront is designed to be enhanced and extended with your own code.

_To learn more, check out a demo of the Retail React App at [pwa-kit.mobify-storefront.com](https://pwa-kit.mobify-storefront.com/) or read the full architecture guide → [The Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md)._

## Browser Compatibility

A site created with PWA Kit is compatible with the following web browsers:

### Mobile Phones and Tablets

| Operating System | Browsers                                                                                                |
| :--------------- | :------------------------------------------------------------------------------------------------------ |
| Android          | <ul><li>Last two major versions of Chrome</li><li>Last two major versions of Samsung Internet</li></ul> |
| iOS              | <ul><li>Last two major versions of Chrome</li><li>Last two major versions of Safari</li></ul>           |

### Desktops and Laptops

| Operating System | Browsers                                                                                                                               |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------- |
| macOS            | <ul><li>Last two major versions of Safari</li><li>Last two major versions of Firefox</li></ul>                                         |
| Windows          | <ul><li>Last two major versions of Chrome</li><li>Last two major versions of Edge</li><li>Last two major versions of Firefox</li></ul> |

## Rendering and Routing

For the best possible shopper experience, PWA Kit storefronts use a system for rendering and routing that runs the same source code in two different contexts: on the server side and on the client side. Server-side rendering optimizes for initial page loading speed, while client-side rendering enables a responsive user interface and smooth page transitions.

The rendering and routing system is established by the Retail React App with its [Express](https://expressjs.com/) server configuration and a hierarchy of React components. Within this system, you can:

- Add new page components and modify existing page components
- Supply data to page components from API requests or from user interaction
- Define patterns for routing URL requests to page components
- Customize the output of all pages

_To learn more, read the full architecture guides → [Rendering](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/rendering.md) and [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.md)._

## Analytics

See [Data and Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/data-and-analytics.md).

## GitHub Repository

The PWA Kit is an open-source project hosted on GitHub.

The [GitHub repository](https://github.com/SalesforceCommerceCloud/pwa-kit/) for PWA Kit is set up as a monorepo with several packages, including libraries, project templates, SDKs, and other tools.

To help you navigate the repository, here is an overview of each package that it contains:

| Package                                                                                                                             | Description                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [pwa-kit-create-app](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/pwa-kit-create-app)                   | Creates PWA Kit projects based on project templates.               |
| [pwa-kit-dev](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/pwa-kit-dev)                                 | Command-line tools to develop, build, and deploy PWA Kit projects. |
| [pwa-kit-runtime](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/pwa-kit-runtime)                         | Enables Node.js applications to run on Managed Runtime.            |
| [pwa-kit-react-sdk](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/pwa-kit-react-sdk)                     | Utilities that support the rendering pipeline.                     |
| [commerce-sdk-react](https://salesforcecommercecloud.github.io/pwa-kit/)                                                            | React hooks for interacting with the Salesforce B2C Commerce API   |
| [template-retail-react-app](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/template-retail-react-app)     | Default template for starting projects.                            |
| [template-typescript-minimal](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/template-typescript-minimal) | Zero-configuration project template for TypeScript applications.   |
| [template-express-minimal](https://github.com/SalesforceCommerceCloud/pwa-kit/tree/develop/packages/template-express-minimal)       | Bare-bones project template for apps running on Managed Runtime.   |

## Support Policy

Security patches are provided for a minimum of 24 months after the general availability of each major version of the PWA Kit SDKs (1.0, 2.0, and so on).

## Nightly Builds

PWA Kit releases nightly builds on a nightly cadence for better visibility about upcoming features and a chance for implementers to test code integrations.

Nightly releases of PWA Kit packages are released to npm using the distribution tag `nightly-next`. The latest `nightly-next` tag can be [viewed on npm](https://www.npmjs.com/package/@salesforce/commerce-sdk-react?activeTab=versions).

These packages can be installed by running:

`npm install <package-name>@nightly-next`

As an example, to install the latest nightly build for `@salesforce/commerce-sdk-react` to your PWA Kit project, run:

`npm install @salesforce/commerce-sdk-react@nightly-next`

**warning:** Do not use preview versions in production.

_These builds are untested and unsupported. Some features included in the nightly builds may not be included in final PWA Kit releases._ These unreleased builds may not even load, may have undocumented features, known defects, and any number of other issues. They are intended for use by developers and others wishing to get early access to planned PWA Kit features.
</code>

## See Also

- [Composable Storefront Release Notes](/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html)
- [Video: Use the PWA Kit to Create a New Project | Configure PWA Kit](https://www.youtube.com/watch?v=SsTBreklZ6s)
- [Video: Configure a Composable Storefront with the PWA Kit | Configure PWA Kit](https://www.youtube.com/watch?v=IUtMy_tfp38)

<!-- document id=a3d64743f93b0debb6db0cabccda772ef5455db753a7754ee282f10c5dcb5fa5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/queries.md -->

# Queries

You can use queries to be selective about data returned by OCAPI, which reduces network bandwidth.

## query

A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

- [`match_all_query`](#match_all_query) - returns all records.
- [`term_query`](#term_query) - matches records where a field (or fields) exactly match some simple value (including null).
- [`text_query`](#text_query) - matches records where a field (or fields) contain a search phrase.
- [`boolean_query`](#boolean_query) - formulates a complex boolean expression using query objects as criteria.
- [`filtered_query`](#filtered_query) - allows for filtering of records based on both a query and a filter.

Queries can also contain [nested queries](#nested_query).

### match_all_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

```
"query":{
   "match_all_query":{}
}

```

### term_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The less and greater operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a [range filter](https://sfcclearning.com/infocenter/OCAPI/current/data/Documents/RangeFilter.php) on a [filtered query](https://sfcclearning.com/infocenter/OCAPI/current/data/Documents/FilteredQuery.php).

**Elastic only**: If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my_id")

```
"query":{
   "term_query":{
      "fields":["id"],
      "operator":"is",
      "values":["my_id"]
   }
}
```

**Example:** (id IN ("my_id","other_id"))

```
"query":{
   "term_query":{
      "fields":["id"],
      "operator":"one_of",
      "values":[
         "my_id",
         "other_id"
      ]
   }
}
```

**Example:** (id=null)

```
"query":{
   "term_query":{
      "fields":[
         "description"
      ],
      "operator":"is_null"
   }
}
```

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

```
"query":{
   "term_query":{
      "fields":[
         "id",
         "description"
      ],
      "operator":"one_of",
      "values":[
         "generic",
         "keyword"
      ]
   }
}
```

| Property | Type                                                                | Constraints                                | Description                                                                          |
| :------- | :------------------------------------------------------------------ | :----------------------------------------- | :----------------------------------------------------------------------------------- |
| fields   | [String]                                                            | mandatory=true, minItems=1, nullable=false | The document field(s), the value(s) are matched against, combined with the operator. |
| operator | Enum {is, one_of, is_null, is_not_null, less, greater, not_in, neq} | mandatory=true, nullable=false             | Returns the operator to use for the term query.                                      |
| values   | [Object]                                                            |                                            | The values, the field(s) are compared against, combined with the operator.           |

### text_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

**Example:** (coupon_id contains "xmas" )

```
"query":{
   "text_query":{
      "fields":[
         "coupon_id"
      ],
      "search_phrase":"xmas"
   }
}
```

**Example:** (coupon_id contains "xmas" OR description contains "xmas")

```
"query":{
   "text_query":{
      "fields":[
         "description",
         "coupon_id"
      ],
      "search_phrase":"xmas"
   }
}
```

**Example:** (description contains "holiday" AND description contains "bojo")

```
"query":{
   "text_query":{
      "fields":[
         "description"
      ],
      "search_phrase":"holiday bogo"
   }
}
```

| Property      | Type     | Constraints                                | Description                                                 |
| :------------ | :------- | :----------------------------------------- | :---------------------------------------------------------- |
| fields        | [String] | mandatory=true, minItems=1, nullable=false | The document fields the search phrase has to match against. |
| search_phrase | String   | mandatory=true, nullable=false             | A search phrase, which may consist of multiple terms.       |

### boolean_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. **Example:** (id = 'foo' AND description LIKE 'bar')

```
"query":{
   "bool_query":{
      "must":[
         {
            "term_query":{
               "fields":[
                  "id"
               ],
               "operator":"is",
               "values":[
                  "foo"
               ]
            }
         },
         {
            "text_query":{
               "fields":[
                  "description"
               ],
               "search_phrase":"bar"
            }
         }
      ]
   }
}
```

**Example:** (id = 'foo' OR description LIKE 'bar')

```
"query":{
   "bool_query":{
      "should":[
         {
            "term_query":{
               "fields":[
                  "id"
               ],
               "operator":"is",
               "values":[
                  "foo"
               ]
            }
         },
         {
            "text_query":{
               "fields":[
                  "description"
               ],
               "search_phrase":"bar"
            }
         }
      ]
   }
}
```

**Example:** (NOT (id = 'foo' OR description LIKE 'bar'))

```
"query":{
   "bool_query":{
      "must_not":[
         {
            "term_query":{
               "fields":[
                  "id"
               ],
               "operator":"is",
               "values":[
                  "foo"
               ]
            }
         },
         {
            "text_query":{
               "fields":[
                  "description"
               ],
               "search_phrase":"bar"
            }
         }
      ]
   }
}
```

**Example:** ((coupon_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

```
"query":{
   "bool_query":{
      "must":[
         {
            "text_query":{
               "fields":[
                  "coupon_id"
               ],
               "search_phrase":"limit"
            }
         },
         {
            "text_query":{
               "fields":[
                  "description"
               ],
               "search_phrase":"limit per customer"
            }
         }
      ],
      "must_not":[
         {
            "term_query":{
               "fields":[
                  "enabled"
               ],
               "operator":"is",
               "values":[
                  false
               ]
            }
         }
      ]
   }
}
```

| Property | Type                                                                                           | Constraints | Description                          |
| :------- | :--------------------------------------------------------------------------------------------- | :---------- | :----------------------------------- |
| must     | [query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}] |             | List of queries that must match.     |
| must_not | [query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}] |             | List of queries that must not match. |
| should   | [query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}] |             | List of queries that should match.   |

Queries can be nested.

### filtered_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter. **Example:**

```
"query":{
   "filtered_query":{
      "query":{
         "text_query":{
            "fields":[
               "coupon_id"
            ],
            "search_phrase":"disabled"
         }
      },
      "filter":{
         "term_filter":{
            "field":"enabled",
            "operator":"is",
            "values":[
               false
            ]
         }
      }
   }
}
```

| Property | Type                                                                                           | Constraints                    | Description                           |
| :------- | :--------------------------------------------------------------------------------------------- | :----------------------------- | :------------------------------------ |
| filter   | Filter {BoolFilter, QueryFilter, Range2Filter, RangeFilter, TermFilter}                        | mandatory=true, nullable=false | The (possibly complex) filter object. |
| query    | [query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}] | mandatory=true, nullable=false | The query object.                     |

### nested_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types.

**Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

```
{
  "query": {
    "bool_query": {
      "must": [
        {
          "nested_query": {
            "path": "order.shipping_addresses",
            "query": {
              "bool_query": {
                "must": [
                  {
                    "bool_query": {
                      "must": [
                        {
                          "term_query": {
                            "fields": [
                              "order.shipping_addresses.first_name"
                            ],
                            "operator": "is",
                            "values": [
                              "John"
                            ]
                          }
                        }
                      ]
                    }
                  },
                  {
                    "bool_query": {
                      "must": [
                        {
                          "term_query": {
                            "fields": [
                              "order.shipping_addresses.last_name"
                            ],
                            "operator": "is",
                            "values": [
                              "Doe"
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            },
            "score_mode": "avg"
          }
        }
      ]
    }
  }
}
```

| Property   | Type                                                                                           | Constraints                    |
| :--------- | :--------------------------------------------------------------------------------------------- | :----------------------------- |
| path       | [String]                                                                                       |                                |
| query      | [query {boolean_query, match_all_query, filtered_query, nested_query, term_query, text_query}] | mandatory=true, nullable=false |
| score_mode | Enum {avg, total, max, none}                                                                   |                                |

<!-- document id=a19fff8d67abc01508bd09f89b811069e0037ff685f651a9d458bb71f6f3819b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-import-tokens-query-using-apex.md -->

# Query Saved Payment Method Records Using Apex

You can query Saved Payment Method records in your Salesforce org using Apex. This option is applicable only to third-party payment gateways.

Here's an example of an Apex query to retrieve SPM records.

```apex
SavedPaymentMethod savedPaymentMethod = fetchSavedPaymentMethod(idToProcess);
token = savedPaymentMethod.GatewayToken;
shopperReference = savedPaymentMethod.GatewayReference;
String paymentMethodType = savedPaymentMethod.type;
String extendedPaymentMethodType = savedPaymentMethod.ExtendedPaymentMethodType;
System.debug('Queried SPM record for QA override');
type = determinePaymentType(paymentMethodType, extendedPaymentMethodType, paymentTypeMap);
private static SavedPaymentMethod fetchSavedPaymentMethod(Id idToProcess) {
    QueryUtils q = new QueryUtils(SavedPaymentMethod.SObjectType);
    q.getSelectClause().addField('GatewayToken', false);
    q.getSelectClause().addField('GatewayReference', false);
    q.getSelectClause().addField('ExtendedPaymentMethodType', false);
    q.getSelectClause().addField('type', false);
    q.setWhereClause(' WHERE Id = \'' + idToProcess + '\'');
    return (SavedPaymentMethod) Database.query(q.buildSOQL())[0];
}
```

Here’s a sample Apex snippet that demonstrates how to make gateway calls using the queried SPM records.

```apex
public commercepayments.GatewayResponse createSaleResponse(commercepayments.SaleRequest saleRequest) {
    // API: https://stripe.com/docs/api/payment_intents
    String token;
    String paymentMethodType;
    Map < String, String > params = new Map < String, String > ();
    Id idToProccess = saleRequest.paymentMethod.id;
    // payment method is card if payment method data is not present or paymentMethodType is card
    if (saleRequest.paymentMethodData == null) {
        // resolved card token,
        //Before v65.0 for card details, you need to query DB for respective card payment method record or if you are sending CPM id in saleRequest
        system.debug('Payment method data is null');
        String paymentMethodId = saleRequest.paymentMethod.id;
        if (idToProccess.getSObjectType() == CardPaymentMethod.SObjectType) {
            token = resolveCardToken(paymentMethodId);
        } else if (idToProccess.getSObjectType() == SavedPaymentMethod.SObjectType) {
            token = resolveSPMToken(paymentMethodId);
        }
        params.put('payment_method', urlEncode(token));
        params.put('payment_method_types[]', 'card');
    } else {
        //NOTE: From v65.0 onwards, paymentMethodData would have all the details like token, type etc required fields for all payment methods(card, bank payment methods).
        //paymentMethodData would have data in case of ACH
        system.debug('Payment method data is not null');
        if (saleRequest.amount == 999999 && idToProccess.getSObjectType() == SavedPaymentMethod.SObjectType) {
            // NOTE: This is only for QA purposes. In an ideal scenario, querying the database record should be avoided unless absolutely necessary.
            String paymentMethodId = saleRequest.paymentMethod.id;
            token = resolveSPMToken(paymentMethodId);
            system.debug('SPM query done when paymentMethodData was available');
        } else {
            token = saleRequest.paymentMethodData.get('gatewayToken');
        }
        System.debug('Value of gatewayToken ' + ': ' + token);
        params.put('payment_method', token);
        paymentMethodType = determinePaymentMethodTypeForSaleFlow(saleRequest);
        params.put('payment_method_types[]', paymentMethodType);
        // populate mandate data
        populateMandateData(params, saleRequest.ipAddress);
    }
    // set customer id in params if it is available
    if (saleRequest.paymentMethodData != null) {
        String gatewayCustomerReference = saleRequest.paymentMethodData.get('gatewayReference');
        if (gatewayCustomerReference != null) {
            params.put('customer', gatewayCustomerReference);
        }
        // Set paymentMethodSubType to be used for Card for Link, Gpay, ApplePay
        String paymentMethodSubType = saleRequest.paymentMethodData.get('paymentMethodSubType');
        if (paymentMethodSubType != null && paymentMethodSubType.equals('link')) {
            String existing = params.get('payment_method_types[]');
            if (existing != null) {
                params.put('payment_method_types[]', existing + '&payment_method_types[]=link');
            } else {
                params.put('payment_method_types[]', 'link');
            }
        }
    }
    String idempotencyKey = saleRequest.idempotencyKey;
    Map < String, String > headers = new Map < String, String > ();
    if (idempotencyKey != null) {
        headers.put('Idempotency-Key', idempotencyKey);
    }
    String currencyIsoCode = saleRequest.currencyIsoCode;
    String amount = toStripeCurrencyUnits(currencyIsoCode, saleRequest.amount);
    params.put('amount', amount);
    params.put('currency', currencyIsoCode);
    params.put('confirm', 'true'); // create & authorize
    params.put('capture_method', 'automatic'); // Set capture method to automatic
    if (paymentMethodType == 'affirm') { // Adding support extended_apm . Affirm supported only for online session
        params.put('return_url', 'https://example.com/success');
    } else {
        params.put('off_session', 'true');
    }
    HttpResponse response = doPost('payment_intents?expand[]=latest_charge', params, headers);
    String body = response.getBody();
    Map < String, Object > intent = (Map < String, Object > ) JSON.deserializeUntyped(body);
    commercepayments.SaleResponse saleResponse = new commercepayments.SaleResponse();
    saleResponse.setGatewayDate(system.now());
    Integer sc = response.getStatusCode();
    if (sc >= 200 && sc < 300) {
        String status = (String) intent.get('status');
        saleResponse.setGatewayResultCode(status);
        saleResponse.setGatewayResultCodeDescription(status);
        saleResponse.setGatewayReferenceNumber((String) intent.get('id'));
        saleResponse.setSalesforceResultCodeInfo(RC_SUCCESS);
        saleResponse.setAmount(fromStripeCurrencyUnits(currencyIsoCode, (Long) intent.get('amount')));
        if (status.equals('processing')) {
            saleResponse.setAsync(true);
        }
    } else {
        // Handle errors
        Map < String, Object > error = (Map < String, Object > ) intent.get('error');
        String errorCode = (String) error.get('code');
        String errorType = (String) error.get('type');
        if (errorType.equals('card_error') && DECLINE_CODES.contains(errorCode)) {
            populateErrorResponse(saleResponse, errorCode, error);
            commercepayments.RetryCategory retryCategory = ERROR_CODES_RETRY_CATEGORY_MAP.get(errorCode);
            saleResponse.setRetryCategory(retryCategory);
            if (RETRIABLE_CODES.contains(errorCode)) {
                saleResponse.setRetryDecision(commercepayments.RetryDecision.Retriable);
            } else if (NON_RETRIABLE_CODES.contains(errorCode)) {
                saleResponse.setRetryDecision(commercepayments.RetryDecision.NonRetriable);
            }
        } else {
            return new commercepayments.GatewayErrorResponse(String.valueOf(sc), 'ERROR: ' + body);
        }


    }


    return saleResponse;
}
private String determinePaymentMethodTypeForSaleFlow(commercepayments.SaleRequest saleRequest) {
    String paymentMethodType = saleRequest.paymentMethodData.get('paymentMethodType');


    // Adding support for extended payment method types
    if ((paymentMethodType.equals('extd_wallet') || paymentMethodType.equals('extd_apm_type')) && saleRequest.paymentMethodData.get('extendedPaymentMethodType') != null) {
        paymentMethodType = saleRequest.paymentMethodData.get('extendedPaymentMethodType');
    }
    return paymentMethodType;
}
```

**See Also**

- [_Apex Reference Guide_: CommercePayments Namespace](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_namespace_commercepayments.htm)
- [_Apex Developer Guide_: Getting Started with Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_intro_get_started.htm)

<!-- document id=191ea6a663618c7b480afece3a3bd91db15880d5b82dba05e71f2cbbae1649a6 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/quick-start.md -->

# Quick Start

This guide features streamlined instructions for experienced [Node.js](https://nodejs.org/) developers who want to get started with PWA Kit immediately using a demo storefront and a demo sandbox for the back end.

## Prerequisites

- Node.js 22+ and npm 10+.
- Apple silicon users: If you haven’t installed Rosetta already, run `softwareupdate --install-rosetta`.

For detailed setup instructions, see [Set Up Your Local Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-your-local-environment.md).

## Generate the Project

To create a project using the [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md) template and connect the project to the demo sandbox, open a terminal and run the following command:

```bash
npx '@salesforce/pwa-kit-create-app@latest' --preset retail-react-app-demo
```

This creates a directory called `retail-react-app-demo`. Open this folder in your text editor and start exploring!

## Start Your Web Server

To start your local web server run the following commands:

```bash
cd retail-react-app-demo
npm start
```

Now that the development server is running, you can open a browser and preview your storefront:

- Go to [http://localhost:3000/](http://localhost:3000/)

Changes made to your project files will be visible in your browser when you refresh.

After you’ve completed the tasks in this guide, [Deploy Your Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.md).

<!-- document id=8e5f22afe288619eb7cb973099b7dca52159f29c3e39b383ec0fb9cadd93c2db url=/developer/current/en-us/commerce-cloud/commerce-api/guides/api-and-sdk-demo.md -->

# Quick Start\: B2C Commerce API and SDK

Make your first request to the B2C Commerce API using the Salesforce Commerce SDK.

For working with on-demand sandboxes, see [Develop With an On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-develop-with-on-demand-sandbox.html).

Our demonstration uses the Shopper Search API to search for dresses in the catalog of an example storefront.

## Create a Test Project

Start by creating a test project and installing the SDK as a package dependency.

Open a terminal and run the following commands:

```bash
mkdir test-commerce-sdk
cd test-commerce-sdk
npm init -y
npm install commerce-sdk
```

## Demo Code

Create a file called `get-dresses.js` and open it in a text editor.

Copy the following demo code, and paste it in the file.

```javascript
const { ShopperSearch, ShopperLogin, slasHelpers } = require("commerce-sdk");

const SLAS_CLIENT_ID = "da422690-7800-41d1-8ee4-3ce983961078";
// WARNING: Secret is provided here for convenience only. Do not include secrets in your code!
const SLAS_CLIENT_SECRET = "D*HHUrgO2%qADp2JTIUi";
// const SLAS_CLIENT_SECRET = process.env.SLAS_CLIENT_SECRET
const ORG_ID = "f_ecom_zzte_053";
const SHORT_CODE = "kv7kzm78";
const SITE_ID = "RefArch";

// Client configuration parameters
const clientConfig = {
  headers: {},
  parameters: {
    clientId: SLAS_CLIENT_ID,
    organizationId: ORG_ID,
    shortCode: SHORT_CODE,
    siteId: SITE_ID,
  },
};

/**
 * Get the shopper or guest JWT/access token, along with a refresh token, using client credentials
 * using the Shopper Login API directly. See below for an example of using the slasHelpers utility function instead.
 * @returns guest user authorization token
 */
async function getGuestUserAuthToken() {
  const credentials = `${SLAS_CLIENT_ID}:${SLAS_CLIENT_SECRET}`;
  const base64data = Buffer.from(credentials).toString("base64");
  const headers = { Authorization: `Basic ${base64data}` };
  const client = new ShopperLogin(clientConfig);

  return await client.getAccessToken({
    headers,
    body: {
      grant_type: "client_credentials",
      channel_id: SITE_ID,
    },
  });
}

// Get a JWT to use with Shopper API clients
async function run() {
  let tokenData;
  try {
    tokenData = await getGuestUserAuthToken();

    // Or use the slasHelpers utility function:
    
    // const client = new ShopperLogin(clientConfig);
    // tokenData = await slasHelpers.loginGuestUserPrivate({
    //   slasClient: client,
    //   credentials: {
    //     clientSecret: SLAS_CLIENT_SECRET,
    //   }
    // })
  } catch (e) {
    console.error(e);
    console.error(await e.response.text());
    return;
  }

  // Add the token to the client configuration
  clientConfig.headers["authorization"] = `Bearer ${tokenData.access_token}`;

  // Search for dresses
  const searchClient = new ShopperSearch(clientConfig);
  const limit = 3;
  const searchResults = await searchClient.productSearch({
    parameters: { q: "dress", limit: limit },
  });

  if (searchResults.total) {
    for (i = 0; i < limit; i++) {
      const result = searchResults.hits[i];
      console.log(`💃 ${result.productId} ${result.productName}`);
    }
  } else {
    console.log("No results for search");
  }
}

run();
```

## Run Your Example

Go back to the terminal and run the demo code:

```bash
node get-dresses.js
```

The output of `get-dresses.js` looks like this:

```bash
💃 25592581M Floral Dress
💃 25593727M V-Neck Dress
💃 25589753M Pack-And-Go Dress
```

For more sample code, see the [examples directory](https://github.com/SalesforceCommerceCloud/commerce-sdk/tree/master/examples) in the Commerce SDK repository.

## Next Steps

In this demo, we’ve already taken care of the following setup tasks for you:

- Created a demo sandbox with demo data, including example products.
- Created a demo API client with both a client ID and client secret.
- Configured SLAS to work with the demo sandbox and demo API client.

To use the API and SDK with _your own_ B2C Commerce instances, you must complete these setup tasks for yourself. These tasks are covered in the following guides: [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md) and [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).

After you’ve completed the setup tasks, explore the SDK’s [README](https://github.com/SalesforceCommerceCloud/commerce-sdk) and the API specifications in the [API Reference](/docs/commerce/commerce-api/references/about-commerce-api/about.html).

<!-- document id=b62c686061f6d2294872e7913344c94bd8c697682b8553a4849f79948c364d38 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-quick-start-choice.md -->

# Quick Start: Create Storefront Next

Create a storefront through the Business Manager UI. The system automatically sets up your API and Managed Runtime resources.

Create a storefront in Business Manager with one of these options:

- To create a storefront in a GitHub repository and set up the associated resources, see [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md).
- To create the associated resources and generate the code locally, see [Create a Storefront in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md).

Create a storefront from the terminal:

- To explore the storefront code and generate it against the demo sandbox instance, see [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-sf.md).

<!-- document id=ca37f61775ad63ba8f99131c16c172270502278506b03ee7561d40218b7c8011 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/quote-events-webhook.md -->

Quote Events Webhook

# Quote Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/quote-events-webhook/quote-events-webhook-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the CMS system so that Salesforce POS can use them to send quote events data.

**Version:** 2.3.4

## Tags

### Quote Events Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/quote-events-webhook/quote-events-webhook-oas-public.yaml)

Sample APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the CMS system so that Salesforce POS can use them to send quote events data.

## Operations

### POST Export quote details for email.

`POST /merchant/spi/sample/endpoint/sa/customer/quote/quoteEmail`

Operation ID: `eReceiptQuoteSPI`. Tags: Quote Events Webhook.

Export the quote details to merchants, and the merchant system sends the quote email to the customer. This SPI shares created Quote events to merchant's system for email. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `ERECEIPT_QUOTE`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `application/json`. Schema: `EReceiptQuoteRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export quote details.

`POST /merchant/spi/sample/endpoint/sa/customer/quote/quoteExport`

Operation ID: `quoteExportWebhook`. Tags: Quote Events Webhook.

Export the created or updated quote details. This webhook exports Quote events to merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `QUOTE_EXPORT`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json"}.

#### Request body

Media type: `application/json`. Schema: `QuotePayload`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### EReceiptQuoteRequest

*   `emailTo` (_array of string_) Emails to receive quote.
*   `quotePayload` (_QuotePayload_)

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### QuotePayload

*   `cartId` (_string_) Cart ID.
*   `suspendedCartId` (_string_, nullable) Unique UUID value present for suspended carts. The value is different from the Cart ID.
*   `storeId` (_string_, nullable) Store ID.
*   `transactionId` (_string_) The unique identifier for this transaction, for example, Void cart.
*   `storeRegisterId` (_string_) Store Register ID. Local to each store.
*   `associateId` (_string_, nullable) Store associate ID.
*   `cartType` (_string_) The type of cart payload ( Void cart or suspended cart).
*   `cartItemList` (_array of Product_) The list of products added to the cart.
*   `subTotal` (_number_) The subtotal amount of the products added to the cart.
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_) The list of price adjustments done on the items in cart.
*   `orderPriceAdjustments` (_array of OrderPriceAdjustment_) The list of price adjustments done on the total order in the cart.
*   `promotionCodes` (_array of string_) The list of promotion codes applied to the items in cart.
*   `taxTotal` (_number_) The total tax amount for the items in cart.
*   `taxExemption` (_number_) The tax exemption applicable on the items in cart.
*   `transactionDiscountAmount` (_number_) The transaction discount amount for the items in cart.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `shippingTotal` (_number_) The total Shipping amount in case of online orders.
*   `customerEmail` (_string_) The email address of the customer.
*   `profile` (_Profile_)
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the actions performed on the cart. For example, reason for discounts applied to the order.
*   `fullfillmentType` (_string_) The fulfillment type of the order: IN\_STORE or ONLINE.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxRates` (_array of OrderTaxRate_) Sale-side tax rate.
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions.
*   `vatRates` (_array of OrderTaxRate_) Sale-side VAT rate.
*   `netTaxRates` (_array of OrderTaxRate_) Net tax rate calculated based on sale-side tax rate and return-side tax rate.
*   `netVatRates` (_array of OrderTaxRate_) Net VAT rate calculated based on sale-side VAT rate and return-side VAT rate.
*   `amountToBeCharged` (_number_) Amount to be charged.
*   `transactionDiscount` (_Discount_)
*   `exchangeItemRequests` (_array of ExchangeItemRequest_) Request for items that are being returned or exchanged.
*   `summary` (_CartSummary_)
*   `notesList` (_array of OrderNote_, nullable) The order-level notes.
*   `employee` (_Employee_)
*   `transactionStartDate` (_string (date-time)_) The timestamp when the cart was created.
*   `transactionDate` (_string (date-time)_) The timestamp when the cart was voided or suspended.
*   `rewardList` (_array of Reward_, nullable) List of rewards applied to the cart.
*   `tariffAmount` (_number_, nullable) Tariff amount applied to the cart.
*   `tariffRate` (_number_, nullable) Tariff rate applied to the cart.
*   `customerLoyaltyProfile` (_CustomerLoyaltyProfile_)
*   `loyaltyId` (_string_, nullable) Loyalty ID of the customer.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup details for the cart.
*   `shippingMethod` (_ShippingMethod_)
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address and corresponding shipping method.
*   `quoteId` (_string_) Quote ID.
*   `externalQuoteId` (_string_, nullable) External quote ID.
*   `customerId` (_string_, nullable) Customer ID.
*   `customerName` (_string_, nullable) Customer Name.
*   `customerPhone` (_string_, nullable) Customer Phone.
*   `createdTs` (_integer (int64)_) Created timestamp in epoch milliseconds.
*   `lastUpdatedTs` (_integer (int64)_) Last updated timestamp in epoch milliseconds.

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### OrderPriceAdjustment

The list of price adjustments done on the total order in the cart.

*   `description` (_string_)
*   `adjustment` (_number_)
*   `discount` (_Discount_)
*   `price` (_number_)
*   `promotionId` (_string_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Discount

Transaction discount applied on the cart with information like discount type and discount value. In online mode it is copied from app's request payload for transaction discount and in case of offline mode it is copied from app's submit order request.

*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`, `AMOUNT, PERCENT`. Default: `AMOUNT`.
*   `discount` (_number_, required) Discount either in percentage or in amount.

### ExchangeItemRequest

Request for items that are being returned or exchanged.

*   `storeAssociateId` (_string_, required) ID of the store associate who performs the returns.
*   `storeId` (_string_, required) ID of the store where the return is being performed.
*   `installationId` (_string_, required) Installation ID of the register from where the return is being performed.
*   `noReceiptReturns` (_boolean_, nullable) Flag to indicate returns without receipt.  
    Default: `false`.
*   `receiptType` (_string_, nullable) Receipt type enum.  
    Allowed values: `ORDER`, `QUOTE`, `GIFT`, `GIFT_SKU_LEVEL`, `GIFT_REWARD_CARD`, `INVENTORY_TRANSFER_PACKING_SLIP`, `PO_ORDER`, `STORE_TO_STORE_TRANSFER`, `RETURN_TO_VENDOR_TRANSFER`, `PICK_LIST`.
*   `editOrderId` (_string_, nullable) Set in case of edit order mode. Value will be same as orderId.
*   `refundFees` (_array of RefundFee_) Refund fees applied when cancelling or returning items from an order during the edit order flow.
*   `offlineMode` (_boolean_) Flag to indicate whether returns or exchange is being performed in offline mode or not.
*   `returnProducts` (_array of ReturnProductIdentification_) Returning item's orderItemId and quantity.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakup for return items.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakup for return items.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `storeAttribution` (_StoreAttribution_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `employee` (_Employee_)
*   `orderSource` (_string_, nullable) Order Source - Indicates channel from where the order originated.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariffAmount` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `giftCardCashOut` (_boolean_)
*   `exchangeOrderPaymentDetails` (_array of ExchangeOrderPaymentDetail_)

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### CustomerLoyaltyProfile

The loyalty profile of the customer if they are enrolled in Loyalty program.

*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `firstName` (_string_) Customer's first name.
*   `lastName` (_string_) Customer's last name.
*   `accountNumber` (_string_) Customer's loyalty account number.
*   `loyaltyStatusCode` (_string_, nullable) Customer's loyalty status code.
*   `currentPoints` (_integer (int32)_, nullable) Customer's current loyalty points. If provided, it will be used for validation against the individual reward points (If points are sent in reward).
*   `currentStoreCredit` (_number (double)_, nullable) Customer's current store credit.
*   `lifetimePoints` (_integer (int32)_, nullable) Loyalty point accumulated so far by the customer.
*   `nextRewardPoints` (_integer (int32)_, nullable) Loyalty point eligible for next reward cycle.
*   `transactions` (_Transactions_)
*   `rewards` (_array of Reward_, nullable) Earned rewards.
*   `tierLevelLabel` (_string_, nullable) Customer's tier level label.
*   `tierLevelValue` (_string_, nullable) Customer's tier level value.
*   `tierLevelCode` (_string_, nullable) Customer's tier level code.
*   `redemptionType` (_string_)
*   `internalMemberId` (_string_, nullable) Customer's internal member ID.
*   `homePhoneNumber` (_string_, nullable) Customer's home phone number.
*   `mobilePhoneNumber` (_string_, nullable) Customer's mobile phone number.
*   `address` (_Address_)
*   `currentTier` (_Tier_)
*   `nextTier` (_Tier_)
*   `customLoyaltyAttributes` (_CustomAttributes_)
*   `totalRewardsAmount` (_number_, nullable) Total amount value of all the rewards available for the customer. If provided, this will be used for validation when applying the individual rewards.
*   `loyaltyIdBarCodeType` (_string_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### RefundFee

Refund fees applied when cancelling or returning items from an order during the edit order flow.

*   `id` (_string_) Refund fee ID. For example, Restocking or 001.
*   `label` (_string_) Refund fee display name. For example, Restocking Fee.
*   `value` (_number_, nullable) Refund fee amount.

### ReturnProductIdentification

Returning item's orderItemId and quantity.

*   `orderItemId` (_string_, required) Order item ID of returning product obtained from original order. It provides the returning item's line item number from the original order.
*   `quantity` (_integer (int32)_, required) Total quantity being returned.
*   `reason` (_Reason_)
*   `epc` (_string_) Electronic Product Code/RFID.
*   `serialNumbers` (_array of string_, nullable) Provide serial numbers for returning product if applicable and captured by store associate.  
    Unique items.

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### ExchangeOrderPaymentDetail

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `refundAmount` (_number_)
*   `amountToBeAppliedForExchange` (_number_)
*   `refundTransactionId` (_number_)
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use refundMode instead.
*   `refundRoundingAmount` (_number_)
*   `refundMode` (_string_, nullable) If the tender requires special handling when performing a refund, provide the specific refund mode here. Supported modes are Unreferenced and ExternalAuth. For example, during a credit card authorization call, provide the refund mode ExternalAuth when the app issues the refund instead of the regular flow.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `splitRefund` (_boolean_) If an original tender is split into multiple refunds during return and if the current refund tender is one of the split refunds of the original tender. Used in MaxCashReturn policy where original tender might get split into two during returns.
*   `validRefundTender` (_boolean_)
*   `remapped` (_boolean_)
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### Transactions

Loyalty transactions.

*   `nextStartMonth` (_integer (int32)_)
*   `txnActivity` (_array of TransactionActivity_)

### Tier

Customer's next tier details.

*   `name` (_string_) Tier name.
*   `minPoints` (_number_) Minimum points required for the tier.
*   `display` (_string_)
*   `points` (_integer (int32)_)
*   `memberSince` (_integer (int64)_) Member since, of this tier.
*   `title` (_string_)
*   `subTitle` (_string_)
*   `imageUrl` (_string_)
*   `expiryDate` (_integer (int64)_) Expiry date of the customer's membership.

### CustomAttributes

Custom attributes.

*   `customLabel` (_string_)
*   `customValues` (_array of CustomValue_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### TransactionActivity

*   `orderId` (_string_)
*   `date` (_integer (int64)_)
*   `description` (_string_)
*   `points` (_integer (int32)_)
*   `amount` (_number_)
*   `pointStatus` (_string_)  
    Allowed values: `EARNED`, `PENDING`, `REWARD`, `REDEEMED`.
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    

### CustomValue

*   `laabel` (_string_)
*   `value` (_string_)
*   `iconType` (_string_)

<!-- document id=87b1a7ace583992f01ef42aff681e85219b53128eb06ceb2694afe71014c2c33 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/quote-spi.md -->

Quote SPI

# Quote SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/quote-spi/quote-spi-oas-public.yaml)

Merchant SPI to search and retrieve quotes from external ERP/quote management systems. APIs include searching quotes, retrieving quote details, and verifying connectivity.

### Prerequisites

Enable these settings in **CMS** > **Store Management** > **Store Settings** > **Advanced**.

1.  **Quote Master of Record is external ERP system** - Set to true
2.  **Keep same Quote ID when quote is resumed as cart and then converted back to quote** - Set to true

### Configuration in CMS

1.  Go to **Store Management** > **Integration** > **Custom API Connectors** > **Create**.
    
    *   Set **API Key** to QUOTE\_SERVICE.
    *   Set **API Endpoint** to your base URL. For example, [https://your-system.com/api/quotes](https://your-system.com/api/quotes).
2.  Under **JSON Config**:
    
    *   Set **Integration Type** to HTTP\_POST.
    *   Set **JSON Headers:** `{"Content-Type":"application/json"}`

**Note:** For exporting quotes from POS to external systems, configure the **QUOTE\_EXPORT** webhook separately. The QUOTE\_EXPORT and QUOTE\_SERVICE endpoints should share the same domain for proper integration.

### Available Endpoints

*   **/search** - Search quotes from external system
*   **/{quoteId}** - Get a specific quote by ID
*   **/{quoteId}** - Delete a quote by ID (DELETE)
*   **/verify** - Verify SPI connectivity

### Quote Source Identification

Quotes created in POS will have a 'source' field indicating origin. External quotes from the merchant's system will be labeled accordingly in the POS quote list.

**Version:** 2.3.4

## Tags

### Quote SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/quote-spi/quote-spi-oas-public.yaml)

Merchant SPI to search and retrieve quotes from external ERP/quote management systems. APIs include searching quotes, retrieving quote details, and verifying connectivity.

### Prerequisites

Enable these settings in **CMS** > **Store Management** > **Store Settings** > **Advanced**.

1.  **Quote Master of Record is external ERP system** - Set to true
2.  **Keep same Quote ID when quote is resumed as cart and then converted back to quote** - Set to true

### Configuration in CMS

1.  Go to **Store Management** > **Integration** > **Custom API Connectors** > **Create**.
    
    *   Set **API Key** to QUOTE\_SERVICE.
    *   Set **API Endpoint** to your base URL. For example, [https://your-system.com/api/quotes](https://your-system.com/api/quotes).
2.  Under **JSON Config**:
    
    *   Set **Integration Type** to HTTP\_POST.
    *   Set **JSON Headers:** `{"Content-Type":"application/json"}`

**Note:** For exporting quotes from POS to external systems, configure the **QUOTE\_EXPORT** webhook separately. The QUOTE\_EXPORT and QUOTE\_SERVICE endpoints should share the same domain for proper integration.

### Available Endpoints

*   **/search** - Search quotes from external system
*   **/{quoteId}** - Get a specific quote by ID
*   **/{quoteId}** - Delete a quote by ID (DELETE)
*   **/verify** - Verify SPI connectivity

### Quote Source Identification

Quotes created in POS will have a 'source' field indicating origin. External quotes from the merchant's system will be labeled accordingly in the POS quote list.

## Operations

### GET Get Quote Details

`GET /merchant/spi/sample/endpoint/quote/{quoteId}`

Operation ID: `getQuoteDetails`. Tags: Quote SPI.

Retrieve detailed information for a specific quote from the merchant's external ERP system. This API is called when a store associate views or resumes a specific quote in POS.

### Use Cases

*   View complete quote details including items, pricing, and customer information
*   Resume a quote to cart for editing or conversion to order
*   Retrieve quote information for reporting or analysis

### Request Parameters

*   **quoteId**: The ID of the quote to retrieve (required, path parameter)

**Response (GetQuoteResponse):**

*   **quote**: SavedCart object containing complete quote details
*   **quoteId**: Unique quote identifier
*   **externalQuoteId**: External system quote ID if different
*   **customerId**: Associated customer ID
*   **status**: Quote status (e.g., Suspended, Active)
*   **cartItemList**: List of items in the quote
*   **subTotal**: Subtotal amount
*   **tax**: Tax amount
*   **total**: Total amount
*   **createdTs**: Quote creation timestamp
*   **source**: Origin of the quote (e.g., "external", "pos")
*   **associateSessionId**: Session identifier for the associate

**Example Response:**

{
"status": "success",
"quote": {
"quoteId": "Q-001",
"externalQuoteId": "EXT-Q-001",
"customerId": "CUST-123",
"status": "Suspended",
"source": "external",
"cartItemList": \[
{
"productId": "PROD-456",
"quantity": 2,
"price": 49.99
}
\],
"subTotal": 99.98,
"tax": 8.00,
"total": 107.98,
"createdTs": 1701619200000
},
"associateSessionId": "session-123"
}

.

#### Parameters

*   `quoteId` (path, string, required)

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiGetQuoteResponse`.
    

### DELETE Delete Quote

`DELETE /merchant/spi/sample/endpoint/quote/{quoteId}`

Operation ID: `deleteQuote`. Tags: Quote SPI.

Delete a quote from the merchant's external ERP system. This API is called when a store associate deletes a quote in POS.

### Use Cases

*   Delete a quote that is no longer needed
*   Remove expired or cancelled quotes
*   Clean up duplicate quotes

### Request Parameters

*   **quoteId**: The ID of the quote to delete (required, path parameter)

**Response (SpiPSResponse):**

*   **status**: success/failure
*   **statusMessage**: Descriptive message

**Example Response:**

{
"status": "success",
"statusMessage": "Quote deleted successfully"
}

.

#### Parameters

*   `quoteId` (path, string, required)

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Search Quotes

`POST /merchant/spi/sample/endpoint/quote/search`

Operation ID: `searchQuotes`. Tags: Quote SPI.

Search quotes from the merchant's external ERP system based on various criteria. This API is called when a store associate searches for quotes in POS.

### Use Cases

*   Search quotes created in POS that were exported to external system
*   Search quotes created on merchant's external website/system
*   Resume a quote to cart for updates

**Request Parameters (SpiQuoteRequest):**

*   **quoteId**: Search by specific quote ID
*   **customerId**: Filter by customer ID
*   **firstName/lastName/name**: Filter by customer name
*   **email**: Filter by customer email
*   **phone**: Filter by customer phone
*   **storeId**: Filter by store
*   **storeAssociateId**: Filter by associate who created the quote
*   **storeRegisterId**: Filter by register
*   **productId**: Find quotes containing this product
*   **quoteDateTimeStampStart/End**: Filter by date range (epoch ms)
*   **start**: Pagination offset (default: 0)
*   **limit**: Max results to return (default: 20)
*   **advanceSearchId**: For pagination across multiple pages
*   **source**: Filter quotes by origin (POS, EXTERNAL, ALL)

**Response (QuoteSearchResponse):**

*   **quoteList**: List of SavedCart objects representing quotes
*   **advanceSearchId**: Token for fetching next page of results

**Example Response:**

{
"status": "success",
"quoteList": \[
{
"quoteId": "Q-001",
"externalQuoteId": "EXT-Q-001",
"customerId": "CUST-123",
"status": "Suspended",
"source": "external",
"cartItemList": \[.\],
"subTotal": 99.99,
"createdTs": 1701619200000
}
\],
"advanceSearchId": "next-page-token"
}

.

#### Request body

Media type: `application/json`. Schema: `SpiQuoteRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiQuoteSearchResponse`.
    

## Schemas

### SpiGetQuoteResponse

SPI Response object for Get Quote Details operations.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `quote` (_QuotePayload_)
*   `associateSessionId` (_string_, nullable) Associate Session Id.
*   `error` (_boolean_)

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### SpiQuoteRequest

Request object for Quote SPI operations.

*   `firstName` (_string_) Customer first name.
*   `lastName` (_string_) Customer last name.
*   `name` (_string_) Customer full name.
*   `email` (_string_) Customer email address.
*   `phone` (_string_) Customer phone.
*   `quoteId` (_string_) Quote ID.
*   `start` (_integer (int32)_) Quote search offset. Used for paginating across multiple quotes.  
    Default: `0`.
*   `limit` (_integer (int32)_) Number of quotes to return. Used for paginating across multiple quotes.  
    Default: `20`.
*   `storeId` (_string_) Store ID. Find quote placed in this store.
*   `customerId` (_string_) Customer ID. Find quotes placed by this customer ID.
*   `productId` (_string_) Product ID. Find quotes containing this product ID.
*   `storeAssociateId` (_string_) Store Associate ID. Find quotes placed by specific store associate.
*   `storeRegisterId` (_string_) Store Register ID. Find quotes placed from specific store register.
*   `quoteDateTimeStampStart` (_integer (int64)_) Find quotes placed on or after this timestamp - represented as milliseconds since epoch.
*   `quoteDateTimeStampEnd` (_integer (int64)_) Find quotes placed or or before this timestamp - represented as milliseconds since epoch.
*   `advanceSearchId` (_string_) Advanced Search Id for changing the page.
*   `source` (_string_) Optional. Only used/expected when Quote SPI (QUOTE\_SERVICE) is configured. Filters quotes by origin.  
    Allowed values: `POS`, `EXTERNAL`, `ALL`, `POS`, `EXTERNAL`, `ALL`.

### SpiQuoteSearchResponse

SPI Response object for Quote search operations.

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `quoteList` (_array of QuotePayload_) List of searched quotes.
*   `advanceSearchId` (_string_)
*   `error` (_boolean_)

### QuotePayload

*   `cartId` (_string_) Cart ID.
*   `suspendedCartId` (_string_, nullable) Unique UUID value present for suspended carts. The value is different from the Cart ID.
*   `storeId` (_string_, nullable) Store ID.
*   `transactionId` (_string_) The unique identifier for this transaction, for example, Void cart.
*   `storeRegisterId` (_string_) Store Register ID. Local to each store.
*   `associateId` (_string_, nullable) Store associate ID.
*   `cartType` (_string_) The type of cart payload ( Void cart or suspended cart).
*   `cartItemList` (_array of Product_) The list of products added to the cart.
*   `subTotal` (_number_) The subtotal amount of the products added to the cart.
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_) The list of price adjustments done on the items in cart.
*   `orderPriceAdjustments` (_array of OrderPriceAdjustment_) The list of price adjustments done on the total order in the cart.
*   `promotionCodes` (_array of string_) The list of promotion codes applied to the items in cart.
*   `taxTotal` (_number_) The total tax amount for the items in cart.
*   `taxExemption` (_number_) The tax exemption applicable on the items in cart.
*   `transactionDiscountAmount` (_number_) The transaction discount amount for the items in cart.
*   `shippingAddress` (_Address_)
*   `billingAddress` (_Address_)
*   `shippingTotal` (_number_) The total Shipping amount in case of online orders.
*   `customerEmail` (_string_) The email address of the customer.
*   `profile` (_Profile_)
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the actions performed on the cart. For example, reason for discounts applied to the order.
*   `fullfillmentType` (_string_) The fulfillment type of the order: IN\_STORE or ONLINE.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxRates` (_array of OrderTaxRate_) Sale-side tax rate.
*   `taxExemptions` (_array of TaxExemptionRequest_) Sale-side tax exemptions.
*   `vatRates` (_array of OrderTaxRate_) Sale-side VAT rate.
*   `netTaxRates` (_array of OrderTaxRate_) Net tax rate calculated based on sale-side tax rate and return-side tax rate.
*   `netVatRates` (_array of OrderTaxRate_) Net VAT rate calculated based on sale-side VAT rate and return-side VAT rate.
*   `amountToBeCharged` (_number_) Amount to be charged.
*   `transactionDiscount` (_Discount_)
*   `exchangeItemRequests` (_array of ExchangeItemRequest_) Request for items that are being returned or exchanged.
*   `summary` (_CartSummary_)
*   `notesList` (_array of OrderNote_, nullable) The order-level notes.
*   `employee` (_Employee_)
*   `transactionStartDate` (_string (date-time)_) The timestamp when the cart was created.
*   `transactionDate` (_string (date-time)_) The timestamp when the cart was voided or suspended.
*   `rewardList` (_array of Reward_, nullable) List of rewards applied to the cart.
*   `tariffAmount` (_number_, nullable) Tariff amount applied to the cart.
*   `tariffRate` (_number_, nullable) Tariff rate applied to the cart.
*   `customerLoyaltyProfile` (_CustomerLoyaltyProfile_)
*   `loyaltyId` (_string_, nullable) Loyalty ID of the customer.
*   `pickUpDetailList` (_array of OrderPickUpDetail_, nullable) List of pickup details for the cart.
*   `shippingMethod` (_ShippingMethod_)
*   `deliveryGroups` (_array of DeliveryGroup_, nullable) List of delivery groups. Each delivery group has shipping address and corresponding shipping method.
*   `quoteId` (_string_) Quote ID.
*   `externalQuoteId` (_string_, nullable) External quote ID.
*   `customerId` (_string_, nullable) Customer ID.
*   `customerName` (_string_, nullable) Customer Name.
*   `customerPhone` (_string_, nullable) Customer Phone.
*   `createdTs` (_integer (int64)_) Created timestamp in epoch milliseconds.
*   `lastUpdatedTs` (_integer (int64)_) Last updated timestamp in epoch milliseconds.

### Product

The details of product's deposit. For example, order item ID, required deposit, and paid deposit.

*   `productId` (_string_, required) Product ID. Unique identifier of an item.  
    All the variations of an item will have distinct product id hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID.  
    All the variants of an item are grouped together under the same variant id.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `productTax` (_ProductTax_)
*   `tax` (_number_, nullable) Total tax on this product.  
    Mandatory for tax countries and applies to products that are subject to taxation.  
    
*   `taxExemption` (_number_, nullable) Tax exemption amount  
    Applicable if the tax exemption is applied by store associate during checkout process.  
    
*   `valueAddedTax` (_number_, nullable) Total VAT on this product. Mandatory for VAT countries.
*   `orderItemId` (_string_, required) Sequence number assigned to this line item.  
    Must be unique within this order and must have numerical value.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.It is used to display the image of the item in the cart, order summary screens. email.
*   `subTotal` (_number_, required) The total cost of the item is inclusive of VAT,  
    but exclusive of discounts, shipping fees, and taxes.
*   `discount` (_number_, nullable) Total discount applied on the item.  
    It is the sum of all the discounts applied on the item.  
    The discount includes manual price adjustments  
    (i.e. item level price override & transaction discount) and  
    promotions (i.e. coupons, auto promotion & reward coupon)  
    Mandatory if any type of discounts is applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/vat and discounts.
*   `store` (_Store_)
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList, orderProductList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and orderProductList.returnsEligibility/productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `NEW`, `PROCESSING`, `PARTIALLY_SHIPPED`, `SHIPPED`, `CANCELED`, `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `REWARD`, `PENDING`, `UNKNOWN`, `READY`, `PACK`, `UNPACK`, `PICKED`, `DELIVERED`, `CREATED`, `CANCELLED_WITH_REFUND`, `UNAVAILABLE`, `DAMAGED`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `RECREATED`, `FULFILLED`, `PENDING_ORDER`, `IN_TRANSIT`, `EDITED`.
*   `returnedDateTimeStamp` (_integer (int64)_, nullable) Timestamp when the item is returned.  
    Mandatory if the item is returned and is part of returnProductList  
    When importing an order from external system and if it has returnProductList, ensure to provide this returned date.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges applied on the item.  
    It is the sum of all the additional charges applied on the item.  
    Mandatory if any type of additional charges is applied.  
    Additional charges include CRV, Liquor Tax etc.
*   `additionalCharges` (_array of AdditionalCharge_, nullable) List of additional charges applied on the item.  
    It is used to capture additional charges like CRV, Liquor Tax etc.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `notesList` (_array of OrderDetailNote_, nullable) List of notes/comments captured at product level during order submission.If the notes are provided when importing an order from an external system,  
    they will be available for store associate in order history screen of POS App.  
    
*   `salesAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `salesAssociateAttribution` (_array of OrderStoreAssociateAttribution_, nullable) Sales associate attribution.  
    If not provided, POS attributes the item to the logged-in store associate.  
    
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    It is used to determine if the item is eligible for returns or not.  
    When importing an order from an external system, item's return-eligibilitycan be controlled by providing appropriate value here.  
    CANNOT\_BE\_RETURNED blocks the return even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `appeasementEligibility` (_string_, nullable) Appeasement eligibility of the item.  
    It is used to determine if the item is eligible for price adjustment or not in edit order flow  
    When importing an order from an external system, item's appeasement-eligibilitycan be controlled by providing appropriate value here.  
    INELIGIBLE\_FOR\_APPEASEMENT blocks any adjustment even if item's status is COMPLETED.  
      
    Allowed values: `ELIGIBLE_FOR_APPEASEMENT`, `INELIGIBLE_FOR_APPEASEMENT`.
*   `cyoDetails` (_CyoDetails_)
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `tlogCustomProductAttributes` (_string_, read-only, nullable) Custom product attributes.  
    It is used to capture custom attributes of the product.  
    If the product has any custom attributes, they will be captured here.  
    Store settings (**CMS** > **Store Management** > **Store Settings** > **OMS**\>  
    Order Export > tLogCustomProductAttributes) needs be configured with  
    the list of custom attributes to be populated here.  
    It it is not required when importing an order from an external system.  
    
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of Product_, nullable) The other items from the cart related to the current item.  
    Commonly used in case of customizations like Alteration as well as for add-on products.  
    Mandatory for alteration or add-on items.  
    No need to provide this attribute, when importing an order and  
    if the item doesn't have add-on item.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_, nullable) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `promotionTitle` (_string_, nullable) Provides applicable promotion titles in pipe delimited format. If the item is qualified for multiple promotions, promotionTitle will have multiple titles in delimited form.It is used to display the promotion title on the item in order history screen of POS App.  
    Example: `Winter discount| Holiday special`.
*   `priceCorrection` (_OrderDetailPriceCorrection_)
*   `fulfillmentLocation` (_Store_)
*   `pickupLocation` (_Store_)
*   `deliveryGroupId` (_string_, nullable) Delivery Group Id - It is an identifier to the shipping details of the item.  
    It links the item to one of the delivery groups available in order level.  
    It is used for item level shipping method and address.  
    Mandatory for all delivery items if item level shipping method  
    or item level shipping address is enabled.  
    For more details, see:  
    1\. Item level shipping method:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html) 2. Item level shipment Address:  
    [Retrieve Delivery and Pickup Dates via SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retrieve-delivery-pickup-dates-via-spi.html)  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) Product from attributes.
*   `pickupDetailId` (_string_, nullable) Provide a link to the corresponding pickup details  
    from pickupDetailList available in the order. Applicable for pickup items.  
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `originalPaidDeposit` (_number_)
*   `serializedUnitDetailList` (_array of SerializedUnitDetail_, nullable) Attributes for each individual unit of the product, for example, activation code or context code.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `itemTariff` (_number_, nullable) The item tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `groupId` (_string_)
*   `returnRelated` (_boolean_)
*   `mainProduct` (_boolean_)
*   `shippingAddress` (_Address_)
*   `requiredDepositPercentage` (_number_)
*   `virtual` (_boolean_)

### ProductPriceAdjustment

*   `productId` (_string_)
*   `basePrice` (_string_)
*   `adjustedPrice` (_string_)
*   `priceAdjustments` (_array of PriceAdjustment_)
*   `orderItemId` (_string_)
*   `priceAfterItemDiscount` (_number_)
*   `priceAfterOrderDiscount` (_number_)
*   `totalAdjustedPrice` (_number_)
*   `totalTaxablePrice` (_number_)
*   `totalAddtionalCharge` (_number_)
*   `totalItemDiscount` (_number_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `additionalCharges` (_array of AdditionalCharge_)

### OrderPriceAdjustment

The list of price adjustments done on the total order in the cart.

*   `description` (_string_)
*   `adjustment` (_number_)
*   `discount` (_Discount_)
*   `price` (_number_)
*   `promotionId` (_string_)
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

### Profile

Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address.
    
    Includes all fields of `Address`.
    
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import.
*   `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments.  
    Optional field returned only when customer has stored cards.
*   `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import.
*   `country` (_string_, nullable) Country.
*   `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import.
*   `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import.
*   `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.
*   `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### OrderTaxRate

VAT breakup for return items.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
      
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Default: `TAX`.
*   `nonRefundable` (_boolean_) Indicates if the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) Tax class corresponding to the tax rate.  
      
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Tax Identifier. Unique identifier for a tax rate. Unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the tax rate for the order.  
    Example: `7.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `returnedTaxAmount` (_number_) Sum of returned tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) across returned products.
*   `remainingTaxAmount` (_number_) Sum of tax amounts of a particular type(group of TaxType, TaxClass, TaxName, TaxRate) across non-returned products.
*   `corporateTaxId` (_string_, nullable) Print tax name for receipts.  
    Includes the merchant's tax identification number, for example, HST-74252RT0001 - 7.25%.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for Merchant Systems.
*   `effectiveDate` (_integer (int64)_) Effective date of the current tax rate in epochMillis. Use the epoch values as-is without applying in offset.
*   `subTotal` (_number_, nullable) Sum of product prices excluding the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. " Product is not necessarily exclusive to a single tax rate in non VAT scenario.Only Products that fall under particular VAT rate are considered.
*   `total` (_number_, nullable) Sum of product prices including the VAT amount. Applicable only for VAT enabled countries because for non VAT countries a product can have two rates applied to it. Product is not exclusive to a single tax rate in non VAT scenario. Only Products that fall under particular VAT rate are considered.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### TaxExemptionRequest

Sale side tax exemptions.

*   `cartId` (_string_, nullable) Cart ID. Backend populates it internally from path param. It is optional for app to provide it if the API endpoint contains the cartId as path param.
*   `customerId` (_string_, nullable) Customer ID.
*   `offlineMode` (_boolean_, nullable) Flag for offline mode.
*   `taxExemptCode` (_string_, required) Tax exemption tax code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer tax exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption.  
    Maximum length: 128.
*   `displayTaxName` (_string_) Display Tax Name to be printed on UI.
*   `printTaxName` (_string_) Tax Name to be printed on receipt.
*   `taxExemptionRate` (_number (float)_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### Discount

Transaction discount applied on the cart with information like discount type and discount value. In online mode it is copied from app's request payload for transaction discount and in case of offline mode it is copied from app's submit order request.

*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`, `AMOUNT, PERCENT`. Default: `AMOUNT`.
*   `discount` (_number_, required) Discount either in percentage or in amount.

### ExchangeItemRequest

Request for items that are being returned or exchanged.

*   `storeAssociateId` (_string_, required) ID of the store associate who performs the returns.
*   `storeId` (_string_, required) ID of the store where the return is being performed.
*   `installationId` (_string_, required) Installation ID of the register from where the return is being performed.
*   `noReceiptReturns` (_boolean_, nullable) Flag to indicate returns without receipt.  
    Default: `false`.
*   `receiptType` (_string_, nullable) Receipt type enum.  
    Allowed values: `ORDER`, `QUOTE`, `GIFT`, `GIFT_SKU_LEVEL`, `GIFT_REWARD_CARD`, `INVENTORY_TRANSFER_PACKING_SLIP`, `PO_ORDER`, `STORE_TO_STORE_TRANSFER`, `RETURN_TO_VENDOR_TRANSFER`, `PICK_LIST`.
*   `editOrderId` (_string_, nullable) Set in case of edit order mode. Value will be same as orderId.
*   `refundFees` (_array of RefundFee_) Refund fees applied when cancelling or returning items from an order during the edit order flow.
*   `offlineMode` (_boolean_) Flag to indicate whether returns or exchange is being performed in offline mode or not.
*   `returnProducts` (_array of ReturnProductIdentification_) Returning item's orderItemId and quantity.
*   `taxRates` (_array of OrderTaxRate_, nullable) Tax breakup for return items.
*   `vatRates` (_array of OrderTaxRate_, nullable) VAT breakup for return items.
*   `paidAmount` (_number_) Used in edit order flow. Amount already paid as part of original order.
*   `storeAttribution` (_StoreAttribution_)
*   `productPriceAdjustments` (_array of ProductPriceAdjustment_)
*   `employee` (_Employee_)
*   `orderSource` (_string_, nullable) Order Source - Indicates channel from where the order originated.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.
*   `tariffAmount` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `giftCardCashOut` (_boolean_)
*   `exchangeOrderPaymentDetails` (_array of ExchangeOrderPaymentDetail_)

### CartSummary

Payload that contains summary of cart totals.

*   `saleSummary` (_TransactionSummary_)
*   `refundSummary` (_TransactionSummary_, required)
*   `netSummary` (_TransactionSummary_, required)
*   `depositSummary` (_TransactionDeposit_)

### OrderNote

The Order level notes.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### Employee

Employee information. It is applicable for orders with employee discount.

*   `employeeId` (_string_, required) Identification of employee.  
    Maximum length: 128.
*   `firstName` (_string_, required) Employee's first name.  
    Maximum length: 128.
*   `lastName` (_string_, nullable) Employee's last name.  
    Maximum length: 128.
*   `email` (_string_, nullable) Employee's email.  
    Maximum length: 128.
*   `promotionIdList` (_array of string_, nullable) List of promotion IDs valid for the employee.
*   `merchantPromotionIdList` (_array of string_, nullable) List of merchant promotion IDs valid for the employee.
*   `approvingEntity` (_ApprovingEntity_)

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

### CustomerLoyaltyProfile

The loyalty profile of the customer if they are enrolled in Loyalty program.

*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `firstName` (_string_) Customer's first name.
*   `lastName` (_string_) Customer's last name.
*   `accountNumber` (_string_) Customer's loyalty account number.
*   `loyaltyStatusCode` (_string_, nullable) Customer's loyalty status code.
*   `currentPoints` (_integer (int32)_, nullable) Customer's current loyalty points. If provided, it will be used for validation against the individual reward points (If points are sent in reward).
*   `currentStoreCredit` (_number (double)_, nullable) Customer's current store credit.
*   `lifetimePoints` (_integer (int32)_, nullable) Loyalty point accumulated so far by the customer.
*   `nextRewardPoints` (_integer (int32)_, nullable) Loyalty point eligible for next reward cycle.
*   `transactions` (_Transactions_)
*   `rewards` (_array of Reward_, nullable) Earned rewards.
*   `tierLevelLabel` (_string_, nullable) Customer's tier level label.
*   `tierLevelValue` (_string_, nullable) Customer's tier level value.
*   `tierLevelCode` (_string_, nullable) Customer's tier level code.
*   `redemptionType` (_string_)
*   `internalMemberId` (_string_, nullable) Customer's internal member ID.
*   `homePhoneNumber` (_string_, nullable) Customer's home phone number.
*   `mobilePhoneNumber` (_string_, nullable) Customer's mobile phone number.
*   `address` (_Address_)
*   `currentTier` (_Tier_)
*   `nextTier` (_Tier_)
*   `customLoyaltyAttributes` (_CustomAttributes_)
*   `totalRewardsAmount` (_number_, nullable) Total amount value of all the rewards available for the customer. If provided, this will be used for validation when applying the individual rewards.
*   `loyaltyIdBarCodeType` (_string_)

### OrderPickUpDetail

List of pick up details for the cart.

*   `orderId` (_string_) Order Identifier.
*   `pickupDetailId` (_string_, required) Unique ID for the order pickup detail. Each pickup item from productList and orderProductList has a reference to this ID.  
    Maximum length: 128.
*   `storeId` (_string_, required) ID of the store from where the items are picked up.  
    Maximum length: 128.
*   `firstName` (_string_, required) First name of the person who is picking up the order.  
    Maximum length: 128.
*   `lastName` (_string_, required) Last name of the person who is picking up the order.  
    Maximum length: 128.
*   `email` (_string_, required) Email of the person who is picking up the order.  
    Maximum length: 128.
*   `phone` (_string_, required) Phone number of the person who is picking up the order.  
    Maximum length: 128.
*   `pickupDate` (_string (date-time)_, nullable) Customer pickup date & time. Used for SLA visibility (BOPIS).
*   `pickupDateTimestamp` (_integer (int64)_, nullable) Customer pickup date & time in epoch milliseconds.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### DeliveryGroup

List of delivery groups. Each delivery group has shipping address and corresponding shipping method.

*   `deliveryGroupId` (_string_, required) Delivery group ID. Each delivery item from productList and orderProductList has a reference to this ID.  
    Maximum length: 32.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_Address_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `availableDateTimeSlotList` (_array of DateTimeSlot_) Available delivery date time slots.
*   `willCallDate` (_DateTimeSlot_)
*   `deliveryDatePickerOption` (_string_) Determines what action to take for the delivery date picker.  
    Allowed values: `ENABLED`, `DISABLED`.
*   `shippingMethodList` (_array of ShippingMethod_, nullable) Available shipping methods corresponding to this delivery group.
*   `sortOrder` (_integer (int32)_)
*   `fulfillmentAddress` (_Address_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ProductTax

Product tax details. Mandatory for tax/vat countries and applies to products that are subject to taxation.

*   `totalTax` (_number_, nullable) Total tax. Applicable for tax countries and if the item is taxable.
*   `taxExemption` (_number_, nullable) Tax Exemption. Applicable for tax countries and if the item is taxable but then the tax exemption is applied.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax rate breakdown for the item. Applicable for tax countries and taxable items. Optional when importing an order from an external system. Used to display the tax breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT rate breakdown for the item. Applicable for VAT countries and taxable items. Optional when importing an order from an external system. Used to display the VAT breakdown on printed receipts and order history screens. If not provided, the breakdown will not be displayed.
*   `valueAddedTax` (_number_, nullable) Total value added tax, Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### AdditionalCharge

*   `display` (_string_)
*   `value` (_number_)
*   `sku` (_string_)
*   `taxable` (_boolean_)
*   `linkedProductId` (_string_)
*   `price` (_number_)
*   `quantity` (_integer (int32)_)
*   `orderItemId` (_string_)
*   `transactionId` (_string_)

### OrderDetailNote

List of notes/comments captured at product level during order submission. If the notes are provided when importing an order from an external system, they will be available for store associate in order history screen of POS App.

*   `orderId` (_string_) Order Identifier.
*   `noteId` (_string_, required) Unique Identifier for the Note.  
    Maximum length: 128.
*   `noteText` (_string_, required) Note Text.  
    Maximum length: 1024.
*   `transactionId` (_string_, required) Unique Identifier for the Transaction.  
    Maximum length: 128.
*   `createdBy` (_string_, required) Associate Id of the User who created the Note.  
    Maximum length: 128.
*   `modifiedBy` (_string_, nullable) Associate Id of the User who modified the Note.  
    Maximum length: 128.
*   `createdOn` (_integer (int64)_, required) Creation Date of the Note in epoch milliseconds.
*   `modifiedOn` (_integer (int64)_, nullable) Modification Date of the Note in epoch milliseconds.
*   `orderItemId` (_string_, required) Order Item Id of the product for which the note is added.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### OrderStoreAssociateAttribution

Sales associate attribution.  
If not provided, POS attributes the item to the logged-in store associate.  

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `contributionPercentage` (_number_)
*   `attributionNote` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### CyoDetails

Payload for CYO - Create Your Own. It is used in multiple use cases like Alterations, DYO, Special Item and Fluid.

*   `type` (_string_, required) Type of customization applied on the product.  
    Allowed values: `Fluid`, `ALTERATIONS`, `DYO`, `SPECIAL_ITEM`, `Fluid, ALTERATIONS, DYO, SPECIAL_ITEM`.
*   `id` (_string_, required) Customization Identification.
*   `payload` (_string_, required) Customization payload containing details specific to the modifications.
*   `customizeUrl` (_string_, nullable) URL for the page or image having finalized customization.
*   `attributes` (_array of CustomField_, nullable) Custom Field.
*   `price` (_number_, required) Customization Price.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### OrderDetailPriceCorrection

If price correction is enabled, the manager can correct the price of the  
item during checkout. The information like original price, approving manager id is  
maintained here after price correction is applied.

*   `orderId` (_string_) Order Identifier.
*   `orderItemId` (_string_, required) Order Item Identifier.  
    Maximum length: 128.
*   `originalPrice` (_number_, required) Original price of the item.
*   `approvingManagerId` (_string_, required) ID of the store manager who has approved the price correction request.  
    Maximum length: 128.
*   `merchantId` (_string_)
*   `locale` (_string_)
*   `region` (_string_)

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### SerializedUnitDetail

Attributes for each individual unit of the product, for example, activation code or context code.

*   `activationCode` (_string_) The activation code of the serialized unit detail.
*   `contextCode` (_string_) The context code of the serialized unit detail.
*   `orderItemId` (_string_) The order item id of the serialized unit detail.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### Wallet

Tokenized card stored in customer wallet for Card on File payments.

*   `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification.
*   `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present.
*   `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification.
*   `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel.  
    Example: `CB`.
*   `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference).  
    Example: `336df316-56b3-430c-a366-ea5e8d694582`.
*   `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID).  
    Example: `xyz12345677777`.
*   `cardAlias` (_string_, required) Identifier of the stored card.  
    Example: `xyz12345677777`.
*   `status` (_string_, required) Status of the wallet card.  
    Allowed values: `Active`, `Inactive`. Example: `Active`.
*   `type` (_string_, required) Type of the wallet card.  
    Allowed values: `Virtual`, `Physical`. Example: `Virtual`.
*   `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex.  
    Example: `Visa`.
*   `cardLastFour` (_string_, required) Last 4 digits of the card number.  
    Example: `1111`.

### RefundFee

Refund fees applied when cancelling or returning items from an order during the edit order flow.

*   `id` (_string_) Refund fee ID. For example, Restocking or 001.
*   `label` (_string_) Refund fee display name. For example, Restocking Fee.
*   `value` (_number_, nullable) Refund fee amount.

### ReturnProductIdentification

Returning item's orderItemId and quantity.

*   `orderItemId` (_string_, required) Order item ID of returning product obtained from original order. It provides the returning item's line item number from the original order.
*   `quantity` (_integer (int32)_, required) Total quantity being returned.
*   `reason` (_Reason_)
*   `epc` (_string_) Electronic Product Code/RFID.
*   `serialNumbers` (_array of string_, nullable) Provide serial numbers for returning product if applicable and captured by store associate.  
    Unique items.

### StoreAttribution

Store attribution corresponding to this order. Applicable for orders placed in-store in offline mode. It is not necessary when an order is imported from an external system.

*   `transactionId` (_string_, required) Transaction ID. It is a unique identifier of the transactions corresponding to an order. The order can have multiple transactions like sale and returns. Each such transaction is uniquely identified by this ID.
*   `storeAssociateId` (_string_, required) The ID of the logged-in store associate.
*   `storeId` (_string_, required) Store Id.
*   `storeGroupID` (_string_, required) Store Group ID.
*   `eventId` (_string_, nullable, deprecated) Event ID within the current transaction. This field is used internally. Don't use in external systems.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `activePaymentReader` (_string_, deprecated) Payment gateway for terminal gift card.
*   `tillSessionId` (_string_)
*   `tillId` (_string_, nullable) Till ID where the transaction is performed.
*   `storeType` (_string_) Store type for current store.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`.
*   `approvingEntity` (_ApprovingEntity_)
*   `timeOffsetFromGMT` (_string_)
*   `millisFromGMT` (_integer (int64)_)

### ExchangeOrderPaymentDetail

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.  
    Maximum length: 128.
*   `paymentMethod` (_string_, required) Payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Payment device.  
    If the payment is made in an external system,  
    set the payment device to External.  
      
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_, nullable) Card number. For CreditCard or GiftCard, the card number is mandatory, including the last 4 digits.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `cardType` (_string_, nullable) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_, nullable) Payment authorization token. Mandatory for credit cards, gift card through Adyen.  
    Maximum length: 128.
*   `authorizationDate` (_string (date-time)_, nullable) Payment authorization timestamp.
*   `captureToken` (_string_, nullable) Payment capture token. Mandatory if the credit card capture is enabled.  
    Maximum length: 128.
*   `captureDate` (_string (date-time)_, nullable) Payment capture timestamp.
*   `firstName` (_string_, nullable) First name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Applicable for credit cards.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 16.
*   `country` (_string_) Country code to use for billing using this tender.Applicable for credit cards.  
    Maximum length: 32.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `refundRequestId` (_string_, nullable) Refund Payment request identification issued by payment gateway/terminal. Mandatory for refund on credit card.  
    Maximum length: 50.
*   `refundDate` (_string (date-time)_, nullable) Refund Date.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) The amount refunded for this tender. Not applicable, if no refund issued yet.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int64)_, required) Payment sequence indicating the order of payment.  
    E.g. if customer pays with cash first and remaining with credit card,  
    then cash tender should have paymentSequenceNumber as 1  
    and credit card tender should have paymentSequenceNumber as 2.  
    
*   `paymentDeviceId` (_string_, nullable) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_, nullable) Bank routing number, Applicable in case of payment method: 'Check'.  
    Maximum length: 32.
*   `accountNumber` (_string_, nullable) Account number. Used for payment through banking system like 'Check', 'Finance'.  
    Maximum length: 32.
*   `checkNumber` (_string_, nullable) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_, nullable) Issues of the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_, nullable) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_string (date-time)_, nullable) Personal identification expiry date. Applicable for Check and Finance.  
    
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).
*   `cardExpirationMonth` (_integer (int32)_, nullable) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_, nullable) Card expiry year. Applicable for credit card.
*   `checkType` (_string_, nullable) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_, nullable) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_, nullable) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_, nullable) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_, nullable) Refers to finance processing related result or instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_, nullable) Primary owner on the account, used for Finance tender.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_, nullable) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response. A non-PII field for merchants to associate a card or card holder with historical transactions.
*   `paymentEntryMode` (_string_, nullable) Indicates how the payment was captured, as provided by the app (for example, VERIFIED\_CARD\_ON\_FILE). The verification is performed on the app side. Used for reporting and audit purposes.
*   `refundAmount` (_number_)
*   `amountToBeAppliedForExchange` (_number_)
*   `refundTransactionId` (_number_)
*   `performedUnreferencedRefunds` (_boolean_, deprecated) Use refundMode instead.
*   `refundRoundingAmount` (_number_)
*   `refundMode` (_string_, nullable) If the tender requires special handling when performing a refund, provide the specific refund mode here. Supported modes are Unreferenced and ExternalAuth. For example, during a credit card authorization call, provide the refund mode ExternalAuth when the app issues the refund instead of the regular flow.  
    Allowed values: `Unreferenced`, `External`, `Default`, `OMS`, `ProductExchange`.
*   `splitRefund` (_boolean_) If an original tender is split into multiple refunds during return and if the current refund tender is one of the split refunds of the original tender. Used in MaxCashReturn policy where original tender might get split into two during returns.
*   `validRefundTender` (_boolean_)
*   `remapped` (_boolean_)
*   `paymentMethodString` (_string_)
*   `authorizationDateMillis` (_integer (int64)_, write-only)
*   `captureDateMillis` (_integer (int64)_, write-only)
*   `effecitivePaidAmount` (_number_)

### TransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required, read-only) Total Item price.
*   `discount` (_number_, read-only, nullable) Total price override and promo coupons applied.
*   `transactionDiscountAmount` (_number_, read-only, nullable) Total transaction discount.
*   `rewardAmount` (_number_, read-only, nullable) Total reward amount.
*   `tax` (_number_, read-only, nullable) Total Tax.
*   `taxExemption` (_number_, read-only, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, read-only, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, read-only, nullable) Total shipping charges.
*   `shippingDiscount` (_number_, read-only, nullable) Total shipping discount.
*   `total` (_number_, required, read-only) Total sale transaction or refund transaction. Cart can have items for a sale transaction or a return transaction or for a transaction that is being performed for both sale and returns in single checkout. In all such scenarios, 'total' is to maintain sale total or refund total or net total (sale total - refund total), i.e., amountToBeCharged respectively. Note: Tip is not included in this total. Tip is on top of this and should not be added to this field.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, read-only, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `totalDiscount` (_number_, nullable) Order Total Savings - Total discount amount applied to the order, combining all discount sources (item-level + transaction-level + promotion-level + shipping discounts). Excludes price corrections.
*   `roundingAmounts` (_number_, write-only)

### TransactionDeposit

Cart summary for deposit of the cart.

*   `requiredDeposit` (_number_, nullable) The minimum deposit required for an order is calculated based on the deposit configuration.  
    For example, if an order includes item1 priced at $100 with a deposit percentage of 10%, and item2 priced at $50 without any deposit configuration, then the minimum deposit needed for this order would be 10% of 100 + 50,  
    which equals $60. Please note that this calculation also includes taxes and shipping charges.
*   `suggestedDeposit` (_number_, nullable) The suggested deposit for an order is calculated based on the deposit configuration when Deposit Must Be Collected to Complete Order is turned off.  
    
*   `depositBalance` (_number_, nullable) Remaining balance for deposit order  
    Applicable for deposit order where customer has paid partial amount  
    and remaining amount is pending.
*   `depositToOrderBalance` (_number_, nullable) The refund amount will be applied to the deposit order.  
    For example, if a refund item is $100 and the deposit balance is $50, the deposit applied to the order will be $50.  
    Similarly, if a refund item is $10 and the deposit balance is $50, the deposit applied to the order will be $10.
*   `depositProductDetails` (_array of Product_, nullable) The details of a product's deposit, for example, order item ID, required deposit, or paid deposit.

### ApprovingEntity

Approving entity who provides approval to set the employee.

*   `approverId` (_string_, nullable) StoreAssociateId who provides approval for the request.
*   `role` (_string_, nullable) The associate's role in the store. It can be one of STORE\_ASSOCIATE, STORE\_MANAGER, or AREA\_MANAGER.

### Transactions

Loyalty transactions.

*   `nextStartMonth` (_integer (int32)_)
*   `txnActivity` (_array of TransactionActivity_)

### Tier

Customer's next tier details.

*   `name` (_string_) Tier name.
*   `minPoints` (_number_) Minimum points required for the tier.
*   `display` (_string_)
*   `points` (_integer (int32)_)
*   `memberSince` (_integer (int64)_) Member since, of this tier.
*   `title` (_string_)
*   `subTitle` (_string_)
*   `imageUrl` (_string_)
*   `expiryDate` (_integer (int64)_) Expiry date of the customer's membership.

### CustomAttributes

Custom attributes.

*   `customLabel` (_string_)
*   `customValues` (_array of CustomValue_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### CustomField

Custom Field.

*   `name` (_string_)
*   `value` (_string_)

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### TransactionActivity

*   `orderId` (_string_)
*   `date` (_integer (int64)_)
*   `description` (_string_)
*   `points` (_integer (int32)_)
*   `amount` (_number_)
*   `pointStatus` (_string_)  
    Allowed values: `EARNED`, `PENDING`, `REWARD`, `REDEEMED`.
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    

### CustomValue

*   `laabel` (_string_)
*   `value` (_string_)
*   `iconType` (_string_)

<!-- document id=93268f46a96584988f0f947207cf3c0c37b2efca32e8fbab13105dada23219dd url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-enterprise-example.md -->

# Real-Life Enterprise Example

Imagine, ElectroFast, a large electronics manufacturer, looking to expand its sales channels to include B2B markets. Using B2B Commerce, ElectroFast sets up a multi-faceted platform to manage complex B2B relationships and transactions, such as bulk orders and custom pricing agreements. Here's what they did.

ElectroFast uses the Product and Catalog data model to categorize its range of products into applicable segments for B2B customers. The Cart and Inventory data models are shared across the B2B stores, to ensure that inventory levels are indicated correctly and that customer carts reflect real-time information regarding availability and pricing.

To provide a seamless order processing experience, ElectroFast integrates B2B Commerce with its existing Enterprise Resource Planning (ERP) system by using Salesforce APIs and the Cart Calculate API framework. This integration synchronizes the order data between the systems, reducing the risk of errors and delays.

ElectroFast also wants to dynamically recommend products based on customer behavior and preferences. For its B2B clients, the company uses Lightning Web Runtime (LWR) to create a customized ordering process that includes approval workflows and discount logic. In addition, ElectroFast modifies the default components with custom attributes and functional flows that leverage the Commerce Connect APIs, Apex and the extension framework.

**See Also**

- [Commerce Data Model](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-dev-data-model.html)
- [Commerce Integrations](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-integration-architecture.html)
- [Build Custom Components](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-custom-component.html)
- [Public Commerce LWR Library](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-public-lwr-library.html)

<!-- document id=ed180d5f6cf1867dfaaa9583a94f56d4a614fd9c4f3d75039fe017b9f73fd77d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/reference.md -->

# Reference

Technical reference for Commerce Apps APIs, data models, and terminology.

## commerce-app.json Schema

Every Commerce App Package must include a `commerce-app.json` file at the root of the CAP directory. This file defines the app's identity and must match the corresponding entry in the App Registry manifest.

| Field          | Type   | Required | Description                                                                                                   |
| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------ |
| `id`           | string | Yes      | App identifier in kebab-case (for example, `avalara-tax`)                                                     |
| `name`         | string | Yes      | Human-readable display name (for example, `Avalara Tax`)                                                      |
| `description`  | string | Yes      | Short description of the app                                                                                  |
| `domain`       | string | Yes      | Commerce domain in hyphen-case (for example, `tax`, `ratings-and-reviews`). Must match the registry manifest. |
| `version`      | string | Yes      | Semantic version (for example, `1.1.0`). Must match the registry manifest.                                    |
| `publisher`    | object | Yes      | Publisher information (see below)                                                                             |
| `dependencies` | object | No       | Reserved for future dependency management between apps                                                        |

**Publisher object:**

| Field     | Type   | Required | Description                               |
| :-------- | :----- | :------- | :---------------------------------------- |
| `name`    | string | Yes      | Publisher/ISV company name                |
| `url`     | string | Yes      | Publisher website or developer portal URL |
| `support` | string | Yes      | Support URL or contact page               |

**Example:**

```json
{
  "id": "avalara-tax",
  "name": "Avalara Tax",
  "description": "Automated tax compliance solution by Avalara",
  "domain": "tax",
  "version": "1.1.0",
  "publisher": {
    "name": "Avalara",
    "url": "https://developer.avalara.com/",
    "support": "https://developer.avalara.com/"
  },
  "dependencies": {}
}
```

> **Important:** The `version` and `domain` fields in `commerce-app.json` must match the corresponding entry in the App Registry root manifest (`commerce-apps-manifest/manifest.json`). A mismatch causes CI validation to fail.

## adminComponents.json Schema

`app-configuration/adminComponents.json` is an **optional** file that declares Business Manager admin UI components that the merchant sees after installing the app. The file is a JSON object with a `configuration` array of interactive setting entries. Each entry describes one component rendered in the BM admin UI for the app.

```json
{
  "configuration": [
    /* interactive setting entries */
  ]
}
```

Every entry must be an object with a non-empty `componentKey` (the stable identifier referenced by locale files) and a non-empty string `type`. Other fields like `header` and `description` are free-form and not validated by registry CI.

The currently supported component type is `storefrontComponentVisibility`, which renders one boolean toggle per UI target the app registers — letting the merchant enable or disable each target without touching code. Toggling a target opens a pull request against the merchant's Storefront Next repository to update `target-config.json` accordingly.

![Storefront Component Visibility component in Business Manager](https://developer.salesforce.com/media/b2c-commerce/storefrontComponentVisibility.png)

### Component Object Fields

Every entry under `configuration`:

| Field          | Type   | Required | Description                                                                                                                                                                                                                                                 |
| :------------- | :----- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentKey` | string | Yes      | Unique snake*case identifier (matching `^[a-z]a-z0-9*]\*\$`) for this configuration entry. Stable across versions; referenced by locale files in`app-configuration/translations/`. See [App-shipped string localization](#app-shipped-string-localization). |
| `type`         | string | Yes      | Component type identifier. Registry CI only deep-validates known types (currently `storefrontComponentVisibility`).                                                                                                                                         |

### `storefrontComponentVisibility` Attributes

When a `configuration` entry has `type: "storefrontComponentVisibility"`, it must also declare an `attributes[]` array. Each entry in `attributes[]` describes one toggle row.

| Field          | Type    | Required | Description                                                                                                                                             |
| :------------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`           | string  | Yes      | The `sfcc.*` UI target ID this toggle controls. Must match a target the app registers in `storefront-next/src/extensions/{appName}/target-config.json`. |
| `label`        | string  | Yes      | Label shown next to the toggle in BM. Translatable — see [App-shipped string localization](#app-shipped-string-localization).                           |
| `defaultValue` | boolean | Yes      | Whether the surface area is enabled by default on install.                                                                                              |

> **Note:** The BM admin UI shows toggles only for targets that exist in both `adminComponents.json` and the merchant's storefront repo `target-config.json`. Targets declared here but not registered in the storefront appear as unavailable in the UI until the storefront is updated.

> **Cache TTL:** Business Manager caches the toggle values it reads from the merchant's Storefront Next `target-config.json` for **30 seconds**. After a merchant merges a storefront PR that flips a toggle value, allow up to 30 seconds before the new value is reflected in the `storefrontComponentVisibility` component.

> **Production environments:** Surface area toggle changes are not allowed on production environments. Merchants must make toggle changes on a non-production instance and promote them by merging the resulting storefront PR and redeploying the storefront to production MRT.

> **Gating:** The `storefrontComponentVisibility` component is hidden in Business Manager until the merchant completes the "Merge Storefront PR" task in the app's configuration task list. Until that task is marked complete, the toggle UI does not render.

### Example

```json
{
  "configuration": [
    {
      "componentKey": "component_visibility",
      "type": "storefrontComponentVisibility",
      "header": "Component Visibility",
      "description": "Control where the component appears on the storefront.",
      "attributes": [
        {
          "id": "sfcc.checkout.shippingAddress.after",
          "label": "Show on Checkout",
          "defaultValue": true
        },
        {
          "id": "sfcc.orderSummary.adjustments",
          "label": "Show on Order Summary",
          "defaultValue": false
        }
      ]
    }
  ]
}
```

### CI Validation

Registry CI validates `adminComponents.json` on every PR that changes a CAP. The file must be a valid JSON object. The `configuration` key, when present, must be an array. Every entry must declare a non-empty string `componentKey` matching `^[a-z][a-z0-9_]*$`, unique within the file, and a non-empty string `type`. Every entry whose `type` is `"storefrontComponentVisibility"` must also declare a non-empty `attributes[]` array. Each attribute has a non-empty string `id`, a non-empty string `label`, and a boolean `defaultValue`. The file is optional — omit it if the app doesn't need merchant-toggled component visibility.

## App-shipped string localization

Two `app-configuration/` artifacts ship strings that Business Manager renders to merchants:

- `tasksList.json` — the post-install "Complete your setup" checklist. Translatable fields: `name`, `description`.
- `adminComponents.json` (optional) — admin-rendered components such as `storefrontComponentVisibility` toggle rows. Translatable fields: `attributes[].label` on each `configuration[]` entry.

By default, both files ship literal English. To render strings in additional locales, ship locale files alongside the source artifact under `app-configuration/translations/`.

### Stable keys: `taskKey` and `componentKey`

Locale files reference tasks and admin components by stable keys, not array index. Every entry in `tasksList.json` must declare a unique non-empty `taskKey`, and every entry in `adminComponents.json` `configuration[]` must declare a unique non-empty `componentKey`:

| Key            | Where                                                     | Format                           | Uniqueness      |
| :------------- | :-------------------------------------------------------- | :------------------------------- | :-------------- |
| `taskKey`      | each task in `tasksList.json`                             | `^[a-z][a-z0-9_]*$` (snake_case) | Within the file |
| `componentKey` | each entry in `configuration[]` of `adminComponents.json` | `^[a-z][a-z0-9_]*$` (snake_case) | Within the file |

Once shipped, a key is the stable identifier for that task or component across versions. Avoid renaming.

### `app-configuration/translations/<locale>.json`

Ship one file per locale under `app-configuration/translations/`:

```
commerce-{appName}-app-v{version}/
└── app-configuration/
    ├── tasksList.json
    ├── adminComponents.json     (optional)
    └── translations/
        ├── en-US.json           # required if translations/ exists
        ├── de.json
        ├── ja.json
        └── ...
```

Each locale file uses two reserved top-level namespaces — `tasks` and `adminComponents` — keyed by `taskKey` and `componentKey` respectively. Include the namespace only if the corresponding artifact is present.

```json
{
  "tasks": {
    "verify_service_credentials": {
      "name": "Avalara-Dienstanmeldedaten überprüfen",
      "description": "Bestätigen Sie, dass die Avalara-Dienstanmeldedaten korrekt konfiguriert sind."
    }
  },
  "adminComponents": {
    "component_visibility": {
      "attributes": {
        "sfcc.checkout.shippingAddress.after": { "label": "Beim Checkout anzeigen" }
      }
    }
  }
}
```

Rules:

- The top-level `tasks` and `adminComponents` keys are reserved by the registry. Don't introduce sibling keys.
- `tasks.<taskKey>.name` and `tasks.<taskKey>.description` are both required and must be non-empty for every task listed.
- `adminComponents.<componentKey>.attributes.<id>.label` is required and must be non-empty for every (componentKey, attribute id) pair listed.
- `en-US.json` is required when `translations/` exists. It defines the canonical key set every other locale file must match exactly — no extra keys, no missing keys, in either namespace.
- The English text in `en-US.json` and the literal English in `tasksList.json` / `adminComponents.json` must stay in sync.

### Fallback chain

At render time the BM client requests a locale; the registry resolves each translatable string in this order:

1. `translations/<requested-locale>.json`
2. `translations/en-US.json`
3. literal English from the source artifact:
   - tasks → `name` / `description` on the task itself in `tasksList.json`
   - admin component attribute labels → `label` on the attribute in `adminComponents.json`

An app that omits `translations/` entirely keeps rendering literal English in every locale (no behavior change). An app that ships only `en-US.json` renders the same strings in every locale, but is wired up to add more locales later.

### Locale rollout

`en-US` is required at submission when `translations/` is present. Additional locales are optional and can be added incrementally as your localization team produces them.

> **Heads up:** translation files are bundled inside the CAP zip and merged into the persisted task list at install time. Adding or updating translations after the fact requires shipping a new app version and having merchants upgrade — there is no out-of-band path for the registry to push translation updates to an already-installed app.

### Supported locales

Locale filenames are validated against the set of locales supported by Business Manager:

| Locale                  | Filename     |
| :---------------------- | :----------- |
| Arabic (Morocco)        | `ar_MA.json` |
| German                  | `de.json`    |
| English (United States) | `en-US.json` |
| Spanish                 | `es.json`    |
| French                  | `fr.json`    |
| Italian                 | `it.json`    |
| Japanese                | `ja.json`    |
| Korean                  | `ko.json`    |
| Dutch                   | `nl.json`    |
| Polish                  | `pl.json`    |
| Portuguese              | `pt.json`    |
| Chinese (Simplified)    | `zh_CN.json` |
| Chinese (Traditional)   | `zh_TW.json` |

CI rejects locale files whose filenames are outside this set.

### CI validation

Registry CI validates app-shipped strings on every PR that changes a CAP:

- Every `tasksList.json` entry has a non-empty `taskKey` matching `^[a-z][a-z0-9_]*$`, unique within the file.
- Every `adminComponents.json` `configuration[]` entry has a non-empty `componentKey` matching `^[a-z][a-z0-9_]*$`, unique within the file.
- When `app-configuration/translations/` exists:
  - `en-US.json` is present.
  - Every locale filename is in the supported set.
  - Every locale file has the expected shape under `tasks` and (when present) `adminComponents`.
  - Every `taskKey` from `tasksList.json` and every (`componentKey`, attribute `id`) pair from `adminComponents.json` appears in `en-US.json`.
  - Every non-default locale file lists exactly the same keys as `en-US.json` in both namespaces — no extras, no missing.

## adminComponents.json Schema

`app-configuration/adminComponents.json` is an **optional** file that declares Business Manager admin UI components that the merchant sees after installing the app. The file is a JSON object with a `configuration` array of interactive setting entries. Each entry describes one component rendered in the BM admin UI for the app.

```json
{
  "configuration": [ /* interactive setting entries */ ]
}
```

Every entry must be an object with a non-empty `componentKey` (the stable identifier referenced by locale files) and a non-empty string `type`. Other fields like `header` and `description` are free-form and not validated by registry CI.

The currently supported component type is `storefrontComponentVisibility`, which renders one boolean toggle per UI target the app registers — letting the merchant enable or disable each target without touching code. Toggling a target opens a pull request against the merchant's Storefront Next repository to update `target-config.json` accordingly.

![Storefront Component Visibility component in Business Manager](https://developer.salesforce.com/media/b2c-commerce/storefrontComponentVisibility.png)

### Component Object Fields

Every entry under `configuration`:

| Field          | Type   | Required | Description                                                                                                                                                                                  |
| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `componentKey` | string | Yes      | Unique snake_case identifier (matching `^[a-z][a-z0-9_]*$`) for this configuration entry. Stable across versions; referenced by locale files in `app-configuration/translations/`. See [App-shipped string localization](#app-shipped-string-localization). |
| `type`         | string | Yes      | Component type identifier. Registry CI only deep-validates known types (currently `storefrontComponentVisibility`).                                                                          |

### `storefrontComponentVisibility` Attributes

When a `configuration` entry has `type: "storefrontComponentVisibility"`, it must also declare an `attributes[]` array. Each entry in `attributes[]` describes one toggle row.

| Field          | Type    | Required | Description                                                                                                                                                                  |
| :------------- | :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | string  | Yes      | The `sfcc.*` UI target ID this toggle controls. Must match a target the app registers in `storefront-next/src/extensions/{appName}/target-config.json`.                      |
| `label`        | string  | Yes      | Label shown next to the toggle in BM. Translatable — see [App-shipped string localization](#app-shipped-string-localization).                                                |
| `defaultValue` | boolean | Yes      | Whether the surface area is enabled by default on install.                                                                                                                   |

> **Note:** The BM admin UI shows toggles only for targets that exist in both `adminComponents.json` and the merchant's storefront repo `target-config.json`. Targets declared here but not registered in the storefront appear as unavailable in the UI until the storefront is updated.

> **Cache TTL:** Business Manager caches the toggle values it reads from the merchant's Storefront Next `target-config.json` for **30 seconds**. After a merchant merges a storefront PR that flips a toggle value, allow up to 30 seconds before the new value is reflected in the `storefrontComponentVisibility` component.

> **Production environments:** Surface area toggle changes are not allowed on production environments. Merchants must make toggle changes on a non-production instance and promote them by merging the resulting storefront PR and redeploying the storefront to production MRT.

> **Gating:** The `storefrontComponentVisibility` component is hidden in Business Manager until the merchant completes the "Merge Storefront PR" task in the app's configuration task list. Until that task is marked complete, the toggle UI does not render.

### Example

```json
{
  "configuration": [
    {
      "componentKey": "component_visibility",
      "type": "storefrontComponentVisibility",
      "header": "Component Visibility",
      "description": "Control where the component appears on the storefront.",
      "attributes": [
        {
          "id": "sfcc.checkout.shippingAddress.after",
          "label": "Show on Checkout",
          "defaultValue": true
        },
        {
          "id": "sfcc.orderSummary.adjustments",
          "label": "Show on Order Summary",
          "defaultValue": false
        }
      ]
    }
  ]
}
```

### CI Validation

Registry CI validates `adminComponents.json` on every PR that changes a CAP. The file must be a valid JSON object. The `configuration` key, when present, must be an array. Every entry must declare a non-empty string `componentKey` matching `^[a-z][a-z0-9_]*$`, unique within the file, and a non-empty string `type`. Every entry whose `type` is `"storefrontComponentVisibility"` must declare a non-empty `attributes[]` array where each attribute has a non-empty string `id`, a non-empty string `label`, and a boolean `defaultValue`. The file is optional — omit it if the app does not need merchant-toggled component visibility.

## App-shipped string localization

Two `app-configuration/` artifacts ship strings that Business Manager renders to merchants:

- `tasksList.json` — the post-install "Complete your setup" checklist. Translatable fields: `name`, `description`.
- `adminComponents.json` (optional) — admin-rendered components such as `storefrontComponentVisibility` toggle rows. Translatable fields: `attributes[].label` on each `configuration[]` entry.

By default, both files ship literal English. To render strings in additional locales, ship locale files alongside the source artifact under `app-configuration/translations/`.

### Stable keys: `taskKey` and `componentKey`

Locale files reference tasks and admin components by stable keys, not array index. Every entry in `tasksList.json` must declare a unique non-empty `taskKey`, and every entry in `adminComponents.json` `configuration[]` must declare a unique non-empty `componentKey`:

| Key            | Where                                  | Format             | Uniqueness                |
| :------------- | :------------------------------------- | :----------------- | :------------------------ |
| `taskKey`      | each task in `tasksList.json`          | `^[a-z][a-z0-9_]*$` (snake_case) | Within the file |
| `componentKey` | each entry in `configuration[]` of `adminComponents.json` | `^[a-z][a-z0-9_]*$` (snake_case) | Within the file |

Once shipped, a key is the stable identifier for that task or component across versions. Avoid renaming.

### `app-configuration/translations/<locale>.json`

Ship one file per locale under `app-configuration/translations/`:

```
commerce-{appName}-app-v{version}/
└── app-configuration/
    ├── tasksList.json
    ├── adminComponents.json     (optional)
    └── translations/
        ├── en-US.json           # required if translations/ exists
        ├── de.json
        ├── ja.json
        └── ...
```

Each locale file uses two reserved top-level namespaces — `tasks` and `adminComponents` — keyed by `taskKey` and `componentKey` respectively. Include the namespace only if the corresponding artifact is present.

```json
{
  "tasks": {
    "verify_service_credentials": {
      "name": "Avalara-Dienstanmeldedaten überprüfen",
      "description": "Bestätigen Sie, dass die Avalara-Dienstanmeldedaten korrekt konfiguriert sind."
    }
  },
  "adminComponents": {
    "component_visibility": {
      "attributes": {
        "sfcc.checkout.shippingAddress.after": { "label": "Beim Checkout anzeigen" }
      }
    }
  }
}
```

Rules:

- The top-level `tasks` and `adminComponents` keys are reserved by the registry. Don't introduce sibling keys.
- `tasks.<taskKey>.name` and `tasks.<taskKey>.description` are both required and must be non-empty for every task listed.
- `adminComponents.<componentKey>.attributes.<id>.label` is required and must be non-empty for every (componentKey, attribute id) pair listed.
- `en-US.json` is required when `translations/` exists. It defines the canonical key set every other locale file must match exactly — no extra keys, no missing keys, in either namespace.
- The English text in `en-US.json` and the literal English in `tasksList.json` / `adminComponents.json` must stay in sync.

### Fallback chain

At render time the BM client requests a locale; the registry resolves each translatable string in this order:

1. `translations/<requested-locale>.json`
2. `translations/en-US.json`
3. literal English from the source artifact:
   - tasks → `name` / `description` on the task itself in `tasksList.json`
   - admin component attribute labels → `label` on the attribute in `adminComponents.json`

An app that omits `translations/` entirely keeps rendering literal English in every locale (no behavior change). An app that ships only `en-US.json` renders the same strings in every locale, but is wired up to add more locales later.

### Locale rollout

`en-US` is required at submission when `translations/` is present. Additional locales are optional and can be added incrementally as your localization team produces them.

> **Heads up:** translation files are bundled inside the CAP zip and merged into the persisted task list at install time. Adding or updating translations after the fact requires shipping a new app version and having merchants upgrade — there is no out-of-band path for the registry to push translation updates to an already-installed app.

### Supported locales

Locale filenames are validated against the set of locales supported by Business Manager:

| Locale | Filename |
| :-- | :-- |
| Arabic (Morocco) | `ar_MA.json` |
| German | `de.json` |
| English (United States) | `en-US.json` |
| Spanish | `es.json` |
| French | `fr.json` |
| Italian | `it.json` |
| Japanese | `ja.json` |
| Korean | `ko.json` |
| Dutch | `nl.json` |
| Polish | `pl.json` |
| Portuguese | `pt.json` |
| Chinese (Simplified) | `zh_CN.json` |
| Chinese (Traditional) | `zh_TW.json` |

CI rejects locale files whose filenames are outside this set.

### CI validation

Registry CI validates app-shipped strings on every PR that changes a CAP:

- Every `tasksList.json` entry has a non-empty `taskKey` matching `^[a-z][a-z0-9_]*$`, unique within the file.
- Every `adminComponents.json` `configuration[]` entry has a non-empty `componentKey` matching `^[a-z][a-z0-9_]*$`, unique within the file.
- When `app-configuration/translations/` exists:
  - `en-US.json` is present.
  - Every locale filename is in the supported set.
  - Every locale file has the expected shape under `tasks` and (when present) `adminComponents`.
  - Every `taskKey` from `tasksList.json` and every (`componentKey`, attribute `id`) pair from `adminComponents.json` appears in `en-US.json`.
  - Every non-default locale file lists exactly the same keys as `en-US.json` in both namespaces — no extras, no missing.

## APIs

The following APIs support Commerce App lifecycle management:

### Install/Uninstall Jobs (OCAPI Data API)

Commerce App installation and uninstallation are driven by system jobs. The B2C CLI uses OCAPI for these operations and WebDAV for package upload or download. See [CLI Authentication Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/development-environment.md#cli-authentication-setup). The following examples describe the direct OCAPI requests.

**Base URL:** `/s/-/dw/data/v{version}/jobs/{job_id}/executions`

**Install Job ID:** `sfcc-install-commerce-app`

**Uninstall Job ID:** `sfcc-uninstall-commerce-app`

Jobs are triggered via `POST` to the executions endpoint with parameters in the request body. The B2C CLI handles this automatically, but the underlying API can also be called directly.

#### Required OCAPI Permissions

Your API client must have the following OCAPI Data API resources configured in Business Manager (**Administration** > **Site Development** > **Open Commerce API Settings**):

```json
[
  {
    "resource_id": "/jobs/*/executions",
    "methods": ["post"],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
  },
  {
    "resource_id": "/jobs/*/executions/*",
    "methods": ["get"],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
  },
  {
    "resource_id": "/job_execution_search",
    "methods": ["post"],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
  },
  {
    "resource_id": "/sites",
    "methods": ["get"],
    "read_attributes": "(**)",
    "write_attributes": "(**)"
  }
]
```

The `/sites` permission is required when `cap list` or `cap pull` discovers sites because `--site-id` is omitted. For a complete OCAPI configuration example, see the [B2C CLI Authentication Guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/authentication.html#ocapi-configuration).

> **Note:** `cap install` also requires WebDAV access in addition to OCAPI. See [Development Environment Setup — WebDAV Access](/docs/commerce/b2c-commerce/guide/development-environment.md#webdav-access).

#### Install Job Parameters

| Parameter          | Type    | Required | Description                                                                                                          |
| :----------------- | :------ | :------- | :------------------------------------------------------------------------------------------------------------------- |
| `app_name`         | string  | Yes      | App ID, such as `avalara-tax`. The CLI reads it from `commerce-app.json`; direct job callers supply it.              |
| `app_source`       | string  | Yes      | Source of the CAP archive: `WebDAV` or `AppRegistry`                                                                 |
| `app_domain`       | string  | Yes      | Recognized commerce domain, such as `tax`, `shipping`, or `fraud`. The CLI reads it from `commerce-app.json`; direct job callers supply it. |
| `site_id`          | string  | Yes      | The target site ID, prefixed with `Sites-` (for example, `Sites-RefArch`)                                            |
| `app_path`         | string  | Conditional | WebDAV path to the uploaded archive, such as `webdav/Sites/Impex/my-app.zip`. **Required** when `app_source` is `WebDAV`. |
| `app_version_id`   | string  | No       | Specific version ID to install; resolved from the registry for `AppRegistry` installs if omitted                     |
| `should_create_pr` | boolean | No       | Whether to attempt a GitHub PR for eligible Storefront Next or cartridge content (default: `false`)                  |

**Example request:**

```json
POST /s/-/dw/data/v25_6/jobs/sfcc-install-commerce-app/executions
{
  "app_name": "avalara-tax",
  "app_source": "WebDAV",
  "app_domain": "tax",
  "site_id": "Sites-RefArch",
  "app_path": "webdav/Sites/Impex/commerce-apps/avalara-tax-v0.2.5.zip"
}
```

> **Note:** When using the B2C CLI (`b2c cap install`), the CLI handles packaging, WebDAV upload, and job execution automatically. Direct API callers must upload the CAP first and pass its WebDAV path as `app_path`.

#### Uninstall Job Parameters

| Parameter    | Type   | Description                                                               |
| :----------- | :----- | :------------------------------------------------------------------------ |
| `app_name`   | string | The app ID to uninstall, such as `avalara-tax`                            |
| `app_domain` | string | The commerce domain, such as `tax`, `shipping`, or `fraud`                |
| `site_id`    | string | The target site ID, prefixed with `Sites-` (for example, `Sites-RefArch`) |

**Example request:**

```json
POST /s/-/dw/data/v25_6/jobs/sfcc-uninstall-commerce-app/executions
{
  "app_name": "avalara-tax",
  "app_domain": "tax",
  "site_id": "Sites-RefArch"
}
```

### Job Execution Response

Both install and uninstall jobs return a standard OCAPI job execution object. The CLI polls the execution status until the job completes or fails. Key response fields:

| Field              | Type   | Description                                       |
| :----------------- | :----- | :------------------------------------------------ |
| `id`               | string | Execution ID for polling status                   |
| `execution_status` | string | `running`, `finished`, `aborted`                  |
| `exit_status.code` | string | Exit code on completion, such as `ok` or `error`  |
| `duration`         | number | Execution duration in milliseconds                |
| `log_file_name`    | string | Path to the job log file (retrievable via WebDAV) |

## CommerceFeatureState Data Model

The `CommerceFeatureState` system object tracks installation and configuration status for each Commerce App per site.

| Field                | Type     | Description                                                                                             |
| :------------------- | :------- | :------------------------------------------------------------------------------------------------------ |
| StateId              | varchar  | Unique identifier for this installation record                                                          |
| SiteId               | varchar  | The site this feature state applies to                                                                  |
| FeatureType          | varchar  | `ISV_APP`, `NATIVE_APP`, `NATIVE_FEATURE`, `CUSTOM_FEATURE`, or `CUSTOM_APP`                             |
| FeatureName          | varchar  | Display name of the app, such as Avalara Tax App                                                        |
| FeatureSource        | varchar  | `AppRegistry` or `WebDAV`                                                                               |
| FeatureVersionId     | varchar  | Installed version, such as 1.0.0                                                                        |
| FeatureDomain        | varchar  | Domain category, such as Tax                                                                            |
| InstallStatus        | varchar  | `INSTALLING`, `INSTALLED`, `INSTALL_FAILED`, `UNINSTALLING`, `UNINSTALLED`, `UNINSTALL_FAILED`          |
| ConfigStatus         | varchar  | `NOT_CONFIGURED`, `CONFIGURING`, `CONFIGURED`, `CONFIGURATION_FAILED`                                   |
| ConfigTasks          | JSON     | Array of setup tasks with status                                                                        |
| InstallationMetadata | JSON     | Job ID, execution ID, cartridge names (`foldersAdded`), log file path, error message, storefront PR URL |
| CreatedAt            | datetime | When the installation record was created                                                                |
| UpdatedAt            | datetime | When the record was last updated                                                                        |
| InstalledAt          | datetime | Timestamp of successful installation                                                                    |
| UninstalledAt        | datetime | Timestamp of uninstallation (if applicable)                                                             |
| ConfiguredAt         | datetime | Timestamp of configuration completion                                                                   |
| UnconfiguredAt       | datetime | Timestamp of configuration being cleared (if applicable)                                                |

### FeatureType Values

For App Registry installs (`AppSource=AppRegistry`), `FeatureType` is derived from the `type` and `provider` fields in the manifest:

| Manifest `type` | Manifest `provider` | FeatureType      | Description                                           |
| :-------------- | :------------------ | :--------------- | :---------------------------------------------------- |
| `app`           | `thirdParty`        | `ISV_APP`        | Third-party ISV Commerce App                          |
| `app`           | `salesforce`        | `NATIVE_APP`     | Salesforce-built Commerce App                         |
| `feature`       | `salesforce`        | `NATIVE_FEATURE` | Native platform feature (for example, Flat Tax)       |
| `feature`       | `custom`            | `CUSTOM_FEATURE` | Customer-customizable feature                         |
| `custom`        | `custom`            | `CUSTOM_FEATURE` | Custom provider placeholder (for example, Custom Tax) |

WebDAV installation doesn't require a manifest entry. The install job forces `FeatureType` to `CUSTOM_APP` and persists `FeatureSource=WebDAV`, even if the supplied domain and app ID happen to match an existing registry entry. See [Develop a Private Commerce App](/docs/commerce/b2c-commerce/guide/private-commerce-apps.md).

### Multi-Site Behavior

The `CommerceFeatureState` record is **per-site**. A single app can be installed on multiple sites within the same realm. Key multi-site behaviors:

- **Cartridge copying:** The install job copies cartridges to the active code version on the first site install. Subsequent site installs skip the copy if the cartridges already exist in the active code version.
- **Cartridge path:** Each site gets its own cartridge path entry, managed independently.
- **IMPEX processing:** Install IMPEX runs for every site install. Uninstall IMPEX only runs when the last site uninstalls the app, because services, jobs, and custom object definitions are instance-scoped resources shared across all sites.
- **Cartridge file deletion:** Cartridge files are only deleted from the active code version when the last site uninstalls the app.

## Feature Toggle Prerequisites

Enable the feature toggles required by your app before installation. When the supplied app ID and domain match a registry entry, the job checks its `requiredFeatureToggle`, when present, and stops if that toggle is disabled. The installer doesn't enable prerequisite toggles. Validation of hook-bearing packages can also add remediation tasks for disabled hook prerequisites.

> **Note:** Beginning with B2C Commerce 26.10, Multiple Tax Levels is generally available to all merchants and doesn't require a tax Commerce App or a merchant-facing toggle. If you set tax items using [`LineItem.setTaxes()`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItem.html) and [`LineItemTax`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.order.LineItemTax.html), you don't need a tax Commerce App to use Multiple Tax Levels.

## Install and Uninstall Flow Details

### Install Flow

The install job (`sfcc-install-commerce-app`) executes these steps in order:

1. **Feature toggle check:** Verifies `CommerceAppsEnabled` is enabled on the instance.
2. **Source-specific validation:**
   - **`AppRegistry`:** Checks that the app name and domain exist in the App Registry manifest.
   - **`WebDAV`:** Skips the per-app name check so unregistered apps can install. Canonicalizes `app_domain` against known registry domains. An unknown domain stops installation before state is created. `AppPath` is required; the job reads the CAP from that WebDAV path. Feature type is set to `CUSTOM_APP`.
3. **Idempotency check:** If the app is already installed on this site, the job skips installation and returns success. If cartridges are missing from the active code version (for example, after a code version switch), the job re-copies them without re-running IMPEX.
4. **Resolve site, library, and code version:** Validates the target site exists, resolves the site's content library ID (for `LIBRARYID` placeholder), and locates the active code version.
5. **Write `INSTALLING` state.**
6. **Resolve and unzip CAP:** Resolves the uploaded WebDAV archive or downloads and verifies the App Registry archive, then extracts it to a temporary directory.
7. **Validate package configuration:** Parses `tasksList.json`, validates optional `adminComponents.json`, and reads optional display metadata and translations.
8. **Copy cartridges:** Copies `site_cartridges/` and `bm_cartridges/` to the active code version directory. Skips copying if the app is already installed on another site and the cartridges are already present.
9. **Update cartridge paths:** Prepends site cartridges to the site's cartridge path and adds BM cartridges to the Business Manager cartridge path.
10. **Process install IMPEX:** Replaces `SITEID` and `LIBRARYID` placeholders, zips the processed files, and executes a Site Import in merge mode.
11. **Serialize uninstall IMPEX:** Persists the contents of `impex/uninstall/` into the `CommerceFeatureState` record so they're available at uninstall time (the CAP isn't needed for uninstall).
12. **Validate integration requirements:** Runs connection-health, compatibility, and extension checks. Some checks add warning or remediation tasks instead of failing installation.
13. **Create storefront PR (optional):** If eligible Storefront Next or cartridge content is present and `should_create_pr` is `true`, attempts a GitHub PR against the merchant's Storefront Next repository. A successful PR prepends a "Merge Storefront PR" task. A PR failure adds a warning task and doesn't fail installation.
14. **Run post-install validation and write `INSTALLED` state.**

Fatal failures after installation state is created write `INSTALL_FAILED` and trigger cleanup. Early source-validation failures occur before state creation, and warning-oriented validation or storefront PR failures don't fail installation.

### Uninstall Flow

The uninstall job (`sfcc-uninstall-commerce-app`) executes these steps:

1. **Feature toggle check:** Verifies `CommerceAppsEnabled` is enabled.
2. **Idempotency check:** Verifies the app is currently installed on the target site and no uninstall is already in progress.
3. **Read persisted state:** Reads installed cartridge names and serialized uninstall IMPEX data from the `CommerceFeatureState` record **before** writing the `UNINSTALLING` state (which overwrites some metadata fields).
4. **Write `UNINSTALLING` state.**
5. **Remove cartridges from paths:** Removes site cartridges from the site's path and BM cartridges from the BM path. On partial failure, attempts to restore the site cartridge path.
6. **Delete cartridge files (last site only):** If this is the last site using the app, deletes the cartridge directories from the active code version.
7. **Process uninstall IMPEX (last site only):** Reconstructs the uninstall IMPEX files from persisted state, replaces placeholders, and executes a Site Import in merge mode. This step is intentionally ordered last because it's irreversible.
8. **Write `UNINSTALLED` state.**

> **Important:** The uninstall job does **not** require access to the original CAP archive. All data needed for uninstall is read from the `CommerceFeatureState` record that was persisted during installation.

## App Registry Manifest

The App Registry uses a root manifest (`commerce-apps-manifest/manifest.json`) to define all available apps. The manifest organizes apps by domain, with each domain containing an array of app entries.

### Manifest Entry Fields

| Field              | Type   | Required      | Description                                                 |
| :----------------- | :----- | :------------ | :---------------------------------------------------------- |
| `id`               | string | Yes           | App identifier in kebab-case                                |
| `name`             | string | Yes           | Display name                                                |
| `description`      | string | Yes           | App description                                             |
| `iconName`         | string | Yes           | Icon filename (for example, `avalara.png`)                  |
| `domain`           | string | Yes           | Commerce domain                                             |
| `type`             | string | Yes           | `app`, `feature`, or `custom`                               |
| `provider`         | string | Yes           | `thirdParty`, `salesforce`, or `custom`                     |
| `version`          | string | Apps only     | Semantic version of the current release                     |
| `zip`              | string | Apps only     | ZIP filename (for example, `avalara-tax-v1.1.0.zip`)        |
| `sha256`           | string | Apps only     | SHA256 hash of the ZIP file for integrity verification      |
| `configurationUrl` | string | Features only | Business Manager deep link for native feature configuration |

### Entry Types

The manifest supports three entry types:

- **`app`** (ISV or Salesforce apps): Installable Commerce App Packages with `version`, `zip`, and `sha256` fields. These go through the full CAP install flow.
- **`feature`** (native platform features): Built-in features like Flat Tax or Basic Shipping that are configured directly in Business Manager via a `configurationUrl`. No CAP install is needed.
- **`custom`** (custom provider placeholders): Placeholders that let merchants configure their own custom integrations. No CAP install is needed.

### Hub Display

Provider domains (`tax`, `payment`, `shipping`) appear under "Providers" in the Cart & Checkout Hub. All other domains appear under "Additional Setup". Multiple entries within the same domain appear as provider options under a single hub tile.

### Manifest and Catalog Cache TTL

Business Manager caches the App Registry `manifest.json` and per-app `catalog.json` responses for **15 minutes**. After a registry PR merges that adds a new app or publishes a new version, allow up to 15 minutes before it appears in the Cart & Checkout Hub of an existing Business Manager session. Starting a new BM session does not bypass the cache — the TTL is per-instance, not per-session.

## Known Limitations

The following limitations apply to Commerce Apps:

### Storefront compatibility

- Commerce Apps are designed **exclusively for Storefront Next**. SiteGenesis and SFRA storefronts aren't supported.
- SiteGenesis cartridges (`sitegenesis_storefront_controllers`, `sitegenesis_storefront_core`) and SFRA cartridges (`app_storefront_base`) override the `dw.order.calculate` hook, which bypasses Commerce App tax hook selection entirely. These cartridges must be removed from the site's cartridge path before installing a tax Commerce App.
- Hybrid setups (Storefront Next with SiteGenesis/SFRA cartridges still on the path) produce unpredictable behavior for Commerce App extension points.

### Extension points

- Only **Tax** extension points (`sfcc.app.tax.calculate`, `sfcc.app.tax.commit`, `sfcc.app.tax.cancel`) are live in the initial release. Shipping, Fraud, and other adapter interface extension points arrive in the second half of 2026.
- Only one Commerce App can be the active provider for a given domain per site. Installing a second tax app on the same site overwrites the first.
- Legacy hooks (`dw.order.calculateTax`) and Commerce App extension points are mutually exclusive per site. When `TaxAppHooksEnabled` is active, the platform calls the registered Commerce App hook instead of the legacy hook.

### Installation and upgrades

- **No in-place upgrades.** To update to a new version, merchants must uninstall the old version and install the new one. Automated version upgrades are planned for Wave 3.
- **No rollback mechanism.** After uninstalling, there is no one-click way to restore the previous version. Merchants must re-install the desired version.

### Multi-site

- Cartridge files are shared across sites at the code version level. You can't run different versions of the same Commerce App on different sites within the same realm.
- Instance-scoped resources (service definitions, custom object type definitions) are shared across all sites. Uninstall IMPEX only runs when the last site uninstalls the app.

### Storefront Next extensions

- Extensions are incorporated via a GitHub Pull Request at install time. The merchant must manually merge the PR and rebuild their storefront.
- There is no automated mechanism to remove storefront extension code on uninstall. Merchants must manually remove the extension files from their Storefront Next repository.

## Connection Health Check

The connection health check is an optional extension point that a Commerce App uses to report whether its external dependency is reachable. Business Manager calls the hook when a merchant views the app details page or manually refreshes the connection status, and shows the result as a health badge on the app's Cart & Checkout Hub tile.

### Extension Point

| Extension point name | Exported function | Return type |
| :--- | :--- | :--- |
| `sfcc.app.<domain>.checkConnectionHealth` | `checkConnectionHealth` | `dw.system.Status` or `null` |

The hook is registered per app domain — for example, `sfcc.app.tax.checkConnectionHealth` for a tax app, `sfcc.app.shipping.checkConnectionHealth` for a shipping app.

### Status Interpretation

| Returned Status | Health state |
| :--- | :--- |
| `Status.OK` (any code) | Healthy |
| `Status.ERROR` with code `DEGRADED` | Degraded |
| `Status.ERROR` with any other code (including `UNHEALTHY`) | Unhealthy |
| `null` return, exception thrown, or CPU timeout | Unknown |

### Status Detail Keys

These detail keys are recognized by the Business Manager health indicator UI when attached via `status.addDetail(key, value)`:

| Key | Type | Description |
| :--- | :--- | :--- |
| `message` | string | Brief human-readable description of the current connection state. Surfaced verbatim in Business Manager. |
| `remediation` | string | Actionable steps the merchant can take to resolve a degraded or unhealthy state. Surfaced verbatim in Business Manager. |

These keys are defined as constants on the `dw.commerceapps.ConnectionHealthStatusCodes` Script API class:

- `ConnectionHealthStatusCodes.DETAIL_MESSAGE`
- `ConnectionHealthStatusCodes.DETAIL_REMEDIATION`

### Localization

The hook executes in the Business Manager session locale context. To provide translated `message` and `remediation` strings, use `dw.web.Resource.msg()` or `dw.web.Resource.msgf()` with resource bundles under `cartridge/templates/resources/` in your cartridge. If you hard-code English strings, they flow through to the UI unchanged regardless of the admin's locale.

### Timeout Behavior

The platform applies a CPU timeout to the hook execution. If the hook exceeds this timeout, the platform treats the result as `null` and shows an "Unknown" health badge. Keep implementations lightweight — prefer a simple health or ping endpoint over complex validation logic.

### Availability

- **Applies to:** All Commerce App types (UI-only, Backend-only, Fullstack)
- **Required:** No. Apps that don't depend on an external connection can omit the hook entirely. The Cart & Checkout Hub tile doesn't show a health badge.
- **Script API reference:** `dw.commerceapps.hooks.ConnectionHealthCheckHooks`, `dw.commerceapps.ConnectionHealthStatusCodes`

## External Documentation Links

- [B2C CLI Documentation](https://salesforcecommercecloud.github.io/b2c-developer-tooling/)
- [B2C Commerce API Documentation](https://developer.salesforce.com/docs/commerce/commerce-api/overview)
- [SCAPI Getting Started](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-get-started.html)
- [Web Services in B2C Commerce](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html)

## Glossary

- **CAP (Commerce App Package):** The standardized `.zip` archive containing all artifacts for a Commerce App.

- **Extension Point:** A platform-defined interface, such as `sfcc.app.tax.calculate`, where ISV logic can be injected.

- **Hook:** The script implementation that fulfills an extension point contract.

- **UI Target:** A named set of feature components in Storefront Next that can be injected at build time.

- **Extension:** An independently toggleable UI plugin feature containing one or more UI targets and associated components.

- **App Registry:** The [centralized GitHub repository](https://github.com/SalesforceCommerceCloud/commerce-apps) hosting certified Commerce App packages.

- **CommerceFeatureState:** The system object tracking installation and configuration status per-site.

- **SCAPI:** Salesforce Commerce API, the RESTful API layer for Commerce Cloud.

- **OCAPI:** Open Commerce API, the Data API used for job execution and Business Manager operations.

- **Storefront Next (Odyssey):** The React-based storefront framework for Commerce Cloud.

- **BFF (Backend for Frontend):** The pattern where a custom SCAPI serves as the intermediary between ISV front-end components and ISV back-end services.

- **[B2C CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md#run-the-b2c-cli):** The command-line interface for B2C Commerce development and operations, including Commerce App lifecycle management.

- **Manifest:** The root `manifest.json` file in the App Registry that defines all available Commerce Apps, native features, and custom provider placeholders.

<!-- document id=019a26733d364606e497729eef06347f7813ae6cf16fd7df0582d173ffcd2a34 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-register.md -->

# Register

### Overview

The Register page provides a self-service buyer registration experience for new storefront users. The registration flow captures buyer information such as:

- First name
- Last name
- Email address
- Password
- Password confirmation

After successful registration, the buyer is associated with the webstore’s buyer group and can access authenticated storefront experiences.

<!--As with the Login flow, Salesforce Commerce supports multiple registration implementation patterns. The reference React storefront implementation uses Option 1 for buyer registration and session establishment.

This flow demonstrates how a headless storefront can orchestrate buyer registration experiences, including account creation and user onboarding workflows.

![Register Flow](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-section-figure-image-33-1.png '{"class": "image-lg", "title": "Register Flow"}')-->

## See Also

- [_B2B Commerce Developer Guide_: Implement Custom Self-Registration for a B2B Store](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-custom-self-registration.html)
- [_Apex Developer Guide_: Introducing Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_intro.htm)

<!-- document id=52d3043be39846bb82267872322a3f5d2fb62d788114203421f6fcda2f769b7f url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-passwordless-login-registration.md -->

# Register a Customer with Passwordless Login

Starting with B2C Commerce version 26.1, the passwordless login flow supports customer registration. By passing additional parameters in the authorization request and validating a time-based one-time password (TOTP), create a B2C Commerce customer profile without requiring a password.

## Overview

To understand how passwordless login with registration works, let’s look at an overview of the process.

![SLAS passwordless login flow with customer registration](https://developer.salesforce.com/docs/media/commerce-api/slas-passwordless-login-registration.png '{"class": "image-xl"}')

1. The shopper requests a passwordless login and registers as a new customer. Your app calls the [authorizePasswordlessCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizePasswordlessCustomer) endpoint and provides a callback URI.
2. SLAS makes an HTTP POST request to your callback URI, including the shopper’s contact information and an eight-digit TOTP.
3. The app sends the TOTP to the shopper over email, SMS, or another mechanism.
4. The shopper provides the TOTP to the app either by clicking a link or entering it manually. Your app calls the [getPasswordLessAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getPasswordLessAccessToken) endpoint to authenticate the shopper.
5. After successful validation of the `pwdless_login_token` (TOTP), or `login_id + pwdless_login_token`, SLAS requests a new customer profile.
6. B2C Commerce creates the new customer profile.
7. SLAS returns the access and refresh tokens. The access token can be used to make authorized requests on behalf of the shopper.

## Configure Passwordless Login with Registration

To implement passwordless login with customer registration, first authorize the customer and then validate the TOTP.

### 1. Authorize the Passwordless Customer with Registration

Call the [`authorizePasswordlessCustomer`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizePasswordlessCustomer) endpoint with the `register_customer` query parameter set to `true`. For customer registration, the request body requires the additional parameters `email` (unless the `user_id` parameter already provides an email) and `last_name`. The `phone_number`, `first_name`, and `customer_no` parameters are optional, but recommended if available.

```text
#!/bin/bash
set -euo pipefail

# Update these values with your configuration:
CODE='qw1ert23'
ORG='f_ecom_abcd_001'
CLIENT='my-slas-private-client-id'
SECRET='my-slas-private-client-secret'
SITE='my-ecom-site'
CALLBACK='https://www.example.com/my-callback-url?secret=open-sesame' LOGIN='testuser@salesforce.com'

BASE="https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG"
curl "$BASE/oauth2/passwordless/login?register_customer=true" \
    --user "$CLIENT:$SECRET" \
    --data "channel_id=$SITE" \
    --data 'mode=callback' \
    --data "callback_uri=$CALLBACK" \
    --data-urlencode "login_id=$LOGIN" \
    --data 'last_name=User' \
    --data 'email=testuser@salesforce.com' \
    --data 'first_name=Test' \
    --data 'phone_number=+10001112222'
    --data 'customer_no=CC147852963'
```

As described in the [passwordless login flow without registration](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html#passwordless-login-implementation), SLAS then makes an HTTP POST request to the specified callback URI. The JSON payload includes a TOTP to send to the shopper.

**important:** The B2C Commerce customer profile isn't created by the call to authorizePasswordlessCustomer. After you call the authorizePasswordlessCustomer endpoint, exchange the TOTP from the callback for an access token (step 2) to complete registration.

### 2. Validate the TOTP and Create Customer Profile

To register the customer, call the `[getPasswordLessAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getPasswordLessAccessToken)` endpoint. This call exchanges the TOTP for an access token.

```sh
curl --location 'https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/passwordless/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "login_id=$LOGIN" \
--data-urlencode 'hint=pwdless_login' \
--data-urlencode 'pwdless_login_token=12345678'
```

The optional `login_id` parameter is used for stronger validation using `login_id` + `pwdless_login_token` (TOTP).

After successful validation of the `pwdless_login_token` (TOTP) or `login_id` + `pwdless_login_token`, SLAS makes a request to create the customer profile in B2C Commerce. The B2C Commerce response includes the new customer profile. Then, SLAS creates the access token (Shopper JWT).

<!-- document id=31c538967e2c17f65133301e84b61f4694549bfc7652385740f3e7fd5fbca0b4 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/rn_b2b_d2c_comms.md -->

Release Notes

# Release Notes

## Release Notes

This section covers the latest updates and changes to the Commerce APIs defined through the OpenAPI specification. For updates on other Salesforce Commerce API types, see the Salesforce Commerce Release Notes.

### Behavior Changes

#### Get Localized Order Status Values in the Order Summary Collection API

The [Order Summary Collection API](https://developer.salesforce.com/docs/platform/connect-rest-api/references/connect-rest-api-commerce#tag/Commerce-B2B-Resources/operation/getOrderSummaryLookup) returns the `status` field in the field map localized to the shopper's language, including the Pending and Failed values.

**Note:** This change takes effect in the Spring '27 release. This advance notice gives you time to prepare your integrations beforehand.

Previously, the `status` field always returned in English, even when a shopper changed their language. If your integration parses or matches on the literal English `status` value, update it to handle localized values before the Spring '27 release.

#### Get Consistent Amount Values from the Order Summary Lookup API for Gross Tax Stores

For stores that use the Gross tax type, the [Order Summary Lookup API](https://developer.salesforce.com/docs/platform/connect-rest-api/references/connect-rest-api-commerce#tag/Commerce-B2B-Resources/operation/getOrderSummaryLookup) returns the same amount values whether the response is backed by the order summary or the cart.

Review any integration or storefront logic that relies on these Order Summary Lookup API amount fields for gross tax:

*   [OrderSummary](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_ordersummary.htm): `TotalProductAmount`, `TotalAdjustedDeliveryAmount`, `TotalAmount`, `TotalProductAmountWithTax`, `TotalAdjustedProductAmount`
*   [OrderItemSummary](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_orderitemsummary.htm): `TotalPrice`, `TotalLineAmount`

**Note:** This change takes effect in the Spring '27 release. This advance notice gives you time to prepare your integrations beforehand.

Starting Spring '27, when this API returns a response with a null order ID, these amount fields will reflect corrected, consistent values at parity with responses with a non-null order ID. Confirm your calculations work with these values before the Spring '27 release.

**See Also**

*   [_Salesforce Winter ’27 Release Notes_: Development](https://help.salesforce.com/s/articleView?id=release-notes.rn_development.htm)
*   [_Salesforce Winter ’27 Release Notes_: Commerce](https://help.salesforce.com/s/articleView?id=release-notes.rn_commerce.htm)

<!-- document id=40c44bc3982ef77f00ae16b5d5ce26838ffbbef21ead5c794158eace3f07ad98 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-remote-includes.md -->

# Remote Includes

**important:** Use Remote Includes wisely, especially in combination with caching. Too many cache misses from Remote Includes will negatively affect the system performance. Currently, using more than 50 includes per request triggers a warning. In the future, this limit will be strictly enforced, causing errors. Stay within the threshold to avoid issues. Also, be aware that authentication and authorization are only performed for the main request, but **not** for the include requests.

- The `RestResponseMgr` method `createScapiRemoteInclude()` allows only SCAPI URLs.
- The `RestResponseMgr` method `createStorefrontControllerRemoteInclude()` allows only Controller URLs.

With B2C Commerce 24.2, build your own SCAPI responses and include responses from other sources, such as SCAPI System APIs or other Custom APIs, using Custom API Remote Includes.

**Example:** We create an API endpoint named `includeTest1`. A second API endpoint, `remoteInclude`, obtains the response from the `includeTest1` endpoint and adds it to the `includeArray` array as `includeArrayItem1`.

```javascript
exports.includeTest1 = function() {
  var data = {
    id: "includeTest1",
  };
  dw.system.RESTResponseMgr.createSuccess( data ).render();
}

exports.remoteInclude = function() {
  var includeArrayItem1 =
    dw.system.RESTResponseMgr.
    createScapiRemoteInclude( "custom", "sample", "v1", "includeTest1",
    dw.web.URLParameter( "siteId", "TestWapi" ) );

  var info = {
    id: "test-id",
    includeArray: [includeArrayItem1]
  };

  dw.system.RESTResponseMgr.createSuccess( info ).render();
}
```

**note:** Add multiple remote includes in the array to create complex and powerful responses.

**important:** - The `RestResponseMgr` method `createScapiRemoteInclude()` allows only SCAPI URLs.
- The `RestResponseMgr` method `createStorefrontControllerRemoteInclude()` allows only Controller URLs.

Cross-API requests (for example, including a Controller response within a Custom API or SCAPI hook) are not possible.

For additional information and examples, see [RemoteInclude](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_RemoteInclude.html) and [Passing Data Between Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#pass-data-between-hooks)

<!-- document id=930e5607c6cdb90f8ee2c368fd153ce10330c5d11fd8581d5579cd1fd2c0402c url=/developer/current/en-us/commerce-cloud/commerce-api/guides/remote-includes.md -->

# Remote Includes

**important:** Use Remote Includes wisely, especially in combination with caching. Too many cache misses from Remote Includes will negatively affect the system performance. Also, be aware that authentication and authorization are only performed for the main request, but **not** for the include requests.

With B2C Commerce 25.1, extend API responses by including responses from other sources using Remote Includes.

Include a response from a SCAPI [Custom API](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html) or [System API](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html), for example to provide additional product details.

**Example 1:** The hook `dw.ocapi.shop.product.modifyGETResponse` is used to customize the product response. A Custom API endpoint, `remoteInclude`, delivers a sample which is added to the product with the custom property `c_remote`.

```javascript
exports.remoteInclude = function() {
  var info = {
    id: "test-id"
  };
  dw.system.RESTResponseMgr.createSuccess(info).render();
}
```

```javascript
exports.modifyGETResponse = function(scriptProduct, doc) {
  var include = dw.system.RESTResponseMgr.createScapiRemoteInclude('custom', 'my-api', 'v1', 'remoteInclude');
    doc.c_remote = {
      value: [ include ]
    };
}
```

**Example 2:** The hook `dw.ocapi.shop.product.modifyGETResponse` is used to customize the product response. It is enhanced with promotion data which is added to the product with the custom property `c_remote`.

```javascript
exports.modifyGETResponse = function(scriptProduct, doc) {
  var include = dw.system.RESTResponseMgr.createScapiRemoteInclude('pricing', 'shopper-promotions', 'v1', 'promotions', dw.web.URLParameter("siteId", "MySite"), dw.web.URLParameter("ids", "my-first-promotion,my-second-promotion"));
    doc.c_remote = {
      value: [ include ]
    };
}
```

**note:** Add multiple remote includes in the array to create complex and powerful responses.

**important:** - The `RestResponseMgr` method `createScapiRemoteInclude()` allows only SCAPI URLs.
- The `RestResponseMgr` method `createStorefrontControllerRemoteInclude()` allows only Controller URLs.

Cross-API requests (for example, including a Controller response within a Custom API or SCAPI hook) are not possible.

For additional information and examples, see [RemoteInclude](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_RemoteInclude.html) and [Passing Data Between Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#pass-data-between-hooks)

<!-- document id=21f4c885c54c86238b57404c49e45f37699b4f89e7254403f4de6c0911efd0ba url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-rename-file-ds.md -->

# RenameFile.ds

Review the RenameFile.ds referenced script files when scheduling inventory imports.

**note:** This code is provided as a sample. It isn't a supported part of the SiteGenesis application.

```
/**
 * Moves a file to another directory.
 *
 * @input SourceFileName  : String   		the file to move
 * @input TargetFileName  : String   		the file to move
 * @input SourceDirectory : dw.io.File   		the processing directory where the file is located
 * @input TargetDirectory : dw.io.File   		the target processing directory
 * @input sampleLogger    : Object Sample logger	input for Sample logger
 * @input Status  	  : dw.system.Status 	The stautus of the DW import pipelet
 * @output TargetFile	  : dw.io.File
 * @output sampleLogger   : Object Sample logger	debug output for Sample logger
 * @output sampleError 	  : Object Sample error	error output for Sample logger
 */
importPackage(dw.system);
importPackage(dw.io);



importScript("bc_sample:library/impex/libImpExConstants.ds");
// Sample Logging ImportScript
importScript("bc_sample:library/common/libContext.ds");
importScript("bc_sample:library/utility/exception/libsampleException.ds");
importScript("bc_sample:library/utility/logging/libLog.ds");



function execute(pdict: PipelineDictionary): Number {
    // Sample Logging var
    var _context: String = new Context("RenameFile.ds");
    var _logger: Log = Log.getLogger(pdict);



    var sourceFileName: String = pdict.SourceFileName;
    var targetFileName: String = pdict.TargetFileName;
    var sourceDirectory: String = pdict.SourceDirectory;
    var targetDirectory: String = pdict.TargetDirectory;
    var status: String = pdict.Status;

    var sourceFile: File = new File(sourceDirectory, sourceFileName);
    var targetFile: File = new File(targetDirectory, targetFileName);

    if (status != null) {
        _logger.error(_context, "Status :" + status.message + " : End Status");
    }


    if (!sourceFile.exists()) {
        _logger.error(_context, "Source file '" + sourceFile.name + "' in path '" + sourceFile.path + "' cannot be found");
        return PIPELET_ERROR;
    }
    if (targetFile.exists()) {
        _logger.warn(_context, "Target file '" + targetFile.name + "' in path '" + targetFile.path + "' already exists. Overwriting it.");
    }

    _logger.info(_context, "Moving file " + sourceFile.name + " to " + targetFile.name);

    try {
        sourceFile.renameTo(targetFile);
        pdict.TargetFile = targetFile;



    } catch (e) {
        var exception: sampleException = new sampleException(_context, "Failed moving file " + sourceFileName, e);
        _logger.error(_context, "Failed moving file " + sourceFileName + exception);
        pdict.sampleError = exception;

        return PIPELET_ERROR;
    }

    return PIPELET_NEXT;
}
```

<!-- document id=54efc935ec3858bd90c54fd92c7e12591ba2531889dba7dfb265f3e821bd6f91 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/rendering.md -->

# Rendering

The PWA Kit architecture builds on React’s rendering system, adding features that benefit both users and developers. This architecture guide takes a closer look at these features of PWA Kit’s rendering system and how they work. Special attention is given to the parts of the PWA Kit React SDK and the Retail React App that come together to power each feature.

## Server-Side Rendering

To create a favorable first impression, the first page that a user requests from your storefront must be loaded as fast as possible. But first page requests demand more rendering time than subsequent page requests. Every component on the page must be rendered, not just the ones that need updating. For the critical first page load, we use server-side rendering because it offers a powerful tool for optimizing performance: caching.

Managed Runtime’s CDN cache can store a previously rendered version of a page and serve it to the user in an instant. There’s no faster render than one that’s already done!

**tip:** To learn how to boost performance through caching, see our guide to [Maximizing Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.md).

### App Server

The main code for server-side rendering is run inside the app server. The app server is an [Express](https://expressjs.com/) app that handles incoming HTTP requests and calls a function called `render` in response. The app server is defined in `app/ssr.js`.

The `render` function is imported from the PWA Kit React SDK. Helper functions (also from the SDK) create an instance of Express and attach the `render` function to it as an Express [route method](https://expressjs.com/en/guide/routing.html) for all `GET` requests.

## Client-Side Rendering

After the first page load, rendering duties are transferred from the server side to the client side through a process called [hydration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Hydration_(web_development)>). During hydration, your React app starts running in the user’s browser. Event handlers spring into action to respond to user input. Page elements are rendered as needed and as directed by the user input in client-side rendering. This more efficient and user directed rendering enables the fluid experience that React is famous for.

The PWA Kit architecture works behind the scenes to make the transition from server-side rendering to client-side rendering as smooth as possible. For example, all your components are preloaded with all the props they need, even props that were the result of API requests. During server-side rendering, these props are serialized and embedded into the page source so that they can be used during hydration.

### Isomorphic Code

Because the same code is rendered in both server-side and client-side environments, it must be [isomorphic](https://medium.com/airbnb-engineering/isomorphic-javascript-the-future-of-web-apps-10882b7a2ebc). Isomorphic JavaScript (also known as universal JavaScript) is code that doesn’t rely on direct access to any code construct that is only available in one runtime environment or another. When a construct isn’t available in both environments, you must add conditional code around it to make sure that it’s available in the current environment.

The following table lists some commonly used constructs that must be used with conditional code:

| Construct         | Description                  | Availability     |
| :---------------- | :--------------------------- | :--------------- |
| `window.location` | Current URL from the browser | Client-side only |
| `req`             | HTTP request from Express    | Server-side only |
| `res`             | HTTP response from Express   | Server-side only |

To determine whether rendering is happening on the client side or the server side, check for the presence of the `window` object. The following example uses this technique to render a price only on the client side:

```javascript
<div>
  {/* The price is only rendered on the client side,
   * because it changes frequently */}
  {typeof window != 'undefined' && <p>Price: ${price}</p>}
</div>
```

**note:** Some content, such as personalized or frequently changing content, must _only_ be rendered on the client side to get the best possible performance. See our guide to [Maximizing Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.md) for more information.

## Correlation ID

The PWA Kit rendering system provides a correlation ID (in [UUID v4 format](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)>)) on each page. The correlation ID can be used to match requests and responses from PWA Kit to activity in other systems, such as the B2C Commerce API.

On the server side, the correlation ID is set to the value of `requestId` in the Managed Runtime infrastructure’s API gateway. On the client side, a UUID is generated with each page navigation using the `randomUUID()` method of the built-in Web Crypto API.

To get the correlation ID in your PWA Kit application import the `useCorrelationId` hook:

```javascript
import {useCorrelationId} from 'pwa-kit-react-sdk/ssr/universal/hooks'

const AppConfig = ({children}) => {
  const {correlationId} = useCorrelationId()
  return <div>{children}</div>
}
```

You can forward the correlation ID from PWA Kit to the B2C Commerce API via the `correlation-x` header. In the response, the forwarded correlation ID is returned in the `x-correlation-id` header, combined with an internal ID from the API.

To learn more about using correlation ID with the B2C Commerce API, see [Investigate by Correlation ID](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id).

## Next Steps

Get a deeper understanding of rendering by reviewing the source code in `app/ssr.js`. It contains important app server settings, such as the default cache lifetime for pages.

As you read through the PWA Kit documentation, don’t miss the architecture guide for [The Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md).

<!-- document id=76ef9e2c618aca98fc5a4821cc635ef15fa58a3a0e08d464c8b09698c92e9b5e url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/replications.md -->

Replications

# Replications

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/replications/replications-oas-v1-public.yaml)

## API Overview

The Replications API provides tools for managing content replication and synchronization across your Commerce Cloud instance. Use this API to control replication throughout your commerce infrastructure.

The API currently supports:

*   Granular Replication: Publishing individual items

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

This API uses OAuth 2.0 authentication via Account Manager (AmOAuth2). You must include the relevant scope(s) in the client ID used to generate the token. For details, see the [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

*   `sfcc.granular-replications.rw` - Enables the triggering of publish processes and access to details about publish processes, for example: monitoring purposes.
*   `sfcc.granular-replications` - Enables access to details about publish processes, for example: monitoring purposes.

For detailed setup instructions, see the [Authorization for Admin APIs guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Granular Replication

The granular replication feature addresses the need to make small updates to existing content in production on an as-needed basis. You can make granular data updates for these three replication groups:

*   Products: Update specific products from staging to production.
*   Price Books: Update specific price table entries from staging to production.
*   Content Assets: Update specific content assets from staging to production. Page Designer pages replicate as content assets with all their components.

Granular Replication is meant to complement and enhance existing data replications, not replace it.

All granular replication related endpoints are available using:

```
https://{shortCode}.api.commercecloud.salesforce.com/operation/replications/v1/organizations/{organizationId}/granular-processes
```

##### Publish Items (POST /granular-processes)

Queues an item, such as products, price tables, and content assets, for the upcoming publish operation.

:::note The published price table is always the table with the continuously valid period. :::

##### List Publish Processes (GET /granular-processes)

Retrieve a list of all publish processes with pagination support.

##### Get Publish Process (GET /granular-processes/{id})

Retrieve details of a specific publish process using its ID.

#### Publish Process Lifecycle

All publish processes follow this lifecycle:

1.  `queued`: Publish process initiated and waiting for publish operation to run.
2.  `in_progress`: Publish operation is running.
3.  `completed`: Publish operation completed and the item was successfully published.
4.  `failed`: The publish operation completed, but an error was detected.

**Version:** 1.0.8

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/operation/replications/v1`
    *   `shortCode (default 123456gf) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope c\_example: custom scopes must start with c\_ used for custom APIs \[MAX length of scope 49 characters\]
    *   Scope sfcc.example: standard salesforce commerce apis scopes must start with "sfcc.". Without suffix ".rw" scopes grants READONLY access. \[MAX length of scope 49 characters\]
    *   Scope sfcc.example.rw: salesforce commerce apis scopes must start with "sfcc.". The suffix ".rw" scopes grants READ and WRITE access. \[MAX length of scope 49 characters\]
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope c\_example: custom scopes mus start with c\_ used for custom APIs \[MAX length of scope 49 characters\]
    *   Scope sfcc.example: standard salesforce commerce apis scopes must start with "sfcc.". Without suffix ".rw" scopes grants READONLY access. \[MAX length of scope 49 characters\]
    *   Scope sfcc.example.rw: salesforce commerce apis scopes must start with "sfcc.". The suffix ".rw" scopes grants READ and WRITE access. \[MAX length of scope 49 characters\]

## Operations

### GET Retrieve a list of all publish processes with pagination support.

`GET /organizations/{organizationId}/granular-processes`

Operation ID: `listPublishProcesses`. Security: AmOAuth2 (sfcc.granular-replications, sfcc.granular-replications.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50.  
    Default: `50`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Retrieved list of publish processes successfully.
    
    Media type: `application/json`. Schema: `PublishProcessListResponse`.
    
    _Example: listResults_ List results example
    
    ```
    {
      "total": 3,
      "offset": 0,
      "limit": 50,
      "data": [
        {
          "id": "xmRhi7394HymoeRkfwAAAZeg3WiM",
          "status": "completed",
          "startTime": "2024-03-15T10:30:00Z",
          "endTime": "2024-03-15T10:30:45Z",
          "initiatedBy": "user@example.com",
          "productItem": {
            "productId": "PROD-12345"
          }
        },
        {
          "id": "xmRhi7394HymoeRkfwAAAZeg3WiN",
          "status": "completed",
          "startTime": "2024-03-15T10:35:00Z",
          "endTime": "2024-03-15T10:35:30Z",
          "initiatedBy": "user@example.com",
          "productItem": {
            "productId": "PROD-67890"
          }
        },
        {
          "id": "xmRhi7394HymoeRkfwAAAZeg3WiK",
          "status": "failed",
          "startTime": "2024-03-15T10:40:00Z",
          "initiatedBy": "api-client-xyz",
          "contentAssetItem": {
            "contentId": "homepage-hero-banner",
            "type": "shared",
            "libraryId": "sharedLibrary"
          }
        }
      ]
    }
    ```
    
*   **400** Bad Request. Invalid query parameter.
    
    Media type: `application/problem+json`. Schema: `InvalidQueryParameterErrorResponse`.
    
    _Example: InvalidQueryParameterErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-query-parameter",
      "detail": "Invalid query parameter.",
      "title": "Invalid Query Parameter"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don't have the required permissions to access the resource, or the Granular Replication feature is disabled.
    
    Media type: `application/problem+json`. Schema: `FeatureNotEnabledErrorResponse`.
    
    _Example: FeatureNotEnabledErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/feature-not-enabled",
      "detail": "The Granular Replication feature is not enabled in your staging and production environments.",
      "title": "Feature Not Enabled"
    }
    ```
    
*   **422** If the request was not sent to a staging instance
    
    Media type: `application/problem+json`. Schema: `NotOnStagingInstanceErrorResponse`.
    
    _Example: NotOnStagingInstanceErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-on-staging-instance",
      "detail": "The request was not sent to a staging instance.",
      "title": "Not On Staging Instance"
    }
    ```
    

### POST Queue items for the upcoming publish operation.

`POST /organizations/{organizationId}/granular-processes`

Operation ID: `publishItems`. Security: AmOAuth2 (sfcc.granular-replications.rw).

Queues items, such as a products, price tables, and content assets, for the upcoming publish operation. You can have multiple items in the queue, but you must send a separate request for each item. Page Designer (PD) pages are replicated as content assets, including all their components. Note: The published price table is always the table with the continuously valid period.

### Publishing Limit

You can queue a maximum of 500 items for a single publish operation. Because each request queues one item, this limit applies to the total number of items queued for the upcoming publish operation across all requests, not to an individual API call. The HTTP status code 409 (Conflict) is returned if the limit is exceeded.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PublishItemRequest`.

_Example: productExample_ Publish a product

Example of publishing a product

```
{
  "product": {
    "productId": "PROD-12345"
  }
}
```

_Example: priceTableExample_ Publish a price table

Example of publishing a price table for a product. Note: The published price table is always the one with the continuously valid period.

```
{
  "priceTable": {
    "productId": "PROD-67890",
    "priceBookId": "USD-Retail-2024"
  }
}
```

_Example: contentAssetExampleSharedLib_ Publish a content asset from a shared library

```
{
  "contentAsset": {
    "contentId": "homepage-hero-banner",
    "type": "shared",
    "libraryId": "mySharedLibrary"
  }
}
```

_Example: contentAssetExamplePrivateLib_ Publish a content asset from a site's private library

Publish a content asset from a site's private library.

```
{
  "contentAsset": {
    "contentId": "homepage-hero-banner",
    "type": "private",
    "siteId": "mySiteID"
  }
}
```

#### Responses

*   **200** ID of the publish process
    
    Media type: `application/json`. Schema: `PublishIdResponse`.
    
    _Example: success_ Successfully queued response
    
    ```
    {
      "id": "xmRhi7394HymoeRkfwAAAZeg3WiM"
    }
    ```
    
*   **400** Bad Request. The request is malformed or contains invalid data.
    
    Media type: `application/problem+json`. Schema: `InvalidRequestBodyErrorResponse`.
    
    _Example: InvalidRequestBodyErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-request-body",
      "detail": "Invalid request body. Must provide valid properties for either a product, price table, or content asset.",
      "title": "Invalid Request Body"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don't have the required permissions to access the resource, or the Granular Replication feature is disabled.
    
    Media type: `application/problem+json`. Schema: `FeatureNotEnabledErrorResponse`.
    
    _Example FeatureNotEnabledErrorResponseExample: same as GET /organizations/{organizationId}/granular-processes 403 response._
    
*   **404** The specified item was not found.
    
    Media type: `application/problem+json`. Schema: `ItemNotFoundErrorResponse`.
    
    _Example: ItemNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/item-not-found",
      "detail": "The specified item was not found.",
      "title": "Item Not Found"
    }
    ```
    
*   **409** The item could not get queued for the upcoming publish operation.
    
    Media type: `application/problem+json`. Schema: `AlreadyQueuedErrorResponse | TooManyQueuedErrorResponse | ReplicationRunningErrorResponse`.
    
    One of: `AlreadyQueuedErrorResponse`, `TooManyQueuedErrorResponse`, `ReplicationRunningErrorResponse`.
    
    _Example: AlreadyQueuedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/already-queued",
      "detail": "The item was already queued for the upcoming publish operation.",
      "title": "Already Queued"
    }
    ```
    
    _Example: TooManyQueuedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/too-many-queued",
      "detail": "The maximum number of items queued for the upcoming publish operation has been exceeded.",
      "title": "Too Many Queued"
    }
    ```
    
    _Example: ReplicationRunningErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/replication-running",
      "detail": "A replication is running. Granular Replication is not possible during a running replication.",
      "title": "Replication Running"
    }
    ```
    
*   **422** The item could not get processed.
    
    Media type: `application/problem+json`. Schema: `FeedBasedPriceBookNotSupportedErrorResponse | NotOnStagingInstanceErrorResponse`.
    
    One of: `FeedBasedPriceBookNotSupportedErrorResponse`, `NotOnStagingInstanceErrorResponse`.
    
    _Example NotOnStagingInstanceErrorResponseExample: same as GET /organizations/{organizationId}/granular-processes 422 response._
    
    _Example: FeedBasedPriceBookNotSupportedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/feed-based-price-book-not-supported",
      "detail": "The price table belongs to a feed based price book. Feed based price books are not supported.",
      "title": "Feed Based Price Book Not Supported"
    }
    ```
    

### GET Retrieve details of a specific publish process using its ID.

`GET /organizations/{organizationId}/granular-processes/{id}`

Operation ID: `getPublishProcess`. Security: AmOAuth2 (sfcc.granular-replications, sfcc.granular-replications.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, id, required) Publish process ID of the published item.

#### Responses

*   **200** Publish process details retrieved successfully.
    
    Media type: `application/json`. Schema: `PublishProcessResponse`.
    
    _Example: productProcess_ Product publish process
    
    ```
    {
      "id": "xmRhi7394HymoeRkfwAAAZeg3WiM",
      "status": "completed",
      "startTime": "2024-03-15T10:30:00Z",
      "endTime": "2024-03-15T10:30:45Z",
      "initiatedBy": "user@example.com",
      "productItem": {
        "productId": "PROD-12345"
      }
    }
    ```
    
    _Example: priceTableProcess_ Price table publish process; Note: The published price table is always the one with the continuously valid period.
    
    ```
    {
      "id": "xmRhi7394HymoeRkfwAAAZeg3WiN",
      "status": "completed",
      "startTime": "2024-03-15T10:35:00Z",
      "endTime": "2024-03-15T10:35:30Z",
      "initiatedBy": "1af8e314-60c7-46f0-b7b4-c88aecd3449d",
      "priceTableItem": {
        "productId": "PROD-67890",
        "priceBookId": "USD-Retail-2024"
      }
    }
    ```
    
    _Example: contentAssetProcess_ Content asset publish process
    
    ```
    {
      "id": "xmRhi7394HymoeRkfwAAAZeg3Wik",
      "status": "in_progress",
      "startTime": "2024-03-15T10:40:00Z",
      "initiatedBy": "api-client-xyz",
      "contentAssetItem": {
        "contentId": "homepage-hero-banner",
        "siteId": "mySiteId",
        "type": "private"
      }
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don't have the required permissions to access the resource, or the Granular Replication feature is disabled.
    
    Media type: `application/problem+json`. Schema: `FeatureNotEnabledErrorResponse`.
    
    _Example FeatureNotEnabledErrorResponseExample: same as GET /organizations/{organizationId}/granular-processes 403 response._
    
*   **404** The publish process for given ID was not found.
    
    Media type: `application/problem+json`. Schema: `PublishProcessNotFoundErrorResponse`.
    
    _Example: PublishProcessNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/publish-process-not-found",
      "detail": "Publish process with ID 'xmRhi7394HymoeRkfwAAAZeg3WiM' was not found.",
      "title": "Publish Process Not Found"
    }
    ```
    
*   **422** If the request was not sent to a staging instance
    
    Media type: `application/problem+json`. Schema: `NotOnStagingInstanceErrorResponse`.
    
    _Example NotOnStagingInstanceErrorResponseExample: same as GET /organizations/{organizationId}/granular-processes 422 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### PublishProcessListResponse

Paginated list of publish processes

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of PublishProcessResponse_, required) Array of publish processes

### InvalidQueryParameterErrorResponse

Returned when an invalid query parameter is provided.

Includes all fields of `ErrorResponse`.

### FeatureNotEnabledErrorResponse

Returned when the Granular Replication feature is disabled.

Includes all fields of `ErrorResponse`.

### NotOnStagingInstanceErrorResponse

Returned when the request is sent to a non-staging instance.

Includes all fields of `ErrorResponse`.

### PublishItemRequest

One of: `ProductPublishRequest`, `PriceTablePublishRequest`, `ContentAssetPublishRequest`.

### PublishIdResponse

Item successfully queued for publishing

*   `id` (_id_, required)

### InvalidRequestBodyErrorResponse

Returned when the request body is malformed or contains invalid data.

Includes all fields of `ErrorResponse`.

### ItemNotFoundErrorResponse

Returned when the specified item (product, price table, or content asset) was not found.

Includes all fields of `ErrorResponse`.

### AlreadyQueuedErrorResponse

Returned when attempting to queue an item that is already queued.

Includes all fields of `ErrorResponse`.

### TooManyQueuedErrorResponse

Returned when the maximum number of items (50) queued for publish has been exceeded.

Includes all fields of `ErrorResponse`.

### ReplicationRunningErrorResponse

Returned when attempting to queue items while a replication is running.

Includes all fields of `ErrorResponse`.

### FeedBasedPriceBookNotSupportedErrorResponse

Returned when attempting to publish a price table from a feed-based price book.

Includes all fields of `ErrorResponse`.

### id

Publish process ID of the published item

Type: `string`.

Maximum length: 28. Example: `xmRhi7394HymoeRkfwAAAZeg3WiM`.

### PublishProcessResponse

*   `id` (_id_, required)
*   `status` (_string_, required) Current status of the publish process  
    Allowed values: `completed`, `in_progress`, `failed`, `queued`. Example: `completed`.
*   `startTime` (_string (date-time)_, required) Timestamp at which the publish process was started  
    Pattern: ^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z$. Example: `2024-03-15T10:30:00Z`.
*   `endTime` (_string (date-time)_) Timestamp at which the publish process was completed (only available if the status is "completed" or "failed")  
    Pattern: ^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{3})?Z$. Example: `2024-03-15T10:30:45Z`.
*   `initiatedBy` (_string_, required) User or ID of the client application that initiated the publish process  
    Maximum length: 256. Example: `user@example.com`.
*   `productItem` (_ProductItem_)
*   `priceTableItem` (_PriceTableItem_)
*   `contentAssetItem` (_ContentAssetItem_)

### PublishProcessNotFoundErrorResponse

Returned when the publish process for given ID was not found.

Includes all fields of `ErrorResponse`.

*   `id` (_id_)

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ProductPublishRequest

*   `product` (_object_, required)
    *   `productId` (_ProductId_, required)

_Example_

```
{
  "product": {
    "productId": "PROD-12345"
  }
}
```

### PriceTablePublishRequest

*   `priceTable` (_object_, required)
    *   `productId` (_ProductId_, required)
    *   `priceBookId` (_string_, required) ID of the price book  
        Maximum length: 256. Example: `USD-Retail-2024`.

_Example_

```
{
  "priceTable": {
    "productId": "PROD-67890",
    "priceBookId": "USD-Retail-2024"
  }
}
```

### ContentAssetPublishRequest

*   `contentAsset` (_ContentAssetItemPrivate | ContentAssetItemShared_, required)
    
    One of: `ContentAssetItemPrivate`, `ContentAssetItemShared`.
    

### ProductItem

Details of the published product (only available if a product was published)

*   `productId` (_ProductId_, required)

### PriceTableItem

Details of the published price table (only available if a price table was published)

*   `productId` (_ProductId_, required)
*   `priceBookId` (_string_, required) ID of the price book  
    Maximum length: 256. Example: `USD-Retail-2024`.

### ContentAssetItem

One of: `ContentAssetItemPrivate`, `ContentAssetItemShared`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### ContentAssetItemPrivate

Details of the published content asset (only available if a content asset was published). Page Designer pages replicate as content assets, including all their components.

*   `contentId` (_string_, required) ID of the content asset  
    Maximum length: 256. Example: `homepage-hero-banner`.
*   `type` (_string_, required) The type of library (private) from which the content asset originates.  
    Allowed values: `private`. Example: `private`.
*   `siteId` (_SiteId_, required)

_Example_

```
{
  "contentId": "homepage-hero-banner",
  "type": "private",
  "siteId": "mySiteId"
}
```

### ContentAssetItemShared

Details of the published content asset (only available if a content asset was published). Page Designer pages replicate as content assets, including all their components.

*   `contentId` (_string_, required) ID of the content asset  
    Maximum length: 256. Example: `homepage-hero-banner`.
*   `type` (_string_, required) The type of library (shared) from which the content asset originates.  
    Allowed values: `shared`. Example: `shared`.
*   `libraryId` (_string_, required) Use the library ID.  
    Maximum length: 256. Example: `libraryId`.

_Example_

```
{
  "contentId": "homepage-hero-banner",
  "type": "shared",
  "libraryId": "myLibrary"
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

<!-- document id=036c56d098fbb8283b26a3892b57c366db43e0c41fdba5ee5560dacc09753101 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ops-troubleshooting/b2c-reporting-to-support.md -->

# Reporting to B2C Commerce Support

In some cases, you must contact Platform Support or Solution Support.
When reporting an issue, first determine whether Platform Support or Solution Support is responsible for the specific problem area.
Salesforce provides Platform Support for the B2C Commerce product as part of your subscription. Platform Support does not normally cover custom solutions built on top of B2C Commerce, unless you have a specific Solution Support contract with Salesforce. Implementation partners typically support their own custom solutions.
If you suspect the issue is specific to the B2C Commerce product, follow these steps:

1. Identify the simplest scenario to cause the issue, preferably in or on top of the Reference Application.
2. Record the steps that produce the problem.
3. Collect any relevant log files.
4. Log into Salesforce and open a case in the [Salesforce Help portal](https://help.salesforce.com/s/).

<!-- document id=49d2d1bb79fb034b69c949708b64d789a31d9dd314b8f1e8d244fff4745cb916 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/reports-and-dashboards.md -->

# Reports & Dashboards

With [B2C Commerce Reports & Dashboards](https://help.salesforce.com/s/articleView?id=cc.b2c_reports_and_dashboards.htm&type=5), you can identify trends over time and make smarter business decisions based on your B2C Commerce data. View data on order conversion metrics, site traffic, frequently searched products, and more. This guide explains how to configure and verify Reports & Dashboards to use with your Progressive Web App (PWA) Kit site.

## Prerequisites

To use Reports & Dashboards:

- Open a support case asking Salesforce Customer Support to [enable Einstein Activities](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-activities-overview.html#business-manager-configuration). If you're migrating from an existing Storefront Reference Architecture (SFRA) site ([hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-implementation.md) or otherwise), you should time this step to coincide with your Composable Storefront launch to preserve your existing SFRA reporting.
- Have the Reports and Dashboards user role in [Account Manager](https://account.demandware.com/) with the scopes of the permission set to the environments in your [realm](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide). If you don’t have this role, ask your Account Manager administrator to assign it to you. See [Managing Account Manager for Salesforce B2C Commerce Users](https://help.salesforce.com/s/articleView?id=000391212&type=1).

**note:** Unless otherwise stated, all of the points in this guide apply to sites built 100% with [Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) (PWA Kit) or with a [phased headless rollout](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html).

## Configure Reports & Dashboards

After completing the [prerequisites](#prerequisites), configure Reports & Dashboards by following these steps.

### 1. Configure Business Manager

- Enable access to Einstein API endpoints. See [Enable Access](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-activities-overview.html#enable-access).
- Configure your B2C Commerce instance to use Einstein Activities for analytics. See [Business Manager Configuration](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-activities-overview.html#business-manager-configuration).

### 2. Update SFRA to Use the Einstein Activities API

**Phased headless rollout only:** Complete the steps in [Einstein Activities for Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/einstein-activities-for-phased-headless-rollouts.html).

### 3. Configure Your PWA Kit Settings

In your PWA Kit project, go to `template-retail-react-app/config/default.js` and set the properties as follows.

- **`host`**: Almost always set to the Einstein production instance `api.cquotient.com`. If you want to use a proxy, you can set this property to a value such as `/mobify/proxy/einstein`. See [No Data in Reports & Dashboards after Correct Setup](#pwa-kit-only-no-data-in-reports--dashboards-after-correct-configuration).

- **`einsteinId`**: Your Einstein API key that you received when you [configured Business Manager](#1-configure-business-manager).
- **`siteId`**: Use the format `realm-siteId`. For example, `zzrf-RefArch.`
- **`isProduction`**: Set this property to `true` if the data is from a production MRT environment. Data appears in Reports & Dashboards only if `isProduction`is set to `true`. Set this to `false` if the data isn’t from a production [Managed Runtime (MRT) environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/mrt-overview.html#environments). For example, if you’re working in a development environment.

Replace placeholders in this example with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

```jsx
einsteinAPI: {
    host: 'https://api.cquotient.com',
    einsteinId: '$EINSTEIN_ID',
    siteId: '$SITE_ID',
    isProduction: false
}
```

After you complete the configuration, data appears in Reports & Dashboards in 24 hours. After that, any new data appears in Reports & Dashboards 24 hours after any corresponding event happens.

## Verify When Einstein Activity Events Are Sent

Install the [B2C Commerce Recommendation Validator](https://chrome.google.com/webstore/detail/commerce-cloud-recommenda/dobmbolmcejainkefklnpkjbaibgjihn) Chrome addon to see the activity events that a page sends out.

Alternatively, you can check the network requests in your browser and filter for `api.cquotient.com` requests.

## Verify Your Data

After completing the [prerequisites](#prerequisites) and [configuration](#configure-reports--dashboards), verify your data in Reports & Dashboards. We recommend that you verify your order numbers.

1. Log into Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Merchant tools > _Your Site_ > Analytics > Reports & Dashboards**.
3. Confirm that order numbers on the Home and Sales tabs are what you expect based on the activity on your site.
4. Go to **Traffic > SHOPPER JOURNEY**.
5. Confirm that the Visits With Orders number is what you expect based on the activity on your site. For more granular analysis, you can filter the report by a specific date or date range. See [Set the Dashboard Date Range](https://help.salesforce.com/s/articleView?id=cc.b2c_set_dashboard_daterange.htm&type=5).

![Associated screenshot](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/reports-dashboards2.png)

## Troubleshoot Reports & Dashboards

This section provides suggested solutions for common errors that you can encounter while using Reports & Dashboards.

### No Data Right after Setup

**Potential Cause:** You configured Reports & Dashboards less than 24 hours ago.

**Suggested Solution:** Wait at least 24 hours after completing the [configuration](#configure-reports--dashboards) before you check your Reports & Dashboards.

### Inaccurate or Missing Data 24 hours After Configuration

**Potential Cause:** The prerequisites weren’t met or Reports & Dashboards configuration is incorrect.

**Suggested Solution:** View Einstein Activity API Calls for your site by using the Network tab in DevTools. Optionally, you can also install the [B2C Commerce Recommendation Validator](https://chrome.google.com/webstore/detail/commerce-cloud-recommenda/dobmbolmcejainkefklnpkjbaibgjihn) Chrome addon. These fields appear in the B2C Commerce Recommendation Validator.

- **Realm:** If this field is empty, Reports & Dashboards doesn’t know which realm the data comes from. Ensure that your user role in Account Manager has the scopes of the permission set to the environments in your realm. Confirm that you have the Reports and Dashboards user role in Account Manager with the scopes of the permission set to the environments in your realm. See the [Prerequisites](#prerequisites).
- **instanceType:** If this field isn’t set to `prd`, your data doesn't appear. Set the `isProduction` property to `true` so that `instanceType` is set to `prd`. See [Configure Reports & Dashboards](#configure-reports--dashboards).

### PWA Kit Only: No Data in Reports & Dashboards after Correct Configuration

**Potential Cause:** Adblockers stop requests to the Einstein Activities API.

**Suggested Solution:**

1. Set up a proxy in [Runtime Admin](https://runtime.commercecloud.com/) as described in [Configure Managed Runtime Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.html#configure-managed-runtime-environments).
   - Use the path `mobify/proxy/einstein`.
   - Direct all Einstein requests through that proxy by adding the Einstein API host as `api.cquotient.com`.
2. Setting up a proxy can prevent data from appearing in Reports & Dashboards. That’s because proxy requests previously replaced the User-Agent header with `Amazon Cloudfront`, causing all user agent request strings to appear in Reports & Dashboards as robots instead of real shoppers. As of June 8, 2026, the Managed Runtime proxy preserves the original User-Agent header. This workaround is only needed for storefronts deployed before that date. See [Request and Response Modifications](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md#request-and-response-modifications). To avoid this issue on older deployments, update the Einstein API code in your PWA Kit project to send `clientUserAgent = navigator.userAgent` in the Einstein request.

   In your project, go to `/template-retail-react-app/app/hooks/use-einstein.js` and add this code.

```jsx
if (this.isProduction) {
  body.instanceType = instanceType_prd
} else {
  body.instanceType = instanceType_sbx
}

// This is included in the Einstein request.
body.clientUserAgent = navigator.userAgent

return body
```

**note:** Setting up a proxy can slow down your site performance.

## See Also

- Salesforce _Help_: [Reports & Dashboards](https://help.salesforce.com/s/articleView?id=cc.b2c_reports_and_dashboards.htm&type=5)
- [Data and Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/data-and-analytics.md)

<!-- document id=ba4199776dd0f4732062f6c02f738cfd203e8e533afeea4097fb063ac8f6b358 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_initialize_an_instance.md -->

# Reset a SIG or ODS Instance in Control Center

Reset an instance to initialize it to a clean state. Resetting deletes all data from the database, so reset SIG sandbox and ODS instances, but you can't reset PIG instances. This limitation prevents the accidental deletion of mission-critical data.

To reset a SIG sandbox or ODS instance, you need sufficient permissions.

1. Log into Control Center.
2. Click **Instances**.
3. Search for and select the sandbox instance you want to initialize.
4. Click **Reset**. A confirmation message appears asking if you want to continue.
5. Click **Yes**. Control Center initializes the instance and sends an email with the new temporary password to the email address of the Control Center account.
6. Start the instance, log in with the temporary password, and when prompted, change the password.

<!-- document id=7242c68aa9e51eff460cfe86d410b5572b36b43c5a65c737a89ef16a69e1c848 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/scapi-request-identification.md -->

# Restrict SCAPI Access to Managed Runtime Traffic

Lock down Shopper API requests so that they are accepted only from your Managed Runtime (MRT) environments, closing off the direct-access path that bots and scrapers use to bypass your CDN and MRT and call Shopper endpoints directly. Leave Admin API requests, which use Account Manager credentials, outside the block rule.

**note:** Available starting with B2C Commerce 26.10. Scope the block rule to Shopper API and SLAS paths. During the log phase, find Shopper callers that reach SCAPI without going through MRT, such as a custom BFF or a mobile app. Route those callers through MRT, or add a narrow exclusion for them. Skip the block rule only if neither option is possible. Leave Admin API paths out of the rule. Those calls use Account Manager credentials, including the B2C CLI, and they aren't the bot path this rule closes.


## How It Works

Enabling the **Managed Runtime SCAPI Request Identification** feature switch sets up a SCAPI Identity Header (SIH): a shared secret header that MRT attaches to every request it forwards to SCAPI. SCAPI's [eCDN zone](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones.md) can then tell the difference between a request that genuinely came from your MRT environment and a request sent directly to SCAPI from anywhere else, including a request that spoofs MRT's IP range or user agent.

This header uses the same secret-header pattern that locks down traffic between a CDN and your MRT origin (see [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#access-control-headers) and [Origin Lockdown with Embedded CDN (eCDN)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html)). SIH applies that pattern one hop further downstream, between MRT and SCAPI.

Salesforce generates and rotates the SIH secret automatically. You don't manage or rotate this secret yourself.

## Enable SCAPI Request Identification

1. In Business Manager, enable the **Managed Runtime SCAPI Request Identification** feature switch separately in each instance you want protected — Development, Staging, and Production. Enabling the switch in one instance doesn't enable it in the others; each instance gets its own SIH secret.
2. For each instance where you enable the switch, wait for the setup job to finish provisioning that instance's secret and its rule in the SCAPI eCDN zone. This can take some time to propagate; don't add a block rule for an instance (the next section) until its setup completes.
3. In Business Manager on your **Production** instance, go to **Administration > Sites > Embedded CDN Settings**, select the **SCAPI zone**, and click the **Security Rules** tab. Because the SCAPI zone is shared, you manage rules for all three instances from this one tab. A new Salesforce-managed custom firewall rule appears for each instance where you enabled the switch. Each rule scopes itself to its instance by matching an org-specific segment in the request URL path (for example, `f_ecom_blnd_prd` for Production, `f_ecom_blnd_stg` for Staging, `f_ecom_blnd_dev` for Development), so it only ever allows that instance's MRT traffic. These rules are locked. View them, but don't edit or delete them.

**important:** The SCAPI zone is shared across your Development, Staging, and Production instances, but each instance's allow rule and secret are scoped separately by that org-specific path segment. Enabling the feature switch in Production doesn't protect Development or Staging — enable it separately in each instance you want covered, and scope any block rule you add the same way.


## Block Direct SCAPI Traffic

After an instance's SIH allow rule is in place, add your own custom firewall rule to block direct Shopper API requests for that instance. The rule lives on the SCAPI zone's **Security Rules** tab. That tab is available when SCAPI Zone Visibility is enabled in Business Manager, which is on by default starting with B2C Commerce 26.10. See [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5).

Scope the block rule to the same org-specific path segment as that instance's allow rule, and to Shopper API and SLAS paths. A rule meant for Production then doesn't also match Staging or Development traffic, and Admin API calls stay outside the rule. The Salesforce allow rule stays scoped to the org segment. It lets Managed Runtime traffic through. Admin traffic doesn't need that header when the block rule doesn't match it. Repeat this section for each instance you want to block.

1. On the **Security Rules** tab for the SCAPI zone (managed from your Production instance), create a new custom firewall rule with **URI Path contains `<org-specific segment>`** and **URI Path contains `/shopper`**. Use the same org segment shown in that instance's Salesforce-managed allow rule (for example, `f_ecom_blnd_prd` for Production). `/shopper` matches Shopper API names such as `shopper-products` and the SLAS path `/shopper/auth`. It doesn't match Admin API paths, so Account Manager calls from the B2C CLI, CI, and other admin integrations keep working. A custom Shopper API uses `/custom/<api>/...` and does not contain `/shopper`. To block direct access to one custom endpoint, use the org segment and **URI Path contains `/custom/<api>`** instead of `/shopper`. See [Create a Custom Firewall Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_create_eCDN_firewall_rule.htm&type=5).
2. Start with the `log` action. Leave the rule in `log` for at least one full business cycle, about 1 to 7 days, and include scheduled jobs and peak hours in that window. See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html) for rule expression syntax and available actions.
3. Review the matches in Security Analytics on the SCAPI zone, or in Log Center, by path, user agent, and ASN. See [Analyze HTTP and Security Traffic for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_analyze_eCDN_traffic.htm&type=5). Look for legitimate Shopper API callers that reach SCAPI without going through MRT. Common ones include:

   - Native mobile apps that call SLAS and the Shopper APIs directly
   - Synthetic monitoring of Shopper APIs
   - QA automation against Shopper APIs

   Admin API callers, such as OMS, ERP, and PIM integrations and the B2C CLI, authenticate with Account Manager. They fall outside a rule scoped to `/shopper`, so you don't route them through MRT or exclude them from this rule.

4. For each legitimate Shopper caller, route the traffic through MRT or add a narrow exclusion. Limit an exclusion to a specific path plus a known signal, such as a client ID or a short list of fixed IPs. Excluding a whole IP range or network weakens the rule, the same way a broad IP exemption weakens WAF and rate-limit rules. Skip the block rule only when you can't route the caller through MRT and can't write a narrow exclusion.
5. When the logged matches are traffic you intend to stop, switch the action to `block`. Use `block`. Shopper API callers are API clients and can't complete a Managed Challenge. Don't switch from `log` to `block` during a flash sale, a holiday code freeze, or another peak window. See [Bot Mitigation Best Practices for Flash Sales](https://developer.salesforce.com/docs/commerce/solutions/guide/bot-mitigation-sk.html) and [Traffic Management for Flash Sales](https://developer.salesforce.com/docs/commerce/solutions/guide/traffic-management-sk.html). Then drag the rule into place directly after that instance's Salesforce-managed allow rule using the reorder handle. Rules evaluate in order, so legitimate MRT traffic for that instance is already skipped by the allow rule before your block rule runs.

![Example custom firewall rule blocking direct SCAPI traffic for the Production org, scoped by the f_ecom_blnd_prd path segment](https://developer.salesforce.com/docs/commerce/media/pwa-kit-managed-runtime/scapi-request-identification-block-rule.png)

Add a separate rule, scoped to its own org-specific segment and to `/shopper`, for each additional instance you want to block. Rule order matters only relative to the allow rule it pairs with — for example, this Production block rule can sit directly after the Production allow rule, ahead of the Staging and Development allow rules:

![Custom Firewall Rules list showing the Production block rule ordered directly after the Production allow rule](https://developer.salesforce.com/docs/commerce/media/pwa-kit-managed-runtime/scapi-request-identification-rule-order.png)

### Roll Back

If the block rule stops legitimate traffic, switch that rule back to `log`, or disable it, before you change the **Managed Runtime SCAPI Request Identification** feature switch. After you enforce the rule, alert on a spike in SCAPI-zone blocks or HTTP 403 responses. [Anomaly Detection in Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_anomaly_detection.htm&type=5) is one way to raise that alert.


## Considerations

- **SIH closes MRT bypass, not every SCAPI attack vector.** SIH verifies that a request came from MRT. Keep the rate limiting, WAF rules, and bot controls you already run on traffic that does pass through MRT. Continue to follow [Bot Management](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html) best practices for that traffic.
- **Composable and hybrid storefronts are both covered.** SIH is applied at the MRT platform level to every proxied request to SCAPI, not only requests from a specific framework version.
- **Salesforce and you split this control.** Salesforce provides the SIH secret, rotates it, and owns the allow rule. You own the block rule, its exclusions, monitoring, and the rate-limit, WAF, and bot controls already in place.
- **Turning off the feature switch leaves that instance's allow rule in place.** You can't delete the allow rule. If you turn off **Managed Runtime SCAPI Request Identification** for an instance while its block rule is still enforced, direct SCAPI traffic that the allow rule used to pass now hits your block rule. Change that block rule from `block` to `log`, or disable it before you turn off the feature switch. See [Roll Back](https://developer.salesforce.com/docs/commerce/shared/mrt-block-direct-scapi-traffic.md#roll-back).

## Related Topics

- [Access Control Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#access-control-headers)
- [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5)
- [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones-custom-rules.md)
- [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-rate-limiting-rules.md)
- [CDN Zones](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones.md)
- [Security](https://developer.salesforce.com/docs/commerce/commerce-api/guides/security.md)
- [Bot Management](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html)
- [Bot Mitigation Best Practices for Flash Sales](https://developer.salesforce.com/docs/commerce/solutions/guides/bot-mitigation-sk.md)

<!-- document id=18ea377aed237a839ecea0c70b701584c3f21fc6301ce6a14b88254f8b76005c url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-scapi-request-identification.md -->

# Restrict SCAPI Access to Managed Runtime Traffic for Storefront Next

Lock down Shopper API requests so that they are accepted only from your Managed Runtime (MRT) environments, closing off the direct-access path that bots and scrapers use to bypass your CDN and MRT and call Shopper endpoints directly. Leave Admin API requests, which use Account Manager credentials, outside the block rule.

**note:** Available starting with B2C Commerce 26.10. Scope the block rule to Shopper API and SLAS paths. During the log phase, find Shopper callers that reach SCAPI without going through MRT, such as a custom BFF or a mobile app. Route those callers through MRT, or add a narrow exclusion for them. Skip the block rule only if neither option is possible. Leave Admin API paths out of the rule. Those calls use Account Manager credentials, including the B2C CLI, and they aren't the bot path this rule closes.


## How It Works

Enabling the **Managed Runtime SCAPI Request Identification** feature switch sets up a SCAPI Identity Header (SIH): a shared secret header that MRT attaches to every request it forwards to SCAPI. SCAPI's [eCDN zone](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones.md) can then tell the difference between a request that genuinely came from your MRT environment and a request sent directly to SCAPI from anywhere else, including a request that spoofs MRT's IP range or user agent.

SIH is applied at the MRT platform level, so it protects Storefront Next the same way it protects Composable Storefront (PWA Kit) and hybrid implementations — you don't need any Storefront Next-specific configuration for MRT to attach the header.

Salesforce generates and rotates the SIH secret automatically. You don't manage or rotate this secret yourself.

## Enable SCAPI Request Identification

1. In Business Manager, enable the **Managed Runtime SCAPI Request Identification** feature switch separately in each instance you want protected — Development, Staging, and Production. Enabling the switch in one instance doesn't enable it in the others; each instance gets its own SIH secret.
2. For each instance where you enable the switch, wait for the setup job to finish provisioning that instance's secret and its rule in the SCAPI eCDN zone. This can take some time to propagate; don't add a block rule for an instance (the next section) until its setup completes.
3. In Business Manager on your **Production** instance, go to **Administration > Sites > Embedded CDN Settings**, select the **SCAPI zone**, and click the **Security Rules** tab. Because the SCAPI zone is shared, you manage rules for all three instances from this one tab. A new Salesforce-managed custom firewall rule appears for each instance where you enabled the switch. Each rule scopes itself to its instance by matching an org-specific segment in the request URL path (for example, `f_ecom_blnd_prd` for Production, `f_ecom_blnd_stg` for Staging, `f_ecom_blnd_dev` for Development), so it only ever allows that instance's MRT traffic. These rules are locked. View them, but don't edit or delete them.

**important:** The SCAPI zone is shared across your Development, Staging, and Production instances, but each instance's allow rule and secret are scoped separately by that org-specific path segment. Enabling the feature switch in Production doesn't protect Development or Staging — enable it separately in each instance you want covered, and scope any block rule you add the same way.


## Block Direct SCAPI Traffic

After an instance's SIH allow rule is in place, add your own custom firewall rule to block direct Shopper API requests for that instance. The rule lives on the SCAPI zone's **Security Rules** tab. That tab is available when SCAPI Zone Visibility is enabled in Business Manager, which is on by default starting with B2C Commerce 26.10. See [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5).

Scope the block rule to the same org-specific path segment as that instance's allow rule, and to Shopper API and SLAS paths. A rule meant for Production then doesn't also match Staging or Development traffic, and Admin API calls stay outside the rule. The Salesforce allow rule stays scoped to the org segment. It lets Managed Runtime traffic through. Admin traffic doesn't need that header when the block rule doesn't match it. Repeat this section for each instance you want to block.

1. On the **Security Rules** tab for the SCAPI zone (managed from your Production instance), create a new custom firewall rule with **URI Path contains `<org-specific segment>`** and **URI Path contains `/shopper`**. Use the same org segment shown in that instance's Salesforce-managed allow rule (for example, `f_ecom_blnd_prd` for Production). `/shopper` matches Shopper API names such as `shopper-products` and the SLAS path `/shopper/auth`. It doesn't match Admin API paths, so Account Manager calls from the B2C CLI, CI, and other admin integrations keep working. A custom Shopper API uses `/custom/<api>/...` and does not contain `/shopper`. To block direct access to one custom endpoint, use the org segment and **URI Path contains `/custom/<api>`** instead of `/shopper`. See [Create a Custom Firewall Rule for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_create_eCDN_firewall_rule.htm&type=5).
2. Start with the `log` action. Leave the rule in `log` for at least one full business cycle, about 1 to 7 days, and include scheduled jobs and peak hours in that window. See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones-custom-rules.html) for rule expression syntax and available actions.
3. Review the matches in Security Analytics on the SCAPI zone, or in Log Center, by path, user agent, and ASN. See [Analyze HTTP and Security Traffic for an eCDN Zone](https://help.salesforce.com/s/articleView?id=cc.b2c_analyze_eCDN_traffic.htm&type=5). Look for legitimate Shopper API callers that reach SCAPI without going through MRT. Common ones include:

   - Native mobile apps that call SLAS and the Shopper APIs directly
   - Synthetic monitoring of Shopper APIs
   - QA automation against Shopper APIs

   Admin API callers, such as OMS, ERP, and PIM integrations and the B2C CLI, authenticate with Account Manager. They fall outside a rule scoped to `/shopper`, so you don't route them through MRT or exclude them from this rule.

4. For each legitimate Shopper caller, route the traffic through MRT or add a narrow exclusion. Limit an exclusion to a specific path plus a known signal, such as a client ID or a short list of fixed IPs. Excluding a whole IP range or network weakens the rule, the same way a broad IP exemption weakens WAF and rate-limit rules. Skip the block rule only when you can't route the caller through MRT and can't write a narrow exclusion.
5. When the logged matches are traffic you intend to stop, switch the action to `block`. Use `block`. Shopper API callers are API clients and can't complete a Managed Challenge. Don't switch from `log` to `block` during a flash sale, a holiday code freeze, or another peak window. See [Bot Mitigation Best Practices for Flash Sales](https://developer.salesforce.com/docs/commerce/solutions/guide/bot-mitigation-sk.html) and [Traffic Management for Flash Sales](https://developer.salesforce.com/docs/commerce/solutions/guide/traffic-management-sk.html). Then drag the rule into place directly after that instance's Salesforce-managed allow rule using the reorder handle. Rules evaluate in order, so legitimate MRT traffic for that instance is already skipped by the allow rule before your block rule runs.

![Example custom firewall rule blocking direct SCAPI traffic for the Production org, scoped by the f_ecom_blnd_prd path segment](https://developer.salesforce.com/docs/commerce/media/pwa-kit-managed-runtime/scapi-request-identification-block-rule.png)

Add a separate rule, scoped to its own org-specific segment and to `/shopper`, for each additional instance you want to block. Rule order matters only relative to the allow rule it pairs with — for example, this Production block rule can sit directly after the Production allow rule, ahead of the Staging and Development allow rules:

![Custom Firewall Rules list showing the Production block rule ordered directly after the Production allow rule](https://developer.salesforce.com/docs/commerce/media/pwa-kit-managed-runtime/scapi-request-identification-rule-order.png)

### Roll Back

If the block rule stops legitimate traffic, switch that rule back to `log`, or disable it, before you change the **Managed Runtime SCAPI Request Identification** feature switch. After you enforce the rule, alert on a spike in SCAPI-zone blocks or HTTP 403 responses. [Anomaly Detection in Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_anomaly_detection.htm&type=5) is one way to raise that alert.


## Considerations

- **SIH closes MRT bypass, not every SCAPI attack vector.** SIH verifies that a request came from MRT. Keep the rate limiting, WAF rules, and bot controls you already run on traffic that does pass through MRT. Continue to follow [Bot Management](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html) best practices for that traffic.
- **Salesforce and you split this control.** Salesforce provides the SIH secret, rotates it, and owns the allow rule. You own the block rule, its exclusions, monitoring, and the rate-limit, WAF, and bot controls already in place.
- **Turning off the feature switch leaves that instance's allow rule in place.** You can't delete the allow rule. If you turn off **Managed Runtime SCAPI Request Identification** for an instance while its block rule is still enforced, direct SCAPI traffic that the allow rule used to pass now hits your block rule. Change that block rule from `block` to `log`, or disable it before you turn off the feature switch. See [Roll Back](https://developer.salesforce.com/docs/commerce/shared/mrt-block-direct-scapi-traffic.md#roll-back).

## Related Topics

- [Limit Access to a Storefront Under Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-protect-storefront.md)
- [Default Security Rules on On-Demand Sandbox (ODS) Instances](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ods-security-rules.md)
- [Security Response Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-security-headers.md)
- [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5)
- [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-zones-custom-rules.md)
- [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/commerce-api/guides/cdn-rate-limiting-rules.md)
- [Security](https://developer.salesforce.com/docs/commerce/commerce-api/guides/security.md)
- [Bot Management](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html)
- [Bot Mitigation Best Practices for Flash Sales](https://developer.salesforce.com/docs/commerce/solutions/guides/bot-mitigation-sk.md)

<!-- document id=407692fef124058a06938e9bd066b3634e9f221815e4b147518bc7a294a3941a url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/retail-react-app.md -->

# Retail React App in PWA Kit v3.x

The Retail React App is a set of sample code and tooling designed to give you a head start on building your storefront on top of APIs and hosting it on Managed Runtime.

When you use the Retail React App with Progressive Web App (PWA) Kit version 3.x, you have access to features, such as Template Extensibility, Personalize with Shopper Context, SLAS private client, Store Locator, and support for different Product types.

This guide for the Retail React App in PWA Kit version 3.x:

- Describes its structure and contents
- Highlights its flexible, open-source foundation

## Prerequisites

To use the Retail React App with PWA Kit version 3.x or later, if you haven’t already done so, upgrade your PWA Kit project from version 2.x to version 3. See [Upgrade to v3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.md).

## File Structure

All PWA Kit projects start with the same set of files. At the start of a project, these files are generated by a script. To generate a PWA Kit project, see [Get Started](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.md).

To get an overview of how the Retail React App works, start by exploring its file structure. Here's a description of some of the folders and files in the PWA Kit project.

| Directory         | Description                                                                     |
| ----------------- | ------------------------------------------------------------------------------- |
| .cursor           | Contains autogenerated Cursor rules for storefront development                  |
| config            | Configuration files                                                             |
| config\default.js | Default configuration file                                                      |
| config\sites.js   | Identifies sites configured in Business Manager. Includes localization details. |
| config\utils.js   | Utilities imported throughout the app                                           |
| node_modules      | Package dependencies                                                            |
| overrides         | Contains overrides for template extensibility                                   |
| overrides\app     | Application code lives here                                                     |
| translations      | Translations for react-intl                                                     |
| worker            | Service worker                                                                  |
| .eslintignore     | Exclusion rules for ESLint                                                      |
| .eslintrc.js      | Code style rules for ESLint                                                     |
| .prettierrc.yaml  | Code formatting rules for Prettier                                              |
| README.MD         | Basic documentation                                                             |
| babel.config.js   | Transpilation rules for Babel                                                   |
| jest.config.js    | Unit testing configuration for Jest                                             |
| package-lock.json | Package configuration lock file                                                 |
| package.json      | Package configuration                                                           |

Here’s a listing of all the files and directories of a freshly generated project.

```
├── .cursor/
│   └── rules/
│       ├── cursor-accessibility-mdc/
│       │   ├── accessibility-button-name.mdc
│       │   ├── accessibility-heading-order.mdc
│       │   ├── accessibility-image-alt.mdc
│       │   ├── accessibility-input-label.mdc
│       │   └── accessibility-link-name.mdc
│       ├── accessibility-rule.mdc
│       ├── component-generation-requirements.mdc
│       ├── cursor-rule.mdc
│       ├── development-guidelines.mdc
│       └── page-creation.mdc
├── config/
│   ├── default.js
│   ├── sites.js
│   └── utils.js
├── node_modules/
├── overrides/
│   └── app/
│       ├── assets/
│       │   └── svg/
│       │       └── brand-logo.svg
│       ├── components/
│       │   └── _app-config/
│       │       └── index.jsx
│       ├── pages/
│       │   ├── home/
│       │   │   └── index.jsx
│       │   └── my-new-route/
│       │       └── index.jsx
│       ├── static/
│       │   ├── ico/
│       │   │   └── favicon.ico
│       │   ├── img/
│       │   │   ├── global/
│       │   │   │   ├── app-icon-192.png
│       │   │   │   ├── app-icon-512.png
│       │   │   │   └── apple-touch-icon.png
│       │   │   ├── GoogleMaps_Logo_Gray_4x.png
│       │   │   └── hero.png
│       │   ├── translations/
│       │   │   └── compiled/
│       │   │       ├── da-DK.json
│       │   │       ├── ...
│       │   ├── manifest.json
│       │   └── robots.txt
│       ├── constants.js
│       ├── main.jsx
│       ├── request-processor.js
│       ├── routes.jsx
│       └── ssr.js
├── translations/
│   ├── README.md
│   ├── da-DK.json
│   ├── ...
├── worker/
│   └── main.js
├── .eslintignore
├── .eslintrc.js
├── .prettierrc.yaml
├── README.MD
├── babel.config.js
├── jest.config.js
├── package-lock.json
└── package.json
```

## Scripts

To automate routine development tasks, the Retail React App includes several scripts. Use the command `npm run <SCRIPT_NAME>` to run them from the terminal.

Here’s a complete list of all the included scripts with a description of each one.

| Name                       | Description                                                                                                                                     |
| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `analyze-build`            | Builds the project in production mode and creates two webpack-bundle-analyzer reports. Use the reports to monitor the size of your code bundle. |
| `compile-messages`         | Compile all localized messages into AST format.                                                                                                 |
| `extract-default-messages` | Automatically extract the default locale’s messages from your React components.                                                                 |
| `format`                   | Format the code using Prettier.                                                                                                                 |
| `lint`                     | Find inconsistent code styling using ESlint.                                                                                                    |
| `lint:fix`                 | Automatically fix ESlint errors.                                                                                                                |
| `prod:build`               | Build the project in production mode.                                                                                                           |
| `push`                     | Push the code bundle (production build artifacts) to Managed Runtime.                                                                           |
| `save-credentials`         | Save Runtime Admin credentials locally (for push command).                                                                                      |
| `start`                    | Start the SSR server.                                                                                                                           |
| `start:inspect`            | Start the SSR server using the Node.js inspector.                                                                                               |
| `start:pseudolocale`       | Start the SSR server with a pseudo locale.                                                                                                      |
| `test`                     | Run unit tests using Jest.                                                                                                                      |
| `test:lighthouse`          | Run Lighthouse tests.                                                                                                                           |
| `test:max-file-size`       | Run a bundlesize test.                                                                                                                          |

## Test Suites

Your project comes with two example test suites for quality assurance: unit tests created with [Jest](https://jestjs.io/docs/getting-started/) and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/).

The unit tests are included alongside each of the page components in their respective directories.

To start the unit tests, run the following command in your terminal:

```bash
npm run test
```

To learn more about testing your storefront, review the source code for the example test suites and explore the documentation for [Jest](https://jestjs.io/docs/getting-started/) and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/).

From the start, the Retail React App gets excellent performance scores, as measured by Google’s Lighthouse test suite. We make it easy to monitor your Lighthouse scores throughout development using the following script:

```bash
npm run test:lighthouse
```

The script runs Lighthouse three times on your storefront and uploads the median scores for each category to Google. Google then uses those scores to generate a report. A link to the report is output by the script before it exits.

## Salesforce APIs

**note:** To use Salesforce APIs to access shopper data, an administrator must complete the tasks described in [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md).

In PWA Kit version 3.x, shopper data in the Retail React App is accessed through the `@salesforce/commerce-sdk-react` library, which replaces the previous CommerceAPI class. This library provides hooks for interacting with Salesforce Commerce Cloud's backend services, streamlining API requests, and enhancing state management through TanStack Query.

The `getProps` method used in previous versions has been replaced by the `withReactQuery` data fetching strategy. This new approach uses the react-query library, allowing for isomorphic data fetching using React hooks. To access the API wrapper from a page component, you can use the React hooks provided by `@salesforce/commerce-sdk-react` as shown in this example:

<!-- prettier-ignore-start -->

```javascript 
const MyPage = (props) => {
  const {categories} = props
  return <div>There are {categories.length} categories.</div>
}

MyPage.getProps = async ({api}) => {
  categories = await api.shopperProducts.getCategory({
    parameters: {id: categoryId, levels: 0}
  })

  return {categories}
}
```

<!-- prettier-ignore-end -->

The `@salesforce/commerce-sdk-react` library currently uses the B2C Commerce API for products, promotions, gift certificates, and search. Each feature is provided with its own set of endpoints, which are documented separately in the [B2C Commerce API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references).

To authorize API requests on behalf of registered shoppers and guests, the `@salesforce/commerce-sdk-react` library relies on a Salesforce Commerce API called the [Shopper Login and API Access Service](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary) (SLAS). For baskets and orders, the library class also uses the [Open Commerce API](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/OCAPI/current/usage/OpenCommerceAPI.html) (OCAPI).

Instructions for setting up the B2C Salesforce Commerce API (including SLAS) and OCAPI are covered in [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md).

## Chakra UI

The [Chakra UI](https://chakra-ui.com/) component library is a new, yet production-ready technology that we’re excited to use in the Retail React App. It includes 50+ user interface components, all with excellent accessibility and usability. Components can be customized with [style props](https://www.chakra-ui.com/docs/styling/overview) or using JavaScript objects for more advanced styling (CSS-in-JS). All Chakra components come with well-designed base styles that can be overridden with a theming system.

### Theming

The [Chakra Theming](https://www.chakra-ui.com/docs/theming/overview) system is based on the [Styled System Theme Specification](https://styled-system.com/theme-specification/). You can customize the look and feel of your components to suit your brand by updating the values in the `app/theme` directory.

**note:** Theming is available for most of the reusable components in `app/components` but isn’t available for the pages like the Product Details Page or Product Listing Page. To change the styling for these pages, edit the inline styles in the source code for their respective page components in `app/pages`.

## SVG Icons

To include custom SVG icons in the project, add them to the `app/assets/svg` directory, import them in `app/components/icons/index.js`, and export the React `icon` component like this: `export const MyCustomIcon = icon('my-custom-icon')`.

The imported SVG icons are packaged into an SVG sprite at build time, and the sprite is included in the server-side rendered HTML.

## The PWA Kit React SDK

The PWA Kit React SDK is a library that supports the isomorphic rendering pipeline for PWA Kit storefronts. It contains many key classes, functions, and components that power the Retail React App. For example, the `render()` function in `app/ssr.js` that kicks off the entire rendering and routing process is imported from the SDK.

The SDK abstracts away some of the implementation details for server-side rendering, caching, and proxying while giving you plenty of opportunities to customize their operation. It also provides general-purpose utilities and tools for maintaining a single set of code that can be rendered both on the client side and the server side.

Salesforce maintains the SDK as a separate `npm` package from the Retail React App so that improvements can be made more easily.

The PWA Kit React SDK and the entire Retail React App are open-source projects and [available on GitHub](https://github.com/SalesforceCommerceCloud/pwa-kit/). We welcome contributions from the B2C Commerce community!

## Other Core Technologies

The open-source technologies listed in this section are the ones that are used most frequently by the Retail React App. They’re also the hardest to replace with alternatives, so we selected them not only for their performance characteristics, but also for their reputation. Each one is actively maintained, highly customizable, well documented, and widely used.

Here’s a brief overview of each of these core technologies, many of which are probably familiar to you already:

### Babel

[Babel](https://babeljs.io/docs/en/) compiles your JavaScript code to make it compatible with a wide range of browsers and Node.js environments. It transforms advanced language syntax and polyfills any features that are missing from the environment.

### Express.js

[Express](https://expressjs.com/) is a popular open-source web server framework, written in JavaScript, and run within the Node.js runtime environment. It handles HTTP requests for the routes you define as the entry points for your storefront.

Express allows you to configure common web server settings, such as the connection port and the location of templates for returning the response. It also allows you to add additional request processing [middleware](https://expressjs.com/en/guide/writing-middleware.html) at any point within the request handling pipeline.

### Node.js

All of the server-side code for a PWA Kit application is run on top of [Node.js](https://nodejs.org/), an open-source runtime environment for JavaScript. The runtime environment omits browser-specific JavaScript APIs and includes its own APIs to access features of the host operating system (such as the file system) in a cross-platform way.

Node.js uses a non-blocking or asynchronous architecture, which is ideal for building highly scalable and data-intensive storefronts.

### React

[React](https://reactjs.org/) is a framework developed by Facebook to create [single-page apps](https://flaviocopes.com/single-page-application/) that deliver fast, fluid, and immersive user interfaces.

In a React app, the user interface is built with discrete _components_ that are typically arranged in complex hierarchies. In a well-designed React app, each component is only responsible for one job—and often that job is just to contain other components.

The component hierarchy in the Retail React App is designed for extensibility. You can build on top of the included components or swap them out for new components.

Packages related to React:

| Name                                                                      | Description                                                                                                                   |
| :------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------- |
| [Loadable Components](https://loadable-components.com/)                   | Speeds up performance through code-splitting of larger bundles.                                                               |
| [ReactDOM](https://reactjs.org/docs/react-dom.html)                       | Provides DOM-specific methods that can be used at the top level of your application.                                          |
| [ReactDOMServer](https://reactjs.org/docs/react-dom-server.html)          | Provides the method renderToString() that pre-renders HTML on the server side.                                                |
| [React Helmet](https://github.com/nfl/react-helmet/blob/master/README.md) | Helps you manage changes to the document’s `head` tag                                                                         |
| [React Router](https://reacttraining.com/react-router/)                   | Maps URL paths to React components. Paths can be expressed as patterns that are matched from most specific to least specific. |

### Webpack

[Webpack](https://webpack.js.org/concepts/) consolidates your code into one or more bundles. These bundles are deployed to Managed Runtime and eventually loaded in the browser as part of the hydration process.

The Retail React App imports ready-made Webpack configurations for the client side and server side from the PWA Kit React SDK. In most cases, you don’t need to change these configurations, but if you do, you can extend the Webpack configuration in `webpack.config.js`.

## Demo Site

Our [demo site](https://pwa-kit.mobify-storefront.com/) is built using the Retail React App. The site looks similar to what’s shown in this example.

![Demo site for Composable Storefront](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/pwa-demo-site.png '{"class": "image-xl"}')

## Best Practices

- Use [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html) to customize your site. This approach helps to reduce your code footprint, development toil, cost of ownership, and future upgrade headaches.
- Keep track of new features in the Retail React App by checking the [release notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html) or the [releases page](https://github.com/SalesforceCommerceCloud/pwa-kit/releases) on GitHub.
- Check out the [Performance Guide for Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-guide.md) on performance best practices and tips to monitor and improve your storefront's performance.

## Troubleshoot the Retail React App

This section provides suggested solutions for a few common errors that you can encounter while using the Retail React App.

### Unable to Access Site Data Using the B2C Commerce API

Potential Cause: API access wasn’t set up.

Suggested Solution: Ensure that an administrator has completed the tasks described in [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md). Also, add code to the relevant page components to access the API wrapper as described in [Salesforce APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.html#salesforce-apis).

### Site Performance is Slow

Potential Cause: Large bundles, images, or caching aren‘t optimized.

Suggested Solutions:

- Check out the [Performance Guide for Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-guide.md) on performance best practices and tips to monitor and improve your storefront's performance.
- Use the [Loadable Components](https://loadable-components.com/) package for code-splitting to improve performance.
- Use the `npm run analyze-build` script to check for large bundle sizes. You may need to perform code splitting to reduce your bundle sizes.
- Optimize images to reduce their size. Consider using image compression tools to reduce page load times.
- Implement caching strategies. See [Maximize Your Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/maximizing-your-cache-hit-ratio.md).

For more performance improvement suggestions, see the [Pre-Build and Go-Live Best Practices](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/best-practices.html) checklist.

## Next Steps

- Now that you’re familiar with the structure and contents of the Retail React App, it’s time to dig deeper! Start by exploring the source code, especially the ecommerce components in `app/pages`.
- See [GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-kit-overview.md#github-repository) for information about the latest files in the Retail React App and other packages.
- Check out [our demo site](https://pwa-kit.mobify-storefront.com/) that’s built using the Retail React App.
- Build your own demo site based on the Retail React App. See the [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.md).
- Learn about features available with the Retail React App on PWA Kit version 3.x such as:
  - [Template Extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md)
  - [Store Locator](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/store-locator.md)
  - [In-Store Pickup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/instore-pickup.md)
  - [Ship Products to Multiple Addresses and Stores](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/multiple-shipments.md)
  - [Personalize with Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/personalize-with-shopper-context.md)
  - [Active Data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/active-data.md)

For other features, check out the [Build Your Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/build-customize.md) section.

<!-- document id=1fb87b31d2ef01cd0756a5c47295654ec98b83b160d896cdd8c6d00bd13bda97 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/retrieve-delivery-groups-via-spi.md -->

# Retrieving Delivery Groups via SPI

Use Point of Sale Delivery Groups SPI to retrieve shipping charges for potential shipping groupings of products in the shopping cart.

## Prerequisites

- Modern POS App Build: 10.3.1 or greater
- Platform Support: iPad and iPhone
- Offline Support: no
- Technical: turn on these Omnichannel settings
  - Enable Order Delivery Grouping
  - Allow Multiple Shipments Per Cart/Order
  - Allow Multiple Delivery and Pickup Dates Per Order
  - Allow Multiple Shipping Addresses Per Order

**note:** For details on this SPI, see [Delivery Group SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/delivery-group-spi) in the Point of Sale reference documentation.

For a comprehensive list of Point of Sale APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Configure the Delivery Group SPI

Configure the Delivery Group Service Provider Interface (SPI) in Custom Connectors to retrieve delivery groups.

1. In CMS, go to **Integrations > Custom Connectors** and select **Create** in the upper right.
2. Under **Connector Type**, select **SPI**.
3. Under **Endpoint Name**, select **DELIVERY_GROUP**.
4. Under **API Endpoint**, provide the external endpoint to retrieve delivery groups.
5. Under **Integration Type**, select **HTTP_POST**.
6. Under **JSON Headers**, provide headers to be passed.
7. Configure the rest of the fields as needed.
8. Save your changes.

## Request and Response Overview

**Endpoint:**

```
POST /merchant/spi/sample/endpoint/sa/deliveryGroup
```

### Request Structure

The request payload includes all items in the cart. Each item has important details, such as the chosen delivery type, shipping method, number of items, price, discounts, and address information (including city, state, zip, and country). In the request, items are grouped by delivery group. A delivery group shares the same unique values for fulfillment type, address, shipping method, and delivery date.

If available, the delivery date is also included in the request. A new request is sent to update the shipping methods whenever a retail associate changes the cart. Cart changes include adding or removing items for delivery, switching the fulfillment type to "Ship to Home," updating the recipient's address, changing the delivery date, applying a price override, or adjusting quantities and prices.

You can also send additional attributes with the request, including information mapped to Point of Sale's product custom fields in CMS using the Store Setting field `tLogCustomProductAttributes`.

For complete request and response payload examples, see the [Delivery Group SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/delivery-group-spi) reference documentation.

## Enhanced Features: Inventory Reservation with Delivery Dates

For POS app builds 10.7.1 or later, the Delivery Group SPI includes enhanced support for delivery date functionality with inventory reservation.

These enhancements introduce three new fields in the SPI response:

| Field                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `availableDateTimeSlotList` | This field is populated from the SPI response and passed to the app for display if it contains any available slots.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `deliveryDatePickerOption`  | **Possible values:** `DISABLED`, `ENABLED`, or `null`<br><br>**DISABLED:** Skips both the date picker UI and the API request, regardless of whether there are available date/time slots. If no slot is selected in the app, users can continue with checkout without issues, and an empty value is sent to Point of Sale's backend.<br><br>**ENABLED or null:** If the `availableDateTimeSlotList` is empty, the date picker API is called as usual. If there are available slots in the `availableDateTimeSlotList`, the date picker API is skipped, and the available slots are displayed to the user. |
| `slotId`                    | Each available date/time slot is assigned a unique slotId, which is passed from SPI to Point of Sale's backend and then to the app. If a user selects a slot, the app sends the corresponding slotId back to the backend as part of the update request.                                                                                                                                                                                                                                                                                                                                                  |

### For Eligible Items

For items that support delivery date selection, the SPI response includes:

- A flag, `deliveryDatePickerOption`, under `deliveryGroupList` with the value `ENABLED`
- The `availableDateTimeSlotList` under `deliveryGroupList`
- A `slotId` for each `dateTimeSlot` in the `availableDateTimeSlotList`

If eligible items are added to the cart and an address is entered, available delivery dates are fetched from the SPI based on the address provided. The selected date appears on the receipt and in the order history.

### For Non-Eligible Items

For items that don't support delivery date selection, the SPI response includes:

- The `deliveryDatePickerOption` flag under `deliveryGroupList` with the value `DISABLED`

<!-- document id=100a698393ebd3c736b6f96535dbb0bd4283e156831b27c19b2f8f93d52adc15 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_field_guide_and_calculation_logic.md -->

# Revenue Field Guide and Calculation Logic for the B2C Commerce Intelligence JDBC Driver

Understanding revenue calculations is critical for accurateA Key Performance Indicator (KPI) creation and ensuring consistency across different dashboards and analytics tools. This section provides definitive guidance based on actual CCAC implementation, addressing common customer concerns about revenue discrepancies and metric consistency.

This topic addresses revenue calculation discrepancies between different analytics tools, the need for detailed metric descriptions and business context, and understanding how data models connect to dashboard implementations.

## Revenue Field Selection

This section provides the essential rules for selecting revenue fields in your analytics queries.

### Primary Rule: Use `std_revenue` for All Analytics

**The system automatically handles currency complexity for you:**

**note:** Any column with the prefix `std` refers to a monetary value that is converted to a common realm reporting currency.

- `std_revenue` = **Always** in your site's configured base currency
- Multi-currency transactions are automatically converted to `std_revenue`
- No complex business type decisions needed

### Revenue Field Definitions

| Field Name    | Data Type | Definition                                                                 | When to Use                            |
| ------------- | --------- | -------------------------------------------------------------------------- | -------------------------------------- |
| `std_revenue` | NUMERIC   | **Gross Merchandise Value (GMV)** in the realm's reporting currency (auto-converted) | **All KPIs, reporting, and analytics** |

### Critical: Revenue = Gross Merchandise Value

**All revenue fields represent GROSS merchandise value (which includes certain discounts), not net revenue.** This ensures consistent baselines across all analytics, matching the approach for Commerce reports and dashboards.

**Revenue Calculation:**

```sql
-- Line Item Level (Source of Truth)
gross_merchandise_value = (quantity × unit_price) -
                         ((promotion_discount + promo_discount_order_allocated) +
                          (manual_discount + manual_disc_order_allocated))

-- Aggregated Level (What you query)
std_revenue = SUM(std_li_gross_merchandise_value)
```

GMV includes all orders placed on the storefront, converted to common reporting currency, and adjusted for reporting timezone.

GMV **isn't** adjusted by returns, cancellations, etc.

The `std_li_gross_merchandise_value` column in `ccdw_fact_line_item` represents GMV at the line item level in standard reporting currency.

In aggregate tables (like `ccdw_aggr_sales_summary` or `ccdw_aggr_product_sales_summary`), the `std_revenue` column is an aggregate of the `std_li_gross_merchandise_value` column.

## Standard Revenue Analytics

These examples demonstrate common revenue analysis patterns using the standardized revenue fields.

### All Business Teams: Use `std_revenue`

**Daily Revenue Trend:**

```sql
SELECT
    submit_date,
    SUM(std_revenue) AS daily_revenue,
    SUM(num_orders) AS daily_orders,
    SUM(std_revenue) / SUM(num_orders) AS avg_order_value
FROM ccdw_aggr_sales_summary
WHERE submit_date BETWEEN ? AND ?
GROUP BY submit_date
ORDER BY submit_date;
```

**Site Performance Comparison:**

```sql
SELECT
    s.nsite_id,
    SUM(ss.std_revenue) AS site_revenue,
    SUM(ss.num_orders) AS site_orders,
    SUM(ss.std_revenue) / SUM(ss.num_orders) AS site_aov
FROM ccdw_aggr_sales_summary ss
JOIN ccdw_dim_site s ON s.site_id = ss.site_id
WHERE ss.submit_date BETWEEN ? AND ?
GROUP BY s.nsite_id
ORDER BY site_revenue DESC;
```

**Product Performance Analysis:**

```sql
SELECT
    p.product_display_name,
    SUM(pss.std_revenue) AS product_revenue,
    SUM(pss.num_units) AS units_sold,
    SUM(pss.std_revenue) / SUM(pss.num_units) AS revenue_per_unit
FROM ccdw_aggr_product_sales_summary pss
JOIN ccdw_dim_product p ON p.product_id = pss.product_id
WHERE pss.submit_date BETWEEN ? AND ?
GROUP BY p.product_display_name
HAVING SUM(pss.std_revenue) > 1000  -- Focus on significant revenue products
ORDER BY product_revenue DESC;
```

## Promotion Revenue Analysis

This section shows how to analyze the impact of promotions on revenue using the standardized revenue calculations.

**Example**: Analyze promotion impact using revenue data:

```sql
-- Promotion revenue analysis using aggregated data
SELECT
    p.display_name AS promotion_name,
    SUM(pss.std_revenue) AS promoted_revenue,
    SUM(pss.std_total_discount) AS discount_given,
    SUM(pss.num_orders) AS orders_with_promotion,
    ROUND(SUM(pss.std_total_discount) / SUM(pss.std_revenue) * 100, 2) AS discount_percentage
FROM ccdw_aggr_promotion_sales_summary pss
JOIN ccdw_dim_promotion p ON p.promotion_id = pss.promotion_id
WHERE pss.submit_date BETWEEN ? AND ?
GROUP BY p.display_name
ORDER BY promoted_revenue DESC;
```

<!-- document id=188a9a5b1c12c7f3b363f77cdaa4d4a419021f2459cbe92899ca28a60196b137 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/reward-spi.md -->

Reward SPI

# Reward SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/reward-spi/reward-spi-oas-public.yaml)

Sample reward-related APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system.

**Version:** 2.3.4

## Tags

### Reward SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/reward-spi/reward-spi-oas-public.yaml)

Sample reward-related APIs that demonstrate how to implement API endpoints or webhooks in the merchant's system. These endpoints must be configured in the POS system.

## Operations

### POST Look up rewards.

`POST /merchant/sample/endpoint/reward/lookup`

Operation ID: `lookupRewards`. Tags: Reward SPI.

Fetch the available rewards for a customer that can be applied as a tender. Reward lookup is done based on the customer account (CustomerId, Card Acquisition Token, etc.). Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `REWARD_LOOKUP`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/lookupRewards](https://sample/external/endpoint/lookupRewards)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `*/*`. Schema: `SpiRewardLookupRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiRewardLookupResponse`.
    

## Schemas

### SpiRewardLookupRequest

Request to look up rewards based on customer details such as Customer ID or Token value. At least one of the fields is required.

*   `customerId` (_string_) Customer ID.
*   `loyaltyId` (_string_) Loyalty Id of the customer.
*   `alias` (_string_) Card Alias/Token Value from the customer card acquisition response.
*   `issuerCountry` (_string_) The Card issuer country.
*   `cardCountryCode` (_string_) The country code present in card acquisition response.

### SpiRewardLookupResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `rewards` (_array of Reward_, required) List of applicable/available rewards earned by the customer. Response is mandatory for a successful response, can be an empty list.
*   `error` (_boolean_)

### Reward

Earned rewards.

*   `issueDate` (_integer (int64)_)
*   `expiryDate` (_integer (int64)_)
*   `description` (_string_)
*   `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender.
*   `rewardName` (_string_)
*   `code` (_string_)
*   `pin` (_string_)
*   `codeType` (_string_)
*   `labelText` (_string_)
*   `disclaimerText` (_string_)
*   `rewardType` (_string_)  
    Allowed values: `Discount`, `Coupon`, `Tender`.
*   `isImageOnly` (_boolean_)
*   `rewardImageURL` (_string_)
*   `rewardInputType` (_string_)
*   `status` (_string_)  
    Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`.
*   `statusDesc` (_string_)
*   `canRedeemNow` (_boolean_)
*   `redeemedDate` (_integer (int64)_)
*   `customAttributes` (_object_)
    
    Additional properties: `object`.
    
*   `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon,  
    it will be coupon code. In the case of discount reward, it is unique identifier.  
    Maximum length: 512.
*   `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart.
*   `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints).

<!-- document id=855d662da7c5e637b4a2aa82748492c8db95d9e8dcda05f98179e2139d5f42b0 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/roles.md -->

Roles

# Roles

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/roles/roles-oas-v1-public.yaml)

## API Overview

The Roles API provides endpoints for managing access roles and their associated users and permissions within Salesforce Commerce Cloud.

### Overview

This API allows administrators to create, retrieve, update, and delete access roles. It also supports managing user assignments to roles, retrieving and setting role permissions, and searching for users within a specific role.

### Key Features

*   **Role Management**: Create, retrieve, and delete access roles
*   **Permission Management**: Get and set permissions for access roles
*   **User Assignment**: Assign and unassign users to/from roles
*   **User Search**: Search for users assigned to a specific role using complex queries

### Searchable Attributes (User Search)

The following attributes can be used in user search queries within a role:

*   `login`: The user login identifier (String)
*   `email`: The user email address (String)
*   `firstName`: The user first name (String)
*   `lastName`: The user last name (String)
*   `externalId`: The external identifier (String)
*   `lastLoginDate`: The date of last login (Date)

### Sortable Attributes (User Search)

Search results can be sorted by:

*   `login`: Sort by user login
*   `email`: Sort by email address
*   `firstName`: Sort by first name
*   `lastName`: Sort by last name
*   `externalId`: Sort by external identifier
*   `lastLoginDate`: Sort by last login date

### Use Cases

*   **Access Control**: Define and manage role-based access control for Business Manager
*   **User Management**: Assign users to appropriate roles for their job functions
*   **Permission Auditing**: Review and update role permissions
*   **Compliance**: Ensure proper access controls are in place

### Authentication

This API requires OAuth 2.0 authentication with the appropriate scopes:

*   `sfcc.roles` - Read access to role resources
*   `sfcc.roles.rw` - Read and write access to role resources

### Best Practices

1.  Use the Administrator role carefully as permission changes are limited for system roles
2.  Review role permissions regularly for security compliance
3.  Use the user search endpoint for efficient user-role lookups
4.  Avoid deleting roles that have active user assignments

**Version:** 1.0.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/merchant/roles/v1`
    *   `shortCode (default 123456gf)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 security scheme for Admin API access using Account Manager. Requires appropriate scopes for role management operations.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.roles: Read access to role resources
    *   Scope sfcc.roles.rw: Read and write access to role resources

## Operations

### GET Get Roles

`GET /organizations/{organizationId}/roles`

Operation ID: `getRoles`. Security: AmOAuth2 (sfcc.roles, sfcc.roles.rw).

Retrieves all access roles with no filtering.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `expand` (query, array of string, style: form, explode: false) The list of resource types to include in the response.  
    Items: Allowed values: `users`, `permissions`. Example: `users`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Returns the collection of access roles
    
    Media type: `application/json`. Schema: `RoleSearch`.
    
    _Example: RoleSearchResult_ Role search result
    
    Example of a role search response. By default, only IDs are returned.
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 3,
      "data": [
        {
          "id": "Administrator"
        },
        {
          "id": "CustomManager"
        },
        {
          "id": "ContentEditor"
        }
      ]
    }
    ```
    
    _Example: RoleSearchExpandUsersResult_ Role search with expand users
    
    Example of a role search response with `expand=users` and `select=(**)`. All role fields are returned and each role includes its full users.
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 3,
      "data": [
        {
          "id": "Administrator",
          "description": "Full administrative access to Business Manager",
          "userCount": 2,
          "userManager": true,
          "users": [
            {
              "login": "admin-user",
              "email": "admin@example.com",
              "firstName": "John",
              "lastName": "Doe",
              "externalId": "ext-12345",
              "disabled": false,
              "locked": false,
              "lastLoginDate": "2024-10-14",
              "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
              "passwordModificationDate": "2024-10-14T10:00:00.000Z",
              "preferredDataLocale": "en-US",
              "preferredUiLocale": "en-US",
              "roles": [
                "Administrator"
              ]
            }
          ]
        },
        {
          "id": "CustomManager",
          "description": "Custom manager role for site operations",
          "userCount": 5,
          "userManager": false,
          "users": [
            {
              "login": "manager-user",
              "email": "manager@example.com",
              "firstName": "Alice",
              "lastName": "Brown",
              "externalId": "ext-11111",
              "disabled": false,
              "locked": false,
              "lastLoginDate": "2024-12-01",
              "passwordExpirationDate": "2025-03-01T00:00:00.000Z",
              "passwordModificationDate": "2024-12-01T09:00:00.000Z",
              "preferredDataLocale": "en-US",
              "preferredUiLocale": "en-US",
              "roles": [
                "CustomManager"
              ]
            }
          ]
        },
        {
          "id": "ContentEditor",
          "description": "Content editing access",
          "userCount": 8,
          "userManager": false,
          "users": [
            {
              "login": "editor-user",
              "email": "editor@example.com",
              "firstName": "Jane",
              "lastName": "Smith",
              "externalId": "ext-67890",
              "disabled": false,
              "locked": false,
              "lastLoginDate": "2024-11-20",
              "passwordExpirationDate": "2025-02-20T00:00:00.000Z",
              "passwordModificationDate": "2024-11-20T08:30:00.000Z",
              "preferredDataLocale": "en-US",
              "preferredUiLocale": "en-US",
              "roles": [
                "ContentEditor"
              ]
            }
          ]
        }
      ]
    }
    ```
    
    _Example: RoleSearchExpandPermissionsResult_ Role search with expand permissions
    
    Example of a role search response with `expand=permissions` and `select=(**)`. All role fields are returned and each role includes its full permissions.
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 3,
      "data": [
        {
          "id": "Administrator",
          "description": "Full administrative access to Business Manager",
          "userCount": 2,
          "userManager": true,
          "permissions": {
            "module": {
              "organization": [
                {
                  "name": "jobschedules",
                  "application": "bm",
                  "system": true,
                  "type": "module",
                  "value": "ACCESS"
                },
                {
                  "name": "customreports",
                  "application": "bm",
                  "system": false,
                  "type": "module",
                  "value": "ACCESS"
                }
              ],
              "site": [
                {
                  "name": "library_content",
                  "application": "bm",
                  "system": true,
                  "type": "module",
                  "values": {
                    "SiteGenesis": "ACCESS",
                    "RefArch": "READONLY"
                  }
                }
              ]
            },
            "functional": {
              "organization": [
                {
                  "name": "Delete_All_Catalogs",
                  "type": "functional",
                  "value": "ACCESS"
                }
              ],
              "site": [
                {
                  "name": "ViewOrders",
                  "type": "functional",
                  "values": {
                    "SiteGenesis": "ACCESS"
                  }
                }
              ]
            },
            "locale": {
              "unscoped": [
                {
                  "localeId": "default",
                  "type": "locale",
                  "value": "ACCESS"
                },
                {
                  "localeId": "en",
                  "type": "locale",
                  "value": "ACCESS"
                }
              ]
            },
            "webdav": {
              "unscoped": [
                {
                  "folder": "/catalogs/apparel-catalog",
                  "type": "webdav",
                  "value": "ACCESS"
                }
              ]
            }
          }
        },
        {
          "id": "CustomManager",
          "description": "Custom manager role for site operations",
          "userCount": 5,
          "userManager": false,
          "permissions": {
            "module": {
              "site": [
                {
                  "name": "library_content",
                  "application": "bm",
                  "system": true,
                  "type": "module",
                  "values": {
                    "SiteGenesis": "ACCESS"
                  }
                }
              ]
            },
            "locale": {
              "unscoped": [
                {
                  "localeId": "default",
                  "type": "locale",
                  "value": "ACCESS"
                }
              ]
            },
            "webdav": {
              "unscoped": []
            }
          }
        },
        {
          "id": "ContentEditor",
          "description": "Content editing access",
          "userCount": 8,
          "userManager": false,
          "permissions": {
            "module": {
              "site": [
                {
                  "name": "library_content",
                  "application": "bm",
                  "system": true,
                  "type": "module",
                  "values": {
                    "SiteGenesis": "READONLY"
                  }
                }
              ]
            },
            "locale": {
              "unscoped": [
                {
                  "localeId": "default",
                  "type": "locale",
                  "value": "ACCESS"
                },
                {
                  "localeId": "en",
                  "type": "locale",
                  "value": "READONLY"
                }
              ]
            },
            "webdav": {
              "unscoped": []
            }
          }
        }
      ]
    }
    ```
    

### GET Get Role

`GET /organizations/{organizationId}/roles/{roleId}`

Operation ID: `getRole`. Security: AmOAuth2 (sfcc.roles, sfcc.roles.rw).

Retrieves a single access role by its identifier.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.
*   `expand` (query, array of string, style: form, explode: false) The list of resource types to include in the response.  
    Items: Allowed values: `users`, `permissions`. Example: `users`.

#### Responses

*   **200** Returns the access role details
    
    Media type: `application/json`. Schema: `Role`.
    
    _Example: RoleDetailsResult_ Single role
    
    Example of a single role response. By default, only the ID is returned.
    
    ```
    {
      "id": "Administrator"
    }
    ```
    
    _Example: RoleDetailsExpandUsersResult_ Single role with expand users
    
    Example of a single role response with `expand=users` and `select=(**)`. All role fields are returned including the assigned users.
    
    ```
    {
      "id": "Administrator",
      "description": "Full administrative access to Business Manager",
      "userCount": 2,
      "userManager": true,
      "users": [
        {
          "login": "admin-user",
          "email": "admin@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "externalId": "ext-12345",
          "disabled": false,
          "locked": false,
          "lastLoginDate": "2024-10-14",
          "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
          "passwordModificationDate": "2024-10-14T10:00:00.000Z",
          "preferredDataLocale": "en-US",
          "preferredUiLocale": "en-US",
          "roles": [
            "Administrator"
          ]
        }
      ]
    }
    ```
    
    _Example: RoleDetailsExpandPermissionsResult_ Single role with expand permissions
    
    Example of a single role response with `expand=permissions` and `select=(**)`. All role fields are returned including the full permissions.
    
    ```
    {
      "id": "Administrator",
      "description": "Full administrative access to Business Manager",
      "userCount": 2,
      "userManager": true,
      "permissions": {
        "module": {
          "organization": [
            {
              "name": "jobschedules",
              "application": "bm",
              "system": true,
              "type": "module",
              "value": "ACCESS"
            },
            {
              "name": "customreports",
              "application": "bm",
              "system": false,
              "type": "module",
              "value": "ACCESS"
            }
          ],
          "site": [
            {
              "name": "library_content",
              "application": "bm",
              "system": true,
              "type": "module",
              "values": {
                "SiteGenesis": "ACCESS",
                "RefArch": "READONLY"
              }
            }
          ]
        },
        "functional": {
          "organization": [
            {
              "name": "Delete_All_Catalogs",
              "type": "functional",
              "value": "ACCESS"
            }
          ],
          "site": [
            {
              "name": "ViewOrders",
              "type": "functional",
              "values": {
                "SiteGenesis": "ACCESS"
              }
            }
          ]
        },
        "locale": {
          "unscoped": [
            {
              "localeId": "default",
              "type": "locale",
              "value": "ACCESS"
            },
            {
              "localeId": "en",
              "type": "locale",
              "value": "ACCESS"
            },
            {
              "localeId": "de",
              "type": "locale",
              "value": "READONLY"
            }
          ]
        },
        "webdav": {
          "unscoped": [
            {
              "folder": "/catalogs/apparel-catalog",
              "type": "webdav",
              "value": "ACCESS"
            },
            {
              "folder": "/impex",
              "type": "webdav",
              "value": "ACCESS"
            }
          ]
        }
      }
    }
    ```
    
*   **404** Role not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    
    ```
    {
      "title": "Role Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/role-not-found",
      "detail": "No access role with ID 'nonexistent-role' could be found."
    }
    ```
    

### PUT Create Role

`PUT /organizations/{organizationId}/roles/{roleId}`

Operation ID: `createRole`. Security: AmOAuth2 (sfcc.roles.rw).

Creates a new access role with the specified identifier.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.

#### Request body (required)

The access role to create

Media type: `application/json`. Schema: `Role`.

_Example: CreateRole_ Create an access role

Example of creating a new access role

```
{
  "id": "CustomManager",
  "description": "Custom manager role for site operations"
}
```

#### Responses

*   **200** The access role was successfully updated
    
    Media type: `application/json`. Schema: `Role`.
    
    _Example: RoleCreated_ Newly created role
    
    Example of a successfully created access role
    
    ```
    {
      "id": "CustomManager",
      "description": "Custom manager role for site operations",
      "userCount": 0,
      "userManager": false
    }
    ```
    
*   **201** The access role was successfully created
    
    Media type: `application/json`. Schema: `Role`.
    
    _Example: RoleCreated_ Newly created role
    
    Example of a successfully created access role
    
    ```
    {
      "id": "CustomManager",
      "description": "Custom manager role for site operations",
      "userCount": 0,
      "userManager": false
    }
    ```
    
*   **400** Bad Request - Invalid role request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict_ ID conflict
    
    Example of an error when the ID in the request body does not match the ID in the URL
    
    ```
    {
      "title": "Id Conflict",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the request body ('DifferentRoleId') doesn't match the ID in the URL ('ScapiTestRole')."
    }
    ```
    
    _Example: RoleAlreadyExists_ Role already exists
    
    Example of an error when trying to create a role that already exists
    
    ```
    {
      "title": "Role Already Exists",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/role-already-exists",
      "detail": "An access role with ID 'ScapiTestRole' already exists. Please delete the existing role before creating a role with the same ID."
    }
    ```
    
    _Example: RoleOperationNotAllowed_ Role operation not allowed
    
    Example of an error when the operation is not allowed for the given role
    
    ```
    {
      "title": "Role Operation Not Allowed",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/role-operation-not-allowed",
      "detail": "The operation isn't allowed for the role with ID 'Administrator'."
    }
    ```
    

### DELETE Delete Role

`DELETE /organizations/{organizationId}/roles/{roleId}`

Operation ID: `deleteRole`. Security: AmOAuth2 (sfcc.roles.rw).

Deletes a single access role.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.

#### Responses

*   **204** The access role was successfully deleted
*   **404** Role not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example RoleNotFound: same as GET /organizations/{organizationId}/roles/{roleId} 404 response._ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    

### GET Get Role Permissions

`GET /organizations/{organizationId}/roles/{roleId}/permissions`

Operation ID: `getRolePermissions`. Security: AmOAuth2 (sfcc.roles, sfcc.roles.rw).

Retrieves the list of permissions assigned to the given role.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.

#### Responses

*   **200** Returns the role permissions
    
    Media type: `application/json`. Schema: `RolePermissions`.
    
    _Example: RolePermissionsSuccess_ Successful role permissions retrieval
    
    Example of a successful retrieval of role permissions
    
    ```
    {
      "module": {
        "organization": [
          {
            "name": "jobschedules",
            "application": "bm",
            "system": true,
            "type": "module",
            "value": "ACCESS"
          },
          {
            "name": "customreports",
            "application": "bm",
            "system": false,
            "type": "module",
            "value": "ACCESS"
          }
        ],
        "site": [
          {
            "name": "library_content",
            "application": "bm",
            "system": true,
            "type": "module",
            "values": {
              "SiteGenesis": "ACCESS",
              "RefArch": "READONLY"
            }
          }
        ]
      },
      "functional": {
        "organization": [
          {
            "name": "Delete_All_Catalogs",
            "type": "functional",
            "value": "ACCESS"
          }
        ],
        "site": [
          {
            "name": "ViewOrders",
            "type": "functional",
            "values": {
              "SiteGenesis": "ACCESS"
            }
          }
        ]
      },
      "locale": {
        "unscoped": [
          {
            "localeId": "default",
            "type": "locale",
            "value": "ACCESS"
          },
          {
            "localeId": "en",
            "type": "locale",
            "value": "ACCESS"
          },
          {
            "localeId": "de",
            "type": "locale",
            "value": "READONLY"
          }
        ]
      },
      "webdav": {
        "unscoped": [
          {
            "folder": "/catalogs/apparel-catalog",
            "type": "webdav",
            "value": "ACCESS"
          },
          {
            "folder": "/impex",
            "type": "webdav",
            "value": "ACCESS"
          }
        ]
      }
    }
    ```
    
*   **404** Role not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example RoleNotFound: same as GET /organizations/{organizationId}/roles/{roleId} 404 response._ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    

### PUT Set Role Permissions

`PUT /organizations/{organizationId}/roles/{roleId}/permissions`

Operation ID: `setRolePermissions`. Security: AmOAuth2 (sfcc.roles.rw).

Assigns permissions to the given role. This will replace the current permission assignments. For the 'Administrator' role only adjustments for custom module permissions will be processed but other given permissions will be ignored.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.

#### Request body (required)

The permissions to assign to the role

Media type: `application/json`. Schema: `RolePermissions`.

_Example: SetPermissions_ Set role permissions

Example of setting permissions for an access role

```
{
  "module": {
    "organization": [
      {
        "name": "jobschedules",
        "application": "bm",
        "system": true,
        "type": "module",
        "value": "ACCESS"
      }
    ],
    "site": [
      {
        "name": "library_content",
        "application": "bm",
        "system": true,
        "type": "module",
        "values": {
          "SiteGenesis": "ACCESS"
        }
      }
    ]
  },
  "functional": {
    "organization": [
      {
        "name": "Delete_All_Catalogs",
        "type": "functional",
        "value": "ACCESS"
      }
    ]
  }
}
```

#### Responses

*   **200** The permissions were successfully updated
    
    Media type: `application/json`. Schema: `RolePermissions`.
    
    _Example RolePermissionsSuccess: same as GET /organizations/{organizationId}/roles/{roleId}/permissions 200 response._ Successful role permissions retrieval
    
    Example of a successful retrieval of role permissions
    
    _Example: RolePermissionsSuccess_ Successful role permissions retrieval
    
    Example of a successful retrieval of role permissions
    
*   **201** The permissions were successfully assigned
    
    Media type: `application/json`. Schema: `RolePermissions`.
    
    _Example RolePermissionsSuccess: same as GET /organizations/{organizationId}/roles/{roleId}/permissions 200 response._ Successful role permissions retrieval
    
    Example of a successful retrieval of role permissions
    
    _Example: RolePermissionsSuccess_ Successful role permissions retrieval
    
    Example of a successful retrieval of role permissions
    
*   **400** Bad Request - Invalid permissions request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidPermissionType_ Invalid permission type
    
    Example of an error when the type of a permission does not match the expected type
    
    ```
    {
      "title": "Invalid Permission Type",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-permission-type",
      "detail": "The expected permission type is 'module' but provided was 'locale' for permission 'jobschedules(system)' in path 'module.organization'."
    }
    ```
    
    _Example: UnknownPermission_ Unknown permission
    
    Example of an error when a permission ID cannot be resolved
    
    ```
    {
      "title": "Unknown Permission",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unknown-permission",
      "detail": "Permission 'nonexistent-permission-xyz(system)' for application 'bm' in path 'module.organization' is unknown."
    }
    ```
    
    _Example: InvalidPermissionValue_ Invalid permission value
    
    Example of an error when a permission value is unknown or not supported
    
    ```
    {
      "title": "Invalid Permission Value",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-permission-value",
      "detail": "Permission 'jobschedules(system)' in path 'module.organization' doesn't support a value of 'INVALID_VALUE'."
    }
    ```
    
*   **404** Role not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example RoleNotFound: same as GET /organizations/{organizationId}/roles/{roleId} 404 response._ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    

### POST Search Role Users

`POST /organizations/{organizationId}/roles/{roleId}/user-search`

Operation ID: `searchRoleUsers`. Security: AmOAuth2 (sfcc.roles, sfcc.roles.rw).

Searches for users of the specified access role.

The query attribute specifies a complex query that can be used to narrow down the search. These are the list of searchable attributes:

*   login - String
*   email - String
*   firstName - String
*   lastName - String
*   externalId - String
*   lastLoginDate - Date
*   isLocked - Boolean
*   isDisabled - Boolean

The output of the query can also be sorted. These are the list of sortable attributes:

*   login - String
*   email - String
*   firstName - String
*   lastName - String
*   externalId - String
*   lastLoginDate - Date

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.

#### Request body (required)

The search request document for role users

Media type: `application/json`. Schema: `RoleUserSearchRequest`.

_Example: SearchUsersByLogin_ Search role users by login

Example of searching for users assigned to a role by their login

```
{
  "query": {
    "textQuery": {
      "fields": [
        "login"
      ],
      "searchPhrase": "admin"
    }
  },
  "limit": 25,
  "offset": 0
}
```

_Example: SearchUsersByEmail_ Search role users by email

Example of searching for users assigned to a role by their email

```
{
  "query": {
    "textQuery": {
      "fields": [
        "email"
      ],
      "searchPhrase": "@salesforce.com"
    }
  },
  "limit": 10,
  "offset": 0,
  "sorts": [
    {
      "field": "login",
      "sortOrder": "asc"
    }
  ]
}
```

#### Responses

*   **200** Returns role user search results
    
    Media type: `application/json`. Schema: `RoleUserSearchResult`.
    
    _Example: RoleUserSearchResultSuccess_ Successful role user search result
    
    Example of a successful role user search
    
    ```
    {
      "limit": 1,
      "offset": 0,
      "total": 1,
      "hits": [
        {
          "login": "admin-user",
          "email": "admin@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "externalId": "ext-12345",
          "disabled": false,
          "locked": false,
          "lastLoginDate": "2024-10-14",
          "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
          "passwordModificationDate": "2024-10-14T10:00:00.000Z",
          "preferredDataLocale": "en-US",
          "preferredUiLocale": "en-US",
          "roles": [
            "Administrator"
          ]
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "login"
          ],
          "searchPhrase": "admin"
        }
      },
      "sorts": [
        {
          "field": "login",
          "sortOrder": "asc"
        }
      ]
    }
    ```
    
*   **400** Bad Request - Malformed search query or invalid parameters
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnqueryableField_ Unqueryable field
    
    Example of an error when an invalid field name is used in the search query
    
    ```
    {
      "title": "Unqueryable Field",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "detail": "The field 'nonexistent_field' can't be queried."
    }
    ```
    
    _Example: FieldNotSortable_ Field not sortable
    
    Example of an error when a field that cannot be used for sorting is specified
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'locked' can't be used to sort the results."
    }
    ```
    
*   **404** Role not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example RoleNotFound: same as GET /organizations/{organizationId}/roles/{roleId} 404 response._ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    

### GET Get Role Users

`GET /organizations/{organizationId}/roles/{roleId}/users`

Operation ID: `getRoleUsers`. Security: AmOAuth2 (sfcc.roles, sfcc.roles.rw).

Retrieves all users assigned to the specified access role.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Returns the collection of users assigned to the role
    
    Media type: `application/json`. Schema: `UserSearch`.
    
    _Example: RoleUserCollectionSuccess_ Successful role user collection
    
    Example of a successful retrieval of users assigned to a role with `select=(**)`
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "data": [
        {
          "login": "admin-user",
          "email": "admin@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "externalId": "ext-12345",
          "disabled": false,
          "locked": false,
          "lastLoginDate": "2024-10-14",
          "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
          "passwordModificationDate": "2024-10-14T10:00:00.000Z",
          "preferredDataLocale": "en-US",
          "preferredUiLocale": "en-US",
          "roles": [
            "Administrator"
          ]
        },
        {
          "login": "editor-user",
          "email": "editor@example.com",
          "firstName": "Jane",
          "lastName": "Smith",
          "externalId": "ext-67890",
          "disabled": false,
          "locked": false,
          "lastLoginDate": "2024-11-20",
          "passwordExpirationDate": "2025-02-20T00:00:00.000Z",
          "passwordModificationDate": "2024-11-20T08:30:00.000Z",
          "preferredDataLocale": "en-US",
          "preferredUiLocale": "en-US",
          "roles": [
            "ContentEditor"
          ]
        }
      ]
    }
    ```
    
*   **404** Role not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example RoleNotFound: same as GET /organizations/{organizationId}/roles/{roleId} 404 response._ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    

### PUT Assign User to Role

`PUT /organizations/{organizationId}/roles/{roleId}/users/{login}`

Operation ID: `assignUserToRole`. Security: AmOAuth2 (sfcc.roles.rw).

Assigns a user to the specified access role.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.
*   `login` (path, string, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.

#### Responses

*   **200** The user was successfully re-assigned to the role
    
    Media type: `application/json`. Schema: `User`.
    
    _Example: UserAssigned_ User assigned to role
    
    Example of a user successfully assigned to an access role
    
    ```
    {
      "login": "admin-user",
      "email": "admin@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "externalId": "ext-12345",
      "disabled": false,
      "locked": false,
      "lastLoginDate": "2024-10-14",
      "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
      "passwordModificationDate": "2024-10-14T10:00:00.000Z",
      "preferredDataLocale": "en-US",
      "preferredUiLocale": "en-US",
      "roles": [
        "Administrator"
      ]
    }
    ```
    
*   **201** The user was successfully assigned to the role
    
    Media type: `application/json`. Schema: `User`.
    
    _Example UserAssigned: same as PUT /organizations/{organizationId}/roles/{roleId}/users/{login} 200 response._ User assigned to role
    
    Example of a user successfully assigned to an access role
    
    _Example: UserAssigned_ User assigned to role
    
    Example of a user successfully assigned to an access role
    
*   **404** Role or user not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example RoleNotFound: same as GET /organizations/{organizationId}/roles/{roleId} 404 response._ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: UserNotFound_ User not found
    
    Example of an error when the specified user does not exist
    
    ```
    {
      "title": "User Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/user-not-found",
      "detail": "No user with login 'nonexistent-user-xyz' could be found."
    }
    ```
    

### DELETE Unassign User from Role

`DELETE /organizations/{organizationId}/roles/{roleId}/users/{login}`

Operation ID: `unassignUserFromRole`. Security: AmOAuth2 (sfcc.roles.rw).

Unassigns a user from the specified access role.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `roleId` (path, string, required) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.
*   `login` (path, string, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.

#### Responses

*   **204** The user was successfully unassigned from the role
*   **404** Role or user not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example RoleNotFound: same as GET /organizations/{organizationId}/roles/{roleId} 404 response._ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example UserNotFound: same as PUT /organizations/{organizationId}/roles/{roleId}/users/{login} 404 response._ User not found
    
    Example of an error when the specified user does not exist
    
    _Example: RoleNotFound_ Role not found
    
    Example of an error when the specified role does not exist
    
    _Example: UserNotFound_ User not found
    
    Example of an error when the specified user does not exist
    

## Schemas

### OrganizationId

An identifier for the organization the request is being made by

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### RoleSearch

Document representing a collection of access roles.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Role_, required) The collection of roles.

### Role

Document representing an access role.

*   `id` (_string_) The identifier of the access role.  
    Minimum length: 1. Maximum length: 256. Example: `Administrator`.
*   `description` (_string_) The description of the access role.  
    Maximum length: 4000. Example: `Full administrative access`.
*   `userCount` (_integer (int32)_) The number of users assigned to this role.  
    Example: `5`.
*   `userManager` (_boolean_) Indicates whether this role has user management capabilities.  
    Example: `true`.
*   `permissions` (_RolePermissions_)
*   `users` (_array of User_) The users assigned to the access role. Available through expands.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### RolePermissions

Document representing the complete set of permissions for an access role.

*   `module` (_RoleModulePermissions_)
*   `functional` (_RoleFunctionalPermissions_)
*   `locale` (_RoleLocalePermissions_)
*   `webdav` (_RoleWebdavPermissions_)

### RoleUserSearchRequest

Document representing a search request for retrieving users assigned to an access role.

Searchable attributes:

*   login - String
*   email - String
*   firstName - String
*   lastName - String
*   externalId - String
*   lastLoginDate - Date
*   isLocked - Boolean
*   isDisabled - Boolean

Sortable attributes:

*   login - String
*   email - String
*   firstName - String
*   lastName - String
*   externalId - String
*   lastLoginDate - Date

Includes all fields of `SearchRequest`.

### RoleUserSearchResult

Document representing a role user search result. This includes the query, sorts, hits (array of user objects), and pagination information.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of User_, required) The sorted array of search hits (user objects). Can be empty.

### UserSearch

Document representing a collection of users assigned to an access role.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of User_, required) The collection of users.

### User

Document representing a user.

*   `login` (_string_, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.
*   `password` (_string_) The password of the user.  
    Maximum length: 256. Example: `password`.
*   `email` (_string_, required) The email address of the user.  
    Maximum length: 256. Example: `admin@example.com`.
*   `firstName` (_string_) The first name of the user.  
    Maximum length: 256. Example: `John`.
*   `lastName` (_string_) The last name of the user.  
    Maximum length: 256. Example: `Doe`.
*   `externalId` (_string_) The external identifier for the user.  
    Maximum length: 256. Example: `ext-12345`.
*   `disabled` (_boolean_) Indicates whether the user is disabled.  
    Example: `false`.
*   `locked` (_boolean_) Indicates whether the user is locked.  
    Example: `false`.
*   `lastLoginDate` (_string (date)_) The date of the user's last login.  
    Example: `2024-10-14`.
*   `passwordExpirationDate` (_string (date-time)_) The date and time when the user's password expires.  
    Example: `2025-01-14T00:00:00.000Z`.
*   `passwordModificationDate` (_string (date-time)_) The date and time when the user's password was last modified.  
    Example: `2024-10-14T10:00:00.000Z`.
*   `preferredDataLocale` (_object_) The preferred data locale for the user.
    
    Includes all fields of `LocaleCode`.
    
*   `preferredUiLocale` (_object_) The preferred UI locale for the user.
    
    Includes all fields of `LocaleCode`.
    
*   `roles` (_array of string_) The list of role identifiers assigned to the user.  
    Items: Maximum length: 256. Example: `Administrator`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### RoleModulePermissions

Document listing the module permissions assigned to a role, scoped to organization and site levels.

*   `organization` (_array of RoleModulePermission_) Organization-level module permissions. Each entry uses a single `value`.
*   `site` (_array of RoleModulePermission_) Site-level module permissions. Each entry uses a `values` map keyed by site ID.

### RoleFunctionalPermissions

Document listing the functional permissions assigned to a role, scoped to organization and site levels.

*   `organization` (_array of RoleFunctionalPermission_) Organization-level functional permissions. Each entry uses a single `value`.
*   `site` (_array of RoleFunctionalPermission_) Site-level functional permissions. Each entry uses a `values` map keyed by site ID.

### RoleLocalePermissions

Document listing the locale permissions assigned to a role (unscoped).

*   `unscoped` (_array of RoleLocalePermission_) Unscoped locale permissions. A permission for the "default" locale is mandatory.

### RoleWebdavPermissions

Document listing the WebDAV permissions assigned to a role (unscoped).

*   `unscoped` (_array of RoleWebdavPermission_) Unscoped WebDAV permissions.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### RoleModulePermission

Document representing a single module permission entry.

*   `name` (_string_, required) The related menu action name of the module permission.  
    Minimum length: 1. Maximum length: 256. Example: `jobschedules`.
*   `type` (_string_, required) The permission type. Always "module" for module permissions.  
    Minimum length: 1. Maximum length: 256. Example: `module`.
*   `application` (_string_, required) The permission application (e.g. "bm" for Business Manager, "csc" for Commerce Service Cloud).  
    Minimum length: 1. Maximum length: 256. Example: `bm`.
*   `system` (_boolean_) Indicates whether this is a system menu action. False for custom menu actions.  
    Example: `true`.
*   `value` (_string_) The non domain-specific permission value used in organization scope (e.g. ACCESS, READONLY).  
    Maximum length: 256. Example: `ACCESS`.
*   `values` (_object_) A map of site identifiers to permission values, used in site scope.
    
    Additional properties: `string`.
    
    Maximum length: 256. Example: `ACCESS`.
    
    _Example_
    
    ```
    {
      "SiteGenesis": "ACCESS",
      "RefArch": "ACCESS"
    }
    ```
    

### RoleFunctionalPermission

Document representing a single functional permission entry.

*   `name` (_string_, required) The name of the functional permission.  
    Minimum length: 1. Maximum length: 256. Example: `Delete_All_Catalogs`.
*   `type` (_string_, required) The permission type. Always "functional" for functional permissions.  
    Minimum length: 1. Maximum length: 256. Example: `functional`.
*   `value` (_string_) The non domain-specific permission value used in organization scope (e.g. ACCESS).  
    Maximum length: 256. Example: `ACCESS`.
*   `values` (_object_) A map of site identifiers to permission values, used in site scope.
    
    Additional properties: `string`.
    
    Maximum length: 256. Example: `ACCESS`.
    
    _Example_
    
    ```
    {
      "SiteGenesis": "ACCESS"
    }
    ```
    

### RoleLocalePermission

Document representing a single locale permission entry.

*   `localeId` (_object_, required) The related locale id of the locale permission.
    
    Includes all fields of `LocaleCode`.
    
*   `type` (_string_, required) The permission type. Always "locale" for locale permissions.  
    Minimum length: 1. Maximum length: 256. Example: `locale`.
*   `value` (_string_) The non domain-specific permission value (e.g. ACCESS, READONLY).  
    Maximum length: 256. Example: `ACCESS`.
*   `values` (_object_) A map of domain identifiers to permission values.
    
    Additional properties: `string`.
    
    Maximum length: 256. Example: `ACCESS`.
    

### RoleWebdavPermission

Document representing a single WebDAV permission entry.

*   `folder` (_string_, required) The WebDAV folder path for this permission.  
    Minimum length: 1. Maximum length: 256. Example: `/catalogs/apparel-catalog`.
*   `type` (_string_, required) The permission type. Always "webdav" for WebDAV permissions.  
    Minimum length: 1. Maximum length: 256. Example: `webdav`.
*   `value` (_string_) The non domain-specific permission value (e.g. ACCESS, READONLY).  
    Maximum length: 256. Example: `ACCESS`.
*   `values` (_object_) A map of domain identifiers to permission values.
    
    Additional properties: `string`.
    
    Maximum length: 256. Example: `ACCESS`.
    

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "value": {
    "must": [
      {
        "textQuery": {
          "fields": [
            "couponId"
          ],
          "searchPhrase": "DEAL"
        }
      },
      {
        "textQuery": {
          "fields": [
            "description"
          ],
          "searchPhrase": "Big bargain deal"
        }
      }
    ],
    "mustNot": [
      {
        "termQuery": {
          "fields": [
            "enabled"
          ],
          "operator": "is",
          "values": [
            false
          ]
        }
      }
    ]
  }
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "value": {
    "operator": "and",
    "filters": [
      {
        "termFilter": {
          "field": "id",
          "operator": "is",
          "values": [
            "myId"
          ]
        }
      },
      {
        "termFilter": {
          "field": "couponId",
          "operator": "is",
          "values": [
            "couponOne"
          ]
        }
      }
    ]
  }
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=1da4ac6a130c000198b79a33d2dce27b7a3f7eba5539003d6fe114a0f67caf09 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-base-path.md -->

# Route Requests to a Single MRT Environment with Environment Base Paths

Consider environment base paths when planning your storefront project with multiple Managed Runtime (MRT) environments and a single domain. To route requests to the correct MRT environment via eCDN, set up environment base paths for each MRT environment. Also, use an environment base path to host the storefront within a specific subpath of a website.

This example diagram shows that two base paths are set up for the `www.example.com` domain. Each base path points to a distinct MRT environment.

![Example of a storefront with two base paths and two MRT environments](https://developer.salesforce.com/docs/media/sfnext/sfnext-base-path-diag-example.com.png '{"class": "image-xl"}')

An organization with a single domain can host multiple storefronts for various uses. One example is offering a storefront for each locale. For example, Northern Trail Outfitters (NTO) has multiple locations and has multiple storefront URLs for each region. `www.northerntrailoutfitters.com/us/retail` is for the US region and `www.northerntrailoutfitters.com/ca/retail` is for the Canadian region. Set up two base paths: `us` and `ca`. Both URLs use the same domain, `www.northerntrailoutfitters.com`, but the base paths map them to distinct MRT environments.

**note:** If a storefront provides all locales within a single MRT environment, use multisite instead of base paths. See [Configure Multisite URLs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-multi-site.md).

Another example is a website that hosts the storefront only in a subpath. For example, `www.example.com` is the main site with pages showing content. It contains one storefront that's available under a specific path: `www.example.com/shop`. This path corresponds to an environment base path of `/shop`. The base path points to an MRT environment.

## Configure Base Paths

Configure base paths in `config.server.ts` under `runtime.ssrParameters.envBasePath`:

```typescript
// config.server.ts
export default {
  runtime: {
    ssrParameters: {
      ssrFunctionNodeVersion: "24.x",
      envBasePath: "/storefront-a",
    },
  },
  app: {
    /* ... */
  },
};
```

## See Also

- [Managed Runtime Overview](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-overview.md)
- [MRT Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md)

<!-- document id=01b2d1c77fcd541ff8a5c1af30fb9e6592e135af9a356dd00a67f7beb7040093 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/routing.md -->

# Routing

When a user makes a request on your storefront domain, it is handled by an Express.js handler named `render` that is defined in `pwa-kit-react-sdk/ssr/server/react-rendering`. The handler chooses a component to render in response. This type of component is called a route. The routes that are available for rendering are defined in an array of objects called `routes` in `app/routes.jsx`.

The routes array follows the [route configuration shape](https://www.npmjs.com/package/react-router-config/v/5.1.0#route-configuration-shape), as defined by React Router. Each object in the `routes` array can have the following properties:

| Key       | Type                                                                  | Description                                                                  | Reference Docs                                                                                        |
| :-------- | :-------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
| path      | An Express-style string, an array of strings, or a regular expression | The path that is compared to the incoming request path for a potential match | [React Router API → Route component → path](https://v5.reactrouter.com/core/api/Route/component)      |
| component | Function (imported into `routes.jsx`)                                 | Component to render if the path matches the request                          | [React Router API → Route component → component](https://v5.reactrouter.com/core/api/Route/component) |
| exact     | Boolean                                                               | Determines whether the path must be an exact match or not                    | [React Router API → Route component → exact](https://v5.reactrouter.com/core/api/Route/exact-bool)    |

A newly generated project already includes objects in the `routes` array for many standard ecommerce pages, such as home, PLP, and PDP.

## React Router

But how does your React app choose the right component to render for any given request? We use the [React Router](https://v5.reactrouter.com/web/guides/quick-start) library to search sequentially through the route configuration objects in the `routes` array until it finds a `path` string that matches the requested path.

React Router gives you lots of options for constructing your `path` strings. You can specify more than one path for the same component and use regular expressions to match paths that follow a pattern.

React Router is also used throughout the Retail React App to implement navigation. For example, all hyperlinks use React Router’s `Link` component. React Router offers other components that give you access to browser history, query parameters, and more.

To learn more about using React Router, see the [official documentation](https://v5.reactrouter.com/web/guides/quick-start). (Stick to the documentation for version 5 because other versions use a different pattern matching system.)

## routeComponent

Each component specified in the `routes` array is automatically enhanced by the `routeComponent` function, a [higher-order component](https://reactjs.org/docs/higher-order-components.html) from the PWA Kit React SDK. The base class that is used to construct `routeComponent` defines several static methods, including two important ones that storefront developers can customize: `getProps` and `shouldGetProps`.

### getProps

The `getProps` method is used to supply data fetched from API requests, to `routeComponent` via the `props` object.

When `routeComponent` enhances a component from the `routes` array, it looks inside the component’s properties for a function named `getProps`. If you define a function there, it is exposed as a method of the enhanced component. You don’t have to define the function for every component in the `routes` array, only the ones where you fetch data before rendering them.

The `getProps` function that you define is expected to return a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). When the promise settles, its resolved value is passed to the enhanced component through the `props` object when the component is rendered.

When a component from the `routes` array is rendered, the component’s `getProps` method is supplied with a single JavaScript object. This object has the following properties, depending on the rendering context:

| Key        | Type   | Description                                                                                                                                                                                                                                              | Availability                     | More Information                                                                      |
| :--------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- | :------------------------------------------------------------------------------------ |
| `params`   | Object | Contains object properties that correspond to the named route parameters in an Express-style route string. Example: If you have the route `/user/:name`, then the value of `:name` in the request path is available as params.name. Default value: `{}`. | Both client side and server side | [Express API → Request → req.params](https://expressjs.com/en/4x/api.html#req.params) |
| `req`      | Object | A version of Node’s request object enhanced by Express. Represents the HTTP request and with properties for the query string, parameters, body, HTTP headers, and more.                                                                                  | Server side only                 | [Express API → Request](https://expressjs.com/en/4x/api.html#req)                     |
| `res`      | Object | Represents the HTTP response that an Express app sends when it gets an HTTP request.                                                                                                                                                                     | Server side only                 | [Express API → Response](https://expressjs.com/en/4x/api.html#res)                    |
| `location` | String | The URL of the request.                                                                                                                                                                                                                                  | Both client side and server side | Not part of the Express API                                                           |

**note:** - As of v3.0.0, we introduced a new data fetching strategy called `withReactQuery` that you can use instead of `getProps`.
- You can use both `withReactQuery` and `withLegacyGetProps` at the same time.
- `getProps` and `shouldGetProps` were removed from the default template of pages of the Retail React App, but aren’t deprecated. Long-term support for these methods remains.

See [Upgrade to v3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v3.md).

### Handling Errors

To handle errors in a `getProps` function, you have two options.

The first option is to throw an `HTTPError` object, which can be imported from `pwa-kit-react-sdk/ssr/universal/errors`. When you throw an `HTTPError`, a dedicated `Error` component is rendered.

The second option is to use props to inform the rendered component of the error so that it can be used in custom error-handling logic.

Here’s an example that uses both error-handling approaches:

```javascript
const ProductDetails = ({name, errorProductNotFound}) => (
  <h1>{errorProductNotFound ? 'Product Not Found' : name}</h1>
)
ProductDetails.getProps = async ({res}) => {
  const response = await fetch(`https://httpbin.org/status/404`)
  if (!response.ok) {
    if (response.status !== 404) {
      throw new HTTPError(response.status, response.statusText)
    }
    res && res.status(404)
    return {errorProductNotFound: true}
  }
  const data = await response.json()
  return data
}
```

### Writing getProps Functions

The object returned by `getProps` is serialized and embedded in the rendered HTML via an object called `__PRELOADED_STATE__` in the page source.

To keep the size of the rendered HTML down, be selective in what data to return in `getProps`. For example, avoid returning the whole response from an API request, if possible.

To preview the version of the page that is rendered on the server side in your browser, append `?__server_only` to the URL. This query parameter stops the [hydration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/%3Chttps://en.wikipedia.org/wiki/Hydration_(web_development)>) process so that the browser won’t take over rendering, leaving the page unchanged after server-side rendering. To see a pretty-printed version of the `__PRELOADED_STATE__` object, add `?__server_only&__pretty_print` to the query string.

When users navigate to subsequent pages during client-side rendering, the page is rendered immediately. Since rendering can happen while `getProps` is still fetching data, always write conditional code in your components to handle undefined props. Also remember to render a placeholder component (like [Skeleton](https://www.chakra-ui.com/docs/components/skeleton) from Chakra UI) while props are undefined.

On the client side, your component’s `render` method is called before and after `getProps` resolves. Use the `isLoading` prop passed to your component to decide whether to render a loading screen or not.

When making multiple HTTP requests in `getProps`, try to make them in parallel. If you can’t make them in parallel, consider moving them to client-side rendering.

If you only want to fetch data on the client side, use [React hooks](https://reactjs.org/docs/hooks-overview.html) in your component instead of `getProps`.

If you want to run the same code for all routes, you can define a `getProps` function that belongs to the `App` component, which is one of the **special components**. Special components are used to add functionality that is shared across multiple routes. To learn more about the [App component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/special-components.md#app) and other special components, see our guide to [Special Components](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/special-components.md).

### shouldGetProps

The `shouldGetProps` method controls when to call the `getProps` method. During server-side rendering, `shouldGetProps` is called only one time. During client-side rendering, it’s called every time the React lifecycle method `componentDidUpdate` is called.

By default, `getProps` calls `getProps` every time the value of `location.pathname` changes. You can override the default behavior for each component in the `routes` array by defining your own function called `shouldGetProps` as a property of the component. You can customize `shouldGetProps` to inspect the request and only call `getProps` for certain requests.

## Next Steps

Get a deeper understanding of routing by reviewing source code. Here are some key files to check out in the Retail React App:

- `app/routes.jsx`: demonstrates the Express-style syntax for path matching, including named route parameters.
- `app/pages/product-detail/index.jsx`: this sample component for the PDP includes custom functions for both `getProps` and `shouldGetProps`.
- `app/components/_app_config/index.jsx`: includes extensive configuration code and an app-wide `getProps` function.

For an alternative routing approach, check out [URL Resolution](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-resolution.html).

As you read through the PWA Kit documentation, don’t miss the architecture guide for [The Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md).

<!-- document id=d02f9f52f7db84fdd216927177d09483cf29c704a927c03e2ec50c7d4c7a59c9 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-routing.md -->

# Routing Differences with PWA Kit

PWA Kit uses React Router 5 with programmatic route arrays and manual splitting patterns. Storefront Next uses React Router 7 file-based routing with native nested layouts, typed loaders/actions, and automatic route-level splitting. Migrating generally means converting centralized route configuration into route files and moving route data logic into exports.

## Key Differences

| Aspect           | PWA Kit                              | Storefront Next                                                                                           |
| ---------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| Router Version   | React Router 5                       | React Router 7 (framework mode)                                                                           |
| Route Definition | Programmatic (array in `routes.jsx`) | File-based (files in `routes/`)                                                                           |
| Code Splitting   | Manual via `@loadable/component`     | Automatic per route file                                                                                  |
| Data Fetching    | Inside components (hooks)            | Outside components (`loader`/`clientLoader`)                                                              |
| Loading States   | Manual `isLoading` flags             | Declarative via Suspense                                                                                  |
| Nested Layouts   | Manual component composition         | Built-in via `<Outlet />`                                                                                 |
| Resource Routes  | Express routes in `ssr.js`           | Action files (`action.*.tsx`)                                                                             |
| Multisite URLs   | `configureRoutes()` expansion        | Declarative config in `config.server.ts` (`url.prefix`, `url.search`) with automatic detection middleware |
| Type Safety      | JavaScript                           | TypeScript with typed loaders                                                                             |

## Route Definition Comparison

PWA Kit:

```javascript
// Centralized route array
export const routes = [
  { path: "/product/:productId", component: ProductDetail },
  { path: "/account", component: Account },
  { path: "/account/orders", component: Orders },
];
```

Storefront Next:

```
src/routes/
├── product.$productId.tsx    # /product/:productId
├── account.tsx               # /account (layout)
├── account._index.tsx        # /account (index)
└── account.orders.tsx        # /account/orders
```

## Navigation API Comparison

**PWA Kit (React Router 5):**

```javascript
import { useHistory, useParams } from "react-router-dom";

const history = useHistory();
history.push("/cart");
history.replace("/new-path");
```

**Storefront Next (React Router 7):**

```typescript
import { useNavigate, useParams } from "react-router";

const navigate = useNavigate();
navigate("/cart");
navigate("/new-path", { replace: true });
```

## Key Similarities

1. Dynamic Parameters: Both use `:param` syntax (PWA Kit in path string, Storefront Next in file name with `$`).
2. Catch-All Routes: Both support wildcard routes (`*` in PWA Kit, `$.tsx` in Storefront Next).
3. Programmatic Navigation: Both provide hooks for imperative navigation.
4. Route Parameter Access: Both provide `useParams()` hook for accessing URL parameters.

## Storefront Conversion Considerations

1. Route File Creation: Each route in `routes.jsx` becomes a separate file in `src/routes/`.
2. Naming Convention: Learn the flat routes naming pattern (`$` for params, `.` for nesting).
3. Data Fetching: Move data fetching from component hooks to `loader`/`clientLoader` exports.
4. Layout Routes: Use layout routes with `<Outlet />` instead of manual nesting.
5. Resource Routes: Convert Express API routes to `action.*.tsx` files.
6. Loading States: Replace `isLoading` checks with Suspense boundaries via `createPage`.

## References

- [React Router 5 Documentation](https://v5.reactrouter.com/)
- [React Router 7 Documentation](https://reactrouter.com/)
- [React Router Flat Routes](https://reactrouter.com/how-to/file-route-conventions)
- [Loadable Components](https://loadable-components.com/)

<!-- document id=fb0f223a92b983a66610cd96f6641878d2db6066332cbf1a1cd2acc8a984d68b url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-api-integration.md -->

# Salesforce B2C Commerce API (SCAPI) Client

Storefront Next includes a type-safe API client for calling Salesforce B2C Commerce Shopper APIs, including custom APIs, from your storefront. This client provides full TypeScript support with autocomplete, type checking, and semantic operation names.

## What Is SCAPI?

The B2C Commerce API (SCAPI) is a collection of RESTful APIs for interacting with B2C Commerce instances. Also known as Salesforce Commerce API or simply Commerce API, it provides endpoints for products, search, baskets, customers, orders, and so on. Create custom APIs to modify the built-in SCAPI endpoints. For example, add filters or modify responses before they get sent back to the calling application. See [B2C Commerce API (SCAPI)](https://developer.salesforce.com/docs/commerce/commerce-api/guides/scapi-get-started.md) and [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/custom-apis.md).

The SCAPI client in `@salesforce/storefront-next-runtime/scapi` wraps these APIs with:

- Minimal bundle size: Built on [openapi-fetch](https://openapi-ts.dev/openapi-fetch/), a lightweight fetch client with near-zero runtime overhead.
- Type-safe operations: Full TypeScript inference from OpenAPI specifications.
- Semantic method names: Call `getProduct()` instead of `GET /products/{id}`.
- Automatic parameter injection: Common parameters like `organizationId` and `siteId` are handled for you.
- Built-in authentication helpers: Guest login, registered login, social login, passwordless login, token refresh, and password reset.

## Creating API Clients

In a Storefront Next project, use the template `createApiClients()` wrapper in route loaders and actions. The wrapper reads site configuration, credentials, and locale from context. It also registers template middleware, including non-personalized response classification.

```typescript
import { createApiClients } from "@/lib/api-clients.server";

export async function loader({ context }: LoaderFunctionArgs) {
  const clients = createApiClients(context);
  // Call SCAPI with clients.
}
```

When you create a storefront in Business Manager, a private SLAS client ID and secret are created for you. See [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md) or [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md).

### Configuration Options

The template `createApiClients()` wrapper reads these values from the Storefront Next configuration and request context. If you create clients directly, pass the values to `createCommerceApiClients()`.

| Parameter        | Required | Description                                                                              |
| ---------------- | -------- | ---------------------------------------------------------------------------------------- |
| `baseUrl`        | Yes      | Commerce API base URL                                                                    |
| `organizationId` | Yes      | Your organization ID (automatically added to path parameters)                            |
| `siteId`         | Yes      | Your site ID (automatically added to query parameters)                                   |
| `clientId`       | Yes      | Shopper Login and Session API (SLAS) client ID                                           |
| `redirectUri`    | Yes      | OAuth redirect URI                                                                       |
| `locale`         | No       | Locale for requests (for example, `en-US`)                                               |
| `clientSecret`   | No       | SLAS client secret. See [Public vs Private SLAS Client](#public-vs-private-slas-client). |

### Public vs Private SLAS Client

The `clientSecret` parameter determines which SLAS authentication flow the client uses.

- Public client (no secret): When `clientSecret` is omitted, the auth helpers use the public client flow with Proof Key for Code Exchange (PKCE). This behavior is suitable for client-side apps where the secret can't be kept secure.

- Private client (with secret): When `clientSecret` is provided, the auth helpers use the private client flow. This behavior enables extra features, such as passwordless login, and is suitable for server-side apps where the secret can be kept secure.

## Replace the Template API Layer

Use `createCommerceApiClients()` directly only when you replace or bypass the template API layer. Configure the clients and required middleware yourself.

```typescript
import { createCommerceApiClients } from "@salesforce/storefront-next-runtime/scapi";

const clients = createCommerceApiClients({
  baseUrl: "https://shortcode.api.commercecloud.salesforce.com",
  organizationId: "f_ecom_xxx",
  siteId: "RefArch",
  clientId: "your-slas-client-id",
  redirectUri: "https://yoursite.com/callback",
  locale: "en-US", // Optional
  clientSecret: process.env.COMMERCE_API_SLAS_SECRET, // Optional, for private SLAS
});
```

### Adding the Access Token to Requests

Clients created outside the template `createApiClients()` wrapper don't receive the template authentication middleware. After you get an access token, add it to API requests using middleware. Skip SLAS authentication endpoints because they handle their own authorization.

```typescript
import { SLAS_AUTH_ENDPOINTS } from "@salesforce/storefront-next-runtime/scapi";

clients.use({
  onRequest({ request }) {
    // Skip auth header for SLAS endpoints (they handle their own auth)
    const url = new URL(request.url);
    const isSlasAuthEndpoint = SLAS_AUTH_ENDPOINTS.some((path) => url.pathname.includes(path));
    if (isSlasAuthEndpoint) {
      return request;
    }

    request.headers.set("Authorization", `Bearer ${accessToken}`);
    return request;
  },
});
```

## Authentication

The Storefront Next template uses server middleware to manage guest login, token refresh, registered sessions, social login, cookies, and access-token injection. For the normal template workflow, use the template authentication services and routes. See [Authentication and Session Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storage-sessions.md).

The client also includes an `auth` namespace with low-level SLAS helpers. These helpers are intentionally **stateless**. They don't store tokens, update template sessions, write cookies, or perform related cleanup. Use them as building blocks only when you implement a custom server-side authentication workflow.

### Guest Login

The template creates guest sessions automatically. In a custom authentication workflow, call the helper and store the returned session with your server-side session implementation.

```typescript
const tokens = await clients.auth.loginAsGuest();
// Returns: { access_token, refresh_token, usid, ... }
```

### Registered User Login

After a successful login, store the returned session with your server-side session implementation.

```typescript
const tokens = await clients.auth.loginWithCredentials({
  username: "user@example.com",
  password: "password123",
});
```

### Token Refresh

The template refreshes expired access tokens automatically. In a custom authentication workflow, persist the refreshed session returned by this helper.

```typescript
const newTokens = await clients.auth.refreshToken({
  refreshToken: storedRefreshToken,
});
```

### Logout

This helper revokes SLAS tokens. A complete logout must also clear the application session and related shopper state.

```typescript
await clients.auth.logout({
  accessToken: currentAccessToken,
  refreshToken: currentRefreshToken,
});
```

### Social Login

The template social-login workflow stores the code verifier in a secure, HTTP-only cookie and persists the returned tokens. A custom workflow must provide equivalent secure storage and session updates.

```typescript
// Step 1: Get authorization URL
const { url, codeVerifier } = await clients.auth.social.getAuthorizationUrl({
  hint: "google", // or 'facebook', 'apple', etc.
});

// Store codeVerifier securely, then redirect user to url

// Step 2: Exchange code (after user returns)
const tokens = await clients.auth.social.exchangeCode({
  code: authorizationCode,
  codeVerifier: storedCodeVerifier,
  redirectUri: "https://yoursite.com/callback",
});
```

## Fetching Data

The client automatically includes `organizationId` and `siteId` in all requests, so you only provide operation-specific parameters.

### Fetching a Product

```typescript
const { data: product } = await clients.shopperProducts.getProduct({
  params: {
    path: { id: "product-123" },
    query: {
      expand: ["availability", "prices", "variations", "images"],
      allImages: true,
    },
  },
});
```

### Search Products

```typescript
const { data: searchResults } = await clients.shopperSearch.productSearch({
  params: {
    query: {
      q: "shoes",
      limit: 24,
      offset: 0,
      sort: "best-matches",
      expand: ["prices", "images", "variations"],
    },
  },
});
```

### Fetching Categories

```typescript
const { data: category } = await clients.shopperProducts.getCategory({
  params: {
    path: { id: "mens-clothing" },
    query: { levels: 2 },
  },
});
```

## Mutations

Use the appropriate client method to perform mutations like adding items to a basket or updating customer information.

### Adding an Item to Basket

```typescript
const { data: updatedBasket } = await clients.shopperBasketsV2.addItemToBasket({
  params: {
    path: { basketId: "basket-123" },
  },
  body: [
    {
      productId: "product-456",
      quantity: 2,
    },
  ],
});
```

### Updating a Basket Item

```typescript
const { data: updatedBasket } = await clients.shopperBasketsV2.updateItemInBasket({
  params: {
    path: {
      basketId: "basket-123",
      itemId: "item-789",
    },
  },
  body: {
    quantity: 3,
  },
});
```

## Classify Non-Personalized Responses

A non-personalized response has the same HTTP status and response body for equivalent authorized requests against the same underlying commerce state, regardless of shopper identity or Shopper Context. Its fields and headers contain no shopper-specific data or personally identifiable information (PII). Non-sensitive diagnostic metadata can differ.

The template `createApiClients()` client factory registers middleware that evaluates server-side SCAPI requests for non-personalized response classification. Requests that use `createCommerceApiClients()` directly don't use the template policy unless you register the middleware yourself. Existing projects must adopt the policy and classification middleware modules, then add client registration and diagnostics to `src/lib/api-clients.server.ts`. Updating the `@salesforce/storefront-next-runtime` package alone doesn't add the policy.

SCAPI can store eligible `GET` responses in the web-tier cache and the content delivery network (CDN) cache. [Enable page caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#enable-caching) in Business Manager. The caches then operate automatically. For information about cache eligibility, time-to-live values, and cache behavior, see [SCAPI Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html).

The `personalized=none` query parameter is a separate instruction. It tells SCAPI to treat the request as non-personalized. SCAPI skips Shopper Context. SCAPI suppresses hook calls to `setVaryBy()`. The parameter doesn't prevent hooks from changing the response.

Storefront Next keeps this safety decision in `src/lib/scapi/non-personalized-response-policy.server.ts`. This policy runs only on the server. The classification middleware examines the request after Storefront Next applies defaults and serializes parameters. It also examines changes from template request middleware. The supported explicit value is `personalized=none`. If the serialized request already contains a `personalized` value, including `none`, the middleware keeps the value and doesn't run automatic classification.

When the policy returns `true`, the middleware adds `personalized=none`. When the policy returns `false` or fails, the middleware forwards the request unchanged and doesn't add `personalized=none`. The unchanged request is **unclassified**: Storefront Next makes no assertion that its response is personalized or non-personalized. SCAPI then applies its normal implicit-caching rules to the request. An eligible request can still use implicit caching when page caching is enabled.

Classification doesn't enable caching or select a cache time-to-live. It doesn't prove that a cache stored the response.

### Review Response Safety

Before you rely on the default policy, review each built-in transport that the policy classifies. Review all hooks, custom response fields, response headers, custom request headers, and other inputs that can change the response. Narrow or disable a default classification when a customization can vary the response by shopper.

Classify a response as non-personalized only if it is safe for all shoppers.

For an automatically evaluated request whose response contains PII, shopper identifiers, or other shopper-specific data, return `false` from the policy. The middleware then forwards the request without adding `personalized=none`. If a call site sets `personalized=none` explicitly, remove that value because the explicit value bypasses the policy. This rule applies to customer, basket, order, payment, and hook-added data. The policy can't identify every custom hook, custom field, custom header, override, or custom API. Review these customizations before you change the policy.

**note:** A client override replaces a built-in Storefront Next client with one generated from a different schema. A custom client adds a client for a new [SCAPI Custom API](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html).

For example, the default Product policy accepts an explicit list of reviewed non-personalized expansions. It rejects the same request when the list includes `prices`.

```typescript
// The default policy can classify this request as non-personalized.
await clients.shopperProducts.getProduct({
  params: {
    path: { id: "product-123" },
    query: { expand: ["images", "variations"] },
  },
});

// The default policy leaves this request unclassified.
await clients.shopperProducts.getProduct({
  params: {
    path: { id: "product-123" },
    query: { expand: ["images", "prices"] },
  },
});
```

The default policy fails closed. It classifies only exact, reviewed built-in transports. It applies these additional rules:

- Product and Product Search requests require an explicit list of reviewed non-personalized expansions. Requests with omitted, empty, unknown, or case-mismatched expansions stay unclassified. Requests with `prices` or `promotions` expansions also stay unclassified. The policy accepts the `none` expansion only by itself.
- Page Designer requests stay unclassified because visibility rules and component logic can vary by shopper.
- SCAPI schema overrides and custom clients stay unclassified, including overrides that keep a built-in client key or path.
- Personal, transactional, non-`GET`, alternate-destination, unknown, and future operations stay unclassified.

Review the policy module for the current transport identities and expansion lists. A template update can change the default policy. Your existing project keeps its policy until you adopt the update.

### Customize the Policy

Edit or replace `src/lib/scapi/non-personalized-response-policy.server.ts` to approve an override or custom client. Match the exact client key and provenance. Match the expected base path, the final request origin and path, the HTTP method, and the schema path. Also match all request inputs that can change the response. Return `false` for unknown values. Don't use a policy that returns `true` for every `GET` request. The middleware also processes personal, transactional, overridden, custom, and future operations.

For example, an exact predicate for a reviewed custom client can check its provenance, path, method, and destination. This predicate is only a starting point. Also check each query value, site, locale, custom header, hook, and response field that can change the response.

```typescript
import type { NonPersonalizedResponseClassifier } from "@/lib/scapi/non-personalized-response.server";

const isReviewedLoyaltyRequest: NonPersonalizedResponseClassifier = (input) => {
  const destination = new URL(input.destination);
  const request = new URL(input.request.url);

  return (
    input.client === "loyalty" &&
    input.provenance === "custom" &&
    input.clientBasePath === "/custom/loyalty/v1" &&
    input.schemaPath === "/offers" &&
    input.method === "GET" &&
    request.origin === destination.origin &&
    request.pathname === `${destination.pathname.replace(/\/+$/, "")}${input.schemaPath}`
  );
};
```

To disable automatic classification, return `false` from the policy or remove the middleware registration from `src/lib/api-clients.server.ts`.

An explicit `personalized=none` value bypasses automatic classification. Apply the same safety review before you set this value on an individual request. Don't use an explicit value to override a policy rejection. When you adopt the central policy, review existing call sites and remove explicit values that the policy replaces.

Classification runs after template request middleware. Per-call middleware runs after classification. Don't use per-call middleware to change a destination, path, query parameter, or header that can change the response. If you can't make the change before classification, leave the request unclassified.

When you change the policy, update `src/lib/scapi/non-personalized-response-policy.server.test.ts`. For each custom rule, test at least one request that the policy accepts and one request that it rejects. Run the focused tests from the Storefront Next project root.

```bash
pnpm test src/lib/scapi/non-personalized-response-policy.server.test.ts
```

### Verify Classification and Cache Status

1. Run `pnpm dev:log`.
2. Find the `[ApiClients] fetch` debug entry.
3. Check `personalizationMode`. The value `automatic-none` means that classification added `personalized=none`. The value `explicit` means that the request contained `personalized` at classification time. The value `absent` means that the middleware didn't record an automatic or explicit value.
4. If an expected classification is absent, find `[ApiClients] non-personalized response classification failed`. A classifier failure leaves the request unchanged.
5. If no failure entry exists, compare the request with the policy. Check the client key, provenance, base path, destination, HTTP method, schema path, and expansions. An `absent` value is often the expected fail-closed result.
6. Check `apiParams` for the serialized query. The query includes values such as `personalized`, `expand`, `siteId`, and `locale`. These values explain classification only if per-call middleware didn't change them. If the values don't agree with `personalizationMode`, inspect per-call middleware.
7. Inspect `sfdc_cache_status` for web-tier cache behavior. Inspect `cf-cache-status` for CDN cache behavior.

For example, this sanitized debug entry shows that automatic classification added `personalized=none`. Actual `apiParams` values can contain sensitive shopper data.

```text
[ApiClients] fetch GET /search/shopper-search/v1/.../product-search
status: 200
apiParams: { q: "example", expand: "images", personalized: "none" }
personalizationMode: "automatic-none"
```

Serialized query parameter values in debug logs can contain sensitive shopper data. Use debug logging briefly in a controlled environment. Cache-status headers report cache behavior. They don't prove that a response is safe for all shoppers.

## Available API Clients

The client provides access to all SCAPI endpoints.

| Client                    | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `shopperAvailability`     | Product availability and inventory                             |
| `shopperProducts`         | Products, categories, and catalog data                         |
| `shopperSearch`           | Product search and suggestions                                 |
| `shopperBasketsV1`        | Basket operations (legacy)                                     |
| `shopperBasketsV2`        | Basket operations (current)                                    |
| `shopperCustomers`        | Customer accounts and profiles                                 |
| `shopperOrders`           | Order history and details                                      |
| `shopperLogin`            | SLAS authentication                                            |
| `shopperPromotions`       | Promotions and campaigns                                       |
| `shopperContext`          | Shopper session context                                        |
| `shopperStores`           | Store locator                                                  |
| `shopperExperience`       | Page Designer content                                          |
| `shopperGiftCertificates` | Gift certificate operations                                    |
| `shopperSeo`              | SEO metadata                                                   |
| `shopperConsents`         | Customer consent management                                    |
| `auth`                    | Authentication helpers. See [Authentication](#authentication). |

## TypeScript Types

The client exports TypeScript types for all API schemas and operations.

```typescript
import type { ShopperProducts, ShopperSearch } from "@salesforce/storefront-next-runtime/scapi";

// Use schema types for data
type Product = ShopperProducts.schemas["Product"];
type Category = ShopperProducts.schemas["Category"];
type SearchResult = ShopperSearch.schemas["ProductSearchResult"];

// Use operation types for parameters
type SearchParams = ShopperSearch.operations["productSearch"]["parameters"]["query"];
```

## Error Handling

API errors throw an `ApiError` with detailed information:

```typescript
import { ApiError } from "@salesforce/storefront-next-runtime/scapi";

try {
  const { data } = await clients.shopperProducts.getProduct(options);
} catch (error) {
  if (error instanceof ApiError) {
    console.error("Status:", error.status); // 404
    console.error("Message:", error.body.detail); // "Product not found"
    console.error("URL:", error.url); // Request URL
    console.error("Method:", error.method); // "GET"
  }
}
```

### ApiError Properties

| Property     | Type          | Description           |
| ------------ | ------------- | --------------------- |
| `status`     | `number`      | HTTP status code      |
| `statusText` | `string`      | HTTP status message   |
| `body`       | `ErrorDetail` | Parsed error response |
| `rawBody`    | `string`      | Raw response text     |
| `headers`    | `Headers`     | Response headers      |
| `url`        | `string`      | Request URL           |
| `method`     | `string`      | HTTP method           |

## Response Format

All operations return both the parsed data and the raw response.

```typescript
const { data, response } = await clients.shopperProducts.getProduct(options);

// Typed data from the API
console.log(data.name);
console.log(data.price);

// Raw response for headers, status, etc.
console.log(response.headers.get("etag"));
console.log(response.status);
```

## Middleware

Add custom behavior to requests and responses:

```typescript
import type { Middleware } from "@salesforce/storefront-next-runtime/scapi";

const loggingMiddleware: Middleware = {
  onRequest({ request }) {
    console.log(`[API] ${request.method} ${request.url}`);
    return request;
  },
  onResponse({ response }) {
    console.log(`[API] ${response.status}`);
    return response;
  },
};

// Add to all clients
clients.use(loggingMiddleware);

// Or add to a specific client
clients.shopperProducts.use(loggingMiddleware);
```

## Custom APIs

[Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/custom-apis.md) let you extend SCAPI with your own endpoints. Storefront Next supports two ways to call a custom API from your storefront, and both reuse the same authentication and middleware patterns as the built-in shopper clients.

### Generate a Typed Client (Recommended)

Generate a fully typed client from your custom API's OpenAPI schema. You get autocomplete, parameter validation, and operation-name calls like `loyaltyClient.getLoyaltyInfo()` instead of hand-rolled paths.

Storefront Next's template app ships a `sfnext scapi` CLI that takes an OpenAPI 3 schema and generates the type definitions and operation map for you, then registers the client alongside the built-in shopper clients. See the template's [SCAPI guide](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/main/docs/README-SCAPI.md) for the project-level workflow.

An external project follows the same pattern with three components:

1. **Types and operation map** generated from the OpenAPI schema. The types are produced with [openapi-typescript](https://openapi-ts.dev/); the operation map records each operation's HTTP method and path so the client can dispatch by `operationId`.
2. **A typed client** built with `createOpenApiFetchClient` and wrapped with the runtime's `createClient` helper to expose operation-name methods.
3. **Auth middleware** registered with `.use()` — the same registration pattern shown in [Adding the Access Token to Requests](#adding-the-access-token-to-requests) earlier in this guide.

Declare the operation map `as const` so its `m` / `b` / `s` values stay literal — the proxy uses those literals to type each operation method's parameters and return value.

```typescript
// ./generated/loyalty-info.operations.ts (generated alongside the types)
export const BASE_PATH = "/organizations/{organizationId}" as const;
export const operations = {
  getLoyaltyInfo: { m: "GET" as const, b: BASE_PATH, s: "/customers" },
} as const;
```

```typescript
// loyalty-client.ts
import { createOpenApiFetchClient, createClient } from "@salesforce/storefront-next-runtime/scapi";
import type { paths } from "./generated/loyalty-info";
import { operations } from "./generated/loyalty-info.operations";

const base = createOpenApiFetchClient<paths>({
  // Stop before /organizations — createClient appends the operation map's
  // base path, which already includes /organizations/{organizationId}.
  baseUrl: "https://shortcode.api.commercecloud.salesforce.com/custom/loyalty-info/v1",
});

const loyaltyClient = createClient(base, operations, {
  organizationId: "f_ecom_xxx",
  siteId: "RefArch",
});

// Register an auth middleware the same way the built-in clients do — see
// [Adding the Access Token to Requests](#adding-the-access-token-to-requests).
loyaltyClient.use(authMiddleware);

const { data } = await loyaltyClient.getLoyaltyInfo({
  params: { query: { c_customer_id: "customer1" } },
});
// GET https://shortcode.api.commercecloud.salesforce.com/custom/loyalty-info/v1
//     /organizations/f_ecom_xxx/customers?siteId=RefArch&c_customer_id=customer1
```

### Call with `fetch` Directly

For one-off calls, or projects without a codegen step, call the endpoint directly with `fetch`. Pull `accessToken`, `organizationId`, `siteId`, and any other dynamic values from the same auth/session context the typed clients use, and let the `URL` API encode user-supplied query values for you.

```typescript
const url = new URL(
  `https://shortcode.api.commercecloud.salesforce.com/custom/loyalty-info/v1/organizations/${organizationId}/customers`,
);
url.searchParams.set("c_customer_id", customerId);
url.searchParams.set("siteId", siteId);

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const data = await response.json();
```

The native-fetch path skips the typed-client features above (TypeScript types, automatic `organizationId`/`siteId` injection, `ApiError` wrapping) — prefer the generated client for any custom API you call from more than one place.

## See Also

- [B2C Commerce API (SCAPI)](https://developer.salesforce.com/docs/commerce/commerce-api/guides/scapi-get-started.md) - Official SCAPI documentation
- [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/custom-apis.md) - Define your own SCAPI endpoints
- [openapi-fetch](https://openapi-ts.dev/openapi-fetch/) - The underlying fetch client library
- [openapi-typescript](https://openapi-ts.dev/) - Generate TypeScript types from an OpenAPI schema

<!-- document id=892f4a4b8a4e3b2665112b50df3473c8188b1d9b322e55200f058ada8fcb871a url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-address-mgmt-apis.md -->

# Salesforce Commerce Address Management API

Salesforce's Commerce Address Management APIs facilitate seamless handling of customer addresses within the platform. Integrating these APIs enhances the user experience by allowing customers to effortlessly manage their addresses, which is essential for smooth checkout and delivery processes.

Registered users can quickly manage their addresses on the My Profile page. The Webstore Account Addresses API allows a user to add a new address to their account associated with a webstore. With support for both POST and GET methods, this API enables users to enter new addresses as well as obtain and show their current address information on the account page. You can also update an address that is already in use or remove an address that is no longer needed by using the Webstore Account Address API. Both the PATCH and DELETE methods are also supported by this API.

## Use Case

Let's consider a scenario where a customer wants to manage their shipping addresses within their account.

![Diagram of the address management API workflow for B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/address_mgmt_api_workflow.png '{"class": "image-lg", "title": "Checkout Workflow"}')

The authenticated customer logs in and goes to the My Profile page, which displays the user account information, including any saved addresses. A GET request to the [Webstore Account Addresses API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm) fetches and displays a list of the customer's saved addresses. When the customer creates a new address, a POST request is made to the [Webstore Account Addresses API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm). If an existing address needs correction, the customer makes the necessary changes and saves them, triggering a PATCH request to the [Webstore Account Address API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm). Finally, the user can remove an address by making a DELETE request to the [Webstore Account Address API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm).

## Resources

Here’s a list of Commerce Address Management resources:

| Resource                                                                                                                                                                                                                        | Supported HTTP Methods | Description                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------- |
| [`/commerce/webstores/{webstoreId}/accounts​/accountId/addresses`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses.htm)                     | GET, POST              | Create a Commerce account address for a webstore, or retrieve a collection of addresses for a webstore account. |
| [`/commerce/webstores/{webstoreId}/accounts​/accountId/addresses/{addressId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm) | DELETE, PATCH          | Update or delete an address for a Commerce account associated with a webstore.                                  |

<!-- document id=8970599696e7e30f9ce250fc5b5662d59ce57bac62667f2a2fc0f8eb1fac57dd url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-analytics-ref.md -->

Salesforce Commerce Analytics API

# Salesforce Commerce Analytics API

This API retrieves details about key performance indicators (KPIs), including their associated data and insights.

**Version:** 66.0

## Servers

*   `https://{yourinstance}.salesforce.com/services/data/{version}`
    *   `version (default v66.0): v66.0, v65.0, v64.0, v63.0, v62.0`

## Operations

### GET commerceIntelligenceKPIsGet

`GET /commerce/intelligence/kpis`

Operation ID: `commerceIntelligenceKPIsGet`.

Retrieves a list of KPIs and the insights each KPI provides.

Fetches a list of KPIs and the insights each KPI supports.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `KPIMetaDataCollectionRepresentation`.
    
*   **400** Bad Request.
    
    Media type: `application/json`. Schema: `object`.
    
    *   `apiErrorCode` (_string_) The error code.
    *   `message` (_string_) The error message.

### GET commerceIntelligenceKPIDataGet

`GET /commerce/intelligence/kpis/{kpiName}`

Operation ID: `commerceIntelligenceKPIDataGet`.

Provides point-in-time data for KPIs based on the current time range, an optional previous time range, and webstore. If only startDateTime and endDateTime are specified, the value field shows the KPI and insight values within that period. If previousStartDate and previousEndDateTime are also provided, the previousValue field will be populated with data from the previous time range. Additionally, the API returns insights if requested, using the same filter criteria. It also returns the relative dashboard URL if the KPI and insight are part of any dashboard.

Retrieves KPI data for the specified time range. The API also returns insights data for the KPI when the appropriate query parameters are provided.

#### Parameters

*   `kpiName` (path, string, required) Name of the KPI.
    
    _Example_
    
    ```
    average_order_value
    ```
    
*   `webstoreId` (query, string, required) Required. Query the KPI and insight within the specific store context. If not specified, the KPI is calculated across all webstores for the org.
    
    _Example_
    
    ```
    0ZExx000000004DGAQ
    ```
    
*   `startDateTime` (query, string (date-time)) Optional. Specifies the start date and time for the current timeframe of the KPI and insights. The maximum supported range between the start and end dates is 180 days. If not provided, it defaults to 30 days prior to the current date.
    
    _Example_
    
    ```
    2018-03-20T09:12:28Z
    ```
    
*   `endDateTime` (query, string (date-time)) Optional. Specifies the end date and time for the current timeframe of the KPI and insights. If not provided, defaults to TODAY.
    
    _Example_
    
    ```
    2018-03-20T09:12:28Z
    ```
    
*   `previousStartDateTime` (query, string (date-time)) Optional. Specifies the start date and time for the previous timeframe of the KPI and insights. The maximum supported range between the start and end dates is 180 days. If previousStartDateTime is provided, previousEndDateTime must also be specified.
    
    _Example_
    
    ```
    2018-03-20T09:12:28Z
    ```
    
*   `previousEndDateTime` (query, string (date-time)) Optional. Specifies the end date and time for the previous timeframe of the KPI and insights. If previousEndDateTime is provided, previousStartDateTime must also be specified.
    
    _Example_
    
    ```
    2018-03-20T09:12:28Z
    ```
    
*   `insightNames` (query, string) Optional. Comma-separated list of insight names to include in the response, with a maximum of 10 insights.
    
    _Example_
    
    ```
    top_performing_products
    ```
    
*   `insightValueLimit` (query, integer) Optional. Specifies the maximum number of insight records to return. For instance, with an insightValueLimit of 3 for the top-performing products insight, the API returns 3 top-performing products. The maximum supported value is 10, and the default is 3 if not specified.
    
    _Example_
    
    ```
    3
    ```
    

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `KPIDataRepresentation`.
    
*   **400** Bad Request.
    
    Media type: `application/json`. Schema: `object`.
    
    *   `apiErrorCode` (_string_) The error code.
    *   `message` (_string_) The error message.
    
    _Example_
    
    ```
    {
      "Invalid endDateTime": {
        "$ref": "#/components/examples/InvalidEndDateTime"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "Invalid previousEndDateTime duration": {
        "$ref": "#/components/examples/InvalidPreviousEndDateTimeDuration"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "Invalid insightValueLimit": {
        "$ref": "#/components/examples/InvalidInsightValueLimit"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "Invalid previousEndDateTime": {
        "$ref": "#/components/examples/InvalidPreviousEndDateTime"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "Invalid previousStartDateTime": {
        "$ref": "#/components/examples/InvalidPreviousStartDateTime"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "InsightNames limit exceeded": {
        "$ref": "#/components/examples/InputInsightNamesLimitExceeded"
      }
    }
    ```
    
*   **404** KPI data resource not found.
    
    Media type: `application/json`. Schema: `object`.
    
    *   `apiErrorCode` (_string_) The error code.
    *   `message` (_string_) The error message.
    
    _Example_
    
    ```
    {
      "KPI name not found": {
        "$ref": "#/components/examples/KPINameNotFound"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "InsightName name not found": {
        "$ref": "#/components/examples/InsightNameNotFound"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "WebStore access denied": {
        "$ref": "#/components/examples/WebStoreAccessDenied"
      }
    }
    ```
    
    _Example_
    
    ```
    {
      "Commerce Intelligence not configured": {
        "$ref": "#/components/examples/CommerceIntelligenceNotConfigured"
      }
    }
    ```
    

## Schemas

### KPIMetaDataCollectionRepresentation

*   `kpis` (_array of KPIMetaDataRepresentation_)

### KPIDataRepresentation

*   `name` (_string_) API name of the KPI.  
    Allowed values: `average_order_value`, `gross_sales`, `total_number_of_orders`, `site_conversion_rate`.
    
    _Example_
    
    ```
    average_order_value
    ```
    
*   `value` (_number (double)_) KPI value for the specified time frame.
    
    _Example_
    
    ```
    1000
    ```
    
*   `previousValue` (_number (double)_) KPI value for the previous time frame.
    
    _Example_
    
    ```
    1001
    ```
    
*   `type` (_string_) Specifies the KPI value type. For example, for a KPI like gross\_sales, a "type" of CURRENCY means the "value" must be interpreted as currency.  
    Allowed values: `CURRENCY`, `NUMBER`.
    
    _Example_
    
    ```
    CURRENCY
    ```
    
*   `currencyISOCode` (_string_) Specifies the ISO currency code for the KPI data values.
    
    _Example_
    
    ```
    USD
    ```
    
*   `startDateTime` (_string (date-time)_) Specifies the start date and time for the current timeframe of the KPI and insight.
    
    _Example_
    
    ```
    2024-04-01T00:00:00Z
    ```
    
*   `endDateTime` (_string (date-time)_) Specifies the end date and time for the current timeframe of the KPI and insight.
    
    _Example_
    
    ```
    2024-05-01T00:00:00Z
    ```
    
*   `previousStartDateTime` (_string (date-time)_) Specifies the start date and time for the previous timeframe of the KPI and insight. If specified in the request, it will be included in the response.
    
    _Example_
    
    ```
    2024-03-01T00:00:00Z
    ```
    
*   `previousEndDateTime` (_string (date-time)_) Specifies the end date and time for the previous timeframe of the KPI and insight. If specified in the request, it will be included in the response.
    
    _Example_
    
    ```
    2024-04-01T00:00:00Z
    ```
    
*   `dashboardUrl` (_string_) Specifies the relative URL of the dashboard where the KPI is visualized.
    
    _Example_
    
    ```
    /lightning/n/standard-CommerceStores?target=intelligence&channelId=0ZESG000000np9T4AQ
    ```
    
*   `kpiSummary` (_string_) Localized, human-readable summary of the change in the KPI value.
    
    _Example_
    
    ```
    Average order value increased to $109.00 from $80.00 over the last month.
    ```
    
*   `insights` (_array of InsightRepresentation_)

### KPIMetaDataRepresentation

*   `name` (_string_) API name of the KPI.  
    Allowed values: `average_order_value`, `gross_sales`, `total_number_of_orders`, `site_conversion_rate`.
    
    _Example_
    
    ```
    average_order_value
    ```
    
*   `label` (_string_) Localized label of the KPI.
    
    _Example_
    
    ```
    Average Order Value
    ```
    
*   `description` (_string_) A localized description that defines what the KPI represents.
    
    _Example_
    
    ```
    Average order value (AOV) refers to the average amount spent by customers per transaction.
    ```
    
*   `insights` (_array of InsightMetaDataRepresentation_)

### InsightRepresentation

*   `name` (_string_) API name of the insight.  
    Allowed values: `top_performing_products`, `bottom_performing_products`, `top_performing_categories`, `bottom_performing_categories`, `top_contributing_locations`, `bottom_contributing_locations`, `top_converting_products`, `bottom_converting_products`.
    
    _Example_
    
    ```
    bottom_performing_category
    ```
    
*   `insightSummary` (_string_) Localized, human-readable summary of the change in the insight value.
    
    _Example_
    
    ```
    Top-performing categories are iPod and MP3 Players and Women's Clothing, accounting for 10% of average order value (AOV).
    ```
    
*   `dashboardUrl` (_string_) Specifies the relative URL of the dashboard where the insight is visualized.
    
    _Example_
    
    ```
    /lightning/n/standard-CommerceStores?target=intelligence&channelId=0ZESG000000np9T4AQ
    ```
    
*   `values` (_array of InsightValueRepresentation_)

### InsightMetaDataRepresentation

*   `name` (_string_) API name of the insight.  
    Allowed values: `top_performing_products`, `bottom_performing_products`, `top_performing_categories`, `bottom_performing_categories`, `top_contributing_locations`, `bottom_contributing_locations`, `top_converting_products`, `bottom_converting_products`.
    
    _Example_
    
    ```
    bottom_performing_products
    ```
    
*   `label` (_string_) Localized label of the insight.
    
    _Example_
    
    ```
    Bottom Performing Products
    ```
    
*   `description` (_string_) A localized description that defines what the insight data represents.
    
    _Example_
    
    ```
    Bottom-performing products refer to those with the lowest contribution to sales.
    ```
    

### InsightValueRepresentation

*   `contextId` (_string_) Specifies the Salesforce ID of the record on which the insight is based. For example, for bottom\_performing\_category, contextId would be the product category ID.
    
    _Example_
    
    ```
    0ZGSG00000099tq4AA
    ```
    
*   `name` (_string_) Specifies the localized name of the record on which the insight is based. For example, for bottom\_performing\_category, name would be the localized category name.
    
    _Example_
    
    ```
    IPhone 15
    ```
    
*   `value` (_number (double)_) Specifies the value of the insight for the current timeframe based on the KPI. For example, if the KPI is gross\_sales and the insight is top\_performing\_product, the insight value would be the total gross sales of the top-performing product during the current timeframe.
    
    _Example_
    
    ```
    1100.9
    ```
    
*   `previousValue` (_number (double)_) Specifies the value of the insight for the previous timeframe based on the KPI. For example, if the KPI is gross\_sales and the insight is top\_performing\_product, the previous value of the insight would be the total gross sales of the top-performing product during the previous timeframe.
    
    _Example_
    
    ```
    1101.4
    ```

<!-- document id=9af82dbec91d2640dff1adbccec494684ae8cd74de87b998ec1796f5cc397264 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-buyer-messaging-consent-ref.md -->

Salesforce Commerce Buyer Messaging Consent API

# Salesforce Commerce Buyer Messaging Consent API

Capture consent from a buyer for a webstore. The buyer can share marketing related emails based on their preference. The buyer can also grant or update consent from various places like the store's home page, the checkout page, the registration page, and the my account page.

Commerce Consent API

**Version:** 66.0

## Servers

*   `https://api.salesforce.com/services/data/${version}`
    *   `version (default v66.0): v66.0, v65.0, v64.0`

## Operations

### GET getConsentSubscription

`GET /commerce/webstores/${webstoreId}/consents/subscriptions?experience=${experience}&userContext=${userContext}`

Operation ID: `getConsentSubscription`.

Retrieves communication subscriptions with consent values for a specific webstore. When userContext is true, consent values are retrieved for the contact's email address.

Retrieves communication subscriptions with consent values for a specific webstore. When userContext is true, consent values are retrieved for the contact's email address.

#### Parameters

*   `webstoreId` (path, string, required) Id of the webstore.  
    Example: `0ZExx000000004DGAQ`.
*   `experience` (query, string) UI experience used to capture the buyer's consent (EmailCaptureComponent or ProfileAndRegistration).  
    Example: `Checkout`.
*   `userContext` (query, boolean) Indicates if the contact point value should be obtained from the user context.  
    Example: `false`.

#### Responses

*   **200** Successfully captured consent for the webstore or contact point value.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "contactPointValue": "josh@gmail.com",
      "webStoreId": "0ZExx00000001k5GAA",
      "experience": "EmailCaptureComponent",
      "isSuccess": true,
      "error": {},
      "communicationSubscriptions": [
        {
          "name": "PromotionSubscription",
          "title": "Promotion subscription",
          "description": "Consent for receiving promotional emails.",
          "commSubscriptionId": "0XlSB000000Fc9p0AC",
          "commSubscriptionChannelTypeId": "0XlSB000000Fc9p0AC",
          "consentExperience": "Checkout",
          "consentType": "Email",
          "consentStatus": "opt-in"
        },
        {
          "name": "TravelRelatedContent",
          "title": "Travel subscription",
          "description": "Consent for receiving travel-related emails.",
          "commSubscriptionId": "0XlSB000000Fc9p0AC",
          "commSubscriptionChannelTypeId": "0XlSB000000Fc9p0AC",
          "consentExperience": "Marketing",
          "consentType": "Email",
          "consentStatus": "opt-in"
        }
      ]
    }
    ```
    
*   **400** Bad request with invalid webstoreId.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INVALID_INPUT",
        "errorMsg": "Invalid webstoreId."
      },
      "communicationSubscriptions": {}
    }
    ```
    
*   **404** Communication subscriptions not found for WebstoreId.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "NOT_FOUND",
        "errorMsg": "Communication Subscriptions not found."
      },
      "communicationSubscriptions": {}
    }
    ```
    
*   **500** Bad request.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INTERNAL_SERVER_ERROR",
        "errorMsg": "Couldn't process request."
      },
      "communicationSubscriptions": {}
    }
    ```
    

### POST updateConsent

`POST /commerce/webstores/${webstoreId}/consents/update`

Operation ID: `updateConsent`.

Updates the consent statuses in Data Cloud of a single contact point value (Email address) related to multiple communication subscription channel types.

Updates the consent statuses in Data Cloud of a single contact point value (Email address) related to multiple communication subscription channel types.

#### Parameters

*   `webstoreId` (path, string, required) Id of the webstore.  
    Example: `0ZExx000000004DGAQ`.

#### Request body (required)

Media type: `application/json`. Schema: `ConsentUpdateInputRepresentation`.

_Example: example-1_ Example of a successful consent value submission.

```
{
  "contactPointValue": "john.doe@example.com",
  "communicationSubscriptionConsentItemList": [
    {
      "commSubscriptionChannelTypeId": "0eBSB000000FRPh2AOYG",
      "consentValue": "opt-out"
    },
    {
      "commSubscriptionChannelTypeId": "0eBSB000000FRPh2GF",
      "consentValue": "opt-in"
    }
  ]
}
```

#### Responses

*   **200** Successfully recorded consent value for contact point value (Email address).
    
    Media type: `application/json`. Schema: `ConsentUpdateResponseRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": true,
      "error": {}
    }
    ```
    
*   **400** Invalid consent experience request.
    
    Media type: `application/json`. Schema: `ConsentUpdateResponseRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INVALID_INPUT",
        "errorMsg": "Invalid consent experience."
      }
    }
    ```
    
*   **404** Failed to find webstore for webstoreId.
    
    Media type: `application/json`. Schema: `ConsentUpdateResponseRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "NOT_FOUND",
        "errorMsg": "Couldn't find webstore."
      }
    }
    ```
    
*   **500** Failed to process request.
    
    Media type: `application/json`. Schema: `ConsentUpdateResponseRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INTERNAL_SERVER_ERROR",
        "errorMsg": "Couldn't process request."
      }
    }
    ```
    

### POST createCommunicationSubscription

`POST /commerce/webstores/${webstoreId}/consents/subscriptions`

Operation ID: `createCommunicationSubscription`.

Create Commerce communication subscription at store level on admin setup UI.

Create Commerce communication subscription at store level on admin setup UI.

#### Parameters

*   `webstoreId` (path, string, required) Id of the webstore.  
    Example: `0ZExx000000004DGAQ`.

#### Request body (required)

Media type: `application/json`. Schema: `ConsentSubscriptionInputRepresentation`.

_Example: example-1_ Example creating communication subscription for webstore with different channel and experience.

```
{
  "name": "PromotionalSubscription",
  "title": "Promotional Email Subscription",
  "description": "User consent for receiving promotional emails.",
  "channels": [
    {
      "consentType": "Email",
      "commSubscriptionChannelTypeId": null
    },
    {
      "consentType": "Sms",
      "commSubscriptionChannelTypeId": null
    }
  ],
  "experiences": [
    "EmailCaptureComponent"
  ]
}
```

#### Responses

*   **201** Successfully created communication subscriptions for webstore.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example_
    
    ```
    {
      "commSubscriptionId": "0eBSB000000FRPh2AO",
      "Success": {
        "value": {
          "isSuccess": true,
          "error": {}
        }
      }
    }
    ```
    
*   **400** Bad request with invalid webstoreId.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INVALID_INPUT",
        "errorMsg": "Invalid request."
      }
    }
    ```
    
*   **404** Couldn't find webstoreId.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "NOT_FOUND",
        "errorMsg": "Couldn't find webstoreId."
      }
    }
    ```
    
*   **500** Couldn't process request.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INTERNAL_SERVER_ERROR",
        "errorMsg": "Couldn't process request."
      }
    }
    ```
    

### PUT updateCommunicationSubscription

`PUT /commerce/webstores/${webstoreId}/consents/subscriptions/${csId}`

Operation ID: `updateCommunicationSubscription`.

Update or delete Commerce communication subscription for a webstore.

Update Commerce communication subscription for a webstore.

#### Parameters

*   `webstoreId` (path, string, required) Id of the webstore.  
    Example: `0ZExx000000004DGAQ`.
*   `communicationSubscriptionId` (path, string, required) Id of communication subscription.  
    Example: `0eBSB000000FRPh2AO`.

#### Request body (required)

Media type: `application/json`. Schema: `ConsentSubscriptionInputRepresentation`.

_Example: example-1_ Example updating communication subscription for webstore with different channel and experience.

```
{
  "name": "PromotionalSubscription",
  "title": "Promotional Email Subscription",
  "description": "Buyer consent for receiving promotional emails.",
  "channels": [
    {
      "consentType": "Email",
      "commSubscriptionChannelTypeId": "0LOxx000000004DGYG"
    }
  ],
  "experiences": [
    "EmailCaptureComponent"
  ]
}
```

#### Responses

*   **200** Successfully updated communication subscriptions for webstore.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": true,
      "error": {}
    }
    ```
    
*   **400** Bad request with invalid webstoreId.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INVALID_INPUT",
        "errorMsg": "Invalid request."
      }
    }
    ```
    
*   **404** Couldn't find webstore for webstoreId.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "NOT_FOUND",
        "errorMsg": "Couldn't find webstore."
      }
    }
    ```
    
*   **500** Couldn't process request.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResultRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "isSuccess": false,
      "error": {
        "errorCode": "INTERNAL_SERVER_ERROR",
        "errorMsg": "Couldn't process request."
      }
    }
    ```
    

### DELETE deleteCommunicationSubscription

`DELETE /commerce/webstores/${webstoreId}/consents/subscriptions/${csId}`

Operation ID: `deleteCommunicationSubscription`.

Update or delete Commerce communication subscription for a webstore.

Delete a Commerce communication subscription for a webstore.

#### Parameters

*   `webstoreId` (path, string, required) Id of the webstore.  
    Example: `0ZExx000000004DGAQ`.
*   `communicationSubscriptionId` (path, string, required) Id of communication subscription.  
    Example: `0eBSB000000FRPh2AO`.

#### Responses

*   **200** Successfully deleted communication subscription.

## Schemas

### ConsentSubscriptionRepresentation

*   `isSuccess` (_boolean_) Indicates whether the operation was successful.
*   `contactPointValue` (_string_) The email address of the buyer, if retrieved in user context.
*   `webStoreId` (_string_) The unique identifier of the webstore.
*   `experience` (_string_) The user experience context in which the consent was captured. Possible values: 'EmailCaptureComponent', 'ProfileAndRegistration', 'Checkout', 'Marketing'.
*   `error` (_object_) Details of any error that occurred during the operation.
*   `communicationSubscriptions` (_array of object_) A list of communication subscription items and their consent statuses.
    *   `name` (_string_) The internal name of the communication subscription.
    *   `title` (_string_) The display title of the subscription.
    *   `description` (_string_) A description of the subscription.
    *   `commSubscriptionId` (_string_) The unique identifier of the communication subscription.
    *   `commSubscriptionChannelTypeId` (_string_) The unique identifier of the communication subscription channel type.
    *   `consentExperience` (_string_) The user experience context in which consent was captured. Possible values: 'EmailCaptureComponent', 'ProfileAndRegistration', 'Checkout', 'Marketing'.
    *   `consentType` (_string_) The communication channel for the subscription. Possible values: 'Email', 'Sms'.
    *   `consentStatus` (_string_) The buyer's consent status. Possible values: 'opt-in', 'opt-out'.

### ConsentUpdateInputRepresentation

*   `contactPointValue` (_string_) Email address of buyer.
*   `communicationSubscriptionConsentItemList` (_array of object_) List of consent values for a communication subscription.
    *   `commSubscriptionChannelTypeId` (_string_) Id of the communication subscription channel type.
    *   `consentValue` (_string_) Buyer's consent value (opt-in or opt-out).

### ConsentUpdateResponseRepresentation

Output representation of consent update.

*   `isSuccess` (_boolean_) Indicates if the update was succeeded.
*   `error` (_array of object_) Subscription consent information.
    *   `errorCode` (_string_) Message describing the error code.
    *   `errorMessage` (_string_) Message stating the reason for error, if any.

### ConsentSubscriptionInputRepresentation

*   `name` (_string_) Name of the subscription or consent item.
*   `title` (_string_) Title of the consent item.
*   `description` (_string_) Description of what the consent item is for.
*   `channels` (_array of object_) List of channels with commSubscriptionChannelTypeId.
    *   `consentType` (_string_) Channel value.
    *   `commSubscriptionChannelTypeId` (_string_) Corresponding commSubscriptionChannelTypeId.
*   `experiences` (_array of object_) List of experiences with commSubscriptionChannelTypeId.
    *   `experience` (_string_) Experience value.

### ConsentSubscriptionResultRepresentation

Output representation of communication subscription upsert.

*   `isSuccess` (_boolean_) Indicates if the operation was successful.
*   `commSubscriptionId` (_string_) Id of communication subscription.
*   `error` (_array of object_) Subscription consent information.
    *   `errorCode` (_string_) Message describing the error code.
    *   `errorMessage` (_string_) Message stating the reason for error, if any.

<!-- document id=3056f1fdc8f0d5893bdf6399233780116d11d089a9d7e0c1a6a2d8996160b682 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-cart-apis.md -->

# Salesforce Commerce Cart API

Salesforce Cart Connect APIs provide developers with a powerful set of APIs to build and customize cart management solutions within the B2B Commerce platform. These APIs enable developers to effortlessly perform various tasks, including creating, updating, and managing carts. Key functionalities encompass adding or removing items, adjusting quantities, transferring items to wishlists, applying promotions, using coupons, and splitting a cart into multiple delivery groups.

The visibility settings for cart messages enable real-time updates and notifications, ensuring customers stay informed about changes to their carts, such as item availability, price adjustments, or promotional offers.

Moreover, developers can create multiple active carts for the same buyer and choose which cart to serve as the primary one. Additionally, the capability to add up to 100 items in a batch to a cart enhances operational efficiency and scalability.

To enhance the shopping experience further, developers can easily manage coupons associated with a cart, applying or removing them as needed. Similarly, they can gain insights into promotions and apply them at either the cart or individual item level.

To streamline order management and enhance customer satisfaction, developers can organize cart items into delivery groups, simplifying the process of shipping items to multiple addresses. Lastly, a cart can be preserved so that when a guest user logs in as an authenticated customer they retain their guest cart items.

## Use Case

Let's consider a basic scenario for building the cart management flow using Cart APIs. This example covers just a few Cart APIs and doesn't include the entire Cart APIs functionality.

![Diagram of the cart management API workflow for B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/cart_apis_workflow.png '{"class": "image-lg", "title": "Cart Management Workflow"}')

In a typical shopping journey, users add products from the Product Listing Page (PLP) or Product Details Page (PDP) to their cart using a POST call on the [Cart Item API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm). Then, they view their cart by clicking the cart icon. If no cart exists for the user, the system creates one using a POST call on the [Create Cart API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts.htm). Next, it retrieves the selected products using a GET call on the [Cart Item API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm).

On the cart page, users can adjust quantities, remove items, or move them to wishlists, which trigger PATCH or DELETE calls on the [Cart Item API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_item.htm), or a POST call on the [Wishlist API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_add_to_wishlist.htm). Promotions can be viewed using GET calls on the [Cart Promotions API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_promotions.htm) and [Cart Items Promotions API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items_promotions.htm). Valid coupons can be applied with a POST call on the [Cart Coupon API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons.htm). Subsequently, make a POST call on the [Cart, Arrange Items API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_arrange_items.htm) to arrange cart items into delivery groups to split your shipment order. Splitting refers to dividing an order into multiple shipments, and it is often implemented due to products being housed in different locations or specific delivery preferences. After finalizing the cart, users can proceed to checkout.

## Resources

Here’s a list of Commerce Cart resources:

| Resource                                                                                                                                                                                                                            | Supported HTTP Methods | Description                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [`/commerce/webstores/{webstoreId}/​carts`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartCollection)                                                                    | POST                   | Create a cart.                                                                                                   |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartSummary)                                                        | GET                    | Get a cart.                                                                                                      |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteCartSummary)                                                     | DELETE                 | Delete a cart.                                                                                                   |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=putCartSummary)                                                        | PUT                    | Create an active cart, if one doesn’t exist.                                                                     |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/actions/add-cart-to-wishlist`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartToWishlist)                       | POST                   | Copy the products from a cart to a wishlist.                                                                     |
| [`/commerce/webstores/webstoreId/carts​/cartStateorId/actions/clone`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartClone)                                               | POST                   | Clones an existing cart to create a secondary, read-only cart to support Pay Now functionality.                  |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/actions/make-primary`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartMakePrimary)                              | POST                   | Make a secondary cart a primary cart.                                                                            |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/actions/preserve`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postPreserveCart)                                     | POST                   | Preserve cart contents when a guest logs in as an authenticated customer.                                        |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-coupons`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartCouponCollection)                                  | GET                    | Get coupons associated with a cart.                                                                              |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-coupons`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartCouponCollection)                                 | POST                   | Apply a coupon code to a cart.                                                                                   |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-coupons/{cartCouponId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteCartCoupon)                          | DELETE                 | Delete a coupon from a cart.                                                                                     |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/messages/actions/set-visibility`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartMessagesVisibility)            | POST                   | Set the visibility for cart messages.                                                                            |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/products`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getProductCartItemCollection)                                 | GET                    | Get the items in a cart, sorted by product ID.                                                                   |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/products/{productId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getProductCartItem)                               | GET                    | Get cart items of a specific product.                                                                            |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/inventory-reservations`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteCartInventoryReservation)                 | DELETE                 | Delete an inventory reservation from the cart.                                                                   |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/inventory-reservations`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=putCartInventoryReservation)                    | PUT                    | Create and update an inventory reservation from the cart.                                                        |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups/actions/itemDistributions`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemMove)            | POST                   | Distribute cart items into delivery groups.                                                                      |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/promotions`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartPromotionCollection)                                 | GET                    | Get promotions associated with a cart.                                                                           |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartItemCollection)                                      | GET                    | Get the items in a cart.                                                                                         |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemCollection)                                     | POST                   | Add an item to a cart.                                                                                           |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/{cartItemId}/children`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getChildCartItemCollection)           | GET                    | Retrieves all child items associated with a specified cart item. This API is supported only for product bundles. |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-items/batch`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemBatchCollection)                          | POST                   | Add a batch of up to 100 items to a cart.                                                                        |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-items/{cartItemId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteCartItem)                                | DELETE                 | Update or delete an item in a cart.                                                                              |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-items/{cartItemId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=patchCartItem)                                 | PATCH                  | Update or delete an item in a cart.                                                                              |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/cart-items/promotions`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemPromotionCollection)                 | POST                   | Get promotions associated with items in a cart.                                                                  |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/delivery-groups/actions/arrange-items`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemArrange)             | POST                   | Arrange cart items into delivery groups.                                                                         |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/delivery-groups`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getDeliveryGroupCollection)                            | GET                    | Get or create a collection of delivery groups in a cart.                                                         |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/delivery-groups`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postDeliveryGroupCollection)                           | POST                   | Get or create a collection of delivery groups in a cart.                                                         |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/delivery-groups/{deliveryGroupId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getDeliveryGroup)                    | GET                    | Get a delivery group in the cart.                                                                                |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/delivery-groups/{deliveryGroupId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=deleteDeliveryGroup)                 | DELETE                 | Delete a delivery group in the cart.                                                                             |
| [`/commerce/webstores/{webstoreId}/carts​/{cartStateOrId}/delivery-groups/{deliveryGroupId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=patchDeliveryGroup)                  | PATCH                  | Update a delivery group in the cart.                                                                             |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/calculate`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartCalculate)                                   | POST                   | Perform a complete cart calculation based on the cart status.                                                    |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/evaluate-shipping`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartEvaluateShipping)                    | POST                   | Evaluate the shipping costs for a cart.                                                                          |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/evaluate-taxes`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartEvaluateTax)                            | POST                   | Evaluate taxes for a cart.                                                                                       |
| [`/commerce/webstores/{webstoreId}/carts/compact-summary`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=getCartBadge)                                                           | GET                    | Retrieve compact cart summary for an existing cart.                                                              |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/actions/apply-configuration`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemsFromConfiguration) | POST                   | Apply a saved configuration context to a cart item.                                                              |
| [`/commerce/webstores/{webstoreId}/carts/{activeCartOrId}/quotes`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=createQuoteFromCart)                                            | POST                   | Create a new quote from an active cart by converting cart items into quote line items.                           |
| [`/commerce/webstores/{webstoreId}/quotes`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-quotes-ref?meta=getQuotes)                                                                           | GET                    | Retrieve all quotes associated with a given account.                                                             |
| [`/commerce/webstores/{webstoreId}/quotes/{quoteId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-quotes-ref?meta=getQuoteDetails)                                                           | GET                    | Retrieve the details of a specific quote using the quote ID provided in the path parameter.                      |

**See Also**

- [_B2B Commerce Developer Guide_: Cart Data Model](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-cart.html)
- [_B2B Commerce Developer Guide_: Cart Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-cart-limits.html)

<!-- document id=9aa46e0480dcba7d31090e2d4e104607060e3492657cca8c8ef81b28aeaf4c0e url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-cart-ref.md -->

Salesforce Commerce Cart API

# Salesforce Commerce Cart API

Salesforce Commerce Cart Connect APIs enable developers to effortlessly perform various tasks, including creating, updating, and managing carts. Key functionalities encompass adding or removing items, adjusting quantities, transferring items to wishlists, applying promotions, using coupons, and splitting a cart into multiple delivery groups.

**Note:** The Salesforce Commerce Cart APIs aren’t supported in preview mode.

**Version:** 67.0

## Servers

*   `https://{yourinstance}.salesforce.com/services/data/{version}`
    *   `version (default v67.0)`

## Operations

### POST Set the visibility for cart messages.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/messages/actions/set-visibility`

Operation ID: `postCartMessagesVisibility`.

Updates the visibility for cart level messages associated a single WebCart.

The visibility settings for cart messages enable real-time updates and notifications, ensuring customers stay informed about changes to their carts, such as item availability, price adjustments, or promotional offers.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartMessagesVisibilityInputRepresentation`.

_Example: Example_ Set the visibility for cart messages.

```
{
  "visibility": true
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartMessagesVisibilityResultRepresentation`.
    

### POST Add a batch of up to 100 items to a cart.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/batch`

Operation ID: `postCartItemBatchCollection`.

Allows batch adding of cart items.

Buyers with read access to carts can add items to carts. Adding items to a cart respects the buyer's view product entitlements, and only users entitled to view product data can access it.

**Note:** The `postCartItemBatchCollection` resource doesn't support dynamic bundles or dynamic attributes for configurable products. To apply or update configurations for these bundles, use the [`postCartItemsFromConfiguration`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-cart-ref?meta=postCartItemsFromConfiguration) resource instead.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `object`.

*   `inputs` (_array of object_)
    *   `richInput` (_sfdc.commerce.cart.connect.api.input.CartItemInputRepresentation_)

_Example: RichInput_ Rich input example

```
{
  "inputs": [
    {
      "richInput": {
        "quantity": 2,
        "productId": "01txx0000006i2SAAQ",
        "type": "Product"
      }
    },
    {
      "richInput": {
        "quantity": 15,
        "productId": "01txx0000006i3AAAQ",
        "type": "Product"
      }
    }
  ]
}
```

_Example: BinaryPartInput_ Binary part input example

```
{
  "inputs": [
    {
      "binaryPartNames": "bin1",
      "richInput": {
        "subjectId": "me",
        "body": {
          "messageSegments": [
            {
              "type": "Text",
              "text": "Please accept this receipt"
            }
          ]
        },
        "capabilities": {
          "content": {
            "description": "Receipt for expenses",
            "title": "receipt.pdf"
          }
        },
        "feedElementType": "FeedItem"
      }
    }
  ]
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `core.connect.api.output.common.BatchRepresentation`.
    
    _Example: Example_ Example of the successful cart items creation response.
    
    ```
    {
      "hasErrors": false,
      "results": [
        {
          "statusCode": 201,
          "result": {
            "billingFrequency": null,
            "cartData": null,
            "cartDeliveryGroupId": "0a7xx000000023RAAQ",
            "cartId": "0a6xx000000023RAAQ",
            "cartItemId": "0a9xx00000003ifAAA",
            "childProductCount": 0,
            "currencyIsoCode": "USD",
            "customFields": [],
            "firstPymtTotalAmount": null,
            "firstPymtTotalListPrice": "49.98",
            "firstPymtTotalPrice": "41.00",
            "firstPymtTotalTax": null,
            "isConfigurationAllowed": false,
            "isShippingChargeNotApplicable": false,
            "itemizedAdjustmentAmount": "0.00",
            "listPrice": "24.99",
            "messagesSummary": {
              "errorCount": null,
              "hasErrors": null,
              "limitedMessages": [],
              "relatedEntityId": null,
              "totalLineItemsWithErrors": null
            },
            "name": "Alpine Energy Drink Chai Post 0.5L PET - 6 pack",
            "parentCartItemId": null,
            "productClass": "Simple",
            "productDetails": {
              "dynamicAttributes": {},
              "fields": {},
              "isConfigurationAllowed": null,
              "name": "Alpine Energy Drink Chai Post 0.5L PET - 6 pack",
              "productClass": null,
              "productId": "01txx0000006i2SAAQ",
              "productSubscriptionInformation": null,
              "productUrlName": null,
              "purchaseQuantityRule": null,
              "sku": "6010009",
              "thumbnailImage": null,
              "variationAttributes": {}
            },
            "productId": "01txx0000006i2SAAQ",
            "productSellingModelId": null,
            "promotionDisplayName": null,
            "quantity": "2",
            "quoteLineItemId": null,
            "salesPrice": "20.50",
            "sellingModelType": null,
            "subType": null,
            "subscriptionTerm": null,
            "totalAdjustmentAmount": "0.00",
            "totalAmount": null,
            "totalListPrice": "49.98",
            "totalPrice": "41.00",
            "totalTax": null,
            "type": "Product",
            "unitAdjustedPrice": "20.50",
            "unitAdjustedPriceWithItemAdj": "20.50",
            "unitAdjustmentAmount": "0",
            "unitItemAdjustmentAmount": "0.00"
          }
        }
      ]
    }
    ```
    

### POST Evaluate the shipping costs for a cart.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/evaluate-shipping`

Operation ID: `postCartEvaluateShipping`.

Evaluates the shipping costs for an existing cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) Optional. The ID of the account for which the request is made. If unspecified, defaults to the account ID for the context user.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartEvaluateShippingInputRepresentation`.

_Example: CartEvaluateShippingInput_ Example of the cart evaluate shipping input.

```
{
  "customFields": [
    {
      "attributes": {
        "type": "WebCart"
      },
      "WebCartCustomField1__c": "Foo"
    },
    {
      "attributes": {
        "type": "CartItem"
      },
      "id": "0a9xx0000000002CI1",
      "CartItemCustomField1__c": "CI1_Field1Value",
      "CartItemCustomField2__c": "CI1_Field2Value"
    },
    {
      "attributes": {
        "type": "CartItem"
      },
      "id": "0a9xx0000000002CI2",
      "CartItemCustomField1__c": "CI2_Field1Value",
      "CartItemCustomField2__c": "CI2_Field2Value"
    },
    {
      "attributes": {
        "type": "CartDeliveryGroup"
      },
      "id": "0a7xx000000000CDG1",
      "CartDeliveryGroupCustomField1__c": "CDG1_Field1Value",
      "CartDeliveryGroupCustomField2__c": "CDG1_Field2Value"
    }
  ],
  "shippingAddress": {
    "name": "Alan Johnson",
    "firstName": "Alan",
    "id": "0a6xx0000000000",
    "lastName": "Johnson",
    "region": "CA",
    "country": "US",
    "city": "San Francisco",
    "street": "415 Mission St",
    "postalCode": 94105
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryResultRepresentation`.
    

### GET Retrieve cart items of a specific product.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/products/{productId}`

Operation ID: `getProductCartItem`.

A collection of cartitems for a given product in the cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `productId` (path, string (Id), required) The ID of the product.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.
*   `productFields` (query, string) The comma-separated list of up to 15 product fields. Results include fields that you have access to. Some product fields (such as productName and sku) are returned even when not included in the productFields parameter.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.ProductCartItemRepresentation`.
    

### PUT Create and update an inventory reservation from the cart.

`PUT /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/inventory-reservations`

Operation ID: `putCartInventoryReservation`.

Handle Inventory Reservations.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartInventoryReservationInputRepresentation`.

_Example: Example_ Example of the cart inventory reservation input.

```
{
  "durationInSeconds": 100
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartInventoryReservationOutputRepresentation`.
    
    _Example: Example_ Example of the cart inventory reservation response.
    
    ```
    {
      "errorCode": null,
      "errorMessage": "Success",
      "inventoryItemReservations": [
        {
          "errorCode": null,
          "errorMessage": "Success",
          "id": "2pmSG000005k7q3YAA",
          "itemReservationSourceId": null,
          "productId": "01tSG000003uisiYAA",
          "quantity": 3,
          "reservedAtLocationId": null
        }
      ],
      "reservationIdentifier": null,
      "success": true
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartInventoryReservationOutputRepresentation`.
    
    _Example: Example_ Client error.
    
    ```
    [
      {
        "errorCode": "JSON_PARSER_ERROR",
        "message": "Unexpected character. Expected a valid value."
      }
    ]
    ```
    

### DELETE Delete an inventory reservation from the cart.

`DELETE /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/inventory-reservations`

Operation ID: `deleteCartInventoryReservation`.

Handle Inventory Reservations.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success

### GET Retrieve the items in a cart, sorted by product ID.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/products`

Operation ID: `getProductCartItemCollection`.

A collection of items grouped by product in the cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.
*   `pageNumber` (query, integer) Specifies the requested page number.
*   `pageSize` (query, integer) Specifies the number of items per page. Valid values are from 1 through 100. If you don’t specify a value, the default size is 25.
*   `productFields` (query, string) The comma-separated list of up to 15 product fields. Results include fields that you have access to. Some product fields (such as productName and sku) are returned even when not included in the productFields parameter.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.ProductCartItemCollectionRepresentation`.
    
*   **400** Bad Request
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.ProductCartItemCollectionRepresentation`.
    
    _Example: Example_ Example of 400 Bad Requests
    
    ```
    [
      {
        "errorCode": "ILLEGAL_QUERY_PARAMETER_VALUE",
        "message": "You must log in to browse our store."
      }
    ]
    ```
    

### POST Copy the products from a cart to a wishlist.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/add-cart-to-wishlist`

Operation ID: `postCartToWishlist`.

Used to copy products from Cart to Wishlist.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartToWishlistInputRepresentation`.

_Example: Example_ Successfully added cart items to wishlist.

```
{
  "wishlistId": "3orxx00000000A1"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartToWishlistResultRepresentation`.
    
    _Example: Example_ Successfully moved cart items to a wishlist.
    
    ```
    {
      "productsAddedCount": 10,
      "wishlistId": "3orxx00000000A1"
    }
    ```
    

### POST Clone an existing cart to create a secondary.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/clone`

Operation ID: `postCartClone`.

Clones an existing cart to create a secondary, read-only cart to support Pay Now functionality. Sets the guest cart status to PendingDelete in a B2B store or Closed in a D2C store.

This creates a secondary, read-only cart to support Pay Now functionality. Sets the guest cart status to PendingDelete in a B2B store or Closed in a D2C store.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `targetEffectiveAccountId` (query, string (Id)) The effective account ID associated with the cloned cart.
*   `targetType` (query, string) The type of the cloned cart. Value is PayNowReadOnly.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation`.
    

### POST Make a secondary cart a primary cart.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/make-primary`

Operation ID: `postCartMakePrimary`.

Makes a secondary cart a primary cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required)
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CommerceActionResultRepresentation`.
    

### DELETE Delete a coupon from a cart.

`DELETE /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-coupons/{cartCouponId}`

Operation ID: `deleteCartCoupon`.

Used to delete single cart coupon.

If your store has simplified cart cleanup enabled, a DELETE request can remove a coupon from a cart without canceling checkout.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `cartCouponId` (path, string (Id), required) The ID of the cart coupon code.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success

### POST Evaluate taxes for a cart.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/evaluate-taxes`

Operation ID: `postCartEvaluateTax`.

Evaluates taxes for an existing cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the account for which the request is made. If unspecified, defaults to the account ID for the context user.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartEvaluateTaxInputRepresentation`.

_Example CartEvaluateTaxInput: same as POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/evaluate-shipping request._ Example of the cart evaluate tax input.

_Example: CartEvaluateTaxInput_ Example of the cart evaluate tax input.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryResultRepresentation`.
    

### GET Retrieve the items in a cart.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items`

Operation ID: `getCartItemCollection`.

A collection of items in the cart.

If there isn’t a current cart, it returns an empty cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.
*   `includeCoupons` (query, boolean) Indicates whether to include coupons (True) or not (False).
*   `includePromotions` (query, boolean) Indicates whether to include promotions (True) or not (False).
*   `page` (query, string) Specifies the page token to use to view a page of information. Page tokens are returned as part of the response, such as currentPageToken or nextPageToken. If you don’t specify a value, the first page is returned.
*   `pageNumber` (query, integer) Specifies the requested page number.
*   `pageSize` (query, integer) Specifies the number of items per page. Valid values are from 1 through 100. If you don’t specify a value, the default size is 25.
*   `productFields` (query, string) The comma-separated list of up to 15 product fields. Results include fields that you have access to. Some product fields (such as productName and sku) are returned even when not included in the productFields parameter.
*   `sort` (query, sfdc.commerce.cart.connect.api.enums.ConnectCartItemSortOrderEnum)

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartItemCollectionRepresentation`.
    
    _Example: Example_ Example of the fetch cart items response.
    

### POST Add an item to a cart.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items`

Operation ID: `postCartItemCollection`.

A collection of items in the cart.

Buyers with read access to carts can add items in carts. Adding items to a cart respects buyer View Product entitlements and only users entitled to view product data can access it.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.
*   `productFields` (query, string) The comma-separated list of up to 15 product fields. Results include fields that you have access to.
*   `includeCartData` (query, boolean) Specify to include complete cart data in the response. This is available ONLY when in sync mode.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartItemInputRepresentation`.

_Example: Example_ Example of the cart item input.

```
{
  "customFields": [
    {
      "attributes": {
        "type": "CartItem"
      },
      "connectCustomLocation__c": {
        "latitude": 3.456,
        "longitude": 7.89
      },
      "connectCustomCurrency__c": 23.4,
      "connectCustomCheckbox__c": true,
      "connectCustomDate__c": "2025-02-17",
      "connectCustomText__c": "sample",
      "connectCustomAddress__c": {
        "city": "city",
        "country": null,
        "geocodeAccuracy": null,
        "latitude": -10,
        "longitude": 1.5,
        "postalCode": "postalCode",
        "state": null,
        "street": "street"
      }
    }
  ],
  "productId": "01t000000000000000",
  "quantity": 5,
  "type": "Product"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartItemRepresentation`.
    
    _Example: Example_ Example of the add an item to a cart response.
    
    ```
    {
      "billingFrequency": null,
      "cartData": null,
      "cartDeliveryGroupId": "0a7VW0000001WkDYAU",
      "cartId": "0a6VW0000001WgzYAE",
      "cartItemId": "0a9VW0000002lZ7YAI",
      "childProductCount": 0,
      "currencyIsoCode": "USD",
      "customFields": [
        {
          "attributes": {
            "type": "CartItem"
          },
          "connectCustomLocation__c": {
            "latitude": 3.456
          },
          "longitude": 7.89,
          "connectCustomDate__c": "2025-02-17",
          "connectCustomAddress__c": {
            "city": "city",
            "country": null,
            "geocodeAccuracy": null,
            "latitude": -10,
            "longitude": 1.5,
            "postalCode": "postalCode",
            "state": null,
            "street": "street"
          },
          "connectCustomCurrency__c": 23.4,
          "connectCustomCheckbox__c": true,
          "connectCustomText__c": "sample"
        }
      ],
      "firstPymtTotalAmount": null,
      "firstPymtTotalListPrice": 45,
      "firstPymtTotalPrice": 45,
      "firstPymtTotalTax": null,
      "itemizedAdjustmentAmount": 0,
      "listPrice": 22.5,
      "messagesSummary": {
        "errorCount": null,
        "hasErrors": null,
        "limitedMessages": [],
        "relatedEntityId": null,
        "totalLineItemsWithErrors": null
      },
      "name": "YetiBar Tart Cherry/Bison Paleo 2oz bar",
      "parentCartItemId": null,
      "productClass": "Simple",
      "productDetails": {
        "fields": null,
        "name": "YetiBar Tart Cherry/Bison Paleo 2oz bar",
        "productId": "01tVW000001TP1WYAW",
        "productSubscriptionInformation": null,
        "purchaseQuantityRule": null,
        "sku": 6010056,
        "thumbnailImage": null,
        "variationAttributes": null
      },
      "productId": "01tVW000001TP1WYAW",
      "productSellingModelId": null,
      "quantity": 2,
      "salesPrice": 22.5,
      "sellingModelType": null,
      "subscriptionTerm": null,
      "totalAdjustmentAmount": 0,
      "totalAmount": null,
      "totalListPrice": 45,
      "totalPrice": 45,
      "totalTax": null,
      "type": "Product",
      "unitAdjustedPrice": 22.5,
      "unitAdjustedPriceWithItemAdj": 22.5,
      "unitAdjustmentAmount": 0,
      "unitItemAdjustmentAmount": 0
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartItemRepresentation`.
    
    _Example: Example_ Client error.
    
    ```
    [
      {
        "errorCode": "JSON_PARSER_ERROR",
        "message": "Value doesn't match expected type."
      }
    ]
    ```
    

### GET Retrieves all child items associated with a specified cart item. This API is supported only for product bundles.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/{cartItemId}/children`

Operation ID: `getChildCartItemCollection`.

Retrieves all child items associated with a specified cart item in the cart. A maximum of 200 child items is allowed per parent cart item.

#### Parameters

*   `cartItemId` (path, string (Id), required) The ID of the parent cart item whose child items you want to retrieve.
*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the account for which this request is made. Specify this account ID when the purchase is intended for an account other than the one associated with the current user context. If unspecified, the default value is determined from context.
*   `page` (query, string) Specifies the page token to use to view a page of information. Page tokens are returned as part of the response, such as currentPageToken or nextPageToken. If you don’t specify a value, the first page is returned.
*   `pageSize` (query, integer) Specifies the number of items per page. Valid values are from 1 through 200. The default value is 200.
*   `productFields` (query, string) The comma-separated list of product field names to include in the response. If this list is empty or not specified, a basic set of fields is returned. To include all fields, use '\*'. There is no limit to the number of fields you can specify; however, the total number of fields and the length of field names may impact the URL size limit.
*   `sort` (query, sfdc.commerce.cart.connect.api.enums.ConnectCartItemSortOrderEnum)

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.ChildCartItemCollectionRepresentation`.
    
    _Example: Example_ Example of the child items associated with a specified cart item.
    
    ```
    {
      "childCartItems": [
        {
          "cartItem": {
            "billingFrequency": null,
            "cartData": null,
            "cartDeliveryGroupId": "0a7xx00000000pdAAA",
            "cartId": "0a6xx00000000pdAAA",
            "cartItemId": "0a9xx00000000zPAAQ",
            "childProductCount": 0,
            "currencyIsoCode": "USD",
            "customFields": [],
            "firstPymtTotalAmount": "20.00",
            "firstPymtTotalListPrice": "30.00",
            "firstPymtTotalPrice": "20.00",
            "firstPymtTotalTax": "0.00",
            "isConfigurationAllowed": false,
            "isShippingChargeNotApplicable": false,
            "itemizedAdjustmentAmount": "0.00",
            "listPrice": "30.0",
            "messagesSummary": {
              "errorCount": null,
              "hasErrors": null,
              "limitedMessages": [],
              "relatedEntityId": null,
              "totalLineItemsWithErrors": null
            },
            "name": "Bag",
            "parentCartItemId": null,
            "productClass": "Simple",
            "productDetails": {
              "fields": {
                "LastModifiedDate": "2025-10-23T11:33:37Z",
                "FulfillmentQtyCalcMethod": null,
                "Description": null,
                "SpecificationType": "Commercial",
                "IsActive": "true",
                "LastReferencedDate": null,
                "StockKeepingUnit": "NHKB",
                "Name": "Bag",
                "ShippingWeightUnitOfMeasure": null,
                "CreatedById": "005xx000001XBov",
                "CloneSourceId": null,
                "RecordTypeId": "012xx0000005qmC",
                "DiscontinuedDate": null,
                "ProductClass": "Simple",
                "CanRamp": "false",
                "DisplayUrl": null,
                "IsDeleted": "false",
                "IsAssetizable": "true",
                "ProductCode": null,
                "UsageModelType": null,
                "ExternalId": null,
                "ProductPurpose": "Sell",
                "LastViewedDate": null,
                "UserRecordAccessId": null,
                "HelpText": null,
                "CurrencyIsoCode": "USD",
                "AvailabilityDate": null,
                "SystemModstamp": "2025-10-23T11:33:37Z",
                "IsArchived": "false",
                "DecompositionScope": null,
                "Type": null,
                "EndOfLifeDate": null,
                "IsShippingChargeNotApplicable": "false",
                "QuantityUnitOfMeasure": null,
                "CreatedDate": "2025-10-23T11:33:37Z",
                "Family": null,
                "UnitOfMeasureId": null,
                "ShippingWeight": null,
                "LastModifiedById": "005xx000001XBov",
                "IsSoldOnlyWithOtherProds": "false"
              },
              "isConfigurationAllowed": null,
              "name": "Bag",
              "productClass": null,
              "productId": "01txx0000006kf1AAA",
              "productSubscriptionInformation": null,
              "productUrlName": null,
              "purchaseQuantityRule": null,
              "sku": "NHKB",
              "thumbnailImage": {
                "alternateText": "bag.jpeg",
                "contentVersionId": null,
                "id": "2pmxx000000000RAAQ",
                "mediaType": "Image",
                "sortOrder": 0,
                "thumbnailUrl": null,
                "title": "bag.jpeg",
                "url": "/cms/delivery/media/MCQMDS7T446NC7XKVP6JOJK2HMSA?version=1.1&channelId=0apxx0000000003&oid=00Dxx00ThLVJ544"
              },
              "variationAttributes": {}
            },
            "productId": "01txx0000006kf1AAA",
            "productSellingModelId": null,
            "promotionDisplayName": null,
            "quantity": "1.0",
            "salesPrice": "20.0",
            "sellingModelType": null,
            "subType": null,
            "subscriptionTerm": null,
            "totalAdjustmentAmount": "0.00",
            "totalAmount": "20.00",
            "totalListPrice": "30.00",
            "totalPrice": "20.00",
            "totalTax": "0.00",
            "type": "Product",
            "unitAdjustedPrice": "20.0",
            "unitAdjustedPriceWithItemAdj": "20.0",
            "unitAdjustmentAmount": "0.0",
            "unitItemAdjustmentAmount": "0"
          },
          "message": null,
          "status": "Success"
        },
        {
          "cartItem": {
            "billingFrequency": null,
            "cartData": null,
            "cartDeliveryGroupId": "0a7xx00000000pdAAA",
            "cartId": "0a6xx00000000pdAAA",
            "cartItemId": "0a9xx00000000zKAAQ",
            "childProductCount": 0,
            "currencyIsoCode": "USD",
            "customFields": [],
            "firstPymtTotalAmount": "2.99",
            "firstPymtTotalListPrice": "3.99",
            "firstPymtTotalPrice": "2.99",
            "firstPymtTotalTax": "0.00",
            "isConfigurationAllowed": false,
            "isShippingChargeNotApplicable": false,
            "itemizedAdjustmentAmount": "0.00",
            "listPrice": "3.99",
            "messagesSummary": {
              "errorCount": null,
              "hasErrors": null,
              "limitedMessages": [],
              "relatedEntityId": null,
              "totalLineItemsWithErrors": null
            },
            "name": "Wired Mouse",
            "parentCartItemId": null,
            "productClass": "Simple",
            "productDetails": {
              "fields": {
                "LastModifiedDate": "2025-10-23T11:33:37Z",
                "FulfillmentQtyCalcMethod": null,
                "Description": "Wired mouse",
                "SpecificationType": "Commercial",
                "IsActive": "true",
                "LastReferencedDate": null,
                "StockKeepingUnit": "NHKWM",
                "Name": "Wired Mouse",
                "ShippingWeightUnitOfMeasure": null,
                "CreatedById": "005xx000001XBov",
                "CloneSourceId": null,
                "RecordTypeId": "012xx0000005qmC",
                "DiscontinuedDate": null,
                "ProductClass": "Simple",
                "CanRamp": "false",
                "DisplayUrl": null,
                "IsDeleted": "false",
                "IsAssetizable": "false",
                "ProductCode": null,
                "UsageModelType": null,
                "ExternalId": null,
                "ProductPurpose": "Sell",
                "LastViewedDate": null,
                "UserRecordAccessId": null,
                "HelpText": null,
                "CurrencyIsoCode": "USD",
                "AvailabilityDate": null,
                "SystemModstamp": "2025-10-23T11:33:37Z",
                "IsArchived": "false",
                "DecompositionScope": null,
                "Type": null,
                "EndOfLifeDate": null,
                "IsShippingChargeNotApplicable": "false",
                "QuantityUnitOfMeasure": null,
                "CreatedDate": "2025-10-23T11:33:37Z",
                "Family": null,
                "UnitOfMeasureId": null,
                "ShippingWeight": null,
                "LastModifiedById": "005xx000001XBov",
                "IsSoldOnlyWithOtherProds": "false"
              },
              "isConfigurationAllowed": null,
              "name": "Wired Mouse",
              "productClass": null,
              "productId": "01txx0000006kexAAA",
              "productSubscriptionInformation": null,
              "productUrlName": null,
              "purchaseQuantityRule": null,
              "sku": "NHKWM",
              "thumbnailImage": {
                "alternateText": "mouse.jpg",
                "contentVersionId": null,
                "id": "2pmxx000000000JAAQ",
                "mediaType": "Image",
                "sortOrder": 0,
                "thumbnailUrl": null,
                "title": "mouse.jpg",
                "url": "/cms/delivery/media/MCWAVWDLQILBFMFIG2LGAY5F3XYU?version=1.1&channelId=0apxx0000000003&oid=00Dxx00ThLVJ544"
              },
              "variationAttributes": {}
            },
            "productId": "01txx0000006kexAAA",
            "productSellingModelId": null,
            "promotionDisplayName": null,
            "quantity": "1.0",
            "salesPrice": "2.99",
            "sellingModelType": null,
            "subType": null,
            "subscriptionTerm": null,
            "totalAdjustmentAmount": "0.00",
            "totalAmount": "2.99",
            "totalListPrice": "3.99",
            "totalPrice": "2.99",
            "totalTax": "0.00",
            "type": "Product",
            "unitAdjustedPrice": "2.99",
            "unitAdjustedPriceWithItemAdj": "2.99",
            "unitAdjustmentAmount": "0.0",
            "unitItemAdjustmentAmount": "0"
          },
          "message": null,
          "status": "Success"
        }
      ],
      "count": 2,
      "currentPageToken": null,
      "currentPageUrl": null,
      "hasErrors": false,
      "nextPageToken": null,
      "nextPageUrl": null,
      "previousPageToken": "2025-10-23T13:49:07Z,0a9xx00000000zPAAQ,CreatedDateAsc",
      "previousPageUrl": "/services/data/v66.0/commerce/webstores/0ZExx00000000mP/carts/current/cart-items/0a9xx00000000zJ/children?page=2025-10-23T13%3A49%3A07Z%2C0a9xx00000000zPAAQ%2CCreatedDateAsc&pageSize=200&productFields=*&sort=CreatedDateAsc"
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_)
    *   `message` (_string_)
    
    _Example: InvalidParameter_
    
    ```
    {
      "errorCode": "INVALID_OPERATION",
      "message": "Currency ISO code not available: '\"INR\"'."
    }
    ```
    
*   **404** Not Found
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_)
    *   `message` (_string_)
    
    _Example_
    
    ```
    {
      "CartNotFound": {
        "value": {
          "errorCode": "CART_NOT_FOUND",
          "message": "Cart not found."
        }
      }
    }
    ```
    
*   **500** Internal Server Error - Unexpected system error occurred
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_)
    *   `message` (_string_)
    
    _Example: InvalidParameter_
    
    ```
    {
      "errorCode": "UNKNOWN_EXCEPTION",
      "message": "Invalid parameter value."
    }
    ```
    

### POST Applies a saved configuration context to a cart item. This API adds, updates, or deletes the cart item based on product configuration retrieved using a specified context ID. This API is supported only for dynamic product bundles. Merchants must ensure that the Product Configurator setup is complete before using this API.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/actions/apply-configuration`

Operation ID: `postCartItemsFromConfiguration`.

Applies a saved configuration context to a cart item.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartItemsConfigurationInputRepresentation`.

_Example: CartItemsConfigurationInput_ Applies the product configuration to the cart items.

```
{
  "contextId": "0000000c27nc17g001317606221363347ae616c7632d4266a1a108e90d10d983"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartItemsConfigurationOutputRepresentation`.
    
*   **400** Bad Request
    
    Media type: `application/json`. Schema: `object`.
    
    *   `message` (_string_)
    
    _Example: invalidContextId_ Invalid ContextId
    
    ```
    {
      "message": "Invalid context ID."
    }
    ```
    
    _Example: cartValidationFailed_ Cart validation failed
    
    ```
    {
      "message": "Cart validation failed."
    }
    ```
    
    _Example: productClassInvalid_ Product class is invalid
    
    ```
    {
      "message": "Invalid product class."
    }
    ```
    
    _Example: sellingModelInvalid_ Product selling model is invalid
    
    ```
    {
      "message": "Invalid product selling model."
    }
    ```
    
    _Example: maxCartLimitExceeded_ Max cart limit exceeded
    
    ```
    {
      "message": "Cart item limit exceeded."
    }
    ```
    
*   **401** UnAuthorized
    
    Media type: `application/json`. Schema: `object`.
    
    *   `message` (_string_)
    
    _Example_
    
    ```
    {
      "message": "Authentication failed."
    }
    ```
    
*   **403** Forbidden
    
    Media type: `application/json`. Schema: `array of object`.
    
    Array of `object`.
    
    *   `errorCode` (_string_)
    *   `message` (_string_)
    
    _Example: invalidOperation_ Invalid operation
    
    ```
    {
      "errorCode": "INVALID_OPERATION",
      "message": "The requested operation isn't allowed for this cart."
    }
    ```
    
    _Example: invalidInput_ Invalid input
    
    ```
    {
      "errorCode": "INVALID_INPUT",
      "message": "Invalid configuration parameters were provided."
    }
    ```
    
    _Example: insufficientAccess_ Insufficient access
    
    ```
    {
      "errorCode": "INSUFFICIENT_ACCESS_OR_READONLY",
      "message": "You don't have sufficient permissions to perform this operation."
    }
    ```
    
    _Example: cartInCheckoutState_ Cart in invalid state
    
    ```
    {
      "errorCode": "INVALID_OPERATION",
      "message": "The cart context can't be configured while the cart is in the checkout state."
    }
    ```
    
*   **404** Not Found
    
    Media type: `application/json`. Schema: `object`.
    
    *   `message` (_string_)
    
    _Example_
    
    ```
    {
      "message": "Cart not found."
    }
    ```
    
*   **409** Conflict
    
    Media type: `application/json`. Schema: `object`.
    
    *   `message` (_string_)
    
    _Example_
    
    ```
    {
      "message": "The request couldn’t be completed due to a conflict with the current cart state. Review your cart and try again."
    }
    ```
    
*   **412** Precondition Failed
    
    Media type: `application/json`. Schema: `array of object`.
    
    Array of `object`.
    
    *   `errorCode` (_string_)
    *   `message` (_string_)
    
    _Example: apexFailed_ Apex calculation failed
    
    ```
    {
      "errorCode": "APEX_FAILED",
      "message": "The cart summary calculation failed due to an internal Apex error."
    }
    ```
    
    _Example: ccaExecutionFailed_ CCA execution failed
    
    ```
    {
      "errorCode": "APEX_FAILED",
      "message": "Unable to calculate cart totals and promotions."
    }
    ```
    
*   **500** Internal Server Error
    
    Media type: `application/json`. Schema: `array of object`.
    
    Array of `object`.
    
    *   `errorCode` (_string_)
    *   `message` (_string_)
    
    _Example: unknownException_ Unknown exception
    
    ```
    {
      "errorCode": "UNKNOWN_EXCEPTION",
      "message": "An unexpected error occurred while processing the request."
    }
    ```
    
    _Example: systemError_ System error
    
    ```
    {
      "errorCode": "UNKNOWN_EXCEPTION",
      "message": "An internal system error occurred while configuring the cart context."
    }
    ```
    
    _Example: unhandledException_ Unhandled exception
    
    ```
    {
      "errorCode": "UNKNOWN_EXCEPTION",
      "message": "An error occurred while configuring the cart context."
    }
    ```
    
*   **503** Service Unavailable
    
    Media type: `application/json`. Schema: `array of object`.
    
    Array of `object`.
    
    *   `errorCode` (_string_)
    *   `message` (_string_)
    
    _Example: maintenanceMode_ System in maintenance mode
    
    ```
    {
      "errorCode": "INSERT_UPDATE_DELETE_NOT_ALLOWED_DURING_MAINTENANCE",
      "message": "The system is currently in maintenance mode and can't process requests. Try again later."
    }
    ```
    
    _Example: readOnlyMode_ System in read-only mode
    
    ```
    {
      "errorCode": "INSERT_UPDATE_DELETE_NOT_ALLOWED_DURING_MAINTENANCE",
      "message": "The system is currently in read-only mode and can't process updates. Try again later."
    }
    ```
    

### POST Distribute cart items into delivery groups.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups/actions/itemDistributions`

Operation ID: `postCartItemMove`.

Distribute cart items into delivery groups.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartItemMoveCollectionInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.BatchResultRepresentation`.
    

### GET Retrieve promotions associated with a cart.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/promotions`

Operation ID: `getCartPromotionCollection`.

Used to get all promotions associated with the cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartPromotionCollectionRepresentation`.
    

### POST Create a cart.

`POST /commerce/webstores/{webstoreId}/carts`

Operation ID: `postCartCollection`.

Gets a list of Carts or used for creating a cart.

Only buyers with read access to carts can create carts.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartInputRepresentation`.

_Example: CreateCartInput_ Example of the cart input to create a cart for the specified account using the provided currency, USD, in an org with the multicurrency feature enabled.

```
{
  "name": "MyCart",
  "type": "Cart",
  "currencyIsoCode": "USD",
  "effectiveAccountId": "001OL000002LC0qYAG"
}
```

_Example: CreateCartWithCustomFieldsInput_ Example of the cart input to create a cart with custom fields from the WebCart sObject. Custom fields are optional and must be previously defined for the sObject.

```
{
  "name": "MyCart",
  "type": "Cart",
  "currencyIsoCode": "USD",
  "effectiveAccountId": "001OL000002LC0qYAG",
  "customFields": {
    "attributes": {
      "type": "WebCart"
    },
    "MyCustomTextField__c": "Text",
    "MyCustomNumberField__c": 12.34,
    "MyCustomPercentField__c": 0.2345,
    "MyCustomGeolocationField__c": {
      "latitude": 33.345,
      "longitude": 45.567
    }
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation`.
    
    _Example: Example_ Successfully created cart.
    
    ```
    {
      "accountId": "3K0SG000000OTaQ0AW",
      "asyncOperationStatus": null,
      "cartId": "0a6SG000001qGHpYAM",
      "currencyIsoCode": "USD",
      "customFields": [],
      "firstPymtGrandTotalAmount": 0,
      "firstPymtTotalAmount": 0,
      "firstPymtTotalListPrice": 0,
      "firstPymtTotalTaxAmount": 0,
      "grandTotalAmount": 0,
      "isSecondary": false,
      "messagesSummary": {
        "errorCount": null,
        "hasErrors": null,
        "limitedMessages": [],
        "relatedEntityId": null,
        "totalLineItemsWithErrors": null
      },
      "name": "My Cart",
      "orderOwnerId": null,
      "ownerId": "005SG00000Gjt8oYAB",
      "purchaseOrderNumber": null,
      "status": "Active",
      "taxType": "Automatic",
      "totalAmountWithItemAdjustment": 0,
      "totalCartLevelAdjustmentAmount": 0,
      "totalChargeAmount": 0,
      "totalChargeAmountWithItemAdjustment": 0,
      "totalListPrice": 0,
      "totalProductAmount": 0,
      "totalProductAmountAfterAdjustments": 0,
      "totalProductCount": 0,
      "totalProductLineItemCount": 0,
      "totalProductListAmount": 0,
      "totalPromotionalAdjustmentAmount": 0,
      "totalSubProductCount": 0,
      "totalTaxAmount": 0,
      "type": "Cart",
      "uniqueProductCount": 0,
      "webstoreId": "0ZESG000001n96S4AQ"
    }
    ```
    
*   **404** Client Error
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation`.
    
    _Example: Example_ Client error.
    
    ```
    [
      {
        "errorCode": "NOT_FOUND",
        "message": "The requested resource doesn't exist."
      }
    ]
    ```
    
*   **500** Internal Server Error
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation`.
    
    _Example: Example_ Internal server error.
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "Invalid parameter value \\\"3K0SG000000OT\\\" for parameter \\\"id\\\"."
      }
    ]
    ```
    

### DELETE Delete an item in a cart.

`DELETE /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/{cartItemId}`

Operation ID: `deleteCartItem`.

Used to update or delete single cart item.

Only buyers with read access to carts can delete items in carts.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `cartItemId` (path, string (Id), required) The ID of the cart item.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success

### PATCH Update an item in a cart.

`PATCH /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/{cartItemId}`

Operation ID: `patchCartItem`.

Used to update or delete single cart item.

Buyers with read access to carts can update items in carts. Updating items in a cart respects buyer view product entitlements, and only users entitled to view product data can access it.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `cartItemId` (path, string (Id), required) The ID of the cart item.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.
*   `includeCartData` (query, boolean) Specify to include complete cart data in the response. This is available ONLY when in sync mode.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartItemInputRepresentation`.

_Example: UpdateCartItemsInput_ This cart input updates an item in a cart.

```
{
  "quantity": 7
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartItemRepresentation`.
    
    _Example: Example_ Successfully updated cart.
    
    ```
    {
      "billingFrequency": null,
      "cartDeliveryGroupId": "0a7SG000001vIajYAE",
      "cartId": "0a6SG000001rCgnYAE",
      "cartItemId": "0a9SG000005Lm0LYAS",
      "childProductCount": 0,
      "currencyIsoCode": "USD",
      "customFields": [],
      "firstPymtTotalAmount": null,
      "firstPymtTotalListPrice": 49.98,
      "firstPymtTotalPrice": 41,
      "firstPymtTotalTax": null,
      "itemizedAdjustmentAmount": 0,
      "listPrice": 24.99,
      "messagesSummary": {
        "errorCount": null,
        "hasErrors": null,
        "limitedMessages": [],
        "relatedEntityId": null,
        "totalLineItemsWithErrors": null
      },
      "name": "Alpine Energy Drink Chai Post 0.5L PET - 6 pack",
      "parentCartItemId": null,
      "productClass": "Simple",
      "productDetails": {
        "fields": {},
        "name": "Alpine Energy Drink Chai Post 0.5L PET - 6 pack",
        "productId": "01tSG000003uisfYAA",
        "productSubscriptionInformation": null,
        "purchaseQuantityRule": null,
        "sku": 6010009,
        "thumbnailImage": {
          "alternateText": null,
          "contentVersionId": null,
          "id": "2pmSG000005k7q3YAA",
          "mediaType": "Image",
          "sortOrder": 0,
          "thumbnailUrl": null,
          "title": "/northerntrailoutfitters.com/nto-alpine-nutrition/default/images/large/6Pack-Chai-Post-Large.jpg",
          "url": "https://s3.amazonaws.com/northerntrailoutfitters.com/nto-alpine-nutrition/default/images/large/6Pack-Chai-Post-Large.jpg"
        },
        "variationAttributes": {}
      },
      "productId": "01tSG000003uisfYAA",
      "productSellingModelId": null,
      "quantity": 2,
      "salesPrice": 20.5,
      "sellingModelType": null,
      "subType": null,
      "subscriptionTerm": null,
      "totalAdjustmentAmount": 0,
      "totalAmount": null,
      "totalListPrice": 49.98,
      "totalPrice": 41,
      "totalTax": null,
      "type": "Product",
      "unitAdjustedPrice": 20.5,
      "unitAdjustedPriceWithItemAdj": 20.5,
      "unitAdjustmentAmount": 0,
      "unitItemAdjustmentAmount": 0
    }
    ```
    

### GET Retrieve details of a delivery group in the cart.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups/{deliveryGroupId}`

Operation ID: `getDeliveryGroup`.

Delivery group in the cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `deliveryGroupId` (path, string (Id), required) The ID of the delivery group.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) Optional. The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.
*   `page` (query, string) Optional. The page token to use to view a page of information. Page tokens are returned as part of the response, such as currentPageToken or nextPageToken. If you don’t specify a value, the first page is returned.
*   `pageSize` (query, integer) Optional. The number of items per page. Valid values are from 1 through 100. If you don’t specify a value, the default size is 25.
*   `sort` (query, sfdc.commerce.cart.connect.api.enums.ConnectCartItemSortOrderEnum)

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.DeliveryGroupRepresentation`.
    

### DELETE Delete a delivery group in the cart.

`DELETE /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups/{deliveryGroupId}`

Operation ID: `deleteDeliveryGroup`.

Delivery group in the cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `deliveryGroupId` (path, string (Id), required) The ID of the delivery group.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `deleteCartItems` (query, boolean) Optional. Indicates whether to delete cart items associated with the delivery group (True) or not (False)
*   `effectiveAccountId` (query, string (Id)) Optional. The ID of the account for which the request is made. If unspecified, defaults to the account ID for the context user.

#### Responses

*   **200** Success

### PATCH Update a delivery group in the cart.

`PATCH /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups/{deliveryGroupId}`

Operation ID: `patchDeliveryGroup`.

Delivery group in the cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `deliveryGroupId` (path, string (Id), required) The ID of the delivery group.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.common.connect.api.input.DeliveryGroupV2InputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.DeliveryGroupRepresentation`.
    

### POST Perform a complete cart calculation based on the cart status.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/calculate`

Operation ID: `postCartCalculate`.

Calculates an existing cart.

Possible calculations include computing prices, evaluating promotions, checking the inventory, computing shipping costs, evaluating shipping promotions, applying post shipping adjustments, and computing taxes.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) Optional. The ID of the account for which the request is made. If unspecified, defaults to the account ID for the context user.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartCalculateInputRepresentation`.

_Example: cartCalculateInput_ Here's an example of the cart calculation POST request.

```
{
  "customFields": [
    {
      "attributes": {
        "type": "WebCart"
      },
      "WebCartCustomField1__c": "Foo"
    },
    {
      "attributes": {
        "type": "CartItem"
      },
      "id": "0a9xx0000000002CI1",
      "CartItemCustomField1__c": "CI1_Field1Value",
      "CartItemCustomField2__c": "CI1_Field2Value"
    },
    {
      "attributes": {
        "type": "CartItem"
      },
      "id": "0a9xx0000000002CI2",
      "CartItemCustomField1__c": "CI2_Field1Value",
      "CartItemCustomField2__c": "CI2_Field2Value"
    },
    {
      "attributes": {
        "type": "CartDeliveryGroup"
      },
      "id": "0a7xx000000000CDG1",
      "CartDeliveryGroupCustomField1__c": "CDG1_Field1Value",
      "CartDeliveryGroupCustomField2__c": "CDG1_Field2Value"
    }
  ]
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryResultRepresentation`.
    

### GET Retrieve summary for a cart.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}`

Operation ID: `getCartSummary`.

Create Cart/ Get Cart Summary/ Delete Cart

During asynchronous cart processing, if enabled, GET response headers include Location and Retry-After. While the cart is processing, GET requests return a 202 status and may include stale, null, or 0 pricing data. When cart processing is complete, requests return a 200 status with up-to-date pricing data.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation`.
    

### PUT Create an active cart

`PUT /commerce/webstores/{webstoreId}/carts/{activeCartOrId}`

Operation ID: `putCartSummary`.

Create Cart/ Get Cart Summary/ Delete Cart

If one doesn’t exist. Buyers with read access to carts can create carts. The PUT request doesn’t require parameters nor a request body.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation`.
    

### DELETE Delete a cart.

`DELETE /commerce/webstores/{webstoreId}/carts/{activeCartOrId}`

Operation ID: `deleteCartSummary`.

Create Cart/ Get Cart Summary/ Delete Cart

Only buyers with read access to carts can delete carts.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success

### PATCH patchCartSummary

`PATCH /commerce/webstores/{webstoreId}/carts/{activeCartOrId}`

Operation ID: `patchCartSummary`.

Create Cart/ Get Cart Summary/ Delete Cart

Update name and description for the cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id), required) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `object`.

*   `name` (_string_, required) The name of the cart. The name can have up to 250 Unicode characters. Avoid using special characters in the cart name, including `\"'<>@!$#&%\\{[]}`.
*   `description` (_string_) The description for the cart.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation`.
    
*   **400** Bad Request - Invalid input parameters or request data.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.ErrorOutputRepresentation`.
    
    _Example: InvalidEffectiveAccountId_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_API_INPUT",
          "message": "The provided EffectiveAccountId parameter is invalid or malformed."
        }
      ]
    }
    ```
    
*   **404** Not Found - Requested resource doesn't exist.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.ErrorOutputRepresentation`.
    
    _Example: WebstoreNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "WEBSTORE_NOT_FOUND",
          "message": "The specified webstore doesn't exist or isn't accessible."
        }
      ]
    }
    ```
    
*   **500** Internal Server Error - Unexpected system error occurred.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.ErrorOutputRepresentation`.
    
    _Example: InternalServerError_
    
    ```
    {
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "An unexpected error occurred while processing the request."
        }
      ]
    }
    ```
    

### GET Retrieve compact cart summary for an existing cart.

`GET /commerce/webstores/{webstoreId}/carts/compact-summary`

Operation ID: `getCartBadge`.

The compact cart summary for an existing cart.

#### Parameters

*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartSummaryCompactRepresentation`.
    
*   **400** Webstore not found
    
    Media type: `application/json`.
    
    _Example_
    
    ```
    [
      {
        "errorCode": "INVALID_INPUT",
        "message": "Invalid webstoreId"
      }
    ]
    ```
    

### POST Retrieve all promotions associated with the cart items.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-items/promotions`

Operation ID: `postCartItemPromotionCollection`.

Retrieve all promotions associated with the cart items.

POST methods typically create an item, but for this resource POST is used to retrieve information. Both POST and GET retrieve the same information. However, GET calls can be cached.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartItemPromotionCollectionInputRepresentation`.

_Example: Example_ Example of the cart item promotion collection input.

```
{
  "items": [
    {
      "cartItemId": "0a9xx000000000GAAQ"
    },
    {
      "cartItemId": "0a9xx000000000GBCQ"
    }
  ]
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartItemPromotionCollectionOutputRepresentation`.
    

### POST Preserve cart contents when a guest logs in as an authenticated customer.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/actions/preserve`

Operation ID: `postPreserveCart`.

Allows preserving the guest cart.

When a guest user adds products to a cart and then logs in, the API creates a new authorized cart and transfers the guest cart’s items and applied coupons to it. The API doesn’t transfer delivery details, tax calculations, or custom fields. It deletes the guest cart after a successful transfer.

If the customer already has an existing cart from a prior authenticated session, the API sets the newly authorized cart as the primary cart and retains the previous cart as a secondary cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.PreserveCartOutputRepresentation`.
    

### POST Arrange cart items into delivery groups.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups/actions/arrange-items`

Operation ID: `postCartItemArrange`.

Arrange cart items among delivery groups

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `deleteEmptyDeliveryGroups` (query, boolean) Specifies whether to delete delivery groups with no cart items (true) or not (false). If unspecified, the default value is true.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.ItemArrangementsInputRepresentation`.

_Example: Example_ Delivery group collection.

```
{
  "arrangements": [
    {
      "deliveryGroupId": "0a7xx000000004rAAA",
      "cartItemId": "0a9xx000000004rAAA",
      "quantity": 5
    }
  ]
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.DeliveryGroupCollectionRepresentation`.
    

### GET Retrieve coupons associated with a cart.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-coupons`

Operation ID: `getCartCouponCollection`.

Apply a coupon code to a cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartCouponCollectionRepresentation`.
    

### POST Apply a coupon code to a cart.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/cart-coupons`

Operation ID: `postCartCouponCollection`.

Apply a coupon code to a cart.

In API version 63.0 and later, if your store has simplified cart cleanup enabled, a POST request can apply a coupon to a cart without canceling checkout.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `currencyIsoCode` (query, string) The three-letter ISO 4217 currency code of the cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CartCouponInputRepresentation`.

_Example: Example_ Apply coupon.

```
{
  "couponCode": "COUP10",
  "customFields": [
    {
      "attributes": {
        "type": "WebCartAdjustmentBasis"
      },
      "Test__C": "test@salesforce.com"
    }
  ]
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartCouponCollectionRepresentation`.
    

### GET Retrieve a collection of delivery groups in a cart.

`GET /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups`

Operation ID: `getDeliveryGroupCollection`.

Create a collection of delivery groups in a cart.

Use CartItemLimit query param to limit the number of cart items included in each delivery group

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `cartItemLimit` (query, integer) The limit of items in a cart.
*   `effectiveAccountId` (query, string (Id)) The ID of the account for which the request is made. If unspecified, defaults to the account ID for the context user.
*   `page` (query, string) Specifies the page token to use to view a page of information. Page tokens are returned as part of the response, such as currentPageToken or nextPageToken. If you don’t specify a value, the first page is returned.
*   `pageSize` (query, integer) Specifies the number of items per page. Valid values are from 1 through 100. If you don’t specify a value, the default size is 25.
*   `sort` (query, sfdc.commerce.cart.connect.api.enums.ConnectCartItemSortOrderEnum)

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.DeliveryGroupCollectionRepresentation`.
    

### POST Create a collection of delivery groups in a cart.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/delivery-groups`

Operation ID: `postDeliveryGroupCollection`.

Create a collection of delivery groups in a cart.

#### Parameters

*   `activeCartOrId` (path, string, required) The valid value is—cartId (ID of the cart), active (this value is only to be used for authenticated users), or current (cart that isn’t closed or pending deletion). Use active only for B2B Aura stores; all other stores must use current.
*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `effectiveAccountId` (query, string (Id)) The ID of the account for which the request is made. If unspecified, defaults to the account ID for the context user.

#### Request body

Media type: `application/json`. Schema: `sfdc.commerce.common.connect.api.input.DeliveryGroupV2InputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.DeliveryGroupRepresentation`.
    

### POST Create a new quote from an active cart by converting cart items into quote line items.

`POST /commerce/webstores/{webstoreId}/carts/{activeCartOrId}/quotes`

Operation ID: `postQuoteFromCart`.

This API is used on the Cart page of the B2B storefront to create a quote from the active cart, retaining pricing and customer details. Buyers can also specify an expiration date and add comments for negotiation.

To access these resources, your org must have the B2B Commerce license. This API is available only to authenticated users.

**Note:** The Commerce Quotes APIs don't support product bundles. Only simple products can be included in quote.

To access this API, your org must have the B2B Commerce license. This API is available only to authenticated users.

This API is used on the Cart page of the B2B storefront to create a quote from the active cart, retaining pricing and customer details. Buyers can also specify an expiration date and add comments for negotiation.

**Note:** Carts must contain at least one product to create a quote. Empty carts return an error. Promotions and bonus products aren't supported.

Supported product types by license:

*   Simple products: Supported with B2B Commerce Only or B2B Commerce and Revenue Cloud licenses.
*   Static bundles: Supported only with the B2B Commerce and Revenue Cloud licenses.
*   Dynamic bundles: Supported only with the B2B Commerce and Revenue Cloud licenses.
*   Subscription products: Not supported with either B2B Commerce Only or B2B Commerce and Revenue Cloud licenses.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `activeCartOrId` (path, string (Id), required) The valid value is the cart ID of an active cart only.

#### Request body (required)

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CreateQuoteFromCartInputRepresentation`.

_Example_

```
{
  "comments": "Provide bulk pricing for orders of 100+ units. We are interested in a long-term partnership.",
  "additionalFields": {
    "ExpirationDate": "2025-12-31",
    "BuyerEmail__c": "procurement@company.com"
  },
  "deleteCart": false
}
```

#### Responses

*   **200** Success — Quote created from cart.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CreateQuoteFromCartOutputRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "quoteId": "0Q0xx0000000001EAA",
      "errors": []
    }
    ```
    
*   **400** Bad Request - Invalid input parameters or request data.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CreateQuoteFromCartOutputRepresentation`.
    
    _Example: InvalidCart_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_INPUT",
          "message": "The specified context ID is invalid."
        }
      ]
    }
    ```
    
    _Example: InvalidCustomFields_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_CUSTOM_FIELDS",
          "message": "One or more custom field values are invalid or don't meet required criteria."
        }
      ]
    }
    ```
    
    _Example: BundlesNotSupported_
    
    ```
    {
      "errors": [
        {
          "code": "BUNDLES_NOT_SUPPORTED",
          "message": "This request doesn't support product bundles."
        }
      ]
    }
    ```
    
*   **404** Not Found - Requested resource doesn't exist.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CreateQuoteFromCartOutputRepresentation`.
    
    _Example: CartNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "CART_NOT_FOUND",
          "message": "The specified cart doesn't exist or you don't have access to it."
        }
      ]
    }
    ```
    
    _Example: WebstoreNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "WEBSTORE_NOT_FOUND",
          "message": "he specified web store doesn't exist or you do not have access to it."
        }
      ]
    }
    ```
    
*   **500** Internal Server Error - Unexpected system error occurred.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CreateQuoteFromCartOutputRepresentation`.
    
    _Example: InternalServerError_
    
    ```
    {
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "An unexpected error occurred while processing the request."
        }
      ]
    }
    ```
    

### POST Create a cart from an approved quote, or duplicate a draft quote into a cart by converting the quote into cart items.

`POST /commerce/webstores/{webstoreId}/quotes/{quoteId}/cart`

Operation ID: `postCartFromQuote`.

This API performs one of the following operations based on the quote status:

*   Create Cart from Quote:
    *   Create a cart from a quote only when its status is Approved or Accepted, as initiated by the Accept & Buy action on the My Quotes page of the B2B storefront.
    *   All items are added at the negotiated and discounted prices.
    *   A quote can be converted to a cart only once if the resulting cart is used to place an order. After the order is placed, the same quote can't be reused.
    *   If the cart is cleared after conversion (before placing an order), the quote can be converted to a cart again.
*   Duplicate Quote to Cart:
    *   Duplicate the quote to cart, as initiated by the Duplicate to Cart action on the My Quotes page of the B2B storefront. This operation isn't supported only for quotes in Approved or Accepted status.
    *   All items are added at their original prices.

Duplicate-to-cart and convert-to-cart operations succeed only when the cart has no matching products. For example, if both the quote and the cart contain Product A, the API returns an error. Partial conversion or duplication, promotions, and bonus products aren't supported.

Supported product types by license:

*   Simple products: Supported with B2B Commerce only or B2B Commerce and Revenue Cloud licenses.
*   Static bundles: Supported with B2B Commerce only or B2B Commerce and Revenue Cloud licenses.
*   Dynamic bundles: Supported only with the B2B Commerce and Revenue Cloud license.
*   Subscription products: Not supported with either B2B Commerce Only or B2B Commerce and Revenue Cloud licenses.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `quoteId` (path, string (Id), required) The ID of the quote record to convert to a cart.

#### Request body (required)

Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.input.CreateCartFromQuoteInputRepresentation`.

_Example_

```
{
  "operationType": "CONVERT_TO_CART"
}
```

#### Responses

*   **200** Success — Cart created from quote.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartFromQuoteOutputRepresentation`.
    
    _Example: Success_
    
    ```
    {
      "cartId": "0Q0xx0000000001EAA",
      "errors": []
    }
    ```
    
*   **400** Bad Request - Invalid input parameters or request data.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartFromQuoteOutputRepresentation`.
    
    _Example: InvalidOperationType_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_OPERATION_TYPE",
          "message": "The provided operationType isn't supported."
        }
      ]
    }
    ```
    
*   **404** Not Found - Requested resource doesn't exist.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartFromQuoteOutputRepresentation`.
    
    _Example: QuoteNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "QUOTE_NOT_FOUND",
          "message": "The specified quote doesn't exist or isn't accessible."
        }
      ]
    }
    ```
    
    _Example: WebstoreNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "WEBSTORE_NOT_FOUND",
          "message": "The specified webstore doesn't exist or isn't accessible."
        }
      ]
    }
    ```
    
*   **500** Internal Server Error - Unexpected system error occurred.
    
    Media type: `application/json`. Schema: `sfdc.commerce.cart.connect.api.output.CartFromQuoteOutputRepresentation`.
    
    _Example: ProcessingError_
    
    ```
    {
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "An unexpected error occurred while creating the cart from the quote."
        }
      ]
    }
    ```
    

## Schemas

### sfdc.commerce.cart.connect.api.input.CartMessagesVisibilityInputRepresentation

Input for updating a message visibility status.

*   `visibility` (_boolean_) Indicates whether to set cart messages as visible (true) or not (false).

### sfdc.commerce.cart.connect.api.output.CartMessagesVisibilityResultRepresentation

Represents the updated visibility value for the cart messages.

*   `visibility` (_boolean_) Indicates whether cart messages are set to visible (true) or not (false).

### sfdc.commerce.cart.connect.api.input.CartItemInputRepresentation

Details of a cart item input.

*   `cartDeliveryGroupId` (_string_) The ID of the cart delivery group associated with the cart item.
*   `customFields` (_array of object_) An array of sObjects and custom fields for the sObjects. Standard fields are ignored. The custom fields must already be defined for the sObject. Currently, only the CartItem sObject is supported. Field-level security rules from the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile. The custom fields can be of type Checkbox, Currency, Date, Email, LongTextArea, Number, Percent, Phone, Text, TextArea, Url, Address, or Location. The customFields property isn't supported in stores built on an Aura template.
    
    Additional properties: `any`.
    
*   `productId` (_string_) The ID of the product.
*   `productSellingModelId` (_string_) The ID of the product selling model associated with Product2.
*   `quantity` (_string_) The quantity of the cart item. Use a value that can be converted to BigDecimal.
*   `subscriptionTerm` (_integer_) The total number of terms in the subscription period.
*   `type` (_any_) The type of item in a cart. This field isn't supported for the PATCH method.

### core.connect.api.output.common.BatchRepresentation

Result of an entire batch request operation. Results are ordered in the same order in which the requests were given. Results are either a successful result with a response body, a successful result without a response body, or an error result without a response body. Success and error are determined by the status code in each result.

*   `hasErrors` (_boolean_) Indicates whether at least one of the results is an error status code in the 400 or 500 range (true) or not (false).
*   `results` (_array of sfdc.commerce.cart.connect.api.output.BatchResultRepresentation_) The collection of batch result items.

### sfdc.commerce.cart.connect.api.input.CartEvaluateShippingInputRepresentation

Details of the cart calculate evaluate shipping input request.

*   `customFields` (_array of object_) Array of sObjects and custom fields for the sObjects. Standard fields are ignored. The custom fields must already be defined for the sObject. Currently, the WebCart, CartItem, and CartDeliveryGroup sObjects are supported. Field-level security rules from the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile.
    
    Additional properties: `any`.
    
*   `shippingAddress` (_sfdc.commerce.common.connect.api.input.CartShippingAddressInputRepresentation_)

### sfdc.commerce.cart.connect.api.output.CartSummaryResultRepresentation

Result of calculating a cart.

Includes all fields of `sfdc.commerce.cart.connect.api.output.CommerceResultRepresentationBase`.

*   `data` (_sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation_)

### sfdc.commerce.cart.connect.api.output.ProductCartItemRepresentation

Cart items of a specific product type.

*   `cartItems` (_array of sfdc.commerce.cart.connect.api.output.CartItemResultRepresentation_) The collection of items in a cart.
*   `product` (_sfdc.commerce.cart.connect.api.output.CartProductSummaryRepresentation_)

### sfdc.commerce.cart.connect.api.input.CartInventoryReservationInputRepresentation

Details of the create a reservation input request.

*   `durationInSeconds` (_integer_, required) Reservation duration in seconds.

### sfdc.commerce.cart.connect.api.output.CartInventoryReservationOutputRepresentation

An inventory reservation.

*   `errorCode` (_string_) The error code for this reservation.
*   `errorMessage` (_string_) The error message for this reservation.
*   `inventoryItemReservations` (_array of sfdc.commerce.cart.connect.api.output.CartInventoryItemReservationOutputRepresentation_) The collection of inventory item reservations.
*   `reservationIdentifier` (_string_) The reservation identifier.
*   `success` (_boolean_) Indicates whether the transaction was successful (true) or not (false).

### sfdc.commerce.cart.connect.api.output.ProductCartItemCollectionRepresentation

Items in the cart, grouped by product type.

*   `count` (_integer_) The number of cart items returned on the current page.
*   `currentPage` (_integer_) The current page of cart items. The value matches the requested page number, unless the requested page number exceeds the total number of pages. In this scenario, the current page is the highest available page number.
*   `hasErrors` (_boolean_) Indicates whether at least one of the results contains an error (True) or not (False).
*   `products` (_array of sfdc.commerce.cart.connect.api.output.ProductCartItemRepresentation_) The collection of products in the cart.
*   `totalItemCount` (_integer_) The total number of unique products in the cart.
*   `totalNumberOfPages` (_integer_) The total number of pages for the given page size.

### sfdc.commerce.cart.connect.api.input.CartToWishlistInputRepresentation

Details of products to be copied from a cart to a wishlist.

*   `wishlistId` (_string_) The ID of the wishlist to copy cart products to.

### sfdc.commerce.cart.connect.api.output.CartToWishlistResultRepresentation

Result of copying products from a cart to a wishlist.

*   `productsAddedCount` (_integer_) The number of products copied from the cart to the wishlist.
*   `wishlistId` (_string (Id)_) The ID of the wishlist that cart products were copied to.

### sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation

Summary of information about a cart and its contents.

*   `accountId` (_string (Id)_) The ID of account for the cart.
*   `asyncOperationStatus` (_sfdc.commerce.cart.connect.api.enums.ConnectCartAsyncOperationStatusEnum_)
*   `cartId` (_string (Id)_) The ID of the cart.
*   `currencyIsoCode` (_string_) The three-letter ISO 4217 currency code associated with the cart.
*   `customFields` (_array of object_) Array of sObjects and viewable custom fields for the sObjects. Field-level security rules from the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile. If no custom fields were specified, returns an empty collection.
    
    Additional properties: `any`.
    
*   `firstPymtGrandTotalAmount` (_string_) First payment amount for subscription products, plus the total payment amount for non-subscription products, including taxes.
*   `firstPymtTotalAmount` (_string_) The total amount on the first payment of the cart.
*   `firstPymtTotalListPrice` (_string_) The total list price on the first payment of the cart.
*   `firstPymtTotalTaxAmount` (_string_) Tax amount on the first payment for any subscription products, plus the total tax amount on non-subscription products.
*   `grandTotalAmount` (_string_) Grand total amount including shipping and tax for items in the cart, in the currency of the cart. and tax).
*   `isSecondary` (_boolean_) Indicates whether the cart is secondary (true) or not (false).
*   `messagesSummary` (_sfdc.commerce.cart.connect.api.output.CartMessagesSummaryRepresentation_)
*   `name` (_string_) The name for the cart. The name can have up to 250 Unicode characters. Avoid using special characters in the cart name, including `\"'<>@!$#&%\\{[]}`. If unspecified, a cart name is generated automatically using the pattern, `Untitled Cart - [Date] [Time]`.
*   `description` (_string_) The description for the cart.
*   `orderOwnerId` (_string (Id)_) The ID of the owner of the cart.
*   `ownerId` (_string (Id)_) The ID of the owner of the order.
*   `purchaseOrderNumber` (_string_) The purchase order for the cart.
*   `status` (_sfdc.commerce.cart.connect.api.enums.ConnectCartStatusEnum_)
*   `taxType` (_sfdc.commerce.cart.connect.api.enums.ConnectCartTaxTypeEnum_)
*   `totalAmountWithItemAdjustment` (_string_) The total amount, including both tier and item level discounts but excluding cart level discounts, for all items in the cart.
*   `totalCartLevelAdjustmentAmount` (_string_) The total cart level discount amount for the cart.
*   `totalChargeAmount` (_string_) The total amount for shipping and other charges in the currency of the cart. Includes adjustments from shipping promotions.
*   `totalChargeAmountWithItemAdjustment` (_string_) The total amount with shipping item level adjustment on cart.
*   `totalListPrice` (_string_) The total list price for the cart.
*   `totalProductAmount` (_string_) The total including discounts, but excluding shipping and tax, for product items in the cart.
*   `totalProductAmountAfterAdjustments` (_string_) The total product amount when promotion is turned off and sum of total product amount and total promotional adjustment amount with promotions turned on.
*   `totalProductCount` (_string_) The total count of items in the cart. This field may not be accurate when faster add-to-cart is turned on and quantity rules are enabled for products in the cart.
*   `totalProductLineItemCount` (_integer_) The total count of line items, of the type Product, in the cart. cart.
*   `totalProductListAmount` (_string_) The total list amount for products in the cart.
*   `totalPromotionalAdjustmentAmount` (_string_) The total promotional adjustment amount for items in the cart. This is the sum of all Itemized adjustment amounts and distributed adjustment amounts in the cart.
*   `totalSubProductCount` (_string_) The total quantity of all cart items with the selling model type Evergreen or Term-Defined.
*   `totalTaxAmount` (_string_) The total tax amount for the cart, including tax on shipping, if applicable.
*   `type` (_sfdc.commerce.cart.connect.api.enums.ConnectCartTypeEnum_)
*   `uniqueProductCount` (_integer_) The total count of unique items, or SKUs, in the cart. This field is supported when faster add-to-cart is turned off.
*   `webstoreId` (_string (Id)_) The ID of the webstore of the cart.

### sfdc.commerce.cart.connect.api.output.CommerceActionResultRepresentation

Result of executing a commerce action.

*   `isSuccess` (_boolean_) Indicates whether the action is a success (true) or not (false).
*   `message` (_string_) The action result message.

### sfdc.commerce.cart.connect.api.input.CartEvaluateTaxInputRepresentation

Details of the evaluate tax input request.

*   `customFields` (_array of object_) Array of sObjects and custom fields for the sObjects. Standard fields are ignored. The custom fields must already be defined for the sObject. Currently, the WebCart, CartItem, and CartDeliveryGroup sObjects are supported. Field-level security rules from the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile.
    
    Additional properties: `any`.
    
*   `shippingAddress` (_sfdc.commerce.common.connect.api.input.CartShippingAddressInputRepresentation_)

### sfdc.commerce.cart.connect.api.enums.ConnectCartItemSortOrderEnum

The sort order for items in a cart.

Type: `string`.

Allowed values: `CreatedDateAsc—Sorts by oldest creation date.`, `CreatedDateDesc—Sorts by most recent creation date.`, `NameAsc—Sorts by name in ascending alphabetical order (A–Z).`, `NameDesc—Sorts by name in descending alphabetical order (Z–A).`, `SalesPriceAsc—Sorts from lowest to highest negotiated price.`, `SalesPriceDesc—Sorts from highest to lowest negotiated price.`.

### sfdc.commerce.cart.connect.api.output.CartItemCollectionRepresentation

Details of the collection of items in a cart.

*   `cartCoupons` (_sfdc.commerce.cart.connect.api.output.CartCouponCollectionRepresentation_)
*   `cartItems` (_array of sfdc.commerce.cart.connect.api.output.CartItemResultRepresentation_) The collection of items in a cart.
*   `cartPromotions` (_sfdc.commerce.cart.connect.api.output.CartPromotionCollectionRepresentation_)
*   `cartSummary` (_sfdc.commerce.cart.connect.api.output.CartSummaryRepresentation_)
*   `approachingDiscounts` (_array of string_) The list of approaching discount messages.
*   `count` (_integer_) The number of cart items returned on the current page.
*   `currentPage` (_integer_) The current page of cart items. The value matches the requested page number, unless the requested page number exceeds the total number of pages. In this scenario, the current page is the highest available page number.
*   `currentPageToken` (_string_) The token identifying the current page.
*   `currentPageUrl` (_string_) The URL identifying the current page.
*   `hasErrors` (_boolean_) Indicates whether at least one of the results contains an error (true) or not (false).
*   `nextPageToken` (_string_) The token identifying the next page, or null if there isn’t a next page.
*   `nextPageUrl` (_string_) The URL identifying the next page, or null if there isn’t a next page.
*   `previousPageToken` (_string_) The token identifying the previous page, or null if there isn’t a previous page.
*   `previousPageUrl` (_string_) The URL identifying the previous page, or null if there isn’t a previous page.
*   `total` (_integer_) The total number of unique products in the cart.
*   `totalNumberOfPages` (_integer_) The total number of pages for the given page size.

### sfdc.commerce.cart.connect.api.output.CartItemRepresentation

Details of an item in a cart.

Includes all fields of `sfdc.commerce.cart.connect.api.output.AbstractCartItemRepresentation`.

*   `currencyIsoCode` (_string_) The three-letter ISO 4217 currency code of the cart.
*   `firstPymtTotalAmount` (_string_) For subscription items, the first payment amount after adjustments and taxes. For non-subscription products, the value is the same as totalAmount.
*   `firstPymtTotalListPrice` (_string_) For subscription items, the total list price of the first payment. For non-subscription items, the value is the same as totalListPrice.
*   `firstPymtTotalPrice` (_string_) For subscription items, the first term price, including adjustments but excluding taxes. For non-subscription items, the total price, including adjustments but excluding taxes.
*   `firstPymtTotalTax` (_string_) For subscription items, the tax amount on the first payment. For non-subscription products, the value is the same as totalTax.
*   `itemizedAdjustmentAmount` (_string_) Total itemized adjustment amount for the item, including promotions and excluding taxes.
*   `listPrice` (_string_) List price for the item.
*   `productClass` (_commerce.catalog.connect.api.enumeration.ConnectProductClassEnum_)
*   `salesPrice` (_string_) Sales price for the item.
*   `totalAdjustmentAmount` (_string_) Total adjustment amount for the item.
*   `totalAmount` (_string_) Total amount for the item.
*   `totalListPrice` (_string_) Total list price for the item.
*   `totalPrice` (_string_) Total price for the item including adjustments but excluding taxes.
*   `totalTax` (_string_) Total tax for the item.
*   `unitAdjustedPrice` (_string_) Unit price, including tier level discounts, for the item. This value is informational only and isn’t used in pricing calculations.
*   `unitAdjustedPriceWithItemAdj` (_string_) Unit price, including both tier and item level discounts, for the item. For bundle products, this value represents the aggregate price of both exclusive and inclusive products. This value is informational only and isn’t used in pricing calculations.
*   `unitAdjustmentAmount` (_string_) Tier level adjustments made to the unit price for the item. This value is informational only and isn’t used in pricing calculations.
*   `unitItemAdjustmentAmount` (_string_) Item level adjustments made to the unit price for the item. This value is informational only and isn’t used in pricing calculations.

### sfdc.commerce.cart.connect.api.output.ChildCartItemCollectionRepresentation

Collection of child cart items associated with the parent cart item.

*   `childCartItems` (_array of sfdc.commerce.cart.connect.api.output.CartItemResultRepresentation_) The collection of items in a cart.
*   `count` (_integer_) The number of cart items returned on the current page.
*   `currentPageToken` (_string_) The token identifying the current page of cart items.
*   `currentPageUrl` (_string_) The URL to the current page of cart items.
*   `hasErrors` (_boolean_) Indicates whether at least one of the results contains an error (True) or not (False).
*   `nextPageToken` (_string_) The token identifying the next page of cart items.
*   `nextPageUrl` (_string_) The URL to the next page of cart items.
*   `previousPageToken` (_string_) The token identifying the previous page of cart items.
*   `previousPageUrl` (_string_) The URL to the previous page of of cart items.

### sfdc.commerce.cart.connect.api.input.CartItemsConfigurationInputRepresentation

Represents the input payload used to configure a cart item based on the provided context ID.

*   `contextId` (_string_) Specifies the unique transaction context ID for the product configuration instance.

### sfdc.commerce.cart.connect.api.output.CartItemsConfigurationOutputRepresentation

Represents the response details returned from cart configuration operations.

### sfdc.commerce.cart.connect.api.input.CartItemMoveCollectionInputRepresentation

Collection of cart items to be moved into delivery groups.

*   `cartItems` (_array of sfdc.commerce.cart.connect.api.input.CartItemMoveInputRepresentation_) An array of cart items to be moved into delivery groups.

### sfdc.commerce.cart.connect.api.output.BatchResultRepresentation

Batch result item.

*   `batchResult` (_array of sfdc.commerce.cart.connect.api.output.CartItemMoveRepresentation_) The details of an item in a cart.

### sfdc.commerce.cart.connect.api.output.CartPromotionCollectionRepresentation

Promotions associated with a cart.

*   `cartId` (_string (Id)_) The ID of the cart.
*   `cartStatus` (_sfdc.commerce.cart.connect.api.enums.ConnectCartStatusEnum_)
*   `currencyIsoCode` (_string_) The three-letter ISO 4217 currency code associated with the cart.
*   `promotions` (_sfdc.commerce.cart.connect.api.output.CartPromotionListRepresentation_)

### sfdc.commerce.cart.connect.api.input.CartInputRepresentation

Details of the create cart input request.

*   `currencyIsoCode` (_string_) The currency ISO code of the cart.
*   `customFields` (_array of object_) An array of sObjects and custom fields for the sObjects. Standard fields are ignored. The custom fields must already be defined for the sObject. Currently, only the WebCart sObject is supported. Field-level security rules from the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile.
    
    Additional properties: `any`.
    
*   `effectiveAccountId` (_string_) The ID of the buyer account or guest buyer profile for which the request is made. If unspecified, the default value is determined from context.
*   `isSecondary` (_boolean_) Indicates whether the cart is secondary (true) or not (false). If unspecified, defaults to false.
*   `name` (_string_) The name of the cart. The name can have up to 250 Unicode characters. Avoid using special characters in the cart name, including `\"'<>@!$#&%\\{[]}`. If no cart name is specified, a default name is generated. When Multi Cart Management is enabled, the generated cart name uses the format `Untitled Cart - [Date] [Time]`. For assistance with Multi Cart Management, contact Salesforce Customer Support.
*   `orderOwnerId` (_string_) The ID of the owner of the order.
*   `type` (_sfdc.commerce.cart.connect.api.enums.ConnectCartTypeEnum_)
*   `typeAsString` (_string_) The type of the cart provided as a string.

### sfdc.commerce.cart.connect.api.output.DeliveryGroupRepresentation

Delivery group for a Commerce store checkout.

*   `availableDeliveryMethods` (_array of sfdc.commerce.cart.connect.api.output.DeliveryMethodRepresentation_) The list of available delivery methods. When Shipping is disabled for your web store, the delivery methods list is empty.
*   `cartId` (_string_) The ID of the cart.
*   `cartItems` (_sfdc.commerce.cart.connect.api.output.CartItemCollectionRepresentation_)
*   `deliveryAddress` (_sfdc.commerce.common.connect.api.output.CheckoutAddressV2Representation_)
*   `desiredDeliveryDate` (_string (date)_) The date when the customer wants the items delivered.
*   `errors` (_array of sfdc.commerce.common.connect.api.output.CheckoutErrorRepresentation_) Errors
*   `id` (_string (Id)_) The ID for the delivery group.
*   `isDefault` (_boolean_) Indicates whether the delivery group is the default (True) or not (False). The default value is False.
*   `name` (_string_) The name of the delivery group.
*   `selectedDeliveryMethod` (_sfdc.commerce.cart.connect.api.output.DeliveryMethodRepresentation_)
*   `shippingInstructions` (_string_) Special shipping and handling instructions.
*   `totalCartItemCount` (_integer_) The number of cart items, including their quantities, of the type Product in the delivery group.
*   `totalCartItemQuantity` (_number (double)_)
    
    The total quantity of all product-type cart items within a delivery group. Supports up to four decimal places. The `totalCartItemCount` field truncates to integers.
    
    **Note:** Support for four decimal places is available for the Shipping service. Use of this precision may vary across other product types and checkout flows, such as tax and order processing, based on their handling of fractional quantities. For details, see the [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.html).
    
*   `totalProductAmount` (_string_) The sum of all the cart items’ totalPrice for cart items of the type Product in the delivery group.
*   `isGift` (_boolean_) Indicates whether the delivery group is a gift (`true`) or not (`false`). The default value is False.
*   `giftMessage` (_string_) The gift message for the delivery group.
*   `giftToName` (_string_) The name of the gift recipient.

### sfdc.commerce.common.connect.api.input.DeliveryGroupV2InputRepresentation

Representation of the checkout delivery group input.

*   `id` (_string_) The ID of the delivery group.
*   `deliveryMethodId` (_string_) The ID of the delivery method.
*   `desiredDeliveryDate` (_string (date)_) The delivery date of the delivery group.
*   `shippingInstructions` (_string_) The shipping instructions for the delivery group.
*   `deliveryAddress` (_sfdc.commerce.common.connect.api.input.CheckoutAddressInputV2Representation_)
*   `name` (_string_) Cart Delivery Group Name
*   `isGift` (_boolean_) Indicates whether the delivery group is a gift (true) or not (false). The default value is False.
*   `giftMessage` (_string_) The gift message for the delivery group.
*   `giftToName` (_string_) The name of the gift recipient.

### sfdc.commerce.cart.connect.api.input.CartCalculateInputRepresentation

Calculate cart input request.

*   `customFields` (_array of object_) An array of sObjects and custom fields for the sObjects. Standard fields are ignored. The custom fields must already be defined for the sObject. Currently, the WebCart, CartItem, and CartDeliveryGroup sObjects are supported. Field-level security rules from the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile.
    
    Additional properties: `any`.
    

### sfdc.commerce.cart.connect.api.output.ErrorOutputRepresentation

Representation of the error response.

*   `code` (_string_, required) The error code identifying the type of error.  
    Example: `INVALID_INPUT`.
*   `message` (_string_, required) The message stating the reason for error, if any.  
    Example: `The provided parameter is invalid or malformed`.

### sfdc.commerce.cart.connect.api.output.CartSummaryCompactRepresentation

A compact cart summary for an existing cart.

*   `cartId` (_string_) The ID of the cart.
*   `currencyIsoCode` (_string_) The currency code associated with this cart.
*   `totalProductCount` (_string_) The total count of all the items in the cart.
*   `uniqueProductCount` (_integer_) The total count of unique items (SKUs) in the cart.

### sfdc.commerce.cart.connect.api.input.CartItemPromotionCollectionInputRepresentation

Representation of the cart item promotion input.

*   `items` (_array of sfdc.commerce.cart.connect.api.input.CartItemPromotionInputRepresentation_) The list of cart items to get the associated promotions.

### sfdc.commerce.cart.connect.api.output.CartItemPromotionCollectionOutputRepresentation

CartItemPromotionCollection representation includes all the promotions associated with the cart items.

*   `currencyIsoCode` (_string_) The three-letter ISO 4217 currency code associated with the cart.
*   `items` (_object_) The map of cart items to promotions.
    
    Additional properties: `sfdc.commerce.cart.connect.api.output.CartPromotionListRepresentation`.
    

### sfdc.commerce.cart.connect.api.output.PreserveCartOutputRepresentation

Representation of a preserve cart.

*   `cartId` (_string (Id)_) The ID of the authenticated cart.
*   `currencyIsoCode` (_string_) The three-letter ISO 4217 currency code of the authenticated cart.
*   `failedCartItems` (_array of sfdc.commerce.cart.connect.api.output.CartItemBasicResultRepresentation_) The list of products that weren’t successfully transferred from the guest cart to the authenticated cart.
*   `numberOfProducts` (_integer_) The total number of products in the guest cart.
*   `numberOfProductsWithError` (_integer_) The total number of products that weren’t successfully transferred from the guest cart to the authenticated cart.
*   `numberOfProductsWithSuccess` (_integer_) The total number of products successfully transferred from the guest cart to the authenticated cart.
*   `succeededCartItems` (_array of sfdc.commerce.cart.connect.api.output.CartItemBasicResultRepresentation_) The list of products successfully transferred from the guest cart to the authenticated cart.

### sfdc.commerce.cart.connect.api.input.ItemArrangementsInputRepresentation

Representation of the cart item arrange input.

*   `arrangements` (_array of sfdc.commerce.cart.connect.api.input.ItemArrangeInputRepresentation_) The set of instructions to arrange cart items into delivery groups.

### sfdc.commerce.cart.connect.api.output.DeliveryGroupCollectionRepresentation

Collection of delivery groups for a Commerce store checkout.

*   `count` (_integer_) The number of delivery group items returned on the current page.
*   `currentPageToken` (_string_) The token identifying the current page of delivery group items.
*   `currentPageUrl` (_string_) The URL to the current page of delivery group items.
*   `errors` (_array of sfdc.commerce.common.connect.api.output.CheckoutErrorRepresentation_) The list of any errors.
*   `id` (_string (Id)_) The ID for the delivery group.
*   `items` (_array of sfdc.commerce.cart.connect.api.output.DeliveryGroupRepresentation_) The list of delivery groups.
*   `nextPageToken` (_string_) The token identifying the next page of delivery group items.
*   `nextPageUrl` (_string_) The URL to the next page of delivery group items.
*   `previousPageToken` (_string_) The token identifying the previous page of delivery group items.
*   `previousPageUrl` (_string_) The URL to the previous page of delivery group items.
*   `sortOrder` (_string_) The sort order for delivery groups. Valid values are CreatedDateDesc and CreatedDateAsc.
*   `total` (_integer_) The total amount for all the cart items in the delivery groups.

### sfdc.commerce.cart.connect.api.output.CartCouponCollectionRepresentation

Collection of coupons associated with the cart.

*   `cartCoupons` (_sfdc.commerce.cart.connect.api.output.CartCouponListRepresentation_)
*   `cartId` (_string (Id)_) The ID of the cart.
*   `cartStatus` (_sfdc.commerce.cart.connect.api.enums.ConnectCartStatusEnum_)
*   `ownerId` (_string (Id)_) The ID of the user who owns this cart.

### sfdc.commerce.cart.connect.api.input.CartCouponInputRepresentation

Representation of the apply coupon input.

*   `couponCode` (_string_) The coupon code to apply on Cart.
*   `customFields` (_array of object_) An array of sObjects and their associated custom fields. Standard fields are ignored. The custom fields must already be defined for the sObject. Currently, only the WebCart and WebCartAdjustmentBasis sObjects is supported. Field-level security rules configured by the web store admin in the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile.
    
    Additional properties: `any`.
    

### sfdc.commerce.cart.connect.api.input.CreateQuoteFromCartInputRepresentation

Representation for creating a quote from a cart.

*   `comments` (_string_) Optional. The comments submitted by the buyer when requesting a quote.  
    Example: `Provide bulk pricing for orders of 100+ units.`.
*   `additionalFields` (_object_) Map of standard and custom Quote fields, such as expiration date and buyer email.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "ExpirationDate": "2024-12-31",
      "BuyerEmail__c": "buyer@company.com"
    }
    ```
    
*   `deleteCart` (_boolean_) Indicate whether to delete the cart (`true`) or not (`false`) after the quote is created.  
    Example: `false`.

### sfdc.commerce.cart.connect.api.output.CreateQuoteFromCartOutputRepresentation

Output representation for quote created from cart.

*   `quoteId` (_string (Id)_, nullable) The ID of the quote created from the cart. The newly created quote is in Draft status.
*   `errors` (_array of sfdc.commerce.cart.connect.api.output.ErrorOutputRepresentation_) List of errors encountered during quote creation. Returns an empty array on success.

### sfdc.commerce.cart.connect.api.input.CreateCartFromQuoteInputRepresentation

Representation for creating a cart from a quote.

*   `operationType` (_string_)
    
    The operation type for creating a cart from a quote. Valid values:
    
    *   CONVERT\_TO\_CART—Create a cart from a quote only when its status is `Approved` or `Accepted`. When the user completes checkout by converting the quote to a cart, the API sets the `QuoteId` field on the [Order](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_order.htm) using the quote ID.
        
    *   DUPLICATE\_TO\_CART—Duplicate the quote to a cart.
        
    
      
    Allowed values: `CONVERT_TO_CART`, `DUPLICATE_TO_CART`.

### sfdc.commerce.cart.connect.api.output.CartFromQuoteOutputRepresentation

Output representation for cart created from quote.

*   `cartId` (_string (Id)_, nullable) The ID of the cart created from the quote.
*   `errors` (_array of sfdc.commerce.cart.connect.api.output.ErrorOutputRepresentation_) List of errors encountered during cart creation. Returns an empty array on success.

### sfdc.commerce.common.connect.api.input.CartShippingAddressInputRepresentation

Details of the shipping address input request.

*   `city` (_string_) The shipping address city.
*   `companyName` (_string_) The shipping address company name.
*   `country` (_string_) The shipping address country.
*   `firstName` (_string_) The shipping address first name.
*   `lastName` (_string_) The shipping address last name.
*   `name` (_string_) The name of the contact.
*   `id` (_string_) The ID of the shipping address.
*   `postalCode` (_string_) The zip code or postal code for the shipping address.
*   `region` (_string_) The shipping address state.
*   `shipToPhoneNumber` (_string_) The shipping address phone number.
*   `street` (_string_) The shipping address street.

### sfdc.commerce.cart.connect.api.output.CommerceResultRepresentationBase

Abstract representation class for a request result.

*   `message` (_string_) The message related to the request.
*   `status` (_sfdc.commerce.cart.connect.api.enums.ConnectCartAsyncOperationStatusEnum_)

### sfdc.commerce.cart.connect.api.output.CartItemResultRepresentation

Cart item result.

*   `cartItem` (_sfdc.commerce.cart.connect.api.output.AbstractCartItemRepresentation_)
*   `message` (_string_) The message when the request isn’t successful.
*   `status` (_string_) The status for the request.

### sfdc.commerce.cart.connect.api.output.CartProductSummaryRepresentation

Product summary for a cart item.

*   `fields` (_object_) The map of product fields and values.
    
    Additional properties: `string`.
    
*   `name` (_string_) The name of the product.
*   `productId` (_string (Id)_) The ID of the product.
*   `productClass` (_string_) The class of the Product.  
    Allowed values: `Simple`, `Variation`, `VariationParent`, `Bundle`, `Set`.
*   `productUrlName` (_string_) The friendly URL name for the product, used for SEO purposes.
*   `productSubscriptionInformation` (_any_) Reserved for future use.
*   `purchaseQuantityRule` (_commerce.catalog.connect.api.output.PurchaseQuantityRuleRepresentation_)
*   `sku` (_string_) The SKU of the product.
*   `thumbnailImage` (_commerce.catalog.connect.api.output.ProductMediaRepresentation_)
*   `variationAttributes` (_object_) The variation attributes associated to this product
    
    Additional properties: `sfdc.commerce.cart.connect.api.output.CartProductAttributeRepresentation`.
    
*   `dynamicAttributes` (_object_) The dynamic attributes associated with this product.
    
    Additional properties: `sfdc.commerce.common.connect.api.output.CommerceProductDynamicAttributeRepresentation`.
    

### sfdc.commerce.cart.connect.api.output.CartInventoryItemReservationOutputRepresentation

Inventory item reservation.

*   `errorCode` (_string_) The error code for this reservation item.
*   `errorMessage` (_string_) The error message for this reservation item.
*   `id` (_string_) The ID for this reservation item.
*   `itemReservationSourceId` (_string_) The item reservation source ID for this reservation item.
*   `productId` (_string_) The product ID for this reservation item.
*   `quantity` (_number (double)_) The quantity for this reservation item.
*   `reservedAtLocationId` (_string_) The reserved at location or group ID for this reservation item.

### sfdc.commerce.cart.connect.api.enums.ConnectCartAsyncOperationStatusEnum

An asynchronous processing status of the cart, if asynchronous processing is enabled for the store.

Type: `string`.

Allowed values: `Completed`, `Errored`, `Processing`.

### sfdc.commerce.cart.connect.api.output.CartMessagesSummaryRepresentation

Messages summary for the item.

*   `errorCount` (_integer_) In the Cart Item Result, the count of messages with the Error severity level.
*   `hasErrors` (_boolean_) Indicates whether there are messages related to the object (true) or not (false).
*   `limitedMessages` (_array of sfdc.commerce.cart.connect.api.output.CartMessageRepresentation_) In the Cart Item Result, a limited list of messages related to the cart item. In the Cart Summary, each message can be related to the cart or to another cart-related object, and each message supports multiple languages.
*   `relatedEntityId` (_string (Id)_) In the Cart Item Result, the ID of the related cart item. In the Cart Summary, each message can be related to the cart or to another cart-related object.
*   `totalLineItemsWithErrors` (_integer_) In the Cart Item Result, either null if the cart item has no errors or 1 if the cart item has errors. In the Cart Summary, the total number of product line items that contain errors.

### sfdc.commerce.cart.connect.api.enums.ConnectCartStatusEnum

The status of a cart.

Type: `string`.

Allowed values: `Active—Cart is created and available for modifications, like adding or removing products or promotions.`, `Checkout—Cart is in checkout. If the customer modifies the cart, the current checkout session is canceled.`, `Closed—Checkout is complete and an order was created. The cart can't be modified.`, `PendingClosed—Cart is marked to be closed, but the request isn't completed yet. The cart can’t be modified.`, `PendingDelete—Cart is marked for delete, but the request isn't completed yet. The cart can’t be modified.`, `Processing—Cart is processing. For example, taxes are being calculated. The cart can’t be modified.`.

### sfdc.commerce.cart.connect.api.enums.ConnectCartTaxTypeEnum

Tax type of the cart.

Type: `string`.

Allowed values: `Automatic—Automatic taxation policy.`, `Gross—Gross taxation policy.`, `Net—Net taxation policy.`.

### sfdc.commerce.cart.connect.api.enums.ConnectCartTypeEnum

The type of cart. If unspecified, defaults to Cart.

Type: `string`.

Allowed values: `Cart—Cart created by a customer.`, `PayNowReadOnly—Clone of a Template cart that the customer can check out with using the Pay Now feature.`, `ReadOnly—Cart created is read-only.`, `Template—Cart created by an internal user.`.

### sfdc.commerce.cart.connect.api.output.AbstractCartItemRepresentation

The abstract representation class for cart item

*   `billingFrequency` (_sfdc.commerce.cart.connect.api.enums.ConnectBillingFrequencyEnum_)
*   `cartDeliveryGroupId` (_string (Id)_) The ID of the cart delivery group.
*   `cartId` (_string (Id)_) The ID of the cart.
*   `cartItemId` (_string (Id)_) The ID of the item. If asynchronous cart processing is enabled, this value returns null for POST requests.
*   `childProductCount` (_integer_) The number of child products in the cart that are associated with the item. A cart item can have child products if the productClass of the item is Bundle. For nested bundles, which include a child product that's also a bundle, childProductCount includes all child products.
*   `customFields` (_array of object_) An array of sObjects and viewable custom fields for the sObjects. Standard fields are ignored. Currently, only the CartItem sObject is supported. Field-level security rules from the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile.
    
    Additional properties: `any`.
    
*   `messagesSummary` (_sfdc.commerce.cart.connect.api.output.CartMessagesSummaryRepresentation_)
*   `name` (_string_) The name of the item.
*   `parentCartItemId` (_string (Id)_) The ID of the item’s parent cart item. The value is empty if the item is a top-level cart item.
*   `productDetails` (_sfdc.commerce.cart.connect.api.output.CartProductSummaryRepresentation_)
*   `productId` (_string (Id)_) The ID of the product for this cart item.
*   `productSellingModelId` (_string_) The ID of the product selling model associated with Product2.
*   `promotionDisplayMessage` (_string_) The display name for the bonus product only.
*   `quantity` (_string_) The quantity of the cart item.
*   `sellingModelType` (_commerce.catalog.connect.api.enumeration.ConnectSellingModelTypeEnum_)
*   `subscriptionTerm` (_integer_) The total number of terms in the subscription period.
*   `type` (_sfdc.commerce.cart.connect.api.enums.ConnectCartItemTypeEnum_)
*   `subType` (_sfdc.commerce.cart.connect.api.enums.ConnectCartItemSubTypeEnum_)
*   `cartData` (_sfdc.commerce.cart.connect.api.output.CartItemCollectionRepresentation_)
*   `IsShippingChargeNotApplicable` (_boolean_) Indicates whether to waive shipping charges (true) or not (false). When set to true, the cart item is classified as a digital good; otherwise, it is treated as a physical good.  
    Default: `false`. Example: `false`.

### commerce.catalog.connect.api.enumeration.ConnectProductClassEnum

Specifies the class of product.

Type: `string`.

Allowed values: `Simple`, `Variation`, `VariationParent`, `Bundle`, `Set`.

### sfdc.commerce.cart.connect.api.input.CartItemMoveInputRepresentation

Details of cart items to be moved into delivery groups.

*   `sourceCartItemId` (_string_) The ID of the item in the source cart.
*   `targetDeliveryGroups` (_array of sfdc.commerce.cart.connect.api.input.TargetDeliveryGroupInputRepresentation_) The target delivery groups for moving the cart items.

### sfdc.commerce.cart.connect.api.output.CartItemMoveRepresentation

Details for cart items moved into delivery groups.

*   `error` (_sfdc.commerce.common.connect.api.output.CheckoutErrorRepresentation_)
*   `sourceCartItemId` (_string_) The ID of the source cart item.
*   `targetCartItemId` (_array of string_) An arrary of IDs of cart item in the target delivery group.

### sfdc.commerce.cart.connect.api.output.CartPromotionListRepresentation

Collection of promotions for a cart.

*   `promotions` (_array of sfdc.commerce.cart.connect.api.output.CartPromotionOutputRepresentation_) The promotion for a cart.

### sfdc.commerce.cart.connect.api.output.DeliveryMethodRepresentation

Details of the delivery method for a Commerce store checkout.

*   `adjustedShippingFee` (_string_) The shipping fee, including totalAdjustmentAmount, for the delivery.
*   `carrier` (_string_) The carrier for the delivery.
*   `classOfService` (_string_) The class of service for the delivery.
*   `currencyIsoCode` (_string_) The three-letter ISO 4217 currency code associated with the delivery.
*   `earliestEstimatedDeliveryTime` (_string (date)_) The earliest estimated delivery date and time for the delivery in ISO 8601 format. Determined by the time at checkout, plus processTime, plus transitTimeMin.
*   `id` (_string (Id)_) The ID of the delivery method.
*   `latestEstimatedDeliveryTime` (_string (date)_) The latest estimated delivery date and time for the delivery in ISO 8601 format. Determined by the time at checkout, plus processTime, plus transitTimeMax.
*   `name` (_string_) The name of the delivery method.
*   `processTime` (_integer_) The merchant-specified process time for the delivery. Process time includes the time between when an order is placed and when the shipment is given to the shipping carrier.
*   `processTimeUnit` (_sfdc.commerce.shipping.connect.api.common.ConnectShippingTimeUnitEnum_) The unit of time used to define processTime.
*   `shippingFee` (_string_) The shipping fee for the delivery.
*   `totalAdjustmentAmount` (_string_) The adjustment amount of a promotion applicable to the delivery method.
*   `transitTimeMax` (_integer_) The maximum estimate of transit time for the delivery. Transit time includes the time between when a shipping carrier receives a shipment and when the shipment arrives at the delivery address.
*   `transitTimeMin` (_integer_) The minimum estimate of transit time for the delivery. Transit time includes the time between when a shipping carrier receives a shipment and when the shipment arrives at the delivery address.
*   `transitTimeUnit` (_sfdc.commerce.shipping.connect.api.common.ConnectShippingTimeUnitEnum_) The unit of time used to define transit​TimeMax and transit​TimeMin.

### sfdc.commerce.common.connect.api.output.CheckoutAddressV2Representation

Checkout Address Representation

*   `city` (_string_) City
*   `companyName` (_string_) CompanyName
*   `country` (_string_) Country
*   `firstName` (_string_) FirstName
*   `lastName` (_string_) LastName
*   `name` (_string_) Name
*   `id` (_string_) Id
*   `postalCode` (_string_) Postal Code
*   `region` (_string_) Region
*   `shipToPhoneNumber` (_string_) Shipping Phone Number
*   `street` (_string_) Street

### sfdc.commerce.common.connect.api.output.CheckoutErrorRepresentation

Checkout Error Representation

*   `type` (_string_) The type of error.
*   `title` (_string_) The brief summary of the error.
*   `detail` (_string_) The detailed information about the error.
*   `instance` (_string_) An URI reference that identifies the specific occurrence of the problem.
*   `invalidParameters` (_array of sfdc.commerce.common.connect.api.output.InvalidParameterRepresentation_) The list of invalid parameters.

### sfdc.commerce.common.connect.api.input.CheckoutAddressInputV2Representation

Details of the checkout address input request.

*   `city` (_string_) The address city.
*   `companyName` (_string_) The company name of the contact.
*   `country` (_string_) The ISO code of the address country. Must match one of the valid ISO codes defined within the org’s State-Country picklist.
*   `firstName` (_string_) The first name of the contact.
*   `lastName` (_string_) The last name of the contact.
*   `name` (_string_) The name of the contact.
*   `id` (_string_) The ID of the contact.
*   `postalCode` (_string_) The zip code or postal code for the address.
*   `region` (_string_) The ISO code of the address region. Must match one of the valid ISO codes defined within the org’s State-Country picklist.
*   `shipToPhoneNumber` (_string_) The phone number of the contact. Don't include a value for this field when submitting an address to the payment API. All default payment components strip phone numbers from the address before submitting to the payment API.
*   `street` (_string_) The address street.

### sfdc.commerce.cart.connect.api.input.CartItemPromotionInputRepresentation

Cart item promotion input.

*   `cartItemId` (_string_) Required. The ID of the item associated with the cart.

### sfdc.commerce.cart.connect.api.output.CartItemBasicResultRepresentation

A representation of the result of a Cart API request. It includes basic cart item information, the status code for the request, and a message if the request isn't successful.

*   `cartItem` (_sfdc.commerce.cart.connect.api.output.CartItemBasicRepresentation_)
*   `message` (_string_) The error message when the request isn't successful.
*   `status` (_string_) The status for the request.

### sfdc.commerce.cart.connect.api.input.ItemArrangeInputRepresentation

Instructions to arrange a cart item into a delivery group.

*   `cartItemId` (_string_) The ID of the cart item.
*   `deliveryAddress` (_sfdc.commerce.common.connect.api.input.CheckoutAddressInputV2Representation_)
*   `deliveryAddressId` (_string_) The ID of the contact pint address used to set the delivery address.
*   `deliveryGroupId` (_string_) The ID of the delivery group.
*   `deliveryGroupName` (_string_) The name of the delivery group.
*   `productId` (_string_) The ID of the product to create a new cart item for.
*   `quantity` (_string_) The quantity of the cart item.

### sfdc.commerce.cart.connect.api.output.CartCouponListRepresentation

List of coupons associated with a cart.

*   `coupons` (_array of sfdc.commerce.cart.connect.api.output.CartCouponRepresentation_) List of coupons associated with a cart

### commerce.catalog.connect.api.output.PurchaseQuantityRuleRepresentation

Rule that restricts the quantity of a product that can be purchased.

*   `maximum` (_string_) The maximum quantity that can be purchased.
*   `minimum` (_string_) The minimum quantity that can be purchased.
*   `increment` (_string_) The increment value of the quantity that can be purchased.

### commerce.catalog.connect.api.output.ProductMediaRepresentation

Media associated with a product.

*   `alternateText` (_string_) An alternative text for the product media.
*   `contentVersionId` (_string_) The ID of the latest published content version if the media is stored as a ContentDocument. If the image is a customer-provided external URL, the value is null. Not supported in enhanced CMS workspaces.
*   `id` (_string_) The ID of the product image.
*   `mediaType` (_commerce.catalog.connect.api.enumeration.ConnectProductMediaTypeEnum_) The type of the product media.
*   `sortOrder` (_integer_) The sort order of a media item within a media group.
*   `thumbnailUrl` (_string_) The URL of the thumbnail for product media. If a value exists, it should be used for the thumbnail whether the image is natively uploaded or hosted externally. Not supported in enhanced CMS workspaces.
*   `title` (_string_) The title of the product media.
*   `url` (_string_) The URL of the product media.

### sfdc.commerce.cart.connect.api.output.CartProductAttributeRepresentation

Product attribute for a cart item.

*   `label` (_string_) The label or display name of the attribute.
*   `sequence` (_integer_) The sequence of the attribute within the attribute set.
*   `value` (_string_) The display value of the attribute.

### sfdc.commerce.common.connect.api.output.CommerceProductDynamicAttributeRepresentation

Represents the dynamic product attributes.

*   `name` (_string_) The name of attribute.
*   `displayValue` (_string_) The display value of attribute.
*   `value` (_string_) The value of attribute.
*   `type` (_string_) The type of the attribute value.
*   `unitOfMeasure` (_sfdc.commerce.common.connect.api.output.UnitOfMeasureRepresentation_)

### sfdc.commerce.cart.connect.api.output.CartMessageRepresentation

Cart message.

*   `message` (_string_) Cart message.
*   `messageId` (_string (Id)_) ID of the object supplying the message.
*   `relatedEntityId` (_string (Id)_) ID of the object, for example, cart, cart item, or cart tax, associated with the message.
*   `severity` (_sfdc.commerce.cart.connect.api.enums.ConnectCartMessageSeverityEnum_)
*   `type` (_string_) Type of message. Standard values include Inventory, Taxes, Pricing, Shipping, Entitlement, SystemError, and Other.
*   `visible` (_boolean_) Indicates whether the message is visible (true) or dismissed (false).

### sfdc.commerce.cart.connect.api.enums.ConnectBillingFrequencyEnum

Specifies the billing frequency.

Type: `string`.

Allowed values: `Annual`, `Monthly`.

### commerce.catalog.connect.api.enumeration.ConnectSellingModelTypeEnum

Indicates the Selling Model Type enum values.

Type: `string`.

Allowed values: `OneTime`, `TermDefined`, `Evergreen`.

### sfdc.commerce.cart.connect.api.enums.ConnectCartItemTypeEnum

Type of item in a cart. Value is Product. This field is required when when adding an item to a cart (POST). This fiels isn't supported when updating an item in a cart (PATCH).

Type: `string`.

Allowed values: `DeliveryCharge`, `Product`.

### sfdc.commerce.cart.connect.api.enums.ConnectCartItemSubTypeEnum

The sub type of cart item.

Type: `string`.

Allowed values: `Bonus`, `Gift`.

### sfdc.commerce.cart.connect.api.input.TargetDeliveryGroupInputRepresentation

Target delivery groups for moving the cart items.

*   `deliveryGroupId` (_string_) The ID of the target delivery group.
*   `quantity` (_number (double)_) The quantity of the cart item.

### sfdc.commerce.cart.connect.api.output.CartPromotionOutputRepresentation

Promotion for a cart.

*   `adjustmentAmount` (_string_) The adjustment amount of the promotion.
*   `couponCode` (_string_) The coupon code for a promotion. A coupon code is available only for manual promotions, not for automatic promotions.
*   `currencyIsoCode` (_string_) The three-letter ISO 4217 currency code of the cart.
*   `displayName` (_string_) The localized display name of the promotion.
*   `promotionId` (_string (Id)_) The ID of the promotion.
*   `targetType` (_sfdc.commerce.cart.connect.api.enums.ConnectCartTargetTypeEnum_)
*   `termsAndConditions` (_string_) The localized terms and conditions for the promotion.

### sfdc.commerce.shipping.connect.api.common.ConnectShippingTimeUnitEnum

The unit of time used to define processTime or transit​TimeUnit.

Type: `string`.

Allowed values: `Days`, `Hours`, `Weeks`.

### sfdc.commerce.common.connect.api.output.InvalidParameterRepresentation

List of invalid parameters.

*   `name` (_string_) The name of the invalid parameter.
*   `detail` (_string_) The detailed message about the invalid parameter.
*   `value` (_string_) The value of the invalid parameter.

### sfdc.commerce.cart.connect.api.output.CartItemBasicRepresentation

A basic cart item.

*   `cartItemId` (_string (Id)_) The ID of the cart item.
*   `name` (_string_) The name of the cart item. description.
*   `productId` (_string (Id)_) The ID of the product for this cart item.
*   `quantity` (_string_) The quantity of the cart item.
*   `type` (_sfdc.commerce.cart.connect.api.enums.ConnectCartItemTypeEnum_)

### sfdc.commerce.cart.connect.api.output.CartCouponRepresentation

Details of the cart coupon.

*   `cartCouponId` (_string (Id)_) The ID for the cart coupon code
*   `couponCode` (_string_) TThe coupon code a buyer can use to manually apply a promotion to the cart.
*   `customFields` (_array of object_) An array of sObjects and their associated custom fields. Standard fields are ignored. The custom fields must already be defined for the sObject. Currently, only the WebCart and WebCartAdjustmentBasis sObjects is supported. Field-level security rules configured by the web store admin in the shopper profile are applied to the custom fields. The rules are applied for registered shoppers and for the guest shopper profile.
    
    Additional properties: `any`.
    

### commerce.catalog.connect.api.enumeration.ConnectProductMediaTypeEnum

The type of product media.

Type: `string`.

Allowed values: `Document`, `Image`, `Video`.

### sfdc.commerce.common.connect.api.output.UnitOfMeasureRepresentation

Represents the unit of measure for the attribute.

*   `unitCode` (_string_) The code for the unit of measure.
*   `scale` (_string_) The scale for the unit of measure.
*   `roundingMethod` (_string_) The rounding method for the unit of measure.

### sfdc.commerce.cart.connect.api.enums.ConnectCartMessageSeverityEnum

The severity of cart message.

Type: `string`.

Allowed values: `Error`, `Info`, `Warning`.

### sfdc.commerce.cart.connect.api.enums.ConnectCartTargetTypeEnum

The promotion target type.

Type: `string`.

Allowed values: `Cart—Promotion targets a cart.`, `Item—Promotion targets an item in a cart.`.

### sfdc.commerce.cart.connect.api.output.CartItemWithoutPriceRepresentation

A cart item without pricing information.

Includes all fields of `sfdc.commerce.cart.connect.api.output.AbstractCartItemRepresentation`.

### sfdc.commerce.cart.connect.api.input.CartItemInputList

Wraps a list of CartItemIds to get the associated promotions.

*   `items` (_array of sfdc.commerce.cart.connect.api.input.CartItemPromotionInputRepresentation_) The list of CartItemIds to get the associated promotions.

### sfdc.commerce.cart.connect.api.input.CustomFieldsListInputRepresentation

ConnectSObject list input representation wrapper for custom fields.

### commerce.catalog.connect.api.output.ProductSellingModelRepresentation

Product selling model with subscription term rules.

*   `id` (_string_) ID of the Product Selling Model.
*   `name` (_string_) Name of the Product Selling Model.
*   `sellingModelType` (_commerce.catalog.connect.api.enumeration.ConnectSellingModelTypeEnum_)
*   `pricingTerm` (_integer_) Pricing Term of the Product Selling Model.
*   `pricingTermUnit` (_commerce.catalog.connect.api.enumeration.ConnectPricingTermUnitEnum_) Pricing Term Unit of the Product Selling Model.
*   `subscriptionTermRule` (_commerce.catalog.connect.api.output.SubscriptionTermRuleRepresentation_) Represents a rule that restricts the subscription term of a subscription product that may be subscribed to.
*   `displayName` (_string_) Name of the Product Selling Model Option.
*   `description` (_string_) Description of the Product Selling Model Option.

### commerce.catalog.connect.api.enumeration.ConnectPricingTermUnitEnum

Indicates the Pricing Term Unit enum values.

Type: `string`.

Allowed values: `Months`, `Annual`.

### commerce.catalog.connect.api.output.SubscriptionTermRuleRepresentation

Represents a rule that restricts the subscription term of a subscription product that may be subscribed to.

*   `maximum` (_integer_) Maximum subscription term that can be subscribed to.
*   `minimum` (_integer_) Minimum subscription term that can be subscribed to.
*   `increment` (_integer_) Indicates the number of pricing term units that can be used to increase the Subscription Term.

<!-- document id=f6d0dbd90d9c6c2e8ea75b4c5911556f7cab0f30ef8e5595732fe88ea6191fca url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-checkout-apis.md -->

# Salesforce Commerce Checkout API

Use the Commerce Checkout APIs to streamline the commerce store checkout process, providing customers with a convenient and secure shopping experience while enabling merchants to efficiently manage orders and payments. Add checkout functionality to your B2B or B2C store. Set up payment, shipping, and tax calculation services.

The initial step in the Commerce Store Checkout process is to start checkout for users. This involves gathering information such as cart items, customer details, shipping information, and payment preferences.

When initiating a Checkout API update request, typically prompted by users adding or modifying shipping addresses during checkout, the process extends to integrations like shipping and tax services. For registered users, saved information, including shipping addresses and saved payment methods can be returned at the start of checkout. Additionally, if a shipping address is saved, shipping methods and taxes are calculated at the beginning of the checkout process. Shipping integrations are engaged to retrieve delivery methods and rates, sourced either from third-party services or Salesforce's native shipping solutions. Similarly, tax calculations are executed to ensure accurate rates depending on the shipping location. These updates are subsequently displayed in the checkout interface, presenting users with delivery options, shipping rates, and relevant taxes. You can either use a third-party tax service or Salesforce's native tax via Stripe Tax.

When users proceed to payment for a Commerce store checkout, the Checkout Payments API is triggered. This API manages payment methods, either configured by merchants or utilizing Salesforce's native payments with Stripe as the gateway. It guarantees secure payment transactions for finalized orders, presenting customers with a range of payment options supported by the commerce platform.

Tokenization of Payment for a Commerce Store Checkout involves encrypting and storing payment information to enhance transaction security. For the purpose of user authorization and transaction processing, this procedure enables the token handshake and makes it easier to communicate with other Salesforce Payment APIs.

Finally, users can place an order for a Commerce Store checkout. In this step, the order is validated, payment is processed, and an order summary is generated for both the user and the merchant. Users choose a payment method to complete their purchase, and this API validates the cart, converting it into an order and generating an order summary.

## Use Case

Let's consider a basic scenario for building the Commerce checkout management flow using Checkout APIs. This example covers just a few Checkout APIs and doesn't include the entire APIs functionality.

![Diagram of the checkout APIs workflow for B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/checkout_apis_workflow.png '{"class": "image-lg", "title": "Checkout Workflow"}')

In a typical shopping journey, users add products to their cart from the Product Listing Page (PLP) or the Product Details Page (PDP). They review their cart items using a GET call on the [Cart Item API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm).

Once they're ready, they start the checkout process with a POST request to the [Webstore Checkouts API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm), receiving user information like contact details, shipping address, and delivery options.

For any updates to contact or shipping details, users can send a PATCH request to the [Webstore Checkout API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm). Subsequently, the Checkout API triggers integrations for shipping and taxes, providing rates and delivery options.

After selecting a delivery method and reviewing charges, users can proceed to payment by making a POST request to the [Webstore Checkout Payments API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm). This API triggers Salesforce's native payments with Stripe as the payment gateway. Then, make a POST request to the [Webstore Payments Token API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_token.htm) for authorization and enhanced security by encrypting payment details.

Finally, users place their order by making a POST request to the [Webstore Checkout Orders API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order.htm), which validates user info, processes payments, and creates order summaries for both users and merchants.

**note:** The checkout API used depends on your webstore configuration. Webstores that don't use the Streamlined Place Order feature use the Webstore Checkout Orders API. Webstores that use the Streamlined Place Order feature use the [Commerce Webstore Checkout, Place Order Action](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm) API instead.

## Resources

Here’s a list of Commerce Checkout resources:

| Resource                                                                                                                                                                                                                          | Supported HTTP Methods | Description                                                                                               |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------- |
| [`/commerce/webstores/{webstoreId}/​checkouts`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm)                                    | POST, PUT              | Start a checkout process for a Commerce store. We recommend using PUT over POST to initiate the checkout. |
| [`/commerce/webstores/{webstoreId}/​checkouts/{activeOrCheckoutId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                              | GET, DELETE, PATCH     | Get, delete, or update a Commerce store checkout.                                                         |
| [`/commerce/webstores/{webstoreId}/​checkouts/{activeOrCheckoutId}/payments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm)            | POST                   | Payment for a Commerce store checkout.                                                                    |
| [`/commerce/webstores/{webstoreId}/​payments/token`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_token.htm)                                                  | POST                   | Tokenize a payment for a Commerce store checkout.                                                         |
| [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}/orders`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order.htm)            | POST                   | Place an order for a Commerce store checkout.                                                             |
| [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}/orders/actions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order_v2.htm) | POST                   | Enhanced version of the Place Order Actions API for the Commerce store checkout process.                  |
| [`/commerce/webstores/webstoreId/​checkouts/activeOrCheckoutId/coupons`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupons.htm)                            | POST                   | Apply a coupon code to a checkout.                                                                        |
| [`/commerce/webstores/webstoreId/​checkouts/activeOrCheckoutId/coupons/cartCouponId`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupon_delete.htm)         | DELETE                 | Delete a coupon from a checkout.                                                                          |

**See Also**

- [_Salesforce B2B Commerce Developer Guide_: B2B Commerce Checkout Process with Commerce APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-get-started.md)
- [_Salesforce B2B Commerce Developer Guide_: Cart and Checkout Features](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-cart-checkout.html)
- [_Salesforce B2B Commerce_: Commerce Checkout](https://help.salesforce.com/s/articleView?id=commerce.comm_checkout_container.htm)

<!-- document id=01048f4768b3c325496d2ccfbd7a9da837ed0edb896052d715e03c94ad0e0366 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-github-repo-access.md -->

# Salesforce Commerce Cloud GitHub Repositories and Access

Commerce Cloud maintains a GitHub organization to share code and artifacts with Commerce Cloud customers and partners: https://github.com/SalesforceCommerceCloud

The org is the primary place where code is shared for using B2C Commerce and includes public and private repositories.

Public repos are available to anyone that browses GitHub. This includes open source repos like [Storefront Next](https://github.com/SalesforceCommerceCloud/storefront-next-template), [PWA Kit](https://github.com/SalesforceCommerceCloud/pwa-kit), [Commerce API SDK](https://github.com/SalesforceCommerceCloud/commerce-sdk), and the [SFCC-CI](https://github.com/SalesforceCommerceCloud/sfcc-ci) command-line tool.

Private repos must be accessed by a GitHub user login that has been authenticated with Commerce Cloud. These repos contain code that is licensed, based on your Commerce Cloud license, and covered under your NDA. They aren't open-source. This includes closed source repos like [Storefront Reference Architecture](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture).

**important:** If you access a private repo and aren't logged into GitHub with a Commerce Cloud authenticated account, you receive a 404 error from GitHub as if the repository doesn’t exist at all!

## Accessing Private GitHub Repos

To access private repos associate your GitHub account with Commerce Cloud using Account Manager:

1.  If you don't have a GitHub user account, create one from the [GitHub Sign Up](https://github.com/join) page.

    **note:** Your GitHub account doesn't need to be related to any Commerce Cloud or Salesforce account you already have. It can be something different.

2.  Enable two-factor authentication (2FA) for your GitHub account.

    To maintain trust, Salesforce requires that anyone accessing the GitHub repositories has 2FA set up for their account. Follow the directions for [Configuring Two-Factor Authentication](https://docs.github.com/en/github/authenticating-to-github/configuring-two-factor-authentication) on GitHub, and complete that process.

    **note:** This is separate from Commerce Cloud or Salesforce two-factor authentication. Use any mechanism for 2FA for your GitHub account.

3.  With a valid and logged in GitHub user account with 2FA configured, associate that account with Commerce Cloud opening the [Salesforce Commerce Cloud Single Sign On](https://github.com/orgs/SalesforceCommerceCloud/sso) page. This connects your GitHub user account to your Account Manager user account.

With the process complete, your GitHub account is allowed access to Salesforce Commerce Cloud private repositories. You’re asked to authenticate with your Account Manager credentials when you attempt to access private repositories.

## GitHub Inactivity and User Maintenance

GitHub users who have been [inactive](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/managing-dormant-users) for 90 days are [removed](https://docs.github.com/en/organizations/managing-membership-in-your-organization/removing-a-member-from-your-organization) from the org.

**important:** Removed users lose access to private forks of the org's private repos.

Users who are removed as a result of this inactivity receive an automated email from GitHub, and can rejoin by authenticating with their Account Manager credentials in the opening the [Salesforce Commerce Cloud Single Sign On](https://github.com/orgs/SalesforceCommerceCloud/sso) page.

<!-- document id=4973c3b232a18717e40b4dcd6cea434e30ced22f542ace9bd4df4d2e615cf57d url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-import-apis.md -->

# Salesforce Commerce Import API

Import product and category data to a store with a `.csv` file by using the Salesforce Commerce Import APIs. You can import data asynchronously.

## Import APIs for Products

For product data, there are two Commerce Import Product Job resources: one to create a product import job, and another to manage a job. Use [Commerce Import Product Job, Create](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_product_job_create.htm) to globally update or add products and related entities from a specified product import file. Use the [manage resource](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_category_job_manage.htm) to get the status of a job with a GET request or cancel a job with a PATCH request. For the PATCH request, specify the `status` property as `Aborted` in the [Product Import Cancel Input](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_product_import_cancel_input.htm) request body.

**note:** A resource was previously introduced for synchronous product imports, but it was superseded by asynchronous product imports, and we plan to remove it in API version 63.0. Use [Commerce Import Product Job, Create](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_product_job_create.htm) to import products instead.

When you construct a product import .csv file, specify column headings that correspond to product, category, and price book information. Each row in the file represents a product and its variations. See [CSV File Format for Importing Commerce Data](https://help.salesforce.com/s/articleView?id=commerce.comm_prod_import_csv.htm).

## Import APIs for Categories

The Import APIs for category data are similar to the resources for product data. To import category data asynchronously, make a POST request to the [Commerce Import Category Job, Create](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_category_job_create.htm) resource. To get the status of a category import job, make a GET request to the Commerce Import Category Job, Manage resource. To cancel a category import job, make a PATCH request to the manage resource with the `status` property specified as `Aborted` in the [Category Import Abort Input](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_category_import_abort_input.htm) request body.

When you construct a category import .csv file, specify column headings that correspond to category path, URL slug, and category description information. Each row in the file represents a category and its structure. See [CSV File Format for Importing Category Data for a Store](https://help.salesforce.com/s/articleView?id=commerce.comm_seo_category_urls.htm).

## Use Case

To understand the Import APIs, consider the steps involved in a product import. This scenario features just a few Import APIs and doesn't include the entire functionality.

First, construct a `.csv` file where column headings correspond to product, category, and price book information and each row represents a product and its variations. The column headings are case-insensitive, and the columns can be in any order. To properly encode special characters, save the `.csv` file in UTF-8 format.

Then, upload your file to [Salesforce Files](https://help.salesforce.com/s/articleView?id=experience.collab_salesforce_files_parent.htm). The upload assigns the file a content version ID, which the Import APIs use later to access the file. To get the content version ID, view the file details in the [Salesforce Files UI](https://help.salesforce.com/s/articleView?id=experience.collab_files_previewing.htm). The second-to-last part of the URL is the content version ID. If you upload the file by using the [User Files Connect API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_users_files_general.htm), the API response includes the content version ID.

Next, make a POST request to `/commerce/management/import/product/jobs`. The request body for POST, [Global Product Import Input](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_global_product_import_input.htm), has a property, `importConfiguration`, that specifies the settings and source for the import. [Import Settings](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_import_settings_input.htm) are applied to all products in the import file and can set details such as which CMS workspace or entitlement policy to associate with the products. The `importSettings` property is required if you specify media-related, price-related, or category-related column headings in your `.csv` file.

To provide the content version ID for your file, use the `importSource` property of the request body. If you’re simply testing the API functionality, you can also provide a sample `.csv` file by setting the `sampleData` property to one of the pre-defined datasets (for example, `B2BSampleData`).

```JSON
{
  "importConfiguration":{
    "importSource":{
      "contentVersionId":"069RM0000008F4FYAU"
      },
    "importSettings":{
      "category":{
        "productCatalogId":"0ZSRM00000004Fk4AI"
         },
      "media":{
        "cmsWorkspaceId":"0ZuRM0000000Fcz0AE"
         },
      "price":{
        "pricebookAliasToIdMapping":{
          "original":"01sRM000004aArJYAU",
          "sales":"01sRM000004aArIYAU",
          "wintersales":"01sRM000004aArKYAU"
        }
      },
      "entitlement":{
        "defaultEntitlementPolicyId":"1CeRM00000003o40AA"
      }
    }
  }
}
```

## Resources

| Resource                                                                                                                                                                                       | Supported HTTP Methods | Description                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| [`/commerce/management/import/​category/jobs`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_category_job_create.htm)         | POST                   | Create a job to asynchronously import category data by using a `.csv` file.                      |
| [`/commerce/management/import/​category/jobs/{jobId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_category_job_manage.htm) | GET, PATCH             | Cancel or get the status of a job to asynchronously import category data by using a `.csv` file. |
| [`/commerce/management/webstores/{webstoreId}/​product-import`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_product.htm)    | POST                   | Synchronously import products for a B2B store by using a `.csv` file.                            |
| [`/commerce/management/import/product/jobs`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_product_job_create.htm)            | POST                   | Create a job to asynchronously import product data by using a `.csv` file.                       |
| [`/commerce/management/import/product/jobs​/{jobId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_import_product_job_manage.htm)   | GET, PATCH             | Manage an asynchronous product import job. You can cancel or get the status of the job.          |

<!-- document id=2af51c76c5f7b61c7e8f306f5f6acd2117e23452f7736d7ed0bbffb0b95bd7ce url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-myprofile-apis.md -->

# Salesforce Commerce My Profile API

The Salesforce Commerce My Profile API allows you to retrieve and update buyer account details. This API works by identifying the buyer's user ID within the logged-in context to either fetch or modify their account information.

The My Profile API supports both GET and PATCH requests. Use the GET request to view buyer profile details, such as phone number, email address, first name, last name, or username.

To update profile information, such as phone number, email address, first name, or last name, make a PATCH request. When you update your email address, a verification process starts. The API sends a confirmation email to your old address. Until you verify the new email, the Profile page GET API still shows the old one. Once confirmed, the GET API displays the updated email.

## Use Case

Let's explore a basic scenario for utilizing the My Profile API's supported methods.

![Diagram of the My Profile APIs workflow for managing customer profile data in B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/myprofile_apis_workflow.png '{"class": "image-lg", "title": "Checkout Workflow"}')

First, let’s consider a scenario where a buyer wants to view their profile details, including phone number, email address, first name, last name, or user name. In this case, a GET request to the [Commerce Webstore My Profile API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_myprofile.htm) can be used to retrieve these details.

Second, if the buyer decides to update their profile information—such as phone number, email address, first name, and last name—a PATCH request to the [Commerce Webstore My Profile API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_myprofile.htm) can be used.

## Resources

Here’s a list of Commerce My Profile resources:

| Resource                                                                                                                                                                                                | Supported HTTP Methods | Description                                                                                                                                                                         | Available Version |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| [`/commerce/webstores/{webstoreId}/myprofile`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_myprofile.htm)                          | GET, PATCH             | Retrieve or update the buyer’s account details. This API works by identifying the buyer's user ID within the logged-in context to either fetch or modify their account information. | 52.0              |
| [`/commerce/webstores/{webstoreId}/myprofile/actions/initOTP`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_myprofile_initotp.htm)  | POST                   | Initiate the one-time password (OTP) via the specified method, such as SMS or Email.                                                                                                | 64.0              |
| [`/commerce/webstores/{webstoreId}/myprofile/actions/verify`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_myprofile_verifyotp.htm) | POST                   | Validate the one-time-password (OTP) provided by the buyer.                                                                                                                         | 64.0              |

<!-- document id=81bf69ff551204f2d4f526fb438672923b9e20e2bae3083249266a62fb22994b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-order-summaries-apis.md -->

# Salesforce Commerce Order Summary APIs

The Salesforce Commerce Order Summary APIs allow users to manage their order summaries for placed orders. With these APIs, they can retrieve past order summaries, view details of a specific order summary, reorder from an existing order summary, and submit asynchronous jobs to calculate adjustment aggregates for multiple order summaries.

## Order Summary API for a Registered User and Guest User

To retrieve order summaries, use the [Commerce Webstore Order Summaries](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries.htm) API. This API fetches order summaries based on a specified account ID. If an account ID isn’t provided as a query parameter, the API defaults to the user’s context and returns order summaries relevant to them. For B2B users, the API supports an account switch feature, enabling access to order summaries from multiple accounts by using the effective account ID parameter.

This API is currently utilized on the Order History page in the out-of-the-box experience, enabling users to view their order summaries. With pagination support, users can seamlessly navigate through additional results using the “Next” function. By default, order summaries are sorted in descending order by creation date, showing the most recent orders first. In Lightning Web Runtime (LWR) templates, only the most recent order summary is shown first, while Aura templates provide sorting flexibility, allowing to show either the oldest or the most recent order summary at the top of the results page.

To view the details of a specific order summary, including all associated line items and relevant order amount fields, use the [Commerce Webstore Order Summary Lookup](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_lookup.htm) API. This API provides details such as the grand total, promotion amount, and coupon amount, reflecting the total adjustments applied. It also returns item images, associated shipping addresses, and the corresponding line items for each address.

This API fetches all line items grouped by shipping addresses. The out-of-the-box solution provides UI-level pagination, but the API doesn’t support pagination for custom implementations. To exclude certain details in the API response, use query parameters like `excludeDeliveryGroups`, `excludeAdjustments`, and `excludeAdjustmentAggregates`.

Guest users can access this API by including the verification parameter in the [Order Summary Lookup Input](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_order_summary_lookup_input.htm). For guests, the order reference number in the `orderSummaryIdOrRefNumber` parameter is mandatory and accepts order reference number (for guests) and Salesforce order summary record ID (for authenticated users). Guest user verification requires a combination of email and phone numbers, with last name as an optional field. Authenticated users, however, are not required to provide verification.

For B2B users, the API supports an account switch feature, enabling access to order summaries from multiple accounts by specifying the effective account ID parameter.

To reorder from an existing order summary, use the [Commerce Webstore Order Summaries Add Order to Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_add_order_to_cart_action.htm?q=add-order-to-cart) API. This API simplifies the reorder process by adding all items from a specified order summary directly to your current cart. For example, as a store owner needing regular inventory replenishment, you can revisit a previous order summary and reorder all items with ease. If no active cart exists, the API creates a new cart and adds the items. This API supports both authenticated and guest users. However, guest users must complete a verification process by providing their last name, email address, and phone number.
To retrieve an order summary, use the [Commerce Webstore Order Summary](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary.htm) API with the order summary ID. To view delivery groups associated with an order summary, use the [Commerce Webstore Order Delivery Groups](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_delivery_groups.htm) API. For details about items in an order summary, leverage the [Commerce Webstore Order Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_items.htm) API. These APIs are designed for registered buyers and are not accessible to guest users.

To retrieve shipment information for a generated order summary, submit a GET request to the [Commerce Webstore Order Shipments](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_shipments.htm) API. To retrieve order items associated with a specific shipment, use the [Commerce Webstore Shipment Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_shipment_items.htm) API with the shipment ID. Both of these APIs are restricted to authenticated users and are not accessible to guest users.

## Order Summary API for an Administrator

To submit a job to recalculate adjustment aggregates for a list of order summary IDs, use the [Commerce Webstore Order Summaries, Adjustment Aggregates](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_adjustment_aggregates.htm) API. Order summaries include various types of adjustments, such as promotional and coupon-related adjustments. This adjustment data is added to the [OrderSummaryAdjustmentAggregates](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_order_summary_adjustment_aggregates.htm) entity. If the adjustment calculations fail for certain order summaries, their values default to null or zero. This API enables administrators to manually recalculate these adjustment values. As an asynchronous API, it allows admin users to submit a list of order summaries for calculating adjustment values.

## Use Case

Let's consider a basic scenario for building a flow using Order Summary resources. This example covers just a few resources and doesn't include the entire API functionality.

![Diagram of the order summaries API workflow for B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/order_summary_apis_workflow.png '{"class": "image-lg", "title": "Order Summaries Workflow"}')

Imagine you manage an online store, and a regular B2B customer frequently reorders the same set of supplies each month. To simplify their experience, you implement the [Commerce Webstore Order Summaries Add Order to Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_add_order_to_cart_action.htm?q=add-order-to-cart) API. With this functionality, the customer can view their past order summaries on their order history page and quickly reorder with one click. Upon reordering, the API automatically adds all items from the previous order summary to their cart, thereby saving time and effort.

## Resources

Here’s a list of Order Summary resources:

| Resource                                                                                                                                                                                                                                                                       | Supported HTTP Methods | Description                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [`/commerce/webstores/webstoreId/order-summaries/actions/lookup`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_lookup.htm)                                                                   | POST                   | Look up details about an OrderSummary for a guest shopper or a registered buyer.                                                 |
| [`/commerce/webstores/${webstoreId}/order-summaries`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries.htm)                                                                                    | GET                    | Get order summaries for registered buyers.                                                                                       |
| [`/commerce/webstores/webstoreId/order-summaries/orderSummaryId/actions/add-order-to-cart`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_add_order_to_cart_action.htm?q=add-order-to-cart) | POST                   | Use a webstore’s order summary to add an order to a cart.                                                                        |
| [`/commerce/webstores/webstoreId/order-summaries/orderSummaryId`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary.htm)                                                                          | GET                    | Get an order summary for a provided order summary ID.                                                                            |
| [`/commerce/webstores/webstoreId/order-summaries/orderSummaryId/delivery-groups`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_delivery_groups.htm)                                          | GET                    | Get order delivery groups for a provided order summary ID.                                                                       |
| [`/commerce/webstores/webstoreId/order-summaries/orderSummaryId/items`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_items.htm)                                                                      | GET                    | Get order items for a specified order summary ID.                                                                                |
| [`/commerce/webstores/webstoreId/order-summaries/orderSummaryId/shipments`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_shipments.htm)                                                              | GET                    | Get order shipments for a specified order summary ID.                                                                            |
| [`/commerce/webstores/webstoreId/shipments/shipmentId/items`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_shipment_items.htm)                                                                       | GET                    | Get shipment items for a provided shipment ID.                                                                                   |
| [`/commerce/webstores/webstoreId/order-summaries/async-actions/adjustment-aggregates`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_adjustment_aggregates.htm)                             | POST                   | Submit a job to calculate adjustment aggregates for a list of order summary IDs. This API is available only to an administrator. |

<!-- document id=481e29a03c18993911ec3c85d76ae113eea9d4543e9849c4d714f6b21993a544 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-ccs-payments-ref.md -->

Salesforce Commerce Payments API

# Salesforce Commerce Payments API

Salesforce Commerce Payments API endpoints are available under /commerce/payments.

To access these resources, your org must have one or more of these licenses:

*   B2B Commerce, or D2C Commerce
*   Commerce Cloud Growth
*   Commerce Cloud Advanced
*   Collections and Financial Recovery
*   Revenue Cloud Billing
*   Salesforce Payments
*   Salesforce Order Management
*   Salesforce Pro Suite
*   Salesforce Foundations

These APIs are unavailable for Guest Users.

**Version:** 66.0

## Servers

*   `https://{yourinstance}.salesforce.com/services/data/{version}`
    *   `version (default v66.0): v66.0, v65.0, v64.0, v63.0, v62.0`

## Operations

### POST Authorize a payment.

`POST /commerce/payments/authorizations`

Operation ID: `authorizePayment`.

#### Request body

Media type: `application/json`. Schema: `AuthorizationInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `AuthorizationOutputRepresentation`.
    

### POST Capture an authorized payment.

`POST /commerce/payments/authorizations/{authorizationId}/captures`

Operation ID: `capturePayment`.

#### Parameters

*   `authorizationId` (path, string, required) Unique ID associated with the payment authorization record.

#### Request body

Media type: `application/json`. Schema: `CaptureInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CaptureOutputRepresentation`.
    

### POST Reverse an authorized payment.

`POST /commerce/payments/authorizations/{authorizationId}/reversals`

Operation ID: `reverseAuthorization`.

#### Parameters

*   `authorizationId` (path, string, required) Unique ID associated with the payment authorization record.

#### Request body

Media type: `application/json`. Schema: `AuthReversalInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `AuthReversalOutputRepresentation`.
    

### POST Tokenize a payment method.

`POST /commerce/payments/payment-methods`

Operation ID: `tokenizePaymentMethod`.

#### Request body

Media type: `application/json`. Schema: `PaymentMethodTokenizationInputRepresentation`.

_Example: BankPaymentMethodTokenisationInput_ Tokenizes the BankPaymentMethod.

```
{
  "address": {
    "street": "415 Mission Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "bankPaymentMethod": {
    "accountId": "001RM000005WOk0YAG",
    "accountNumber": "000123456789",
    "accountHolderType": "Individual",
    "bankType": "Ach",
    "accountHolderFirstName": "John",
    "accountHolderLastName": "Doe",
    "bankCode": "110000000",
    "nickName": "John Doe",
    "accountHolderName": "John Doe",
    "email": "johndoe@test.com",
    "autoPay": true,
    "standardEntryClassCode": "WEB",
    "accountType": "Savings"
  },
  "paymentGatewayId": "0b0xx0000000001XYZ"
}
```

_Example: CardPaymentMethodTokenisationInput_ Tokenizes the card payment method.

```
{
  "address": {
    "street": "415 Mission Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "cardPaymentMethod": {
    "accountId": "001RM000005WOk0YAG",
    "cardHolderName": "John Doe",
    "autoPay": true,
    "expiryMonth": "10",
    "expiryYear": "2028",
    "startMonth": "10",
    "startYear": "2018",
    "cvv": "113",
    "cardNumber": "4242424242424242",
    "cardCategory": "CreditCard",
    "cardType": "visa",
    "nickName": "John",
    "cardHolderFirstName": "John",
    "cardHolderLastName": "Doe",
    "email": "johndoe@test.com"
  },
  "paymentGatewayId": "0b0xx0000000001XYZ"
}
```

_Example: GeneralTokenisationInput_ Tokenisation of the specified CardPaymentMethod or BankPaymentMethod (only one payment method can be used).

```
{
  "address": {},
  "bankPaymentMethod": {},
  "cardPaymentMethod": {},
  "paymentGatewayId": "paymentGatewayId"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `PaymentMethodTokenizationOutputRepresentation`.
    

### POST Create a refund for a payment.

`POST /commerce/payments/payments/{paymentId}/refunds`

Operation ID: `createPaymentRefund`.

#### Parameters

*   `paymentId` (path, string, required)

#### Request body

Media type: `application/json`. Schema: `ReferencedRefundInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `RefundServiceOutputRepresentation`.
    

### POST Confirm that the merchant is ready to capture payment of an existing pre-authorized transaction.

`POST /commerce/payments/postAuths`

Operation ID: `postAuthorize`.

#### Request body

Media type: `application/json`. Schema: `PostAuthInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `PostAuthOutputRepresentation`.
    

### POST Make a payment sale.

`POST /commerce/payments/sales`

Operation ID: `salePayment`.

#### Request body

Media type: `application/json`. Schema: `SaleInputRepresentation`.

_Example: EnhancedPaymentData_ Sale API with Enhanced Payment Data.

```
{
  "amount": "2472",
  "paymentGatewayId": "0b0PRD0000008XyAAI",
  "currencyIsoCode": "USD",
  "paymentGroup": {
    "createPaymentGroup": "true",
    "currencyIsoCode": "USD"
  },
  "paymentMethod": {
    "id": "12qPRD000002Z9kQAA"
  },
  "enhancedPaymentData": {
    "referenceId": "ORD-784512",
    "invoiceNumber": "INV-784512",
    "totalTaxAmount": "172",
    "shippingAmount": "250",
    "shipFromZip": "94105",
    "shipToZip": "10001",
    "shipToCountry": "US",
    "lineItems": [
      {
        "lineItemId": "LI-1001",
        "sku": "LTP-4500",
        "name": "Business Laptop Pro 14",
        "description": "14-inch business laptop with 16GB RAM and 512GB SSD",
        "quantity": 10,
        "taxAmount": 96,
        "unitPrice": 120,
        "uom": "EA",
        "commodityCode": "43211503",
        "discount": 100
      },
      {
        "lineItemId": "LI-1002",
        "sku": "MON-27UHD",
        "name": "27-inch 4K UHD Monitor",
        "description": "Ultra HD LED monitor with HDR support",
        "quantity": 5,
        "taxAmount": 76,
        "unitPrice": 200,
        "uom": "EA",
        "commodityCode": "43211902",
        "discount": 50
      }
    ]
  },
  "comments": "Authorization request for enterprise hardware order"
}
```

_Example: PaymentInitiationSource_ Sale API with Payment Initiation Source.

```
{
  "amount": 25,
  "paymentGatewayId": "{{pgid}}",
  "currencyIsoCode": "AUD",
  "paymentGroup": {
    "createPaymentGroup": true,
    "currencyIsoCode": "AUD"
  },
  "paymentInitiationSourceId": "1KCxx0000004CDsGAM",
  "accountId": "001SM00000GPtUqYAL",
  "paymentMethod": {
    "id": "{{pmId}}"
  },
  "comments": "Auth request."
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `SaleOutputRepresentation`.
    

## Schemas

### AuthorizationInputRepresentation

Payment authorization input consumed by the payment authorization service. service.

Includes all fields of `GatewayCallableBaseInputRepresentation`.

*   `accountId` (_string_) Required. Salesforce account that contains the payment transaction being authorized.
*   `paymentInitiationSource` (_PaymentInitiationSourceInputRepresentation_) Optional. Payment Initiation Source Input Representation for Auth Request
*   `amount` (_number (double)_) Required. Authorization amount.
*   `comments` (_string_) Optional. Comments for the payment authorization.
*   `currencyIsoCode` (_string_) Required, if multicurrency is enabled. Three-letter ISO 4217 currency code associated with the payment group record.
*   `effectiveDate` (_string_) Required. Date that the authorization will be applied to the transaction.
*   `paymentData` (_object_) Payment Data
    
    Additional properties: `string`.
    
*   `paymentGatewayId` (_string_) Required. Payment gateway that processes the authorization.
*   `paymentGroup` (_PaymentGroupInputRepresentation_)
*   `paymentMethod` (_AuthApiPaymentMethodInputRepresentation_)
*   `sourceObjects` (_array of string_) Source IDs for the sale transaction.

_Example_

```
{
  "accountId": "accountId",
  "paymentGatewayId": "paymentGatewayId",
  "amount": 0.8008281904610115,
  "comments": "comments",
  "paymentGroup": {},
  "paymentData": {
    "key": "paymentData"
  },
  "paymentMethod": {},
  "currencyIsoCode": "currencyIsoCode",
  "effectiveDate": "effectiveDate",
  "sourceObjects": [
    "sourceObjects",
    "sourceObjects"
  ]
}
```

### AuthorizationOutputRepresentation

Payment authorization output representation.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayResponse` (_AuthorizationGatewayResponseRepresentation_)
*   `paymentAuthorization` (_PaymentAuthorizationOutputRepresentation_)
*   `paymentGatewayLogs` (_array of GatewayLogOutputRepresentation_) Gateway Log list representation for Payment Authorization
*   `paymentGroup` (_PaymentGroupRepresentation_)
*   `paymentMethod` (_PaymentMethodOutputRepresentation_)
*   `isMultiCaptureSupported` (_boolean_) Indicates whether the authorization status from a payment gateway, such as Stripe, supports multiple captures (true) or not (false).

_Example_

```
{
  "paymentGatewayLogs": [
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    },
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    }
  ],
  "paymentAuthorization": {
    "accountId": "accountId",
    "amount": 0.8008281904610115,
    "requestDate": "requestDate",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id",
    "effectiveDate": "effectiveDate",
    "expirationDate": "expirationDate",
    "paymentAuthorizationNumber": "paymentAuthorizationNumber",
    "status": "status"
  },
  "gatewayResponse": {
    "gatewayAuthorizationCode": "gatewayAuthorizationCode"
  },
  "paymentGroup": {
    "sourceObjectId": "sourceObjectId",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id"
  },
  "paymentMethod": {
    "accountId": "accountId",
    "paymentMethodDetails": {
      "digitalWallet": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "alternativePaymentMethod": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "paymentMethodDetails": "paymentMethodDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodSubType": "paymentMethodSubType",
        "type": "type",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "cardPaymentMethod": {
        "autoPay": true,
        "comments": "comments",
        "cardHolderName": "cardHolderName",
        "startMonth": 5,
        "nickName": "nickName",
        "cardType": "cardType",
        "expiryMonth": 6,
        "startYear": 5,
        "cardCategory": "CreditCard",
        "cardHolderLastName": "cardHolderLastName",
        "displayCardNumber": "displayCardNumber",
        "expiryYear": 1,
        "cardLastFour": "cardLastFour",
        "accountId": "accountId",
        "cardBin": "cardBin",
        "cardTypeCategory": "AmericanExpress",
        "paymentMethodDetails": "paymentMethodDetails",
        "paymentMethodSubType": "paymentMethodSubType",
        "paymentMethodType": "Ach",
        "cardHolderFirstName": "cardHolderFirstName",
        "email": "email"
      }
    },
    "id": "id",
    "status": "status"
  },
  "error": {},
  "isMultiCaptureSupported": true
}
```

### CaptureInputRepresentation

Payment capture input consumed by payment capture service.

Includes all fields of `GatewayCallableBaseInputRepresentation`.

*   `accountId` (_string_) Optional. ID of the account that must be linked to this capture request.
*   `amount` (_number (double)_) Required. Amount that must be captured.
*   `clientContext` (_string_) Optional. Specifies the context for payment APIs. Used for a payment caller to reestablish context.
*   `comments` (_string_) Optional. Specifies comments for payment capture request.
*   `effectiveDate` (_string_) Optional. Date that the payment becomes effective.
*   `paymentAuthorizationId` (_string_) Unique ID associated with the payment authorization record.
*   `paymentGroup` (_PaymentGroupInputRepresentation_)
*   `isFinalCapture` (_boolean_) Optional. Indicates whether the current capture payment transaction is the final request (true) or not (false). Default value is false, but it also depends on the cardType associated with the payment authorization.

_Example_

```
{
  "clientContext": "clientContext",
  "accountId": "accountId",
  "amount": 0.8008281904610115,
  "comments": "comments",
  "paymentAuthorizationId": "paymentAuthorizationId",
  "paymentGroup": {},
  "effectiveDate": "effectiveDate",
  "isFinalCapture": false
}
```

### CaptureOutputRepresentation

Capture output representation.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayResponse` (_CaptureGatewayResponseRepresentation_)
*   `payment` (_PaymentOutputRepresentation_)
*   `paymentGatewayLogs` (_array of GatewayLogOutputRepresentation_) Gateway Log Collection Representation for Auth Capture
*   `paymentGroup` (_PaymentGroupRepresentation_)

_Example_

```
{
  "paymentGatewayLogs": [
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    },
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    }
  ],
  "gatewayResponse": {},
  "paymentGroup": {
    "sourceObjectId": "sourceObjectId",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id"
  },
  "payment": {
    "accountId": "accountId",
    "amount": 0.8008281904610115,
    "requestDate": "requestDate",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id",
    "effectiveDate": "effectiveDate",
    "paymentNumber": "paymentNumber",
    "status": "status"
  },
  "error": {}
}
```

### AuthReversalInputRepresentation

Authorization reversal input consumed by authorization reversal service. service.

Includes all fields of `GatewayCallableBaseInputRepresentation`.

*   `accountId` (_string_) Optional. Account for the payment authorization reversal. Must match the payment authorization's account.
*   `amount` (_number (double)_) Required. Amount of adjustment applied to the payment authorization.
*   `comments` (_string_) Optional. Users can add comments to provide additional details about a record. Maximum of 1,000 characters.
*   `effectiveDate` (_string_) Required. Date that the adjustment takes effect on the authorization.
*   `paymentAuthorizationId` (_string_) Optional. Payment authorization ID to be used if needed to fund the exchange order.

_Example_

```
{
  "accountId": "accountId",
  "amount": 0.8008281904610115,
  "comments": "comments",
  "paymentAuthorizationId": "paymentAuthorizationId",
  "effectiveDate": "effectiveDate"
}
```

### AuthReversalOutputRepresentation

Authorization reversal output representation.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayResponse` (_AuthReversalGatewayResponseRepresentation_)
*   `paymentAuthAdjustment` (_AuthAdjustmentOutputRepresentation_)
*   `paymentGatewayLogs` (_array of GatewayLogOutputRepresentation_) Gateway Log Collection Representation for Auth Reversal

_Example_

```
{
  "paymentGatewayLogs": [
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    },
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    }
  ],
  "gatewayResponse": {},
  "error": {},
  "paymentAuthAdjustment": {
    "accountId": "accountId",
    "amount": 0.8008281904610115,
    "paymentAuthAdjustmentNumber": "paymentAuthAdjustmentNumber",
    "requestDate": "requestDate",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id",
    "effectiveDate": "effectiveDate",
    "status": "status"
  }
}
```

### PaymentMethodTokenizationInputRepresentation

Represents the payment method tokenization input that is processed by the payment tokenization service.

Includes all fields of `GatewayCallableBaseInputRepresentation`.

*   `address` (_AddressInputRepresentation_)
*   `cardPaymentMethod` (_CardPaymentMethodInputRepresentation_)
*   `bankPaymentMethod` (_BankPaymentMethodInputRepresentation_)
*   `paymentGatewayId` (_string_) Required. ID of the payment gateway.

_Example_

```
{
  "BankPaymentMethodTokenisation": {
    "summary": "Tokenisation for the BankPaymentMethod.",
    "value": {
      "address": {
        "city": "San Francisco",
        "country": "US",
        "postalCode": "94105",
        "state": "CA",
        "street": "415 Mission Street"
      },
      "bankPaymentMethod": {
        "accountHolderFirstName": "John",
        "accountHolderLastName": "Doe",
        "accountHolderName": "John Doe",
        "accountHolderType": "Individual",
        "accountId": "001RM000005WOk0YAG",
        "accountNumber": 123456789,
        "accountType": "Savings",
        "autoPay": true,
        "bankCode": "110000000",
        "bankType": "Ach",
        "email": "johndoe@test.com",
        "nickName": "John Doe",
        "standardEntryClassCode": "WEB"
      },
      "paymentGatewayId": "0b0xx0000000001XYZ"
    }
  },
  "CardPaymentMethodTokenisation": {
    "summary": "Tokenisation for the CardPaymentMethod.",
    "value": {
      "address": {
        "city": "San Francisco",
        "country": "US",
        "postalCode": "94105",
        "state": "CA",
        "street": "415 Mission Street"
      },
      "cardPaymentMethod": {
        "accountId": "001RM000005WOk0YAG",
        "autoPay": true,
        "cardCategory": "CreditCard",
        "cardHolderFirstName": "John",
        "cardHolderLastName": "Doe",
        "cardHolderName": "John Doe",
        "cardNumber": "4242424242424242",
        "cardType": "visa",
        "cvv": "113",
        "email": "johndoe@test.com",
        "expiryMonth": "10",
        "expiryYear": "2028",
        "nickName": "John",
        "startMonth": "10",
        "startYear": "2018"
      },
      "paymentGatewayId": "0b0xx0000000001XYZ"
    }
  },
  "GeneralTokenisation": {
    "summary": "Tokenisation for the given CardPaymentMethod or BankPaymentMethod(Only one PaymentMethod can be used).",
    "value": {
      "address": {},
      "bankPaymentMethod": {},
      "cardPaymentMethod": {},
      "paymentGatewayId": "paymentGatewayId"
    }
  }
}
```

### PaymentMethodTokenizationOutputRepresentation

Payment method tokenization output representation.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayResponse` (_PaymentMethodTokenizationGatewayResponseRepresentation_)
*   `paymentGatewayLogs` (_array of GatewayLogOutputRepresentation_) Payment gateway log response containing details of the PaymentGatewayLog entity records created during the processing of the sale request.
*   `paymentMethod` (_PaymentMethodOutputRepresentation_)

_Example_

```
{
  "paymentGatewayLogs": [
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    },
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    }
  ],
  "gatewayResponse": {
    "gatewayResultCode": "gatewayResultCode",
    "gatewayResultCodeDescription": "gatewayResultCodeDescription",
    "salesforceResultCode": "salesforceResultCode",
    "gatewayAvsCode": "gatewayAvsCode",
    "gatewayDate": "gatewayDate",
    "gatewayToken": "gatewayToken",
    "gatewayMessage": "gatewayMessage"
  },
  "paymentMethod": {
    "accountId": "accountId",
    "paymentMethodDetails": {
      "digitalWallet": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "alternativePaymentMethod": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "paymentMethodDetails": "paymentMethodDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodSubType": "paymentMethodSubType",
        "type": "type",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "cardPaymentMethod": {
        "autoPay": true,
        "comments": "comments",
        "cardHolderName": "cardHolderName",
        "startMonth": 5,
        "nickName": "nickName",
        "cardType": "cardType",
        "expiryMonth": 6,
        "startYear": 5,
        "cardCategory": "CreditCard",
        "cardHolderLastName": "cardHolderLastName",
        "displayCardNumber": "displayCardNumber",
        "expiryYear": 1,
        "cardLastFour": "cardLastFour",
        "accountId": "accountId",
        "cardBin": "cardBin",
        "cardTypeCategory": "AmericanExpress",
        "paymentMethodDetails": "paymentMethodDetails",
        "paymentMethodSubType": "paymentMethodSubType",
        "paymentMethodType": "Ach",
        "cardHolderFirstName": "cardHolderFirstName",
        "email": "email"
      },
      "bankPaymentMethod": {
        "accountId": "01xx00000HGJHG",
        "bankType": "ACH",
        "autoPay": false,
        "email": "email@email.com",
        "comments": "comments",
        "accountHolderType": "Individual",
        "accountType": "Savings",
        "lastFour": "4444",
        "bankCode": "21312311123",
        "standardEntryClassCode": "WEB",
        "savedPaymentMethodId": "12qxx000002pmkqAAA",
        "bankName": "ACH Bank",
        "name": null,
        "gatewayTokenDetails": "gatewayTokenDetails",
        "gatewayToken": "gatewayToken"
      }
    },
    "id": "id",
    "status": "status"
  },
  "error": {}
}
```

### ReferencedRefundInputRepresentation

Referenced refund input representation.

Includes all fields of `RefundInputRepresentation`.

*   `accountId` (_string_) Optional. ID of the account which must be linked to this referenced refund request.
*   `amount` (_number (double)_) Required. Amount that must be refunded.
*   `clientContext` (_string_) Optional. Provides context for payment APIs. Used for a payment caller to reestablish context.
*   `comments` (_string_) Optional. Comments for the refund.
*   `effectiveDate` (_string_) Optional. Date that the refund becomes effective.
*   `paymentGroup` (_PaymentGroupInputRepresentation_)
*   `paymentId` (_string_) Required. ID of the payment record.

_Example_

```
{
  "clientContext": "clientContext",
  "accountId": "accountId",
  "amount": 0.8008281904610115,
  "comments": "comments",
  "paymentId": "paymentId",
  "paymentGroup": {},
  "effectiveDate": "effectiveDate"
}
```

### RefundServiceOutputRepresentation

Refund comprehensive output representation.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayResponse` (_RefundGatewayResponseRepresentation_)
*   `paymentGatewayLogs` (_array of GatewayLogOutputRepresentation_) Gateway log collection representation for a refund.
*   `paymentGroup` (_PaymentGroupRepresentation_)
*   `refund` (_RefundOutputRepresentation_)

_Example_

```
{
  "paymentGatewayLogs": [
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    },
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    }
  ],
  "gatewayResponse": {},
  "paymentGroup": {
    "sourceObjectId": "sourceObjectId",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id"
  },
  "error": {},
  "refund": {
    "accountId": "accountId",
    "amount": 0.8008281904610115,
    "requestDate": "requestDate",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id",
    "effectiveDate": "effectiveDate",
    "refundNumber": "refundNumber",
    "status": "status"
  }
}
```

### PostAuthInputRepresentation

Payment post authorization input consumed by payment post authorization service. service.

Includes all fields of `GatewayCallableBaseInputRepresentation`.

*   `accountId` (_string_) Required. ID of the account of the customer for the authorized payment.
*   `amount` (_number (double)_) Required. Amount of the post authorization.
*   `comments` (_string_) Optional. Comments for payment post authorization. Maximum of 1000 characters.
*   `currencyIsoCode` (_string_) Optional. Three-letter ISO 4217 currency code associated with the payment group record.
*   `effectiveDate` (_string_) Required. Date that the payment post authorization occurs.
*   `paymentData` (_object_) Required. Payment Data to be used for this post authorization.
    
    Additional properties: `string`.
    
*   `paymentGatewayId` (_string_) Required. Payment gateway that evaluates the post authorization.
*   `paymentGroup` (_PaymentGroupInputRepresentation_)
*   `paymentMethod` (_PostAuthApiPaymentMethodInputRepresentation_)
*   `sourceObjects` (_array of string_) Source IDs for the sale transaction. This list is validated only against the native payment gateway (for example, a PayPal response).

_Example_

```
{
  "accountId": "accountId",
  "paymentGatewayId": "paymentGatewayId",
  "amount": 0.8008281904610115,
  "comments": "comments",
  "paymentGroup": {},
  "paymentData": {
    "key": "paymentData"
  },
  "paymentMethod": {},
  "currencyIsoCode": "currencyIsoCode",
  "effectiveDate": "effectiveDate",
  "sourceObjects": [
    "sourceObjects",
    "sourceObjects"
  ]
}
```

### PostAuthOutputRepresentation

Payment post authorization output.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayResponse` (_PostAuthGatewayResponseRepresentation_)
*   `payment` (_PaymentOutputRepresentation_)
*   `paymentAuthorization` (_PaymentAuthorizationOutputRepresentation_)
*   `paymentGatewayLogs` (_array of GatewayLogOutputRepresentation_) Gateway Log list representation for Payment Authorization
*   `paymentGroup` (_PaymentGroupRepresentation_)
*   `paymentMethod` (_PaymentMethodOutputRepresentation_)
*   `savedPaymentMethodStatus` (_string_) Saved payment method status.  
    Allowed values: `AlreadyExists`, `Created`, `Updated`.

_Example_

```
{
  "paymentGatewayLogs": [
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    },
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    }
  ],
  "paymentAuthorization": {
    "accountId": "accountId",
    "amount": 0.8008281904610115,
    "requestDate": "requestDate",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id",
    "effectiveDate": "effectiveDate",
    "expirationDate": "expirationDate",
    "paymentAuthorizationNumber": "paymentAuthorizationNumber",
    "status": "status"
  },
  "gatewayResponse": {
    "gatewayAuthorizationCode": "gatewayAuthorizationCode",
    "paymentMethodDetails": {
      "digitalWallet": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "alternativePaymentMethod": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "paymentMethodDetails": "paymentMethodDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodSubType": "paymentMethodSubType",
        "type": "type",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "cardPaymentMethod": {
        "autoPay": true,
        "comments": "comments",
        "cardHolderName": "cardHolderName",
        "startMonth": 5,
        "nickName": "nickName",
        "cardType": "cardType",
        "expiryMonth": 6,
        "startYear": 5,
        "cardCategory": "CreditCard",
        "cardHolderLastName": "cardHolderLastName",
        "displayCardNumber": "displayCardNumber",
        "expiryYear": 1,
        "cardLastFour": "cardLastFour",
        "accountId": "accountId",
        "cardBin": "cardBin",
        "cardTypeCategory": "AmericanExpress",
        "paymentMethodDetails": "paymentMethodDetails",
        "paymentMethodSubType": "paymentMethodSubType",
        "paymentMethodType": "Ach",
        "cardHolderFirstName": "cardHolderFirstName",
        "email": "email"
      }
    }
  },
  "paymentGroup": {
    "sourceObjectId": "sourceObjectId",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id"
  },
  "paymentMethod": {
    "accountId": "accountId",
    "paymentMethodDetails": {
      "digitalWallet": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "alternativePaymentMethod": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "paymentMethodDetails": "paymentMethodDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodSubType": "paymentMethodSubType",
        "type": "type",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "cardPaymentMethod": {
        "autoPay": true,
        "comments": "comments",
        "cardHolderName": "cardHolderName",
        "startMonth": 5,
        "nickName": "nickName",
        "cardType": "cardType",
        "expiryMonth": 6,
        "startYear": 5,
        "cardCategory": "CreditCard",
        "cardHolderLastName": "cardHolderLastName",
        "displayCardNumber": "displayCardNumber",
        "expiryYear": 1,
        "cardLastFour": "cardLastFour",
        "accountId": "accountId",
        "cardBin": "cardBin",
        "cardTypeCategory": "AmericanExpress",
        "paymentMethodDetails": "paymentMethodDetails",
        "paymentMethodSubType": "paymentMethodSubType",
        "paymentMethodType": "Ach",
        "cardHolderFirstName": "cardHolderFirstName",
        "email": "email"
      }
    },
    "id": "id",
    "status": "status"
  },
  "savedPaymentMethodStatus": "AlreadyExists",
  "payment": {
    "accountId": "accountId",
    "amount": 0.8008281904610115,
    "requestDate": "requestDate",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id",
    "effectiveDate": "effectiveDate",
    "paymentNumber": "paymentNumber",
    "status": "status"
  },
  "error": {}
}
```

### SaleInputRepresentation

Payment Sale input consumed by the payment sale service.

Includes all fields of `GatewayCallableBaseInputRepresentation`.

*   `accountId` (_string_) Optional. Salesforce account that contains the payment for the sale request.
*   `paymentInitiationSource` (_PaymentInitiationSourceInputRepresentation_) Optional. Payment initiation source representation for sale request.
*   `paymentInitiationSourceId` (_any_)
    
    ID of the source that initiated the payment.
    
    Specify if `paymentInitiationSource` isn't provided. Supported only for third-party payment gateways; not supported for native payments. See [PaymentInitiationSource](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentinitiationsource.htm) object documentation for more information.
    
*   `amount` (_number (double)_) Required. Amount of the sale.
*   `comments` (_string_) Optional. Comments for the payment sale request.
*   `currencyIsoCode` (_string_) Required, if multi-currency is enabled. A three-letter ISO 4217 currency code associated with the payment group record.
*   `enhancedPaymentData` (_EnhancedPaymentDataInputRepresentation_)
*   `effectiveDate` (_string_) Optional. The date that the sale request takes effect.
*   `paymentData` (_object_) Required. Payment data for a payment sale transaction.
    
    Additional properties: `string`.
    
*   `paymentGatewayId` (_string_) Required. The gateway that evaluates the payment sale request.
*   `paymentGroup` (_PaymentGroupInputRepresentation_)
*   `paymentMethod` (_SaleApiPaymentMethodInputRepresentation_)
*   `sourceObjects` (_array of string_) Source IDs for the sale transaction.

### SaleOutputRepresentation

Payment sale output.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayResponse` (_SaleGatewayResponseRepresentation_)
*   `payment` (_PaymentOutputRepresentation_)
*   `paymentGatewayLogs` (_array of GatewayLogOutputRepresentation_) Payment gateway log response containing details of the PaymentGatewayLog entity records created during the processing of the sale request.
*   `paymentGroup` (_PaymentGroupRepresentation_)
*   `paymentMethod` (_PaymentMethodOutputRepresentation_)

_Example_

```
{
  "paymentGatewayLogs": [
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    },
    {
      "gatewayResultCode": "gatewayResultCode",
      "createdDate": "createdDate",
      "id": "id",
      "interactionStatus": "interactionStatus"
    }
  ],
  "gatewayResponse": {},
  "paymentGroup": {
    "sourceObjectId": "sourceObjectId",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id"
  },
  "paymentMethod": {
    "accountId": "accountId",
    "paymentMethodDetails": {
      "digitalWallet": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "alternativePaymentMethod": {
        "accountId": "accountId",
        "comments": "comments",
        "name": "name",
        "gatewayTokenDetails": "gatewayTokenDetails",
        "paymentMethodDetails": "paymentMethodDetails",
        "gatewayToken": "gatewayToken",
        "paymentMethodSubType": "paymentMethodSubType",
        "type": "type",
        "paymentMethodType": "Ach",
        "email": "email"
      },
      "cardPaymentMethod": {
        "autoPay": true,
        "comments": "comments",
        "cardHolderName": "cardHolderName",
        "startMonth": 5,
        "nickName": "nickName",
        "cardType": "cardType",
        "expiryMonth": 6,
        "startYear": 5,
        "cardCategory": "CreditCard",
        "cardHolderLastName": "cardHolderLastName",
        "displayCardNumber": "displayCardNumber",
        "expiryYear": 1,
        "cardLastFour": "cardLastFour",
        "accountId": "accountId",
        "cardBin": "cardBin",
        "cardTypeCategory": "AmericanExpress",
        "paymentMethodDetails": "paymentMethodDetails",
        "paymentMethodSubType": "paymentMethodSubType",
        "paymentMethodType": "Ach",
        "cardHolderFirstName": "cardHolderFirstName",
        "email": "email"
      },
      "bankPaymentMethod": {
        "accountId": "01xx00000HGJHG",
        "bankType": "ACH",
        "accountHolderFirstName": "John",
        "accountHolderLastName": "Doe",
        "autoPay": false,
        "email": "email@email.com",
        "nickName": "John's ACH",
        "comments": "comments",
        "accountHolderType": "Individual",
        "accountNumberLastFour": "4444"
      }
    },
    "id": "id",
    "status": "status"
  },
  "payment": {
    "accountId": "accountId",
    "amount": 0.8008281904610115,
    "requestDate": "requestDate",
    "currencyIsoCode": "currencyIsoCode",
    "id": "id",
    "effectiveDate": "effectiveDate",
    "paymentNumber": "paymentNumber",
    "status": "status"
  },
  "error": {}
}
```

### GatewayCallableBaseInputRepresentation

Base request parameters input representation.

Includes all fields of `AuditParamsInputRepresentation`.

*   `additionalData` (_object_) Optional. Additional data from a payment request. Supports up to five key-value pairs. Each key and each value can contain up to 255 characters.
    
    Additional properties: `string`.
    
*   `duplicate` (_boolean_) Reserved for internal use.
*   `idempotencyKey` (_string_) Optional. Idempotency key used for the payment request. The key can be in the payload or the header but not both.

### PaymentInitiationSourceInputRepresentation

Input Representation for Payment Initiation Source.

*   `application` (_object_) Application that initiated this payment, such as Revenue Lifecycle Management (RLM).
    
    Includes all fields of `Application`.
    
*   `channel` (_string_) Channel that submitted the payment.
*   `process` (_string_) Process or component of the application that submitted the payment, such as the Billing component of RLM.
*   `orderSummary` (_string_) Reference to Order Summary linked to this payment.
*   `opportunity` (_string_) Reference to Opportunity that initiated this payment.
*   `serviceAppointment` (_string_) Reference to Service Appointment that initiated this payment.
*   `workOrder` (_string_) Reference to Work Order that initiated this payment.
*   `workOrderLineItem` (_string_) Reference to Work Order Line Item that initiated this payment.
*   `quote` (_string_) Reference to Quote that initiated this payment.
*   `initiatingAccount` (_string_) Reference to account that initiated this payment.
*   `initiatingContact` (_string_) Reference to Contact that initiated this payment.
*   `webStore` (_string_) Reference to WebStore that initiated this payment.
*   `webCart` (_string_) Reference to WebCart that initiated this payment.
*   `site` (_string_) Reference to the Site that initiated this payment.
*   `collectionPlan` (_string_) Reference to the CollectionPlan that initiated this payment.
*   `customFields` (_object_) Wraps a map of custom field name and id.
    
    Includes all fields of `CustomFieldInputRepresentation`.
    

### PaymentGroupInputRepresentation

Payment group details associated with the request. Users can either request creation of a new ID or pass an ID.

*   `createPaymentGroup` (_boolean_) Indicates whether payment group needs to be created (true) or not (false).
*   `currencyIsoCode` (_string_) Three-letter ISO 4217 currency code associated with the payment group record.
*   `id` (_string_) If ID has a value, the payment capture is using an active PaymentGroup. If ID is null and other parameters have values, the payment capture will create a new payment group. If a payment group ID exists, currencyIsoCode and sourceObjectId parameters must be null, and createPaymentGroup can be absent or false.
*   `sourceObjectId` (_string_) ID of the Order object for linking an order to a payment group. Provide an existing OrderId.
*   `uuid` (_string_) Unique ID to refer payment intent.

### AuthApiPaymentMethodInputRepresentation

Payment method input representation for authorization.

Includes all fields of `BaseApiPaymentMethodInputRepresentation`.

*   `cardPaymentMethod` (_CardPaymentMethodInputRepresentation_)

### ErrorResponseRepresentation

Error response following a failed payment method tokenization request.

*   `errorCode` (_string_) Error code.
*   `errorMessage` (_string_) Message stating the reason for error, if any.

### AuthorizationGatewayResponseRepresentation

Response returned by the payment gateway following an authorization request from the payment gateway adapter.

Includes all fields of `AbstractGatewayTxnResponseRepresentation`.

*   `gatewayAuthorizationCode` (_string_) Authorization code for the payment gateway.

_Example_

```
{
  "gatewayAuthorizationCode": "gatewayAuthorizationCode"
}
```

### PaymentAuthorizationOutputRepresentation

Payment authorization output representation.

*   `accountId` (_string_) Salesforce account for the payment authorization.
*   `amount` (_number (double)_) Amount that the gateway authorized for the payment transaction.
*   `currencyIsoCode` (_string_) Three-letter ISO 4217 currency code associated with the payment group record.
*   `effectiveDate` (_string_) Date that the authorization becomes effective.
*   `expirationDate` (_string_) Date that the authorization expires.
*   `id` (_string_) ID of the payment authorization record.
*   `paymentAuthorizationNumber` (_string_) System-defined number for the payment authorization record.
*   `requestDate` (_string_) Date that the authorization occurred.
*   `status` (_string_) Status of the payment authorization as returned by the gateway.

_Example_

```
{
  "accountId": "accountId",
  "amount": 0.8008281904610115,
  "requestDate": "requestDate",
  "currencyIsoCode": "currencyIsoCode",
  "id": "id",
  "effectiveDate": "effectiveDate",
  "expirationDate": "expirationDate",
  "paymentAuthorizationNumber": "paymentAuthorizationNumber",
  "status": "status"
}
```

### GatewayLogOutputRepresentation

Gateway log output representation.

*   `createdDate` (_string_) Date indicating when the gateway log was created.
*   `gatewayResultCode` (_string_) The gateway sends result codes to show the status of a transaction as it is passed to the financial institution and then returned to the client.
*   `id` (_string_) ID of the gateway log record.
*   `interactionStatus` (_string_) Gateway interaction status. Current supported values are SUCCESS, FAILED, or TIMEOUT.

_Example_

```
{
  "gatewayResultCode": "gatewayResultCode",
  "createdDate": "createdDate",
  "id": "id",
  "interactionStatus": "interactionStatus"
}
```

### PaymentGroupRepresentation

Payment group output representation.

*   `currencyIsoCode` (_string_) Three-letter ISO 4217 currency code associated with the payment group record.
*   `id` (_string_) ID of the payment group record.
*   `sourceObjectId` (_string_) Source object ID of the payment group record. Supports only OrderId.

_Example_

```
{
  "sourceObjectId": "sourceObjectId",
  "currencyIsoCode": "currencyIsoCode",
  "id": "id"
}
```

### PaymentMethodOutputRepresentation

Payment method response.

*   `accountId` (_string_) Salesforce Payments account to which this payment method is linked.
*   `id` (_string_) ID of the payment method record.
*   `paymentMethodDetails` (_PaymentMethodDetailsRepresentation_)
*   `status` (_string_) Status of the payment method as returned by the payment gateway.

_Example_

```
{
  "accountId": "accountId",
  "paymentMethodDetails": {
    "digitalWallet": {
      "accountId": "accountId",
      "comments": "comments",
      "name": "name",
      "gatewayTokenDetails": "gatewayTokenDetails",
      "gatewayToken": "gatewayToken",
      "paymentMethodType": "Ach",
      "email": "email"
    },
    "alternativePaymentMethod": {
      "accountId": "accountId",
      "comments": "comments",
      "name": "name",
      "gatewayTokenDetails": "gatewayTokenDetails",
      "paymentMethodDetails": "paymentMethodDetails",
      "gatewayToken": "gatewayToken",
      "paymentMethodSubType": "paymentMethodSubType",
      "type": "type",
      "paymentMethodType": "Ach",
      "email": "email"
    },
    "cardPaymentMethod": {
      "autoPay": true,
      "comments": "comments",
      "cardHolderName": "cardHolderName",
      "startMonth": 5,
      "nickName": "nickName",
      "cardType": "cardType",
      "expiryMonth": 6,
      "startYear": 5,
      "cardCategory": "CreditCard",
      "cardHolderLastName": "cardHolderLastName",
      "displayCardNumber": "displayCardNumber",
      "expiryYear": 1,
      "cardLastFour": "cardLastFour",
      "accountId": "accountId",
      "cardBin": "cardBin",
      "cardTypeCategory": "AmericanExpress",
      "paymentMethodDetails": "paymentMethodDetails",
      "paymentMethodSubType": "paymentMethodSubType",
      "paymentMethodType": "Ach",
      "cardHolderFirstName": "cardHolderFirstName",
      "email": "email"
    }
  },
  "id": "id",
  "status": "status"
}
```

### CaptureGatewayResponseRepresentation

Capture Gateway Response representation.

Includes all fields of `AbstractGatewayTxnResponseRepresentation`.

_Example_

```
{}
```

### PaymentOutputRepresentation

Payment output representation.

*   `accountId` (_string_) ID of the account related the payment record.
*   `amount` (_number (double)_) Total amount of the payment transaction performed in the payment request.
*   `currencyIsoCode` (_string_) Three-letter ISO 4217 currency code associated with the payment output.
*   `effectiveDate` (_string_) Effective Date, date from which this payment is effective
*   `id` (_string_) Id of the Payment record
*   `paymentNumber` (_string_) Payment number
*   `requestDate` (_string_) Date on which this payment transaction occurred
*   `status` (_string_) Date that the payment becomes effective.

_Example_

```
{
  "accountId": "accountId",
  "amount": 0.8008281904610115,
  "requestDate": "requestDate",
  "currencyIsoCode": "currencyIsoCode",
  "id": "id",
  "effectiveDate": "effectiveDate",
  "paymentNumber": "paymentNumber",
  "status": "status"
}
```

### AuthReversalGatewayResponseRepresentation

Authorization reversal gateway response representation.

Includes all fields of `AbstractGatewayTxnResponseRepresentation`.

_Example_

```
{}
```

### AuthAdjustmentOutputRepresentation

Authorization adjustment output representation.

*   `accountId` (_string_) ID of the account containing the payment authorization being adjusted.
*   `amount` (_number (double)_) Amount of the payment authorization adjustment.
*   `currencyIsoCode` (_string_) Three-letter ISO 4217 currency code associated with the payment authorization adjustment.
*   `effectiveDate` (_string_) Date when the authorization adjustment becomes effective.
*   `id` (_string_) ID of the PaymentAuthAdjustment record.
*   `paymentAuthAdjustmentNumber` (_string_) System-defined reference number.
*   `requestDate` (_string_) Date when the authorization adjustment transaction occurred.
*   `status` (_string_) Status of the payment authorization adjustment. Status can either be DRAFT: The payment authorization reversal can be edited before applying it against the parent authorization., PROCESSED: The payment authorization reversal has been finalized. or CANCELLED: The payment authorization reversal has been canceled. The parent authorization has returned to its pre-reversal balance. Users can change the status as: Draft to Processed, Processed to Canceled, or Draft to Canceled.

_Example_

```
{
  "accountId": "accountId",
  "amount": 0.8008281904610115,
  "paymentAuthAdjustmentNumber": "paymentAuthAdjustmentNumber",
  "requestDate": "requestDate",
  "currencyIsoCode": "currencyIsoCode",
  "id": "id",
  "effectiveDate": "effectiveDate",
  "status": "status"
}
```

### AddressInputRepresentation

Commerce address input.

*   `city` (_string_) Address city.
*   `companyName` (_string_) Address company name.
*   `country` (_string_) Address country.
*   `postalCode` (_string_) Zip code or postal code for the address.
*   `state` (_string_) Address state.
*   `street` (_string_) Address street.

### CardPaymentMethodInputRepresentation

Card payment method input consumed by the payment gateway.

Includes all fields of `BasePaymentMethodInputRepresentation`.

*   `accountId` (_string_) Required. Salesforce Payments account to which this payment method is linked.
*   `autoPay` (_boolean_) Optional. Indicates whether a token for recurring payments is being requested (true) or not (false). If autoPay is set to true, a SavedPaymentMethod is created, and the generated token can be used for recurring payments.
*   `cardCategory` (_string_) Required. Card processing type.  
    Allowed values: `CreditCard`, `DebitCard`.
*   `cardHolderFirstName` (_string_) Required. First name of the card holder.
*   `cardHolderLastName` (_string_) Required. Last name of the card holder.
*   `cardHolderName` (_string_) Required. Full name of the card holder.
*   `cardNumber` (_string_) Required. Card number.
*   `cardType` (_string_) Required. Card network type.
*   `comments` (_string_) Optional. Optional comments for providing more information about the card.
*   `cvv` (_string_) Required. Card verification value. A unique number on the back of a credit card to authenticate the card.
*   `email` (_string_) Optional. Email address of the card holder.
*   `expiryMonth` (_integer_) Required. Card expiration month.
*   `expiryYear` (_integer_) Required. Card expiration year.
*   `nickName` (_string_) Optional. Nickname for the card.
*   `startMonth` (_integer_) Optional. Month the card becomes active.
*   `startYear` (_integer_) Optional. Year the card becomes active.

### BankPaymentMethodInputRepresentation

Details of the bank's payment method for the payment gateway.

Includes all fields of `BasePaymentMethodInputRepresentation`.

*   `accountId` (_string_, required) Required. Salesforce Payments account ID associated with the bank payment method.
*   `bankType` (_BankType_, required)
*   `accountHolderName` (_string_, required) Required. Name of the account holder.
*   `accountHolderFirstName` (_string_) First name of the account holder.
*   `accountHolderLastName` (_string_) Last name of the account holder.
*   `autoPay` (_boolean_) Indicates whether a token for recurring payments is being requested (true) or not (false). If autoPay is set to true, a SavedPaymentMethod is created, and the generated token can be used for recurring payments.
*   `email` (_string_) Email address of the account holder.
*   `nickName` (_string_) Nick name of the account holder.
*   `comments` (_string_) Additional details about the bank account.
*   `accountHolderType` (_AccountHolder_)
*   `accountNumber` (_string_, required) Required. Unique account number for the bank account.
*   `bankCode` (_string_, required) Required. Routing number is a unique nine-digit code that identifies the bank.
*   `accountType` (_AccountType_)
*   `standardEntryClassCode` (_StandardEntryClassCode_)

### PaymentMethodTokenizationGatewayResponseRepresentation

Represents the response from the payment method tokenization gateway.

Includes all fields of `AbstractGatewayResponseRepresentation`.

*   `gatewayToken` (_string_) Payment method token from the payment gateway.

_Example_

```
{
  "gatewayResultCode": "gatewayResultCode",
  "gatewayResultCodeDescription": "gatewayResultCodeDescription",
  "salesforceResultCode": "salesforceResultCode",
  "gatewayAvsCode": "gatewayAvsCode",
  "gatewayDate": "gatewayDate",
  "gatewayToken": "gatewayToken",
  "gatewayMessage": "gatewayMessage"
}
```

### RefundInputRepresentation

Abstract refund input representation.

Includes all fields of `GatewayCallableBaseInputRepresentation`.

### RefundGatewayResponseRepresentation

Refund gateway response representation.

Includes all fields of `AbstractGatewayTxnResponseRepresentation`.

_Example_

```
{}
```

### RefundOutputRepresentation

Refund output representation.

*   `accountId` (_string_) ID of the account related to the refund record.
*   `amount` (_number (double)_) Total amount of the refund transaction performed in the payment request.
*   `currencyIsoCode` (_string_) Three-letter ISO 4217 currency code associated with the payment group record.
*   `effectiveDate` (_string_) Date that the refund becomes effective.
*   `id` (_string_) ID of the refund record.
*   `refundNumber` (_string_) Number of the refund record that was created as a result of the request processing.
*   `requestDate` (_string_) Date when the refund occurred.
*   `status` (_string_) Indicates the results of processing the refund transaction in the gateway. The status can either be DRAFT, PROCESSED, or CANCELLED.

_Example_

```
{
  "accountId": "accountId",
  "amount": 0.8008281904610115,
  "requestDate": "requestDate",
  "currencyIsoCode": "currencyIsoCode",
  "id": "id",
  "effectiveDate": "effectiveDate",
  "refundNumber": "refundNumber",
  "status": "status"
}
```

### PostAuthApiPaymentMethodInputRepresentation

Payment method input representation for post authorization.

Includes all fields of `BaseApiPaymentMethodInputRepresentation`.

*   `alternativePaymentMethod` (_AlternativePaymentMethodInputRepresentation_)
*   `cardPaymentMethod` (_CardPaymentMethodInputRepresentation_)

### PostAuthGatewayResponseRepresentation

Post authorization payment gateway response.

Includes all fields of `AbstractGatewayTxnResponseRepresentation`.

*   `gatewayAuthorizationCode` (_string_) Code used with the authorization request in the payment gateway.
*   `paymentMethodDetails` (_PaymentMethodDetailsRepresentation_)

_Example_

```
{
  "gatewayAuthorizationCode": "gatewayAuthorizationCode",
  "paymentMethodDetails": {
    "digitalWallet": {
      "accountId": "accountId",
      "comments": "comments",
      "name": "name",
      "gatewayTokenDetails": "gatewayTokenDetails",
      "gatewayToken": "gatewayToken",
      "paymentMethodType": "Ach",
      "email": "email"
    },
    "alternativePaymentMethod": {
      "accountId": "accountId",
      "comments": "comments",
      "name": "name",
      "gatewayTokenDetails": "gatewayTokenDetails",
      "paymentMethodDetails": "paymentMethodDetails",
      "gatewayToken": "gatewayToken",
      "paymentMethodSubType": "paymentMethodSubType",
      "type": "type",
      "paymentMethodType": "Ach",
      "email": "email"
    },
    "cardPaymentMethod": {
      "autoPay": true,
      "comments": "comments",
      "cardHolderName": "cardHolderName",
      "startMonth": 5,
      "nickName": "nickName",
      "cardType": "cardType",
      "expiryMonth": 6,
      "startYear": 5,
      "cardCategory": "CreditCard",
      "cardHolderLastName": "cardHolderLastName",
      "displayCardNumber": "displayCardNumber",
      "expiryYear": 1,
      "cardLastFour": "cardLastFour",
      "accountId": "accountId",
      "cardBin": "cardBin",
      "cardTypeCategory": "AmericanExpress",
      "paymentMethodDetails": "paymentMethodDetails",
      "paymentMethodSubType": "paymentMethodSubType",
      "paymentMethodType": "Ach",
      "cardHolderFirstName": "cardHolderFirstName",
      "email": "email"
    }
  }
}
```

### EnhancedPaymentDataInputRepresentation

Represents enhanced payment data with Level 2 and Level 3 fields. Supported only for third-party payment gateways; not supported for native payments.

*   `additionalAttributes` (_AdditionalAttributesInputRepresentation_)
*   `discountAmount` (_number (double)_) Discount amount.
*   `dutyAmount` (_number (double)_) The total amount charged as duty or import or export tariffs on the transaction.
*   `invoiceNumber` (_string_) Invoice number associated with the transaction.
*   `lineItems` (_LineItemsListInputRepresentation_)
*   `referenceId` (_string_) Customer reference or identifier.
*   `salesTaxAmount` (_number (double)_) Sales tax amount.
*   `shipFromZip` (_string_) Origin postal code.
*   `shipToCountry` (_string_) Destination country code.
*   `shipToZip` (_string_) Destination postal code.
*   `shippingAmount` (_number (double)_) Shipping or freight amount.
*   `taxRate` (_number (double)_) The percentage rate of tax applied to the transaction or line item.
*   `totalTaxAmount` (_number (double)_) Total tax amount for the transaction.

### SaleApiPaymentMethodInputRepresentation

Payment method input consumed by the payment gateway.

Represents a payment method to be used in a payment sale request.

Includes all fields of `BaseApiPaymentMethodInputRepresentation`.

*   `cardPaymentMethod` (_CardPaymentMethodInputRepresentation_)
*   `bankPaymentMethod` (_BankPaymentMethodInputRepresentation_)

### SaleGatewayResponseRepresentation

Contains information about the payment gateway's processing of the payment sale request.

Includes all fields of `AbstractGatewayTxnResponseRepresentation`.

_Example_

```
{}
```

### AuditParamsInputRepresentation

Audit parameters input.

*   `email` (_string_) Optional. Email of the client that initiated the request.
*   `ipAddress` (_string_) Optional. IP address of the client from which the request is made.
*   `macAddress` (_string_) Optional. Mac address of the client from which the request is made.
*   `phone` (_string_) Optional. Phone of the client that initiated the request.

### Application

Application

Type: `any`.

Allowed values: `FSL—Field Service (FSL)`, `RLM—Revenue Lifecycle Management`, `Scheduler—Salesforce Scheduler`, `SCOM—Salesforce Commerce`.

### CustomFieldInputRepresentation

CustomFieldInputRepresentation

Map of custom field names and their corresponding IDs.

*   `asMap` (_object_) Map of custom field names and their corresponding IDs.
    
    Additional properties: `string`.
    

### BaseApiPaymentMethodInputRepresentation

Payment method input consumed by the payment gateway.

*   `address` (_object_) Required. Address of the payment method.
*   `id` (_string_) Required. ID of the payment method record. Used in payment transactions.
*   `saveForFuture` (_boolean_) Optional. Indicates whether to save a record of the payment method for future use (true) or not (false).

### AbstractGatewayTxnResponseRepresentation

Payment gateway response fields used in Sale, Auth and Capture APIs.

Includes all fields of `AbstractGatewayResponseRepresentation`.

*   `gatewayReferenceDetails` (_string_) Gateway reference details.
*   `gatewayReferenceNumber` (_string_) Gateway reference number.

### PaymentMethodDetailsRepresentation

Details about the payment method.

*   `alternativePaymentMethod` (_AlternativePaymentMethodRepresentation_)
*   `cardPaymentMethod` (_CardPaymentMethodRepresentation_)
*   `digitalWallet` (_DigitalWalletRepresentation_)
*   `bankPaymentMethod` (_BankPaymentMethodRepresentation_)

_Example_

```
{
  "digitalWallet": {
    "accountId": "accountId",
    "comments": "comments",
    "name": "name",
    "gatewayTokenDetails": "gatewayTokenDetails",
    "gatewayToken": "gatewayToken",
    "paymentMethodType": "Ach",
    "email": "email"
  },
  "alternativePaymentMethod": {
    "accountId": "accountId",
    "comments": "comments",
    "name": "name",
    "gatewayTokenDetails": "gatewayTokenDetails",
    "paymentMethodDetails": "paymentMethodDetails",
    "gatewayToken": "gatewayToken",
    "paymentMethodSubType": "paymentMethodSubType",
    "type": "type",
    "paymentMethodType": "Ach",
    "email": "email"
  },
  "cardPaymentMethod": {
    "autoPay": true,
    "comments": "comments",
    "cardHolderName": "cardHolderName",
    "startMonth": 5,
    "nickName": "nickName",
    "cardType": "cardType",
    "expiryMonth": 6,
    "startYear": 5,
    "cardCategory": "CreditCard",
    "cardHolderLastName": "cardHolderLastName",
    "displayCardNumber": "displayCardNumber",
    "expiryYear": 1,
    "cardLastFour": "cardLastFour",
    "accountId": "accountId",
    "cardBin": "cardBin",
    "cardTypeCategory": "AmericanExpress",
    "paymentMethodDetails": "paymentMethodDetails",
    "paymentMethodSubType": "paymentMethodSubType",
    "paymentMethodType": "Ach",
    "cardHolderFirstName": "cardHolderFirstName",
    "email": "email"
  }
}
```

### BasePaymentMethodInputRepresentation

Base payment method input consumed by the payment gateway.

### BankType

Bank type

Required. Bank type.

Type: `string`.

Allowed values: `ACH—Automated Clearing House transaction`, `SepaDebit—Single Euro Payments Area transaction`, `BECS—Bulk Electronic Clearing System transaction`, `BACS—Bankers' Automated Clearing Services transaction`.

### AccountHolder

AccountHolder

Account holder type.

Type: `string`.

Allowed values: `Individual`, `Business`.

### AccountType

AccountType

Account type.

Type: `string`.

Allowed values: `Savings`, `Business`.

### StandardEntryClassCode

StandardEntryClassCode

A three-letter code that identifies the type of electronic payment transaction being processed within the Automated Clearing House (ACH) network.

Type: `string`.

Allowed values: `WEB—Internet Initiated/Mobile`, `CCD—Corporate Credit or Debit`, `PPD—Prearranged Payment and Deposit`, `TEL—Telephone-Initiated Entry`.

### AbstractGatewayResponseRepresentation

Payment Gateway Response fields common across some services.

*   `gatewayAvsCode` (_string_) Gateway AVS code.
*   `gatewayDate` (_string_) Gateway date.
*   `gatewayMessage` (_string_) Message returned by the gateway.
*   `gatewayResultCode` (_string_) Gateway result code.
*   `gatewayResultCodeDescription` (_string_) Gateway result code description.
*   `salesforceResultCode` (_string_) Salesforce result code.

### AlternativePaymentMethodInputRepresentation

Alternative payment method input.

Includes all fields of `BasePaymentMethodInputRepresentation`.

*   `accountId` (_string_) Required. Salesforce Payments account to which this payment method is linked.
*   `comments` (_string_) Optional. Details about a record added by a user. Maximum of 1,000 characters.Users can add comments to provide additional details about a record. Maximum of 1000 characters.
*   `email` (_string_) Optional. Email address of the card holder.
*   `gatewayToken` (_string_) Required. A unique, alphanumeric ID, called a token, that a payment gateway generates when it first processes a payment. The token replaces the actual payment data so that the data is kept secure. This token is stored as encrypted text, and can be used for recurring payments.
*   `gatewayTokenDetails` (_string_) Required. Information about the gateway token.
*   `name` (_string_) Optional. Name that you assign to the payment method object.

### AdditionalAttributesInputRepresentation

A map of gateway-specific or custom fields.

*   `asMap` (_object_) Additional data for payment gateway.
    
    Additional properties: `string`.
    

### LineItemsListInputRepresentation

Collection of individual line items associated with the payment.

*   `lineItems` (_array of LineItemInputRepresentation_) Line items.

### AlternativePaymentMethodRepresentation

Alternative payment method details.

*   `accountId` (_string_) Salesforce Payments account to which this payment method is linked.
*   `comments` (_string_) Details about a record added by a user. Maximum of 1,000 characters.
*   `email` (_string_) Email address of the card holder.
*   `gatewayToken` (_string_) A unique, alphanumeric ID, called a token, that a payment gateway generates when it first processes a payment. The token replaces the actual payment data so that the data is kept secure. This token is stored as encrypted text, and can be used for recurring payments.
*   `gatewayTokenDetails` (_string_) Detailed information about the gateway token.
*   `name` (_string_) Name that you assign to the payment method object.
*   `paymentMethodDetails` (_string_) Payment method details.
*   `paymentMethodSubType` (_string_) Payment method sub type.
*   `paymentMethodType` (_PaymentMethodType_)
*   `type` (_string_) Payment method type.

_Example_

```
{
  "accountId": "accountId",
  "comments": "comments",
  "name": "name",
  "gatewayTokenDetails": "gatewayTokenDetails",
  "paymentMethodDetails": "paymentMethodDetails",
  "gatewayToken": "gatewayToken",
  "paymentMethodSubType": "paymentMethodSubType",
  "type": "type",
  "paymentMethodType": "Ach",
  "email": "email"
}
```

### CardPaymentMethodRepresentation

Details about the card payment method.

*   `accountId` (_string_) Salesforce Payments account to which this payment method is linked.
*   `autoPay` (_boolean_) Indicates whether a token for recurring payments is being requested (true) or not (false). If autoPay is set to true, a SavedPaymentMethod is created, and the generated token can be used for recurring payments.
*   `cardBin` (_string_) Bank Identification Number (BIN). The BIN is the first 4-6 numbers on a payment card that identifies the card issuer.
*   `cardCategory` (_string_) Card processing type.  
    Allowed values: `CreditCard`, `DebitCard`.
*   `cardHolderFirstName` (_string_) Card holder first name.
*   `cardHolderLastName` (_string_) Card holder last name.
*   `cardHolderName` (_string_) Card holder name.
*   `cardLastFour` (_string_) Last four digits of the card.
*   `cardType` (_string_) Credit card issuer.
*   `cardTypeCategory` (_CardTypeCategory_)
*   `comments` (_string_) Details about a record added by a user. Maximum of 1,000 characters.
*   `displayCardNumber` (_string_) Displayed card number.
*   `email` (_string_) Email address of the card holder.
*   `expiryMonth` (_integer_) Card expiration month.
*   `expiryYear` (_integer_) Card expiration year.
*   `nickName` (_string_) Nickname for the card.
*   `paymentMethodDetails` (_string_) Payment method details.
*   `paymentMethodSubType` (_string_) Payment method sub type.
*   `paymentMethodType` (_string_) Payment method type.  
    Allowed values: `Ach`, `AfterpayClearpay`, `AmericanExpress`, `ApplePay`, `Bacs`, `BanContact`, `Becs`, `DinersClub`, `Discover`, `Eps`, `GooglePay`, `Ideal`, `Jcb`, `Klarna`, `Maestro`, `Master`, `Other`, `PayPal`, `SepaDebit`, `UnionPay`, `Venmo`, `Visa`.
*   `startMonth` (_integer_) Month the card becomes active.
*   `startYear` (_integer_) Year the card becomes active.

_Example_

```
{
  "autoPay": true,
  "comments": "comments",
  "cardHolderName": "cardHolderName",
  "startMonth": 5,
  "nickName": "nickName",
  "cardType": "cardType",
  "expiryMonth": 6,
  "startYear": 5,
  "cardCategory": "CreditCard",
  "cardHolderLastName": "cardHolderLastName",
  "displayCardNumber": "displayCardNumber",
  "expiryYear": 1,
  "cardLastFour": "cardLastFour",
  "accountId": "accountId",
  "cardBin": "cardBin",
  "cardTypeCategory": "AmericanExpress",
  "paymentMethodDetails": "paymentMethodDetails",
  "paymentMethodSubType": "paymentMethodSubType",
  "paymentMethodType": "Ach",
  "cardHolderFirstName": "cardHolderFirstName",
  "email": "email"
}
```

### DigitalWalletRepresentation

Digital wallet details representation.

*   `accountId` (_string_) Digital wallet account ID.
*   `comments` (_string_) Comments for providing more information about the digital wallet.
*   `email` (_string_) Email address of the digital wallet holder.
*   `gatewayToken` (_string_) A unique, alphanumeric ID, called a token, that a payment gateway generates when it first processes a payment. The token replaces the actual payment data so that the data is kept secure. This token is stored as encrypted text, and can be used for recurring payments.
*   `gatewayTokenDetails` (_string_) Information about the gateway token.
*   `name` (_string_) Name for the digital wallet.
*   `paymentMethodType` (_string_) Payment method type.  
    Allowed values: `Ach`, `AfterpayClearpay`, `AmericanExpress`, `ApplePay`, `Bacs`, `BanContact`, `Becs`, `DinersClub`, `Discover`, `Eps`, `GooglePay`, `Ideal`, `Jcb`, `Klarna`, `Maestro`, `Master`, `Other`, `PayPal`, `SepaDebit`, `UnionPay`, `Venmo`, `Visa`.

_Example_

```
{
  "accountId": "accountId",
  "comments": "comments",
  "name": "name",
  "gatewayTokenDetails": "gatewayTokenDetails",
  "gatewayToken": "gatewayToken",
  "paymentMethodType": "Ach",
  "email": "email"
}
```

### BankPaymentMethodRepresentation

Details of the bank's payment method for the payment gateway.

*   `accountId` (_string_) Salesforce Payments account ID associated with the bank payment method.
*   `bankType` (_BankType_)
*   `autoPay` (_boolean_) Indicates whether a token for recurring payments is being requested (true) or not (false). If autoPay is set to true, a SavedPaymentMethod is created, and the generated token can be used for recurring payments.
*   `email` (_string_) Email address of the account holder.
*   `comments` (_string_) Additional details about the bank account.
*   `accountHolderType` (_AccountHolder_)
*   `accountType` (_AccountType_)
*   `lastFour` (_string_) Account Number last four.
*   `bankCode` (_string_) Routing number is a unique nine-digit code that identifies the bank.
*   `standardEntryClassCode` (_StandardEntryClassCode_)
*   `savedPaymentMethodId` (_string_) Saved payment method id.
*   `bankName` (_string_) Bank name.
*   `name` (_string_) Display name.
*   `gatewayToken` (_string_) Token that represents payment method.
*   `gatewayTokenDetails` (_string_) Details on the payment token.

_Example_

```
{
  "ACH": {
    "accountId": "01xx00000HGJHG",
    "bankType": "ACH",
    "autoPay": false,
    "email": "email@email.com",
    "comments": "comments",
    "accountHolderType": "Individual",
    "accountType": "Savings",
    "lastFour": "4444",
    "bankCode": "21312311123",
    "standardEntryClassCode": "WEB",
    "savedPaymentMethodId": "12qxx000002pmkqAAA",
    "bankName": "ACH Bank",
    "name": "ACH - 4444",
    "gatewayTokenDetails": "gatewayTokenDetails",
    "gatewayToken": "gatewayToken"
  },
  "SEPA": {
    "accountId": "01xx00000HGJHG",
    "bankType": "SepaDebit",
    "autoPay": false,
    "email": "email@email.com",
    "comments": "comments",
    "accountHolderType": "Individual",
    "accountType": "Savings",
    "lastFour": "3201",
    "bankCode": "110000001",
    "standardEntryClassCode": "WEB",
    "savedPaymentMethodId": "12qxx000002pmkqAAA",
    "bankName": "Sepa debit Bank",
    "name": "SepaDebit - SepaDebit",
    "gatewayTokenDetails": "gatewayTokenDetails",
    "gatewayToken": "gatewayToken"
  },
  "BECS": {
    "accountId": "01xx00000HGJHG",
    "bankType": "BECS",
    "autoPay": false,
    "email": "email@email.com",
    "comments": "comments",
    "accountHolderType": "Individual",
    "accountType": "Savings",
    "lastFour": "3456",
    "bankCode": "000000",
    "standardEntryClassCode": "WEB",
    "savedPaymentMethodId": "12qxx000002pmkqAAA",
    "bankName": "BECS Bank",
    "name": "BECS - 3456",
    "gatewayTokenDetails": "gatewayTokenDetails",
    "gatewayToken": "gatewayToken"
  },
  "BACS": {
    "accountId": "01xx00000HGJHG",
    "bankType": "BACS",
    "autoPay": false,
    "email": "email@email.com",
    "comments": "comments",
    "accountHolderType": "Individual",
    "accountType": "Savings",
    "lastFour": "2345",
    "bankCode": "108800",
    "standardEntryClassCode": "WEB",
    "savedPaymentMethodId": "12qxx000002pmkqAAA",
    "bankName": "BACS Bank",
    "name": "BACS - 2345",
    "gatewayTokenDetails": "gatewayTokenDetails",
    "gatewayToken": "gatewayToken"
  }
}
```

### LineItemInputRepresentation

Level 3 line item input representation.

*   `additionalAttributes` (_AdditionalAttributesInputRepresentation_)
*   `commodityCode` (_string_) Commodity code.
*   `description` (_string_) Product description.
*   `discount` (_number (double)_) Discount applied to the line item level.
*   `discountIndicator` (_string_) Specifies whether a discount was applied to the specific line item.
*   `dutyAmount` (_number (double)_) Duty or tariff applied specifically to a item (not the whole order).
*   `grossNetIndicator` (_string_) Specifies if the line item amount is Gross (before discounts) or Net (after discounts).
*   `lineItemId` (_string_) Line item identifier. Specify when multiple items are present.
*   `lineItemTotal` (_number (double)_) Total amount for that line item.
*   `name` (_string_) Product or service name.
*   `quantity` (_integer (int32)_) Quantity purchased.
*   `shippingAmount` (_number (double)_) Shipping or freight cost allocated to that line item.
*   `sku` (_string_) SKU or product code.
*   `taxAmount` (_number (double)_) Line-level tax amount.
*   `taxRate` (_number (double)_) Tax percentage applied to that specific line item.
*   `unitPrice` (_number (double)_) Unit price in minor units.
*   `uom` (_string_) Unit of measure. For example, EA, HRS, and KG.

### PaymentMethodType

PaymentMethodType

Types of the payment methods

Type: `string`.

Allowed values: `Ach`, `AfterpayClearpay`, `AmericanExpress`, `ApplePay`, `Bacs`, `BanContact`, `Becs`, `DinersClub`, `Discover`, `Eps`, `GooglePay`, `Ideal`, `Jcb`, `Klarna`, `Maestro`, `Master`, `Other`, `PayPal`, `SepaDebit`, `UnionPay`, `Venmo`, `Visa`.

### CardTypeCategory

Card type category.

Type: `string`.

Allowed values: `AmericanExpress`, `DinersClub`, `Discover`, `Jcb`, `Maestro`, `MasterCard`, `UnionPay`, `Visa`.

### AdditionalDataInputRepresentation

Wraps a map of additional data.

*   `asMap` (_object_) Additional data object consists of entries, each of which includes a key and value. Supports up to five key-value pairs. Each key and each value can contain up to 255 characters.
    
    Additional properties: `string`.
    

### DigitalWalletInputRepresentation

Digital wallet input representation.

Includes all fields of `BasePaymentMethodInputRepresentation`.

*   `accountId` (_string_) Required. Salesforce Payments account to which this payment method is linked.
*   `comments` (_string_) Optional. Details about a record added by a user. Maximum of 1,000 characters.
*   `email` (_string_) Optional. Email address of the card holder.
*   `gatewayToken` (_string_) Required. Token that represents payment method.
*   `gatewayTokenDetails` (_string_) Required. Details on the payment token like what it represents.
*   `name` (_string_) Optional. Name that you assign to the digital wallet.

### PaymentDataInputRepresentation

Payment data input representation.

*   `asMap` (_object_) Additional payment data.
    
    Additional properties: `string`.
    

### PaymentMethodInputRepresentation

Payment method input consumed by the payment gateway.

*   `address` (_object_) Required. Address of the payment method.
*   `cardPaymentMethod` (_object_) Required. Card details for the payment method.
*   `id` (_string_) Required. ID of the payment method record. Used in payment transactions.
*   `saveForFuture` (_boolean_) Optional. Indicates whether to save a record of the payment method for future use (true) or not (false).

### PostAuthPaymentDataInputRepresentation

Payment data for post auth service input representation.

*   `asMap` (_object_) Additional payment data for all post auth service.
    
    Additional properties: `string`.

<!-- document id=0d08add8c6f65cec8862ded737f16ebd8b7094e71d3257c62c7f3c639d2f3604 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-pricing-promotions-apis.md -->

# Salesforce Commerce Pricing and Promotions API

The Commerce Pricing and Promotion APIs enable developers to access product prices and promotions, streamlining the development of their applications. These APIs are typically used to populate Product Listing Page and Product Display Page, as well as when users add products to their carts.

The pricing API allows users to retrieve prices for single or multiple products. Product prices are determined by selecting the lowest (or highest priority) price from the pricebooks assigned to the store and any buyer groups the shopper belongs to.

There are two promotion evaluation APIs: Evaluate Products and Evaluate Cart. Evaluate products is commonly used on the Product Display Pages (PDP) and Product Listing Pages (PLP) to display promotion price and promotion messaging. For example, 10% of items in category clothing when you spend \$50.

Evaluate cart is invoked during any cart modification, such as adding to the cart, changing quantity, and applying coupons, and during checkout to compute promotion adjustments for the cart. This can either be called as part of the above-mentioned operations or directly through the Webstore Promotions, Evaluate Action API.

Furthermore, it's flexible in assessing promotions for specific products or sets, including variants and independent items, while excluding parent products. The API caters to both domain-dependent and independent needs, utilizing parameters like webstoreId and effectiveAccountId for internal evaluations or external datasets like SKUs.

Lastly, the Coupon API monitors coupon code redemption usage, allowing you to revert previously redeemed codes and tracking increases in usage of coupon codes.

## Use Case

Let's consider a basic scenario for understanding how to use Pricing and Promotion APIs. This example covers just a few Pricing and Promotion APIs APIs and doesn't include the entire APIs functionality.
![Diagram of the pricing and promotions APIs workflow for B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/pricing_promotions_apis_workflow.png '{"class": "image-lg", "title": "Pricing and Promotions Workflow"}')

In a typical shopping journey, when users land on your store's homepage, they've two options: they can either browse products by category or use the search box to find products, which are then displayed on the Product Listing Page (PLP). If customers choose to browse by category, the Product Listing Page loads, showcasing all products within the chosen category.

The process of displaying products onto the Product Listing Page involves two key steps: firstly, retrieving the list of products along with their prices, and secondly, fetching the promotions entitled to users. Make a GET call on the [Webstore Products API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_products.htm) to retrieve products and their prices. Make a POST request to [Webstore Cart Items API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm) to add product items to the cart and fetch and apply cart-level promotions entitled to users. This API offers the ability to retrieve cart-level promotions that users are entitled to, calculate the required price adjustments, and add the chosen products to the cart, in addition to adding products to the cart. Subsequently, make a GET call on the [Webstore Cart Items API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm) to review your cart and proceed with checkout.

Depending on your specific scenario, you may call these independent APIs, such as making a GET or POST request on the [Webstore Pricing Products API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_pricing_products.htm) to retrieve the pricing of products, making a POST request on the [Webstore Promotions, Evaluate Products Action API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_promotions_actions_evaluate_products.htm) to view the product promotions alongside displaying the products and pricing on the Product Listing Page and compute the applicable price adjustments, or making a POST request to the [Webstore Promotions, Evaluate Action API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_promotions_actions_evaluate.htm) to get promotions entitied to users based on the store and buyer group to be applied to the cart.

## Resources

Here’s a list of Product Pricing and Promotions resources:

| Resource                                                                                                                                                                                                      | Supported HTTP Methods | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/commerce/webstores/{webstoreId}/pricing/​products/{productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_price.htm)        | GET                    | Get the list and buyer price for a product.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [`/commerce/webstores/{webstoreId}/pricing/​products`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_pricing_products.htm)                 | GET, POST              | Get the prices for multiple products.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| [`/commerce/promotions/actions/evaluate`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_promotions_actions_evaluate.htm)                   | POST                   | Determine which promotions the customer is eligible for based on the store and buyer group, and compute the applicable price adjustments based on the coupons and the items in the cart. This API evaluates only the first 50 active manual promotions and first 50 active automatic promotions, based on priority. This API computes and returns applicable price adjustments, but it does not apply those adjustments to the webcart record. If you want to enable promotions based on shipping, contact Salesforce Customer Support.                    |
| [`/commerce/promotions/actions/evaluate-products`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_promotions_actions_evaluate_products.htm) | POST                   | Determine which promotions apply to a product or set of products, and compute the applicable price adjustments. This API evaluates discrete products, including product variants and independent products but not parent products. Domain dependent and independent use cases are both supported. For example, a domain dependent call uses `webstoreId` and `effectiveAccountId` to evaluate products in a cart based on internal products or product categories. A domain independent call uses an external dataset based on SKUs or product categories. |
| [`/commerce/promotions/actions/decrease-use​/coupon-codes`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_coupon_code_redemption_decrease.htm)               | POST                   | Get coupon code redemption usage to revert a previously redeemed coupon code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [`/commerce/promotions/actions/increase-use​/coupon-codes`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_coupon_code_redemption_increase.htm)               | POST                   | Get coupon code redemption addition (increase) usage.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

**See Also**

- [_B2B Commerce Developer Guide_: Pricing Data Model](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-pricing.html)
- [_B2B Commerce Developer Guide_: Promotions Data Model](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-promotions.html)
- [_B2B Commerce Developer Guide_: Promotions Data Model](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_data_model_promotions.htm)
- [_Salesforce B2B Commerce_: Pricing for Commerce Stores](https://help.salesforce.com/s/articleView?id=commerce.comm_pricebooks.htm)
- [_Salesforce B2B Commerce_: Commerce Promotions](https://help.salesforce.com/s/articleView?id=commerce.comm_promotions_create_manage.htm)

<!-- document id=0d2fbc393883f28687f7c48169640527a25513aba64258fbd575e2d4566c175d url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-product-category-apis.md -->

# Salesforce Commerce Product and Category APIs

Streamline product catalog management and improve the shopping experience by using the Salesforce Commerce Product and Category APIs. You can add or update products in your store, link them with specific categories and media records, create variation products, and get product information such as fields, prices, and category paths. The APIs also support product searches by term or category, search suggestions for products, and retrieval of sort rules for the search index.

## Add, Update, and Get Products with Product APIs

To add a product to your store, use [Commerce Webstore Composite Products, Create](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_products_create.htm). If you want to add a variation of a parent product, such as a different color or size of a shirt, you can use [Commerce Webstore Composite Product Variations, Create](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_variations_create.htm). These APIs work within the store’s context. When you create a product, the APIs link it to the default buyer group, entitlement policy, and price book records created during store setup. They also associate it to the current store’s catalog and the specified category and media in the POST request.

To update an existing product, make a PUT request to the [Commerce Webstore Composite Products, Update](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_products_update.htm) resource. When you update a product record, include both the category and media records that are already linked to it and any new ones that you want to add. If you don’t specify the existing associated category and media records, the API removes their association with the product.

To retrieve information about products, you can use one of three resources that support GET requests. These resources respect buyer View Product entitlements, so only users entitled to product data can access it.

1. For the [Product Detail representation](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_product_detail.htm) of a specific product, make a GET request to the [Commerce Webstore Product](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product.htm) resource.
2. For the fields, prices, and default images for a list of products, make a GET request to the [Commerce Webstore Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_products.htm) resource. This resource can also provide attribute set, variation, selling model, and quantity rule information for the product.
3. For a collection of bundle or set child products related to a parent product, make a GET request to the [Commerce Webstore Product Children](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_children.htm) resource.

## Get Category Details and Paths with Category APIs

Effective category structure in a store highlights product relationships and makes products easier to find through search and navigation. To help access your store’s product category information, Salesforce Commerce provides three API resources.

To get the details of a product category, make a GET request to [Commerce Webstore Product Category](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_category.htm). Include the IDs of the product category and the webstore in the request URL. The [response body](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_product_category_detail.htm) contains information such as a list of fields, media groups, and the URL slug for the category.

To get subcategories for a specific parent product category or get all the top-level product categories for the store, make a GET request to [Commerce Webstore Product Categories Children](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_categories_children.htm). The output depends on whether you set the ​`​parentProductCategoryId` request parameter. If you provide the ID of a product category, the API returns each of that category’s subcategories. A store supports up to 5 levels of categories and subcategories. If ​​`parentProductCategoryId` is unspecified, the API returns all the top-level product categories for the store.

To get the product category path from the root category to a specific category, make a GET request to [Commerce Webstore Product Category Path](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_category_path.htm). The response includes a list of categories in the path with each category’s ID, name, description, and URL slug. This information can help you highlight category hierarchy. For example, you can show a category path that goes from `Coffee Beans` to `Dark Roast`.

## Get Search Results, Suggestions, and Sort Rules with Product Search APIs

Help your customers find what they’re looking for with the Product Search APIs. Use these APIs to search for products in your catalog based on search terms or a category ID. You can also get suggested products for a search term, and get sort rules for the search index.

To search for products, make a GET request to [Commerce Webstore Search Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm). In your request, include a list of up to 32 space-separated search terms. To return only products from a particular product category, specify a category ID as well. You can specify just the category ID to return all products from that category without matching search terms, but at least 1 category ID or search term is required. Include product variation information in search results by setting the `includeProductVariationInfo` request parameter to `true`.

**note:** A resource was previously introduced to search products by using a POST request, but it was superseded by the GET endpoint. We recommend using the GET endpoint to take advantage of the latest API features. For example, only the GET endpoint supports the parameter `searchFields`, which is used to specify a subset of searchable fields to query.

To return suggested search terms or products, make a GET request to [Commerce Webstore Product Search Suggestions](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_suggestions.htm). In your request, you can include a string with up to 10 characters of a user’s search term. The response returns autocomplete suggestions from the user’s recent searches and suggestions from the product catalog. For example, the search term ground can return `ground coffee`, among other suggestions. Specify how many suggestions to return by setting the `maxResults` request parameter to a value from 1 to 10. If unspecified, this value defaults to 4.

You can also use this resource without providing a search term. If there’s no search term, the API identifies suggestions based on the user’s recent searches. In the example scenario, after searching for `ground coffee`, that term can be suggested the next time the user starts a search.

To return suggested products rather than terms, set the boolean request parameter `includeSuggestedProducts` to `true`. Product suggestions are returned as product IDs. Then, a call to one of the Product APIs can return information based on the product ID. For example, you can show the name and default image of a product in the search bar dropdown.

Lastly, to retrieve sort rules for a webstore, make a GET request to [Commerce Management Webstore Search, Sort Rules](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_management_webstore_search_sort_rules.htm). The Commerce search engine’s default Best Match rule sorts search results based on relevance. You can also add custom sort rules with a PUT request so that customers can arrange results by options like price in search and category pages.

## Use Case

To understand the Product and Category APIs, consider the steps involved in a sample workflow. This scenario doesn’t include the entire functionality of the APIs.

![Workflow of Product and Category APIs: add products and sort rules, suggest search terms and products, and get search results](https://developer.salesforce.com/media/d2c-commerce/product_category_apis_workflow.png '{"class": "image-framed"}')

A store manager begins by using the [Commerce Webstore Composite Products, Create](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_products_create.htm) API to update the store’s catalog, adding new products. This action ensures that customers always see the latest offerings and accurate product details.

For products that come in multiple variations, such as different sizes or colors, the manager uses the [Commerce Webstore Composite Product Variations, Create](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_variations_create.htm) API to create these variation listings. Now, customers can choose their preferred product variations directly from the product page.

To add custom sort rules, the manager uses the [Commerce Management Webstore Search, Sort Rules](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_management_webstore_search_sort_rules.htm) API. For example, they can create a sort rule so that customers can arrange results based on product attributes.

In the webstore, customers use the improved search functionality provided by the [Commerce Webstore Search Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm) and [Commerce Webstore Product Search Suggestions](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_suggestions.htm) APIs. They can quickly find products through search terms or categories, and the suggestions help them discover products more easily.

## Resources

| Resource                                                                                                                                                                                                                                        | Supported HTTP Methods | Description                                                                                                              |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| [`/commerce/management/webstore/${webstoreId}/composite-products`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_products_create.htm)                                       | POST                   | Add a product to your store and associate it with the specified category and media records.                              |
| [`/commerce/management/webstore/${webstoreId}/composite-products/${productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_products_update.htm)                          | PUT                    | Update an existing product record with the specified category and media records.                                         |
| [`/commerce/management/webstore/${webstoreId}/composite-variations`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_composite_variations_create.htm)                                   | POST                   | Create variation products with media and pricing details for a given parent product.                                     |
| [`/commerce/webstores/{webstoreId}/products`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_products.htm)                                                                    | GET                    | Get fields, prices, and default images for a list of products.                                                           |
| [`/commerce/webstores/{webstoreId}/products/{​productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product.htm)                                                        | GET                    | Get a product.                                                                                                           |
| [`/commerce/webstores/{webstoreId}/products/{​productId}/children`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_children.htm)                                      | GET                    | Get a collection of child products related to a parent product.                                                          |
| [`/commerce/webstores/{webstoreId}/​product-categories/children`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_categories_children.htm)                             | GET                    | Get product categories for a specific parent product category, or get all the top-level product categories for the store. |
| [`/commerce/webstores/{webstoreId}/​product-categories/{productCategoryId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_category.htm)                             | GET                    | Get a product category.                                                                                                  |
| [`/commerce/webstores/{webstoreId}/​product-category-path/product-categories/​{productCategoryId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_category_path.htm) | GET                    | Get the product category path from the root category to the current category.                                            |
| [`/commerce/webstores/{webstoreId}/search/​products`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm)                                                     | GET                    | Search products by search term or category in a webstore.                                                                |
| [`/commerce/webstores/{webstoreId}/search/​product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)                                                | POST                   | Search products.                                                                                                         |
| [`/commerce/webstores/{webstoreId}/search/​sort-rules`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_sort_rules.htm)                                                 | GET                    | Get sort rules for the live index.                                                                                       |
| [`/commerce/webstores/{webstoreId}/search/​suggestions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_suggestions.htm)                                               | GET                    | Get suggestions for product searches.                                                                                    |
| [`/commerce/management/webstores/{webstoreId}/search/​category-pinning-rules`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-product-search-category-pinning-rules-ref?meta=getSearchCategoryPinningRules)          | GET                    | Get a paginated list of category pinning rules for a web store.                                                          |
| [`/commerce/management/webstores/{webstoreId}/search/​category-pinning-rules`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-product-search-category-pinning-rules-ref?meta=createSearchCategoryPinningRule)        | POST                   | Create a category pinning rule for a web store.                                                                          |
| [`/commerce/management/webstores/{webstoreId}/search/​category-pinning-rules/{ruleId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-product-search-category-pinning-rules-ref?meta=getSearchCategoryPinningRule)  | GET                    | Get a category pinning rule.                                                                                             |
| [`/commerce/management/webstores/{webstoreId}/search/​category-pinning-rules/{ruleId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-product-search-category-pinning-rules-ref?meta=updateSearchCategoryPinningRule) | PUT                    | Replace a category pinning rule.                                                                                        |
| [`/commerce/management/webstores/{webstoreId}/search/​category-pinning-rules/{ruleId}`](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-product-search-category-pinning-rules-ref?meta=deleteSearchCategoryPinningRule) | DELETE                 | Delete a category pinning rule.                                                                                         |

<!-- document id=9fc988970a73c72ad19cab12c3639c09f17daba07730e183ea3c090f8aa4c75b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-product-quotes-ref.md -->

Salesforce Commerce Product Quotes API

# Salesforce Commerce Product Quotes API

Creates a quote from a product by leveraging a secondary cart, enabling buyers to request quotes for specific products with configurable selling models, quantities, and subscription terms. To access this API, users must have the following licenses and permissions:

*   B2B Commerce
*   Revenue Lifecycle Management

**Version:** v67.0

## Servers

*   `https://api.salesforce.com/services/data/{version}`
    *   `version (default v67.0)`

## Operations

### POST Create a quote from a product.

`POST /commerce/webstores/{webstoreId}/products/{productId}/quotes`

Operation ID: `createQuoteFromProduct`.

This API creates a new quote from a product on the Product Display Pages (PDP) in a B2B storefront.

It creates a temporary (secondary) cart to process the request. It converts the product details into quote line items based on the specified product ID and quantity. After processing, the secondary cart is deleted, regardless of whether the API call succeeds or fails.

Supported product types by license:

*   Simple products: Supported with B2B Commerce Only or B2B Commerce and Revenue Cloud licenses.
*   Static bundles: Supported only with the B2B Commerce and Revenue Cloud licenses.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the webstore
    
    The ID of the quote record to be retrieved.
    
*   `productId` (path, string (Id), required) The ID of the product to create a quote for
    
    The ID of the product to be converted to a quote.
    
*   `effectiveAccountId` (query, string (Id)) ID of the account for which the request is made. If null, the context user's account is used.
    
    The ID of the user account associated with the quote.
    

#### Request body (required)

Input parameters for creating a quote from the product.

Media type: `application/json`. Schema: `sfdc.commerce.product.connect.api.input.CreateQuoteFromProductInputRepresentation`.

_Example: basicQuote_ Basic quote request

```
{
  "quantity": "10"
}
```

_Example: fullQuote_ Full quote request with all options

```
{
  "productSellingModelId": "01txx0000000003AAA",
  "quantity": "100",
  "subscriptionTerm": 24,
  "comments": "Bulk order for enterprise deployment",
  "additionalFields": {
    "ExpirationDate": "2024-12-31",
    "BuyerEmail__c": "procurement@company.com"
  }
}
```

#### Responses

*   **200** Quote created successfully from product.
    
    Media type: `application/json`. Schema: `sfdc.commerce.product.connect.api.output.CreateQuoteFromProductOutputRepresentation`.
    
    _Example: success_ Successful quote creation
    
    ```
    {
      "quoteId": "0Q0xx0000000001AAA",
      "errors": []
    }
    ```
    
*   **400** Invalid input parameters or request data.
    
    Media type: `application/json`. Schema: `sfdc.commerce.product.connect.api.output.CreateQuoteFromProductOutputRepresentation`.
    
    _Example: invalidInput_ Invalid input error
    
    ```
    {
      "quoteId": null,
      "errors": [
        {
          "code": "INVALID_INPUT",
          "message": "The provided parameter is invalid or malformed."
        }
      ]
    }
    ```
    
    _Example: invalidCustomFields_ Invalid custom fields error
    
    ```
    {
      "quoteId": null,
      "errors": [
        {
          "code": "INVALID_CUSTOM_FIELDS",
          "message": "One or more custom field values are invalid."
        }
      ]
    }
    ```
    
*   **404** Requested resource doesn't exist.
    
    Media type: `application/json`. Schema: `sfdc.commerce.product.connect.api.output.CreateQuoteFromProductOutputRepresentation`.
    
    _Example: productNotFound_ Product not found error
    
    ```
    {
      "quoteId": null,
      "errors": [
        {
          "code": "PRODUCT_NOT_FOUND",
          "message": "The specified product doesn't exist."
        }
      ]
    }
    ```
    
    _Example: webstoreNotFound_ Web store not found error
    
    ```
    {
      "quoteId": null,
      "errors": [
        {
          "code": "WEBSTORE_NOT_FOUND",
          "message": "The specified web store doesn't exist."
        }
      ]
    }
    ```
    
*   **500** Unexpected system error occurred.
    
    Media type: `application/json`. Schema: `sfdc.commerce.product.connect.api.output.CreateQuoteFromProductOutputRepresentation`.
    
    _Example: internalError_ Internal server error
    
    ```
    {
      "quoteId": null,
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "An unexpected error occurred while processing the request."
        }
      ]
    }
    ```
    

## Schemas

### sfdc.commerce.product.connect.api.input.CreateQuoteFromProductInputRepresentation

Input representation for creating a quote from a product.

*   `quantity` (_string_, required) The quantity of the product to be included in the quote.  
    Example: `10`.
*   `comments` (_string_) The buyer-provided comments when requesting a quote, including special requests, bulk pricing inquiries, or additional notes.  
    Example: `Provide bulk pricing for 100+ units.`.
*   `additionalFields` (_object_) The key-value pairs for quote entity fields, including both standard and custom fields, used to set additional quote properties during creation.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "ExpirationDate": "2024-12-31",
      "BuyerEmail__c": "buyer@company.com"
    }
    ```
    

### sfdc.commerce.product.connect.api.output.CreateQuoteFromProductOutputRepresentation

Output representation for the create quote from product operation.

*   `quoteId` (_string (Id)_, nullable) The ID of the quote created upon a successful request.  
    Example: `0Q0xx0000000001AAA`.
*   `errors` (_array of sfdc.commerce.product.connect.api.output.ErrorOutputRepresentation_) List of errors encountered during cart creation. Returns an empty array on success.

### sfdc.commerce.product.connect.api.output.ErrorOutputRepresentation

Represents an error that occurred during the operation.

*   `code` (_string_) Error code identifying the error type.  
    Example: `INVALID_INPUT`.
*   `message` (_string_) Human-readable error message.  
    Example: `The provided parameter is invalid or malformed.`.

<!-- document id=e845c15a12ae5e3b308412278368608a5fba2f9965955395107bb95a551b4906 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-quotes-ref.md -->

Salesforce Commerce Quotes API

# Salesforce Commerce Quotes API

Salesforce Commerce Quotes APIs provide a streamlined way for developers to manage the complete quote lifecycle within a web store. They provide access to individual quote details, all quotes tied to a customer account, and real-time quote status and expiration tracking, supporting streamlined account-based quote workflows.

To access these resources, your org must have the B2B Commerce license, and these APIs are available only to authenticated users.

**Note:** The Commerce Quotes APIs don't support product bundles. Only simple products can be included in quote.

**Version:** 67.0

## Servers

*   `https://{yourinstance}.salesforce.com/services/data/{version}`
    *   `version (default v67.0)`

## Operations

### GET Retrieve details for a specified quote.

`GET /commerce/webstores/{webstoreId}/quotes/{quoteId}`

Operation ID: `getQuoteDetails`.

This API is used on the My Quotes page of the B2B storefront to retrieve details of a specific quote record, including status, line items, and user comments.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `quoteId` (path, string (Id), required) The ID of the quote record to be retrieved.
*   `fields` (query, array of string) A list of quote fields to return in the response.
    
    _Example_
    
    ```
    Quote.Status
    ```
    
    _Example_
    
    ```
    Quote.ExpirationDate
    ```
    
*   `effectiveAccountId` (query, string (Id), required) The user account ID used to fetch the associated quote details.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CommerceQuoteDetailRepresentation`.
    
    _Example: Example_ Example of all quotes associated with an account.
    
    ```
    {
      "fields": {
        "LastModifiedDate": {
          "dataName": "LastModifiedDate",
          "dataType": "xsd:dateTime",
          "label": "Last Modified Date",
          "text": "2025-11-24T10:17:37Z",
          "type": "datetime"
        },
        "ExpirationDate": {
          "dataName": "ExpirationDate",
          "dataType": "xsd:date",
          "label": "Expiration Date",
          "text": "2025-12-01",
          "type": "date"
        },
        "Subtotal": {
          "dataName": "Subtotal",
          "dataType": "xsd:double",
          "label": "Subtotal",
          "text": "5.0",
          "type": "currency"
        },
        "CreatedDate": {
          "dataName": "CreatedDate",
          "dataType": "xsd:dateTime",
          "label": "Created Date",
          "text": "2025-11-24T10:17:37Z",
          "type": "datetime"
        },
        "CurrencyIsoCode": {
          "dataName": "CurrencyIsoCode",
          "dataType": "xsd:string",
          "label": "Currency ISO Code",
          "text": "USD",
          "type": "picklist"
        },
        "LineItemCount": {
          "dataName": "LineItemCount",
          "dataType": "xsd:int",
          "label": "Line Items",
          "text": "1",
          "type": "int"
        }
      },
      "id": "0Q0LT0000007l2D0AQ",
      "lineItems": [
        {
          "fields": {
            "UnitPrice": {
              "dataName": "UnitPrice",
              "dataType": "xsd:double",
              "label": "Sales Price",
              "text": "5.0",
              "type": "currency"
            },
            "Subtotal": {
              "dataName": "Subtotal",
              "dataType": "xsd:double",
              "label": "Subtotal",
              "text": "5.0",
              "type": "currency"
            },
            "Quantity": {
              "dataName": "Quantity",
              "dataType": "xsd:double",
              "label": "Quantity",
              "text": "1.0",
              "type": "double"
            }
          },
          "id": "0QLLT000000DOKf4AO",
          "product": {
            "canViewProduct": null,
            "error": null,
            "fields": {
              "LastModifiedDate": {
                "dataName": "LastModifiedDate",
                "dataType": "STANDARD",
                "label": "LastModifiedDate",
                "text": "Mon Nov 24 09:58:13 GMT 2025",
                "type": "DATETIME"
              },
              "IsDeleted": {
                "dataName": "IsDeleted",
                "dataType": "STANDARD",
                "label": "IsDeleted",
                "text": "false",
                "type": "BOOLEAN"
              },
              "IsActive": {
                "dataName": "IsActive",
                "dataType": "STANDARD",
                "label": "IsActive",
                "text": "true",
                "type": "BOOLEAN"
              },
              "ProductPurpose": {
                "dataName": "ProductPurpose",
                "dataType": "STANDARD",
                "label": "ProductPurpose",
                "text": "Sell",
                "type": "PICKLIST"
              },
              "LastViewedDate": {
                "dataName": "LastViewedDate",
                "dataType": "STANDARD",
                "label": "LastViewedDate",
                "text": "Mon Nov 24 10:17:01 GMT 2025",
                "type": "DATETIME"
              },
              "LastReferencedDate": {
                "dataName": "LastReferencedDate",
                "dataType": "STANDARD",
                "label": "LastReferencedDate",
                "text": "Mon Nov 24 10:17:01 GMT 2025",
                "type": "DATETIME"
              },
              "CurrencyIsoCode": {
                "dataName": "CurrencyIsoCode",
                "dataType": "STANDARD",
                "label": "CurrencyIsoCode",
                "text": "USD",
                "type": "PICKLIST"
              },
              "Name": {
                "dataName": "Name",
                "dataType": "STANDARD",
                "label": "Name",
                "text": "prod1",
                "type": "STRING"
              },
              "SystemModstamp": {
                "dataName": "SystemModstamp",
                "dataType": "STANDARD",
                "label": "SystemModstamp",
                "text": "Mon Nov 24 09:58:14 GMT 2025",
                "type": "DATETIME"
              },
              "IsArchived": {
                "dataName": "IsArchived",
                "dataType": "STANDARD",
                "label": "IsArchived",
                "text": "false",
                "type": "BOOLEAN"
              },
              "CreatedById": {
                "dataName": "CreatedById",
                "dataType": "STANDARD",
                "label": "CreatedById",
                "text": "005LT000008mTXl",
                "type": "REFERENCE"
              },
              "CreatedDate": {
                "dataName": "CreatedDate",
                "dataType": "STANDARD",
                "label": "CreatedDate",
                "text": "Mon Nov 24 09:58:13 GMT 2025",
                "type": "DATETIME"
              },
              "ProductClass": {
                "dataName": "ProductClass",
                "dataType": "STANDARD",
                "label": "ProductClass",
                "text": "Simple",
                "type": "PICKLIST"
              },
              "LastModifiedById": {
                "dataName": "LastModifiedById",
                "dataType": "STANDARD",
                "label": "LastModifiedById",
                "text": "005LT000008mTXl",
                "type": "REFERENCE"
              }
            },
            "id": "01tLT00000A0Jw9YAF",
            "image": {
              "alternateText": "",
              "contentVersionId": null,
              "id": null,
              "mediaType": "Image",
              "sortOrder": 0,
              "thumbnailUrl": null,
              "title": "image",
              "url": "/img/b2b/default-product-image.svg"
            },
            "name": "prod1",
            "productClass": null,
            "purchaseQuantityRule": null,
            "sku": null,
            "success": true,
            "variationAttributes": []
          }
        }
      ],
      "notes": [
        {
          "content": "sds",
          "contentModifiedDate": "Mon Nov 24 10:17:37 GMT 2025",
          "createdBy": "Test User",
          "title": "Notes from User"
        }
      ],
      "quoteNumber": "00000046",
      "status": "Draft"
    }
    ```
    
*   **400** Bad Request - Invalid input parameters or request data.
    
    Media type: `application/json`. Schema: `CommerceQuoteDetailRepresentation`.
    
    _Example: InvalidQuoteId_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_INPUT",
          "message": "The specified quote ID is invalid."
        }
      ]
    }
    ```
    
    _Example: InvalidCustomFields_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_CUSTOM_FIELDS",
          "message": "One or more custom field values are invalid or don't meet required criteria."
        }
      ]
    }
    ```
    
*   **404** Not Found - Requested resource doesn't exist.
    
    Media type: `application/json`. Schema: `CommerceQuoteDetailRepresentation`.
    
    _Example: QuoteNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "QUOTE_NOT_FOUND",
          "message": "The specified quote doesn't exist or you do not have access to it."
        }
      ]
    }
    ```
    
    _Example: WebstoreNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "WEBSTORE_NOT_FOUND",
          "message": "The specified web store doesn't exist or you do not have access to it."
        }
      ]
    }
    ```
    
*   **500** Internal Server Error - Unexpected system error occurred.
    
    Media type: `application/json`. Schema: `CommerceQuoteDetailRepresentation`.
    
    _Example: InternalServerError_
    
    ```
    {
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "An unexpected error occurred while processing the request."
        }
      ]
    }
    ```
    

### PATCH Initiate a quote renegotiation or decline the quote. The API updates the status of an existing quote from Approved to Draft and saves the associated negotiation comments.

`PATCH /commerce/webstores/{webstoreId}/quotes/{quoteId}`

Operation ID: `updateQuote`.

This API is used on the My Quotes page of the B2B storefront to retrieve details of a specific quote record, including status, line items, and user comments.

This API initiates negotiation only when the quote status is Approved, as triggered by the Renegotiate or Decline action on the My Quotes page of the B2B storefront.

Updates quote status based on user action: changes Approved quotes back to Draft for renegotiation while saving comments, or sets status to Denied for rejected quotes.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the Webstore
    
    The ID of the web store.
    
*   `quoteId` (path, string (Id), required) The ID of the quote whose status is to be updated.

#### Request body (required)

Media type: `application/json`. Schema: `UpdateQuoteInputRepresentation`.

_Example_

```
{
  "status": "Draft",
  "note": {
    "title": "Quote submitted for renegotiation",
    "content": "Requesting a 20% discount on the quoted price."
  }
}
```

#### Responses

*   **204** Success. The quote status has been updated. No response body is returned.
*   **400** Bad Request - Invalid input parameters or request data.
    
    Media type: `application/json`. Schema: `ErrorResponseRepresentation`.
    
    _Example: InvalidStatus_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_INPUT",
          "message": "The provided status value is invalid or not allowed for this quote."
        }
      ]
    }
    ```
    
*   **404** Not Found - Requested resource doesn't exist.
    
    Media type: `application/json`. Schema: `ErrorResponseRepresentation`.
    
    _Example: QuoteNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "QUOTE_NOT_FOUND",
          "message": "The specified quote doesn't exist or isn't accessible."
        }
      ]
    }
    ```
    
    _Example: WebstoreNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "WEBSTORE_NOT_FOUND",
          "message": "The specified web store doesn't exist or isn't accessible."
        }
      ]
    }
    ```
    
*   **500** Internal Server Error - Unexpected system error occurred.
    
    Media type: `application/json`. Schema: `ErrorResponseRepresentation`.
    
    _Example: InternalServerError_
    
    ```
    {
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "An unexpected error occurred while processing the request"
        }
      ]
    }
    ```
    

### GET Retrieve all quotes associated with a given account.

`GET /commerce/webstores/{webstoreId}/quotes`

Operation ID: `getQuotes`.

This API is used on the My Quotes page of the B2B storefront to display a list of a buyer’s quotes.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store.
*   `fields` (query, array of string) A list of fields to include in the response. Supports fields from the Quote, Quote Line Item, and Product2 objects.
    
    _Example_
    
    ```
    Quote.Status
    ```
    
    _Example_
    
    ```
    Quote.ExpirationDate
    ```
    
*   `effectiveAccountId` (query, string (Id), required) The user account ID used to fetch the associated quote details.
*   `sort` (query, QuotesSortOrderEnum)
*   `pageToken` (query, string) Specifies the base64 encoded page token to use to view a page of information. Page tokens are pageToken String returned as part of the response, such as currentPageToken or nextPageToken. If you don’t specify a value, the first page is returned.
    
    _Example_
    
    ```
    eyJkIjoxNjAxODQ3MTcyMDAwLCJpIjoiMU9zeHgwMDAwMDAwMU44Q0FJIiwicyI6MiwicSI6Ik9yZGVyZWREYXRlRGVzYyJ9
    ```
    
*   `pageSize` (query, number) The number of items per page. Valid values are from 1 through 200. The default value is 25.
*   `earliestDate` (query, string (date-time)) The ISO 8601 date string for the oldest date from which to get quote records. Return quotes created on or after this date. Valid format: yyyy-MM-dd'T'HH:mm:ss.SSSZ.
    
    _Example_
    
    ```
    2023-01-01T00:00:00.000+0000
    ```
    
*   `latestDate` (query, string (date-time)) The ISO 8601 date string for the most recent date from which to get quote records. Return quotes created before this date. Valid format: yyyy-MM-dd'T'HH:mm:ss.SSSZ.
    
    _Example_
    
    ```
    2023-12-31T23:59:59.999+0000
    ```
    

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CommerceQuoteCollectionRepresentation`.
    
    _Example: Example_ Example of all quotes associated with an account.
    
    ```
    {
      "count": 1,
      "currentPageToken": null,
      "currentPageUrl": "/services/data/v66.0/commerce/webstores/0ZELT000000OuKP/quotes?effectiveAccountId=001LT00000w3S82&pageSize=10&sort=CreatedDateDesc",
      "errors": [],
      "nextPageToken": null,
      "nextPageUrl": null,
      "previousPageToken": null,
      "previousPageUrl": null,
      "quotes": [
        {
          "fields": {
            "LastModifiedDate": {
              "dataName": "LastModifiedDate",
              "dataType": "xsd:dateTime",
              "label": "Last Modified Date",
              "text": "2025-11-24T10:17:37Z",
              "type": "datetime"
            },
            "ExpirationDate": {
              "dataName": "ExpirationDate",
              "dataType": "xsd:date",
              "label": "Expiration Date",
              "text": "2025-12-01",
              "type": "date"
            },
            "Subtotal": {
              "dataName": "Subtotal",
              "dataType": "xsd:double",
              "label": "Subtotal",
              "text": "5.0",
              "type": "currency"
            },
            "CreatedDate": {
              "dataName": "CreatedDate",
              "dataType": "xsd:dateTime",
              "label": "Created Date",
              "text": "2025-11-24T10:17:37Z",
              "type": "datetime"
            },
            "CurrencyIsoCode": {
              "dataName": "CurrencyIsoCode",
              "dataType": "xsd:string",
              "label": "Currency ISO Code",
              "text": "USD",
              "type": "picklist"
            },
            "LineItemCount": {
              "dataName": "LineItemCount",
              "dataType": "xsd:int",
              "label": "Line Items",
              "text": "1",
              "type": "int"
            }
          },
          "id": "0Q0LT0000007l2D0AQ",
          "products": [
            {
              "canViewProduct": null,
              "error": null,
              "fields": {},
              "id": "01tLT00000A0Jw9YAF",
              "image": {
                "alternateText": "",
                "contentVersionId": null,
                "id": null,
                "mediaType": "Image",
                "sortOrder": 0,
                "thumbnailUrl": null,
                "title": "image",
                "url": "/img/b2b/default-product-image.svg"
              },
              "name": null,
              "productClass": null,
              "purchaseQuantityRule": null,
              "sku": null,
              "success": null,
              "variationAttributes": []
            }
          ],
          "quoteNumber": "00000046",
          "status": "Draft"
        }
      ]
    }
    ```
    
*   **400** Bad Request - Invalid input parameters or request data.
    
    Media type: `application/json`. Schema: `CommerceQuoteCollectionRepresentation`.
    
    _Example: InvalidEffectiveAccountId_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_INPUT",
          "message": "The specified effective account ID parameter is invalid."
        }
      ]
    }
    ```
    
    _Example: InvalidCustomFields_
    
    ```
    {
      "errors": [
        {
          "code": "INVALID_CUSTOM_FIELDS",
          "message": "One or more custom field values are invalid or do not meet required criteria."
        }
      ]
    }
    ```
    
*   **404** Not Found - Requested resource does not exist.
    
    Media type: `application/json`. Schema: `CommerceQuoteCollectionRepresentation`.
    
    _Example: QuoteNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "QUOTE_NOT_FOUND",
          "message": "The specified quote does not exist or is not accessible"
        }
      ]
    }
    ```
    
    _Example: WebstoreNotFound_
    
    ```
    {
      "errors": [
        {
          "code": "WEBSTORE_NOT_FOUND",
          "message": "The specified quote doesn't exist or you don't have access to it."
        }
      ]
    }
    ```
    
*   **500** Internal Server Error - Unexpected system error occurred.
    
    Media type: `application/json`. Schema: `CommerceQuoteCollectionRepresentation`.
    
    _Example: InternalServerError_
    
    ```
    {
      "errors": [
        {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "An unexpected error occurred while processing the request."
        }
      ]
    }
    ```
    

## Schemas

### CommerceQuoteDetailRepresentation

Unified representation containing the quote, quote line items, and product related fields.

Includes all fields of `CommerceQuoteBaseRepresentation`.

*   `lineItems` (_array of CommerceQuoteLineItemRepresentation_) A collection of quote line items associated with the specified quote.
*   `notes` (_array of CommerceNoteRepresentation_) A collection of notes exchanged between the buyer and sales representative.

### UpdateQuoteInputRepresentation

Input representation for updating a quote and/or creating an associated note.

*   `status` (_string_)
    
    A new status to be applied to the quote. Valid values:
    
    *   Draft: Renegotiate the quote.
    *   Denied: Decline the quote
    
    _Example_
    
    ```
    Draft
    ```
    
    _Example_
    
    ```
    Denied
    ```
    
*   `note` (_CommerceNoteRepresentation_)

### ErrorResponseRepresentation

ErrorResponseRepresentation

Representation of the error response.

*   `errorCode` (_string_) The error code.
    
    _Example_
    
    ```
    401
    ```
    
*   `message` (_string_) The message stating the reason for error, if any.
    
    _Example_
    
    ```
    Some error message
    ```
    
*   `errorEntityId` (_string_) The ID of the object associated with the error.
    
    _Example_
    
    ```
    02ixx0000004Hb4AAE
    ```
    

### QuotesSortOrderEnum

The sort order for quotes.

Type: `string`.

Allowed values: `CreatedDateAsc—Sorts by the oldest created date.`, `CreatedDateDesc—Sorts by the most recent created date.`.

### CommerceQuoteCollectionRepresentation

Unified representation of all quotes associated with an account, including success response and array-based errors.

*   `nextPageUrl` (_string_) The URL identifying the next page, or null if there isn’t a next page.
    
    _Example_
    
    ```
    /services/data/v66.0/commerce/webstores/0ZExx000000004r/quotes?effectiveAccountId=001xx000003GZ1X&pageSize=2&pageToken=eyJkYXRlIjoxNzU4NzIyMjUyMDAwLCJpZCI6IjBRMHh4MDAwMDAwNENDR0NBMiIsInF1ZXJ5U29ydE9yZGVyIjoiQ3JlYXRlZERhdGVEZXNjIn0%3D&sort=CreatedDateAsc
    ```
    
*   `nextPageToken` (_string_) The token identifying the next page, or null if there isn’t a next page.
    
    _Example_
    
    ```
    eyJkIjoxNjAxODQ3MTcyMDAwLCJpIjoiMU9zeHgwMDARTYUMU44Q0FJIiwicyI6MiwicSI6Ik9yZGVyZWREYXRlRGVzYyJ9
    ```
    
*   `previousPageUrl` (_string_) The URL identifying the previous page, or null if there isn’t a previous page.
    
    _Example_
    
    ```
    /services/data/v66.0/commerce/webstores/0ZExx000000004r/quotes?effectiveAccountId=001xx000003GZ1X&pageSize=2&pageToken=eyJkYXRlIjoxNzU4NzIyMjUyMDAwLCJpZCI6IjBRMHh4MDAwMDAwNENDR0NBMiIsInF1ZXJ5U29ydE9yZGVyIjoiQ3JlYXRlZERhdGVEZXNjIn0%3D&sort=CreatedDateAsc
    ```
    
*   `previousPageToken` (_string_) The token identifying the previous page, or null if there isn’t a previous page.
    
    _Example_
    
    ```
    eyJkIjoxNjAxODQ3MTcyMDAwLCJpIjoiMU9zeHgwMDAwMDAwMU44Q0FJIiwicyI6MiwicSI6Ik9yZGWERTYRlRGVzYyJ9
    ```
    
*   `currentPageUrl` (_string_) The URL identifying the current page.
    
    _Example_
    
    ```
    /services/data/v66.0/commerce/webstores/0ZExx000000004r/quotes?effectiveAccountId=001xx000003GZ1X&pageSize=2&pageToken=eyJkYXRlIjoxNzU4NzIyMjUyMDAwLCJpZCI6IjBRMHh4MDAwMDAwNENDR0NBMiIsInF1ZXJ5U29ydE9yZGVyIjoiQ3JlYXRlZERhdGVEZXNjIn0%3D&sort=CreatedDateAsc
    ```
    
*   `currentPageToken` (_string_) The token identifying the current page.
    
    _Example_
    
    ```
    eyJkIjoxNjAxODQ3MTcyMDAwLCJpIjoiMU9zeHgwMDAwMDAwMU44Q0FJIiwicyI6MiwicSI6Ik9yZGVyZWREYXRlRGVzYyJ9
    ```
    
*   `quotes` (_array of object_) A collection of quotes corresponding with a user account.
    
    Includes all fields of `CommerceQuoteBaseRepresentation`.
    
    *   `products` (_array of BuyerProductSummaryRepresentation_)
*   `errors` (_array of ErrorResponseRepresentation_) List of errors encountered during quote creation. Returns an empty array on success.

### CommerceQuoteBaseRepresentation

Unified representation of quote-related fields.

*   `id` (_string (Id)_, nullable) The ID of the quote, returned on success or null on error.
*   `quoteNumber` (_string_) The quote reference number of the quote.
    
    _Example_
    
    ```
    EBDMO-WJLPM-SDFHA-4CV4D
    ```
    
*   `status` (_string_) The status of the quote.
    
    _Example_
    
    ```
    Complete
    ```
    
*   `fields` (_object_)
    
    fields
    
    The quote record fields to be retrieved.
    
    _Example_
    
    ```
    {
      "ExpirationDate": {
        "Label": "Expiration Date",
        "Type": "datetime",
        "Text": "2024-12-10T11:54:32.000Z"
      },
      "Status": {
        "Label": "Status",
        "Type": "picklist",
        "Text": "Created"
      }
    }
    ```
    

### CommerceQuoteLineItemRepresentation

Representation for quote line item summary lookup.

*   `id` (_string_) The ID of the quote line item.
    
    _Example_
    
    ```
    10uxx0000004EOJAA2
    ```
    
*   `fields` (_object_)
    
    fields
    
    A list of quote line item fields to return in the response.
    
    _Example_
    
    ```
    {
      "Quantity": {
        "Label": "Quantity",
        "Type": "Double",
        "Text": 5
      },
      "UnitPrice": {
        "Label": "Unit Price",
        "Type": "Currency",
        "Text": 100
      }
    }
    ```
    
*   `product` (_BuyerProductSummaryRepresentation_)

### CommerceNoteRepresentation

Representation of notes on the quote.

*   `title` (_string_) The title of the note.
    
    _Example_
    
    ```
    Negotiation Request
    ```
    
*   `content` (_string_) The comments from both the buyer and sales representative on a specific quote.
    
    _Example_
    
    ```
    Please provide bulk pricing for 100+ units
    ```
    
*   `createdBy` (_string_) For internal use only. The name of the user who created the note.
    
    _Example_
    
    ```
    James Adam
    ```
    
*   `contentModifiedDate` (_string (datetime)_) For internal use only. The timestamp indicating when the content was last modified.

### BuyerProductSummaryRepresentation

BuyerProductSummaryRepresentation

Representation of the buyer product summary.

*   `id` (_string (uuid)_) The ID of the product.
    
    _Example_
    
    ```
    64bf835f-ada9-4538-b5a3-f4ed8672c7b5
    ```
    
*   `name` (_string_) The name of the product.
    
    _Example_
    
    ```
    Alpine Creative Suite
    ```
    
*   `sku` (_string_) The Stock Keeping Unit (SKU) of the product.
    
    _Example_
    
    ```
    #421234
    ```
    
*   `fields` (_object_) A collection of additional fields from the Product2 object.
    
    Additional properties: `RecordFieldRepresentation`.
    
*   `image` (_ProductMediaRepresentation_) The media details associated with a product.
*   `variationAttributes` (_array of ProductAttributeSummaryRepresentation_) A list of variation attributes (color, size, and so on) associated with the product.
*   `canViewProduct` (_boolean_) Indicates whether the context user can view the product (true) or not (false).
    
    _Example_
    
    ```
    true
    ```
    
*   `success` (_boolean_) Indicates whether the request was successful (true) or not (false).
    
    _Example_
    
    ```
    true
    ```
    
*   `error` (_ErrorResponseRepresentation_) Error response representation for buyer product summary.

### RecordFieldRepresentation

RecordFieldRepresentation

Representation of a generic record field containing a label and text value.

*   `type` (_string_) The type of the record field.
    
    _Example_
    
    ```
    string
    ```
    
    _Example_
    
    ```
    int
    ```
    
    _Example_
    
    ```
    currency
    ```
    
*   `label` (_string_) The label for the record field.
    
    _Example_
    
    ```
    Account
    ```
    
    _Example_
    
    ```
    Billing
    ```
    
    _Example_
    
    ```
    Address
    ```
    
    _Example_
    
    ```
    Status
    ```
    
*   `dataName` (_string_) The data name associated with the record field.
    
    _Example_
    
    ```
    isBuyer
    ```
    
*   `dataType` (_string_) The data type of the record field.
    
    _Example_
    
    ```
    xsd:string
    ```
    
*   `text` (_string_) The text value of the field. All record fields have a text value. To ensure that all clients can consume new content, inspect the record field’s type property. If it isn’t recognized, render the text value as the default case.
    
    _Example_
    
    ```
    Created
    ```
    
    _Example_
    
    ```
    34
    ```
    

### ProductMediaRepresentation

ProductMediaRepresentation

Representation of the media associated with a product.

*   `id` (_string (uuid)_) The ID of the product image.
    
    _Example_
    
    ```
    64bf835f-ada9-4538-b5a3-f4ed8672c7b5
    ```
    
*   `url` (_string (uri)_) The URL of the product media.
    
    _Example_
    
    ```
    /cms/delivery/media/MC2KSOOFJGRZDDJGQG4QJHLKHTZQ?recordId=01tRO000000FVNB&buyerId=001RO000001npBo
    ```
    
*   `thumbnailUrl` (_string (uri)_) The URL of the thumbnail for product media. If a value exists, it should be used for the thumbnail whether the image is natively uploaded or hosted externally. Not supported in enhanced CMS workspaces.
    
    _Example_
    
    ```
    /img/b2b/default-thumbnail-product-image.svg
    ```
    
*   `title` (_string_) The title of the product media.
    
    _Example_
    
    ```
    tshirt 5
    ```
    
*   `alternateText` (_string_) The alternative text for the product media.
    
    _Example_
    
    ```
    Pack of TShirt, 2oz - 6 pack
    ```
    
*   `sortOrder` (_integer_) The sort order of a media item within a media group.
    
    _Example_
    
    ```
    0
    ```
    
*   `mediaType` (_string_)  
    Allowed values: `IMAGE`, `VIDEO`, `DOCUMENT`.
*   `contentVersionId` (_string (uuid)_) The ID of the latest published content version if the media is stored as a ContentDocument. If the image is a customer-provided external URL, the value is null. Not supported in enhanced CMS workspaces.

### ProductAttributeSummaryRepresentation

ProductAttributeSummaryRepresentation

Representation of a product attribute summary.

*   `apiName` (_string_) The API name of the product attribute.
    
    _Example_
    
    ```
    size
    ```
    
*   `label` (_string_) The display label of the product attribute.
    
    _Example_
    
    ```
    Size
    ```
    
*   `value` (_string_) The display value of the product attribute.
    
    _Example_
    
    ```
    Medium
    ```
    
*   `sequence` (_integer_) The sequence of the attribute in the attribute set.
    
    _Example_
    
    ```
    1
    ```

<!-- document id=78a5ab79e4f4efb657861a27b0971608eb63b1e612edd42dccbea5a3cf0797e2 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-product-search-category-pinning-rules-ref.md -->

Salesforce Commerce Search Category Pinning Rules API

# Salesforce Commerce Search Category Pinning Rules API

Use category pinning rules to pin specific products to fixed positions on a category's browse-results page. When a shopper browses the category, pinned products appear at the configured positions regardless of the default sort order.

**Version:** v67.0

## Servers

*   `https://api.salesforce.com/services/data/{version}`
    *   `version (default v67.0): v67.0 Salesforce API version`

## Operations

### GET Get category pinning rules

`GET /commerce/management/webstores/{webstoreId}/search/category-pinning-rules`

Operation ID: `getSearchCategoryPinningRules`. Tags: CategoryPinningRulesCollection.

Collection of category pinning rules configured for a web store.

Returns a paginated list of category pinning rules for the specified web store. To page through results, pass `pageSize` and `pageToken`. Get `pageToken` from the `pageToken=` query parameter in the previous response's `nextPageUrl` and use that value, not the full URL. Each response includes the `count`, `currentPageUrl`, `nextPageUrl`, and `sortOrder` fields alongside the `categoryPinningRules` array. On the last page, `nextPageUrl` is `null`. A web store can have up to 100 category pinning rules, so a request with `pageSize=100` returns a web store's rules in a single page.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `pageToken` (query, string) Opaque cursor that identifies the page of results to return. To get the next page, use the `pageToken` value from the previous response's `nextPageUrl`. If you don't specify a value, the first page is returned.
*   `pageSize` (query, integer) Number of rules to return per page. Valid values are from 1 through 100. If you don't specify a value, the default size is 50.  
    Default: `50`. Minimum: 1. Maximum: 100. Example: `50`.

#### Responses

*   **200** The web store's category pinning rules. Returns an empty `categoryPinningRules` array when the web store has no rules.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRulesCollectionOutputRepresentation`.
    
    _Example: CollectionResponse_ Collection of category pinning rules
    
    ```
    {
      "categoryPinningRules": [
        {
          "id": "1pJxx0000004C92EAE",
          "name": "Holiday Drill Promotion",
          "categoryId": "0ZGxx0000004CaGGAU",
          "locales": [
            "en_US"
          ],
          "active": true,
          "startDate": "2026-12-01T00:00:00.000Z",
          "endDate": "2026-12-31T23:59:59.000Z",
          "pins": [
            {
              "pinnedProductId": "01txx0000006i2SAAQ",
              "position": 1
            },
            {
              "pinnedProductId": "01txx0000006i2TAAQ",
              "position": 2
            }
          ]
        }
      ],
      "count": 1,
      "currentPageUrl": "/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules?pageSize=50",
      "nextPageUrl": null,
      "sortOrder": "createdDate ASC"
    }
    ```
    
    _Example: EmptyCollectionResponse_ Web store has no category pinning rules
    
    ```
    {
      "categoryPinningRules": [],
      "count": 0,
      "currentPageUrl": "/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules?pageSize=50",
      "nextPageUrl": null,
      "sortOrder": "createdDate ASC"
    }
    ```
    
*   **400** The request failed validation of a pagination parameter. `errorCode` is `INVALID_API_INPUT` when `pageToken` can't be decoded, or `LIMIT_EXCEEDED` when `pageSize` is outside the range 1–100.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InvalidPageToken_ pageToken value isn't a valid pagination cursor
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a valid page token. The value 'not-base64!' isn't a valid pagination cursor; pass a token returned in a previous response's nextPageUrl, or omit the parameter to start from the first page."
      }
    ]
    ```
    
    _Example: PageSizeOutOfRange_ pageSize is outside the range 1–100
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "Specify a pageSize from 1 through 100. The value specified was 0."
      }
    ]
    ```
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The specified web store ID wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### POST Create a category pinning rule

`POST /commerce/management/webstores/{webstoreId}/search/category-pinning-rules`

Operation ID: `createSearchCategoryPinningRule`. Tags: CategoryPinningRulesCollection.

Collection of category pinning rules configured for a web store.

Creates a category pinning rule for the specified web store. A web store can have up to 100 category pinning rules. When the web store reaches this limit, the request fails with `errorCode: LIMIT_EXCEEDED`, and you must delete a rule before you can create another. Each category can have only one rule; creating a second rule for the same category fails with `errorCode: DUPLICATE_VALUE`.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.

#### Request body (required)

Media type: `application/json`. Schema: `SearchCategoryPinningRuleInputRepresentation`.

_Example: CreateCategoryPinningRule_ Create a category pinning rule

```
{
  "name": "Holiday Drill Promotion",
  "categoryId": "0ZGxx0000004CaGGAU",
  "locales": [
    "en_US"
  ],
  "active": true,
  "startDate": "2026-12-01T00:00:00.000Z",
  "endDate": "2026-12-31T23:59:59.000Z",
  "pins": [
    {
      "pinnedProductId": "01txx0000006i2SAAQ",
      "position": 1
    },
    {
      "pinnedProductId": "01txx0000006i2TAAQ",
      "position": 2
    }
  ]
}
```

#### Responses

*   **201** The category pinning rule that was created.
    
    Headers:
    
    *   `Location` (string (url), required)  
        Example: `https://api.salesforce.com/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules/1pJxx0000004C92EAE`.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRuleOutputRepresentation`.
    
    _Example: CreatedRule_ Created category pinning rule
    
    ```
    {
      "id": "1pJxx0000004C92EAE",
      "name": "Holiday Drill Promotion",
      "categoryId": "0ZGxx0000004CaGGAU",
      "locales": [
        "en_US"
      ],
      "active": true,
      "startDate": "2026-12-01T00:00:00.000Z",
      "endDate": "2026-12-31T23:59:59.000Z",
      "pins": [
        {
          "pinnedProductId": "01txx0000006i2SAAQ",
          "position": 1
        },
        {
          "pinnedProductId": "01txx0000006i2TAAQ",
          "position": 2
        }
      ]
    }
    ```
    
*   **400**
    
    The request failed validation. `errorCode` indicates the cause:
    
    *   `REQUIRED_FIELD_MISSING`—a required field is missing or empty - `MALFORMED_ID`—a Salesforce ID isn't a valid 18-character ID - `LIMIT_EXCEEDED`—a limit was exceeded, such as the maximum number of pins or rules
    *   `DUPLICATE_VALUE`—a uniqueness constraint was violated, such as a duplicate rule name, pin position, or pinned product
    *   `INVALID_API_INPUT`—another input check failed, such as a length, range, date, or locale check
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InvalidRuleDefinition_ One or more required fields are missing from the rule
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the category pinning rule input are missing."
      }
    ]
    ```
    
    _Example: MissingRequiredField_ A required field is missing from the rule
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "The required field name is missing for the category pinning rule. Provide a value and try again."
      }
    ]
    ```
    
    _Example: EmptyPins_ The rule has no pins
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "Specify at least one pinned product for the category pinning rule."
      }
    ]
    ```
    
    _Example: NameTooLong_ Rule name exceeds maximum length (80 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category pinning rule name is too long. The maximum length is 80 characters."
      }
    ]
    ```
    
    _Example: CategoryIdTooLong_ Category ID exceeds maximum length (18 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category identifier is too long. The maximum length is 18 characters."
      }
    ]
    ```
    
    _Example: InvalidCategoryId_ Category ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce category identifier. The value '0ZGxxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: PastEndDate_ End date is in the past
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify an end date that's in the future."
      }
    ]
    ```
    
    _Example: InvalidDateRange_ Start date isn't before end date
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a start date that's earlier than the end date."
      }
    ]
    ```
    
    _Example: MaxPinsExceeded_ Exceeded maximum number of pins per rule (10)
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "A category pinning rule can have at most 10 pinned items."
      }
    ]
    ```
    
    _Example: MaxRulesPerWebstore_ Web store already has the maximum number of category pinning rules (100)
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "You can configure up to 100 category pinning rules per web store. Delete an existing rule before creating another."
      }
    ]
    ```
    
    _Example: InvalidPin_ A pin is missing a required field
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the pinned item are missing."
      }
    ]
    ```
    
    _Example: InvalidPinPosition_ Pin position is outside the range 1–10
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a pin position from 1 through 10. The value specified was 11."
      }
    ]
    ```
    
    _Example: DuplicatePinPosition_ Duplicate positions within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Pin position 1 is used more than once. Each position must be unique within a rule."
      }
    ]
    ```
    
    _Example: DuplicatePinProduct_ Duplicate product IDs within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Product 01txx0000006i2SAAQ is pinned more than once. Each product can be pinned only once within a rule."
      }
    ]
    ```
    
    _Example: InvalidPinProductId_ Pinned product ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce product identifier. The value '01txxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: InvalidLocale_ Locale isn't in underscore format, such as en\_US
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a valid locale in underscore format (for example, en_US). Hyphenated BCP47 tags aren't accepted."
      }
    ]
    ```
    
    _Example: DuplicateRuleName_ Another rule in the same web store already uses this name
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "The name specified for the category pinning rule conflicts with an existing rule in this web store. Specify a unique name."
      }
    ]
    ```
    
    _Example: DuplicateRuleForCategory_ Another rule in the same web store already targets this category
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "A category pinning rule already exists for category '0ZGxx0000004CaGGAU' in this web store. Delete or update the existing rule before creating another for the same category."
      }
    ]
    ```
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The specified web store ID wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### GET Get a category pinning rule

`GET /commerce/management/webstores/{webstoreId}/search/category-pinning-rules/{ruleId}`

Operation ID: `getSearchCategoryPinningRule`. Tags: CategoryPinningRule.

Manage a single category pinning rule by its ID.

Returns a category pinning rule for the specified web store.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `ruleId` (path, string (Id), required) The ID of the category pinning rule to operate on.  
    Example: `1pJxx0000004C92EAE`.

#### Responses

*   **200** The requested category pinning rule.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRuleOutputRepresentation`.
    
    _Example SingleRule: same as POST /commerce/management/webstores/{webstoreId}/search/category-pinning-rules 201 response._ A single category pinning rule
    
    _Example: SingleRule_ A single category pinning rule
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The category pinning rule or web store wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
    _Example: RuleNotFound_ Rule ID doesn't exist or doesn't belong to this web store
    
    ```
    [
      {
        "errorCode": "NOT_FOUND",
        "message": "Enter a valid category pinning rule ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### PUT Replace a category pinning rule

`PUT /commerce/management/webstores/{webstoreId}/search/category-pinning-rules/{ruleId}`

Operation ID: `updateSearchCategoryPinningRule`. Tags: CategoryPinningRule.

Manage a single category pinning rule by its ID.

Replaces a category pinning rule for the specified web store. Include the complete rule in the request body (`name`, `categoryId`, `active`, `startDate`, `endDate`, and `pins`). A partial body fails validation. The same `categoryId` and `pins` rules as create apply, including the one-rule-per-category limit. Optional fields are replaced, not merged. If you omit `locales`, the rule resets to all locales instead of keeping the stored value. If the rule's `endDate` is already in the past, send back the same `endDate` value. Sending a different past `endDate` fails validation. This way, you can correct an expired promotion without extending its dates.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `ruleId` (path, string (Id), required) The ID of the category pinning rule to operate on.  
    Example: `1pJxx0000004C92EAE`.

#### Request body (required)

Media type: `application/json`. Schema: `SearchCategoryPinningRuleInputRepresentation`.

_Example: UpdateCategoryPinningRule_ Update a category pinning rule (full replace)

```
{
  "name": "Holiday Drill Promotion - Extended",
  "categoryId": "0ZGxx0000004CaGGAU",
  "locales": [
    "en_US"
  ],
  "active": true,
  "startDate": "2026-12-01T00:00:00.000Z",
  "endDate": "2027-01-15T23:59:59.000Z",
  "pins": [
    {
      "pinnedProductId": "01txx0000006i2SAAQ",
      "position": 1
    },
    {
      "pinnedProductId": "01txx0000006i2TAAQ",
      "position": 2
    },
    {
      "pinnedProductId": "01txx0000006i2UAAQ",
      "position": 3
    }
  ]
}
```

#### Responses

*   **200** The category pinning rule that was updated.
    
    Media type: `application/json`. Schema: `SearchCategoryPinningRuleOutputRepresentation`.
    
    _Example: UpdatedRule_ Updated category pinning rule
    
    ```
    {
      "id": "1pJxx0000004C92EAE",
      "name": "Holiday Drill Promotion - Extended",
      "categoryId": "0ZGxx0000004CaGGAU",
      "locales": [
        "en_US"
      ],
      "active": true,
      "startDate": "2026-12-01T00:00:00.000Z",
      "endDate": "2027-01-15T23:59:59.000Z",
      "pins": [
        {
          "pinnedProductId": "01txx0000006i2SAAQ",
          "position": 1
        },
        {
          "pinnedProductId": "01txx0000006i2TAAQ",
          "position": 2
        },
        {
          "pinnedProductId": "01txx0000006i2UAAQ",
          "position": 3
        }
      ]
    }
    ```
    
*   **400** The request failed validation. A replace runs the same checks as create and returns the same `errorCode` values (`REQUIRED_FIELD_MISSING`, `MALFORMED_ID`, `LIMIT_EXCEEDED`, `DUPLICATE_VALUE`, or `INVALID_API_INPUT`). See the create (POST) response for what each code means.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example DuplicateRuleForCategory: same as POST /commerce/management/webstores/{webstoreId}/search/category-pinning-rules 400 response._ Another rule in the same web store already targets this category
    
    _Example: InvalidRuleDefinition_ One or more required fields are missing from the rule
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the category pinning rule input are missing."
      }
    ]
    ```
    
    _Example: NameTooLong_ Rule name exceeds maximum length (80 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category pinning rule name is too long. The maximum length is 80 characters."
      }
    ]
    ```
    
    _Example: CategoryIdTooLong_ Category ID exceeds maximum length (18 characters)
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "The category identifier is too long. The maximum length is 18 characters."
      }
    ]
    ```
    
    _Example: InvalidCategoryId_ Category ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce category identifier. The value '0ZGxxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: PastEndDate_ End date is in the past
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify an end date that's in the future."
      }
    ]
    ```
    
    _Example: InvalidDateRange_ Start date isn't before end date
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a start date that's earlier than the end date."
      }
    ]
    ```
    
    _Example: MaxPinsExceeded_ Exceeded maximum number of pins per rule (10)
    
    ```
    [
      {
        "errorCode": "LIMIT_EXCEEDED",
        "message": "A category pinning rule can have at most 10 pinned items."
      }
    ]
    ```
    
    _Example: InvalidPin_ A pin is missing a required field
    
    ```
    [
      {
        "errorCode": "REQUIRED_FIELD_MISSING",
        "message": "One or more required fields in the pinned item are missing."
      }
    ]
    ```
    
    _Example: InvalidPinPosition_ Pin position is outside the range 1–10
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a pin position from 1 through 10. The value specified was 11."
      }
    ]
    ```
    
    _Example: DuplicatePinPosition_ Duplicate positions within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Pin position 1 is used more than once. Each position must be unique within a rule."
      }
    ]
    ```
    
    _Example: DuplicatePinProduct_ Duplicate product IDs within the pins array
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "Product 01txx0000006i2SAAQ is pinned more than once. Each product can be pinned only once within a rule."
      }
    ]
    ```
    
    _Example: InvalidPinProductId_ Pinned product ID isn't a valid 18-character Salesforce ID
    
    ```
    [
      {
        "errorCode": "MALFORMED_ID",
        "message": "Specify a valid Salesforce product identifier. The value '01txxx' isn't a valid 18-character ID."
      }
    ]
    ```
    
    _Example: InvalidLocale_ Locale isn't in underscore format, such as en\_US
    
    ```
    [
      {
        "errorCode": "INVALID_API_INPUT",
        "message": "Specify a valid locale in underscore format (for example, en_US). Hyphenated BCP47 tags aren't accepted."
      }
    ]
    ```
    
    _Example: DuplicateRuleName_ Another rule in the same web store already uses this name
    
    ```
    [
      {
        "errorCode": "DUPLICATE_VALUE",
        "message": "The name specified for the category pinning rule conflicts with an existing rule in this web store. Specify a unique name."
      }
    ]
    ```
    
    _Example: DuplicateRuleForCategory_ Another rule in the same web store already targets this category
    
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The category pinning rule or web store wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
    _Example: RuleNotFound_ Rule ID doesn't exist or doesn't belong to this web store
    
    ```
    [
      {
        "errorCode": "NOT_FOUND",
        "message": "Enter a valid category pinning rule ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

### DELETE Delete a category pinning rule

`DELETE /commerce/management/webstores/{webstoreId}/search/category-pinning-rules/{ruleId}`

Operation ID: `deleteSearchCategoryPinningRule`. Tags: CategoryPinningRule.

Manage a single category pinning rule by its ID.

Deletes a category pinning rule for the specified web store.

#### Parameters

*   `webstoreId` (path, string (Id), required) The ID of the web store to operate on.  
    Example: `0ZExx000000004sGAA`.
*   `ruleId` (path, string (Id), required) The ID of the category pinning rule to operate on.  
    Example: `1pJxx0000004C92EAE`.

#### Responses

*   **204** The category pinning rule was deleted.
*   **403** The user doesn't have merchandiser permission, or category pinning isn't enabled for the org.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: InsufficientAccess_ User isn't a store merchandiser
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org doesn't have the required privileges."
      }
    ]
    ```
    
    _Example: FeatureNotEnabled_ Category pinning isn't enabled for the org
    
    ```
    [
      {
        "errorCode": "INSUFFICIENT_ACCESS",
        "message": "You or your org don't have access to this feature."
      }
    ]
    ```
    
*   **404** The category pinning rule or web store wasn't found.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: WebStoreNotFound_ Web store ID not found
    
    ```
    [
      {
        "errorCode": "WEBSTORE_NOT_FOUND",
        "message": "Specify a valid WebStore ID."
      }
    ]
    ```
    
    _Example: RuleNotFound_ Rule ID doesn't exist or doesn't belong to this web store
    
    ```
    [
      {
        "errorCode": "NOT_FOUND",
        "message": "Enter a valid category pinning rule ID."
      }
    ]
    ```
    
*   **500** An unexpected error occurred on the server.
    
    Media type: `application/json`. Schema: `ErrorRepresentationList`.
    
    _Example: UnknownException_ Unexpected error
    
    ```
    [
      {
        "errorCode": "UNKNOWN_EXCEPTION",
        "message": "An internal error occurred while processing this request."
      }
    ]
    ```
    

## Schemas

### SearchCategoryPinningRulesCollectionOutputRepresentation

A paginated list of category pinning rules for a web store. `categoryPinningRules` is always present, and is an empty array when the web store has no rules or the requested page is past the end of the list. The `count`, `currentPageUrl`, `nextPageUrl`, and `sortOrder` fields are always present, and `nextPageUrl` is `null` on the last page. Because a web store can have up to 100 rules, a request with `pageSize=100` returns all of them in one page.

*   `categoryPinningRules` (_array of SearchCategoryPinningRuleOutputRepresentation_, required) The category pinning rules on this page.
*   `count` (_integer_, required) Number of rules on this page.  
    Example: `1`.
*   `currentPageUrl` (_string_, required) URL of the current page, including the resolved `pageToken` and `pageSize` query parameters. Always present on a successful response.  
    Example: `/services/data/v67.0/commerce/management/webstores/0ZExx000000004sGAA/search/category-pinning-rules?pageSize=50`.
*   `nextPageUrl` (_string_, required, nullable) The URL of the next page, or `null` when there are no more rules.
*   `sortOrder` (_string_, required) Sort order applied to the list. Currently always `createdDate ASC`. Additional sort orders might be supported in future API versions.  
    Example: `createdDate ASC`.

### ErrorRepresentationList

Error response returned on every unsuccessful request. It's a JSON array that contains a single error object—for example, `[{ "errorCode": "DUPLICATE_VALUE", "message": "..." }]`.

Array of `ErrorRepresentation`.

Minimum items: 1. Maximum items: 1.

### SearchCategoryPinningRuleInputRepresentation

The category pinning rule to create or replace.

*   `name` (_string_, required) The name of the category pinning rule. Must be unique within the web store. Maximum length is 80 characters.  
    Minimum length: 1. Maximum length: 80. Example: `Holiday Drill Promotion`.
*   `categoryId` (_string (Id)_, required) The ID of the category that the rule applies to. Must be a valid 18-character Salesforce ID for a product category. Each category can have only one rule.  
    Example: `0ZGxx0000004CaGGAU`.
*   `locales` (_array of string_) Locale codes that the rule applies to, in underscore format, such as `en_US`. Hyphenated BCP47 tags aren't accepted. An empty or omitted list applies the rule to all locales. On replace (PUT), omitting `locales` resets the rule to all locales instead of keeping the stored value.  
    Items: Maximum length: 10. Maximum items: 50.
    
    _Example_
    
    ```
    [
      "en_US"
    ]
    ```
    
*   `active` (_boolean_, required) Indicates whether the category pinning rule is active.  
    Example: `true`.
*   `startDate` (_string (date-time)_, required) The start date and time of the rule, in ISO 8601 format. A past start date is allowed on create and update.  
    Example: `2026-12-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_, required) The end date and time of the rule, in ISO 8601 format. Must be after `startDate`. On create, the date must be in the future. On update, a past end date is rejected only if it differs from the stored value, so you can edit an expired rule without extending its dates.  
    Example: `2026-12-31T23:59:59.000Z`.
*   `pins` (_array of CategoryPinningRulePinInputRepresentation_, required) Ordered list of products to pin and their positions. Include 1 to 10 pins. Each position must be from 1 through 10 and unique within the rule, and each product can be pinned only once.  
    Minimum items: 1. Maximum items: 10.

### SearchCategoryPinningRuleOutputRepresentation

A category pinning rule.

*   `id` (_string (Id)_, required) The ID of the category pinning rule.  
    Example: `1pJxx0000004C92EAE`.
*   `name` (_string_, required) Name of the category pinning rule.  
    Example: `Holiday Drill Promotion`.
*   `categoryId` (_string (Id)_, required) The ID of the category that the rule applies to.  
    Example: `0ZGxx0000004CaGGAU`.
*   `locales` (_array of string_) Locale codes that the rule applies to, in underscore format, such as `en_US`. An empty list means the rule applies to all locales.
    
    _Example_
    
    ```
    [
      "en_US"
    ]
    ```
    
*   `active` (_boolean_, required) Indicates whether the category pinning rule is active.  
    Example: `true`.
*   `startDate` (_string (date-time)_, required) The start date and time of the category pinning rule, in ISO 8601 format.  
    Example: `2026-12-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_, required) The end date and time of the category pinning rule, in ISO 8601 format.  
    Example: `2026-12-31T23:59:59.000Z`.
*   `pins` (_array of CategoryPinningRulePinOutputRepresentation_, required) Ordered list of pinned products and their positions for this category.

### ErrorRepresentation

A single error returned in the error response array.

*   `errorCode` (_string_, required) Code that identifies the error condition. The client-error codes `INVALID_API_INPUT`, `REQUIRED_FIELD_MISSING`, `MALFORMED_ID`, `LIMIT_EXCEEDED`, and `DUPLICATE_VALUE` map to HTTP 400, so you can handle a specific failure without parsing the message text.  
    Allowed values: `WEBSTORE_NOT_FOUND`, `NOT_FOUND`, `INSUFFICIENT_ACCESS`, `INVALID_API_INPUT`, `REQUIRED_FIELD_MISSING`, `MALFORMED_ID`, `LIMIT_EXCEEDED`, `DUPLICATE_VALUE`, `UNKNOWN_EXCEPTION`.
*   `message` (_string_, required) Description of the error and how to resolve it.  
    Example: `Specify a valid WebStore ID.`.

### CategoryPinningRulePinInputRepresentation

A product to pin and its position.

*   `pinnedProductId` (_string (Id)_, required) The ID of the product to pin in the category's result list. Must be a valid 18-character Salesforce ID. A product can be pinned only once within a rule.  
    Example: `01txx0000006i2SAAQ`.
*   `position` (_integer_, required) Position in the category's result list where the product is pinned, from 1 through 10. Must be unique within the rule.  
    Minimum: 1. Maximum: 10. Example: `1`.

### CategoryPinningRulePinOutputRepresentation

A pinned product and its position.

*   `pinnedProductId` (_string (Id)_, required) The ID of the pinned product.  
    Example: `01txx0000006i2SAAQ`.
*   `position` (_integer_, required) Position where the product is pinned in the category's result list, from 1 through 10.  
    Minimum: 1. Maximum: 10. Example: `1`.

<!-- document id=223a792b0b994070ae7c40dab926a94d2933f3163e1f55c9566babdceb667ab1 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-search-settings-apis.md -->

# Salesforce Commerce Search Settings API

The Salesforce Commerce Search Settings APIs assist in managing and optimizing search functionality within the B2B Commerce platform. These APIs are categorized for both the shopper's experience and the administrative setup. Key functionalities include configuring search indexes, handling search suggestions, performing product searches, and managing search-related attributes.

## Search Settings APIs for Store Management

To effectively use the Search Settings APIs, set up your products by creating them, defining custom attributes, and importing them into the store.

The Facetable Attributes API defines which product attributes can be used as facets in search results. Attributes like category, brand, size, and color are displayed in the left-hand navigation on the Product Listing Page (PLP), helping users refine their search results.

The Searchable Attributes API specifies which attributes are searchable. Not all product attributes are relevant for text searches. For example, if you type "shirt" in the search box, this API determines which fields must be searched for that word.

The Sort Rules API enables sorting of search results, which is useful for category-based searches where all products in a category have the same relevancy. You can sort products by conditions such as name or price, in ascending or descending order.

Additionally, you can use the [Commerce Management Webstore Search, Include Rules](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_management_webstore_search_results_rules.htm) to add synonyms for search terms. This API supports both single-word and multi-word synonyms. For example, if you configure "jacket" as a synonym for "winter coat" and "wintercoat", either search term returns similar results.

The Boost and Bury Rules API adjusts the visibility of products based on their relevancy-based scoring. It allows you to boost the relevancy of certain products, making them appear higher in search results, or bury them to decrease their relevancy. You can also define a time period for these rules. This changes the product's relevance for all searches. The API supports creating, retrieving, and deleting boost and bury rules.

After you've created attributes and rules, add data from the product catalog to the search index. Product indexing improves search performance and speed. The Indexing APIs help you set up a search index for your store. The API supports creating an index for a product catalog on a web store or retrieving index information for the entire web store. Additionally, the Index Log API helps you retrieve search index logs for a web store.

## Search APIs for Shopper

The Search Suggestions and Product Search APIs enhance the shopper's experience. The Search Suggestions API provides real-time suggestions as users type in the search box. This API improves the user experience by quickly offering relevant suggestions. For example, when a user types "shirt", the API suggests terms like "men shirt" and "women shirt". The Product Search API conducts the actual search based on the entered search terms or filters. After a suggestion is selected or the search term is fully entered, the API retrieves a list of matching products, applying filters such as category and refinement. For example, if you select the category "clothing" and specify "red" as the refinement, the API returns red shirts.

## Use Case

Let's consider a basic scenario for building a flow using Search Settings APIs. This example covers just a few Search Settings APIs and doesn't include the full API functionality.

![Search Settings Workflow diagram showing the sequence for configuring and using Search Settings APIs](https://developer.salesforce.com/media/d2c-commerce/search_settings_apis_workflow.png '{"class": "image-lg", "title": "Search Settings Workflow"}')

Before using the Search Settings APIs, make sure that your products are set up in the store.

Let’s assume a product wasn’t configured as searchable during its creation. Make a PATCH request to the [Webstore Search Product Settings API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_product_settings.htm) to set the product as searchable.

Next, to add a new facet, such as the attribute "red" under the parent facet "color," make a PUT request to the [Webstore Search Facetable Attributes API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_facets.htm), including the new attribute "red" with the existing ones. These facets appear in the left-hand navigation on the Product Listing Page (PLP). Additionally, define which attributes are searchable by making a PATCH request to the [Webstore Search Searchable Attributes API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_attributes.htm).

After defining the attributes and setting them as searchable, update your store index to reflect these changes. Make a POST request to the [Webstore Search Indexes API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_indexes.htm) to create an index. This live index replaces the current one and removes any in-progress indexes.

When your store is ready, as a shopper types "shirt," a GET request to the [Webstore Product Search Suggestions API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_suggestions.htm) returns suggestions like "shirt men" and "shirt women." After selecting a suggestion or fully entering the search term, make a POST request to the [Commerce Webstore Product Search API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm) to retrieve a list of products matching the search term, applying filters such as "red" for color.

## Resources

Here’s a list of Search Settings resources:

| Resource                                                                                                                                                                                                                              | Supported HTTP Methods | Description                                                                                                                              | Available Version |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| [`/commerce/management/webstores/​{webstoreId}/search/product-settings`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_product_settings.htm)                | GET, PATCH             | Specify whether a product is searchable or not.                                                                                          | 49.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/attribute-settings/​facetable-fields`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_facets.htm)      | GET, PUT               | Get and update facetable attributes.                                                                                                     | 49.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/attribute-settings/​searchable-fields`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_attributes.htm) | GET, PATCH             | Get and update searchable attributes.                                                                                                    | 49.0              |
| [`/commerce/management/webstores/{webstoreId}/search/​boost-bury-rules`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_boost_bury_create.htm)               | GET, POST              | Get all boost and bury rules for a web store. Create a boost and bury rule. You can create up to 25 boost and bury rules for a webstore. | 59.0              |
| [`/commerce/management/webstores/{webstoreId}/search/​boost-bury-rules​/ruleId`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_boost_bury_manage.htm)       | DELETE, GET            | Get a boost and bury rule. Delete a boost and bury rule.                                                                                 | 59.0              |
| [`/commerce/management/webstores/{webstoreId}/search/​results-rules`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_management_webstore_search_results_rules.htm)           | GET, PUT, POST         | Create or retrieve search include rules for a web store. You can create up to 50 rules for a web store.                                  | 58.0              |
| `/commerce/management/webstores/{webstoreId}/search/​results-rules/ruleId`                                                                                                                                                            | DELETE, PUT            | Create or delete a search include rule for a web store.                                                                                  | 66.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/indexes`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_indexes.htm)                                  | GET, POST              | Get indexes and create an index of a product catalog.                                                                                    | 49.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/indexes/{indexId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_index.htm)                          | GET                    | Get and delete a search index.                                                                                                           | 49.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/index-logs`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_index_logs.htm)                            | GET                    | Get search index logs for a web store.                                                                                                   | 57.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/sort-rules`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_management_webstore_search_sort_rules.htm)                 | GET, PUT               | Create or retrieve sort rules for a web store.                                                                                           | 54.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/suggestions`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_suggestions.htm)                          | GET                    | Get suggestions for product searches.                                                                                                    | 52.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/products`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm)                                | GET                    | Search products.                                                                                                                         | 58.0              |
| [`/commerce/management/webstores/​{webstoreId}/search/product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)                           | POST                   | Search products.                                                                                                                         | 49.0              |

<!-- document id=b111ed408d40277608cf90320a26fed3692e04de5817c726327bcc32413399dc url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-tax-apis.md -->

# Salesforce Commerce Tax API

Calculate taxes for line items and get tax information for specified products by using the Salesforce Commerce Tax APIs. You can execute these requests outside cart and checkout pages so that you can show tax calculations elsewhere in your store.

## Calculate Taxes API

To calculate taxes for line items in a Commerce webstore, make a POST request to the [Commerce Webstore Calculate Taxes](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_calculate_taxes.htm) resource. This request executes the same tax calculations used by the [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.html) (CCA). However, using the Connect API resource rather than CCA means tax calculations can be done outside of cart and checkout.

For a POST request, specify the [Calculate Taxes Input](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_calculate_taxes_input.htm) request body. This request body requires a list of [line items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_requests_calculate_taxes_line_item_input.htm) grouped by shipping address. The shipping address includes the ISO code of the country and state. The request associates line items with the buyer account or guest profile ID (from `effectiveAccountId`) and the webstore ID (from the URL).

If your store supports multiple currencies, the POST request must also specify the `currencyIsoCode` to use for tax calculation (for example, `USD`). If unspecified, the default value is the default country for the webstore.

You can use the boolean property `calculatebyTaxClass` to determine whether taxes are calculated based on tax class (true) or not (false). Tax classes are important if your store supports the Japanese Consumption Tax (JCT), which imposes different tax rates on different types of products. The rate is 10% for most goods and services, but it‘s 8% for certain food, beverage, and newspaper products. Tax calculation rounds JCT amounts by the total JCT amount per tax class rather than per product.

The response body for the POST request, [Calculate Taxes](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_calculate_taxes.htm), indicates whether the tax calculation was successful, and, if it wasn‘t successful, lists any error messages. The property `taxLocaleType` indicates whether the webstore uses gross taxation, where product prices include tax, or net taxation, where prices don’t include tax.

The tax information returned includes the sum of taxes for all line items and tax details, including amounts, adjustments, and rates, broken down by line item. If `calculatebyTaxClass` was set to true, the response body also returns details about the taxation amount by tax class.

## Get Tax Rates API

To get tax rates for a product based on the webstore, shipping location, and buyer account or guest profile ID, make a GET request to the [Commerce Webstore Taxes](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_tax.htm) resource.

This resource is for stores that use the [manual Salesforce tax solution](https://help.salesforce.com/s/articleView?id=commerce.comm_what_is_tax_solution.htm) and gross taxation, or a custom extension. If your store uses the [Salesforce tax solution](https://help.salesforce.com/s/articleView?id=commerce.comm_set_up_salesforcetaxsoln.htm) with a third-party tax calculation service like Stripe, only mocked data returns from GET requests. The manual solution is suitable if you have a simple gross tax situation. In any case, consult with a tax expert when setting up taxes for your store.

Specify the webstore and product IDs in the resource URL. For example, `https://yourInstance.salesforce.com/services/data/v62.0/commerce/webstores/0ZEPI0000000j8Q4AQ/taxes/​products/01tPI0000003fLBYAY`.

In the request parameters, set `countryIsoCode` to indicate the destination country or territory for the shipped product, rather than the origin of the order. This code determines the applicable geo country tax rate. If unspecified, the default value is the default country for the store. If you configured tax rates for states or provinces within the country or territory, also set the optional `stateIsoCode` parameter. For both parameters, match the ISO codes with codes defined within your org’s state and country picklists. For a list of ISO codes, see [Standard Countries and Territories for Address Picklists](https://help.salesforce.com/s/articleView?id=xcloud.admin_state_country_picklists_standard_countries.htm).

The GET request also requires the `effective​AccountId` parameter, which represents the buyer account or guest buyer profile ID for which the request is made. If unspecified, the default value is determined from context.

The [response body for GET](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_commerce_get_store_tax_info.htm) returns the tax locale type of the store (`Gross` or `Net`) and a map of the product ID to its taxation details.

## Use Case

To understand the Tax APIs, consider the steps involved in a basic scenario for tax calculation and rate retrieval. This scenario doesn’t include the entire Tax API functionality.

![Workflow of Tax APIs: configure tax rates, Calculate Taxes POST API, Tax Rates GET API](https://developer.salesforce.com/media/d2c-commerce/tax_apis_workflow.png '{"class": "image-framed"}')

First, confirm that your Commerce administrator configured taxes rates for your store. They can use the manual tax solution, the Salesforce tax solution with Stripe, or a custom extension. The Calculate Taxes POST API is compatible with each option, but the Taxes GET API isn’t compatible with the native Stripe integration.

When a buyer adds products to their cart, the platform groups these items by shipping address, which includes necessary details like country and state ISO codes. To show taxes right away when the cart is viewed, you can send a POST request to the Salesforce Commerce Webstore Calculate Taxes resource. In the request, include line items, shipping details, and the currency ISO code. The API calculates taxes based on this data and returns detailed tax amounts, adjustments, and rates for each line item.

If your store uses the manual tax solution with gross taxation, you can enhance the shopping experience by displaying tax rates on additional pages outside of cart and checkout, like the Product Detail page. For example, make a GET request to the Commerce Webstore Taxes resource. In your request, include the IDs for the webstore, product, and account. Also include the buyer’s country or territory and state or province, if applicable. Then, parse the tax rate of the product from the response. You can use this information to calculate the product price before taxes and display this value on the Product Detail page beneath the gross price.

## Resources

| Resource                                                                                                                                                                                                 | Supported HTTP Methods | Description                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| [`/commerce/webstores/{webstoreId}/taxes/actions/calculate-taxes`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_calculate_taxes.htm) | POST                   | Calculate taxes for a Commerce webstore.                                                           |
| [`/commerce/webstores/{webstoreId}/taxes/products/{productId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_tax.htm)                | GET                    | Get taxes for a product based on the store, state, country, and buyer account or guest profile ID. |

<!-- document id=f2c393baa60cb56838a963be31204238ab9fe411bf02873c81eb08ac61460461 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-wishlists-apis.md -->

# Salesforce Commerce Wishlists API

The Salesforce Commerce Wishlists API allows customers to manage their Wishlists. Wishlists provide customers with a convenient way to save or bookmark products they are interested in. For example, while browsing for products, customers can add items to their Wishlists for future reference. Wishlists are available in both B2B stores.

There are six Wishlist-related APIs—some manage Wishlists, while others handle individual items. These APIs allow you to add products to new or existing Wishlist, delete Wishlist items, add Wishlist items to a cart, or move all items from a cart to a Wishlist. Although the Lightning Web Runtime (LWR) template doesn't support moving all Wishlist items to a specific cart in the UI, you can use the API to create a custom solution for this.

The [Commerce Webstore Wishlists API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlists.htm) can be used to retrieve a list of Wishlists or to create a new Wishlist for a user. The GET method retrieves the details of the user's Wishlists but does not include associated products by default. You can use the includeDisplayedList request parameter to fetch complete details of the oldest Wishlist, including associated items and their related data (such as fields and images). However, to fetch complete details about a particular WishList, pass the wishListId request parameter. The POST method allows you to create a new Wishlist by providing the Wishlist name and the IDs of the products you want to associate with it.

The [Commerce Webstore Wishlist API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist.htm) allows you to update, delete, or retrieve a specific Wishlist. The GET method fetches complete details of the specified Wishlist, including associated items and their related data. The PATCH method is limited to updating only the Wishlist's name, without support for modifying any other attributes. To delete a specific Wishlist, the DELETE method can be used.

For managing individual Wishlist items, the [Commerce Webstore Wishlist Item API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_item.htm) provides functionality to delete a single item. The DELETE method allows you to remove a specific item from a Wishlist.

The [Commerce Webstore Wishlist Items API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_items.htm) allows you to add items to a Wishlist or retrieve them. The GET method retrieves items from a specified Wishlist, while the POST method adds a single product to an existing Wishlist. Typically used on the Product Detail Page, this API enables users to bookmark a product by adding it to one of their existing Wishlists.

The [Commerce Webstore Wishlist, Add To Cart API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_add_to_cart.htm) allows you to move all products from a Wishlist to an active and specific cart. For example, if you're on the Wishlist page and want to add all items from a Wishlist to a cart, you can make a POST request to move the items to the desired cart. Currently, the Lightning Web Runtime (LWR) experience builder site does not support adding Wishlist items to a specific cart through the user interface. However, if customers are creating their own custom experience, they can use this API to build an action that adds all items from a Wishlist to an active cart.

The [Commerce Webstore Cart, Add To Wishlist API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_add_to_wishlist.htm?q=%2Factions%2Fadd-cart-to-wishlist) enables users to move products from their active and specific cart to an existing Wishlist. This API functions exclusively within the cart, allowing users to move all items from the cart to a specified Wishlist using the POST method.

## Use Case

Let's consider a basic scenario for building a flow using Wishlists APIs. This example covers just a few Wishlists APIs and doesn't include the entire APIs functionality.

### Scenario 1

![Diagram of the wishlists API workflow for B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/wishlists_apis_workflow.png '{"class": "image-lg", "title": "Checkout Workflow"}')

Imagine a scenario where a buyer is on the Product Detail page and wants to bookmark a product for future reference. In this case, they would make a POST request to the [Commerce Webstore Wishlist Items API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_items.htm) to add the product to an existing Wishlist. Later, if the buyer decides to remove a specific product from their Wishlist, they would send a DELETE request to the [Commerce Webstore Wishlist Item API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_item.htm) to remove that item.

### Scenario 2

![Continuation of the wishlists API workflow diagram for B2B and D2C Commerce](https://developer.salesforce.com/media/d2c-commerce/wishlists_apis_workflow1.png '{"class": "image-lg", "title": "Checkout Workflow"}')

Consider a scenario where a customer adds multiple items to their cart but decides to complete the purchase at a later time. For instance, on a shopping site, the customer can add products directly to your cart, and if you change your mind, you can move those products to your Wishlist for later reference. In this case, you can make a POST request to the [Commerce Webstore Cart, Add To Wishlist API](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_add_to_wishlist.htm?q=%2Factions%2Fadd-cart-to-wishlist) to transfer products from your active cart to an existing Wishlist.

## Resources

Here’s a list of Commerce Wishlists resources:

| Resource                                                                                                                                                                                                                                                             | Supported HTTP Methods | Description                                            |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------------ |
| [`/commerce/webstores/{webstoreId}/wishlists`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlists.htm)                                                                                       | GET, POST              | Create a new WishList or fetch collection of WishList. |
| [`/commerce/webstores/{webstoreId}/wishlists/{wishlistId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist.htm)                                                                           | DELETE, GET, PATCH     | Delete, edit, or fetch a specific WishList.            |
| [`/commerce/webstores/{webstoreId}/wishlists/{wishlistId}/actions/add-wishlist-to-cart`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_add_to_cart.htm)                                  | POST                   | Add all products from WishList to the provided Cart.   |
| [`/commerce/webstores/{webstoreId}/wishlists/{wishlistId}/wishlist-items`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_items.htm)                                                      | GET, POST              | Get wishlist items or add items to the wishlist.       |
| [`/commerce/webstores/{webstoreId}/wishlists/{wishlistId}/wishlist-items/{wishlistItemId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_item.htm)                                      | DELETE                 | Delete single WishList item.                           |
| [`/commerce/webstores/{webstoreId}/carts/cartStateOrId/actions/add-cart-to-wishlist`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_add_to_wishlist.htm?q=%2Factions%2Fadd-cart-to-wishlist) | POST                   | Copy products from Cart to WishList.                   |

<!-- document id=425f9cdfcb17f88a7362cea6dcf65d53417236a4f5f0e785ea4e985ef8eebd38 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-payments-ref.md -->

Salesforce Payments API

# Salesforce Payments API

The Salesforce Payments API provides resources for managing payment methods within a merchant account. With this API, you can manage payment methods, save and update setup intents and payment method details, retrieve configured payment method sets, initiate payment processes, create payment link orders, and retrieve payment link details.

Salesforce Payments API endpoints are available under /payments. To access these resources, your org must have one or more of these licenses:

*   Salesforce Payments Internal license
*   Salesforce Payments External User license
*   Payments Administrator permissions
*   Authenticated Payer permissions
*   Access to public API sites for guest users who want to make payments

**Version:** 66.0

## Servers

*   `https://{yourinstance}.salesforce.com/services/data/{version}`
    *   `version (default v66.0): v66.0, v65.0, v64.0, v63.0, v62.0`

## Operations

### POST Create an order for a payment link.

`POST /payments/link-to-order/{paymentLinkId}`

Operation ID: `createPaymentLinkToOrder`. Tags: Payment Link.

First, the Payment Link, Get Configuration API is called to fetch the payment link details, which are then shown on the Pay Now page. These details include the amount, payment method, and currency. After users enter payment details and additional information, the Payment Link, Create Order API is called to process the payment and generate the payment order.

#### Parameters

*   `paymentLinkId` (path, string, required, style: simple) Payment link ID used to process payments and create payment orders.

#### Request body

Payment link input that's used to generate the payment order.

Media type: `application/json`. Schema: `PaymentLinkToOrderInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `PaymentLinkToOrderOutputRepresentation`.
    

### GET Retrieve all saved payment methods for a specific merchant account or contact.

`GET /payments/merchant-accounts/{merchantAccountId}/saved-payment-methods`

Operation ID: `getSavedPaymentMethods`. Tags: Saved Payment Method.

#### Parameters

*   `merchantAccountId` (path, string, required, style: simple) Required. Salesforce Payments merchant account ID associated with the saved payment method.
*   `effectiveAccountId` (query, string, style: form, explode: true) Required. Owner of the saved payment method. Saved Payment Method doesn't support account switching in B2B Commerce. Make sure the logged-in user's parent account ID matches the store's effective account ID.
*   `pageSize` (query, integer (int32), style: form, explode: true) Optional. Number of records returned per page.
*   `pageToken` (query, string, style: form, explode: true) Optional. Marker denoting the next page to retrieve.
*   `sortOrder` (query, SavedPaymentMethodSortOrderEnum, style: form, explode: true) Optional. Sorts the returned list in descending or ascending by name.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `SavedPaymentMethodCollectionOutputRepresentation`.
    

### POST Create a new saved payment method. This API is available only to registered shoppers.

`POST /payments/merchant-accounts/{merchantAccountId}/saved-payment-methods`

Operation ID: `createSavedPaymentMethod`. Tags: Saved Payment Method.

#### Parameters

*   `merchantAccountId` (path, string, required, style: simple) Required. Salesforce Payments merchant account ID associated with the saved payment method.

#### Request body

Details of the shopper’s saved payment method.

Media type: `application/json`. Schema: `SavedPaymentMethodInputRepresentation`.

_Example: CreateCardSetupIntent_ Creates the setup intent for card payment method with Stripe.

```
{
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "savedByMerchant": false,
  "referenceOwnerId": "001RM000005WOk0YAG",
  "usageType": "OffSession",
  "isDefault": true
}
```

_Example: Create&ConfirmMotoSetupIntent_ Creates and confirms the setup intent for MOTO with Stripe.

```
{
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "savedByMerchant": true,
  "gatewayToken": "pm_1P5tJgI1HBpLATyQnQp1aidp",
  "referenceOwnerId": "001RM000005WOk0YAG",
  "usageType": "OffSession",
  "isDefault": true,
  "payerBillingAddress": {
    "companyName": "Adidas",
    "street": "125 Mission St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  }
}
```

_Example: CreateCardMotoSetupIntentAdyen_ Creates a setup intent for card payment method MOTO with Adyen.

```
{
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "savedByMerchant": true,
  "referenceOwnerId": "001RM000005WOk0YAG",
  "paymentMethodInformation": {
    "paymentMethodData": {
      "paymentMethod": {
        "type": "scheme",
        "encryptedCardNumber": "test_4111111111111111",
        "encryptedExpiryMonth": "test_03",
        "encryptedExpiryYear": "test_2030",
        "encryptedSecurityCode": "test_737",
        "holderName": "John Smith"
      }
    }
  },
  "usageType": "OffSession",
  "isDefault": true,
  "payerBillingAddress": {
    "companyName": "Adidas",
    "street": "125 Mission St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  }
}
```

_Example: CreateACHMotoSetupIntentAdyen_ Creates a setup intent for ACH payment method MOTO with Adyen.

```
{
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "ach",
  "savedByMerchant": true,
  "referenceOwnerId": "001RM000005WOk0YAG",
  "paymentMethodInformation": {
    "paymentMethodData": {
      "paymentMethod": {
        "type": "ach",
        "bankLocationId": 11000138,
        "bankAccountNumber": 1234567890,
        "ownerName": "John Smith"
      }
    }
  },
  "usageType": "OffSession",
  "isDefault": true,
  "payerBillingAddress": {
    "companyName": "Adidas",
    "street": "125 Mission St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  }
}
```

_Example: Create&ConfirmACHSetupIntentByMerchant_ Creates and confirms the ACH setup intent by a merchant with Stripe.

```
{
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "us_bank_account",
  "savedByMerchant": true,
  "referenceOwnerId": "001RM000005WOk0YAG",
  "usageType": "OffSession",
  "isDefault": true,
  "payerBillingAddress": {
    "companyName": "Adidas",
    "street": "125 Mission St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "paymentMethodInformation": {
    "accountHolder": "Business",
    "accountType": "Savings",
    "accountNumber": 123456789,
    "routingNumber": 110000000,
    "achConsentMethod": "Written"
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `SavedPaymentMethodCollectionOutputRepresentation`.
    
    _Example: Create&ConfirmMotoSetupIntent_ Creates and confirms the setup intent for MOTO with Stripe
    
    ```
    {
      "items": [
        {
          "gatewayRefId": "seti_1P66utI1HBpLATyQDFReChaH",
          "savedByMerchant": true,
          "gatewayResponse": {
            "id": "seti_1P66utI1HBpLATyQDFReChaH",
            "object": "setup_intent",
            "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
            "automatic_payment_methods": null,
            "cancellation_reason": null,
            "client_secret": "seti_1P66utI1HBpLATyQDFReChaH_secret_PvysjHIcpI3u8zTLaHrVfTnGxsjIetU",
            "created": 1713254339,
            "customer": "cus_PvkpNaxCGzZUwC",
            "description": null,
            "flow_directions": null,
            "last_setup_error": null,
            "latest_attempt": "setatt_1P66utI1HBpLATyQksnLimz7",
            "livemode": false,
            "mandate": null,
            "metadata": {},
            "next_action": null,
            "on_behalf_of": null,
            "payment_method": "pm_1P5tJgI1HBpLATyQnQp1aidp",
            "payment_method_configuration_details": null,
            "payment_method_options": {
              "card": {
                "mandate_options": null,
                "network": null,
                "request_three_d_secure": "automatic"
              }
            },
            "payment_method_types": [
              "card"
            ],
            "single_use_mandate": null,
            "status": "succeeded",
            "usage": "off_session"
          }
        }
      ]
    }
    ```
    
    _Example: CreateCardMotoSetupIntentAdyen_ Creates a setup intent for Card Payment Method MOTO with Adyen
    
    ```
    {
      "items": [
        {
          "gatewayRefId": "L9QW69WV35F2MV65",
          "gatewayResponse": {
            "amount": {
              "currency": "USD",
              "value": 0
            },
            "resultCode": "Authorised",
            "paymentMethod": {
              "brand": "visa",
              "type": "scheme"
            },
            "additionalData": {
              "recurringProcessingModel": "UnscheduledCardOnFile",
              "recurring.recurringDetailReference": "LXNBKMWVRT84QM65",
              "recurring.shopperReference": "o:00Dxx0000006GvnEAE;g:0b0xx00000000G9AAI;m:8zbxx00000000G9AAI;u:001xx000003GYiTAAW;"
            },
            "pspReference": "L9QW69WV35F2MV65",
            "merchantReference": "099a3f57-3eda-47a8-a5ad-d682a566e566"
          }
        }
      ]
    }
    ```
    
    _Example: CreateACHMotoSetupIntentAdyen_ Creates a setup intent for ACH Payment Method MOTO with Adyen
    
    ```
    {
      "items": [
        {
          "gatewayRefId": "L264T3W4X3H8F6V5",
          "gatewayResponse": {
            "amount": {
              "currency": "USD",
              "value": 0
            },
            "resultCode": "Authorised",
            "paymentMethod": {
              "type": "ach"
            },
            "additionalData": {
              "achdirectdebit.dateOfSignature": "2024-10-03",
              "recurring.recurringDetailReference": "MJBKDGF9MPN4VDV5",
              "achdirectdebit.mandateId": "L264T3W4X3H8F6V5",
              "achdirectdebit.sequenceType": "First",
              "recurring.shopperReference": "o:00Dxx0000006GvnEAE;g:0b0xx00000000G9AAI;m:8zbxx00000000G9AAI;u:001xx000003GYiTAAW;"
            },
            "pspReference": "L264T3W4X3H8F6V5",
            "merchantReference": "099a3f57-3eda-47a8-a5ad-d682a566e566"
          }
        }
      ]
    }
    ```
    
    _Example: Create&ConfirmACHSetupIntentByMerchant_ Creates and confirms the ACH setup intent by Merchant
    
    ```
    {
      "items": [
        {
          "gatewayRefId": "seti_1P66utI1HBpLATyQDFReChaH",
          "savedByMerchant": true,
          "gatewayResponse": {
            "id": "seti_1P66utI1HBpLATyQDFReChaH",
            "object": "setup_intent",
            "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
            "automatic_payment_methods": null,
            "cancellation_reason": null,
            "client_secret": "seti_1P66SnI1HBpLATyQEXWAVBOl_secret_PvyPWvOg30xev3xjFMbMghEeQmlpUEe",
            "created": 1713252597,
            "customer": "cus_PvkpNaxCGzZUwC",
            "description": null,
            "flow_directions": null,
            "last_setup_error": null,
            "latest_attempt": "setatt_1P66SnI1HBpLATyQLg2LQWYJ",
            "livemode": false,
            "mandate": "mandate_1P66SnI1HBpLATyQQzOfm0Lo",
            "metadata": {},
            "next_action": {
              "type": "verify_with_microdeposits",
              "verify_with_microdeposits": {
                "arrival_date": 1713337200,
                "hosted_verification_url": "https://payments.stripe.com/microdeposit/sacs_test_YWNjdF8xUDI3aG1JMUhCcExBVHlRLHNhX25vbmNlX1B2eVBNWmM2V0I1dGV3N2VYU1lwRHJpR2xMcGpFMUE0000SItrkZtX",
                "microdeposit_type": "descriptor_code"
              }
            },
            "on_behalf_of": null,
            "payment_method": "pm_1P66SnI1HBpLATyQ9tByE7xb",
            "payment_method_configuration_details": null,
            "payment_method_options": {
              "us_bank_account": {
                "mandate_options": {
                  "collection_method": "paper"
                },
                "verification_method": "microdeposits"
              }
            },
            "payment_method_types": [
              "us_bank_account"
            ],
            "single_use_mandate": null,
            "status": "requires_action",
            "usage": "off_session"
          }
        }
      ]
    }
    ```
    

### POST Store setup intent and payment method details in the SavedPaymentMethod object.

`POST /payments/merchant-accounts/{merchantAccountId}/saved-payment-methods/saveToken`

Operation ID: `saveSavedPaymentMethod`. Tags: Saved Payment Method.

#### Parameters

*   `merchantAccountId` (path, string, required, style: simple) Required. Salesforce Payments merchant account ID associated with the saved payment method.

#### Request body

Details of the shopper’s saved payment method.

Media type: `application/json`. Schema: `SavedPaymentMethodInputRepresentation (extended)`.

Includes all fields of `SavedPaymentMethodInputRepresentation`.

_Example_

```
{
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "referenceOwnerId": "001RM000005WOk0YAG",
  "gatewayCustomerReference": "cus_PvkpNaxCGzZUwC",
  "gatewayInitiatorReference": "seti_1P5uM1I1HBpLATyQTQbtun8h"
}
```

_Example: SaveCard_ Saving card payment method type

```
{
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "referenceOwnerId": "001RM000005WOk0YAG",
  "gatewayCustomerReference": "cus_PvkpNaxCGzZUwC",
  "gatewayInitiatorReference": "seti_1P5uM1I1HBpLATyQTQbtun8h"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `SavedPaymentMethodOutputRepresentation (extended)`.
    
    Includes all fields of `SavedPaymentMethodOutputRepresentation`.
    
    _Example_
    
    ```
    {
      "gatewayRefId": "seti_1P5uM1I1HBpLATyQTQbtun8h",
      "isSharedWithinSameAccount": false,
      "isOwner": true,
      "gatewayResponse": {
        "id": "seti_1P5uM1I1HBpLATyQTQbtun8h",
        "object": "setup_intent",
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "automatic_payment_methods": null,
        "cancellation_reason": null,
        "client_secret": "seti_1P66P7I1HBpLATyQQw89mRvq_secret_PvyLqn7WbP3LpBQlcTi6Q16k7keTdvZ",
        "created": 1713252369,
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "flow_directions": null,
        "last_setup_error": null,
        "latest_attempt": "setatt_1P66P7I1HBpLATyQMGeylNCZ",
        "livemode": false,
        "mandate": null,
        "metadata": {},
        "next_action": null,
        "on_behalf_of": null,
        "payment_method": {
          "id": "pm_1P5tJgI1HBpLATyQnQp1aidp",
          "object": "payment_method",
          "billing_details": {
            "address": {
              "city": "San Francisco",
              "country": "US",
              "line1": "126 Mission St",
              "line2": null,
              "postal_code": "94102",
              "state": "California"
            },
            "email": "davidtaylor@salesforce.com",
            "name": "David Taylor",
            "phone": null
          },
          "card": {
            "brand": "visa",
            "checks": {
              "address_line1_check": "pass",
              "address_postal_code_check": "pass",
              "cvc_check": "pass"
            },
            "country": "US",
            "display_brand": "visa",
            "exp_month": 3,
            "exp_year": 2026,
            "fingerprint": "aXEXuPhFCIBH7ifR",
            "funding": "credit",
            "generated_from": null,
            "last4": "4242",
            "networks": {
              "available": [
                "visa"
              ],
              "preferred": null
            },
            "three_d_secure_usage": {
              "supported": true
            },
            "wallet": null
          },
          "created": 1713202060,
          "customer": "cus_PvkpNaxCGzZUwC",
          "livemode": false,
          "metadata": {},
          "type": "card"
        },
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "card": {
            "mandate_options": null,
            "network": null,
            "request_three_d_secure": "automatic"
          }
        },
        "payment_method_types": [
          "card"
        ],
        "single_use_mandate": null,
        "status": "succeeded",
        "usage": "off_session"
      }
    }
    ```
    
    _Example: SaveCardResponse_ Save card payment method type response
    
    ```
    {
      "gatewayRefId": "seti_1P5uM1I1HBpLATyQTQbtun8h",
      "isSharedWithinSameAccount": false,
      "isOwner": true,
      "gatewayResponse": {
        "id": "seti_1P5uM1I1HBpLATyQTQbtun8h",
        "object": "setup_intent",
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "automatic_payment_methods": null,
        "cancellation_reason": null,
        "client_secret": "seti_1P66P7I1HBpLATyQQw89mRvq_secret_PvyLqn7WbP3LpBQlcTi6Q16k7keTdvZ",
        "created": 1713252369,
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "flow_directions": null,
        "last_setup_error": null,
        "latest_attempt": "setatt_1P66P7I1HBpLATyQMGeylNCZ",
        "livemode": false,
        "mandate": null,
        "metadata": {},
        "next_action": null,
        "on_behalf_of": null,
        "payment_method": {
          "id": "pm_1P5tJgI1HBpLATyQnQp1aidp",
          "object": "payment_method",
          "billing_details": {
            "address": {
              "city": "San Francisco",
              "country": "US",
              "line1": "126 Mission St",
              "line2": null,
              "postal_code": "94102",
              "state": "California"
            },
            "email": "davidtaylor@salesforce.com",
            "name": "David Taylor",
            "phone": null
          },
          "card": {
            "brand": "visa",
            "checks": {
              "address_line1_check": "pass",
              "address_postal_code_check": "pass",
              "cvc_check": "pass"
            },
            "country": "US",
            "display_brand": "visa",
            "exp_month": 3,
            "exp_year": 2026,
            "fingerprint": "aXEXuPhFCIBH7ifR",
            "funding": "credit",
            "generated_from": null,
            "last4": "4242",
            "networks": {
              "available": [
                "visa"
              ],
              "preferred": null
            },
            "three_d_secure_usage": {
              "supported": true
            },
            "wallet": null
          },
          "created": 1713202060,
          "customer": "cus_PvkpNaxCGzZUwC",
          "livemode": false,
          "metadata": {},
          "type": "card"
        },
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "card": {
            "mandate_options": null,
            "network": null,
            "request_three_d_secure": "automatic"
          }
        },
        "payment_method_types": [
          "card"
        ],
        "single_use_mandate": null,
        "status": "succeeded",
        "usage": "off_session"
      }
    }
    ```
    

### DELETE Delete a saved payment method linked to a specific merchant account.

`DELETE /payments/merchant-accounts/{merchantAccountId}/saved-payment-methods/{savedPaymentMethodId}`

Operation ID: `deleteSavedPaymentMethod`. Tags: Saved Payment Method.

#### Parameters

*   `merchantAccountId` (path, string, required, style: simple) Required. Salesforce Payments merchant account ID associated with the saved payment method.
*   `savedPaymentMethodId` (path, string, required, style: simple) Required. ID of the saved payment method record to delete.
*   `effectiveAccountId` (query, string, style: form, explode: true) Required. Owner of the saved payment method. Saved Payment Method doesn't support account switching in B2B Commerce. Make sure the logged-in user's parent account ID matches the store's effective account ID.

#### Responses

*   **200** Success

### PATCH Update a saved payment method linked to a specific merchant account.

`PATCH /payments/merchant-accounts/{merchantAccountId}/saved-payment-methods/{savedPaymentMethodId}`

Operation ID: `updateSavedPaymentMethod`. Tags: Saved Payment Method.

#### Parameters

*   `merchantAccountId` (path, string, required, style: simple) Required. Salesforce Payments merchant account ID associated with the saved payment method.
*   `savedPaymentMethodId` (path, string, required, style: simple) Required. ID of the saved payment method record to update.
*   `effectiveAccountId` (query, string, style: form, explode: true) Required. Owner of the saved payment method. Saved Payment Method doesn't support account switching in B2B Commerce. Make sure the logged-in user's parent account ID matches the store's effective account ID.

#### Request body

Marks Saved Payment Method as Default or Shared

Media type: `application/json`. Schema: `UpdateSavedPaymentMethodInputRepresentation (extended)`.

Includes all fields of `UpdateSavedPaymentMethodInputRepresentation`.

_Example_

```
{
  "markAsDefault": true,
  "markAsShared": false
}
```

_Example: MarkSPMAsDefault_ Marks SPM as default

```
{
  "markAsDefault": true
}
```

_Example: MarkSPMAsShared_ Marks SPM as shared

```
{
  "markAsShared": false
}
```

_Example: Create&MarkSPMAsDefaultAndShared_ Marks Saved Payment Method as default and Shared.

```
{
  "markAsDefault": true,
  "markAsShared": false
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `SavedPaymentMethodOutputRepresentation`.
    

### GET Retrieve dependent records associated with the specified saved payment method.

`GET /payments/merchant-accounts/{merchantAccountId}/saved-payment-methods/{savedPaymentMethodId}/dependents`

Operation ID: `getSavedPaymentMethodDependents`. Tags: Saved Payment Method.

#### Parameters

*   `merchantAccountId` (path, string, required, style: simple) Required. Salesforce Payments merchant account ID associated with the saved payment method.
*   `savedPaymentMethodId` (path, string, required, style: simple) Required. ID of the saved payment method record for which dependents needs to be returned.
*   `effectiveAccountId` (query, string, style: form, explode: true) ID of the account for which the request is made. If unspecified, defaults to the account ID for the context user.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `SavedPaymentMethodDependentOutputRepresentation`.
    
    _Example: GetDependentSubscriptionItems_ Gets the list of dependent subscription items.
    
    ```
    {
      "items": [
        {
          "id": "02i000000Xy1234",
          "startDate": "2023-08-01T00:00:00.000Z",
          "endDate": "2024-07-31T23:59:59.000Z",
          "quantity": 4
        }
      ]
    }
    ```
    

### POST Initiate a payment using Salesforce Payments.

`POST /payments/payment-intents`

Operation ID: `createPaymentIntent`. Tags: Payment Intent.

#### Request body

Payment intents input consumed to initiate a payment.

Media type: `application/json`. Schema: `PaymentIntentInputRepresentation (extended)`.

Includes all fields of `PaymentIntentInputRepresentation`.

_Example_

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "gatewayToken": "pm_1P5tJgI1HBpLATyQnQp1aidp"
}
```

_Example: Create&ConfirmMOTOPaymentIntentWhenSaveForFutureUsageNotChecked_ Creates and confirms MOTO Payment Intent when SaveForFutureUsage isn't checked with Stripe.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "gatewayToken": "pm_1P5tJgI1HBpLATyQnQp1aidp"
}
```

_Example: Create&ConfirmMOTOPaymentIntentWhenSaveForFutureUsageIsChecked_ Creates and confirms MOTO Payment Intent when SaveForFutureUsage is checked with Stripe.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "gatewayToken": "pm_1P5tJgI1HBpLATyQnQp1aidp",
  "paymentMethod": {
    "usageType": "OffSession",
    "referenceOwnerId": "001RM000005WOk0",
    "isDefault": true
  }
}
```

_Example: Create&ConfirmMOTOPaymentIntentWhenExistingSPMSelected_ Creates and confirms MOTO Payment Intent when an existing Saved Payment Method is selected.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "paymentMethod": {
    "id": "12q000000123"
  }
}
```

_Example: Create&ConfirmMerchantACHPaymentIntentWhenSaveForFutureUsageNotChecked_ Creates and confirms ACH Payment Intent by a merchant when SaveForFutureUsage isn't checked with Stripe.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "us_bank_account",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "payerBillingAddress": {
    "companyName": "Adidas",
    "street": "125 Mission St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "paymentMethodInformation": {
    "accountHolder": "Business",
    "accountType": "Savings",
    "accountNumber": 123456789,
    "routingNumber": 110000000,
    "achConsentMethod": "Written"
  }
}
```

_Example: Create&ConfirmMerchantACHPaymentIntentWhenSaveForFutureUsageIsChecked_ Creates and confirms ACH Payment Intent by a merchant when SaveForFutureUsage is checked with Stripe.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "us_bank_account",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "payerBillingAddress": {
    "companyName": "Adidas",
    "street": "125 Mission St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "paymentMethodInformation": {
    "accountHolder": "Business",
    "accountType": "Savings",
    "accountNumber": 123456789,
    "routingNumber": 110000000,
    "achConsentMethod": "Written"
  },
  "paymentMethod": {
    "usageType": "OffSession",
    "referenceOwnerId": "001RM000005WOk0",
    "isDefault": true
  }
}
```

_Example: Create&ConfirmMerchantACHPaymentIntentWhenExistingSPMSelected_ Creates and confirms ACH Payment Intent by Merchant when an existing Saved Payment Method is selected.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "us_bank_account",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "paymentMethod": {
    "id": "12q000000123"
  }
}
```

_Example: Create&ConfirmMOTOPaymentIntentWhenSaveForFutureUsageNotCheckedWithAdyen_ Creates MOTO Payment Intent when SaveForFutureUsage isn't checked with Adyen.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "card",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "paymentMethodInformation": {
    "paymentMethodData": {
      "paymentMethod": {
        "type": "scheme",
        "encryptedCardNumber": "test_4111111111111111",
        "encryptedExpiryMonth": "test_03",
        "encryptedExpiryYear": "test_2030",
        "encryptedSecurityCode": "test_737",
        "holderName": "John Smith"
      }
    }
  }
}
```

_Example: Create&ConfirmMerchantACHPaymentIntentWhenSaveForFutureUsageNotCheckedWithAdyen_ Creates ACH Payment Intent by Merchant when SaveForFutureUsage isn't checked with Adyen.

```
{
  "amount": 23.54,
  "currencyIsoCode": "USD",
  "paymentGatewayId": "0b0xx0000000001",
  "paymentMethodType": "us_bank_account",
  "useManualCapture": false,
  "businessAchEnabled": false,
  "isExpress": false,
  "isShippingApplicable": false,
  "isSavedPaymentMethodEnabled": true,
  "paymentMethodSetDeveloperName": "AMER_US",
  "entryMode": "Merchant",
  "payerBillingAddress": {
    "companyName": "Adidas",
    "street": "125 Mission St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "paymentMethodInformation": {
    "paymentMethodData": {
      "paymentMethod": {
        "type": "ach",
        "bankLocationId": 11000138,
        "bankAccountNumber": 1234567890,
        "ownerName": "John Smith"
      }
    }
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `object`.
    
    List of initiated payment intents.
    
    Includes all fields of `PaymentIntentOutputRepresentation`.
    
    _Example_
    
    ```
    {
      "guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
      "gatewayRefId": "pi_3P82FtI1HBpLATyQ08rpHRXA",
      "status": "Succeeded",
      "isMultiCaptureSupported": true,
      "paymentGatewayId": "0b0xx0000000001",
      "gatewayResponse": {
        "id": "pi_3P82KpI1HBpLATyQ07x42HAF",
        "object": "payment_intent",
        "amount": 2000,
        "amount_capturable": 0,
        "amount_details": {
          "tip": {}
        },
        "amount_received": 2000,
        "amount_subtotal": 2000,
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "application_fee_amount": 88,
        "automatic_payment_methods": null,
        "canceled_at": null,
        "cancellation_reason": null,
        "capture_method": "automatic",
        "client_secret": "pi_3P82KpI1HBpLATyQ07x42HAF_secret_Bwz2UPW56VMOBNGGXKtWR6WQi",
        "confirmation_method": "automatic",
        "created": 1713713383,
        "currency": "usd",
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "invoice": null,
        "last_payment_error": null,
        "latest_charge": "ch_3P82KpI1HBpLATyQ0FXja9ud",
        "level3": null,
        "livemode": false,
        "metadata": {
          "gatewayId": "0b0xx0000000001",
          "is_existing_pm": "false",
          "sf_prod_org_id": "0DB000000123",
          "sfp.guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
          "sfp.sourceObjectId": "sourceObjectId",
          "sfp.merchant_id": "8zbRO00000000VAYAY",
          "sfp.gateway_id": "0b0xx0000000001"
        },
        "next_action": null,
        "on_behalf_of": null,
        "payment_method": "pm_1P82FfI1HBpLATyQR7auyqsN",
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "card": {
            "installments": null,
            "mandate_options": null,
            "network": null,
            "request_three_d_secure": "automatic"
          }
        },
        "payment_method_types": [
          "card"
        ],
        "processing": null,
        "receipt_email": null,
        "review": null,
        "setup_future_usage": null,
        "shipping": null,
        "source": null,
        "statement_descriptor": null,
        "statement_descriptor_suffix": null,
        "status": "succeeded",
        "total_details": {
          "amount_discount": 0,
          "amount_tax": 0
        },
        "transfer_data": null,
        "transfer_group": null
      }
    }
    ```
    
    _Example: Create&ConfirmMOTOPaymentIntentWhenSaveForFutureUsageNotChecked_ Creates and confirms MOTO payment intent when SaveForFutureUsage isn't checked with Stripe
    
    ```
    {
      "guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
      "gatewayRefId": "pi_3P82FtI1HBpLATyQ08rpHRXA",
      "status": "Succeeded",
      "isMultiCaptureSupported": true,
      "paymentGatewayId": "0b0xx0000000001",
      "gatewayResponse": {
        "id": "pi_3P82KpI1HBpLATyQ07x42HAF",
        "object": "payment_intent",
        "amount": 2000,
        "amount_capturable": 0,
        "amount_details": {
          "tip": {}
        },
        "amount_received": 2000,
        "amount_subtotal": 2000,
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "application_fee_amount": 88,
        "automatic_payment_methods": null,
        "canceled_at": null,
        "cancellation_reason": null,
        "capture_method": "automatic",
        "client_secret": "pi_3P82KpI1HBpLATyQ07x42HAF_secret_Bwz2UPW56VMOBNGGXKtWR6WQi",
        "confirmation_method": "automatic",
        "created": 1713713383,
        "currency": "usd",
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "invoice": null,
        "last_payment_error": null,
        "latest_charge": "ch_3P82KpI1HBpLATyQ0FXja9ud",
        "level3": null,
        "livemode": false,
        "metadata": {
          "gatewayId": "0b0xx0000000001",
          "is_existing_pm": "false",
          "sf_prod_org_id": "0DB000000123",
          "sfp.guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
          "sfp.sourceObjectId": "sourceObjectId",
          "sfp.merchant_id": "8zbRO00000000VAYAY",
          "sfp.gateway_id": "0b0xx0000000001"
        },
        "next_action": null,
        "on_behalf_of": null,
        "payment_method": "pm_1P82FfI1HBpLATyQR7auyqsN",
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "card": {
            "installments": null,
            "mandate_options": null,
            "network": null,
            "request_three_d_secure": "automatic"
          }
        },
        "payment_method_types": [
          "card"
        ],
        "processing": null,
        "receipt_email": null,
        "review": null,
        "setup_future_usage": null,
        "shipping": null,
        "source": null,
        "statement_descriptor": null,
        "statement_descriptor_suffix": null,
        "status": "succeeded",
        "total_details": {
          "amount_discount": 0,
          "amount_tax": 0
        },
        "transfer_data": null,
        "transfer_group": null
      }
    }
    ```
    
    _Example: Create&ConfirmMOTOPaymentIntentWhenSaveForFutureUsageIsChecked_ Creates and confirms MOTO payment intent when SaveForFutureUsage is checked with Stripe
    
    ```
    {
      "guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
      "gatewayRefId": "pi_3P82g8I1HBpLATyQ1BExtho3",
      "status": "Succeeded",
      "isMultiCaptureSupported": true,
      "paymentGatewayId": "0b0xx0000000001",
      "gatewayResponse": {
        "id": "pi_3P82g8I1HBpLATyQ1BExtho3",
        "object": "payment_intent",
        "amount": 2000,
        "amount_capturable": 0,
        "amount_details": {
          "tip": {}
        },
        "amount_received": 2000,
        "amount_subtotal": 2000,
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "application_fee_amount": 88,
        "automatic_payment_methods": null,
        "canceled_at": null,
        "cancellation_reason": null,
        "capture_method": "automatic",
        "client_secret": "pi_3P82g8I1HBpLATyQ1BExtho3_secret_fQmzJfeJXdWDjpQNAlk4MdS42",
        "confirmation_method": "automatic",
        "created": 1713714704,
        "currency": "usd",
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "invoice": null,
        "last_payment_error": null,
        "latest_charge": "ch_3P82g8I1HBpLATyQ13GpI177",
        "level3": null,
        "livemode": false,
        "metadata": {
          "gatewayId": "0b0xx0000000001",
          "is_existing_pm": "false",
          "sf_prod_org_id": "0DB000000123",
          "sfp.guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
          "sfp.sourceObjectId": "sourceObjectId",
          "sfp.merchant_id": "8zbRO00000000VAYAY",
          "sfp.gateway_id": "0b0xx0000000001",
          "save_as_default": true
        },
        "next_action": null,
        "on_behalf_of": null,
        "payment_method": "pm_1P82FfI1HBpLATyQR7auyqsN",
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "card": {
            "installments": null,
            "mandate_options": null,
            "network": null,
            "request_three_d_secure": "automatic"
          }
        },
        "payment_method_types": [
          "card"
        ],
        "processing": null,
        "receipt_email": null,
        "review": null,
        "setup_future_usage": "off_session",
        "shipping": null,
        "source": null,
        "statement_descriptor": null,
        "statement_descriptor_suffix": null,
        "status": "succeeded",
        "total_details": {
          "amount_discount": 0,
          "amount_tax": 0
        },
        "transfer_data": null,
        "transfer_group": null
      }
    }
    ```
    
    _Example: Create&ConfirmMOTOPaymentIntentWhenExistingSPMSelected_ Creates and confirms MOTO payment intent when existing SPM is selected with Stripe
    
    ```
    {
      "guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
      "gatewayRefId": "pi_3P82xJI1HBpLATyQ0t1ckrH6",
      "status": "Succeeded",
      "isMultiCaptureSupported": true,
      "paymentGatewayId": "0b0xx0000000001",
      "gatewayResponse": {
        "id": "pi_3P82xJI1HBpLATyQ0t1ckrH6",
        "object": "payment_intent",
        "amount": 2000,
        "amount_capturable": 0,
        "amount_details": {
          "tip": {}
        },
        "amount_received": 2000,
        "amount_subtotal": 2000,
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "application_fee_amount": 88,
        "automatic_payment_methods": null,
        "canceled_at": null,
        "cancellation_reason": null,
        "capture_method": "automatic",
        "client_secret": "pi_3P82xJI1HBpLATyQ0t1ckrH6_secret_m4Ur8GdJMOYfWAlqcz6kkdiEG",
        "confirmation_method": "automatic",
        "created": 1713715769,
        "currency": "usd",
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "invoice": null,
        "last_payment_error": null,
        "latest_charge": "ch_3P82xJI1HBpLATyQ0kADzdhX",
        "level3": null,
        "livemode": false,
        "metadata": {
          "sfp.spm_id": "12q000000123",
          "is_existing_pm": "true",
          "sf_prod_org_id": "0DB000000123",
          "sfp.guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
          "sfp.sourceObjectId": "sourceObjectId",
          "sfp.merchant_id": "8zbRO00000000VAYAY",
          "sfp.gateway_id": "0b0xx0000000001"
        },
        "next_action": null,
        "on_behalf_of": null,
        "payment_method": "pm_1P82FfI1HBpLATyQR7auyqsN",
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "card": {
            "installments": null,
            "mandate_options": null,
            "network": null,
            "request_three_d_secure": "automatic"
          }
        },
        "payment_method_types": [
          "card"
        ],
        "processing": null,
        "receipt_email": null,
        "review": null,
        "setup_future_usage": null,
        "shipping": null,
        "source": null,
        "statement_descriptor": null,
        "statement_descriptor_suffix": null,
        "status": "succeeded",
        "total_details": {
          "amount_discount": 0,
          "amount_tax": 0
        },
        "transfer_data": null,
        "transfer_group": null
      }
    }
    ```
    
    _Example: Create&ConfirmMerchantACHPaymentIntentWhenSaveForFutureUsageNotChecked_ Creates & confirms ACH Payment Intent by Merchant when SaveForFutureUsage is not checked
    
    ```
    {
      "guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
      "gatewayRefId": "pi_3P836MI1HBpLATyQ09mC72Q6",
      "status": "Pending",
      "isMultiCaptureSupported": true,
      "paymentGatewayId": "0b0xx0000000001",
      "gatewayResponse": {
        "id": "pi_3P836MI1HBpLATyQ09mC72Q6",
        "object": "payment_intent",
        "amount": 2000,
        "amount_capturable": 0,
        "amount_details": {
          "tip": {}
        },
        "amount_received": 0,
        "amount_subtotal": 2000,
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "application_fee_amount": null,
        "automatic_payment_methods": null,
        "canceled_at": null,
        "cancellation_reason": null,
        "capture_method": "automatic",
        "client_secret": "pi_3P836MI1HBpLATyQ09mC72Q6_secret_PSnKM5ST8IRu9hQMKxmtFDE8D",
        "confirmation_method": "automatic",
        "created": 1713716330,
        "currency": "usd",
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "invoice": null,
        "last_payment_error": null,
        "latest_charge": null,
        "level3": null,
        "livemode": false,
        "metadata": {
          "gatewayId": "0b0xx0000000001",
          "is_existing_pm": "false",
          "sf_prod_org_id": "0DB000000123",
          "sfp.guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
          "sfp.sourceObjectId": "sourceObjectId",
          "sfp.merchant_id": "8zbRO00000000VAYAY",
          "sfp.gateway_id": "0b0xx0000000001"
        },
        "next_action": {
          "type": "verify_with_microdeposits",
          "verify_with_microdeposits": {
            "arrival_date": 1713769200,
            "hosted_verification_url": "https://payments.stripe.com/microdeposit/pacs_test_YWNjdF8xUDI3aG1JMUhCcExBVHlRLHBhX25vbmNlX1B4ejRUTU5zOUJlcHQ0bVAxcUoxdHJhUTBnRXFNY2w0000OcArUQ6i",
            "microdeposit_type": "descriptor_code"
          }
        },
        "on_behalf_of": null,
        "payment_method": "pm_1P836MI1HBpLATyQryeNmKhW",
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "us_bank_account": {
            "mandate_options": {
              "collection_method": "paper"
            },
            "verification_method": "microdeposits"
          }
        },
        "payment_method_types": [
          "us_bank_account"
        ],
        "processing": null,
        "receipt_email": null,
        "review": null,
        "setup_future_usage": null,
        "shipping": null,
        "source": null,
        "statement_descriptor": null,
        "statement_descriptor_suffix": null,
        "status": "requires_action",
        "total_details": {
          "amount_discount": 0,
          "amount_tax": 0
        },
        "transfer_data": null,
        "transfer_group": null
      }
    }
    ```
    
    _Example: Create&ConfirmMerchantACHPaymentIntentWhenSaveForFutureUsageIsChecked_ Creates and confirms ACH payment intent by a merchant when SaveForFutureUsage is checked with Stripe
    
    ```
    {
      "guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
      "gatewayRefId": "pi_3P836MI1HBpLATyQ09mC72Q6",
      "status": "Pending",
      "isMultiCaptureSupported": true,
      "paymentGatewayId": "0b0xx0000000001",
      "gatewayResponse": {
        "id": "pi_3P83DOI1HBpLATyQ13TOnyoy",
        "object": "payment_intent",
        "amount": 2000,
        "amount_capturable": 0,
        "amount_details": {
          "tip": {}
        },
        "amount_received": 0,
        "amount_subtotal": 2000,
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "application_fee_amount": null,
        "automatic_payment_methods": null,
        "canceled_at": null,
        "cancellation_reason": null,
        "capture_method": "automatic",
        "client_secret": "pi_3P83DOI1HBpLATyQ13TOnyoy_secret_vK1iSLnFb0p7YDXW3wCa5eOaY",
        "confirmation_method": "automatic",
        "created": 1713716766,
        "currency": "usd",
        "customer": "cus_PvkpNaxCGzZUwC",
        "description": null,
        "invoice": null,
        "last_payment_error": null,
        "latest_charge": null,
        "level3": null,
        "livemode": false,
        "metadata": {
          "gatewayId": "0b0xx0000000001",
          "is_existing_pm": "false",
          "sf_prod_org_id": "0DB000000123",
          "sfp.guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
          "sfp.sourceObjectId": "sourceObjectId",
          "sfp.merchant_id": "8zbRO00000000VAYAY",
          "sfp.gateway_id": "0b0xx0000000001",
          "save_as_default": true
        },
        "next_action": {
          "type": "verify_with_microdeposits",
          "verify_with_microdeposits": {
            "arrival_date": 1713769200,
            "hosted_verification_url": "https://payments.stripe.com/microdeposit/pacs_test_YWNjdF8xUDI3aG1JMUhCcExBVHlRLHBhX25vbmNlX1B4ekI4QWx6VlVKQlBtVFlBcUVQVmhPeE9ZRnh3RVo0000Hce92QY4",
            "microdeposit_type": "descriptor_code"
          }
        },
        "on_behalf_of": null,
        "payment_method": "pm_1P83DOI1HBpLATyQ6eIXjZpi",
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "us_bank_account": {
            "mandate_options": {
              "collection_method": "paper"
            },
            "verification_method": "microdeposits"
          }
        },
        "payment_method_types": [
          "us_bank_account"
        ],
        "processing": null,
        "receipt_email": null,
        "review": null,
        "setup_future_usage": "off_session",
        "shipping": null,
        "source": null,
        "statement_descriptor": null,
        "statement_descriptor_suffix": null,
        "status": "requires_action",
        "total_details": {
          "amount_discount": 0,
          "amount_tax": 0
        },
        "transfer_data": null,
        "transfer_group": null
      }
    }
    ```
    
    _Example: Create&ConfirmMerchantACHPaymentIntentWhenExistingSPMSelected_ Creates and confirms ACH payment intent by a merchant when an existing SPM is selected for Stripe
    
    ```
    {
      "guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
      "gatewayRefId": "pi_3P836MI1HBpLATyQ09mC72Q6",
      "status": "Pending",
      "isMultiCaptureSupported": true,
      "paymentGatewayId": "0b0xx0000000001",
      "gatewayResponse": {
        "id": "pi_3P83OKI1HBpLATyQ0aTD4lsN",
        "object": "payment_intent",
        "amount": 2000,
        "amount_capturable": 0,
        "amount_details": {
          "tip": {}
        },
        "amount_received": 0,
        "amount_subtotal": 2000,
        "application": "ca_G7iB1bFhSoNnfoXuHb85hdsCavzd19DI",
        "application_fee_amount": null,
        "automatic_payment_methods": null,
        "canceled_at": null,
        "cancellation_reason": null,
        "capture_method": "automatic",
        "client_secret": "pi_3P83OKI1HBpLATyQ0aTD4lsN_secret_o2qNE6vDBH5aDCi18y805Lmy2",
        "confirmation_method": "automatic",
        "created": 1713717444,
        "currency": "usd",
        "customer": "cus_PxzMEtdNziB7B4",
        "description": null,
        "invoice": null,
        "last_payment_error": null,
        "latest_charge": "py_3P83OKI1HBpLATyQ0VZy01qM",
        "level3": null,
        "livemode": false,
        "metadata": {
          "sfp.spm_id": "12q000000123",
          "is_existing_pm": "true",
          "sf_prod_org_id": "0DB000000123",
          "sfp.guid": "2f96f2c2-0f4e-4921-a92f-9ad1dc497919",
          "sfp.sourceObjectId": "sourceObjectId",
          "sfp.merchant_id": "8zbRO00000000VAYAY",
          "sfp.gateway_id": "0b0xx0000000001"
        },
        "next_action": null,
        "on_behalf_of": null,
        "payment_method": "pm_1P83O3I1HBpLATyQUejyK3LV",
        "payment_method_configuration_details": null,
        "payment_method_options": {
          "us_bank_account": {
            "mandate_options": {
              "collection_method": "paper"
            },
            "verification_method": "microdeposits"
          }
        },
        "payment_method_types": [
          "us_bank_account"
        ],
        "processing": null,
        "receipt_email": null,
        "review": null,
        "setup_future_usage": "off_session",
        "shipping": null,
        "source": null,
        "statement_descriptor": null,
        "statement_descriptor_suffix": null,
        "status": "processing",
        "total_details": {
          "amount_discount": 0,
          "amount_tax": 0
        },
        "transfer_data": null,
        "transfer_group": null
      }
    }
    ```
    
    _Example: Create&ConfirmMOTOPaymentIntentWhenSaveForFutureUsageNotCheckedWithAdyen_ Creates & confirms MOTO Payment Intent when SaveForFutureUsage is not checked with Adyen
    
    ```
    {
      "gatewayRefId": "PT9GV3ZQ9SM8F6V5",
      "status": "Created",
      "paymentGatewayId": "0b0xx00000000G9AAI",
      "guid": "73dd6f04-ea2a-4c39-9170-eef351325e05",
      "gatewayResponse": {
        "amount": {
          "currency": "USD",
          "value": 10000
        },
        "environment": "test",
        "resultCode": "Authorised",
        "paymentMethod": {
          "brand": "visa",
          "type": "scheme"
        },
        "guid": "73dd6f04-ea2a-4c39-9170-eef351325e05",
        "additionalData": {
          "recurringProcessingModel": "UnscheduledCardOnFile",
          "recurring.shopperReference": "o:00Dxx0000006GvnEAE;g:0b0xx00000000G9AAI;m:8zbxx00000000G9AAI;u:001xx000003GYiTAAW",
          "recurring.recurringDetailReference": "LXNBKMWVRT84QM65"
        },
        "pspReference": "PT9GV3ZQ9SM8F6V5",
        "merchantReference": "73dd6f04-ea2a-4c39-9170-eef351325e05"
      }
    }
    ```
    

### GET Retrieve the configuration details of a payment link.

`GET /payments/payment-link-configs/{paymentLinkId}`

Operation ID: `getPaymentLinkConfig`. Tags: Payment Link.

#### Parameters

*   `paymentLinkId` (path, string, required, style: simple) Required. Unique identifier for the payment link.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `object`.
    
    Payment link configuration details.
    
    Includes all fields of `PaymentLinkConfigOutputRepresentation`.
    

### GET Retrieve all configured payment method sets.

`GET /payments/payment-method-sets`

Operation ID: `getPaymentMethodSetsByDevOrMerchantAccountId`. Tags: Payment Method Set.

#### Parameters

*   `developerName` (query, string, style: form, explode: true) Optional. Developer name of the payment method set associated with the payment link, which is used to display the payment methods on the payment link page.
*   `merchantAccountId` (query, string, style: form, explode: true) Required. Salesforce Payments merchant account ID associated with the saved payment method.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `object`.
    
    List of payment method sets in use for Salesforce Payments merchant accounts.
    
    Includes all fields of `PaymentMethodSetOutputRepresentation`.
    

### GET Retrieve the details of a specified configured payment method set.

`GET /payments/payment-method-sets/{paymentMethodSetId}`

Operation ID: `getPaymentMethodSetsById`. Tags: Payment Method Set.

#### Parameters

*   `paymentMethodSetId` (path, string, required, style: simple) Required. Unique identifier for the payment method set. You can use the developerName query parameter in place of this path variable.
*   `developerName` (query, string, style: form, explode: true) Optional. Developer-assigned unique name to identify a payment method set. You can use this query parameter instead of the payment method set ID path variable.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `object`.
    
    List of payment method sets in use for Salesforce Payments merchant accounts.
    
    Includes all fields of `PaymentMethodSetOutputRepresentation`.
    

### POST Create a token for a terminal connection.

`POST /payments/terminal-connection-token`

Operation ID: `createTerminalConnectionToken`. Tags: Tap To Pay.

#### Parameters

*   `paymentGatewayId` (query, string, style: form, explode: true) Required. ID of the payment gateway.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `object`.
    
    Terminal connection token details.
    
    Includes all fields of `TerminalConnectionTokenOutputRepresentation`.
    

### POST Create a PaymentGroup container for all payments in a session and initiate the creation of Payment Intents.

`POST /payments/prepare-payments`

Operation ID: `preparePayments`. Tags: Prepare Payments.

#### Request body (required)

Consumes input to create or find Payment Group and initiate creation of Payment Intents.

Media type: `application/json`. Schema: `PreparePaymentsInputRepresentation (extended)`.

Includes all fields of `PreparePaymentsInputRepresentation`.

_Example_

```
{
  "sourceObjectId": "0a6xx000000001dAAA",
  "currencyIsoCode": "USD",
  "totalAmount": "1000",
  "useExistingPaymentGroup": false,
  "paymentIntents": [
    {
      "amount": 1000,
      "currencyIsoCode": "USD",
      "paymentGatewayId": "0b0xx0000000001",
      "paymentMethodType": "card",
      "useManualCapture": false,
      "businessAchEnabled": false,
      "isExpress": false,
      "isShippingApplicable": false,
      "isSavedPaymentMethodEnabled": true,
      "paymentMethodSetDeveloperName": "AMER_US",
      "entryMode": "PlaceOrderV2",
      "gatewayToken": "pm_1P5tJgI1HBpLATyQnQp1aidp"
    }
  ]
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `object`.
    
    PaymentGroupId and list of Payment Intents created.
    
    Includes all fields of `PreparePaymentsOutputRepresentation`.
    

## Schemas

### PaymentLinkToOrderInputRepresentation

PaymentLinkToOrderInputRepresentation

Payment link input that's used to generate the payment order.

*   `additionalData` (_AdditionalDataInputRepresentation_)
*   `paymentData` (_string_) Payment data identifier received from the payment gateway, such as Stripe, after successful validation of the payment data. This data is in JSON format and is stored in Salesforce object after successful payment request.

### PaymentLinkToOrderOutputRepresentation

PaymentLinkToOrderOutputRepresentation

Payment link to order output.

*   `orderReferenceNumber` (_string_) Globally unique identifier (GUID) of the payment order generated after successful completion of a payment request.

### SavedPaymentMethodSortOrderEnum

SavedPaymentMethodSortOrder

Type: `string`.

Allowed values: `CreatedDateAsc`, `CreatedDateDesc`, `IsDefaultAsc`, `IsDefaultDesc`, `NameAsc`, `NameDesc`.

### SavedPaymentMethodCollectionOutputRepresentation

SavedPaymentMethodCollectionOutputRepresentation

Collection of active saved payment methods for an account or contact.

*   `count` (_integer (int32)_) Count of saved payment methods.
*   `currentPageToken` (_string_) Token identifying the current page of saved payment methods.
*   `currentPageUrl` (_string_) URL to the current page of saved payment methods.
*   `items` (_array of SavedPaymentMethodOutputRepresentation_) List of saved payment methods.
*   `nextPageToken` (_string_) Token identifying the next page of saved payment methods.
*   `nextPageUrl` (_string_) URL to the next page of saved payment methods.
*   `pageSize` (_integer (int32)_) Page size for saved payment methods.
*   `previousPageToken` (_string_) Token identifying the previous page of saved payment methods.
*   `previousPageUrl` (_string_) URL to the previous page of saved payment methods.

### SavedPaymentMethodInputRepresentation

SavedPaymentMethodInputRepresentation

Details of the shopper’s saved payment method.

*   `additionalData` (_AdditionalDataInputRepresentation_)
*   `flowContext` (_string_) Optional. Checkout or My Account flow for this payment method.
*   `gatewayCustomerReference` (_string_) Required. Owner associated with the payment method to the payment gateway.
*   `gatewayInitiatorReference` (_string_) Required. Specifies the gateway initiator reference, such as setup intent ID for gateway Stripe.
*   `id` (_string_) Optional. Salesforce ID of the saved payment method record.
*   `isDefault` (_boolean_) Optional. Indicates whether the saved payment method is the default method to use for transactions (true) or not (false).
*   `paymentGatewayId` (_string_) Required. Salesforce ID of the Payment Gateway object record.
*   `paymentMethodType` (_string_) Required. Payment method type, such as a credit card.
*   `referenceOwnerId` (_string_) Required. ID of the merchant account of the contact record.
*   `usageType` (_SavedPaymentMethodUsageType_)
*   `savedByMerchant` (_boolean_) Indicates whether the saved payment method is created by the merchant (true) or not (false).  
    Default: `false`.
*   `gatewayToken` (_string_) Payment method token from the payment gateway.  
    Example: `pm_1P5tJgI1HBpLATyQnQp1aidp`.
*   `payerBillingAddress` (_AddressInputRepresentation_)
*   `paymentMethodInformation` (_PaymentMethodInformationInputRepresentation_)

### SavedPaymentMethodOutputRepresentation

SavedPaymentMethodOutputRepresentation

*   `gatewayResponse` (_object_) Gateway response representation for a saved payment method.
    
    Additional properties: `any`.
    
*   `accountHolderEmail` (_string_) Email of the customer that holds the saved payment method.
*   `accountHolderName` (_string_) Name of customer that holds the saved payment method.
*   `bankAccountType` (_string_) Type of bank account, such as checking or savings.
*   `bankCode` (_string_) Code of the banking institution that issued the saved payment method.
*   `bankName` (_string_) Name of the bank that issued the payment method.
*   `error` (_ErrorResponseRepresentation_)
*   `expiryMonth` (_string_) Month the saved card expires.
*   `expiryYear` (_string_) Year the saved card expires.
*   `gatewayCustomerReference` (_string_) Owner associated with the payment method to the payment gateway.
*   `gatewayRefId` (_string_) ID returned by a payment gateway in a transaction response, indicating that the transaction has happened.
*   `gatewayToken` (_string_) Token representing the saved payment method that is used for future transactions.
*   `id` (_string_) Salesforce ID of the saved payment method record.
*   `isDefault` (_boolean_) Indicates whether the saved payment method is the default payment method to use for transactions (true) or not (false).
*   `isSharedWithinSameAccount` (_boolean_) Indicates whether the saved payment method is shared with other contacts within the same account (true) or not (false). Default is false.
*   `savedByMerchant` (_boolean_) Indicates whether the saved payment method is created by the merchant (true) or not (false).
*   `issuer` (_string_) Issuer of the saved payment method.
*   `last4` (_string_) Last 4 Digits of the saved card payment method.
*   `merchantAccountId` (_string_) Salesforce Payments merchant account ID associated with the saved payment method.
*   `name` (_string_) Name of the saved payment record.
*   `network` (_string_) Saved payment method card network, for example Visa or Union Pay.
*   `paymentGatewayId` (_string_) Salesforce ID of the Payment Gateway object record.
*   `referenceOwnerId` (_string_) Account or Contact record that owns the payment method.
*   `status` (_SavedPaymentMethodStatus_)
*   `type` (_SavedPaymentMethodType_)
*   `usageType` (_SavedPaymentMethodUsageType_)
*   `standardEntryClassCode` (_StandardEntryClassCode_)
*   `isOwner` (_boolean_) Indicates if the current user is the owner of the SavedPaymentMethod (true) or not (false).

### UpdateSavedPaymentMethodInputRepresentation

UpdateSavedPaymentMethodInputRepresentation

*   `markAsDefault` (_boolean_) Optional. Indicates whether to set the saved payment method as the default (true) or not (false). The default is false.
*   `markAsShared` (_boolean_) Optional. Indicates whether to share the saved payment method with other contacts within the same account (true) or not (false). Default is false.

### SavedPaymentMethodDependentOutputRepresentation

SavedPaymentMethodDependentOutputRepresentation

*   `subscriptions` (_array of CommerceSubscriptionDetailRepresentation_) List of dependent subscriptions.

### PaymentIntentInputRepresentation

PaymentIntentInputRepresentation

Payment intents input consumed to initiate a payment.

*   `additionalData` (_AdditionalDataInputRepresentation_)
*   `paymentInitiationSource` (_PaymentInitiationSourceInputRepresentation_)
*   `amount` (_number_) Required. Amount to be captured.
*   `currencyIsoCode` (_string_) Required. Three-letter ISO 4217 code indicating the currency of the payment.
*   `customerId` (_string_) Required. Unique identifier for the customer.
*   `gatewayToken` (_string_) A unique, alphanumeric ID, called a token, that a payment gateway generates when it first processes a payment. The token replaces the actual payment data so that the data is kept secure. This token is stored as encrypted text, and can be used for recurring payments.
*   `isExpress` (_boolean_) Optional. Indicates whether the payment intent request is for Express checkout (true) or not (false). The default value is false. This field is applicable to only the PayPal gateway.
*   `entryMode` (_EntryMode_)
*   `isSavedPaymentMethodEnabled` (_boolean_) Indicates whether saved payment method is enabled (true) or not (false).
*   `isShippingApplicable` (_boolean_) Indicates whether shipping is applicable to this particular payment (true) or not (false). The default value is false. This field is applicable to only the PayPal gateway.
*   `payerAccountId` (_string_) Optional. ID of the payer’s Salesforce account. The ID is shown in the URL of any record. For example, if the record’s URL is [https://na1.lightning.force.com/lightning/r/Account/001OK000002KF2RYAW/view](https://na1.lightning.force.com/lightning/r/Account/001OK000002KF2RYAW/view), the ID is 001OK000002KF2RYAW.
*   `paymentGatewayId` (_string_) Required. ID of the payment gateway that processes the payment intent.
*   `paymentMethod` (_object_) Optional. Details required to save a payment method.
*   `paymentMethodSetDeveloperName` (_string_) Optional. Developer name for the payment method set.
*   `paymentMethodType` (_string_) Required. Type of payment instrument, such as a credit card or digital wallet.
*   `shippingAddress` (_AddressInputRepresentation_)
*   `sourceObjectIds` (_array of string_) Required. A list of cart or checkout IDs that indicates what the payment was made for.
*   `useManualCapture` (_boolean_) Optional. Indicates whether to use manual capture of a payment (true) or not (false).
*   `businessAchEnabled` (_boolean_) Optional. Indicates whether to enable business ACH accounts in the payment sheet (true) or not (false).
*   `payerBillingAddress` (_AddressInputRepresentation_)
*   `paymentMethodInformation` (_PaymentMethodInformationInputRepresentation_)
*   `applyDomainValidations` (_boolean_) Optional (defaulted to true). Indicates whether validation specific to the application where the payment originated is performed.

### PaymentIntentOutputRepresentation

PaymentIntentOutputRepresentation

List of initiated payment intents.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayRefId` (_string_) Identifier of the gateway response.
*   `gatewayResponse` (_object_) Response from the payment gateway request.
    
    Additional properties: `any`.
    
*   `guid` (_string_) Unique identifier of the payment intent request.
*   `paymentGatewayId` (_string_) ID of the Salesforce Payment Gateway object.
*   `status` (_string_) Status of payment intent.  
    Allowed values: `created`, `processing`, `succeed.`.
*   `isMultiCaptureSupported` (_boolean_) Indicates whether the status of the payment intent from a payment gateway, such as Stripe is multi-capturable (true) or not (false).

### PaymentLinkConfigOutputRepresentation

PaymentLinkConfigOutputRepresentation

Payment link configuration details.

*   `amount` (_number_) Amount of the payment link.
*   `cartId` (_string_) ID of the cart associated with the payment link.  
    Example: `0a6000000AN79`.
*   `currencyIsoCode` (_string_) Currency Iso code of the payment link.  
    Example: `USD`.
*   `description` (_string_) Description of the payment link.  
    Example: `Sample payment link description`.
*   `paymentMethodSetDevName` (_string_) Developer name of the payment method set associated with the payment link, which is used to display the payment methods on the payment link page.  
    Example: `AMER-US`.
*   `title` (_string_) Title of the payment link.  
    Example: `Some payment link title`.
*   `type` (_PaymentLinkType_)

### PaymentMethodSetOutputRepresentation

PaymentMethodSetOutputRepresentation

PaymentMethodSet output representation

*   `countryCode` (_string_) Country that the payment method set is assigned to.
*   `developerName` (_string_) Developer-assigned unique name to identify the payment method set.
*   `id` (_string_) Identifies the payment method set that is mapped to a web store.
*   `merchantAccountId` (_string_) Identifies the Salesforce Payments merchant account associated with the payment method set.
*   `name` (_string_) Assigned name of the payment method set.
*   `paymentMethodSetAccounts` (_array of PaymentMethodSetAccount_) List of payment gateway accounts for the payment method set.
*   `paymentMethods` (_array of PaymentMethod_) List of payment method sets in use for Salesforce Payments merchant accounts.

### TerminalConnectionTokenOutputRepresentation

TerminalConnectionTokenOutputRepresentation

Details of the terminal connection token.

*   `clientSecret` (_string_) A client secret token provided to the payment gateway, such as Stripe.
*   `error` (_ErrorResponseRepresentation_)
*   `locationId` (_string_) The ID of the location to which this connection token is limited.

### PreparePaymentsInputRepresentation

PreparePaymentsInputRepresentation

Prepare Payments input consumed to create or find a Payment Group and initiate creation of payment intents.

*   `sourceObjectId` (_string_) Required. A unique identifier representing the cart for which the payment was made.
*   `currencyIsoCode` (_string_) Required. Three-letter ISO 4217 code indicating the currency of the payment.
*   `totalAmount` (_string_) Required. Total amount required to initiate and complete the payment session.
*   `paymentIntents` (_array of PaymentIntentInputRepresentation_) List of payment intents to create.
*   `useExistingPaymentGroup` (_boolean_) Optional. Indicates whether the payment method has changed since the last request (true) or not (false). Defaulted to false.

### PreparePaymentsOutputRepresentation

PreparePaymentsOutputRepresentation

Output consists of the id of the Payment Group and list of Payment Intents.

*   `error` (_ErrorResponseRepresentation_)
*   `paymentGroupId` (_string_) Identifier of the created or existing active PaymentGroup associated to sourceObjectId.
*   `paymentIntents` (_array of PaymentIntentOutputRepresentation_) List of payment intents that have been created.

### AdditionalDataInputRepresentation

AdditionalDataInputRepresentation

Specifies the additional entries for all connect services, each of which includes a key and value. Supports up to five key-value pairs. Each key and each value can contain up to 255 characters.

*   `asMap` (_object_) Additional data for all connect services
    
    Additional properties: `string`.
    

### SavedPaymentMethodUsageType

SavedPaymentMethodUsageType

Saved Payment Method Usage Type

Type: `string`.

Allowed values: `OffSession`, `OnSession`.

### AddressInputRepresentation

AddressInputRepresentation

Address input.

*   `city` (_string_) Optional. Address city.
*   `companyName` (_string_) Optional. Address company name.  
    Example: `Test Company`.
*   `country` (_string_) Optional. Address country.  
    Example: `United States`.
*   `postalCode` (_string_) Optional. Zip code or postal code for the address.  
    Example: `94102`.
*   `state` (_string_) Optional. Address state.  
    Example: `CA`.
*   `street` (_string_) Optional. Address street.  
    Example: `Baker Street`.
*   `phone` (_string_) Optional. Address phone number.  
    Example: `+1(415)555‑0132`.
*   `email` (_string_) Optional. Email address.  
    Example: `john.doe@gmail.com`.

### PaymentMethodInformationInputRepresentation

PaymentMethodInformationInputRepresentation

Payment Method Information input representation

*   `accountHolder` (_AccountHolder_)
*   `accountType` (_AccountType_)
*   `accountNumber` (_integer (int32)_) Unique number of the bank account.
*   `routingNumber` (_integer (int32)_) Bank routing number.
*   `paymentMethodData` (_object_) A map of key-value pairs holding dynamic payment method data. The key is a string representing the attribute, and the value can be any object.
    
    Additional properties: `object`.
    
*   `achConsentMethod` (_AchConsentMethod_)

### ErrorResponseRepresentation

ErrorResponseRepresentation

An error representation containing an error code and error message.

*   `errorCode` (_string_) Error code.  
    Example: `401`.
*   `errorMessage` (_string_) Message stating the reason for error, if any.  
    Example: `Some error message`.

### SavedPaymentMethodStatus

SavedPaymentMethodStatus

Saved Payment Method status

Type: `string`.

Allowed values: `Active`, `AwaitingPayment`, `Errored`, `Expired`.

### SavedPaymentMethodType

SavedPaymentMethodType

Saved Payment Method type

Type: `string`.

Allowed values: `Au_becs_debit`, `Bacs_debit`, `Bancontact`, `Card`, `Ideal`, `Sepa_debit`, `Us_bank_account`.

### StandardEntryClassCode

StandardEntryClassCode

Standard Entry Codes for ACH transactions  
\* `WEB` - Web Internet Initiated/Mobile Entry  
\* `CCD` - Coreporate Credit or Debit Entry  
\* `PPD` - Prearranged Payment and Deposit  
\* `TEL` - Telephone-Initiated Entry

Type: `string`.

Allowed values: `WEB`, `CCD`, `PPD`, `TEL`.

### CommerceSubscriptionDetailRepresentation

CommerceSubscriptionDetailRepresentation

Output Representation for Commerce Subscription.

*   `id` (_string (uuid)_) Unique identifier for the subscription.  
    Example: `64bf835f-ada9-4538-b5a3-f4ed8672c7b5`.
*   `startDate` (_string (date-time)_) The date when the subscription starts.  
    Example: `2023-08-01T00:00:00.000Z`.
*   `endDate` (_string (date-time)_) The date when the subscription ends.  
    Example: `2024-07-31T23:59:59.000Z`.
*   `quantity` (_number (double)_) The quantity associated with the subscription.  
    Example: `5`.
*   `product` (_object_) Details about the product.
    
    Includes all fields of `BuyerProductSummaryRepresentation`.
    
*   `sellingModel` (_object_) Details about the product selling model.
    
    Includes all fields of `ProductSellingModelRepresentation`.
    
*   `billing` (_object_) Summary of the billing information.
    
    Includes all fields of `CommerceSubscriptionBillingSummaryRepresentation`.
    

### PaymentInitiationSourceInputRepresentation

Input Representation for Payment Initiation Source

*   `application` (_Application_)
*   `channel` (_string_) Channel that submitted the payment.
*   `process` (_string_) Process(Component) that submitted the payment
*   `standardReferences` (_StandardReferenceInputRepresentation_)
*   `customFields` (_CustomFieldInputRepresentation_)

### EntryMode

EntryMode

Determines how the payment information is supplied.

Type: `string`.

Allowed values: `Payer_Online`, `Merchant`, `TapToPay`.

### PaymentLinkType

PaymentLinkType

Type of the PaymentLink

Type: `string`.

Allowed values: `CheckoutWithOrder`, `PredefindAmount`, `WithProducts`.

### PaymentMethodSetAccount

PaymentMethodSetAccount

Details of the payment method set for an account.

*   `accountId` (_string_) Gateway provider account for the payment method set.
*   `config` (_object_) Gateway configuration for the payment method set.
    
    Additional properties: `string`.
    
*   `gatewayId` (_string_) Unique identifier of the gateway provider.
*   `vendor` (_string_) Vendor name.

### PaymentMethod

PaymentMethod

PaymentMethodSet Payment Type representation

*   `accountId` (_string_) Salesforce Payments account to which this payment method is linked.
*   `paymentMethodType` (_string_) Type of payment instrument, such as a credit card or digital wallet.
*   `paymentModes` (_array of string_) Payment modes.

### AccountHolder

AccountHolder

Account holder type.

Type: `string`.

Allowed values: `Individual`, `Business`.

### AccountType

AccountType

Bank account type

Type: `string`.

Allowed values: `Checking`, `Savings`.

### AchConsentMethod

AchConsentMethod

The method used to collect offline mandate customer acceptance.

Type: `string`.

Allowed values: `Written`, `Verbal`.

### BuyerProductSummaryRepresentation

BuyerProductSummaryRepresentation

*   `id` (_string (uuid)_) Unique identifier for the product  
    Example: `64bf835f-ada9-4538-b5a3-f4ed8672c7b5`.
*   `name` (_string_) Name of the product  
    Example: `Alpine Creative Suite`.
*   `sku` (_string_) Stock Keeping Unit (SKU) of the product  
    Example: `#421234`.
*   `fields` (_object_) A map of fields associated with the product
    
    Additional properties: `RecordFieldRepresentation`.
    
*   `image` (_ProductMediaRepresentation_)
*   `variationAttributes` (_array of ProductAttributeSummaryRepresentation_) List of attributes representing product variations
*   `canViewProduct` (_boolean_) Indicates if the product can be viewed  
    Example: `true`.
*   `success` (_boolean_) Indicates if the product retrieval was successful  
    Example: `true`.
*   `error` (_ErrorResponseRepresentation_)

### ProductSellingModelRepresentation

ProductSellingModelRepresentation

*   `id` (_string (uuid)_) Unique identifier for the selling model.  
    Example: `64bf835f-ada9-4538-b5a3-f4ed8672c7b5`.
*   `name` (_string_) Name of the selling model.  
    Example: `Term Defined`.
*   `sellingModelType` (_string_) Type of the selling model.  
    Allowed values: `OneTime`, `TermDefined`, `Evergreen`. Example: `TermDefined`.
*   `pricingTerm` (_integer_) The term for pricing in the selling model.  
    Example: `1`.
*   `pricingTermUnit` (_string_) Unit of the pricing term.  
    Allowed values: `Months`, `Annual`. Example: `Months`.
*   `subscriptionTermRule` (_SubscriptionTermRuleRepresentation_)
*   `displayName` (_string_) Display name of the selling model.  
    Example: `Monthly Subscription`.
*   `description` (_string_) Description of the selling model.  
    Example: `This selling model offers a monthly subscription with a fixed term.`.

### CommerceSubscriptionBillingSummaryRepresentation

CommerceSubscriptionBillingSummaryRepresentation

*   `currencyIsoCode` (_string_) ISO code for the currency used in billing.  
    Example: `USD`.
*   `billingMethod` (_string_) Method of billing.  
    Example: `OrderAmount`.
*   `billingTerm` (_integer_) The term duration for billing.  
    Example: `1`.
*   `billingTermUnit` (_string_) Unit of the billing term.  
    Example: `Month`.
*   `billingType` (_string_) Type of billing.  
    Example: `Advance`.
*   `billingPeriodAmount` (_string_) Amount to be billed for each period.  
    Example: `500`.
*   `nextBillingDate` (_string (date-time)_) The date for the next billing.  
    Example: `2023-08-01T11:41:45.040Z`.
*   `cancellationDate` (_string (date-time)_) The date the subscription was or will be canceled.  
    Example: `2024-08-29T11:41:45.040Z`.

### Application

Application

Application through which the payment was submitted.

Type: `string`.

Allowed values: `Commerce`, `OrderManagement`, `Payments`, `Revenue`, `FieldService`, `Scheduler`, `Collections`, `Service`, `Sales`, `Custom`.

### StandardReferenceInputRepresentation

StandardReferenceInputRepresentation

Wraps a map of standard field reference names and their corresponding IDs.

*   `asMap` (_object_) Map of standard field reference names and their corresponding IDs.
    
    Additional properties: `string`.
    

### CustomFieldInputRepresentation

CustomFieldInputRepresentation

Wraps a map of custom field names and their corresponding values.

*   `asMap` (_object_) Map of custom field names and their corresponding values.
    
    Additional properties: `object`.
    

### RecordFieldRepresentation

RecordFieldRepresentation

A generic record field object with type, label and text.

*   `type` (_string_) The type of the record field.  
    Example: `string, int, currency`.
*   `label` (_string_) The label for the record field.  
    Example: `Account, Billing Address, Status`.
*   `dataName` (_string_) The data name associated with the field.  
    Example: `isBuyer`.
*   `dataType` (_string_) The data type of the field.  
    Example: `xsd:string`.
*   `text` (_string_) The textual content of the field.  
    Example: `Created, 34`.

### ProductMediaRepresentation

ProductMediaRepresentation

*   `id` (_string (uuid)_) Unique identifier for the media.  
    Example: `64bf835f-ada9-4538-b5a3-f4ed8672c7b5`.
*   `url` (_string (uri)_) URL to the media resource.  
    Example: `/cms/delivery/media/MC2KSOOFJGRZDDJGQG4QJHLKHTZQ?recordId=01tRO000000FVNB&buyerId=001RO000001npBo`.
*   `thumbnailUrl` (_string (uri)_) URL to the thumbnail of the media.  
    Example: `/img/b2b/default-thumbnail-product-image.svg`.
*   `title` (_string_) Title of the media.  
    Example: `tshirt 5`.
*   `alternateText` (_string_) Alternate text for the media, used for accessibility.  
    Example: `Pack of TShirt, 2oz - 6 pack`.
*   `sortOrder` (_integer_) Sort order of the media among others.  
    Example: `0`.
*   `mediaType` (_string_) Type of media  
    Allowed values: `IMAGE`, `VIDEO`, `DOCUMENT`.
*   `contentVersionId` (_string (uuid)_) Unique identifier for the content version associated with the media.

### ProductAttributeSummaryRepresentation

ProductAttributeSummaryRepresentation

*   `apiName` (_string_) API name of the product attribute.  
    Example: `size`.
*   `label` (_string_) Display label for the product attribute.  
    Example: `Size`.
*   `value` (_string_) Value of the product attribute.  
    Example: `Medium`.
*   `sequence` (_integer_) The sequence or order of the attribute among other attributes.  
    Example: `1`.

### SubscriptionTermRuleRepresentation

SubscriptionTermRuleRepresentation

*   `minimum` (_integer_) The minimum term for the subscription.  
    Example: `5`.
*   `maximum` (_integer_) The maximum term for the subscription.  
    Example: `15`.
*   `increment` (_integer_) The increment value between terms for the subscription.  
    Example: `5`.

### SavedPaymentMethodAbstractOutputRepresentation

SavedPaymentMethodAbstractOutputRepresentation

Payment saved payment method output representation.

*   `gatewayResponse` (_object_) Gateway response representation for a saved payment method.
    
    Additional properties: `any`.
    

### TerminalConnectionTokenInputRepresentation

TerminalConnectionTokenInputRepresentation

Terminal Connection Token Connect Input Rep

*   `paymentGatewayId` (_string_) Set Gateway Account Id

<!-- document id=b324ee822f5dcd0f308758169000c18b2af43c24efbf366fd571f60ef3436eb2 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/references/generated-api-specs/comm-payments-management-ref.md -->

Salesforce Payments Management API

# Salesforce Payments Management API

The Salesforce Management API offers a set of resources for merchants for managing payments configuration or capturing or making refunds on buyer's behalf.

**Version:** 66.0

## Servers

*   `https://api.salesforce.com/services/data/{version}`
    *   `version (default v66.0): v66.0, v65.0, v64.0`

## Operations

### GET Retrieve the payment settings associated with a specific channel.

`GET /commerce/management/channels/${channelId}/payment/settings`

Operation ID: `getChannelPaymentSettings`.

#### Parameters

*   `channelId` (path, string, required, style: simple) ID of the channel.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `ChannelPaymentSettingsOutputRepresentation`.
    
    _Example: GetPaymentSettingsSuccess_ Details of the channel payment settings.
    
    ```
    {
      "merchantAccountId": "8zbSG0000009Rc5YAE",
      "stripeAccountId": "acct_1PYNXfIdWE9Sjzxm",
      "paymentMethodSetDevName": "AMER_US",
      "isSavedPaymentMethodSharingEnabled": true,
      "isManualCaptureEnabled": true,
      "isBusinessAchEnabled": true
    }
    ```
    
*   **401** Unauthorized Access
    
    Media type: `application/json`.
    
    _Example: NoAccessError_ User do not have right permission
    
    ```
    {
      "errorCode": "UNAUTHORIZED_ACCESS",
      "message": "You don't have access to this resource."
    }
    ```
    
*   **404** Resource Not Found
    
    Media type: `application/json`.
    
    _Example: InvalidChannelId_ Invalid ChannelId is provided
    
    ```
    {
      "errorCode": "RESOURCE_NOT_FOUND",
      "message": "Provide a valid channelId."
    }
    ```
    

### PUT Update the payment settings for a specific channel.

`PUT /commerce/management/channels/${channelId}/payment/settings`

Operation ID: `updatePaymentSettings`.

#### Parameters

*   `channelId` (path, string, required, style: simple) ID of the channel.

#### Request body

Representation of payment settings for a given channel.

Media type: `application/json`. Schema: `ChannelPaymentSettingsInputRepresentation`.

_Example: UpdateChannelMerchantAccountIdRequest_ Update merchantAccountId for the given channel

```
{
  "merchantAccountId": "8zbSG0000009Rc5YAE"
}
```

_Example: UpdateMultipleSettingsRequest_ Updating multiple payment settings for the given channel

```
{
  "merchantAccountId": "8zbSG0000009Rc5YAE",
  "isManualCaptureEnabled": false,
  "isBusinessAchEnabled": true
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `ChannelPaymentSettingsOutputRepresentation`.
    
    _Example: PutPaymentSettingsSuccess_ Updated payment settings successfully.
    
    ```
    {
      "merchantAccountId": "8zbSG0000009Rc5YAE",
      "stripeAccountId": "acct_1PYNXfIdWE9Sjzxm",
      "paymentMethodSetDevName": "AMER_US",
      "isSavedPaymentMethodSharingEnabled": true,
      "isManualCaptureEnabled": true
    }
    ```
    
*   **401** Unauthorized Access
    
    Media type: `application/json`.
    
    _Example: NoAccessError_ User do not have right user permisison
    
    ```
    {
      "errorCode": "UNAUTHORIZED_ACCESS",
      "message": "You don't have access to this resource."
    }
    ```
    
    _Example: NoAccessOnMerchantAccount_ User don't have access to the merchant account.
    
    ```
    {
      "errorCode": "NO_ACCESS",
      "message": "You don't have access to the provided merchant account."
    }
    ```
    
*   **404** Resource Not Found
    
    Media type: `application/json`.
    
    _Example: InvalidChannelId_ Invalid channelId is provided
    
    ```
    {
      "errorCode": "RESOURCE_NOT_FOUND",
      "message": "Provide a valid channelId."
    }
    ```
    
    _Example: InvalidMerchantAccountId_ Invalid merchantAccountId is provided.
    
    ```
    {
      "errorCode": "INVALID_MERCHANT_ACCOUNT_ID",
      "message": "Provide a valid merchantAccountId."
    }
    ```
    

### POST Capture a payment. User must have Payments Manager permission.

`POST /payments/payment-intents/{paymentGuidOrPaymentIntentId}/capture`

Operation ID: `capturePayment`.

#### Parameters

*   `paymentIntentId` (path, string, required) The payment GUID or payment intent id.
*   `Idempotency-Key` (header, string, required) Idempotency key used for the payment request. This key is generated by the caller of this API to guarantee a unique request.

#### Request body

Media type: `application/json`. Schema: `BasePaymentActionInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CaptureServiceOutputRepresentation`.
    
*   **400** Bad Request
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `INVALID_ID_FIELD`.
    *   `message` (_string_) The error message.  
        Example: `Invalid identifier <some id>`.
*   **401** Unauthorized
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `UNAUTHORIZED`.
    *   `message` (_string_) The error message.  
        Example: `Unauthorized access`.
*   **403** Forbidden
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `FORBIDDEN`.
    *   `message` (_string_) The error message.  
        Example: `Forbidden access`.
*   **404** Not Found
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `NOT_FOUND`.
    *   `message` (_string_) The error message.  
        Example: `Resource not found`.
*   **409** Conflict
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `CONFLICT`.
    *   `message` (_string_) The error message.  
        Example: `Resource conflict`.
*   **500** Internal Server Error
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `INTERNAL_SERVER_ERROR`.
    *   `message` (_string_) The error message.  
        Example: `An unexpected error occurred`.

### POST Creates a refund (full or partial) for a payment. User must have Payments Manager permission.

`POST /payments/payment-intents/{paymentGuidOrPaymentIntentId}/refund`

Operation ID: `refundPayment`.

#### Parameters

*   `paymentIntentId` (path, string, required) The payment GUID or payment intent id.
*   `Idempotency-Key` (header, string, required) Idempotency key used for the payment request. This key is generated by the caller of this API to guarantee a unique request.

#### Request body

Media type: `application/json`. Schema: `RefundInputRepresentation`.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `RefundServiceOutputRepresentation`.
    
*   **400** Bad Request
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `INVALID_ID_FIELD`.
    *   `message` (_string_) The error message.  
        Example: `Invalid identifier <some id>`.
*   **401** Unauthorized
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `UNAUTHORIZED`.
    *   `message` (_string_) The error message.  
        Example: `Unauthorized access`.
*   **403** Forbidden
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `FORBIDDEN`.
    *   `message` (_string_) The error message.  
        Example: `Forbidden access`.
*   **404** Not Found
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `NOT_FOUND`.
    *   `message` (_string_) The error message.  
        Example: `Resource not found`.
*   **409** Conflict
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `CONFLICT`.
    *   `message` (_string_) The error message.  
        Example: `Resource conflict`.
*   **500** Internal Server Error
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `INTERNAL_SERVER_ERROR`.
    *   `message` (_string_) The error message.  
        Example: `An unexpected error occurred`.

### GET Retrieve a list of Apple Pay domains.

`GET /payments/merchant-accounts/{merchantAccountId}/apple-pay-domains`

Operation ID: `retrieveApplePayDomains`. Tags: Apple Pay Domain.

#### Parameters

*   `merchantAccountId` (path, string, required) Salesforce Payments merchant account ID associated with the Apple Pay domain.

#### Responses

*   **200** Successful operation
    
    Media type: `application/json`. Schema: `ApplePayDomainOutputCollectionRepresentation`.
    
*   **401** Unauthorized
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `UNAUTHORIZED`.
    *   `message` (_string_) The error message.  
        Example: `Unauthorized access`.
*   **403** Forbidden
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `FORBIDDEN`.
    *   `message` (_string_) The error message.  
        Example: `Forbidden access`.
*   **500** Internal Server Error
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `INTERNAL_SERVER_ERROR`.
    *   `message` (_string_) The error message.  
        Example: `An unexpected error occurred`.

### POST Register an Apple Pay domain with the payment gateway.

`POST /payments/merchant-accounts/{merchantAccountId}/apple-pay-domains`

Operation ID: `registerApplePayDomain`. Tags: Apple Pay Domain.

#### Parameters

*   `merchantAccountId` (path, string, required) Salesforce Payments merchant account ID associated with the Apple Pay domain.

#### Request body (required)

Media type: `application/json`. Schema: `ApplePayDomainInputRepresentation`.

#### Responses

*   **200** Successful operation
    
    Media type: `application/json`. Schema: `ApplePayDomainOutputRepresentation`.
    
*   **401** Unauthorized
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `UNAUTHORIZED`.
    *   `message` (_string_) The error message.  
        Example: `Unauthorized access`.
*   **403** Forbidden
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `FORBIDDEN`.
    *   `message` (_string_) The error message.  
        Example: `Forbidden access`.
*   **500** Internal Server Error
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `INTERNAL_SERVER_ERROR`.
    *   `message` (_string_) The error message.  
        Example: `An unexpected error occurred`.

### DELETE Unregisters an Apple Pay domain from the payment gateway.

`DELETE /payments/merchant-accounts/{merchantAccountId}/apple-pay-domains/{applePayDomainId}`

Operation ID: `unregisterApplePayDomain`. Tags: Apple Pay Domain.

#### Parameters

*   `merchantAccountId` (path, string, required) Salesforce Payments merchant account ID associated with the Apple Pay domain.
*   `applePayDomainId` (path, string, required) Unique identifier used by Apple to recognize your business for Apple Pay transactions.

#### Responses

*   **204** Successful operation
*   **401** Unauthorized
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `UNAUTHORIZED`.
    *   `message` (_string_) The error message.  
        Example: `Unauthorized access`.
*   **403** Forbidden
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `FORBIDDEN`.
    *   `message` (_string_) The error message.  
        Example: `Forbidden access`.
*   **404** Not Found
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `NOT_FOUND`.
    *   `message` (_string_) The error message.  
        Example: `Resource not found`.
*   **500** Internal Server Error
    
    Media type: `application/json`. Schema: `object`.
    
    *   `errorCode` (_string_) The error code.  
        Example: `INTERNAL_SERVER_ERROR`.
    *   `message` (_string_) The error message.  
        Example: `An unexpected error occurred`.

## Schemas

### ChannelPaymentSettingsOutputRepresentation

*   `merchantAccountId` (_string_) Salesforce Payments merchant account ID associated with the channel.
*   `stripeAccountId` (_string_) ID of the Stripe account associated with the payment channel.
*   `paymentMethodSetDevName` (_string_) Developer name of the configured payment method set for the channel.
*   `isSavedPaymentMethodSharingEnabled` (_boolean_) Indicates whether saved payment method sharing is enabled for the channel (true) or not (false). This field is applicable for the B2B channel.
*   `isManualCaptureEnabled` (_boolean_) Indicates whether manual capture is enabled for the channel (true) or not (false).
*   `isBusinessAchEnabled` (_boolean_) Indicates whether the business ACH is enabled for the channel (true) or not (false).

### ChannelPaymentSettingsInputRepresentation

*   `merchantAccountId` (_string_) Salesforce Payments merchant account ID associated with the channel.
*   `isSavedPaymentMethodSharingEnabled` (_boolean_) Indicates whether saved payment method sharing is enabled for the channel (true) or not (false). This field is applicable for the B2B channel.
*   `isManualCaptureEnabled` (_boolean_) Indicates whether manual capture is enabled for the channel (true) or not (false).
*   `isBusinessAchEnabled` (_boolean_) Indicates whether the business ACH is enabled for the channel (true) or not (false).

### BasePaymentActionInputRepresentation

*   `amount` (_number_, required) Amount of the payment intent, specified in the currency associated with the payment.

_Example_

```
{
  "amount": 2.12
}
```

### CaptureServiceOutputRepresentation

Capture output representation.

Includes all fields of `PaymentServiceOutputRepresentation`.

### RefundInputRepresentation

Includes all fields of `BasePaymentActionInputRepresentation`.

*   `reason` (_string_, required) Reason for the refund. Required only for refunds.  
    Allowed values: `duplicate`, `fraudulent`, `requested_by_customer`.

_Example_

```
{
  "reason": "duplicate"
}
```

### RefundServiceOutputRepresentation

Capture output representation.

Includes all fields of `PaymentServiceOutputRepresentation`.

### ApplePayDomainOutputCollectionRepresentation

*   `domains` (_array of ApplePayDomainOutputRepresentation_)

### ApplePayDomainInputRepresentation

*   `domain` (_string_, required) Required. Domain to be registered for Apple Pay. A valid domain name must use HTTPS, and must not contain a port, path, query parameter, or fragment. Valid domain examples include [https://salesforce.com](https://salesforce.com) and [https://www.mysite.com](https://www.mysite.com).

### ApplePayDomainOutputRepresentation

*   `id` (_string_) Unique identifier of the registered Apple Pay domain.
*   `domain` (_string_) Registered domain of the Apple Pay domain.
*   `status` (_string_) Status of the Apple Pay domain registration.

### PaymentServiceOutputRepresentation

PaymentServiceOutputRepresentation

List of initiated payment intents.

*   `error` (_ErrorResponseRepresentation_)
*   `gatewayRefId` (_string_) Identifier of the gateway response.
*   `gatewayResponse` (_object_) Response from the payment gateway request.
    
    Additional properties: `any`.
    
*   `guid` (_string_) Unique identifier of the payment intent request.
*   `paymentGatewayId` (_string_) ID of the Salesforce Payment Gateway object.
*   `status` (_string_) Status of payment intent, such as created, processing, succeed.

### ErrorResponseRepresentation

ErrorResponseRepresentation

An error representation containing an error code and error message.

*   `errorCode` (_string_) Error code.  
    Example: `401`.
*   `errorMessage` (_string_) Message stating the reason for error, if any.  
    Example: `Some error message`.

<!-- document id=9d554af12bf26b6c8fdb9c0d18db02a1ef36c8ba4049e554704abcc4e6036b16 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-sample-checkout-component.md -->

# Sample Custom Checkout Component

The Terms and Conditions sample component shows how to create a custom checkout component for a B2B or B2C store created with an LWR template. You can add a Terms and Conditions component to any section of your Checkout page, but we recommend placing it after the Payment component.

The Terms and Conditions component presents a checkbox to the customer. If the customer accepts the terms and conditions by selecting the box, they can continue the checkout process. Otherwise, the component blocks the checkout process. The checkbox text links to a page that describes your store’s terms and conditions, which you provide.

This example shows a Terms and Conditions component (1) placed in its own Terms and Conditions section after the Payment section.

![Terms and Conditions Checkbox](https://developer.salesforce.com/media/d2c-commerce/terms_and_conditions.png)

You need four files to implement the Terms and Conditions component.

The first file is the LWC template: `terms.html`

```xml

<template>
    <div>
        <input
            type="checkbox"
            id="termsandconditions"
            name="terms"
            checked={checked}
            onchange={handleChange}
        ></input>
        <label class="slds-p-left_x-small" for="termsandconditions">
            <lightning-formatted-rich-text
                value={disclaimerLink}
            ></lightning-formatted-rich-text>
        </label>
    </div>
    <label if:true={showError} class="slds-text-color_error">
        {error}
    </label>
</template>

```

The second file is the JavaScript component: `terms.js`:

```javascript
import { LightningElement, api } from "lwc";

import { useCheckoutComponent } from "commerce/checkoutApi";

const CheckoutStage = {
  CHECK_VALIDITY_UPDATE: "CHECK_VALIDITY_UPDATE",
  REPORT_VALIDITY_SAVE: "REPORT_VALIDITY_SAVE",
  BEFORE_PAYMENT: "BEFORE_PAYMENT",
  PAYMENT: "PAYMENT",
  BEFORE_PLACE_ORDER: "BEFORE_PLACE_ORDER",
  PLACE_ORDER: "PLACE_ORDER",
};

/**
 * Terms and Conditions has a link to the terms and conditions for the
 * checkout user to read and a checkbox to accept the terms. Place order
 * should be blocked by this component when placed in the payment step
 * before or after the payment component.
 *
 * One page layout: this component may be placed anywhere.
 *
 * Accordion layout: this component may be placed in its own section
 * before the payment section or directly in the payment section
 * before or after the payment component.
 */
export default class CheckoutTerms extends useCheckoutComponent(LightningElement) {
  _checkedByDefault = false;
  checked = false;
  showError = false;

  // The message to show to the shopper
  @api
  disclaimer = "I accept the [[Terms and Conditions]]";

  // The link to the page containing the terms and conditions
  @api
  link = "/s/terms-and-conditions";

  // The error message instructing the user to accept the terms
  @api
  error = "Please click the checkbox to accept the terms and conditions";

  /**
   * The terms may be checked by default from the builder property panel.
   */
  @api
  get checkedByDefault() {
    return this._checkedByDefault;
  }

  set checkedByDefault(value) {
    this._checkedByDefault = value;
    this.checked = value;
  }

  /**
   * Embed a link directing in the disclaimer string.
   */
  get disclaimerLink() {
    if (
      this.disclaimer.indexOf("[[") > 0 &&
      this.disclaimer.indexOf("[[") << this.disclaimer.indexOf("]]")
    ) {
      return this.disclaimer
        .replace(
          "[[",
          `<a href="${this.link}"
                            target="termsandconditions">`,
        )
        .replace("]]", "</a>");
    }

    return `<a href="${this.link}"
        target="termsandconditions">${this.disclaimer}</a>`;
  }

  /**
   * update form when our container asks us to
   */
  stageAction(checkoutStage /*CheckoutStage*/) {
    switch (checkoutStage) {
      case CheckoutStage.CHECK_VALIDITY_UPDATE:
        return Promise.resolve(this.checkValidity());
      case CheckoutStage.REPORT_VALIDITY_SAVE:
        return Promise.resolve(this.reportValidity());
      default:
        return Promise.resolve(true);
    }
  }

  /**
   * Return true when terms checkoutbox is checked
   */
  checkValidity() {
    return !this.checked;
  }

  /**
   * Return true when terms checkbox is checked
   */
  reportValidity() {
    this.showError = !this.checked;

    if (this.showError) {
      this.dispatchUpdateErrorAsync({
        groupId: "TermsAndConditions",
        type: "/commerce/errors/checkout-failure",
        exception: "Terms and Conditions must be accepted first by clicking the checkbox",
      });
    }

    return this.checked;
  }

  /**
   * Check and uncheck the checkbox. Show error unless checked.
   * @param {*} event
   */
  handleChange(event) {
    this.checked = event.target.checked || false;
    this.showError = !this.checked;
  }
}
```

The third file is the component’s metadata: `terms.js-meta.xml`

```xml
<?xml version="1.0" encoding="UTF-8"?>
<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
  <apiVersion>56.0</apiVersion>
  <isExposed>true</isExposed>
  <masterLabel>Terms and Conditions</masterLabel>
  <targets>
    <target>lightningCommunity__Page</target>
    <target>lightningCommunity__Default</target>
  </targets>
  <targetConfigs>
    <targetConfig targets="lightningCommunity__Default">
      <property
        label="Checked by Default"
        name="checkedByDefault"
        type="Boolean"
        default="false"/>
      <property
        label="Disclaimer"
        name="disclaimer"
        type="String"
        default="By clicking, you are confirming that your have read, understand and agree to the [[Terms and Conditions]]"/>
      <property
        label="Link URL"
        name="link"
        type="String"
        default="/s/terms-and-conditions"/>
      <property
        label="Error Message"
        name="error"
        type="String"
        default="Please click the checkbox to accept the terms and conditions"/>
    </targetConfig>
 </targetConfigs>
</LightningComponentBundle>
```

And the fourth file is a checkout icon: `terms.svg`:

```nolang

<svg viewBox="0 0 52 52"
    width="52"
    height="52"
    xmlns="http://www.w3.org/2000/svg"
    xmlns:bx="https://boxy-svg.com">
    <rect width="100%" height="100%" fill="#225f8c"/>
    <path d="M 34.996 27.173
             C 41.499 27.169 45.571 33.914 42.324 39.316
             C 39.077 44.718 30.947 44.724 27.689 39.328
             C 26.944 38.093 26.552 36.692 26.553 35.265
             C 26.562 30.8 30.336 27.181 34.996 27.173
             Z
             M 21.34 34.522
             C 23.637 34.522 25.072 36.904 23.923 38.81
             C 22.776 40.716 19.906 40.716 18.757 38.81
             C 18.496 38.375 18.357 37.883 18.357 37.381
             C 18.357 35.802 19.693 34.522 21.34 34.522
             Z
             M 38.075 31.976 L 33.556 36.83 L 31.513 34.85
             C 31.283 34.634 30.914 34.634 30.685 34.85
             L 29.857 35.615
             C 29.634 35.798 29.61 36.12 29.804 36.33
             L 29.857 36.387
             L 32.706 39.074
             C 32.931 39.292 33.236 39.416 33.556 39.418
             C 33.875 39.427 34.183 39.302 34.399 39.074
             L 39.76 33.449
             C 39.926 33.239 39.926 32.946 39.76 32.734
             L 38.925 31.984 C 38.695 31.768 38.327 31.768 38.098 31.984
             L 38.075 31.976
             Z
             M 12.272 9.054
             C 13.046 9.072 13.72 9.561 13.95 10.269
             L 14.412 11.812
             L 40.73 11.812 C 41.345 11.797 41.859 12.26 41.879 12.849
             C 41.886 12.964 41.871 13.077 41.834 13.185
             L 38.717 23.657
             C 38.663 23.89 38.525 24.098 38.329 24.243
             C 37.245 23.944 36.122 23.791 34.996 23.785
             C 33.602 23.794 32.221 24.036 30.916 24.5
             L 20.595 24.5
             C 19.689 24.492 18.947 25.19 18.939 26.058
             C 18.938 26.241 18.97 26.423 19.036 26.595
             L 19.036 26.651
             C 19.247 27.34 19.906 27.811 20.654 27.81
             L 25.949 27.81
             C 25.071 28.789 24.373 29.903 23.883 31.105
             L 18.089 31.105
             C 17.307 31.11 16.62 30.612 16.411 29.889 L 11.004 12.356
             L 9.386 12.356
             C 8.412 12.341 7.635 11.574 7.648 10.641
             L 7.648 10.597
             C 7.762 9.706 8.56 9.04 9.497 9.054
             L 12.272 9.054 Z"
             style="paint-order: fill; fill: rgb(255, 255, 255);" bx:origin="0.507 0.496"/>
</svg><svg viewBox="0 0 52 52" width="52" height="52" xmlns="http://www.w3.org/2000/svg" xmlns:bx="https://boxy-svg.com">
    <rect width="100%" height="100%" fill="#225f8c"/>
    <path d="M 34.996 27.173 C 41.499 27.169 45.571 33.914 42.324 39.316 C 39.077 44.718 30.947 44.724 27.689 39.328 C 26.944 38.093 26.552 36.692 26.553 35.265 C 26.562 30.8 30.336 27.181 34.996 27.173 Z M 21.34 34.522 C 23.637 34.522 25.072 36.904 23.923 38.81 C 22.776 40.716 19.906 40.716 18.757 38.81 C 18.496 38.375 18.357 37.883 18.357 37.381 C 18.357 35.802 19.693 34.522 21.34 34.522 Z M 38.075 31.976 L 33.556 36.83 L 31.513 34.85 C 31.283 34.634 30.914 34.634 30.685 34.85 L 29.857 35.615 C 29.634 35.798 29.61 36.12 29.804 36.33 L 29.857 36.387 L 32.706 39.074 C 32.931 39.292 33.236 39.416 33.556 39.418 C 33.875 39.427 34.183 39.302 34.399 39.074 L 39.76 33.449 C 39.926 33.239 39.926 32.946 39.76 32.734 L 38.925 31.984 C 38.695 31.768 38.327 31.768 38.098 31.984 L 38.075 31.976 Z M 12.272 9.054 C 13.046 9.072 13.72 9.561 13.95 10.269 L 14.412 11.812 L 40.73 11.812 C 41.345 11.797 41.859 12.26 41.879 12.849 C 41.886 12.964 41.871 13.077 41.834 13.185 L 38.717 23.657 C 38.663 23.89 38.525 24.098 38.329 24.243 C 37.245 23.944 36.122 23.791 34.996 23.785 C 33.602 23.794 32.221 24.036 30.916 24.5 L 20.595 24.5 C 19.689 24.492 18.947 25.19 18.939 26.058 C 18.938 26.241 18.97 26.423 19.036 26.595 L 19.036 26.651 C 19.247 27.34 19.906 27.811 20.654 27.81 L 25.949 27.81 C 25.071 28.789 24.373 29.903 23.883 31.105 L 18.089 31.105 C 17.307 31.11 16.62 30.612 16.411 29.889 L 11.004 12.356 L 9.386 12.356 C 8.412 12.341 7.635 11.574 7.648 10.641 L 7.648 10.597 C 7.762 9.706 8.56 9.04 9.497 9.054 L 12.272 9.054 Z" style="paint-order: fill; fill: rgb(255, 255, 255);" bx:origin="0.507 0.496"/>
</svg>
```

<!-- document id=1aa289335bf06b1369e724dcafa27d967738a168a7e8c5d1d6c25974fbb4be13 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-guest-jwt-sample-flow.md -->

# Sample Flow: Authorizing Guest Users and Calling Commerce APIs

Once the external client app is set up and you have the consumer details, including Consumer Key and Consumer Secret, you're ready to use the Headless Guest Flow. Issue identifiers in the form of unique visitor IDs (UVIDs) for these unknown visitors with the Headless Guest Flow. See [Headless Identity APIs: Headless Guest Flow for Public Clients](https://help.salesforce.com/s/articleView?id=sf.external_identity_headless_guest_flow.htm&type=5) for more information.

## Request Authorization Code for the Guest User

### Authorization

The first step is to authorize the guest user. The following is an example of an authorization request.

**Endpoint:** `(POST) https://<domain>.site.com/<site ID>/services/oauth2/authorize`

**Request**

**Header:**

```json
Uvid-Hint: UVID abcd-1234-efgh
Auth-Request-Type: guest
```

**Body:**

```json
response_type=code_credentials&
client_id=***********&
redirect_uri=https://www.MyExperienceCloudSite.my.site.com/services/oauth2/echo&
code_challenge=********&
scope=openid
```

**Response**

Salesforce validates the UVID and authorizes the guest user. If the UVID was passed as a JWT-based access token, Salesforce checks the validity of the token. The API returns the code response with the authorization and other parameters.

```json
{
  "code": "aPrxhgBwK8L6...",
  "state": "optional_state_parameter"
}
```

### Token Exchange (Tokenization)

After authorization is complete, exchange the authorization code for a JWT access token.

**Header:**

```json
Uvid-Hint: UVID abcd-1234-efgh
Auth-Request-Type: guest
```

**Note:** For guest user authentication flows, include the Uvid-Hint and Auth-Request-Type guest headers in the token request. Requests that omit these headers can return an unknown_error response.

**Endpoint:** `(POST) https://<domain>.site.com/<site ID>/services/oauth2/token`

**Request**

**Body:**

```json
grant_type=authorization_code
code={AUTHORIZATION_CODE} /*Received using the Authorize POST request*/
client_id={CONSUMER_KEY}
client_secret={CONSUMER_SECRET}
redirect_uri={CALLBACK_URL}
```

**Response**

Your app processes the access token response and creates a guest session, persisting the UVID value.

```json
{
  "access_token": "00D5g000000xxxx!AQwAQH...",
  "token_format": "jwt",
  "token_type": "Bearer"
}
```

## Use Commerce APIs

Use the JWT token to interact with Commerce APIs.

### Create Cart

**Endpoint:** `(POST) https://<domain>.site.com/<site ID>/services/data/vXX.X/commerce/webstores/{webstoreId}/carts?currencyIsoCode=USD&language=en-US&asGuest=true&htmlEncode=false`

See [Commerce Webstore, Create Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts.htm) for more information.

### Add Items to Cart

**Endpoint:** `(POST) https://<domain>.site.com/<site ID>/services/data/vXX.X/commerce/webstores/{webstoreId}/carts/{cartId}/cart-items?currencyIsoCode=USD&language=en-US&asGuest=true&htmlEncode=false`

See [Commerce Webstore, Add Items to Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm) for more information.

### Checkout Flow

**Start Checkout:**

**Endpoint:** `(POST) https://<domain>.site.com/<site ID>/services/data/vXX.X/commerce/webstores/{webstoreId}/carts/{cartId}/checkouts?currencyIsoCode=USD&language=en-US&asGuest=true&htmlEncode=false`

To continue with the checkout process, choose the Checkout API that best fits your implementation requirements:

- [Commerce Webstore, Checkout Orders](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkout.htm)—Single-step order placement.
- [Commerce Webstore Checkout, Place Order Action](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkout_place_order.htm)—Two-step process: Prepare and Submit.

<!-- document id=cfca3c72124ed19325a0fbe94b2344797398c5ebccfbf316a9f1d73d529f6eab url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-saved-payment-method-overview.md -->

# Saved Payment Method Creation Methods

You can create a Saved Payment Method (SPM) in Salesforce several ways, depends on the origin of the payment information and how the payment information is collected. These options support common integration patterns while ensuring payment details are securely stored and managed in Salesforce.

Choose the method that best fits your payment flow and integration requirements.

- [Saved Payment Method API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-payments-ref?meta=createSavedPaymentMethod)—Create Saved Payment Methods using client-side tokenization with native payment gateways, such as Stripe and Adyen. This API is primarily used internally by Storefront pages or Experience Cloud sites.
- [Tokenize Payment Method API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-ccs-payments-ref?meta=tokenizePaymentMethod)—Tokenize raw card or bank account details to generate a payment token. When `Autopay` is set to true for recurring payments, you can create a Saved Payment Method directly from the tokenized data.
- [Import Tokenized Payments](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-spm-import-tokens-overview.md)—Import previously tokenized payment methods into Salesforce as Saved Payment Methods. Use this option when migrating existing customers and payment data to Salesforce.
- [Buyer-Facing Client-Side Component](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-spm-client-side-component.md)—Create Saved Payment Methods from buyer-facing client-side components. This approach enables customers to onboard any payment method, including those not defined in the Saved Payment Method type. This option is available only to customers using third-party payment gateways.

<!-- document id=9cf9e418d45261b7c698e1dd8d37997def2c6402df927942e8be4142f14a7ea8 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/server-side-web-tier-caching.md -->

# SCAPI Caching

SCAPI caches eligible GET responses in a two-tier cache to reduce latency and load on the origin. A request passes through the tiers in the following order:

```text
Shopper  →  SCAPI CDN cache (edge)  →  Web-tier cache (origin)  →  B2C Commerce application
```

- **Web-tier cache (origin):** One of the B2C Commerce application layer components performs web-tier caching of SCAPI requests, which affects GET requests to various API families. This cache runs only after a request reaches the B2C Commerce server-side application layer. The web-tier cache is the foundation of SCAPI caching and determines what is cacheable and for how long.
- **CDN cache (edge):** An implicit Content Delivery Network (CDN) cache sits in front of the web-tier cache. It automatically caches eligible, non-personalized responses at the edge, closer to the shopper, so that repeat requests are answered without contacting the origin. For these responses, the CDN mirrors the web tier: their time-to-live and invalidation follow the web-tier behavior described on this page.

If there is another caching mechanism in place (for example, on the client side), it is still used independently. Consider this when dealing with multiple layers of caching on the front-end or client side of a storefront implementation.

**note:** The SCAPI CDN cache is distinct from the eCDN edge caching used by storefronts.

## What Is Cached

Responses to GET requests of the following APIs are cached:

### Categories

- /product/shopper-products/v1/organizations/{org-id}/categories/{id}
- /product/shopper-products/v1/organizations/{org-id}/categories

### Products

- /product/shopper-products/v1/organizations/{org-id}/products/{id}
- /product/shopper-products/v1/organizations/{org-id}/products

### Availability

- /product/shopper-availability/v1/organizations/{org-id}/availability

### Product Search

- /search/shopper-search/v1/organizations/{org-id}/product-search

### Search Suggestions

- /search/shopper-search/v1/organizations/{org-id}/search-suggestions

### Promotions

- /pricing/shopper-promotions/v1/organizations/{org-id}/promotions/campaigns

### Campaigns

- /pricing/shopper-promotions/v1/organizations/{org-id}/promotions/campaigns

### SEO URL Mapping

- /site/shopper-seo/v1/organizations/{org-id}/url-mapping

### Stores

- /store/shopper-stores/v1/organizations/{org-id}/stores

### Preferences

#### Site Custom Preferences

- /configuration/preferences/v1/organizations/{org-id}/site-custom-preferences?{siteId}

#### Global Custom Preferences

- /configuration/preferences/v1/organizations/{org-id}/global-custom-preferences

### Shopper Experience (Page Designer)

For Shopper Experience API caching details, see the [Page Designer documentation](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-designer-caching).

### Shopper Configurations

- /configuration/shopper-configurations/v1/organizations/{org-id}/configurations

### Caching Summary by API

The following table summarizes the caching status of all Shopper APIs:

| API                                          | Cached | Notes                                                                                                                                               |
| -------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shopper Products (categories, products)      | Yes    | TTL varies by expansion (60s-86400s)                                                                                                                |
| Shopper Search (product search, suggestions) | Yes    | TTL varies by expansion (60s-86400s)                                                                                                                |
| Shopper Availability                         | Yes    | 60s TTL                                                                                                                                             |
| Shopper Promotions (promotions, campaigns)   | Yes    | 3600s TTL                                                                                                                                           |
| Shopper SEO (URL mapping)                    | Yes    | 43200s TTL                                                                                                                                          |
| Shopper Stores                               | Yes    | 86400s TTL                                                                                                                                          |
| Shopper Experience (Page Designer)           | Yes    | See [Page Designer caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-designer-caching) |
| Shopper Configurations                       | Yes    | 900s TTL                                                                                                                                            |
| Preferences (Admin, site and global)         | Yes    | 300s TTL                                                                                                                                            |
| Shopper Baskets                              | **No** | Stateful/transactional - each basket is unique                                                                                                      |
| Shopper Orders                               | **No** | Stateful/transactional                                                                                                                              |
| Shopper Customers                            | **No** | Contains personal data                                                                                                                              |
| Shopper Login (SLAS)                         | **No** | Authentication endpoints                                                                                                                            |
| Shopper Payments                             | **No** | Payment configuration                                                                                                                               |
| Shopper Context                              | **No** | Per-shopper state                                                                                                                                   |
| Shopper Custom Objects                       | **No** | Dynamic data                                                                                                                                        |
| Shopper Consents                             | **No** | Per-shopper state                                                                                                                                   |
| Shopper Gift Certificates                    | **No** | Transactional (POST-based lookup)                                                                                                                   |
| Custom APIs                                  |        | See [Custom API Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-caching.md)                                                                                                     |

## Enable Caching

Page caching of dynamic content must be enabled for the specific site.

To do so, in Business Manager, navigate to **Administration** > **Sites** > **Manage Sites** > **Site Name - Cache** and select “**Enable Page Caching**”. This single setting governs both the web-tier cache and the CDN cache.

## Default Cache Expiration and Personalization Settings

How long a cache entry lives and whether the response is personalized, depends on the API and, if there are expansions available on the API, the selected expansions.

| API name             | Expansion            | Cache time-to-live, seconds (Defaults) | Is personalized (Defaults) |
| -------------------- | -------------------- | -------------------------------------- | -------------------------- |
| Categories           | N/A                  | 86400                                  | No                         |
|                      |                      |                                        |                            |
| Products             | availability         | 60                                     | No                         |
|                      | bundled_products     | 86400                                  | No                         |
|                      | images               | 86400                                  | No                         |
|                      | links                | 86400                                  | No                         |
|                      | options              | 86400                                  | No                         |
|                      | page_meta_tags       | 86400                                  | No                         |
|                      | prices               | 900                                    | Yes                        |
|                      | promotions           | 900                                    | Yes                        |
|                      | recommendations      | 86400                                  | No                         |
|                      | set_products         | 86400                                  | No                         |
|                      | shipping_methods     | 86400                                  | No                         |
|                      | variations           | 86400                                  | No                         |
|                      | none                 | 86400                                  | No                         |
|                      |                      |                                        |                            |
| Availability         | N/A                  | 60                                     | No                         |
|                      |                      |                                        |                            |
| Product Search       | availability         | 60                                     | No                         |
|                      | custom_properties    | 86400                                  | No                         |
|                      | description          | 86400                                  | No                         |
|                      | images               | 86400                                  | No                         |
|                      | page_meta_tags       | 86400                                  | No                         |
|                      | prices               | 900                                    | Yes                        |
|                      | primary_category     | 86400                                  | No                         |
|                      | promotions           | 900                                    | Yes                        |
|                      | represented_products | 86400                                  | No                         |
|                      | slug                 | 86400                                  | No                         |
|                      | variations           | 86400                                  | No                         |
|                      | none                 | 86400                                  | No                         |
|                      |                      |                                        |                            |
| Search Suggestions   | N/A                  | 900                                    | No                         |
|                      |                      |                                        |                            |
| Promotions           | N/A                  | 3600                                   | No                         |
|                      |                      |                                        |                            |
| Campaigns            | N/A                  | 3600                                   | No                         |
|                      |                      |                                        |                            |
| SEO Url Mapping      | N/A                  | 43200                                  | No                         |
|                      |                      |                                        |                            |
| Stores               | N/A                  | 86400                                  | No                         |
|                      |                      |                                        |                            |
| Configurations       | N/A                  | 900                                    | No                         |
|                      |                      |                                        |                            |
| Preferences (Site)   |                      | 300                                    | No                         |
|                      |                      |                                        |                            |
| Preferences (Global) |                      | 300                                    | No                         |

The lowest time-to-live of all the expansions decides how long the cache entry stays alive. If at least one of the requested expansions is marked as “personalized”, the whole response is considered to be personalized.

## "expand" Parameter Impact on Cache Hit Rates

The cache hit rates are greatly impacted by the expansions you select for the product and product-search endpoints. For example, if a request to the product API includes the "availability" expansion, the cache entry is stored for only 60 seconds by default. If no expand parameter is specified, all expansions are considered selected.

_Example 1_

A request to `/product/shopper-products/v1/organizations/{org-id}/products?ids=product1,product2` is made every 30 minutes. Since no expand parameter is specified, all expansions are applied, and the lowest time-to-live among them is for "availability", which is 60 seconds. Consequently, the cache hit rate is likely to remain zero because the cache entry expires before the next identical request is made.

_Example 2_

A request to `/product/shopper-products/v1/organizations/{org-id}/products?ids=product1,product2&expand=images,links,options` is made every hour. The shortest time-to-live among the specified expansions is 86400 seconds (24 hours), so the cache hit rate is expected to be high.

**note:** Due to how short the cache entry live time is for certain expansions, we recommend you make sure only necessary expansions are included in the request. For example, unnecessarily including the “availability” expansion in requests to the Products and Product Search APIs reduces the cache hit rate drastically and negatively affect the overall performance of requests. If no expand parameter is specified, all expansions are considered selected.

## Improve the Cache Hit Ratio

To get more requests served from cache:

- Request only the expansions you need, and avoid low-TTL expansions such as `availability` on requests you want cached longer. See ["expand" Parameter Impact on Cache Hit Rates](#expand-parameter-impact-on-cache-hit-rates).
- Avoid hook-based personalization. Apply personalization before the cache key is computed, through the Shopper Context API. See [Personalization and Custom Code](#personalization-and-custom-code).
- Avoid unnecessary custom query parameters, because each distinct query string is a separate cache entry.
- Track the effect of these changes with [cache statistics](#view-cache-statistics).

## Personalized Caching

When personalization is enabled for a resource, the following information becomes part of the cache key in addition to the URL string:

- The complete set of active promotions.
- The complete set of active product sorting rules.
- The complete set of applicable price books.
- The complete set of active ABTest Groups.

The cache stores different response variations in the cache and delivers the correct version to the API user based on this additional information.

Let’s think of what it means for two shoppers accessing the same product API (as in, the same URL). In this case, shopper A is eligible for promotion X, and shopper B is eligible for promotion Y. The same product (no change in URL) is cached twice. All shoppers with the promotion X are subsequently served the same respective cache entry, as are the shoppers with the promotion Y. Depending on the number of price books and promotions, this scenario can lead to a large increase in the number of cache entries, regardless of the price of the product.

**note:** Consider using personalized caching only when necessary. And only for well-sized groups of shoppers.

### The `personalized=none` Query Parameter

The `personalized=none` query parameter marks a request as non-personalized. When it is present, the B2C Commerce application skips applying personalization to the request, including the [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary), and the first computed response is reused for all subsequent shoppers of that request.

Because non-personalized responses are cacheable for a wider audience, using `personalized=none` where the content is intended to be identical for all shoppers can improve cache efficiency at both the web-tier and CDN layers.

`personalized=none` can be applied to any Shopper API except Shopper Login (SLAS) and Shopper Context. It takes precedence over custom code: if a hook marks the response as personalized with `dw.system.Response#setVaryBy(identifier)`, that call is suppressed and the response is still treated as non-personalized.

**warning:** Use `personalized=none` only for content that is intended to be identical for all shoppers.

### Personalization and Custom Code

For a new request, the web-tier first checks for the existence of a cache entry. The cache key is calculated before any hook customization is invoked, and doesn't include any changes that occur later within hooks.

#### Personalization Changes in Hooks

**note:** Personalization changes made within hook logic aren't compatible with Server-Side Web-Tier Caching.

The cache key calculation happens before any hook customization is executed, which means that any personalization changes made within hooks, such as modifying price books, promotions, or other personalization details, aren't considered during the cache key generation process.

**Step-by-Step Example:**

1. Request arrives: A shopper requests a product with promotions expansion.
2. Cache key calculation: The system calculates the cache key based on:
   - URL and query parameters
   - Other request-related factors
   - Current active promotions
   - Current applied price books
   - Current product sorting rules
   - Current AB test groups
3. Cache lookup: The system looks for an existing cache entry using the cache key.
4. If there is a cache miss: The request proceeds to processing.
5. Hook execution: Custom hooks are invoked and modify personalization details.
6. Response generation: The final response is generated with a potentially different personalization.
7. Cache storage: The response is stored with the altered cache key that reflects the changes in the personalization.

**important:** The cache key from step 2 doesn't reflect the personalization changes made in step 5, leading to:

- Incorrect cache entries being served to users
- Cache misses
- Potential performance degradation due to frequent cache misses

Changing applicable price books and promotions within hook logic causes the final cache entry to not match the original key. This causes a decrease in performance due to a lower cache hit rate. Use the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) to apply personalization changes before the cache key calculation occurs, instead of relying on hook-based personalization modifications.

#### Response Body Customization

Potential updates of the response body, such as adding custom attributes, aren't considered within the cache key. If two otherwise identical requests (URL and query string) are supposed to produce different responses solely due to conditional hook logic, the web-tier considers such requests as identical and returns the cached response. To make sure that the web-tier cache behaves correctly, append a custom query parameter to the URL.

Example:

```text
https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/{productId}?siteId={siteId}&c_customParameter=uniqueCondition
```

**note:** The customization of responses via conditional code is only cached correctly in case the condition is given as part of the URL that is, a custom query parameter. Do this only when necessary, because it can impact performance.

## Cache Expiration for Objects with a Validity Period

With B2C Commerce 24.8, set a time window, called the Validity Period, for the Shopper Products [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProduct) and [getCategory](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getCategory) endpoints and the Campaigns [getCampaign](https://developer.salesforce.com/docs/commerce/commerce-api/references/campaigns?meta=getCampaign) endpoint. The validity is considered for server-side cache expiration in order to prevent serving stale content. The attributes that define the Validity Period are `Valid From` and `Valid To`. For other resource types, the default cache expiration times are applied.

The server-side cache expiration is adjusted to reflect date and time values of `Valid From` and `Valid To` attributes if those are defined and take effect prior to the default cache expiration. Otherwise, the default expiration is applied.

For requests that contain multiple resource identifiers, such as multiple SKUs, all Validity Periods are taken into consideration when calculating cache expiration. The earliest effective date determines the cache expiration of the response.

For example, a request using a single Product SKU is cached by default for 24 hours (no additional expansions; see table above). Assuming the Product has an assigned `Valid To` time that is earlier than the default cache expiration, then the cache expiration is recalculated to reflect the shorter `Valid To` time.

![Cache validity configuration with sample values](https://developer.salesforce.com/docs/media/commerce-api/caching-validity-sample1.png)

If you use a `Valid From` time to configure a Product launch for a future date, an `HTTP 404` response code is returned. The `HTTP 404` response is also cached using a cache expiration that reflects the respective `Valid From` value. When the cache expires at that time, the Product becomes viewable for shoppers in your storefront.

![Additional cache validity settings and parameters](https://developer.salesforce.com/docs/media/commerce-api/caching-validity-sample2.png)

## Change Cache Settings Programmatically

Script API provides options to control the cache settings programmatically.

### Change Cache Time-to-Live

The `dw.system.Response#setExpires( milliseconds )` method of the Script API makes it possible to set an arbitrary cache expiration timestamp. Since the method accepts the timestamp in milliseconds, a sum of the current timestamp and desired “time-to-live” has to be passed as a parameter.

For instance, if a response for the Category API should be only cached for an hour instead of the day, the following custom code can be used:

```javascript
exports.modifyGETResponse = function (scriptCategory, categoryWO) {
  response.setExpires(Date.now() + 3600000);

  return new Status(Status.OK);
};
```

### Constraints

The cache time-to-live has to be at least one second and cannot exceed 86,400 seconds.

**note:** A TTL set with `setExpires` applies to the CDN cache entry as well; the CDN mirrors the web-tier TTL.

### Apply Personalization

The `dw.system.Response#setVaryBy( String varyBy )` method of the Script API marks the response as personalized with the given variant identifier. Only `price_promotion` is supported, and any other value has no effect.

```javascript
exports.modifyGETResponse = function (scriptCategory, categoryWO) {
  response.setVaryBy("price_promotion");

  return new Status(Status.OK);
};
```

By default, product calls with _prices_ and _promotions_ expansions, as well as product search calls with the _prices_ and _promotions_ expansions, are personalized.

## Cache Invalidation

Cache invalidation is kept in sync across both cache tiers: clearing the web-tier page cache also purges the corresponding CDN entries.

### Manual Invalidation

At the moment there is only one way to invalidate cache manually - which is to invalidate the entire site page cache.

In Business Manager, navigate to **Administration** > **Sites** > **Manage Sites** > **Site Name - Cache**, and select the **Cache** tab. In the “Cache Invalidation” section there is a button to invalidate the site page cache. Once the invalidation has been triggered, the entirety of the site page cache is cleared within 15 minutes, including the cache related to SCAPI responses. The corresponding CDN entries are purged as well.

**warning:** Doing this also invalidates all existing pipeline cache, possibly resulting in a temporary decrease in performance.

### Automated Invalidation (Replication)

A data replication that clears a site's page cache also purges the site's CDN entries automatically, keeping both cache tiers consistent with the newly published data.

As with the manual case, invalidation is not instantaneous: the clear is staggered over an interval (approximately 15 minutes) to avoid a sudden load spike on the origin.

### Cache Tags

Purge-by-tag drives CDN invalidation. Every cacheable SCAPI response carries a `Cache-Tag` response header with two tags:

```text
Cache-Tag: pc:<siteId>_<pageCacheId>,site:<siteId>
```

- `pc:<siteId>_<pageCacheId>`: identifies the site's current page cache generation (site ID plus page cache ID). When the page cache is cleared, the page cache ID changes and the entries tagged with the previous value are purged.
- `site:<siteId>`: identifies the site, so all of a site's CDN entries can be purged together.

## Cache-Control HTTP Header

With the new server-side caching in place, responses of cached endpoints always return the `Cache-Control` header value: `no-cache, no-store, must-revalidate`. This is necessary to maintain uniform behavior of SCAPI and Script Controller APIs, especially in the case of personalization.

## Cache Status Response Headers

SCAPI returns a separate cache-status response header for each cache tier: `sfdc_cache_status` for the web tier and `cf-cache-status` for the CDN edge.

### sfdc_cache_status (Web Tier)

The `sfdc_cache_status` response header provides visibility into how the **web-tier** cache resolved a request.

#### Applicability

The `sfdc_cache_status` header is calculated and assigned in the web tier and is returned for:

- Shopper API endpoints listed in the [What Is Cached](#what-is-cached) section of this page.
- Custom APIs.

#### Header Values

The `sfdc_cache_status` header returns one of the following values:

| Value           | Description                                                                     | Example         |
| --------------- | ------------------------------------------------------------------------------- | --------------- |
| `HIT [M/M]`     | Main request plus all related include requests were fully resolved from cache.  | `HIT [1/1]`     |
| `MISS [0/M]`    | No requests were resolved from cache.                                           | `MISS [0/1]`    |
| `PARTIAL [N/M]` | Request was partially resolved from cache. N is greater than 0 but less than M. | `PARTIAL [2/5]` |

#### Understand the [N/M] Notation

The notation `[N/M]` provides insight into cache efficiency:

- **M** = Total number of requests, including the main request and all related include requests.
- **N** = Number of requests that were resolved from the cache.

Because most requests don't involve include requests, M usually equals 1, making `HIT [1/1]` and `MISS [0/1]` the most common values. The `PARTIAL` status only appears if include requests are involved.

For example, if a request involves include requests and the response header shows `PARTIAL [3/5]`, it means:

- Five total requests were made (one main request + four include requests).
- Three of the five requests were served from cache.
- Two requests resulted in cache misses and were processed by the application.

Example:

```text
sfdc_cache_status: HIT [1/1]
```

**note:** `sfdc_cache_status` reflects the **web tier only**.

### cf-cache-status (CDN Edge)

The `cf-cache-status` response header reports how the **CDN** layer resolved the request. It reflects only the CDN tier.

| Value      | Description                                                                                                 |
| ---------- | ----------------------------------------------------------------------------------------------------------- |
| `HIT`      | The response was served from the CDN cache.                                                                 |
| `MISS`     | The response was not in the CDN cache; it was fetched from the origin and may now be cached.                |
| `EXPIRED`  | The resource was found in the CDN cache but had expired, so it was served from the origin.                  |
| `UPDATING` | The resource had expired but was served from the CDN cache while the origin refreshed it in the background. |
| `DYNAMIC`  | The request was not eligible for CDN caching and was served from the origin.                                |
| `BYPASS`   | The response could not be cached in the CDN because it was personalized.                                    |

### Example: How a Request Travels Through Both Cache Tiers

Consider a shopper GET request for an eligible, non-personalized resource.

**First request (both tiers empty):**

1. The CDN has no entry, so `cf-cache-status` is `MISS`. The request is forwarded to the origin.
2. The web-tier cache also has no entry, so `sfdc_cache_status` is `MISS [0/1]`. The B2C Commerce application computes the response.
3. The response is stored in the web-tier cache and in the CDN edge cache.

**Subsequent identical request (served from the edge):**

The response is returned directly from the CDN, and the origin is not contacted:

```text
cf-cache-status: HIT
```

Because the request never reaches the origin on a CDN hit, the web tier does not process it and `sfdc_cache_status` is not recalculated for that request.

**tip:** It is normal to observe `cf-cache-status: HIT` together with `sfdc_cache_status: MISS` on subsequent responses. When a request is computed for the first time, its response carries `sfdc_cache_status: MISS` (nothing was cached in the web tier yet) and is then stored in both the web-tier cache and the CDN. Because that stored copy already includes `sfdc_cache_status: MISS`, later requests resolved from the CDN return it verbatim without traveling to the web tier. This combination reflects a CDN hit on the originally computed response and is not an indicator of a problem in the web-tier cache.

## View Cache Statistics

Aggregate SCAPI cache statistics are available in Reports & Dashboards:

1. In Business Manager, click App Launcher and select **Merchant Tools** > select your site.
2. Go to **Analytics** > **Reports and Dashboards** > **Technical** > **SCAPI**.

These statistics reflect web-tier cache behavior.

## Troubleshoot Personalized Caching

If a personalized response is served incorrectly - for example, two requests that should receive different personalization return the same cached response - work through the following steps:

1. Review [Personalization and Custom Code](#personalization-and-custom-code) and confirm your implementation follows it. In particular, the cache key is computed before hooks run, so personalization changes made in hooks aren't reflected in the cache key.
2. If the behavior persists, reproduce the requests with debug logging enabled by sending the `sfdc_verbose: true` request header. See [Collect Detailed Request Information](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md#collect-detailed-request-information).
3. In the logs, inspect the [cache status response headers](#cache-status-response-headers) together with the debug log entries that begin with `Price promotion personalization hash`. These entries record the personalization inputs (promotions, price books, product sorting rules, and AB test groups) that make up the cache key.
4. Compare two requests that are expected to have different personalization. If their logged personalization inputs - and therefore their cache key - are identical, the requests resolve to the same cache entry and receive the same personalization. This indicates the differing personalization is not being applied before the cache key is computed (for example, it is applied in a hook). Apply it earlier instead, such as through the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary).

## Logout and Cached Responses

Logout invalidates tokens at the origin. On a CDN edge cache hit, the origin is never contacted, so a previously cached `200` response can still be served after logout instead of a `401`. Only responses served from the CDN cache are affected.

**warning:** Don't include personally identifiable information (PII) in responses that can be cached, including custom attributes and Custom API responses. As long as a cached response contains no PII, stale delivery after logout has no security impact.

For reference, see the following logout-related endpoints:

- [Revoke Token](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=revokeToken)
- [Logout Customer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=logoutCustomer)
- [Batch Logout](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=batchLogout)

## Alter Cache Key

**important:** Use the `Web Adapter Cache Key Ignore by Query String` feature toggle to exclude query parameters from the cache key. This applies when you want to increase the cache hit rate, but only when the query parameter does NOT influence the response in any way. Because the specified query parameters affect the caching of Salesforce Commerce APIs and Controllers, use this feature toggle with caution.

<!-- document id=76ecd6aa9d3bf678efe0b5223694dc820051099b71c28beae0cf041db6fa66b7 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-caching.md -->

# SCAPI CDN Caching

SCAPI CDN caching is documented as part of the SCAPI caching stack. See [SCAPI Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md).

<!-- document id=ae216907bdee75a9d90d87f35493ced0b7ffde13c8f2ec154f1e728e861c71fd url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_schema_conventions.md -->

# Schema Conventions

The following conventions are used throughout the schema:

- **Table Prefixes**: All tables in the warehouse schema are prefixed with `ccdw` to organize the tables into a model representing the Commerce Cloud Data Warehouse.
- **Table Types**:
  - **Dimensions** (`dim_` prefix): These tables represent business context.
  - **Facts** (`fact_` prefix): These tables represent details about a measured business process.
  - **Aggregates** (`aggr_` prefix): These tables represent aggregate data about a business process and support quick access to commonly used business questions.
- **Currency Prefixes**:
  - `lcl_`: Monetary values in the tendered currency
  - `std_`: Monetary values converted to a common reporting currency, as configured in Reports & Dashboards administration settings in Business Manager
- **Time Prefixes**:
  - `utc_`: Columns representing Universal Time Coordinated time

<!-- document id=0b366854db6afe33df1d5823b7e9675c4f7acf99c60e5d21687acac003bb9e95 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/scapi-schemas.md -->

Schemas

# Schemas

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/scapi-schemas/scapi-schemas-oas-v1-public.yaml)

## API Overview

The SCAPI Schema API provides programmatic retrieval of OpenAPI schema definitions for all B2C Commerce API (SCAPI) endpoints, which facilitates better integration, validation, and development workflows across the Commerce Cloud ecosystem.

This API serves as a central registry for all SCAPI schema definitions, allowing you to discover available APIs by family, name, and version, as well as retrieve detailed schema specifications for specific API endpoints.

### Authentication & Authorization

The SCAPI Schema API uses an Account Manager OAuth 2.0 bearer token for authentication. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account manager to log in.

The necessary scope for accessing the SCAPI Schema API is:

*   `sfcc.scapi-schemas`: Provides access to retrieve SCAPI schema definitions and listings.

You must include the relevant scope(s) in the client ID used to generate the token. For details, see [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

Access is typically intended for developers, integration tools, and administrative applications that need to programmatically work with SCAPI schema definitions.

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Schema Discovery and Cataloging

Discover all available SCAPI endpoints and their current schema versions. This is particularly useful for:

*   Development Tools: IDE plugins and code generators that need to understand available APIs
*   Integration Platforms: Systems that need to dynamically discover and adapt to available Commerce Cloud APIs
*   Documentation Systems: Tools that automatically generate API documentation or SDK references
*   Governance and Compliance: Tracking which APIs are available, their versions, and deprecation status

The API allows filtering by:

*   API family, for example: "product", "checkout", "customer
*   API name, for example: "shopper-products", "orders"
*   API version, for example: "v1", "v2"
*   Cartridge name, for example: "my\_cartridge". **Only for Custom APIs.**
*   Status, for example: "current", "deprecated"

#### Schema Validation and Code Generation

Retrieve detailed OpenAPI schema specifications to enable:

*   Request/Response Validation: Validate API requests and responses against the official schema.
*   Mock Server Creation: Generate mock servers for testing and development.
*   API Contract Testing: Ensure your implementations comply with the SCAPI specifications.

#### Version Management and Migration Planning

Track schema versions and plan migrations by:

*   Version Comparison: Compare different versions of the same API to understand changes.
*   Deprecation Tracking: Identify deprecated schemas and plan migration strategies.
*   Breaking Change Detection: Analyze schema differences to identify potential breaking changes.
*   Rollback Planning: Access historical schema versions for rollback scenarios.

#### Development Workflow Integration

Integrate schema access into your development workflows:

*   CI/CD Pipeline Integration: Validate API implementations against current schemas during build processes.
*   Local Development: Provide developers with up-to-date schema definitions for better IDE support.
*   Testing Automation: Generate comprehensive test suites based on schema definitions.
*   API Gateway Configuration: Configure API gateways with current schema definitions for validation and routing.

**Version:** 1.0.3

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/dx/scapi-schemas/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.scapi-schemas: SCAPI schema READONLY scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Get a list of known SCAPI schema definitions.

`GET /organizations/{organizationId}/schemas`

Operation ID: `getSchemaList`. Security: AmOAuth2 (sfcc.scapi-schemas).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `apiFamily` (query, ApiFamily) The API family
*   `apiName` (query, ApiName) The API name
*   `apiVersion` (query, ApiVersion) The API version
*   `cartridgeName` (query, CartridgeName) The cartridge name
*   `status` (query, string) The schema status  
    Allowed values: `current`, `deprecated`. Example: `current`.

#### Responses

*   **200** List of known SCAPI schema definitions successfully retrieved.
    
    Media type: `application/json`. Schema: `SchemaListResult`.
    
    _Example: SchemaListSuccess_
    
    ```
    {
      "limit": 1,
      "total": 3,
      "filter": {
        "apiFamily": "product",
        "apiName": "shopper-products",
        "apiVersion": "v1",
        "status": "current"
      },
      "data": [
        {
          "schemaVersion": "1.0.25",
          "apiFamily": "product",
          "apiName": "shopper-products",
          "apiVersion": "v1",
          "status": "current",
          "link": "https://api.example.com/scapi/schemas/product/shopper-products/v1"
        }
      ]
    }
    ```
    
    _Example: SchemaListSuccessNoFilter_
    
    ```
    {
      "limit": 3,
      "total": 3,
      "data": [
        {
          "schemaVersion": "1.0.25",
          "apiFamily": "product",
          "apiName": "shopper-products",
          "apiVersion": "v1",
          "status": "current",
          "link": "https://api.example.com/scapi/schemas/product/shopper-products/v1"
        },
        {
          "schemaVersion": "2.1.0",
          "apiFamily": "checkout",
          "apiName": "shopper-baskets",
          "apiVersion": "v2",
          "status": "current",
          "link": "https://api.example.com/scapi/schemas/checkout/shopper-baskets/v2"
        },
        {
          "schemaVersion": "1.5.12",
          "apiFamily": "customer",
          "apiName": "customers",
          "apiVersion": "v1",
          "status": "deprecated",
          "link": "https://api.example.com/scapi/schemas/customer/customers/v1"
        }
      ]
    }
    ```
    
*   **400** Value constraint violation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/value-constraint-violation",
      "title": "Bad Request",
      "detail": "Value for parameter 'apiFamily' violates API constraint '^[a-z0-9-]+$'"
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get a SCAPI schema specification.

`GET /organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}`

Operation ID: `getSchemaDetails`. Security: AmOAuth2 (sfcc.scapi-schemas).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `apiFamily` (path, ApiFamily, required) The API family
*   `apiName` (path, ApiName, required) The API name
*   `apiVersion` (path, ApiVersion, required) The API version
*   `expand` (query, array of string, style: form, explode: false) Optional schema expansion e.g. 'custom\_properties'.  
    Items: Allowed values: `custom_properties`. Example: `custom_properties`.
    
    _Example_
    
    ```
    [
      "custom_properties"
    ]
    ```
    

#### Responses

*   **200** SCAPI schema specifications successfully retrieved.
    
    Media type: `application/json`. Schema: `any`.
    
    Type: `any`.
    
    _Example_
    
    ```
    {}
    ```
    
*   **400** Value constraint violation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as GET /organizations/{organizationId}/schemas 400 response._
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Forbidden_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ResourceNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
      "title": "Resource Not Found",
      "detail": "Could not find requested resource"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### ApiFamily

The API family name

Type: `string`.

Maximum length: 50. Pattern: ^\[a-z0-9-\]+$. Example: `product`.

### ApiName

The API name

Type: `string`.

Maximum length: 200. Pattern: ^\[a-z0-9-\]+$. Example: `shopper-products`.

### ApiVersion

The API version

Type: `string`.

Pattern: ^v\\d+$. Example: `v1`.

### CartridgeName

The cartridge name

Type: `string`.

Pattern: ^\[a-z\_\]\[a-z0-9\_\]\*$. Example: `my_cartridge`.

### SchemaListResult

Includes all fields of `ResultBase`.

*   `filter` (_ScapiSchemaFilter_)
*   `data` (_array of SchemaListItem_) List containing all filtered schema entries.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### ScapiSchemaFilter

*   `apiFamily` (_ApiFamily_)
*   `apiName` (_ApiName_)
*   `apiVersion` (_ApiVersion_)
*   `cartridgeName` (_CartridgeName_)
*   `status` (_string_)  
    Allowed values: `current`, `deprecated`. Example: `current`.

### SchemaListItem

*   `schemaVersion` (_string_) Semantic OAS schema version  
    Pattern: ^\\d+\\.\\d+\\.\\d+$. Example: `1.0.0`.
*   `apiFamily` (_string_) The API family name  
    Maximum length: 50. Pattern: ^\[a-z0-9-\]+$. Example: `product`.
*   `apiName` (_string_) The API name  
    Maximum length: 200. Pattern: ^\[a-z0-9-\]+$. Example: `shopper-products`.
*   `apiVersion` (_string_) The API version  
    Pattern: ^v\\d+$. Example: `v1`.
*   `cartridgeName` (_string_) The cartridge name (only for Custom APIs)  
    Pattern: ^\[a-z\_\]\[a-z0-9\_\]\*$. Example: `my_cartridge`.
*   `status` (_string_)  
    Allowed values: `current`, `deprecated`. Example: `deprecated`.
*   `link` (_string_) The URL to the SCAPI schema detail endpoint  
    Maximum length: 2048. Example: `https://api.example.com/scapi/schemas/customer/customers/v1`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=f5eb32a2f8e92824a2fc8bd31e97f39c87d85cdf2bb8620ebc2141f0bafaca99 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/scriptprogramming/demandwarejavascript.md -->

# Script Programming

Use B2C Commerce JavaScript to customize your ecommerce storefront application.

For details on specific B2C Commerce Script API, see the B2C Commerce API documentation.

- Use B2C Commerce JavaScript to:

  - Add new calculations and logic to business processes
  - Create business objects (data)
  - Call web services
  - Integrate back-end systems
  - Process XML data
  - Share information across users

- Use client-side processing to:
  - Validate user input (for example, checking values entered in forms)
  - Prompt users for confirmation and showing error or informational boxes
  - Conditionalize HTML
  - Perform other functions not requiring information from the server

## Industry Standards

B2C Commerce JavaScript is based on Rhino JavaScript. Multiple language versions are supported. The active compatibility mode determines the language version. Compatibility modes earlier than 21.2 use the ECMAScript 5 language version. Compatibility modes 21.2 or later enable the latest language version that includes some ECMAScript 6 constructs. See [Compatibility Mode Changes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-compatibility-mode-considerations.md) for details.

B2C Commerce supports the following:

- Mozilla extensions up to JavaScript 1.8
- ECMAScript for XML (E4X)
- Optional type specification support from JavaScript 2.0/ECMA 4th edition proposal and ActionScript, as in the following examples:
  - `let a: String;`
  - `let p: dw.catalog.Product;`
- Nonstandard behavior for older compatibility modes.

### What Javascript Engine Does B2C Commerce Use?
On server side, B2C Commerce uses the Mozilla Rhino JavaScript engine to translate the Javascript from developers to Java that can be understood by the server. Any server side JavaScript code is executed by Rhino.

#### What Rhino version does Salesforce B2C Commerce use?
| Compatibility mode | Rhino Version | VERSION_ES6 |
| ------------------ | ------------- | ----------- |
| 22.7               | 1.7.14        | set         |
| 21.2               | 1.7.13        | set         |
| earlier ones       | 1.7R5         | not set     |

<!-- document id=995d45ac6cc739c5f81292420f2b85d42092b6750d9386f68f138c92e318e924 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-working-with-scripts.md -->

# Scripts

B2C Commerce provides a proprietary scripting language that the server interprets and includes in storefront pages as JavaScript.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Supported Data Types

B2C Commerce script supports data types that allow you to integrate extensive functionality into your scripts.

Attributes that are queryable can be found when using Advanced Search extended attributes when searching for products in Business Manager. Whether or not the data type is queryable in Business Manager doesn't affect whether the attribute is searchable in the storefront.

B2C Commerce supports the data types listed in the following table for B2C Commerce script.

| Type            | JavaScript Type                                                                                               | Description                                                                                                                                                                                                                                                                           | Queryable in Business Manager? |
| --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| String          | B2C Commerce script top-level String class                                                                    | Letters, numbers, and punctuation. Use for a word or sentence. Maximum 4000 bytes allowed.                                                                                                                                                                                            | Yes                            |
| Text            | B2C Commerce script top-level String class                                                                    | Letters, numbers, and punctuation. Use for large amounts of text, such as descriptions.                                                                                                                                                                                               | No                             |
| Html            | B2C Commerce script dw.content.MarkupText class                                                               | HTML tags. This type is intended for HTML tags and values. If editing HTML attributes, Business Manager displays an HTML editor for editing them. Editing in an HTML editor isn't possible for String or Text data types.                                                             | No                             |
| Integer         | number                                                                                                        | A number without decimal places, such as 1, 2, 3, or 4. Attribute value range is from -2,147,483,648 to 2,147,483,647 (32 bit Signed Integer)                                                                                                                                         | Yes                            |
| Number          | number                                                                                                        | A floating point number with double precision. In terms of persistency or database, the supported values are zero as well as positive and negative fixed numbers with absolute values from 1.0E-130 to but not including 1.0E126. 'NaN', 'Infinity' and '-Infinity' aren't supported. | Yes                            |
| Boolean         | boolean                                                                                                       | True or False                                                                                                                                                                                                                                                                         | Yes                            |
| Date            | B2C Commerce script top-level Date class                                                                      | MM/dd/yyyy                                                                                                                                                                                                                                                                            | Yes                            |
| Date + Time     | B2C Commerce script top-level Date class                                                                      | MM/dd/yyyy : h: mm a                                                                                                                                                                                                                                                                  | Yes                            |
| Image           | B2C Commerce script dw.content.MediaFile class                                                                | An image. Merchants can select the image from the image folder structure. Developers can use a script to dynamically retrieve an image using a pipeline.                                                                                                                              | No                             |
| Email           | string                                                                                                        | Email address. Business Manager requires the merchant to enter a valid syntax for an email address. For example, it requires a valid extension after the @ sign, among other requirements.                                                                                            | Yes                            |
| Password        | string                                                                                                        | Password. This type shows a masked field and confirmation field where the merchant can enter a password. Password data type values are encrypted on export and can be encrypted for import.                                                                                           | No                             |
| Set of String   | JavaScript array object containing string                                                                     | The attribute value is zero or more strings. Use when you want the merchant to enter one or more strings. Sets don't contain duplicates.                                                                                                                                              | Yes                            |
| Set of Integer  | JavaScript array object containing number                                                                     | The attribute value is zero or more integers. Use when you want the merchant to enter one or more integers. Sets don't contain duplicates.                                                                                                                                            | Yes                            |
| Set of Number   | JavaScript array object containing number                                                                     | The attribute value is zero or more numbers. Use when you want the merchant to enter one or more numbers. Sets don't contain duplicates.                                                                                                                                              | Yes                            |
| Enum of String  | B2C Commerce script dw.value.EnumValue class with value of type string, possibly in a JavaScript array object | The attribute value is zero or more strings. Use when you want the merchant to select one or more fixed values. Select **Multiple** if you want more than one value associated with the attribute.                                                                                    | Yes                            |
| Enum of Integer | B2C Commerce script dw.value.EnumValue class with value of type number, possibly in a JavaScript array object | The attribute value is zero or more integers. Check the **Multiple** checkbox if you want more than one value associated with the attribute.                                                                                                                                          | Yes                            |

## Custom Code Timeouts

We provide script timeouts to protect storefronts. For example, if you accidentally create an endless loop, the loop can cause massive thread exhaustion and require a restart of the instance.

### Script Timeouts

**note:** The described rules apply fully for compatibility modes 21.2 and later. For older compatibility modes depending on the situation, a defined timeout may not be active.

Scripts in different contexts can have different timeouts (see the following tables). If a script is called from a different context then the resulting timeout is the one that ends earliest. For example, if shortly before the 5-minute timeout of a controller request a page designer script is started, then the page designer script can be aborted before its own 30-second timeout is finished.

| Root Contexts        | Timeout    | Configurable                                                                             |
| -------------------- | ---------- | ---------------------------------------------------------------------------------------- |
| Controller Requests  | 5 minutes  | -                                                                                        |
| OCAPI Requests Hooks | 30 seconds | -                                                                                        |
| Script module step   | -          | Yes, see [Steptypes.json Syntax](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/jobs/b2c-custom-job-steps.md#steptypes.json-syntax). |

| Embedded Contexts             | Timeout    | Configurable |
| ----------------------------- | ---------- | ------------ |
| Page Designer scripts         | 30 seconds | -            |
| Form field validation scripts | 30 seconds | -            |
| Hooks called from scripts     | -          | -            |
| ISML embedded scripts         | -          | -            |

| Pipeline Contexts (deprecated) | Timeout                                                          | Configurable                                                                                                                                         |
| ------------------------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pipeline assigns node scripts  | 30 seconds                                                       | -                                                                                                                                                    |
| Eval pipelet                   | 30 seconds                                                       | -                                                                                                                                                    |
| Script pipelet                 | 30 seconds within storefront requests and 15 minutes within jobs | Yes, see [Pipelet Script.](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/pipeletapi/html/index.html?target=pipelet.Script.html) |

**note:** If a debug session is open, the minimum timeout for all script contexts is increased to 30 minutes.

In case a script timeout occurs the script is aborted with a non-catchable exception. The exception is logged in the error log. The message text contains something like:

```
ScriptingTimeoutError: Runtime of script more than 30000 milliseconds. Script stopped.
```

Typically this error leads to an error response (HTTP status 500) or a failed job execution. Note if this happens during template rendering the request might not fail, instead, a partly rendered response might be seen by users, but such responses are never cached longer than 5 minutes.

### Pipeline Timeouts

Pipeline runtime is limited via the Quota “api.pipeline.timeout”. This defines a timeout of 5 minutes for storefront requests, and no timeout during job execution, for example, via the ExecutePipeline Job Step.

**note:** The rules for the script timeout always apply and aren’t influenced by the Quota “api.pipeline.timeout”.

### Service Call Timeouts

The timeout values for `SFTPClient`, `HTTPClient`, and `webreference` objects are based on the timeout value of the calling script. The script timeout value is used as an upper bound for the timeout that is configured for the `SFTPClient` and `HTTPClient`.

It’s recommended to use the service framework, which has multiple monitoring and management features for web services. Nevertheless, for HTTPClient or SFTPClient, the timeouts can also be set as part of the function call.

To view the default global timeout:

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Global Preferences** > **Global Timeouts**.

If you’re having difficulty with scripts timing out while calling a third-party system or service, contact Customer Support to change the timeouts temporarily.

## Script Debugger API

The Script Debugger API is a JSON-based set of requests and responses that are managed using a REST servlet.

Use this RESTful API to create applications that interact with the Script Debugger for setting breakpoints, viewing variables, and evaluating expressions.

**important:** This API isn't available on a Production instance.

<!-- document id=0f36d0211c891fa55b01d3e36603df8b6518099dc1364b9f265f60555041d36a url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/scripts.md -->

Scripts

# Scripts

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/scripts/scripts-oas-v1-public.yaml)

## API Overview

The Scripts API provides endpoints for managing code versions on a Commerce Cloud instance.

### Overview

Code versions represent deployable bundles of cartridge code. This API allows administrators to list, create, read, update, and delete code versions on their Commerce Cloud instance.

### Key Features

*   **List Code Versions**: Retrieve all code versions available on the instance
*   **Get Code Version**: Get detailed information about a specific code version
*   **Create Code Version**: Create or replace a code version using PUT
*   **Update Code Version**: Modify code version properties, such as activating a code version
*   **Delete Code Version**: Remove a code version (the active code version cannot be deleted)

### Authentication

This API requires OAuth 2.0 authentication with the appropriate scopes:

*   `sfcc.scripts` - Read access to code version resources
*   `sfcc.scripts.rw` - Read and write access to code version resources

### Best Practices

1.  Always verify which code version is active before making changes
2.  Use PATCH to update specific properties like activating a code version
3.  Avoid deleting the active code version - deactivate it first
4.  Use the GET list endpoint to discover available code versions before performing operations

**Version:** 1.0.1

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/dx/scripts/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.scripts: Scripts API READONLY scope
    *   Scope sfcc.scripts.rw: Scripts API scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Get a list of code versions.

`GET /organizations/{organizationId}/code-versions`

Operation ID: `getCodeVersions`. Security: AmOAuth2 (sfcc.scripts, sfcc.scripts.rw).

Retrieves a list of all code versions available on the instance.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `expand` (query, array of string, style: form, explode: false) Specifies which related resources to include in the response. Use `size` to include the total size of the code version.  
    Items: Allowed values: `size`. Example: `size`.
    
    _Example_
    
    ```
    [
      "size"
    ]
    ```
    

#### Responses

*   **200** List of code versions successfully retrieved.
    
    Media type: `application/json`. Schema: `CodeVersionResult`.
    
    _Example: CodeVersionListSuccess_ Successful code version list result
    
    Example of a successful response returning a list of all code versions on the instance.
    
    ```
    {
      "limit": 2,
      "total": 2,
      "data": [
        {
          "id": "version1",
          "active": true,
          "cartridges": [
            "app_storefront_base",
            "app_storefront_controllers"
          ],
          "compatibilityMode": "25.6",
          "lastModificationTime": "2025-01-15T10:30:00.000Z",
          "rollback": false,
          "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1"
        },
        {
          "id": "version2",
          "active": false,
          "cartridges": [
            "app_storefront_base"
          ],
          "compatibilityMode": "25.6",
          "lastModificationTime": "2025-01-10T08:00:00.000Z",
          "rollback": true,
          "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version2"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get a code version.

`GET /organizations/{organizationId}/code-versions/{codeVersionId}`

Operation ID: `getCodeVersion`. Security: AmOAuth2 (sfcc.scripts, sfcc.scripts.rw).

Retrieves the details of a specific code version by its ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `codeVersionId` (path, string, required) The ID of the code version.  
    Minimum length: 1. Maximum length: 256. Example: `version1`.
*   `expand` (query, array of string, style: form, explode: false) Specifies which related resources to include in the response. Use `size` to include the total size of the code version.  
    Items: Allowed values: `size`. Example: `size`.
    
    _Example_
    
    ```
    [
      "size"
    ]
    ```
    

#### Responses

*   **200** Code version successfully retrieved.
    
    Media type: `application/json`. Schema: `CodeVersion`.
    
    _Example: CodeVersionSuccess_ Successful code version retrieval
    
    Example of a successful response returning a single code version with all properties.
    
    ```
    {
      "id": "version1",
      "active": true,
      "cartridges": [
        "app_storefront_base",
        "app_storefront_controllers"
      ],
      "compatibilityMode": "25.6",
      "lastModificationTime": "2025-01-15T10:30:00.000Z",
      "rollback": false,
      "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1"
    }
    ```
    
    _Example: CodeVersionSuccessWithSize_ Successful code version retrieval with size expanded
    
    Example of a successful response returning a single code version with the totalSize field included when `expand=size` is requested.
    
    ```
    {
      "id": "version1",
      "active": true,
      "cartridges": [
        "app_storefront_base",
        "app_storefront_controllers"
      ],
      "compatibilityMode": "25.6",
      "lastModificationTime": "2025-01-15T10:30:00.000Z",
      "rollback": false,
      "totalSize": 104857600,
      "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Code version not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CodeVersionIdNotFound_
    
    ```
    {
      "title": "Code Version Id Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/code-version-id-not-found",
      "detail": "The code version with ID 'nonexistent_version' couldn't be found."
    }
    ```
    

### PUT Create or replace a code version.

`PUT /organizations/{organizationId}/code-versions/{codeVersionId}`

Operation ID: `createCodeVersion`. Security: AmOAuth2 (sfcc.scripts.rw).

Creates a new code version or replaces an existing one with the given ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `codeVersionId` (path, string, required) The ID of the code version.  
    Minimum length: 1. Maximum length: 256. Example: `version1`.

#### Responses

*   **200** Code version successfully replaced.
    
    Media type: `application/json`. Schema: `CodeVersion`.
    
    _Example: CodeVersionReplacedSuccess_ Successful code version replacement
    
    Example of a successful response when an existing code version is replaced via PUT.
    
    ```
    {
      "id": "version1",
      "active": true,
      "cartridges": [
        "app_storefront_base",
        "app_storefront_controllers"
      ],
      "compatibilityMode": "25.6",
      "lastModificationTime": "2025-01-16T12:00:00.000Z",
      "rollback": false,
      "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1"
    }
    ```
    
*   **201** Code version successfully created.
    
    Media type: `application/json`. Schema: `CodeVersion`.
    
    _Example: CodeVersionCreatedSuccess_ Successful code version creation
    
    Example of a successful response when a new code version is created via PUT.
    
    ```
    {
      "id": "new_version",
      "active": false,
      "cartridges": [
        "app_storefront_base"
      ],
      "compatibilityMode": "25.6",
      "lastModificationTime": "2025-01-16T09:00:00.000Z",
      "rollback": false,
      "webDavUrl": "https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/new_version"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **409** A code version with the given ID already exists.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CodeVersionIdAlreadyExists_
    
    ```
    {
      "title": "Code Version Id Already Exists",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/code-version-id-already-exists",
      "detail": "The code version ID 'version1' already exists."
    }
    ```
    

### DELETE Delete a code version.

`DELETE /organizations/{organizationId}/code-versions/{codeVersionId}`

Operation ID: `deleteCodeVersion`. Security: AmOAuth2 (sfcc.scripts.rw).

Deletes an existing code version by its ID. The active code version cannot be deleted.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `codeVersionId` (path, string, required) The ID of the code version.  
    Minimum length: 1. Maximum length: 256. Example: `version1`.

#### Responses

*   **204** Code version successfully deleted.
*   **400** The active code version cannot be deleted.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CodeVersionModification_
    
    ```
    {
      "title": "Code Version Modification",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/code-version-modification",
      "detail": "The code version 'version1' is active and can't be changed."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Code version not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CodeVersionIdNotFound: same as GET /organizations/{organizationId}/code-versions/{codeVersionId} 404 response._
    

### PATCH Update a code version.

`PATCH /organizations/{organizationId}/code-versions/{codeVersionId}`

Operation ID: `updateCodeVersion`. Security: AmOAuth2 (sfcc.scripts.rw).

Updates an existing code version with the provided properties. Use this endpoint to activate a code version.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `codeVersionId` (path, string, required) The ID of the code version.  
    Minimum length: 1. Maximum length: 256. Example: `version1`.

#### Request body (required)

Media type: `application/json`. Schema: `CodeVersion`.

_Example: ActivateCodeVersion_ Activate a code version

Example of activating a code version by setting active to true

```
{
  "active": true
}
```

#### Responses

*   **200** Code version successfully updated.
    
    Media type: `application/json`. Schema: `CodeVersion`.
    
    _Example CodeVersionSuccess: same as GET /organizations/{organizationId}/code-versions/{codeVersionId} 200 response._ Successful code version retrieval
    
    Example of a successful response returning a single code version with all properties.
    
    _Example: CodeVersionSuccess_ Successful code version retrieval
    
    Example of a successful response returning a single code version with all properties.
    
*   **400** The active code version cannot be modified.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CodeVersionModification: same as DELETE /organizations/{organizationId}/code-versions/{codeVersionId} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Code version not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CodeVersionIdNotFound: same as GET /organizations/{organizationId}/code-versions/{codeVersionId} 404 response._
    
*   **409** A code version with the given ID already exists (when renaming).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CodeVersionIdAlreadyExists: same as PUT /organizations/{organizationId}/code-versions/{codeVersionId} 409 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### CodeVersionResult

Result containing a list of code versions.

Includes all fields of `ResultBase`.

*   `data` (_array of CodeVersion_) List of code versions.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CodeVersion

A code version represents a deployable bundle of cartridge code on a Commerce Cloud instance.

*   `id` (_string_) The ID of the code version.  
    Minimum length: 1. Maximum length: 256. Example: `version1`.
*   `active` (_boolean_) Whether this is the active code version.  
    Example: `true`.
*   `cartridges` (_array of string_) A list containing the names of all cartridges participating in this code version.  
    Items: Maximum length: 256. Example: `app_storefront_base`.
    
    _Example_
    
    ```
    [
      "app_storefront_base",
      "app_storefront_controllers"
    ]
    ```
    
*   `compatibilityMode` (_string_) The compatibility mode for this code version.  
    Maximum length: 100. Example: `25.6`.
*   `activationTime` (_string (date-time)_) The timestamp when this code version was activated.  
    Example: `2025-01-15T10:00:00.000Z`.
*   `lastModificationTime` (_string (date-time)_) The timestamp when this code version was last modified.  
    Example: `2025-01-15T10:30:00.000Z`.
*   `rollback` (_boolean_) Whether this code version supports rollback.  
    Example: `false`.
*   `totalSize` (_integer (int64)_) The total size of the code version in bytes. Only included when `expand=size` is requested.  
    Example: `104857600`.
*   `webDavUrl` (_string_) The WebDAV URL for uploading code to this code version.  
    Maximum length: 4000. Example: `https://example.com/on/demandware.servlet/webdav/Sites/Cartridges/version1`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=9223d8ff45de2b83870ab288c73db78c635b6843efebdc5d20452442e528b33b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/search-and-navigation/b2c-search-and-navigation.md -->

# Search and Navigation

Salesforce B2C Commerce provides powerful search and navigation capabilities to optimize the online shopping experience. It includes features such as auto-suggest, spell correction, and faceted search for efficient product discovery. The platform offers customizable menus, breadcrumbs, and category hierarchies to facilitate smooth navigation. Dynamic merchandising enables personalized navigation experiences, while mobile optimization ensures seamless search and navigation across devices. These capabilities enhance discoverability, improve customer satisfaction, and drive conversions within the online store.

<!-- document id=a5747ff3572b54c2866517181a01733113a45cb4b5e2e5784c96daa0ff8a990f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/search-and-navigation/b2c-search-and-navigation-implementation-considerations.md -->

# Search and Navigation Implementation Considerations

Guidelines and requirements you may want to consider as you implement search and navigation throughout your storefront.

## Requirements Phase

Identify how many types of search are required for the solution. For example, do you want different behavior or presentation for different categories: top sellers versus clearance items or for content assets versus products?

Paging logic:

- Determine which pages show search results.
- Determine how many search results to show per page.
- Determine what happens when:
  - No search results are defined for a category or product
  - Less than the planned number of search results are defined for a category or product. For example, you want to redirect a search to a category page or another page to provide the user with more results.
  - More than the planned number of search results are defined for a category or product. For example, you want the customer to be able to refine their search.

Sorting and ranking logic:

- Determine how many ways a customer might want to sort results
- Determine whether you want to promote specific products through search
- Determine what happens when:
  - Multiple sorts are applied in a specific order
  - Ranking logic is applied to reposition results after sorting

Indexing attributes:

- Identify what additional information is required for indexing, so that customers can search on it. Every attribute that is needed for indexing must be marked as searchable.
- Identify required search features, including:
  - Category placement
  - Search placement
  - Search rank
  - Text relevance boosting

Maintaining indexes:

- Identify how data for indexes will be maintained (for example, import, manual, programmatic, or other):
  - During development
  - When the site is live
- If the merchant plans to manually create search indexes in the Business Manager, identify:
  - Who will be responsible for creating them
  - If there will be a review process
  - How they are tested
  - How search indexes are replicated with catalog data

If the merchant plans to import search index definitions, define the import process. If possible, implement it as a job within Salesforce B2C Commerce, to take advantage of the scheduling and notification functionality built into B2C Commerce. If you intend to perform regular index updates, these can also be scheduled in Business Manager.

## Design Phase

During the design phase, merchants should consider the day-to-day operational overhead associated with creating and maintaining search indexes manually within B2C Commerce, especially merchants with large product catalogs. This process includes examining current customer searches, identifying needed changes, configuring dictionaries and indexes, and manually building and replicating indexes.

## Build Phase

Build code to support search requirements.

## Development/Test Phase

To facilitate development and testing, you must:

- Create users with permissions that are in line with merchant-defined business processes.
- Create an initial set of test search results.
- Use a test plan to make sure that all use cases are reviewed, including current Storefront searches, if known.
- Test the import process, if applicable.

## Best Practices

Salesforce recommends the following best practices:

- Show all variations for sale; don't attempt to narrow the results by variation using scripts to process search results. For example, if color is a slicing attribute, show all iPods in all colors, don't attempt to iterate over the results to pull out only pink iPods via scripts. While this can be done, it requires post-processing of the full result set, which can impact the search performance. Instead, it's recommended that you add a search refinement that lets the customer drill down a specific selection.
- Any result processing that requires that you iterate through all the results can make search a lot slower.
- Be careful when applying text relevance boosting. Because this feature is site wide, it can have unexpected consequences if not applied with the full search set in mind.
- Make sure that scheduled indexing is disabled when you replicate index information from staging to production.

### Performance Recommendations

If you have a large catalog of products and you want to improve the speed of search, try to make the size of your indexes smaller. See the size of an index after it's built on the Search > Search Indexes page. Usually, the number of attributes being indexed is what determines index size. Add stop words to decrease the size of the index.

However, if you decrease the number of searchable attributes, this means that the search results might be less accurate.

If you have an average size catalog of products, decreasing index size isn't normally a concern.

### Testing Recommendations

We recommend testing the top 50–100 searches on your site as a baseline to make sure that the search results are returned in the order that you prefer.

## Limitations

Consider the following limitations when designing search features.

- Parallel product searches and contextual searches are currently not supported.
- Salesforce B2C Commerce currently supports only one index based on real-time data: the availability index. This index, based on an inventory list can support one or more sites. Multiple sites that use the same inventory list also use the same search availability index.

## Paging Results

Use the productgrid.isml templates in the SiteGenesis application to control the number of search results returned and the display of search results. Use the productnav.isml templates to control the look of the paging bar that has the previous and next buttons, and the links to each page of results. Both templates are located in the SiteGenesis Storefront Core cartridge in default\\search. The SiteGenesis application includes customer paging preferences.

## Quality of Search Testing

We recommend you test the quality of your searching regularly and we’ve prepared some resources to help with your testing.

### Reports & Dashboards

Use these resources with the Reports & Dashboards Search Conversion reports.

- [Quality of Search Feedback Form](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/NEWQualityofSearchTestingforB2CCommerce-ReportsandDashboards.xlsx) for Reports & Dashboards (after July 13, 2020): A Quality of Search Feedback Form to be used along with the Best Practices of Site Search Optimization methodology.
- [Quality of Search Feedback Form](https://org62.my.salesforce.com/sfc/p/#000000000062/a/0M000000YDxv/mTbt.-YjG7DgP6TQBpPV3dBHXisiBSl7wesIZDr6-N4) for Business Manager Reporting (before July 13, 2020): A Quality of Search Feedback Form to be used along with the Best Practices of Site Search Optimization methodology.

### Historical Reports

(Formally Business Manager Analytics)

These reports are being deprecated. Use the Historical Reports module to generate reports and review data for dates before January 1, 2017.

- [Quality of Search Template How-To (1 of 2)](https://salesforce.vidyard.com/watch/gqqAZYDajSebL2Pw8ZjQiu): This video walks through how to download the Search Conversion Report from Business Manager and import it into the Quality of Search Testing Tool Template.
- [Quality of Search Template How-To (2 of 2)](https://salesforce.vidyard.com/watch/FFE6zS9zxpYRDqq4mwpPiu): This video walks through the Quality of Search Testing Methodology and how to execute it using Business Manager tools and reports.

<!-- document id=488c24ea49f34d7a2c81d38962c6be91d1d079e2560921f31f5f707bc0e62474 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-search-limits.md -->

# Search Data Limits

| Object                                         | Limit B2B Except Where Indicated     | Store or Org | Notes                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------------------------------- | ------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Filter or Facet Values per Attribute in search | 100<sup>\*</sup> values              | N/A          | The number of filterable values per attribute. More than 100 values can be added to a filterable field, but the selectable limit is 100.                                                                                                                                                                                                                                                                               |
| Filter Fields in a Query in Search             | 10 filterable fields                 | N/A          | The number of fields a customer can select to apply in a search query.                                                                                                                                                                                                                                                                                                                                                 |
| Facets Displayed for a Search Query            | 10<sup>\*</sup>                      | N/A          | You can configure up to 10 filterable fields as facets. When auto-faceting is enabled, the system automatically displays the 10 most populated filterable fields as facets. Contact your account representative when you need to increase this limit to the maximum of 50 facets.                                                                                                                                      |
| Filterable Attributes per Store                | 50<sup>\*</sup> filterable fields    | Store        | The number of attributes used as filters per search. Filtered search attributes enable a faceted search experience. To configure a total of 100 searchable and filterable fields, contact Salesforce Customer Support.                                                                                                                                                                                                 |
| Searchable Attributes per Store                | 25<sup>\*</sup> searchable fields    | Store        | The limit of searchable characteristics or properties associated with products that are configured to be searchable within your store. Make use of standard searchable attributes like product name, description, SKU, and others. These are often foundational attributes that users frequently use for searching. To configure a total of 100 searchable and filterable fields, contact Salesforce Customer Support. |
| Sort Rules per Store                           | 15                                   | Store        | The limit is 15 sort rules to a store. Each variation, such as Price (Low to High) and Price (High to Low), counts as separate rules. The combined total of searchable attributes, filterable attributes, and sort rules per store can't exceed 70.                                                                                                                                                                    |
| Search Terms per Search                        | 1024 characters or 32 words B2C Only | N/A          | The number of characters or words entered in a search field and applied to a search.                                                                                                                                                                                                                                                                                                                                   |
| Product per Search Results Page                | B2B: 200 search results              | N/A          | The total number of items per page returned. Search returns the number of items configured per page plus up to 5 thousand if applicable.                                                                                                                                                                                                                                                                               |
| Filter Values per Attribute per Product        | B2B: 250 values                      |              | For each locale, a product field can have up to 250 values, including category name and ID. Products exceeding this limit aren't indexed in search. <br>You can increase the maximum number of category values associated with a product—including category names and IDs—to any value between 250 and 500. To configure a limit higher than the default, contact Salesforce Customer Support.                         |
| Locale                                         | 25                                   | N/A          | Search can index a maximum of 25 locales.                                                                                                                                                                                                                                                                                                                                                                              |
| Synonym Rules per Store                        | 50                                   | Store        | The limit is 50 synonym rules per store.                                                                                                                                                                                                                                                                                                                                                                               |
| Boost and Bury Rules per Store                 | 100                                  | N/A          | The limit is 100 boost and bury rules to a store.                                                                                                                                                                                                                                                                                                                                                                      |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce Customer Support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

Maintaining search settings within the Salesforce B2B Commerce search limits helps improve search functionality and the customer experience. Before considering extending search limits for B2B, evaluate your search configuration and customizations.

Optimize Product Data: Search data, such as fields, values, and attributes, are directly linked to product data. To limit the need for excessive search data, make sure that your product data is well-organized, accurate, and complete. This includes maintaining consistent and descriptive product names, detailed descriptions, and appropriately configured attributes. Product data that is well-maintained minimizes the need for large sets of search filters and search values that increase search data and slow down search results.

Identify and prioritize the key searchable fields. Set the fields that are most relevant to your customers as searchable. Focus on the fields that are commonly used in searches and are critical for product identification.

Use the available custom field options so that customers can tailor their search configuration to align with your products, customer needs, and industry search standards. When setting custom fields for search, you can minimize data usage, by only using fields that help customers target and refine a search. Avoid setting catch-all fields that don’t return refined results as searchable.

Regularly maintain your searchable fields and attributes so they stay within the store limits. When you discontinue products, review your searchable field and attributes and remove those that are specific to the discontinued product. Regularly test the search functionality, especially after implementing changes or updates. Monitor search performance and analyze user behavior to identify areas for improvement.

If you have search data requirements that exceed the limits, consider the impact on search performance and data storage limits.

- Does the additional data push related data objects beyond their limits?
- Can you offset a data increase by decreasing data requirements in other store functions?

After you assess the impact of a data increase, if you still want to request an increase, contact Salesforce Customer Support.

<!-- document id=c3d0339b9dcd935b8e9dd858e9f9efadefebe42960f7afe051d3f3f4ccb85b0c url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-search.md -->

# Search Data Model

The Search data model connects objects used to support store search functionality in a B2B or B2C store. This data model includes objects used to configure search indexes, handle search suggestions, perform product searches, and manage search-related attributes.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the search data model require at least one of the following licenses: B2B Commerce.

![Diagram of the Search data model](https://developer.salesforce.com/media/d2c-commerce/search_data_model.png)

- [BuyerAccount](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyeraccount.htm)
- [Entitlement](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_entitlement.htm)
- [ManagedContentChannel](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_managedcontentchannel.htm)
- [Pricebook](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebook2.htm)
- [Product](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm)
- [ProductAttribute](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productattribute.htm)
- [ProductCatalog](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcatalog.htm)
- [ProductCategory](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcategoryproduct.htm)
- [ProductCategoryProduct](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_productcategoryproduct.htm)
- [WebStore](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)
- [WebStoreSearchProductSettings](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstoresearchprodsettings.htm)

<!-- document id=91d816f43fe4879875a28ca11c718e50927132321b85ce8b8e0eec905045c9d1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/search-and-navigation/b2c-search-suggestion-for-developers.md -->

# Search Suggestion

Add more complex search completion support to your application via the Salesforce B2C Commerce APIs. Before you begin coding, review the SiteGenesis application to see how this feature was implemented.

## SiteGenesis Implementation

Review these SiteGensis files to understand how this feature was implemented, for example:

- SiteGenesis/cartridge
  - `static/default/js/app.js`
  - `templates/default/resources/appresources.isml`
- SiteGenesis Storefront Core/cartridge
  - `pipelines/Search.xml`
  - `static/default/css/style.css`
  - `templates/default/search/suggestionsbeta.isml`
  - `templates/resources/search.properties`
- Data files: `sg20_demo_data_no_hires_images/meta/system-objecttype-extensions.xml`

When you implement this feature, you need to consider the performance impact. The SiteGenesis implementation shows suggestions as a popup immediately after the customer starts entering text in the search field. The popup's HTML content is fetched using an asynchronous AJAX call. The SiteGenesis application executes the AJAX calls in a gracefully way as follows:

- Only one request at a time
- Only if search phrase has changed
- If the search phrase has changed multiple times while a single AJAX call was running, only the last most recent search phrase is used in the next AJAX call (no queuing)
- The page cache must be used on the server
- The minimum input length is set to three (3) characters

## Using the B2C Commerce APIs

Use the B2C Commerce APIs to customize your code. The _Suggest_ API consists of the following:

- `dw.suggest.SuggestModel` class: main access point to obtain suggestions
- `dw.suggest.Suggestions` class: container for bundling suggested items (for example, products), suggested phrases, and the specific terms of a particular type (for example, auto completed products names), for example, _dw.suggest.ProductSuggestions_
- `dw.suggest.SuggestedTerms` class: lists of terms suggested for a single term of the customer input
- `dw.suggest.SuggestedTerm` class: provided by specific classes such as _SuggestedProduct_ or _SuggestedContent._ Each _SuggestedTerm_ object represents a single suggested term and its associated attributes and flags
- `dw.suggest.SuggestedPhrases` class: represents one or more search phrases suggested by B2C Commerce
- `dw.catalog.ProductSearchModel.getSuggestedSearchPhrase` method: provides the corrected search phrase as a hint on the search results page.

See the B2C Commerce APIs for more information.

**Match Types**

Matches are defined as follows:

| Match Type      | Ranking Priority | Description                                                                              |
| --------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| Exact           | 1                | The original and suggested terms are exactly equal                                       |
| Auto completion | 2                | The original is a prefix of the suggested term.                                          |
| Fuzzy           | 3                | The original and suggested terms differ by a few characters, similar to spell correction |

**note:** The match types and ranking described here is only applicable for suggested terms, that is, auto completion and auto correction. It doesn't affect any search results or sorting rules.

<!-- document id=7f249c1d55244047b8f4ef2dfd46d53a9243400eeba5bfc917a089ffc426a567 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/searchindexupdateconfiguration.md -->

# SearchIndexUpdateConfiguration document

Configuration document for updating the search index.    

| Property   | Type     | Constraints                    | Description |
| :--------- | :------- | :----------------------------- | :---------- |
| site_scope | [String] | mandatory=true, nullable=false |             |

<!-- document id=44e873e8eca3c7cd848e3fe0fa14d9cc778a7eb67310c281882e0e87f8b6e550 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-secure-storefront-section.md -->

# Secure Your Storefront

Control access to your Storefront Next environments and apply security rules to protect storefronts under development and on On-Demand Sandbox instances.

In this section:

- [Limit Access to a Storefront Under Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-protect-storefront.md)
- [Default Security Rules on On-Demand Sandbox (ODS) Instances](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ods-security-rules.md)
- [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-scapi-request-identification.md)

<!-- document id=438182b00c8d260039a0b51d5128839f0b3d8f781ced4e633dcf7c04318ef8b6 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/security.md -->

# Security

Ensuring data privacy and trusted access to ecommerce systems is a critical part of the B2C Commerce platform. All interactions with the B2C Commerce API must be fully authenticated and authorized.

## Headless Commerce Security Features

B2C Commerce provides authentication, authorization, and availability features for headless commerce.

### Authentication

Authentication is about validating identity to make sure that the client (for example, a PWA Kit storefront) is who it says it is. An administrator provisions an API client with a secret (think of it like a password). The client uses the secret to request an access token. The API gateway authenticates the client’s identity based on the access token.

### Authorization

Authorization is about validating access to a particular resource and making sure that the client has permission to perform certain tasks. An administrator provisions an API client with scopes that assign permissions to the client. The API client specifies a set of scopes when requesting an access token. The API gateway performs authorization on the basis of the access token. For more information, see [Authorization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization.md).

### Availability

Availability ensures that a service remains up and running. Availability is implemented for headless commerce using DoS protection, API rate limiting, and eCDN controls on authentication traffic. For API quota limits, see [Rate Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/throttle-rates.md). For platform DoS and DDoS protection, see [Denial-of-Service Protection in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_denial_of_service_protection.htm&type=5). For bot management and credential-stuffing controls, see [Bot Management](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html).

Starting with B2C Commerce 26.10, Production exposes a SCAPI zone for Commerce API traffic. Edit custom rules, rate-limiting rules, and IP access lists on that zone in Production Business Manager (**Administration > Sites > Embedded CDN Settings**), without opening a support case. The zone is shared by Development, Staging, and Production. It doesn't appear in Business Manager or in the CDN API on Development or Staging. Scope each rule by the org ID in the URL path, for example `/organizations/{organizationId}/`. Some platform-managed rules are visible and locked, including an allowlist for valid Managed Runtime (MRT) to SCAPI traffic that skips custom, rate-limiting, and managed WAF checks. Managed WAF isn't a customer control on this zone. For the control matrix, see [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5).

Use these proactive controls that are available today:

- **SLAS private client and Strict Client Auth.** Mitigate credential stuffing against private-client SLAS flows. See [SLAS Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-best-practices.md) and [Private SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-private-client.md). Public clients ignore Strict Client Auth.
- **Passwordless login.** Prefer passwordless shopper authentication (OTPs or passkeys) when your storefront supports it. It offers protection against phishing and brute-force password cracking. See [Passwordless Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-passwordless-login-overview.md).
- **Leaked Credentials Detection.** Use the `cf.waf.credential_check.*` fields on storefront login and on SLAS login. Detection scans HTTP Basic credentials in the `Authorization` header and in storefront form fields. OCAPI Shop `POST /dw/shop/{version}/customers/auth` also submits HTTP Basic credentials and is served on the storefront zone, not the SCAPI zone. Existing integrations that still call this deprecated endpoint can use the same detection fields there. For SLAS login, add a rate-limiting rule on the SCAPI zone. For OCAPI login, add a rate-limiting rule on the storefront zone. Use the `block` action rather than a Challenge action for both SLAS and OCAPI login. See [eCDN Custom Rules](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-zones-custom-rules.md) and [eCDN Rate Limiting Rules](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/cdn-rate-limiting-rules.md).
- **Anomaly detection.** Configure Log Center detectors on authentication-failure logs as an early-warning complement to the preceding enforcement controls. See [Anomaly Detection in Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_anomaly_detection.htm&type=5).
- **Restrict SCAPI to Managed Runtime traffic.** Starting with B2C Commerce 26.10, enable **Managed Runtime SCAPI Request Identification** on each instance whose shopper traffic reaches SCAPI through Managed Runtime, including Composable Storefront and Storefront Next. Managed Runtime attaches the SCAPI Identity Header to the requests it makes. You add the block rule on the SCAPI zone **Security Rules** tab. Scope it to that instance's org-specific path segment and to Shopper API paths (`/shopper`), so Admin API and B2C CLI calls aren't affected, and place it directly after that instance's allow rule. Use `block`, not a challenge action, and run the rule in `log` mode first. Enabling the switch alone doesn't stop direct Shopper API calls. This control closes the Managed Runtime bypass path only. See [How do I restrict SCAPI to Managed Runtime traffic?](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html#how-do-i-restrict-scapi-to-managed-runtime-traffic), [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-request-identification.html) for Composable Storefront, and [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-scapi-request-identification.html) for Storefront Next.

## The Shared Responsibility Model

As a B2C Commerce customer, you’re responsible for providing security for your custom head, including both the presentation and BFF layers, since the custom head runs on your infrastructure and application stack. Make sure that you’re willing and able to take on this responsibility. Building, hosting, and maintaining high-traffic public-facing applications can be extremely challenging.

Salesforce is responsible for providing security for the API endpoints exposed to your custom head and the B2C Commerce platform on which your commerce resources are hosted. For Managed Runtime SCAPI Request Identification, Salesforce provides and rotates the SCAPI Identity Header secret and the allow rule on the SCAPI zone. You own the block rule, its exclusions, and monitoring, along with rate limiting and your other bot controls.

Availability ensures that a service remains up and running. Availability is implemented for headless commerce using DoS protection, API rate limiting, and the eCDN controls described in [Availability](#availability).

## General Security Best Practices

Follow all general good security principles when developing for headless commerce, for example, defense-in-depth and secure defaults. Implement maximum protection for your sites against security threats using the best practices described in [General Security Best Practices](https://help.salesforce.com/s/articleView?id=cc.b2c_general_security_best_practices.htm&type=5).

Use secure design and coding practices during implementation. We recommend reviewing the resources provided by the Open Web Application Security Project (OWASP). OWASP is an online community that provides articles, methodologies, documentation, tools, and technologies for web application security.

## B2C Headless Security Best Practices

Follow B2C security best practices when developing your headless commerce architecture.

**warning:** In addition to implementing the B2C security best practices described here, you’re also responsible for implementing security on your own front-end infrastructure as part of the shared responsibility model.

### Least Privilege

Follow the principle of least privilege to give API clients, users, applications, systems, and other components only the minimum privilege level they need to do their jobs. Implement the least privilege principle when you provision an API client in Account Manager. Also apply least privilege when an API client requests a JWT access token from Account Manager. When a client calls an API, the API gateway performs authorization on the basis of the access token.

As described in [Authorization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization.md), the B2C Commerce headless model uses OAuth scopes to define permissions for API Clients. As part of the API Client provisioning process, your administrator specifies both Allowed Scopes and Default Scopes for that API Client. When requesting a JWT access token, your API client can request a set of scopes to be included in the JWT access token.

If the API client doesn’t request any scopes, the scopes specified in the Default Scopes section are included in the JWT access token returned to the API client. If the API client does request scopes, and those scopes are provisioned in the Allowed Scopes for the API Client, the requested scopes are included in the JWT access token. Apply the least privilege principle when you provision an API client in Account Manager. For example, if an API Client requires only access to the Catalogs API, provision only scopes related to the Catalogs API for that client.

Don’t provision scopes for other APIs for that client since additional scopes give the client more privilege it needs. Similarly, if an API Client requires only read access to the Products API, don’t configure the API client with the read/write scope for the Products API. A scope that ends with `.rw` specifies both read and write access, while a scope that doesn’t end with `.rw` specifies only read access.

The following example shows the scopes provisioned for an API client that is configured with read/write access to the Catalogs API and read-only access to the Products API.

```text
sfcc.catalogs.rw sfcc.products
```

Apply least privilege when an API client requests a JWT access token from Account Manager. For example, an API client is provisioned with access to both the Catalogs API and Products API. If the API client requires only the Products API, the API client asks only for that scope in the access token. If the API client later wants to call the Catalogs API, the client can request the Catalogs scope.

## Secure Rendering of API Response Data

SCAPI returns stored data as-is, without HTML encoding or sanitization. This is standard behavior for JSON REST APIs — the API is context-neutral and cannot anticipate how consumers render data.

When rendering API response data in HTML, apply context-appropriate output encoding to prevent cross-site scripting ([XSS](https://owasp.org/www-community/attacks/xss/)).

## Next Steps

For details about how to maintain performance, scale, and security for headless commerce applications, refer to the following documents.

- [Getting Started with Headless Commerce](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/WhitePaper_GettingStartedwithHeadlessCommerce_022120_V6.pdf)
- [Headless Commerce Implementation Guide](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/B2CCommerceHeadlessImplementation_WhitePaper__052220_FINAL.pdf)
- [B2C Commerce Security, Privacy, and Architecture](https://www.salesforce.com/content/dam/web/en_us/www/documents/legal/misc/commerce-cloud-security-privacy-and-architecture.pdf)
- [Salesforce B2C Headless Commerce Node.JS SDK](http://salesforcecommercecloud.github.io/commerce-sdk)
- [Bot Management](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html)
- [Denial-of-Service Protection in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_denial_of_service_protection.htm&type=5)
- [SLAS Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-best-practices.md)
- [Passwordless Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-passwordless-login-overview.md)

<!-- document id=41f0bdf1d776acbd72fc350320c5c41339f216559f279eca4287c74babd2b6d3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-security-headers.md -->

# Security Response Headers

Storefront Next sends security response headers by default. Every storefront that you generate from the template inherits these headers. The headers help protect shoppers from common web attacks, such as cross-site scripting (XSS), clickjacking, and protocol downgrade.

Unlike Composable Storefront (PWA Kit), which sets headers explicitly in your storefront code, Storefront Next manages these headers for you. The defaults ship from the `@salesforce/storefront-next-runtime` package, so you don't maintain them yourself. To support an external integration, extend the defaults through `config.server.ts` or an environment variable.

## Default Headers

The table lists the headers that Storefront Next sends with every page response.

| Header                      | Default Value                                                                                                 |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `Content-Security-Policy`   | See [Content Security Policy Directives](#content-security-policy-directives).                                |
| `Strict-Transport-Security` | `max-age=15552000; includeSubDomains` (sent on Managed Runtime only, and suppressed during local development) |
| `X-Frame-Options`           | `SAMEORIGIN`                                                                                                  |
| `X-Content-Type-Options`    | `nosniff`                                                                                                     |
| `Referrer-Policy`           | `strict-origin-when-cross-origin`                                                                             |
| `Permissions-Policy`        | `camera=(), microphone=(), geolocation=()`                                                                    |

The headers apply to pages that your storefront renders. They don't apply to the Managed Runtime health check, the B2C Commerce API (SCAPI) proxy path, or static assets, because other layers serve those responses.

### Content Security Policy Directives

The Content Security Policy (CSP) controls which origins a page loads content from. The default policy is tuned for the Storefront Next stack: server-side rendering, Dynamic Imaging Service (DIS) images, Cloudflare Turnstile, Tailwind CSS inline styles, and SCAPI as the only outbound API origin.

| Directive                   | Default Value                                                                                              | Description                                                                                                                                 |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `default-src`               | `'self'`                                                                                                   | Restricts every fetch type that no other directive covers.                                                                                  |
| `script-src`                | `'self' https://challenges.cloudflare.com 'nonce-<per-request>'`                                           | Permits scripts from your own origin and the Turnstile widget. A per-request nonce authorizes the storefront's inline configuration script. |
| `style-src`                 | `'self' 'unsafe-inline'`                                                                                   | Permits inline styles, which Tailwind CSS relies on.                                                                                        |
| `img-src`                   | `'self' data: https://*.commercecloud.salesforce.com https://*.demandware.net`                             | Permits DIS and B2C Commerce image URLs.                                                                                                    |
| `font-src`                  | `'self' data:`                                                                                             | Permits self-hosted web fonts.                                                                                                              |
| `connect-src`               | `'self' https://*.commercecloud.salesforce.com https://*.demandware.net https://challenges.cloudflare.com` | Permits SCAPI calls and requests from the Turnstile widget.                                                                                 |
| `frame-src`                 | `https://challenges.cloudflare.com`                                                                        | Permits the Turnstile widget iframe.                                                                                                        |
| `frame-ancestors`           | `'self'`                                                                                                   | Restricts which origins can embed your storefront in a frame.                                                                               |
| `form-action`               | `'self'`                                                                                                   | Restricts the origins that forms submit to.                                                                                                 |
| `base-uri`                  | `'self'`                                                                                                   | Prevents injection of a `<base>` element.                                                                                                   |
| `object-src`                | `'none'`                                                                                                   | Blocks plugin content, such as Flash.                                                                                                       |
| `upgrade-insecure-requests` | Enabled                                                                                                    | Upgrades HTTP subresource requests to HTTPS.                                                                                                |

## Add Headers for an External Integration

To add an origin for an external integration, such as an analytics provider or a third-party widget, extend the defaults in `config.server.ts`. Import `defaultCspDirectives`, spread it, and add your origin to the relevant directive.

**important:** Each directive that you set replaces the default for that directive. Spread `defaultCspDirectives` and add your origin so that your storefront keeps the values that Storefront Next requires.

```typescript
// config.server.ts
import { defaultCspDirectives } from "@salesforce/storefront-next-runtime/security";

export default defineConfig<Config>({
  app: {
    security: {
      headers: {
        csp: {
          directives: {
            ...defaultCspDirectives,
            "script-src": [...defaultCspDirectives["script-src"]!, "https://cdn.example.com"],
            "connect-src": [...defaultCspDirectives["connect-src"]!, "https://api.example.com"],
          },
        },
      },
    },
  },
});
```

To add an identity provider for social login, extend `connect-src` with the provider's origins. For more information, see [Implement Social Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-social-login.md).

**warning:** Report-only mode doesn't block content, so it provides no protection. Don't use report-only mode for a production deployment. To discover the origins that an integration uses, deploy with `csp: { reportOnly: true }` in a test environment, where the browser reports violations to the DevTools console. After you add the origins, set `reportOnly` to `false` to enforce the policy.

## Override Headers with an Environment Variable

To change a header without a code change, use the `PUBLIC__` environment-variable override. The variable path uses double-underscore (`__`) separators.

```bash
# Turn on CSP report-only mode:
PUBLIC__app__security__headers__csp__reportOnly=true

# Turn off the Strict-Transport-Security header:
PUBLIC__app__security__headers__hsts=false
```

An environment variable replaces the entire `directives` map, not an individual directive, because the variable path uses `__` as its separator and directive names contain hyphens, such as `script-src`. Provide the full map as a JSON value.

```bash
# Replace the entire CSP directives map (this replaces all defaults):
PUBLIC__app__security__headers__csp__directives='{"default-src":["'"'"'self'"'"'"],"script-src":["'"'"'self'"'"'","https://cdn.example.com"]}'
```

Because an environment-variable override replaces all defaults, reserve it for unusual cases. For most changes, edit `config.server.ts` and spread `defaultCspDirectives`. For more information about environment-variable overrides, see [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md).

## Related Topics

- [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md)
- [Implement Social Login for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-social-login.md)
- [Limit Access to a Storefront Under Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-protect-storefront.md)

<!-- document id=f13d6fdb05a1daa8ac6c0bd58ea7a80a9bd2bcb62e39d0fe6b7ac50b02d1ed09 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/scapi-property-selection.md -->

# Select Response Properties

Property selectors allow you to set which properties are returned in API responses. You can use them to remove unneeded properties from large responses, reducing their size.

To use property selectors include the `select` parameter in a request. For example, to select only the `name` property of [getProduct](/commerce-api/references/shopper-products?meta=getProduct), use the selector `select=(name)`:

```json
GET /product/shopper-products/v1/organizations/f_ecom_zzte_053/products/25604524M?siteId=RefArch&select=(name)

{
  "name": "Black Single Pleat Athletic Fit Wool Suit",
}
```

Selector values must be enclosed in parentheses. The following selectors are supported:

| Capability                                                      | Value of select parameter                         |
| --------------------------------------------------------------- | ------------------------------------------------- |
| Include a single property.                                      | `(property)`                                      |
| Exclude a single property.                                      | `(-property)`                                     |
| Include properties of all levels, including complex properties. | `(**)`                                            |
| Include properties of top level, except complex properties.     | `(*)`                                             |
| Include the child document properties.                          | `(property.(**))`                                 |
| Return the first document. Index starts with 0.                 | `(property[0].(**))`                              |
| Return the first 5 documents.                                   | `(property[0:4].(**))`                            |
| Return the second, fourth, and sixth documents.                 | `(property[1,3,5].(**))`                          |
| Return matching documents matching a condition.                 | `(property[?(@.key==val)])`                       |
| Return matching documents matching multiple conditions.         | `(property[?(@.key1==val1) \|\| ?(@.key2=val2)])` |

Use a comma-separated value to select multiple properties. For example, to select `name` and `recommendations` including its children, use the selector `select=(name,recommendations.(**)`:

```json
GET /product/shopper-products/v1/organizations/f_ecom_zzte_053/products/25604524M?siteId=RefArch&select=(name,recommendations.(**))

{
  "name": "Black Single Pleat Athletic Fit Wool Suit",
  "recommendations": [
    {
      "recommendationType": {
        "displayValue": "Product Detail Page - Cross Sell",
        "value": 1
      },
      "recommendedItemId": "25686544M"
    }
  ]
}
```

To select child properties, include all result levels. For example, to select the `productId` of `variants`, use the selector `select=(variants.(productId))`:

```json
GET /product/shopper-products/v1/organizations/f_ecom_zzrf_016/products/25604524M?siteId=RefArch&select=(variants.(productId))

{
  "variants": [
    {
      "productId": "750518699660M"
    }
  ]
}
```

Selectors can also be used to exclude properties. To exclude a property, first include a property. For example, to exclude `backorderable` from `inventory` use `select=(inventory.(*,-backorderable))`:

```json
GET /product/shopper-products/v1/organizations/f_ecom_zzrf_016/products/25604524M?siteId=RefArch&select=(inventory.(*,-backorderable))

{
  "inventory": {
    "ats": 1800,
    "id": "inventory_m",
    "orderable": true,
    "preorderable": false,
    "stockLevel": 1800
  }
}
```

Selectors can be used to filter documents based on one or more conditions. For example, to filter for `small` and `large` images use `select=(imageGroups[?(@.viewType==small || @.viewType==large)])`:

```json
GET /product/shopper-products/v1/organizations/f_ecom_zzrf_016/products/25604524M?siteId=RefArch&select=(imageGroups[?(@.viewType==small || @.viewType==large)])

{
  "imageGroups": [
    {
      "images": [],
      "viewType": "large"
    },
    {
      "images": [],
      "viewType": "small"
    }
  ]
}
```

**note:** Property selectors are only supported for a subset of Shopper endpoints. You can check endpoint whether an endpoint supports `select` by reviewing its query parameters in the [API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references).

<!-- document id=3ab2f1b6cc3f497be9b6104437aa2047779a5c3e55ade8149833991ab1b88cad url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/hybrid-auth-select-storefront.md -->

# Select Your Storefront

Choose the storefront architecture that matches your implementation. Each path has its own step-by-step setup guide. All paths share the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md).

| Storefront type                                                         | Setup instructions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Storefront Next** (with SFRA/SiteGenesis)                             | Run Storefront Next alongside SFRA/SiteGenesis. See [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid.md). Storefront Next also supports [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-quick-start.md).                                                                                                                                                                                                                                                                                  |
| **PWA Kit** / Composable Storefront (with SFRA/SiteGenesis)             | Run PWA Kit alongside SFRA/SiteGenesis. Choose the guide that matches your project:<br>**New implementations (PWA Kit v3):** [Configure a Hybrid Storefront with Hybrid Auth (PWA Kit)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/hybrid-auth.md). New customers must start on PWA Kit v3.<br>**Existing PWA Kit v2.x projects:** [Hybrid Auth Implementation with PWA Kit v2.x](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-pwa-kit-v2.md)—an upgrade path to v2.10.0 (SLAS Public Clients only) for projects not yet moving to v3. |
| **SFRA/SiteGenesis only** (no headless runtime)                         | Use Hybrid Auth on an existing SFRA or SiteGenesis storefront for SLAS benefits—such as longer sessions and federated login—without a headless runtime. This path is for existing SFRA/SiteGenesis customers only. For the setup steps, see [SFRA and SiteGenesis Hybrid Setup (Existing Customers)](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-manual-setup.md#sfrasitegenesis-proper--hybrid-auth-session-extension-and-slas-setup) in the Manual Setup guide.                                                                                         |
| **Custom headless** (self-built and self-hosted, with SFRA/SiteGenesis) | For transitional architectures where a custom headless storefront that you build and host yourself (not Storefront Next or PWA Kit) runs alongside SFRA/SiteGenesis. For the setup steps, see [Headless Storefront + SFRA Hybrid Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-manual-setup.md#headless-storefronts--sfrasitegenesis) in the Manual Setup guide.                                                                                                                                                                                     |

<!-- document id=8237b3fb71a52759b9598f366ae4a0ada72e4cfe245ddd008e2b17ebb3580577 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-activities/send-einstein-activities.md -->

# Send Activities

When configuring Einstein Activities APIs, keep in mind these important call-related and identification-related API parameters.

## Important API Parameters

- Parameters needed for all API calls:
  - `siteId` - Your Einstein site ID, which can be found in the top right of the page on [Einstein Configurator](https://configurator.cquotient.com). It has the format `xxxx-<B2C Commerce Site ID>`
  - `clientId` - The API key. To use Einstein API, you must authenticate by passing a query parameter with your Account Manager client ID. Customer admins can [add an API Client ID](https://help.salesforce.com/s/articleView?id=cc.b2c_account_manager_add_api_client_id.htm&type=5) on the [Account Manager](https://account.demandware.com/) page.
  - `instanceType` - Indicates whether to use the event's data to feed the prediction engine and for reporting, or not use it, for example, in the case of a mock call.
- Identification-related parameters:
  - `userId` - Einstein does not handle cross-device management on our side. In order to link users across different devices, Commerce customers must collect and pass a shared ID through this `userId`. Typically, only if the shopper is logged in and the login parameter is passed through this field, can shoppers be identified across device. To comply with GDPR, this field must be obscured through hashing or some other method.
  - `cookieId` - Pass a unique identifier in this parameter so that subsequent activities can be linked to the same user.
  - `uuid` - If you cannot generate a consistent `cookieId` for a given user (don't have a way of distinguishing between people), you can use this parameter outputted by Einstein API instead. Each activity request returns a UUID representing the user, which can be stored and passed in subsequent calls.

## Activities and Einstein Recommendations

Primarily intended for B2C Commerce, the Einstein Recommendations API uses activities that it receives to output recommendations. The `viewProduct`, `viewReco`, `clickReco`, `addToCart` activities are required. The API calls send each activity to the Einstein engine when these events occur. The Einstein engine then uses the data gathered from these activities to generate recommendations that it returns to the site.

For more information about the Einstein Recommendations API and how to use it, see the [B2C Commerce Einstein API](https://developer.salesforce.com/docs/commerce/einstein-api/overview/).

## Activities and PWA Kit

The Progressive Web App (PWA) Kit is a framework for creating storefronts using the Retail React App. It's available as an open-source project on GitHub. The Retail React App is a customizable storefront that implements core ecommerce flows from home page to checkout.

To get started, see the [PWA Kit and Managed Runtime](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) documentation.

<!-- document id=04425ce003268fb18327918fe25333b0698dba9b1af2144857bc917d42565a18 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-recommendations/send-activities.md -->

# Send Activities

Activities tracking data provides Einstein insights into how shoppers interact with the applications. For the Einstein engine to learn and serve the best possible recommendations, you must send your activities data through the API.

viewProduct, viewReco, clickReco, and addToCart are the required activities. During implementation, confirm that you’re making the API calls to send each activity when these events occur. See `Specification` - `Endpoints` - `Activities` for details on the API calls.

- viewProduct - Send this activity one time when a shopper views any product detail page.
- viewReco - Send this activity when viewing every set of recommendations.<br>
  **note:** Ideally, you send this activity when a user views recommendations, but that is not required. Instead, send this activity when recommendations are loaded and displayed.

- clickReco - Send this activity every time a shopper clicks a recommendation.
- addToCart - Send this activity every time a shopper adds a product to the cart.

To confirm that the API successfully sends activities, make sure that the API call returns a “200 - OK” status response code. To confirm the response, go to the [Einstein Configurator](https://configurator.cquotient.com/) and check the activity health status dashboard on the API page. If Einstein receives an activity 5 times or more in the last 7 days, that activity is marked as healthy. The system marks fewer than 5 received activities as unhealthy, or indicates when no activities are received at all.

Activities for a recommender typically appear within 48 hours in the Einstein dashboard tab in the Reports and Dashboards app. To make separate reporting and troubleshooting easier, we recommend that you create separate recommenders for the Einstein Recommendations API.

**note:** The `finishCheckout` activity is also required. However, because it’s likely your site is already enabled on the B2C Commerce platform, the `finishCheckout` activity is sent automatically.

If the required activities are not passed to the Einstein API, reporting on the Einstein dashboard tab in the Reports and Dashboards app is affected. The content generated for this report is based on these required activities.

<!-- document id=c4c4284e57247c1a005503de05b3e409a6a3d3f353c8730b457bff65e3a47d79 url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-profile-connector/send-profile-data.md -->

# Send Profile Data

Developers can set up two ways for customers to send shopper profile attributes to Einstein: bulk upload and real-time activity tracking. You can use either method (or both) to send shopper profile data to Einstein.

When submitting data to Einstein, keep the following in mind:

- Salesforce strongly recommends that you do not send personal identifiable information (PII) to Einstein other than the specified recommended user identifiers.
- All collected data is stored internally for up to one year. At the one year mark, data is aged out and removed from all Einstein databases. To continue using this profile data, you must resend it to Einstein.
- When updating data, make sure to upload all existing, unchanged data along with the most recent data changes. Newly uploaded data replaces any previously uploaded data based on the original upload method. For example, uploading new bulk profile data replaces existing bulk profile data, and uploading new real-time profile data replaces existing real-time profile data.
- Einstein uses all profile data provided. New data is not valued any differently than existing data.

## Bulk Upload

Salesforce offers a secure [bulk upload endpoint](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-profile-connector?meta=sendBulkProfile) for customers to upload any historical shopper profile data they have collected.

The bulk upload option is intended for:

- Any shopper profile-related data that you have tracked and collected.
- Any trusted third-party data that you want Einstein to use for added shopper personalization.

### Authorization

Uploading data in bulk can have a major impact on Einstein data. For this reason, we allow only authorized users to upload large quantities of data. In addition, each upload API call must pass a required authorization header (bearer) access token obtained from Account Manager.

**Note:** To reduce load on the Account Manager server, avoid generating any new tokens until the current token expires. Refer to the API Specification for more information on bulk upload API calls.

### Preparing Bulk Upload Data

To prepare bulk upload data for Einstein consumption, make sure of the following:

- The bulk file is a gzipped tab-separated values (TSV) file.
- The TSV file is properly formatted and saved using UTF-8 character encoding.
- The mimetype of the file is set correctly for use by the gzip application.
- The header row must contain the `login_id` identification field, `email_address` identification field, or both.
- Add additional columns for every shopper profile attribute that you want to send.
- Values are either strings or lists of strings. For a list of strings, make sure to separate values using the pipe (|) separator. For example, `orange|yellow`.
- Empty columns are ignored. When Einstein encounters an empty column, it skips that column and continues processing the remaining user attributes data.

### Bulk Upload User Identifiers

To help generate relevant product recommendations for each shopper, the Profile Connector API needs either of these user identifiers for shopper identification in bulk upload.

| Field         | Description                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| login_id      | Shopper's login ID. In some cases this is the same as the email_address value. |
| email_address | Shopper's full email address. For example, shopper1@somewhere.com.             |

### Example Bulk Upload Data

Here is an example of shopper profile bulk upload TSV data with random column names:

| login_id | email_address          | gender | colors             | brand_list     |
| -------- | ---------------------- | ------ | ------------------ | -------------- |
| shopper1 | shopper1@somewhere.com | male   | orange\|yellow     | brandA\|brandB |
| shopper2 | shopper2@somewhere.com | female | blue\|black        | brandD         |
| shopper3 | shopper3@somewhere.com | female | red\|black\|violet | brandB\|brandE |

### Shopper Bulk Upload Endpoint Limitations

When performing shopper profile bulk upload, keep the following endpoint limitations in mind:

- Upload only one file at a time. However, you can upload multiple files, one after another.
- The maximum allowed file size is 2 GB.

### Uploading Shopper Profile Bulk Data to Einstein

After you prepare the shopper profile bulk data files, gzip each individual file and upload it to Einstein’s shopper profile bulk upload endpoint. For more information, refer to the [Send bulk profile endpoint](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-profile-connector?meta=sendBulkProfile).

## Real-Time Activity Tracking

Use the activity [updateProfile tracking endpoint](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-profile-connector?meta=sendUpdateProfile) to call and send real-time shopper profile data updates and preferences. Capturing information that a shopper provides in your storefront in real time enables recommendations to reflect these changes immediately.

The real-time activity tracking option is intended for:

- Capturing shopper preference activities in real time.
- Making shopper profile updates in real time.

To help generate relevant product recommendations for each shopper, the Profile Connector API provides two user identifiers for shopper identification in real-time tracking.

- `cookieId` (required) - Unique identifier of an anonymous shopper. Typically, the cookieId is the value of a first-party cookie.
  - When making API requests from a traditional B2C Commerce storefront, pass the `cqcid` cookie value to match the automatic activity tracking on the traditional storefront. For more information, see [Browser-Based Local Data Storage](https://help.salesforce.com/s/articleView?id=cc.b2c_local_data_storage.htm&type=5).
  - When using OCAPI or the Salesforce Commerce API, use the `visit_id` value from the guest login response to match automatic activities. For more information, see the [OCAPI Customer Document](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer).
- `userId` (encouraged) - Unique identifier of a logged-in shopper. This parameter enables Einstein to link the same logged-in user across multiple devices.
  - When making API requests from a traditional B2C Commerce storefront, use the `cquid` cookie value to match automatic activity tracking on the traditional storefront. For more information, see [Browser-Based Local Data Storage](https://help.salesforce.com/s/articleView?id=cc.b2c_local_data_storage.htm&type=5).
  - When using OCAPI or the Salesforce Commerce API, use the `hashed_login` value from the registered login response to match automatic activities. For more information, see the [OCAPI Customer Document](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-customers?meta=type%3Acustomer).

**note:** To avoid potential malicious activity, user identifier parameters must be non-sequential. The parameters should not include sequences, patterns, IP addresses, email addresses, names, or anything linked to a specific person. All user identifier parameters must comply with General Data Protection Regulation (GDPR) through hashing or other methods.

<!-- document id=ce243494c920159ac0eb23f4a9c1f6c502a763211d1ea1ef0751aae15e9891e7 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-data360.md -->

# Send Storefront Next Analytics Events to Data 360

To unify your customer data on Salesforce, connect Storefront Next to [Data 360](https://help.salesforce.com/s/articleView?id=data.c360_a_data_cloud.htm). After you set your store as a data source, Data 360 receives engagement events, which are triggered by shopper activities in your storefront.

These engagement events are supported.

- `view_page`: A shopper views a page.
- `view_product`: A shopper views a product detail page.
- `view_search`: A shopper views a category or listing page.
- `view_category`: A shopper performs a product search.
- `view_recommender`: A shopper views personalized recommendations.

## Prerequisites

To use Data 360 with Storefront Next, you must first set up your own production instance of Data 360. See [Get Started Using Data 360](https://help.salesforce.com/s/articleView?id=data.c360_a_product_considerations.htm) in _Salesforce Help_.

## Set Up Storefront Next Events for Data 360

1. To connect your storefront to Data 360, complete the instructions from [Connect a Website or Mobile App to Data 360](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-set-up-mobile-web-connection.html) in the _Data 360 Integration Guide_. When the New Connection window asks what you’re connecting to, select **A Custom Website**.
2. To start sending data from your storefront to Data 360, complete the instructions from [Create a Web or Mobile App Data Stream](https://developer.salesforce.com/docs/data/data-cloud-int/guide/c360-a-mobile-web-datastream.html) in the _Data 360 Integration Guide_.
3. Get the Data 360 tenant ID.
   1. In Data 360, click ![Setup](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/comm-setup-icon-no-border.png) at the top of the page, and then select **Data 360 Setup**.
   2. In the Your Home Org Details section, copy and save the tenant ID from the tenant endpoint. The tenant ID is the string preceding the first period. For example, `<tenantId>.c360a.salesforce.com`.
4. Get the Data 360 app source ID.
   1. Go back to Data 360 Setup.
   2. In the Set Up Data 360 section, click **Connect Other Data Sources | Website and Mobile App**.
   3. Select the connection for your Storefront Next storefront.
   4. In the Integration Guide section, copy and save the app source ID from the script. The app source ID is the string preceding `/scripts`. For example, `https://cdn.pc-rnd.c360a.salesforce.com/beacon/c360a/<appSourceId>/scripts/c360a.min.js`.
5. Update your Storefront Next project’s `config.server.ts` with the Data 360 tenant and app source IDs from steps 3 and configure the adapter under `engagement.adapters.data360`. Here’s an example, with placeholders for your IDs:

   ```javascript
   engagement: {
       adapters: {
           data360: {
               enabled: true,
               appSourceId: '<your-app-source-id>',
               tenantId: '<your-tenant-id>',
               siteId: '<your-site-id>',
           },
       },
   }
   ```

   `<your-app-source-id>`, `<your-tenant-id>`, and `<your-site-id>` are required. For the full field reference, including `webStoreId`, `consentCategory`, and the per-event `eventToggles`, see [Set Up Data 360](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-analytics.md#set-up-data360).

## Verify Event Retrieval

1. In Data 360, click **Data Explorer**.
2. Select a data space.
3. From the Object dropdown list, select **Data Model Object**.
4. In the object field, search for and select **Website Engagement**.
5. To personalize your data view, click **Edit Columns** and select the columns corresponding to the data points you want to view.
6. In your store‘s test environment, try out shopper activities: search for a product, view a product detail page, and so on.
7. Refresh your Data Explorer tab and verify that engagement event data appears.

For more information about how B2C Commerce storefronts can integrate with Data 360, see [Sending B2C Commerce Engagement Events to Data 360](https://help.salesforce.com/s/articleView?id=cc.b2c_data_cloud_send_engagement_events_container.htm) in _Salesforce Help_.

<!-- document id=fc09ade0fb911a0b6c6a80ecc5f3611729b84bbc1d89c7e7cba95fa9e77640e1 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-sending-email-via-scripts-or-hooks.md -->

# Sending Email Using Scripts or Hooks

If you’re creating a pipeline, the preferred method of sending an email is to use the SendMail pipelet. However, to create an OC API hook to send email or send email from inside a script, use the `dw.net.mail` class to construct an email and send it. Use `dw.net.mail` with the new `dw.util.Template` class to construct an email using an ISML template.

## Differences Between Sending Email Via dw.net.Mail and the SendMail Pipelet

- With `dw.net.Mail` you must set the subject, mail body, and the to, cc, or bcc. If you don’t, the invocation of `mail.send()` fails with an `IllegalArgumentException`.
- Any tags provided in a template for `to`, `from`, `subject`, or other fields are ignored and not used. Only the values provided by the `dw.net.Mail.set*` arguments are used to generate an email.
- Although a variable called `pdict` is accessible from within the ISML template, it isn't the Pipeline Dictionary. Pipeline Dictionary default data, such as `Session,` isn’t accessible.
- The `Mail.send()` returns the `OK` status if the email is successfully queued to the internal mailing queue, or `ERROR` if the email couldn’t be queued. The email itself is placed on the mail queue asynchronously, meaning that it isn’t sent if there’s a problem with the mail server.

## Creating Mail with Plain String Content

The following script uses the `dw.net.Mail` setter methods to create an email using only simple strings.

```

importPackage( dw.net );
importPackage( dw.system );

function sendMail() {

     var mail: Mail = new dw.net.Mail();
     mail.addTo("to@example.org");
     mail.setFrom("from@example.org");
     mail.setSubject("Example Email");
     // sets the content of the mail as plain string
     mail.setContent("plain string");
     mail.send();
}

```

## Creating Mail with Static Content and Header Information

The following script uses the `dw.net.Mail` setter methods to create an email with an HTML body and header information.

```
importPackage( dw.net );
importPackage( dw.system );

function sendMail() {

     var mail: Mail = new dw.net.Mail();
     mail.addTo("to@example.org");
     mail.setFrom("from@example.org");
     mail.setSubject("Example Email");
     // sets the content of the mail as plain string
     mail.setContent(“
         <html>
         <head><title>Welcome</title></head>
         <body><b>Thank you</b> for registering at our shop!</body>
         </html>”,“text/html”,“UTF-8”);

     mail.send();
}
```

## Creating Mail Based on a Template

The following script uses the `dw.net.Mail` setter methods to create an email and send it to the internal mail queue.

Because mail can be sent outside the scope of a Pipeline Dictionary, we can't rely on using Pipeline Dictionary access. Although the `pdict` variable is still available, it isn't the Pipeline Dictionary. All data within a Pipeline Dictionary is only available if it's within the parameter map at rendering time.

### Template

A simple template with some customized content for a specific user.

Access parameters created in the parameter map in the script through `<isprint value="${param.parameter}">`, as this name reflects the type of object one is working with.

```
<iscontent type="text/html" charset="UTF-8">

<html>
<head><title>${Resource.msg('user.passwordemail.001','user',null)}</title></head>
<body>
 <div style="font-family: Verdana, Geneva, Arial, Helvetica, sans-serif; font-size: x-small; color: Black;">
 ${Resource.msg('user.passwordemail.002','user',null)}&nbsp;<isprint value="${param.customer}">&nbsp;${Resource.msg('global.symbol.comma','global',null)}
 <br/><br/>
 ${Resource.msg('user.passwordemail.004','user',null)}&nbsp;<isprint value="${pdict.resetPassword}">${Resource.msg('global.symbol.period','global',null)}
 <br/>
 ${Resource.msg('user.passwordemail.006','user',null)} <a href="${URLUtils.https(false, 'Login-Show')}">${Resource.msg('user.passwordemail.007','user',null)}</a> ${Resource.msg('user.passwordemail.008','user',null)}
 <br />
 ${Resource.msg('user.passwordemail.009','user',null)}
 <br /><br />
 &nbsp;
 </div>
</body>
</html>
```

### Salesforce B2C Commerce Script

This script:

1.  Creates a parameter map, which holds all parameters required to render the template.
2.  Specifies and renders a template with the given parameter map
3.  Creates a mail object and a mail body, using the MIME encoded text generated by rendering the template in the previous step.

```
importPackage( dw.net );
importPackage( dw.value );
importPackage( dw.util );
importPackage( dw.system );

function sendMail() {
     var template: Template = new dw.util.Template(“myTemplate.isml”);

     var o: Map = new dw.util.HashMap();
     o.put("customer","User");
     o.put("resetPassword","reset");

     var text: MimeEncodedText = template.render(o);

     var mail: Mail = new dw.net.Mail();
     mail.addTo("to@example.org");
     mail.setFrom("from@example.org");
     mail.setSubject("Example Email");
     mail.setContent(text);
     mail.send();

}
```

<!-- document id=a827ab2ae8e159d2089a4ef9fe00e24177cf770796e842d350e5f9ee41630370 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/seo.md -->

SEO

# SEO

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/seo/seo-oas-v1-public.yaml)

## API Overview

This API uploads a custom sitemap and triggers the sitemap generation process.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the `Authorization` header of your API request.

You must include the relevant scope(s) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) guide.

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Related APIs

*   [Shopper SEO](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=Summary) — Resolve SEO-friendly URLs for shoppers.

**Version:** 1.0.12

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/site/seo/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.seo.rw: Allows write operations on seo.
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### PUT Upload a custom sitemap and trigger sitemap generation process.

`PUT /organizations/{organizationId}/sitemap`

Operation ID: `uploadCustomSitemapAndTriggerSitemapGeneration`. Security: AmOAuth2 (sfcc.seo.rw).

This API uploads a custom sitemap and triggers the sitemap generation process.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `multipart/form-data`. Schema: `SitemapRequest`.

_Example: sitemapRequestBody_

```
{
  "customSitemapFile": "sitemap.xml",
  "hostname": "secure.sitegenesis.com"
}
```

#### Responses

*   **202** The site generation process runs asynchronously and takes a few minutes to complete. The generated sitemap is available at the location specified in the location header.
    
    Headers:
    
    *   `Location` (Location) The generated sitemap location url
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: putSitemap400_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The custom sitemap must be an XML file."
    }
    ```
    
*   **404** The given hostname was not found in the alias file.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: putSitemap404_
    
    ```
    {
      "title": "The given hostname was not found in the alias file.",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors",
      "detail": "The hostname was not found in the alias file.",
      "hostname": "www.abc.com"
    }
    ```
    
*   **409** The requested action could not be completed because the job is currently running and its state is being updated.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: putSitemap409_
    
    ```
    {
      "title": "Sitemap Generation In Progress",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The previous generate sitemap request has not completed."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SitemapRequest

*   `customSitemapFile` (_string_, required) The custom sitemap file to be uploaded. Must conform to the [Sitemap Protocol](https://www.sitemaps.org/protocol.html), with a root `<urlset>` element and well-formed `<url>` entries.The filename must not start with `sitemap` nor contain forward or backward slashes. The file must contain valid xml content and the filename must have an .xml extension.  
    Maximum length: 4000. Example: `custom-sitemap.xml`.
*   `hostname` (_string_, required) The hostname for which the sitemap will be generated. The hostname must be listed in the aliases file in Business Manager  
    Minimum length: 1. Maximum length: 4000. Example: `www.abc.com`.

### Location

URL where the resource is located.

Type: `string`.

Maximum length: 2048. Example: `/index.html`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

<!-- document id=ae0d43815b98471d3d231dba8865d5269538e08f2a2fb84b3f398b25bbba4b26 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-seo-metadata.md -->

# SEO and Metadata

Storefront Next template’s built-in SEO features helps optimize your store’s search and product discoverability. The storefront template provides SEO features with `hreflang` alternate links, canonical URLs, page titles, meta tags, indexing control, and structured data (JSON-LD)

## Hreflang Alternate Links

The storefront can render locale-aware `<link rel="alternate" hreflang="...">` tags in the document `<head>`. These tags are generated centrally in [`src/utils/seo.ts`](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/src/utils/seo.ts) and returned from the root [`meta` export in `src/root.tsx`](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/src/root.tsx).

### Why It Matters

Search engines use `hreflang` to understand whether several pages are regional or language-specific versions of the same content.

For an ecommerce storefront, the alternate links feature is especially useful because:

- It helps search engines send shoppers to the right language or locale version of a product, category, or content page.
- It reduces confusion between similar pages that differ only by locale, currency, or URL prefix.
- It increases the likelihood that international shoppers land on the version of the storefront that matches their market.

### How It Works

The root loader calls `buildSeoMetaDescriptors(...)`, which returns:

1. A canonical `<link rel="canonical">`
2. One `<link rel="alternate" hreflang="...">` per supported locale
3. An `x-default` alternate pointing to the site's default locale

The alternate URLs are built from the current request path plus the configured multisite URL prefix. In practice, this means:

- Locale-specific URLs are generated automatically from `site.supportedLocales`.
- Locale aliases are respected when configured in the multisite setup.
- The current locale prefix is stripped before alternates are rebuilt, so switching locales keeps the same logical page path.
- Query parameters follow the same canonical normalization rules described in a section later.
- Each page includes a self-referencing hreflang tag pointing to itself, which Google requires for valid hreflang sets.

### Example Output

```html
<!-- When viewing the en-GB version of a page with en-GB (default) and fr-FR locales: -->
<link rel="canonical" href="https://www.example.com/global/en-GB/product/123" />
<link rel="alternate" hreflang="en-GB" href="https://www.example.com/global/en-GB/product/123" />
<!-- self-referencing -->
<link rel="alternate" hreflang="fr-FR" href="https://www.example.com/global/fr-FR/product/123" />
<link
  rel="alternate"
  hreflang="x-default"
  href="https://www.example.com/global/en-GB/product/123"
/>
```

### When You Need to Change `hreflang` Tags

You usually don't add `hreflang` tags in route components manually. Update this centralized logic only if you change:

- The multisite URL prefix format
- How locale aliases map into URLs
- Which query parameters are considered content-bearing for canonicalization

## Canonical URLs

Every page renders a `<link rel="canonical">` tag in the `<head>`. This tells search engines which URL should be treated as the preferred version of the page.

### Why It Matters

Search engines often discover multiple URLs that show the same page content. Canonical URLs tell them which version should receive SEO credit.

For an ecommerce storefront, canonical URLs are useful because:

- Product and category pages often collect tracking parameters, sort parameters, and filter parameters that can create many URL variations.
- It helps consolidate ranking signals instead of spreading them across duplicate URLs.
- It lowers the risk of duplicate-content problems on search, category, and product detail pages.

### How It Works

The canonical URL is built in [`src/utils/canonical-url.ts`](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/src/utils/canonical-url.ts). Storefront Next adds it to the root-level SEO descriptors generated by [`src/utils/seo.ts`](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/src/utils/seo.ts) and renders it from [`src/root.tsx`](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/src/root.tsx).

It applies three normalizations:

1. **Allowlisted query parameters** — Only parameters that change page content are kept. Everything else (tracking params, analytics IDs, unknown params) is stripped.
2. **Sorted parameters** — Retained params are sorted alphabetically so that `?sort=price&q=jacket` and `?q=jacket&sort=price` produce the same canonical URL.
3. **Trailing slash removal** — Trailing slashes are removed from non-root paths (`/product/jacket/` → `/product/jacket`).

### Query Parameter Allowlist

The canonical URL uses an **allowlist** that specifies which query parameters are kept in canonical URLs. Storefront Next strips any parameter not explicitly listed, such as tracking parameters, analytics IDs, and other non-content parameters.

The current allowlist is defined in `src/utils/canonical-url.ts`:

| Parameter | Purpose            | Used by             |
| --------- | ------------------ | ------------------- |
| `q`       | Search query       | Search page         |
| `offset`  | Pagination offset  | Category, Search    |
| `sort`    | Sort order         | Category, Search    |
| `refine`  | Filter refinements | Category, Search    |
| `pid`     | Product variant ID | Product detail page |

### Adding a Custom Query Parameter

If you add a feature that uses a new query parameter to change the page's main content, add it to the allowlist so it's kept in the canonical URL and in locale alternates.

**Example:** You add a `?view=grid` parameter that switches between grid and list layouts with different product data.

1. Open `src/utils/canonical-url.ts`
2. Add the parameter to the `CONTENT_PARAMS` set:

```typescript
const CONTENT_PARAMS = new Set([
  "q",
  "offset",
  "sort",
  "refine",
  "pid",
  "view", // layout mode (grid/list)
]);
```

3. Add a corresponding test in `src/utils/canonical-url.test.ts`:

```typescript
it("preserves view param", () => {
  expect(buildCanonicalUrl(origin, "/category/mens", "?view=grid")).toBe(
    "https://www.example.com/category/mens?view=grid",
  );
});
```

**When not to add a parameter:** If the parameter doesn't change the page's main content, don't add it to the allowlist. Examples include analytics flags, modal triggers, and UI preferences.

## Page Titles and Meta Tags (`SeoMeta`)

`SeoMeta` is a React component defined in [`src/components/seo-meta/index.tsx`](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/src/components/seo-meta/index.tsx). Route components render this component to add page-level `<title>` and `<meta>` tags. `SeoMeta` handles page titles, descriptions, robots directives, Open Graph tags, and X (formerly Twitter) Card tags.

Canonical and `hreflang` links are **not** rendered by `SeoMeta`. Those are generated centrally at the root level, as described above.

React hoists these tags into `<head>` automatically, so you can render the `SeoMeta` component inside a route component and the final tags still end up in the right place.

### Why It Matters

The page title and meta tags help search engines understand what a page is about and how it should appear in search results or link previews.

For an ecommerce storefront, these tags are especially useful because:

- Clear titles help product, category, and content pages compete for relevant searches.
- Good descriptions can improve click-through rate from search results.
- Consistent metadata makes it easier for search engines to understand the difference between product, category, cart, account, and content pages.

### What `SeoMeta` Renders

| Concern               | Tags                                                                          |
| --------------------- | ----------------------------------------------------------------------------- |
| Title                 | `<title>`                                                                     |
| Description           | `<meta name="description">`                                                   |
| Robots                | `<meta name="robots" content="noindex">` when `noIndex` is true               |
| Open Graph            | `og:title`, `og:description`, `og:type`, `og:url`, `og:image`, `og:site_name` |
| X Card / Twitter Card | `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`       |

### Basic Usage

```tsx
import { SeoMeta } from "@/components/seo-meta";

// `SeoMeta` is a component that you render in your route
// Standard page — site name is appended automatically
// Renders: <title>Classic Jacket | My Storefront Next Store</title>
<SeoMeta
  title="Classic Jacket"
  description="A premium leather jacket with a tailored fit."
  openGraph={{
    type: "product",
    url: "https://www.example.com/product/classic-jacket",
    image: "https://www.example.com/images/classic-jacket.jpg",
  }}
/>;
```

### Props

| Prop          | Type      | Default                       | Description                                                                                                                                                |
| ------------- | --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `title`       | `string`  | —                             | Page title. By default it renders as `{title} \| {siteName}`. If omitted, the site name alone is used.                                                     |
| `rawTitle`    | `boolean` | `false`                       | Render `title` exactly as given, with no `\| {siteName}` suffix. See [Title Modes](#title-modes) below.                                                    |
| `description` | `string`  | —                             | Meta description. Also reused for Open Graph and X Card description tags when those are rendered.                                                          |
| `noIndex`     | `boolean` | `false`                       | Adds `<meta name="robots" content="noindex">`.                                                                                                             |
| `siteName`    | `string`  | `t('common:defaultSiteName')` | Override the site name used in the title suffix and `og:site_name`.                                                                                        |
| `twitter`     | `object`  | —                             | X Card metadata (`cardType`, `image`). The `twitter:` meta tag prefix is part of the Card spec and is still used by X.                                     |
| `openGraph`   | `object`  | —                             | Open Graph metadata (`type`, `url`, `image`) for social sharing. When provided without `twitter`, X Card tags are auto-derived from the Open Graph values. |

### Title Modes

`SeoMeta` supports two title modes through the `title` and `rawTitle` props:

| Mode                   | Props                      | `<title>` output                      | When to use                                                                              |
| ---------------------- | -------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Suffixed** (default) | `title="My Page"`          | `My Page \| My Storefront Next Store` | Most pages: product, category, search, account, and content pages.                       |
| **Raw**                | `rawTitle title="My Page"` | `My Page`                             | Pages that need full control, for example, the homepage that passes the full store name. |
| **Fallback**           | _(no title)_               | `My Storefront Next Store`            | Only the site name.                                                                      |

**Examples:**

```tsx
// Suffixed (default) — most pages use this
<SeoMeta title="Classic Jacket" />
// → <title>Classic Jacket | My Storefront Next Store</title>

// Raw — homepage or any page needing exact title control
<SeoMeta rawTitle title="My Storefront Next Store — Shop the Latest" />
// → <title>My Storefront Next Store — Shop the Latest</title>

// Fallback — no title provided
<SeoMeta />
// → <title>My Storefront Next Store</title>
```

### General Meta Tag Behavior

- **Title** comes from `title` and also contains the localized site name suffix unless `rawTitle` is set.
- **Description** renders `meta[name="description"]` and is reused for Open Graph and X Card descriptions.
- **Open Graph** is opt-in via the `openGraph` prop.
- **X Card / Twitter Card** is opt-in via the `twitter` prop, or auto-generated from `openGraph`.
- **Robots** only renders when `noIndex` is set for pages that should not be indexed.

### Why Each Meta Tag Helps

- **Title**: Search engines use the page title as a strong signal for what the page is about, and it is often shown as the main clickable headline in search results.
- **Description**: Search engines may use the meta description as the summary snippet in search results, which can help attract clicks.
- **Open Graph**: Social platforms use these tags when a page is shared, helping product and content links look more complete and trustworthy.
- **X Card / Twitter Card**: Similar to Open Graph, these tags improve how shared links appear on X.
- **Robots / `noIndex`**: This helps keep low-value or private pages out of search results so search engines focus on pages shoppers should actually land on.

### Open Graph and X Card Behavior

When `openGraph` is provided, `SeoMeta` renders:

- `og:title`
- `og:description` when `description` is present
- `og:type` (defaults to `website`)
- `og:url` when provided
- `og:image` when provided
- `og:site_name`

When `twitter` is provided, or when `openGraph` is provided without an explicit `twitter` prop, `SeoMeta` renders:

- `twitter:card`
- `twitter:title`
- `twitter:description` when `description` is present
- `twitter:image` when an image is available

If `openGraph.image` is present and `twitter.cardType` is not set, the card defaults to `summary_large_image`; otherwise it defaults to `summary`.

### Why Social Tags Matter for SEO

Open Graph and X Card tags aren't direct search ranking factors, but they're still valuable for storefront SEO. When someone shares a storefront URL on a platform such as Facebook, LinkedIn, X, Slack, or other messaging tools, that platform's crawler usually fetches the page and reads its social metadata.

The crawler uses tags such as:

- `og:title` or `twitter:title` for the preview headline
- `og:description` or `twitter:description` for the preview summary
- `og:image` or `twitter:image` for the preview image
- `twitter:card` to decide which X card layout to use

This metadata helps the platform build a richer preview card instead of showing a plain URL.

For an ecommerce storefront, this is useful because:

- Product, category, and campaign links look more polished and trustworthy when shared.
- Preview cards can show the product name, a useful summary, and a strong product image before the shopper even clicks.
- Better-looking previews can improve click-through from social, messaging, affiliate, and marketing channels.
- Consistent preview data reduces the chance that a platform picks incomplete or low-quality fallback content from the page.

### Canonical URL Consistency for Social Tags

For pages that supply `openGraph.url`, pass the same absolute URL that you want search engines to treat as canonical. In most routes, this is the canonicalized `pageUrl` built in the loader.

This keeps search and social signals aligned around the same preferred URL.

### Changing the Site Name

The site name appended to page titles (for example, `" | My Storefront Next Store"`) comes from the `common.defaultSiteName` translation key. To change it, update the value in each locale's `translations.json`:

```json
// src/locales/en-US/translations.json
{
  "common": {
    "defaultSiteName": "Your Store Name"
  }
}
```

You can also override it per-route via the `siteName` prop:

```tsx
<SeoMeta title="Sale" siteName="My Outlet Store" />
// Renders: "Sale | My Outlet Store"
```

### Route Patterns

The template uses two common patterns depending on whether a page is public or auth-protected.

**Public pages**: Include both title and description.

```tsx
<SeoMeta
  title={t("meta.title", { defaultValue: "About Us" })}
  description={t("meta.description", { defaultValue: "Learn more about our story." })}
/>
```

**Auth-protected or transactional pages**: Include a title for browser tab UX, but omit the description and set `noIndex`.

```tsx
<SeoMeta title={t("meta.title", { defaultValue: "Order History" })} noIndex />
```

### Adding Meta Tags to a New Page

1. Import `SeoMeta` and render it inside your route component:

```tsx
import { SeoMeta } from "@/components/seo-meta";

export default function MyNewPage() {
  const { t } = useTranslation("myPage");

  return (
    <>
      <SeoMeta
        title={t("meta.title", { defaultValue: "My Page" })}
        description={t("meta.description", { defaultValue: "Description of my page." })}
      />
      {/* page content */}
    </>
  );
}
```

2. If the page should be shared socially, pass `openGraph` and optionally `twitter`.
3. All title and description strings use i18n with `defaultValue` fallbacks. To localize them, add the corresponding keys to your translation files, for example `meta.title` and `meta.description`.

### Where `SeoMeta` Is Used

| Route                          | Title               | Description                       | Open Graph / Twitter | noIndex |
| ------------------------------ | ------------------- | --------------------------------- | -------------------- | ------- |
| `/` (Home)                     | Store name (raw)    | Welcome message                   | Yes                  | —       |
| `/category/:id`                | Category name       | Category page/general description | Yes                  | —       |
| `/product/:id`                 | Product name        | Product page/short description    | Yes                  | —       |
| `/search`                      | Search query        | Result count + query              | Yes                  | —       |
| `/about-us`                    | About Us            | Store mission description         | Yes                  | —       |
| `/login`                       | Sign In             | Sign in prompt                    | Yes                  | —       |
| `/cart`                        | Cart                | Cart review prompt                | Yes                  | —       |
| `/signup`                      | Sign Up             | Account creation prompt           | Yes                  | —       |
| `/checkout`                    | Checkout            | —                                 | No                   | Yes     |
| `/order-confirmation/:orderNo` | Order Confirmation  | —                                 | No                   | Yes     |
| `/account/*` (all sub-pages)   | Page-specific title | —                                 | No                   | Yes     |

**Note on search and cart indexability:** The template indexes `/search` and `/cart` by default. Some storefronts prefer to add `noIndex` to internal search results (to avoid thin/duplicate content) and to the cart page (session-specific content). Evaluate whether these pages provide value as search landing pages for your store and add noIndex if they do not.

### Why Some Pages Use `noIndex`

Pages behind authentication (account, wishlist, orders) and transactional pages (checkout, order confirmation) use `noIndex` because:

- **Account pages aren't useful landing pages for search**: Crawlers trying to visit account, wishlist, or order pages will usually be redirected to the login page instead of seeing the actual account content.
- **Checkout pages are often empty without shopper state**: A crawler visiting checkout without an active basket will usually see an empty or unusable checkout experience, which is not helpful in search results.
- **Some pages are session-specific**: An order confirmation page or another shopper-specific page has no value for a general search audience.

If your implementation exposes any of these pages publicly (for example, shared wishlists), remove `noIndex` from those routes.

### Why `noIndex` Helps

Search engines work best when they focus on pages that are useful landing pages for shoppers.

For an ecommerce storefront, `noIndex` helps by:

- Keeping checkout, account, and other private flows out of search results
- Preventing thin, empty, or session-specific pages from being indexed
- Helping search engines spend more attention on high-value pages such as product, category, brand, and content pages

<!-- document id=c2a643fde8bcc30e70d8fb22c7b4092d223ff9347a33b6628a56c71818479180 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-seo-metadata.md -->

# SEO and Metadata Differences with PWA Kit

PWA Kit uses react-helmet to manage meta tags, with developers manually adding Helmet components to each page. Storefront Next provides a comprehensive SEO system built around the `SeoMeta` component, with built-in support for hreflang alternates, canonical URLs, Open Graph, Twitter Cards, and robots control. Both support dynamic metadata, but Storefront Next offers a more complete, production-ready SEO implementation out of the box.

## Key Differences

| Aspect          | PWA Kit                    | Storefront Next                    |
| --------------- | -------------------------- | ---------------------------------- |
| Library         | react-helmet               | Built-in React component (SeoMeta) |
| Pattern         | Manual Helmet in each page | SeoMeta component                  |
| Dynamic Meta    | Implemented via Helmet     | Implemented via SeoMeta            |
| Hreflang        | Not documented             | Automatic locale alternates        |
| Canonical URLs  | Not documented             | With query param normalization     |
| Robots Control  | Manual via Helmet          | Built-in `noIndex` prop            |
| Social Tags     | Manual via Helmet          | Open Graph + Twitter Card support  |
| API Integration | Consumes `pageMetaTags`    | Uses SeoMeta with dynamic props    |

## Head Management Approach

PWA Kit:

```javascript
// Per-page Helmet usage
import { Helmet } from "react-helmet";

export default function ProductDetail() {
  return (
    <>
      <Helmet>
        <title>{product.pageTitle}</title>
        <meta name="description" content={product.pageDescription} />
      </Helmet>
      {/* page content */}
    </>
  );
}
```

Storefront Next:

```typescript
// SeoMeta component usage
import { SeoMeta } from "@/components/seo-meta";

export default function ProductDetail() {
  return (
    <>
      <SeoMeta
        title={product.pageTitle}
        description={product.pageDescription}
        openGraph={{
          type: "product",
          url: canonicalUrl,
          image: product.imageUrl,
        }}
      />
      {/* page content */}
    </>
  );
}
```

## API Meta Tag Consumption

PWA Kit consumes the Commerce API's `pageMetaTags` array directly:

```javascript
// PWA Kit: Renders each meta tag from API via Helmet
import { Helmet } from "react-helmet";

<Helmet>
  <title>{product.pageTitle}</title>
  <meta name="description" content={product.pageDescription} />
  {product.pageMetaTags?.map(({ id, value }) => (
    <meta name={id} content={value} key={id} />
  ))}
</Helmet>;
```

Storefront Next uses the `SeoMeta` component with explicit props rather than consuming `pageMetaTags` directly:

```typescript
// Storefront Next: Uses SeoMeta component
import { SeoMeta } from "@/components/seo-meta";

<SeoMeta
  title={product.pageTitle}
  description={product.pageDescription}
  openGraph={{
    type: "product",
    url: canonicalUrl,
    image: product.imageUrl,
  }}
  twitter={{ cardType: "summary_large_image" }}
/>;
```

If you need to consume `pageMetaTags` in Storefront Next, you can map them to the `SeoMeta` props or render them as additional meta tags.

## Key Similarities

1. **Dynamic metadata**: Both support dynamic page titles and meta descriptions.
2. **SSR support**: Both render meta tags server-side for SEO.
3. **Component-based**: Both use React components to manage meta tags.
4. **No structured data**: Neither implements JSON-LD by default (can be added manually).

## Storefront Next Advantages

1. **Hreflang alternates**: Automatically generates locale-specific alternate links with x-default support.
2. **Canonical URLs**: Built-in canonical URL generation with query parameter normalization and allowlist.
3. **Social tags**: Built-in Open Graph and Twitter Card support via `SeoMeta` props.
4. **Robots control**: Simple `noIndex` prop for controlling search engine indexing.
5. **Centralized SEO utils**: SEO logic consolidated in `src/utils/seo.ts` and `src/utils/canonical-url.ts`.
6. **Title modes**: Support for suffixed (default), raw, and fallback title rendering.

## Storefront Next Hreflang Implementation

Storefront Next automatically generates hreflang tags for all supported locales:

```html
<!-- Automatically generated in <head> -->
<link rel="canonical" href="https://www.example.com/global/en-GB/product/123" />
<link rel="alternate" hreflang="en-GB" href="https://www.example.com/global/en-GB/product/123" />
<link rel="alternate" hreflang="fr-FR" href="https://www.example.com/global/fr-FR/product/123" />
<link
  rel="alternate"
  hreflang="x-default"
  href="https://www.example.com/global/en-GB/product/123"
/>
```

PWA Kit does not provide built-in hreflang support. You would need to implement this manually using react-helmet.

## Canonical URL Management

Storefront Next includes sophisticated canonical URL handling with query parameter normalization:

**Allowed parameters** (kept in canonical URL):

- `q` - search query
- `offset` - pagination
- `sort` - sort order
- `refine` - filters
- `pid` - product variant ID

**Removed parameters**: All tracking params, analytics IDs, and non-content parameters are stripped.

PWA Kit does not provide built-in canonical URL management. You would need to implement this manually.

## Storefront Conversion Considerations

When migrating from PWA Kit to Storefront Next:

1. Replace react-helmet with SeoMeta

   - Remove `react-helmet` imports and `<Helmet>` components.
   - Replace with `<SeoMeta>` component from `@/components/seo-meta`.
   - Convert inline meta tags to `SeoMeta` props.

2. Leverage Built-in SEO Features

   - Hreflang alternates are already configured in `src/utils/seo.ts`.
   - Canonical URLs are automatically generated via `src/utils/canonical-url.ts`.
   - Add `openGraph` and `twitter` props to `SeoMeta` for social sharing.

3. Add noIndex for Protected Pages

   - Use `<SeoMeta noIndex />` for account, checkout, and order pages.
   - This prevents search engines from indexing private content.

4. Configure Query Parameters

   - Update `CONTENT_PARAMS` in `src/utils/canonical-url.ts` if you add custom query params that affect page content.

5. Optional: Add Structured Data

   - Consider adding JSON-LD for products, categories, and breadcrumbs.
   - Render `<script type="application/ld+json">` tags within route components.

6. Test Multi-Locale Sites
   - Verify hreflang links are generated correctly for all locales.
   - Confirm canonical URLs strip locale prefixes appropriately.

<!-- document id=4c26531ae0962ea78bd2f4ffc9a56460daaca4840228318ecae18378190e85c4 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-seo-url-rules-best-practices.md -->

# SEO URL Rules Best Practices for Storefront Next

Deterministic SEO URLs let Storefront Next infer a URL's content type (product, category, or content) and fetch that content directly from the path, with no `getUrlMapping` call to resolve the URL. That keeps routing decisions fast and URL patterns predictable, which improves SEO. This guide outlines best practices for configuring SEO URL rules in Storefront Next and Business Manager.

**note:** These best practices suggest some ways to configure SEO URL rules. Other SEO URL configurations can work depending on your needs. These suggestions are subject to change.

## Business Manager Is the Source of Truth

Business Manager defines a site's SEO URL grammar: the product URL prefix, the category URL prefix, whether category URLs carry the category ID or a pure slug path, and the optional content prefix. Business Manager enforces the URL requirements and serves as the canonical configuration for your B2C Commerce instance. Storefront Next mirrors those settings so its generated URLs stay consistent with the rest of your commerce ecosystem.

1. Define the URL structure in Business Manager. See [Configure SEO URLs for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_configuring_seo_urls.htm&type=5) in _Salesforce Help_.
2. Mirror that structure in Storefront Next with the `seoRoutes` configuration (see [Configure `seoRoutes`](#configure-seoroutes)). You do not rename route files to match the grammar.
3. Test URLs in both environments to verify consistency.

## Configure `seoRoutes`

Storefront Next generates product and category URLs from per-site `seoRoutes` configuration in `config.server.ts`, keyed by Commerce site ID. Each site defines a product prefix, a category prefix, a category mode, and an optional content prefix.

```typescript
url: {
    prefix: '/:siteId/:localeId',
    excludeRoutes: ['/resource/**', '/action/**'],
    seoRoutes: {
        RefArchGlobal: {
            product: {prefix: 'p'},
            category: {prefix: 'c', mode: 'id-suffix'},
        },
    },
}
```

- `product.prefix` and `category.prefix` are static path segments without slashes (for example `p`, `c`, `product`, `category`).
- `category.mode` is `id-suffix` or `slug-path` (see [URL Guidance for Categories](#url-guidance-for-categories)).
- `content.prefix` is optional and reserved for standalone content URLs.

With `seoRoutes` set, a product URL is `/{siteId}/{localeId}/{product-prefix}/{slug}/{id}` and a category URL follows the category mode. Generate these URLs with the semantic builders (`createProductUrl`, `createCategoryUrl`, and `createCategoryUrlFromLegacyPath`) rather than hard-coded paths. The builders return the functional path (such as `/{product-prefix}/{slug}/{id}`) and encode each segment; the template's `Link` and navigation wrappers add the `/{siteId}/{localeId}` prefix. Route server-side redirects and plain anchors through the same context-aware builders and wrappers, or they generate an unprefixed URL. The builders make no SCAPI or `getUrlMapping` call.

### You Don't Rename Route Files

Adopting `seoRoutes` doesn't rename, move, or split any file in `src/routes/`. The canonical `_app.product.$productId.tsx` and `_app.category.$categoryId.tsx` modules stay where they are. At build time each becomes a parent that owns its configured prefix, so the configured URLs route back to the same loader and component. Both modules must remain leaf routes (no nested child routes) when `seoRoutes` is enabled, or the build fails.

### Every Active Site Needs an Entry, and Changes Require a Rebuild

When `seoRoutes` is set, every active site must have an entry. The storefront compiles the union of every site's prefixes into its route manifest and drops the built-in `/product/{id}` and `/category/{id}` routes, so a site with no entry can't generate product or category URLs. Treat `seoRoutes` as an all-sites decision, not a gradual per-site rollout.

`seoRoutes` is a protected configuration value: it is compiled into the route manifest and cannot be overridden with a `PUBLIC__` environment variable at runtime. When you change a URL setting in Business Manager, update `config.server.ts` to match, then rebuild and redeploy. Storefront Next doesn't pick up the change automatically.

**note:** Automatic synchronization between Business Manager and Storefront Next is a planned enhancement. Until it ships, treat every Business Manager URL-setting change as a storefront configuration change that requires a rebuild and redeploy.

## URL Guidance by Content Type

### URL Guidance for Products

When you configure URL rules for products, we recommend that the URL:

- Includes this prefix: `/p/`.
- Ends with the product ID. Storefront Next reads the ID from the final path segment and fetches product data directly, with no extra API call to resolve the URL.
- Includes an identifiable slug before the ID. Product slugs are optional because the ID stays authoritative, but a readable slug improves SEO. Product search and search-suggestion responses already include the slug, so tiles, typeahead, and structured data use it without an extra request.

#### Example

```
/p/summer-dress/product-id-12345
```

**note:** The `seoRoutes` grammar Storefront Next generates has no file extension. If your Business Manager URL rules or already-indexed URLs use an `.html` suffix, redirect the `.html` form to the suffix-less canonical URL with a 301 (see [Prevent Broken Indexed URLs](#prevent-broken-indexed-urls-and-redirect-loops)).

### URL Guidance for Categories

`category.mode` decides how a category URL resolves, and each mode has a prerequisite:

| Mode | URL shape | How it resolves | Prerequisite |
|---|---|---|---|
| `id-suffix` | `/c/{slug}/{id}` | Reads the category ID from the final path segment. Deterministic, no `getUrlMapping` call. | Category ID present as the final segment. |
| `slug-path` | `/c/{full-slug-path}` | The final segment is a slug, not the ID. Storefront Next doesn't translate the slug back to an ID. | A slug-to-ID data source you supply for the site. |

We recommend `id-suffix` mode: it keeps category resolution deterministic and requires no additional data source.

As with products, the category slug is optional in `id-suffix` mode. The trailing ID is authoritative, so the storefront also generates slug-less `/c/{id}` URLs. Include a slug when one is available for better SEO.

#### Example

```
/c/furniture/outdoor-furniture/category-id-567
```

**note:** In `slug-path` mode the category URL carries no ID, so Storefront Next cannot resolve it from the path alone. Until you supply a slug-to-ID data source for the site, keep the site in `id-suffix` mode. A pure slug path produces cleaner URLs but depends on that data source.

### URL Guidance for Content Pages

Standalone content URLs use the optional `content.prefix`.

**note:** The `content.prefix` is reserved. Storefront Next validates its format and guards it against collisions with the product and category prefixes, but it doesn't yet check it against static app routes (such as `account`), and it doesn't yet register a content route, so a `content.prefix` URL is not served on its own. Set it to reserve the grammar now; content routing is a planned enhancement.

When you configure URL rules for content pages, we recommend that the URL:

- Includes a content prefix such as `/content/`.
- Includes a content ID or an identifiable slug.

#### Example

```
/content/about-us
/content/shipping-policy
```

## Prevent Broken Indexed URLs and Redirect Loops

Changing a product or category prefix changes every already-indexed URL for that resource. Roll the prefix change and its redirect rules out together, and handle the transition at the CDN or Business Manager redirect layer, not in the storefront.

- **Redirect the old grammar to the new with a single 301.** Map the previous URL form to the new one (for example `/product/{id}` to `/p/{slug}/{id}`). A 301 preserves the page's ranking and keeps inbound links working.
- **Redirect once, directly to the canonical URL.** The canonical URL is the one the storefront now generates. Don't chain redirects, and do not let the new URL redirect back toward the old form. Either one creates a redirect loop that crawlers penalize.
- **Handle `.html` suffixes.** If legacy Commerce URLs ended in `.html`, redirect the `.html` form to the suffix-less canonical URL with a 301. Don't serve both.
- **Match the canonical tag to the redirect target.** Each page's `<link rel="canonical">` must name the same URL the redirects point at. See [SEO and Metadata](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-seo-metadata.md).
- **Regenerate sitemaps.** Sitemap entries must use the new prefixes and contain no legacy-grammar URLs.

## Hybrid Deployments

In a [hybrid storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid.md), some paths are served by Storefront Next and some by the existing Commerce (SFRA or SiteGenesis) storefront. `seoRoutes` governs only the product and category paths Storefront Next owns.

- Storefront Next generates and serves SEO URLs for the sites and paths it owns.
- Paths owned by the legacy storefront keep their Commerce-managed URLs. `seoRoutes` does not rewrite them.
- An inbound URL that matches neither the new grammar nor a redirect rule falls through to the terminal Shopper SEO fallback. For an eligible GET or HEAD request, Storefront Next makes one Business Manager Shopper SEO URL Mapping lookup and, on a hit, redirects to the mapped product, category, or URL destination. A mapping miss, a rejected result, or an ineligible request returns a 404, and in a hybrid deployment a legacy-owned path is left for the legacy storefront. External redirect origins and forwarded query parameters are denied unless you allow them per site in the fallback policy. Still confirm your redirects direct legacy-owned URLs to the storefront that serves them.

## Reference: Market Street

Market Street, the retail reference storefront, uses short prefixes and deterministic `id-suffix` category routing:

```typescript
seoRoutes: {
    MarketStreet: {
        product: {prefix: 'p'},
        category: {prefix: 'c', mode: 'id-suffix'},
    },
}
```

Products resolve at `/{siteId}/{localeId}/p/{slug}/{id}` and categories at `/{siteId}/{localeId}/c/{slug}/{id}`. Copy this shape per site, and remember that every active site needs its own entry before you enable `seoRoutes`.

<!-- document id=889f63d65c899fc87557deaefe3880a0973bfa84e068dd7b24e2c5e0311a360a url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-server-routes.md -->

# Server API Routes

Server API Routes, also known as Resource Routes, are the standard way to fetch and mutate data in Storefront Next. They implement the Backend-For-Frontend (BFF) pattern—your client-side components communicate with these server endpoints, which securely handle B2C Commerce API calls, authentication, and sensitive business logic.

## How It Works

All data fetching routes through server endpoints. Server routes handle:

- API authentication: SLAS flows, client secrets, and token management.
- B2C Commerce API proxying: All SCAPI calls route through server endpoints.
- Callbacks and redirects: Auth redirects, webhooks, JWKS proxying.
- Cookie and header management: Session handling, locale preferences.
- JSON responses: Data for `useFetcher()` or client-side `fetch()` calls.

This approach keeps credentials secure, reduces client bundle size, and centralizes data access patterns.

## The Backend-For-Frontend Pattern

Server routes implement the Backend-for-Frontend (BFF) pattern. Your storefront app acts as an intermediary between the client and backend services.

```
Browser  →  Server Route  →  B2C Commerce API
   ↑                              ↓
   └────── JSON Response ─────────┘
```

This architecture provides:

- API aggregation: Combine multiple Commerce API calls into single endpoints.
- Security: Keep API credentials and sensitive logic on the server.
- Performance: Reduce client-side JavaScript and network requests.
- Flexibility: Transform API responses to match your UI needs.

## Server Route Architecture

Storefront Next uses React Router 7 in framework mode. Routes are defined by files in `src/routes/` by using the flat routes convention.

A route module becomes a **resource route** (API endpoint) when it exports only data functions such as `loader` and `action`, without a default React component.

### Key Concepts

| Term           | Definition                                                              |
| -------------- | ----------------------------------------------------------------------- |
| Server route   | Any route file in `src/routes/` that runs on the server.                |
| Resource route | A server route that exports only data functions (no default component). |
| Loader         | A function that handles GET requests and returns data.                  |
| Action         | A function that handles mutations (POST, PUT, DELETE).                  |

### Naming Conventions

Storefront Next uses these naming conventions.

- `resource.*` files map to `/resource/...` endpoints.
- `action.*` files map to `/action/...` endpoints.
- `loader.*` files map to `/loader/...` endpoints.
- `_empty.*` files bypass parent layouts. Use this prefix when a route needs to render without the standard page wrapper, for example, the logout action that redirects immediately.

## Server-Side Data Layer

All data fetching in Storefront Next happens on the server. Resource routes use `loader` and `action` functions that run server-side for both initial page loads and client-side navigation.

This server-side approach provides:

- Security: Sensitive API keys and business logic stay on the server.
- Performance: Reduced client bundle size.
- Consistency: Single source of truth for data-fetching logic.
- SEO: All data is available during server-side rendering.

**important:** Always use server-side `loader` and `action` functions. While React Router supports `clientLoader` and `clientAction`, Storefront Next enforces a server-only data retrieval. Client-side loaders expose your app to security risks and violates the architecture. If you have a rare edge case that seems to require client-side data fetching, consult with the team before implementing.

## Route Types

Server routes support three main patterns: loaders for GET requests, actions for mutations, and dynamic parameters for flexible endpoints.

### Loader Routes (GET)

Use a `loader` to respond to GET requests. This example shows a store search endpoint.

```typescript
// src/extensions/store-locator/routes/resource.stores.ts
import { data, type LoaderFunctionArgs } from 'react-router'
import { extractResponseError } from '@/lib/utils'
import { createApiClients } from '@/lib/api-clients'

export async function loader({ request, context }: LoaderFunctionArgs) {
    try {
        const url = new URL(request.url)
        const postalCode = url.searchParams.get('postalCode') ?? undefined
        const maxDistance = url.searchParams.get('maxDistance')
        const distanceUnit = url.searchParams.get('distanceUnit') ?? 'km'

        const clients = createApiClients(context)

        const { data: stores } = await clients.shopperStores.searchStores({
            params: {
                query: {
                    postalCode,
                    maxDistance: maxDistance ? Number(maxDistance) : undefined,
                    distanceUnit: distanceUnit as 'mi' | 'km',
                },
            },
        })

        return Response.json({ success: true, stores })
    } catch (error) {
        const { responseMessage, status_code } = await extractResponseError(error as Error)
        return data(
            { success: false, error: responseMessage },
            { status: Number(status_code) }
        )
    }
}
```

### Action Routes (POST/PUT/DELETE)

Use an `action` to handle mutations and form submissions. This example shows a locale-setting endpoint.

```typescript
// src/routes/action.set-locale.ts
import { data, type ActionFunction } from 'react-router'
import { localeCookie } from '@/middlewares/i18next.server'

export const action: ActionFunction = async ({ request }) => {
    const formData = await request.formData()
    const locale = formData.get('locale') as string

    if (!locale) {
        throw new Response('Locale is required', { status: 400 })
    }

    const cookieHeader = await localeCookie.serialize(locale)

    return data(
        { success: true },
        {
            headers: {
                'Set-Cookie': cookieHeader,
            },
        }
    )
}
```

### Dynamic Route Parameters

Use dynamic segments when a family of endpoints shares a common shape.

```typescript
// src/routes/resource.auth.$operation.ts
import type { ActionFunctionArgs } from "react-router";

type AuthHandler = (request: Request, context: ActionFunctionArgs["context"]) => Promise<unknown>;

const authHandlers: Record<string, AuthHandler> = {
  "refresh-token": handleRefreshToken,
  "login-guest": handleLoginGuest,
  "login-registered": handleLoginRegistered,
};

export async function action({ request, params, context }: ActionFunctionArgs) {
  const operation = params.operation as string;

  const handler = authHandlers[operation];
  if (!handler) {
    return Response.json({
      success: false,
      error: `Unknown auth operation: ${operation}`,
    });
  }

  try {
    const result = await handler(request, context);
    return Response.json({ success: true, data: result });
  } catch (error) {
    return Response.json({ success: false, error: "Operation failed" });
  }
}
```

This dynamic segment maps to `/resource/auth/:operation`. For example, `/resource/auth/login-guest`.

### Calling B2C Commerce APIs with `useScapiFetcher`

For standard B2C Commerce operations, use the `useScapiFetcher` hook. This hook pairs with a generic server route so that you can call any SCAPI method from your components while keeping the actual API communication on the server.

You don't interact with the underlying server route directly—the hook handles everything for you.

```typescript
import { useScapiFetcher } from "@/hooks/use-scapi-fetcher";
import { useEffect } from "react";

export function ProductDetails({ productId }: { productId: string }) {
  // The hook expects: (clientName, methodName, options)
  // Options use the SCAPI structure: { params: { path: {...}, query: {...} }, body: {...} }
  const fetcher = useScapiFetcher("shopperProducts", "getProduct", {
    params: {
      path: { productId },
    },
  });

  useEffect(() => {
    fetcher.load();
  }, [productId]);

  if (fetcher.state === "loading") return <div>Loading...</div>;
  if (!fetcher.success) return <div>Error: {fetcher.errors?.join(", ")}</div>;
  if (!fetcher.data) return null;

  return (
    <div>
      <h1>{fetcher.data.name}</h1>
      <span>{fetcher.data.price}</span>
    </div>
  );
}
```

For mutations, use the `submit` method.

```typescript
import { useScapiFetcher } from "@/hooks/use-scapi-fetcher";

export function UpdateProfile({ customerId }: { customerId: string }) {
  const fetcher = useScapiFetcher("shopperCustomers", "updateCustomer", {
    params: {
      path: { customerId },
    },
    body: {},
  });

  const handleSubmit = (formData: FormData) => {
    fetcher.submit(formData);
  };

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        handleSubmit(new FormData(e.currentTarget));
      }}
    >
      <input name="firstName" placeholder="First Name" />
      <input name="lastName" placeholder="Last Name" />
      <button type="submit" disabled={fetcher.state === "submitting"}>
        {fetcher.state === "submitting" ? "Saving..." : "Save"}
      </button>
    </form>
  );
}
```

**note:** While `useScapiFetcher` looks like a direct API call, it serializes your request, sends it to the server route, executes the SDK method on the server, and returns the result. The hook provides these convenience properties: `data` (the response payload), `errors` (any error messages), `success` (a boolean), and `state` (`loading`, `submitting`, or `idle`).

**tip:** Don't `await` the `load()` or `submit()` methods expecting `data` to be populated when the promise resolves. These methods trigger the fetch but return immediately. Use the `state` property or `useEffect` to react to data changes instead.

## Request and Response Patterns

Server routes use standard Web APIs, such as [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request), [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response), and [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData), for handling requests and responses. For detailed patterns, see the [React Router Actions](https://reactrouter.com/start/framework/actions).

## Error Handling

Handle errors gracefully and return appropriate status codes. Don't expose sensitive information in error messages.

```typescript
import type { ActionFunctionArgs } from "react-router";
import { data } from "react-router";
import { extractResponseError } from "@/lib/utils";

export async function action({ request }: ActionFunctionArgs) {
  try {
    const formData = await request.formData();
    const result = await performOperation(formData);

    return Response.json({ success: true, data: result });
  } catch (error) {
    // Use extractResponseError to safely extract error details
    const { responseMessage, status_code } = await extractResponseError(error as Error);

    return data({ success: false, error: responseMessage }, { status: Number(status_code) || 500 });
  }
}
```

**Status Code Guidelines**

| Status | Use Case                                        |
| ------ | ----------------------------------------------- |
| `400`  | Validation errors for missing or invalid input. |
| `401`  | Authentication required.                        |
| `403`  | Authorization denied.                           |
| `404`  | Unknown operations or resources.                |
| `500`  | Unexpected server failures.                     |

## Call Server Routes from UI Code

Use React Router's `useFetcher()` hook to call server routes without triggering a full page navigation. For complete documentation, see [React Router's Data Loading](https://reactrouter.com/start/framework/data-loading#usefetcher).

```typescript
import { useFetcher } from "react-router";

function LocaleSwitcher() {
  const fetcher = useFetcher();

  return (
    <fetcher.Form method="post" action="/action/set-locale">
      <select name="locale">
        <option value="en-US">English</option>
        <option value="fr-FR">Français</option>
      </select>
      <button type="submit">Change Language</button>
    </fetcher.Form>
  );
}
```

**tip:** Don't `await` the `fetcher.load()` or `fetcher.submit()` methods expecting `fetcher.data` to be populated when the promise resolves. These methods trigger the request but return immediately. Use `fetcher.state` or a `useEffect` watching `fetcher.data` to react when data arrives.

## Security Best Practices

Server routes handle sensitive operations. Follow these practices.

### Validate Input

Always validate and sanitize input from requests.

```typescript
export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const email = formData.get("email");

  if (!email || typeof email !== "string") {
    return Response.json({ error: "Valid email address required" }, { status: 400 });
  }

  // Proceed with validated input
}
```

### Keep Secrets Server-Side

Never embed client secrets in browser code. Server routes exist specifically to keep credentials secure.

```typescript
// ✅ Correct: Secret stays on server
export async function action({ context }: ActionFunctionArgs) {
  const clientSecret = process.env.COMMERCE_API_SLAS_SECRET;
  // Use secret in server-side API call
}
```

### Avoid Open Proxies

Use the generic Commerce SDK proxy (`resource.api.client.$resource.ts`) carefully. If you implement similar patterns, enforce an allowlist of methods and validate parameters. Don't expose a "call-anything" proxy without guardrails.

### Set Cache Headers Intentionally

Public endpoints must set appropriate `Cache-Control` headers.

```typescript
return data(
  { products },
  {
    headers: {
      "Cache-Control": "public, max-age=300", // Cache for 5 minutes
    },
  },
);
```

## File Naming Conventions

| File Name                          | Route URL                        | Purpose                        |
| ---------------------------------- | -------------------------------- | ------------------------------ |
| `resource.stores.ts`               | `/resource/stores`               | Store locator BFF endpoint     |
| `resource.auth.$operation.ts`      | `/resource/auth/:operation`      | Authentication operations      |
| `resource.api.client.$resource.ts` | `/resource/api/client/:resource` | Generic Commerce SDK proxy     |
| `action.set-locale.ts`             | `/action/set-locale`             | Set locale cookie server-side  |
| `action.set-currency.ts`           | `/action/set-currency`           | Set currency preference        |
| `action.place-order.ts`            | `/action/place-order`            | Order placement                |
| `loader.wishlist-products.tsx`     | `/loader/wishlist-products`      | Wishlist products data         |
| `oauth2.jwks.ts`                   | `/oauth2/jwks`                   | JWKS proxy endpoint            |
| `_empty.logout.ts`                 | `/logout`                        | Logout endpoint without layout |

## Dependencies

| Package                               | Purpose                              |
| ------------------------------------- | ------------------------------------ |
| `react-router`                        | Framework with loader/action pattern |
| `@salesforce/storefront-next-runtime` | Runtime utilities, SCAPI types       |

## See Also

- [Salesforce B2C Commerce API (SCAPI) Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md)

<!-- document id=7e2efbbcdb73b516ee547d0064f23e2944f4cf8cb6edc13c04db10c70bdd80a3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-server-routes.md -->

# Server Routes Differences with PWA Kit

PWA Kit server routes are typically centralized as Express handlers in SSR server code. Storefront Next replaces that with file-based resource routes and loader/action handlers using standard Web `Request`/`Response` APIs. This distributes server behavior across route modules and aligns API endpoints with routing conventions.

## Key Differences

| Aspect           | PWA Kit                     | Storefront Next                        |
| ---------------- | --------------------------- | -------------------------------------- |
| Pattern          | Express routes in `ssr.js`  | File-based resource routes             |
| Configuration    | Centralized in one file     | Distributed across route files         |
| Request API      | Express `req`/`res` objects | Web Standard `Request`/`Response`      |
| Route Definition | `app.get('/path', handler)` | Export `loader`/`action` from file     |
| Dynamic Routes   | Express params (`/:param`)  | File naming (`$param`)                 |
| Middleware       | Express middleware chain    | React Router middleware exports        |
| Client Execution | Server only                 | Optional `clientLoader`/`clientAction` |

## PWA Kit Express Routes

```javascript
// Single file: app/ssr.js
app.get("/api/search", async (req, res) => {
  const query = req.query.q;
  const results = await searchProducts(query);
  res.json(results);
});

app.post("/api/auth/login", async (req, res) => {
  const { email, password } = req.body;
  const session = await login(email, password);
  res.json(session);
});
```

## Storefront Next Resource Routes

```typescript
// src/routes/resource.search.ts
export function loader({ request }: LoaderFunctionArgs) {
  const url = new URL(request.url);
  const query = url.searchParams.get("q");
  const results = await searchProducts(query);
  return Response.json(results);
}

// src/routes/resource.auth.login.ts
export async function action({ request }: ActionFunctionArgs) {
  const { email, password } = await request.json();
  const session = await login(email, password);
  return Response.json(session);
}
```

## Key Similarities

- Both support GET (loaders) and POST/PUT/DELETE (actions).
- Both can set cache headers and response status codes.
- Both integrate with SLAS for authentication callbacks.
- Both can proxy Commerce API calls.
- Both support dynamic route parameters.

## Storefront Conversion Considerations

Keep these tips in mind when you convert your PWA Kit storefront to Storefront Next.

- Route extraction: Move logic from `ssr.js` callbacks into separate route files.
- Request handling: Convert Express `req.body`/`req.query` to `request.json()`/`URL.searchParams`.
- Response handling: Convert `res.json()` to `Response.json()`.
- Middleware: Use React Router middleware exports instead of Express middleware.
- Client-side option: Consider adding `clientLoader` for endpoints that can run on the client.

<!-- document id=e6c7f8c01e599ba50fdfe3d25e99341ddebf16147b251dcdb93babd1baca95a2 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-rendering.md -->

# Server-Side Rendering (SSR) Differences with PWA Kit

PWA Kit and Storefront Next implement SSR, but with fundamentally different architectures that reflect their respective technology stacks. PWA Kit's SSR approach gives developers explicit control through Express and React Query, with optional partial hydration via Islands. Storefront Next uses React Router 7's built-in SSR with automatic streaming, middleware chains, and loader-based data fetching. Storefront Next's approach reduces boilerplate and provides better streaming performance, while the PWA Kit approach offers more granular control over hydration timing.

## Key Differences

| Aspect            | PWA Kit                              | Storefront Next                       |
| ----------------- | ------------------------------------ | ------------------------------------- |
| SSR Runtime       | Express server with `runtime.render` | React Router 7 framework mode         |
| Data Hydration    | React Query cache serialization      | Promise streaming with `use()` hook   |
| Middleware        | Express middleware                   | React Router middleware chain         |
| Partial Hydration | `Island` component with strategies   | Suspense boundaries with `createPage` |
| Server Context    | `useServerContext()` hook            | Context from middleware chain         |
| Code Splitting    | `@loadable/component`                | React Router's automatic splitting    |
| Cache Control     | Manual via `res.set()`               | Via HTTP response from middleware     |

## Data Flow Comparison

PWA Kit:

1. Express receives request.
2. React tree renders.
3. React Query hooks execute during render.
4. Data fetched, components re-render with data.
5. Query cache serialized to HTML.
6. Client hydrates with cached data.

Storefront Next:

1. React Router receives request.
2. Middleware chain runs (auth, config, i18n).
3. Loaders execute, return promises.
4. React renders, `use()` unwraps promises.
5. HTML streams as promises resolve.
6. Client hydrates, clientLoader runs.

## Hydration Approaches

**PWA Kit** offers fine-grained control with `Island`:

```javascript
<Island hydrateOn="visible">
  <Footer />
</Island>
```

**Storefront Next** uses Suspense boundaries:

```typescript
export default createPage({
  component: ProductDetail,
  fallback: <ProductSkeleton />,
});
```

## Storefront Conversion Considerations

1. useServerContext vs. Middleware: Server-side logic like setting cache headers moves from component hooks to middleware or loaders.

2. React Query vs. Loaders: Data fetching moves from hooks inside components to loader functions exported from route files.

3. Island vs. Suspense: Partial hydration with Island becomes Suspense boundaries with `createPage`.

4. Express routes vs. Resource routes: Custom API endpoints move from Express handlers to React Router resource routes.

<!-- document id=e3832b3dff44effbcd87ec22e0850c9703912d7aefc9ea3b3c9ab002e967178f url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-session-bridge-auth.md -->

# Session Bridge Authorization

If you have an existing B2C Commerce session from a Storefront Reference Architecture or Site Genesis storefront and you want to get an access token for it, use the [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getSessionBridgeAccessToken) endpoint.

This can be helpful when building out hybrid storefronts where different technologies are used to power a single shopping experience.

## Prerequisites

- You have configured a SLAS client with the `sfcc.session_bridge` scope.
- For a guest shopper, you have the `dwsgst` value.
- For a registered shopper, you have the `dwsid` value and `login_id`.

The process for getting tokens for sessions is different for guest and registered users. The following call examples use a SLAS private client.

## Session Bridge Guest Shoppers

To bridge a guest session you need a signed guest token from the Script API method [`Session.generateGuestSessionSignature()`](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/api/class_dw_system_Session.html#dw_system_Session_generateGuestSessionSignature_DetailAnchor). You must set `login_id` to “guest”:

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/session-bridge/token" \
  --user "$CLIENT:$SECRET" \
  --data 'grant_type=client_credentials' \
  --data 'hint=sb-guest' \
  --data 'login_id=guest' \
  --data "channel_id=$SITE" \
  --data "dwsgst=$DWSGST"
```

## Session Bridge Registered Shoppers

To bridge a registered shopper session you need a signed, registered token (DWSRST) from the Script API method [`Session.generateRegisteredSessionSignature()`](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/scriptapi/html/api/class_dw_system_Session.html#dw_system_Session_generateRegisteredSessionSignature_DetailAnchor). You must set `login_id` to the login ID of the registered shopper.

**note:** - The use of DWSID is still supported, but for performance reasons, use the DWSRST instead of passing in the DWSID.
- In the future, DWSID for registered shopper session bridging will be deprecated.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/session-bridge/token" \
    --user "$CLIENT:$SECRET" \
    --data 'grant_type=client_credentials' \
    --data 'hint=sb-user' \
    --data "login_id=$SHOPPER" \
    --data "channel_id=$SITE" \
    --data "dwsrst=$DWSRST"
```

The following code sample shows the legacy `dwsid` token. Use `dwsrst` as shown in the previous example.

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/session-bridge/token" \
    --user "$CLIENT:$SECRET" \
    --data 'grant_type=client_credentials' \
    --data 'hint=sb-user' \
    --data "login_id=$SHOPPER" \
    --data "channel_id=$SITE" \
    --data "dwsid=$DWSID"
```

<!-- document id=afa906158c7d282b9b8afa52a343a5f04707a606335096ae6fa1d2ecdcedcef5 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-session-bridge-overview.md -->

# Session Bridging Overview

Clients can interact with the B2C Commerce platform using controllers, HTTP APIs, or both. Controllers and APIs use different authentication and authorization (authnz) methods, which means you must “bridge” the different authnz methods in hybrid implementations to keep them in sync for shopper login, logout, and other shopper-related events.

This topic provides an approach for “session bridging” using a hybrid SCAPI/OCAPI and B2C Commerce controller implementation. You can use this approach as a guide when working with PWA Kit or any other headless Backend for Frontend (BFF). For additional session bridging instructions that apply when using a hybrid implementation (SiteGenesis/SFRA and PWA Kit), see [Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html#2-session-bridging). In our case, session bridging involves synchronizing a SLAS JWT (for SCAPI) with a session `dwsid` (for B2C Commerce controllers), or vice versa. At any time, the browser must be able to make a request to either the controller or an API and be recognized as the same shopper.

Note: SLAS tokens can be used with all SCAPI and OCAPI Shopper APIs, but using SCAPI is preferred.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## SCAPI and Controller Authnz Overview

This section outlines the authnz methods for a headless implementation using PWA Kit and hybrid authentication (Hybrid Auth), providing a guide for other headless implementations.

**note:** As of B2C Commerce 25.3, Hybrid Auth is the functional equivalent and replacement for Plugin SLAS.

PWA Kit uses SCAPI for authnz, while B2C Commerce controllers use Hybrid Auth. For details, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-authentication.md) and
[Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html).

Make sure you:

- Understand the authnz methods of whatever components you include in your headless implementation.
- Minimize the use of session bridging (POST sessions and POST customers/auth). Only create a session if necessary and reuse existing sessions for as long as possible.
- For optimal performance, apply the same approach to JWT creation for SCAPI/OCAPI calls.

Summary of SCAPI and B2C Commerce controller authnz mechanisms:

| **Client Access** | **Access Method**                                                                                                                                                  | **Expiry Time**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | **Refresh Token**                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| SCAPI             | Retrieve SLAS access tokens (in the form of a JWT):                                                                                                                | JWT access tokens are valid for 30 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | For up to 90 days, you can use the refresh token provided by SLAS to get a new access token. |
| Controllers       | Use sessions that are identified by HTTP cookies prefixed with `dw`. The `dwsid` cookie contains your Session ID and is used by the server to locate your session. | <ul style="font-size: var(--table-cell-text-base); margin-left: 0px;"><li>Sessions are valid for 30 minutes and are automatically extended by 30 minutes when a request is made to a controller during the session. After 30 minutes without a request, the session expires.</li><li>Important: If you make a request after a session expires, a new session is initiated. No error is returned.</li><li>Sessions can be extended for up to six hours, and you can configure the six-hour [session timeout](https://help.salesforce.com/s/articleView?id=cc.b2c_login_settings.htm&type=5) value in Business Manager by navigating to **Administrator** > **Sites** > **Manage Sites** > **Site** > **Settings** > **Session Timeout**</li></ul> | N/A                                                                                          |

**note:** Basket lifetime is different from session lifetime and configured separately. To learn more see [Configure Basket Preferences](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_basket_preferences.htm&language=en_US&type=5).

## Events That Require Session Bridging

You must perform session bridging for various lifecycle events, for example: when a shopper first lands on a storefront, when a shopper subsequently logs in or out, and when tokens or sessions expire.

The call flows that are detailed in the following sections are the flows that PWA Kit and Hybrid Auth (the functional equivalent and replacement for Plugin SLAS) use. The purpose of these flows is to obtain a JWT (SLAS access token) and a `dwsid` (session) that reference the same shopper, so that subsequent requests are in sync, regardless of whether those requests come from an API or a controller.

### Session Bridging for New Shoppers

These flows are for new shoppers who have never before visited your storefront. The series of calls you must make depends on whether a shopper first lands on a headless/PWA site or the B2C Commerce (SFRA) site.

**note:** You can choose to store the refresh token in different ways, including persisting the SLAS JWT and refresh token on your BFF or, alternatively, sending them back to the client. For all flows discussed in our approach, it is assumed that the SLAS refresh token that is associated with the shopper is stored in a cookie that is accessible both from the server and from JavaScript.

#### Shopper First Lands on the Headless Site (PWA Kit)

In our case, we are using PWA Kit, but the following guidance applies to any BFF:

1. Get a JWT From SLAS. Depending on whether you’re using a public or private client, the flow varies. If you use a SLAS private client, you only need to call `getAccessToken`.
   1. Call SLAS[`authorizeCustomer`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer) (`oauth2/authorize)`
   2. Call SLAS[`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken) (`oauth2/token`)
2. You now have a SLAS token, which includes a JWT that you can use to access the APIs, and a refresh token you can use to get a new JWT.
3. Call OCAPI Shop[`/sessions`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-sessions?meta=Exchange%2BJWT)_`.`_
4. You now have a cookie with a `dwsid` that is associated with your JWT.

With a SLAS access token and a Session ID, you can make requests using either APIs or controllers.

The following image shows the request flow for new shoppers landing on a headless site:

![New shopper basket creation in headless implementation](https://developer.salesforce.com/docs/media/commerce-api/shopper-new-headless.png)

#### Shopper First Lands on B2C Commerce (SFRA)

In this flow, the browser makes a request to B2C Commerce, which automatically creates a session and returns a `dwsid` for any request that meets the following criteria:

- Doesn’t contain a DWSID cookie.
- The session referenced by the cookie is expired or otherwise invalid.

Use [Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-authentication.md), which is the functional equivalent and replacement for Plugin SLAS, or manually perform the following steps:

1. Get a JWT From SLAS. Depending on whether you’re using a public or private client, the flow varies. If you use a SLAS private client, you only need the token call, not the authorize call.
   1. Call SLAS[`authorizeCustomer`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer) (`oauth2/authorize)`
   2. Call SLAS[`getSessionBridgeAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getSessionBridgeAccessToken) (`oauth2/session-bridge/token`)
2. You now have a SLAS token, which includes a JWT that you can use to access the APIs, and a refresh token you can use to get a new JWT.

The following image shows the request flow for new shoppers landing on a B2C Commerce site:

![New shopper basket creation process in B2C Commerce](https://developer.salesforce.com/docs/media/commerce-api/shopper-new-b2c.png)

### Session Bridging for Returning Shoppers

Returning guest and returning registered shopper flows are the same, but the sequence of calls depends on whether the shopper first landed on the headless storefront or B2C Commerce.

#### Returning Shopper on the Headless Site (PWA Kit)

1. Use the SLAS refresh token to call SLAS[`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken) (`oauth2/token?refresh_token=...`)
2. Call OCAPI Shop[`/sessions`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-sessions?meta=Exchange%2BJWT) to get new DW cookies for the shopper.
   1. Now you've got both an access token and a session to call APIs or controllers. The returning shopper is now logged in again.

The following image shows the request flow for the returning shopper on the headless site:

![Returning shopper basket retrieval in headless implementation](https://developer.salesforce.com/docs/media/commerce-api/shopper-return-headless.png)

#### Returning Shopper on B2C Commerce (SFRA)

If your browser doesn’t have a `dwsid` in its cookie jar to send, or the `dwsid` that you send is invalid or expired (maximum session life is six hours), then you will get a new session when the request is made to B2C Commerce and you must perform session bridging.\* \*
Use [Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-authentication.md), which is the functional equivalent and replacement for Plugin SLAS, or manually perform the following steps:

1. Use the refresh token to call SLAS[`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken) (`oauth2/token?refresh_token=...`)
2. Call OCAPI Shop[`/sessions`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-sessions?meta=Exchange%2BJWT) to get new DW cookies for the shopper.
3. Reload the page. This forces the page to be rendered using the newly acquired session.

The following image shows the request flow for a returning shopper on B2C Commerce:

![Returning shopper basket retrieval process in B2C Commerce](https://developer.salesforce.com/docs/media/commerce-api/shopper-return-b2c.png)

### Shopper Login

If a guest shopper logs in, the sequence of calls you need to make depends on whether the shopper logs in to the headless storefront or B2C Commerce.

If the guest shopper logs in to the headless storefront:

1. Provide the user's credentials to login with [oauth2/authorize](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer). At that point, you'll have a JWT for the logged in shopper.
2. Whatever `dwsid` you currently have references the guest session, which means it is stale.
   1. Call OCAPI Shop[`/sessions`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-sessions?meta=Exchange%2BJWT) with the logged in JWT to retrieve a `dwsid` for the logged-in shopper.

If the guest shopper logs in to B2C Commerce (SFRA):

1. Provide the user's credentials to login with [oauth2/authorize](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer). At that point, you'll have a JWT for the logged in shopper.
2. Call OCAPI Shop[`/sessions`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-sessions?meta=Exchange%2BJWT) with the logged in JWT to retrieve a `dwsid` for the logged-in shopper.
3. Return a redirect to the shopper so the page is re-rendered with the updated session.

### Shopper Logout

When a shopper logs out of your storefront, the sequence of calls you need to make depends on whether the shopper logs out of the headless storefront or B2C Commerce.

If the shopper logs out of the headless storefront:

1. Discard the current JWT and refresh token. You can log the customer out using the [loguoutCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=logoutCustomer) endpoint.
2. Obtain a new guest JWT using[`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken)_`.`_
3. Call OCAPI Shop[`/sessions`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-sessions?meta=Exchange%2BJWT)_._

If the shopper logs out of B2C Commerce (SFRA):

1. The existing session is automatically cleared.
2. However, the JWT still is logged in. Obtain a new guest JWT using[`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken)_`.`_

### SLAS Access Token Timeout

SLAS access tokens are good for 30 minutes from the time they are granted. You can decode the JWT and look at the `exp` field for the exact timestamp.

After 30 minutes elapses, the token can no longer be used to make an API request. If you make a request with an expired JWT, an error is thrown.

1. Use the refresh token to call SLAS[`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken) (`oauth2/token?grant_type=refresh_token`) to get a new token.
   1. Note: Refresh tokens from public clients can only be redeemed once, while refresh tokens from private clients can be used for multiple days.
   2. For `prd` instances, refresh tokens are good for 90 days. For other instances, refresh tokens are good for nine days. The exact value can be found in [_TokenResponse_](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=type%3ATokenResponse)'s refresh_token_expires_in property.

### B2C Commerce Session Timeout

- When the session expires due to a timeout, the next call to B2C Commerce results in the OnSession hook firing, so this will be the same as the returning visitor scenario.
- For details on returning shopper behavior in SFRA, see the [SLAS Session Bridge Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-session-bridge-auth.md) guide.

<!-- document id=807ad11a22a6d99fd822516d72925edc893eb33d49ec6e15cc7de5b63e5f6cd6 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/base-paths.md -->

# Set an Environment Base Path to Route Requests to an MRT Environment

If your store domain is backed by multiple Managed Runtime environments (MRT) and uses a single domain, use environment base paths to route requests to the correct environment. Set an environment base path for each environment to route requests via a CDN. Also, use an environment base path to host the storefront within a specific subpath.

The bundle assets and proxies of a single Managed Runtime environment, as well as the PWA Kit local developer environment, are placed at the root level.

For example, your environment could have its bundle assets accessed at `https://pwa-kit.mobify-storefront.com/mobify/bundle/...` and its proxies at `https://pwa-kit.mobify-storefront.com/mobify/proxy/...`.

If you were to place a domain `www.example.com` in front of the above environment, your bundle and proxy URLs will become `www.example.com/mobify/bundle/...` and `www.example.com/mobify/proxy/...`.

But what if you wanted to have multiple environments under `www.example.com`? Or what if you wanted to place the PWA in a subpath under your domain, such as `www.example.com/shop`?

This guide explains how you can set up these scenarios by setting an environment base path.

## Prerequisites

- PWA Kit release version 3.17.1 or later.
- The corresponding commerce-sdk-react 5.1.1 and retail-react-app 9.1.1.
- Your setup must have a CDN, such as eCDN, in front of your Managed Runtime Environment.

## Before You Begin

This guide covers how to set an environment base path.

The environment base path is applied to URLs needed for the app to function, such as:

- **`/mobify/...` URLs** — This includes `/mobify/bundle/...`, `/mobify/proxy/...`, and so on.
- **`/callback` URLs** — This includes SLAS callback URLs used for password reset, and so on.
- **Express routes** — This includes `/worker.js` and any custom express endpoints defined inside `ssr.js`.

Be aware that these endpoints are e-commerce site and locale agnostic. These URLs serve the same resource regardless of the base path.

By default, the environment base path isn’t added to app URLs that are defined with React Router. These URLs, which correspond to pages and routes defined in `route.jsx`, can have the environment base path added by setting `showBasePath` to `true` in your PWA Kit config file.

```javascript
url: {
    site: 'path',
    locale: 'path',
    showDefaults: true,
    showBasePath: true,
    interpretPlusSignAsSpace: false
},
```

## Initial Configuration

You can set an environment base path by setting the `envBasePath` property inside the `ssrParameters` section of your PWA configuration file.

This example `config/default.js` file, sets the environment base path to `'/test'`.

```javascript
ssrParameters: {
    ssrFunctionNodeVersion: '24.x',
    envBasePath: '/test',
    proxyConfigs: [
        {
            host: 'kv7kzm78.api.commercecloud.salesforce.com',
            path: 'api'
        },
        {
            host: 'zzrf-001.dx.commercecloud.salesforce.com',
            path: 'ocapi'
        }
    ]
}
```

After you set the base path, start the local app and observe that your `/mobify` and express routes now include `envBasePath` in the URL.

If you set `showBasePath` to `true`, observe that your page URLs now include `envBasePath` after your domain.

### App Changes

Add the `envBasePath` property to all custom outbound `/mobify` and express routes in your app.

Make sure you test your app. If you notice any express URLs where the base path should be added, update the URL to include the environment base path via `getEnvBasePath()`.

You can import `getEnvBasePath()` using this import:

```js
import {getEnvBasePath} from '@salesforce/pwa-kit-runtime/utils/ssr-namespace-paths'
```

For example, this is how `getEnvBasePath()` is used inside the `_app-config.jsx` file:

```js
import {
   getEnvBasePath,
   slasPrivateProxyPath
} from '@salesforce/pwa-kit-runtime/utils/ssr-namespace-paths'

...

// Set absolute uris for CommerceApiProvider proxies and callbacks
const redirectURI = `${appOrigin}${getEnvBasePath()}/callback`
const proxy = `${appOrigin}${getEnvBasePath()}${commerceApiConfig.proxyPath}`
const slasPrivateClientProxyEndpoint = `${appOrigin}${getEnvBasePath()}${slasPrivateProxyPath}`
const passwordlessLoginCallbackURI = isAbsoluteURL(passwordlessCallback)
    ? passwordlessCallback
    : `${appOrigin}${getEnvBasePath()}${passwordlessCallback}`

return (
    <CommerceApiProvider
        proxy={proxy}
        redirectURI={redirectURI}
        passwordlessLoginCallbackURI={passwordlessLoginCallbackURI}
        slasPrivateClientProxyEndpoint={slasPrivateClientProxyEndpoint}
        . . .
```

## Set an Environment Base Path to Your Remote Environment

You must update several systems to set an environment base path for your remote Managed Runtime environment.

### SLAS Configuration

SLAS clients use two fields, `redirect_uri` and `callback_url`, that receive requests as part of the login process. The URLs you set in these fields must include the base paths of your environments.

For example, if you have two environments with base paths of `/shop` and `/store` and your domain is `www.example.com`, your SLAS `redirect_uri` should be set to:

`www.example.com/shop/callback | www.example.com/store/callback`

### CDN Configuration

#### Origin Routing Rules

Set up origin rules to route your domain and paths to the underlying Managed Runtime environments serving your site.

For example, you have two different environments that can be accessed at `www.example.com/mrt-env-1` and `www.example.com/mrt-env-2`. 
In this example, `envBasePath` for `mrt-env-1` is `/mrt-env-1` and similarly `envBasePath` for `mrt-env-2` is `/mrt-env-2`.

Your origin rule can look as follows:

![Origin routing rule](https://developer.salesforce.com/docs/media/pwa-kit-managed-runtime/env-path-origin-rule2.png '{"class": "image-xl"}')

In the preceding image, the target MRT origin is the MRT hostname you're targeting with the base path.

### PWA and MRT Configuration

On bundle upload (`npm run push`), the push command passes along the properties set in your `config/default.js` `ssrParameters` to MRT as part of the bundle’s upload properties.

To set a base path for another MRT environment, update the `envBasePath` property in your `config/default.js` and upload another bundle.

To help keep track of which base path is set with the bundle upload, consider including the base path in the upload message:

```bash
npm run push -- -s your-MRT-project --target your-target-environment --message "Bundle with base path /shop"
```

For repeat deployments, consider creating a continuous integration (CI) job or script that sets the correct base path for each target environment.

Once the bundle is deployed onto MRT, view your store and verify that the base path is set in calls to `/mobify` paths.

## URL Redirects

When a base path is set on an environment, MRT redirects are affected in these ways.

**Redirect From**

No change. MRT automatically appends the base path.

If you have an existing redirect-from, it continues to work as-is.

**Redirect To**

MRT doesn’t automatically append the base path, because absolute URLs or external domains are valid targets.

If you modify the base path, review your redirect-to targets to ensure the targets are what you expect.

## Storefront Preview

Storefront Preview is compatible with base paths. However, Storefront Preview operates on a per-environment basis. Keep these considerations in mind.

- When you preview a store on Runtime Admin, the domain that's used by Storefront Preview is the environment host name that's set in MRT, not your external-facing domain.
- Storefront Preview can’t switch targets to a bundle running on a different environment. If you're using Storefront Preview on environment A with base path `/store-a`, you can’t switch to environment B with base path `/store-b` via URL. Open a separate Storefront Preview instance targeting environment B’s MRT host name.

## Best Practices

- Try to avoid overlaps among your environment base path, site ID, and locale. While `www.example.com/us/us/us/...` can work, it may cause confusion about which URI segment corresponds to which property.
- When defining custom express endpoints, don’t set your endpoint’s first URI part to be equivalent to the base path. For example, `app.get('/:basePath/:otherParam/test')` isn’t ideal, because the duplication can cause confusion.

<!-- document id=b14eb5e450ad5354dae88b414e08ffdc07ca812e4050a246f32e798620621b87 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-setting-permissions-for-csc.md -->

# Set Permissions

## Set Permissions to Create an Order

An agent can create an order in Customer Service Center. The agent needs the necessary permissions.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Organization** > **Roles** > **Permissions** role.
2.  Click **Business Manager**.
3.  Select your site.
4.  Set the following permissions:

    - Orders
    - Customer Service Center

5.  Click **Functional Permissions**.
6.  Select your site.
7.  Enable the following permissions:

    - Adjust_Item_Price
    - Adjust_Shipping_Price
    - Adjust_Order_Price
    - Delete_Order_Note
    - Create_Order_On_Behalf_Of
    - Search_Orders

8.  Click **Locale Permissions**.
9.  Check locales to enable them, uncheck to disable them for this role.
10. Click **Apply**.

## Set Permissions to 'Browse On Behalf Of' in the Storefront

Assign 'Browse On Behalf Of' permission so your agent can use the Storefront to create an order on behalf of the customer.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Organization** > **Roles & Permissions** > \*\*\*\* role.

2.  Click **Business Manager Modules**.

3.  Select your site.

4.  Enable the following permissions:

    - Orders
    - Customer Service Center

5.  Click **Functional Permissions**.

6.  Select your site.

7.  Enable the Login_On_Behalf permission.

8.  Click the **Locale Permissions** tab.

9.  Check locales to enable them, uncheck to disable them for this role.

10. Click **Apply**.

<!-- document id=20ab67dfcc49790cfd1ada1f7422a641cb4903eb084839753e6909eafd57af2b url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/setting-up-api-access.md -->

# Set Up API Access

Enable your PWA Kit storefront to securely access data from Shopper APIs, including products, baskets, orders, and more. The technology that authorizes this API access is called the **Shopper Login and API Access Service (SLAS)**, which is part of the Salesforce B2C Commerce API. In addition to authorizing API requests to the B2C Commerce API, SLAS also authorizes API requests to the Open Commerce API (OCAPI).

**note:** The setup process has recently been streamlined thanks to the new SLAS Admin UI.

## Before You Begin

Complete the instructions in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md) in the B2C Commerce API documentation to create a SLAS client. We encourage you to use a SLAS private client but depending on your use case, you could opt to use a SLAS public client instead.

If you’re planning to do a [phased rollout](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html) of a PWA Kit experience, make sure to follow the instructions in the [Extra Steps for Phased Rollouts of PWA Kit](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md#extra-steps-for-phased-rollouts-of-pwa-kit) section of the guide.

After creating a SLAS client, return to this guide and read on.

## Set the Client Secret

If you are using a SLAS private client, you must set the client secret via an [environment variable](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md#set-environment-variables).

**note:** Projects generated from PWA Kit 3.5 and above will be configured to use a SLAS private client by default.

To learn more about using SLAS private clients, see [Using A Slas Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md).

If you are using a SLAS public client, skip this section and continue with updating your OCAPI settings as described in the next section.

## Update Open Commerce API Settings

For certain features, your PWA Kit storefront must make requests to the Open Commerce API (OCAPI) on your B2C Commerce instance.

Here’s how to update your OCAPI settings for PWA Kit:

1.  Log in to Business Manager on your B2C Commerce instance.
2.  Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Open Commerce API Settings**.
3.  Copy this JSON:

```json
{
  "_v": "21.3",
  "clients": [
    {
      "client_id": "PLACEHOLDER_CLIENT_ID",
      "resources": [
        {
          "resource_id": "/sessions",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}
```

4.  Go back to Business Manager and paste the JSON into the field.
5.  Replace the placeholder value for `PLACEHOLDER_CLIENT_ID` with the client ID for the public SLAS client that you created using the SLAS Admin UI.
6.  Scroll down to the bottom of the page.
7.  Click **Save**.

Repeat these instructions for each B2C Commerce instance that is used with PWA Kit.

## See Also

- [Build and Customize](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/build-customize.md)

<!-- document id=ec01cdad0199a5c2d95249fa1f8e7a2299c89510621d2aa4dba31733738694f9 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/callback-url-for-payment-gateway-integrations.md -->

# Set Up Callback URL for Payment Gateway Integrations

A callback URL is an address that a server provides for receiving POST requests. Point of Sale generates a callback URL as part of the payment gateway configuration. When you use Adyen, you must configure a callback URL so Point of Sale can receive payment event notifications, such as payment failures. Without it, Point of Sale can’t update order status or handle failed payments. Set up the callback URL at the correct company or organization level in Adyen. If you configure it at the wrong level, Adyen can send callbacks for unrelated web orders, creating unnecessary bloat in failed order records.

For Point of Sale to receive Adyen callbacks related to payment failures, a callback URL is needed. This is similarly used in the case of HiPay for pay by link. Part of the configuration process requires a callback URL generated by Point of Sale. This article explains how to generate a callback URL and use it for Adyen and HiPay.

## Generate the Callback URL

1.  In the CMS, go to **Integrations** | **Payment Gateways.**

2.  Create a new integration by clicking **Create**.

3.  For Payment Gateway, select an integration to configure.

4.  For Callback URL, click **Generate**.

5.  Copy the URL and configure it in the selected integration portal.

### Adyen

The callback URL is configured in the Adyen Portal at the appropriate Company or Merchant account level. The callback URL can't be configured at both the Company and Merchant level. For more information on integrating Adyen, refer to [Adyen Payment Gateway Integration](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_hardware_ayden_gateway_info.htm) in _Salesforce Help_.

#### Recommended Account Setup

Configure the callback URL in Adyen at the Point of Sale merchant-region level. Each region requires a unique payment gateway setup with its own callback URL. For example, a DE region callback URL should be linked only to the DE Adyen account. Ideally, each Point of Sale merchant account maps 1:1 with an Adyen merchant account for a cleaner integration and accurate reporting.

Point of Sale also supports mapping multiple merchant accounts to one Adyen account if each uses a distinct order number range and Adyen is configured with multiple webhooks. However, this setup can cause false positives in the Failed Order report because all Point of Sale environments receive every webhook. Consult your Adyen representative to confirm the best configuration for your setup.

#### Pay by Link (PBL)

To facilitate in-store payments via PBL and for brands operating under a parent company, set up callback URLs or webhooks at the parent company level for each child branch. This consolidates all payments made across the child brands at the company level as each instance has one callback URL in CMS.

### HiPay

Similar to Adyen, in the case of HiPay, callback URLs are used for pay by link integration.

For more information, refer to [Set Up HiPay Hosted Page Payments](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_3p_int_finance_hipay.htm&type=5) in _Salesforce Help_.

<!-- document id=86d31db71b211f41549e849968d6752a9e78d492fc891938f03fd2f6ce79537f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-payment-clientside-container.md -->

# Set Up Client-Side Payment Processing

A client-side payment processing integration requires that your checkout UI component communicate directly with the payment provider server. The Salesforce server isn’t involved in the payment authorization, but is subsequently notified about the client-side payment transaction. Client-side is a typical integration pattern when adapting payment providers’ prebuilt UI components or building custom checkout UI components.

<!-- document id=922d28093263152b57ce5bd8012bf7dff72ce596ef11e32e03b363a283ee7d75 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-set-up-guest-checkout-headless.md -->

# Set Up Guest Checkout for Headless Commerce Stores

Setting up guest checkout for headless implementations requires enabling guest store access and, to track guest carts, modifications to checkout processing. Both server- and client-side payment processing support guest checkout for headless Commerce stores.

## Set Up Guest Access to Headless Commerce Stores

From the Commerce app, declaratively perform tasks to let unauthenticated customers browse your store, discover products, and make purchases. Guest access is optional for B2B stores.

Using your store’s Commerce app, you:

- Grant guest access to the store site and to its media, content, and related objects including public APIs.
- Create a guest buyer profile and turn on cart and checkout access for the profile.
- Configure carts to preserve items added by a guest when the guest then logs in as an authenticated user.
- Configure sharing and security fields for product-related fields to let guests search your catalogs.
- Rebuild the search engine to include products that guest customers are entitled to discover. To set up guest access to your store, see [Enable Guest Access to a Store](https://help.salesforce.com/s/articleView?id=commerce.comm_config_guest_browsing.htm).

## Set Up Guest Authorization and Cart Tracking for Headless Commerce Stores

Establish guest authorization by setting and passing cookies. Enable guest carts by appending a runtime URL to cart and checkout API requests. Use a Postman Collection to set up and test both.
Store access for registered buyers uses authorization headers. By contrast, authorizing store access for guest shoppers requires sending the following cookies with cart-related requests:

- `guest_uuid_essential_{siteId}` - generated by the client as a unique guest cart identifier where `siteId` is the 15-digit ID for the site associated with the webstore. When creating a guest cart, the client sets the cookie value to a Version 4 UUID that is adequately randomized for each guest shopper. This same cookie is set on every subsequent call associated with that guest cart. Here’s a sample cookie value:

  ```
  Cookie: guest_uuid_essential_0DMSM0000000hD6=66fdbefd-b9b0-4bb9-9765-ed3c50048d16
  ```

- `GuestCartSessionId_{sessionId}` - generated by the server where `sessionId` is a unique cookie value. When a cart is created, the server returns `GuestCartSessionId_{sessionId}` through the set-cookie response header. The create cart call captures this cookie, which is then set every time a call is made involving that guest shopper’s cart right through checkout. For example, if the response header in the create cart API call is:  
   then for each request this cookie is set on all subsequent calls. For example:

  ```
  Cookie: GuestCartSessionId_0ZESM0000004cGY=da6370a8-7efd-4e32-b9f0-2c97d32f8ad0
  ```

When using these cookies to authorize guest shoppers, a different (web runtime) API URL is required for cart and checkout API calls. Appending the web runtime URL allows access to the protected endpoints needed for headless checkout (create cart, add item to cart, create checkout). On such API calls, you append the web runtime/API to the store URL. For example:

```
https://example.my.site.com/mystore/webruntime/api/services/data/v59.0/commerce/webstores/0ZESM0000004cGY4AY/checkouts
```

**note:** Salesforce Commerce supports multiple international countries, designated as Markets, to target customers. Markets encompass the locales where shoppers access the storefront. For unregistered customers, Salesforce Commerce determines the locale by the guest shopper’s location and the Experience User context. With headless APIs, you can also target customers by passing additional parameters to the corresponding Connect APIs using the `language=<locale>` key value pair.

<!-- document id=1fab90a94dd54bb0ebd6d0a527cfe782e00d9beadbb7846c14864245d66b19eb url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-hybrid-proxy-local-dev.md -->

# Set Up Hybrid Proxy Locally in Secondary Instance Group (SIG) Environments

**Applies to: Storefront Next**

Use the hybrid proxy Vite plugin to run Storefront Next and SFRA/SiteGenesis side by side at one origin during local development when connected to an on-demand sandbox. The steps in this documentation apply primarily to local development. At the end of this setup, you can navigate between Storefront Next and SFRA/SiteGenesis pages at `http://localhost:5173` without visible redirects.

**warning:** Hybrid proxy is for local development with a sandbox (ODS) only. It works only with `pnpm dev` and must not run in production.

For Managed Runtime (MRT) and production deployments, use Cloudflare eCDN origin routing between Storefront Next and SFRA/SiteGenesis.

## Hybrid Proxy Features

### Side-by-Side Local Development

Run Storefront Next and SFRA/SiteGenesis simultaneously at a single origin (`localhost:5173`) with no visible redirects or session loss. Navigate freely between Storefront Next pages and SFRA/SiteGenesis pages as if they were one unified storefront.

### Parity with eCDN Routing Rules

Routing decisions use the same Cloudflare eCDN expression format (`http.request.uri.path matches`) as your production configuration. Copy your `HYBRID_ROUTING_RULES` value from your eCDN origin rules, or keep it in sync with them, so local development routing matches production.

### Configuration Flexibility

No assumptions are made about which pages live on Storefront Next versus SFRA/SiteGenesis. You define the split entirely through `HYBRID_ROUTING_RULES`. Any combination of migrated and legacy pages is valid; include only the routes you've built in Storefront Next.

### Feature Flag Safeguard

A dedicated `HYBRID_PROXY_ENABLED` flag controls the proxy. It defaults to `false`, so the proxy doesn't activate unless you explicitly turn it on. The plugin is also guarded by a `mode === 'development'` check in `vite.config.ts`, so the proxy doesn't run in a production build.

## Before You Begin

Make sure that:

- You run your storefront with `pnpm dev`.
- You have access to an B2C Commerce sandbox that runs SFRA/SiteGenesis.
- You have the required storefront environment variables.
- You complete "Configure Business Manager" in [Shared Hybrid Auth Setup, Step 4](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-4-configure-business-manager). Those Business Manager settings are also required when using the hybrid proxy.

## Configure the Hybrid Proxy

### Step 1: Configure the Application (All Environments)

These application and routing settings must be present in your `.env` for local development, and in your MRT environment variables for staging and production. The hybrid proxy plugin itself is enabled only for local development (Step 2).

1. Copy the environment template if you haven't already done so.

   ```bash
   cp .env.default .env
   ```

2. Enable hybrid mode.

   ```bash
   PUBLIC__app__hybrid__enabled=true
   ```

3. Set `PUBLIC__app__hybrid__legacyRoutes` to a JSON array of routes that belong to SFRA/SiteGenesis. When a user clicks a `<Link>` to one of these paths, the client-side navigation middleware forces a full-page load so the CDN routes the request to SFRA/SiteGenesis.

   ```bash
   PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout"]'
   ```

   OR

   Supports exact paths and React Router-style parameterized patterns:

   ```bash
   PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/product/:id"]'
   ```

   **note:** This list is the inverse of `HYBRID_ROUTING_RULES`. If a route isn't in your routing rules (SFRA/SiteGenesis owns it) and a Storefront Next page links to it, add it here. If it's missing, React Router tries to render the route client-side and shows a 404.

### Step 2: Configure Proxy Plugin (Local Development Only)

These settings apply only to the Vite dev server. They have no effect in production builds.

4. Set `HYBRID_PROXY_ENABLED=true`.

   ```bash
   HYBRID_PROXY_ENABLED=true
   ```

5. Set `SFCC_ORIGIN` to the full HTTPS URL of your B2C Commerce sandbox.

   ```bash
   SFCC_ORIGIN=https://zzrf-001.dx.commercecloud.salesforce.com
   ```

6. Set `HYBRID_ROUTING_RULES` to define which paths stay on Storefront Next.

   ```bash
   HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/reset-password.*" or http.request.uri.path matches "^/signup.*" or http.request.uri.path matches "^/logout.*" or http.request.uri.path matches "^/login.*" or http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*" or http.request.uri.path matches "^/search.*" or http.request.uri.path matches "^/account.*" or http.request.uri.path matches "^/social-callback.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\\.data.*")'
   ```

7. Set `PUBLIC__app__defaultSiteId` so that the proxy can build SFRA/SiteGenesis-prefixed paths. The proxy fails fast at startup if this variable is missing when `HYBRID_PROXY_ENABLED=true`.

   ```bash
   PUBLIC__app__defaultSiteId=RefArchGlobal
   ```

8. Optional: Set `HYBRID_PROXY_LOCALE` if your SFRA/SiteGenesis locale path differs from your storefront fallback locale.

   ```bash
   HYBRID_PROXY_LOCALE=en-GB
   ```

9. Start the local development server with `pnpm dev`.

The proxy is disabled by default in `.env.default` and only activates when `HYBRID_PROXY_ENABLED=true`.

## Set Routing Rules

Use `HYBRID_ROUTING_RULES` to define route ownership.
To compare route split patterns, see [Choose a Hybrid Routing Matrix](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-routing-matrix.md).

- Paths that match your expression go to Storefront Next.
- Paths that don't match go to B2C Commerce (SFRA/SiteGenesis) via the proxy.
- Define any split between migrated and legacy pages. Include only the routes you've built in Storefront Next.

The rule syntax matches Cloudflare eCDN origin rules:

```text
http.request.uri.path matches "<regex>"
```

Combine clauses with `or` and wrap the expression in parentheses:

```text
(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/category.*")
```

### Required Route Patterns

Include these patterns so React Router server endpoints continue to work:

| Pattern        | Required for                          |
| -------------- | ------------------------------------- |
| `^/resource.*` | React Router resource routes          |
| `^/action/.*`  | React Router actions                  |
| `.*\.data.*`   | Production parity in shared rule sets |

### Page route patterns (optional)

Add patterns for Storefront Next pages that your team has already migrated:

| Pattern               | Route                  |
| --------------------- | ---------------------- |
| `^/$`                 | Homepage               |
| `^/login.*`           | Login page             |
| `^/logout.*`          | Logout                 |
| `^/signup.*`          | Registration           |
| `^/reset-password.*`  | Password reset         |
| `^/account.*`         | Account pages          |
| `^/product.*`         | Product detail pages   |
| `^/category.*`        | Category and PLP pages |
| `^/search.*`          | Search results         |
| `^/social-callback.*` | Social login callback  |

### Full Rule Set Example

This example keeps homepage, auth, product, category, search, account, and server endpoints on Storefront Next:

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/reset-password.*" or http.request.uri.path matches "^/signup.*" or http.request.uri.path matches "^/logout.*" or http.request.uri.path matches "^/login.*" or http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*" or http.request.uri.path matches "^/search.*" or http.request.uri.path matches "^/account.*" or http.request.uri.path matches "^/social-callback.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\\.data.*")'
```

### Paths Excluded From Proxying

The proxy doesn't forward these paths to B2C Commerce:

- `/@*`, `/__*` (Vite internals)
- `/src/*`, `/node_modules/*` (Vite-served source files)
- `*.data` (React Router data requests)
- `/mobify/*` (SCAPI proxy paths handled by React Router)
- Static assets (`.js`, `.css`, `.png`, `.woff2`, and similar extensions)

The proxy always forwards SFRA/SiteGenesis static assets under `/on/demandware.static/*` and `/on/demandware.store/*` to B2C Commerce.

## Understanding Request Flow

The hybrid proxy processes each development request in this order:

1. Vite receives the request at `localhost:5173`.
2. The hybrid proxy middleware evaluates the request path.
3. If the path matches `HYBRID_ROUTING_RULES`, React Router handles the request in Storefront Next.
4. If the path doesn't match, the proxy forwards the request to `SFCC_ORIGIN`.
5. For proxied storefront paths, the proxy rewrites to SFRA/SiteGenesis format:
   - `/cart` -> `/s/{siteId}/{locale}/cart`
6. The proxy rewrites response cookies and response body links for localhost continuity.

## Understanding Cookie Behavior

Hybrid auth requires that both Storefront Next and SFRA/SiteGenesis share the same session cookies (`dwsid`, `cc-*`). The proxy keeps them in sync in three ways:

1. **Set-Cookie header rewriting (Layer 1)**: The proxy rewrites `Domain=.salesforce.com` to `Domain=localhost` in B2C Commerce response headers. The proxy preserves all other cookie attributes (`Secure`, `SameSite`, `HttpOnly`). Localhost is a [secure context](https://w3c.github.io/webappsec-secure-contexts/), so `Secure` cookies work on `http://localhost`.

2. **Storefront Next server cookies (Layer 2)**: Storefront Next sets its own session cookies (`dwsid`, access token, refresh token, etc.) server-side via the auth middleware. Storefront Next writes them directly to `localhost`—they require no rewriting. The proxy doesn't modify them.

3. **Client-side cookie interception (Layer 3)**—localhost workaround only: The proxy injects an inline script at the top of every proxied HTML page. The script patches `document.cookie` to apply the same `Domain=localhost` rewrite to any cookies set by SFRA/SiteGenesis's own JavaScript. SFRA/SiteGenesis's client-side scripts check `window.location.protocol` to decide whether to include `Secure` on cookies—on `http://localhost` they omit it, producing cookies the browser silently rejects. This layer exists solely to compensate for localhost's non-HTTPS context and has no equivalent in the eCDN-based hybrid implementation used in production.

## Troubleshoot Common Issues

### Client-side navigation to SFRA/SiteGenesis routes shows a 404

If a `<Link>` in Storefront Next navigates to an SFRA/SiteGenesis route and React Router shows a 404 or error boundary instead of the SFRA/SiteGenesis page, the route is probably missing from `PUBLIC__app__hybrid__legacyRoutes`.

Add the missing path to the array:

```bash
PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/missing-route"]'
```

Set this routing variable in every environment—local development and production (MRT). The hybrid proxy itself runs only in local development.

### Routing rules out of sync with production

Keep `HYBRID_ROUTING_RULES` aligned with your Cloudflare eCDN origin rules. If they diverge, local behavior doesn't match production routing.

### Missing routing rules

If a Storefront Next path is missing from `HYBRID_ROUTING_RULES`, the request can fall through to SFRA/SiteGenesis and trigger SFRA/SiteGenesis redirects. The proxy logs a warning for SFRA/SiteGenesis 404 redirect patterns, for example:

```text
[Hybrid Proxy] SFCC returned a redirect to 404 for /login
  This usually means your HYBRID_ROUTING_RULES are missing a pattern for this path.
```

Add the missing route pattern to `HYBRID_ROUTING_RULES`.

### Invalid locale in SFRA/SiteGenesis path rewriting

SFRA/SiteGenesis expects `/s/{siteId}/{locale}/path`. If `HYBRID_PROXY_LOCALE` doesn't match your SFRA/SiteGenesis locale configuration, requests can return 404 responses or redirects.

### Unsupported compression

The proxy rewrites response bodies after decompressing `gzip`, `brotli`, and `deflate`. If B2C Commerce returns another compression format, the proxy skips body URL rewriting.

### Production-mode guard

The plugin runs only in development mode through the `mode === 'development'` guard in `vite.config.ts`.

## Override Route Matching (Optional)

**warning:** We strongly recommend using the default `shouldRouteToNext` matcher. Overriding it means your local dev routing no longer mirrors the Cloudflare eCDN expression format used in production. Only do this if you have a specific reason and understand the divergence it introduces.

The default matcher (`shouldRouteToNext`) parses Cloudflare expression syntax. Use a custom matcher only when you intentionally diverge from production-style route expressions.

```typescript
// vite.config.ts
import { hybridProxyPlugin, shouldRouteToNext } from "@salesforce/storefront-next-dev";

hybridProxyPlugin({
  routeMatcher: (pathname, rules) => {
    if (pathname === "/my-custom-page") return true;
    if (pathname === "/legacy-only") return false;
    return shouldRouteToNext(pathname, rules);
  },
});
```

To replace the matcher entirely, use:

```typescript
routeMatcher: (pathname) => myOwnRoutingLogic(pathname),
```

The callback receives `pathname` and `routingRules`. Return `true` to route to Storefront Next, or `false` to proxy to B2C Commerce.

If the matcher throws an error, the proxy fails safe and passes the request to React Router.

## See Also

- [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid.md)
- [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md)
- [B2C Commerce API: CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html)
- [B2C Commerce Architecture](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/get-started.html)

<!-- document id=5be695f568ce50b4fafdc6289ce1362b3c4c0f29efadf5e09b96ef1acf13dc2a url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-hybrid-ods.md -->

# Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN

**Applies to: Storefront Next**

Use Cloudflare eCDN origin routing on ODS instances to run Storefront Next and SFRA/SiteGenesis side by side at one origin. This setup is for deployed ODS environments and uses eCDN origin routing instead of the local hybrid proxy. At the end of this setup, navigate between Storefront Next and SFRA/SiteGenesis pages in ODS with no visible redirects, using routing behavior that mirrors production.

**warning:** ODS deployments use eCDN origin routing instead of the hybrid proxy plugin. Hybrid proxy is local-development only and runs only with `pnpm dev`.

For ODS, Managed Runtime (MRT), and production-style testing, route traffic with Cloudflare eCDN origin rules between Storefront Next and SFRA/SiteGenesis.

## Hybrid ODS Features

### Production-Like Hybrid Routing on ODS

Run Storefront Next and SFRA/SiteGenesis together on deployed ODS instances under one origin, with no visible redirects or session loss. Teams can validate hybrid behavior in an environment that is much closer to production than localhost.

### Parity with Production eCDN Rules

Routing decisions on ODS use the same Cloudflare eCDN expression format (`http.request.uri.path matches`) used in production. Reuse your production routing patterns so ODS testing reflects real deployment behavior.

### Scalable Development Environment Strategy

ODS lets customers spin up multiple development instances in parallel and test different migration or routing configurations safely. This strategy complements local hybrid proxy workflows on `localhost`, giving teams both fast local iteration and production-like validation on ODS.

### Configuration Flexibility

No assumptions are made about which pages live on Storefront Next versus SFRA/SiteGenesis. You define the split entirely through your eCDN origin rules, so any mix of migrated and legacy routes is supported.

## Before You Begin

Make sure that:

- You have an active ODS instance with SFRA/SiteGenesis deployed.
- You have Managed Runtime Admin console access for the target environment.
- You complete storefront setup in Business Manager as described in [Choose Your Storefront Next Quick Start Path](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-choice.md).

## Configure Hybrid Storefront Settings

### Step 1: Enable Hybrid Auth in Business Manager

Complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) for the site on your ODS instance. The shared steps are the same across all environments:

1. Create or confirm a SLAS client that includes the `sfcc.session_bridge` scope. For an ODS instance, you can find your SLAS Client ID and Client Secret in SLAS Admin or in your `.env.default` file. See [Shared Hybrid Auth Setup, Steps 1–2](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-1-set-up-a-slas-client).
2. In **Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings**, enable the **Hybrid Auth** toggle, enter your SLAS Client ID (and secret, or select **Is Public Client** for a public client), optionally enable **Shopper Context** and **Do-Not-Track Synchronization**, and click **Apply**. See [Shared Hybrid Auth Setup, Step 4](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-4-configure-business-manager).

**note:** The **HttpOnly True** toggle doesn't affect Storefront Next. Storefront Next always sets cookies with `HttpOnly=true`, regardless of this setting.

### Step 2: Configure the Application (MRT Environments)

In the Managed Runtime Admin console, open your project, select the target environment, and go to the **Environment Variables** section. Set the following values for each deployed environment where you use hybrid routing.

1. Enable hybrid mode.

   ```bash
   PUBLIC__app__hybrid__enabled=true
   ```

2. Set `PUBLIC__app__hybrid__legacyRoutes` to a JSON array of routes that belong to SFRA/SiteGenesis. When a user clicks a `<Link>` to one of these paths, the client-side navigation middleware forces a full-page load so eCDN routes the request to SFRA/SiteGenesis.

   ```bash
   PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout"]'
   ```

   Or use exact paths and React Router-style parameterized patterns:

   ```bash
   PUBLIC__app__hybrid__legacyRoutes='["/cart", "/checkout", "/product/:id"]'
   ```

   **note:** This list is the inverse of your eCDN origin routing rules. If a route isn't in your routing rules (SFRA/SiteGenesis owns it) and a Storefront Next page links to it, add it here. If it's missing, React Router tries to render the route client-side and shows a 404.

   For example, if your eCDN rule routes `/product/*` to Storefront Next, do not include `/product/*` in `legacyRoutes`. If `/cart` and `/checkout` aren't in your eCDN rule, include them in `legacyRoutes` so Storefront Next forces a full-page navigation to SFRA/SiteGenesis.

### Step 3: Configure eCDN Routing Rules

Use the hosted zone created during setup to configure eCDN origin routing rules.
To compare route split patterns, see [Choose a Hybrid Routing Matrix](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-routing-matrix.md).

#### Locate the eCDN Zone Hostname

1. In Business Manager, navigate to **Administration > Sites > Storefronts**.
2. Select the storefront that you just created.
3. Under **Environments**, select the environment that you are setting up.
4. In the **eCDN** section, find the default routing rule.
5. Expand that routing rule to locate your eCDN zone hostname.

![Default eCDN routing rule showing the hosted zone hostname](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-ods-ecdn-1.png '{"class": "image-xl"}')

#### Update Aliases with the eCDN Hostname

1. In Business Manager, navigate to **Merchant Tools > Select Site > SEO & Discoverability > Aliases**.
2. Update `http-host` and `https-host` with the eCDN hostname that you noted in the previous section.

   ```json
   {
     "__version": "1",
     "settings": {
       "http-host": "your-demo-hostname.zzrf-000.my.commercecloud.salesforce.com",
       "https-host": "your-demo-hostname.zzrf-000.my.commercecloud.salesforce.com"
     }
   }
   ```

3. Click **Save**.

**note:** ODS hybrid storefronts use the Salesforce-provided eCDN default domain. Custom or vanity domains aren't supported for ODS setups. Updating site URL aliases doesn't create a custom hostname—it only makes generated storefront URLs use the ODS default domain.

#### Update eCDN Routing Rules for Your Demo Site

Configure the eCDN routing rule for your hostname in the Business Manager eCDN UI, then set the Storefront Next rule expression. For the full UI walkthrough and screenshots, see [Configure Routing Rules in the Business Manager UI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html#configure-routing-rules-in-the-business-manager-ui).

1. Go to **Administration > Sites > Embedded CDN Settings**, open **Configure Routing Rules** for the zone that contains your hostname, and click **Edit** on the routing rule for your hostname.
2. Confirm that the **Hostnames** and **MRT Origin** fields are prefilled and match your setup.
3. In **Rule expression**, paste the following rule. This expression matches Storefront Next routes (home, category, product, search, and account flows), plus resource routes, action endpoints, React Router data prefetch requests, and static assets.

   ```text
   (http.request.uri.path matches "^(/[^/]+/[^/]+)?/(|home|category|product|search|account|login|signup|logout|reset-password|social-callback)(/.*)?$" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\.data.*" or http.request.uri.path matches "^/assets/.*" or http.request.uri.path matches "^/favicon\.ico$")
   ```

   ![Rule expression configured for hybrid routing](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-ods-ecdn-3.png '{"class": "image-xl"}')

   **note:** This guide uses a default hybrid split: top-of-funnel pages (home, category, product, search, and authentication flows) on Storefront Next, with cart and checkout on SFRA. Modify both eCDN origin rules and `PUBLIC__app__hybrid__legacyRoutes` to support any hybrid storefront combination. Make sure the two route definitions are complementary.

4. Click **Save**.

### Step 4 (Optional): Configure Locale Rules

Storefront Next enables storefront context and automatically adds site ID and locale prefixes to routes.

To correctly route between pages that include locale prefixes, configure URL rules in Business Manager so that SFRA/SiteGenesis URLs use matching prefixes.

1. In Business Manager, navigate to **Merchant Tools > Select Site > SEO & Discoverability > URL Rules**.
2. Select the **Settings** tab.
3. In the **Locale Mapping** section, set **Locale Mapping** to **Path**.
4. Add your Storefront Next prefixes for each supported locale.

![Locale mapping configuration for hybrid routing](https://developer.salesforce.com/docs/media/sfnext/sfnext-hybrid-ods-locale-1.png '{"class": "image-xl"}')

5. Click **Apply**.

### Step 5: Verify Your Setup

Your setup is working when navigation between Storefront Next and SFRA/SiteGenesis occurs without visible redirects, all required cookies persist across transitions, and the `sfdc_dwsid` request header matches the `dwsid` cookie value.

1. Visit your eCDN hostname.
2. Confirm the home page loads on Storefront Next.
3. Navigate to a page served by SFRA/SiteGenesis.
4. Open browser Developer Tools and inspect cookies. Confirm that the following cookies are set:
   - `cc-nx-g_{Site_ID}`: Guest refresh token
   - `dwsid`: B2C Commerce session ID
   - `usid`: SLAS customer ID
   - `cc-at_{Site_ID}`: SLAS access token (this cookie appears when the user lands on an SFRA/SiteGenesis page; after handoff to Storefront Next, it is consumed)
5. Navigate to any Storefront Next page and verify:
   - `cc-nx-g_{SiteID}` remains the same.
   - `dwsid` remains the same.
   - `usid_{SiteID}` remains the same.
   - `cc-at_{SiteID}` is no longer present because Storefront Next consumes it and stores the access token in `localStorage` as `accesstoken{SiteID}`.
6. In Developer Tools, switch to the **Network** tab.
7. Add an item to cart on Storefront Next.
8. Inspect the SCAPI Add to Cart request. In **Request Headers**, confirm `sfdc_dwsid` matches the `dwsid` cookie value.

**note:** The `sfdc_dwsid` request header is required to keep hybrid storefront behavior stable at production scale when traffic can be distributed across multiple app servers.

If you are not using Storefront Next, set this header in your headless application whenever the `dwsid` cookie is available.

## Troubleshooting

| Symptom                                               | Likely cause                                                                       | Resolution                                                                                                                                                       |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Routing sends users to the wrong storefront.          | eCDN rule and `PUBLIC__app__hybrid__legacyRoutes` are out of sync.                 | Confirm that routes matched by the eCDN expression are not listed in `legacyRoutes`, and that any route owned by SFRA/SiteGenesis is included in `legacyRoutes`. |
| Cookies don't persist across navigation.              | Hybrid Auth is disabled or SLAS is missing the `sfcc.session_bridge` scope.        | Re-enable **Hybrid Auth** in Business Manager and confirm the SLAS client has `sfcc.session_bridge`.                                                             |
| 404 errors on Storefront Next pages.                  | MRT environment variables aren't set or weren't applied to the active environment. | In the MRT Admin console, verify `PUBLIC__app__hybrid__enabled` and `PUBLIC__app__hybrid__legacyRoutes` for the active environment, then redeploy if needed.     |
| `sfdc_dwsid` header doesn't match the `dwsid` cookie. | The header isn't being sent with SCAPI requests.                                   | Confirm that you're on Storefront Next, or that your headless app sets `sfdc_dwsid` from the `dwsid` cookie before each SCAPI request.                           |

## Next Steps

- Compare alternate route splits in [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-routing-matrix.md).
- Iterate on routing locally before redeploying to ODS by following [Set Up Hybrid Proxy for Local Development](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-proxy-local-dev.md).

<!-- document id=a828a05e4496eeea00e0f66e251dd982597cd7e4cc3a20d3325fa62753b119be url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-payment-b2b-setup.md -->

# Set Up Payment Processing

To collect credit card payment information in your store, create a payment gateway and connect it to your checkout. The adapter you also create to communicate with the gateway depends on whether you implement a server- or client-side payment process.

**note:** Payment processing in the checkout flow is limited to payment authorization. The checkout flow doesn’t collect or store payment information in the provided payment components. Payment authorization occurs prior to order placement to limit the chance of an error occurring before credit card authorization.

<!-- document id=00608a3ad3c0a748428888f67072bddf4436e6da0cfdff8f606c7e7aa752b154 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/search-and-navigation/b2c-search-mode-ab-testing.md -->

# **Set Up Search Mode A/B Testing in B2C Commerce**

Compare Agentic Commerce Search results against the native B2C Commerce search engine on live storefront traffic. Read the results in Google Analytics 4.

## What You Need Before You Start

- [Agentic Commerce Search](https://help.salesforce.com/s/articleView?language=en_US&id=cc.b2c_acs_enable.htm&type=5) turned on for your storefront.
- A [Google Analytics 4 (GA4)](https://support.google.com/analytics/answer/9304153) account.
- Familiarity with the [Shopper Search](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=Summary) API.
- [SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) authentication configured for Shopper API calls.

## How Search Mode A/B Testing Works

B2C Commerce lets you pin a search request to a specific engine with a `searchMode` value.

- `A semantic` search request routes the query to the Agentic Commerce Search engine.
- `A lexical` (case-insensitive) search request routes the query to the legacy B2C Commerce Search engine.

Every search response echoes back the mode that was actually served, so you always know which engine produced a given result set. The echo makes a clean A/B comparison possible.

- Assign each shopper to a mode.
- Tag your analytics with the mode they got.
- Compare conversion between the two groups.

### Platform and Storefront Responsibilities for Search Mode A/B Testing

Search Mode A/B testing splits work between the B2C Commerce platform and your storefront.

**What B2C Commerce provides**

- The `searchMode` request parameter and response fields on SCAPI.
- Safe fallback when the engine can’t serve the requested mode.
- The mode actually served on every response.

**What you implement**

- Deciding which shopper gets which mode (the bucketing algorithm).
- Making the assignment sticky per shopper and getting it into the URL.
- Emitting the assigned mode to your analytics platform.

The reference implementation is a starting point. You own that code and fork it to fit your storefront and analytics stack.

## How Shopper Assignment Works

Three principles shape the design:

1. **You own the bucketing.** You pick a seed and a ratio. The assignment is `SHA-256(seed:userId) % 100 < ratio ? semantic : lexical`. Anyone with the seed and ratio can independently replay `userId to mode` mapping and verify it, with no opaque service-side bucketing.
2. **Assignment is sticky per shopper.** A shopper sees the same engine for every search in their session, and across sessions, for the life of their identity cookie. Otherwise, the conversion data is noise.
3. **The mode rides in the URL.** Edge-cached storefront responses are keyed on URL \+ querystring, so the assigned mode is appended to the search URL as `?searchMode=semantic` / `?searchMode=lexical`. This segregates the page cache per variant. Two shoppers on different modes never share a cache entry.

The reference implementation computes the mode at session start, redirects cacheable search routes to the URL carrying the mode, and reads that value back on the search request. On the SFRA path, it pins the mode via a Script API call on the product-search model before the query runs.

## Call the **`searchMode`** Parameter on Product Search

**Note:** The **`effectiveSearchMode`** response fields are currently available only in the BETA API version. On lower versions, B2C Commerce silently strips them from the response. Request the BETA version to see them.

`searchMode` is a top-level parameter on the product-search resource, accepted by both SCAPI and [OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/b2c-api-doc.html). Values are `semantic` or `lexical`, and any other value returns HTTP 400\.
**Warning:** OCAPI is deprecated as of April 2026\. For new work, [use SCAPI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/why-use-scapi.html).

Every response echoes the **`effectiveSearchMode`** field, which is the mode actually served. The field may differ from what you requested. For more information, see [When Semantic Search Falls Back to Lexical](#when-semantic-search-falls-back-to-lexical).

Field casing follows each API's convention:

| Surface | Request param | Response fields |
| :---- | :---- | :---- |
| SCAPI (`shopper-search`) | `?searchMode=semantic` | `effectiveSearchMode` (camelCase) |
| OCAPI (`product_search`) | `?searchMode=semantic` | `effective_search_mode` (snake\_case) |
| Script API  (`dw.catalog.ProductSearchModel`) | `setSearchMode("semantic")` | `getEffectiveSearchMode()` |
| SFRA storefront URL | `?searchMode=semantic` | \- (cartridge-owned) |
| GA4 user properties | N/A | `effective_search_mode` |

**Note**: These API calls require a [Shopper Login and API Access Service (SLAS) access token](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html). Also, replace {org} and the host with your B2C Commerce instance values.

**SCAPI Example:**

```http
GET /search/shopper-search/v1/organizations/{org}/product-search?q=shirt&searchMode=semantic
```

```json
{
  "effectiveSearchMode": "semantic",
  "hits": [ ... ]
}
```

**OCAPI Example:**

```http
GET /s/{site}/dw/shop/v23_2/product_search?q=shirt&search_mode=semantic
```

```json
{
  "effective_search_mode": "semantic",
  "hits": [ ... ]
}
```

**Script API.** On the SFRA / server-side path, the same contract is exposed on [`dw.catalog.ProductSearchModel`](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-script-api/dw.catalog.ProductSearchModel.html). Call `setSearchMode("semantic")` before `search()` to pin the mode, and read `getEffectiveSearchMode()` afterward to see what was actually served. This is the surface the reference implementation uses internally.

## When Semantic Search Falls Back to Lexical

The engine cannot serve `semantic` in a few cases.

- The semantic index is missing or not ready.
- A single-token product lookup.
- A category-browse with the semantic toggle off.

In those cases the platform serves `lexical`. This is expected, not an error, but a high fallback rate during a test means the semantic engine is unstable and the comparison is contaminated.

## Set Up Search Mode A/B Testing

The reference implementation ships as two cartridges:

- `The plugin_cimulate_ab_experience` cartridge is the merchant-agnostic decider and hooks.
- `The int_merchant_ab_experience` cartridge is your configuration and analytics loader.

After you deploy the cartridges, you own both and can fork and adapt them for your storefront.

### Configure the abConfig.js File

The only file you must edit is the `int_merchant_ab_experience/.../scripts/config/abConfig.js` file.

```javascript
module.exports = {
    SEED: 'search-mode-2026',           // pick once, never change mid-test
    RATIO: 50,                          // 0..100 percent routed to semantic
    GA4_MEASUREMENT_ID: 'G-XXXXXXXXXX'  // your GA4 measurement ID
};
```

Set these values before you deploy.

- `SEED` — Keep this value stable for the life of the test. If you change it, B2C Commerce re-buckets every shopper on their next session and mixes your data.
- `RATIO` — Use any integer from `0` to `100`. `50` is a clean 50/50 split to semantic search.
- `GA4_MEASUREMENT_ID` — Match the GA4 property where you registered the custom dimension. If this value is empty, the analytics emission is a silent no-op. An empty measurement ID is a common reason that you see no data in GA4 even after you deploy the cartridges.

### Add the Cartridges to the Site’s Cartridge Path

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Sites > Manage Sites > *site* > Settings**.
2. Prepend the two cartridges before `app_storefront_base`, with the merchant cartridge first:

   ```text
   int_merchant_ab_experience:plugin_cimulate_ab_experience:app_storefront_base
   ```

   The merchant cartridge overrides the plugin's placeholder config, so prepend the merchant cartridge first.
3. Save your changes. SFRA picks up the path changes when you make your next request.

### Upload and Deploy the Search Mode A/B Testing Cartridges

Deploy both cartridges to your instance with your normal cartridge upload process (`dwupload` / SFCC VS Code extension / your CI). Neither cartridge contains Java, so no platform build is required.

## Register the Search Mode Dimension in GA4

1. Create or pick a GA4 property and a Web data stream, and copy the **Measurement ID** (`G-XXXXXXXXXX`) into the `abConfig.js` file.
2. In GA4, go to **Admin > Data display > Custom Definitions > Create custom dimension**.
3. Create a user-scoped custom dimension with these values:
   - Name: `Search Mode`
   - Scope: `User`
   - User property: `effective_search_mode`

   Without this dimension, GA4 silently drops the user properties. The values are sent, but never appear in any report or export column.
4. Grant DebugView access to whoever verifies that `effective_search_mode` appears in GA4.

## Verify Search Mode A/B Testing Before You Run It

Run these checks before you trust GA4 reports for the test.

### Run the Response Echo Test

1. Log in to the storefront as a real customer.
2. Open the browser’s **DevTools** and go to **Network**.
3. Perform a search and find the product-search response.
4. Confirm that `effectiveSearchMode` (or `effective_search_mode` on OCAPI) is `semantic` or `lexical`.

### Run the Analytics Emission Test

1. Open the browser’s **DevTools** and go to **Network**.
2. Filter by `collect`.
   Confirm that the GA4 `collect` request body includes a `user_properties` block with `effective_search_mode`.
3. Alternatively, run `dataLayer` in the console and look for the `gtag('set', 'user_properties', ...)` entry.

### Run the GA4 DebugView Test

1. In GA4, go to **Admin \> Data display \> DebugView**.
2. Append `?_dbg=1` to the storefront URL (or use the *Google Analytics Debugger* Chrome extension).
3. Click any event. The **User Properties** panel lists `effective_search_mode`.

## Run the Search Mode A/B Test

After the assignment flows and the DebugView test shows `effective_search_mode` on every event, run the test. Track these questions as you run the test.

| Question | Where to look | What to check |
| :---- | :---- | :---- |
| Did every shopper get assigned? | Realtime \> Users by user property (dimension \= `effective_search_mode`) | Populated on essentially every active user. A chunk of `(not set)` means the cartridge isn't pinning and usually indicates a cartridge-path order issue. |
| What's the assignment ratio? | Explore, dimension \= `effective_search_mode`, metric \= `users` | Roughly `RATIO%` semantic / `(100-RATIO)%` lexical. |
| Does semantic convert better? | Explore, dimension \= `effective_search_mode`, metrics \= `transactions`, `purchase_revenue`, `add_to_cart` | The actual A/B result. Wait for statistical significance before drawing conclusions. |
| Did tagging stick across the session? | DebugView, single user, multiple events | Every event for one user should carry the same `effective_search_mode`. If it flips mid-session, the assignment isn't sticky. |

## Troubleshoot Search Mode A/B Testing

| Symptom | Likely cause |
| :---- | :---- |
| `effective_search_mode` always `lexical` on `?searchMode=semantic` requests | The semantic engine is unhealthy for that site, and may indicate index missing, single-token product search, or category-browse with the semantic toggle off. |
| `effective_search_mode` populated on the response but **not** in GA4 reports | Custom dimensions weren't registered. GA4 silently drops user properties that aren't pre-registered. |
| `effective_search_mode` flips mid-session for the same user | The shopper's session or identity isn't surviving the request and typically indicates a cross-domain boundary or blocked cookies. |
| Assignment ratio is far off `RATIO` | `SEED` was changed mid-test. Reset and start fresh because the existing data is mixed. |
| Response omits the `effectiveSearchMode` field entirely | Request was made against a version below BETA. The fields are BETA-gated and stripped on lower versions. Retry against BETA. |

<!-- document id=24ea38029be51e4fd4c2b1065853e35b1fada54e326eeb2224302347c890ab08 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-payment-serverside-setup.md -->

# Set Up Server-Side Payment Processing

A server-side payment processing integration requires a server-to-server integration between your Salesforce store and the payment provider. This implies using the payment component(s) shipped with your B2C or D2C Commerce app. In this model you either author, or obtain from the App Exchange, an Apex payment gateway adapter that handles the server-side payment transaction processing between the Salesforce platform and the payment gateway.

Create your store and configure checkout before you set up your payment system.

**note:** For exposure to security threats, implementing custom payment components with a server-side integration is not recommended.

The paved path for server-side integration in commerce checkout is a tokenization-to-authorization flow that currently supports only CardPaymentMethods and single use tokenization with no support for saved payment methods. From a checkout standpoint the [PaymentRequestTypes](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_enum_commercepayments_RequestType.htm) to implement are Tokenize and Authorize. Of course you’ll need to implement the other request types to handle downstream operations in your order management system such as capture and referencedrefund. When integrating payments with a server to payment gateway server pattern, use our out-of-the-box payment components: Payment and Dual Payment (available in B2B stores only). Otherwise you are on an unpaved path.

The diagram illustrates a typical server-side integration. The Checkout UI component triggers the Commerce Checkout Payment APIs, which call the [Commerce Payment Connect APIs](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_payments.htm). The Apex Payment Adapter posts request types to the gateway. Those request types are what you implement when you create the Apex Adapter

![Diagram of Server-side payment flow.](https://developer.salesforce.com/media/d2c-commerce/serverside_payment_flow.png)

To implement server-side payment processing, see [Payment Gateway Adapters](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_commercepayments_adapter_intro.htm) and then connect your payment gateway to your checkout using the integrated store service as described in [Connect a Payment Service to Store Checkout](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-checkout-connect-gateway.md).

<!-- document id=6fc5d7da137a782f5d643794e31b992ce842bb3e970089816382c2d045ac0525 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/tax-integration-via-spi.md -->

# Set Up Tax Integration Using SPI

Point of Sale (POS) SPIs empower merchants to calculate taxes according to their own system's rules. Retrieve tax rates for offline transactions and access a list of supported tax exemptions. Also finalize the taxes applied to sales transactions.

## Prerequisites

- Modern POS App Build: 10.0.1 or greater
- Platform Support: iPad & iPhone
- Offline Support: No

**note:** For details on this SPI, see [Tax Calculation SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/tax-calculation-spi?meta=Summary) in the Point of Sale reference documentation.

For a comprehensive list of POS APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Tax SPIs

1. Calculate Tax - Calculates the tax based on the rules defined in the merchant's system. The request includes a list of products, applicable tax exemptions, and the originating and destination addresses to apply the correct tax rates.

`POST/merchant/spi/sample/endpoint/taxEngine/calculateTax`

1. Download Tax Rates - Retrieves a list of tax or VAT rates for offline transactions. The request can include optional parameters like country code, state, city, and postal code. The response is provided in CSV format. The first line contains the column headers and subsequent lines include the corresponding tax or VAT rate values. For attributes and a sample file, refer to the "Tax Feed Specification section in [Tax Rates Feed & Setup](https://help.salesforce.com/s/articleView?id=commerce.rt_adv_config_data_feeds_specs_tax_rates.htm&type=5) in _Salesforce Help_.

`GET/merchant/spi/sample/endpoint/taxEngine/downloadTaxRates`

3. Finalize Tax Submission - This optional SPI finalizes the taxes applied to sale transactions. It sends a list of products, the applied taxes, and the associated order ID to the tax engine.

`POST/merchant/spi/sample/endpoint/taxEngine/finalizeTaxSubmission`

4. Retrieve Tax Exemptions - Retrieves a list of tax exemptions supported by the merchant. The request can include optional parameters such as country code, state, city, and postal code.

`GET/merchant/spi/sample/endpoint/taxEngine/getTaxExemptions`

5. Verify Tax Engine - Verifies that the SPI Tax Engine is available and that requests can be sent. If this API is implemented, it's checked when verifying the feed source for offline taxes. If it is not implemented, it will be allowed to pass through and attempt to download tax rates.

`GET/merchant/spi/sample/endpoint/taxEngine/verify`

## Configure SPI

Create a custom connector SPI named `TAX_SERVICE` with the endpoint and other relevant details. This automatically generates the Tax Engine as an SPI. This configuration can be edited to set the shipping tax configuration. No additional details are required here; all other specifics should be included in the SPI.

1.  In CMS, go to **Integrations** | **Custom Connectors**.

2.  Click **Create**.![A screenshot shows the Custom Connection Configuration (SPI and Webhooks) dialog.](https://developer.salesforce.com/docs/media/retail-cloud/rt-adv-config-3p-int-tax-spi-setup.png)

3.  For Connector Type, select **SPI**.

4.  For Endpoint Name, select **TAX_SERVICE**.

5.  For API Endpoint, enter the common endpoint\URL base in the configuration. Create only one custom connector for tax. POS automatically appends each of the following paths to your base URL. Implement all of these methods with the exact ending keywords as specified:

    1.  `/calculateTax`

    2.  `/downloadTaxRates` (for offline transactions)

    3.  `/getTaxExemptions`

    4.  `/finalizeTaxSubmission` (if the store setting flag finalizeTaxOnOrderSubmission is enabled under **Store Management** | **Store Settings** | **Tax**)

    **important:** All four methods are mandatory, even if you don't use every feature. For example, implement `/getTaxExemptions` even if you don't offer tax exemptions. In that case, return a response with an empty `taxExemptions` array:

    ```json
    {
      "taxExemptions": []
    }
    ```

## Example Payloads

These are examples of the request payload and the response for the Calculate Tax SPI.

**Request**

```java
{
  "taxBuckets": [
    {
      "products": [
        {
          "amount": 0,
          "productId": "string",
          "quantity": 0,
          "orderItemId": "string",
          "description": "string",
          "taxClass": "string"
        }
      ],
      "taxExemptions": [
        {
          "customerName": "string",
          "cardNumber": "string",
          "taxExemptCode": "string",
          "taxExemptName": "string",
          "taxType": "CLASS"
        }
      ],
      "originStoreId": "string",
      "fromAddress": {
        "firstName": "string",
        "lastName": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "countryCode": "string",
        "phone": "string",
        "storeId": "string",
        "emailAddress": "string"
      },
      "toAddress": {
        "firstName": "string",
        "lastName": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "countryCode": "string",
        "phone": "string",
        "storeId": "string",
        "emailAddress": "string"
      }
    }
  ]
}
```

**Response**

```java
{
  "errorMessage": "Invalid request. Please check the request and try again.",
  "errorCode": "INTERNAL_ERROR",
  "taxItems": [
    {
      "amount": 0,
      "productId": "string",
      "quantity": 0,
      "orderItemId": "string",
      "description": "string",
      "taxClass": "string",
      "taxRecord": {
        "totalTax": 0,
        "taxRates": [
          {
            "taxRate": 0,
            "taxAmount": 0,
            "taxType": "CLASS",
            "taxCode": "string",
            "taxClass": "string",
            "perUnitTaxAmount": 0,
            "highPrecisionTaxAmount": 0,
            "taxName": "string",
            "isExempt": false,
            "taxExemptCode": "string",
            "taxExemptionAmount": 0,
            "countryCode": "string",
            "state": "string",
            "postalCode": "string"
          }
        ],
        "totalExemptionAmount": 0
      },
      "vatRecord": {
        "totalVat": 0,
        "vatRates": [
          {
            "taxRate": 0,
            "taxAmount": 0,
            "taxType": "CLASS",
            "taxCode": "string",
            "taxClass": "string",
            "perUnitTaxAmount": 0,
            "highPrecisionTaxAmount": 0,
            "taxName": "string",
            "isExempt": false,
            "taxExemptCode": "string",
            "taxExemptionAmount": 0,
            "countryCode": "string",
            "state": "string",
            "postalCode": "string"
          }
        ],
        "totalExemptionAmount": 0
      }
    }
  ],
  "error": true
}
```

## Frequently Asked Questions (FAQs)

**For GET tax exemption, is this expected to be called once for any new tax exempt value (For example, Government, Military, etc.)?**

Yes, the call is made this each time a tax exemption is applied through the app.

**For POST tax, is this call made every time an item is added to the cart?**

Yes, the call is made each time a product is added to the cart.

**For GET download rates, do merchants run this every 24 hours like we do with Avalara?**

Yes, similar to Avalara, a job is set up to call the API and download the tax rates every 24 hours.

**For POST tax submission, when is this triggered? On order submission for every order?**

Yes, this is triggered during order submission for each order. This is optional for the merchant to implement.

**What do the following attributes mean?**

- `Total tax amount with high precision`: High precision means storing detailed tax amounts in our database and Tlog for reconciliation purposes. Generally, values are rounded to two decimal places (for example, 5.37 from 5.368125).
- `OrderItemId`: This is the sequence number of an item within the cart. For example, if it’s the third item out of 5 total items, Point of Sale passes 3, and we expect the same value back. If it does not match, it won't fail, but we expect the `orderItemId` to be returned along with the appropriate tax rate.

**Is there a tax bucket for each delivery group and its "to" shipping address?**

No, a separate tax calculation request is sent for each delivery group and shipping method/address. Each request is processed individually, meaning there aren't multiple tax buckets combined in a single request. The tax calculation SPI is called for each delivery group separately.

**Will each tax bucket contain only one item in the products array with `productId = "shipping"`?**

Yes.

**How does Point of Sale know which items in the delivery group the shipping tax is applied to when sending the response? Does the request contain a comma-separated list of all orderItemIds in the delivery group?**

The tax calculation request for shipping isn't tied to specific `orderItemIds`. Instead, the shipping price and shipping tax class apply to all items in that delivery group. The request is based solely on the shipping cost and tax class, without referencing individual order items.

**How does the app handle tax exemptions?**

When a tax exemption is applied through the app, a tax calculation request is sent to the SPI with the exemption details. The SPI responds with updated tax information, including:

- `taxExempt=true`: Indicates that the exemption has been applied.
- `taxExemptionAmount`: Specifies the exemption amount applied.

These fields are used to recalculate and display the adjusted tax amount in the app.

**note:** The `totalExemptionAmount` and `itemTax.taxExemptionAmount` in the SPI response are expected to be negative (-ve) values to properly reflect the tax reduction.

<!-- document id=21f63886253786c7b65c298d7c0165322b25c25c54fb3467babf9e2a6054fb68 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/setting-up-your-local-environment.md -->

# Set Up Your Local Environment

This guide covers how to set up your local environment for developing with PWA Kit.

## Recommendations

We recommend using a Unix-based operating system for PWA Kit development, such as:

- Windows 10 with the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-wsl) installed
- macOS 10.13 or greater
- Ubuntu Linux 18.x or greater

**Windows users**: See Microsoft’s [official recommendations](https://docs.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows) for Node developers.

## Required Software

You must install specific versions of Node and Node Package Manager (NPM) that are supported by Managed Runtime.

Go to the [Node 22.x download page](https://nodejs.org/dist/latest-v22.x/) to download the right installer for your machine.

**Windows users**: Download the `.msi` file that corresponds to your processor. For example, if you have a 64-bit Intel processor, you would choose the `x64` installer.

**Mac users**: Download the `.pkg` file.

**Apple silicon users**: If you haven’t installed Rosetta already, run `softwareupdate --install-rosetta`.

**Linux users**: Download the `-linux` file that corresponds to your processor. For example, if you have a 64-bit Intel processor, you would choose the `linux-x64` installer in your preferred archive format.

### Run the Node Installer

Now that you’ve downloaded the appropriate Node installer, open it and complete the setup instructions.

When prompted by the installer, accept the default option to also install the Node.js runtime, install Node Package Manager, and add the Node.js runtime to your path.

### Check the Versions of Node and NPM

Before moving on, check that the correct versions of Node and NPM are installed:

1.  Open a terminal.
2.  Run `node -v`.
3.  Make sure that it returns `v22.14.0` (or the latest `22.x` version).
4.  Run `npm -v`.
5.  Make sure that it returns `9.5.1` (or the latest version included with Node `22.x`).

### Install NPM Manually

If you have a different version of NPM installed, you can install version `9.5.1` manually like this:

1.  Open a terminal.
2.  Run `npm install -g npm@9.5.1`.
3.  Run `npm -v` again.
4.  Make sure that it returns `9.5.1`.

### Multiple Versions of Node

If you want to manage multiple versions of Node on Windows, we recommend [Node Version Switcher](https://github.com/jasongin/nvs) or [Volta](https://volta.sh/). We don’t recommend Corey Butler’s Node Version Manager (NVM) for Windows because we have encountered issues with it during our testing.

For Mac and Linux users, we recommend installing [Node Version Manager](https://github.com/nvm-sh/nvm).

## Create a Runtime Admin Project

Every PWA Kit storefront must have a project created in [Runtime Admin](https://runtime.commercecloud.com/) for managing deployments.

**important:** Before you can use Managed Runtime and Runtime Admin, ask your B2C Commerce administrator to add one of these roles to your account in Account Manager: **Managed Runtime User** or **Managed Runtime Admin**.


If you or someone on your team hasn’t already, here’s how to create a project in Runtime Admin:

1.  Log in to [Runtime Admin](https://runtime.commercecloud.com).
2.  **Click New Project**.
3.  Enter a name for the project.
4.  Click **Create Project**.

Make a note of the project ID because **you need it for generating project files** for development.

**note:** When you first create a project, the site isn’t accessible on the web until after the necessary cloud infrastructure is deployed. The deployment process can take up to 40 minutes.

To learn more about what you can do in Runtime Admin, see our guide to [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md).

## Use Existing Project Files

Most PWA Kit developers start by cloning a repository containing a previously generated set of project files. (To learn how to generate a new project, skip to the next section.)

After cloning your project repository, you must install package dependencies:

1. Open a terminal.
2. Change to the project directory.
3. Run `npm ci`

## Generate New Project Files

If you already have an existing PWA Kit project and have completed the instructions in the last section, you can skip to the next section. Otherwise, you must generate a project.

To generate a project, open a terminal and run the following command. Replace `~/PLACEHOLDER-PROJECT-ID` with a path that includes the project ID from Runtime Admin:

```bash
npx @salesforce/pwa-kit-create-app@latest --outputDir ~/PLACEHOLDER-PROJECT-ID
```

**note:** In the `npx` command, you can replace `@latest` with a specific version of the Retail React App, such as `@v3.0.0` or `@v2.7.3`. If you don’t specify a version, you can get unexpected results due to caching of old versions.

### Project Presets

When prompted to choose a project preset, select from one of the following options:

- `retail-react-app-demo`: Use the [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md) storefront template and use the demo sandbox for the back end. No further configuration required.
- `retail-react-app`: Use the [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.md) storefront template and use your own B2C Commerce instance for the back end. You must provide configuration values.

### Configuration Values

When using the `retail-react-app` preset, the generator script asks you to provide several configuration values. These configuration values associate your new PWA Kit project with a corresponding project in the Runtime Admin tool and a B2C Commerce instance.

The following table provides more information about each project configuration value and where to find them. The configuration values are also covered in more detail in the B2C Commerce API documentation. See [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/commerce-api/guides/base-url.md).

| Configuration Value                              | More Information                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project ID in Managed Runtime Admin              | [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md) covers how to create a project and look up the project ID of an existing project. <ul><li>Example: `example-project`</li></ul>                                                                                                                                                                                                               |
| URL for your B2C Commerce instance               | Need a new B2C Commerce instance for development or testing? See [Create an On-Demand Sandbox](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/creating-an-on-demand-sandbox.md).<ul><li>Example: `https://zzdc-001.dx.commercecloud.salesforce.com`</li></ul>                                                                                                                                                                                                   |
| Commerce API client ID                           | This identifier isn’t found in Account Manager anymore. See [Generate a Client ID for API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md#3-generate-a-client-id-for-api-access).<ul><li>Example: `1adba44c-ee9b-41f9-b4bf-1bbc3dda1967`</li></ul>                                                                                                                                                                              |
| Commerce API private client mode                 | This toggles whether your application will use a public or private authentication flow for logging in shoppers. See the [Shopper Login documentation](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#slas-clients) and [Use A SLAS Private Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/use-a-slas-private-client.md) for more information. <ul><li>Default: `true`</li></ul>                                          |
| Site ID in Business Manager                      | String used to identify a particular ecommerce site. To get a list of available sites and their associated site IDs in Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.<ul><li>Example: `RefArch`</li></ul>                                                                                        |
| Commerce API organization ID in Business Manager | String used to identify your organization for API access based on the realm and instance. To find the organization ID in Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Salesforce Commerce API Settings**.<ul><li>Example: `f_ecom_zzdc_001`</li></ul>                                               |
| Commerce API short code in Business Manager      | An eight-character string assigned to a realm for routing purposes. The short code applies to your entire realm environment, across all instances. To find your short code in Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Salesforce Commerce API Settings**.<ul><li>Example: `kv7kzm78`</li></ul> |
| API Client ID in the Einstein Configurator       | See the [Einstein API documentation](https://developer.salesforce.com/docs/commerce/einstein-api/overview) for B2C Commerce developers and access the [Einstein Configurator](https://configurator.cquotient.com/) directly.                                                                                                                                                                                     |

After generating a project, we recommend that you commit the generated project files to a repository and share the repository with your storefront developers.

You can edit a project’s configuration values _after_ a project has been generated too. See [Configuration Files](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configuration-options.md) for more information.

**note:** Don’t forget to update the configuration whenever any of these values change, such as when you customize project files to work with a different B2C Commerce instance.

## Start Your Web Server

To start your web server for local development, run the following command from your project directory:

```bash
npm start
```

Now that the development server is running, you can open a browser and preview your storefront:

- Go to [http://localhost:3000/](http://localhost:3000/)

You can stop the development server at any time by using the keyboard shortcut `Control`+`C`.

To preview a server-side rendered page, append the `?__server_only` query string to the URL you’d like to preview. For example, you can test the server-side rendered version of `www.example.com` by visiting the URL `www.example.com?__server_only`.

## Troubleshooting

- After cloning an existing project and running `npm ci` or generating a new project, it can take a few minutes before you see any activity in the terminal, so don’t cancel the process until it finishes. Also, anti-virus software (especially on Windows) can cause installations to take much longer than usual.

- If you get an HTTP 401 error response from the `authorize` endpoint, there’s a configuration problem with the Shopper Login and API Access Service (SLAS). To correct your SLAS configuration, see the instructions in [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md).

## See Also

- [Build and Customize](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/build-customize.md)

<!-- document id=f10eee0210838ade9d4317da0893fb7f9da195dc53c3b4e30de636335d6a629c url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/setting-up-oauth-with-retail-cloud-apis.md -->

# Setting Up OAuth with Point of Sale APIs

Point of Sale supports OAuth for secure authentication with [APIs and SPIs](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html). Configure the OAUTH-OAuth SPI by entering the required URL, client secret, and headers. This setup allows the system to obtain an authentication token before making any other SPI calls.

## CMS Configuration and Setup

To configure OAuth authentication for Point of Sale APIs, set up the OAUTH-OAuth SPI connector in CMS and then configure your individual SPIs to use the generated authentication tokens. The process involves two main steps: first establishing the OAuth connection, then applying it to your specific API integrations.

### Configuring OAUTH-OAuth SPI

1. In CMS, go to Integrations > Custom Connectors.
2. Click **Create**.
3. For Connector Type, select **SPI**.
4. For Endpoint Name, select **OAUTH-OAuth**.
5. Update the API Endpoint to add `grant_type=client_credentials`. For example, `https://interdev.my.sf.com/services/oauth2/token?grant_type=client_credentials`.
6. Set the Integration Type to `HTTP_POST`.
7. Specify the authorization key using the JSON Headers.
   1. Retrieve the Client ID and Client Secret from the external API.
   2. Generate a Base64 concatenated Client ID and Client Secret, with a colon (:) and a single space.
   3. Add this string to the JSON Headers.

```json
{
  "Content-Type": "application/x-www-form-urlencoded",
  "Authorization": "Basic M01WRzlGSU5PMW5zeFJ1QVRUODVIOEVzMVZ5eUhWemNFd1BmQ0dkZnNSQlhVQUJlSjJ2YXFDSE00cG9vd2k2c2tZQnZiN2xqLkl0ZnQ0ZTVacXNQbTogQjg1MjFBNEFFMjZBMzJERDQwOTZDMzlCODJCN0UyQjhEQjRBNUIxMjU3MUEwQUYwQjlBREM3Qjg5OTEyQTBEQQ=="
}
```

**note:** - Include a space after the word `Basic` (don't include a colon).
- Generate the basic token by concatenating the Client ID and Client Secret with a colon and space. For example, `client_id: client_secret`.

![mceclip0.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip0-icon.png)

#### Example SPI Response

```json
{
  "token_type": "Bearer",
  "expires_in": 3600, //Optional field - Number of seconds this key will be present in cache for subsequent SPI calls
  "access_token": "*****" // Token sent as part of the header in other SPI requests.
}
```

### Configuring SPIs with OAuth

1. In CMS, go to **Integrations > Custom Connectors**.
2. Click **Create** in the upper right.
3. For Connector Type, select **SPI**.
4. For Endpoint Name, select an SPI. For example, **SHIPPING_METHOD**.
5. Navigate to the OAuth Config settings.
6. Set the OAuth Header to the header of your choice.
7. Set the OAuth API Key to either `OAuth` or `OAUTH`.
8. Configure the rest of the required fields.
9. Save your changes.

![mceclip3.png](https://developer.salesforce.com/docs/media/retail-cloud/mceclip3.png)

#### Example SPI Request with Headers

```json
{
  "httpHeaders": {
    "Authorization": "Bearer *****",
    "Content-Type": "application/json"
  }
}
```

<!-- document id=d74f6546e3345c490a5fb3e93cc1f5e1484af1dc753e03b8ebdaa9bd7a5c70c4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jdbc/jdbc_access_guide.md -->

# Setting Up the B2C Commerce Intelligence JDBC Driver

This section describes how to configure your JDBC driver and connect it to the B2C Commerce Data Warehouse. The B2C Commerce Data Warehouse is a centralized data repository that stores and organizes B2C Commerce transactional data, customer interactions, and business metrics in a structured format optimized for analytics and reporting. It serves as the foundation for the Commerce Intelligence JDBC Driver, providing access to pre-aggregated business data through standardized SQL queries.

The data warehouse contains:

- Fact tables (for example, line items, orders, payments, inventory snapshots)
- Dimension tables (for example, products, customers, sites, dates, geographies)
- Aggregate tables (for example, daily sales summaries, search analytics, promotion performance)

This architecture enables business users to perform complex analytics on e-commerce data, supporting use cases like sales analytics, customer behavior analysis, inventory optimization, and marketing campaign effectiveness measurement.

## Roles and Permissions

1. **Account Setup**: Your current account typically has the necessary permissions to access data using the JDBC driver. No additional roles are required.
2. **Role**: Salesforce Commerce API
3. **Tenant Filter**: To authenticate successfully, you must add the appropriate tenant filter. Specify multiple tenant IDs as needed.

## Download and Install the Driver

The Commerce Intelligence JDBC Driver enables seamless connectivity to your B2C Commerce data warehouse through a JDBC interface, ensuring compatibility with various SQL editors and data visualization tools.

### Download Options

There are **two ways** to download the Commerce Intelligence JDBC Driver:

#### 1. From GitHub

Download the latest version directly from the [Salesforce Commerce Cloud GitHub Repository](https://github.com/forcedotcom/salesforce-commerce-intelligence-jdbc). For detailed installation steps, refer to the `README` file in the repository.

**note:** Authentication steps may be required to access the repository. This documentation will be updated with detailed instructions on how to authenticate and download the driver.

#### 2. As a Maven Dependency

Include the driver as a Maven dependency in your Java project. This is helpful if you're building a custom application and want to manage dependencies via Maven.

Add the following to your `pom.xml`:

```xml
<dependency>
    <groupId>com.salesforce.commerce.intelligence.jdbc.client</groupId>
    <artifactId>cip-client-dataconnector</artifactId>
    <version>[VERSION]</version> <!-- Replace with the latest version -->
</dependency>
```

Find the latest version on [Maven Repository](https://mvnrepository.com/artifact/com.salesforce.commerce.intelligence.jdbc.client/cip-client-dataconnector).

For demonstration purposes, this document uses **DBeaver** as an example SQL editor. However, the Commerce Intelligence JDBC Driver is compatible with any JDBC-compliant tool, such as SQL Workbench, DataGrip, or custom Java applications.

## Using the Driver in DBeaver

To use the driver in DBeaver:

1. Open DBeaver.
2. Go to **Database → Driver Manager**.
3. Click **New**.
4. Enter the Driver Name (for example, "CommerceIntelligenceDriver").
5. Specify the Driver Class: `com.salesforce.commerce.intelligence.jdbc.client.CIPDriver`.
6. Add the Driver JAR:
   1. Click the **Libraries** tab.
   2. Click **Add File**, and select the driver JAR file you downloaded.
   3. Click **Find Driver**.
7. Click **OK**.
8. Create a database connection:
   1. Navigate to **Database → New Database Connection**.
   2. Select the driver you registered and click **Next**.

## Connection Properties

**note:** Use the JDBC Driver connection to access analytics data used for Reports and Dashboards. It doesn't establish a connection to your B2C commerce instance or to Business Manager, and it can't be used to modify your live site.

The following properties must be configured to connect to your B2C Commerce data warehouse:

| Property     | Description                                                                                                                                                                                                             | Type   | Required | Example                                                                                  |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| **JDBC URL** | Specifies the B2C Commerce database connection string, including the target instance. Replace the `{your_instance_id}` placeholder with your actual TenantId, which uniquely identifies your tenant's data environment. | String | Yes      | `jdbc:salesforcecc://jdbc.analytics.commercecloud.salesforce.com:443/{your_instance_id}` |
| **Username** | The Client ID provided by your Account Manager.                                                                                                                                                                         | String | Yes      | `your-client-id`                                                                         |
| **Password** | The Client Secret provided by your Account Manager.                                                                                                                                                                     | String | Yes      | `your-client-secret`                                                                     |

## Connecting to Non-Production Environments

Starting with B2C Commerce release 26.1, the B2C Commerce Intelligence JDBC Driver supports connections to non-production B2C Commerce environments. Supported non-production instances include:

- On-demand sandboxes (ODS)
- Development instances
- Staging instances
- Production instances in designated test realms (realms not serving live traffic)

### Enable Non-Production Access

To use the JDBC driver with a non-production instance, turn on the **Enable Reports & Dashboards Data Tracking** feature switch in Business Manager. For instructions, see [Set Feature Switches (Toggles) in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_feature_switches.htm&type=5). After turning on the feature switch, wait up to 2 hours for provisioning to complete.

### Non-Production JDBC URL

For non-production environments, use the non-production JDBC URL instead of the production URL:

| Environment    | JDBC URL                                                                                     |
| -------------- | -------------------------------------------------------------------------------------------- |
| Production     | `jdbc:salesforcecc://jdbc.analytics.commercecloud.salesforce.com:443/{your_instance_id}`     |
| Non-Production | `jdbc:salesforcecc://jdbc.stg.analytics.commercecloud.salesforce.com:443/{your_instance_id}` |

Replace `{your_instance_id}` with your actual instance identifier (for example, `bjnl_dev` or `bjnl_stg`).

**note:** The Real-Time Performance dashboard and Einstein Dashboard data aren't available for non-production instances.

## Java Example: Using the JDBC Driver

Use the Commerce Intelligence JDBC Driver directly in your Java applications. The following sample code demonstrates how to connect and query your B2C Commerce data:

```java
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

public class JDBCExample {
    public static void main(String[] args) {
        String jdbcUrl = "jdbc:salesforcecc://jdbc.analytics.commercecloud.salesforce.com:443/bjnl_prd"; // Replace with your actual JDBC URL
        String username = "your-client-id"; // Replace with your Client ID
        String password = "your-client-secret"; // Replace with your Client Secret

        try {
            // Load the JDBC driver explicitly
            Class.forName("com.salesforce.commerce.intelligence.jdbc.client.CIPDriver");

            try (Connection connection = DriverManager.getConnection(jdbcUrl, username, password)) {
                System.out.println("Connection established successfully!");

                String query = "SELECT * FROM your_table_name"; // Replace with your actual query
                try (PreparedStatement preparedStatement = connection.prepareStatement(query);
                     ResultSet resultSet = preparedStatement.executeQuery()) {

                    while (resultSet.next()) {
                        System.out.println("Column 1: " + resultSet.getString(1));
                        System.out.println("Column 2: " + resultSet.getString(2));
                        // Add more columns as needed
                    }
                }
            }
        } catch (ClassNotFoundException e) {
            System.err.println("JDBC Driver not found. Ensure the Commerce Intelligence Driver JAR is in the classpath.");
            e.printStackTrace();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

## Best Practices

Keep these best practices in mind when issuing queries to B2C Commerce.

1. Use an index column with your queries to make sure performance is optimal.
2. Rewrite your query against an aggregate table whenever possible because queries that target aggregate tables are significantly faster.
3. Never run queries like `SELECT * FROM <TABLE>` against tables with thousands of rows.
4. Design data extraction by using incremental processing techniques to retrieve data from large datasets in multiple batches. Primary keys generated with sequence numbers allow for incremental extraction of data.
5. Avoid `SELECT *` in JDBC queries. List only the columns you need so that queries remain stable when table schemas change.
6. Use `LOWER()` to normalize search terms in SQL and make results match SFCC dashboards.

## Non-Functional Requirements (NFR)

The following non-functional limits and behaviors apply when using the B2C Commerce Intelligence connector. Review these carefully to avoid unexpected errors or interruptions:

### Query Execution Timeout

- Queries have a maximum execution time of **30 minutes**.
- Any query exceeding this limit will be automatically terminated.
- To avoid timeouts, optimize your queries using indexing, aggregations, and batching techniques.

### Case Sensitivity

- SQL queries are **case-sensitive**.
- Make sure all **table and column names match the exact casing** used in the schema documentation.

### Quota Limit

- Download up to **25 GB of data per day** through the JDBC driver.
- The quota **resets daily at 12:00 AM UTC**.
- Once the limit is reached, further queries will be blocked until the quota resets.

### Rate Limit

- Execute up to **10 queries per minute**.
- Each query that returns **more than 450,000 rows** will count as **multiple queries** toward this limit.
- For example, a query that returns 900,000 rows will count as 2 queries.
- If you exceed the rate limit, additional queries will be temporarily throttled.

## Sample Queries

Here are some sample queries:

```sql
--
-- Sales Trend Query
--
SELECT
 "submit_date",
 SUM("num_orders") AS orders,
 SUM("num_units") AS units,
 SUM("std_revenue") AS gmv,
 SUM("std_total_discount") AS discounts,
 SUM("std_shipping") AS shipping,
 SUM("std_tax") AS tax
FROM
 "ccdw_aggr_sales_summary"
WHERE
 "submit_date" between ? AND ?
GROUP BY "submit_date"
ORDER BY "submit_date" DESC
```

```sql
---
--- Geography Analysis (Shipping Region)
---
SELECT
 g."region_name" AS region,
 SUM(quantity) AS units
FROM
 "ccdw_fact_line_item" AS li,
 "ccdw_dim_geography" AS g
WHERE
 li."shipping_geography_id" = g."region_id" AND
 li."utc_submit_timestamp" between ? AND ?
GROUP BY g."region_name"
```

```sql
---
--- Top Search Terms (Conversion)
---
SELECT
 sc."query" AS query,
 SUM(sc."num_searches") AS searches,
 SUM(sc."num_orders") AS search_orders,
 SUM(sc."std_revenue") AS search_gmv
FROM
 "ccdw_aggr_search_conversion" sc
WHERE
 sc."search_date" between ? AND ?
GROUP BY sc."query"
ORDER BY 2 DESC
```

## Frequently Asked Questions

**Why do my custom queries give different results than the standard CC Reports and Dashboards (CCAC) reports?**

When analyzing search data, you might see discrepancies when comparing results from the data warehouse tables accessed via the JDBC driver and reports viewed in CC Reports and Dashboards (CCAC). If you attempt to reproduce a specific CCAC report metric using a direct table query, be aware that your results might not align with the dashboard figures due to underlying proprietary logic. We recommend using established table definitions for custom reporting while acknowledging that reproducing proprietary dashboard metrics isn't supported.

**Is there any difference in data availability (time) in Reports and Dashboards vs via JDBC driver?**

No. Data will be available at the same time in Reports and Dashboards as well as JDBC driver.

**Do you plan to make more data available for access through JDBC driver?**

Yes, more information will be shared closer to release time.

<!-- document id=2a1672304a0e365e3628266ae5176b46fcb93a69746f5bf12bd1e6fa093f3297 url=/developer/current/en-us/commerce-cloud/sfra/guides/sfra-feature-list.md -->

# SFRA Features

This document contains list of features available and supported by the Storefront Reference Architecture on the B2C Commerce platform.

## Homepage, Header, Footer and Global Navigation

| ID  | Feature                                                                        |
| --- | ------------------------------------------------------------------------------ |
| 1.1 | Header                                                                         |
| 1.2 | Global Navigation                                                              |
| 1.3 | Footer                                                                         |
| 1.4 | Tracking Consent                                                               |
| 1.5 | Cookie Notification                                                            |
| 1.6 | Homepage - content slots, product tiles, product quickview, email sign-up form |

## Search Suggestions | Search Results | Article Detail | Search Refinements

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">2.1</td>
<td colspan="1" rowspan="1">Search Suggestions (Search as you type - SAYT)
<ul>
  <li>Dynamic search list automatically shown when search term is typed in search field</li>
  <li>Support to display Einstein Predictive Search results</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2.2</td>
<td colspan="1" rowspan="1">Search Results with no Products
<ul>
  <li>Did you Mean in case of mis-spellings</li>
  <li>Search tips</li>
  <li>Display content slot with pre-configured product recommendations</li>
  <li>Support to display Einstein powered product recommendations on Search</li>
  <li>No Results page</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2.3</td>
<td colspan="1" rowspan="1">Search Results with Products</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2.4</td>
<td colspan="1" rowspan="1">Search Results with Articles (Unstructured Content)</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2.5</td>
<td colspan="1" rowspan="1">Article Detail Page</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2.6</td>
<td colspan="1" rowspan="1">Search Refinements</td>
</tr>
<tr>
<td colspan="1" rowspan="1">2.6.1</td>
<td colspan="1" rowspan="1">Search Refinements with Single-Select and Multi-Select</td>
</tr>
</tbody>
</table>

## Category Landing | Category Grid | Product Tile

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">3.1</td>
<td colspan="1" rowspan="1">
<div>Category Landing page</div>

<div>The Category Landing template can be configured in Business Manager when the category attribute <code>rendering template</code> is set to <code>rendering/category/catLanding</code>.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">3.2</td>
<td colspan="1" rowspan="1">Category Grid</td>
</tr>
<tr>
<td colspan="1" rowspan="1">3.3</td>
<td colspan="1" rowspan="1">Product tiles on Category and Search Results pages</td>
</tr>
<tr>
<td colspan="1" rowspan="1">3.4</td>
<td colspan="1" rowspan="1">
<div>Product Title - Pricing</div>

<div>Single, 2-Tier and Range Pricing all supported</div>
</td>
</tr>
</tbody>
</table>

## Compare Products

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">4.1</td>
<td colspan="1" rowspan="1">Compare Bucket
<ul>
<li>Add items to the compare bucket for side-by-side product attribute comparison</li>
<li>Applies to Category Grid pages, but not to Search pages.</li>
<li>Product sets and bundles are not comparable.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">4.2</td>
<td colspan="1" rowspan="1">Compare Products
<ul>
<li>Select &amp; display up to four products to compare.</li>
<li>When fewer than four are selected, the width of each item expands.</li>
</ul>
</td>
</tr>
</tbody>
</table>

## Product Detail Pages

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">5.1</td>
<td colspan="1" rowspan="1">Product Detail page (PDP)
<ul>
<li>Display product attributes and information including images</li>
<li>Size chart</li>
<li>Add to cart</li>
<li>Add to wishlist/registry (if applicable)</li>
</ul>
<b>Note</b>: Product Images, Description, and Size Chart either based on primary category or product attribute.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.1.1</td>
<td colspan="1" rowspan="1">Standard Product Detail page</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.1.2</td>
<td colspan="1" rowspan="1">
<div>Product Option Detail</div>

<div><b>Note</b>: Product Option isn&rsquo;t a stand alone page, this is a feature of a product to associate options with a product.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.1.3</td>
<td colspan="1" rowspan="1">Variation Product Detail page</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.2</td>
<td colspan="1" rowspan="1">Product Detail w/ limited inventory message</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.3</td>
<td colspan="1" rowspan="1">Product Detail w/ Price Display and Promotion Callouts</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.4</td>
<td colspan="1" rowspan="1">Product Detail w/ Bonus Products</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.5</td>
<td colspan="1" rowspan="1">Product Sets Detail page</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.6</td>
<td colspan="1" rowspan="1">Product Bundles Detail page</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.7</td>
<td colspan="1" rowspan="1">
<div>Einstein Product Recommendations</div>

<div>Support to display Einstein powered product recommendations on product detail page for cross-sells and upsells</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">5.8</td>
<td colspan="1" rowspan="1">Product Detail with In-store inventory
<ul>
<li>Support to display in-store inventory information if available in Business Manager</li>
<li>Shopper needs to select SKU and Store information to view available inventory</li>
</ul>
</td>
</tr>
</tbody>
</table>

## Quickview Capabilities

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">6</td>
<td colspan="1" rowspan="1">Quickview
<ul>
<li>Display a module window when a shopper clicks the Quickview icon within a product grid.</li>
<li>Add to cart.</li>
</ul>
<b>Note</b>: Quickview is not designed to support Mobile devices.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">6.1</td>
<td colspan="1" rowspan="1">Quickview: Standard Product detail</td>
</tr>
<tr>
<td colspan="1" rowspan="1">6.2</td>
<td colspan="1" rowspan="1">Quickview: Product Option detail</td>
</tr>
<tr>
<td colspan="1" rowspan="1">6.3</td>
<td colspan="1" rowspan="1">Quickview: Variation Product detail</td>
</tr>
<tr>
<td colspan="1" rowspan="1">6.4</td>
<td colspan="1" rowspan="1">Quickview: Product sets detail</td>
</tr>
<tr>
<td colspan="1" rowspan="1">6.5</td>
<td colspan="1" rowspan="1">Quickview: Product bundles detail</td>
</tr>
</tbody>
</table>

## In-Store Pickup (ISPU / BOPIS)

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">7</td>
<td colspan="1" rowspan="1">In-Store Pickup (ISPU)
<ul>
<li>Display in-store pickup on the Product Detail page</li>
</ul>
Configuration:

<ul>
<li>Install the <code>plugin_instorepickup</code> cartridge.</li>
<li>Assign an active inventory book to the store record.</li>
<li>Enable the product attribute <code>availableForInStorePickup</code>.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.1</td>
<td colspan="1" rowspan="1">ISPU: Product detail page with no saved store</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.1.1</td>
<td colspan="1" rowspan="1">ISPU: Store selection (Enter Zip code / Postal code)</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.2</td>
<td colspan="1" rowspan="1">ISPU: Product Detail page with saved store</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.3</td>
<td colspan="1" rowspan="1">ISPU: Cart page
<ul>
<li>For a store saved in the session, display store details such as name, address, and phone number.</li>
<li>If no store is saved in session, allow selection for Store Pickup in the Shipping Method options</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.4</td>
<td colspan="1" rowspan="1">ISPU: Shipping Address for Ship method selection with no saved store
<ul>
<li>If no store is saved in session, allow selection for Store Pickup in the Shipping Method options</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.5</td>
<td colspan="1" rowspan="1">ISPU: Shipping Address for Ship method selection with saved store
<ul>
<li>Display selected or saved store details such as name, address and phone number.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.6</td>
<td colspan="1" rowspan="1">ISPU: Billing Address w/ Payment method
<ul>
<li>Displays store details such as name, address, and phone number.</li>
<li>Allows shoppers to edit store selection, if required.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.7</td>
<td colspan="1" rowspan="1">ISPU: Place Order (Order Review) page
<ul>
<li>Displays store details such as name, address, and phone number.</li>
<li>Allows shoppers to edit store selection, if required.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.8</td>
<td colspan="1" rowspan="1">ISPU: Order Receipt (Order Confirmation) page
<ul>
<li>Displays ship method as &ldquo;Store Pick-up&rdquo; with store details such as name, address, and phone number.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.9</td>
<td colspan="1" rowspan="1">Order History page
<ul>
<li>Displays store pick up details</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">7.10</td>
<td colspan="1" rowspan="1">ISPU: Order Detail page
<ul>
<li>Displays ship method as &ldquo;Store Pick-up&rdquo; with store details such as name, address, and phone number.</li>
</ul>
</td>
</tr>
</tbody>
</table>

## Cart and Mini-Cart

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">8.1</td>
<td colspan="1" rowspan="1">Mini-Cart
<ul>
<li>Displays compact product details for item(s) added to cart.</li>
<li>Supports quick edit for item quantity.</li>
<li>Displays button to Proceed to Checkout and Apple Pay, if applicable.</li>
</ul>
<b>Note</b>: Mini-cart does not display on mobile devices.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">8.2</td>
<td colspan="1" rowspan="1">Cart: Empty cart page
<ul>
<li>Display empty Shopping Cart page when a shopper navigates to the cart page without any products added to cart.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">8.3</td>
<td colspan="1" rowspan="1">Cart: Product List and Order Summary
<ul>
<li>Display product attributes for items added to cart.</li>
<li>Display quick order summary details - order subtotal, tax, shipping costs and estimated total.</li>
<li>Supports Quickview functionality on desktop devices for edits to products in cart.</li>
<li>Add to wishlist.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">8.4</td>
<td colspan="1" rowspan="1">Cart: Coupon and Promotion Messaging
<ul>
<li>Display promotion messaging if the Cart qualifies for a product-level discount.</li>
<li>Display list price with a strikethrough with the promotion price shown underneath.</li>
<li>Allow shoppers to enter coupon/promotion codes for redemption.</li>
<li style="margin-left: 40px;">Update cart page with updated pricing based on applied promotion</li>
<li style="margin-left: 40px;">Display error message if coupon/promotion code is expired/invalid</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">8.4.1</td>
<td colspan="1" rowspan="1">Cart: Choice of Bonus product (Promotion)
<ul>
<li>Allow for selection of bonus product, if a shopper is eligible for a choice of bonus product promotion.</li>
<li>Select Bonus Product opens the the choice of bonus product window, and display selected bonus product in cart.</li>
<li>Bonus product is removed if the qualifying product is removed from cart.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">8.5</td>
<td colspan="1" rowspan="1">Einstein Product Recommendations
<ul>
<li>Support to display Einstein powered product recommendations on cart page for cross-sells and upsells.</li>
</ul>
</td>
</tr>
</tbody>
</table>

## Checkout (Registered & Guest)

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">9.1</td>
<td colspan="1" rowspan="1">Checkout - Login
<ul>
<li>Option to complete checkout as a guest or as a registered user.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">9.2</td>
<td colspan="1" rowspan="1">Registered Checkout: support checkout for registered customers
<ul>
<li>Use saved addresses from address book for billing &amp; shipping</li>
<li>Select shipping method</li>
<li>Use saved payment tender info from wallet for payment option</li>
<li>Complete order purchase, and save order details to My Account - Order History</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">9.3</td>
<td colspan="1" rowspan="1">Guest Checkout: support guest checkout for shoppers
<ul>
<li>Enter shipping and billing address information</li>
<li>Select shipping method</li>
<li>Enter payment information</li>
<li>Complete order purchase</li>
<li>Create (new) account from order receipt page and save order details to My Account - Order History</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">9.4</td>
<td colspan="1" rowspan="1">Update or Add New Shipping Address
<ul>
<li>Edit the shipping address information.</li>
<li>Add new shipping address.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">9.5</td>
<td colspan="1" rowspan="1">Update or Add New Billing Address
<ul>
<li>Edit the billing address information.</li>
<li>Add new billing address.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">9.6</td>
<td colspan="1" rowspan="1">Add Payment Method
<ul>
<li>Add payment tender information</li>
<li>Fields will dynamically update based on credit card type</li>
</ul>

<div><b>Note</b>: Payment Methods like PayPal, 3rd party Gift Cards/Certificates can be added via customization.</div>

<div><b>Note</b>: B2C Commerce eGift Certificates can be supported in SFRA via customization.</div>
</td>
</tr>
</tbody>
<tbody>
<tr>
<td colspan="1" rowspan="1">9.7</td>
<td colspan="1" rowspan="1">Multi-Ship Checkout
<ul>
<li>For multiple items in the cart, option to ship the products to multiple addresses.</li>
<li>Select Ship Method for each Shipping Address/Group.</li>
</ul>
<b>Note</b>: SFRA supports multi-ship checkout in the templates. Customers can choose to not enable multi-ship checkout.</td>
</tr>
</tbody>
</table>

## My Account Page

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">10.1</td>
<td colspan="1" rowspan="1">My Account - Login
<ul>
<li>Supports login with email address and password for registered users.</li>
<li>Supports new account creation with email address and password.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.1.1</td>
<td colspan="1" rowspan="1">My Account - Forgot Password
<ul>
<li>Ability to reset account password by entering account email address</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.2</td>
<td colspan="1" rowspan="1">My Account - Dashboard
<ul>
<li>Displays shopper&rsquo;s profile information with address book and order history, if available.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.3</td>
<td colspan="1" rowspan="1">My Account - Edit Profile
<ul>
<li>Edit account profile information including name, email, phone, and password.</li>
<li>Display error message when email/password and confirm email/confirm password fields do not match.</li>
<li>Additional profile information can be captured to be attached to the account via customization</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.4</td>
<td colspan="1" rowspan="1">My Account - Address Book
<ul>
<li>Ability to enter addresses to address book.</li>
<li>View addresses in address book and edit, if necessary.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.5</td>
<td colspan="1" rowspan="1">My Account - Payment Method
<ul>
<li>View existing payment method</li>
<li>Add new payment method</li>
<li>Remove existing payment method (*editing existing payment method is not supported).</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.6</td>
<td colspan="1" rowspan="1">My Account - Order History
<ul>
<li>Displays list of orders attached to the account</li>
<li>Ability to select individual orders to view additional order details</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.7</td>
<td colspan="1" rowspan="1">Check Order Status
<ul>
<li>Look up order status for guest users with order number, email address, and billing zip code/postal code.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">10.8</td>
<td colspan="1" rowspan="1">Social Login (Facebook, Google)
<ul>
<li>Supports login via Facebook and/or Google via 3rd party integration</li>
</ul>
</td>
</tr>
</tbody>
</table>

## Wishlist and Gift Registry

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">11.1.1</td>
<td colspan="1" rowspan="1">Wishlist
<ul>
<li>Ability to add item(s) to wishlist for registered users from PDP and Cart page.</li>
<li>View wishlist item(s) from Wishlist landing page.</li>
<li>Ability to remove item(s) from wishlist.</li>
<li>Update quantity for item(s) in wishlist.</li>
<li>Make wishlist private or public (default is private).</li>
<li>Ability to hide/unhide item(s) from public view.</li>
<li>Share wishlist via email or other social channels (3rd party integration required for social share).</li>
</ul>
Configuration:

<ul>
<li>Install the <code>plugin_wishlists</code> cartridge</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">11.1.2</td>
<td colspan="1" rowspan="1">Wishlist - Search
<ul>
<li>Ability to search for public wishlist(s) by entering first name, last name, and email address.</li>
<li>Display wishlist search results based on information entered based on public view settings.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">11.2.1</td>
<td colspan="1" rowspan="1">Gift Registry - Event
<ul>
<li>Create registry with attributes - primary registrant &amp; role, (using registered account user - first name, last name, email), event date, event name, city, state, and country.</li>
<li>Add co-registrant information - role, first name, last name, and email.</li>
<li>Enter shipping address for pre-event and post-event.</li>
<li>Make gift registry private or public (default is private).</li>
<li>Ability for registered users to have more than one gift registry.</li>
</ul>
Configuration:

<ul>
<li>Install the <code>plugin_giftregistry</code> cartridge.</li>
<li>Configure the footer content asset with a link to the controller route <code>GiftRegistry-Landing</code>.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">11.2.2</td>
<td colspan="1" rowspan="1">Gift Registry - Items
<ul>
<li>Ability to add item(s) to registry for registered users from PDP and Cart page.</li>
<li>View registry item(s) from registry landing page.</li>
<li>Ability to remove item(s) from registry.</li>
<li>Update quantity for item(s) in registry.</li>
<li>Ability to hide/unhide item(s) from public view.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">11.2.3</td>
<td colspan="1" rowspan="1">Gift Registry - Search
<ul>
<li>Ability to search for public registry by entering first name, last name (required) with event details and email address as optional.</li>
<li>Display registry search results based on information entered based on public view settings.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">11.2.4</td>
<td colspan="1" rowspan="1">Gift Registry - Management
<ul>
<li>Ability for registered users to have more than one gift registry.</li>
<li>Ability to remove/delete registry(ies).</li>
</ul>
</td>
</tr>
</tbody>
</table>

## **GDPR, Apple Pay, Cross-Cloud, Page Designer and Others**

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">12.1</td>
<td colspan="1" rowspan="1">GDPR
<ul>
<li>Support for GDPR guidelines for consent tracking, data deletion, data portability, and restriction of processing.</li>
<li>Support for shopper to provide or restrict consent tracking.</li>
<li>Support for shopper to download their own data (registered users only).</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">12.2</td>
<td colspan="1" rowspan="1">Apple Pay
<ul>
<li>Support for Apple Pay feature to be displayed on PDP, Mini-Cart, Cart page, and Checkout - Payment page.</li>
</ul>
Configuration:

<ul>
<li>Install the <code>plugin_applepay</code> cartridge.</li>
</ul>

<div><b>Note</b>: Requires 3rd party configuration and implementation.</div>

<div><b>Note</b>: Works on iOS &amp; MacOS devices w/ Safari browser only.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">12.3</td>
<td colspan="1" rowspan="1">Ratings &amp; Reviews
<ul>
<li>Support to display rating and reviews attached to products.</li>
</ul>
Configuration:

<ul>
<li>Install the <code>plugin_ratings</code> and <code>plugins_reviews</code> cartridge.</li>
</ul>
<b>Note</b>: Requires 3rd party configuration and implementation.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">12.4</td>
<td colspan="1" rowspan="1">Loyalty
<ul>
<li>Support to display customer loyalty information (for registered users only).</li>
</ul>
Configurations:

<ul>
<li>Install the <code>plugin_loyalty</code> cartridge.</li>
</ul>
<b>Note</b>: Requires 3rd party configuration and implementation</td>
</tr>
<tr>
<td colspan="1" rowspan="1">12.5</td>
<td colspan="1" rowspan="1">
<div>Cross Cloud Connectors</div>

<div>SFRA supports cross cloud connectors for Commerce &amp; Marketing and Commerce &amp; Service.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">12.6</td>
<td colspan="1" rowspan="1">
<div>Page Designer page layouts and components</div>

<div>Enable easier adoption of Page Designer through SFRA delivered Page Designer page layouts and components</div>

<p>Components available:</p>

<ul>
<li>Header</li>
<li>Main Banner / Hero Image</li>
<li>Shop Category</li>
<li>Catalog carousel</li>
<li>Campaign banner</li>
<li>Product Tile</li>
<li>Product Carousel - Einstein</li>
<li>Look Book / Sets</li>
<li>Photo tile</li>
<li>Static Content w/ Shop Link</li>
<li>Content Mix blocks</li>
</ul>
</td>
</tr>
</tbody>
</table>

## **Error Pages**

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">13.1</td>
<td colspan="1" rowspan="1">
<div>General (500) Error</div>

<div>Display error page for when server-side error occurs, but the server could not be more specific on what the exact problem is.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">13.2</td>
<td colspan="1" rowspan="1">
<div>Missing Page (404) Error</div>

<div>Display error page for when client side error occurs when the webpage the shopper is trying to reach could not be found on the server</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">13.3</td>
<td colspan="1" rowspan="1">
<div>Client Side Validation Error</div>

<div>Error message(s) displayed when shoppers does not provide required information or enters invalid data in form fields.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">13.4</td>
<td colspan="1" rowspan="1">
<div>Server Side Validation Error</div>

<div>Error message(s) displayed when shoppers submits a form but the data is invalid or does not match constraints.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">13.5</td>
<td colspan="1" rowspan="1">
<div>Coupon Code Error</div>

<div>Display appropriate error messaging for coupon code errors (expired or invalid).</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">13.6</td>
<td colspan="1" rowspan="1">
<div>Login Error</div>

<div>Display appropriate error messaging for login errors on My account or Checkout page.</div>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">13.7</td>
<td colspan="1" rowspan="1">Credit Card Error
<ul>
<li>Display error when shopper attempts to submit a form without completing the required fields.</li>
<li>Display error when shopper attempts to submit an invalid credit card number.</li>
<li>Display error when shopper attempts to submit an expired credit card number.</li>
</ul>
</td>
</tr>
<tr>
<td colspan="1" rowspan="1">13.8</td>
<td colspan="1" rowspan="1">
<div>Order Tracking Error</div>

<div>Display error when shopper attempts to submit an invalid order number and/or billing postal code that does not match order records.</div>
</td>
</tr>
</tbody>
</table>

## **General Features**

<table>
<thead>
<tr>
<th colspan="1" rowspan="1">ID</th>
<th colspan="1" rowspan="1">Feature</th>
</tr>
</thead>
<tbody>
<tr>
<td colspan="1" rowspan="1">14.1</td>
<td colspan="1" rowspan="1">Store Locator
<ul>
<li>Support store locator functionality</li>
<li>Display list of stores based on zip code, or city, state and selected radius</li>
<li>Display store attributes as maintained in Business Manager</li>
</ul>
<b>Note</b>: In order to use the Google Maps functionality, the Google Maps API Key must be configured in the Site Preference <code>google map api key</code>.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.2</td>
<td colspan="1" rowspan="1">
<div>Breadcrumbs</div>
Display navigation breadcrumbs based on clickpath or pre-set paths.</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.3</td>
<td colspan="1" rowspan="1">Localization</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.4</td>
<td colspan="1" rowspan="1">Contact Us Form</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.5</td>
<td colspan="1" rowspan="1">XML Sitemap for SEO</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.6</td>
<td colspan="1" rowspan="1">Meta Tags and Alt Image Tags for SEO</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.7</td>
<td colspan="1" rowspan="1">Robots.txt</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.8</td>
<td colspan="1" rowspan="1">Rate Limiting (Platform feature)</td>
</tr>
<tr>
<td colspan="1" rowspan="1">14.9</td>
<td colspan="1" rowspan="1">Adjust Bootstrap Configuration to Our Design</td>
</tr>
</tbody>
</table>

<!-- document id=0b97076821ba177f30a8e37c5857487a128689b177cdd62eea49753ca12fdadb url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-features-and-comps.md -->

# SFRA Features and Components

SFRA is carefully architected so that it's easy to use as a blueprint for your own storefront. Built-in features and components provide a range of options for customizing the site to meet your needs.

## SFRA Architecture

SFRA provides an `app_storefront_base` cartridge and a `server` module. A storefront site uses the SFRA base cartridge and overlay plugin, LINK, and custom cartridge functionality to create a cartridge stack. Define the order of the cartridge stack by configuring the cartridge path in Business Manager.

The base cartridge contains only the functionality common to most sites. Layer functionality over the base cartridge with plug-in cartridges, LINK cartridges, and custom code cartridges. B2C Commerce provides plug-in cartridges that provide other features, such as gift registries, Apple Pay, product comparisons, and middleware capability. LINK partners, such as PayPal and Bazaarvoice, provide LINK cartridges for third-party integrations. Create one or more custom cartridges to override portions of the base cartridge and customize the functionality and branding of your storefront site.

The `app_storefront_base` cartridge includes multiple models These models use the B2C Commerce script API to retrieve data from the platform for a functional area of the application, such as orders. The models then construct a JSON object that you can use to render a template.

The `server` module provides objects containing data from HTTP requests, responses, and session objects. The `server` module registers routes that map a URL to code that's executed when B2C Commerce detects the URL. It uses a modern JavaScript approach that is conceptually similar to NodeJS's [Express](http://expressjs.com/).

The `app_storefront_base` cartridge models and `server` module objects are guaranteed to be backward compatible between major point releases. The guarantee lets you adopt new features more easily and maintains a clear distinction between base and custom code, which can help you troubleshoot issues and adopt bug fixes.

**important:** Editing the `app_storefront_base` cartridge or `server` module voids the guarantee of backward compatibility and hinders feature and fix adoption. Instead, use B2C Commerce script methods to extend base cartridge functionality. The JSON objects created by the `server` module and the `app_storefront_base` models retain their structure and don't change properties between point releases. However, B2C Commerce reserves the right to change how these objects are created.

A typical cartridge stack includes several layers, as shown in this table:

| Layer   | Description                                                                                                                                                                                                                                                                                             | Tips                                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Custom  | Adds specific customizations for your brand and organization. Perform all customizations of the base, LINK, and product cartridges in custom cartridges for easy adoption of future features.                                                                                                           | Rename all custom cartridges with `app_custom_*` to make them easy to distinguish.                                               |
| LINK    | Adds third-party functionality to your site. Integrate features from LINK partners, such as payment providers and tax services.                                                                                                                                                                         | Import LINK partner data, such as tax tables or inventory feeds. See specific LINK cartridge documentation for more information. |
| Plug-in | Enhances the ecommerce capabilities provided by B2C Commerce or anyone else in the Salesforce community. Cartridges provided by B2C Commerce let you integrate (optional) products and features such as product compare and gift registry.                                                              | Plug-ins can create custom objects or data that are specific to a product or feature.                                            |
| Base    | Core functionality modified only by the B2C Commerce team or through contributions to GitHub. The core cartridge includes best-practice code for features used by most customers. In addition to the default features, the base cartridge contains features that can be configured in Business Manager. | Some of the features in the base cartridge are configured in Business Manager, such as pick up in store.                         |

The following graphic shows a typical cartridge stack:

![Diagram of a typical SFRA cartridge stack showing custom, LINK, plug-in, and base layers](https://developer.salesforce.com/docs/media/sfra/b2c_sfra_cartridge_stack.gif)

The cartridge path is always searched left to right, and the first controller or pipeline found with a particular name is used. This behavior allows cartridges earlier on the path to override the functionality of cartridges later on the path. The cartridge path for this stack is:

```
app_custom_mybrand:app_custom_mysite:LINK_bazaarvoice:LINK_wordpress:plugin_applepay:plugin_comparison:app_storefront_base
```

B2C Commerce provides demo data that lets you view and explore the base cartridge as a working site.

**note:** Though cartridge data is imported into B2C Commerce and used by the code in each cartridge, it isn't stored in the cartridge itself.

## Base Cartridge Architecture

We highly recommend that you do not modify `app_storefront_base`. Instead, create your own cartridge and add it as an overlay in the Business Manager cartridge path. Using an overlay cartridge lets you upgrade to a newer version of SFRA without having to manually cherry-pick changes and perform manual merges. You can still adjust your custom code, but the upgrade and feature adoption process is quicker and less painful.

```
storefront-reference-architecture
  dw.json //used to upload code
  package.json
  cartridges
    ├── app_storefront_base
        ├── client //client-side JavaScript and CSS
        │   ├── js
        │   └── scss
        ├── controllers // business logic for the application
        ├── forms
        ├── models //gets data from server and provides it as JSON objects
        ├── scripts //reusable functionality
        │   ├── cart
        │   ├── factories
        │   ├── helpers
        │   ├── payment
        │   └── search
        ├── static //static resources unlikely to change, such as branding images
        └── templates //ISML templates
            ├── default
            └── resources
                 ...

    ├── modules
        └── server
              ...
```

## The Modules Folder and the Server Module

A server module in the SFRA global `modules` folder provides the routing functionality for controllers. Every SFRA controller requires this module. Any JavaScript module included in the `modules` folder is globally available and can be required without a path in any controller or script.

The following example requires the `server` module in the `modules` folder.

```
var server = require('server');
```

The `modules` folder is a separate cartridge, so you can easily upload it to the platform. However, you don't have to include it on the cartridge path. For information on using the `server` module, see Extending the Base Cartridge Architecture.

**note:** Don't directly extend or customize the `server` module. If you customize it directly, B2C Commerce can't be held responsible for changes that are not backward compatible in future versions of SFRA.

However, if you want to extend or customize `server` module functionality, create your own module and place it in the `modules` folder. Require `server` module functions and extend them in your own module as you would any JavaScript function.

## ViewModels and Controllers

SFRA uses a variant of Model-View-Controller architecture. Controllers handle information from the user, create ViewModels, and render pages. The ViewModels request data from B2C Commerce, convert B2C Commerce script API objects into pure JSON objects, and apply business logic.

![Diagram of the SFRA Model-View-Controller architecture showing controllers, ViewModels, and page rendering](https://developer.salesforce.com/docs/media/sfra/b2c_sfra_mvc.gif)

A controller requests data from B2C Commerce and passes the returned objects to a ViewModel to be converted into a serializable JavaScript object.

A ViewModel differs from a standard B2C Commerce script object in the following ways.

- A B2C Commerce script object sometimes behaves like a Java object, not a JavaScript object, whereas a model is a serializable JavaScript object.
- A ViewModel provides the data to render pages in the application and often combines data from multiple B2C Commerce script objects.

**note:** ViewModels are also referred to simply as models, because that's the name of the folder where they are located in the application.

## Defining Endpoints

SFRA defines endpoints (URIs) with a `Controller-RouteName` syntax. Defining an endpoint depends on your controller's filename and the routes defined within it.

The syntax of your endpoint depends on the SEO options you choose for your site. When developing, you can use the B2C Commerce Standard URL Syntax without SEO options. This approach makes it easy to test your controllers.

<!--TODO: Fix link post migration -->
<!-- The syntax of your endpoint depends on the SEO options you choose for your site. When developing, you can use the [B2C Commerce Standard URL Syntax](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/search-engine-optimization/b2c-digital-url-syntax-without-seo.md) without SEO options. This approach makes it easy to test your controllers.
 -->

Example: Defining an Endpoint for Your Home Page

Suppose that you want to create an endpoint in B2C Commerce standard URL syntax that looks like the following:

```
http://www.mystore.com/on/demandware.store/​Sites-YourShopHere-Site/​EN_US/Home-Show
```

You create a `Home.js` module in the controller folder with the following code:

```
'use strict';

var server = require('server');    //the server module is used by all controllers
var cache = require('*/cartridge/scripts/middleware/cache');

server.get('Show', cache.applyDefaultCache, function (req, res, next) {  //registers the Show route for the Home module
    res.render('/home/homepage');      //renders the hompage template
    next();            //notifies middleware chain that it can move to the next step or terminate if this is the last step.
});

module.exports = server.exports();
```

The `Home-Show` route consists of the module name (`Home.js`) and the first parameter in the `server.get` function (`Show`).

## Defining Routes

The `server` module `use` function takes the `RouteName` of the function to execute as the first argument. SFRA provides two utility methods to call the `use` function (`server.get` and `server.post`) that make sure the URI is either a GET or POST request.

This functionality is different from many other frameworks, which define routes by overriding anchor functionality in the URI to define actions to execute.

## How Controllers Are Executed

When a request is made via a URI in the web browser, the last part of the endpoint specifies the `Controller-RouteName` to execute. In this example, the filename is `Page.js` and the route name is `Show`. The `Page.js` file must be stored in the `controllers` folder for B2C Commerce to recognize it as a controller.

```
http://www.mystore.com/on/demandware.store/Sites-YourShopHere-Site/EN_US/Page-Show
```

The B2C Commerce server executes the first controller in the cartridge path with the correct name. B2C Commerce recognizes both SiteGenesis JavaScript Controller (SGJC) and SFRA controllers as equal and doesn't prioritize one over the other. If no controller is found in the cartridge path, the server executes the first pipeline file found in the cartridge path. Because SFRA doesn't use pipelines, this pipeline is the first one found in a custom cartridge.

When the controller is located, all `require` statements at the beginning of the controller are executed. These statements must include a `require` for the `server` module. The `server` module is located in the `modules` folder, which is a peer of the `app_storefront_base` cartridge. Requiring the `server` module returns an empty `server` object.

The next line to be executed is the following:

```
module.exports = server.exports();
```

This line is present in all controllers. Calling `server.exports()` causes the server to register all functions in the controller that use the `server.get`, `server.post`, or `server.use` functions as routes. The server then executes the function whose first parameter matches the route name in the URI.

For example, if you assume the URI in the previous example that ends in `Page-Show`, B2C Commerce registers all functions in `Page.js` and then executes the `Show` function.

```
server.get('Show', locale, function (req, res, next) {
    res.render('/home/homepage');
    next();
});
```

## Rendering a JSON String

Suppose that this code is saved to a file named `Page.js`.

```
var server = require('server');
server.get('Show', function(req, res, next) {
    res.json({ value: 'Hello World'});
    next();
});
module.exports = server.exports();
```

The `Page.js` file creates a route for a URL.

```
http://sandbox-host-name/on/demandware.store/site-name/en_US/Page-Show
```

Whenever that URL is called, the provided function is executed and renders a page with the following `Content-Type` header:

```
Content-Type: application/json
```

The rendered page also includes the following body:

```
{ value: 'Hello World '}
```

## Protecting Route Access

Enhance this code by adding the `server.middleware.https` parameter after `Show`, to limit this route to only allow HTTPS requests. This example restricts the `Account-Show` route to HTTPS.

**note:** This function is one of the middleware functions provided by B2C Commerce.

```
server.get('Show', server.middleware.https, function (req, res, next) {
    var accountModel = getModel(req);
    if (accountModel) {
        res.render('account/accountdashboard', {
            account: accountModel,
            accountlanding: true
        });
    } else {
        res.redirect(URLUtils.url('Login-Show'));
    }
    next();
});
```

**note:** Information about middleware filtering classes is available in the SFRA JSDoc in the server-side global documentation for the `server` module.

## Using server.use, server.get, or server.post

For a`server.get` or `server.post` function, the first parameter is always the name of the route (the URL endpoint). The last parameter is always the main function for the endpoint. Usually, the main function in the controller renders a page for the storefront or redirects to another controller.

Add as many parameters in between the first and last parameter as you want. Each parameter specifies a function to be executed in order and can let the next step be executed (by calling `next()` or reject a request by calling `next(new Error())`.

Example 1: Conditionally Executing a Middleware Step

This example shows a main function that conditionally executes `next()`or `next(new Error())` depending on whether an Apple Pay order is being placed.

```
server.post('Submit', function (req, res, next) {
    var order = OrderMgr.getOrder(req.querystring.order_id);

    if (!order && req.querystring.order_token !== order.getOrderToken()) {
        return next(new Error('Order token does not match'));
    }

    var orderPlacementStatus = orderHelpers.placeOrder(order);

    if (orderPlacementStatus.error) {
        return next(new Error('Could not place order'));
    }

    var orderModel = orderHelpers.buildOrderModel(order);
    res.render('checkout/confirmation/confirmation', { order: orderModel });
    return next();
});
```

The code executed between the first and last parameter is referred to as _middleware_ and the entire process is called _chaining_. Create middleware functions to limit route access, add information to the data object passed to the template for rendering, or for any other purpose. One limitation to this approach is that you must call the `next` function at the end of every step in the chain. Otherwise, the next function in the chain is not executed.

## Middleware

Each step of a middleware chain is a function that takes three arguments: `req`, `res`, and `next`, in that order.

`req`

This argument is short for `Request`. It contains information about the server request that initiated execution. The `req` object contains user input information, such as the content-type that the user accepts, the user's login and locale information, or session information. The `req` argument parses query string parameters and assigns them to the `req.querystring` object.

`res`

This argument is short for `Response`. It contains functionality for outputting data back to the client. For example:

- `res.cacheExpiration(24)`: Sets cache expiration to 24 hours from now.
- `res.render(templateName, data)`: Outputs an ISML template back to the client and assigns `data` to `pdict`.
- `res.json(data)`: Prints a JSON object back to the screen. It's helpful in creating AJAX service endpoints that you want to execute from the client-side scripts.
- `res.setViewData(data)`: Doesn't render anything, but sets the output object. This behavior can be helpful if you want to add multiple objects to the `pdict` of the template. The `pdict` contains the information for rendering that is passed to the template. `setViewData` merges all the data that you passed into a single object, so you can call it at every step of the middleware chain. For example, you can create a separate middleware function that retrieves information about a user's locale to render a language switch on the page. The output object of the ISML template or JSON is set after every step of the middleware chain is complete.

  Use the ViewData object to extend the data created in a controller that you are extending. You don't have to duplicate the logic used in the original controller to get the data. You only have to add the additional data to the ViewData object and render it.

`next()`

Executing the `next` function notifies the server that you are done with a middleware step so that it can execute the next step in the chain.

By chaining multiple middleware functions, you can compartmentalize your code and extend or modify routes without having to rewrite them.

## Event Emitters

The `server` module emits events at every step of execution and you can subscribe and unsubscribe to events from a given route. Use an event emitter to override the middleware chain by removing the event listener and creating a new one. However, if you have to change individual steps in a middleware chain, we recommend that you replace a route. While SFRA does supply `removeListener` and `removeAllListener` functions, they don't recognize named event emitters. For this reason, it isn't possible to use `Step` event emitters to override a specific step in the middleware chain.

The following is a list of currently supported events:

- `route:BeforeComplete` is emitted before the `route:Complete` event but after all middleware functions. Used to store user submitted data to the database; most commonly in forms.
- `route:Complete` is emitted after all steps in the chain finish execution. Subscribed to by the server to render ISML or JSON back to the client.
- `route:Redirect` is emitted before `res.redirect` execution.
- `route:Start` is emitted as before middleware chain execution.
- `route:Step` is emitted before execution of each step in the middleware chain.

All events provide both `req` and `res` as parameters to all handlers.

Subscribing or unsubscribing to an event lets you do complex and interesting things. For example, the server subscribes to the `route:Complete` event to render ISML back to the client. If you want to use something other than ISML to render the content of your template, unsubscribe from the `route:Complete` event. Subscribe to it again with a function that uses your own rendering engine instead of ISML, without modifying any of the existing controllers.

## OnRequest and OnSession Event Handlers

The `OnRequest` and `OnSession` event handlers that were implemented as pipelines in SiteGenesis Pipeline Processor (SGPP) and as controllers in SGJC are not used in SFRA. You still have access to request and session data using the middleware `req` (request) and `res` (response) objects. However, SFRA avoids using OnRequest and OnSession anywhere in our code outside of the `server` module.

If you want to implement `OnRequest` and `OnSession`, they must be implemented through hooks. B2C Commerce looks for `OnSession` as the controller name, but the new architecture doesn't do that. The only difference between a hook and controller is that the hook doesn't have access to the `req` and `res` objects.

## Extending Base Cartridge Architecture

B2C Commerce owns and maintains the `app_storefront_base` cartridge. The base cartridge is hosted on GitHub and anyone can contribute to it through a pull request. We test all pull requests before they are approved.

The `app_storefront_base` cartridge contains controllers for business logic, models with JSON objects populated from the B2C Commerce script API, and ISML templates. It also contains the `modules` directory with a `server` module for SFRA.

**note:** Anything in the `modules` folder or `TopLevel` package is globally available and can be required without a path. Add your own custom modules to the `modules` folder.

### Extension example Plugin_applepay

We provide a sample plugin cartridge as part of the SFRA project that demonstrates how to selectively add custom functionality to the base cartridge. Add this cartridge to the left of the base cartridge on the cartridge path to observe the functionality.

We publish an npm node named [sgmf-scripts](https://www.npmjs.com/package/sgmf-scripts). This node has tools to compile the CSS and scripts for your storefront site. Use the tools to create a CSS and client-side JavaScript that includes functionality from other cartridges.

## Best Practices for Storefront Reference Architecture Maintenance

Make sure to regularly update your `app_cartridge_base` and `server` module to have access to the most up-to-date security and bug fixes. Regularly updating your base cartridge.

<!-- document id=69639fedc7683c1d404b2fe0e88cef419e508e31bd69a3b3ba295aa930cb26d8 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-hooks.md -->

# SFRA Hooks

Use hooks to configure functionality to be called at a specific point in your application flow or at a specific event.

Use these hooks with a B2C Commerce storefront application:

- OCAPI hooks: B2C Commerce provides extension points to call scripts before or after specific OCAPI calls.
- Custom hooks: Define custom extension points and call them in your storefront code using the B2C Commerce script `System` package `HookMgr` class methods. Access the hook in either OCAPI or your storefront code. This flexibility makes them useful for functionality in a multichannel set of applications based on the same site.

For additional information, see:

- [Class HookMgr](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_system_HookMgr.html)
- [SFRA Hooks](https://developer.salesforce.com/docs/commerce/sfra/guide/b2c-sfra-hooks.html)

## Hook Definition

The `package.json` file points to the hook file for a cartridge, using the `hooks` keyword.

```
{
   "hooks": "./cartridge/scripts/hooks.json"
}

```

The hook file defines a uniquely named extension point and a script to run. Implement hook scripts as a CommonJS module. This approach ensures that the `script` identifier is a module identifier. The value of this identifier can be a relative path or any other valid module identifier.

### OCAPI Hook Example

`hook.json` file defines a `dw.ocapi.shop.basket.calculate`hook that calls the `calculate.js` script.

```
{
    "hooks": [
        {
            "name": "dw.ocapi.shop.basket.calculate",
            "script": "./hooks/cart/calculate.js"
        },
        {
            "name": "app.payment.processor.default",
            "script": "./hooks/payment/processor/default"
        },
        {
            "name": "app.payment.processor.basic_credit",
            "script": "./hooks/payment/processor/basic_credit"
        },
        {
            "name": "app.validate.basket",
            "script": "./hooks/validateBasket"
        }
    ]
}

```

This example shows an OCAPI hook and several custom hooks. The OCAPI hook runs a script to calculate the cart in the `scripts/hooks/cart` directory. If you use the System package `HookMgr` class `callHook` method, you can call the custom hooks. These hooks are located subdirectories of the `scripts/hooks` directory.

### Custom Hook Example

This example calls the hook from calculate.js.

```
return dw.system.HookMgr.callHook('app.payment.processor.default', 'Handle', {
            Basket : cart
        });

```

## Running Multiple Hooks for an Extension Point

In a single `hooks.json` file, you can register multiple modules to call for an extension point. However, you can't control the order in which the modules are called. If you call multiple modules, only the last hook returns a value. All modules are called, regardless of whether any of them return a value.

At run time, B2C Commerce runs all hooks registered for an extension point in all cartridges in your cartridge path. Hooks are executed in the order their cartridges appear on the path. Each cartridge can register a module for the same hook. Modules are called in cartridge-path order for all cartridges in which they are registered.

**note:** Hooks are executed in the order of the cartridges on the path. Therefore, when you change the order of the cartridges, you also change the order of hook execution.

## Error Logging

Controller and script logging is available.

- Custom error log: Contains the hierarchy of controller and script functions and the line numbers related to exceptions thrown. Intended for developers to debug code.
- System error log: Primarily used for B2C Commerce Support.

### Example: Custom error log

```
Error while executing script 'test_cartridge_treatascustom/cartridge/controllers/TestController.js': Wrapped com.demandware.beehive.core.internal.template.ServletAbortException: Requested template 'controller/testController' not found! (test_cartridge_treatascustom/cartridge/controllers/TestController.js#21)
    at test_cartridge_treatascustom/cartridge/controllers/TestController.js:21 (isml)
    at test_cartridge_treatascustom/cartridge/controllers/TestController.js:52 (anonymous)

```

<!-- document id=6a6065444af3a270b3c07f6cb9931d1a374009a69418b7e59e63f3c45896546f url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-modules.md -->

# SFRA Modules

Access JavaScript/B2C Commerce script modules that conform to the Modules 1.1.1 CommonJS specification within your storefront script code.

For information about the Modules 1.1.1 CommonJS specification, see [Modules 1.1.1](http://wiki.commonjs.org/wiki/Modules/1.1.1).

- [CommonJS Modules and Require](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sfra-modules.md#commonjs-modules-and-require)
- [ImportPackage vs. Require](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sfra-modules.md#importpackage-vs-require)

## CommonJS Modules and Require

Use CommonJS modules to share reusable functionality. Multiple controllers can reuse the same module.

A module is a `.ds` or `.js` file. You put module files either in the special `modules` folder or in a cartridge’s `script` folder.

The `modules` folder is a peer of cartridge folders. B2C Commerce provides it for globally shared modules, such as third-party modules.

```
+-- modules
    +-- mymodule1.js
+-- My_Cartridge_1
    +-- cartridge
        +-- scripts
            +-- mymodule2.js
+-- My_Cartridge_2
    +-- cartridge
        +-- scripts
            +-- mymodule3.js

```

Access modules in your cartridge, in other cartridges, or in the `modules` folder.

Storefront Reference Architecture (SFRA) provides a `server` module in the modules folder. This name is reserved for this module and editing the `server` module voids any promise of backward compatibility or support from B2C Commerce.

## Accessing Modules

B2C Commerce supports CommonJS `require` syntax to access modules and relative paths.

Use this syntax:

| Syntax | Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Example                                            |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| ~      | Specifies the current cartridge name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `require ('~/cartridge/scripts/cart')`             |
| .      | Specifies the same folder (as with CommonJS).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `require('./shipping');`                           |
| ..     | Specifies the parent folder (as with CommonJS).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `require('../../util')`                            |
| \*/    | Searches for the module in all cartridges that are assigned to the current site from the beginning of the cartridge path. The search is done in the order of the cartridges in the cartridge list. This notation makes it easier to load modules for a logical name. You don't have to remember what cartridge is the first in the cartridge path for a site to contain the module. For example, you can have multiple plug-in cartridges that each have a copy of the module. This syntax lets you add new plug-ins and always use the module that is first in the cartridge path. | `var m = require('*/cartridge/scripts/MyModule');` |

## ImportPackage vs. Require

Use `ImportPackage` statement to import B2C Commerce packages into scripts used by pipeline script nodes.

However, we recommend that you use `require` to import B2C Commerce script packages instead of `ImportPackage`. For example: `require(‘dw/system/Transaction’)`

**important:** Using the `require()` function to load a module has an impact on performance. To handle a request, a controller is loaded and then executed on a _global level_, just as exported methods are executed. When the controller module is initialized, the actual controller function is invoked.

If the dependencies to other modules are initialized on a global level, many modules can be loaded unnecessarily. If possible, place `require()` statements in the most limited scope that is appropriate (for example, as local variables within a function body). If your `require()` statements are placed at a global level, they are loaded for every request. For example, `require()` statements at the top of a controller file are loaded with each request. Globally required modules are loaded even if they are not needed in the current execution context.

If all modules execute their `require()` statements globally, all modules are loaded for every request. This overhead can significantly degrade performance, depending on the number of modules. We suggest, instead, that you move the `require()` calls for non-API modules into the function bodies so that they are resolved only when necessary. A `require()` isn't an import; it's a real function call. An import in Java, in contrast, is only a compiler directive and has no effect at run time.

## Understanding Cartridge Path Inheritance for Controllers and Pipelines

When a request arrives for a specific URL:

1.  B2C Commerce searches the cartridge path for a matching controller. If the controller is found, it's used to handle the request.
2.  If no controller is found, the cartridge path is searched again for a matching pipeline. If the pipeline is found, it's used to handle the request.

**note:** If a cartridge contains a controller and a pipeline with a matching name, the controller takes precedence.

When searching the cartridge path, B2C Commerce doesn't verify whether the controller contains the called function in the requesting URL. Calling a controller function that doesn't exist causes an error.

The platform simply searches the `controllers` folder. Therefore, it doesn't matter what type of cartridge contains the controllers. They can be in a SiteGenesis JavaScript Controllers (SGJC) cartridge or a Storefront Reference Architecture (SFRA) cartridge.

## Inheriting and Overriding Modules in Your Cartridge Stack Using Module.SuperModule

Often, you can have several layers of cartridges that overlay one another. Each cartridge can import from the previous cartridge and overlay it. To make this easy, B2C Commerce provides a chaining mechanism that lets you access modules that you intend to override.

The `module.superModule` global property provides access to the most recent module on the cartridge path module with the same path and name as the current module.

![Diagram showing how module.superModule accesses the most recent matching module in the cartridge path](https://developer.salesforce.com/docs/media/sfra/b2c_sfra_super_module.gif)

B2C Commerce searches cartridges after the current cartridge on the site cartridge path. It searches for a module with the same name and in the same location in the cartridge as the current module. B2C Commerce skips cartridges before the current cartridge in the path, and it skips the current cartridge, and only searches cartridges after the current cartridge. It continues searching through all the remaining cartridges in the cartridge path until a matching module is found. If no matching module is found, `module.superModule` returns `null`.

**note:** To create a module that inherits from an existing module, create the existing module in your cartridge and require it in your new module. For example, suppose that you want to create a home page for a specific customer group, named `BigSpenderHome.js`. To create the homepage, first create `Home.js` in your cartridge. Next, modify it to include (require) the functionality of `Home.js` from your cartridge stack.

### Example: Overriding and Extending an Existing Controller

This example shows how the Page.js module is inherited from the last cartridge in the stack and overrides the Show function. Specifically, it changes the data model used to render the page to show _Hello B2C Commerce._

```
//Page.js
var page = module.superModule; // require functionality from last controller in the chain with this name
var server = require('server');

server.extend(page);

server.append('Show', function(req, res, next) {
    res.setViewData({ value: 'Hello B2C Commerce' });
    next();
});

module.exports = server.exports();
```

## SuperModule Scenarios

For example, suppose that you are modifying the `Page.js` file, and it defines a `page` variable using the `module.superModule` property:

```
//Page.js
var page = module.superModule;
```

The `Page.js` file is located in the folder `mysite/cartridges/cartridge_B/cartridge/controllers`.

Suppose that you have the following cartridge path:

```
cartridge_A: cartridge_B: cartridge_C: cartridge_D: app_storefront_base
```

B2C Commerce searches the path starting with `cartridge_C`.

| If:                                                                                                                                                      | The platform returns:                                                                                  |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| All cartridges contain a `Page.js` file in the same location as `cartridge_B`.                                                                           | `cartridge_C module` `Page.js` module- because it's the next cartridge after `cartridge_B` in the path |
| `cartridge_A` and `cartridge_D` contain a `Page.js` file in the same location as `cartridge_B`.                                                          | `cartridge_D module` `Page.js` module - because it's after `cartridge_B` in the path                   |
| Only `cartridge_A` contains a `Page.js` file in the same location as `cartridge_`B.                                                                      | `null` - because `cartridge_A` isn't after cartridge_B in the path                                     |
| All cartridges contain a Page.js file in a different location than cartridge_B.                                                                          | `null` - because none of the files match the location of the file in the current cartridge.            |
| `cartridge_C` contains a `Page.js` file in a different location and app_storefront_base contains a `Page.js` file in the same location as `cartridge_B`. | `app-storefront_base` `Page.js` module - because the files must match name and location.               |

The power of the `module.superModule` mechanism is that it lets you chain overlay cartridges on top of one another. For example, if `cartridge_C` and `cartridge_D` both use the `module.superModule` function and both add functionality, all of that functionality is available to `cartridge_B`.

**important:** Chaining depends on an expected order of cartridges in the site cartridge path. Therefore, changing the order of cartridges in the cartridge path can impact your code. To minimize code changes, think about the order of your cartridge layers in advance.

## Global Modules

Make a script globally available by adding it to the `modules` folder. We recommend that you add the script to the `storefront-reference-architecture` repository’s `modules` folder. We recommend a single `modules` directory in one repository per site. This approach makes upload work in a predictable manner. The `uploadCartridge` tool deletes the existing `modules` folder before upload, and the `upload` tool doesn't identify or prevent naming collisions when uploading files.

<!-- document id=cdd50061e2f1bae959d57a6e25b5a170ae44ec0c5779edea433af14d0bd916b6 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-features.md -->

# SFRA Standard and Optional Features

SFRA implements standard features in the base cartridge and optional features in overlay cartridges.

Many features are implemented in the `app_storefront_base` cartridge. These features are considered standard. For example, the consent tracking feature is considered standard.

Optional features are typically implemented in overlay plugin cartridges. For example:

- `plugin_applepay`: implements the Apple Pay feature.
- `plugin_commercepayments`: implements functionality for payment integration with Stripe.
- `plugin_datadownload`: implements a **Download My Data** button, which gives shoppers a way to [download their data](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sfra-download-pi-data.md).
- `plugin_giftregistry`: implements gift registry functionality.
- `plugin_reviews`: implements a product review feature.
- `plugin_ratings`: implements product ratings feature.
- `plugin_instorepickup`: implements an order online and pickup in store feature.
- `plugin_productcompare`: implements a product compare feature.
- `plugin_sitemap`: implements a sitemap feature.
- `plugin_wishlists`: implements wishlist functionality.
- `plugin_ordermanagement`: implements Salesforce Order Management self-service.

<!-- document id=e745958ef5b7c9fbb6ce32903a499a2ccd5f013e6a20921a462e726a2050b442 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-standards-compliance.md -->

# SFRA Standards Compliance

SFRA supports standard industry technologies and browsers.

## Bootstrap

Storefront Reference Architecture (SFRA) uses [Bootstrap 5](https://getbootstrap.com/). Bootstrap was selected because of its wide adoption in the technical community.

For browser support: the latest version of Firefox, Chrome, Safari, and Edge.

For mobile devices: Android, iPhone, and iPad.

## Salesforce B2C Commerce

SFRA requires B2C Commerce Release 17.5 or later, due to the new script APIs used in the application.

## Desktop Browsers

SFRA officially supports the two latest versions of the following browsers:

- Edge
- Safari (MacOS)
- Firefox
- Chrome

## Mobile and Table Browsers

SFRA officially supports the following devices:

- Android phone-only Chrome is supported on Android devices.
- iPhone-only Safari is supported
- iPad-only Safari is supported

## Cookies Notification; Opt in for European Cookie Law

European Cookie Law requires websites to notify customers that cookies are being used and how. The SFRA application uses an optional content asset, called `cookie_hint,` to contain this notice.

| If this asset is ... | Then ...                                                                                                                                                   |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Missing or offline   | No notice is given. The cookies are set as they always have been. This approach is used in the USA, for example.                                           |
| Present and online\* | The `cookie_hint` content asset is used to show a notification: "Cookies are in use on this site." To proceed, the customer must dismiss the notification. |

## SFRA and Web Content Accessibility Guidelines (WCAG)

The Web Content Accessibility Guidelines (WCAG) provide a single shared standard for web content accessibility that meets the needs of individuals, organizations, and governments internationally. WCAG documents explain how to make web content more accessible to people with disabilities. See [http://www.w3.org/WAI/intro/wcag](http://www.w3.org/WAI/intro/wcag).

**important:** While B2C Commerce attempts to conform to Level AA test standards, compliance with WCAG is the sole responsibility of the merchant.

The WCAG guidelines followed were:

- Level A: 2.4.4 Link Purpose (In Context)
- Level AAA: 2.4.9 Link Purpose (Link Only)

The previous title-related corrections to SFRA use technique H33 ([http://www.w3.org/TR/2014/NOTE-WCAG20-TECHS-20140916/H33](http://www.w3.org/TR/2014/NOTE-WCAG20-TECHS-20140916/H33)). The link text is supplemented with the title attribute to add more context. This extra context makes it easier for people with disabilities to determine the purpose of the link.

<!-- document id=0d71aa8c6aec64fba47ecb12e755d2b96a034980d44b8f13e48c246f3ba3ac09 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-testing-sfra.md -->

# SFRA Testing Technologies

Include integration, unit, and functional tests in your SFRA development process.

Supported testing technologies include these kinds of tests:

- Controllers are tested with integration tests. Salesforce B2C Commerce uses mocha, chai, and request-promise for integration testing.
- Models are tested with unit tests. B2C Commerce uses mocha, chai, sinon, and proxyquire for unit tests.
- Views are tested with functional tests. B2C Commerce uses mocha, chai, and webdriver.io for functional tests.

## Testing Commands

Use these commands:

| Command                          | Description                                   |
| -------------------------------- | --------------------------------------------- |
| `npm run cover`                  | Runs unit tests with a coverage report.       |
| `npm run test`                   | \* Runs all SFRA unit tests.                  |
| `npm run test:appium`            | \* Runs functional tests for mobile devices.  |
| `npm run test:integration`       | \* Runs the integration tests.                |
| `npm run test:functional`        | Runs the functional tests in the browser.     |
| `npm run test:functional:docker` | Runs the functional tests from inside docker. |
| `npm run test:functional:sauce`  | Runs the remote functional tests              |

**note:** - These commands require a `dw.json` file or extra command-line parameters.

<!-- document id=8fdc7e8d9ada5159981092a2eb20a66f99ffd5ce27428e165a1d6b23f3c18879 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-sfra-versions.md -->

# SFRA Versions and Releases

Choosing a specific SFRA version ensures that your base cartridge and plugin cartridges work well together. In GitHub, some versions are labeled as releases, and others are labeled as pre-releases. Releases are stable; pre-releases might be unstable.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Version Numbers in SFRA

SFRA version numbers follow the semantic versioning pattern. Semantic versioning is used for all SFRA product repositories on GitHub. In semantic versioning, there are major versions, minor versions, and patch versions.

### Version Number Format

Each major version represents a version that is not backwards-compatible with previous versions. Each minor version represents new functionality and features that are backwards-compatible within the major version. Each patch version contains bug fixes or patches that are backwards-compatible within each minor version.

SFRA version numbers have the following format:

v*\<major_version>*.\<_minor_version>_.\<_patch_version>_

For example: v3.3.0

### Repositories in an SFRA Version

This version number format applies to all SFRA GitHub product repositories, including the following:

- [lib_productlist](https://github.com/SalesforceCommerceCloud/lib_productlist)
- [plugin-applepay](https://github.com/SalesforceCommerceCloud/plugin-applepay)
- [plugin_datadownload](https://github.com/SalesforceCommerceCloud/plugin_datadownload)
- [plugin_giftregistry](https://github.com/SalesforceCommerceCloud/plugin_giftregistry)
- [plugin_instorepickup](https://github.com/SalesforceCommerceCloud/plugin_instorepickup)
- [plugin_productcompare](https://github.com/SalesforceCommerceCloud/plugin_productcompare)
- [plugin_sitemap](https://github.com/SalesforceCommerceCloud/plugin_sitemap)
- [plugin_wishlists](https://github.com/SalesforceCommerceCloud/plugin_wishlists)
- [plugin_ordermanagement](https://github.com/SalesforceCommerceCloud/plugin_ordermanagement)
- [storefront-reference-architecture](https://github.com/SalesforceCommerceCloud/storefront-reference-architecture)
- [storefrontdata](https://github.com/SalesforceCommerceCloud/storefrontdata)

## Git Tags in SFRA Repositories

SFRA versions have matching Git tags. For example, SFRA version v3.3.0 corresponds to the Git tag v3.3.0. All SFRA product repositories are tagged separately but follow the same pattern. After cloning the SFRA product repositories, fetch the tags for each repository, list the tags, and check out the same version tag for each repository to make sure you are using the same version everywhere.

### Fetching Git Tags

For each SFRA product repository, fetch all the tags before listing them or checking them out. Fetch the tags using the following command:

```
git fetch --tags
```

After fetching the tags, list them using the `git tag` command.

### Listing Git Tags

List the tags for an SFRA repository as follows:

```
git tag
```

For example, issuing the `git tag` command against the plugin-applepay repository produces the following output (this output changes over time as tags are added):

```
v1.0.0
v2.0.0
v2.1.0
v3.0.0
v3.1.0
v3.2.0
v3.3.0
```

### Checking Out Git Tags

Check out a Git tag using the following command:

```
git checkout {\<tag>}

```

For example:

```
git checkout v3.3.0
```

When you check out a tag, Git displays a message similar to the following:

```
Note: checking out 'v3.3.0'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b <new-branch-name>

HEAD is now at 274a5ee7... 3.3.0
```

Use the suggested command to create a branch from the tag. For example:

```
git checkout -b my3_3_0
```

Work in the branch you created, knowing that it matches the specified version (in this example, v3.3.0).

Repeat this process for all SFRA product repositories that you want to include in your project.

## SFRA Releases in GitHub

The SFRA base repository (storefront-reference-architecture) is continually updated regularly, and each incremental update corresponds to a new version, but only some correspond to releases.

### GitHub Release Labels

Development occurs on the integration branch of the base repository, and code changes are merged from the integration branch onto the main branch. Once merged, these incremental changes are considered a new version (and are tagged using a corresponding Git tag). However, only some versions are fully tested against the full suite of SFRA plugin repositories and deemed stable. These fully tested, stable releases are labeled as releases in GitHub. Other versions are labeled as pre-releases. For all versions, once the base repository is tagged, all other SFRA product repositories are tagged with matching tags.

When you view the SFRA base repository in GitHub, you can click the **releases** tab to view releases. For example:

![SFRA GitHub repository releases tab showing release and pre-release version labels](https://developer.salesforce.com/docs/media/sfra/b2c_sfra_git_hub_label.png)

Here, the v3.3.0 tag is labeled as the 'Latest Release.' This label indicates that the v3.3.0 version is fully integration-tested with other product plugins and is considered stable. It further indicates that you can check out the v3.3.0 tag not only for the base storefront-reference-architecture repository, but also for other SFRA plugin repositories (for example, plugin-applepay, plugin_wishlist, plugin_ordermanagement, and so on).

### Pre-Release Labels

If a storefront-reference-architecture tag is labeled as 'Pre-release' in GitHub, the version has not been integration-tested with other SFRA product plugins and might be unstable. A pre-release version is compatible within its major and minor versions, as is standard for semantic versioning, but it might be unstable.

### Releases and Branches

Within SFRA repositories, branches can be updated and commits can be pushed without being tagged. Nothing prevents you from checking out the main branch of any SFRA repository. But unless you check out a tag, you cannot be sure if the changes in the branch are compatible with other SFRA repositories. By checking out only tags that are labeled as releases, you can be confident that you are starting with a stable code base. You can also be confident that all like-tagged SFRA plugin repositories have been integration-tested against the base repository.

<!-- document id=d41e666af50b1157d8967fe394e2a2f01002286c9f11066b3aa732b4d35ff34d url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-components-references.md -->

# Shared Components

The following code summarizes the shared components that can be used for the `components` object in the API contract:

```yaml
components:
  securitySchemes:
    ShopperToken:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes: { list of available scopes }
        clientCredentials:
          tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token
          scopes: { list of available scopes }
    AmOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes: { list of available scopes }
        clientCredentials:
          tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
          scopes: { list of available scopes }
  parameters:
    siteId:
      name: siteId
      in: query
      description: The site of the current request.
      required: true
      schema:
        type: string
        minLength: 1
    locale:
      name: locale
      in: query
      description: The locale of the current request.
      required: false
      schema:
        type: string
        minLength: 1
```

After that, the individual entries can be reused at different places of the schema.

## Use of References

The OpenAPI specification allows the use of [JSON References](https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03) in schema files [as described here](https://spec.openapis.org/oas/v3.0.0#reference-object). This avoids defining objects multiple times at different places in the schema, leading to files that are smaller and easier to maintain.

**important:** Contrary to OAS, Custom APIs **_only allow local references_**, that is, references to objects defined in the same schema file. Specifically, only such references are possible:

- `$ref: '#/components/parameters/sampleParam'`

However, remote and URL references like these are not possible:

- `$ref: '../other_schema.yaml#/components/parameters/sampleParam'`
- `$ref: 'https://www.example.org/other_schema.yaml#/components/parameters/sampleParam'`

**Example:** Using the system query parameter `siteId` via a reference:

```yaml
components:
  parameters:
    siteId:
      name: siteId
      in: query
      description: The site of the current request.
      required: true
      schema:
        type: string
        minLength: 1
```

```yaml
paths:
  /customers:
    get:
      summary: Get loyalty information for customer
      operationId: getLoyaltyInfo
      parameters:
        - $ref: "#/components/parameters/siteId"
```

<!-- document id=53b31252964d0b56e8386a585fc877489dde186ea734a4601843960a2fb7d5f4 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/hybrid-auth-shared-setup.md -->

# Shared Hybrid Auth Setup (All Architectures)

Complete these steps regardless of your storefront architecture. They configure SLAS, Business Manager, and the platform features that Hybrid Auth depends on.

<!-- REVIEW(SME/SLAS team): Step 7 now follows sfnext-hybrid.md and sfnext-hybrid-ods.md, which both state that HTTPOnly True doesn't affect Storefront Next (it always sets HttpOnly=true regardless). The earlier "required for Storefront Next" wording was removed to resolve the cross-page contradiction. Still unverified and pending SME confirmation: (1) the "Starting with B2C Commerce version 26.7" gating on steps 7 and 11, and (2) the "set the cookie domain level requires HTTPOnly True" dependency. These claims aren't corroborated by PR #2378 (which added the domain-scope step with no version gate or dependency). Confirm, then align this hub, sfnext-hybrid.md, sfnext-hybrid-ods.md, sfnext-domain-cookie.md, and pwa-domain-cookie.md. -->

## Step 1: Set Up a SLAS Client

- Hybrid Auth supports both SLAS public and private clients. Create a SLAS client if you don't already have one. For details, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md).
- Starting with B2C Commerce version 26.6, Hybrid Auth supports the `x-slas-client-auth` header for private clients using Strict Client Auth. Use this header with `/login` and `/authorize` endpoints to pass client credentials directly.

## Step 2: Enable Session Bridging

- Update the scope of the SLAS client used for Hybrid Auth to include `sfcc.session_bridge`.
- Use the same client ID in Hybrid Auth and in your storefront application (Storefront Next, PWA Kit, or SFRA/SiteGenesis).

## Step 3: (Optional) Configure Third-Party IDP and Social Login

Starting with B2C Commerce version 25.8, Hybrid Auth supports Third-Party IDP and Social Login. Perform all third-party IDP interactions with SLAS, not Business Manager.

1. Create an OAuth client in the IDP's administration portal.
2. Use the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=Summary) or [SLAS Admin UI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md) to [configure the IDP](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-identity-providers.html) for a SLAS tenant. In the SLAS Admin UI, go to the **Idps** tab, select **Add Idp**, and add the SLAS callback URL as the **Redirect URL**, for example: `https://$SHORT_CODE.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/$IDP_NAME`.

   **note:** The IDP name in the SLAS Admin configuration is case sensitive and must match the OAuth Provider ID in SFRA/SiteGenesis.

   ![Hybrid Auth SLAS IDP name in Business Manager](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-slas-idp-name-setup.png)

3. Add the SFRA/SiteGenesis Login-OAuthReentry redirect URIs to the SLAS client ID in the SLAS Admin UI. For B2C Commerce v26.4 and later, separate multiple URIs with a pipe delimiter, for example: `https://<Site Host Name 1>/on/demandware.store/Sites-<Site Id>-Site/<locale1>/Login-OAuthReentry|https://<Site Host Name 2>/on/demandware.store/Sites-<Site Id>-Site/<locale2>/Login-OAuthReentry`.

   ![Redirect URI example](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-redirect-uri.png)

4. Add the SLAS callback URI in the IDP's administration portal, for example: `https://$SHORT_CODE.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/$IDP_NAME`.

   ![Hybrid Auth SLAS callback URI in Business Manager](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-slas-callback-uri.png)

## Step 4: Configure Business Manager

1. In Business Manager, go to **Merchant Tools**.

   1. Select a site that matches your setup, for example: `RefArch`, `RefArchGlobal`, or `SiteGenesisGlobal`.
   2. In the quick-find box, search for "hybrid auth" and select **Hybrid Auth Settings**. For B2C Commerce version 25.10, the Business Manager interface was updated. If you're using a version earlier than 25.10, the options differ slightly.

      ![Hybrid Auth Setup in Business Manager](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-business-manager-settings2.png)

   3. Enable the **Hybrid Auth** toggle.
   4. Enter your SLAS client ID (public or private).
      - For a public client, select the **Is Public Client** checkbox.
      - For a private client, enter your SLAS private client secret.
   5. Enable the **Shopper Context** toggle to use Shopper Context features with Hybrid Auth.
   6. Enable the **Do-Not-Track Synchronization** toggle to use DNT sync with Hybrid Auth.
   7. (Recommended) Starting with B2C Commerce version 26.7, turn on **HTTPOnly True** to enhance cookie security. When enabled, Hybrid Auth cookies are set with the `HttpOnly` flag, which prevents client-side JavaScript from accessing them. Turn this on if you set the cookie domain level (step 11). This toggle doesn't affect Storefront Next, which always sets its cookies with `HttpOnly=true` regardless of this setting. For PWA Kit and other headless storefronts, HTTPOnly True is optional but recommended for security.

      - For hybrid storefronts using PWA Kit or another headless solution, coordinate this setting with your headless application. Make sure your PWA Kit or headless app is configured to work with `HttpOnly` cookies before you enable this toggle. For details, see [HttpOnly Mode: SLAS Property Storage Mapping](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/httponly-storage-mapping.md) in the _PWA Kit docs on GitHub_.
      - For SFRA, SiteGenesis, and Storefront Next storefronts, no additional setup is required.

      ![Hybrid Auth HTTP-only cookie setting](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-business-manager-httponly-setting.png)

   8. (Optional) If you enable a third-party IDP or Social Login in SFRA pages, set the Redirect URI. For B2C Commerce v26.4 and later, specify multiple Login-OAuthReentry endpoints separated by a pipe delimiter.

      ![Hybrid Auth Site Settings in Business Manager](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-site-settings-redirect-uri.png)

   9. (Optional) Starting with B2C Commerce version 25.8.1, to lower the guest refresh token TTL from the default 30 days, enter a value between 360 and 43200 (6 hours to 30 days, in minutes) in **Guest Refresh Token Cookie Override TTL**. Configure your storefront's guest refresh token cookie TTL to the same value.
   10. (Optional) Starting with B2C Commerce version 25.8.1, to lower the registered refresh token TTL from the default 90 days, enter a value between 360 and 129600 (6 hours to 90 days, in minutes) in **Registered Refresh Token Cookie Override TTL**. Configure your storefront's registered refresh token cookie TTL to the same value.
   11. (Optional) Starting with B2C Commerce version 26.7, set the domain scope for Hybrid Auth cookies. To scope cookies to the current host only, enter 0 for the cookie domain level. To share cookies across subdomains (for example, to share the cookie with `www.example.com` and `shop.example.com`), set the level to 2. If you set the cookie domain level, make sure you've also turned on **HTTPOnly True** (step 7).
       - If your storefront uses PWA Kit or Storefront Next, coordinate this setting with the corresponding cookie domain configuration in your headless application. For details, see [Hybrid Cookie Domain Configuration](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/hybrid-cookie-domain-configuration.md) in the _PWA Kit docs on GitHub_.
       - ![Hybrid auth cookie domain level setting](https://developer.salesforce.com/docs/media/commerce-api/hybrid-auth-cookie-domain-level.png)
   12. Click **Apply**.

2. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and select **Administration**.
   1. In the quick-find box, search for **Security**.
   2. Select the **Access Restriction** tab.
   3. Enable the **Enforce HTTPS** checkbox.
   4. Click **Apply**.

## Step 5: Remove Plugin SLAS (If Migrating)

With the migration to Hybrid Auth, Plugin SLAS is no longer required.

**note:** Complete these steps only if you previously used Plugin SLAS. If you have a new hybrid storefront and never used Plugin SLAS, skip this step.

1. Click App Launcher and select **Administration > Sites > Manage Sites > Select Site**.
2. Go to the **Settings** tab.
3. Remove `plugin_slas` from the cartridge path.
4. For code customizations:
   - Shopper authentication customizations that aren't specific to Plugin SLAS should continue to work as is.
   - Review Plugin SLAS-specific customizations, because they might not be required or might need to be re-implemented in a different cartridge.
   - Implement customizations in a separate cartridge instead of modifying out-of-the-box SFRA cartridge code.
   - Make sure none of your custom cartridge code calls session bridging endpoints. Hybrid Auth handles session bridging for you.

## Step 6: Remove OCAPI Permissions (If Migrating from Plugin SLAS)

Hybrid Auth is fully SCAPI-based and doesn't require OCAPI. If you're migrating from Plugin SLAS, remove OCAPI permissions for the client ID you use for Hybrid Auth to improve security and prevent configuration conflicts.

1. In Business Manager, go to **Administration > Site Development > Open Commerce API Settings**.
2. Remove your Hybrid Auth client ID from the OCAPI configuration.

**note:** If you need OCAPI access for other applications, use a different client ID. Never share a client ID between Hybrid Auth and OCAPI.

## Step 7: (Optional) Set Shopper Context

For Hybrid Auth, we recommend using [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) to drive geolocation-based personalization for promotions, customer groups, and region-specific content.

To maintain consistency across a hybrid storefront, use the same geolocation for both SCAPI and controller calls:

- Call Shopper Context with the `clientIp`.
- Set the `evaluateContextWithClientIp` query parameter to `true`. You must set `&evaluateContextWithClientIp=true` for the IP-related context features to work correctly.
- For example:

  ```http
  PUT https://<shortCode>.api.commercecloud.salesforce.com/shopper/shopper-context
  /v1/organizations/f_ecom_<tenantId>/shopper-context/<usid>
  ?siteId=<siteId>&evaluateContextWithClientIp=true

  {
      "clientIp": "73.4.153.145"
  }
  ```

For details, see [Shopper Context Guides](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md). You can also use the [Shopper Context Script API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html) to personalize shopper experiences for hybrid implementations that use SFRA/SiteGenesis pages.

## Step 8: (Optional) Enable or Disable Do-Not-Track Synchronization

To enable or disable DNT synchronization in Business Manager, go to **Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings**.

SFRA-only sites: the DNT value is automatically synchronized to the extended session, ensuring a seamless experience across sessions.

SFRA and PWA Kit hybrid implementations (new and existing): when you enable both Hybrid Auth and DNT synchronization, the tracking consent provided by a shopper on one site is automatically synchronized with the other site. For example, in a hybrid site where the home page runs on PWA Kit and the cart page runs on SFRA:

- On the home page (PWA Kit), the shopper is presented with a consent form and provides their tracking preference.
- When the shopper navigates to the cart page (SFRA), the DNT value from PWA Kit is synchronized with SFRA.
- As a result, the SFRA cart page does not prompt the shopper for tracking consent again.

SFRA and non-PWA Kit headless hybrid implementations (new and existing): leverage the DNT synchronization implemented in the platform provided that:

- SFRA uses the default DNT implementation. For details, see [Consent Tracking in SFRA](https://developer.salesforce.com/docs/commerce/sfra/guide/b2c-sfra-consent-tracking.html).
- Your non-PWA Kit headless solution implements DNT similar to PWA Kit. For details, see [Default Tracking Consent Implementation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/tracking-consent.html#default-tracking-consent-implementation).

If you customize the default DNT implementation, the default synchronization might not be required nor work as expected. In such cases, disable DNT synchronization using a site preference. You can still enable Hybrid Auth even if DNT synchronization is turned off.

### DNT Cookie Expiration

There is a key difference in DNT cookie expiration between SFRA and PWA Kit:

- SFRA sets the DNT cookie to expire at the end of the session.
- PWA Kit sets the expiration to match the refresh token's lifespan (for example, 30 days for guest users).

When a shopper moves from a PWA Kit page to an SFRA page, the DNT cookie's expiration changes from the refresh token's expiry to a session-based expiry. If the shopper closes the browser, the cookie is deleted. As a result, when the shopper returns, the tracking consent popup/banner is displayed again as expected.

## Next Steps

After you complete the shared setup, finish configuring Hybrid Auth for the storefront architecture you chose:

1. Follow the setup path for your architecture: [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-quick-start.md) (Storefront Next only) or [Manual Setup](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-manual-setup.md) (all other architectures).
2. Review per-environment differences and route ownership in [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-environment-matrix.md).
3. Resolve issues with [Hybrid Auth Troubleshooting](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-troubleshooting.md).

<!-- document id=d1fc87ba5564865f02e99baeb2ece7e1abe0f4bf3269a353fa1a822cd78a0cf7 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/multiple-shipments.md -->

# Ship Products to Multiple Addresses and Stores in a Single Order

With the Retail React app template in PWA Kit v3.12 and later, enable multiple shipments in one order to give shoppers greater flexibility in choosing their order fulfillment options in the cart and the checkout page. For example, a shopper can order gifts for multiple recipients with different addresses in the same order. If in-store pickup is also enabled, shoppers can choose to pick up products from different stores in the same order, in addition to specifying multiple shipping addresses. For example, a shopper can send items to themselves to the locations they're traveling to, such as a home address, a hotel, and pick up items at store locations in different cities. This feature provides convenience and a faster checkout experience by avoiding the placement of separate orders for each recipient and shipment type.

## Prerequisites

- Build your site with:
  - The [Retail React app template](https://pwa-kit.mobify-storefront.com/)
  - Retail React App version 7.1.0 or later
  - Commerce SDK React version 4.0 or later

## Implement Multiple Shipments in Your App

1. By default, the multiple shipments feature is enabled in the Retail React app template, in addition to the in-store pickup feature. If multiple shipments isn't turned on in your app, set the `multishipEnabled: true` value in [config/default.js](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/packages/template-retail-react-app/config/default.js). This example shows the default configuration with both multiple shipments and in-store pickup features enabled.

```
   module.exports = {
    app: {
        ...
        storeLocatorEnabled: true,
        multishipEnabled: true
    },
```

2. (Optional) If in-store pickup isn't enabled in your cloned [pwa-kit GitHub repository](https://github.com/SalesforceCommerceCloud/pwa-kit/), and you want to enable it, follow the steps in [Expand Shopping Options with In-Store Pickup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/instore-pickup.html).

## Shipment and In-Store Pickup Options

To enable multiple options for both in-store pickup and shipments, you can enable the multiple shipment and the in-store pickup features. This table shows the shipping and pickup options you get when you enable or disable these features in all combinations.

| Multiple Shipments Enabled | In-Store Pickup Enabled | In a Single Order, Shoppers Can...                                             |
| -------------------------- | ----------------------- | ------------------------------------------------------------------------------ |
| Yes                        | Yes                     | Ship products to multiple addresses AND pick up products from multiple stores. |
| No                         | Yes                     | Ship products to one address OR pick up products from one store.               |
| Yes                        | No                      | Ship products to multiple addresses. No in-store pickup option.                |
| No                         | No                      | Ship products to one address. No in-store pickup option.                       |

## Constraints

- You can add shipments for up to 20 addresses.

<!-- document id=dcb19ae48e6223311a75eef484d1d0adcb09a05ddce149164bcbdaa48bd2d81f url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/shipment-spi.md -->

Shipment SPI

# Shipment SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipment-spi/shipment-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping options and shipping labels. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint.

**Version:** 2.3.4

## Tags

### Shipment Spi

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipment-spi/shipment-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping options and shipping labels. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint.

## Operations

### POST Retrieve shipping label.

`POST /merchant/spi/sample/endpoint/sa/shipping/to/get/shippingLabel/from/external/system`

Operation ID: `getShippingLabel`. Tags: Shipment Spi.

Retrieve shipping label from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SHIPPING_LABEL`
    *   **API Endpoint:** Provide the external endpoint
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the shipping label from an external system during BOFIS fulfillment or Inventory Transfer flows.

#### Request body

Media type: `application/json`. Schema: `ShipmentSpiRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ShipmentLabelSpiResponse`.
    

### POST Retrieve shipping options.

`POST /merchant/spi/sample/endpoint/sa/shipping/to/get/shippingOptions/from/external/system`

Operation ID: `getShippingOptions`. Tags: Shipment Spi.

Retrieve shipping options from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `SHIPPING_OPTIONS`
    *   **API Endpoint:** Provide the external endpoint
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the shipping options from an external system during BOFIS fulfillment or Inventory Transfer flows.

#### Request body

Media type: `application/json`. Schema: `ShipmentSpiRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ShipmentOptionSpiResponse`.
    

## Schemas

### ShipmentSpiRequest

*   `shipmentContext` (_string_, required) Shipment context. Provides the context of the request, indicating whether it is related to a BOFIS order or inventory transfer.  
    Allowed values: `ORDER`, `RETURN_TO_VENDOR`, `STORE_TO_STORE_TRANSFER`, `CORP_TRANSFER`.
*   `requestTime` (_integer (int64)_, required) Request time in epoch milliseconds.
*   `storeId` (_string_, required) ID of the store that fulfills the shipment.
*   `storeAssociateId` (_string_, required) ID of the store associate.
*   `orderId` (_string_) Order number of BOFIS order or inventory transfer.
*   `customerName` (_string_) Customer name.
*   `fromAddress` (_SPIAddress_, required)
*   `shippingAddress` (_SPIAddress_, required)
*   `store` (_Store_)
*   `packageDimension` (_PackageDimension_)
*   `itemWeight` (_number_) Total weight of all items in the package.
*   `items` (_array of ShipmentItem_) Items in the package.
*   `packageValue` (_number_) Cost of the package (item total).

### ShipmentLabelSpiResponse

*   `errorMessage` (_string_) Error Message.
*   `errorCode` (_string_) Error Code.
*   `shippingLabelLink` (_string_, required) Link to shipping label image. The image must be in PNG format.
*   `trackingNumber` (_string_) Tracking number corresponding to the shipping label link.
*   `shippingMethod` (_ShippingOption_, required)
*   `packageDimension` (_PackageDimension_, required)
*   `itemWeight` (_number_, required) Replay the provided item weight.

### ShipmentOptionSpiResponse

*   `errorMessage` (_string_) Error Message.
*   `errorCode` (_string_) Error Code.
*   `shippingMethodList` (_array of ShippingOption_, required) Shipping method options.

### SPIAddress

The full address of the destination of transaction.

*   `firstName` (_string_) Customer first name saved for address.
*   `lastName` (_string_) Customer last name saved for address.
*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.
*   `phone` (_string_) Phone.
*   `storeId` (_string_) Store ID if it is store address.
*   `emailAddress` (_string_) Customer Email Address.

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### PackageDimension

Dimension of package being shipped.

*   `length` (_number_, required) Length of the package.  
    Example: `12.2`.
*   `height` (_number_, required) Height of the package.  
    Example: `12.2`.
*   `width` (_number_, required) Width of the package.  
    Example: `12.2`.

### ShipmentItem

Items in the package.

*   `productId` (_string_) Product ID.
*   `quantity` (_integer (int32)_) Number of items.
*   `orderItemId` (_string_) Item sequence or system-generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `shippingMethodId` (_string_) Unique Identifier for the Shipping Method.
*   `shippingCarrier` (_string_) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.
*   `deliveryDate` (_integer (int64)_) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_) Expected delivery time slot.  
    Example: `09:00 - 12:00`.

### ShippingOption

Shipping method options.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.
*   `name` (_string_) Shipping Method Name.
*   `description` (_string_) Description.
*   `shippingCarrier` (_string_, required) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.
*   `serviceLevel` (_string_) Service-level description. This is shown on the POS app. For example, 3-5 Days, 1-Day, Express, Standard, Overnight.
*   `price` (_number_, required) Shipping Method Price.
*   `sortOrder` (_integer (int32)_, required) Display rank. Helps determine display sequence of shipping methods on screen. For example, a shipping method with display rank of 1 will be displayed beforea method with display rank 2 and so on.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

<!-- document id=1338592ce0340d7c45022cd5ee91281ff5b7123d9262d77800478f4aee6399a2 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-ship-tax-integration-container.md -->

# Shipping and Tax Integration

A single API call fetches both shipping and tax costs for cart items in B2B stores.

**note:** In the Winter ‘24 release, we introduced Commerce extensions for pricing, inventory, shipping, taxes, and other services. While the checkout integrations framework is still supported, we recommend extensions over integrations because they offer more targeted customizations for your B2B or B2C store. Plus, they’re available for more Commerce domains. See [Get Started With Salesforce Commerce Extensions](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/extensions.html).

## Shipping and Tax API

Because shipping and tax providers require the same inputs to make their respective calculations, a single API call fetches both shipping and tax costs for cart items.

An asynchronous shipping cost and tax API call to service providers is triggered when a shopper enters a shipping address.

![Diagram of shipping and tax integration.](https://developer.salesforce.com/media/d2c-commerce/shipping_tax_flow_2.png)

Here’s the structure of RetrieveDeliveryMethod, the triggering shipping and tax calculation API call.

```
{
   “id” : ID : // the cart delivery group id
   “deliveryMethods” :  DeliveryMethodCollectionRepresentation :
   “deliveryAddress” : AddressRepresentation : // selected delivery address
   “cartItems” : CartItemCollectionRepresentation :
}

```

Here’s a sample DeliveryGroupRepresentation.

```
{
   “id”:”2Dg456789012345678AAA”,
   "cartItems":{
       Total: 1,
       carItems:
       [
         {
           "cartItemId":"0a9456789012345678AAA",
           "productId":"01txx0000006i44AAA",
           "name":"shower bar",
           "listPrice":"29.95",
           "salesPrice":"20.00",
           "totalTax":"1.85",
           "totalAmount":"1",
           "totalPrice":"31.80",
           "totalAdjustmentAmount":"31.80"
         }
       ]
   },
   "deliveryMethods":{
     “total: 2”,
     “items” :
     [
       {
         "id":"2Dm456789012345678AAA",
         "shippingFee":14.00,
         "currencyCode":"USD",
         "carrier":"UPS",
         "classOfService":"Next Day Shipping",
         “timeOfArrival” : “2020-11-05T13:15:30Z”
         "selected":true
       },
       {
         "id":"2Dm123789012345678EAA",
         "shippingFee":9.00,
         "currencyCode":"USD",
         "carrier":"UPS",
         "classOfService":"Three Day Shipping",
         “timeOfArrival” : “2020-11-07T16:15:30Z”
         "selected":false
       }
     ]},
   "shippingAddress":{
      "AddressType":"Shipping",
      "City":"Boston",
      "Country":"USA",
      "Id":"81Wxx0000000001EAA",
      "IsPrimary":true,
      "Name":"Home Address",
      "PostalCode":"01234",
      "State":"MA",
      "Street":"1 Milk Street"
   }
}
```

## Shipping Reference Package

A reference shipping integration package supports both B2B Commerce implementations. You can use it as a template to create your own shipping calculation package.

Clone or download the [Shipping Reference Integration Package](https://github.com/forcedotcom/commerce-on-lightning/tree/main/examples/b2c/checkout/integrations) package.

## Tax Reference Package

A reference tax integration package supports both B2B Commerce and implementations. You can use it as a template to create your own tax calculation package.

Clone or download the [Tax Reference Integration Package](https://github.com/forcedotcom/commerce-on-lightning/tree/main/examples/b2c/checkout/integrations) package.

<!-- document id=0adc98bfdbf41d1b9ec4d2a2d097fcb110064caafb63d6997aead77735df0964 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-shipping.md -->

# Shipping Data Model

The Shipping data model aligns objects with relationships that support shipping calculation throughout the cart-to-checkout sequence.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the Shipping data model require at least one of the following licenses: B2B Commerce.

![Diagram of the Shipping Data Model](https://developer.salesforce.com/media/d2c-commerce/commerce_cloud_shipping_zh.png)

- [ShippingConfigurationSet](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_shippingconfigurationset.htm) (the shipping profile)
- [ShippingRateGroup](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_shippingrategroup.htm)
- [ShippingRateArea](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_shippingratearea.htm)
- [StandardShippingRate](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_standardshippingrate.htm)

<!-- document id=00093888f12bb3e756873ea86366bc3df2fc827cfd52c579c170a76d46af196d url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/shipping-method-spi.md -->

Shipping Method SPI

# Shipping Method SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipping-method-spi/shipping-method-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping methods with respect to items and shipping address of a particular cart. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint.

**Version:** 2.3.4

## Tags

### Shipping Method SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipping-method-spi/shipping-method-spi-oas-public.yaml)

Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping methods with respect to items and shipping address of a particular cart. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint.

## Operations

### POST Return applicable shipping methods.

`POST /merchant/spi/sample/endpoint/sa/shipping/methods`

Operation ID: `shippingMethods`. Tags: Shipping Method SPI.

Return applicable shipping options. This merchant-provided API takes in cart items that are marked for shipping or delivery, customerId, address, etc. as input and provides applicable shipping options. **Note:** Only the items marked for shipping or delivery are sent in the request. In-store or Pick Up Later items are not sent as part of this request.

#### Request body

Media type: `application/json`. Schema: `ShippingMethodsRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ShippingMethodsResponse`.
    

## Schemas

### ShippingMethodsRequest

*   `customerId` (_string_) Identifier of the customer associated with this cart.
*   `cartItemList` (_array of ShippingSPIProduct_, required) List of items in cart which require shipping to a particular address.

### ShippingMethodsResponse

*   `shippingMethods` (_array of ShippingMethod_) List of all shipping methods that can be applied to cart.

### ShippingSPIProduct

Details of an item available in the cart. Includes mandatory and optional item attributes. The optional attributes are provided only if they are configured with product field mapping. Product field mapping is available under **CMS** > **Feeds** > **Field Mappings** > **Products**. To learn more about field mapping, salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-field-mapping.html.

*   `productId` (_string_, required) Distinct product ID for each combination of variations, for example, size or color.  
    Example: `3661601595547`.
*   `title` (_string_, required) Product title.  
    Example: `E18PENDANT1`.
*   `description` (_string_, required) Product description.  
    Example: `Number 1 medallion`.
*   `productClass` (_string_, required) Product class of the item.  
    Example: `Merchandise`.
*   `categories` (_array of string_) Merchant categories of the product. A pipe-separated list of category names belongs to this product.  
    Items: Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`.
*   `googleCategory` (_string_) Product categories for Google search.  
    Example: `Accessories > Categories > Jewelry`.
*   `imageUrl` (_string_) Image url of the product.  
    Example: `https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html`.
*   `additionalImageUrls` (_array of string_) Additional image urls of the product.  
    Items: Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`.
*   `condition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`, `NEW, USED, REFURBISHED` . Example: `NEW`.
*   `availability` (_string_) Free text value that provides information about the availability of the product.  
    Example: `Available`.
*   `listPrice` (_number (double)_, required) Listing price of the product.  
    Example: `60`.
*   `salePrice` (_number (double)_, required) Sale price of the product. It can be same as listing price.  
    Example: `60`.
*   `storePrice` (_number (double)_) Store specific price of the product.  
    Example: `55`.
*   `currencyCode` (_string_) ISO currency code.  
    Default: `USD`. Minimum length: 3. Maximum length: 3. Example: `USD`.
*   `brand` (_string_) Product's brand.  
    Example: `Gucci`.
*   `gtin` (_string_) Product's GTIN. It can be one of UPC, EAN, JAN, ISBN, or ITF-14.  
    Minimum length: 12. Maximum length: 14. Example: `065100004327`.
*   `mpn` (_string_) Manufacturer part number.  
    Example: `100-440-0.750-3434-A`.
*   `gender` (_string_) Free text to provide gender related to the product.  
    Example: `Unisex`.
*   `ageGroup` (_string_) Free text to provide age group related to the product.  
    Example: `10-45`.
*   `subVariantGroupId` (_string_) Sub variant group id.
*   `variantGroupId` (_string_, required) Group id of the product. All the different variations of the product are grouped together under a single group id.  
    Example: `E18PENDANT1`.
*   `color` (_string_) Product color.  
    Example: `Silver`.
*   `colorSwatchUrl` (_string_) The image link for color swatches.
*   `size` (_string_) Product size.  
    Example: `M`.
*   `pattern` (_string_) Free text to provide the product pattern.  
    Example: `Oval`.
*   `sku` (_string_) SKU Id of the product. It can be same as product Id and unique per variation of the product.  
    Example: `3661601595547`.
*   `isOnSale` (_boolean_, required) Specifies whether the product is on sale.  
    Example: `false`.
*   `promotionTitle` (_string_, nullable) Promotion title applicable to the product.  
    Example: `Summer22`.
*   `promotionPrice` (_number (double)_, nullable) Discounted price after applying promotion corresponding to the promotion title.  
    Example: `55`.
*   `customString0` (_string_, nullable) Custom field of type String.
*   `customString1` (_string_, nullable) Custom field of type String.
*   `customString2` (_string_, nullable) Custom field of type String.
*   `customString3` (_string_, nullable) Custom field of type String.
*   `customString4` (_string_, nullable) Custom field of type String.
*   `customString5` (_string_, nullable) Custom field of type String.
*   `customString6` (_string_, nullable) Custom field of type String.
*   `customString7` (_string_, nullable) Custom field of type String.
*   `customString8` (_string_, nullable) Custom field of type String.
*   `customString9` (_string_, nullable) Custom field of type String.
*   `customString10` (_string_, nullable) Custom field of type String.
*   `customString11` (_string_, nullable) Custom field of type String.
*   `customString12` (_string_, nullable) Custom field of type String.
*   `customInt0` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customInt1` (_integer (int32)_, nullable) Custom field of type Integer.
*   `customDecimal0` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDecimal1` (_number (float)_, nullable) Custom field of type Decimal.
*   `customDateTime0` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `customDateTime1` (_integer (int64)_, nullable) Custom field of type Epoch time in millis.
*   `onlineInventory` (_integer (int32)_, nullable) The current online inventory. Provide a value if online inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `material` (_string_, nullable) Product material.  
    Example: `Metal`.
*   `manufacturer` (_string_, nullable) Manufacturer of the product.  
    Example: `ABC Jewellers`.
*   `sizeGuideUrl` (_string_, nullable) Image url of the size guide.
*   `manufacturerDetails` (_string_, nullable) Manufacturer details.
*   `manufacturerLocation` (_string_, nullable) Location of product manufacturer.
*   `productLocation` (_string_, nullable) Product manufacturing location.
*   `banner` (_string_, nullable) Banner text. If provided, it will be shown on PLP and PDP screens.
*   `availableStores` (_array of string_, nullable) List of stores where the product is available.
*   `lastUpdate` (_string (date-time)_)
*   `storeInventory` (_integer (int32)_, nullable) The current store inventory. Provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).
*   `isVirtual` (_boolean_, nullable) Specifies whether the product is available only in online mode (true) or not (false).
*   `multipleGTINs` (_array of string_, nullable) If the product supports multiple GTINs, provide all of them.
*   `storeProductDetails` (_StoreProductDetails_)
*   `onlineAvailableStores` (_array of string_, nullable) List of stores where online products are available.
*   `costPrice` (_number (double)_, nullable) Cost of per item.
*   `casePackQuantity` (_integer (int32)_, nullable) Number of items per case pack.
*   `additionalCharges` (_string_, nullable) Additional charges for CA, FR.
*   `casePackID` (_string_, nullable) Identifier for case pack.
*   `availabilityStartTime` (_string (date-time)_, nullable) Start time, when product is visible on POS.
*   `availabilityEndTime` (_string (date-time)_, nullable) End time, when product will not be visible on POS.
*   `price` (_number_, required) Unit price of this line item.
*   `quantity` (_integer (int32)_, required) Quantity of this line item.
*   `fulfillmentLocation` (_Store_, required)
*   `shippingAddress` (_SPIAddress_)
*   `deliveryDate` (_integer (int64)_) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_) Expected delivery time slot.  
    Example: `09:00 - 12:00`.

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### StoreProductDetails

Provide details about products in the store. This includes store-level inventory, store level pricing, store level promotions, etc. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).

*   `storeId` (_string_) Store or warehouse ID.
*   `productId` (_string_) Product ID.
*   `storeInventory` (_integer (int32)_) Product sellable quantity.
*   `storePrice` (_number_) Product price at the store.
*   `storePromoText` (_string_) Product promotion text applicable to this store.
*   `listPrice` (_number_) Product list price.
*   `salesPrice` (_number_) Product sale price.
*   `storePromoBanner` (_string_) Product promotion banner text.
*   `clearanceItems` (_array of ClearanceItem_) Product location within the store.
*   `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders.
*   `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity.
*   `quantityOnHand` (_integer (int32)_) Product quantity on hand.
*   `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store.
*   `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that isn't for sale.
*   `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that isn't for sale.
*   `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that isn't for sale.
*   `fullPriceSerialNumbers` (_array of string_) Full price serial numbers.
*   `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in store.
*   `customString0` (_string_) Custom string attribute of the product for the store.
*   `customString1` (_string_) Custom string attribute of the product for the store.
*   `quantity` (_integer (int32)_)

### Store

Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here.

*   `storeId` (_string_, required) Store ID field to be provided by app.
*   `name` (_string_, required) Store name.
*   `addressLine1` (_string_, required) Store Address Line1.
*   `addressLine2` (_string_, nullable) Store Address Line2.
*   `city` (_string_, required) City.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code.
*   `countryCode` (_string_, required) Country Code.
*   `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID.
*   `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone.
*   `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax.
*   `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours.
*   `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude.
*   `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude.
*   `storeType` (_string_, nullable) Store type.  
    Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`.
*   `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID.
*   `storeGroupID` (_string_)

### SPIAddress

The full address of the destination of transaction.

*   `firstName` (_string_) Customer first name saved for address.
*   `lastName` (_string_) Customer last name saved for address.
*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.
*   `phone` (_string_) Phone.
*   `storeId` (_string_) Store ID if it is store address.
*   `emailAddress` (_string_) Customer Email Address.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### ClearanceItem

Product location within the store.

*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `clearancePrice` (_number_)
*   `itemLocationWithinStore` (_string_)
*   `instructionText` (_string_)

### Hours

Store's operational hours. Mandatory if the store is configured in CMS with operational hours.

*   `day` (_string_)
*   `open` (_string_)
*   `close` (_string_)

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

<!-- document id=89ae11ee5370751cc265c8b366a1b54d214f4c2b8497d078b6d8944d734b4995 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-baskets.md -->

Shop Baskets (deprecated)

# Shop Baskets (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Create basket

`POST /baskets`

Operation ID: `Create basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Creates a new basket. The created basket is initialized with default values. Data provided in the body document will be populated into the created basket. Query parameter `temporary` can be set to `true` to create a temporary basket for the customer. The default value is `false` . Temporary baskets are separate from shopper storefront and agent baskets, and are intended for use to perform calculations or create an order without disturbing a shopper's open storefront basket. Temporary baskets are automatically deleted after a short time (15 minutes). A temporary basket can be identified with the property `temporary_basket` , which is `true` for temporary basket and `false` otherwise. Temporary baskets are available to all shoppers including guests (unlike agent baskets). All functionality that exists for a basket also applies to a temporary basket.  
A basket can be updated with further Shop API calls. Considered values from the request body are:

*   customer information: PUT /baskets/{basket\_id}/customer
    
*   billing address: PUT /baskets/{basket\_id}/billing\_address
    
*   shipments including shipping address and shipping method: POST /baskets/{basket\_id}/shipments
    
*   product items: POST /baskets/{basket\_id}/items
    
*   coupon items: POST /baskets/{basket\_id}/coupons
    
*   Invalid coupons are silently ignored.
    
*   gift certificate items: POST /baskets/{basket\_id}/gift\_certificates
    
*   payment method and card type: POST /baskets/{basket\_id}/payment\_instruments
    
*   custom properties: PATCH /baskets/{basket\_id}
    

Related resource means with which resource you can specify the same data after the basket creation. Identify the basket using the `basket_id` property, which should be integrated into the path of an update request, for example a POST to `/baskets/{basket_id}/items` . The resource supports JWT or OAuth tokens for authentication:

*   A customer must provide a JWT which specifies exactly one customer (it may be a guest or a registered customer). In this case the resource creates a basket for this customer.
    
*   An agent must provide an OAuth token. The agent can use this resource to create a basket for a newly created guest customer, and can later update the customer if desired.
    

The number of baskets which can be created per customer is limited. When a basket is created it is said to be _open_ . It remains _open_ until either an order is created from it using a POST to resource `/orders` or it is _deleted_ using a DELETE to resource `/baskets/{basket_id}` . The number of _open_ baskets allowed depends on the authentication method used and the type of basket:

*   When using JWT each customer can have just 1 _open_ basket. In addition, each customer can have up to 4 _open temporary_ baskets (by default).
    
*   When using OAuth each customer can have up to 4 _open_ baskets. These baskets can be temporary baskets or a mix of storefront and temporary baskets.
    

Custom properties in the form c\_ < CUSTOM\_NAME > are supported. A custom property must correspond to a custom attribute ( < CUSTOM\_NAME > ) defined for the Basket system object, and its value must be valid for that custom attribute. Other basket properties like the channel type or source code cannot be set with this resource.

This endpoint may return the following faults:

*   400 - CustomerBasketsQuotaExceededException - Thrown if a new basket cannot be created because the maximum number of baskets per customer would be exceeded.
*   400 - CustomerTemporaryBasketsQuotaExceededException - Thrown if a new temporary basket cannot be created because the maximum number of temporary baskets per customer would be exceeded.
*   400 - DuplicateShipmentIdException - Indicates that the same shipment id appeared twice in the body.
*   400 - InvalidCustomerException - Thrown if the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidPaymentMethodIdException - Indicates that the provided payment method is invalid or not applicable.
*   400 - InvalidPriceAdjustmentLevelException - Indicates that a fixed price adjustment was added at order level which is disallowed.
*   400 - InvalidPromotionIdException - When attempting to add a price adjustment, indicates that a promotion id was used twice.
*   400 - MissingCouponCodeException - Thrown if the coupon number is not provided.
*   400 - SystemPromotionIdException - When attempting to add a price adjustment, indicates that a system promotion id was used as a manual promotion id.
*   400 - TooManyPromotionsException - Indicates that more than one hundred price adjustments would have been created.
*   404 - ShipmentNotFoundException - Thrown if the shipment with the given shipment id is unknown.

#### Parameters

*   `temporary` (query, boolean) The boolean flag for creating the basket as temporary.

#### Request body

Media type: `application/json, text/xml`. Schema: `basket`.

#### Responses

*   **400** `CustomerBasketsQuotaExceededException` - Thrown if a new basket cannot be created because the maximum number of baskets per customer would be exceeded. or `CustomerTemporaryBasketsQuotaExceededException` - Thrown if a new temporary basket cannot be created because the maximum number of temporary baskets per customer would be exceeded. or `DuplicateShipmentIdException` - Indicates that the same shipment id appeared twice in the body. or `InvalidCustomerException` - Thrown if the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidPaymentMethodIdException` - Indicates that the provided payment method is invalid or not applicable. or `InvalidPriceAdjustmentLevelException` - Indicates that a fixed price adjustment was added at order level which is disallowed. or `InvalidPromotionIdException` - When attempting to add a price adjustment, indicates that a promotion id was used twice. or `MissingCouponCodeException` - Thrown if the coupon number is not provided. or `SystemPromotionIdException` - When attempting to add a price adjustment, indicates that a system promotion id was used as a manual promotion id. or `TooManyPromotionsException` - Indicates that more than one hundred price adjustments would have been created.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ShipmentNotFoundException` - Thrown if the shipment with the given shipment id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### POST Create a basket from a reference

`POST /baskets/reference`

Operation ID: `Create a basket from a reference`. Tags: baskets. Security: customers\_auth; client\_id.

Creates a new basket based on a basket reference.

The returned basket will be a copy of the basket in the reference. The basket in the reference must be a basket of a guest customer and the provided customer\_id in the reference must match the guest customer in the basket. There is a check that an authenticated customer for whom a basket is being copied doesn't already have a basket. In case customer\_id not matching a BasketNotFoundException will be returned as fault. All personal data like payment instruments and coupons will not be copied over to the new basket. When authenticated via JWT, a customer can only have one open basket and a CustomerBasketsQuotaExceededException is thrown, when the customer tries to create a second basket. Before using this endpoint to create a basket for a JWT-authenticated customer, verify that they don't already have one.

This endpoint may return the following faults:

*   404 - BasketNotFoundException - Indicates that the basket with the given basket id and customer id is unknown.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `basket_reference`.

#### Responses

*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id and customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### GET Get basket

`GET /baskets/{basket_id}`

Operation ID: `Get basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Gets a basket.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be retrieved  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Remove a basket

`DELETE /baskets/{basket_id}`

Operation ID: `Remove a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Removes a basket.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be retrieved  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update the customer of a basket

`PATCH /baskets/{basket_id}`

Operation ID: `Update the customer of a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Updates a basket. Only the currency of the basket, source code, and the custom properties of the basket and of the shipping items will be considered.

This endpoint may return the following faults:

*   400 - DuplicateShippingItemIdException - Indicates that a few shipping items with the same item id are provided.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidShippingItemIdException - Indicates that the given shipping item id is null or empty.
*   400 - SourceCodeInactiveException - Indicates that the provided code is not currently active.
*   400 - UnsupportedCurrencyException - Indicates that the basket cannot be updated because the requested currency is not supported by the site.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - ShippingItemNotFoundException - Indicates that the shipping item with the given item id is unknown for the basket
*   404 - SourceCodeNotFoundException - Indicates that the provided code was not found.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `basket`.

#### Responses

*   **400** `DuplicateShippingItemIdException` - Indicates that a few shipping items with the same item id are provided. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidShippingItemIdException` - Indicates that the given shipping item id is null or empty. or `SourceCodeInactiveException` - Indicates that the provided code is not currently active. or `UnsupportedCurrencyException` - Indicates that the basket cannot be updated because the requested currency is not supported by the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `ShippingItemNotFoundException` - Indicates that the shipping item with the given item id is unknown for the basket or `SourceCodeNotFoundException` - Indicates that the provided code was not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PUT Put a basket as agent basket.

`PUT /baskets/{basket_id}/agent`

Operation ID: `Put a basket as agent basket.`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Marks a basket as an agent basket.

This endpoint may return the following faults:

*   400 - CustomerBasketsQuotaExceededException - Indicates that marking this basket as an agent basket would exceed the open agent basket limit for the basket customer
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the basket id  
    Minimum length: 1.

#### Responses

*   **400** `CustomerBasketsQuotaExceededException` - Indicates that marking this basket as an agent basket would exceed the open agent basket limit for the basket customer
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### GET Get approaching discounts of a basket

`GET /baskets/{basket_id}/approaching_discounts`

Operation ID: `Get approaching discounts of a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Gets the approaching discounts of a basket

This endpoint may return the following faults:

*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) The id of the basket to be checked.  
    Minimum length: 1.

#### Responses

*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `approaching_discount_result`.
    

### PUT Set billing address of a basket

`PUT /baskets/{basket_id}/billing_address`

Operation ID: `Set billing address of a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Sets the billing address of a basket.

This endpoint may return the following faults:

*   400 - CustomerAddressIdNotApplicableException - Indicates that both customer\_address\_id and address body was provided.
*   400 - EmptyBillingAddressException - Indicates that the billing address was null and no customer\_address\_id was provided.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT (not relevant when using OAuth).
*   404 - AddressNotFoundException - Indicates that the address specified by customer\_address\_id is unknown.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) The id of the basket to be modified.  
    Minimum length: 1.
*   `use_as_shipping` (query, boolean) The flag indicating whether the given address will also be used as shipping address for the default shipment.
*   `customer_address_id` (query, string) The id of the customer address to be set as billing address. Cannot be used together with an existing body.  
    Minimum length: 1.

#### Request body

Media type: `application/json, text/xml`. Schema: `order_address`.

#### Responses

*   **400** `CustomerAddressIdNotApplicableException` - Indicates that both customer\_address\_id and address body was provided. or `EmptyBillingAddressException` - Indicates that the billing address was null and no customer\_address\_id was provided. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT (not relevant when using OAuth).
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AddressNotFoundException` - Indicates that the address specified by customer\_address\_id is unknown. or `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### POST Update basket with coupon

`POST /baskets/{basket_id}/coupons`

Operation ID: `Update basket with coupon`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Adds a coupon to an existing basket.

This endpoint may return the following faults:

*   400 - InvalidCouponCodeException - Thrown if the coupon code specified is invalid.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - MissingCouponCodeException - Thrown if the coupon number is not provided.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) The id of the basket to be modified.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `coupon_item`.

#### Responses

*   **400** `InvalidCouponCodeException` - Thrown if the coupon code specified is invalid. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `MissingCouponCodeException` - Thrown if the coupon number is not provided.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Remove coupon from basket

`DELETE /baskets/{basket_id}/coupons/{coupon_item_id}`

Operation ID: `Remove coupon from basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Removes a coupon from the basket.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - CouponItemNotFoundException - Indicates that the couponItemId URL parameter does not match any coupon item id in the basket.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `coupon_item_id` (path, string, required) the id of the coupon item to be removed  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `CouponItemNotFoundException` - Indicates that the couponItemId URL parameter does not match any coupon item id in the basket.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PUT Update customer of basket

`PUT /baskets/{basket_id}/customer`

Operation ID: `Update customer of basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Sets customer information for an existing basket.

This endpoint may return the following faults:

*   400 - CustomerBasketsQuotaExceededException - Indicates that the customer cannot be set to the basket because the max number of baskets per customer would be exceeded.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer number is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_info`.

#### Responses

*   **400** `CustomerBasketsQuotaExceededException` - Indicates that the customer cannot be set to the basket because the max number of baskets per customer would be exceeded. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `CustomerNotFoundException` - Indicates that the customer with the given customer number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### POST Add a gift certificate item to a basket

`POST /baskets/{basket_id}/gift_certificate_items`

Operation ID: `Add a gift certificate item to a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Adds a gift certificate item to an existing basket.

This endpoint may return the following faults:

*   400 - InvalidGiftCertificateItemAmountException - Indicates that the gift certificate item amount is negative.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - ShipmentNotFoundException - Indicates that the shipment with the given shipment id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `gift_certificate_item`.

#### Responses

*   **400** `InvalidGiftCertificateItemAmountException` - Indicates that the gift certificate item amount is negative.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `ShipmentNotFoundException` - Indicates that the shipment with the given shipment id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Delete a gift certificate item from a basket

`DELETE /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

Operation ID: `Delete a gift certificate item from a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Deletes a gift certificate item from an existing basket.

This endpoint may return the following faults:

*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - GiftCertificateItemNotFoundException - Indicates that the gift certificate item with the given gift certificate item id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `gift_certificate_item_id` (path, string, required) the id of the gift certificate item to be removed  
    Minimum length: 1.

#### Responses

*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `GiftCertificateItemNotFoundException` - Indicates that the gift certificate item with the given gift certificate item id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PATCH Updates a gift certificate item of a basket

`PATCH /baskets/{basket_id}/gift_certificate_items/{gift_certificate_item_id}`

Operation ID: `Updates a gift certificate item of a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Updates a gift certificate item of an existing basket.

This endpoint may return the following faults:

*   400 - InvalidGiftCertificateItemAmountException - Indicates that the gift certificate item amount is negative.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - GiftCertificateItemNotFoundException - Indicates that the gift certificate item with the given gift certificate item id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `gift_certificate_item_id` (path, string, required) the id of the gift certificate item to be updated  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `gift_certificate_item`.

#### Responses

*   **400** `InvalidGiftCertificateItemAmountException` - Indicates that the gift certificate item amount is negative.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `GiftCertificateItemNotFoundException` - Indicates that the gift certificate item with the given gift certificate item id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### POST Add items to a basket

`POST /baskets/{basket_id}/items`

Operation ID: `Add items to a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Adds new items to a basket. The added items are associated with the specified shipment. If no shipment id is specified, the added items are associated with the default shipment. Considered values from the request body, for each item are:

*   **product\_id** : a valid product id. This is the id of the product to be added to the basket. If the product is already in the basket, the API either increments the quantity of the existing product line item or creates a new product line item, based on the site preference 'Add Product Behavior'. For option products and product bundles containing variation masters, the API creates a new product line item regardless of the site preference.
    
*   **shipment\_id** : a valid shipment id (optional). This is the id of the shipment in which the product item is created.
    
*   **quantity** : a number between 0.01 and 999. This is the quantity of the product to order.
    
*   **inventory\_id** : a valid inventory id (optional). This is the id of the inventory from which the item is allocated.
    
*   **bonus\_discount\_line\_item\_id** : a valid bonus discount line item id (optional). This is the id of the bonus discount line item for which the added product is a selected bonus product.
    
*   **option\_items/option\_value\_id** : a valid option value id. This is an option value for an option item of an option product. This is only possible if the product item is an option product. To set option values, you must specify a collection of option items in the `option_items` property. These option items must contain `option_id` and `option_value_id` . Also, the values you specify must be valid for the option product that this product item represents. Otherwise, the server throws an `InvalidProductOptionItemException` or an `InvalidProductOptionValueItemException` .
    
*   **custom properties in the form c\_ < CUSTOM\_NAME >** : the custom property must correspond to a custom attribute ( < CUSTOM\_NAME > ) defined for ProductLineItem. The value of this property must be valid for the type of custom attribute defined for ProductLineItem.
    

This endpoint may return the following faults:

*   400 - BasketQuotaExceededException - Indicates that the maximum allowed number, of products added to the basket, has been exceeded.
*   400 - BonusDiscountLineItemNotFoundException - Indicates that the provided bonus discount line item id is not present in the current basket.
*   400 - BonusProductQuantityException - Indicates that the quantity of the product to be added will result in the number of selected bonus choice products to exceed the amount that the user is permitted to select.
*   400 - InvalidBonusProductException - Indicates that the selected bonus product is not an applicable product for the bonus discount line item provided.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidProductIdException - Indicates that the given product id is `null` or invalid.
*   400 - InvalidProductItemException - Indicates that the product with the given product id is unknown, offline or not assigned to site catalog or the given product item quantity is `null` or invalid.
*   400 - InvalidProductItemQuantityException - Indicates a null quantity value
*   400 - InvalidProductOptionItemException - Indicates that an option with the specified option id is unknown.
*   400 - InvalidProductOptionValueItemException - Indicates that an option with the specified option value id is unknown.
*   400 - InvalidProductTypeException - Indicates that the product cannot be added to the basket because of its type.
*   400 - ProductItemNotAvailableException - Indicates that the requested product quantity is not available.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - ShipmentNotFoundException - Indicates that the basket does not contain a shipment with the given shipment id.

#### Parameters

*   `basket_id` (path, string, required) The id of the basket to be modified.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_item`.

#### Responses

*   **400** `BasketQuotaExceededException` - Indicates that the maximum allowed number, of products added to the basket, has been exceeded. or `BonusDiscountLineItemNotFoundException` - Indicates that the provided bonus discount line item id is not present in the current basket. or `BonusProductQuantityException` - Indicates that the quantity of the product to be added will result in the number of selected bonus choice products to exceed the amount that the user is permitted to select. or `InvalidBonusProductException` - Indicates that the selected bonus product is not an applicable product for the bonus discount line item provided. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidProductIdException` - Indicates that the given product id is `null` or invalid. or `InvalidProductItemException` - Indicates that the product with the given product id is unknown, offline or not assigned to site catalog or the given product item quantity is `null` or invalid. or `InvalidProductItemQuantityException` - Indicates a null quantity value or `InvalidProductOptionItemException` - Indicates that an option with the specified option id is unknown. or `InvalidProductOptionValueItemException` - Indicates that an option with the specified option value id is unknown. or `InvalidProductTypeException` - Indicates that the product cannot be added to the basket because of its type. or `ProductItemNotAvailableException` - Indicates that the requested product quantity is not available.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `ShipmentNotFoundException` - Indicates that the basket does not contain a shipment with the given shipment id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PATCH patchBasketsByIDItems

`PATCH /baskets/{basket_id}/items`

Operation ID: `patchBasketsByIDItems`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

#### Parameters

*   `basket_id` (path, string, required)  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_item`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Remove product item from basket

`DELETE /baskets/{basket_id}/items/{item_id}`

Operation ID: `Remove product item from basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Removes a product item from the basket.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - ProductItemNotFoundException - Indicates that the product item with the given product item id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `item_id` (path, string, required) the id of the product item to be removed  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `ProductItemNotFoundException` - Indicates that the product item with the given product item id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PATCH Update an item of a basket

`PATCH /baskets/{basket_id}/items/{item_id}`

Operation ID: `Update an item of a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Updates an item in a basket. The following values in the request body are considered by the server:

*   `product_id` : a valid product id. The purpose of this value is to exchange a variation of a variation product.
    
*   `shipment_id` : a valid shipment id. The purpose of this value is to move a product item to another shipment.
    
*   `quantity` : a number between 0 and 999. The purpose of this value is to change quantity of the product item. If quantity is 0, the product item is removed.
    
*   `gift` : a boolean and `gift_message` a string allowing the setting of gift details in the product item.
    
*   `option_items/option_value_id` : a valid option value id. The purpose of this value is to exchange an option value for an option item of an option product. This is only possible if the product item is an option product. To change option values a collection of option items to be changed need to be provided in property `option_items` . Those `option_items` need to contain `option_id` and `option_value_id` . The provided values must be valid for the option product that this product item represents. Otherwise `InvalidProductOptionItemException` or `InvalidProductOptionValueItemException` will be thrown.
    
*   `_custom properties_ c_ < CUSTOM_NAME >` : a value corresponding to the type defined for custom attribute < CUSTOM\_NAME > of ProductLineItem. The purpose of this value is to add or change the value of a custom attribute defined for ProductLineItem.
    

Support for updating bundled-productlineitems is limited. This allows the caller to specify an itemId identifying a bundled-productlineitem (as opposed to a top-level productlineitem) and to update one of `product_id` , `custom properties` , `gift` and `gift_message` properties.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidProductItemException - Indicates that the product with the given product id in the request body is invalid.
*   400 - InvalidProductItemIdException - Indicates that no product item with given item id was found for the basket.
*   400 - InvalidProductItemQuantityException - Indicates a null quantity value
*   400 - InvalidProductOptionItemException - Indicates that an option with the specified option id is unknown.
*   400 - InvalidProductOptionValueItemException - Indicates that an option with the specified option value id is unknown.
*   400 - InvalidShipmentIdException - Indicates that the given shipment id is invalid.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown
*   404 - ShipmentNotFoundException - Indicates that a shipment with it's given id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `item_id` (path, string, required) the it of the item to be updated  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `product_item`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidProductItemException` - Indicates that the product with the given product id in the request body is invalid. or `InvalidProductItemIdException` - Indicates that no product item with given item id was found for the basket. or `InvalidProductItemQuantityException` - Indicates a null quantity value or `InvalidProductOptionItemException` - Indicates that an option with the specified option id is unknown. or `InvalidProductOptionValueItemException` - Indicates that an option with the specified option value id is unknown. or `InvalidShipmentIdException` - Indicates that the given shipment id is invalid.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown or `ShipmentNotFoundException` - Indicates that a shipment with it's given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### GET Get notes from a basket

`GET /baskets/{basket_id}/notes`

Operation ID: `Get notes from a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Retrieves notes for a basket.

This endpoint may return the following faults:

*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) The id of the basket for which you want to retrieve the notes.  
    Minimum length: 1.

#### Responses

*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `notes_result`.
    

### POST Add a note to a basket

`POST /baskets/{basket_id}/notes`

Operation ID: `Add a note to a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Adds a note to an existing basket.

This endpoint may return the following faults:

*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) The id of the basket to be modified.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `note`.

#### Responses

*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Remove a note from a basket

`DELETE /baskets/{basket_id}/notes/{note_id}`

Operation ID: `Remove a note from a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Removes a basket note.

This endpoint may return the following faults:

*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `note_id` (path, string, required) the id of the note to be removed  
    Minimum length: 1.

#### Responses

*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### POST Add payment instrument to basket

`POST /baskets/{basket_id}/payment_instruments`

Operation ID: `Add payment instrument to basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Adds a payment instrument to a basket.

Payment instruments are usually authorized after order creation, for example in a custom hook. The default payment authorization process executes an authorization when a payment instrument is added to an order or updated. See `POST /orders/{order_no}/payment_instruments` and `PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}` . NOTE: If CREDIT\_CARD is selected as the payment\_method\_id, it is mandatory to provide the property card\_type.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidPaymentMethodIdException - Indicates that the provided payment method is invalid or not applicable.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - PaymentInstrumentNotFoundException - Indicates that the payment instrument with the given customer payment instrument id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the basket id  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `basket_payment_instrument_request`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidPaymentMethodIdException` - Indicates that the provided payment method is invalid or not applicable.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `PaymentInstrumentNotFoundException` - Indicates that the payment instrument with the given customer payment instrument id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Removes a payment instrument from a basket

`DELETE /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

Operation ID: `Removes a payment instrument from a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Removes a payment instrument of a basket.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - PaymentInstrumentNotFoundException - Indicates that the payment instrument with the given payment instrument number is unknown.

#### Parameters

*   `basket_id` (path, string, required) the basket id  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) the id of the payment instrument to be removed  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `PaymentInstrumentNotFoundException` - Indicates that the payment instrument with the given payment instrument number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PATCH Updates payment instrument of basket

`PATCH /baskets/{basket_id}/payment_instruments/{payment_instrument_id}`

Operation ID: `Updates payment instrument of basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Updates a payment instrument of a basket.

Payment instruments are usually authorized after order creation, for example in a custom hook. The default payment authorization process executes an authorization when a payment instrument is added to an order or updated. See `POST /orders/{order_no}/payment_instruments` and `PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidPaymentMethodIdException - Indicates that the provided payment method is invalid or not applicable.
*   400 - PaymentInstrumentPermanentlyMaskedException - Indicates that the basket payment instrument with the given id already is permanently masked. Please see `dw.order.PaymentInstrument.isPermanentlyMasked()` for detailed information.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - PaymentInstrumentNotFoundException - Indicates that the payment instrument with the given payment instrument number is unknown.

#### Parameters

*   `basket_id` (path, string, required) the basket id  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) the id of the payment instrument to be updated  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `basket_payment_instrument_request`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidPaymentMethodIdException` - Indicates that the provided payment method is invalid or not applicable. or `PaymentInstrumentPermanentlyMaskedException` - Indicates that the basket payment instrument with the given id already is permanently masked. Please see `dw.order.PaymentInstrument.isPermanentlyMasked()` for detailed information.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `PaymentInstrumentNotFoundException` - Indicates that the payment instrument with the given payment instrument number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### GET Get applicable payment methods for basket

`GET /baskets/{basket_id}/payment_methods`

Operation ID: `Get applicable payment methods for basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Gets applicable payment methods for an existing basket considering the open payment amount only.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the basket id  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `payment_method_result`.
    

### POST Add price adjustment to basket

`POST /baskets/{basket_id}/price_adjustments`

Operation ID: `Add price adjustment to basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Adds a custom manual price adjustment to the basket.

This endpoint may return the following faults:

*   400 - FixedPriceAdjustmentAlreadyExistsException - Indicates that a fixed price adjustment was already created for the given level.
*   400 - InvalidPriceAdjustmentLevelException - Indicates that a fixed price adjustment was added at order level.
*   400 - InvalidPromotionIdException - Indicates that a promotion id was used twice.
*   400 - PriceAdjustmentLimitExceededException - Indicates that the price adjustment limit is exceeded.
*   400 - SystemPromotionIdException - Indicates that a system promotion id was used as a manual promotion id.
*   400 - TooManyPromotionsException - Indicates that more than one hundred price adjustments would have been created.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `price_adjustment_request`.

#### Responses

*   **400** `FixedPriceAdjustmentAlreadyExistsException` - Indicates that a fixed price adjustment was already created for the given level. or `InvalidPriceAdjustmentLevelException` - Indicates that a fixed price adjustment was added at order level. or `InvalidPromotionIdException` - Indicates that a promotion id was used twice. or `PriceAdjustmentLimitExceededException` - Indicates that the price adjustment limit is exceeded. or `SystemPromotionIdException` - Indicates that a system promotion id was used as a manual promotion id. or `TooManyPromotionsException` - Indicates that more than one hundred price adjustments would have been created.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Remove price adjustment from basket

`DELETE /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

Operation ID: `Remove price adjustment from basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Removes a custom manual price adjustment from the basket.

This endpoint may return the following faults:

*   400 - InvalidPriceAdjustmentItemIdException - Indicates that the priceAdjustmentId is missing, empty or whitespace.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `price_adjustment_id` (path, string, required) the uuid of the adjustment to be removed  
    Minimum length: 1.

#### Responses

*   **400** `InvalidPriceAdjustmentItemIdException` - Indicates that the priceAdjustmentId is missing, empty or whitespace.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PATCH Updates a price adjustment on a basket

`PATCH /baskets/{basket_id}/price_adjustments/{price_adjustment_id}`

Operation ID: `Updates a price adjustment on a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Updates a custom manual price adjustment on the basket. Only the following PATH values are considered for the update: discount, item\_text, reason\_code and custom properties; all other attributes are ignored. The discount type of a price adjustment cannot be updated and therefore, the value of the existing type must be passed. For an adjustment of type PERCENTAGE, the 'percentage' attribute is mandatory. For adjustments of type AMOUNT and FIXED\_PRICE, the 'amount' attribute is mandatory.

This endpoint may return the following faults:

*   400 - PriceAdjustmentLimitExceededException - Indicates that the price adjustment limit is exceeded.
*   400 - PriceAdjustmentUpdateAttributeMissingException - Indicates that the expected attributes are missing in the input.
*   400 - PriceAdjustmentUpdateNotManualException - Indicates that the price adjustment is not manual and cannot be updated.
*   400 - PriceAdjustmentUpdateTypeMismatchException - Indicates that the type of a price adjustment does not match the adjustment type of the input data.
*   404 - PriceAdjustmentIdNotFoundException - Indicates that the priceAdjustmentId is not found.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `price_adjustment_id` (path, string, required) the uuid of the adjustment to be updated  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `price_adjustment`.

#### Responses

*   **400** `PriceAdjustmentLimitExceededException` - Indicates that the price adjustment limit is exceeded. or `PriceAdjustmentUpdateAttributeMissingException` - Indicates that the expected attributes are missing in the input. or `PriceAdjustmentUpdateNotManualException` - Indicates that the price adjustment is not manual and cannot be updated. or `PriceAdjustmentUpdateTypeMismatchException` - Indicates that the type of a price adjustment does not match the adjustment type of the input data.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `PriceAdjustmentIdNotFoundException` - Indicates that the priceAdjustmentId is not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### POST Create shipment for a basket

`POST /baskets/{basket_id}/shipments`

Operation ID: `Create shipment for a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Creates a new shipment for a basket.

The created shipment is initialized with values provided in the body document and can be updated with further data API calls. Considered from the body are the following properties if specified:

*   the id
    
*   the shipping address
    
*   the shipping method
    
*   gift boolean flag
    
*   gift message
    
*   custom properties
    

This endpoint may return the following faults:

*   400 - DuplicateShipmentIdException - Indicates that a shipment with the provided id already exists for the basket.
*   400 - DuplicateShipmentNoException - Indicates that a shipment with the provided shipment number already exists for the basket.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidShippingMethodIdException - Indicates that a shipping method with an id was specified which is not a valid shipping method id.
*   400 - MissingShipmentIdException - Indicates that a shipment id is not provided.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `shipment`.

#### Responses

*   **400** `DuplicateShipmentIdException` - Indicates that a shipment with the provided id already exists for the basket. or `DuplicateShipmentNoException` - Indicates that a shipment with the provided shipment number already exists for the basket. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidShippingMethodIdException` - Indicates that a shipping method with an id was specified which is not a valid shipping method id. or `MissingShipmentIdException` - Indicates that a shipment id is not provided.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### DELETE Remove shipment from basket

`DELETE /baskets/{basket_id}/shipments/{shipment_id}`

Operation ID: `Remove shipment from basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Removes a specified shipment and all associated product, gift certificate, shipping and price adjustment line items from a basket. You can't remove a default shipment (id = "me").

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidShipmentIdException - Indicates that the given shipment id is invalid.
*   403 - DefaultShipmentDeletionForbiddenException - Indicates that the given shipment id corresponds to the default shipment (shipment ID always set to "me") and cannot be removed.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `shipment_id` (path, string, required) the id of the shipment to be deleted  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidShipmentIdException` - Indicates that the given shipment id is invalid.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **403** `DefaultShipmentDeletionForbiddenException` - Indicates that the given shipment id corresponds to the default shipment (shipment ID always set to "me") and cannot be removed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PATCH Update shipment for a basket

`PATCH /baskets/{basket_id}/shipments/{shipment_id}`

Operation ID: `Update shipment for a basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Updates a shipment for a basket. The body can include updated values for the following properties:

*   the id
    
*   the shipping address
    
*   the shipping method
    
*   gift boolean flag
    
*   gift message
    
*   custom properties
    

This endpoint may return the following faults:

*   400 - DuplicateShipmentIdException - Indicates that a shipment with the provided id already exists for the basket.
*   400 - DuplicateShipmentNoException - Indicates that a shipment with the provided shipment number already exists for the basket.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidShipmentIdException - Indicates that the given shipment id was invalid.
*   400 - InvalidShippingMethodIdException - Indicates an invalid shipping method.
*   400 - MissingShippingMethodIdException - Indicates a missing shipping method.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `shipment_id` (path, string, required) the id of the shipment to be modified  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `shipment`.

#### Responses

*   **400** `DuplicateShipmentIdException` - Indicates that a shipment with the provided id already exists for the basket. or `DuplicateShipmentNoException` - Indicates that a shipment with the provided shipment number already exists for the basket. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidShipmentIdException` - Indicates that the given shipment id was invalid. or `InvalidShippingMethodIdException` - Indicates an invalid shipping method. or `MissingShippingMethodIdException` - Indicates a missing shipping method.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PUT Sets the shipping address of a shipment

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_address`

Operation ID: `Sets the shipping address of a shipment`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Sets a shipping address of a specific shipment of a basket.

This endpoint may return the following faults:

*   400 - CustomerAddressIdNotApplicableException - Indicates that both customer\_address\_id and address body was provided.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT (not relevant when using OAuth).
*   400 - InvalidShipmentIdException - Thrown if the shipment with the given shipment id is unknown.
*   404 - AddressNotFoundException - Indicates that the address specified by customer\_address\_id is unknown.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) The id of the basket to be modified.  
    Minimum length: 1.
*   `shipment_id` (path, string, required) The id of the shipment to be modified.  
    Minimum length: 1.
*   `use_as_billing` (query, boolean) The flag indicating whether the given address will also be used as billing address.
*   `customer_address_id` (query, string) The id of the customer address to be set as shipping address. Cannot be used together with an existing body.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_address`.

#### Responses

*   **400** `CustomerAddressIdNotApplicableException` - Indicates that both customer\_address\_id and address body was provided. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT (not relevant when using OAuth). or `InvalidShipmentIdException` - Thrown if the shipment with the given shipment id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `AddressNotFoundException` - Indicates that the address specified by customer\_address\_id is unknown. or `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### PUT Set shipping method to shipment

`PUT /baskets/{basket_id}/shipments/{shipment_id}/shipping_method`

Operation ID: `Set shipping method to shipment`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Sets a shipping method to a specific shipment of a basket.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidShippingMethodIdException - Indicates that a shipping method with an id was specified which is not a valid shipping method id.
*   400 - MissingShippingMethodIdException - Indicates that the id of the shipping method is missing.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket to be modified  
    Minimum length: 1.
*   `shipment_id` (path, string, required) the id of the shipment to be modified  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `shipping_method`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidShippingMethodIdException` - Indicates that a shipping method with an id was specified which is not a valid shipping method id. or `MissingShippingMethodIdException` - Indicates that the id of the shipping method is missing.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

### GET Get applicable shipping methods for certain shipment of basket

`GET /baskets/{basket_id}/shipments/{shipment_id}/shipping_methods`

Operation ID: `Get applicable shipping methods for certain shipment of basket`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Gets the applicable shipping methods for a certain shipment of a basket.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   404 - ShipmentNotFoundException - Indicates that the shipment with the given shipment id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the id of the basket  
    Minimum length: 1.
*   `shipment_id` (path, string, required) the id of the shipment  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown. or `ShipmentNotFoundException` - Indicates that the shipment with the given shipment id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `shipping_method_result`.
    

### PUT Put a basket as storefront basket.

`PUT /baskets/{basket_id}/storefront`

Operation ID: `Put a basket as storefront basket.`. Tags: baskets. Security: customers\_auth; oauth2\_application; client\_id.

Marks a basket as storefront basket.

This endpoint may return the following faults:

*   400 - CustomerBasketsQuotaExceededException - Thrown if a storefront basket already exists and exchange is `false` .
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Parameters

*   `basket_id` (path, string, required) the basket id  
    Minimum length: 1.
*   `exchange` (query, boolean) if `true` an existing storefront basket will be exchanged and marked as agent basket. if `false` a CustomerBasketsQuotaExceededException will be thrown.

#### Responses

*   **400** `CustomerBasketsQuotaExceededException` - Thrown if a storefront basket already exists and exchange is `false` .
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `basket`.
    

## Schemas

### basket

Document representing a basket.

The following flashes are used to indicate the invalidity of a basket:

*   InvalidProductItem - a product item (or bundled product item) refers to a product which no longer exists, is offline, or the product is no longer assigned to a site catalog.
    
*   InvalidOptionItem - indicates that an option item refers to an option id or option value which no longer exists.
    
*   OptionItemWithoutPrice - indicates an option item without a price.
    
*   InvalidCouponCode (until 17.2) - indicates a coupon item became invalid, for example because its redemption limit is reached.
    
*   ProductItemNotAvailable - indicates too little available inventory to support the item quantity.
    
*   ProductItemWithoutPrice - indicates that the item has no price.
    
*   CustomerEmailRequired (until 17.2) - indicates the need to specify a customer email.
    
*   ShippingAddressRequired - indicates the need to specify a shipping address.
    
*   BillingAddressRequired - indicates the need to specify a billing address.
    
*   ShippingMethodRequired - indicates the need to specify a shipping method.
    
*   ShippingMethodNotApplicable - indicates that the currently specified shipping method is not applicable for the given addresses or product items.
    
*   PaymentMethodRequired - indicates the need to specify a payment method.
    
*   PaymentMethodNotApplicable - the currently specified payment method is not applicable for the given addresses or product items.
    
*   OrderTotalNotSet - the basket calculation could not be completed for some reason.
    
*   ProductItemAdjustedPriceLessThanZero - a price adjustment reduces an item price to a value below zero and should be corrected.
    

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency.
    
    Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `agent_basket` (_boolean_) Is the basket created by an agent?
*   `basket_id` (_string_) The unique identifier for the basket.
*   `billing_address` (_order\_address_) The billing address. This property is part of basket checkout information only.
*   `bonus_discount_line_items` (_array of bonus\_discount\_line\_item_) The bonus discount line items of the line item container.
*   `channel_type` (_string_, read-only)
    
    The sales channel for the order.
    
    This is a read-only attribute that can't be modified by an OCAPI call. For OCAPI, the sales channel is determined based on the client ID and token used for the OCAPI call. Usually, a customer-based authentication sets the channel to Storefront, and an agent-based authentication sets it to CallCenter. Using applications that use other client IDs for OCAPI calls, like Customer Service Center, will set different channel types. To modify the channel type in OCAPI, use a hook. \*
    
      
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `google`, `tiktok`, `snapchat`, `youtube`, `whatsapp`.
*   `coupon_items` (_array of coupon\_item_) The sorted array of coupon items. This array can be empty.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `customer_info` (_customer\_info_) The customer information for logged in customers. This property is part of basket checkout information only.
*   `gift_certificate_items` (_array of gift\_certificate\_item_) The sorted array of gift certificate line items. This array can be empty.
*   `grouped_tax_items` (_array of grouped\_tax_) Tax values that are summed and grouped based on the tax rate. The tax totals of the line items with the same tax rate will be grouped together and summed up. This will not affect calculation in any way.
*   `inventory_reservation_expiry` (_string (date-time)_)
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `merchandize_total_tax` (_number (double)_)
    
    The products total tax in purchase currency.
    
    Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
    
*   `notes` (_simple\_link_) The notes for the line item container.
*   `order_price_adjustments` (_array of price\_adjustment_) The array of order level price adjustments. This array can be empty.
*   `order_total` (_number (double)_) The total price of the order, including products, shipping and tax. This property is part of basket checkout information only.
*   `payment_instruments` (_array of order\_payment\_instrument_) The payment instruments list for the order.
*   `product_items` (_array of product\_item_) The sorted array of product items (up to a maximum of 50 items by default). This array can be empty.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipments` (_array of shipment_) The array of shipments. This property is part of basket checkout information only.
*   `shipping_items` (_array of shipping\_item_) The sorted array of shipping items. This array can be empty.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the order after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross. This property is part of basket checkout information only.
    
    ```
         Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `source_code` (_string_) Gets the source code assigned to this basket.
*   `tax_rounded_at_group` (_boolean_) If the tax is rounded at group level then this is set to true, false if the tax is rounded at item or unit level
*   `tax_total` (_number (double)_) The total tax amount of the order. This property is part of basket checkout information only.
*   `taxation` (_string_) The taxation the line item container is based on.  
    Allowed values: `gross`, `net`.
*   `temporary_basket` (_boolean_) Is the basket created a temporary basket?

_Example_

```
{
  "basket_id": "bczFTaOjgEqUkaaadkvHwbgrP5",
  "currency": "USD",
  "customer_info": {
    "customer_id": "adNJrbxJovaT5DPxUSfOywk6Et",
    "email": ""
  },
  "order_total": 0,
  "product_sub_total": 0,
  "product_total": 0,
  "shipments": [
    {
      "id": "me",
      "shipment_id": "bc5OTaOjgEqUoaaadkvHwbgrP5"
    }
  ],
  "shipping_items": [
    {
      "item_id": "bcwsbaOjgEqUsaaadkvHwbgrP5",
      "shipment_id": "me"
    }
  ],
  "shipping_total": 0,
  "shipping_total_tax": 0,
  "tax_total": 0,
  "taxation": "net"
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### basket\_reference

Reference to a basket.

*   `basket_id` (_string_, required) The unique identifier for the basket.
*   `customer_id` (_string_, required) The unique identifier for the customer.  
    Maximum length: 100.

_Example_

```
{
  "basket_id": "tczFTaOjgEqUkacedkvHwbgrP3",
  "customer_id": "dlNJrbxJovaT5TPxUSfOywk6as"
}
```

### approaching\_discount\_result

A result of a approaching discount request.

*   `approaching_discounts` (_array of approaching\_discount_) Lists approaching discounts.

_Example_

```
{
  "approaching_discounts": [
    {
      "_type": "approaching_discount",
      "condition_threshold": 100,
      "type": "order"
    }
  ]
}
```

### order\_address

Document representing an order address.

*   `address1` (_string_) The first address.
*   `address2` (_string_) The second address.
*   `city` (_string_) The city.
*   `company_name` (_string_) The company name.
*   `country_code` (_string_) The two-letter ISO 3166-1 (Alpha-2) country code.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States.
*   `first_name` (_string_) The first name.
*   `full_name` (_string_) The full name.
*   `id` (_string_) Id used to identify this address
*   `job_title` (_string_) The job title.
*   `last_name` (_string_) The last name.
*   `phone` (_string_) The phone number.
*   `post_box` (_string_) The post box.
*   `postal_code` (_string_) The postal code.
*   `salutation` (_string_) The salutation.
*   `second_name` (_string_) The second name.
*   `state_code` (_string_) The state code.
*   `suffix` (_string_) The suffix.
*   `suite` (_string_) The suite.
*   `title` (_string_) The title.

_Example_

```
{
  "city": "Boston",
  "country_code": "US",
  "first_name": "John",
  "last_name": "Smith"
}
```

### coupon\_item

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256.
*   `coupon_item_id` (_string_) The coupon item id.
*   `status_code` (_string_) The status of the coupon item.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is 'applied' or 'no\_applicable\_promotion'.

_Example_

```
{
  "code": "the99coupon"
}
```

### customer\_info

Document representing information used to identify a customer.

*   `customer_id` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `customer_name` (_string_)
*   `customer_no` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `email` (_string (email)_, required) The customer's email address.

_Example_

```
{
  "customer_no": "customer0012",
  "email": "valid@email.com"
}
```

### gift\_certificate\_item

A gift certificate item.

*   `amount` (_number (double)_, required) The certificate item amount.
*   `gift_certificate_item_id` (_string_) Id used to identify this item
*   `message` (_string_) The certificate's message.  
    Maximum length: 4000.
*   `recipient_email` (_string_, required) The recipient's email.  
    Minimum length: 1.
*   `recipient_name` (_string_) The recipient's name.
*   `sender_name` (_string_) The sender's name.
*   `shipment_id` (_string_) The shipment id.

_Example_

```
{
  "amount": 200,
  "message": "Present from your brother",
  "recipient_email": "peter@example.com",
  "recipient_name": "Peter Doe",
  "sender_name": "John Doe"
}
```

### product\_item

Document representing a product item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_, required) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 5,
  "base_price": 16.49,
  "bonus_product_line_item": false,
  "item_id": "cdHBEiWbNV9ZcaaadhrCk35gtp",
  "item_text": "Simple Product",
  "price": 16.49,
  "price_after_item_discount": 16.49,
  "price_after_order_discount": 1,
  "product_id": "SimpleProduct",
  "product_name": "Simple Product",
  "quantity": 1,
  "tax": 5,
  "tax_basis": 16.49,
  "tax_class_id": null,
  "tax_rate": 0.05,
  "c_strValue": "Test"
}
```

### notes\_result

A result of a note request.

Contains notes for an object - for example, for a basket.

*   `notes` (_array of note_) The notes for an object.

_Example_

```
{
  "notes": [
    {
      "subject": "Unhappy customer",
      "text": "The customer was not very happy due to a delay."
    },
    {
      "subject": "Happy customer",
      "text": "The customer is already happy!"
    }
  ]
}
```

### note

Document representing a note to an object.

*   `created_by` (_string_) The author of the note.
*   `creation_date` (_string (date-time)_) The creation date of the note.
*   `id` (_string_) The ID of the note.
*   `subject` (_string_) The note's subject.  
    Maximum length: 256.
*   `text` (_string_) The note's text.  
    Maximum length: 4000.

_Example_

```
{
  "subject": "this is an example subject",
  "text": "This is a note because the customer was not very happy."
}
```

### basket\_payment\_instrument\_request

Document representing a basket payment instrument request.

*   `amount` (_number (double)_) The payment transaction amount.
*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `customer_payment_instrument_id` (_string_) The id of a customer payment instrument.
*   `gift_certificate_code` (_string_) The gift certificate code.  
    Maximum length: 256.
*   `payment_bank_account` (_payment\_bank\_account\_request_) The payment bank account request data.
*   `payment_card` (_order\_payment\_card\_request_) The payment card.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "amount": 1,
  "payment_card": {
    "card_type": "Visa",
    "expiration_month": 1,
    "expiration_year": 2021,
    "holder": "John Doe",
    "number": "411111111111111",
    "security_code": "121"
  },
  "payment_method_id": "CREDIT_CARD"
}
```

### payment\_method\_result

Result document of payment methods applicable for a basket.

*   `applicable_payment_methods` (_array of payment\_method_) The applicable payment methods.

_Example_

```
{
  "applicable_payment_methods": [
    {
      "id": "BANK_TRANSFER",
      "name": "Bank Transfer"
    },
    {
      "cards": [
        {
          "card_type": "Visa",
          "checksum_verification_enabled": true,
          "id": "CREDIT_CARD.Visa",
          "name": "Visa",
          "number_lengths": [
            "13",
            "16"
          ],
          "number_prefixes": [
            "4"
          ],
          "security_code_length": 3
        },
        {
          "card_type": "Master",
          "checksum_verification_enabled": true,
          "id": "CREDIT_CARD.Master",
          "name": "Mastercard",
          "number_lengths": [
            "16"
          ],
          "number_prefixes": [
            "2221-2720",
            "51-55"
          ],
          "security_code_length": 3
        },
        {
          "card_type": "Amex",
          "checksum_verification_enabled": true,
          "id": "CREDIT_CARD.Amex",
          "name": "American Express",
          "number_lengths": [
            "15"
          ],
          "number_prefixes": [
            "34",
            "37"
          ],
          "security_code_length": 4
        }
      ],
      "id": "CREDIT_CARD",
      "name": "Credit Card",
      "c_somestring": "PaymentMethod String Value"
    },
    {
      "description": "A conditional payment method on customer group 'Unregistered'.",
      "id": "OCAPI_Payment_Unregistered",
      "image": "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
      "name": "OCAPI Payment (Unregistered)"
    },
    {
      "description": "A conditional payment method on country 'DE'.",
      "id": "OCAPI_Payment_DE",
      "image": "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
      "name": "OCAPI Payment (DE)"
    },
    {
      "description": "A simple payment method without any conditions.",
      "id": "OCAPI_Payment_Simple",
      "image": "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
      "name": "OCAPI Payment (Simple)"
    }
  ]
}
```

### price\_adjustment\_request

Document representing a price adjustment request.

Use the `level` and `item_id` properties to specify where you want the price adjustment to be added:

*   If you specify **order** as the level, you do not have to specify an `item_id` . This indicates that the price adjustment should be added directly to basket.
    
*   If you specify **product** as the level, the `item_id` that you specify is the `item_id` of the product item. This indicates that the price adjustment should be added to the product item.
    
*   If you specify **shipping** as the level, `item_id` that you specify is the `item_id` of the shipping item. This indicates that the price adjustment is added to the shipping item.
    

You can use the `item_text` and `reason_code` properties to describe the price adjustment.

The `promotion_id` property is optional. If you do not specify an id, one is automatically assigned (in the format 'dw.manual\[n\]', where \[n\] is 1, 2, 3...). If you specify an id, make sure that it is not already used for a price adjustment in the basket or for a promotion in the promotion engine.

You need to specify the value of the price adjustment by defining a `discount` from which the price adjustment is calculated. The discount definition consists of a `type` and a `value` .

The type **amount** describes a (unit) price discount, and its corresponding `value` (positive) defines the amount each unit is to be reduced. For example, for a $10 discount:

`{ "discount" : {"type" : "amount", "value" : 10.00 }, ... }`

The type **percentage** describes a percentage discount, and its corresponding `value` (positive) defines the percentage reduction. For example, for a 5% discount:

`{ "discount" : {"type" : "percentage", "value" : 5 }, ... }` The type **fixed\_price** describes a fixed price discount, and its corresponding `value` (positive) defines the resulting fixed price for the item. Only one **fixed\_price** discount can be set for each item. For example, to fix a $15 price for the item:

`{ "discount" : {"type" : "fixed_price", "value" : 15.00 }, ... }`

The type **fixed\_price** is not applicable at the **order** level.

*   `discount` (_discount\_request_) A discount that you can specify instead of a `price`. When defining a discount, you must specify a `type` and a `value`.
*   `item_id` (_string_) The item to which the price adjustment should be added, depending on the specified level. If the level is 'order', you need not specify an item id. If 'shipping', specify the uuid of the shipping item. If 'product', specify the uuid of the product item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `level` (_string_, required) The level at which the adjustment is applied. When a product or shipping level is specified, you must also specify the item id.  
    Allowed values: `product`, `shipping`, `order`.
*   `promotion_id` (_string_) The id of the related promotion. Custom price adjustments can be assigned any promotion id so long it is not used by a price adjustment belonging to the same item and is not used by promotion defined in the promotion engine. If not specified, a promotion id is generated.
*   `reason_code` (_string_) The reason why this price adjustment was made.  
    Allowed values: `BACKORDER`, `EVEN_EXCHANGE`, `PRICE_MATCH`. Value meanings: `BACKORDER`: Backorder; `EVEN_EXCHANGE`: Even Exchange; `PRICE_MATCH`: Price Match.

_Example_

```
{
  "discount": {
    "type": "percentage",
    "value": 5
  },
  "item_text": "MyOrderAdjustment",
  "level": "order",
  "promotion_id": "manual adjustment"
}
```

### price\_adjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level. They can be created by the promotion engine (if the custom flag is set to false) or can be added by custom logic (if the custom flag is set to true). For custom price adjustments created by a user, the manual flag should be set to true; this is always the case for price adjustments created using OCAPI.

A price adjustment created by custom logic can either define a price that defines the absolute price reduction or define a discount from which a price reduction is calculated (amount, percentage, and fixed\_price discounts are supported). The applied\_discount property describes the discount applied to create the price-adjustment.

*   `applied_discount` (_discount_) A price adjustment that provides details of the discount that was applied. This is `null` for custom price adjustments created without discount details.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, provided the price adjustment was created as the result of a promotion being triggered by a coupon.
*   `created_by` (_string_) The user who created the price adjustment.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.
*   `item_text` (_string_) The text describing the item in more detail.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `manual` (_boolean_)
    
    A flag indicating whether this price adjustment was created in a manual process.
    
    For custom price adjustments created using the shop API, this _always_ returns `true`. Using the scripting API, however, it is possible to set this to `true` or `false`, according to the use case.
    
*   `price` (_number (double)_) The adjustment price.
*   `price_adjustment_id` (_string_) The price adjustment id (uuid).
*   `promotion_id` (_string_) The id of the related promotion. Custom price adjustments can be assigned any promotion id so long it is not used by a price adjustment belonging to the same item and is not used by promotion defined in the promotion engine. If not specified, a promotion id is generated.
*   `promotion_link` (_string_) The URL addressing the related promotion.
*   `reason_code` (_string_) The reason why this price adjustment was made.  
    Allowed values: `BACKORDER`, `EVEN_EXCHANGE`, `PRICE_MATCH`. Value meanings: `BACKORDER`: Backorder; `EVEN_EXCHANGE`: Even Exchange; `PRICE_MATCH`: Price Match.

### shipment

Document representing a shipment.

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency. Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift.
*   `gift_message` (_string_) The gift message.
*   `merchandize_total_tax` (_number (double)_) The products total tax in purchase currency. Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipment_id` (_string_) The order specific id to identify the shipment.
*   `shipment_no` (_string_)
    
    Returns the shipment number for this shipment.
    
    This number is automatically generated.
    
*   `shipment_total` (_number (double)_)
    
    The total price of the shipment, including products, shipping and tax.
    
    Note that order level adjustments are not considered.
    
*   `shipping_address` (_order\_address_) The shipping address.
*   `shipping_method` (_shipping\_method_) The shipping method.
*   `shipping_status` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the shipment after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross.
    
    ```
         net. Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `tax_total` (_number (double)_)
    
    The total tax amount of the shipment.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `tracking_number` (_string_) The tracking number of the shipment.

_Example_

```
{
  "gift": true,
  "gift_message": "Happy Birthday, Sværre",
  "id": "StandardShipping",
  "shipping_address": {
    "city": "Boston",
    "country_code": "US",
    "first_name": "John",
    "last_name": "Smith"
  },
  "shipping_method": {
    "id": "BaseShippingMethod"
  }
}
```

### shipping\_method

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.
*   `external_shipping_method` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method id.  
    Maximum length: 256.
*   `name` (_string_) The localized name of the shipping method.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs and product level fix and surcharge costs.
*   `shipping_promotions` (_array of shipping\_promotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

_Example_

```
{
  "id": "BaseShippingMethod"
}
```

### shipping\_method\_result

Result document containing shipping methods.

*   `applicable_shipping_methods` (_array of shipping\_method_) The applicable shipping method documents.
*   `default_shipping_method_id` (_string_) The default shipping method.

_Example_

```
{
  "applicable_shipping_methods": [
    {
      "description": "The default shipping method.",
      "id": "DefaultShippingMethod",
      "name": "Default Shipping Method",
      "price": 5.55
    },
    {
      "description": "The base shipping method.",
      "id": "BaseShippingMethod",
      "name": "Base Shipping Method",
      "price": 0.99
    },
    {
      "description": "A shipping method that contains product level shipping costs.",
      "id": "ProductLevelShippingCostsShippingMethod",
      "name": "Product Level Shipping Costs Shipping Method",
      "price": 0.1
    }
  ],
  "default_shipping_method_id": "DefaultShippingMethod"
}
```

### bonus\_discount\_line\_item

Document representing a bonus discount line item

*   `bonus_products` (_array of product\_details\_link_) The list of links to the bonus products the customer can choose from.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, if applicable.
*   `id` (_string_) The ID of the line item.
*   `max_bonus_items` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotion_id` (_string_) The ID of the promotion which triggered the creation of the line item.

### grouped\_tax

Document representing a tax rate with it's summed up tax values

*   `tax_rate` (_number (double)_) The tax rate
*   `tax_value` (_number (double)_) The summed up tax total for the tax rate

### simple\_link

Document representing a link to another resource.

*   `link` (_string_) The link to the resource.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/orders/bc0KwiWexX0ZQaaadqRTwMZFga/notes"
}
```

### order\_payment\_instrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.
*   `authorization_status` (_status_) The authorization status of the payment transaction.
*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code.
*   `payment_bank_account` (_payment\_bank\_account_) The payment bank account.
*   `payment_card` (_payment\_card_) The payment card.
*   `payment_instrument_id` (_string_) The payment instrument ID.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "amount": 1,
  "payment_card": {
    "card_type": "Visa",
    "credit_card_expired": false,
    "expiration_month": 1,
    "expiration_year": 2021,
    "holder": "John Doe",
    "masked_number": "***********1111",
    "number_last_digits": "1111"
  },
  "payment_instrument_id": "ceDUYiWbN1IkkaaadkYHRkclwC",
  "payment_method_id": "CREDIT_CARD",
  "c_strValue": "any custom value"
}
```

### shipping\_item

Document representing a shipping item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `shipment_id` (_string_) The identifier of the shipment to which this item belongs.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 0,
  "base_price": 0.01,
  "item_id": "devgoiWbNVc92aaadhrSk35gtp",
  "item_text": "Shipping",
  "price": 0.01,
  "price_after_item_discount": 0.01,
  "shipment_id": "me",
  "tax": 0,
  "tax_basis": 0.01,
  "tax_class_id": "DefaultTaxClass",
  "tax_rate": 0.05
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### approaching\_discount

Document representing a note to an object.

*   `condition_threshold` (_number (double)_) The total amount needed to receive the discount.
*   `discount` (_discount_) The discount the customer can receive if eligible.
*   `merchandise_total` (_number (double)_) The amount the customer basket contributes towards the purchase condition.
*   `promotion_link` (_promotion\_link_) The link to details of the promotion associated with this discount.
*   `shipment_id` (_string_) The unique id of the shipment the discount relates to.
*   `shipping_methods` (_array of shipping\_method_) The shipping methods the promotion relates to.
*   `type` (_string_) The type of the approaching discount ("order" or "shipping").

_Example_

```
{
  "condition_threshold": 100,
  "type": "order"
}
```

### option\_item

Document representing an option item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_id` (_string_, required) The id of the option.  
    Maximum length: 256.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `option_value_id` (_string_, required) The id of the option value.  
    Maximum length: 256.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "option_id": "Warranty",
  "option_value_id": "oneYear"
}
```

### product\_list\_item\_reference

*   `id` (_string_, required) The id of the product list item.
*   `priority` (_integer (int32)_)
*   `product_details_link` (_product\_details\_link_)
*   `product_list` (_product\_list\_link_) The link of the product list, the item is assigned
*   `public` (_boolean_)
*   `purchased_quantity` (_number (double)_)
*   `quantity` (_number (double)_)  
    Minimum: 0.
*   `type` (_string_)  
    Allowed values: `product`, `gift_certificate`.

### payment\_bank\_account\_request

Document representing a payment bank account request.

*   `drivers_license` (_string_) The drivers license.  
    Maximum length: 256.
*   `drivers_license_state_code` (_string_) The driver license state code.  
    Maximum length: 256.
*   `holder` (_string_) The holder of the bank account.  
    Maximum length: 256.
*   `number` (_string_) The payment bank account number.  
    Maximum length: 256.

### order\_payment\_card\_request

Document representing an order payment card request.

*   `card_type` (_string_) The payment card type (for example, 'Visa').  
    Maximum length: 256.
*   `credit_card_expired` (_boolean_) A flag indicating if the credit card is expired.
*   `credit_card_token` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.
*   `expiration_month` (_integer (int32)_) The month when the payment card expires.
*   `expiration_year` (_integer (int32)_) The year when the payment card expires.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256.
*   `issue_number` (_string_) The payment card issue number.  
    Maximum length: 256.
*   `number` (_string_) The payment card number.  
    Maximum length: 4000.
*   `security_code` (_string_) The security code for the payment card.  
    Maximum length: 4.
*   `valid_from_month` (_integer (int32)_) The payment card valid from month.  
    Minimum: 1. Maximum: 12.
*   `valid_from_year` (_integer (int32)_) The payment card valid from year.

### payment\_method

Document representing a payment method.

*   `cards` (_array of payment\_card\_spec_) The sorted array of payment cards (included only when the system payment method is CREDIT\_CARD).
*   `description` (_string_) The localized description of the payment method or card.
*   `id` (_string_, required) The id of the payment method or card.  
    Maximum length: 256.
*   `image` (_string_) The URL to the image that represents the payment method or card.
*   `name` (_string_) The localized name of the payment method or card.
*   `payment_processor_id` (_string_) The payment processor ID.

_Example_

```
{
  "cards": [
    {
      "card_type": "Visa",
      "checksum_verification_enabled": true,
      "id": "CREDIT_CARD.Visa",
      "name": "Visa",
      "number_lengths": [
        "13",
        "16"
      ],
      "number_prefixes": [
        "4"
      ],
      "security_code_length": 3
    },
    {
      "card_type": "Master",
      "checksum_verification_enabled": true,
      "id": "CREDIT_CARD.Master",
      "name": "Mastercard",
      "number_lengths": [
        "16"
      ],
      "number_prefixes": [
        "2221-2720",
        "51-55"
      ],
      "security_code_length": 3
    },
    {
      "card_type": "Amex",
      "checksum_verification_enabled": true,
      "id": "CREDIT_CARD.Amex",
      "name": "American Express",
      "number_lengths": [
        "15"
      ],
      "number_prefixes": [
        "34",
        "37"
      ],
      "security_code_length": 4
    }
  ],
  "id": "CREDIT_CARD",
  "name": "Credit Card",
  "c_somestring": "PaymentMethod String Value"
}
```

### discount\_request

Document representing a discount to be applied to a custom price adjustment. The properties `type` and `value` are mandatory.

The type amount describes a (unit) price discount, and its corresponding value (positive) defines the amount each unit is to be reduced. For example, for a $10 discount:

{ "discount" : {"type" : "amount", "value" : 10.00 }, ... }

The type percentage describes a percentage discount, and its corresponding value (positive) defines the percentage reduction. For example, for a 5% discount:

{ "discount" : {"type" : "percentage", "value" : 5 }, ... }

The type fixed\_price describes a fixed price discount, and its corresponding value (positive) defines the resulting fixed price for the item. Only one fixed\_price discount can be set for each item. For example, to set a fixed price of $15 for the item:

{ "discount" : {"type" : "fixed\_price", "value" : 15.00 }, ... }

The type `fixed_price` is not supported at the order level.

*   `type` (_string_, required) The type of discount.  
    Allowed values: `percentage`, `fixed_price`, `amount`.
*   `value` (_number (double)_, required) The amount of the discount.

### discount

Document representing a discount that was _either_ optionally applied when creating a custom price adjustment _or_ applied by the promotion engine. The property `type` is mandatory; the properties `amount` and `priceBookId` are used only in association with specific types. Some examples:

*   Type `percentage` with percentage `15.00` : a 15% discount was applied.
    
*   Type `amount` with amount `5.99` : a discount was applied to reduce the (unit) price by 5.99.
    
*   Type `fixed_price` with amount `49.99` : a discount was applied to reduce the price to 49.99.
    
*   Type `free` : a discount was applied to reduce the price to zero.
    
*   Type `price_book_price` with price\_book\_id `MyPriceBook` : a discount was applied to set the price to that defined in MyPriceBook.
    

*   `amount` (_number (double)_) The amount that is used with the amount and fixed price types.
*   `percentage` (_number (double)_) The percentage that is used with percentage types.
*   `price_book_id` (_string_) The price book id that is used with some types.
*   `type` (_string_, required) The type of discount.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`.

_Example_

```
{
  "amount": 15,
  "type": "amount"
}
```

### shipping\_promotion

Document representing a shipping promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotion_name` (_string_) The localized promotion name.

### product\_details\_link

Document representing a link to the resource for product details.

*   `link` (_string_) The target of the link.
*   `product_description` (_string_) The description of the product.
*   `product_id` (_string_, required) The id of the product.
*   `product_name` (_string_) The name of the product.
*   `title` (_string_) The link title.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/products/BlueJeansType1",
  "product_id": "BlueJeansType1",
  "product_name": "Product w/- Local Option",
  "title": "Product w/- Local Option"
}
```

### status

Document representing a status of an object.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_)
    
    The status.
    
    For more information on the status values see dw.system.Status.OK and dw.system.Status.ERROR.
    

### payment\_bank\_account

Document representing a payment bank account.

*   `drivers_license_last_digits` (_string_) The last 4 characters of the decrypted driver's license number of the bank account associated with this payment instrument.  
    Maximum length: 256.
*   `drivers_license_state_code` (_string_) The driver license state code.  
    Maximum length: 256.
*   `holder` (_string_) The holder of the bank account.  
    Maximum length: 256.
*   `masked_drivers_license` (_string_)
    
    The decrypted driver's license number of the bank account with all but the last 4 characters replaced with a '\*' character.
    
    ```
         with a '*' character.
    ```
    
      
    Maximum length: 256.
*   `masked_number` (_string_) The bank account masked number.  
    Maximum length: 256.
*   `number_last_digits` (_string_) The last digits of the bank account number.  
    Maximum length: 256.

_Example_

```
{
  "drivers_license_last_digits": "ense",
  "drivers_license_masked": "**************ense",
  "number_last_digits": "mber",
  "number_masked": "*************mber"
}
```

### payment\_card

Document representing a payment card.

*   `card_type` (_string_) The payment card type (for example, 'Visa').  
    Maximum length: 256.
*   `credit_card_expired` (_boolean_) A flag indicating if the credit card is expired.
*   `credit_card_token` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.
*   `expiration_month` (_integer (int32)_) The month when the payment card expires.
*   `expiration_year` (_integer (int32)_) The year when the payment card expires.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256.
*   `issue_number` (_string_) The payment card issue number.  
    Maximum length: 256.
*   `masked_number` (_string_) The masked credit card number.  
    Maximum length: 4000.
*   `number_last_digits` (_string_) The last digits of credit card number.  
    Maximum length: 4000.
*   `valid_from_month` (_integer (int32)_) The payment card valid from month.  
    Minimum: 1. Maximum: 12.
*   `valid_from_year` (_integer (int32)_) The payment card valid from year.

_Example_

```
{
  "card_type": "Visa",
  "credit_card_expired": false,
  "expiration_month": 2,
  "expiration_year": 2022,
  "holder": "John Smith",
  "masked_number": "***********ber2",
  "number_last_digits": "ber2"
}
```

### promotion\_link

Document representing a promotion link.

*   `callout_msg` (_string (html)_) The localized call-out message of the promotion.
*   `link` (_string_)
*   `name` (_string_) The localized name of the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `title` (_string_)

### product\_list\_link

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `link` (_string_) The target of the link.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`.

### payment\_card\_spec

Document representing the specification for a payment card.

The information in the specification can be used to verify data entered by a customer before sending to the payment authorization. The configuration can be made in the payment methods section in Business Manager.

*   `card_type` (_string_) The type of the payment card.
*   `checksum_verification_enabled` (_boolean_)
    
    A flag indicating whether the card number is verified using the Luhn checksum algorithm.
    
    ```
         <code>false</code>
    ```
    
*   `description` (_string_) The localized description of the payment card.
*   `image` (_string_) The URL to the image that represents the payment card.
*   `name` (_string_) The localized name of the payment card.
*   `number_lengths` (_array of string_) The sorted list of number lengths (individual lengths as well as length ranges).
*   `number_prefixes` (_array of string_) The sorted list of number prefixes (individual prefixes as well as prefix ranges).
*   `security_code_length` (_integer (int32)_) The length of the security code for this card.

_Example_

```
{
  "card_type": "Visa",
  "checksum_verification_enabled": true,
  "id": "CREDIT_CARD.Visa",
  "name": "Visa",
  "number_lengths": [
    "13",
    "16"
  ],
  "number_prefixes": [
    "4"
  ],
  "security_code_length": 3
}
```

<!-- document id=32999236db2abb244cdfef324e592456988000938fd71d10a8ffd26ecb064b5d url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-categories.md -->

Shop Categories (deprecated)

# Shop Categories (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get multiple categories

`GET /categories/({ids})`

Operation ID: `Get multiple categories`. Tags: categories. Security: client\_id; customers\_auth.

When you use the URL template below, the server returns multiple categories (a result object of category documents). You can use this template as a convenient way of obtaining multiple categories in a single request, instead of issuing separate requests for each category. You can specify multiple ids (up to a maximum of 50). You must enclose the list of ids in parentheses. If a category identifier contains a parenthesis or the separator sign, you must URL encode the character.

This endpoint fetches both online and offline categories. For offline categories, only the top-level category is returned, not offline subcategories.

Using a large value for levels can cause performance issues when there is a large and deep category tree.

#### Parameters

*   `ids` (path, array of string, required) The comma separated list of category ids.  
    Maximum length: 256.
*   `levels` (query, integer (int32)) Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2. Only online subcategories are returned.  
    Minimum: 0.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category_result`.
    

### GET Get category

`GET /categories/{id}`

Operation ID: `Get category`. Tags: categories. Security: client\_id; customers\_auth.

When you use the URL template below, the server returns a category identified by its id; by default, the server also returns the first level of subcategories, but you can specify another level by setting the levels parameter.

This endpoint fetches both online and offline categories. For offline categories, only the top-level category is returned, not offline subcategories.

Using a large value for levels can cause performance issues when there is a large and deep category tree.

This endpoint may return the following faults:

*   404 - CategoryNotFoundException - Thrown if no online or offline category is found with the specified ID.

#### Parameters

*   `id` (path, string, required) The id of the requested category.  
    Maximum length: 256.
*   `levels` (query, integer (int32)) Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2. Only online subcategories are returned.  
    Minimum: 0.
*   `locale` (query, string) The locale context.

#### Responses

*   **404** `CategoryNotFoundException` - Thrown if no online or offline category is found with the specified ID.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `category`.
    

## Schemas

### category\_result

Result document containing an array of categories.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of category_) The array of category documents.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "description": "",
      "id": "mens",
      "image": "http://foo.com.bar.jpg",
      "name": "Mens",
      "parent_category_id": "root",
      "thumbnail": "http://foo.com.bar.jpg"
    },
    {
      "description": "",
      "id": "womens",
      "image": "http://foo.com.bar.jpg",
      "name": "Womens",
      "parent_category_id": "root",
      "thumbnail": "http://foo.com.bar.jpg"
    }
  ],
  "total": 2
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### category

Document representing a category.

*   `categories` (_array of category_) Array of subcategories. Can be empty.
*   `description` (_string_) The localized description of the category.
*   `id` (_string_) The id of the category.
*   `image` (_string_) The URL to the category image.
*   `name` (_string_) The localized name of the category.
*   `page_description` (_string_) The localized page description of the category.
*   `page_keywords` (_string_) The localized page keywords of the category.
*   `page_title` (_string_) The localized page title of the category.
*   `parent_category_id` (_string_) The id of the parent category.
*   `parent_category_tree` (_array of path\_record_) List of parent categories
*   `thumbnail` (_string_) The URL to the category thumbnail.

_Example_

```
{
  "categories": [
    {
      "categories": [
        {
          "description": "",
          "id": "footwear",
          "image": "http://foo.com.bar.jpg",
          "name": "Footwear",
          "parent_category_id": "mens",
          "thumbnail": "http://foo.com.bar.jpg"
        },
        {
          "description": "",
          "id": "clothing",
          "image": "http://foo.com.bar.jpg",
          "name": "Clothing",
          "parent_category_id": "mens",
          "thumbnail": "http://foo.com.bar.jpg"
        }
      ],
      "description": "",
      "id": "mens",
      "image": "http://foo.com.bar.jpg",
      "name": "Mens",
      "parent_category_id": "root",
      "thumbnail": "http://foo.com.bar.jpg"
    },
    {
      "categories": [
        {
          "description": "",
          "id": "footwear",
          "image": "http://foo.com.bar.jpg",
          "name": "Footwear",
          "parent_category_id": "womens",
          "thumbnail": "http://foo.com.bar.jpg"
        },
        {
          "description": "",
          "id": "clothing",
          "image": "http://foo.com.bar.jpg",
          "name": "Clothing",
          "parent_category_id": "womens",
          "thumbnail": "http://foo.com.bar.jpg"
        }
      ],
      "description": "",
      "id": "womens",
      "image": "http://foo.com.bar.jpg",
      "name": "Womens",
      "parent_category_id": "root",
      "thumbnail": "http://foo.com.bar.jpg"
    }
  ],
  "id": "root"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### path\_record

Document representing most basic info (id and name) of a category or catalog.

*   `id` (_string_) The id of the category path.
*   `name` (_string_) The name of the category path.

<!-- document id=72f1e39ea2c3dac9ad22771ec117b34f500a3996c2b9638f18d5577b26798e57 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-content.md -->

Shop Content (deprecated)

# Shop Content (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get multiple content

`GET /content/({ids})`

Operation ID: `Get multiple content`. Tags: content. Security: client\_id; customers\_auth.

To access multiple content asset, you construct a URL using the template shown below. This template requires you to specify one or many content asset id. In response, the server returns a result set of corresponding content asset documents. Only content assets, which are marked as online are returned. An assignment to a folder is not necessary.

#### Parameters

*   `ids` (path, array of string, required) The ids of the requested content assets  
    Maximum length: 256.
*   `locale` (query, string) The locale context

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_result`.
    

### GET Get content

`GET /content/{id}`

Operation ID: `Get content`. Tags: content. Security: client\_id; customers\_auth.

To access a content asset, you construct a URL using the template shown below. This template requires you to specify a content asset id. In response, the server returns a corresponding content asset document. Only content assets, which are marked as online are returned. An assignment to a folder is not necessary.

#### Parameters

*   `id` (path, string, required) The id of the requested content asset.  
    Maximum length: 256.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content`.
    

## Schemas

### content\_result

Result document containing an array of content assets.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of content_) The array of content assets.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "description": "It all started with a series of observations ...",
      "id": "about-us",
      "name": "About Us",
      "c_body": "&lt;h1&gt;About Us&lt;/h1&gt;&lt;h2&gt;It all started with a series of observations ...",
      "c_customCSSFile": "http://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites-SiteGenesis-Library/default/v1365077029384/css/aboutus.css"
    },
    {
      "description": "These terms of use set forth the basis on which you are permitted to access and use this website, example.com",
      "id": "terms",
      "name": "Terms & Conditions of Sale",
      "c_body": "&lt;h1&gt;Terms & Conditions of Sale&lt;/h1&gt;&lt;p&gt;ATTENTION: These terms of use set forth the basis on which you are permitted ..."
    }
  ],
  "total": 2
}
```

### content

Document representing a content asset.

*   `description` (_string_) The localized content asset description.
*   `id` (_string_, required) The id of the content asset.  
    Minimum length: 1. Maximum length: 256.
*   `name` (_string_) The localized content asset name.
*   `page_description` (_string_) The localized content asset page description.
*   `page_keywords` (_string_) The localized content asset page description.
*   `page_title` (_string_) The localized content asset page title.

_Example_

```
{
  "description": "It all started with a series of observations...",
  "id": "about-us",
  "name": "About Us",
  "c_body": "&lt;h1&gt;About Us&lt;/h1&gt;&lt;h2&gt;It all started with a series of observations ...",
  "c_customCSSFile": "http://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites-SiteGenesis-Library/default/v1365077029384/css/aboutus.css"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=21e5835bbb3a854dcc42060f2c79727eaa791e8868054dd63ba8662dedfc0574 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-content-search.md -->

Shop Content Search (deprecated)

# Shop Content Search (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Search content

`GET /content_search`

Operation ID: `Search content`. Tags: content\_search. Security: client\_id; customers\_auth.

Provides keyword and refinement search functionality for content assets. The search result contains only content that is online and assigned to a folder.

#### Parameters

*   `q` (query, string) The query phrase to search for.  
    Maximum length: 50.
*   `refine` (query, array of string)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute id and value(s) are separated by '='. Multiple values are supported by a sub-set of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=foo=(100..500) Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementType=type1|type2|type3. The following system refinement attribute ids are supported:
    
    *   fdid: Allows to refine per single content folder id. Multiple folder ids are not supported.
        
*   `sort` (query, array of string) Parameter that represents a sorting attribute/value(s) pair. Sorting attribute id and value are separated by '='. The value describes the sort direction. Possible values are 'asc' and 'desc', for ascending or descending sort direction. I.e. sort=c\_myAttribute=desc. Precondition: You have to select your sorting attributes in Business Manager > YourSite > Search Indexes > Content Index > Sorting Attributes.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_search_result`.
    

## Schemas

### content\_search\_result

Document representing a content search result.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object_)
*   `hits` (_array of content_) The sorted array of search hits. Can be empty.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `query` (_string_) The query String that was searched for.
*   `refinements` (_array of content\_search\_refinement_) The sorted array of search refinements. Can be empty.
*   `selected_refinements` (_object_) Map of selected refinement attribute id/value(s) pairs. The sorting order is the same like in request URL.
    
    Additional properties: `string`.
    
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 4,
  "hits": [
    {
      "description": "Welcome to B2C Commerce. At B2C Commerce we recognize all good success starts with people ...",
      "id": "jobs-landing",
      "name": "Jobs Landing Page",
      "c_body": "&lt;div&gt;&lt;h1&gt;Careers at B2C Commerce&lt;/h1&gt;&lt;hr /&gt;&lt;p&gt;Welcome to B2C Commerce ... "
    },
    {
      "description": "It all started with a series of observations: eCommerce merchandising and marketing innovation is what generates the revenue ...",
      "id": "about-us",
      "name": "About Us",
      "c_body": "&lt;h1\"&gt;About Us&lt;/h1&gt;&lt;h2&gt;It all started with a series of observations ...",
      "c_customCSSFile": "http://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites-SiteGenesis-Library/default/v1365077029384/css/aboutus.css"
    },
    {
      "description": "Interested in getting more information about B2C Commerce and our On-Demand eCommerce solution? Here is information on office locations ...",
      "id": "contact-us-details",
      "name": "Contact Us Details",
      "c_body": "&lt;h5&gt;Connect with B2C Commerce&lt;/h5&gt;&lt;div&gt;&lt;p&gt;Interested in getting more information ..."
    },
    {
      "description": "With B2C Commerce ecommerce, they're spending more time leading with merchandising and marketing. They're in complete control over their site ...",
      "id": "history",
      "name": "Our Story",
      "c_body": "&lt;p&gt;&lt;strong&gt;It all started with a series of observations:&lt;/strong&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;eCommerce merchandising ..."
    }
  ],
  "query": "about",
  "refinements": [
    {
      "attribute_id": "fdid",
      "label": "About Us",
      "values": [
        {
          "hit_count": 4,
          "label": "About B2C Commerce",
          "value": "about-us",
          "values": [
            {
              "hit_count": 1,
              "label": "Our Story",
              "value": "our-story"
            },
            {
              "hit_count": 0,
              "label": "Our Team",
              "value": "our-team"
            },
            {
              "hit_count": 0,
              "label": "As Seen In",
              "value": "as-seen-in"
            },
            {
              "hit_count": 1,
              "label": "Contact Us",
              "value": "contact-us-new"
            },
            {
              "hit_count": 1,
              "label": "Join Us",
              "value": "employment"
            }
          ]
        },
        {
          "hit_count": 0,
          "label": "Customer Service",
          "value": "customer-service"
        }
      ]
    }
  ],
  "selected_refinements": {
    "fdid": "about-us"
  },
  "start": 0,
  "total": 4
}
```

### content

Document representing a content asset.

*   `description` (_string_) The localized content asset description.
*   `id` (_string_, required) The id of the content asset.  
    Minimum length: 1. Maximum length: 256.
*   `name` (_string_) The localized content asset name.
*   `page_description` (_string_) The localized content asset page description.
*   `page_keywords` (_string_) The localized content asset page description.
*   `page_title` (_string_) The localized content asset page title.

_Example_

```
{
  "description": "It all started with a series of observations...",
  "id": "about-us",
  "name": "About Us",
  "c_body": "&lt;h1&gt;About Us&lt;/h1&gt;&lt;h2&gt;It all started with a series of observations ...",
  "c_customCSSFile": "http://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites-SiteGenesis-Library/default/v1365077029384/css/aboutus.css"
}
```

### content\_search\_refinement

Document representing a search refinement attribute.

*   `attribute_id` (_string_, required) The id of the search refinement attribute. In the case of an attribute refinement, this is the attribute id. Custom attributes are marked by the prefix "c\_".
*   `label` (_string_) The localized label of the refinement.
*   `values` (_array of content\_search\_refinement\_value_) The sorted array of refinement values. The array can be empty.

### content\_search\_refinement\_value

Document representing a search refinement value.

*   `description` (_string_) The localized description of the refinement value.
*   `hit_count` (_integer (int32)_) The number of search hits (0 or more) when selecting the refinement value.
*   `label` (_string_) The localized label of the refinement value.
*   `presentation_id` (_string_) The optional presentation id associated with the refinement value. The presentation id can be used, for example, to associate an id with an HTML widget.
*   `value` (_string_) The refinement value. In the case of an attribute refinement, this is the bucket, the attribute value, or a value range. In the case of a content folder refinement, this is the folder id.
*   `values` (_array of content\_search\_refinement\_value_) The array of hierarchical refinement values. This array can be empty.

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=4a6b410649ec7872bdd8eb66cf6a52a1ebcacfe9b49105f23c5da030d283fd74 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-custom-objects.md -->

Shop Custom Objects (deprecated)

# Shop Custom Objects (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Read custom object

`GET /custom_objects/{object_type}/{key}`

Operation ID: `Read custom object`. Tags: custom\_objects. Security: client\_id; customers\_auth.

Reads a custom object with a given object type ID and a value for the key attribute of the object which represents its unique identifier.

This endpoint may return the following faults:

*   400 - MalformedKeyParameterException - If the object key must be an integer, but the path parameter has an invalid format
*   404 - CustomObjectNotFoundException - If the custom object cannot be found
*   404 - ObjectTypeNotFoundException - For an unknown object type ID

#### Parameters

*   `object_type` (path, string, required) the ID of the object type  
    Minimum length: 1.
*   `key` (path, string, required) the key attribute value of the custom object  
    Minimum length: 1.

#### Responses

*   **400** `MalformedKeyParameterException` - If the object key must be an integer, but the path parameter has an invalid format
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomObjectNotFoundException` - If the custom object cannot be found or `ObjectTypeNotFoundException` - For an unknown object type ID
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `custom_object`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### custom\_object

Document representing a custom object that contains all defined custom attributes for its object type.

*   `key_property` (_string_) The name of the key property for the custom object.
*   `key_value_integer` (_integer (int32)_) The id of the custom object when the type of the key is Integer.
*   `key_value_string` (_string_) The id of the custom object when the type of the key is String.
*   `object_type` (_string_) The id of the object type.  
    Maximum length: 256.

_Example_

```
{
  "key_property": "key_attribute",
  "object_type": "my_object_type",
  "c_boolean": true,
  "c_date": "2015-02-03T00:00:00.000Z",
  "c_email": "jdoe@salesforce.com",
  "c_integer": 42,
  "c_number": 42,
  "c_string": "some text"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=578462e6c6c44d27c89526fca2536f3ca7634b39bb11aa1aab8373825d779763 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-customers.md -->

Shop Customers (deprecated)

# Shop Customers (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Register customer

`POST /customers`

Operation ID: `Register customer`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Registers a customer.

You must specify the login credentials, last name, and email address. This method ignores all other data, which can only be set for an existing customer. To set other values, make calls after the customer is created.

When using OAuth, don't include the password in the request. In this case, including the password throws an `InvalidPasswordException` .

When using JWT, the password is required.

Also returns the hashedLoginId for Einstein use cases.

Note: If customers are created using OCAPI call then any updated to the customer records should be done through OCAPI calls as well. The customer records created with Script API call should not be updated with OCAPI calls as the email validation is handled differently in these calls and may result in InvalidEmailException.

This endpoint may return the following faults:

*   400 - CustomerAlreadyRegisteredException - Indicates that the resource is called with JWT representing a registered customer.
*   400 - InvalidLoginException - Indicates that login doesn't match acceptance criteria.
*   400 - InvalidPasswordException - Indicates that password doesn't match acceptance criteria.
*   400 - LoginAlreadyInUseException - Indicates that the given login is already used.
*   400 - MissingEmailException - Indicates that request document does not contain email.
*   400 - MissingLastNameException - Indicates that request document does not contain last\_name.
*   400 - MissingLoginException - Indicates that request document does not contain login.
*   400 - MissingPasswordException - Indicates that password was not provided in JWT scenario.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_registration`.

#### Responses

*   **400** `CustomerAlreadyRegisteredException` - Indicates that the resource is called with JWT representing a registered customer. or `InvalidLoginException` - Indicates that login doesn't match acceptance criteria. or `InvalidPasswordException` - Indicates that password doesn't match acceptance criteria. or `LoginAlreadyInUseException` - Indicates that the given login is already used. or `MissingEmailException` - Indicates that request document does not contain email. or `MissingLastNameException` - Indicates that request document does not contain last\_name. or `MissingLoginException` - Indicates that request document does not contain login. or `MissingPasswordException` - Indicates that password was not provided in JWT scenario.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### POST Get or refresh customer JWT (JSON Web Token)

`POST /customers/auth`

Operation ID: `Get or refresh customer JWT (JSON Web Token)`. Tags: customers. Security: client\_id.

Obtains a new JWT (JSON Web Token) for a guest or registered customer. Tokens are returned as a HTTP Authorization:Bearer response header entry. These kinds of request are supported, as specified by the `type` :

*   Type _guest_ \- creates a new guest (non-authenticated) customer and returns a token for the customer.
    
*   Type _credentials_ \- authenticates credentials passed in the HTTP Authorization:Basic request header, returning a token for a successfully authenticated customer, otherwise it throws an AuthenticationFailedException.
    
*   Type _session_ \- authenticates the customer (anonymous or registered) based on the _dwsid_ and _dwsecuretoken_ cookies. It returns a token for a successfully authenticated customer, otherwise it throws an AuthenticationFailedException.
    
*   Type _refresh_ \- examines the token passed in the HTTP Authorization:Bearer request header and when valid returns a new token with an updated expiry time.
    

For a request of type _credentials_ :

*   Updates profile attributes for the customer (for example, "last-visited").
    
*   Handles the maximum number of failed login attempts.
    

For a request of type _session_ :

*   The session and corresponding _dwsecuretoken_ must be active and valid. An expired session can't be used. The _dwsecuretoken_ cookie must have been used for at least one previous HTTPS request with the same _dwsid_ cookie.
    
*   Does not touch profile attributes for the registered customer (for example, "last-visited"), since this is not a real login.
    
*   Returns different tokens for multiple requests with the same session id. Means, there should be only one call per session.
    

About JWT

The token contains 3 sections:

*   the _header_ section (specifies token type and algorithm used)
    
*   the _payload_ section (contains customer information, client id, issue and expiration time)
    
*   finally the _signature_ section records the token signature.
    

A token is created and returned to the client whenever a registered customer logs in (type "credentials") or a guest customer requests it (type "guest"). The token is returned in the response header as `Authorization: Bearer --token--` The client has to include the token in the request header as `Authorization: Bearer --token--` in any follow up request. The server declines any follow up requests without a token or which cannot be verified based on the token signature or expiration time. A token nearing its expiration time should be exchanged for a new one (type "refresh"). See "API Usage > JWT" for more details on using JWT as an authentication mechanism.

This endpoint may return the following faults:

*   400 - AuthorizationBasicMissingException - Indicates that no HTTP Authorization:Basic header was provided.
*   401 - AuthenticationFailedException - Indicates in case of type _credentials_ the username is unknown or the password does not match. In case of type _session_ the session is not active anymore or the _dwsecuretoken_ value is invalid. In both cases the customer is disabled or locked.

#### Parameters

*   `Authorization` (header, string)
    *   Authorization:Basic for type `credentials`
        
    *   Authorization:Bearer for type `refresh`
        

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `auth_request`.

#### Responses

*   **400** `AuthorizationBasicMissingException` - Indicates that no HTTP Authorization:Basic header was provided.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **401** `AuthenticationFailedException` - Indicates in case of type _credentials_ the username is unknown or the password does not match. In case of type _session_ the session is not active anymore or the _dwsecuretoken_ value is invalid. In both cases the customer is disabled or locked.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### DELETE Invalidate an existing customer JWT (JSON Web Token)

`DELETE /customers/auth`

Operation ID: `Invalidate an existing customer JWT (JSON Web Token)`. Tags: customers. Security: client\_id; customers\_auth.

Invalidates the JWT provided in the header.

#### Parameters

*   `Authorization` (header, string) the JWT

#### Responses

*   **204**

### POST Authorize Trusted System Client

`POST /customers/auth/trustedsystem`

Operation ID: `Authorize Trusted System Client`. Tags: customers. Security: oauth2\_application; client\_id.

Obtain the JWTs for registered customers whose credentials are stored using a third party system.

*   Accepts `login_id` and `client_id`
    
*   Returns a customer object in the response body, and the JWT generated against the `client_id` in the response header. In addition, the returned response will include the hashedLoginId field for Einstein use.
    

This endpoint may return the following faults:

*   401 - AuthenticationFailedException -

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `trusted_system_auth_request`.

#### Responses

*   **401** `AuthenticationFailedException` -
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### GET Get customerExtProfile

`GET /customers/ext_profile`

Operation ID: `Get customerExtProfile`. Tags: customers. Security: oauth2\_application; client\_id.

Gets the customerExtProfile based on the passed in query parameters of external\_id and authentication\_provider\_id

This endpoint may return the following faults:

*   400 - MissingAuthenticationProviderException - Indicates that authentication\_provider\_id is not provided.
*   400 - MissingExternalIDException - Indicates that External\_id is not provided.

#### Parameters

*   `external_id` (query, string, required)  
    Minimum length: 1.
*   `authentication_provider_id` (query, string, required)  
    Minimum length: 1.

#### Responses

*   **400** `MissingAuthenticationProviderException` - Indicates that authentication\_provider\_id is not provided. or `MissingExternalIDException` - Indicates that External\_id is not provided.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customers_ext_profile`.
    

### POST Register customerExtProfile

`POST /customers/ext_profile`

Operation ID: `Register customerExtProfile`. Tags: customers. Security: customers\_auth; client\_id.

Register a customerExtProfile. The mandatory data are the external\_id and authentication\_provider\_id.

While using JWT the guest JWT needs to be used.

This will not be supporting hooks

This endpoint may return the following faults:

*   400 - CustomerAlreadyRegisteredException - Indicates that the resource is called with JWT representing a registered customer and not a guest JWT.
*   400 - CustomerExtProfileAlreadyExistException - Indicates that the customer external profile already exists.
*   400 - InvalidCustomerExtProfileException - Indicates that customerExtProfileCreation failed.
*   400 - InvalidEmailException - Indicates that the email sent in through the request document is not valid.
*   400 - InvalidLoginException - Indicates that login doesn't match acceptance criteria.
*   400 - LoginAlreadyInUseException - Indicates that the given login already exists.
*   400 - MissingAuthenticationProviderException - Indicates that request document does not contain authentication\_provider\_id.
*   400 - MissingExternalIDException - Indicates that request document does not contain External\_id.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customers_ext_profile`.

#### Responses

*   **400** `CustomerAlreadyRegisteredException` - Indicates that the resource is called with JWT representing a registered customer and not a guest JWT. or `CustomerExtProfileAlreadyExistException` - Indicates that the customer external profile already exists. or `InvalidCustomerExtProfileException` - Indicates that customerExtProfileCreation failed. or `InvalidEmailException` - Indicates that the email sent in through the request document is not valid. or `InvalidLoginException` - Indicates that login doesn't match acceptance criteria. or `LoginAlreadyInUseException` - Indicates that the given login already exists. or `MissingAuthenticationProviderException` - Indicates that request document does not contain authentication\_provider\_id. or `MissingExternalIDException` - Indicates that request document does not contain External\_id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customers_ext_profile`.
    

### POST Reset Password Token

`POST /customers/password/actions/create_reset_token`

Operation ID: `Reset Password Token`. Tags: customers. Security: oauth2\_application; client\_id.

Returns a reset password token for the passed in customer's login that will be used with the customers/reset\_password endpoint to change the customer's password.

This differs from the customers/password\_reset endpoint as it does not require or allow before or after hook processing.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer with the given login id is unknown.
*   400 - MissingLoginException - Indicates that login id is missing from the request.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `reset_password_token_request`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer with the given login id is unknown. or `MissingLoginException` - Indicates that login id is missing from the request.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `reset_password_token_result`.
    

### POST Reset Customer Password

`POST /customers/password/actions/reset`

Operation ID: `Reset Customer Password`. Tags: customers. Security: oauth2\_application; client\_id.

Changes the customer's password to the new password value in the call using the reset password token that was returned from the customers/reset\_password\_token endpoint.

This differs from the customers/password\_reset endpoint as it does not require or allow before or after hook processing.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates there was a problem with the passed in values.
*   400 - InvalidPasswordException - Indicates that the rest password failed.
*   400 - MissingLoginException - Indicates that login id is missing from the request.
*   400 - MissingResetTokenException - Indicates that reset\_token is missing from the request..

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `reset_password_request`.

#### Responses

*   **204**
*   **400** `InvalidCustomerException` - Indicates there was a problem with the passed in values. or `InvalidPasswordException` - Indicates that the rest password failed. or `MissingLoginException` - Indicates that login id is missing from the request. or `MissingResetTokenException` - Indicates that reset\_token is missing from the request..
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### POST Starts a password reset process

`POST /customers/password_reset`

Operation ID: `Starts a password reset process`. Tags: customers. Security: client\_id.

First the beforePOST hook is called. After that the validation of the customer information provided in the the password reset document is performed. Then a password reset token is generated and together with the resolved customer is passed to a afterPOST hook. The customer resolution is based on the password reset request type. Both hooks are performed in a single transaction. Currently the resolution can be done by email or login. In case of an email the password reset hook is only executed if one and only one customer has been identified for that email. In the case that more than one customers have been identified for the provided email the resource does nothing.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `password_reset`.

#### Responses

*   **204**

### GET Get a Customer

`GET /customers/{customer_id}`

Operation ID: `Get a Customer`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Gets a customer.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - If customerId URL parameter does not match the verified customer represented by the JWT (not relevant when using OAuth).
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) The customer id  
    Minimum length: 1.
*   `expand` (query, array of string) The expand parameter. A comma separated list with the allowed values ( _addresses, paymentinstruments_ ).

#### Responses

*   **400** `InvalidCustomerException` - If customerId URL parameter does not match the verified customer represented by the JWT (not relevant when using OAuth).
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### PATCH Update a Customer

`PATCH /customers/{customer_id}`

Operation ID: `Update a Customer`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Updates a customer. This endpoint can't update login credentials.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - If customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidEmailException - Indicates that the provided email is not valid.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) the customer id  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer`.

#### Responses

*   **400** `InvalidCustomerException` - If customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidEmailException` - Indicates that the provided email is not valid.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### GET Get all customer addresses

`GET /customers/{customer_id}/addresses`

Operation ID: `Get all customer addresses`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns a sorted pageable list of all customer addresses in the address book. The default page size is 10 customer addresses. The addresses are sorted so that the preferred address is always sorted first. The remaining addresses are sorted alphabetically by ID.

When the customer cannot be found `CustomerNotFoundException` is thrown in a case of an agent but an empty result list is returned in a case of JWT.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - If customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.

#### Parameters

*   `customer_id` (path, string, required) The customer uuid  
    Minimum length: 1.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0. Maximum: 999.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.

#### Responses

*   **400** `InvalidCustomerException` - If customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address_result`.
    

### POST Create customer address

`POST /customers/{customer_id}/addresses`

Operation ID: `Create customer address`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Creates a new address with the given name for the given customer.

This endpoint may return the following faults:

*   400 - AddressIdAlreadyInUseException - Indicates that the provided address name is already used for the customer.
*   400 - InvalidCustomerAddressIdException - Indicates that address name is not provided or it's blank.
*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to create the address for  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_address`.

#### Responses

*   **400** `AddressIdAlreadyInUseException` - Indicates that the provided address name is already used for the customer. or `InvalidCustomerAddressIdException` - Indicates that address name is not provided or it's blank. or `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address`.
    

### GET Get customer address

`GET /customers/{customer_id}/addresses/{address_name}`

Operation ID: `Get customer address`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Retrieves a customer's address by address name.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerAddressNotFoundException - Indicates that the address with the given name in unknown for the customer with the given customer id.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to retrieve the address for  
    Minimum length: 1.
*   `address_name` (path, string, required) the name of the address to retrieve  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerAddressNotFoundException` - Indicates that the address with the given name in unknown for the customer with the given customer id. or `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address`.
    

### DELETE Delete customer address

`DELETE /customers/{customer_id}/addresses/{address_name}`

Operation ID: `Delete customer address`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Deletes a customer's address by address name.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerAddressNotFoundException - Indicates that the address with the given name in unknown for the customer with the given customer id.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to delete the address for  
    Minimum length: 1.
*   `address_name` (path, string, required) the name of the address to delete  
    Minimum length: 1. Maximum length: 256.

#### Responses

*   **204**
*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerAddressNotFoundException` - Indicates that the address with the given name in unknown for the customer with the given customer id. or `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update customer address

`PATCH /customers/{customer_id}/addresses/{address_name}`

Operation ID: `Update customer address`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Updates a customer's address by address name.

This endpoint may return the following faults:

*   400 - AddressIdAlreadyInUseException - Indicates that the provided new address name is already used for the customer.
*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerAddressNotFoundException - Indicates that the address with the given name in unknown for the customer with the given customer id.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to update the address for  
    Minimum length: 1.
*   `address_name` (path, string, required) the name of the address to update  
    Minimum length: 1. Maximum length: 256.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_address`.

#### Responses

*   **400** `AddressIdAlreadyInUseException` - Indicates that the provided new address name is already used for the customer. or `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerAddressNotFoundException` - Indicates that the address with the given name in unknown for the customer with the given customer id. or `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_address`.
    

### POST Get an agent on behalf of customer token

`POST /customers/{customer_id}/auth`

Operation ID: `Get an agent on behalf of customer token`. Tags: customers. Security: customers\_auth; oauth2\_application.

Obtains a new agent on behalf token for a registered customer. Token is returned as a HTTP Authorization:Bearer response header entry.

A token is created and returned to the client whenever an agent with `Create_Order_On_Behalf_Of` permission calls the resource for a registered customer.

The token is returned in the response header as `Authorization: Bearer --token--` .

The client has to include the token in the request header as `Authorization: Bearer --token--`

in any follow up request, the agent will do on behalf of the customer.

About the order on behalf token

The token contains 3 sections:

*   the _header_ section (specifies token type and algorithm used)
    
*   the _payload_ section (contains customer information, client id, issue and expiration time)
    
*   finally the _signature_ section records the token signature.
    

A token nearing its expiration time should be exchanged for a new one by calling this resource once more.

#### Parameters

*   `customer_id` (path, string, required) specifies the customer to act on behalf of  
    Minimum length: 1.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer`.
    

### GET Get customer basket

`GET /customers/{customer_id}/baskets`

Operation ID: `Get customer basket`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Gets the baskets of a customer. From v24.1 onwards, the fetched baskets will also include the customer's temporary baskets.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - if customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to retrieve the baskets for  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - if customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `baskets_result`.
    

### GET Get orders of customer

`GET /customers/{customer_id}/orders`

Operation ID: `Get orders of customer`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns a pageable list of all customer's orders. The default page size is 10.

The sum of the values of the start and count parameters should not be more than 10000.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidOrderStatusException - Thrown if specified status is unknown.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.

#### Parameters

*   `customer_id` (path, string, required) the customer uuid  
    Minimum length: 1.
*   `start` (query, integer (int32)) the result set index to return the first instance for; default value is 0  
    Minimum: 0.
*   `count` (query, integer (int32)) the maximum number of instances per request; default value is 10  
    Minimum: 1. Maximum: 200.
*   `cross-sites` (query, boolean) the flag whether all sites should be searched; ignored in case of JWT; default value is `false`
*   `from` (query, string) The from date specifying the date time range to filter orders (inclusive, null allowed, ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ).
*   `until` (query, string) The until date specifying the date time range to filter orders (inclusive, null allowed, ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ).
*   `status` (query, string) The order status of the orders to be retrieved. Status included: created, new, open, completed, cancelled, replaced, failed.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidOrderStatusException` - Thrown if specified status is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_order_result`.
    

### PUT Update a customer's password.

`PUT /customers/{customer_id}/password`

Operation ID: `Update a customer's password.`. Tags: customers. Security: customers\_auth; client\_id.

Updates a customer's password. The default implementation updates the password in the resource.  
Versions prior to 21.3 updated the password in the afterPUT hook, which was incompatible with the Mercury API. Starting in version 21.3, the afterPUT\_v2 hook replaces the afterPUT hook.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - If customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) the customer id  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `password_change_request`.

#### Responses

*   **204**
*   **400** `InvalidCustomerException` - If customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### POST Starts a password reset process for given customer

`POST /customers/{customer_id}/password_reset`

Operation ID: `Starts a password reset process for given customer`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Starts a password reset process. The user must be an agent logged in on behalf of a customer.

Generates a password reset token and passes it with the specified customer as the path parameter to the dw.ocapi.shop.customer.password\_reset.afterPOST hook. The hook can use the provided reset token to perform actions such as sending a reset email.

This endpoint may return the following faults:

*   404 - CustomerNotFoundException - Indicates that the customer specified was not found.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer  
    Minimum length: 1.

#### Responses

*   **204**
*   **404** `CustomerNotFoundException` - Indicates that the customer specified was not found.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get customer payment instruments

`GET /customers/{customer_id}/payment_instruments`

Operation ID: `Get customer payment instruments`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Gets customer payment instruments for an customer. Can be limited to a specific payment method by providing query parameter `payment_method_id` .

When the customer cannot be found `CustomerNotFoundException` is thrown in a case of an agent but an empty result list is returned in a case of JWT.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to retrieve the payment instruments for  
    Minimum length: 1.
*   `payment_method_id` (query, string) the id of the payment method, if null - all payment instruments are retrieved

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_payment_instrument_result`.
    

### POST Add payment instrument for customer

`POST /customers/{customer_id}/payment_instruments`

Operation ID: `Add payment instrument for customer`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Adds a payment instrument to a customer. Note that it can't update the read-only `credit_card_token` on a `payment_card` record.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_payment_instrument_request`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_payment_instrument`.
    

### GET Get customer payment instrument

`GET /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

Operation ID: `Get customer payment instrument`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Retrieves a customer's payment instrument by its id.

This endpoint may return the following faults:

*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - PaymentInstrumentNotFoundException - Indicates that the payment instrument with the given id is unknown for the customer with the given customer id.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to retrieve the payment instrument for  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) the id of the payment instrument to be retrievedCustomer  
    Minimum length: 1.

#### Responses

*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `PaymentInstrumentNotFoundException` - Indicates that the payment instrument with the given id is unknown for the customer with the given customer id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_payment_instrument`.
    

### DELETE Delete customer payment instrument

`DELETE /customers/{customer_id}/payment_instruments/{payment_instrument_id}`

Operation ID: `Delete customer payment instrument`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Deletes a customer's payment instrument.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.

#### Parameters

*   `customer_id` (path, string, required) the id of the customer to delete the payment instrument for  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) the id of the payment instrument to be deleted  
    Minimum length: 1.

#### Responses

*   **204**
*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### GET Get customer product lists

`GET /customers/{customer_id}/product_lists`

Operation ID: `Get customer product lists`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns all customer product lists in a paginated manner.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.

#### Parameters

*   `customer_id` (path, string, required)
    
    *   The customer id.
    
      
    Minimum length: 1.
*   `expand` (query, array of string)
    *   The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.
*   `start` (query, integer (int32))
    
    *   The start of the product List
    
      
    Minimum: 0.
*   `count` (query, integer (int32))
    
    *   The count returned per page
    
      
    Minimum: 1. Maximum: 200.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_result`.
    

### POST Create customer product list

`POST /customers/{customer_id}/product_lists`

Operation ID: `Create customer product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Creates a customer product list.

This endpoint may return the following faults:

*   400 - InvalidAddressLinkException - Indicates that the id of the given address link does not reference an address of the current customer.
*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidProductListTypeException - Indicates that there was no or an invalid type given for the to be created product list.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.

#### Parameters

*   `customer_id` (path, string, required) The customer id.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_product_list`.

#### Responses

*   **400** `InvalidAddressLinkException` - Indicates that the id of the given address link does not reference an address of the current customer. or `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidProductListTypeException` - Indicates that there was no or an invalid type given for the to be created product list.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list`.
    

### GET Get customer product list

`GET /customers/{customer_id}/product_lists/{list_id}`

Operation ID: `Get customer product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns a customer product list of the given customer.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The customer id.  
    Minimum length: 1.
*   `list_id` (path, string, required) The product list id.  
    Minimum length: 1. Maximum length: 28.
*   `expand` (query, array of string) The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list`.
    

### DELETE Delete customer product list

`DELETE /customers/{customer_id}/product_lists/{list_id}`

Operation ID: `Delete customer product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Deletes a customer product list.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The customer id.  
    Minimum length: 1.
*   `list_id` (path, string, required) The product list id.  
    Minimum length: 1. Maximum length: 28.

#### Responses

*   **204**
*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Change customer product list

`PATCH /customers/{customer_id}/product_lists/{list_id}`

Operation ID: `Change customer product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Changes a product list. Changeable properties are the name, description and if the list is public.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The customer id.  
    Minimum length: 1.
*   `list_id` (path, string, required) The product list id.  
    Minimum length: 1. Maximum length: 28.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_product_list`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list`.
    

### GET Get items of customer's product list

`GET /customers/{customer_id}/product_lists/{list_id}/items`

Operation ID: `Get items of customer's product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns a pageable list of all items of a customer's product list. The default page size is 10.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the customer to retrieve the product list items for.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `expand` (query, array of string) The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.
*   `start` (query, integer (int32)) The result set index to return the first instance for; default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request; default value is 10.  
    Minimum: 1. Maximum: 200.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item_result`.
    

### POST Add item to customer's product list

`POST /customers/{customer_id}/product_lists/{list_id}/items`

Operation ID: `Add item to customer's product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Adds an item to the customer's product list. Considered values from the request body are:

*   **type** : a valid type, mandatory. This is the type of the item to be added to the customer's product list.
    
*   **priority** : This is the priority of the item to be added to the customer's product list.
    
*   **public** : This is the flag whether the item to be added to the customer's product list is public.
    
*   **product\_id** : a valid product id, used for `product` item type only. This is the id (sku) of the product related to the item to be added to the customer's product list. It is mandatory for `product` item type and it must be a valid product id, otherwise `ProductListProductIdMissingException` or `ProductListProductNotFoundException` will be thrown.
    
*   **quantity** : used for `product` item type only. This is the quantity of the item to be added to the customer's product list.
    
*   **custom properties in the form c\_ < CUSTOM\_NAME >** : the custom property must correspond to a custom attribute ( < CUSTOM\_NAME > ) defined for ProductListItem. The value of this property must be valid for the type of custom attribute defined for ProductListItem.
    

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - ProductListDuplicateGiftCertificateException - Indicates that the customer product list already has gift certificate item.
*   400 - ProductListItemTypeMissingException - Indicates that type property in request body is not provided.
*   400 - ProductListProductIdMissingException - Indicates that product property in request body is not provided.
*   400 - ProductListProductNotFoundException - Indicates that the product with the provided id is unknown.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the customer - owner of the product list.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list  
    Minimum length: 1. Maximum length: 28.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_product_list_item`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth. or `ProductListDuplicateGiftCertificateException` - Indicates that the customer product list already has gift certificate item. or `ProductListItemTypeMissingException` - Indicates that type property in request body is not provided. or `ProductListProductIdMissingException` - Indicates that product property in request body is not provided. or `ProductListProductNotFoundException` - Indicates that the product with the provided id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item`.
    

### GET Get an item of a customer product list

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

Operation ID: `Get an item of a customer product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns an item of a customer product list.

This endpoint may return the following faults:

*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListItemNotFoundException - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the customer to retrieve the product list items for.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the product list item to retrieve.  
    Minimum length: 1. Maximum length: 28.
*   `expand` (query, array of string) The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.

#### Responses

*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListItemNotFoundException` - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item`.
    

### DELETE Remove item from customer's product list

`DELETE /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

Operation ID: `Remove item from customer's product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Removes an item from a customer product list.

This endpoint may return the following faults:

*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListItemNotFoundException - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the owner of the product list  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the product list item to delete.  
    Minimum length: 1. Maximum length: 28.

#### Responses

*   **204**
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListItemNotFoundException` - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    

### PATCH Update customer's product list item

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}`

Operation ID: `Update customer's product list item`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Updates an item of a customer's product list. Considered values from the request body are:

*   **priority** : This is the priority of the customer's product list item.
    
*   **public** : This is the flag whether the customer's product list item is public.
    
*   **quantity** : used for `product` item type only. This is the quantity of the customer's product list item.
    
*   **custom properties in the form c\_ < CUSTOM\_NAME >** : the custom property must correspond to a custom attribute ( < CUSTOM\_NAME > ) defined for ProductListItem. The value of this property must be valid for the type of custom attribute defined for ProductListItem.
    

This endpoint may return the following faults:

*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListItemNotFoundException - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the owner of the product list.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the product list item to update.  
    Minimum length: 1. Maximum length: 28.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_product_list_item`.

#### Responses

*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListItemNotFoundException` - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item`.
    

### GET Get the purchases of a customer product list item

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases`

Operation ID: `Get the purchases of a customer product list item`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns a list of all purchases of an item from a customer's product list.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListItemNotFoundException - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the customer to retrieve the product list item purchases for.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the product list item to retrieve from.  
    Minimum length: 1. Maximum length: 28.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListItemNotFoundException` - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item_purchase_result`.
    

### POST Add a purchase to an item on a customer product list

`POST /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases`

Operation ID: `Add a purchase to an item on a customer product list`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Adds a purchase to an item in the customer's product list. Considered values from the request body are:

*   **purchaser\_name** : name of the purchaser, mandatory. This is the full name of the purchaser of this product list item.
    
*   **quantity** : amount purchased, mandatory. This is the quantity of the items purchased from the product list.
    
*   **custom properties in the form c\_ < CUSTOM\_NAME >** : the custom property must correspond to a custom attribute ( < CUSTOM\_NAME > ) defined for ProductListItemPurchase. The value of this property must be valid for the type of custom attribute defined for ProductListItemPurchase.
    

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListItemNotFoundException - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the customer - owner of the product list.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the product list item where to add the purchase.  
    Minimum length: 1. Maximum length: 28.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_product_list_item_purchase`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListItemNotFoundException` - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item_purchase`.
    

### GET Get a purchase of a customer product list item

`GET /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}`

Operation ID: `Get a purchase of a customer product list item`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Returns a purchase of an item from a customer's product list.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListItemNotFoundException - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
*   404 - ProductListItemPurchaseNotFoundException - Indicates that the product list item purchase with the given purchase id is unknown for the site, customer, product list, and item.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the customer to retrieve the product list items for.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the product list item to retrieve.  
    Minimum length: 1. Maximum length: 28.
*   `purchase_id` (path, string, required) The id of the product list item purchase to retrieve.  
    Minimum length: 1. Maximum length: 28.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListItemNotFoundException` - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list. or `ProductListItemPurchaseNotFoundException` - Indicates that the product list item purchase with the given purchase id is unknown for the site, customer, product list, and item. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item_purchase`.
    

### PATCH Update a purchase of a customer product list item

`PATCH /customers/{customer_id}/product_lists/{list_id}/items/{item_id}/purchases/{purchase_id}`

Operation ID: `Update a purchase of a customer product list item`. Tags: customers. Security: customers\_auth; oauth2\_application; client\_id.

Updates a purchase of an item from a customer's product list. Considered values from the request body are:

*   **custom properties in the form c\_ < CUSTOM\_NAME >** : the custom property must correspond to a custom attribute ( < CUSTOM\_NAME > ) defined for ProductListItemPurchase. The value of this property must be valid for the type of custom attribute defined for ProductListItemPurchase.
    

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - CustomerNotFoundException - Indicates that the customer with the given customer id is unknown for the site.
*   404 - ProductListItemNotFoundException - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list.
*   404 - ProductListItemPurchaseNotFoundException - Indicates that the product list item purchase with the given purchase id is unknown for the site, customer, product list, and item.
*   404 - ProductListNotFoundException - Indicates that the product list with the given list id is unknown for the site and the customer.

#### Parameters

*   `customer_id` (path, string, required) The id of the customer to retrieve the product list item purchases for.  
    Minimum length: 1.
*   `list_id` (path, string, required) The id of the product list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the product list item to retrieve.  
    Minimum length: 1. Maximum length: 28.
*   `purchase_id` (path, string, required) The id of the product list item purchase to retrieve.  
    Minimum length: 1. Maximum length: 28.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `customer_product_list_item_purchase`.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customerId URL parameter does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `CustomerNotFoundException` - Indicates that the customer with the given customer id is unknown for the site. or `ProductListItemNotFoundException` - Indicates that the product list item with the given item id is unknown for the site, the customer and the product list. or `ProductListItemPurchaseNotFoundException` - Indicates that the product list item purchase with the given purchase id is unknown for the site, customer, product list, and item. or `ProductListNotFoundException` - Indicates that the product list with the given list id is unknown for the site and the customer.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `customer_product_list_item_purchase`.
    

## Schemas

### customer\_registration

Document representing the registration information for a customer.

*   `customer` (_customer_, required) The customer registration information. The mandatory properties for registration are login, last name and email.
*   `password` (_string_) The password to authorize.  
    Maximum length: 4096.

_Example_

```
{
  "customer": {
    "email": "jsmith@test.com",
    "last_name": "Smith",
    "login": "jsmith"
  },
  "password": "12345!aBcD"
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### customer

Document representing a customer.

*   `addresses` (_array of customer\_address_) The customer's addresses.
*   `auth_type` (_string_) The customer's authorization type (indicates if the customer is a guest or a registered customer).  
    Allowed values: `guest`, `registered`.
*   `birthday` (_string (date)_) The customer's birthday.
*   `company_name` (_string_) The customer's company name.  
    Maximum length: 256.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `customer_id` (_string_, read-only) The customer's number (id). Both registered and guest customers have a customer id.  
    Maximum length: 28.
*   `customer_no` (_string_) The customer's number (id). Only a registered customer has a customer number.  
    Maximum length: 100.
*   `email` (_string (email)_) The customer's email address.  
    Maximum length: 256.
*   `enabled` (_boolean_) A flag indicating whether this customer is is enabled and can log in.
*   `fax` (_string_) The customer's fax number. The length is restricted to 32 characters.  
    Maximum length: 32.
*   `first_name` (_string_) The customer's first name.  
    Maximum length: 256.
*   `gender` (_integer (int32)_) The customer's gender.  
    Allowed values: `1`, `2`. Value meanings: `1`: Male; `2`: Female.
*   `hashed_login` (_string_) The customer's hashed LoginId which is used for activity tracking for logged in customers in conjunction with visitId. This field is READ-ONLY
*   `job_title` (_string_) The customer's job title.  
    Maximum length: 256.
*   `last_login_time` (_string (date-time)_, read-only) The time when the customer last logged in.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `last_name` (_string_) The customer's last name.  
    Maximum length: 256.
*   `last_visit_time` (_string (date-time)_, read-only) The time when the customer last visited.
*   `login` (_string_) The customer's login.  
    Maximum length: 256.
*   `note` (_string_) The customer's note.
*   `payment_instruments` (_array of customer\_payment\_instrument_) The customer's payment instruments.
*   `phone_business` (_string_) The customer's business phone number.  
    Maximum length: 32.
*   `phone_home` (_string_) The customer's home phone number.  
    Maximum length: 32.
*   `phone_mobile` (_string_) The customer's mobile phone number.  
    Maximum length: 32.
*   `preferred_locale` (_string_, read-only) The customer's preferred locale.
*   `previous_login_time` (_string (date-time)_) The time when the customer logged in previously.
*   `previous_visit_time` (_string (date-time)_)
    
    The time when the customer last visited the store.
    
    ```
         visit.
    ```
    
*   `salutation` (_string_) The salutation to use for the customer.  
    Maximum length: 256.
*   `second_name` (_string_) The customer's second name.  
    Maximum length: 256.
*   `suffix` (_string_) The customer's suffix (for example, "Jr." or "Sr.").  
    Maximum length: 256.
*   `title` (_string_) The customer's title (for example, "Mrs" or "Mr").  
    Maximum length: 256.
*   `visit_id` (_string_) The customer's visitId. This field is READ-ONLY

_Example_

```
{
  "adresses": [
    {
      "address1": "10 Presidential Way",
      "address_id": "me",
      "city": "Woburn",
      "country_code": "US",
      "first_name": "John",
      "full_name": "John M. Smith",
      "last_name": "Smith",
      "postal_code": "01827",
      "salutation": "Mr.",
      "state_code": "MA"
    }
  ],
  "auth_type": "registered",
  "creation_date": "2015-08-20T11:30:36.000Z",
  "customer_id": "abfTWMDZOgi3JPzkHjv9IhmziI",
  "customer_no": "999",
  "email": "jsmith@salesforce.com",
  "first_name": "John",
  "gender": 1,
  "last_name": "Smith",
  "payment_instruments": [
    {
      "payment_bank_account": {
        "_type": "payment_bank_account"
      },
      "payment_card": {
        "card_type": "Visa",
        "credit_card_expired": false,
        "expiration_month": 2,
        "expiration_year": 2022,
        "holder": "John Smith",
        "masked_number": "***********ber2",
        "number_last_digits": "ber2"
      },
      "payment_instrument_id": "beybQiWcyatEEaaadniwhKxxFl",
      "payment_method_id": "CREDIT_CARD",
      "uuid": "beybQiWcyatEEaaadniwhKxxFl"
    }
  ],
  "phone_business": "234560003",
  "phone_home": "123450003",
  "phone_mobile": "345670003",
  "c_origin": "webshop"
}
```

### auth\_request

Document representing the authentication request type.

*   `type` (_string_, required) Type of authentication request: guest, login (credentials), refresh or session.  
    Allowed values: `guest`, `credentials`, `refresh`, `session`.

_Example_

```
{
  "type": "credentials"
}
```

### trusted\_system\_auth\_request

*   `client_id` (_string_, required) The client id of the shopping application to be encoded in the customer JWT. This is not the same as the OAuth Client ID used to authenticate the API call. The OAuth Client ID is the trusted/private one; this is the untrusted/public one.  
    Pattern: ^(?!\\s\*$).+.
*   `login` (_string_, required) The customer's login.  
    Pattern: ^(?!\\s\*$).+.

_Example_

```
{
  "client_id": "abdtkZzH6sqInJGIHNR1yUw90A",
  "login": "guest@email.com"
}
```

### customers\_ext\_profile

*   `authentication_provider_id` (_string_) This is a mandatory parameter  
    Maximum length: 256.
*   `creation_date` (_string (date-time)_)
*   `customer_id` (_string_)  
    Maximum length: 28.
*   `email` (_string_)  
    Maximum length: 256.
*   `external_id` (_string_) Mandatory parameter  
    Maximum length: 256.
*   `first_name` (_string_)  
    Maximum length: 256.
*   `last_modified` (_string (date-time)_)
*   `last_name` (_string_)  
    Maximum length: 256.

_Example_

```
{
  "authentication_provider_id": "Google",
  "creation_date": "2020-07-09T05:27:55.563Z",
  "customer_id": "bfqcN48dn2y4EaV9Qj5bNpVJVj",
  "email": "testCustomer@test.com",
  "external_id": "testCustomer@test.com",
  "first_name": "John",
  "last_modified": "2020-07-09T05:27:55.563Z",
  "last_name": "Doe"
}
```

### reset\_password\_token\_request

*   `login` (_string_) The login id of the customer.  
    Maximum length: 256.

### reset\_password\_token\_result

*   `email` (_string_) The email address of the customer.
*   `expires_in_minutes` (_integer (int32)_) The password reset token expire time in minutes.
*   `login` (_string_) The login id of the customer.  
    Maximum length: 256.
*   `reset_token` (_string_) The password reset token for the customer.

_Example_

```
{
  "email": "jsmith@nonexist.com",
  "expires_in_minutes": 30,
  "login": "jsmith@nonexist.com",
  "reset_token": "01a13f8e3997cf722d98fac92a05bff09c00b8568b2d98"
}
```

### reset\_password\_request

*   `login` (_string_) The login id of the customer.  
    Maximum length: 256.
*   `new_password` (_string_, required) The new password for the customer.  
    Maximum length: 4096.
*   `reset_token` (_string_) The password reset token for the customer.

_Example_

```
{
  "login": "jsmith@nonexist.com",
  "new_password": "NewPassw0rd!",
  "reset_token": "1e95f1032d7f863226e05bc10385bc841885fbb18654fe"
}
```

### password\_reset

Document representing a password reset request.

*   `identification` (_string_) The customer's login or the customer's email depending on the type value.
*   `type` (_string_) The type of customer identification.  
    Allowed values: `email`, `login`.

_Example_

```
{
  "identification": "jsmith@nonexist.com",
  "type": "email"
}
```

### customer\_address\_result

Result document containing an array of customer addresses.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of customer\_address_) The array of customer address documents.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 1,
  "data": [
    {
      "address1": "10 Free Way",
      "address_id": "private",
      "city": "Woburn",
      "country_code": "US",
      "first_name": "James",
      "full_name": "James Last",
      "last_name": "Last",
      "postal_code": "01827",
      "salutation": "Mr.",
      "state_code": "MA"
    }
  ],
  "next": "https://example.com/dw/shop/{version}/customers/abdlkQCKV1aEqUQoeFOwAOeD4U/addresses?count=1&start=1",
  "start": 0,
  "total": 2
}
```

### customer\_address

Document representing a customer address.

*   `address1` (_string_) The first address.  
    Maximum length: 256.
*   `address2` (_string_) The second address.  
    Maximum length: 256.
*   `address_id` (_string_) The id of the address as specified by account owner.  
    Maximum length: 256.
*   `city` (_string_) The city.  
    Maximum length: 256.
*   `company_name` (_string_) The company name.  
    Maximum length: 256.
*   `country_code` (_string_) The two-letter ISO 3166-1 (Alpha-2) country code.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States. Maximum length: 2.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `first_name` (_string_) The first name.  
    Maximum length: 256.
*   `full_name` (_string_) The full name.  
    Maximum length: 256.
*   `job_title` (_string_) The job title.  
    Maximum length: 256.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `last_name` (_string_) The last name.  
    Maximum length: 256.
*   `phone` (_string_) The phone number.  
    Maximum length: 32.
*   `post_box` (_string_) The post box.  
    Maximum length: 256.
*   `postal_code` (_string_) The postal code.  
    Maximum length: 256.
*   `preferred` (_boolean_) The preferred attribute.
*   `salutation` (_string_) The salutation.  
    Maximum length: 256.
*   `second_name` (_string_) The second name.  
    Maximum length: 256.
*   `state_code` (_string_) The state code.  
    Maximum length: 256.
*   `suffix` (_string_) The suffix.  
    Maximum length: 256.
*   `suite` (_string_) The suite.  
    Maximum length: 32.
*   `title` (_string_) The title.  
    Maximum length: 256.

_Example_

```
{
  "address1": "5 Wall St",
  "address2": "24 Presidential Way",
  "address_id": "home_address",
  "city": "Burlington",
  "company_name": "Salesforce B2C Commerce",
  "country_code": "US",
  "first_name": "John",
  "full_name": "John Jim Murphy",
  "job_title": "Developer",
  "last_name": "Murphy",
  "phone": "408-555-1212",
  "post_box": "12a",
  "postal_code": "01805",
  "preferred": false,
  "salutation": "Mr.",
  "second_name": "Jim",
  "state_code": "MA",
  "title": "Dr."
}
```

### baskets\_result

Result document containing an array of baskets.

*   `baskets` (_array of basket_) The list of baskets for a customer.
*   `total` (_integer (int32)_) The total number of baskets.

_Example_

```
{
  "baskets": [
    {
      "basket_id": "bccO1aOjgEnuIaaadk7pYO2rFE"
    },
    {
      "basket_id": "bcs5vaOjgEQ9Uaaadk9zQIrXE6"
    }
  ],
  "total": 2
}
```

### customer\_order\_result

Result document containing an array of customer orders.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of order_) The array of customer order documents.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `select` (_string_) The fields that you want to select.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 1,
  "data": [
    {
      "adjusted_merchandize_total_tax": 5,
      "adjusted_shipping_total_tax": 0,
      "customer_info": {
        "customer_id": "bczhcasxVFpLdxtF05OIPEb25u",
        "customer_name": "John Smith",
        "email": "customer@sample.com"
      },
      "order_no": "00001228",
      "product_sub_total": 16.49,
      "product_total": 16.49,
      "shipping_total": 0.01,
      "shipping_total_tax": 0,
      "status": "created",
      "tax_total": 5,
      "taxation": "net"
    }
  ],
  "next": "https://example.com/dw/shop/{version}/customers/bczhcasxVFpLdxtF05OIPEb25u/orders?count=1&start=1",
  "start": 0,
  "total": 3
}
```

### password\_change\_request

Document representing a password change request.

*   `current_password` (_string_, required) The customer's current password.  
    Maximum length: 4096.
*   `password` (_string_, required) The customer's new password.  
    Maximum length: 4096.

_Example_

```
{
  "current_password": "01dpass",
  "password": "newpass"
}
```

### customer\_payment\_instrument\_result

Document representing a customer payment instrument result. The payment data contained is masked where needed for security purposes.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of customer\_payment\_instrument_) The customer payment instruments list.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "payment_bank_account": {
        "_type": "payment_bank_account"
      },
      "payment_card": {
        "card_type": "Visa",
        "credit_card_expired": false,
        "expiration_month": 2,
        "expiration_year": 2022,
        "holder": "John Doe",
        "masked_number": "***********1111",
        "number_last_digits": "1111"
      },
      "payment_instrument_id": "cdlPgiWbN6LM2aaadkcia6MgbA",
      "payment_method_id": "CREDIT_CARD",
      "c_strValue": "custom value 2"
    },
    {
      "bank_routing_number": "bankrouting3446",
      "gift_certificate_code_masked": "*****code",
      "payment_bank_account": {
        "drivers_license_last_digits": "e111",
        "drivers_license_state_code": "MA",
        "holder": "Joe Doe",
        "masked_drivers_license": "**********e111",
        "masked_number": "**********t111",
        "number_last_digits": "t111"
      },
      "payment_card": {
        "credit_card_expired": false
      },
      "payment_instrument_id": "cdTsgiWbN6DFEaaadkbia6MgbA",
      "payment_method_id": "OCAPI_Payment_Simple",
      "c_strValue": "custom value 1"
    }
  ],
  "total": 2
}
```

### customer\_payment\_instrument\_request

Document representing a customer payment instrument request.

*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `gift_certificate_code` (_string_) The gift certificate code.  
    Maximum length: 256.
*   `payment_bank_account` (_payment\_bank\_account\_request_) The payment bank account request data.
*   `payment_card` (_customer\_payment\_card\_request_) The customer payment card.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "bank_routing_number": "bankrouting3776",
  "gift_certificate_code": "gift_code7",
  "payment_card": {
    "card_type": "MasterCard",
    "expiration_month": 7,
    "expiration_year": 2027,
    "holder": "Joe Doe",
    "issue_number": "i117",
    "number": "1234567",
    "valid_from_month": 8,
    "valid_from_year": 2007
  },
  "payment_method_id": "OCAPI_Payment_Simple",
  "c_strValue": "custom value 7"
}
```

### customer\_payment\_instrument

Document representing a customer payment instrument.

*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code.
*   `payment_bank_account` (_payment\_bank\_account_) The payment bank account.
*   `payment_card` (_payment\_card_) The payment card.
*   `payment_instrument_id` (_string_) The payment instrument ID.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "bank_routing_number": "bankrouting3776",
  "gift_certificate_code_masked": "******ode7",
  "payment_bank_account": {
    "_type": "payment_bank_account"
  },
  "payment_card": {
    "card_type": "MasterCard",
    "credit_card_expired": false,
    "expiration_month": 7,
    "expiration_year": 2027,
    "holder": "Joe Doe",
    "issue_number": "i117",
    "masked_number": "***4567",
    "number_last_digits": "4567",
    "valid_from_month": 8,
    "valid_from_year": 2007
  },
  "payment_instrument_id": "cdOLciWbOsYl6aaadkwcsx9xHH",
  "payment_method_id": "OCAPI_Payment_Simple",
  "c_strValue": "custom value 7"
}
```

### customer\_product\_list\_result

Document representing a customer product lists result.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of customer\_product\_list_) The customer product lists.
*   `next` (_string_)
*   `previous` (_string_)
*   `start` (_integer (int32)_)  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "creation_date": "2020-07-29T22:30:43.000Z",
      "event": {
        "_type": "product_list_event"
      },
      "id": "0000073597bbf8c7604dce8f2c",
      "items_link": {
        "link": "https://example.com/s/SiteGenesis/dw/shop/{version}/customers/acXvoeW9o2g9SSiaHDHjnm7Pvc/product_lists/0000073597bbf8c7604dce8f2c/items?start=0&count=2",
        "title": "0 items"
      },
      "last_modified": "2020-07-29T22:30:44.000Z",
      "public": false,
      "type": "wish_list"
    },
    {
      "creation_date": "2020-07-29T22:30:42.000Z",
      "event": {
        "_type": "product_list_event"
      },
      "id": "0000407a34e39368119d1db05c",
      "items_link": {
        "link": "https://example.com/s/SiteGenesis/dw/shop/{version}/customers/acXvoeW9o2g9SSiaHDHjnm7Pvc/product_lists/0000407a34e39368119d1db05c/items?start=0&count=2",
        "title": "0 items"
      },
      "last_modified": "2020-07-29T22:30:44.000Z",
      "public": false,
      "type": "wish_list"
    }
  ],
  "next": "https://localhost/s/SiteGenesis/dw/shop/{version}/customers/acXvoeW9o2g9SSiaHDHjnm7Pvc/product_lists?start=2&count=2",
  "start": 0,
  "total": 4
}
```

### customer\_product\_list

Document representing a customer product List.

*   `co_registrant` (_customer\_product\_list\_registrant_) The coRegistrant of this product list.
*   `creation_date` (_string (date-time)_) Returns the value of attribute 'creationDate'.
*   `current_shipping_address_link` (_customer\_address\_link_) The resource link to the current shipping address of this customer product list.
*   `customer_product_list_items` (_array of customer\_product\_list\_item_) The list of customer product list items.
*   `description` (_string_) The description of this product list.
*   `event` (_product\_list\_event_) The event of this product list.
*   `id` (_string_) The id of this product list.  
    Minimum length: 1.
*   `items_link` (_customer\_product\_list\_item\_link_) The resource link to the items of this customer product list.
*   `last_modified` (_string (date-time)_) Returns the value of attribute 'lastModified'.
*   `name` (_string_) The name of this product list.
*   `post_event_shipping_address_link` (_customer\_address\_link_) The resource link to the post event shipping address of this customer product list.
*   `product_list_shipping_address` (_product\_list\_shipping\_address_) The abbreviated shipping address of this product list representing what anonymous user can see.
*   `public` (_boolean_) Indicates whether the owner made this product list available for access by other customers.
*   `registrant` (_customer\_product\_list\_registrant_) The registrant of this product list.
*   `shipping_address_link` (_customer\_address\_link_) The resource link to the shipping address of this customer product list.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`.

_Example_

```
{
  "co_registrant": {
    "email": "janedoe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "role": "Bride"
  },
  "description": "our productlist",
  "event": {
    "city": "Washington",
    "country": "US",
    "date": "2015-07-30T00:00Z",
    "state": "DC",
    "type": "Wedding"
  },
  "id": "bb151cd88655b081acc1fa85c6",
  "items_link": {
    "link": "https://example.com/dw/shop/{version}/customers/abKvXV2tYXMZPTdDwPXgx031cd/product_lists/bb151cd88655b081acc1fa85c6/items",
    "title": "0 items"
  },
  "name": "OurProductList",
  "public": false,
  "registrant": {
    "email": "johndoe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "Groom"
  },
  "type": "wish_list"
}
```

### customer\_product\_list\_item\_result

Document representing a customer product list items result.

*   `count` (_integer (int32)_)
*   `data` (_array of customer\_product\_list\_item_) The customer product list items.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_)

_Example_

```
{
  "count": 2,
  "data": [
    {
      "id": "ebe04a8c6be5c01a5dac9e50ac",
      "priority": 4,
      "product_details_link": {
        "link": "https://example.com/dw/shop/{version}/products/008884303989",
        "title": "Platinum Blue Stripes Easy Care Fitted Shirt"
      },
      "product_id": "008884303989",
      "public": true,
      "purchased_quantity": 0,
      "quantity": 2,
      "type": "product"
    },
    {
      "id": "f33bfc1a99e64c79ddfbb49b19",
      "priority": 2,
      "public": false,
      "purchased_quantity": 0,
      "type": "gift_certificate"
    }
  ],
  "start": 0,
  "total": 2
}
```

### customer\_product\_list\_item

Document representing a customer product list item.

*   `id` (_string_) The id of this product list item.
*   `priority` (_integer (int32)_) The priority of the item.
*   `product` (_product_) The product item
*   `product_details_link` (_product\_simple\_link_) A link to the product.
*   `product_id` (_string_) The id of the product.
*   `public` (_boolean_) Is this product list item available for access by other customers?
*   `purchased_quantity` (_number (double)_) The quantity of products already purchased.
*   `quantity` (_number (double)_) The quantity of this product list item.  
    Minimum: 0.
*   `type` (_string_) The type of the item.  
    Allowed values: `product`, `gift_certificate`.

_Example_

```
{
  "id": "1d447daa4d25805fd682bd4ce1",
  "priority": 4,
  "product_details_link": {
    "link": "https://example.com/dw/shop/{version}/products/008884303989",
    "title": "Platinum Blue Stripes Easy Care Fitted Shirt"
  },
  "product_id": "008884303989",
  "public": true,
  "purchased_quantity": 0,
  "quantity": 2,
  "type": "product"
}
```

### customer\_product\_list\_item\_purchase\_result

Document representing a customer product list purchases result.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of customer\_product\_list\_item\_purchase_) The customer product list item purchases.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 1,
  "data": [
    {
      "id": "2cebc21d3698a82efae72acff0",
      "product_list_item_id": "416ce013b346c908bee07d62e0",
      "purchase_name": "Jane Doe",
      "quantity": 1
    }
  ],
  "total": 1
}
```

### customer\_product\_list\_item\_purchase

Document representing a customer product list item purchase.

*   `id` (_string_) The id of this purchase.
*   `order_no` (_string_) The order number of this purchase.
*   `product_list_item_id` (_string_) The id of the product list item this purchase relates to.
*   `purchaser_name` (_string_) The name of the purchaser.
*   `quantity` (_number (double)_) The quantity of this product list item purchased.  
    Minimum: 0.

_Example_

```
{
  "id": "dcdb9e4d1f930a2d3a32310ec5",
  "product_list_item_id": "842ea014e952ded367c74a6c56",
  "purchaser_name": "first last",
  "quantity": 1
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### basket

Document representing a basket.

The following flashes are used to indicate the invalidity of a basket:

*   InvalidProductItem - a product item (or bundled product item) refers to a product which no longer exists, is offline, or the product is no longer assigned to a site catalog.
    
*   InvalidOptionItem - indicates that an option item refers to an option id or option value which no longer exists.
    
*   OptionItemWithoutPrice - indicates an option item without a price.
    
*   InvalidCouponCode (until 17.2) - indicates a coupon item became invalid, for example because its redemption limit is reached.
    
*   ProductItemNotAvailable - indicates too little available inventory to support the item quantity.
    
*   ProductItemWithoutPrice - indicates that the item has no price.
    
*   CustomerEmailRequired (until 17.2) - indicates the need to specify a customer email.
    
*   ShippingAddressRequired - indicates the need to specify a shipping address.
    
*   BillingAddressRequired - indicates the need to specify a billing address.
    
*   ShippingMethodRequired - indicates the need to specify a shipping method.
    
*   ShippingMethodNotApplicable - indicates that the currently specified shipping method is not applicable for the given addresses or product items.
    
*   PaymentMethodRequired - indicates the need to specify a payment method.
    
*   PaymentMethodNotApplicable - the currently specified payment method is not applicable for the given addresses or product items.
    
*   OrderTotalNotSet - the basket calculation could not be completed for some reason.
    
*   ProductItemAdjustedPriceLessThanZero - a price adjustment reduces an item price to a value below zero and should be corrected.
    

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency.
    
    Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `agent_basket` (_boolean_) Is the basket created by an agent?
*   `basket_id` (_string_) The unique identifier for the basket.
*   `billing_address` (_order\_address_) The billing address. This property is part of basket checkout information only.
*   `bonus_discount_line_items` (_array of bonus\_discount\_line\_item_) The bonus discount line items of the line item container.
*   `channel_type` (_string_, read-only)
    
    The sales channel for the order.
    
    This is a read-only attribute that can't be modified by an OCAPI call. For OCAPI, the sales channel is determined based on the client ID and token used for the OCAPI call. Usually, a customer-based authentication sets the channel to Storefront, and an agent-based authentication sets it to CallCenter. Using applications that use other client IDs for OCAPI calls, like Customer Service Center, will set different channel types. To modify the channel type in OCAPI, use a hook. \*
    
      
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `google`, `tiktok`, `snapchat`, `youtube`, `whatsapp`.
*   `coupon_items` (_array of coupon\_item_) The sorted array of coupon items. This array can be empty.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `customer_info` (_customer\_info_) The customer information for logged in customers. This property is part of basket checkout information only.
*   `gift_certificate_items` (_array of gift\_certificate\_item_) The sorted array of gift certificate line items. This array can be empty.
*   `grouped_tax_items` (_array of grouped\_tax_) Tax values that are summed and grouped based on the tax rate. The tax totals of the line items with the same tax rate will be grouped together and summed up. This will not affect calculation in any way.
*   `inventory_reservation_expiry` (_string (date-time)_)
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `merchandize_total_tax` (_number (double)_)
    
    The products total tax in purchase currency.
    
    Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
    
*   `notes` (_simple\_link_) The notes for the line item container.
*   `order_price_adjustments` (_array of price\_adjustment_) The array of order level price adjustments. This array can be empty.
*   `order_total` (_number (double)_) The total price of the order, including products, shipping and tax. This property is part of basket checkout information only.
*   `payment_instruments` (_array of order\_payment\_instrument_) The payment instruments list for the order.
*   `product_items` (_array of product\_item_) The sorted array of product items (up to a maximum of 50 items by default). This array can be empty.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipments` (_array of shipment_) The array of shipments. This property is part of basket checkout information only.
*   `shipping_items` (_array of shipping\_item_) The sorted array of shipping items. This array can be empty.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the order after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross. This property is part of basket checkout information only.
    
    ```
         Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `source_code` (_string_) Gets the source code assigned to this basket.
*   `tax_rounded_at_group` (_boolean_) If the tax is rounded at group level then this is set to true, false if the tax is rounded at item or unit level
*   `tax_total` (_number (double)_) The total tax amount of the order. This property is part of basket checkout information only.
*   `taxation` (_string_) The taxation the line item container is based on.  
    Allowed values: `gross`, `net`.
*   `temporary_basket` (_boolean_) Is the basket created a temporary basket?

_Example_

```
{
  "basket_id": "bczFTaOjgEqUkaaadkvHwbgrP5",
  "currency": "USD",
  "customer_info": {
    "customer_id": "adNJrbxJovaT5DPxUSfOywk6Et",
    "email": ""
  },
  "order_total": 0,
  "product_sub_total": 0,
  "product_total": 0,
  "shipments": [
    {
      "id": "me",
      "shipment_id": "bc5OTaOjgEqUoaaadkvHwbgrP5"
    }
  ],
  "shipping_items": [
    {
      "item_id": "bcwsbaOjgEqUsaaadkvHwbgrP5",
      "shipment_id": "me"
    }
  ],
  "shipping_total": 0,
  "shipping_total_tax": 0,
  "tax_total": 0,
  "taxation": "net"
}
```

### order

Document representing an order.

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency.
    
    Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `billing_address` (_order\_address_) The billing address. This property is part of basket checkout information only.
*   `bonus_discount_line_items` (_array of bonus\_discount\_line\_item_) The bonus discount line items of the line item container.
*   `channel_type` (_string_, read-only) The sales channel for the order.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `google`, `tiktok`, `snapchat`, `youtube`, `whatsapp`.
*   `confirmation_status` (_string_) The confirmation status of the order.  
    Allowed values: `not_confirmed`, `confirmed`.
*   `coupon_items` (_array of coupon\_item_) The sorted array of coupon items. This array can be empty.
*   `created_by` (_string_) The name of the user who created the order.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `customer_info` (_customer\_info_) The customer information for logged in customers. This property is part of basket checkout information only.
*   `customer_name` (_string_) The name of the customer associated with this order.
*   `export_status` (_string_) The export status of the order.  
    Allowed values: `not_exported`, `exported`, `ready`, `failed`.
*   `external_order_status` (_string_) The external status of the order.
*   `gift_certificate_items` (_array of gift\_certificate\_item_) The sorted array of gift certificate line items. This array can be empty.
*   `global_party_id` (_string_) globalPartyId is managed by Customer 360. Its value can be changed.
*   `grouped_tax_items` (_array of grouped\_tax_) Tax values that are summed and grouped based on the tax rate. The tax totals of the line items with the same tax rate will be grouped together and summed up. This will not affect calculation in any way.
*   `guest` (_boolean_) The registration status of the customer.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `merchandize_total_tax` (_number (double)_)
    
    The products total tax in purchase currency.
    
    Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
    
*   `notes` (_simple\_link_) The notes for the line item container.
*   `order_no` (_string_, read-only) The order number of the order.
*   `order_price_adjustments` (_array of price\_adjustment_) The array of order level price adjustments. This array can be empty.
*   `order_token` (_string_) The order token used to secure the lookup of an order on base of the plain order number. The order token contains only URL safe characters.
*   `order_total` (_number (double)_) The total price of the order, including products, shipping and tax. This property is part of basket checkout information only.
*   `payment_instruments` (_array of order\_payment\_instrument_) The payment instruments list for the order.
*   `payment_status` (_string_) The payment status of the order.  
    Allowed values: `not_paid`, `part_paid`, `paid`.
*   `product_items` (_array of product\_item_) The sorted array of product items (up to a maximum of 50 items by default). This array can be empty.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipments` (_array of shipment_) The array of shipments. This property is part of basket checkout information only.
*   `shipping_items` (_array of shipping\_item_) The sorted array of shipping items. This array can be empty.
*   `shipping_status` (_string_) The shipping status of the order.  
    Allowed values: `not_shipped`, `part_shipped`, `shipped`.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the order after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross. This property is part of basket checkout information only.
    
    ```
         Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `site_id` (_string_) The site where the order resides.
*   `source_code` (_string_) Gets the source code assigned to this basket.
*   `status` (_string_) The status of the order.  
    Allowed values: `created`, `new`, `open`, `completed`, `cancelled`, `replaced`, `failed`.
*   `tax_rounded_at_group` (_boolean_) If the tax is rounded at group level then this is set to true, false if the tax is rounded at item or unit level
*   `tax_total` (_number (double)_) The total tax amount of the order. This property is part of basket checkout information only.
*   `taxation` (_string_) The taxation the line item container is based on.  
    Allowed values: `gross`, `net`.

_Example_

```
{
  "adjusted_merchandize_total_tax": 0.05,
  "adjusted_shipping_total_tax": 0,
  "billing_address": {
    "city": "Boston",
    "country_code": "US",
    "first_name": "Jeff",
    "full_name": "Jeff Lebowski",
    "last_name": "Lebowski",
    "c_strValue": "cTest"
  },
  "creation_date": "2014-11-06T13:36Z",
  "currency": "USD",
  "customer_info": {
    "customer_no": "jlebowski",
    "email": "jeff@lebowski.com"
  },
  "merchandize_total_tax": 5,
  "order_no": "00000101",
  "order_token": "XizrH5hY1vB-Mxno-zfoCqTkegl3y7_OrRPGNZFlYG8",
  "order_total": 1.06,
  "payment_instruments": [
    {
      "amount": 1,
      "id": "cdKCIiWbNVndQaaadhlSa35gtp",
      "payment_bank_account": {
        "drivers_license_last_digits": "ense",
        "drivers_license_masked": "**************ense",
        "number_last_digits": "mber",
        "number_masked": "*************mber"
      },
      "payment_card": {
        "card_type": "testVisa",
        "credit_card_expired": false,
        "expiration_month": 4,
        "expiration_year": 21.2,
        "holder": "TestPerson",
        "number_last_digits": "mber",
        "number_masked": "**********mber"
      },
      "payment_method_id": "OCAPI_Payment_Simple"
    }
  ],
  "product_items": [
    {
      "adjusted_tax": 5,
      "base_price": 16.49,
      "bonus_product_line_item": false,
      "item_id": "cdHBEiWbNV9ZcaaadhrCk35gtp",
      "item_text": "Simple Product",
      "price": 16.49,
      "price_after_item_discount": 16.49,
      "price_after_order_discount": 1,
      "product_id": "SimpleProduct",
      "product_name": "Simple Product",
      "quantity": 1,
      "tax": 5,
      "tax_basis": 16.49,
      "tax_class_id": null,
      "tax_rate": 0.05,
      "c_strValue": "Test"
    }
  ],
  "product_sub_total": 16.49,
  "product_total": 1,
  "shipments": [
    {
      "id": "me",
      "shipping_address": {
        "city": "Boston",
        "country_code": "US",
        "first_name": "Jeff",
        "full_name": "Jeff Lebowski",
        "last_name": "Lebowski",
        "c_strValue": "cTest"
      },
      "shipping_method": {
        "description": {
          "default": "The base shipping method."
        },
        "id": "BaseShippingMethod",
        "name": {
          "default": "Base Shipping Method"
        },
        "price": 0.01,
        "c_somestring": "ShippingMethod String Value"
      }
    }
  ],
  "shipping_items": [
    {
      "adjusted_tax": 0,
      "base_price": 0.01,
      "item_id": "devgoiWbNVc92aaadhrSk35gtp",
      "item_text": "Shipping",
      "price": 0.01,
      "price_after_item_discount": 0.01,
      "shipment_id": "me",
      "tax": 0,
      "tax_basis": 0.01,
      "tax_class_id": "DefaultTaxClass",
      "tax_rate": 0.05
    }
  ],
  "shipping_total": 0.01,
  "shipping_total_tax": 0,
  "status": "created",
  "tax_total": 0.05,
  "c_strValue": "before submit basket",
  "c_textValue": "after submit basket"
}
```

### payment\_bank\_account\_request

Document representing a payment bank account request.

*   `drivers_license` (_string_) The drivers license.  
    Maximum length: 256.
*   `drivers_license_state_code` (_string_) The driver license state code.  
    Maximum length: 256.
*   `holder` (_string_) The holder of the bank account.  
    Maximum length: 256.
*   `number` (_string_) The payment bank account number.  
    Maximum length: 256.

### customer\_payment\_card\_request

Document representing a customer payment card request.

*   `card_type` (_string_) The payment card type (for example, 'Visa').  
    Maximum length: 256.
*   `credit_card_expired` (_boolean_) A flag indicating if the credit card is expired.
*   `credit_card_token` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.
*   `expiration_month` (_integer (int32)_) The month when the payment card expires.
*   `expiration_year` (_integer (int32)_) The year when the payment card expires.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256.
*   `issue_number` (_string_) The payment card issue number.  
    Maximum length: 256.
*   `number` (_string_) The payment card number.  
    Maximum length: 4000.
*   `valid_from_month` (_integer (int32)_) The payment card valid from month.  
    Minimum: 1. Maximum: 12.
*   `valid_from_year` (_integer (int32)_) The payment card valid from year.

### payment\_bank\_account

Document representing a payment bank account.

*   `drivers_license_last_digits` (_string_) The last 4 characters of the decrypted driver's license number of the bank account associated with this payment instrument.  
    Maximum length: 256.
*   `drivers_license_state_code` (_string_) The driver license state code.  
    Maximum length: 256.
*   `holder` (_string_) The holder of the bank account.  
    Maximum length: 256.
*   `masked_drivers_license` (_string_)
    
    The decrypted driver's license number of the bank account with all but the last 4 characters replaced with a '\*' character.
    
    ```
         with a '*' character.
    ```
    
      
    Maximum length: 256.
*   `masked_number` (_string_) The bank account masked number.  
    Maximum length: 256.
*   `number_last_digits` (_string_) The last digits of the bank account number.  
    Maximum length: 256.

_Example_

```
{
  "drivers_license_last_digits": "ense",
  "drivers_license_masked": "**************ense",
  "number_last_digits": "mber",
  "number_masked": "*************mber"
}
```

### payment\_card

Document representing a payment card.

*   `card_type` (_string_) The payment card type (for example, 'Visa').  
    Maximum length: 256.
*   `credit_card_expired` (_boolean_) A flag indicating if the credit card is expired.
*   `credit_card_token` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.
*   `expiration_month` (_integer (int32)_) The month when the payment card expires.
*   `expiration_year` (_integer (int32)_) The year when the payment card expires.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256.
*   `issue_number` (_string_) The payment card issue number.  
    Maximum length: 256.
*   `masked_number` (_string_) The masked credit card number.  
    Maximum length: 4000.
*   `number_last_digits` (_string_) The last digits of credit card number.  
    Maximum length: 4000.
*   `valid_from_month` (_integer (int32)_) The payment card valid from month.  
    Minimum: 1. Maximum: 12.
*   `valid_from_year` (_integer (int32)_) The payment card valid from year.

_Example_

```
{
  "card_type": "Visa",
  "credit_card_expired": false,
  "expiration_month": 2,
  "expiration_year": 2022,
  "holder": "John Smith",
  "masked_number": "***********ber2",
  "number_last_digits": "ber2"
}
```

### customer\_product\_list\_registrant

Document representing a customer product list registrant.

*   `email` (_string_) The email of the registrant.
*   `first_name` (_string_) The first name of the registrant.
*   `last_name` (_string_) The last name of the registrant.
*   `role` (_string_) The role of the registrant.

### customer\_address\_link

*   Result document of product list addresses.

*   `address_id` (_string_) The id of the address.  
    Maximum length: 256.
*   `link` (_string_) The target of the link.
*   `title` (_string_) The link title.

### product\_list\_event

Document representing a product list event.

*   `city` (_string_) The city where the event takes place.
*   `country` (_string_) The country where the event takes place.
*   `date` (_string (date-time)_) The date when the event takes place.
*   `state` (_string_) The federal state where the event takes place.
*   `type` (_string_) Type of the event to celebrate.

_Example_

```
{
  "city": "Washington",
  "country": "US",
  "date": "2015-07-30T00:00Z",
  "state": "DC",
  "type": "Wedding"
}
```

### customer\_product\_list\_item\_link

Document representing a customer product list item link.

*   `link` (_string_) The target of the link.
*   `title` (_string_) The link title.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/customers/acE9xUWs5ea75qwTh0Svi2XfRY/product_lists/bcedkiWbxCM2MaaadkRhB2IBzM/items",
  "title": "0 items"
}
```

### product\_list\_shipping\_address

Document representing a product list shipping address.

*   `address_id` (_string_, required) The id of this address.  
    Minimum length: 1.
*   `city` (_string_) The city of this address.
*   `first_name` (_string_) The first name of this address.
*   `last_name` (_string_) The last name of this address.

### product

Document representing a product.

*   `brand` (_string_) The product's brand.
*   `bundled_products` (_array of bundled\_product_) The array of all bundled products of this product.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `ean` (_string_) The European Article Number.
*   `fetch_date` (_integer (int32)_)
*   `id` (_string_, required) The id (SKU) of the product.  
    Minimum length: 1. Maximum length: 100.
*   `image_groups` (_array of image\_group_) The array of product image groups.
*   `inventories` (_array of inventory_) The array of product inventories explicitly requested via 'inventory\_ids' query parameter. This property is only returned in context of the 'availability' expansion.
*   `inventory` (_inventory_) The site default inventory information. This property is only returned in context of the 'availability' expansion.
*   `long_description` (_string (html)_) The localized product long description.
*   `manufacturer_name` (_string_) The products manufacturer name.
*   `manufacturer_sku` (_string_) The products manufacturer sku.
*   `master` (_master_) The master product information. Only for types master, variation group and variant.
*   `min_order_quantity` (_number (double)_) The minimum order quantity for this product.
*   `name` (_string_) The localized product name.
*   `options` (_array of option_) The array of product options. This array can be empty. Only for type option.
*   `page_description` (_string_) The localized products page description.
*   `page_keywords` (_string_) The localized products page description.
*   `page_title` (_string_) The localized products page title.
*   `price` (_number (double)_) The sales price of the product. In case of complex products like master or set this is the minimum price of related child products.
*   `price_max` (_number (double)_) The maximum sales of related child products in case of complex products like master or set.
*   `price_per_unit` (_number (double)_) The sales price per unit of the product. In case of complex products like master or set this is the minimum price per unit of related child products.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of related child products in case of complex products like master or set.
*   `prices` (_object_) The prices map with price book ids and their values.
    
    Additional properties: `number (double)`.
    
*   `primary_category_id` (_string_) The id of the products primary category.
*   `product_links` (_array of product\_link_) The array of source and target products links information.
*   `product_promotions` (_array of product\_promotion_) An array of active customer product promotions for this product, sorted by promotion priority using SORT\_BY\_EXCLUSIVITY ordering (exclusivity -> rank -> promotion class -> discount type -> best discount -> ID). This array can be empty. Coupon promotions are not returned in this array. See PromotionPlan.SORT\_BY\_EXCLUSIVITY for more details.
*   `recommendations` (_array of recommendation_) Returns a list of recommendations.
*   `set_products` (_array of product_) The array of set products of this product.
*   `short_description` (_string (html)_) The localized product short description.
*   `step_quantity` (_number (double)_) The steps in which the order amount of the product can be increased.
*   `type` (_product\_type_) The product type information. Can be one or multiple of the following values: item,master,variation\_group,variant,bundle,set.
*   `unit` (_string_) The sales unit of the product.
*   `unit_measure` (_string_) The unitMeasure of the product.
*   `unit_quantity` (_number (double)_)
*   `upc` (_string_) The Universal Product Code.
*   `valid_from` (_string (date-time)_) The time when product is valid from.
*   `valid_to` (_string (date-time)_) The time when product is valid to.
*   `variants` (_array of variant_) The array of actual variants. This array can be empty. Only for types master, variation group and variant.
*   `variation_attributes` (_array of variation\_attribute_) Sorted array of variation attributes information. This array can be empty. Only for types master, variation group and variant.
*   `variation_groups` (_array of variation\_group_) The array of actual variation groups. This array can be empty. Only for types master, variation group and variant.
*   `variation_values` (_object_)
    
    The actual variation attribute id - value pairs. Only for type variant and variation group.
    
    ```
         Only for type variant and variation group.
    ```
    
    Additional properties: `string`.
    

_Example_

```
{
  "_type": "product",
  "_v": "24.5",
  "brand": "Creative",
  "id": "creative-zen-v",
  "min_order_quantity": 1,
  "name": "Creative ZEN V Digital Media Player",
  "page_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
  "page_keywords": "Creative",
  "page_title": "Creative ZEN V Digital Media Player",
  "primary_category_id": "electronics-digital-media-players",
  "short_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
  "step_quantity": 1,
  "type": {
    "item": true
  },
  "c_mediaFormat": [
    "0010",
    "0020",
    "0030",
    "0040"
  ],
  "c_memorySize": "1GB",
  "c_tabDescription": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player."
}
```

### product\_simple\_link

Document representing a link to a product.

*   `link` (_string_) The target of the link.
*   `title` (_string_) The link title.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/products/008884303989",
  "title": "Platinum Blue Stripes Easy Care Fitted Shirt"
}
```

### order\_address

Document representing an order address.

*   `address1` (_string_) The first address.
*   `address2` (_string_) The second address.
*   `city` (_string_) The city.
*   `company_name` (_string_) The company name.
*   `country_code` (_string_) The two-letter ISO 3166-1 (Alpha-2) country code.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States.
*   `first_name` (_string_) The first name.
*   `full_name` (_string_) The full name.
*   `id` (_string_) Id used to identify this address
*   `job_title` (_string_) The job title.
*   `last_name` (_string_) The last name.
*   `phone` (_string_) The phone number.
*   `post_box` (_string_) The post box.
*   `postal_code` (_string_) The postal code.
*   `salutation` (_string_) The salutation.
*   `second_name` (_string_) The second name.
*   `state_code` (_string_) The state code.
*   `suffix` (_string_) The suffix.
*   `suite` (_string_) The suite.
*   `title` (_string_) The title.

_Example_

```
{
  "city": "Boston",
  "country_code": "US",
  "first_name": "John",
  "last_name": "Smith"
}
```

### bonus\_discount\_line\_item

Document representing a bonus discount line item

*   `bonus_products` (_array of product\_details\_link_) The list of links to the bonus products the customer can choose from.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, if applicable.
*   `id` (_string_) The ID of the line item.
*   `max_bonus_items` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotion_id` (_string_) The ID of the promotion which triggered the creation of the line item.

### coupon\_item

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256.
*   `coupon_item_id` (_string_) The coupon item id.
*   `status_code` (_string_) The status of the coupon item.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is 'applied' or 'no\_applicable\_promotion'.

_Example_

```
{
  "code": "the99coupon"
}
```

### customer\_info

Document representing information used to identify a customer.

*   `customer_id` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `customer_name` (_string_)
*   `customer_no` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `email` (_string (email)_, required) The customer's email address.

_Example_

```
{
  "customer_no": "customer0012",
  "email": "valid@email.com"
}
```

### gift\_certificate\_item

A gift certificate item.

*   `amount` (_number (double)_, required) The certificate item amount.
*   `gift_certificate_item_id` (_string_) Id used to identify this item
*   `message` (_string_) The certificate's message.  
    Maximum length: 4000.
*   `recipient_email` (_string_, required) The recipient's email.  
    Minimum length: 1.
*   `recipient_name` (_string_) The recipient's name.
*   `sender_name` (_string_) The sender's name.
*   `shipment_id` (_string_) The shipment id.

_Example_

```
{
  "amount": 200,
  "message": "Present from your brother",
  "recipient_email": "peter@example.com",
  "recipient_name": "Peter Doe",
  "sender_name": "John Doe"
}
```

### grouped\_tax

Document representing a tax rate with it's summed up tax values

*   `tax_rate` (_number (double)_) The tax rate
*   `tax_value` (_number (double)_) The summed up tax total for the tax rate

### simple\_link

Document representing a link to another resource.

*   `link` (_string_) The link to the resource.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/orders/bc0KwiWexX0ZQaaadqRTwMZFga/notes"
}
```

### price\_adjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level. They can be created by the promotion engine (if the custom flag is set to false) or can be added by custom logic (if the custom flag is set to true). For custom price adjustments created by a user, the manual flag should be set to true; this is always the case for price adjustments created using OCAPI.

A price adjustment created by custom logic can either define a price that defines the absolute price reduction or define a discount from which a price reduction is calculated (amount, percentage, and fixed\_price discounts are supported). The applied\_discount property describes the discount applied to create the price-adjustment.

*   `applied_discount` (_discount_) A price adjustment that provides details of the discount that was applied. This is `null` for custom price adjustments created without discount details.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, provided the price adjustment was created as the result of a promotion being triggered by a coupon.
*   `created_by` (_string_) The user who created the price adjustment.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.
*   `item_text` (_string_) The text describing the item in more detail.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `manual` (_boolean_)
    
    A flag indicating whether this price adjustment was created in a manual process.
    
    For custom price adjustments created using the shop API, this _always_ returns `true`. Using the scripting API, however, it is possible to set this to `true` or `false`, according to the use case.
    
*   `price` (_number (double)_) The adjustment price.
*   `price_adjustment_id` (_string_) The price adjustment id (uuid).
*   `promotion_id` (_string_) The id of the related promotion. Custom price adjustments can be assigned any promotion id so long it is not used by a price adjustment belonging to the same item and is not used by promotion defined in the promotion engine. If not specified, a promotion id is generated.
*   `promotion_link` (_string_) The URL addressing the related promotion.
*   `reason_code` (_string_) The reason why this price adjustment was made.  
    Allowed values: `BACKORDER`, `EVEN_EXCHANGE`, `PRICE_MATCH`. Value meanings: `BACKORDER`: Backorder; `EVEN_EXCHANGE`: Even Exchange; `PRICE_MATCH`: Price Match.

### order\_payment\_instrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.
*   `authorization_status` (_status_) The authorization status of the payment transaction.
*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code.
*   `payment_bank_account` (_payment\_bank\_account_) The payment bank account.
*   `payment_card` (_payment\_card_) The payment card.
*   `payment_instrument_id` (_string_) The payment instrument ID.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "amount": 1,
  "payment_card": {
    "card_type": "Visa",
    "credit_card_expired": false,
    "expiration_month": 1,
    "expiration_year": 2021,
    "holder": "John Doe",
    "masked_number": "***********1111",
    "number_last_digits": "1111"
  },
  "payment_instrument_id": "ceDUYiWbN1IkkaaadkYHRkclwC",
  "payment_method_id": "CREDIT_CARD",
  "c_strValue": "any custom value"
}
```

### product\_item

Document representing a product item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_, required) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 5,
  "base_price": 16.49,
  "bonus_product_line_item": false,
  "item_id": "cdHBEiWbNV9ZcaaadhrCk35gtp",
  "item_text": "Simple Product",
  "price": 16.49,
  "price_after_item_discount": 16.49,
  "price_after_order_discount": 1,
  "product_id": "SimpleProduct",
  "product_name": "Simple Product",
  "quantity": 1,
  "tax": 5,
  "tax_basis": 16.49,
  "tax_class_id": null,
  "tax_rate": 0.05,
  "c_strValue": "Test"
}
```

### shipment

Document representing a shipment.

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency. Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift.
*   `gift_message` (_string_) The gift message.
*   `merchandize_total_tax` (_number (double)_) The products total tax in purchase currency. Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipment_id` (_string_) The order specific id to identify the shipment.
*   `shipment_no` (_string_)
    
    Returns the shipment number for this shipment.
    
    This number is automatically generated.
    
*   `shipment_total` (_number (double)_)
    
    The total price of the shipment, including products, shipping and tax.
    
    Note that order level adjustments are not considered.
    
*   `shipping_address` (_order\_address_) The shipping address.
*   `shipping_method` (_shipping\_method_) The shipping method.
*   `shipping_status` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the shipment after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross.
    
    ```
         net. Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `tax_total` (_number (double)_)
    
    The total tax amount of the shipment.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `tracking_number` (_string_) The tracking number of the shipment.

_Example_

```
{
  "gift": true,
  "gift_message": "Happy Birthday, Sværre",
  "id": "StandardShipping",
  "shipping_address": {
    "city": "Boston",
    "country_code": "US",
    "first_name": "John",
    "last_name": "Smith"
  },
  "shipping_method": {
    "id": "BaseShippingMethod"
  }
}
```

### shipping\_item

Document representing a shipping item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `shipment_id` (_string_) The identifier of the shipment to which this item belongs.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 0,
  "base_price": 0.01,
  "item_id": "devgoiWbNVc92aaadhrSk35gtp",
  "item_text": "Shipping",
  "price": 0.01,
  "price_after_item_discount": 0.01,
  "shipment_id": "me",
  "tax": 0,
  "tax_basis": 0.01,
  "tax_class_id": "DefaultTaxClass",
  "tax_rate": 0.05
}
```

### bundled\_product

Document representing a bundled product within a product bundle.

*   `id` (_string_)
*   `product` (_product_) The product being bundled.
*   `quantity` (_number (double)_) For the product being bundled, the quantity added to the bundle.

_Example_

```
{
  "product": {
    "brand": "Sony",
    "id": "sony-ps3-console",
    "name": "Sony Playstation 3 Game Console",
    "page_description": "ncludes PLAYSTATION 3 80GB system, DUALSHOCK 3 wireless controller, free PLAYSTATION Network membership, internet ready Wi-Fi, and 80GB of hard disk storage for all your games, music, videos, and photos. Every PS3 comes with a built-in Blu-ray player to give you the best high-definition viewing experience and pristine picture quality. Plus, the PS3 can play your entire catalog of CDs and DVDs.",
    "page_keywords": "Sony",
    "page_title": "Sony Playstation 3 Game Console",
    "primary_category_id": "electronics-game-consoles",
    "short_description": "ncludes PLAYSTATION 3 80GB system, DUALSHOCK 3 wireless controller, free PLAYSTATION Network membership, internet ready Wi-Fi, and 80GB of hard disk storage for all your games, music, videos, and photos. Every PS3 comes with a built-in Blu-ray player to give you the best high-definition viewing experience and pristine picture quality. Plus, the PS3 can play your entire catalog of CDs and DVDs.",
    "type": {
      "item": true,
      "option": true
    }
  },
  "quantity": 1
}
```

### image\_group

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of image_) The images of the image group.
*   `variation_attributes` (_array of variation\_attribute_) Returns a list of variation attributes applying to this image group.
*   `view_type` (_string_) The image view type.

_Example_

```
{
  "images": [
    {
      "alt": "ALT master detail",
      "link": "https://example.com/foo/bar/master_detail.jpg",
      "title": "TITLE master detail"
    }
  ],
  "view_type": "detail"
}
```

### inventory

Document representing inventory information of the current product for a particular inventory list.

*   `ats` (_number (double)_) The ats of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.ats.max\_threshold'.
*   `backorderable` (_boolean_) A flag indicating whether the product is back orderable.
*   `id` (_string_, required) The inventory id.
*   `in_stock_date` (_string (date-time)_) A flag indicating the date when the product will be in stock.
*   `orderable` (_boolean_) A flag indicating whether at least one of products is available to sell.
*   `preorderable` (_boolean_) A flag indicating whether the product is pre orderable.
*   `stock_level` (_number (double)_) The stock level of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.stock\_level.max\_threshold'.

_Example_

```
{
  "ats": 0,
  "backorderable": false,
  "id": "BlueJeansInventory",
  "orderable": false,
  "preorderable": false,
  "stock_level": 0
}
```

### master

Document representing a variation master.

*   `link` (_string_) The URL addressing the master product.
*   `master_id` (_string_, required) The id (SKU) of the master product.  
    Minimum length: 1. Maximum length: 100.
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.
*   `price` (_number (double)_) The minimum sales price of the related variants.
*   `price_max` (_number (double)_) The maximum sales of related variants.
*   `price_per_unit` (_number (double)_) The minimum sales price per unit of the related variants.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of the related variants.
*   `prices` (_object_)
    
    Additional properties: `number (double)`.
    

### option

Document representing a product option.

*   `description` (_string_) The localized description of the option.
*   `id` (_string_, required) The id of the option.  
    Minimum length: 1. Maximum length: 100.
*   `image` (_string_) The URL to the option image.
*   `name` (_string_) The localized name of the option.
*   `values` (_array of option\_value_) The array of option values. This array can be empty.

### product\_link

Document representing a link between two products. It contains the id of the source and target products, the type of product link, and URLs to retrieve product data.

*   `source_product_id` (_string_) The semantic id of the product from which this product link is coming.
*   `source_product_link` (_string_) The URL addressing the product from which this product link is coming.
*   `target_product_id` (_string_) The semantic id of the product to which this product link is pointing.
*   `target_product_link` (_string_) The URL addressing the product to which this product link is pointing.
*   `type` (_string_) The type of this product link.  
    Allowed values: `cross_sell`, `replacement`, `up_sell`, `accessory`, `newer_version`, `alt_orderunit`, `spare_part`, `other`.

_Example_

```
{
  "source_product_id": "namco-we-ski-wii",
  "source_product_link": "http://example.com/dw/shop/{version}/products/namco-we-ski-wii?pretty_print=true",
  "target_product_id": "midway-cruisn-wii",
  "target_product_link": "http://example.com/dw/shop/{version}/products/midway-cruisn-wii?pretty_print=true",
  "type": "cross_sell"
}
```

### product\_promotion

Document representing a product promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotional_price` (_number (double)_) The promotional price for this product.

_Example_

```
{
  "callout_msg": "Save 15% Off iPod Nano",
  "link": "http://example.com/dw/shop/{version}/promotions/15off-nano",
  "promotion_id": "15off-nano"
}
```

### recommendation

Document representing a product recommendation.

*   `callout_msg` (_string (html)_) The localized callout message of the recommendation.
*   `image` (_image_) The image of the recommendation.
*   `long_description` (_string (html)_) The localized long description of the recommendation.
*   `name` (_string_) The localized name of the recommendation.
*   `recommendation_type` (_recommendation\_type_) The recommendation type of the recommendation.
*   `recommended_item_id` (_string_) The recommended item id of the recommendation.
*   `recommended_item_link` (_string_) The recommended item link of the recommendation.
*   `short_description` (_string (html)_) The localized short description of the recommendation.

### product\_type

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.
*   `master` (_boolean_) A flag indicating whether the product is a master.
*   `option` (_boolean_) A flag indicating whether the product is an option.
*   `set` (_boolean_) A flag indicating whether the product is a set.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.
*   `variation_group` (_boolean_) A flag indicating whether the product is a variation group.

_Example_

```
{
  "item": true
}
```

### variant

Document representing a product variation.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.
*   `price` (_number (double)_) The sales price of the variant.
*   `price_per_unit` (_number (double)_) The sales price of the variant.
*   `product_id` (_string_, required) The id (SKU) of the variant.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "http://example.com/dw/shop/{version}/products/apple-ipod-touch-8gb?pretty_print=true",
  "product_id": "apple-ipod-touch-8gb",
  "variation_values": {
    "memorySize": "8 GB"
  }
}
```

### variation\_attribute

Document representing a variation attribute.

*   `id` (_string_, required) The id of the variation attribute.  
    Minimum length: 1.
*   `name` (_string_) The localized display name of the variation attribute.
*   `values` (_array of variation\_attribute\_value_) The sorted array of variation values. This array can be empty.

_Example_

```
{
  "id": "memorySize",
  "name": "Memory Size",
  "values": [
    {
      "name": "1 GB",
      "value": "1 GB"
    },
    {
      "name": "2 GB",
      "value": "2 GB"
    },
    {
      "name": "8 GB",
      "value": "8 GB"
    },
    {
      "name": "16 GB",
      "value": "16 GB"
    },
    {
      "name": "32 GB",
      "value": "32 GB"
    },
    {
      "name": "120 GB",
      "value": "120 GB"
    }
  ]
}
```

### variation\_group

Document representing a variation group.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.
*   `price` (_number (double)_) The sales price of the variation group.
*   `price_per_unit` (_number (double)_) The sales price per unit of the variation group.
*   `product_id` (_string_) The id (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

### product\_details\_link

Document representing a link to the resource for product details.

*   `link` (_string_) The target of the link.
*   `product_description` (_string_) The description of the product.
*   `product_id` (_string_, required) The id of the product.
*   `product_name` (_string_) The name of the product.
*   `title` (_string_) The link title.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/products/BlueJeansType1",
  "product_id": "BlueJeansType1",
  "product_name": "Product w/- Local Option",
  "title": "Product w/- Local Option"
}
```

### discount

Document representing a discount that was _either_ optionally applied when creating a custom price adjustment _or_ applied by the promotion engine. The property `type` is mandatory; the properties `amount` and `priceBookId` are used only in association with specific types. Some examples:

*   Type `percentage` with percentage `15.00` : a 15% discount was applied.
    
*   Type `amount` with amount `5.99` : a discount was applied to reduce the (unit) price by 5.99.
    
*   Type `fixed_price` with amount `49.99` : a discount was applied to reduce the price to 49.99.
    
*   Type `free` : a discount was applied to reduce the price to zero.
    
*   Type `price_book_price` with price\_book\_id `MyPriceBook` : a discount was applied to set the price to that defined in MyPriceBook.
    

*   `amount` (_number (double)_) The amount that is used with the amount and fixed price types.
*   `percentage` (_number (double)_) The percentage that is used with percentage types.
*   `price_book_id` (_string_) The price book id that is used with some types.
*   `type` (_string_, required) The type of discount.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`.

_Example_

```
{
  "amount": 15,
  "type": "amount"
}
```

### status

Document representing a status of an object.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_)
    
    The status.
    
    For more information on the status values see dw.system.Status.OK and dw.system.Status.ERROR.
    

### option\_item

Document representing an option item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_id` (_string_, required) The id of the option.  
    Maximum length: 256.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `option_value_id` (_string_, required) The id of the option value.  
    Maximum length: 256.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "option_id": "Warranty",
  "option_value_id": "oneYear"
}
```

### product\_list\_item\_reference

*   `id` (_string_, required) The id of the product list item.
*   `priority` (_integer (int32)_)
*   `product_details_link` (_product\_details\_link_)
*   `product_list` (_product\_list\_link_) The link of the product list, the item is assigned
*   `public` (_boolean_)
*   `purchased_quantity` (_number (double)_)
*   `quantity` (_number (double)_)  
    Minimum: 0.
*   `type` (_string_)  
    Allowed values: `product`, `gift_certificate`.

### shipping\_method

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.
*   `external_shipping_method` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method id.  
    Maximum length: 256.
*   `name` (_string_) The localized name of the shipping method.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs and product level fix and surcharge costs.
*   `shipping_promotions` (_array of shipping\_promotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

_Example_

```
{
  "id": "BaseShippingMethod"
}
```

### image

Document representing a product image.

*   `alt` (_string_) The localized alternative text of the image.
*   `dis_base_link` (_string_) Base URL for dynamic image service address. This is only shown, if the image is stored on the server and DIS is enabled.
*   `link` (_string_, required) The URL of the actual image.  
    Minimum length: 1.
*   `title` (_string_) The localized title of the image.

_Example_

```
{
  "alt": "ALT main swatch",
  "link": "https://example.com/foo/bar/main_swatch.jpg",
  "title": "TITLE main swatch"
}
```

### option\_value

Document representing an option value.

*   `default` (_boolean_) A flag indicating whether this option value is the default one.
*   `id` (_string_, required) The id of the option value.  
    Minimum length: 1. Maximum length: 100.
*   `name` (_string_) The localized name of the option value.
*   `price` (_number (double)_) The effective price of this option value.

### recommendation\_type

Document representing a recommendation type.

*   `display_value` (_string_) The localized display value of the recommendation type.
*   `value` (_integer (int32)_) The value of the recommendation type.

_Example_

```
{
  "display_value": "Cross-Sell",
  "value": 1
}
```

### variation\_attribute\_value

Document representing a variation attribute value.

*   `description` (_string_) The localized description of the variation value.
*   `image` (_image_) The first product image for the configured viewtype and this variation value.
*   `image_swatch` (_image_) The first product image for the configured viewtype and this variation value. (typically the swatch image)
*   `name` (_string_) The localized display name of the variation value.
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1.

### product\_list\_link

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `link` (_string_) The target of the link.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`.

### shipping\_promotion

Document representing a shipping promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotion_name` (_string_) The localized promotion name.

<!-- document id=4012f8b996c6d73140107cb4172fc4998e58276198e73767ef47ec4f43edd33c url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-folders.md -->

Shop Folders (deprecated)

# Shop Folders (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get multiple content folders

`GET /folders/({ids})`

Operation ID: `Get multiple content folders`. Tags: folders. Security: client\_id; customers\_auth.

To access one or more content folder, you construct a URL using the template shown below. This template requires you to specify one or more content folder ids and a subfolder level. In response, the server returns a result set of corresponding content folder documents. Only content folder, which are marked as online are returned.

#### Parameters

*   `ids` (path, array of string, required) The ids of the requested content folders.  
    Maximum length: 256.
*   `levels` (query, integer (int32)) Specifies how many levels of nested subfolders you want the server to return. The default value is 1. Valid values are 0, 1, or 2.  
    Minimum: 0. Maximum: 2.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder_result`.
    

### GET Get content folder

`GET /folders/{id}`

Operation ID: `Get content folder`. Tags: folders. Security: client\_id; customers\_auth.

To access a content folder, you construct a URL using the template shown below. This template requires you to specify a content folder id and a subfolder level. In response, the server returns a corresponding content folder document. Only content folder, which are marked as online are returned.

#### Parameters

*   `id` (path, string, required) The id of the requested content folder.  
    Maximum length: 256.
*   `levels` (query, integer (int32)) Specifies how many levels of nested subfolders you want the server to return. The default value is 1. Valid values are 0, 1, or 2.  
    Minimum: 0. Maximum: 2.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `content_folder`.
    

## Schemas

### content\_folder\_result

Result document containing an array of content folders.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of content\_folder_) The array of content folder documents.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "id": "our-story",
      "name": "Our Story",
      "parent_folder_id": "about-us"
    },
    {
      "id": "our-team",
      "name": "Our Team",
      "parent_folder_id": "about-us"
    }
  ],
  "total": 2
}
```

### content\_folder

Document representing a content folder.

*   `description` (_string_) The localized content folder description.
*   `folders` (_array of content\_folder_) The array of content subfolders. This array can be empty.
*   `id` (_string_, required) The id of the content folder.  
    Minimum length: 1. Maximum length: 256.
*   `name` (_string_) The localized content folder name.
*   `page_description` (_string_) The localized content folder page description.
*   `page_keywords` (_string_) The localized content folder page description.
*   `page_title` (_string_) The localized content folder page title.
*   `parent_folder_id` (_string_) The id of the parent content folder.

_Example_

```
{
  "folders": [
    {
      "id": "our-story",
      "name": "Our Story",
      "parent_folder_id": "about-us"
    },
    {
      "id": "our-team",
      "name": "Our Team",
      "parent_folder_id": "about-us"
    },
    {
      "id": "as-seen-in",
      "name": "As Seen In",
      "parent_folder_id": "about-us"
    },
    {
      "id": "contact-us-new",
      "name": "Contact Us",
      "parent_folder_id": "about-us"
    },
    {
      "id": "employment",
      "name": "Join Us",
      "parent_folder_id": "about-us"
    }
  ],
  "id": "about-us",
  "name": "About Salesforce B2C Commerce",
  "parent_folder_id": "root",
  "c_customCSSFile": "http://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites-SiteGenesis-Library/default/v1365077029384/css/aboutus.css"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=828dbc24b848531a7a62cf19a7b84ca6ecced98a13cbfa59673fe83a86e3df73 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-gift-certificate.md -->

Shop Gift Certificate (deprecated)

# Shop Gift Certificate (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Get Gift Certificate

`POST /gift_certificate`

Operation ID: `Get Gift Certificate`. Tags: gift\_certificate. Security: customers\_auth; oauth2\_application; client\_id.

Action to retrieve an existing gift certificate.

This endpoint may return the following faults:

*   404 - GiftCertificateNotFoundException - Thrown if the given gift certificate code is not valid.

#### Request body

Media type: `application/json, text/xml`. Schema: `gift_certificate_request`.

#### Responses

*   **404** `GiftCertificateNotFoundException` - Thrown if the given gift certificate code is not valid.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `gift_certificate`.
    

## Schemas

### gift\_certificate\_request

Document representing a gift certificate request data.

*   `gift_certificate_code` (_string_) The gift certificate code.

_Example_

```
{
  "gift_certificate_code": "123456789012"
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### gift\_certificate

Document representing a gift certificate.

*   `amount` (_number (double)_) The gift certificate original amount.
*   `balance` (_number (double)_) The gift certificate balance.
*   `description` (_string_) The gift certificate description.
*   `enabled` (_boolean_) Is the gift certificate is enabled?
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code.
*   `merchant_id` (_string_) The merchant ID.
*   `message` (_string_) The message.
*   `recipient_email` (_string_) The recipient email.
*   `recipient_name` (_string_) The recipient name.
*   `sender_name` (_string_) The sender name.
*   `status` (_string_) The gift certificate status.  
    Allowed values: `pending`, `issued`, `partially_redeemed`, `redeemed`.

_Example_

```
{
  "balance": 30,
  "description": "Enabled gift certificate",
  "enabled": true,
  "masked_gift_certificate_code": "********9012",
  "merchant_id": "00000001",
  "message": "...",
  "recipient_email": "jdoe@example.com",
  "recipient_name": "Joe Doe",
  "status": "pending"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=d85605c915add362b7fecff9348efefcc6dbb33b3a22203b7ce982dcc6a65f49 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-order-search.md -->

Shop Order Search (deprecated)

# Shop Order Search (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Search orders

`POST /order_search`

Operation ID: `Search orders`. Tags: order\_search. Security: customers\_auth; oauth2\_application; client\_id.

Searches for orders.

The query attribute specifies a complex query that can be used to narrow down the search.

Note that search fields are mandatory now and no default ones are supported.

As the old order search version, the new one always uses Search Service too and the for that reason Order Incremental Indexing should be enabled. Otherwise HTTP 500 response will occur.

The supported search fields are:

*   affiliate\_partner\_i\_d
    
*   affiliate\_partner\_name
    
*   business\_type
    
*   channel\_type
    
*   confirmation\_status (String)
    
*   created\_by
    
*   creation\_date
    
*   last\_modified
    
*   currency\_code
    
*   customer\_email
    
*   customer\_name
    
*   customer\_no
    
*   export\_after
    
*   export\_status (String)
    
*   external\_order\_no
    
*   external\_order\_status
    
*   global\_party\_id
    
*   last\_modified
    
*   order\_no
    
*   original\_order\_no
    
*   payment\_status (String)
    
*   replaced\_order\_no
    
*   replacement\_order\_no
    
*   shipping\_status (String)
    
*   status (String)
    
*   total\_gross\_price
    
*   total\_net\_price
    
*   order.has\_holds
    
*   coupon\_line\_items.coupon\_code
    
*   coupon\_line\_items.coupon\_id
    
*   holds.type
    
*   invoices.status
    
*   order\_items.status
    
*   payment\_instruments.credit\_card\_type
    
*   payment\_instruments.payment\_method\_id
    
*   product\_items.product\_id
    
*   return\_cases.return\_case\_number
    
*   shipments.shipping\_method\_id
    
*   shipping\_orders.shipping\_order\_number
    

The sort order of the retrieved orders could be specified by the "sorts" parameter. It is a list of objects presenting field name and sort direction ("asc" or "desc").

Custom attributes could be used as search fields and as sort fields too. A prefix "c\_" has to be added to them.

The sum of the values of the start and count parameters should not be more than 10000.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_search_request`.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order_search_result`.
    

## Schemas

### order\_search\_request

Document representing an order search request.

*   `count` (_integer (int32)_) The number of returned documents  
    Minimum: 1. Maximum: 200.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `query` (_query_, required) The query to apply
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.

_Example_

```
{
  "query": {
    "text_query": {
      "fields": [
        "customer_email"
      ],
      "search_phrase": "example@non.existing.com"
    }
  },
  "select": "(**)",
  "sorts": [
    {
      "field": "customer_name",
      "sort_order": "asc"
    }
  ]
}
```

### order\_search\_result

Document representing an order search result.

*   `count` (_integer (int32)_) The number of returned documents
*   `data` (_array of object_)
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling  
    Minimum: 0.
*   `expand` (_array of string_) List of expansions to be applied to each search results. Expands are optional
*   `hits` (_array of order\_search\_hit_) The sorted array of search hits. This array can be empty.
*   `next` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the next result page.
*   `previous` (_result\_page_) The data that can be used (as parameters on the search request) to retrieve the previous result page.
*   `query` (_query_) The query passed into the search
*   `select` (_string_) The field to be selected.
*   `sorts` (_array of sort_) The list of sort clauses configured for the search request. Sort clauses are optional.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The number of returned documents

_Example_

```
{
  "count": 1,
  "hits": [
    {
      "data": {
        "adjusted_merchandize_total_tax": 3.75,
        "adjusted_shipping_total_tax": 0,
        "billing_address": {
          "city": "Boston",
          "country_code": "US",
          "first_name": "Jane",
          "full_name": "Jane Doe",
          "last_name": "Doe",
          "postal_code": "29199"
        },
        "channel_type": "callcenter",
        "c_created_by": "testAgent"
      },
      "relevance": 2.822207450866699
    }
  ],
  "select": "(**)",
  "start": 0,
  "total": 1
}
```

### query

Document representing a query. A query contains a set of objects that define criteria used to select records. A query can contain one of the following:

*   match\_all\_query - returns all records.
    
*   term\_query - matches records where a field (or fields) exactly match some simple value (including null).
    
*   text\_query - matches records where a field (or fields) exactly matches one (or more) terms in the search phrase.
    
*   boolean\_query - formulates a complex boolean expression using query objects as criteria.
    
*   filtered\_query - allows for filtering of records based on both a query and a filter.
    

Type: `any`.

### sort

Document representing a sort request.

*   `field` (_string_, required) The name of the field to sort on.
*   `sort_order` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (ASC) is used.  
    Allowed values: `asc`, `desc`.

_Example_

```
{
  "field": "customer_name",
  "sort_order": "asc"
}
```

### order\_search\_hit

Document representing an order search hit.

*   `data` (_order_) The search hit data
*   `relevance` (_number (double)_) The hit's relevance score.

_Example_

```
{
  "data": {
    "adjusted_merchandize_total_tax": 3.75,
    "adjusted_shipping_total_tax": 0,
    "billing_address": {
      "city": "Boston",
      "country_code": "US",
      "first_name": "Jane",
      "full_name": "Jane Doe",
      "last_name": "Doe",
      "postal_code": "29199"
    },
    "channel_type": "callcenter",
    "c_created_by": "testAgent"
  },
  "relevance": 2.822207450866699
}
```

### result\_page

Data that can be used to get the next and previous page of a Data API results object.

*   `count` (_integer (int32)_) The number of returned documents.
*   `db_start_record_` (_integer (int32)_) The zero-based index of the record that we want to start with, used to optimize special handling
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.

### order

Document representing an order.

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency.
    
    Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `billing_address` (_order\_address_) The billing address. This property is part of basket checkout information only.
*   `bonus_discount_line_items` (_array of bonus\_discount\_line\_item_) The bonus discount line items of the line item container.
*   `channel_type` (_string_, read-only) The sales channel for the order.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `google`, `tiktok`, `snapchat`, `youtube`, `whatsapp`.
*   `confirmation_status` (_string_) The confirmation status of the order.  
    Allowed values: `not_confirmed`, `confirmed`.
*   `coupon_items` (_array of coupon\_item_) The sorted array of coupon items. This array can be empty.
*   `created_by` (_string_) The name of the user who created the order.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `customer_info` (_customer\_info_) The customer information for logged in customers. This property is part of basket checkout information only.
*   `customer_name` (_string_) The name of the customer associated with this order.
*   `export_status` (_string_) The export status of the order.  
    Allowed values: `not_exported`, `exported`, `ready`, `failed`.
*   `external_order_status` (_string_) The external status of the order.
*   `gift_certificate_items` (_array of gift\_certificate\_item_) The sorted array of gift certificate line items. This array can be empty.
*   `global_party_id` (_string_) globalPartyId is managed by Customer 360. Its value can be changed.
*   `grouped_tax_items` (_array of grouped\_tax_) Tax values that are summed and grouped based on the tax rate. The tax totals of the line items with the same tax rate will be grouped together and summed up. This will not affect calculation in any way.
*   `guest` (_boolean_) The registration status of the customer.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `merchandize_total_tax` (_number (double)_)
    
    The products total tax in purchase currency.
    
    Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
    
*   `notes` (_simple\_link_) The notes for the line item container.
*   `order_no` (_string_, read-only) The order number of the order.
*   `order_price_adjustments` (_array of price\_adjustment_) The array of order level price adjustments. This array can be empty.
*   `order_token` (_string_) The order token used to secure the lookup of an order on base of the plain order number. The order token contains only URL safe characters.
*   `order_total` (_number (double)_) The total price of the order, including products, shipping and tax. This property is part of basket checkout information only.
*   `payment_instruments` (_array of order\_payment\_instrument_) The payment instruments list for the order.
*   `payment_status` (_string_) The payment status of the order.  
    Allowed values: `not_paid`, `part_paid`, `paid`.
*   `product_items` (_array of product\_item_) The sorted array of product items (up to a maximum of 50 items by default). This array can be empty.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipments` (_array of shipment_) The array of shipments. This property is part of basket checkout information only.
*   `shipping_items` (_array of shipping\_item_) The sorted array of shipping items. This array can be empty.
*   `shipping_status` (_string_) The shipping status of the order.  
    Allowed values: `not_shipped`, `part_shipped`, `shipped`.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the order after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross. This property is part of basket checkout information only.
    
    ```
         Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `site_id` (_string_) The site where the order resides.
*   `source_code` (_string_) Gets the source code assigned to this basket.
*   `status` (_string_) The status of the order.  
    Allowed values: `created`, `new`, `open`, `completed`, `cancelled`, `replaced`, `failed`.
*   `tax_rounded_at_group` (_boolean_) If the tax is rounded at group level then this is set to true, false if the tax is rounded at item or unit level
*   `tax_total` (_number (double)_) The total tax amount of the order. This property is part of basket checkout information only.
*   `taxation` (_string_) The taxation the line item container is based on.  
    Allowed values: `gross`, `net`.

_Example_

```
{
  "adjusted_merchandize_total_tax": 0.05,
  "adjusted_shipping_total_tax": 0,
  "billing_address": {
    "city": "Boston",
    "country_code": "US",
    "first_name": "Jeff",
    "full_name": "Jeff Lebowski",
    "last_name": "Lebowski",
    "c_strValue": "cTest"
  },
  "creation_date": "2014-11-06T13:36Z",
  "currency": "USD",
  "customer_info": {
    "customer_no": "jlebowski",
    "email": "jeff@lebowski.com"
  },
  "merchandize_total_tax": 5,
  "order_no": "00000101",
  "order_token": "XizrH5hY1vB-Mxno-zfoCqTkegl3y7_OrRPGNZFlYG8",
  "order_total": 1.06,
  "payment_instruments": [
    {
      "amount": 1,
      "id": "cdKCIiWbNVndQaaadhlSa35gtp",
      "payment_bank_account": {
        "drivers_license_last_digits": "ense",
        "drivers_license_masked": "**************ense",
        "number_last_digits": "mber",
        "number_masked": "*************mber"
      },
      "payment_card": {
        "card_type": "testVisa",
        "credit_card_expired": false,
        "expiration_month": 4,
        "expiration_year": 21.2,
        "holder": "TestPerson",
        "number_last_digits": "mber",
        "number_masked": "**********mber"
      },
      "payment_method_id": "OCAPI_Payment_Simple"
    }
  ],
  "product_items": [
    {
      "adjusted_tax": 5,
      "base_price": 16.49,
      "bonus_product_line_item": false,
      "item_id": "cdHBEiWbNV9ZcaaadhrCk35gtp",
      "item_text": "Simple Product",
      "price": 16.49,
      "price_after_item_discount": 16.49,
      "price_after_order_discount": 1,
      "product_id": "SimpleProduct",
      "product_name": "Simple Product",
      "quantity": 1,
      "tax": 5,
      "tax_basis": 16.49,
      "tax_class_id": null,
      "tax_rate": 0.05,
      "c_strValue": "Test"
    }
  ],
  "product_sub_total": 16.49,
  "product_total": 1,
  "shipments": [
    {
      "id": "me",
      "shipping_address": {
        "city": "Boston",
        "country_code": "US",
        "first_name": "Jeff",
        "full_name": "Jeff Lebowski",
        "last_name": "Lebowski",
        "c_strValue": "cTest"
      },
      "shipping_method": {
        "description": {
          "default": "The base shipping method."
        },
        "id": "BaseShippingMethod",
        "name": {
          "default": "Base Shipping Method"
        },
        "price": 0.01,
        "c_somestring": "ShippingMethod String Value"
      }
    }
  ],
  "shipping_items": [
    {
      "adjusted_tax": 0,
      "base_price": 0.01,
      "item_id": "devgoiWbNVc92aaadhrSk35gtp",
      "item_text": "Shipping",
      "price": 0.01,
      "price_after_item_discount": 0.01,
      "shipment_id": "me",
      "tax": 0,
      "tax_basis": 0.01,
      "tax_class_id": "DefaultTaxClass",
      "tax_rate": 0.05
    }
  ],
  "shipping_total": 0.01,
  "shipping_total_tax": 0,
  "status": "created",
  "tax_total": 0.05,
  "c_strValue": "before submit basket",
  "c_textValue": "after submit basket"
}
```

### order\_address

Document representing an order address.

*   `address1` (_string_) The first address.
*   `address2` (_string_) The second address.
*   `city` (_string_) The city.
*   `company_name` (_string_) The company name.
*   `country_code` (_string_) The two-letter ISO 3166-1 (Alpha-2) country code.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States.
*   `first_name` (_string_) The first name.
*   `full_name` (_string_) The full name.
*   `id` (_string_) Id used to identify this address
*   `job_title` (_string_) The job title.
*   `last_name` (_string_) The last name.
*   `phone` (_string_) The phone number.
*   `post_box` (_string_) The post box.
*   `postal_code` (_string_) The postal code.
*   `salutation` (_string_) The salutation.
*   `second_name` (_string_) The second name.
*   `state_code` (_string_) The state code.
*   `suffix` (_string_) The suffix.
*   `suite` (_string_) The suite.
*   `title` (_string_) The title.

_Example_

```
{
  "city": "Boston",
  "country_code": "US",
  "first_name": "John",
  "last_name": "Smith"
}
```

### bonus\_discount\_line\_item

Document representing a bonus discount line item

*   `bonus_products` (_array of product\_details\_link_) The list of links to the bonus products the customer can choose from.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, if applicable.
*   `id` (_string_) The ID of the line item.
*   `max_bonus_items` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotion_id` (_string_) The ID of the promotion which triggered the creation of the line item.

### coupon\_item

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256.
*   `coupon_item_id` (_string_) The coupon item id.
*   `status_code` (_string_) The status of the coupon item.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is 'applied' or 'no\_applicable\_promotion'.

_Example_

```
{
  "code": "the99coupon"
}
```

### customer\_info

Document representing information used to identify a customer.

*   `customer_id` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `customer_name` (_string_)
*   `customer_no` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `email` (_string (email)_, required) The customer's email address.

_Example_

```
{
  "customer_no": "customer0012",
  "email": "valid@email.com"
}
```

### gift\_certificate\_item

A gift certificate item.

*   `amount` (_number (double)_, required) The certificate item amount.
*   `gift_certificate_item_id` (_string_) Id used to identify this item
*   `message` (_string_) The certificate's message.  
    Maximum length: 4000.
*   `recipient_email` (_string_, required) The recipient's email.  
    Minimum length: 1.
*   `recipient_name` (_string_) The recipient's name.
*   `sender_name` (_string_) The sender's name.
*   `shipment_id` (_string_) The shipment id.

_Example_

```
{
  "amount": 200,
  "message": "Present from your brother",
  "recipient_email": "peter@example.com",
  "recipient_name": "Peter Doe",
  "sender_name": "John Doe"
}
```

### grouped\_tax

Document representing a tax rate with it's summed up tax values

*   `tax_rate` (_number (double)_) The tax rate
*   `tax_value` (_number (double)_) The summed up tax total for the tax rate

### simple\_link

Document representing a link to another resource.

*   `link` (_string_) The link to the resource.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/orders/bc0KwiWexX0ZQaaadqRTwMZFga/notes"
}
```

### price\_adjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level. They can be created by the promotion engine (if the custom flag is set to false) or can be added by custom logic (if the custom flag is set to true). For custom price adjustments created by a user, the manual flag should be set to true; this is always the case for price adjustments created using OCAPI.

A price adjustment created by custom logic can either define a price that defines the absolute price reduction or define a discount from which a price reduction is calculated (amount, percentage, and fixed\_price discounts are supported). The applied\_discount property describes the discount applied to create the price-adjustment.

*   `applied_discount` (_discount_) A price adjustment that provides details of the discount that was applied. This is `null` for custom price adjustments created without discount details.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, provided the price adjustment was created as the result of a promotion being triggered by a coupon.
*   `created_by` (_string_) The user who created the price adjustment.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.
*   `item_text` (_string_) The text describing the item in more detail.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `manual` (_boolean_)
    
    A flag indicating whether this price adjustment was created in a manual process.
    
    For custom price adjustments created using the shop API, this _always_ returns `true`. Using the scripting API, however, it is possible to set this to `true` or `false`, according to the use case.
    
*   `price` (_number (double)_) The adjustment price.
*   `price_adjustment_id` (_string_) The price adjustment id (uuid).
*   `promotion_id` (_string_) The id of the related promotion. Custom price adjustments can be assigned any promotion id so long it is not used by a price adjustment belonging to the same item and is not used by promotion defined in the promotion engine. If not specified, a promotion id is generated.
*   `promotion_link` (_string_) The URL addressing the related promotion.
*   `reason_code` (_string_) The reason why this price adjustment was made.  
    Allowed values: `BACKORDER`, `EVEN_EXCHANGE`, `PRICE_MATCH`. Value meanings: `BACKORDER`: Backorder; `EVEN_EXCHANGE`: Even Exchange; `PRICE_MATCH`: Price Match.

### order\_payment\_instrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.
*   `authorization_status` (_status_) The authorization status of the payment transaction.
*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code.
*   `payment_bank_account` (_payment\_bank\_account_) The payment bank account.
*   `payment_card` (_payment\_card_) The payment card.
*   `payment_instrument_id` (_string_) The payment instrument ID.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "amount": 1,
  "payment_card": {
    "card_type": "Visa",
    "credit_card_expired": false,
    "expiration_month": 1,
    "expiration_year": 2021,
    "holder": "John Doe",
    "masked_number": "***********1111",
    "number_last_digits": "1111"
  },
  "payment_instrument_id": "ceDUYiWbN1IkkaaadkYHRkclwC",
  "payment_method_id": "CREDIT_CARD",
  "c_strValue": "any custom value"
}
```

### product\_item

Document representing a product item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_, required) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 5,
  "base_price": 16.49,
  "bonus_product_line_item": false,
  "item_id": "cdHBEiWbNV9ZcaaadhrCk35gtp",
  "item_text": "Simple Product",
  "price": 16.49,
  "price_after_item_discount": 16.49,
  "price_after_order_discount": 1,
  "product_id": "SimpleProduct",
  "product_name": "Simple Product",
  "quantity": 1,
  "tax": 5,
  "tax_basis": 16.49,
  "tax_class_id": null,
  "tax_rate": 0.05,
  "c_strValue": "Test"
}
```

### shipment

Document representing a shipment.

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency. Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift.
*   `gift_message` (_string_) The gift message.
*   `merchandize_total_tax` (_number (double)_) The products total tax in purchase currency. Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipment_id` (_string_) The order specific id to identify the shipment.
*   `shipment_no` (_string_)
    
    Returns the shipment number for this shipment.
    
    This number is automatically generated.
    
*   `shipment_total` (_number (double)_)
    
    The total price of the shipment, including products, shipping and tax.
    
    Note that order level adjustments are not considered.
    
*   `shipping_address` (_order\_address_) The shipping address.
*   `shipping_method` (_shipping\_method_) The shipping method.
*   `shipping_status` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the shipment after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross.
    
    ```
         net. Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `tax_total` (_number (double)_)
    
    The total tax amount of the shipment.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `tracking_number` (_string_) The tracking number of the shipment.

_Example_

```
{
  "gift": true,
  "gift_message": "Happy Birthday, Sværre",
  "id": "StandardShipping",
  "shipping_address": {
    "city": "Boston",
    "country_code": "US",
    "first_name": "John",
    "last_name": "Smith"
  },
  "shipping_method": {
    "id": "BaseShippingMethod"
  }
}
```

### shipping\_item

Document representing a shipping item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `shipment_id` (_string_) The identifier of the shipment to which this item belongs.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 0,
  "base_price": 0.01,
  "item_id": "devgoiWbNVc92aaadhrSk35gtp",
  "item_text": "Shipping",
  "price": 0.01,
  "price_after_item_discount": 0.01,
  "shipment_id": "me",
  "tax": 0,
  "tax_basis": 0.01,
  "tax_class_id": "DefaultTaxClass",
  "tax_rate": 0.05
}
```

### product\_details\_link

Document representing a link to the resource for product details.

*   `link` (_string_) The target of the link.
*   `product_description` (_string_) The description of the product.
*   `product_id` (_string_, required) The id of the product.
*   `product_name` (_string_) The name of the product.
*   `title` (_string_) The link title.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/products/BlueJeansType1",
  "product_id": "BlueJeansType1",
  "product_name": "Product w/- Local Option",
  "title": "Product w/- Local Option"
}
```

### discount

Document representing a discount that was _either_ optionally applied when creating a custom price adjustment _or_ applied by the promotion engine. The property `type` is mandatory; the properties `amount` and `priceBookId` are used only in association with specific types. Some examples:

*   Type `percentage` with percentage `15.00` : a 15% discount was applied.
    
*   Type `amount` with amount `5.99` : a discount was applied to reduce the (unit) price by 5.99.
    
*   Type `fixed_price` with amount `49.99` : a discount was applied to reduce the price to 49.99.
    
*   Type `free` : a discount was applied to reduce the price to zero.
    
*   Type `price_book_price` with price\_book\_id `MyPriceBook` : a discount was applied to set the price to that defined in MyPriceBook.
    

*   `amount` (_number (double)_) The amount that is used with the amount and fixed price types.
*   `percentage` (_number (double)_) The percentage that is used with percentage types.
*   `price_book_id` (_string_) The price book id that is used with some types.
*   `type` (_string_, required) The type of discount.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`.

_Example_

```
{
  "amount": 15,
  "type": "amount"
}
```

### status

Document representing a status of an object.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_)
    
    The status.
    
    For more information on the status values see dw.system.Status.OK and dw.system.Status.ERROR.
    

### payment\_bank\_account

Document representing a payment bank account.

*   `drivers_license_last_digits` (_string_) The last 4 characters of the decrypted driver's license number of the bank account associated with this payment instrument.  
    Maximum length: 256.
*   `drivers_license_state_code` (_string_) The driver license state code.  
    Maximum length: 256.
*   `holder` (_string_) The holder of the bank account.  
    Maximum length: 256.
*   `masked_drivers_license` (_string_)
    
    The decrypted driver's license number of the bank account with all but the last 4 characters replaced with a '\*' character.
    
    ```
         with a '*' character.
    ```
    
      
    Maximum length: 256.
*   `masked_number` (_string_) The bank account masked number.  
    Maximum length: 256.
*   `number_last_digits` (_string_) The last digits of the bank account number.  
    Maximum length: 256.

_Example_

```
{
  "drivers_license_last_digits": "ense",
  "drivers_license_masked": "**************ense",
  "number_last_digits": "mber",
  "number_masked": "*************mber"
}
```

### payment\_card

Document representing a payment card.

*   `card_type` (_string_) The payment card type (for example, 'Visa').  
    Maximum length: 256.
*   `credit_card_expired` (_boolean_) A flag indicating if the credit card is expired.
*   `credit_card_token` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.
*   `expiration_month` (_integer (int32)_) The month when the payment card expires.
*   `expiration_year` (_integer (int32)_) The year when the payment card expires.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256.
*   `issue_number` (_string_) The payment card issue number.  
    Maximum length: 256.
*   `masked_number` (_string_) The masked credit card number.  
    Maximum length: 4000.
*   `number_last_digits` (_string_) The last digits of credit card number.  
    Maximum length: 4000.
*   `valid_from_month` (_integer (int32)_) The payment card valid from month.  
    Minimum: 1. Maximum: 12.
*   `valid_from_year` (_integer (int32)_) The payment card valid from year.

_Example_

```
{
  "card_type": "Visa",
  "credit_card_expired": false,
  "expiration_month": 2,
  "expiration_year": 2022,
  "holder": "John Smith",
  "masked_number": "***********ber2",
  "number_last_digits": "ber2"
}
```

### option\_item

Document representing an option item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_id` (_string_, required) The id of the option.  
    Maximum length: 256.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `option_value_id` (_string_, required) The id of the option value.  
    Maximum length: 256.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "option_id": "Warranty",
  "option_value_id": "oneYear"
}
```

### product\_list\_item\_reference

*   `id` (_string_, required) The id of the product list item.
*   `priority` (_integer (int32)_)
*   `product_details_link` (_product\_details\_link_)
*   `product_list` (_product\_list\_link_) The link of the product list, the item is assigned
*   `public` (_boolean_)
*   `purchased_quantity` (_number (double)_)
*   `quantity` (_number (double)_)  
    Minimum: 0.
*   `type` (_string_)  
    Allowed values: `product`, `gift_certificate`.

### shipping\_method

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.
*   `external_shipping_method` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method id.  
    Maximum length: 256.
*   `name` (_string_) The localized name of the shipping method.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs and product level fix and surcharge costs.
*   `shipping_promotions` (_array of shipping\_promotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

_Example_

```
{
  "id": "BaseShippingMethod"
}
```

### product\_list\_link

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `link` (_string_) The target of the link.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`.

### shipping\_promotion

Document representing a shipping promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotion_name` (_string_) The localized promotion name.

### bool\_filter

Document representing a boolean filter.

A boolean filter allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is configured with a boolean operator (AND, OR, NOT) and a list of filters the operator relates to. If multiple filters are given to a boolean NOT operator, this is interpreted as a NOT upon a boolean OR of the given filters.

**Example:** (id="myId" AND coupon\_id="couponOne")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "and",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["myId"\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["couponOne"\] } }
\]
}
}
}
}

**Example:** (id="holidaySale" OR redemption\_count BETWEEN(1, 20)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "or",
filters: \[
{ term\_filter: { field: "id", operator: "is", values: \["holidaySale"\] } },
{ range\_filter: { field: "redemption\_count", from: 1, to: 20 } }
\]
}
}
}
}

**Example:** NOT(enabled=false OR coupon\_id="special")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
bool\_filter: {
operator: "not",
filters: \[
{ term\_filter: { field: "enabled", operator: "is", values: \[false\] } },
{ term\_filter: { field: "coupon\_id", operator: "is", values: \["special"\] } }
\]
}
}
}
}

*   `filters` (_array of filter_) A list of filters, which are logically combined by an operator.
*   `operator` (_string_, required) The logical operator the filters are combined with.  
    Allowed values: `and`, `or`, `not`.

### bool\_query

A boolean query allows construction of full logical expression trees consisting of other queries (usually term and text queries). A boolean query basically has 3 sets of clauses that 'must', 'should' and / or 'must not' match. If 'must', 'must\_not', or 'should' appear in the same boolean query, they are combined logically using the AND operator. The difference between must and should operators is that the must operator requires all subqueries to match whereas the should operator only requires one match

**Example:** (id = 'foo' AND description LIKE 'bar')

query: {
bool\_query: {
must: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (id = 'foo' OR description LIKE 'bar')

query: {
bool\_query: {
should: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** (NOT (id = 'foo' AND description LIKE 'bar'))

query: {
bool\_query: {
must\_not: \[
{ term\_query: { fields: \["id"\], operator: "is", values: \["foo"\] } },
{ text\_query: { fields: \["description"\], search\_phrase: "bar" } }
\]
}
}

**Example:** ((coupon\_id LIKE "limit" AND description LIKE "limit per customer") AND NOT (enabled=false))

query: {
bool\_query: {
must: \[
{ text\_query: { fields: \[ "coupon\_id" \], search\_phrase: "limit" } },
{ text\_query: { fields: \[ "description" \], search\_phrase: "limit per customer" } }
\],
must\_not: \[
{ term\_query: { fields: \[ "enabled" \], operator: "is", values: \[false\] } }
\]
}
}

*   `must` (_array of query_) List of queries that must match.
*   `must_not` (_array of query_) List of queries that must not match.
*   `should` (_array of query_) List of queries that should match (i.e., at least one query must match).

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### filter

Document representing a filter.

A filter contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   term\_filter - matches records where a field (or fields) exactly match some simple value (including null).
    
*   range\_filter - matches records where a field value lies in a specified range.
    
*   query\_filter - provides filtering based on a query.
    
*   bool\_filter - provides filtering of records using a set of filters combined with a specified operator.
    

Type: `any`.

### filtered\_query

A filtered query allows to filter the result of a (possibly complex) query using a (possibly complex) filter.

**Example:**

query : {
filtered\_query: {
query: {
text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" }
},
filter: {
term\_filter: {
field: "enabled", operator: "is", values: \[ false \]
}
}
}
}

*   `filter` (_filter_, required) The (possibly complex) filter object.
*   `query` (_query_, required) The query object.

### match\_all\_query

A match all query simply matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

**Example:**

query: {
match\_all\_query: {}
}

Type: `any`.

### nested\_query

A nested query queries nested documents that are part of a larger document. The classical example is a product master with variants (in one big document) where you want to constrain a search to masters that have variants that match multiple constraints (like color = blue AND size = M). This query is not compatible with some search types. **Example:** finds all the documents that has firstname = "John" and lastname = "Doe"

{
"query": {
"bool\_query": {
"must": \[
{
"nested\_query": {
"path": "order.shipping\_addresses",
"query": {
"bool\_query": {
"must": \[
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.first\_name" \],
"operator": "is",
"values": \[ "John" \]
}
}
\]
}
},
{
"bool\_query": {
"must": \[
{
"term\_query": {
"fields": \[ "order.shipping\_addresses.last\_name" \],
"operator": "is",
"values": \[ "Doe" \]
}
}
\]
}
}
\]
}
},
"score\_mode": "avg"
}
}
\]
}
}
}

*   `path` (_string_, required)
*   `query` (_query_, required)
*   `score_mode` (_string_)  
    Allowed values: `avg`, `total`, `max`, `none`.

### query\_filter

Document representing a query filter. A query filter wraps any query and allows it to be used as a filter.

**Example:** (coupon\_id contains "disabled" AND (enabled=false OR active=false))

query : {
filtered\_query: {
query: { text\_query: { fields: \["coupon\_id"\], search\_phrase: "disabled" } },
filter: {
query\_filter: {
query: {
term\_query: { fields: \["enabled","active"\], operator: "is", values: \[ false \] }
}
}
}
}
}

*   `query` (_query_, required) The query to use as a filter.

### range2\_filter

Document representing a range comparison with a range filter, named Range2Filter.

A Range2Filter allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes ("from\_field" and "to\_field") that specify the extent of a range, such as the attributes "valid\_from" and "valid\_to".

The second range (R2) is defined by "from\_value" and "to\_value".

The filter mode specifies the method used to compare the two ranges:

*   overlap: R1 overlaps fully or partially with R2
    
*   containing: R1 contains R2
    
*   contained: R1 is contained in R2
    

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** (valid dates overlap with the range January 1, 2007 through January 1, 2017)

"query" : {
"filtered\_query": {
"filter": {
"range2\_filter": {
"from\_field": "valid\_from",
"to\_field": "valid\_to",
"filter\_mode":"overlap",
"from\_value": "2007-01-01T00:00:00.000Z",
"to\_value": "2017-01-01T00:00:00.000Z"
}
},
"query": { "match\_all\_query": {} }
}
}

*   `filter_mode` (_string_) Compare mode: overlap, containing, or contained. If not specified, the default is overlap.  
    Allowed values: `overlap`, `containing`, `contained`.
*   `from_field` (_string_, required) The field name of the field that starts the first range.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `from_value` (_object_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `to_field` (_string_, required) The field name of the field that ends the first range.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the second range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to_value` (_object_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.

### range\_filter

Document representing a range filter.

A range filter allows you to restrict a search result to hits that have values for a given attribute that fall into a given value range. The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended (at one end only). You can configure whether the lower and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

**Example:** ( redemption\_count BETWEEN (0,10\] )

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
range\_filter: {
field: "redemption\_count",
from: 0,
to: 10,
from\_inclusive: false
}
}
}
}

*   `field` (_string_, required) The search field.
*   `from` (_object_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
*   `from_inclusive` (_boolean_) Indicates whether the lower bound of the range is inclusive. If not specified, the default is true. Set to false to make the lower bound exclusive.
*   `to` (_object_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
*   `to_inclusive` (_boolean_) Indicates whether the upper bound of the range is inclusive. If not specified, the default is true. Set to false to made the upper bound exclusive.

### term\_filter

Document representing a term filter.

A term filter allows you to restrict a search result to hits that match (exactly) one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criterion you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

**Example:** (id="my\_id")

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "is",
values: \["my\_id"\]
}
}
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "id",
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}
}
}

**Example:** (description=NULL)

query: {
filtered\_query: {
query: { match\_all\_query: {} },
filter: {
term\_filter: {
field: "description",
operator: "is\_null"
}
}
}
}

*   `field` (_string_, required) The filter field.
*   `operator` (_string_, required) The operator to compare the field's values with the given ones.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The filter values.

### term\_query

A term query matches one (or more) value(s) against one (or more) document field(s). A document is considered a hit if one of the values matches (exactly) with at least one of the given fields. The operator "is" can only take one value, while "one\_of" can take multiple values. If multiple fields are specified, they are combined using the OR operator. The `less` and `greater` operators are not compatible with some search types. To query based on numeric bounds in those cases, you can use a range filter on a filtered query .

**Elastic only** : If used with multiple fields, the query is internally handled as a boolean OR of DisjointMaxQueries (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

**Example:** (id="my\_id")

query: {
term\_query: {
fields: \["id"\],
operator: "is",
values: \["my\_id"\]
}
}

**Example:** (id IN ("my\_id","other\_id"))

query: {
term\_query: {
fields: \["id"\],
operator: "one\_of",
values: \["my\_id","other\_id"\]
}
}

**Example:** (id=null)

query: {
term\_query: {
fields: \["description"\],
operator: "is\_null"
}
}

**Example:** ((id IN ('generic', 'keyword')) OR (description IN ('generic', 'keyword'))

query: {
term\_query: {
fields: \["id", "description"\],
operator: "one\_of",
values: \["generic","keyword"\]
}
}

*   `fields` (_array of string_, required) The document field(s) the value(s) are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`.
*   `values` (_array of object_) The values the field(s) are compared against, combined with the operator.

### text\_query

A text query is used to match some text (i.e. a search phrase possibly consisting of multiple terms) against one or multiple fields. In case multiple fields are provided, the phrase conceptually forms a logical OR over the fields. In this case, the terms of the phrase basically have to match the text that would result from concatenating all given fields.

**Example:** (coupon\_id contains "xmas" )

query: {
text\_query: {
fields: \["coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (coupon\_id contains "xmas" OR description contains "xmas")

query: {
text\_query: {
fields: \["description", "coupon\_id"\],
search\_phrase: "xmas"
}
}

**Example:** (description contains "holiday" AND description contains "bojo")

query: {
text\_query: {
fields: \["description"\],
search\_phrase: "holiday bogo"
}
}

*   `fields` (_array of string_, required) The document fields the search phrase has to match.  
    Minimum items: 1.
*   `search_phrase` (_string_, required) A search phrase which may consist of multiple terms.

<!-- document id=746a0422809a51487d77d0f0d8529871426f0058af012db79b83707dfe98092f url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-orders.md -->

Shop Orders (deprecated)

# Shop Orders (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Submit basket

`POST /orders`

Operation ID: `Submit basket`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Submits an order based on a prepared basket. Note: If the basket has been submitted using Order Center (considered by it's client id) the channel type will be set to "Call Center". In case another channel type was set by a script before submitting the basket, the channel type will be reset to "Call Center" and a warning will be logged. The only considered value from the request body is **basket\_id** .

This endpoint may return the following faults:

*   400 - GiftCertificateCreationException - Thrown if a failure during the creation of a gift certificate for a gift certificate item.
*   400 - InvalidBasketIdException - Indicates that the basket id in the request body is null or empty.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidProductItemException - Indicates an invalid product item.
*   400 - InvalidProductOptionItemException - Indicates that an option with the specified option id is unknown.
*   400 - InvalidProductOptionValueItemException - Indicates that an option with the specified option value id is unknown.
*   400 - ProductItemNotAvailableException - Thrown if a product item is not available.
*   400 - ValidationException - Indicates that the basket contains flashes.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `basket`.

#### Responses

*   **400** `GiftCertificateCreationException` - Thrown if a failure during the creation of a gift certificate for a gift certificate item. or `InvalidBasketIdException` - Indicates that the basket id in the request body is null or empty. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidProductItemException` - Indicates an invalid product item. or `InvalidProductOptionItemException` - Indicates that an option with the specified option id is unknown. or `InvalidProductOptionValueItemException` - Indicates that an option with the specified option value id is unknown. or `ProductItemNotAvailableException` - Thrown if a product item is not available. or `ValidationException` - Indicates that the basket contains flashes.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### GET Get order

`GET /orders/{order_no}`

Operation ID: `Get order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Gets information for an order.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - Indicates that the order with the given order number is unknown.

#### Parameters

*   `order_no` (path, string, required) the order number  
    Minimum length: 1.

#### Responses

*   **404** `OrderNotFoundException` - Indicates that the order with the given order number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### PUT Submit basket with given order number

`PUT /orders/{order_no}`

Operation ID: `Submit basket with given order number`. Tags: orders. Security: oauth2\_application; customers\_auth; client\_id.

Submits an order with a given order number, based on a prepared basket. The only considered value from the request body is **basket\_id** .

This endpoint may return the following faults:

*   400 - GiftCertificateCreationException - Thrown if a failure during the creation of a gift certificate for a gift certificate item.
*   400 - InvalidBasketIdException - Indicates that the basket id in the request body is null or empty.
*   400 - InvalidCustomerException - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   400 - InvalidProductItemException - Indicates an invalid product item.
*   400 - InvalidProductOptionItemException - Indicates that an option with the specified option id is unknown.
*   400 - InvalidProductOptionValueItemException - Indicates that an option with the specified option value id is unknown.
*   400 - ProductItemNotAvailableException - Thrown if a product item is not available.
*   400 - ValidationException - Indicates that the basket contains flashes.
*   404 - BasketNotFoundException - Indicates that the basket with the given basket id is unknown.
*   409 - DuplicateOrderNumberException - 409 CONFLICT Indicates that the requested order number is already allocated to an existing order.

#### Parameters

*   `order_no` (path, string, required) The order number to assign to the new order.  
    Minimum length: 1. Maximum length: 50.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `basket`.

#### Responses

*   **400** `GiftCertificateCreationException` - Thrown if a failure during the creation of a gift certificate for a gift certificate item. or `InvalidBasketIdException` - Indicates that the basket id in the request body is null or empty. or `InvalidCustomerException` - Indicates that the customer assigned to the basket does not match the verified customer represented by the JWT, not relevant when using OAuth. or `InvalidProductItemException` - Indicates an invalid product item. or `InvalidProductOptionItemException` - Indicates that an option with the specified option id is unknown. or `InvalidProductOptionValueItemException` - Indicates that an option with the specified option value id is unknown. or `ProductItemNotAvailableException` - Thrown if a product item is not available. or `ValidationException` - Indicates that the basket contains flashes.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `BasketNotFoundException` - Indicates that the basket with the given basket id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **409** `DuplicateOrderNumberException` - 409 CONFLICT Indicates that the requested order number is already allocated to an existing order.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### PATCH Update order

`PATCH /orders/{order_no}`

Operation ID: `Update order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Update an order.

Considered fields for update are status (same status transitions are possible as for dw.order.Order.setStatus(int status) plus CREATED to FAILED) and custom properties. During the call the correct channel type will be assured to be set for the order in a successful call. Without agent context the channel type will be storefront otherwise callcenter.

This endpoint may return the following faults:

*   404 - NotFoundException - Indicates that the order with the given order number is unknown.

#### Parameters

*   `order_no` (path, string, required) the order number  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order`.

#### Responses

*   **404** `NotFoundException` - Indicates that the order with the given order number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### GET Get notes from an order

`GET /orders/{order_no}/notes`

Operation ID: `Get notes from an order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Retrieves notes for an order.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - Thrown if the order with the given order number is unknown.

#### Parameters

*   `order_no` (path, string, required) The id of the order from which you want to retrieve notes.  
    Minimum length: 1.

#### Responses

*   **404** `OrderNotFoundException` - Thrown if the order with the given order number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `notes_result`.
    

### POST Add a note to an order

`POST /orders/{order_no}/notes`

Operation ID: `Add a note to an order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Adds a note to an existing order.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - Thrown if the order with the given order number is unknown.

#### Parameters

*   `order_no` (path, string, required) The id of the order to be modified.  
    Minimum length: 1.

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `note`.

#### Responses

*   **404** `OrderNotFoundException` - Thrown if the order with the given order number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### DELETE Remove a note from an order

`DELETE /orders/{order_no}/notes/{note_id}`

Operation ID: `Remove a note from an order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Removes an order note.

This endpoint may return the following faults:

*   404 - NoteNotFoundException - Indicates that the order with the given order number is unknown.
*   404 - OrderNotFoundException - Indicates that the order with the given order number is unknown.

#### Parameters

*   `order_no` (path, string, required) the id of the order to be modified  
    Minimum length: 1.
*   `note_id` (path, string, required) the id of the note to be removed  
    Minimum length: 1.

#### Responses

*   **404** `NoteNotFoundException` - Indicates that the order with the given order number is unknown. or `OrderNotFoundException` - Indicates that the order with the given order number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### POST Add payment instrument to order

`POST /orders/{order_no}/payment_instruments`

Operation ID: `Add payment instrument to order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Adds a payment instrument to an order. It is possible either to supply the full payment information or only a customer payment instrument id and amount. In case the customer payment instrument id was set all the other properties (except amount) are ignored and the payment data is resolved from the stored customer payment information. An attempt is made to authorize the order by passing it to the authorize or authorizeCreditCard hook.

Details:

*   The payment instrument is added with the provided details or the details from the customer payment instrument. The payment method must be applicable for the order see `GET /baskets/{basket_id}/payment_methods` , if the payment method is 'CREDIT\_CARD' `a payment_card` must be specified in the request.
    
*   Order authorization:
    
    To authorize the order one of two possible customization hooks is called and an `dw.order.OrderPaymentInstrument` is passed as an input argument.
    
    Which hook is called?
    
    *   If the request includes a `payment_card` or the `dw.order.OrderPaymentInstrument` contains a `creditCardType` the customization hook `dw.order.payment.authorizeCreditCard` is called. See `dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status` .
        
    *   Otherwise `dw.order.payment.authorize` is called. See `dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status` .
        
    
    What is the `dw.order.OrderPaymentInstrument` input argument passed to the hook?
    
    *   If the request contains a `customer_payment_instrument_id` the `dw.order.OrderPaymentInstrument` is copied from the customer payment instrument (An exception is thrown if none was found).
        
    *   Otherwise the data from the request document is passed ( `payment_card` or `payment_bank_account` etc. information).
        
    
    Note: the `amount` and the `security_code` (cvn) contained in the `payment_card` data will be propagated if available to `dw.order.payment.authorizeCreditCard` even if the `dw.order.OrderPaymentInstrument` is resolved from a customer payment instrument.
    
*   Customization hook `dw.ocapi.shop.order.afterPostPaymentInstrument` is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling `dw.order.OrderMgr.placeOrder(order : Order)` in the scripting API) results in the order being changed to status `NEW` and prepared for export.
    

This endpoint may return the following faults:

*   400 - InvalidOrderNumberException - Indicates that the given order number is invalid.
*   400 - InvalidPaymentMethodIdException - Indicates that the provided payment method is invalid or not applicable.
*   404 - OrderNotFoundException - Indicates that the order with the given order number is unknown.
*   404 - PaymentInstrumentNotFoundException - Indicates that a customer payment instrument could not be resolved based on the provided customer payment instrument id.

#### Parameters

*   `order_no` (path, string, required) the order number  
    Minimum length: 1.
*   `skip_authorization` (query, boolean)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_payment_instrument_request`.

#### Responses

*   **400** `InvalidOrderNumberException` - Indicates that the given order number is invalid. or `InvalidPaymentMethodIdException` - Indicates that the provided payment method is invalid or not applicable.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `OrderNotFoundException` - Indicates that the order with the given order number is unknown. or `PaymentInstrumentNotFoundException` - Indicates that a customer payment instrument could not be resolved based on the provided customer payment instrument id.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### DELETE Removes a payment instrument of an order

`DELETE /orders/{order_no}/payment_instruments/{payment_instrument_id}`

Operation ID: `Removes a payment instrument of an order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Removes a payment instrument of an order.

This endpoint may return the following faults:

*   404 - OrderNotFoundException - Indicates that the order with the given order number is unknown.
*   404 - PaymentInstrumentNotFoundException - Indicates that the payment instrument with the given payment instrument number is unknown.

#### Parameters

*   `order_no` (path, string, required) the order number  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) the id of the payment instrument to be updated  
    Minimum length: 1.

#### Responses

*   **404** `OrderNotFoundException` - Indicates that the order with the given order number is unknown. or `PaymentInstrumentNotFoundException` - Indicates that the payment instrument with the given payment instrument number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### PATCH Updates payment instrument of order

`PATCH /orders/{order_no}/payment_instruments/{payment_instrument_id}`

Operation ID: `Updates payment instrument of order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Updates a payment instrument of an order and passes the order and updated payment instrument to the correct payment authorizeCreditcard or authorize hook.

Details:

*   The payment instrument is updated with the provided details. The payment method must be applicable for the order see `GET /baskets/{basket_id}/payment_methods` , if the payment method is 'CREDIT\_CARD' a `payment_card` must be specified in the request.
    
*   Order authorization:
    
    To authorize the order one of two possible customization hooks is called and an `dw.order.OrderPaymentInstrument` is passed as an input argument.
    
    Which hook is called?
    
    *   If the request includes a `payment_card` or the `dw.order.OrderPaymentInstrument` contains a `creditCardType` the customization hook `dw.order.payment.authorizeCreditCard` is called. See `dw.order.hooks.PaymentHooks.authorizeCreditCard(order : Order, paymentDetails : OrderPaymentInstrument, cvn : String) : Status` .
        
    *   Otherwise `dw.order.payment.authorize` is called. See `dw.order.hooks.PaymentHooks.authorize(order : Order, paymentDetails : OrderPaymentInstrument) : Status` .
        
    
    What is the `dw.order.OrderPaymentInstrument` input argument passed to the hook?
    
    *   If the request contains a `customer_payment_instrument_id` the `dw.order.OrderPaymentInstrument` is copied from the customer payment instrument (An exception is thrown if none was found).
        
    *   Otherwise the data from the request document is passed ( `payment_card` or `payment_bank_account` etc. information).
        
    
    Note: the `amount` and the `security_code` (cvn) contained in the `payment_card` data will be propagated if available to `dw.order.payment.authorizeCreditCard` even if the `dw.order.OrderPaymentInstrument` is resolved from a customer payment instrument.
    
*   Customization hook `dw.ocapi.shop.order.afterPatchPaymentInstrument` is called. The default implementation places the order if the order status is CREATED and the authorization amount equals or exceeds the order total. Placing the order (equivalent to calling `dw.order.OrderMgr.placeOrder(order : Order)` in the scripting API) results in the order being changed to status `NEW` and prepared for export.
    

This endpoint may return the following faults:

*   400 - InvalidPaymentMethodIdException - Indicates that the provided payment method is invalid or not applicable.
*   400 - PaymentInstrumentPermanentlyMaskedException - Indicates that the basket payment instrument with the given id already is permanently masked.
*   404 - OrderNotFoundException - Indicates that the order with the given order number is unknown.
*   404 - PaymentInstrumentNotFoundException - Indicates that the payment instrument with the given payment instrument number is unknown.

#### Parameters

*   `order_no` (path, string, required) the order number  
    Minimum length: 1.
*   `payment_instrument_id` (path, string, required) the id of the payment instrument to be updated  
    Minimum length: 1.
*   `skip_authorization` (query, boolean)

#### Request body (required)

Media type: `application/json, text/xml`. Schema: `order_payment_instrument_request`.

#### Responses

*   **400** `InvalidPaymentMethodIdException` - Indicates that the provided payment method is invalid or not applicable. or `PaymentInstrumentPermanentlyMaskedException` - Indicates that the basket payment instrument with the given id already is permanently masked.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `OrderNotFoundException` - Indicates that the order with the given order number is unknown. or `PaymentInstrumentNotFoundException` - Indicates that the payment instrument with the given payment instrument number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `order`.
    

### GET Get applicable payment methods for an order

`GET /orders/{order_no}/payment_methods`

Operation ID: `Get applicable payment methods for an order`. Tags: orders. Security: customers\_auth; oauth2\_application; client\_id.

Gets the applicable payment methods for an existing order considering the open payment amount only.

This endpoint may return the following faults:

*   400 - InvalidCustomerException - Indicates that the customer assigned to the order does not match the verified customer represented by the JWT, not relevant when using OAuth.
*   404 - OrderNotFoundException - Indicates that the order with the given order number is unknown.

#### Parameters

*   `order_no` (path, string, required) the order number  
    Minimum length: 1.

#### Responses

*   **400** `InvalidCustomerException` - Indicates that the customer assigned to the order does not match the verified customer represented by the JWT, not relevant when using OAuth.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `OrderNotFoundException` - Indicates that the order with the given order number is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `payment_method_result`.
    

## Schemas

### basket

Document representing a basket.

The following flashes are used to indicate the invalidity of a basket:

*   InvalidProductItem - a product item (or bundled product item) refers to a product which no longer exists, is offline, or the product is no longer assigned to a site catalog.
    
*   InvalidOptionItem - indicates that an option item refers to an option id or option value which no longer exists.
    
*   OptionItemWithoutPrice - indicates an option item without a price.
    
*   InvalidCouponCode (until 17.2) - indicates a coupon item became invalid, for example because its redemption limit is reached.
    
*   ProductItemNotAvailable - indicates too little available inventory to support the item quantity.
    
*   ProductItemWithoutPrice - indicates that the item has no price.
    
*   CustomerEmailRequired (until 17.2) - indicates the need to specify a customer email.
    
*   ShippingAddressRequired - indicates the need to specify a shipping address.
    
*   BillingAddressRequired - indicates the need to specify a billing address.
    
*   ShippingMethodRequired - indicates the need to specify a shipping method.
    
*   ShippingMethodNotApplicable - indicates that the currently specified shipping method is not applicable for the given addresses or product items.
    
*   PaymentMethodRequired - indicates the need to specify a payment method.
    
*   PaymentMethodNotApplicable - the currently specified payment method is not applicable for the given addresses or product items.
    
*   OrderTotalNotSet - the basket calculation could not be completed for some reason.
    
*   ProductItemAdjustedPriceLessThanZero - a price adjustment reduces an item price to a value below zero and should be corrected.
    

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency.
    
    Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `agent_basket` (_boolean_) Is the basket created by an agent?
*   `basket_id` (_string_) The unique identifier for the basket.
*   `billing_address` (_order\_address_) The billing address. This property is part of basket checkout information only.
*   `bonus_discount_line_items` (_array of bonus\_discount\_line\_item_) The bonus discount line items of the line item container.
*   `channel_type` (_string_, read-only)
    
    The sales channel for the order.
    
    This is a read-only attribute that can't be modified by an OCAPI call. For OCAPI, the sales channel is determined based on the client ID and token used for the OCAPI call. Usually, a customer-based authentication sets the channel to Storefront, and an agent-based authentication sets it to CallCenter. Using applications that use other client IDs for OCAPI calls, like Customer Service Center, will set different channel types. To modify the channel type in OCAPI, use a hook. \*
    
      
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `google`, `tiktok`, `snapchat`, `youtube`, `whatsapp`.
*   `coupon_items` (_array of coupon\_item_) The sorted array of coupon items. This array can be empty.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `customer_info` (_customer\_info_) The customer information for logged in customers. This property is part of basket checkout information only.
*   `gift_certificate_items` (_array of gift\_certificate\_item_) The sorted array of gift certificate line items. This array can be empty.
*   `grouped_tax_items` (_array of grouped\_tax_) Tax values that are summed and grouped based on the tax rate. The tax totals of the line items with the same tax rate will be grouped together and summed up. This will not affect calculation in any way.
*   `inventory_reservation_expiry` (_string (date-time)_)
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `merchandize_total_tax` (_number (double)_)
    
    The products total tax in purchase currency.
    
    Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
    
*   `notes` (_simple\_link_) The notes for the line item container.
*   `order_price_adjustments` (_array of price\_adjustment_) The array of order level price adjustments. This array can be empty.
*   `order_total` (_number (double)_) The total price of the order, including products, shipping and tax. This property is part of basket checkout information only.
*   `payment_instruments` (_array of order\_payment\_instrument_) The payment instruments list for the order.
*   `product_items` (_array of product\_item_) The sorted array of product items (up to a maximum of 50 items by default). This array can be empty.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipments` (_array of shipment_) The array of shipments. This property is part of basket checkout information only.
*   `shipping_items` (_array of shipping\_item_) The sorted array of shipping items. This array can be empty.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the order after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross. This property is part of basket checkout information only.
    
    ```
         Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `source_code` (_string_) Gets the source code assigned to this basket.
*   `tax_rounded_at_group` (_boolean_) If the tax is rounded at group level then this is set to true, false if the tax is rounded at item or unit level
*   `tax_total` (_number (double)_) The total tax amount of the order. This property is part of basket checkout information only.
*   `taxation` (_string_) The taxation the line item container is based on.  
    Allowed values: `gross`, `net`.
*   `temporary_basket` (_boolean_) Is the basket created a temporary basket?

_Example_

```
{
  "basket_id": "bczFTaOjgEqUkaaadkvHwbgrP5",
  "currency": "USD",
  "customer_info": {
    "customer_id": "adNJrbxJovaT5DPxUSfOywk6Et",
    "email": ""
  },
  "order_total": 0,
  "product_sub_total": 0,
  "product_total": 0,
  "shipments": [
    {
      "id": "me",
      "shipment_id": "bc5OTaOjgEqUoaaadkvHwbgrP5"
    }
  ],
  "shipping_items": [
    {
      "item_id": "bcwsbaOjgEqUsaaadkvHwbgrP5",
      "shipment_id": "me"
    }
  ],
  "shipping_total": 0,
  "shipping_total_tax": 0,
  "tax_total": 0,
  "taxation": "net"
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### order

Document representing an order.

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency.
    
    Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `billing_address` (_order\_address_) The billing address. This property is part of basket checkout information only.
*   `bonus_discount_line_items` (_array of bonus\_discount\_line\_item_) The bonus discount line items of the line item container.
*   `channel_type` (_string_, read-only) The sales channel for the order.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `google`, `tiktok`, `snapchat`, `youtube`, `whatsapp`.
*   `confirmation_status` (_string_) The confirmation status of the order.  
    Allowed values: `not_confirmed`, `confirmed`.
*   `coupon_items` (_array of coupon\_item_) The sorted array of coupon items. This array can be empty.
*   `created_by` (_string_) The name of the user who created the order.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `customer_info` (_customer\_info_) The customer information for logged in customers. This property is part of basket checkout information only.
*   `customer_name` (_string_) The name of the customer associated with this order.
*   `export_status` (_string_) The export status of the order.  
    Allowed values: `not_exported`, `exported`, `ready`, `failed`.
*   `external_order_status` (_string_) The external status of the order.
*   `gift_certificate_items` (_array of gift\_certificate\_item_) The sorted array of gift certificate line items. This array can be empty.
*   `global_party_id` (_string_) globalPartyId is managed by Customer 360. Its value can be changed.
*   `grouped_tax_items` (_array of grouped\_tax_) Tax values that are summed and grouped based on the tax rate. The tax totals of the line items with the same tax rate will be grouped together and summed up. This will not affect calculation in any way.
*   `guest` (_boolean_) The registration status of the customer.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `merchandize_total_tax` (_number (double)_)
    
    The products total tax in purchase currency.
    
    Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
    
*   `notes` (_simple\_link_) The notes for the line item container.
*   `order_no` (_string_, read-only) The order number of the order.
*   `order_price_adjustments` (_array of price\_adjustment_) The array of order level price adjustments. This array can be empty.
*   `order_token` (_string_) The order token used to secure the lookup of an order on base of the plain order number. The order token contains only URL safe characters.
*   `order_total` (_number (double)_) The total price of the order, including products, shipping and tax. This property is part of basket checkout information only.
*   `payment_instruments` (_array of order\_payment\_instrument_) The payment instruments list for the order.
*   `payment_status` (_string_) The payment status of the order.  
    Allowed values: `not_paid`, `part_paid`, `paid`.
*   `product_items` (_array of product\_item_) The sorted array of product items (up to a maximum of 50 items by default). This array can be empty.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipments` (_array of shipment_) The array of shipments. This property is part of basket checkout information only.
*   `shipping_items` (_array of shipping\_item_) The sorted array of shipping items. This array can be empty.
*   `shipping_status` (_string_) The shipping status of the order.  
    Allowed values: `not_shipped`, `part_shipped`, `shipped`.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the order after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross. This property is part of basket checkout information only.
    
    ```
         Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `site_id` (_string_) The site where the order resides.
*   `source_code` (_string_) Gets the source code assigned to this basket.
*   `status` (_string_) The status of the order.  
    Allowed values: `created`, `new`, `open`, `completed`, `cancelled`, `replaced`, `failed`.
*   `tax_rounded_at_group` (_boolean_) If the tax is rounded at group level then this is set to true, false if the tax is rounded at item or unit level
*   `tax_total` (_number (double)_) The total tax amount of the order. This property is part of basket checkout information only.
*   `taxation` (_string_) The taxation the line item container is based on.  
    Allowed values: `gross`, `net`.

_Example_

```
{
  "adjusted_merchandize_total_tax": 0.05,
  "adjusted_shipping_total_tax": 0,
  "billing_address": {
    "city": "Boston",
    "country_code": "US",
    "first_name": "Jeff",
    "full_name": "Jeff Lebowski",
    "last_name": "Lebowski",
    "c_strValue": "cTest"
  },
  "creation_date": "2014-11-06T13:36Z",
  "currency": "USD",
  "customer_info": {
    "customer_no": "jlebowski",
    "email": "jeff@lebowski.com"
  },
  "merchandize_total_tax": 5,
  "order_no": "00000101",
  "order_token": "XizrH5hY1vB-Mxno-zfoCqTkegl3y7_OrRPGNZFlYG8",
  "order_total": 1.06,
  "payment_instruments": [
    {
      "amount": 1,
      "id": "cdKCIiWbNVndQaaadhlSa35gtp",
      "payment_bank_account": {
        "drivers_license_last_digits": "ense",
        "drivers_license_masked": "**************ense",
        "number_last_digits": "mber",
        "number_masked": "*************mber"
      },
      "payment_card": {
        "card_type": "testVisa",
        "credit_card_expired": false,
        "expiration_month": 4,
        "expiration_year": 21.2,
        "holder": "TestPerson",
        "number_last_digits": "mber",
        "number_masked": "**********mber"
      },
      "payment_method_id": "OCAPI_Payment_Simple"
    }
  ],
  "product_items": [
    {
      "adjusted_tax": 5,
      "base_price": 16.49,
      "bonus_product_line_item": false,
      "item_id": "cdHBEiWbNV9ZcaaadhrCk35gtp",
      "item_text": "Simple Product",
      "price": 16.49,
      "price_after_item_discount": 16.49,
      "price_after_order_discount": 1,
      "product_id": "SimpleProduct",
      "product_name": "Simple Product",
      "quantity": 1,
      "tax": 5,
      "tax_basis": 16.49,
      "tax_class_id": null,
      "tax_rate": 0.05,
      "c_strValue": "Test"
    }
  ],
  "product_sub_total": 16.49,
  "product_total": 1,
  "shipments": [
    {
      "id": "me",
      "shipping_address": {
        "city": "Boston",
        "country_code": "US",
        "first_name": "Jeff",
        "full_name": "Jeff Lebowski",
        "last_name": "Lebowski",
        "c_strValue": "cTest"
      },
      "shipping_method": {
        "description": {
          "default": "The base shipping method."
        },
        "id": "BaseShippingMethod",
        "name": {
          "default": "Base Shipping Method"
        },
        "price": 0.01,
        "c_somestring": "ShippingMethod String Value"
      }
    }
  ],
  "shipping_items": [
    {
      "adjusted_tax": 0,
      "base_price": 0.01,
      "item_id": "devgoiWbNVc92aaadhrSk35gtp",
      "item_text": "Shipping",
      "price": 0.01,
      "price_after_item_discount": 0.01,
      "shipment_id": "me",
      "tax": 0,
      "tax_basis": 0.01,
      "tax_class_id": "DefaultTaxClass",
      "tax_rate": 0.05
    }
  ],
  "shipping_total": 0.01,
  "shipping_total_tax": 0,
  "status": "created",
  "tax_total": 0.05,
  "c_strValue": "before submit basket",
  "c_textValue": "after submit basket"
}
```

### notes\_result

A result of a note request.

Contains notes for an object - for example, for a basket.

*   `notes` (_array of note_) The notes for an object.

_Example_

```
{
  "notes": [
    {
      "subject": "Unhappy customer",
      "text": "The customer was not very happy due to a delay."
    },
    {
      "subject": "Happy customer",
      "text": "The customer is already happy!"
    }
  ]
}
```

### note

Document representing a note to an object.

*   `created_by` (_string_) The author of the note.
*   `creation_date` (_string (date-time)_) The creation date of the note.
*   `id` (_string_) The ID of the note.
*   `subject` (_string_) The note's subject.  
    Maximum length: 256.
*   `text` (_string_) The note's text.  
    Maximum length: 4000.

_Example_

```
{
  "subject": "this is an example subject",
  "text": "This is a note because the customer was not very happy."
}
```

### order\_payment\_instrument\_request

Document representing an order payment instrument request.

*   `amount` (_number (double)_) The payment transaction amount.
*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `create_customer_payment_instrument` (_boolean_) A flag indicating whether a related customer payment instrument should be created. The CustomerPaymentInstrument is only created when the OrderPaymentInstrument was authorized successfully.
*   `customer_payment_instrument_id` (_string_) The id of a customer payment instrument.
*   `gift_certificate_code` (_string_) The gift certificate code.  
    Maximum length: 256.
*   `payment_bank_account` (_payment\_bank\_account\_request_) The payment bank account request data.
*   `payment_card` (_order\_payment\_card\_request_) The payment card.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "amount": 2,
  "payment_card": {
    "card_type": "Visa",
    "expiration_month": 2,
    "expiration_year": 2022,
    "holder": "Ed Smith",
    "number": "4111111111111111",
    "security_code": "112"
  },
  "payment_method_id": "CREDIT_CARD"
}
```

### payment\_method\_result

Result document of payment methods applicable for a basket.

*   `applicable_payment_methods` (_array of payment\_method_) The applicable payment methods.

_Example_

```
{
  "applicable_payment_methods": [
    {
      "id": "BANK_TRANSFER",
      "name": "Bank Transfer"
    },
    {
      "cards": [
        {
          "card_type": "Visa",
          "checksum_verification_enabled": true,
          "id": "CREDIT_CARD.Visa",
          "name": "Visa",
          "number_lengths": [
            "13",
            "16"
          ],
          "number_prefixes": [
            "4"
          ],
          "security_code_length": 3
        },
        {
          "card_type": "Master",
          "checksum_verification_enabled": true,
          "id": "CREDIT_CARD.Master",
          "name": "Mastercard",
          "number_lengths": [
            "16"
          ],
          "number_prefixes": [
            "2221-2720",
            "51-55"
          ],
          "security_code_length": 3
        },
        {
          "card_type": "Amex",
          "checksum_verification_enabled": true,
          "id": "CREDIT_CARD.Amex",
          "name": "American Express",
          "number_lengths": [
            "15"
          ],
          "number_prefixes": [
            "34",
            "37"
          ],
          "security_code_length": 4
        }
      ],
      "id": "CREDIT_CARD",
      "name": "Credit Card",
      "c_somestring": "PaymentMethod String Value"
    },
    {
      "description": "A conditional payment method on customer group 'Unregistered'.",
      "id": "OCAPI_Payment_Unregistered",
      "image": "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
      "name": "OCAPI Payment (Unregistered)"
    },
    {
      "description": "A conditional payment method on country 'DE'.",
      "id": "OCAPI_Payment_DE",
      "image": "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
      "name": "OCAPI Payment (DE)"
    },
    {
      "description": "A simple payment method without any conditions.",
      "id": "OCAPI_Payment_Simple",
      "image": "https://example.com/on/demandware.static/Sites-SiteGenesis-Site/Sites/default/v1426675691129/office.jpg",
      "name": "OCAPI Payment (Simple)"
    }
  ]
}
```

### order\_address

Document representing an order address.

*   `address1` (_string_) The first address.
*   `address2` (_string_) The second address.
*   `city` (_string_) The city.
*   `company_name` (_string_) The company name.
*   `country_code` (_string_) The two-letter ISO 3166-1 (Alpha-2) country code.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States.
*   `first_name` (_string_) The first name.
*   `full_name` (_string_) The full name.
*   `id` (_string_) Id used to identify this address
*   `job_title` (_string_) The job title.
*   `last_name` (_string_) The last name.
*   `phone` (_string_) The phone number.
*   `post_box` (_string_) The post box.
*   `postal_code` (_string_) The postal code.
*   `salutation` (_string_) The salutation.
*   `second_name` (_string_) The second name.
*   `state_code` (_string_) The state code.
*   `suffix` (_string_) The suffix.
*   `suite` (_string_) The suite.
*   `title` (_string_) The title.

_Example_

```
{
  "city": "Boston",
  "country_code": "US",
  "first_name": "John",
  "last_name": "Smith"
}
```

### bonus\_discount\_line\_item

Document representing a bonus discount line item

*   `bonus_products` (_array of product\_details\_link_) The list of links to the bonus products the customer can choose from.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, if applicable.
*   `id` (_string_) The ID of the line item.
*   `max_bonus_items` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotion_id` (_string_) The ID of the promotion which triggered the creation of the line item.

### coupon\_item

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256.
*   `coupon_item_id` (_string_) The coupon item id.
*   `status_code` (_string_) The status of the coupon item.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is 'applied' or 'no\_applicable\_promotion'.

_Example_

```
{
  "code": "the99coupon"
}
```

### customer\_info

Document representing information used to identify a customer.

*   `customer_id` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `customer_name` (_string_)
*   `customer_no` (_string_) The customer's number (id).  
    Maximum length: 100.
*   `email` (_string (email)_, required) The customer's email address.

_Example_

```
{
  "customer_no": "customer0012",
  "email": "valid@email.com"
}
```

### gift\_certificate\_item

A gift certificate item.

*   `amount` (_number (double)_, required) The certificate item amount.
*   `gift_certificate_item_id` (_string_) Id used to identify this item
*   `message` (_string_) The certificate's message.  
    Maximum length: 4000.
*   `recipient_email` (_string_, required) The recipient's email.  
    Minimum length: 1.
*   `recipient_name` (_string_) The recipient's name.
*   `sender_name` (_string_) The sender's name.
*   `shipment_id` (_string_) The shipment id.

_Example_

```
{
  "amount": 200,
  "message": "Present from your brother",
  "recipient_email": "peter@example.com",
  "recipient_name": "Peter Doe",
  "sender_name": "John Doe"
}
```

### grouped\_tax

Document representing a tax rate with it's summed up tax values

*   `tax_rate` (_number (double)_) The tax rate
*   `tax_value` (_number (double)_) The summed up tax total for the tax rate

### simple\_link

Document representing a link to another resource.

*   `link` (_string_) The link to the resource.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/orders/bc0KwiWexX0ZQaaadqRTwMZFga/notes"
}
```

### price\_adjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level. They can be created by the promotion engine (if the custom flag is set to false) or can be added by custom logic (if the custom flag is set to true). For custom price adjustments created by a user, the manual flag should be set to true; this is always the case for price adjustments created using OCAPI.

A price adjustment created by custom logic can either define a price that defines the absolute price reduction or define a discount from which a price reduction is calculated (amount, percentage, and fixed\_price discounts are supported). The applied\_discount property describes the discount applied to create the price-adjustment.

*   `applied_discount` (_discount_) A price adjustment that provides details of the discount that was applied. This is `null` for custom price adjustments created without discount details.
*   `coupon_code` (_string_) The coupon code that triggered the promotion, provided the price adjustment was created as the result of a promotion being triggered by a coupon.
*   `created_by` (_string_) The user who created the price adjustment.
*   `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.
*   `item_text` (_string_) The text describing the item in more detail.
*   `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.
*   `manual` (_boolean_)
    
    A flag indicating whether this price adjustment was created in a manual process.
    
    For custom price adjustments created using the shop API, this _always_ returns `true`. Using the scripting API, however, it is possible to set this to `true` or `false`, according to the use case.
    
*   `price` (_number (double)_) The adjustment price.
*   `price_adjustment_id` (_string_) The price adjustment id (uuid).
*   `promotion_id` (_string_) The id of the related promotion. Custom price adjustments can be assigned any promotion id so long it is not used by a price adjustment belonging to the same item and is not used by promotion defined in the promotion engine. If not specified, a promotion id is generated.
*   `promotion_link` (_string_) The URL addressing the related promotion.
*   `reason_code` (_string_) The reason why this price adjustment was made.  
    Allowed values: `BACKORDER`, `EVEN_EXCHANGE`, `PRICE_MATCH`. Value meanings: `BACKORDER`: Backorder; `EVEN_EXCHANGE`: Even Exchange; `PRICE_MATCH`: Price Match.

### order\_payment\_instrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.
*   `authorization_status` (_status_) The authorization status of the payment transaction.
*   `bank_routing_number` (_string_) The bank routing number.  
    Maximum length: 256.
*   `masked_gift_certificate_code` (_string_) The masked gift certificate code.
*   `payment_bank_account` (_payment\_bank\_account_) The payment bank account.
*   `payment_card` (_payment\_card_) The payment card.
*   `payment_instrument_id` (_string_) The payment instrument ID.
*   `payment_method_id` (_string_) The payment method id. Optional if a customer payment instrument id is specified.  
    Maximum length: 256.

_Example_

```
{
  "amount": 1,
  "payment_card": {
    "card_type": "Visa",
    "credit_card_expired": false,
    "expiration_month": 1,
    "expiration_year": 2021,
    "holder": "John Doe",
    "masked_number": "***********1111",
    "number_last_digits": "1111"
  },
  "payment_instrument_id": "ceDUYiWbN1IkkaaadkYHRkclwC",
  "payment_method_id": "CREDIT_CARD",
  "c_strValue": "any custom value"
}
```

### product\_item

Document representing a product item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_, required) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 5,
  "base_price": 16.49,
  "bonus_product_line_item": false,
  "item_id": "cdHBEiWbNV9ZcaaadhrCk35gtp",
  "item_text": "Simple Product",
  "price": 16.49,
  "price_after_item_discount": 16.49,
  "price_after_order_discount": 1,
  "product_id": "SimpleProduct",
  "product_name": "Simple Product",
  "quantity": 1,
  "tax": 5,
  "tax_basis": 16.49,
  "tax_class_id": null,
  "tax_rate": 0.05,
  "c_strValue": "Test"
}
```

### shipment

Document representing a shipment.

*   `adjusted_merchandize_total_tax` (_number (double)_)
    
    The products tax after discounts applying in purchase currency. Adjusted merchandize prices represent the sum of product prices before services such as shipping have been added, but after adjustment from promotions have been added.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `adjusted_shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container after shipping adjustments have been applied.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift.
*   `gift_message` (_string_) The gift message.
*   `merchandize_total_tax` (_number (double)_) The products total tax in purchase currency. Merchandize total prices represent the sum of product prices before services such as shipping or adjustment from promotions have been added.
*   `product_sub_total` (_number (double)_) The total price of all product items after all product discounts. Depending on taxation policy the returned price is net or gross.
*   `product_total` (_number (double)_) The total price of all product items after all product and order discounts. Depending on taxation policy the returned price is net or gross.
*   `shipment_id` (_string_) The order specific id to identify the shipment.
*   `shipment_no` (_string_)
    
    Returns the shipment number for this shipment.
    
    This number is automatically generated.
    
*   `shipment_total` (_number (double)_)
    
    The total price of the shipment, including products, shipping and tax.
    
    Note that order level adjustments are not considered.
    
*   `shipping_address` (_order\_address_) The shipping address.
*   `shipping_method` (_shipping\_method_) The shipping method.
*   `shipping_status` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`.
*   `shipping_total` (_number (double)_)
    
    The total shipping price of the shipment after all shipping discounts. Excludes tax if taxation policy is net. Includes tax if taxation policy is gross.
    
    ```
         net. Includes tax if taxation policy is gross.
    ```
    
*   `shipping_total_tax` (_number (double)_) The tax of all shipping line items of the line item container before shipping adjustments have been applied.
*   `tax_total` (_number (double)_)
    
    The total tax amount of the shipment.
    
    Note that order level adjustments are considered if Discount Taxation preference is set to "Tax Products and Shipping Only Based on Adjusted Price".
    
*   `tracking_number` (_string_) The tracking number of the shipment.

_Example_

```
{
  "gift": true,
  "gift_message": "Happy Birthday, Sværre",
  "id": "StandardShipping",
  "shipping_address": {
    "city": "Boston",
    "country_code": "US",
    "first_name": "John",
    "last_name": "Smith"
  },
  "shipping_method": {
    "id": "BaseShippingMethod"
  }
}
```

### shipping\_item

Document representing a shipping item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `shipment_id` (_string_) The identifier of the shipment to which this item belongs.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "adjusted_tax": 0,
  "base_price": 0.01,
  "item_id": "devgoiWbNVc92aaadhrSk35gtp",
  "item_text": "Shipping",
  "price": 0.01,
  "price_after_item_discount": 0.01,
  "shipment_id": "me",
  "tax": 0,
  "tax_basis": 0.01,
  "tax_class_id": "DefaultTaxClass",
  "tax_rate": 0.05
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### payment\_bank\_account\_request

Document representing a payment bank account request.

*   `drivers_license` (_string_) The drivers license.  
    Maximum length: 256.
*   `drivers_license_state_code` (_string_) The driver license state code.  
    Maximum length: 256.
*   `holder` (_string_) The holder of the bank account.  
    Maximum length: 256.
*   `number` (_string_) The payment bank account number.  
    Maximum length: 256.

### order\_payment\_card\_request

Document representing an order payment card request.

*   `card_type` (_string_) The payment card type (for example, 'Visa').  
    Maximum length: 256.
*   `credit_card_expired` (_boolean_) A flag indicating if the credit card is expired.
*   `credit_card_token` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.
*   `expiration_month` (_integer (int32)_) The month when the payment card expires.
*   `expiration_year` (_integer (int32)_) The year when the payment card expires.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256.
*   `issue_number` (_string_) The payment card issue number.  
    Maximum length: 256.
*   `number` (_string_) The payment card number.  
    Maximum length: 4000.
*   `security_code` (_string_) The security code for the payment card.  
    Maximum length: 4.
*   `valid_from_month` (_integer (int32)_) The payment card valid from month.  
    Minimum: 1. Maximum: 12.
*   `valid_from_year` (_integer (int32)_) The payment card valid from year.

### payment\_method

Document representing a payment method.

*   `cards` (_array of payment\_card\_spec_) The sorted array of payment cards (included only when the system payment method is CREDIT\_CARD).
*   `description` (_string_) The localized description of the payment method or card.
*   `id` (_string_, required) The id of the payment method or card.  
    Maximum length: 256.
*   `image` (_string_) The URL to the image that represents the payment method or card.
*   `name` (_string_) The localized name of the payment method or card.
*   `payment_processor_id` (_string_) The payment processor ID.

_Example_

```
{
  "cards": [
    {
      "card_type": "Visa",
      "checksum_verification_enabled": true,
      "id": "CREDIT_CARD.Visa",
      "name": "Visa",
      "number_lengths": [
        "13",
        "16"
      ],
      "number_prefixes": [
        "4"
      ],
      "security_code_length": 3
    },
    {
      "card_type": "Master",
      "checksum_verification_enabled": true,
      "id": "CREDIT_CARD.Master",
      "name": "Mastercard",
      "number_lengths": [
        "16"
      ],
      "number_prefixes": [
        "2221-2720",
        "51-55"
      ],
      "security_code_length": 3
    },
    {
      "card_type": "Amex",
      "checksum_verification_enabled": true,
      "id": "CREDIT_CARD.Amex",
      "name": "American Express",
      "number_lengths": [
        "15"
      ],
      "number_prefixes": [
        "34",
        "37"
      ],
      "security_code_length": 4
    }
  ],
  "id": "CREDIT_CARD",
  "name": "Credit Card",
  "c_somestring": "PaymentMethod String Value"
}
```

### product\_details\_link

Document representing a link to the resource for product details.

*   `link` (_string_) The target of the link.
*   `product_description` (_string_) The description of the product.
*   `product_id` (_string_, required) The id of the product.
*   `product_name` (_string_) The name of the product.
*   `title` (_string_) The link title.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/products/BlueJeansType1",
  "product_id": "BlueJeansType1",
  "product_name": "Product w/- Local Option",
  "title": "Product w/- Local Option"
}
```

### discount

Document representing a discount that was _either_ optionally applied when creating a custom price adjustment _or_ applied by the promotion engine. The property `type` is mandatory; the properties `amount` and `priceBookId` are used only in association with specific types. Some examples:

*   Type `percentage` with percentage `15.00` : a 15% discount was applied.
    
*   Type `amount` with amount `5.99` : a discount was applied to reduce the (unit) price by 5.99.
    
*   Type `fixed_price` with amount `49.99` : a discount was applied to reduce the price to 49.99.
    
*   Type `free` : a discount was applied to reduce the price to zero.
    
*   Type `price_book_price` with price\_book\_id `MyPriceBook` : a discount was applied to set the price to that defined in MyPriceBook.
    

*   `amount` (_number (double)_) The amount that is used with the amount and fixed price types.
*   `percentage` (_number (double)_) The percentage that is used with percentage types.
*   `price_book_id` (_string_) The price book id that is used with some types.
*   `type` (_string_, required) The type of discount.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`.

_Example_

```
{
  "amount": 15,
  "type": "amount"
}
```

### status

Document representing a status of an object.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_)
    
    The status.
    
    For more information on the status values see dw.system.Status.OK and dw.system.Status.ERROR.
    

### payment\_bank\_account

Document representing a payment bank account.

*   `drivers_license_last_digits` (_string_) The last 4 characters of the decrypted driver's license number of the bank account associated with this payment instrument.  
    Maximum length: 256.
*   `drivers_license_state_code` (_string_) The driver license state code.  
    Maximum length: 256.
*   `holder` (_string_) The holder of the bank account.  
    Maximum length: 256.
*   `masked_drivers_license` (_string_)
    
    The decrypted driver's license number of the bank account with all but the last 4 characters replaced with a '\*' character.
    
    ```
         with a '*' character.
    ```
    
      
    Maximum length: 256.
*   `masked_number` (_string_) The bank account masked number.  
    Maximum length: 256.
*   `number_last_digits` (_string_) The last digits of the bank account number.  
    Maximum length: 256.

_Example_

```
{
  "drivers_license_last_digits": "ense",
  "drivers_license_masked": "**************ense",
  "number_last_digits": "mber",
  "number_masked": "*************mber"
}
```

### payment\_card

Document representing a payment card.

*   `card_type` (_string_) The payment card type (for example, 'Visa').  
    Maximum length: 256.
*   `credit_card_expired` (_boolean_) A flag indicating if the credit card is expired.
*   `credit_card_token` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.
*   `expiration_month` (_integer (int32)_) The month when the payment card expires.
*   `expiration_year` (_integer (int32)_) The year when the payment card expires.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256.
*   `issue_number` (_string_) The payment card issue number.  
    Maximum length: 256.
*   `masked_number` (_string_) The masked credit card number.  
    Maximum length: 4000.
*   `number_last_digits` (_string_) The last digits of credit card number.  
    Maximum length: 4000.
*   `valid_from_month` (_integer (int32)_) The payment card valid from month.  
    Minimum: 1. Maximum: 12.
*   `valid_from_year` (_integer (int32)_) The payment card valid from year.

_Example_

```
{
  "card_type": "Visa",
  "credit_card_expired": false,
  "expiration_month": 2,
  "expiration_year": 2022,
  "holder": "John Smith",
  "masked_number": "***********ber2",
  "number_last_digits": "ber2"
}
```

### option\_item

Document representing an option item.

*   `adjusted_tax` (_number (double)_) The tax of the product item after adjustments applying.
*   `base_price` (_number (double)_) The base price for the line item, which is the price of the unit before applying adjustments, in the purchase currency. The base price may be net or gross of tax depending on the configured taxation policy.
*   `bonus_discount_line_item_id` (_string_) The id of the bonus discount line item this bonus product relates to.
*   `bonus_product_line_item` (_boolean_) A flag indicating whether the product item is a bonus.
*   `bundled_product_items` (_array of product\_item_) The array of bundled product items. Can be empty.
*   `gift` (_boolean_) Returns true if the item is a gift.
*   `gift_message` (_string_) The gift message.
*   `inventory_id` (_string_) The inventory list id associated with this item.  
    Maximum length: 256.
*   `item_id` (_string_) The item identifier. Use this to identify an item when updating the item quantity or creating a custom price adjustment for an item.
*   `item_text` (_string_) The text describing the item in more detail.
*   `option_id` (_string_, required) The id of the option.  
    Maximum length: 256.
*   `option_items` (_array of option\_item_) The array of option items. This array can be empty.
*   `option_value_id` (_string_, required) The id of the option value.  
    Maximum length: 256.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned.
*   `price_adjustments` (_array of price\_adjustment_) Array of price adjustments. Can be empty.
*   `price_after_item_discount` (_number (double)_) The price of the product line item after applying all product-level adjustments. For net pricing the adjusted net price is returned. For gross pricing, the adjusted gross price is returned.
*   `price_after_order_discount` (_number (double)_) The price of this product line item after considering all dependent price adjustments and prorating all order-level price adjustments. For net pricing the net price is returned. For gross pricing, the gross price is returned.
*   `product_id` (_string_) The id (SKU) of the product.  
    Maximum length: 100.
*   `product_list_item` (_product\_list\_item\_reference_)
*   `product_name` (_string_) The name of the product.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0.
*   `shipment_id` (_string_) The id of the shipment which includes the product item.
*   `shipping_item_id` (_string_) The reference to the related shipping item if it exists. This is the case if for example when a surcharge is defined for individual products using a particular a shipping method.
*   `tax` (_number (double)_) The tax of the product item before adjustments applying.
*   `tax_basis` (_number (double)_)
    
    The price used to calculate the tax for this product item.
    
    ```
         null if tax has not been set for this product item yet
    ```
    
*   `tax_class_id` (_string_)
    
    The tax class ID for the product item or null if no tax class ID is associated with the product item.
    
    if no tax class ID is associated with the product item
    
*   `tax_rate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item.

_Example_

```
{
  "option_id": "Warranty",
  "option_value_id": "oneYear"
}
```

### product\_list\_item\_reference

*   `id` (_string_, required) The id of the product list item.
*   `priority` (_integer (int32)_)
*   `product_details_link` (_product\_details\_link_)
*   `product_list` (_product\_list\_link_) The link of the product list, the item is assigned
*   `public` (_boolean_)
*   `purchased_quantity` (_number (double)_)
*   `quantity` (_number (double)_)  
    Minimum: 0.
*   `type` (_string_)  
    Allowed values: `product`, `gift_certificate`.

### shipping\_method

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.
*   `external_shipping_method` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method id.  
    Maximum length: 256.
*   `name` (_string_) The localized name of the shipping method.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs and product level fix and surcharge costs.
*   `shipping_promotions` (_array of shipping\_promotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

_Example_

```
{
  "id": "BaseShippingMethod"
}
```

### payment\_card\_spec

Document representing the specification for a payment card.

The information in the specification can be used to verify data entered by a customer before sending to the payment authorization. The configuration can be made in the payment methods section in Business Manager.

*   `card_type` (_string_) The type of the payment card.
*   `checksum_verification_enabled` (_boolean_)
    
    A flag indicating whether the card number is verified using the Luhn checksum algorithm.
    
    ```
         <code>false</code>
    ```
    
*   `description` (_string_) The localized description of the payment card.
*   `image` (_string_) The URL to the image that represents the payment card.
*   `name` (_string_) The localized name of the payment card.
*   `number_lengths` (_array of string_) The sorted list of number lengths (individual lengths as well as length ranges).
*   `number_prefixes` (_array of string_) The sorted list of number prefixes (individual prefixes as well as prefix ranges).
*   `security_code_length` (_integer (int32)_) The length of the security code for this card.

_Example_

```
{
  "card_type": "Visa",
  "checksum_verification_enabled": true,
  "id": "CREDIT_CARD.Visa",
  "name": "Visa",
  "number_lengths": [
    "13",
    "16"
  ],
  "number_prefixes": [
    "4"
  ],
  "security_code_length": 3
}
```

### product\_list\_link

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `link` (_string_) The target of the link.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`.

### shipping\_promotion

Document representing a shipping promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotion_name` (_string_) The localized promotion name.

<!-- document id=96b8b00f242b97e2e2a9b378ec49eab5303cd8f03e200b0e13f9ae4eecc9ce9d url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-price-adjustment-limits.md -->

Shop Price Adjustment Limits (deprecated)

# Shop Price Adjustment Limits (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get price adjustment limits

`GET /price_adjustment_limits`

Operation ID: `Get price adjustment limits`. Tags: price\_adjustment\_limits. Security: customers\_auth; oauth2\_application; client\_id.

Returns a list of price adjustment limits for the authenticated user and the site defined in the URL.

At least one of the following functional permissions must be assigned to the user to be able to access it: Adjust\_Item\_Price or Adjust\_Shipping\_Price or Adjust\_Order\_Price.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `price_adjustment_limits`.
    

## Schemas

### price\_adjustment\_limits

Document representing a list of PriceAdjustmentLimit items. It returns all the price adjustment limits for a particular user across various Access Roles.

*   `limits` (_array of price\_adjustment\_limit_) The list of price adjustment limits applicable for a user across all roles.

_Example_

```
{
  "limits": [
    {
      "percent": 20,
      "type": "item"
    },
    {
      "percent": 25,
      "type": "order"
    },
    {
      "amount": 60,
      "currency": "USD",
      "percent": 25,
      "type": "order"
    }
  ]
}
```

### price\_adjustment\_limit

Document representing a price adjustment limit.

A price adjustment limit specifies the amount of manual adjustment that can be applied by a user at the specified level.

*   `amount` (_number (double)_) The value for the currency or null if no currency value is specified.
*   `currency` (_string_)
    
    Returns the currency of the Price Adjustment Limit or null if not applicable.
    
    Will be null if this is a percent limit only.
    
    Price adjustment limits can be given up to a fixed amount (unit=a currency unit).
    
*   `percent` (_number (double)_)
    
    Returns percentage value of the Price Adjustment Limit or null if not applicable.
    
    Will be null if this is a currency limit only.
    
*   `type` (_string_) The Price Adjustment Limit type - ITEM, SHIPPING or ORDER. It identifies the level at which the Price Adjustment is applicable.  
    Allowed values: `item`, `shipping`, `order`.

_Example_

```
{
  "percent": 20,
  "type": "item"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=4ec6b3c0c4308fcb575ccd8a5dd5a5c512636740a43af255a0c9c33e94b83af3 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-product-lists.md -->

Shop Product Lists (deprecated)

# Shop Product Lists (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get list of product lists

`GET /product_lists`

Operation ID: `Get list of product lists`. Tags: product\_lists. Security: client\_id; customers\_auth.

Retrieves all public product lists as defined by the given search term (email, first name, last name).

This endpoint may return the following faults:

*   400 - ProductListSearchTermException - Indicates that the anonymous customer did not provide a proper search term.

#### Parameters

*   `email` (query, string) The email address of the customer, the product lists belong to.
*   `firstname` (query, string) The first name of the customer, the product lists belong to.
*   `lastname` (query, string) The last name of the customer, the product lists belong to.

#### Responses

*   **400** `ProductListSearchTermException` - Indicates that the anonymous customer did not provide a proper search term.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `public_product_list_result`.
    

### GET Get product list

`GET /product_lists/{list_id}`

Operation ID: `Get product list`. Tags: product\_lists. Security: client\_id; customers\_auth.

Retrieves a public product list by id.

This endpoint may return the following faults:

*   404 - ProductListNotFoundException - Indicates that this list doesn't exist.

#### Parameters

*   `list_id` (path, string, required) The id of the list.  
    Minimum length: 1. Maximum length: 28.
*   `expand` (query, array of string) The possible expansions - items, product, images, availability. The product information is included in the product list items that is why the product expansion has to be done together with items expansion. For images and availability both product and items have to be expanded as well.

#### Responses

*   **404** `ProductListNotFoundException` - Indicates that this list doesn't exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `public_product_list`.
    

### GET Get product list items

`GET /product_lists/{list_id}/items`

Operation ID: `Get product list items`. Tags: product\_lists. Security: client\_id; customers\_auth.

Retrieves the items of a public product list.

This endpoint may return the following faults:

*   404 - ProductListNotFoundException - Indicates that this list doesn't exist.

#### Parameters

*   `list_id` (path, string, required) The id of the list.  
    Minimum length: 1. Maximum length: 28.
*   `expand` (query, array of string) The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.

#### Responses

*   **404** `ProductListNotFoundException` - Indicates that this list doesn't exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `public_product_list_item_result`.
    

### GET Get product list item

`GET /product_lists/{list_id}/items/{item_id}`

Operation ID: `Get product list item`. Tags: product\_lists. Security: client\_id; customers\_auth.

Retrieves an item from a public product list.

This endpoint may return the following faults:

*   404 - ProductListItemNotFoundException - Indicates that this product list item doesn't exist.
*   404 - ProductListNotFoundException - Indicates that this list doesn't exist.

#### Parameters

*   `list_id` (path, string, required) The id of the list.  
    Minimum length: 1. Maximum length: 28.
*   `item_id` (path, string, required) The id of the item.  
    Minimum length: 1.
*   `expand` (query, array of string) The possible expansions - product, images, availability. For images and availability the product has to be expanded as well.

#### Responses

*   **404** `ProductListItemNotFoundException` - Indicates that this product list item doesn't exist. or `ProductListNotFoundException` - Indicates that this list doesn't exist.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `public_product_list_item`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### public\_product\_list\_result

Result document containing an array of public product list links.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of public\_product\_list\_link_) The array of product list link documents.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "href": "https://example.com/dw/shop/{version}/product_lists/cd2Id9aaabTQYaaadj9vRpVGwg",
      "name": "WAPI-Wedding",
      "public": false,
      "title": "Wedding",
      "type": "gift_registry"
    },
    {
      "href": "https://example.com/dw/shop/{version}/product_lists/ghjMV9aaab9d2aaafjycppVGwe",
      "public": false,
      "title": "Wish List",
      "type": "wish_list"
    }
  ],
  "total": 2
}
```

### public\_product\_list

*   `co_registrant` (_product\_list\_registrant_) The coRegistrant of this product list.
*   `creation_date` (_string (date-time)_) Returns the value of attribute 'creationDate'.
*   `description` (_string_) The description of this product list.
*   `event` (_product\_list\_event_) The event of this product list.
*   `id` (_string_) The id of this product list.  
    Minimum length: 1.
*   `items_link` (_product\_simple\_link_) The resource link to the items of this product list.
*   `last_modified` (_string (date-time)_) Returns the value of attribute 'lastModified'.
*   `name` (_string_) The name of this product list.
*   `product_list_items` (_array of public\_product\_list\_item_) The product list items
*   `product_list_shipping_address` (_product\_list\_shipping\_address_) The abbreviated shipping address of this product list representing what anonymous user can see.
*   `public` (_boolean_) Indicates whether the owner made this product list available for access by other customers.
*   `registrant` (_product\_list\_registrant_) The registrant of this product list.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`.

_Example_

```
{
  "co_registrant": {
    "email": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "role": "Bride"
  },
  "current_shipping_address_link": {
    "link": "https://example.com/dw/shop/{version}/customers/f93jdf93jdfd/addresses/me",
    "title": "me, John Doe, Woburn"
  },
  "event": {
    "city": "Washington",
    "country": "US",
    "date": "2015-07-30T00:00Z",
    "state": "DC",
    "type": "Wedding"
  },
  "id": "bcqg6iWbw4XEYaaadjixFLTWP0",
  "items_link": {
    "link": "https://example.com/dw/shop/{version}/product_lists/bcqg6iWbw4XEYaaadjixFLTWP0/items",
    "title": "2 items"
  },
  "name": "DC-Doe-Wedding",
  "post_event_shipping_address_link": {
    "link": "https://example.com/dw/shop/{version}/customers/f93jdf93jdfd/addresses/jane",
    "title": "jane, Jane Doe, Springfield"
  },
  "product_list_items": [
    {
      "id": "50f50f608aa9ff2fbf9272ed7e",
      "priority": 2,
      "product": {
        "id": "BlueJeans1",
        "inventories": [
          {
            "ats": 100,
            "backorderable": false,
            "id": "BlueJeans1Inventory",
            "orderable": true,
            "preorderable": false,
            "stock_level": 100
          }
        ],
        "min_order_quantity": 1,
        "step_quantity": 1
      },
      "product_details_link": {
        "link": "https://example.com/dw/shop/{version}/products/BlueJeans1?expand=items%2Cproduct%2Cavailability%2Cimages",
        "product_id": "BlueJeans1",
        "product_name": "Product w/- Local Option",
        "title": "Product w/- Local Option"
      },
      "type": "product"
    },
    {
      "id": "2ab5aa2a2e050f1b7fd9463af1",
      "priority": 3,
      "product": {
        "id": "BlackJeans1",
        "inventories": [
          {
            "ats": 999999,
            "backorderable": false,
            "id": "BlackJeans1Inventory",
            "orderable": true,
            "preorderable": false,
            "stock_level": 999999
          }
        ],
        "min_order_quantity": 1,
        "step_quantity": 1
      },
      "product_details_link": {
        "link": "https://example.com/dw/shop/{version}/products/BlackJeans1?expand=items%2Cproduct%2Cavailability%2Cimages",
        "product_id": "BlackJeans1",
        "product_name": "Simple Web API Product",
        "title": "Black Jeans"
      },
      "type": "product"
    },
    {
      "id": "09c9df175e247c0d75d76f443e",
      "priority": 6,
      "product": {
        "id": "RedDress1",
        "image_groups": [
          {
            "images": [
              {
                "alt": "ALT master detail",
                "link": "https://example.com/foo/bar/master_detail.jpg",
                "title": "TITLE master detail"
              }
            ],
            "view_type": "detail"
          },
          {
            "images": [
              {
                "alt": "ALT main swatch",
                "link": "https://example.com/foo/bar/main_swatch.jpg",
                "title": "TITLE main swatch"
              }
            ],
            "view_type": "swatch"
          },
          {
            "images": [
              {
                "alt": "ALT master thumbnail",
                "link": "https://example.com/foo/bar/master_thumbnail.jpg",
                "title": "TITLE master thumbnail"
              }
            ],
            "view_type": "thumbnail"
          }
        ],
        "inventories": [
          {
            "ats": 0,
            "backorderable": false,
            "id": "RedDress1Inventory",
            "orderable": false,
            "preorderable": false,
            "stock_level": 0
          }
        ],
        "min_order_quantity": 1,
        "step_quantity": 1
      },
      "product_details_link": {
        "link": "https://example.com/dw/shop/{version}/products/RedDress2?expand=items%2Cproduct%2Cavailability%2Cimages",
        "product_id": "RedDress2",
        "product_name": "Red Dress 2",
        "title": "Red Dress"
      },
      "type": "product"
    }
  ],
  "public": true,
  "registrant": {
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "role": "Groom"
  },
  "shipping_address_link": {
    "link": "https://example.com/dw/shop/{version}/customers/f93jdf93jdfd/addresses/me",
    "title": "me, John Doe, Woburn"
  },
  "type": "gift_registry"
}
```

### public\_product\_list\_item\_result

Result document containing an array of product list items.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of public\_product\_list\_item_) The array of product list item documents.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "id": "cdPIB9aaabYFEaaadjOdBoMrMt",
      "position": -1,
      "priority": 2,
      "product_details_link": {
        "link": "https://example.com/dw/shop/{version}/products/008884303989?locale=en-US",
        "product_id": "008884303989",
        "product_name": "Platinum Blue Stripes Easy Care Fitted Shirt",
        "title": "Platinum Blue Stripes Easy Care Fitted Shirt"
      },
      "public": true,
      "purchased_quantity": 0,
      "quantity": 10,
      "type": "product"
    },
    {
      "id": "cdH9N9aaabYFIaaadjOdBoMrMt",
      "position": -1,
      "priority": 2,
      "product": {
        "id": "BlueShirt",
        "image_groups": [
          {
            "images": [
              {
                "alt": "ALT master detail",
                "link": "https://example.com/foo/bar/master_detail.jpg",
                "title": "TITLE master detail"
              }
            ],
            "view_type": "detail"
          },
          {
            "images": [
              {
                "alt": "ALT main swatch",
                "link": "https://example.com/foo/bar/main_swatch.jpg",
                "title": "TITLE main swatch"
              }
            ],
            "view_type": "swatch"
          },
          {
            "images": [
              {
                "alt": "ALT master thumbnail",
                "link": "https://example.com/foo/bar/master_thumbnail.jpg",
                "title": "TITLE master thumbnail"
              }
            ],
            "view_type": "thumbnail"
          }
        ],
        "inventories": [
          {
            "ats": 0,
            "backorderable": false,
            "id": "BlueShirtInventory",
            "orderable": false,
            "preorderable": false,
            "stock_level": 0
          }
        ],
        "product_details_link": {
          "link": "https://example.com/dw/shop/{version}/products/008885535488?locale=en-US",
          "product_id": "008885535488",
          "product_name": "Must Have Washable No-Iron Georgette Blouse",
          "title": "Must Have Washable No-Iron Georgette Blouse"
        },
        "public": false,
        "purchased_quantity": 0,
        "quantity": 1,
        "type": "product"
      },
      "total": 2
    }
  ]
}
```

### public\_product\_list\_item

Document representing a product list item.

*   `id` (_string_) The id of this product list item.
*   `priority` (_integer (int32)_) The priority of the item.
*   `product` (_product_) The product item
*   `product_details_link` (_product\_simple\_link_) A link to the product.
*   `type` (_string_) The type of the item.  
    Allowed values: `product`, `gift_certificate`.

_Example_

```
{
  "id": "50f50f608aa9ff2fbf9272ed7e",
  "priority": 2,
  "product": {
    "id": "BlueJeans",
    "image_groups": [
      {
        "images": [
          {
            "alt": "ALT master detail",
            "link": "https://example.com/foo/bar/master_detail.jpg",
            "title": "TITLE master detail"
          }
        ],
        "view_type": "detail"
      },
      {
        "images": [
          {
            "alt": "ALT main swatch",
            "link": "https://example.com/foo/bar/main_swatch.jpg",
            "title": "TITLE main swatch"
          }
        ],
        "view_type": "swatch"
      },
      {
        "images": [
          {
            "alt": "ALT master thumbnail",
            "link": "https://example.com/foo/bar/master_thumbnail.jpg",
            "title": "TITLE master thumbnail"
          }
        ],
        "view_type": "thumbnail"
      }
    ],
    "inventories": [
      {
        "ats": 0,
        "backorderable": false,
        "id": "BlueJeansInventory",
        "orderable": false,
        "preorderable": false,
        "stock_level": 0
      }
    ],
    "min_order_quantity": 1,
    "step_quantity": 1
  },
  "product_details_link": {
    "link": "https://example.com/dw/shop/{version}/products/BlueJeansType1",
    "product_id": "BlueJeansType1",
    "product_name": "Product w/- Local Option",
    "title": "Product w/- Local Option"
  },
  "quantity": 99,
  "type": "product"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### public\_product\_list\_link

Document representing a link to a public product list.

*   `description` (_string_) The description of this product list.
*   `id` (_string_) The ID of this product list.
*   `link` (_string_) The target of the link.
*   `name` (_string_) The name of this product list.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`.

### product\_list\_registrant

Document representing a product list registrant.

A ProductListRegistrant is typically associated with an event related product list such as a gift registry. It holds information about a person associated with the event such as a bride or groom.

*   `first_name` (_string_) The first name of the registrant.
*   `last_name` (_string_) The last name of the registrant.
*   `role` (_string_) The role of the registrant.

_Example_

```
{
  "email": "johndoe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "role": "Groom"
}
```

### product\_list\_event

Document representing a product list event.

*   `city` (_string_) The city where the event takes place.
*   `country` (_string_) The country where the event takes place.
*   `date` (_string (date-time)_) The date when the event takes place.
*   `state` (_string_) The federal state where the event takes place.
*   `type` (_string_) Type of the event to celebrate.

_Example_

```
{
  "city": "Washington",
  "country": "US",
  "date": "2015-07-30T00:00Z",
  "state": "DC",
  "type": "Wedding"
}
```

### product\_simple\_link

Document representing a link to a product.

*   `link` (_string_) The target of the link.
*   `title` (_string_) The link title.

_Example_

```
{
  "link": "https://example.com/dw/shop/{version}/products/008884303989",
  "title": "Platinum Blue Stripes Easy Care Fitted Shirt"
}
```

### product\_list\_shipping\_address

Document representing a product list shipping address.

*   `address_id` (_string_, required) The id of this address.  
    Minimum length: 1.
*   `city` (_string_) The city of this address.
*   `first_name` (_string_) The first name of this address.
*   `last_name` (_string_) The last name of this address.

### product

Document representing a product.

*   `brand` (_string_) The product's brand.
*   `bundled_products` (_array of bundled\_product_) The array of all bundled products of this product.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `ean` (_string_) The European Article Number.
*   `fetch_date` (_integer (int32)_)
*   `id` (_string_, required) The id (SKU) of the product.  
    Minimum length: 1. Maximum length: 100.
*   `image_groups` (_array of image\_group_) The array of product image groups.
*   `inventories` (_array of inventory_) The array of product inventories explicitly requested via 'inventory\_ids' query parameter. This property is only returned in context of the 'availability' expansion.
*   `inventory` (_inventory_) The site default inventory information. This property is only returned in context of the 'availability' expansion.
*   `long_description` (_string (html)_) The localized product long description.
*   `manufacturer_name` (_string_) The products manufacturer name.
*   `manufacturer_sku` (_string_) The products manufacturer sku.
*   `master` (_master_) The master product information. Only for types master, variation group and variant.
*   `min_order_quantity` (_number (double)_) The minimum order quantity for this product.
*   `name` (_string_) The localized product name.
*   `options` (_array of option_) The array of product options. This array can be empty. Only for type option.
*   `page_description` (_string_) The localized products page description.
*   `page_keywords` (_string_) The localized products page description.
*   `page_title` (_string_) The localized products page title.
*   `price` (_number (double)_) The sales price of the product. In case of complex products like master or set this is the minimum price of related child products.
*   `price_max` (_number (double)_) The maximum sales of related child products in case of complex products like master or set.
*   `price_per_unit` (_number (double)_) The sales price per unit of the product. In case of complex products like master or set this is the minimum price per unit of related child products.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of related child products in case of complex products like master or set.
*   `prices` (_object_) The prices map with price book ids and their values.
    
    Additional properties: `number (double)`.
    
*   `primary_category_id` (_string_) The id of the products primary category.
*   `product_links` (_array of product\_link_) The array of source and target products links information.
*   `product_promotions` (_array of product\_promotion_) An array of active customer product promotions for this product, sorted by promotion priority using SORT\_BY\_EXCLUSIVITY ordering (exclusivity -> rank -> promotion class -> discount type -> best discount -> ID). This array can be empty. Coupon promotions are not returned in this array. See PromotionPlan.SORT\_BY\_EXCLUSIVITY for more details.
*   `recommendations` (_array of recommendation_) Returns a list of recommendations.
*   `set_products` (_array of product_) The array of set products of this product.
*   `short_description` (_string (html)_) The localized product short description.
*   `step_quantity` (_number (double)_) The steps in which the order amount of the product can be increased.
*   `type` (_product\_type_) The product type information. Can be one or multiple of the following values: item,master,variation\_group,variant,bundle,set.
*   `unit` (_string_) The sales unit of the product.
*   `unit_measure` (_string_) The unitMeasure of the product.
*   `unit_quantity` (_number (double)_)
*   `upc` (_string_) The Universal Product Code.
*   `valid_from` (_string (date-time)_) The time when product is valid from.
*   `valid_to` (_string (date-time)_) The time when product is valid to.
*   `variants` (_array of variant_) The array of actual variants. This array can be empty. Only for types master, variation group and variant.
*   `variation_attributes` (_array of variation\_attribute_) Sorted array of variation attributes information. This array can be empty. Only for types master, variation group and variant.
*   `variation_groups` (_array of variation\_group_) The array of actual variation groups. This array can be empty. Only for types master, variation group and variant.
*   `variation_values` (_object_)
    
    The actual variation attribute id - value pairs. Only for type variant and variation group.
    
    ```
         Only for type variant and variation group.
    ```
    
    Additional properties: `string`.
    

_Example_

```
{
  "_type": "product",
  "_v": "24.5",
  "brand": "Creative",
  "id": "creative-zen-v",
  "min_order_quantity": 1,
  "name": "Creative ZEN V Digital Media Player",
  "page_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
  "page_keywords": "Creative",
  "page_title": "Creative ZEN V Digital Media Player",
  "primary_category_id": "electronics-digital-media-players",
  "short_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
  "step_quantity": 1,
  "type": {
    "item": true
  },
  "c_mediaFormat": [
    "0010",
    "0020",
    "0030",
    "0040"
  ],
  "c_memorySize": "1GB",
  "c_tabDescription": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player."
}
```

### bundled\_product

Document representing a bundled product within a product bundle.

*   `id` (_string_)
*   `product` (_product_) The product being bundled.
*   `quantity` (_number (double)_) For the product being bundled, the quantity added to the bundle.

_Example_

```
{
  "product": {
    "brand": "Sony",
    "id": "sony-ps3-console",
    "name": "Sony Playstation 3 Game Console",
    "page_description": "ncludes PLAYSTATION 3 80GB system, DUALSHOCK 3 wireless controller, free PLAYSTATION Network membership, internet ready Wi-Fi, and 80GB of hard disk storage for all your games, music, videos, and photos. Every PS3 comes with a built-in Blu-ray player to give you the best high-definition viewing experience and pristine picture quality. Plus, the PS3 can play your entire catalog of CDs and DVDs.",
    "page_keywords": "Sony",
    "page_title": "Sony Playstation 3 Game Console",
    "primary_category_id": "electronics-game-consoles",
    "short_description": "ncludes PLAYSTATION 3 80GB system, DUALSHOCK 3 wireless controller, free PLAYSTATION Network membership, internet ready Wi-Fi, and 80GB of hard disk storage for all your games, music, videos, and photos. Every PS3 comes with a built-in Blu-ray player to give you the best high-definition viewing experience and pristine picture quality. Plus, the PS3 can play your entire catalog of CDs and DVDs.",
    "type": {
      "item": true,
      "option": true
    }
  },
  "quantity": 1
}
```

### image\_group

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of image_) The images of the image group.
*   `variation_attributes` (_array of variation\_attribute_) Returns a list of variation attributes applying to this image group.
*   `view_type` (_string_) The image view type.

_Example_

```
{
  "images": [
    {
      "alt": "ALT master detail",
      "link": "https://example.com/foo/bar/master_detail.jpg",
      "title": "TITLE master detail"
    }
  ],
  "view_type": "detail"
}
```

### inventory

Document representing inventory information of the current product for a particular inventory list.

*   `ats` (_number (double)_) The ats of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.ats.max\_threshold'.
*   `backorderable` (_boolean_) A flag indicating whether the product is back orderable.
*   `id` (_string_, required) The inventory id.
*   `in_stock_date` (_string (date-time)_) A flag indicating the date when the product will be in stock.
*   `orderable` (_boolean_) A flag indicating whether at least one of products is available to sell.
*   `preorderable` (_boolean_) A flag indicating whether the product is pre orderable.
*   `stock_level` (_number (double)_) The stock level of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.stock\_level.max\_threshold'.

_Example_

```
{
  "ats": 0,
  "backorderable": false,
  "id": "BlueJeansInventory",
  "orderable": false,
  "preorderable": false,
  "stock_level": 0
}
```

### master

Document representing a variation master.

*   `link` (_string_) The URL addressing the master product.
*   `master_id` (_string_, required) The id (SKU) of the master product.  
    Minimum length: 1. Maximum length: 100.
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.
*   `price` (_number (double)_) The minimum sales price of the related variants.
*   `price_max` (_number (double)_) The maximum sales of related variants.
*   `price_per_unit` (_number (double)_) The minimum sales price per unit of the related variants.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of the related variants.
*   `prices` (_object_)
    
    Additional properties: `number (double)`.
    

### option

Document representing a product option.

*   `description` (_string_) The localized description of the option.
*   `id` (_string_, required) The id of the option.  
    Minimum length: 1. Maximum length: 100.
*   `image` (_string_) The URL to the option image.
*   `name` (_string_) The localized name of the option.
*   `values` (_array of option\_value_) The array of option values. This array can be empty.

### product\_link

Document representing a link between two products. It contains the id of the source and target products, the type of product link, and URLs to retrieve product data.

*   `source_product_id` (_string_) The semantic id of the product from which this product link is coming.
*   `source_product_link` (_string_) The URL addressing the product from which this product link is coming.
*   `target_product_id` (_string_) The semantic id of the product to which this product link is pointing.
*   `target_product_link` (_string_) The URL addressing the product to which this product link is pointing.
*   `type` (_string_) The type of this product link.  
    Allowed values: `cross_sell`, `replacement`, `up_sell`, `accessory`, `newer_version`, `alt_orderunit`, `spare_part`, `other`.

_Example_

```
{
  "source_product_id": "namco-we-ski-wii",
  "source_product_link": "http://example.com/dw/shop/{version}/products/namco-we-ski-wii?pretty_print=true",
  "target_product_id": "midway-cruisn-wii",
  "target_product_link": "http://example.com/dw/shop/{version}/products/midway-cruisn-wii?pretty_print=true",
  "type": "cross_sell"
}
```

### product\_promotion

Document representing a product promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotional_price` (_number (double)_) The promotional price for this product.

_Example_

```
{
  "callout_msg": "Save 15% Off iPod Nano",
  "link": "http://example.com/dw/shop/{version}/promotions/15off-nano",
  "promotion_id": "15off-nano"
}
```

### recommendation

Document representing a product recommendation.

*   `callout_msg` (_string (html)_) The localized callout message of the recommendation.
*   `image` (_image_) The image of the recommendation.
*   `long_description` (_string (html)_) The localized long description of the recommendation.
*   `name` (_string_) The localized name of the recommendation.
*   `recommendation_type` (_recommendation\_type_) The recommendation type of the recommendation.
*   `recommended_item_id` (_string_) The recommended item id of the recommendation.
*   `recommended_item_link` (_string_) The recommended item link of the recommendation.
*   `short_description` (_string (html)_) The localized short description of the recommendation.

### product\_type

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.
*   `master` (_boolean_) A flag indicating whether the product is a master.
*   `option` (_boolean_) A flag indicating whether the product is an option.
*   `set` (_boolean_) A flag indicating whether the product is a set.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.
*   `variation_group` (_boolean_) A flag indicating whether the product is a variation group.

_Example_

```
{
  "item": true
}
```

### variant

Document representing a product variation.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.
*   `price` (_number (double)_) The sales price of the variant.
*   `price_per_unit` (_number (double)_) The sales price of the variant.
*   `product_id` (_string_, required) The id (SKU) of the variant.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "http://example.com/dw/shop/{version}/products/apple-ipod-touch-8gb?pretty_print=true",
  "product_id": "apple-ipod-touch-8gb",
  "variation_values": {
    "memorySize": "8 GB"
  }
}
```

### variation\_attribute

Document representing a variation attribute.

*   `id` (_string_, required) The id of the variation attribute.  
    Minimum length: 1.
*   `name` (_string_) The localized display name of the variation attribute.
*   `values` (_array of variation\_attribute\_value_) The sorted array of variation values. This array can be empty.

_Example_

```
{
  "id": "memorySize",
  "name": "Memory Size",
  "values": [
    {
      "name": "1 GB",
      "value": "1 GB"
    },
    {
      "name": "2 GB",
      "value": "2 GB"
    },
    {
      "name": "8 GB",
      "value": "8 GB"
    },
    {
      "name": "16 GB",
      "value": "16 GB"
    },
    {
      "name": "32 GB",
      "value": "32 GB"
    },
    {
      "name": "120 GB",
      "value": "120 GB"
    }
  ]
}
```

### variation\_group

Document representing a variation group.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.
*   `price` (_number (double)_) The sales price of the variation group.
*   `price_per_unit` (_number (double)_) The sales price per unit of the variation group.
*   `product_id` (_string_) The id (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

### image

Document representing a product image.

*   `alt` (_string_) The localized alternative text of the image.
*   `dis_base_link` (_string_) Base URL for dynamic image service address. This is only shown, if the image is stored on the server and DIS is enabled.
*   `link` (_string_, required) The URL of the actual image.  
    Minimum length: 1.
*   `title` (_string_) The localized title of the image.

_Example_

```
{
  "alt": "ALT main swatch",
  "link": "https://example.com/foo/bar/main_swatch.jpg",
  "title": "TITLE main swatch"
}
```

### option\_value

Document representing an option value.

*   `default` (_boolean_) A flag indicating whether this option value is the default one.
*   `id` (_string_, required) The id of the option value.  
    Minimum length: 1. Maximum length: 100.
*   `name` (_string_) The localized name of the option value.
*   `price` (_number (double)_) The effective price of this option value.

### recommendation\_type

Document representing a recommendation type.

*   `display_value` (_string_) The localized display value of the recommendation type.
*   `value` (_integer (int32)_) The value of the recommendation type.

_Example_

```
{
  "display_value": "Cross-Sell",
  "value": 1
}
```

### variation\_attribute\_value

Document representing a variation attribute value.

*   `description` (_string_) The localized description of the variation value.
*   `image` (_image_) The first product image for the configured viewtype and this variation value.
*   `image_swatch` (_image_) The first product image for the configured viewtype and this variation value. (typically the swatch image)
*   `name` (_string_) The localized display name of the variation value.
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1.

<!-- document id=97ec7a123976069b44faaed77a9f0f7a143a492a850db95c43992fa4309991c5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-product-search.md -->

Shop Product Search (deprecated)

# Shop Product Search (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Search Products

`GET /product_search`

Operation ID: `Search Products`. Tags: product\_search. Security: client\_id; customers\_auth.

Provides keyword and refinement search functionality for products. Only returns the product id, link and name in the product search hit. Other search hit properties can be added by using the expand parameter. The search result contains only products that are online and assigned to site catalog.

This resource does not return detailed information about variation products. If a variation product matches the query, basic information for the parent master product is returned. Use the products resource to retrieve more details about a variation product.

This endpoint may return the following faults:

*   400 - InvalidExpandParameterException - Thrown in case a specified expand parameter value is unknown.
*   400 - MalformedPriceRefinementException - Thrown if a price refinement parameter is malformed.

#### Parameters

*   `q` (query, string) The query phrase to search for.  
    Maximum length: 50.
*   `refine` (query, array of string)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute id and value(s) are separated by '='. Multiple values are supported by a sub-set of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=price=(100..500) Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementColor=red|green|blue. The following system refinement attribute ids are supported:
    
    *   cgid: Allows to refine per single category id. Multiple category ids are not supported.
        
    *   price: Allows to refine per single price range. Multiple price ranges are not supported.
        
    *   pmid: Allows to refine per promotion id(s).
        
    *   htype: Allow to refine by including only the provided hit types. Accepted types are 'product', 'master', 'set', 'bundle', 'slicing\_group' (deprecated), 'variation\_group'.
        
    *   orderable\_only: Unavailable products will be excluded from the search results if true is set. Multiple refinement values are not supported.
        
*   `sort` (query, string) The id of the sorting option to sort the search hits.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.
*   `expand` (query, array of string) The expand parameter. A comma separated list with the allowed values ( _availability, images, prices, represented\_products, variations_ )
*   `currency` (query, string) The currency mnemonic specified for price. This parameter is effective only if specified expand parameter value contains prices.
*   `locale` (query, string) The locale context.

#### Responses

*   **400** `InvalidExpandParameterException` - Thrown in case a specified expand parameter value is unknown. or `MalformedPriceRefinementException` - Thrown if a price refinement parameter is malformed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_search_result`.
    

### GET Search Products - Availability

`GET /product_search/availability`

Operation ID: `Search Products - Availability`. Tags: product\_search. Security: client\_id; customers\_auth.

Provides keyword and refinement search functionality for products. Only returns the product id, link, name and availability information in the product search hit.

This resource does not return detailed information about variation products. If a variation product matches the query, basic information for the parent master product is returned. Use the products resource to retrieve more details about a variation product.

This endpoint may return the following faults:

*   400 - MalformedPriceRefinementException - Thrown if a price refinement parameter is malformed.

#### Parameters

*   `q` (query, string) The query phrase to search for.  
    Maximum length: 50.
*   `refine` (query, array of string)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute id and value(s) are separated by '='. Multiple values are supported by a sub-set of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=price=(100..500) Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementColor=red|green|blue. The following system refinement attribute ids are supported:
    
    *   cgid: Allows to refine per single category id. Multiple category ids are not supported.
        
    *   price: Allows to refine per single price range. Multiple price ranges are not supported.
        
    *   pmid: Allows to refine per promotion id(s).
        
    *   orderable\_only: Unavailable products will be excluded from the search results if true is set. Multiple refinement values are not supported.
        
*   `sort` (query, string) The id of the sorting option to sort the search hits.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.
*   `locale` (query, string) The locale context.

#### Responses

*   **400** `MalformedPriceRefinementException` - Thrown if a price refinement parameter is malformed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_search_result`.
    

### GET Search Products - Images

`GET /product_search/images`

Operation ID: `Search Products - Images`. Tags: product\_search. Security: client\_id; customers\_auth.

Provides keyword and refinement search functionality for products. Only returns the product id, link, name and image information in the product search hit.

This resource does not return detailed information about variation products. If a variation product matches the query, basic information for the parent master product is returned. Use the products resource to retrieve more details about a variation product.

This endpoint may return the following faults:

*   400 - MalformedPriceRefinementException - Thrown if a price refinement parameter is malformed.

#### Parameters

*   `q` (query, string) The query phrase to search for.  
    Maximum length: 50.
*   `refine` (query, array of string)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute id and value(s) are separated by '='. Multiple values are supported by a sub-set of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=price=(100..500) Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementColor=red|green|blue. The following system refinement attribute ids are supported:
    
    *   cgid: Allows to refine per single category id. Multiple category ids are not supported.
        
    *   price: Allows to refine per single price range. Multiple price ranges are not supported.
        
    *   pmid: Allows to refine per promotion id(s).
        
    *   orderable\_only: Unavailable products will be excluded from the search results if true is set. Multiple refinement values are not supported.
        
*   `sort` (query, string) The id of the sorting option to sort the search hits.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.
*   `locale` (query, string) The locale context.

#### Responses

*   **400** `MalformedPriceRefinementException` - Thrown if a price refinement parameter is malformed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_search_result`.
    

### GET Search Products - Prices

`GET /product_search/prices`

Operation ID: `Search Products - Prices`. Tags: product\_search. Security: client\_id; customers\_auth.

Provides keyword and refinement search functionality for products. Only returns the product id, link, name and price information in the product search hit.

This resource does not return detailed information about variation products. If a variation product matches the query, basic information for the parent master product is returned. Use the products resource to retrieve more details about a variation product.

This endpoint may return the following faults:

*   400 - MalformedPriceRefinementException - Thrown if a price refinement parameter is malformed.

#### Parameters

*   `q` (query, string) The query phrase to search for.  
    Maximum length: 50.
*   `refine` (query, array of string)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute id and value(s) are separated by '='. Multiple values are supported by a sub-set of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=price=(100..500) Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementColor=red|green|blue. The following system refinement attribute ids are supported:
    
    *   cgid: Allows to refine per single category id. Multiple category ids are not supported.
        
    *   price: Allows to refine per single price range. Multiple price ranges are not supported.
        
    *   pmid: Allows to refine per promotion id(s).
        
    *   orderable\_only: Unavailable products will be excluded from the search results if true is set. Multiple refinement values are not supported.
        
*   `sort` (query, string) The id of the sorting option to sort the search hits.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.
*   `currency` (query, string) The currency mnemonic specified for price.
*   `locale` (query, string) The locale context.

#### Responses

*   **400** `MalformedPriceRefinementException` - Thrown if a price refinement parameter is malformed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_search_result`.
    

### GET Search Products - Represented Products

`GET /product_search/represented_products`

Operation ID: `Search Products - Represented Products`. Tags: product\_search. Security: client\_id; customers\_auth.

Provides keyword and refinement search functionality for products. Only returns the product id, link, name and represented product information in the product search hit.

This resource does not return detailed information about variation products. If a variation product matches the query, basic information for the parent master product is returned. Use the products resource to retrieve more details about a variation product.

This endpoint may return the following faults:

*   400 - MalformedPriceRefinementException - Thrown if a price refinement parameter is malformed.

#### Parameters

*   `q` (query, string) The query phrase to search for.  
    Maximum length: 50.
*   `refine` (query, array of string)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute id and value(s) are separated by '='. Multiple values are supported by a sub-set of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=price=(100..500) Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementColor=red|green|blue. The following system refinement attribute ids are supported:
    
    *   cgid: Allows to refine per single category id. Multiple category ids are not supported.
        
    *   price: Allows to refine per single price range. Multiple price ranges are not supported.
        
    *   pmid: Allows to refine per promotion id(s).
        
    *   orderable\_only: Unavailable products will be excluded from the search results if true is set. Multiple refinement values are not supported.
        
*   `sort` (query, string) The id of the sorting option to sort the search hits.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.
*   `locale` (query, string) The locale context.

#### Responses

*   **400** `MalformedPriceRefinementException` - Thrown if a price refinement parameter is malformed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_search_result`.
    

### GET Search Products - Variations

`GET /product_search/variations`

Operation ID: `Search Products - Variations`. Tags: product\_search. Security: client\_id; customers\_auth.

Provides keyword and refinement search functionality for products. Only returns the product id, name and variation information in the product search hit.

This resource does not return detailed information about variation products. Use the products resource to retrieve more details about a variation product.

This endpoint may return the following faults:

*   400 - MalformedPriceRefinementException - Thrown if a price refinement parameter is malformed.

#### Parameters

*   `q` (query, string) The query phrase to search for.  
    Maximum length: 50.
*   `refine` (query, array of string)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute id and value(s) are separated by '='. Multiple values are supported by a sub-set of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=price=(100..500) Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementColor=red|green|blue. The following system refinement attribute ids are supported:
    
    *   cgid: Allows to refine per single category id. Multiple category ids are not supported.
        
    *   price: Allows to refine per single price range. Multiple price ranges are not supported.
        
    *   pmid: Allows to refine per promotion id(s).
        
    *   orderable\_only: Unavailable products will be excluded from the search results if true is set. Multiple refinement values are not supported.
        
*   `sort` (query, string) The id of the sorting option to sort the search hits.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.
*   `locale` (query, string) The locale context.

#### Responses

*   **400** `MalformedPriceRefinementException` - Thrown if a price refinement parameter is malformed.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_search_result`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### product\_search\_result

Document representing a product search result.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of object_)
*   `fetch_date` (_integer (int32)_)
*   `hits` (_array of product\_search\_hit_) The sorted array of search hits. This array can be empty.
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `query` (_string_) The query String that was searched for.
*   `refinements` (_array of product\_search\_refinement_) The sorted array of search refinements. This array can be empty.
*   `search_phrase_suggestions` (_suggestion_) The suggestion given by the system for the submitted search phrase.
*   `selected_refinements` (_object_) A map of selected refinement attribute id/value(s) pairs. The sorting order is the same as in request URL.
    
    Additional properties: `string`.
    
*   `selected_sorting_option` (_string_) The id of the applied sorting option.
*   `sorting_options` (_array of product\_search\_sorting\_option_) The sorted array of search sorting options. This array can be empty.
*   `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 4,
  "hits": [
    {
      "link": "http://example.com/dw/shop/{version}/products/25772717",
      "price": 99,
      "price_per_unit": 99,
      "product_id": "25772717",
      "product_name": "Zerrick",
      "product_type": {
        "master": true
      },
      "unit_measure": "each",
      "unit_quantity": 1
    },
    {
      "link": "http://example.com/dw/shop/{version}/products/25791388",
      "price": 99,
      "price_per_unit": 99,
      "product_id": "25791388",
      "product_name": "Zacco",
      "product_type": {
        "master": true
      },
      "unit_measure": "each",
      "unit_quantity": 1
    },
    {
      "link": "http://example.com/dw/shop/{version}/products/25772792",
      "price": 79,
      "price_per_unit": 79,
      "product_id": "25772792",
      "product_name": "Aylin",
      "product_type": {
        "master": true
      },
      "unit_measure": "each",
      "unit_quantity": 1
    },
    {
      "link": "http://example.com/dw/shop/{version}/products/25772707",
      "price": 89,
      "price_per_unit": 89,
      "product_id": "25772707",
      "product_name": "Bozwell",
      "product_type": {
        "master": true
      },
      "unit_measure": "each",
      "unit_quantity": 1
    }
  ],
  "query": "shoes",
  "refinements": [
    {
      "attribute_id": "cgid",
      "label": "Category",
      "values": [
        {
          "hit_count": 1,
          "label": "New Arrivals",
          "value": "newarrivals"
        },
        {
          "hit_count": 4,
          "label": "Womens",
          "value": "womens",
          "values": [
            {
              "hit_count": 4,
              "label": "Accessories",
              "value": "womens-accessories",
              "values": [
                {
                  "hit_count": 4,
                  "label": "Shoes",
                  "value": "womens-accessories-shoes"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "attribute_id": "c_refinementColor",
      "label": "Color",
      "values": [
        {
          "hit_count": 1,
          "label": "Beige",
          "presentation_id": "beige",
          "value": "Beige"
        },
        {
          "hit_count": 4,
          "label": "Black",
          "presentation_id": "black",
          "value": "Black"
        },
        {
          "hit_count": 0,
          "label": "Blue",
          "presentation_id": "blue",
          "value": "Blue"
        },
        {
          "hit_count": 0,
          "label": "Navy",
          "presentation_id": "navy",
          "value": "Navy"
        },
        {
          "hit_count": 1,
          "label": "Brown",
          "presentation_id": "brown",
          "value": "Brown"
        },
        {
          "hit_count": 0,
          "label": "Green",
          "presentation_id": "green",
          "value": "Green"
        },
        {
          "hit_count": 1,
          "label": "Grey",
          "presentation_id": "grey",
          "value": "Grey"
        },
        {
          "hit_count": 0,
          "label": "Orange",
          "presentation_id": "orange",
          "value": "Orange"
        },
        {
          "hit_count": 1,
          "label": "Pink",
          "presentation_id": "pink",
          "value": "Pink"
        },
        {
          "hit_count": 0,
          "label": "Purple",
          "presentation_id": "purple",
          "value": "Purple"
        },
        {
          "hit_count": 0,
          "label": "Red",
          "presentation_id": "red",
          "value": "Red"
        },
        {
          "hit_count": 1,
          "label": "White",
          "presentation_id": "white",
          "value": "White"
        },
        {
          "hit_count": 0,
          "label": "Yellow",
          "presentation_id": "yellow",
          "value": "Yellow"
        },
        {
          "hit_count": 0,
          "label": "Miscellaneous",
          "presentation_id": "miscellaneous",
          "value": "Miscellaneous"
        }
      ]
    },
    {
      "attribute_id": "c_isNew",
      "label": "New Arrival"
    },
    {
      "attribute_id": "c_size",
      "label": "Size",
      "values": [
        {
          "hit_count": 0,
          "label": "OS",
          "value": "OS"
        },
        {
          "hit_count": 4,
          "label": "6",
          "value": "6"
        },
        {
          "hit_count": 4,
          "label": "6.5",
          "value": "6.5"
        },
        {
          "hit_count": 4,
          "label": "7",
          "value": "7"
        },
        {
          "hit_count": 4,
          "label": "7.5",
          "value": "7.5"
        },
        {
          "hit_count": 4,
          "label": "8",
          "value": "8"
        },
        {
          "hit_count": 3,
          "label": "8.5",
          "value": "8.5"
        },
        {
          "hit_count": 3,
          "label": "9",
          "value": "9"
        },
        {
          "hit_count": 4,
          "label": "9.5",
          "value": "9.5"
        },
        {
          "hit_count": 3,
          "label": "10",
          "value": "10"
        },
        {
          "hit_count": 1,
          "label": "11",
          "value": "11"
        }
      ]
    },
    {
      "attribute_id": "price",
      "label": "Price",
      "values": [
        {
          "hit_count": 4,
          "label": "$50 - $17.89",
          "value": "(50..100)"
        }
      ]
    }
  ],
  "search_phrase_suggestions": {
    "suggested_phrases": [
      {
        "exact_match": true,
        "phrase": "shoes"
      }
    ],
    "suggested_terms": [
      {
        "original_term": "shoes",
        "terms": [
          {
            "completed": false,
            "corrected": false,
            "exact_match": true,
            "value": "shoes"
          }
        ]
      }
    ]
  },
  "selected_refinements": {
    "cgid": "womens",
    "price": "(0..500)",
    "c_refinementColor": "Black"
  },
  "selected_sorting_option": "top-sellers",
  "sorting_options": [
    {
      "id": "best-matches",
      "label": "Best Matches"
    },
    {
      "id": "price-low-to-high",
      "label": "Price Low To High"
    },
    {
      "id": "price-high-to-low",
      "label": "Price High to Low"
    },
    {
      "id": "product-name-ascending",
      "label": "Product Name A - Z"
    },
    {
      "id": "product-name-descending",
      "label": "Product Name Z - A"
    },
    {
      "id": "brand",
      "label": "Brand"
    },
    {
      "id": "most-popular",
      "label": "Most Popular"
    },
    {
      "id": "top-sellers",
      "label": "Top Sellers"
    }
  ],
  "start": 0,
  "total": 4
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### product\_search\_hit

Document representing a product search hit.

*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `hit_type` (_string_) The type information for the search hit.
*   `image` (_image_) The first image of the product hit for the configured viewtype.
*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the product is orderable.
*   `price` (_number (double)_) The sales price of the product. In case of complex products like master or set this is the minimum price of related child products.
*   `price_max` (_number (double)_) The maximum sales of related child products in case of complex products like master or set.
*   `price_per_unit` (_number (double)_) The sales price per unit of the product. In case of complex products like master or set this is the minimum price per unit of related child products.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of related child products in case of complex products like master or set.
*   `prices` (_object_) The prices map with price book ids and their values.
    
    Additional properties: `number (double)`.
    
*   `product_id` (_string_) The id (SKU) of the product.
*   `product_name` (_string_) The localized name of the product.
*   `product_type` (_product\_type_) The type information for the product.
*   `represented_product` (_product\_ref_) The first represented product.
*   `represented_products` (_array of product\_ref_) All the represented products.
*   `variation_attributes` (_array of variation\_attribute_) The array of represented variation attributes (for the master product only). This array can be empty.

_Example_

```
{
  "link": "http://example.com/dw/shop/{version}/products/25791388?pretty_print=true",
  "product_id": "25791388",
  "product_name": "Zacco",
  "product_type": {
    "item": true
  },
  "represented_product": {
    "id": "25791388",
    "link": "http://example.com/dw/shop/{version}/products/25791388?pretty_print=true"
  },
  "represented_products": [
    {
      "id": "25791388",
      "link": "http://example.com/dw/shop/{version}/products/25791388?pretty_print=true"
    },
    {
      "id": "25772717",
      "link": "http://example.com/dw/shop/{version}/products/25772717?pretty_print=true"
    },
    {
      "id": "25772792",
      "link": "http://example.com/dw/shop/{version}/products/25772792?pretty_print=true"
    },
    {
      "id": "25772707",
      "link": "http://example.com/dw/shop/{version}/products/25772707?pretty_print=true"
    }
  ]
}
```

### product\_search\_refinement

Document representing a product search refinement attribute.

*   `attribute_id` (_string_, required) The id of the search refinement attribute. In the case of an attribute refinement, this is the attribute id. Custom attributes are marked by the prefix "c\_" (for example, "c\_refinementColor"). In the case of a category refinement, the id must be "cgid". In the case of a price refinement, the id must be "price".
*   `label` (_string_) The localized label of the refinement.
*   `values` (_array of product\_search\_refinement\_value_) The sorted array of refinement values. This array can be empty.

### suggestion

Document representing a suggestion.

*   `brands` (_array of string_) The sorted list of suggested brands. This list can be empty.
*   `categories` (_array of suggested\_category_) The sorted list of suggested categories. This list can be empty.
*   `content` (_array of suggested\_content_) The sorted list of suggested content. This list can be empty.
*   `custom_suggestions` (_array of string_) The sorted list of suggested custom suggestions. This list can be empty.
*   `products` (_array of suggested\_product_) The sorted list of suggested products. This list can be empty.
*   `suggested_phrases` (_array of suggested\_phrase_) A list of suggested phrases. This list can be empty.
*   `suggested_terms` (_array of suggested\_terms_) A list of suggested terms. This list can be empty.

_Example_

```
{
  "categories": [
    {
      "id": "mens-clothing-dress-shirts",
      "link": "http://example.com/dw/shop/{version}/categories/mens-clothing-dress-shirts?count=1&q=shi&currency=EUR",
      "name": "Dress Shirts",
      "parent_category_name": "Clothing"
    }
  ],
  "suggested_phrases": [
    {
      "exact_match": false,
      "phrase": "Dress Shirts"
    }
  ],
  "suggested_terms": [
    {
      "original_term": "shi",
      "terms": [
        {
          "completed": true,
          "corrected": false,
          "exact_match": false,
          "value": "shirts"
        }
      ]
    }
  ]
}
```

### product\_search\_sorting\_option

Document representing a product search sorting option.

*   `id` (_string_) The id of the sorting option.
*   `label` (_string_) The localized label of the sorting option.

### image

Document representing a product image.

*   `alt` (_string_) The localized alternative text of the image.
*   `dis_base_link` (_string_) Base URL for dynamic image service address. This is only shown, if the image is stored on the server and DIS is enabled.
*   `link` (_string_, required) The URL of the actual image.  
    Minimum length: 1.
*   `title` (_string_) The localized title of the image.

_Example_

```
{
  "alt": "ALT main swatch",
  "link": "https://example.com/foo/bar/main_swatch.jpg",
  "title": "TITLE main swatch"
}
```

### product\_type

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.
*   `master` (_boolean_) A flag indicating whether the product is a master.
*   `option` (_boolean_) A flag indicating whether the product is an option.
*   `set` (_boolean_) A flag indicating whether the product is a set.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.
*   `variation_group` (_boolean_) A flag indicating whether the product is a variation group.

_Example_

```
{
  "item": true
}
```

### product\_ref

Document representing a product reference.

*   `id` (_string_, required) The ID of the product reference.
*   `link` (_string_, required) The link to the product reference.  
    Maximum length: 100.

_Example_

```
{
  "id": "25791388",
  "link": "http://example.com/dw/shop/{version}/products/25791388?pretty_print=true"
}
```

### variation\_attribute

Document representing a variation attribute.

*   `id` (_string_, required) The id of the variation attribute.  
    Minimum length: 1.
*   `name` (_string_) The localized display name of the variation attribute.
*   `values` (_array of variation\_attribute\_value_) The sorted array of variation values. This array can be empty.

_Example_

```
{
  "id": "memorySize",
  "name": "Memory Size",
  "values": [
    {
      "name": "1 GB",
      "value": "1 GB"
    },
    {
      "name": "2 GB",
      "value": "2 GB"
    },
    {
      "name": "8 GB",
      "value": "8 GB"
    },
    {
      "name": "16 GB",
      "value": "16 GB"
    },
    {
      "name": "32 GB",
      "value": "32 GB"
    },
    {
      "name": "120 GB",
      "value": "120 GB"
    }
  ]
}
```

### product\_search\_refinement\_value

Document representing a product search refinement value.

*   `description` (_string_) The localized description of the refinement value.
*   `hit_count` (_integer (int32)_) The number of search hits when selecting the refinement value. Can be 0.
*   `label` (_string_) The localized label of the refinement value.
*   `presentation_id` (_string_) The optional presentation id associated with the refinement value. The presentation id can be used, for example, to associate an id with an HTML widget.
*   `value` (_string_) The refinement value. In the case of an attribute refinement, this is the bucket, the attribute value, or a value range. In the case of a category refinement, this is the category id. In the case of a price refinement,k this is the price range. Ranges are enclosed by parentheses and separated by ".."; for example, "(100..999)" and "(Aa..Fa)" are valid ranges.
*   `values` (_array of product\_search\_refinement\_value_) The array of hierarchical refinement values. This array can be empty.

### suggested\_category

*   `id` (_string_) The id of the category.
*   `link` (_string_) The URL addressing the category.
*   `name` (_string_) The localized name of the category.
*   `parent_category_name` (_string_) The name of the parent category.

### suggested\_content

*   `id` (_string_) The id of the content.
*   `link` (_string_) The URL addressing the content.
*   `name` (_string_) The localized name of the content.

### suggested\_product

Document representing a product search hit.

*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `image` (_image_) The first image of the product hit for the configured viewtype.
*   `link` (_string_) The URL addressing the product.
*   `price` (_number (double)_) The sales price of the product. In the case of complex products like a master or a set, this is the minimum price of related child products.
*   `product_id` (_string_) The id (SKU) of the product.
*   `product_name` (_string_) The localized name of the product.

### suggested\_phrase

Document representing a suggested search phrase.

*   `exact_match` (_boolean_) Returns whether this suggested phrase exactly matches the user input search phrase.
*   `phrase` (_string_) Returns the suggested search phrase.

_Example_

```
{
  "exact_match": false,
  "phrase": "Sega"
}
```

### suggested\_terms

Document representing a list of suggested terms for each term of a search phrase.

*   `original_term` (_string_) Returns the original term that the suggested terms relates to.
*   `terms` (_array of suggested\_term_) Returns the suggested terms.

_Example_

```
{
  "original_term": "shi",
  "terms": [
    {
      "completed": false,
      "corrected": true,
      "exact_match": false,
      "value": "sega"
    }
  ]
}
```

### variation\_attribute\_value

Document representing a variation attribute value.

*   `description` (_string_) The localized description of the variation value.
*   `image` (_image_) The first product image for the configured viewtype and this variation value.
*   `image_swatch` (_image_) The first product image for the configured viewtype and this variation value. (typically the swatch image)
*   `name` (_string_) The localized display name of the variation value.
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1.

### suggested\_term

Document representing a suggested term.

*   `completed` (_boolean_) Returns whether this term value is a completion match.
*   `corrected` (_boolean_) Returns whether this term value is a correction match.
*   `exact_match` (_boolean_) Returns whether this term value is a exact match.
*   `value` (_string_) Returns the term value.

_Example_

```
{
  "completed": false,
  "corrected": true,
  "exact_match": false,
  "value": "sega"
}
```

<!-- document id=aa4def7d1b2f2dd95b2338edbf21823f1da196fe6411064735b1d5e894d5d232 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-products.md -->

Shop Products (deprecated)

# Shop Products (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get multiple products

`GET /products/({ids})`

Operation ID: `Get multiple products`. Tags: products. Security: client\_id; customers\_auth.

Allows to access multiple products by a single request. This convenience resource should be used instead making separated requests. This saves bandwidth and CPU time on the server. The URI is the same like requesting a single Product by id, but multiple ids wrapped by parentheses and separated can be provided. If a parenthesis or the separator is part of the identifier itself it has to be URL encoded. Instead of a single Product document a result object of Product documents is returned. Note: Only products that are online and assigned to site catalog are returned. The maximum number of ids is 24. If none of the products requested are found, the cache-control header will be defaulted to 60 seconds.

#### Parameters

*   `ids` (path, array of string, required) The ids of the requested products.  
    Maximum length: 100.
*   `expand` (query, array of string) The expand parameter. A comma separated list with the allowed values (availability, bundled\_products, links, promotions, options, images, prices, variations, set\_products, recommendations)
*   `inventory_ids` (query, array of string) the optional inventory list ids, for which the availability should be shown.
*   `currency` (query, string) The currency mnemonic specified for price.
*   `locale` (query, string) The locale context.
*   `all_images` (query, boolean) The flag that indicates whether to retrieve the whole image model for the requested product.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product_result`.
    

### GET Get single product

`GET /products/{id}`

Operation ID: `Get single product`. Tags: products. Security: client\_id; customers\_auth.

To access single products resource, you construct a URL using the template shown below. This template requires you to specify an Id (typically a SKU) for a product. In response, the server returns a corresponding Product document, provided the product is online and assigned to site catalog. The document contains variation attributes (including values) and the variant matrix; this data is provided for both the master and for the variant.

This endpoint may return the following faults:

*   400 - InvalidExpandParameterException - Thrown in case a specified expand parameter value is unknown.

#### Parameters

*   `id` (path, string, required) The id of the requested product.  
    Maximum length: 100.
*   `expand` (query, array of string) The expand parameter. A comma separated list with the allowed values (availability, bundled\_products, links, promotions, options, images, prices, variations, set\_products, recommendations)
*   `inventory_ids` (query, array of string) the optional inventory list ids, for which the availability should be shown.
*   `currency` (query, string) The currency mnemonic specified for price.
*   `locale` (query, string) The locale context.
*   `all_images` (query, boolean) The flag that indicates whether to retrieve the whole image model for the requested product.

#### Responses

*   **400** `InvalidExpandParameterException` - Thrown in case a specified expand parameter value is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get product availability

`GET /products/{id}/availability`

Operation ID: `Get product availability`. Tags: products. Security: client\_id; customers\_auth.

Access product availability information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `inventory_ids` (query, array of string) the optional inventory list ids, for which the availability should be shown.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get bundled products

`GET /products/{id}/bundled_products`

Operation ID: `Get bundled products`. Tags: products. Security: client\_id; customers\_auth.

Access bundled product information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get product images

`GET /products/{id}/images`

Operation ID: `Get product images`. Tags: products. Security: client\_id; customers\_auth.

Access product image information of products that are online and assigned to site catalog. Filter the result by view type and variation values.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `view_type` (query, array of string) The view types.  
    Maximum length: 256.
*   `all_images` (query, boolean) If set to true, all images according to the requested product, view type and attribute value filter are returned. If set to false (or omitted), the best matching image for the requested product is returned. The attribute value filter is ignored in such case.
*   `variation_attribute` (query, string) the variation values context  
    Maximum length: 256.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get product links

`GET /products/{id}/links`

Operation ID: `Get product links`. Tags: products. Security: client\_id; customers\_auth.

Access product link information of products that are online and assigned to site catalog. Filter the result by link type and link direction.

This endpoint may return the following faults:

*   400 - MalformedLinkDirectionParameterException - 400 indicates unknown link direction
*   400 - MalformedLinkTypeCodeParameterException - 400 indicates unknown product link type code
*   404 - ProductNotFoundException - 404 No product with given id found

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `type` (query, string) The type of the product link. (Enum {accessory, alt\_orderunit, cross\_sell, newer\_version, other, replacement, spare\_part, up\_sell} )
*   `direction` (query, string) The product link direction Enum {in, out}
*   `locale` (query, string) The locale context.

#### Responses

*   **400** `MalformedLinkDirectionParameterException` - 400 indicates unknown link direction or `MalformedLinkTypeCodeParameterException` - 400 indicates unknown product link type code
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **404** `ProductNotFoundException` - 404 No product with given id found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get product options

`GET /products/{id}/options`

Operation ID: `Get product options`. Tags: products. Security: client\_id; customers\_auth.

Access product option information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get product prices

`GET /products/{id}/prices`

Operation ID: `Get product prices`. Tags: products. Security: client\_id; customers\_auth.

Access product price information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get product promotions

`GET /products/{id}/promotions`

Operation ID: `Get product promotions`. Tags: products. Security: client\_id; customers\_auth.

Access product promotion information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `currency` (query, string) The currency mnemonic specified for price
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get product recommendations

`GET /products/{id}/recommendations`

Operation ID: `Get product recommendations`. Tags: products. Security: client\_id; customers\_auth.

Access product recommendation information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `recommendation_type` (query, integer (int32)) The optional recommendation type.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get set products

`GET /products/{id}/set_products`

Operation ID: `Get set products`. Tags: products. Security: client\_id; customers\_auth.

Access product set information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

### GET Get applicable shipping methods for certain product

`GET /products/{id}/shipping_methods`

Operation ID: `Get applicable shipping methods for certain product`. Tags: products. Security: customers\_auth; oauth2\_application; client\_id.

Retrieves the applicable shipping methods for a certain product.

This endpoint may return the following faults:

*   404 - ProductNotFoundException - Indicates that the product with the given id is unknown.

#### Parameters

*   `id` (path, string, required) the requested product id  
    Minimum length: 1.

#### Responses

*   **404** `ProductNotFoundException` - Indicates that the product with the given id is unknown.
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `shipping_method_result`.
    

### GET Get product variations

`GET /products/{id}/variations`

Operation ID: `Get product variations`. Tags: products. Security: client\_id; customers\_auth.

Access product variation information of products that are online and assigned to site catalog.

#### Parameters

*   `id` (path, string, required) The requested product id.  
    Maximum length: 100.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `product`.
    

## Schemas

### product\_result

Result document containing an array of products.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of product_) The array of product documents.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "brand": "Creative",
      "id": "creative-zen-v",
      "min_order_quantity": 1,
      "name": "Creative ZEN V Digital Media Player",
      "page_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
      "page_keywords": "Creative",
      "page_title": "Creative ZEN V Digital Media Player",
      "primary_category_id": "electronics-digital-media-players",
      "short_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
      "step_quantity": 1,
      "type": {
        "item": true
      },
      "unit_measure": "each",
      "unit_quantity": 1,
      "c_mediaFormat": [
        "0010",
        "0020",
        "0030",
        "0040"
      ],
      "c_memorySize": "1GB",
      "c_tabDescription": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player."
    },
    {
      "brand": "Namco",
      "id": "namco-we-ski-wii",
      "min_order_quantity": 1,
      "name": "We Ski (for Wii)",
      "page_description": "Welcome to the Happy Ski Resort, where fresh powder, groomed runs, multiple trails, and state of the art facilities await!  We Ski™ takes you down the slopes in the most exciting skiing game to hit the Wii™!  Grab your Wii Remote™ and Nunchuk™ or step onto your Wii Balance Board™ to execute perfect wedge stops, shred the slaloms, and negotiate moguls with ease. With an in-depth Ski School and over a dozen lengthy runs packed with jumps, races, and more, you and your friends won’t want to leave the slopes again!",
      "page_keywords": "Namco",
      "page_title": "We Ski (for Wii)",
      "primary_category_id": "electronic-games",
      "short_description": "Welcome to the Happy Ski Resort, where fresh powder, groomed runs, multiple trails, and state of the art facilities await!  We Ski™ takes you down the slopes in the most exciting skiing game to hit the Wii™!  Grab your Wii Remote™ and Nunchuk™ or step onto your Wii Balance Board™ to execute perfect wedge stops, shred the slaloms, and negotiate moguls with ease. With an in-depth Ski School and over a dozen lengthy runs packed with jumps, races, and more, you and your friends won’t want to leave the slopes again!",
      "step_quantity": 1,
      "type": {
        "item": true
      },
      "unit_measure": "each",
      "unit_quantity": 1,
      "c_gameSystemType": "Wii™",
      "c_tabDescription": "Welcome to the Happy Ski Resort, where fresh powder, groomed runs, multiple trails, and state of the art facilities await!  We Ski™ takes you down the slopes in the most exciting skiing game to hit the Wii™!  Grab your Wii Remote™ and Nunchuk™ or step onto your Wii Balance Board™ to execute perfect wedge stops, shred the slaloms, and negotiate moguls with ease. With an in-depth Ski School and over a dozen lengthy runs packed with jumps, races, and more, you and your friends won’t want to leave the slopes again!"
    }
  ],
  "total": 2
}
```

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### product

Document representing a product.

*   `brand` (_string_) The product's brand.
*   `bundled_products` (_array of bundled\_product_) The array of all bundled products of this product.
*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `ean` (_string_) The European Article Number.
*   `fetch_date` (_integer (int32)_)
*   `id` (_string_, required) The id (SKU) of the product.  
    Minimum length: 1. Maximum length: 100.
*   `image_groups` (_array of image\_group_) The array of product image groups.
*   `inventories` (_array of inventory_) The array of product inventories explicitly requested via 'inventory\_ids' query parameter. This property is only returned in context of the 'availability' expansion.
*   `inventory` (_inventory_) The site default inventory information. This property is only returned in context of the 'availability' expansion.
*   `long_description` (_string (html)_) The localized product long description.
*   `manufacturer_name` (_string_) The products manufacturer name.
*   `manufacturer_sku` (_string_) The products manufacturer sku.
*   `master` (_master_) The master product information. Only for types master, variation group and variant.
*   `min_order_quantity` (_number (double)_) The minimum order quantity for this product.
*   `name` (_string_) The localized product name.
*   `options` (_array of option_) The array of product options. This array can be empty. Only for type option.
*   `page_description` (_string_) The localized products page description.
*   `page_keywords` (_string_) The localized products page description.
*   `page_title` (_string_) The localized products page title.
*   `price` (_number (double)_) The sales price of the product. In case of complex products like master or set this is the minimum price of related child products.
*   `price_max` (_number (double)_) The maximum sales of related child products in case of complex products like master or set.
*   `price_per_unit` (_number (double)_) The sales price per unit of the product. In case of complex products like master or set this is the minimum price per unit of related child products.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of related child products in case of complex products like master or set.
*   `prices` (_object_) The prices map with price book ids and their values.
    
    Additional properties: `number (double)`.
    
*   `primary_category_id` (_string_) The id of the products primary category.
*   `product_links` (_array of product\_link_) The array of source and target products links information.
*   `product_promotions` (_array of product\_promotion_) An array of active customer product promotions for this product, sorted by promotion priority using SORT\_BY\_EXCLUSIVITY ordering (exclusivity -> rank -> promotion class -> discount type -> best discount -> ID). This array can be empty. Coupon promotions are not returned in this array. See PromotionPlan.SORT\_BY\_EXCLUSIVITY for more details.
*   `recommendations` (_array of recommendation_) Returns a list of recommendations.
*   `set_products` (_array of product_) The array of set products of this product.
*   `short_description` (_string (html)_) The localized product short description.
*   `step_quantity` (_number (double)_) The steps in which the order amount of the product can be increased.
*   `type` (_product\_type_) The product type information. Can be one or multiple of the following values: item,master,variation\_group,variant,bundle,set.
*   `unit` (_string_) The sales unit of the product.
*   `unit_measure` (_string_) The unitMeasure of the product.
*   `unit_quantity` (_number (double)_)
*   `upc` (_string_) The Universal Product Code.
*   `valid_from` (_string (date-time)_) The time when product is valid from.
*   `valid_to` (_string (date-time)_) The time when product is valid to.
*   `variants` (_array of variant_) The array of actual variants. This array can be empty. Only for types master, variation group and variant.
*   `variation_attributes` (_array of variation\_attribute_) Sorted array of variation attributes information. This array can be empty. Only for types master, variation group and variant.
*   `variation_groups` (_array of variation\_group_) The array of actual variation groups. This array can be empty. Only for types master, variation group and variant.
*   `variation_values` (_object_)
    
    The actual variation attribute id - value pairs. Only for type variant and variation group.
    
    ```
         Only for type variant and variation group.
    ```
    
    Additional properties: `string`.
    

_Example_

```
{
  "_type": "product",
  "_v": "24.5",
  "brand": "Creative",
  "id": "creative-zen-v",
  "min_order_quantity": 1,
  "name": "Creative ZEN V Digital Media Player",
  "page_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
  "page_keywords": "Creative",
  "page_title": "Creative ZEN V Digital Media Player",
  "primary_category_id": "electronics-digital-media-players",
  "short_description": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player.",
  "step_quantity": 1,
  "type": {
    "item": true
  },
  "c_mediaFormat": [
    "0010",
    "0020",
    "0030",
    "0040"
  ],
  "c_memorySize": "1GB",
  "c_tabDescription": "The ZEN V player was designed for people like you—those who walk a step or two ahead of the pack. So don't be surprised when people take notice of your cool, colorful music and photo player."
}
```

### shipping\_method\_result

Result document containing shipping methods.

*   `applicable_shipping_methods` (_array of shipping\_method_) The applicable shipping method documents.
*   `default_shipping_method_id` (_string_) The default shipping method.

_Example_

```
{
  "applicable_shipping_methods": [
    {
      "description": "The default shipping method.",
      "id": "DefaultShippingMethod",
      "name": "Default Shipping Method",
      "price": 5.55
    },
    {
      "description": "The base shipping method.",
      "id": "BaseShippingMethod",
      "name": "Base Shipping Method",
      "price": 0.99
    },
    {
      "description": "A shipping method that contains product level shipping costs.",
      "id": "ProductLevelShippingCostsShippingMethod",
      "name": "Product Level Shipping Costs Shipping Method",
      "price": 0.1
    }
  ],
  "default_shipping_method_id": "DefaultShippingMethod"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### bundled\_product

Document representing a bundled product within a product bundle.

*   `id` (_string_)
*   `product` (_product_) The product being bundled.
*   `quantity` (_number (double)_) For the product being bundled, the quantity added to the bundle.

_Example_

```
{
  "product": {
    "brand": "Sony",
    "id": "sony-ps3-console",
    "name": "Sony Playstation 3 Game Console",
    "page_description": "ncludes PLAYSTATION 3 80GB system, DUALSHOCK 3 wireless controller, free PLAYSTATION Network membership, internet ready Wi-Fi, and 80GB of hard disk storage for all your games, music, videos, and photos. Every PS3 comes with a built-in Blu-ray player to give you the best high-definition viewing experience and pristine picture quality. Plus, the PS3 can play your entire catalog of CDs and DVDs.",
    "page_keywords": "Sony",
    "page_title": "Sony Playstation 3 Game Console",
    "primary_category_id": "electronics-game-consoles",
    "short_description": "ncludes PLAYSTATION 3 80GB system, DUALSHOCK 3 wireless controller, free PLAYSTATION Network membership, internet ready Wi-Fi, and 80GB of hard disk storage for all your games, music, videos, and photos. Every PS3 comes with a built-in Blu-ray player to give you the best high-definition viewing experience and pristine picture quality. Plus, the PS3 can play your entire catalog of CDs and DVDs.",
    "type": {
      "item": true,
      "option": true
    }
  },
  "quantity": 1
}
```

### image\_group

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of image_) The images of the image group.
*   `variation_attributes` (_array of variation\_attribute_) Returns a list of variation attributes applying to this image group.
*   `view_type` (_string_) The image view type.

_Example_

```
{
  "images": [
    {
      "alt": "ALT master detail",
      "link": "https://example.com/foo/bar/master_detail.jpg",
      "title": "TITLE master detail"
    }
  ],
  "view_type": "detail"
}
```

### inventory

Document representing inventory information of the current product for a particular inventory list.

*   `ats` (_number (double)_) The ats of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.ats.max\_threshold'.
*   `backorderable` (_boolean_) A flag indicating whether the product is back orderable.
*   `id` (_string_, required) The inventory id.
*   `in_stock_date` (_string (date-time)_) A flag indicating the date when the product will be in stock.
*   `orderable` (_boolean_) A flag indicating whether at least one of products is available to sell.
*   `preorderable` (_boolean_) A flag indicating whether the product is pre orderable.
*   `stock_level` (_number (double)_) The stock level of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.stock\_level.max\_threshold'.

_Example_

```
{
  "ats": 0,
  "backorderable": false,
  "id": "BlueJeansInventory",
  "orderable": false,
  "preorderable": false,
  "stock_level": 0
}
```

### master

Document representing a variation master.

*   `link` (_string_) The URL addressing the master product.
*   `master_id` (_string_, required) The id (SKU) of the master product.  
    Minimum length: 1. Maximum length: 100.
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants is orderable.
*   `price` (_number (double)_) The minimum sales price of the related variants.
*   `price_max` (_number (double)_) The maximum sales of related variants.
*   `price_per_unit` (_number (double)_) The minimum sales price per unit of the related variants.
*   `price_per_unit_max` (_number (double)_) The maximum sales price per unit of the related variants.
*   `prices` (_object_)
    
    Additional properties: `number (double)`.
    

### option

Document representing a product option.

*   `description` (_string_) The localized description of the option.
*   `id` (_string_, required) The id of the option.  
    Minimum length: 1. Maximum length: 100.
*   `image` (_string_) The URL to the option image.
*   `name` (_string_) The localized name of the option.
*   `values` (_array of option\_value_) The array of option values. This array can be empty.

### product\_link

Document representing a link between two products. It contains the id of the source and target products, the type of product link, and URLs to retrieve product data.

*   `source_product_id` (_string_) The semantic id of the product from which this product link is coming.
*   `source_product_link` (_string_) The URL addressing the product from which this product link is coming.
*   `target_product_id` (_string_) The semantic id of the product to which this product link is pointing.
*   `target_product_link` (_string_) The URL addressing the product to which this product link is pointing.
*   `type` (_string_) The type of this product link.  
    Allowed values: `cross_sell`, `replacement`, `up_sell`, `accessory`, `newer_version`, `alt_orderunit`, `spare_part`, `other`.

_Example_

```
{
  "source_product_id": "namco-we-ski-wii",
  "source_product_link": "http://example.com/dw/shop/{version}/products/namco-we-ski-wii?pretty_print=true",
  "target_product_id": "midway-cruisn-wii",
  "target_product_link": "http://example.com/dw/shop/{version}/products/midway-cruisn-wii?pretty_print=true",
  "type": "cross_sell"
}
```

### product\_promotion

Document representing a product promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotional_price` (_number (double)_) The promotional price for this product.

_Example_

```
{
  "callout_msg": "Save 15% Off iPod Nano",
  "link": "http://example.com/dw/shop/{version}/promotions/15off-nano",
  "promotion_id": "15off-nano"
}
```

### recommendation

Document representing a product recommendation.

*   `callout_msg` (_string (html)_) The localized callout message of the recommendation.
*   `image` (_image_) The image of the recommendation.
*   `long_description` (_string (html)_) The localized long description of the recommendation.
*   `name` (_string_) The localized name of the recommendation.
*   `recommendation_type` (_recommendation\_type_) The recommendation type of the recommendation.
*   `recommended_item_id` (_string_) The recommended item id of the recommendation.
*   `recommended_item_link` (_string_) The recommended item link of the recommendation.
*   `short_description` (_string (html)_) The localized short description of the recommendation.

### product\_type

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.
*   `master` (_boolean_) A flag indicating whether the product is a master.
*   `option` (_boolean_) A flag indicating whether the product is an option.
*   `set` (_boolean_) A flag indicating whether the product is a set.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.
*   `variation_group` (_boolean_) A flag indicating whether the product is a variation group.

_Example_

```
{
  "item": true
}
```

### variant

Document representing a product variation.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.
*   `price` (_number (double)_) The sales price of the variant.
*   `price_per_unit` (_number (double)_) The sales price of the variant.
*   `product_id` (_string_, required) The id (SKU) of the variant.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

_Example_

```
{
  "link": "http://example.com/dw/shop/{version}/products/apple-ipod-touch-8gb?pretty_print=true",
  "product_id": "apple-ipod-touch-8gb",
  "variation_values": {
    "memorySize": "8 GB"
  }
}
```

### variation\_attribute

Document representing a variation attribute.

*   `id` (_string_, required) The id of the variation attribute.  
    Minimum length: 1.
*   `name` (_string_) The localized display name of the variation attribute.
*   `values` (_array of variation\_attribute\_value_) The sorted array of variation values. This array can be empty.

_Example_

```
{
  "id": "memorySize",
  "name": "Memory Size",
  "values": [
    {
      "name": "1 GB",
      "value": "1 GB"
    },
    {
      "name": "2 GB",
      "value": "2 GB"
    },
    {
      "name": "8 GB",
      "value": "8 GB"
    },
    {
      "name": "16 GB",
      "value": "16 GB"
    },
    {
      "name": "32 GB",
      "value": "32 GB"
    },
    {
      "name": "120 GB",
      "value": "120 GB"
    }
  ]
}
```

### variation\_group

Document representing a variation group.

*   `link` (_string_) The URL addressing the product.
*   `orderable` (_boolean_) A flag indicating whether the variation group is orderable.
*   `price` (_number (double)_) The sales price of the variation group.
*   `price_per_unit` (_number (double)_) The sales price per unit of the variation group.
*   `product_id` (_string_) The id (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100.
*   `variation_values` (_object_) The actual variation attribute id - value pairs.
    
    Additional properties: `string`.
    

### shipping\_method

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.
*   `external_shipping_method` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method id.  
    Maximum length: 256.
*   `name` (_string_) The localized name of the shipping method.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs and product level fix and surcharge costs.
*   `shipping_promotions` (_array of shipping\_promotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

_Example_

```
{
  "id": "BaseShippingMethod"
}
```

### image

Document representing a product image.

*   `alt` (_string_) The localized alternative text of the image.
*   `dis_base_link` (_string_) Base URL for dynamic image service address. This is only shown, if the image is stored on the server and DIS is enabled.
*   `link` (_string_, required) The URL of the actual image.  
    Minimum length: 1.
*   `title` (_string_) The localized title of the image.

_Example_

```
{
  "alt": "ALT main swatch",
  "link": "https://example.com/foo/bar/main_swatch.jpg",
  "title": "TITLE main swatch"
}
```

### option\_value

Document representing an option value.

*   `default` (_boolean_) A flag indicating whether this option value is the default one.
*   `id` (_string_, required) The id of the option value.  
    Minimum length: 1. Maximum length: 100.
*   `name` (_string_) The localized name of the option value.
*   `price` (_number (double)_) The effective price of this option value.

### recommendation\_type

Document representing a recommendation type.

*   `display_value` (_string_) The localized display value of the recommendation type.
*   `value` (_integer (int32)_) The value of the recommendation type.

_Example_

```
{
  "display_value": "Cross-Sell",
  "value": 1
}
```

### variation\_attribute\_value

Document representing a variation attribute value.

*   `description` (_string_) The localized description of the variation value.
*   `image` (_image_) The first product image for the configured viewtype and this variation value.
*   `image_swatch` (_image_) The first product image for the configured viewtype and this variation value. (typically the swatch image)
*   `name` (_string_) The localized display name of the variation value.
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1.

### shipping\_promotion

Document representing a shipping promotion.

*   `callout_msg` (_string_) The localized call-out message of the promotion.
*   `link` (_string_) The URL addressing the promotion.
*   `promotion_id` (_string_) The unique id of the promotion.
*   `promotion_name` (_string_) The localized promotion name.

<!-- document id=152f44d8eb6428c7418f758af5049730ff35bdd3fe5da64742b3462e824de907 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-promotions.md -->

Shop Promotions (deprecated)

# Shop Promotions (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get multiple promotions by filter criteria

`GET /promotions`

Operation ID: `Get multiple promotions by filter criteria`. Tags: promotions. Security: client\_id; customers\_auth.

Handles get promotion by filter criteria Returns an array of enabled promotions matching specified filter criteria. In the request URL, you must provide a campaign\_id parameter, and you can optionally specify a date range by providing start\_date and end\_date parameters. Both parameters are required to specify a date range: omitting one causes the server to return a MissingParameterException fault. Each request returns only enabled promotions; the server does not consider promotion qualifiers or schedules.

This endpoint may return the following faults:

*   400 - EndDateBeforeStartException - Thrown when the given end date is before the given start date
*   400 - MissingEndDateException - Thrown when a start date, but no end date was given
*   400 - MissingStartDateException - Thrown when an end date but no start date was given

#### Parameters

*   `campaign_id` (query, string, required) Find the promotions assigned to this campaign (mandatory)  
    Minimum length: 1. Maximum length: 256.
*   `start_date` (query, string) The start date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ
*   `end_date` (query, string) The end date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ
*   `currency` (query, string) The currency mnemonic specified for price

#### Responses

*   **400** `EndDateBeforeStartException` - Thrown when the given end date is before the given start date or `MissingEndDateException` - Thrown when a start date, but no end date was given or `MissingStartDateException` - Thrown when an end date but no start date was given
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion_result`.
    

### GET Get multiple promotions by Id

`GET /promotions/({ids})`

Operation ID: `Get multiple promotions by Id`. Tags: promotions. Security: client\_id; customers\_auth.

Returns an array of enabled promotions for a list of specified ids. In the request URL, you can specify up to 50 ids. You must enclose the list of ids in parentheses. If you specify an id that contains either parentheses or the separator characters, you must URL encode these characters. Each request returns only enabled promotions; the server does not consider promotion qualifiers or schedules.

#### Parameters

*   `ids` (path, array of string, required) The ids of the requested promotions.  
    Maximum length: 256.
*   `locale` (query, string) The locale context.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion_result`.
    

### GET Get promotion

`GET /promotions/{id}`

Operation ID: `Get promotion`. Tags: promotions. Security: client\_id; customers\_auth.

Returns an enabled promotion using a specified id. Each request returns a response only for an enabled promotion; the server does not consider promotion qualifiers or schedules.

This endpoint may return the following faults:

*   404 - PromotionNotFoundException - Thrown when there is no promotion found with the given ID for the requested site

#### Parameters

*   `id` (path, string, required) The id of the requested promotion.  
    Maximum length: 256.
*   `locale` (query, string) The locale context.

#### Responses

*   **404** `PromotionNotFoundException` - Thrown when there is no promotion found with the given ID for the requested site
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `promotion`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### promotion\_result

Result document containing an array of promotions.

*   `count` (_integer (int32)_) The number of returned documents.
*   `data` (_array of promotion_) The array of promotion documents.
*   `total` (_integer (int32)_) The total number of documents.

_Example_

```
{
  "count": 2,
  "data": [
    {
      "callout_msg": "15% Off GPS Unit With Coupon",
      "details": "15% Off GPS Unit With Coupon with a coupon.",
      "end_date": "2020-06-01T00:00Z",
      "id": "15off-gps",
      "image": "",
      "name": "GPS 15% Off",
      "start_date": "2010-06-01T00:00Z"
    },
    {
      "callout_msg": "20% Off select TVs",
      "details": "20% Off TVs, selected models only for this promotion. Limit 1 television per order",
      "discounted_products_link": "http://example.com/dw/shop/{version}/product_search?pretty_print=true&refine=pmid=20off-tvs",
      "end_date": "2020-06-01T00:00Z",
      "id": "20off-tvs",
      "image": "",
      "name": "20% Off select TVs",
      "start_date": "2010-06-01T00:00Z"
    }
  ],
  "total": 2
}
```

### promotion

Document representing a promotion.

*   `callout_msg` (_string (html)_) The localized call-out message of the promotion.
*   `currency` (_string_) The currency that a promotion can be applied to. A null value means that the promotion applies to all allowed currencies.
*   `details` (_string (html)_) The localized detailed description of the promotion.
*   `discounted_products_link` (_string_) An optional product search link. Product promotions that are marked searchable provide a product search link with the promotion id as refinement.
*   `end_date` (_string (date-time)_) The end date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ . The time zone of the date time is always UTC.
*   `id` (_string_) The unique id of the promotion.
*   `image` (_string_) The URL to the promotion image.
*   `name` (_string_) The localized name of the promotion.
*   `start_date` (_string (date-time)_) The start date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ. The time zone of the date time is always UTC.

_Example_

```
{
  "callout_message": "15% Off GPS Unit With Coupon",
  "details": "15% Off GPS Unit With Coupon with a coupon.",
  "end_date": "2020-06-01T00:00Z",
  "id": "15off-gps",
  "image": "",
  "name": "GPS 15% Off",
  "start_date": "2010-06-01T00:00Z"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=015b01bfd0f93bdc365cd6ce5410f0e342a45127c4966ac7c09c846af7eaeb43 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-search-suggestion.md -->

Shop Search Suggestion (deprecated)

# Shop Search Suggestion (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get search suggestions

`GET /search_suggestion`

Operation ID: `Get search suggestions`. Tags: search\_suggestion. Security: client\_id; customers\_auth.

Provides keyword search functionality for products, categories, content, brands and custom suggestions. Returns suggested products, suggested categories, suggested content, suggested brands and custom suggestions for the given search phrase.

#### Parameters

*   `q` (query, string, required) The query phrase to search for.  
    Minimum length: 3. Maximum length: 50.
*   `count` (query, integer (int32)) The maximum number of suggestions per request. Default value is 5. This affects all types of suggestions (category, product, content, brand, custom suggestions).  
    Minimum: 1. Maximum: 10.
*   `currency` (query, string) The currency mnemonic specified for price. This parameter is effective only for product suggestions.
*   `locale` (query, string)

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `suggestion_result`.
    

## Schemas

### suggestion\_result

Document representing a search suggestion result.

*   `brand_suggestions` (_suggestion_) Returns the suggested brands.
*   `category_suggestions` (_suggestion_) Returns the suggested categories.
*   `content_suggestions` (_suggestion_) Returns the suggested content.
*   `custom_suggestions` (_suggestion_) Returns the suggested custom suggestions.
*   `product_suggestions` (_suggestion_) Returns the suggested products.
*   `query` (_string_) The query phrase to search for.

_Example_

```
{
  "brand_suggestions": {
    "brands": [
      "Sega"
    ],
    "suggested_phrases": [
      {
        "exact_match": false,
        "phrase": "Sega"
      }
    ],
    "suggested_terms": [
      {
        "original_term": "shi",
        "terms": [
          {
            "completed": false,
            "corrected": true,
            "exact_match": false,
            "value": "sega"
          }
        ]
      }
    ]
  },
  "category_suggestions": {
    "categories": [
      {
        "id": "mens-clothing-dress-shirts",
        "link": "http://example.com/dw/shop/{version}/categories/mens-clothing-dress-shirts?count=1&q=shi&currency=EUR",
        "name": "Dress Shirts",
        "parent_category_name": "Clothing"
      }
    ],
    "suggested_phrases": [
      {
        "exact_match": false,
        "phrase": "Dress Shirts"
      }
    ],
    "suggested_terms": [
      {
        "original_term": "shi",
        "terms": [
          {
            "completed": true,
            "corrected": false,
            "exact_match": false,
            "value": "shirts"
          }
        ]
      }
    ]
  },
  "content_suggestions": {
    "content": [
      {
        "id": "super-save-shipping",
        "link": "http://example.com/dw/shop/{version}/content/super-save-shipping?count=1&q=shi&currency=EUR",
        "name": "Super Saver Shipping"
      }
    ],
    "suggested_phrases": [
      {
        "exact_match": false,
        "phrase": "shipping"
      }
    ],
    "suggested_terms": [
      {
        "original_term": "shi",
        "terms": [
          {
            "completed": true,
            "corrected": false,
            "exact_match": false,
            "value": "shipping"
          }
        ]
      }
    ]
  },
  "custom_suggestions": {
    "custom_suggestions": [
      "Point and Shoot"
    ],
    "suggested_phrases": [
      {
        "exact_match": false,
        "phrase": "Point and Shoot"
      }
    ],
    "suggested_terms": [
      {
        "original_term": "shi",
        "terms": [
          {
            "completed": false,
            "corrected": true,
            "exact_match": false,
            "value": "shoot"
          },
          {
            "completed": false,
            "corrected": true,
            "exact_match": false,
            "value": "short"
          }
        ]
      }
    ]
  },
  "product_suggestions": {
    "products": [
      {
        "currency": "EUR",
        "link": "http://example.com/dw/shop/{version}/products/25591125?count=1&q=shi&currency=EUR",
        "price": 29.51,
        "product_id": "25591125",
        "product_name": "Striped Shirt"
      }
    ],
    "suggested_phrases": [
      {
        "exact_match": false,
        "phrase": "shirt"
      }
    ],
    "suggested_terms": [
      {
        "original_term": "shi",
        "terms": [
          {
            "completed": true,
            "corrected": false,
            "exact_match": false,
            "value": "shirt"
          },
          {
            "completed": true,
            "corrected": false,
            "exact_match": false,
            "value": "shirts"
          }
        ]
      }
    ]
  },
  "query": "shi"
}
```

### suggestion

Document representing a suggestion.

*   `brands` (_array of string_) The sorted list of suggested brands. This list can be empty.
*   `categories` (_array of suggested\_category_) The sorted list of suggested categories. This list can be empty.
*   `content` (_array of suggested\_content_) The sorted list of suggested content. This list can be empty.
*   `custom_suggestions` (_array of string_) The sorted list of suggested custom suggestions. This list can be empty.
*   `products` (_array of suggested\_product_) The sorted list of suggested products. This list can be empty.
*   `suggested_phrases` (_array of suggested\_phrase_) A list of suggested phrases. This list can be empty.
*   `suggested_terms` (_array of suggested\_terms_) A list of suggested terms. This list can be empty.

_Example_

```
{
  "categories": [
    {
      "id": "mens-clothing-dress-shirts",
      "link": "http://example.com/dw/shop/{version}/categories/mens-clothing-dress-shirts?count=1&q=shi&currency=EUR",
      "name": "Dress Shirts",
      "parent_category_name": "Clothing"
    }
  ],
  "suggested_phrases": [
    {
      "exact_match": false,
      "phrase": "Dress Shirts"
    }
  ],
  "suggested_terms": [
    {
      "original_term": "shi",
      "terms": [
        {
          "completed": true,
          "corrected": false,
          "exact_match": false,
          "value": "shirts"
        }
      ]
    }
  ]
}
```

### suggested\_category

*   `id` (_string_) The id of the category.
*   `link` (_string_) The URL addressing the category.
*   `name` (_string_) The localized name of the category.
*   `parent_category_name` (_string_) The name of the parent category.

### suggested\_content

*   `id` (_string_) The id of the content.
*   `link` (_string_) The URL addressing the content.
*   `name` (_string_) The localized name of the content.

### suggested\_product

Document representing a product search hit.

*   `currency` (_string_) The ISO 4217 mnemonic code of the currency.
*   `image` (_image_) The first image of the product hit for the configured viewtype.
*   `link` (_string_) The URL addressing the product.
*   `price` (_number (double)_) The sales price of the product. In the case of complex products like a master or a set, this is the minimum price of related child products.
*   `product_id` (_string_) The id (SKU) of the product.
*   `product_name` (_string_) The localized name of the product.

### suggested\_phrase

Document representing a suggested search phrase.

*   `exact_match` (_boolean_) Returns whether this suggested phrase exactly matches the user input search phrase.
*   `phrase` (_string_) Returns the suggested search phrase.

_Example_

```
{
  "exact_match": false,
  "phrase": "Sega"
}
```

### suggested\_terms

Document representing a list of suggested terms for each term of a search phrase.

*   `original_term` (_string_) Returns the original term that the suggested terms relates to.
*   `terms` (_array of suggested\_term_) Returns the suggested terms.

_Example_

```
{
  "original_term": "shi",
  "terms": [
    {
      "completed": false,
      "corrected": true,
      "exact_match": false,
      "value": "sega"
    }
  ]
}
```

### image

Document representing a product image.

*   `alt` (_string_) The localized alternative text of the image.
*   `dis_base_link` (_string_) Base URL for dynamic image service address. This is only shown, if the image is stored on the server and DIS is enabled.
*   `link` (_string_, required) The URL of the actual image.  
    Minimum length: 1.
*   `title` (_string_) The localized title of the image.

_Example_

```
{
  "alt": "ALT main swatch",
  "link": "https://example.com/foo/bar/main_swatch.jpg",
  "title": "TITLE main swatch"
}
```

### suggested\_term

Document representing a suggested term.

*   `completed` (_boolean_) Returns whether this term value is a completion match.
*   `corrected` (_boolean_) Returns whether this term value is a correction match.
*   `exact_match` (_boolean_) Returns whether this term value is a exact match.
*   `value` (_string_) Returns the term value.

_Example_

```
{
  "completed": false,
  "corrected": true,
  "exact_match": false,
  "value": "sega"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=7eabc713e7c90ce77c46c887d0f69a0bfdfb559fd2f99f18ff373d9bbf136abe url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-sessions.md -->

Shop Sessions (deprecated)

# Shop Sessions (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### POST Exchange JWT

`POST /sessions`

Operation ID: `Exchange JWT`. Tags: sessions. Security: customers\_auth.

Exchanges a valid JWT into a new session, which is associated with the authenticated or anonymous customer. All _Set-Cookie_ headers for handling the session are applied on the response.

Only the JWT is used to create the new session. Any session IDs included in the request are ignored.

Once you create a session from a JWT, you can use it in parallel with stateless OCAPI calls that use the JWT. There is no need to call the bridging resources again.

If the customer is authenticated and has a storefront basket, that basket is transferred into the session and can be retrieved using BasketMgr.getCurrentBasket(), along with sensitive data such as addresses and payment information. The following examples show why this behavior is important to understand as it relates to guest customers:

Basket created after the session is created:

POST /customers/auth with type "guest"
POST /sessions
POST /baskets
Storefront request (controller with BasketMgr.getCurrentBasket())
-> Sensitive data is erased from the basket due to security considerations

Basket created before the session is created:

POST /customers/auth with type "guest"
POST /baskets
POST /sessions
Storefront request (controller with BasketMgr.getCurrentBasket())
-> Sensitive data is accessible because the basket is marked as secured for this session

#### Responses

*   **204**

## Schemas

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=7f15173d1fd48260f080aa8fd6d2ae797872dbd533a625a81f990e12e412e73f url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-site.md -->

Shop Site (deprecated)

# Shop Site (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get site

`GET /site`

Operation ID: `Get site`. Tags: site. Security: client\_id; customers\_auth.

Access site information, like site status and site content URLs.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `site`.
    

## Schemas

### site

Document representing a site.

*   `allowed_currencies` (_array of string_) The list of allowed currencies.
*   `allowed_locales` (_array of locale_) A list of all allowed site locales.
*   `default_currency` (_string_) The currency mnemonic of the site.
*   `default_locale` (_string_) The default locale of the site.
*   `http_dis_base_url` (_string_) The HTTP DIS base URL.
*   `http_hostname` (_string_) The configured HTTP host name. If no host name is configured the instance host name is returned.
*   `http_library_content_url` (_string_) The HTTP URL to the library content location of the site.
*   `http_site_content_url` (_string_) The HTTP URL to the site content location.
*   `https_dis_base_url` (_string_) The HTTPS DIS base URL.
*   `https_hostname` (_string_) The configured HTTPS host name. If no host name is configured the instance host name is returned.
*   `https_library_content_url` (_string_) The HTTPS URL to the library content location of the site.
*   `https_site_content_url` (_string_) The HTTPS URL to the site content location.
*   `id` (_string_) The id of the site.
*   `name` (_string_) The descriptive name for the site.
*   `status` (_string_) The site status online/offline.  
    Allowed values: `online`, `offline`.
*   `timezone` (_string_) The time zone of the site (for example, USA/Eastern).
*   `timezone_offset` (_integer (int32)_) The time zone offset from UTC for the current time in milliseconds (for example, -14400000).

_Example_

```
{
  "allowed_currencies": [
    "USD",
    "EUR"
  ],
  "allowed_locales": [
    {
      "country": "US",
      "default": true,
      "display_country": "United States",
      "display_language": "English",
      "display_name": "English (United States)",
      "id": "en-US",
      "iso3_country": "USA",
      "iso3_language": "eng",
      "language": "en",
      "name": "English (United States)"
    },
    {
      "country": "",
      "default": false,
      "display_country": "",
      "display_language": "español",
      "display_name": "español",
      "id": "es",
      "iso3_country": "",
      "iso3_language": "spa",
      "language": "es",
      "name": "Spanish"
    }
  ],
  "default_currency": "USD",
  "default_locale": "default",
  "http_dis_base_url": "http://image.<domain>/dw/image/v2/abcd_s01",
  "http_hostname": "demo.ocapi.<domain>",
  "http_library_content_url": "http://demo.ocapi.<domain>/on/<domain>.static/Sites-SiteGenesis-Site/Sites-SiteGenesis-Library/default/v1345174669086",
  "http_site_content_url": "http://demo.ocapi.<domain>/on/<domain>.static/Sites-SiteGenesis-Site/-/default/v1345174669086",
  "https_dis_base_url": "https://image.<domain>/dw/image/v2/abcd_s01",
  "https_hostname": "demo.ocapi.<domain>",
  "https_library_content_url": "https://demo.ocapi.<domain>/on/<domain>.static/Sites-SiteGenesis-Site/Sites-SiteGenesis-Library/default/v1345174669086",
  "https_site_content_url": "https://demo.ocapi.<domain>/on/<domain>.static/Sites-SiteGenesis-Site/-/default/v1345174669086",
  "id": "SiteGenesis",
  "name": "Site Genesis",
  "status": "online",
  "timezone": "Etc/UTC",
  "timezone_offset": 0
}
```

### locale

Document that describes a single locale.

*   `country` (_string_) The uppercase ISO 3166 2-letter country/region code for this Locale. If no country has been specified for this Locale, this value is an empty string.
*   `default` (_boolean_) Flag that is true if this locale is the default to use if a locale is not specified.
*   `display_country` (_string_) The display name of this Locale's country, in this Locale's language, not in the session locale's language. If no country has been specified for this Locale, this value is an empty string.
*   `display_language` (_string_) The display name of this Locale's language, in this Locale's language, not in the session locale's language. If no country has been specified for this Locale, this value is an empty string.
*   `display_name` (_string_) The display name of this Locale, in this Locale's language, not in the session locale's language. If no display name has been specified for this Locale, this value is an empty string.
*   `id` (_string_) The identifier of the `Locale`. Combines the language and the country key, concatenated with "-". For example: "en-US". This attribute is the primary key of the class.
*   `iso3_country` (_string_) The uppercase ISO 3166 3-letter country/region code for this Locale. If no country has been specified for this Locale, this value is an empty string.
*   `iso3_language` (_string_) The 3-letter ISO 639 language code for this Locale. If no language has been specified for this Locale, this value is an empty string.
*   `language` (_string_) The lowercase ISO 639 language code for this Locale. If no language has been specified for this Locale, this value is an empty string.
*   `name` (_string_) The display name of the Locale. Uses the current request locale to localize the value.

_Example_

```
{
  "country": "US",
  "default": true,
  "display_country": "United States",
  "display_language": "English",
  "display_name": "English (United States)",
  "id": "en-US",
  "iso3_country": "USA",
  "iso3_language": "eng",
  "language": "en",
  "name": "English (United States)"
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

<!-- document id=bdeb9ebed9a267daf80ffd59373f6a4c37770240e49fd7cafccaec6e6145ea12 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-stores.md -->

Shop Stores (deprecated)

# Shop Stores (deprecated)

The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders.

**Version:** 25.6

## Servers

*   `https://{host}/s/{siteId}/dw/shop/v25_6`

Protocols: https.

## Security

*   `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header.
*   `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager.
    *   OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token)
    *   Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required.
*   `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter.
    *   API key in header: x-dw-client-id

## Operations

### GET Get nearest stores

`GET /stores`

Operation ID: `Get nearest stores`. Tags: stores. Security: client\_id; customers\_auth.

This resource retrieves a list of stores, for the given site, that are within a configured distance of a location on the earth. The stores and their distance from the specified location are returned as a result set of Store objects. The distance is interpreted either in miles or kilometers depending on the distance\_unit input parameter.

The location can be specified by either directly providing a latitude/longitude coordinate pair or by providing a country and a postal code:

*   If a postal code is passed, the resource looks in the system's geolocation mappings to find the coordinates for this postal code. If no matching geolocation is found, the resource will return an empty list of stores.
    
*   If coordinates are passed, the values for country and postal code are ignored.
    

This endpoint may return the following faults:

*   400 - MalformedDistanceUnitException - Invalid distance\_unit given.
*   400 - MissingCoordinatesException - Thrown if only one of latitude or longitude are provided.
*   400 - MissingCountryCodeException - Thrown if no coordinates (latitude and longitude) are provided and in addition no country code is given.
*   400 - MissingPostalCodeException - Thrown if no coordinates (latitude and longitude) are provided and in addition no postal code is given..

#### Parameters

*   `latitude` (query, number (double)) The geo coordinate latitude to search for stores (value range -90.00 .. 90.00).  
    Minimum: -90. Maximum: 90.
*   `longitude` (query, number (double)) The geo coordinate longitude to search for stores (value range -180.00 .. 180.00).  
    Minimum: -180. Maximum: 180.
*   `country_code` (query, string) The two letter ISO country code e.g. "US".  
    Minimum length: 2. Maximum length: 2.
*   `postal_code` (query, string) The postal code e.g. "01801".  
    Minimum length: 3. Maximum length: 10.
*   `distance_unit` (query, string) The distance unit. Supported values are "mi" and "km" (for miles and kilometers respectively, default is "km").
*   `max_distance` (query, number (double)) The area (radius) in distancUnit where stores will be searched for (default is half of the earth's perimeter).  
    Minimum: 0. Maximum: 20012.
*   `start` (query, integer (int32)) The result set index to return the first instance for. Default value is 0.  
    Minimum: 0.
*   `count` (query, integer (int32)) The maximum number of instances per request. Default value is 25.  
    Minimum: 1. Maximum: 200.

#### Responses

*   **400** `MalformedDistanceUnitException` - Invalid distance\_unit given. or `MissingCoordinatesException` - Thrown if only one of latitude or longitude are provided. or `MissingCountryCodeException` - Thrown if no coordinates (latitude and longitude) are provided and in addition no country code is given. or `MissingPostalCodeException` - Thrown if no coordinates (latitude and longitude) are provided and in addition no postal code is given..
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `store_result`.
    

### GET Get multiple stores

`GET /stores/({ids})`

Operation ID: `Get multiple stores`. Tags: stores. Security: client\_id; customers\_auth.

To access multiple stores, you construct a URL using the template shown below. This template requires you to specify a store id. In the response, the server returns a corresponding store document.

#### Parameters

*   `ids` (path, array of string, required) The ids of the requested stores.  
    Maximum length: 256.

#### Responses

*   **default**
    
    Media type: `application/json, text/xml`. Schema: `store_result`.
    

### GET Get store

`GET /stores/{id}`

Operation ID: `Get store`. Tags: stores. Security: client\_id; customers\_auth.

To access a store, you construct a URL using the template shown below. This template requires you to specify a store id. In the response, the server returns a corresponding store document.

This endpoint may return the following faults:

*   404 - StoreNotFoundException - Thrown if the requested store was not found

#### Parameters

*   `id` (path, string, required) The id of the requested store.  
    Maximum length: 256.

#### Responses

*   **404** `StoreNotFoundException` - Thrown if the requested store was not found
    
    Media type: `application/json, text/xml`. Schema: `fault`.
    
*   **default**
    
    Media type: `application/json, text/xml`. Schema: `store`.
    

## Schemas

### fault

Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error).

*   `arguments` (_object_)
    
    A map that provides fault arguments.
    
    Data can be used to provide error messages on the client side.
    
    Additional properties: `object`.
    
*   `cause` (_cause_)
*   `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given
*   `message` (_string_) The message text of the java exception.
*   `stack_trace` (_string_)
*   `type` (_string_) The name of the java exception.

### store\_result

Result document containing an array of stores.

*   `count` (_integer (int32)_) The number of search results in the current page.
*   `data` (_array of store_)
*   `next` (_string_) The URL of the next result page.
*   `previous` (_string_) The URL of the previous result page.
*   `start` (_integer (int32)_) The zero-based index of the first search result to include in the document.  
    Minimum: 0.
*   `total` (_integer (int32)_) The total number of search results.

_Example_

```
{
  "count": 4,
  "data": [
    {
      "address1": "333 Washington St",
      "city": "Boston",
      "country_code": "US",
      "distance": 0,
      "distance_unit": "mi",
      "email": "contact@downtowntvshop.com",
      "id": "store10",
      "name": "Downtown TV Shop",
      "phone": "+1-617-695-1565",
      "pos_enabled": false,
      "postal_code": "02108",
      "state_code": "MA",
      "store_locator_enabled": true
    },
    {
      "address1": "1001 Cambridge St",
      "city": "Cambridge",
      "country_code": "US",
      "distance": 1.41,
      "distance_unit": "mi",
      "email": "store4@company.com",
      "id": "store4",
      "name": "Champaign Electronic Shop",
      "phone": "+1-617-714-2640",
      "pos_enabled": false,
      "postal_code": "02141",
      "state_code": "MA",
      "store_locator_enabled": true
    },
    {
      "address1": "584 Columbus Ave",
      "city": "Boston",
      "country_code": "US",
      "distance": 1.94,
      "distance_unit": "mi",
      "id": "store5",
      "name": "Short Electro",
      "phone": "+1-617-888-7276",
      "pos_enabled": false,
      "postal_code": "02118",
      "state_code": "MA",
      "store_locator_enabled": true
    },
    {
      "address1": "363 Hancock St",
      "city": "North Quincy",
      "country_code": "US",
      "distance": 6.56,
      "distance_unit": "mi",
      "email": "store3@company.com",
      "id": "store3",
      "name": "Wire-Wire",
      "phone": "+1-617-318-2860",
      "pos_enabled": false,
      "postal_code": "02171",
      "state_code": "MA",
      "store_locator_enabled": true
    }
  ],
  "next": "http://example.com/dw/shop/{version}/stores?count=4&start=4&country_code=US&postal_code=02108&distance_unit=mi&max_distance=10.00",
  "start": 0,
  "total": 8
}
```

### store

Document representing a store.

*   `address1` (_string_) The first address of the store.  
    Minimum length: 1.
*   `address2` (_string_) The second address of the store.
*   `city` (_string_) The city of the store.
*   `country_code` (_string_) The country code of the store.  
    Allowed values: `CA`, `DE`, `US`. Value meanings: `CA`: Canada; `DE`: Germany; `US`: United States.
*   `distance` (_number (double)_) The distance to the given geo location in the unit of attribute distance (miles or kilometers).
*   `distance_unit` (_string_) The distance unit the distance attribute is measured in (either in miles or kilometers).
*   `email` (_string_) The email address of the store.
*   `fax` (_string_) The fax number of the store.
*   `id` (_string_, required) The id of the store.  
    Minimum length: 1. Maximum length: 256.
*   `image` (_string_) The store image.
*   `inventory_id` (_string_) The inventory list id associated with this store.  
    Maximum length: 256.
*   `latitude` (_number (double)_) The latitude of the store.  
    Minimum: -90. Maximum: 90.
*   `longitude` (_number (double)_) The longitude of the store.  
    Minimum: -180. Maximum: 180.
*   `name` (_string_) The store name.
*   `phone` (_string_) The phone number of the store.
*   `pos_enabled` (_boolean_) Whether this store uses Store Point-of-Sale.
*   `postal_code` (_string_) The postal code of the store.
*   `state_code` (_string_) The state code of the store.
*   `store_events` (_string (html)_) The store events.
*   `store_hours` (_string (html)_) The store opening hours.
*   `store_locator_enabled` (_boolean_) Whether this store should show up in store locator results.

_Example_

```
{
  "address1": "333 Washington St",
  "city": "Boston",
  "country_code": "US",
  "email": "contact@downtowntvshop.com",
  "id": "ma-bos-dt",
  "name": "Downtown TV Shop",
  "phone": "+1-617-695-1565",
  "pos_enabled": false,
  "postal_code": "02108",
  "state_code": "MA",
  "store_locator_enabled": true
}
```

### cause

*   `cause` (_cause_)
*   `message` (_string_)
*   `type` (_string_)

<!-- document id=3b90d6a0458d036e8af29a22feddd46393ad5e86986f50f2ba08099a011e998e url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-api-future.md -->

# Shop the Future

You can retrieve promotions that are active at a particular time. Implement this use case in your storefront by following the steps below:

## Set Shopper Context

Follow the instructions in [Set and Retrieve Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md#set-and-retrieve-shopper-context).

## Set Effective Date

To retrieve promotions that are active within a particular time window, set an effective date as a context parameter.

![Shopper Context storefront configuration interface](https://developer.salesforce.com/docs/media/commerce-api/shopper-context-stf.png)

```json
{"effectiveDateTime": "2020-12-20T00:00:00Z"
}
```

**note:** If the effect date time isn’t provided, the current `dateTime` is assumed.

## See Also

- [createShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=createShopperContext)
- [Shopper Login (SLAS)](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=Summary)
- [Assign a Price Book or Promotion to a Specific Store in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_assigning_a_pricebook_or_promotion_specific.htm&type=5) in _Salesforce Help_

<!-- document id=bd770fa99a88e88ae2f28e0cdc999787a0e3282a994532fa2fa1dd2c2644278e url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-shopping-agent.md -->

# Shopper Agent for Storefront Next

Shopper Agent for Storefront Next guides customers through product discovery and their purchasing journey. With the AI-powered Shopper Agent, shoppers can find products, get recommendations, and complete purchases using the Commerce Client chat instead of traditional browse-and-click navigation. Enable Shopper Agent to provide it in your storefront.

## Required Licenses

See [Required Licenses for the B2C Shopper Agent](https://help.salesforce.com/s/articleView?id=cc.b2c_shopping_agent_licences.htm&type=5) in _Salesforce Help_.

For detailed configuration steps, see [Install the Agentforce Commerce Client on Storefront Next](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/agentforce-commerce-client/install-on-sfnext.md).

After you complete the setup of Shopper Agent, launch it by opening the chat panel in one of these locations.

- The storefront header: click the Shopper Agent icon.

  ![Launch Shopper Agent from the header to get the chat window](https://developer.salesforce.com/docs/media/sfnext/sfnext-shopper-agent-launch.png)

- The Account Overview page: under the "Need Help?" section, click **Ask a question**.

  ![Launch Shopper Agent from the header to get the chat window](https://developer.salesforce.com/docs/media/sfnext/sfnext-shopper-agent-launch-account-overview.png)

<!-- document id=f9a349baf8bfb7eb51f9e3992e5acee2d310887aa01ef2ac4c37ed36f5e4de90 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-agents.md -->

Shopper Agents

# Shopper Agents

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-agents/shopper-agents-oas-v1-public.yaml)

## API Overview

This REST API initializes an Agentforce session when a new session starts.

### Authentication & Authorization

The Shopper Agent API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include the relevant scope(s) in the client ID used to generate the SLAS token.

*   `sfcc.shopper-agents.rw`: Required for initializing shopper agent session (POST operations).

For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

### Use Cases

#### Shopper Agent Initialization

When a new agentic session starts, you receive a session initialization key. Include that key in the request to initialize the Agentforce session.

**Flow:**

1.  Obtain a `sessionInitKey` from a supported service.
2.  Initialize an agent session using the previously obtained `sessionInitKey`.

#### sessionInitKey

`sessionInitKey` is the session initialization identifier that is obtained when an Agentforce session starts.

The request body must include the `sessionInitKey` field. Missing or invalid `sessionInitKey` results in `INVALID_REQUEST_PARAMETERS` (400).

**Version:** 1.1.5

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-agents/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the B2C Commerce Shopper API endpoints.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-agents.rw: Allows read/write operations on shopper agents.
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-agents.rw: Allows read/write operations on shopper agents
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-agents.rw: Allows read/write operations on shopper agents.

## Operations

### POST Initializes an Agentforce session.

`POST /organizations/{organizationId}/session/init`

Operation ID: `postSessionInit`. Security: ShopperToken (sfcc.shopper-agents.rw); ShopperClientContextToken (sfcc.shopper-agents.rw).

The request body must include the sessionInitKey field. Missing or invalid sessionInitKey information results in INVALID\_REQUEST\_PARAMETERS (400).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `SessionInitRequest`.

_Example: ShopperAgentsSessionInitRequest_

```
{
  "sessionInitKey": "aPrx.0rn0R1k7G.PtUUXh6S90_rMvqsYhpDZlNpyYsLsTm8KYLodM3flsRBbCD"
}
```

#### Responses

*   **202** Accepted (initialization successful; no response body)
*   **400** Validation Error
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ValidationError_
    
    ```
    {
      "title": "Validation Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "Unable to validate post body."
    }
    ```
    
*   **401** Unauthorized (invalid or expired token)
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "title": "Invalid Basic Authentication",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user."
    }
    ```
    
*   **500** Unexpected server-side exception during SLAS authentication
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ReadError_
    
    ```
    {
      "title": "Internal Server Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/internal-server-error",
      "detail": "Unexpected server-side exception during SLAS authentication."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SessionInitRequest

*   `sessionInitKey` (_string_) The session initialization key that is is obtained when beginning an Agentforce session, and is then used to initialize the session.  
    Minimum length: 1. Maximum length: 256. Example: `aPrx.0rn0R1k7G.PtUUXh6S90_rMvqsYhpDZlNpyYsLsTm8KYLodM3flsRBbCD`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

<!-- document id=4fc4b0e06e89996d27db129dedb254ab9a0115db4c27d4aad4d3c2f29d11acf2 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/performance.md -->

# Shopper API Performance and Best Practices

Optimize your shopper experience and B2C Commerce instance operations using the following Shopper API performance best practices. The choices you make in API implementation, testing, and monitoring all significantly influence storefront performance.

The best practices provided in this article focus on Shopper API performance. Some of this information also applies to SCAPI Admin APIs, but some of it does not, for example: the hook-related information.

For Composable Storefront performance guidance, see [Performance Guide for Composable Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/perf-guide.html).

**note:** Performance is an important aspect for your APIs, not only to allow your customers to navigate through your storefront quickly and purchase items with ease, but also to avoid impact to your storefront when APIs do not respond within the specified time limit. Shopper APIs must respond in under 10 seconds, or a HTTP 504 timeout response is returned and users will not be able to complete transactions due to these errors.

## SCAPI Performance Responsibilities

When you build a feature, you must decide which APIs you will use to build it:

- Shopper APIs (out-of-the-box)
- Shopper APIs with hooks
- Custom APIs

This decision impacts performance and the amount of performance-related work that you must do. SCAPI performance is a shared responsibility, which is summarized in the following table:

| API Type                      | Performance Testing Responsibilities                                                                                                  | Performance Notes                                                                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Shopper APIs (out-of-the-box) | Salesforce: <ul><li>Shopper API code</li></ul>You:<ul><li>Your catalog</li><li>Parameters you send</li></ul>                          | Salesforce tests the Shopper APIs to ensure that they are performant.                                                                        |
| Shopper APIs with hooks       | Salesforce: <ul><li>Shopper API code</li></ul>You:<ul><li>Your catalog</li><li>Parameters you send</li><li>Your custom code</li></ul> | Hooks are slower than the out-of-the-box (OOTB) Shopper APIs because using hooks includes both the Shopper API code and your customizations. |
| Custom APIs                   | You:<ul><li>Your catalog</li><li>Parameters you send</li><li>All API code that you write</li></ul>                                    | Performance testing efforts increase as code size increases.                                                                                 |

## Shopper API Implementation Best Practices

Use the out-of-the-box (OOTB) Shopper APIs when the provided functionality is sufficient.

For example, let's say you're building a storefront and you want to display a list of products. You can typically accomplish this with existing Shopper Search or Shopper Products API functionality.

When you call Shopper APIs, pay attention to:

### Catalog size

The larger your catalog, the longer certain platform requests take, for example: if you search using Shopper Products, searching a small number of products is faster than searching a large number of products.

Make sure you understand your catalog data and test for worst-case scenarios. Some Shopper APIs return responses that aren't paginated, such as categories and variants, which can result in very large response sizes.

For example: you call [`getCategories`](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getCategories) with `levels=2` and `id=root`. If your category tree includes thousands of categories, the resulting response is large. Or, you call [`getProducts`](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProducts) with `expand=variants` for a pair of pants that can vary by fit, waist, inseam, colors, washes, rise, and stretch. This could easily produce a huge response!

### Response size

Bigger responses take longer to retrieve and transfer.

Response size is impacted by:

- Your catalog and number of objects
- Expansions
  - Many Shopper APIs support expansions, which is the ability to query related objects. Expansions also increase retrieval and transfer time.
- Custom attributes
  - Use custom attributes to extend system objects. Use `select` or hooks to remove attributes you don't need.

Use the [`select`](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html) or `expand` parameters to only select the response properties you need. For complex response filtering, use modify hooks.

Make sure that your API client is configured to request [compressed](https://developer.mozilla.org/en-US/docs/Web/HTTP/Compression) resources.

### Caching

Expansions impact cache effectiveness as some expansions can only be cached for a short amount of time. If you must use an expansion with low cache time, like `availability`, which can only be cached for 60 seconds, consider making an additional request to retrieve it when needed. This is especially important for API endpoints you call frequently, like [_product search_](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-search?meta=productSearch) and [get products](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProducts). For details, see [Default Cache Expiration and Personalization Settings](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html?q=caching#default-cache-expiration-and-personalization-settings).

**note:** If no expand parameter is specified, all expansions are considered selected. For more details, see ["expand" Parameter Impact on Cache Hit Rates](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#expand-parameter-impact-on-cache-hit-rates).

Be careful about adding intermediate caches on top of B2C Commerce APIs. Most API responses can be [personalized](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching), which means it isn't possible to use only the URL as the cache key in an upstream caching system like NGINX or a stacked CDN.

In Production Business Manager, the SCAPI zone includes HTTP and security analytics. A data replication, or invalidating the site page cache in Business Manager, also purges the SCAPI CDN cache. If you suspect the cache is outdated, purge it by tag or path in the [SCAPI zone](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5) or with [cachePurge](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=cachePurge).

## Hook Implementation Best Practices

If a Shopper API exists, but it doesn't have all the data or functionality you need, extend it using hooks.

APIs that include hooks are always slower than APIs without hooks, because there is additional code to execute. With hooks, the Shopper APIs and your hook customizations are being run. If you're adding hooks, you are responsible for the performance of your code, so make sure you perform adequate performance testing to make sure that the code you're using is performant.

Hooks are extensions to system logic, and these extensions run whenever the applicable API logic is run. For example, Shopper API code runs frequently, so make sure you:

- Follow the best practices previously listed in [Shopper API Implementation Best Practices](#shopper-api-implementation-best-practices).
- Use the [code profiler](https://developer.salesforce.com/docs/commerce/commerce-api/guide/code-profiler.html) to view the performance of your hooks.
- Consider whether your hook logic impacts how long a response can be cached. Modify the out of the box caching if required using the [Script API](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#change-cache-settings-programmatically).
- Minimize calls to external systems. If you must call out to an external service, use the [service framework](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html) and ensure the associated service's profile has aggressive timeout and circuit breaking settings. Review whether it is possible to [import](https://help.salesforce.com/s/articleView?id=cc.b2c_import_and_export.htm&language=en_US&type=5) the external data into your B2C instance rather than requesting it at runtime.
- Consider caching expensive operations in a [custom caches](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-caches.html). Custom caches are limited to 20B total and 128KB per entry. If these limits are exceeded, a warning is returned. For custom cache details, see [Custom Caches](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-caches.html).

**note:** Hook performance is negatively impacted with complex promotions that involve a large number of retrievals. Make sure you work with your merchandising team to [optimize promotions](https://help.salesforce.com/s/articleView?id=cc.b2c_promotion_best_practices.htm&type=5).

## Custom API Best Practices

Use Custom APIs when no equivalent Shopper API exists for what you want to do. This involves code that you write, so make sure you perform adequate performance testing for your Custom APIs.

- Follow the best practices previously listed in [Shopper API Implementation Best Practices](#shopper-api-implementation-best-practices) and [Hook Implementation Best Practices](#hook-implementation-best-practices).
- With custom APIs, you are responsible for caching. Consider whether responses from your API are suitable for caching, and if so, use the [Script API](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-caching.html) to make sure that the platform caches them.
- Use [remote includes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-api-remote-includes.html) where applicable to create reusable response fragments that you can cache separately, such as promotion details or product information.

## Test and Measure Your APIs

Measure the speed of your endpoints, hooks, and Custom APIs. Slow responses impact shopper experience and also make your storefront instance work harder. Your storefront can serve far more fast responses than slow responses.

- For SCAPI response time constraints, see [Error Codes](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html).
- For help resolving request timeouts, see [Troubleshoot Request Timeouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeout-troubleshoot.md).

Check your API performance with your initial implementation, but also implement continuous monitoring after building them, as performance is an ongoing concern. Two key performance testing approaches are laboratory testing and field testing.

Laboratory testing involves setting up ongoing performance tests against specific endpoints and measuring the results. If performance drops, an alarm (such as an email) alerts your team to review it. This is typically done in Continuous Integration environments.

Field testing measures the performance of actual API calls in real-world usage. For details, see [Reports and Dashboards Technical Timing SCAPI](https://help.salesforce.com/s/articleView?id=cc.b2c_technical_scapi_dashboard.htm&type=5) page.

### Laboratory Testing

Laboratory testing uses controlled conditions to test out API changes, for example, testing it in rapid succession to make sure that you haven't regressed performance and that performance meets acceptable standards before deployment.

Integrate laboratory testing into your continuous integration (CI) to create tests that record timing information, for example: create a test that makes multiple requests to your APIs.

If performance is too slow:

- See [collect request details](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md#collect-detailed-request-information) for how to inspect and track Shopper API, hook, and Custom API call times.
- Use the [code profiler](https://developer.salesforce.com/docs/commerce/commerce-api/guide/code-profiler.html) to investigate timing bottlenecks in your code.

### Field Testing

Field testing measures performance in a live environment after deployment, for example: measuring how long requests take from different shoppers. This helps you understand what is happening with your API calls and check for edge cases or other unexpected issues that you missed in laboratory testing.

#### Reports and Dashboards

Use The Account Manager **Technical Timing** tab and **SCAPI** tab to view how your APIs and controllers are operating at scale. This information shows:

- Average response time over time, number of requests, and status codes
- Performance distribution:

  - Drill down to view the performance and behavior of specific APIs, including Custom APIs. For example, look at an API family, such as Shopper Baskets, and drill into endpoints within that API family. Also view and drill into custom APIs, and sort by the most frequently called endpoints to see average response times.

- Trends:
  - Monitor trends over time and after important code changes. For example, overlay data with code changes to evaluate whether your code changes regressed performance.

Helpful questions to ask:

- Did response time increase because I made a code change?
- Did response time increase because people are searching for different things?

#### Code Profiler

To understand and address timing bottlenecks, use the [code profiler](https://developer.salesforce.com/docs/commerce/commerce-api/guide/code-profiler.html).

## Next Steps

- [Secure Your Site](https://developer.salesforce.com/docs/commerce/commerce-api/guide/security.html)

<!-- document id=ce593e1db2013a168d1be67c7199721a21e20b994347443225d169c2ca7eaa6d url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-availability.md -->

Shopper Availability

# Shopper Availability

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-availability/shopper-availability-oas-v1-public.yaml)

## API Overview

Use the Shopper Availability API enables to retrieve inventory availability for products without fetching full product details. This allows independent caching strategies for volatile availability data and stable product data.

Use `/availability` to retrieve availability for products. If the `inventoryIds` parameter is omitted, availability is returned from the site-assigned default inventory list. If `inventoryIds` is provided, availability is returned only from the specified inventory lists.

Caching is provided for the Shopper Availability API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

### Authentication & Authorization

The client requesting the availability information must have access to the Availability resource. The Shopper Availability API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include the relevant scopes in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

### Use Cases

#### Retrieve Product Availability

Use the Shopper Availability API so that a customer can see whether products are in stock. This API returns availability details, including stock levels and inventory status, for up to 24 products per request.

#### Retrieve Availability from Specific Inventory Lists

Use the `inventoryIds` parameter to retrieve availability from specific inventory lists rather than the site-assigned default. This is useful for scenarios such as showing availability at specific store locations or warehouses. You can request availability from up to 5 inventory lists per request.

#### Retrieve Availability for Product Variations

Use the `expand=variations` parameter to retrieve availability for all variants of a master product in a single request. Use the `productId` from each entry in the Shopper Products API `variants` array to look up availability for a specific variant.

### Use Hooks

For details working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

**Version:** 1.4.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-availability/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-availability: scope granting read-access to shopper availability endpoints
    *   Scope sfcc.shopper-standard: standard aggregated scope granting read-access to a curated set of shopper endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-availability: scope granting read-access to shopper availability endpoints
    *   Scope sfcc.shopper-standard: standard aggregated scope granting read-access to a curated set of shopper endpoints
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-availability: scope granting read-access to shopper availability endpoints
    *   Scope sfcc.shopper-standard: standard aggregated scope granting read-access to a curated set of shopper endpoints

## Operations

### GET Returns availability for multiple products.

`GET /organizations/{organizationId}/availability`

Operation ID: `getAvailability`. Security: ShopperToken (sfcc.shopper-availability, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-availability, sfcc.shopper-standard).

Returns availability for multiple products. If `inventoryIds` is omitted, availability is returned from the site-assigned default inventory list. If `inventoryIds` is provided, availability is returned only from the specified inventory lists. The maximum number of product IDs that you can request is 24. The maximum number of inventory list IDs you can request is 5. The `productIds` parameter accepts product IDs for any product type (master, variant, standard, set, or bundle). Products that are offline or not found are silently filtered from the response. To retrieve availability for all variants of a master product, use the `expand=variations` parameter. Use the `productId` from each entry in the Shopper Products API `variants` array to look up availability for a specific variant.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `productIds` (query, array of object, required, style: form, explode: false) The IDs of the requested products (comma-separated, max 24 IDs). If more than 24 IDs are required, split them into multiple parallel requests. Products that are offline or not found are silently filtered from the response.  
    Minimum items: 1. Maximum items: 24.
    
    _Example_
    
    ```
    apple-ipod-shuffle,apple-ipod-nano
    ```
    
    _Example_
    
    ```
    [
      "apple-ipod-shuffle",
      "apple-ipod-nano"
    ]
    ```
    
*   `inventoryIds` (query, array of object, style: form, explode: false) The inventory list IDs for which the availability should be shown (comma-separated, max 5 inventory list IDs). If omitted, availability is returned from the site-assigned default inventory list. If provided, availability is returned only from the specified inventory lists.  
    Minimum items: 1. Maximum items: 5.
    
    _Example_
    
    ```
    Site1InventoryList,Site2InventoryList
    ```
    
    _Example_
    
    ```
    [
      "Site1InventoryList",
      "Site2InventoryList"
    ]
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `expand` (query, array of string, style: form, explode: false) Expand the response to include availability for related products. When `variations` is specified, availability for all variation products of a master product is included. When `set_products` is specified, availability for all products in a product set is included. The parent product's availability is always included alongside the expanded entries. Expansion is single-level only: if a variation is itself a product set, its set products are not further expanded. Other product types (bundles, bundled items, set items) are not expanded. Expanded results are returned flat at the top level of the response array, not nested below their parent product. **Note:** When using `expand=variations`, combine this response with variant data from the Shopper Products API to determine which specific variant attribute combinations (e.g. size=L, color=red) are orderable. Use the `productId` from each entry in the Shopper Products API `variants` array as the key to look up availability for that variant in this response.  
    Items: Allowed values: `variations`, `set_products`. Example: `variations`.
    
    _Example_
    
    ```
    variations,set_products
    ```
    
    _Example_
    
    ```
    [
      "variations",
      "set_products"
    ]
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `AvailabilityResult`.
    
    _Example: GetAvailabilityResponseExample_
    
    ```
    {
      "data": [
        {
          "id": "poodle-collar",
          "inventories": [
            {
              "ats": 100,
              "backorderable": false,
              "id": "site-default-inventory",
              "inStockDate": "2026-06-15T00:00:00.0Z",
              "orderable": true,
              "preorderable": false,
              "stockLevel": 90
            }
          ]
        },
        {
          "id": "poodle-coat",
          "inventories": [
            {
              "id": "site-default-inventory"
            }
          ]
        }
      ],
      "limit": 2,
      "total": 2
    }
    ```
    
    _Example: GetAvailabilityInventoryListsResponseExample_
    
    ```
    {
      "data": [
        {
          "id": "poodle-collar",
          "inventories": [
            {
              "ats": 100,
              "backorderable": false,
              "id": "inventory1",
              "orderable": true,
              "preorderable": false,
              "stockLevel": 90
            },
            {
              "ats": 5,
              "backorderable": false,
              "id": "inventory2",
              "orderable": true,
              "preorderable": true,
              "stockLevel": 5
            }
          ]
        },
        {
          "id": "poodle-coat",
          "inventories": [
            {
              "ats": 7100,
              "backorderable": false,
              "id": "inventory1",
              "orderable": true,
              "preorderable": false,
              "stockLevel": 7090
            },
            {
              "ats": 15,
              "backorderable": false,
              "id": "inventory2",
              "orderable": true,
              "preorderable": true,
              "stockLevel": 15
            }
          ]
        }
      ],
      "limit": 2,
      "total": 2
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetAvailabilityBadRequestResponseExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "Maximum number of product IDs you can request in one call is 24."
    }
    ```
    
    _Example: GetAvailabilityInventoryListsBadRequestResponseExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "Maximum number of inventory list IDs you can request in one call is 5."
    }
    ```
    
    _Example: MalformedSelectorResponseExample_
    
    ```
    {
      "title": "Malformed Selector",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector",
      "detail": "The property selector '(data.(id, inventories.(**))' is malformed.",
      "selector": "(data.(id, inventories.(**))"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    

#### Extension points

*   `sfcc.product.shopper-availability.v1.availability.beforeGET` (before) called before retrieving product availability.
*   `sfcc.product.shopper-availability.v1.availability.modifyGETResponse` (modifyResponse) called to modify the product availability response.

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### InventoryId

The inventory ID.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `Site1InventoryList`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### AvailabilityResult

Result document containing an array of product availability.

*   `limit` (_integer (int32)_, required) The number of returned product entries in the data array.  
    Example: `2`.
*   `data` (_array of Availability_, required) The array of product availability entries. Each entry represents one product (SKU) with available inventory across the requested inventory lists.
*   `total` (_integer (int32)_, required) The total number of distinct product entries in the data array, not individual inventory records.  
    Example: `2`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### Availability

Availability of one product across the requested inventory lists, or the site-assigned default inventory list.

*   `id` (_ProductId_, required)
*   `inventories` (_array of Inventory_, required) The array of inventory information for the product.

### Inventory

Document representing inventory information of the current product for a particular inventory list.

*   `ats` (_number (double)_) The Available To Sell (ATS) of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.ats.max\_threshold'.  
    Example: `15`.
*   `backorderable` (_boolean_) A flag indicating whether the product is backorderable.  
    Example: `true`.
*   `id` (_InventoryId_, required)
*   `inStockDate` (_string (date-time)_) A flag indicating the date when the product will be in stock.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `orderable` (_boolean_) A flag indicating whether at least one of the products is available to sell.  
    Example: `true`.
*   `preorderable` (_boolean_) A flag indicating whether the product is preorderable.  
    Example: `false`.
*   `stockLevel` (_number (double)_) The stock level of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.stock\_level.max\_threshold'.  
    Example: `10`.

<!-- document id=9e102af786c3883ee58cf371b8ea22aaf34afdb1515f0c514c87464216d9bbb5 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-baskets.md -->

Shopper Baskets V1

# Shopper Baskets V1

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-baskets/shopper-baskets-oas-v1-public.yaml)

## API Overview

Use the Shopper Baskets API to create a basket in the B2C Commerce system and populate it with all the data required to ready the basket for checkout.

To create a basket, start with the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=createBasket) endpoint. The endpoint creates the basket in the B2C Commerce system and returns a JSON representation of the basket with a `basketId` property.

If you provide the JSON for a prepopulated basket to the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets?meta=createBasket) endpoint, you can create a basket using a single API request.

You can also create a basket and gradually populate it with data using subsequent API requests that reference the same `basketId`. The gradual approach allows you to validate the input data as you go.

The Shopper Baskets API includes endpoints to populate each part of a basket separately, including:

*   Billing address
*   Customer information
*   Line items
    *   Products
    *   Coupons
    *   Gift certificates
*   Payment methods
*   Price books
*   Shipments
*   Taxation (for items and the basket itself)

In addition to creating a basket, the main `/baskets` resource offers endpoints to get, transfer, merge, and delete baskets, depending on the HTTP method that you use and the parameters that you supply. These endpoints can you help you handle a variety of complex scenarios, such as when a user starts shopping as a guest and then logs in before checkout.

You can also use the main `/baskets` resource to add custom properties to your basket, prefixed with `c_` (example: `c_faxNumber`).

When your basket is fully populated, you can use its `basketId` property to create an order with the [Shopper Orders API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary).

For more detail on building baskets, see [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html).

### Authentication & Authorization

The client requesting the basket information must have access to the `/baskets` resource. The Shopper Baskets API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

You must include `sfcc.shopper-baskets-orders` or `sfcc.shopper-baskets-orders.rw` in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

The following resources require an Account Manager OAuth token with a client ID:

*   `/baskets/{basketId}/taxes`
*   `/baskets/{basketId}/items/{itemId}/taxes`
*   `/baskets/{basketId}/price-books`

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)

#### Caching

Responses from this API are not cached. Basket data is stateful and unique to each shopper session.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Create a Basket

Create a new basket for the shopper.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1/organizations/{organizationId}/baskets?siteId=RefArch" \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Basket Calculation

Unless you’re using [hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html), each modification to a basket triggers the following calculations:

1.  Calculate product prices:
    *   Iterate through the product line items and determine the base price of each using its price model. If multiple price books apply to a product, the lowest price is used.
    *   Calculate product option line item prices using the product option model.
    *   For bonus products, check dependent adjustments in the basket to determine the price.
2.  Iterate through the gift certificate line items and calculate the price of each by multiplying the base price by the quantity.
3.  Recalculate for all promotions, adding and removing them as appropriate.
4.  Apply product-specific shipping costs.
5.  Calculate the total shipping cost.
6.  Recalculate for all promotions, adding and removing them as appropriate.
7.  Calculate prices for products added by the promotion engine.
8.  Calculate taxes using line item tax class codes.
    *   For internal tax mode, use the tax tables.
    *   For external tax mode, use the tax rates returned by the tax API endpoints.
9.  Calculate the order’s net, tax, and gross totals by adding up the line totals.

### External Taxation

The B2C Commerce API calculates taxes internally using tax tables. If you want to integrate with a third-party tax provider, or calculate tax on your own, you can use the external taxation feature to add a taxation rate and optional taxation value. When setting a taxation rate, the taxation is calculated for this specific rate. If you pass a value, this value is used as taxation value, as well, without recalculation. To use this feature, set the `taxMode` parameter to `external` when creating the basket.

When using external taxation, you must set a tax rate either in one request to the `/baskets/{basketId}/taxes` or with separate requests for each line item, using `/baskets/{basketId}/items/{lineItemId}/taxes`.

If the tax mode of a basket is set to `external`, a tax item is required for all line items even for zero-tax items to avoid oversights.

#### External Taxation with Hooks Enabled

To use external tax calculation with [hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html), use the following API methods in the [Calculate Hook](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#calculate-hook):

*   `dw.order.LineItemCtnr#isExternallyTaxed`: Returns true if the basket was created with `taxMode = external`
*   `dw.order.TaxMgr#applyExternalTax`: Applies externally set tax rates to the given basket. Only use when `dw.order.LineItemCtnr#isExternallyTaxed` returns true.

The following example shows an implementation of external tax calculation with hooks enabled in the [Calculate Hook](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#calculate-hook):

```javascript
exports.calculate = function (basket) {
   if ( basket.isExternallyTaxed() )
   {
      TaxMgr.applyExternalTaxation( basket ); // apply the external tax calculation based on the tax rates set by the SCAPI external taxation APIs
   }
   else
   {
      // calculation with tax tables or customization
   }
}
```

### Related APIs

*   [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) — Place an order from a completed basket.
*   [Shopper Payments](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments?meta=Summary) — Retrieve payment method configuration for checkout.

**Version:** 1.12.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `RegisteredShopperToken` (oauth2) `RegisteredShopperToken` is a child of the `ShopperToken` security scheme and restricts access to a **registered (authenticated) shopper**. Access is only granted to a shopper token that represents a registered shopper; a guest shopper token is rejected. Endpoints secured with `RegisteredShopperToken` operate on identity-bound resources of a registered shopper, such as their addresses, payment instruments, password, or saved product lists. Besides these endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `RegisteredShopperToken`. To get a `RegisteredShopperToken`, the shopper must authenticate with SLAS (for example, through the authorization code flow or the [login endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer)). For details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `ShopperTokenTaob` (oauth2) `ShopperTokenTaob` (Taob = trusted agent on behalf) is a child of the `ShopperToken` security scheme and extends the functionality of `ShopperToken` for specific use cases. A token of type `ShopperTokenTaob` allows you to access Shopper API endpoints, including OCAPI and Salesforce Commerce API for headless applications. Besides endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `ShopperTokenTaob`. To get a `ShopperTokenTaob` token, a `Taob` session needs to be created first (see [getTrustedAgentAuthorizationToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=getTrustedAgentAuthorizationToken)). Afterwards the `ShopperTokenTaob` token can be gained (see [getTrustedAgentAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=getTrustedAgentAccessToken)). For more information regarding the `Taob` flow see also [Trusted Agent Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html).
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/trusted-agent/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints

## Operations

### POST Create a new basket.

`POST /organizations/{organizationId}/baskets`

Operation ID: `createBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Creates a new basket.

The created basket is initialized with default values. Optional JSON data provided in the request body is populated into the created basket. It can be updated with other endpoints offered by the Shopper Baskets API.

Each shopper is limited to one open basket at a time. Attempting to create a second basket for the same customer will result in a 400 Bad Request error with the message: "Customer Baskets Quota Exceeded". A basket is considered "open" upon creation and remains in this state until it is either converted into an order or explicitly deleted. For implementation best practices, see [Hybrid Storefront Best Practices for Working with Baskets](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html#hybrid-storefront-best-practices-for-working-with-baskets).

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `taxMode` (query, string)
    
    Determines how taxes are calculated.
    
    The default value is `internal` where the tax calculation is done automatically based on internal tax tables. Setting `taxMode` to `external` allows manual modification of the tax rates and values. External tax data is mandatory for product line items, option line items, shipping line items, coupon line items, and bonus discount line item. Gift certificate line items are optional and use zero tax rate by default, which can be overwritten. Price adjustments cannot be set because they are either calculated or inherited. Depending on the type, the tax rate is either obtained from the related line item or computed as a prorate of the basket.
    
      
    Allowed values: `internal`, `external`. Default: `internal`. Example: `external`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Basket`.

_Example: PostBasketBody_

```
{
  "customerInfo": {
    "email": "shopper@salesforce-test.com",
    "customerNo": "000000001"
  },
  "billingAddress": {
    "firstName": "Stephanie",
    "lastName": "Miller",
    "address1": "104 Presidential Way",
    "city": "Woburn",
    "postalCode": "01801",
    "stateCode": "MA",
    "countryCode": "US"
  },
  "shipments": [
    {
      "shippingMethod": {
        "id": "001"
      },
      "shippingAddress": {
        "firstName": "Agustin",
        "lastName": "Estes",
        "address1": "4162  Turkey Pen Road",
        "city": "New York",
        "postalCode": "10016",
        "stateCode": "NY",
        "countryCode": "US"
      }
    }
  ],
  "paymentInstruments": [
    {
      "paymentMethodId": "CREDIT_CARD",
      "paymentCard": {
        "cardType": "Visa"
      }
    }
  ],
  "couponItems": [
    {
      "code": "5ties"
    }
  ],
  "productItems": [
    {
      "productId": "green-umbrella",
      "quantity": 3
    }
  ]
}
```

#### Responses

*   **200** The initialized basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketsPostSuccess_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the provided payment method is invalid or not applicable.
    *   the customerId URL parameter does not match the verified customer represented by the JSON Web Token (JWT).
    *   a new basket cannot be created because the maximum number of baskets per customer would be exceeded.
    *   the same shipment ID appeared twice in the body.
    *   the coupon number is not provided.
    *   a fixed price adjustment was added at order level which is disallowed.
    *   a promotion ID was used twice, while attempting to add a price adjustment.
    *   a system promotion ID was used as a manual promotion ID, while attempting to add a price adjustment.
    *   more than one hundred price adjustments would have been created.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'."
    }
    ```
    
    _Example: CustomerBasketQuotaExceededException_
    
    ```
    {
      "title": "Customer Baskets Quota Exceeded",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-baskets-quota-exceeded",
      "detail": "The maximum number of baskets per customer was exceeded. Please reuse or delete one of the existing baskets (40e91e04aba6e42a6836f79308).",
      "basketIds": "40e91e04aba6e42a6836f79308"
    }
    ```
    
*   **404** Returned if the shipment with the given shipment ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ShipmentNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/shipment-not-found",
      "title": "Shipment Not Found",
      "detail": "The shipping method with ID '123' is unknown or can't be applied to the basket."
    }
    ```
    

### POST Transfer an existing basket.

`POST /organizations/{organizationId}/baskets/actions/transfer`

Operation ID: `transferBasket`. Security: RegisteredShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Transfer the previous shopper's basket to the current shopper by updating the basket's owner. No other values change. You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token.

This endpoint provides different methods for handling the scenario in which both a previous guest shopper and the current registered shopper have an active basket attached, and utilizes the `merge` parameter as follows:

*   `true` (recommended): Triggers a merge hook for graceful handling and prevents 409 status returns. For more information, refer to the `merge` parameter documentation.
*   `false`: Either overrides the basket of the current registered shopper or returns a 409 response, and allows you to choose between the options explained below.

If you call the endpoint with `merge=false` and the current shopper has an active basket, you have two options using the `overrideExisting` parameter. Setting it to `true` deletes the registered user's basket, while setting it to `false` returns a `BasketTransferException` (HTTP status 409), after which you can choose how to proceed:

*   Keep the current shopper's active basket.
*   Merge the previous and current shoppers' baskets by calling the `baskets/actions/merge` endpoint.
*   Force the transfer by calling the `baskets/actions/transfer` endpoint again, with the parameter `overrideExisting=true`. Forcing the transfer deletes the current shopper's active basket.

A successful response provides the transferred (and merged) current basket. However, if neither the previous nor current shopper had an active basket, a 204 (No Content) response is returned.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `overrideExisting` (query, boolean)
    
    If the current shopper has no active basket, this parameter is ignored. If the current shopper has an active basket, this parameter controls the behavior:
    
    *   `false` (default): Return a BasketTransferException (HTTP status 409). The basket owner doesn't change.
    *   `true`: Force the transfer by deleting the current shopper's active basket and making the current shopper the owner of the previous shopper's basket. Returns the transferred basket (HTTP status 200).
    
      
    Default: `false`. Example: `false`.
*   `merge` (query, boolean)
    
    This parameter controls the behavior: - `false` (default): Transfers the basket or returns a 409 response with the appropriate message (taking `overrideExisting` in consideration). - `true`: (recommended): Executes the dw.order.mergeBasket hook if at least one basket exists.
    
    The hook dw.order.mergeBasket default implementation merges a source basket into the current basket. This behavior can be customized, as shown in this [sample implementation](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f).
    
    There are four possible use cases:
    
    a) Guest basket and registered basket exist The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called with the source basket (former registered shopper basket) and the transferred current basket (former guest basket).
    
    b) Guest basket exists but no registered basket exists The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called without the source basket (null passed to the hook) and the transferred current basket (former guest basket).
    
    c) No guest basket exists but a registered basket exists The registered basket is retained. The hook dw.order.mergeBasket is called with the retained current basket but without the source basket (null passed to the hook).
    
    d) Neither basket exists The hook dw.order.mergeBasket is not called.
    
    The API returns the current basket (after executing dw.order.mergeBasket).
    
      
    Default: `false`. Example: `false`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** The current basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **204** The operation was successful. No current basket was returned because neither the previous nor current shopper had an active basket attached that could be transferred.
*   **403** The call returns this error if no SLAS token for a registered shopper is available.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenMissingPrevCustomerInfo_
    
    ```
    {
      "title": "Forbidden",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "detail": "Your access-token is valid, but it contains no previous customer to process this action."
    }
    ```
    
*   **409**
    
    The call returns this response when the `merge` request parameter is set to `false` and one of the following cases applies:
    
    *   The previous shopper has no active basket.
    *   The current shopper has an active basket and the `overrideExisting` query parameter is set to `false` (default value).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: SourceBasketException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/no-source-basket-exception",
      "title": "Conflict",
      "detail": "The previous customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has no active basket."
    }
    ```
    
    _Example: BasketTransferException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-transfer-basket-already-exists-exception",
      "title": "Conflict",
      "detail": "The current customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has an active basket."
    }
    ```
    

### POST Merge baskets.

`POST /organizations/{organizationId}/baskets/actions/merge`

Operation ID: `mergeBasket`. Security: RegisteredShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

( DEPRECATED ) Instead of using this endpoint, we recommend using the `/baskets/actions/transfer` endpoint with the `merge=true` parameter, because the transfer endpoint offers greater customization by invoking a hook, allowing for adjustments if the default implementation does not process the merge as expected.

Merge data from the previous shopper's basket into the current shopper's active basket and delete the previous shopper's basket. This endpoint doesn't merge Personally Identifiable Information (PII). You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token. After the merge, all basket amounts are recalculated and totaled, including lookups for prices, taxes, shipping, and promotions, unless hooks are enabled.

The following information is merged:

*   custom attributes on the basket and on all copied records
*   product items
*   gift certificate items
*   coupon items
*   shipments
*   ad-hoc price adjustments

To control the merging of products that exist in both baskets, use the `productItemMergeMode` parameter. By default, the higher of the two basket quantities is used for each product. Products in both baskets are considered to be the same when all of the following values match (if one product doesn't have a value, the other product is a match only if it also doesn't have that value):

*   shipment
*   productId
*   option values
*   wishlist reference
*   inventory list id
*   gift flag & message
*   ad-hoc price adjustments

If any of the listed values don't match, then the item in the previous shopper's basket is copied to a new line item in the current shopper's basket. If the listed values all match, but the matching products have different values for any custom attribute, the merged line item keeps the custom attribute value from the current shopper's basket.

A success response contains the current shopper's active basket. The previous guest shopper's active basket is deleted.

If the current shopper doesn't have an active basket, and the createDestinationBasket request parameter is false, then the merge request returns a BasketMergeException (HTTP status 409). You can proceed with one of these options:

*   Transfer the previous shopper's active basket to the current logged-in shopper by calling the `baskets/transfer` endpoint.
*   Force the merge by calling the `baskets/merge` endpoint again, with the parameter `createDestinationBasket=true`. Forcing the merge creates a new basket for the current shopper and copies information from the previous shopper's basket into it. Because the merge doesn't copy all basket data, a forced merge is not the same as a transfer. For example, the new basket doesn't contain any Personally Identifiable Information (PII) from the previous basket.

#### before merge

| Previous Shopper's Basket, SKU: Quantity, Custom Attributes | Current Shopper's Basket, SKU: Quantity, Custom Attributes |
| --- | --- |
| SKU\_A: 5   SKU\_B: 3   SKU\_C: 4   c\_customAttr\_1: 'ABC'   c\_customAttr\_2: 'DEF' | SKU\_A: 2   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_3: 'XYZ' |

#### after merge - (previous shopper's basket is deleted)

| productItemMergeMode | Current Shopper's Basket - SKU: Quantity, Custom Attributes |
| --- | --- |
| sum\_quantities | SKU\_A: 7   SKU\_B: 3   SKU\_C: 4   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |
| higher\_quantity | SKU\_A: 5   SKU\_B: 3   SKU\_C: 4   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |
| saved\_quantity | SKU\_A: 2   SKU\_B: 3   SKU\_C: 4   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |
| separate\_item | SKU\_A: 5   SKU\_B: 3   SKU\_C: 4   SKU\_A: 2   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `createDestinationBasket` (query, boolean)
    
    If the current shopper has an active basket, this parameter is ignored. If the current shopper has no active basket, this parameter controls the behavior:
    
    *   `false` (default): Return a BasketMergeException (HTTP status 409).
    *   `true`: Force the merge by creating a basket for the current shopper and copying information from the previous shopper's basket into it. Return success (HTTP status 200).
    
      
    Default: `false`.
*   `productItemMergeMode` (query, string)
    
    This parameter controls the quantity calculation for products that exist in both baskets.
    
    *   higher\_quantity (default): Compare the product's quantities in each basket, and use the higher value.
    *   sum\_quantities: Use the sum of the product's quantities from both baskets.
    *   saved\_quantity: Use the product's quantity in the current shopper's active basket. Ignore the quantity from the previous shopper's basket.
    *   separate\_item: Add a separate product item to the current shopper's basket for the quantity in the previous shopper's basket.
    
      
    Allowed values: `higher_quantity`, `sum_quantities`, `saved_quantity`, `separate_item`. Default: `higher_quantity`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** The current shopper's active basket, including items merged from the previous shopper's basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **403** The call returns this error if no SLAS token for a registered shopper is available.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenMissingPrevCustomerInfo: same as POST /organizations/{organizationId}/baskets/actions/transfer 403 response._
    
*   **409**
    
    The call returns this response in either of these cases:
    
    *   The previous shopper has no active basket.
    *   The current shopper has no active basket and the `createDestinationBasket` query parameter was `false` (default value).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SourceBasketException: same as POST /organizations/{organizationId}/baskets/actions/transfer 409 response._
    
    _Example: BasketMergeException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-merge-no-current-basket-exception",
      "title": "Conflict",
      "detail": "The current customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has no active basket."
    }
    ```
    

### GET Retrieve an existing basket.

`GET /organizations/{organizationId}/baskets/{basketId}`

Operation ID: `getBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders, sfcc.shopper-standard).

Gets a basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the retrieved basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example GetBasket: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Delete a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}`

Operation ID: `deleteBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **204** Success, without a body.
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}`

Operation ID: `updateBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a basket. Only the currency of the basket, source code, the custom properties of the basket, and the shipping items will be considered.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Basket`.

_Example: BasketPatch_

```
{
  "c_textValue": "oak"
}
```

#### Responses

*   **200** Success, the response body contains the updated basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "7800e0f611dac6caf77afb9df9",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:53:30.993Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:53:35.747Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "2b76b8644eb6da43e7e223b48d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "43c38652bc3844e14cd482ff28",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "b4ff13039bc7abd1b9d933b871",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "193e99bc1205b870cebd36d970",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "ac7a3b62dc1df8de898d7a2141",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8,
      "c_textValue": "oak"
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the basket cannot be updated because the requested currency is not supported by the site.
    *   the given shipping item ID is null or empty.
    *   a few shipping items with the same item ID are provided.
    *   the provided code is not currently active.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the shipping item with the given item ID is unknown for the basket.
    *   the provided code was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Designate a basket as an agent basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/agent`

Operation ID: `updateAsAgentBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Marks a basket as an agent basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Responses

*   **200** Success, the response body contains basket that is set as an agent basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketPutAgent_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": true,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** Marking this basket as an agent basket would exceed the open agent basket limit for the basket customer.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomerInfoJwtMismatch: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add a billing address to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/billing-address`

Operation ID: `updateBillingAddressForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets the billing address of a basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `useAsShipping` (query, boolean) When true, the address is also used as the shipping address.
    
    _Example_
    
    ```
    true
    ```
    
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `OrderAddress`.

_Example: BillingAddressPut_

```
{
  "firstName": "Stephanie",
  "lastName": "Miller",
  "address1": "385  Prospect Valley Road",
  "city": "Woburn",
  "postalCode": "01801",
  "stateCode": "MA",
  "countryCode": "US"
}
```

#### Responses

*   **200** Success, the response body contains basket with the added billing address.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BillingAddress_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "385  Prospect Valley Road",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "7800e0f611dac6caf77afb9df9",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:53:30.993Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:53:35.747Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "2b76b8644eb6da43e7e223b48d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "43c38652bc3844e14cd482ff28",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "b4ff13039bc7abd1b9d933b871",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "193e99bc1205b870cebd36d970",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "ac7a3b62dc1df8de898d7a2141",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add a coupon to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/coupons`

Operation ID: `addCouponToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a coupon to an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CouponItem`.

_Example: CouponCodePost_

```
{
  "code": "10_percent_off"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added coupon.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: CouponCodePost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        },
        {
          "code": "10_percent_off",
          "couponItemId": "9372d0f511dac8caf77afc4kj2",
          "statusCode": "applied",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible Reasons:
    
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the coupon number is not provided.
    *   the coupon code specified is invalid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a coupon from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/coupons/{couponItemId}`

Operation ID: `removeCouponFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a coupon from the basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `couponItemId` (path, CouponItemId, required) The ID of the coupon item.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted coupon.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example Basket: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the couponItemId URL parameter does not match any coupon item ID in the basket.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add shopper information to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/customer`

Operation ID: `updateCustomerForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets customer information for an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerInfo`.

_Example: BillingAddressPut_

```
{
  "email": "shopperUpdate@salesforce-test.com"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added customer information.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BillingAddress_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopperUpdate@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the customer cannot be set to the basket because the max number of baskets per customer would be exceeded.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the customer with the given customer number is unknown.
    *   the basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add a gift certificate to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items`

Operation ID: `addGiftCertificateItemToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a gift certificate item to an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `GiftCertificateItem`.

_Example: GiftCertificateItemPost_

```
{
  "amount": 1,
  "recipientEmail": "miller@salesforce-test.com",
  "shipmentId": "me"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added gift certificate.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: GiftCertPost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopperUpdate@salesforce-test.com"
      },
      "giftCertificateItems": [
        {
          "amount": 2,
          "giftCertificateItemId": "83726a8351540534af93f3b15f",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** The gift certificate item amount is negative.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the shipment with the given shipment ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a gift certificate from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}`

Operation ID: `removeGiftCertificateItemFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Deletes a gift certificate item from an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `giftCertificateItemId` (path, GiftCertificateItemId, required) the ID of the gift certificate item to be updated.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted gift certificate.
    
    Media type: `application/json`. Schema: `Basket`.
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the gift certificate item with the given gift certificate item ID is unknown.

### PATCH Update gift certificate information for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}`

Operation ID: `updateGiftCertificateItemInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a gift certificate item of an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `giftCertificateItemId` (path, GiftCertificateItemId, required) the ID of the gift certificate item to be updated.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `GiftCertificateItem`.

_Example: GiftCertificateItemPost_

```
{
  "amount": 1,
  "recipientEmail": "miller@salesforce-test.com"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated gift certificate.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: GiftCertPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopperUpdate@salesforce-test.com"
      },
      "giftCertificateItems": [
        {
          "amount": 1,
          "giftCertificateItemId": "83726a8351540534af93f3b15f",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** The gift certificate item amount is negative.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the gift certificate item with the given gift certificate item ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add an item to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/items`

Operation ID: `addItemToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds new items to a basket. The added items are associated with the specified shipment. If no shipment id is specified, the added items are associated with the default shipment. Considered values from the request body, for each item are:

*   productId: a valid product ID. This is the ID of the product to be added to the basket. If the product is already in the basket, the API either increments the quantity of the existing product line item or creates a new product line item, based on the site preference 'Add Product Behavior'. For option products and product bundles containing variation masters, the API creates a new product line item regardless of the site preference.
*   shipmentId: a valid shipment ID (optional). This is the ID of the shipment in which the product item is created.
*   quantity: a number between 0.01 and 999. This is the quantity of the product to order.
*   inventoryId: a valid inventory ID (optional). This is the ID of the inventory from which the item is allocated.
*   bonusDiscountLineItemId: a valid bonus discount line item ID (optional). This is the ID of the bonus discount line item for which the added product is a selected bonus product.
*   optionItems/optionValueId: a valid option value ID. This is an option value for an option item of an option product. This is only possible if the product item is an option product. To set option values, you must specify a collection of option items in the optionItems property. These option items must contain optionId and optionValueId. Also, the values you specify must be valid for the option product that this product item represents. Otherwise, the server throws an InvalidProductOptionItemException or an InvalidProductOptionValueItemException.
*   custom properties in the form c\_<CUSTOM\_NAME>: the custom property must correspond to a custom attribute (<CUSTOM\_NAME>) defined for ProductLineItem. The value of this property must be valid for the type of custom attribute defined for ProductLineItem.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `array of ProductItem`.

Array of `ProductItem`.

_Example: ItemPost_

```
[
  {
    "productId": "green-bag",
    "quantity": 1
  }
]
```

#### Responses

*   **200** Success, the response body contains the basket with the added items.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   the given product ID is null or invalid.
    *   the product with the given product ID is unknown, offline or not assigned to site catalog or the given product item quantity is null or invalid.
    *   a null quantity value.
    *   the requested product quantity is not available.
    *   the product cannot be added to the basket because of its type.
    *   an option with the specified option ID is unknown.
    *   an option with the specified option value ID is unknown.
    *   the maximum allowed number of products added to the basket, has been exceeded.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the provided bonus discount line item ID is not present in the current basket.
    *   the quantity of the product to be added will result in the number of selected bonus choice products to exceed the amount that the user is permitted to select.
    *   the selected bonus product is not an applicable product for the bonus discount line item provided. body: application/problem+json: type: ErrorResponse examples: dataTypes.ErrorResponse: !include exchange\_modules/893f605e-10e2-423a-bdb4-f952f56eb6d8/checkout-data-types/2.0.6/examples/error/bad-request-example.raml
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the basket does not contain a shipment with the given shipment ID.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a basket item.

`PATCH /organizations/{organizationId}/baskets/{basketId}/items`

Operation ID: `updateItemsInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates multiple items in a basket. This behaviour matches that of updating a single item, but the body contains an array of ProductItems to be updated that are identified by `itemId`. The items to update can include bundled product items, although the kind of update supported for bundled product items is limited to `productId`, `gift`, `giftMessage` and custom properties. The following values in the request body are considered by the server:

*   `itemId` (mandatory): identifies an item to be updated.
*   `productId`: a valid product ID. The purpose of this value is to change the variation of a variation product.
*   `shipmentId`: a valid shipment ID. The purpose of this value is to move a product item to another shipment.
*   `quantity`: a number between 0 and 999. The purpose of this value is to change the quantity of the product item. If the quantity is 0, the product item is removed.
*   `optionItems`/`optionValueId`: a valid option value ID. The purpose of this value is to exchange an option value for an option item of an option product. This is only possible if the product item is an option product. To change option values, a collection of the option items to be changed must be provided in the property `optionItems`. Those `optionItems` must contain `optionId` and `optionValueId`. The provided values must be valid for the option product that this product item represents. Otherwise, `InvalidProductOptionItemException` or `InvalidProductOptionValueItemException` is thrown.
*   custom properties `c_<CUSTOM_NAME>`: a value corresponding to the type defined for custom attribute `<CUSTOM_NAME>` of the ProductLineItem. The purpose of this value is to add or change the value of a custom attribute defined for the ProductLineItem.
*   `gift`: a boolean value that specifies whether the item is a gift.
*   `giftMessage`: a message to include with the gift.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `array of ProductItem`.

Array of `ProductItem`.

_Example: ItemsPatch_

```
[
  {
    "itemId": "051e908cca031ebf8ee80cbb0a",
    "productId": "green-bag",
    "quantity": 1
  },
  {
    "itemId": "078a492cca031ebf8ee80739ab",
    "optionItems": [
      {
        "optionId": "Option1",
        "optionValueId": "ValueA"
      }
    ],
    "quantity": 1
  }
]
```

#### Responses

*   **200** Success, the response body contains the basket with the updated item.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   no product item with a given item ID was found for the basket.
    *   the product with the given product ID in the request body is invalid.
    *   a null quantity value.
    *   an option with a specified option ID is unknown.
    *   an option with a specified option value ID is unknown.
    *   the given shipment ID is invalid.
    *   the customer assigned to the basket does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** Possible reasons: basket not found

### DELETE Remove an item from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/items/{itemId}`

Operation ID: `removeItemFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a product item from the basket.

#### Parameters

*   `itemId` (path, ItemId, required) The ID of the item to be updated.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted item.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update an item in a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/items/{itemId}`

Operation ID: `updateItemInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Possible reasons:

*   no product item with given item ID was found for the basket.
*   the product with the given product ID in the request body is invalid.
*   a null quantity value.
*   an option with the specified option id is unknown.
*   an option with the specified option value id is unknown.
*   the given shipment ID is invalid.
*   the customer assigned to the basket does not. match the verified customer represented by the JWT token.

#### Parameters

*   `itemId` (path, ItemId, required) The ID of the item to be updated.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ProductItem`.

_Example: ItemPatch_

```
{
  "quantity": 1
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated item.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ItemPatchSuccess_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 10,
      "adjustedShippingTotalTax": 0.4,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "7800e0f611dac6caf77afb9df9",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:53:30.993Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:58:39.498Z",
      "merchandizeTotalTax": 10,
      "orderTotal": 218.38,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "2b76b8644eb6da43e7e223b48d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 10,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "43c38652bc3844e14cd482ff28",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "b4ff13039bc7abd1b9d933b871",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATre",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 1,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 199.99,
          "priceAfterItemDiscount": 199.99,
          "priceAfterOrderDiscount": 199.99,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 1,
          "shipmentId": "me",
          "tax": 10,
          "taxBasis": 199.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 199.99,
      "productTotal": 199.99,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 10,
          "adjustedShippingTotalTax": 0.4,
          "gift": false,
          "merchandizeTotalTax": 10,
          "productSubTotal": 199.99,
          "productTotal": 199.99,
          "shipmentId": "me",
          "shipmentTotal": 218.38,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "193e99bc1205b870cebd36d970",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 7.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 7.99,
          "shippingTotalTax": 0.4,
          "taxTotal": 10.4
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.4,
          "basePrice": 7.99,
          "itemId": "ac7a3b62dc1df8de898d7a2141",
          "itemText": "Shipping",
          "price": 7.99,
          "priceAfterItemDiscount": 7.99,
          "shipmentId": "me",
          "tax": 0.4,
          "taxBasis": 7.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 7.99,
      "shippingTotalTax": 0.4,
      "taxation": "net",
      "taxTotal": 10.4
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   no product item with given item ID was found for the basket.
    *   the product with the given product ID in the request body is invalid.
    *   a null quantity value.
    *   an option with the specified option id is unknown.
    *   an option with the specified option value id is unknown.
    *   the given shipment ID is invalid.
    *   the customer assigned to the basket does not. match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   a shipment with it's given ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add taxation information for a basket item.

`PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes`

Operation ID: `addTaxesForBasketItem`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw).

This method allows you to apply external taxation data to an existing basket to be able to pass tax rates and optional values for a specific taxable line item. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `itemId` (path, ItemId, required) The ID of the item to be updated.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `TaxItems`.

_Example: BasketItemTaxPut_

```
{
  "taxItems": [
    {
      "id": "DE_7",
      "rate": 0.07,
      "value": 13.99
    },
    {
      "id": "DE_19",
      "rate": 0.19
    }
  ]
}
```

#### Responses

*   **204** Success, without body.
*   **404**
    
    Possible reasons:
    
    *   The basket with the given basket ID is unknown.
    *   The item with the given item ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    
*   **409**
    
    Possible Reasons:
    
    *   The tax mode of the referenced basket is not set to EXTERNAL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnsupportedRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-request-if-scapi-hooks-enabled",
      "title": "Unsupported Request If SCAPI Hooks Enabled",
      "detail": "You can't call this endpoint because Salesforce Commerce API hook execution is enabled."
    }
    ```
    

### POST Add a payment instrument to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/payment-instruments`

Operation ID: `addPaymentInstrumentToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a payment instrument to a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `BasketPaymentInstrumentRequest`.

_Example: PaymentInstrumentPost_

```
{
  "amount": 1,
  "paymentCard": {
    "expirationYear": 1990,
    "expirationMonth": 7,
    "validFromMonth": 8,
    "validFromYear": 2007,
    "issueNumber": "i117",
    "maskedNumber": "*********1234",
    "holder": "Miller",
    "cardType": "Visa"
  },
  "paymentMethodId": "CREDIT_CARD"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added payment instrument.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   the provided payment method is invalid or not applicable.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a payment instrument from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/payment-instruments/{paymentInstrumentId}`

Operation ID: `removePaymentInstrumentFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a payment instrument of a basket.

#### Parameters

*   `paymentInstrumentId` (path, PaymentInstrumentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted payment instrument.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the payment instrument with the given basket payment instrument ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a payment instrument for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/payment-instruments/{paymentInstrumentId}`

Operation ID: `updatePaymentInstrumentInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates payment instrument of an existing basket.

#### Parameters

*   `paymentInstrumentId` (path, PaymentInstrumentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `OrderPaymentInstrument`.

_Example: PaymentInstrumentPatch_

```
{
  "amount": 0,
  "paymentCard": {
    "holder": "Miller",
    "cardType": "Visa"
  },
  "paymentMethodId": "CREDIT_CARD"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated payment instrument.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: PaymentInstrumentPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false,
            "holder": "Miller"
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the provided payment method is invalid or not applicable.
    *   the basket payment intsrument with the given id is already permanently masked.
    *   The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the payment instrument item with the given payment instrument ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### GET Retrieve payment instruments for a basket.

`GET /organizations/{organizationId}/baskets/{basketId}/payment-methods`

Operation ID: `getPaymentMethodsForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders, sfcc.shopper-standard).

Gets applicable payment methods for an existing basket considering the open payment amount only.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the applicable payment methods for the basket.
    
    Media type: `application/json`. Schema: `PaymentMethodResult`.
    
    _Example: PaymentMethodsGet_
    
    ```
    {
      "applicablePaymentMethods": [
        {
          "id": "GIFT_CERTIFICATE",
          "name": "Gift Certificate",
          "paymentProcessorId": "BASIC_GIFT_CERTIFICATE"
        },
        {
          "cards": [
            {
              "cardType": "Visa",
              "checksumVerificationEnabled": true,
              "name": "Visa",
              "numberLengths": [
                "13",
                "16"
              ],
              "numberPrefixes": [
                "4"
              ]
            },
            {
              "cardType": "Amex",
              "checksumVerificationEnabled": true,
              "name": "American Express",
              "numberLengths": [
                "15"
              ],
              "numberPrefixes": [
                "34",
                "37"
              ]
            },
            {
              "cardType": "Master Card",
              "checksumVerificationEnabled": true,
              "name": "MasterCard",
              "numberLengths": [
                "16"
              ],
              "numberPrefixes": [
                "51-55"
              ]
            },
            {
              "cardType": "Discover",
              "checksumVerificationEnabled": true,
              "name": "Discover",
              "numberLengths": [
                "16"
              ],
              "numberPrefixes": [
                "6011",
                "622126-622925",
                "644-649",
                "65"
              ]
            }
          ],
          "id": "CREDIT_CARD",
          "name": "Credit Card",
          "paymentProcessorId": "BASIC_CREDIT"
        },
        {
          "id": "PayPal",
          "name": "Pay Pal",
          "paymentProcessorId": "PAYPAL_EXPRESS"
        },
        {
          "id": "BML",
          "name": "Bill Me Later",
          "paymentProcessorId": "CYBERSOURCE_BML"
        }
      ]
    }
    ```
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add a price adjustment to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/price-adjustments`

Operation ID: `addPriceAdjustmentToBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a custom manual price adjustment to the basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PriceAdjustmentRequest`.

_Example: PriceAdjustmentPost_

```
{
  "discount": {
    "value": 5,
    "type": "percentage"
  },
  "itemText": "MyOrderAdjustment",
  "level": "order",
  "promotionId": "manual adjustment"
}
```

#### Responses

*   **200** Success, the response body contains the basket with added price adjustment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: PriceAdjustmentPost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 28.45,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 0.05,
            "percentage": 5,
            "type": "percentage"
          },
          "createdBy": "testAgent",
          "creationDate": "2015-05-25T09:13:10.942Z",
          "custom": true,
          "itemText": "MyOrderAdjustment",
          "manual": true,
          "price": -30,
          "promotionId": "manual adjustment",
          "priceAdjustmentId": "cdzoAiWbOmbiUaaadlfSpMDgNw"
        }
      ],
      "orderTotal": 615.21,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 569.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 569.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 569.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   a fixed price adjustment was already created for the given level.
    *   a fixed price adjustment was added at `order` level.
    *   a promotion ID was used twice.
    *   a system promotion ID was used as a manual promotion ID.
    *   more than one hundred price adjustments would have been created.
    *   the price adjustment limit had exceeded.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a price adjustment from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/price-adjustments/{priceAdjustmentId}`

Operation ID: `removePriceAdjustmentFromBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a custom manual price adjustment from the basket.

#### Parameters

*   `priceAdjustmentId` (path, PriceAdjustmentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Responses

*   **200** Success, the response body contains the basket without the deleted price adjustment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The priceAdjustmentId is missing, empty or whitespace.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a price adjustment for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/price-adjustments/{priceAdjustmentId}`

Operation ID: `updatePriceAdjustmentInBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a custom manual price adjustment on the basket. Only the following path values are considered for the update; all other attributes are ignored.

*   `discount`
*   `itemText`
*   `reasonCode`
*   `custom properties` The discount `type` of a price adjustment cannot be updated and therefore, the value of the existing type must be passed. For an adjustment of type `percentage`, the `percentage` attribute is mandatory. For adjustments of type `amount` and `fixed_price`, the `amount` attribute is mandatory.

#### Parameters

*   `priceAdjustmentId` (path, PriceAdjustmentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PriceAdjustment`.

_Example: PriceAdjustmentPatch_

```
{
  "appliedDiscount": {
    "amount": 15,
    "type": "amount"
  },
  "itemText": "AgentOrderAdjustment",
  "reasonCode": "override manual promo"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated price adjustment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: PriceAdjustmentPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 15,
            "type": "amount"
          },
          "createdBy": "testWapiAgent",
          "creationDate": "2017-03-14T09:15:35.543Z",
          "custom": true,
          "itemText": "MyOrderAdjustment",
          "lastModified": "2017-03-14T09:15:35.594Z",
          "manual": true,
          "price": -15,
          "priceAdjustmentId": "e397cd21f9a9c0643277ba1011",
          "promotionId": "manual adjustment",
          "reasonCode": "override manual promo"
        }
      ],
      "orderTotal": 631.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the price adjustment is not manual and cannot be updated.
    *   the expected attributes are missing in the input.
    *   the type of a price adjustment does not match the adjustment type of the input data.
    *   the price adjustment limit is exceeded.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The price adjustment ID is not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: PriceAdjustmentIdNotFoundException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/price-adjustment-not-found",
      "title": "Price Adjustment Not Found",
      "detail": "No price adjustment with ID '453599643347eac5e4ebd85b49' could be found."
    }
    ```
    

### GET Retrieve price books for a basket.

`GET /organizations/{organizationId}/baskets/{basketId}/price-books`

Operation ID: `getPriceBooksForBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders).

( DEPRECATED ) Gets applicable price books for an existing basket. This endpoint is deprecated. Use [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary), hooks or `dw.catalog.PriceBookMgr#getApplicablePriceBooks()` instead.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the priceBookIds for the basket.
    
    Media type: `application/json`. Schema: `PriceBookIds`.
    
    _Example: PriceBooksGet_
    
    ```
    [
      "price-book-id1",
      "price-book-id2"
    ]
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add price books to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/price-books`

Operation ID: `addPriceBooksToBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw).

( DEPRECATED ) This method allows you to put an array of priceBookIds to an existing basket, which will be used for basket calculation. This endpoint is deprecated. Use [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary), hooks or `dw.catalog.PriceBookMgr#setApplicablePriceBooks()` instead.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `PriceBookIds`.

_Example: PriceBooksPut_

```
[
  "price-book-id1",
  "price-book-id2"
]
```

#### Responses

*   **204** Success, without body.
*   **404** The basket with the given basket ID is unknown or contains a price book ID that does not correspond to an existing price book.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Create a shipment for a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/shipments`

Operation ID: `createShipmentForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Creates a new shipment for a basket.

The created shipment is initialized with values provided in the body document and can be updated with further data API calls. Considered from the body are the following properties if specified:

*   the ID
*   the shipping address
*   the shipping method
*   gift boolean flag
*   gift message
*   custom properties

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Shipment`.

_Example: ShipmentsPost_

```
{
  "shipmentId": "me2",
  "shippingMethod": {
    "id": "001"
  },
  "shippingAddress": {
    "firstName": "Stephanie",
    "lastName": "Miller",
    "address1": "385  Prospect Valley Road",
    "city": "Woburn",
    "postalCode": "01801",
    "stateCode": "MA",
    "countryCode": "US"
  }
}
```

#### Responses

*   **200** Success, the response body contains the basket with added shipment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsPost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek"
          },
          "shippingMethod": {
            "description": "Order received in 2 business days",
            "id": "002",
            "name": "2-Day Express",
            "price": 20.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 20.99,
          "shippingTotalTax": 1.05,
          "taxTotal": 36.05
        },
        {
          "adjustedMerchandizeTotalTax": 35,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 35,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me2",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "385  Prospect Valley Road",
            "city": "Woburn",
            "stateCode": "MA",
            "countryCode": "US",
            "firstName": "Stephanie",
            "fullName": "Stephanie Miller",
            "id": "84f06786daa68ae33af7e21ec6",
            "lastName": "Miller"
          },
          "shippingMethod": {
            "description": "Order received in 2 business days",
            "id": "001",
            "name": "2-Day Express",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 35
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 1.05,
          "basePrice": 20.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 20.99,
          "priceAfterItemDiscount": 20.99,
          "shipmentId": "me",
          "tax": 1.05,
          "taxBasis": 20.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        },
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "6fea9966277c94e06b482a5c43",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 36.98,
      "shippingTotalTax": 1.35,
      "taxation": "net",
      "taxTotal": 36.35
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   a shipment id is not provided.
    *   a shipment with the provided ID already. exists for the basket.
    *   a shipment with the provided shipment number already exists for the basket.
    *   a shipping method with an ID was specified which is not a valid shipping method ID.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a shipment from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}`

Operation ID: `removeShipmentFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a specified shipment and all associated product, gift certificate, shipping, and price adjustment line items from a basket. It is not allowed to remove the default shipment.

#### Parameters

*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted shipment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   the given shipment ID is invalid.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **403** The given shipment ID corresponds to the default shipment and cannot be removed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "The shipment with ID 'me' corresponds to the default shipment and can't be deleted."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a shipment for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}`

Operation ID: `updateShipmentForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a shipment for a basket.

The shipment is initialized with values provided in the body document and can be updated with further data API calls. Considered from the body are the following properties if specified:

*   the ID
*   the shipping address
*   the shipping method
*   gift boolean flag
*   gift message
*   custom properties

#### Parameters

*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Shipment`.

_Example: ShipmentsPatch_

```
{
  "shipmentId": "me",
  "shipmentNo": "ignored shipment no",
  "shippingMethod": {
    "id": "003"
  },
  "shippingAddress": {
    "firstName": "Ward J",
    "lastName": "Adamek",
    "address1": "4911  Lincoln Street",
    "city": "IDANHA",
    "postalCode": "97350",
    "stateCode": "OR",
    "countryCode": "US"
  },
  "c_wapi-string": "shipment_custom_property"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated shipment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek"
          },
          "shippingMethod": {
            "description": "Order received in 2 business days",
            "id": "002",
            "name": "2-Day Express",
            "price": 20.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 20.99,
          "shippingTotalTax": 1.05,
          "taxTotal": 36.05
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 1.05,
          "basePrice": 20.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 20.99,
          "priceAfterItemDiscount": 20.99,
          "shipmentId": "me",
          "tax": 1.05,
          "taxBasis": 20.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 20.99,
      "shippingTotalTax": 1.05,
      "taxation": "net",
      "taxTotal": 36.05
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the given shipment ID was invalid.
    *   a shipment with the provided ID already exists for the basket.
    *   a shipment with the provided shipment number already exists for the basket.
    *   a missing shipping method.
    *   an invalid shipping method.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Update the shipping address for a shipment.

`PUT /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-address`

Operation ID: `updateShippingAddressForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets a shipping address of a specific shipment of a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `useAsBilling` (query, boolean) When true, the address is also used as the billing address.
    
    _Example_
    
    ```
    true
    ```
    
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `OrderAddress`.

_Example: ShipmentsAddressPut_

```
{
  "firstName": "Ward J",
  "lastName": "Adamek",
  "address1": "4911  Lincoln Street",
  "city": "IDANHA",
  "postalCode": "97350",
  "stateCode": "OR",
  "countryCode": "US"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added shipping address.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsAddressPut_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "postalCode": "97350",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek",
            "stateCode": "OR"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the shipment with the given shipment ID is unknown.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Update the shipping method for a shipment.

`PUT /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-method`

Operation ID: `updateShippingMethodForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets a shipping method to a specific shipment of a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ShippingMethod`.

_Example: ShipmentsMethodPut_

```
{
  "id": "003"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added shipping method.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsMethodPut_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "postalCode": "97350",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek",
            "stateCode": "OR"
          },
          "shippingMethod": {
            "description": "Order received the next business day",
            "id": "003",
            "name": "Overnight",
            "price": 29.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 29.99,
          "shippingTotalTax": 1.5,
          "taxTotal": 36.5
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 1.5,
          "basePrice": 29.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 29.99,
          "priceAfterItemDiscount": 29.99,
          "shipmentId": "me",
          "tax": 1.5,
          "taxBasis": 29.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 29.99,
      "shippingTotalTax": 1.5,
      "taxation": "net",
      "taxTotal": 36.5
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the id of the shipping method is missing.
    *   a shipping method with an ID was specified which is not a valid shipping method ID.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### GET Retrieve the shipping methods for a shipment.

`GET /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-methods`

Operation ID: `getShippingMethodsForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders, sfcc.shopper-standard).

Gets the applicable shipping methods for a certain shipment of a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the applicable shipping methods for a certain shipment of the basket.
    
    Media type: `application/json`. Schema: `ShippingMethodResult`.
    
    _Example: ShipmentsMethodGet_
    
    ```
    {
      "applicableShippingMethods": [
        {
          "description": "Order received within 7-10 business days",
          "id": "001",
          "name": "Ground",
          "price": 15.99
        },
        {
          "description": "Order received in 2 business days",
          "id": "002",
          "name": "2-Day Express",
          "price": 20.99
        },
        {
          "description": "Order received the next business day",
          "id": "003",
          "name": "Overnight",
          "price": 29.99
        },
        {
          "description": "Store Pickup",
          "id": "005",
          "name": "Store Pickup",
          "price": 0,
          "c_storePickupEnabled": true
        }
      ],
      "defaultShippingMethodId": "001"
    }
    ```
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   The basket with the given basket ID is unknown.
    *   The shipment with the given shipment ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Designate a basket as a storefront basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/storefront`

Operation ID: `updateAsStorefrontBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Marks a basket as a storefront basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `exchange` (query, boolean) If true, an existing storefront basket is exchanged and marked as an agent basket. If false, a `CustomerBasketsQuotaExceededException` is thrown.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Responses

*   **200** Success, the response body contains a basket that is set as a storefront basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketPutStorefront_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "callcenter",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** Returned if a storefront basket already exists and the query parameter `exchange` is false.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomerBasketQuotaExceededException: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### GET Retrieve the external taxation information for a basket.

`GET /organizations/{organizationId}/baskets/{basketId}/taxes`

Operation ID: `getTaxesFromBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw, sfcc.shopper-baskets-orders).

This method gives you the external taxation data set by the PUT taxes API. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the external taxation from all line items from the referenced basket.
    
    Media type: `application/json`. Schema: `Taxes`.
    
    _Example: PostBasketBody_
    
    ```
    {
      "taxes": {
        "3d4e28425ce0b3a65b0ac4e163": {
          "taxItems": [
            {
              "id": "DE_7",
              "rate": 0.07,
              "value": 13.99
            },
            {
              "id": "DE_19",
              "rate": 0.19
            }
          ]
        },
        "ff9452ed11fcf5c80f9143a8f1": {
          "taxItems": [
            {
              "id": "US_1",
              "rate": 0.01
            },
            {
              "id": "US_5",
              "rate": 0.05
            }
          ]
        }
      }
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    
*   **409**
    
    Possible Reasons:
    
    *   The tax mode of the referenced basket is not set to EXTERNAL.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example UnsupportedRequest: same as PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes 409 response._
    
    _Example: InvalidTaxMode_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-tax-mode",
      "title": "Invalid Tax Mode",
      "detail": "Basket with ID 'a10ff320829cb0eef93ca5310a' has invalid tax mode."
    }
    ```
    

### PUT Add external taxation information to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/taxes`

Operation ID: `addTaxesForBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw).

This method allows you to apply external taxation data to an existing basket to be able to pass tax rates and optional values for all taxable line items. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Taxes`.

_Example PostBasketBody: same as GET /organizations/{organizationId}/baskets/{basketId}/taxes 200 response._

#### Responses

*   **204** Success, without body.
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    
*   **409**
    
    Possible Reasons:
    
    *   The tax mode of the referenced basket is not set to EXTERNAL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnsupportedRequest: same as PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes 409 response._
    

## Schemas

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### Basket

Document representing a basket.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `agentBasket` (_boolean_) Is the basket created by an agent? It is read only.  
    Example: `true`.
*   `basketId` (_string_) The unique identifier for the basket. It is read only.  
    Example: `e78aa5646a8efebdd9cdd38be7`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `OrderAddress`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `channelType` (_string_) The sales channel. It is read only.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`. Example: `storefront`.
*   `couponItems` (_array of CouponItem_) The coupon items.
*   `creationDate` (_string (date-time)_) The timestamp when the basket was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `currency` (_CurrencyCode_)
*   `customerInfo` (_object_) The customer information, if the customer is logged in.
    
    Includes all fields of `CustomerInfo`.
    
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items.
*   `inventoryReservationExpiry` (_string (date-time)_) The expiration datetime of the inventory reservation. It is read only.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the basket was last modified. It is read only.  
    Example: `2015-05-19T15:25:18.000Z`.
*   `merchandizeTotalTax` (_number (double)_) The total products tax in the purchase currency. Merchandise total price represents the sum of the product prices before services (such as shipping) or adjustments from promotions have been added. It is read only.  
    Example: `4.95`.
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments.
*   `orderTotal` (_number (double)_) The total price, including products, shipping and tax. It is read only.  
    Example: `110.24`.
*   `paymentInstruments` (_array of OrderPaymentInstrument_) The payment instruments list.
*   `productItems` (_array of ProductItem_) The product items.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products including adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `88`.
*   `shipments` (_array of Shipment_) The shipments.
*   `shippingItems` (_array of ShippingItem_) The shipping items.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments. It is read only.  
    Example: `0.3`.
*   `sourceCode` (_string_) The source code assigned to the basket. It is read only.  
    Example: `OUTDOOR1`.
*   `taxTotal` (_number (double)_) The total tax amount. It is read only.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net). It is read only.  
    Allowed values: `gross`, `net`. Example: `net`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### OrderAddress

Document representing an order address.

*   `address1` (_string_) The first address line.  
    Example: `45 Main Rd.`.
*   `address2` (_string_) The second address line.  
    Example: `Apartment 204`.
*   `city` (_string_) The city.  
    Example: `Boston`.
*   `companyName` (_string_) The company name.  
    Example: `Salesforce`.
*   `countryCode` (_CountryCode_)
*   `firstName` (_string_) The first name.  
    Example: `Max`.
*   `fullName` (_string_) The full name.  
    Example: `Max Mustermann`.
*   `id` (_string_) The ID of the address.  
    Example: `me`.
*   `jobTitle` (_string_) The job title.  
    Example: `Software Engineer`.
*   `lastName` (_string_) The last name.  
    Example: `Mustermann`.
*   `phone` (_string_) The phone number.  
    Example: `6175555555`.
*   `postBox` (_string_) The post office box.  
    Example: `PO BOX 109`.
*   `postalCode` (_string_) The postal code.  
    Example: `05408`.
*   `salutation` (_string_) The salutation.  
    Example: `Mr`.
*   `secondName` (_string_) The second name.
*   `stateCode` (_string_) The state code.  
    Example: `MA`.
*   `suffix` (_string_) The suffix.  
    Example: `Sr`.
*   `suite` (_string_) The suite.  
    Example: `24A`.
*   `title` (_string_) The title.  
    Example: `Dr.`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CouponItem

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256. Example: `5ties`.
*   `couponItemId` (_object_) The coupon item ID. It is read only.
    
    Includes all fields of `CouponItemId`.
    
*   `statusCode` (_string_) The status of the coupon item. It is read only.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`. Example: `no_applicable_promotion`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is "applied" or "no\_applicable\_promotion". It is read only.  
    Example: `true`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CouponItemId

The coupon item ID

Type: `string`.

Minimum length: 1. Example: `d4c9c0141e9c74c150225580f3`.

### CustomerInfo

The customer information for guest or logged-in customers.

*   `customerId` (_string_) The customer ID. It is read only.  
    Maximum length: 100. Example: `abMKqMaNYOBMnNdDNzyC5oNTi5`.
*   `customerName` (_string_) The customer name.  
    Example: `Max Mustermann`.
*   `customerNo` (_string_) The customer number.  
    Maximum length: 100. Example: `0002352`.
*   `email` (_string_, required) The customer's email address.  
    Example: `no-reply@salesforce.com`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GiftCertificateItem

A gift certificate item.

*   `amount` (_number (double)_, required) The gift certificate item amount.  
    Example: `20`.
*   `giftCertificateItemId` (_object_) The item ID. It is read only.
    
    Includes all fields of `GiftCertificateItemId`.
    
*   `message` (_string_) The gift certificate message.  
    Maximum length: 4000. Example: `Birthday present.`.
*   `recipientEmail` (_string_, required) The recipient email.  
    Minimum length: 1. Example: `no-reply@salesforce.com`.
*   `recipientName` (_string_) The recipient's name.  
    Example: `Daniel Mustermann`.
*   `senderName` (_string_) The sender's name.  
    Example: `Max Mustermann`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GiftCertificateItemId

Type: `string`.

Minimum length: 1. Example: `629dea6e7b61e58da629b57b21`.

### ProductItem

Document representing a product item.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `130`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus.  
    Example: `true`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.
*   `optionItems` (_array of OptionItem_) The option items.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `20.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `15.5`.
*   `productId` (_string_) The ID of the product.  
    Maximum length: 100. Example: `nintendo-ds-console`.
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `qualifyingProductItemId` (_string_) Returns the id of the ProductLineItem that qualified the basket for this bonus product. This method is only applicable if the product line item is a bonus product line item, and if the promotion is a product promotion with number of qualifying products granting a bonus-product discount. If these conditions aren't met, the method returns null. If there are multiple product line items that triggered this bonus product, this method returns the last one by position within the order.  
    Maximum length: 28.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax for the product item, not including price adjustments. It is read only.  
    Example: `0.3`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this product item. It is read only.  
    Example: `30`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.9`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ItemId

The item id.

Type: `string`.

Example: `430ef5aad3a24de59378458434`.

### TaxItems

Taxation for a line item.

*   `taxItems` (_array of TaxItem_) The list of tax items. It is read only.

### BasketPaymentInstrumentRequest

Document representing a basket payment instrument request.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `12030000`.
*   `giftCertificateCode` (_string_) The gift certificate code.  
    Maximum length: 256. Example: `AFGRTUZ`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `OrderPaymentCardRequest`.
    
*   `paymentMethodId` (_string_) The payment method ID.  
    Maximum length: 256. Example: `CREDIT_CARD`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentInstrumentId

The payment instrument ID

Type: `string`.

Example: `ba248424e3eee797f062162f8b`.

### OrderPaymentInstrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction. It is read only.
    
    Includes all fields of `Status`.
    
*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `12030000`.
*   `maskedGiftCertificateCode` (_string_) The gift certificate code with the last 4 characters not masked.  
    Example: `******Gzzy`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `PaymentCard`.
    
*   `paymentInstrumentId` (_object_) The payment instrument ID. It is read only.
    
    Includes all fields of `PaymentInstrumentId`.
    
*   `paymentMethodId` (_string_) The payment method ID. It is read only.  
    Maximum length: 256. Example: `CREDIT_CARD`.

### PaymentMethodResult

Result document of payment methods applicable for a basket.

*   `applicablePaymentMethods` (_array of PaymentMethod_) The applicable payment methods. It is read only.

### PriceAdjustmentRequest

Request that represents a price adjustment.

*   `discount` (_object_) A discount that can be specified instead of a price.
    
    Includes all fields of `DiscountRequest`.
    
*   `itemId` (_string_) The item to which the price adjustment should be added, depending on the specified level. If the level is ´order´, item id is not needed. If `shipping`, specify the UUID of the shipping item. If `product`, specify the UUID of the product item.  
    Example: `93196fae953cbedbe54d67e760`.
*   `itemText` (_string_) The text describing the item in more detail.  
    Example: `A discounted item`.
*   `level` (_string_, required)
    
    The level at which the adjustment is applied.
    
    *   `order` indicates that the price adjustment should be added directly to basket.
    *   `product` indicates that the price adjustment should be added to the product item.
    *   `shipping` indicates that the price adjustment is added to the shipping item.
    
      
    Allowed values: `product`, `shipping`, `order`. Example: `order`.
*   `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID as long as it's not used by a price adjustment belonging to the same item and isn't used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated.  
    Example: `Shipping100`.
*   `reasonCode` (_string_) The reason for the price adjustment.  
    Example: `Shipping promotion on order above $1,000 USD`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceAdjustmentId

Type: `string`.

Example: `ba248424e3eee797f062161f8b`.

### PriceAdjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level.

*   `appliedDiscount` (_object_) Details describing the discount this price adjustment is based on. For adjustments not based on a discount, this value is null.
    
    Includes all fields of `Discount`.
    
*   `couponCode` (_string_) The coupon code of the coupon this price adjustment is based on. For adjustments not based on a coupon, this value is null. It is read only.  
    Example: `5ties`.
*   `createdBy` (_string_) The user who created the price adjustment. It is read only.  
    Example: `Support`.
*   `creationDate` (_string (date-time)_) The timestamp when the price adjustment was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.  
    Example: `true`.
*   `itemText` (_string_) The text describing the item.
*   `lastModified` (_string (date-time)_) The timestamp when the price adjustment was last modified. It is read only.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `manual` (_boolean_) A flag indicating whether this price adjustment was created by a manual process. If the price adjustment was created by the promotion engine, this value is always false.  
    Example: `true`.
*   `price` (_number (double)_) The adjustment price. It is read only.  
    Example: `120.88`.
*   `priceAdjustmentId` (_object_) The price adjustment ID. It is read only.
    
    Includes all fields of `PriceAdjustmentId`.
    
*   `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID so long it is not used by a price adjustment belonging to the same item, and is not used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated.
*   `reasonCode` (_string_) The reason for the price adjustment.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceBookIds

Array of price book IDs to use for the basket calculation.

Array of `string`.

Items: Maximum length: 256. Maximum items: 10.

### Shipment

Document representing a shipment.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, not including price adjustments or service charges such as shipping. It is read only.  
    Example: `4.95`.
*   `productSubTotal` (_number (double)_) The total price of all products in the shipment, including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `shipmentId` (_object_) The order-specific ID of the shipment. The default value is 'me'.  
    Default: `me`.
    
    Includes all fields of `ShipmentId`.
    
    Default: `me`.
    
*   `shipmentNo` (_string_) The shipment number of this shipment. This number is automatically generated. It is read only.
*   `shipmentTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments, shipping charges, and tax. It is read only.  
    Example: `39.99`.
*   `shippingAddress` (_object_) The shipping address.
    
    Includes all fields of `OrderAddress`.
    
*   `shippingMethod` (_ShippingMethod_)
*   `shippingStatus` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges in the shipment, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, not including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `taxTotal` (_number (double)_) The total tax on the shipment, including item-level price adjustments and service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `1.8`.
*   `trackingNumber` (_string_) The tracking number of the shipment.  
    Example: `1Z204E380338943508`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShipmentId

The identifier of the shipment

Type: `string`.

Minimum length: 1. Example: `me`.

### ShippingMethod

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.  
    Example: `Order received within 7-10 business days`.
*   `externalShippingMethod` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method ID.  
    Maximum length: 256. Example: `001`.
*   `name` (_string_) The localized name of the shipping method.  
    Example: `Ground`.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs, product level fix, and surcharge costs. It is read only.  
    Example: `15`.
*   `shippingPromotions` (_array of ShippingPromotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingMethodResult

Result document containing shipping methods.

*   `applicableShippingMethods` (_array of ShippingMethod_) The applicable shipping method documents. It is read only.
*   `defaultShippingMethodId` (_string_) The default shipping method. It is read only.  
    Example: `me`.

### Taxes

Document representing the tax rates and (optionally) amounts for all items in a basket.

*   `taxes` (_object_, required) Map containing the TaxItems for the line item ids: Map<LineItemId, TaxItems \[\]>
    
    Additional properties: `TaxItems`.
    

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### BonusDiscountLineItem

Document representing a bonus discount line item.

*   `bonusProducts` (_array of ProductDetailsLink_) The bonus products the customer can choose from.
*   `couponCode` (_string_) The coupon code that triggered the promotion, if applicable.  
    Example: `5ties`.
*   `id` (_string_) The ID of the line item. It is read only.  
    Example: `91f4dd8bfa0653d58b7783b04f`.
*   `maxBonusItems` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotionId` (_string_) The ID of the promotion that triggered the creation of the line item.  
    Example: `Buy1Get2`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### ShippingItem

Document representing a shipping item.

*   `adjustedTax` (_number (double)_) The tax for the shipping item, including price adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the shipping item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `itemId` (_string_) The shipping item ID. Use it to identify this shipping item when updating its quantity or creating a custom price adjustment for it. It is read only.  
    Example: `430ef5aad3a24de59378458434`.
*   `itemText` (_string_) The text describing the shipping item.  
    Example: `Shipping`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the shipping item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.
*   `shipmentId` (_object_) The identifier of the shipment to which this item belongs.
    
    Includes all fields of `ShipmentId`.
    
*   `tax` (_number (double)_) The tax on the product item, not including adjustments. It is read only.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this shipping item. It is read only.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1. It is read only.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### OptionItem

An option item represents an optional purchase related to a product item, and is always associated with that parent product item. An option item can have different values from which to select. For example, a refrigerator item can have an option item representing an extended warranty, with a set of option item values representing different warranty lengths. When a shopper purchases the warranty option item together with the parent refrigerator item, they select one of the available warranty option item values.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.  
    Example: `ba248414e3eee797f062162f8b`.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus. It is read only.  
    Example: `false`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `false`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item. It is read only.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.  
    Example: `The item text.`.
*   `optionId` (_string_, required) The ID of the option. It is read only.  
    Maximum length: 256. Example: `consoleWarranty`.
*   `optionItems` (_array of OptionItem_) The option items.
*   `optionValueId` (_string_, required) The ID of the option value. It is read only.  
    Maximum length: 256. Example: `000`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `150.99`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `40.5`.
*   `productId` (_ProductId_)
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `quantity` (_number (double)_) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments. It is read only.  
    Example: `0`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item. It is read only.  
    Example: `50`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.19`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductListItemReference

Document representing product list item details.

*   `id` (_object_, required) The ID of the product list item. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `priority` (_integer (int32)_) The priority of the product list item.  
    Example: `1`.
*   `productDetailsLink` (_ProductDetailsLink_)
*   `productList` (_object_) A reference to the associated product list. It is read only.
    
    Includes all fields of `ProductListLink`.
    
*   `public` (_boolean_)  
    Example: `false`.
*   `purchasedQuantity` (_number (double)_) The total quantity of this item purchased from the product list.  
    Example: `0`.
*   `quantity` (_number (double)_) The number of products or gift certificates that get shipped when purchasing this product list item.  
    Minimum: 0. Example: `1`.
*   `type` (_string_) Specifies whether the item is a product or a gift certificate.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### TaxItem

Object representing the taxation.

*   `id` (_string_, required) The taxation identifier.
*   `rate` (_number (double)_, required) The taxation rate.  
    Example: `0.13`.
*   `value` (_number (double)_) The tax amount. Will be computed if not set.

### OrderPaymentCardRequest

Document representing an order payment card request.

*   `cardType` (_string_) The payment card type (for example: Visa).  
    Maximum length: 256. Example: `Visa`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store.  
    Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number.  
    Maximum length: 25. Pattern: ^\[0-9 -\]{0,7}\\D{6,15}\\d{0,4}$. Example: `*********4422`.
*   `validFromMonth` (_integer (int32)_) The month the payment card is valid from.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year the payment card is valid from.  
    Example: `2019`.

### Status

Document representing an object status.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_) The status. For more information on the status values see Status.OK and Status.ERROR.

### PaymentCard

Document representing a payment card.

*   `cardType` (_string_) The payment card type.  
    Maximum length: 256. Example: `Visa`.
*   `creditCardExpired` (_boolean_) A flag indicating if the credit card is expired. It is read only.  
    Example: `true`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store.  
    Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number.  
    Maximum length: 4000. Example: `*********4422`.
*   `numberLastDigits` (_string_) The last digits of the payment card number. It is read only.  
    Maximum length: 4000. Example: `4422`.
*   `validFromMonth` (_integer (int32)_) The month the payment card is valid from.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year the payment card is valid from.  
    Example: `2015`.

### PaymentMethod

Document representing a payment method.

*   `cards` (_array of PaymentCardSpec_) The sorted array of payment cards (included only when the system payment method is CREDIT\_CARD). It is read only.
*   `description` (_string_) The localized description of the payment method or card. It is read only.
*   `id` (_string_, required) The ID of the payment method or card. It is read only.  
    Maximum length: 256.
*   `image` (_string_) The URL to the image that represents the payment method or card. It is read only.
*   `name` (_string_) The localized name of the payment method or card. It is read only.
*   `paymentProcessorId` (_string_) The payment processor ID. It is read only. It is read only.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### DiscountRequest

Request that represents a discount to be applied to a custom price adjustment.

*   `type` (_string_, required)
    
    The type of discount.
    
    *   `amount` describes a (unit) price discount, and its corresponding value (positive) defines the amount each unit is to be reduced by. Example: For a $10 discount, set `type` to `amount` and `value` to `10.00`.
    *   `percentage` describes a percentage discount, and its corresponding value (positive) defines the percentage reduction. Example: For a 5% discount, set `type` to `percentage` and `value` to `5.00`.
    *   `fixed_price` describes a fixed price discount, and its corresponding value (positive) defines the resulting fixed price for the item. Only one `fixed_price` discount can be set for each item. Example: To set a fixed price of $15, set `type` to `fixed_price` and `value` to `15.00`. **Important**: Setting `type` to `fixed_price` is not supported when `level` is set to `order`.
    
      
    Allowed values: `percentage`, `fixed_price`, `amount`. Example: `percentage`.
*   `value` (_number (double)_, required) The amount of the discount.  
    Example: `20`.

### Discount

Document representing a discount.

*   `amount` (_number (double)_) The discount amount for discount types that define specific discount amounts. It is read only.  
    Example: `130.88`.
*   `percentage` (_number (double)_) The discount percent for discount types that define percentage discounts. It is read only.  
    Example: `0.19`.
*   `priceBookId` (_string_) The price book ID that is used with some types. It is read only.  
    Example: `usd-sale-prices`.
*   `type` (_string_, required) The type of discount. It is read only.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`. Example: `fixed_price`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingPromotion

Document representing a shipping promotion.

*   `calloutMsg` (_string_) The localized callout message of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `promotionId` (_string_) The unique ID of the promotion.  
    Example: `$30FixedShippingAmountAbove150`.
*   `promotionName` (_string_) The localized promotion name.  
    Example: `$30 Fixed Shipping Amount Above 150`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductDetailsLink

Document representing a link to the resource for product details.

*   `productDescription` (_string_) The description of the product.  
    Example: `Nintendo DS revolutionizes handheld gameplay.`.
*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `title` (_string_) The link title.  
    Example: `Nintendo DS Game Console`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### ProductListLink

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers. It is read only.  
    Example: `true`.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `shopping_list`.

### PaymentCardSpec

Document representing the specification for a payment card.

*   `cardType` (_string_) The payment card type. It is read only.  
    Example: `Visa`.
*   `checksumVerificationEnabled` (_boolean_) A flag indicating whether the card number is verified using the Luhn checksum algorithm. It is read only.  
    Example: `true`.
*   `description` (_string_) The localized description of the payment card. It is read only.
*   `image` (_string_) The URL to the image that represents the payment card. It is read only.
*   `name` (_string_) The localized name of the payment card. It is read only.
*   `numberLengths` (_array of string_) The sorted list of number lengths (individual lengths as well as length ranges). It is read only.
*   `numberPrefixes` (_array of string_) The sorted list of number prefixes (individual prefixes as well as prefix ranges). It is read only.
*   `securityCodeLength` (_integer (int32)_) The length of the security code for this card. It is read only.

<!-- document id=46b066b88b9c34eef4bdef9f91630141960f628f4dd0b55289de70edd53f7d51 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-baskets-v2.md -->

Shopper Baskets V2

# Shopper Baskets V2

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-baskets-v2/shopper-baskets-oas-v2-public.yaml)

## API Overview

Shopper Baskets V2 provides all Shopper Basket V1 functionality and adds support for temporary baskets. Temporary baskets can perform calculations to generate totals, line items, promotions, and item availability without affecting the shopper’s storefront cart, and you can use those calculations for temporary basket checkout. You can also use a temporary basket for an immediate order request.

**Note**: `dw.ocapi.shop.basket.beforePOST` hook is no longer supported and is replaced by the `dw.ocapi.shop.basket.beforePOST_v2` hook.

Use the Shopper Baskets API to create a basket in the B2C Commerce system and populate it with all the data required to ready the basket for checkout.

To create a basket, start with the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket) endpoint. The endpoint creates the basket in the B2C Commerce system and returns a JSON representation of the basket with a `basketId` property.

If you provide the JSON for a prepopulated basket to the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket) endpoint, you can create a basket using a single API request.

You can also create a basket and gradually populate it with data using subsequent API requests that reference the same `basketId`. The gradual approach allows you to validate the input data as you go.

The Shopper Baskets API includes endpoints to populate each part of a basket separately, including:

*   Billing address
*   Customer information
*   Line items
    *   Products
    *   Coupons
    *   Gift certificates
*   Payment methods
*   Price books
*   Shipments
*   Taxation (for items and the basket itself)

In addition to creating a basket, the main `/baskets` resource offers endpoints to get, transfer, merge, and delete baskets, depending on the HTTP method that you use and the parameters that you supply. These endpoints can you help you handle a variety of complex scenarios, such as when a user starts shopping as a guest and then logs in before checkout.

You can also use the main `/baskets` resource to add custom properties to your basket, prefixed with `c_` (example: `c_faxNumber`).

When your basket is fully populated, you can use its `basketId` property to create an order with the [Shopper Orders API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary).

For more detail on building baskets, see [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html).

### Authentication & Authorization

The client requesting the basket information must have access to the `/baskets` resource. The Shopper Baskets API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

You must include `sfcc.shopper-baskets-orders` or `sfcc.shopper-baskets-orders.rw` in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

The following resources require an Account Manager OAuth token with a client ID:

*   `/baskets/{basketId}/taxes`
*   `/baskets/{basketId}/items/{itemId}/taxes`
*   `/baskets/{basketId}/price-books`

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)

#### Caching

Responses from this API are not cached. Basket data is stateful and unique to each shopper session.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Create a Basket

Create a new basket for the shopper.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v2/organizations/{organizationId}/baskets?siteId=RefArch" \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{}'
```

#### Add an Item to a Basket

Add a product to an existing basket.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v2/organizations/{organizationId}/baskets/{basketId}/items?siteId=RefArch" \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '[{ "productId": "25695327M", "quantity": 1 }]'
```

#### Basket Calculation

Unless you’re using [hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html), each modification to a basket triggers the following calculations:

1.  Calculate product prices:
    *   Iterate through the product line items and determine the base price of each using its price model. If multiple price books apply to a product, the lowest price is used.
    *   Calculate product option line item prices using the product option model.
    *   For bonus products, check dependent adjustments in the basket to determine the price.
2.  Iterate through the gift certificate line items and calculate the price of each by multiplying the base price by the quantity.
3.  Recalculate for all promotions, adding and removing them as appropriate.
4.  Apply product-specific shipping costs.
5.  Calculate the total shipping cost.
6.  Recalculate for all promotions, adding and removing them as appropriate.
7.  Calculate prices for products added by the promotion engine.
8.  Calculate taxes using line item tax class codes.
    *   For internal tax mode, use the tax tables.
    *   For external tax mode, use the tax rates returned by the tax API endpoints.
9.  Calculate the order’s net, tax, and gross totals by adding up the line totals.

#### External Taxation

The B2C Commerce API calculates taxes internally using tax tables. If you want to integrate with a third-party tax provider, or calculate tax on your own, you can use the external taxation feature to add a taxation rate and optional taxation value. When setting a taxation rate, the taxation is calculated for this specific rate. If you pass a value, this value is used as taxation value, as well, without recalculation. To use this feature, set the `taxMode` parameter to `external` when creating the basket.

When using external taxation, you must set a tax rate either in one request to the `/baskets/{basketId}/taxes` or with separate requests for each line item, using `/baskets/{basketId}/items/{lineItemId}/taxes`.

If the tax mode of a basket is set to `external`, a tax item is required for all line items even for zero-tax items to avoid oversights.

#### External Taxation with Hooks Enabled

To use external tax calculation with [hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html), use the following API methods in the [Calculate Hook](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#calculate-hook):

*   `dw.order.LineItemCtnr#isExternallyTaxed`: Returns true if the basket was created with `taxMode = external`
*   `dw.order.TaxMgr#applyExternalTax`: Applies externally set tax rates to the given basket. Only use when `dw.order.LineItemCtnr#isExternallyTaxed` returns true.

The following example shows an implementation of external tax calculation with hooks enabled in the [Calculate Hook](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html#calculate-hook):

```javascript
exports.calculate = function (basket) {
   if ( basket.isExternallyTaxed() )
   {
      TaxMgr.applyExternalTaxation( basket ); // apply the external tax calculation based on the tax rates set by the SCAPI external taxation APIs
   }
   else
   {
      // calculation with tax tables or customization
   }
}
```

### Temporary Baskets

A temporary basket is populated with all the data required to ready the basket for checkout, but differs from a shopper basket in the following ways:

*   Basket lifetime is limited to 15 minutes.
*   The shopper can have up to 10 (default 4) temporary baskets, which can be configured via Basket Preferences (Sites -> Merchant Tools -> Basket Preferences) and specifying the preference **Temporary Baskets per Customer**.
*   Available to all shoppers (guest and registered shoppers), as well as agents.

To create a temporary basket, set the `temporary` parameter to `true` with the [Create basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=createBasket) endpoint.

To promote a temporary basket by clearing its `isTemporary` flag, use the [Promote basket](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=promoteTemporaryBasket) endpoint.

### Related APIs

*   [Shopper Orders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-orders?meta=Summary) — Place an order from a completed basket.
*   [Shopper Payments](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-payments?meta=Summary) — Retrieve payment method configuration for checkout.

**Version:** 2.13.4

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-baskets/v2`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `RegisteredShopperToken` (oauth2) `RegisteredShopperToken` is a child of the `ShopperToken` security scheme and restricts access to a **registered (authenticated) shopper**. Access is only granted to a shopper token that represents a registered shopper; a guest shopper token is rejected. Endpoints secured with `RegisteredShopperToken` operate on identity-bound resources of a registered shopper, such as their addresses, payment instruments, password, or saved product lists. Besides these endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `RegisteredShopperToken`. To get a `RegisteredShopperToken`, the shopper must authenticate with SLAS (for example, through the authorization code flow or the [login endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer)). For details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `ShopperTokenTaob` (oauth2) `ShopperTokenTaob` (Taob = trusted agent on behalf) is a child of the `ShopperToken` security scheme and extends the functionality of `ShopperToken` for specific use cases. A token of type `ShopperTokenTaob` allows you to access Shopper API endpoints, including OCAPI and Salesforce Commerce API for headless applications. Besides endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `ShopperTokenTaob`. To get a `ShopperTokenTaob` token, a `Taob` session needs to be created first (see [getTrustedAgentAuthorizationToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=getTrustedAgentAuthorizationToken)). Afterwards the `ShopperTokenTaob` token can be gained (see [getTrustedAgentAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-login?meta=getTrustedAgentAccessToken)). For more information regarding the `Taob` flow see also [Trusted Agent Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html).
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/trusted-agent/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints

## Operations

### POST Create a new basket.

`POST /organizations/{organizationId}/baskets`

Operation ID: `createBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Creates a new basket.

The created basket is initialized with default values. Optional JSON data provided in the request body is populated into the created basket. It can be updated with other endpoints offered by the Shopper Baskets API.

Each shopper is limited to one open basket at a time. Attempting to create a second basket for the same customer will result in a 400 Bad Request error with the message: "Customer Baskets Quota Exceeded". A basket is considered "open" upon creation and remains in this state until it is either converted into an order or explicitly deleted. For implementation best practices, see [Hybrid Storefront Best Practices for Working with Baskets](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html#hybrid-storefront-best-practices-for-working-with-baskets).

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `taxMode` (query, string)
    
    Determines how taxes are calculated.
    
    The default value is `internal` where the tax calculation is done automatically based on internal tax tables. Setting `taxMode` to `external` allows manual modification of the tax rates and values. External tax data is mandatory for product line items, option line items, shipping line items, coupon line items, and bonus discount line item. Gift certificate line items are optional and use zero tax rate by default, which can be overwritten. Price adjustments cannot be set because they are either calculated or inherited. Depending on the type, the tax rate is either obtained from the related line item or computed as a prorate of the basket.
    
      
    Allowed values: `internal`, `external`. Default: `internal`. Example: `external`.
*   `temporary` (query, boolean) If set to true, the basket created is a temporary basket.  
    Default: `false`.
*   `populateCustomerDetails` (query, boolean)
    
    If set to true, the system invokes the `dw.order.populateCustomerDetails` hook.
    
    By default, the hook retrieves the registered customer's default address or first saved address, and payment instrument. The hook then uses this information to populate the basket:
    
    *   If no shipping address is specified, the shipping address is set to the customer's saved address.
    *   If no billing address is specified, the billing address is set to the customer's saved address.
    *   If no payment instrument is specified, the payment instrument is set to the customer's saved payment instrument.
    
    This behavior can be customized by overriding the hook.
    
      
    Default: `false`. Example: `false`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Basket`.

_Example: PostBasketBody_

```
{
  "customerInfo": {
    "email": "shopper@salesforce-test.com",
    "customerNo": "000000001"
  },
  "billingAddress": {
    "firstName": "Stephanie",
    "lastName": "Miller",
    "address1": "104 Presidential Way",
    "city": "Woburn",
    "postalCode": "01801",
    "stateCode": "MA",
    "countryCode": "US"
  },
  "shipments": [
    {
      "shippingMethod": {
        "id": "001"
      },
      "shippingAddress": {
        "firstName": "Agustin",
        "lastName": "Estes",
        "address1": "4162  Turkey Pen Road",
        "city": "New York",
        "postalCode": "10016",
        "stateCode": "NY",
        "countryCode": "US"
      }
    }
  ],
  "paymentInstruments": [
    {
      "paymentMethodId": "CREDIT_CARD",
      "paymentCard": {
        "cardType": "Visa"
      }
    }
  ],
  "couponItems": [
    {
      "code": "5ties"
    }
  ],
  "productItems": [
    {
      "productId": "green-umbrella",
      "quantity": 3
    }
  ]
}
```

#### Responses

*   **200** The initialized basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketsPostSuccess_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the provided payment method is invalid or not applicable.
    *   the customerId URL parameter does not match the verified customer represented by the JSON Web Token (JWT).
    *   a new basket cannot be created because the maximum number of baskets per customer would be exceeded.
    *   a new temporary basket cannot be created because the maximum number of temporary baskets per customer would be exceeded.
    *   the same shipment ID appeared twice in the body.
    *   the coupon number is not provided.
    *   a fixed price adjustment was added at order level which is disallowed.
    *   a promotion ID was used twice, while attempting to add a price adjustment.
    *   a system promotion ID was used as a manual promotion ID, while attempting to add a price adjustment.
    *   more than one hundred price adjustments would have been created.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'."
    }
    ```
    
    _Example: CustomerBasketQuotaExceededException_
    
    ```
    {
      "title": "Customer Baskets Quota Exceeded",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-baskets-quota-exceeded",
      "detail": "The maximum number of baskets per customer was exceeded. Please reuse or delete one of the existing baskets (40e91e04aba6e42a6836f79308).",
      "basketIds": "40e91e04aba6e42a6836f79308"
    }
    ```
    
    _Example: TemporaryBasketQuotaExceededException_
    
    ```
    {
      "title": "Customer Temporary Baskets Quota Exceeded,",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-temporary-baskets-quota-exceeded",
      "detail": "The maximum number of temporary baskets per customer was exceeded. Please reuse or delete one of the existing temporary baskets (40e91e04aba6e42a6836f79308, 73ca0f0860a67df946782c2688).",
      "basketIds": "40e91e04aba6e42a6836f79308, 73ca0f0860a67df946782c2688"
    }
    ```
    
*   **404** Returned if the shipment with the given shipment ID is unknown.
    
    Media type: `application/problem+json`.
    
    _Example: ShipmentNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/shipment-not-found",
      "title": "Shipment Not Found",
      "detail": "The shipping method with ID '123' is unknown or can't be applied to the basket."
    }
    ```
    

### POST Transfer an existing basket.

`POST /organizations/{organizationId}/baskets/actions/transfer`

Operation ID: `transferBasket`. Security: RegisteredShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Transfer the previous shopper's basket to the current shopper by updating the basket's owner. No other values change. You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token.

This endpoint provides different methods for handling the scenario in which both a previous guest shopper and the current registered shopper have an active basket attached, and utilizes the `merge` parameter as follows:

*   `true` (recommended): Triggers a merge hook for graceful handling and prevents 409 status returns. For more information, refer to the `merge` parameter documentation.
*   `false`: Either overrides the basket of the current registered shopper or returns a 409 response, and allows you to choose between the options explained below.

If you call the endpoint with `merge=false` and the current shopper has an active basket, you have two options using the `overrideExisting` parameter. Setting it to `true` deletes the registered user's basket, while setting it to `false` returns a `BasketTransferException` (HTTP status 409), after which you can choose how to proceed:

*   Keep the current shopper's active basket.
*   Merge the previous and current shoppers' baskets by calling the `baskets/actions/merge` endpoint.
*   Force the transfer by calling the `baskets/actions/transfer` endpoint again, with the parameter `overrideExisting=true`. Forcing the transfer deletes the current shopper's active basket.

A successful response provides the transferred (and merged) current basket. However, if neither the previous nor current shopper had an active basket, a 204 (No Content) response is returned.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `overrideExisting` (query, boolean)
    
    If the current shopper has no active basket, this parameter is ignored. If the current shopper has an active basket, this parameter controls the behavior:
    
    *   `false` (default): Return a BasketTransferException (HTTP status 409). The basket owner doesn't change.
    *   `true`: Force the transfer by deleting the current shopper's active basket and making the current shopper the owner of the previous shopper's basket. Returns the transferred basket (HTTP status 200).
    
      
    Default: `false`. Example: `false`.
*   `merge` (query, boolean)
    
    This parameter controls the behavior:  
    \- `false` (default): Transfers the basket or returns a 409 response with the appropriate message (taking `overrideExisting` in consideration). - `true`: (recommended): Executes the dw.order.mergeBasket hook if at least one basket exists.
    
    The hook dw.order.mergeBasket default implementation merges a source basket into the current basket. This behavior can be customized, as shown in this [sample implementation](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f).
    
    There are four possible use cases:
    
    a) Guest basket and registered basket exist The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called with the source basket (former registered shopper basket) and the transferred current basket (former guest basket).
    
    b) Guest basket exists but no registered basket exists The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called without the source basket (null passed to the hook) and the transferred current basket (former guest basket).
    
    c) No guest basket exists but a registered basket exists The registered basket is retained. The hook dw.order.mergeBasket is called with the retained current basket but without the source basket (null passed to the hook).
    
    d) Neither basket exists The hook dw.order.mergeBasket is not called.
    
    The API returns the current basket (after executing dw.order.mergeBasket).
    
      
    Default: `false`. Example: `false`.
*   `populateCustomerDetails` (query, boolean)
    
    If set to true, the system invokes the `dw.order.populateCustomerDetails` hook.
    
    By default, the hook retrieves the registered customer's default address or first saved address, and payment instrument. The hook then uses this information to populate the basket:
    
    *   If no shipping address is specified, the shipping address is set to the customer's saved address.
    *   If no billing address is specified, the billing address is set to the customer's saved address.
    *   If no payment instrument is specified, the payment instrument is set to the customer's saved payment instrument.
    
    This behavior can be customized by overriding the hook.
    
      
    Default: `false`. Example: `false`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** The current basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **204** The operation was successful. No current basket was returned because neither the previous nor current shopper had an active basket attached that could be transferred.
*   **403** The call returns this error if no SLAS token for a registered shopper is available.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenMissingPrevCustomerInfo_
    
    ```
    {
      "title": "Forbidden",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "detail": "Your access-token is valid, but it contains no previous customer to process this action."
    }
    ```
    
*   **409**
    
    The call returns this response when the `merge` request parameter is set to `false` and one of the following cases applies:
    
    *   The previous shopper has no active basket.
    *   The current shopper has an active basket and the `overrideExisting` query parameter is set to `false` (default value).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: SourceBasketException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/no-source-basket-exception",
      "title": "Conflict",
      "detail": "The previous customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has no active basket."
    }
    ```
    
    _Example: BasketTransferException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-transfer-basket-already-exists-exception",
      "title": "Conflict",
      "detail": "The current customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has an active basket."
    }
    ```
    

### POST Merge baskets.

`POST /organizations/{organizationId}/baskets/actions/merge`

Operation ID: `mergeBasket`. Security: RegisteredShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

( DEPRECATED ) Instead of using this endpoint, we recommend using the `/baskets/actions/transfer` endpoint with the `merge=true` parameter, because the transfer endpoint offers greater customization by invoking a hook, allowing for adjustments if the default implementation does not process the merge as expected.

Merge data from the previous shopper's basket into the current shopper's active basket and delete the previous shopper's basket. This endpoint doesn't merge Personally Identifiable Information (PII). You must obtain the shopper authorization token via SLAS and you must provide the ‘guest usid‘ in both the ‘/oauth2/login‘ and ‘/oauth2/token‘ calls while fetching the registered user JWT token. After the merge, all basket amounts are recalculated and totaled, including lookups for prices, taxes, shipping, and promotions, unless hooks are enabled.

The following information is merged:

*   custom attributes on the basket and on all copied records
*   product items
*   gift certificate items
*   coupon items
*   shipments
*   ad-hoc price adjustments

To control the merging of products that exist in both baskets, use the `productItemMergeMode` parameter. By default, the higher of the two basket quantities is used for each product. Products in both baskets are considered to be the same when all of the following values match (if one product doesn't have a value, the other product is a match only if it also doesn't have that value):

*   shipment
*   productId
*   option values
*   wishlist reference
*   inventory list id
*   gift flag & message
*   ad-hoc price adjustments

If any of the listed values don't match, then the item in the previous shopper's basket is copied to a new line item in the current shopper's basket. If the listed values all match, but the matching products have different values for any custom attribute, the merged line item keeps the custom attribute value from the current shopper's basket.

A success response contains the current shopper's active basket. The previous guest shopper's active basket is deleted.

If the current shopper doesn't have an active basket, and the createDestinationBasket request parameter is false, then the merge request returns a BasketMergeException (HTTP status 409). You can proceed with one of these options:

*   Transfer the previous shopper's active basket to the current logged-in shopper by calling the `baskets/transfer` endpoint.
*   Force the merge by calling the `baskets/merge` endpoint again, with the parameter `createDestinationBasket=true`. Forcing the merge creates a new basket for the current shopper and copies information from the previous shopper's basket into it. Because the merge doesn't copy all basket data, a forced merge is not the same as a transfer. For example, the new basket doesn't contain any Personally Identifiable Information (PII) from the previous basket.

#### before merge

| Previous Shopper's Basket, SKU: Quantity, Custom Attributes | Current Shopper's Basket, SKU: Quantity, Custom Attributes |
| --- | --- |
| SKU\_A: 5   SKU\_B: 3   SKU\_C: 4   c\_customAttr\_1: 'ABC'   c\_customAttr\_2: 'DEF' | SKU\_A: 2   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_3: 'XYZ' |

#### after merge - (previous shopper's basket is deleted)

| productItemMergeMode | Current Shopper's Basket - SKU: Quantity, Custom Attributes |
| --- | --- |
| sum\_quantities | SKU\_A: 7   SKU\_B: 3   SKU\_C: 4   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |
| higher\_quantity | SKU\_A: 5   SKU\_B: 3   SKU\_C: 4   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |
| saved\_quantity | SKU\_A: 2   SKU\_B: 3   SKU\_C: 4   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |
| separate\_item | SKU\_A: 5   SKU\_B: 3   SKU\_C: 4   SKU\_A: 2   SKU\_D: 6   SKU\_E: 7   c\_customAttr\_1: 'UVW'   c\_customAttr\_2: 'DEF'   c\_customAttr\_3: 'XYZ' |

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `createDestinationBasket` (query, boolean)
    
    If the current shopper has an active basket, this parameter is ignored. If the current shopper has no active basket, this parameter controls the behavior:
    
    *   `false` (default): Return a BasketMergeException (HTTP status 409).
    *   `true`: Force the merge by creating a basket for the current shopper and copying information from the previous shopper's basket into it. Return success (HTTP status 200).
    
      
    Default: `false`.
*   `productItemMergeMode` (query, string)
    
    This parameter controls the quantity calculation for products that exist in both baskets.
    
    *   higher\_quantity (default): Compare the product's quantities in each basket, and use the higher value.
    *   sum\_quantities: Use the sum of the product's quantities from both baskets.
    *   saved\_quantity: Use the product's quantity in the current shopper's active basket. Ignore the quantity from the previous shopper's basket.
    *   separate\_item: Add a separate product item to the current shopper's basket for the quantity in the previous shopper's basket.
    
      
    Allowed values: `higher_quantity`, `sum_quantities`, `saved_quantity`, `separate_item`. Default: `higher_quantity`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** The current shopper's active basket, including items merged from the previous shopper's basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **403** The call returns this error if no SLAS token for a registered shopper is available.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenMissingPrevCustomerInfo: same as POST /organizations/{organizationId}/baskets/actions/transfer 403 response._
    
*   **409**
    
    The call returns this response in either of these cases:
    
    *   The previous shopper has no active basket.
    *   The current shopper has no active basket and the `createDestinationBasket` query parameter was `false` (default value).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SourceBasketException: same as POST /organizations/{organizationId}/baskets/actions/transfer 409 response._
    
    _Example: BasketMergeException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-merge-no-current-basket-exception",
      "title": "Conflict",
      "detail": "The current customer with ID 'cdo7rJNie7ahERqXSb51Yvz2M4' has no active basket."
    }
    ```
    

### GET Retrieve an existing basket.

`GET /organizations/{organizationId}/baskets/{basketId}`

Operation ID: `getBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Gets a basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `expand` (query, array of string, style: form, explode: false)
    
    Expands the response with additional data.
    
    *   payment\_references: Adds a `paymentReference` object to each `paymentInstrument`, holding data regarding the payment with the external payment gateway. If Salesforce Payments is not enabled, this expansion has no effect.
    *   approaching\_discounts: The endpoint returns the approachingDiscounts array on the basket, which contains order and shipping discount entries. If you don't provide this parameter, the approachingDiscounts field isn't included in the response.
    
      
    Items: Allowed values: `payment_references`, `approaching_discounts`. Example: `payment_references`.
    
    _Example_
    
    ```
    [
      "payment_references",
      "approaching_discounts"
    ]
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the retrieved basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: GetBasket_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "deliveryWindow": {
            "startAt": "2026-05-04T14:00:00Z",
            "endAt": "2026-05-07T22:00:00Z"
          },
          "gift": false,
          "merchandizeTotalTax": 30,
          "orderCutoffAt": "2026-04-27T14:00:00Z",
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99,
            "deliveryWindow": {
              "startAt": "2026-05-04T14:00:00Z",
              "endAt": "2026-05-07T22:00:00Z"
            },
            "orderCutoffAt": "2026-04-27T14:00:00Z"
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
    _Example: GetBasketWithOrderApproachingDiscount_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "channelType": "storefront",
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8,
      "approachingDiscounts": [
        {
          "type": "order",
          "conditionThreshold": 700,
          "merchandiseTotal": 599.97,
          "discount": {
            "type": "percentage",
            "percentage": 0.15
          },
          "promotionLink": {
            "promotionId": "15off700",
            "name": "15% off $700 orders",
            "calloutMsg": "Spend $100 more to save 15%!",
            "title": "15% off $700 orders",
            "link": "/s/RefArch/promotions/15off700"
          }
        }
      ]
    }
    ```
    
    _Example: GetBasketWithShippingApproachingDiscount_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "channelType": "storefront",
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8,
      "approachingDiscounts": [
        {
          "type": "shipping",
          "conditionThreshold": 750,
          "merchandiseTotal": 599.97,
          "discount": {
            "type": "amount",
            "amount": 15.99
          },
          "promotionLink": {
            "promotionId": "freeship750",
            "name": "Free shipping over $750",
            "calloutMsg": "Add $150 more for free shipping!",
            "title": "Free shipping over $750",
            "link": "/s/RefArch/promotions/freeship750"
          },
          "shipmentId": "me",
          "shippingMethods": [
            {
              "id": "001",
              "name": "Ground",
              "description": "Order received within 7-10 business days",
              "price": 15.99
            },
            {
              "id": "002",
              "name": "2-Day Express",
              "description": "Order received in 2 business days",
              "price": 20.99
            }
          ]
        }
      ]
    }
    ```
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Delete a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}`

Operation ID: `deleteBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **204** Success, without a body.
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}`

Operation ID: `updateBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a basket. Only the currency of the basket, source code, the custom properties of the basket, and the shipping items will be considered.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Basket`.

_Example: BasketPatch_

```
{
  "c_textValue": "oak"
}
```

#### Responses

*   **200** Success, the response body contains the updated basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "7800e0f611dac6caf77afb9df9",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:53:30.993Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:53:35.747Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "2b76b8644eb6da43e7e223b48d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "43c38652bc3844e14cd482ff28",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "b4ff13039bc7abd1b9d933b871",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "193e99bc1205b870cebd36d970",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "ac7a3b62dc1df8de898d7a2141",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8,
      "c_textValue": "oak"
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the basket cannot be updated because the requested currency is not supported by the site.
    *   the given shipping item ID is null or empty.
    *   a few shipping items with the same item ID are provided.
    *   the provided code is not currently active.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the shipping item with the given item ID is unknown for the basket.
    *   the provided code was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Promote a temporary basket by clearing its isTemporary flag.

`POST /organizations/{organizationId}/baskets/{basketId}/actions/promote`

Operation ID: `promoteTemporaryBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Clears the `isTemporary` flag on a temporary basket (`isTemporary = true`). The basket UUID is preserved. For regular shopper baskets, the result satisfies `isStorefrontBasket`; for agent baskets (`isAgentBasket = true`), the `isTemporary` flag is cleared but the basket remains an agent basket — it does not become a storefront basket.

**Agent baskets:** Because agent baskets do not occupy the customer's storefront basket slot after promotion, conflict resolution is skipped entirely. The `merge` and `overrideExisting` parameters are ignored when promoting an agent basket.

For non-agent baskets, if the shopper already has a storefront basket, this endpoint uses the `merge` parameter to control the behavior:

*   `true` (recommended): Executes the `dw.order.mergeBasket` hook to fold the pre-existing storefront basket's contents into the promoted basket.
*   `false`: Either overrides the pre-existing storefront basket or returns a `409` response, depending on the `overrideExisting` parameter.

If `merge=false` and the shopper has a pre-existing storefront basket, the `overrideExisting` parameter controls the behavior:

*   `false` (default): Returns a `BasketNotPromotableException` (HTTP status 409).
*   `true`: Deletes the pre-existing storefront basket and completes the promotion.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `overrideExisting` (query, boolean)
    
    If the current shopper has no active basket, this parameter is ignored. If the current shopper has an active basket, this parameter controls the behavior:
    
    *   `false` (default): Return a BasketTransferException (HTTP status 409). The basket owner doesn't change.
    *   `true`: Force the transfer by deleting the current shopper's active basket and making the current shopper the owner of the previous shopper's basket. Returns the transferred basket (HTTP status 200).
    
      
    Default: `false`. Example: `false`.
*   `merge` (query, boolean)
    
    This parameter controls the behavior:  
    \- `false` (default): Transfers the basket or returns a 409 response with the appropriate message (taking `overrideExisting` in consideration). - `true`: (recommended): Executes the dw.order.mergeBasket hook if at least one basket exists.
    
    The hook dw.order.mergeBasket default implementation merges a source basket into the current basket. This behavior can be customized, as shown in this [sample implementation](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f).
    
    There are four possible use cases:
    
    a) Guest basket and registered basket exist The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called with the source basket (former registered shopper basket) and the transferred current basket (former guest basket).
    
    b) Guest basket exists but no registered basket exists The guest basket becomes the current basket for the registered shopper by updating the basket's owner (no personal data is removed). The hook dw.order.mergeBasket is called without the source basket (null passed to the hook) and the transferred current basket (former guest basket).
    
    c) No guest basket exists but a registered basket exists The registered basket is retained. The hook dw.order.mergeBasket is called with the retained current basket but without the source basket (null passed to the hook).
    
    d) Neither basket exists The hook dw.order.mergeBasket is not called.
    
    The API returns the current basket (after executing dw.order.mergeBasket).
    
      
    Default: `false`. Example: `false`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** The basket's `isTemporary` flag has been cleared. For regular shopper baskets the result is a storefront basket; agent baskets remain agent baskets.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketPutStorefront_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "callcenter",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **409** The call returns this response when the `merge` request parameter is set to `false` and the shopper has a pre-existing storefront basket and `overrideExisting` is set to `false` (default value).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotPromotableException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-promotable-exception",
      "title": "Conflict",
      "detail": "The basket with ID 'a10ff320829cb0eef93ca5310a' cannot be promoted to a storefront basket in its current state."
    }
    ```
    

#### Extension points

*   `dw.order.mergeBasket` (service-logic) Called when merge=true and the shopper has a pre-existing storefront basket. Merges the pre-existing basket into the promoted basket.
*   `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.beforePOST` (before) Called before promoting the temporary basket. The default implementation does nothing.
*   `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.afterPOST` (after) Called after promoting the temporary basket. The default implementation calls the calculate hook, which recalculates the promoted basket.
*   `sfcc.checkout.shopper-baskets.v2.baskets.basketId.actions.promote.modifyPOSTResponse` (modifyResponse) Called to modify the basket returned in the response after promotion. The default implementation does nothing.

### PUT Designate a basket as an agent basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/agent`

Operation ID: `updateAsAgentBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw).

Marks a basket as an agent basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Responses

*   **200** Success, the response body contains basket that is set as an agent basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BasketPutAgent_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": true,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** Marking this basket as an agent basket would exceed the open agent basket limit for the basket customer.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomerInfoJwtMismatch: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add a billing address to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/billing-address`

Operation ID: `updateBillingAddressForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets the billing address of a basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `useAsShipping` (query, boolean) When true, the address is also used as the shipping address.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `OrderAddress`.

_Example: BillingAddressPut_

```
{
  "firstName": "Stephanie",
  "lastName": "Miller",
  "address1": "385  Prospect Valley Road",
  "city": "Woburn",
  "postalCode": "01801",
  "stateCode": "MA",
  "countryCode": "US"
}
```

#### Responses

*   **200** Success, the response body contains basket with the added billing address.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BillingAddress_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "385  Prospect Valley Road",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "7800e0f611dac6caf77afb9df9",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:53:30.993Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:53:35.747Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "2b76b8644eb6da43e7e223b48d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "43c38652bc3844e14cd482ff28",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "b4ff13039bc7abd1b9d933b871",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "193e99bc1205b870cebd36d970",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "ac7a3b62dc1df8de898d7a2141",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add a coupon to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/coupons`

Operation ID: `addCouponToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a coupon to an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CouponItem`.

_Example: CouponCodePost_

```
{
  "code": "10_percent_off"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added coupon.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: CouponCodePost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        },
        {
          "code": "10_percent_off",
          "couponItemId": "9372d0f511dac8caf77afc4kj2",
          "statusCode": "applied",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible Reasons:
    
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the coupon number is not provided.
    *   the coupon code specified is invalid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a coupon from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/coupons/{couponItemId}`

Operation ID: `removeCouponFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a coupon from the basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `couponItemId` (path, CouponItemId, required) The ID of the coupon item.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted coupon.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example Basket: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the couponItemId URL parameter does not match any coupon item ID in the basket.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add shopper information to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/customer`

Operation ID: `updateCustomerForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets customer information for an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerInfo`.

_Example: BillingAddressPut_

```
{
  "email": "shopperUpdate@salesforce-test.com"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added customer information.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: BillingAddress_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopperUpdate@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the customer cannot be set to the basket because the max number of baskets per customer would be exceeded.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the customer with the given customer number is unknown.
    *   the basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add a gift certificate to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items`

Operation ID: `addGiftCertificateItemToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a gift certificate item to an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `GiftCertificateItem`.

_Example: GiftCertificateItemPost_

```
{
  "amount": 1,
  "recipientEmail": "miller@salesforce-test.com",
  "shipmentId": "me"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added gift certificate.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: GiftCertPost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopperUpdate@salesforce-test.com"
      },
      "giftCertificateItems": [
        {
          "amount": 2,
          "giftCertificateItemId": "83726a8351540534af93f3b15f",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** The gift certificate item amount is negative.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the shipment with the given shipment ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a gift certificate from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}`

Operation ID: `removeGiftCertificateItemFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Deletes a gift certificate item from an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `giftCertificateItemId` (path, GiftCertificateItemId, required) the ID of the gift certificate item to be updated.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted gift certificate.
    
    Media type: `application/json`. Schema: `Basket`.
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the gift certificate item with the given gift certificate item ID is unknown.

### PATCH Update gift certificate information for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}`

Operation ID: `updateGiftCertificateItemInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a gift certificate item of an existing basket.

#### Parameters

*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `giftCertificateItemId` (path, GiftCertificateItemId, required) the ID of the gift certificate item to be updated.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `GiftCertificateItem`.

_Example: GiftCertificateItemPost_

```
{
  "amount": 1,
  "recipientEmail": "miller@salesforce-test.com"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated gift certificate.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: GiftCertPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopperUpdate@salesforce-test.com"
      },
      "giftCertificateItems": [
        {
          "amount": 1,
          "giftCertificateItemId": "83726a8351540534af93f3b15f",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400** The gift certificate item amount is negative.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the gift certificate item with the given gift certificate item ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add an item to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/items`

Operation ID: `addItemToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds new items to a basket. The added items are associated with the specified shipment. If no shipment id is specified, the added items are associated with the default shipment. Considered values from the request body, for each item are:

*   productId: a valid product ID. This is the ID of the product to be added to the basket. If the product is already in the basket, the API either increments the quantity of the existing product line item or creates a new product line item, based on the site preference 'Add Product Behavior'. For option products and product bundles containing variation masters, the API creates a new product line item regardless of the site preference.
*   shipmentId: a valid shipment ID (optional). This is the ID of the shipment in which the product item is created.
*   quantity: a number between 0.01 and 999. This is the quantity of the product to order.
*   inventoryId: a valid inventory ID (optional). This is the ID of the inventory from which the item is allocated.
*   bonusDiscountLineItemId: a valid bonus discount line item ID (optional). This is the ID of the bonus discount line item for which the added product is a selected bonus product.
*   optionItems/optionValueId: a valid option value ID. This is an option value for an option item of an option product. This is only possible if the product item is an option product. To set option values, you must specify a collection of option items in the optionItems property. These option items must contain optionId and optionValueId. Also, the values you specify must be valid for the option product that this product item represents. Otherwise, the server throws an InvalidProductOptionItemException or an InvalidProductOptionValueItemException.
*   custom properties in the form c\_<CUSTOM\_NAME>: the custom property must correspond to a custom attribute (<CUSTOM\_NAME>) defined for ProductLineItem. The value of this property must be valid for the type of custom attribute defined for ProductLineItem.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `array of BasketProductItem`.

Array of `BasketProductItem`.

_Example: ItemPost_

```
[
  {
    "productId": "green-bag",
    "quantity": 1
  }
]
```

#### Responses

*   **200** Success, the response body contains the basket with the added items.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   the given product ID is null or invalid.
    *   the product with the given product ID is unknown, offline or not assigned to site catalog or the given product item quantity is null or invalid.
    *   a null quantity value.
    *   the requested product quantity is not available.
    *   the product cannot be added to the basket because of its type.
    *   an option with the specified option ID is unknown.
    *   an option with the specified option value ID is unknown.
    *   the maximum allowed number of products added to the basket, has been exceeded.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    *   the provided bonus discount line item ID is not present in the current basket.
    *   the quantity of the product to be added will result in the number of selected bonus choice products to exceed the amount that the user is permitted to select.
    *   the selected bonus product is not an applicable product for the bonus discount line item provided. body: application/problem+json: type: ErrorResponse examples: dataTypes.ErrorResponse: !include exchange\_modules/893f605e-10e2-423a-bdb4-f952f56eb6d8/checkout-data-types/2.0.6/examples/errors/bad-request-example.raml
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the basket does not contain a shipment with the given shipment ID.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a basket item.

`PATCH /organizations/{organizationId}/baskets/{basketId}/items`

Operation ID: `updateItemsInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates multiple items in a basket. This behaviour matches that of updating a single item, but the body contains an array of ProductItems to be updated that are identified by `itemId`. The items to update can include bundled product items, although the kind of update supported for bundled product items is limited to `productId`, `gift`, `giftMessage` and custom properties. The following values in the request body are considered by the server:

*   `itemId` (mandatory): identifies an item to be updated.
*   `productId`: a valid product ID. The purpose of this value is to change the variation of a variation product.
*   `shipmentId`: a valid shipment ID. The purpose of this value is to move a product item to another shipment.
*   `quantity`: a number between 0 and 999. The purpose of this value is to change the quantity of the product item. If the quantity is 0, the product item is removed.
*   `optionItems`/`optionValueId`: a valid option value ID. The purpose of this value is to exchange an option value for an option item of an option product. This is only possible if the product item is an option product. To change option values, a collection of the option items to be changed must be provided in the property `optionItems`. Those `optionItems` must contain `optionId` and `optionValueId`. The provided values must be valid for the option product that this product item represents. Otherwise, `InvalidProductOptionItemException` or `InvalidProductOptionValueItemException` is thrown.
*   custom properties `c_<CUSTOM_NAME>`: a value corresponding to the type defined for custom attribute `<CUSTOM_NAME>` of the ProductLineItem. The purpose of this value is to add or change the value of a custom attribute defined for the ProductLineItem.
*   `gift`: a boolean value that specifies whether the item is a gift.
*   `giftMessage`: a message to include with the gift.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `array of BasketProductItem`.

Array of `BasketProductItem`.

_Example: ItemPatch_

```
{
  "quantity": 1
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated item.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   no product item with a given item ID was found for the basket.
    *   the product with the given product ID in the request body is invalid.
    *   a null quantity value.
    *   an option with a specified option ID is unknown.
    *   an option with a specified option value ID is unknown.
    *   the given shipment ID is invalid.
    *   the customer assigned to the basket does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** Possible reasons: basket not found

### DELETE Remove an item from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/items/{itemId}`

Operation ID: `removeItemFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a product item from the basket.

#### Parameters

*   `itemId` (path, ItemId, required) The ID of the item to be updated.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted item.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update an item in a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/items/{itemId}`

Operation ID: `updateItemInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates an item in a basket. The item to be updated can be a bundled product item, although the kind of update supported for bundled product items is limited to `productId` (to support variation products), `gift`, `giftMessage` and custom properties. The following values in the request body are considered by the server:

*   `productId`: a valid product ID. The purpose of this value is to exchange a variation of a variation product.
*   `shipmentId`: a valid shipment ID. The purpose of this value is to move a product item to another shipment.
*   `quantity`: a number between 0 and 999. The purpose of this value is to change quantity of the product item. If quantity is 0, the product item is removed.
*   `optionItems`/`optionValueId`: a valid option value ID. The purpose of this value is to exchange an option value for an option item of an option product. This is only possible if the product item is an option product. To change option values a collection of option items to be changed need to be provided in property optionItems. Those optionItems need to contain optionId and `optionValueId`. The provided values must be valid for the option product that this product item represents. Otherwise, `InvalidProductOptionItemException` or `InvalidProductOptionValueItemException` is thrown.
*   custom properties `c_<CUSTOM_NAME>`: a value corresponding to the type defined for custom attribute `<CUSTOM_NAME>` of ProductLineItem. The purpose of this value is to add or change the value of a custom attribute defined for ProductLineItem.
*   `gift`: a boolean value that specifies whether the item is a gift
*   `giftMessage`: a message for the gift

#### Parameters

*   `itemId` (path, ItemId, required) The ID of the item to be updated.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `BasketProductItem`.

_Example: ItemPatch_

```
{
  "quantity": 1
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated item.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   no product item with given item ID was found for the basket.
    *   the product with the given product ID in the request body is invalid.
    *   a null quantity value.
    *   an option with the specified option id is unknown.
    *   an option with the specified option value id is unknown.
    *   the given shipment ID is invalid.
    *   the customer assigned to the basket does not. match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   a shipment with it's given ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add taxation information for a basket item.

`PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes`

Operation ID: `addTaxesForBasketItem`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw).

This method allows you to apply external taxation data to an existing basket to be able to pass tax rates and optional values for a specific taxable line item. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `itemId` (path, ItemId, required) The ID of the item to be updated.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `TaxItems`.

_Example: BasketItemTaxPut_

```
{
  "taxItems": [
    {
      "id": "DE_7",
      "rate": 0.07,
      "value": 13.99
    },
    {
      "id": "DE_19",
      "rate": 0.19
    }
  ]
}
```

#### Responses

*   **204** Success, without body.
*   **404**
    
    Possible reasons:
    
    *   The basket with the given basket ID is unknown.
    *   The item with the given item ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    
*   **409**
    
    Possible Reasons:
    
    *   The tax mode of the referenced basket is not set to EXTERNAL.
    *   One or more tax item custom attributes are invalid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnsupportedRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-request-if-scapi-hooks-enabled",
      "title": "Unsupported Request If SCAPI Hooks Enabled",
      "detail": "You can't call this endpoint because Salesforce Commerce API hook execution is enabled."
    }
    ```
    

### POST Add a payment instrument to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/payment-instruments`

Operation ID: `addPaymentInstrumentToBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a payment instrument to a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `BasketPaymentInstrumentRequest`.

_Example: PaymentInstrumentPost_

```
{
  "amount": 1,
  "paymentCard": {
    "expirationYear": 1990,
    "expirationMonth": 7,
    "validFromMonth": 8,
    "validFromYear": 2007,
    "issueNumber": "i117",
    "maskedNumber": "*********1234",
    "holder": "Miller",
    "cardType": "Visa"
  },
  "paymentMethodId": "CREDIT_CARD"
}
```

_Example: PaymentInstrumentPostWithSalesforcePayments_

```
{
  "amount": 15,
  "paymentMethodId": "Salesforce Payments",
  "paymentReferenceRequest": {
    "paymentMethodType": "paypal",
    "zoneId": "Amer-Zone",
    "gatewayProperties": {
      "paypal": {
        "shippingPreference": "SET_PROVIDED_ADDRESS"
      }
    }
  }
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added payment instrument.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketsPostSuccess: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   the provided payment method is invalid or not applicable.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a payment instrument from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/payment-instruments/{paymentInstrumentId}`

Operation ID: `removePaymentInstrumentFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a payment instrument of a basket.

#### Parameters

*   `paymentInstrumentId` (path, PaymentInstrumentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted payment instrument.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the payment instrument with the given basket payment instrument ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a payment instrument for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/payment-instruments/{paymentInstrumentId}`

Operation ID: `updatePaymentInstrumentInBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates payment instrument of an existing basket.

#### Parameters

*   `paymentInstrumentId` (path, PaymentInstrumentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `BasketPaymentInstrumentRequest`.

_Example: PaymentInstrumentPatch_

```
{
  "amount": 0,
  "paymentCard": {
    "holder": "Miller",
    "cardType": "Visa"
  },
  "paymentMethodId": "CREDIT_CARD"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated payment instrument.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: PaymentInstrumentPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false,
            "holder": "Miller"
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the provided payment method is invalid or not applicable.
    *   the basket payment intsrument with the given id is already permanently masked.
    *   The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   the basket with the given basket ID is unknown.
    *   the payment instrument item with the given payment instrument ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### GET Retrieve payment instruments for a basket.

`GET /organizations/{organizationId}/baskets/{basketId}/payment-methods`

Operation ID: `getPaymentMethodsForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Gets applicable payment methods for an existing basket considering the open payment amount only.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the applicable payment methods for the basket.
    
    Media type: `application/json`. Schema: `PaymentMethodResult`.
    
    _Example: PaymentMethodsGet_
    
    ```
    {
      "applicablePaymentMethods": [
        {
          "id": "GIFT_CERTIFICATE",
          "name": "Gift Certificate",
          "paymentProcessorId": "BASIC_GIFT_CERTIFICATE"
        },
        {
          "cards": [
            {
              "cardType": "Visa",
              "checksumVerificationEnabled": true,
              "name": "Visa",
              "numberLengths": [
                "13",
                "16"
              ],
              "numberPrefixes": [
                "4"
              ]
            },
            {
              "cardType": "Amex",
              "checksumVerificationEnabled": true,
              "name": "American Express",
              "numberLengths": [
                "15"
              ],
              "numberPrefixes": [
                "34",
                "37"
              ]
            },
            {
              "cardType": "Master Card",
              "checksumVerificationEnabled": true,
              "name": "MasterCard",
              "numberLengths": [
                "16"
              ],
              "numberPrefixes": [
                "51-55"
              ]
            },
            {
              "cardType": "Discover",
              "checksumVerificationEnabled": true,
              "name": "Discover",
              "numberLengths": [
                "16"
              ],
              "numberPrefixes": [
                "6011",
                "622126-622925",
                "644-649",
                "65"
              ]
            }
          ],
          "id": "CREDIT_CARD",
          "name": "Credit Card",
          "paymentProcessorId": "BASIC_CREDIT"
        },
        {
          "id": "PayPal",
          "name": "Pay Pal",
          "paymentProcessorId": "PAYPAL_EXPRESS"
        },
        {
          "id": "BML",
          "name": "Bill Me Later",
          "paymentProcessorId": "CYBERSOURCE_BML"
        }
      ]
    }
    ```
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Add a price adjustment to a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/price-adjustments`

Operation ID: `addPriceAdjustmentToBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a custom manual price adjustment to the basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PriceAdjustmentRequest`.

_Example: PriceAdjustmentPost_

```
{
  "discount": {
    "value": 5,
    "type": "percentage"
  },
  "itemText": "MyOrderAdjustment",
  "level": "order",
  "promotionId": "manual adjustment"
}
```

#### Responses

*   **200** Success, the response body contains the basket with added price adjustment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: PriceAdjustmentPost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 28.45,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 0.05,
            "percentage": 5,
            "type": "percentage"
          },
          "createdBy": "testAgent",
          "creationDate": "2015-05-25T09:13:10.942Z",
          "custom": true,
          "itemText": "MyOrderAdjustment",
          "manual": true,
          "price": -30,
          "promotionId": "manual adjustment",
          "priceAdjustmentId": "cdzoAiWbOmbiUaaadlfSpMDgNw"
        }
      ],
      "orderTotal": 615.21,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 569.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 569.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 569.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   a fixed price adjustment was already created for the given level.
    *   a fixed price adjustment was added at `order` level.
    *   a promotion ID was used twice.
    *   a system promotion ID was used as a manual promotion ID.
    *   more than one hundred price adjustments would have been created.
    *   the price adjustment limit had exceeded.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a price adjustment from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/price-adjustments/{priceAdjustmentId}`

Operation ID: `removePriceAdjustmentFromBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a custom manual price adjustment from the basket.

#### Parameters

*   `priceAdjustmentId` (path, PriceAdjustmentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Responses

*   **200** Success, the response body contains the basket without the deleted price adjustment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400** The priceAdjustmentId is missing, empty or whitespace.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a price adjustment for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/price-adjustments/{priceAdjustmentId}`

Operation ID: `updatePriceAdjustmentInBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a custom manual price adjustment on the basket. Only the following path values are considered for the update; all other attributes are ignored.

*   `discount`
*   `itemText`
*   `reasonCode`
*   `custom properties` The discount `type` of a price adjustment cannot be updated and therefore, the value of the existing type must be passed. For an adjustment of type `percentage`, the `percentage` attribute is mandatory. For adjustments of type `amount` and `fixed_price`, the `amount` attribute is mandatory.

#### Parameters

*   `priceAdjustmentId` (path, PriceAdjustmentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `PriceAdjustment`.

_Example: PriceAdjustmentPatch_

```
{
  "appliedDiscount": {
    "amount": 15,
    "type": "amount"
  },
  "itemText": "AgentOrderAdjustment",
  "reasonCode": "override manual promo"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated price adjustment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: PriceAdjustmentPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 15,
            "type": "amount"
          },
          "createdBy": "testWapiAgent",
          "creationDate": "2017-03-14T09:15:35.543Z",
          "custom": true,
          "itemText": "MyOrderAdjustment",
          "lastModified": "2017-03-14T09:15:35.594Z",
          "manual": true,
          "price": -15,
          "priceAdjustmentId": "e397cd21f9a9c0643277ba1011",
          "promotionId": "manual adjustment",
          "reasonCode": "override manual promo"
        }
      ],
      "orderTotal": 631.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "4432af77112f7c2433248a48e8",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the price adjustment is not manual and cannot be updated.
    *   the expected attributes are missing in the input.
    *   the type of a price adjustment does not match the adjustment type of the input data.
    *   the price adjustment limit is exceeded.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The price adjustment ID is not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: PriceAdjustmentIdNotFoundException_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/price-adjustment-not-found",
      "title": "Price Adjustment Not Found",
      "detail": "No price adjustment with ID '453599643347eac5e4ebd85b49' could be found."
    }
    ```
    

### GET Retrieve price books for a basket.

`GET /organizations/{organizationId}/baskets/{basketId}/price-books`

Operation ID: `getPriceBooksForBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw).

( DEPRECATED ) Gets applicable price books for an existing basket. This endpoint is deprecated. Use [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary), hooks or `dw.catalog.PriceBookMgr#getApplicablePriceBooks()` instead.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the priceBookIds for the basket.
    
    Media type: `application/json`. Schema: `PriceBookIds`.
    
    _Example: PriceBooksGet_
    
    ```
    [
      "price-book-id1",
      "price-book-id2"
    ]
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Add price books to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/price-books`

Operation ID: `addPriceBooksToBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw).

( DEPRECATED ) This method allows you to put an array of priceBookIds to an existing basket, which will be used for basket calculation. This endpoint is deprecated.  
Use [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary), hooks or `dw.catalog.PriceBookMgr#setApplicablePriceBooks()` instead.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `PriceBookIds`.

_Example: PriceBooksPut_

```
[
  "price-book-id1",
  "price-book-id2"
]
```

#### Responses

*   **204** Success, without body.
*   **404** The basket with the given basket ID is unknown or contains a price book ID that does not correspond to an existing price book.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Create a shipment for a basket.

`POST /organizations/{organizationId}/baskets/{basketId}/shipments`

Operation ID: `createShipmentForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Creates a new shipment for a basket.

The created shipment is initialized with values provided in the body document and can be updated with further data API calls. Considered from the body are the following properties if specified:

*   the ID
*   the shipping address
*   the shipping method
*   gift boolean flag
*   gift message
*   custom properties

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Shipment`.

_Example: ShipmentsPost_

```
{
  "shipmentId": "me2",
  "shippingMethod": {
    "id": "001"
  },
  "shippingAddress": {
    "firstName": "Stephanie",
    "lastName": "Miller",
    "address1": "385  Prospect Valley Road",
    "city": "Woburn",
    "postalCode": "01801",
    "stateCode": "MA",
    "countryCode": "US"
  }
}
```

#### Responses

*   **200** Success, the response body contains the basket with added shipment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsPost_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek"
          },
          "shippingMethod": {
            "description": "Order received in 2 business days",
            "id": "002",
            "name": "2-Day Express",
            "price": 20.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 20.99,
          "shippingTotalTax": 1.05,
          "taxTotal": 36.05
        },
        {
          "adjustedMerchandizeTotalTax": 35,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 35,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me2",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "385  Prospect Valley Road",
            "city": "Woburn",
            "stateCode": "MA",
            "countryCode": "US",
            "firstName": "Stephanie",
            "fullName": "Stephanie Miller",
            "id": "84f06786daa68ae33af7e21ec6",
            "lastName": "Miller"
          },
          "shippingMethod": {
            "description": "Order received in 2 business days",
            "id": "001",
            "name": "2-Day Express",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 35
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 1.05,
          "basePrice": 20.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 20.99,
          "priceAfterItemDiscount": 20.99,
          "shipmentId": "me",
          "tax": 1.05,
          "taxBasis": 20.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        },
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "6fea9966277c94e06b482a5c43",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 36.98,
      "shippingTotalTax": 1.35,
      "taxation": "net",
      "taxTotal": 36.35
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   a shipment id is not provided.
    *   a shipment with the provided ID already. exists for the basket.
    *   a shipment with the provided shipment number already exists for the basket.
    *   a shipping method with an ID was specified which is not a valid shipping method ID.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### DELETE Remove a shipment from a basket.

`DELETE /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}`

Operation ID: `removeShipmentFromBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a specified shipment and all associated product, gift certificate, shipping, and price adjustment line items from a basket. It is not allowed to remove the default shipment.

#### Parameters

*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the basket without the deleted shipment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPost: same as POST /organizations/{organizationId}/baskets 200 response._
    
*   **400**
    
    Possible reasons:
    
    *   the given shipment ID is invalid.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **403** The given shipment ID corresponds to the default shipment and cannot be removed.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "The shipment with ID 'me' corresponds to the default shipment and can't be deleted."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PATCH Update a shipment for a basket.

`PATCH /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}`

Operation ID: `updateShipmentForBasket`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a shipment for a basket.

The shipment is initialized with values provided in the body document and can be updated with further data API calls. Considered from the body are the following properties if specified:

*   the ID
*   the shipping address
*   the shipping method
*   gift boolean flag
*   gift message
*   custom properties

#### Parameters

*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Shipment`.

_Example: ShipmentsPatch_

```
{
  "shipmentId": "me",
  "shipmentNo": "ignored shipment no",
  "shippingMethod": {
    "id": "003"
  },
  "shippingAddress": {
    "firstName": "Ward J",
    "lastName": "Adamek",
    "address1": "4911  Lincoln Street",
    "city": "IDANHA",
    "postalCode": "97350",
    "stateCode": "OR",
    "countryCode": "US"
  },
  "c_wapi-string": "shipment_custom_property"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the updated shipment.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsPatch_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek"
          },
          "shippingMethod": {
            "description": "Order received in 2 business days",
            "id": "002",
            "name": "2-Day Express",
            "price": 20.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 20.99,
          "shippingTotalTax": 1.05,
          "taxTotal": 36.05
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 1.05,
          "basePrice": 20.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 20.99,
          "priceAfterItemDiscount": 20.99,
          "shipmentId": "me",
          "tax": 1.05,
          "taxBasis": 20.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 20.99,
      "shippingTotalTax": 1.05,
      "taxation": "net",
      "taxTotal": 36.05
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the given shipment ID was invalid.
    *   a shipment with the provided ID already exists for the basket.
    *   a shipment with the provided shipment number already exists for the basket.
    *   a missing shipping method.
    *   an invalid shipping method.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Update the shipping address for a shipment.

`PUT /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-address`

Operation ID: `updateShippingAddressForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets a shipping address of a specific shipment of a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `useAsBilling` (query, boolean) When true, the address is also used as the billing address.
*   `removeExternalTax` (query, boolean) If `true` (default value), the external tax rates are removed from the basket and set to null. To add external tax rates to a basket, use the `addTaxesForBasket` or `addTaxesForBasketItem` endpoint. The removal of external tax rates depends on the update performed on the basket, for example: an update to the `currency` triggers a removal. Set this parameter to `false` to disable the removal of external tax rates/values.  
    Default: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `OrderAddress`.

_Example: ShipmentsAddressPut_

```
{
  "firstName": "Ward J",
  "lastName": "Adamek",
  "address1": "4911  Lincoln Street",
  "city": "IDANHA",
  "postalCode": "97350",
  "stateCode": "OR",
  "countryCode": "US"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added shipping address.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsAddressPut_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "postalCode": "97350",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek",
            "stateCode": "OR"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the shipment with the given shipment ID is unknown.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Update the shipping method for a shipment.

`PUT /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-method`

Operation ID: `updateShippingMethodForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Sets a shipping method to a specific shipment of a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ShippingMethod`.

_Example: ShipmentsMethodPut_

```
{
  "id": "003"
}
```

#### Responses

*   **200** Success, the response body contains the basket with the added shipping method.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example: ShipmentsMethodPut_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "agentBasket": false,
      "basketId": "a10ff320829cb0eef93ca5310a",
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "bfea663fd3de75d5be3ec02702",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "cc6ef43f207bf64099288aec36",
          "statusCode": "no_applicable_promotion",
          "valid": true
        }
      ],
      "creationDate": "2019-10-17T08:29:55.340Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "email": "shopper@salesforce-test.com"
      },
      "lastModified": "2019-10-17T08:29:55.698Z",
      "merchandizeTotalTax": 30,
      "orderTotal": 646.76,
      "paymentInstruments": [
        {
          "amount": 0,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "b7679bea661819b2de78b9de7d",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "3d4e28425ce0b3a65b0ac4e163",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "ff9452ed11fcf5c80f9143a8f1",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.97,
          "priceAfterItemDiscount": 599.97,
          "priceAfterOrderDiscount": 599.97,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4911  Lincoln Street",
            "postalCode": "97350",
            "city": "IDANHA",
            "countryCode": "US",
            "firstName": "Ward J",
            "fullName": "Ward J Adamek",
            "id": "b3e1269a2c1d0ad56694206741",
            "lastName": "Adamek",
            "stateCode": "OR"
          },
          "shippingMethod": {
            "description": "Order received the next business day",
            "id": "003",
            "name": "Overnight",
            "price": 29.99
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 29.99,
          "shippingTotalTax": 1.5,
          "taxTotal": 36.5
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 1.5,
          "basePrice": 29.99,
          "itemId": "d5ed0e58b8f8b5efe8d617a630",
          "itemText": "Shipping",
          "price": 29.99,
          "priceAfterItemDiscount": 29.99,
          "shipmentId": "me",
          "tax": 1.5,
          "taxBasis": 29.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 29.99,
      "shippingTotalTax": 1.5,
      "taxation": "net",
      "taxTotal": 36.5
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the id of the shipping method is missing.
    *   a shipping method with an ID was specified which is not a valid shipping method ID.
    *   the customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### GET Retrieve the shipping methods for a shipment.

`GET /organizations/{organizationId}/baskets/{basketId}/shipments/{shipmentId}/shipping-methods`

Operation ID: `getShippingMethodsForShipment`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Gets the applicable shipping methods for a certain shipment of a basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `shipmentId` (path, ShipmentId, required) The ID of the shipment to be modified.
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the applicable shipping methods for a certain shipment of the basket.
    
    Media type: `application/json`. Schema: `ShippingMethodResult`.
    
    _Example: ShipmentsMethodGet_
    
    ```
    {
      "applicableShippingMethods": [
        {
          "description": "Order received within 7-10 business days",
          "id": "001",
          "name": "Ground",
          "price": 15.99,
          "deliveryWindow": {
            "startAt": "2026-05-04T14:00:00Z",
            "endAt": "2026-05-07T22:00:00Z"
          },
          "orderCutoffAt": "2026-04-27T14:00:00Z"
        },
        {
          "description": "Order received in 2 business days",
          "id": "002",
          "name": "2-Day Express",
          "price": 20.99,
          "deliveryWindow": {
            "startAt": "2026-04-29T14:00:00Z",
            "endAt": "2026-04-29T22:00:00Z"
          },
          "orderCutoffAt": "2026-04-27T14:00:00Z"
        },
        {
          "description": "Order received the next business day",
          "id": "003",
          "name": "Overnight",
          "price": 29.99
        },
        {
          "description": "Store Pickup",
          "id": "005",
          "name": "Store Pickup",
          "price": 0,
          "c_storePickupEnabled": true
        }
      ],
      "defaultShippingMethodId": "001"
    }
    ```
    
*   **400** The customer assigned to the basket does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomerInfoJwtMismatch_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404**
    
    Possible reasons:
    
    *   The basket with the given basket ID is unknown.
    *   The shipment with the given shipment ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### PUT Designate a basket as a storefront basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/storefront`

Operation ID: `updateAsStorefrontBasket`. Security: ShopperTokenTaob (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Marks a basket as a storefront basket.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `exchange` (query, boolean) If true, an existing storefront basket is exchanged and marked as an agent basket. If false, a `CustomerBasketsQuotaExceededException` is thrown.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    

#### Responses

*   **200** Success, the response body contains a basket that is set as a storefront basket.
    
    Media type: `application/json`. Schema: `Basket`.
    
    _Example BasketPutStorefront: same as POST /organizations/{organizationId}/baskets/{basketId}/actions/promote 200 response._
    
*   **400** Returned if a storefront basket already exists and the query parameter `exchange` is false.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomerBasketQuotaExceededException: same as POST /organizations/{organizationId}/baskets 400 response._
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### GET Retrieve the external taxation information for a basket.

`GET /organizations/{organizationId}/baskets/{basketId}/taxes`

Operation ID: `getTaxesFromBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw).

This method gives you the external taxation data set by the PUT taxes API. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the external taxation from all line items from the referenced basket.
    
    Media type: `application/json`. Schema: `Taxes`.
    
    _Example: PostBasketBody_
    
    ```
    {
      "taxes": {
        "3d4e28425ce0b3a65b0ac4e163": {
          "taxItems": [
            {
              "id": "DE_7",
              "rate": 0.07,
              "value": 13.99
            },
            {
              "id": "DE_19",
              "rate": 0.19
            }
          ]
        },
        "ff9452ed11fcf5c80f9143a8f1": {
          "taxItems": [
            {
              "id": "US_1",
              "rate": 0.01
            },
            {
              "id": "US_5",
              "rate": 0.05
            }
          ]
        }
      }
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    
*   **409**
    
    Possible Reasons:
    
    *   The tax mode of the referenced basket is not set to EXTERNAL.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example UnsupportedRequest: same as PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes 409 response._
    
    _Example: InvalidTaxMode_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-tax-mode",
      "title": "Invalid Tax Mode",
      "detail": "Basket with ID 'a10ff320829cb0eef93ca5310a' has invalid tax mode."
    }
    ```
    

### PUT Add external taxation information to a basket.

`PUT /organizations/{organizationId}/baskets/{basketId}/taxes`

Operation ID: `addTaxesForBasket`. Security: AmOAuth2 (sfcc.shopper-baskets-orders.rw).

This method allows you to apply external taxation data to an existing basket to be able to pass tax rates and optional values for all taxable line items. This endpoint can be called only if external taxation mode was used for basket creation. See POST /baskets for more information.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `basketId` (path, string, required) The ID of the basket to be modified.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Taxes`.

_Example BasketTaxPut: same as GET /organizations/{organizationId}/baskets/{basketId}/taxes 200 response._

#### Responses

*   **204** Success, without body.
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    
*   **409**
    
    Possible Reasons:
    
    *   The tax mode of the referenced basket is not set to EXTERNAL.
    *   One or more tax item custom attributes are invalid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnsupportedRequest: same as PUT /organizations/{organizationId}/baskets/{basketId}/items/{itemId}/taxes 409 response._
    

## Schemas

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### Basket

Document representing a basket.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `agentBasket` (_boolean_) Is the basket created by an agent? It is read only.  
    Example: `true`.
*   `basketId` (_string_) The unique identifier for the basket. It is read only.  
    Example: `e78aa5646a8efebdd9cdd38be7`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `OrderAddress`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `channelType` (_string_) The sales channel. It is read only.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`, `chatgpt`, `gemini`. Example: `storefront`.
*   `couponItems` (_array of CouponItem_) The coupon items.
*   `creationDate` (_string (date-time)_) The timestamp when the basket was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `currency` (_CurrencyCode_)
*   `customerInfo` (_object_) The customer information, if the customer is logged in.
    
    Includes all fields of `CustomerInfo`.
    
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items.
*   `groupedTaxItems` (_array of GroupedTaxItem_) Tax values that are grouped and summed based on the tax rate. The tax totals of the line items with the same tax rate are grouped together and summed up. This does not affect the calculation in any way. It is read only.
*   `inventoryReservationExpiry` (_string (date-time)_) The expiration datetime of the inventory reservation. It is read only.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the basket was last modified. It is read only.  
    Example: `2015-05-19T15:25:18.000Z`.
*   `merchandizeTotalTax` (_number (double)_) The total products tax in the purchase currency. Merchandise total price represents the sum of the product prices before services (such as shipping) or adjustments from promotions have been added. It is read only.  
    Example: `4.95`.
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments.
*   `orderTotal` (_number (double)_) The total price, including products, shipping and tax. It is read only.  
    Example: `110.24`.
*   `paymentInstruments` (_array of OrderPaymentInstrument_) The payment instruments list.
*   `productItems` (_array of BasketProductItem_) The product items.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products including adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `88`.
*   `shipments` (_array of Shipment_) The shipments.
*   `shippingItems` (_array of ShippingItem_) The shipping items.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments. It is read only.  
    Example: `0.3`.
*   `sourceCode` (_string_) The source code assigned to the basket. It is read only.  
    Example: `OUTDOOR1`.
*   `taxTotal` (_number (double)_) The total tax amount. It is read only.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net). It is read only.  
    Allowed values: `gross`, `net`. Example: `net`.
*   `taxRoundedAtGroup` (_boolean_) If the tax is rounded at the group level, this is set to true. If the tax is rounded at the item or unit level, it is set to false.  
    Example: `true`.
*   `temporaryBasket` (_boolean_) If the created basket is a temporary basket, this is set to true. Otherwise, it is set to false.  
    Example: `true`.
*   `approachingDiscounts` (_array of ApproachingDiscount_) A list of approaching discount objects for the basket. The list includes both order-level and shipping-level promotions. This field is only included when the expand query parameter contains 'approaching\_discounts'.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### OrderAddress

Document representing an order address.

*   `address1` (_string_) The first address line.  
    Example: `45 Main Rd.`.
*   `address2` (_string_) The second address line.  
    Example: `Apartment 204`.
*   `city` (_string_) The city.  
    Example: `Boston`.
*   `companyName` (_string_) The company name.  
    Example: `Salesforce`.
*   `countryCode` (_CountryCode_)
*   `firstName` (_string_) The first name.  
    Example: `Max`.
*   `fullName` (_string_) The full name.  
    Example: `Max Mustermann`.
*   `id` (_string_) The ID of the address.  
    Example: `me`.
*   `jobTitle` (_string_) The job title.  
    Example: `Software Engineer`.
*   `lastName` (_string_) The last name.  
    Example: `Mustermann`.
*   `phone` (_string_) The phone number.  
    Example: `6175555555`.
*   `postBox` (_string_) The post office box.  
    Example: `PO BOX 109`.
*   `postalCode` (_string_) The postal code.  
    Example: `05408`.
*   `salutation` (_string_) The salutation.  
    Example: `Mr`.
*   `secondName` (_string_) The second name.
*   `stateCode` (_string_) The state code.  
    Example: `MA`.
*   `suffix` (_string_) The suffix.  
    Example: `Sr`.
*   `suite` (_string_) The suite.  
    Example: `24A`.
*   `title` (_string_) The title.  
    Example: `Dr.`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CouponItem

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256. Example: `5ties`.
*   `couponItemId` (_object_) The coupon item ID. It is read only.
    
    Includes all fields of `CouponItemId`.
    
*   `statusCode` (_string_) The status of the coupon item. It is read only.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`. Example: `no_applicable_promotion`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is "applied" or "no\_applicable\_promotion". It is read only.  
    Example: `true`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CouponItemId

The coupon item ID

Type: `string`.

Minimum length: 1. Example: `d4c9c0141e9c74c150225580f3`.

### CustomerInfo

The customer information for guest or logged-in customers.

*   `customerId` (_string_) The customer ID. It is read only.  
    Maximum length: 100. Example: `abMKqMaNYOBMnNdDNzyC5oNTi5`.
*   `customerName` (_string_) The customer name.  
    Example: `Max Mustermann`.
*   `customerNo` (_string_) The customer number.  
    Maximum length: 100. Example: `0002352`.
*   `email` (_string_, required) The customer's email address.  
    Example: `no-reply@salesforce.com`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GiftCertificateItem

A gift certificate item.

*   `amount` (_number (double)_, required) The gift certificate item amount.  
    Example: `20`.
*   `giftCertificateItemId` (_object_) The item ID. It is read only.
    
    Includes all fields of `GiftCertificateItemId`.
    
*   `message` (_string_) The gift certificate message.  
    Maximum length: 4000. Example: `Birthday present.`.
*   `recipientEmail` (_string_, required) The recipient email.  
    Minimum length: 1. Example: `no-reply@salesforce.com`.
*   `recipientName` (_string_) The recipient's name.  
    Example: `Daniel Mustermann`.
*   `senderName` (_string_) The sender's name.  
    Example: `Max Mustermann`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GiftCertificateItemId

Type: `string`.

Minimum length: 1. Example: `629dea6e7b61e58da629b57b21`.

### BasketProductItem

Document representing a basket product item.

Includes all fields of `ProductItem`.

### ItemId

The item id.

Type: `string`.

Example: `430ef5aad3a24de59378458434`.

### TaxItems

Taxation for a line item.

*   `taxItems` (_array of TaxItem_) The list of tax items. It is read only.

### BasketPaymentInstrumentRequest

Document representing a basket payment instrument request.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `12030000`.
*   `giftCertificateCode` (_string_) The gift certificate code.  
    Maximum length: 256. Example: `AFGRTUZ`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `OrderPaymentCardRequest`.
    
*   `giftCardRequest` (_object_) The gift card request.
    
    Includes all fields of `GiftCardRequest`.
    
*   `paymentMethodId` (_string_) The payment method ID.  
    Maximum length: 256. Example: `CREDIT_CARD`.
*   `paymentReferenceRequest` (_object_) Payment reference information for various payment service providers, only when Salesforce Payments is enabled.
    
    Includes all fields of `PaymentReferenceRequest`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentInstrumentId

The payment instrument ID

Type: `string`.

Example: `ba248424e3eee797f062162f8b`.

### PaymentMethodResult

Result document of payment methods applicable for a basket.

*   `applicablePaymentMethods` (_array of PaymentMethod_) The applicable payment methods. It is read only.

### PriceAdjustmentRequest

Request that represents a price adjustment.

*   `discount` (_object_) A discount that can be specified instead of a price.
    
    Includes all fields of `DiscountRequest`.
    
*   `itemId` (_string_) The item to which the price adjustment should be added, depending on the specified level. If the level is ´order´, item id is not needed. If `shipping`, specify the UUID of the shipping item. If `product`, specify the UUID of the product item.  
    Example: `93196fae953cbedbe54d67e760`.
*   `itemText` (_string_) The text describing the item in more detail.  
    Example: `A discounted item`.
*   `level` (_string_, required)
    
    The level at which the adjustment is applied.
    
    *   `order` indicates that the price adjustment should be added directly to basket.
    *   `product` indicates that the price adjustment should be added to the product item.
    *   `shipping` indicates that the price adjustment is added to the shipping item.
    
      
    Allowed values: `product`, `shipping`, `order`. Example: `order`.
*   `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID as long as it's not used by a price adjustment belonging to the same item and isn't used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated.  
    Example: `Shipping100`.
*   `reasonCode` (_string_) The reason for the price adjustment.  
    Example: `Shipping promotion on order above $1,000 USD`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceAdjustmentId

Type: `string`.

Example: `ba248424e3eee797f062161f8b`.

### PriceAdjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level.

*   `appliedDiscount` (_object_) Details describing the discount this price adjustment is based on. For adjustments not based on a discount, this value is null.
    
    Includes all fields of `Discount`.
    
*   `couponCode` (_string_) The coupon code of the coupon this price adjustment is based on. For adjustments not based on a coupon, this value is null. It is read only.  
    Example: `5ties`.
*   `createdBy` (_string_) The user who created the price adjustment. It is read only.  
    Example: `Support`.
*   `creationDate` (_string (date-time)_) The timestamp when the price adjustment was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.  
    Example: `true`.
*   `itemText` (_string_) The text describing the item.
*   `lastModified` (_string (date-time)_) The timestamp when the price adjustment was last modified. It is read only.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `manual` (_boolean_) A flag indicating whether this price adjustment was created by a manual process. If the price adjustment was created by the promotion engine, this value is always false.  
    Example: `true`.
*   `price` (_number (double)_) The adjustment price. It is read only.  
    Example: `120.88`.
*   `priceAdjustmentId` (_object_) The price adjustment ID. It is read only.
    
    Includes all fields of `PriceAdjustmentId`.
    
*   `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID so long it is not used by a price adjustment belonging to the same item, and is not used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated.
*   `reasonCode` (_string_) The reason for the price adjustment.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceBookIds

Array of price book IDs to use for the basket calculation.

Array of `string`.

Items: Maximum length: 256. Maximum items: 10.

### Shipment

Document representing a shipment.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `deliveryWindow` (_object_) The estimated delivery window for the shipment. The sfcc.app.shipping.calculate hook populates this value from the selected shipping method. The response omits this field if the hook doesn't return a delivery window. This field is reserved for future use and will be supported in an upcoming release.
    
    Includes all fields of `DeliveryWindow`.
    
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, not including price adjustments or service charges such as shipping. It is read only.  
    Example: `4.95`.
*   `orderCutoffAt` (_string (date-time)_) The timestamp by which an order must be placed for the deliveryWindow to apply, as an RFC 3339 date-time. The sfcc.app.shipping.calculate hook populates this value from the selected shipping method. The response omits this field if the hook doesn't return a cutoff time. This field is reserved for future use and will be supported in an upcoming release.  
    Example: `2026-04-27T14:00:00Z`.
*   `productSubTotal` (_number (double)_) The total price of all products in the shipment, including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `shipmentId` (_object_) The order-specific ID of the shipment. The default value is 'me'.  
    Default: `me`.
    
    Includes all fields of `ShipmentId`.
    
    Default: `me`.
    
*   `shipmentNo` (_string_) The shipment number of this shipment. This number is automatically generated. It is read only.
*   `shipmentTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments, shipping charges, and tax. It is read only.  
    Example: `39.99`.
*   `shippingAddress` (_object_) The shipping address.
    
    Includes all fields of `OrderAddress`.
    
*   `shippingMethod` (_ShippingMethod_)
*   `shippingStatus` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges in the shipment, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, not including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `taxTotal` (_number (double)_) The total tax on the shipment, including item-level price adjustments and service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `1.8`.
*   `trackingNumber` (_string_) The tracking number of the shipment.  
    Example: `1Z204E380338943508`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShipmentId

The identifier of the shipment

Type: `string`.

Minimum length: 1. Example: `me`.

### ShippingMethod

Document representing a shipping method.

*   `deliveryWindow` (_object_) The estimated delivery window for this shipping method. The sfcc.app.shipping.quote hook populates this value. The response omits this field if the hook doesn't return a delivery window.
    
    Includes all fields of `DeliveryWindow`.
    
*   `description` (_string_) The localized description of the shipping method.  
    Example: `Order received within 7-10 business days`.
*   `externalShippingMethod` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method ID.  
    Maximum length: 256. Example: `001`.
*   `name` (_string_) The localized name of the shipping method.  
    Example: `Ground`.
*   `orderCutoffAt` (_string (date-time)_) The timestamp by which an order must be placed for the deliveryWindow to apply, as an RFC 3339 date-time. The sfcc.app.shipping.quote hook populates this value. The response omits this field if the hook doesn't return a cutoff time.  
    Example: `2026-04-27T14:00:00Z`.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs, product level fix, and surcharge costs. It is read only.  
    Example: `15`.
*   `shippingPromotions` (_array of ShippingPromotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingMethodResult

Result document containing shipping methods.

*   `applicableShippingMethods` (_array of ShippingMethod_) The applicable shipping method documents. It is read only.
*   `defaultShippingMethodId` (_string_) The default shipping method. It is read only.  
    Example: `me`.

### Taxes

Document representing the tax rates and (optionally) amounts for all items in a basket.

*   `taxes` (_object_, required) Map containing the TaxItems for the line item ids: Map<LineItemId, TaxItems \[\]>
    
    Additional properties: `TaxItems`.
    

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### BonusDiscountLineItem

Document representing a bonus discount line item.

*   `bonusProducts` (_array of ProductDetailsLink_) The bonus products the customer can choose from.
*   `couponCode` (_string_) The coupon code that triggered the promotion, if applicable.  
    Example: `5ties`.
*   `id` (_string_) The ID of the line item. It is read only.  
    Example: `91f4dd8bfa0653d58b7783b04f`.
*   `maxBonusItems` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotionId` (_string_) The ID of the promotion that triggered the creation of the line item.  
    Example: `Buy1Get2`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### GroupedTaxItem

Document representing the grouped tax item.

*   `taxRate` (_number (double)_) The tax rate. It is read only.  
    Example: `0.1`.
*   `taxValue` (_number (double)_) The summed up tax total for the tax rate. It is read only.  
    Example: `10.03`.

### OrderPaymentInstrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction. It is read only.
    
    Includes all fields of `Status`.
    
*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `12030000`.
*   `fraudDecisions` (_object_) The normalized fraud decisions for the order payment instrument. It is read only. Omitted when no decisions are returned.
    
    Includes all fields of `FraudDecisions`.
    
*   `maskedGiftCertificateCode` (_string_) The gift certificate code with the last 4 characters not masked.  
    Example: `******Gzzy`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `PaymentCard`.
    
*   `paymentDetails` (_object_) The normalized, shopper-relevant payment details for the order payment instrument. It is read only. Omitted when no details are available for the payment.
    
    Includes all fields of `PaymentDetails`.
    
*   `giftCard` (_object_) The gift card.
    
    Includes all fields of `GiftCardResponse`.
    
*   `paymentInstrumentId` (_object_) The payment instrument ID. It is read only.
    
    Includes all fields of `PaymentInstrumentId`.
    
*   `paymentMethodId` (_string_) The payment method ID. It is read only.  
    Maximum length: 256. Example: `CREDIT_CARD`.
*   `paymentReference` (_object_) Payment reference information for various payment service providers, only when Salesforce Payments is enabled.
    *   `paymentReferenceId` (_string_) Payment reference identifier. Can be payment intent ID for Stripe, PSP reference for Adyen, PayPal order ID for PayPal, or similar identifier for other payment providers.  
        Maximum length: 256. Example: `pi_3N4B2vF0wDjebNCp1234567`.
    *   `gateway` (_string_) The payment gateway used to process the payment.  
        Allowed values: `stripe`, `paypal`, `adyen`. Example: `stripe`.
    *   `gatewayProperties` (_object_) The payment gateway specific properties.
        *   `stripe` (_object_)
            
            ## Stripe specific properties.
            
            *   setupFutureUsage: Indicates that you intend to make future payments with this payment method.
                *   **on\_session**: The payment method is intended to be used for a future payment on the same website session.
                *   **off\_session**: The payment method is intended to be used for a future payment on a different website session.
            *   **null**: The payment method is not intended to be used for a future payment.
            *   clientSecret: Secret for Stripe client-side payment confirmation. Don't store, log, or expose the client secret to anyone other than the customer, and only use it on pages where TLS is enabled.
                *   type: string
                *   maxLength: 256
                *   example: "pi\_1J4K5L2eZvKYlo2CyZ8K5L6M\_secret\_abc123"
        *   `paypal` (_object_)
            
            ## PayPal specific properties.
            
        *   `adyen` (_object_)
            
            ## Adyen specific properties.
            
            *   adyenError: Error information returned by Adyen if the payment fails. Null on success.
            *   adyenPaymentIntent: The Adyen payment intent object containing payment details and required actions.
                *   resultCode: The result of the payment request (for example, "REDIRECT\_SHOPPER", "AUTHORISED", "PENDING", "REFUSED").
                *   accountID: The Adyen merchant account ID.
                *   adyenPaymentIntentAction: The action object for payment methods requiring additional shopper interaction.
                    *   url: The URL for completing the payment (redirect or 3DS authentication).
                    *   type: The action type (for example, "redirect", "threeDS2", "voucher").
                    *   method: The HTTP method for the action (for example, "GET", "POST").
            *   successful: A boolean indicating whether the Adyen operation is successful.

### ShippingItem

Document representing a shipping item.

*   `adjustedTax` (_number (double)_) The tax for the shipping item, including price adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the shipping item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `itemId` (_string_) The shipping item ID. Use it to identify this shipping item when updating its quantity or creating a custom price adjustment for it. It is read only.  
    Example: `430ef5aad3a24de59378458434`.
*   `itemText` (_string_) The text describing the shipping item.  
    Example: `Shipping`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the shipping item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.
*   `shipmentId` (_object_) The identifier of the shipment to which this item belongs.
    
    Includes all fields of `ShipmentId`.
    
*   `tax` (_number (double)_) The tax on the product item, not including adjustments. It is read only.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this shipping item. It is read only.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxItems` (_array of TaxItem_) The individual tax items for this shipping line item (e.g. state tax, county tax). It is read only.  
    Maximum items: 10.
*   `taxRate` (_number (double)_) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1. It is read only.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ApproachingDiscount

Document representing an approaching discount for a basket. Contains information about promotions the customer is close to qualifying for.

*   `type` (_string_, required) The type of approaching discount (order-level or shipping-level).  
    Allowed values: `order`, `shipping`. Example: `order`.
*   `conditionThreshold` (_number (double)_) The total amount needed to receive the discount.  
    Example: `100`.
*   `merchandiseTotal` (_number (double)_) The amount the customer basket contributes towards the purchase condition.  
    Example: `90`.
*   `discount` (_object_) The applied discount when the order meets the threshold.
    
    Includes all fields of `Discount`.
    
*   `promotionLink` (_object_) Document representing a promotion link.
    
    Includes all fields of `PromotionLink`.
    
*   `shipmentId` (_string_) The unique id of the shipment the discount relates to. Only applicable when type = shipping.  
    Minimum length: 1. Maximum length: 256. Example: `me`.
*   `shippingMethods` (_array of ShippingMethod_) The shipping methods the promotion relates to. Only applicable when type = shipping.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### ProductItem

Document representing a product item.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `130`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus.  
    Example: `true`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.
*   `optionItems` (_array of OptionItem_) The option items.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `20.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `15.5`.
*   `productId` (_string_) The ID of the product.  
    Maximum length: 100. Example: `nintendo-ds-console`.
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `qualifyingProductItemId` (_string_) Returns the id of the ProductLineItem that qualified the basket for this bonus product. This method is only applicable if the product line item is a bonus product line item, and if the promotion is a product promotion with number of qualifying products granting a bonus-product discount. If these conditions aren't met, the method returns null. If there are multiple product line items that triggered this bonus product, this method returns the last one by position within the order.  
    Maximum length: 28.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax for the product item, not including price adjustments. It is read only.  
    Example: `0.3`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this product item. It is read only.  
    Example: `30`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxItems` (_array of TaxItem_) The individual tax items for this product line item (e.g. state tax, county tax). It is read only.  
    Maximum items: 10.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.9`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### TaxItem

Object representing the taxation.

*   `id` (_string_, required) The taxation identifier.
*   `rate` (_number (double)_, required) The taxation rate.  
    Example: `0.13`.
*   `value` (_number (double)_) The tax amount. Will be computed if not set.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderPaymentCardRequest

Document representing an order payment card request.

*   `cardType` (_string_) The payment card type (for example: Visa).  
    Maximum length: 256. Example: `Visa`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store.  
    Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number.  
    Maximum length: 25. Pattern: ^\[0-9 -\]{0,7}\\D{6,15}\\d{0,4}$. Example: `*********4422`.
*   `validFromMonth` (_integer (int32)_) The month the payment card is valid from.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year the payment card is valid from.  
    Example: `2019`.

### GiftCardRequest

Represents gift card details for a request.

*   `brand` (_string_, required) The gift card type or brand (for example, givex, blackhawk).  
    Maximum length: 256. Example: `givex`.
*   `cardNumber` (_string_, required) The gift card number.  
    Maximum length: 40. Example: `6364530000000000`.
*   `cvc` (_string_, required) The card verification code (CVC/CVV) for the gift card.  
    Maximum length: 4. Example: `123`.
*   `expirationMonth` (_integer (int32)_) The month when the gift card expires.  
    Example: `1`.
*   `expirationYear` (_integer (int32)_) The year when the gift card expires.  
    Example: `2030`.

### PaymentReferenceRequest

Properties for Payments Reference Request

*   `paymentMethodType` (_string_) Payment Method Type  
    Maximum length: 64. Example: `card`.
*   `zoneId` (_string_) The unique identifier for a Payments zone.  
    Minimum length: 1. Maximum length: 100. Pattern: ^\[a-zA-Z0-9\\-\_\]{1,100}$.
    
    _Example_
    
    ```
    {
      "Amer-Zone": null
    }
    ```
    
*   `gateway` (_string_) The payment gateway used to process the payment.  
    Allowed values: `stripe`, `paypal`, `adyen`. Example: `stripe`.
*   `gatewayProperties` (_object_) The payment gateway specific properties.
    *   `stripe` (_object_)
        
        ## Stripe specific properties.
        
        *   setupFutureUsage: Indicates that you intend to make future payments with this payment method.
            *   **on\_session**: The payment method is intended to be used for a future payment on the same website session.
            *   **off\_session**: The payment method is intended to be used for a future payment on a different website session.
            *   **null**: The payment method is not intended to be used for a future payment.
    *   `paypal` (_object_)
        
        ## PayPal specific properties.
        
        *   shippingPreference: Shipping preference for PayPal payment processing. Applicable only for basket payment instruments.
            *   **GET\_FROM\_FILE**
            *   **NO\_SHIPPING**
            *   **SET\_PROVIDED\_ADDRESS**
    *   `adyen` (_object_)
        
        ## Adyen specific properties.
        

### PaymentMethod

Document representing a payment method.

*   `cards` (_array of PaymentCardSpec_) The sorted array of payment cards (included only when the system payment method is CREDIT\_CARD). It is read only.
*   `description` (_string_) The localized description of the payment method or card. It is read only.
*   `id` (_string_, required) The ID of the payment method or card. It is read only.  
    Maximum length: 256.
*   `image` (_string_) The URL to the image that represents the payment method or card. It is read only.
*   `name` (_string_) The localized name of the payment method or card. It is read only.
*   `paymentProcessorId` (_string_) The payment processor ID. It is read only. It is read only.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### DiscountRequest

Request that represents a discount to be applied to a custom price adjustment.

*   `type` (_string_, required)
    
    The type of discount.
    
    *   `amount` describes a (unit) price discount, and its corresponding value (positive) defines the amount each unit is to be reduced by. Example: For a $10 discount, set `type` to `amount` and `value` to `10.00`.
    *   `percentage` describes a percentage discount, and its corresponding value (positive) defines the percentage reduction. Example: For a 5% discount, set `type` to `percentage` and `value` to `5.00`.
    *   `fixed_price` describes a fixed price discount, and its corresponding value (positive) defines the resulting fixed price for the item. Only one `fixed_price` discount can be set for each item. Example: To set a fixed price of $15, set `type` to `fixed_price` and `value` to `15.00`. **Important**: Setting `type` to `fixed_price` is not supported when `level` is set to `order`.
    
      
    Allowed values: `percentage`, `fixed_price`, `amount`. Example: `percentage`.
*   `value` (_number (double)_, required) The amount of the discount.  
    Example: `20`.

### Discount

Document representing a discount.

*   `amount` (_number (double)_) The discount amount for discount types that define specific discount amounts. It is read only.  
    Example: `130.88`.
*   `percentage` (_number (double)_) The discount percent for discount types that define percentage discounts. It is read only.  
    Example: `0.19`.
*   `priceBookId` (_string_) The price book ID that is used with some types. It is read only.  
    Example: `usd-sale-prices`.
*   `type` (_string_, required) The type of discount. It is read only.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`. Example: `fixed_price`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### DeliveryWindow

The range describing when an item is expected to be delivered. Both bounds are RFC 3339 date-time timestamps. The API preserves sub-day precision end-to-end.

*   `startAt` (_string (date-time)_) The earliest expected delivery time, as an RFC 3339 date-time.  
    Example: `2026-04-30T14:00:00Z`.
*   `endAt` (_string (date-time)_) The latest expected delivery time, as an RFC 3339 date-time.  
    Example: `2026-04-30T18:00:00Z`.

### ShippingPromotion

Document representing a shipping promotion.

*   `calloutMsg` (_string_) The localized callout message of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `promotionId` (_string_) The unique ID of the promotion.  
    Example: `$30FixedShippingAmountAbove150`.
*   `promotionName` (_string_) The localized promotion name.  
    Example: `$30 Fixed Shipping Amount Above 150`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductDetailsLink

Document representing a link to the resource for product details.

*   `productDescription` (_string_) The description of the product.  
    Example: `Nintendo DS revolutionizes handheld gameplay.`.
*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `title` (_string_) The link title.  
    Example: `Nintendo DS Game Console`.

### Status

Document representing an object status.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_) The status. For more information on the status values see Status.OK and Status.ERROR.

### FraudDecisions

Normalized fraud decisions for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no decisions are returned. The values remain readable for historical orders.

*   `preAuthorization` (_string_)
    
    The pre-authorization fraud decision used by the client to orchestrate checkout. Expected values are:
    
    *   `NOT_REVIEWED`: the payment instrument was not reviewed pre-authorization.
    *   `APPROVED`: the payment authorization can proceed.
    *   `CHALLENGE`: the payment authorization should be challenged with additional verification (for example, a 3D Secure challenge) before it can proceed.
    *   `DECLINED`: the payment authorization is declined.
    
    A custom value may also be returned. It is read only.
    
      
    Maximum length: 256. Example: `APPROVED`.

### PaymentCard

Document representing a payment card.

*   `cardType` (_string_) The payment card type.  
    Maximum length: 256. Example: `Visa`.
*   `creditCardExpired` (_boolean_) A flag indicating if the credit card is expired. It is read only.  
    Example: `true`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store.  
    Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number.  
    Maximum length: 4000. Example: `*********4422`.
*   `numberLastDigits` (_string_) The last digits of the payment card number. It is read only.  
    Maximum length: 4000. Example: `4422`.
*   `validFromMonth` (_integer (int32)_) The month the payment card is valid from.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year the payment card is valid from.  
    Example: `2015`.

### PaymentDetails

Normalized, shopper-relevant payment details for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no details are available for the payment. The values remain readable for historical orders.

*   `type` (_string_) The normalized payment method type. Expected values are `bancontact`, `card`, `gift_card`, `eps`, `ideal`, `klarna`, `sepa_debit`, `paypal`, `venmo`, `afterpay_clearpay`, `amazon_pay`, and `twint`. A custom value may also be returned. It is read only.  
    Maximum length: 256. Example: `card`.
*   `brand` (_string_) The normalized card brand. Expected values are `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, and `unknown`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `visa`.
*   `last4` (_string_) The last four digits of the payment instrument. It is read only.  
    Maximum length: 4. Example: `4242`.
*   `walletType` (_string_) The normalized digital wallet used for the payment. Expected values are `apple_pay` and `google_pay`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `apple_pay`.
*   `expirationMonth` (_integer (int32)_) The month when the payment instrument expires. It is read only.  
    Minimum: 1. Maximum: 12. Example: `12`.
*   `expirationYear` (_integer (int32)_) The year when the payment instrument expires. It is read only.  
    Example: `2028`.
*   `token` (_string_) The reference token representing the payment instrument. This is an opaque identifier, not the card number (PAN). It is read only.  
    Maximum length: 40. Example: `pm_abc123`.
*   `tokenType` (_string_) The type of token backing the reference token. Expected values are `NETWORK` and `GATEWAY`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `GATEWAY`.
*   `accountHolderName` (_string_) The name of the payment instrument account holder. It is read only.  
    Maximum length: 256. Example: `Alex Shopper`.

### GiftCardResponse

Document representing a gift card response.

*   `brand` (_string_) The gift card brand.  
    Maximum length: 256. Example: `givex`.
*   `maskedCardNumber` (_string_) The masked gift card number.  
    Maximum length: 40. Example: `*********4422`.
*   `expirationMonth` (_integer (int32)_) The month when the gift card expires.  
    Example: `1`.
*   `expirationYear` (_integer (int32)_) The year when the gift card expires.  
    Example: `2030`.

### PromotionLink

Document representing a promotion link.

*   `promotionId` (_string_) The unique id of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10off100`.
*   `name` (_string_) The localized name of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10% off $100 orders`.
*   `calloutMsg` (_string_) The localized call-out message of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `Spend $10 more to save 10%!`.
*   `title` (_string_) The link title.  
    Minimum length: 1. Maximum length: 256. Example: `10% off $100 orders`.
*   `link` (_string_) The URL addressing the promotion.  
    Minimum length: 1. Maximum length: 2048. Example: `/s/SiteGenesis/promotion?id=10off100`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OptionItem

An option item represents an optional purchase related to a product item, and is always associated with that parent product item. An option item can have different values from which to select. For example, a refrigerator item can have an option item representing an extended warranty, with a set of option item values representing different warranty lengths. When a shopper purchases the warranty option item together with the parent refrigerator item, they select one of the available warranty option item values.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.  
    Example: `ba248414e3eee797f062162f8b`.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus. It is read only.  
    Example: `false`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `false`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item. It is read only.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.  
    Example: `The item text.`.
*   `optionId` (_string_, required) The ID of the option. It is read only.  
    Maximum length: 256. Example: `consoleWarranty`.
*   `optionItems` (_array of OptionItem_) The option items.
*   `optionValueId` (_string_, required) The ID of the option value. It is read only.  
    Maximum length: 256. Example: `000`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `150.99`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `40.5`.
*   `productId` (_ProductId_)
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `quantity` (_number (double)_) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments. It is read only.  
    Example: `0`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item. It is read only.  
    Example: `50`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.19`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductListItemReference

Document representing product list item details.

*   `id` (_object_, required) The ID of the product list item. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `priority` (_integer (int32)_) The priority of the product list item.  
    Example: `1`.
*   `productDetailsLink` (_ProductDetailsLink_)
*   `productList` (_object_) A reference to the associated product list. It is read only.
    
    Includes all fields of `ProductListLink`.
    
*   `public` (_boolean_)  
    Example: `false`.
*   `purchasedQuantity` (_number (double)_) The total quantity of this item purchased from the product list.  
    Example: `0`.
*   `quantity` (_number (double)_) The number of products or gift certificates that get shipped when purchasing this product list item.  
    Minimum: 0. Example: `1`.
*   `type` (_string_) Specifies whether the item is a product or a gift certificate.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### PaymentCardSpec

Document representing the specification for a payment card.

*   `cardType` (_string_) The payment card type. It is read only.  
    Example: `Visa`.
*   `checksumVerificationEnabled` (_boolean_) A flag indicating whether the card number is verified using the Luhn checksum algorithm. It is read only.  
    Example: `true`.
*   `description` (_string_) The localized description of the payment card. It is read only.
*   `image` (_string_) The URL to the image that represents the payment card. It is read only.
*   `name` (_string_) The localized name of the payment card. It is read only.
*   `numberLengths` (_array of string_) The sorted list of number lengths (individual lengths as well as length ranges). It is read only.
*   `numberPrefixes` (_array of string_) The sorted list of number prefixes (individual prefixes as well as prefix ranges). It is read only.
*   `securityCodeLength` (_integer (int32)_) The length of the security code for this card. It is read only.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### ProductListLink

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers. It is read only.  
    Example: `true`.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `shopping_list`.

<!-- document id=332e57ae540da261549b4a9276df44c24db54388b4810d10bd7819a9cc3e135f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-shopper-buyer-groups-accounts-limits.md -->

# Shopper Buyer Groups and Accounts Data Limits

| Object                                                                                                                                                                                                | Limit for B2B                                           | Store or Org | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Buyer Groups                                                                                                                                                                                          | 5 million<sup>\*</sup>                                  | N/A          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Buyer Accounts                                                                                                                                                                                        | 10 million<sup>\*</sup>                                 | N/A          | B2B: If leveraging any external license that requires associated roles, for example, Customer Community Plus and Partner Community, the default number of roles used in an org’s portals or communities is 50,000. See experience cloud documentation on Portal Roles and External Licenses. For B2B, this limit can be extended. Please work with your account representative if you need more than 1M shoppers.                                                                                                                |
| Buyer Accounts per Buyer Group                                                                                                                                                                        | 10 million<sup>\*</sup>                                 | N/A          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Buyer Groups per Buyer Account                                                                                                                                                                        | 20<sup>\*</sup>                                         | N/A          | The limit supports 100 buyer groups per buyer account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Buyer Groups per Buyer Account <ul><li>(with [CommerceBuyGrp](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_namespace_CommerceBuyGrp.htm) Apex extensibility)</li></ul> | 30<sup>\*</sup>                                         | N/A          | Refers to buyer groups per buyer account+10. For example, if the configured limit is 30, the effective total becomes 40. To make sure the buyer group extensibility service functions properly and to avoid caching-related issues, disable both the [Salesforce Content Delivery Network](https://help.salesforce.com/s/articleView?id=platform.community_builder_cdn_considerations.htm) (CDN) and [Salesforce Edge Network](https://help.salesforce.com/s/articleView?id=xcloud.domain_name_edge_network_considerations.htm). |
| Buyer Users                                                                                                                                                                                           | 1.5 million<sup>\*</sup> Buyer users and Buyer managers | N/A          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Account Switcher                                                                                                                                                                                      | 200<sup>\*</sup> Buy For Accounts                       | N/A          | B2B: To extend beyond the 200 Buy For accounts limit, requires you to create a custom implementation of the Account Switcher. At levels beyond 200 Buy For accounts, the performance of the provided Account Switcher begins to degrade. At 2 thousand Buy For accounts the Account Switcher fails.                                                                                                                                                                                                                              |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce customer support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

Salesforce recommends you manage buyer group data within the scope of the established limits. If you intend to customize buyer group limits, design a clear and efficient approach that doesn’t push all data boundaries. Define buyer groups' relationships and dependencies with other objects and ensure a logical structure. For example, Buyer groups have pricing and entitlements object dependencies. Changing a buyer group limit can impact the pricing and entitlements limits.

Establish clear policies and guidelines for managing buyer groups. Set policies for creating new groups, updating existing groups, and deleting groups.

When creating buyer groups, use buyer demographics to segment your buyers into appropriate buyer groups effectively. Consider criteria such as industry, size, location, or purchasing behavior. Well-planned buyer group segmentation can minimize the number of buyer groups and lower the impact on data required to support them.

Regularly review and clean up buyer group data. Remove any outdated or unused groups or group members, and ensure that the information within each group is accurate and up-to-date.

If you have buyer group requirements that exceed the limits, consider the impact on performance and data storage limits.

- Does the additional data push the related data objects beyond their limits?
- Can you offset a data increase by decreasing data requirements in other store functions?

After you assess the impact of a data increase, if you still want to request an increase, contact Support.

<!-- document id=a4db115d01f92ca15316c2dd887faa2fc8b4003802401538573229b2e1abec16 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-configurations.md -->

Shopper Configurations

# Shopper Configurations

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-configurations/shopper-configurations-oas-v1-public.yaml)

## API Overview

The Shopper Configurations API provides cacheable configuration data to shopper-facing applications, enabling them to make decisions based on merchant settings without requiring server-side logic.

This highly cacheable data encompasses toggles, preferences, and configuration information that allows the application to be reactive to changes performed by the merchant, admin, or support engineer.

Configuration types include:

*   siteConfiguration: Site-specific settings such as name, status, currencies, and locales
*   globalConfiguration: Instance-wide settings such as feature flags

### Authentication & Authorization

The Shopper Configuration API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include `sfcc.shopper-configurations` in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

### Customization

#### Hooks

You can extend the Shopper Configurations response with custom data using the `dw.shop.shopper_configuration.modifyGETResponse` hook. This is useful for adding custom site preferences to the response.

```javascript
exports.modifyGETResponse = function (configResp) {
  var customPreference = dw.system.Site.getCurrent().getCustomPreferenceValue(
    "customerServiceEmail"
  );
  configResp.c_customPrefs = {
    customerServiceEmail: customPreference || "noreply@example.com"
  };
};
```

For details on hook registration, see [Hook Method Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook-method-details.html). For general information on hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get Site Configuration

Retrieve site and global configuration settings (name, status, currencies, locales, feature flags).

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/configuration/shopper-configurations/v1/organizations/{organizationId}/configurations?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Site Identification and Availability

Retrieve the site's display name and current operational status to determine if the storefront is online, offline, or in a maintenance state for shoppers.

#### Currency Configuration

Identify the default currency for the site and the list of all supported currencies to ensure correct price rendering and multi-currency support.

#### Locale and Language Settings

Access the default locale and the full set of supported locales to localize content, formatting, and language for the shopper's specific region.

#### Feature Enablement

View the status of various storefront features and toggles to dynamically enable or disable application logic based on the merchant's active configuration.

**Version:** 1.4.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/configuration/shopper-configurations/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) Shopper token flow.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-configurations: Shopper Configurations READONLY
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-configurations: Shopper Configurations READONLY
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-configurations: Shopper Configurations READONLY

## Operations

### GET Retrieves configurations

`GET /organizations/{organizationId}/configurations`

Operation ID: `getConfigurations`. Security: ShopperToken (sfcc.shopper-configurations, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-configurations, sfcc.shopper-standard).

Retrieves configurations for the specified organization and site.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Retrieved configurations successfully.
    
    Media type: `application/json`. Schema: `SiteConfiguration`.
    
    _Example: ConfigurationsExample_
    
    ```
    {
      "configurations": [
        {
          "id": "id",
          "value": "RefArch",
          "configurationType": "siteConfiguration"
        },
        {
          "id": "name",
          "value": "Ref Arch",
          "configurationType": "siteConfiguration"
        },
        {
          "id": "status",
          "value": "online",
          "configurationType": "siteConfiguration"
        },
        {
          "id": "timezone",
          "value": "Etc/UTC",
          "configurationType": "siteConfiguration"
        },
        {
          "id": "timezoneOffset",
          "value": 0,
          "configurationType": "siteConfiguration"
        },
        {
          "id": "defaultCurrency",
          "value": "USD",
          "configurationType": "siteConfiguration"
        },
        {
          "id": "allowedCurrencies",
          "value": [
            "USD",
            "EUR"
          ],
          "configurationType": "siteConfiguration"
        },
        {
          "id": "defaultLocale",
          "value": "en-US",
          "configurationType": "siteConfiguration"
        },
        {
          "id": "allowedLocales",
          "value": [
            {
              "id": "en-US",
              "country": "US",
              "default": true,
              "displayCountry": "United States",
              "displayLanguage": "English",
              "displayName": "English (United States)",
              "iso3Country": "USA",
              "iso3Language": "eng",
              "language": "en",
              "name": "English (United States)"
            },
            {
              "id": "en-CA",
              "country": "CA",
              "default": false,
              "displayCountry": "Canada",
              "displayLanguage": "English",
              "displayName": "English (Canada)",
              "iso3Country": "CAN",
              "iso3Language": "eng",
              "language": "en",
              "name": "English (Canada)"
            }
          ],
          "configurationType": "siteConfiguration"
        },
        {
          "id": "SalesforcePaymentsAllowed",
          "value": true,
          "configurationType": "globalConfiguration"
        },
        {
          "id": "gcp",
          "value": "abc123",
          "configurationType": "globalConfiguration"
        }
      ]
    }
    ```
    
*   **400** Bad request - invalid parameters provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: getShopperConfigurations400_ Bad Request Error
    
    Example of a 400 Bad Request error response
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The request could not be processed due to invalid parameters.",
      "correlationId": "12345678-1234-1234-1234-123456789012"
    }
    ```
    
*   **401** Your shopper JWT is invalid and cannot be used to identify the API client.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: getShopperConfigurations401_ Unauthorized Error
    
    Example of a 401 Unauthorized error response
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your shopper JWT is invalid and cannot be used to identify the API client.",
      "correlationId": "12345678-1234-1234-1234-123456789012"
    }
    ```
    
*   **404** Application context not found for the specified organization and site.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: getShopperConfigurations404_ Not Found Error
    
    Example of a 404 Not Found error response
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "title": "Not Found",
      "detail": "Configuration not found for the specified organization and site.",
      "correlationId": "12345678-1234-1234-1234-123456789012"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SiteConfiguration

Site Configuration object

*   `configurations` (_array of Configuration_, required) List configurations for the instance and site  
    Maximum items: 100.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### Configuration

Configuration object

*   `id` (_string_, required) identifier  
    Maximum length: 255. Example: `SalesforcePaymentsAllowed`.
*   `value` (_any_, required) value for identifier  
    Maximum length: 255. Example: `true`.
*   `configurationType` (_string_) type of configuration value  
    Maximum length: 255. Example: `globalConfiguration`.

<!-- document id=bdb36cad8b7a2709705545e246385e9f2acd44b4ffe52f12afd8512c2c8077c7 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-consents.md -->

Shopper Consents

# Shopper Consents

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-consents/shopper-consents-oas-v1-public.yaml)

## API Overview

The Shopper Consent API offers a centralized method for managing shopper consent. With this API, shoppers can view and update subscription preferences for marketing communications across various channels. This API controls how and where shoppers receive marketing messages while ensuring compliance with privacy regulations.

The Shopper Consent API provides sensible defaults for optional fields to simplify integration:

*   Consent Type: Defaults to "marketing" for marketing communications.
*   Consent Required: Defaults to false, making subscriptions optional by default.
*   Default Status: Defaults to "opt\_out" to respect privacy-first principles.
*   Tags: Defaults to an empty array when not specified.

### Authentication & Authorization

The Shopper Consent API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include the relevant scope(s) in the client ID used to generate the SLAS token.

*   `sfcc.shopper-consents`: Required for reading communication subscription data (GET operations).
*   `sfcc.shopper-consents.rw`: Required for creating and modifying communication subscription consent data (POST operations).

For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached. Consent data is unique to each shopper.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get Consent Subscriptions

Retrieve the communication subscriptions for a shopper.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-consents/v1/organizations/{organizationId}/subscriptions?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Retrieve communication subscriptions

Retrieve relevant communication subscription options with rich display information. - Communication subscription options can be filtered by one or more qualifying tags. - Use the `expand` parameter to conditionally include subscription status.

#### Update individual subscription consent

Update consent status for a single subscription with simple request/response pattern.

#### Bulk subscription updates

Efficiently manage multiple subscription preferences with a single request. - Update 1-50 subscriptions per bulk request. - Partial success handling with detailed error reporting for failed updates.

### Data Model

#### Subscriptions

Subscriptions represent a shopper's consent to receive specific types of marketing communications. Each subscription includes:

*   Subscription Id: Descriptive identifier
*   Channels: Array of communication methods - Email, SMS, or WhatsApp
*   Consent Type: Marketing or legal subscription classification
*   Consent Required: Whether the subscription is mandatory for the shopper
*   Default Status: Default opt-in or opt-out behavior
*   Consent Status: Array of status entries for each channel showing current opt-in or opt-out status (conditionally returned based on expand parameter)
*   Rich Display Information:
    *   Title: Simple localized string for subscription name
    *   Subtitle: Simple localized string with HTML markup support for descriptions
    *   Localized content determined by the locale parameter
*   Tags: Categorical tags indicating where the subscription option can appear (defaults to empty array, max 10 tags)

#### Channels

Channels define the communication methods available for a subscription:

*   `email`: Email communications
*   `sms`: SMS/text messages
*   `whatsapp`: WhatsApp messaging

#### Tags

Tags indicate where subscription options are displayed in your shopper experience. Tags are also accepted as optional filtering parameters in the retrieval of shopper consent subscriptions. For example:

*   `homepage_banner`: Main website homepage
*   `registration`: Shopper registration form
*   `checkout`: Checkout flow
*   `user_profile`: User profile management section

### Advanced Features

#### Expand Parameter

The `expand` parameter provides conditional field inclusion:

*   `expand=[]` (default): Returns basic subscription information
*   `expand=["consentStatus"]`: Include consent status information in the response
*   Future expansion may include additional fields

### Best Practices

*   Use single subscription updates for real-time, interactive preference changes.
*   Use bulk operations when updating multiple subscriptions to reduce API calls and improve performance.
*   Only request status information when needed using the expand parameter to reduce latency.

**Version:** 1.2.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-consents/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-consents: Allows read operations on shopper consents
    *   Scope sfcc.shopper-consents.rw: Allows read/write operations on shopper consents
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-consents: Allows read operations on shopper consents
    *   Scope sfcc.shopper-consents.rw: Allows read/write operations on shopper consents
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-consents: Allows read operations on shopper consents
    *   Scope sfcc.shopper-consents.rw: Allows read/write operations on shopper consents

## Operations

### GET Get shopper consent preferences

`GET /organizations/{organizationId}/subscriptions`

Operation ID: `getSubscriptions`. Security: ShopperToken (sfcc.shopper-consents, sfcc.shopper-consents.rw); ShopperClientContextToken (sfcc.shopper-consents, sfcc.shopper-consents.rw).

Retrieve all subscription preferences for the shopper (authenticated or guest).

Use the 'expand' parameter to include additional fields in the response:

*   expand=\["consentStatus"\]: Include subscription status information
*   expand=\[\]: Default behavior, excludes status for privacy and performance

The expand parameter provides privacy benefits by not exposing sensitive status information unless explicitly requested.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `tags` (query, array of Tag, style: form, explode: false) Optional parameter of 0 or more query string values which act as a filtering criteria. Multiple values are treated with `OR` logic, and absence of a value indicates no filtering by tag is desired.  
    Minimum items: 0. Maximum items: 10.
    
    _Example: one_ One tag filter
    
    ```
    [
      "homepage_banner"
    ]
    ```
    
    _Example: multiple_ Multiple tag filters (ORs)
    
    ```
    [
      "homepage_banner",
      "user_profile",
      "checkout",
      "registration"
    ]
    ```
    
*   `expand` (query, array of string, style: form, explode: false)
    
    Optional parameter to expand response with additional fields. Accepts an array of field names to include in the response. Currently supports:
    
    *   "consentStatus": Include consent status information in the response
    
    Future expansions may include additional fields.
    
      
    Items: Allowed values: `consentStatus`. Example: `consentStatus`. Default: `[]`. Minimum items: 0. Maximum items: 10. Unique items.
    
    _Example: empty_ No expansion (default behavior)
    
    ```
    []
    ```
    
    _Example: consentStatus_ Include status information
    
    ```
    [
      "consentStatus"
    ]
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Successfully retrieved subscription preferences.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResponse`.
    
    _Example ConsentSubscriptionResponseGuest: same as GET /organizations/{organizationId}/subscriptions 200 response._ GUEST shopper's available consent subscriptions
    
    _Example: ConsentSubscriptionResponseAuthenticated_ AUTHENTICATED shopper's available consent subscriptions
    
    ```
    {
      "data": [
        {
          "subscriptionId": "weekly-newsletter",
          "channels": [
            "email",
            "whatsapp"
          ],
          "title": "Weekly Newsletter",
          "subtitle": "Get our weekly newsletter with the latest updates. <a href=\"https://example.com/newsletter\">Learn more</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "homepage_banner",
            "user_profile"
          ]
        },
        {
          "subscriptionId": "promotional-offers",
          "channels": [
            "sms"
          ],
          "title": "Promotional Offers",
          "subtitle": "Receive special promotional offers. <a href=\"https://example.com/offers\">View terms</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "checkout"
          ]
        }
      ]
    }
    ```
    
    _Example: ConsentSubscriptionResponseAuthenticatedExpanded_ AUTHENTICATED shopper's consent subscriptions with expand=\["consentStatus"\]
    
    ```
    {
      "data": [
        {
          "subscriptionId": "weekly-newsletter",
          "channels": [
            "email",
            "whatsapp"
          ],
          "consentStatus": [
            {
              "channel": "email",
              "contactPointValue": "customer@example.com",
              "status": "opt_in"
            },
            {
              "channel": "whatsapp",
              "contactPointValue": "+1 555 123 4567",
              "status": "opt_out"
            }
          ],
          "title": "Weekly Newsletter",
          "subtitle": "Get our weekly newsletter with the latest updates. <a href=\"https://example.com/newsletter\">Learn more</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "homepage_banner",
            "user_profile"
          ]
        },
        {
          "subscriptionId": "promotional-offers",
          "channels": [
            "sms"
          ],
          "consentStatus": [
            {
              "channel": "sms",
              "contactPointValue": "+1 555 987 6543",
              "status": "opt_out"
            }
          ],
          "title": "Promotional Offers",
          "subtitle": "Receive special promotional offers. <a href=\"https://example.com/offers\">View terms</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "checkout",
            "user_profile"
          ]
        },
        {
          "subscriptionId": "privacy-policy-updates",
          "channels": [
            "email"
          ],
          "consentStatus": [
            {
              "channel": "email",
              "contactPointValue": "customer@example.com",
              "status": "opt_in"
            }
          ],
          "title": "Privacy Policy Updates",
          "subtitle": "Important updates to our privacy policy. <a href=\"https://example.com/privacy\">Read policy</a>",
          "consentType": "legal",
          "consentRequired": true,
          "defaultStatus": "opt_in",
          "tags": [
            "registration"
          ]
        }
      ]
    }
    ```
    
    _Example: ConsentSubscriptionResponseGuest_ GUEST shopper's available consent subscriptions
    
*   **400** Error retrieving subscription preferences
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ConsentSubscriptionError_
    
    ```
    {
      "title": "Error Retrieving Consent Subscription",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Error retrieving consent subscription."
    }
    ```
    

### POST Update shopper subscription preference

`POST /organizations/{organizationId}/subscriptions`

Operation ID: `updateSubscription`. Security: ShopperToken (sfcc.shopper-consents.rw); ShopperClientContextToken (sfcc.shopper-consents.rw).

Update the consent status for a single subscription.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ConsentSubscriptionRequest`.

_Example: ConsentSubscriptionUpdateRequest_ Single subscription update request

```
{
  "subscriptionId": "weekly-newsletter",
  "contactPointValue": "john.doe@example.com",
  "channel": "email",
  "status": "opt_in"
}
```

#### Responses

*   **200** Subscription update completed successfully.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionUpdateResponse`.
    
    _Example: ConsentSubscriptionUpdateResponseSuccess_ Single subscription update successful (200 response)
    
    ```
    {
      "subscriptionId": "weekly-newsletter",
      "contactPointValue": "john.doe@example.com",
      "channel": "email",
      "status": "opt_in"
    }
    ```
    
*   **400** Error with request format or validation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ConsentSubscriptionUpdateError_
    
    ```
    {
      "title": "Error Updating Consent Subscription",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "Consent subscription could not be updated."
    }
    ```
    

### POST Update shopper subscription preferences

`POST /organizations/{organizationId}/subscriptions/actions/bulk`

Operation ID: `updateSubscriptions`. Security: ShopperToken (sfcc.shopper-consents.rw); ShopperClientContextToken (sfcc.shopper-consents.rw).

Update the consent status for multiple subscriptions in a single bulk request. Supports 1-50 subscription updates per request with partial success handling.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ConsentSubscriptionBulkRequest`.

_Example: ConsentSubscriptionBulkUpdateRequest_ Bulk subscription update request

```
{
  "subscriptions": [
    {
      "subscriptionId": "weekly-newsletter",
      "contactPointValue": "john.doe@example.com",
      "channel": "email",
      "status": "opt_in"
    },
    {
      "subscriptionId": "sms-alerts",
      "contactPointValue": "+1 555 123 4567",
      "channel": "sms",
      "status": "opt_out"
    }
  ]
}
```

#### Responses

*   **200** All subscription updates completed successfully.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionBulkResponse`.
    
    _Example: ConsentSubscriptionBulkUpdateResponseSuccess_ All subscription updates successful (200 response)
    
    ```
    {
      "results": [
        {
          "subscriptionId": "weekly-newsletter",
          "contactPointValue": "john.doe@example.com",
          "channel": "email",
          "status": "opt_in",
          "success": true
        },
        {
          "subscriptionId": "sms-alerts",
          "contactPointValue": "+1 555 123 4567",
          "channel": "sms",
          "status": "opt_out",
          "success": true
        }
      ]
    }
    ```
    
*   **207** Partial success - some subscription updates succeeded, others failed.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionBulkResponse`.
    
    _Example: ConsentSubscriptionBulkUpdateResponsePartial_ Partial success - some updates failed (207 response)
    
    ```
    {
      "results": [
        {
          "subscriptionId": "weekly-newsletter",
          "contactPointValue": "john.doe@example.com",
          "channel": "email",
          "status": "opt_in",
          "success": true
        },
        {
          "subscriptionId": "sms-alerts",
          "contactPointValue": "invalid-phone",
          "channel": "sms",
          "status": "opt_out",
          "success": false,
          "error": {
            "code": "INVALID_CONTACT_POINT",
            "message": "Invalid phone number format",
            "details": {
              "field": "contactPointValue",
              "provided": "invalid-phone"
            }
          }
        }
      ]
    }
    ```
    
*   **400** Error with bulk request format or validation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BulkValidationError_
    
    ```
    {
      "title": "Bulk Request Validation Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "One or more validation errors occurred in the bulk request.",
      "instance": "/organizations/f_ecom_zzrf_001/subscriptions"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### Tag

Filter criteria for consent subscriptions

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `homepage_banner`.

### ConsentSubscriptionResponse

Collection wrapper of consent subscriptions

*   `data` (_array of ConsentSubscription_, required)  
    Minimum items: 0. Maximum items: 50.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ConsentSubscriptionRequest

Consent subscription update request

*   `subscriptionId` (_SubscriptionId_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `channel` (_ChannelType_, required)
*   `status` (_ConsentStatus_, required)

### ConsentSubscriptionUpdateResponse

Single subscription update response

*   `subscriptionId` (_SubscriptionId_, required)
*   `channel` (_ChannelType_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `status` (_ConsentStatus_, required)

### ConsentSubscriptionBulkRequest

Bulk request for updating multiple consent subscriptions

*   `subscriptions` (_array of ConsentSubscriptionRequest_, required) Array of subscription consent updates to process  
    Minimum items: 1. Maximum items: 50.
    
    _Example_
    
    ```
    [
      {
        "subscriptionId": "weekly-newsletter",
        "channel": "email",
        "contactPointValue": "john.doe@example.com",
        "status": "opt_in"
      },
      {
        "subscriptionId": "sms-alerts",
        "channel": "sms",
        "contactPointValue": "+1 555 123 4567",
        "status": "opt_out"
      }
    ]
    ```
    

### ConsentSubscriptionBulkResponse

Bulk response with results for each subscription update request

*   `results` (_array of ConsentSubscriptionResult_, required) Results for each subscription update request

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### ConsentSubscription

*   `subscriptionId` (_SubscriptionId_, required)
*   `channels` (_SubscriptionChannel_, required)
*   `consentStatus` (_object_) Subscription status information across different channels. This field is only included in the response when the 'expand' parameter contains "consentStatus". For privacy and performance reasons, status is not returned by default.
    
    Includes all fields of `SubscriptionStatusArray`.
    
*   `title` (_SubscriptionTitle_)
*   `subtitle` (_SubscriptionSubtitle_)
*   `tags` (_array of Tag_)  
    Default: `[]`. Minimum items: 0. Maximum items: 10.
    
    _Example_
    
    ```
    [
      "homepage_banner",
      "user_profile"
    ]
    ```
    
*   `consentType` (_string_) Type of consent subscription  
    Allowed values: `marketing`, `legal`. Default: `marketing`. Example: `marketing`.
*   `consentRequired` (_boolean_) Whether this subscription is mandatory for the user  
    Default: `false`. Example: `false`.
*   `defaultStatus` (_string_) Default consent status for this subscription  
    Allowed values: `opt_in`, `opt_out`. Default: `opt_out`. Example: `opt_out`.

### SubscriptionId

Identifier for the communication subscription

Type: `string`.

Minimum length: 1. Maximum length: 255. Pattern: ^\[a-z0-9\]+(?:-\[a-z0-9\]+)\*$. Example: `weekly-newsletter`.

### ContactPointValue

The customer's contact point value, polymorphic based on the channel type as below:

*   `sms` - Subject's phone number in E.164 format, ex: `+1 424 535 3546`
*   `email` - Subject's email address in RFC 5321 & RFC 5322 format, ex: `jack.sparrow@salesforce.com`

Type: `string`.

Minimum length: 3. Maximum length: 320. Example: `jack.sparrow@salesforce.com`.

### ChannelType

Type: `string`.

Allowed values: `email`, `sms`, `whatsapp`. Example: `email`.

### ConsentStatus

The consent status of the subscription as supplied or recorded by this system

Type: `string`.

Allowed values: `opt_in`, `opt_out`. Example: `opt_in`.

### ConsentSubscriptionResult

Individual subscription update result with input parameters

*   `subscriptionId` (_SubscriptionId_, required)
*   `channel` (_ChannelType_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `status` (_ConsentStatus_, required)
*   `success` (_boolean_, required) Whether the subscription update was successful  
    Example: `true`.
*   `error` (_object_) Error details (present when success is false)
    
    Includes all fields of `ConsentSubscriptionError`.
    

### SubscriptionChannel

Array of `ChannelType`.

Minimum items: 1. Maximum items: 3. Unique items.

_Example_

```
[
  "email",
  "sms"
]
```

### SubscriptionStatusArray

Array of subscription status entries for different channels

Array of `SubscriptionStatusEntry`.

Minimum items: 0. Maximum items: 10.

_Example_

```
[
  {
    "channel": "email",
    "contactPointValue": "john.doe@example.com",
    "status": "opt_in"
  },
  {
    "channel": "sms",
    "contactPointValue": "+1 555 123 4567",
    "status": "opt_out"
  }
]
```

### SubscriptionTitle

The localized title of the subscription for shopper displays

Type: `string`.

Minimum length: 1. Maximum length: 255. Example: `Weekly Newsletter`.

### SubscriptionSubtitle

The localized subtitle of the subscription for shopper displays, may contain HTML markup

Type: `string`.

Minimum length: 1. Maximum length: 2000. Example: `Stay informed about new features. <a href="https://example.com/features">Learn more</a>`.

### ConsentSubscriptionError

Error details for failed subscription updates

*   `code` (_string_, required) Error code indicating the type of failure  
    Maximum length: 100. Example: `INVALID_CONTACT_POINT`.
*   `message` (_string_, required) Human-readable error message  
    Maximum length: 500. Example: `Invalid email address format`.
*   `details` (_object_) Additional error details
    
    _Example_
    
    ```
    {
      "field": "contactPointValue",
      "provided": "invalid-email"
    }
    ```
    

### SubscriptionStatusEntry

Individual subscription status entry for a specific channel

*   `channel` (_ChannelType_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `status` (_ConsentStatus_, required)

_Example_

```
{
  "channel": "email",
  "contactPointValue": "john.doe@example.com",
  "status": "opt_in"
}
```

<!-- document id=62bd74a40af1722f9298162508f6615c67ea2d4757474faeda08b82a175c8c90 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-api.md -->

# Shopper Context

SCAPI provides the following capabilities for personalizing headless storefront shopper experiences:

- Shopper Context API
- Hooks/Script API

This topic describes how to work with the Shopper Context API.

## Shopper Context API Benefits

The Shopper Context API provides the following benefits versus using hooks and Script API:

- You don't need to write hooks or deploy a cartridge.
- You don't need to understand the qualification rules and corresponding Script API.
- You can set qualifiers, including `effectiveDate` and `couponCodes`, that aren't available in the Script API.
- You can set context one time and have it respected across all SCAPI calls, with state maintained for several days.

The following table provides shopper personalization example use cases:

| Example Use Case                               | Preferred Personalization Method        | Qualifier Used                                          | Cache Support |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------------------- | ------------- |
| Shop the Store                                 | Shop the Future Shopper Context "store" | "effectiveDateTime"                                     | No            |
| All Salesforce employees get employee pricing. | Native SCAPI                            | Dynamic Customer Group – Email endswith @salesforce.com | Yes           |

Use the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) to personalize shopping experiences:

- [Send promotions on store selection](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-store-specific.html)
- [Track contextual information about a shopper, such as location, device type](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-personalized.html)
- [Give special pricing to shoppers who use a source code](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-source-code.html)
- [Preview your storefront as it would look like in the future](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-future.html)

**warning:** Access tokens whose scope includes the Shopper Context API are powerful: they can activate specific promotions and be used to see how a storefront would appear in the future. Don't share them with untrusted clients like web browsers or client apps.

It is highly recommended to use Shopper Context calls with a private client and to only make setting Shopper Context calls through a secure backend channel. Users of Shopper Context should avoid making direct calls through a browser or similar clients where the data can be viewed to prevent potential misuse.

As part of this, when creating a new public client in SLAS for a tenant, if adding Shopper Context scope is attempted, a warning message is displayed to make sure that the user is aware of the pitfalls of doing so.

Let’s look at a shopper’s personalized journey while browsing for jackets in the Northern Trail Outfitters shopping app:

1. She visits the shopping app and starts as a guest shopper
2. She’s from Seattle and notices that signing up to receive email promotions gets 15% off her purchase.
3. After signing up, she logs in to the shopping app. The two contexts reveal that:
   - She’s browsing from the city of Seattle.
   - She’s logged in to the shopping app.
4. She takes advantage of the 15% off and makes a purchase!

![Shopper context data flow throughout customer journey](https://developer.salesforce.com/docs/media/commerce-api/shopper-context-journey.png)

## Shopper Context Lite

To personalize the first Shopper API request without first creating shopper context and waiting for the response, use [Shopper Context Lite](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-lite.html). It applies a lightweight subset of context (`clientIp`, `sourceCode`, and up to two `customQualifiers`) through the `sfdc_shopper_context` request header, so a storefront can skip a separate context-setup call on the critical path.

Use Shopper Context Lite for context that's available when a shopper arrives. For all other context, such as customer groups, coupon codes, assignment qualifiers, effective dates, and geolocation, use the Shopper Context API described on this page.

## Set and Retrieve Shopper Context

To set and retrieve shopper context with the Shopper Context API:

1. Enable Shopper Context in Business Manager:
   1. Log in to Business Manager.
   2. Go to **Merchant Tools** | **_site_** | **Site Preferences** | **Hybrid Auth Settings**.
   3. Enable **Shopper Context**.
2. Add the `sfcc.shopper-context.rw` to a [SLAS API Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).
3. Request a SLAS access token.
4. Call the PUT Shopper Context API (in the scope of USID returned with the SLAS access token). Provide the shopper's USID and context you would like to set, using [createShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=createShopperContext) or [updateShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=updateShopperContext) endpoints:

```bash
curl "https://$SHORTCODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID" \
    --method 'PUT' \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{
        "customQualifiers": {
            "deviceType": "mobile"
        },
        "effectiveDateTime": "1999-12-31T23:59:59Z",
        "assignmentQualifiers": {
            "storeId": "boston"
        },
        "sourceCode": "email"
    }'
```

5. After the shopper context is set, make a call to retrieve shopper context information, for example: `GET products`.

## Constraints

- After the shopper is logged out, the shopper’s context is deleted.
- For PRD instances, context is stored for one day for guest shoppers and seven days for registered shoppers. For other instances, a context is stored for one day for both guest and registered shoppers. As a best practice, extend the context periodically by creating a new one.
- The number of contexts that can be stored per instance is limited. By default, the PRD instances can store five million contexts. Other instances can store five thousand. If the limit is reached, subsequent requests to create a context return an HTTP 400 response. For quota limits best practices, see [Update Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-best-practices.html#update-shopper-context).

| B2C Instance Type | Guest Shopper TTL | Registered Shopper TTL | Context Quota limit |
| ----------------- | ----------------- | ---------------------- | ------------------- |
| PRD               | 1 day             | 7 days                 | 5,000,000           |
| Non-PRD           | 1 day             | 1 day                  | 5,000               |

- The Shopper Context API doesn't support custom fields and objects.
- Shopper Context is only compatible with OCAPI that use a `ShopperToken` (or SLAS). OCAPI can work with other authentication schemes, but Shopper Context is only supported with the `ShopperToken` authentication scheme.

<!-- document id=d1acf528e909a8231f4d7b6040eee0031bb26195e2a8e0e691902bb7a75c9959 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-context.md -->

Shopper Context

# Shopper Context

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-context/shopper-context-oas-v1-public.yaml)

## API Overview

With the Shopper Context API, you can set any context information as a key/value pair and use it to retrieve personalized promotions, payment methods, and shipping methods. The context information that is set is evaluated against the customer group definitions to determine a customer group (shopper segment), and is then used to activate the experiences that are associated with a particular segment, such as promotions.

You can also get personalized API responses triggered by shopper context from the [Open Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html) (OCAPI). Support for both the B2C Commerce API and OCAPI allows shopper context to be used in hybrid deployments.

**Warning** Access tokens with a scope that includes the Shopper Context API are powerful. They can activate specific promotions and can be used to see how a storefront would be displayed in the future. Don't share them with untrusted clients like web browsers or client apps.

Make Shopper Context calls with a private client and only set shopper context through a secure backend channel. To avoid misuse, do not make direct calls through a browser or similar client in which data can be viewed.

As part of this, when creating a SLAS public client for a tenant, if you attempt to add the Shopper Context API scope, a warning message is displayed to ensure you are aware of the pitfalls of doing so.

**Note**:

Shopper context is valid for 1 day for guest shoppers and 7 days for registered shoppers. To extend the context set, create a new context. As a best practice, refresh your contexts periodically to ensure that the right personalized experience is rendered for your shoppers.

### Authentication & Authorization

The Shopper Context API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include `sfcc.shopper-context.rw` in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

For more information, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) in the Get Started guides.

**Warning**: As with all APIs, never store access tokens in the browser because this creates a security vulnerability.

### Customization

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached. Shopper context is per-shopper state that changes with each context update.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Set Shopper Context

Set context attributes for a shopper to personalize subsequent API responses.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/{organizationId}/shopper-context/{usid}?siteId=RefArch" \
  -X PUT \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "customQualifiers": { "deviceType": "mobile" }, "assignmentQualifiers": { "storeId": "boston" } }'
```

For detailed usage information, see the [Shopper Context guides](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html).

**Version:** 1.1.4

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-context/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-context: Shopper Context READONLY
    *   Scope sfcc.shopper-context.rw: Shopper Context
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-context: Shopper Context READONLY
    *   Scope sfcc.shopper-context.rw: Shopper Context
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-context: Shopper Context READONLY
    *   Scope sfcc.shopper-context.rw: Shopper Context

## Operations

### GET Get the shopper's context based on the shopperJWT.

`GET /organizations/{organizationId}/shopper-context/{usid}`

Operation ID: `getShopperContext`. Security: ShopperToken (sfcc.shopper-context, sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context, sfcc.shopper-context.rw).

#### Parameters

*   `usid` (path, string, required) The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The site context.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.

#### Responses

*   **200** Shopper Context retrieved successfully.
    
    Headers:
    
    *   `X-Geolocation` (string) The response header returns the geolocation based on the `clientIp` or `geoLocation` attribute set in the shopper context. If both are set, `geoLocation` takes precedence.  
        Example: `CountryCode: US; Country: United States; MetroCode: 0; Latitude: 37.751; Longitude: -97.822`.
    
    Media type: `application/json`. Schema: `ShopperContext`.
    
    _Example: ShopperContextExample_
    
    ```
    {
      "effectiveDateTime": "2020-12-20T00:00:00Z",
      "sourceCode": "wii1-98",
      "customQualifiers": {
        "deviceType": "mobile",
        "ipAddress": "189.0.0.0",
        "operatingSystem": "Android"
      },
      "assignmentQualifiers": {
        "store": "boston"
      },
      "customerGroupIds": [
        "BigSpenders",
        "MobileUsers"
      ],
      "clientIp": "12.12.12.1",
      "couponCodes": [
        "Save20",
        "FREESHIP"
      ]
    }
    ```
    
*   **400** The usid in the incoming request does not match the usid in the token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getShopperContext400_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/usid-not-matching-with-token",
      "detail": "Usid in incoming request does not match Usid in token.",
      "title": "Usid not matching with token"
    }
    ```
    
*   **401** Your shopper JWT is invalid and cannot be used to identify the API client.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getShopperContext401_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your shopper JWT is invalid and could not be used to identify the API client."
    }
    ```
    
*   **403** Your shopper JWT is valid, but you do not have permission to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getShopperContext403_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Your shopper JWT is valid, but you have no permissions to access the resource."
    }
    ```
    
*   **404** Shopper Context for ORGANIZATION\_ID - f\_ecom\_bhbv\_prd and USID - 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in repository.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getShopperContext404_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/shopper-context-no-found",
      "detail": "Shopper Context for ORGANIZATION_ID: f_ecom_bhbv_prd and USID: 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in Repository.",
      "title": "Shopper Context Not Found"
    }
    ```
    

### PUT Create the shopper's context based on the shopperJWT. If a shopper context already exists, the entire existing context is replaced.

`PUT /organizations/{organizationId}/shopper-context/{usid}`

Operation ID: `createShopperContext`. Security: ShopperToken (sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context.rw).

#### Parameters

*   `usid` (path, string, required) The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The site context.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `evaluateContextWithClientIp` (query, boolean)
    
    Determines whether to evaluate the context using the provided `clientIp`. This property is available with B2C Commerce version 24.7.
    
    *   If `evaluateContextWithClientIp` is set to `true`:
        
        *   The `clientIP` is saved and used in subsequent requests.
    *   If `evaluateContextWithClientIp` is set to `false`:
        
        *   The `clientIP` is not saved and will not be used in subsequent requests.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.

#### Request body (required)

Media type: `application/json`. Schema: `ShopperContext`.

_Example ShopperContextExample: same as GET /organizations/{organizationId}/shopper-context/{usid} 200 response._

#### Responses

*   **200** The shopper's context was created successfully.
    
    Headers:
    
    *   `X-Geolocation` (string) The response header returns the geolocation based on the `clientIp` or `geoLocation` attribute set in the shopper context. If both are set, `geoLocation` takes precedence.
*   **201** The shopper's context was created successfully.
    
    Headers:
    
    *   `X-Geolocation` (string) The response header returns the geolocation based on the `clientIp` or `geoLocation` attribute set in the shopper context. If both are set, `geoLocation` takes precedence.
*   **400** The usid in the incoming request does not match the usid in the token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getShopperContext400: same as GET /organizations/{organizationId}/shopper-context/{usid} 400 response._
    
*   **401** Your shopper JWT is invalid and cannot be used to identify the API client.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getShopperContext401: same as GET /organizations/{organizationId}/shopper-context/{usid} 401 response._
    
*   **403** Your shopper JWT is valid, but you do not have permission to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example Forbidden: same as GET /organizations/{organizationId}/shopper-context/{usid} 403 response._
    

### DELETE deleteShopperContext

`DELETE /organizations/{organizationId}/shopper-context/{usid}`

Operation ID: `deleteShopperContext`. Security: ShopperToken (sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context.rw).

Delete the shopper's context based on the shopperJWT.

#### Parameters

*   `usid` (path, string, required) The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The site context.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.

#### Responses

*   **204** The shopper's context was deleted successfully.
*   **400** The usid in the incoming request does not match the usid in the token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getShopperContext400: same as GET /organizations/{organizationId}/shopper-context/{usid} 400 response._
    
*   **401** Your shopper JWT is invalid and cannot be used to identify the API client.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getShopperContext401: same as GET /organizations/{organizationId}/shopper-context/{usid} 401 response._
    
*   **403** Your shopper JWT is valid, but you do not have permission to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example Forbidden: same as GET /organizations/{organizationId}/shopper-context/{usid} 403 response._
    
*   **404** Shopper Context for ORGANIZATION\_ID - f\_ecom\_bhbv\_prd and USID - 7e1f65fb-185c-4788-8cec-05fef8dac77d not found in repository.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getShopperContext404: same as GET /organizations/{organizationId}/shopper-context/{usid} 404 response._
    

### PATCH Update an existing shopper's context based on the Shopper JWT.

`PATCH /organizations/{organizationId}/shopper-context/{usid}`

Operation ID: `updateShopperContext`. Security: ShopperToken (sfcc.shopper-context.rw); ShopperClientContextToken (sfcc.shopper-context.rw).

If the shopper context exists, it's updated with the patch body.

*   If a new attribute that does not exist in the existing shopper context is present, it is added to the context. -If an attribute is already present in the existing shopper context, its value is replaced by the corresponding value from the new shopper context in the request body as follows:
    
    *   `custom qualifiers` or `assignment qualifiers`:
    
    If the individual qualifier key exists, it is overwritten with the new value.
    
    If the value of the key is set to null, it is deleted from the existing shopper context.
    
    If an empty `custom qualifiers` or `assignment qualifiers` object `{}` is passed, the entire qualifier object is deleted.
    
    *   `effectiveDateTime` or `sourceCode` or `clientIp`:
    
    If the new value is set to an empty string (""), it is deleted from the existing shopper context.
    
    If the new value is set to null, it is ignored.
    
    If the new value is not empty or null, it overwrites the existing value.
    
    *   `customerGroupIds`:
    
    If a list of `customerGroupIds` exists, it is replaced by the new list of customer group IDs from the request.
    
    If `customerGroupIds` is set to an empty array \[\], the existing list in the shopper context is deleted.
    
    *   `geoLocation`:
    
    If it exists, the entire `geoLocation` object is replaced with the new value.
    
    If the new value is set to null, it is ignored.
    
    If an empty `geoLocation` object `{}` is passed, it is deleted.
    

#### Parameters

*   `usid` (path, string, required) The Shopper's unique identifier. It is a required parameter and is part of the response from the Guest or Registered User Shopper Login (SLAS) API call.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The site context.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `evaluateContextWithClientIp` (query, boolean)
    
    Determines whether to evaluate the context using the provided `clientIp`. This property is available with B2C Commerce version 24.7.
    
    *   If `evaluateContextWithClientIp` is set to `true`:
        
        *   The `clientIP` is saved and used in subsequent requests.
    *   If `evaluateContextWithClientIp` is set to `false`:
        
        *   The `clientIP` is not saved and will not be used in subsequent requests.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.

#### Request body (required)

Media type: `application/json`. Schema: `ShopperContext`.

_Example: ShopperContextUpdateRequestBody_

```
{
  "effectiveDateTime": null,
  "customQualifiers": {
    "deviceType": "iPad",
    "operatingSystem": null,
    "storeId": "SLC1"
  },
  "assignmentQualifiers": {
    "store": "london"
  },
  "clientIp": "12.12.12.1",
  "geoLocation": {
    "countryCode": "US",
    "country": "United States of America",
    "city": "Boston",
    "postalCode": "01730",
    "metroCode": "M234",
    "region": "NA",
    "regionCode": "12345",
    "latitude": 10.11,
    "longitude": 198.34
  },
  "couponCodes": [
    "Save20",
    "FREESHIP"
  ]
}
```

#### Responses

*   **200** The shopper context was updated successfully.
    
    Headers:
    
    *   `X-Geolocation` (string)
    
    Media type: `application/json`. Schema: `ShopperContext`.
    
    _Example: ShopperContextUpdateResponseExample_
    
    ```
    {
      "sourceCode": "wii1-98",
      "customQualifiers": {
        "deviceType": "iPad",
        "ipAddress": "189.0.0.0",
        "storeId": "SLC1"
      },
      "assignmentQualifiers": {
        "store": "london"
      },
      "customerGroupIds": [
        "BigSpenders",
        "MobileUsers"
      ],
      "clientIp": "12.12.12.1",
      "geoLocation": {
        "countryCode": "US",
        "country": "United States of America",
        "city": "Boston",
        "postalCode": "01730",
        "metroCode": "M234",
        "region": "NA",
        "regionCode": "12345",
        "latitude": 10.11,
        "longitude": 198.34
      },
      "couponCodes": [
        "Save20",
        "FREESHIP"
      ]
    }
    ```
    
*   **400** The usid in the incoming request does not match the usid in the token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example updateShopperContext400: same as GET /organizations/{organizationId}/shopper-context/{usid} 400 response._
    
*   **401** Your shopper JWT is invalid and cannot be used to identify the API client.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example updateShopperContext401: same as GET /organizations/{organizationId}/shopper-context/{usid} 401 response._
    
*   **403** Your shopper JWT is valid, but you do not have permission to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example updateShopperContext403: same as GET /organizations/{organizationId}/shopper-context/{usid} 403 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### ShopperContext

A shoppers' context represented as key-value string pairs.

*   `effectiveDateTime` (_string (date-time)_, nullable) Qualifier to set the effective date time for the context to apply. For example, "Shop the Future" use cases. If not provided, the current dateTime will be assumed.  
    Example: `2020-12-20T00:00:00Z`.
*   `sourceCode` (_string_, nullable) Qualifier to set the source code for the context to apply. Set the source code to evaluate source code group that triggers the promotion (campaign assignment) and Price books (assigned to Source code group).  
    Example: `wii1-98`.
*   `customerGroupIds` (_array of string_) Qualifier to set the Customer Group Ids for the context to apply. Set the Customer Group Ids to evaluate customer groups that trigger the promotions (campaign assignment) assigned to the customer groups.  
    Items: Maximum length: 256. Example: `BigSpenders`.
*   `customQualifiers` (_object_) Map of custom qualifiers for the shopper context. Set this object to trigger pricing and promotion experiences using a dynamic session-based customer group. Object size is limited to 20 key-value pairs (properties).
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "deviceType": "mobile",
      "ipAddress": "189.0.0.0",
      "operatingSystem": "Android"
    }
    ```
    
*   `assignmentQualifiers` (_object_) Map of assignment qualifiers for the shopper context. Set this object when using the assignment framework to activate experiences based on assignment qualifiers. Currently, only pricing and promotion experiences are supported. Object size is limited to 20 key-value pairs (properties).
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "store": "boston"
    }
    ```
    
*   `clientIp` (_string_)
    
    The IP Address of the client. If the client IP is not a valid IPv4 address, a Bad Request (400) error is thrown. This property is available with B2C Commerce version 24.7.
    
    When `clientIp` is set, the geolocation based on the `clientIp` is returned in the `X-Geolocation` header in the response. Note: Use/retrieve this header in a case insensitive manner.
    
    However, if the `geoLocation` attribute is also set in the context, it takes precedence over the `clientIp`, and the `X-Geolocation` header returns the geolocation based on the `geoLocation` attribute.
    
    The query parameter `evaluateContextWithClientIp` determines whether to evaluate the context using the provided `clientIp`.
    
    *   If `evaluateContextWithClientIp` is set to `true`:
        
        *   The `clientIp` is saved and used in subsequent requests.
        
        Note: If `geoLocation` is also saved in the context, it takes precedence over the `clientIp`.
        
    *   If `evaluateContextWithClientIp` is set to `false`:
        
        *   The `clientIp` is not saved and is not used in subsequent requests.
    
      
    Example: `12.12.12.1`.
*   `geoLocation` (_object_) The geographic location of the client. When you set a geolocation, it is saved as context for subsequent requests. This overrides any geolocation context previously saved using `clientIp`. This property is available with B2C Commerce version 24.7.
    *   `city` (_string_) The city name associated with this location.  
        Example: `Boston`.
    *   `country` (_string_) The country name associated with this location.  
        Example: `United States of America`.
    *   `countryCode` (_string_) The ISO country code associated with this location.  
        Example: `US`.
    *   `latitude` (_number (double)_) The latitude coordinate, which is a number between -90.0 and +90.0, associated with this location.  
        Example: `10.11`.
    *   `longitude` (_number (double)_) The longitude coordinate, which is a number between -180.0 and +180.0, associated with this location.  
        Example: `198.34`.
    *   `metroCode` (_string_) The metro code associated with this location.
    *   `postalCode` (_string_) The postal code associated with this location.  
        Example: `01730`.
    *   `region` (_string_) The region (subdivision) name for this location. Corresponds with "state" in the USA.  
        Example: `NA`.
    *   `regionCode` (_string_) The region (province or state) code for this location.  
        Example: `12345`.
*   `couponCodes` (_array of string_) Array of coupon codes to be saved in the shopper context. Set the coupon codes to evaluate promotions that can be triggered by these codes.  
    Items: Maximum length: 256. Example: `SAVE20`.

_Example_

```
{
  "effectiveDateTime": "2020-12-20T00:00:00Z",
  "sourceCode": "wii1-98",
  "customQualifiers": {
    "deviceType": "mobile",
    "ipAddress": "189.0.0.0",
    "operatingSystem": "Android"
  },
  "assignmentQualifiers": {
    "store": "boston"
  },
  "customerGroupIds": [
    "BigSpenders",
    "MobileUsers"
  ],
  "clientIp": "12.12.12.1",
  "couponCodes": [
    "Save20",
    "FREESHIP"
  ]
}
```

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

<!-- document id=547c809339305821fd9fa56bdfd764c47ad10797d1a3dede0ac7843d9ab20e70 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-shopper-context.md -->

# Shopper Context

Shopper Context enables personalized commerce experiences by associating session-level attributes—such as source codes, customer groups, custom qualifiers, and assignment qualifiers—with a shopper's session. These attributes influence pricing, promotions, product sorting, and other backend behaviors, and you don't need to change individual API calls.

This integration wraps the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) and manages qualifier state through server middleware, cookies, and a React hook.

## Feature Flag

By default, Shopper Context is disabled. Turn it on with an environment variable or configuration:

```bash
PUBLIC__app__features__shopperContext__enabled=true
```

When Shopper Context is off, the middleware exits early and doesn't call Salesforce Commerce API (SCAPI).

## How It Works

Qualifiers enter the system through two paths:

1. URL query parameters: The server middleware extracts qualifiers from the URL on every request (for example, `?src=spring-sale&deviceType=mobile`).
2. React hook: The `useShopperContext` hook lets components update qualifiers from UI interactions (for example, store selector, coupon input).

Both paths merge new qualifiers with the current state stored in cookies, then send the full merged context to SCAPI with a PUT request that fully replaces the existing context. The integration writes the updated state back to cookies for subsequent requests.

The SCAPI `personalized=none` query parameter tells SCAPI to skip Shopper Context. If Shopper Context can change a response, leave the request unclassified and don't set `personalized=none` explicitly. See [Classify Non-Personalized Responses](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md#classify-non-personalized-responses).

## Qualifier Support

The template supports the following qualifiers from the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=type%3AShopperContext) out of the box:

| API Field              | URL Parameter | Notes                                                        |
| ---------------------- | ------------- | ------------------------------------------------------------ |
| `sourceCode`           | `src`         | Campaign/source code for attribution and promotion targeting |
| `couponCodes`          | `couponCodes` | Comma-separated list of coupon codes                         |
| `customQualifiers`     | `deviceType`  | For example, `?deviceType=mobile`                            |
| `assignmentQualifiers` | `store`       | For example, `?store=boston`                                 |

`effectiveDateTime`, `customerGroupIds`, `clientIp`, and `geoLocation` aren't enabled by default. To turn them on, update `SHOPPER_CONTEXT_SEARCH_PARAMS` in `src/lib/shopper-context/constants.ts`. Verify that the API supports the qualifier—see the [ShopperContext type reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=type%3AShopperContext). The `geoLocation` qualifier is a structured object, so it typically needs additional handling.

To add a validation layer on commerce API requests, consider the [Shopper Context Hooks](https://github.com/SalesforceCommerceCloud/shopper_context_hooks) cartridge. It intercepts calls to create/update context and validates the body against a predefined scope for a given client ID.

## Cookies

Shopper Context uses two `httpOnly` cookies to persist qualifier state on the server. The server reads qualifier state from the cookies, so the integration doesn't refetch the full context from SCAPI on every request. The middleware also includes those qualifiers in subsequent GET calls without extra API round-trips.

| Cookie          | Base Name                 | Default Expiry | Format      | Purpose                           |
| --------------- | ------------------------- | -------------- | ----------- | --------------------------------- |
| Shopper Context | `storefront-next-context` | 6 hours        | JSON object | All qualifiers except source code |
| Source Code     | `dwsourcecode`            | 30 days        | Bare string | Source code qualifier             |

The `dwsourcecode_*` cookie stores the bare source-code string (for example, `email`) rather than a JSON object so SFRA storefronts running side-by-side can read the same cookie name and value format directly.

On each request, the middleware reads current state from cookies, merges in any new qualifiers, sends the merged context to SCAPI if anything changed, and writes updated cookies back. New values overwrite existing keys. The merge preserves unmentioned keys.

## Customization

To add a new qualifier, edit `SHOPPER_CONTEXT_SEARCH_PARAMS` in `src/lib/shopper-context/constants.ts`. After you add a qualifier, the template supports it automatically in both URL query parameters and the `useShopperContext` hook.

To update qualifiers programmatically from a component, use the `useShopperContext` hook. It accepts the same qualifier keys used in URL parameters and updates SCAPI and cookies without a full page navigation.

```typescript
import { useShopperContext } from "@/hooks/use-shopper-context";

function StoreSelector() {
  const { updateQualifiers, isLoading, error, success } = useShopperContext();

  const handleStoreChange = (storeId: string) => {
    updateQualifiers({ store: storeId });
  };

  return (
    <select onChange={(e) => handleStoreChange(e.target.value)} disabled={isLoading}>
      <option value="boston">Boston</option>
      <option value="nyc">New York</option>
    </select>
  );
}
```

## Expiry

- Browser cookies: The storefront clears these cookies when the shopper logs out or if authentication fails. The shopper context cookie expires after 6 hours, and the source code cookie expires after 30 days. Cookie expiry values are defined in `src/lib/shopper-context/constants.ts`.
- API-side context: The API ties context to the USID (Unique Shopper ID). The API doesn't currently notify the storefront when the backend clears context, so the storefront can't detect the change. The next request re-creates the context when the shopper sets new qualifiers.

<!-- document id=513a88fa757e029fbf09587fcee75894f486b245782abe3d86260a0b57f79091 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-best-practices.md -->

# Shopper Context Best Practices

The Shopper Context API is essential for managing personalized shopping experiences on your storefront. It is designed to optimize interactions for both guest and registered users by setting context-specific attributes that enhance personalization and efficiency.

When setting shopper context, the API utilizes the `USID` derived from the SLAS token, ensuring a seamless and secure integration.

**important:** - Always set shopper context information from your Backend for Frontend (BFF) using private clients. Do not use public clients for this purpose.
- Include the `siteId` query parameter in all Shopper Context API requests (`GET`, `PUT`, `PATCH`, and `DELETE`).

## When to Set Shopper Context

- Initial visit or login: Implement shopper context when a shopper logs in or initially visits the storefront, immediately after obtaining the SLAS (Shopper Login and Access Services) token.
- Token refresh: For SLAS token refresh, reuse the existing `USID` to maintain continuity and prevent duplicate records. This is important due to the resources available to store shopper context data.
- Shopper login transition: Set shopper context when:
  - A guest shopper subsequently logs in as a registered shopper.
  - A registered shopper subsequently logs in as a guest shopper.
- Session Management: Reset the context upon user login as logging out clears the existing shopper context.

## Shopper Context Updates

- Context lifetime: Shopper context records last 1 day for guest shoppers and 7 days for registered shoppers. Regular updates are crucial to keep the context current.
- Quota limits: Be aware of the default quota limits for the number of shopper context records that can be created in a B2C Commerce instance:
  - 5000 records for non-Production instances.
  - 5 million for Production instances.
  - If you have a legitimate need to increase the limit in your Production instances, contact your Customer Success Manager or Account Executive.
  - Some steps to take before reaching out to increase the quota limits:
    - Lower the Time-to-live (TTL) for registered shopper context from 7 days to 1 or 2 days to automatically clear out context information. Context information can be reset when the shopper logs in again.
    - Reuse the `USID` for the same shopper to avoid duplicate shopper context records.
    - Explicitly log out shoppers to delete the corresponding shopper context record.
  - In B2C Commerce version 25.1, view your quota and usage. Log in to Business Manager and navigate to **Administration** > **Site Development** > **Salesforce Commerce API Settings**.
- Avoid duplicates: Reuse `USID`s and verify existing contexts before setting new ones.
- Efficient resource use: Regularly update existing contexts to optimize the limited storage available.
- Preferred timing for updates: Align context updates with token refresh events to maintain consistency and minimize redundant updates.

## Integration

- Update your API integrations to include the `siteId` query parameter in all requests to the Shopper Context API. The following example shows the updated request format:

```text
shopper/shopper-context/v1/organizations/{organizationId}/shopper-context/{usid}?siteId={siteId}
```

## When Not to Use Shopper Context

Do not use Shopper Context when attributes like customer profiles and addresses are automatically assigned and evaluated.

## Shopper Context Use Cases

- Store personalization: At login, use the Shopper Context API to set the store ID in both the `customerQualifier` and `assignment` qualifier, ensuring tailored interactions per store.
- Dynamic personalization: Use store IDs from the Shopper Context for personalized pricing and promotions during the session.
  - The store ID is retrieved from the context and stored in the session for future reference, for example: `session.custom.storeId`.
  - If dynamic customer groups are set for specific store IDs, it activates experiences assigned with the corresponding customer groups.
- Pricebook and promotion triggers: Use shopper context to activate specific pricebooks and promotions. For example, setting the store ID to `BOST1` might trigger the `BOSPRICEBOOK` and `10%OFFPROMOTION` for that particular store. Subsequent product retrieval calls will return personalized responses based on these triggers.

## Constraints

Sorting Rules are not supported.

<!-- document id=2957db91671c553befd468d855d6b577a2c3054ab57230b74907d6c1b63b1cab url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-lite.md -->

# Shopper Context Lite

**warning:** Shopper Context Lite is not currently recommended for production personalization. Because of a known caching limitation, one shopper can receive content that's personalized for another shopper. This limitation will be resolved in an upcoming release.

Shopper API `GET` responses can be cached and reused across shoppers regardless of the `sfdc_shopper_context` header, so a response generated for one context can be returned to a shopper in a different context. For details, see [Caching](#caching).

Until the fix is available, use the [Shopper Context API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md) for personalization that must be isolated per shopper.

Shopper Context Lite uses the `sfdc_shopper_context` request header to apply a lightweight subset of shopper context to personalized Shopper API requests. A headless storefront can start personalized requests immediately, without first creating shopper context and waiting for the response.

Use Shopper Context Lite for context that a storefront knows when a shopper arrives, such as an IP address, source code, or limited storefront-specific qualifiers. For context such as customer groups, coupon codes, assignment qualifiers, effective dates, and geolocation, use the [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html). Shopper Context Lite complements the Shopper Context API and doesn't replace it.

## Benefits

- Applies personalization on the first personalized Shopper API request, without a preceding context update.
- Removes the client-side waterfall for the supported properties.
- Preserves other stored shopper context when lite values are merged.
- Uses a compact, bounded payload.
- Is optional and backward compatible. Requests without the header use the stored shopper context.
- Doesn't require an additional OAuth scope.

## Before You Begin

Obtain a Shopper Login and API Access Service (SLAS) shopper access token that authorizes the Shopper API request. The token provides the unique shopper ID (USID) that B2C Commerce uses to associate stored shopper context with the shopper.

Shopper Context Lite doesn't require an additional OAuth scope. If you also use the Shopper Context API to create or update context, add the `sfcc.shopper-context.rw` scope to your SLAS API client. See [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md#set-and-retrieve-shopper-context).

Review [Shopper Context Best Practices](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-best-practices.html) for additional guidance, quota limits, and time-to-live (TTL) considerations for shopper context.

## Add Shopper Context Lite to a Request

Add the `sfdc_shopper_context` header to each personalized Shopper API request that depends on Shopper Context Lite. Set the header value to a minified JSON object.

This example applies shopper context when retrieving a product.

```bash
curl "https://$SHORT_CODE.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/$ORGANIZATION_ID/products/$PRODUCT_ID?siteId=$SITE_ID" \
    --header "Authorization: Bearer $SLAS_ACCESS_TOKEN" \
    --header 'sfdc_shopper_context: {"clientIp":"203.0.113.42","sourceCode":"summer2026","customQualifiers":{"deviceType":"mobile","channel":"app"}}'
```

- `SHORT_CODE`: The short code for your B2C Commerce instance.
- `ORGANIZATION_ID`: The organization ID for your B2C Commerce instance.
- `PRODUCT_ID`: The product ID to retrieve.
- `SITE_ID`: The site ID associated with the SLAS access token.
- `SLAS_ACCESS_TOKEN`: A SLAS shopper access token that authorizes the request.

The request must include valid SLAS authorization and all scopes required by the Shopper API operation.

Shopper Context Lite accepts only these properties in the header value. All properties are optional.

| Property           | Type   | Limits and Behavior                                                             |
| ------------------ | ------ | ------------------------------------------------------------------------------- |
| `clientIp`         | string | A valid IPv4 address up to 15 characters. Use it for location-derived personalization on the first request. |
| `sourceCode`       | string | An active campaign source code up to 256 characters.                            |
| `customQualifiers` | object | Free-form key-value pairs for session-based personalization rules. The object supports a maximum of two properties, and each value supports a maximum of 256 characters. |

Shopper Context Lite ignores properties other than `clientIp`, `sourceCode`, and `customQualifiers`. To set other properties, such as `assignmentQualifiers`, `customerGroupIds`, `couponCodes`, `effectiveDateTime`, or `geoLocation`, call `createShopperContext` or `updateShopperContext` in the Shopper Context API.

## Understand Merge and Precedence Behavior

For each request that includes `sfdc_shopper_context`, B2C Commerce resolves context for the current shopper USID and `siteId`.

- If stored shopper context doesn't exist, B2C Commerce creates it from the supported header properties.
- If stored shopper context exists, B2C Commerce merges the supported header properties into it. Values supplied in the header take precedence over matching stored values. Stored context outside the supplied values remains available.
- B2C Commerce stores the combined context only when a supplied property changes.
- B2C Commerce applies the combined context to the current request before returning the personalized response.

For example, consider this stored context.

```json
{
  "clientIp": "198.51.100.10",
  "sourceCode": "spring2026",
  "customQualifiers": {
    "deviceType": "desktop"
  },
  "assignmentQualifiers": {
    "storeId": "store1"
  }
}
```

The next Shopper API request includes this header value.

```json
{
  "sourceCode": "summer2026",
  "customQualifiers": {
    "deviceType": "mobile"
  }
}
```

B2C Commerce applies this combined context to the request.

```json
{
  "clientIp": "198.51.100.10",
  "sourceCode": "summer2026",
  "customQualifiers": {
    "deviceType": "mobile"
  },
  "assignmentQualifiers": {
    "storeId": "store1"
  }
}
```

The header overrides `sourceCode` and `customQualifiers`. The stored `clientIp` and `assignmentQualifiers` remain unchanged.

## Send the Header on Parallel Requests

Storefronts commonly make several personalized Shopper API requests in parallel, such as requests for product details, prices, inventory, and recommendations. Add the same `sfdc_shopper_context` header to every parallel request that depends on the context. B2C Commerce compares the supplied values with the stored context and stores an update only when a value changes.

**important:** Send consistent header values on concurrent requests. If concurrent requests provide different values for the same shopper context property, request processing order determines the final stored value. Create one immutable context snapshot per page render or navigation, and reuse its serialized header value across all parallel requests.

## Caching

Don't rely on the `sfdc_shopper_context` header to isolate cached responses.

When two Shopper API `GET` requests are otherwise identical, a cached response generated from one Shop
per Context Lite value can be returned for a later request, even if the later request sends a differen
t `sfdc_shopper_context` value or doesn't include the header. The later shopper can therefore receive
content personalized for the earlier context.

For any response that can vary based on Shopper Context Lite, prevent the response from being reused a
cross shoppers.

## Combine Shopper Context Lite with the Shopper Context API

Shopper Context Lite is optimized for the small set of values commonly known at page entry. It doesn't replace create or update operations in the Shopper Context API. A typical integration is:

1. Build a validated lite-context object from server-trusted request information.
2. Attach the same serialized object to all relevant Shopper API requests started in parallel for the page.
3. Call the Shopper Context API when the shopper experience requires properties outside the lite subset.
4. On later requests, omit the header to use stored context, or continue sending it when those values must change going forward.

Use Shopper Context Lite to apply these properties on the first personalized request:

- Client IP address
- Source code
- Up to two custom qualifiers

Use the Shopper Context API to set or update these properties:

- Assignment qualifiers
- Coupon codes
- Customer group IDs
- Effective date and time
- Geolocation

**note:** Lite header values and full Shopper Context API updates use last-write-wins behavior for overlapping properties. If a later `PUT` or `PATCH` request supplies a different value for a property that was set through the header, the last request that B2C Commerce processes determines the value. Coordinate updates so that parallel requests don't send different values for the same shopper.

## Best Practices

### Validate Before You Serialize

Don't forward arbitrary query parameters, cookies, or client-provided JSON directly into the header. Allowlist qualifier keys and validate lengths, formats, and permitted values on the server before you serialize the header.

### Don't Send Stale Values

When a supported property is present in the header, it overrides the stored value for that request and becomes part of the merged stored context. Don't send stale values on every request, because they can overwrite a newer full-context update.

### Keep the Request Header Small

The lite payload is bounded, but it contributes to the total request-header size. Use short qualifier keys and only the values required for personalization. Account for authorization, cookies, tracing, and proxy-added headers when you evaluate total header size.

## Limitations

- Shopper Context Lite supports only `clientIp`, `sourceCode`, and `customQualifiers`. Full personalization still requires the Shopper Context API for properties outside this subset.
- Shopper Context Lite doesn't create promotions, assignments, source code groups, or dynamic customer groups. The header values must match active Business Manager configuration.
- Storage lifetimes for shopper context and instance quotas are unchanged.
- B2C Commerce scopes the header by the current shopper USID and `siteId`. It isn't a global storefront setting.
- Shopper Context Lite doesn't isolate cached responses across shoppers. See [Caching](#caching).

## See Also

- [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md)
- [Shopper Context Best Practices](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-best-practices.md)
- [Shopper Geolocation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-geolocation.md)
- [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md)

<!-- document id=230991c022d4ff4081b542b34a1d6ae5561ed3fe0887a7b25e8adcc9101b9561 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-custom-objects.md -->

Shopper Custom Objects

# Shopper Custom Objects

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-custom-objects/shopper-custom-objects-oas-v1-public.yaml)

## API Overview

Custom Objects hold configuration information that is unique to your business, such as third-party configuration information or special field values for Product Information Management (PIM) systems.

For example, if your out-of-the-box B2C Commerce product attributes do not include employee ID information, you can create a custom attribute for employee ID and use this API to retrieve the information. You provide access to this Custom Object information when requesting a SLAS token.

Use Business Manager to set up Custom Object types, including a definition of the object and the values it contains.

Use the Shopper Custom Objects API to retrieve Custom Object information. You can specify an object type ID as well as a key attribute for the object.

### Authentication & Authorization

The Shopper Custom Objects API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include `sfcc.shopper-custom-objects.{object_type}` in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

Important:

Using an additional scope namespace, you can define exactly which Custom Object types a specific token can access. The requested custom `object_type` must exactly match the `object-type` specified in the scope. Note that SLAS is capable of handling a maximum of 20 Custom Object scopes.

For example, to limit access to a specific Custom Object type, such as `employee_details`, include it as the `object_type`. In this case, only the `employee_details` custom object type can be accessed:

```
sfcc.shopper-custom-objects.employee_details
```

To grant global access to all Custom Object types, specify:

```
sfcc.shopper-custom-objects
```

For access to multiple Custom Object types, define the applicable scope(s) in the SLAS API client scopes to be included in the SLAS token, for example:

```
sfcc.shopper-custom-objects.employee_details
sfcc.shopper-custom-objects.employee_performance
```

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

### Request Details

#### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached. Custom object data is dynamic and may change frequently.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get a Custom Object

Retrieve a custom object by its type and key.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/custom-object/shopper-custom-objects/v1/organizations/{organizationId}/custom-objects/employee_details/emp_123?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Create and View Custom Object Types

Custom object types are created in Business Manager:

1.  Navigate to **Administration** -> **Site Development** -> **Custom Object Types**.
2.  In the **Custom Object Type List** section, the available Custom Objects are listed.
3.  To create a new Custom Object type, select **New** and enter the applicable information. This creates the `custom_object_type` information that is in the call to the Shopper Custom Objects API endpoint.

Additionally, keys that provide additional information can be defined for Custom Object types, for example, a `employee_id` key for an `employee_details` Custom Object type.

#### Request Custom Object Information

To request Custom Object type information, the Custom Object type is specified following `custom-objects/` in the API URL:

```
https://{shortCode}/custom-object/shopper-custom-objects/v1/organizations/{organizationId}/custom-objects/{objectType}/{key}
```

`key` is an optional parameter that retrieves additional Custom Object type information, if available.

For example, to retrieve the Custom Object type key `employee_id` for the Custom Object type `employee_details`:

```
https://{shortCode}/custom-object/shopper-custom-objects/v1/organizations/{organizationId}/custom-objects/employee_details/employee_id?siteId=RefArch.
```

### Constraints

Custom Object scopes: SLAS is capable of handling a maximum of 20 custom object scopes.

Custom Objects: Maximum 27 custom objects.

For additional details, see [Governance and Quotas.](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-governance-and-quotas.html)

### Troubleshooting

The Custom Object type requested must exactly match, including case, the information in the SLAS token, for example:

If the scope is `sfcc.custom-object-type.employee_details`, `employee_details` must match the information in the Shopper Custom Objects request:

```
https://…/custom-object/shopper-custom-objects/v1/organizations/f_ecom_bgmj_stg/custom-objects/employee_details/{key}?siteId`
```

If you do not include the `shopper-custom-objects` as part of the SLAS token request, and you subsequently call the Shopper Custom Objects API, a 401 error is returned.

If you specify `key` information when no `key` information has been defined for the Custom Object, a 404 response code is returned.

**Version:** 1.1.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/custom-object/shopper-custom-objects/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-custom-objects: Shopper Custom Objects scope
    *   Scope sfcc.shopper-custom-objects.{objectType}: Shopper Custom Objects objectType READ ONLY scope
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-custom-objects: Shopper Custom Objects scope
    *   Scope sfcc.shopper-custom-objects.{objectType}: Shopper Custom Objects objectType READ ONLY scope
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-custom-objects: Shopper Custom Objects scope
    *   Scope sfcc.shopper-custom-objects.{objectType}: Shopper Custom Objects objectType READ ONLY scope

## Operations

### GET Read a custom object using its object type ID and its unique key attribute value.

`GET /organizations/{organizationId}/custom-objects/{objectType}/{key}`

Operation ID: `getCustomObject`. Security: ShopperToken (sfcc.shopper-custom-objects, sfcc.shopper-custom-objects.{objectType}); ShopperClientContextToken (sfcc.shopper-custom-objects, sfcc.shopper-custom-objects.{objectType}).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `objectType` (path, string, required) The object type of custom object.  
    Minimum length: 1. Example: `Test_Integer`.
*   `key` (path, string, required) The key to identify the custom object.  
    Minimum length: 1. Example: `1`.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Custom object retrieved successfully.
    
    Media type: `application/json`. Schema: `CustomObject`.
    
    _Example: CustomObjectResultExample_
    
    ```
    {
      "keyProperty": "global_key",
      "objectType": "Global_String",
      "c_BooleanAttribute": true,
      "c_DateAttribute": "2015-02-03",
      "c_DateTimeAttribute": "2015-02-20T01:00:00.000Z",
      "c_EmailAttribute": "tralala@gmail.com",
      "c_HtmlAttribute": "<html>\r\n<head><title>some title</title></head>\r\n<body>the body</body>\r\n</html>",
      "c_ImageAttribute": "https://whatever/on/demandware.static/-/Sites/default/v0/home/user/images/image.gif",
      "c_IntegerAttribute": 42,
      "c_IntegerEnumAttribute": 3,
      "c_IntegerSetAttribute": [
        1,
        2
      ],
      "c_NumberAttribute": 42,
      "c_NumberSetAttribute": [
        1,
        1.1
      ],
      "c_PasswordAttribute": "UUIG6ydSpJtdBbYDb1JMd7jgiA1rwYmQTzB5AEvz/YjorR6cIl19cu1IN6H/i/Ol",
      "c_StringAttribute": "Tralala",
      "c_StringEnumAttribute": "Value3",
      "c_StringSetAttribute": [
        "string1",
        "string2"
      ],
      "c_TextAttribute": "This is a text, which is not very meaningful."
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MalformedKeyParameter_
    
    ```
    {
      "title": "Malformed Key Parameter",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-key-parameter",
      "detail": "The format of path parameter 'gdd' for data type 'integer' is invalid.",
      "value": "gdd",
      "parameter": "integer"
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: Unauthorized_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user.",
      "accessToken": "hbGciOiJIUzI1NiIsenR5cCI6Ikp"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomObjectNotFound_
    
    ```
    {
      "title": "Custom Object Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-object-not-found",
      "detail": "No custom object with key '2213' for object type 'Test_Integer' could be found.",
      "key": "2213",
      "objectType": "Test_Integer"
    }
    ```
    
    _Example: ObjectTypeNotFound_
    
    ```
    {
      "title": "Object Type Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/object-type-not-found",
      "detail": "No object type with ID 'Test_Integer1' could be found.",
      "objectType": "Test_Integer1"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### CustomObject

Document representing a custom object that contains all defined custom attributes for its object type.

*   `keyProperty` (_string_) The name of the key property for the custom object. This is ignored in input documents.  
    Example: `global_key`.
*   `keyValueInteger` (_integer (int32)_) The id of the custom object when the type of the key is Integer. This is ignored in input documents.  
    Example: `1`.
*   `keyValueString` (_string_) The id of the custom object when the type of the key is String. This is ignored in input documents.  
    Example: `1`.
*   `objectType` (_string_) The id of the object type. This is ignored in input documents.  
    Maximum length: 256. Example: `Global_String`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

<!-- document id=c29fcbf8aaecb0ae2256f7325c7733da20f1521d9d1da916b26ae1fadd1ece90 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-customers.md -->

Shopper Customers

# Shopper Customers

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-customers/shopper-customers-oas-v1-public.yaml)

## API Overview

The Shopper Customers API enables you to develop functionality that lets customers log in, and manage their profiles and product lists. Profile management includes ability for shoppers to add or modify addresses and payment methods, and add or modify products to wishlists or favorites. Commerce Cloud provides a rich set of Authentication APIs that include logging in guest shoppers, registered shoppers, agents on behalf of customers and a trusted system authentication on behalf of customers. In all authentication scenarios involving customers, a JSON Web Token (JWT) is generated in Commerce Cloud. Using the JWT, customers can access other Shopper API resources like Orders and Baskets. The application must refresh the JWT every 30 minutes to save the shopper activity (for example, retain products in a shopper's cart) for prolonged periods of time.

### Authentication & Authorization

The client requesting the customer information must have access to the Customer and Product List resources. The Shopper Customer API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include the relevant scope(s) in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached. Customer data is personal and unique to each shopper.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get Customer Profile

Retrieve a registered customer profile. Requires a registered shopper SLAS token.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/{customerId}?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Register a New Customer

In this use case, a customer who is browsing on a commerce shopping app built using B2C Commerce APIs would like to create a customer profile, so that they can track their order when logged in on the next visit.

The API flow is shown in the following diagram:

![b2c-commerce-shopper-customers-screenshot-1.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-shopper-customers-screenshot-1.png)

1.  The shopper opens the shopping app.
2.  Request an access token from SLAS. For details, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.
3.  The SLAS API responds with the shopper access token (JWT).
4.  The shopper adds a product to their basket.
5.  Use the Shopper Baskets API to create a basket. The shopper JWT from SLAS is supplied in the authorization header.
6.  Save the basket with a registered user customer ID (even though the shopper is still a guest). The shopper JWT from SLAS is supplied in the authorization header.
7.  The shopper creates a profile.
8.  Use the Shopper Customers API to register the customer.

#### Authenticate a Trusted System on Behalf of a Customer

In this cross-cloud use case, a Experience Cloud user places an order on Commerce Cloud from the Experience Cloud using the platform APIs. The Experience Cloud app is a trusted system that has a trusted relationship with Commerce Cloud using the OAuth client credentials grant against the Commerce Cloud Account Manager. The Experience Cloud user logs in with a redirect to Salesforce IDM and after successful login, the client application is able to call B2C Commerce APIs on behalf of the customer. Commerce Cloud returns a JWT for the Experience Cloud user and the Experience Cloud user is able to place orders on Commerce Cloud.

The API flow is shown in the following diagram:

![b2c-commerce-shopper-customers-screenshot-2.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-shopper-customers-screenshot-2.png)

#### Reset Customer Password

In this use case, a shopper who is browsing on a commerce shopping app, built using B2C Commerce APIs, requests to reset their password. The app verifies the shopper's credentials and returns a 404 if verification fails. Otherwise, when the shopper requests their password to be reset, the app first creates a password reset token using the shopper’s login ID, and an account manager token (obtained using the client credentials grant). After the app has the password reset token, the app can prompt the shopper for new password. Any app-level customization, such as sending a password reset email, can be done at this step. Finally, the app calls the reset endpoint to reset the customer’s password.

![b2c-commerce-shopper-customers-screenshot-3.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-shopper-customers-screenshot-3.png)

#### Update Shopper LoginId

In this use case, in order to update a shopper's loginId, the PATCH /customers/{customerId} call can be used starting B2C Commerce Cloud GA release 24.7. The new field in the request called `currentPassword` is mandatory and needs to match the shopper's existing password. If this field is not provided or does not match the existing shopper password when trying to update loginId, a HTTP 400 response will be returned. If the loginId field is not sent in the PATCH request body, the `currentPassword` field is not required. **Note:** After the `loginId` is updated, a new SLAS token must be fetched for the shopper for subsequent calls.

### Related APIs

*   [Customers (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/customers?meta=Summary) — Manage customer records, addresses, and credentials.

**Version:** 1.10.1

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-customers.register: Shopper Customers Register scope READONLY
    *   Scope sfcc.shopper-myaccount.baskets: Shopper MyAccount Baskets scope READONLY
    *   Scope sfcc.shopper-myaccount.orders: Shopper MyAccount Orders scope READONLY
    *   Scope sfcc.shopper-myaccount.paymentinstruments.rw: Shopper MyAccount PaymentInstruments scope
    *   Scope sfcc.shopper-myaccount.productlists: Shopper MyAccount ProductLists scope READONLY
    *   Scope sfcc.shopper-myaccount.productlists.rw: Shopper MyAccount ProductLists scope
    *   Scope sfcc.shopper-productlists: Shopper ProductLists scope READONLY
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-customers.register: Shopper Customers Register scope READONLY
    *   Scope sfcc.shopper-myaccount.baskets: Shopper MyAccount Baskets scope READONLY
    *   Scope sfcc.shopper-myaccount.orders: Shopper MyAccount Orders scope READONLY
    *   Scope sfcc.shopper-myaccount.paymentinstruments.rw: Shopper MyAccount PaymentInstruments scope
    *   Scope sfcc.shopper-myaccount.productlists: Shopper MyAccount ProductLists scope READONLY
    *   Scope sfcc.shopper-myaccount.productlists.rw: Shopper MyAccount ProductLists scope
    *   Scope sfcc.shopper-productlists: Shopper ProductLists scope READONLY
*   `RegisteredShopperToken` (oauth2) `RegisteredShopperToken` is a child of the `ShopperToken` security scheme and restricts access to a **registered (authenticated) shopper**. Access is only granted to a shopper token that represents a registered shopper; a guest shopper token is rejected. Endpoints secured with `RegisteredShopperToken` operate on identity-bound resources of a registered shopper, such as their addresses, payment instruments, password, or saved product lists. Besides these endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `RegisteredShopperToken`. To get a `RegisteredShopperToken`, the shopper must authenticate with SLAS (for example, through the authorization code flow or the [login endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer)). For details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary).
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-customers.login: Shopper Customers Login scope READONLY
    *   Scope sfcc.shopper-myaccount: Shopper MyAccount scope READONLY
    *   Scope sfcc.shopper-myaccount.rw: Shopper MyAccount scope
    *   Scope sfcc.shopper-myaccount.addresses: Shopper MyAccount Addresses scope READONLY
    *   Scope sfcc.shopper-myaccount.addresses.rw: Shopper MyAccount Addresses scope
    *   Scope sfcc.shopper-myaccount.paymentinstruments: Shopper MyAccount PaymentInstruments scope READONLY
    *   Scope sfcc.shopper-myaccount.paymentinstruments.rw: Shopper MyAccount PaymentInstruments scope
*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-customers.login: Shopper Customers Login scope READONLY
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-customers.register: Shopper Customers Register scope READONLY
    *   Scope sfcc.shopper-myaccount.baskets: Shopper MyAccount Baskets scope READONLY
    *   Scope sfcc.shopper-myaccount.orders: Shopper MyAccount Orders scope READONLY
    *   Scope sfcc.shopper-myaccount.paymentinstruments.rw: Shopper MyAccount PaymentInstruments scope
    *   Scope sfcc.shopper-myaccount.productlists: Shopper MyAccount ProductLists scope READONLY
    *   Scope sfcc.shopper-myaccount.productlists.rw: Shopper MyAccount ProductLists scope
    *   Scope sfcc.shopper-productlists: Shopper ProductLists scope READONLY

## Operations

### POST Register a new customer.

`POST /organizations/{organizationId}/customers`

Operation ID: `registerCustomer`. Security: ShopperToken (sfcc.shopper-customers.register, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-customers.register, sfcc.shopper-standard).

Mandatory data includes the credentials, profile last name, and email. This endpoint requires a guest JSON Web Token (JWT) from the [Shopper Login and API Access Service](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken). The return type object for this endpoint is a common customer object shared by multiple Shopper Customer endpoints. In this case, all customer object details are returned, but attributes that are not included in the response, although they might be part of the customer object, are ignored. For example, although address information is included in the customer object, it is not displayed in the response for this endpoint and is ignored.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerRegistration`.

_Example: CustomerRegistrationBody_

```
{
  "password": "12345!aBcD",
  "customer": {
    "login": "jsmith",
    "email": "jsmith@test.com",
    "firstName": "John",
    "lastName": "Smith"
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example: customerRegistrationResponse_
    
    ```
    {
      "authType": "registered",
      "crmContactId": "003xx000004WhKe",
      "creationDate": "2020-02-13T17:44:15.892Z",
      "customerId": "abkd9LhOWzAiAFubdEDChtkMHW",
      "customerNo": "00006002",
      "email": "jsmith@test.com",
      "emailVerified": false,
      "enabled": true,
      "firstName": "John",
      "hasPassword": true,
      "lastModified": "2020-02-13T17:44:15.898Z",
      "lastName": "Smith",
      "login": "jsmith"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **401** In the case of type credentials, the username is unknown or the password does not match. In the case of type session, the session is no longer active or the dwsecuretoken value is invalid. In both cases, the customer is disabled or locked.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer401_
    
    ```
    {
      "title": "Authentication Failed",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/authentication-failed",
      "detail": "Customer authentication based on JohnSmith failed.",
      "credentialType": "JohnSmith"
    }
    ```
    

### POST Reset customer password after obtaining a reset token.

`POST /organizations/{organizationId}/customers/password/actions/reset`

Operation ID: `resetPassword`. Security: AmOAuth2 (sfcc.shopper-customers.login).

This is the second step in the reset customer password flow, in which a customer password is reset by providing new credentials along with a reset token. This call should be preceded by a call to the /create-reset-token endpoint.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ResetPasswordRequest`.

_Example: ResetPasswordBody_

```
{
  "resetToken": "R1e2s3e4t5T6o7k8e9n0",
  "login": "janedoe@test.com",
  "newPassword": "p@assword2"
}
```

#### Responses

*   **204** Reset password successful. No Content.
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    

### POST Get reset password token.

`POST /organizations/{organizationId}/customers/password/actions/create-reset-token`

Operation ID: `getResetPasswordToken`. Security: AmOAuth2 (sfcc.shopper-customers.login).

This is the first step in the reset customer password flow, in which a password reset token is requested for future use to reset a customer password. This call should be followed by a call to the /reset endpoint.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ResetPasswordTokenRequest`.

_Example: ResetPasswordTokenBody_

```
{
  "login": "janedoe@test.com"
}
```

#### Responses

*   **200** Reset password token generated and returned successfully.
    
    Media type: `application/json`. Schema: `ResetPasswordToken`.
    
    _Example: getResetPasswordTokenSuccess_
    
    ```
    {
      "login": "janedoe@test.com",
      "email": "janedoe@test.com",
      "resetToken": "R1e2s3e4t5T6o7k8e9n0",
      "expiresInMinutes": 30
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    

### GET Gets the new external profile for a customer. This endpoint only accepts a registered customer ShopperToken (JWT).

`GET /organizations/{organizationId}/customers/external-profile`

Operation ID: `getExternalProfile`. Security: AmOAuth2 (sfcc.shopper-customers.login).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `externalId` (query, string, required) The External ID of the customer.  
    Minimum length: 1.
*   `authenticationProviderId` (query, string, required) The authentication Provider Id.  
    Minimum length: 1.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerExternalProfile`.
    
    _Example: getExternalProfileSuccess_
    
    ```
    {
      "authenticationProviderId": "Google",
      "firstName": "John",
      "lastName": "Doe",
      "customerId": "bfqcN48dn2y4EaV9Qj5bNpVJVj",
      "email": "testCustomer@test.com",
      "externalId": "testCustomer@test.com"
    }
    ```
    
*   **400** Customer ExternalId URL parameter is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getExternalProfile400_
    
    ```
    {
      "title": "Invalid Customer External Profile",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer-external-profile",
      "detail": "The customer external profile is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getExternalProfile404_
    
    ```
    {
      "title": "Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "detail": "No customer with external profile with ID 'abfTWMDZOgi3JPzkHjv9IhmziI' could be found.",
      "externalId": "abfTWMDZOgi3JPzkHjv9IhmziI"
    }
    ```
    

### POST Register a new external profile for a customer. This endpoint accepts a guest customer ShopperToken (JWT) only.

`POST /organizations/{organizationId}/customers/external-profile`

Operation ID: `registerExternalProfile`. Security: ShopperToken (sfcc.shopper-customers.register, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-customers.register, sfcc.shopper-standard).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerExtProfileRequest`.

_Example: ExternalProfileBody_

```
{
  "authenticationProviderId": "Google",
  "firstName": "John",
  "lastName": "Doe",
  "email": "testCustomer@test.com",
  "externalId": "testCustomer@test.com"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerExternalProfile`.
    
    _Example registerExternalProfileSuccess: same as GET /organizations/{organizationId}/customers/external-profile 200 response._
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **401** In the case of type credentials, the username is unknown or the password does not match. In the case of type session, the session is no longer active or the dwsecuretoken value is invalid. In both cases, the customer is disabled or locked.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example registerCustomer401: same as POST /organizations/{organizationId}/customers 401 response._
    

### GET Get a customer and all existing addresses and payment instruments associated with the requested customer. This endpoint only accepts a registered customer ShopperToken (JWT).

`GET /organizations/{organizationId}/customers/{customerId}`

Operation ID: `getCustomer`. Security: RegisteredShopperToken (sfcc.shopper-myaccount, sfcc.shopper-myaccount.rw, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `expand` (query, array of string, style: form, explode: false)
    
    Expands the response with additional customer data.
    
    *   addresses (Default)
    *   paymentinstruments (Default)
    *   paymentmethodreferences (Requires Salesforce Payments integration; ignored otherwise)
    *   none (Excludes all expansion data)
    
      
    Items: Allowed values: `none`, `addresses`, `paymentinstruments`, `paymentmethodreferences`.
    
    _Example_
    
    ```
    [
      "addresses",
      "paymentinstruments",
      "paymentmethodreferences"
    ]
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example: getCustomerSuccess_
    
    ```
    {
      "addresses": [
        {
          "address1": "10 Presidential Way",
          "addressId": "me",
          "city": "Woburn",
          "countryCode": "US",
          "firstName": "John",
          "fullName": "John M. Smith",
          "lastName": "Smith",
          "postalCode": "01827",
          "salutation": "Mr.",
          "stateCode": "MA"
        }
      ],
      "authType": "registered",
      "crmContactId": "003xx000004WhKe",
      "creationDate": "2020-02-14T20:39:53.818Z",
      "customerId": "abfTEMDZOgi3JPrkHjv9IhoziM",
      "customerNo": "00010009",
      "email": "jsmith@demandware.com",
      "emailVerified": true,
      "firstName": "John",
      "gender": 1,
      "hasPassword": true,
      "lastName": "Smith",
      "paymentInstruments": [
        {
          "bankRoutingNumber": "0763564",
          "creationDate": "2017-08-20T11:30:36.000Z",
          "lastModified": "2017-08-20T11:30:50.000Z",
          "maskedGiftCertificateCode": "***********ode",
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false,
            "expirationMonth": 2,
            "expirationYear": 2022,
            "holder": "John Smith",
            "maskedNumber": "***********ber2",
            "numberLastDigits": "ber2"
          },
          "paymentInstrumentId": "beybQiWcyatEEaaadniwhKxxFl",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "phoneBusiness": "234560003",
      "phoneHome": "123450003",
      "phoneMobile": "345670003"
    }
    ```
    
    _Example: getCustomerSuccessWithSalesforcePayments_
    
    ```
    {
      "addresses": [
        {
          "address1": "10 Presidential Way",
          "addressId": "me",
          "city": "Woburn",
          "countryCode": "US",
          "firstName": "John",
          "fullName": "John M. Smith",
          "lastName": "Smith",
          "postalCode": "01827",
          "salutation": "Mr.",
          "stateCode": "MA"
        }
      ],
      "authType": "registered",
      "crmContactId": "003xx000004WhKe",
      "creationDate": "2020-02-14T20:39:53.818Z",
      "customerId": "abfTEMDZOgi3JPrkHjv9IhoziM",
      "customerNo": "00010009",
      "email": "jsmith@demandware.com",
      "firstName": "John",
      "gender": 1,
      "hasPassword": false,
      "lastName": "Smith",
      "paymentInstruments": [],
      "paymentMethodReferences": [
        {
          "type": "card",
          "id": "pm_card_1234567890",
          "brand": "visa",
          "last4": "4242",
          "expiryMonth": 12,
          "expiryYear": 2028,
          "accountId": "acct_1RegszI5I22eU0I3"
        },
        {
          "type": "sepa_debit",
          "id": "pm_sepa_debit_1234567890",
          "last4": "5678",
          "accountHolderName": "John Smith",
          "accountId": "acct_1RegszI5I22eU0I3"
        }
      ],
      "phoneBusiness": "234560003",
      "phoneHome": "123450003",
      "phoneMobile": "345670003"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getCustomer404_
    
    ```
    {
      "title": "Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "detail": "No customer with ID 'abfTWMDZOgi3JPzkHjv9IhmziI' could be found.",
      "customerId": "abfTWMDZOgi3JPzkHjv9IhmziI"
    }
    ```
    

### PATCH Update a customer. This endpoint only accepts a registered customer ShopperToken (JWT).

`PATCH /organizations/{organizationId}/customers/{customerId}`

Operation ID: `updateCustomer`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.rw, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `Customer`.

_Example: UpdateCustomerBody_

```
{
  "customerNo": "00010009",
  "firstName": "John",
  "lastName": "Wild",
  "email": "jwild@yourstore.com",
  "fax": "+49 03641 78393 346"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `Customer`.
    
    _Example: updateCustomerResponse_
    
    ```
    {
      "authType": "registered",
      "crmContactId": "003xx000004WhKe",
      "creationDate": "2020-02-14T20:39:53.818Z",
      "customerId": "abfTEMDZOgi3JPrkHjv9IhoziM",
      "customerNo": "00010009",
      "email": "jwild@yourstore.com",
      "emailVerified": true,
      "enabled": true,
      "fax": "+49 03641 78393 346",
      "firstName": "John",
      "hasPassword": true,
      "lastLoginTime": "2020-02-14T20:51:59.313Z",
      "lastModified": "2020-02-14T20:55:12.133Z",
      "lastName": "Wild",
      "lastVisitTime": "2020-02-14T20:51:59.313Z",
      "login": "f0a43dc2-692a-43bf-b008-e10918ea935d",
      "previousLoginTime": "2020-02-14T20:51:59.313Z",
      "previousVisitTime": "2020-02-14T20:51:59.313Z"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### POST Create a new address with the given name for the customer. This endpoint only accepts a registered customer ShopperToken (JWT).

`POST /organizations/{organizationId}/customers/{customerId}/addresses`

Operation ID: `createCustomerAddress`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.addresses.rw, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerAddress`.

_Example: CustomerAddressBody_

```
{
  "addressId": "home_address",
  "address1": "5 Wall St",
  "address2": "24 Presidential Way",
  "city": "Burlington",
  "companyName": "Salesforce Commerce Cloud",
  "countryCode": "US",
  "firstName": "John",
  "jobTitle": "Developer",
  "lastName": "Murphy",
  "phone": "408-555-1212",
  "postalCode": "01805",
  "postBox": "12a",
  "preferred": false,
  "salutation": "Mr.",
  "secondName": "Jim",
  "stateCode": "MA",
  "title": "Dr."
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerAddress`.
    
    _Example: customerAddressResponse_
    
    ```
    {
      "addressId": "home_address",
      "address1": "5 Wall St",
      "address2": "24 Presidential Way",
      "city": "Burlington",
      "companyName": "Salesforce Commerce Cloud",
      "countryCode": "US",
      "creationDate": "2020-02-14T21:13:29.769Z",
      "firstName": "John",
      "fullName": "John Jim Murphy",
      "jobTitle": "Developer",
      "lastModified": "2020-02-14T21:13:29.770Z",
      "lastName": "Murphy",
      "phone": "408-555-1212",
      "postalCode": "01805",
      "postBox": "12a",
      "preferred": false,
      "salutation": "Mr.",
      "secondName": "Jim",
      "stateCode": "MA",
      "title": "Dr."
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Retrieve a customer's address by address name. This endpoint only accepts a registered customer ShopperToken (JWT).

`GET /organizations/{organizationId}/customers/{customerId}/addresses/{addressName}`

Operation ID: `getCustomerAddress`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.addresses, sfcc.shopper-myaccount.addresses.rw, sfcc.shopper-standard).

#### Parameters

*   `addressName` (path, string, required) The name of the address to update.  
    Minimum length: 1. Maximum length: 256.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerAddress`.
    
    _Example customerAddressResponse: same as POST /organizations/{organizationId}/customers/{customerId}/addresses 200 response._
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### DELETE Delete a customer's address by address name. This endpoint only accepts a registered customer ShopperToken (JWT).

`DELETE /organizations/{organizationId}/customers/{customerId}/addresses/{addressName}`

Operation ID: `removeCustomerAddress`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.addresses.rw, sfcc.shopper-standard).

#### Parameters

*   `addressName` (path, string, required) The name of the address to update.  
    Minimum length: 1. Maximum length: 256.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **204** No content
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### PATCH Update a customer's address by address name. This endpoint only accepts a registered customer ShopperToken (JWT).

`PATCH /organizations/{organizationId}/customers/{customerId}/addresses/{addressName}`

Operation ID: `updateCustomerAddress`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.addresses.rw, sfcc.shopper-standard).

#### Parameters

*   `addressName` (path, string, required) The name of the address to update.  
    Minimum length: 1. Maximum length: 256.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerAddress`.

_Example CustomerAddressResponseBody: same as POST /organizations/{organizationId}/customers/{customerId}/addresses 200 response._

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerAddress`.
    
    _Example customerAddressResponse: same as POST /organizations/{organizationId}/customers/{customerId}/addresses 200 response._
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Get the baskets for a customer. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/customers/{customerId}/baskets`

Operation ID: `getCustomerBaskets`. Security: ShopperToken (sfcc.shopper-myaccount.baskets, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.baskets, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `BasketsResult`.
    
    _Example: customerBasketsResult_
    
    ```
    {
      "baskets": [
        {
          "basketId": "bccO1aOjgEnuIaaadk7pYO2rFE",
          "adjustedMerchandizeTotalTax": 0,
          "adjustedShippingTotalTax": 0,
          "agentBasket": true,
          "billingAddress": {
            "address1": "10 Presidential Way",
            "city": "Woburn",
            "countryCode": "US",
            "firstName": "John",
            "fullName": "John M. Smith",
            "id": "abfTEMDZOgi3JPrkHjv9IhoziM",
            "lastName": "Smith",
            "phone": "123450003",
            "postalCode": "01827",
            "salutation": "Mr.",
            "stateCode": "MA"
          },
          "bonusDiscountLineItems": [
            {
              "bonusProducts": [
                {
                  "productDescription": "Bonus Product",
                  "productId": "34984327448",
                  "productName": "Extra Fluffy Bonus Product",
                  "title": "Bonus Product"
                }
              ],
              "couponCode": "BONUS",
              "id": "qhegj345ruhrfkj",
              "maxBonusItems": 1,
              "promotionId": "basds98295jsafi"
            }
          ],
          "channelType": "storefront",
          "couponItems": [
            {
              "code": "5634573",
              "couponItemId": "100-89038",
              "statusCode": "coupon_code_already_in_basket",
              "valid": true
            }
          ],
          "creationDate": "2019-09-05T17:12:56.670Z",
          "currency": "USD",
          "customerInfo": {
            "c_familyStatus": "string",
            "customerId": "abfTEMDZOgi3JPrkHjv9IhoziM",
            "customerName": "John Smith",
            "customerNo": "1000",
            "email": "jsmith@demandware.com"
          },
          "giftCertificateItems": [
            {
              "amount": 0,
              "giftCertificateItemId": "901",
              "message": "Preferred Customer",
              "recipientEmail": "jsmith@demandware.com",
              "recipientName": "John Smith",
              "senderName": "Jane Smith",
              "shipmentId": "678934jsadLHY5"
            }
          ],
          "inventoryReservationExpiry": "2019-09-05T17:12:56.670Z",
          "lastModified": "2019-09-05T17:12:56.670Z",
          "merchandizeTotalTax": 0,
          "orderPriceAdjustments": [
            {
              "appliedDiscount": {
                "amount": 0,
                "percentage": 0,
                "priceBookId": "asdfgh4567",
                "type": "percentage"
              },
              "couponCode": "2345-009",
              "createdBy": "System",
              "creationDate": "2019-09-05T17:12:56.670Z",
              "custom": true,
              "itemText": "string",
              "lastModified": "2019-09-05T17:12:56.670Z",
              "manual": true,
              "price": 0,
              "priceAdjustmentId": "324545673fgjghj",
              "promotionId": "1000-7654",
              "promotionLink": "link to promotion",
              "reasonCode": "PRICE_MATCH"
            }
          ],
          "orderTotal": 0,
          "paymentInstruments": [
            {
              "amount": 0,
              "authorizationStatus": {
                "code": "AUTH",
                "message": "Authorizing",
                "status": 0
              },
              "bankRoutingNumber": "string",
              "maskedGiftCertificateCode": "string",
              "paymentCard": {
                "cardType": "Visa",
                "creditCardExpired": false,
                "creditCardToken": "sadjklfajkgae",
                "expirationMonth": 12,
                "expirationYear": 2019,
                "holder": "John",
                "issueNumber": "389342643978",
                "maskedNumber": "**************53",
                "numberLastDigits": "8753",
                "validFromMonth": 4,
                "validFromYear": 2015
              },
              "paymentInstrumentId": "creditCard",
              "paymentMethodId": "credit"
            }
          ],
          "productItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusDiscountLineItemId": "string",
              "bonusProductLineItem": true,
              "bundledProductItems": [
                {
                  "quantity": 10
                }
              ],
              "gift": true,
              "giftMessage": "string",
              "inventoryId": "string",
              "itemId": "string",
              "itemText": "string",
              "optionItems": [
                {
                  "adjustedTax": 0,
                  "basePrice": 110,
                  "bonusDiscountLineItemId": "dsklgladsjkq349857",
                  "bonusProductLineItem": true,
                  "bundledProductItems": [
                    {
                      "quantity": 10
                    }
                  ],
                  "gift": true,
                  "giftMessage": "Happy Birthday",
                  "inventoryId": "258963",
                  "itemId": "apple-ipod-classic",
                  "itemText": "Apple iPod Classic",
                  "optionId": "34526hjyuGGH56",
                  "optionItems": [
                    {
                      "optionId": "sdiughsdjkfgoqtuy",
                      "optionValueId": "1564897654"
                    }
                  ],
                  "optionValueId": "string",
                  "price": 0,
                  "priceAdjustments": [
                    {
                      "appliedDiscount": {
                        "amount": 0,
                        "percentage": 0,
                        "priceBookId": "34526hjyuGGH56",
                        "type": "percentage"
                      },
                      "couponCode": "109475",
                      "createdBy": "System",
                      "creationDate": "2019-09-05T17:12:56.670Z",
                      "custom": true,
                      "itemText": "",
                      "lastModified": "2019-09-05T17:12:56.670Z",
                      "manual": true,
                      "price": 0,
                      "priceAdjustmentId": "1597563",
                      "promotionId": "963852",
                      "promotionLink": "link to promotion",
                      "reasonCode": "PRICE_MATCH"
                    }
                  ],
                  "priceAfterItemDiscount": 0,
                  "priceAfterOrderDiscount": 0,
                  "productId": "apple-ipod-classic",
                  "productListItem": {
                    "id": "2345245e654utjSSDFfdhh",
                    "priority": 0,
                    "productDetailsLink": {
                      "productDescription": "apple-ipod-classic",
                      "productId": "apple-ipod-classic",
                      "productName": "Apple iPod Classic",
                      "title": "Apple iPod Classic Silver"
                    },
                    "productList": {
                      "description": "My Product List",
                      "name": "Electronics",
                      "public": true,
                      "title": "My Electronics Wish List",
                      "type": "wish_list"
                    },
                    "public": true,
                    "purchasedQuantity": 0,
                    "quantity": 0,
                    "type": "product"
                  },
                  "productName": "Apple iPod Classic",
                  "quantity": 0,
                  "shipmentId": "12345rdsghfjh",
                  "shippingItemId": "47568ghfhjgkg",
                  "tax": 0,
                  "taxBasis": 0,
                  "taxClassId": "STATE",
                  "taxRate": 0
                }
              ],
              "price": 0,
              "priceAdjustments": [
                {
                  "appliedDiscount": {
                    "amount": 0,
                    "percentage": 0,
                    "priceBookId": "string",
                    "type": "percentage"
                  },
                  "couponCode": "sadfghgjw4e56r7",
                  "createdBy": "System",
                  "creationDate": "2019-09-05T17:12:56.672Z",
                  "custom": true,
                  "itemText": "string",
                  "lastModified": "2019-09-05T17:12:56.672Z",
                  "manual": true,
                  "price": 0,
                  "priceAdjustmentId": "asdgfhg5463798453",
                  "promotionId": "100-7345",
                  "promotionLink": "Link to promotion",
                  "reasonCode": "PRICE_MATCH"
                }
              ],
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "string",
              "productListItem": {
                "id": "string",
                "priority": 0,
                "productDetailsLink": {
                  "productDescription": "apple-ipod-classic",
                  "productId": "apple-ipod-classic",
                  "productName": "Apple iPod Classic",
                  "title": "Apple iPod Classic Silver"
                },
                "productList": {
                  "description": "My Product List",
                  "name": "Electronics",
                  "public": true,
                  "title": "My Electronics Wish List",
                  "type": "wish_list"
                },
                "public": true,
                "purchasedQuantity": 0,
                "quantity": 0,
                "type": "product"
              },
              "productName": "Apple iPod Classic",
              "quantity": 0,
              "shipmentId": "12345rdsghfjh",
              "shippingItemId": "47568ghfhjgkg",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "STATE",
              "taxRate": 0
            }
          ],
          "productSubTotal": 0,
          "productTotal": 0,
          "shipments": [
            {
              "adjustedMerchandizeTotalTax": 0,
              "adjustedShippingTotalTax": 0,
              "gift": true,
              "giftMessage": "Happy Birthday",
              "merchandizeTotalTax": 0,
              "productSubTotal": 0,
              "productTotal": 0,
              "shipmentId": "1200",
              "shipmentNo": "3",
              "shipmentTotal": 0,
              "shippingAddress": {
                "address1": "10 Presidential Way",
                "city": "string",
                "countryCode": "US",
                "firstName": "John",
                "fullName": "John M. Smith",
                "id": "abfTWMDZOgi3JPzkHjv9IhmziI",
                "lastName": "Smith",
                "phone": "123450003",
                "postalCode": "01827",
                "salutation": "Mr.",
                "stateCode": "MA"
              },
              "shippingMethod": {
                "c_storePickupEnabled": true,
                "description": "Ship using FEDEX",
                "externalShippingMethod": "FEDEX",
                "id": "1200",
                "name": "John Smith",
                "price": 0,
                "shippingPromotions": [
                  {
                    "calloutMsg": "Callout Message",
                    "promotionId": "123452768sdfgh",
                    "promotionName": "Special Promotion"
                  }
                ]
              },
              "shippingStatus": "not_shipped",
              "shippingTotal": 0,
              "shippingTotalTax": 0,
              "taxTotal": 0,
              "trackingNumber": "89e980-562489-54ifsdgj"
            }
          ],
          "shippingItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "itemId": "2345245e654utjSSDFfdhh",
              "itemText": "apple-iPod-classic",
              "price": 0,
              "priceAdjustments": [
                {
                  "appliedDiscount": {
                    "amount": 0,
                    "percentage": 0,
                    "priceBookId": "string",
                    "type": "percentage"
                  },
                  "couponCode": "sadfghgjw4e56r7",
                  "createdBy": "System",
                  "creationDate": "2019-09-05T17:12:56.672Z",
                  "custom": true,
                  "itemText": "string",
                  "lastModified": "2019-09-05T17:12:56.672Z",
                  "manual": true,
                  "price": 0,
                  "priceAdjustmentId": "asdgfhg5463798453",
                  "promotionId": "100-7345",
                  "promotionLink": "Link to promotion",
                  "reasonCode": "PRICE_MATCH"
                }
              ],
              "priceAfterItemDiscount": 0,
              "shipmentId": "asghdfjghwertyu",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "STATE",
              "taxRate": 0
            }
          ],
          "shippingTotal": 0,
          "shippingTotalTax": 0,
          "sourceCode": "",
          "taxTotal": 0,
          "taxation": "gross"
        }
      ],
      "total": 1
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Return a page list of all the customer's orders. The default page size is 10. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/customers/{customerId}/orders`

Operation ID: `getCustomerOrders`. Security: ShopperToken (sfcc.shopper-myaccount.orders, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.orders, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `crossSites` (query, boolean) The flag indicating whether all sites should be searched. This flag is ignored unless a valid User / Agent is present with a trusted agent on behalf (TAOB) token. Without a TAOB token, only the customer's orders placed on the site specified by siteId are returned.
*   `from` (query, string) The start date for the date range filter (ISO 8601 format).
*   `until` (query, string) The end date for the date range filter (ISO 8601 format).
*   `status` (query, string) Filter results by status.
*   `expand` (query, string) This parameter enhances the order result with extra data. By using `expand=oms`, all orders for the current customer are loaded directly from Salesforce Order Management (SOM). The system returns the retrieved SOM order data, along with any orders not yet transferred to SOM. If your instance is not integrated with SOM, the `expand=oms` command is disregarded.  
    Allowed values: `oms`. Example: `oms`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 10.  
    Default: `10`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerOrderResult`.
    
    _Example: CustomersOrdersResult_
    
    ```
    {
      "limit": 1,
      "data": [
        {
          "adjustedMerchandizeTotalTax": 0,
          "adjustedShippingTotalTax": 0,
          "billingAddress": {
            "address1": "10 Presidential Way",
            "city": "Woburn",
            "countryCode": "US",
            "firstName": "John",
            "fullName": "John M. Smith",
            "id": "abfTEMDZOgi3JPrkHjv9IhoziM",
            "lastName": "Smith",
            "phone": "123450003",
            "postalCode": "01827",
            "salutation": "Mr.",
            "stateCode": "MA"
          },
          "bonusDiscountLineItems": [
            {
              "bonusProducts": [
                {
                  "productDescription": "Bonus Product",
                  "productId": "34984327448",
                  "productName": "Extra Fluffy Bonus Product",
                  "title": "Bonus Product"
                }
              ],
              "couponCode": "BONUS",
              "id": "qhegj345ruhrfkj",
              "maxBonusItems": 1,
              "promotionId": "basds98295jsafi"
            }
          ],
          "channelType": "storefront",
          "confirmationStatus": "not_confirmed",
          "couponItems": [
            {
              "code": "5634573",
              "couponItemId": "100-89038",
              "statusCode": "coupon_code_already_in_basket",
              "valid": true
            }
          ],
          "creationDate": "2019-09-05T17:12:56.670Z",
          "currency": "USD",
          "customerInfo": {
            "c_familyStatus": "string",
            "customerId": "abfTEMDZOgi3JPrkHjv9IhoziM",
            "customerName": "John Smith",
            "customerNo": "00010009",
            "email": "jsmith@demandware.com"
          },
          "exportStatus": "not_exported",
          "externalOrderStatus": "string",
          "giftCertificateItems": [
            {
              "amount": 0,
              "giftCertificateItemId": "901",
              "message": "Preferred Customer",
              "recipientEmail": "jsmith@demandware.com",
              "recipientName": "John Smith",
              "senderName": "Jane Smith",
              "shipmentId": "678934jsadLHY5"
            }
          ],
          "lastModified": "2019-09-05T17:12:56.670Z",
          "merchandizeTotalTax": 0,
          "orderPriceAdjustments": [
            {
              "appliedDiscount": {
                "amount": 0,
                "percentage": 0,
                "priceBookId": "asdfgh4567",
                "type": "percentage"
              },
              "couponCode": "2345-009",
              "createdBy": "System",
              "creationDate": "2019-09-05T17:12:56.670Z",
              "custom": true,
              "itemText": "string",
              "lastModified": "2019-09-05T17:12:56.670Z",
              "manual": true,
              "price": 0,
              "priceAdjustmentId": "324545673fgjghj",
              "promotionId": "1000-7654",
              "promotionLink": "link to promotion",
              "reasonCode": "PRICE_MATCH"
            }
          ],
          "orderTotal": 0,
          "paymentInstruments": [
            {
              "amount": 0,
              "authorizationStatus": {
                "code": "AUTH",
                "message": "Authorizing",
                "status": 0
              },
              "bankRoutingNumber": "string",
              "maskedGiftCertificateCode": "string",
              "paymentCard": {
                "cardType": "Visa",
                "creditCardExpired": false,
                "creditCardToken": "sadjklfajkgae",
                "expirationMonth": 12,
                "expirationYear": 2019,
                "holder": "John",
                "issueNumber": "389342643978",
                "maskedNumber": "**************53",
                "numberLastDigits": "8753",
                "validFromMonth": 4,
                "validFromYear": 2015
              },
              "paymentInstrumentId": "creditCard",
              "paymentMethodId": "credit"
            }
          ],
          "paymentStatus": "not_paid",
          "productItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusDiscountLineItemId": "string",
              "bonusProductLineItem": true,
              "bundledProductItems": [
                {
                  "quantity": 10
                }
              ],
              "gift": true,
              "giftMessage": "string",
              "inventoryId": "string",
              "itemId": "string",
              "itemText": "string",
              "optionItems": [
                {
                  "adjustedTax": 0,
                  "basePrice": 110,
                  "bonusDiscountLineItemId": "dsklgladsjkq349857",
                  "bonusProductLineItem": true,
                  "bundledProductItems": [
                    {
                      "quantity": 10
                    }
                  ],
                  "gift": true,
                  "giftMessage": "Happy Birthday",
                  "inventoryId": "258963",
                  "itemId": "apple-ipod-classic",
                  "itemText": "Apple iPod Classic",
                  "optionId": "34526hjyuGGH56",
                  "optionItems": [
                    {
                      "optionId": "sdiughsdjkfgoqtuy",
                      "optionValueId": "1564897654"
                    }
                  ],
                  "optionValueId": "string",
                  "price": 0,
                  "priceAdjustments": [
                    {
                      "appliedDiscount": {
                        "amount": 0,
                        "percentage": 0,
                        "priceBookId": "34526hjyuGGH56",
                        "type": "percentage"
                      },
                      "couponCode": "109475",
                      "createdBy": "System",
                      "creationDate": "2019-09-05T17:12:56.670Z",
                      "custom": true,
                      "itemText": "",
                      "lastModified": "2019-09-05T17:12:56.670Z",
                      "manual": true,
                      "price": 0,
                      "priceAdjustmentId": "1597563",
                      "promotionId": "963852",
                      "promotionLink": "link to promotion",
                      "reasonCode": "PRICE_MATCH"
                    }
                  ],
                  "priceAfterItemDiscount": 0,
                  "priceAfterOrderDiscount": 0,
                  "productId": "apple-ipod-classic",
                  "productListItem": {
                    "id": "2345245e654utjSSDFfdhh",
                    "priority": 0,
                    "productDetailsLink": {
                      "productDescription": "apple-ipod-classic",
                      "productId": "apple-ipod-classic",
                      "productName": "Apple iPod Classic",
                      "title": "Apple iPod Classic Silver"
                    },
                    "productList": {
                      "description": "My Product List",
                      "name": "Electronics",
                      "public": true,
                      "title": "My Electronics Wish List",
                      "type": "wish_list"
                    },
                    "public": true,
                    "purchasedQuantity": 0,
                    "quantity": 0,
                    "type": "product"
                  },
                  "productName": "Apple iPod Classic",
                  "quantity": 0,
                  "shipmentId": "12345rdsghfjh",
                  "shippingItemId": "47568ghfhjgkg",
                  "tax": 0,
                  "taxBasis": 0,
                  "taxClassId": "STATE",
                  "taxRate": 0
                }
              ],
              "price": 0,
              "priceAdjustments": [
                {
                  "appliedDiscount": {
                    "amount": 0,
                    "percentage": 0,
                    "priceBookId": "string",
                    "type": "percentage"
                  },
                  "couponCode": "sadfghgjw4e56r7",
                  "createdBy": "System",
                  "creationDate": "2019-09-05T17:12:56.672Z",
                  "custom": true,
                  "itemText": "string",
                  "lastModified": "2019-09-05T17:12:56.672Z",
                  "manual": true,
                  "price": 0,
                  "priceAdjustmentId": "asdgfhg5463798453",
                  "promotionId": "100-7345",
                  "promotionLink": "Link to promotion",
                  "reasonCode": "PRICE_MATCH"
                }
              ],
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "string",
              "productListItem": {
                "id": "string",
                "priority": 0,
                "productDetailsLink": {
                  "productDescription": "apple-ipod-classic",
                  "productId": "apple-ipod-classic",
                  "productName": "Apple iPod Classic",
                  "title": "Apple iPod Classic Silver"
                },
                "productList": {
                  "description": "My Product List",
                  "name": "Electronics",
                  "public": true,
                  "title": "My Electronics Wish List",
                  "type": "wish_list"
                },
                "public": true,
                "purchasedQuantity": 0,
                "quantity": 0,
                "type": "product"
              },
              "productName": "Apple iPod Classic",
              "quantity": 0,
              "shipmentId": "12345rdsghfjh",
              "shippingItemId": "47568ghfhjgkg",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "STATE",
              "taxRate": 0
            }
          ],
          "productSubTotal": 0,
          "productTotal": 0,
          "shipments": [
            {
              "adjustedMerchandizeTotalTax": 0,
              "adjustedShippingTotalTax": 0,
              "gift": true,
              "giftMessage": "Happy Birthday",
              "merchandizeTotalTax": 0,
              "productSubTotal": 0,
              "productTotal": 0,
              "shipmentId": "1200",
              "shipmentNo": "3",
              "shipmentTotal": 0,
              "shippingAddress": {
                "address1": "10 Presidential Way",
                "city": "string",
                "countryCode": "US",
                "firstName": "John",
                "fullName": "John M. Smith",
                "id": "abfTWMDZOgi3JPzkHjv9IhmziI",
                "lastName": "Smith",
                "phone": "123450003",
                "postalCode": "01827",
                "salutation": "Mr.",
                "stateCode": "MA"
              },
              "shippingMethod": {
                "c_storePickupEnabled": true,
                "description": "Ship using FEDEX",
                "externalShippingMethod": "FEDEX",
                "id": "1200",
                "name": "John Smith",
                "price": 0,
                "shippingPromotions": [
                  {
                    "calloutMsg": "Callout Message",
                    "link": "link to shipping promotions",
                    "promotionId": "123452768sdfgh",
                    "promotionName": "Special Promotion"
                  }
                ]
              },
              "shippingStatus": "not_shipped",
              "shippingTotal": 0,
              "shippingTotalTax": 0,
              "taxTotal": 0,
              "trackingNumber": "89e980-562489-54ifsdgj"
            }
          ],
          "shippingItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "itemId": "2345245e654utjSSDFfdhh",
              "itemText": "apple-iPod-classic",
              "price": 0,
              "priceAdjustments": [
                {
                  "appliedDiscount": {
                    "amount": 0,
                    "percentage": 0,
                    "priceBookId": "string",
                    "type": "percentage"
                  },
                  "couponCode": "sadfghgjw4e56r7",
                  "createdBy": "System",
                  "creationDate": "2019-09-05T17:12:56.672Z",
                  "custom": true,
                  "itemText": "string",
                  "lastModified": "2019-09-05T17:12:56.672Z",
                  "manual": true,
                  "price": 0,
                  "priceAdjustmentId": "asdgfhg5463798453",
                  "promotionId": "100-7345",
                  "promotionLink": "Link to promotion",
                  "reasonCode": "PRICE_MATCH"
                }
              ],
              "priceAfterItemDiscount": 0,
              "shipmentId": "asghdfjghwertyu",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "STATE",
              "taxRate": 0
            }
          ],
          "shippingStatus": "not_shipped",
          "shippingTotal": 0,
          "shippingTotalTax": 0,
          "sourceCode": "",
          "status": "created",
          "taxTotal": 0,
          "taxation": "gross"
        }
      ],
      "offset": 0,
      "total": 1
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### PUT Update a customer's password. This endpoint only accepts a registered customer ShopperToken (JWT).

`PUT /organizations/{organizationId}/customers/{customerId}/password`

Operation ID: `updateCustomerPassword`. Security: RegisteredShopperToken (sfcc.shopper-customers.login, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `PasswordChangeRequest`.

_Example: UpdatePasswordBody_

```
{
  "currentPassword": "01dpass",
  "password": "newpass"
}
```

#### Responses

*   **204** No content
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### POST Add a payment instrument to the customer information. This endpoint only accepts a registered customer ShopperToken (JWT).

`POST /organizations/{organizationId}/customers/{customerId}/payment-instruments`

Operation ID: `createCustomerPaymentInstrument`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.paymentinstruments.rw, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerPaymentInstrumentRequest`.

_Example: CustomerPaymentInstrumentBody_

```
{
  "paymentCard": {
    "expirationYear": 2027,
    "expirationMonth": 7,
    "validFromMonth": 8,
    "validFromYear": 2007,
    "issueNumber": "i117",
    "number": "1234567",
    "holder": "John Smith",
    "cardType": "MasterCard"
  },
  "giftCertificateCode": "gift_code7",
  "paymentMethodId": "OCAPI_Payment_Simple",
  "bankRoutingNumber": "bankrouting3776",
  "default": true
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerPaymentInstrument`.
    
    _Example: getCustomerPaymentInstrumentSuccess_
    
    ```
    {
      "bankRoutingNumber": "bankrouting3776",
      "paymentCard": {
        "cardType": "MasterCard",
        "creditCardExpired": false,
        "expirationMonth": 7,
        "expirationYear": 2027,
        "holder": "John Smith",
        "issueNumber": "i117",
        "maskedNumber": "***4567",
        "numberLastDigits": "4567",
        "validFromMonth": 8,
        "validFromYear": 2007
      },
      "paymentMethodId": "OCAPI_Payment_Simple",
      "paymentInstrumentId": "cdOLciWbOsYl6aaadkwcsx9xHH",
      "default": false
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Retrieve a customer's payment instrument by its ID. This endpoint only accepts a registered customer ShopperToken (JWT).

`GET /organizations/{organizationId}/customers/{customerId}/payment-instruments/{paymentInstrumentId}`

Operation ID: `getCustomerPaymentInstrument`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.paymentinstruments, sfcc.shopper-myaccount.paymentinstruments.rw, sfcc.shopper-standard).

#### Parameters

*   `paymentInstrumentId` (path, string, required) The ID of the payment instrument to be retrievedCustomer.  
    Minimum length: 1.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerPaymentInstrument`.
    
    _Example getCustomerPaymentInstrumentSuccess: same as POST /organizations/{organizationId}/customers/{customerId}/payment-instruments 200 response._
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### DELETE Delete a customer's payment instrument. This endpoint only accepts a registered customer ShopperToken (JWT).

`DELETE /organizations/{organizationId}/customers/{customerId}/payment-instruments/{paymentInstrumentId}`

Operation ID: `deleteCustomerPaymentInstrument`. Security: ShopperToken (sfcc.shopper-myaccount.paymentinstruments.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.paymentinstruments.rw, sfcc.shopper-standard).

#### Parameters

*   `paymentInstrumentId` (path, string, required) The ID of the payment instrument to be retrievedCustomer.  
    Minimum length: 1.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **204** No content
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### PATCH Update a customer's payment instrument. This endpoint only accepts a registered customer ShopperToken (JWT).

`PATCH /organizations/{organizationId}/customers/{customerId}/payment-instruments/{paymentInstrumentId}`

Operation ID: `updateCustomerPaymentInstrument`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.paymentinstruments.rw, sfcc.shopper-standard).

#### Parameters

*   `paymentInstrumentId` (path, string, required) The ID of the payment instrument to be retrievedCustomer.  
    Minimum length: 1.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerPaymentInstrumentUpdateRequest`.

_Example: UpdateCustomerPaymentInstrumentBody_

```
{
  "default": false,
  "paymentCard": {
    "expirationYear": 2028,
    "expirationMonth": 12
  }
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerPaymentInstrument`.
    
    _Example: updateCustomerPaymentInstrumentSuccess_
    
    ```
    {
      "paymentCard": {
        "cardType": "MasterCard",
        "creditCardExpired": false,
        "expirationMonth": 12,
        "expirationYear": 2028,
        "holder": "John Smith",
        "issueNumber": "i117",
        "maskedNumber": "***4567",
        "numberLastDigits": "4567",
        "validFromMonth": 8,
        "validFromYear": 2007
      },
      "paymentMethodId": "OCAPI_Payment_Simple",
      "paymentInstrumentId": "cdOLciWbOsYl6aaadkwcsx9xHH",
      "default": false
    }
    ```
    
*   **400** Either the CustomerId URL parameter does not match the verified customer represented by the JWT token, or the request contains unsupported fields for update.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: invalidCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "CustomerId URL parameter does not match the verified customer represented by the JWT token."
    }
    ```
    
    _Example: updatePaymentInstrumentUnsupportedFields400_
    
    ```
    {
      "title": "Unsupported Fields",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-fields",
      "detail": "Unsupported fields in the request for updates."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### DELETE Delete a customer's payment method reference. This endpoint only accepts a registered customer ShopperToken (JWT).

`DELETE /organizations/{organizationId}/customers/{customerId}/payment-method-references/{paymentMethodReferenceId}`

Operation ID: `deleteCustomerPaymentMethodReference`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.paymentinstruments.rw).

Deletes a specific payment method reference from a customer's account using the payment method reference ID and account ID. This endpoint requires Salesforce Payments integration.

#### Parameters

*   `paymentMethodReferenceId` (path, string, required) The ID of the payment method reference to delete.  
    Minimum length: 1. Maximum length: 256. Example: `pm_12345678`.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `accountId` (query, string, required) The account ID used to scope payment method references.  
    Minimum length: 1. Maximum length: 256. Example: `acc_987654321`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **204** No content

### POST Set up a new payment method reference for a customer. This endpoint only accepts a registered customer ShopperToken (JWT).

`POST /organizations/{organizationId}/customers/{customerId}/payment-method-references/actions/setup`

Operation ID: `setupCustomerPaymentMethodReference`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.paymentinstruments.rw).

Initiates the setup of a new payment method reference for a customer. Requires Salesforce Payments. Stripe does not require gatewayProperties. Adyen requires gatewayProperties.adyen.paymentMethod; missing that field returns 400.

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `zoneId` (query, string, required) The zone identifier for the payment configuration.
    
    The unique identifier for a Payments zone.
    
      
    Minimum length: 1. Maximum length: 100. Example: `Amer-Zone`.
    
    _Example: ZoneId_
    
    ```
    Amer-Zone
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `PaymentMethodReferenceSetupRequest`.

_Example: PaymentMethodReferenceSetupBodyStripe_ Setup Payment Method Reference (Stripe)

```
{
  "paymentMethodType": "card",
  "gatewayProperties": {
    "stripe": {
      "usage": "on_session"
    }
  }
}
```

_Example: PaymentMethodReferenceSetupBodyAdyen_ Setup Payment Method Reference (Adyen)

```
{
  "gatewayProperties": {
    "adyen": {
      "paymentMethod": {
        "type": "scheme",
        "encryptedCardNumber": "test_4111111111111111",
        "encryptedExpiryMonth": "test_03",
        "encryptedExpiryYear": "test_2030",
        "encryptedSecurityCode": "test_737"
      }
    }
  }
}
```

#### Responses

*   **200** Payment method reference setup initiated successfully.
    
    Media type: `application/json`. Schema: `PaymentMethodReferenceSetupResponse`.
    
    _Example: setupPaymentMethodReferenceSuccess_ Successful payment method reference setup (Stripe)
    
    ```
    {
      "paymentMethodReferenceSetupId": "seti_1Mm8s8LkdIwHu7ix0OXBfTRG",
      "gatewayProperties": {
        "stripe": {
          "clientSecret": "seti_1Mm8s8LkdIwHu7ix0OXBfTRG_secret_NXDICkPqPeiBTAFYUKGBMVdE7"
        }
      }
    }
    ```
    
*   **400** The request is invalid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: invalidPaymentMethodReferenceSetup400_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "The string length constraint was violated by 'paymentMethodType'. The expected maximum length is '256'.",
      "parameter": "paymentMethodType",
      "expected": "256"
    }
    ```
    
    _Example: invalidPaymentMethodReferenceSetupAdyen400_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "The null value constraint for parameter 'gatewayProperties.adyen.paymentMethod' was violated. Null isn't allowed. Please provide a value.",
      "parameter": "gatewayProperties.adyen.paymentMethod"
    }
    ```
    
    _Example: invalidPaymentZone400_
    
    ```
    {
      "title": "Invalid Payment Zone",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-payment-zone",
      "detail": "The provided payment zone ID 'non_existent_zone' isn't a valid Salesforce Payments zone ID.",
      "zoneId": "non_existent_zone"
    }
    ```
    
*   **401** Authentication failed or the authenticated shopper is not authorized to access the requested customer.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: unauthorizedCustomer401_
    
    ```
    {
      "title": "Unauthorized",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "detail": "Invalid token provided."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: customerNotFound404_
    
    ```
    {
      "title": "Customer Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/customer-not-found",
      "detail": "No customer with ID 'abfTWMDZOgi3JPzkHjv9IhmziI' could be found.",
      "customerId": "abfTWMDZOgi3JPzkHjv9IhmziI"
    }
    ```
    
*   **412** Salesforce Payments is not enabled (instance feature toggles) or is not configured for the requested site (org payments config, site, or zone assignment).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: salesforcePaymentsEnabledPreconditionFailed412_
    
    ```
    {
      "title": "Salesforce Payments Enabled Precondition Failed",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/salesforce-payments-enabled-precondition-failed",
      "detail": "Salesforce Payments isn't enabled."
    }
    ```
    
    _Example: salesforcePaymentsConfiguredPreconditionFailed412_
    
    ```
    {
      "title": "Salesforce Payments Configured Precondition Failed",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/salesforce-payments-configured-precondition-failed",
      "detail": "Salesforce Payments isn't configured for this site."
    }
    ```
    

### POST Complete payment method reference setup for a customer. This endpoint only accepts a registered customer ShopperToken (JWT).

`POST /organizations/{organizationId}/customers/{customerId}/payment-method-references/actions/complete`

Operation ID: `completeCustomerPaymentMethodReferenceSetup`. Security: RegisteredShopperToken (sfcc.shopper-myaccount.paymentinstruments.rw).

Completes payment method reference setup after provider success.

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `zoneId` (query, string, required) The zone identifier for the payment configuration.
    
    The unique identifier for a Payments zone.
    
      
    Minimum length: 1. Maximum length: 100. Example: `Amer-Zone`.
    
    _Example: ZoneId_
    
    ```
    Amer-Zone
    ```
    
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `PaymentMethodReferenceCompleteRequest`.

_Example: PaymentMethodReferenceCompleteBody_ Complete Payment Method Reference setup

```
{
  "paymentMethodReferenceSetupId": "seti_1Mm8s8LkdIwHu7ix0OXBfTRG"
}
```

#### Responses

*   **204** No content
*   **400** The request is invalid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: invalidPaymentMethodReferenceComplete400_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "The null value constraint for parameter 'paymentMethodReferenceSetupId' was violated. Null isn't allowed. Please provide a value.",
      "parameter": "paymentMethodReferenceSetupId"
    }
    ```
    
*   **401** Authentication failed or the authenticated shopper is not authorized to access the requested customer.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: unauthorizedCustomer401_
    
    ```
    {
      "title": "Unauthorized",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "detail": "Invalid token provided."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example customerNotFound404: same as POST /organizations/{organizationId}/customers/{customerId}/payment-method-references/actions/setup 404 response._
    
    _Example: paymentMethodReferenceNotFound404_
    
    ```
    {
      "title": "Payment Method Reference Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/payment-method-reference-not-found",
      "detail": "No payment method reference with ID 'pm_nonexistent' could be found.",
      "paymentMethodReferenceId": "pm_nonexistent"
    }
    ```
    
*   **412** Salesforce Payments is not enabled (instance feature toggles) or is not configured for the requested site (org payments config, site, or zone assignment).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example salesforcePaymentsEnabledPreconditionFailed412: same as POST /organizations/{organizationId}/customers/{customerId}/payment-method-references/actions/setup 412 response._
    
    _Example salesforcePaymentsConfiguredPreconditionFailed412: same as POST /organizations/{organizationId}/customers/{customerId}/payment-method-references/actions/setup 412 response._
    

### GET Return all customer product lists. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/customers/{customerId}/product-lists`

Operation ID: `getCustomerProductLists`. Security: ShopperToken (sfcc.shopper-myaccount.productlists, sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists, sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerProductListResult`.
    
    _Example: customerProductListResult_
    
    ```
    {
      "limit": 1,
      "data": [
        {
          "coRegistrant": {
            "email": "janedoe@example.com",
            "firstName": "Jane",
            "lastName": "Doe",
            "role": "Bride"
          },
          "creationDate": "2019-10-18T22:06:28.965Z",
          "currentShippingAddressInfo": {
            "addressId": "home_address",
            "title": "home_address, John Murphy, Burlington"
          },
          "customerProductListItems": [
            {
              "id": "30f35c187ea255ccb633c3ba11",
              "priority": 4,
              "productId": "SimpleProduct",
              "public": false,
              "purchasedQuantity": 0,
              "quantity": 2,
              "type": "product"
            }
          ],
          "postEventShippingAddressInfo": {
            "addressId": "home_address",
            "title": "home_address, John Murphy, Burlington"
          },
          "productListShippingAddress": {
            "addressId": "home_address",
            "city": "Burlington",
            "firstName": "John",
            "lastName": "Murphy"
          },
          "name": "OurProductList",
          "registrant": {
            "email": "johndoe@example.com",
            "firstName": "John",
            "lastName": "Doe",
            "role": "Groom"
          },
          "lastModified": "2019-10-18T22:06:28.971Z",
          "description": "a productlist",
          "event": {
            "city": "any city",
            "country": "USA",
            "type": "product_list_event"
          },
          "id": "8b04014a9d6e5dbae542004824",
          "public": false,
          "type": "wish_list"
        }
      ],
      "total": 1
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### POST Create a customer product list. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`POST /organizations/{organizationId}/customers/{customerId}/product-lists`

Operation ID: `createCustomerProductList`. Security: ShopperToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

#### Parameters

*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerProductList`.

_Example: PostCustomerProductListBody_

```
{
  "coRegistrant": {
    "email": "janedoe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "role": "Bride"
  },
  "creationDate": "2019-10-18T22:06:28.965Z",
  "description": "our productlist",
  "event": {
    "city": "Washington",
    "country": "US",
    "date": "2019-09-05T17:12:56.670Z",
    "state": "DC",
    "type": "Wedding"
  },
  "id": "bcedkiWbxCM2MaaadkRhB2IBzM",
  "lastModified": "2019-10-18T22:06:28.971Z",
  "name": "OurProductList",
  "public": true,
  "registrant": {
    "email": "johndoe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "Groom"
  },
  "type": "wish_list"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerProductList`.
    
    _Example: customerProductList_
    
    ```
    {
      "coRegistrant": {
        "email": "janedoe@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "role": "Bride"
      },
      "creationDate": "2019-10-18T22:06:28.965Z",
      "currentShippingAddressInfo": {
        "addressId": "home_address",
        "title": "home_address, John Murphy, Burlington"
      },
      "description": "our productlist",
      "event": {
        "city": "Washington",
        "country": "US",
        "date": "2019-09-05T17:12:56.670Z",
        "state": "DC",
        "type": "Wedding"
      },
      "id": "bcedkiWbxCM2MaaadkRhB2IBzM",
      "lastModified": "2019-10-18T22:06:28.971Z",
      "name": "OurProductList",
      "postEventShippingAddressInfo": {
        "addressId": "home_address",
        "title": "home_address, John Murphy, Burlington"
      },
      "productListShippingAddress": {
        "addressId": "home_address",
        "city": "Burlington",
        "firstName": "John",
        "lastName": "Murphy"
      },
      "public": false,
      "registrant": {
        "email": "johndoe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "role": "Groom"
      },
      "shippingAddressInfo": {
        "addressId": "me",
        "title": "me, John Doe, Woburn"
      },
      "type": "wish_list"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Return a customer product list for the given customer and the items in the list. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/customers/{customerId}/product-lists/{listId}`

Operation ID: `getCustomerProductList`. Security: ShopperToken (sfcc.shopper-myaccount.productlists, sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists, sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

#### Parameters

*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerProductList`.
    
    _Example: getCustomerProductListByListId_
    
    ```
    {
      "coRegistrant": {
        "email": "janedoe@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "role": "Bride"
      },
      "creationDate": "2019-10-18T22:06:28.965Z",
      "currentShippingAddressInfo": {
        "addressId": "home_address",
        "title": "home_address, John Murphy, Burlington"
      },
      "customerProductListItems": [
        {
          "id": "30f35c187ea255ccb633c3ba11",
          "priority": 4,
          "productId": "SimpleProduct",
          "public": false,
          "purchasedQuantity": 0,
          "quantity": 2,
          "type": "product"
        }
      ],
      "description": "our productlist",
      "event": {
        "city": "Washington",
        "country": "US",
        "date": "2019-09-05T17:12:56.670Z",
        "state": "DC",
        "type": "Wedding"
      },
      "id": "bcedkiWbxCM2MaaadkRhB2IBzM",
      "lastModified": "2019-10-18T22:06:28.971Z",
      "name": "OurProductList",
      "public": true,
      "registrant": {
        "email": "johndoe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "role": "Groom"
      },
      "type": "wish_list"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### DELETE deleteCustomerProductList

`DELETE /organizations/{organizationId}/customers/{customerId}/product-lists/{listId}`

Operation ID: `deleteCustomerProductList`. Security: ShopperToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

Delete a customer product list. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

#### Parameters

*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **204** No content
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### PATCH Change a product list. Changeable properties include name, description, and if the list is public. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`PATCH /organizations/{organizationId}/customers/{customerId}/product-lists/{listId}`

Operation ID: `updateCustomerProductList`. Security: ShopperToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

#### Parameters

*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerProductList`.

_Example: UpdateCustomerProductListByListIdBody_

```
{
  "description": "Description"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerProductList`.
    
    _Example: getCustomerProductListByListId_
    
    ```
    {
      "coRegistrant": {
        "email": "janedoe@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "role": "Bride"
      },
      "creationDate": "2019-10-18T22:06:28.965Z",
      "currentShippingAddressInfo": {
        "addressId": "home_address",
        "title": "home_address, John Murphy, Burlington"
      },
      "customerProductListItems": [
        {
          "id": "30f35c187ea255ccb633c3ba11",
          "priority": 4,
          "productId": "SimpleProduct",
          "public": false,
          "purchasedQuantity": 0,
          "quantity": 2,
          "type": "product"
        }
      ],
      "description": "Description",
      "event": {
        "city": "Washington",
        "country": "US",
        "date": "2019-09-05T17:12:56.670Z",
        "state": "DC",
        "type": "Wedding"
      },
      "id": "bcedkiWbxCM2MaaadkRhB2IBzM",
      "lastModified": "2019-10-18T22:06:28.971Z",
      "name": "OurProductList",
      "public": true,
      "registrant": {
        "email": "johndoe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "role": "Groom"
      },
      "type": "wish_list"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### POST Add an item to the customer's product list.

`POST /organizations/{organizationId}/customers/{customerId}/product-lists/{listId}/items`

Operation ID: `createCustomerProductListItem`. Security: ShopperToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

Considered values from the request body are:

*   `type` → The item type to be added to the customer's product. This value is required and must be a valid type. list.
*   `priority` → The priority of the item to be added to the customer's product list.
*   `public` → The flag that determines whether the item to be added to the customer's product list is public.
*   `product_id` → The ID (SKU) of the product related to the item to be added to the customer's product list. Required when item type is `product`, and must be a valid product ID and only used for product item type. Otherwise, a `ProductListProductIdMissingException` or `ProductListProductNotFoundException` is thrown.
*   `quantity` → Only used for product item type. This is the quantity of the item to be added to the customer's product list.

You can also use a custom property of the form `c_<CUSTOM_NAME>`. The custom property must correspond to a custom attribute (`<CUSTOM_NAME>`) that is defined for `ProductListItem`. The value of this property must be valid for the type of custom attribute defined for `ProductListItem`.

#### Parameters

*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerProductListItem`.

_Example: UpdateCustomerProductListItemBody_

```
{
  "id": "1d447daa4d25805fd682bd4ce1",
  "priority": 4,
  "productId": "RedDress1",
  "public": true,
  "purchasedQuantity": 0,
  "quantity": 2,
  "type": "product"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerProductListItem`.
    
    _Example: updateCustomerProductListItemSuccess_
    
    ```
    {
      "id": "1d447daa4d25805fd682bd4ce1",
      "priority": 4,
      "productId": "RedDress1",
      "public": true,
      "purchasedQuantity": 0,
      "quantity": 2,
      "type": "product"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Return an item of a customer product list and the actual product details such as image, availability, and price. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/customers/{customerId}/product-lists/{listId}/items/{itemId}`

Operation ID: `getCustomerProductListItem`. Security: ShopperToken (sfcc.shopper-myaccount.productlists, sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists, sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

#### Parameters

*   `itemId` (path, string, required) The ID of the item.  
    Minimum length: 1.
*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerProductListItem`.
    
    _Example: getCustomerProductListItemSuccess_
    
    ```
    {
      "id": "1d447daa4d25805fd682bd4ce1",
      "priority": 4,
      "productId": "RedDress1",
      "product": {
        "id": "RedDress1",
        "imageGroups": [
          {
            "images": [
              {
                "alt": "ALT master detail",
                "link": "https://example.com/foo/bar/master_detail.jpg",
                "title": "TITLE master detail"
              }
            ],
            "viewType": "detail"
          },
          {
            "images": [
              {
                "alt": "ALT master swatch",
                "link": "https://example.com/foo/bar/master_swatch.jpg",
                "title": "TITLE master swatch"
              }
            ],
            "viewType": "swatch"
          },
          {
            "images": [
              {
                "alt": "ALT master thumbnail",
                "link": "https://example.com/foo/bar/master_thumbnail.jpg",
                "title": "TITLE master thumbnail"
              }
            ],
            "viewType": "thumbnail"
          }
        ],
        "inventories": [
          {
            "ats": 0,
            "backorderable": false,
            "id": "RedDress1Inventory",
            "orderable": false,
            "preorderable": false,
            "stockLevel": 0
          }
        ],
        "minOrderQuantity": 1,
        "price": 99.99,
        "stepQuantity": 1
      },
      "public": true,
      "purchasedQuantity": 0,
      "quantity": 2,
      "type": "product"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### DELETE Remove an item from a customer product list. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`DELETE /organizations/{organizationId}/customers/{customerId}/product-lists/{listId}/items/{itemId}`

Operation ID: `deleteCustomerProductListItem`. Security: ShopperToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

#### Parameters

*   `itemId` (path, string, required) The ID of the item.  
    Minimum length: 1.
*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **204** No content
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### PATCH Update an item in a customer's product list.

`PATCH /organizations/{organizationId}/customers/{customerId}/product-lists/{listId}/items/{itemId}`

Operation ID: `updateCustomerProductListItem`. Security: ShopperToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-myaccount.productlists.rw, sfcc.shopper-standard).

This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken. Considered values from the request body are:

priority: The priority of the customer's product list item. public: The flag that indicates if the customer's product list item is public. quantity: The quantity of the customer's product list item. Onlyl used for product item type. custom properties in the form c\_<CUSTOM\_NAME>: The custom property must correspond to a custom attribute (<CUSTOM\_NAME>) defined for ProductListItem. The value of this property must be valid for the type of custom attribute defined for ProductListItem.

#### Parameters

*   `itemId` (path, string, required) The ID of the item.  
    Minimum length: 1.
*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `customerId` (path, string, required) The customer ID.  
    Minimum length: 1.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `CustomerProductListItem`.

_Example: CustomerProductListItemBody_

```
{
  "productId": "RedDress1",
  "id": "1",
  "purchasedQuantity": 0,
  "priority": 3,
  "quantity": 4,
  "public": false,
  "type": "product"
}
```

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `CustomerProductListItem`.
    
    _Example: updateCustomerProductListItemSuccess_
    
    ```
    {
      "id": "1d447daa4d25805fd682bd4ce1",
      "priority": 4,
      "productId": "RedDress1",
      "public": true,
      "purchasedQuantity": 0,
      "quantity": 2,
      "type": "product"
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Retrieve all public product lists as defined by the given search term, for example: email OR first name and last name). This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/product-lists`

Operation ID: `getPublicProductListsBySearchTerm`. Security: ShopperToken (sfcc.shopper-productlists, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-productlists, sfcc.shopper-standard).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `email` (query, string) The email address of the customer the product lists belong to.
*   `firstName` (query, string) The first name of the customer the product lists belong to. This field is case sensitive and must be an exact match.
*   `lastName` (query, string) The last name of the customer the product lists belong to. This field is case sensitive and must be an exact match.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `PublicProductListResult`.
    
    _Example: productListsResultExample_
    
    ```
    {
      "limit": 3,
      "data": [
        {
          "description": "our productlist",
          "id": "f4682729817ee215acd3a1a8b4",
          "name": "OurProductList",
          "title": "OurProductList",
          "type": "wish_list"
        },
        {
          "description": "something",
          "id": "b985bea3aaae7702c0b692c65c",
          "name": "OurProductList",
          "title": "OurProductList",
          "type": "wish_list"
        },
        {
          "description": "our productlist",
          "id": "95aa60b8c681ad5431cb4c5bfa",
          "name": "OurProductList",
          "title": "OurProductList",
          "type": "wish_list"
        }
      ],
      "total": 3
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **401** Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, which is not relevant when using OAuth, or indicates that the provided new address name is already in use for the customer.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getPublicProductListsBySearchTerm401_
    
    ```
    {
      "title": "Invalid Access Token",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token",
      "detail": "The request is unauthorized, the access token is invalid.",
      "accessToken": "iI6IjEiLCJhbGciOiJIUzI1NiIsInR5cCI6Ik"
    }
    ```
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Retrieve a public product list by ID and the items under that product list. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/product-lists/{listId}`

Operation ID: `getPublicProductList`. Security: ShopperToken (sfcc.shopper-productlists, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-productlists, sfcc.shopper-standard).

#### Parameters

*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `PublicProductList`.
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **401** Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, which is not relevant when using OAuth, or indicates that the provided new address name is already in use for the customer.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getPublicProductListsBySearchTerm401: same as GET /organizations/{organizationId}/product-lists 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

### GET Retrieve all items of a public product list.

`GET /organizations/{organizationId}/product-lists/{listId}/items`

Operation ID: `getPublicProductListItems`. Security: ShopperToken (sfcc.shopper-productlists, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-productlists, sfcc.shopper-standard).

The possible expansions are product, images, and availability. For images and availability, the product must be expanded as well. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

#### Parameters

*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `expand` (query, array of string, style: form, explode: false) Expand product details. Valid values are 'product', 'images', 'availability'. For images and availability, the product must also be expanded.  
    Items: Allowed values: `product`, `images`, `availability`.
    
    _Example_
    
    ```
    [
      "product",
      "images",
      "availability"
    ]
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `PublicProductListItemResult`.
    
    _Example: publicProductListItemsResult_
    
    ```
    {
      "data": [
        {
          "id": "item-1",
          "priority": 1,
          "type": "product",
          "product": {
            "id": "apple-ipod-classic",
            "name": "Apple iPod Classic",
            "currency": "USD",
            "price": 199.99,
            "imageGroups": [
              {
                "images": [
                  {
                    "alt": "ALT master detail",
                    "link": "https://example.com/foo/bar/master_detail.jpg",
                    "title": "TITLE master detail"
                  }
                ],
                "viewType": "large"
              }
            ]
          }
        },
        {
          "id": "item-2",
          "priority": 2,
          "type": "product",
          "product": {
            "id": "sony-headphones",
            "name": "Sony Wireless Headphones",
            "currency": "USD",
            "price": 149.99
          }
        }
      ],
      "limit": 2,
      "total": 25
    }
    ```
    
*   **400** Invalid request parameters
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getPublicProductListItems400_
    
    ```
    {
      "title": "Invalid expand parameter",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-expand-parameter",
      "detail": "An invalid expand parameter 'wishList' was found.",
      "param": "wishList"
    }
    ```
    
*   **404** The specified product list was not found or is not public.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getPublicProductListItems404_
    
    ```
    {
      "title": "Product List Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-list-not-found",
      "detail": "A product list with ID 'my-wishlist' couldn't be found.",
      "productListId": "my-wishlist"
    }
    ```
    

### GET Retrieve an item from a public product list and the actual product details such as product, image, availability, and price. This endpoint accepts a registered customer ShopperToken (JWT) or a guest customer ShopperToken.

`GET /organizations/{organizationId}/product-lists/{listId}/items/{itemId}`

Operation ID: `getProductListItem`. Security: ShopperToken (sfcc.shopper-productlists, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-productlists, sfcc.shopper-standard).

#### Parameters

*   `itemId` (path, string, required) The ID of the item.  
    Minimum length: 1.
*   `listId` (path, string, required) The ID of the list.  
    Minimum length: 1. Maximum length: 28.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `PublicProductListItem`.
    
    _Example: getCustomerProductListItemSuccess_
    
    ```
    {
      "id": "023513f915fad06573f330fb0d",
      "priority": 0,
      "product": {
        "id": "RedDress1",
        "imageGroups": [
          {
            "images": [
              {
                "alt": "ALT master detail",
                "link": "https://example.com/foo/bar/master_detail.jpg",
                "title": "TITLE master detail"
              }
            ],
            "viewType": "detail"
          },
          {
            "images": [
              {
                "alt": "ALT master swatch",
                "link": "https://example.com/foo/bar/master_swatch.jpg",
                "title": "TITLE master swatch"
              }
            ],
            "viewType": "swatch"
          },
          {
            "images": [
              {
                "alt": "ALT master thumbnail",
                "link": "https://example.com/foo/bar/master_thumbnail.jpg",
                "title": "TITLE master thumbnail"
              }
            ],
            "viewType": "thumbnail"
          }
        ],
        "inventories": [
          {
            "ats": 0,
            "backorderable": false,
            "id": "RedDress1Inventory",
            "orderable": false,
            "preorderable": false,
            "stockLevel": 0
          }
        ],
        "minOrderQuantity": 1,
        "price": 99.99,
        "stepQuantity": 1
      },
      "type": "product"
    }
    ```
    
*   **400** CustomerId URL parameter does not match the verified customer represented by the JWT token.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: registerCustomer400_
    
    ```
    {
      "title": "Invalid Customer",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-customer",
      "detail": "The customer is invalid."
    }
    ```
    
*   **401** Indicates that the customerId URL parameter does not match the verified customer represented by the JWT token, which is not relevant when using OAuth, or indicates that the provided new address name is already in use for the customer.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getPublicProductListsBySearchTerm401: same as GET /organizations/{organizationId}/product-lists 401 response._
    
*   **404** Requested resource not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example getCustomer404: same as GET /organizations/{organizationId}/customers/{customerId} 404 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### CustomerRegistration

Document representing the registration information for a customer.

*   `customer` (_object_, required) The customer registration information. The mandatory properties for registration are login, last name and email.
    
    Includes all fields of `Customer`.
    
    _Example_
    
    ```
    {
      "email": "jsmith@test.com",
      "last_name": "Smith",
      "login": "jsmith"
    }
    ```
    
*   `password` (_string_, required) The login password  
    Example: `Abcd!1234`.

### Customer

Person or entity who shops on Commerce Cloud storefronts by creating a shopper account in Commerce Cloud.

*   `addresses` (_array of CustomerAddress_) The customer's addresses.
*   `authType` (_string_) The customer's authorization type (indicates whether the customer is a guest or a registered customer).  
    Allowed values: `guest`, `registered`. Example: `registered`.
*   `birthday` (_string (date)_) The customer's birthday.
*   `companyName` (_string_) The customer's company name.  
    Maximum length: 256. Example: `Acme`.
*   `crmContactId` (_string_) The customer's core contact ID.  
    Maximum length: 18. Example: `003xx000004WhKe`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `currentPassword` (_string_) The shopper's current password. This is only used when attempting to update a shopper's `loginId` in a PATCH call. This value is never returned in any response for security reasons, but is validated and must match shopper's existing password in order to update `loginId`. Otherwise, an HTTP 400 statusCode is returned and the `loginId` is not updated. This field and functionality is available with B2C Commerce version 24.7.
*   `customerId` (_string_) The customer's number (ID). Both registered and guest customers have an customer ID.  
    Maximum length: 28. Example: `dfuisydifu2342usyf`.
*   `customerNo` (_string_) The customer's number (ID). Only a registered customer has a customer number.  
    Maximum length: 100. Example: `D0000123`.
*   `email` (_string_) The customer's email address.  
    Maximum length: 256. Example: `johnsmith@email.com`.
*   `emailVerified` (_boolean_, read-only) Indicates whether the customer's email address has been verified. Only included for customers who registered after the "Enable Email Verification" site preference under "Storefront Login Preferences" was enabled. This is a read-only field. If included in a PATCH or Register customer request, it's ignored. This field is available with B2C Commerce version 26.6.  
    Example: `true`.
*   `enabled` (_boolean_) A flag indicating whether this customer is enabled and can log in.  
    Example: `true`.
*   `fax` (_string_) The customer's fax number. The length is restricted to 32 characters.  
    Maximum length: 32. Example: `555-555-5555`.
*   `firstName` (_string_) The customer's first name.  
    Maximum length: 256. Example: `John`.
*   `gender` (_integer (int32)_) The customer's gender.  
    Example: `1`.
*   `hasPassword` (_boolean_, read-only) Indicates whether the customer has a password set. A value of `false` means the customer was created via another method (for example, social login or passwordless flow). This is a read-only field. If included in a PATCH or Register customer request, it's ignored. This field is available with B2C Commerce version 26.6.  
    Example: `true`.
*   `hashedLogin` (_string_) Represents the read-only hashed value for the `loginId` used for Einstein events. This field is available with B2C Commerce version 24.9.  
    Example: `123927deac310a3dae382897d9e458bd92ef1d4ea5cdd327a0fcffd8426dfbb5`.
*   `jobTitle` (_string_) The customer's job title.  
    Maximum length: 256. Example: `Supervisor`.
*   `lastLoginTime` (_string (date-time)_) The time when the customer last logged in.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `lastName` (_string_) The customer's last name.  
    Maximum length: 256. Example: `Smith`.
*   `lastVisitTime` (_string (date-time)_) The time when the customer last visited.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `login` (_string_) The customer's login. In a PATCH call, this field can only be updated by providing a valid `currentPassword` for the shopper. The `loginId` update feature is available with B2C Commerce version 24.7, but is disabled by default. Contact Customer Support to enable this feature.  
    Maximum length: 256. Example: `jsmith`.
*   `note` (_string_) The customer's note.  
    Example: `customer-note`.
*   `paymentInstruments` (_array of CustomerPaymentInstrument_) The customer's payment instruments.
*   `paymentMethodReferences` (_array of CustomerPaymentMethodReference_) Payment method reference information for Salesforce Payments.
*   `phoneBusiness` (_string_) The customer's business phone number.  
    Maximum length: 32. Example: `555-555-5555`.
*   `phoneHome` (_string_) The customer's home phone number.  
    Maximum length: 32. Example: `555-555-5555`.
*   `phoneMobile` (_string_) The customer's mobile phone number.  
    Maximum length: 32. Example: `555-555-5555`.
*   `preferredLocale` (_string_) The customer's preferred locale.  
    Example: `us-en`.
*   `previousLoginTime` (_string (date-time)_) The time when the customer previously logged in.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `previousVisitTime` (_string (date-time)_) The time when the customer last visited the store.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `salutation` (_string_) The salutation to use for the customer.  
    Maximum length: 256. Example: `Mr.`.
*   `secondName` (_string_) The customer's second name.  
    Maximum length: 256. Example: `Smith`.
*   `suffix` (_string_) The customer's suffix (for example, "Jr." or "Sr.").  
    Maximum length: 256. Example: `Jr.`.
*   `title` (_string_) The customer's title (for example, "Mrs" or "Mr").  
    Maximum length: 256. Example: `Mr.`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ResetPasswordRequest

Document representing a reset password request.

*   `resetToken` (_string_, required) Temporary token used to reset password.  
    Maximum length: 4096. Example: `R1e2s3e4t5T6o7k8e9n0`.
*   `login` (_string_, required) The customer's login.  
    Maximum length: 256. Example: `loginId`.
*   `newPassword` (_string_, required) New password to reset to.  
    Maximum length: 4096. Example: `p@ssword2`.

### ResetPasswordTokenRequest

Document representing a reset password token request.

*   `login` (_string_, required) The customer's login.  
    Maximum length: 256. Example: `loginId`.

### ResetPasswordToken

Document representing reset password token response.

*   `login` (_string_, required) The customer's login.  
    Maximum length: 256. Example: `loginId`.
*   `email` (_string_, required) The customer's email address.  
    Maximum length: 256. Example: `jdoe@customer.com`.
*   `resetToken` (_string_, required) Temporary token generated that will be used to reset password.  
    Maximum length: 4096. Example: `R1e2s3e4t5T6o7k8e9n0`.
*   `expiresInMinutes` (_integer (int32)_, required) Reset token expiry (in minutes).  
    Example: `30`.

### CustomerExternalProfile

The Document representing the External Profile of a Customer.

Includes all fields of `CustomerExtProfileRequest`.

*   `customerId` (_string_, required) The Id of the Customer  
    Minimum length: 1. Example: `1234`.

### CustomerExtProfileRequest

Document representing the External Profile Request.

*   `authenticationProviderId` (_string_, required) The authentication Provider Id  
    Minimum length: 1. Example: `Google`.
*   `email` (_string_) The Email of the customer.  
    Minimum length: 1. Example: `s@gmail.com`.
*   `externalId` (_string_, required) The ID of the customer.  
    Minimum length: 1. Example: `jsmith@gmail.com`.
*   `firstName` (_string_) The First Name of the customer.  
    Minimum length: 1. Example: `John`.
*   `lastName` (_string_) The Last Name of the customer.  
    Minimum length: 1. Example: `Smith`.

### CustomerAddress

Address that is associated with a shopper (billing, shipping, mailing, and so on).

*   `address1` (_string_) The first address.  
    Maximum length: 256. Example: `10 Presidential Way`.
*   `address2` (_string_) The second address.  
    Maximum length: 256. Example: `Apt-616`.
*   `addressId` (_string_, required) The ID of the address as specified by account owner.  
    Maximum length: 256. Example: `Home`.
*   `city` (_string_) The city.  
    Maximum length: 256. Example: `New York`.
*   `companyName` (_string_) The company name.  
    Maximum length: 256. Example: `Acme Inc`.
*   `countryCode` (_string_, required) The two-letter ISO 3166-1 (Alpha-2) country code.  
    Maximum length: 2. Pattern: ^(\[A-Z\]\[A-Z\])$. Example: `US`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `9999-12-31T17:12:56.670Z`.
*   `firstName` (_string_) The first name.  
    Maximum length: 256. Example: `John`.
*   `fullName` (_string_) The full name.  
    Maximum length: 256. Example: `John Smith`.
*   `jobTitle` (_string_) The job title.  
    Maximum length: 256. Example: `Supervisor`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `9999-12-31T17:12:56.670Z`.
*   `lastName` (_string_, required) The last name.  
    Maximum length: 256. Example: `Smith`.
*   `phone` (_string_) The phone number.  
    Maximum length: 32. Example: `555-555-5555`.
*   `postBox` (_string_) The post box.  
    Maximum length: 256. Example: `12345`.
*   `postalCode` (_string_) The postal code.  
    Maximum length: 256. Example: `N5`.
*   `preferred` (_boolean_) The preferred attribute.  
    Example: `true`.
*   `salutation` (_string_) The salutation.  
    Maximum length: 256. Example: `Sir`.
*   `secondName` (_string_) The second name.  
    Maximum length: 256. Example: `Smith`.
*   `stateCode` (_string_) The state code.  
    Maximum length: 256. Example: `UT`.
*   `suffix` (_string_) The suffix.  
    Maximum length: 256. Example: `Sr.`.
*   `suite` (_string_) The suite.  
    Maximum length: 32. Example: `100`.
*   `title` (_string_) The title.  
    Maximum length: 256. Example: `Supervisor`.

### BasketsResult

Result document containing an array of baskets.

*   `baskets` (_array of object_) The list of baskets for a customer.
    
    Includes all fields of `Basket`.
    
*   `total` (_integer (int32)_, required) The total number of baskets.  
    Example: `10`.

### CustomerOrderResult

Result document containing an array of customer orders.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Order_) The array of customer order documents.

### PasswordChangeRequest

Document representing a password change request.

*   `currentPassword` (_string_, required) The customer's current password.  
    Maximum length: 4096. Example: `p@ssword1`.
*   `password` (_string_, required) The customer's new password.  
    Maximum length: 4096. Example: `p@ssword2`.

### CustomerPaymentInstrumentRequest

Document representing a customer payment instrument request.

*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `AB123`.
*   `giftCertificateCode` (_string_) The gift certificate code.  
    Maximum length: 256. Example: `gift-code`.
*   `paymentBankAccount` (_object_) The payment bank account request data.
    
    Includes all fields of `PaymentBankAccountRequest`.
    
*   `paymentCard` (_object_) The customer payment card.
    
    Includes all fields of `CustomerPaymentCardRequest`.
    
*   `paymentMethodId` (_string_) The payment method ID. Optional if a customer payment instrument ID is specified.  
    Maximum length: 256. Example: `Credit Card`.
*   `default` (_boolean_) The default payment instrument.  
    Example: `true`.

### CustomerPaymentInstrument

Method for customers to pay for the goods purchased on an ecommerce site. Payment methods include - credit card, debit card, bank account, and gift card.

*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `KDSJHKS`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `253402214400`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `253402214400`.
*   `maskedGiftCertificateCode` (_string_) The masked gift certificate code.  
    Example: `gift-code`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `PaymentCard`.
    
*   `paymentInstrumentId` (_string_) The payment instrument ID.  
    Example: `Personal`.
*   `paymentMethodId` (_string_) The payment method ID. Optional if a customer payment instrument ID is specified.  
    Maximum length: 256. Example: `Personal`.
*   `default` (_boolean_) The default payment instrument.  
    Example: `true`.

### CustomerPaymentInstrumentUpdateRequest

Document representing a customer payment instrument update request. Only allows updating the default flag and card expiration date.

*   `default` (_boolean_) The default payment instrument.  
    Example: `true`.
*   `paymentCard` (_object_) The payment card expiration information.
    *   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
        Minimum: 1. Maximum: 12. Example: `12`.
    *   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
        Example: `2028`.

### PaymentMethodReferenceSetupRequest

Request to set up a new payment method reference. Stripe does not require gatewayProperties. Adyen requires gatewayProperties.adyen.paymentMethod at runtime (400 if missing).

*   `paymentMethodType` (_string_) Payment Method Type  
    Maximum length: 256. Example: `card`.
*   `gatewayProperties` (_object_) Properties specific to the payment gateway
    *   `stripe` (_object_)
        
        ## Stripe-specific properties.
        
    *   `adyen` (_object_)
        
        ## Adyen-specific properties.
        

### PaymentMethodReferenceSetupResponse

Response from setting up a new payment method reference.

*   `paymentMethodReferenceSetupId` (_string_, required) The provider-specific identifier for the payment method reference setup (e.g., Stripe Setup Intent ID, Adyen pspReference).  
    Maximum length: 256. Example: `seti_1Mm8s8LkdIwHu7ix0OXBfTRG`.
*   `gatewayProperties` (_object_) Properties specific to the payment gateway
    *   `stripe` (_object_)
        
        ## Stripe-specific properties.
        
    *   `adyen` (_object_)
        
        ## Adyen-specific properties.
        

### PaymentMethodReferenceCompleteRequest

Request to complete payment method reference setup after provider success.

*   `paymentMethodReferenceSetupId` (_string_, required) Provider setup identifier (for example Stripe SetupIntent ID or Adyen pspReference).  
    Minimum length: 1. Maximum length: 256. Example: `seti_1Mm8s8LkdIwHu7ix0OXBfTRG`.

### CustomerProductListResult

Document representing a customer product lists result.

Includes all fields of `ResultBase`.

*   `data` (_array of CustomerProductList_, required) The customer product lists.

### CustomerProductList

Document representing a customer product list.

*   `coRegistrant` (_object_) The coregistrant of this product list.
    
    Includes all fields of `CustomerProductListRegistrant`.
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `currentShippingAddressInfo` (_object_) The resource link to the current shipping address of this customer product list.
    
    Includes all fields of `CustomerAddressInfo`.
    
*   `customerProductListItems` (_array of CustomerProductListItem_) The list of customer product list items.
*   `description` (_string_) The description of this product list.  
    Example: `My Product List`.
*   `event` (_object_) The event of this product list.
    
    Includes all fields of `ProductListEvent`.
    
*   `id` (_string_) The ID of this product list.  
    Minimum length: 1. Example: `MyList`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `name` (_string_) The name of this product list.  
    Example: `Danny's Product List`.
*   `postEventShippingAddressInfo` (_object_) The resource link to the post event shipping address of this customer product list.
    
    Includes all fields of `CustomerAddressInfo`.
    
*   `productListShippingAddress` (_object_) The abbreviated shipping address of this product list representing what an anonymous user can see.
    
    Includes all fields of `ProductListShippingAddress`.
    
*   `public` (_boolean_) Indicates whether the owner made this product list available for access by other customers.  
    Example: `true`.
*   `registrant` (_object_) The registrant of this product list.
    
    Includes all fields of `CustomerProductListRegistrant`.
    
*   `shippingAddressInfo` (_object_) The resource link to the shipping address of this customer product list.
    
    Includes all fields of `CustomerAddressInfo`.
    
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `wish_list`.

### CustomerProductListItem

Document representing a customer product list item.

*   `id` (_string_) The ID of this product list item.  
    Example: `Main Product`.
*   `priority` (_integer (int32)_, required) The priority of the item.  
    Example: `1`.
*   `product` (_object_) The product item.
    
    Includes all fields of `Product`.
    
*   `productId` (_object_) The ID of the product.  
    Example: `Toaster`.
    
    Includes all fields of `ProductId`.
    
    Example: `Toaster`.
    
*   `public` (_boolean_, required) Is this product list item available for access by other customers?  
    Example: `true`.
*   `purchasedQuantity` (_number (double)_) The quantity of products already purchased.  
    Example: `1`.
*   `quantity` (_number (double)_, required) The quantity of this product list item.  
    Minimum: 0. Example: `2`.
*   `type` (_string_) The type of the item.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### PublicProductListResult

Result document containing an array of public product list links.

Includes all fields of `ResultBase`.

*   `data` (_array of PublicProductListInfo_, required) The array of product list link documents.

### PublicProductList

Document representing a customer product list.

*   `coRegistrant` (_object_) The coRegistrant of this product list.
    
    Includes all fields of `ProductListRegistrant`.
    
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `description` (_string_) The description of this product list.  
    Example: `Super Product List`.
*   `event` (_object_) The event of this product list.
    
    Includes all fields of `ProductListEvent`.
    
*   `id` (_string_, required) The id of this product list.  
    Minimum length: 1. Example: `873465834`.
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `name` (_string_) The name of this product list.  
    Example: `My Product List`.
*   `productListItems` (_array of PublicProductListItem_) The product list items
*   `productListShippingAddress` (_object_) The abbreviated shipping address of this product list representing what anonymous users see.
    
    Includes all fields of `ProductListShippingAddress`.
    
*   `public` (_boolean_, required) Indicates whether the owner made this product list available for access by other customers.  
    Example: `true`.
*   `registrant` (_object_) The registrant of this product list.
    
    Includes all fields of `ProductListRegistrant`.
    
*   `type` (_string_, required) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `gift_registry`.

### PublicProductListItemResult

Results containing an array of public product list items.

Includes all fields of `ResultBase`.

*   `data` (_array of PublicProductListItem_) The array of public product list items.

### PublicProductListItem

Document representing a product list item.

*   `id` (_string_, required) The ID of this product list item.  
    Example: `8745345`.
*   `priority` (_integer (int32)_, required) The priority of the item.  
    Example: `2`.
*   `product` (_object_) The product item.
    
    Includes all fields of `Product`.
    
*   `type` (_string_, required) The type of the item.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### CustomerPaymentMethodReference

*   `type` (_string_, read-only) The payment method type. It is read only.  
    Allowed values: `card`, `sepa_debit`. Example: `card`.
*   `id` (_string_, read-only) The gateway ID for the payment method. It is read only.  
    Maximum length: 256. Example: `pm_1234567890`.
*   `last4` (_string_, read-only) The last four digits of the payment method number. It is read only.  
    Maximum length: 4. Example: `4242`.
*   `accountId` (_string_, read-only) Account identifier  
    Minimum length: 1. Maximum length: 100. Example: `acct_1RegszI5I22eU0I3`.
*   `brand` (_string_, read-only) Card brand when the payment method type is `card`.  
    Minimum length: 1. Maximum length: 256. Example: `visa`.
*   `expiryMonth` (_integer (int32)_, read-only) Card expiry month when the payment method type is `card`.  
    Minimum: 1. Maximum: 12. Example: `12`.
*   `expiryYear` (_integer (int32)_, read-only) Card expiry year when the payment method type is `card`.  
    Minimum: 1000. Maximum: 9999. Example: `2028`.
*   `accountHolderName` (_string_, read-only) SEPA account holder name when the payment method type is `sepa_debit`.  
    Minimum length: 1. Maximum length: 256. Example: `Jane Doe`.

### Basket

Document representing a basket.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `agentBasket` (_boolean_) Is the basket created by an agent? It is read only.  
    Example: `true`.
*   `basketId` (_string_) The unique identifier for the basket. It is read only.  
    Example: `e78aa5646a8efebdd9cdd38be7`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `OrderAddress`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `channelType` (_string_) The sales channel. It is read only.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`. Example: `storefront`.
*   `couponItems` (_array of CouponItem_) The coupon items.
*   `creationDate` (_string (date-time)_) The timestamp when the basket was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `currency` (_CurrencyCode_)
*   `customerInfo` (_object_) The customer information, if the customer is logged in.
    
    Includes all fields of `CustomerInfo`.
    
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items.
*   `groupedTaxItems` (_array of GroupedTaxItem_) Tax values that are grouped and summed based on the tax rate. The tax totals of the line items with the same tax rate are grouped together and summed up. This does not affect the calculation in any way. It is read only.
*   `inventoryReservationExpiry` (_string (date-time)_) The expiration datetime of the inventory reservation. It is read only.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the basket was last modified. It is read only.  
    Example: `2015-05-19T15:25:18.000Z`.
*   `merchandizeTotalTax` (_number (double)_) The total products tax in the purchase currency. Merchandise total price represents the sum of the product prices before services (such as shipping) or adjustments from promotions have been added. It is read only.  
    Example: `4.95`.
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments.
*   `orderTotal` (_number (double)_) The total price, including products, shipping and tax. It is read only.  
    Example: `110.24`.
*   `paymentInstruments` (_array of OrderPaymentInstrument_) The payment instruments list.
*   `productItems` (_array of BasketProductItem_) The product items.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products including adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `88`.
*   `shipments` (_array of Shipment_) The shipments.
*   `shippingItems` (_array of ShippingItem_) The shipping items.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments. It is read only.  
    Example: `0.3`.
*   `sourceCode` (_string_) The source code assigned to the basket. It is read only.  
    Example: `OUTDOOR1`.
*   `taxTotal` (_number (double)_) The total tax amount. It is read only.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net). It is read only.  
    Allowed values: `gross`, `net`. Example: `net`.
*   `taxRoundedAtGroup` (_boolean_) If the tax is rounded at the group level, this is set to true. If the tax is rounded at the item or unit level, it is set to false.  
    Example: `true`.
*   `temporaryBasket` (_boolean_) If the created basket is a temporary basket, this is set to true. Otherwise, it is set to false.  
    Example: `true`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Order

Document representing an order.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the order, including price adjustments, but not including service charges such as shipping. It is read only.  
    Example: `1.5`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the order, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `OrderAddress`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `channelType` (_string_) The sales channel. It is read only.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`. Example: `storefront`.
*   `confirmationStatus` (_string_) The confirmation status.  
    Allowed values: `not_confirmed`, `confirmed`. Example: `confirmed`.
*   `couponItems` (_array of CouponItem_) The coupon items. It is read only.
*   `createdBy` (_string_) This value depends on how the order was created. If a shopper created the order, this value is Customer. If a job created the order, this value is System. Otherwise, this value is the name of the user who created the order. It is read only.  
    Example: `Customer`.
*   `creationDate` (_string (date-time)_) The timestamp when the order was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `currency` (_object_) The ISO 4217 mnemonic code of the currency. It is read only.
    
    Includes all fields of `CurrencyCode`.
    
*   `customerInfo` (_object_) The customer information for guest or logged-in customers. It is read only.
    
    Includes all fields of `CustomerInfo`.
    
*   `customerName` (_string_) The customer name. It is read only.  
    Example: `Max Mustermann`.
*   `exportStatus` (_string_) The export status of the order.  
    Allowed values: `not_exported`, `exported`, `ready`, `failed`. Example: `exported`.
*   `externalOrderStatus` (_string_) The external status of the order.  
    Example: `Submitted`.
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items. It is read only.
*   `globalPartyId` (_string_) The Customer 360 Global Party ID associated with the shopper. It is read only.  
    Example: `GP_1234`.
*   `lastModified` (_string (date-time)_) The timestamp when the order was last modified. It is read only.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `merchandizeTotalTax` (_number (double)_) The total products tax in the purchase currency. Merchandise total prices represent the sum of product prices not including shipping or adjustments. It is read only.  
    Example: `1.5`.
*   `orderNo` (_object_) The order number.  
    Example: `00000410`.
    
    Includes all fields of `OrderNo`.
    
    Example: `00000410`.
    
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments. It is read only.
*   `orderToken` (_string_) The order token used to secure the lookup of an order on base of the plain order number. The order token contains only URL safe characters. It is read only.
*   `orderTotal` (_number (double)_) The total price, including products, shipping, and tax. It is read only.  
    Example: `110.24`.
*   `orderViewCode` (_string_) The order view code used to secure the order lookup of an order using Order Lookup API. The order view code contains only URL safe characters. Warning : Order view code must not be exposed in the URL and must only be displayed to the shopper or sent as an email. Order view code must not be logged in the code. It is read only.
*   `paymentInstruments` (_array of OrderPaymentInstrument_) The payment instruments list.
*   `paymentStatus` (_string_) The payment status.  
    Allowed values: `not_paid`, `part_paid`, `paid`. Example: `paid`.
*   `productItems` (_array of OrderProductItem_) The product items. It is read only.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `taxRoundedAtGroup` (_boolean_) If the tax is rounded at the group level, this is set to true. If the tax is rounded at the item or unit level, it is set to false. It is read only.  
    Example: `true`.
*   `shipments` (_array of Shipment_) The shipments. It is read only.
*   `shippingItems` (_array of ShippingItem_) The shipping items. It is read only.
*   `shippingStatus` (_string_) The shipping status.  
    Allowed values: `not_shipped`, `part_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments. It is read only.  
    Example: `0.3`.
*   `siteId` (_object_) The order's site. It is read only.  
    Example: `ShoppingSite`.
    
    Includes all fields of `SiteId`.
    
    Example: `ShoppingSite`.
    
*   `omsData` (_object_) Information retrieved from Order Management (OMS) for the order.
    
    Includes all fields of `OmsData`.
    
*   `sourceCode` (_string_) The source code assigned to the basket from which this order was created. It is read only.  
    Example: `OUTDOOR1`.
*   `status` (_string_) The status.  
    Allowed values: `created`, `new`, `completed`, `cancelled`, `replaced`, `failed`. Example: `created`.
*   `taxTotal` (_number (double)_) The total tax amount. It is read only.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net). It is read only.  
    Allowed values: `gross`, `net`. Example: `net`.
*   `groupedTaxItems` (_array of GroupedTaxItem_) Tax values that are grouped and summed based on the tax rate. The tax totals of the line items with the same tax rate are grouped together and summed up. This does not affect the calculation in any way. It is read only.
*   `guest` (_boolean_) The registration status of the customer. It is read only.  
    Example: `true`.

### PaymentBankAccountRequest

Document representing a payment bank account request.

*   `driversLicense` (_string_, required) The driver’s license.  
    Maximum length: 256. Example: `84736485`.
*   `driversLicenseStateCode` (_string_, required) The driver’s license state code.  
    Maximum length: 256. Example: `UT`.
*   `holder` (_string_, required) The holder of the bank account.  
    Maximum length: 256. Example: `John Smith`.
*   `number` (_string_, required) The payment bank account number.  
    Maximum length: 256. Example: `9796976`.

### CustomerPaymentCardRequest

Document representing a customer payment card request.

*   `cardType` (_string_, required) The payment card type (for example, "Visa").  
    Maximum length: 256. Example: `Visa`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data at the token store.  
    Example: `hk2jh293484`.
*   `expirationMonth` (_integer (int32)_, required) The month the payment card expires.  
    Example: `11`.
*   `expirationYear` (_integer (int32)_, required) The year the payment card expires.  
    Example: `9999`.
*   `holder` (_string_, required) The payment card holder.  
    Maximum length: 256. Example: `John Smith`.
*   `issueNumber` (_string_, required) The payment card issue number.  
    Maximum length: 256. Example: `92743927`.
*   `number` (_string_, required) The payment card number.  
    Maximum length: 4000. Example: `4454852652415965`.
*   `validFromMonth` (_integer (int32)_, required) The month the payment card valid is from.  
    Minimum: 1. Maximum: 12. Example: `11`.
*   `validFromYear` (_integer (int32)_, required) The year the payment card is valid from.  
    Example: `23`.

### PaymentCard

Document representing a payment card.

*   `cardType` (_string_) The payment card type.  
    Maximum length: 256. Example: `Visa`.
*   `creditCardExpired` (_boolean_) A flag indicating if the credit card is expired. It is read only.  
    Example: `true`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store.  
    Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number.  
    Maximum length: 4000. Example: `*********4422`.
*   `numberLastDigits` (_string_) The last digits of the payment card number. It is read only.  
    Maximum length: 4000. Example: `4422`.
*   `validFromMonth` (_integer (int32)_) The month the payment card is valid from.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year the payment card is valid from.  
    Example: `2015`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CustomerProductListRegistrant

Document representing a customer product list registrant.

*   `email` (_string_, required) The email of the registrant.  
    Example: `jsmith@mail.com`.
*   `firstName` (_string_, required) The first name of the registrant.  
    Example: `John`.
*   `lastName` (_string_, required) The last name of the registrant.  
    Example: `Smith`.
*   `role` (_string_, required) The role of the registrant.  
    Example: `Friend`.

### CustomerAddressInfo

Result document of product list addresses.

*   `addressId` (_string_, required) The ID of the address.  
    Maximum length: 256. Example: `Home`.
*   `title` (_string_, required) The link title.  
    Example: `title`.

### ProductListEvent

Document representing a product list event.

*   `city` (_string_) The city where the event takes place.  
    Example: `New York`.
*   `country` (_string_) The country where the event takes place.  
    Example: `USA`.
*   `date` (_string (date-time)_) The date when the event takes place.  
    Example: `253402214400`.
*   `state` (_string_) The federal state where the event takes place.  
    Example: `UT`.
*   `type` (_string_, required) Type of the event to celebrate.  
    Example: `wedding`.

### ProductListShippingAddress

Document representing a product list shipping address.

*   `addressId` (_string_, required) The ID of this address.  
    Minimum length: 1. Example: `Home`.
*   `city` (_string_) The city of this address.  
    Example: `New York`.
*   `firstName` (_string_) The first name of this address.  
    Example: `John`.
*   `lastName` (_string_) The last name of this address.  
    Example: `Smith`.

### Product

Any product that is sold, shown alone, and does not have variations such as different sizes or colors. A product has no reliance on any other product for inheritance. _A product has a SKU and can have a product option, which has a different SKU_.

*   `brand` (_string_) The product's brand.  
    Example: `Apple`.
*   `bundledProducts` (_array of BundledProduct_) The array of all bundled products of this product.
*   `currency` (_CurrencyCode_)
*   `ean` (_string_) The European Article Number of the product.  
    Example: `8essdf9w3`.
*   `fetchDate` (_integer (int32)_)  
    Example: `5`.
*   `id` (_ProductId_, required)
*   `imageGroups` (_array of ImageGroup_) The array of product image groups.
*   `inventories` (_array of Inventory_) The array of product inventories explicitly requested via the 'inventory\_ids' query parameter. This property is only returned in context of the 'availability' expansion.
*   `inventory` (_object_) The site default inventory information. This property is only returned in context of the 'availability' expansion.
    
    Includes all fields of `Inventory`.
    
*   `longDescription` (_string_) The localized product's long description.  
    Example: `Awesome long description of product`.
*   `manufacturerName` (_string_) The product's manufacturer name.  
    Example: `Apple`.
*   `manufacturerSku` (_string_) The product's manufacturer SKU.  
    Example: `2ND8834`.
*   `master` (_object_) The master product information, only for types: master, variation group, and variant.
    
    Includes all fields of `Master`.
    
*   `minOrderQuantity` (_number (double)_) The minimum order quantity for this product.  
    Example: `2`.
*   `name` (_string_) The localized product name.  
    Example: `Apple IPod Classic`.
*   `options` (_array of Option_) The array of product options, only for type option. This array can be empty.
*   `pageDescription` (_string_) The localized product's page description.  
    Example: `Really good Product`.
*   `pageKeywords` (_string_) The localized product's page description.  
    Example: `Ipod, Music Player`.
*   `pageTitle` (_string_) The localized product's page title.  
    Example: `Apple IPod Classic`.
*   `pageMetaTags` (_array of PageMetaTag_) Page Meta tags associated with the given product.
*   `price` (_number (double)_) The sales price of the product. In case of complex products, like master or set, this is the minimum price of related child products.  
    Example: `59.99`.
*   `pricePerUnit` (_number (double)_) The price per unit if defined for the product  
    Example: `19.99`.
*   `pricePerUnitMax` (_number (double)_) The max price per unit typically for a master product's variant.  
    Example: `29.99`.
*   `priceMax` (_number (double)_) The maximum sales of related child products in complex products like master or set.  
    Example: `69.99`.
*   `priceRanges` (_array of PriceRange_) Array of one or more price range objects representing one or more Pricebooks in context for the site.
*   `prices` (_object_) The prices map with pricebook IDs and their values.
    
    Additional properties: `number (double)`.
    
*   `primaryCategoryId` (_string_) The ID of the products primary category.  
    Example: `electronics`.
*   `primaryCategory` (_object_) The primary category of the product, including its full ancestor breadcrumb path (root to leaf, root category node excluded). Only present when the primary\_category expand is requested.
    *   `id` (_string_) The ID of the primary category.  
        Minimum length: 1. Maximum length: 256. Example: `electronics-digital-media-players`.
    *   `name` (_string_) The localized name of the primary category.  
        Minimum length: 1. Maximum length: 256. Example: `iPod & MP3 Players`.
    *   `slug` (_string_) SEO path persisted for the primary category. This property is omitted when no category URL mapping exists for the requested locale.  
        Minimum length: 1. Maximum length: 256. Example: `electronics/ipod-mp3-players`.
    *   `parentCategoryTree` (_array of object_) The list of ancestor categories from root to the primary category (root category node excluded).
        *   `id` (_string_) The ID of the ancestor category.  
            Minimum length: 1. Maximum length: 256. Example: `electronics`.
        *   `name` (_string_) The name of the ancestor category.  
            Minimum length: 1. Maximum length: 256. Example: `Electronics`.
        *   `slug` (_string_) SEO path persisted for the primary category. This property is omitted when no category URL mapping exists for the requested locale.  
            Minimum length: 1. Maximum length: 256. Example: `electronics/ipod-mp3-players`.
*   `productLinks` (_array of ProductLink_) The array of source and target product links information.
*   `productPromotions` (_array of ProductPromotion_) An array of active customer product promotions for this product, sorted by promotion priority using SORT\_BY\_EXCLUSIVITY ordering (exclusivity → rank → promotion class → discount type → best discount → ID). This array can be empty. Coupon promotions are not returned in this array. See [PromotionPlan.SORT\_BY\_EXCLUSIVITY](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_campaign_PromotionPlan.html) for more details.
*   `recommendations` (_array of Recommendation_) Returns a list of recommendations.
*   `setProducts` (_array of Product_) The array of set products of this product.
*   `shortDescription` (_string_) The localized product short description.  
    Example: `Awesome Product`.
*   `slug` (_string_) The SEO URL slug for the product. Only present when the slug expand is requested and the slug feature is enabled.  
    Maximum length: 256. Example: `modern-dress-shirt/74974310M.html`.
*   `slugUrl` (_string_) The complete link to this product's storefront page.  
    Example: `https://www.example.com/on/store/Sites-MySite/default/Product-Show?pid=MyProduct`.
*   `stepQuantity` (_number (double)_) The steps in which the order amount of the product can be increased.  
    Example: `2`.
*   `tieredPrices` (_array of ProductPriceTable_) The document represents list of tiered prices if the product is a variant
*   `type` (_object_) The product type information. Can be one or more of the following values: item, master, variation\_group, variant, bundle, and set.
    
    Includes all fields of `ProductType`.
    
*   `unit` (_string_) The sales unit of the product.  
    Example: `lbs`.
*   `upc` (_string_) The Universal Product Code (UPC).  
    Example: `JSDU876`.
*   `validFrom` (_string (date-time)_) The time a product is valid from.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `validTo` (_string (date-time)_) The time a product is valid to.  
    Example: `9999-12-31T23:59:59.0Z`.
*   `variants` (_array of Variant_) The array of actual variants. Only for master, variation group, and variant types. This array can be empty.
*   `variationAttributes` (_array of VariationAttribute_) Sorted array of variation attributes information. Only for master, variation group, and variant types. This array can be empty.
*   `variationGroups` (_array of VariationGroup_) The array of actual variation groups. Only for master, variation group, and variant types. This array can be empty.
*   `variationValues` (_object_) The actual variation attribute ID - value pairs. Only for variant and variation group types.
    
    Additional properties: `string`.
    
*   `shippingMethods` (_array of ShippingMethod_) The array of applicable shipping methods for this product. This array can be empty. This property is only returned in context of the 'shipping\_methods' expansion.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### PublicProductListInfo

Document representing a link to a public product list.

*   `description` (_string_) The description of this product list.  
    Example: `Super Awesome ProductList`.
*   `id` (_string_, required) The ID of the product-list document.  
    Example: `3958739435`.
*   `name` (_string_) The name of this product list.  
    Example: `My Product List`.
*   `title` (_string_, required) The link title.  
    Example: `Product List Title`.
*   `type` (_string_, required) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `custom_1`.

### ProductListRegistrant

A `ProductListRegistrant` is typically associated with an event-related product list, such as a gift registry. It holds information about a person associated with the event, such as a bride or groom.

*   `firstName` (_string_, required) The first name of the registrant.  
    Example: `John`.
*   `lastName` (_string_, required) The last name of the registrant.  
    Example: `Smith`.
*   `role` (_string_, required) The role of the registrant.  
    Example: `CEO`.

### OrderAddress

Document representing an order address.

*   `address1` (_string_) The first address line.  
    Example: `45 Main Rd.`.
*   `address2` (_string_) The second address line.  
    Example: `Apartment 204`.
*   `city` (_string_) The city.  
    Example: `Boston`.
*   `companyName` (_string_) The company name.  
    Example: `Salesforce`.
*   `countryCode` (_CountryCode_)
*   `firstName` (_string_) The first name.  
    Example: `Max`.
*   `fullName` (_string_) The full name.  
    Example: `Max Mustermann`.
*   `id` (_string_) The ID of the address.  
    Example: `me`.
*   `jobTitle` (_string_) The job title.  
    Example: `Software Engineer`.
*   `lastName` (_string_) The last name.  
    Example: `Mustermann`.
*   `phone` (_string_) The phone number.  
    Example: `6175555555`.
*   `postBox` (_string_) The post office box.  
    Example: `PO BOX 109`.
*   `postalCode` (_string_) The postal code.  
    Example: `05408`.
*   `salutation` (_string_) The salutation.  
    Example: `Mr`.
*   `secondName` (_string_) The second name.
*   `stateCode` (_string_) The state code.  
    Example: `MA`.
*   `suffix` (_string_) The suffix.  
    Example: `Sr`.
*   `suite` (_string_) The suite.  
    Example: `24A`.
*   `title` (_string_) The title.  
    Example: `Dr.`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### BonusDiscountLineItem

Document representing a bonus discount line item.

*   `bonusProducts` (_array of ProductDetailsLink_) The bonus products the customer can choose from.
*   `couponCode` (_string_) The coupon code that triggered the promotion, if applicable.  
    Example: `5ties`.
*   `id` (_string_) The ID of the line item. It is read only.  
    Example: `91f4dd8bfa0653d58b7783b04f`.
*   `maxBonusItems` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotionId` (_string_) The ID of the promotion that triggered the creation of the line item.  
    Example: `Buy1Get2`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CouponItem

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256. Example: `5ties`.
*   `couponItemId` (_object_) The coupon item ID. It is read only.
    
    Includes all fields of `CouponItemId`.
    
*   `statusCode` (_string_) The status of the coupon item. It is read only.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`. Example: `no_applicable_promotion`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is "applied" or "no\_applicable\_promotion". It is read only.  
    Example: `true`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### CustomerInfo

The customer information for guest or logged-in customers.

*   `customerId` (_string_) The customer ID. It is read only.  
    Maximum length: 100. Example: `abMKqMaNYOBMnNdDNzyC5oNTi5`.
*   `customerName` (_string_) The customer name.  
    Example: `Max Mustermann`.
*   `customerNo` (_string_) The customer number.  
    Maximum length: 100. Example: `0002352`.
*   `email` (_string_, required) The customer's email address.  
    Example: `no-reply@salesforce.com`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GiftCertificateItem

A gift certificate item.

*   `amount` (_number (double)_, required) The gift certificate item amount.  
    Example: `20`.
*   `giftCertificateItemId` (_object_) The item ID. It is read only.
    
    Includes all fields of `GiftCertificateItemId`.
    
*   `message` (_string_) The gift certificate message.  
    Maximum length: 4000. Example: `Birthday present.`.
*   `recipientEmail` (_string_, required) The recipient email.  
    Minimum length: 1. Example: `no-reply@salesforce.com`.
*   `recipientName` (_string_) The recipient's name.  
    Example: `Daniel Mustermann`.
*   `senderName` (_string_) The sender's name.  
    Example: `Max Mustermann`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GroupedTaxItem

Document representing the grouped tax item.

*   `taxRate` (_number (double)_) The tax rate. It is read only.  
    Example: `0.1`.
*   `taxValue` (_number (double)_) The summed up tax total for the tax rate. It is read only.  
    Example: `10.03`.

### PriceAdjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level.

*   `appliedDiscount` (_object_) Details describing the discount this price adjustment is based on. For adjustments not based on a discount, this value is null.
    
    Includes all fields of `Discount`.
    
*   `couponCode` (_string_) The coupon code of the coupon this price adjustment is based on. For adjustments not based on a coupon, this value is null. It is read only.  
    Example: `5ties`.
*   `createdBy` (_string_) The user who created the price adjustment. It is read only.  
    Example: `Support`.
*   `creationDate` (_string (date-time)_) The timestamp when the price adjustment was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.  
    Example: `true`.
*   `itemText` (_string_) The text describing the item.
*   `lastModified` (_string (date-time)_) The timestamp when the price adjustment was last modified. It is read only.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `manual` (_boolean_) A flag indicating whether this price adjustment was created by a manual process. If the price adjustment was created by the promotion engine, this value is always false.  
    Example: `true`.
*   `price` (_number (double)_) The adjustment price. It is read only.  
    Example: `120.88`.
*   `priceAdjustmentId` (_object_) The price adjustment ID. It is read only.
    
    Includes all fields of `PriceAdjustmentId`.
    
*   `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID so long it is not used by a price adjustment belonging to the same item, and is not used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated.
*   `reasonCode` (_string_) The reason for the price adjustment.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderPaymentInstrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction. It is read only.
    
    Includes all fields of `Status`.
    
*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `12030000`.
*   `maskedGiftCertificateCode` (_string_) The gift certificate code with the last 4 characters not masked.  
    Example: `******Gzzy`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `PaymentCard`.
    
*   `giftCard` (_object_) The gift card.
    
    Includes all fields of `GiftCardResponse`.
    
*   `paymentInstrumentId` (_object_) The payment instrument ID. It is read only.
    
    Includes all fields of `PaymentInstrumentId`.
    
*   `paymentMethodId` (_string_) The payment method ID. It is read only.  
    Maximum length: 256. Example: `CREDIT_CARD`.
*   `paymentReference` (_object_) Payment reference information for various payment service providers, only when Salesforce Payments is enabled.
    *   `paymentReferenceId` (_string_) Payment reference identifier. Can be payment intent ID for Stripe, PSP reference for Adyen, PayPal order ID for PayPal, or similar identifier for other payment providers.  
        Maximum length: 256. Example: `pi_3N4B2vF0wDjebNCp1234567`.
    *   `gateway` (_string_) The payment gateway used to process the payment.  
        Allowed values: `stripe`, `paypal`, `adyen`. Example: `stripe`.
    *   `gatewayProperties` (_object_) The payment gateway specific properties.
        *   `stripe` (_object_)
            
            ## Stripe specific properties.
            
            *   setupFutureUsage: Indicates that you intend to make future payments with this payment method.
                *   **on\_session**: The payment method is intended to be used for a future payment on the same website session.
                *   **off\_session**: The payment method is intended to be used for a future payment on a different website session.
            *   **null**: The payment method is not intended to be used for a future payment.
            *   clientSecret: Secret for Stripe client-side payment confirmation. Don't store, log, or expose the client secret to anyone other than the customer, and only use it on pages where TLS is enabled.
                *   type: string
                *   maxLength: 256
                *   example: "pi\_1J4K5L2eZvKYlo2CyZ8K5L6M\_secret\_abc123"
        *   `paypal` (_object_)
            
            ## PayPal specific properties.
            
        *   `adyen` (_object_)
            
            ## Adyen specific properties.
            
            *   adyenError: Error information returned by Adyen if the payment fails. Null on success.
            *   adyenPaymentIntent: The Adyen payment intent object containing payment details and required actions.
                *   resultCode: The result of the payment request (for example, "REDIRECT\_SHOPPER", "AUTHORISED", "PENDING", "REFUSED").
                *   accountID: The Adyen merchant account ID.
                *   adyenPaymentIntentAction: The action object for payment methods requiring additional shopper interaction.
                    *   url: The URL for completing the payment (redirect or 3DS authentication).
                    *   type: The action type (for example, "redirect", "threeDS2", "voucher").
                    *   method: The HTTP method for the action (for example, "GET", "POST").
            *   successful: A boolean indicating whether the Adyen operation is successful.

### BasketProductItem

Document representing a basket product item.

Includes all fields of `ProductItem`.

### Shipment

Document representing a shipment.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, not including price adjustments or service charges such as shipping. It is read only.  
    Example: `4.95`.
*   `productSubTotal` (_number (double)_) The total price of all products in the shipment, including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `shipmentId` (_object_) The order-specific ID of the shipment. The default value is 'me'.  
    Default: `me`.
    
    Includes all fields of `ShipmentId`.
    
    Default: `me`.
    
*   `shipmentNo` (_string_) The shipment number of this shipment. This number is automatically generated. It is read only.
*   `shipmentTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments, shipping charges, and tax. It is read only.  
    Example: `39.99`.
*   `shippingAddress` (_object_) The shipping address.
    
    Includes all fields of `OrderAddress`.
    
*   `shippingMethod` (_ShippingMethod_)
*   `shippingStatus` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges in the shipment, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, not including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `taxTotal` (_number (double)_) The total tax on the shipment, including item-level price adjustments and service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `1.8`.
*   `trackingNumber` (_string_) The tracking number of the shipment.  
    Example: `1Z204E380338943508`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingItem

Document representing a shipping item.

*   `adjustedTax` (_number (double)_) The tax for the shipping item, including price adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the shipping item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `itemId` (_string_) The shipping item ID. Use it to identify this shipping item when updating its quantity or creating a custom price adjustment for it. It is read only.  
    Example: `430ef5aad3a24de59378458434`.
*   `itemText` (_string_) The text describing the shipping item.  
    Example: `Shipping`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the shipping item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.
*   `shipmentId` (_object_) The identifier of the shipment to which this item belongs.
    
    Includes all fields of `ShipmentId`.
    
*   `tax` (_number (double)_) The tax on the product item, not including adjustments. It is read only.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this shipping item. It is read only.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1. It is read only.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### OrderNo

The order number

Type: `string`.

Minimum length: 1. Maximum length: 50. Example: `00000410`.

### OrderProductItem

Document representing an order product item.

Includes all fields of `ProductItem`.

*   `omsData` (_object_) Product information retrieved from Order Management (OMS). Only available in the context of an order.
    
    Includes all fields of `OmsProductData`.
    

### OmsData

Additional information retrieved from Order Management (OMS) See [https://developer.salesforce.com/docs/atlas.en-us.order\_management\_developer\_guide.meta/order\_management\_developer\_guide/sforce\_api\_objects\_ordersummary.htm](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/sforce_api_objects_ordersummary.htm) for more information.

*   `status` (_string_) Current status of the order  
    Example: `shipped`.
*   `shipments` (_array of OmsShipment_) List of shipments associated with the order

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### BundledProduct

A bundle of products that can be bought together (all or nothing). Each product in the bundle can itself be bought independently, but this is outside of the context of the bundle. A bundle is a purchasing convenience. _Product bundle has a SKU and price._

*   `id` (_string_, required)  
    Example: `823476`.
*   `product` (_object_, required) The product being bundled.
    
    Includes all fields of `Product`.
    
*   `quantity` (_number (double)_, required) For the product being bundled, the quantity added to the bundle.  
    Example: `5`.

### ImageGroup

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of Image_, required) The images of the image group.
*   `variationAttributes` (_array of VariationAttribute_) Returns a list of variation attributes applying to this image group.
*   `viewType` (_string_, required) The image view type.  
    Example: `hi-res`.

### Inventory

Document representing inventory information of the current product for a particular inventory list.

*   `ats` (_number (double)_) The Available To Sell (ATS) of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.ats.max\_threshold'.  
    Example: `15`.
*   `backorderable` (_boolean_) A flag indicating whether the product is backorderable.  
    Example: `true`.
*   `id` (_InventoryId_, required)
*   `inStockDate` (_string (date-time)_) A flag indicating the date when the product will be in stock.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `orderable` (_boolean_) A flag indicating whether at least one of the products is available to sell.  
    Example: `true`.
*   `preorderable` (_boolean_) A flag indicating whether the product is preorderable.  
    Example: `false`.
*   `stockLevel` (_number (double)_) The stock level of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.stock\_level.max\_threshold'.  
    Example: `10`.

### Master

The master product is a representation of a group of variant products. This is a non-buyable entity, provides inheritable attributes for its product variants, and is used for navigation. _Doesn't have a SKU._

*   `masterId` (_object_, required) The ID (SKU) of the master product.
    
    Includes all fields of `ProductId`.
    
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants can be ordered.  
    Example: `true`.
*   `price` (_object_) The minimum sales price of the related variants.
    
    Includes all fields of `Price`.
    
*   `priceMax` (_object_) The maximum sales price of the related variants.
    
    Includes all fields of `Price`.
    
*   `prices` (_object_) List of sale prices.
    
    Additional properties: `number (double)`.
    

### Option

Product options enable you to sell configurable products that have optional accessories, upgrades, or additional services. Options are always purchased with a product and can't be purchased separately. _Product Option has a SKU and a price associated with it._

*   `description` (_string_) The localized description of the option.  
    Example: `Get this Option`.
*   `id` (_object_, required) The ID of the option.  
    Example: `Warranty`.
    
    Includes all fields of `ProductId`.
    
    Example: `Warranty`.
    
*   `image` (_string_) The URL to the option image.  
    Example: `https://www.exampleimage.com/images/optionImage.jpg`.
*   `name` (_string_) The localized name of the option.  
    Example: `Warranty`.
*   `values` (_array of OptionValue_) The array of option values. This array can be empty.

### PageMetaTag

Document representing a Page Meta Tag object.

*   `id` (_string_) The ID of the Page Meta Tag.  
    Maximum length: 100. Example: `title`.
*   `value` (_string_) Locale-specific value of the Page Meta Tag, evaluated by resolving the rule set for the given Business Manager ID.  
    Example: `Buy the Long Sleeve Covered Placket Blouse for USD 61.99.`.
*   `type` (_string_)
    
    The kind of Page Meta Tag, indicating how the storefront should render the value. Documented values are `name`, `property`, `title`, and `jsonld`:
    
    *   `name` — render as `<meta name="...">`.
    *   `property` — render as `<meta property="...">` (e.g. Open Graph tags).
    *   `title` — render as the HTML `<title>` element.
    *   `jsonld` — JSON-LD structured data, intended for rendering inside `<script type="application/ld+json">`. The field may be absent when the kind cannot be determined. Clients should treat unknown values as opaque so additional kinds can be introduced without breaking the contract.
    
      
    Maximum length: 64. Example: `name`.

### PriceRange

Document representing price ranges for a product which happens to be a master product (per Pricebook)

*   `maxPrice` (_object_) Maximum price for the given pricebook (usually for a master Product would be the price for the Variant which has the highest price out of all Variants in that pricebook)
    
    Includes all fields of `Price`.
    
*   `minPrice` (_object_) Minimum price for the given pricebook (usually for a master Product would be the price for the Variant which has the least price out of all Variants in that pricebook)
    
    Includes all fields of `Price`.
    
*   `pricebook` (_string_) The active pricebook from which the min and the max prices are calculated. The pricebook is based on the site context of the request as defined in ECOM.  
    Example: `usd-list-pricebook`.

### ProductLink

Document representing a link between two products. It contains the ID of the source and target products, the type of product link, and the URLs to retrieve product data.

*   `sourceProductId` (_object_, required) The semantic ID of the product this product link is coming from.  
    Example: `824756924`.
    
    Includes all fields of `ProductId`.
    
    Example: `824756924`.
    
*   `sourceProductLink` (_string_, required) The URL addressing the product this product link is coming from.  
    Example: `Link`.
*   `targetProductId` (_object_, required) The semantic ID of the product this product link is pointing to.  
    Example: `2TR93459`.
    
    Includes all fields of `ProductId`.
    
    Example: `2TR93459`.
    
*   `targetProductLink` (_string_, required) The URL addressing the product this product link is pointing to.  
    Example: `Link`.
*   `type` (_string_, required) The type of product link.  
    Allowed values: `cross_sell`, `replacement`, `up_sell`, `accessory`, `newer_version`, `alt_orderunit`, `spare_part`, `other`. Example: `up_sell`.

### ProductPromotion

Document representing a product promotion.

*   `calloutMsg` (_string_, required) The localized call-out message of the promotion.  
    Example: `Fantastic promotion`.
*   `promotionId` (_string_, required) The unique ID of the promotion.  
    Example: `summerSale`.
*   `promotionalPrice` (_object_, required) The promotional price for this product.
    
    Includes all fields of `Price`.
    

### Recommendation

Document representing a product recommendation.

*   `calloutMsg` (_string_) The localized callout message of the recommendation.  
    Example: `Absolutely recommended`.
*   `image` (_Image_)
*   `longDescription` (_string_) The localized long description of the recommendation.  
    Example: `Really good detailed product description`.
*   `name` (_string_) The localized name of the recommendation.  
    Example: `Apple Ipod Shuffle`.
*   `recommendationType` (_RecommendationType_, required)
*   `recommendedItemId` (_string_) The recommended item ID of the recommendation.  
    Example: `apple-ipod-shuffle`.
*   `shortDescription` (_string_) The localized short description of the recommendation.  
    Example: `Product description`.

### ProductPriceTable

Tiered Price Level Object

*   `price` (_object_) Price for the product for the specified tier for the specified pricebook
    
    Includes all fields of `Price`.
    
*   `pricebook` (_string_) The active pricebook for which this price is defined  
    Example: `usd-list-pricebook`.
*   `quantity` (_number (double)_) Quantity tier for which the price is defined.  
    Example: `1`.

### ProductType

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.  
    Example: `true`.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.  
    Example: `false`.
*   `master` (_boolean_) A flag indicating whether the product is a master.  
    Example: `true`.
*   `option` (_boolean_) A flag indicating whether the product is an option.  
    Example: `false`.
*   `set` (_boolean_) A flag indicating whether the product is a set.  
    Example: `true`.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.  
    Example: `false`.
*   `variationGroup` (_boolean_) A flag indicating whether the product is a variation group.  
    Example: `false`.

### Variant

A product which is a variation within a master product that describes different colors, sizes, or other variation attributes. _Has a SKU._

*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.  
    Example: `true`.
*   `price` (_object_) The sales price of the variant.
    
    Includes all fields of `Price`.
    
*   `productId` (_object_, required) The ID (SKU) of the variant.  
    Example: `8W4756834`.
    
    Includes all fields of `ProductId`.
    
    Example: `8W4756834`.
    
*   `tieredPrices` (_array of ProductPriceTable_) List of tiered prices if the product is a variant
*   `variationValues` (_object_) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    

### VariationAttribute

Document representing a variation attribute.

*   `id` (_string_, required) The ID of the variation attribute.  
    Minimum length: 1. Example: `color`.
*   `name` (_string_) The localized display name of the variation attribute.  
    Example: `Color`.
*   `values` (_array of VariationAttributeValue_) The sorted array of variation values. This array can be empty.

### VariationGroup

Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for its product variants, and is used for navigation. _Doesn't have a SKU._

*   `orderable` (_boolean_, required) A flag indicating whether the variation group is orderable.  
    Example: `false`.
*   `price` (_object_, required) The sales price of the variation group.
    
    Includes all fields of `Price`.
    
*   `productId` (_object_, required) The ID (SKU) of the variation group.  
    Example: `49345VG`.
    
    Includes all fields of `ProductId`.
    
    Example: `49345VG`.
    
*   `variationValues` (_object_, required) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    

### ShippingMethod

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.  
    Example: `Order received within 7-10 business days`.
*   `externalShippingMethod` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method ID.  
    Maximum length: 256. Example: `001`.
*   `name` (_string_) The localized name of the shipping method.  
    Example: `Ground`.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs, product level fix, and surcharge costs. It is read only.  
    Example: `15`.
*   `shippingPromotions` (_array of ShippingPromotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### ProductDetailsLink

Document representing a link to the resource for product details.

*   `productDescription` (_string_) The description of the product.  
    Example: `Nintendo DS revolutionizes handheld gameplay.`.
*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `title` (_string_) The link title.  
    Example: `Nintendo DS Game Console`.

### CouponItemId

The coupon item ID

Type: `string`.

Minimum length: 1. Example: `d4c9c0141e9c74c150225580f3`.

### GiftCertificateItemId

Type: `string`.

Minimum length: 1. Example: `629dea6e7b61e58da629b57b21`.

### Discount

Document representing a discount.

*   `amount` (_number (double)_) The discount amount for discount types that define specific discount amounts. It is read only.  
    Example: `130.88`.
*   `percentage` (_number (double)_) The discount percent for discount types that define percentage discounts. It is read only.  
    Example: `0.19`.
*   `priceBookId` (_string_) The price book ID that is used with some types. It is read only.  
    Example: `usd-sale-prices`.
*   `type` (_string_, required) The type of discount. It is read only.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`. Example: `fixed_price`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceAdjustmentId

Type: `string`.

Example: `ba248424e3eee797f062161f8b`.

### Status

Document representing an object status.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_) The status. For more information on the status values see Status.OK and Status.ERROR.

### GiftCardResponse

Document representing a gift card response.

*   `brand` (_string_) The gift card brand.  
    Maximum length: 256. Example: `givex`.
*   `maskedCardNumber` (_string_) The masked gift card number.  
    Maximum length: 40. Example: `*********4422`.
*   `expirationMonth` (_integer (int32)_) The month when the gift card expires.  
    Example: `1`.
*   `expirationYear` (_integer (int32)_) The year when the gift card expires.  
    Example: `2030`.

### PaymentInstrumentId

The payment instrument ID

Type: `string`.

Example: `ba248424e3eee797f062162f8b`.

### ProductItem

Document representing a product item.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `130`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus.  
    Example: `true`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.
*   `optionItems` (_array of OptionItem_) The option items.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `20.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `15.5`.
*   `productId` (_string_) The ID of the product.  
    Maximum length: 100. Example: `nintendo-ds-console`.
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `qualifyingProductItemId` (_string_) Returns the id of the ProductLineItem that qualified the basket for this bonus product. This method is only applicable if the product line item is a bonus product line item, and if the promotion is a product promotion with number of qualifying products granting a bonus-product discount. If these conditions aren't met, the method returns null. If there are multiple product line items that triggered this bonus product, this method returns the last one by position within the order.  
    Maximum length: 28.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax for the product item, not including price adjustments. It is read only.  
    Example: `0.3`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this product item. It is read only.  
    Example: `30`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.9`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShipmentId

The identifier of the shipment

Type: `string`.

Minimum length: 1. Example: `me`.

### OmsProductData

Additional information retrieved from Order Management (OMS) See [https://developer.salesforce.com/docs/atlas.en-us.order\_management\_developer\_guide.meta/order\_management\_developer\_guide/sforce\_api\_objects\_orderitemsummary.htm](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/sforce_api_objects_orderitemsummary.htm) for more information. Only available in context of an order.

*   `status` (_string_) Order Management (OMS) status  
    Allowed values: `ordered`, `returned`, `canceled`, `paid`, `reshipped`, `fulfilled`, `partially_fulfilled`, `allocated`, `partially_allocated`, `return_initiated`. Example: `ordered`.
*   `quantityAvailableToCancel` (_number (double)_) The quantity that can be cancelled.  
    Example: `2`.

### OmsShipment

Shipment information from Salesforce Order Management created during fulfillment process. See [https://developer.salesforce.com/docs/atlas.en-us.230.0.order\_management\_developer\_guide.meta/order\_management\_developer\_guide/sforce\_api\_objects\_fulfillmentorder.htm](https://developer.salesforce.com/docs/atlas.en-us.230.0.order_management_developer_guide.meta/order_management_developer_guide/sforce_api_objects_fulfillmentorder.htm) for more information.

*   `id` (_string_) Unique identifier for the shipment  
    Example: `0OBVF000000003F4AQ`.
*   `status` (_string_) Current status of the shipment  
    Example: `shipped`.
*   `provider` (_string_) Shipping provider name  
    Example: `UPS`.
*   `trackingNumber` (_string_) Tracking number for the shipment  
    Example: `123456789`.
*   `trackingUrl` (_string_) URL to track the shipment  
    Example: `https://www.ups.com/track?loc=en_US&tracknum=123456789`.
*   `expectedDeliveryDate` (_string (date-time)_) Expected delivery date and time  
    Example: `2025-11-12T20:00:00.000+0000`.
*   `actualDeliveryDate` (_string (date-time)_) Actual delivery date and time (null if not yet delivered)  
    Example: `2025-11-12T20:00:00.000+0000`.
*   `shipmentItems` (_array of OmsShipmentItem_) Items included in this shipment

### Image

Product image

*   `alt` (_string_) The localized alternative text of the image.  
    Example: `Apple iPod Shuffle, large`.
*   `disBaseLink` (_string_) Base URL for the Dynamic Image Service (DIS) address. This is only shown if the image is stored on the server and DIS is enabled.  
    Example: `https://example.com/images/large/ipod-shuffle-silver.jpg`.
*   `link` (_string_, required) The URL of the actual image.  
    Minimum length: 1. Example: `https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dwc2/images/large/ipod-shuffle.jpg`.
*   `title` (_string_) The localized title of the image.  
    Example: `Apple iPod Shuffle`.

### InventoryId

The inventory ID.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `Site1InventoryList`.

### Price

Document representing a price for a product

Type: `number (double)`.

Example: `12.99`.

### OptionValue

Document representing an option value.

*   `default` (_boolean_) A flag indicating whether this option value is the default one.  
    Example: `true`.
*   `id` (_object_, required) The ID of the option value.  
    Example: `5YR`.
    
    Includes all fields of `ProductId`.
    
    Example: `5YR`.
    
*   `name` (_string_) The localized name of the option value.  
    Example: `5 Year Warranty`.
*   `price` (_object_) The effective price of the option value.
    
    Includes all fields of `Price`.
    

### RecommendationType

Document representing a recommendation type.

*   `displayValue` (_string_, required) The localized display value of the recommendation type.  
    Example: `UpSell`.
*   `value` (_integer (int32)_, required) The value of the recommendation type.  
    Example: `2`.

### VariationAttributeValue

Document representing a variation attribute value.

*   `description` (_string_) The localized description of the variation value.  
    Example: `Color of the product`.
*   `image` (_object_) The first product image for the configured viewtype and this variation value.
    
    Includes all fields of `Image`.
    
*   `imageSwatch` (_object_) The first product image for the configured viewtype and this variation value (typically the swatch image).
    
    Includes all fields of `Image`.
    
*   `name` (_string_) The localized display name of the variation value.  
    Example: `Red`.
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.  
    Example: `true`.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1. Example: `red`.

### ShippingPromotion

Document representing a shipping promotion.

*   `calloutMsg` (_string_) The localized callout message of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `promotionId` (_string_) The unique ID of the promotion.  
    Example: `$30FixedShippingAmountAbove150`.
*   `promotionName` (_string_) The localized promotion name.  
    Example: `$30 Fixed Shipping Amount Above 150`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ItemId

The item id.

Type: `string`.

Example: `430ef5aad3a24de59378458434`.

### OptionItem

An option item represents an optional purchase related to a product item, and is always associated with that parent product item. An option item can have different values from which to select. For example, a refrigerator item can have an option item representing an extended warranty, with a set of option item values representing different warranty lengths. When a shopper purchases the warranty option item together with the parent refrigerator item, they select one of the available warranty option item values.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.  
    Example: `ba248414e3eee797f062162f8b`.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus. It is read only.  
    Example: `false`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `false`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item. It is read only.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.  
    Example: `The item text.`.
*   `optionId` (_string_, required) The ID of the option. It is read only.  
    Maximum length: 256. Example: `consoleWarranty`.
*   `optionItems` (_array of OptionItem_) The option items.
*   `optionValueId` (_string_, required) The ID of the option value. It is read only.  
    Maximum length: 256. Example: `000`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `150.99`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `40.5`.
*   `productId` (_ProductId_)
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `quantity` (_number (double)_) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments. It is read only.  
    Example: `0`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item. It is read only.  
    Example: `50`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.19`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductListItemReference

Document representing product list item details.

*   `id` (_object_, required) The ID of the product list item. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `priority` (_integer (int32)_) The priority of the product list item.  
    Example: `1`.
*   `productDetailsLink` (_ProductDetailsLink_)
*   `productList` (_object_) A reference to the associated product list. It is read only.
    
    Includes all fields of `ProductListLink`.
    
*   `public` (_boolean_)  
    Example: `false`.
*   `purchasedQuantity` (_number (double)_) The total quantity of this item purchased from the product list.  
    Example: `0`.
*   `quantity` (_number (double)_) The number of products or gift certificates that get shipped when purchasing this product list item.  
    Minimum: 0. Example: `1`.
*   `type` (_string_) Specifies whether the item is a product or a gift certificate.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### OmsShipmentItem

Individual item within a shipment

*   `id` (_string_) Unique identifier for the shipment item  
    Example: `0OBVF000006603F4AQ`.
*   `productItemId` (_string_) Reference to the product item in the order  
    Example: `10uVF0000002fGnYAI`.
*   `quantity` (_number (double)_) Quantity of product items with the referenced productItemId in this shipment  
    Example: `2`.

### ProductListLink

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers. It is read only.  
    Example: `true`.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `shopping_list`.

<!-- document id=0f94d4962d91d89967326c35a72052a8f46f8668ffe35dfd32d23268e5d0d58c url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-delivery-estimates.md -->

Shopper Delivery Estimates

# Shopper Delivery Estimates

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-delivery-estimates/shopper-delivery-estimates-oas-v1-public.yaml)

## API Overview

Use the Shopper Delivery Estimates API to retrieve carrier-calculated delivery date ranges for a single product at a destination postal code. The API is intended for product detail pages (PDP) where shoppers want to know when an item will arrive before adding it to a basket.

For the requested product, the platform enumerates the site's applicable shipping methods. Estimates are returned only when the `sfcc.app.shipping.estimate` hook is bound to a provider via an installed Commerce App; if no provider is bound, the platform returns no estimates.

The Shopper Delivery Estimates API is currently uncached. The URL is deterministic in `productIds`, `postalCode`, and `countryCode`, and will utilize a cache layer in the future.

### Authentication & Authorization

The Shopper Delivery Estimates API requires a shopper access token.

For details on how to request an access token, see [Get a Shopper Token from SLAS](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html).

You must include `sfcc.shopper-delivery-estimates` and `sfcc.shopper-standard` in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Customization

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached. The endpoint is currently uncached even though request URLs are deterministic for `productIds`, `postalCode`, and `countryCode`; a cache layer is planned for a future release. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Show "Arrives by" on a Product Detail Page

Use this API on the PDP after a shopper enters postal code and country. The response provides delivery windows by applicable shipping method so you can display messaging such as "Arrives Fri, Oct 4."

```bash
curl -X GET \
  "https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-delivery-estimates/v1/organizations/{organizationId}/delivery-estimates?siteId={siteId}&productIds={productId}&postalCode=94105&countryCode=US" \
  -H "Authorization: Bearer {shopper_access_token}" \
  -H "Content-Type: application/json" \
  -H "correlation-id: pdp-delivery-estimate-001"
```

#### Choose Which Shipping Methods to Highlight

The response includes one entry per applicable shipping method for each product. If a method is deliverable, use the `deliveryWindow`; if it is not deliverable, use `nonDeliverableReason` to suppress or de-prioritize that method in your UI.

#### Hide the Estimate Module When No Estimates Are Available

If `productDeliveryEstimates` is empty, no estimates are available for requested products (for example, no applicable shipping methods or no provider response). In that case, hide the delivery estimate component to avoid showing incomplete or misleading delivery messaging.

### Best Practices

*   Keep calls scoped to PDP interactions, since the endpoint is currently uncached.
*   Respect the current one-product constraint (`productIds` currently supports one product per request) and avoid batching assumptions until multi-product support is released.
*   Gracefully handle partial availability by rendering only methods with delivery windows and clearly handling non-deliverable methods.
*   Ensure the `sfcc.app.shipping.estimate` hook is bound to a provider via an installed Commerce App — without a bound provider, no estimates are returned. Validate hook performance and timeout behavior to stay within the 10-second Shopper API limit.
*   Always include a `correlation-id` header for easier production troubleshooting.

### Related APIs

This API is commonly used with SLAS token APIs for shopper authentication and Shopper Products APIs for PDP data retrieval.

**Version:** 1.2.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-delivery-estimates/v1`
    *   `shortCode (default shortCode)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-delivery-estimates: scope granting read-access to shopper delivery estimates endpoints
    *   Scope sfcc.shopper-standard: scope granting read-access to standard shopper endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-delivery-estimates: scope granting read-access to shopper delivery estimates endpoints
    *   Scope sfcc.shopper-standard: scope granting read-access to standard shopper endpoints
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-delivery-estimates: scope granting read-access to shopper delivery estimates endpoints
    *   Scope sfcc.shopper-standard: scope granting read-access to standard shopper endpoints

## Operations

### GET Returns delivery date estimates for the requested product.

`GET /organizations/{organizationId}/delivery-estimates`

Operation ID: `getDeliveryEstimates`. Security: ShopperToken (sfcc.shopper-delivery-estimates, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-delivery-estimates, sfcc.shopper-standard).

Returns delivery date estimates for the requested products at a destination postal code. Currently limited to one product per request. For each requested product, the platform enumerates all applicable site-level shipping methods. Estimates are returned only when the `sfcc.app.shipping.estimate` Commerce Apps hook is bound to a provider. If no provider is bound, the platform returns no estimates. Each entry in the response corresponds to one requested product, and contains one entry per applicable shipping method. Methods for which the provider returned an estimate carry a `deliveryWindow`. Methods for which the provider could not return an estimate include a `nonDeliverableReason`. An empty `productDeliveryEstimates` array means the platform has no estimates for any of the requested products, for example, no applicable shipping methods or the provider returned no results. In this case, clients should hide the delivery estimation block.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `productIds` (query, array of ProductId, required, style: form, explode: false) The IDs of the products for which to retrieve delivery estimates. Each product must be online and site-assigned. Currently limited to one ID per request; multi-product support is reserved for a future release.  
    Minimum items: 1. Maximum items: 1.
    
    _Example_
    
    ```
    apple-ipod-shuffle
    ```
    
    _Example_
    
    ```
    [
      "apple-ipod-shuffle"
    ]
    ```
    
*   `postalCode` (query, string, required) The destination postal code for which to compute delivery estimates. Format depends on the destination country (for example, a 5-digit ZIP for US, a 6-character alphanumeric code for CA).  
    Minimum length: 1. Maximum length: 20. Example: `10001`.
    
    _Example_
    
    ```
    10001
    ```
    
*   `countryCode` (query, CountryCode, required) The destination country as an ISO 3166-1 alpha-2 country code (for example, `US`, `CA`, `GB`). Required for unambiguous resolution of the destination — postal codes are not globally unique.
    
    _Example_
    
    ```
    US
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `DeliveryEstimatesResult`.
    
    _Example: GetDeliveryEstimatesResponseExample_ Happy path — one product with two shipping options, both deliverable.
    
    ```
    {
      "productDeliveryEstimates": [
        {
          "productId": "apple-ipod-shuffle",
          "destination": {
            "postalCode": "10001",
            "countryCode": "US"
          },
          "shippingOptions": [
            {
              "shippingMethodId": "GroundShipping",
              "name": "Ground",
              "description": "Standard ground shipping",
              "carrier": "UPS",
              "price": 5.99,
              "currency": "USD",
              "deliveryWindow": {
                "startAt": "2026-04-30T14:00:00Z",
                "endAt": "2026-04-30T18:00:00Z"
              },
              "orderCutoffAt": "2026-04-27T14:00:00Z"
            },
            {
              "shippingMethodId": "TwoDayShipping",
              "name": "Two-Day",
              "description": "Expedited air shipping",
              "carrier": "UPS",
              "price": 12.99,
              "currency": "USD",
              "deliveryWindow": {
                "startAt": "2026-04-28T09:00:00Z",
                "endAt": "2026-04-28T17:00:00Z"
              },
              "orderCutoffAt": "2026-04-26T18:00:00Z"
            }
          ]
        }
      ]
    }
    ```
    
    _Example: GetDeliveryEstimatesPartialResponseExample_ One shipping option is deliverable, another is not. Methods that cannot deliver for a particular reason are kept in the response with \`nonDeliverableReason\` populated.
    
    ```
    {
      "productDeliveryEstimates": [
        {
          "productId": "apple-ipod-shuffle",
          "destination": {
            "postalCode": "10001",
            "countryCode": "US"
          },
          "shippingOptions": [
            {
              "shippingMethodId": "GroundShipping",
              "name": "Ground",
              "description": "Standard ground shipping",
              "carrier": "UPS",
              "price": 5.99,
              "currency": "USD",
              "deliveryWindow": {
                "startAt": "2026-04-30T14:00:00Z",
                "endAt": "2026-04-30T18:00:00Z"
              },
              "orderCutoffAt": "2026-04-27T14:00:00Z"
            },
            {
              "shippingMethodId": "OvernightShipping",
              "name": "Overnight",
              "description": "Priority overnight shipping",
              "carrier": "UPS",
              "nonDeliverableReason": "INSUFFICIENT_INVENTORY"
            }
          ]
        }
      ]
    }
    ```
    
    _Example: GetDeliveryEstimatesEmptyResponseExample_ No estimates available — for example, when the provider returned an empty result.
    
    ```
    {
      "productDeliveryEstimates": []
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetDeliveryEstimatesBadRequestResponseExample_ A required parameter is missing or has an invalid value.
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The 'postalCode' parameter is required."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **404** Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetDeliveryEstimatesProductNotFoundResponseExample_ The supplied \`productId\` does not resolve to an online, site-assigned product.
    
    ```
    {
      "title": "Product Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found",
      "detail": "No product with ID 'apple-ipod-shuffle' for site 'SiteGenesis' could be found.",
      "productId": "apple-ipod-shuffle",
      "siteId": "SiteGenesis"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### DeliveryEstimatesResult

Result document containing per-product delivery estimates.

*   `productDeliveryEstimates` (_array of ProductDeliveryEstimate_, required) The array of per-product delivery estimate entries, one per requested product that has estimates. The array is empty when the platform has no estimates for any of the requested products.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ProductDeliveryEstimate

Delivery estimates for one product at a destination, broken down by applicable shipping method.

*   `productId` (_ProductId_, required)
*   `destination` (_Destination_, required)
*   `shippingOptions` (_array of ShippingOption_, required) The array of shipping method estimates for the product at the destination. Each entry corresponds to one applicable shipping method.

### Destination

The normalized destination used for estimation. Echoes the values supplied on the request.

*   `postalCode` (_string_, required) The destination postal code.  
    Minimum length: 1. Maximum length: 20. Example: `10001`.
*   `countryCode` (_object_, required) The destination country as an ISO 3166-1 alpha-2 code.
    
    Includes all fields of `CountryCode`.
    

### ShippingOption

A delivery estimate for one applicable shipping method. When the provider answered with a delivery window, `deliveryWindow` is populated and `nonDeliverableReason` is omitted. When the provider answered "cannot deliver via this method", `deliveryWindow` is omitted and `nonDeliverableReason` is populated.

*   `shippingMethodId` (_string_, required) The identifier of the shipping method (matches the B2C Commerce `ShippingMethod.ID`).  
    Minimum length: 1. Maximum length: 256. Example: `GroundShipping`.
*   `name` (_string_) The localized name of the shipping method.  
    Minimum length: 1. Maximum length: 256. Example: `Ground`.
*   `description` (_string_) The localized description of the shipping method.  
    Minimum length: 1. Maximum length: 4000. Example: `Standard ground shipping`.
*   `carrier` (_string_) The carrier the provider resolved for this shipping method (for example, `UPS`, `FedEx`, `USPS`). May be omitted when the provider cannot or does not identify a single carrier.  
    Minimum length: 1. Maximum length: 256. Example: `UPS`.
*   `price` (_number (double)_) The estimated shipping cost for this shipping method, in the currency given by `currency`. May be omitted when the provider cannot or does not return a price.  
    Minimum: 0. Example: `5.99`.
*   `currency` (_object_) The ISO 4217 currency code for `price`. Defaults to the site's default currency. Omitted when `price` is omitted.
    
    Includes all fields of `CurrencyCode`.
    
*   `deliveryWindow` (_object_) The estimated delivery window for this shipping method. Omitted when `nonDeliverableReason` is set.
    
    Includes all fields of `DeliveryWindow`.
    
*   `orderCutoffAt` (_string (date-time)_) The latest timestamp by which an order must be placed for the `deliveryWindow` to apply. Clients compare this to the current time to decide whether the estimate is still valid. Omitted when not applicable. Sub-day RFC 3339 precision.  
    Example: `2026-04-27T14:00:00Z`.
*   `nonDeliverableReason` (_string_) A SCREAMING\_SNAKE\_CASE code identifying why the provider could not deliver via this shipping method. This is not localized and not intended to be shown directly to shoppers. This field may be omitted when the provider cannot or does not identify a single reason. Provider implementations may emit additional codes. Omitted when `deliveryWindow` is set.  
    Minimum length: 1. Maximum length: 256. Example: `INSUFFICIENT_INVENTORY`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### DeliveryWindow

A time window during which the delivery is expected. Both endpoints are sub-day RFC 3339 timestamps passed through unmodified from the underlying provider.

*   `startAt` (_string (date-time)_, required) The earliest expected delivery timestamp (inclusive).  
    Example: `2026-04-30T14:00:00Z`.
*   `endAt` (_string (date-time)_, required) The latest expected delivery timestamp (inclusive).  
    Example: `2026-04-30T18:00:00Z`.

<!-- document id=35f8a5a5f663fbd76cb1f89f3ba355451755f2908596a7b80fd267ddfb0f53e3 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-experience.md -->

Shopper Experience

# Shopper Experience

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-experience/shopper-experience-oas-v1-public.yaml)

## API Overview

Use the Shopper Experience API to look up page information for pages created in Page Designer, search and retrieve content assets, and access content folders.

### Authentication & Authorization

The Shopper Experience API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

You must include `sfcc.shopper-experience` in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

**Important**: Currently, the Shopper Experience Pages endpoints can’t be used when the [storefront password protection](https://help.salesforce.com/s/articleView?id=cc.b2c_storefront_password_protection.htm&type=5) feature is enabled.

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API. Page Designer uses its own visibility rules (scheduling, customer groups) to control component visibility.

#### Caching

Caching is provided for the Shopper Experience API. For details, see [Server-Side Web-Tier Caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) and [Page Designer Caching](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-designer-caching).

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get a Page Designer Page

Retrieve a Page Designer page by ID.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/experience/shopper-experience/v1/organizations/{organizationId}/pages/{pageId}?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Access Content Folders

The API provides access to content folders, which are used to organize and manage content assets. Content folders support:

*   Hierarchical organization with nested subfolders
*   Localized metadata including names, descriptions, and SEO attributes
*   Custom attributes for extended functionality
*   Configurable depth levels for subfolder retrieval (0, 1, or 2 levels)

Only content folders that are marked as online are returned in the API responses.

#### Search Content Assets

Search for content assets using keywords and refinement filters. The search functionality supports:

*   Keyword-based search across content assets
*   Refinement attributes to filter results, for example, by folder or content type
*   Sorting by configurable attributes
*   Pagination for large result sets (up to 200 items per page)

Only content assets that are online and assigned to a folder are included in search results.

#### Batch Retrieval

Retrieve multiple content assets or content folders in a single API request for improved performance (up to 50 content assets or folders at once).

### Page Responses

Responses for pages include the following:

*   The entire component hierarchy of the page at design time.
*   All merchant data provided at design time.
*   Server-side scripting data provided at run time.
*   Tracking for each rendered component or fragment using a globally unique content link UUID.
*   Support for reusable component fragments that can be shared across multiple pages.

Both the page and components contain the values of all native and custom attributes that have been populated during page authoring.

Only visible pages are returned. Because the visibility of components is driven by rules (scheduling or customer groups, for example), these rules are subject to evaluation when assembling the component hierarchy in the response. Only components that are visible for the current customer context appear in the response. The same rules apply to the page itself, which is only processed and returned if it is visible.

### Content Asset Responses

Content asset responses include:

*   Rich content including text, HTML, and images
*   SEO metadata (title, description, keywords)
*   Template information for rendering
*   Folder organization structure
*   Custom attributes and properties

Only content assets that are marked as online are returned. Content assets provide flexible content management capabilities for storefronts.

### Related APIs

*   [Experiences (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/experiences?meta=Summary) — Manage Page Designer pages and content assets.

**Version:** 1.7.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/experience/shopper-experience/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-experience: Shopper Experience scope READONLY
    *   Scope sfcc.shopper-experience.pages: Shopper Experience scope READONLY for pages
    *   Scope sfcc.shopper-experience.contents: Shopper Experience scope READONLY for contents
    *   Scope sfcc.shopper-experience.folders: Shopper Experience scope READONLY for folders
    *   Scope sfcc.shopper-experience.qualifiers: Shopper Experience scope for resolving qualifiers
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-experience: Shopper Experience scope READONLY
    *   Scope sfcc.shopper-experience.pages: Shopper Experience scope READONLY for pages
    *   Scope sfcc.shopper-experience.contents: Shopper Experience scope READONLY for contents
    *   Scope sfcc.shopper-experience.folders: Shopper Experience scope READONLY for folders
    *   Scope sfcc.shopper-experience.qualifiers: Shopper Experience scope for resolving qualifiers
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-experience: Shopper Experience scope READONLY
    *   Scope sfcc.shopper-experience.pages: Shopper Experience scope READONLY for pages
    *   Scope sfcc.shopper-experience.contents: Shopper Experience scope READONLY for contents
    *   Scope sfcc.shopper-experience.folders: Shopper Experience scope READONLY for folders
    *   Scope sfcc.shopper-experience.qualifiers: Shopper Experience scope for resolving qualifiers

## Operations

### GET Get Page Designer pages.

`GET /organizations/{organizationId}/pages`

Operation ID: `getPages`. Security: ShopperToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard).

Get Page Designer pages. The results apply the visibility rules for each page's components, such as personalization or scheduled visibility.

You must provide the `aspectTypeId` along with either a `categoryId` or a `productId`. Since you can only create one page-to-product or page-to-category assignment per aspect type, the result contains at most one element.

**Important**:

*   Currently, you can't use the Shopper Experience Pages endpoints when the [storefront password protection](https://help.salesforce.com/s/articleView?id=cc.b2c_storefront_password_protection.htm&type=5) feature is enabled.
*   Because this resource uses the GET method, you must not pass sensitive data, for example: payment card information, and must not perform transactional processes within the server-side scripts that are run for the page and components.
*   Be aware that pagecache during fingerprint calculation will only be leveraged for pages and their components that don't use visibility rules. Furthermore the pagecaching of the actual response assembly solely depends on the response instrumentation with the serverside page type and component type script implementations. For more details also see the [Page Designer Caching Guide](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-caching).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `categoryId` (query, string) Category identifier that is used for searching the page assignment. Must be provided if no `productId` is provided.  
    Maximum length: 256. Example: `home-clearance`.
*   `productId` (query, string) Product identifier that is used for searching the page assignment. Must be provided if no `categoryId` is provided.  
    Maximum length: 100. Example: `iphone11`.
*   `aspectTypeId` (query, string, required) Aspect type identifier that is used for searching the page assignment in conjunction with either the `productId` or `categoryId`.  
    Maximum length: 256. Example: `pdp`.
*   `aspectAttributes` (query, string) A JSON representation of aspect attributes. Each aspect attribute is a key/value pair. Aspect attributes serve as a runtime parameter contract between caller (for example, this API or the DWScript API) and callee (the page). This parameter must not contain more than 256 characters after URL decoding.  
    Maximum length: 256. Example: `{ "product" : "iphone11", "breadcrumbCategory" : "home-clearance" }`.
*   `parameters` (query, string) A free-form definition of parameters that influences the page rendering according to its implementation. This parameter must not contain more than 256 characters after URL decoding.  
    Maximum length: 256. Example: `refine=color,size;currency=USD;showNavigation=false`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `PageResult`.
    
    _Example: PageResult_
    
    ```
    {
      "data": [
        {
          "id": "homePpage",
          "typeId": "storePage",
          "aspectTypeId": "pdpAspect",
          "name": "Homepage",
          "description": "Home page of the storefront.",
          "pageTitle": "Homepage - My Shop",
          "pageDescription": "Get started shopping",
          "pageKeywords": "fashion, my shop",
          "data": {
            "thumbnail": "myshop.jpg"
          },
          "custom": {
            "thumbnail_full": "http://static.myshop.com/myshop.jpg"
          },
          "visible": true,
          "localized": true,
          "designMetadata": {
            "id": "storePage",
            "name": "Store Page",
            "archType": "headless"
          },
          "regions": [
            {
              "id": "header",
              "components": [
                {
                  "id": "2192f5b9aac0f2af2385f6f6b7",
                  "typeId": "commerce_assets.banner",
                  "name": "Sale Banner",
                  "fragment": false,
                  "embedded": false,
                  "contentLinkUuid": "a7b2c4d8e1f9032a5b6c7d8e9f0",
                  "data": {
                    "title": "Products On Sale",
                    "bannerImage": "sale/topsellerPromo.jpg"
                  },
                  "localized": true,
                  "visible": true,
                  "custom": {
                    "thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
                  },
                  "designMetadata": {
                    "id": "commerce_assets.banner",
                    "name": "Banner Component",
                    "archType": "headless"
                  }
                }
              ]
            },
            {
              "id": "main",
              "components": [
                {
                  "id": "5c5ebbcd2aee1a67af519c83b5",
                  "typeId": "commerce_assets.carousel",
                  "name": "Topseller Carousel",
                  "fragment": false,
                  "embedded": false,
                  "contentLinkUuid": "3f8e2a1b5c9d7e4f0a2b3c6d8e1",
                  "data": {
                    "title": "Topseller",
                    "category": "topseller"
                  },
                  "localized": true,
                  "visible": true,
                  "custom": {
                    "detailUrl": "www.myshop.com/topseller"
                  },
                  "designMetadata": {
                    "id": "commerce_assets.carousel",
                    "name": "Carousel Component",
                    "archType": "headless"
                  },
                  "regions": [
                    {
                      "id": "tiles",
                      "components": [
                        {
                          "id": "d98a30dfe93715e3e6fc22a329",
                          "typeId": "commerce_assets.productTile",
                          "fragment": true,
                          "embedded": false,
                          "contentLinkUuid": "c4d6e8f0a2b4c6d8e0f2a4b6c8d",
                          "data": {
                            "product": "iphone6"
                          },
                          "localized": false,
                          "visible": true
                        },
                        {
                          "id": "43aa39896afb9292308181ce14",
                          "typeId": "commerce_assets.productTile",
                          "fragment": false,
                          "embedded": false,
                          "contentLinkUuid": "9e1a3c5d7f0b2e4a6c8d0f2b4e6",
                          "data": {
                            "product": "iphone7"
                          },
                          "localized": true,
                          "visible": false
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "id": "detailpage",
          "typeId": "storePage",
          "name": "storepage",
          "description": "A Store page",
          "pageTitle": "A Store",
          "pageDescription": "Buy in store",
          "pageKeywords": "fashion, my shop, store",
          "data": {
            "thumbnail": "mystore.jpg"
          },
          "visible": true,
          "localized": false,
          "designMetadata": {
            "id": "storePage",
            "name": "Store Page",
            "archType": "headless"
          }
        }
      ]
    }
    ```
    
*   **400** Business Object ID Invalid
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BusinessObjectIDInvalid_
    
    ```
    {
      "title": "Business Object ID Invalid",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/business-object-id-invalid",
      "detail": "At least one provided business object identifier was invalid. This means either none was provided at all or exclusiveness of multiple identifiers wasn't honored or the referenced business object didn't exist."
    }
    ```
    
*   **404** Requested Aspect Type Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: AspectTypeNotFound_
    
    ```
    {
      "title": "Aspect Type Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/aspect-type-not-found",
      "detail": "No aspect type with ID 'pdp' was found in site 'RefArch'."
    }
    ```
    

### GET Get a Page Designer page based on a single page ID.

`GET /organizations/{organizationId}/pages/{pageId}`

Operation ID: `getPage`. Security: ShopperToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-experience, sfcc.shopper-experience.pages, sfcc.shopper-standard).

Get a Page Designer page for a specific page ID. The results apply the visibility rules for the page's components, such as personalization or scheduled visibility.

**Important**:

*   Currently, you can't use the Shopper Experience Pages endpoints when the [storefront password protection](https://help.salesforce.com/s/articleView?id=cc.b2c_storefront_password_protection.htm&type=5) feature is enabled.
*   Because this resource uses the GET method, you must not pass sensitive data, for example: payment card information, and must not perform transactional processes within the server-side scripts that are run for the page and components.
*   Be aware that pagecache during fingerprint calculation will only be leveraged for pages and their components that don't use visibility rules. Furthermore the pagecaching of the actual response assembly solely depends on the response instrumentation with the serverside page type and component type script implementations. For more details also see the [Page Designer Caching Guide](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-dev-for-page-designer.html#page-caching).

#### Parameters

*   `pageId` (path, string, required) Identifier for the requested page.  
    Maximum length: 256. Example: `homepage`.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `aspectAttributes` (query, string) A JSON representation of aspect attributes. Each aspect attribute is a key/value pair. Aspect attributes serve as a runtime parameter contract between caller (for example, this API or the DWScript API) and callee (the page). This parameter must not contain more than 256 characters after URL decoding.  
    Maximum length: 256. Example: `{ "product" : "iphone11", "breadcrumbCategory" : "home-clearance" }`.
*   `parameters` (query, string) A free-form definition of parameters that influences the page rendering according to its implementation. This parameter must not contain more than 256 characters after URL decoding.  
    Maximum length: 256. Example: `refine=color,size;currency=USD;showNavigation=false`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `Page`.
    
    _Example: Page_
    
    ```
    {
      "id": "homepage",
      "typeId": "storePage",
      "aspectTypeId": "pdpAspect",
      "name": "Homepage",
      "description": "Home page of the storefront.",
      "pageTitle": "Homepage - My Shop",
      "pageDescription": "Get started shopping",
      "pageKeywords": "fashion, my shop",
      "data": {
        "thumbnail": "myshop.jpg"
      },
      "custom": {
        "thumbnail_full": "http://static.myshop.com/myshop.jpg"
      },
      "visible": true,
      "localized": true,
      "designMetadata": {
        "id": "storePage",
        "name": "Store Page",
        "archType": "headless"
      },
      "regions": [
        {
          "id": "header",
          "components": [
            {
              "id": "375b9107b067902827083772f9",
              "typeId": "commerce_assets.banner",
              "name": "Sale Banner",
              "fragment": false,
              "embedded": false,
              "contentLinkUuid": "2b4d6f8a0c2e4a6b8d0f2a4c6e8",
              "data": {
                "title": "Products On Sale",
                "bannerImage": "sale/topsellerPromo.jpg"
              },
              "localized": true,
              "visible": true,
              "custom": {
                "thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
              },
              "designMetadata": {
                "id": "commerce_assets.banner",
                "name": "Banner Component",
                "archType": "headless"
              }
            }
          ]
        },
        {
          "id": "main",
          "components": [
            {
              "id": "be1f331b92d8ad7e38e440e35d",
              "typeId": "commerce_assets.carousel",
              "fragment": false,
              "embedded": false,
              "contentLinkUuid": "f0a2c4e6b8d0f2a4c6e8b0d2f4",
              "data": {
                "title": "Topseller",
                "category": "topseller"
              },
              "localized": true,
              "visible": true,
              "custom": {
                "detailUrl": "www.myshop.com/topseller"
              },
              "regions": [
                {
                  "id": "tiles",
                  "components": [
                    {
                      "id": "45af07459684e6db78990c5d05",
                      "typeId": "commerce_assets.productTile",
                      "fragment": false,
                      "embedded": false,
                      "contentLinkUuid": "5d7f1a3b5c7e9f0a2c4d6e8f0a2",
                      "data": {
                        "product": "iphone6"
                      },
                      "localized": false,
                      "visible": true
                    },
                    {
                      "id": "df6e33766d90e7e205d109aa2f",
                      "typeId": "commerce_assets.productTile",
                      "fragment": false,
                      "embedded": false,
                      "contentLinkUuid": "e8b0d2f4a6c8e0b2d4f6a8c0e2b",
                      "data": {
                        "product": "iphone7"
                      },
                      "localized": true,
                      "visible": false
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Invalid Query Parameter
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: AspectAttributeInvalid_
    
    ```
    {
      "title": "Aspect Attribute Invalid",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/aspect-attribute-invalid",
      "detail": "Aspect attribute value \"5555\" does not fulfill its respective definition {\"id\" : \"foobar\", \"type\" : \"string\",\"required\" : \"false\"}"
    }
    ```
    
*   **401** Unauthorized Access
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
*   **404** Requested Page Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: PageNotFound_
    
    ```
    {
      "title": "Page Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/page-not-found",
      "detail": "No visible page with ID 'homepage' was found in site 'RefArch'."
    }
    ```
    

### GET Get a component by ID.

`GET /organizations/{organizationId}/components/{componentId}`

Operation ID: `getComponent`. Security: ShopperToken (sfcc.shopper-experience, sfcc.shopper-experience.pages); ShopperClientContextToken (sfcc.shopper-experience, sfcc.shopper-experience.pages).

Get a Page Designer component by its unique identifier. The results apply the visibility rules for the component, such as personalization or scheduled visibility.

**Important**:

*   Because this resource uses the GET method, you must not pass sensitive data, for example: payment card information, and must not perform transactional processes within the server-side scripts that are run for the component.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `componentId` (path, string, required) Identifier for the requested component.  
    Maximum length: 256. Example: `be1f331b92d8ad7e38e440e35d`.
*   `parameters` (query, string) A free-form definition of parameters that influences the page rendering according to its implementation. This parameter must not contain more than 256 characters after URL decoding.  
    Maximum length: 256. Example: `refine=color,size;currency=USD;showNavigation=false`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `Component`.
    
    _Example: Component_
    
    ```
    {
      "id": "be1f331b92d8ad7e38e440e35d",
      "typeId": "commerce_assets.carousel",
      "name": "Topseller Carousel",
      "fragment": false,
      "embedded": false,
      "contentLinkUuid": "f0a2c4e6b8d0f2a4c6e8b0d2f4",
      "data": {
        "title": "Topseller",
        "category": "topseller"
      },
      "localized": true,
      "visible": true,
      "custom": {
        "detailUrl": "www.myshop.com/topseller"
      },
      "designMetadata": {
        "id": "commerce_assets.carousel",
        "name": "Carousel Component",
        "archType": "headless"
      },
      "regions": [
        {
          "id": "tiles",
          "components": [
            {
              "id": "45af07459684e6db78990c5d05",
              "typeId": "commerce_assets.productTile",
              "name": "iPhone 6 Tile",
              "fragment": false,
              "embedded": false,
              "contentLinkUuid": "5d7f1a3b5c7e9f0a2c4d6e8f0a2",
              "data": {
                "product": "iphone6"
              },
              "localized": false,
              "visible": true
            },
            {
              "id": "df6e33766d90e7e205d109aa2f",
              "typeId": "commerce_assets.productTile",
              "name": "iPhone 7 Tile",
              "fragment": false,
              "embedded": false,
              "contentLinkUuid": "e8b0d2f4a6c8e0b2d4f6a8c0e2b",
              "data": {
                "product": "iphone7"
              },
              "localized": true,
              "visible": true
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Invalid Parameter
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ComponentBadRequest_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "The provided 'componentId' is invalid or missing required query parameter 'siteId'."
    }
    ```
    
*   **401** Unauthorized Access
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
*   **404** Component Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ComponentNotFound_
    
    ```
    {
      "title": "Component Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/component-not-found",
      "detail": "No visible component with ID 'rfdvj4ojtltljw3' was found in site 'RefArch'."
    }
    ```
    
*   **500** Internal Server Error
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ComponentInternalError_
    
    ```
    {
      "title": "Internal Server Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/internal-server-error",
      "detail": "An unexpected error occurred while processing the request."
    }
    ```
    

### GET Get a content asset by ID.

`GET /organizations/{organizationId}/contents/{id}`

Operation ID: `getContent`. Security: ShopperToken (sfcc.shopper-experience.contents); ShopperClientContextToken (sfcc.shopper-experience.contents).

Get a content asset by its unique identifier. Only content assets that are marked as online are returned.

Content assets contain rich content that can be displayed on storefronts, including text, HTML, images, and custom attributes.

**Important**:

*   Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, ContentId, required) Identifier for the requested content asset.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `Content`.
    
    _Example: Content_
    
    ```
    {
      "id": "homepage-banner",
      "name": "Homepage Banner",
      "description": "Main promotional banner for the homepage",
      "pageTitle": "Homepage Banner - My Shop",
      "pageDescription": "Discover amazing products at great prices",
      "pageKeywords": "banner, promotion, homepage"
    }
    ```
    
*   **404** Content Asset Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ContentNotFound_
    
    ```
    {
      "title": "Content Asset Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/content-not-found",
      "detail": "No visible content asset with ID 'homepage-banner' was found in site 'RefArch'."
    }
    ```
    

### GET Get multiple content assets.

`GET /organizations/{organizationId}/contents`

Operation ID: `getMultipleContent`. Security: ShopperToken (sfcc.shopper-experience.contents); ShopperClientContextToken (sfcc.shopper-experience.contents).

Get multiple content assets by their identifiers. Only content assets that are marked as online are returned.

This endpoint allows you to retrieve multiple content assets in a single request, which is more efficient than making multiple individual requests.

**Important**:

*   Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `ids` (query, array of ContentId, required, style: form, explode: false) Comma-separated list of content asset identifiers to retrieve.  
    Minimum items: 1. Maximum items: 50.
    
    _Example_
    
    ```
    homepage-banner,footer-content,sidebar-promo
    ```
    
    _Example_
    
    ```
    [
      "homepage-banner",
      "footer-content",
      "sidebar-promo"
    ]
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `ContentResult`.
    
    _Example: ContentResult_
    
    ```
    {
      "data": [
        {
          "id": "homepage-banner",
          "name": "Homepage Banner",
          "description": "Main promotional banner for the homepage",
          "pageTitle": "Homepage Banner - My Shop",
          "pageDescription": "Discover amazing products at great prices",
          "pageKeywords": "banner, promotion, homepage"
        },
        {
          "id": "footer-content",
          "name": "Footer Content",
          "description": "Footer information and links",
          "pageTitle": "Footer - My Shop",
          "pageDescription": "Footer content with links and copyright information",
          "pageKeywords": "footer, links, copyright"
        }
      ],
      "total": 2,
      "limit": 2
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetContentsBadRequest_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "'ids' violates the value constraint. The expected value is between '(0..50)'.",
      "parameter": "ids",
      "expected": "(0..50)"
    }
    ```
    

### GET Search for content assets.

`GET /organizations/{organizationId}/content-search`

Operation ID: `searchContent`. Security: ShopperToken (sfcc.shopper-experience.contents); ShopperClientContextToken (sfcc.shopper-experience.contents).

Provides keyword and refinement search functionality for content assets. The search result contains only content that is online and assigned to a folder.

**Refinement Parameters:** The following system refinement attribute IDs are supported:

*   `fdid`: Allows refinement per single content folder ID. Multiple folder IDs are not supported.

**Important**:

*   Because this resource uses the GET method, you must not pass sensitive data and must not perform transactional processes.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `q` (query, string) The query phrase to search for content assets. For example, to search for content with "banner", type q=banner.  
    Minimum length: 1. Maximum length: 50. Example: `banner`.
*   `refine` (query, string, style: form, explode: true)
    
    Parameter that represents a refinement attribute/value(s) pair. Refinement attribute ID and value(s) are separated by '='. Multiple values are supported by a subset of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"). Value ranges can be specified like this: refine=foo=(100..500). Multiple refine parameters can be provided by adding an underscore in combination with an integer counter right behind the parameter name and a counter range 1..9. I.e. refine\_1=c\_refinementType=type1|type2|type3.
    
    The following system refinement attribute IDs are supported:
    
    *   `fdid`: Allows refinement per single content folder ID. Multiple folder IDs are not supported.
    
      
    Maximum length: 256. Example: `fdid=homepage-folder`.
*   `sort` (query, string, style: form, explode: true)
    
    Parameter that represents a sorting attribute/value(s) pair. Sorting attribute ID and value are separated by '='. The value describes the sort direction. Possible values are 'asc' and 'desc', for ascending or descending sort direction. I.e. sort=c\_myAttribute=desc.
    
    Precondition: You have to select your sorting attributes in Business Manager > YourSite > Search Indexes > Content Index > Sorting Attributes.
    
      
    Maximum length: 256. Example: `name=asc`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50.  
    Default: `50`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `ContentSearchResult`.
    
    _Example: ContentSearchResult_
    
    ```
    {
      "query": "banner",
      "hits": [
        {
          "id": "homepage-banner",
          "name": "Homepage Banner",
          "description": "Main promotional banner for the homepage",
          "pageTitle": "Homepage Banner - My Shop",
          "pageDescription": "Discover amazing products at great prices",
          "pageKeywords": "banner, promotion, homepage"
        },
        {
          "id": "sidebar-banner",
          "name": "Sidebar Banner",
          "description": "Promotional banner for the sidebar",
          "pageTitle": "Sidebar Banner - My Shop",
          "pageDescription": "Check out our special offers",
          "pageKeywords": "banner, sidebar, promotion"
        }
      ],
      "selectedRefinements": {
        "fdid": "homepage-folder",
        "c_contentType": "banner"
      },
      "refinements": [
        {
          "attributeId": "c_contentType",
          "label": "Content Type",
          "values": [
            {
              "value": "banner",
              "label": "Banner",
              "hitCount": 15
            },
            {
              "value": "text",
              "label": "Text Content",
              "hitCount": 8
            }
          ]
        },
        {
          "attributeId": "fdid",
          "label": "Content Folder",
          "values": [
            {
              "value": "homepage-folder",
              "label": "Homepage",
              "hitCount": 5
            },
            {
              "value": "promotions-folder",
              "label": "Promotions",
              "hitCount": 10
            }
          ]
        }
      ],
      "total": 2,
      "limit": 25,
      "offset": 0
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ContentSearchBadRequest_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Invalid refinement parameter format. Expected format: 'attribute=value'.",
      "parameter": "refine"
    }
    ```
    

### GET Get content folder

`GET /organizations/{organizationId}/folders/{id}`

Operation ID: `getContentFolder`. Security: ShopperToken (sfcc.shopper-experience.folders); ShopperClientContextToken (sfcc.shopper-experience.folders).

To access a content folder, you construct a URL using the template shown below. This template requires you to specify a content folder id and a subfolder level. In response, the server returns a corresponding content folder document. Only content folders which are marked as online are returned.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, FolderId, required) Identifier for the requested content folder.
*   `levels` (query, integer) Specifies how many levels of nested subfolders you want the server to return. The default value is 1. Valid values are 0, 1, or 2.  
    Default: `1`. Minimum: 0. Maximum: 2. Example: `1`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `ContentFolder`.
    
    _Example: ContentFolder_
    
    ```
    {
      "id": "homepage-folder",
      "parentFolderId": "root-folder",
      "name": "Homepage Folder",
      "description": "Folder containing homepage content assets",
      "pageTitle": "Homepage Folder - My Store",
      "pageDescription": "SEO description for homepage folder",
      "pageKeywords": "homepage, main, landing",
      "folders": [
        {
          "id": "hero-section",
          "parentFolderId": "homepage-folder",
          "name": "Hero Section",
          "description": "Hero section content folder",
          "folders": []
        },
        {
          "id": "featured-products",
          "parentFolderId": "homepage-folder",
          "name": "Featured Products",
          "description": "Featured products content folder",
          "folders": []
        }
      ],
      "c_customAttribute": "customValue"
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidLevelsParameter_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "'levels' violates the value constraint. The expected value is between '(0..2)'."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Folder Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ContentFolderNotFound_
    
    ```
    {
      "title": "Folder Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/folder-not-found",
      "detail": "No online content folder with ID 'non-existent-folder' for site 'RefArch' could be found."
    }
    ```
    

### GET Get multiple content folders

`GET /organizations/{organizationId}/folders`

Operation ID: `getContentFolders`. Security: ShopperToken (sfcc.shopper-experience.folders); ShopperClientContextToken (sfcc.shopper-experience.folders).

To access one or more content folders, you construct a URL using the template shown below. This template requires you to specify one or more content folder ids as a query parameter and a subfolder level. In response, the server returns a result set of corresponding content folder documents. Only content folders which are marked as online are returned.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `ids` (query, array of object, required, style: form, explode: false) Comma-separated list of content folder identifiers.  
    Minimum items: 1. Maximum items: 50.
    
    _Example_
    
    ```
    homepage-folder,category-folder,product-folder
    ```
    
    _Example_
    
    ```
    [
      "homepage-folder",
      "category-folder",
      "product-folder"
    ]
    ```
    
*   `levels` (query, integer) Specifies how many levels of nested subfolders you want the server to return. The default value is 1. Valid values are 0, 1, or 2.  
    Default: `1`. Minimum: 0. Maximum: 2. Example: `1`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success
    
    Media type: `application/json`. Schema: `ContentFolderResult`.
    
    _Example: ContentFolderResult_
    
    ```
    {
      "limit": 2,
      "total": 10,
      "data": [
        {
          "id": "homepage-folder",
          "parentFolderId": "root-folder",
          "name": "Homepage Folder",
          "description": "Folder containing homepage content assets",
          "pageTitle": "Homepage Folder - My Store",
          "pageDescription": "SEO description for homepage folder",
          "pageKeywords": "homepage, main, landing",
          "folders": [
            {
              "id": "hero-section",
              "parentFolderId": "homepage-folder",
              "name": "Hero Section",
              "description": "Hero section content folder",
              "folders": []
            },
            {
              "id": "featured-products",
              "parentFolderId": "homepage-folder",
              "name": "Featured Products",
              "description": "Featured products content folder",
              "folders": []
            }
          ],
          "c_customAttribute": "customValue"
        },
        {
          "id": "category-folder",
          "parentFolderId": "root-folder",
          "name": "Category Folder",
          "description": "Folder containing category content assets",
          "pageTitle": "Category Folder - My Store",
          "pageDescription": "SEO description for category folder",
          "pageKeywords": "category, products, listing",
          "folders": []
        }
      ]
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InvalidLevelsParameter: same as GET /organizations/{organizationId}/folders/{id} 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### POST Resolve qualifiers for customer groups, campaign promotions, and data binding contexts.

`POST /organizations/{organizationId}/qualifiers/resolve`

Operation ID: `resolveQualifiers`. Security: ShopperToken (sfcc.shopper-experience.qualifiers); ShopperClientContextToken (sfcc.shopper-experience.qualifiers).

Resolves a list of customer groups, campaigns, promotions, and data bindings for the given user.

The endpoint takes each value and determines whether the user is active for the item:

*   Customer groups are verified against the user's qualification via the EffectiveContext.
*   Campaign qualifiers are checked to determine if the user is applicable for each campaign and promotion.
*   Data bindings are resolved by fetching the requested records from their respective data providers.

Returns a boolean result for each provided qualifier and resolved data binding objects grouped by provider type and record identifier. If a qualifier cannot be validated, `false` is returned for that item. If a data binding cannot be resolved, it is omitted from the response.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `QualifierResolveRequest`.

_Example: QualifierResolveRequest_

```
{
  "customerGroups": [
    "VIP"
  ],
  "campaignQualifiers": [
    {
      "campaignId": "my-campaign",
      "promotionId": "my-promotion"
    },
    {
      "campaignId": "winter-promo"
    }
  ],
  "dataBindings": [
    {
      "type": "content_asset",
      "id": "homepage-banner"
    }
  ]
}
```

#### Responses

*   **200** Success. All qualifiers have been resolved.
    
    Media type: `application/json`. Schema: `QualifierResolveResponse`.
    
    _Example: QualifierResolveResponse_
    
    ```
    {
      "customerGroups": {
        "VIP": true
      },
      "campaignQualifiers": {
        "my-campaign": {
          "my-promotion": false
        }
      },
      "campaigns": {
        "winter-promo": false
      },
      "dataBindings": {
        "content_asset": {
          "homepage-banner": {
            "title": "Winter Sale",
            "body": "<div>Shop our winter collection</div>",
            "showCountdown": true,
            "endDate": "2026-03-31T23:59:59Z"
          }
        }
      }
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: QualifierResolveBadRequest_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Invalid request body. The 'campaignQualifiers' array contains entries missing the required field 'campaignId'."
    }
    ```
    
    _Example: QualifierResolveTooManyItems_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "'campaignQualifiers' violates the value constraint. The expected value is between '(0..50)'."
    }
    ```
    
    _Example: QualifierResolveInvalidIdentifier_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Invalid request body. The 'customerGroups' array contains empty or invalid identifiers."
    }
    ```
    
    _Example: QualifierResolveInvalidDataBindingType_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Invalid request body. The 'dataBindings' array contains entries missing the required 'type' field."
    }
    ```
    
    _Example: QualifierResolveInvalidDataBindingId_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Invalid request body. The 'dataBindings' array contains entries missing the required 'id' field."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### PageResult

*   `data` (_array of Page_, required)
    
    Data
    
    List of pages.
    

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### Page

*   `id` (_string_, required)
    
    ID
    
    Page identifier.
    
      
    Maximum length: 256. Example: `homepage`.
*   `typeId` (_string_, required)
    
    Page Type ID
    
    Page type identifier.
    
      
    Maximum length: 256. Example: `storePage`.
*   `aspectTypeId` (_string_)
    
    Aspect Type ID
    
    The aspect type assigned to the page.
    
      
    Maximum length: 256. Example: `pdpAspect`.
*   `name` (_string_)
    
    Page Name
    
    Display name of the page.
    
      
    Maximum length: 4000. Example: `Homepage`.
*   `description` (_string_)
    
    Page Description
    
    Description of the page.
    
      
    Maximum length: 4000. Example: `Home page of the storefront.`.
*   `pageTitle` (_string_)
    
    SEO Title
    
    The SEO title of the page.
    
      
    Maximum length: 4000. Example: `Homepage - My Shop`.
*   `pageDescription` (_string_)
    
    SEO Description
    
    The SEO description of the page.
    
      
    Maximum length: 4000. Example: `Get started shopping`.
*   `pageKeywords` (_string_)
    
    SEO Keywords
    
    The SEO keywords of the page.
    
      
    Maximum length: 4000. Example: `fashion, my shop`.
*   `data` (_object_)
    
    Page Data
    
    The configuration data assigned to the page.
    
    _Example_
    
    ```
    {
      "thumbnail": "myshop.jpg"
    }
    ```
    
*   `custom` (_object_)
    
    Custom Page Data
    
    Any custom data added by the custom code for the page type.
    
    _Example_
    
    ```
    {
      "thumbnail_full": "http://static.myshop.com/myshop.jpg"
    }
    ```
    
*   `visible` (_boolean_)
    
    Visibility
    
    Whether the page is visible based on the current visiblity rules and context.
    
      
    Example: `true`.
*   `localized` (_boolean_)
    
    Localized
    
    Whether the page has been localized with content in the current locale. If false, the page content will fallback to the default locale.
    
      
    Example: `true`.
*   `designMetadata` (_object_)
    
    Design Metadata
    
    Design metadata of the page. This includes information about the page type definition needed by the page designer for design-time functionality.
    
    _Example_
    
    ```
    {
      "id": "storePage",
      "name": "Store Page",
      "archType": "headless"
    }
    ```
    
*   `regions` (_array of Region_)
    
    Regions
    
    The regions (and their assigned components) for the page.
    
    _Example_
    
    ```
    [
      {
        "id": "header",
        "components": [
          {
            "id": "iofwj38fhw3f",
            "typeId": "commerce_assets.banner",
            "data": {
              "title": "Products On Sale",
              "bannerImage": "sale/topsellerPromo.jpg"
            },
            "custom": {
              "thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
            }
          }
        ]
      },
      {
        "id": "main",
        "components": [
          {
            "id": "rfdvj4ojtltljw3",
            "typeId": "commerce_assets.carousel",
            "data": {
              "title": "Topseller",
              "category": "topseller"
            },
            "custom": {
              "detailUrl": "www.myshop.com/topseller"
            },
            "regions": [
              {
                "id": "tiles",
                "components": [
                  {
                    "id": "w3reö9wsjf3",
                    "typeId": "commerce_assets.productTile",
                    "data": {
                      "product": "iphone6"
                    }
                  },
                  {
                    "id": "cgn8d4ngdl4n",
                    "typeId": "commerce_assets.productTile",
                    "data": {
                      "product": "iphone7"
                    }
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "id": "footer",
        "components": []
      }
    ]
    ```
    

### Component

*   `id` (_string_, required)
    
    ID
    
    Component identifier.
    
      
    Maximum length: 256. Example: `rfdvj4ojtltljw3`.
*   `typeId` (_string_, required)
    
    Component Type ID
    
    Component type identifier.
    
      
    Maximum length: 256. Example: `commerce_assets.carousel`.
*   `name` (_string_)
    
    Component Name
    
    Display name of the component.
    
      
    Maximum length: 256. Example: `Topseller Carousel`.
*   `fragment` (_boolean_)
    
    Fragment
    
    Indicates whether the component is a fragment. True if the component is a fragment, otherwise false.
    
      
    Example: `false`.
*   `embedded` (_boolean_)
    
    Embedded
    
    Indicates whether the component is embedded in another component. True if the component is embedded, otherwise false.
    
      
    Example: `false`.
*   `contentLinkUuid` (_string_)
    
    Content Link UUID
    
    Represents a globally unique identifier for every instance of a content component (or fragment) rendered on a page.
    
      
    Maximum length: 256. Example: `0e1f329d4ac66ff2c3bbf70301`.
*   `data` (_object_)
    
    Component Data
    
    The configuration data assigned to the component.
    
    _Example_
    
    ```
    {
      "title": "Topseller",
      "category": "topseller"
    }
    ```
    
*   `localized` (_boolean_)
    
    Localized
    
    Whether the component has been localized with content in the current locale. If false, the components content will fallback to the default locale.
    
      
    Example: `true`.
*   `visible` (_boolean_)
    
    Visibility
    
    Whether the component is visible based on the current visiblity rules and context.
    
      
    Example: `true`.
*   `custom` (_object_)
    
    Custom Component Data
    
    Any custom data added by the custom code for this component.
    
    _Example_
    
    ```
    {
      "detailUrl": "www.myshop.com/topseller"
    }
    ```
    
*   `designMetadata` (_object_)
    
    Design Metadata
    
    Design metadata of the component. This includes information about the component type definition needed by the page designer for design-time functionality.
    
    _Example_
    
    ```
    {
      "id": "commerce_assets.carousel",
      "name": "Carousel Component",
      "archType": "headless"
    }
    ```
    
*   `regions` (_array of Region_)
    
    Regions
    
    The regions (and their assigned components) for the component.
    
    _Example_
    
    ```
    [
      {
        "id": "tiles",
        "components": [
          {
            "id": "w3reö9wsjf3",
            "typeId": "commerce_assets.productTile",
            "data": {
              "product": "iphone6"
            }
          },
          {
            "id": "cgn8d4ngdl4n",
            "typeId": "commerce_assets.productTile",
            "data": {
              "product": "iphone7"
            }
          }
        ]
      }
    ]
    ```
    

### ContentId

The id of the content asset.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `homepage-banner`.

### Content

*   `id` (_object_, required) ID
    
    Includes all fields of `ContentId`.
    
*   `name` (_string_)
    
    Name
    
    The localized content asset name.
    
      
    Maximum length: 4000. Example: `Homepage Banner`.
*   `description` (_string_)
    
    Description
    
    The localized content asset description.
    
      
    Maximum length: 4000. Example: `Main banner displayed on the homepage`.
*   `pageDescription` (_string_)
    
    Page Description
    
    The localized content asset page description for SEO.
    
      
    Maximum length: 4000. Example: `Discover our latest products and offers`.
*   `pageKeywords` (_string_)
    
    Page Keywords
    
    The localized content asset page keywords for SEO.
    
      
    Maximum length: 4000. Example: `products, offers, sale, fashion`.
*   `pageTitle` (_string_)
    
    Page Title
    
    The localized content asset page title for SEO
    
      
    Maximum length: 4000. Example: `Shop Now - Best Deals`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ContentResult

Includes all fields of `ResultBase`.

*   `data` (_array of Content_, required)
    
    Data
    
    List of content assets.
    

### ContentSearchResult

Includes all fields of `PaginatedResultBase`.

*   `query` (_string_)
    
    Query
    
    The query String that was searched for.
    
      
    Maximum length: 256. Example: `banner`.
*   `hits` (_array of Content_, required)
    
    Content Hits
    
    The sorted array of search hits. Can be empty.
    
*   `selectedRefinements` (_object_)
    
    Selected Refinements
    
    Map of selected refinement attribute id/value(s) pairs. The sorting order is the same like in request URL.
    
    Additional properties: `string`.
    
    Maximum length: 256. Example: `homepage-folder`.
    
    _Example_
    
    ```
    {
      "fdid": "homepage-folder",
      "c_contentType": "banner"
    }
    ```
    
*   `refinements` (_array of ContentSearchRefinement_)
    
    Refinements
    
    The sorted array of search refinements. Can be empty.
    

### FolderId

Type: `string`.

Maximum length: 256. Example: `homepage-folder`.

### ContentFolder

*   `id` (_string_, required)
    
    ID
    
    The id of the content folder.
    
      
    Maximum length: 256. Example: `homepage-folder`.
*   `parentFolderId` (_string_)
    
    Parent Folder ID
    
    The id of the parent content folder.
    
      
    Maximum length: 256. Example: `root-folder`.
*   `name` (_string_)
    
    Name
    
    The localized content folder name.
    
      
    Maximum length: 4000. Example: `Homepage Folder`.
*   `description` (_string_)
    
    Description
    
    The localized content folder description.
    
      
    Maximum length: 4000. Example: `Folder containing homepage content assets`.
*   `pageDescription` (_string_)
    
    Page Description
    
    The localized content folder page description.
    
      
    Maximum length: 4000. Example: `SEO description for homepage folder`.
*   `pageKeywords` (_string_)
    
    Page Keywords
    
    The localized content folder page keywords.
    
      
    Maximum length: 4000. Example: `homepage, main, landing`.
*   `pageTitle` (_string_)
    
    Page Title
    
    The localized content folder page title.
    
      
    Maximum length: 4000. Example: `Homepage Folder - My Store`.
*   `folders` (_array of ContentFolder_)
    
    Folders
    
    The array of content subfolders. This array can be empty.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ContentFolderResult

Includes all fields of `ResultBase`.

*   `data` (_array of ContentFolder_, required)
    
    Data
    
    List of content folders.
    

### QualifierResolveRequest

Request body for resolving customer group qualifications, campaign promotion eligibility, and data bindings. All fields are optional. An empty body is valid and returns an empty response.

*   `customerGroups` (_array of string_)
    
    Customer Groups
    
    List of customer group identifiers to resolve qualification for.
    
      
    Items: Minimum length: 1. Maximum length: 256. Example: `VIP`. Maximum items: 50.
    
    _Example_
    
    ```
    [
      "VIP"
    ]
    ```
    
*   `campaignQualifiers` (_array of CampaignQualifier_)
    
    Campaign Qualifiers
    
    List of campaign qualifiers to resolve. Each qualifier must include a campaignId and may optionally include a promotionId.
    
      
    Maximum items: 50.
*   `dataBindings` (_array of DataBindingRequirement_)
    
    Data Bindings
    
    List of data binding requirements to resolve, each specifying a provider type and record identifier.
    
      
    Maximum items: 50.

### QualifierResolveResponse

Response containing the resolved qualification results for customer groups, campaign qualifiers, and data bindings.

*   `customerGroups` (_object_)
    
    Customer Groups
    
    Map of customer group identifiers to their qualification status. True if the user is qualified, false otherwise.
    
    Additional properties: `boolean`.
    
    Example: `true`.
    
    _Example_
    
    ```
    {
      "VIP": true
    }
    ```
    
*   `campaignQualifiers` (_object_)
    
    Campaign Qualifiers
    
    Map of campaign ID to promotion qualification results. Each value is a map of promotion ID to qualification result. Only contains entries for request qualifiers that included a promotionId.
    
    Additional properties: `object`.
    
    Additional properties: `boolean`.
    
    Example: `false`.
    
    _Example_
    
    ```
    {
      "my-campaign": {
        "my-promotion": false
      }
    }
    ```
    
*   `campaigns` (_object_)
    
    Campaigns
    
    Map of campaign ID to qualification result for request qualifiers that did not include a promotionId. A value of true means the campaign is active and its scenario rule applies to the shopper context.
    
    Additional properties: `boolean`.
    
    Example: `false`.
    
    _Example_
    
    ```
    {
      "winter-promo": false
    }
    ```
    
*   `dataBindings` (_object_)
    
    Data Bindings
    
    Resolved data binding objects grouped by provider type, then by record identifier. Used by the expression resolver to evaluate attribute expressions.
    
    Additional properties: `object`.
    
    Additional properties: `object`.
    
    _Example_
    
    ```
    {
      "content_asset": {
        "homepage-banner": {
          "title": "Winter Sale",
          "body": "<div>Shop our winter collection</div>",
          "showCountdown": true,
          "endDate": "2026-03-31T23:59:59Z"
        }
      }
    }
    ```
    

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### Region

*   `id` (_string_, required)
    
    ID
    
    Region identifier.
    
      
    Maximum length: 256. Example: `header`.
*   `components` (_array of Component_)
    
    Components
    
    The components in the region.
    
    _Example_
    
    ```
    [
      {
        "id": "iofwj38fhw3f",
        "typeId": "commerce_assets.banner",
        "data": {
          "title": "Products On Sale",
          "bannerImage": "sale/topsellerPromo.jpg"
        },
        "custom": {
          "thumbnail_full": "http://static.myshop.com/sale/topsellerPromo.jpg"
        }
      }
    ]
    ```
    

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### ContentSearchRefinement

*   `attributeId` (_string_, required)
    
    Attribute ID
    
    The ID of the refinement attribute.
    
      
    Maximum length: 256. Example: `c_contentType`.
*   `label` (_string_)
    
    Label
    
    The localized label of the refinement attribute.
    
      
    Maximum length: 4000. Example: `Content Type`.
*   `values` (_array of ContentSearchRefinementValue_)
    
    Values
    
    The array of refinement values.
    

### CampaignQualifier

A campaign qualifier, optionally scoped to a specific promotion within the campaign. When promotionId is omitted, the qualifier matches if the campaign itself is active and its scenario rule applies.

*   `campaignId` (_string_, required)
    
    Campaign ID
    
    The campaign identifier.
    
      
    Minimum length: 1. Maximum length: 256. Example: `my-campaign`.
*   `promotionId` (_string_)
    
    Promotion ID
    
    Optional promotion identifier. When provided, qualification requires both the campaign and the specific promotion-campaign assignment to apply.
    
      
    Minimum length: 1. Maximum length: 256. Example: `my-promotion`.

### DataBindingRequirement

A data binding requirement specifying a provider type and record identifier to resolve.

*   `type` (_string_, required)
    
    Type
    
    The data provider type identifier.
    
      
    Minimum length: 1. Maximum length: 256. Example: `content_asset`.
*   `id` (_string_, required)
    
    ID
    
    The record identifier to resolve from the data provider.
    
      
    Minimum length: 1. Maximum length: 256. Example: `homepage-banner`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### ContentSearchRefinementValue

*   `label` (_string_)
    
    Label
    
    The localized label of the refinement value.
    
      
    Maximum length: 4000. Example: `Banner`.
*   `value` (_string_, required)
    
    Value
    
    The refinement value.
    
      
    Maximum length: 256. Example: `banner`.
*   `hitCount` (_integer_)
    
    Hit Count
    
    The number of search hits when this refinement value is applied.
    
      
    Minimum: 0. Example: `5`.

<!-- document id=65d0072f9b3d12f853ea4c9304b2cc76f144e6bb558191f1c28a94fa91302947 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-geolocation.md -->

# Shopper Geolocation

Geolocation plays a crucial role in providing personalized experiences based on shopper location. Use this guide to integrate [Shopper Context API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) geolocation features with your storefront for enhanced shopper experiences.

With B2C Commerce version 24.7, work with geolocation information in the following ways:

- Look up a shopper's location using the client's IP address.
- Look up a shopper's location using the client's IP address and use that information to set context for subsequent requests.
- Manually provide a location and use that information in subsequent requests.

**note:** - When you use SCAPI to retrieve geolocation information, the client's IP address is used to retrieve geolocation information from the B2C Commerce platform, and the IP lookup is based on your database information. For details, see [Geolocation Lookup for IP Addresses](https://help.salesforce.com/s/articleView?id=cc.b2c_geolocation_lookup_for_ip_addresses.htm&type=5).
- An association with a location impacts future requests. For example, you have a dynamic customer group for which membership includes `request.geolocation.city == 'San Francisco'`. For the purposes of group membership evaluation, this geolocation location applies to subsequent requests for this shopper. For details, see [Customer Segmentation Via Geolocation](https://help.salesforce.com/s/articleView?id=cc.b2c_customer_segmentation_via_geolocation.htm&language=en_US&type=5).

## Enable Shopper Context

1. Log in to Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Global Preferences** > **Feature Switches**.
3. Check **Enable Shopper Context**.

## Retrieve Geolocation with Client IP Address

**important:** The SCAPI geolocation service does not support Anycast-related IP addresses. Anycast allows the same IP in multiple locations, and, therefore, can't resolve to one single location.

Using SCAPI, geolocation information is retrieved using the client's IP address to look up geolocation information in the B2C Commerce platform.

Include the `clientIp` attribute with a Shopper Context [PATCH](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=updateShopperContext) or [PUT](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=createShopperContext) request, for example:

```sh
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
	    --method 'PUT' \
	    --header 'Authorization: Bearer $TOKEN' \
	    --header 'Content-Type: application/json' \
	    --data '{ "clientIp": "13.108.0.0" }'
```

The following keys are provided in the HTTP response header `x-geolocation`, and are delimited with semicolons (;):

- CountryCode
- Country
- City
- PostalCode
- MetroCode
- Region
- RegionCode
- Latitude
- Longitude

```text
x-geolocation: CountryCode: US; Country: United States; City: San Francisco; PostalCode: 94105; MetroCode: 820; Region: San Francisco; RegionCode: CA; Latitude: 37.7749; Longitude: -122.4194
```

**note:** Consume the geolocation HTTP response header in a case insensitive way, because it can be returned as `x-geolocation` or `X-Geolocation`.

## Retrieve and Use Geolocation from Client IP

Retrieving geolocation with `clientIp` returns information, but does not impact subsequent requests. To use the location provided by `clientIp` on subsequent requests, you must specify the `evaluateContextWithClientIp` query parameter:

If `evaluateContextWithClientIp` is set to `true:`

- the `clientIP` is saved and is used with subsequent requests.

If `evaluateContextWithClientIp` is set to `false`:

- the clientIP is not saved and is not used with subsequent requests.

In both cases, the `x-geolocation` response header is returned. Null or empty values are not returned.

## Retrieve Geolocation with `geoLocation` Attribute and Set Context

You can also use the `geoLocation` attribute to set a specific context geolocation. You can collect a user’s location via native browser functionality (navigator.geolocation) or via manual user input, and send these coordinates to the Shopper Context API for site personalization.

You can manually set any combination of the following optional parameters:

- countryCode
- country
- city
- postalCode
- metroCode
- region
- regionCode
- latitude
- longitude

The following Shopper Context example request provides the `city` and `countryCode` parameters in the `geoLocation` attribute to set the geolocation information:

```json
{
   "clientIp": "12.12.12.1",
    "geoLocation": {
      "city": "Boston",
      "countryCode": "US"
    }
}
```

THe `x-geolocation` response header returned is:

```text
x-geolocation: CountryCode: US; City: Boston;
```

**important:** If you set a location using the `geoLocation` attribute in the request body, it is saved as context for subsequent requests. If both `geoLocation` and `clientIp` are set in the context, the location set with `geoLocation` takes precedence over the location resolved from the `clientIp`.

For example, let's assume the following promotion configuration:

- For New York, USA: 20% discount on women's tops.
- For Boston, USA: 15% discount on women's tops.

In the following Shopper Context request, both `clientIp` and `geoLocation` attributes are provided. In this case, the `geoLocation` value takes precedence and the response header `x-geolocation` returns the location based on the `geoLocation` attribute in the request:

```sh
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
	    --method 'PUT' \
	    --header 'Authorization: Bearer $TOKEN' \
	    --header 'Content-Type: application/json' \
	    --data '{ "clientIp": "12.12.12.1",
                "geoLocation": {
                    "countryCode": "US",
                    "country": "United States of America",
                    "city": "Boston",
                    "postalCode": "01730",
                    "metroCode": "M234",
                    "region": "NA",
                    "regionCode": "12345",
                    "latitude": 10.11,
                    "longitude": 198.34
                }
              }'
```

The following `x-geolocation` response header is returned:

```text
x-geolocation: CountryCode: US; Country: United States of America; City: Boston; PostalCode: 01730; MetroCode: M234; Region: NA; RegionCode: 12345; Latitude: 10.11; Longitude: 198.34
```

Suppose the `clientIp` 12.12.12.1 resolves to New York, USA, but because the `geoLocation` in the payload specifies Boston, US, the context is evaluated based on Boston-specific promotions, resulting in a 15% discount on women's tops.

### Prompt the User for Geolocation

In this case, you provide a prompt for the user to enter geolocation information, which you can then send to the Shopper Context API, for example:

#### Provide Latitude and Longitude

```sh
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
    --method 'PUT' \
    --header 'Authorization: Bearer $TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{ "geoLocation": { "latitude": 37.7749, "longitude": -122.4194 } }'
```

#### Provide Other Location Data

```sh
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/shopper-context/v1/organizations/$ORG/shopper-context/$USID' \
    --method 'PUT' \
    --header 'Authorization: Bearer $TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{ "geoLocation": { "countryCode": "US", "city": "San Francisco" } }'
```

## Update Geolocation For Use in Subsequent Requests

When the `geoLocation` attribute is updated in Shopper Context PATCH calls, the entire existing geolocation value is replaced, not individual property values. To make a change to the geolocation, you must send all required properties, because geolocation properties work together.

You can set a new location context using the `geoLocation` attribute in the request body. The `geoLocation` attribute contains:

- `countryCode`
- `country`
- `city`
- `postalCode`
- `metroCode`
- `region`
- `regionCode`
- `latitude`
- `longitude`

Null values are not returned.

## Geolocation with Hooks

From a Script API perspective, [dw.system.Request.getGeoLocation](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/upcoming/scriptapi/html/api/class_dw_system_Request.html#dw_system_Request_getGeolocation_DetailAnchor)` returns the following geolocation information, which is useful when using hooks:

- City: `request.geolocation.city`
- Country Name: `request.geolocation.countryName`
- Country Code: `request.geolocation.countryCode`
- Latitude: `request.geolocation.latitude`
- Longitude: `request.geolocation.longitude`
- Metro Code: `request.geolocation.metroCode`
- Postal Code: `request.geolocation.postalCode`
- Region Name: `request.geolocation.regionName`
- Region Code: `request.geolocation.regionCode`

<!-- document id=f78380db1af36a58844163b78c68164dc58a5d9b7ab05a74cc1301ef75e5382f url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-gift-certificates.md -->

Shopper Gift Certificates

# Shopper Gift Certificates

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-gift-certificates/shopper-gift-certificates-oas-v1-public.yaml)

## API Overview

Use the Shopper Gift Certificates API to obtain gift certificate details.

### Authentication & Authorization

The Shopper Gift Certificates API requires a JSON Web Token acquired via the Shopper Customers endpoint:

```
https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login
```

You must include the relevant scope(s) in the client ID used to generate the SLAS token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Request Details

#### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Retrieve a Gift Certificate

Look up a gift certificate by its code. The code is sent in the request body (not the URL) for security.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-gift-certificates/v1/organizations/{organizationId}/gift-certificate?siteId=RefArch" \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "giftCertificateCode": "GIFT-1234-ABCD" }'
```

#### Retrieve Existing Gift Certificate Details

A shopper who received a code identifying a gift certificate can use the gift certificate code to query information, such as the status or remaining balance.

### Related APIs

*   [Gift Certificates (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates?meta=Summary) — Create and manage gift certificates.

**Version:** 1.3.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-gift-certificates/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-gift-certificates: Allows read operations on shopper gift certificates
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-gift-certificates: Allows read operations on shopper gift certificates
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-gift-certificates: Allows read operations on shopper gift certificates

## Operations

### POST Retrieve an existing gift certificate.

`POST /organizations/{organizationId}/gift-certificate`

Operation ID: `getGiftCertificate`. Security: ShopperToken (sfcc.shopper-gift-certificates, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-gift-certificates, sfcc.shopper-standard).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `GiftCertificateRequest`.

_Example: Gift-Certificates_

```
{
  "giftCertificateCode": "MYGIFTCERTIFICATECODE"
}
```

#### Responses

*   **200** Gift certificate retrieved successfully.
    
    Media type: `application/json`. Schema: `GiftCertificate`.
    
    _Example: CreateGiftCertificate_ A newly issued gift certificate with full balance.
    
    ```
    {
      "amount": 100,
      "balance": 100,
      "enabled": true,
      "maskedGiftCertificateCode": "************FJWQ",
      "merchantId": "00000001",
      "recipientEmail": "jane.doe@example.com",
      "recipientName": "Jane Doe",
      "senderName": "John Smith",
      "status": "issued",
      "description": "Happy Birthday!"
    }
    ```
    
*   **404** Returned when the given gift certificate code is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GiftCertificate404_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "title": "Gift Certificate Not Found Exception",
      "detail": "The gift certificate with the provided code could not be retrieved."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### GiftCertificateRequest

Document representing a gift certificate request data.

*   `giftCertificateCode` (_string_, required) The gift certificate code.  
    Example: `MYGIFTCERTIFICATECODE`.

### GiftCertificate

Document representing a gift certificate.

*   `amount` (_number (double)_, required) The gift certificate original amount.  
    Example: `100`.
*   `balance` (_number (double)_, required) The gift certificate remaining balance.  
    Example: `100`.
*   `description` (_string_) The gift certificate description.
*   `enabled` (_boolean_, required) Is the gift certificate is enabled?  
    Example: `true`.
*   `maskedGiftCertificateCode` (_string_, required) The masked gift certificate code.  
    Example: `************FJWQ`.
*   `merchantId` (_string_, required) The merchant ID.  
    Example: `00000001`.
*   `message` (_string_) The message.
*   `recipientEmail` (_string_, required) The recipient email.  
    Example: `p@gmail.com`.
*   `recipientName` (_string_, required) The recipient name.  
    Example: `sampleuser`.
*   `senderName` (_string_, required) The sender name.  
    Example: `Salesforce Support`.
*   `status` (_string_, required) The gift certificate status.  
    Allowed values: `pending`, `issued`, `partially_redeemed`, `redeemed`. Example: `issued`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

<!-- document id=23b52f52e865ca2fd24f6de7f36fc3c3e1d4dd4b962f4d25db106a3274931d70 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/auth.md -->

Shopper Login (SLAS)

# Shopper Login (SLAS)

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/auth/auth-oas-v1-public.yaml)

## API Overview

The Shopper Login and API Access Service (SLAS) enables secure access to Commerce Cloud’s Shopper APIs for a wide range of headless commerce applications.

**Important:** Before using this API, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) in the Get Started guides and the more detailed [SLAS guides](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) for instructions on setting up a SLAS client, obtaining credentials, as well as flow and use case information.

For load shedding and rate limiting information, see [Load Shedding and Rate Limiting.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/throttle-rates.html)

**Version:** 1.50.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1`
    *   `shortCode (default shortCode)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.pwdless\_login: Passwordless Login scope
    *   Scope sfcc.session\_bridge: Session Bridge scope
    *   Scope sfcc.ta\_ext\_on\_behalf\_of: Trusted Agent External On Behalf Of scope
    *   Scope sfcc.ts\_ext\_on\_behalf\_of: Trusted System External On Behalf Of scope
    *   OAuth flow authorizationCode (authorizationUrl: https://{short-code}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{short-code}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.pwdless\_login: Passwordless Login scope
    *   Scope sfcc.session\_bridge: Session Bridge scope
    *   Scope sfcc.ta\_ext\_on\_behalf\_of: Trusted Agent External On Behalf Of scope
    *   Scope sfcc.ts\_ext\_on\_behalf\_of: Trusted System External On Behalf Of scope

## Operations

### POST Log in a shopper with credentials that are managed by a B2C Commerce instance (B2C Commerce).

`POST /organizations/{organizationId}/oauth2/login`

Operation ID: `authenticateCustomer`.

This follows the authorization code grant flow as defined by the OAuth 2.1 standard. It also uses a proof key for code exchange (PKCE).

For PKCE values:

*   The `code_verifier` string is a random string used for the `/token` endpoint request.
*   The `code_challenge` is an encoded version of the `code_verifier` string using an SHA-256 hash.

The request must include a basic authorization header that contains a Base64 encoded version of the following string: `<shopperUserID>:<shopperPassword>`. Required parameters: `code_challenge`, `channel_id`, `client_id`, and `redirect_uri`.

Optional parameters: `usid`. The SLAS `/login` endpoint redirects back to the redirect URI and returns an authorization code. Calls to `/login` made with the same loginId and tenantId within 1 second result in a conflict.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string, required) Base64-encoded username and password for HTTP basic authentication  
    Example: `Basic <client credentials>`.
*   `x-slas-client-auth` (header, string)
    
    Base64-encoded string of client credentials. The string is composed of a client ID and client secret, separated by a colon (`:`). For example, `clientId:clientSecret`. Don't add the string `"Basic"`.
    
    The `x-slas-client-auth` header is supported for SLAS private clients. When strict client auth is enabled for the client, requests without this header are rejected with a 401.
    

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `LoginRequest`.

#### Responses

*   **303** The authorization code and usid were successfuly added to the location header and sent to the callback as query parameters.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `string`.
    
    Type: `string`.
    
    _Example: authenticateCustomerSuccess_
    
    ```
    {
      "location": "https://<host>:<port>/callback?usid=d11392ae-cbf0-4296-9723-8f9f0e49fd73&state=1728422547223&scope=openid%20offline_access&code=561X8NOKvoRezq2aucazwwkrevUoIP37YRTfsRHX8ow"
    }
    ```
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InvalidBasicAuth401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Basic Authorization failed."
    }
    ```
    
*   **409** Conflict
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: ConflictingCalls409_
    
    ```
    {
      "error": "conflict",
      "error_description": "The same loginId and tenantId tried to login twice within 1 second."
    }
    ```
    
*   **500** Internal server error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### POST Allow the customer to authenticate when their identity provider is down.

`POST /organizations/{organizationId}/oauth2/passwordless/login`

Operation ID: `authorizePasswordlessCustomer`.

This endpoint allows customers to authenticate when their configured identity provider is inaccessible. It provides an alternative authentication path through passwordless login methods like email or SMS verification.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `register_customer` (query, string)
    
    When set to `true`, creates a new customer profile in B2C Commerce if one doesn't already exist. Requires `last_name` and `email` body parameters unless `user_id` is an email address. Optionally accepts `first_name` and `phone_number` body parameters. If the customer profile doesn't exist, it is created when the TOTP is validated via the `passwordless/token` endpoint.
    
    When set to `false` (or omitted), no customer profile is created in B2C Commerce.
    
      
    Maximum length: 5.
*   `strict_verify` (query, boolean)
    
    When set to `true`, blocks the passwordless login request and returns a `400` error if the shopper's email is not verified. Use this to enforce shopper email verification before allowing passwordless authentication. Available in B2C Commerce version 26.6 and later.
    
    Default: `false`
    
      
    Default: `false`. Example: `true`.
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`), for example: `clientId:clientSecret`  
    Maximum length: 4096. Example: `Basic <client credentials>`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `PasswordlessLoginRequest`.

#### Responses

*   **200** The customer authenticated successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `string`.
    
    Type: `string`.
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingAccessToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token."
    }
    ```
    
    _Example: UnverifiedShopper400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Email not verified."
    }
    ```
    
    _Example: TooManyLoginRequests400_
    
    This error is returned specifically when mode = email and the user has exceeded the maximum number of login attempts within the rate limit window. The client should implement exponential backoff and retry the request after the specified time period.
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Too many login requests were made. Please try again later."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **412** Precondition failure
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: DependentServiceUnavailable412_
    
    ```
    {
      "error": "precondition_failure",
      "error_description": "Dependent service is not available."
    }
    ```
    

### GET Log out a shopper.

`GET /organizations/{organizationId}/oauth2/logout`

Operation ID: `logoutCustomer`.

The shopper's access token and refresh token are revoked. If the shopper authenticated with a B2C Commerce (B2C Commerce) instance, the OCAPI JWT is also revoked. Call this endpoint for registered users that have logged in using SLAS. Do not use this endpoint for guest users.

Required header: Authorization header bearer token of the Shopper access token to log out.

Required parameters: `refresh token`, `channel_id`, and `client`.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `client_id` (query, string, required) The SLAS public client ID or SLAS private client ID for use with trusted-agent requests. When using a private client ID a PKCE code challenge is not required.  
    Maximum length: 40.
*   `refresh_token` (query, string, required) Refresh token that was given during the access token request.
*   `channel_id` (query, string) The `channel_id` parameter must be provided if the shopper authenticated using the `login` endpoint with B2C Commerce.  
    Maximum length: 100. Example: `RefArch`.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `hint` (query, string)
    
    `hint=all-sessions` logs out all sessions and invalidates all refresh tokens for a shopper with the same SLAS user ID. This only works within the same session type. Sessions created through different authentication methods (/authorize vs. Trusted System On Behalf) are treated as separate sessions. To invalidate tokens with different SLAS User IDs, you must make explicit logout calls with each token. A shopper authenticated via both /authorize and TSOB has two separate sessions. You will need two logout calls (one per token) to fully log them out.
    
    If this query parameter is not provided, the default behavior is to log out only the current session that matches the refresh token in the request.
    
    If an incorrect value is provided for the hint other than `all-sessions`, the request fails.
    
      
    Allowed values: `all-sessions`.
*   `Authorization` (header, string, required) Shopper access token to be revoked  
    Example: `Bearer eyJ2ZXIiOiIxLjAiLCJraWQiOiI0ZTQyNTFkOS0zM2Y2LTRjMTMtYjZmZC1mOWJkNTJmYTZhNDciLCJ0eXAiOiJqd3QiLCJjbHYiOiJKMi4xLjAiLCJhbGciOiJFUzI1NiJ9.eyJhdXQiOiJHVUlEIiwic2NwIjoic2ZjYy5wcm9kdWN0cy5ybyBzZmNjLmNhdGFsb2dzLnJvIHNmY2Muc2hvcHBlci5ydyIsInN1YiI6ImNjLXNsYXM6OnNsc2FfZGV2OjpzY2lkOjU1M2FjOGFjLTRkYjktNGVkMy04MjVjLTNhZTNiZjVkMzI3Yjo6dXNpZDoxY2E3OWZiNi0xYjIyLTRmOWItOGJiNi05YmU5NWNjMjA4NjMiLCJjdHgiOiJzbGFzLm5vdF9mb3JfZXh0ZXJuYWxfdXNlIiwiaXNzIjoic2xhcy9kZXYvc2xzYV9kZXYiLCJpc3QiOjEsImF1ZCI6ImNvbW1lcmNlY2xvdWQvZGV2L3Nsc2FfZGV2IiwibmJmIjoxNTk0NzY0MDgwLCJzdHkiOiJVc2VyIiwiaXNiIjoidWlkbzpzbGFzOjp1cG46R3Vlc3Q6OnVpZG46R3Vlc3QgVXNlciIsImV4cCI6MTU5NDc2NTkxMCwiaWF0IjoxNTk0NzY0MTEwLCJqdGkiOiJDMkMxNjM0NTE0NTEwLTE3MTQzMTg2NzY0MjcwNTcyNjQ2NTYxMzgifQ.UVYAsWXCn3hoUPy8vLlc7O96RZEHD3N3ZgdNH-ZVvJ1G-R6uJ2VPrYvwKmYXF41Ujm2bo83AYOHVqEEEPT8Kgw`.

#### Responses

*   **200** Success
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `TokenResponse`.
    
    _Example: logoutCustomerSuccess_
    
    ```
    {
      "access_token": "",
      "id_token": "null",
      "refresh_token": "",
      "expires_in": 0,
      "refresh_token_expires_in": 0,
      "token_type": "Bearer",
      "usid": "null",
      "customer_id": "null",
      "enc_user_id": "null",
      "idp_access_token": "",
      "idp_refresh_token": "null",
      "dnt": "null"
    }
    ```
    
*   **303** The user has sent too many requests in a given amount of time, and rate limiting is in effect.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **500** Internal server error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### GET Get an authorization code after authenticating a user against an identity provider (IDP).

`GET /organizations/{organizationId}/oauth2/authorize`

Operation ID: `authorizeCustomer`.

This is the first step of the OAuth 2.1 authorization code flow, in which a user can log in via federation to the IDP configured for the client. After successfully logging in, the user gets an authorization code via a redirect URI.

You can call this endpoint from the front channel (the browser).

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `redirect_uri` (query, string, required)
    
    The redirect for Account Manager to redirect to. A variety of URI formats and wildcard for host are supported, but app links like `airbnb://` or `fb://` are not. Examples of supported URIs:
    
    *   `http://localhost:3000/callback`
    *   `https://example.com/callback`
    *   `com.example.app:redirect_uri_path`
    *   `*.subdomain.topleveldomain.com`
    
      
    Maximum length: 256.
*   `response_type` (query, string, required) Must be `code`. Indicates that the caller wants an authorization code.
    
    Response Type
    
      
    Allowed values: `code`.
*   `client_id` (query, string, required) The SLAS public client ID or SLAS private client ID for use with trusted-agent requests. When using a private client ID a PKCE code challenge is not required.  
    Maximum length: 40.
*   `scope` (query, string)  
    Allowed values: `openid`, `offline_access`, `email`. Maximum length: 256.
*   `state` (query, string) Value to send the client to determine the state between the authorization request and the server response. Optional, but strongly recommended.  
    Maximum length: 512.
*   `usid` (query, string) A unique shopper identifier (USID). If not provided, a new USID is generated.  
    Maximum length: 256.
*   `hint` (query, string)
    
    Name of an identity provider (IDP) to optionally redirect to, thereby skipping the IDP selection step.
    
    To use a public client, set `hint` to `guest` and use a public client ID to get an authorization code. If no `hint` is provided, the preferred IDP of the tenant is used by default.
    
    For session bridge authorization the `hint` should be set to `sb-user` for a registered customer and to `sb-guest` for a guest. For session bridge authorization the SLAS Client `sfcc.session_bridge` scope.
    
      
    Maximum length: 256.
*   `channel_id` (query, string) The channel that this request is for. For a B2C Commerce request, this is angalous to the site ID.  
    Maximum length: 100. Example: `RefArch`.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `code_challenge` (query, string)
    
    PKCE code challenge. Created by the caller.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
    The _`code_challenge` and 'code\_verifier'_ are required if a using SLAS public `client_id`.
    
      
    Minimum length: 43. Maximum length: 128.
*   `ui_locales` (query, string)
    
    End-User's preferred languages and scripts for the user interface, represented as a space-separated list of BCP47 \[RFC5646\] language tag values, ordered by preference. For example, the value `fr-CA fr en` represents a preference for French as spoken in Canada, then French (without a region designation), followed by English (without a region designation).
    
    In most cases the IDP supports one language tag and has a default language set on the server. SLAS will support the space-separated list and pass them to the IDP.
    
      
    Maximum length: 256.
*   `x-slas-client-auth` (header, string)
    
    Base64-encoded string of client credentials. The string is composed of a client ID and client secret, separated by a colon (`:`). For example, `clientId:clientSecret`. Don't add the string `"Basic"`.
    
    The `x-slas-client-auth` header is supported for SLAS private clients. When strict client auth is enabled for the client, requests without this header are rejected with a 401.
    

#### Responses

*   **303** The authorization code was successfully added to the `redirect_uri`.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `string`.
    
    Type: `string`.
    
    _Example: authorizeCustomerSuccess_
    
    ```
    {
      "authorizationCode": "eyJ2ZXIiOiIxLjAiLCJraWQiOiJTTEFTIiwidHlwIjoiand0IiwiY2x2IjoiS",
      "usid": "156c4e69-e89b-406b-a4b7-576980bb234e"
    }
    ```
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InvalidBasicAuth401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Basic Authorization failed."
    }
    ```
    
*   **500** Internal Server Error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### POST Get the shopper or guest JWT access token and a refresh token.

`POST /organizations/{organizationId}/oauth2/token`

Operation ID: `getAccessToken`.

This is the second step of the OAuth 2.1 authorization code flow.

For a private client, an application is able to get an access token for the shopper through the back channel (a trusted server) by passing in the client credentials and the authorization code retrieved from the `authorize` endpoint.

For a guest user, get the shopper JWT access token and a refresh token. This is where a client application is able to get an access token for the guest user through the back channel (a trusted server) by passing in the client credentials.

For a public client using PKCE, an application passes a PKCE `code_verifier` that matches the `code_challenge` that was used to `authorize` the customer along with the authorization code.

When refreshing the access token with a private client ID and client secret, the refresh token is _not_ regenerated. However, when refreshing the access token with a public client ID, the refresh token is _always_ regenerated. The old refresh token is voided with every refresh call, so the refresh token on the client must be replaced to always store the new refresh token.

See the Body section for required parameters, including `grant_type` and others that depend on the value of `grant_type`.

**Important**: As of July 31, 2024\*\*, SLAS requires the `channel_id` query parameter in token requests.

* * *

## Token Issuer Subject Construction & Constraints

The Issuer Subject (`isb`) claim of the issued JWT is a composite string that identifies the shopper session. It concatenates the identity origin (`uido`), login ID (`upn`), display name (`uidn`), guest customer ID (`gcid`, 26 chars), registered customer ID (`rcid`, 26 chars, when applicable), channel ID (`chid`), and any flow-specific values (`tsob`, `taob`, `agent`, `login`, `sesb`) as `key:value` pairs separated by `::`.

**Constraint:** the assembled `isb` must not exceed **256 characters**. Exceeding this returns `400 BAD_REQUEST` with _"Issuer Subject length must be less than 256 characters"_.

**Length calculation breakdown** (with `gcid`\=26, `rcid`\=26, `chid`≤100). Overhead = key chars + each key's trailing `:` + `::` separators between pairs.

| Shape | Overhead | Fixed values | Remaining budget |
| --- | --- | --- | --- |
| Guest | 32 | gcid 26 + chid 100 = 126 | 98 |
| Registered | 39 | gcid 26 + rcid 26 + chid 100 = 152 | 65 |
| TSOB guest | 39 | gcid 26 + chid 100 = 126 | 91 - len(tsob) |
| TSOB registered | 46 | gcid 26 + rcid 26 + chid 100 = 152 | 58 - len(tsob) |
| Pwdless | 47 | gcid 26 + rcid 26 + chid 100 = 152 | 57 - len(login) |
| SESB guest | 39 | gcid 26 + chid 100 = 126 | 91 - len(sesb) |
| SESB registered | 46 | gcid 26 + rcid 26 + chid 100 = 152 | 58 - len(sesb) |
| TAOB guest | 47 | gcid 26 + chid 100 = 126 | 83 - len(taob + agent) |
| TAOB registered | 54 | gcid 26 + rcid 26 + chid 100 = 152 | 50 - len(taob + agent) |

**Worst case (TAOB registered):**

```
256  total
- 54 overhead
- 26  gcid
- 26  rcid
- 100  chid (allowed max)
----
50

Then if taob = ta_ext_on_behalf_of: 
50 - 19 = 31

Meaning only 31 characters remain for uido + upn + uidn + agent.

```

**Practical caps per variable sub-claim:**

| Sub-claim | Description | Max length |
| --- | --- | --- |
| `uido` | Identity origin | ~20 |
| `upn` | Login ID / email | ~80 |
| `uidn` | Display name (after `%3A` escaping) | ~60 |
| `tsob` / `taob` | Trusted-system / trusted-agent hint | ~21 |
| `agent` | Agent ID | ~32 |
| `login` | Passwordless literal (e.g. `pwdless`) | short |
| `sesb` | Session-bridge hint | short |
| `chid` | Channel ID | 100 |

**Notes:**

*   **Identity Origin Variance** — `uido` is a static IDP-configuration string (e.g. `ecom`, `google`, `Link_Brand_Production`). A longer origin reduces the budget available for user-supplied inputs.
*   **Double-Count Fallback** — if a shopper registers without a first and last name, `uidn` is generated from the email (prefix as first name, domain as last name), so the email is effectively counted **twice** (once as `upn`, once as `uidn`). Long emails are the most common cause of overflow.
*   Colons inside `uidn` are URL-encoded as `%3A`, which can further inflate its length.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`), for example: `clientId:clientSecret`. Not required if the grant type is `authorization_code_pkce` or `refresh_token`.  
    Example: `Basic <client credentials>`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `TokenRequest`.

#### Responses

*   **200** the shopper or guest JWT access token and a refresh token were retrieved successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `TokenResponse`.
    
    _Example: getAccessTokenSuccess_
    
    ```
    {
      "access_token": "eyJ2ZXIiOiIxLjAiLCJraWQiOiJTTEFTIiwidHlwIjoiand0IiwiY2x2IjoiSjIuMS4wIiwiYWxnIjoiRVMyNTYifQ.eyJhdWQiOiJjb3JlL2Rldi9idGluZ2V5bHRtMiIsImF1dCI6IkdVSUQiLCJzdWIiOiJ1c2lkOjo1NGFkMmM1YS05MWYwLTQ0YWItODE3Yy03M2Q2Yjg2ODcyZDk6OnVwbjpndWVzdCIsIm5iZiI6MTU4Mjg0NTYyNCwiY3R4Ijoic2ZkYy5jb21tZXJjZWNsb3VkIiwiaXNzIjoiY29yZS9kZXYvYnRpbmdleWx0bTIiLCJzdHkiOiJVc2VyIiwiaXN0IjoxLCJleHAiOjE1ODI4NDU3NDQsImlhdCI6MTU4Mjg0NTY1NCwianRpIjoiQzJDOTA0ODg2NDA3MDkwNDg4NjQwNzMyMjExNzQ1ODEyMTQzIn0.2a6lMBSY17PrhDO8pvEk7PCXW_nkguMHi4J-Tuirkz-ETB6rnKyuRjF5yD6B55tMvm8dO8ulAHyDYqjObMxLJg",
      "id_token": "eyJraWQiOiI3NGU2YjMxZS1lYTczLTQ3OTYtOWRkYi1jMDJmZGI4ZDgwYmUiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2lkOmQ1MDBhMzY5LTc1MWQtNDkzYy1iNDAzLThmOThmYjg3MTdiNiIsImF1ZCI6IjU1M2FjOGFjLTRkYjktNGVkMy04MjVjLTNhZTNiZjVkMzI3YiIsImlzcyI6ImRldi51cy5zaG9wcGVyLmNjLnNhbGVzZm9yY2UuY29tIiwibmFtZSI6ImJsYWlyLnNsYXMudGVzdEBnbWFpbC5jb20iLCJleHAiOjE1OTExMTE0MzgsImlhdCI6MTU5MTEwOTYzOCwiZW1haWwiOiJibGFpci5zbGFzLnRlc3RAZ21haWwuY29tIn0.KgpAcq-G9Lz7IGnjkJlaFLFXYncVCwcVrRIuy3bEfgzRozqaDRvAori4oOz4RtgYjmoc5x2euoisHL0mVnHgPKOdYBty1wTJqneJEQt6hP4Kp0KFciID_ILCi-DE8VWS5t0NknnMP_iKhIkqcRL48iwPFUWkWA6AEWxE_yvJLNRLithsSxsx7EfBfpD8Hr2b5tMEwImQNmJNYGRTI4LSmcYspBORvJoAnfGpMC0kglxl40bhf5j4ItX4_DiWQC4zaGYD-HJV4BDr6C7iGCs5ZVPypF0yQD3iBio26fwj9Ys5WF9XMtPtqET2kqsz6fDC5GkE6HTUHH_r87jxbDq-8w",
      "refresh_token": "EgMYpjfFKdlSy-a3PYeyihmP95IpIp3FaDpPmVH1yu8.lahomBi7zJbRa6yKAuAAiKu3lprTPsEueKwqcBvhRLU",
      "expires_in": 900,
      "refresh_token_expires_in": 7776000,
      "token_type": "Bearer",
      "usid": "18cda486-fe32-4e27-888b-6e4f89938e67",
      "customer_id": "1000005",
      "enc_user_id": "45D39A8499A95288F82855427EBA99B5",
      "idp_access_token": "eyJraWQiOiJYS21HbHVuSm0zSlBTMHNjQXZXV19XQlYtRi1wMkxLSDR0V05UMHVVSjVJIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjFMY0xxTWhqM2t0N1FKeFhxQ0VtdGZOOVV2eUcweW1meDFxZG9BdzF1NWMub2FyeXhveHF0QUtxaVFMbkM1ZDYiLCJpc3MiOiJodHRwczovL2Rldi05NTY1MjM2Lm9rdGEuY29tIiwiYXVkIjoiaHR0cHM6Ly9kZXYtOTU2NTIzNi5va3RhLmNvbSIsInN1YiI6Im9rdGEuc2xhcy50ZXN0IiwiaWF0IjoxNjc5Njk4MzA4LCJleHAiOjE2Nzk3MDE5MDgsImNpZCI6IjBvYTJrNXNma0JXZ0poTEVHNWQ2IiwidWlkIjoiMDB1MzhxZGpuU2NMT0IxbXE1ZDYiLCJzY3AiOlsib2ZmbGluZV9hY2Nlc3MiLCJvcGVuaWQiLCJlbWFpbCIsInByb2ZpbGUiXSwiYXV0aF90aW1lIjoxNjc5Njk4MzA2fQ.FDbGsnZGwTYVKGSlAo6jqcjG2HQ_BqQKRk72M5h69DRHyOM4wngsEELN_Wtgj3E77sP7IOmIKjiK5SFP17ADMbKZptVr2pqaMVF3PuU3Cbl_MgXZValfT-z12jHRq9sHMfsdTjY2RnvG44ZDFKc2no8mdL6IJ1MfCaZT5Tql5Ktq_UgudaWFsYqad3ETcmp5Y8ivz1bFnqud0sO9D9JzYOtfd9h71JKcsSC2rXc_Si-INPKKaGl8CDgaLXxu_Am9twJpUenHLpy0BerhcVvdFz7_611E53xOT_Esrc1pe-XAZtlYsJFnhxTBDT342ukiSWk2m6juVappv1GsRfUf2g"
    }
    ```
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingAccessToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InvalidBasicAuth401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Basic Authorization failed."
    }
    ```
    
*   **500** Internal server error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### POST Get a shopper JWT access token for a customer using session bridging.

`POST /organizations/{organizationId}/oauth2/session-bridge/token`

Operation ID: `getSessionBridgeAccessToken`.

For public client ID requests, you must set the grant\_type to `session_bridge`.

For private client\_id and secret, you must set the grant\_type to `client_credentials` along with a basic authorization header.

**DEPRECATED** - As of January 31, 2024, SLAS no longer supports the SESB `dwsid` parameter for `guest` users for `session-bridge/token` calls. We recommended you transition to using a SESB `dwsgst` token.

The `dwsid` is still needed for `registered` user `session-bridge/token` calls.

**NOTE:** The registered customer Json Web Token (JWT) is available in B2C Commerce versions 25.4 and later.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `SessionBridgeTokenRequest`.

#### Responses

*   **200** The shopper JWT access token was retrieved successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `TokenResponse`.
    
    _Example: getSessionBridgeAccessTokenSuccess_
    
    ```
    {
      "access_token": "eyJ2ZXIiOiIxLjAiLCJraWQiOiJTTEFTIiwidHlwIjoiand0IiwiY2x2IjoiSjIuMS4wIiwiYWxnIjoiRVMyNTYifQ.eyJhdWQiOiJjb3JlL2Rldi9idGluZ2V5bHRtMiIsImF1dCI6IkdVSUQiLCJzdWIiOiJ1c2lkOjo1NGFkMmM1YS05MWYwLTQ0YWItODE3Yy03M2Q2Yjg2ODcyZDk6OnVwbjpndWVzdCIsIm5iZiI6MTU4Mjg0NTYyNCwiY3R4Ijoic2ZkYy5jb21tZXJjZWNsb3VkIiwiaXNzIjoiY29yZS9kZXYvYnRpbmdleWx0bTIiLCJzdHkiOiJVc2VyIiwiaXN0IjoxLCJleHAiOjE1ODI4NDU3NDQsImlhdCI6MTU4Mjg0NTY1NCwianRpIjoiQzJDOTA0ODg2NDA3MDkwNDg4NjQwNzMyMjExNzQ1ODEyMTQzIn0.2a6lMBSY17PrhDO8pvEk7PCXW_nkguMHi4J-Tuirkz-ETB6rnKyuRjF5yD6B55tMvm8dO8ulAHyDYqjObMxLJg",
      "id_token": "eyJraWQiOiI3NGU2YjMxZS1lYTczLTQ3OTYtOWRkYi1jMDJmZGI4ZDgwYmUiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2lkOmQ1MDBhMzY5LTc1MWQtNDkzYy1iNDAzLThmOThmYjg3MTdiNiIsImF1ZCI6IjU1M2FjOGFjLTRkYjktNGVkMy04MjVjLTNhZTNiZjVkMzI3YiIsImlzcyI6ImRldi51cy5zaG9wcGVyLmNjLnNhbGVzZm9yY2UuY29tIiwibmFtZSI6ImJsYWlyLnNsYXMudGVzdEBnbWFpbC5jb20iLCJleHAiOjE1OTExMTE0MzgsImlhdCI6MTU5MTEwOTYzOCwiZW1haWwiOiJibGFpci5zbGFzLnRlc3RAZ21haWwuY29tIn0.KgpAcq-G9Lz7IGnjkJlaFLFXYncVCwcVrRIuy3bEfgzRozqaDRvAori4oOz4RtgYjmoc5x2euoisHL0mVnHgPKOdYBty1wTJqneJEQt6hP4Kp0KFciID_ILCi-DE8VWS5t0NknnMP_iKhIkqcRL48iwPFUWkWA6AEWxE_yvJLNRLithsSxsx7EfBfpD8Hr2b5tMEwImQNmJNYGRTI4LSmcYspBORvJoAnfGpMC0kglxl40bhf5j4ItX4_DiWQC4zaGYD-HJV4BDr6C7iGCs5ZVPypF0yQD3iBio26fwj9Ys5WF9XMtPtqET2kqsz6fDC5GkE6HTUHH_r87jxbDq-8w",
      "refresh_token": "EgMYpjfFKdlSy-a3PYeyihmP95IpIp3FaDpPmVH1yu8.lahomBi7zJbRa6yKAuAAiKu3lprTPsEueKwqcBvhRLU",
      "expires_in": 900,
      "refresh_token_expires_in": 7776000,
      "token_type": "Bearer",
      "usid": "18cda486-fe32-4e27-888b-6e4f89938e67",
      "customer_id": "1000005",
      "enc_user_id": "45D39A8499A95288F82855427EBA99B5",
      "idp_access_token": ""
    }
    ```
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingAccessToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **503** Gateway error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: GatewayError503_
    
    ```
    {
      "error": "gateway_server_error",
      "error_description": "A service that the server relies on is down or is having difficulty."
    }
    ```
    

### POST Get a shopper JWT access token for a registered customer whose credentials are stored using a third party.

`POST /organizations/{organizationId}/oauth2/trusted-system/token`

Operation ID: `getTrustedSystemAccessToken`.

The SLAS client must have the `sfcc.ts_ext_on_behalf_of` scope to access this endpoint.

For trusted-system requests, you can use a basic authorization header that includes a SLAS private client ID and SLAS private client secret instead of the bearer token.

For trusted-system requests, you cannot use SLAS public client\_ids.

* * *

## Token Issuer Subject Construction & Constraints

The Issuer Subject (`isb`) claim of the issued JWT is a composite string that identifies the shopper session. It concatenates the identity origin (`uido`), login ID (`upn`), display name (`uidn`), guest customer ID (`gcid`, 26 chars), registered customer ID (`rcid`, 26 chars, when applicable), channel ID (`chid`), and any flow-specific values (`tsob`, `taob`, `agent`, `login`, `sesb`) as `key:value` pairs separated by `::`.

**Constraint:** the assembled `isb` must not exceed **256 characters**. Exceeding this returns `400 BAD_REQUEST` with _"Issuer Subject length must be less than 256 characters"_.

**Length calculation breakdown** (with `gcid`\=26, `rcid`\=26, `chid`≤100). Overhead = key chars + each key's trailing `:` + `::` separators between pairs.

| Shape | Overhead | Fixed values | Remaining budget |
| --- | --- | --- | --- |
| Guest | 32 | gcid 26 + chid 100 = 126 | 98 |
| Registered | 39 | gcid 26 + rcid 26 + chid 100 = 152 | 65 |
| TSOB guest | 39 | gcid 26 + chid 100 = 126 | 91 - len(tsob) |
| TSOB registered | 46 | gcid 26 + rcid 26 + chid 100 = 152 | 58 - len(tsob) |
| Pwdless | 47 | gcid 26 + rcid 26 + chid 100 = 152 | 57 - len(login) |
| SESB guest | 39 | gcid 26 + chid 100 = 126 | 91 - len(sesb) |
| SESB registered | 46 | gcid 26 + rcid 26 + chid 100 = 152 | 58 - len(sesb) |
| TAOB guest | 47 | gcid 26 + chid 100 = 126 | 83 - len(taob + agent) |
| TAOB registered | 54 | gcid 26 + rcid 26 + chid 100 = 152 | 50 - len(taob + agent) |

**Worst case (TAOB registered):**

```
256  total
- 54 overhead
- 26  gcid
- 26  rcid
- 100  chid (allowed max)
----
50

Then if taob = ta_ext_on_behalf_of: 
50 - 19 = 31

Meaning only 31 characters remain for uido + upn + uidn + agent.

```

**Practical caps per variable sub-claim:**

| Sub-claim | Description | Max length |
| --- | --- | --- |
| `uido` | Identity origin | ~20 |
| `upn` | Login ID / email | ~80 |
| `uidn` | Display name (after `%3A` escaping) | ~60 |
| `tsob` / `taob` | Trusted-system / trusted-agent hint | ~21 |
| `agent` | Agent ID | ~32 |
| `login` | Passwordless literal (e.g. `pwdless`) | short |
| `sesb` | Session-bridge hint | short |
| `chid` | Channel ID | 100 |

**Notes:**

*   **Identity Origin Variance** — `uido` is a static IDP-configuration string (e.g. `ecom`, `google`, `Link_Brand_Production`). A longer origin reduces the budget available for user-supplied inputs.
*   **Double-Count Fallback** — if a shopper registers without a first and last name, `uidn` is generated from the email (prefix as first name, domain as last name), so the email is effectively counted **twice** (once as `upn`, once as `uidn`). Long emails are the most common cause of overflow.
*   Colons inside `uidn` are URL-encoded as `%3A`, which can further inflate its length.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`), for example: `clientId:clientSecret`. Not required if the grant type is `authorization_code_pkce` or `refresh_token`.  
    Example: `Basic <client credentials>`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `TrustedSystemTokenRequest`.

#### Responses

*   **200** The shopper JWT access token was retrieved successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `TokenResponse`.
    
    _Example getTrustedSystemAccessTokenSuccess: same as POST /organizations/{organizationId}/oauth2/session-bridge/token 200 response._
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **409** Conflict
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: ConflictingCalls409_
    
    ```
    {
      "error": "conflict",
      "error_description": "The same loginId and tenantId tried to login twice within 1 second."
    }
    ```
    
*   **503** Gateway error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: GatewayError503_
    
    ```
    {
      "error": "gateway_server_error",
      "error_description": "A service that the server relies on is down or is having difficulty."
    }
    ```
    

### GET Obtain a new agent on behalf of an authorization token for a registered customer.

`GET /organizations/{organizationId}/oauth2/trusted-agent/authorize`

Operation ID: `getTrustedAgentAuthorizationToken`.

This endpoint enables trusted agents (such as customer service representatives or merchants) to obtain authorization tokens that allow them to act on behalf of registered customers. This facilitates customer support scenarios where agents need secure access to customer accounts.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `client_id` (query, string, required) The SLAS public client ID or SLAS private client ID for use with trusted-agent requests. When using a private client ID a PKCE code challenge is not required.  
    Maximum length: 40.
*   `channel_id` (query, string, required) The channel (B2C Commerce site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `code_challenge` (query, string)
    
    PKCE code challenge. Created by the caller.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
    The _`code_challenge` and 'code\_verifier'_ are required if a using SLAS public `client_id`.
    
      
    Minimum length: 43. Maximum length: 128.
*   `login_id` (query, string, required)
    
    The ID of the shopper for trusted agent access.
    
    For TAOB Guest the `login_id` must be set to `Guest`.
    
      
    Maximum length: 128.
*   `idp_origin` (query, string, required)
    
    The IDP that the shopper is associated with.
    
    For TAOB Guest the `idp_origin` must be set to `slas`. This is standard for SLAS Guest requests. If any other `idp_origin` value is used, SLAS returns a bad request.
    
      
    Maximum length: 16.
*   `redirect_uri` (query, string, required)
    
    The redirect for Account Manager to redirect to. A variety of URI formats and wildcard for host are supported, but app links like `airbnb://` or `fb://` are not. Examples of supported URIs:
    
    *   `http://localhost:3000/callback`
    *   `https://example.com/callback`
    *   `com.example.app:redirect_uri_path`
    *   `*.subdomain.topleveldomain.com`
    
      
    Maximum length: 256.
*   `response_type` (query, string, required) Must be `code`. Indicates that the caller wants an authorization code.
    
    Response Type
    
      
    Allowed values: `code`.

#### Responses

*   **303** The new agent was obtained successfully.
    
    Headers:
    
    *   `Location` (string) Location header with the `redirect_uri` to Account Manager, which allows the agent to log in.
        
        URL with redirect
        
          
        Maximum length: 2048. Example: `https://account.demandware.com:443/dwsso/UI/Login?realm=/&goto=https://account.demandware.com:443/dwsso/oauth2/authorize?client_id=6739cb07-2f5f-4e16-a88a-8113a3cb5512&redirect_uri=https://stg.us1.shopper.cc.salesforce.com/api/v1/trusted-agent/callback"`.
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `string`.
    
    Type: `string`.
    
    _Example: getTrustedAgentAuthorizationTokenSuccess_
    
    ```
    {}
    ```
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **500** Internal server error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### POST Get a shopper JWT access token for a registered customer using a trusted agent (merchant).

`POST /organizations/{organizationId}/oauth2/trusted-agent/token`

Operation ID: `getTrustedAgentAccessToken`.

If using a SLAS private client ID, you must also use an `_sfdc_client_auth` header.

The value of the `_sfdc_client_auth` header must be a Base64-encoded string. The string is composed of a SLAS private client ID and client secret, separated by a colon (`:`). For example, `privateClientId:privateClientsecret` becomes `cHJpdmF0ZUNsaWVudElkOnByaXZhdGVDbGllbnRzZWNyZXQ=` after Base64 encoding.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `_sfdc_client_auth` (header, string)
    
    "Base64-encoded string of client credentials. The string is composed of a client ID and client secret, separated by a colon (`:`), like this: `clientId:clientSecret`. (Do not add the string `"Basic"`.)
    
    The `_sfdc_client_auth` header is only required when using a SLAS private client ID."
    
*   `Authorization` (header, string) This is the `Bearer` token that is returned from Account Manager after the trusted agent on behalf of (TAOB) authorize call.  
    Example: `Bearer HQ8zQXpc0VVaXEdBdzasZQaCQDw`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `TrustedAgentTokenRequest`.

#### Responses

*   **200** Success
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `TokenResponse`.
    
    _Example: getTrustedAgentAccessTokenSuccess_
    
    ```
    {
      "access_token": "eyJ2ZXIiOiIxLjAiLCJraWQiOiJTTEFTIiwidHlwIjoiand0IiwiY2x2IjoiSjIuMS4wIiwiYWxnIjoiRVMyNTYifQ.eyJhdWQiOiJjb3JlL2Rldi9idGluZ2V5bHRtMiIsImF1dCI6IkdVSUQiLCJzdWIiOiJ1c2lkOjo1NGFkMmM1YS05MWYwLTQ0YWItODE3Yy03M2Q2Yjg2ODcyZDk6OnVwbjpndWVzdCIsIm5iZiI6MTU4Mjg0NTYyNCwiY3R4Ijoic2ZkYy5jb21tZXJjZWNsb3VkIiwiaXNzIjoiY29yZS9kZXYvYnRpbmdleWx0bTIiLCJzdHkiOiJVc2VyIiwiaXN0IjoxLCJleHAiOjE1ODI4NDU3NDQsImlhdCI6MTU4Mjg0NTY1NCwianRpIjoiQzJDOTA0ODg2NDA3MDkwNDg4NjQwNzMyMjExNzQ1ODEyMTQzIn0.2a6lMBSY17PrhDO8pvEk7PCXW_nkguMHi4J-Tuirkz-ETB6rnKyuRjF5yD6B55tMvm8dO8ulAHyDYqjObMxLJg",
      "id_token": "eyJraWQiOiI3NGU2YjMxZS1lYTczLTQ3OTYtOWRkYi1jMDJmZGI4ZDgwYmUiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2lkOmQ1MDBhMzY5LTc1MWQtNDkzYy1iNDAzLThmOThmYjg3MTdiNiIsImF1ZCI6IjU1M2FjOGFjLTRkYjktNGVkMy04MjVjLTNhZTNiZjVkMzI3YiIsImlzcyI6ImRldi51cy5zaG9wcGVyLmNjLnNhbGVzZm9yY2UuY29tIiwibmFtZSI6ImJsYWlyLnNsYXMudGVzdEBnbWFpbC5jb20iLCJleHAiOjE1OTExMTE0MzgsImlhdCI6MTU5MTEwOTYzOCwiZW1haWwiOiJibGFpci5zbGFzLnRlc3RAZ21haWwuY29tIn0.KgpAcq-G9Lz7IGnjkJlaFLFXYncVCwcVrRIuy3bEfgzRozqaDRvAori4oOz4RtgYjmoc5x2euoisHL0mVnHgPKOdYBty1wTJqneJEQt6hP4Kp0KFciID_ILCi-DE8VWS5t0NknnMP_iKhIkqcRL48iwPFUWkWA6AEWxE_yvJLNRLithsSxsx7EfBfpD8Hr2b5tMEwImQNmJNYGRTI4LSmcYspBORvJoAnfGpMC0kglxl40bhf5j4ItX4_DiWQC4zaGYD-HJV4BDr6C7iGCs5ZVPypF0yQD3iBio26fwj9Ys5WF9XMtPtqET2kqsz6fDC5GkE6HTUHH_r87jxbDq-8w",
      "refresh_token": "EgMYpjfFKdlSy-a3PYeyihmP95IpIp3FaDpPmVH1yu8.lahomBi7zJbRa6yKAuAAiKu3lprTPsEueKwqcBvhRLU",
      "expires_in": 900,
      "token_type": "Bearer",
      "refresh_token_expires_in": 7776000,
      "usid": "18cda486-fe32-4e27-888b-6e4f89938e67",
      "customer_id": "1000005",
      "enc_user_id": "45D39A8499A95288F82855427EBA99B5",
      "idp_access_token": ""
    }
    ```
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingAccessToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **503** Gateway error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: GatewayError503_
    
    ```
    {
      "error": "gateway_server_error",
      "error_description": "A service that the server relies on is down or is having difficulty."
    }
    ```
    

### POST Request a reset password token.

`POST /organizations/{organizationId}/oauth2/password/reset`

Operation ID: `getPasswordResetToken`.

This endpoint initiates the password reset process for a customer by requesting a password reset token. The token is delivered through the configured delivery mode (email, SMS, etc.) and can be used with the password/action endpoint to set a new password.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `PasswordActionRequest`.

#### Responses

*   **200** The reset password token was requested successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadMissingAccessOrRefreshToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token or refresh token"
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **412** Precondition failure
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: DependentServiceUnavailable412_
    
    ```
    {
      "error": "precondition_failure",
      "error_description": "Dependent service is not available."
    }
    ```
    

### POST Create a new password.

`POST /organizations/{organizationId}/oauth2/password/action`

Operation ID: `resetPassword`.

This endpoint allows a customer to set a new password using a valid password reset token. The customer must provide the token received from the password/reset endpoint along with the desired new password.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`), for example: `clientId:clientSecret`  
    Example: `Basic <client credentials>`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `PasswordActionVerifyRequest`.

#### Responses

*   **200** The password was created successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadParameters400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing request parameters."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **503** Gateway error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: GatewayError503_
    
    ```
    {
      "error": "gateway_server_error",
      "error_description": "A service that the server relies on is down or is having difficulty."
    }
    ```
    

### POST Issue a shopper token (JWT).

`POST /organizations/{organizationId}/oauth2/passwordless/token`

Operation ID: `getPasswordLessAccessToken`.

This endpoint issues a shopper JSON Web Token (JWT) using a passwordless login token. It enables authentication flows where traditional username/password combinations are not required, supporting alternative authentication methods.

* * *

## Token Issuer Subject Construction & Constraints

The Issuer Subject (`isb`) claim of the issued JWT is a composite string that identifies the shopper session. It concatenates the identity origin (`uido`), login ID (`upn`), display name (`uidn`), guest customer ID (`gcid`, 26 chars), registered customer ID (`rcid`, 26 chars, when applicable), channel ID (`chid`), and any flow-specific values (`tsob`, `taob`, `agent`, `login`, `sesb`) as `key:value` pairs separated by `::`.

**Constraint:** the assembled `isb` must not exceed **256 characters**. Exceeding this returns `400 BAD_REQUEST` with _"Issuer Subject length must be less than 256 characters"_.

**Length calculation breakdown** (with `gcid`\=26, `rcid`\=26, `chid`≤100). Overhead = key chars + each key's trailing `:` + `::` separators between pairs.

| Shape | Overhead | Fixed values | Remaining budget |
| --- | --- | --- | --- |
| Guest | 32 | gcid 26 + chid 100 = 126 | 98 |
| Registered | 39 | gcid 26 + rcid 26 + chid 100 = 152 | 65 |
| TSOB guest | 39 | gcid 26 + chid 100 = 126 | 91 - len(tsob) |
| TSOB registered | 46 | gcid 26 + rcid 26 + chid 100 = 152 | 58 - len(tsob) |
| Pwdless | 47 | gcid 26 + rcid 26 + chid 100 = 152 | 57 - len(login) |
| SESB guest | 39 | gcid 26 + chid 100 = 126 | 91 - len(sesb) |
| SESB registered | 46 | gcid 26 + rcid 26 + chid 100 = 152 | 58 - len(sesb) |
| TAOB guest | 47 | gcid 26 + chid 100 = 126 | 83 - len(taob + agent) |
| TAOB registered | 54 | gcid 26 + rcid 26 + chid 100 = 152 | 50 - len(taob + agent) |

**Worst case (TAOB registered):**

```
256  total
- 54 overhead
- 26  gcid
- 26  rcid
- 100  chid (allowed max)
----
50

Then if taob = ta_ext_on_behalf_of:
50 - 19 = 31

Meaning only 31 characters remain for uido + upn + uidn + agent.

```

**Practical caps per variable sub-claim:**

| Sub-claim | Description | Max length |
| --- | --- | --- |
| `uido` | Identity origin | ~20 |
| `upn` | Login ID / email | ~80 |
| `uidn` | Display name (after `%3A` escaping) | ~60 |
| `tsob` / `taob` | Trusted-system / trusted-agent hint | ~21 |
| `agent` | Agent ID | ~32 |
| `login` | Passwordless literal (e.g. `pwdless`) | short |
| `sesb` | Session-bridge hint | short |
| `chid` | Channel ID | 100 |

**Notes:**

*   **Identity Origin Variance** — `uido` is a static IdP-configuration string (e.g. `ecom`, `google`, `Link_Brand_Production`). A longer origin reduces the budget available for user-supplied inputs.
*   **Double-Count Fallback** — if a shopper registers without a first and last name, `uidn` is generated from the email (prefix as first name, domain as last name), so the email is effectively counted **twice** (once as `upn`, once as `uidn`). Long emails are the most common cause of overflow.
*   Colons inside `uidn` are URL-encoded as `%3A`, which can further inflate its length.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`), for example: `clientId:clientSecret`  
    Example: `Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `PasswordLessLoginTokenRequest`.

#### Responses

*   **200** The shopper token was issued successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `TokenResponse`.
    
    _Example getPasswordLessAccessTokenSuccess: same as POST /organizations/{organizationId}/oauth2/session-bridge/token 200 response._
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingAccessToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **503** Gateway error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: GatewayError503_
    
    ```
    {
      "error": "gateway_server_error",
      "error_description": "A service that the server relies on is down or is having difficulty."
    }
    ```
    

### POST Invalidate a refresh token.

`POST /organizations/{organizationId}/oauth2/revoke`

Operation ID: `revokeToken`.

A basic auth header with Base64-encoded `clientId:secret` is required in the Authorization header, and the refresh token to be revoked is required in the body.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string, required) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`), like this: `clientId:clientSecret`  
    Example: `Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `TokenActionRequest`.

_Example: TokenActionRequestBody_

```
{
  "token": "ry5XU_WHX20S6Cn6W7keFIs7Pzkv4wTZJS9Yvh0Ve9A.cdBxoCY9Q3jffQQOFnb_qghbSmSRnn9-2H4GwFTDMTk",
  "token_type_hint": "refresh_token"
}
```

#### Responses

*   **200** The refresh token was revoked successfully.
    
    Media type: `application/json`. Schema: `TokenActionRequest`.
    
    _Example: revokeTokenSuccess_
    
    ```
    {
      "access_token": "",
      "id_token": "null",
      "refresh_token": "EnL9U2f3-WiVPwL60CFBI21UY_oxWAwX5JkgO-X12Vs",
      "expires_in": 0,
      "refresh_token_expires_in": 0,
      "token_type": "Bearer",
      "usid": "null",
      "customer_id": "null",
      "enc_user_id": "null",
      "idp_access_token": ""
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingRefreshToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing refresh token."
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InvalidBasicAuth401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Basic Authorization failed."
    }
    ```
    
*   **500** Internal server error
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### POST Return token properties.

`POST /organizations/{organizationId}/oauth2/introspect`

Operation ID: `introspectToken`.

A basic auth header with Base64-encoded `clientId:secret` is required in the Authorization header, as well as an access token or refresh token. Use `token_type_hint` to help identify the token.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string, required) Base64 string for HTTP Basic authentication.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `TokenActionRequest`.

_Example: TokenActionRequestBody_

```
{
  "token": "ry5XU_WHX20S6Cn6W7keFIs7Pzkv4wTZJS9Yvh0Ve9A.cdBxoCY9Q3jffQQOFnb_qghbSmSRnn9-2H4GwFTDMTk",
  "token_type_hint": "refresh_token"
}
```

#### Responses

*   **200** Token properties returned successfully.
    
    Media type: `application/json`. Schema: `TokenActionRequest`.
    
    _Example: introspectTokenSuccess_
    
    ```
    {
      "active": true,
      "client_id": "553ac8ac-4db9-4ed3-825c-3ae3bf5d327b",
      "exp": 1602523099,
      "iat": 1594747099,
      "iss": "https://localhost:9000/",
      "scope": "offline_access openid",
      "sub": "usid:edbf780a-2d83-4e82-9f64-8d051e3538d2::uido:Google::upn:blair.slas.test@gmail.com::uidn:Foo SLAS-Test",
      "token_type": "refresh_token"
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadMissingAccessOrRefreshToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token or refresh token"
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InvalidBasicAuth401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Basic Authorization failed."
    }
    ```
    
*   **500** Internal server error
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### GET Return a JSON listing of claims about the currently authenticated user.

`GET /organizations/{organizationId}/oauth2/userinfo`

Operation ID: `getUserInfo`.

This endpoint returns identity information about the authenticated user in the form of OpenID Connect claims. It requires a valid access token and returns information such as user ID, name, email, and other identity attributes based on the scopes granted during authentication.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `channel_id` (query, string) Used when getting user information for a SFCC login. For an B2C Commerce customer, this is angalous to the site ID. Required when getting user information for an B2C Commerce customer.  
    Maximum length: 100. Example: `RefArch`.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `idpValidate` (query, boolean)
    
    When a user authenticates via an IDP, SLAS calls the IDP's `/userinfo` endpoint to retrieve user information. Since some IDPs don't reliably return user info, set `idpValidate=false` to skip this call and use the user information already stored in SLAS instead.
    
    Default: `true`
    
      
    Example: `false`.
    
    _Example_
    
    ```
    false
    ```
    
*   `Authorization` (header, string, required) SLAS Access Token  
    Maximum length: 4096. Example: `Bearer eyJ2ZXIiOiIxLjAiLCJraWQiOiI0ZTQyNTFkOS0zM2Y2LTRjMTMtYjZmZC1mOWJkNTJmYTZhNDciLCJ0eXAiOiJqd3QiLCJjbHYiOiJKMi4xLjAiLCJhbGciOiJFUzI1NiJ9.eyJhdXQiOiJHVUlEIiwic2NwIjoic2ZjYy5wcm9kdWN0cy5ybyBzZmNjLmNhdGFsb2dzLnJvIHNmY2Muc2hvcHBlci5ydyIsInN1YiI6ImNjLXNsYXM6OnNsc2FfZGV2OjpzY2lkOjU1M2FjOGFjLTRkYjktNGVkMy04MjVjLTNhZTNiZjVkMzI3Yjo6dXNpZDoxY2E3OWZiNi0xYjIyLTRmOWItOGJiNi05YmU5NWNjMjA4NjMiLCJjdHgiOiJzbGFzLm5vdF9mb3JfZXh0ZXJuYWxfdXNlIiwiaXNzIjoic2xhcy9kZXYvc2xzYV9kZXYiLCJpc3QiOjEsImF1ZCI6ImNvbW1lcmNlY2xvdWQvZGV2L3Nsc2FfZGV2IiwibmJmIjoxNTk0NzY0MDgwLCJzdHkiOiJVc2VyIiwiaXNiIjoidWlkbzpzbGFzOjp1cG46R3Vlc3Q6OnVpZG46R3Vlc3QgVXNlciIsImV4cCI6MTU5NDc2NTkxMCwiaWF0IjoxNTk0NzY0MTEwLCJqdGkiOiJDMkMxNjM0NTE0NTEwLTE3MTQzMTg2NzY0MjcwNTcyNjQ2NTYxMzgifQ.UVYAsWXCn3hoUPy8vLlc7O96RZEHD3N3ZgdNH-ZVvJ1G-R6uJ2VPrYvwKmYXF41Ujm2bo83AYOHVqEEEPT8Kgw`.

#### Responses

*   **200** Claims returned successfully.
    
    Media type: `application/json`. Schema: `string`.
    
    Type: `string`.
    
    _Example: getUserInfoSuccess_
    
    ```
    {
      "customer_id": "abxHc1lblIlKwRl0k1mqYYkewY",
      "email": "slas-okta-test@test.org",
      "external_id": "okta-00u38qdjnScLOB1mq5d6",
      "family_name": "Test",
      "given_name": "Slas",
      "name": "Slas Test",
      "sub": "98a84e4b-be50-422a-ab04-e9034e859eb9",
      "validated": true
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingAccessToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token."
    }
    ```
    
*   **500** Internal server error
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### GET Return a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details. For performance purposes, the \`/.well-known/openid-configuration\` endpoint is rate limited to 25 call per minute.

`GET /organizations/{organizationId}/oauth2/.well-known/openid-configuration`

Operation ID: `getWellknownOpenidConfiguration`.

This endpoint provides OpenID Connect discovery information in a standardized format. It allows clients to programmatically discover SLAS capabilities, including available endpoints, supported authentication flows, token signing algorithms, and other configuration details. This information helps clients integrate with the authentication service with minimal manual configuration.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** The JSON listing information was returned successfully.
    
    Media type: `application/json`. Schema: `string`.
    
    Type: `string`.
    
    _Example: getWellknownOpenidConfigurationSuccess_
    
    ```
    {
      "authorization_endpoint": "https://stg.us.shopper.cc.salesforce.com/api/v1/organizations/zzzz_tst/oauth2/authorize",
      "claims_supported": [
        "email",
        "name",
        "given_name",
        "family_name",
        "sub"
      ],
      "code_challenge_methods_supported": [
        "S256"
      ],
      "grant_types_supported": [
        "authorization_code",
        "authorization_code_pkce",
        "client_credentials",
        "refresh_token"
      ],
      "id_token_encryption_enc_values_supported": [
        "A256GCM"
      ],
      "issuer": "https://stg.us.shopper.cc.salesforce.com/api/v1/organizations/zzzz_tst/oauth2",
      "jwks_uri": "https://stg.us.shopper.cc.salesforce.com/api/v1/organizations/zzzz_tst/oauth2/jwks",
      "response_types_supported": [
        "code",
        "token",
        "token id_token"
      ],
      "revocation_endpoint": "https://stg.us.shopper.cc.salesforce.com/api/v1/organizations/zzzz_tst/oauth2/revoke",
      "scopes_supported": [
        "email",
        "openid",
        "profile"
      ],
      "subject_types_supported": [
        "public"
      ],
      "token_endpoint": "https://stg.us.shopper.cc.salesforce.com/api/v1/organizations/zzzz_tst/oauth2/token",
      "userinfo_endpoint": "https://stg.us.shopper.cc.salesforce.com/api/v1/organizations/zzzz_tst/oauth2/userinfo"
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: MalformedTenantId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Tenant Id Exception - Must be a well-formed tenantId"
    }
    ```
    
*   **500** Internal server error
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### GET Retrieve JWKS keys.

`GET /organizations/{organizationId}/oauth2/jwks`

Operation ID: `getJwksUri`.

The `/jwks` endpoint provides a JSON Web Key Set (JWKS) that includes current, past, and future public keys. These keys allow clients to validate the Shopper JSON Web Token (JWT) issued by SLAS, ensuring that no tampering with the token has occurred. Every SLAS JWT that is passed into SLAS, SCAPI, or OCAPI is always validated and is rejected if the signature validation does not match.

To optimize performance, the `/jwks` endpoint is limited to 25 calls per minute, so we recommended caching the JWKS keys and refresh them only when necessary, instead of making frequent requests. Typically, the JWKs endpoint can be used once per DAY.

For additional information on using JWKS, see [https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-validate-jwt-with-jwks.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-validate-jwt-with-jwks.html).

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** The response body containing the JWKS keys was retrieved successfully.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example: getJwksSuccess_
    
    ```
    {
      "keys": [
        {
          "crv": "P-256",
          "kid": "2d670fa8-0f28-44a1-b8b4-87a6d2feb1d8",
          "kty": "EC",
          "use": "sig",
          "x": "_2tPqxGhgX6cA5Qg7v6UH_9om8OR3-OehkgXXWraTp8",
          "y": "DAykmQPtf282buIcL0rLwKYbK6ApgripMjazdAthUFw"
        },
        {
          "crv": "P-256",
          "kid": "eb70508f-4d64-46f7-a3d5-b36558d6e6b6",
          "kty": "EC",
          "use": "sig",
          "x": "VV0JVJFhkz71wY0E73Z-snorZ5oJf1QOdkIbCjyMqLs",
          "y": "QLkqBVSPPrkd7HjaSEMgMU9Ob-FDpg1W-oLq5I4ExqQ"
        },
        {
          "crv": "P-256",
          "kid": "0f2016af-1388-4972-b54d-31cb9e3704ed",
          "kty": "EC",
          "use": "sig",
          "x": "KpmPoZTFXs80Uxy7QcOQ9aaqW35xgT3Qyakee8zR7gA",
          "y": "P87TZ52rjnOGlmjaPeUGbLaOqiB7FHnoEzULIw6QlfJ"
        }
      ]
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: getJwksUri400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Tenant Id Exception - Must be a well-formed tenantId"
    }
    ```
    
*   **500** Internal Server Error
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### POST Authorize user for WebAuthn registration

`POST /organizations/{organizationId}/oauth2/webauthn/register/authorize`

Operation ID: `authorizeWebauthnRegistration`.

Authorizes a user to register a WebAuthn credential (passkey). This endpoint validates the user's credentials and creates a password action token that can be used to start the registration process. The token is sent to the user via the specified channel (email or SMS).

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`). For example: `clientId:clientSecret`.  
    Example: `Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `PasswordActionRequest`.

#### Responses

*   **204** User successfully authorized for WebAuthn registration. TOTP sent to user.
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    

### POST Start WebAuthn registration

`POST /organizations/{organizationId}/oauth2/webauthn/register/start`

Operation ID: `startWebauthnUserRegistration`.

Starts the WebAuthn registration process by generating credential creation options. Returns the challenge and other parameters needed by the authenticator to create a new credential.

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`). For example: `clientId:clientSecret`.  
    Example: `Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `RegistrationStartRequest`.

_Example: registrationStartRequest_

```
{
  "client_id": "12345678-1234-1234-1234-123456789012",
  "pwd_action_token": "12345678",
  "user_id": "user@example.com",
  "channel_id": "RefArch",
  "display_name": "John Doe",
  "nick_name": "My iPhone"
}
```

#### Responses

*   **200** Registration options successfully generated.
    
    Media type: `application/json`. Schema: `object`.
    
    _Example: startWebauthnUserRegistrationSuccess_
    
    ```
    {
      "extensions": {},
      "attestation": "none",
      "challenge": "qcjjr4ZckSHuiSd1nShZkVt12I1udQO_7MAkynXP8Nk",
      "authenticatorSelection": {
        "userVerification": "preferred",
        "requireResidentKey": false,
        "residentKey": "preferred"
      },
      "user": {
        "name": "darth.vader",
        "id": "GyOH81kDRxJBvHPQkkbmTagOADuixhp_37P_UnSwHAI",
        "displayName": "Darth Vader"
      },
      "rp": {
        "name": "SLAS Service",
        "id": "localhost"
      },
      "timeout": 90000,
      "excludeCredentials": [],
      "pubKeyCredParams": {
        "alg": -7,
        "type": "public-key"
      }
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    

### POST Finish WebAuthn registration

`POST /organizations/{organizationId}/oauth2/webauthn/register/finish`

Operation ID: `finishWebauthnUserRegistration`.

Completes the WebAuthn registration process by verifying the credential created by the authenticator. Stores the public key and credential information for future authentication.

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`). For example: `clientId:clientSecret`.  
    Example: `Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.

#### Request body (required)

Media type: `application/json`. Schema: `RegistrationFinishRequest`.

#### Responses

*   **204** Registration successfully completed
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    

### POST Start WebAuthn authentication

`POST /organizations/{organizationId}/oauth2/webauthn/authenticate/start`

Operation ID: `startWebauthnAuthentication`.

Starts the WebAuthn authentication process by generating credential request options. Returns the challenge and allowed credentials for the user to authenticate with.

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`). For example: `clientId:clientSecret`.  
    Example: `Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `AuthenticateRequest`.

_Example: authenticateRequest_

```
{
  "tenant_id": "zzte_053",
  "client_id": "12345678-1234-1234-1234-123456789012",
  "channel_id": "RefArch",
  "user_id": "user@example.com"
}
```

#### Responses

*   **200** Authentication options successfully generated
    
    Media type: `application/json`. Schema: `PublicKeyCredentialRequestOptions`.
    
    _Example: webauthnAuthenticationStartSuccess_
    
    ```
    {
      "challenge": "V2FsdGVyIFdoaXRlIFRlc3QgQ2hhbGxlbmdl",
      "timeout": 60000,
      "rpId": "localhost",
      "allowCredentials": [
        {
          "type": "public-key",
          "id": "AQIDBAUGBwgJCgsMDQ4PEA",
          "transports": [
            "usb",
            "nfc"
          ]
        }
      ],
      "userVerification": "preferred",
      "extensions": {}
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **404** Not Found
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: UserNotFound404_
    
    ```
    {
      "error": "not_found",
      "error_description": "User Not Found"
    }
    ```
    

### POST Finish WebAuthn authentication

`POST /organizations/{organizationId}/oauth2/webauthn/authenticate/finish`

Operation ID: `finishWebauthnAuthentication`.

Completes the WebAuthn authentication process by verifying the assertion from the authenticator. Returns OAuth tokens upon successful authentication.

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `Authorization` (header, string) Base64-encoded string for HTTP Basic authentication. The string is composed of a client ID and client secret, separated by a colon (`:`). For example: `clientId:clientSecret`.  
    Example: `Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW`.

#### Request body (required)

Media type: `application/json`. Schema: `AuthenticateFinishRequest`.

#### Responses

*   **200** Authentication successful
    
    Media type: `application/json`. Schema: `AuthenticateResult`.
    
    _Example: webauthnAuthenticationFinishSuccess_
    
    ```
    {
      "credentialId": "AQIDBAUGBwgJCgsMDQ4PEA",
      "username": "user@example.com",
      "success": true,
      "tokenResponse": {
        "access_token": "eyJ2ZXIiOiIxLjAiLCJraWQiOiJTTEFTIiwidHlwIjoiand0IiwiY2x2IjoiSjIuMS4wIiwiYWxnIjoiRVMyNTYifQ.eyJhdWQiOiJjb3JlL2Rldi9idGluZ2V5bHRtMiIsImF1dCI6IkdVSUQiLCJzdWIiOiJ1c2lkOjo1NGFkMmM1YS05MWYwLTQ0YWItODE3Yy03M2Q2Yjg2ODcyZDk6OnVwbjpndWVzdCIsIm5iZiI6MTU4Mjg0NTYyNCwiY3R4Ijoic2ZkYy5jb21tZXJjZWNsb3VkIiwiaXNzIjoiY29yZS9kZXYvYnRpbmdleWx0bTIiLCJzdHkiOiJVc2VyIiwiaXN0IjoxLCJleHAiOjE1ODI4NDU3NDQsImlhdCI6MTU4Mjg0NTY1NCwianRpIjoiQzJDOTA0ODg2NDA3MDkwNDg4NjQwNzMyMjExNzQ1ODEyMTQzIn0.2a6lMBSY17PrhDO8pvEk7PCXW_nkguMHi4J-Tuirkz-ETB6rnKyuRjF5yD6B55tMvm8dO8ulAHyDYqjObMxLJg",
        "id_token": "eyJraWQiOiI3NGU2YjMxZS1lYTczLTQ3OTYtOWRkYi1jMDJmZGI4ZDgwYmUiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2lkOmQ1MDBhMzY5LTc1MWQtNDkzYy1iNDAzLThmOThmYjg3MTdiNiIsImF1ZCI6IjU1M2FjOGFjLTRkYjktNGVkMy04MjVjLTNhZTNiZjVkMzI3YiIsImlzcyI6ImRldi51cy5zaG9wcGVyLmNjLnNhbGVzZm9yY2UuY29tIiwibmFtZSI6ImJsYWlyLnNsYXMudGVzdEBnbWFpbC5jb20iLCJleHAiOjE1OTExMTE0MzgsImlhdCI6MTU5MTEwOTYzOCwiZW1haWwiOiJibGFpci5zbGFzLnRlc3RAZ21haWwuY29tIn0.KgpAcq-G9Lz7IGnjkJlaFLFXYncVCwcVrRIuy3bEfgzRozqaDRvAori4oOz4RtgYjmoc5x2euoisHL0mVnHgPKOdYBty1wTJqneJEQt6hP4Kp0KFciID_ILCi-DE8VWS5t0NknnMP_iKhIkqcRL48iwPFUWkWA6AEWxE_yvJLNRLithsSxsx7EfBfpD8Hr2b5tMEwImQNmJNYGRTI4LSmcYspBORvJoAnfGpMC0kglxl40bhf5j4ItX4_DiWQC4zaGYD-HJV4BDr6C7iGCs5ZVPypF0yQD3iBio26fwj9Ys5WF9XMtPtqET2kqsz6fDC5GkE6HTUHH_r87jxbDq-8w",
        "refresh_token": "EgMYpjfFKdlSy-a3PYeyihmP95IpIp3FaDpPmVH1yu8.lahomBi7zJbRa6yKAuAAiKu3lprTPsEueKwqcBvhRLU",
        "expires_in": 900,
        "refresh_token_expires_in": 7776000,
        "token_type": "Bearer",
        "usid": "18cda486-fe32-4e27-888b-6e4f89938e67",
        "customer_id": "1000005",
        "enc_user_id": "45D39A8499A95288F82855427EBA99B5",
        "idp_access_token": ""
      }
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    

### GET Retrieve passkey user information and credentials by login ID

`GET /organizations/{organizationId}/oauth2/webauthn/passkey/user/{loginId}`

Operation ID: `getPasskeyUserByLoginId`. Security: ShopperToken (sfcc.pwdless\_login).

This endpoint retrieves a user's WebAuthn passkey information including all associated credentials. It returns the user's profile information along with a list of all registered passkey credentials.

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

This endpoint requires Shopper JWT authentication.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `channel_id` (query, string, required) The channel (B2C Commerce site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `loginId` (path, string, required) The login ID (username) of the user whose passkey information is being retrieved  
    Minimum length: 1. Maximum length: 256. Example: `user@example.com`.
*   `Authorization` (header, string, required) Shopper JWT access token  
    Minimum length: 1. Maximum length: 4096. Example: `Bearer eyJ2ZXIiOiIxLjAiLCJraWQiOiI0ZTQyNTFkOS0zM2Y2LTRjMTMtYjZmZC1mOWJkNTJmYTZhNDciLCJ0eXAiOiJqd3QiLCJjbHYiOiJKMi4xLjAiLCJhbGciOiJFUzI1NiJ9...`.

#### Responses

*   **200** The passkey user information and credentials were retrieved successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/json`. Schema: `PasskeyUser`.
    
    _Example: getPasskeyUserByLoginIdSuccess_
    
    ```
    {
      "id": 26,
      "userName": "user@example.com",
      "displayName": "John Doe",
      "userHandle": "yRU-7pWyWUE6nw8hztqqUZG635p7UKDDb2lbC1FyF78",
      "slasUserId": 10000,
      "credentials": [
        {
          "id": 21,
          "userId": 26,
          "credentialId": "t5Awv5pJ_kM7K8U2-5ijw5rSKNkHFHTTg_gAbdrod8c",
          "nickName": "Fingerprint",
          "publicKey": "pQECAyYgASFYIKIpY59lUthC1dDw_9WXKCOaLNCB2WSoGrK0kAZG33s3IlggxTvdmk2QC_HPjAwf_eHdoxIBvfN3c376ws8xUaxlJ4A",
          "userHandle": "yRU-7pWyWUE6nw8hztqqUZG635p7UKDDb2lbC1FyF78",
          "signatureCount": "2"
        },
        {
          "id": 22,
          "userId": 26,
          "credentialId": "SVKfbUGBXofb2JzliJrMtZDENYByWgq_j4-p2M_3wC4",
          "nickName": "YubiKey",
          "publicKey": "pQECAyYgASFYIHM_4IKLMC8dboiRNfD0E0Gk4LmCTIgEyCTr-9SyHHeIIlggfn5_AzAl67kttLXWb-_Ts6MG7WHKoXzlKtame_wEYPE",
          "userHandle": "yRU-7pWyWUE6nw8hztqqUZG635p7UKDDb2lbC1FyF78",
          "signatureCount": "5"
        }
      ]
    }
    ```
    
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingLoginId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "The login ID is missing or invalid."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **403** Forbidden - token validation failed
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: TokenMismatch403_
    
    ```
    {
      "error": "forbidden",
      "error_description": "The loginId, organizationId, or channel_id in the token does not match the request parameters."
    }
    ```
    
*   **404** Not found
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: PasskeyUserNotFound404_
    
    ```
    {
      "error": "not_found",
      "error_description": "No passkey user found with the provided login ID."
    }
    ```
    

### DELETE Delete passkey user and all associated credentials

`DELETE /organizations/{organizationId}/oauth2/webauthn/passkey/user/{loginId}`

Operation ID: `deletePasskeyUser`. Security: ShopperToken (sfcc.pwdless\_login).

This endpoint deletes a user's WebAuthn passkey information and all associated credentials. The endpoint validates the Shopper JWT signature and ensures that the loginId, organizationId, and channel\_id in the token match the values in the path and query parameters.

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

This endpoint requires Shopper JWT authentication.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `channel_id` (query, string, required) The channel (B2C Commerce site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `loginId` (path, string, required) The login ID (username) of the user whose passkey information is being deleted  
    Minimum length: 1. Maximum length: 256. Example: `user@example.com`.
*   `Authorization` (header, string, required) Shopper JWT access token  
    Minimum length: 1. Maximum length: 4096. Example: `Bearer eyJ2ZXIiOiIxLjAiLCJraWQiOiI0ZTQyNTFkOS0zM2Y2LTRjMTMtYjZmZC1mOWJkNTJmYTZhNDciLCJ0eXAiOiJqd3QiLCJjbHYiOiJKMi4xLjAiLCJhbGciOiJFUzI1NiJ5...`.

#### Responses

*   **204** The passkey user and all credentials were deleted successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingLoginId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "The login ID is missing or invalid."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **403** Forbidden - token validation failed
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: TokenMismatch403_
    
    ```
    {
      "error": "forbidden",
      "error_description": "The loginId, organizationId, or channel_id in the token does not match the request parameters."
    }
    ```
    
*   **404** Not found
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: PasskeyUserNotFound404_
    
    ```
    {
      "error": "not_found",
      "error_description": "No passkey user found with the provided login ID."
    }
    ```
    

### DELETE Delete a specific passkey credential

`DELETE /organizations/{organizationId}/oauth2/webauthn/passkey/user/{loginId}/credentials/{credentialId}`

Operation ID: `deletePasskeyCredential`. Security: ShopperToken (sfcc.pwdless\_login).

This endpoint deletes a specific WebAuthn passkey credential for a user. The endpoint validates the Shopper JWT signature and ensures that the loginId, organizationId, and channel\_id in the token match the values in the path and query parameters.

The SLAS client must have the `sfcc.pwdless_login` scope to access this endpoint.

This endpoint requires Shopper JWT authentication.

#### Parameters

*   `organizationId` (path, string, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/get-started.html#instance-types).  
    Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `channel_id` (query, string, required) The channel (B2C Commerce site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
    
    _Example_
    
    ```
    RefArch
    ```
    
*   `loginId` (path, string, required) The login ID (username) of the user whose passkey credential is being deleted  
    Minimum length: 1. Maximum length: 256. Example: `user@example.com`.
*   `credentialId` (path, string, required) The unique identifier of the credential to delete  
    Minimum length: 1. Maximum length: 1024. Example: `Y3JlZGVudGlhbElkMTIz`.
*   `Authorization` (header, string, required) Shopper JWT access token  
    Minimum length: 1. Maximum length: 4096. Example: `Bearer eyJ2ZXIiOiIxLjAiLCJraWQiOiI0ZTQyNTFkOS0zM2Y2LTRjMTMtYjZmZC1mOWJkNTJmYTZhNDciLCJ0eXAiOiJqd3QiLCJjbHYiOiJKMi4xLjAiLCJhbGciOiJFUzI1NiJ5...`.

#### Responses

*   **204** The passkey credential was deleted successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingParameter400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "The login ID or credential ID is missing or invalid."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **403** Forbidden - token validation failed
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: TokenMismatch403_
    
    ```
    {
      "error": "forbidden",
      "error_description": "The loginId, organizationId, or channel_id in the token does not match the request parameters."
    }
    ```
    
*   **404** Not found
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: PasskeyCredentialNotFound404_
    
    ```
    {
      "error": "not_found",
      "error_description": "No passkey credential found with the provided credential ID."
    }
    ```
    

### POST Request a one-time password (OTP) for a shopper.

`POST /organizations/{organizationId}/oauth2/otp/request`

Operation ID: `requestOtp`. Security: ShopperToken (sfcc.pwdless\_login).

Generates a one-time password (OTP) and delivers it to the shopper via the specified mode (email or callback). The OTP can then be used with the `/otp/verify` endpoint to verify the shopper.

When `mode` is `email`, the `email` field is required. A shopper is limited to 6 email OTP requests per 10-minute window. When `mode` is `callback`, the `callback_uri` field is required and must match a registered callback URI for the client.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `OtpRequest`.

_Example: otpRequest_

```
{
  "client_id": "12345678-1234-1234-1234-123456789012",
  "channel_id": "RefArch",
  "user_id": "shopper@example.com",
  "mode": "email",
  "email": "shopper@example.com",
  "locale": "en-GB"
}
```

#### Responses

*   **202** The OTP was generated and delivery was initiated successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Bad request
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingClientId400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing client_id."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **429** Too many requests
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: TooManyRequests429_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Too many OTP requests were made. Please try again later."
    }
    ```
    
*   **500** Internal server error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

### POST Verify a one-time password (OTP) for a shopper.

`POST /organizations/{organizationId}/oauth2/otp/verify`

Operation ID: `verifyOtp`. Security: ShopperToken (sfcc.pwdless\_login).

Verifies a one-time password (OTP) previously issued by the `/otp/request` endpoint. On success, the OTP token is consumed and cannot be reused. Each new call to `/otp/request` invalidates any previously issued OTP.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/x-www-form-urlencoded`. Schema: `OtpVerifyRequest`.

_Example: otpVerifyRequest_

```
{
  "pwd_action_token": "12345678",
  "client_id": "12345678-1234-1234-1234-123456789012",
  "channel_id": "RefArch",
  "user_id": "shopper@example.com"
}
```

#### Responses

*   **204** The OTP was verified successfully.
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
*   **400** Bad request or invalid/expired OTP
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: BadOrMissingAccessToken400_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Bad or missing access token."
    }
    ```
    
*   **401** Unauthorized
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: Unauthorized401_
    
    ```
    {
      "error": "invalid_client",
      "error_description": "Authorization failed."
    }
    ```
    
*   **429** Too many requests
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: TooManyRequests429_
    
    ```
    {
      "error": "invalid_request",
      "error_description": "Too many OTP verification attempts were made. Please try again later."
    }
    ```
    
*   **500** Internal server error
    
    Headers:
    
    *   `X-RateLimit-1M-Limit` (string) The 1 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-1M-Remaining` (string) The 1 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-1M-Reset` (string) The 1 minute time at which the current rate limit window resets in UTC epoch seconds.
    *   `X-RateLimit-5M-Limit` (string) The 5 minute maximum number of requests permitted per hour.
    *   `X-RateLimit-5M-Remaining` (string) The 5 minute number of requests remaining in the current rate limit window.
    *   `X-RateLimit-5M-Reset` (string) The 5 minute time at which the current rate limit window resets in UTC epoch seconds.
    
    Media type: `application/problem+json`. Schema: `Oauth2ErrorResponse`.
    
    _Example: InternalServerError500_
    
    ```
    {
      "error": "server_error",
      "error_description": "The server has encountered a situation that it doesn't know how to handle."
    }
    ```
    

## Schemas

### LoginRequest

Supports multiple custom parameters to invoke hooks in B2C Commerce API. Multiple custom parameters can be added. Use the `c_` prefix to distinguish custom query parameters from standard query parameters, for example: c\_captcha=true If there is a validation error, a 400 Bad\_Request with the details of the error is thrown.

*   `client_id` (_string_) SLAS client ID. Required when the grant type is `authorization_code_pkce`.  
    Maximum length: 40. Example: `z99ec276-cg53-4g94-cf72-76f300c6778zc`.
*   `response_type` (_object_) Must be `code`. Indicates that the client wants an authorization code (when the grant type is `authorization_code`).
    
    Includes all fields of `ResponseType`.
    
*   `redirect_uri` (_string_, required)
    
    The URI to which the server redirects the browser after the user grants the authorization. The URI must be registered with the SLAS client. A variety of URI formats and wildcards for host are supported, but app links like airbnb:// or fb:// are not. Examples of supported URIs:
    
    Examples of supported URIs:
    
    *   `http://localhost:3000/callback`
    *   `https://example.com/callback`
    *   `com.example.app:redirect_uri_path`
    *   `*.subdomain.topleveldomain.com`
    
      
    Maximum length: 256. Example: `http://localhost:3000/callback`.
*   `state` (_string_) Value to be sent by the client to determine the state between the authorization request and the server response. Optional, but strongly recommended.  
    Maximum length: 512. Example: `client-state`.
*   `scope` (_string_) Scopes to limit an application's access to a user's account.  
    Maximum length: 256. Example: `openid|offline_access|email`.
*   `usid` (_string_) The unique shopper ID.  
    Maximum length: 128. Example: `18cda486-fe32-4e27-888b-6e4f89938e67`.
*   `channel_id` (_string_, required) The channel that the request is for. For a B2C Commerce request, this is angalous to the site ID.  
    Maximum length: 100. Example: `RefArch`.
*   `code_challenge` (_string_)
    
    PKCE code verifier. Created by the client calling the `login` endpoint.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
    The `code_challenge` is optional when using a private client id for the token request.
    
      
    Minimum length: 43. Maximum length: 128. Example: `krc5G3_5lRUcXDUzFZQ88oJA_-ZmlHWkyGsgOrSLEWg`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Oauth2ErrorResponse

*   `error` (_string_, required)  
    Example: `invalid_client`.
*   `error_uri` (_string_)  
    Example: `https://api.commercecloud.salesforce.com/documentation/error/v1/errors/oauth-service`.
*   `error_description` (_string_)  
    Example: `Missing access token or refresh token.`.

### PasswordlessLoginRequest

A request for a passwordless login token. This is only available for registered users using B2C Commerce.

*   `user_id` (_string_, required) User ID for logging in.  
    Maximum length: 128. Example: `samantha.sampleson@example.com`.
*   `mode` (_string_, required) Password Action delivery modes  
    Allowed values: `callback`, `sms`, `email`. Example: `email`.
*   `locale` (_string_) The locale of the template. Required when the mode is `email` or `sms`.  
    Example: `en-us`.
*   `usid` (_string_) The shopper's unique identifier, if known. If not provided, a new USID is generated.  
    Example: `18cda486-fe32-4e27-888b-6e4f89938e67`.
*   `channel_id` (_string_, required) The channel (B2C Commerce site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
*   `callback_uri` (_string_)
    
    The callback URI. Required when the mode is `callback`. The `callback_uri` property will be validated against the callback URIs that have been registered with the SLAS client. The callback URI _must_ be a `POST` endpoint because the token will be included in the body.
    
    Wildcards are not allowed in the callback\_uri because this is a security risk that can expose the token. This is not considered an OAuth2 callback\_url.
    
      
    Example: `http://localhost:9050/passwordless/login/callback`.
*   `last_name` (_string_) The user's last name. Required when `register_customer` is `true`. The `last_name` parameter is not used when `register_customer` parameter is not added or is `false`.  
    Maximum length: 100. Example: `Sampleson`.
*   `email` (_string_) The user's email address. Required when `register_customer` is `true` and `user_id` is not an email address. The `email` parameter is not used when `register_customer` parameter is not added or is `false`.  
    Maximum length: 128. Example: `samantha.sampleson@example.com`.
*   `first_name` (_string_) The user's first name. Optional when `register_customer` is `true`. The `first_name` parameter is not used when `register_customer` parameter is not added or is `false`.  
    Maximum length: 100. Example: `Samantha`.
*   `phone_number` (_string_) The user's phone number. Optional when `register_customer` is `true`. The `phone_number` parameter is not used when `register_customer` parameter is not added or is `false`.  
    Maximum length: 48. Example: `17776665555`.
*   `customer_no` (_string_) The customer number assigned to the shopper profile when `register_customer` is set to `true`. If the `customer_no` already exists, the request fails. The `customer_no` parameter is optional and only used when `register_customer` is set to `true`.  
    Maximum length: 100. Example: `123456789`.

### TokenResponse

*   `access_token` (_string_, required)
    
    Short term shopper JWT that can be used to access Shopper APIs. Valid for 30 minutes.
    
    A trusted agent shopper JWT is valid for 15 min.
    
      
    Example: `eyJ2ZXIiOiIxLjAiLCJraWQiOiJTTEFTIiwidHlwIjoiand0IiwiY2x2IjoiSjIuMS4wIiwiYWxnIjoiRVMyNTYifQ.eyJhdWQiOiJjb3JlL2Rldi9idGluZ2V5bHRtMiIsImF1dCI6IkdVSUQiLCJzdWIiOiJ1c2lkOjo1NGFkMmM1YS05MWYwLTQ0YWItODE3Yy03M2Q2Yjg2ODcyZDk6OnVwbjpndWVzdCIsIm5iZiI6MTU4Mjg0NTYyNCwiY3R4Ijoic2ZkYy5jb21tZXJjZWNsb3VkIiwiaXNzIjoiY29yZS9kZXYvYnRpbmdleWx0bTIiLCJzdHkiOiJVc2VyIiwiaXN0IjoxLCJleHAiOjE1ODI4NDU3NDQsImlhdCI6MTU4Mjg0NTY1NCwianRpIjoiQzJDOTA0ODg2NDA3MDkwNDg4NjQwNzMyMjExNzQ1ODEyMTQzIn0.2a6lMBSY17PrhDO8pvEk7PCXW_nkguMHi4J-Tuirkz-ETB6rnKyuRjF5yD6B55tMvm8dO8ulAHyDYqjObMxLJg`.
*   `id_token` (_string_, required) User ID token. Valid for 30 minutes.  
    Example: `eyJraWQiOiI3NGU2YjMxZS1lYTczLTQ3OTYtOWRkYi1jMDJmZGI4ZDgwYmUiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2lkOmQ1MDBhMzY5LTc1MWQtNDkzYy1iNDAzLThmOThmYjg3MTdiNiIsImF1ZCI6IjU1M2FjOGFjLTRkYjktNGVkMy04MjVjLTNhZTNiZjVkMzI3YiIsImlzcyI6ImRldi51cy5zaG9wcGVyLmNjLnNhbGVzZm9yY2UuY29tIiwibmFtZSI6ImJsYWlyLnNsYXMudGVzdEBnbWFpbC5jb20iLCJleHAiOjE1OTExMTE0MzgsImlhdCI6MTU5MTEwOTYzOCwiZW1haWwiOiJibGFpci5zbGFzLnRlc3RAZ21haWwuY29tIn0.KgpAcq-G9Lz7IGnjkJlaFLFXYncVCwcVrRIuy3bEfgzRozqaDRvAori4oOz4RtgYjmoc5x2euoisHL0mVnHgPKOdYBty1wTJqneJEQt6hP4Kp0KFciID_ILCi-DE8VWS5t0NknnMP_iKhIkqcRL48iwPFUWkWA6AEWxE_yvJLNRLithsSxsx7EfBfpD8Hr2b5tMEwImQNmJNYGRTI4LSmcYspBORvJoAnfGpMC0kglxl40bhf5j4ItX4_DiWQC4zaGYD-HJV4BDr6C7iGCs5ZVPypF0yQD3iBio26fwj9Ys5WF9XMtPtqET2kqsz6fDC5GkE6HTUHH_r87jxbDq-8w`.
*   `refresh_token` (_string_, required)
    
    Long term refresh token that can be used to refresh an access token. Valid for 30 days.
    
    The refresh\_token will not be returned for trusted agents JWTs. A JWT for trusted agents expires after 15 minutes and is not refreshable. When expired, then app must restart the authorization flow and make another request to the /trusted-agent/authorize endpoint.
    
      
    Example: `EgMYpjfFKdlSy-a3PYeyihmP95IpIp3FaDpPmVH1yu8.lahomBi7zJbRa6yKAuAAiKu3lprTPsEueKwqcBvhRLU`.
*   `expires_in` (_integer_, required) Remaining access token expiry time, in seconds.  
    Example: `900`.
*   `refresh_token_expires_in` (_number_, required) Remaining refresh token expiry time, in seconds.  
    Example: `2592000`.
*   `token_type` (_TokenType_, required)
*   `usid` (_string_, required) The unique shopper ID. Returned when using the `client_credentials` grant type.  
    Example: `18cda486-fe32-4e27-888b-6e4f89938e67`.
*   `customer_id` (_string_, required) Customer's ID  
    Example: `1000005`.
*   `enc_user_id` (_string_, required) MD5 Hashed B2C Commerce user ID in uppercase.  
    Example: `45D39A8499A95288F82855427EBA99B5`.
*   `idp_access_token` (_string_, required) This is the access token that is returned from the IDP. The IDP access token is returned to be able to make calls into the IDP outside of SLAS.  
    Maximum length: 8192. Example: `eyJraWQiOiJYS21HbHVuSm0zSlBTMHNjQXZXV19XQlYtRi1wMkxLSDR0V05UMHVVSjVJIiwiYWxnIjoiUlMyNTYifQ.eyJ2ZXIiOjEsImp0aSI6IkFULjFMY0xxTWhqM2t0N1FKeFhxQ0VtdGZOOVV2eUcweW1meDFxZG9BdzF1NWMub2FyeXhveHF0QUtxaVFMbkM1ZDYiLCJpc3MiOiJodHRwczovL2Rldi05NTY1MjM2Lm9rdGEuY29tIiwiYXVkIjoiaHR0cHM6Ly9kZXYtOTU2NTIzNi5va3RhLmNvbSIsInN1YiI6Im9rdGEuc2xhcy50ZXN0IiwiaWF0IjoxNjc5Njk4MzA4LCJleHAiOjE2Nzk3MDE5MDgsImNpZCI6IjBvYTJrNXNma0JXZ0poTEVHNWQ2IiwidWlkIjoiMDB1MzhxZGpuU2NMT0IxbXE1ZDYiLCJzY3AiOlsib2ZmbGluZV9hY2Nlc3MiLCJvcGVuaWQiLCJlbWFpbCIsInByb2ZpbGUiXSwiYXV0aF90aW1lIjoxNjc5Njk4MzA2fQ.FDbGsnZGwTYVKGSlAo6jqcjG2HQ_BqQKRk72M5h69DRHyOM4wngsEELN_Wtgj3E77sP7IOmIKjiK5SFP17ADMbKZptVr2pqaMVF3PuU3Cbl_MgXZValfT-z12jHRq9sHMfsdTjY2RnvG44ZDFKc2no8mdL6IJ1MfCaZT5Tql5Ktq_UgudaWFsYqad3ETcmp5Y8ivz1bFnqud0sO9D9JzYOtfd9h71JKcsSC2rXc_Si-INPKKaGl8CDgaLXxu_Am9twJpUenHLpy0BerhcVvdFz7_611E53xOT_Esrc1pe-XAZtlYsJFnhxTBDT342ukiSWk2m6juVappv1GsRfUf2g`.
*   `idp_refresh_token` (_string_) This is the refresh token that is returned from the IDP. The IDP refresh token is returned to be able to make calls into the IDP outside of SLAS.  
    Maximum length: 128. Example: `EgMYpjfFKdlSy-a3PYeyihmP95IpIp3FaDpPmVH1yu8.lahomBi7zJbRa6yKAuAAiKu3lprTPsEueKwqcBvhRLU`.
*   `dnt` (_string_) Do not track  
    Maximum length: 5. Example: `true`.

### TokenRequest

*   `refresh_token` (_string_) The long-term token used to refresh the short term access token. Required only with a grant type of `refresh_token`.  
    Maximum length: 256.
*   `code` (_string_) Authorization code from the OAuth 2.1 service received in the front channel that is used to get access tokens and refresh tokens. Required with a grant type of `authorization_code` and `session_bridge`.  
    Maximum length: 256. Example: `M0t1K0pyoFKhBpUZnuUYO07xf8iYyMJrAc7h31h_ra8.gglPClJHsofqdTm_yPe5n6m2yCXzFmD8qICwIEjQGVA`.
*   `usid` (_string_) The shopper's unique identifier, if known. If not provided, a new USID is generated.  
    Example: `54ad2c5a-91f0-44ab-817c-73d6b86872d9`.
*   `grant_type` (_GrantType_, required)
*   `redirect_uri` (_string_)
    
    The redirect URI that was used when getting the authorization code. A variety of URI formats and wildcards for host are supported, but app links like `airbnb://` or `fb://` are not.
    
    Examples of supported URIs:
    
    *   `http://localhost:3000/callback`
    *   `https://example.com/callback`
    *   `com.example.app:redirect_uri_path`
    *   `*.subdomain.topleveldomain.com`
    
      
    Maximum length: 256. Example: `http://localhost:3000/callback`.
*   `code_verifier` (_string_)
    
    PKCE code verifier. Created by the client calling the `login` endpoint.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
    The `code_verifier` is optional when using a private client id for the token request.
    
      
    Maximum length: 128.
*   `client_id` (_string_) The SLAS client ID. Required when the grant type is `authorization_code_pkce`.  
    Maximum length: 40. Example: `z99ec276-cg53-4g94-cf72-76f300c6778zc`.
*   `channel_id` (_string_)
    
    The channel (B2C Commerce site) that the user is associated with.
    
    \*\*Important: We strongly recommended using the channel\_id query parameter because it will be required in the future.
    
    **NOTE - As of July 31, 2024**, SLAS will be requiring the `channel_id` query parameter in token requests.
    
      
    Maximum length: 100. Example: `RefArch`.
*   `dnt` (_string_)
    
    This is an optional parameter to set `Do Not Track` for the session.
    
    SLAS is making this available, but will not be used by B2C Commerce until after the 24.4 release.
    
    Values are:
    
    *   `false`
    *   `true`
    
    If not added the `dnt` value will default to `false`.
    
      
    Example: `true`.

### SessionBridgeTokenRequest

*   `code` (_string_, required) Authorization code returned from session bridge authorization received in the front channel that is used to get session bridge access tokens and refresh tokens. Required with a grant type of `session_bridge`. The SLAS client must have the `sfcc.session_bridge` scope to request a session bridge token.  
    Maximum length: 256. Example: `M0t1K0pyoFKhBpUZnuUYO07xf8iYyMJrAc7h31h_ra8.gglPClJHsofqdTm_yPe5n6m2yCXzFmD8qICwIEjQGVA`.
*   `client_id` (_string_, required) The SLAS public client ID for use with PKCE requests. This is a required parameter when using a public client.  
    Maximum length: 40. Example: `6c388ebd-6843-4863-aef9-781382c9e8cd`.
*   `channel_id` (_string_, required) The channel (B2C Commerce site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
*   `code_verifier` (_string_, required)
    
    PKCE code verifier. Created by the caller. This is a required parameter when using a public client.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
      
    Example: `Ar0lAwU_jsuA~ZXX8-JnMbZFxrnDot2OtgLEi1kOT_FxD6Bo0EQDbbrvoym9xHvatNGnNzrObLJeK6e4U9m4pveRMbdwNGa4jwiAlKGvijVn0PW0hqb03_w1gQE00wTo`.
*   `dwsid` (_string_, required)
    
    Cookie passed back from the '/authorize' endpoint call for session bridge. This parameter is optional and not needed if using the `dwsgst` parameter.
    
    **DEPRECATED** - As of January 31, 2024, SLAS will no longer support the SESB `dwsid` parameter for `guest` users for `session-bridge/token` calls. It is recommended to transition over to using a SESB `dwsgst` token.
    
    The `dwsid` will still be needed for `registered` user session-bridge/token calls.
    
      
    Example: `pATvWUO3KSdt-Kmcy-8-RsxKnoO4BMDwoec7ACVlW6tZNnhaOL7gt7mHqL-h7QYn5TyE61z0DeSMCqxngsWeHw==`.
*   `grant_type` (_string_, required) Grant Type  
    Allowed values: `authorization_code`, `refresh_token`, `client_credentials`, `authorization_code_pkce`, `session_bridge`.
*   `login_id` (_string_, required) The ID of the shopper for session bridge access. If requesting a token for a guest user set login\_id to `guest`.  
    Maximum length: 128. Example: `jack.shopper@example.com`.
*   `dwsgst` (_string_) Signed guest Json Web Token (JWT) that was obtained from B2C Commerce. This parameter is optional and not needed if using the guest `dwsid` parameter.  
    Example: `eyJraWQiOiIxNjgxNTU5OTkxNzkwIiwiYWxnIjoiRVMyNTYifQ.eyJ0ZW5hbnRJZCI6IkJHVk5fUzA1IiwiZHdzaWQiOiJuWHRhckdNU2ZxbnBaSUNJUGFKTHJSWGZ6b2lWYXBBU3BBTFNfeFdUMV9QZjRBWDA0N1lMQ1dSUFByM1BiSEl4d2RaODFiVGZoM3M1Wlgza2NhOG0zZz09IiwiY3VzdG9tZXJJZCI6ImJjQXI5N2NuMm1ZdmhjMGhqTGsxYmFXSzRqIiwiaWF0IjoxNjg1MTI4NjM2LCJleHAiOjE2ODUxMjkyMzksImlzcyI6ImNvbW1lcmNlY2xvdWQvcHJvZHVjdGlvbi9iZ3ZuczA1IiwidmVycyI6IjEiLCJ0eXBlIjoiRyJ9.BGY4kyOXbQSzZxubE3BrSzhf8ByehGUfJa7_J2XRQ93xY4dAOhF_xbXcHmBaEUBUzSny-Cf0pATzEaSsKpTxkg`.
*   `dwsrst` (_string_)
    
    Signed registered customer Json Web Token (JWT) that was obtained from B2C Commerce. This parameter is optional and not needed if using the registered user `dwsid` parameter.
    
    **NOTE:** The registered customer Json Web Token (JWT) will be available in ECOM versions 25.4 and higher.
    
      
    Example: `eyJraWQiOiIxNjMwOTM5MzAyODE0IiwiYWxnIjoiRVMyNTYifQ.eyJmbmFtZSI6Ikx1a2UiLCJkd3NpZCI6IkdkWWpSQjViZGVpU0xkb3Ixdy15QzRTZ1l3dDJHYl9Ec255OG5nZ2I3c0VDajVMWndnT0ZJWTZsa21sNlVRMXZoazl1SDVJUGxMek5rZTJhNTV2YU9nPT0iLCJ2ZXJzIjoiMiIsImlzcyI6InNsYXMvZGV2L2Jndm5fc3RnIiwidHlwZSI6IlIiLCJsbmFtZSI6IlNreXdhbGtlciIsInJjdXN0b21lcklkIjoiOGgzNHh6dDQxOTVpOHA1MmE2ejAzczIxNDgiLCJwaG9uZSI6bnVsbCwidGVuYW50SWQiOiJiZ3ZuX3N0ZyIsImN1c3RvbWVySWQiOiI0OHB1eXA4dTdmMmM5NHgzMTUxeDA4bGEweiIsImV4cCI6MTczNTE1NDQ4NiwiaWF0IjoxNzMyNTYyNDg2LCJlbWFpbCI6Imx1a2Uuc2t5d2Fsa2VyQG5hYm9vLm9yZyJ9.Q2nF0wuEl1X7aVZ-ycCwxDjjmq5toJred5AEDqKXXjj89BY_0HIQoAEMbx9UDqOmhjdBkxN4idVzYVoXcl0c2A`.
*   `usid` (_string_) The unique shopper ID. Returned when from session bridge authorization.  
    Example: `18cda486-fe32-4e27-888b-6e4f89938e67`.
*   `dnt` (_string_)
    
    This is an optional parameter to set `Do Not Track` for the session.
    
    SLAS is making this available, but will not be used by B2C Commerce until after the 24.4 release.
    
    Values are:
    
    *   `false`
    *   `true`
    
    If not added the `dnt` value will default to `false`.
    
      
    Example: `true`.

### TrustedSystemTokenRequest

A request for an access token on behalf of a registered user whose credentials are stored using a third party system.

*   `usid` (_string_) The shopper's unique identifier, if known. If not provided, a new USID is generated.  
    Example: `54ad2c5a-91f0-44ab-817c-73d6b86872d9`.
*   `grant_type` (_string_, required) Grant Type  
    Allowed values: `authorization_code`, `refresh_token`, `client_credentials`, `authorization_code_pkce`, `session_bridge`.
*   `hint` (_string_, required) Type of system used for Trusted System On Behalf of requests.  
    Allowed values: `ts_ext_on_behalf_of`.
*   `login_id` (_string_, required)
    
    The ID used by the shopper for trusted system access.
    
    If set to `guest`, a token is returned for a guest user.
    
      
    Maximum length: 128. Example: `samantha.sampleson@example.com`.
*   `idp_origin` (_string_, required) IDPs that work with SLAS. Use `ecom` when using B2C Commerce is the identity provider.  
    Allowed values: `apple`, `auth0`, `azure`, `azure_adb2c`, `cognito`, `default`, `ecom`, `facebook`, `forgerock`, `gigya`, `gigya_socialize`, `google`, `okta`, `ping`, `salesforce`.
*   `client_id` (_string_, required) The SLAS public client ID for use with trusted-system requests.  
    Maximum length: 40. Example: `6c388ebd-6843-4863-aef9-781382c9e8cd`.
*   `channel_id` (_string_, required) The channel (ECOM site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
*   `email_id` (_string_) The email address for the shopper that is used for trusted-system requests. If not provided, `login_id` is used instead.  
    Maximum length: 128. Example: `samantha.sampleson@example.com`.
*   `dnt` (_string_)
    
    This is an optional parameter to set `Do Not Track` for the session.
    
    SLAS is making this available, but will not be used by B2C Commerce until after the 24.4 release.
    
    Values are:
    
    *   `false`
    *   `true`
    
    If not added the `dnt` value will default to `false`.
    
    Note: The default value for `dnt` is set to `false` for SLAS token requests except for Trusted Agent token request. For Trusted Agent token requests the default value for `dnt` is `true`.
    
      
    Example: `true`.

### TrustedAgentTokenRequest

*   `agent_id` (_string_)
    
    The ID of the merchant. If passed in, the `agent_id` will be validated using the SUB claim in the response from Account Manager.
    
    This is an optional parameter unless the request is for a Trusted Agent on Behalf then `agent_id` is required.
    
      
    Maximum length: 40. Example: `merchant@example.com`.
*   `client_id` (_string_, required)
    
    The SLAS public client ID or SLAS private client ID for use with trusted-system requests.
    
    The `client_id` is not needed if a using a SLAS private `client_id` and the `_sfdc_client_auth` header.
    
      
    Maximum length: 40. Example: `6c388ebd-6843-4863-aef9-781382c9e8cd`.
*   `channel_id` (_string_, required) The channel (B2C Commerce site) that the user is associated with.  
    Maximum length: 100. Example: `RefArch`.
*   `code_verifier` (_string_, required)
    
    PKCE code verifier. Created by the caller.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
    The `code_verifier` is not needed if a using a SLAS private `client_id` and the `_sfdc_client_auth` header.
    
      
    Example: `Ar0lAwU_jsuA~ZXX8-JnMbZFxrnDot2OtgLEi1kOT_FxD6Bo0EQDbbrvoym9xHvatNGnNzrObLJeK6e4U9m4pveRMbdwNGa4jwiAlKGvijVn0PW0hqb03_w1gQE00wTo`.
*   `grant_type` (_string_, required) Grant Type  
    Allowed values: `authorization_code`, `refresh_token`, `client_credentials`, `authorization_code_pkce`, `session_bridge`.
*   `login_id` (_string_, required)
    
    The ID is the shopper for trusted agent access.
    
    For TAOB Guest the `login_id` must be set to `Guest`.
    
      
    Maximum length: 128. Example: `jack.shopper@example.com`.
*   `idp_origin` (_string_, required)
    
    The IDP that the user is associated with.
    
    For TAOB Guest the `idp_origin` parameter should be `slas`. If set to any other IDP origin a 400 Bad Request will be returned.
    
      
    Maximum length: 16. Example: `ecom`.
*   `usid` (_string_) The shopper's unique identifier, if known. If not provided, a new USID is generated.  
    Example: `54ad2c5a-91f0-44ab-817c-73d6b86872d9`.
*   `dnt` (_string_)
    
    This is an optional parameter to set `Do Not Track` for the session.
    
    SLAS is making this available, but will not be used by B2C Commerce until after the 24.4 release.
    
    Values are:
    
    *   `false`
    *   `true`
    
    If not added the `dnt` value will default to `true`
    
    Note: The default value for `dnt` is set to `true` for all TAOB flows. This is opposite from other SLAS token requests.
    
      
    Example: `true`.
*   `state` (_string_)
    
    This is an optional parameter to set state for the trusted agent session.
    
    If the `state` parameter is used it will be validated and a 400 Bad Request will be returned if missing or invalid.
    
    For TAOB Guest you must pass the `state` parameter to transfer the state from the TAOB Guest authorization call to the token call. The `state` parameter value is returned with the authorization code in the response url from the TAOB guest authorization call, for example: `.../taob/callback?code=HETXpvg5LKBNIHjDTWkRrf2MLVU&state=taob.gst.7bc7fb7f-e646-44fd-bc73-dfd5c3c9019b`.
    
    You would use `taob.gst.7bc7fb7f-e646-44fd-bc73-dfd5c3c9019b` for the `state` value in the TAOB request.
    
      
    Example: `taobgst.3ebdcbb6-ef87-4f41-8173-67728636e513`.

### PasswordActionRequest

A request for a password reset token. This is only available for resgistered users using B2C Commerce.

*   `user_id` (_string_, required) User ID for logging in. This is the id that is used to log into SFCC.  
    Maximum length: 128. Example: `samantha.sampleson@example.com`.
*   `mode` (_string_, required) Password Action delivery modes  
    Allowed values: `callback`, `sms`, `email`. Example: `email`.
*   `channel_id` (_string_, required) The channel (B2C Commerce site) that the user is associated with.  
    Example: `RefArch`.
*   `locale` (_string_) The locale of the template. Required when the mode is `email` or `sms`.  
    Example: `en-us`.
*   `client_id` (_string_) -| The public client ID. Requires setting `grant_type` to `passwordless_login_pkce`. When using the `hint` query parameter either a public or private client ID can be used.  
    Maximum length: 40. Example: `6b200ebd-7843-4073-aef9-792482c9e1de`.
*   `code_challenge` (_string_)
    
    PKCE code challenge. Created by the client.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
    Requires setting `grant_type` to `passwordless_login_pkce`
    
      
    Minimum length: 43. Maximum length: 128. Example: `Nx_Vf0-0W6SpyRVBVTbl8VSu2OE4yD2fZNExW6N3V_Q`.
*   `callback_uri` (_string_)
    
    The callback uri. Required when the mode is `callback`. The `callback_uri` property will be validated against the callback URIs that have been registered with the SLAS client. The callback URI _must_ be a `POST` endpoint because the token will be included in the body.
    
    Wildcards are not allowed in the callback\_uri because this is a security risk that can expose the token. This is not considered an OAuth2 callback\_url.
    
      
    Example: `http://localhost:9050/password/reset/callback`.
*   `idp_name` (_string_) The name of the 3rd party identity provider for the user ID  
    Example: `okta`.
*   `hint` (_string_) Adding a `hint` query parameter with a value of `cross_device` will remove the need to have the code\_challenge for password reset request. If the `hint` query parameter is used it must also be used in the password reset request.  
    Example: `cross_device`.

### PasswordActionVerifyRequest

A request for creating a new password using the password action token.

*   `client_id` (_string_, required) -| The public client ID. When using the `hint` query parameter either a public or private client ID can be used.  
    Maximum length: 40. Example: `6b200ebd-7843-4073-aef9-792482c9e1de`.
*   `pwd_action_token` (_string_, required) Password action token that was returned from the `/password/reset` endpoint.  
    Example: `QJO3CA7QTPVCQ3OMROXF2MTDDED3EEC3`.
*   `code_verifier` (_string_)
    
    PKCE code verifier. Created by the client.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
      
    Example: `Ar0lAwU_jsuA~ZXX8-JnMbZFxrnDot2OtgLEi1kOT_FxD6Bo0EQDbbrvoym9xHvatNGnNzrObLJeK6e4U9m4pveRMbdwNGa4jwiAlKGvijVn0PW0hqb03_w1gQE00wTo`.
*   `new_password` (_string_) The new password to set for the shopper associated with the password action token.  
    Example: `new_password`.
*   `channel_id` (_string_, required) The channel that the request is for. For a B2C Commerce request, this is angalous to the site ID.  
    Maximum length: 100. Example: `RefArch`.
*   `hint` (_string_) Adding a `hint` query parameter with a value of `cross_device` will remove the need to have the code\_verifier for password reset request. If the `hint` query parameter is used it must also have been used in the password action request.  
    Example: `cross_device`.
*   `user_id` (_string_) User ID for logging in. This is the id that is used to log into SFCC. Required only when hint is provided.  
    Maximum length: 128. Example: `samantha.sampleson@example.com`.

### PasswordLessLoginTokenRequest

A request for an access token using a passwordless token.

*   `grant_type` (_string_, required) Grant Type  
    Allowed values: `authorization_code`, `refresh_token`, `client_credentials`, `authorization_code_pkce`, `session_bridge`.
*   `hint` (_string_, required) Passwordless hint. Use `pwdless_login`.  
    Example: `pwdless_login`.
*   `pwdless_login_token` (_string_, required) Passwordless login token that was created from the user ID.  
    Example: `QJO3CA7QTPVCQ3OMROXF2MTDDED3EEC3`.
*   `client_id` (_string_) The public client ID.  
    Maximum length: 40. Example: `6b200ebd-7843-4073-aef9-792482c9e1de`.
*   `code_verifier` (_string_)
    
    PKCE code verifier. Created by the client.
    
    The `code_challenge` is created by SHA256 hashing the `code_verifier` and Base64 encoding the resulting hash.
    
    The `code_verifier` should be a high entropy cryptographically random string with a minimum of 43 characters and a maximum of 128 characters.
    
      
    Example: `Ar0lAwU_jsuA~ZXX8-JnMbZFxrnDot2OtgLEi1kOT_FxD6Bo0EQDbbrvoym9xHvatNGnNzrObLJeK6e4U9m4pveRMbdwNGa4jwiAlKGvijVn0PW0hqb03_w1gQE00wTo`.
*   `login_id` (_string_) The ID used by the shopper for password token request. When provided, login\_id must exactly match the ID used during passwordless login. ex. If passwordless login used `samantha.sampleson@example.com`, but the passwordless login token request provides `sam.sampleson@example.com`, the request fails due to mismatch.  
    Maximum length: 128. Example: `samantha.sampleson@example.com`.

### TokenActionRequest

*   `token` (_string_, required) Token to inspect or revoke.  
    Example: `EgMYpjfFKdlSy-a3PYeyihmP95IpIp3FaDpPmVH1yu8.lahomBi7zJbRa6yKAuAAiKu3lprTPsEueKwqcBvhRLU`.
*   `token_type_hint` (_string_) Token Type Hint  
    Allowed values: `access_token`, `refresh_token`.

### RegistrationStartRequest

WebAuthn registration request. Inherits most fields from PasswordActionVerifyRequest but does NOT use code\_verifier or new\_password fields.

*   `client_id` (_string_) OAuth client identifier. Required if Authorization header is not provided.  
    Minimum length: 36. Maximum length: 36. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `12345678-1234-1234-1234-123456789012`.
*   `pwd_action_token` (_string_, required) Password action token (TOTP) received by the user. The token length is either 6 or 8 digits, configurable in SLAS Admin.  
    Pattern: ^\[0-9\]{6,8}$. Example: `12345678`.
*   `user_id` (_string_, required) The ID of the user.  
    Maximum length: 128. Example: `user@example.com`.
*   `channel_id` (_string_, required) The ID of the channel.  
    Maximum length: 100. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `RefArch`.
*   `display_name` (_string_) Display name for the passkey.  
    Maximum length: 128. Example: `John Doe`.
*   `nick_name` (_string_) Nickname for the credential.  
    Maximum length: 128. Example: `My iPhone`.

### RegistrationFinishRequest

*   `client_id` (_string_, required) The ID of the OAuth client.  
    Maximum length: 36. Example: `12345678-1234-1234-1234-123456789012`.
*   `username` (_string_, required) Username for the credential.  
    Maximum length: 128. Example: `user@example.com`.
*   `credential` (_PublicKeyCredentialJson_, required)
*   `channel_id` (_string_, required) The ID of the channel.  
    Maximum length: 128. Example: `RefArch`.
*   `pwd_action_token` (_string_, required) Password action token. The token length is either 6 or 8 digits, configurable in SLAS Admin.  
    Maximum length: 8. Pattern: ^\[0-9\]{6,8}$. Example: `12345678`.

### AuthenticateRequest

*   `tenant_id` (_string_) The ID of the tenant.  
    Maximum length: 8. Example: `zzte_053`.
*   `client_id` (_string_, required) The ID of the OAuth client.  
    Minimum length: 36. Maximum length: 36. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `12345678-1234-1234-1234-123456789012`.
*   `channel_id` (_string_, required) The ID of the channel.  
    Maximum length: 100. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `RefArch`.
*   `user_id` (_string_) The ID of the user.  
    Maximum length: 128. Example: `user@example.com`.

### PublicKeyCredentialRequestOptions

Options for requesting a WebAuthn credential (returned by authenticate/start).

*   `challenge` (_string_) Base64url-encoded challenge.  
    Maximum length: 512. Example: `V2FsdGVyIFdoaXRlIFRlc3QgQ2hhbGxlbmdl`.
*   `timeout` (_integer_) Timeout value in milliseconds.  
    Example: `60000`.
*   `rpId` (_string_) The ID of the relying party.  
    Maximum length: 256. Example: `example.com`.
*   `allowCredentials` (_array of PublicKeyCredentialDescriptor_) Allowed credentials for authentication.
*   `userVerification` (_string_) The level of requirement for user verification.  
    Allowed values: `required`, `preferred`, `discouraged`. Example: `preferred`.
*   `extensions` (_object_) WebAuthn extensions.

### AuthenticateFinishRequest

*   `user_id` (_string_) The ID of the user.  
    Maximum length: 128. Example: `user@example.com`.
*   `channel_id` (_string_, required) The ID of the channel.  
    Maximum length: 100. Example: `RefArch`.
*   `client_id` (_string_, required) The ID of the OAuth client.  
    Minimum length: 36. Maximum length: 36. Example: `12345678-1234-1234-1234-123456789012`.
*   `email` (_string (email)_) User's email address.  
    Maximum length: 128. Example: `user@example.com`.
*   `tenant_id` (_string_) The ID of the tenant.  
    Maximum length: 8. Example: `zzte_053`.
*   `usid` (_string_) The unique session ID.  
    Maximum length: 128. Example: `87654321-4321-4321-4321-210987654321`.
*   `credential` (_PublicKeyCredentialJson_, required)

### AuthenticateResult

*   `credentialId` (_string_) The credential ID that was used for authentication.  
    Maximum length: 1024. Example: `AQIDBAUGBwgJCgsMDQ4PEA`.
*   `username` (_string_) The authenticated username.  
    Maximum length: 128. Example: `user@example.com`.
*   `success` (_boolean_) Specifies whether authentication was successful (true) or not (false).  
    Example: `true`.
*   `tokenResponse` (_TokenResponse_)

### PasskeyUser

Represents a passkey user with their associated credentials

*   `id` (_integer (int32)_) Unique identifier for the passkey user  
    Example: `26`.
*   `userName` (_string_) The username of the passkey user  
    Maximum length: 128. Example: `user@example.com`.
*   `displayName` (_string_) The display name of the passkey user  
    Maximum length: 256. Example: `John Doe`.
*   `userHandle` (_string_) The user handle (WebAuthn user ID)  
    Maximum length: 128. Example: `yRU-7pWyWUE6nw8hztqqUZG635p7UKDDb2lbC1FyF78`.
*   `slasUserId` (_integer (int32)_) The associated SLAS user ID  
    Example: `10000`.
*   `credentials` (_array of PasskeyCredential_) Set of passkey credentials associated with this user  
    Unique items.

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### OtpRequest

A request to generate and deliver a one-time password (OTP) to a shopper.

*   `client_id` (_string_, required) The ID of the OAuth client.  
    Minimum length: 36. Maximum length: 36. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `12345678-1234-1234-1234-123456789012`.
*   `channel_id` (_SiteId_, required)
*   `user_id` (_string_, required) User ID for the shopper requesting the OTP.  
    Maximum length: 128. Example: `shopper123`.
*   `mode` (_string_, required) Password Action delivery modes  
    Allowed values: `callback`, `sms`, `email`. Example: `email`.
*   `email` (_string_) Required when `mode` is `email`. Must match a registered email for the shopper.  
    Maximum length: 128. Example: `shopper@example.com`.
*   `callback_uri` (_string_) Required when `mode` is `callback`. Must match a registered callback URI for the client. The callback URI must be a `POST` endpoint. Wildcards are not allowed.  
    Maximum length: 256. Example: `https://example.com/otp-callback`.
*   `locale` (_object_) The locale for the OTP delivery template. Defaults to `en-US` for email mode.
    
    Includes all fields of `LanguageCountry`.
    

### OtpVerifyRequest

A request to verify a one-time password (OTP) token for a shopper.

*   `pwd_action_token` (_string_, required) Password action token (TOTP) received by the user. The token length is either 6 or 8 digits, configurable in SLAS Admin.  
    Pattern: ^\[0-9\]{6,8}$. Example: `12345678`.
*   `client_id` (_string_, required) The ID of the OAuth client.  
    Minimum length: 36. Maximum length: 36. Pattern: ^\[A-Za-z0-9\_-\]+$. Example: `12345678-1234-1234-1234-123456789012`.
*   `channel_id` (_SiteId_, required)
*   `user_id` (_string_, required) The user ID of the shopper whose OTP is being verified.  
    Maximum length: 128. Example: `shopper123`.

### ResponseType

Response Type

Type: `string`.

Allowed values: `code`. Example: `code`.

### TokenType

Token Type

Type: `string`.

Allowed values: `Bearer`. Example: `Bearer`.

### GrantType

Grant Type

Type: `string`.

Allowed values: `authorization_code`, `refresh_token`, `client_credentials`, `authorization_code_pkce`, `session_bridge`. Example: `authorization_code`.

### PublicKeyCredentialJson

WebAuthn credential representation. The response field can contain either AuthenticatorAttestationResponseJson (for registration) or AuthenticatorAssertionResponseJson (for authentication).

*   `id` (_string_, required) Base64url-encoded credential ID  
    Maximum length: 256. Example: `AQIDBAUGBwgJCgsMDQ4PEA`.
*   `rawId` (_string_, required) Base64url-encoded raw credential ID.  
    Maximum length: 256. Example: `AQIDBAUGBwgJCgsMDQ4PEA`.
*   `type` (_string_, required) The type of credential.  
    Allowed values: `public-key`. Example: `public-key`.
*   `clientExtensionResults` (_string_, nullable) WebAuthn client extension results (typically empty).  
    Maximum length: 100.
    
    _Example_
    
    ```
    {
      "extensions": {}
    }
    ```
    
*   `response` (_AuthenticatorAttestationResponseJson | AuthenticatorAssertionResponseJson_, required) Authenticator response (attestation for registration, assertion for authentication)
    
    One of: `AuthenticatorAttestationResponseJson`, `AuthenticatorAssertionResponseJson`.
    

### PublicKeyCredentialDescriptor

Public key credential descriptor.

*   `type` (_string_, required) Credential type.  
    Allowed values: `public-key`. Maximum length: 256. Example: `public-key`.
*   `id` (_string_, required) The base64url-encoded ID of the credential.  
    Maximum length: 64. Example: `AQIDBAUGBwgJCgsMDQ4PEA`.
*   `transports` (_array of string_) Authenticator transports.  
    Items: Allowed values: `usb`, `nfc`, `ble`, `internal`. Maximum length: 8. Example: `usb`.
    
    _Example_
    
    ```
    [
      "internal",
      "usb"
    ]
    ```
    

### PasskeyCredential

Represents a WebAuthn passkey credential

*   `id` (_integer (int32)_) Unique identifier for the credential  
    Example: `20`.
*   `userId` (_integer (int32)_) The ID of the user who owns this credential  
    Example: `26`.
*   `credentialId` (_string_) The WebAuthn credential ID  
    Maximum length: 1024. Example: `SVKfbUGBXofb2JzliJrMtZDENYByWgq_j4-p2M_3wC4`.
*   `nickName` (_string_) User-friendly name for the credential  
    Maximum length: 32. Example: `Fingerprint`.
*   `publicKey` (_string_) The public key associated with this credential  
    Maximum length: 1024. Example: `pQECAyYgASFYIHM_4IKLMC8dboiRNfD0E0Gk4LmCTIgEyCTr-9SyHHeIIlggfn5_AzAl67kttLXWb-_Ts6MG7WHKoXzlKtame_wEYPE`.
*   `userHandle` (_string_) The user handle associated with this credential  
    Maximum length: 128. Example: `yRU-7pWyWUE6nw8hztqqUZG635p7UKDDb2lbC1FyF78`.
*   `signatureCount` (_string_) The signature counter for replay attack prevention  
    Maximum length: 8. Example: `42`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### AuthenticatorAttestationResponseJson

Authenticator response for registration (attestation).

*   `clientDataJSON` (_array of object_, required) Base64url-encoded client data JSON.
    *   `id` (_string (byte)_)  
        Example: `eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiVjJGc2RHVnlJRmRvYVhSbElGUmxjM1FnUTJoaGJHeGxibWRsIiwib3JpZ2luIjoiaHR0cHM6Ly9leGFtcGxlLmNvbSJ9`.
*   `attestationObject` (_array of object_, required) Base64url-encoded attestation object.
    *   `id` (_string (byte)_)  
        Example: `o2NmbXRkbm9uZWdhdHRTdG10oGhhdXRoRGF0YVikSZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2NFAAAAAK3OAAI1vMYKZIsLJfHwVQMAIAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8gpQECAyYgASFYIIGjL8Hs9Yz5LvVGBnGJlGYKbJZXLqLLnKLJKLJLKLJLIlgg`.

### AuthenticatorAssertionResponseJson

Authenticator response for authentication (assertion).

*   `authenticatorData` (_array of object_, required) Base64url-encoded authenticator data
    *   `id` (_string (byte)_)  
        Example: `SZYN5YgOjGh0NBcPZHZgW4_krrmihjLHmVzzuoMdl2MFAAAAAQ`.
*   `clientDataJSON` (_array of object_, required) Base64url-encoded client data JSON.
    *   `id` (_string (byte)_)  
        Example: `eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiVjJGc2RHVnlJRmRvYVhSbElGUmxjM1FnUTJoaGJHeGxibWRsIiwib3JpZ2luIjoiaHR0cHM6Ly9leGFtcGxlLmNvbSJ9`.
*   `signature` (_array of object_, required) Base64url-encoded signature.
    *   `id` (_string (byte)_)  
        Example: `MEYCIQDqwzerkQlKKLJKLJKLJKLJKLJKLJKLJKLJKLJKLJKLJAiEA`.
*   `userHandle` (_array of object_, nullable) Base64url-encoded user handle.
    *   `id` (_string (byte)_)  
        Example: `dXNlckBleGFtcGxlLmNvbQ`.

<!-- document id=7c347a1451fd10736ab905f02e7f6b8670649ff643934b1ae582b7796ea68c6b url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/auth-admin.md -->

Shopper Login (SLAS) Admin

# Shopper Login (SLAS) Admin

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/auth-admin/auth-admin-oas-v1-public.yaml)

## API Overview

The SLAS Admin API is a companion to the main [Shopper Login and API Access Service](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary) (SLAS), which enables secure access to Commerce Cloud’s Shopper APIs. The SLAS Admin API is only used for administration tasks, not for requesting access to the Shopper APIs.

**Important:** Before using this API, follow the instructions in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) from the Get Started guides. The guide provides a complete set of instructions for setting up a SLAS client.

For more information, see the [SLAS guides](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html).

### Tenant Id

In context of SLAS administration a tenant identifier is used instead of the organization identifier.

A B2C Commerce instance is considered a “tenant” when it's associated with a supporting system, such as the Shopper Login and API Access Service (SLAS). A tenant ID begins with a four-character realm ID, followed by an underscore (`_`) and an instance ID.

These are example tenant IDs for various types of instances:

| Instance Type | Realm ID | Instance ID | Tenant ID |
| --- | --- | --- | --- |
| Staging | bcgl | stg | bcgl\_stg |
| On-demand sandbox | zzte | 053 | zzte\_053 |
| POD sandbox | zzrf | s01 | zzrf\_s01 |

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Related APIs

*   [Shopper Login (SLAS)](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=Summary) — Authenticate shoppers and obtain access tokens.

**Version:** 1.19.1

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth-admin/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `BearerToken` (http) A security scheme that supplements SLAS Administration APIs that are secured with an B2c Commerce Account Manager JWT. This security scheme expects a valid B2C Commerce Account Manager Bearer token passed in the Authorization header to permit API access.
    *   HTTP scheme: bearer (JWT)

## Operations

### GET Retrieve a tenant by tenant ID.

`GET /tenants/{tenantId}`

Operation ID: `retrieveTenant`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Retrieve a tenant by tenant ID.

#### Parameters

*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Responses

*   **200** The tenant was retrieved successfully.
    
    Media type: `application/json`. Schema: `Tenant`.
    
    _Example: Tenant_
    
    ```
    {
      "createdBy": "slas",
      "modifiedBy": "slas",
      "createdTime": "2021-02-25T00:55:54.119+0000",
      "modifiedTime": "2021-02-25T00:55:54.119+0000",
      "tenantId": "slsa_dev",
      "merchantId": 2,
      "description": "SLAS Default Tenant Two",
      "contact": "Tenant Two",
      "emailAddress": "tenant2@slas.tst",
      "phoneNo": "111-222-4444",
      "tier": "S",
      "requestQuotaPerMinute": 8000,
      "isDeleted": false,
      "status": "CLEAR"
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TenantRequestException400_
    
    ```
    {
      "type": "TenantRequestException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id is invalid"
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TenantException401_
    
    ```
    {
      "type": "TenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id is invalid"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TenantNotFoundException404_
    
    ```
    {
      "type": "TenantNotFoundException",
      "title": "Unable to retrieve resource because no resource was found with that value",
      "detail": "Tenant id Not Found"
    }
    ```
    

### PUT Create or update a tenant. Use the request body to provide identification and contact information for the tenant and its associated merchant.

`PUT /tenants/{tenantId}`

Operation ID: `registerTenant`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

This API is used to create or update a tenant. The tenant ID is the unique identifier for the tenant and is used in all subsequent API calls. The tenant ID must be unique across all tenants in the system.

#### Parameters

*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Request body (required)

Media type: `application/json`. Schema: `TenantDto`.

_Example: TenantDto_

```
{
  "tenantId": "slsa_dev",
  "merchantName": "Popular Merchant",
  "description": "Merchant Description",
  "contact": "Jerry Smith",
  "emailAddress": "jerry@merchant.com",
  "phoneNo": "801-555-1234"
}
```

#### Responses

*   **200** The tenant was updated successfully.
    
    Media type: `application/json`. Schema: `Tenant`.
    
    _Example Tenant: same as GET /tenants/{tenantId} 200 response._
    
*   **201** The tenant was created successfully.
    
    Media type: `application/json`. Schema: `Tenant`.
    
    _Example Tenant: same as GET /tenants/{tenantId} 200 response._
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TenantUpdateException400_
    
    ```
    {
      "type": "TenantUpdateException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not updated"
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TenantUpdateException401_
    
    ```
    {
      "type": "TenantUpdateException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not updated"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TenantNotFoundException404_
    
    ```
    {
      "type": "TenantNotFoundException",
      "title": "Unable to retrieve resource because no resource was found with that value",
      "detail": "Tenant id Not Found"
    }
    ```
    
*   **409** Conflict
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: TenantAlreadyExistsException409_
    
    ```
    {
      "type": "TenantAlreadyExistsException",
      "title": "Tenant[abcd_prd] already exists!",
      "detail": "Tenant already exists"
    }
    ```
    

### POST Log out multiple shoppers in a single request by revoking active refresh and access tokens for each shopper and all their sessions.

`POST /tenants/{tenantId}/batch-logout`

Operation ID: `batchLogout`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

For each valid shopper in the request, this operation revokes the shopper's active refresh tokens and inactivates their active access tokens issued before the call, across all sessions. As a result, the shopper must log in again with their existing password (this action doesn't force a password change). For more information, see [Log Out Multiple Shoppers](https://developer.salesforce.com/docs/commerce/sfra/guide/slas-batch-logout.html).

#### Parameters

*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.
*   `channelId` (query, string, required) The identifier of the sales channel (site).  
    Maximum length: 100. Example: `SiteGenesis`.

#### Request body (required)

Media type: `application/json`. Schema: `BatchLogoutRequest`.

_Example: BatchLogoutRequest_

```
{
  "loginIds": [
    "user1@example.com",
    "user2@example.com"
  ]
}
```

#### Responses

*   **200** The batch logout request was processed successfully. The detailed message in response body will indicate which shoppers were actually logged out and which ones failed and why.
    
    Media type: `application/json`. Schema: `BatchLogoutResponse`.
    
    _Example: BatchLogoutResponse_
    
    ```
    {
      "results": [
        {
          "loginId": "user1@example.com",
          "status": "success"
        },
        {
          "loginId": "user2@example.com",
          "status": "failure",
          "errorMessage": "User not found"
        }
      ],
      "totalProcessed": 2,
      "successCount": 1,
      "failureCount": 1
    }
    ```
    
*   **400** The request is badly formatted or constructed. If syntactically the request was correct but the loginIds provided did not result in shoppers getting logged out, the result will still be a 200 with details in the response body.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: BatchLogoutRequestException400_
    
    ```
    {
      "type": "BadRequestException",
      "title": "Unable to process resource because the request body was invalid",
      "detail": "Batch size 51 exceeds maximum allowed: 50"
    }
    ```
    
*   **401** Incorrect Authorization provided.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: BatchLogoutTenantException401_
    
    ```
    {
      "type": "TenantException",
      "title": "Unable to process resource because the tenant id was invalid and/or does not match authorization",
      "detail": "Tenant id is invalid"
    }
    ```
    

### GET Retrieve/Get all tenant clients.

`GET /tenants/{tenantId}/clients`

Operation ID: `retrieveClients`. Security: BearerToken (SLAS\_SERVICE\_ADMIN).

Retrieve a list of SLAS clients associated with the tenant\_id.

#### Parameters

*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Responses

*   **200** All tenant clients retrieved successfully.
    
    Media type: `application/json`. Schema: `ClientListResponse`.
    
    _Example: ClientListResponse_
    
    ```
    {
      "data": [
        {
          "clientId": "a462b606-317c-4a3c-90a7-4b0b938f3807",
          "secret": "",
          "name": "Shop Mart",
          "scopes": [
            "sfcc.products sfcc.catalogs sfcc.products.ro"
          ],
          "redirectUri": "http://localhost:9010/callback",
          "callbackUri": "http://localhost:9010/pwd/reset/callback",
          "channels": [
            "SiteGenesis",
            "OtherSite"
          ],
          "isPrivateClient": true,
          "loginEpRestrict": false,
          "isSixDigitOtp": false,
          "strictClientAuth": false
        },
        {
          "clientId": "726bde86-7b99-415d-98ec-9290bad18904",
          "secret": "",
          "name": "High Adventure Wear",
          "scopes": [
            "sfcc.products sfcc.catalogs sfcc.products.ro"
          ],
          "redirectUri": "http://localhost:9010/callback",
          "callbackUri": "http://localhost:9010/pwd/reset/callback",
          "channels": [
            "SiteGenesis",
            "OtherSite"
          ],
          "isPrivateClient": true,
          "loginEpRestrict": false,
          "isSixDigitOtp": false,
          "strictClientAuth": false
        },
        {
          "clientId": "slas-default-client-1",
          "secret": "",
          "name": "Shop Salesforce",
          "scopes": [
            "sfcc.products.ro sfcc.catalogs.ro"
          ],
          "redirectUri": "http://localhost:9010/callback",
          "callbackUri": "http://localhost:9010/pwd/reset/callback",
          "channels": [
            "SiteGenesis",
            "OtherSite"
          ],
          "isPrivateClient": true,
          "loginEpRestrict": false,
          "isSixDigitOtp": false,
          "strictClientAuth": false
        }
      ]
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientTenantException401_
    
    ```
    {
      "type": "ClientTenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not found. Please check the tenant id."
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientNotFoundException404_
    
    ```
    {
      "type": "ClientNotFoundException",
      "title": "Unable to retrieve resource because no resource was found with that value",
      "detail": "Client Not Found"
    }
    ```
    

### GET Retrieve a client.

`GET /tenants/{tenantId}/clients/{clientId}`

Operation ID: `retrieveClient`. Security: BearerToken (SLAS\_SERVICE\_ADMIN).

Retrieve a client by client ID. The client ID is the unique identifier for the client and is used in all subsequent API calls. The client ID must be unique across all tenants in the system.

#### Parameters

*   `clientId` (path, string, required) The SLAS client identifier.  
    Maximum length: 36. Example: `876aff68-6ee5-474f-932d-c90c1d79bcf7`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Responses

*   **200** The client was retrieved successfully.
    
    Media type: `application/json`. Schema: `Client`.
    
    _Example: Client_
    
    ```
    {
      "clientId": "client-id1",
      "name": "High Adventure Wear",
      "secret": "secret1234",
      "scopes": [
        "sfcc.products sfcc.catalogs sfcc.customers:ro"
      ],
      "redirectUri": "http://localhost/callback",
      "callbackUri": "http://localhost:9010/pwd/reset/callback",
      "channels": [
        "SiteGenesis",
        "OtherSite"
      ],
      "isPrivateClient": true,
      "loginEpRestrict": false,
      "isSixDigitOtp": false,
      "strictClientAuth": false
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientRequestException400_
    
    ```
    {
      "type": "ClientRequestException",
      "title": "Unable to retrieve resource because the client id was invalid",
      "detail": "Client id is invalid"
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientTenantException401_
    
    ```
    {
      "type": "ClientTenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not found. Please check the tenant id."
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientNotFoundException404_
    
    ```
    {
      "type": "ClientNotFoundException",
      "title": "Unable to retrieve resource because no resource was found with that value",
      "detail": "Client Not Found"
    }
    ```
    

### PUT Create or update a client.

`PUT /tenants/{tenantId}/clients/{clientId}`

Operation ID: `registerClient`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

It is strongly advised to refrain from using the “sfcc-shopper-context.rw” scope with a PUBLIC Client because it offers fewer protections and could potentially enable malicious actors to access Shopper Context enabled promotions. It is highly recommended to use “sfcc-shopper-context.rw” scope with a private client.

#### Parameters

*   `clientId` (path, string, required) The SLAS client identifier.  
    Maximum length: 36. Example: `876aff68-6ee5-474f-932d-c90c1d79bcf7`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Request body (required)

Media type: `application/json`. Schema: `ClientRequest`.

_Example: ClientRequest_

```
{
  "clientId": "client-id1",
  "secret": "secret12345",
  "name": "High Adventure Wear",
  "scopes": [
    "sfcc.products",
    "sfcc.catalogs",
    "sfcc.products.ro"
  ],
  "redirectUri": [
    "http://localhost:9010/callback"
  ],
  "callbackUri": [
    "http://localhost:9010/pwd/reset/callback"
  ],
  "channels": [
    "SiteGenesis",
    "OtherSite"
  ],
  "isPrivateClient": true,
  "loginEpRestrict": false,
  "isSixDigitOtp": false,
  "strictClientAuth": false
}
```

#### Responses

*   **200** The client was updated successfully. A secret is only returned when a secret was sent with the update request.
    
    Media type: `application/json`. Schema: `Client`.
    
    _Example: ClientRequest_
    
    ```
    {
      "clientId": "client-id1",
      "name": "High Adventure Wear",
      "secret": "secret12345",
      "scopes": [
        "sfcc.products",
        "sfcc.catalogs",
        "sfcc.customers:ro"
      ],
      "redirectUri": "http://localhost:9010/callback",
      "callbackUri": "http://localhost:9010/pwd/reset/callback",
      "channels": [
        "SiteGenesis",
        "OtherSite"
      ],
      "isPrivateClient": true,
      "loginEpRestrict": false,
      "isSixDigitOtp": false,
      "strictClientAuth": false
    }
    ```
    
*   **201** The client was created successfully. This is the only time the secret is returned.
    
    Media type: `application/json`. Schema: `Client`.
    
    _Example ClientRequest: same as PUT /tenants/{tenantId}/clients/{clientId} 200 response._
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientRequestException400_
    
    ```
    {
      "type": "ClientRequestException",
      "title": "Unable to retrieve resource because the client id was invalid",
      "detail": "Client id is invalid"
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientTenantException401_
    
    ```
    {
      "type": "ClientTenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not found. Please check the tenant id."
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientNotFoundException404_
    
    ```
    {
      "type": "ClientNotFoundException",
      "title": "Unable to retrieve resource because no resource was found with that value",
      "detail": "Client Not Found"
    }
    ```
    
*   **409** Conflict
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientConflictException409_
    
    ```
    {
      "type": "ClientConflictException",
      "title": "Unable to create resource because a duplicate resource was found",
      "detail": "Client was not created. Duplicate resource was found."
    }
    ```
    

### DELETE Delete a client.

`DELETE /tenants/{tenantId}/clients/{clientId}`

Operation ID: `deleteClient`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Delete a client by client ID.

#### Parameters

*   `clientId` (path, string, required) The SLAS client identifier.  
    Maximum length: 36. Example: `876aff68-6ee5-474f-932d-c90c1d79bcf7`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Responses

*   **204** No content
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientRequestException400_
    
    ```
    {
      "type": "ClientRequestException",
      "title": "Unable to retrieve resource because the client id was invalid",
      "detail": "Client id is invalid"
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientTenantException401_
    
    ```
    {
      "type": "ClientTenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not found. Please check the tenant id."
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientNotFoundException404_
    
    ```
    {
      "type": "ClientNotFoundException",
      "title": "Unable to retrieve resource because no resource was found with that value",
      "detail": "Client Not Found"
    }
    ```
    

### GET Retrieve/get a password action template.

`GET /tenants/{tenantId}/clients/{clientId}/password-action-templates`

Operation ID: `retrievePwdActionTemplate`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Retrieve a password action template by client ID.

#### Parameters

*   `clientId` (path, string, required) The SLAS client identifier.  
    Maximum length: 36. Example: `876aff68-6ee5-474f-932d-c90c1d79bcf7`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.
*   `channelId` (query, string, required) The identifier of the sales channel (site).  
    Maximum length: 100. Example: `SiteGenesis`.
*   `actionType` (query, string, required) The type of password action (reset or create).
    
    Describes the type of action that the password action template will be used for. Here are the actions that each enumerated string refers to: - `PWDLESS_LOGIN`: Passwordless login - `PWD_RESET_ACTION`: Password reset - `PWD_RESET_CROSS_DEVICE_ACTION`: Password reset for cross-device flow
    
      
    Allowed values: `PWDLESS_LOGIN`, `PWD_RESET_ACTION`, `PWD_RESET_CROSS_DEVICE_ACTION`. Maximum length: 36. Example: `PWDLESS_LOGIN`.
*   `templateType` (query, string, required) The type of email template.  
    Allowed values: `EMAIL`, `SMS`. Maximum length: 8. Example: `EMAIL`.

#### Responses

*   **200** The password action template was retrieved successfully.
    
    Media type: `application/json`. Schema: `PasswordActionTemplate`.
    
    _Example: PasswordActionTemplate_
    
    ```
    {
      "channelId": "SiteGenesis",
      "name": "Passwordless SMS Template",
      "subject": "Passwordless Token Request",
      "link": "This is your passwordless token: ${token}",
      "locale": "en-us",
      "actionType": "PWDLESS_LOGIN",
      "templateType": "SMS",
      "template": "Passwordless Login Token Request\n\nHello ${name},\nYou're receiving this because you requested a passwordless login token for your account.\n${link}"
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: BadRequestException400_
    
    ```
    {
      "type": "BadRequestException",
      "title": "Unable to update resource because the request body was invalid",
      "detail": "Request body is invalid."
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientTenantException401_
    
    ```
    {
      "type": "ClientTenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not found. Please check the tenant id."
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: PasswordActionTemplateNotFoundException404_
    
    ```
    {
      "type": "PasswordActionTemplateNotFoundException",
      "title": "Template was not found",
      "detail": "Template was not found."
    }
    ```
    

### PUT Create or update a password action template.

`PUT /tenants/{tenantId}/clients/{clientId}/password-action-templates`

Operation ID: `registerPwdActionTemplate`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Create or update a password action template by client ID.

#### Parameters

*   `clientId` (path, string, required) The SLAS client identifier.  
    Maximum length: 36. Example: `876aff68-6ee5-474f-932d-c90c1d79bcf7`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Request body (required)

Media type: `application/json`. Schema: `PasswordActionTemplate`.

_Example: PasswordActionTemplateRequest_

```
{
  "channelId": "SiteGenesis",
  "name": "Passwordless SMS Template",
  "subject": "Passwordless Token Request",
  "link": "This is your passwordless token: ${token}",
  "locale": "en-us",
  "actionType": "PWDLESS_LOGIN",
  "templateType": "SMS",
  "template": "Passwordless Login Token Request\nHello ${name},\nYou're receiving this because you requested a passwordless login token for your account.\n${link}"
}
```

#### Responses

*   **200** The password action template was updated successfully.
    
    Media type: `application/json`. Schema: `PasswordActionTemplate`.
    
    _Example PasswordActionTemplate: same as GET /tenants/{tenantId}/clients/{clientId}/password-action-templates 200 response._
    
*   **201** A password action template was created successfully.
    
    Media type: `application/json`. Schema: `PasswordActionTemplate`.
    
    _Example PasswordActionTemplate: same as GET /tenants/{tenantId}/clients/{clientId}/password-action-templates 200 response._
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: PasswordActionTemplateCreateException400_
    
    ```
    {
      "type": "PasswordActionTemplateCreateException",
      "title": "Template was not created or updated",
      "detail": "Template was not created or updated."
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientTenantException401_
    
    ```
    {
      "type": "ClientTenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not found. Please check the tenant id."
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: PasswordActionTemplateNotFoundException404_
    
    ```
    {
      "type": "PasswordActionTemplateNotFoundException",
      "title": "Template was not found",
      "detail": "Template was not found."
    }
    ```
    

### DELETE Delete a password action template.

`DELETE /tenants/{tenantId}/clients/{clientId}/password-action-templates`

Operation ID: `deletePwdActionTemplate`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Delete a password action template.

#### Parameters

*   `clientId` (path, string, required) The SLAS client identifier.  
    Maximum length: 36. Example: `876aff68-6ee5-474f-932d-c90c1d79bcf7`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.
*   `channelId` (query, string, required) The identifier of the sales channel (site).  
    Maximum length: 100. Example: `SiteGenesis`.
*   `actionType` (query, string, required) The type of password action (reset or create).
    
    Describes the type of action that the password action template will be used for. Here are the actions that each enumerated string refers to: - `PWDLESS_LOGIN`: Passwordless login - `PWD_RESET_ACTION`: Password reset - `PWD_RESET_CROSS_DEVICE_ACTION`: Password reset for cross-device flow
    
      
    Allowed values: `PWDLESS_LOGIN`, `PWD_RESET_ACTION`, `PWD_RESET_CROSS_DEVICE_ACTION`. Maximum length: 36. Example: `PWDLESS_LOGIN`.
*   `templateType` (query, string, required) The type of email template.  
    Allowed values: `EMAIL`, `SMS`. Maximum length: 8. Example: `EMAIL`.
*   `locale` (query, string, required) A descriptor for a geographical region by both a language and country code.  
    Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

#### Responses

*   **204** No content
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: PasswordActionTemplateDeleteException400_
    
    ```
    {
      "type": "PasswordActionTemplateDeleteException",
      "title": "Template was not deleted",
      "detail": "Template was not deleted."
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ClientTenantException401_
    
    ```
    {
      "type": "ClientTenantException",
      "title": "Unable to retrieve resource because the tenant id was invalid",
      "detail": "Tenant id was not found. Please check the tenant id."
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: PasswordActionTemplateNotFoundException404_
    
    ```
    {
      "type": "PasswordActionTemplateNotFoundException",
      "title": "Template was not found",
      "detail": "Template was not found."
    }
    ```
    

### GET Retrieve/Get all tenant identity providers.

`GET /tenants/{tenantId}/idps`

Operation ID: `retrieveIdentityProviders`. Security: BearerToken (SLAS\_SERVICE\_ADMIN).

Retrieve a list of SLAS identity providers associated with the tenant\_id.

#### Parameters

*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Responses

*   **200** All tenant identity providers retrieved successfully.
    
    Media type: `application/json`. Schema: `IdpListResponse`.
    
    _Example: IdpListResponse_
    
    ```
    {
      "data": [
        {
          "name": "google",
          "clientId": "idp-client-id",
          "clientSecret": "idp-secret",
          "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
          "tokenUrl": "https://oauth2.googleapis.com/token",
          "tokenInfoUrl": "https://oauth2.googleapis.com/tokeninfo",
          "userInfoUrl": "https://www.googleapis.com/oauth2/v3/userinfo",
          "redirectUrl": "http://localhost:9010/hydra/callback",
          "wellKnownUrl": "https://accounts.google.com/.well-known/openid-configuration",
          "scopes": [
            "openid",
            "email",
            "profile"
          ],
          "isPreferred": true,
          "isClientCredsBody": false,
          "teamId": "appleTeamId",
          "keyId": "appleKeyId",
          "loginMergeClaims": [
            "email"
          ],
          "oidcClaimMapper": [
            "accessToken=access_token",
            "refreshToken=refresh_token",
            "accessTokenTTL=expires_in",
            "idToken=id_token",
            "subject=sub",
            "email=email",
            "userId=sub",
            "familyName=family_name",
            "givenName=given_name",
            "name=name"
          ]
        },
        {
          "name": "Facebook",
          "clientId": "idp-client-id",
          "clientSecret": "idp-secret",
          "authUrl": "https://www.facebook.com/v19.0/dialog/oauth",
          "tokenUrl": "https://graph.facebook.com/v19.0/oauth/access_token",
          "tokenInfoUrl": "https://graph.facebook.com/v19.0/debug_token",
          "userInfoUrl": "https://graph.facebook.com/v19.0/me",
          "redirectUrl": "http://my.host.com/api/v1/idp/callback/Facebook",
          "wellKnownUrl": "https://www.facebook.com/.well-known/openid-configuration",
          "scopes": [
            "openid",
            "email",
            "profile"
          ],
          "isPreferred": true,
          "isClientCredsBody": false,
          "teamId": "appleTeamId",
          "keyId": "appleKeyId",
          "loginMergeClaims": [
            "email"
          ],
          "oidcClaimMapper": [
            "accessToken=access_token",
            "refreshToken=refresh_token",
            "accessTokenTTL=expires_in",
            "idToken=id_token",
            "subject=sub",
            "email=email",
            "userId=sub",
            "familyName=family_name",
            "givenName=given_name",
            "name=name"
          ]
        }
      ]
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpRequestException400_
    
    ```
    {
      "type": "IdpRequestException",
      "title": "Unable to update resource because the request body was invalid",
      "detail": "Request body is invalid."
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpTenantException401_
    
    ```
    {
      "type": "IdpTenantException",
      "title": "Unable to update resource because the tenant id was invalid",
      "detail": "Tenant id is invalid"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpNotFoundException404_
    
    ```
    {
      "type": "IdpNotFoundException",
      "title": "Unable to update resource because no resource was found with that value",
      "detail": "Idp Not Found"
    }
    ```
    

### GET Retrieve/Get a specific identity provider.

`GET /tenants/{tenantId}/idps/{name}`

Operation ID: `retrieveIdentityProvider`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Retrieve a specific identity provider by name.

#### Parameters

*   `name` (path, string, required) The name of the identity provider.  
    Maximum length: 256. Example: `Name`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Responses

*   **200** The identity provider was retrieved successfully.
    
    Media type: `application/json`. Schema: `IdentityProvider`.
    
    _Example: IdentityProvider_
    
    ```
    {
      "name": "google",
      "clientId": "idp-client-id",
      "clientSecret": "idp-secret",
      "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
      "tokenUrl": "https://oauth2.googleapis.com/token",
      "tokenInfoUrl": "https://oauth2.googleapis.com/tokeninfo",
      "userInfoUrl": "https://www.googleapis.com/oauth2/v3/userinfo",
      "redirectUrl": "http://localhost:9010/hydra/callback",
      "wellKnownUrl": "https://accounts.google.com/.well-known/openid-configuration",
      "scopes": [
        "openid",
        "email",
        "profile"
      ],
      "preferenceValue": true,
      "isClientCredsBody": false,
      "teamId": "appleTeamId",
      "keyId": "appleKeyId",
      "loginMergeClaims": [
        "email"
      ],
      "oidcClaimMapper": [
        "accessToken=access_token",
        "refreshToken=refresh_token",
        "accessTokenTTL=expires_in",
        "idToken=id_token",
        "subject=sub",
        "email=email",
        "userId=sub",
        "familyName=family_name",
        "givenName=given_name",
        "name=name"
      ]
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpRequestException400_
    
    ```
    {
      "type": "IdpRequestException",
      "title": "Unable to update resource because the request body was invalid",
      "detail": "Request body is invalid."
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpTenantException401_
    
    ```
    {
      "type": "IdpTenantException",
      "title": "Unable to update resource because the tenant id was invalid",
      "detail": "Tenant id is invalid"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpNotFoundException404_
    
    ```
    {
      "type": "IdpNotFoundException",
      "title": "Unable to update resource because no resource was found with that value",
      "detail": "Idp Not Found"
    }
    ```
    

### PUT Create or update an identity provider.

`PUT /tenants/{tenantId}/idps/{name}`

Operation ID: `registerIdentityProvider`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Create or update an identity provider by name.

#### Parameters

*   `name` (path, string, required) The name of the identity provider.  
    Maximum length: 256. Example: `Name`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Request body (required)

Media type: `application/json`. Schema: `IdentityProvider`.

_Example IdentityProvider: same as GET /tenants/{tenantId}/idps/{name} 200 response._

#### Responses

*   **200** The identity provider was updated successfully.
    
    Media type: `application/json`. Schema: `IdentityProviderResponse`.
    
    _Example: IdpProviderResponse_
    
    ```
    {
      "name": "google",
      "clientId": "idp-client-id",
      "clientSecret": "idp-secret",
      "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
      "tokenUrl": "https://oauth2.googleapis.com/token",
      "tokenInfoUrl": "https://oauth2.googleapis.com/tokeninfo",
      "userInfoUrl": "https://www.googleapis.com/oauth2/v3/userinfo",
      "redirectUrl": "http://localhost:9010/hydra/callback",
      "wellKnownUrl": "https://accounts.google.com/.well-known/openid-configuration",
      "scopes": [
        "openid",
        "email",
        "profile"
      ],
      "isPreferred": true,
      "isClientCredsBody": false,
      "teamId": "appleTeamId",
      "keyId": "appleKeyId",
      "loginMergeClaims": [
        "email"
      ],
      "oidcClaimMapper": [
        "accessToken=access_token",
        "refreshToken=refresh_token",
        "accessTokenTTL=expires_in",
        "idToken=id_token",
        "subject=sub",
        "email=email",
        "userId=sub",
        "familyName=family_name",
        "givenName=given_name",
        "name=name"
      ]
    }
    ```
    
*   **201** The identity provider was created successfully.
    
    Media type: `application/json`. Schema: `IdentityProviderResponse`.
    
    _Example IdpProviderResponse: same as PUT /tenants/{tenantId}/idps/{name} 200 response._
    
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpRequestException400_
    
    ```
    {
      "type": "IdpRequestException",
      "title": "Unable to update resource because the request body was invalid",
      "detail": "Request body is invalid."
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpTenantException401_
    
    ```
    {
      "type": "IdpTenantException",
      "title": "Unable to update resource because the tenant id was invalid",
      "detail": "Tenant id is invalid"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpNotFoundException404_
    
    ```
    {
      "type": "IdpNotFoundException",
      "title": "Unable to update resource because no resource was found with that value",
      "detail": "Idp Not Found"
    }
    ```
    
*   **409** Conflict. Duplicate
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpConflictException409_
    
    ```
    {
      "type": "IdpConflictException",
      "title": "Unable to create resource because a duplicate resource was found",
      "detail": "Idp was not created. Duplicate resource was found."
    }
    ```
    

### DELETE Delete an identity provider.

`DELETE /tenants/{tenantId}/idps/{name}`

Operation ID: `deleteIdentityProvider`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Delete an identity provider by name.

#### Parameters

*   `name` (path, string, required) The name of the identity provider.  
    Maximum length: 256. Example: `Name`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.

#### Responses

*   **204** No content
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpRequestException400_
    
    ```
    {
      "type": "IdpRequestException",
      "title": "Unable to update resource because the request body was invalid",
      "detail": "Request body is invalid."
    }
    ```
    
*   **401** Unauthorized. Wrong tenant
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpTenantException401_
    
    ```
    {
      "type": "IdpTenantException",
      "title": "Unable to update resource because the tenant id was invalid",
      "detail": "Tenant id is invalid"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdpNotFoundException404_
    
    ```
    {
      "type": "IdpNotFoundException",
      "title": "Unable to update resource because no resource was found with that value",
      "detail": "Idp Not Found"
    }
    ```
    

### DELETE Delete all shopper records associated with a shopper's customer ID. The email ID is used if it's passed as a query parameter. This conforms to the GDPR regulations.

`DELETE /tenants/{tenantId}/customers/{customerId}`

Operation ID: `deleteShopper`. Security: BearerToken (SLAS\_SERVICE\_ADMIN, SLAS\_ORGANIZATION\_ADMIN).

Delete all shopper records associated with a shopper's customer ID. The email ID is used if it's passed as a query parameter. This conforms to the GDPR regulations.

#### Parameters

*   `customerId` (path, string, required) The unique identifier of a customer.  
    Maximum length: 28. Example: `bcJN7998472pLiZuyGabs8knlj`.
*   `tenantId` (path, string, required) The identifier of the SLAS tenant (format: realmId\_instanceId).  
    Maximum length: 32. Example: `zzeu_001, bgvn_dev`.
*   `emailAddress` (query, string) The shoppers email address.  
    Maximum length: 256. Example: `joe.shopper@foo.org`.

#### Responses

*   **204** No content
*   **400** Bad request
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ShopperDeleteException_
    
    ```
    {
      "type": "ShopperDeleteException",
      "title": "Email address does not match stored email address",
      "detail": "Email address does not match stored email address"
    }
    ```
    
*   **404** Not found
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: ShopperNotFoundException_
    
    ```
    {
      "type": "ShopperNotFoundException",
      "title": "SLAS USER was not found by customer id",
      "detail": "SLAS USER was not found by customer id"
    }
    ```
    

## Schemas

### Tenant

Tenant

*   `tenantId` (_string_, required)  
    Maximum length: 8. Example: `aaaa_prd`.
*   `merchantId` (_integer_, required)  
    Minimum: 0. Example: `1`.
*   `description` (_string_, required)  
    Maximum length: 256. Example: `SLAS Merchant Name`.
*   `contact` (_string_, required)  
    Maximum length: 256. Example: `SLAS Tenant Contact`.
*   `emailAddress` (_string_, required)  
    Maximum length: 200. Example: `tenant_contact@slas.tst`.
*   `phoneNo` (_string_, required)  
    Maximum length: 50. Example: `000-000-0000`.
*   `isDeleted` (_boolean_, required)  
    Maximum length: 1. Example: `false`.
*   `status` (_string_, required)  
    Maximum length: 16. Example: `CLEAR`.
*   `tier` (_string_, required)
    
    This read only value relates to the B2C Comerce realm of the customer.
    
    *   XS = Bronze and Bronze+
    *   S = Silver and Silver+
    *   M = Gold and Gold+
    *   L = Platinum and Platinum+
    
      
    Allowed values: `XS`, `S`, `M`, `L`. Example: `L`.
*   `requestQuotaPerMinute` (_number_, required) This read only value shows the the number of requests that can be made per minute.  
    Example: `8000`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### TenantDto

Create or update tenants

*   `tenantId` (_string_, required)  
    Maximum length: 8. Example: `aaaa_prd`.
*   `merchantName` (_string_, required) Name of the merchant.  
    Maximum length: 256. Example: `Merchant Name`.
*   `description` (_string_, required)  
    Maximum length: 256. Example: `Additional information about the tenant.`.
*   `contact` (_string_, required)  
    Maximum length: 256. Example: `Name of the merchant's designated contact.`.
*   `emailAddress` (_string_, required) Email address of the designated contact.  
    Maximum length: 200. Example: `joe.shopper@foo.org`.
*   `phoneNo` (_string_, required) Phone number of the designated contact.  
    Maximum length: 50. Example: `+1 000-000-0000`.

### BatchLogoutRequest

*   `loginIds` (_array of string_, required) The list of login IDs to log out. Duplicate login IDs are deduplicated before processing and marked `not_processed` in the response. Exceeding the maximum returns a 400.  
    Items: Maximum length: 256. Example: `user1@example.com`. Minimum items: 1. Maximum items: 50.
    
    _Example_
    
    ```
    [
      "user1@example.com",
      "user2@example.com"
    ]
    ```
    

### BatchLogoutResponse

*   `results` (_array of LoginIdResult_, required) The per-loginId outcome of the batch logout, in the same order as the request.
*   `totalProcessed` (_integer_, required) The total number of login IDs processed.  
    Example: `2`.
*   `successCount` (_integer_, required) The number of login IDs successfully logged out.  
    Example: `2`.
*   `failureCount` (_integer_, required) The number of login IDs that failed to log out.  
    Example: `0`.

### ClientListResponse

*   `data` (_array of Client_, required) An array of clients.

### Client

*   `clientId` (_string_, required) Client ID  
    Maximum length: 100. Example: `fd0d4ab9-bb85-4c04-bebd-589bd74bdd75`.
*   `name` (_string_, required) Client Name  
    Maximum length: 100. Example: `Client Name`.
*   `secret` (_string_, required) Client Secret. The secret will only display on create and if the secret was updated when updating the client.  
    Maximum length: 256. Example: `client-secret`.
*   `scopes` (_array of string_, required)
    
    Merchant scopes. These scopes allows different permissions in SLAS and B2C commerce. Shopper Custom Objects additionally provides a way to do granular scoping besides the standard `sfcc.shopper-custom-objects` like `sfcc.shopper-custom-objects.xyz` SLAS is capable of handling a maximum of 20 Custom Object scopes.
    
    For B2C Commerce scope details, see the [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)."
    
      
    Items: Maximum length: 100. Example: `sfcc.products sfcc.catalogs sfcc.customers:ro`.
    
    _Example_
    
    ```
    [
      "sfcc.products",
      "sfcc.catalogs",
      "sfcc.customers:ro"
    ]
    ```
    
*   `redirectUri` (_string_, required) An absolute URL, beginning with a protocol  
    Maximum length: 2048. Example: `https://www.salesforce.com`.
*   `callbackUri` (_string_, required) An absolute URL, beginning with a protocol  
    Maximum length: 2048. Example: `https://www.salesforce.com`.
*   `channels` (_array of string_, required) Client Channels  
    Items: Maximum length: 1024. Example: `RefArch SiteGenesis`.
    
    _Example_
    
    ```
    [
      "RefArch",
      "SiteGenensis"
    ]
    ```
    
*   `isPrivateClient` (_boolean_) Private or Public Client  
    Example: `true`.
*   `loginEpRestrict` (_boolean_) When enabling (true) this will restrict all calls to the `\login` endpoint for the Client Id. When calling the `\login` endpoint and `loginEpRestrict` is enabled a HTTP Status code of 403 will be returned.  
    Maximum length: 1. Example: `false`.
*   `isSixDigitOtp` (_boolean_) If this attribute is set to true in the request for the clientId, a 6-digit OTP is generated during PasswordlessLogin, PasswordReset, and WebAuthn Authorization. If set to false or unspecified, an 8-digit OTP is generated by default for the aforementioned calls.  
    Example: `false`.
*   `strictClientAuth` (_boolean_) When enabled, requests from this client to `/oauth2/login` and `/oauth2/authorize` are rejected with a 401 if the `x-slas-client-auth` header is missing. The `strictClientAuth` attribute applies only to private clients. The 'x-slas-client-auth' header is a Base64-encoded string of client credentials. The string is composed of a client ID and client secret, separated by a colon (`:`). For example, `clientId:clientSecret`. Don't add the string `"Basic"`.  
    Example: `false`.

### ClientRequest

Used to create and update a SLAS Client

*   `name` (_string_, required) Client Name  
    Maximum length: 100. Example: `High Adventure Wear`.
*   `clientId` (_string_, required) SLAS client id. Must match the query parameter.  
    Maximum length: 100. Example: `fd0d4ab9-bb85-4c04-bebd-589bd74bdd75`.
*   `secret` (_string_, required) SLAS client secret. On create if left blank then a secret will be generated.  
    Maximum length: 256. Example: `client_secret`.
*   `scopes` (_array of string_, required) Merchant scopes. These scopes allows different permissions in SLAS and B2C commerce. Shopper Custom Objects additionally provides a way to do granular scoping besides the standard `sfcc.shopper-custom-objects` like `sfcc.shopper-custom-objects.xyz` SLAS is capable of handling a maximum of 20 Custom Object scopes."  
    Items: Maximum length: 4096. Example: `sfcc.products sfcc.catalogs sfcc.customers:ro`.
    
    _Example_
    
    ```
    [
      "sfcc.products",
      "sfcc.catalogs",
      "sfcc.customers:ro"
    ]
    ```
    
*   `redirectUri` (_array of string_, required) Array of SLAS redirect URLs. Include protocol and domain name in each URL. Wildcards supported.  
    Items: Maximum length: 2048. Example: `http://localhost:3000/callback`.
    
    _Example_
    
    ```
    [
      "http://localhost:3000/callback",
      "https://*.example.com/callback"
    ]
    ```
    
*   `callbackUri` (_array of string_) Array of SLAS callback URLs that will be used for passworless login and password reset when mode=callback. Include protocol and domain name in each URL. Wildcards are NOT supported.  
    Items: Maximum length: 2048. Example: `localhost:3000/passwordless-login-callback`.
    
    _Example_
    
    ```
    [
      "http://localhost:3000/password-reset-callback",
      "http://localhost:3000/passwordless-login-callback"
    ]
    ```
    
*   `channels` (_array of string_, required) Client Channels  
    Items: Maximum length: 1024. Example: `RefArch SiteGenesis`.
    
    _Example_
    
    ```
    [
      "RefArch",
      "SiteGenensis"
    ]
    ```
    
*   `isPrivateClient` (_boolean_, required) Private or Public Client. If left blank the client will default to private.  
    Example: `true`.
*   `loginEpRestrict` (_boolean_) When enabling (true) this will restrict all calls to the `\login` endpoint for the Client Id. When calling the `\login` endpoint and `loginEpRestrict` is enabled a HTTP Status code of 403 will be returned.  
    Example: `false`.
*   `isSixDigitOtp` (_boolean_) If this attribute is set to true in the request for the clientId, a 6-digit OTP is generated during PasswordlessLogin, PasswordReset, and WebAuthn Authorization. If set to false or unspecified, an 8-digit OTP is generated by default for the aforementioned calls.  
    Example: `false`.
*   `strictClientAuth` (_boolean_) When enabled, requests from this client to `/oauth2/login` and `/oauth2/authorize` are rejected with a 401 if the `x-slas-client-auth` header is missing. The `strictClientAuth` attribute applies only to private clients. The 'x-slas-client-auth' header is a Base64-encoded string of client credentials. The string is composed of a client ID and client secret, separated by a colon (`:`). For example, `clientId:clientSecret`. Don't add the string `"Basic"`.  
    Example: `false`.

### PasswordActionTemplate

*   `channelId` (_string_, required)  
    Maximum length: 36. Example: `SiteGenesis`.
*   `name` (_string_, required)  
    Maximum length: 128. Example: `Password Action Email Template`.
*   `subject` (_string_, required)  
    Maximum length: 128. Example: `Password Action Token Request`.
*   `link` (_string_, required)  
    Maximum length: 2048. Example: `This is your password action token: ${token}`.
*   `locale` (_string_, required) Identifies the locale of the template. Must be one of the [language tag strings supported by JDK 11](https://www.oracle.com/java/technologies/javase/jdk11-suported-locales.html). The string is stored in all lowercase.  
    Maximum length: 16. Example: `en-us`.
*   `actionType` (_PasswordTemplateActionType_, required)
*   `templateType` (_PasswordTemplateType_, required)
*   `template` (_string_, required)  
    Maximum length: 2048. Example: `Passwordless Login Token Request You're receiving this because you requested a passwordless login token for your account. ${link}`.

### IdpListResponse

*   `data` (_array of IdentityProviderResponse_, required) An array of identity providers.

### IdentityProvider

Identity provider

*   `name` (_string_, required) Identity Provider Name  
    Allowed values: `adfs`, `apple`, `auth0`, `azure`, `cognito`, `facebook`, `forgerock`, `gigya`, `gigya_social`, `google`, `okta`, `ping`, `salesforce`. Maximum length: 200. Example: `google`.
*   `authUrl` (_string_, required) IDP authorize URL  
    Maximum length: 256. Example: `https://www.salesforce.com/authorize`.
*   `tokenUrl` (_string_, required) IDP token URL  
    Maximum length: 256. Example: `https://www.salesforce.com/token`.
*   `tokenInfoUrl` (_string_, required) IDP token info URL  
    Maximum length: 256. Example: `https://www.salesforce.com/introspect`.
*   `userInfoUrl` (_string_, required) IDP user info URL  
    Maximum length: 256. Example: `https://www.salesforce.com/userinfo`.
*   `redirectUrl` (_string_, required) Redirect URL to go to after IDP flow is complete. This URL must be registered with the IDP.  
    Maximum length: 256. Example: `https://www.salesforce.com/idp/callback`.
*   `wellKnownUrl` (_string_, required) IDP URL to get OIDC configuration.  
    Maximum length: 256. Example: `https://www.salesforce.com/.well-known/openid-configuration`.
*   `clientId` (_string_, required) Client Id of the third party IDP.  
    Maximum length: 128. Example: `934277749308-02dg4398n3s31ofge8cot46jirn3kpkf.apps.googleusercontent.com`.
*   `clientSecret` (_string_, required) Client Secret of the third party IDP. For Apple copy the contents from the .p8 file that was downloaded from Apple between -_\----BEGIN PRIVATE KEY-----_ and -_\---END PRIVATE KEY-----_ markers.  
    Maximum length: 512. Example: `aKZM1xEnZopNP2bm2gc3GKex`.
*   `preferenceValue` (_boolean_) Set the IDP configuration as the Preferred SLAS IDP. Default value is `false`.  
    Maximum length: 1. Example: `true`.
*   `isClientCredsBody` (_boolean_, required) Default is to place the client credentials in a basic authorization header for the call to the IDP. If true, the client credentials are placed in the POST body to the IDP.  
    Maximum length: 1. Example: `false`.
*   `useWellKnown` (_boolean_) If set to `true`, SLAS uses the `wellKnowUrl` value to populate the `authUrl`, `tokenUrl`, `userInfoUrl`, and `scopes` values from the identity provider. Default value is `false`.  
    Maximum length: 1. Example: `false`.
*   `scopes` (_array of string_, required) IDP Scopes  
    Items: Maximum length: 8192. Example: `openid email profile`.
    
    _Example_
    
    ```
    [
      "oidc",
      "email",
      "profile"
    ]
    ```
    
*   `teamId` (_string_) Apple Team Id. Used primarily for Sign with Apple in generating the client secret.  
    Maximum length: 32. Example: `appleTeamId`.
*   `keyId` (_string_) Apple key id. This is the Key ID that was obtained from Apple when the the private key for client authentication was created. Used primarily for Sign with Apple in generating the client secret.  
    Maximum length: 32. Example: `appleKeyId`.
*   `loginMergeClaims` (_array of string_) List of user info claims that can be used as identifiers to look up and merge with an existing B2C Commerce profile for a registered shopper or an existing B2C Commerce profile created via federated login with an external Identity Provider with the same merge claim as this one. If multiple matching B2C Commerce shopper (customer) profiles are found, the external profile is merged with the most recently created shopper (customer) profile. Refer to the Merge Shopper Profiles user guide for more details. Note: When configuring an Apple IDP, 'email' and 'sub' are the only supported merge claims.  
    Items: Maximum length: 256. Example: `email`.
    
    _Example_
    
    ```
    [
      "email",
      "phone"
    ]
    ```
    
*   `oidcClaimMapper` (_array of string_) Mapping from the identity provider’s token claims for SLAS to get user information values when the user successfully authenticates. The values in this array should be setup using the following `key=value` pair pattern. The key part is the SLAS key with the value part being the OIDC claim key.  
    Items: Maximum length: 1024. Example: `accessToken=access_token efreshToken=refresh_token accessTokenTTL=expires_in idToken=id_token subject=sub email=email userId=sub familyName=family_name givenName=given_name name=name`.
    
    _Example_
    
    ```
    [
      "accessToken=access_token",
      "refreshToken=refresh_token",
      "accessTokenTTL=expires_in",
      "idToken=id_token",
      "subject=sub",
      "email=email",
      "userId=sub",
      "familyName=family_name",
      "givenName=given_name",
      "name=name"
    ]
    ```
    

### IdentityProviderResponse

Identity provider Response

*   `name` (_string_, required) Identity Provider Name  
    Maximum length: 200. Example: `google`.
*   `authUrl` (_string_, required) IDP authorization URL  
    Maximum length: 256. Example: `https://www.salesforce.com/authorize`.
*   `tokenUrl` (_string_, required) IDP token URL  
    Maximum length: 256. Example: `https://www.salesforce.com/token`.
*   `tokenInfoUrl` (_string_, required) IDP token info URL  
    Maximum length: 256. Example: `https://www.salesforce.com/inspect`.
*   `userInfoUrl` (_string_, required) IDP user info URL  
    Maximum length: 256. Example: `https://www.salesforce.com/userinfo`.
*   `redirectUrl` (_string_, required) Redirect URL to go to after IDP flow is complete. This URL must be registered with the IDP.  
    Maximum length: 256. Example: `https://www.salesforce.com/idp/callback`.
*   `wellKnownUrl` (_string_) IDP to get OIDC configuration.  
    Maximum length: 256. Example: `https://www.salesforce.com/.well-known/openid-configuration`.
*   `clientId` (_string_, required) Client Id of the third party IDP.  
    Maximum length: 128. Example: `934277749308-02dg4398n3s31ofge8cot46jirn3kpkf.apps.googleusercontent.com`.
*   `clientSecret` (_string_, required) Client Secret of the third party IDP. For Apple copy the contents from the .p8 file that was downloaded from Apple between -_\----BEGIN PRIVATE KEY-----_ and -_\---END PRIVATE KEY-----_ markers.  
    Maximum length: 512. Example: `aKZM1xEnZopNP2bm2gc3GKex`.
*   `isPreferred` (_boolean_, required) Indicates if the IDP configuration is the Preferred SLAS IDP for the Tenant Id.  
    Maximum length: 1. Example: `true`.
*   `isClientCredsBody` (_boolean_, required) Default is to place the client credentials in a basic authorization header for the call to the IDP. If true, the client credentials are placed in the POST body to the IDP.  
    Maximum length: 1. Example: `false`.
*   `scopes` (_array of string_, required) Scopes needed by the IDP.  
    Items: Maximum length: 8192. Example: `openid email profile`.
    
    _Example_
    
    ```
    [
      "oidc",
      "email",
      "profile"
    ]
    ```
    
*   `teamId` (_string_) Apple Team ID. Used primarily for Sign with Apple in generating the client secret.  
    Maximum length: 32. Example: `appleTeamId`.
*   `keyId` (_string_) Apple key ID. This is the Key ID that was obtained from Apple when the the private key for client authentication was created. Used primarily for Sign with Apple in generating the client secret.  
    Maximum length: 8192. Example: `appleKeyId`.
*   `loginMergeClaims` (_array of string_)
    
    List of user info claims that can be used as identifiers to look up and merge with an existing B2C Commerce profile for a registered shopper or an existing B2C Commerce profile created via federated login with an external Identity Provider with the same merge claim as this one. If multiple matching B2C Commerce shopper (customer) profiles are found, the external profile is merged with the most recently created shopper (customer) profile. Refer to the Merge Shopper Profiles user guide for more details.
    
    Note: When configuring an Apple IDP, 'email' and 'sub' are the only supported merge claims.
    
      
    Items: Maximum length: 256. Example: `email`.
    
    _Example_
    
    ```
    [
      "email",
      "phone"
    ]
    ```
    
*   `oidcClaimMapper` (_array of string_) Mapping from the identity provider’s token claims for SLAS to get user information values when the user successfully authenticates. The values in this array should be setup using the following `key=value` pair pattern. The key part is the SLAS key with the value part being the OIDC claim key.  
    Items: Maximum length: 1024. Example: `accessToken=access refresh_token accessTokenTTL=expires_in idToken=id_token subject=sub email=email userId=sub familyName=family_name givenName=given_name name=name`.
    
    _Example_
    
    ```
    [
      "accessToken=access_token",
      "refreshToken=refresh_token",
      "accessTokenTTL=expires_in",
      "idToken=id_token",
      "subject=sub",
      "email=email",
      "userId=sub",
      "familyName=family_name",
      "givenName=given_name",
      "name=name"
    ]
    ```
    

### LoginIdResult

*   `loginId` (_string_, required)  
    Maximum length: 256. Example: `user1@example.com`.
*   `status` (_string_, required)
    
    The outcome of the logout for this login ID:
    
    *   `success`: Logout succeeded.
    *   `failure`: Logout failed. See `errorMessage` for details.
    *   `not_processed`: Skipped as a duplicate of another login ID in the request.
    
      
    Allowed values: `success`, `failure`, `not_processed`. Example: `success`.
*   `errorMessage` (_string_) The reason the logout failed. Only present when `status` is `failure` or `not_processed`.  
    Maximum length: 512. Example: `User not found`.

### PasswordTemplateActionType

Describes the type of action that the password action template will be used for. Here are the actions that each enumerated string refers to:

*   `PWDLESS_LOGIN`: Passwordless login
*   `PWD_RESET_ACTION`: Password reset
*   `PWD_RESET_CROSS_DEVICE_ACTION`: Password reset for cross-device flow
*   `WEBAUTHN_AUTHORIZE_USER`: WebAuthn authorize user

Type: `string`.

Allowed values: `PWDLESS_LOGIN`, `PWD_RESET_ACTION`, `PWD_RESET_CROSS_DEVICE_ACTION`, `WEBAUTHN_AUTHORIZE_USER`. Example: `PWDLESS_LOGIN`.

### PasswordTemplateType

Identifies the type of mode that the password action template will be used for.

Type: `string`.

Allowed values: `SMS`, `EMAIL`. Example: `EMAIL`.

<!-- document id=b0d6ba9761af1f202779a765f80b9f27e3d016c5cec787b634d9b5f0a90e9c54 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas.md -->

# Shopper Login and API Access Service (SLAS) Overview

The Shopper Login and API Access Service (SLAS) enables secure access to the Shopper APIs of the B2C Commerce API and the [Open Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html) (OCAPI).

Two admin tools are available for setting up SLAS: the [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary) and the SLAS Admin UI. Both admin tools use Account Manager for access control, and they both require that you have the **SLAS Organization Administrator** role and the correct filters applied for your B2C Commerce instances.

To access the SLAS Admin UI, replace `{short-code}` in the following URL with the short code used by your B2C Commerce instances:

```text
https://{short-code}.api.commercecloud.salesforce.com/shopper/auth-admin/v1/ui/
```

To learn more about short codes, see the [Base URL and Request Formation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/base-url.md) guide.

For advice on how to use SLAS under high-volume situations, see this article on the Salesforce Developers blog: [Shopper Login API: Techniques and Tricks to Get the Most Out of High-Volume Holidays](https://developer.salesforce.com/blogs/2022/11/shopper-login-api-techniques-and-tricks-to-get-the-most-out-of-high-volume-holidays).

## SLAS Clients

To make authorized requests to SLAS, each application must be associated with one or more SLAS clients. Each SLAS client is registered to a single SLAS tenant and each SLAS tenant is associated with a single B2C Commerce instance.

A SLAS client can be created as one of two types: public or private. To choose the right client type for your application, the most important thing to ask is whether the client can be trusted to securely store a client secret or not. Use a private client when you can trust the client and use a public client when you cannot.

For example, a mobile app that communicates directly with SLAS must store the client secret on the shopper’s device, which is not secure. Therefore, most mobile apps use a public client. On the other hand, a mobile app with a backend for frontend (BFF) system _can_ store a client secret in a secure location where the shopper’s device cannot access it. Any app with a BFF system can use a private client.

The following table summarizes which client types are used by the most common types of applications:

| Application                                             | Client Type    |
| ------------------------------------------------------- | -------------- |
| Single-page web app (for example, a PWA Kit storefront) | Public client  |
| Traditional full stack web app                          | Private client |
| Mobile app (Android or iOS)                             | Public client  |
| Any kind of app with a backend-for-frontend (BFF)       | Private client |

**important:** - Do not add shopper-related scopes to Account Manager clients.
- Do not add data- or admin-related scopes to SLAS clients.
- The previous actions cause token bloat and do not work as expected.

To create, inspect, or update clients from your terminal, see [Manage SLAS Clients with the B2C CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md#slas-admin-ui-create-a-slas-client). The CLI can append scopes, channels, and redirect URIs while preserving existing values.

## Grant Types and Token Types

The SLAS API is based on grant types defined by the [OAuth 2.1](https://oauth.net/2.1/) standard.

The grant type used for an access token request depends on the type of SLAS client (public or private) and the shopper’s authentication method.

Most SLAS clients request access tokens with the [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:getAccessToken) endpoint and receive a [ShopperToken](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:security:ShopperToken).

Trusted systems use the [getTrustedSystemAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:getTrustedSystemAccessToken) endpoint and receive a [ShopperTsob token](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:security:ShopperTokenTsob). This token has additional capabilities so that trusted systems can make requests on behalf of users.

Agents acting on behalf of shoppers use the [getTrustedAgentAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedAgentAccessToken) endpoint and receive a [ShopperTokenTaob token](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=security%3AShopperTokenTaob).

To get a SLAS token for a B2C Commerce session, use the [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getSessionBridgeAccessToken) endpoint.

The following table summarizes the different grant types and token types used by each type of SLAS client and user authentication method.

| SLAS Client | Authentication Method                   | Method                                                                                                                         | Grant Type              | Token       |
| ----------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------- | ----------- |
| Public      | None (guest user)                       | [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html)                    | authorization_code_pkce | Shopper     |
| Public      | Registered user (federated login)       | [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html)                    | authorization_code_pkce | Shopper     |
| Public      | Registered user (B2C Commerce login)    | [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html)                    | authorization_code_pkce | Shopper     |
| Private     | None (guest user)                       | [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html)                   | client_credentials      | Shopper     |
| Private     | Registered user (federated login)       | [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html)                   | authorization_code      | Shopper     |
| Private     | Registered user (B2C Commerce login)    | [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html)                   | authorization_code      | Shopper     |
| Private     | Registered user (B2C Commerce login)    | [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html)                   | authorization_code_pkce | Shopper     |
| Private     | Trusted system on behalf of (TSOB) user | [getTrustedSystemAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-system.html)      | client_credentials      | ShopperTsob |
| Public      | Session Bridge (guest user)             | [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-session-bridge-auth.html) | session_bridge          | ShopperSesb |
| Public      | Session Bridge (B2C Commerce login)     | [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-session-bridge-auth.html) | session_bridge          | ShopperSesb |
| Private     | Session Bridge (guest user)             | [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-session-bridge-auth.html) | client_credentials      | ShopperSesb |
| Private     | Session Bridge (B2C Commerce login)     | [getSessionBridgeAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-session-bridge-auth.html) | client_credentials      | ShopperSesb |
| Private     | Trusted agent on behalf of (TAOB)       | [getTrustedAgentAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html)        | client_credentials      | ShopperTaob |

## Access Tokens and Refresh Tokens

To request a [ShopperToken](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:security:ShopperToken), use the [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken) endpoint. To request a [ShopperTokenTsob](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:security:ShopperTokenTsob), use the [getTrustedSystemAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedSystemAccessToken) endpoint.

Both endpoints return the following upon successful authorization:

- An access token in JSON Web Token (JWT) format
- A `customer_id` string
- A unique shopper identifier (USID)
- A refresh token

Access tokens are valid for 30 minutes. They can be used to make requests to any B2C Commerce API endpoints covered by the scopes of the issuing SLAS API client. They can request Open Commerce API endpoints for which the SLAS API client ID has been allowed. They may only be used to request APIs from the instance and site they were issued.

The refresh token can be used to request a new access token. For production tenants, refresh tokens are valid for 90 days for registered shoppers and 30 days for guests. On non-production tenants, refresh tokens are valid for 9 days. Using the refresh tokens extends the lifetime of the subsequently issued token by its lifetime duration.

Refresh tokens issued to using public clients are single use. When the refresh token is used, a new one is returned in the response. Refresh tokens issued using private clients may be used multiple times. The same refresh token is returned in the response.

- When a shopper changes their login ID or password, access tokens that were granted before the password change are revoked and rejected by both the B2C Commerce API and OCAPI. Prompt the shopper to log in again using the new credentials. Note that token revocation requires several minutes to complete, and is only enabled by default in production environments. For other environments, such as sandboxes, you must enable token revocation.
- The JWT returned by SLAS includes a number of claims. When writing code to inspect claims, be sure not to rely on ordering, as additional claims may be added.
- Access tokens allow you to act on behalf of the shopper. The actions taken can be sensitive, such as updating an account's email. Always take the necessary precautions to protect the shopper.

**note:** To initialize an Agentforce session, obtain a SLAS shopper access token that includes the `sfcc.shopper-agents.rw` scope, and then call the [Shopper Agents API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-agents?meta=Summary) with the `sessionInitKey` received at session start.

### Guest Tokens

To prevent unauthorized access across different storefronts, the `channel_id` (site) parameter is required when requesting a guest access token with a `grant_type` of `client_credentials` or `authorization_code_pkce`. If this parameter is missing, your request receives a 400 invalid refresh token error.

**important:** Following a tiered rollout, the `channel_id` parameter requirement started being enforced for all production tenants on 3/25/25. For details, see the [SLAS Release Notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html#03182025).
Existing customers must update their implementation to include the `channel_id` parameter in their guest access token requests.

These sample requests show the required use of the `channel_id` parameter.

#### Sample request for client_credentials

```sh
curl -X POST --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic <client_id:secret>' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'channel_id=RefArch'
```

#### Sample request for authorization_code_pkce

```sh
curl --location 'https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=4bc7QNx0NDc-n991Ppi6IiwPO6OaPrT_jMgF823lGyg' \
--data-urlencode 'grant_type=authorization_code_pkce' \
--data-urlencode 'redirect_uri=http://localhost:9010/callback' \
--data-urlencode 'client_id=3a15f34e-fecd-4fcc-8235-86b70978e629' \
--data-urlencode 'code_verifier=MyLi6hIowxiGsvBvvCJ0FV4AkOpOOnRHxC2PCsvD7yVLy4ZtzKl9Mv9a1r65dh1qg0ZvZ2nvMlLN8uYsZOKcj8cae1XbBBmD' \
--data-urlencode 'channel_id=SiteGenesis'
```

#### Sample request for fetching tokens

```sh
curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/token" \
    --user "$CLIENT:$SECRET" \
    --data 'grant_type=client_credentials' \
    --data "channel_id=$CHANNEL_ID"
```

Additionally, SLAS shopper tokens created for one site (Site A) can’t be used for making SCAPI or OCAPI calls for another site (Site B). For example, a SLAS access token that was requested for the `channel_id` of RefArch can only be used with SCAPI or OCAPI calls that use the same `site_id`:

```sh
curl --location 'https://sandbox-001.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_bcgl_stg/products?ids=nikon-d90-wlens&siteId=RefArch' \
--header 'Authorization: Bearer <access_token>'
```

### Decoded Access Tokens

You can view token details in the decoded access token, such as token lifespan or authorized scopes. For example:

#### Header

```json
{
  "ver": "1.0",
  "jku": "slas/prod/zzrf_001",
  "kid": "73290ac8-ee0d-414e-ae51-2078ab4dc4d1",
  "typ": "jwt",
  "clv": "J2.3.4",
  "alg": "ES256"
}
```

- `jku`: this is the same as the body `iss` claim.
- `kid` : the key id of the public key to use to validate token signature. Get the keys with the [getJwksUri](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getJwksUri) endpoint.

#### Body

```json
{
  "aut": "GUID",
  "scp": "sfcc.shopper-myaccount.baskets sfcc.shopper-discovery-search sfcc.shopper-myaccount.paymentinstruments sfcc.shopper-customers.login sfcc.shopper-experience sfcc.shopper-myaccount.orders sfcc.shopper-productlists sfcc.shopper-promotions sfcc.session_bridge sfcc.shopper-myaccount.paymentinstruments.rw sfcc.shopper-myaccount.productlists sfcc.shopper-categories sfcc.shopper-myaccount sfcc.shopper-myaccount.addresses sfcc.shopper-products sfcc.shopper-myaccount.rw sfcc.shopper-stores sfcc.shopper-customers.register sfcc.shopper-baskets-orders sfcc.shopper-myaccount.addresses.rw sfcc.shopper-myaccount.productlists.rw sfcc.shopper-baskets-orders.rw sfcc.shopper-gift-certificates sfcc.shopper-product-search sfcc.shopper-seo",
  "sub": "cc-slas::zzrf_001::scid:c9c45bfd-0ed3-4aa2-9971-40f88962b836::usid:51b61c73-3a52-4b29-ac90-5ace596e5b27",
  "ctx": "slas",
  "iss": "slas/prod/zzrf_001",
  "ist": 1,
  "dnt": "0",
  "aud": "commercecloud/prod/zzrf_001",
  "nbf": 1717191705,
  "sty": "User",
  "isb": "uido:slas::upn:Guest::uidn:Guest User::gcid:ablrdGlHdHlXkRk0cZkGYYwHg3::chid:RefArchGlobal",
  "exp": 1717193535,
  "iat": 1717191735,
  "jti": "C2C4856201860-1890678903105595297713040"
}
```

- `scp`: Scopes in the token. Unless specific scopes are requests, this will be the scopes of the SLAS client.
- `sub`: Contains the client_id, tenant_id, and usid.
- `dnt`: Shopper tracking preferences. For details, see [Manage Shopper Tracking Preferences](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-tracking-preferences.md).
- `isb`: Contains IDP origin, shopper information, guest id, registered shopper id, token type and channel id.

## Verify the SLAS Password Action Callback

To help verify the authenticity of passwordless login and password reset callbacks, SLAS provides a **SlasCallbackToken** (JWT) for each passwordless login and password reset callback that SLAS sends:

- SLAS adds a `x-slas-callback-token` HTTP header with the **SlasCallbackToken.**
- If SLAS is unable to create the **SlasCallbackToken,** the `x-slas-callback-token` HTTP header is not created, and you must use the callback body to retrieve the callback values.

**important:** SLAS makes the POST call to the given `callback_uri` without adding additional headers or parameters. If the `callback_uri` needs additional headers, such as an authorization header, you must have a proxy in place between SLAS and the `callback_uri` that can add any additional headers or parameters as needed.

### Example SLAS Callback Header

```json
{
    "user-agent": "ReactorNetty/1.0.38",
    "host": "localhost:9003",
    "accept": "*/*",
    "x-correlation-id": "1cf7ce67-1d49-4ab5-832e-85daac619e4a",
    "content-type": "application/json",
    "x-slas-callback-token": "eyJraWQiOiIyZDY3MGZhOC0wZjI4LTQ0YTEtYjhiNC04N2E2ZDJmZWIxZDgiLCJ0eXAiOiJqd3QiLCJhbGciOiJFUzI1NiJ9.eyJlbWFpbF9pZCI6ImRhcnRoLnZhZGVyQGVuZG9yLm9yZyIsImxvZ2luX2lkIjoiZGFydGgudmFkZXIiLCJzdWIiOiI4NzlhOTczMC0zYjNlLTQ3N2QtOWVhMC0xYzdiYWI1ZjI4MzMiLCJwaG9uZSI6IiIsImlzcyI6InNsYXMvZGV2L2Jndm5fc3RnIiwiY3VzdG9tZXJfaWQiOiJhZFUxS0V3WEhLd3JiUjl5OVRhbjFPdHhXQSIsImV4cCI6MTcyNTQxNzMxMiwiaWF0IjoxNzI1NDE2NDEyLCJ0b2tlbiI6IjQwMjc1NTQ5IiwidXNpZCI6IjNmMDY4OTg3LWE3YWItNDE1Ny1iZmRkLTBmOGY4MjYzMzlkNSJ9.gFdqdu5gNNyZ6g2eFehbgOzY5DsoJZcHg0G5EZyhHy_FnD0bTFxE_pGzMgxttUrpeI7o7UBXGzvK5YL3K4wtAA",
    "content-length": "180"
}
```

### Example SLAS Callback Body

```json
{
    "email_id": "darth.vader@endor.org",
    "login_id": "darth.vader",
    "phone": "",
    "customer_id": "adU1KEwXHKwrbR9y9Tan1OtxWA",
    "token": "40275549",
    "usid": "3f068987-a7ab-4157-bfdd-0f8f826339d5"
}
```

### Steps to Validate SLAS Passwordless Login and Password Reset Callbacks

1. Extract the `x-slas-callback-token` header from the request. Using the previous examples, callback header values are:

```text
eyJraWQiOiIyZDY3MGZhOC0wZjI4LTQ0YTEtYjhiNC04N2E2ZDJmZWIxZDgiLCJ0eXAiOiJqd3QiLCJhbGciOiJFUzI1NiJ9.eyJlbWFpbF9pZCI6ImRhcnRoLnZhZGVyQGVuZG9yLm9yZyIsImxvZ2luX2lkIjoiZGFydGgudmFkZXIiLCJzdWIiOiI4NzlhOTczMC0zYjNlLTQ3N2QtOWVhMC0xYzdiYWI1ZjI4MzMiLCJwaG9uZSI6IiIsImlzcyI6InNsYXMvZGV2L2Jndm5fc3RnIiwiY3VzdG9tZXJfaWQiOiJhZFUxS0V3WEhLd3JiUjl5OVRhbjFPdHhXQSIsImV4cCI6MTcyNTQxNzMxMiwiaWF0IjoxNzI1NDE2NDEyLCJ0b2tlbiI6IjQwMjc1NTQ5IiwidXNpZCI6IjNmMDY4OTg3LWE3YWItNDE1Ny1iZmRkLTBmOGY4MjYzMzlkNSJ9.gFdqdu5gNNyZ6g2eFehbgOzY5DsoJZcHg0G5EZyhHy_FnD0bTFxE_pGzMgxttUrpeI7o7UBXGzvK5YL3K4wtAA
```

2. Use the SLAS `/jwks` endpoint to get the public key to verify the JWT signature. The response includes public keys for your tenant, for example:

```json
{
    "keys": [
        {
            "kty": "EC",
            "crv": "P-256",
            "use": "sig",
            "kid": "2d670fa8-0f28-44a1-b8b4-87a6d2feb1d8",
            "x": "_2tPqxGhgX6cA5Qg7v6UH_9om8OR3-OehkgXXWraTp8",
            "y": "DAykmQPtf282buIcL0rLwKYbK6ApgripMjazdAthUFw"
        },
        {
            "kty": "EC",
            "crv": "P-256",
            "use": "sig",
            "kid": "eb70508f-4d64-46f7-a3d5-b36558d6e6b6",
            "x": "VV0JVJFhkz71wY0E73Z-snorZ5oJf1QOdkIbCjyMqLs",
            "y": "QLkqBVSPPrkd7HjaSEMgMU9Ob-FDpg1W-oLq5I4ExqQ"
        }
    ]
}
```

3. Use the public key to verify the `SlasCallbackToken` signature:

- You can use several JSON Web Token (JWT) libraries to verify the **SlasCallbackToken** signature. See [JWT Libraries](https://jwt.io/libraries) to find a Json Web Token (JWT) library for your programming language. For example, verify the signature using the Java `nimbus-jose-jwt` library:

```java
// prerequisite is to get the public keys using the SLAS /jwks endpoint
// response into a String.

import com.nimbusds.jose.JWSVerifier;
import com.nimbusds.jose.crypto.ECDSAVerifier;
import com.nimbusds.jose.jwk.ECKey;
import com.nimbusds.jwt.SignedJWT;
import org.apache.commons.lang3.StringUtils;
import org.json.JSONArray;
import org.json.JSONObject;

public boolean isSignatureValid(String callbackJwt) {

    ECDSAVerifier jwksVerifier = null;

    try {
        // publicKeys value is from the /jwks endpoint
        JSONObject publicKeyJSON = new JSONObject(publicKeys);
        JSONArray publicKeyArray = publicKeyJSON.getJSONArray("keys");
        // Build a signed JWT
        SignedJWT callbackSignedJWT = SignedJWT.parse(callbackJwt);
        // Get the signing key id.
        String jwtKeyId = callbackSignedJWT.getHeader().getKeyID();

        // Find the signing key from the array of public keys.
        // If found then create a verifier.
        for(Object jo : publicKeyArray) {
         if( StringUtils.equals(((JSONObject)jo).getString("kid"), jwtKeyId)) {
            String publicKey = jo.toString();
            jwksVerifier = new ECDSAVerifier(ECKey.parse(publicKey));
            break;
          }
        }

       if(Objects.nonNull(jwksVerifier) ) {
           // Verify the JWT.
           return callbackSignedJWT.verify(jwksVerifier);
       } else {
           return false;
       }
    }
    catch(ParseException | JOSEException e) {
        return false;
    }
 }
```

## Shopper Tracking Preferences

You can incorporate shopper tracking preferences into your applications. When you get a SLAS token using `getAccessToken`, you specify a tracking preference. The tracking preference is respected for all requests using that token. After the B2C Commerce 24.4 release, the Shopper Login API will include a boolean `dnt` parameter to set `Do Not Track` for the session. If not defined, the `dnt` value defaults to `false`.

For details, see: [Manage Shopper Tracking Preferences.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-tracking-preferences.html)

## View SLAS Error Logs in Log Center

SLAS 4xx and 5xx error logs are available in Log Center, which provides multiple benefits, including a single URL for all realms, up to 14 days of log data, and improved search capabilities.

To access SLAS 4xx and 5xx error logs:

1. If you built your site using Progressive Web App (PWA) Kit, first complete the prerequisites described in [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#debug-using-log-center).
2. [Start Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_start_log_center.htm&type=5).
3. Select a Region.
4. Select a [Realm](https://help.salesforce.com/s/articleView?id=cc.b2c_platform_overview.htm&type=5). If you don’t know your realm ID, ask your Account Executive (AE) or Customer Success Manager (CSM).
5. Select **Show filtered results**.
6. Select **Search** and then select **Current Search**.
7. In **Service Type**, select **SLAS logs**.
8. For a faster search, use an LCQL query, which filters the results using a specific `httpStatus` code:
   1. Select **Search** and then select **Current Search**.
   2. In the **Search** page, enter an `(httpstatus)` code for **LCQL**, for example: `text:(httpstatus) AND text:(401)`.

## SLAS Rate Limits

For SLAS rate limits, troubleshooting guidance, and best practices, see [Load Shedding and Rate Limiting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/throttle-rates.md#shopper-login-and-api-access-service-slas).

## Constraints

- A SLAS service protection mechanism restricts calls to the same SLAS endpoint repeatedly using the same USID (Unique Shopper ID) within a short span of time. This returns a 409 HTTP response.

- Some SLAS endpoints, including [authenticateCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer), communicate with the associated B2C Commerce instance. If the instance is unavailable, calls to these endpoints will fail.

- [SCAPI hooks](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/extensibility_via_hooks.md) including hooks on `dw.ocapi.shop.customer.auth.*` can conflict with SLAS calls. If SLAS calls are unexpectedly failing, check your B2C Commerce logs for hook invocation errors.

- If a shopper account associated with an access token is disabled or deleted, any subsequent requests made with that access token will fail.

- SLAS is capable of handling a maximum of 30 Custom Object scopes. For details, see [Shopper Custom Objects API.](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-custom-objects?meta=Summary)

- In B2C Commerce, SLAS functions as a multi-tenant service that serves both PRD and non-PRD instances from its production environment. SLAS treats PRD and non-PRD instances as different "entities", and prioritizes production environment performance by minimizing the potential impact of non-PRD traffic and events to production. As a result, there are SLAS differences between PRD and non-PRD environments, which will be resolved in the future. SLAS PRD and non-PRD differences include:

  - SLAS token revocation behavior after a shopper password or email change: In non-PRD environments, after changing a password or email, it is possible to issue a request using the previously issued SLAS token without receiving an error.
  - When a B2C commerce shopper is deleted, an event is sent to SLAS to delete the corresponding SLAS user. In rare instances, if the delete event does not reach SLAS, you must use [`deleteShopper`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=deleteShopper) to delete the corresponding record in SLAS.
  - Overall eventing (using events to trigger and communicate between services): By default, eventing is only available in PRD instances, so unless this is configured in other environments, it is not available. To have your non-PRD instances evaluated for possible eventing enablement, contact your Customer Success Manager or Account Executive.

## Next Steps

If you haven’t already, set up your public SLAS clients or private SLAS clients by following the instructions in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.md) in the Get Started guides.

After setting up your SLAS clients, see the SLAS guides that cover how to use both the main SLAS API and the SLAS Admin API:

- [Public SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-public-client.md) (main SLAS API)
- [Private SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-private-client.md) (main SLAS API)
- [SLAS Identity Providers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-identity-providers.md) (SLAS Admin API)

For more technical details on the capabilities of the SLAS APIs, explore the API specifications in the Reference section:

- [SLAS API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary)
- [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=slas-admin:Summary)

<!-- document id=808da5d116c4879e6d0540ec4fc4d7c0e695eb577c4d8fea516ceaff27158f3f url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-orders.md -->

Shopper Orders

# Shopper Orders

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-orders/shopper-orders-oas-v1-public.yaml)

## API Overview

The Shopper Orders API enables you to:

*   Create orders based on baskets prepared using the Shopper Baskets API.
*   Add a customer's payment instrument to an order.

You can choose to supply the full payment information or supply only a customer payment instrument ID and amount. If the customer payment instrument ID is set, all the other properties (except amount) are ignored and the payment data is resolved from the stored customer payment information.

**Note:** The API doesn’t allow the storage of credit card numbers. The endpoint provides the storage of masked credit card numbers only.

To update the payment status, use the Orders API.

Responses from this API are not cached because order data is transactional and unique to each shopper.

For additional guidance when working with baskets, see [Build Baskets and Place Orders](https://developer.salesforce.com/docs/commerce/commerce-api/guide/work-with-baskets-orders.html).

### Authentication & Authorization

The client requesting order information must have access to the Orders resource. The Shopper Orders API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

You must include `sfcc.shopper-baskets-orders` or `sfcc.shopper-baskets-orders.rw` in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached. Order data is transactional and unique to each shopper.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Create an Order from a Basket

Place an order by providing a basket ID. The basket must have a valid shipping address, shipping method, billing address, and payment instrument.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-orders/v1/organizations/{organizationId}/orders?siteId=RefArch" \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "basketId": "{basketId}" }'
```

### Related APIs

*   [Orders (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/orders?meta=Summary) — Update order status, payment status, and shipping addresses.
*   [Shopper Baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) — Build and manage baskets before placing an order.

**Version:** 1.22.4

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-orders/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `ShopperTokenTsob` (oauth2) `ShopperTokenTsob` (Tsob = trusted system on behalf) is a child of the `ShopperToken` security scheme and extends the functionality of `ShopperToken` for specific use cases. A token of type `ShopperTokenTsob` allows you to access Shopper API endpoints, including OCAPI and Salesforce Commerce API for headless applications. Besides endpoints that require this specific subtype, all other endpoints secured by the `ShopperToken` parent scheme can be accessed with a `ShopperTokenTsob`. To learn how to get a `ShopperTokenTsob` token, see [getTrustedSystemAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:getTrustedSystemAccessToken).
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/trusted-system/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints

## Operations

### POST Submits an order for a basket.

`POST /organizations/{organizationId}/orders`

Operation ID: `createOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Submits an order based on a prepared basket. The only considered value from the request body is basketId.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `Basket`.

_Example: OrderPost_

```
{
  "basketId": "a10ff320829cb0eef93ca5310a"
}
```

#### Responses

*   **200** Success, the response body contains the submitted order.
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example: Order_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "confirmationStatus": "not_confirmed",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "d3f7ae47e5897a6b5d2fd541f0",
          "statusCode": "applied",
          "valid": true
        }
      ],
      "createdBy": "Customer",
      "creationDate": "2019-10-22T12:17:28.341Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "customerName": "Stephanie Miller",
        "email": "shopper@salesforce-test.com"
      },
      "customerName": "Stephanie Miller",
      "exportStatus": "not_exported",
      "groupedTaxItems": [
        {
          "taxRate": 0.05,
          "taxValue": 30.8
        }
      ],
      "guest": true,
      "giftCertificateItems": [
        {
          "amount": 1,
          "giftCertificateItemId": "540db3ffe58bfb04ab673757d7",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-22T12:17:28.376Z",
      "merchandizeTotalTax": 30,
      "orderNo": "00000410",
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 10,
            "type": "amount"
          },
          "reasonCode": "customer service",
          "createdBy": "support",
          "creationDate": "2019-10-22T12:17:28.347Z",
          "custom": true,
          "lastModified": "2019-10-22T12:17:28.349Z",
          "manual": true,
          "price": -10,
          "priceAdjustmentId": "63b9eb9b4a92bd3e5c6ee804c2",
          "promotionId": "5ties"
        }
      ],
      "orderToken": "7gJDIFlnho_mXrxfxVB9Neic3J7szzR9glvgU5Ath-I",
      "orderTotal": 586.76,
      "orderViewCode": "YGXrGbZWlr29tIsGnYgR5o_8OxBMXWigevx1WD0X1Hc",
      "paymentInstruments": [
        {
          "amount": 20,
          "paymentInstrumentId": "ca47e0da3d49b067b630db624a",
          "paymentMethodId": "BML"
        },
        {
          "amount": 566.76,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "6b970a04ca8a468a64b9936764",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "paymentStatus": "not_paid",
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "d9516eecc64bd90b0022714d26",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "8991e8d7adf0f46ffbc584e175",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.99,
          "priceAfterItemDiscount": 599.99,
          "priceAfterOrderDiscount": 589.99,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 37,
          "adjustedShippingTotalTax": 0.5,
          "deliveryWindow": {
            "startAt": "2026-05-04T14:00:00Z",
            "endAt": "2026-05-07T22:00:00Z"
          },
          "gift": false,
          "merchandizeTotalTax": 30,
          "orderCutoffAt": "2026-04-27T14:00:00Z",
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "d5d95acf5381dc6e273b4336a7",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99,
            "deliveryWindow": {
              "startAt": "2026-05-04T14:00:00Z",
              "endAt": "2026-05-07T22:00:00Z"
            },
            "orderCutoffAt": "2026-04-27T14:00:00Z"
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "768abee75aa8015239a9696c7e",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingStatus": "not_shipped",
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "status": "created",
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   a failure during the creation of a gift certificate for a gift certificate item.
    *   the basket ID in the request body is null or empty.
    *   an invalid product item.
    *   an option with the specified option ID is unknown.
    *   an option with the specified option value ID is unknown.
    *   a product item is not available.
    *   the customer assigned to the basket does not match the verified customer represented by the JWT token.
    *   the basket contains flashes (validation errors that prevent order placement).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'."
    }
    ```
    
*   **404** The basket with the given basket ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### GET Retrieve Order Management (OMS) configuration data needed to render cancel and return experiences.

`GET /organizations/{organizationId}/orders/oms-meta-data`

Operation ID: `getOmsMetaData`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Retrieves configuration data from Order Management (OMS) required by the storefront to render cancel and return experiences. The response contains the reason codes configured in OMS for cancelling an order and for returning order items. Each reason code carries a `default` flag. When the caller omits a reason, the cancel and return endpoints (`cancelOmsOrder`, `returnOmsOrder`) apply the reason marked as `default` for that flow.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the OMS meta data.
    
    Media type: `application/json`. Schema: `OmsMetaData`.
    
    _Example: OmsMetaData_
    
    ```
    {
      "cancelReasonCodes": [
        {
          "reason": "Not specified",
          "default": true
        },
        {
          "reason": "Defect",
          "default": false
        },
        {
          "reason": "Wrong item",
          "default": false
        }
      ],
      "returnReasonCodes": [
        {
          "reason": "Not specified",
          "default": true
        },
        {
          "reason": "Defect",
          "default": false
        },
        {
          "reason": "Does not fit",
          "default": false
        }
      ]
    }
    ```
    
*   **409** Order Management (OMS) is not active for this site.
    
    Media type: `application/problem+json`. Schema: `OmsNotActiveErrorResponse`.
    
    _Example: OmsNotActiveErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/oms-not-active",
      "detail": "Order Management (OMS) is not active for this site.",
      "title": "Oms Not Active"
    }
    ```
    

#### Extension points

*   `sfcc.checkout.shopper-orders.v1.orders.oms-meta-data.modifyGETResponse` (modifyResponse) Called to modify the OMS meta data returned in the response.

### GET Retrieve order information.

`GET /organizations/{organizationId}/orders/{orderNo}`

Operation ID: `getOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Gets information for an order.

#### Parameters

*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `expand` (query, array of string, style: form, explode: false) When you select 'oms' expand, data is loaded from Order Management (OMS), if available. When OMS data is available, the expand parameter has the following behavior: "expand=oms": order and related order entities (product & shipping items, delivery groups and price adjustments) are returned. "expand=oms\_shipments": order and fulfillment (shipment) data is returned. "expand=oms,oms\_shipments": order, related order entities and fulfillment (shipment) data are returned. If your instance is not integrated with OMS or the order data is not available, the `expand=oms` command is disregarded.  
    Items: Allowed values: `oms`, `oms_shipments`. Example: `oms`.
    
    _Example_
    
    ```
    oms,oms_shipments
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the order.
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example Order: same as POST /organizations/{organizationId}/orders 200 response._
    
*   **404** The order with the given order number is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BasketNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/basket-not-found",
      "title": "Basket Not Found",
      "detail": "No basket with ID '123' could be found."
    }
    ```
    

### POST Retrieve order information using a combination of non-token identifying factors.

`POST /organizations/{organizationId}/orders/{orderNo}/lookup`

Operation ID: `guestOrderLookup`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Retrieve order details using non-token identifiers or an authenticated shopper session.

The endpoint distinguishes between two levels of access: - Full access: Granted using shopper authentication, an OrderViewCode, or a time-limited access code. The OrderViewCode and access code are both passed in the `orderViewCode` request-body field; the server distinguishes them by format. Returns the complete order graph. - Partial access: Granted using a billing PostalCode paired with email or phone information. Filters sensitive data and Personally Identifiable Information (PII).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `expand` (query, array of string, style: form, explode: false) When you select 'oms' expand, data is loaded from Order Management (OMS), if available. When OMS data is available, the expand parameter has the following behavior: "expand=oms": order and related order entities (product & shipping items, delivery groups and price adjustments) are returned. "expand=oms\_shipments": order and fulfillment (shipment) data is returned. "expand=oms,oms\_shipments": order, related order entities and fulfillment (shipment) data are returned. If your instance is not integrated with OMS or the order data is not available, the `expand=oms` command is disregarded.  
    Items: Allowed values: `oms`, `oms_shipments`. Example: `oms`.
    
    _Example_
    
    ```
    oms,oms_shipments
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `OrderLookupRequest`.

_Example: OrderLookUp_

```
{
  "email": "no-reply@salesforce.com",
  "orderViewCode": "YGXrGbZWlr29tIsGnYgR5o_8OxBMXWigevx1WD0X1Hc"
}
```

_Example: OrderLookUpWithAccessCode_

```
{
  "orderViewCode": "847291"
}
```

#### Responses

*   **200** Success, the response returns the order, though sensitive details may be filtered based on access level.
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example Order: same as POST /organizations/{organizationId}/orders 200 response._
    
    _Example: OrderPartialAccess_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "billingAddress": {
        "postalCode": "01801"
      },
      "channelType": "storefront",
      "currency": "USD",
      "groupedTaxItems": [
        {
          "taxRate": 0.05,
          "taxValue": 30.8
        }
      ],
      "guest": true,
      "lastModified": "2019-10-22T12:17:28.376Z",
      "merchandizeTotalTax": 30,
      "orderNo": "00000410",
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 10,
            "type": "amount"
          },
          "reasonCode": "customer service",
          "creationDate": "2019-10-22T12:17:28.347Z",
          "custom": true,
          "lastModified": "2019-10-22T12:17:28.349Z",
          "manual": true,
          "price": -10,
          "priceAdjustmentId": "63b9eb9b4a92bd3e5c6ee804c2",
          "promotionId": "5ties"
        }
      ],
      "orderTotal": 586.76,
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "d9516eecc64bd90b0022714d26",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "8991e8d7adf0f46ffbc584e175",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.99,
          "priceAfterItemDiscount": 599.99,
          "priceAfterOrderDiscount": 589.99,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 37,
          "adjustedShippingTotalTax": 0.5,
          "gift": false,
          "merchandizeTotalTax": 30,
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingMethod": {
            "description": "Order received within 7-10 business days.",
            "id": "001",
            "name": "Ground",
            "price": 15.99
          },
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "768abee75aa8015239a9696c7e",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "status": "created",
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   The combination of identifying information is not sufficient for any access level.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InsufficientIdentifyingInformation_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/insufficient-identifying-information",
      "title": "Insufficient Identifying Information",
      "detail": "Insufficient identifying information provided to retrieve the order."
    }
    ```
    
*   **404**
    
    Order was not found. Possible reasons:
    
    *   the order with the given order number is unknown.
    *   the combination of identifying information you provided, such as email or postal code, does not match the order record.
    *   the provided access code is invalid or has expired.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### POST Fail an Order.

`POST /organizations/{organizationId}/orders/{orderNo}/actions/fail`

Operation ID: `failOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Fails an unplaced order and optionally reopens the basket when indicated. Creates a HistoryEntry in the failed Order with provided reasonCode.

See also: Find more info on fail order behavior here: `https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_order_OrderMgr.html#dw_order_OrderMgr_failOrder_Order_Boolean_DetailAnchor`

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `reopenBasket` (query, boolean) Set to true to reopen basket from the order. A basket can only be reopened if no other basket for the customer exists at the moment of the call to fail Order, since a customer is limited to 1 storefront basket at a time.  
    Default: `false`. Example: `false`.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `FailOrderRequest`.

_Example: FailOrder_

```
{
  "reasonCode": "payment_confirm_failure"
}
```

#### Responses

*   **201** Order failed successfully. No content returned.
    
    Headers:
    
    *   `Location` (string) The location for accessing the reopened basket if one exists.
*   **204** Order failed successfully. No content returned.
*   **400**
    
    Possible reasons:
    
    *   Invalid request parameters.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The order with the given order number is unknown for the shopper.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    
*   **409** The order is in invalid status.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidStateTransition_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-status-transition",
      "title": "Order Status Transition",
      "detail": "The order status change from 'Completed' to 'Failed' for order with number '00000335' isn't supported."
    }
    ```
    

### POST Cancel an order that is integrated with Order Management (OMS).

`POST /organizations/{organizationId}/orders/{orderNo}/actions/oms-cancel-order`

Operation ID: `cancelOmsOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Cancels an order that is integrated with Order Management (OMS). The cancellation always applies to the entire order; partial cancellations are not supported.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `OmsCancelOrderRequest`.

_Example: OmsCancelOrder_

```
{
  "reason": "Wrong item"
}
```

_Example: OmsCancelOrderWithAccessCode_

```
{
  "reason": "Wrong item",
  "orderAccessCode": "847291"
}
```

#### Responses

*   **200** Success, the response body contains the updated order retrieved from Order Management (OMS).
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example Order: same as POST /organizations/{organizationId}/orders 200 response._
    
*   **400**
    
    The cancel request is invalid. Possible reasons:
    
    *   The supplied reason code is not configured in Order Management (OMS).
    
    Media type: `application/problem+json`. Schema: `InvalidReasonCodeErrorResponse`.
    
    _Example: InvalidReasonCodeErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-reason-code",
      "detail": "The reason 'Damaged in transit' is not configured in Order Management (OMS).",
      "title": "Invalid Reason Code"
    }
    ```
    
*   **404**
    
    Order was not found. Possible reasons:
    
    *   the order with the given order number is unknown.
    *   the provided access code is invalid or has expired.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    
*   **409**
    
    The order cannot be cancelled. Possible reasons:
    
    *   The order is no longer in a state that permits cancellation.
    *   Order Management (OMS) rejected the cancel request after ECOM accepted the input.
    *   Order Management (OMS) is not active for this site.
    
    Media type: `application/problem+json`. Schema: `OrderCancelFailedErrorResponse | OmsNotActiveErrorResponse`.
    
    One of: `OrderCancelFailedErrorResponse`, `OmsNotActiveErrorResponse`.
    
    _Example: OrderCancelFailedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-cancel-failed",
      "detail": "Order '00000335' cannot be cancelled.",
      "title": "Order Cancel Failed"
    }
    ```
    
    _Example: OmsNotActiveErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/oms-not-active",
      "detail": "Order Management (OMS) is not active for this site.",
      "title": "Oms Not Active"
    }
    ```
    

#### Extension points

*   `sfcc.checkout.shopper-orders.v1.orders.orderNo.actions.oms-cancel-order.modifyPOSTResponse` (modifyResponse) Called to modify the order returned in the response after cancellation.

### POST Initiate the return of one or more items of an order that is integrated with Order Management (OMS).

`POST /organizations/{organizationId}/orders/{orderNo}/actions/oms-return-order`

Operation ID: `returnOmsOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Initiates the return of one or more items of an order that is integrated with Order Management (OMS).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `OmsReturnOrderRequest`.

_Example: OmsReturnOrder_

```
{
  "productItems": [
    {
      "itemId": "10uVF0000003W0BYAU",
      "quantity": 1,
      "reason": "Does not fit"
    },
    {
      "itemId": "11uVF0000045W0BYAU",
      "quantity": 1,
      "reason": "Defect"
    }
  ]
}
```

_Example: OmsReturnOrderWithAccessCode_

```
{
  "productItems": [
    {
      "itemId": "10uVF0000003W0BYAU",
      "quantity": 1,
      "reason": "Does not fit"
    }
  ],
  "orderAccessCode": "847291"
}
```

#### Responses

*   **200** Success, the response body contains the updated order retrieved from Order Management (OMS).
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example Order: same as POST /organizations/{organizationId}/orders 200 response._
    
*   **400**
    
    The return request is invalid. Possible reasons:
    
    *   The supplied reason code is not configured in Order Management (OMS).
    *   One or more of the supplied `productItems[].itemId` values do not match any product item of the order.
    *   The requested return quantity exceeds the quantity available to return for one or more items.
    
    Media type: `application/problem+json`. Schema: `InvalidReasonCodeErrorResponse | UnknownProductItemIdsErrorResponse | ReturnQuantityExceededErrorResponse`.
    
    One of: `InvalidReasonCodeErrorResponse`, `UnknownProductItemIdsErrorResponse`, `ReturnQuantityExceededErrorResponse`.
    
    _Example InvalidReasonCodeErrorResponseExample: same as POST /organizations/{organizationId}/orders/{orderNo}/actions/oms-cancel-order 400 response._
    
    _Example: UnknownProductItemIdsErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unknown-product-item-ids",
      "detail": "One or more product item IDs in the request are not part of order '00000335'.",
      "title": "Unknown Product Item Ids"
    }
    ```
    
    _Example: ReturnQuantityExceededErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/return-quantity-exceeded",
      "detail": "The return request for order '00000335' exceeds the quantity available to return on one or more items.",
      "title": "Return Quantity Exceeded"
    }
    ```
    
*   **404**
    
    Order was not found. Possible reasons:
    
    *   the order with the given order number is unknown.
    *   the provided access code is invalid or has expired.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    
*   **409**
    
    The order cannot be returned. Possible reasons:
    
    *   The order is no longer in a state that permits return of the requested items.
    *   Order Management (OMS) rejected the return after ECOM accepted the input.
    *   Order Management (OMS) is not active for this site.
    
    Media type: `application/problem+json`. Schema: `OrderReturnFailedErrorResponse | OmsNotActiveErrorResponse`.
    
    One of: `OrderReturnFailedErrorResponse`, `OmsNotActiveErrorResponse`.
    
    _Example: OrderReturnFailedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-return-failed",
      "detail": "Order '00000335' cannot be returned.",
      "title": "Order Return Failed"
    }
    ```
    
    _Example: OmsNotActiveErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/oms-not-active",
      "detail": "Order Management (OMS) is not active for this site.",
      "title": "Oms Not Active"
    }
    ```
    

#### Extension points

*   `sfcc.checkout.shopper-orders.v1.orders.orderNo.actions.oms-return-order.modifyPOSTResponse` (modifyResponse) Called to modify the order returned in the response after the return was initiated.

### POST Request a time-limited access code for a guest order.

`POST /organizations/{organizationId}/orders/{orderNo}/actions/request-access-code`

Operation ID: `requestOrderAccessCode`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Generates a time-limited access code and delivers it via email to the address associated with the order. The shopper can then use this code with the lookup, cancel, and return endpoints to access the order without the original session.

The generated code is valid for 15 minutes. Too many incorrect access attempts invalidate the code early, but the 15-minute cooldown remains — a new code cannot be generated until the original validity period has elapsed, even if the code was invalidated early.

The endpoint always returns 202 — whether the order and email combination is valid, and whether a new code was generated. This uniform response prevents enumeration of valid orders and avoids revealing cooldown state to callers.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `expand` (query, array of string, style: form, explode: false) When you specify `expand=oms`, the integrated Order Management System (OMS) is included during the email validation. If your instance isn't integrated with OMS or the order data isn't available, B2C Commerce ignores the `expand=oms` parameter.  
    Items: Allowed values: `oms`. Example: `oms`.
    
    _Example_
    
    ```
    oms
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `RequestOrderAccessCodeRequest`.

_Example: RequestOrderAccessCode_

```
{
  "email": "shopper@example.com"
}
```

#### Responses

*   **202** Accepted. Always returned, regardless of whether the order and email combination is valid, to prevent enumeration of valid orders. If the combination is valid, a new access code is generated and delivered via email.
*   **400**
    
    The access code request is invalid. Possible reasons:
    
    *   The email field is missing or empty.
    
    Media type: `application/problem+json`. Schema: `InvalidAccessCodeRequestErrorResponse`.
    
    _Example: InvalidAccessCodeRequestErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-code-request",
      "detail": "The access code request is invalid.",
      "title": "Invalid Access Code Request"
    }
    ```
    

#### Extension points

*   `sfcc.app.order.sendOrderAccessCode` (service-logic) Invoked to send the access code via email when the order number and email combination is valid.

### POST Add a payment instrument to an order.

`POST /organizations/{organizationId}/orders/{orderNo}/payment-instruments`

Operation ID: `createPaymentInstrumentForOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Adds a payment instrument to an order.

Details:

The payment instrument is added with the provided details. The payment method must be applicable for the order see GET /baskets/{basketId}/payment-methods, if the payment method is 'CREDIT\_CARD' a paymentCard must be specified in the request.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `OrderPaymentInstrumentRequest`.

_Example: PaymentInstrumentPost_

```
{
  "amount": 700,
  "paymentCard": {
    "expirationYear": 1990,
    "expirationMonth": 7,
    "validFromMonth": 8,
    "validFromYear": 2007,
    "issueNumber": "i117",
    "maskedNumber": "************4567",
    "holder": "Miller",
    "cardType": "Visa"
  },
  "paymentMethodId": "CREDIT_CARD"
}
```

#### Responses

*   **200** Success, the response body contains the order with the added payment instrument.
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example: Order_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "confirmationStatus": "not_confirmed",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "d3f7ae47e5897a6b5d2fd541f0",
          "statusCode": "applied",
          "valid": true
        }
      ],
      "createdBy": "Customer",
      "creationDate": "2019-10-22T12:17:28.341Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "customerName": "Stephanie Miller",
        "email": "shopper@salesforce-test.com"
      },
      "customerName": "Stephanie Miller",
      "exportStatus": "not_exported",
      "groupedTaxItems": [
        {
          "taxRate": 0.05,
          "taxValue": 30.8
        }
      ],
      "guest": true,
      "giftCertificateItems": [
        {
          "amount": 1,
          "giftCertificateItemId": "540db3ffe58bfb04ab673757d7",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-22T12:17:28.376Z",
      "merchandizeTotalTax": 30,
      "orderNo": "00000410",
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 10,
            "type": "amount"
          },
          "reasonCode": "customer service",
          "createdBy": "support",
          "creationDate": "2019-10-22T12:17:28.347Z",
          "custom": true,
          "lastModified": "2019-10-22T12:17:28.349Z",
          "manual": true,
          "price": -10,
          "priceAdjustmentId": "63b9eb9b4a92bd3e5c6ee804c2",
          "promotionId": "5ties"
        }
      ],
      "orderToken": "7gJDIFlnho_mXrxfxVB9Neic3J7szzR9glvgU5Ath-I",
      "orderTotal": 586.76,
      "orderViewCode": "YGXrGbZWlr29tIsGnYgR5o_8OxBMXWigevx1WD0X1Hc",
      "paymentInstruments": [
        {
          "amount": 20,
          "paymentInstrumentId": "ca47e0da3d49b067b630db624a",
          "paymentMethodId": "BML"
        },
        {
          "amount": 566.76,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "6b970a04ca8a468a64b9936764",
          "paymentMethodId": "CREDIT_CARD"
        },
        {
          "amount": 700,
          "paymentCard": {
            "expirationYear": 1990,
            "expirationMonth": 7,
            "validFromMonth": 8,
            "validFromYear": 2007,
            "issueNumber": "i117",
            "maskedNumber": "************4567",
            "holder": "Miller",
            "cardType": "Visa"
          },
          "paymentInstrumentId": "9f21f0b51f206fbde2ff5789e5",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "paymentStatus": "not_paid",
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "d9516eecc64bd90b0022714d26",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "8991e8d7adf0f46ffbc584e175",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.99,
          "priceAfterItemDiscount": 599.99,
          "priceAfterOrderDiscount": 589.99,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 37,
          "adjustedShippingTotalTax": 0.5,
          "deliveryWindow": {
            "startAt": "2026-05-04T14:00:00Z",
            "endAt": "2026-05-07T22:00:00Z"
          },
          "gift": false,
          "merchandizeTotalTax": 30,
          "orderCutoffAt": "2026-04-27T14:00:00Z",
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "d5d95acf5381dc6e273b4336a7",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99,
            "deliveryWindow": {
              "startAt": "2026-05-04T14:00:00Z",
              "endAt": "2026-05-07T22:00:00Z"
            },
            "orderCutoffAt": "2026-04-27T14:00:00Z"
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "768abee75aa8015239a9696c7e",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingStatus": "not_shipped",
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "status": "new",
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the given order number is invalid.
    *   the provided payment method is invalid or not applicable.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The order with the given order number is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### DELETE Remove a payment instrument from an order.

`DELETE /organizations/{organizationId}/orders/{orderNo}/payment-instruments/{paymentInstrumentId}`

Operation ID: `removePaymentInstrumentFromOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Removes a payment instrument of an order.

#### Parameters

*   `paymentInstrumentId` (path, PaymentInstrumentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the order without the deleted payment instrument.
    
    Media type: `application/json`. Schema: `Order`.
    
*   **404**
    
    Possible reasons:
    
    *   The order with the given order number is unknown.
    *   The payment instrument with the given order payment instrument ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### PATCH Update payment instrument details for an order.

`PATCH /organizations/{organizationId}/orders/{orderNo}/payment-instruments/{paymentInstrumentId}`

Operation ID: `updatePaymentInstrumentForOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Updates a payment instrument of an order.

Details:

The payment instrument is updated with the provided details. The payment method must be applicable for the order see GET /baskets/{basketId}/payment-methods, if the payment method is 'CREDIT\_CARD' a paymentCard must be specified in the request.

#### Parameters

*   `paymentInstrumentId` (path, PaymentInstrumentId, required)
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `OrderPaymentInstrumentRequest`.

_Example: PaymentInstrumentPatch_

```
{
  "amount": 2,
  "paymentMethodId": "CREDIT_CARD",
  "paymentCard": {
    "cardType": "Visa",
    "maskedNumber": "****-****-****-4567"
  }
}
```

_Example: PaymentInstrumentPatchWithSalesforcePayments_

```
{
  "amount": 700,
  "paymentMethodId": "Salesforce Payments",
  "paymentReferenceRequest": {
    "paymentMethodType": "card",
    "zoneId": "Amer-Zone",
    "gateway": "stripe",
    "gatewayProperties": {
      "stripe": {
        "setupFutureUsage": "on_session"
      }
    }
  }
}
```

#### Responses

*   **200** Success, the response body contains the order with the updated payment instrument. When Salesforce Payments is enabled, the paymentReference object will be included in the paymentInstruments.
    
    Media type: `application/json`. Schema: `Order`.
    
    _Example: Order_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "confirmationStatus": "not_confirmed",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "d3f7ae47e5897a6b5d2fd541f0",
          "statusCode": "applied",
          "valid": true
        }
      ],
      "createdBy": "Customer",
      "creationDate": "2019-10-22T12:17:28.341Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "customerName": "Stephanie Miller",
        "email": "shopper@salesforce-test.com"
      },
      "customerName": "Stephanie Miller",
      "exportStatus": "not_exported",
      "groupedTaxItems": [
        {
          "taxRate": 0.05,
          "taxValue": 30.8
        }
      ],
      "guest": true,
      "giftCertificateItems": [
        {
          "amount": 1,
          "giftCertificateItemId": "540db3ffe58bfb04ab673757d7",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-22T12:17:28.376Z",
      "merchandizeTotalTax": 30,
      "orderNo": "00000410",
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 10,
            "type": "amount"
          },
          "reasonCode": "customer service",
          "createdBy": "support",
          "creationDate": "2019-10-22T12:17:28.347Z",
          "custom": true,
          "lastModified": "2019-10-22T12:17:28.349Z",
          "manual": true,
          "price": -10,
          "priceAdjustmentId": "63b9eb9b4a92bd3e5c6ee804c2",
          "promotionId": "5ties"
        }
      ],
      "orderToken": "7gJDIFlnho_mXrxfxVB9Neic3J7szzR9glvgU5Ath-I",
      "orderTotal": 586.76,
      "orderViewCode": "YGXrGbZWlr29tIsGnYgR5o_8OxBMXWigevx1WD0X1Hc",
      "paymentInstruments": [
        {
          "amount": 20,
          "paymentInstrumentId": "ca47e0da3d49b067b630db624a",
          "paymentMethodId": "BML"
        },
        {
          "amount": 566.76,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "6b970a04ca8a468a64b9936764",
          "paymentMethodId": "CREDIT_CARD"
        },
        {
          "amount": 2,
          "paymentCard": {
            "expirationYear": 1990,
            "expirationMonth": 7,
            "validFromMonth": 8,
            "validFromYear": 2007,
            "issueNumber": "i117",
            "maskedNumber": "******4567",
            "holder": "Miller",
            "cardType": "Visa"
          },
          "paymentInstrumentId": "9f21f0b51f206fbde2ff5789e5",
          "paymentMethodId": "CREDIT_CARD"
        }
      ],
      "paymentStatus": "not_paid",
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "d9516eecc64bd90b0022714d26",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "8991e8d7adf0f46ffbc584e175",
              "itemText": "We will plant a tree for your order.",
              "optionId": "plantATree",
              "optionValueId": "000",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "000",
              "productName": "Plant a tree.",
              "quantity": 3,
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxClassId": "standard",
              "taxRate": 0.05
            }
          ],
          "price": 599.99,
          "priceAfterItemDiscount": 599.99,
          "priceAfterOrderDiscount": 589.99,
          "productId": "green-umbrella",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 3,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 599.97,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 599.97,
      "productTotal": 599.97,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 37,
          "adjustedShippingTotalTax": 0.5,
          "deliveryWindow": {
            "startAt": "2026-05-04T14:00:00Z",
            "endAt": "2026-05-07T22:00:00Z"
          },
          "gift": false,
          "merchandizeTotalTax": 30,
          "orderCutoffAt": "2026-04-27T14:00:00Z",
          "productSubTotal": 599.97,
          "productTotal": 599.97,
          "shipmentId": "me",
          "shipmentTotal": 646.76,
          "shippingAddress": {
            "address1": "4162  Turkey Pen Road",
            "city": "New York",
            "countryCode": "US",
            "firstName": "Agustin",
            "fullName": "Agustin Estes",
            "id": "d5d95acf5381dc6e273b4336a7",
            "lastName": "Estes",
            "postalCode": "10016",
            "stateCode": "NY"
          },
          "shippingMethod": {
            "description": "Order received within 7-10 business days",
            "id": "001",
            "name": "Ground",
            "price": 15.99,
            "deliveryWindow": {
              "startAt": "2026-05-04T14:00:00Z",
              "endAt": "2026-05-07T22:00:00Z"
            },
            "orderCutoffAt": "2026-04-27T14:00:00Z"
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "768abee75aa8015239a9696c7e",
          "itemText": "Shipping",
          "price": 15.99,
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxClassId": "standard",
          "taxRate": 0.05
        }
      ],
      "shippingStatus": "not_shipped",
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "status": "new",
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
    _Example: OrderWhenSalesforcePaymentsEnabled_
    
    ```
    {
      "adjustedMerchandizeTotalTax": 30,
      "adjustedShippingTotalTax": 0.8,
      "billingAddress": {
        "address1": "104 Presidential Way",
        "city": "Woburn",
        "countryCode": "US",
        "firstName": "Stephanie",
        "fullName": "Stephanie Miller",
        "id": "5f695b6f4bb63cb686483d65a0",
        "lastName": "Miller",
        "postalCode": "01801",
        "stateCode": "MA"
      },
      "channelType": "storefront",
      "confirmationStatus": "not_confirmed",
      "couponItems": [
        {
          "code": "5ties",
          "couponItemId": "d3f7ae47e5897a6b5d2fd541f0",
          "statusCode": "applied",
          "valid": true
        }
      ],
      "createdBy": "Customer",
      "creationDate": "2019-10-22T12:17:28.341Z",
      "currency": "USD",
      "customerInfo": {
        "customerId": "beQeANXJNsd0xcINsB6cSrobQa",
        "customerName": "Stephanie Miller",
        "email": "shopper@salesforce-test.com"
      },
      "customerName": "Stephanie Miller",
      "exportStatus": "not_exported",
      "groupedTaxItems": [
        {
          "taxRate": 0.05,
          "taxValue": 30.8
        }
      ],
      "guest": true,
      "giftCertificateItems": [
        {
          "amount": 1,
          "giftCertificateItemId": "540db3ffe58bfb04ab673757d7",
          "recipientEmail": "miller@salesforce-test.com",
          "shipmentId": "me"
        }
      ],
      "lastModified": "2019-10-22T12:17:28.376Z",
      "merchandizeTotalTax": 30,
      "orderNo": "00000410",
      "orderPriceAdjustments": [
        {
          "appliedDiscount": {
            "amount": 10,
            "type": "amount"
          },
          "reasonCode": "customer service",
          "createdBy": "support",
          "creationDate": "2019-10-22T12:17:28.347Z",
          "custom": true,
          "lastModified": "2019-10-22T12:17:28.349Z",
          "manual": true,
          "price": -10,
          "priceAdjustmentId": "63b9eb9b4a92bd3e5c6ee804c2",
          "promotionId": "5ties"
        }
      ],
      "orderToken": "7gJDIFlnho_mXrxfxVB9Neic3J7szzR9glvgU5Ath-I",
      "orderTotal": 586.76,
      "orderViewCode": "YGXrGbZWlr29tIsGnYgR5o_8OxBMXWigevx1WD0X1Hc",
      "paymentInstruments": [
        {
          "amount": 20,
          "paymentInstrumentId": "ca47e0da3d49b067b630db624a",
          "paymentMethodId": "PAYPAL",
          "paymentReference": {
            "paymentReferenceId": "PAY-1AB23456CD789012EF34GHIJ"
          }
        },
        {
          "amount": 566.76,
          "paymentCard": {
            "cardType": "Visa",
            "creditCardExpired": false
          },
          "paymentInstrumentId": "6b970a04ca8a468a64b9936764",
          "paymentMethodId": "CREDIT_CARD",
          "paymentReference": {
            "paymentReferenceId": "8815749596351791C"
          }
        },
        {
          "amount": 2,
          "paymentCard": {
            "expirationYear": 1990,
            "expirationMonth": 7,
            "validFromMonth": 8,
            "validFromYear": 2007,
            "issueNumber": "i117",
            "maskedNumber": "******4567",
            "holder": "Miller",
            "cardType": "Visa"
          },
          "paymentInstrumentId": "9f21f0b51f206fbde2ff5789e5",
          "paymentMethodId": "CREDIT_CARD",
          "paymentReference": {
            "paymentReferenceId": "pi_1J4K5L2eZvKYlo2CyZ8K5L6M",
            "gateway": "stripe",
            "gatewayProperties": {
              "stripe": {
                "setupFutureUsage": "on_session",
                "clientSecret": "pi_1J4K5L2eZvKYlo2CyZ8K5L6M_secret_abcdef123456"
              }
            }
          }
        }
      ],
      "paymentStatus": "not_paid",
      "productItems": [
        {
          "adjustedTax": 30,
          "basePrice": 199.99,
          "bonusProductLineItem": false,
          "gift": false,
          "itemId": "d9516eecc64bd90b0022714d26",
          "itemText": "Green Umbrella - Sustained Edition",
          "optionItems": [
            {
              "adjustedTax": 0,
              "basePrice": 0,
              "bonusProductLineItem": false,
              "gift": false,
              "itemId": "8991e8d7adf0f46ffbc584e175",
              "itemText": "Monogramming: Letter \"A\"",
              "optionId": "textMonogramLetters",
              "optionValueId": "A",
              "price": 0,
              "priceAfterItemDiscount": 0,
              "priceAfterOrderDiscount": 0,
              "productId": "701643632930",
              "productName": "Flat Front Pant",
              "shipmentId": "me",
              "tax": 0,
              "taxBasis": 0,
              "taxRate": 0.05
            }
          ],
          "priceAfterItemDiscount": 199.99,
          "priceAfterOrderDiscount": 199.99,
          "productId": "701643632930",
          "productName": "Green Umbrella - Sustained Edition",
          "quantity": 1,
          "shipmentId": "me",
          "tax": 30,
          "taxBasis": 199.99,
          "taxRate": 0.05
        }
      ],
      "productSubTotal": 199.99,
      "productTotal": 199.99,
      "shipments": [
        {
          "adjustedMerchandizeTotalTax": 30,
          "adjustedShippingTotalTax": 0.8,
          "gift": false,
          "merchandizeTotalTax": 199.99,
          "productSubTotal": 199.99,
          "productTotal": 199.99,
          "shipmentId": "me",
          "shipmentNo": "00000001",
          "shipmentTotal": 386.75,
          "shippingAddress": {
            "address1": "104 Presidential Way",
            "city": "Woburn",
            "countryCode": "US",
            "firstName": "Stephanie",
            "fullName": "Stephanie Miller",
            "id": "5f695b6f4bb63cb686483d65a0",
            "lastName": "Miller",
            "postalCode": "01801",
            "stateCode": "MA"
          },
          "shippingMethod": {
            "description": "Order within the next 3 hours to get it tomorrow morning",
            "id": "EXPRESS",
            "name": "Express",
            "price": 15.99,
            "shippingPromotions": [
              {
                "calloutMsg": "Free shipping amount has been reduced!",
                "promotionId": "freeshipping_level1",
                "promotionName": "Free shipping Level 1"
              }
            ]
          },
          "shippingStatus": "not_shipped",
          "shippingTotal": 15.99,
          "shippingTotalTax": 0.8,
          "taxTotal": 30.8
        }
      ],
      "shippingItems": [
        {
          "adjustedTax": 0.8,
          "basePrice": 15.99,
          "itemId": "768abee75aa8015239a9696c7e",
          "itemText": "Shipping",
          "priceAfterItemDiscount": 15.99,
          "shipmentId": "me",
          "tax": 0.8,
          "taxBasis": 15.99,
          "taxRate": 0.05
        }
      ],
      "shippingStatus": "not_shipped",
      "shippingTotal": 15.99,
      "shippingTotalTax": 0.8,
      "status": "new",
      "taxation": "net",
      "taxTotal": 30.8
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the basket payment instrument with the given ID already is permanently masked.
    *   the provided payment method is invalid or not applicable.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404**
    
    Possible reasons:
    
    *   The order with the given order number is unknown.
    *   The payment instrument with the given payment instrument ID is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### GET Retrieve payment instrument details for an order.

`GET /organizations/{organizationId}/orders/{orderNo}/payment-methods`

Operation ID: `getPaymentMethodsForOrder`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Gets the applicable payment methods for an existing order considering the open payment amount only.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the applicable payment methods for the order.
    
    Media type: `application/json`. Schema: `PaymentMethodResult`.
    
    _Example: PaymentMethodResult_
    
    ```
    {
      "applicablePaymentMethods": [
        {
          "id": "GIFT_CERTIFICATE",
          "name": "Gift Certificate",
          "paymentProcessorId": "BASIC_GIFT_CERTIFICATE"
        },
        {
          "cards": [
            {
              "cardType": "Visa",
              "checksumVerificationEnabled": true,
              "name": "Visa",
              "numberLengths": [
                "13",
                "16"
              ],
              "numberPrefixes": [
                "4"
              ],
              "securityCodeLength": 3
            },
            {
              "cardType": "Amex",
              "checksumVerificationEnabled": true,
              "name": "American Express",
              "numberLengths": [
                "15"
              ],
              "numberPrefixes": [
                "34",
                "37"
              ],
              "securityCodeLength": 4
            },
            {
              "cardType": "Master Card",
              "checksumVerificationEnabled": true,
              "name": "MasterCard",
              "numberLengths": [
                "16"
              ],
              "numberPrefixes": [
                "51-55"
              ],
              "securityCodeLength": 3
            },
            {
              "cardType": "Discover",
              "checksumVerificationEnabled": true,
              "name": "Discover",
              "numberLengths": [
                "16"
              ],
              "numberPrefixes": [
                "6011",
                "622126-622925",
                "644-649",
                "65"
              ],
              "securityCodeLength": 3
            }
          ],
          "id": "CREDIT_CARD",
          "name": "Credit Card",
          "paymentProcessorId": "BASIC_CREDIT"
        },
        {
          "id": "PayPal",
          "name": "Pay Pal",
          "paymentProcessorId": "PAYPAL_EXPRESS"
        },
        {
          "id": "BML",
          "name": "Bill Me Later",
          "paymentProcessorId": "CYBERSOURCE_BML"
        }
      ]
    }
    ```
    
*   **400** The customer assigned to the order does not match the verified customer represented by the JSON Web Token (JWT).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as POST /organizations/{organizationId}/orders 400 response._
    
*   **404** The order with the given order number is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    

### GET Retrieve external taxation data for an order.

`GET /organizations/{organizationId}/orders/{orderNo}/taxes`

Operation ID: `getTaxesFromOrder`. Security: AmOAuth2 (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw).

This method gives you the external taxation data of the order transferred from the basket during order creation. This endpoint can be called only if external taxation was used. See POST /baskets for more information.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `orderNo` (path, OrderNo, required) The order number of the order to be modified.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success, the response body contains the external taxation from all items from the referenced order.
    
    Media type: `application/json`. Schema: `Taxes`.
    
    _Example: Taxes_
    
    ```
    {
      "taxes": {
        "3d4e28425ce0b3a65b0ac4e163": {
          "taxItems": [
            {
              "id": "DE_7",
              "rate": 0.07,
              "value": 13.99
            },
            {
              "id": "DE_19",
              "rate": 0.19
            }
          ]
        },
        "ff9452ed11fcf5c80f9143a8f1": {
          "taxItems": [
            {
              "id": "US_1",
              "rate": 0.01
            },
            {
              "id": "US_5",
              "rate": 0.05
            }
          ]
        }
      }
    }
    ```
    
*   **404** The order with the given order number is unknown.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: OrderNotFound_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/order-not-found",
      "title": "Order Not Found",
      "detail": "No order with number '123' was found."
    }
    ```
    
*   **409**
    
    Possible Reasons:
    
    *   The tax mode of the referenced basket is not set to EXTERNAL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidTaxMode_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-tax-mode",
      "title": "Invalid Tax Mode",
      "detail": "Basket with ID 'a10ff320829cb0eef93ca5310a' has invalid tax mode."
    }
    ```
    
    _Example: UnsupportedRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-request-if-scapi-hooks-enabled",
      "title": "Unsupported Request If SCAPI Hooks Enabled",
      "detail": "You can't call this endpoint because Salesforce Commerce API hook execution is enabled."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### Basket

Document representing a basket.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `agentBasket` (_boolean_) Is the basket created by an agent? It is read only.  
    Example: `true`.
*   `basketId` (_string_) The unique identifier for the basket. It is read only.  
    Example: `e78aa5646a8efebdd9cdd38be7`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `OrderAddress`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `channelType` (_string_) The sales channel. It is read only.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`, `chatgpt`, `gemini`. Example: `storefront`.
*   `couponItems` (_array of CouponItem_) The coupon items.
*   `creationDate` (_string (date-time)_) The timestamp when the basket was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `currency` (_CurrencyCode_)
*   `customerInfo` (_object_) The customer information, if the customer is logged in.
    
    Includes all fields of `CustomerInfo`.
    
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items.
*   `groupedTaxItems` (_array of GroupedTaxItem_) Tax values that are grouped and summed based on the tax rate. The tax totals of the line items with the same tax rate are grouped together and summed up. This does not affect the calculation in any way. It is read only.
*   `inventoryReservationExpiry` (_string (date-time)_) The expiration datetime of the inventory reservation. It is read only.  
    Example: `2015-05-19T15:30:18.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the basket was last modified. It is read only.  
    Example: `2015-05-19T15:25:18.000Z`.
*   `merchandizeTotalTax` (_number (double)_) The total products tax in the purchase currency. Merchandise total price represents the sum of the product prices before services (such as shipping) or adjustments from promotions have been added. It is read only.  
    Example: `4.95`.
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments.
*   `orderTotal` (_number (double)_) The total price, including products, shipping and tax. It is read only.  
    Example: `110.24`.
*   `paymentInstruments` (_array of OrderPaymentInstrument_) The payment instruments list.
*   `productItems` (_array of BasketProductItem_) The product items.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products including adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `88`.
*   `shipments` (_array of Shipment_) The shipments.
*   `shippingItems` (_array of ShippingItem_) The shipping items.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments. It is read only.  
    Example: `0.3`.
*   `sourceCode` (_string_) The source code assigned to the basket. It is read only.  
    Example: `OUTDOOR1`.
*   `taxTotal` (_number (double)_) The total tax amount. It is read only.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net). It is read only.  
    Allowed values: `gross`, `net`. Example: `net`.
*   `taxRoundedAtGroup` (_boolean_) If the tax is rounded at the group level, this is set to true. If the tax is rounded at the item or unit level, it is set to false.  
    Example: `true`.
*   `temporaryBasket` (_boolean_) If the created basket is a temporary basket, this is set to true. Otherwise, it is set to false.  
    Example: `true`.
*   `approachingDiscounts` (_array of ApproachingDiscount_) A list of approaching discount objects for the basket. The list includes both order-level and shipping-level promotions. This field is only included when the expand query parameter contains 'approaching\_discounts'.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Order

Document representing an order.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the order, including price adjustments, but not including service charges such as shipping. It is read only.  
    Example: `1.5`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the order, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `billingAddress` (_object_) The billing address.
    
    Includes all fields of `OrderAddress`.
    
*   `bonusDiscountLineItems` (_array of BonusDiscountLineItem_) The bonus discount line items.
*   `channelType` (_string_) The sales channel. It is read only.  
    Allowed values: `storefront`, `callcenter`, `marketplace`, `dss`, `store`, `pinterest`, `twitter`, `facebookads`, `subscriptions`, `onlinereservation`, `customerservicecenter`, `instagramcommerce`, `tiktok`, `snapchat`, `google`, `whatsapp`, `youtube`, `chatgpt`, `gemini`. Example: `storefront`.
*   `confirmationStatus` (_string_) The confirmation status.  
    Allowed values: `not_confirmed`, `confirmed`. Example: `confirmed`.
*   `couponItems` (_array of CouponItem_) The coupon items. It is read only.
*   `createdBy` (_string_) This value depends on how the order was created. If a shopper created the order, this value is Customer. If a job created the order, this value is System. Otherwise, this value is the name of the user who created the order. It is read only.  
    Example: `Customer`.
*   `creationDate` (_string (date-time)_) The timestamp when the order was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `currency` (_object_) The ISO 4217 mnemonic code of the currency. It is read only.
    
    Includes all fields of `CurrencyCode`.
    
*   `customerInfo` (_object_) The customer information for guest or logged-in customers. It is read only.
    
    Includes all fields of `CustomerInfo`.
    
*   `customerName` (_string_) The customer name. It is read only.  
    Example: `Max Mustermann`.
*   `exportStatus` (_string_) The export status of the order.  
    Allowed values: `not_exported`, `exported`, `ready`, `failed`. Example: `exported`.
*   `externalOrderStatus` (_string_) The external status of the order.  
    Example: `Submitted`.
*   `giftCertificateItems` (_array of GiftCertificateItem_) The gift certificate line items. It is read only.
*   `globalPartyId` (_string_) The Customer 360 Global Party ID associated with the shopper. It is read only.  
    Example: `GP_1234`.
*   `lastModified` (_string (date-time)_) The timestamp when the order was last modified. It is read only.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `merchandizeTotalTax` (_number (double)_) The total products tax in the purchase currency. Merchandise total prices represent the sum of product prices not including shipping or adjustments. It is read only.  
    Example: `1.5`.
*   `orderNo` (_object_) The order number.  
    Example: `00000410`.
    
    Includes all fields of `OrderNo`.
    
    Example: `00000410`.
    
*   `orderPriceAdjustments` (_array of PriceAdjustment_) The order-level price adjustments. It is read only.
*   `orderToken` (_string_) The order token used to secure the lookup of an order on base of the plain order number. The order token contains only URL safe characters. It is read only.
*   `orderTotal` (_number (double)_) The total price, including products, shipping, and tax. It is read only.  
    Example: `110.24`.
*   `orderViewCode` (_string_) The order view code used to secure the order lookup of an order using Order Lookup API. The order view code contains only URL safe characters. Warning : Order view code must not be exposed in the URL and must only be displayed to the shopper or sent as an email. Order view code must not be logged in the code. It is read only.
*   `paymentInstruments` (_array of OrderPaymentInstrument_) The payment instruments list.
*   `paymentStatus` (_string_) The payment status.  
    Allowed values: `not_paid`, `part_paid`, `paid`. Example: `paid`.
*   `productItems` (_array of OrderProductItem_) The product items. It is read only.
*   `productSubTotal` (_number (double)_) The total price of all products including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `taxRoundedAtGroup` (_boolean_) If the tax is rounded at the group level, this is set to true. If the tax is rounded at the item or unit level, it is set to false. It is read only.  
    Example: `true`.
*   `shipments` (_array of Shipment_) The shipments. It is read only.
*   `shippingItems` (_array of ShippingItem_) The shipping items. It is read only.
*   `shippingStatus` (_string_) The shipping status.  
    Allowed values: `not_shipped`, `part_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on all shipping charges, not including shipping adjustments. It is read only.  
    Example: `0.3`.
*   `siteId` (_object_) The order's site. It is read only.  
    Example: `ShoppingSite`.
    
    Includes all fields of `SiteId`.
    
    Example: `ShoppingSite`.
    
*   `omsData` (_object_) Information retrieved from Order Management (OMS) for the order.
    
    Includes all fields of `OmsData`.
    
*   `sourceCode` (_string_) The source code assigned to the basket from which this order was created. It is read only.  
    Example: `OUTDOOR1`.
*   `status` (_string_) The status.  
    Allowed values: `created`, `new`, `completed`, `cancelled`, `replaced`, `failed`. Example: `created`.
*   `taxTotal` (_number (double)_) The total tax amount. It is read only.  
    Example: `5.25`.
*   `taxation` (_string_) The taxation policy (gross or net). It is read only.  
    Allowed values: `gross`, `net`. Example: `net`.
*   `groupedTaxItems` (_array of GroupedTaxItem_) Tax values that are grouped and summed based on the tax rate. The tax totals of the line items with the same tax rate are grouped together and summed up. This does not affect the calculation in any way. It is read only.
*   `guest` (_boolean_) The registration status of the customer. It is read only.  
    Example: `true`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### OmsMetaData

Configuration data from Order Management (OMS) that the storefront requires to render cancel and return experiences.

*   `cancelReasonCodes` (_array of OmsReasonCode_, required) The reason codes available for cancelling an order. The server applies the reason marked with `default` when no reason is supplied on the cancel request.
*   `returnReasonCodes` (_array of OmsReasonCode_, required) The reason codes available for returning order items. The server applies the reason marked with `default` when no reason is supplied on a returned item.

### OmsNotActiveErrorResponse

Indicates that an OMS-dependent endpoint was called for a site that does not have OMS enabled.

Includes all fields of `ErrorResponse`.

### OrderNo

The order number

Type: `string`.

Minimum length: 1. Maximum length: 50. Example: `00000410`.

### OrderLookupRequest

Document representing an order lookup request.

*   `email` (_string_) The customer's email address associated with order to be looked up.  
    Example: `no-reply@salesforce.com`.
*   `orderViewCode` (_string_) The order view code associated with the order to be looked up.
*   `postalCode` (_string_) The billing address postal code of the order to be looked up.  
    Maximum length: 256. Example: `05408`.
*   `phone` (_string_) The phone number of the order to be looked up.  
    Maximum length: 256. Example: `6175555555`.

### FailOrderRequest

Document representing a fail order request.

*   `reasonCode` (_string_) The reason code for failing the order.  
    Allowed values: `payment_confirm_failure`, `payment_capture_failure`, `payment_auth_failure`. Example: `payment_confirm_failure`.

### OmsCancelOrderRequest

Document representing a request to cancel an order that is integrated with Order Management (OMS). The cancellation always applies to the entire order; partial cancellations are not supported.

*   `reason` (_string_) The reason for cancelling the order. The value must match one of the `cancelReasonCodes` configured in OMS and returned by the `getOmsMetaData` endpoint. When omitted, the default reason code configured in OMS is applied by the server.  
    Maximum length: 256. Example: `Not specified`.
*   `orderAccessCode` (_OrderAccessCode_)

### InvalidReasonCodeErrorResponse

Indicates that the supplied reason code does not match any reason configured in OMS.

Includes all fields of `ErrorResponse`.

*   `reason` (_string_) The reason value that the request supplied.  
    Maximum length: 256. Example: `Damaged in transit`.

### OrderCancelFailedErrorResponse

Returned when the order cannot be cancelled. This covers both the case where the order's state no longer permits cancellation and the case where Order Management (OMS) rejected the cancel request after ECOM accepted the input.

Includes all fields of `ErrorResponse`.

*   `orderNo` (_string_) The order number from the request path.  
    Maximum length: 256. Example: `00000335`.

### OmsReturnOrderRequest

Document representing a request to initiate the return of one or more items of an order that is integrated with Order Management (OMS).

*   `productItems` (_array of OmsReturnProductItem_, required) The product items of the order for which to initiate a return.  
    Minimum items: 1.
*   `orderAccessCode` (_OrderAccessCode_)

### UnknownProductItemIdsErrorResponse

Indicates that one or more `productItems[].itemId` values supplied in the return request do not match any product item of the order.

Includes all fields of `ErrorResponse`.

*   `orderNo` (_string_) The order number from the request path.  
    Maximum length: 256. Example: `00000335`.
*   `unknownItemIds` (_array of string_) The `productItems[].itemId` values from the request that do not match any product item of the order.  
    Items: Maximum length: 256. Example: `10uVF0000003W0BYAU`.
    
    _Example_
    
    ```
    [
      "10uVF0000003W0BYAU",
      "11uVF0000045W0BYAU"
    ]
    ```
    

### ReturnQuantityExceededErrorResponse

Returned when one or more `productItems` entries in the return request specify a quantity that exceeds the quantity available to return for that item. Issue a GET on the order to obtain the current available quantities and resubmit with valid values.

Includes all fields of `ErrorResponse`.

*   `orderNo` (_string_) The order number from the request path.  
    Maximum length: 256. Example: `00000335`.
*   `itemIds` (_array of string_) The `productItems[].itemId` values from the request whose requested quantity exceeded the quantity available to return.  
    Items: Maximum length: 256. Example: `10uVF0000003W0BYAU`.
    
    _Example_
    
    ```
    [
      "10uVF0000003W0BYAU",
      "11uVF0000045W0BYAU"
    ]
    ```
    

### OrderReturnFailedErrorResponse

Returned when the order cannot be returned. This covers both the case where the order's state no longer permits return of the requested items and the case where Order Management (OMS) rejected the return request after ECOM accepted the input. Obvious input problems are reported as 400 Bad Request before the request reaches OMS.

Includes all fields of `ErrorResponse`.

*   `orderNo` (_string_) The order number from the request path.  
    Maximum length: 256. Example: `00000335`.

### RequestOrderAccessCodeRequest

Represents a request to generate a time-limited access code for a guest order.

*   `email` (_string_, required) The email address of the shopper. Must match the email address associated with the order for a code to be generated and sent.  
    Maximum length: 256. Example: `shopper@example.com`.

### InvalidAccessCodeRequestErrorResponse

Indicates that the request to generate an access code is invalid, for example, because the email field is missing or empty.

Includes all fields of `ErrorResponse`.

### OrderPaymentInstrumentRequest

Document representing an order payment instrument request.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `12030000`.
*   `giftCertificateCode` (_string_) The gift certificate code.  
    Maximum length: 256.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `OrderPaymentCardRequest`.
    
*   `giftCardRequest` (_object_) The gift card request.
    
    Includes all fields of `GiftCardRequest`.
    
*   `paymentMethodId` (_string_) The payment method ID.  
    Maximum length: 256. Example: `CREDIT_CARD`.
*   `paymentReferenceRequest` (_object_) Payment reference information for various payment service providers, only when Salesforce Payments is enabled.
    
    Includes all fields of `PaymentReferenceRequest`.
    

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PaymentInstrumentId

The payment instrument ID

Type: `string`.

Example: `ba248424e3eee797f062162f8b`.

### PaymentMethodResult

Result document of payment methods applicable for a basket.

*   `applicablePaymentMethods` (_array of PaymentMethod_) The applicable payment methods. It is read only.

### Taxes

Document representing the tax rates and (optionally) amounts for all items in a basket.

*   `taxes` (_object_, required) Map containing the TaxItems for the line item ids: Map<LineItemId, TaxItems \[\]>
    
    Additional properties: `TaxItems`.
    

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### OrderAddress

Document representing an order address.

*   `address1` (_string_) The first address line.  
    Example: `45 Main Rd.`.
*   `address2` (_string_) The second address line.  
    Example: `Apartment 204`.
*   `city` (_string_) The city.  
    Example: `Boston`.
*   `companyName` (_string_) The company name.  
    Example: `Salesforce`.
*   `countryCode` (_CountryCode_)
*   `firstName` (_string_) The first name.  
    Example: `Max`.
*   `fullName` (_string_) The full name.  
    Example: `Max Mustermann`.
*   `id` (_string_) The ID of the address.  
    Example: `me`.
*   `jobTitle` (_string_) The job title.  
    Example: `Software Engineer`.
*   `lastName` (_string_) The last name.  
    Example: `Mustermann`.
*   `phone` (_string_) The phone number.  
    Example: `6175555555`.
*   `postBox` (_string_) The post office box.  
    Example: `PO BOX 109`.
*   `postalCode` (_string_) The postal code.  
    Example: `05408`.
*   `salutation` (_string_) The salutation.  
    Example: `Mr`.
*   `secondName` (_string_) The second name.
*   `stateCode` (_string_) The state code.  
    Example: `MA`.
*   `suffix` (_string_) The suffix.  
    Example: `Sr`.
*   `suite` (_string_) The suite.  
    Example: `24A`.
*   `title` (_string_) The title.  
    Example: `Dr.`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### BonusDiscountLineItem

Document representing a bonus discount line item.

*   `bonusProducts` (_array of ProductDetailsLink_) The bonus products the customer can choose from.
*   `couponCode` (_string_) The coupon code that triggered the promotion, if applicable.  
    Example: `5ties`.
*   `id` (_string_) The ID of the line item. It is read only.  
    Example: `91f4dd8bfa0653d58b7783b04f`.
*   `maxBonusItems` (_integer (int32)_) The maximum number of bonus items the user can select for this promotion.
*   `promotionId` (_string_) The ID of the promotion that triggered the creation of the line item.  
    Example: `Buy1Get2`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CouponItem

Document representing a coupon item.

*   `code` (_string_, required) The coupon code.  
    Maximum length: 256. Example: `5ties`.
*   `couponItemId` (_object_) The coupon item ID. It is read only.
    
    Includes all fields of `CouponItemId`.
    
*   `statusCode` (_string_) The status of the coupon item. It is read only.  
    Allowed values: `coupon_code_already_in_basket`, `coupon_code_already_redeemed`, `coupon_code_unknown`, `coupon_disabled`, `redemption_limit_exceeded`, `customer_redemption_limit_exceeded`, `timeframe_redemption_limit_exceeded`, `no_active_promotion`, `coupon_already_in_basket`, `no_applicable_promotion`, `applied`, `adhoc`. Example: `no_applicable_promotion`.
*   `valid` (_boolean_) A flag indicating whether the coupon item is valid. A coupon line item is valid if the status code is "applied" or "no\_applicable\_promotion". It is read only.  
    Example: `true`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### CustomerInfo

The customer information for guest or logged-in customers.

*   `customerId` (_string_) The customer ID. It is read only.  
    Maximum length: 100. Example: `abMKqMaNYOBMnNdDNzyC5oNTi5`.
*   `customerName` (_string_) The customer name.  
    Example: `Max Mustermann`.
*   `customerNo` (_string_) The customer number.  
    Maximum length: 100. Example: `0002352`.
*   `email` (_string_, required) The customer's email address.  
    Example: `no-reply@salesforce.com`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GiftCertificateItem

A gift certificate item.

*   `amount` (_number (double)_, required) The gift certificate item amount.  
    Example: `20`.
*   `giftCertificateItemId` (_object_) The item ID. It is read only.
    
    Includes all fields of `GiftCertificateItemId`.
    
*   `message` (_string_) The gift certificate message.  
    Maximum length: 4000. Example: `Birthday present.`.
*   `recipientEmail` (_string_, required) The recipient email.  
    Minimum length: 1. Example: `no-reply@salesforce.com`.
*   `recipientName` (_string_) The recipient's name.  
    Example: `Daniel Mustermann`.
*   `senderName` (_string_) The sender's name.  
    Example: `Max Mustermann`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### GroupedTaxItem

Document representing the grouped tax item.

*   `taxRate` (_number (double)_) The tax rate. It is read only.  
    Example: `0.1`.
*   `taxValue` (_number (double)_) The summed up tax total for the tax rate. It is read only.  
    Example: `10.03`.

### PriceAdjustment

Document representing a price adjustment within a basket or order. Price adjustments can be assigned at the order, product, or shipping level.

*   `appliedDiscount` (_object_) Details describing the discount this price adjustment is based on. For adjustments not based on a discount, this value is null.
    
    Includes all fields of `Discount`.
    
*   `couponCode` (_string_) The coupon code of the coupon this price adjustment is based on. For adjustments not based on a coupon, this value is null. It is read only.  
    Example: `5ties`.
*   `createdBy` (_string_) The user who created the price adjustment. It is read only.  
    Example: `Support`.
*   `creationDate` (_string (date-time)_) The timestamp when the price adjustment was created. It is read only.  
    Example: `2015-05-19T15:23:18.000Z`.
*   `custom` (_boolean_) A flag indicating whether this price adjustment was created by custom logic. This flag is set to true unless the price adjustment was created by the promotion engine.  
    Example: `true`.
*   `itemText` (_string_) The text describing the item.
*   `lastModified` (_string (date-time)_) The timestamp when the price adjustment was last modified. It is read only.  
    Example: `2021-02-25T09:58:08.715Z`.
*   `manual` (_boolean_) A flag indicating whether this price adjustment was created by a manual process. If the price adjustment was created by the promotion engine, this value is always false.  
    Example: `true`.
*   `price` (_number (double)_) The adjustment price. It is read only.  
    Example: `120.88`.
*   `priceAdjustmentId` (_object_) The price adjustment ID. It is read only.
    
    Includes all fields of `PriceAdjustmentId`.
    
*   `promotionId` (_string_) The ID of the related promotion. Custom price adjustments can be assigned any promotion ID so long it is not used by a price adjustment belonging to the same item, and is not used by a promotion defined in the promotion engine. If not specified, a promotion ID is generated.
*   `reasonCode` (_string_) The reason for the price adjustment.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderPaymentInstrument

Document representing an order payment instrument.

*   `amount` (_number (double)_) The payment transaction amount.  
    Example: `130.88`.
*   `authorizationStatus` (_object_) The authorization status of the payment transaction. It is read only.
    
    Includes all fields of `Status`.
    
*   `bankRoutingNumber` (_string_) The bank routing number.  
    Maximum length: 256. Example: `12030000`.
*   `fraudDecisions` (_object_) The normalized fraud decisions for the order payment instrument. It is read only. Omitted when no decisions are returned.
    
    Includes all fields of `FraudDecisions`.
    
*   `maskedGiftCertificateCode` (_string_) The gift certificate code with the last 4 characters not masked.  
    Example: `******Gzzy`.
*   `paymentCard` (_object_) The payment card.
    
    Includes all fields of `PaymentCard`.
    
*   `paymentDetails` (_object_) The normalized, shopper-relevant payment details for the order payment instrument. It is read only. Omitted when no details are available for the payment.
    
    Includes all fields of `PaymentDetails`.
    
*   `giftCard` (_object_) The gift card.
    
    Includes all fields of `GiftCardResponse`.
    
*   `paymentInstrumentId` (_object_) The payment instrument ID. It is read only.
    
    Includes all fields of `PaymentInstrumentId`.
    
*   `paymentMethodId` (_string_) The payment method ID. It is read only.  
    Maximum length: 256. Example: `CREDIT_CARD`.
*   `paymentReference` (_object_) Payment reference information for various payment service providers, only when Salesforce Payments is enabled.
    *   `paymentReferenceId` (_string_) Payment reference identifier. Can be payment intent ID for Stripe, PSP reference for Adyen, PayPal order ID for PayPal, or similar identifier for other payment providers.  
        Maximum length: 256. Example: `pi_3N4B2vF0wDjebNCp1234567`.
    *   `gateway` (_string_) The payment gateway used to process the payment.  
        Allowed values: `stripe`, `paypal`, `adyen`. Example: `stripe`.
    *   `gatewayProperties` (_object_) The payment gateway specific properties.
        *   `stripe` (_object_)
            
            ## Stripe specific properties.
            
            *   setupFutureUsage: Indicates that you intend to make future payments with this payment method.
                *   **on\_session**: The payment method is intended to be used for a future payment on the same website session.
                *   **off\_session**: The payment method is intended to be used for a future payment on a different website session.
            *   **null**: The payment method is not intended to be used for a future payment.
            *   clientSecret: Secret for Stripe client-side payment confirmation. Don't store, log, or expose the client secret to anyone other than the customer, and only use it on pages where TLS is enabled.
                *   type: string
                *   maxLength: 256
                *   example: "pi\_1J4K5L2eZvKYlo2CyZ8K5L6M\_secret\_abc123"
        *   `paypal` (_object_)
            
            ## PayPal specific properties.
            
        *   `adyen` (_object_)
            
            ## Adyen specific properties.
            
            *   adyenError: Error information returned by Adyen if the payment fails. Null on success.
            *   adyenPaymentIntent: The Adyen payment intent object containing payment details and required actions.
                *   resultCode: The result of the payment request (for example, "REDIRECT\_SHOPPER", "AUTHORISED", "PENDING", "REFUSED").
                *   accountID: The Adyen merchant account ID.
                *   adyenPaymentIntentAction: The action object for payment methods requiring additional shopper interaction.
                    *   url: The URL for completing the payment (redirect or 3DS authentication).
                    *   type: The action type (for example, "redirect", "threeDS2", "voucher").
                    *   method: The HTTP method for the action (for example, "GET", "POST").
            *   successful: A boolean indicating whether the Adyen operation is successful.

### BasketProductItem

Document representing a basket product item.

Includes all fields of `ProductItem`.

### Shipment

Document representing a shipment.

*   `adjustedMerchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, including item-level price adjustments but not including service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `4.95`.
*   `adjustedShippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `deliveryWindow` (_object_) The estimated delivery window for the shipment. The sfcc.app.shipping.calculate hook populates this value from the selected shipping method. The response omits this field if the hook doesn't return a delivery window. This field is reserved for future use and will be supported in an upcoming release.
    
    Includes all fields of `DeliveryWindow`.
    
*   `gift` (_boolean_) A flag indicating whether the shipment is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `merchandizeTotalTax` (_number (double)_) The total tax on products in the shipment, not including price adjustments or service charges such as shipping. It is read only.  
    Example: `4.95`.
*   `orderCutoffAt` (_string (date-time)_) The timestamp by which an order must be placed for the deliveryWindow to apply, as an RFC 3339 date-time. The sfcc.app.shipping.calculate hook populates this value from the selected shipping method. The response omits this field if the hook doesn't return a cutoff time. This field is reserved for future use and will be supported in an upcoming release.  
    Example: `2026-04-27T14:00:00Z`.
*   `productSubTotal` (_number (double)_) The total price of all products in the shipment, including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `productTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `99`.
*   `shipmentId` (_object_) The order-specific ID of the shipment. The default value is 'me'.  
    Default: `me`.
    
    Includes all fields of `ShipmentId`.
    
    Default: `me`.
    
*   `shipmentNo` (_string_) The shipment number of this shipment. This number is automatically generated. It is read only.
*   `shipmentTotal` (_number (double)_) The total price of all products in the shipment including item-level adjustments, shipping charges, and tax. It is read only.  
    Example: `39.99`.
*   `shippingAddress` (_object_) The shipping address.
    
    Includes all fields of `OrderAddress`.
    
*   `shippingMethod` (_ShippingMethod_)
*   `shippingStatus` (_string_) The shipping status of the shipment.  
    Allowed values: `not_shipped`, `shipped`. Example: `shipped`.
*   `shippingTotal` (_number (double)_) The total price of all shipping charges in the shipment, including shipping adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `5.99`.
*   `shippingTotalTax` (_number (double)_) The total tax on shipping charges in the shipment, not including shipping price adjustments. It is read only.  
    Example: `0.3`.
*   `taxTotal` (_number (double)_) The total tax on the shipment, including item-level price adjustments and service charges such as shipping. If the Discount Taxation preference is set to Tax Products and Shipping Only Based on Adjusted Price, this amount also includes prorated order-level price adjustments. It is read only.  
    Example: `1.8`.
*   `trackingNumber` (_string_) The tracking number of the shipment.  
    Example: `1Z204E380338943508`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ShippingItem

Document representing a shipping item.

*   `adjustedTax` (_number (double)_) The tax for the shipping item, including price adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the shipping item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `itemId` (_string_) The shipping item ID. Use it to identify this shipping item when updating its quantity or creating a custom price adjustment for it. It is read only.  
    Example: `430ef5aad3a24de59378458434`.
*   `itemText` (_string_) The text describing the shipping item.  
    Example: `Shipping`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the shipping item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.
*   `shipmentId` (_object_) The identifier of the shipment to which this item belongs.
    
    Includes all fields of `ShipmentId`.
    
*   `tax` (_number (double)_) The tax on the product item, not including adjustments. It is read only.  
    Example: `0.19`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this shipping item. It is read only.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxItems` (_array of TaxItem_) The individual tax items for this shipping line item (e.g. state tax, county tax). It is read only.  
    Maximum items: 10.
*   `taxRate` (_number (double)_) The tax rate applicable to this product line item. For a 10% tax rate, the value is 0.1. It is read only.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ApproachingDiscount

Document representing an approaching discount for a basket. Contains information about promotions the customer is close to qualifying for.

*   `type` (_string_, required) The type of approaching discount (order-level or shipping-level).  
    Allowed values: `order`, `shipping`. Example: `order`.
*   `conditionThreshold` (_number (double)_) The total amount needed to receive the discount.  
    Example: `100`.
*   `merchandiseTotal` (_number (double)_) The amount the customer basket contributes towards the purchase condition.  
    Example: `90`.
*   `discount` (_object_) The applied discount when the order meets the threshold.
    
    Includes all fields of `Discount`.
    
*   `promotionLink` (_object_) Document representing a promotion link.
    
    Includes all fields of `PromotionLink`.
    
*   `shipmentId` (_string_) The unique id of the shipment the discount relates to. Only applicable when type = shipping.  
    Minimum length: 1. Maximum length: 256. Example: `me`.
*   `shippingMethods` (_array of ShippingMethod_) The shipping methods the promotion relates to. Only applicable when type = shipping.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OrderProductItem

Document representing an order product item.

Includes all fields of `ProductItem`.

*   `omsData` (_object_) Product information retrieved from Order Management (OMS). Only available in the context of an order.
    
    Includes all fields of `OmsProductData`.
    

### OmsData

Additional information retrieved from Order Management (OMS) See [https://developer.salesforce.com/docs/atlas.en-us.order\_management\_developer\_guide.meta/order\_management\_developer\_guide/sforce\_api\_objects\_ordersummary.htm](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/sforce_api_objects_ordersummary.htm) for more information.

*   `status` (_string_) Current status of the order  
    Example: `shipped`.
*   `shipments` (_array of OmsShipment_) List of shipments associated with the order

### OmsReasonCode

A single reason code configured in Order Management (OMS).

*   `reason` (_string_, required) The reason value as configured in OMS.  
    Maximum length: 256. Example: `Defect`.
*   `default` (_boolean_, required) Whether this reason is the default that the server uses when no reason is supplied on a cancel or return request.  
    Example: `false`.

### OrderAccessCode

A time-limited access code that serves as an alternative access grant for guest shoppers who have lost their original session. The code is generated by calling the `requestOrderAccessCode` endpoint, which delivers it via email to the address on the order. The shopper provides this code to authorize the request. The code is valid for 15 minutes after generation.

Type: `string`.

Maximum length: 6. Pattern: ^\\d{6}$. Example: `847291`.

### OmsReturnProductItem

An individual product item to be returned as part of an `OmsReturnOrderRequest`.

*   `itemId` (_string_, required) The identifier of the product item on the order to be returned.  
    Maximum length: 256. Example: `10uVF0000003W0BYAU`.
*   `quantity` (_number (double)_, required) The quantity to be returned. Can't exceed the `quantityAvailableToReturn` of the product item on the order.  
    Minimum: 0. Example: `1`.
*   `reason` (_string_) The reason for returning this product item. The value must match one of the `returnReasonCodes` configured in OMS and returned by the `getOmsMetaData` endpoint. When omitted, the server applies the default reason code configured in OMS.  
    Maximum length: 256. Example: `Defect`.
*   `reasonText` (_string_) A free-text note that explains why the shopper is returning this product item. Use it to provide additional detail beyond the coded `reason`, such as the shopper's own explanation.  
    Maximum length: 255. Example: `The item arrived with a cracked screen and won't power on.`.

### OrderPaymentCardRequest

Document representing an order payment card request.

*   `cardType` (_string_) The payment card type (for example: Visa).  
    Maximum length: 256. Example: `Visa`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store.  
    Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number.  
    Maximum length: 25. Pattern: ^\[0-9 -\]{0,7}\\D{6,15}\\d{0,4}$. Example: `*********4422`.
*   `validFromMonth` (_integer (int32)_) The month the payment card is valid from.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year the payment card is valid from.  
    Example: `2019`.

### GiftCardRequest

Represents gift card details for a request.

*   `brand` (_string_, required) The gift card type or brand (for example, givex, blackhawk).  
    Maximum length: 256. Example: `givex`.
*   `cardNumber` (_string_, required) The gift card number.  
    Maximum length: 40. Example: `6364530000000000`.
*   `cvc` (_string_, required) The card verification code (CVC/CVV) for the gift card.  
    Maximum length: 4. Example: `123`.
*   `expirationMonth` (_integer (int32)_) The month when the gift card expires.  
    Example: `1`.
*   `expirationYear` (_integer (int32)_) The year when the gift card expires.  
    Example: `2030`.

### PaymentReferenceRequest

Properties for Payments Reference Request

*   `paymentMethodType` (_string_) Payment Method Type  
    Maximum length: 64. Example: `card`.
*   `zoneId` (_string_) The unique identifier for a Payments zone.  
    Minimum length: 1. Maximum length: 100. Pattern: ^\[a-zA-Z0-9\\-\_\]{1,100}$.
    
    _Example_
    
    ```
    {
      "Amer-Zone": null
    }
    ```
    
*   `gateway` (_string_) The payment gateway used to process the payment.  
    Allowed values: `stripe`, `paypal`, `adyen`. Example: `stripe`.
*   `gatewayProperties` (_object_) The payment gateway specific properties.
    *   `stripe` (_object_)
        
        ## Stripe specific properties.
        
        *   setupFutureUsage: Indicates that you intend to make future payments with this payment method.
            *   **on\_session**: The payment method is intended to be used for a future payment on the same website session.
            *   **off\_session**: The payment method is intended to be used for a future payment on a different website session.
            *   **null**: The payment method is not intended to be used for a future payment.
    *   `paypal` (_object_)
        
        ## PayPal specific properties.
        
        *   shippingPreference: Shipping preference for PayPal payment processing. Applicable only for basket payment instruments.
            *   **GET\_FROM\_FILE**
            *   **NO\_SHIPPING**
            *   **SET\_PROVIDED\_ADDRESS**
    *   `adyen` (_object_)
        
        ## Adyen specific properties.
        

### PaymentMethod

Document representing a payment method.

*   `cards` (_array of PaymentCardSpec_) The sorted array of payment cards (included only when the system payment method is CREDIT\_CARD). It is read only.
*   `description` (_string_) The localized description of the payment method or card. It is read only.
*   `id` (_string_, required) The ID of the payment method or card. It is read only.  
    Maximum length: 256.
*   `image` (_string_) The URL to the image that represents the payment method or card. It is read only.
*   `name` (_string_) The localized name of the payment method or card. It is read only.
*   `paymentProcessorId` (_string_) The payment processor ID. It is read only. It is read only.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### TaxItems

Taxation for a line item.

*   `taxItems` (_array of TaxItem_) The list of tax items. It is read only.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### ProductDetailsLink

Document representing a link to the resource for product details.

*   `productDescription` (_string_) The description of the product.  
    Example: `Nintendo DS revolutionizes handheld gameplay.`.
*   `productId` (_ProductId_, required)
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `title` (_string_) The link title.  
    Example: `Nintendo DS Game Console`.

### CouponItemId

The coupon item ID

Type: `string`.

Minimum length: 1. Example: `d4c9c0141e9c74c150225580f3`.

### GiftCertificateItemId

Type: `string`.

Minimum length: 1. Example: `629dea6e7b61e58da629b57b21`.

### Discount

Document representing a discount.

*   `amount` (_number (double)_) The discount amount for discount types that define specific discount amounts. It is read only.  
    Example: `130.88`.
*   `percentage` (_number (double)_) The discount percent for discount types that define percentage discounts. It is read only.  
    Example: `0.19`.
*   `priceBookId` (_string_) The price book ID that is used with some types. It is read only.  
    Example: `usd-sale-prices`.
*   `type` (_string_, required) The type of discount. It is read only.  
    Allowed values: `percentage`, `fixed_price`, `amount`, `free`, `price_book_price`, `bonus`, `total_fixed_price`, `bonus_choice`, `percentage_off_options`. Example: `fixed_price`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PriceAdjustmentId

Type: `string`.

Example: `ba248424e3eee797f062161f8b`.

### Status

Document representing an object status.

*   `code` (_string_) The status code.
*   `message` (_string_) The status message.
*   `status` (_integer (int32)_) The status. For more information on the status values see Status.OK and Status.ERROR.

### FraudDecisions

Normalized fraud decisions for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no decisions are returned. The values remain readable for historical orders.

*   `preAuthorization` (_string_)
    
    The pre-authorization fraud decision used by the client to orchestrate checkout. Expected values are:
    
    *   `NOT_REVIEWED`: the payment instrument was not reviewed pre-authorization.
    *   `APPROVED`: the payment authorization can proceed.
    *   `CHALLENGE`: the payment authorization should be challenged with additional verification (for example, a 3D Secure challenge) before it can proceed.
    *   `DECLINED`: the payment authorization is declined.
    
    A custom value may also be returned. It is read only.
    
      
    Maximum length: 256. Example: `APPROVED`.

### PaymentCard

Document representing a payment card.

*   `cardType` (_string_) The payment card type.  
    Maximum length: 256. Example: `Visa`.
*   `creditCardExpired` (_boolean_) A flag indicating if the credit card is expired. It is read only.  
    Example: `true`.
*   `creditCardToken` (_string_) A credit card token. If a credit card is tokenized, the token can be used to look up the credit card data in the token store.  
    Example: `E67TY8GQ27X`.
*   `expirationMonth` (_integer (int32)_) The month when the payment card expires.  
    Example: `3`.
*   `expirationYear` (_integer (int32)_) The year when the payment card expires.  
    Example: `2025`.
*   `holder` (_string_) The payment card holder.  
    Maximum length: 256. Example: `Max Mustermann`.
*   `issueNumber` (_string_) The payment card issue number.  
    Maximum length: 256. Example: `2`.
*   `maskedNumber` (_string_) The masked payment card number.  
    Maximum length: 4000. Example: `*********4422`.
*   `numberLastDigits` (_string_) The last digits of the payment card number. It is read only.  
    Maximum length: 4000. Example: `4422`.
*   `validFromMonth` (_integer (int32)_) The month the payment card is valid from.  
    Minimum: 1. Maximum: 12. Example: `5`.
*   `validFromYear` (_integer (int32)_) The year the payment card is valid from.  
    Example: `2015`.

### PaymentDetails

Normalized, shopper-relevant payment details for the order payment instrument. All properties are optional and read only. The object is omitted entirely when no details are available for the payment. The values remain readable for historical orders.

*   `type` (_string_) The normalized payment method type. Expected values are `bancontact`, `card`, `gift_card`, `eps`, `ideal`, `klarna`, `sepa_debit`, `paypal`, `venmo`, `afterpay_clearpay`, `amazon_pay`, and `twint`. A custom value may also be returned. It is read only.  
    Maximum length: 256. Example: `card`.
*   `brand` (_string_) The normalized card brand. Expected values are `amex`, `diners`, `discover`, `jcb`, `mastercard`, `unionpay`, `visa`, and `unknown`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `visa`.
*   `last4` (_string_) The last four digits of the payment instrument. It is read only.  
    Maximum length: 4. Example: `4242`.
*   `walletType` (_string_) The normalized digital wallet used for the payment. Expected values are `apple_pay` and `google_pay`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `apple_pay`.
*   `expirationMonth` (_integer (int32)_) The month when the payment instrument expires. It is read only.  
    Minimum: 1. Maximum: 12. Example: `12`.
*   `expirationYear` (_integer (int32)_) The year when the payment instrument expires. It is read only.  
    Example: `2028`.
*   `token` (_string_) The reference token representing the payment instrument. This is an opaque identifier, not the card number (PAN). It is read only.  
    Maximum length: 40. Example: `pm_abc123`.
*   `tokenType` (_string_) The type of token backing the reference token. Expected values are `NETWORK` and `GATEWAY`. A custom value may also be returned. It is read only.  
    Maximum length: 20. Example: `GATEWAY`.
*   `accountHolderName` (_string_) The name of the payment instrument account holder. It is read only.  
    Maximum length: 256. Example: `Alex Shopper`.

### GiftCardResponse

Document representing a gift card response.

*   `brand` (_string_) The gift card brand.  
    Maximum length: 256. Example: `givex`.
*   `maskedCardNumber` (_string_) The masked gift card number.  
    Maximum length: 40. Example: `*********4422`.
*   `expirationMonth` (_integer (int32)_) The month when the gift card expires.  
    Example: `1`.
*   `expirationYear` (_integer (int32)_) The year when the gift card expires.  
    Example: `2030`.

### ProductItem

Document representing a product item.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `130`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus.  
    Example: `true`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `true`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.
*   `optionItems` (_array of OptionItem_) The option items.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the line item is based on net pricing then the net price is returned. If the line item is based on gross pricing then the gross price is returned. It is read only.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `20.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `15.5`.
*   `productId` (_string_) The ID of the product.  
    Maximum length: 100. Example: `nintendo-ds-console`.
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `qualifyingProductItemId` (_string_) Returns the id of the ProductLineItem that qualified the basket for this bonus product. This method is only applicable if the product line item is a bonus product line item, and if the promotion is a product promotion with number of qualifying products granting a bonus-product discount. If these conditions aren't met, the method returns null. If there are multiple product line items that triggered this bonus product, this method returns the last one by position within the order.  
    Maximum length: 28.
*   `quantity` (_number (double)_) The quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax for the product item, not including price adjustments. It is read only.  
    Example: `0.3`.
*   `taxBasis` (_number (double)_) The price used to calculate the tax for this product item. It is read only.  
    Example: `30`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxItems` (_array of TaxItem_) The individual tax items for this product line item (e.g. state tax, county tax). It is read only.  
    Maximum items: 10.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.9`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### DeliveryWindow

The range describing when an item is expected to be delivered. Both bounds are RFC 3339 date-time timestamps. The API preserves sub-day precision end-to-end.

*   `startAt` (_string (date-time)_) The earliest expected delivery time, as an RFC 3339 date-time.  
    Example: `2026-04-30T14:00:00Z`.
*   `endAt` (_string (date-time)_) The latest expected delivery time, as an RFC 3339 date-time.  
    Example: `2026-04-30T18:00:00Z`.

### ShipmentId

The identifier of the shipment

Type: `string`.

Minimum length: 1. Example: `me`.

### ShippingMethod

Document representing a shipping method.

*   `deliveryWindow` (_object_) The estimated delivery window for this shipping method. The sfcc.app.shipping.quote hook populates this value. The response omits this field if the hook doesn't return a delivery window.
    
    Includes all fields of `DeliveryWindow`.
    
*   `description` (_string_) The localized description of the shipping method.  
    Example: `Order received within 7-10 business days`.
*   `externalShippingMethod` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method ID.  
    Maximum length: 256. Example: `001`.
*   `name` (_string_) The localized name of the shipping method.  
    Example: `Ground`.
*   `orderCutoffAt` (_string (date-time)_) The timestamp by which an order must be placed for the deliveryWindow to apply, as an RFC 3339 date-time. The sfcc.app.shipping.quote hook populates this value. The response omits this field if the hook doesn't return a cutoff time.  
    Example: `2026-04-27T14:00:00Z`.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs, product level fix, and surcharge costs. It is read only.  
    Example: `15`.
*   `shippingPromotions` (_array of ShippingPromotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### TaxItem

Object representing the taxation.

*   `id` (_string_, required) The taxation identifier.
*   `rate` (_number (double)_, required) The taxation rate.  
    Example: `0.13`.
*   `value` (_number (double)_) The tax amount. Will be computed if not set.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PromotionLink

Document representing a promotion link.

*   `promotionId` (_string_) The unique id of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10off100`.
*   `name` (_string_) The localized name of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `10% off $100 orders`.
*   `calloutMsg` (_string_) The localized call-out message of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `Spend $10 more to save 10%!`.
*   `title` (_string_) The link title.  
    Minimum length: 1. Maximum length: 256. Example: `10% off $100 orders`.
*   `link` (_string_) The URL addressing the promotion.  
    Minimum length: 1. Maximum length: 2048. Example: `/s/SiteGenesis/promotion?id=10off100`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OmsProductData

Additional information retrieved from Order Management (OMS) See [https://developer.salesforce.com/docs/atlas.en-us.order\_management\_developer\_guide.meta/order\_management\_developer\_guide/sforce\_api\_objects\_orderitemsummary.htm](https://developer.salesforce.com/docs/atlas.en-us.order_management_developer_guide.meta/order_management_developer_guide/sforce_api_objects_orderitemsummary.htm) for more information. Only available in context of an order.

*   `status` (_string_) Order Management (OMS) status  
    Allowed values: `ordered`, `returned`, `canceled`, `paid`, `reshipped`, `fulfilled`, `partially_fulfilled`, `allocated`, `partially_allocated`, `return_initiated`. Example: `ordered`.
*   `quantityAvailableToCancel` (_number (double)_) The quantity that can be cancelled.  
    Example: `2`.
*   `quantityAvailableToReturn` (_number (double)_) The quantity that can be returned.  
    Example: `2`.
*   `quantityCanceled` (_number (double)_) The quantity that has been cancelled.  
    Example: `0`.
*   `quantityReturnInitiated` (_number (double)_) The quantity for which a return has been initiated.  
    Example: `0`.
*   `quantityReturned` (_number (double)_) The quantity that has been returned.  
    Example: `0`.
*   `quantityOrdered` (_number (double)_) The quantity that was originally ordered.  
    Example: `2`.

_Example_

```
{
  "status": "ordered",
  "quantityAvailableToCancel": 2,
  "quantityAvailableToReturn": 2,
  "quantityCanceled": 0,
  "quantityReturnInitiated": 0,
  "quantityReturned": 0,
  "quantityOrdered": 2
}
```

### OmsShipment

Shipment information from Salesforce Order Management created during fulfillment process. See [https://developer.salesforce.com/docs/atlas.en-us.230.0.order\_management\_developer\_guide.meta/order\_management\_developer\_guide/sforce\_api\_objects\_fulfillmentorder.htm](https://developer.salesforce.com/docs/atlas.en-us.230.0.order_management_developer_guide.meta/order_management_developer_guide/sforce_api_objects_fulfillmentorder.htm) for more information.

*   `id` (_string_) Unique identifier for the shipment  
    Example: `0OBVF000000003F4AQ`.
*   `status` (_string_) Current status of the shipment  
    Example: `shipped`.
*   `provider` (_string_) Shipping provider name  
    Example: `UPS`.
*   `trackingNumber` (_string_) Tracking number for the shipment  
    Example: `123456789`.
*   `trackingUrl` (_string_) URL to track the shipment  
    Example: `https://www.ups.com/track?loc=en_US&tracknum=123456789`.
*   `expectedDeliveryDate` (_string (date-time)_) Expected delivery date and time  
    Example: `2025-11-12T20:00:00.000+0000`.
*   `actualDeliveryDate` (_string (date-time)_) Actual delivery date and time (null if not yet delivered)  
    Example: `2025-11-12T20:00:00.000+0000`.
*   `shipmentItems` (_array of OmsShipmentItem_) Items included in this shipment

### PaymentCardSpec

Document representing the specification for a payment card.

*   `cardType` (_string_) The payment card type. It is read only.  
    Example: `Visa`.
*   `checksumVerificationEnabled` (_boolean_) A flag indicating whether the card number is verified using the Luhn checksum algorithm. It is read only.  
    Example: `true`.
*   `description` (_string_) The localized description of the payment card. It is read only.
*   `image` (_string_) The URL to the image that represents the payment card. It is read only.
*   `name` (_string_) The localized name of the payment card. It is read only.
*   `numberLengths` (_array of string_) The sorted list of number lengths (individual lengths as well as length ranges). It is read only.
*   `numberPrefixes` (_array of string_) The sorted list of number prefixes (individual prefixes as well as prefix ranges). It is read only.
*   `securityCodeLength` (_integer (int32)_) The length of the security code for this card. It is read only.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### ItemId

The item id.

Type: `string`.

Example: `430ef5aad3a24de59378458434`.

### OptionItem

An option item represents an optional purchase related to a product item, and is always associated with that parent product item. An option item can have different values from which to select. For example, a refrigerator item can have an option item representing an extended warranty, with a set of option item values representing different warranty lengths. When a shopper purchases the warranty option item together with the parent refrigerator item, they select one of the available warranty option item values.

*   `adjustedTax` (_number (double)_) The tax on the line item, including any adjustments. It is read only.  
    Example: `19`.
*   `basePrice` (_number (double)_) The base price of the line item, which is the unit price not including adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50`.
*   `bonusDiscountLineItemId` (_string_) The ID of the bonus discount line item this bonus product relates to. It is read only.  
    Example: `ba248414e3eee797f062162f8b`.
*   `bonusProductLineItem` (_boolean_) A flag indicating whether the product item is a bonus. It is read only.  
    Example: `false`.
*   `bundledProductItems` (_array of ProductItem_) The bundled product items.
*   `gift` (_boolean_) Returns true if the item is a gift. It is read only.  
    Example: `false`.
*   `giftMessage` (_string_) The gift message.  
    Example: `Happy Birthday`.
*   `inventoryId` (_string_) The inventory list ID associated with this item. It is read only.  
    Maximum length: 256. Example: `inventory`.
*   `itemId` (_object_) The product item ID. Use it to identify this item when updating its quantity or creating a custom price adjustment for it. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `itemText` (_string_) The text describing the item.  
    Example: `The item text.`.
*   `optionId` (_string_, required) The ID of the option. It is read only.  
    Maximum length: 256. Example: `consoleWarranty`.
*   `optionItems` (_array of OptionItem_) The option items.
*   `optionValueId` (_string_, required) The ID of the option value. It is read only.  
    Maximum length: 256. Example: `000`.
*   `price` (_number (double)_) The price of the line item before applying any adjustments. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `150.99`.
*   `priceAdjustments` (_array of PriceAdjustment_) The price adjustments.
*   `priceAfterItemDiscount` (_number (double)_) The price of the product line item including item-level adjustments, but not including order-level adjustments or shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `50.99`.
*   `priceAfterOrderDiscount` (_number (double)_) The price of the product line item including item-level adjustments and prorated order-level adjustments, but not including shipping charges. If the taxation policy is net, it doesn't include tax. If the taxation policy is gross, it includes tax. It is read only.  
    Example: `40.5`.
*   `productId` (_ProductId_)
*   `productListItem` (_object_) If this product line item was added from a product list, this value is a reference to the corresponding product list item.
    
    Includes all fields of `ProductListItemReference`.
    
*   `productName` (_string_) The name of the product.  
    Example: `Nintendo DS Game Console`.
*   `quantity` (_number (double)_) The ordered quantity of the products represented by this item.  
    Minimum: 0. Example: `1`.
*   `shipmentId` (_string_) The ID of the shipment this item belongs to.  
    Example: `me`.
*   `shippingItemId` (_string_) If the product line item has a related shipping item, this value is its ID. A related shipping item represents a surcharge applied to individual products using a particular shipping method. It is read only.  
    Example: `006490dcc338feeafc71c964bf`.
*   `tax` (_number (double)_) The tax on the line item before applying any adjustments. It is read only.  
    Example: `0`.
*   `taxBasis` (_number (double)_) The amount used to calculate the tax for this item. It is read only.  
    Example: `50`.
*   `taxClassId` (_string_) The tax class ID for the product item, or null if no tax class ID is associated with the product item. It is read only.
*   `taxRate` (_number (double)_) The tax rate, which is the decimal tax rate to be applied to the product represented by this item. It is read only.  
    Example: `0.19`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductListItemReference

Document representing product list item details.

*   `id` (_object_, required) The ID of the product list item. It is read only.
    
    Includes all fields of `ItemId`.
    
*   `priority` (_integer (int32)_) The priority of the product list item.  
    Example: `1`.
*   `productDetailsLink` (_ProductDetailsLink_)
*   `productList` (_object_) A reference to the associated product list. It is read only.
    
    Includes all fields of `ProductListLink`.
    
*   `public` (_boolean_)  
    Example: `false`.
*   `purchasedQuantity` (_number (double)_) The total quantity of this item purchased from the product list.  
    Example: `0`.
*   `quantity` (_number (double)_) The number of products or gift certificates that get shipped when purchasing this product list item.  
    Minimum: 0. Example: `1`.
*   `type` (_string_) Specifies whether the item is a product or a gift certificate.  
    Allowed values: `product`, `gift_certificate`. Example: `product`.

### ShippingPromotion

Document representing a shipping promotion.

*   `calloutMsg` (_string_) The localized callout message of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `promotionId` (_string_) The unique ID of the promotion.  
    Example: `$30FixedShippingAmountAbove150`.
*   `promotionName` (_string_) The localized promotion name.  
    Example: `$30 Fixed Shipping Amount Above 150`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### OmsShipmentItem

Individual item within a shipment

*   `id` (_string_) Unique identifier for the shipment item  
    Example: `0OBVF000006603F4AQ`.
*   `productItemId` (_string_) Reference to the product item in the order  
    Example: `10uVF0000002fGnYAI`.
*   `quantity` (_number (double)_) Quantity of product items with the referenced productItemId in this shipment  
    Example: `2`.

### ProductListLink

Document representing a link to a product list.

*   `description` (_string_) The description of this product list.
*   `name` (_string_) The name of this product list.
*   `public` (_boolean_) A flag indicating whether the owner made this product list available for access by other customers. It is read only.  
    Example: `true`.
*   `title` (_string_) The link title.
*   `type` (_string_) The type of the product list.  
    Allowed values: `wish_list`, `gift_registry`, `shopping_list`, `custom_1`, `custom_2`, `custom_3`. Example: `shopping_list`.

<!-- document id=673df3dccb0adf02b68a36ea141176610b07c5c2a0b393014435dad2b911e4c6 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-payments.md -->

Shopper Payments

# Shopper Payments

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-payments/shopper-payments-oas-v1-public.yaml)

## API Overview

Use the Shopper Payments API to:

*   Retrieve payment configuration information for storefronts when Salesforce Payments is enabled.

The API returns the available payment methods, merchant account details, and payment gateway configurations for a specific payment zone site assignment.

The response includes:

*   Zone ID: The unique identifier for the Payments zone.
*   Payment Method Set Accounts: List of configured payment processor accounts with API keys, vendor information (Stripe, Adyen, PayPal, etc.), and live/test mode indicators.
*   Payment Methods: List of available payment methods with their associated accounts, payment method types, and supported payment modes.

### Authentication & Authorization

The client requesting payment configuration must have access to the `/payment-configuration` resource. The Shopper Payments API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

You must include `sfcc.shopper-baskets-orders`, `sfcc.shopper-baskets-orders.rw`, or `sfcc.shopper-standard` in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get Payment Configuration

Retrieve the available payment methods for a site.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-payments/v1/organizations/{organizationId}/payment-configuration?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Retrieve Payment Configuration

Retrieve payment configuration settings for Stripe, PayPal, and Adyen based on the payment methods enabled in the merchant's payment zone site. This includes API keys, vendor details, and live/test mode status. Specify a zone via `zoneId` or use `currency` and `countryCode` for automatic resolution.

### Related APIs

*   [Shopper Baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) — Build baskets and add payment instruments.

**Version:** 1.7.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/checkout/shopper-payments/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both OCAPI and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-baskets-orders: Scope granting read-access to shopper basket or orders endpoints
    *   Scope sfcc.shopper-baskets-orders.rw: Scope granting read and write access to shopper basket or orders endpoints

## Operations

### GET Get payment configuration

`GET /organizations/{organizationId}/payment-configuration`

Operation ID: `getPaymentConfiguration`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Retrieves the payment configuration for the organization.

**Parameters:**

*   `siteId`: Required. The site identifier for context-specific configuration
*   `currency`: Required. Three-letter currency code (ISO 4217) for payment method configuration
*   `countryCode`: Optional. Two-letter country code (ISO 3166-1 alpha-2) for country-specific payment configuration
*   `amount`: Optional. Transaction amount for payment method configuration
*   `zoneId`: Optional. Payment zone identifier to retrieve zone-specific configuration

**Response Behavior:**

*   Returns payment configuration data when available
*   Returns null values for missing data (e.g., when account not found or payments zone not found)

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `currency` (query, CurrencyCode, required) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `countryCode` (query, CountryCode) The country code (ISO 3166-1 alpha-2) for country-specific payment configuration filtering.
*   `zoneId` (query, ZoneId) The zone identifier for the payment configuration. Optional, if specified will return zone specific payment configuration instead of resolving based on the currency and country.
    
    _Example: ZoneId_
    
    ```
    Amer-Zone
    ```
    
*   `amount` (query, Amount) The transaction amount. Optional. Some gateways, such as Adyen, allow for payment methods to be qualified or disqualified based on the amount of the transaction.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Payment configuration details.
    
    Media type: `application/json`. Schema: `PaymentConfiguration`.
    
    _Example: stripeConfiguration_
    
    ```
    {
      "zoneId": "Amer-Zone",
      "paymentMethodSetAccounts": [
        {
          "accountId": "acct_1RegszI5I22eU0I3",
          "config": {
            "key": "pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV"
          },
          "live": false,
          "vendor": "Stripe"
        }
      ],
      "paymentMethods": [
        {
          "accountId": "acct_1RegszI5I22eU0I3",
          "paymentMethodType": "card",
          "paymentModes": [
            "Multistep"
          ]
        }
      ]
    }
    ```
    
    _Example: stripeAndPaypalConfiguration_
    
    ```
    {
      "zoneId": "Amer-Zone",
      "paymentMethodSetAccounts": [
        {
          "accountId": "acct_1RegszI5I22eU0I3",
          "config": {
            "key": "pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV"
          },
          "live": false,
          "vendor": "Stripe"
        },
        {
          "accountId": "XK92PMVFNRBDG",
          "config": {
            "bnCode": "SalesforceCommerceCloud_PPCP",
            "key": "AYzMrnD7y4Zc5m5QJZTQ4zPKbP8TMn0r7aStK_3hM9gnaykL-VwK5tGQj4g1y93V6UNvC5j_FZSSa6xpR"
          },
          "live": false,
          "vendor": "Paypal"
        }
      ],
      "paymentMethods": [
        {
          "accountId": "acct_1RegszI5I22eU0I3",
          "paymentMethodType": "card",
          "paymentModes": [
            "Multistep"
          ]
        },
        {
          "accountId": "XK92PMVFNRBDG",
          "paymentMethodType": "paypal",
          "paymentModes": [
            "Multistep"
          ]
        }
      ]
    }
    ```
    
    _Example: adyenConfiguration_
    
    ```
    {
      "zoneId": "Amer-Zone",
      "paymentMethodSetAccounts": [
        {
          "accountId": "TestAccount941ECOM",
          "config": {
            "country": "US",
            "key": "test_JE2ML2CMKZHJRL3QWUW4YCE32A3SL3BH",
            "paymentMethods": {
              "paymentMethods": [
                {
                  "brands": [
                    "amex",
                    "cup",
                    "diners",
                    "discover",
                    "mc",
                    "visa"
                  ],
                  "name": "Cards",
                  "type": "scheme"
                }
              ]
            }
          },
          "live": false,
          "vendor": "Adyen"
        }
      ],
      "paymentMethods": [
        {
          "accountId": "TestAccount941ECOM",
          "paymentMethodType": "card",
          "paymentModes": [
            "Multistep"
          ]
        }
      ]
    }
    ```
    
    _Example: noDataFound_
    
    ```
    {
      "zoneId": null,
      "paymentMethodSetAccounts": [],
      "paymentMethods": []
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the site ID is required and must not be null.
    *   the specified currency is invalid (must be ISO 4217) or not supported by the site.
    *   the provided country code is invalid (must be 2 uppercase letters matching ISO 3166-1 alpha-2).
    *   the provided zone ID is invalid (must match pattern \[a-zA-Z0-9-\_\]{1,100}).
    *   the provided amount is invalid (must be non-negative).
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "Decoding of the property with path '$.failedExample.[1].intProperty' failed because the expected type is 'Integer|Decimal' but the actual type was 'String'."
    }
    ```
    
    _Example: InvalidPaymentConfigurationRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-payment-configuration-request",
      "title": "Bad Request",
      "detail": "The payment configuration request field 'countryCode' is invalid.",
      "invalidField": "countryCode"
    }
    ```
    

### POST Check payment instrument balance

`POST /organizations/{organizationId}/payment-instruments/balance`

Operation ID: `getPaymentInstrumentBalance`. Security: ShopperToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-baskets-orders, sfcc.shopper-baskets-orders.rw, sfcc.shopper-standard).

Checks the balance of a payment instrument.

**Parameters:**

*   `siteId`: Required. Specifies the site identifier for context-specific configuration.

**Request Body:**

*   `paymentMethodId`: Required. The payment method ID.
*   `provider`: Required. Identifies the payment provider that handles the balance inquiry.
*   `providerProperties`: Required. Provider-specific balance inquiry properties. Do not include PCI-relevant data, such as a primary account number (PAN), in this object. Use client-side tokenization or encrypted fields when payment-instrument data is required.

**Response Behavior:**

*   Returns the balance amount and currency when the payment instrument is valid.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `PaymentInstrumentBalanceRequest`.

_Example: PaymentInstrumentBalanceRequest_

```
{
  "paymentMethodId": "COMMERCE_APP_GIFT_CARD",
  "provider": "givex",
  "providerProperties": {
    "balanceToken": "provider-issued-short-lived-token"
  }
}
```

#### Responses

*   **200** Payment instrument balance retrieved successfully.
    
    Media type: `application/json`. Schema: `PaymentInstrumentBalanceResponse`.
    
    _Example: PaymentInstrumentBalance_
    
    ```
    {
      "amount": 50,
      "currency": "USD"
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   the provided payment method is invalid or not applicable.
    *   the provider-specific request properties are invalid or missing.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as GET /organizations/{organizationId}/payment-configuration 400 response._
    
    _Example: InvalidPaymentInstrumentBalanceRequest_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The provided payment method is invalid or not applicable."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### ZoneId

The unique identifier for a Payments zone.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `Amer-Zone`.

### Amount

The transaction amount.

Type: `number (double)`.

Minimum: 0. Example: `100`.

### PaymentConfiguration

*   `zoneId` (_string_, nullable) The unique identifier for a Payments zone.  
    Minimum length: 1. Maximum length: 100. Pattern: ^\[a-zA-Z0-9\\-\_\]{1,100}$. Example: `Amer-Zone`.
*   `paymentMethodSetAccounts` (_array of object_, required) List of payment method set accounts
    *   `accountId` (_string_, required) Account identifier  
        Minimum length: 1. Maximum length: 100. Example: `acct_1RegszI5I22eU0I3`.
    *   `config` (_object_) Account configuration
        *   `key` (_string_) API key for the payment processor  
            Maximum length: 200. Example: `pk_test_JsbBx7imKb7n7Xtlb5MH5BNO00ttiURmPV`.
        *   `bnCode` (_string_) Account BN code (optional, null if not a PayPal account)  
            Maximum length: 100. Example: `Example_PPCP`.
        *   `country` (_string_) The country associated with this payment account configuration  
            Maximum length: 256. Example: `US`.
        *   `paymentMethods` (_object_, nullable) Available payment methods from gateway (optional, null if not an Adyen account)
    *   `live` (_boolean_, required) Whether the account is in live mode  
        Example: `false`.
    *   `vendor` (_string_, required) Payment vendor name  
        Example: `Stripe`.
*   `paymentMethods` (_array of object_, required) Configured payment methods
    *   `accountId` (_string_, required) Associated account identifier  
        Minimum length: 1. Example: `acct_1RegszI5I22eU0I3`.
    *   `paymentMethodType` (_string_, required) Type of payment method  
        Example: `card`.
    *   `paymentModes` (_array of string_, required) Supported payment modes  
        Items: Example: `Multistep`.
        
        _Example_
        
        ```
        [
          "Multistep"
        ]
        ```
        

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### PaymentInstrumentBalanceRequest

Request body for checking the balance of a payment instrument.

The payment method ID and provider identify the payment provider. Provider-specific properties are defined and validated by that provider.

*   `paymentMethodId` (_string_, required) The payment method ID.  
    Minimum length: 1. Maximum length: 256. Example: `COMMERCE_APP_GIFT_CARD`.
*   `provider` (_string_, required) Identifies the payment provider that handles the balance inquiry.  
    Minimum length: 1. Maximum length: 256. Example: `givex`.
*   `providerProperties` (_object_, required) Provider-specific balance inquiry properties. Do not include PCI-relevant data, such as a primary account number (PAN), in this object. Use client-side tokenization or encrypted fields when payment-instrument data is required.

### PaymentInstrumentBalanceResponse

Response containing the payment instrument balance information.

*   `amount` (_number_, required) The remaining balance on the payment instrument.  
    Minimum: 0. Example: `50`.
*   `currency` (_object_, required) The three-letter currency code (ISO 4217) of the payment instrument balance.
    
    Includes all fields of `CurrencyCode`.

<!-- document id=de2f51ec74a27a9d46dcfe5dc0b935271ab0ba77a68b739e2ba3d4f6a37226d0 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-products.md -->

Shopper Products

# Shopper Products

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-products/shopper-products-oas-v1-public.yaml)

## API Overview

The Shopper Products API enables you to access product details for products that are online, merchandised to a particular site catalog, and ready to be sold. You can use these product details to merchandise the product on other ecommerce channels. To set up category navigation paths on other commerce apps or storefronts, you can use the Categories API.

### Authentication & Authorization

The client requesting the product information must have access to the Products resource. The Shopper Products API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include the relevant scopes in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html#guest-user) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html#guest-user) in the SLAS guides.

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Request Details

#### Property Selection

This API supports the `select` query parameter for filtering response properties. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html)

#### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### Response Details

#### Personalization

Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)

#### Caching

Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get a Single Product

Retrieve product details by ID. Replace `{access_token}` with a valid SLAS token.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products/25695327M?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Get Multiple Products

Retrieve up to 24 products in a single request:

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/{organizationId}/products?ids=25695327M,25519318M&siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Populate Product Listing Pages

Use the Shopper Product API so that a customer, browsing on a commerce shopping app built using Commerce Cloud APIs, can see a list of products. For example, hydrate a list of products (max 24). The API returns product details including images, prices, promotions, and product availability.

![b2c-commerce-shopper-products-screenshot-1.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-shopper-products-screenshot-1.png)

#### Get Variation Product Details on an Ecommerce Channel

Use the API so that a customer, browsing on a commerce shopping app built using Commerce Cloud APIs, can switch between different variation products. The API returns product details including images, prices, promotions, and available to sell inventory.

![b2c-commerce-shopper-products-screenshot-2.png](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/b2c-commerce-shopper-products-screenshot-2.png)

#### Retrieve Promotion Information

Promotions provide discounts to shoppers when they meet certain purchase requirements.

Promotion information is described in detail in [Promotion Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/promotion-details.html), but the following list provides several key points:

*   Pricing discounts for basket and shipping promotions are NEVER returned by the 'getProduct' or 'getProducts' endpoint.
*   Promotional pricing is ONLY returned for products that are included with non-conditional promotions.
*   Callout messages are ALWAYS returned by the 'getProduct' and 'getProducts' endpoints.

By default, 'getProduct' and 'getProducts' return promotion information for a queried product. Promotion information includes both pricing and callout message information. However, the specific pricing and callout information that is fetched is determined by:

*   Promotion Type
*   Product Type
*   Product Purchase Requirements

Some promotions can be displayed on a Product Data Page (PDP) or Product Listing page (PLP), while other promotions are displayed in the context of a basket, such as an order level promotion: "add the product to your basket to view price information". It is important to understand what is included in the response when designing a PDP or PLP on top of SCAPI to ensure your design aligns with implementable features.

##### Shopper Personalization

The SCAPI response can be personalized using the Shopper Context API or hooks. By setting specific values in the Shopper Context API, you can modify the response of the 'getProduct' or 'getProducts' endpoint based on the shopper's context. For instance, you can offer a 5% discount or free shipping to shoppers using mobile devices.

##### JWA Caching

The response is cached in JWA, which means promotion data contained in the response is also cached based on the TTL (Time to Live) specified in the Business Manager [Feature Switches](https://help.salesforce.com/s/articleView?id=cc.b2c_feature_switches.htm&type=5) configuration. When the shopper context value is updated, a check is conducted to see if the updated shopper context affects the retrieval of product-promotion data. If it does, then the response is fetched from the source and cached in the JWA.

For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

### Resources

#### Product

A full representation of a product or service that is to merchandise. A ready to merchandise product is one that is online, categorized, and published to a channel. The information associated with a product includes, the product name, description, custom and system attributes, variations, price, availability, and images.

#### Category

Categories and subcategories are the structure by which products are organized and grouped in a catalog and on a storefront. Categories can have relationships to other categories. Further, each category can provide context that is inherited by subcategories. For example, a category can have an assigned attribute. A product assigned to that category or any subcategory inherits the categories’s attribute value. Once the product is removed from the category, the attribute value is no longer inherited by the product. You can also use category linking for site hierarchical navigation. For example, inside the Clothing category you may have Men’s, and inside the Men’s category you may have Pants.

Categories are not tags.

### Related APIs

*   [Products (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/products?meta=Summary) — Manage product catalogs, variations, and options.

**Version:** 1.13.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/product/shopper-products/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-products: scope granting read-access to product endpoints
    *   Scope sfcc.shopper-categories: scope granting read-access to category endpoints
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-products: scope granting read-access to product endpoints
    *   Scope sfcc.shopper-categories: scope granting read-access to category endpoints
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-products: scope granting read-access to product endpoints
    *   Scope sfcc.shopper-categories: scope granting read-access to category endpoints

## Operations

### GET Returns product details for multiple products.

`GET /organizations/{organizationId}/products`

Operation ID: `getProducts`. Security: ShopperToken (sfcc.shopper-products, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-products, sfcc.shopper-standard).

Allows access to multiple product details with a single request. Only products that are online and assigned to a site catalog are returned. The maximum number of product IDs that you can request is 24. In addition to product details, the availability, images, price, bundled\_products, set\_products, recommendations, product options, variations, shipping\_methods, and promotions for the products are included, as applicable.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `ids` (query, array of object, required, style: form, explode: false) The IDs of the requested products (comma-separated, max 24 IDs).  
    Maximum items: 100.
    
    _Example_
    
    ```
    apple-ipod-shuffle,apple-ipod-nano
    ```
    
    _Example_
    
    ```
    [
      "apple-ipod-shuffle",
      "apple-ipod-nano"
    ]
    ```
    
*   `inventoryIds` (query, array of object, style: form, explode: false) The optional inventory list IDs, for which the availability should be shown (comma-separated, max 5 inventoryListIDs).  
    Maximum items: 5.
    
    _Example_
    
    ```
    Site1InventoryList,Site2InventoryList,Site3InventoryList,Site4InventoryList,Site5InventoryList
    ```
    
    _Example_
    
    ```
    [
      "Site1InventoryList",
      "Site2InventoryList",
      "Site3InventoryList",
      "Site4InventoryList",
      "Site5InventoryList"
    ]
    ```
    
*   `expand` (query, array of string, style: form, explode: false) All expand parameters except page\_meta\_tags and slug are used for the request when no expand parameter is provided. The value "none" may be used to turn off all expand options. The page\_meta\_tags expand value is optional and available starting from B2C Commerce version 25.2. The availability expand is deprecated. Use the Shopper Availability API instead for better caching performance. The primary\_category expand returns the full breadcrumb path (root to leaf) for each product's primary category. The slug expand populates the slug field on the product. Available starting from B2C Commerce version 26.8.  
    Items: Allowed values: `none`, `availability`, `bundled_products`, `links`, `promotions`, `options`, `images`, `prices`, `variations`, `set_products`, `recommendations`, `shipping_methods`, `page_meta_tags`, `primary_category`, `slug`. Example: `promotions`.
    
    _Example_
    
    ```
    prices,promotions
    ```
    
    _Example_
    
    ```
    [
      "prices",
      "promotions"
    ]
    ```
    
*   `allImages` (query, boolean) The flag that indicates whether to retrieve the whole image model for the requested product.  
    Example: `true`.
*   `imgTypes` (query, string) Filters product images by viewType with optional count limits per type. This parameter requires the images expand parameter. When used, the response includes the imageGroups property filtered by the specified image types. The format is a comma-separated list of image types with optional counts: :,:. If the count is omitted, all images of that type are returned. If specified, the count limits the number of images returned for that type. For example, imgTypes=large:2,small:1 returns up to 2 large images and 1 small image per product in the imageGroups. If imgTypes is used without expand=images, it is ignored and imageGroups aren't included in the response.  
    Maximum length: 50. Example: `large:3,small:1`.
    
    _Example_
    
    ```
    large:3,small:1
    ```
    
*   `perPricebook` (query, boolean) The flag that indicates whether to retrieve the per PriceBook prices and tiered prices (if available) for requested Products. Available end of June, 2021.  
    Example: `true`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `ProductResult`.
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetProductsBadRequestResponseExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "Maximum number of products you can request in one call is 25."
    }
    ```
    
    _Example: MalformedSelectorResponseExample_
    
    ```
    {
      "title": "Malformed Selector",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector",
      "detail": "The property selector '(data.(name, imageGroups.(**))' is malformed.",
      "selector": "(data.(name, imageGroups.(**))"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    

### GET Returns product details for a single product.

`GET /organizations/{organizationId}/products/{id}`

Operation ID: `getProduct`. Security: ShopperToken (sfcc.shopper-products, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-products, sfcc.shopper-standard).

Allows access to product details for a single product ID. Only products that are online and assigned to a site catalog are returned. In addition to product details, the availability, images, price, bundled\_products, set\_products, recommendations, product options, variations, shipping\_methods, and promotions for the products are included, as applicable.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, ProductId, required) The ID of the requested product.
*   `inventoryIds` (query, array of object, style: form, explode: false) The optional inventory list IDs, for which the availability should be shown (comma-separated, max 5 inventoryListIDs).  
    Maximum items: 5.
    
    _Example_
    
    ```
    Site1InventoryList,Site2InventoryList,Site3InventoryList,Site4InventoryList,Site5InventoryList
    ```
    
    _Example_
    
    ```
    [
      "Site1InventoryList",
      "Site2InventoryList",
      "Site3InventoryList",
      "Site4InventoryList",
      "Site5InventoryList"
    ]
    ```
    
*   `expand` (query, array of string, style: form, explode: false) All expand parameters except page\_meta\_tags and slug are used for the request when no expand parameter is provided. The value "none" may be used to turn off all expand options. The page\_meta\_tags expand value is optional and available starting from B2C Commerce version 25.2. The availability expand is deprecated. Use the Shopper Availability API instead for better caching performance. The primary\_category expand returns the full breadcrumb path (root to leaf) for the product's primary category. The slug expand populates the slug field on the product. Available starting from B2C Commerce version 26.8.  
    Items: Allowed values: `none`, `availability`, `bundled_products`, `links`, `promotions`, `options`, `images`, `prices`, `variations`, `set_products`, `recommendations`, `shipping_methods`, `page_meta_tags`, `primary_category`, `slug`. Example: `links`.
    
    _Example_
    
    ```
    prices,promotions
    ```
    
    _Example_
    
    ```
    [
      "prices",
      "promotions"
    ]
    ```
    
*   `allImages` (query, boolean) The flag that indicates whether to retrieve the whole image model for the requested product.  
    Example: `true`.
*   `imgTypes` (query, string) Filters product images by viewType with optional count limits per type. This parameter requires the images expand parameter. When used, the response includes the imageGroups property filtered by the specified image types. The format is a comma-separated list of image types with optional counts: :,:. If the count is omitted, all images of that type are returned. If specified, the count limits the number of images returned for that type. For example, imgTypes=large:2,small:1 returns up to 2 large images and 1 small image per product in the imageGroups. If imgTypes is used without expand=images, it is ignored and imageGroups aren't included in the response.  
    Maximum length: 50. Example: `large:3,small:1`.
    
    _Example_
    
    ```
    large:3,small:1
    ```
    
*   `perPricebook` (query, boolean) The flag that indicates whether to retrieve the per PriceBook prices and tiered prices (if available) for requested Products. Available end of June, 2021.  
    Example: `true`.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `Product`.
    
    _Example: GetProductResponseExample_
    
    ```
    {
      "brand": "Apple",
      "currency": "USD",
      "id": "apple-ipod-shuffle",
      "imageGroups": [
        {
          "images": [
            {
              "alt": "Apple iPod Shuffle, , large",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dwc2cc65b0/images/large/ipod-shuffle-silver.jpg",
              "title": "Apple iPod Shuffle, "
            }
          ],
          "viewType": "large"
        },
        {
          "images": [
            {
              "alt": "Apple iPod Shuffle, , medium",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dw5f36aab1/images/medium/ipod-shuffle-silver.jpg",
              "title": "Apple iPod Shuffle, "
            }
          ],
          "viewType": "medium"
        },
        {
          "images": [
            {
              "alt": "Apple iPod Shuffle, , small",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dw2b078e02/images/small/ipod-shuffle-silver.jpg",
              "title": "Apple iPod Shuffle, "
            }
          ],
          "viewType": "small"
        }
      ],
      "inventory": {
        "ats": 0,
        "backorderable": false,
        "id": "SiteGenesisList",
        "orderable": true,
        "preorderable": false,
        "stockLevel": 999999
      },
      "longDescription": "Supports AAC, protected AAC, MP3, MP3 VBR, Audible, WAV and AIFF for immediate playback of multiple formats.",
      "master": {
        "masterId": "apple-ipod-shuffle",
        "orderable": false,
        "price": 45.99
      },
      "minOrderQuantity": 1,
      "name": "Apple iPod Shuffle",
      "pageDescription": "With the same size circular control pad as the previous model on a much more compact case with a built-in clip, the updated shuffle is ready to rock and easily tags along when you're on the go.",
      "pageKeywords": "Apple, iPod, Shuffle, MP3, Music Player",
      "pageMetaTags": [
        {
          "id": "description",
          "value": "The updated Shuffle features the same-sized circular control pad in a more compact, clip-on case, making it perfect for on-the-go use.",
          "type": "name"
        },
        {
          "id": "robots",
          "value": "index, follow",
          "type": "name"
        },
        {
          "id": "title",
          "value": "Buy the Apple iPod Shuffle for USD 45.99-69.00.",
          "type": "title"
        },
        {
          "id": "og:title",
          "value": "Apple iPod Shuffle",
          "type": "property"
        },
        {
          "id": "product",
          "value": "{\"@context\":\"https://schema.org/\",\"@type\":\"Product\",\"name\":\"Apple iPod Shuffle\",\"sku\":\"apple-ipod-shuffle\",\"offers\":{\"@type\":\"AggregateOffer\",\"priceCurrency\":\"USD\",\"lowPrice\":\"45.99\",\"highPrice\":\"69.00\"}}",
          "type": "jsonld"
        }
      ],
      "pageTitle": "Apple iPod Shuffle",
      "price": 45.99,
      "priceMax": 69,
      "primaryCategoryId": "electronics-digital-media-players",
      "primaryCategory": {
        "id": "electronics-digital-media-players",
        "name": "iPod & MP3 Players",
        "slug": "ipod-mp3-players",
        "parentCategoryTree": [
          {
            "id": "electronics",
            "name": "Electronics",
            "slug": "electronics"
          }
        ]
      },
      "shortDescription": "With the same size circular control pad as the previous model on a much more compact case with a built-in clip, the updated shuffle is ready to rock and easily tags along when you're on the go.",
      "stepQuantity": 1,
      "type": {
        "master": true
      },
      "variants": [
        {
          "orderable": true,
          "price": 45.99,
          "productId": "apple-ipod-shuffle-silver-1g",
          "variationValues": {
            "color": "Silver",
            "memorySize": "1 GB"
          }
        },
        {
          "orderable": true,
          "price": 49,
          "productId": "apple-ipod-shuffle-blue-1g",
          "variationValues": {
            "color": "Blue",
            "memorySize": "1 GB"
          }
        },
        {
          "orderable": true,
          "price": 49,
          "productId": "apple-ipod-shuffle-green-1g",
          "variationValues": {
            "color": "Green",
            "memorySize": "1 GB"
          }
        },
        {
          "orderable": true,
          "price": 49,
          "productId": "apple-ipod-shuffle-red-1g",
          "variationValues": {
            "color": "Red",
            "memorySize": "1 GB"
          }
        },
        {
          "orderable": true,
          "price": 49,
          "productId": "apple-ipod-shuffle-fuscia-1g",
          "variationValues": {
            "color": "Fuscia",
            "memorySize": "1 GB"
          }
        },
        {
          "orderable": true,
          "price": 60,
          "productId": "apple-ipod-shuffle-silver-2g",
          "variationValues": {
            "color": "Silver",
            "memorySize": "2 GB"
          }
        },
        {
          "orderable": true,
          "price": 69,
          "productId": "apple-ipod-shuffle-green-2g",
          "variationValues": {
            "color": "Green",
            "memorySize": "2 GB"
          }
        },
        {
          "orderable": true,
          "price": 60,
          "productId": "apple-ipod-shuffle-red-2g",
          "variationValues": {
            "color": "Red",
            "memorySize": "2 GB"
          }
        },
        {
          "orderable": true,
          "price": 69,
          "productId": "apple-ipod-shuffle-fuscia-2g",
          "variationValues": {
            "color": "Fuscia",
            "memorySize": "2 GB"
          }
        }
      ],
      "variationAttributes": [
        {
          "id": "color",
          "name": "Color",
          "values": [
            {
              "name": "Silver",
              "orderable": false,
              "value": "Silver"
            },
            {
              "name": "Blue",
              "orderable": false,
              "value": "Blue"
            },
            {
              "name": "Green",
              "orderable": false,
              "value": "Green"
            },
            {
              "name": "Red",
              "orderable": false,
              "value": "Red"
            },
            {
              "name": "Fuscia",
              "orderable": false,
              "value": "Fuscia"
            }
          ]
        },
        {
          "id": "memorySize",
          "name": "Memory Size",
          "values": [
            {
              "name": "1 GB",
              "orderable": true,
              "value": "1 GB"
            },
            {
              "name": "2 GB",
              "orderable": true,
              "value": "2 GB"
            }
          ]
        }
      ]
    }
    ```
    
*   **400** Bad Request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example MalformedSelectorResponseExample: same as GET /organizations/{organizationId}/products 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **404** Product Not Found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetProductNotFoundResponseExample_
    
    ```
    {
      "title": "Product Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found",
      "detail": "No product with ID 'pple-ipod-shuffle' for site 'SiteGenesis' could be found.",
      "productId": "pple-ipod-shuffle",
      "siteId": "SiteGenesis"
    }
    ```
    

### GET Returns product image data for a single product.

`GET /organizations/{organizationId}/products/{productId}/images`

Operation ID: `getProductImages`. Security: ShopperToken (sfcc.shopper-products); ShopperClientContextToken (sfcc.shopper-products).

Returns a Product document for the specified product ID, focused on imageGroups and related image fields. Only online products assigned to a site catalog are returned.

Use the following parameters to control image output: imgTypes — Filters which catalog view types to include, with optional per-type image limits. Defaults to all view types with a 200-image cap per type.

allImages — Controls whether the full image model is returned.

variationAttribute — Narrows image selection by variation context. Applies only when allImages is true.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `productId` (path, ProductId, required) The ID of the product whose images to retrieve.
*   `imgTypes` (query, string) Comma-separated list of view types to include in the response, with optional per-type image limits. Each item is either viewType or viewType:count. If omitted, all catalog view types are returned, up to 200 images per view type. If present, only the listed view types are included. The image count defaults to 200 per view type when no limit is specified.  
    Maximum length: 50. Example: `large:3,small:1`.
    
    _Example_
    
    ```
    large:3,small:1
    ```
    
*   `allImages` (query, boolean) When true, returns all variation-specific image groups rather than only the best-matching group for the product's variation attribute values. Default: false.  
    Default: `false`. Example: `false`.
*   `variationAttribute` (query, array of string, style: form, explode: false) Variation attribute values used to filter image groups when allImages=true. Format: \=. This parameter can be repeated for multiple attributes. Example: color=red&variationAttribute=size=L  
    Items: Minimum length: 1. Maximum length: 256. Example: `color=red`.
    
    _Example_
    
    ```
    [
      "color=red"
    ]
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `ProductImages`.
    
    _Example: GetProductImagesResponseExample_
    
    ```
    {
      "id": "apple-ipod-shuffle",
      "imageGroups": [
        {
          "images": [
            {
              "alt": "Apple iPod Shuffle, large",
              "disBaseLink": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dwc2cc65b0/images/large/ipod-shuffle-silver.jpg",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dwc2cc65b0/images/large/ipod-shuffle-silver.jpg",
              "title": "Apple iPod Shuffle"
            },
            {
              "alt": "Apple iPod Shuffle Blue, large",
              "disBaseLink": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dw1a2b3c4d/images/large/ipod-shuffle-blue.jpg",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dw1a2b3c4d/images/large/ipod-shuffle-blue.jpg",
              "title": "Apple iPod Shuffle Blue"
            }
          ],
          "variationAttributes": [
            {
              "id": "color",
              "values": [
                {
                  "value": "Blue"
                }
              ]
            }
          ],
          "viewType": "large"
        },
        {
          "images": [
            {
              "alt": "Apple iPod Shuffle, small",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dw2b078e02/images/small/ipod-shuffle-silver.jpg",
              "title": "Apple iPod Shuffle"
            }
          ],
          "viewType": "small"
        },
        {
          "images": [
            {
              "alt": "Apple iPod Shuffle Silver Swatch",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dw3c089f13/images/swatch/ipod-shuffle-silver-swatch.jpg",
              "title": "Silver"
            },
            {
              "alt": "Apple iPod Shuffle Blue Swatch",
              "link": "https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dw4d090g24/images/swatch/ipod-shuffle-blue-swatch.jpg",
              "title": "Blue"
            }
          ],
          "viewType": "swatch"
        }
      ]
    }
    ```
    
*   **400** Bad Request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetProductImagesBadRequestResponseExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The 'imgTypes' parameter value 'large:abc' is invalid. Counts must be positive integers."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **404** Product Not Found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetProductImagesNotFoundResponseExample_
    
    ```
    {
      "title": "Product Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found",
      "detail": "No product with ID 'unknown-product-id' for site 'SiteGenesis' could be found.",
      "productId": "unknown-product-id",
      "siteId": "SiteGenesis"
    }
    ```
    

#### Extension points

*   `sfcc.product.shopper-products.v1.products.productId.images.beforeGET` (before) Called before retrieving product images.
*   `sfcc.product.shopper-products.v1.products.productId.images.modifyGETResponse` (modifyResponse) Called to modify the product images response.

### GET Returns price details for a single product.

`GET /organizations/{organizationId}/products/{productId}/prices`

Operation ID: `getProductPrices`. Security: ShopperToken (sfcc.shopper-products); ShopperClientContextToken (sfcc.shopper-products).

Returns price details for a single product that is online and assigned to a site catalog. Returns the effective sales price, tiered prices, and per-pricebook prices. Prices are personalized by customer group and pricebook. Responses are not CDN-cached but are eligible for JWA caching with a 15-minute TTL.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `productId` (path, ProductId, required) The ID of the product whose prices to retrieve.
    
    _Example_
    
    ```
    apple-ipod-shuffle
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `PricesResult`.
    
    _Example: GetProductPricesResponseExample_
    
    ```
    {
      "productId": "apple-ipod-shuffle",
      "price": 89.99,
      "priceMax": 99.99,
      "pricePerUnit": 8.99,
      "pricePerUnitMax": 9.99,
      "pricePerUnitUnit": "kg",
      "tieredPrices": [
        {
          "price": 89.99,
          "pricebook": "usd-sale-pricebook",
          "quantity": 1
        },
        {
          "price": 79.99,
          "pricebook": "usd-sale-pricebook",
          "quantity": 10
        },
        {
          "price": 69.99,
          "pricebook": "usd-sale-pricebook",
          "quantity": 50
        }
      ],
      "prices": {
        "usd-sale-pricebook": 89.99,
        "usd-list-pricebook": 99.99
      }
    }
    ```
    
*   **400** Bad Request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetProductPricesBadRequestResponseExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The locale 'xx-INVALID' is not valid."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **404** Product Not Found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetProductPricesNotFoundResponseExample_
    
    ```
    {
      "title": "Product Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found",
      "detail": "No product with ID 'unknown-product' for site 'SiteGenesis' could be found.",
      "productId": "unknown-product",
      "siteId": "SiteGenesis"
    }
    ```
    

#### Extension points

*   `sfcc.product.shopper-products.v1.products.productId.prices.beforeGET` (before) called before retrieving product price details.
*   `sfcc.product.shopper-products.v1.products.productId.prices.modifyGETResponse` (modifyResponse) called to modify the product price details response.

### GET Returns active promotion details for a single product.

`GET /organizations/{organizationId}/products/{productId}/promotions`

Operation ID: `getProductPromotions`. Security: ShopperToken (sfcc.shopper-products); ShopperClientContextToken (sfcc.shopper-products).

Returns active promotion details for a single product that is online and assigned to a site catalog. Active promotions are filtered by customer group, campaign date range, and time slot. Promotions are personalized. Responses are not CDN-cached but are eligible for JWA caching with a 15-minute TTL.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `productId` (path, ProductId, required) The ID of the product whose promotions to retrieve.
    
    _Example_
    
    ```
    apple-ipod-shuffle
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `PromotionsResult`.
    
    _Example: GetProductPromotionsResponseExample_
    
    ```
    {
      "productId": "apple-ipod-shuffle",
      "productPromotions": [
        {
          "promotionId": "20off-electronics",
          "calloutMsg": "Save 20%!",
          "promotionalPrice": 71.99
        },
        {
          "promotionId": "free-shipping-50",
          "calloutMsg": "Free Shipping"
        }
      ]
    }
    ```
    
*   **400** Bad Request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetProductPromotionsBadRequestResponseExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "The locale 'xx-INVALID' is not valid."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **404** Product Not Found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example GetProductPromotionsNotFoundResponseExample: same as GET /organizations/{organizationId}/products/{productId}/prices 404 response._
    

#### Extension points

*   `sfcc.product.shopper-products.v1.products.productId.promotions.beforeGET` (before) called before retrieving product promotion details.
*   `sfcc.product.shopper-products.v1.products.productId.promotions.modifyGETResponse` (modifyResponse) called to modify the product promotions response.

### GET Returns category and subcategory details for one or more categories.

`GET /organizations/{organizationId}/categories`

Operation ID: `getCategories`. Security: ShopperToken (sfcc.shopper-categories, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-categories, sfcc.shopper-standard).

When you use the URL template, the server returns multiple categories (a result object of category documents). You can use this template to obtain up to 50 categories in a single request. You must enclose the list of IDs in parentheses. If a category identifier contains parenthesis or the separator sign, you must URL encode the character.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `ids` (query, array of object, required, style: form, explode: false) The comma separated list of category IDs or slugs (max 50). For each value, if a category exists with that value as its ID, it is returned (ID takes precedence). Otherwise, the value is treated as a slug. If a slug is provided, it must be URL-encoded (for example, `mens%2Fclothing` for the slug `mens/clothing`).  
    Maximum items: 50.
    
    _Example_
    
    ```
    electronics-digital-cameras,electronics-televisions
    ```
    
    _Example_
    
    ```
    [
      "electronics-digital-cameras",
      "electronics-televisions"
    ]
    ```
    
*   `levels` (query, integer (int32)) Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2. Only online subcategories are returned.  
    Allowed values: `0`, `1`, `2`. Minimum: 0. Example: `1`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `CategoryResult`.
    
    _Example: GetCategoriesResponseExample_
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "id": "electronics-digital-cameras",
          "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw3535377d/images/slot/sub_banners/cat-banner-electronics-camera.jpg",
          "name": "Digital Cameras",
          "slug": "digital-cameras",
          "onlineSubCategoriesCount": 0,
          "pageDescription": "Shop the latest digital cameras from all the top brands, makes and models at Salesforce Commerce Cloud.",
          "pageKeywords": "cameras, digital camerasm point and shoot, slr",
          "pageTitle": "Digital Cameras",
          "parentCategoryId": "electronics",
          "parent_category_tree": [
            {
              "id": "electronics",
              "name": "electronics",
              "slug": "electronics"
            }
          ]
        },
        {
          "categories": [
            {
              "id": "electronics-televisions-flat-screen",
              "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dwc3940e75/images/slot/sub_banners/cat-banner-electronics-tv.jpg",
              "name": "Flat Screen",
              "slug": "flat-screen",
              "pageDescription": "Shop all Flat Screen Televisions including the latest in LCD and Plasma technology from all the latest brands, makes and models at Salesforce Commerce Cloud.",
              "pageKeywords": "flat screen, flat screen television, LCD, plasma, HDTV",
              "pageTitle": "LCD & Plasma High Definition Flat Screen Televisions",
              "parentCategoryId": "electronics-televisions",
              "parent_category_tree": [
                {
                  "id": "electronics",
                  "name": "electronics",
                  "slug": "electronics"
                }
              ]
            },
            {
              "id": "electronics-televisions-projection",
              "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dwc3940e75/images/slot/sub_banners/cat-banner-electronics-tv.jpg",
              "name": "Projection",
              "slug": "projection",
              "onlineSubCategoriesCount": 0,
              "pageDescription": "Shop all Projection Televisions from all the latest brands, makes and models at Salesforce Commerce Cloud.",
              "pageKeywords": "projection, projection televisions, HDTV",
              "pageTitle": "Projection High Definition Televisions",
              "parentCategoryId": "electronics-televisions",
              "parent_category_tree": [
                {
                  "id": "electronics",
                  "name": "electronics",
                  "slug": "electronics"
                }
              ]
            }
          ],
          "id": "electronics-televisions",
          "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dwc3940e75/images/slot/sub_banners/cat-banner-electronics-tv.jpg",
          "name": "Televisions",
          "slug": "televisions",
          "onlineSubCategoriesCount": 2,
          "pageDescription": "Shop the latest Televisions including LCD, Plasma, Flat Screens, Projection including all the top brands, makes and models at Salesforce Commerce Cloud.",
          "pageKeywords": "televisions, tvs, LCD, plasma, flat screen, high definition, HDTV, projection",
          "pageTitle": "Televisions Including LCD, Plasma & More in High Definition",
          "parentCategoryId": "electronics",
          "parent_category_tree": [
            {
              "id": "electronics",
              "name": "electronics",
              "slug": "electronics"
            }
          ]
        }
      ],
      "total": 2
    }
    ```
    
*   **400** Bad Request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetCategoriesBadRequestResponseExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "Maximum number of categories you can request in one call is 50."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    

### GET Returns category and subcategory details for a single category.

`GET /organizations/{organizationId}/categories/{id}`

Operation ID: `getCategory`. Security: ShopperToken (sfcc.shopper-categories, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-categories, sfcc.shopper-standard).

When you use the URL template, the server returns a category identified by the ID. By default, the server also returns the first level of subcategories, but you can specify an additional level using the levels parameter.

This endpoint fetches both online and offline categories. For offline categories, only the top-level category is returned, not offline subcategories.

Using a large value for levels can cause performance issues when there is a large and deep category tree.

#### Parameters

*   `id` (path, CategoryId, required) The ID or slug of the requested category. If a category exists with the given value as its ID, it is returned (ID takes precedence). Otherwise, the value is treated as a slug. If a slug is provided, it must be URL-encoded (for example, `mens%2Fclothing` for the slug `mens/clothing`).
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `levels` (query, integer (int32)) Specifies how many levels of nested subcategories you want the server to return. The default value is 1. Valid values are 0, 1, or 2. Only online subcategories are returned.  
    Allowed values: `0`, `1`, `2`. Minimum: 0. Example: `1`.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_dw_dnt` (header, string) Do Not Track header for privacy preferences. Used with endpoints secured with ShopperClientContextToken. If this header is not passed with endpoints secured with ShopperClientContextToken default value of 0 will be used.  
    Allowed values: `0`, `1`. Example: `1`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Success.
    
    Media type: `application/json`. Schema: `Category`.
    
    _Example: GetCategoryResponseExample_
    
    ```
    {
      "categories": [
        {
          "id": "electronics-televisions",
          "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dwc3940e75/images/slot/sub_banners/cat-banner-electronics-tv.jpg",
          "name": "Televisions",
          "slug": "televisions",
          "onlineSubCategoriesCount": 2,
          "pageDescription": "Shop the latest Televisions including LCD, Plasma, Flat Screens, Projection including all the top brands, makes and models at Salesforce Commerce Cloud.",
          "pageKeywords": "televisions, tvs, LCD, plasma, flat screen, high definition, HDTV, projection",
          "pageTitle": "Televisions Including LCD, Plasma & More in High Definition",
          "parentCategoryId": "electronics",
          "parent_category_tree": [
            {
              "id": "electronics",
              "name": "electronics",
              "slug": "electronics"
            }
          ],
          "c_enableCompare": true,
          "c_showInMenu": true,
          "c_slotBannerImage": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw1d6f6411/images/slot/landing/cat-landing-tv.jpg"
        },
        {
          "id": "electronics-digital-cameras",
          "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw3535377d/images/slot/sub_banners/cat-banner-electronics-camera.jpg",
          "name": "Digital Cameras",
          "slug": "digital-cameras",
          "onlineSubCategoriesCount": 0,
          "pageDescription": "Shop the latest digital cameras from all the top brands, makes and models at Salesforce Commerce Cloud.",
          "pageKeywords": "cameras, digital camerasm point and shoot, slr",
          "pageTitle": "Digital Cameras",
          "parentCategoryId": "electronics",
          "parent_category_tree": [
            {
              "id": "electronics",
              "name": "electronics",
              "slug": "electronics"
            }
          ],
          "c_enableCompare": true,
          "c_showInMenu": true,
          "c_slotBannerImage": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw1a543dc7/images/slot/landing/cat-landing-camera.jpg"
        },
        {
          "id": "electronics-digital-media-players",
          "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw7e9353db/images/slot/sub_banners/cat-banner-electronics-mp3.jpg",
          "name": "iPod & MP3 Players",
          "slug": "ipod-mp3-players",
          "onlineSubCategoriesCount": 0,
          "pageDescription": "Shop Digital Media Players including iPods, Creative Zen, Sony & the latest from all the top brands, makes and models at Salesforce Commerce Cloud.",
          "pageKeywords": "mp3, iPods, mp3 players",
          "pageTitle": "iPod & MP3 Digital Media Players",
          "parentCategoryId": "electronics",
          "parent_category_tree": [
            {
              "id": "electronics",
              "name": "electronics",
              "slug": "electronics"
            }
          ],
          "c_enableCompare": true,
          "c_showInMenu": true,
          "c_slotBannerImage": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw9f3d289a/images/slot/landing/cat-landing-mp3.jpg"
        },
        {
          "id": "electronics-gps-units",
          "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw6ea864f2/images/slot/sub_banners/cat-banner-electronics-gps.jpg",
          "name": "GPS Navigation",
          "slug": "gps-navigation",
          "onlineSubCategoriesCount": 0,
          "pageDescription": "Shop the latest in GPS units from Garmin and Tom Tom along with other brands, makes and models at Salesforce Commerce Cloud.",
          "pageKeywords": "gps, gps units, garmin, tom tom",
          "pageTitle": "GPS Units",
          "parentCategoryId": "electronics",
          "parent_category_tree": [
            {
              "id": "electronics",
              "name": "electronics",
              "slug": "electronics"
            }
          ],
          "c_enableCompare": true,
          "c_showInMenu": true,
          "c_slotBannerImage": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dwad4e06f8/images/slot/landing/cat-landing-gps.jpg"
        },
        {
          "id": "electronics-gaming",
          "image": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/default/dw9da58d91/images/slot/sub_banners/cat-banner-electronics.jpg",
          "name": "Gaming",
          "slug": "gaming",
          "onlineSubCategoriesCount": 2,
          "pageDescription": "Shop games and game consoles from Xbox, Xbox360, Playstation 2, Playstation 3, Game Cube, Wii, Playstation Portable and Nintento DS at Salesforce Commerce Cloud.",
          "pageKeywords": "gaming, xbox, xbox360, ps3, ps2, playstaion 3, psp, game cube, wii, nintendo, nintendo ds",
          "pageTitle": "Gaming",
          "parentCategoryId": "electronics",
          "parent_category_tree": [
            {
              "id": "electronics",
              "name": "electronics",
              "slug": "electronics"
            }
          ],
          "c_enableCompare": true,
          "c_showInMenu": true,
          "c_slotBannerImage": "https://example.com/on/demandware.static/-/Sites-storefront-catalog-en/en_US/v1551233475301/images/slot/landing/cat-landing-gaming.jpg"
        }
      ],
      "id": "electronics",
      "name": "Electronics",
      "slug": "electronics",
      "onlineSubCategoriesCount": 5,
      "pageDescription": "Shop Electronics including the latest in televisions, digital cameras, camcorders, mp3, ipod, mobil phones, GPS & gaming at Salesforce Commerce Cloud",
      "pageKeywords": "televisions, digital cameras, camcorders, mp3, ipod, mobil phones, GPS, gaming",
      "pageTitle": "Shop Electronics Including Televisions, Digital Cameras, iPods & More",
      "parentCategoryId": "root",
      "parent_category_tree": [
        {
          "id": "root",
          "name": "root",
          "slug": "root"
        }
      ],
      "c_enableCompare": true,
      "c_headerMenuOrientation": "Vertical",
      "c_showInMenu": true
    }
    ```
    
*   **400** Bad Request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example GetCategoryBadRequestResponseExample: same as GET /organizations/{organizationId}/categories 400 response._
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **404** No online or offline category was found with the specified ID.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GetCategoryNotFoundResponseExample_
    
    ```
    {
      "title": "Category Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/product-not-found",
      "detail": "No category with ID 'electronics-televi' for site 'SiteGenesis' could be found.",
      "productId": "electronics-televi",
      "siteId": "SiteGenesis"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### ProductId

The id (SKU) of the product.

Type: `string`.

Minimum length: 1. Maximum length: 100. Example: `apple-ipod-classic`.

### InventoryId

The inventory ID.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `Site1InventoryList`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### ProductResult

Result document containing an array of products.

*   `limit` (_integer (int32)_, required) The number of returned documents.  
    Example: `12`.
*   `data` (_array of Product_, required) The array of product documents.
*   `total` (_integer (int32)_, required) The total number of documents.  
    Example: `12`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### Product

Any product that is sold, shown alone, and does not have variations such as different sizes or colors. A product has no reliance on any other product for inheritance. _A product has a SKU and can have a product option, which has a different SKU_.

*   `brand` (_string_) The product's brand.  
    Example: `Apple`.
*   `bundledProducts` (_array of BundledProduct_) The array of all bundled products of this product.
*   `currency` (_CurrencyCode_)
*   `ean` (_string_) The European Article Number of the product.  
    Example: `8essdf9w3`.
*   `fetchDate` (_integer (int32)_)  
    Example: `5`.
*   `id` (_ProductId_, required)
*   `imageGroups` (_array of ImageGroup_) The array of product image groups.
*   `inventories` (_array of Inventory_) The array of product inventories explicitly requested via the 'inventory\_ids' query parameter. This property is only returned in context of the 'availability' expansion.
*   `inventory` (_object_) The site default inventory information. This property is only returned in context of the 'availability' expansion.
    
    Includes all fields of `Inventory`.
    
*   `longDescription` (_string_) The localized product's long description.  
    Example: `Awesome long description of product`.
*   `manufacturerName` (_string_) The product's manufacturer name.  
    Example: `Apple`.
*   `manufacturerSku` (_string_) The product's manufacturer SKU.  
    Example: `2ND8834`.
*   `master` (_object_) The master product information, only for types: master, variation group, and variant.
    
    Includes all fields of `Master`.
    
*   `minOrderQuantity` (_number (double)_) The minimum order quantity for this product.  
    Example: `2`.
*   `name` (_string_) The localized product name.  
    Example: `Apple IPod Classic`.
*   `options` (_array of Option_) The array of product options, only for type option. This array can be empty.
*   `pageDescription` (_string_) The localized product's page description.  
    Example: `Really good Product`.
*   `pageKeywords` (_string_) The localized product's page description.  
    Example: `Ipod, Music Player`.
*   `pageTitle` (_string_) The localized product's page title.  
    Example: `Apple IPod Classic`.
*   `pageMetaTags` (_array of PageMetaTag_) Page Meta tags associated with the given product.
*   `price` (_number (double)_) The sales price of the product. In case of complex products, like master or set, this is the minimum price of related child products.  
    Example: `59.99`.
*   `pricePerUnit` (_number (double)_) The price per unit if defined for the product  
    Example: `19.99`.
*   `pricePerUnitMax` (_number (double)_) The max price per unit typically for a master product's variant.  
    Example: `29.99`.
*   `priceMax` (_number (double)_) The maximum sales of related child products in complex products like master or set.  
    Example: `69.99`.
*   `priceRanges` (_array of PriceRange_) Array of one or more price range objects representing one or more Pricebooks in context for the site.
*   `prices` (_object_) The prices map with pricebook IDs and their values.
    
    Additional properties: `number (double)`.
    
*   `primaryCategoryId` (_string_) The ID of the products primary category.  
    Example: `electronics`.
*   `primaryCategory` (_object_) The primary category of the product, including its full ancestor breadcrumb path (root to leaf, root category node excluded). Only present when the primary\_category expand is requested.
    *   `id` (_string_) The ID of the primary category.  
        Minimum length: 1. Maximum length: 256. Example: `electronics-digital-media-players`.
    *   `name` (_string_) The localized name of the primary category.  
        Minimum length: 1. Maximum length: 256. Example: `iPod & MP3 Players`.
    *   `slug` (_string_) SEO path persisted for the primary category. This property is omitted when no category URL mapping exists for the requested locale.  
        Minimum length: 1. Maximum length: 256. Example: `electronics/ipod-mp3-players`.
    *   `parentCategoryTree` (_array of object_) The list of ancestor categories from root to the primary category (root category node excluded).
        *   `id` (_string_) The ID of the ancestor category.  
            Minimum length: 1. Maximum length: 256. Example: `electronics`.
        *   `name` (_string_) The name of the ancestor category.  
            Minimum length: 1. Maximum length: 256. Example: `Electronics`.
        *   `slug` (_string_) SEO path persisted for the primary category. This property is omitted when no category URL mapping exists for the requested locale.  
            Minimum length: 1. Maximum length: 256. Example: `electronics/ipod-mp3-players`.
*   `productLinks` (_array of ProductLink_) The array of source and target product links information.
*   `productPromotions` (_array of ProductPromotion_) An array of active customer product promotions for this product, sorted by promotion priority using SORT\_BY\_EXCLUSIVITY ordering (exclusivity → rank → promotion class → discount type → best discount → ID). This array can be empty. Coupon promotions are not returned in this array. See [PromotionPlan.SORT\_BY\_EXCLUSIVITY](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html?target=class_dw_campaign_PromotionPlan.html) for more details.
*   `recommendations` (_array of Recommendation_) Returns a list of recommendations.
*   `setProducts` (_array of Product_) The array of set products of this product.
*   `shortDescription` (_string_) The localized product short description.  
    Example: `Awesome Product`.
*   `slug` (_string_) The SEO URL slug for the product. Only present when the slug expand is requested and the slug feature is enabled.  
    Maximum length: 256. Example: `modern-dress-shirt/74974310M.html`.
*   `slugUrl` (_string_) The complete link to this product's storefront page.  
    Example: `https://www.example.com/on/store/Sites-MySite/default/Product-Show?pid=MyProduct`.
*   `stepQuantity` (_number (double)_) The steps in which the order amount of the product can be increased.  
    Example: `2`.
*   `tieredPrices` (_array of ProductPriceTable_) The document represents list of tiered prices if the product is a variant
*   `type` (_object_) The product type information. Can be one or more of the following values: item, master, variation\_group, variant, bundle, and set.
    
    Includes all fields of `ProductType`.
    
*   `unit` (_string_) The sales unit of the product.  
    Example: `lbs`.
*   `upc` (_string_) The Universal Product Code (UPC).  
    Example: `JSDU876`.
*   `validFrom` (_string (date-time)_) The time a product is valid from.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `validTo` (_string (date-time)_) The time a product is valid to.  
    Example: `9999-12-31T23:59:59.0Z`.
*   `variants` (_array of Variant_) The array of actual variants. Only for master, variation group, and variant types. This array can be empty.
*   `variationAttributes` (_array of VariationAttribute_) Sorted array of variation attributes information. Only for master, variation group, and variant types. This array can be empty.
*   `variationGroups` (_array of VariationGroup_) The array of actual variation groups. Only for master, variation group, and variant types. This array can be empty.
*   `variationValues` (_object_) The actual variation attribute ID - value pairs. Only for variant and variation group types.
    
    Additional properties: `string`.
    
*   `shippingMethods` (_array of ShippingMethod_) The array of applicable shipping methods for this product. This array can be empty. This property is only returned in context of the 'shipping\_methods' expansion.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductImages

Document containing only the image groups for a product. Contains no price, availability, or other non-image data.

*   `id` (_ProductId_, required)
*   `imageGroups` (_array of ImageGroup_) Array of image groups for this product. Each group corresponds to a view type and optionally to specific variation attribute values.

### PricesResult

Document representing the price details for a single product. Contains only price-related fields; no images, availability, variations, or other product data are included. Price fields are absent when no pricebook is configured for the requested site and locale context — only `productId` is guaranteed in the response.

*   `productId` (_string_, required) The ID of the product.  
    Minimum length: 1. Maximum length: 100. Example: `apple-ipod-shuffle`.
*   `price` (_number (double)_) The effective sales price of the product. For complex products (master, set), this is the minimum price of the related child products.  
    Example: `89.99`.
*   `priceMax` (_number (double)_) The maximum sales price. For complex products (master, set), this is the maximum price of the related child products.  
    Example: `99.99`.
*   `pricePerUnit` (_number (double)_) The price per unit if defined for the product.  
    Example: `8.99`.
*   `pricePerUnitMax` (_number (double)_) The maximum price per unit, typically for a master product's variant.  
    Example: `9.99`.
*   `pricePerUnitUnit` (_string_) The unit of measure for the per-unit price (e.g. "kg", "lb").  
    Minimum length: 1. Maximum length: 256. Example: `kg`.
*   `tieredPrices` (_array of ProductPriceTable_) The list of tiered prices for the product. Each entry represents a price for a given pricebook and minimum order quantity threshold. Uses the effective (lowest) winning price from the merged applicable pricebooks for each quantity tier — matching the SCAPI product endpoint's tieredPrices field.
*   `prices` (_object_) A map of pricebook IDs to their corresponding prices for this product.
    
    Additional properties: `number (double)`.
    
    Example: `89.99`.
    
    _Example_
    
    ```
    {
      "usd-sale-pricebook": 89.99,
      "usd-list-pricebook": 99.99
    }
    ```
    
*   `currency` (_CurrencyCode_)
*   `priceRanges` (_array of ProductPriceRange_) Per-pricebook min/max price ranges. Only present for complex products (master, variation group, product set) that have variants with differing prices.

### PromotionsResult

Document representing the active promotion details for a single product. Contains only promotion-related fields; no price, images, availability, variations, or other product data are included. Active promotions are filtered by customer group, campaign date range, and time slot.

*   `productId` (_string_, required) The ID of the product.  
    Minimum length: 1. Maximum length: 100. Example: `apple-ipod-shuffle`.
*   `productPromotions` (_array of schemas-ProductPromotion_) An array of active customer promotions applicable to this product, sorted by promotion priority using SORT\_BY\_EXCLUSIVITY ordering (exclusivity → rank → promotion class → discount type → best discount → ID). This array can be empty. Coupon promotions are not returned in this array.

### CategoryId

The ID of the category.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `mens`.

### CategoryResult

Result document containing an array of categories.

Includes all fields of `ResultBase`.

*   `data` (_array of Category_, required) The array of category documents.

### Category

Categories allow products to be organized into hierarchical structures. Categories can have relationships to other parent categories. Each category can also provide a context inherited by subcategories. For example, a category may have an attribute value assigned to it, and any product assigned to the category or a subcategory would inherit the attribute value as long as the product is assigned. Once the product is removed from the category those attribute values would no longer be in the context of the product. Linking of categories is also used for Site hierarchical navigation. For example, inside 'Clothing' you may have 'Mens', and inside 'Mens' you may have 'Pants'. Categories are not _Tags._

*   `categories` (_array of Category_) Array of subcategories. Can be empty.
*   `description` (_string_) The localized description of the category.  
    Example: `Category description for Men's Category`.
*   `id` (_CategoryId_, required)
*   `image` (_string_) The URL of the category image.  
    Example: `https://example.com/images/large/mens-category.jpg`.
*   `name` (_string_) The localized name of the category.  
    Example: `Mens`.
*   `onlineSubCategoriesCount` (_integer (int64)_) The total number of online sub-categories. This information will be available from B2C Commerce version 24.5.  
    Example: `20`.
*   `pageDescription` (_string_) The localized page description of the category.  
    Example: `This category ahs all men's clothing`.
*   `pageKeywords` (_string_) The localized page keywords of the category.  
    Example: `Mens, shirts`.
*   `pageTitle` (_string_) The localized page title of the category.  
    Example: `Men's Category`.
*   `parentCategoryId` (_string_) The ID of the parent category.  
    Example: `apparel`.
*   `parentCategoryTree` (_array of PathRecord_) The List of the parent categories.
*   `slug` (_string_) SEO path persisted for the category. This property is omitted when no category URL mapping exists for the requested locale.  
    Minimum length: 1. Maximum length: 256. Example: `mens/cloting`.
*   `thumbnail` (_string_) The URL of the category thumbnail.  
    Example: `https://www.exampleimage.com/images/categoryImage.jpg`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### BundledProduct

A bundle of products that can be bought together (all or nothing). Each product in the bundle can itself be bought independently, but this is outside of the context of the bundle. A bundle is a purchasing convenience. _Product bundle has a SKU and price._

*   `id` (_string_, required)  
    Example: `823476`.
*   `product` (_object_, required) The product being bundled.
    
    Includes all fields of `Product`.
    
*   `quantity` (_number (double)_, required) For the product being bundled, the quantity added to the bundle.  
    Example: `5`.

### ImageGroup

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of Image_, required) The images of the image group.
*   `variationAttributes` (_array of VariationAttribute_) Returns a list of variation attributes applying to this image group.
*   `viewType` (_string_, required) The image view type.  
    Example: `hi-res`.

### Inventory

Document representing inventory information of the current product for a particular inventory list.

*   `ats` (_number (double)_) The Available To Sell (ATS) of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.ats.max\_threshold'.  
    Example: `15`.
*   `backorderable` (_boolean_) A flag indicating whether the product is backorderable.  
    Example: `true`.
*   `id` (_InventoryId_, required)
*   `inStockDate` (_string (date-time)_) A flag indicating the date when the product will be in stock.  
    Example: `9999-12-31T00:00:00.0Z`.
*   `orderable` (_boolean_) A flag indicating whether at least one of the products is available to sell.  
    Example: `true`.
*   `preorderable` (_boolean_) A flag indicating whether the product is preorderable.  
    Example: `false`.
*   `stockLevel` (_number (double)_) The stock level of the product. If it is infinity, the return value is 999999. The value can be overwritten by the OCAPI setting 'product.inventory.stock\_level.max\_threshold'.  
    Example: `10`.

### Master

The master product is a representation of a group of variant products. This is a non-buyable entity, provides inheritable attributes for its product variants, and is used for navigation. _Doesn't have a SKU._

*   `masterId` (_object_, required) The ID (SKU) of the master product.
    
    Includes all fields of `ProductId`.
    
*   `orderable` (_boolean_) A flag indicating whether at least one of the variants can be ordered.  
    Example: `true`.
*   `price` (_object_) The minimum sales price of the related variants.
    
    Includes all fields of `Price`.
    
*   `priceMax` (_object_) The maximum sales price of the related variants.
    
    Includes all fields of `Price`.
    
*   `prices` (_object_) List of sale prices.
    
    Additional properties: `number (double)`.
    

### Option

Product options enable you to sell configurable products that have optional accessories, upgrades, or additional services. Options are always purchased with a product and can't be purchased separately. _Product Option has a SKU and a price associated with it._

*   `description` (_string_) The localized description of the option.  
    Example: `Get this Option`.
*   `id` (_object_, required) The ID of the option.  
    Example: `Warranty`.
    
    Includes all fields of `ProductId`.
    
    Example: `Warranty`.
    
*   `image` (_string_) The URL to the option image.  
    Example: `https://www.exampleimage.com/images/optionImage.jpg`.
*   `name` (_string_) The localized name of the option.  
    Example: `Warranty`.
*   `values` (_array of OptionValue_) The array of option values. This array can be empty.

### PageMetaTag

Document representing a Page Meta Tag object.

*   `id` (_string_) The ID of the Page Meta Tag.  
    Example: `title`.
*   `value` (_string_) Locale-specific value of the Page Meta Tag, evaluated by resolving the rule set for the given Business Manager ID.  
    Example: `Buy the Long Sleeve Covered Placket Blouse for USD 61.99.`.
*   `type` (_string_)
    
    The kind of Page Meta Tag, indicating how the storefront should render the value. Documented values are `name`, `property`, `title`, and `jsonld`:
    
    *   `name` — render as `<meta name="...">`.
    *   `property` — render as `<meta property="...">` (e.g. Open Graph tags).
    *   `title` — render as the HTML `<title>` element.
    *   `jsonld` — JSON-LD structured data, intended for rendering inside `<script type="application/ld+json">`. The field may be absent when the kind cannot be determined. Clients should treat unknown values as opaque so additional kinds can be introduced without breaking the contract.
    
      
    Maximum length: 64. Example: `name`.

### PriceRange

Document representing price ranges for a product which happens to be a master product (per Pricebook)

*   `maxPrice` (_object_) Maximum price for the given pricebook (usually for a master Product would be the price for the Variant which has the highest price out of all Variants in that pricebook)
    
    Includes all fields of `Price`.
    
*   `minPrice` (_object_) Minimum price for the given pricebook (usually for a master Product would be the price for the Variant which has the least price out of all Variants in that pricebook)
    
    Includes all fields of `Price`.
    
*   `pricebook` (_string_) The active pricebook from which the min and the max prices are calculated. The pricebook is based on the site context of the request as defined in ECOM.  
    Example: `usd-list-pricebook`.

### ProductLink

Document representing a link between two products. It contains the ID of the source and target products, the type of product link, and the URLs to retrieve product data.

*   `sourceProductId` (_object_, required) The semantic ID of the product this product link is coming from.  
    Example: `824756924`.
    
    Includes all fields of `ProductId`.
    
    Example: `824756924`.
    
*   `sourceProductLink` (_string_, required) The URL addressing the product this product link is coming from.  
    Example: `Link`.
*   `targetProductId` (_object_, required) The semantic ID of the product this product link is pointing to.  
    Example: `2TR93459`.
    
    Includes all fields of `ProductId`.
    
    Example: `2TR93459`.
    
*   `targetProductLink` (_string_, required) The URL addressing the product this product link is pointing to.  
    Example: `Link`.
*   `type` (_string_, required) The type of product link.  
    Allowed values: `cross_sell`, `replacement`, `up_sell`, `accessory`, `newer_version`, `alt_orderunit`, `spare_part`, `other`. Example: `up_sell`.

### ProductPromotion

Document representing a product promotion.

*   `calloutMsg` (_string_, required) The localized call-out message of the promotion.  
    Example: `Fantastic promotion`.
*   `promotionId` (_string_, required) The unique ID of the promotion.  
    Example: `summerSale`.
*   `promotionalPrice` (_object_, required) The promotional price for this product.
    
    Includes all fields of `Price`.
    

### Recommendation

Document representing a product recommendation.

*   `calloutMsg` (_string_) The localized callout message of the recommendation.  
    Example: `Absolutely recommended`.
*   `image` (_Image_)
*   `longDescription` (_string_) The localized long description of the recommendation.  
    Example: `Really good detailed product description`.
*   `name` (_string_) The localized name of the recommendation.  
    Example: `Apple Ipod Shuffle`.
*   `recommendationType` (_RecommendationType_, required)
*   `recommendedItemId` (_string_) The recommended item ID of the recommendation.  
    Example: `apple-ipod-shuffle`.
*   `shortDescription` (_string_) The localized short description of the recommendation.  
    Example: `Product description`.

### ProductPriceTable

Tiered Price Level Object

*   `price` (_object_) Price for the product for the specified tier for the specified pricebook
    
    Includes all fields of `Price`.
    
*   `pricebook` (_string_) The active pricebook for which this price is defined  
    Example: `usd-list-pricebook`.
*   `quantity` (_number (double)_) Quantity tier for which the price is defined.  
    Example: `1`.

### ProductType

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.  
    Example: `true`.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.  
    Example: `false`.
*   `master` (_boolean_) A flag indicating whether the product is a master.  
    Example: `true`.
*   `option` (_boolean_) A flag indicating whether the product is an option.  
    Example: `false`.
*   `set` (_boolean_) A flag indicating whether the product is a set.  
    Example: `true`.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.  
    Example: `false`.
*   `variationGroup` (_boolean_) A flag indicating whether the product is a variation group.  
    Example: `false`.

### Variant

A product which is a variation within a master product that describes different colors, sizes, or other variation attributes. _Has a SKU._

*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.  
    Example: `true`.
*   `price` (_object_) The sales price of the variant.
    
    Includes all fields of `Price`.
    
*   `productId` (_object_, required) The ID (SKU) of the variant.  
    Example: `8W4756834`.
    
    Includes all fields of `ProductId`.
    
    Example: `8W4756834`.
    
*   `tieredPrices` (_array of ProductPriceTable_) List of tiered prices if the product is a variant
*   `variationValues` (_object_) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    

### VariationAttribute

Document representing a variation attribute.

*   `id` (_string_, required) The ID of the variation attribute.  
    Minimum length: 1. Example: `color`.
*   `name` (_string_) The localized display name of the variation attribute.  
    Example: `Color`.
*   `values` (_array of VariationAttributeValue_) The sorted array of variation values. This array can be empty.

### VariationGroup

Representation of a group of variant products by an attribute. This is a non-buyable entity, provides inheritable attributes for its product variants, and is used for navigation. _Doesn't have a SKU._

*   `orderable` (_boolean_, required) A flag indicating whether the variation group is orderable.  
    Example: `false`.
*   `price` (_object_, required) The sales price of the variation group.
    
    Includes all fields of `Price`.
    
*   `productId` (_object_, required) The ID (SKU) of the variation group.  
    Example: `49345VG`.
    
    Includes all fields of `ProductId`.
    
    Example: `49345VG`.
    
*   `variationValues` (_object_, required) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    

### ShippingMethod

Document representing a shipping method.

*   `description` (_string_) The localized description of the shipping method.  
    Example: `Order received within 7-10 business days`.
*   `externalShippingMethod` (_string_) The external shipping method.
*   `id` (_string_, required) The shipping method ID.  
    Maximum length: 256. Example: `001`.
*   `name` (_string_) The localized name of the shipping method.  
    Example: `Ground`.
*   `price` (_number (double)_) The shipping cost total, including shipment level costs, product level fix, and surcharge costs. It is read only.  
    Example: `15`.
*   `shippingPromotions` (_array of ShippingPromotion_) The array of active customer shipping promotions for this shipping method. This array can be empty.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductPriceRange

Document representing the min/max price range for a single pricebook. Only present for complex products (master, variation group, product set).

*   `pricebook` (_string_) The ID of the pricebook.  
    Minimum length: 1. Maximum length: 256. Example: `usd-sale-pricebook`.
*   `minPrice` (_number (double)_) The minimum price across all variants for this pricebook.  
    Example: `19.99`.
*   `maxPrice` (_number (double)_) The maximum price across all variants for this pricebook.  
    Example: `99.99`.

### schemas-ProductPromotion

Document representing an active promotion applicable to a product.

*   `promotionId` (_string_, required) The unique ID of the promotion.  
    Minimum length: 1. Maximum length: 256. Example: `20off-electronics`.
*   `calloutMsg` (_string_, required) The localized call-out message of the promotion.  
    Minimum length: 1. Maximum length: 4000. Example: `Save 20%!`.
*   `promotionalPrice` (_number (double)_) The promotional price for this product. Only present for PRODUCT class promotions.  
    Example: `71.99`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### PathRecord

Document representing most basic info (id and name) of a category or catalog.

*   `id` (_string_) The id of the category path.  
    Example: `mens`.
*   `name` (_string_) The name of the category path.  
    Example: `mens`.
*   `slug` (_string_) SEO path persisted for the category. This property is omitted when no category URL mapping exists for the requested locale.  
    Minimum length: 1. Maximum length: 256. Example: `mens/cloting`.

### Image

Product image

*   `alt` (_string_) The localized alternative text of the image.  
    Example: `Apple iPod Shuffle, large`.
*   `disBaseLink` (_string_) Base URL for the Dynamic Image Service (DIS) address. This is only shown if the image is stored on the server and DIS is enabled.  
    Example: `https://example.com/images/large/ipod-shuffle-silver.jpg`.
*   `link` (_string_, required) The URL of the actual image.  
    Minimum length: 1. Example: `https://example.com/on/demandware.static/-/Sites-electronics-catalog/default/dwc2/images/large/ipod-shuffle.jpg`.
*   `title` (_string_) The localized title of the image.  
    Example: `Apple iPod Shuffle`.

### Price

Document representing a price for a product

Type: `number (double)`.

Example: `12.99`.

### OptionValue

Document representing an option value.

*   `default` (_boolean_) A flag indicating whether this option value is the default one.  
    Example: `true`.
*   `id` (_object_, required) The ID of the option value.  
    Example: `5YR`.
    
    Includes all fields of `ProductId`.
    
    Example: `5YR`.
    
*   `name` (_string_) The localized name of the option value.  
    Example: `5 Year Warranty`.
*   `price` (_object_) The effective price of the option value.
    
    Includes all fields of `Price`.
    

### RecommendationType

Document representing a recommendation type.

*   `displayValue` (_string_, required) The localized display value of the recommendation type.  
    Example: `UpSell`.
*   `value` (_integer (int32)_, required) The value of the recommendation type.  
    Example: `2`.

### VariationAttributeValue

Document representing a variation attribute value.

*   `description` (_string_) The localized description of the variation value.  
    Example: `Color of the product`.
*   `image` (_object_) The first product image for the configured viewtype and this variation value.
    
    Includes all fields of `Image`.
    
*   `imageSwatch` (_object_) The first product image for the configured viewtype and this variation value (typically the swatch image).
    
    Includes all fields of `Image`.
    
*   `name` (_string_) The localized display name of the variation value.  
    Example: `Red`.
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.  
    Example: `true`.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1. Example: `red`.

### ShippingPromotion

Document representing a shipping promotion.

*   `calloutMsg` (_string_) The localized callout message of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `promotionId` (_string_) The unique ID of the promotion.  
    Example: `$30FixedShippingAmountAbove150`.
*   `promotionName` (_string_) The localized promotion name.  
    Example: `$30 Fixed Shipping Amount Above 150`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=4cfd1bd4b52ad8da97fc29f04e6bd4d75ef0108e7389370ba6cba629911d4df6 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-promotions.md -->

Shopper Promotions

# Shopper Promotions

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-promotions/shopper-promotions-oas-v1-public.yaml)

## API Overview

Retrieve information about active promotions within the context of a shopper and a site. You can use this API to retrieve promotions that you configured in the commerce platform by searching for specific promotion IDs or by searching for promotions associated with a campaign.

### Authentication & Authorization

The Shopper Promotions API requires a JSON Web Token acquired via the Shopper Customers endpoint:

```
https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login
```

You must include the relevant scope(s) in the client ID used to generate the SLAS token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Request Details

#### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### Response Details

#### Personalization

Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)

#### Caching

Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get Promotions by ID

Retrieve one or more promotions by their IDs (comma-separated, max 50).

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-promotions/v1/organizations/{organizationId}/promotions?ids=Buy5for50,free_shipping&siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Get Promotion by Promotion ID

Use the Shopper Promotions API to find promotion information by the promotion ID.

For example, a customer who is browsing on a commerce shopping app built using Commerce Cloud APIs can see the details about the applied promotions in the cart.

#### Get Promotion by Campaign ID

Use the Shopper Promotions API to find promotion information by the campaign ID.

For example, a customer who is browsing on a commerce shopping app built using Commerce Cloud APIs can see the possible promotions that can be applied in the cart.

### Related APIs

*   [Promotions (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/promotions?meta=Summary) — Create and manage promotions, discounts, and qualifiers.

**Version:** 1.4.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-promotions/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-promotions: Allows read operations on shopper promotions
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-promotions: Allows read operations on shopper promotions
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-promotions: Allows read operations on shopper promotions

## Operations

### GET Return an array of enabled promotions for specified IDs.

`GET /organizations/{organizationId}/promotions`

Operation ID: `getPromotions`. Security: ShopperToken (sfcc.shopper-promotions, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-promotions, sfcc.shopper-standard).

In the request URL, you can specify up to 50 IDs. If you specify an ID that contains either parentheses or the separator characters, you must URL encode these characters. Each request returns only enabled promotions as the server does not consider promotion qualifiers or schedules.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `ids` (query, array of string, required) A comma-separated list of promotion identifiers. Maximum: 50.  
    Items: Maximum length: 256.
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Promotion information retrieved successfully.
    
    Media type: `application/json`. Schema: `PromotionResult`.
    
    _Example: PromotionsResult_ Multiple promotions retrieved by ID
    
    ```
    {
      "limit": 2,
      "data": [
        {
          "id": "Buy5for50",
          "name": "Buy 5 for $50",
          "calloutMsg": "Buy 5 for $50",
          "details": "Buy any 5 qualifying items and pay only $50. Discount applied at checkout.",
          "currency": "USD",
          "startDate": "2025-01-01T00:00:00Z",
          "endDate": "2025-12-31T23:59:00Z"
        },
        {
          "id": "$5_off_ties_promotion",
          "name": "$5 Off Ties Promotion",
          "calloutMsg": "$5 off Men's Ties",
          "details": "$5 off Men's Ties when you apply coupon code TIES5.",
          "currency": "USD",
          "startDate": "2025-03-01T00:00:00Z",
          "endDate": "2025-06-30T23:59:00Z",
          "c_promoCategory": "apparel"
        }
      ],
      "total": 2
    }
    ```
    
*   **404** Returned when there is no promotion found with the given ID for the requested site.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getPromotions404_
    
    ```
    {
      "type": "/PromotionNotFoundException",
      "detail": "There is no promotion found with the given ID for the requested site.",
      "title": "Not Found",
      "instance": "/foo"
    }
    ```
    

### GET Return an array of enabled promotions matching the specified filter criteria.

`GET /organizations/{organizationId}/promotions/campaigns/{campaignId}`

Operation ID: `getPromotionsForCampaign`. Security: ShopperToken (sfcc.shopper-promotions, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-promotions, sfcc.shopper-standard).

Retrieves promotion information using filter criteria. In the request URL, you must provide a campaign\_id parameter, and you can optionally specify a date range by providing start\_date and end\_date parameters. Both parameters are required to specify a date range, and omitting one causes the server to return a MissingParameterException fault. Each request returns only enabled promotions, since the server does not consider promotion qualifiers or schedules.

#### Parameters

*   `campaignId` (path, string, required) Find the promotions assigned to this campaign (mandatory).  
    Minimum length: 1. Maximum length: 256.
*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `startDate` (query, string) The start date of the promotion in ISO 8601 date time format.
*   `endDate` (query, string) The end date of the promotion in ISO 8601 date time format.
*   `currency` (query, CurrencyCode) The currency mnemonic specified for price. This parameter is effective only for product suggestions.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Retrieved promotion information successfully.
    
    Media type: `application/json`. Schema: `PromotionResult`.
    
    _Example PromotionsResult: same as GET /organizations/{organizationId}/promotions 200 response._ Multiple promotions retrieved by ID
    
    _Example: PromotionsResult_ Multiple promotions retrieved by ID
    
*   **400** Returned when a start date is provided without an end date, when an end date is provided without a start date, or when an end date precedes the start date.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getPromotionsForCampaign400_
    
    ```
    {
      "type": "/InvalidDateException",
      "detail": "Invalid Start or End Date",
      "title": "Invalid Start or End Date",
      "instance": "/foo"
    }
    ```
    
*   **404** Returned when no promotion with the specified ID is found for the requested site.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getPromotions404_
    
    ```
    {
      "type": "/PromotionNotFoundException",
      "detail": "There is no promotion found with the given ID for the requested site.",
      "title": "Not Found",
      "instance": "/foo"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### PromotionResult

Result document containing an array of promotions.

Includes all fields of `ResultBase`.

*   `data` (_array of Promotion_, required) The array of promotion documents.

_Example_

```
{
  "limit": 2,
  "data": [
    {
      "calloutMsg": "Buy5for50",
      "details": "Buy5for50",
      "id": "Buy5for50",
      "name": "Buy5for50"
    },
    {
      "calloutMsg": "$5 off Men's Ties",
      "details": "$5 off Men's Ties (with coupon)",
      "id": "$5_off_ties_promotion",
      "name": "5 Off Ties Promotion"
    }
  ],
  "total": 2
}
```

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Promotion

Document representing a promotion.

*   `calloutMsg` (_string_) The localized call-out message of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `currency` (_string_) The currency that a promotion can be applied to. A null value means that the promotion applies to all allowed currencies.  
    Example: `USD`.
*   `details` (_string_) The localized detailed description of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `endDate` (_string (date-time)_) The end date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ . The time zone of the date time is always UTC.  
    Example: `2015-07-04T21:00:00Z`.
*   `id` (_string_, required) The unique ID of the promotion.  
    Example: `$30FixedShippingAmountAbove150`.
*   `image` (_string_) The URL to the promotion image.
*   `name` (_string_) The localized name of the promotion.  
    Example: `$30 Fixed Shipping Amount Above 150`.
*   `startDate` (_string (date-time)_) The start date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ. The time zone of the date time is always UTC.  
    Example: `2015-07-04T21:00:00Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=f4f3be1a625931ce88b971c9dab469a6c1c8182104be93e105c14e4772eb80cf url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-search.md -->

Shopper Search

# Shopper Search

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-search/shopper-search-oas-v1-public.yaml)

## API Overview

Use the Shopper Search API for search functionality that lets shoppers search for products using keywords and refinement. The search results can be products or suggestions based on the endpoint you choose in the API.

### Authentication & Authorization

The client requesting the API must have access to the product search and search suggestion resources.

The Shopper Search API requires a JWT acquired via the Shopper Customers endpoint:

```
https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login
```

You must include the relevant scopes in the client ID used to generate the SLAS token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Request Details

#### Property Selection

This API supports the `select` query parameter for filtering response properties. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html)

#### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### Response Details

#### Personalization

Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)

#### Caching

Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Search for Products

Search for products by keyword. Replace `{access_token}` with a valid SLAS token.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1/organizations/{organizationId}/product-search?q=dress&siteId=RefArch&limit=5" \
  -H "Authorization: Bearer {access_token}"
```

#### Provide Search Suggestions

Use the Shopper Search API to provide search suggestions as a shopper searches.

For example, a developer who is building a shopping app using the Salesforce Commerce API would like to provide product, brand, and category suggestions. When a shopper types in a search phrase that exceeds a definable minimum length and the GET Search Suggestion endpoint is requested, the platform delivers a set of suggestions with products (name, ID), brands (name), and categories (name, ID). Shoppers can reach their desired search results more quickly using the suggested completion and correction.

#### Provide Search Results

Use the Shopper Search API to gather product results for a shoppers search query.

For example, a developer who is building a shopping app using the Salesforce Commerce API would like to implement a product search functionality. When a shopper enters a search phrase and the GET Product Search endpoint is requested, the platform performs a keyword search and a sorted search result is returned. The sorted search result can be refined according to given values (for example, a price range). The product search result contains a definable number of product search hits. A product search hit describes a matching product with its ID and name. Furthermore, the search hit contains product images, prices, represented products, and variations. In addition to the search hits, the search results also deliver refinement and sorting options.

#### Retrieve Promotion Information

Note: This only applies if `promotions` expand is provided in the query parameter.

Promotions provide discounts to shoppers when they meet certain purchase requirements.

Promotion information is described in detail in [Promotion Details](https://developer.salesforce.com/docs/commerce/commerce-api/guide/promotion-details.html), but the following list provides several key points:

*   Pricing discounts for basket and shipping promotions are NEVER returned by the 'getProduct' or 'getProducts' endpoint.
*   Promotional pricing is ONLY returned for products that are included with non-conditional promotions.
*   Callout messages are ALWAYS returned by the 'getProduct' and 'getProducts' endpoints.

By default, 'getProduct' and 'getProducts' return promotion information for a queried product. Promotion information includes both pricing and callout message information. However, the specific pricing and callout information that is fetched is determined by:

*   Promotion Type
*   Product Type
*   Product Purchase Requirements

Some promotions can be displayed on a Product Data Page (PDP) or Product Listing page (PLP), while other promotions are displayed in the context of a basket, such as an order level promotion: "add the product to your basket to view price information". It is important to understand what is included in the response when designing a PDP or PLP on top of SCAPI to ensure your design aligns with implementable features.

Note: When you search for a variant product, the Product Search API returns the master or main product as the primary search hit. When promotion data (productPromotion) is returned, it does not contain pricing information because the returned product is the main product. To retrieve pricing information, pass the query string `allVariationProperties=true` with the `promotions` expand parameter, which returns pricing data for variant products if the promotion is unconditional. The `allVariationProperties` flag specifies the variation properties to be included in the result.

#### Filter Products by Promotion Role

You can filter products by their role in a promotion using the `pmid` (promotion ID) and `pmpt` (promotion product type) refinement parameters together. This allows you to find specific types of products within a promotion:

*   `pmid`: Specifies the promotion ID to filter by
*   `pmpt`: Specifies the type of products to return within that promotion:
    *   `all`: Returns all products related to the promotion (default behavior)
    *   `qualifying`: Returns only products that qualify for the promotion but don't receive the discount/bonus
    *   `discounted`: Returns only products that receive a discount in the promotion
    *   `bonus`: Returns only products that are given as bonuses in the promotion

Example Usage:

```
GET /organizations/{organizationId}/product-search?refine=pmid=summer-sale&refine=pmpt=discounted
```

This would return only the products that receive discounts in the "summer-sale" promotion.

**Note:** The `pmpt` parameter only has an effect when used with `pmid`. If `pmpt` is specified without `pmid`, it will be ignored and all products will be returned.

#### Shopper Personalization

The SCAPI response can be personalized using the Shopper Context API or hooks. By setting specific values in the Shopper Context API, you can modify the response of the 'getProduct' or 'getProducts' endpoint based on the shopper's context. For instance, you can offer a 5% discount or free shipping to shoppers using mobile devices.

### JWA Caching

The response is cached in JWA, which means promotion data contained in the response is also cached based on the TTL (Time to Live) specified in the Business Manager [Feature Switches](https://help.salesforce.com/s/articleView?id=cc.b2c_feature_switches.htm&type=5) configuration. When the shopper context value is updated, a check is conducted to see if the updated shopper context affects the retrieval of product-promotion data. If it does, then the response is fetched from the source and cached in the JWA.

For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

### Best Practices

These best practices refer to features that are generally available with B2C Commerce 24.3.

For better performance, when you call the GET Product Search endpoint, we recommend that you:

*   Use the `select` query parameter to filter the response of a specified field or set of fields, and remove default outputs that you don't need. For example, filter the response to return only the relevant product names, ids, variants, and product IDs of the variants.
*   Limit API requests to the GET Product Search endpoint instead of calling both the GET Product Search and GET Products endpoints to show information on a product listing page (PLP). Use these features to provide the additional product information needed to render product tiles:
    *   **Allowable value:** `promotions` value in the `expand` query parameter
    *   **Query parameters:** `perPricebook`, `allImages`, and `allVariationProperties`
    *   **Responses:** `productPromotions`, `imageGroups`, `priceRanges`, `tieredPrices`, `variants`, and `variationGroups`
*   Pass in only the `expand` values and query parameters that you consider necessary to meet your PLP requirements. Requesting large amounts of information can increase the latency, especially if there's a lot of data to be returned (for example, many imageGroups and variants).

**Version:** 1.15.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/search/shopper-search/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-product-search: Allows read operations on shopper search.
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-product-search: Allows read operations on shopper search.
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-product-search: Allows read operations on shopper search.

## Operations

### GET Provides keyword and refinement-based search for products, returning only product ID, link, and name. Results are limited to products that are online and part of the site catalog.

`GET /organizations/{organizationId}/product-search`

Operation ID: `productSearch`. Security: ShopperToken (sfcc.shopper-product-search, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-product-search, sfcc.shopper-standard).

Provide keyword and refinement search functionality for products. Only returns the product ID, link, and name in the product search hit. The search result only contains products that are online and assigned to the site catalog.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `select` (query, Select) The property selector declaring which fields are included in the product search response payload. For details, see [Property Selection.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html)
    
    _Example_
    
    ```
    (hits.(**), refinements, sortingOptions.(id))
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `q` (query, string) The query phrase to search for. For example to search for a product "shirt", type q=shirt. **Note:** - Lexical search queries are limited to a maximum of 50 characters.  
    Minimum length: 1. Maximum length: 500. Example: `shirt`.
*   `refine` (query, array of string, style: form, explode: true)
    
    Parameter that represents a refinement attribute or values pair. Refinement attribute ID and values are separated by '='.  
    Multiple values are supported by a subset of refinement attributes and can be provided by separating them using a pipe (URL encoded = "|"), for example: refine=c\_refinementColor=red|green|blue.  
    Value ranges can be specified like this: refine=price=(100..500).  
    Multiple refine parameters can be provided by using the refine as the key, for example: refine=price=(0..10)&refine=c\_refinementColor=green.  
    The refinements can be a collection of custom defined attributes IDs and the system defined attributes IDs but the search can only accept a total of 9 refinements at a time.  
    
    The following system refinement attribute ids are supported:  
    `cgid`: Allows refinement per single category ID. Multiple category IDs are not supported.  
    `cgslug`: Allows refinement by a category URL slug (for example, `mens/clothing`). The server resolves the slug to a category ID using the site's storefront URL mapping. If the slug can't be resolved to a category, the API returns a 400 error. This parameter is mutually exclusive with `cgid`. If both are provided, `cgid` takes priority and `cgslug` is ignored.  
    `price`: Allows refinement per single price range. Multiple price ranges are not supported.  
    `htype`: Allow refinement by including only the provided hit types. Accepted types are 'product', 'master', 'set', 'bundle', 'slicing\_group' (deprecated), 'variation\_group'.  
    `orderable_only`: Unavailable products are excluded from the search results if true is set. Multiple refinement values are not supported.  
    `ilids`: Allows refining by inventory list IDs. Supports up to 10 inventory list IDs per request.  
    `pmid`: Allows refinement on the supplied promotion ID(s). When used with `pmpt`, filters products by their role in the promotion.  
    `pmpt`: Allows refinement per promotion product type. Must be used with `pmid` to filter products by their role in the promotion. Valid values are:
    
    *   `all`: Returns all products related to the promotion (default)
    *   `qualifying`: Returns only products that qualify for the promotion but don't receive the discount/bonus
    *   `discounted`: Returns only products that receive a discount in the promotion
    *   `bonus`: Returns only products that are given as bonuses in the promotion
    
    **Note:** To refine a search using multiple promotion filters—for example, to find products in both the spring and summer campaigns—see [Refining by Multiple Promotions](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-promotions-for-developers.html#refining-by-multiple-promotions).
    
      
    Items: Maximum length: 4000. Example: `price=(0..10)`. Maximum items: 9.
*   `sort` (query, string) The ID of the sorting option to sort the search hits.  
    Maximum length: 256. Example: `brand`.
*   `searchMode` (query, string)
    
    A hint for the search matching approach the platform should use for this request. `semantic` selects meaning-based matching; `lexical` selects keyword/token-based matching.
    
    The hint is non-authoritative and applies only to this request: the platform runs its full routing cascade and may demote a `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field in the response rather than assuming the requested mode was honored. When omitted, the platform's configured default applies.
    
      
    Allowed values: `semantic`, `lexical`. Example: `semantic`.
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `expand` (query, array of string) A comma-separated list with allowed values - `availability`, `images`, `prices`, `represented_products`, `variations`, `promotions`, `custom_properties`, `slug`. By default, the expand parameter includes `availability, images, prices, represented_products, variations`. Use none to disable all expand options.  
    Items: Allowed values: `none`, `availability`, `images`, `prices`, `represented_products`, `variations`, `promotions`, `custom_properties`, `page_meta_tags`, `slug`. Example: `prices`.
*   `allImages` (query, boolean) When the `images` expand parameter is used with this flag, the response includes the `imageGroups` property, which contains an image model. If this flag is true, the full image model is returned and you can combine with `imgTypes` to filter image types and counts. If false, only matching images are included. If no flag is passed, the `imageGroups` property is omitted from the response.  
    Example: `true`.
*   `imgTypes` (query, string) Filters product images by type with optional count limits per type. This parameter requires both the `images` expand parameter and `allImages=true`. When used, the response includes the `imageGroups` property filtered by the specified image types. The format is a comma-separated list of image types with optional counts: `<imageType>:<count>,<imageType>:<count>`. If the count is omitted, all images of that type are returned. If specified, the count limits the number of images returned for that type. For example, `imgTypes=large:2,small:1` returns up to 2 large images and 1 small image per product in the imageGroups. If `imgTypes` is used without `allImages=true`, it is ignored and imageGroups aren't included in the response.  
    Maximum length: 50. Example: `large:2,small:1`.
*   `perPricebook` (query, boolean) When this flag is set to `true` and is used with the `prices` expand parameter, the response includes per PriceBook prices and tiered prices (if available).  
    Example: `true`.
*   `allVariationProperties` (query, boolean) The flag that determines which variation properties are included in the result. When set to `true` with the `variations` expand parameter, all variation properties (`variationAttributes`, `variationGroups`, `variants`) are returned. When set to false, only the default property `variationAttributes` is returned.  
    Example: `false`.
*   `includedCustomVariationProperties` (query, array of string) A comma-separated list of custom property ids to be returned for variant products. The `variants` expand parameter and `allVariationProperties` query parameter are required for these properties to be returned.  
    Items: Maximum length: 256. Pattern: ^c\_.\*. Example: `c_batteryLife`. Maximum items: 5.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Product search successfully returned results.
    
    Media type: `application/json`. Schema: `ProductSearchResult`.
    
    _Example: ProductSearchResultExample_
    
    ```
    {
      "limit": 3,
      "hits": [
        {
          "currency": "USD",
          "hitType": "master",
          "image": {
            "alt": "Modern Dress Shirt, , large",
            "disBaseLink": "https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/ZZEU_006/on/demandware.static/-/Sites-apparel-catalog/default/dw7671b929/images/large/B0174501_GY9_0.jpg",
            "link": "https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw7671b929/images/large/B0174501_GY9_0.jpg",
            "title": "Modern Dress Shirt, "
          },
          "orderable": true,
          "price": 135,
          "productId": "74974310",
          "productName": "Modern Dress Shirt",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "74974310-1"
          },
          "representedProducts": [
            {
              "id": "74974310-1"
            },
            {
              "id": "74974310-2"
            },
            {
              "id": "74974310-3"
            },
            {
              "id": "74974310-4"
            }
          ],
          "variationAttributes": [
            {
              "id": "color",
              "name": "color",
              "values": [
                {
                  "name": "Blue",
                  "orderable": true,
                  "value": "002"
                }
              ]
            },
            {
              "id": "size",
              "name": "size",
              "values": [
                {
                  "name": "15R",
                  "orderable": true,
                  "value": "15R"
                },
                {
                  "name": "15L",
                  "orderable": true,
                  "value": "15L"
                },
                {
                  "name": "16L",
                  "orderable": true,
                  "value": "16L"
                }
              ]
            }
          ]
        },
        {
          "currency": "USD",
          "hitType": "master",
          "image": {
            "alt": "The White Dress Shirt, , large",
            "disBaseLink": "https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/ZZEU_006/on/demandware.static/-/Sites-apparel-catalog/default/dw9368b001/images/large/70284588_100_0.jpg",
            "link": "https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw9368b001/images/large/70284588_100_0.jpg",
            "title": "The White Dress Shirt, "
          },
          "orderable": true,
          "price": 135,
          "productId": "78916783",
          "productName": "The White Dress Shirt",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "78916783-1"
          },
          "representedProducts": [
            {
              "id": "78916783-1"
            },
            {
              "id": "78916783-2"
            },
            {
              "id": "78916783-3"
            },
            {
              "id": "78916783-4"
            }
          ],
          "variationAttributes": [
            {
              "id": "color",
              "name": "Color",
              "values": [
                {
                  "name": "White",
                  "orderable": true,
                  "value": "white"
                }
              ]
            },
            {
              "id": "size",
              "name": "size",
              "values": [
                {
                  "name": "15L",
                  "orderable": true,
                  "value": "15L"
                },
                {
                  "name": "15R",
                  "orderable": true,
                  "value": "15R"
                }
              ]
            }
          ]
        },
        {
          "currency": "USD",
          "hitType": "master",
          "image": {
            "alt": "Striped Shirt, , large",
            "disBaseLink": "https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/ZZEU_006/on/demandware.static/-/Sites-apparel-catalog/default/dw83b22281/images/large/PG.10213135.JJ9VSA5.PZ.jpg",
            "link": "https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw83b22281/images/large/PG.10213135.JJ9VSA5.PZ.jpg",
            "title": "Striped Shirt, "
          },
          "orderable": true,
          "price": 40.99,
          "productId": "25518484",
          "productName": "Striped Shirt",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "701642854760"
          },
          "representedProducts": [
            {
              "id": "701642854760"
            },
            {
              "id": "701642854784"
            },
            {
              "id": "701642854791"
            },
            {
              "id": "701642854777"
            }
          ],
          "variationAttributes": [
            {
              "id": "color",
              "name": "Color",
              "values": [
                {
                  "name": "Royal Multi",
                  "orderable": true,
                  "value": "JJ9VSA5"
                }
              ]
            },
            {
              "id": "size",
              "name": "Size",
              "values": [
                {
                  "name": "S",
                  "orderable": true,
                  "value": "9SM"
                },
                {
                  "name": "M",
                  "orderable": true,
                  "value": "9MD"
                },
                {
                  "name": "L",
                  "orderable": true,
                  "value": "9LG"
                },
                {
                  "name": "XL",
                  "orderable": true,
                  "value": "9XL"
                }
              ]
            }
          ]
        }
      ],
      "pageMetaTags": [
        {
          "id": "description",
          "value": "Browse our latest selection of shirts. Free shipping on orders over $50.",
          "type": "name"
        },
        {
          "id": "robots",
          "value": "index,follow",
          "type": "name"
        },
        {
          "id": "title",
          "value": "Find amazing products in Storefront Catalog - EN' today",
          "type": "title"
        },
        {
          "id": "og:title",
          "value": "Shirts - Storefront Catalog",
          "type": "property"
        },
        {
          "id": "itemList",
          "value": "{\"@context\":\"https://schema.org/\",\"@type\":\"ItemList\",\"name\":\"Shirts\",\"numberOfItems\":4}",
          "type": "jsonld"
        }
      ],
      "query": "shirt",
      "searchMode": "semantic",
      "effectiveSearchMode": "semantic",
      "refinements": [
        {
          "attributeId": "cgid",
          "label": "Category",
          "values": [
            {
              "hitCount": 4,
              "label": "New Arrivals",
              "value": "newarrivals"
            }
          ]
        },
        {
          "attributeId": "c_refinementColor",
          "label": "Color",
          "values": [
            {
              "hitCount": 0,
              "label": "Beige",
              "presentationId": "beige",
              "value": "Beige"
            },
            {
              "hitCount": 0,
              "label": "Yellow",
              "presentationId": "yellow",
              "value": "Yellow"
            },
            {
              "hitCount": 7,
              "label": "Miscellaneous",
              "presentationId": "miscellaneous",
              "value": "Miscellaneous"
            }
          ]
        },
        {
          "attributeId": "price",
          "label": "Price",
          "values": [
            {
              "hitCount": 14,
              "label": "$20 - $49.99",
              "value": "(20..50)"
            },
            {
              "hitCount": 26,
              "label": "$50 - $99.99",
              "value": "(50..100)"
            },
            {
              "hitCount": 6,
              "label": "$100 - $499.99",
              "value": "(100..500)"
            }
          ]
        },
        {
          "attributeId": "c_isNew",
          "label": "New Arrival",
          "values": [
            {
              "hitCount": 1,
              "label": "true",
              "value": "true"
            }
          ]
        },
        {
          "attributeId": "brand",
          "label": "brand",
          "values": [
            {
              "hitCount": 1,
              "label": "Lacy-S",
              "value": "Lacy-S"
            }
          ]
        }
      ],
      "searchPhraseSuggestions": {
        "suggestedPhrases": [
          {
            "exactMatch": true,
            "phrase": "shirt"
          }
        ],
        "suggestedTerms": [
          {
            "originalTerm": "shirt",
            "terms": [
              {
                "completed": false,
                "corrected": false,
                "exactMatch": true,
                "value": "shirt"
              }
            ]
          }
        ]
      },
      "sortingOptions": [
        {
          "id": "best-matches",
          "label": "Best Matches"
        },
        {
          "id": "price-low-to-high",
          "label": "Price Low To High"
        }
      ],
      "offset": 0,
      "total": 46
    }
    ```
    
    _Example: ProductSearchWithPromotionFilterExample_ Product search with promotion filtering using pmid and pmpt
    
    Example showing how to filter products by their role in a promotion using pmid and pmpt parameters
    
    ```
    {
      "limit": 1,
      "hits": [
        {
          "currency": "USD",
          "hitType": "master",
          "image": {
            "alt": "Platinum Red Stripes Easy Care Fitted Shirt, , large",
            "disBaseLink": "https://image.demandware.com/dw/image/v2/zzzz_s01/on/demandware.static/-/Sites-apparel-catalog/default/dw8c838411/images/large/PG.10123426.JJ8WXXX.PZ.jpg",
            "link": "https://localhost/on/demandware.static/-/Sites-apparel-catalog/default/dw8c838411/images/large/PG.10123426.JJ8WXXX.PZ.jpg",
            "title": "Platinum Red Stripes Easy Care Fitted Shirt, "
          },
          "orderable": true,
          "price": 75,
          "pricePerUnit": 75,
          "productId": "25050730",
          "productName": "Platinum Red Stripes Easy Care Fitted Shirt",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "008884304108"
          },
          "representedProducts": [
            {
              "id": "008884304108"
            }
          ],
          "variationAttributes": [
            {
              "id": "color",
              "name": "Color",
              "values": [
                {
                  "name": "White",
                  "orderable": true,
                  "value": "JJ8WXXX"
                }
              ]
            },
            {
              "id": "size",
              "name": "Size",
              "values": [
                {
                  "name": "6",
                  "orderable": true,
                  "value": "006"
                }
              ]
            }
          ]
        }
      ],
      "query": "shirts",
      "refinements": [
        {
          "attributeId": "cgid",
          "label": "Category",
          "values": [
            {
              "hitCount": 1,
              "label": "Womens",
              "value": "womens",
              "values": [
                {
                  "hitCount": 1,
                  "label": "Clothing",
                  "value": "womens-clothing",
                  "values": [
                    {
                      "hitCount": 1,
                      "label": "Tops",
                      "value": "womens-clothing-tops"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "attributeId": "c_refinementColor",
          "label": "Color",
          "values": [
            {
              "hitCount": 0,
              "label": "Beige",
              "presentationId": "beige",
              "value": "Beige"
            },
            {
              "hitCount": 0,
              "label": "White",
              "presentationId": "white",
              "value": "White"
            }
          ]
        },
        {
          "attributeId": "c_isNew",
          "label": "New Arrival"
        },
        {
          "attributeId": "c_topType",
          "label": "Type | Use"
        },
        {
          "attributeId": "c_size",
          "label": "Size",
          "values": [
            {
              "hitCount": 0,
              "label": "4",
              "value": "4"
            },
            {
              "hitCount": 1,
              "label": "6",
              "value": "6"
            },
            {
              "hitCount": 0,
              "label": "8",
              "value": "8"
            }
          ]
        },
        {
          "attributeId": "price",
          "label": "Price",
          "values": [
            {
              "hitCount": 1,
              "label": "$50 - $99.99",
              "value": "(50..100)"
            }
          ]
        }
      ],
      "searchPhraseSuggestions": {
        "suggestedPhrases": [
          {
            "exactMatch": true,
            "phrase": "shirts"
          }
        ],
        "suggestedTerms": [
          {
            "originalTerm": "shirts",
            "terms": [
              {
                "completed": false,
                "corrected": false,
                "exactMatch": true,
                "value": "shirts"
              }
            ]
          }
        ]
      },
      "selectedRefinements": {
        "pmid": "BonusProductOnOrderOfAmountABove250",
        "pmpt": "bonus"
      },
      "sortingOptions": [
        {
          "id": "best-matches",
          "label": "Best Matches"
        },
        {
          "id": "price-low-to-high",
          "label": "Price Low To High"
        },
        {
          "id": "price-high-to-low",
          "label": "Price High to Low"
        },
        {
          "id": "product-name-ascending",
          "label": "Product Name A - Z"
        },
        {
          "id": "product-name-descending",
          "label": "Product Name Z - A"
        },
        {
          "id": "brand",
          "label": "Brand"
        },
        {
          "id": "most-popular",
          "label": "Most Popular"
        },
        {
          "id": "top-sellers",
          "label": "Top Sellers"
        }
      ],
      "offset": 0,
      "total": 1
    }
    ```
    
    _Example: ProductSearchResultWithCustomVariationPropertiesExample_ Product search result demonstrating custom variation properties on product variants.
    
    ```
    {
      "limit": 1,
      "hits": [
        {
          "hitType": "master",
          "productId": "portable-media-player",
          "productName": "Portable Media Player",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "media-player-purple-8gb"
          },
          "variants": [
            {
              "productId": "media-player-silver-8gb",
              "variationValues": {
                "color": "Silver",
                "memorySize": "8 GB"
              },
              "c_badges": [
                "Popular"
              ],
              "c_mediaFormat": [
                "0020",
                "0050"
              ],
              "c_musicStorage": "2,000 songs"
            },
            {
              "productId": "media-player-purple-8gb",
              "variationValues": {
                "color": "Purple",
                "memorySize": "8 GB"
              },
              "c_badges": [
                "Best Seller"
              ],
              "c_mediaFormat": [
                "0010",
                "0020",
                "0030"
              ],
              "c_musicStorage": "2,000 songs"
            }
          ]
        }
      ],
      "query": "media player purple",
      "refinements": [],
      "searchPhraseSuggestions": {
        "suggestedPhrases": [],
        "suggestedTerms": []
      },
      "sortingOptions": [
        {
          "id": "best-matches",
          "label": "Best Matches"
        }
      ],
      "offset": 0,
      "total": 1
    }
    ```
    
    _Example: ProductSearchWithProcessedQueryExample_ Product search result demonstrating processors being executed on the search query.
    
    ```
    {
      "limit": 1,
      "hits": [
        {
          "hitType": "master",
          "productId": "portable-media-player",
          "productName": "Portable Media Player",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "media-player-purple-8gb"
          },
          "variants": [
            {
              "productId": "media-player-silver-8gb",
              "variationValues": {
                "color": "Silver",
                "memorySize": "8 GB"
              },
              "c_badges": [
                "Popular"
              ],
              "c_mediaFormat": [
                "0020",
                "0050"
              ],
              "c_musicStorage": "2,000 songs"
            },
            {
              "productId": "media-player-purple-8gb",
              "variationValues": {
                "color": "Purple",
                "memorySize": "8 GB"
              },
              "c_badges": [
                "Best Seller"
              ],
              "c_mediaFormat": [
                "0010",
                "0020",
                "0030"
              ],
              "c_musicStorage": "2,000 songs"
            }
          ]
        }
      ],
      "processedQuery": {
        "appliedProcessors": [
          {
            "processorName": "Attribute Aware Search",
            "refinements": {
              "price": "(..200)"
            },
            "result": "media player purple"
          }
        ],
        "query": "media player purple"
      },
      "query": "media player purple under 200",
      "refinements": [],
      "searchPhraseSuggestions": {
        "suggestedPhrases": [],
        "suggestedTerms": []
      },
      "sortingOptions": [
        {
          "id": "best-matches",
          "label": "Best Matches"
        }
      ],
      "offset": 0,
      "total": 1
    }
    ```
    
    _Example: ProductSearchWithFallbackModeExample_ Product search where a semantic request was demoted to lexical.
    
    The caller requested `searchMode=semantic`, but the platform could not serve semantically (for example a single-token SKU lookup) and demoted to `lexical`. The response echoes the requested `searchMode` and reports the mode actually used in `effectiveSearchMode`, which a client reads to detect that the requested mode was not honored.
    
    ```
    {
      "limit": 25,
      "hits": [
        {
          "currency": "USD",
          "hitType": "product",
          "orderable": true,
          "price": 19.99,
          "productId": "ABC-12345",
          "productName": "Classic Cotton Crew Sock",
          "productType": {
            "item": true
          },
          "representedProduct": {
            "id": "ABC-12345"
          }
        },
        {
          "currency": "USD",
          "hitType": "product",
          "orderable": true,
          "price": 24.99,
          "productId": "ABC-12346",
          "productName": "Ribbed Wool Blend Sock",
          "productType": {
            "item": true
          },
          "representedProduct": {
            "id": "ABC-12346"
          }
        }
      ],
      "query": "ABC-12345",
      "searchMode": "semantic",
      "effectiveSearchMode": "lexical",
      "refinements": [],
      "searchPhraseSuggestions": {
        "suggestedPhrases": [],
        "suggestedTerms": []
      },
      "sortingOptions": [
        {
          "id": "best-matches",
          "label": "Best Matches"
        }
      ],
      "offset": 0,
      "total": 2
    }
    ```
    
    _Example: ProductSearchWithConfiguredModeExample_ Product search with no requested mode, resolved by the platform's configured default.
    
    The request omitted `searchMode`, so the response omits the echoed hint and the platform's configured default selected the mode reported in `effectiveSearchMode`.
    
    ```
    {
      "limit": 25,
      "hits": [
        {
          "currency": "USD",
          "hitType": "master",
          "orderable": true,
          "price": 39.99,
          "productId": "74974310",
          "productName": "Modern Dress Shirt",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "74974310-1"
          }
        },
        {
          "currency": "USD",
          "hitType": "master",
          "orderable": true,
          "price": 44.99,
          "productId": "78916783",
          "productName": "The White Dress Shirt",
          "productType": {
            "master": true
          },
          "representedProduct": {
            "id": "78916783-1"
          }
        }
      ],
      "query": "shirt",
      "effectiveSearchMode": "semantic",
      "refinements": [],
      "searchPhraseSuggestions": {
        "suggestedPhrases": [],
        "suggestedTerms": []
      },
      "sortingOptions": [
        {
          "id": "best-matches",
          "label": "Best Matches"
        }
      ],
      "offset": 0,
      "total": 2
    }
    ```
    
*   **400** Bad Request.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MalformedSelectorGetProductsSearchForSelect_
    
    ```
    {
      "title": "Malformed Selector",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-selector",
      "detail": "The property selector '(hits.(currency, hitType,image.(**))' is malformed.",
      "selector": "(hits.(currency, hitType,image.(**))"
    }
    ```
    
    _Example: TooManyCustomVariationAttributes_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "'includedCustomVariationProperties' violates the value constraint. The expected value is between '(0..5)'.",
      "parameter": "includedCustomVariationProperties",
      "expected": "(0..5)"
    }
    ```
    
    _Example: InvalidCategorySlugRefinement_
    
    ```
    {
      "title": "Invalid Category Slug Refinement",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-category-slug-refinement",
      "detail": "The category slug refinement 'i-dont-exist' could not be resolved to a category.",
      "categorySlug": "i-dont-exist"
    }
    ```
    
    _Example: InvalidSearchMode_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "'searchMode' violates the value constraint. The expected value is one of '[semantic, lexical]'.",
      "parameter": "searchMode",
      "expected": "[semantic, lexical]"
    }
    ```
    

### GET Provides keyword-based search suggestions for products, categories, and brands. Returns suggested items for each based on the search phrase.

`GET /organizations/{organizationId}/search-suggestions`

Operation ID: `getSearchSuggestions`. Security: ShopperToken (sfcc.shopper-product-search, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-product-search, sfcc.shopper-standard).

Provide keyword search functionality for products, categories, and brands suggestions. Returns suggested products, suggested categories, and suggested brands for the given search phrase.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `q` (query, string, required) The search phrase (q) for which suggestions are evaluated. Search suggestions are determined when the search phrase input is at least three (default) characters long. The value is configurable in the Business Manager.  
    Minimum length: 3. Maximum length: 50. Example: `sho`.
*   `searchMode` (query, string)
    
    A hint for the search matching approach the platform should use for this request. `semantic` selects meaning-based matching; `lexical` selects keyword/token-based matching.
    
    The hint is non-authoritative and applies only to this request: the platform runs its full routing cascade and may demote a `semantic` request to `lexical` (for example when the semantic index is unavailable). Always read the resolved `effectiveSearchMode` field in the response rather than assuming the requested mode was honored. When omitted, the platform's configured default applies.
    
      
    Allowed values: `semantic`, `lexical`. Example: `semantic`.
*   `limit` (query, integer) The maximum number of suggestions made per request. If no value is defined, by default five suggestions per suggestion type are evaluated. This affects all types of suggestions (category, product, brand, and custom suggestions).  
    Default: `5`. Minimum: 1. Maximum: 10. Example: `5`.
*   `currency` (query, CurrencyCode) A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.
    
    _Example: CurrencyCode_
    
    ```
    USD
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `expand` (query, array of string) A comma-separated list of the values `images`, `prices`, `custom_product_properties`, and `slug`. By default, the expand parameter includes `prices`.  
    Items: Allowed values: `images`, `prices`, `custom_product_properties`, `slug`. Example: `prices`.
*   `includedCustomProductProperties` (query, array of string) A comma-separated list of custom property ids to be returned for product suggestions. The `custom_product_properties` expand parameter is required for these properties to be returned.  
    Items: Maximum length: 256. Pattern: ^c\_.\*. Example: `c_batteryLife`. Maximum items: 5.
*   `includeEinsteinSuggestedPhrases` (query, boolean) The flag that determines whether or not to show recent and popular suggested phrases from Einstein.  
    Example: `false`.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Search suggestions successfully returned.
    
    Media type: `application/json`. Schema: `SuggestionResult`.
    
    _Example: SearchSuggestionResultExample_
    
    ```
    {
      "brandSuggestions": {
        "suggestedPhrases": [
          {
            "exactMatch": false,
            "phrase": "Sony"
          }
        ],
        "suggestedTerms": [
          {
            "originalTerm": "son",
            "terms": [
              {
                "completed": true,
                "corrected": false,
                "exactMatch": false,
                "value": "sony"
              }
            ]
          }
        ]
      },
      "categorySuggestions": {
        "suggestedTerms": [
          {
            "originalTerm": "son"
          }
        ]
      },
      "productSuggestions": {
        "products": [
          {
            "currency": "EUR",
            "price": 300,
            "productId": "sony-ps3-bundle",
            "productName": "Playstation 3 Bundle"
          },
          {
            "currency": "EUR",
            "price": 310,
            "productId": "sony-alpha350-wlen",
            "productName": "Sony Alpha 350 Digital SLR Camera w/18-70mm Lens"
          },
          {
            "currency": "EUR",
            "price": 10,
            "productId": "sony-alpha900-body",
            "productName": "Sony Alpha 900 Digital SLR Camera (body only)"
          },
          {
            "currency": "EUR",
            "price": 50,
            "productId": "sony-warhawk-ps3",
            "productName": "Warhawk (for Sony PS3)"
          },
          {
            "currency": "EUR",
            "price": 280,
            "productId": "sony-psp-console",
            "productName": "Sony PSP® Game Console"
          }
        ],
        "suggestedPhrases": [
          {
            "exactMatch": false,
            "phrase": "sony"
          }
        ],
        "suggestedTerms": [
          {
            "originalTerm": "son",
            "terms": [
              {
                "completed": true,
                "corrected": false,
                "exactMatch": false,
                "value": "sony"
              },
              {
                "completed": true,
                "corrected": false,
                "exactMatch": false,
                "value": "sonyalpha"
              }
            ]
          }
        ]
      },
      "einsteinSuggestedPhrases": {
        "popularSearchPhrases": [
          {
            "exactMatch": false,
            "phrase": "sony"
          },
          {
            "exactMatch": false,
            "phrase": "sony alpha"
          }
        ],
        "recentSearchPhrases": [
          {
            "exactMatch": false,
            "phrase": "sony alpha"
          },
          {
            "exactMatch": false,
            "phrase": "sony alpha 900 body"
          }
        ]
      },
      "searchPhrase": "son",
      "searchMode": "semantic",
      "effectiveSearchMode": "semantic"
    }
    ```
    
    _Example: SearchSuggestionResultWithCustomProductPropertiesExample_ Search suggestions with custom product properties.
    
    ```
    {
      "brandSuggestions": {
        "suggestedPhrases": [
          {
            "exactMatch": false,
            "phrase": "Media Player"
          }
        ],
        "suggestedTerms": [
          {
            "originalTerm": "player",
            "terms": [
              {
                "completed": true,
                "corrected": false,
                "exactMatch": false,
                "value": "media"
              }
            ]
          }
        ]
      },
      "categorySuggestions": {
        "suggestedTerms": [
          {
            "originalTerm": "player"
          }
        ]
      },
      "productSuggestions": {
        "products": [
          {
            "currency": "USD",
            "price": 229,
            "productId": "portable-media-player",
            "productName": "Portable Media Player",
            "c_badges": [],
            "c_mediaFormat": [
              "0020",
              "0030"
            ],
            "c_musicStorage": "1,000 songs"
          }
        ],
        "suggestedPhrases": [
          {
            "exactMatch": false,
            "phrase": "media player"
          }
        ],
        "suggestedTerms": [
          {
            "originalTerm": "player",
            "terms": [
              {
                "completed": true,
                "corrected": false,
                "exactMatch": true,
                "value": "player"
              },
              {
                "completed": true,
                "corrected": false,
                "exactMatch": false,
                "value": "media player"
              }
            ]
          }
        ]
      },
      "searchPhrase": "player"
    }
    ```
    
    _Example: SearchSuggestionWithFallbackModeExample_ Search suggestions where a semantic request was demoted to lexical.
    
    The caller requested `searchMode=semantic` for type-ahead, but the platform demoted to `lexical`. The response echoes the requested `searchMode` and reports the mode actually used in `effectiveSearchMode`.
    
    ```
    {
      "searchPhrase": "abc12345",
      "searchMode": "semantic",
      "effectiveSearchMode": "lexical"
    }
    ```
    
    _Example: SearchSuggestionWithConfiguredModeExample_ Search suggestions with no requested mode, resolved by the platform's configured default.
    
    The request omitted `searchMode`, so the response omits the echoed hint and the platform's configured default selected the mode reported in `effectiveSearchMode`.
    
    ```
    {
      "searchPhrase": "sho",
      "effectiveSearchMode": "semantic"
    }
    ```
    
*   **400** Returned when a query parameter or its value is unknown, or when a maximum or minimum constraint is violated.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InvalidSearchMode: same as GET /organizations/{organizationId}/product-search 400 response._
    
    _Example: StringConstraintViolation_
    
    ```
    {
      "title": "String Constraint Violation",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/string-constraint-violation",
      "detail": "The string length constraint was violated by 'q'. The expected length is '(3..50)'.",
      "expected": "(3..50)",
      "parameter": "q"
    }
    ```
    
    _Example: TooManyCustomProductAttributes_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "'includedCustomProductProperties' violates the value constraint. The expected value is between '(0..5)'.",
      "parameter": "includedCustomProductProperties",
      "expected": "(0..5)"
    }
    ```
    
    _Example: InvalidExpandParameter_
    
    ```
    {
      "title": "Invalid Expand Parameter",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-expand-parameter",
      "detail": "An invalid expand parameter 'invalidParameter' was found.",
      "param": "invalidParameter"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### CurrencyCode

A three letter uppercase currency code conforming to the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) standard, or the string `N/A` indicating that a currency is not applicable.

Type: `string`.

Pattern: ^(\[A-Z\]\[A-Z\]\[A-Z\]|N/A)$. Example: `USD`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### ProductSearchResult

Document representing a product search result.

Includes all fields of `PaginatedResultBase`.

*   `hits` (_array of ProductSearchHit_, required) A sorted array of search hits (`ProductSearchHit` objects). The array can be empty.  
    Minimum length: 1.
*   `pageMetaTags` (_array of PageMetaTag_) Page Meta tags associated with the search result.
*   `query` (_string_, required) The query string that was searched for.  
    Maximum length: 50. Example: `dresses`.
*   `searchMode` (_object_) The search matching approach the client requested for this search, echoed back from the `searchMode` query parameter. Omitted when the request did not supply one. This is the requested hint, not necessarily the mode that served the result — see `effectiveSearchMode`.
    
    Includes all fields of `SearchMode`.
    
*   `effectiveSearchMode` (_object_) The search matching approach the platform actually used to serve this result. May differ from the requested `searchMode` when the platform demoted the mode (for example when the semantic index is unavailable).
    
    Includes all fields of `SearchMode`.
    
*   `processedQuery` (_object_) The result of query processing.
    
    Includes all fields of `ProcessedQuery`.
    
*   `refinements` (_array of ProductSearchRefinement_, required) The sorted array of search refinements. This array can be empty.  
    Minimum length: 1.
*   `searchPhraseSuggestions` (_object_, required) The suggestion given by the system for the submitted search phrase.  
    Minimum length: 1.
    
    Includes all fields of `Suggestion`.
    
    Minimum length: 1.
    
*   `selectedRefinements` (_object_) A map of selected refinement attribute ID or value pairs. The sorting order is the same as in request URL.
    
    Additional properties: `string`.
    
    Maximum length: 4000. Example: `Beige`.
    
*   `selectedSortingOption` (_string_) The ID of the applied sorting option.  
    Maximum length: 4000. Example: `best-matches`.
*   `sortingOptions` (_array of ProductSearchSortingOption_, required) The sorted array of search sorting options. This array can be empty.  
    Minimum length: 1.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SuggestionResult

Document representing a search suggestion result.

*   `brandSuggestions` (_object_) Returns the suggested brands.
    
    Includes all fields of `BrandSuggestions`.
    
*   `categorySuggestions` (_object_) Returns the suggested categories.
    
    Includes all fields of `CategorySuggestions`.
    
*   `productSuggestions` (_object_) Returns the suggested products.
    
    Includes all fields of `ProductSuggestions`.
    
*   `customSuggestion` (_object_) Returns custom suggestions.
    
    Includes all fields of `CustomSuggestions`.
    
*   `einsteinSuggestedPhrases` (_object_) Returns Einstein suggested phrases containing popular and recent search phrases.
    
    Includes all fields of `EinsteinSuggestedPhrases`.
    
*   `searchPhrase` (_string_, required) The query phrase (q) for which suggestions where made.  
    Minimum length: 3. Maximum length: 50. Example: `dresses`.
*   `searchMode` (_object_) The search matching approach the client requested for these suggestions, echoed back from the `searchMode` query parameter. Omitted when the request did not supply one. This is the requested hint, not necessarily the mode that served the suggestions — see `effectiveSearchMode`.
    
    Includes all fields of `SearchMode`.
    
*   `effectiveSearchMode` (_object_) The search matching approach the platform actually used to serve these suggestions. May differ from the requested `searchMode` when the platform demoted the mode (for example when the semantic index is unavailable).
    
    Includes all fields of `SearchMode`.
    

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### ProductSearchHit

Document representing a product search hit.

*   `currency` (_CurrencyCode_)
*   `hitType` (_string_) The type information for the search hit.  
    Maximum length: 256. Example: `product`.
*   `image` (_object_) The first image of the product hit for the configured viewtype.
    
    Includes all fields of `Image`.
    
*   `orderable` (_boolean_) A flag indicating whether the product is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The sales price of the product. In complex products, like master or set, this is the minimum price of related child products.  
    Example: `135`.
*   `priceMax` (_number (double)_) The maximum sales of related child products in complex products like master or set.  
    Example: `150`.
*   `productId` (_string_, required) The ID (SKU) of the product.  
    Minimum length: 1. Maximum length: 100. Example: `74974310`.
*   `productName` (_string_) The localized name of the product.  
    Maximum length: 4000. Example: `Modern Dress Shirt`.
*   `productType` (_object_) The type information for the product.
    
    Includes all fields of `ProductType`.
    
*   `representedProduct` (_object_) The first represented product.
    
    Includes all fields of `ProductRef`.
    
*   `representedProducts` (_array of ProductRef_) All the represented products.
*   `variationAttributes` (_array of VariationAttribute_) The array of represented variation attributes, for the master product only. This array can be empty.
*   `imageGroups` (_array of ImageGroup_) The array of product image groups.
*   `priceRanges` (_array of PriceRange_) Array of one or more price range objects representing one or more Pricebooks in context for the site.
*   `productPromotions` (_array of ProductPromotion_) The array of active customer product promotions for this product. This array can be empty. Coupon promotions are not returned in this array.
*   `tieredPrices` (_array of ProductPriceTable_) The document represents list of tiered prices if the product is a variant
*   `variants` (_array of Variant_) The array of actual variants. Only for master, variation group, and variant types. This array can be empty.
*   `variationGroups` (_array of VariationGroup_) The array of actual variation groups. Only for master, variation group, and variant types. This array can be empty.
*   `slug` (_string_) SEO-friendly slug for the product, derived from the site's configured product URL rule. This is the slug segment only, not a full URL. Returned only when `expand=slug` is requested. Use the slug to construct user-friendly product detail page URLs (for example, /products/{slug}/{productId}).  
    Maximum length: 4000. Example: `modern-dress-shirt`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### PageMetaTag

Document representing a Page Meta Tag object.

*   `id` (_string_) The ID of the Page Meta Tag.  
    Maximum length: 100. Example: `title`.
*   `value` (_string_) Locale-specific value of the Page Meta Tag, evaluated by resolving the rule set for the given Business Manager ID.  
    Example: `Buy the Long Sleeve Covered Placket Blouse for USD 61.99.`.
*   `type` (_string_)
    
    The kind of Page Meta Tag, indicating how the storefront should render the value. Documented values are `name`, `property`, `title`, and `jsonld`:
    
    *   `name` — render as `<meta name="...">`.
    *   `property` — render as `<meta property="...">` (e.g. Open Graph tags).
    *   `title` — render as the HTML `<title>` element.
    *   `jsonld` — JSON-LD structured data, intended for rendering inside `<script type="application/ld+json">`. The field may be absent when the kind cannot be determined. Clients should treat unknown values as opaque so additional kinds can be introduced without breaking the contract.
    
      
    Maximum length: 64. Example: `name`.

### SearchMode

A search matching approach. `semantic` is meaning-based matching; `lexical` is keyword/token-based matching.

Type: `string`.

Allowed values: `semantic`, `lexical`. Example: `semantic`.

### ProcessedQuery

The result of query processing.

*   `query` (_query_)
*   `appliedProcessors` (_array of AppliedProcessor_) The processors that were executed for the search query and their results.  
    Maximum items: 5.

### ProductSearchRefinement

Document representing a product search refinement attribute.

*   `attributeId` (_string_, required) The ID of the search refinement attribute. In the case of an attribute refinement, this is the attribute ID. Custom attributes are marked by the prefix "c\_" (for example, "c\_refinementColor"). In the case of a category refinement, the ID must be "cgid". In the case of a price refinement, the ID must be "price".  
    Minimum length: 1. Maximum length: 256. Example: `refinementColor`.
*   `label` (_string_) The localized label of the refinement.  
    Maximum length: 256. Example: `Color`.
*   `values` (_array of ProductSearchRefinementValue_) The sorted array of refinement values. This array can be empty.

### Suggestion

Document representing a suggestion.

*   `suggestedPhrases` (_array of SuggestedPhrase_) A list of suggested phrases. This list can be empty.
*   `suggestedTerms` (_array of SuggestedTerms_, required) A list of suggested terms. This list can be empty.  
    Minimum length: 1.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ProductSearchSortingOption

Document representing a product search sorting option.

*   `id` (_string_, required) The ID of the sorting option.  
    Minimum length: 1. Maximum length: 256. Example: `best-matches`.
*   `label` (_string_, required) The localized label of the sorting option.  
    Minimum length: 1. Maximum length: 4000. Example: `Best Matches`.

### BrandSuggestions

The suggested brand names are listed in suggested phrases. If this list is empty, no brand suggestion for a given search phrase was found.

Includes all fields of `Suggestion`.

### CategorySuggestions

Includes all fields of `Suggestion`.

*   `categories` (_array of SuggestedCategory_) The sorted list of suggested categories. This list can be empty.

### ProductSuggestions

Includes all fields of `Suggestion`.

*   `products` (_array of SuggestedProduct_) The sorted list of suggested products. This list can be empty.

### CustomSuggestions

The custom suggestions are listed in suggested phrases. If this list is empty, no custom suggestion for the given search phrase was found.

Includes all fields of `Suggestion`.

*   `customSuggestion` (_string_)  
    Example: `Try searching for budget shoes.`.

### EinsteinSuggestedPhrases

Einstein-suggested phrases containing popular and recent search phrases.

*   `popularSearchPhrases` (_array of SuggestedPhrase_) A list of popular search phrases suggested by Einstein. This list can be empty.  
    Maximum length: 10.
*   `recentSearchPhrases` (_array of SuggestedPhrase_) A list of recent search phrases suggested by Einstein. This list can be empty.  
    Maximum length: 10.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Image

*   `alt` (_string_)  
    Maximum length: 4000. Example: `The White Dress Shirt`.
*   `disBaseLink` (_string_)  
    Maximum length: 4000. Example: `https://edge.disstg.commercecloud.salesforce.com/dw/image/v2/ZZEU_006/on/demandware.static/-/Sites-apparel-catalog/default/dw9368b001/images/large/70284588_100_0.jpg`.
*   `link` (_string_, required)  
    Minimum length: 1. Maximum length: 4000. Example: `https://zzeu-006.sandbox.us01.dx.commercecloud.salesforce.com/on/demandware.static/-/Sites-apparel-catalog/default/dw9368b001/images/large/70284588_100_0.jpg`.
*   `title` (_string_)  
    Maximum length: 4000. Example: `The White Dress Shirt`.

### ProductType

Document representing a product type.

*   `bundle` (_boolean_) A flag indicating whether the product is a bundle.  
    Example: `true`.
*   `item` (_boolean_) A flag indicating whether the product is a standard item.  
    Example: `true`.
*   `master` (_boolean_) A flag indicating whether the product is a master.  
    Example: `true`.
*   `option` (_boolean_) A flag indicating whether the product is an option.  
    Example: `true`.
*   `set` (_boolean_) A flag indicating whether the product is a set.  
    Example: `true`.
*   `variant` (_boolean_) A flag indicating whether the product is a variant.  
    Example: `true`.
*   `variationGroup` (_boolean_) A flag indicating whether the product is a variation group.  
    Example: `true`.

### ProductRef

Document representing a product reference.

*   `id` (_string_, required) The ID of the product reference.  
    Minimum length: 1. Maximum length: 100. Example: `74974310`.

### VariationAttribute

Document representing a variation attribute.

*   `id` (_string_, required) The ID of the variation attribute.  
    Minimum length: 1. Maximum length: 256. Example: `size`.
*   `name` (_string_) The localized display name of the variation attribute.  
    Maximum length: 4000. Example: `size`.
*   `values` (_array of VariationAttributeValue_) The sorted array of variation values. This array can be empty.

### ImageGroup

Document representing an image group containing a list of images for a particular view type and an optional variation value.

*   `images` (_array of Image_, required) The images of the image group.  
    Minimum length: 1.
*   `variationAttributes` (_array of VariationAttribute_) Returns a list of variation attributes applying to this image group.
*   `viewType` (_string_, required) The image view type.  
    Minimum length: 1. Maximum length: 256. Example: `hi-res`.

### PriceRange

Document representing price ranges for a product which happens to be a master product (per Pricebook)

*   `maxPrice` (_number (double)_) Maximum price for the given pricebook (usually for a master Product would be the price for the Variant which has the highest price out of all Variants in that pricebook)  
    Example: `10.89`.
*   `minPrice` (_number (double)_) Minimum price for the given pricebook (usually for a master Product would be the price for the Variant which has the least price out of all Variants in that pricebook)  
    Example: `10.89`.
*   `pricebook` (_string_) The active pricebook from which the min and the max prices are calculated. The pricebook is based on the site context of the request as defined in ECOM.  
    Maximum length: 256. Example: `usd-list-pricebook`.

### ProductPromotion

Document representing a product promotion.

*   `calloutMsg` (_string_, required) The localized call-out message of the promotion.  
    Minimum length: 1. Maximum length: 4000. Example: `Fantastic promotion`.
*   `promotionId` (_string_, required) The unique ID of the promotion.  
    Minimum length: 1. Maximum length: 260. Example: `summerSale`.
*   `promotionalPrice` (_number (double)_, required) The promotional price for this product.  
    Minimum length: 1. Example: `12.99`.

### ProductPriceTable

Tiered Price Level Object

*   `price` (_number (double)_) Price for the product for the specified tier for the specified pricebook  
    Example: `12.99`.
*   `pricebook` (_string_) The active pricebook for which this price is defined  
    Maximum length: 256. Example: `usd-list-pricebook`.
*   `quantity` (_number (double)_) Quantity tier for which the price is defined.  
    Example: `1`.

### Variant

A product which is a variation within a master product that describes different colors, sizes, or other variation attributes. _Has a SKU._

*   `orderable` (_boolean_) A flag indicating whether the variant is orderable.  
    Example: `true`.
*   `price` (_number (double)_) The sales price of the variant.  
    Example: `25.99`.
*   `productId` (_string_, required) The ID (SKU) of the variant.  
    Minimum length: 1. Maximum length: 100. Example: `8W4756834`.
*   `tieredPrices` (_array of ProductPriceTable_) List of tiered prices if the product is a variant
*   `variationValues` (_object_) The actual variation attribute ID - value pairs.
    
    Additional properties: `string`.
    
    Maximum length: 4000. Example: `Beige`.
    
*   `productPromotions` (_array of ProductPromotion_) The array of active customer product promotions for this product. This array can be empty. Coupon promotions are not returned in this array.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### VariationGroup

Representation of a group of variant products by an attribute. This can't be purchased by a shopper. It provides inheritable attributes for its product variants and is used for navigation. A VariationGroup doesn't have a SKU.

*   `orderable` (_boolean_, required) A flag indicating whether the variation group is orderable.  
    Minimum length: 1. Example: `false`.
*   `price` (_number (double)_, required) The sales price of the variation group.  
    Minimum length: 1. Example: `24.99`.
*   `productId` (_string_, required) The ID (SKU) of the variation group.  
    Minimum length: 1. Maximum length: 100. Example: `49345VG`.
*   `variationValues` (_object_, required) The actual variation attribute ID - value pairs.  
    Minimum length: 1.
    
    Minimum length: 1.
    
    Additional properties: `string`.
    
    Maximum length: 4000. Example: `Beige`.
    

### query

The query string that was searched for.

Type: `string`.

Maximum length: 50. Example: `dresses`.

### AppliedProcessor

The result of a processor execution.

*   `processorName` (_string_) The name of the processor.  
    Maximum length: 256. Example: `Attribute Aware Search`.
*   `result` (_query_)
*   `refinements` (_object_) The refinements that were applied to the query.
    
    Additional properties: `string`.
    
    Maximum length: 256. Example: `Beige`.
    

### ProductSearchRefinementValue

Document representing a product search refinement value.

*   `description` (_string_) The localized description of the refinement value.  
    Maximum length: 4000. Example: `The Beige objects`.
*   `hitCount` (_integer (int32)_, required) The number of search hits when selecting the refinement value. Can be 0.  
    Minimum length: 1. Example: `3`.
*   `label` (_string_, required) The localized label of the refinement value.  
    Minimum length: 1. Maximum length: 4000. Example: `Beige`.
*   `presentationId` (_string_) The optional presentation ID associated with the refinement value. The presentation ID can be used, for example, to associate an ID with an HTML widget.  
    Maximum length: 256. Example: `beige`.
*   `value` (_string_, required) The refinement value. In the case of an attribute refinement, this is the bucket, the attribute value, or a value range. In the case of a category refinement, this is the category ID. In the case of a price refinement, this is the price range. Ranges are enclosed by parentheses and delimited by ".."; for example, "(100..999)" and "(Aa..Fa)" are valid ranges.  
    Minimum length: 1. Maximum length: 4000. Example: `Beige`.
*   `values` (_array of ProductSearchRefinementValue_) The array of hierarchical refinement values. This array can be empty.

### SuggestedPhrase

Document representing a suggested search phrase.

*   `exactMatch` (_boolean_, required) Returns whether this suggested phrase exactly matches the user input search phrase.  
    Minimum length: 1. Example: `true`.
*   `phrase` (_string_, required) Returns the suggested search phrase.  
    Minimum length: 1. Maximum length: 50. Example: `sony`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### SuggestedTerms

Document representing a list of suggested terms for each term of a search phrase.

*   `originalTerm` (_string_, required) Returns the original term that the suggested terms relates to.  
    Minimum length: 1. Maximum length: 50. Example: `son`.
*   `terms` (_array of SuggestedTerm_) Returns the suggested terms.

### SuggestedCategory

*   `id` (_string_, required) The ID of the category.  
    Minimum length: 1. Maximum length: 260. Example: `womens-clothing-dresses`.
*   `name` (_string_, required) The localized name of the category.  
    Minimum length: 1. Maximum length: 4000. Example: `Dresses`.
*   `parentCategoryName` (_string_, required) The name of the parent category.  
    Minimum length: 1. Maximum length: 4000. Example: `Clothing`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### SuggestedProduct

Document representing a product search hit.

*   `currency` (_CurrencyCode_, required)
*   `price` (_number (double)_, required) The sales price of the product. In the case of complex products like a master or a set, this is the minimum price of related child products.  
    Minimum length: 1. Example: `300`.
*   `productId` (_string_, required) The ID (SKU) of the product.  
    Minimum length: 1. Maximum length: 100. Example: `sony-ps3-bundle`.
*   `productName` (_string_, required) The localized name of the product.  
    Minimum length: 1. Maximum length: 4000. Example: `Playstation 3 Bundle`.
*   `slug` (_string_) SEO-friendly slug for the product, derived from the site's configured product URL rule. This is the slug segment only, not a full URL. Returned only when `expand=slug` is requested. Use the slug to construct user-friendly product detail page URLs (for example, /products/{slug}/{productId}).  
    Maximum length: 4000. Example: `modern-dress-shirt`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### VariationAttributeValue

Document representing a variation attribute value.

*   `description` (_string_) The localized description of the variation value.  
    Maximum length: 4000. Example: `Size 15R`.
*   `image` (_object_) The first product image for the configured viewtype and this variation value.
    
    Includes all fields of `Image`.
    
*   `imageSwatch` (_object_) The first product image for the configured viewtype and this variation value. Typically the swatch image.
    
    Includes all fields of `Image`.
    
*   `name` (_string_) The localized display name of the variation value.  
    Maximum length: 4000. Example: `15R`.
*   `orderable` (_boolean_) A flag indicating whether at least one variant with this variation attribute value is available to sell.  
    Example: `true`.
*   `value` (_string_, required) The actual variation value.  
    Minimum length: 1. Maximum length: 4000. Example: `15R`.

### SuggestedTerm

Document representing a suggested term.

*   `completed` (_boolean_, required) Returns whether this term value is a completion match.  
    Minimum length: 1. Example: `true`.
*   `corrected` (_boolean_, required) Returns whether this term value is a correction match.  
    Minimum length: 1. Example: `false`.
*   `exactMatch` (_boolean_, required) Returns whether this term value is a exact match.  
    Minimum length: 1. Example: `false`.
*   `value` (_string_, required) Returns the term value.  
    Minimum length: 1. Maximum length: 50. Example: `sony`.

<!-- document id=15256de95c396bbb6c903e2128ef3877059f977c820561d2d7de22bb84e74195 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-seo.md -->

Shopper SEO

# Shopper SEO

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-seo/shopper-seo-oas-v1-public.yaml)

## API Overview

The Shopper SEO API Provides access to SEO-related information, such as URL mapping information.

### Authentication & Authorization

The Shopper SEO API requires a shopper access token from the [Shopper Login and API Access Service (SLAS).](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html)

You must include the relevant scope(s) in the client ID used to generate the SLAS token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

### Customization

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Caching is provided for this API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Resolve a URL

Resolve a URL path to its resource type (product, category, or content page).

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/site/shopper-seo/v1/organizations/{organizationId}/url-mapping?urlSegment=new-arrivals-tops&siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### URL Resolution

For information on setting up URL rules and URL redirects in Business Manager, see [URL Resolution.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-resolution.html)

### Related APIs

*   [SEO (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/seo?meta=Summary) — Manage SEO URL rules and redirects.

**Version:** 1.3.1

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/site/shopper-seo/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-seo: Allows read operations on shopper seo.
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-seo: Allows read operations on shopper seo.
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-seo: Allows read operations on shopper seo.

## Operations

### GET Get URL mapping information for a URL segment.

`GET /organizations/{organizationId}/url-mapping`

Operation ID: `getUrlMapping`. Security: ShopperToken (sfcc.shopper-seo); ShopperClientContextToken (sfcc.shopper-seo).

The mapping information is based on URL rules and redirects that are set up in Business Manager. For more information about prerequisites and sample usage, see [URL Resolution](/docs/commerce/commerce-api/guide/url-resolution.html). You can customize the behavior of this endpoint by using hooks. For details, refer to the [Hook List](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook_list.html).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `urlSegment` (query, string, required) The part of the requested URL that comes after the domain name. For example, the urlSegment for "www.abc.com/blue/new-arrivals/tops" is "blue/new-arrivals/tops". There's no limit on the length of the urlSegment. However, for this endpoint, the maximum allowed length of the URL (after URL encoding) is 2047 characters. Make this field URL-encoded so that it properly handles special values such as whitespace. If a urlSegment includes a query string, a 404 error code is returned.  
    Minimum length: 1. Maximum length: 2047. Example: `mens/clothing/shorts`.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string)
    
    Controls whether personalization is applied to the response. Set to `none` to opt out of personalized response handling so the response is safe to cache at the CDN layer.
    
    When set to `none`, the server skips applying personalization to the response.
    
    Setting `personalized=none` is necessary but not sufficient for CDN caching: a response is only cached when the endpoint is also cacheable in the [server-side web-tier cache](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html), subject to its TTLs and invalidation. A call that is uncacheable in the web tier is not cached at the CDN either. See [CDN caching](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-caching.html).
    
      
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Returns URL mapping information for a URL that a shopper entered or selected.
    
    Media type: `application/json`. Schema: `UrlMapping`.
    
    _Example: UrlMappingCategory_ URL mapped to a category with refinements.
    
    ```
    {
      "resourceType": "CATEGORY",
      "resourceId": "new-arrivals-tops",
      "refinements": {
        "refinementColor": "Blue"
      }
    }
    ```
    
    _Example: UrlMappingProduct_ URL mapped to a product.
    
    ```
    {
      "resourceType": "PRODUCT",
      "resourceId": "25695327M"
    }
    ```
    
    _Example: UrlMappingContentAsset_ URL mapped to a content asset.
    
    ```
    {
      "resourceType": "CONTENT_ASSET",
      "resourceId": "about-us"
    }
    ```
    
*   **400** The locale is invalid. Make sure you provide a locale using the correct format: ISO 639-1 for the language code and ISO 3166-1 for the country code. For example, en-US.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getUrlMapping400_
    
    ```
    {
      "title": "Unknown Locale",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unknown-locale",
      "detail": "The locale 'ab-CD' is unknown.",
      "locale": "ab-CD"
    }
    ```
    
*   **401** The user making the call isn't authorized to make this request. For example, the correct scope wasn't added to an SLAS API Client or the access token is invalid or missing.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getUrlMapping401_
    
    ```
    {
      "title": "Invalid Access Token",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token",
      "detail": "The request is unauthorized, the access token is invalid.",
      "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp"
    }
    ```
    
*   **404** No mapping information for the requested URL exists because there's no corresponding URL rule in Business Manager.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: getUrlMapping404_
    
    ```
    {
      "title": "Seo Url Mapping Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/seo-url-mapping-not-found",
      "detail": "black/mens/accessories/luggage",
      "urlSegment": "black/mens/accessories/luggage",
      "locale": "en_US"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### UrlMapping

The URL mapping information for a URL that a shopper clicked or typed in.

*   `resourceType` (_string_) The type of resource that corresponds to the requested URL. If you set up a URL redirect in Business Manager, resourceType returns the corresponding destination type value from the redirect. If there's a URI redirect, resourceType isn't returned. The URL redirect feature is available from B2C Commerce version 24.3.  
    Allowed values: `CATEGORY`, `PRODUCT`, `CONTENT_ASSET`. Minimum length: 1. Maximum length: 256. Example: `CATEGORY`.
*   `resourceSubType` (_string_) If the resourceType is CONTENT\_ASSET, this field tells you whether the resource is a standard content asset or a Page Designer content asset. This output is available from B2C Commerce version 24.2.  
    Allowed values: `STANDARD_CONTENT_ASSET`, `PAGE_DESIGNER_CONTENT_ASSET`. Minimum length: 1. Maximum length: 256. Example: `STANDARD_CONTENT_ASSET`.
*   `resourceId` (_string_) The identifier for the resource that corresponds to the requested URL. If you set up a URL redirect in Business Manager, resourceId returns the corresponding destination ID value from the redirect. If there's a URI redirect, resourceId isn't returned. The URL redirect feature is available from B2C Commerce version 24.3.  
    Minimum length: 1. Maximum length: 256. Example: `mens-clothing-shorts`.
*   `refinements` (_object_) The refinement filters that correspond to the URL and resourceType. Refinements are returned only if all of these conditions are met - a) the resourceType is CATEGORY, b) refinements are included in the urlSegment, and c) the refinements are configured in Business Manager. This field returns a key-value pair of refinement name and refinement value. If there’s a matching URL redirect for the requested URL. the refinements output isn’t returned. The URL redirect feature is available from B2C Commerce version 24.3.
*   `statusCode` (_integer (int32)_) This field is populated only if you set up a URL redirect in Business Manager. It specifies whether the redirect is temporary (302 or 307) or permanent (301). See [Create a Redirect from a B2C Commerce URL.](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5) This parameter is available from B2C Commerce version 24.3.  
    Example: `301`.
*   `destinationUrl` (_string_) This field is populated if the urlSegment resolves to a redirect. Specifies the URL you want to redirect to as an absolute or relative URL. The destinationUrl is based on your configuration in Business Manager. It's either a calculated value indicating the Commerce Cloud object (product, category, or content asset) URL or your specified URL. Note that an object's path may not necessarily match your headless storefront URLs but can be used as a reference for calculating the destinationUrl. See [Create a Redirect from a B2C Commerce URL.](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5). Available from B2C Commerce 24.3.  
    Minimum length: 1. Maximum length: 2048. Example: `mens/clothing/shorts`.
*   `copySourceParams` (_boolean_) This field is populated only if you set up a URL redirect in Business Manager. It’s a flag that shows whether the parameters of the source URL have been copied to the destination URL. This parameter is available from B2C Commerce version 24.3.  
    Example: `true`.
*   `additionalUrlParams` (_string_) This field is populated only if you set up a URL redirect in Business Manager. It returns the parameters you want to add to the end of the URL. This parameter is available from B2C Commerce version 24.3.  
    Minimum length: 1. Maximum length: 2048. Example: `&cgid=womens-accessories-scarves&prefn1=displaySize`.
*   `productCategoryId` (_string_) This field is populated only if you set up a URL redirect in Business Manager. It identifies the destination product's category ID. This field is returned only when the destination type is product. This parameter is available from B2C Commerce version 24.3.  
    Minimum length: 1. Maximum length: 256.
*   `onlineFrom` (_string (date-time)_, nullable) The date and time from which the URL redirect is active. If null, the redirect has no start date constraint. This field is populated only if you set up a URL redirect in Business Manager. This parameter is available from B2C Commerce version 26.8.  
    Example: `2025-06-01T00:00:00.000Z`.
*   `onlineTo` (_string (date-time)_, nullable) The date and time until which the URL redirect is active. If null, the redirect has no end date constraint. This field is populated only if you set up a URL redirect in Business Manager. This parameter is available from B2C Commerce version 26.8.  
    Example: `2025-12-31T23:59:59.000Z`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

<!-- document id=71f1b12b6459c158ec0ae2ac0453a68b3d8ed8e62e545206b54f6caa5d6715f8 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-stores.md -->

Shopper Stores

# Shopper Stores

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-stores/shopper-stores-oas-v1-public.yaml)

## API Overview

Use this API to access stores via search or ID lookup.

### Authentication & Authorization

The Shopper Stores API requires a shopper access token from the [Shopper Login and API Access Service (SLAS).](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html)

You must include `sfcc.shopper-stores` and other relevant scope(s) in the client ID used to generate the SLAS token. For a full list of permissions, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Request Details

#### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### Response Details

#### Personalization

Responses from this API can be personalized using the [Shopper Context API.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) By setting context attributes such as customer group, source code, or store ID, you can retrieve personalized promotions, pricing, and shipping methods. For details on how personalization interacts with caching, see [Personalized Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html#personalized-caching)

#### Caching

Caching is provided for the Shopper Stores API. For details, see [Server-Side Web-Tier Caching.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Search Stores by Location

Find stores within a radius of a geographic coordinate.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/store/shopper-stores/v1/organizations/{organizationId}/store-search?latitude=37.7749&longitude=-122.4194&distanceUnit=mi&maxDistance=25&siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

#### Store Retrieval

*   Specific Lookup: Retrieve detailed information for one or more stores using unique IDs.
*   Localization: Fetch store data tailored to specific languages and regional formats using locale.

#### Location-Based Search

*   Proximity Search: Find stores within a specific radius (miles or kilometers) of a shopper.
*   Coordinate Search: Locate stores using precise latitude and longitude pairs.
*   Postal Code Search: Identify stores near a specific zip or postal code using automated geolocation mapping.

#### Search Optimization

*   Threshold Filtering: Limit results to a maximum distance from the shopper's location.
*   Pagination: Manage large result sets efficiently using limit and offset parameters.

### Related APIs

*   [Stores (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/stores?meta=Summary) — Manage store records and attributes.

**Version:** 1.4.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/store/shopper-stores/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-stores: Allows read operations on shopper-stores
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-stores: Allows read operations on shopper-stores
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-stores: Allows read operations on shopper-stores

## Operations

### GET Return stores identified by the IDs provided as input.

`GET /organizations/{organizationId}/stores`

Operation ID: `getStores`. Security: ShopperToken (sfcc.shopper-stores, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-stores, sfcc.shopper-standard).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `ids` (query, string, required) The IDs of a requested stores (comma separated, max 50 IDs).  
    Minimum length: 1. Maximum length: 256.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Returned details for specific stores.
    
    Media type: `application/json`. Schema: `StoreResult`.
    
    _Example: StoresResult_
    
    ```
    {
      "data": [
        {
          "address1": "1487 Bay St",
          "city": "Springfield",
          "countryCode": "US",
          "distance": 147.03,
          "distanceUnit": "km",
          "id": "store9",
          "name": "Springfield Media Store",
          "phone": "+1-413-413-6916",
          "posEnabled": false,
          "postalCode": "01109",
          "stateCode": "MA",
          "storeEvents": "Here are some store events.",
          "storeHours": "Here are the store hours",
          "storeLocatorEnabled": true
        },
        {
          "address1": "70 Wood Ave",
          "city": "Bridgeport",
          "countryCode": "US",
          "distance": 198.36,
          "distanceUnit": "km",
          "email": "store1@company.com",
          "id": "store11",
          "name": "Electronics Super Store",
          "phone": "+1-203-965-7014",
          "posEnabled": false,
          "postalCode": "06605",
          "stateCode": "CT",
          "storeLocatorEnabled": true
        },
        {
          "address1": "239 Bridge St",
          "city": "Manchester",
          "countryCode": "US",
          "distance": 219,
          "distanceUnit": "km",
          "id": "store8",
          "name": "Gardena Mart",
          "phone": "+1-603-715-9773",
          "posEnabled": false,
          "postalCode": "03104",
          "stateCode": "NH",
          "storeLocatorEnabled": true
        },
        {
          "address1": "150 Winthrop Ave",
          "city": "Lawrence",
          "countryCode": "US",
          "distance": 242.77,
          "distanceUnit": "km",
          "id": "store6",
          "name": "Khale Street Electronics",
          "phone": "+1-978-580-2704",
          "posEnabled": false,
          "postalCode": "01843",
          "stateCode": "MA",
          "storeLocatorEnabled": true
        },
        {
          "address1": "110 Smith St",
          "city": "Providence",
          "countryCode": "US",
          "distance": 245.02,
          "distanceUnit": "km",
          "email": "store2@company.com",
          "id": "store2",
          "name": "Super Electronics",
          "phone": "+1-401-312-6284",
          "posEnabled": false,
          "postalCode": "02903",
          "stateCode": "RI",
          "storeLocatorEnabled": true
        }
      ],
      "limit": 5,
      "total": 12
    }
    ```
    
*   **400** A value constraint for query parameters was violated. Or, a combination of latitude and longitude, a combination of country code and postal code, or an invalid distance\_unit was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MissingIds400_
    
    ```
    {
      "detail": "Missing required query parameter(s): 'ids'",
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-query-parameter"
    }
    ```
    

### GET Retrieve a list of stores for the given site that are within a configured distance of a geolocation.

`GET /organizations/{organizationId}/store-search`

Operation ID: `searchStores`. Security: ShopperToken (sfcc.shopper-stores, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-stores, sfcc.shopper-standard).

*   The distance is interpreted either in miles or kilometers, depending on the `distanceUnit` input parameter.
    
*   The location is specified by either directly providing a latitude and longitude coordinate pair, or by providing a country and a postal code. If a postal code is passed, the resource looks in the system's geolocation mappings in Business Manager to find the coordinates for this postal code. If no matching geolocation is found, the resource returns an empty list of stores. If coordinates are passed, the values for country and postal code are ignored.
    
    To verify site latitude and longitude information in Business Manager:
    
    *   Navigate to **Merchant Tools -> Online Marketing -> Stores**.
    *   Select the applicable site.
    *   In the **Address** tab, verify that valid information is provided in the following fields: **Address**, **City**, **Postal Code**, **State**, and **Country**. For latitude and longitude values, you can manually enter values or provide all field values to auto-populate **Latitude** and **Longitude**. You must provide valid values for all of the previous fields for latitude and longitude to auto-populate **Latitude** and **Longitude** values.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `countryCode` (query, CountryCode) The two letter ISO country code, such as "US". This value is required when a postalCode is provided.
*   `distanceUnit` (query, DistanceUnit) The distance unit. Supported values are "mi" (miles) and "km" (kilometers). The default is "km".
*   `latitude` (query, Latitude) The geographical latitude to search for stores (value range -90.00 .. 90.00). This value is required when a longitude is provided.
*   `longitude` (query, Longitude) The geographical longitude to search for stores (value range -180.00 .. 180.00). You must provide a longitude when a latitude is provided.
*   `maxDistance` (query, Distance) The area (radius) in distanceUnit where stores will be searched.
*   `postalCode` (query, PostalCode) The postal code, such as "84121". You must provide a countryCode when a postalCode is provided.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Returned a list of stores for the given search parameters, up to the paging size, including their distance from the given geolocation and additional information on the pagination of objects.
    
    Media type: `application/json`. Schema: `Stores`.
    
    _Example: StoreSearchResult_
    
    ```
    {
      "data": [
        {
          "address1": "1487 Bay St",
          "city": "Springfield",
          "countryCode": "US",
          "distance": 147.03,
          "distanceUnit": "km",
          "id": "store9",
          "name": "Springfield Media Store",
          "phone": "+1-413-413-6916",
          "posEnabled": false,
          "postalCode": "01109",
          "stateCode": "MA",
          "storeEvents": "Here are some store events.",
          "storeHours": "Here are the store hours",
          "storeLocatorEnabled": true
        },
        {
          "address1": "70 Wood Ave",
          "city": "Bridgeport",
          "countryCode": "US",
          "distance": 198.36,
          "distanceUnit": "km",
          "email": "store1@company.com",
          "id": "store11",
          "name": "Electronics Super Store",
          "phone": "+1-203-965-7014",
          "posEnabled": false,
          "postalCode": "06605",
          "stateCode": "CT",
          "storeLocatorEnabled": true
        },
        {
          "address1": "239 Bridge St",
          "city": "Manchester",
          "countryCode": "US",
          "distance": 219,
          "distanceUnit": "km",
          "id": "store8",
          "name": "Gardena Mart",
          "phone": "+1-603-715-9773",
          "posEnabled": false,
          "postalCode": "03104",
          "stateCode": "NH",
          "storeLocatorEnabled": true
        },
        {
          "address1": "150 Winthrop Ave",
          "city": "Lawrence",
          "countryCode": "US",
          "distance": 242.77,
          "distanceUnit": "km",
          "id": "store6",
          "name": "Khale Street Electronics",
          "phone": "+1-978-580-2704",
          "posEnabled": false,
          "postalCode": "01843",
          "stateCode": "MA",
          "storeLocatorEnabled": true
        },
        {
          "address1": "110 Smith St",
          "city": "Providence",
          "countryCode": "US",
          "distance": 245.02,
          "distanceUnit": "km",
          "email": "store2@company.com",
          "id": "store2",
          "name": "Super Electronics",
          "phone": "+1-401-312-6284",
          "posEnabled": false,
          "postalCode": "02903",
          "stateCode": "RI",
          "storeLocatorEnabled": true
        }
      ],
      "limit": 5,
      "offset": 0,
      "total": 12
    }
    ```
    
*   **400** A value constraint for query parameters was violated. Or, a combination of latitude and longitude, a combination of country code and postal code, or an invalid distance\_unit was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MissingPostalCode400_
    
    ```
    {
      "title": "Missing Postal Code",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/missing-postal-code",
      "detail": "The input parameter 'postal_code' is required when no coordinates are provided."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### StoreResult

Result object containing an array of stores.

Includes all fields of `ResultBase`.

*   `data` (_array of Store_) The list of stores in the search result.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### DistanceUnit

The unit the distance attribute is measured in (either in miles or kilometers).

Type: `string`.

Allowed values: `km`, `mi`.

### Latitude

The latitude of the store.

Type: `number (double)`.

Minimum: -90. Maximum: 90.

### Longitude

The longitude of the store.

Type: `number (double)`.

Minimum: -180. Maximum: 180.

### Distance

The distance to the given geolocation where the stores will be searched, using the unit given in the attribute 'DistanceUnit' (miles or kilometers).

Type: `number (double)`.

Minimum: 0. Maximum: 20012.

### PostalCode

The postal code of the store.

Type: `string`.

Minimum length: 3. Maximum length: 10.

### Stores

Result object containing an paginated array of stores.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Store_) The list of stores in the search result.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Store

Document representing a store.

*   `address1` (_string_) The primary address of the store.  
    Minimum length: 1.
*   `address2` (_string_) The secondary address of the store.
*   `city` (_string_) The city of the store.
*   `countryCode` (_CountryCode_)
*   `distance` (_Distance_)
*   `distanceUnit` (_DistanceUnit_)
*   `email` (_string_) The email address of the store.
*   `fax` (_string_) The fax number of the store.
*   `id` (_string_, required) The id of the store.  
    Minimum length: 1. Maximum length: 256.
*   `image` (_string_) The store image.
*   `inventoryId` (_string_) The inventory list id associated with this store.  
    Maximum length: 256.
*   `latitude` (_Latitude_)
*   `longitude` (_Longitude_)
*   `name` (_string_) The store name.
*   `phone` (_string_) The phone number of the store.
*   `posEnabled` (_boolean_) Whether this store uses Store Point-of-Sale.
*   `postalCode` (_object_) The postal code of the store.
    
    Includes all fields of `PostalCode`.
    
*   `stateCode` (_string_) The state code of the store.
*   `storeEvents` (_string_) The store events.
*   `storeHours` (_string_) The opening hours of the store.
*   `storeLocatorEnabled` (_boolean_) Whether this store should show up in store locator results.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

<!-- document id=d37b59ce0507731792495b9885c2343791869f459293f4e12baad5cb22c145a2 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-cart-cleanup.md -->

# Simplified Cart Cleanup

As of Spring ’25 (API version 63.0), customers can modify a cart during the checkout process without canceling and restarting the checkout. This feature applies to LWR stores with the [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.htm) enabled.

## Previous Limitations

Previously, any change to a cart with the status of `Checkout` canceled the current checkout session and set the status to `Active`. Buyers had to go back to cart, make their adjustments, and initiate checkout again. This behavior was time-consuming and prevented options like editing cart item quantities from being offered on checkout screens.

**note:** If needed, you can revert your store to the previous behavior. To disable simplified cart cleanup, contact Salesforce customer support or your account representative.

## Cart and Checkout API Impact

With simplified cart cleanup, when a customer modifies their cart, the Cart Calculate API performs checkout calculations like shipping and taxes based on the new cart contents. The cart status can remain in `Checkout` rather than reverting back to `Active`. This adjustment keeps the checkout flow uninterrupted and leads to a smoother transaction.

You can also call the [Salesforce Commerce Cart Connect APIs](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-cart-apis.htm) without canceling checkout. For example, make a PATCH or DELETE request to the [Commerce Webstore Cart Item](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_item.htm) resource to update or delete an item from a cart in checkout.

To support coupons in checkout, we previously introduced the Commerce Webstore Checkout Coupon resources for [POST](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupons.htm) and [DELETE](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupon_delete.htm) requests. Now, you can use the Commerce Webstore Cart Coupon resources for [POST](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons.htm) and [DELETE](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons_delete_coupon.htm) requests instead. We plan to remove the Commerce Webstore Checkout Coupon resources in API version 65.0.

If simplified cart cleanup is enabled, POST requests to the [Commerce Webstore Cart, Arrange Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_arrange_items.htm) resource and DELETE requests to the [Commerce Webstore Cart Delivery Group](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_delivery_group.htm) resource return new status codes. Previously, successful POST requests returned 201 and successful DELETE requests returned 204 in the response header. Now, these requests return 202.

The [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm) resource remains fully supported. If needed, you can still cancel a checkout using a DELETE request.

| Resource                                                                                                                                                                               | Method        | Behavior with simplified cart cleanup enabled (API version 63.0 and later)                                                                                                                                      |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                        | POST          | Add an item to a cart without canceling checkout.                                                                                                                                                               |
| [Commerce Webstore Cart Item](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_item.htm)                          | PATCH, DELETE | Update or delete an item in a cart without canceling checkout.                                                                                                                                                  |
| [Commerce Webstore Cart Coupons](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons.htm)              | POST          | Apply a coupon to a cart without canceling checkout.                                                                                                                                                            |
| [Commerce Webstore Cart Coupon](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons_delete_coupon.htm) | DELETE        | Remove a coupon from a cart without canceling checkout.                                                                                                                                                         |
| [Commerce Webstore Cart, Arrange Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_arrange_items.htm)       | POST          | Arrange cart items into delivery groups without canceling checkout. Successful requests return 202.                                                                                                             |
| [Commerce Webstore Cart Delivery Groups](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_delivery_groups.htm)    | POST          | Create a collection of delivery groups in a cart without canceling checkout.                                                                                                                                    |
| [Commerce Webstore Cart Delivery Group](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_delivery_group.htm)      | PATCH, DELETE | Update or delete a delivery group in a cart without canceling checkout. Successful DELETE requests return 202.                                                                                                  |
| [Commerce Webstore Checkout Coupons](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupons.htm)                     | POST          | Deprecated. Use [Commerce Webstore Cart Coupons](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons.htm) instead.              |
| [Commerce Webstore Checkout Coupon, Delete](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_coupon_delete.htm)        | DELETE        | Deprecated. Use [Commerce Webstore Cart Coupon](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons_delete_coupon.htm) instead. |

<!-- document id=54b6248aba4543d045b57e4cd29857b1637bb05602f69ba81ed7efa83f03d33e url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/single-use-promotion-code.md -->

# Single-Use Promotion Code

Configure and set up single-use promotion codes (SUPC) in Point of Sale CMS.

Salesforce supports SUPC validation outside the Point of Sale Promotion Engine through an SPI. If a code is entered in the Point of Sale app, the code is first checked in the Point of Sale system. If the code isn't found, it is checked in the merchant's external system. See [Create Promotions in Point of Sale CMS](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_modules_promotions.htm&type=5) in _Salesforce Help_.

## Prerequisites

- Modern POS App Build: 10.3.1 or greater
- Platform Support: iPad & iPhone
- Offline Support: no

## Configure Point of Sale CMS for SPI SUPC

1. In CMS, go to **Integrations** | **Custom Connectors**.

2. Click **Create**.

3. For Connector Type, select **SPI**.

4. For Endpoint Name, select **SUPC_PROMOTION_CODE_VALIDATION**.

5. For API Endpoint, provide the external endpoint for validating SUPCs.

6. For Integration Type, select **HTTP_POST**.

7. Specify any JSON headers that must be passed.

8. Configure the rest of the fields for the SPI. See [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

9. Save your changes. ![The SUPC settings in Point of Sale CMS.](https://developer.salesforce.com/docs/media/retail-cloud/rt-cms-modules-supc-in-cms.png)

<!-- document id=22d130db09e03dc62c3114da633ac7b30bcc1dc56e97aaa5aee6d1fc95dde595 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-performance/b2c-site-performance.md -->

# Site Performance

Front-end site performance refers to the time it takes to load a page in the browser, which impacts customers' first impression of your site and shopping experience. Front-end site performance can directly increase or decrease your site traffic and sales.

**important:** This information focuses on front-end Store Front Reference Architecture (SFRA) performance. For Composable Storefront performance guidance, see [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.html). For B2C Commerce API (SCAPI) guidance, see [SCAPI Performance](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html).

## Front-End Page Loading

The browser consumes most of the time needed for loading a page. The server requires only a small fraction of the total time required to load the page.

For example, when Google slowed their site 500 ms for a user test, it caused a 20% drop in traffic. Greg Linden of Amazon said that in A/B tests, redesigning a page so that it was 100 ms slower caused a 1% drop in sales.

Front-end performance is influenced by:

- JavaScript
- CSS
- Images
- Flash files
- HTTP request count
- Page complexity and size
- Whether pages are cached

Here's what happens when a page is rendered:

1.  Entering a URL in a browser triggers an HTTP request.
2.  The server builds the page and sends it back to the browser.
3.  The browser parses the DOM tree into memory.
4.  The browser resolves the components of the page: JavaScript, CSS, images, and AJAX.

    **note:** The browser must have the DOM tree and CSS information before it starts rendering. Everything that is JavaScript and defined in the header must be loaded first. Flash files also trigger reload operations.

![Page Rendering Process](https://developer.salesforce.com/media/b2c-commerce/b2c_site_performance_site_performance.gif)

Follow these basic guidelines:

- The browser needs the CSS information before it can begin rendering. Therefore, if you include the CSS information, whether inline or external, at the beginning of the page, the page renders faster.
- All JavaScript in the header must be loaded first. If you include the JavaScript at the end of the file, the page appears to load faster. When JavaScript is at the end of the file, the page doesn't complete rendering faster, but it appears to load faster, because parts of the page can begin to render sooner.
- Because Flash files can trigger reload operations, it is better to put them before JavaScript, but after the rest of the page.

![Optimal HTML Structure and Order](https://developer.salesforce.com/media/b2c-commerce/b2c_site_performance_site_performance_page_positioning.gif)

## Tools for Improving Site Performance

Use a tool to view the loading operations of a page and determine how long the page takes to load. Use this tool to improve performance by identifying what is causing a page to be slow.

There are several Firefox Add-ons recommended for assessing and improving front-end performance:

- Web Developer Toolbar - a series of web developer tools
- Fiddler Everywhere - use as an HTTP Debugging Proxy to log HTTP traffic.
- YSlow! - use to analyze web pages to determine performance improvements.
- WebPagetest - a helpful performance testing tool that details specific changes to caching and image compression, along with other metrics.

Use Code Profiler, which is included with Salesforce B2C Commerce, to assess your storefront performance.

### Use Code Profiler

The Code Profiler provides insight into run-time performance. There are three Code Profiler modes that provide different levels of detail.

- Production Mode - This mode measures run-time behavior for a subset of requests and provides an aggregated view for systems even under load. This mode is the default for non-sandbox instances and can't be deactivated. Using the Code Profiler in this mode has minimal performance impact.
- Development Mode - This mode measures run-time behavior for all requests of the system and provides detailed data broken down per request. This mode is the default for sandbox instances and can be activated for other instance types. This mode requires some run-time overhead compared to Production Mode.
- Extended Script Development Mode - This mode provides insight into script internal run-time behavior, in addition to the information that Development Mode provides. Using the Code Profiler in this mode has severe performance implications. Use with caution in production environments.

All application servers in a cluster always operate in the same Code Profiler mode. The Business Manager Code Profiler screen displays only data gathered on the application server serving the current Business Manager session.

A background job exports the Code Profiler data hourly to the file system into CSV files, which you can download. After the export, the data in the server is reset. The Code Profiler screen shows data only since the last reset.

1.  Open the storefront for the site you want to examine.

2.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Code Profiler**.

3.  Select the mode.

    - Production Mode
    - Development Mode
    - Extended Script Development Mode

      **note:** When you change modes, the results are flushed. If you are gathering data on a sandbox, you must make the behavior occur again to measure it. However, if you are gathering data on a production instance that has sufficient traffic, you might simply have to wait to see the behavior.

4.  To change what appears in the results, specify the result types to view.

    | **Result Type**    | Includes                                                                                                                                                                                                                                                                                                        |
    | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Request**        | <ul><li>ONREQUEST: onrequest calls</li><li>REST_SHOP: OCAP Shop API requests</li><li>REST_DATA: OCAPI Data API requests</li<li>REST_BATCH: OCAPI Batch API requests</li><li>REST_META: OCAPI Meta-API results</li><li>SF_PAGE: storefront page requests</li><li>PAGE_DESIGNER: Page Designer requests</li></ul> |
    | **Job**            | <ul><li>JOB: Job execution</li><li>JOB_STEP: Job steps</li></ul>                                                                                                                                                                                                                                                |
    | **Controller**     | <ul><li>SCRIPT_CONTROLLER: JavaScript controllers</li></ul>                                                                                                                                                                                                                                                     |
    | **Script details** | <ul><li>SCRIPT_API: API call</li><li>SCRIPT_FUNCTION: JavaScript functions</li><li>SCRIPT_HOOK: Hook function</li><li>SCRIPT_LINE: single lines of JavaScript code</li></ul>                                                                                                                                    |
    | **View**           | ISML template rendering                                                                                                                                                                                                                                                                                         |

5.  To remove results for a result type, uncheck the box next to the filter and click **Apply**.

6.  To add result types, check the box next to the filter and click **Apply**.

7.  To sort the results table, click a column heading.

### Code Profiler Results

Code Profiler results are sorted in descending order by the sum of total elapsed times. The results provide a quick overview of where time is spent.

The table of results includes:

- Type - the kind of artifact being measured
- Name - the specific artifact being measured
- Hits - the number of invocations of the artifact that have been measured

  **note:** Because Production Mode only measures a subset of all requests, this number might not represent the total number of invocations.

- Time, which is measured in two different ways:
  - Elapsed Time - the time spent executing the given artifact
  - Wait Time - subset of Elapsed Time that isn't spent processing, such as I/O operations (database or service calls) or concurrency-related locking
- For Elapsed Time and Wait Time, there is also data to indicate:
  - Own Time - the time spent exclusively by the given measurement frame, subtracting runtimes of enclosed frames
  - Total Time - total duration between the beginning and the end of the result's execution
- For Own Time and Total time, the following is provided:

  - Sum - the total amount of all measured runtimes for the given result

    **note:** Sum times in Production Mode only represent runtimes in the measured subset of requests.

  - Average - the mean runtime given by Sum divided by Hits

## Techniques for Improving Site Performance

The following techniques improve site performance.

### Test Site Performance

Use Code Profiler to assess the performance times of artifacts that comprise your site.

When assessing site performance, or formulating a testing strategy, it’s important to include or account for:

- Cross-Network Testing

- Cross-Machine / Cross-Browser Testing

- Server-Side Performance

- Load Testing

#### Cross-Network Testing

Performance testing from internal corporate LANs doesn't accurately test the user experience over external internet access across geographies. Network performance can vary depending on whether the eCDN content delivery network has cached contents and how close a user is to the content delivery node or edge server.

It’s important to test the global network performance of one or more storefronts using available online tools (for example, [https://www.websitepulse.com/tools/website-test.](https://www.websitepulse.com/tools/) or [https://webpagetest.org/](https://webpagetest.org/) ), to determine what your end users are experiencing. These online tools help to simulate performance from several geographical locations, as well as various connection speeds, device types, and screen resolutions. The global network should include the eCDN (Cloudflare) network and all other third-party CDNs stacked outside of eCDN.

Test results indicate times for DNS lookup, connect, redirect, download times (ms) of the first byte and last byte of the page response from the selected geography. If applicable, check if it's accessible from China with this tool: [https://www.websitepulse.com/tools/china-firewall-test](https://www.websitepulse.com/tools/china-firewall-test).

It may also be helpful to gather My Traceroute (MTR) data, especially when you’re observing slowness. MTR data helps determine whether there’s a network issue. It’s recommended to review the MTR output with 25–50 cycles, or at least 15–20 traceroutes (if no MTR can be done).

#### Cross-Machine or Browser Testing

Storefronts can be accessed through different mobile device types – phones or tablets, which come in several screen sizes and a few platforms having different browsers, operating systems and screen resolutions.

B2C Commerce supported browsers for desktop and mobile are listed [Browser Support](https://help.salesforce.com/s/articleView?id=cc.b2c_business_manager_user_interface.htm&type=5) in the Infocenter. Test performance across all supported browsers with any available online tool (for example, [WebPageTest.org](https://www.webpagetest.org/)). Cross-Machine or Browser testing helps to discover front-end issues such as Javascript or network errors.

#### Server-Side Performance Testing

Use the code profiler and the CCAC dashboard to identify performance problems.

#### Load Testing

Conduct load testing to determine a system’s behavior under both normal and peak conditions.

Load Test environment options include:

1.  Loaner realm

    The load test is run against a realm that is rented solely for testing. This realm is sized to match the production realm. If the storefront isn’t live yet, the test realm is sized based on predicted target volume.

2.  Pre-Production realm

    If the customer isn't yet live, using their production instance group (PIG) is an option that allows for load testing of all expected scenarios including order placement. Resource footprint in this type test could be limited.

Regardless of which option is selected, it's important that the test realm has the same resource footprint as production does (or will) for the storefront. The customer or load test partner is responsible to prepare the loaner realm (data, code, and configuration).

It ' required that the support team is notified of load tests by opening up a support case. The support team notifies the SFCC technical operations team so that the traffic generated by the anticipated load test isn’t misconstrued as malicious and subsequently blocked. Provide the following information in the support case (ideally a week in advance of any planned load tests):

- Who is performing the test

- When the test takes place (start date, end date)

- How much traffic is expected

  - Number of visits per hour
  - Number of orders per hour

- IP addresses of load generators or data centers.

### Optimize First Pages

A first page is the page a customer sees when they access your site. The home page isn't always the first page for customers. First pages can also be a landing page, which a customer accesses through a search engine link, a partner site link, or an email link. A landing page is designed for a specific campaign, such as a product recommendation or an email blast.

Landing pages should be entirely focused on conversion. Page speed is now a landing page factor for Google Search and Ads. A faster page speed results in a better conversion rate. Increases in conversion rates have a huge impact on how much revenue the storefront generates.

#### Match Your First Page to Your Presence

Tailor the features on your first page to how your customers find you and what they need from your site.

- **One-click presence**: A site that most customers find through a search engine link, often because the site is selling a limited number of strongly branded products. Usually the products are presented on the first page and don't need an extensive search feature.

- **Affiliate-advertising presence**: A site that most customers access from partner sites, rather than a search engine link or through the home page. In this case, the landing pages from the affiliates must be fast and the home page can be larger or slower to load.

  Example: Sites selling movie merchandise that most customers find from individual movie sites. In this case, optimize multiple landing pages for customers coming from different affiliates.

**Feature-focused presence**: A site that offers a particular feature, such as a sophisticated search or Flash application, that is a focus of the customer access point. In this case, optimize all first pages to let the feature load quickly. Generally, this type of site has a loyal customer base that returns regularly to the site, ensuring that appropriate caching can help the site perform well, despite having more first page content than most sites.

#### First Page Identification

Use a web analytics tool (such as Google Analytics) to analyze your traffic to find what the top visited first pages are for your site. You could expect that your home page is the most visited first page, but instead discover that a landing page from another site or from customer emails is the most common entrance point for customers. The most visited first pages are the pages that you want to optimize.

#### First Page Page-Speed Evaluation

Evaluate first page performance with any of these or other available online tools like [PageSpeed Insights](https://developers.google.com/speed/pagespeed/insights)(PSI), or [Lighthouse, a lab tool](https://developers.google.com/web/tools/lighthouse). There are several types of metrics that are relevant to how users perceive performance. If you’re using PSI, our recommended first page performance score should be **90 or above**.

Below are important PSI metrics with recommended values for first pages:

| Metrics                        | Description                                                                                                                                                                                                                            | Desktop    | Mobile     |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---------- |
| First contentful paint (FCP)   | Measures the time from when the page starts loading to when any part of the page's content is rendered on the screen.                                                                                                                  | \<=1000 ms | \<=1500 ms |
| Largest contentful paint (LCP) | Measures the time from when the page starts loading to when the largest text block or image element is rendered on the screen.                                                                                                         | \<=1500 ms | \<=2000 ms |
| First input delay (FID)        | Measures the time from when a user first interacts with your site (for example, when they click a link, tap a button, or use a custom, JavaScript-powered control) to the time when the browser is able to respond to that interaction | \<=20 ms   | \<=50 ms   |
| Time to Interactive (TTI)      | Measures the time from when the page starts loading to when it's visually rendered, its initial scripts (if any) have loaded, and it's capable of reliably responding to user input quickly.                                           | \<=2000 ms | \<=5000 ms |
| Total blocking time (TBT)      | Measures the total amount of time between FCP and TTI where the main thread was blocked for long enough to prevent input responsiveness.                                                                                               | \<=300 ms  | \<=1000 ms |
| Cumulative layout shift (CLS)  | Measures the cumulative score of all unexpected layout shifts that occur between when the page starts loading and when its lifecycle state changes to hidden.                                                                          | \<=0.10    | \<=0.25    |

#### First Page Optimizations

Below are some important landing page design considerations for platform scalability:

- **Server-Side Performance -** Analyze and optimize the controller rendering of the first page with the [CCAC Dashboard](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-troubleshooting-platform-performance.html) Technical Reports to have an average response time \< 500 ms.

- **Calls-To-Action (CTA)**: Make sure you have one CTA and one form. Displaying multiple CTA buttons dilutes the power of your first page and could be overwhelming or confusing to site customers. A first page should have one desired action for the user to complete. A good landing page should have one message and can be short and sweet or contain a high volume of copy rallying around that message. Also, the CTA button should be large and use a color that stands out from the background of the page.

- **Page Size Optimization:** Page size is the total file size of all the resources that need to be loaded for the page to function. Page size impacts load speed of the page on a browser, and it can also have a big impact on mobile users.

  Make sure the Hi-Res images file sizes are optimized to \< 6 MB or have dimensions not exceeding 3000x3000 pixels.

  Choose the right image file type - JPEG or PNG. Generally, images with significant color variation (such as, photographs) perform better as JPEGs. PNG is ideal for simple images with defined shapes, like those with text.

  If your landing page includes a series of similar-sized images (say, for a client logo bar), shorten your load time by combining them into an image sprite, then use CSS to display specific chunks of that sprite at a time. See [Reduce URL and Page Size](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-site-performance.html?q=reduce%20url#reduce-url-and-page-size) for more information.

- **Javascripts and CSS** - Minify HTML, CSS, and Javascript to condense your code so that browsers can read it faster. Remove Render-Blocking JS and CSS. Review the JS scripts and plugins on your landing page (including header and footer templates) and decide whether they’re essential to your visitor experience. If they’re not, removing them could help cut some extra seconds off load time. See [Reduce and Reuse Scripts](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-site-performance.html?q=reuse+script#reduce-and-reuse-scripts) for more information.

- **PDP-lite Approach:** - If the landing page for a product hype-event is to the Product Details Page (PDP), consider presenting a lite-version, that is the actual PDP without the add to cart button/link made available prior to the product being made available (online). This allows for the caching of key page elements prior to product being made available to purchase, thus improving delivery performance of the page when the product is made available (and the Add to Cart button or link is made active).

  It’s important that proper segmentation of cacheable elements occurs (using remote includes) and adequate caching policy or times are applied (in general, 24 hours for most PDP elements).

- **Lazy Loading**- Lazy Load CSS Background Images, product tile images or use appropriate placeholder images - dominant color from the original image or a low quality image.Trigger the full resolution image load using Javascript events - scroll, resize, and orientationChange events in the browser.

- **Minimize HTTP Requests**- Reduce the number of HTTP requests on the first page. Reduce the number of content slots or remote includes used. Internally each content-slot \<ISSLOT> uses 2 remote includes. See [Fewer and Smaller HTTP Requests](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-site-performance.html?q=http+request#make-fewer-and-smaller-http-requests) for more information.

- **Web Services Framework** - Third-Party Service calls can have a significant performance impact on your entire site when the third-party service stops responding or is responding slowly. Avoiding content served from web services will significantly lower the page load time.

- **Page Caching**- Make sure the first page and target of a campaign is fully cached for 24 hours. It isn’t recommended to use unique parameters (such as customer IDs or email addresses) in the URLs embedded within your emails as this decreases the cache hit rate.

### Optimize General Site Pages

General site pages are any pages on your site that aren't initial access points for customers.

#### Use Progressive Rendering

By controlling the order in which components of a page load, give the impression of a faster loading page. Instant feedback from a partially rendered page or a progress bar makes the page feel faster to the customer. A blank page can seem to load more slowly, even if the total loading time for the blank page is shorter than the incrementally loaded page.

Use the following general guidelines:

- Focus on initial page rendering and then add external content via AJAX.
- Put JavaScript at the end of the page unless it's necessary for it to be at the top of the page. When the JavaScript is at the bottom, the page is loaded first and then the JavaScript is processed, which decreases the apparent load time, by making the page appear more quickly in the browser. Split the JavaScript if needed, with some at the bottom and some at the top.
- Put CSS information at the top of the page. The browser must have the CSS information before it starts rendering. Having the CSS at the top makes it possible for the page to load faster.
- To keep the customer informed and give an instant response to interaction, add progress bars. For example, if you must spend time loading a flash file, return the page and put up a progress bar for the flash file.

#### Limit Domains

Each domain included on a page costs DNS resolution time. Many pages incorporate Scene7, Akamai, Salesforce B2C Commerce, Google (for Analytics), Verisign, Trusted Dudes, or Omniture. Each domain requires a DNS lookup, which can take from 20 to 120 milliseconds.

The standard recommendation for browsers is no more than two downloads per domain. Sometimes, it makes sense to split data across domains to use concurrent downloads. However, each domain requires a DNS lookup that takes more time.

B2C Commerce offers hosting of static content via its embedded CDN, and enables that by default.

#### Avoid 301 and 302 Redirects

Avoid 301 (permanent) and 302 (temporary) redirects. These redirects are wasted HTTP requests and can prevent caching. Temporary redirects aren't cached, so the request is always issued. Permanent redirects change the behavior of search engines and therefore are usually cached.

#### Keep Pages Maintainable

As with any optimization process, there are always trade-offs. While consolidating code and removing comments can make pages faster to load, it makes them more difficult to maintain. Sometimes, it can make sense to sacrifice performance to make the site easier to maintain or extend.

#### Use Compression

B2C Commerce GZIPs all page components. This behavior is standard for all B2C Commerce production environments. All data delivered to the HTTP client is gzipped, with the exclusion of images and data for some older browsers.

#### Minimize Image Size

The image file format you use depends on the type of image (photographs vs. graphics), the size of the image, and how the image is composed (transparency or large blocks of color). In selecting or compressing your image formats, the goal is to make them as small as possible.

| File Type | Recommended For                                                                                                                                                                                                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| gif       | Most graphics. gif files have higher compression rates than GIF and support true colors and alpha-transparency.                                                                                                                                                                                                 |
| GIF       | Graphics that have large blocks of color. GIF is also recommended for graphics that require transparency that must be shown in Internet Explorer 6. Internet Explorer 6 doesn't allow transparency for gif files. While there are tweaks to address this issue, the tweaks can cause more performance overhead. |
| gif       | Photographs.                                                                                                                                                                                                                                                                                                    |

Many graphics or web publishing tools add information (EXIF-information) to graphics files to make it easier to store and sort them. However, this extra information makes the files larger than they would otherwise be. Use tools to strip any additional information included in the image by the digital camera or the image-processing software.

#### Reduce and Reuse CSS

B2C Commerce has the following recommendations for optimizing CSS use in your browser:

- Include inline CSS or references to external CSS files at the top of the page.
- Make CSS files external rather than inline to reuse the CSS more effectively.
- Only have one CSS file. One file is smaller than 10 compressed files. The disadvantage of having a single file is that the CSS file is less reusable and more difficult to maintain than multiple files.
- Don't duplicate CSS.
- Use page types and CSS cascading correctly. Correctly using cascading eliminates lot of unnecessary CSS code for the browser to process.
- Remove unused or redundant code from CSS files. Avoid unnecessary styles or media types.
- Avoid CSS expressions.
- Remove any non-standard CSS intended for Internet Explorer, such as JavaScript in CSS.

#### Use a Content Delivery Network

Content delivery networks serve content to a browser from a server that is geographically near to them. This arrangement can substantially reduce the time to load pages. An embedded CDN comes standard with B2C Commerce. Salesforce recommends that you host as much content as possible, especially CSS and JavaScript, with a content delivery network.

**note:** There could be cross-domain scripting issues for JavaScript or Flash due to the embedded CDN security model.

Set a time to live (TTL) for static content in Business Manager. This setting is carried over to the embedded CDN or other content delivery networks.

### Make Fewer and Smaller HTTP Requests

Making fewer HTTP requests that return less content is the single most effective technique for improving front-end performance. Each HTTP request usually takes at least 10 milliseconds to send and more time to return the page. Reducing the number of HTTP requests you make is often one of the most effective ways to improve site performance.

#### Reduce the Size and Number of Cookies

Cookies are always sent with each request for the same host or domain, so reduce the size and number of cookies to make requests quicker.

#### Reduce the Number of Images

If you have many small icons, make them one image or use CSS sprites, which require only one HTTP request. Header information, corners, button, or background images can be transferred using one or two CSS sprites. The exception to this is extremely large images, which can take more time to transfer.

This approach improves performance because instead of sending 10 requests for 1 KB each, send one request for 10 KB. In the first case, the minimum amount of time to load the page is 100 ms and the second, it's 10 ms. Also, using compression (gif, jpg), the single file compressed can be smaller than 10 files compressed, further saving loading time.

#### Consider Hidden Requests Carefully

Be aware of hidden requests, such as using `@import` statements in CSS files. The `@import` statement is a client-side statement, so each import adds another request to the request for the main file.

Including analytics scripts such as Omniture or Google Analytics generates additional HTTP requests. The first call goes out to the server as a request to get the JavaScript, the browser processes the JavaScript makes another request to the server to transfer the information. Including two analytics engines actually requires four calls. Temporary redirects aren't cached, so the request is always issued. Redirects are always an additional HTTP request

#### Using GET vs. POST Requests

For GET requests, all parameters are passed in the URL. For POST requests, everything is in the header information. GET requests can be cached easily, because it's assumed that the request doesn't change the server state. POST is never cached, because it changes the state on the server.

For Salesforce B2C Commerce, only GET can be placed in the page cache. POST requests are never cached and are therefore slower than other requests. POST is useful for specific operations, such as login or interacting with the shopping cart. Most requests, however, should use a GET request. For AJAX components, POST requests are also not cached.

#### Iframes

Salesforce recommends that you generally avoid Iframes if possible. Iframes block the browser onload event and they always have performance cost even if they are empty. This is because each Iframe is a separate HTTP request, which might not be cached. However, Iframes are useful for decoupling the page impression from external services.

#### Expires and Conditional Headers

Expires and conditional headers are currently not supported in B2C Commerce.

### Reduce and Reuse Scripts

Optimize the use of scripts in your pages.

- Only have one JavaScript file. A single JavaScript file is easier and faster to load, but difficult to maintain.
- Remove redundancy. Don't use inline CSS or inline JavaScript. Inline CSS and JavaScript must be reprocessed every time the page is sent, unlike for pages that are cached with an external JavaScript or CSS file.
- Reuse JavaScript. The browser caches it and doesn't request it from the server.

#### Unobtrusive JavaScript

Using unobtrusive JavaScript can be better than extensive HTML markup. The page is smaller and the JavaScript is on the bottom, so the page renders faster.

#### Test DOM Modifications

If you modify the DOM on-the-fly, page loading performance could be negatively affected. If you must modify the DOM, test the performance with multiple browsers and browser versions

### Reduce URL and Page Size

Optimize the use of URLs and minimize page size. Page size is the total file size of all the resources that must be loaded for the page to function. Page size impacts load speed of the page on a browser, and it can also have a significant impact on mobile users.

We recommend the following best practices for optimizing pages and URLs:

- Reduce URL Parameters

  Remove unused URL parameters and POST data. In B2C Commerce, enable SEO URLs that substantially shorten the standard URL.

- Optimize Features

  Remove features from first pages and landing pages.

- Reduce DOM Size

  Use minimal, standard XHTML with minimal DOM nodes. For example, use the standard H3 HTML tag instead of a span class.

- Use CSS Cascading

  Rely on CSS cascading to get rid of class information, rather than specifying it explicitly.

- Remove Inline Comments

  Remove comments. Minimizing comments makes it harder to maintain the page, but makes it faster to load. For ISML templates, create ISML comments that use three dashes. The dashes are removed when the page is sent to the browser.

  For example, add the following comments in ISML:

  ```html
  <!-- End User Can See -->
  <!--- Invisible to End User --->
  ```

  Comments in CSS, however, are always sent with the page.

  For example, add the following comment in CSS:

  ```html
  /* Always Viewable */
  ```

- Use Optimized Images

  Make sure Hi-Res image file sizes are optimized to \< 6 MB or have dimensions not exceeding 3000x3000 pixels.

  Choose the right image file type to reduce the page size as per the recommendations below.

  | File Type   | Recommended For                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | JPEGs       | For photographs only. JPEG file type can handle all of the colors in a photograph in a relatively small, efficient file size. JPEGs are typically more SEO-friendly than PNGs, especially if you don’t need transparent backgrounds, as they offer better compression levels.                                                                                                                                                                                                                                                                      |
  | PNG         | Simple images or graphics using large, flat areas of color. This includes most designs, infographics, images with lots of text in them, and logos. PNGs are higher quality than JPEGs, but typically come with a larger file size. PNGs deal with areas of color and text with nice crisp lines, so you can zoom in and not lose any quality. They also support transparent backgrounds. If you have a choice, we recommend saving PNGs as “24 bit” format rather than “8 bit” because of the better quality and richer array of supported colors. |
  | GIF         | For animated images only. GIF only uses 256 colors along with lossless compression, which makes it the best choice for animated images.                                                                                                                                                                                                                                                                                                                                                                                                            |
  | SVG/Sprites | For logos, diagrams, and icons or other high-resolution, computer-generated graphics. Multiple SVG images can also be placed into a single SVG file and each can be referenced by an ID rather than a pixel position.                                                                                                                                                                                                                                                                                                                              |
  | BMP         | Not recommended                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
  | TIFF        | Not recommended                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

  Many graphics or web publishing tools add information (EXIF-information) to graphics files to make it easier to store and sort them. However, this extra information makes the files larger than they would otherwise be. Use tools to strip any additional information included in the image by the digital camera or the image-processing software.

  If your landing page includes a series of similar-sized images (say, for a client logo bar), shorten your load time by combining them into an image sprite, then use CSS to display specific chunks of that sprite at a time.

- Optimize or Remove Unnecessary Custom Fonts

  Review and optimize the number of custom fonts you're using on the page. While a couple won't hurt, using them in excess could still hurt your page speed. Here’s a summary of the key things to consider when using custom web fonts:

  - At a minimum, use a WOFF2 font file to get the smallest size as there are no downsides.

  - Subset your fonts to include only the characters that are required. This could be to remove all but a few characters (as a font file correctly prepared can be smaller than a graphic), or limited to a specific language.

  - Implement a strategy for how typography behaves. Be it an all or nothing approach until the font is loaded or a carefully selected fallback.

  - Give the browser the best chance at getting fonts right by preloading required fonts.

### 404 Errors and 404 Pages

A site containing missing pages, images, JavaScript, or CSS files, can result in HTTP 404 error responses. To resolve these errors, use a link crawler to find broken links or missing images on any site pages.

**note:** We recommend that you use link crawler tools during non-peak times.

Use browser developer tools to identify missing objects on pages that are responding to your browser with a 404 error.

No 404 error messages appear to shoppers for missing JavaScript or a missing include. However, error messages are generated and can affect system performance. We don't cache 404 responses by default. When 404 error response caching isn't enabled, the system must request the asset each time a page is requested, resulting in the server having to work harder to respond to each page request. With administrator access, enable 404 error response caching for either static or dynamic content using feature switches available in Business Manager.

When using the 404 error response caching feature switches, keep the following in mind:

- When using 404 caching for dynamic content, make sure to use the 404 response code when appropriate. For example, converting a sporadic 500 response to a 404 response can result in the undesirable effect of the web tier caching the response.
- Be mindful of any content you included in 404 pages. We recommend that you avoid personalized content in 404 pages, as these pages can get cached and potentially displayed to many shoppers.

**note:** New realms created after September 15th 2020 have 404 caching enabled by default. Administrators can disable 404 error response caching using feature switches in Business Manager.

When a shopper searches for an item that doesn't exist, they might also receive a 404 error page. This type of error typically results in the shopper seeing a generic 404 page not found message instead of the storefront. Receiving 404 pages can adversely affect the selling potential of a site. To help draw customers back to the shopping experience, we recommend customizing your 404 pages. For example, try adding the following to 404 pages:

1.  Informational message―Add a message explaining that the page the customer is looking for can't be found.
2.  Merchandising―Add top featured products, previously viewed products, or recently searched for products.
3.  Search―Add a search box enabling the customer to search for a new product.
4.  Sitemap―Add a sitemap that enables the customer to return to the site and continue shopping.

![404 Error Handling Scenario](https://developer.salesforce.com/media/b2c-commerce/b2c_404_error_page.png)

### Performance and Stability Coding Standards

Ecommerce applications built on Salesforce B2C Commerce can run fast and perform reliably. Use B2C Commerce within its capabilities and make sure that your customizations follow coding best practices. Identify permissible designs that ensure the scalability and robustness of your customizations.

#### Data Transfer Volume

B2C Commerce imposes limits on incoming and outgoing network traffic for B2C Commerce instances and the Content Delivery Network.

These limits are relative to the Gross Merchandise Value (GMV) and are defined in the Main Subscription Agreement (MSA). Data transfers within the limits are at no additional charge (are included in the subscription fee). There is a fee for data transfers exceeding the limits.

#### Storefront Development for Performance and Stability

When developing your storefront, consider storefront development best practices.

- Don't post-process product or content search results. Search results can be large sets. Instead, all search criteria must go into the query for efficiency execution. Don't post-process with custom code.
- Don't iterate over variations of a base product on a search result page (or any page where multiple base products appear). This approach can significantly increase the number of touched business objects. Instead, use native Salesforce B2C Commerce features to deal with variation product availability (pipelet Search, input parameter OrderableProductsOnly), to determine available variation values (dw.catalog.ProductSearchHit.getRepresentedVariationValues), or to determine price ranges (dw.catalog.ProductSearchHit.minPrice or Product.priceMode.minPrice).
- Do Break search results into pages before processing or displaying in the storefront (pipelet Paging, class PagingModel). Instead, limit the maximum page size, for example, a maximum of 120 products per page, especially if the "View All" functionality is provided.
- Don't trigger live calls to external systems on frequently visited pages (homepage, category, or search result pages and product pages). Where live calls are needed, specify a low timeout value (for example, 1 second). A B2C Commerce application server thread waiting for a response from an external system can't serve other requests. Many threads waiting for responses can make the entire cluster unresponsive, for any pages.
- Don't execute any long running operations in a storefront controller or pipeline (for example, import or export). Instead, use "jobs" for all long running tasks. The web tier closes browser connections after 5 minutes. The controller or pipeline could still be running at this time.
- Avoid concurrent changes to the same object. Storefront controllers and pipelines should only read shared data (for example, catalogs and prices) and read or write customer-specific data (for example, customer profiles, shopping carts or orders). This practice avoids making concurrent changes. The inventory framework is designed to support concurrent change (for example, two customers buying the same product at the same time or a customer buying a product while the inventory import is running). The storefront controller or pipeline marks the order with EXPORT_STATUS_READY as the last step in order creation. Then order processing jobs can start modifying the order object. Concurrent requests for the same session are serialized at the application server. Concurrent Script API controller or pipeline requests can lead to Optimistic Locking exceptions. Any number of requests (AJAX or a WS) in the same session from a controller are treated as separate requests to the platform. If requests are concurrent, then optimistic locks prevents two requests from modifying same resource and the second request errors out.
- Limit transaction size. The system is designed to deal with transactions with up to 1,000 modified business objects. A storefront controller or pipeline shouldn't even come close to this number.
- Make sure that the most visited pages are cacheable and well performing. These controller and pages are usually category page or search result pages (Search-Show), product detail pages (Product-Show), home pages (Default-Start, Home-Show), Cart Page (Cart-Show) and Checkout. For more information, see [Optimize General Site Pages](#optimize-general-site-pages).
- Limit expensive (> 10 ms) custom server logic on OnSession and OnRequest controllers. (Needed only one time at the start of a code review).
- Use Index Friendly APIs
  - Replace database intensive or inefficient APIs with appropriate index-friendly APIs. Check code for database intensive APIs in most-visited pages:
    - `Category.getOnlineSubCategories()`
    - `Category.getProducts()`
    - `Category.getOnlineProducts()`
    - `Category.getProductAssignments()`
    - `Category.getOnlineCategoryAssignments()`
    - `ProductMgr.queryAllSiteProducts()`
    - `Product.getPriceModel()`
    - `Product.getVariants()`
    - `Product.getVariationModel()`
  - Use API Methods that are index-friendly as appropriate to replace custom logic:
    - `ProductSearchModel.search()`
    - `ProductSearchModel.orderableProductsOnly(true)`
    - `ProductSearchModel.getRefinements()`
    - `ProductSearchRefinements.getNextLevelRefinementValues()`
    - `ProductSearchModel.getProductSearchHits()`
    - `ProductSearchHit.getMinPrice()`
    - `ProductSearchHit.getMaxPrice()`
    - `ProductSearchHit.getRepresentedProductIDs()`
    - `ProductSearchHit.getRepresentedVariationValues(attribute)`
- Make sure all direct 3rd-party HTTP calls are migrated to Web Service Framework
- Make sure no enforced quota violations are reported in STAGING and PRODUCTION, and that Quota Dashboard alerts have been subscribed by all site admins.
- Make sure there isn’t unnecessary creation of custom Session objects, productlist objects, or cookies.
- Make sure a WishList isn’t created for every anonymous user (for example, created at the end of every product item add to cart calls)
- Make sure Custom Object volume is kept in check with purge jobs
- OCAPI:
  - Make sure Shop API GET requests are limited to smaller blocks of data. Instead of 200 products payload, retrieve 100 or 50.
  - Make sure there’s no OCAPI request of persistent objects within a hook customization such as ProductMgr.getProduct() or product.getVariations()
  - For more information, see [OCAPI best practices](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/bestpractices.html).
- SFRA:
  - Make sure SFRA templates don't include multi-part, embedded, or nested forms. We don't recommend them as a best practice.
  - Make sure that controllers don’t call each other, because controller functionality should be self-contained to avoid circular dependencies.
  - Avoid calling pipelets from within a controller. It's allowed while there are still pipelets that don't have equivalent B2C Commerce script methods, but won’t be supported in future.

#### Job Development for Performance and Stability

To optimize job performance, follow the job development standards.

- To modify objects in Salesforce B2C Commerce, we recommend that you use standard imports instead of customizations. In jobs, use [B2C Commerce Job Steps](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/jobstepapi/html/index.html) for imports.
- B2C Commerce standard imports are designed to process arbitrary feed sizes. Changes are committed to the database on a per business object basis. If related changes must be committed in a single transaction, enclose the import pipelets in an explicit controller or pipeline transaction. Choose this approach only as an exception. The transaction size limit applies. Make sure that this limit isn't exceeded.
- The transaction size is limited to 1,000 modified business objects. Make sure that this limit isn't exceeded. B2C Commerce doesn't enforce this limit today, but might in the future.
- Don't implement data validation jobs on B2C Commerce (for example, products with no names or \$0 prices). Instead, make sure that the feeds into B2C Commerce are of high quality, and don't include products with incomplete attribution or are marked offline. Manually review catalog data on a staging instance.
- When processing large data sets, pay attention to the memory footprint:
  - Design loop logic so that memory consumption doesn't increase with result set size.
  - Keep only currently processed objects in memory, and don't retain references to that object (so that the object can be freed from memory). Specifically, don't perform sorting or other types of collections in memory.
  - Stream data to file regularly (don't build large structures in memory).
  - Read feeds record by record (don't read an entire file into memory).
- If you must create multiple feeds, query the objects once and write records to all feeds as you iterate over the results. This approach saves time because the objects must be created in memory only once.
- Avoid concurrent changes to the same object. Use the locking framework to ensure exclusive access. Specify named resources for job schedules.
- Keep application server utilization by jobs to a minimum. Calculate the job load factor: total number of seconds of job execution time on an instance (Staging or Production) on a day divided by 86,400 (number of seconds in a day). Try to keep the job load factor below 0.20.
- Pay attention to recovery in solution design. A job might end abnormally, for example, server restart or application server failure. The job can be resumed or restarted. Design the job so that it recovers gracefully. It must be possible to repeat a job step that was aborted.
- Don't start many jobs at the same time. Instead, disperse job start times to balance the job load.

#### Administrative Considerations for Performance and Stability

When designing your ecommerce application, consider these administrative best practices.

- When using the Site Backup feature on the staging instance, configure it to run no more than one time a day. Don't keep more archives than necessary. Salesforce B2C Commerce allows up to 5 backups.
- Don't run custom spiders against the production storefront in an attempt to populate the page cache. This technique consumes significant system resources without delivering much performance benefit.
- Enable **Incremental Search Index Updates** on staging instances to allow for near real-time preview in storefront; but only on production instances if you must account for product availability needs in search and sorting. Configure a search index rebuild schedule (full index rebuild) on the Staging instance to run no more than one time a day. If you must run a full index rebuild during the day, trigger it manually in Business Manager. Use Data Replication to transfer search indexes to production.
- Don't perform page cache invalidation on production during peak traffic time. This practice can significantly degrade storefront performance. The page cache is automatically invalidated after a data replication or code replication. Invalidate the page cache programmatically or manually in Business Manager.
- Don't perform data or code replications during peak traffic times. Besides performance considerations (see page cache invalidation) replications during peak times can also impact business performance if there’s a code or deployment defect and the operations must be rolled back.

<!-- document id=f5c74c717b6add37518bb83149b71754cfe986d328a6ab965fff7c57828a61a4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/sitearchiveexportconfiguration.md -->

# SiteArchiveExportConfiguration document

Input record for site archive export system job.

| Property              | Type                                                            | Constraints                    | Description                                                                                                                  |
| :-------------------- | :-------------------------------------------------------------- | :----------------------------- | :--------------------------------------------------------------------------------------------------------------------------- |
| data_units            | [ExportDataUnitsConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/exportdataunitsconfiguration.md) | mandatory=true, nullable=false | The data units to export in JSON format.                                                                                     |
| export_file           | [String]                                                        | mandatory=true, nullable=false | Export file pathname relative to 'IMPEX/src' folder.                                                                         |
| overwrite_export_file | Boolean                                                         | mandatory=true, nullable=false | Overwrite existing file. If option is not selected and the file already exists, the job step will use the ERROR exit status. |

<!-- document id=14e2d1d022251412ceece7f1f11d1d5b6b33df92cd7fea66d8ddf0f34bac98f9 url=/developer/current/en-us/commerce-cloud/b2c-commerce/references/ocapi/current/sitearchiveimportconfiguration.md -->

# SiteArchiveImportConfiguration document

Input record for site archive import system job.

| Property  | Type         | Constraints                    | Description                                                         |
| :-------- | :----------- | :----------------------------- | :------------------------------------------------------------------ |
| file_name | [String]     | mandatory=true, nullable=false | File path to the import file, which must be existent on the server. |
| mode      | Enum {merge} |                                | Import mode to use. Default value is 'merge'.                       |

<!-- document id=d0f9f4eda33a722a0f51f4b17698792733f3f7e22648b4e90c76d3aa67761978 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/sites.md -->

Sites

# Sites

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/sites/sites-oas-v1-public.yaml)

## API Overview

The Sites API provides endpoints for retrieving and searching sites within Salesforce Commerce Cloud using the following capabilities:

*   Site Retrieval: List all sites in an organization or retrieve a specific site by ID.
*   Advanced Discovery: Use the `displayName`, `description`, or `id` attributes to find specific sites for reporting or administrative operations.
*   Status Monitoring: Filter sites by their `inDeletion` status to track maintenance workflows or identify sites marked for removal.
*   Results Management: Navigate large datasets efficiently using pagination (limit/offset), field selection, and multi-field sorting.

Sites represent individual storefronts or channels within a Commerce Cloud organization.

### Authentication

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.sites` (read-only access) or `sfcc.sites.rw` (read-write access) and other relevant scopes in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Endpoints

| Method | Endpoint | Description |
| --- | --- | --- |
| GET | `/organizations/{organizationId}/sites` | Returns a paginated list of sites |
| GET | `/organizations/{organizationId}/sites/{siteId}` | Returns a single site by ID |
| POST | `/organizations/{organizationId}/site-search` | Searches for sites using complex queries |

### Attribute Reference

The following attributes can be used in search queries and sorting:

*   `id`: The unique identifier of the site (String)
*   `displayName`: The user-friendly display name of the site (String)
*   `description`: The description of the site (String)
*   `inDeletion`: Boolean flag indicating if the site is marked for deletion (Boolean)

### Use Cases

*   Site Management: Find and filter sites for administrative operations.
*   Site Lookup: Retrieve a specific site by ID to inspect its configuration.
*   Reporting: Generate reports on site configurations and status.
*   Monitoring: Track sites that are marked for deletion or maintenance.
*   Lifecycle Tracking: Monitor the deletion queue by filtering for sites where `inDeletion` is true.

### Best Practices

*   Use the `select` parameter to limit response fields and reduce payload size.
*   Use specific search queries to minimize result set size.
*   Apply sorting to organize results meaningfully.
*   Use pagination for large result sets.
*   Filter out deleted sites when appropriate using the `inDeletion` attribute.
*   Cache site information when possible to reduce API calls.

**Version:** 1.3.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/site/sites/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 security scheme for Admin API access using Account Manager. Requires appropriate scopes for site management operations.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.sites: Access to site resources
    *   Scope sfcc.sites.rw: Read and write access to site resources

## Operations

### POST Search Sites

`POST /organizations/{organizationId}/site-search`

Operation ID: `searchSites`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw).

Searches for sites.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   id - String
*   displayName - String
*   description - String
*   inDeletion - Boolean

The output of the query can also be sorted. These are the list of sortable attributes:

*   id - String
*   displayName - String
*   description - String
*   inDeletion - Boolean

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

The search request document

Media type: `application/json`. Schema: `SiteSearchRequest`.

_Example: SiteSearchById_ Search sites by ID

Example of searching for sites by their ID using a term query

```
{
  "query": {
    "termQuery": {
      "fields": [
        "id"
      ],
      "operator": "is",
      "values": [
        "RefArch"
      ]
    }
  },
  "limit": 10,
  "offset": 0
}
```

_Example: SiteSearchByDisplayName_ Search sites by display name

Example of searching for sites by their display name using a text query

```
{
  "query": {
    "textQuery": {
      "fields": [
        "displayName"
      ],
      "searchPhrase": "Reference Architecture"
    }
  },
  "limit": 25,
  "offset": 0,
  "sorts": [
    {
      "field": "displayName",
      "sortOrder": "asc"
    }
  ]
}
```

_Example: SiteSearchActiveOnly_ Search only non-deleted sites

Example of searching for sites that are not marked for deletion

```
{
  "query": {
    "termQuery": {
      "fields": [
        "inDeletion"
      ],
      "operator": "is",
      "values": [
        false
      ]
    }
  },
  "limit": 100,
  "offset": 0,
  "sorts": [
    {
      "field": "id",
      "sortOrder": "asc"
    }
  ]
}
```

_Example: SiteSearchComplex_ Complex site search with multiple criteria

Example of a complex search combining multiple conditions

```
{
  "query": {
    "boolQuery": {
      "must": [
        {
          "termQuery": {
            "fields": [
              "inDeletion"
            ],
            "operator": "is",
            "values": [
              false
            ]
          }
        },
        {
          "textQuery": {
            "fields": [
              "displayName",
              "description"
            ],
            "searchPhrase": "production"
          }
        }
      ]
    }
  },
  "limit": 20,
  "offset": 0,
  "sorts": [
    {
      "field": "displayName",
      "sortOrder": "asc"
    }
  ]
}
```

#### Responses

*   **200** Returns site search results
    
    Media type: `application/json`. Schema: `SiteSearchResult`.
    
    _Example: SiteSearchResultSuccess_ Successful site search result
    
    Example of a successful site search returning multiple sites
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "hits": [
        {
          "id": "RefArch",
          "customerListLink": {
            "customerListId": "RefArch",
            "title": "Default Customer List"
          },
          "displayName": {
            "default": "displayName",
            "en": "An English displayName",
            "de": "A German displayName"
          },
          "description": {
            "default": "description",
            "en": "An English description",
            "de": "A German description"
          },
          "inDeletion": false,
          "storefrontStatus": "online",
          "siteCatalogId": "storefront-catalog-m-en",
          "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
          "customCartridges": "plugin_custom_cartridge:plugin_wishlists",
          "creationDate": "2024-01-15T10:00:00.000Z",
          "lastModified": "2024-10-14T15:30:00.000Z"
        },
        {
          "id": "RefArchGlobal",
          "customerListLink": {
            "customerListId": "RefArchGlobal",
            "title": "Default Customer List"
          },
          "displayName": {
            "default": "displayName",
            "en": "An English displayName",
            "de": "A German displayName"
          },
          "description": {
            "default": "description",
            "en": "An English description",
            "de": "A German description"
          },
          "inDeletion": false,
          "storefrontStatus": "online",
          "siteCatalogId": "storefront-catalog-m-de",
          "cartridges": "plugin_custom_cartridge:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
          "customCartridges": "plugin_custom_cartridge",
          "creationDate": "2024-02-10T08:00:00.000Z",
          "lastModified": "2024-11-01T12:00:00.000Z"
        }
      ],
      "query": {
        "termQuery": {
          "fields": [
            "inDeletion"
          ],
          "operator": "is",
          "values": [
            false
          ]
        }
      },
      "sorts": [
        {
          "field": "id",
          "sortOrder": "asc"
        }
      ]
    }
    ```
    
    _Example: SiteSearchResultSingle_ Single site search result
    
    Example of a site search returning a single site
    
    ```
    {
      "limit": 1,
      "offset": 0,
      "total": 1,
      "hits": [
        {
          "id": "RefArch",
          "customerListLink": {
            "customerListId": "RefArch",
            "title": "Default Customer List"
          },
          "displayName": {
            "default": "displayName",
            "en": "An English displayName",
            "de": "A German displayName"
          },
          "description": {
            "default": "description",
            "en": "An English description",
            "de": "A German description"
          },
          "inDeletion": false,
          "storefrontStatus": "online",
          "siteCatalogId": "storefront-catalog-m-en",
          "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
          "customCartridges": "plugin_custom_cartridge:plugin_wishlists",
          "creationDate": "2024-01-15T10:00:00.000Z",
          "lastModified": "2024-10-14T15:30:00.000Z"
        }
      ],
      "query": {
        "termQuery": {
          "fields": [
            "id"
          ],
          "operator": "is",
          "values": [
            "RefArch"
          ]
        }
      },
      "sorts": [
        {
          "field": "id",
          "sortOrder": "asc"
        }
      ]
    }
    ```
    
*   **400** Bad Request - Malformed search query or invalid parameters
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MalformedSearchParameter_ Malformed search query
    
    Example of an error when the search query is malformed or invalid
    
    ```
    {
      "title": "Malformed Search Parameter",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/malformed-search-parameter",
      "detail": "The search query contains invalid syntax. Please check the query structure and try again."
    }
    ```
    
    _Example: InvalidFieldName_ Unqueryable Field
    
    Example of an error when an invalid field name is used in the search query
    
    ```
    {
      "title": "Unqueryable Field",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "detail": "The field 'invalid_field' is not a searchable attribute for sites. Valid fields are: id, displayName, description, inDeletion."
    }
    ```
    
    _Example: InvalidSortField_ Field Not Sortable
    
    Example of an error when an invalid field is used for sorting
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'invalid_sort' is not a sortable attribute for sites. Valid sortable fields are: id, displayName, description, inDeletion."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get Sites

`GET /organizations/{organizationId}/sites`

Operation ID: `getSites`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw).

Returns a paginated list of sites for the organization. Results are sorted by site ID in ascending order by default.

Use the `select` parameter to control which fields are included in the response. Use the `limit` and `offset` parameters to paginate through results.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 50 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 50.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Returns a paginated list of sites
    
    Media type: `application/json`. Schema: `Sites`.
    
    _Example: GetSitesSuccess_ Successful retrieval of sites
    
    Example of a successful response returning a paginated list of sites with `select=(**)` applied.
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 3,
      "data": [
        {
          "id": "RefArch",
          "displayName": {
            "default": "Reference Architecture Site"
          },
          "description": {
            "default": "Main storefront for reference architecture"
          },
          "inDeletion": false,
          "storefrontStatus": "online",
          "siteCatalogId": "storefront-catalog-m-en",
          "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
          "customCartridges": "plugin_custom_cartridge:plugin_wishlists",
          "customerListLink": {
            "customerListId": "customer-list-1",
            "title": "Default Customer List"
          },
          "creationDate": "2024-01-15T10:00:00.000Z",
          "lastModified": "2024-10-14T15:30:00.000Z"
        },
        {
          "id": "SiteGenesis",
          "displayName": {
            "default": "SiteGenesis Demo Site"
          },
          "description": {
            "default": "Demo site for testing purposes"
          },
          "inDeletion": false,
          "storefrontStatus": "online",
          "siteCatalogId": "storefront-catalog-sg",
          "cartridges": "plugin_custom_cartridge:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
          "customCartridges": "plugin_custom_cartridge",
          "customerListLink": {
            "customerListId": "customer-list-sg",
            "title": "SiteGenesis Customer List"
          },
          "creationDate": "2023-06-10T08:00:00.000Z",
          "lastModified": "2024-09-20T12:45:00.000Z"
        },
        {
          "id": "MobileSite",
          "displayName": {
            "default": "Mobile First Site"
          },
          "description": {
            "default": "Optimized for mobile shopping experience"
          },
          "inDeletion": false,
          "storefrontStatus": "maintenance",
          "siteCatalogId": "mobile-catalog",
          "cartridges": "plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
          "customCartridges": "plugin_wishlists",
          "creationDate": "2024-03-01T14:20:00.000Z",
          "lastModified": "2024-10-10T09:15:00.000Z"
        }
      ]
    }
    ```
    
    _Example: GetSitesWithSelect_ Sites with select filter applied
    
    Example of a response when the select parameter limits returned fields
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "data": [
        {
          "id": "RefArch"
        },
        {
          "id": "SiteGenesis"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### GET Get Site

`GET /organizations/{organizationId}/sites/{siteId}`

Operation ID: `getSiteById`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw).

Returns the site identified by the given site ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (path, SiteId, required) The identifier of the site.
    
    _Example_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Returns the requested site
    
    Media type: `application/json`. Schema: `Site`.
    
    _Example: GetSiteByIdSuccess_ Successful retrieval of a single site
    
    Example of a successful response returning a single site by its ID
    
    ```
    {
      "id": "RefArch",
      "displayName": {
        "default": "Reference Architecture Site"
      },
      "description": {
        "default": "Main storefront for reference architecture"
      },
      "inDeletion": false,
      "storefrontStatus": "online",
      "siteCatalogId": "storefront-catalog-m-en",
      "cartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
      "customCartridges": "plugin_custom_cartridge:plugin_wishlists",
      "customerListLink": {
        "customerListId": "customer-list-1",
        "title": "Default Customer List"
      },
      "creationDate": "2024-01-15T10:00:00.000Z",
      "lastModified": "2024-10-14T15:30:00.000Z"
    }
    ```
    
    _Example: GetSiteByIdMaintenance_ Site in maintenance mode
    
    Example of a site with maintenance storefront status
    
    ```
    {
      "id": "MobileSite",
      "displayName": {
        "default": "Mobile First Site"
      },
      "description": {
        "default": "Optimized for mobile shopping experience"
      },
      "inDeletion": false,
      "storefrontStatus": "maintenance",
      "siteCatalogId": "mobile-catalog",
      "cartridges": "plugin_wishlists:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core",
      "customCartridges": "plugin_wishlists",
      "creationDate": "2024-03-01T14:20:00.000Z",
      "lastModified": "2024-10-10T09:15:00.000Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Site Not Found - The requested site ID does not exist
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: SiteNotFound_ Site Not Found
    
    Example of an error when the requested site ID does not exist
    
    ```
    {
      "title": "Site Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found",
      "detail": "No site with ID 'unknown' could be found."
    }
    ```
    

### GET Get Site Custom Cartridges

`GET /organizations/{organizationId}/sites/{siteId}/custom-cartridges`

Operation ID: `getSiteCustomCartridges`. Security: AmOAuth2 (sfcc.sites, sfcc.sites.rw).

Returns the site's custom cartridge path - the colon-delimited list of custom (non-system) cartridges assigned to the site. This is the mutable segment of the site's cartridge path.

For the effective cartridge path, including system cartridges, see the `cartridges` field on the [Site](#tag/Sites/operation/getSiteById) resource.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (path, SiteId, required) The identifier of the site.
    
    _Example_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Returns the site's custom cartridge path
    
    Media type: `application/json`. Schema: `SiteCustomCartridges`.
    
    _Example: GetSiteCustomCartridgesSuccess_ Successful retrieval of a site's custom cartridge path
    
    Example of a successful response returning the site's custom cartridge path
    
    ```
    {
      "customCartridges": "plugin_custom_cartridge:plugin_wishlists"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Site Not Found - The requested site ID does not exist
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: SiteNotFound_ Site Not Found
    
    Example of an error when the requested site ID does not exist
    
    ```
    {
      "title": "Site Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found",
      "detail": "No site with ID 'unknown' could be found."
    }
    ```
    

### PUT Replace Site Custom Cartridges

`PUT /organizations/{organizationId}/sites/{siteId}/custom-cartridges`

Operation ID: `replaceSiteCustomCartridges`. Security: AmOAuth2 (sfcc.sites.rw).

Atomically replaces the site's custom cartridge path with the provided colon-delimited list. Each cartridge name must start with a letter and contain only letters, numbers, or underscores. Cartridge names that don't match this format are rejected with 400 Bad Request. This endpoint does not verify that a cartridge is present the active code version. System cartridges are not part of this resource and are unaffected by this operation.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (path, SiteId, required) The identifier of the site.
    
    _Example_
    
    ```
    RefArch
    ```
    

#### Request body (required)

The custom cartridge path replacement request

Media type: `application/json`. Schema: `SiteCustomCartridges`.

_Example: ReplaceSiteCustomCartridgesRequest_ Replace the custom cartridge path

Example of replacing a site's custom cartridge path with a new colon-delimited list

```
{
  "customCartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_loyalty"
}
```

#### Responses

*   **200** Custom cartridge path successfully replaced
    
    Media type: `application/json`. Schema: `SiteCustomCartridges`.
    
    _Example: ReplaceSiteCustomCartridgesSuccess_ Successfully replaced a site's custom cartridge path
    
    Example of a successful response after replacing the site's custom cartridge path
    
    ```
    {
      "customCartridges": "plugin_custom_cartridge:plugin_wishlists:plugin_loyalty"
    }
    ```
    
*   **400** Bad Request - Invalid cartridge path
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidCartridgeName_ Invalid Cartridge Path
    
    Example of an error when a specified cartridge name does not match the required format
    
    ```
    {
      "title": "Invalid Cartridge Path",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-cartridge-path",
      "detail": "Invalid cartridge path '123_invalid': The cartridge name may only contain letters, numbers, or '_', must start with a letter, and be separated by ':'.",
      "cartridge": "123_invalid"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** Site Not Found - The requested site ID does not exist
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: SiteNotFound_ Site Not Found
    
    Example of an error when the requested site ID does not exist
    
    ```
    {
      "title": "Site Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/site-not-found",
      "detail": "No site with ID 'unknown' could be found."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteSearchRequest

Document representing a search request for retrieving sites. The query is a potentially complex set of expressions.

Searchable attributes:

*   id - String
*   displayName - String
*   description - String
*   inDeletion - Boolean

Sortable attributes:

*   id - String
*   displayName - String
*   description - String
*   inDeletion - Boolean

Includes all fields of `SearchRequest`.

### SiteSearchResult

Document representing a site search result. This includes the query, sorts, hits (array of Site objects), and pagination information.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Site_, required) The sorted array of search hits (Site objects). Can be empty.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### Sites

Document representing a paginated list of sites.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Site_, required) The array of sites.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### Site

*   `id` (_object_, required)
    
    ID
    
    The ID of the site.
    
    Includes all fields of `SiteId`.
    
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Site Display Name`.
    
    _Example_
    
    ```
    {
      "default": "Site Display Name",
      "en-US": "Site Display Name",
      "de-DE": "Site-Anzeigename",
      "ja-JP": "サイト表示名"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Site Description`.
    
    _Example_
    
    ```
    {
      "default": "Site Description",
      "en-US": "Site Description",
      "de-DE": "Site-Beschreibung",
      "ja-JP": "サイトの説明"
    }
    ```
    
*   `customerListLink` (_object_) The link to the customer list
    
    Includes all fields of `CustomerListLink`.
    
*   `inDeletion` (_boolean_) Specifies whether the site status is in deletion (true) or not (false)  
    Example: `false`.
*   `storefrontStatus` (_string_) Status of the storefront  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`. Example: `online`.
*   `siteCatalogId` (_string_) The catalog bound to the given site.  
    Minimum length: 1. Maximum length: 256. Example: `storefront-catalog-m-en`.
*   `cartridges` (_string_, read-only) The effective cartridge path for the site, delimited by ':'. Includes both system cartridges and the site's custom cartridges (see `customCartridges`).  
    Maximum length: 4000. Example: `app_storefront_base:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core`.
*   `customCartridges` (_string_) The custom cartridge path assigned to the site, delimited by ':'. Does not include system cartridges. This is the subset of `cartridges` that can be configured for the site.  
    Maximum length: 4000. Example: `app_storefront_base`.
*   `creationDate` (_string (date-time)_) The timestamp when the site was created.  
    Example: `2024-01-15T10:00:00.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the site was last modified.  
    Example: `2024-10-14T15:30:00.000Z`.

### SiteCustomCartridges

Document representing the custom cartridge path of a site - the colon-delimited list of custom (non-system) cartridges assigned to the site. This is the mutable segment of the site's cartridge path and aligns with the site import and export representation (`custom-cartridges`). Each cartridge name must start with a letter and contain only letters, numbers, or underscores.

*   `customCartridges` (_string_, required) The custom cartridges assigned to the site, delimited by ':'.  
    Maximum length: 4000. Example: `plugin_custom_cartridge:plugin_wishlists`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### CustomerListLink

Document representing a link to a customer list.

*   `customerListId` (_string_) The customer list identifier  
    Minimum length: 1. Maximum length: 256. Example: `customer-list-1`.
*   `title` (_string_) The title of the customer list link  
    Maximum length: 256. Example: `Default Customer List`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=22f05cd11ddf734793abe0147d84b40c8bae4d3e1e0b48cfcb63d78f68db94bc url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/skills-for-success.md -->

# Skills for Success

This guide covers the key technical skills for successful development with PWA Kit.

Generally speaking, PWA Kit developers should be comfortable with:

- Building universal React.js applications.
- Coding in [ES6](https://developer.mozilla.org/en-US/docs/Web/JavaScript) JavaScript.
- Styling UI components with [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS).
- Working with RESTful APIs like the [Salesforce Commerce API](https://developer.salesforce.com/docs/commerce/commerce-api/guide).
- Developing web applications with [Node.js](https://nodejs.org/) and [Express.js](https://expressjs.com/).
- Using [npm](https://docs.npmjs.com/) to manage packages and run scripts.

If that describes you, then you're ready to dive right in! What follows is a more comprehensive inventory of skills used in building a storefront application with PWA Kit. Don't worry if you're not an expert on every single thing. Working with PWA Kit presents plenty of opportunities to have fun learning new skills that are in high demand!

## JavaScript

A PWA Kit app is coded in modern JavaScript. Even your CSS is written in JavaScript!

A headless commerce app makes frequent network requests, so knowledge of [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) is crucial. We recommend using a universal fetch library ([cross-fetch](https://www.npmjs.com/package/cross-fetch), for example) that works both in a browser and in a Node.js environment. For maximum performance, you must be able write asynchronous code with [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and [async and await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function).

### Recommended JavaScript Resources

- Online course: [Modern JavaScript From The Beginning](https://www.udemy.com/course/modern-javascript-from-the-beginning/)
- Online course: [JavaScript Concurrency](https://www.executeprogram.com/courses/javascript-concurrency)
- MDN: [Fetch API - Web APIs](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
- [`fetch()` cheatsheet](https://devhints.io/js-fetch)
- The [Express.js](https://expressjs.com/) web server
- How to [debug](https://nodejs.org/en/docs/guides/debugging-getting-started/) a Node.js application
- Managing [npm packages](https://docs.npmjs.com/cli-commands/install.html)
- Using [npm-run-scripts](https://docs.npmjs.com/cli-commands/run-script.html)

## React.js

React is the foundation for all PWA Kit apps. The [official React documentation](https://react.dev/learn) is an excellent place to start. It's so helpful that we recommend reading all of it! For a more targeted approach to learning React, try focusing on the components, props, the rendering lifecycle, and state management, including new concepts like hooks that were introduced in React 16.8.

### Recommended React.js Resources

- Online course: [Modern React](https://www.udemy.com/course/react-redux/)
- [Components](https://react.dev/learn/your-first-component) and [Props](https://react.dev/learn/passing-props-to-a-component) – React
- [State Management](https://kentcdodds.com/blog/application-state-management-with-react)
- [State](https://react.dev/learn/state-a-components-memory) and [Synchronizing with Effects](https://react.dev/learn/synchronizing-with-effects)
- [Context](https://kentcdodds.com/blog/how-to-use-react-context-effectively)
- [Error Boundaries](https://kentcdodds.com/blog/use-react-error-boundary-to-handle-errors-in-react)
- Hooks: [Quick Start](https://react.dev/learn), [Tutorial](https://react.dev/learn/tutorial-tic-tac-toe), and [Reference Overview](https://react.dev/reference/react)
- [Server Side Rendering](https://react.dev/reference/react-dom/server)
- [Hydration](https://react.dev/reference/react-dom/client/hydrateRoot)
- Debugging with [React DevTools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi?hl=en)
- React extensions like [react-router](https://v5.reactrouter.com/core/guides/quick-start) and [react-helmet](https://github.com/nfl/react-helmet)

## APIs

Your app gets all its commerce data from Salesforce B2C Commerce using APIs. You should be familiar with RESTful APIs in general and the [B2C Commerce API](https://developer.salesforce.com/docs/commerce/commerce-api/guide) and [Open Commerce API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html) (OCAPI) in particular.

### Recommended API Resources

- [Commerce API Reference](https://developer.salesforce.com/docs/commerce/commerce-api/references)
- [B2C Commerce Developer Sandbox Rest API](https://admin.us01.dx.commercecloud.salesforce.com/)

## Get Training

- Instructor-led training: [Develop a B2C Composable Storefront](https://trailheadacademy.salesforce.com/classes/b2c201-develop-a-b2c-composable-storefront)

## Additional Knowledge and Skills

Depending on the details of your project, additional knowledge and skills in the following areas will be an asset:

- Architectural principles for single-page applications and the backend-for-frontend pattern
- Web page performance testing using Lighthouse and WebPageTest
- The [PWA Checklist](https://web.dev/pwa-checklist/)
- Interacting with APIs using tools like [cURL](https://curl.haxx.se/docs/manpage.html) and [Postman](https://www.postman.com/)
- HTTP networking and caching
- Web analytics
- Search engine optimization
- Configuring build tools like [webpack](https://webpack.js.org/)
- Making DNS changes and performing cutovers
- Working with third-party JavaScript libraries to enhance site functionality
- Responsive web design layout techniques using [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries), [flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox), and [grid](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Grids)

<!-- document id=83959e1e9f9f64470a379638428f51f514a402cf578d0bf93fc034fe71f19f91 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-best-practices.md -->

# SLAS Best Practices

Follow best practices for the Shopper Login and API Access Service (SLAS) to maximize security and performance. Recommended steps include using Strict Client Auth for private clients, offering passwordless login when your storefront supports it, and rotating a guest shopper’s session after they place an order.

## Strict Client Auth

Strict Client Auth is a highly recommended setting for private clients, which requires all `/login` and `/authorize` requests to pass their credentials directly in the `x-slas-client-auth` header. This feature is part of a broader set of protections to help keep authentication endpoints secure and resilient against automated threats. Public clients don't support Strict Client Auth and ignore the `x-slas-client-auth` header if present.

Follow these steps to use Strict Client Auth.

1. From the SLAS Admin UI, create a new private client or edit an existing one.
2. Turn on **Strict Client Auth**. To review how Strict Client Auth interacts with the `x-slas-client-auth` header, expand the **Strict Client Auth Behavior Matrix** dropdown.

![Strict Client Auth feature toggle in the SLAS Admin UI](https://developer.salesforce.com/docs/media/commerce-api/slas-strict-client-auth.png)

3. Save the private client.

4. Include a valid `x-slas-client-auth` header on requests to `/login` and `/authorize` endpoints. Requests that don't include the header or include an invalid header return a 401 Unauthorized error. The header value must be a Base64-encoded string in the format `client_id:client_secret`.

```
x-slas-client-auth: Base64(client_id:client_secret)
```

SLAS validates the header against these criteria.

- The header value must be valid Base64.  
- The decoded value must follow `client_id:client_secret` format with both values present.  
- The `client_id` in the header must match the `client_id` query parameter.  
- The `client_secret` must match the provisioned secret for the client.

**note:** SLAS validates the `x-slas-client-auth` header whenever it's included in the request, regardless of whether the client has Strict Client Auth turned on.

## Passwordless Login

Prefer passwordless login for shopper authentication when your storefront supports it. Passwordless login verifies a shopper’s identity without a password and offers protection against cyberattacks such as phishing and brute-force password cracking. SLAS supports one-time passwords (OTPs) and passkeys. For current storefront support, see [Passwordless Login Feature Support](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-passwordless-login-overview.md#passwordless-login-feature-support).

## Leaked Credentials on SLAS Login

Leaked Credentials Detection applies to `POST /shopper/auth/v1/organizations/{organizationId}/oauth2/login` because SLAS submits shopper credentials as HTTP Basic in the `Authorization` header. For a leaked-credentials match, use a SCAPI-zone rate-limiting rule with the `block` action (HTTP 429). Start the rule with the `log` action, review the matches, and then switch to `block`. Don't use a `managed_challenge`, `js_challenge`, or `legacy_captcha` action. For storefront form login and rule examples, see [Bot Management](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/bot-management.html). For leaked-credentials detection and SCAPI-zone availability controls, see [Security](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/security.md).

## Refresh Token Service Protection

To protect against refresh-token replay abuse, SLAS limits how frequently a single refresh token can be exchanged at `/oauth2/token`.

- A refresh token can be exchanged up to 3 times within 60 seconds.  
- Additional attempts return an HTTP 429 (Too Many Requests) response with a `Retry-After` header.  
- Repeated use of a revoked, expired, or unknown token can also return an HTTP 429 response.

To avoid hitting these limits, review your integration to make sure it doesn't reuse or concurrently exchange the same refresh token, and make sure your application correctly handles HTTP 429 responses.

## Delete Shopper Rate Limiting

The SLAS Admin [Delete Shopper](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=deleteShopper) endpoint is rate limited to 100 requests per minute per tenant by default.

- Requests that exceed this limit return an HTTP 429 (Too Many Requests) response.  
- When you receive a 429 response, wait before retrying. A 429 response blocks further requests until a 10-minute time-to-live (TTL) period expires. Requests sent before the TTL expires don't return a valid response, so wait for the TTL to expire before retrying.

## SCAPI Zone Rate Limiting

The SLAS limits in Refresh Token Service Protection and Delete Shopper Rate Limiting stay in place. A refresh token can be exchanged up to 3 times in 60 seconds, and Delete Shopper is limited to 100 requests per minute per tenant. Add rate-limiting rules on the SCAPI zone in Production Business Manager, in front of those limits. A rule applies to Development, Staging, and Production unless you scope it by the org ID in the URL path. See [SCAPI Zone Support for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5).

## Custom Header Forwarding

SLAS forwards `c_*` custom headers to ECOM on the `/login` endpoint. Use this to pass per-request context to third-party security and bot mitigation solutions integrated with your storefront.

To take advantage of this, prefix any custom header you want forwarded with `c_`.

## Preserve OAuth State in Trusted Agent On Behalf Flows

The OAuth `state` parameter is preserved end-to-end through the [Trusted Agent On Behalf](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html) (TAOB) flow, providing consistent state handling across the authorization and token requests. For details on passing the `state` parameter in a TAOB flow, see [Specify TAOB Parameters for Guest Shoppers](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-agent.html#specify-taob-parameters-for-guest-shoppers).

## Handle the Audience (`aud`) Claim

As a best practice, don't validate or hardcode the specific value of the `aud` claim in your applications, as its format may change over time. Applications should rely on standard OAuth/OIDC token validation and use the `aud` claim only to verify that the token is intended for the receiving service, rather than matching a specific expected value.

## Mitigate Guest Token Reuse

Prevent guest order data from appearing in a shopper's registered account by rotating the guest session immediately after receiving a guest order. Treat every completed guest order as a session boundary. In the recommended flow, after order confirmation, request a fresh guest token from SLAS using `grant_type=client_credentials`. Then, replace the currently stored access token and refresh token with the new ones. 

If a guest later registers on the same device, the registered profile has no association with prior guest orders. By isolating guest sessions, you enable privacy-first guest shopping on retail kiosks, public computers, and shared devices where multiple guest shoppers browse and checkout sequentially.

### Recommended Guest Token Flow

![Sequence diagram showing guest token rotation flow with order placement, session rotation, and later registration](https://developer.salesforce.com/docs/media/commerce-api/slas-guest-token-reuse-flow.png)

The recommended flow triggers upon order confirmation, when a POST `/orders` request succeeds (1).

**note:** Ideally, make order confirmation the trigger for session rotation. This step marks the strongest boundary for guest shopper activity.   
Alternatively, use these trigger points, in order of preference:

1. After payment completion, if using a multi-step checkout with deferred order creation.  
2. On logout. SLAS already handles this via `/logout`. However, this trigger doesn't help if the guest never explicitly logs out before registering.

#### Session Rotation Step 1: Get a Fresh Guest Token

Send a POST request to `/token` with `grant_type` set to `client_credentials` (2). Passing the client credentials allows the client application to get access and refresh tokens for guest user through a trusted server. For more information, see [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken).

```
POST /shopper/auth/v1/organizations/{organizationId}/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&channel_id={siteId}
```

The response includes a new `access_token` and `refresh_token`.

#### Session Rotation Step 2: Swap Tokens in the Storefront

Replace the stored `access_token` and `refresh_token` with the values returned in Step 1 (3). All subsequent B2C Commerce API calls use the new session.

#### Result: Empty Order List Following Account Registration

The benefit of session rotation shows up if the guest shopper subsequently registers an account (4). The previous guest order data doesn’t appear in the registered account profile.

To demonstrate this result, the sequence diagram shows that after registering an account and authorizing a new session, calling [getCustomerOrders](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-customers?meta=getCustomerOrders) returns an empty order list.

### Edge Cases to Consider

When implementing a session rotation flow for guest tokens, keep these edge cases in mind.

| Scenario | Recommendation |
| :---- | :---- |
| Guest places multiple orders in one session | Rotate after **each** order, or at minimum after the last order before the session ends. |
| Guest refreshes page between revoke and new token | Treat revoke+new-token as an atomic operation (no user-visible gap). |
| Guest has items in cart when session rotates | Transfer the basket to the new session if needed, or perform the rotation only after checkout completes (cart is empty). Cart is managed by the [Shopper Baskets](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=Summary) API, keyed by `customer_id.` |
| Public client without `client_secret` | Use `token_type_hint=refresh_token` with the refresh token in the revoke call; for the new guest token, use `client_credentials` with Proof Key for Code Exchange (PKCE) if required by the client configuration. |
| Session Bridge (SESB/hybrid) flows | Rotate before the session bridge, not after. SESB flows intentionally preserve guest context across the bridge. |

<!-- document id=7fd3925f4df1f2217ecfc4a1ee13687fbab556c50e6c4d895403b393cbe4ad07 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-identity-providers.md -->

# SLAS Identity Providers

To support logging in with social media accounts or other federated login systems (Google’s, for example), you must set up an external identity provider (IDP) for SLAS.

When using an IDP, shopper credentials are stored in the external identity system, instead of the B2C Commerce. Using IDPs is optional. You can still use SLAS for implementing login and API access for shoppers whose credentials are stored in the B2C Commerce system as well (not the external IDP).

When a shopper logs in through an IDP, a customer record related to that IDP is typically created. For example, if `rachel.rodriquez@example.com` logs in first using Google and second using Facebook, two separate customer records are created. If Rachel logs in with Google, makes a purchase, and then logs in with Facebook, they can’t see the purchase that they made while logged in with Google. To see the purchase again, they must log in with Google (not Facebook).

## SLAS Restrict /login Endpoint Access

When you are only using 3rd party identity providers (IDPs) for SLAS authentication, configure a SLAS client ID to block access to the SLAS `/login` endpoint, which is not needed for 3rd party IDP workflows.

To block the use of the `/login` endpoint, set the `loginEpRestrict` parameter to `true` (enabled) when configuring the SLAS client ID in the SLAS Admin UI. For security reasons, when `loginEpRestrict` is set to `true` (enabled), calls to the `/login` endpoint return a 403 Forbidden code.

To allow access to the SLAS `/login` endpoint, do either of the following actions:

- Configure a separate SLAS client ID that does not have `loginEpRestrict` enabled.
- Disable the `loginEpRestrict` parameter.

By default, loginEpRestrict is set to false(not enabled), which allows SLAS /login endpoint calls to be processed.

## Register an Identity Provider

To set up a supported IDP, first create an OAuth client in the IDP's administration portal. Next, use the [SLAS Admin UI](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) or [SLAS Admin API](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=Summary) to configure the IDP for a SLAS tenant.

You can set up more than one IDP for a tenant. For example, you could set up both Google and Facebook as IDPs for the same tenant.

Here’s an example request to set up Google as an IDP using the SLAS Admin API [registerIdentityProvider](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider) endpoint:

```bash
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/$TENANT/idps/$IDP_NAME' \
    --request 'PUT' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --data-raw '{
        "name": "$IDP_NAME",
        "clientId": "$IDP_CLIENT_ID",
        "clientSecret": "$IDP_CLIENT_SECRET",
        "authUrl": "https://accounts.google.com/o/oauth2/v2/auth",
        "tokenUrl": "https://www.googleapis.com/oauth2/v3/token",
        "tokenInfoUrl": "https://www.googleapis.com/oauth2/v3/tokeninfo",
        "userInfoUrl": "https://www.googleapis.com/oauth2/v3/userinfo",
        "redirectUrl": "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/$IDP_NAME",
        "preferenceValue": false
    }'
```

- `name`'s value must be prefixed with an identifier for a supported IDP. Append a `-` to the prefix followed by a string to create variations. For example, use `google` `google-test` , but not `googletest"`.
- `redirectUrl` follows a specific format.
- The IDP uses the `redirectUrl` to redirect back to SLAS so that the shopper can stay logged in and a SLAS authorization code is created.
- By default, SLAS uses [`client_secret_basic`](https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1) authentication to interact with the IDP. To change the method to `client_secret_post` provide `isClientCredsBody: true` in the request body.

## Log In with an Identity Provider

To log a shopper in with an IDP, follow federated login flows detailed in the [public](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-public-client.md#registered-user-federated-login) or [private](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-private-client.md#registered-user-federated-login) use cases guides.

An example of a public client flow is shown below using the [authorizeCustomer](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer) and [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken) endpoints:

```bash
CODE='my-shortcode'
ORG='my-org'
CLIENT='my-slas-client-id'
SITE='my-site-id'
REDIRECT='http://example.com/callback'

BASE_SCAPI="https://$CODE.api.commercecloud.salesforce.com"
BASE_AUTH="$BASE_SCAPI/shopper/auth/v1/organizations/$ORG"

# 1. Call SLAS `authorizeCustomer` to get a authorization URL to provide the shopper.
VERIFIER=$(openssl rand -base64 96 | tr -d '\n' | tr '/+' '_-' | tr -d '=')
CHALLENGE=$(echo -n "$VERIFIER" | openssl dgst -binary -sha256 | openssl base64 -A | tr '/+' '_-' | tr -d '=')
AUTH_URI=$(
    curl "$BASE_AUTH/oauth2/authorize" \
        -G \
        -d "client_id=$CLIENT" \
        -d "channel_id=$SITE" \
        -d "redirect_uri=$REDIRECT" \
        -d 'response_type=code' \
        -d 'hint=auth0' \
        -d "code_challenge=$CHALLENGE" \
        -D- |
        grep -i 'location' | awk '{ print $2}' | tr -d '\r\n'
)

# 2. The shopper opens the authorization URL.
echo -e "\n--> Open a browser to authenticate..."
echo "$AUTH_URI"

# 3. If the shopper authenticates, their browser is sent to the redirect URI
#    with code and USID params in the query string.
echo -en "\n--> Enter Code and USID: "
read -r USID_AND_CODE

# 4. The USID and code are provided to `getAccessToken` to get a token response.
echo -e "\n--> POST oauth2/token"
curl "$BASE_AUTH/oauth2/token" \
    -d "code_verifier=$VERIFIER" \
    -d 'grant_type=authorization_code_pkce' \
    -d "redirect_uri=$REDIRECT" \
    -d "$USID_AND_CODE"
```

If the shopper does not successfully authenticate or cancels the authentication, the browser is sent to the redirect URI with the details of the error in the query string.

**note:** Calling the SLAS [`logoutCustomer`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=logoutCustomer) endpoint does not log the customer out of a third-party IDP. The customer must explicitly log out from the IDP.

## Customize Redirect Domain

Some IDPs, notably Google, display the redirect URL (or part of the redirect URL) on the OAuth consent screen.

To customize the redirect URL so that it includes your domain:

1. On a branded domain, configure a reverse proxy to proxy the SLAS IDP callback URL. For example: `https://auth.example.com/slas-callback/{idp_name}` → `https://$SHORT_CODE.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/$IDP_NAME`.
2. Configure the IDP’s OAuth client to include the reverse proxy URL as an allowed callback URL.
3. Configure your SLAS IDP settings to use the reverse proxy URL for the `redirectUrl` parameter. You can register a new IDP or update an existing one using either the [registerIdentityProvider](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider) endpoint of the SLAS Admin API or the IDP page of the SLAS Admin UI.

### For PWA Kit Developers

If you are a PWA Kit developer, skip the step of configuring a reverse proxy. (You still must do the other two configuration steps described earlier.) By default, PWA Kit projects are already configured to use Managed Runtime’s reverse proxy to forward requests with `/mobify/proxy/api/` in the path to the B2C Commerce API. A SLAS IDP callback URL in a PWA Kit project looks like this:

```bash
https://www.example.com/mobify/proxy/api/shopper/auth/v1/idp/callback/$IDP_NAME
```

For more information on proxying with PWA Kit and Managed Runtime, see [Proxy Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.html).

## Pass Query Parameters to 3rd Party Identity Providers

For auth code flows with 3rd parties, SLAS allows for the addition of query parameters to the SLAS `/authorize` endpoint that can be passed through to the 3rd party IDP `/authorize` endpoint.

SLAS looks for the 3rd party authorization parameters that have a prefix of **“c\_”**. When present, SLAS passes these through to the **3rd party IDP `/authorize`** endpoint.

- SLAS looks for query params that begin with **“c\_”**, for example:
  - **c_auth0_state=a495d731-66a1-4e0b-9b57-b9fa4adca2cc&c_parm2:jakku,**
- SLAS removes the “**c\_**” prefix and add the key value pairs to the 3rd party IDP /authorize URI as query parameters, for example:
  - ...auth0/authorize&**auth0_state=a495d731-66a1-4e0b-9b57-b9fa4adca2cc,&param2=jakku**&scope=offline email...
- SLAS validates the 3rd party IDP /authorize endpoint query parameters:
  - Values missing from the key value pair will drop the query parameter from being added.
  - Total character length of all 3rd party IDP /authorize endpoint query parameters cannot exceed 2K.

### Call Flow

![SLAS Identity Provider call flow with custom parameters](https://developer.salesforce.com/docs/media/commerce-api/slas-idp-custom-parameters.png)

1. A Web, SPA, or Mobile app or a BFF calls the SLAS `/authorize` endpoint.
2. The call includes the OAuth `STATE` param and `NEW` customer parameters denoted with `c_`.
3. SLAS saves the `CALLER_STATE` and returns it later via a redirect.
4. SLAS calls the downstream IDP `/authorize` endpoint as part of an SSO flow. The call includes the `SLAS_STATE` value and the custom parameters provided to SLAS in the first step.
5. The IDP performs the authentication call.
6. The IDP returns the `SLAS_STATE` in a redirect call.
7. SLAS pulls the `CALLER_STATE` from its backing store.
8. SLAS returns the `CALLER_STATE` in the redirect back to the original caller.

Example cUrl command to SLAS with an IDP state variable `c_auth0_state`:

```sh
curl --location
'http://localhost:9020/api/v1/organizations/bgvn_stg/oauth2/authorize?
client_id=879a9730-3b3e-477d-9ea0-1c7bab5f2833
&redirect_uri=https://shotz.photo.com/auth/callback
&hint=auth0
&state=a495d731-66a1-4e0b-9b57-b9fa4adca2cc
&scope=offline_access%20openid%20email
&channel_id=SiteGenesis
&response_type=code
&ui_locales=en
**&c_auth0_state=a495d731-66a1-4e0b-9b57-b9fa4adca2cc**
**&c_param2=jakku**'
```

SLAS then creates the location header for the call to the 3rd-party IDP’s `/authorize` endpoint:

```diff
-->auth0_idp/authorize?
grant_type=autorization_code
&response_type=code
&client_id=879a9730-3b3e-477d-9ea0-1c7bab5f2833
&state=8fb24a51-d4cc-42bd-af02-7c1740a1448c
&redirect_uri=http://localhost:8090/sso/callback]
&scope=offline_access openid email profile
&ui_locales=en
**&****auth0_state****=****a495d731****-****66a1****-****4e0b****-****9b57****-****b9fa4adca2cc**
&param2=jakku
```

The previous call results in a callback to SLAS from the IDP with **8fb24a51-d4cc-42bd-af02-7c1740a1448c** preserved per the OIDC spec.

**note:** Neither custom parameters nor custom parameters values are returned to `redirect_uri` when authentication is complete.

## Supported Identity Providers

The following IDPs are natively supported by SLAS:

- `adfs`: [Active Directory Federated Service](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/development/ad-fs-openid-connect-oauth-concepts)
- `apple`: [Apple](https://developer.apple.com/sign-in-with-apple/get-started/)
- `auth0`: [Auth0](https://auth0.com/docs/authenticate)
- `azure_adb2c`: Azure Active Directory B2C
- `azure`: [Azure Active Directory](https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/auth-oauth2)
- `cognito`: [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html)
- `facebook`: [Facebook](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow)
- `forgerock`: [Forgerock](https://backstage.forgerock.com/docs/am/7/oauth2-guide/oauth2-register-client.html)
- `gigya`: [SAP Gigya](https://help.sap.com/docs/SAP_BUSINESS_ONE_IAM/548d6202b2b6491b824a488cfc447343/7f94c5836fad44e6a02322d39e229cc3.html)
- `gigya_social`: [SAP Gigya Social Login](https://help.sap.com/docs/SAP_CUSTOMER_DATA_CLOUD/8b8d6fffe113457094a17701f63e3d6a/4172d0a670b21014bbc5a10ce4041860.html)
- `google`: [Google](https://developers.google.com/identity/protocols/oauth2)
- `line`: [Integrating LINE Login with your web app](https://developers.line.biz/en/docs/line-login/integrate-line-login/)
- `okta`: [Okta](https://developer.okta.com/docs/reference/api/oidc/)
- `ping`: [Ping Identity](https://docs.pingidentity.com/)
- `salesforce`: [Salesforce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-salesforce-idp.md)

**note:** SLAS only supports IDPs that support OpenID Connect. SLAS does not support SAML.

Use SLAS' [default IDP functionality](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas-default-idp.md) to configure other IDPs.

### Apple IDP Configuration

Configuring Apple as an IDP requires additional configuration:

- The `authUrl` must be `https://appleid.apple.com/auth/authorize?response_mode=form_post`.
- The client secret must be the Apple application private key. From the Apple Developer Dashboard under Certificates IDs & Profiles select Keys. Select the key to be used with SLAS and download its `.p8` file. Use the value between `-----BEGIN PRIVATE KEY-----` and `----END PRIVATE KEY-----` as the client secret.
- Provide the Key ID obtained from Apple when you created your private key for client authentication. This value is also in the Apple Developer Dashboard under Certificates IDs & Profiles under Keys.
- Provide your Apple Team ID.

Here’s an example request to set up Apple as an IDP using the SLAS Admin API [`registerIdentityProvider`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=registerIdentityProvider) endpoint:

```bash
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/auth-admin/v1/tenants/$TENANT/idps/apple' \
    --request 'PUT' \
    --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    --data-raw '{
        "name": "apple",
        "clientId": "com.example.www.client",
        "clientSecret": "MIGTAgEAMBMGByqGSM49AgqGSM49AwEHBHkwdwIBAQQgaWDdP1NOT4sCSMf0wQDyVLkCczhW+G1HkiNPSW6ZkwugCgYIKoZIzj0DAQehRANCAAQKdXHgaSwThJU6Z6KMgwmko1kRFSiZSRulPdGoTxwHkFItObxCMWyf3ZOrSfiRTddC3B5eB6IfL2AxpjGU7nob",
        "keyId": "22T2PARP65",
        "teamId": "6WV5TS3D7M",
        "authUrl": "https://appleid.apple.com/auth/authorize?response_mode=form_post",
        "tokenUrl": "https://appleid.apple.com/auth/token",
        "tokenInfoUrl": "https://appleid.apple.com/auth/token",
        "userInfoUrl": "https://appleid.apple.com/auth/token",
        "redirectUrl": "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/idp/callback/$IDP_NAME",
        "preferenceValue": false
    }
```
 ### LINE IDP Configuration

  When a shopper signs in with LINE for the first time, SLAS attempts to link the sign-in to an existing storefront
  profile before creating a new customer record. If SLAS finds a matching identifier returned by LINE on an existing
  profile, the LINE sign-in is linked to that profile. If no match is found, SLAS creates a new customer record as
  usual.

  This linking check applies only to the first-time LINE sign-in for a shopper. It doesn't change LINE token
  refresh behavior, and it doesn't affect linking behavior for other identity providers (such as Apple or Azure).

  The behavior reduces duplicate customer records when a shopper already exists in your customer base (for example, a
  shopper who previously registered natively and later signs in with LINE).                    

  For details on how SLAS matches and merges shopper profiles across identity providers, see [Merge Shopper 
  Profiles](https://developer.salesforce.com/docs/commerce/commerce-api/guide/merge-shopper-profiles.html).

<!-- document id=ac4a2da51c99812b83ac12160ac00342e123d277223a5854408771dd48eca51e url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-custom-parameters.md -->

# SLAS Support for Custom Parameters and Hooks

Custom parameters can be passed to the following SLAS endpoints:

- [`/login`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authenticateCustomer). When applicable, SLAS passes custom parameters to the [OCAPI SHOP `/customers/auth` hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook-method-details.html#authentication).
- [`/authorize`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer). When applicable, SLAS passes this information to 3rd party IDPs.

Make sure you prefix the parameter names with `c_`.

**note:** - For the `/login` endpoint, SLAS forwards custom `c_`-prefixed headers (with values matching [a-zA-Z0-9-._]) to the B2C Commerce platform.
- There are no SCAPI hooks for the `/login` and `/authorize` endpoints. `/login` runs `/customers/auth` hooks and `/authorize` runs no hooks.

<!-- document id=ddbe554dc3e93eff1321348a0130f895fe8babcf725a029a5a8c2ead6d123781 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-trusted-system.md -->

# SLAS Trusted System on Behalf Authorization

Trusted System on Behalf (TSOB) is a login flow designed for system to system communication in back office workflows, for example:

- You want all logins to route through your external IDP and don’t want customers to login with SLAS.
- You want to take action as a system on behalf of a shopper.

TSOB authentication uses the [`getTrustedSystemAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedSystemAccessToken) endpoint, which requires a SLAS [private](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html#slas-clients) client with the `sfcc.ts_ext_on_behalf_of` scope. For details, see the [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

**note:** TSOB is not the preferred method for Shopper authentication flows as it is outside the OAuth and OIDC standard. For the most secure authentication mechanism, use one of the workflows described in [Shopper Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) public and private use cases. Do not use TSOB if shopper information frequently changes and `idp_origin=ecom`, as TSOB will not retrieve the most up-to-date customer information from B2C Commerce.

**important:** SLAS Trusted System on Behalf (TSOB) login has a service window of 3 seconds.

## Shopper login_ids and USIDs

Each shopper is associated with a unique `login_id`. You must use the shopper's unique `login_id` for each interaction with that shopper. Otherwise, multiple shopper records are created in SLAS and B2C Commerce. If a new `login_id` is passed in for TSOB using an IDP, a new shopper is created.

Each USID is a unique shopper ID that is created for a specific shopper's session. After a USID is created, you can use it across that shopper's interactions. The SLAS client API application (SPA, Mobile, Composable, etc.) handles the USID, which must be saved by the client API app and used as needed when making SLAS API calls.

To avoid issues with claim size during token creation, we recommend limiting the `login_id` or `email_id` to 60 characters or fewer.

## Shopper Verification

TSOB using an IDP, for example: Google, does **not** make a call to the IDP for user verification, because SLAS performs checks to verify a user is valid. Using the SLAS /authorize endpoint provides the strongest validation from the IDP.

## SLAS TSOB Shopper Flows

All TSOB flows require a SLAS private client id and secret to be in an Authorization header.

### Guest Shopper Flow

To request a guest shopper TSOB token:

```sh
curl "$https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/trusted-system/token" \
  -u "$CLIENT:$SECRET" \
  -d 'hint=ts_ext_on_behalf_of' \
  -d 'grant_type=client_credentials' \
  -d "channel_id=$SITE" \
  -d 'idp_origin=ecom' \
  -d 'login_id=guest'
```

Provide body parameters `idp_origin=ecom` and `login_id=guest`.

### Registered B2C Commerce Shopper Flow

To request a registered shopper TSOB token:

```sh
curl "$https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/trusted-system/token" \
    -u "$CLIENT:$SECRET" \
    -d 'hint=ts_ext_on_behalf_of' \
    -d 'grant_type=client_credentials' \
    -d "channel_id=$SITE" \
    -d 'idp_origin=ecom' \
    --data-urlencode 'login_id=shopper@salesforce.com'
```

Provide body parameters `idp_origin=ecom` and `login_id`, whose value is the login of an existing registered shopper.

If the shopper does not exist, SLAS returns an HTTP 400:

```json
{
  "status_code": "400 BAD_REQUEST",
  "message": "External user not found"
}
```

### Registered Shopper with External IDP Flow

To request a TSOB token for a shopper registered through an external IDP:

```sh
curl "$https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/$ORG/oauth2/trusted-system/token" \
    -u "$CLIENT:$SECRET" \
    -d 'hint=ts_ext_on_behalf_of' \
    -d 'grant_type=client_credentials' \
    -d "channel_id=$SITE" \
    -d 'idp_origin=$IDP' \
    -d "login_id=$SHOPPER"
```

Provide body parameters `idp_origin`, whose value is the ID of the IDP and `login_id`, whose value is the shopper login.

If the shopper record does not exist, SLAS creates it. The shopper's `login_id`, `first_name`, and `last_name` as set to the value provided. _SLAS does not communicate with the IDP to get the shopper information._

## TSOB Token Response

TSOB returns a [TokenResponse](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=type%3ATokenResponse), including a SLAS TSOB access token for the shopper and a refresh token. A TSOB access token includes the `tsob:ts_ext_on_behalf_of` type in the `isb` sub-claim.

The refresh token can be used with the [`getAccessToken`](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken) endpoint to obtain a new TSOB access token. When an access_token is refreshed, the new token's TTL is reset. The refresh token's TTL is also reset.

## Customer Profile Last-Login Update

After a successful TSOB login, SLAS updates the last-login timestamp on the shopper's B2C Commerce customer profile and increments the version of the customer profile object. This behavior applies starting with the 26.6 B2C Commerce release.

## Constraints

To protect against overuse, if multiple calls for the same shopper are made in succession, SLAS returns an HTTP 409:

```json
{
  "status_code": "409 CONFLICT",
  "message": "Tenant id <tenant_Id> has already performed a login operation for user id <user_id> on OCAPI in the last 3 seconds."
}
```

<!-- document id=d9fe582ed9209844dbbcfef1e21a3a3f9aaf5c920c5a585a6a3971d392af7404 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-api-source-code.md -->

# Source Code Based Price Books and Promotions

To activate source code based price books and promotions, follow the steps listed below:

## Set the Shopper Context

1. Follow the instructions in [Set and Retrieve Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md#set-and-retrieve-shopper-context).
2. Set the qualifier as key and value pair, making sure you use the same qualifier name as in the assignment.
   - `customQualifiers`: Set when you want to trigger pricing and promotion experiences using a dynamic session-based customer group.
   - `assignmentQualifiers`: Set when using the assignment framework. Can be used to trigger pricing and promotion experiences in pages such as Products, Product Search, Basket, and Shipping method. Be sure to use the same qualifier name as in the assignment.
   - `sourceCode`: Set the source code to evaluate source code group that triggers the promotion (campaign assignment) and Price books (assigned to Source code group).

```json
{
  "sourceCode": "wii1-98"
}
```

## See Also

- [createShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=createShopperContext)
- [Shopper Login (SLAS)](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=Summary)
- [Assign a Price Book or Promotion to a Specific Store in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_assigning_a_pricebook_or_promotion_specific.htm&type=5) in _Salesforce Help_

<!-- document id=4af517489d8d6f4b608334056f7b178bc5906c16d8badaf65538722e04fe2b1f url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/source-code-groups.md -->

Source Code Groups

# Source Code Groups

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/source-code-groups/source-code-groups-oas-v1-public.yaml)

## API Overview

APIs that support the creation, update, deletions and search of source code groups.

### Authentication & Authorization

The client requesting the source code information must have access to the Source Code resource. For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request. The client must first authenticate against Account Manager to log in.

You must include `sfcc.source-codes` or `sfcc.source-codes.rw` in the client ID used to generate the token. For a full list of required permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

**Version:** 1.0.42

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/source-code-groups/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.source-codes: source-codes READONLY
    *   Scope sfcc.source-codes.rw: source-codes read/write
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Retrieve source code group information.

`GET /organizations/{organizationId}/source-code-groups/{id}`

Operation ID: `getSourceCodeGroup`. Security: AmOAuth2 (sfcc.source-codes, sfcc.source-codes.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, SourceCodeGroupId, required) The unique identifier of the source code group.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Source code group information returned successfully.
    
    Media type: `application/json`. Schema: `SourceCodeGroup`.
    
    _Example: GetSourceCodeGroup_
    
    ```
    {
      "active": false,
      "activeRedirect": {
        "location": "urlString",
        "locationType": "url"
      },
      "creationDate": "2019-11-25T15:24:25.317Z",
      "description": "description for source code group test2",
      "enabled": false,
      "endTime": "2030-10-01T00:00:00.000Z",
      "id": "20% off (£30) New Customer",
      "inactiveRedirect": {
        "location": "urlString",
        "locationType": "url"
      },
      "lastModified": "2019-11-25T15:28:55.175Z",
      "startTime": "2014-10-01T00:00:00.000Z"
    }
    ```
    
*   **404** Returned when the source code group does not exist or does not match the given ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: SourceCodeGroupNotFound404_
    
    ```
    {
      "type": "SourceCodeGroupNotFoundException",
      "title": "Source Code Groups Not Found",
      "instance": "/sites/SiteGenesis/source_code_groups/foo",
      "detail": "No source code group with ID 'foo' for site 'SiteGenesis' could be found."
    }
    ```
    

### PUT Create a source code group using the information provided.

`PUT /organizations/{organizationId}/source-code-groups/{id}`

Operation ID: `createSourceCodeGroup`. Security: AmOAuth2 (sfcc.source-codes.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, SourceCodeGroupId, required) The unique identifier of the source code group.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SourceCodeGroup`.

#### Responses

*   **200** The source code group was created successfully.
    
    Media type: `application/json`. Schema: `SourceCodeGroup`.
    
    _Example: CreateSourceCodeGroup_
    
    ```
    {
      "active": false,
      "activeRedirect": {
        "location": "urlString",
        "locationType": "url"
      },
      "creationDate": "2019-11-25T15:24:25.317Z",
      "description": "description for source code group test",
      "enabled": false,
      "endTime": "2030-10-01T00:00:00.000Z",
      "id": "20% off (£30) New Customer",
      "inactiveRedirect": {
        "location": "urlString",
        "locationType": "url"
      },
      "lastModified": "2019-11-25T15:24:25.320Z",
      "startTime": "2014-10-01T00:00:00.000Z"
    }
    ```
    
*   **400**
    
    Possible reasons:
    
    *   Returned when the ID given in the request URL is different from the ID provided in the source code group document.
    *   The source code group peovided is not valid.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict400_
    
    ```
    {
      "type": "IdConflictException",
      "title": "Source Code Groups Id Conflict",
      "instance": "/sites/SiteGenesis/source_code_groups/foo",
      "detail": "The ID given in the request URL is different from the ID provided in the source code group document."
    }
    ```
    
    _Example: SourceCodeGroupInvalid400_
    
    ```
    {
      "type": "SourceCodeGroupInvalidException",
      "title": "Source Code Groups Invalid",
      "instance": "/sites/SiteGenesis/source_code_groups/foo",
      "detail": "The source code group passed in is not valid."
    }
    ```
    

### DELETE Delete the specified source code group ID.

`DELETE /organizations/{organizationId}/source-code-groups/{id}`

Operation ID: `deleteSourceCodeGroup`. Security: AmOAuth2 (sfcc.source-codes.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, SourceCodeGroupId, required) The unique identifier of the source code group.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **204** The source code group was deleted successfully.

### PATCH Update the source code group with the specified information.

`PATCH /organizations/{organizationId}/source-code-groups/{id}`

Operation ID: `updateSourceCodeGroup`. Security: AmOAuth2 (sfcc.source-codes.rw).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `id` (path, SourceCodeGroupId, required) The unique identifier of the source code group.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SourceCodeGroup`.

#### Responses

*   **200** The source code group was updated successfully.
    
    Media type: `application/json`. Schema: `SourceCodeGroup`.
    
    _Example UpdateSourceCodeGroup: same as GET /organizations/{organizationId}/source-code-groups/{id} 200 response._
    
*   **404** Returned when the source code group does not exist matching the given ID.
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example SourceCodeGroupNotFound404: same as GET /organizations/{organizationId}/source-code-groups/{id} 404 response._
    

### POST Search for source code groups.

`POST /organizations/{organizationId}/source-code-groups`

Operation ID: `sourceCodeGroupsSearch`. Security: AmOAuth2 (sfcc.source-codes, sfcc.source-codes.rw).

The following query attributes can be used to narrow the search:

| Attribute | Type |
| --- | --- |
| id | String |
| description | String |
| sourceCode | String |
| startTime | DateTime |
| endTime | DateTime |
| creationDate | DateTime |
| enabled | Boolean |
| active | Boolean |

The sourceCode and active fields can only be used in queries as conjunctions (using AND). If the field is used in a disjunction (OR), an exception is thrown.

The query output can also be sorted with the following attributes:

| Attribute | Type |
| --- | --- |
| id | String |
| description | String |
| enabled | Boolean |
| creationDate | DateTime |

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body

Media type: `application/json`. Schema: `SearchRequest`.

#### Responses

*   **200** The source code group information was returned successfully.
    
    Media type: `application/json`. Schema: `SourceCodeGroupSearchResult`.
    
    _Example: SourceCodeGroupsSearch_
    
    ```
    {
      "limit": 1,
      "hits": [
        {
          "active": false,
          "activeRedirect": {
            "location": "nintendo-wii-console",
            "locationType": "product"
          },
          "creationDate": "2020-01-06T15:30:26.000Z",
          "description": "Email promoting save 20% of WII game when buying system",
          "enabled": true,
          "endTime": "2009-12-20T00:00:00.000Z",
          "id": "gaming-email",
          "inactiveRedirect": {
            "location": "inactive-source-code",
            "locationType": "page"
          },
          "lastModified": "2020-01-06T15:30:26.000Z",
          "startTime": "2009-11-01T00:00:00.000Z"
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id"
          ],
          "searchPhrase": "gaming"
        }
      },
      "offset": 0,
      "total": 1
    }
    ```
    
*   **400** Returned when the query is ill-formed.

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SourceCodeGroupId

The ID of source code group.

Type: `string`.

Minimum length: 1. Maximum length: 28. Example: `TV-Email`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### SourceCodeGroup

Document representing a source code group.

*   `active` (_boolean_) The active flag, a computed value based on start and end time.  
    Example: `true`.
*   `activeRedirect` (_object_) The active redirect information.
    
    Includes all fields of `SourceCodeRedirectInfo`.
    
*   `cookieDuration` (_integer (int32)_) The cookie duration in days.  
    Minimum: 0. Maximum: 999. Example: `25`.
*   `creationDate` (_string (date-time)_) Returns the value of attribute 'creationDate'.  
    Example: `2019-10-20T12:00:00Z`.
*   `description` (_string_) The description.  
    Example: `This source code group is used to email promoting Flat Screen Television.` .
*   `enabled` (_boolean_) The enabled flag for storefront to consider the source code group, default to false.  
    Example: `false`.
*   `endTime` (_string (date-time)_) The end time.  
    Example: `2019-11-20T12:00:00Z`.
*   `id` (_SourceCodeGroupId_, required)
*   `inactiveRedirect` (_object_) The inactive redirect information.
    
    Includes all fields of `SourceCodeRedirectInfo`.
    
*   `lastModified` (_string (date-time)_) Returns the value of attribute 'lastModified'.  
    Example: `2019-10-20T12:00:00Z`.
*   `specifications` (_array of SourceCodeSpecification_) Source code specifications.
*   `startTime` (_string (date-time)_) The start time.  
    Example: `2019-10-20T12:00:00Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### SourceCodeGroupSearchResult

Document representing a source code group search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of SourceCodeGroup_, required) The sorted array of search hits. Can be empty.

### SourceCodeRedirectInfo

Document representing source code redirect info.

*   `locationType` (_string_, required) The type of redirect location, such as product (for a product page), category (a category page), home (for home page), page (for content), or URL (for a URL location).  
    Allowed values: `default`, `home`, `product`, `category`, `page`, `url`. Example: `url`.
*   `location` (_string_) The location of redirect, based on the type, this can be a product location, category location, home page, content page, or just a URL.

### SourceCodeSpecification

Document representing a source code specification.

*   `expression` (_string_, required)
    
    Expression is a value for the "Source Code Specification" may be literal source code, or it may contain wildcards. Literal code is simply the literal code. Valid characters are letters and numbers (no spaces). A wildcard allows a single source code specification to match multiple source codes. The following wildcards are supported:
    
    *   ? - Matches any single alpha-numeric character.
    
    For example: the source code specification 'ABC?' would match 'ABCD' or 'ABC3', but not 'ABCDE'.
    
    *   \* - Matches any sequence of alpha-numeric characters.
    
    For example: the source code specification 'ABC\*' would match 'ABCD', 'ABCDE', or 'ABC123'.
    
    *   \[n1..n2\] - Matches any number from n1 through and including n2.
    
    For example: the source code specification 'ABC\[3..22\]' would match 'ABC3', 'ABC4' or 'ABC22', but not 'ABC33' or 'ABCD'.
    
      
    Example: `televisions[1..10000]`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=088d3335509d903c1f2f15d3fb302c1fd3f0b84ed60abad590c66349a36a78e0 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/special-components.md -->

# Special Components

**note:** This guide assumes that you’re familiar with how routing works in a PWA Kit storefront. To learn more, see our guide to [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.md).

The PWA Kit React SDK includes the following special components: `AppConfig`, `App`, `Error`, and `Document`.

The default implementation of each special component can be overridden by your own custom version so that you can configure and customize the behavior of your storefront across multiple pages.

Let’s look at each special component separately:

## AppConfig

The `AppConfig` component is positioned near the top of the component hierarchy in your React app. From this position, it allows you to insert code to configure and support app-wide features, such as [state management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managing-global-state.md) or component theming. In the Retail React App, the `ChakraProvider` component is inserted into `AppConfig` to make theme values (for colors, spacing, and so on) available to all the [Chakra UI](https://chakra-ui.com/) components.

The `AppConfig` component also lets you extend the set of arguments that get passed to all components that are enhanced by `routeComponent` via the `getProps` function. To add these arguments, define a function called `extraGetPropsArgs` as a property of the `AppConfig` component.

The Retail React App uses the `extraGetPropsArgs` function to give all components that are enhanced by `routeComponent` access to an object for interacting with the Salesforce Commerce API:

```javascript
AppConfig.restore = (locals = {}) => {
  locals.api = new CommerceAPI(apiConfig)
}

AppConfig.freeze = () => undefined

AppConfig.extraGetPropsArgs = (locals = {}) => {
  return {
    api: locals.api
  }
}
```

The version of the `AppConfig` component from the PWA Kit React SDK doesn’t do much—unless you override it. To override the SDK version of `AppConfig`, define a file in `app/components/_app-config/index.jsx`. A newly generated PWA Kit project already includes this file to get you started.

## App

The `App` component is a child of the `AppConfig` component. Its main purpose is to include any components for layout and UI that persist throughout your React app, such as the header, footer, and sidebar.

The `App` component is also enhanced by the `routeComponent` function. If you define a `getProps` function as a property of the `App` component, it gets called when _any_ component from the `routes` array is rendered. Use it for any logic that you’d like to run on every page.

Like `AppConfig`, a default version of the `App` component exists in the PWA Kit React SDK, and you’re encouraged to override it. To override the SDK version of `App`, define a file in `app/components/_app/index.jsx`. A newly generated PWA Kit project already includes this file to get you started.

Some of the features that are implemented in `App` for a newly generated project include: analytics tracking, offline detection, and the `SkipNavLink` component for accessibility.

## Error

The `Error` component is rendered in place of the `App` component under any of the following conditions:

- The user makes a request for a path that isn’t found in the `routes` array.
- A component from the `routes` array throws an error in its `getProps` function.
- A component from the `routes` array throws an error during rendering.

When the `Error` component is returned, an HTTP 404 status is also included in the response header.

Like the other special components, the PWA Kit React SDK includes a default version of the `Error` component, and you’re encouraged to override it. To override the SDK version of `Error`, define a file in `app/components/_error/index.jsx`. A newly generated PWA Kit project already includes this file to get you started.

By overriding the `Error` component, you can do things like customize the error page for your brand, add redirects, and track the error as an analytics event.

## Document

The `Document` component defines the HTML that surrounds your application, such as the `<html>`, `<head>`, and `<body>` tags.

Like the other special components, the PWA Kit React SDK includes a default version of the `Document` component that can be overridden. But, in this case, we _don’t_ recommend that you override it. But if you need fine-grained control over your application, you can override `Document` by defining a file in `app/components/_document/index.jsx`. A newly generated PWA Kit project does _not_ include this file.

**tip:** Rather than override the `Document` component, we recommend using the [React Helmet](https://www.npmjs.com/package/react-helmet) library to modify the HTML tags in `Document`, such as `<head>`.

<!-- document id=2e2cb3252c35924339f6b58a4118608b9eae03416a3851e687ab08545219014a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-specifying-customer-service-center-settings.md -->

# Specify Customer Service Center Settings

For an agent to use Customer Service Center, permissions must be granted.

1.  Select **_site_** > **Merchant Tools** > **Site Preferences** > **Customer Service Center Preferences**.

2.  Select the image view type to use in Customer Service Center.

3.  Select the product search image view types.

4.  Check whether to allow multiple shipments per basket or order.

5.  Specify the Storefront Hostname and Storefront Path.

    Use Storefront Hostname and Storefront Path to define a custom storefront URL that Customer Service Center uses to open the storefront. A Storefront Path can only be set if a Storefront Hostname is also set. Storefront Hostname is instance-specific. Define the settings in the Staging environment and replicate them to the Production environment.

6.  Click **Submit**.

**note:** A Storefront Path can only be set if a Storefront Hostname is also set.

<!-- document id=76688123356f51d7163caab8bb7cb86e7d335791c75f1778314b9d939eaa6a8b url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/spi-customer-search-layout.md -->

# SPI Customer Search Layout

Search for a customer in the Point of Sale app with either a default or a customized layout. Find a customer via first name, last name, email address, and phone number.

To make it easier to find customers, Salesforce uses a customer-specific information system (SPI). This allows businesses to use their own customer records instead of Salesforce. There's also additional configuration needed in CMS that involves correctly mapping Point of Sale fields. If the fields are incorrectly configured, this results in a failure to search for the right customer.

## Prerequisites

- Modern POS App Build: 8.8.1 and later
- Platform Support: iPhone & iPad
- Offline Support: no

## Configure Point of Sale CMS for SPI Searches

1. In your custom external system, configure the [Clienteling SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/references/clienteling-spi?meta=Summary). For more information on APIs and SPIs, refer to [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

2. In CMS, create a Customer Search layout. See [Set Up a Clienteling Layout](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_layouts_templates_clienteling.htm&type=5) in _Salesforce Help_.

3. Edit a cell by clicking inside it.

4. From the toolbar menu, go to **Cell Content** | **Form Element**.

5. For Field, enter the corresponding Point of Sale field value. For example, to search a customer by first name, enter **firstName**. For the full list of values, refer to the [Customer Search Layout Mapping table](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-customer-search-layout.html#customer-search-layout-mapping-table). ![The Form Element Textfield section with Field configured.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-manage-spi-search-cms-config.png)

6. Fill in the rest of the fields. See [Cell Configuration in Layouts](https://help.salesforce.com/s/articleView?id=commerce.rt_cms_layouts_manage_cell_config.htm&type=5) in _Salesforce Help_.

7. Save and publish your changes.

8. In CMS, go to **Apps** | **All**.

9. Edit the app configuration you want to have the search layout.

10. Go to **Modules** | **Clienteling**.

11. For Customer Search Layout, select the layout you've created. ![The Clienteling section of Point of Sale CMS showing the Customer Search Layout setting, where you can pick the one you created.](https://developer.salesforce.com/docs/media/retail-cloud/rt-pos-manage-spi-customer-search-layout.png)

## Customer Search Layout Mapping Table

The table below lists the fields that you would typically see on a Customer Search layout. It also lists the corresponding Point of Sale field value and a description for each field.

<table>
<col/>
<col/>
<col/>
<col/>
<thead>
  <tr>
    <th>
      Layout Field
    </th>
    <th>
      Point of Sale Field
    </th>
    <th>
      Location
    </th>
    <th>
      Description
    </th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>
      First Name
    </td>
    <td>
      firstName
    </td>
    <td>
      This field can be configured in the Default and Customized layout.
    </td>
    <td>
      Search a customer by their first name.
    </td>
  </tr>
  <tr>
    <td>
      Last Name
    </td>
    <td>
      lastName
    </td>
    <td>
      This field can be configured in the Default and Customized layout.
    </td>
    <td>
      Search a customer by their last name.
    </td>
  </tr>
  <tr>
    <td>
      Full Name
    </td>
    <td>
      fullName
    </td>
    <td>
      This field can be configured in the Default and Customized layout.
    </td>
    <td>
      Search a customer by their full name.
    </td>
  </tr>
  <tr>
    <td>
      Phone Number
    </td>
    <td>
      phone
    </td>
    <td>
      This field can be configured in the Default and Customized layout.
    </td>
    <td>
      Search a customer by their phone number.
    </td>
  </tr>
  <tr>
    <td>
      Email Address
    </td>
    <td>
      email
    </td>
    <td>
      This field can be configured in a customized layout.
    </td>
    <td>
      Search a customer by their email address.
    </td>
  </tr>
  <tr>
    <td>
      ZIP code
    </td>
    <td>
      postalCode
    </td>
    <td>
      This field can be configured in a customized layout.
    </td>
    <td>
      Search a customer by their ZIP code.
    </td>
  </tr>
  <tr>
    <td>
      Customer ID
    </td>
    <td>
      id
    </td>
    <td>
      This field can be configured in a Customized layout.
    </td>
    <td>
      Search a customer by their customer ID.
    </td>
  </tr>
  <tr>
    <td>
      Birthdate
    </td>
    <td>
      birthDate
    </td>
    <td>
      This field can be configured in a Customized layout.
    </td>
    <td>
      Search a customer by their birthdate.
    </td>
  </tr>
  <tr>
    <td>
      Search String
    </td>
    <td>
      searchString
    </td>
    <td>
      This field can be configured in a Customized layout.
    </td>
    <td>
      Search a customer by matching the entered value.
    </td>
  </tr>
</tbody>
</table>

<!-- document id=63fac2d3148b1df003bda5b55d305f13598dc8aad86f5dc27f82d7c7e16d275b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-split-payments.md -->

# Split Payments for Custom Checkout

In API version 64.0 and later, customers can use multiple credit cards to pay for an order through Checkout APIs. This feature is available for authenticated and guest buyers in B2B Lightning Web Runtime (LWR) stores.

To use split credit card payments, your checkout implementation must meet these requirements.

- Your store uses [custom checkout](https://help.salesforce.com/s/articleView?id=commerce.comm_custom_checkout.htm&) or is headless.
- The [Cart Calculate API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/cart-calculate-api.html) is turned on.
- The [High Scale Orders](https://help.salesforce.com/s/articleView?id=commerce.comm_high_scale_order_enable.htm) feature is enabled.
- [Streamlined place order](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-streamlined-place-order.html) is enabled.

Additionally, the checkout itself must meet these requirements.

- The payment is split among multiple credit cards. No other payment types are supported.
- The cart includes only nonsubscription products.
- The payment uses standard fields, not custom ones.

## Salesforce Payments Split Payment Flow

If your store uses Salesforce Payments, follow the [streamlined place order](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-d2c-comm-streamlined-place-order.html) call sequence. In the request payload for the Prepare Payments API, include multiple payment intents for the split payment. You can specify up to 5 split payment intents. The split payment intents, which must have payment method types set to credit card, are associated with a single payment group.

## Server-Side Split Payment Flow

For server-side split payment processing, implement these calls from an active checkout session.

1. **Tokenize the payment method.** Make a POST request to the [Commerce Webstore Payments Token](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_token.htm) resource, ensuring that you capture the credit card information in the `card​PaymentM​ethod` property.
2. **Authorize the payment method.** Make a POST request to the [Commerce Webstore Checkout Payments](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm) resource with a `requestType` of `Auth`. Specify the payment token from the previous call. In the `paymentAmount` field, specify a value that’s less than the total amount for the cart.
3. **Repeat steps 1 and 2.** Tokenize and authorize additional payment methods until the sum of payment amounts equals the cart’s grand total amount, including tax and shipping. For example, if a cart has a grand total amount of $100, you can set up split payments of $75 and \$25 on separate payment methods. Each payment authorization is aggregated under the same payment group on the cart.
4. **Create the order.** Make a POST request to [Commerce Webstore Checkout Orders](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_place_order.htm). With streamlined place order enabled, validations check that the payment amount covers the full cart amount. If not, order submission is blocked. However, an order can still go through if the payment amount is greater than the cart amount. Allowing overpayment, which a merchandiser can reconcile afterward, prevents the scenario of an orphaned payment with no order.

<!-- document id=069ccff2679c626de3452435897259cd39f0fb7937e5cf1cdb884ca5042f2061 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/standard-shopper-scope.md -->

# Standard Shopper Scope

Grant a client access to a default collection of B2C Commerce endpoints by assigning the preconfigured `sfcc.shopper-standard` scope. This scope aggregates a commonly required set of over 15 scopes. By reducing the number of scopes assigned to the client, using the `sfcc.shopper-standard` scope significantly reduces the size of the JSON Web Token (JWT) issued by SLAS.

Configure scopes for a SLAS client by using either the SLAS Admin UI or the SLAS Admin API. To use the SLAS Admin UI, see [SLAS Admin UI: Create a SLAS Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.html#create-a-slas-client). To use the SLAS Admin API, see [Advanced: SLAS Admin API](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization-for-shopper-apis.html#advanced-slas-admin-api).

## Included Scopes

Before you assign the `sfcc.shopper-standard` scope, review this table to understand which scopes are included in the aggregated set. The set of included scopes can't be modified. If you assign `sfcc.shopper-standard`, the client has access to each scope and its endpoints.

| Scope                                          | Endpoints                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| :--------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sfcc.shopper-baskets-orders.rw`               | `POST /baskets` (createBasket)<br>`POST /baskets/actions/transfer` (transferBasket)<br>`POST /baskets/actions/merge` (mergeBasket)<br>`GET /baskets/{basketId}` (getBasket)<br>`DELETE /baskets/{basketId}` (deleteBasket)<br>`PATCH /baskets/{basketId}` (updateBasket)<br>`POST /baskets/{basketId}/actions/promote` (promoteTemporaryBasket)<br>`PUT /baskets/{basketId}/agent` (updateAsAgentBasket)<br>`PUT /baskets/{basketId}/billing-address` (updateBillingAddressForBasket)<br>`POST /baskets/{basketId}/coupons` (addCouponToBasket)<br>`DELETE /baskets/{basketId}/coupons/{couponItemId}` (removeCouponFromBasket)<br>`PUT /baskets/{basketId}/customer` (updateCustomerForBasket)<br>`POST /baskets/{basketId}/gift-certificate-items` (addGiftCertificateItemToBasket)<br>`DELETE /baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}` (removeGiftCertificateItemFromBasket)<br>`PATCH /baskets/{basketId}/gift-certificate-items/{giftCertificateItemId}` (updateGiftCertificateItemInBasket)<br>`POST /baskets/{basketId}/items` (addItemToBasket)<br>`PATCH /baskets/{basketId}/items` (updateItemsInBasket)<br>`DELETE /baskets/{basketId}/items/{itemId}` (removeItemFromBasket)<br>`PATCH /baskets/{basketId}/items/{itemId}` (updateItemInBasket)<br>`PUT /baskets/{basketId}/items/{itemId}/taxes` (addTaxesForBasketItem)<br>`POST /baskets/{basketId}/payment-instruments` (addPaymentInstrumentToBasket)<br>`DELETE /baskets/{basketId}/payment-instruments/{paymentInstrumentId}` (removePaymentInstrumentFromBasket)<br>`PATCH /baskets/{basketId}/payment-instruments/{paymentInstrumentId}` (updatePaymentInstrumentInBasket)<br>`GET /baskets/{basketId}/payment-methods` (getPaymentMethodsForBasket)<br>`POST /baskets/{basketId}/price-adjustments` (addPriceAdjustmentToBasket)<br>`DELETE /baskets/{basketId}/price-adjustments/{priceAdjustmentId}` (removePriceAdjustmentFromBasket)<br>`PATCH /baskets/{basketId}/price-adjustments/{priceAdjustmentId}` (updatePriceAdjustmentInBasket)<br>`GET /baskets/{basketId}/price-books` (getPriceBooksForBasket)<br>`PUT /baskets/{basketId}/price-books` (addPriceBooksToBasket)<br>`POST /baskets/{basketId}/shipments` (createShipmentForBasket)<br>`DELETE /baskets/{basketId}/shipments/{shipmentId}` (removeShipmentFromBasket)<br>`PATCH /baskets/{basketId}/shipments/{shipmentId}` (updateShipmentForBasket)<br>`PUT /baskets/{basketId}/shipments/{shipmentId}/shipping-address` (updateShippingAddressForShipment)<br>`PUT /baskets/{basketId}/shipments/{shipmentId}/shipping-method` (updateShippingMethodForShipment)<br>`GET /baskets/{basketId}/shipments/{shipmentId}/shipping-methods` (getShippingMethodsForShipment)<br>`PUT /baskets/{basketId}/storefront` (updateAsStorefrontBasket)<br>`GET /baskets/{basketId}/taxes` (getTaxesFromBasket)<br>`PUT /baskets/{basketId}/taxes` (addTaxesForBasket)<br>`POST /orders` (createOrder)<br>`GET /orders/oms-meta-data` (getOmsMetaData)<br>`GET /orders/{orderNo}` (getOrder)<br>`POST /orders/{orderNo}/lookup` (guestOrderLookup)<br>`POST /orders/{orderNo}/actions/fail` (failOrder)<br>`POST /orders/{orderNo}/actions/oms-cancel-order` (cancelOmsOrder)<br>`POST /orders/{orderNo}/actions/oms-return-order` (returnOmsOrder)<br>`POST /orders/{orderNo}/payment-instruments` (createPaymentInstrumentForOrder)<br>`DELETE /orders/{orderNo}/payment-instruments/{paymentInstrumentId}` (removePaymentInstrumentFromOrder)<br>`PATCH /orders/{orderNo}/payment-instruments/{paymentInstrumentId}` (updatePaymentInstrumentForOrder)<br>`GET /orders/{orderNo}/payment-methods` (getPaymentMethodsForOrder)<br>`GET /orders/{orderNo}/taxes` (getTaxesFromOrder)<br>`GET /payment-configuration` (getPaymentConfiguration)<br>`POST /payment-instruments/balance` (getPaymentInstrumentBalance) |
| `sfcc.shopper-categories`                      | `GET /categories` (getCategories)<br>`GET /categories/{id}` (getCategory)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `sfcc.shopper-customers.login`                 | `POST /customers/password/actions/reset` (resetPassword)<br>`POST /customers/password/actions/create-reset-token` (getResetPasswordToken)<br>`GET /customers/external-profile` (getExternalProfile)<br>`PUT /customers/{customerId}/password` (updateCustomerPassword)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `sfcc.shopper-customers.register`              | `POST /customers` (registerCustomer)<br>`POST /customers/external-profile` (registerExternalProfile)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `sfcc.shopper-gift-certificates`               | `POST /gift-certificate` (getGiftCertificate)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `sfcc.shopper-myaccount.addresses.rw`          | `GET /customers/{customerId}/addresses/{addressName}` (getCustomerAddress)<br>`POST /customers/{customerId}/addresses` (createCustomerAddress)<br>`DELETE /customers/{customerId}/addresses/{addressName}` (removeCustomerAddress)<br>`PATCH /customers/{customerId}/addresses/{addressName}` (updateCustomerAddress)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `sfcc.shopper-myaccount.baskets`               | `GET /customers/{customerId}/baskets` (getCustomerBaskets)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `sfcc.shopper-myaccount.orders`                | `GET /customers/{customerId}/orders` (getCustomerOrders)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `sfcc.shopper-myaccount.paymentinstruments.rw` | `POST /customers/{customerId}/payment-instruments` (createCustomerPaymentInstrument)<br>`GET /customers/{customerId}/payment-instruments/{paymentInstrumentId}` (getCustomerPaymentInstrument)<br>`DELETE /customers/{customerId}/payment-instruments/{paymentInstrumentId}` (deleteCustomerPaymentInstrument)<br>`PATCH /customers/{customerId}/payment-instruments/{paymentInstrumentId}` (updateCustomerPaymentInstrument)<br>`DELETE /customers/{customerId}/payment-method-references/{paymentMethodReferenceId}` (deleteCustomerPaymentMethodReference)<br>`POST /customers/{customerId}/payment-method-references/actions/setup` (setupCustomerPaymentMethodReference)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `sfcc.shopper-myaccount.productlists.rw`       | `GET /customers/{customerId}/product-lists` (getCustomerProductLists)<br>`POST /customers/{customerId}/product-lists` (createCustomerProductList)<br>`GET /customers/{customerId}/product-lists/{listId}` (getCustomerProductList)<br>`DELETE /customers/{customerId}/product-lists/{listId}` (deleteCustomerProductList)<br>`PATCH /customers/{customerId}/product-lists/{listId}` (updateCustomerProductList)<br>`POST /customers/{customerId}/product-lists/{listId}/items` (createCustomerProductListItem)<br>`GET /customers/{customerId}/product-lists/{listId}/items/{itemId}` (getCustomerProductListItem)<br>`DELETE /customers/{customerId}/product-lists/{listId}/items/{itemId}` (deleteCustomerProductListItem)<br>`PATCH /customers/{customerId}/product-lists/{listId}/items/{itemId}` (updateCustomerProductListItem)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `sfcc.shopper-myaccount.rw`                    | `GET /customers/{customerId}` (getCustomer)<br>`PATCH /customers/{customerId}` (updateCustomer)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sfcc.shopper-configurations`                  | `GET /configurations` (getConfigurations)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `sfcc.shopper-product-search`                  | `GET /product-search` (productSearch)<br>`GET /search-suggestions` (getSearchSuggestions)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `sfcc.shopper-productlists`                    | `GET /product-lists` (getPublicProductListsBySearchTerm)<br>`GET /product-lists/{listId}` (getPublicProductList)<br>`GET /product-lists/{listId}/items` (getPublicProductListItems)<br>`GET /product-lists/{listId}/items/{itemId}` (getProductListItem)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `sfcc.shopper-products`                        | `GET /products` (getProducts)<br>`GET /products/{id}` (getProduct)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `sfcc.shopper-promotions`                      | `GET /promotions` (getPromotions)<br>`GET /promotions/campaigns/{campaignId}` (getPromotionsForCampaign)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `sfcc.shopper-stores`                          | `GET /stores` (getStores)<br>`GET /store-search` (searchStores)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `sfcc.shopper-experience`                      | `GET /pages` (getPages)<br>`GET /pages/{pageId}` (getPage)<br>`GET /components/{componentId}` (getComponent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `sfcc.shopper-delivery-estimates`              | `GET /delivery-estimates` (getDeliveryEstimates)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `sfcc.shopper-availability`                    | `GET /availability` (getAvailability)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

## Adding Additional Scopes

To add additional scopes beyond those included in `sfcc.shopper-standard`, append them to the client’s scopes list. For example, this scopes list specifies a client with all the scopes from `sfcc.shopper-standard` plus `sfcc.pwdless_login`.

```json
sfcc.shopper-standard sfcc.pwdless_login
```

For more information on specific scopes, see [Authorization Scopes Catalog](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

## When Not to Use sfcc.shopper-standard

Don’t use `sfcc.shopper-standard` if it contains any scopes that you don’t want assigned to the client. It isn’t possible to customize the set of scopes included in `sfcc.shopper-standard`. Instead, you must explicitly list each scope that you want. For example, here’s the scopes list for a client with all the scopes from `sfcc.shopper-standard` except for the `myaccount` scopes.

```json
sfcc.shopper-baskets-orders.rw sfcc.shopper-categories sfcc.shopper-customers.login sfcc.shopper-customers.register sfcc.shopper-gift-certificates sfcc.shopper-configurations sfcc.shopper-product-search sfcc.shopper-productlists sfcc.shopper-products sfcc.shopper-promotions sfcc.shopper-stores
```

<!-- document id=bc09f6585c8c0c999dcdd1924026b14990d2d3a73d3262e348ee0be4578a8a6c url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-start-checkout.md -->

# Start Checkout

Create a checkout session and initialize background calculators.

**Endpoint:** PUT [`/commerce/webstores/{webstoreId}/checkouts`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_start_checkout.htm)

**What happens:**

- Checks for existing checkout session and returns it if found
- Creates new checkout session if none exists
- Runs pricing, promotions, and inventory calculators
- Runs shipping and tax calculators if address is available

![Diagram of the start checkout flow in B2B Commerce showing how a checkout session is initiated from a cart](https://developer.salesforce.com/media/d2c-commerce/commerce-start-checkout.png '{"class": "image-lg", "title": "Start Checkout"}')

**Request parameters:**

- `cartId` (string) — **Required**. The ID of the shopping cart.
- `deliveryAddressInput` — **Optional**. Input for the delivery address.
- `customFields` — **Optional**. Custom fields to include.

**Response includes:**

- `checkoutId`
- `deliveryGroups`
- `contactInfo`
- `errors`
- `statusCode`
- `cartSummary`
- `orderReferenceNumber`
- `customFields`

**Processing and Validation Steps:**

- The system validates access to the specified webstore.
- The system validates access to the shopping cart (`cartId`).
- The system validates the cart status.
- If `deliveryAddressInput` is provided, the system validates the delivery address.
- The system checks if an active Checkout Session already exists for the cart; if so, the system retrieves and returns it.
- If no existing Checkout Session is found, the system creates a new session and returns the `checkoutId` in the response.
- If `shouldUseDefaultAddress` is set to true, the system retrieves and validates the address associated with the Contact Point Address (CPA) or Profile. The system then applies this address to the CartDeliveryGroup object.
- For guest users, if the request includes `deliveryAddressInput`, the system validates the provided address and applies it to the CartDeliveryGroup object.

**Response codes:**

- 200 OK – Checkout session ready, all calculations complete
- 202 Accepted – Processing in progress, poll GET endpoint until you receive 200

<!-- document id=ed353b5aa1312ad0bd0abe669fb72af49ad86fe54e4cd74d020ffee7bfc5b2e6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-starting-customer-service-center.md -->

# Start Customer Service Center

With Customer Service Center, an agent can find or create an order, and find a customer. The agent must have permission to use Customer Service Center.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Ordering** > **Customer Service Center**.
2.  Select an action.

    - Find an Order
    - Create a New Order
    - Find a Customer

3.  To view the menu or return to the Welcome page, click the menu icon.

    The Customer Service Center opens in a new tab. To return to Business Manager, click the original tab in your browser. When you click the sidebar navigation, only a single instance of the tab is opened. If a tab is already open, clicking the sidebar brings the tab into view.

4.  To log out of the site, click the menu in the top-right corner.

    The current user appears in the top-right corner of every page. The Log Out button is part of this menu. The current site also appears in this menu.

5.  To switch to a different site, click the menu in the top-right corner.

<!-- document id=d9f87a456f09849bde0928d416562d9c1b8a6df1da19f222db4f6abf0ec34722 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_start_and_stop_an_instance.md -->

# Start, Stop, and Restart Instances in Control Center

If you have sufficient permissions, restart any running instance, stop any running on-demand sandboxes (ODS), and start any instance whose status is Administratively down or System down.

1. Log into Control Center.
2. Click **Instances**.
3. Select the instance you want to start, stop, or restart.
4. Click **start**, **stop**, or **restart**. When you click one of these actions, a confirmation message appears.
5. Click **Yes**.

Control Center attempts to start, stop, or restart the instance, and changes the instance's status as appropriate.

**note:** Starting or restarting an instance can take several minutes.

<!-- document id=dc78d71e30fd3d7471f72441b7866a4530b618958f2972acb492aca95951f257 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/managing-global-state.md -->

# State Management

Some storefront applications demand a way to manage global state. There are many state-management libraries out there that help you do just that, such as [Redux](https://redux.js.org/) and [MobX](https://mobx.js.org/README.html). Salesforce does not endorse one particular state-management library over any other—and you can build a PWA Kit app without using one at all.

You can always provide state information to your components via props, but if you want to use React’s more advanced features for managing state, this guide covers other approaches too.

## Using Props

The simplest technique for sharing state among components is to provide that state information via props to a component. That component must be a parent to all the components that need to access the state data. The React docs describe this technique in detail and call it [lifting state up](https://reactjs.org/docs/lifting-state-up.html).

## Using the React Context API

React’s [Context API](https://reactjs.org/docs/context.html) simplifies the process of making data available to a large number of components, without having to manually pass that data through props at each level of your app’s component tree.

### React Context Example

Here’s an example of how you might use the React Context API with a component that acts as a wrapper around all of your components to provide them with shared state data.

Start by creating a component called `GlobalState` that has two context objects:

1.  `GlobalStateContext`: where you can store global state data.
2.  `GlobalDispatchContext`: your `dispatch` function, which returns an updated snapshot of global state through a reducer function.

Each context object comes with a `<Provider>` component that allows consuming components to subscribe to context changes. Here, the context objects are initialized with the props `initialState` and `dispatch`. You get these props when you connect your state with a `reducer`, using the `useReducer` Hook. For more information on React Hooks, including how to use them with the Context API, see the official [React Hooks reference documentation](https://reactjs.org/docs/hooks-reference.html).

Here’s how you would define and initialize a component that uses the Context API for storing global state in your storefront app:

```javascript
// app/components/_app-config/index.jsx

import {createContext, useContext} from 'react'

export const GlobalContext = createContext()
export const useGlobalState = () => useContext(GlobalContext)

const AppConfig = (props) => {
    const [globalState, setGlobalState] = useState({
        customer: {name: 'Samantha', registered: true},
    })

    return (
        <GlobalContext.Provider value={(globalState, setGlobalState)}>
            {props.children}
        </GlobalContext.Provider>
    )
}

// app/pages/page/index.jsx

import React, {useContext} from 'react'
import {useGlobalState} from 'components/_app-config'

export const Page = () => {
    const {customer, setGlobalState} = useGlobalState()

    // Use setGlobalState to change the global state.

    return <div>{customer.name}</div>
}
```

The `AppConfig` special component located in `app/components/_app-config/index.jsx` is where you can initialize your state management system. Here, `props.children` contains all the components of your app, so that's where you want to add your `GlobalState` component.

To get the props object you need to initialize it first. Use the React Hook `useReducer` to create a connected state to your reducer. The `useReducer` function takes in an `initialState` object and the `reducer` imported from the GlobalState component. Next, pass in the connected state and a `dispatch` function to modify that state.

For example:

```javascript
// <PROJECT_DIR>/app/components/_app-config/index.jsx

// Replace your existing React imports
import React, { useState }, { useReducer }, from "react"

// Import GlobalState component defined in previous example
import GlobalState, { reducer } from "../global-state"

const initialState = {
  cart: null
}

// Combine this with your existing AppConfig component code
function AppConfig(props) {
  const [state, dispatch] = useReducer(reducer, initialState);

  return (
    <GlobalState initialState={state} dispatch={dispatch}>
      {props.children}
    </GlobalState>
  )
}
```

Now you can give any component access to your global context data, including the ability to update it. Import `GlobalStateContext` and `GlobalDispatchContext` from your `GlobalState` component and provide those context objects to the `useContext()` method.

For example:

```javascript
import React, {useContext} from 'react'
import {GlobalStateContext, GlobalDispatchContext, SET_CART_ITEMS} from 'app/components/global-state'

function ExamplePage() {
    const globalState = useContext(GlobalStateContext)
    const dispatch = useContext(GlobalDispatchContext)

    // Use this where you want to update the cart data in your global state
    dispatch({type: SET_CART_ITEMS, payload: cartItems})

    return ( /* render something */ )
}
```

## Using a State-Management Library

You can customize your application to use a state management library by overriding the default `AppConfig` special component located in `app/components/_app-config/index.jsx`.

### Redux Example

Here's how to set up Redux for your PWA by inside `AppConfig`. The component has four methods that you need to use:

1.  The `restore` method is where you create your Redux store with a reducer, initial state, and any middleware.
2.  The `freeze` method allows you to freeze your state management backend for embedding into the page HTML.
3.  The `extraGetPropsArgs` method is where you can return any extra arguments that you’d like to inject into `getProps` methods across the entire app. In this case, we can return the Redux store as an extra argument.
4.  The `render` method allows you to set up context providers for a state management library. For example, you can use it to wrap the app in a Redux provider.

Here is a brief example showing how to use the methods of `AppConfig` to set up Redux for your storefront app. In addition to the steps we show here, a complete solution requires you to create your store with a reducer, initial state, and any required middleware.

```javascript
// <PROJECT_DIR>/app/components/_app-config/index.jsx

// Combine these imports with your existing imports to include Redux
imports import React, { useState }, { useReducer }, from "react"
import PropTypes from "prop-types"
import { createStore } from "redux"
import { Provider } from "react-redux"

/**
 * Combine this code with your existing AppConfig code to use Redux by injecting store object and dispatch function into all getProps() functions.
 */

class AppConfig extends React.Component {
  static restore(locals, frozen = {}) {
    // create your store with a reducer, initial state, and any middleware.
    const initialState = isServerSide ? {} : frozen
    locals.store = createStore(reducer, initialState, middlewares)
  }
  static freeze(locals) {
    return locals.store.getState()
  }
  static extraGetPropsArgs(locals) {
    return {
      store: locals.store,
      dispatch: locals.store.dispatch
    }
  }

  /**
   * The render function will wrap the app in a Redux provider.
   */
  render() {
    const { children, locals } = this.props
    return <Provider store={locals.store}>{children}</Provider>
  }
}

AppConfig.propTypes = {
  children: PropTypes.node,
  locals: PropTypes.object
}

export default AppConfig
```

<!-- document id=d819267520827b295993b50aee6fde14b54871752157a5210095cce8f7cc00df url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-state-management.md -->

# State Management

React Router fundamentally changes how you think about client-side state. Its `loader`/`action` pattern handles the most common use case for global state management libraries, such as [Redux](https://redux.js.org), [React Query](https://tanstack.com/query), or [Zustand](https://github.com/pmndrs/zustand): fetching server data and keeping it synchronized after mutations. Since React Router manages this natively, you typically don’t need a separate library for such _remote state_.

**What this means in practice:** A server-centric model replaces the classic client-side fetch-on-mount, store-in-state, manually-invalidate cycle:

1. Route enters, `loader()` runs, and then data flows into the component. For example, data flows via the [`useLoaderData()`](https://reactrouter.com/api/hooks/useLoaderData) hook.
2. User submits form, `action()` runs, and then React Router revalidates all loaders automatically.

## State Types and Their Native Tools

| State Type                                                             | Description                                 | Native Tool                                          |
| ---------------------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------- |
| [Server / Remote State](#server-state-via-loader-and-action)           | Data fetched from a server                  | `loader` + `useLoaderData`                           |
| [Mutations](#mutations-via-action-and-form)                            | Write operations to the server              | `action` + `Form`                                    |
| [Component-Local Mutations](#component-local-mutations-via-usefetcher) | Mutations without navigation                | `useFetcher`                                         |
| [Cross-Route Data](#cross-route-data-via-userouteloaderdata)           | Accessing another route’s loader data       | `useRouteLoaderData`                                 |
| [Middleware Context](#middleware-context)                              | Request-scoped data injected before loaders | `context.set` / `context.get`                        |
| [Navigation State](#navigation-state)                                  | Current navigation in progress              | `useNavigation`                                      |
| [URL State](#url-state)                                                | State encoded in the URL                    | `useSearchParams`, `useParams`                       |
| [Persistent State](#persistent-state-via-cookies-and-sessions)         | State persisted across requests via cookies | `createCookie`, `createCookieSessionStorage`         |
| [Optimistic State](#optimistic-state)                                  | Temporary UI before server confirms         | `fetcher.formData`, `useNavigation`, `useOptimistic` |
| [Error State](#error-state)                                            | Loader/action errors per route              | `useRouteError`                                      |
| [React Primitives](#native-react-state-primitives)                     | Native React state management primitives    | `useState`, `useMemo`, Context API, and so on        |

## Server State via loader() and action()

This is the central state management pattern in React Router. It replaces client-side data fetching patterns, such as fetch-on-mount and manual cache invalidation, with a declarative, server-centric model.

- A `loader` runs on the server before the route renders. Its return value becomes the component’s data via [`useLoaderData()`](https://reactrouter.com/api/hooks/useLoaderData).
- An `action` handles mutations. After it completes, React Router automatically revalidates all active loaders. React Router manages the data lifecycle entirely.

For [loader](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#loaders), [data classification](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#data-classification) (critical vs. non-critical), streaming patterns, [action processing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#actions), and [resource routes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#resource-routes), see [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md).

## Mutations via action() and Form

The `<Form>` component serializes form state into `FormData` and submits it to the route’s `action`. After the action completes, React Router revalidates all active loaders automatically. This is the primary mutation pattern when the operation **_should trigger a navigation_** or a full-page state update.

For action arguments, validation patterns, and examples, see [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#actions).

## Component-Local Mutations via useFetcher()

[`useFetcher`](https://reactrouter.com/api/hooks/useFetcher) triggers loaders and actions **_without causing navigation_**. It gives each component its own mutation lifecycle, making it suitable for inline edits, autosave, toggling, and any mutation that shouldn’t change the URL.

From a state management perspective, each fetcher exposes its own lifecycle. `fetcher.state` exposes the mutation lifecycle while `fetcher.data` holds the action’s return value. This enables per-component feedback (for example, inline validation errors) without global state.

For fetcher usage patterns and resource routes, see [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#fetchers). For visual feedback patterns based on `fetcher.state`, see [Loading States](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md#the-usefetcher-hook).

## Cross-Route Data via useRouteLoaderData()

[`useRouteLoaderData`](https://reactrouter.com/api/hooks/useRouteLoaderData) accesses the loader data of any currently active route by its route ID. This avoids prop-drilling when a child route needs data that a parent or sibling route already loaded.

A common use case is accessing root-level data, such as session, locale, or site configuration, from deeply nested routes without passing it through every intermediate layout. The route ID passed to `useRouteLoaderData` must match the route’s `id` as defined in the route configuration. The hook returns `undefined` if the target route isn’t currently active.

```jsx
// routes/root.tsx
export async function loader() {
  const user = await getUser();
  const locale = await getLocale();
  return { user, locale };
}

// routes/products/product-detail.tsx
import { useRouteLoaderData } from "react-router";

export default function ProductDetail() {
  const rootData = useRouteLoaderData<typeof rootLoader>("root");
  return <p>Welcome, {rootData?.user?.name}</p>;
}
```

## Middleware Context

Middleware context is React Router’s mechanism for request-scoped dependency injection. Middlewares run in a pipeline _before_ loaders and actions, populating a typed context object with data that all downstream loaders and actions can access. This eliminates the need for loaders to independently resolve cross-cutting concerns such as sessions, app configuration, or API clients.

For middleware definition, pipeline ordering, and writing middleware functions, see [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#middlewares).

**note:** Middleware context isn’t the React Context API. While middleware context carries server-side data, it serves a distinct role from loaders. Middleware context operates in the request lifecycle (before render), is consumed by loaders and actions, and is scoped to a single request. The React [Context API](#shared-ui-state) operates in the render lifecycle and is consumed by components. Data from middleware context typically reaches components via the `loader` return value and `useLoaderData`.

## Navigation State

[`useNavigation`](https://reactrouter.com/api/hooks/useNavigation) exposes the global navigation state, useful for pending UI during route transitions.

```jsx
import { useNavigation } from "react-router";

function GlobalSpinner() {
  const navigation = useNavigation();
  if (navigation.state === "idle") {
    return null;
  }
  return <Spinner />;
}
```

`navigation.formData` is available during form submissions, enabling optimistic UI based on the submitted values before the server responds. For loading state patterns in detail, see [Loading States](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md).

## URL State

The URL is a state container. Search parameters, path parameters, and the location object are reactive state sources that survive page refreshes, are shareable via links, and integrate with the browser’s history stack.

### useSearchParams()

[`useSearchParams`](https://reactrouter.com/api/hooks/useSearchParams) reads and writes URL query parameters. It replaces `useState` for state that should be reflected in the URL, such as filters, pagination, sort order, or modal visibility.

**When to use `useSearchParams` over `useState`:** If the state should survive a page refresh, be shareable via URL, or be accessible to loaders (via `request.url`), it belongs in search params.

```jsx
import { useSearchParams } from "react-router";

function ProductFilters() {
  const [searchParams, setSearchParams] = useSearchParams();
  const category = searchParams.get("category") ?? "all";

  return (
    <select value={category} onChange={(e) => setSearchParams({ category: e.target.value })}>
      <option value="all">All</option>
      <option value="shoes">Shoes</option>
      <option value="bags">Bags</option>
    </select>
  );
}
```

### useParams()

[`useParams`](https://reactrouter.com/api/hooks/useParams) returns the dynamic path parameters for the current route. It’s read-only and reactive, the component re-renders when the route changes.

```jsx
import { useParams } from "react-router";

function ProductDetail() {
  const { productId } = useParams();
  // productId is derived from the URL, e.g., /products/:productId
}
```

## Persistent State via Cookies and Sessions

Sometimes, state must survive page refreshes and revisits without belonging to the URL. Examples include user preferences (theme, locale, dismissed banners), shopping cart identifiers, and authentication tokens. Cookies and server sessions are React Router’s native mechanism for this kind of persistent state.

Unlike `useState` (transient) or `useSearchParams` (URL-visible), cookies travel with every HTTP request and are available in loaders and actions on the server. This behavior makes cookies a single source of truth that requires no client-side synchronization, avoids `localStorage` SSR issues, and works even before scripts load.

React Router provides [`createCookie`](https://reactrouter.com/explanation/sessions-and-cookies#cookies) for simple key-value cookies and [`createCookieSessionStorage`](https://reactrouter.com/explanation/sessions-and-cookies#sessions) for structured, typed session data. Both integrate directly with the `loader`/`action` lifecycle: cookies are read via `request.headers.get('Cookie')` and written via `Set-Cookie` response headers.

### When to Use Cookies vs. Sessions vs. URL State

| Criterion                   | Cookies (`createCookie`)  | Sessions (`createCookieSessionStorage`) | URL (`useSearchParams`)   |
| --------------------------- | ------------------------- | --------------------------------------- | ------------------------- |
| Survives page refresh       | Yes                       | Yes                                     | Yes                       |
| Shareable via link          | No                        | No                                      | Yes                       |
| Available in loaders        | Yes                       | Yes                                     | Yes (via `request.url`)   |
| Works without JS            | Yes                       | Yes                                     | Only with `<Form>`        |
| Structured / typed data     | Manual parsing            | Built-in typed API                      | String key-value pairs    |
| Security (httpOnly, signed) | Yes                       | Yes (with secrets)                      | No (user-visible)         |
| Best for                    | Simple preferences, flags | Auth, multi-field user state            | Filters, pagination, sort |

For details on cookies and sessions APIs, see [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md#cookies-and-sessions).

## Optimistic State

Optimistic UI updates the interface immediately, before the server confirms the mutation, and rolls back if the operation fails. React Router and React offer complementary approaches, each suited to a different kind of state.

### Via fetcher.formData (React Router)

`useFetcher` exposes the submitted `formData` while an action is in flight. This enables optimistic reads directly from the pending submission without additional state management. This pattern requires no extra hooks and works with any version of React. It’s the idiomatic React Router approach for simple optimistic updates derived from the submitted form values.

```jsx
const fetcher = useFetcher();

const isComplete = fetcher.formData ? fetcher.formData.get("complete") === "true" : item.complete;

return (
  <fetcher.Form method="post" action="/api/toggle">
    <input type="hidden" name="complete" value={String(!item.complete)} />
    <button type="submit">{isComplete ? "✓ Complete" : "Mark complete"}</button>
  </fetcher.Form>
);
```

### Via useNavigation() (React Router, URL-Driven State)

When state is serialized into URL search parameters and updates trigger a `navigate()` call, `useNavigation()` provides a navigation-aware optimistic path. While a navigation is pending, `navigation.location` holds the target `Location` object. Reading the intended query parameters from that target reflects the user’s action immediately, without any local state to manage.

```jsx
import { useNavigation } from "react-router";

function Filters({ items }: { items: string[] }) {
  const navigation = useNavigation();

  // While a navigation is pending, read from the target URL.
  // Once it settles, fall back to the server-provided props.
  const effectiveItems = navigation.location
    ? new URLSearchParams(navigation.location.search).getAll("item")
    : items;

  return (
    <ul>
      {effectiveItems.map((item) => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  );
}
```

This works because `navigation.location` is only defined while a navigation is in flight. It holds the destination URL, so the component can derive the optimistic state from the search params the router is navigating to. When the navigation completes, `navigation.location` becomes `undefined` in the same render cycle that delivers the fresh loader props. The ternary falls through to the new server data automatically.

Key properties of this pattern:

- No local state: Nothing to sync, reset, or reconcile.
- Survives the pending phase: The optimistic value is read from the URL the router is navigating to, so it persists for the entire loader fetch.
- Self-cleaning: Once the navigation settles, the component naturally falls back to the new props.

**note:** `useNavigation()` reflects _any_ in-flight navigation, not just the one the current component triggered. In practice this is acceptable: if a different navigation starts, the entire page is about to change anyway. For mutations that don’t change the URL, prefer `fetcher.formData` or `useOptimistic` instead.

### Via useOptimistic() (React)

[`useOptimistic`](https://react.dev/reference/react/useOptimistic) applies a temporary state update that React automatically reverts once the underlying async operation settles. It’s suited for more complex optimistic transformations where the optimistic state isn’t a direct read from `formData` or the URL, for example, inserting a new item into a list.

```jsx
import { useOptimistic } from 'react';

function ProductList({ products }: { products: Product[] }) {
  const [optimisticProducts, addOptimistic] = useOptimistic(
    products,
    (state, newProduct: Product) => [...state, newProduct]
  );

  async function handleAdd(formData: FormData) {
    const name = formData.get('name') as string;
    addOptimistic({ id: 'temp', name }); // Immediate UI update
    await createProduct(name);           // Actual server call
  }

  return (
    <>
      <form action={handleAdd}>
        <input name="name" />
        <button type="submit">Add</button>
      </form>
      <ul>
        {optimisticProducts.map(p => (
          <li key={p.id} style={{ opacity: p.id === 'temp' ? 0.5 : 1 }}>
            {p.name}
          </li>
        ))}
      </ul>
    </>
  );
}
```

## Error State

React Router treats errors from loaders and actions as a first-class route state. When a loader or action throws an error, React Router catches the error and renders the nearest [`ErrorBoundary`](https://reactrouter.com/start/framework/route-module#errorboundary) export in the route hierarchy.

[`useRouteError`](https://reactrouter.com/api/hooks/useRouteError) accesses the thrown error inside an `ErrorBoundary`. [`isRouteErrorResponse`](https://reactrouter.com/api/utils/isRouteErrorResponse) distinguishes between Response-based errors (thrown via `throw new Response(...)` or [`data()`](https://reactrouter.com/api/utils/data) with a non-2xx status in a loader or action) and unexpected exceptions. This behavior enables differentiated error UIs, for example, a styled 404 page vs. a generic error fallback.

```jsx
// routes/products.tsx
import { useRouteError, isRouteErrorResponse } from "react-router";

export function ErrorBoundary() {
  const error = useRouteError();

  if (isRouteErrorResponse(error)) {
    return (
      <div>
        <h1>{error.status}</h1>
        <p>{error.statusText}</p>
      </div>
    );
  }

  return <div>An unexpected error occurred.</div>;
}
```

## Native React State Primitives

The sections above cover state that React Router manages as part of the routing and data lifecycle. What remains to complete the picture, is state that lives entirely on the client, managed by React’s own primitives. These are the built-in hooks and patterns for local component state, derived values, cross-component sharing, and integration with external stores.

### Local UI State

#### useState()

The baseline primitive for synchronous, isolated state within a single component. Use the [`useState`](https://react.dev/reference/react/useState) hook when exactly one component owns the state and you don’t need to share it.

```jsx
function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount((c) => c + 1)}>{count}</button>;
}
```

#### useReducer()

The [`useReducer`](https://react.dev/reference/react/useReducer) hook is preferable over `useState` when state transitions are complex, interdependent, or benefit from explicit action semantics.

```jsx
type State = { count: number, step: number };
type Action = { type: "increment" } | { type: "setStep", payload: number };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case "increment":
      return { ...state, count: state.count + state.step };
    case "setStep":
      return { ...state, step: action.payload };
  }
}

function Counter() {
  const [state, dispatch] = useReducer(reducer, { count: 0, step: 1 });
  return (
    <>
      <p>Count: {state.count}</p>
      <button onClick={() => dispatch({ type: "increment" })}>+</button>
      <input
        type="number"
        value={state.step}
        onChange={(e) => dispatch({ type: "setStep", payload: Number(e.target.value) })}
      />
    </>
  );
}
```

### Derived Local UI State

Derived state is any value you compute from existing state or props rather than store independently. It’s a pure function of other state and has no source of truth of its own.

**Key rule:** Don’t store derived values in `useState`. This practice creates a secondary source of truth and forces manual synchronization, which is a common source of bugs.

```jsx
// Bad: redundant state, sync required
const [fullName, setFullName] = useState(`${firstName} ${lastName}`);

// Good: computed inline, always in sync
const fullName = `${firstName} ${lastName}`;
```

#### useMemo()

[`useMemo`](https://react.dev/reference/react/useMemo) caches the result of an expensive computation and only recalculates it when one of its dependencies changes, preventing unnecessary recalculation on every render. Use this for expensive transformations, such as sorting, filtering, and aggregating, over arrays or objects.

**When to use `useMemo`:** For cheap computations, a plain variable in the render body is sufficient. Reserve `useMemo` for expensive computations or when referential stability is required (for example, as a dependency in `useEffect` or `memo`).

```jsx
// Plain variable: fine for cheap ops
const fullName = `${firstName} ${lastName}`;

// useMemo: justified for expensive ops or stable references
const filteredItems = useMemo(() => largeList.filter((item) => item.active), [largeList]);
```

#### useCallback()

[`useCallback`](https://react.dev/reference/react/useCallback) memoizes a function reference. Without it, every render creates a new function instance, which breaks referential equality checks in child components wrapped with [`memo`](https://react.dev/reference/react/memo).

```jsx
const handleDelete = useCallback((id: string) => {
  setProducts((prev) => prev.filter((p) => p.id !== id));
}, []); // stable reference — no unnecessary re-renders in React.memo children
```

**When `useCallback` isn’t needed:** If `memo` doesn’t wrap the receiving component, `useCallback` has no observable effect and only adds noise. Apply it specifically when passing callbacks to memoized components or as dependencies of other hooks (`useEffect`, `useMemo`) where referential stability matters.

### Shared UI State

[Context](https://react.dev/learn/passing-data-deeply-with-context) propagates state through the React tree without prop drilling. It’s appropriate for state that changes infrequently and must be accessible across many components.

**note:** For request-scoped data that loaders and actions need (session, auth, and config), see [Middleware Context](#middleware-context). The React Context API is for UI state shared across the component tree during rendering.

**Good use cases:** Locale, user preferences, and feature flags.

**Poor use cases:** High-frequency updates (for example, mouse position, real-time data), large state objects where many consumers only need a small slice.

#### Basic Setup

```jsx
// preferences-context.tsx
type PreferencesState = {
  density: "compact" | "comfortable",
  setDensity: (d: "compact" | "comfortable") => void,
};
const PreferencesContext = createContext<PreferencesState | null>(null);

export function PreferencesProvider({ children }: { children: React.ReactNode }) {
  const [density, setDensity] = useState<"compact" | "comfortable">("comfortable");

  return (
    <PreferencesContext.Provider value={{ density, setDensity }}>
      {children}
    </PreferencesContext.Provider>
  );
}

export function usePreferences() {
  const ctx = useContext(PreferencesContext);
  if (!ctx) {
    throw new Error("usePreferences must be used within PreferencesProvider");
  }
  return ctx;
}
```

**note:** Every context value change re-renders all its consumers, regardless of whether they use the changed part of the value. Mitigate this by splitting contexts. A component using, for example, only `PreferencesContext` doesn't re-render when `user` changes.

```jsx
// Instead of one large context:
<AppContext.Provider value={{ user, preferences, locale }} />

// Split into focused contexts:
<UserContext.Provider value={user} />
<PreferencesContext.Provider value={preferences} />
<LocaleContext.Provider value={locale} />
```

### Context Selector Pattern

When a context holds multiple values but a consumer only needs one slice, splitting contexts isn't always practical. Domain stores often have many fields and many consumers each needing different slices. The selector pattern addresses this demand by accepting a selector function and returning only the selected slice. Combined with [`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore), subscriptions are per-slice: a consumer re-renders only when its slice changes.

The context holds a reference to an external store, not the state itself. The hook drives the subscription via `useSyncExternalStore`:

```jsx
const StoreLocatorContext = createContext<StoreApi<StoreLocatorState> | null>(null);

export function useStoreLocator<T>(selector: (state: StoreLocatorState) => T): T {
  const store = useContext(StoreLocatorContext);
  if (!store) {
    throw new Error('useStoreLocator must be used within StoreLocatorProvider');
  }
  const getSnapshot = useCallback(() => selector(store.getState()), [store, selector]);
  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot);
}
```

Consumers call the hook once per slice. The badge re-renders only when `isOpen` flips. The form re-renders only when `config` changes:

```jsx
function StoreLocatorBadge() {
  const isOpen = useStoreLocator((s) => s.isOpen);
  const close = useStoreLocator((s) => s.close);
  // ...
}

function StoreLocatorForm() {
  const config = useStoreLocator((s) => s.config);
  // ...
}
```

**note:** React's `useContext` doesn't support selectors natively—every consumer re-renders on any context value change. A selector hook that only wraps `useContext` is a convention and doesn't, by itself, skip renders. Actual render memoization requires either `useSyncExternalStore`, as shown earlier, which is tearing-safe and concurrent-mode correct, or `React.memo` on the consuming component, combined with a referentially stable selector result. For high-frequency updates on large domain stores, prefer the `useSyncExternalStore` approach.

### Global Client State via useSyncExternalStore()

[`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore) integrates state that lives **outside the React tree**—vanilla JavaScript objects, browser APIs, or custom event emitters. It is concurrent-mode safe and does not require a Provider.

#### Building a Minimal Store

```typescript
// store.ts
type Listener = () => void;

function createStore<T>(initialState: T) {
  let state = initialState;
  const listeners = new Set<Listener>();

  return {
    getSnapshot: () => state,
    subscribe: (listener: Listener) => {
      listeners.add(listener);
      return () => listeners.delete(listener);
    },
    setState: (updater: (prev: T) => T) => {
      state = updater(state);
      listeners.forEach((fn) => fn());
    },
  };
}

export const cartStore = createStore({ items: [] as CartItem[] });
```

```typescript
// useCart.ts
import { useSyncExternalStore } from "react";
import { cartStore } from "./store";

export function useCart() {
  const state = useSyncExternalStore(cartStore.subscribe, cartStore.getSnapshot);

  return {
    items: state.items,
    addItem: (item: CartItem) => cartStore.setState((s) => ({ items: [...s.items, item] })),
  };
}
```

Every component calling `useCart()` subscribes automatically. No Provider, no wrapping component required.

#### Wrapping Browser APIs

The same pattern makes any browser API reactive:

```typescript
// useOnlineStatus.ts
const subscribe = (cb: () => void) => {
  window.addEventListener("online", cb);
  window.addEventListener("offline", cb);
  return () => {
    window.removeEventListener("online", cb);
    window.removeEventListener("offline", cb);
  };
};

export const useOnlineStatus = () =>
  useSyncExternalStore(
    subscribe,
    () => navigator.onLine,
    () => true, // server snapshot (SSR)
  );
```

The same pattern applies to `matchMedia`, `localStorage`, `BroadcastChannel`, `visibilitychange`, and similar APIs.

#### Critical: getSnapshot Stability

`getSnapshot` must return a **referentially stable value** when state hasn’t changed. Returning a new object on every call causes an infinite render loop.

```typescript
// WRONG — new object reference on every call
getSnapshot: () => ({ ...state });

// CORRECT — same reference when state is unchanged
getSnapshot: () => state;
```

If you need derived/selected state, cache the result inside the store or use `useRef` for memoization.

#### Comparison: useSyncExternalStore() vs. Context API

| Criterion             | `useSyncExternalStore`         | Context API                             |
| --------------------- | ------------------------------ | --------------------------------------- |
| State location        | Outside React (module scope)   | Inside React tree                       |
| Re-render granularity | Only subscribed components     | All consumers of the context            |
| Provider required     | No                             | Yes                                     |
| Concurrent Mode safe  | Yes (tearing-safe by design)   | Partially                               |
| Best for              | High-frequency or global state | Infrequently changing, tree-local state |

### Additional State Primitives

#### use(Promise)

Reads a Promise directly inside a component and integrates with `Suspense`. Eliminates the need for `useEffect`-based data fetching and loading state management. For declarative loading patterns with `use()` and `Suspense`, see [Loading States](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md#the-use-and-suspense-pattern).

```jsx
import { use, Suspense } from "react";

function UserProfile({ userPromise }: { userPromise: Promise<User> }) {
  const user = use(userPromise); // Suspends until resolved
  return <p>{user.name}</p>;
}

function App() {
  const userPromise = fetchUser(userId);
  return (
    <Suspense fallback={<Skeleton />}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  );
}
```

#### useTransition() and useDeferredValue()

`useTransition` marks state updates as non-urgent, keeping the UI responsive during heavy re-renders.

```jsx
const [isPending, startTransition] = useTransition();

function handleSearch(query: string) {
  startTransition(() => {
    setSearchResults(computeResults(query)); // Non-blocking update
  });
}
```

`useDeferredValue` defers the propagation of a rapidly changing value, similar to debouncing but integrated with React’s concurrent scheduler.

```jsx
const deferredQuery = useDeferredValue(searchQuery);
// deferredQuery lags behind searchQuery during rapid input
const results = useMemo(() => search(deferredQuery), [deferredQuery]);
```

#### useActionState()

[`useActionState`](https://react.dev/reference/react/useActionState) manages the full lifecycle of an async action: pending status, return value, and error state. It replaces manual `useState` and `useTransition` wiring around actions. Listed here for completeness as a React primitive.

**note:** In the React Router framework, `useActionState` has no practical relevance. Route `action` + `Form` and `useFetcher` provide the same pending or error lifecycle and additionally trigger automatic loader revalidation after mutations. `useActionState` bypasses React Router’s data lifecycle entirely, loaders aren’t revalidated after a `useActionState` action completes. Even for purely client-side logic, a `clientAction` with `useFetcher` is preferable because it keeps the component within React Router’s consistent data flow and avoids introducing a parallel mutation pattern.

<!-- document id=d2af4e6ebcb4c69062152446ee311bafb21470da362ef5f01d25b7330a32d673 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-state-management.md -->

# State Management Differences with PWA Kit

PWA Kit's state management is React Query-centric, treating the API as the source of truth with sophisticated caching. Storefront Next takes a server-first approach where loaders provide data and client state is minimal and feature-specific. The shift eliminates the need for a dedicated server state library, simplifying the mental model while enabling better streaming and Suspense integration.

## Key Differences

| Aspect           | PWA Kit                      | Storefront Next                    |
| ---------------- | ---------------------------- | ---------------------------------- |
| Primary Approach | React Query for server state | React Router loaders               |
| State Library    | React Query + Context        | React Router Context + React State |
| Caching          | React Query in-memory cache  | Router revalidation                |
| Server State     | Managed by React Query       | Managed by React Router            |
| Persistence      | localStorage                 | Cookies                            |
| Architecture     | Centralized (React Query)    | Decentralized                      |

## Server State Management

PWA Kit uses React Query for all server state:

```javascript
// PWA Kit: Data fetched in component via hooks
const ProductPage = ({ productId }) => {
  const { data, isLoading } = useProduct({ parameters: { id: productId } });
  // Component handles loading state
};
```

Storefront Next uses loaders for server state:

```typescript
// Storefront Next: Data fetched before component renders
export function loader({ params, context }) {
  return { product: fetchProduct(params.productId) };
}

const ProductPage = ({ loaderData }) => {
  const product = use(loaderData.product); // Suspends if not ready
};
```

## Key Similarities

1. React Context for distribution: Both use Context to make state available to components.
2. Provider pattern: Both wrap the app in provider components.
3. Hooks for consumption: Both expose custom hooks (useAuth, useBasket, etc.).
4. Persistence considerations: Both handle localStorage/cookies for persistence.
5. SSR awareness: Both handle server vs client rendering differences.

## Storefront Conversion Considerations

Keep these considerations in mind when converting your storefront from PWA Kit to Storefront Next.

- React Query to Loaders

  - Move data fetching from component hooks to route loaders.
  - Replace `isLoading` checks with Suspense boundaries.
  - Remove React Query configuration and providers.

- Context Simplification

  - Simplify contexts to just hold values (no complex logic).
  - Move complex state to Zustand if needed.
  - Use middleware for initialization instead of provider effects.

- State Persistence

  - Migrate localStorage usage to cookies for SSR compatibility.
  - Use middleware to read persisted state during request processing.

- Derived State
  - Move derived calculations from hooks to selectors (Zustand) or loaders.
  - Use `useMemo` sparingly; prefer computed values in state stores.

<!-- document id=c916c9aab824dea85ac97e59a5bf8e30f533e89072fbf414ea988497a9455e33 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-static-assets.md -->

# Static Assets

Learn how to add and use static files like images, fonts, and other resources in your Storefront Next app.

Storefront Next uses Vite to serve static files from the `public` directory.

## What Are Static Assets?

Static assets are files that your app serves directly without server-side processing. This table shows the common asset types.

| Asset Type | Examples                                | Common Use                        |
| ---------- | --------------------------------------- | --------------------------------- |
| Images     | `.png`, `.jpg`, `.svg`, `.webp`, `.gif` | Product images, logos, icons      |
| Fonts      | `.woff`, `.woff2`, `.ttf`, `.otf`       | Custom typography                 |
| Media      | `.mp4`, `.webm`, `.mp3`                 | Videos, audio files               |
| Documents  | `.pdf`, `.json`                         | Downloadable content, static data |

## The `public` Directory

Files in the `public` directory are served directly at the site root without processing. Vite copies these files as-is to the build output.

```
public/
├── favicon.ico
├── robots.txt
└── images/
    ├── logo.svg
    └── hero.png
```

Use the `public` directory for assets that must retain their exact filename without a content hash.

## Using Assets

Import assets by using an import statement to get the correct path.

```tsx
import logoImage from "/images/logo.svg";

<img src={logoImage} alt="Logo" />;
```

When you import an asset, Vite returns the resolved URL. In development, this is a simple path like `/images/logo.svg`. In production on Managed Runtime (MRT), the path includes the bundle identifier (for example, `/mobify/bundle/362/client/images/logo.svg`).

**note:** Don't use raw paths like `src="/images/logo.svg"` directly in your code. These paths work in development but fail in production because the server requires the full bundle path.

## Adding an Asset

This example demonstrates adding a promotional banner image.

### Step 1: Add the Asset to the Public Directory

```
public/
└── images/
    └── summer-sale.png
```

### Step 2: Import and Use the Asset in Your Component

```tsx
// src/components/promo-banner/index.tsx
import bannerImage from "/images/summer-sale.png";

export function PromoBanner() {
  return (
    <div className="relative w-full overflow-hidden rounded-lg">
      <img
        src={bannerImage}
        alt="Summer sale - up to 50% off"
        className="w-full h-auto"
        loading="lazy"
      />
    </div>
  );
}
```

## Static File Serving in Production

In production on Managed Runtime (MRT), static assets are served from a bundle-specific path (for example, `/mobify/bundle/362/client/`). When you import an asset, Vite automatically resolves to the correct bundle path. The server sets optimized caching headers so browsers cache assets efficiently.

## See Also

- [_Vite:_ Static Asset Handling](https://vite.dev/guide/assets)
- [_Vite:_ The public Directory](https://vite.dev/guide/assets#the-public-directory)

<!-- document id=06ff4730ba20b327ed6261c0c5a6ec2556cd3d06306ec5feeabca12cb5ff6697 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-static-assets.md -->

# Static Assets Differences with PWA Kit

PWA Kit uses a traditional Webpack-based approach with SVG sprites and utility functions for responsive images. Storefront Next leverages Vite's native asset handling with a modern component-based approach for responsive images and tree-shaken icon imports. The shift simplifies asset management while providing more powerful responsive image capabilities through the DynamicImage component.

## Key Differences

| Aspect            | PWA Kit                 | Storefront Next                   |
| ----------------- | ----------------------- | --------------------------------- |
| Build Tool        | Webpack                 | Vite                              |
| Static Directory  | `app/static/`           | `public/`                         |
| Asset URLs        | `getAssetUrl()` helper  | Direct `/` paths                  |
| Icon System       | SVG sprite sheet        | Tree-shaken React icons           |
| Image Component   | Custom with SSR preload | `<picture>` with React 19 preload |
| Responsive Images | Utility functions       | DynamicImage component            |
| Font Strategy     | Chakra UI defaults      | Tailwind CSS defaults             |
| CSP Headers       | Explicit in ssr.js      | Framework-handled                 |

## Image Import Patterns

PWA Kit:

```javascript
import { getAssetUrl } from "@salesforce/pwa-kit-react-sdk/ssr/universal/utils";

const src = getAssetUrl("static/img/hero.png");
// Result: /mobify/bundle/development/static/img/hero.png?v=abc123
```

Storefront Next:

```typescript
import heroImage from "/images/hero.png";
// or
const src = "/images/hero.png";
```

## Icon Usage

PWA Kit:

```javascript
// Import registers to sprite
import "@salesforce/retail-react-app/app/assets/svg/search.svg";

// Use via sprite reference
<Icon>
  <use xlinkHref="#search" />
</Icon>;
```

Storefront Next:

```typescript
import { Search } from "lucide-react";

<Search className="h-5 w-5" />;
```

## Responsive Image Handling

PWA Kit:

```javascript
// Manual utility function usage
const {srcSet, sizes} = getResponsivePictureAttributes({
    src: imageUrl,
    breakpoints: [320, 640, 1024]
})

<picture>
    <source srcSet={srcSet} sizes={sizes} />
    <img src={imageUrl} alt={alt} />
</picture>
```

Storefront Next:

```typescript
// Component handles complexity
<DynamicImage
  src={imageUrl}
  alt={alt}
  widths={{ base: "100vw", md: "50vw", lg: "33vw" }}
  priority="high"
/>
```

## Key Similarities

1. Lazy loading default: Both default to `loading="lazy"`.
2. B2C Commerce images: Both use Dynamic Imaging Service (`?sw={width}`).
3. System fonts: Neither bundles custom web fonts.
4. SSR awareness: Both handle preloading for above-fold images.
5. Aspect ratio handling: Both manage layout stability.

## Storefront Conversion Considerations

- Asset Path Changes

  - Replace `getAssetUrl()` with direct `/` paths.
  - Move files from `app/static/` to `public/`.

- SVG Icons

  - Replace sprite imports with `lucide-react` icons.
  - Or create individual SVG component imports.

- Image Component

  - Replace custom Image with DynamicImage.
  - Update width props to new format.

- Responsive Images
  - Convert utility function usage to DynamicImage props.
  - Breakpoint format changes from array to object.

<!-- document id=2d9a3e11fb76a62c16fed9822430c7eb9b4bef23552b0e5017494d0737f7f42c url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jobs/b2c-step-types-json-example.md -->

# Steptypes.json Example

This example shows a `steptypes.json` file that describes three custom steps: a step defined using a task-oriented CommonJS module, a step defined using a legacy pipeline, and a step defined using a chunk-oriented CommonJS module.

To check the syntax of your `steptypes.json` file, access the `steptypes.schema` file [here](https://resources.docs.salesforce.com/rel1/doc/en-us/static/misc/steptypes.schema.json).

```
my_cartridge/steptypes.json
{
  "step-types":
  {
    "script-module-step":
    [
      {
        "@type-id":"custom.MyCustomScriptStepType",
        "@supports-parallel-execution":"true",
        "@supports-site-context":"true",
        "@supports-organization-context":"false",
        "description":"My custom script step type",
        "module":"my_cartridge/cartridge/scripts/steps/myModule.ds",
        "function":"myFunctionName",
        "transactional":"false",
        "timeout-in-seconds":"900",
        "parameters":
        {
          "parameter":
          [
            {
              "@name":"MyParameter1",
              "@type":"boolean",
              "@required":"true",
              "description":"A required boolean parameter."
            },
            {
              "@name":"MyParameter2",
              "@type":"long",
              "@required":"false",
              "description":"An optional long parameter. The default value is 10 when not defined.",
              "default-value":"10"
            },
            {
              "@name":"MyParameter3",
              "@type":"double",
              "@required":"true",
              "@trim":"true",
              "description":"A required double parameter were the raw value is trimmed, value must be betwenn -10 and +10.",
              "min-value":"-10",
              "max-value":"10"
            },
            {
              "@name":"MyParameter4",
              "@type":"string",
              "@required":"false",
              "description":"An optional string parameter, length must be between 10 and 50",
              "min-length":"10",
              "max-length":"50"
            },
            {
              "@name":"MyParameter5",
              "@type":"string",
              "@required":"true",
              "@trim":"false",
              "description":"A required string parameter, must be one of One, Two or Three.",
              "enum-values":
              {
                "value":
                [
                  "One",
                  "Two",
                  "Three"
                ]
              }
            },
            {
              "@name":"MyParameter6",
              "@type":"datetime-string",
              "@required":"false",
              "@target-type":"date",
              "description":"An optional datetime parameter."
            },
            {
              "@name":"MyParameter7",
              "@type":"date-string",
              "@required":"false",
              "@target-type":"date",
              "description":"An optional date parameter."
            },
            {
              "@name":"MyParameter8",
              "@type":"time-string",
              "@required":"false",
              "@target-type":"long",
              "description":"An optional time parameter."
            }
          ]
        },
        "status-codes":
        {
                  "status":
          [
                      {
                          "@code": "ERROR",
                          "description": "Used when the step failed with an error."
                      },
                      {
                          "@code": "FINISHED",
              "description": "Used when the step finished successfully."
                      },
                      {
                          "@code": "FINISHED_WITH_WARNINGS",
              "description": "Used when the step finished with warnings."
                      }
                  ]
              }
      }
    ],
    "pipeline-step":
    [
      {
        "@type-id":"custom.MyCustomPipelineStepType",
        "@supports-parallel-execution":"false",
        "@supports-site-context":"false",
        "@supports-organization-context":"true",
        "pipeline":"MyProcessPipeline-MyStartNode",
        "description":"This is a custom pipeline step type",
        "parameters":
        {
          "parameter":
          [
            {
              "@name":"MyParameter1",
              "@type":"boolean",
              "@required":"true",
              "description":"A required boolean parameter."
            }
          ]
        },
        "status-codes":
        {
                  "status":
          [
                      {
                          "@code": "ERROR",
                          "description": "Used when the step failed with an error."
                      }
                  ]
              }
      }
    ],
    "chunk-script-module-step":
    [
      {
        "@type-id":"custom.MyCustomChunkScriptModuleStep",
        "@supports-parallel-execution":"false",
        "@supports-site-context":"true",
        "@supports-organization-context":"false",
        "description":"My custom chunk script step type",
        "module":"my_cartridge/cartridge/scripts/steps/myModule.ds",
        "before-step-function":"beforeStep",
        "total-count-function":"getTotalCount",
        "before-chunk-function":"beforeChunk",
        "read-function":"read",
        "process-function":"process",
        "write-function":"write",
        "after-chunk-function":"afterChunk",
        "after-step-function":"afterStep",
        "chunk-size":10,
        "transactional":"true",
        "parameters":
        {
          "parameter":
          [
            {
              "@name":"MyParameter",
              "@type":"boolean",
              "@required":"false"
            }
          ]
        },
        "status-codes":
        {
                  "status":
          [
                      {
                          "@code": "ERROR",
                          "description": "Used when the step failed with an error."
                      },
                      {
                          "@code": "OK",
              "description": "Used when the step finished successfully."
                      }
                  ]
              }
      }
    ]
  }
}

```

<!-- document id=4d97b6a45b41839e3aeb588318a21163b5596cff1ecef91fd5253b88dfbc485b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/jobs/b2c-step-types-xml-example.md -->

# Steptypes.xml Example

Use an XML definition instead of JSON to define your custom steps. The file must be named `steptypes.xml` and placed in a custom cartridge in the root folder. The XML file is parsed and reloaded whenever the active code version is changed. Each cartridge supports only one `steptypes.json` or `steptypes.xml` file.

```
my_cartridge/steptypes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<step-types>
  <script-module-step type-id="custom.DownloadFromFTP">
    <description>Downloads files from a FTP server</description>
    <module>jf_example_cartridge/cartridge/scripts/steps/FTPTransfer.ds</module>
    <function>download</function>
    <transactional>false</transactional>
    <parameters>
      <parameter name="DeleteFile" type="boolean" required="false" trim="false">
        <default-value>false</default-value>
      </parameter>
      <parameter name="FileNamePattern" type="string" required="true" trim="false"/>
      <parameter name="HostURL" type="string" required="true" trim="false"/>
      <parameter name="SourceFolder" type="string" required="true" trim="false"/>
      <parameter name="TargetFolder" type="string" required="true" trim="false"/>
      <parameter name="_SimulateExitStatus" type="string" required="false" trim="false">
        <enum-values>
          <value>ERROR</value>
          <value>NO_FILE_FOUND</value>
          <value>OK</value>
        </enum-values>
      </parameter>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when an error occurred during FTP download.</description>
      </status>
      <status code="NO_FILE_FOUND">
        <description>Used when no file could be found on the FTP.</description>
      </status>
      <status code="OK">
        <description>Used when FTP download was successful.</description>
      </status>
    </status-codes>
  </script-module-step>
  <script-module-step type-id="custom.UploadToFTP">
    <description>Uploads files to a FTP server</description>
    <module>jf_example_cartridge/cartridge/scripts/steps/FTPTransfer.ds</module>
    <function>upload</function>
    <transactional>false</transactional>
    <parameters>
      <parameter name="DeleteFile" type="boolean" required="false" trim="false">
        <default-value>false</default-value>
      </parameter>
      <parameter name="FileNamePattern" type="string" required="true" trim="false"/>
      <parameter name="HostURL" type="string" required="true" trim="false"/>
      <parameter name="SourceFolder" type="string" required="true" trim="false"/>
      <parameter name="TargetFolder" type="string" required="true" trim="false"/>
      <parameter name="_SimulateExitStatus" type="string" required="false" trim="false">
        <enum-values>
          <value>ERROR</value>
          <value>NO_FILE_FOUND</value>
          <value>OK</value>
        </enum-values>
      </parameter>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when an error occurred during FTP upload.</description>
      </status>
      <status code="NO_FILE_FOUND">
        <description>Used when no file could be found for upload to the FTP.</description>
      </status>
      <status code="OK">
        <description>Used when FTP upload was successful.</description>
      </status>
    </status-codes>
  </script-module-step>
  <script-module-step type-id="custom.RebuildIndexes">
    <module>jf_example_cartridge/cartridge/scripts/steps/RebuildIndexes.ds</module>
    <function>execute</function>
    <transactional>false</transactional>
    <parameters>
      <parameter name="RebuildContentIndexes" type="boolean" required="false" trim="false">
        <default-value>false</default-value>
      </parameter>
      <parameter name="RebuildProductIndexes" type="boolean" required="false" trim="false">
        <default-value>false</default-value>
      </parameter>
      <parameter name="_SimulateExitStatus" type="string" required="false" trim="false">
        <enum-values>
          <value>ERROR</value>
          <value>OK</value>
        </enum-values>
      </parameter>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when index rebuild failed.</description>
      </status>
      <status code="OK">
        <description>Used when index rebuild was successful.</description>
      </status>
    </status-codes>
  </script-module-step>
  <pipeline-step type-id="custom.Import">
    <pipeline>Import-Start</pipeline>
    <parameters>
      <parameter name="FileNamePattern" type="string" required="true" trim="false"/>
      <parameter name="ImportMode" type="string" required="true" trim="false">
        <enum-values>
          <value>DELETE</value>
          <value>MERGE</value>
          <value>REPLACE</value>
          <value>UPDATE</value>
        </enum-values>
      </parameter>
      <parameter name="ObjectType" type="string" required="true" trim="false">
        <enum-values>
          <value>catalog</value>
          <value>inventory</value>
          <value>pricebook</value>
          <value>promotion</value>
        </enum-values>
      </parameter>
      <parameter name="_SimulateExitStatus" type="string" required="false" trim="false">
        <enum-values>
          <value>ERROR</value>
          <value>NO_FILE_FOUND</value>
          <value>OK</value>
        </enum-values>
      </parameter>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when the import failed.</description>
      </status>
      <status code="NO_FILE_FOUND">
        <description>Used when no file to import was found.</description>
      </status>
      <status code="OK">
        <description>Used when the import was successful.</description>
      </status>
    </status-codes>
  </pipeline-step>
  <pipeline-step type-id="custom.ExportOrders">
    <pipeline>ExportOrders-Start</pipeline>
    <parameters>
      <parameter name="FileName" type="string" required="true" trim="false"/>
      <parameter name="OrderStatus" type="string" required="false" trim="false">
        <enum-values>
          <value>All</value>
          <value>ConfirmedAndPaid</value>
        </enum-values>
        <default-value>All</default-value>
      </parameter>
      <parameter name="_SimulateExitStatus" type="string" required="false" trim="false">
        <enum-values>
          <value>ERROR</value>
          <value>NO_ORDERS_FOUND</value>
          <value>OK</value>
        </enum-values>
      </parameter>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when the order export failed.</description>
      </status>
      <status code="NO_ORDERS_FOUND">
        <description>Used when no order to export were found.</description>
      </status>
      <status code="OK">
        <description>Used when the order export was successful.</description>
      </status>
    </status-codes>
  </pipeline-step>
  <chunk-script-module-step type-id="custom.MyCustomChunkScriptModuleStep">
    <description>My custom chunk script step type/description>
    <module>my_cartridge/cartridge/scripts/steps/myModule.ds</module>
    <before-step-function>beforeStep</before-step-function>
    <total-count-function>beforeChunk</total-count-function>
      <before-chunk-function>beforeChunk</before-chunk-function>
      <read-function>read</read-function>
      <process-function>process</process-function>
      <write-function>write</write-function>
    <after-chunk-function>afterChunk</after-chunk-function>
      <after-step-function>afterStep</after-step-function>
      <chunk-size>10</chunk-size>
      <transactional>true</transactional>
    <parameters>
      <parameter name="MyParameter" type="boolean" required="false" trim="false">
      </parameter>
    </parameters>
    <status-codes>
      <status code="ERROR">
        <description>Used when an error occurred.</description>
      </status>
      <status code="OK">
        <description>Used when no error occured.</description>
      </status>
    </status-codes>
  </script-module-step>
</step-types>
```

<!-- document id=fb957d868de229fc04028537218e1d236b757a41623d4dac4b0812b66a76cbcc url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-storage-sessions.md -->

# Storage and Sessions

Storefront Next uses a **server-only** authentication architecture. All Shopper Login and API Access Service (SLAS) token management—guest login, refresh, registered login, social and passwordless flows, and cookie writing—happens in a single server middleware, `auth.server.ts`, that runs on every request. Tokens never reach the browser. Client components receive only a small, non-sensitive slice of session data through the `useAuth()` hook.

## Architecture Overview

Storefront Next auth has two layers and a single source of truth:

1. **Server middleware** (`middlewares/auth.server.ts`) runs on every request—both full page loads and React Router client navigations, which re-invoke the server loaders. It reads auth cookies from the `Cookie` header, validates and refreshes tokens, performs guest login when needed, and writes updated cookies through `Set-Cookie` headers.
2. **React context** (`providers/auth.tsx`) exposes a `PublicSessionData` object (no tokens) to components through the `useAuth()` hook. The root loader extracts this slice with `getPublicSessionData(session)` and passes it to the provider.

Route modules use only the server `loader` and `action`—never `clientLoader` or `clientAction`.

### Request Flow

```
Browser request (full load or client navigation)
        │
        ▼
auth.server.ts middleware
  • parse cookies from the Cookie header
  • decode access-token JWT (userType, customerId, usid, expiry, tracking consent)
  • if the access token is valid → use it
    else if a refresh token is present → refresh
      if refresh fails AND user was registered → 307 redirect to /login?returnUrl=...&error=session_expired
      if refresh fails AND user was guest → guest login
    else → guest login
  • write updated tokens and metadata through Set-Cookie
        │
        ▼
root loader: getAuth(context) → full SessionData
             getPublicSessionData(session) → clientAuth (no tokens)
        │
        ▼
<AuthProvider value={clientAuth}> → useAuth() in components
```

## Cookie Architecture

Storefront Next stores all auth state across separate cookies, each with its own purpose, expiry, and value source. **Every auth cookie is `HttpOnly`.** The browser sends them on each request—so the server middleware and hybrid B2C Commerce can both read them—but client-side JavaScript can't access them. The client gets its auth state from the serialized loader data, not by reading cookies. This architecture protects every token from cross-site scripting (XSS) attacks.

| Cookie              | Purpose                                                      | User type  | Expiry                                  | Value source                         |
| ------------------- | ------------------------------------------------------------ | ---------- | --------------------------------------- | ------------------------------------ |
| `cc-nx-g`           | Guest refresh token                                          | Guest      | Guest refresh expiry (max 30 days)      | SLAS body                            |
| `cc-nx`             | Registered refresh token                                     | Registered | Registered refresh expiry (max 90 days) | SLAS body                            |
| `cc-at`             | Access token                                                 | Both       | Access-token JWT `exp`                  | SLAS body                            |
| `usid`              | User session ID (mirrors JWT `sub` → `usid`)                 | Both       | Refresh expiry, else access expiry      | JWT `sub` claim                      |
| `enc_user_id`       | Encoded user ID                                              | Registered | Refresh expiry                          | SLAS body                            |
| `idp_access_token`  | IDP access token (social login)                              | Both       | Access expiry (proxy)                   | SLAS body                            |
| `id_token`          | OIDC ID token                                                | Both       | Access expiry                           | SLAS body                            |
| `idp_refresh_token` | IDP refresh token (social login)                             | Both       | Refresh expiry                          | SLAS body                            |
| `dw_dnt`            | Tracking consent preference (value = `TrackingConsent` enum) | Both       | Session                                 | Cookie (source of truth) / JWT `dnt` |
| `dwsid`             | Hybrid storefront session ID (B2C Commerce session bridge)   | Both       | Session                                 | SLAS `Set-Cookie` header             |
| `cc-cv`             | OAuth2 PKCE code verifier                                    | Both       | 5 minutes                               | Generated (social flow)              |
| `cc-auth-recover`   | 401-recovery loop guard                                      | Both       | 30 seconds                              | Middleware                           |

**note:** **Value source.** Token strings come verbatim from the SLAS `TokenResponse` body. The session _facts_—`userType`, `customerId`, `usid`, `accessTokenExpiry`, and tracking consent—are decoded from the access-token JWT rather than read from the body, so they can never drift from the token. The `dwsid` cookie is the exception: it comes from the SLAS response's `Set-Cookie` header.

`customerId` is not a cookie. It's derived per request from the access-token JWT and exposed through `getAuth()` on the server and `useAuth()` on the client. The logout and error paths also clear any legacy `customer_id` cookie left by older versions.

### Key Design Decisions

- **Mutually exclusive refresh tokens:** Only one of `cc-nx-g` (guest) or `cc-nx` (registered) exists at a time. On a user-type transition, the middleware explicitly deletes the other with a `Set-Cookie` header that uses an expired date.
- **`userType` is never stored in a cookie:** It's derived from the JWT. The refresh-cookie name is only a write-time decision for where to store the refresh token.
- **Namespacing:** Cookies are suffixed with `siteId` (for example, `cc-nx_RefArch`) to support multi-site deployments, _except_ `dwsid` and `dw_dnt`, which are excluded so external or B2C Commerce systems can read them directly.
- **HttpOnly on every auth cookie:** Client-side JavaScript can never read auth tokens. The client receives only non-sensitive session data through the loader, so there is no need for JavaScript cookie access.

### User Type Detection

`userType` comes from the access-token JWT: registered tokens carry an `rcid` identity claim that guest tokens lack. It isn't determined by which refresh cookie exists. The refresh-cookie name is consulted only as a cold-start fallback, before any access token has been issued, and to decide which refresh cookie to write or delete on the response.

### Token Expiry Management

- **Access token:** The expiry is read from the JWT `exp` claim, stored as a timestamp, and compared at runtime with a fast numeric check—so there's no repeated JWT decoding in the hot path.
- **Refresh token:** Configurable through environment variables and capped at the B2C Commerce maximums (guest 30 days, and registered user 90 days).

### 401 Recovery Redirect

When a SCAPI call returns a `401` for a non-SLAS endpoint, the SCAPI client throws `AuthTokenInvalidError`. The middleware catches it in `handleAuthTokenInvalidation`, clears stale token state, re-runs the refresh or guest flow, and—if recovery succeeds—issues a `307` redirect back to the same URL so the request restarts with fresh cookies. The redirect carries the `x-sfnext-auth-recovery: 1` header for observability.

To prevent loops, a short-lived guard cookie, `cc-auth-recover` (`Max-Age=30`), is set during recovery. If a `401` recurs while the guard is present, recovery isn't retried—the error surfaces and the response carries the `x-sfnext-auth-recovery-guard: 1` header. The guard is cleared on the follow-up request.

### Registered Session Expiry Redirect

When a **registered** shopper's SLAS refresh token fails (SLAS returns a 400), the middleware redirects to `/login` (with the site and locale prefix) instead of silently downgrading the shopper to a guest session. The redirect carries `returnUrl` (the original request path, already prefixed) and `error=session_expired` so the login page can display a contextual message. A fresh guest session is created in parallel so the application has a valid token while the redirect is processed.

The same `cc-auth-recover` guard cookie prevents redirect loops: if the guard is already set when the redirect would fire, the middleware falls through to the guest session rather than redirecting again. The guard expires after 30 seconds and is cleared on the follow-up request.

Guest shoppers whose refresh token fails are unaffected by this change. They continue to receive a new guest session silently.

### JWT Integrity Validation

SLAS guarantees `gcid` or `rcid` in the `isb` claim and `usid` in the `sub` claim. The middleware validates this on the incoming cookie token, but only when that token survived validation unchanged. After a refresh or guest login, re-validation is skipped because the freshly issued token was already validated inside `updateAuthStorageDataByTokenResponse` when it was stored.

If a structurally invalid token is detected (decodable but missing required claims, or undecodable), `AuthTokenInvalidError` is thrown and routed through the same recovery flow as a `401`: clear cookies, fresh login, `307` redirect. Because this indicates a critical token-issuance failure, it logs at the error level for production visibility.

## Configuration

### Environment Variables (Optional)

```bash
# Override guest refresh token expiry (capped at 30 days)
PUBLIC_COMMERCE_API_GUEST_REFRESH_TOKEN_EXPIRY_SECONDS=2592000

# Override registered refresh token expiry (capped at 90 days)
PUBLIC_COMMERCE_API_REGISTERED_REFRESH_TOKEN_EXPIRY_SECONDS=7776000
```

### Cookie Domain

To share cookies across subdomains—or to keep session continuity in a hybrid Storefront Next and SFRA deployment—set a cookie domain by using the global `app.cookies.domain` or a per-site `commerce.sites[].cookies.domain` override. It applies to every cookie the storefront writes and is opt-in (host-only by default).

Cookie attribute defaults (`path: '/'`, `sameSite: 'lax'`, and `secure`) are applied automatically. The resolved cookie domain takes precedence over these defaults. `secure` is gated on `isRemote()` (the `BUNDLE_ID` signal): `true` on deployed (HTTPS) environments, `false` on local `pnpm dev` and `pnpm preview`, which serve plain HTTP over `localhost`. Without gating secure on `isRemote()`, Safari and WebKit silently refuse to persist `Secure` cookies on loopback and login never sticks. Chrome and Firefox mask it with a localhost exception. `SameSite=None` cookies, which are used in Page Designer design mode, always stay `Secure`, as the spec requires.

The per-site override takes precedence over the global setting. A leading-dot value scopes the cookie to the apex domain and all subdomains:

```typescript
// config.server.ts — global cookie domain
export default {
  app: {
    cookies: {
      domain: ".example.com", // applies to all sites unless overridden
    },
  },
  commerce: {
    sites: [
      {
        id: "RefArch",
        cookies: { domain: ".us.example.com" }, // per-site override
        defaultLocale: "en-US",
        // …
      },
      {
        id: "RefArchGlobal",
        // inherits global .example.com
        defaultLocale: "en-GB",
        // …
      },
    ],
  },
};
```

Cookie attribute defaults (`path: '/'`, `sameSite: 'lax'`) are applied automatically. The resolved cookie domain takes precedence over them.

The `secure` attribute is set to `true` on deployed (HTTPS) environments and `false` on local development (`pnpm dev` or `pnpm preview`), which serve plain HTTP over `localhost`. Without this, Safari and WebKit silently refuse to persist `Secure` cookies on loopback and login never sticks. Chrome and Firefox mask this with a localhost exception. `SameSite=None` cookies—used in Page Designer design mode—always stay `Secure`, as the spec requires.

For the full guide, including the matching Business Manager setting and rollout guidance, see the [Cookie Domain Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-domain-cookie.md) guide.

## Accessing Session Data

### On the Server

The auth middleware reads cookies from the request and builds the full `SessionData`, including tokens. You can access this data only on the server—in loaders, actions, and other middlewares. Use `getAuth(context)`:

```typescript
import { getAuth } from "@/middlewares/auth.server";
import type { LoaderFunctionArgs } from "react-router";

export async function loader({ context }: LoaderFunctionArgs) {
  const auth = getAuth(context);

  const accessToken = auth.accessToken; // server only
  const customerId = auth.customerId;
  const userType = auth.userType; // 'guest' | 'registered'
  const usid = auth.usid;

  return { customerId, isRegistered: userType === "registered" };
}
```

### In Client Components

There's no client-side `getAuth`. Client components read the non-sensitive slice through the `useAuth()` hook—tokens are never available on the client:

```typescript
import { useAuth } from "@/providers/auth";

function AccountBadge() {
  const auth = useAuth(); // PublicSessionData | undefined

  if (auth?.userType === "registered") {
    return <span>Welcome back</span>;
  }
  return <SignInLink />;
}
```

For route-level auth checks, branch inside the server `loader`—not in a client guard.

## Updating and Destroying Auth

### Updating Auth (Login)

`updateAuth(context, updater)` accepts either a SLAS token response or a function updater:

```typescript
import { updateAuth, loginRegisteredUser } from "@/middlewares/auth.server";
import type { ActionFunctionArgs } from "react-router";

export async function action({ request, context }: ActionFunctionArgs) {
  const formData = await request.formData();
  const email = formData.get("email") as string;
  const password = formData.get("password") as string;

  try {
    const tokenResponse = await loginRegisteredUser(context, email, password);
    updateAuth(context, tokenResponse); // token-response form
    return redirect("/account");
  } catch {
    return { error: "Login failed" };
  }
}
```

The token-response form re-derives `userType`, `customerId`, `usid`, and expiry from the new JWT, preserves the tracking-consent cookie, and writes the appropriate cookies. The function form, `updateAuth(context, (data) => ({ ...data, codeVerifier }))`, merges in fields such as the PKCE code verifier without a full token swap.

### Destroying Auth (Logout)

```typescript
import { destroyAuth } from "@/middlewares/auth.server";

export async function action({ context }: ActionFunctionArgs) {
  destroyAuth(context); // clears storage; middleware deletes all auth cookies on the response
  return redirect("/");
}
```

### Social Login (OAuth2 PKCE)

For social login flows that use OAuth2 PKCE (Proof Key for Code Exchange), the code verifier is stored in an `HttpOnly` cookie (`cc-cv`) between the authorization request and the token exchange:

```typescript
import { getAuth, updateAuth } from "@/middlewares/auth.server";

// Step 1 — generate PKCE challenge, store verifier, redirect to IDP
export async function loader({ context }: LoaderFunctionArgs) {
  const { url, codeVerifier } = await clients.auth.social
    .getAuthorizationUrl
    /* ... */
    ();
  updateAuth(context, (current) => ({ ...current, codeVerifier })); // stored in HttpOnly cc-cv
  return redirect(url);
}

// Step 2 — exchange code for tokens (verifier read from cc-cv); cc-cv auto-deleted on the next write
export async function action({ request, context }: ActionFunctionArgs) {
  const session = getAuth(context);
  const tokenResponse = await exchangeCodeForTokens(code, session.codeVerifier); // illustrative
  updateAuth(context, tokenResponse);
  return redirect("/account");
}
```

**important:** **CSP note:** When you add a social-login provider beyond the defaults, extend `connect-src` (and any redirect or popup origins) in your `app.security.headers.csp.directives` config. For the full guide, see [Configure CSP for Social Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-security-headers.md#configure-csp-for-social-login).

### Custom Auth Operations

The following server-side SLAS helpers are exported from `auth.server.ts`:

```typescript
import {
  loginGuestUser,
  loginRegisteredUser,
  refreshAccessToken,
  authorizePasswordless,
  getPasswordLessAccessToken,
  getPasswordResetToken,
  resetPasswordWithToken,
  requestOtp,
  verifyOtp,
  flashAuth,
  clearInvalidSessionAndRestoreGuest,
} from "@/middlewares/auth.server";
```

```typescript
const guestTokens = await loginGuestUser(context, { usid: "optional-usid" });
const newTokens = await refreshAccessToken(context, refreshToken);

// Passwordless (magic link)
await authorizePasswordless(context, { userid: "user@example.com", redirectPath: "/account" });
const tokens = await getPasswordLessAccessToken(context, magicLinkToken);

// OTP email verification (validates a code without creating a new session)
await requestOtp(context, { email: "user@example.com" });
await verifyOtp(context, { pwdActionToken, email: "user@example.com" });

// Password reset
await getPasswordResetToken(context, { email: "user@example.com" });
await resetPasswordWithToken(context, { email, token, newPassword });

// Recovery helpers
flashAuth(context, "Your session expired"); // clear session + set an error message
await clearInvalidSessionAndRestoreGuest(context); // e.g. deleted customer / corrupted session
```

For the related shopper features, see [Social Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-social-login.md), [Passwordless Login](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passwordless-login.md), and [Password Reset](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-password-reset.md).

The recovery helpers cover error and corruption scenarios:

- **`flashAuth(context, message)`** — Clears the session and sets an error message. Use this when a shopper account is deleted or becomes invalid mid-session so the storefront can redirect the shopper to login with an appropriate message.
- **`clearInvalidSessionAndRestoreGuest(context)`** — Replaces a corrupted or unrecoverable session with a fresh guest session. Use this when the session state is structurally invalid and a clean guest login is preferable to surfacing an error.

## Authentication Flows

### New Guest User

1. The user visits with no auth cookies.
2. The server middleware finds no usable token and calls SLAS guest login.
3. The server writes `cc-nx-g`, `cc-at`, and `usid` (and any `dwsid` from the response).
4. The root loader serializes `clientAuth`, and `AuthProvider` makes it available through `useAuth()`.

### Returning User (Token Valid)

1. The server reads cookies from the `Cookie` header.
2. If the access-token `exp` is in the future, the tokens are used as-is.
3. If the access token is expired but a refresh token exists, the server refreshes and rewrites `cc-at` (and `usid` if it changed).

### Guest to Registered (Login)

1. The action calls `loginRegisteredUser()`, and SLAS returns a registered token whose JWT carries `rcid`.
2. `updateAuth(context, tokenResponse)` derives `userType = 'registered'` from the JWT.
3. The middleware writes `cc-nx` and deletes `cc-nx-g` to maintain mutual exclusivity.
4. Guest resources are merged into the registered account (see below).

### Logout

1. The action calls `destroyAuth(context)`.
2. The middleware deletes all auth cookies through expired `Set-Cookie` headers (including the legacy `customer_id`).
3. The next request finds no cookies and triggers a fresh guest login.

### Guest to Registered Resource Merge

On any guest-to-registered transition (social, passwordless, or standard login), guest-owned resources must be captured _before_ the token swap, because `customerId` changes from the guest `gcid` to the registered `rcid`, and SCAPI rejects the guest customer ID under a registered token:

```typescript
// lib/api/auth/social-login.server.ts (shape)
const guestWishlistSnapshot = await captureGuestWishlistSnapshot(context); // BEFORE swap
const result = await loginIDPUser(context /* ... */); // token swap (updateAuth)
await mergeBasket(context); // AFTER swap
await mergeWishlist(context, guestWishlistSnapshot); // AFTER swap
```

Tracking consent is preserved across the swap: `updateAuthStorageData` restores the `dw_dnt` cookie value (the source of truth) after clearing storage, and login and refresh calls forward it to SLAS as the `dnt` parameter.

### Hybrid Storefronts (B2C Commerce Session Bridge)

There's no client-side cookie sync. The bridge is the `dwsid` cookie:

1. The SDK extracts `dwsid` from the SLAS response's `Set-Cookie` header, and the middleware persists it.
2. `dwsid` (and `dw_dnt`) aren't namespaced, so the B2C Commerce cartridge can read and write them directly.
3. The browser sends these cookies on every request. On the next full request, the React storefront's server middleware reads them from the `Cookie` header. There's no real-time iframe or single-page-app sync in middleware scope.

For more about hybrid implementations, see [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid.md).

## Hydration

Auth is available immediately during server-side rendering (SSR) and hydration without serializing any tokens:

- **Server:** The root loader builds the full `SessionData` through `getAuth(context)`, then returns only `clientAuth = getPublicSessionData(session)`—a `Pick` of `userType`, `customerId`, `usid`, `encUserId`, and `trackingConsent`.
- **Client:** The root renders `<AuthProvider value={clientAuth}>` directly. Components that read `useAuth()` see exactly the same data that produced the SSR markup, so there's no hydration gap and no bootstrap snapshot.
- **Subsequent navigations:** React Router re-invokes the root loader, which re-derives `clientAuth`. `AuthProvider` stays mounted, and the root memoizes the provider tree on `clientAuth`, so only its `value` changes and `useAuth()` consumers re-render.

```typescript
// providers/auth.tsx
export const AuthContext = createContext<PublicSessionData | undefined>(undefined);
export const useAuth = (): PublicSessionData | undefined => useContext(AuthContext);

// root.tsx (shape)
const session = getAuth(context); // full SessionData (server only)
const clientAuth = getPublicSessionData(session); // non-sensitive slice → loader data
// ...
<AuthProvider value={clientAuth}>{/* app */}</AuthProvider>;
```

The server-side auth during hydration keeps a single source of truth, exposes no tokens to the client, and maintains a stable provider tree.

## Type Safety

`SessionData` and `PublicSessionData` are custom types defined in the template, not part of React Router's [sessions and cookies API](https://reactrouter.com/explanation/sessions-and-cookies). Storefront Next doesn't use React Router's `createCookieSessionStorage` because auth requires individual cookies with separate expiry times—access tokens expire in minutes, while refresh tokens persist for days. React Router's session API packs all data into a single cookie, which doesn't support these requirements.

```typescript
import type { SessionData, PublicSessionData } from "@/lib/api/types";

// Full server-side session (tokens included — never serialized to the client)
type SessionData = {
  accessToken?: string;
  accessTokenExpiry?: number;
  refreshToken?: string;
  refreshTokenExpiry?: number;
  customerId?: string;
  userType?: "guest" | "registered";
  usid?: string;
  encUserId?: string;
  codeVerifier?: string; // OAuth2 PKCE (server-only, ephemeral)
  idpAccessToken?: string;
  idpAccessTokenExpiry?: number;
  idToken?: string; // OIDC id_token (server-only)
  idpRefreshToken?: string; // social login (server-only)
  dwsid?: string; // hybrid storefront session bridge
  trackingConsent?: TrackingConsent;
};

// The only data exposed to the client (Pick — stays in sync with SessionData)
type PublicSessionData = Pick<
  SessionData,
  "customerId" | "userType" | "usid" | "encUserId" | "trackingConsent"
>;
```

## Best Practices

- **Server versus client:** Use `getAuth(context)` in loaders and actions, and `useAuth()` in components. Tokens are server-only.
- **No direct cookie writes:** Always go through `updateAuth()` or `destroyAuth()`—the middleware owns cookie serialization.
- **User-type checks:** Use `auth.userType`, which is JWT-derived.
- **Token refresh:** Handled automatically by the middleware. Don't refresh manually in routes.
- **Capture before swap:** On guest-to-registered login, snapshot guest resources before the token swap and merge after.
- **Security:** Never log or expose `accessToken` or `refreshToken`.
- **No `clientLoader` or `clientAction`:** Route modules use the server `loader` and `action` only.

## File Structure

```
src/
├── middlewares/
│   ├── auth.server.ts        # Server auth middleware, SLAS operations, cookie I/O, getAuth/updateAuth/destroyAuth
│   └── auth.utils.ts         # Cookie-name constants, JWT decoding/claims, userType derivation, getPublicSessionData
├── providers/
│   └── auth.tsx              # AuthContext + AuthProvider + useAuth() (PublicSessionData only)
└── lib/
    ├── cookie-utils.server.ts  # getCookieConfig, createCookie, namespacing, parseAllCookies
    ├── auth/                   # passwordless-login.server.ts, error-handler.ts
    └── api/auth/               # register, standard-login, social-login, reset-password (.server.ts)
```

For a comparison with the PWA Kit approach, see [Storage and Sessions Differences with PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-pwa-storage-sessions.md).

<!-- document id=4aad2dbbad0785b260d83874d320cce51f8913f284524a8aeba16e62c5dd11b0 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-storage-sessions.md -->

# Storage and Sessions Differences with PWA Kit

PWA Kit manages auth on both client and server through `commerce-sdk-react`. Storefront Next handles auth exclusively on the server through middleware and stores tokens in `httpOnly` cookies that client-side JavaScript can't access.

## Key Differences

| Aspect              | PWA Kit                                                       | Storefront Next                                      |
| ------------------- | ------------------------------------------------------------- | ---------------------------------------------------- |
| Auth management     | `commerce-sdk-react` Auth class                               | Server auth middleware                               |
| Access token        | localStorage (`access_token_{siteId}`)                        | Cookie (`cc-at_{siteId}`)                            |
| Other session data  | localStorage                                                  | Cookies                                              |
| Server-side storage | In-memory (`MemoryStorage`)                                   | Request cookies only (stateless)                     |
| Auth calls          | Client and server (via `commerce-sdk-react`)                  | Server-only (via middleware and SCAPI clients)       |
| Token refresh       | SDK refreshes on both client and server when token is expired | Middleware refreshes on server before route handlers |

## Auth Flow

In PWA Kit, auth runs on both server and client. During SSR, `commerce-sdk-react` uses in-memory storage because browser APIs aren't available. On the client, the SDK initiates the SLAS OAuth flow (guest login) and stores tokens in localStorage and cookies. On subsequent navigations, the SDK checks for existing tokens before making new auth calls, and handles token refresh and registered login as needed.

In Storefront Next, auth runs exclusively on the server. For details, see [Storage and Sessions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storage-sessions.md).

## Accessing Auth Data in Components

PWA Kit exposes auth state through `commerce-sdk-react` hooks:

```typescript
import { useCustomerType, useCustomerId } from "@salesforce/commerce-sdk-react";

const { isGuest, isRegistered } = useCustomerType();
const customerId = useCustomerId();
```

Storefront Next exposes a subset of session data through the `useAuth()` hook:

```typescript
import { useAuth } from "@/providers/auth";

const session = useAuth();
// session.userType, session.customerId, session.usid
```

<!-- document id=1328c64e64a1ce00d94011bb6a29eaf3934af6003b6e090fb91504fee4a625f5 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-store-and-experience-metadata.md -->

# Store and Experience Metadata

A B2B Commerce store has both store metadata and Experience Bundle metadata. The store metadata defines the functionality, and the Experience Bundle metadata defines the store’s look and feel and navigation. When deploying metadata from a Salesforce B2B source org to a target org, deploy the store metadata before deploying the Experience Bundle metadata.
The store metadata defines the structure and behavior of your B2B store.

- The experience layer often depends on the underlying store metadata. By deploying the store metadata first, you can perform tests to make sure that all the business processes and data models work as expected in the new environment and avoid errors when layering on the user interface and user experience component metadata.

## Commerce Metadata Files

The metadata files are organized in the `force-app` directory of your Salesforce project and have distinct file extensions to identify them.

- Directory structure–Metadata files are organized into folders based on their type. For example:

  `- force-app/main/default/objects/` for custom objects

  `- force-app/main/default/classes/` for Apex classes

  `- force-app/main/default/experiences/` for Experience Cloud sites

- File extensions–The metadata file extensions indicate their type. Some common extensions include:

  `- .object-meta.xml` for custom objects

  `- .cls and .cls-meta.xml` for Apex classes

  `- .site-meta.xml` for Experience Cloud sites

- Naming conventions–Metadata files often follow a naming convention that includes the name of the component and the type of metadata. For example:

      ` - Account.object-meta.xml` for the Account object metadata

      ` - MyCustomClass.cls and MyCustomClass.cls-meta.xml` for an Apex class named MyCustomClass

      ` - MyExperience.site-meta.xml` for an Experience Cloud site named MyExperience

  Here’s a sample directory structure:

          `force-app/`

          `└── main/`

          ` └── default/`

          ` ├── objects/`

          ` │ └── Account.object-meta.xml`

          ` ├── classes/`

          ` │ ├── MyCustomClass.cls`

          ` │ └── MyCustomClass.cls-meta.xml`

          ` └── experiences/`

          ` └── MyExperience.site-meta.xml`

  By following these conventions, you can easily identify and locate metadata files within the `force-app` directory.

<!-- document id=c766fef1edec1147c128ad9d70f9b22bfdee9b74e3ad4bfff2ee001947d72074 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/store-associate-management-api.md -->

Store Associate Management API

# Store Associate Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-associate-management-api/store-associate-management-api-oas-public.yaml)

POS Merchant API to create, search, update, and deactivate store associates from the POS system.

**Version:** 2.3.4

## Tags

### Store Associate Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-associate-management-api/store-associate-management-api-oas-public.yaml)

POS Merchant API to create, search, update, and deactivate store associates from the POS system.

## Operations

### PUT Create or update store associates.

`PUT /merchant/{version}/associates/bulk`

Operation ID: `bulkUpsertStoreAssociate`. Tags: Store Associate Management API.

Create or update a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. All mandatory fields are required for each associate being created or updated. If any non-mandatory field is set to null, it overwrites the existing data with null. Update and create validation rules are applied to each associate in the request. If all associates are created or updated successfully, a successful response is returned; otherwise, the response contains error messages corresponding to the failures. ErrorMessage and code are populated for validation failures. General Validation includes:

1.  Ensuring the associateList is not empty or null.
2.  Performing mobile configuration ID validation. Update Validation includes:
3.  Verifying that all associates to be updated exist in the system.
4.  Checking for mismatches between the number of updating associates and existing associates.
5.  Validating that all associate IDs in the update list exist in the system. Create Validation includes:
6.  Verifying that all associates to be created do not exist in the system.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `StoreAssociateBulkRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### POST Create store associates.

`POST /merchant/{version}/associates/bulk`

Operation ID: `bulkCreateStoreAssociate`. Tags: Store Associate Management API.

Create a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. All mandatory fields are required for each associate being created. If any non-mandatory field is set to null, it overwrites the existing data with null. If all associates are created successfully, a successful response is returned. Otherwise, the response contains an errorMessage and errorCode corresponding to the failure. ErrorMessage and code are populated for validation failures. Validation includes:

1.  Ensuring the associateList is not empty or null.
2.  Verifying that all associates to be created do not exist in the system.
3.  Performing mobile configuration ID validation.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `StoreAssociateBulkRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### PATCH Update store associates.

`PATCH /merchant/{version}/associates/bulk`

Operation ID: `bulkUpdateStoreAssociate`. Tags: Store Associate Management API.

Update a list of store associates in the POS system. The number of associates in the request must be between 1 and 100. The update only requires the store associate ID field. Only the fields provided in the request are updated. If all associates are updated successfully, a successful response is returned. Otherwise, the response contains an errorMessage and errorCode corresponding to the failure. ErrorMessage and code are populated for validation failures. Validation includes:

1.  Ensuring the associateList is not empty or null.
2.  Verifying that all associates to be updated exist in the system.
3.  Checking for mismatches between the number of updating associates and existing associates.
4.  Validating that all associate IDs in the update list exist in the system.
5.  Performing mobile configuration ID validation.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `StoreAssociateBulkRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### GET Retrieve store associates.

`GET /merchant/{version}/associates`

Operation ID: `getStoreAssociates`. Tags: Store Associate Management API.

Retrieve active or inactive store associates based on query parameters storeId and associateId. Both query parameters are optional.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `storeId` (query, string)
*   `associateId` (query, string)
*   `active` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### PUT Update store associate.

`PUT /merchant/{version}/associates`

Operation ID: `updateStoreAssociate`. Tags: Store Associate Management API.

Update a store associate in the POS system. If the associate is updated successfully, the same associate details are returned. Otherwise, the response contains ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Associate`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### POST Create store associate.

`POST /merchant/{version}/associates`

Operation ID: `createStoreAssociate`. Tags: Store Associate Management API.

Create a store associate in the POS system. If the associate is created successfully, the same associate details are returned. Otherwise, the response contains ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `Associate`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### DELETE Deactivate store associate.

`DELETE /merchant/{version}/associates`

Operation ID: `deleteStoreAssociate`. Tags: Store Associate Management API.

Deactivate a store associate from the POS system corresponding to the associateId query parameter. On successful deactivation, the active field on the associate is set to false, and the response contains the deactivated associate details. If unsuccessful, the response contains the ErrorMessage and ErrorCode corresponding to the failure.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `associateId` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreAssociateSearchResponse`.
    

### GET Retrieve store associate.

`GET /merchant/{version}/associates/{associateId}`

Operation ID: `getStoreAssociate`. Tags: Store Associate Management API.

Retrieve store associate details by associateId.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `associateId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `Associate`.
    

## Schemas

### StoreAssociateBulkRequest

*   `associateList` (_array of Associate_, required) List of associates to create, update, or upsert in the POS System. This list must contain at least 1 associate and no more than 100 associates.  
    Minimum items: 1. Maximum items: 100.

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### StoreAssociateSearchResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `storeAssociates` (_array of Associate_) List of the store associates. It can have a single associate, the associates from a store, or all associates.
*   `error` (_boolean_)

### Associate

Store associate.

*   `storeAssociateID` (_string_) ID of the store associate (POS login ID for the associate).
*   `storeID` (_string_, nullable) Store ID of the associate.
*   `merchantUserID` (_string_, nullable) Merchant's underlying system's user ID for the store associates. For example, LoginId for underlying OMS or Salseforce Commerce.
*   `paymentDeviceMerchantID` (_string_, nullable) Merchant ID of a payment device assigned to the associate.
*   `paymentDeviceID` (_string_, nullable) ID of a payment device, like terminal ID, assigned to the associate.
*   `storeAssociatePassword` (_string_) Store associate's password (POS Login Password for the associate).
*   `merchantPassword` (_string_, nullable) Merchant's underlying system's password for the associate.
*   `storeAssociatePasswordPin` (_string_, nullable) Password hint for the associate's POS login.
*   `firstName` (_string_, nullable) First name of the associate.
*   `lastName` (_string_, nullable) Last name of the associate.
*   `storeType` (_string_) Type of the store where the associate works. Possible values include: Regular, Popup, Outlet or eComm.
*   `role` (_string_) The associate's role in the store. Possible values include: STORE\_ASSOCIATE, STORE\_MANAGER or AREA\_MANAGER.
*   `passwordSetOn` (_integer (int64)_, nullable) Date when password was set last time. Represented as the number of milliseconds since epoch.
*   `storeAssociatePasswordFlag` (_boolean_) Flag indicating that the store associate password is updated during associate update operation. Used only during update operation.
*   `merchantPasswordFlag` (_boolean_) Flag indicating that the merchant password is updated during associate update operation. Used only during update operation.
*   `storeAssociateSecretFlag` (_boolean_, nullable) Flag indicating that the store associate secret is updated during associate update operation. Used only during update operation.
*   `imageUrl` (_string_, nullable) The associate's image URL.
*   `active` (_boolean_) Specifies whether the status of the associate is active (true) or removed/deactivated (false).
*   `emailId` (_string_, nullable) Email ID of the associate.
*   `mobilePhoneNumber` (_string_, nullable) Mobile phone number of the associate.
*   `additionalStoreIDs` (_array of string_, nullable) Additional store IDs where the associate can log in.
*   `gender` (_string_) Gender of the store associate.  
    Allowed values: `Male`, `Female`, `Neutral`, `Unknown`.
*   `hireDate` (_integer (int64)_, nullable) Date when the associate is hired or can start work in the store.
*   `terminationDate` (_integer (int64)_, nullable) Termination date for the associate.
*   `firstLoginPasswordReset` (_boolean_) Flag indicating that the password is set on the first login.
*   `mobileConfigID` (_string_, nullable) Mobile configuration ID.  
    Maximum length: 128. Example: `134ac374-0f49-4239-a161-ccfe4d3d7686`.

<!-- document id=8ed6c960cabc18bd65c7d5515039d5f539fc176fdf9e73998b0082b603a4277b url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-store-limits.md -->

# Store Data Limits

| Object                        | Limit B2B Except Where Indicated | Store or Org | Notes                                                                                                               |
| ----------------------------- | -------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| Stores                        | 100                              | Org          | The limit supports 100 B2B stores per Org.                                                                          |
| Languages per Store           | 25<sup>\*</sup>                  | Org          | 25 languages can be associated with a store. Only 1 language per user session can be selected as the user language. |
| Translations and Localization | 25<sup>\*</sup>                  | Org          | The limit supports translating products and categories into 25 languages.                                           |

**note:** The <sup>\*</sup> denotes a soft limit that can be increased by contacting Salesforce customer support. Limits without the <sup>\*</sup> are hard limits and can't be changed.

**Best Practice**

As a data object, a store significantly impacts your org-level data limits. To minimize stress on data limits, carefully consider the number of stores it takes to support your business needs. At the Org level, Store data impacts prices, price books, price book entries, buyer group price books, entitlement policies, buyer groups, buyer accounts, translations, promotions, and coupons.

Evaluate the business objectives of each store and design stores that maximize customer needs. For example, you have a main store so all customers can shop for your main product offerings in several languages and currencies. In addition, you can operate a few specialty stores that offer limited lines of products, serve smaller geographic areas, or cater to specific demographics. A well-architected approach helps you set up stores that use data to generate traffic and revenue.

<!-- document id=b10483334bd118844853f8e8caf9cd0dca4ea67d4949b7b110ce02c579b7de93 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-store.md -->

# Store Data Model

The Store data model is a hub object with preset relationships to Commerce Cloud and Standard Salesforce objects that bring it all together.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the Store data model require at least one of the following licenses: B2B Commerce.

![Diagram of the Inventory data model](https://developer.salesforce.com/media/d2c-commerce/commerce_cloud_store_zh.png)

- [Store](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)
  - [Store Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-store-limits.md)
- [Store Network](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorenetwork.htm)
- [Network](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_network.htm)
- [Site](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_site.htm)
- [StoreTemplate](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_webstoretemplate.htm)
- [Currency](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/field_types.htm)
- [Guest Buyer Profile](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_guestbuyerprofile.htm)
- [Language](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)
- [Location](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_location.htm)
- [PriceBook](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_pricebook2.htm)
- [Tax Policy](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_taxpolicy.htm)
- [Store Buyer Group](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorebuyergroup.htm)
- [BuyerGroup](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergroup.htm)
  - [Pricebook Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-price-book-limits.md)
- [Tax Policy](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_taxpolicy.htm)
- [Store Buyer Group](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorebuyergroup.htm)
  - [Entitlement Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-entitlement-limits.md)
- [BuyerGroup](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_buyergroup.htm)
  - [Shopper Buyer Groups and Accounts Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-shopper-buyer-groups-accounts-limits.md)
- [Store Catalog](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorecatalog.htm)
- [Product Catalog](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorecatalog.htm)
- [Store PriceBook](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstorepricebook.htm)
- [Store Search Product Settings](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstoresearchprodsettings.htm)
  - [Search Data Limits](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-data-model-search-limits.md)

<!-- document id=02bd2cf38cc1746aa5c7b84b4156d7a3b41cbf6a6f92565867448e242205e342 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/store-fulfillment-event-webhook.md -->

Store Fulfillment Event Webhook

# Store Fulfillment Event Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-fulfillment-event-webhook/store-fulfillment-event-webhook-oas-public.yaml)

The specification to implement a webhook in the merchant's system to export store fulfillment events from the POS to the merchant's downstream system.

The store fulfillment events are listed below and are related to BOPIS and BOFIS orders:

1.  BOPIS Order
    
    1.  PACK: Order is ready and items are packed by store associate.
    2.  DELIVERED: Items are picked up by the pickup person.
    3.  CANCELED: Items are canceled by store associate.
2.  BOFIS Order
    
    1.  PACK: Order is ready and items are packed by store associate.
    2.  SHIPPED: Items are shipped by store associate from the store.
    3.  CANCELED: Items are canceled by store associate.

**Version:** 2.3.4

## Tags

### Store Fulfillment Event Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-fulfillment-event-webhook/store-fulfillment-event-webhook-oas-public.yaml)

The specification to implement a webhook in the merchant's system to export store fulfillment events from the POS to the merchant's downstream system.

The store fulfillment events are listed below and are related to BOPIS and BOFIS orders:

1.  BOPIS Order
    
    1.  PACK: Order is ready and items are packed by store associate.
    2.  DELIVERED: Items are picked up by the pickup person.
    3.  CANCELED: Items are canceled by store associate.
2.  BOFIS Order
    
    1.  PACK: Order is ready and items are packed by store associate.
    2.  SHIPPED: Items are shipped by store associate from the store.
    3.  CANCELED: Items are canceled by store associate.

## Operations

### POST Export BOFIS events.

`POST /merchant/webhook/sa/sample/endpoint/to/export/bofis/events/to/external/system`

Operation ID: `exportBofis`. Tags: Store Fulfillment Event Webhook.

Export BOFIS events from merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BOFIS_EXPORT`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `FulfillmentEvent`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### POST Export BOPIS events.

`POST /merchant/webhook/sa/sample/endpoint/to/export/bopis/events/to/external/system`

Operation ID: `exportBopis`. Tags: Store Fulfillment Event Webhook.

Export BOPIS events from merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BOPIS_EXPORT`
    *   **API Endpoint:** Provide the external endpoint to get the order
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}.

#### Request body

Media type: `application/json`. Schema: `FulfillmentEvent`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### FulfillmentEvent

*   `orderId` (_string_, required) Order Id.
*   `orderType` (_string_, required) Order type. It can be either: 1. Store Fulfillment: order is fulfilled by a store. 2. Store Pickup: order is available for pickup at a store.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `productList` (_array of FulfillmentProduct_, required) Item list.
*   `status` (_string_, required) Store Fulfillment Status. 1. PACK: BOPIS, BOFIS, or ROPIS item is packed by store associate. 2. DELIVERED: BOPIS item is picked up by the customer or pickup person. 3. CANCELED: BOPIS or BOFIS item is canceled by store associate. 4. SHIPPED: BOFIS item is shipped by store associate. 5. READY: When importing a fulfillment order into POS, it must have a 'READY' status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`.
*   `storeId` (_string_, required) Store ID from where the item(s) are picked or fulfilled.
*   `deliveryGroupList` (_array of ShipmentDetail_, nullable) The shipping details of the items for store fulfillment order. Each delivery group has shipping address and corresponding shipping method. Each delivery item from productList is associated with its delivery group using productList\[\].deliveryGroupId. Note: It is available only if the CMS Property - 'Allow multiple shipments per cart/order' is enabled. This is a CMS setting and can be found in **CMS** > **Store Management** > **Store Setting** > **Store** fulfillment > Omni settings. If the property is disabled, refer to shipment.
*   `shipment` (_ShipmentDetail_)
*   `pickupDetail` (_PickupDetail_)
*   `note` (_string_) Note provided by associate during pack, pick, or shipment.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### FulfillmentProduct

Item list.

*   `productId` (_string_, required) Product Id.  
    Example: `N0345123`.
*   `orderItemId` (_string (The value should be numeric in string format)_, required) Item sequence/system generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `itemStatus` (_string_, required) Store fulfillment status. Possible values are: 1. **PACK**: The BOPIS, BOFIS, or ROPIS item is packed by a store associate. 2. **DELIVERED**: The BOPIS item is picked up by the customer or a designated pickup person. 3. **CANCELED**: The BOPIS or BOFIS item is canceled by a store associate. 4. **SHIPPED**: The BOFIS item is shipped by a store associate. 5. **READY**: When importing a fulfillment order into POS, it must have a **READY** status.  
    Allowed values: `PACK`, `DELIVERED`, `CANCELED`, `SHIPPED`, `READY`. Example: `PACK`.
*   `name` (_string_, required) Item name.  
    Example: `White Shirt`.
*   `quantity` (_integer (int32)_, required) Item quantity. This represents the original quantity. If the store setting `treatEachItemInCartAsSeparateLineItem` is enabled in CMS, then the quantity should be 1 per line item. This setting can be found in: **CMS** > **Store Management** > **Store Settings** > **OMS** > **Advanced**.  
    Example: `1`.
*   `price` (_number_, required) Item price.  
    Example: `12.05`.
*   `total` (_number_, required) Item total after discount and taxes.  
    Example: `14`.
*   `adjustedQuantity` (_integer (int32)_, required, read-only) Packed quantity for a PACK event, picked-up quantity for a DELIVERED event, and shipped quantity for a SHIPPED event.

### ShipmentDetail

Shipping details applicable for store fulfillment order. If CMS flag 'Allow multiple shipments per cart/order' is enabled, the shipment will be populated. Refer to deliveryGroupList for more details on this CMS flag.

*   `shipmentId` (_string_, required) Shipment ID. Unique number.
*   `trackingNumber` (_string_, required) Shipment tracking number entered by store associate during fulfillment from the store.
*   `shippingMethodId` (_string_, required) Shipping method ID used during placing order. Mandatory.
*   `shippingName` (_string_) Shipping name. Optional.  
    Example: `Express shipping`.
*   `shippingDescription` (_string_) Shipping description. Optional.  
    Example: `Express shipping arrives in 2-3 business days`.
*   `shippingCarrier` (_string_, required) Shipping carrier code. Mandatory.  
    Example: `UPS`.
*   `shippingServiceLevel` (_string_) Shipping service level. Optional.  
    Example: `3 Business Days`.
*   `price` (_number_, required) Shipping Cost. Mandatory.
*   `deliveryDate` (_integer (int64)_) Delivery date in epoch.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.
*   `items` (_array of DeliveryItem_) List of items in this shipment. This can be a subset of the product list provided at the order level.
*   `shippingAddress` (_Address_, required)
*   `expectedShippingDate` (_integer (int64)_) Expected shipping date in epoch. Used for SLA calculation in BOFIS orders.

### PickupDetail

Pickup information for store pickup order.

*   `storeId` (_string_) Store Id.
*   `firstName` (_string_) First name of pickup person.
*   `lastName` (_string_) Last name of pickup person.
*   `email` (_string_, nullable) Email of pickup person.
*   `phone` (_string_, nullable) Phone of pickup person.
*   `pickupDate` (_integer (int64)_, nullable) Customer pickup date & time. Milliseconds since epoch.

### DeliveryItem

List of items in this shipment. This can be a subset of the product list provided at the order level.

*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Number of items.
*   `orderItemId` (_string_) Item sequence/system generated item ID assigned to this line item. Must be unique within this order.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.

### Address

Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_) Customer first name saved for address.  
    Maximum length: 64.
*   `secondName` (_string_, nullable) Customer second name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `suffix` (_string_, nullable) Suffix.
*   `addressLine1` (_string_, required) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required) City.  
    Maximum length: 64.
*   `state` (_string_, required) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `emailAddress` (_string_, nullable) Customer Email Address.
*   `country` (_string_, nullable) Country.
*   `defaultBilling` (_boolean_)
*   `defaultShipping` (_boolean_)

<!-- document id=ff1d35346cb71e12524dede21322f645a1e3864e82b9d0186e0fee00d8534f04 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/store-group-management-api.md -->

Store Group Management API

# Store Group Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-group-management-api/store-group-management-api-oas-public.yaml)

Store Group Management API to create, search, update, and delete store groups from the POS system.

**Version:** 2.3.4

## Tags

### Store Group Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-group-management-api/store-group-management-api-oas-public.yaml)

Store Group Management API to create, search, update, and delete store groups from the POS system.

## Operations

### GET Retrieve all store group prices.

`GET /merchant/v1/admin/storegroup`

Operation ID: `getAllStoreGroupPrices`. Tags: Store Group Management API.

Retrieve all store group prices.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `start` (query, integer (int32))
*   `limit` (query, integer (int32))

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PageStoreGroupResponse`.
    

### PUT Update store group price.

`PUT /merchant/v1/admin/storegroup`

Operation ID: `updateStoreGroupPrice`. Tags: Store Group Management API.

Update a store group price.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `StoreGroupRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

### POST Add store group price for product.

`POST /merchant/v1/admin/storegroup`

Operation ID: `addStoreGroupPrice`. Tags: Store Group Management API.

Add a store group price for a product.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `StoreGroupRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

### PATCH Update store group prices.

`PATCH /merchant/v1/admin/storegroup`

Operation ID: `patchStoreGroups`. Tags: Store Group Management API.

Update store group prices or other attributes. **Limit:** 100 store groups per request. The store groups in the request are updated in batch. Only if all store groups are updated successfully, a successful response is returned. Validation includes:

1.  Empty request
2.  Valid store group ID and product ID.

#### Parameters

*   `PredictSpring-Secret` (header, string)

#### Request body

Media type: `application/json`. Schema: `UpdateStoreGroupsRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PageStoreGroupResponse`.
    

### GET Get store group price for product by productId and storeGroupId

`GET /merchant/v1/admin/storegroup/{storeGroupId}/{productId}`

Operation ID: `getStoreGroupPriceByStoreGroupIdProductId`. Tags: Store Group Management API.

API to get store group price for product by productId and storGroupId.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `storeGroupId` (path, string, required)
*   `productId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

### DELETE Delete store group price by storeGroupId and productId

`DELETE /merchant/v1/admin/storegroup/{storeGroupId}/{productId}`

Operation ID: `deleteStoreGroupPrice`. Tags: Store Group Management API.

API to delete store group price.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `storeGroupId` (path, string, required)
*   `productId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreGroupResponse`.
    

## Schemas

### PageStoreGroupResponse

*   `totalPages` (_integer (int32)_)
*   `totalElements` (_integer (int64)_)
*   `pageable` (_Pageable_)
*   `numberOfElements` (_integer (int32)_)
*   `first` (_boolean_)
*   `number` (_integer (int32)_)
*   `size` (_integer (int32)_)
*   `content` (_array of StoreGroupResponse_)
*   `sort` (_Sort_)
*   `last` (_boolean_)
*   `empty` (_boolean_)

### StoreGroupRequest

Store group pricing request.

*   `storeGroupId` (_string_, required) Store group identifier.  
    Example: `SG-001`.
*   `productId` (_string_, required) Product identifier.  
    Example: `PROD-12345`.
*   `storeGroupPrice` (_number_, required) Store group specific price for the product.  
    Example: `99.99`.
*   `customString0` (_string_, nullable) Custom string field 0 for additional attributes.
*   `customString1` (_string_, nullable) Custom string field 1 for additional attributes.

### StoreGroupResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `storeGroupId` (_string_)
*   `productId` (_string_)
*   `storePrice` (_number_)
*   `customString0` (_string_)
*   `customString1` (_string_)
*   `error` (_boolean_)

### UpdateStoreGroupsRequest

Batch update request for store group prices.

*   `storeGroups` (_array of StoreGroupRequest_, required) List of store group pricing updates. Maximum 100 store groups per request.

### Pageable

*   `pageSize` (_integer (int32)_)
*   `pageNumber` (_integer (int32)_)
*   `paged` (_boolean_)
*   `unpaged` (_boolean_)
*   `offset` (_integer (int64)_)
*   `sort` (_Sort_)

### Sort

*   `unsorted` (_boolean_)
*   `sorted` (_boolean_)
*   `empty` (_boolean_)

<!-- document id=e1e54200b7890908f465d8e76a8dc6d45cd4696d069503076e34d258009306e2 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/store-product-management-api.md -->

Store Product Management API

# Store Product Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-product-management-api/store-product-management-api-oas-public.yaml)

POS Merchant API to manage store inventory.

**Version:** 2.3.4

## Tags

### Store Product Management API

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/store-product-management-api/store-product-management-api-oas-public.yaml)

POS Merchant API to manage store inventory.

## Operations

### GET Retrieve store inventory.

`GET /merchant/{version}/storeproducts/inventory`

Operation ID: `getMultiStoreInventory`. Tags: Store Product Management API.

Return store inventory details for queried store and product ID. This API accepts multiple product IDs and store IDs in one call. - **productIds** (Required): Product IDs to search. Use commas to separate values. Number of IDs range is 0 to 20. - **storeIds**: Store IDs to search. Number of store IDs: 0 to 1000. Use commas to separate values. If empty or null, search in all stores by default.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `storeIds` (query, string)
*   `productIds` (query, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### PUT Update inventory.

`PUT /merchant/{version}/storeproducts/inventory`

Operation ID: `updateStoreInventory`. Tags: Store Product Management API.

Update store or ecommerce inventory of products.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of InventoryAdjustRequest`.

Array of `InventoryAdjustRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of InventoryAdjustResponse`.
    
    Array of `InventoryAdjustResponse`.
    

### POST Create inventory.

`POST /merchant/{version}/storeproducts/inventory`

Operation ID: `addStoreInventory`. Tags: Store Product Management API.

Create store or ecommerce inventory of products.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of InventoryAdjustRequest`.

Array of `InventoryAdjustRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of InventoryAdjustResponse`.
    
    Array of `InventoryAdjustResponse`.
    

### DELETE Delete store inventory.

`DELETE /merchant/{version}/storeproducts/inventory`

Operation ID: `deleteStoreInventory`. Tags: Store Product Management API.

Delete store inventory with last updated date older than the given date. This API deletes store inventory records that have not been updated for a long time.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `lastUpdated` (query, integer (int64))

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

### GET Retrieve store inventory CSV.

`GET /merchant/{version}/storeproducts/inventory/{storeId}`

Operation ID: `getStoreInventory`. Tags: Store Product Management API.

Provide the URL for a CSV file containing store inventory. - **delimiter**: Optional query parameter that accepts two values: csv and tsv. - **fullInventory**: Optional (true/false) to get full inventory. Default is false. If fullInventory is false, inventory updates that happened in a day are provided.

#### Parameters

*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.
*   `storeId` (path, string, required)
*   `delimiter` (query, string)  
    Default: `csv`.
*   `fullInventory` (query, boolean)  
    Default: `false`.
*   `useMapping` (query, boolean)  
    Default: `false`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DownloadResponse`.
    

### PUT Update store product details.

`PUT /merchant/{version}/storeproducts`

Operation ID: `updateStoreProducts`. Tags: Store Product Management API.

Update store product details including item's list price, sale price, quantity, and promo banner text.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of StoreProductDetails`.

Array of `StoreProductDetails`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `array of StoreProductUpdateResponse`.
    
    Array of `StoreProductUpdateResponse`.
    

### PATCH Update store product details.

`PATCH /merchant/{version}/storeproducts`

Operation ID: `patchStoreProducts`. Tags: Store Product Management API.

Update store product details. The request can include any or all details of the store inventory product. **Limit:** 100 store products per request.

#### Parameters

*   `PredictSpring-Secret` (header, string)
*   `version` (path, string, required) Supported: v1.  
    Pattern: v1|v2.

#### Request body

Media type: `application/json`. Schema: `array of StoreProductDetails`.

Array of `StoreProductDetails`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `StoreInventoryProductsUpdateResponse`.
    

## Schemas

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### InventoryAdjustRequest

*   `productId` (_string_, required)
    
    productId
    
    Product ID.
    
      
    Example: `123456`.
*   `storeId` (_string_, required)
    
    storeId
    
    Store ID.
    
      
    Example: `1`.
*   `quantity` (_integer (int32)_, required)
    
    quantity
    
    Quantity adjustment for the product.
    
      
    Example: `10`.
*   `reason` (_string_, required)
    
    reason
    
    Adjustment reason.
    
      
    Example: `Restock`.
*   `overlay` (_boolean_)
    
    overlay
    
    Specifies whether to adjust inventory as a delta (incremental change) or an absolute value. If the value is missing or false, the adjustment will be made as a delta; if the value is true, the adjustment will be made as an absolute value.
    
      
    Example: `true`.

### InventoryAdjustResponse

*   `productId` (_string_, required)
    
    productId
    
    Product ID.
    
      
    Example: `123456`.
*   `storeId` (_string_, required)
    
    storeId
    
    Store ID.
    
      
    Example: `1`.
*   `quantity` (_integer (int32)_, required)
    
    quantity
    
    Quantity adjustment for the product.
    
      
    Example: `10`.
*   `reason` (_string_, required)
    
    reason
    
    Adjustment reason.
    
      
    Example: `Restock`.
*   `overlay` (_boolean_)
    
    overlay
    
    Specifies whether to adjust inventory as a delta (incremental change) or an absolute value. If the value is missing or false, the adjustment will be made as a delta; if the value is true, the adjustment will be made as an absolute value.
    
      
    Example: `true`.
*   `inventoryAdjustStatus` (_string_)  
    Allowed values: `COMPLETE`, `FAILED`.
*   `errorMessage` (_string_)

### DownloadResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `url` (_string_) URL for the artifact to be downloaded.
*   `fileName` (_string_) File location for the artifact to be downloaded.
*   `error` (_boolean_)

### StoreProductDetails

Provide details about products in the store. This includes store-level inventory, store level pricing, store level promotions, etc. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**).

*   `storeId` (_string_) Store or warehouse ID.
*   `productId` (_string_) Product ID.
*   `storeInventory` (_integer (int32)_) Product sellable quantity.
*   `storePrice` (_number_) Product price at the store.
*   `storePromoText` (_string_) Product promotion text applicable to this store.
*   `listPrice` (_number_) Product list price.
*   `salesPrice` (_number_) Product sale price.
*   `storePromoBanner` (_string_) Product promotion banner text.
*   `clearanceItems` (_array of ClearanceItem_) Product location within the store.
*   `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders.
*   `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity.
*   `quantityOnHand` (_integer (int32)_) Product quantity on hand.
*   `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store.
*   `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that isn't for sale.
*   `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that isn't for sale.
*   `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that isn't for sale.
*   `fullPriceSerialNumbers` (_array of string_) Full price serial numbers.
*   `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in store.
*   `customString0` (_string_) Custom string attribute of the product for the store.
*   `customString1` (_string_) Custom string attribute of the product for the store.
*   `quantity` (_integer (int32)_)

### StoreProductUpdateResponse

*   `storeId` (_string_) Store or warehouse ID.
*   `productId` (_string_) Product ID.
*   `storeInventory` (_integer (int32)_) Product sellable quantity.
*   `storePrice` (_number_) Product price at the store.
*   `storePromoText` (_string_) Product promotion text applicable to this store.
*   `listPrice` (_number_) Product list price.
*   `salesPrice` (_number_) Product sale price.
*   `storePromoBanner` (_string_) Product promotion banner text.
*   `clearanceItems` (_array of ClearanceItem_) Product location within the store.
*   `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders.
*   `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity.
*   `quantityOnHand` (_integer (int32)_) Product quantity on hand.
*   `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store.
*   `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store.
*   `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that's not for sale.
*   `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that's not for sale.
*   `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that's not for sale.
*   `fullPriceSerialNumbers` (_array of string_) Full price serial numbers.
*   `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in the store.
*   `customString0` (_string_) Custom string attribute of the product for the store.
*   `customString1` (_string_) Custom string attribute of the product for the store.
*   `quantity` (_integer (int32)_)

### StoreInventoryProductsUpdateResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `products` (_array of StoreProductUpdateResponse_)
*   `error` (_boolean_)

### ClearanceItem

Product location within the store.

*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `clearancePrice` (_number_)
*   `itemLocationWithinStore` (_string_)
*   `instructionText` (_string_)

<!-- document id=d21bc0636a42794869cc2c501b12ffdd1e06d98334f6b39ac0ebe38fa35fa26b url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/store-redirect-mappings.md -->

Store Redirect Mappings

# Store Redirect Mappings

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/store-redirect-mappings/store-redirect-mappings-oas-v1-public.yaml)

## API Overview

The Store Redirect Mappings API provides access to store redirect mapping data within the Store API family. Use this API to manage redirect mappings that configure redirects from one store ID to another. This is typically used for SEO purposes when URL patterns require traffic to be redirected to different stores.

### Features

*   Get Store Redirect Mappings: Retrieve a paginated list of all store redirect mappings in an organization.
*   Get Specific Mapping: Retrieve a specific store redirect mapping by source store ID.
*   Bulk Operations: Create or update multiple store redirect mappings in a single request (only returns counts for performance).
*   Batch Deletion: Delete multiple store redirect mappings in a single request (only returns counts for performance).
*   Pagination: Built-in pagination support with configurable limits and offsets
*   Sorting: Sort results by `sourceStoreId` or `targetStoreId` in ascending or descending order

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

The API client must also have the following OAuth scopes:

*   `sfcc.store-redirect-mappings` - Read access to store redirect mapping resources
*   `sfcc.store-redirect-mappings.rw` - Read and write access to store redirect mapping resources

You must include the relevant scope(s) in the client ID used to generate the token. For details, see the \[Authorization Scopes Catalog\[(https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html).

For detailed setup instructions, see the \[Authorization for Admin APIs guide\[(https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html).

### Mapping Fields

Each store redirect mapping contains the following fields:

*   `sourceStoreId` - The source store ID that should redirect (String, 1-256 characters)
*   `targetStoreId` - The target store ID to redirect to (String, 1-256 characters)

### Use Cases

*   Store Consolidation: When merging stores, redirect old store IDs to new store IDs.
*   SEO Management: Maintain search engine rankings when store IDs change.
*   URL Migration: Handle redirects during store reorganization or rebranding.

**Version:** 1.2.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/store/store-redirect-mappings/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 Authorization via Account Manager
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.store-redirect-mappings: Read access to store redirect mapping resources
    *   Scope sfcc.store-redirect-mappings.rw: Read and write access to store redirect mapping resources

## Operations

### GET Get all store redirect mappings.

`GET /organizations/{organizationId}/store-redirect-mappings`

Operation ID: `getAllStoreRedirectMappings`. Tags: Store Redirect Mappings. Security: AmOAuth2 (sfcc.store-redirect-mappings, sfcc.store-redirect-mappings.rw).

Retrieve all store redirect mappings for the specified organization and site. Use the offset and limit parameters for pagination, or omit them to return all mappings. You can also sort results using the sortBy and sortOrder parameters.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sortBy` (query, string) Field for sorting  
    Allowed values: `sourceStoreId`, `targetStoreId`. Default: `sourceStoreId`. Example: `sourceStoreId`.
*   `sortOrder` (query, string) Sort direction  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.
*   `limit` (query, integer (int32)) Maximum records to retrieve per request, not to exceed 200. Defaults to 25.  
    Default: `25`. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Store redirect mappings returned successfully.
    
    Media type: `application/json`. Schema: `StoreRedirectMappingsResult`.
    
    _Example: StoreRedirectMappingsResultGetResponse_ Successfully retrieved store redirect mappings
    
    Example response for GET all store redirect mappings
    
    ```
    {
      "data": [
        {
          "sourceStoreId": "store1",
          "targetStoreId": "store2"
        },
        {
          "sourceStoreId": "store3",
          "targetStoreId": "store4"
        }
      ],
      "offset": 0,
      "limit": 25,
      "total": 2
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user."
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Your access token is valid, but you don’t have the required permissions to access the resource."
    }
    ```
    

### POST Create or update store redirect mappings.

`POST /organizations/{organizationId}/store-redirect-mappings/actions/bulk`

Operation ID: `upsertStoreRedirectMappings`. Tags: Store Redirect Mappings. Security: AmOAuth2 (sfcc.store-redirect-mappings.rw).

Performs a batch creation or update of store redirect mappings.

*   If a mapping for a `sourceStoreId` already exists, the system updates it; otherwise, it creates a new mapping.
*   If the request contains duplicate keys in the `storeRedirectMappings` object, the system processes only the last value provided for each key.
*   Entries with a blank `sourceStoreId` or `targetStoreId` are ignored.
*   To maintain efficiency with large datasets, the response returns execution counts rather than the full objects.

To verify the current state of mappings after a batch update, use the `GET` endpoint.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `StoreRedirectMappingsRequest`.

_Example: UpsertSingle_ Upsert single store redirect mapping

Example request body for creating or updating a single store redirect mapping

```
{
  "storeRedirectMappings": {
    "store1": "target1"
  }
}
```

_Example: UpsertMultiple_ Upsert multiple store redirect mappings

Example request body for creating or updating multiple store redirect mappings

```
{
  "storeRedirectMappings": {
    "store1": "target1",
    "store2": "target2",
    "store3": "target3"
  }
}
```

#### Responses

*   **207** Multi-status response for non-atomic bulk operation. The response contains operation counts (total, success, failures). All items might succeed (failures = 0) or some might fail (failures > 0).
    
    Media type: `application/json`. Schema: `StoreRedirectMappingsBulkResponse`.
    
    _Example: StoreRedirectMappingsBulkUpsertResponse_ Bulk upsert operation response
    
    Example response for POST bulk upsert operation (HTTP 207 Multi-Status). The response contains operation counts (total, success, failures). This example shows a case where some items succeeded while others failed.
    
    ```
    {
      "total": 100,
      "success": 95,
      "failures": 5
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: EmptyUpsertRequest_ Empty Upsert Request Body
    
    Example error response when upsert request body is missing or empty
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The request body must contain at least one store redirect mapping in the storeRedirectMappings object."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/store-redirect-mappings 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/store-redirect-mappings 403 response._
    

### POST Delete store redirect mappings (batch).

`POST /organizations/{organizationId}/store-redirect-mappings/actions/bulk-delete`

Operation ID: `deleteStoreRedirectMappings`. Tags: Store Redirect Mappings. Security: AmOAuth2 (sfcc.store-redirect-mappings.rw).

Deletes multiple store redirect mappings in a single request.

*   Accepts an array of source store IDs.
*   Blank IDs are skipped, and non-existent mappings are silently ignored.
*   The response returns summary counts instead of deleted items to optimize for large datasets.

Use the `GET` endpoint to retrieve remaining mappings if needed.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `StoreRedirectMappingsDeleteRequest`.

_Example: DeleteSingle_ Delete single store redirect mapping

Example request body for deleting a single store redirect mapping

```
{
  "sourceStoreIds": [
    "store1"
  ]
}
```

_Example: DeleteMultiple_ Delete multiple store redirect mappings

Example request body for deleting multiple store redirect mappings

```
{
  "sourceStoreIds": [
    "store1",
    "store2",
    "store3"
  ]
}
```

#### Responses

*   **207** Multi-status response for non-atomic bulk operation. The response contains operation counts (total, success, failures). All items might succeed (failures = 0) or some might fail (failures > 0).
    
    Media type: `application/json`. Schema: `StoreRedirectMappingsBulkResponse`.
    
    _Example: StoreRedirectMappingsBulkDeleteResponse_ Bulk delete operation response
    
    Example response for POST bulk delete operation (HTTP 207 Multi-Status). The response contains operation counts (total, success, failures). This example shows a case where some items succeeded while others failed.
    
    ```
    {
      "total": 50,
      "success": 48,
      "failures": 2
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: EmptyDeleteRequest_ Empty Delete Request Body
    
    Example error response when delete request body is missing or contains no valid source store IDs
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The request body must contain at least one valid source store ID in the sourceStoreIds array."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/store-redirect-mappings 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/store-redirect-mappings 403 response._
    

### GET Get a specific store redirect mapping.

`GET /organizations/{organizationId}/store-redirect-mappings/{sourceStoreId}`

Operation ID: `getStoreRedirectMapping`. Tags: Store Redirect Mappings. Security: AmOAuth2 (sfcc.store-redirect-mappings, sfcc.store-redirect-mappings.rw).

Retrieve a specific store redirect mapping by source store ID.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `sourceStoreId` (path, SourceStoreId, required) The source store ID to use for retrieval.
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Responses

*   **200** Specified store redirect mapping successfully retrieved.
    
    Media type: `application/json`. Schema: `StoreRedirectMapping`.
    
    _Example: StoreRedirectMappingGetResponse_ Successfully retrieved a store redirect mapping
    
    Example response for GET a specific store redirect mapping
    
    ```
    {
      "sourceStoreId": "store1",
      "targetStoreId": "store2"
    }
    ```
    
*   **400** Bad request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BlankSourceStoreId_ Blank Source Store ID
    
    Example error response when sourceStoreId parameter is blank
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "title": "Bad Request",
      "detail": "The sourceStoreId parameter is required and cannot be blank."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/store-redirect-mappings 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/store-redirect-mappings 403 response._
    
*   **404** Store redirect mapping not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: StoreRedirectMappingNotFound_ Store Redirect Mapping Not Found
    
    Example error response when the requested store redirect mapping was not found
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "title": "Store Redirect Mapping Not Found",
      "detail": "Store redirect mapping with source store ID 'nonexistent-store' was not found."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the organization the request is being made by

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### StoreRedirectMappingsResult

Document representing a paginated list of store redirect mappings.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of StoreRedirectMapping_, required) Array of store redirect mappings

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### StoreRedirectMappingsRequest

*   `storeRedirectMappings` (_object_, required) Map of source store IDs to target store IDs. Keys are source store IDs, values are target store IDs. Note: If duplicate keys are present in the JSON, only the last value for each key will be used.  
    Minimum properties: 1.
    
    Minimum properties: 1.
    
    Additional properties: `string`.
    
    Minimum length: 1. Maximum length: 256. Example: `target1`.
    

### StoreRedirectMappingsBulkResponse

Response for bulk operations (create/update/delete) containing operation counts

*   `total` (_integer (int32)_, required) Total number of items in the request  
    Example: `60000`.
*   `success` (_integer (int32)_, required) Number of items successfully processed  
    Example: `50000`.
*   `failures` (_integer (int32)_, required) Number of items that failed or were skipped (invalid or not found)  
    Example: `10000`.

### StoreRedirectMappingsDeleteRequest

*   `sourceStoreIds` (_array of SourceStoreId_, required) Array of source store IDs to delete  
    Minimum items: 1.

### SourceStoreId

The source store ID that should redirect

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `store1`.

### StoreRedirectMapping

*   `sourceStoreId` (_SourceStoreId_, required)
*   `targetStoreId` (_TargetStoreId_, required)

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### TargetStoreId

The target store ID to redirect to

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `store2`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_object_, required)  
    Maximum: 200.
    
    Includes all fields of `Limit`.
    
    Maximum: 200.
    
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Limit

Maximum records to retrieve per request, not to exceed the maximum defined. A limit must be at least 1 so at least one record is returned (if any match the criteria).

Type: `integer (int32)`.

Default: `10`. Minimum: 1. Example: `10`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=55d72822a37d1f009c28e08394c967c250c4bc4cf07a5c31044f3432638a049d url=/developer/current/en-us/commerce-cloud/commerce-api/guides/shopper-context-api-store-specific.md -->

# Store-Specific Price Books and Promotions

This guide covers how to activate store-specific price books and promotions when the shopper sets their local store.

## Set the Shopper Context

1. Follow the instructions in [Set and Retrieve Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/shopper-context-api.md#set-and-retrieve-shopper-context).
2. Set the qualifier as key and value pair. Use the same qualifier name as in the assignment.
   - `customQualifiers`: Set when you want to trigger pricing and promotion experiences using a dynamic session-based customer group.
   - `assignmentQualifiers`: Set when using the assignment framework. Can be used to trigger pricing and promotion experiences on pages such as Products, Product Search, Basket, and Shipping method.

```json
{
  "assignmentQualifiers": {
    "storeId": "boston"
  }
}
```

## Create the Assignment in Business Manager

Create the assignments using the import and export feature of Business Manager.

Log in to the Business Manager and go to **Merchant Tools** > **Online Marketing** > **Import & Export**.

![Shopper context assignment configuration interface](https://developer.salesforce.com/docs/media/commerce-api/shopper-context-assignments.png)

Use the following sample `assignment.xml` file to import the assignment into B2C Commerce.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<assignments xmlns="http://www.demandware.com/xml/impex/assignment/2020-11-30">
    <assignment assignment-id="assignment_store_boston_promotion">
        <description xml:lang="x-default">Promotions assigned to Store Boston</description>
        <enabled-flag>true</enabled-flag>
        <assigned-sites>
            <site>SiteGenesis</site>
        </assigned-sites>
        <qualifiers match-mode="any">
            <qualifier type="storeId">boston</qualifier>
        </qualifiers>
        <experiences>
          <pricebooks>
            <pricebook-id>sale_pricebook</pricebook-id>
          </pricebooks>
            <promotions>
                <promotion-id>10_%_off_electronics</promotion-id>
            </promotions>
        </experiences>
    </assignment>
</assignments>
```

## See Also

- [createShopperContext](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=createShopperContext)
- [Shopper Login (SLAS)](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=Summary)
- [Assign a Price Book or Promotion to a Specific Store in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_assigning_a_pricebook_or_promotion_specific.htm&type=5) in _Salesforce Help_

<!-- document id=4545cd74729e02023eb9b97d17da6b6cef26be40ad79b44bd3f5c933949c79b0 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-headless-storefront-home.md -->

# Storefront (Home)

### Overview

The storefront landing page initializes the buyer experience by loading the category navigation, displaying promotional content, and rendering a featured product grid. The featured products section automatically uses the first available top-level category from the Commerce APIs. This means the storefront can work with different catalog configurations without changing the code.

This flow demonstrates how a headless storefront can orchestrate category discovery and product merchandising experiences using B2B Commerce Product Category APIs.

![Storefront Home Buyer Journey](https://developer.salesforce.com/media/d2c-commerce/b2b-headless-b2b-commerce-headless-flow-orchestration-storefront-home-buyer-journey-7-1.png '{"class": "image-lg", "title": "Storefront Home Buyer Journey"}')

### B2B Commerce APIs Used in the Flow

| Purpose                  | HTTP Method | Endpoint                                                                                                                                                                                                         |
| ------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Load category menu       | GET         | [`/commerce/webstores/webstoreId/product-categories/children`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_categories_children.htm) |
| Search featured products | POST        | [`/commerce/webstores/{webstoreId}/search/product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)                  |

### Buyer Journey

1. Load the storefront landing page. The storefront calls the following endpoint to retrieve the category menu:

   - GET [`/commerce/webstores/webstoreId/product-categories/children`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_categories_children.htm)

   - Pass the following query parameter: `addHomeMenuItem=false`

   - Setting `addHomeMenuItem=false` returns actual top-level categories in the response. If this parameter isn’t specified, the API wraps the category hierarchy inside a synthetic Home menu item. The generated Home category ID isn't supported for product search requests.

2. Select the first top-level category returned in the category menu response. Use the category ID to run a category-scoped product search.

3. Call the following endpoint to retrieve products for the selected category:

   POST [`/commerce/webstores/{webstoreId}/search/product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)

   ```json
   {
     "categoryId": "<category-id>",
     "page": 0,
     "pageSize": 12,
     "includePrices": true,
     "fields": ["Name", "Description", "StockKeepingUnit"]
   }
   ```

   The `product-search` endpoint requires at least one of the following request parameters:

   - `categoryId`
   - `searchTerm`

4. Render the storefront landing page using the API responses. Use the category menu response to display category navigation and the product search response to display the product grid.

### Extend the Flow

- Replace the storefront landing page implementation while continuing to use the [`/product-categories/children`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_categories_children.htm) and [`product-search`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm) endpoints for category navigation and product discovery.
- To configure a specific featured category, use a predefined category ID instead of dynamically selecting the first top-level category from the category menu response.
- Implement any navigation experience that fits your storefront design. The storefront only depends on the structure of the [`/product-categories/children`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_categories_children.htm) response and not on a specific UI component or rendering framework.

<!-- document id=68be076fd9e464946d9bf64f3718fb7aa2d77827e921a58def999aca73c04dba url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-display-lwc-apis.md -->

# Storefront APIs

B2B stores built with LWR templates support Storefront APIs that help you build custom Lightning Web Components (LWCs) including headers, footers, and banners. Storefront APIs connect LWCs with data and execute processes, like adding a product to a wishlist or a cart, or applying a coupon to an order. Storefront APIs simplify LWC creation and help integrate components into larger page contexts.

| Required Editions                                                                                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------- |
| Available in: Lightning communities accessed through Lightning Experience in **Enterprise**, **Unlimited**, and **Developer** editions. |

Implementing components with Storefront APIs delivers distinct advantages over those relying on platform UI APIs and Aura controllers:

- Security - Storefront APIs automatically apply guardrails, such as buyer entitlement, that protect transactions and personalize customer journeys, with minimum risk.
- Performance and Scalability - Storefront APIs ensure that the same data is not requested and retrieved multiple times. Optimized to use multiple cache layers (browser, CDN, server), Storefront APIs retrieve information efficiently. Storefront Actions, for example, are designed to fetch data from the nearest available source.
- Convenience - Storefront APIs aggregate data from multiple sources and objects, like catalogs, or price books, and can execute business logic (fetch a product price, determine promotion eligibility).
- UI Cohesiveness - Components that implement Storefront APIs help ensure a consistent, cohesive customer experience. Cart components that use Wire Adapters, for example, achieve real-time reactivity: adding an item to a cart automatically updates the cart icon in the header.

The Storefront APIs fetch and display data for Commerce, Platform, and CMS products and include Imperative APIs, Wire Adapters, and Storefront Actions. Each of these differ in how and when they retrieve data for your component. A State Management layer provides access to hosted data via REST APIs and also coordinates operations that engage and update builder components. For example, when a buyer adds a product to the cart via a Storefront API, the State Management layer assures that this updates the list of cart items and the cart status icon. Taken together, the Storefront APIs provide a comprehensive framework for a dynamic shopping experience.

![Illustration of Custom Component Apis.](https://developer.salesforce.com/media/d2c-commerce/custom_comp_apis.png)

- Imperative APIs are process-oriented functions that, for example, call a Connect API method (POST, PUT, PATCH) to update data and return an outcome. Imperative calls typically retrieve hosted data when triggered by a page load or button click. Imperative APIs prompt updates to related entities including Wire Adapters, all orchestrated via State Management.
- Wire Adapters specify a GET method to call and retrieve data from a hosted data source. The adapter automatically updates properties in the LWC when hosted source data changes. When the LWC loads or updates, it executes the adapter call and retrieves the data in real time. For more information, see [Understand the Wire Service](https://developer.salesforce.com/docs/platform/lwc/guide/data-wire-service-about.html).
- Storefront Actions are events, such as adding an item to a cart or using a filter to search on a product variant, that trigger updates to closely-related LWCs. Unlike actual backend API endpoint communication, Storefront Actions react to UI clicks more responsively, by making changes to related page-level components in chain-of-sequence fashion within a proximate scope. When a customer clicks a quantity selector component, for example, a `createCartItemsLoadAction` refreshes the quantity displayed in the cart. Tight data binding ensures that the triggered operation gets and sets data from the closest source. That said, Storefront Actions can result in calls (via Wire Adapters or Imperative APIs) to Rest API endpoints

These tables provide information about custom component Imperative APIs and adapters.

**note:** In B2B stores, imperative Checkout APIs intentionally strip any 'name' properties on ContactPointAddress, CartDeliveryGroup, and OrderDeliveryGroup objects before initiating the request to Checkout Connect Endpoints. The best way to work around this issue is to create custom Apex triggers on insert or update for the relevant objects to update DeliverToName based on your stores globalization requirements. We recommend using the same behavior as the out of the box checkout component and only pass ContactPointAddress ID when calling the updateShippingAddress Imperative API.

## Imperative APIs

| Namespace/Bundle <div style="width:120px"></div> | Name/Interface <div style="width:120px"></div>                                                                                                                                  | Product <div style="width:120px"></div> | API Version <div style="width:120px"></div> | Description <div style="width:120px"></div>                                                                                                                                                                                                                                                                                                                                                                                                           | Associated Endpoint <div style="width:120px"></div>                                                                                                                                               | Javascript Sample <div style="width:120px"></div>                                                                                                                                                                                                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commerce/activitiesApi`                         | `trackAddProductToCart(product: Product): void`                                                                                                                                 | Commerce                                | 55.0                                        | Triggers the `addToCart` activity when a shopper adds a product to the cart. <ul><li>If you replace the Product Detail Purchase Options component with a custom component, implement the addToCart activity to ensure that Commerce Einstein Recommendations use cases generate results based on shopper or buyer view behavior.</li></ul>                                                                                                            | [Einstein Recommendations API](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=Summary.htm)                                                  |                                                                                                                                                                                                                                                                                    |
| `commerce/activitiesApi`                         | `trackClickReco(`<br>`recommenderName: string,`<br>`recoUUID: string,`<br>`product: Product,`<br>`sku: string`<br>`): void`                                                     | Commerce                                | 55.0                                        | Triggers the `clickReco` activity when a recommended product is clicked and the customer is taken to the product detail page. <ul><li>Implement this activity when building a custom Commerce Einstein recommendations component.</li></ul>                                                                                                                                                                                                           | [Einstein Recommendations API](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=Summary.htm)                                                  |                                                                                                                                                                                                                                                                                    |
| `commerce/activitiesApi`                         | `trackViewProduct({`<br>`id: productId,`<br>`sku: string`<br>`}): void`                                                                                                         | Commerce                                | 55.0                                        | Triggers the `viewProduct` activity when a shopper views a Product Detail page. <ul><li>Don’t fire if a product is displayed via a recommendation, search result, or any other means.</li><li>If you replace the Product Detail Purchase Options component with a custom component, implement the viewProduct activity to ensure that Commerce Einstein Recommendations use cases generate results based on shopper or buyer view behavior.</li></ul> | [Einstein Recommendations API](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=Summary.htm)                                                  |                                                                                                                                                                                                                                                                                    |
| `commerce/activitiesApi`                         | `trackViewReco(`<br>`recommenderName: string,`<br>`recoUUID: string,`<br>`products: Products,`<br>`sku: string`<br>`): void`                                                    | Commerce                                | 55.0                                        | Triggers the `viewReco` activity when a recommendation is displayed. <ul><li>Implement this activity when building a custom Commerce Einstein recommendations component.</li><li>If you calculate a recommendation but don’t show it to the customer—for example, it doesn’t have as many results as you like—don’t fire this activity.</li></ul>                                                                                                     | [Einstein Recommendations API](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=Summary.htm)                                                  |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `addItemToCart(productId: string, quantity: number) : Promise<Record<string, unknown>>`                                                                                         | Commerce                                | 57.0                                        | Adds an item to a cart.                                                                                                                                                                                                                                                                                                                                                                                                                               | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `addItemsToCart(payload: AddItemsToCartActionPayload) : Promise<Record<string, unknown>>`                                                                                       | Commerce                                | 57.0                                        | Adds multiple items to the cart.                                                                                                                                                                                                                                                                                                                                                                                                                      | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `applyCouponToCart(couponCode: string) : Promise<Record<string, unknown>>`                                                                                                      | Commerce                                | 57.0                                        | Applies a coupon to the cart.                                                                                                                                                                                                                                                                                                                                                                                                                         | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `deleteCouponFromCart(couponId: string) : Promise<Record<string, unknown>>`                                                                                                     | Commerce                                | 57.0                                        | Deletes an applied coupon from the cart.                                                                                                                                                                                                                                                                                                                                                                                                              | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `deleteCurrentCart() : Promise<Record<string, unknown>>`                                                                                                                        | Commerce                                | 57.0                                        | Deletes an active/current cart.                                                                                                                                                                                                                                                                                                                                                                                                                       | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `deleteItemFromCart(itemId: string) : Promise<Record<string, unknown>>`                                                                                                         | Commerce                                | 57.0                                        | Deletes an item from the cart.                                                                                                                                                                                                                                                                                                                                                                                                                        | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `refreshCartSummary() : Promise<Record<string, unknown>>`                                                                                                                       | Commerce                                | 58.0                                        | Refreshes the cart summary.                                                                                                                                                                                                                                                                                                                                                                                                                           | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `updateCartStatusProcessing(status: boolean) : Promise<void>`                                                                                                                   | Commerce                                | 58.0                                        | Sets the `isProcessing` status field of the cart to the provided processing state.                                                                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/cartApi`                               | `updateItemInCart(itemId: string, quantity: number) : Promise<Record<string, unknown>>`                                                                                         | Commerce                                | 57.0                                        | Updates the item quantity in the cart.                                                                                                                                                                                                                                                                                                                                                                                                                | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                   |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `authorizePayment(checkoutId, token, billingAddress): Promise<PaymentAuthorizationResponse>`                                                                                    | Commerce                                | 56.0                                        | Authorizes a tokenized payment for a checkout session.                                                                                                                                                                                                                                                                                                                                                                                                | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `checkoutStatusIsReady(checkoutStatus: CheckoutStatus \| undefined): boolean`                                                                                                   | Commerce                                | 60.0                                        | Returns true if the supplied checkout status is complete and will accept additional parameters.                                                                                                                                                                                                                                                                                                                                                       | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `createContactPointAddress(address: Address): Promise<Address>`                                                                                                                 | Commerce                                | 56.0                                        | Creates a contact point address record. <ul><li>This API doesn’t affect the checkout session.</li></ul>                                                                                                                                                                                                                                                                                                                                               | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `loadCheckout(): Promise<CheckoutInformation>`                                                                                                                                  | Commerce                                | 57.0                                        | Loads the checkout session or error and saves it in the store for access by the wire adapter.                                                                                                                                                                                                                                                                                                                                                         | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `notifyCheckout(state: CheckoutInformation \| Error \| null): Promise<CheckoutInformation \| Error \| null>`                                                                    | Commerce                                | 57.0                                        | Publishes an updated checkout session state to the store so changes can be propagated by the wire adapter to subscribed listeners. <ul><li>Passing an Error replaces the checkout state and checkout ID with the error state.</li><li>Passing null clears the published data cache. Returns the passed in data unmodified.</li></ul>                                                                                                                  | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `notifyAndPollCheckout(state: CheckoutInformation \| Error \| null): Promise<CheckoutInformation \| Error \| null>`                                                             | Commerce                                | 57.0                                        | Calls `notifyCheckout` and polls async operations. <ul><li>Additionally, when state indicates an async computation in progress (httpStatus is 202), it calls loadCheckout to poll until async tasks complete.</li><li>Automatically triggers a cart summary refresh if needed.</li></ul>                                                                                                                                                              | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `placeOrder(): Promise<OrderConfirmation>`                                                                                                                                      | Commerce                                | 56.0                                        | Finalizes the order, completing the active checkout session.                                                                                                                                                                                                                                                                                                                                                                                          | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `postAuthorizePayment(checkoutId: string, paymentToken: string, billingAddress?: Address, paymentsData?: Object): Promise`                                                      | Commerce                                | 56.0                                        | Sends a client-side authorization result to the server.                                                                                                                                                                                                                                                                                                                                                                                               | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `restartCheckout(): Promise<void>`                                                                                                                                              | Commerce                                | 56.0                                        | Restarts an active checkout process. <ul><li>Before you use this API, clear all cached checkout and address data to prepare for a new “active” session. Clear cache is required anytime the previous checkout session becomes invalid. Attempts to use other checkout APIs after the previous session become invalid and fail until the restart is called.</li></ul>                                                                                  | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `simplePurchaseOrderPayment(checkoutId: string, tokenResponseToken: string, billingAddress: Address): Promise<PaymentAuthorizationResponse>`                                    | B2B Commerce                            | 57                                          | Sends an authenticated buyer's simple purchase order number to the server.                                                                                                                                                                                                                                                                                                                                                                            | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `updateContactInformation(contactInfo: ContactInfo): Promise<void>`                                                                                                             | Commerce                                | 56.0                                        | Updates the guest contact information in the active checkout session.                                                                                                                                                                                                                                                                                                                                                                                 | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `updateContactPointAddress(address: Address): Promise<Address>`                                                                                                                 | Commerce                                | 56.0                                        | Updates an existing contact point address. <ul><li>This API doesn’t affect the checkout session.</li></ul>                                                                                                                                                                                                                                                                                                                                            | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `updateDeliveryMethod(deliveryMethodId: string): Promise<void>`                                                                                                                 | Commerce                                | 56.0                                        | Updates the delivery method for the default delivery group in the active checkout session, and updates the cart summary.                                                                                                                                                                                                                                                                                                                              | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `updateGuestEmail(guestEmail: string \| undefined): Promise<void>`                                                                                                              | Commerce                                | 56.0                                        | Updates the cached guest email value that’s shared between components. <ul><li>This API doesn’t affect the checkout session.</li></ul>                                                                                                                                                                                                                                                                                                                | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `updateShippingAddress(deliveryGroup: DeliveryGroup): Promise<void>`                                                                                                            | Commerce                                | 56.0                                        | Updates the shipping address for the default delivery group in the active checkout session.                                                                                                                                                                                                                                                                                                                                                           | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/checkoutApi`                           | `waitForCheckout(): Promise<CheckoutInformation>`                                                                                                                               | Commerce                                | 57.0                                        | Returns a resolved promise immediately if the checkout status is complete. Otherwise, the returned promise resolves after the checkout status becomes complete or errors.                                                                                                                                                                                                                                                                             | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/contextApi`                            | `getAppContext(): Promise<AppContext>`                                                                                                                                          | Commerce                                | 53.0                                        | Get application-context-specific data.                                                                                                                                                                                                                                                                                                                                                                                                                | [Commerce Webstore Application Context](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_application_context.htm)                 |                                                                                                                                                                                                                                                                                    |
| `commerce/contextApi`                            | `getSessionContext(): Promise<SessionContext>`                                                                                                                                  | Commerce                                | 53.0                                        | Get session-context-specific data.                                                                                                                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Application Context](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_application_context.htm)                 |                                                                                                                                                                                                                                                                                    |
| `commerce/myAccountApi`                          | `createMyAccountAddress(`<br>`address: MyAccountAddress`<br>`): Promise<MyAccountAddress>`                                                                                      | Commerce                                | 54.0                                        | Create an account address.                                                                                                                                                                                                                                                                                                                                                                                                                            | [Commerce Webstore Account Address](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm)              |                                                                                                                                                                                                                                                                                    |
| `commerce/myAccountApi`                          | `deleteMyAccountAddress(`<br>`addressId: string`<br>`): Promise<void>`                                                                                                          | Commerce                                | 54.0                                        | Delete an account address.                                                                                                                                                                                                                                                                                                                                                                                                                            | [Commerce Webstore Account Address](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm)              |                                                                                                                                                                                                                                                                                    |
| `commerce/myAccountApi`                          | `updateMyAccountAddress(`<br>`address: MyAccountAddress`<br>`): Promise<MyAccountAddress>`                                                                                      | Commerce                                | 54.0                                        | Update an account address.                                                                                                                                                                                                                                                                                                                                                                                                                            | [Commerce Webstore Account Address](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm)              |                                                                                                                                                                                                                                                                                    |
| `commerce/myAccountApi`                          | `resetPassword(`<br>`username: string`<br>`): Promise<Response>`                                                                                                                | Commerce                                |                                             | Reset a password.                                                                                                                                                                                                                                                                                                                                                                                                                                     | [Commerce Webstore Account Address](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm)              |                                                                                                                                                                                                                                                                                    |
| `commerce/myAccountApi`                          | `updateMyAccountProfile(profile: MyAccountProfileRequestOptions): Promise<MyAccountProfileResponse>`                                                                            | Commerce                                | 59.0                                        | Update an existing account profile.                                                                                                                                                                                                                                                                                                                                                                                                                   | [Commerce Webstore Account Address](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_accounts_addresses_address.htm)              |                                                                                                                                                                                                                                                                                    |
| `commerce/orderApi`                              | `startReOrder(options: OrderActionAddToCartRequestOptions): Promise<OrderActionAddToCartData>`                                                                                  | Commerce                                | 57.0                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                       | [Commerce Checkout Order](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_checkout_order.htm)                                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/orderApi`                              | `authorizeOrderSummaryAccess(options): Promise<OrderSummaryAccessAuthorizationData>`                                                                                            | Commerce                                | 64.0                                        | Authorize guest users by verifying their personally identifiable information to access the requested order summary. This API is specifically for guest users.                                                                                                                                                                                                                                                                                         | [Commerce Webstore Order Summary Authorization](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_authorization.htm) |                                                                                                                                                                                                                                                                                    |
| `experience/cmsEditorApi`                        | `contentBodyModify['propertyOfContentType'] = 'new value';`<br>`updateContent({`<br>`contentBody: contentBodyModify`<br>`}).then(() => {`<br>`});`                              | CMS                                     | 54.0                                        | Updates the property to be updated in content form. Then calls back after the form is updated.                                                                                                                                                                                                                                                                                                                                                        | [CMS Content](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_contents_content.htm)                                                            |                                                                                                                                                                                                                                                                                    |
| `commerce/effectiveAccountApi`                   | `effectiveAccount.update('Sample Account Id','Sample Account Name');`<br>`const accountId = effectiveAccount.accountId;`<br>`const accountName = effectiveAccount.accountName;` | Commerce                                | 57.0                                        | Sets the account name and ID in session storage.                                                                                                                                                                                                                                                                                                                                                                                                      | [B2B Commerce Resources](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce.htm)                                                             |                                                                                                                                                                                                                                                                                    |
| `commerce/productApi`                            | `getProductCollection(options): Promise<WishlistItemData>`                                                                                                                      | Commerce                                | 64.0                                        | Retrieves detailed product information for multiple products by IDs or SKUs in a single batch request.                                                                                                                                                                                                                                                                                                                                                | [Commerce Webstore Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_products.htm)                                       |                                                                                                                                                                                                                                                                                    |
| `commerce/productApi`                            | `getProductPricingCollection(options): Promise<WishlistItemData>`                                                                                                               | Commerce                                | 64.0                                        | Retrieves pricing information for multiple products based on buyer context and active pricebook.                                                                                                                                                                                                                                                                                                                                                      | [Commerce Webstore Pricing Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_pricing_products.htm)                       |                                                                                                                                                                                                                                                                                    |
| `commerce/productApi`                            | `getProductRecommendations(options): Promise<WishlistItemData>`                                                                                                                 | Commerce                                | 64.0                                        | Retrieves Einstein-powered product recommendations using specified recommender type and anchor context.                                                                                                                                                                                                                                                                                                                                               | [Commerce Einstein Webstore Recommendations](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_ai_recommendations.htm)             |                                                                                                                                                                                                                                                                                    |
| `commerce/promotionApi`                          | `getPromotionPricingCollection(options): Promise<WishlistItemData>`                                                                                                             | Commerce                                | 64.0                                        | Evaluates active promotions for multiple products and returns promotional pricing and adjustments.                                                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Promotion Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce.htm)                                               |                                                                                                                                                                                                                                                                                    |
| `commerce/productApi`                            | `searchProducts(options): Promise<WishlistItemData>`                                                                                                                            | Commerce                                | 64.0                                        | Performs product search with support for search terms, category filters, refinements, and sorting.                                                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Search Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_search_products.htm)                         |                                                                                                                                                                                                                                                                                    |
| `commerce/wishlistApi`                           | `addItemToWishlist(options): Promise<WishlistItemData>`                                                                                                                         | Commerce                                | 58.0                                        | Add items to wishlist.                                                                                                                                                                                                                                                                                                                                                                                                                                | [Commerce Webstore Wishlist Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_items.htm)                           | `const payload = { wishlistId: '3orxx0000000001AAA', effectiveAccountId: '001000000000ABC', wishlistItemInput: { productId: '01txx0000006i2SAAQ' }}; import { addItemToWishlist } from 'commerce/wishlistApi'; const result: WishlistItemData = await addItemToWishlist(payload);` |
| `commerce/wishlistApi`                           | `addWishlistToCart(options): Promise<WishlistToCartResultData>`                                                                                                                 | Commerce                                | 58.0                                        | Add a wishlist to a cart.                                                                                                                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Wishlist, Add to Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_add_to_cart.htm)              |                                                                                                                                                                                                                                                                                    |
| `commerce/wishlistApi`                           | `createWishlist(options): Promise<WishlistData>`                                                                                                                                | Commerce                                | 58.0                                        | Create a wishlist.                                                                                                                                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Wishlists](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlists.htm)                                     |                                                                                                                                                                                                                                                                                    |
| `commerce/wishlistApi`                           | `deleteItemFromWishlist(options): Promise<void>`                                                                                                                                | Commerce                                | 58.0                                        | Delete a wishlist item.                                                                                                                                                                                                                                                                                                                                                                                                                               | [Commerce Webstore Wishlist Item](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist_item.htm)                             |                                                                                                                                                                                                                                                                                    |
| `commerce/wishlistApi`                           | `deleteWishlist(options): Promise<void>`                                                                                                                                        | Commerce                                | 58.0                                        | Delete a wishlist.                                                                                                                                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Wishlists](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist.htm)                                      |                                                                                                                                                                                                                                                                                    |
| `commerce/wishlistApi`                           | `updateWishlist(options): Promise<WishlistSummaryData>`                                                                                                                         | Commerce                                | 58.0                                        | Update a wishlist.                                                                                                                                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Wishlist](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist.htm)                                       |                                                                                                                                                                                                                                                                                    |

## Wire Adapters in the Commerce Namespace

| Namespace/Bundle <div style="width:120px"></div> | Adapter <div style="width:120px"></div> | Product <div style="width:120px"></div> | API Version <div style="width:120px"></div> | Description <div style="width:120px"></div>                                                                                                                                                                                                                                                 | Associated Endpoint <div style="width:120px"></div>                                                                                                                                                 |
| ------------------------------------------------ | --------------------------------------- | --------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commerce/cartApi`                               | `CartAdapter`                           | Commerce                                | 60.0                                        | Retrieves total count of items in the cart.                                                                                                                                                                                                                                                 | [Commerce Webstore Cart](https://developer.salesforce.com/docs/atlas.en-us.248.0.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart.htm)                                           |
| `commerce/cartApi`                               | `CartCouponsAdapter`                    | Commerce                                | 55.0                                        | Retrieves cart coupon information, loads cart coupons.                                                                                                                                                                                                                                      | [Commerce Webstore Cart Coupons](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_carts_cart_coupons.htm)                           |
| `commerce/cartApi`                               | `CartItemsAdapter`                      | Commerce                                | 53.0                                        | Fetches and loads cart items, supports sorting.                                                                                                                                                                                                                                             | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)                                     |
| `commerce/cartApi`                               | `CartPromotionsAdapter`                 | Commerce                                | 55.0                                        | Retrieves and loads cart-level and item promotion information when eligible items are added or updated.                                                                                                                                                                                     | [Commerce Webstore Cart Promotions](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_promotions.htm)                           |
| `commerce/cartApi`                               | `CartSummaryAdapter`                    | Commerce                                | 53.0                                        | Fetches current cart totals data from rollup calculators for CartBadge, CartSummary, Checkout, and other components.                                                                                                                                                                        | [Commerce Webstore Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart.htm)                                                 |
| `commerce/cartApi`                               | `CartStatusAdapter`                     | Commerce                                | 58.0                                        | Retrieves status information about a cart, including whether a cart is processing, whether a cart is ready for checkout, and whether guest cart or checkout access is enabled.                                                                                                              | [Commerce Webstore Cart](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart.htm)                                                 |
| `commerce/checkoutApi`                           | `CheckoutAddressAdapter`                | Commerce                                | 56.0                                        | Uses multiple calls to aggregate results for the get-address-list API. This adapter is a deeper get-address-list API wrapper.                                                                                                                                                               | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                        |
| `commerce/checkoutApi`                           | `CheckoutGuestEmailAdapter`             | Commerce                                | 56.0                                        | Retrieves guest email info value from the store.                                                                                                                                                                                                                                            | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                        |
| `commerce/checkoutApi`                           | `CheckoutInformationAdapter`            | Commerce                                | 56.0                                        | Retrieves data from CheckoutStore, guest email info value from the store, the deliveryGroup, and the first shippingInstructions in the store. Called one time at startup and then whenever the data store updates.                                                                          | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)                                        |
| `commerce/contextApi`                            | `AppContextAdapter`                     | Commerce                                | 53.0                                        | Retrieves app context data from the AppContext store. If data hasn’t been loaded, the adapter calls the application context API.                                                                                                                                                            | [Application Context](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_application_context.htm)                                                       |
| `commerce/contextApi`                            | `SessionContextAdapter`                 | Commerce                                | 53.0                                        | Retrieves session context data from the SessionContext store. If data hasn’t been loaded, the adapter calls the session context API.                                                                                                                                                        | [Session Context](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_session_context.htm)                                                               |
| `commerce/orderApi`                              | `OrderAdapter`                          | Commerce                                | 57.0                                        | Called when a buyer views the order summary of an order. Retrieves an order summary, including fields, based on the effective account ID.                                                                                                                                                   | [Commerce Webstore Order Summary](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary.htm)                               |
| `commerce/orderApi`                              | `OrdersAdapter`                         | Commerce                                | 57.0                                        | Called when a buyer views their order history page. Retrieves order summaries, including fields, for the buyer associated with the storefront.                                                                                                                                              | [Commerce Webstore Order Summaries](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries.htm)                           |
| `commerce/orderApi`                              | `OrdersAdjustmentsAdapter`              | Commerce                                | 57.0                                        | Called when a buyer views the order summary of an order. Retrieves adjustments for an order summary.                                                                                                                                                                                        | [Commerce Webstore Order Summary, Adjustments](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_adjustments.htm)    |
| `commerce/orderApi`                              | `OrderDeliveryGroupsAdapter`            | Commerce                                | 57.0                                        | Called when a buyer views the order summary of an order. Retrieves an order delivery group.                                                                                                                                                                                                 | [Commerce Webstore Order Delivery Groups](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_delivery_groups.htm)       |
| `commerce/orderApi`                              | `OrderItemsAdapter`                     | Commerce                                | 57.0                                        | Called when a buyer views the order summary of an order. Retrieves order items, including fields.                                                                                                                                                                                           | [Commerce Webstore Order Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_items.htm)                                   |
| `commerce/orderApi`                              | `OrderItemsAdjustmentsAdapter`          | Commerce                                | 57.0                                        | Called when a buyer views the order summary of an order. Retrieves adjustments for order items.                                                                                                                                                                                             | [Commerce Webstore Order Items, Adjustments](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summaries_item_adjustments.htm) |
| `commerce/orderApi`                              | `OrderSummaryLookupAdapter`             | Commerce                                | 58.0                                        | Retrieves details about an order summary for a guest shopper or a registered buyer. Authorizes guest users using either a valid session cookie or verification information such as email, last name, or phone.                                                                              | [Commerce Webstore Order Summary Lookup](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_lookup.htm)                 |
| `commerce/orderApi`                              | `OrderSummaryLookupDataAdapter`         | Commerce                                | 64.0                                        | Retrieves details about an order summary for a guest shopper or a registered buyer. Authorizes guest users using either a valid session cookie or an access token.                                                                                                                          | [Commerce Webstore Order Summary Lookup](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary_lookup.htm)                 |
| `commerce/productApi`                            | `ProductAdapter`                        | Commerce                                | 53.0                                        | Called when the product is loaded. Retrieves product information from the store.                                                                                                                                                                                                            | [Commerce Webstore Product](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product.htm)                                           |
| `commerce/productApi`                            | `ProductCollectionAdapter`              | Commerce                                | 54.0                                        | Called when the product is loaded. Retrieve fields, prices, and default images for a list of products.                                                                                                                                                                                      | [Commerce Webstore Products](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_products.htm)                                         |
| `commerce/productApi`                            | `ProductCategoryAdapter`                | Commerce                                | 53.0                                        | Retrieves category information, including fields and related media.                                                                                                                                                                                                                         | [Commerce Webstore Product Category](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_category.htm)                         |
| `commerce/productApi`                            | `ProductCategoryHierarchyAdapter`       | Commerce                                | 53.0                                        | Retrieves a list of product category information, including fields and related media, based on the parent product category Id.                                                                                                                                                              | [Commerce Webstore Product Categories Children](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_categories_children.htm)   |
| `commerce/productApi`                            | `ProductCategoryPathAdapter`            | Commerce                                | 53.0                                        | Retrieves the category path from the root category to the current category.                                                                                                                                                                                                                 | [Commerce Webstore Product Category Path](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_category_path.htm)               |
| `commerce/productApi`                            | `ProductChildrenAdapter`                | Commerce                                | 57.0                                        | Retrieves child product information including pricing, inventory, and promotional pricing. Based on the parent product category ID.                                                                                                                                                         | [[Commerce Webstore Product Children](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_children.htm)                        |
| `commerce/productApi`                            | `ProductPricingAdapter`                 | Commerce                                | 53.0                                        | Called when the product is loaded. Retrieves tiered pricing information for a given product.                                                                                                                                                                                                | [Commerce Webstore Pricing Product](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_price.htm)                             |
| `commerce/productApi`                            | `ProductSearchAdapter`                  | Commerce                                | 57.0                                        | Retrieves products by search parameters.                                                                                                                                                                                                                                                    | [Commerce Webstore Product Search](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)                             |
| `commerce/productApi`                            | `ProductTaxAdapter`                     | Commerce                                | 57.0                                        | Retrieves tax information for a given product.                                                                                                                                                                                                                                              | [Commerce Webstore Taxes](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_tax.htm)                                                 |
| `commerce/recommendationsApi`                    | `ProductRecommendationsAdapter`         | Commerce                                | 55.0                                        | Returns Einstein product recommendations. Import it from the einsteinAPI module within the commerce namespace (`commerce/einsteinAPI`) and then declare its required parameters with the `@wire` decorator.                                                                                 | [B2C Commerce Einstein Product Recommendations API](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_b2c_reco_api_ref.htm)            |
| `commerce/wishlistApi`                           | `WishlistAdapter`                       | Commerce                                | 58.0                                        | Retrieves complete details of a specified Wishlist, including associated items and their related data.                                                                                                                                                                                      | [Commerce Webstore Wishlist](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlist.htm)                                         |
| `commerce/wishlistApi`                           | `WishlistsAdapter`                      | Commerce                                | 58.0                                        | Retrieves a collection of Wishlists. The response doesn't include associated products by default. You can use the `includeDisplayedList` request parameter to fetch complete details of the oldest Wishlist, including associated items and their related data (such as fields and images). | [Commerce Webstore Wishlists](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlists.htm)                                       |

## Wire Adapters in the Experience Namespace

| Namespace/Bundle <div style="width:120px"></div> | Wire Adapter <div style="width:120px"></div> | Product <div style="width:120px"></div> | API Version <div style="width:120px"></div> | Description <div style="width:120px"></div>                                                                                           | Associated Endpoint <div style="width:120px"></div>                                                                                                          |
| ------------------------------------------------ | -------------------------------------------- | --------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `experience/navigationMenuApi`                   | `getNavigationMenu`                          | Platform                                | 54.0                                        | Retrieves the items for a navigation menu in an Experience Cloud site.                                                                | [Navigation Menu Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_navigation_menu_items.htm)            |
| `experience/cmsDeliveryApi`                      | `getContent`                                 | CMS                                     | 54.0                                        | Retrieves published content from an enhanced CMS workspace to use in a custom Lightning web component for an enhanced LWR site.       | [CMS Delivery Content](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_delivery_content.htm)              |
| `experience/cmsEditorApi`                        | `getContext`                                 | CMS                                     | 54.0                                        | Retrieve metadata about the content item in the CMS content editor.                                                                   | [CMS Content](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_contents_content.htm?q=CMS%20get%20content) |
| `experience/cmsEditorApi`                        | `getContent`                                 | CMS                                     | 54.0                                        | Retrieve the title, urlName, and contentBody of the content item based on the content type: image, news, document, or custom content. | [CMS Content](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_contents_content.htm?q=CMS%20get%20content) |

## Storefront Actions

Storefront Actions are centrally combined in the component bundle `commerce/actionApi`. The table shows the factory methods for this bundle.

| Category <div style="width:120px"></div> | Name <div style="width:120px"></div>      | Product <div style="width:120px"></div> | API Version <div style="width:120px"></div> | Description <div style="width:120px"></div>                                                                             | Properties <div style="width:120px"></div>                                                                                                                                                                                                                                                                                                  | actionApi Source <div style="width:120px"></div>                                                                                                                          |
| ---------------------------------------- | ----------------------------------------- | --------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cart                                     | `createCartItemAddAction`                 | Commerce                                | 58.0                                        | Returns an Action that triggers an add-item-to-cart operation from the closest applicable Data Provider.                | `productId: stringquantity?: number`                                                                                                                                                                                                                                                                                                        | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartItemUpdateAction`              | Commerce                                | 58.0                                        | Returns an Action that triggers an update to cart contents operation from the closest applicable Data Provider.         | `cartItemId: stringquantity: number`                                                                                                                                                                                                                                                                                                        | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartItemDeleteAction`              | Commerce                                | 58.0                                        | Returns an Action that triggers a remove-item-in-cart operation from the closest applicable Data Provider.              | `cartItemId: string`                                                                                                                                                                                                                                                                                                                        | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartItemsAddAction`                | Commerce                                | 58.0                                        | Returns an Action that triggers an add items in cart operation from the closest applicable Data Provider.               | `items: Record<string, number>`                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartItemsLoadAction`               | Commerce                                | 58.0                                        | Returns an Action that triggers a load more cart items operation from the closest applicable Data Provider.             |                                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartSortUpdateAction`              | Commerce                                | 58.0                                        | Returns an Action that triggers an update cart sort order operation from the closest applicable Data Provider.          | `sortOrder?: 'CreatedDateDesc' \| 'CreatedDateAsc' \| 'NameDesc' \| 'NameAsc'`                                                                                                                                                                                                                                                              | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartStatusUpdateAction`            | Commerce                                | 58.0                                        | Returns an Action that triggers an update cart status operation from the closest applicable Data Provider.              | `status?: { isProcessing?: boolean; isReadyForCheckout?: boolean; isGuestCartEnabled?: boolean; isGuestCheckoutEnabled?: boolean;}`                                                                                                                                                                                                         | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartClearAction`                   | Commerce                                | 58.0                                        | Returns an Action that triggers a clear cart operation from the closest applicable Data Provider.                       |                                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Cart                                     | `createCartInventoryReserveAction`        | Commerce                                | 59.0                                        | Returns an Action that triggers a reserve inventory for cart items operation from the closest applicable Data Provider. |                                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Cart Items](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_items.htm)           |
| Checkout                                 | `createCheckoutAddressesCreateAction`     | Commerce                                | 58.0                                        | Returns an Action that triggers a checkout addresses create operation from the closest applicable Data Provider.        | `address: { name?: string; firstName?: string; lastName?: string; companyName?: string; street?: string; city?: string; postalCode?: string; region?: string; country?: string; addressId?: string; id?: string; fields?: unknown; geocodeAccuracy?: string; isDefault?: boolean; addressType?: string; label?: string;}`                   | [checkout ActionApi](https://git.soma.salesforce.com/communities/ui-commerce-components/blob/main/packages/commerce-components/src/lwc/commerce/actionApi/checkout.ts)    |
| Checkout                                 | `createCheckoutAddressesPageChangeAction` | Commerce                                | 58.0                                        | Returns an Action that triggers a checkout addresses page change from the closest applicable Data Provider.             | `total: number`                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)              |
| Checkout                                 | `createCheckoutAddressesUpdateAction`     | Commerce                                | 58.0                                        | Returns an Action that triggers a checkout addresses update from the closest applicable Data Provider.                  | `address: { name?: string; firstName?: string; lastName?: string; companyName?: string; street?: string; city?: string; postalCode?: string; region?: string; country?: string; addressId?: string; id?: string; fields?: unknown; geocodeAccuracy?: string; isDefault?: boolean; addressType?: string; label?: string;}`                   | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)              |
| Checkout                                 | `createCheckoutFinalizeAction`            | Commerce                                | 58.0                                        | Returns an Action that triggers a finalize action from the closest applicable Data Provider.                            |                                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)              |
| Checkout                                 | `createCheckoutPlaceOrderAction`          | Commerce                                | 58.0                                        | Returns an Action that triggers a place order action from the closest applicable Data Provider.                         |                                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)              |
| Checkout                                 | `createCheckoutUpdateFormAction`          | Commerce                                | 58.0                                        | Returns an Action that triggers a checkout update from the closest applicable Data Provider.                            | `* applicable {@link DataProvider}.`                                                                                                                                                                                                                                                                                                        | [Commerce Webstore Checkout](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)              |
| Common                                   | `createCommonQuantityUpdateAction`        | Commerce                                | 59.0                                        | Returns an Action that triggers an update quantity from the closest applicable Data Provider.                           | `quantity: number`                                                                                                                                                                                                                                                                                                                          | [Commerce Webstore Cart Item](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)             |
| Coupon                                   | `createCouponApplyAction`                 | Commerce                                | 58.0                                        | Returns an Action that triggers an apply coupon from the closest applicable Data Provider.                              | `couponId: string`                                                                                                                                                                                                                                                                                                                          | [Commerce Webstore Cart Promotions](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_promotions.htm) |
| Coupon                                   | `createCouponDeleteAction`                | Commerce                                | 58.0                                        | Returns an Action that triggers a delete coupon from the closest applicable Data Provider.                              | `couponId: string`                                                                                                                                                                                                                                                                                                                          | [Commerce Webstore Cart Promotions](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_cart_promotions.htm) |
| Order                                    | `createOrderAccessValidateAction`         | Commerce                                | 59.0                                        | Returns an Action that triggers an order summary access validate from the closest applicable Data Provider.             | `verificationDetails: { orderSummaryIdOrRefNumber?: string; fields?: string[] \| null; excludeAdjustments?: boolean \| null; excludeAdjustmentAggregates?: boolean \| null; excludeLineItems?: boolean \| null; excludeDeliveryGroups?: boolean \| null; email?: string \| null; lastName?: string \| null; phoneNumber?: string \| null;}` | [Commerce Webstore Order Summary](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary.htm)     |
| Product                                  | `createProductQuantityUpdateAction`       | Commerce                                | 58.0                                        | Returns an Action that triggers an update product quantity from the closest applicable Data Provider.                   | `productId: stringquantity: number`                                                                                                                                                                                                                                                                                                         | [Commerce Webstore Order Summary](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_order_summary.htm)     |
| Product                                  | `createProductVariantUpdateAction`        | Commerce                                | 58.0                                        | Returns an Action that triggers an update product variant from the closest applicable Data Provider.                    | `options: string[]isValid: boolean`                                                                                                                                                                                                                                                                                                         | [CMS Contents Variant](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_cms_contents_variant.htm?q=variant)                 |
| Product                                  | `createProductSubscriptionUpdateAction`   | Commerce                                | 59.0                                        | Returns an Action that triggers an update product subscription from the closest applicable Data Provider.               | `productSellingModelId: stringsubscriptionTerm?: number \| null`                                                                                                                                                                                                                                                                            | [Subscription](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_responses_subscription.htm)                                           |
| Search                                   | `createSearchSortUpdateAction`            | Commerce                                | 58.0                                        | Returns an Action that triggers an update search sort order from the closest applicable Data Provider.                  | `sortRuleId?: string`                                                                                                                                                                                                                                                                                                                       | [Commerce Webstore Product Search](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)   |
| Search                                   | `createSearchFiltersUpdateAction`         | Commerce                                | 58.0                                        | Returns an Action that triggers an update search filters from the closest applicable Data Provider.                     | `refinements?: ProductSearchRefinement[]; categoryId?: string; page?: number; mruFacet?: SearchFacetData;}`                                                                                                                                                                                                                                 | [Commerce Webstore Product Search](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)   |
| Search                                   | `createSearchFiltersClearAction`          | Commerce                                | 58.0                                        | Returns an Action that triggers a clear search filters from the closest applicable Data Provider.                       |                                                                                                                                                                                                                                                                                                                                             | [Commerce Webstore Product Search](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_product_search.htm)   |
| Wishlist                                 | `createWishlistItemAddAction`             | Commerce                                | 58.0                                        | Returns an Action that triggers an add items to wishlist from the closest applicable Data Provider.                     | `productId: string`                                                                                                                                                                                                                                                                                                                         | [Commerce Webstore Wishlists](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlists.htm?q=wishlist)  |
| Wishlist                                 | `createWishlistItemDeleteAction`          | Commerce                                | 58.0                                        | Returns an Action that triggers an delete items to wishlist from the closest applicable Data Provider.                  | `wishlistItemId: string`                                                                                                                                                                                                                                                                                                                    | [Commerce Webstore Wishlists](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_wishlists.htm?q=wishlist)  |

<!-- document id=d5e168d8c8e4540f4afc9c150abbd5801b14862d3e8bbdd0a29e56ef4aec2d15 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-architecture.md -->

# Storefront Next Architecture

Storefront Next is a full-stack React framework for building B2C Commerce storefronts. It combines server-side rendering with client-side navigation to deliver performant and personalized shopping experiences. Storefront Next runs on Managed Runtime, the infrastructure for deploying, hosting, and monitoring storefronts.

## Architectural Components of Storefront Next

This diagram shows the architecture of Storefront Next, including the request flow from the Shopper Experience to Managed Runtime, data retrieval from the B2C Commerce instance, and interaction with the Salesforce Platform.

![Storefront Next Architecture](https://developer.salesforce.com/docs/media/sfnext/sfnext-architecture2.png '{"class": "image-xl"}')

Here's a description of the request flow.

1. Frontend request: The shopper sends a request to Managed Runtime, which handles server-side rendering (SSR) via the Storefront Next app.
2. Data Store fetching: The Storefront Next app calls into the Managed Runtime Data Store to fetch any required Site Preferences for rendering.
3. Commerce data fetching: The Storefront Next app calls the Salesforce B2C Commerce API (SCAPI) on the B2C Commerce backend.
4. Business logic: The B2C Commerce system executes cartridge logic. It accesses data, such as products, pricing, and content, and uses configurations from Business Manager.
5. Personalization and recommendations: The storefront communicates with the Salesforce Platform via Recommendations APIs to get product recommendations. It fetches personalized content powered by the personalization engine.

### Managed Runtime and Storefront Next

Managed Runtime provides the infrastructure to deploy, host, and monitor the Storefront Next app. Managed Runtime includes these services.

- Static asset storage: Enables uploading and deploying your static assets, such as code artifacts and images.
- Data storage: Enables synchronizing and storage of site preferences from Business Manager for rendering.
- App server: A scalable serverless Node.js runtime environment for your storefront. The Storefront Next app runs on the Managed Runtime app server and uses these technologies: React 19, React Router 7, shadcn/ui, and Tailwind CSS.

### B2C Commerce Backend

The B2C Commerce platform provides the ecommerce services and features that your storefront consumes.

- Custom APIs and hooks: Optional server-side extensions that developers provide with custom APIs packaged in cartridges, or hooks that modify the behavior of SCAPI endpoints.
- Business Manager: Where merchants manage content assets, promotions, campaigns, and personalization.
- Einstein Segments: Customer segmentation for personalized experiences.
- Page Designer: Page Designer connects to the storefront via component metadata. Merchants use Page Designer, a visual editor in Business Manager, to design, schedule, and publish custom pages in the storefront without writing code. See [Salesforce Help: What Is Page Designer?](https://help.salesforce.com/s/articleView?id=cc.b2c_what_is_page_designer.htm&type=5)

### Salesforce Platform Integration

The storefront connects to the Salesforce Platform through these services.

- Personalization Engine: Delivers personalized content and recommendations.
- Einstein for B2C Commerce: AI-powered product recommendations. Data flows between B2C Commerce and the Salesforce Platform through segment synchronization.

## Core Foundation: React Router 7

Storefront Next is built on [React Router 7](https://reactrouter.com/) in framework mode. Before diving into Storefront Next specifics, understand this foundation.

React Router 7 is more than a client-side router—it's a full-stack framework that handles:

- Server-side rendering: Pages render on the server and stream HTML to the browser.
- Data loading: Loaders fetch data before components render.
- Mutations: Actions handle form submissions and data changes.
- Client navigation: After initial load, navigation happens without full page reloads.

If you're familiar with Remix, React Router 7 framework mode uses the same patterns. If you're new to these concepts, we recommend reviewing the [React Router Documentation](https://reactrouter.com/start/framework/routing).

### Technology Stack

| Technology                                    | Purpose                                           | Highlights                                                                                                                                                                            |
| --------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [React 19](https://react.dev/)                | UI components and rendering                       | Includes Node.js streaming, enabling data to be read in small chunks and processed incrementally, which offers scalability and efficient memory use.                                  |
| [React Router 7](https://reactrouter.com/)    | Full-stack framework (routing, SSR, data loading) | React Router's Framework Mode provides a comprehensive development experience by integrating server-side rendering (SSR) and data handling capabilities directly within React Router. |
| [Vite](https://vite.dev/)                     | Build tool and development server                 | Provides fast server start times and improved Hot Module Replacement (HMR) performance.                                                                                               |
| [TypeScript](https://www.typescriptlang.org/) | Statically Type Programming Language              | Enables defining types at design time and catching type-related errors early during development.                                                                                      |
| [Tailwind CSS](https://tailwindcss.com/)      | Styling                                           | Optimized for performance by eliminating runtime overhead, supporting features like tree-shaking and partial rendering in modern React apps.                                          |
| [shadcn/ui](https://ui.shadcn.com/)           | Open-source library for accessible UI components  | Ensures high accessibility standards (WCAG/ARIA) and full customization through the underlying Tailwind CSS.                                                                          |

## Page Rendering

Storefront Next uses React Router's rendering model to deliver fast, personalized pages. Understanding this model helps you build performant storefronts. Storefront Next does server-side rendering (SSR) for all requests and handles only page navigation on the client for subsequent requests, as follows.

1. Initial page load: The first page load uses streaming SSR for data fetching, which ensures that personalization data, such as pricing and promotions, is included in the HTML payload. With React's streaming model, static content appears immediately while dynamic fragments fill in as data becomes available.
2. Subsequent navigations: After the initial load, Storefront Next fetches data via the server-side data loaders. Navigations are handled client-side using React Router 7, which minimizes network requests and enables smooth transitions.

### Initial Page Load

When a shopper first visits your storefront:

1. The request reaches Managed Runtime after passing through eCDN.
2. Middleware runs to set up authentication, configuration, and internationalization.
3. The route's loader fetches data from the Salesforce Commerce API.
4. React renders components on the server and streams HTML to the browser.
5. The browser shows content as it arrives.
6. React hydrates the page, making it interactive.

```
Browser Request
      ↓
   eCDN (cache check)
      ↓
Managed Runtime (Lambda)
      ↓
   Middleware Chain
   ├── App Config
   ├── i18n Setup
   ├── Authentication
   └── Analytics
      ↓
   Route Loader
   (fetches data from Commerce API)
      ↓
   React Render
   (streams HTML)
      ↓
   Browser
   (displays content, hydrates)
```

### Client-Side Hydration and Navigation

After the browser receives the streamed HTML, React hydrates the page. Hydration attaches event handlers to the server-rendered HTML, making buttons clickable, forms submittable, and components interactive. The page is visible immediately and becomes fully interactive after hydration completes.

After hydration, subsequent navigation happens entirely on the client.

1. React Router intercepts link clicks.
2. The new route's `loader` fetches needed data.
3. React updates the DOM without a full page reload.

This hybrid approach gives you the SEO and performance benefits of server rendering with the smooth experience of a single-page app.

## Next Steps

To dive deeper into the technical aspects of Storefront Next, check out these links.

- [Project Configuration and Build Tools](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config-build-tools.md)
- [Data Fetching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data-loading.md)
- [Loading States](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-suspense.md)
- [State Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-state-management.md)
- [Basket Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-basket-management.md)
- [SCAPI Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-api-integration.md)
- [Content Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-caching-content.md)
- [Storage and Sessions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storage-sessions.md)
- [Shopper Context](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-shopper-context.md)
- [Server API Routes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-server-routes.md)
- [UI Styling](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-ui-styling.md)
- [Images](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-images.md)
- [Static Assets](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-static-assets.md)
- [SEO and Metadata](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-seo-metadata.md)
- [AEO and GEO](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-aeo-geo.md)
- [Multisite Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-multi-site.md)
- [Internationalization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-intl.md)
- [Adapters](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-adapters.md)
- [Security Response Headers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-security-headers.md)

<!-- document id=479127455b72839024d8884c45baaadca64c5d11c4da93393849985f3fec9143 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/hybrid-auth-quick-start.md -->

# Storefront Next Automated Setup

Storefront Next Automated Setup is the quickest way to stand up a hybrid storefront, and is available for **Storefront Next** only. The Storefront Next setup flow in Business Manager provisions the storefront, its Managed Runtime (MRT) environment, and eCDN for you, so you complete only the Hybrid Auth configuration.

**note:** Storefront Next Automated Setup applies to Storefront Next only. For PWA Kit (Composable Storefront), SFRA, or SiteGenesis, use [Manual Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-manual-setup.md).

## Before You Begin

Complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md) (SLAS, session bridging, and Business Manager). These steps are the same for every instance type.

## Set Up by Instance Type

Across all instance types, the Hybrid Auth configuration is the same: enable Hybrid Auth in Business Manager (see [Shared Hybrid Auth Setup, Step 4](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-4-configure-business-manager)) and set the hybrid MRT environment variables `PUBLIC__app__hybrid__enabled` and `PUBLIC__app__hybrid__legacyRoutes`. Only the routing setup differs by environment, as summarized in [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-environment-matrix.md). Configure each instance type as follows.

### PIG (Primary Instance Group)

1. Enable Hybrid Auth in Business Manager.
2. Enable the hybrid environment variables for MRT.
3. Configure eCDN routing using the Business Manager UI. See [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid.md).

### ODS (On-Demand Sandbox)

1. Enable Hybrid Auth in Business Manager.
2. Enable the hybrid environment variables for MRT.
3. Configure eCDN routing using the Business Manager UI. See [Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-ods.md).

### Localhost (Local Development)

1. Enable Hybrid Auth in Business Manager for the target sandbox/site.
2. Enable the hybrid environment variables for the local runtime.
3. Configure routing with the local hybrid proxy instead of eCDN. See [Set Up Hybrid Proxy Locally in Secondary Instance Group (SIG) Environments](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-proxy-local-dev.md).

## Next Steps

- For the full Storefront Next implementation details, including eCDN routing rules, see [Use Storefront Next in a Hybrid Implementation](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid.md).
- To choose how to split traffic between Storefront Next and SFRA/SiteGenesis, see the [Hybrid Storefront Routing Matrix](https://developer.salesforce.com/docs/commerce/sfnext/guides/sfnext-hybrid-routing-matrix.md).
- Review the environment-specific routing deltas in [Hybrid Auth Environments and Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-environment-matrix.md).
- If you hit issues, see [Hybrid Auth Troubleshooting](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-troubleshooting.md).

**See also:** For all other architectures, use [Manual Setup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth-manual-setup.md). For how Hybrid Auth and its setup paths fit together, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md).

<!-- document id=5c947000cdfd5e4dbbb7def3b48a92eddd5df6fefec6d8acbb7feac769c06ce5 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-release-notes.md -->

# Storefront Next Release Notes

Learn about Storefront Next features that are part of the Storefront Next monthly releases.

**tip:** - Because the Storefront Next v1.0.0 release was a major launch, the initial release notes of Storefront Next are in [Storefront Next Version 1.0.0 Release](https://help.salesforce.com/s/articleView?id=release-notes.rn_b2c_sf_next_v_1_0_0_release.htm&release=262&type=5) in the Salesforce Release Notes.
- To check out detailed changes in Storefront Next releases, see the [releases](https://github.com/SalesforceCommerceCloud/storefront-next-template/releases/) page in the [storefront-next-template](https://github.com/SalesforceCommerceCloud/storefront-next-template) GitHub repository. The changes listed in the releases page correspond to merged pull requests, which are the underlying changes of Storefront Next features.
- To check out Managed Runtime release notes for Storefront Next, see [Managed Runtime Release Notes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-release-notes.md).

<!--
TEMPLATE FOR RELEASE NOTE

## <Date> - vx.y.z
OR for the automated setup in Business Manager, use '- B2C Commerce 26.x'
## <Date> - B2C Commerce 26.x

### <Release note title>

<Intro paragraph introduces the what and why>

**Where**: (Optional) Indicate where your feature or change is available in case it requires other products or features turned on, for example, if a feature is available in a specific template.
**When**: (Optional) Use if the feature depends on both the B2C Commerce and a template version, or if it is released later.
For example:
    **When**: This feature is available after the B2C Commerce 26.8 release and is in Storefront Next version 1.2.0.
**Who**: (Optional) If your feature is available only to users with certain licenses or perms, include that info in the Who section.
**Why**: (Optional) Use this section to go into more detail about your feature or change and why it matters to customers. The Why section is a great place for content like examples and screenshots. Including a screenshot? Be sure to add some introductory text. *NOTE*: If you’ve said everything you need to about your feature’s benefits and use cases in your intro, simply delete this section.
**How**: (Optional) Provide a brief, high-level overview of the steps involved in getting your feature up and running. Or, if you're writing about an admin- or dev-focused feature or change, you can include a brief, high-level overview of how to use that feature. Don’t include comprehensive, step-by-step instructions here. Put that info in the topic and link to it in your See Also section.

-->

## September 29, 2026 - B2C Commerce 26.10

### Start Faster with Footwear, Furniture, and Foundations Templates

Choose a Storefront Next template that matches how you sell. Use Foundations when you want the full commerce toolkit with no vertical theme applied so you can configure the storefront your way. Use Footwear Next when shoppers need to determine product fit and use fit and size-related features, such as size guides and a community-driven fit confidence indicator. Use Furniture Next when brands need room-set imagery, detailed dimension and material specs, and financing options.

![Select a template suitable for your merchandise](https://developer.salesforce.com/docs/media/sfnext/sfnext-select-template2.png '{"class": "image-lg"}')

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This change is part of B2C Commerce 26.10.

**How**: In Business Manager, click App Launcher and then select **Administration > Sites > Storefronts > New Storefront**. Click **Use Template** for the selected template.

**See Also**

- [Storefront Next Template Features](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-template-compare.md)
- [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md)
- [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md)
- [Footwear Next Demo Site](https://sfdc.co/bctUqU)
- [Furniture Next Demo Site](https://sfdc.co/bGMvs7)
- [Foundations Demo Site](https://sfdc.co/55pxc)

## September 1, 2026 - Storefront Next 1.3.0

### Show Estimated Delivery Dates on Your Storefront

Use the Commerce Delivery Service (CDS) Commerce App to show shoppers estimated delivery dates on the Checkout and Product Detail pages. Forecast delivery dates using your fulfillment locations, real-time inventory, processing and cutoff times, and carrier transit times. Install and configure the app from Business Manager with minimal custom development.

**Where**: This change applies to Storefront Next for B2C Commerce. Salesforce Order Management is required.

**When**: This feature is available in Storefront Next 1.3.0.

![Install Commerce Delivery Service](https://developer.salesforce.com/docs/media/sfnext/sfnext-commerce-delivery-service.png '{"class": "image-lg"}')

**See Also**

- [Commerce Apps for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_apps.htm)
- [Configure Commerce Delivery Service for B2C Commerce](https://help.salesforce.com/s/articleView?id=commerce.om_configure_commerce_delivery_service.htm)
- [Get Delivery Estimates for a Product](#show-delivery-estimates-for-a-product)

### Guest Shoppers Can Look Up Orders Quickly Without Registration

Enable guest shoppers to look up their order status, shipment tracking, and other details in Storefront Next for orders placed without authentication or account registration. The self-service order lookup feature reduces support inquiries and costs, and improves the post-purchase shopper experience. The guest shopper provides the order number and an email address that's different than the one in their registered account. To make sure only the order recipient can access the order details, guest shoppers must undergo multi-factor verification via email. Guest order lookup returns read-only order details—guests can't make changes to the order, such as canceling an order or returning order items, which require authentication. This feature is turned off by default.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available in Storefront Next 1.3.0.

**See Also**

- [Guest Order Lookup for Unregistered Shoppers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-guest-order.md)

### Show Delivery Estimates for a Product

Shoppers use the Estimated Delivery Date panel to get delivery date estimates for a specific postal code. The delivery estimate for the shipping method that has the latest delivery date is shown. Also, shoppers view delivery date estimates and shipping costs based on the available shipping methods.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available in Storefront Next 1.3.0.

**How**: In the Estimated Delivery Date panel of the product detail page, shoppers enter a postal code and then click **Calculate**.

![Get delivery date estimates for a product](https://developer.salesforce.com/docs/media/sfnext/sfnext-delivery-date.png '{"class": "image-lg"}')

After clicking **Calculate**, the estimated delivery date is populated. To view shipping costs and more delivery dates based on shipping methods, shoppers click **View All Shipping Options**.

![The estimated delivery date appears after specifying a postal code and clicking Calculate](https://developer.salesforce.com/docs/media/sfnext/sfnext-calculated-delivery-date-bopis.png '{"class": "image-lg"}')

If the storefront doesn't have the Buy Online Pick Up In Store (BOPIS) extension installed, the product detail page doesn't have a pickup option and the estimated delivery date is displayed in the Estimated Delivery Date panel.

![The estimated delivery date appears after specifying a postal code and clicking Calculate](https://developer.salesforce.com/docs/media/sfnext/sfnext-delivery-date-filled.png '{"class": "image-lg"}')

To provide the delivery date, install the Commerce Delivery Service (CDS) Commerce App. See [Show Estimated Delivery Dates on Your Storefront](#show-estimated-delivery-dates-on-your-storefront). If a specific product variant, such as a distinct color, isn't configured in the Commerce App, the system calls the [getProduct](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-products?meta=getProduct) SCAPI endpoint to get all shipping methods. Also, it displays a default delivery estimate, such as delivery within 7 to 10 business days.

## August 18, 2026 - B2C Commerce 26.9

### Link Your Storefront to a GitHub Repository in Business Manager

Connect a storefront that was set up with the Salesforce CLI option to an existing GitHub repository in Business Manager. Linking a repository to GitHub enables version control, team collaboration, and CI/CD pipelines for your storefront code. Also, it provides the prerequisites required to install Commerce Apps in your storefront. This feature links existing repositories only and doesn't create a new one.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This change is part of B2C Commerce 26.9.

**How**: In Business Manager, click App Launcher and then select **Administration > Sites > Storefronts**. Select a storefront that was created with the Salesforce CLI option, and then click **Connect to GitHub**.

**See Also**

- [Link Your Storefront to a GitHub Repository in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-github-connect.md)

## August 4, 2026 - Storefront Next 1.2.0

### Streamline Sign-In with Passkeys

Offer passwordless login with passkeys so shoppers can sign in with a device biometric or security key instead of a password. Built on the WebAuthn and FIDO2 standards, passkeys use public key cryptography: the shopper's device holds a private key that never leaves the authenticator, and Shopper Login and API Access Service (SLAS) stores only the corresponding public key. A signed-in shopper can register a passkey on any device with an authenticator, sign in on return visits, and manage or remove registered passkeys from their account. In this release, passkey support doesn't include hybrid storefronts that use Storefront Next.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available in Storefront Next 1.2.0.

**How**: Configure a SLAS client for passkeys through the SLAS Admin UI (Relying Party ID and Allowed Origins), then set `features.passkey.enabled` to `true` in `config.server.ts`. Choose an OTP delivery method with `features.passkey.mode` (`email` or `callback`).

![Manage passkeys in the account area](https://developer.salesforce.com/docs/media/sfnext/sfnext-passkey-manage.png '{"class": "image-md"}')

**See Also**

- [Passwordless Login with Passkeys for Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-passkey-login.md)
- [Passwordless Login with Passkeys](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-passkey.html)

### Manage Sites for Storefront Next in Business Manager

Change the sites assigned to a provisioned storefront after Storefront Next is set up in Business Manager. Add sites for new locales, brands, or markets, or remove sites you no longer need. Site changes propagate to Shopper Login and API Access Service (SLAS) for authentication to B2C Commerce API (SCAPI), and to Managed Runtime (MRT) for environment variable updates. Site management provides a straightforward way to evolve your storefront's site list while keeping all other setup configurations intact. Starting in Storefront Next 1.2, site assignments in the storefront detail page in Business Manager are synchronized live to the storefront from the [MRT Data Store](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-data-store.md) without requiring configuration changes in `config.server.ts`. Before Storefront Next 1.2, the storefront accessed sites in `commerce.sites`, which the MRT Data Store replaces for site assignment retrieval.

**Where**: This feature is available in Storefront Next 1.2.0 and B2C Commerce 26.8.

**When**: This feature is available a few days after the Storefront Next 1.2.0 release.

![Manage sites modal for changing site assignments for the storefront](https://developer.salesforce.com/docs/media/sfnext/manage-sites.png '{"class": "image-lg"}')

**See Also**

- [Manage Sites for Storefront Next in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-manage-sites.md)

### Send Storefront Next Analytics Events to Data 360

Use the new built-in engagement adapter for Data 360 (formerly Data Cloud) to send analytics events to Data 360. After you connect Storefront Next to Data 360 and set your store as a data source, Data 360 receives engagement events, which are triggered by shopper activities in your storefront. The adapter sends only view and impression events, such as viewing a page. Click events aren't supported.

These view and impression events are supported.

- `view_page`: A shopper views a page.
- `view_product`: A shopper views a product detail page.
- `view_search`: A shopper views a category or listing page.
- `view_category`: A shopper performs a product search.
- `view_recommender`: A shopper views personalized recommendations.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available in Storefront Next 1.2.0.

**See Also**

- [Send Storefront Next Analytics Events to Data 360](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data360.md)
- [Track Storefront Next Activity with Analytics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-analytics.md)
- [Engagement Adapter Pattern](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-adapters.md)
- [Data 360](https://help.salesforce.com/s/articleView?id=data.c360_a_data_cloud.htm)

### Integrate Storefront Next with Salesforce Order Management

With the integration with Salesforce Order Management (SOM), Storefront Next displays orders from SOM in the order history page and order detail page. Shoppers can check the status of their orders and manage their orders from Storefront Next. They can track shipment, return items, and cancel an eligible order. The integration keeps storefront orders synchronized with the merchant’s backend order management system. Providing shoppers with self-service order management capabilities from within the storefront enhances the shopper experience and reduces support costs. The integration requires that you set up a connection between the B2C Commerce instance and the Salesforce Order Management (SOM) organization.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available in Storefront Next 1.2.0.

![Order history page showing the orders placed for the logged-in shopper](https://developer.salesforce.com/docs/media/sfnext/sfnext-order-history-page.png '{"class": "image-lg"}')

**See Also**

- [Integrate Storefront Next with Salesforce Order Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-order-mgmt.md)

### Keep Shoppers Browsing with Load More Pagination

The Load More button replaces numbered pagination on product listing pages, appending products without page reloads or scroll position loss. Shoppers stay in a continuous discovery flow as they click to load more products. A progress indicator shows "Showing X of Y products" to maintain context while browsing. The load more behavior offers a better shopper experience than numbered pagination, which breaks browsing flow because of full page reloads. The Load More button is enabled by default. Use the `uiConfig.pages.category.pagination` configuration to set pagination properties or switch to numbered pagination.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available in Storefront Next 1.2.0.

![Load More button](https://developer.salesforce.com/docs/media/sfnext/sfnext-load-more-button.png '{"class": "image-md"}')

**See Also**

- [Keep Shoppers Browsing with Load More Pagination](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-load-more.md)

## July 21, 2026 - B2C Commerce 26.8

### Speed Up Storefront Next Development with the Beauty Street Template

Save time by choosing the new Beauty Street template for storefronts that offer beauty and cosmetic products. The Beauty Street template is customized for the beauty industry. It provides attributes that are specific to beauty products, a custom layout, theme, and style. As part of storefront setup in Business Manager, select the template that's most suitable to your storefront's products and industry.

![Select a template suitable for your merchandise](https://developer.salesforce.com/docs/media/sfnext/sfnext-select-template.png '{"class": "image-lg"}')

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This change is part of B2C Commerce 26.8.

**How**: In Business Manager, click App Launcher and then select **Administration > Sites > Storefronts > New Storefront**. Click **Use Template** for the selected template.

**See Also**

- [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md)
- [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md)
- [Beauty Street Demo Site](https://sfdc.co/storefrontnext-beauty)

## July 9, 2026 - Storefront Next 1.1.0

### Process Payments Natively in Storefront Next with Salesforce Payments

Streamline the checkout experience by offering shoppers multiple payment methods and third-party payment gateways, including Adyen, Stripe, and PayPal, with Salesforce Payments. Simplify the cost and complexity of payment implementation.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available after the B2C Commerce 26.7 release and is in Storefront Next version 1.1.0.

**How**: In Business Manager, click App Launcher, and then select **Merchant Tools > Site > Ordering > Commerce Apps**. In the Providers section, for Payments, click **Get Started**. Install and configure Salesforce Payments.

![Install Salesforce Payments to process payments natively in Storefront Next.](https://developer.salesforce.com/docs/media/sfnext/sfnext-salesforce-payments.png '{"class": "image-lg"}')

**See Also**

- [Commerce Apps for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_commerce_apps.htm)
- [Configure Salesforce Payments for B2C Commerce Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-salesforce-payments.md)
- [Salesforce Payments for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_salesforce_payments.htm&type=5)

### Maintain Shopper Sessions Across Subdomains in Storefront Next

Configure a shared parent cookie domain to keep shoppers logged in with their baskets preserved when navigating between different subdomains. The domain-level cookie applies to storefronts that use multiple subdomains, such as `www.` and `shop.` on the `example.com` domain. It also applies to hybrid PWA Kit and SFRA storefronts that serve different paths under one parent domain. Without this configuration, shoppers lose their login status and shopping baskets when crossing subdomain boundaries. The loss of login status happens because browsers isolate cookies to individual hosts by default. Prevent frustration and abandoned carts by setting up domain-level cookies.

**Where**: This change applies to Storefront Next for B2C Commerce.

**When**: This feature is available in Storefront Next 1.1.0.

**See Also**

- [Maintain Shopper Sessions Across Subdomains in Storefront Next](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-domain-cookie.md)

### Secure Your Storefront and Stabilize APIs by Upgrading to React Router 7.18

As part of upgrading your storefront to Storefront Next 1.1, you must upgrade React Router 7.12 to 7.18. React Router 7.18 provides improved security and stabilized APIs. It fixes an unauthenticated remote-code-execution vulnerability plus four additional security advisories in the turbo-stream dependency. The upgrade replaces several unstable\_\* API symbols with their stable counterparts, reducing breaking changes in future updates. Pin React Router and every `@react-router/*` package to 7.18.0 in `package.json` to prevent using an untested patch. Use the migration guide to perform the upgrade.

**Where**: This change applies to Storefront Next storefronts that use React Router 7.12 or earlier.

**Why**: The migration guide organizes the eight API stabilizations by how they surface—silent failures, typecheck-caught issues, and prefix swaps—so you can address high-risk changes first. For instance, the unstable_instrumentations export rename is silent at compile time but causes OpenTelemetry spans to fail at runtime if missed. The guide flags this upfront. You also get fixes for two React Router 7.16+ behavioral changes: an MRT streaming-drain issue that caused long responses to hang, and a fetcher idle-race condition that prevented checkout actions from firing. Both fixes ship in the SDK, so most projects inherit them automatically.

**How**: To learn more about the migration steps, check out [Migrating to React Router 7.18](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/migrations/react-router-7.18/README.md) in the `storefront-next-template` GitHub repository. The migration guide includes step-by-step instructions, a Claude Code integration, code examples for each rename, and a verification checklist. To automate the migration, paste the guide into a Claude Code session with the framing prompt provided in the "7. Using this guide with Claude Code" section. Claude Code drives the entire rename set while skipping changes your project doesn't need, such as SDK-internal fixes or test-only updates. After the migration, run the verification checklist to confirm all packages pin exactly to 7.18, typechecking passes, and no instrumentation warnings appear in your dev log.

<!-- document id=8e881f5b1927dd1e8573ed92ba242bb8d8f1053f7361a97e020192c62e9e699b url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-template-compare.md -->

# Storefront Next Template Features

When you create a storefront in Business Manager, choose a template that matches your storefront's needs and how you sell your products. Each template provides features for shoppers, and sets the page layout, visual theme, and product attributes shoppers use to browse and buy.

To select a template in Business Manager, click App Launcher, and then select **Administration > Sites > Storefronts > New Storefront**. To preview a layout, click **View Demo**. Then choose a template by clicking **Use Template**. See [Create Storefront Next in Business Manager with a GitHub Repository](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm-github.md) or [Create Storefront Next in Business Manager with Local Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-bm.md).

To select a template in the CLI, choose a template from the list of templates given in the terminal. See [Explore Storefront Next Code Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-quick-start-create-sf.md) and [Command-Line Interface (CLI) Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-cli.md).

## Select a Template

Check out the features included in each template.

| Template                                                                               | When to Use                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Foundations](https://github.com/SalesforceCommerceCloud/storefront-next-foundations)  | Use Foundations when you want the full commerce toolkit with no vertical theme applied so that you can configure the storefront your way. The Foundations template isn't specific to any industry. Use it as a starting point and customize it for your storefront needs. See the [Foundations demo site](https://sfdc.co/55pxc).                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [Retail Next](https://github.com/SalesforceCommerceCloud/storefront-next-template)     | Use Retail Next when you want a template that contains a general retail layout and includes a home page, a Product Listing Page (PLP), and a Product Detail Page (PDP) as the default layout. It includes rich media galleries, ratings and reviews, built-in Buy Online, Pick Up In Store feature and approaching discounts components. The My Account page shows orders, addresses, payment methods, and a wishlist. This template is the base template for other templates. It is the standard for Page Designer content blocks, page variations, and the Storefront Next extension model. Built-in BOPIS (Buy Online, Pick Up In Store) messaging and native "Approaching Discounts" components. See the [Retail Next demo site](https://sfdc.co/storefront-next-demo). |
| [Beauty Next](https://github.com/SalesforceCommerceCloud/storefront-next-beauty)       | Use Beauty Next when you want a variant-rich template that offers ingredient transparency. The product variants that this template offers include shade-related attributes, such as shade name and undertone, and a shade selector for mobile use. Includes a thumb-zone shade selector for mobile users. Product media and variant states update instantly without a full page reload. With the sticky buy bar, the selected shade, price, stock, and add-to-cart button are within reach. See the [Beauty Next demo site](https://sfdc.co/storefrontnext-beauty).                                                                                                                                                                                                         |
| [Footwear Next](https://github.com/SalesforceCommerceCloud/storefront-next-footwear)   | Use Footwear Next when you want shoppers to be able to determine whether a product fits. Includes a multi-system size guide drawer for US, UK, EU, CM size systems, and a community-driven fit confidence indicator. Shoppers choose size, width, and color, compare performance details, and browse by activity such as running or trail. Uses a colorway strip with live hero-image swapping and performance spec cards for technical visualizations (cushioning, heel drop, and terrain). See the [Footwear Next demo site](https://sfdc.co/bctUqU).                                                                                                                                                                                                                     |
| [Furniture Next](https://github.com/SalesforceCommerceCloud/storefront-next-furniture) | Use Furniture Next when your brands need room-set imagery, detailed dimensions and material specifications, delivery services, and financing options. Shoppers compare dimensions, configure size, fabric, and legs, browse by room, and choose delivery and services. See the [Furniture Next demo site](https://sfdc.co/bGMvs7).                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## Product Attributes

Each section describes the catalog attributes to set on products in your catalog. Map these catalog attributes so that the catalog can show them.

### Foundations Attributes

The Foundations template doesn't define `c_category`, `c_subcategory`, `c_materials`, or `c_isLimitedEdition`.

| Attribute                                                                                                 | What the Storefront Displays                                                                               |
| --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Color and size                                                                                            | Variation choices on the product detail page, product listing page, and cart                               |
| `c_refinementColor`                                                                                       | Color filter on the product listing                                                                        |
| `c_isNew`, `c_isSale`, `c_isLimited`, `c_isExclusive`, `c_isTrending`, `c_isBestSeller`, `c_isOutOfStock` | Badges on the product tile, such as New, Sale, Limited, Exclusive, Trending, Best Seller, and Out of Stock |
| `c_availableForInStorePickup`                                                                             | Whether the product can be picked up in a store                                                            |

### Retail Next Attributes

| Attribute                                                                                                 | What the Storefront Displays                                                                                |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Color and size                                                                                            | Variation choices on the product detail page, product listing page, and cart                                |
| `c_refinementColor`                                                                                       | Color filter on the product listing. Values include black, blue, green, red, white, beige, brown, and navy. |
| `c_category`, `c_subcategory`                                                                             | Category classification. Category values are Women, Men, and Kids                                           |
| `c_materials`                                                                                             | Material composition                                                                                        |
| `c_isNew`, `c_isSale`, `c_isLimited`, `c_isExclusive`, `c_isTrending`, `c_isBestSeller`, `c_isOutOfStock` | Badges on the product tile, such as New, Sale, Limited, Exclusive, Trending, Best Seller, and Out of Stock  |
| `c_isLimitedEdition`                                                                                      | Limited-edition flag on the product                                                                         |
| `c_availableForInStorePickup`                                                                             | Whether the product can be picked up in a store                                                             |

### Beauty Next Attributes

| Attribute       | What the Storefront Displays                                                                          |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| Color and size  | Variation choices on the product detail page. The size value name can describe volume, such as 10 ml. |
| `c_ingredients` | Ingredients. Separate lines become a bulleted list.                                                   |
| `c_howToUse`    | How to use                                                                                            |
| `c_keyBenefits` | Key benefits. Separate lines become a bulleted list.                                                  |
| `c_skinType`    | Skin type in the product details                                                                      |
| `c_pdpFinish`   | Finish in the product details                                                                         |
| `c_coverage`    | Coverage in the product details                                                                       |
| `c_size`        | Size in the product details                                                                           |

### Footwear Next Attributes

| Attribute                                                              | What the Storefront Displays                                                    |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Size, width, and color                                                 | Variation choices on the product detail page, product listing page, and cart    |
| `c_activity`                                                           | Activity used for browsing and related products                                 |
| `c_cushioning`, `c_heelDrop`, `c_weight`, `c_supportType`, `c_terrain` | Performance details such as cushioning, heel drop, weight, support, and terrain |
| `c_fitFeedback`                                                        | Fit feedback on the product detail page                                         |
| `c_sizeChart`                                                          | Size chart in the size guide                                                    |

### Furniture Next Attributes

| Attribute                                            | What the Storefront Displays                                                        |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Size, fabric, and leg style                          | Configuration choices, with fabric grouped by family                                |
| `c_width`, `c_depth`, `c_height`                     | Width, depth, and height on the product listing page, product detail page, and cart |
| `c_seatHeight`                                       | Seat height on the product detail page                                              |
| `c_comfortLevel`, `c_style`                          | Comfort and style                                                                   |
| `c_assemblyRequired`, `c_leadTimeDays`, `c_weightKg` | Whether assembly is required, how long the item takes to ship, and weight           |

<!-- document id=a1f19660cdc5ee3bad4254d969e1b6628da8ba32c14400854c3f48b42837d3f3 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/storefront-preview-section.md -->

# Storefront Preview

Preview your PWA Kit storefront based on shopper context such as customer groups, date and time, source code triggers, and qualifiers. Test changes to products, pricing, and marketing strategies in a staging environment before deploying to production—whether you're preparing for an upcoming sale such as a Black Friday or Cyber Monday sale.

In this section:

- **Recommended:** [Preview Your Storefront in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview-bm.md)
- [Storefront Preview in Runtime Admin](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md)
- [Troubleshoot Common Storefront Preview Errors](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview-troubleshoot.md)

<!-- document id=00fbdd67cec5dabdbf9cb16d8dab80bfdef686a12ba81de5ce7110917deebdca url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/storefront-preview.md -->

# Storefront Preview in Runtime Admin

Preview you PWA Kit storefront in Runtime Admin to verify how it looks based on shopper context including customer groups, date and time, source code triggers, and qualifiers. Use it to test changes to products, pricing, and marketing strategies in a staging environment before deploying to production, ensuring your site displays correctly for specific scenarios like upcoming sales or seasonal campaigns.

In addition, integrate Storefront Preview with a third-party content management system (CMS). Let’s say, for example, that you have a holiday sale banner managed by your CMS. You can allow your CMS to recognize the current context, such as the effective date and time, so your site preview displays the correct content, such as the holiday sale banner for the specified time period.

**tip:** Storefront Preview is available in Runtime Admin, but we recommend you preview the storefront in Business Manager, which requires less setup. See [Preview Your Storefront in Business Manager](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview-bm.md).

## Sample Usage

This video shows an example of how to preview your storefront.

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/Gu7QtjU1ykQKQ99CnSMwGi" title="Storefront Preview in a PWA Kit Site" type="vidyard"}

## Prerequisites

To use Storefront Preview, first:

### Have the Required PWA Kit Version

Build your site using [PWA Kit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html) version 2.8.4 or newer or version 3.6.0 or newer. Storefront Preview isn’t available in PWA Kit versions older than 2.8.4 or 3.6.0. Upgrade your project to use PWA Kit 2.8.4 or 3.6.0 depending on your current major version.

### Complete this Additional Setup

- Have access to the project in [Runtime Admin](https://runtime.commercecloud.com/) in any role other than read only. If you don't have access, ask someone in a Managed Runtime (MRT) Admin role to help you with that.
- [Enable shopper context](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api-personalized.html#enable-shopper-context) in Business Manager.
- Set up your site based on the functionality you want to validate in Storefront Preview. Examples:
  - Set up [custom qualifiers](https://help.salesforce.com/s/articleView?id=cc.b2c_using_session_custom_attributes.htm&type=5) and [customer group IDs](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_customer_group.htm&type=5) using customer groups in Business Manager to apply rules for personalized pricing, products, or promotions.
  - To see a personalized shopper experience, set up source code that calls the [Shopper Context endpoints](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html). This is required because Storefront Preview uses context information for personalization.
  - Set up the pricing that you want to offer on a particular date. That way your specified pricing appears when you select that date in Storefront Preview.
- Follow the configuration steps outlined in the [Configure Storefront Preview](#configure-storefront-preview) section.
- Configure your browser to allow third-party cookies on `https://runtime.commercecloud.com`.

### Integration with a Third-Party CMS

Optionally, you can write a function if you want to integrate Storefront Preview with a third-party CMS. See [Add the StorefrontPreview component to your storefront](#4-add-the-storefrontpreview-component-to-your-storefront) and [Integrate with a Third-Party CMS](#integrate-with-a-third-party-cms).

**note:** The function you write to integrate with a third-party CMS must be asynchronous. This will help to avoid unexpected results when you preview your site.

## Supported Browsers

You can use Storefront Preview with the latest versions of Chrome or Safari. Your browser **must** allow `https://runtime.commercecloud.com` to access third-party cookies. Storefront Preview **won't work** if you don't enable third-party cookies.

**tip:** Learn how to enable third-party cookies for [Chrome](https://support.google.com/accounts/answer/61416?hl=en&co=GENIE.Platform%3DDesktop) and [Safari](https://support.apple.com/guide/safari/enable-cookies-ibrw850f6c51/mac).

## Considerations

- Data and experiences shown in Storefront Preview don't necessarily reflect the shopper experience. Shopper personalization requires the use of the Shopper Context API within your PWA Kit project. Learn more about [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html).
- Storefront Preview works on PWA Kit pages and not on Storefront Reference Architecture (SFRA) pages. However, you can use [Storefront Toolkit Site Preview Tool in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_using_the_site_preview_tool.htm) to preview SFRA pages.

## Configure Storefront Preview

Follow these one-time configuration steps required for each site that uses Storefront Preview:

<style>
ul.no-bullets {
    list-style-type: none;
}
</style>

<ul class="no-bullets">
  <li>1. <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html#1-create-a-slas-private-client-for-your-b2c-commerce-instances">Create a SLAS Private Client for your B2C Commerce instances</a></li>
 <li>2. <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html#2-create-mrt-environment-variables-with-the-slas-private-client-details-and-the-commerce-api-short-code">Create MRT Environment Variables with the SLAS Private Client details and the Commerce API Short Code</a></li>
 <li>3. <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html#3-confirm-that-your-account-manager-user-has-access-to-the-b2c-commerce-instance">Confirm that your Account Manager user has access to the B2C Commerce instance</a></li>
 <li>4. <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html#4-add-the-storefrontpreview-component-to-your-storefront">Add the StorefrontPreview component to your storefront</a></li>
 <li>5. <a href="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.html#5-update-the-storefront-content-security-policy-headers">Update the storefront Content Security Policy headers</a></li>
</ul>

### 1. Create a SLAS Private Client for Your B2C Commerce Instances

You must create a Shopper Login and API Access Service (SLAS) private client with the scopes `sfcc.shopper-context.rw` and `sfcc.ts_ext_on_behalf_of` for the B2C Commerce instances used by your storefront. Storefront Preview uses the SLAS private client to set the context in the storefront. The SLAS private client can be easily created using the SLAS Admin UI.

Follow the steps in the [Authorization for Shopper APIs guide](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html) to create a SLAS private client for each B2C Commerce instance where you want to use Storefront Preview:

- Select the app type **BFF or Web App** in the **Which App Type will be used?** field to create a private client.
- Specify the scopes separated by a white space in the **Enter the shopper scopes** field: `sfcc.shopper-context.rw sfcc.ts_ext_on_behalf_of`

Copy the automatically generated client secret displayed at the top of the results page and the client ID so you can use them in the next step.

For CLI client creation, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md#slas-admin-ui-create-a-slas-client).

### 2. Create MRT Environment Variables with the SLAS Private Client details and the Commerce API Short Code

To create the MRT environment variables, call the MRT API endpoint [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update).
Replace `$SLAS_PRIVATE_CLIENT_ID` and `$SLAS_PRIVATE_CLIENT_SECRET` with the values that you copied in step 1. Replace `$CC_SHORT_CODE` with the [short code configuration value](https://developer.salesforce.com/docs/commerce/commerce-api/guide/commerce-api-configuration-values.html#short-code) from Business Manager. You can also use Runtime Admin to manage environment variables. See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.html).

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY="$MOBIFY_API_KEY"

npx @salesforce/b2c-cli mrt env var set \
  "CC_SHORT_CODE=$CC_SHORT_CODE" \
  "SLAS_PRIVATE_CLIENT_ID=$SLAS_PRIVATE_CLIENT_ID" \
  "SLAS_PRIVATE_CLIENT_SECRET=$SLAS_PRIVATE_CLIENT_SECRET" \
  --project my-storefront --environment staging
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
--request 'PATCH' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $MOBIFY_API_KEY" \
--data "{
    \"CC_SHORT_CODE\": {\"value\": \"$CC_SHORT_CODE\"},
    \"SLAS_PRIVATE_CLIENT_ID\": {\"value\": \"$SLAS_PRIVATE_CLIENT_ID\"},
    \"SLAS_PRIVATE_CLIENT_SECRET\": {\"value\": \"$SLAS_PRIVATE_CLIENT_SECRET\"}
}"
```

**note:** Calling this API redeploys your current deployed bundle. You must wait for the redeployment to finish before previewing your storefront. When the redeployment has successfully completed, the bundle appears underneath the heading **Deployed Bundle** in your project directory.

### 3. Confirm that your Account Manager user has access to the B2C Commerce instance

To use Storefront Preview with a storefront connected to your B2C Commerce instance, you must have one of these Account Manager user roles: Business Manager Administrator or Business Manager User. To verify whether you have one of these roles, check your roles in [Account Manager](https://account.demandware.com/).

If you don't have either of the required roles, follow these [Granting Permissions instructions](https://help.salesforce.com/s/articleView?id=000391212&type=1#GrantPerms) to add instances to your Account Manager user.

### 4. Add the StorefrontPreview component to your storefront

**note:** - This step is only required for projects generated prior to the release of PWA Kit version 2.8.0 and 3.2.0.
- If you want to integrate Storefront Preview with a third-party CMS, you must add the `onContextChange` prop to the StorefrontPreview component. Note that `onContextChange` is available in only PWA Kit version 3.6.x or later. If you already added the StorefrontPreview component to your storefront, see [Integrate with a Third-Party CMS](#integrate-with-a-third-party-cms).

For the communication between Runtime Admin and your storefront to work, establish a communications channel. This involves two steps:

- To enable communication, render the `StorefrontPreview` component from the PWA Kit React SDK in your storefront. The `StorefrontPreview` component injects a script to establish communication with Runtime Admin. This script doesn't affect the performance of your storefront because it loads only when your storefront is running in Storefront Preview.
- Wherever you render `StorefrontPreview`, you must define the `getToken` prop, which must return the access token of the current shopper.

Optionally, if you want to integrate Storefront Preview with a third-party CMS, you can add the `onContextChange` prop to the `StorefrontPreview` component. Note that `onContextChange` is available in only PWA Kit version 3.6.x or later. See [Integration with a Third-Party CMS](#integration-with-a-third-party-cms). In the examples below, we add the `onContextChange` prop and pass an asynchronous function to it named `handleContextChange`. You can replace the `console.log` statement in the `handleContextChange` function with your own logic to respond to context changes. Customize the `handleContextChange` function based on your specific requirements. The `newContext` parameter in the function will contain the updated context information.

**If you have PWA Kit version 2.8.x, use the following code in your storefront to establish a communication channel. Add the `StorefrontPreview` component around your `IntlProvider` component in the `_app/index.jsx` file.**

```jsx
// app/component/_app/index.jsx
import StorefrontPreview from 'pwa-kit-react-sdk/storefront-preview'

const App = () => {
  // Optionally, include an asynchronous function such as handleContextChange to integrate with a third-party CMS.
  const handleContextChange = async (newContext) => {
    console.log('Context changed:', newContext)
  }

  return (
    <Box className="sf-app" {...styles.container}>
      <StorefrontPreview getToken={() => window.localStorage.getItem('token')}>
        <IntlProvider>
          <CurrencyProvider currency={currency}>...</CurrencyProvider>
        </IntlProvider>
      </StorefrontPreview>
    </Box>
  )
}

export default App
```

**If you have PWA Kit version 3.6.x, use the following code in your storefront to establish a communication channel. Add the `StorefrontPreview` component around your `IntlProvider` component in the `_app/index.jsx` file.**

```jsx
// app/component/_app/index.jsx
import {StorefrontPreview} from '@salesforce/commerce-sdk-react/components'

const App = () => {
  const {getTokenWhenReady} = useAccessToken()
  // Optionally, include an asynchronous function such as handleContextChange to integrate with a third-party CMS.
  const handleContextChange = async (newContext) => {
    console.log('Context changed:', newContext)
  }

  return (
    <Box className="sf-app" {...styles.container}>
      <StorefrontPreview
        getToken={getTokenWhenReady}
        //Pass the optional handleContextChange function to the onContextChange prop.
        onContextChange={handleContextChange}
      >
        <IntlProvider>
          <CurrencyProvider currency={currency}>...</CurrencyProvider>
        </IntlProvider>
      </StorefrontPreview>
    </Box>
  )
}

export default App
```

### 5. Update the storefront Content Security Policy headers

**note:** - This step is only required for projects generated prior to the release of PWA Kit version 2.8.0 and 3.2.0.
- Starting with version 2.8.1 and 3.2.1, this step is done automatically in new projects.
- This step is _not_ required for projects using PWA Kit version 2.8.0 or 3.2.0, as the `defaultPwaKitSecurityHeaders` middleware doesn't exist in those versions.

To enable the communication channel, your storefront must:

- Allow itself to be embedded in an iframe by Runtime Admin (runtime.commercecloud.com), and
- Allow the script mentioned in step 4 to be loaded and executed.

Enable the communication channel by adding `https://runtime.commercecloud.com` to your Content Security Policy (CSP) `frame-ancestors`, `connect-src`, and `script-src` directives. To have this handled for you automatically, import and use the `defaultPwaKitSecurityHeaders` middleware provided by the `pwa-kit-runtime` package.

```js
// app/ssr.js
// Using PWA Kit version 3.6.x
import {getRuntime} from '@salesforce/pwa-kit-runtime/ssr/server/express'
import {defaultPwaKitSecurityHeaders} from '@salesforce/pwa-kit-runtime/utils/middleware'
// Using PWA Kit version 2.8.x
import {getRuntime} from 'pwa-kit-runtime/ssr/server/express'
import {defaultPwaKitSecurityHeaders} from 'pwa-kit-runtime/utils/middleware'

const runtime = getRuntime()
const {handler} = runtime.createHandler(options, (app) => {
    // Set default HTTP security headers required by PWA Kit / Storefront Preview
    app.use(defaultPwaKitSecurityHeaders)
    // ...
```

## Integrate with a Third-Party CMS

**note:** `onContextChange` is available in only PWA Kit version 3.6.x or later.

If you already [added the StorefrontPreview component to your storefront](#4-add-the-storefrontpreview-component-to-your-storefront) and now you want to integrate with a third-party CMS, add the `onContextChange` prop to the `StorefrontPreview` component. See [Integration with a Third-Party CMS](#integration-with-a-third-party-cms).

In the examples below, we add the `onContextChange` prop and an asynchronous function named `handleContextChange`. You can replace the `console.log`statement in the `handleContextChange` function with your own logic to respond to context changes. Customize the `handleContextChange` function based on your specific requirements. The `newContext` parameter in the function will contain the updated context information.

**If you have PWA Kit version 3.6.x or later, use the following code and add the onContextChange prop in the `_app/index.jsx` file.**

```jsx
// app/component/_app/index.jsx
import {StorefrontPreview} from '@salesforce/commerce-sdk-react/components'

const App = () => {
  const {getTokenWhenReady} = useAccessToken()
  // Include an asynchronous function such as handleContextChange to integrate with a third-party CMS.
  const handleContextChange = async (newContext) => {
    console.log('Context changed:', newContext)
  }

  return (
    <Box className="sf-app" {...styles.container}>
      <StorefrontPreview
        getToken={getTokenWhenReady}
        // Pass the handleContextChange function to the onContextChange prop.
        onContextChange={handleContextChange}
      ></StorefrontPreview>
    </Box>
  )
}

export default App
```

## Preview Your Storefront

See [Sample Usage](#sample-usage) for a video that shows how to preview your storefront.

Follow these steps to use Storefront Preview:

1. Open [Runtime Admin](https://runtime.commercecloud.com/login) in your browser and log in using your Account Manager credentials.

2. Navigate to the project's environments page and click **Preview Site** next to the environment in which you want to preview your site.

   A new tab opens showing the storefront, with the Storefront Preview form on the left sidebar.

3. (Optional) Choose the effective **date** and **time** for the context to preview. The date and time displayed is based on your computer's time zone and then converted to UTC time before sending the request that sets the context. If you don't specify a date and time, the preview reflects the current date and time.
4. (Optional) Enter the **source code** that triggers the promotion (campaign assignment) and price books (assigned to source code group) for the context you want to preview.
5. (Optional) Enter the **customer group ids** set up in Business Manager. Separate each ID using a comma.
6. (Optional) Enter the **custom qualifiers** that apply to the personalized prices, products, or promotions set up in Business Manager. The custom qualifier keys must be unique. You can define up to 20 custom qualifiers.
7. Click **Preview**.

   You can now navigate the storefront using the context you want to preview.

   For easier sharing, the URL in the browser tab is updated to include the context values.

**note:** Sometimes you have to interact with the previewed storefront to see the expected behavior. For example, you can click a particular size of clothing to see any applicable discounted price.

## Debug Storefront Preview

If you experience any issues with Storefront Preview, you can enable Storefront Preview logs in your MRT environment.
This prints extra logs when you click the **Preview** button to help you debug the issues.

To enable Storefront Preview logs, add the MRT [environment variable](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#environment-variables) `STOREFRONT_PREVIEW_DEBUG=1` to your MRT environment.

You can use [MRT tail logs](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#tail-logs-on-managed-runtime) to read the Storefront Preview logs.

<!-- document id=550e0dd5d3ca4aebaf81890d615406f8663ab4398c6aefbee023b4bf2f2e5e73 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/storefronts.md -->

Storefronts

# Storefronts

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/storefront/storefronts-oas-v1-public.yaml)

## API Overview

The Storefronts API provides B2C Commerce API (SCAPI)-native access to B2C storefront data for Storefront Next and PWA Kit. It replaces the Business Manager UI and partially data API setup flow. The B2C CLI and other tooling can use it for end-to-end automation. The Storefronts API provides full provisioning for Storefront Next and partial administration tasks for PWA Kit.

*   **Storefronts** — create, retrieve, list, update (site assignment), and delete storefronts at the organization level.

Storefront creation and deletion are asynchronous: the API returns immediately with the resource in a non-terminal status, and callers poll the resource by ID to track progress. See the [Environments API](https://developer.salesforce.com/static/commercecloud/commerce-api/storefront/environments-oas-v1-public.yaml) for managing a storefront's environments.

### Authentication & Authorization

Requests are authenticated with Account Manager OAuth 2.0 bearer tokens (`AmOAuth2`). Access is governed by the Storefronts API scopes: `sfcc.storefront.storefronts` grants read-only access, and `sfcc.storefront.storefronts.rw` grants read and write access. Read operations (`GET`) accept either scope. Write operations (`POST`, `PATCH`, `DELETE`) require `sfcc.storefront.storefronts.rw`.

### Idempotency

*   `POST /storefronts`: This operation is idempotent in effect but not in response code while the storefront record exists. The API rejects the requested storefrontName immediately if a record already exists with the same name, regardless of setup status. The retries don't create a second storefront or modify the existing one. The first call returns 202, and retries return 409 (StorefrontAlreadyExistsErrorResponse). After the storefront is fully deleted, its record is removed and the storefrontName becomes available for reuse. A subsequent POST with that name succeeds (202) instead of returning 409.
*   `PATCH /storefronts/{storefrontId}`: This operation is idempotent. The request body is the full desired `sites` list (complete replacement). Repeating an identical request produces the same resulting state.
*   `DELETE /storefronts/{storefrontId}`: This operation is idempotent in effect, but not in response code. The first call queues deletion (202). Once deletion completes, retrying returns 404. Deleting a storefront while a deletion of that same storefront is already in progress returns 409 (`StorefrontBusyErrorResponse`) rather than queuing a duplicate deletion.

### Use Cases

*   Provision a Storefront Next storefront.
*   Assign or reassign existing sites to a storefront.
*   Poll storefront status during asynchronous provisioning or teardown.
*   Decommission a storefront.

**Version:** 1.0.4

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/storefront/storefronts/v1`
    *   `shortCode (default 123456gf)`

## Security

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.storefront.storefronts: Read-only access to the Storefronts API.
    *   Scope sfcc.storefront.storefronts.rw: Read and write access to the Storefronts API.

## Operations

### GET Get storefronts for an organization.

`GET /organizations/{organizationId}/storefronts`

Operation ID: `getStorefronts`. Security: AmOAuth2 (sfcc.storefront.storefronts, sfcc.storefront.storefronts.rw).

Retrieves the list of storefronts provisioned for the organization, ordered by creationDate ascending.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** List of storefronts successfully retrieved.
    
    Media type: `application/json`. Schema: `StorefrontResult`.
    
    _Example: StorefrontListSuccess_ Successful storefront list result
    
    Example of a successful response returning the list of storefronts for an organization.
    
    ```
    {
      "limit": 25,
      "offset": 0,
      "total": 2,
      "data": [
        {
          "storefrontId": "market-street-a1b2c3",
          "storefrontName": "MarketStreet",
          "type": "storefront_next",
          "setupStatus": "success",
          "sites": [
            "MarketStreet"
          ],
          "creationDate": "2026-04-08T21:47:28.188965Z",
          "lastModified": "2026-04-08T21:47:31.307595Z"
        },
        {
          "storefrontId": "beauty-street-d4e5f6",
          "storefrontName": "BeautyStreet",
          "type": "pwa_kit",
          "setupStatus": "in_progress",
          "sites": [
            "BeautyStreet"
          ],
          "creationDate": "2026-04-09T10:12:00.000000Z",
          "lastModified": "2026-04-09T10:12:00.000000Z"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    

### POST Create a storefront.

`POST /organizations/{organizationId}/storefronts`

Operation ID: `createStorefront`. Security: AmOAuth2 (sfcc.storefront.storefronts.rw).

Queues creation of a new storefront. Returns immediately with the storefront resource in the in\_progress setup status. Poll the storefront by ID to track provisioning progress.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `StorefrontCreateRequest`.

_Example: CreateStorefront_ Create a storefront

Create a storefront with an initial site assignment.

```
{
  "storefrontName": "MarketStreet",
  "type": "storefront_next",
  "sites": [
    "MarketStreet"
  ]
}
```

#### Responses

*   **202** Storefront creation successfully queued.
    
    Media type: `application/json`. Schema: `Storefront`.
    
    _Example: StorefrontCreatedSuccess_ Successful storefront creation
    
    Example of a successful response when a new storefront is queued for creation (202 Accepted).
    
    ```
    {
      "storefrontId": "market-street-a1b2c3",
      "storefrontName": "MarketStreet",
      "type": "storefront_next",
      "setupStatus": "in_progress",
      "sites": [
        "MarketStreet"
      ],
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-08T21:47:28.188965Z"
    }
    ```
    
*   **400** Bad Request. The storefront creation request body is invalid.
    
    Media type: `application/problem+json`. Schema: `InvalidStorefrontCreateRequestErrorResponse | StorefrontSiteNotFoundErrorResponse`.
    
    One of: `InvalidStorefrontCreateRequestErrorResponse`, `StorefrontSiteNotFoundErrorResponse`.
    
    _Example: InvalidStorefrontCreateRequestErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-storefront-create-request",
      "detail": "The storefront creation request body is invalid. A valid storefrontName, type, and sites are required.",
      "title": "Invalid Storefront Create Request"
    }
    ```
    
    _Example: StorefrontSiteNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-site-not-found",
      "detail": "We couldn't find site RefArch.",
      "title": "Storefront Site Not Found"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **409** We couldn't create the storefront due to a conflict.
    
    Media type: `application/problem+json`. Schema: `StorefrontAlreadyExistsErrorResponse | StorefrontSiteCollisionErrorResponse`.
    
    One of: `StorefrontAlreadyExistsErrorResponse`, `StorefrontSiteCollisionErrorResponse`.
    
    _Example: StorefrontAlreadyExistsErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-already-exists",
      "detail": "A storefront with ID 'my-storefront' already exists.",
      "title": "Storefront Already Exists"
    }
    ```
    
    _Example: StorefrontSiteCollisionErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-site-collision",
      "detail": "Site 'RefArch' is already assigned to another storefront.",
      "title": "Storefront Site Collision"
    }
    ```
    

### GET Get a storefront by ID.

`GET /organizations/{organizationId}/storefronts/{storefrontId}`

Operation ID: `getStorefrontById`. Security: AmOAuth2 (sfcc.storefront.storefronts, sfcc.storefront.storefronts.rw).

Retrieves the details of a specific storefront, including its current setup status and assigned sites.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

#### Responses

*   **200** Storefront successfully retrieved.
    
    Media type: `application/json`. Schema: `Storefront`.
    
    _Example: StorefrontSuccess_ Successful storefront retrieval
    
    Example of a successful response returning a single storefront.
    
    ```
    {
      "storefrontId": "market-street-a1b2c3",
      "storefrontName": "MarketStreet",
      "type": "storefront_next",
      "setupStatus": "success",
      "sites": [
        "MarketStreet"
      ],
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-08T21:47:31.307595Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested storefront.
    
    Media type: `application/problem+json`. Schema: `StorefrontNotFoundErrorResponse`.
    
    _Example: StorefrontNotFoundErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-not-found",
      "detail": "We couldn't find storefront my-storefront-a1b2c3.",
      "title": "Storefront Not Found"
    }
    ```
    

### DELETE Delete a storefront.

`DELETE /organizations/{organizationId}/storefronts/{storefrontId}`

Operation ID: `deleteStorefront`. Security: AmOAuth2 (sfcc.storefront.storefronts.rw).

Queues deletion of the storefront. Returns immediately with the storefront resource in the delete\_in\_progress setup status. Poll the storefront by ID to track deletion progress.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

#### Responses

*   **202** Storefront deletion successfully queued.
    
    Media type: `application/json`. Schema: `Storefront`.
    
    _Example: StorefrontDeleteAcceptedSuccess_ Successful storefront deletion request
    
    Example of a successful response when a storefront is queued for deletion (202 Accepted).
    
    ```
    {
      "storefrontId": "market-street-a1b2c3",
      "storefrontName": "MarketStreet",
      "type": "storefront_next",
      "setupStatus": "delete_in_progress",
      "sites": [
        "MarketStreet"
      ],
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-09T09:30:00.000000Z"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Access to requested resource forbidden"
    }
    ```
    
*   **404** We couldn't find the requested storefront.
    
    Media type: `application/problem+json`. Schema: `StorefrontNotFoundErrorResponse`.
    
    _Example StorefrontNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId} 404 response._
    
*   **409** We couldn't delete the storefront because a deletion of this storefront is already in progress.
    
    Media type: `application/problem+json`. Schema: `StorefrontBusyErrorResponse`.
    
    _Example: StorefrontBusyErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-busy",
      "detail": "There is an ongoing deletion for storefront 'my-storefront-a1b2c3'.",
      "title": "Storefront Busy"
    }
    ```
    

### PATCH Update a storefront.

`PATCH /organizations/{organizationId}/storefronts/{storefrontId}`

Operation ID: `updateStorefront`. Security: AmOAuth2 (sfcc.storefront.storefronts.rw).

Updates a storefront. Every field is optional and only the supplied fields are changed. When `sites` is provided it replaces the storefront's full set of assigned sites—a complete replacement, not an incremental update—so the request body must contain the complete desired set of site IDs. The `ssrRegion`, `ssrArchitecture`, `allowCookies`, and `preserveProxyUserAgent` fields update the storefront's default configuration.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `storefrontId` (path, string, required) The storefront identifier that B2C Commerce generates based on the provided storefront name. It consists of lowercase letters, numbers, and hyphens only, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

#### Request body (required)

Media type: `application/json`. Schema: `StorefrontUpdateRequest`.

_Example: UpdateStorefront_ Replace a storefront's site assignment

Replace the full set of sites assigned to a storefront.

```
{
  "sites": [
    "MarketStreet",
    "BeautyStreet"
  ]
}
```

_Example: UpdateStorefrontConfiguration_ Update a storefront's default configuration

Update the storefront's default SSR and proxy configuration without changing its site assignment. Every field is optional.

```
{
  "ssrRegion": "us_east_2",
  "ssrArchitecture": "arm64",
  "allowCookies": true,
  "preserveProxyUserAgent": false
}
```

#### Responses

*   **200** Storefront successfully updated.
    
    Media type: `application/json`. Schema: `Storefront`.
    
    _Example: StorefrontUpdatedSuccess_ Successful storefront site-assignment update
    
    Example of a successful response after replacing a storefront's site assignment.
    
    ```
    {
      "storefrontId": "market-street-a1b2c3",
      "storefrontName": "MarketStreet",
      "type": "storefront_next",
      "setupStatus": "success",
      "sites": [
        "MarketStreet",
        "BeautyStreet"
      ],
      "creationDate": "2026-04-08T21:47:28.188965Z",
      "lastModified": "2026-04-09T09:00:00.000000Z"
    }
    ```
    
*   **400** Bad Request. The storefront update request body is invalid.
    
    Media type: `application/problem+json`. Schema: `InvalidStorefrontUpdateRequestErrorResponse | StorefrontSsrRegionDisabledErrorResponse | StorefrontSsrArchitectureNotEnabledErrorResponse | StorefrontSsrArchitectureX86EndOfLifeErrorResponse`.
    
    One of: `InvalidStorefrontUpdateRequestErrorResponse`, `StorefrontSsrRegionDisabledErrorResponse`, `StorefrontSsrArchitectureNotEnabledErrorResponse`, `StorefrontSsrArchitectureX86EndOfLifeErrorResponse`.
    
    _Example: InvalidStorefrontUpdateRequestErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-storefront-update-request",
      "detail": "The storefront update request body is invalid.",
      "title": "Invalid Storefront Update Request"
    }
    ```
    
    _Example: StorefrontSsrRegionDisabledErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-ssr-region-disabled",
      "detail": "SSR region 'eu_south_1' is temporarily disabled. Choose a different region.",
      "title": "Storefront Ssr Region Disabled"
    }
    ```
    
    _Example: StorefrontSsrArchitectureNotEnabledErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-ssr-architecture-not-enabled",
      "detail": "The Server-Side Rendering architecture configuration isn't enabled for this organization.",
      "title": "Storefront Ssr Architecture Not Enabled"
    }
    ```
    
    _Example: StorefrontSsrArchitectureX86EndOfLifeErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-ssr-architecture-x86-end-of-life",
      "detail": "x86 is past end-of-life and can no longer be selected. Use arm64.",
      "title": "Storefront Ssr Architecture X86 End Of Life"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Unauthorized request"
    }
    ```
    
*   **403** Forbidden. The requested storefront update is not permitted.
    
    Media type: `application/problem+json`. Schema: `StorefrontAllowCookiesBlockedErrorResponse`.
    
    _Example: StorefrontAllowCookiesBlockedErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-allow-cookies-blocked",
      "detail": "You can't modify Allow Cookies for Storefront Next. Cookies are always enabled.",
      "title": "Storefront Allow Cookies Blocked"
    }
    ```
    
*   **404** We couldn't find the requested storefront.
    
    Media type: `application/problem+json`. Schema: `StorefrontNotFoundErrorResponse`.
    
    _Example StorefrontNotFoundErrorResponseExample: same as GET /organizations/{organizationId}/storefronts/{storefrontId} 404 response._
    
*   **409** We couldn't update the storefront's site assignment due to a conflict.
    
    Media type: `application/problem+json`. Schema: `StorefrontSiteCollisionErrorResponse | StorefrontInvalidStateForUpdateErrorResponse`.
    
    One of: `StorefrontSiteCollisionErrorResponse`, `StorefrontInvalidStateForUpdateErrorResponse`.
    
    _Example StorefrontSiteCollisionErrorResponseExample: same as POST /organizations/{organizationId}/storefronts 409 response._
    
    _Example: StorefrontInvalidStateForUpdateErrorResponseExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/storefront-invalid-state-for-update",
      "detail": "Storefront 'my-storefront-a1b2c3' can't be updated while its setup status is 'in_progress'.",
      "title": "Storefront Invalid State For Update"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### StorefrontResult

Result containing a paginated list of storefronts.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Storefront_, required) The list of storefronts. This field can be empty.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### StorefrontCreateRequest

Request body for creating a storefront.

*   `storefrontName` (_string_, required) The name to assign to the new storefront. Must be unique within the organization.  
    Minimum length: 1. Maximum length: 64. Example: `my-storefront`.
*   `type` (_StorefrontCreateType_, required)
*   `sites` (_array of SiteId_, required) The IDs of existing sites to assign to the storefront. At least one site is required.  
    Minimum items: 1.
    
    _Example_
    
    ```
    [
      "RefArch"
    ]
    ```
    

### Storefront

A storefront represents a provisioned Storefront Next or PWA Kit Composable storefront, its type, and the sites assigned to it.

*   `storefrontId` (_string_, required) A storefront identifier that B2C Commerce generates based on the provided storefront name. The storefront ID is unique within the organization. It consists only of lowercase letters, numbers, and hyphens, with no leading or trailing hyphens.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `storefrontName` (_string_, required) The storefront name that you specify when creating a storefront. Must be 64 characters or fewer.  
    Minimum length: 1. Maximum length: 64. Example: `my-storefront`.
*   `type` (_StorefrontType_, required)
*   `setupStatus` (_StorefrontSetupStatus_, required)
*   `sites` (_array of SiteId_) The IDs of the existing sites assigned to this storefront. By default a site can be assigned to only one storefront. Storefronts of type `pwa_kit` are exempt from this restriction and may share a site with another storefront.
    
    _Example_
    
    ```
    [
      "RefArch"
    ]
    ```
    
*   `creationDate` (_string (date-time)_) The timestamp when the storefront was created.  
    Example: `2026-04-08T21:47:28.188965Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the storefront was last modified.  
    Example: `2026-04-08T21:47:31.307595Z`.
*   `ssrRegion` (_SsrRegion_)
*   `ssrArchitecture` (_string_, nullable) The default architecture for the server-side rendering function of environments newly created under this storefront. Null when no architecture default is configured.  
    Allowed values: `x86`, `arm64`. Example: `arm64`.
*   `allowCookies` (_boolean_) Whether cookies are allowed for the storefront. Always enabled for Storefront Next storefronts.  
    Example: `true`.
*   `preserveProxyUserAgent` (_boolean_) Whether the end-user's User-Agent header is preserved on requests forwarded through the storefront's configured proxies.  
    Example: `false`.

### InvalidStorefrontCreateRequestErrorResponse

Returned when the storefront creation request body is malformed or missing required fields.

Includes all fields of `ErrorResponse`.

### StorefrontSiteNotFoundErrorResponse

Returned when a site in the storefront creation request does not exist.

Includes all fields of `ErrorResponse`.

*   `siteId` (_string_) The identifier of the site that couldn't be found.  
    Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### StorefrontAlreadyExistsErrorResponse

Returned when a storefront with the requested storefrontName already exists in the organization.

Includes all fields of `ErrorResponse`.

*   `storefrontName` (_string_) The identifier that was already in use.  
    Minimum length: 1. Maximum length: 64. Example: `my-storefront`.

### StorefrontSiteCollisionErrorResponse

Returned when a site in the request is already assigned to a different storefront. Only storefronts of type pwa\_kit are exempt from this restriction.

Includes all fields of `ErrorResponse`.

*   `siteId` (_string_) The identifier of the site that is already assigned elsewhere.  
    Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### StorefrontNotFoundErrorResponse

Returned when the requested storefront does not exist for this organization.

Includes all fields of `ErrorResponse`.

*   `storefrontId` (_string_) The identifier of the storefront that couldn't be found.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

### StorefrontBusyErrorResponse

Returned when a storefront deletion cannot proceed because a deletion of this storefront is already in progress. Retry once the in-progress deletion completes.

Includes all fields of `ErrorResponse`.

*   `storefrontId` (_string_) The identifier of the storefront whose deletion was requested.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.

### StorefrontUpdateRequest

Request body for updating a storefront. Every field is optional and only the supplied fields are changed. When `sites` is provided it is a complete replacement of the storefront's site assignment, not an incremental update—supply the full set of site IDs.

*   `sites` (_array of SiteId_) The complete set of site IDs assigned to the storefront, replacing any previous assignment. When provided, at least one site is required.  
    Minimum items: 1.
    
    _Example_
    
    ```
    [
      "RefArch"
    ]
    ```
    
*   `ssrRegion` (_SsrRegion_)
*   `ssrArchitecture` (_string_, nullable) The default architecture for the server-side rendering function of environments newly created under this storefront. Set to null to clear the architecture default.  
    Allowed values: `x86`, `arm64`. Example: `arm64`.
*   `allowCookies` (_boolean_) Whether cookies are allowed for the storefront. Cannot be modified for Storefront Next storefronts, where cookies are always enabled.  
    Example: `true`.
*   `preserveProxyUserAgent` (_boolean_) Whether the end-user's User-Agent header is preserved on requests forwarded through the storefront's configured proxies.  
    Example: `false`.

### InvalidStorefrontUpdateRequestErrorResponse

Returned when the storefront update request body is malformed, contains an unsupported value (for example an invalid ssrRegion or ssrArchitecture), or supplies an empty sites list.

Includes all fields of `ErrorResponse`.

### StorefrontSsrRegionDisabledErrorResponse

Returned when the requested ssrRegion is in the temporarily disabled set.

Includes all fields of `ErrorResponse`.

*   `ssrRegion` (_string_) The identifier of the SSR region that is temporarily disabled.  
    Maximum length: 32. Example: `eu_south_1`.

### StorefrontSsrArchitectureNotEnabledErrorResponse

Returned when the x86 ssrArchitecture is requested but the organization is not permitted to configure the SSR architecture.

Includes all fields of `ErrorResponse`.

### StorefrontSsrArchitectureX86EndOfLifeErrorResponse

Returned when the x86 ssrArchitecture is requested after its end-of-life date and the organization has no active grace period.

Includes all fields of `ErrorResponse`.

### StorefrontAllowCookiesBlockedErrorResponse

Returned when allowCookies is changed on a Storefront Next storefront, where cookies are always enabled.

Includes all fields of `ErrorResponse`.

### StorefrontInvalidStateForUpdateErrorResponse

Returned when a site-assignment update is requested for a storefront whose setupStatus is not success.

Includes all fields of `ErrorResponse`.

*   `storefrontId` (_string_) The identifier of the storefront that cannot be updated.  
    Minimum length: 1. Maximum length: 20. Pattern: ^\[a-z0-9\]+(?:-+\[a-z0-9\]+)\*$. Example: `my-storefront-a1b2c3`.
*   `setupStatus` (_string_) The storefront's current setup status, which is not success.  
    Allowed values: `in_progress`, `backfilled`, `failed`, `delete_in_progress`, `delete_failed`, `deleted`, `unknown`. Example: `in_progress`.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### StorefrontCreateType

The type of storefront to create. Only `storefront_next` is currently supported by the create-new-storefront flow.

Type: `string`.

Allowed values: `storefront_next`. Example: `storefront_next`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### StorefrontType

The type of the storefront. `unknown` is a legacy fallback for existing records with no recorded type; it is never a valid value on create.

Type: `string`.

Allowed values: `storefront_next`, `pwa_kit`, `headless`, `unknown`. Example: `storefront_next`.

### StorefrontSetupStatus

The current provisioning/lifecycle status of the storefront.

Type: `string`.

Allowed values: `in_progress`, `success`, `backfilled`, `failed`, `delete_in_progress`, `delete_failed`, `deleted`, `unknown`. Example: `success`.

### SsrRegion

The default AWS region for server-side rendering functions of environments newly created under this storefront. Each value corresponds to the AWS region of the same name with underscores substituted for hyphens (for example, `us_east_2` is the AWS region `us-east-2`).

Type: `string`.

Allowed values: `us_east_1`, `us_east_2`, `us_west_1`, `us_west_2`, `ap_south_1`, `ap_south_2`, `ap_northeast_2`, `ap_southeast_1`, `ap_southeast_2`, `ap_southeast_3`, `ap_northeast_1`, `ap_northeast_3`, `ca_central_1`, `eu_central_1`, `eu_central_2`, `eu_west_1`, `eu_west_2`, `eu_west_3`, `eu_north_1`, `eu_south_1`, `sa_east_1`. Example: `us_east_2`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=56c3b9965567ce52188d789d8cc147cbd99a8c57020f9dc3f13d8702abb8de77 url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/stores.md -->

Stores

# Stores

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/stores/stores-oas-v1-public.yaml)

## API Overview

The Stores API provides access to store data within the Data API family. This API allows you to retrieve and search for stores using complex query expressions.

### Features

*   **Get Stores**: Retrieve a paginated list of all stores in an organization
*   **Store Search**: Search for stores using flexible query expressions
*   **Complex Queries**: Support for term queries, text queries, boolean queries, and range filters
*   **Sorting**: Sort results by any searchable field
*   **Pagination**: Built-in pagination support with configurable limits and offsets
*   **Field Selection**: Use the select parameter to retrieve only specific fields

### Endpoints

#### GET /organizations/{organizationId}/stores

Retrieve a list of all stores within the specified organization. This endpoint returns all stores without any filtering and supports pagination for results.

**Parameters:**

*   `organizationId` (required) - The organization identifier
*   `siteId` (required) - The site identifier
*   `offset` (optional) - Zero-based index of the first store to return (default: 0)
*   `limit` (optional) - Maximum number of stores to return (default: 50, max: 200)
*   `select` (optional) - Property selector to retrieve only specific fields

#### GET /organizations/{organizationId}/stores/{id}

Retrieve detailed information for a specific store by ID.

**Parameters:**

*   `organizationId` (required) - The organization identifier
*   `siteId` (required) - The site identifier
*   `id` (required) - The ID of the store to retrieve
*   `select` (optional) - Property selector to retrieve only specific fields

**Error Responses:**

*   `404` - Store not found when the specified store ID does not exist

#### POST /organizations/{organizationId}/store-search

Search for stores using flexible query expressions with support for filtering, sorting, and pagination.

### Searchable Fields

The following fields are searchable in store queries:

*   `id` - Store identifier (String)
*   `name` - Store name (String)
*   `address1` - Primary address (String)
*   `address2` - Secondary address (String)
*   `city` - City name (String)
*   `stateCode` - State code (String)
*   `postalCode` - Postal code (String)
*   `countryCode` - Country code (String)
*   `phone` - Phone number (String)
*   `fax` - Fax number (String)
*   `email` - Email address (String)
*   `latitude` - Geographic latitude (Double)
*   `longitude` - Geographic longitude (Double)
*   `inventoryId` - Associated inventory list ID (String)
*   `storeHours` - Store hours information (String)
*   `storeEvents` - Store events information (String)

### Authentication

This API uses OAuth 2.0 client credentials flow via Account Manager with the following scope:

*   `sfcc.stores` - Read access to store resources

### Related APIs

*   **Shopper Stores API**: Shopper-facing store search with geolocation support
*   **Inventory APIs**: Manage inventory associated with stores

**Version:** 1.2.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/store/stores/v1`
    *   `shortCode (default shortCode)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 Authorization via Account Manager
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.stores: Read access to store resources
    *   Scope sfcc.stores.rw: Read and write access to store resources

## Operations

### GET Get Stores

`GET /organizations/{organizationId}/stores`

Operation ID: `getStores`. Security: AmOAuth2 (sfcc.stores, sfcc.stores.rw).

Retrieve a list of all stores in an organization. Pagination is supported for results.

This endpoint returns all stores within the specified organization without any filtering. Use the offset and limit parameters to control pagination.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 50.  
    Default: `50`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Returns a paginated list of stores
    
    Media type: `application/json`. Schema: `StoreResult`.
    
    _Example: StoreResultSuccess_ Successful store list result
    
    Example response for a successful get stores request with pagination
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 5,
      "data": [
        {
          "id": "store-001",
          "name": "Downtown Store",
          "address1": "123 Main St",
          "address2": "Suite 100",
          "city": "San Francisco",
          "stateCode": "CA",
          "postalCode": "94102",
          "countryCode": "US",
          "phone": "+1-555-123-4567",
          "email": "downtown@example.com",
          "latitude": 37.7749,
          "longitude": -122.4194,
          "inventoryId": "inventory-001",
          "storeHours": {
            "default": {
              "markup": "08:00 am - 07:30 pm",
              "source": "08:00 am - 07:30 pm"
            }
          },
          "storeEvents": {
            "default": {
              "markup": "Sale 40% off",
              "source": "Sale 40% off"
            }
          },
          "storeLocatorEnabled": true,
          "posEnabled": true,
          "creationDate": "2023-01-15T10:30:00.000Z",
          "lastModified": "2024-06-20T14:45:00.000Z",
          "c_customAttribute": "Custom Value"
        },
        {
          "id": "store-002",
          "name": "Downtown Plaza",
          "address1": "456 Market St",
          "city": "San Francisco",
          "stateCode": "CA",
          "postalCode": "94103",
          "countryCode": "US",
          "phone": "+1-555-234-5678",
          "email": "plaza@example.com",
          "latitude": 37.7833,
          "longitude": -122.4167,
          "inventoryId": "inventory-002",
          "storeHours": {
            "default": {
              "markup": "08:00 am - 07:30 pm",
              "source": "08:00 am - 07:30 pm"
            }
          },
          "storeLocatorEnabled": true,
          "posEnabled": false,
          "creationDate": "2023-03-20T08:15:00.000Z",
          "lastModified": "2024-07-10T16:20:00.000Z"
        }
      ]
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UnauthorizedExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "title": "Unauthorized",
      "detail": "Your access token is invalid or expired and can’t be used to identify a user."
    }
    ```
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ForbiddenExample_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "title": "Forbidden",
      "detail": "Your access token is valid, but you don’t have the required permissions to access the resource."
    }
    ```
    

### GET Get Store

`GET /organizations/{organizationId}/stores/{id}`

Operation ID: `getStore`. Security: AmOAuth2 (sfcc.stores, sfcc.stores.rw).

Retrieve information for a specific store by ID.

This endpoint returns detailed information about a single store within the specified organization. Use the select parameter to retrieve only specific fields.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `id` (path, StoreId, required) The ID of the store to retrieve.
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    

#### Responses

*   **200** Returns the store document
    
    Media type: `application/json`. Schema: `Store`.
    
    _Example: StoreSuccess_ Successful single store retrieval
    
    Example response for a successful get store by ID request
    
    ```
    {
      "id": "store-001",
      "name": "Downtown Store",
      "address1": "123 Main St",
      "address2": "Suite 100",
      "city": "San Francisco",
      "stateCode": "CA",
      "postalCode": "94102",
      "countryCode": "US",
      "phone": "+1-555-123-4567",
      "fax": "+1-555-123-4568",
      "email": "downtown@example.com",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "inventoryId": "inventory-001",
      "storeHours": {
        "default": {
          "markup": "08:00 am - 07:30 pm",
          "source": "08:00 am - 07:30 pm"
        }
      },
      "storeEvents": {
        "default": {
          "markup": "Sale 40% off",
          "source": "Sale 40% off"
        }
      },
      "image": {
        "path": "https://example.com/images/store-001.jpg"
      },
      "storeLocatorEnabled": true,
      "posEnabled": true,
      "creationDate": "2023-01-15T10:30:00.000Z",
      "lastModified": "2024-06-20T14:45:00.000Z",
      "c_customAttribute": "Custom Value",
      "c_region": "West Coast"
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/stores 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/stores 403 response._
    
*   **404** Store Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: StoreNotFound_ Store Not Found
    
    Example error response when the requested store ID does not exist
    
    ```
    {
      "title": "Store Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/store-not-found",
      "detail": "No store with ID 'store-999' could be found."
    }
    ```
    

### PUT Create or Replace Store

`PUT /organizations/{organizationId}/stores/{id}`

Operation ID: `createOrReplaceStore`. Security: AmOAuth2 (sfcc.stores.rw).

Create a new store or replace an existing store.

If a store with the specified ID does not exist, a new store is created (returns 201). If a store with the specified ID already exists, it is replaced with the provided data (returns 200).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `id` (path, StoreId, required) The ID of the store to create or replace.

#### Request body (required)

The store data to create or replace.

Media type: `application/json`. Schema: `StoreRequest`.

_Example: CreateStore_ Create a new store

Example request body to create a new store via PUT

```
{
  "id": "new-store-001",
  "name": "New Downtown Store",
  "address1": "789 Market St",
  "city": "San Francisco",
  "stateCode": "CA",
  "postalCode": "94103",
  "countryCode": "US",
  "phone": "+1-555-789-0123",
  "email": "newstore@example.com",
  "latitude": 37.785,
  "longitude": -122.41,
  "storeLocatorEnabled": true,
  "posEnabled": false
}
```

#### Responses

*   **200** Returns the replaced store document.
    
    Media type: `application/json`. Schema: `Store`.
    
    _Example: ReplaceStoreSuccess_ Successful store replacement
    
    Example response for a successful PUT store replacement (200)
    
    ```
    {
      "id": "store-001",
      "name": "Replaced Downtown Store",
      "address1": "789 Market St",
      "city": "San Francisco",
      "stateCode": "CA",
      "postalCode": "94103",
      "countryCode": "US",
      "phone": "+1-555-789-0123",
      "email": "replaced@example.com",
      "latitude": 37.785,
      "longitude": -122.41,
      "storeLocatorEnabled": true,
      "posEnabled": true,
      "creationDate": "2023-01-15T10:30:00.000Z",
      "lastModified": "2026-04-01T12:00:00.000Z"
    }
    ```
    
*   **201** Returns the newly created store document.
    
    Media type: `application/json`. Schema: `Store`.
    
    _Example: CreateStoreSuccess_ Successful store creation
    
    Example response for a successful PUT store creation (201)
    
    ```
    {
      "id": "new-store-001",
      "name": "New Downtown Store",
      "address1": "789 Market St",
      "city": "San Francisco",
      "stateCode": "CA",
      "postalCode": "94103",
      "countryCode": "US",
      "phone": "+1-555-789-0123",
      "email": "newstore@example.com",
      "latitude": 37.785,
      "longitude": -122.41,
      "storeLocatorEnabled": true,
      "posEnabled": false,
      "creationDate": "2026-04-01T10:00:00.000Z",
      "lastModified": "2026-04-01T10:00:00.000Z"
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: IdConflict_ ID Conflict
    
    Example error response when the store ID in the path does not match the ID in the request body
    
    ```
    {
      "title": "ID Conflict",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the URL 'store-001' does not match the ID in the body 'store-002'."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/stores 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/stores 403 response._
    

### DELETE Delete Store

`DELETE /organizations/{organizationId}/stores/{id}`

Operation ID: `deleteStore`. Security: AmOAuth2 (sfcc.stores.rw).

Delete a store by ID.

Permanently removes the store with the specified ID from the organization.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `id` (path, StoreId, required) The ID of the store to delete.

#### Responses

*   **204** Store successfully deleted. No content returned.
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/stores 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/stores 403 response._
    
*   **404** Store Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: StoreNotFound_ Store Not Found
    
    Example error response when the requested store ID does not exist
    
    ```
    {
      "title": "Store Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/store-not-found",
      "detail": "No store with ID 'store-999' could be found."
    }
    ```
    

### PATCH Update Store

`PATCH /organizations/{organizationId}/stores/{id}`

Operation ID: `updateStore`. Security: AmOAuth2 (sfcc.stores.rw).

Update an existing store.

Updates the store with the specified ID using the properties provided in the request body. Only the properties included in the request body are updated; all other properties remain unchanged.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `id` (path, StoreId, required) The ID of the store to update.

#### Request body (required)

The store data to update.

Media type: `application/json`. Schema: `StoreRequest`.

_Example: UpdateStore_ Update an existing store

Example request body to update an existing store via PATCH

```
{
  "id": "store-001",
  "name": "Updated Downtown Store",
  "phone": "+1-555-123-9999",
  "email": "updated@example.com",
  "address2": "Suite 200"
}
```

#### Responses

*   **200** Returns the updated store document.
    
    Media type: `application/json`. Schema: `Store`.
    
    _Example: UpdateStoreSuccess_ Successful store update
    
    Example response for a successful PATCH store update
    
    ```
    {
      "id": "store-001",
      "name": "Updated Downtown Store",
      "address1": "123 Main St",
      "address2": "Suite 200",
      "city": "San Francisco",
      "stateCode": "CA",
      "postalCode": "94102",
      "countryCode": "US",
      "phone": "+1-555-123-9999",
      "fax": "+1-555-123-4568",
      "email": "updated@example.com",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "inventoryId": "inventory-001",
      "storeLocatorEnabled": true,
      "posEnabled": true,
      "creationDate": "2023-01-15T10:30:00.000Z",
      "lastModified": "2026-04-01T11:00:00.000Z"
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IdConflict: same as PUT /organizations/{organizationId}/stores/{id} 400 response._ ID Conflict
    
    Example error response when the store ID in the path does not match the ID in the request body
    
    _Example: IdConflict_ ID Conflict
    
    Example error response when the store ID in the path does not match the ID in the request body
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/stores 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/stores 403 response._
    
*   **404** Store Not Found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: StoreNotFound_ Store Not Found
    
    Example error response when the requested store ID does not exist
    
    ```
    {
      "title": "Store Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/store-not-found",
      "detail": "No store with ID 'store-999' could be found."
    }
    ```
    

### POST Search Stores

`POST /organizations/{organizationId}/store-search`

Operation ID: `searchStores`. Security: AmOAuth2 (sfcc.stores, sfcc.stores.rw).

Searches for stores.

The query attribute specifies a complex query that can be used to narrow down the search. This is the list of searchable attributes:

*   address1 - String
*   address2 - String
*   city - String
*   countryCode - String
*   email - String
*   fax - String
*   id - String
*   inventoryId - String
*   latitude - double
*   longitude - double
*   name - String
*   phone - String
*   postalCode - String
*   stateCode - String
*   storeHours - String
*   storeEvents - String

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    

#### Request body (required)

The search request document

Media type: `application/json`. Schema: `StoreSearchRequest`.

_Example: StoreSearchByName_ Search stores by name

Example request to search for stores by name using a text query

```
{
  "query": {
    "textQuery": {
      "fields": [
        "name"
      ],
      "searchPhrase": "downtown"
    }
  },
  "limit": 10,
  "offset": 0,
  "sorts": [
    {
      "field": "name",
      "sortOrder": "asc"
    }
  ]
}
```

_Example: StoreSearchByCity_ Search stores by city and state

Example request to search for stores in a specific city and state using term queries

```
{
  "query": {
    "boolQuery": {
      "must": [
        {
          "termQuery": {
            "fields": [
              "city"
            ],
            "operator": "is",
            "values": [
              "San Francisco"
            ]
          }
        },
        {
          "termQuery": {
            "fields": [
              "stateCode"
            ],
            "operator": "is",
            "values": [
              "CA"
            ]
          }
        }
      ]
    }
  },
  "limit": 25,
  "offset": 0,
  "sorts": [
    {
      "field": "name",
      "sortOrder": "asc"
    }
  ]
}
```

#### Responses

*   **200** Returns store search results
    
    Media type: `application/json`. Schema: `StoreSearchResult`.
    
    _Example: StoreSearchResultSuccess_ Successful store search result
    
    Example response for a successful store search with multiple results
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 10,
      "query": {
        "textQuery": {
          "fields": [
            "name"
          ],
          "searchPhrase": "downtown"
        }
      },
      "sorts": [
        {
          "field": "name",
          "sortOrder": "asc"
        }
      ],
      "hits": [
        {
          "id": "store-001",
          "name": "Downtown Store",
          "address1": "123 Main St",
          "address2": "Suite 100",
          "city": "San Francisco",
          "stateCode": "CA",
          "postalCode": "94102",
          "countryCode": "US",
          "phone": "+1-555-123-4567",
          "email": "downtown@example.com",
          "latitude": 37.7749,
          "longitude": -122.4194,
          "inventoryId": "inventory-001",
          "storeHours": {
            "default": {
              "markup": "08:00 am - 07:30 pm",
              "source": "08:00 am - 07:30 pm"
            }
          },
          "storeEvents": {
            "default": {
              "markup": "Sale 40% off",
              "source": "Sale 40% off"
            }
          },
          "storeLocatorEnabled": true,
          "posEnabled": true,
          "creationDate": "2023-01-15T10:30:00.000Z",
          "lastModified": "2024-06-20T14:45:00.000Z",
          "c_customAttribute": "Custom Value"
        },
        {
          "id": "store-002",
          "name": "Downtown Plaza",
          "address1": "456 Market St",
          "city": "San Francisco",
          "stateCode": "CA",
          "postalCode": "94103",
          "countryCode": "US",
          "phone": "+1-555-234-5678",
          "email": "plaza@example.com",
          "latitude": 37.7833,
          "longitude": -122.4167,
          "inventoryId": "inventory-002",
          "storeHours": {
            "default": {
              "markup": "Mon-Sun: 10am-8pm",
              "source": "Mon-Sun: 10am-8pm"
            }
          },
          "storeLocatorEnabled": true,
          "posEnabled": false,
          "creationDate": "2023-03-20T08:15:00.000Z",
          "lastModified": "2024-07-10T16:20:00.000Z"
        }
      ]
    }
    ```
    
*   **400** Bad Request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: MalformedSearchParameter_ Malformed search query
    
    Example error response when the search query is malformed
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "The search query is malformed. Please check the query syntax."
    }
    ```
    
    _Example: InvalidQueryField_ Unqueryable Field
    
    Example error response when an invalid field is used in the query
    
    ```
    {
      "title": "Unqueryable Field",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unqueryable-field",
      "detail": "Invalid field 'invalidField' in query. Please use a valid searchable field."
    }
    ```
    
    _Example: FieldNotSortable_ Field Not Sortable
    
    Example error response when an invalid field is used in the query
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'invalidField' can't be used to sort the results."
    }
    ```
    
*   **401** Your access token is invalid or expired and can’t be used to identify a user.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example UnauthorizedExample: same as GET /organizations/{organizationId}/stores 401 response._
    
*   **403** Forbidden. Your access token is valid, but you don’t have the required permissions to access the resource.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example ForbiddenExample: same as GET /organizations/{organizationId}/stores 403 response._
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### StoreResult

Document representing a paginated list of stores.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of Store_, required) The array of store instances.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### StoreId

The ID of the store.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `store-001`.

### Store

*   `id` (_object_, required) ID
    
    Includes all fields of `StoreId`.
    
*   `name` (_string_) The name of the store.  
    Maximum length: 256. Example: `Downtown Store`.
*   `address1` (_string_)
    
    address1
    
    The first line of the store address.
    
      
    Maximum length: 256. Example: `123 Main St`.
*   `address2` (_string_)
    
    address2
    
    The second line of the store address.
    
      
    Maximum length: 256. Example: `Suite 100`.
*   `city` (_string_) The city of the store.  
    Maximum length: 256. Example: `San Francisco`.
*   `countryCode` (_CountryCode_)
*   `phone` (_string_) The phone number of the store.  
    Maximum length: 256. Example: `+1-555-123-4567`.
*   `postalCode` (_string_) The postal code of the store.  
    Maximum length: 10. Example: `94102`.
*   `stateCode` (_string_) The state code of the store.  
    Maximum length: 256. Example: `CA`.
*   `fax` (_string_) The fax number of the store.  
    Maximum length: 256. Example: `+1-555-123-4568`.
*   `longitude` (_number (double)_) The longitude of the store.  
    Minimum: -180. Maximum: 180. Example: `-122.4194`.
*   `latitude` (_number (double)_) The latitude of the store.  
    Minimum: -90. Maximum: 90. Example: `37.7749`.
*   `inventoryId` (_object_) inventoryListID
    
    Includes all fields of `InventoryId`.
    
*   `storeHours` (_object_) The localized store opening hours.
    
    Additional properties: `MarkupText`.
    
*   `storeEvents` (_object_) The localized store events.
    
    Additional properties: `MarkupText`.
    
*   `email` (_object_)
    
    Includes all fields of `Email`.
    
*   `image` (_object_) The image URL associated with the store.
    
    Includes all fields of `MediaFile`.
    
*   `storeLocatorEnabled` (_boolean_) Specifies whether the store appears in store locator searches (true) or not (false).  
    Example: `true`.
*   `posEnabled` (_boolean_) Specifies whether the store uses Store product for Point-of-Sale (true) or not (false).  
    Example: `true`.
*   `creationDate` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'.  
    Example: `2023-01-15T10:30:00.000Z`.
*   `lastModified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'.  
    Example: `2024-06-20T14:45:00.000Z`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### StoreRequest

Document representing a store request body for create or update operations.

*   `id` (_object_, required) ID
    
    Includes all fields of `StoreId`.
    
*   `name` (_string_) The name of the store.  
    Maximum length: 256. Example: `Downtown Store`.
*   `address1` (_string_)
    
    address1
    
    The first line of the store address.
    
      
    Maximum length: 256. Example: `123 Main St`.
*   `address2` (_string_)
    
    address2
    
    The second line of the store address.
    
      
    Maximum length: 256. Example: `Suite 100`.
*   `city` (_string_) The city of the store.  
    Maximum length: 256. Example: `San Francisco`.
*   `countryCode` (_CountryCode_)
*   `phone` (_string_) The phone number of the store.  
    Maximum length: 256. Example: `+1-555-123-4567`.
*   `postalCode` (_string_) The postal code of the store.  
    Maximum length: 10. Example: `94102`.
*   `stateCode` (_string_) The state code of the store.  
    Maximum length: 256. Example: `CA`.
*   `fax` (_string_) The fax number of the store.  
    Maximum length: 256. Example: `+1-555-123-4568`.
*   `longitude` (_number (double)_) The longitude of the store.  
    Minimum: -180. Maximum: 180. Example: `-122.4194`.
*   `latitude` (_number (double)_) The latitude of the store.  
    Minimum: -90. Maximum: 90. Example: `37.7749`.
*   `inventoryId` (_object_) inventoryListID
    
    Includes all fields of `InventoryId`.
    
*   `storeHours` (_object_) The localized store opening hours.
    
    Additional properties: `MarkupText`.
    
*   `storeEvents` (_object_) The localized store events.
    
    Additional properties: `MarkupText`.
    
*   `email` (_object_)
    
    Includes all fields of `Email`.
    
*   `image` (_object_) The image URL associated with the store.
    
    Includes all fields of `MediaFile`.
    
*   `storeLocatorEnabled` (_boolean_) Specifies whether the store appears in store locator searches (true) or not (false).  
    Example: `true`.
*   `posEnabled` (_boolean_) Specifies whether the store uses Store product for Point-of-Sale (true) or not (false).  
    Example: `true`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### StoreSearchRequest

Document representing a search request for retrieving stores within the Admin API. The query is a potentially complex set of expressions.

Includes all fields of `SearchRequest`.

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "name",
        "city"
      ],
      "searchPhrase": "downtown"
    }
  },
  "limit": 10,
  "offset": 0,
  "sorts": [
    {
      "field": "name",
      "sortOrder": "asc"
    }
  ]
}
```

### StoreSearchResult

Document representing a store search result. This includes the query, sorts, hits (array of Store objects), and pagination information.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of Store_, required) The sorted array of search hits (Store objects). Can be empty.

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### CountryCode

A two letter uppercase country code conforming to the [ISO 3166-1](https://www.iso.org/iso-3166-country-codes.html) alpha-2 standard.

Type: `string`.

Pattern: ^\[A-Z\]\[A-Z\]$. Example: `US`.

### InventoryId

The inventory list ID associated with the store.

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `inventory-001`.

### MarkupText

Document representing markup text.

*   `markup` (_string_, required) The rendered HTML.
*   `source` (_string_, required) The raw markup text.

### Email

Email address to contact the store.

Type: `string (email)`.

Maximum length: 256. Example: `store@example.com`.

### MediaFile

Document representing media file.

*   `absUrl` (_string_) The absolute URL with request protocol.  
    Example: `https://www.example-image.com/images/apple-ipod-classic.jpg`.
*   `alt` (_object_) The alternative image text.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "iPod"
    }
    ```
    
*   `disBaseUrl` (_string_) The Dynamic Image Service (DIS) base URL for product images only.  
    Example: `https://www.dis-base-url/images/apple-ipod-clasic.jpg`.
*   `path` (_string_, required) The raw media file path.  
    Example: `/images/apple-ipod-classic.jpg`.
*   `title` (_object_) The image title.
    
    Additional properties: `string`.
    
    _Example_
    
    ```
    {
      "en_US": "iPod"
    }
    ```
    

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "value": {
    "must": [
      {
        "textQuery": {
          "fields": [
            "couponId"
          ],
          "searchPhrase": "DEAL"
        }
      },
      {
        "textQuery": {
          "fields": [
            "description"
          ],
          "searchPhrase": "Big bargain deal"
        }
      }
    ],
    "mustNot": [
      {
        "termQuery": {
          "fields": [
            "enabled"
          ],
          "operator": "is",
          "values": [
            false
          ]
        }
      }
    ]
  }
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "value": {
    "operator": "and",
    "filters": [
      {
        "termFilter": {
          "field": "id",
          "operator": "is",
          "values": [
            "myId"
          ]
        }
      },
      {
        "termFilter": {
          "field": "couponId",
          "operator": "is",
          "values": [
            "couponOne"
          ]
        }
      }
    ]
  }
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```

<!-- document id=5561df0c6c3bb6338abc8a2c97122bfcb3ac8a7ab237e5dd97c4888e746e43db url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-storybook-structure.md -->

# Storybook File and Folder Structure

Storybook files are under the `.storybook/` folder. Components are under the `src/components/` folder.

```
src/
  components/
    __mocks__/
      checkout-data.ts
      ...
    buttons/
      button.tsx
      button.test.tsx
      /stories
        button.stories.tsx
        button-snapshot.tsx
        __snapshots__/
          button-snapshot.tsx.snap
.storybook/
  main.ts
  preview.tsx
  vite.config.ts
  vitest.setup.ts
  storybook-providers.tsx

```

## See Also

- [GitHub: Storybook Readme](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/README-STORYBOOK.md)
- [Build and Test Components with Storybook](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storybook.md)

<!-- document id=fa212e157c445663b22ac1204cf2e85c9880df4cfb1eacd09cf7414fbeab0354 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-d2c-comm-streamlined-place-order.md -->

# Streamlined Place Order

The streamlined place order feature improves checkout performance and scale, and prevents orphaned payments. This enhanced design consolidates order placement API calls, processes payments asynchronously, and provides greater flexibility for modular customization. Streamlined place order is enabled by default in B2B Lightning Web Runtime (LWR) stores created in Summer ’25 and later releases.

## Streamlined Place Order Design

Streamlined place order triggers when a customer clicks the Place Order button from checkout. Then, the system prepares the order and payment before capturing a payment and creating the order asynchronously. If an error occurs during asynchronous order or payment processing, the Commerce admin receives a process exception to resolve.

![Streamlined place order flow chart showing sequence of prepare order, prepare payments, submit order, and asynchronous processing.](https://developer.salesforce.com/media/d2c-commerce/streamlined_place_order_flow.png)

1. **Prepare Order**—First, calls to the Prepare Order API reserve the order’s required inventory and, if applicable, redeem any coupons. To confirm that the cart can be converted into an order, this step includes cart validations. For example, validations check that a cart delivery group exists and that the checkout session hasn’t expired.

**note:** The default checkout TTL for B2B stores is 48 hours. If a checkout expires, the checkout status is set to Canceled and the cart status is reverted to Active.

2. **Prepare Payment**—Next, calls to the Payment APIs get the order ready for payment collection. Based on the input information, the system creates the necessary [payment group](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentgroup.htm) object and calls the [Commerce Payment Gateway](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-b2c-comm-payment-gateway-processing.htm). If streamlined place order is successful up to this point, the customer sees a pending transaction on their account. However, the payment isn’t captured yet.

**note:** The system doesn’t create a [payment gateway log](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentgatewaylog.htm) by default.

3. **Asynchronous Processing**—After a payment is prepared, asynchronous payment processing begins. Calls to the Commerce Payment Gateway from the previous step create and confirm the [payment intent](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentintent.htm) object. Asynchronous processing also performs the payment capture, transferring funds from the customer to your store, and creates the order and order summary.

If an issue arises during this step, the store generates a process exception. For more information, see [Resolving Asynchronous Order Failures in B2B Stores](https://help.salesforce.com/s/articleView?id=commerce.comm_async_processing_overview.htm).
**note:** The pending closed checkout TTL setting determines how long a store waits for payment confirmation from the payment gateway. If the payment confirmation doesn’t arrive in time, a process exception occurs. If payment confirmation arrives after the pending closed checkout TTL has expired, the order and order summary are still created, unless the Commerce admin changed the WebCart status to Closed while resolving the process exception. You can set the pending closed checkout TTL in minutes by using the `Checkout.pendingClosedCheckoutTTL` configuration.

4. **Submit Order**—The system once again validates the inventory and coupons, confirms that the payment amount covers the full cart amount, and attaches the payment group to the cart. If the cart isn’t paid in full, the system returns a checkout service exception. If the checks pass, the payment group is attached to the cart.

   The system updates the cart status to Pending Closed and the customer is sent to the order confirmation page. Because payment processing is asynchronous, the payment method isn’t displayed on the confirmation page.

## API Overview

Streamlined place order introduces new and updated APIs for order orchestration.
New APIs:

- To prepare an order, make a POST request to the Commerce Webstore Checkout Order Actions API with the action set to prepare.
- To submit an order, make a POST request to the Commerce Webstore Checkout Order Actions API with the action set to submit.
- To prepare a payment, make a POST request to the Prepare Payment API.
  Updated APIs:
- If you use a custom payment integration and make a PostAuth request to [Commerce Webstore Checkout Payments](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts_payments.htm) while streamlined place order is enabled, no payment gateway calls or credit card storage (CCS) entities are created. The call returns a successful 200 response code without performing any additional actions.

## State Management

This table describes the state of relevant objects at the end of each stage in the streamlined place order flow.

| Object                     | Prepare Order                                                    | Prepare Payment | Process Payment (Asynchronous) | Submit Order  |
| -------------------------- | ---------------------------------------------------------------- | --------------- | ------------------------------ | ------------- |
| **WebCart**                | Checkout                                                         | Checkout        | Closed                         | PendingClosed |
| **InventoryReservation**   | Reserved if inventory is available. Not reserved if unavailable. | Reserved        | Reserved                       | Reserved      |
| **Coupon** (if applicable) | Redeemed                                                         | Redeemed        | Redeemed                       | Redeemed      |
| **Order**                  | Not created                                                      | Not created     | Active                         | Not created   |
| **OrderSummary**           | Not Created                                                      | Not created     | Created                        | Not created   |

## Implementation Best Practices

If you develop customizations on top of the simplified order processing flow, keep these recommendations in mind.

### Sequence of API Calls

To reduce the likelihood of reversed payments, make sure that your store follows the intended sequence of API calls: Prepare Order, Prepare Payment, and Submit Order. This order also applies to headless implementations.

### Salesforce Payments

If your store uses Salesforce Payments, the native payment service, note that customizations must be implemented differently when using streamlined place order. For example, in stores created prior to Summer ’25, the legacy order processing flow supported direct calls to the [create payment intent API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-payments-ref). Instead, for streamlined place order, use the Prepare Payment API to create payment intents.

<!-- document id=b5fbdb2ae12f301f7bce281f6bd0e99fc94505b6c50e561f31cdaaabbe38a21a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/style-and-theme-the-widget.md -->

# Style and Theme the Widget

The Agentforce Commerce Client is non-opinionated: it ships with no CSS framework and applies no global resets. Every element carries a `cim-widget-` class prefix, so widget styles never leak into your page and your storefront styles never affect the widget. You style the widget in three escalating layers: theme properties, header configuration, and custom CSS.

## Theme properties

The `theme` object is the primary way to make the widget feel brand-native. A handful of properties cascade across every surface (buttons, messages, typography, borders, and corners), so a few lines of configuration reshape the widget's look with no custom CSS.

```ts
theme: {
  primaryColor: "#3182ce",
  secondaryColor: "#2c5282",
  fontColor: "#1a202c",
  fontFamily: "inherit",
  backgroundColor: "#ffffff",
  borderColor: "#dddddd",
  borderRadius: "0.25rem",
}
```

| Property | Applies to | Default |
| --- | --- | --- |
| `primaryColor` | Buttons, icons, and user message backgrounds | `#3182ce` |
| `secondaryColor` | AI response message backgrounds | `#2c5282` |
| `fontColor` | All text | `#1a202c` |
| `fontFamily` | Typography | `inherit` |
| `backgroundColor` | Widget canvas and container | `#ffffff` |
| `borderColor` | Outer borders (dialog and embedded modes) | `#dddddd` |
| `borderRadius` | Corner rounding | `0.25rem` |

A partial `theme` overrides only the values you set; every unset property falls back to its default.

Because `fontFamily` defaults to `inherit`, the widget automatically adopts whatever typeface your storefront uses. If your site rebrands to a new font, the widget follows with no configuration change. Stick to universally supported font values so the widget renders consistently even when a custom font hasn't loaded.

## Header configuration

The `headerConfig` object independently styles the widget header (logo, title text, and header chrome).

| Field | Type | Notes |
| --- | --- | --- |
| `logoUrl` | `string` | Logo image in the header. |
| `headerText` | `string` | Header title text. |
| `headerBackgroundColor` | `string` | Header bar background. Defaults to `transparent`. |
| `headerTextColor` | `string` | Header title color. Defaults to `inherit`. |
| `headerTextFontSize` | `string` | Header title size. Defaults to `1.25rem`. |
| `headerTextFontWeight` | `number` | Header title weight. Defaults to `bold`. |
| `headerTextFontFamily` | `string` | Header title typeface. Defaults to `inherit`. |
| `headerTextTextAlign` | `"left" \| "center" \| "right"` | Header title alignment. Defaults to `left`. |

## Other presentation options

A few more properties adjust presentation.

- **`suggestionButtonConfig`** adds an opt-in icon to the prompt and in-conversation suggestion buttons. Set `icon` to `"sparkle"`, `"plus"`, or `"paper-plane"`, and `iconPosition` to `"left"` (default) or `"right"`. No icon shows unless you set one.
- **`searchConfig`** customizes the search bar: `placeholder`, `buttonLabel`, `buttonAriaLabel`, `buttonIconUrl`, `buttonType` (`"icon"`, `"text"`, or `"icon-text"`), and `enableCancelSearch`. Set the search bar's placeholder and button label here through `placeholder` and `buttonLabel`.
- **`promptsConfig`** controls the prompts extension: `promptsDisplay` (`"input"`, `"buttons"`, or `"both"`, default `"both"`), `staticQuestions` (fixed questions rendered as buttons; trimmed and deduplicated, empties dropped), and `disableAskElseButton` (default `false`).

## CSS custom properties

The widget emits theme and header values as CSS custom properties, so you can also read or override them in your own stylesheet:

```css
--cim-widget-primary-color
--cim-widget-secondary-color
--cim-widget-font-color
--cim-widget-font-family
--cim-widget-background-color
--cim-widget-border-color
--cim-widget-border-radius
```

Header properties follow the same convention with a `--cim-widget-header-` prefix (for example, `--cim-widget-header-background-color`).

## Custom CSS for pixel-perfect control

When theme properties aren't enough, target the widget's classes directly. Every `cim-widget-*` class is a stable selector, for example:

```css
.cim-widget-container {
}
.cim-widget-message-container {
}
.cim-widget-suggestion-button {
}
.cim-widget-modal-title {
}
```

For an extra specificity hook, set the `globalClassName` property. The widget adds that class to all of its elements, giving you a scoped selector to raise specificity without editing the widget's source.

**Per-platform notes.** The `cim-widget-` classes are the same regardless of storefront framework, so custom CSS targets them the same way everywhere. Deliver that CSS through your storefront's normal styling pipeline:

- **SFRA:** add the rules to a cartridge stylesheet.
- **Composable Storefront (PWA Kit):** add the rules alongside your Chakra styles, scoped to the `cim-widget-` classes.
- **Storefront Next:** add the rules to your app's stylesheet; the `cim-widget-` prefix keeps them isolated from your utility classes.

Because the widget attaches no shadow root, your storefront CSS reaches these elements normally.

## Related resources

- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Choose a Customization Approach](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/customization-decision-guide.md)
- [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md)

<!-- document id=e4a353ed9a3dd84ecffe001813b6a3e86f609d69a2526f3c5f55acacea3621f5 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-pwa-styling.md -->

# Styling Differences with PWA Kit

PWA Kit styling is largely Chakra CSS-in-JS with prop-based responsive and variant systems. Storefront Next styling centers on Tailwind utility classes, CSS variables, and class-variant composition. The migration is primarily a syntax and architecture shift from style props/theme objects to utility classes and typed variant helpers.

## Key Differences

| Aspect            | PWA Kit (Chakra)                         | Storefront Next (Tailwind/shadcn)               |
| ----------------- | ---------------------------------------- | ----------------------------------------------- |
| Approach          | CSS-in-JS with JavaScript objects        | Utility-first CSS with class strings            |
| Theme Location    | `app/theme/` directory                   | `src/app.css` CSS variables                     |
| Component Styling | `useMultiStyleConfig` hook               | `cva()` + `cn()` utilities                      |
| Design Tokens     | JavaScript objects (colors.js, space.js) | CSS custom properties (--primary, --background) |
| Variants          | Props-based (`colorScheme`, `variant`)   | Class-based via CVA                             |
| Responsive        | Array syntax `[base, sm, md, lg]`        | Prefix syntax `sm:` `md:` `lg:`                 |
| Runtime           | Generates styles at run time             | Pre-compiled utilities                          |
| Dark Mode         | Theme color mode provider                | CSS variables + `dark:` prefix                  |
| Bundle            | Includes Chakra UI runtime               | Zero runtime (utility classes)                  |
| Type Safety       | PropTypes                                | Full TypeScript with `VariantProps`             |

## Styling Declaration Comparison

### Responsive Container

PWA Kit (Chakra):

```jsx
<Box px={[4, 4, 6, 6, 8]} maxWidth="container.xxxl" marginX="auto">
  {children}
</Box>
```

Storefront Next (Tailwind):

```tsx
<div className="px-4 sm:px-6 lg:px-8 max-w-7xl mx-auto">{children}</div>
```

### Button Variants

PWA Kit (Chakra):

```jsx
<Button variant="solid" colorScheme="blue" size="md">
    Primary
</Button>
<Button variant="outline" colorScheme="black">
    Secondary
</Button>
```

Storefront Next (Tailwind):

```tsx
<Button variant="default" size="default">
    Primary
</Button>
<Button variant="outline">
    Secondary
</Button>
```

### Conditional Visibility

PWA Kit (Chakra):

```jsx
<Box display={["none", "none", "none", "block"]}>Desktop only content</Box>
```

Storefront Next (Tailwind):

```tsx
<div className="hidden lg:block">Desktop only content</div>
```

## Key Similarities

- Component-based architecture: Both use composable UI components.
- Design token systems: Both define colors, spacing, and other tokens centrally.
- Variant support: Both support multiple variants and sizes for components.
- Responsive design: Both provide breakpoint-based responsive utilities.
- Dark mode: Both support light and dark theme switching.
- Accessibility: Both use accessible UI primitives (Chakra built-in, Radix UI in shadcn).

## Storefront Conversion Considerations

Keep these considerations in mind when converting a storefront from PWA Kit to Storefront Next.

- Theme Conversion: Convert JavaScript theme tokens to CSS custom properties.
- Responsive Syntax: Convert array-based responsive values `[a, b, c]` to prefix-based `sm:b md:c`.
- Component Props to Classes: Replace Chakra style props with Tailwind utility classes.
- Layer Styles: Convert layer styles to Tailwind `@apply` directives or component classes.
- Multi-part Components: Replace `useMultiStyleConfig` with compound component patterns.
- Variant Logic: Use CVA for variant management instead of Chakra's variant system.
- Pseudo-selectors: Convert `_hover`, `_active`, and so on to Tailwind modifiers `hover:`, `active:`.

<!-- For detailed component mapping between Chakra and Tailwind/shadcn, see the UI Component Mapping guide (to be created).>

<!-- document id=35a9222b09294b074d1739fbbf09068dcc92b77949abe6bfe700a0c9b2f5454d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-sub-pipeline-do-inventory.md -->

# Sub-Pipeline : DoInventory

Review the DoInventory sub-pipeline when scheduling inventory imports.

![DoInventory sub-pipeline diagram showing error count decision node and import processing path retrieval steps](https://developer.salesforce.com/media/b2c-commerce/b2c_inventory_inventory_do_inventory.gif)

1.  Decision Node : `ErrorCount == null`
    - If `true` , continue
    - If `false` , return error
2.  Pipelet Script (bc_api). Call `[GetImpExProcessingPath.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-imp-ex-processing-path-ds.md)`. This script retrieves the import processing path.
3.  Continue after calling node.

| Variable                      | Type         |                                          |
| ----------------------------- | ------------ | ---------------------------------------- |
| `@input TaskDirectoryName`    | `String`     | Task directory name                      |
| `@input SiteID`               | `String`     | Site ID                                  |
| `@input FileName`             | `String`     | File name                                |
| `@input ImpexRoot`            | `Boolean`    | Root directory is IMPEX (default: false) |
| `@input FileExtension`        | `String`     | Processing File Extension (.processing)  |
| `@input sampleLogger`         | `Object`     | Sample Logger                            |
| `@output ImpExProcessing`     | `dw.io.File` | Import/Export processing file            |
| `@output ImpExProcessingPath` | `String`     | Import/Export processing file path       |
| `@output SampleLogger`        | `Object`     | Debug output for Sample logger           |
| `@output SampleError`         | `Object`     | Error output for Sample logger           |

<!-- document id=2990bb954e1f094c1225af9a08715541626dd0de9eeeb5245ef745ce0dca6537 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-sub-pipeline-get-exec-settings.md -->

# Sub-Pipeline : GetExecSettings

Review the GetExecSettings sub-pipeline when scheduling inventory imports.

![GetExecSettings sub-pipeline diagram showing script execution timeout preference retrieval steps](https://developer.salesforce.com/media/b2c-commerce/b2c_inventory_inventory_get_exec_settings.gif)

1.  Pipelet: Assign (bc_api) GetScriptExecTimeoutPreference
    - `ScriptExecTime = dw.system.Site.getCurrent().getCustomPreferenceValue​('ImpexScriptExecutionTimeout')`
2.  Pipelet: Assign (bc_api) SetScriptExecTimeout
    - `ScriptExecTimeout = !empty(ScriptExecTimeout) ? ScriptExecTimeout : '10'`
3.  Continue after calling node.

<!-- document id=55458ea6ddcc48952181c02a0b2e12ad34b356c521e449e99b762c5b7818480b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-sub-pipeline-get-unzip-file.md -->

# Sub-Pipeline : GetUnzipFile

Review the GetUnzipFile sub-pipeline when scheduling inventory imports.

![GetUnzipFile sub-pipeline diagram showing steps to unzip and rename inventory import files](https://developer.salesforce.com/media/b2c-commerce/b2c_inventory_inventory_get_unzip_file.gif)

1.  Script (bc_api). Call Get `Unzip.ds` . This script unzips a file.

| Variable                 | Type         | Comment                                                        |
| ------------------------ | ------------ | -------------------------------------------------------------- |
| `@input ZIPFileName`     | `String`     | The file name of the .zip file                                 |
| `@input SourceDirectory` | `dw.io.File` | The processing directory where the file is located             |
| `@input importLogger`    | `Object`     | import logger                                                  |
| `@output UnzipDirectory` | `dw.io.File` | The unzip directory where the extracted import file is located |
| `@output ZIPFile`        | `dw.io.File` | The .zip file                                                  |
| `@output importLogger`   | `Object`     | import logger                                                  |
| `@output importError`    | `Object`     | import error                                                   |

1.  Script (bc_api). Calls `[GetFilesFromDirectory.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-files-from-directory-ds.md)` . This script retrieves a file list from an FTP/HTTP(S) server.

    | Variable               | Type                   | Comment                                              |
    | ---------------------- | ---------------------- | ---------------------------------------------------- |
    | `@input Directory`     | `dw.io.File`           | the directory to browse                              |
    | `@input SortDirection` | `String`               | 'ASCENDING' or 'DESCENDING'                          |
    | `@input NamePattern`   | `String`               | The pattern for the filenames (use ".\*" to get all) |
    | `@input importLogger`  | `Object import logger` | input for import logger                              |
    | `@output FileList`     | `dw.util Collection`   | The files matching the pattern                       |
    | `@output importLogger` | `Object import logger` | debug output for import logger                       |
    | `@output importError`  | `Object import error`  | error output for import logger                       |

2.  Loop : UpzipFiles[]
3.  Pipelet : Script (bc_api). Calls `[RenameFile.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-rename-file-ds.md)` .
4.  Pipelet : Eval (bc_api). Delete the original Import .zip file with `ZipFile.remove()` .
5.  Pipelet: Assign (bc_api). Set the following value.

    `ImportFile = UnzipFile.name`

6.  Loop to UnzipFiles[] until all files are processed.
7.  Pipelet : Eval (bc_api). Delete the original Import .zip file direcctory with `UnzipDirectory.remove()` .
8.  Continue after calling node.

<!-- document id=1f5c7a8ef517b15c9cffa87ebfa99805fe8f51a7729a2c1074e069e2e7516172 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-sub-pipeline-load-files-from-ftp.md -->

# Sub-Pipeline : LoadFilesFromFTP

Review the LoadFilesFromFTP sub-pipeline when scheduling inventory imports.

![LoadFilesFromFTP sub-pipeline diagram showing steps to retrieve inventory files from an FTP server](https://developer.salesforce.com/media/b2c-commerce/b2c_inventory_inventory_load_files_from_ftp.gif)

Pipelet: Assign (bc_api). Call `[GetFilesFromFTPServer.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-files-from-ftp-server-ds.md)` .

| Variable               | Type                   | Comment                        |
| ---------------------- | ---------------------- | ------------------------------ |
| `@input Hostname`      | `String`               | The host name                  |
| `@input Username`      | `String`               | The user name                  |
| `@input Password`      | `String`               | The password                   |
| `@input Directory`     | `String`               | The directory                  |
| `@input importLogger`  | `Object import logger` | input for import logger        |
| `@output importLogger` | `Object import logger` | debug output for import logger |
| `@output importError`  | `Object import error`  | error output for import logger |

Continue after calling node.

<!-- document id=250312c0a7afae2e617278a88d285dc43905240cffccd3a3f50774d030898a54 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-sub-pipeline-load-files-from-http.md -->

# Sub-Pipeline : LoadFilesFromHTTP

Review the LoadFilesFromHTTP sub-pipeline when scheduling inventory imports.

![LoadFilesFromHTTP sub-pipeline diagram showing steps to retrieve inventory files from an HTTP server](https://developer.salesforce.com/media/b2c-commerce/b2c_inventory_inventoryloadfilesfromhttp.gif)

Pipelet : Script (bc_api). Calls `[GetFilesFromHttpServer.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-files-from-http-server-ds.md)`

| Variable                | Type                   | Comment                                              |
| ----------------------- | ---------------------- | ---------------------------------------------------- |
| `@input ConnectionUrl`  | `String`               | of the server URL including protocol                 |
| `@input Login`          | `String`               | The login for authentication                         |
| `@input Password`       | `String`               | The password for authentication                      |
| `@input SortDirection`  | `String`               | 'ASCENDING' or 'DESCENDING'                          |
| `@input NamePattern`    | `String`               | The pattern for the filenames (use ".\*" to get all) |
| `@input ServerPath`     | `String`               | the directory path at the server                     |
| `@input importLogger`   | `Object import logger` | input for import logger                              |
| `@Output FileList`      | `dw.util Collection`   | The files matching the pattern                       |
| `@Output StatusCode`    | `Number`               | The servers status code                              |
| `@Output StatusMessage` | `String`               | The servers status message                           |
| `@Output importLogger`  | `Object import logger` | debug output for import logger                       |
| `@Output importError`   | `Object import error`  | error output for import logger                       |

Continue after calling node.

<!-- document id=31461093303dfb54901253466b27c5300b5388d4f6e4aef4f6db6f2203af5665 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-zones-cipher-suite-types.md -->

# Supported Cipher Suites

Cipher suites are cipher combinations that are used to negotiate security settings during the Secure Sockets Layer (SSL)/Transport Layer Security (TLS) handshake.

Make sure you verify the correct cipher settings with your security team, and update your eCDN zone cipher suite settings based on your security requirements.

The following SCAPI eCDN endpoints retrieve and restrict the available TLS cipher suites that browsers and devices are allowed to use when accessing a customer’s website/hostname that is served by a specified zone:

- [getCipherSuites](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getCipherSuites)
- [updateCipherSuites](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateCipherSuites)

**note:** TLS 1.2 or later is recommended for all connections.

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
# Required scopes: sfcc.cdn-zones, sfcc.cdn-zones.rw
export SFCC_CLIENT_ID='your-account-manager-client-id'
export SFCC_CLIENT_SECRET='your-account-manager-client-secret'
export SFCC_SHORTCODE='your-short-code'

npx @salesforce/b2c-cli ecdn cipher-suites get \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net

npx @salesforce/b2c-cli ecdn cipher-suites update \
  --tenant-id abcd_stg --zone stg-abcd-example-com.cc-ecdn.net \
  --suite-type Modern
```

## Cipher Suite Types

### Modern Cipher Suites

Modern cipher suites offer the best security and performance by limiting your clients to modern devices and browsers. All modern cipher suites use forward secrecy encryption and support authenticated encryption (AEAD).

The following Modern cipher suites are supported:

- `ECDHE-ECDSA-AES128-GCM-SHA256`
- `ECDHE-ECDSA-CHACHA20-POLY1305`
- `ECDHE-RSA-AES128-GCM-SHA256`
- `ECDHE-RSA-CHACHA20-POLY1305`
- `ECDHE-ECDSA-AES256-GCM-SHA384`
- `ECDHE-RSA-AES256-GCM-SHA384`

### Compatible Cipher Suites

Compatible cipher suites provide broader compatibility with support for additional cipher suites:

- `ECDHE-ECDSA-AES128-GCM-SHA256`
- `ECDHE-ECDSA-CHACHA20-POLY1305`
- `ECDHE-RSA-AES128-GCM-SHA256`
- `ECDHE-RSA-CHACHA20-POLY1305`
- `ECDHE-ECDSA-AES256-GCM-SHA384`
- `ECDHE-RSA-AES256-GCM-SHA384`,
- `ECDHE-ECDSA-AES128-SHA256`
- `ECDHE-RSA-AES128-SHA256`
- `ECDHE-ECDSA-AES256-SHA384`
- `ECDHE-RSA-AES256-SHA384`

### Legacy Cipher Suites

Legacy cipher suites include all cipher suites that our eCDN partners support. By default, these legacy cipher suites are selected, because this provides the broadest compatibility for customer implementations, although it includes some weaker ciphers.

The [getCipherSuites](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=getCipherSuites)
endpoint returns a `cipherSuiteType` of `Legacy` and an empty cipher suite array, which means that the following default legacy cipher suites are used:

- `AEAD-AES128-GCM-SHA256`
- `AEAD-AES256-GCM-SHA384`
- `AEAD-CHACHA20-POLY1305-SHA256`
- `ECDHE-ECDSA-AES128-GCM-SHA256`
- `ECDHE-ECDSA-CHACHA20-POLY1305`
- `ECDHE-RSA-AES128-GCM-SHA256`
- `ECDHE-RSA-CHACHA20-POLY1305`
- `ECDHE-ECDSA-AES256-GCM-SHA384`
- `ECDHE-RSA-AES256-GCM-SHA384`
- `ECDHE-ECDSA-AES128-SHA256`
- `ECDHE-RSA-AES128-SHA256`
- `ECDHE-ECDSA-AES256-SHA384`
- `ECDHE-RSA-AES256-SHA384`
- `ECDHE-ECDSA-AES128-SHA`
- `ECDHE-RSA-AES128-SHA`
- `AES128-GCM-SHA256`
- `AES128-SHA256`
- `AES128-SHA`
- `ECDHE-RSA-AES256-SHA`
- `AES256-GCM-SHA384`
- `AES256-SHA256`
- `AES256-SHA`
- `DES-CBC3-SHA`

### Custom Cipher Suites

To combine or specify a set of cipher suites that you want to allow, use the [updateCipherSuites](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateCipherSuites) endpoint to specify the custom cipher suites that you want to support and set `cipherSuiteType` to `Custom`. When you set `cipherSuiteType` to `Custom`, you must specify a minimum of 5 valid ciphers.

## TLS 1.3 Cipher Suites

If you require TLS 1.3 for HTTPS connections, you must first enable TLS 1.3 connections to be accepted in your zone using the Business Manager crypto settings of the zone or using the [updateSecuritySettings](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateSecuritySettings) endpoint. This automatically enables the following ciphers:

- `AEAD-AES128-GCM-SHA256` (IANA name: `TLS_AES_128_GCM_SHA256`)
- `AEAD-AES256-GCM-SHA384` (IANA name: `TLS_AES_256_GCM_SHA384`)
- `AEAD-CHACHA20-POLY1305-SHA256` (IANA name: `TLS_CHACHA20_POLY1305_SHA256`)

## Cipher Suite Summary

| OpenSSL Cipher Name           | IANA Name                                     | Available in Cipher Suite Type | Minimum TLS Protocol Version |
| ----------------------------- | --------------------------------------------- | ------------------------------ | ---------------------------- |
| ECDHE-ECDSA-AES128-GCM-SHA256 | TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256       | Modern, Compatible, Legacy     | TLS 1.2                      |
| ECDHE-ECDSA-CHACHA20-POLY1305 | TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 | Modern, Compatible, Legacy     | TLS 1.2                      |
| ECDHE-RSA-AES128-GCM-SHA256   | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256         | Modern, Compatible, Legacy     | TLS 1.2                      |
| ECDHE-RSA-CHACHA20-POLY1305   | TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256   | Modern, Compatible, Legacy     | TLS 1.2                      |
| ECDHE-ECDSA-AES128-SHA256     | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256       | Compatible, Legacy             | TLS 1.2                      |
| ECDHE-ECDSA-AES128-SHA        | TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA          | Legacy                         | TLS 1.0                      |
| ECDHE-RSA-AES128-SHA256       | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256         | Compatible, Legacy             | TLS 1.2                      |
| ECDHE-RSA-AES128-SHA          | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA            | Legacy                         | TLS 1.0                      |
| AES128-GCM-SHA256             | TLS_RSA_WITH_AES_128_GCM_SHA256               | Legacy                         | TLS 1.2                      |
| AES128-SHA256                 | TLS_RSA_WITH_AES_128_CBC_SHA256               | Legacy                         | TLS 1.2                      |
| AES128-SHA                    | TLS_RSA_WITH_AES_128_CBC_SHA                  | Legacy                         | TLS 1.0                      |
| ECDHE-ECDSA-AES256-GCM-SHA384 | TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384       | Modern, Compatible, Legacy     | TLS 1.2                      |
| ECDHE-ECDSA-AES256-SHA384     | TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384       | Compatible, Legacy             | TLS 1.2                      |
| ECDHE-RSA-AES256-GCM-SHA384   | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384         | Modern, Compatible, Legacy     | TLS 1.2                      |
| ECDHE-RSA-AES256-SHA384       | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384         | Compatible, Legacy             | TLS 1.2                      |
| ECDHE-RSA-AES256-SHA          | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA            | Legacy                         | TLS 1.0                      |
| AES256-GCM-SHA384             | TLS_RSA_WITH_AES_256_GCM_SHA384               | Legacy                         | TLS 1.2                      |
| AES256-SHA256                 | TLS_RSA_WITH_AES_256_CBC_SHA256               | Legacy                         | TLS 1.2                      |
| AES256-SHA                    | TLS_RSA_WITH_AES_256_CBC_SHA                  | Legacy                         | TLS 1.0                      |
| DES-CBC3-SHA                  | TLS_RSA_WITH_3DES_EDE_CBC_SHA                 | Legacy                         | TLS 1.0                      |
| AEAD-AES128-GCM-SHA256        | TLS_AES_128_GCM_SHA256                        | Custom                         | TLS 1.3                      |
| AEAD-AES256-GCM-SHA384        | TLS_AES_256_GCM_SHA384                        | Custom                         | TLS 1.3                      |
| AEAD-CHACHA20-POLY1305-SHA256 | TLS_CHACHA20_POLY1305_SHA256                  | Custom                         | TLS 1.3                      |

## Frequently Asked Questions (FAQs)

- What cipher suites are needed for Payment Card Industry Data Security Standard (PCI DSS) compliance?
  - The following cipher suites are recommended for PCI DSS compliance. Check with your security team to verify compliance with your site's security requirements.
    - `ECDHE-ECDSA-AES128-GCM-SHA256`
    - `ECDHE-RSA-AES128-GCM-SHA256`
    - `ECDHE-ECDSA-AES256-GCM-SHA384`
    - `ECDHE-RSA-AES256-GCM-SHA384`
    - `ECDHE-ECDSA-CHACHA20-POLY1305`
    - `ECDHE-RSA-CHACHA20-POLY1305`
- How can I disable weak cipher suites listed in the SSL Labs weak ciphers report?
  - To disable weak ciphers listed in a Qualys SSL Labs report:
    1. Use the previous table to get the corresponding cipher suite information.
    2. Identify which cipher suites you want to allow.
    3. Use the [updateCipherSuites](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=updateCipherSuites) endpoint to specify the custom cipher suites that you want to update and set `cipherSuiteType` to `Custom` for the applicable zone.
- What is the order in which cipher suites are used?
  - ECDSA cipher suites are prioritized over RSA, and then cipher suites are condered in the order they were set. This means that, if both ECDSA and RSA are used, Cloudflare presents the ECDSA ciphers first in the order they were set. Then the RSA ciphers are presented in the order they were set.
- Why am I getting the `ERR_SSL_VERSION_OR_CIPHER_MISMATCH` cipher suite mismatch error when visiting my site?
  - Make sure that the certificate is compatible with the chosen cipher suites for your zone. For example, if you upload an RSA certificate, your cipher suite selection cannot specify support for only ECDSA certificates.

<!-- document id=f9ae30cfadc961277dee3105883a604eb51358ccc9e5e24c889ca9cc35761870 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/cdn-supported-csp-directives.md -->

# Supported CSP Directives

| Directive    | Category | Supported special values | Alerting Enabled | Example usage |
| ------------ | -------- | ------------------------ | ---------------- | ------------- |
| `script-src` | Scripts  | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |Yes |`script-src stripe.com *.stripe.com ;` |
|`connect-src` |Connections | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul>` |Yes |`connect-src 'unsafe-inline' https://www.shop.stg.bcxg.sfcc-store-internal.net ;` |
|`default-src` |Default | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | `default-src *.js.stripe.com 'unsafe-eval' 'unsafe-inline' ;` |
|`img-src` |Images | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No |`img-src 'self' 'unsafe-inline' ;` |
|`style-src` |Styles | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`font-src` |Fonts | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`object-src` |Objects | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`media-src` |Media | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`child-src` |Child | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`form-action` |Form actions | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`worker-src` |Workers | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`base-uri` |Base URI | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`manifest-src` |Manifests | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`frame-src` |Frames | <ul><li>`'none'`</li><li>`'self'`</li><li>`'unsafe-inline'`</li><li>`'unsafe-eval'`</li><li>`'<HASH>'`</li></ul> |No | |
|`frame-ancestors` |Frame ancestors | <ul><li>`'none'`</li><li>`'self'`</li></ul> |No | |
|`upgrade-insecure-requests` |Upgrade insecure requests |N/A |No | |

<!-- document id=1f13498163842ffb2b6535f93f4d6ce6514e476a44591636b656773edae306dc url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/supported-domains.md -->

# Supported Domains

This section documents each commerce domain supported by the Commerce Apps framework, organized by release wave. Each domain entry covers the architecture(s) available, extension points and UI targets, and anchor partners.

## Domain Registry

Every Commerce App must declare a `domain` field. Domains use hyphen-case. The Cart & Checkout Hub in Business Manager organizes domains into two sections:

- **Providers** (`tax`, `payment`, `shipping`): Display under "Providers" in the hub. Multiple apps in the same provider domain appear as alternative choices under one tile.
- **Additional Setup** (all other domains): Display under "Additional Setup" in the hub.

| Domain                  | Hub Section      | Description                                   | Example ISVs              |
| :---------------------- | :--------------- | :-------------------------------------------- | :------------------------ |
| `tax`                   | Providers        | Tax calculation and compliance                | Avalara, Vertex           |
| `payment`               | Providers        | Payment processing                            | Stripe, Adyen, PayPal     |
| `shipping`              | Providers        | Shipping and fulfillment                      | ShipStation, EasyPost     |
| `gift-cards`            | Additional Setup | Gift card purchasing, redemption, and balance | Salesforce Gift Cards     |
| `ratings-and-reviews`   | Additional Setup | Product ratings and reviews                   | Bazaarvoice, Yotpo        |
| `loyalty`               | Additional Setup | Loyalty programs and rewards                  | LoyaltyLion, Smile.io     |
| `search`                | Additional Setup | Search and merchandising                      | Algolia                   |
| `address-verification`  | Additional Setup | Address validation and standardization        | Loqate, Smarty            |
| `analytics`             | Additional Setup | Analytics and reporting                       | Google Analytics, Segment |
| `approaching-discounts` | Additional Setup | Approaching discount notifications            | Salesforce                |
| `oms`                   | Additional Setup | Post-purchase order management                | Custom (third-party OMS)  |

## Release Timeline Overview

| Wave   | Release           | Domains                                                                  |
| :----- | :---------------- | :----------------------------------------------------------------------- |
| Wave 1 | April 2026        | Tax, Ratings & Reviews, Loyalty, Search, Address Verification, Analytics |
| Wave 2 | August 2026[^1]   | Shipping, Fraud, Marketing & TOS Consent + SFRA support                  |
| Wave 3 | October 2026[^1]  | Versioning, upgrade support, dependency management                       |
| Wave 4 | February 2027[^1] | Recurring Orders, Surcharges, CMS, CDN/Hosting, SMS, PIM, ERP            |

[^1]: Salesforce future roadmap subject to change and under our [Safe Harbor](https://investor.salesforce.com/financials/safe-harbor/default.aspx) statement.

## Tax Domain

Tax is the first domain with a platform-defined adapter interface. The platform provides the front-end components for collecting shipping addresses and calculating tax in the order summary, and defines back-end extension points. You implement the script API contract.

**Extension points** (triggers summarized below; see [Tax Extension Points](/docs/commerce/b2c-commerce/guide/building-your-app.md#extension-points) for full contracts including parameters, return values, and error semantics):

- `sfcc.app.tax.calculate` — every basket operation (adding items, changing quantities, updating shipping address, and so on); not only at checkout
- `sfcc.app.tax.commit` — immediately after successful order creation (status `CREATED`)
- `sfcc.app.tax.cancel` — on order cancellation or failure (`OrderMgr.failOrder()` or `OrderMgr.cancelOrder()`)

### Extension Point Flows

#### `sfcc.app.tax.calculate`

Fires during every basket calculation (add item, change quantity, update shipping address, and so on). The platform selects the tax hook based on registration and whether hooks are enabled for the request.

![Flowchart showing the sfcc.app.tax.calculate hook triggered on every basket operation, with the platform routing to the registered tax provider](https://developer.salesforce.com/media/b2c-commerce/calculateTax.png)

#### `sfcc.app.tax.commit`

Fires inside the order creation transaction immediately after the order is created with status `CREATED`.

![Flowchart showing sfcc.app.tax.commit triggered immediately after order creation with status CREATED, with blocking and non-blocking error paths](https://developer.salesforce.com/media/b2c-commerce/commitTax.png)

#### `sfcc.app.tax.cancel`

Fires when an order is cancelled (`OrderMgr.cancelOrder()`) or failed (`OrderMgr.failOrder()`). The platform invokes this hook after inventory release and other critical operations complete.

![Flowchart showing sfcc.app.tax.cancel triggered when an order is cancelled or failed via OrderMgr.cancelOrder or OrderMgr.failOrder](https://developer.salesforce.com/media/b2c-commerce/cancelTax.png)

### Tax UI Targets

| Feature                | Surface                    | Target ID                            |
| :--------------------- | :------------------------- | :----------------------------------- |
| Tax Product Message    | PDP                        | `sfcc.pdp.tax.productMessage`        |
| Tax Line Item Message  | Cart                       | `sfcc.cart.tax.lineItemMessage`      |
| Tax Line Item Message  | Mini Cart                  | `sfcc.miniCart.tax.lineItemMessage`  |
| Order Summary Tax Line | Order Summary              | `sfcc.orderSummary.tax.line`         |
| Tax Summary            | Order Confirmation         | `sfcc.orderConfirmation.tax.summary` |
| Order Details Tax      | My Account - Order Details | `sfcc.myAccount.orderDetails.tax`    |

## OMS Domain

OMS is a backend-only domain with a platform-defined adapter interface. There are no storefront UI targets: the platform already exposes order data through Shopper Orders, Shopper Customers, and Universal Commerce Protocol (UCP) order lifecycle updates. You implement the script API contract so a third-party OMS can serve that data.

Declare `"domain": "oms"` in `commerce-app.json`. For the full hook contracts, inbound `oms-status-events` API, and worked examples, see [Connect a Third-Party OMS](/docs/commerce/b2c-commerce/guide/connect-third-party-oms.md).

**Architecture:** Backend-only (extension point hooks). All four core hooks must be registered together or the platform falls back to its default order store.

**Extension points** (triggers summarized below; see [Connect a Third-Party OMS](/docs/commerce/b2c-commerce/guide/connect-third-party-oms.md#the-hooks) for full contracts including parameters, return values, and error semantics):

- `sfcc.app.oms.order.retrieve` — provide a single order (pre-populated when the platform still holds the order locally, empty when the platform doesn't hold it)
- `sfcc.app.oms.order.list` — provide orders for a single customer (order history)
- `sfcc.app.oms.order.cancel` — cancel a whole order in the OMS
- `sfcc.app.oms.order.return` — start a return for specific order items
- `sfcc.app.oms.order.accessControl` (optional) — override the default shopper-owns-order check
- `sfcc.app.oms.order.reasonCodes` (optional) — supply cancel and return reason codes

The platform also exposes an inbound Admin API (`POST .../oms-status-events`) so the OMS can push fulfillment and adjustment events. See [Order Post-Processing Events in the UCP Order Lifecycle](/docs/commerce/b2c-commerce/guide/ucp-order-post-processing-events.md) for how those events become signed UCP snapshots.

## Ratings & Reviews Domain

Ratings & Reviews is a fullstack domain. Storefront Next provides mocked UI components out of the box that you replace with your own extensions. You build a custom SCAPI for the backend and provide Storefront Next components that consume it.

**SCAPI interface:** No platform-defined interface. ISV builds custom SCAPI (Get Star Rating exists as a platform API needing extension; Get Reviews and Submit Review are ISV custom SCAPI).

**sfNext components:** Available in April 2026. UI targets available in May 2026.

### Ratings & Reviews UI Targets

| Feature         | Surface                    | Target ID                            |
| :-------------- | :------------------------- | :----------------------------------- |
| Star Rating     | PDP                        | `sfcc.pdp.reviews.rating`            |
| Review Summary  | PDP                        | `sfcc.pdp.reviews.summary`           |
| Reviews List    | PDP                        | `sfcc.pdp.reviews.list`              |
| Star Rating     | Shared - Product Card      | `sfcc.productCard.reviews.rating`    |
| Q&A             | PDP                        | `sfcc.pdp.reviews.qna`               |
| Review Purchase | My Account - Order Details | `sfcc.myAccount.orderDetails.review` |
| Manage Reviews  | My Account - Overview      | `sfcc.myAccount.reviews.pending`     |

## Loyalty Domain (Wave 1, Fullstack)

Loyalty is a fullstack domain. You build a custom SCAPI for points calculation and redemption and provide Storefront Next components.

### Loyalty UI Targets

| Feature         | Surface               | Target ID                                  |
| :-------------- | :-------------------- | :----------------------------------------- |
| Loyalty Points  | PDP                   | `sfcc.pdp.loyalty.points`                  |
| Loyalty Points  | Product Card          | `sfcc.productCard.loyalty.points`          |
| Points Earned   | Cart                  | `sfcc.cart.loyalty.pointsEarned`           |
| Loyalty Summary | My Account - Overview | `sfcc.myAccount.loyalty.summary`           |
| Enrollment      | User Registration     | `sfcc.userRegistration.loyalty.enrollment` |

## Additional Wave 1 Domains (Fullstack)

The following domains are available in Wave 1 as fullstack (custom SCAPI + Storefront Next extensions). Detailed UI target catalogs will be published as target IDs are finalized.

- **Address Verification:** UI targets in May 2026. Features include Address Auto Suggest and Address Validation Confirmation across Checkout, User Registration, and My Account.

- **Search:** UI targets still being defined. Features include Search Input and Search Results Grid.

- **Analytics:** UI targets pending discovery. Primarily script/beacon-based, minimal UI. See [Injecting External SDK Scripts](/docs/commerce/b2c-commerce/guide/building-your-app.md#injecting-external-sdk-scripts) for guidance on loading analytics SDKs using `contextProviders`.

## Wave 2 Domains (264, Backend-Only: Extension Points)

These domains will introduce platform-defined extension points similar to Tax. You implement the adapter interface contract. Documentation for specific extension points and interface specifications will be published as they are finalized.

- **Shipping:** Anchor partner Zenkraft/Navar. Extension points for rate calculation, delivery estimation. SCAPI interface in 264.

- **Fraud:** Anchor partner Forter/Signifyd. Extension points for pre-auth and post-auth fraud checks. SCAPI interface in 264. Fraud beacons can be injected today using `contextProviders` — see [Injecting External SDK Scripts](/docs/commerce/b2c-commerce/guide/building-your-app.md#injecting-external-sdk-scripts).

- **Marketing & TOS Consent:** Native + ISV. SCAPI interface in 264.

## Wave 4 and Beyond

Domains planned for 266 and beyond include Recurring Orders, Surcharges, CMS, CDN/Hosting, SMS, PIM, and ERP. These aren't documented in detail in this guide. Documentation will be published as each domain becomes available.

<!-- document id=fccdbbe6420d3b32d8b65a5c0ddc596f7cfb4fd4dbb0c8bc7f69f5c13a44766d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/inventory/b2c-supporting-scheduled-inventory-imports.md -->

# Supporting Scheduled Inventory Imports

When scheduling an inventory import, you must create a pipeline that retrieves files to be imported within your customized application.

## Import Pipeline

To better understand the pipeline, review the sub-pipeline details in the following pages:

- Sub-pipeline : [GetExecSettings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sub-pipeline-get-exec-settings.md)
- Sub-pipeline : [GetUnzipFile](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sub-pipeline-get-unzip-file.md)
- Sub-pipeline : [LoadFilesFromFTP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sub-pipeline-load-files-from-ftp.md)
- Sub-pipeline : [LoadFilesFromHTTP](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sub-pipeline-load-files-from-http.md)
- Sub-pipeline : [DoInventory](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-sub-pipeline-do-inventory.md)

The following are the referenced script files:

- [BeginFileLog.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-begin-file-log-ds.md)
- [CreateImpExFolderStructure.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-create-impex-folder-structure-ds.md)
- [DelFile.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-del-file-ds.md)
- [EndFileLog.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-end-file-log-ds.md)
- [GetFilesFromDirectory.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-files-from-directory-ds.md)
- [GetFilesFromFTPServer.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-files-from-ftp-server-ds.md)
- [GetFilesFromHttpServer.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-files-from-http-server-ds.md)
- [GetImpExProcessingPath.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-imp-ex-processing-path-ds.md)
- [GetUnzip.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-get-unzip-ds.md)
- [LoadTaskConfiguration.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-load-task-configuration-ds.md)
- [RenameFile.ds](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-rename-file-ds.md)

<!-- document id=8b34bd76246c255fb0c821c61eebc95c48aa35ffd5d0761d55835f02ce30ecd7 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/active-merchandising/b2c-tagging-pages-for-data-collection.md -->

# Tagging Pages for Data Collection

The active merchandising tags aren't used for web analytics reporting. They collect data that is used by your storefront for product placement and sorting search results.

## Instrumenting Pages

You must _instrument_ the ISML templates to enable analytics data collection. To instrument the pages, you add tags in specific places within your ISML templates to collect the data. Not all sites require all the data that can be collected, so omit any steps that are unnecessary for your site. Choose the pages to instrument carefully, because over-instrumenting pages can cause performance problems

**note:** For examples of already instrumented pages, in the latest version of Studio, select **File > New > SiteGenesis Storefront Cartridges.** This cartridge download includes SiteGenesis, which contains examples of already tagged pages.

To instrument your ISML templates:

1.  Add the [`<isactivedatahead>` Tag](#add-isactivedatahead-tags) to templates containing HTML `<head>` tags.
2.  Add the [`<isactivedatacontext>` Tag](#add-isactivedatacontext-tags) to templates where category context is indicated.
3.  Add [`<isobject>` Tags](#add-isobject-tags) to templates to capture activity related to viewing the following:
    - Product details
    - Product sets
    - Search results
    - Recommendations
4.  Add calls to Salesforce B2C Commerce Client-Side JavaScript functions where product representations are made visible only as a result of storefront customer interaction after the page is rendered.
5.  Validate your active data tags.

## Add isactivedatahead Tags

To collect active data, place the `<isactivedatahead>` tag in every ISML template that contains an HTML `<head>` tag that you want to collect the data from. ISML templates without an HTML `<head>` tag don't use the `<isactivedatahead>` tag. Place the tag immediately before the closing head tag `</head>`.

The `<isactivedatahead> tag must appear:

- Before any other analytic data collection ISML tags
- After all references to external JavaScript libraries
- In a location where `<script>` tags are valid

If this tag appears after any other analytic data collection ISML tags, those tags could fail to collect data. If this tag appears before any references to external JavaScript libraries, those external JavaScript libraries could become incompatible. This tag must appear where `<script>` tags are valid. For example, it can't be placed between two `<tr>` tags for rows of a table or similar structures in a page.

If the tag isn't placed in a page or isn't placed in a page correctly, the storefront customer could experience JavaScript errors. Customers could be notified of the error or the page rendering could be negatively affected.

Best Practice: Generally, always place the `<isactivedatahead>` tag in the `<head>` tags. However, if the template is used solely for a page or page set that could never have data of analytic interest, don’t add the tag.

This feature is implemented in SiteGenesis as follows:

The `htmlhead.ism` file references `htmlhead_UI.isml` via an include (`<isinclude template="components/header/htmlhead_UI"/>`).

The `htmlhead_UI.html` file contains this line: `<isactivedatahead>.`

## Add isactivedatacontext Tags

To collect active data on the most specific category browsed on the page, add the `<isactivedatacontext>` tag to the `<head>` or `<body>` tags of site pages with valid `<script>` tags. The best location is wherever the category context of the site is most prominently indicated to the storefront customer. For example, breadcrumbs that are rendered that show the current category.

Best practice: Include this tag in exactly one template used to make up each HTML page. If this tag appears in multiple templates used to make up a single HTML page, the latest template takes precedence. For example, if one tag indicates the _Hats_ category, and a later tag indicates the _Socks_ category, the _Socks_ category takes precedence. There is no negative effect if the tag appears in multiple templates with the same category value for the same HTML page, but it's redundant. If this tag doesn't appear in any templates that are used to make up an HTML page, no category context is associated with the page.

The specified category is also associated with data collected in the page about products.

**note:** If the `categoryID` attribute of `ProductLineItem` is set, Salesforce B2C updates the `topCategoriesOrdered` field with that category instead of the category specified by the `isactivedatacontext` tag.

The following table shows how this feature is implemented in SiteGenesis:

| Template                                                 | Tag example                                                              |
| -------------------------------------------------------- | ------------------------------------------------------------------------ |
| `components/productbreadcrumbs_left_directcategory.isml` | `<isactivedatacontext category="${category}">`                           |
| `components/productbreadcrumbs.isml`                     | `<isactivedatacontext category="${category}">`                           |
| `search/components/productsearchbreadcrumbs.isml`        | `<isactivedatacontext category="${pdict.ProductSearchResult.category}">` |

## Add isobject Tags

Embed the `<isobject>` tag in ISML templates to collect active data from customer storefront activity. This tag can appear any number of times in the same page, with no limit, but the tag must be placed where `<script>` tags are valid.

If the same product appears in multiple tags in the same page, for the same type of count only the first one is counted. It's unnecessary to wrap all product representations that result from searches, but product representations that aren’t wrapped are excluded from analytics collection. It's unnecessary to wrap the HTML content for every representation of every product that appears in the site. For example, it isn't always appropriate to wrap products in pages that show the contents of the cart.

Set the `<isobject>` tag `<view>` attribute to one of the following values, or data isn’t be collected.

<table><col /><col /><col /><thead><tr><th>Value</th><th>Collects</th><th>Details</th></tr></thead><tbody><tr><td>detail</td><td><p>product views</p> <p>Each HTML page containing an <isobject> tag with view="detail" counts as one product view for the product.</p></td><td><p>Use this value to tag your site and collect hits on product information. The <isobject> tag must be placed so that it wraps the ISML that represents the product details on a product detail page.</p> <p>Most sites use only one template to render product information on a product detail page. Optionally, tag templates that render a Quick view or show the products in a set.</p> <p>The tag results in an increment of the number of product views for a product. There aren’t clear rules about the number or detail type required of a product for it to count as a view instead of an impression. To make the impressions and views metrics meaningful, the views and impressions attributes must not be used interchangeably. Consider requiring the storefront customer to initiate an action to get more information about a product to consider it as a view. This action can call a quick view, click to the product detail page, or click through a product set to see product details.</p></td></tr><tr><td>none</td><td>Each HTML page containing an <isobject> tag with view="recommendations" counts as one product impression for the product.</td><td>Collects search information for the storefront toolkit but doesn't count the object as a product hit for active merchandising. For example, you might want to use this for templates where no search hits are found. This attribute can be used to collect information for the Storefront Toolkit Search Information Tool even if active merchandising isn't enabled for the instance. The passed object attribute is an instance product search model object. For example, <codeblock><isobject object="${ProductSearchModel}" view="none"></codeblock></td></tr><tr><td>recommendation</td><td><p>product impressions</p> <p>Each HTML page containing an <isobject> tag with view="recommendations" counts as one product impression for the product.</p></td><td><p>Use this value to tag your site and collect product recommendations hits. The <isobject> tag must be placed so that it wraps the ISML that represents each product recommended to the storefront customer.</p> <p>Each template must wrap its recommended products in this tag, or those products are excluded from analytics collection.</p> <p>A site can have multiple templates that render recommendations: home page, landing pages, product detail pages, and in slots, search results, order confirmations, and cart views. If your site uses many different templates to render recommendations, create a common template that renders the product information included by these templates. Then add the <isobject> tag there. Optionally, place the recommendation type in the pipeline dictionary or make it a module attribute.</p> <p>The <isobject> tag increments the number of product impressions for a specified product. The tag also tracks that the product was recommended to the customer as part of the visit. The fact that it was recommended stays in effect until the customer ends the visit or completes the ordering process.</p> <p>The same product can only count for one product impression per page using this method. If multiple tags specify the same product, it's only counted one time.</p></td></tr><tr><td>setproduct</td><td><p>product impressions</p> <p>Each HTML page containing an <isobject> tag with view="setproduct" counts as one product impression for the product.</p></td><td><p>Use this value to tag your site and collect hits on products that are part of a product set.</p> <p>The <isobject> tag must be placed so that it wraps the ISML that represents each product that is part of a product set.</p> <p>Most sites only have a few templates that render the product detail page for a product set. Each product set product detail page template must wrap each product in the set in this tag, or those products are excluded from analytics collection. As a best practice, don't include the tag unless the products in the set are represented on the page. For example, a product set is rendered in a slot among other recommended products. It isn't appropriate to add the tag for the products in the set that aren’t represented individually to the customer. When the set products are shown in greater detail, it's better to consider the product detail value.</p> <p>The <isobject> tag increments the number of product impressions for a product. Even for a product with some representation on a page, if the page isn't intended to merchandise the product, no tag is needed. For example, a product set doesn't have its own image so the set product images appear instead. This lack of images alone isn't enough reason to tag the set products</p> <p>The same product can only count for one product impression per page using this method. If multiple tags specify the same product, it's only counted one time.</p></td></tr><tr><td>searchhit</td><td><p>product impressions</p> <p>Each HTML page containing an isobject tag with view="searchhit" counts as one product impression for the product.</p></td><td><p>Use this value to tag your site and collect hits on search results.</p> <p>The <isobject> tag must be placed so that it wraps the ISML for HTML components that represent the product: product name, image, callout, price, swatches, and other components.</p> <p>Use the instance type of ProductHit in the tag's attribute, when view is of type <code>searchhit</code>. For example, <code>ProductSearchHit</code></p> <p>Most sites use only a single template to render products in search results. A site with different search result layouts for different categories can have multiple templates.</p> <p>When someone other than a storefront customer performs a search, other view values can achieve more meaningful results. For example, a search is performed using the API to determine the products to show in a slot. The product detail or recommendation view types can be a better choice, depending on how much detail is shown for the product and the merchandising intent.</p> <p>The <isobject> tag increments the number of product impressions for the wrapped product. The same product can only count for one product impression per page using this method. If multiple tags specify the same product, it is only counted one time.</p></td></tr></tbody></table></sfdocstbl>
If you don't wrap a product representation in a template, the representation in that template doesn’t affect analytics data. Place this tag anywhere in an ISML template that contains a representation of a product with the intent of merchandising that product for sale. If a product representation is tagged but doesn't exactly match a view type listed previously, select the view type that best matches the intent.

### Examples

```
<isobject object="${ProductSearchHit}" view="searchhit"><div class="image">...</div></isobject>
 <isobject object="${pdict.Product}" view="setproduct">
 <isinclude template="product/components/subproduct"/>
</isobject>
<isobject object="${product}" view="recommendation">
 <isproducttile product="${product}" showswatches="${true}" showpricing="${true}" ​showpromotion="${true}" showrating="${true}">
</isobject>
```

### SiteGenesis and Examples

The following table shows examples of the [<isobject>](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/isml/b2c-isobject.md) tag, and identifies the SiteGenesis templates that contain an example of the tag.

| Tag Example                                                | SiteGenesis Template                                                       |
| ---------------------------------------------------------- | -------------------------------------------------------------------------- |
| `<isobject object="${pdict.Product}" view="detail">`       | `product/productdetails.isml`                                              |
| `<isobject object="${pdict.Product}" view="setproduct">`   | `product/producttocontentPS.isml AND product/components/bonusproduct.isml` |
| `<isobject object="${ProductSearchHit}" view="searchhit">` | `search/productgrid.isml`                                                  |
| `<isobject object="${product}" view="recommendation">`     | `slots/product/product_1x4.isml`                                           |

**note:** `<isobject object="${product}" view="recommendation">` doesn't currently aggregate data and is included for future development.

## Add JavaScript Calls for DHTML Widgets

Some sites have pages that contain dynamic content that only appears to storefront customers in certain circumstances. For example, SiteGenesis features carousel widgets that cycle through several products when arrows are clicked, or rotating banners that cycle through several products over time.

**note:** If you don't use DHTML widgets in your storefront, ignore this topic.

If `<isobject>` tags are included in the ISML templates for all products in these widgets, then all products are included in the analytics collection. The products are included even if the customer never clicks in the carousel or waits long enough to cycle through the banners. Salesforce B2C Commerce provides JavaScript functions that enable you to be more precise when collecting data.

The B2C Commerce JavaScript library includes two JavaScript functions: `dw.ac.capture` and `dw.ac.applyContext`.

### dw.ac.capture (Object or Array data)

The `dw.ac.capture` function is used to collect analytics information for products that can't be guaranteed to appear. In the previous examples, the `dw.ac.capture` function is called in two cases. The function is called when the customer clicks an arrow to move the carousel and when the banner automatically rotates to show the next product.

Each time the `dw.ac.capture` function is called, analytics data is collected. If the carousel is cycled through all of its products so that when the initial product appears again, it can be counted twice. To avoid double counting, only call the capture function the first time a product appears.

The `dw.ac.capture` function collects the data and submits it for processing. The data can either be a single object with the product attributes listed (see following table), or an array of objects that each have these attributes.

| Product attribute | Purpose                                                       | Optional |
| ----------------- | ------------------------------------------------------------- | -------- |
| String id         | The ID (SKU) of the product                                   | Yes      |
| String type       | The type of data to collect, such as `dw.ac.EV_PRD_SEARCHHIT` |          |

Only valid objects that have these attributes are collected. If no valid product objects are provided for collection, submission doesn't occur.

**Examples**:

This example is part of the app.js file in the SiteGenesis cartridge.

```
dw.ac.capture({ id : $(this).text(), type : dw.ac.EV_PRD_RECOMMENDATION });
```

**Arguments**:

For each product specified in a call to the `dw.ac.capture` function, you must specify the type of event that causes the information capture. Use the following constant values in the JavaScript library, in objects passed as arguments to the `dw.ac.capture` function.

| Constant value                | Description                                             |
| ----------------------------- | ------------------------------------------------------- |
| `dw.ac.EV_PRD_DETAIL`         | A product shown in detail, as for a product detail page |
| `dw.ac.EV_PRD_RECOMMENDATION` | A product shown as a recommendation to the customer     |
| `dw.ac.EV_PRD_SEARCHHIT`      | A product shown as a hit in search results              |
| `dw.ac.EV_PRD_SETPRODUCT`     | A product shown as a constituent of a product set       |

These constants correspond to the four values of the `type` attribute for the `<isobject>` tag.

These examples show how to use the `dw.ac.capture` function to track product view, search result view, and recommendations view in dhtml.

**Examples**:

```
dw.ac.capture({ id: pid, type: dw.ac.EV_PRD_DETAIL });
```

```
dw.ac.capture({ id: pid, type: dw.ac.EV_PRD_SEARCHHIT });
```

```
dw.ac.capture({ id: pid, type: dw.ac.EV_PRD_RECOMMENDATION });
```

**note:** Gathering these analytics requires that tracking is enabled during the shopper's session.

### dw.ac.applyContext (Object configs)

Use the `dw.ac.applyContext` function to change the analytics context from what is initially provided by the `<isactivedatacontext>` tag. For example, a rotating banner on the home page showcases a product from each top-level category of the site. If the `<isactivedatacontext>` tag isn't on that page, no category is associated with the representation of these products. If you want to associate a category context with each product in the banner, use the `<isactivedatacontext>` tag. The category provided in the tag could only be appropriate for the first product that appears in the banner. For each subsequent product to appear in the banner, call the _dw.ac.applyContext_ function to associate a new category.

Each time the `dw.ac.applyContext` function is called, it affects all subsequent calls to `dw.ac.capture` until the next call to `dw.ac.applyContext`. For example, a banner cycles through products 1 through 6. Products 1 through 3 are in category A, and products 4 through 6 are in category B. Use the `<isactivedatacontext>` tag or call `dw.ac.applyContext` to set category A before product 1 appears. This category stays in effect when the banner cycles to products 2 and 3. Because product 4 is in a different category, call `dw.ac.applyContext` before calling the `dw.ac.capture` function for product 4, to set the context to category B.

The following parameter sets the context for subsequent events that occur on the page. Call this function if automatic DHTML or customer activity changes the context of the page. This function doesn't cause data to be submitted for processing; it only changes values in the current context to be associated with data submitted later.

| Configuration parameter | Purpose                                    | Optional |
| ----------------------- | ------------------------------------------ | -------- |
| String category         | The ID of the category browsed on the page | Yes      |

**Example**:

```
dw.ac.applyContext({ category: 'SomeCategoryID' });
```

For example, assume that a home page has a slot that shows the top selling product in each category in a carousel. Each time the carousel shows a new product, the context for that product is a different category. This function is called each time the carousel is scrolled, to set the appropriate category for the product now shown.

## Validating Active Data Tags

An active data integration is valid if the correct information is collected on a Production instance and retrieved on Production and Staging instances.

Test on those instances or on other instances with an equivalent configuration. Because analytics information is only collected from the Production system, retrieved information is always identical for all instances of a site.

Use the Analytics Debugger tool to validate information that is sent from the template to Salesforce B2C Commerce. All cases of ISML tags and calls to the analytics JavaScript library must be validated to make sure that they are collecting the expected data. Sample pages of the site to make sure that there are no places where tags or JavaScript calls are missing.

## Using the Analytics Debugger

The Analytics Debugger (debugger) is a feature of the analytics JavaScript library. The debugger output is an alert message that shows each time information is provided to the JavaScript library for submission.

To turn on the debugger, include the following as the URL for a browser favorite or bookmark, and access that bookmark:

```
JavaScript:dw.ac.setDebugEnabled(true);
```

The debugger uses a session cookie to track that it was turned on. When it's turned on, it remains on for the rest of the browser storefront session. If the browser is closed, or the session otherwise comes to an end, it turns off automatically.

To manually turn it off, include the following as a separate bookmark:

```
JavaScript:dw.ac.setDebugEnabled(false);
```

The information in the alert messages shows exactly what is provided by the template for submission to Salesforce B2C Commerce. However, these messages don’t prove that the content was sent. If the debugger shows that information was submitted, but data wasn't collected, contact customer support to validate that B2C Commerce received the information.

### Troubleshooting

If data collection isn't enabled for the store front, the debugger shows the message:

`Analytics data collection is disabled.`

If data collection is on and the debugger is enabled, navigating to a page in the storefront shows a window similar to the following:

```
Message from webpage

s._account="demand"
s.pageName="__internal"
s.visitorID="xU9k5Y57WgjFgMXkGPdD545x9evWirFSSTA="
s.prop1=""
s.prop2="women-footwear"
s.campaign=""
s.events="event3"
s.products=";10002;;;;evar2=women-footwear,;10001;;;;evar2=women-footwear
,;11033;;;;evar2=women-footwear,;10729;;;;evar2=woman-footwear
,;11016;;;;evar2=women-footwear,;11050;;;;evar2=woman-footwear
,;10408;;;;evar2=women-footwear,;10734;;;;evar2=woman-footwear
,;10655;;;;evar2=women-footwear,;10774;;;;evar2=woman-footwear
,;10809;;;;evar2=women-footwear,;10823;;;;evar2=woman-footwear
"
s.eVar1=""
s.eVar5="xU9k5Y57WgjFgMXkGPdD545x9evWirFSSTA="
OK
```

<!-- document id=91e6ae384bd0dcc0ab47a2379c1f1065ee7cef0d4dcc4a39c1a7d69f61053647 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/tax-calculation-spi.md -->

Tax Calculation SPI

# Tax Calculation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/tax-calculation-spi/tax-calculation-spi-oas-public.yaml)

Merchant SPI to calculate taxes for a transaction according to the rules defined in the tax engine of the merchant's system. APIs include tax calculation, getting tax exemptions, and downloading tax rates for offline transactions.

### Configuration

1.  **Store Management** > **Integration** > **Custom API Connectors** > **Create**
    *   **API KEY:** TAX\_SERVICE with authentication details and URL Base.
    *   All the APIs defined below will use this URL base; only the last keyword will change.
2.  Set **Store Management** > **Store Settings** > **Tax** > **valueAddedTaxEnabled** to `true` to enable VAT.

For more details, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html).

**Version:** 2.3.4

## Tags

### Tax Calculation SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/tax-calculation-spi/tax-calculation-spi-oas-public.yaml)

Merchant SPI to calculate taxes for a transaction according to the rules defined in the tax engine of the merchant's system. APIs include tax calculation, getting tax exemptions, and downloading tax rates for offline transactions.

### Configuration

1.  **Store Management** > **Integration** > **Custom API Connectors** > **Create**
    *   **API KEY:** TAX\_SERVICE with authentication details and URL Base.
    *   All the APIs defined below will use this URL base; only the last keyword will change.
2.  Set **Store Management** > **Store Settings** > **Tax** > **valueAddedTaxEnabled** to `true` to enable VAT.

For more details, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html).

## Operations

### POST Calculate tax.

`POST /merchant/spi/sample/endpoint/taxEngine/calculateTax`

Operation ID: `calculateTax`. Tags: Tax Calculation SPI.

Calculate the tax based on the rules defined in the merchant's system. The request includes a list of products, tax exemptions to be applied if any, and the addresses (originating and destination) so that the correct tax rates can be applied.

#### Request body

Media type: `application/json`. Schema: `SpiTaxCalculationRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiTaxResponse`.
    

### GET Download tax rates.

`GET /merchant/spi/sample/endpoint/taxEngine/downloadTaxRates`

Operation ID: `downloadTaxRates`. Tags: Tax Calculation SPI.

Download tax and VAT rates into the POS system. This integration enables POS to retrieve accurate tax and VAT rates for offline transactions. The SPI supports optional query parameters such as `countryCode`, `state`, `city`, and `postalCode`, which allow for precise tax rate retrieval. The expected response format is a plain string in CSV, containing the relevant tax and VAT rates. For more detailed information, including sample requests and responses, refer to [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html)

#### Parameters

*   `countryCode` (query, string)
*   `state` (query, string)
*   `city` (query, string)
*   `postalCode` (query, string)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `DownloadTaxRatesResponse`.
    

### POST Finalize tax submission.

`POST /merchant/spi/sample/endpoint/taxEngine/finalizeTaxSubmission`

Operation ID: `finalizeTaxSubmission`. Tags: Tax Calculation SPI.

Finalize the taxes applied to sale transactions. This is an optional SPI. It provides a list of products and applied taxes to the tax engine, and the orderId associated with the transaction.

#### Request body

Media type: `application/json`. Schema: `SpiTaxSubmissionRequest`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

### GET Retrieve tax exemptions.

`GET /merchant/spi/sample/endpoint/taxEngine/getTaxExemptions`

Operation ID: `getTaxExemptionList`. Tags: Tax Calculation SPI.

Retrieve the list of tax exemptions supported on the merchant's side. This is an optional SPI and applicable only for tax regions and not applicable for VAT. The following optional fields can be provided in the response: TaxClasses, CountryCode, State, City, and Postal Code, such that the tax exemption is applicable as per the provided values. For example: If a tax exemption is provided with State = CA, then that tax exemption is assumed to be applied only for CA state. If an exemption can be applied regardless of state, country, or particular tax class, these fields in the response don't need to be populated. We mark them as 'ANY' denoting it can be applied without any rules or restrictions.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiTaxExemptionResponse`.
    

### GET Verify tax engine.

`GET /merchant/spi/sample/endpoint/taxEngine/verify`

Operation ID: `verify`. Tags: Tax Calculation SPI.

Verify that the SPI Tax Engine is available and requests can be sent. If the verify API is implemented, it is checked when verifying the feed source for offline taxes. If it is not implemented, we let it pass through and try to download tax rates.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `SpiPSResponse`.
    

## Schemas

### SpiTaxCalculationRequest

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `taxBuckets` (_array of SpiTaxBucket_, required) All products that require tax calculations are grouped based on their origin and destination addresses, and provided in these tax buckets, along with any applicable tax exemptions.

### SpiTaxResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `taxItems` (_array of TaxOrVatRecord_, required) List of products and their tax rates.
*   `error` (_boolean_)

### DownloadTaxRatesResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `taxRates` (_string_, required) Contains the tax or VAT rates in CSV format. The first line must contain the column headers, and subsequent lines must have the corresponding tax or VAT rate values. Column names are case-sensitive and must adhere to the specified format. All required columns, their specifications, and a sample response are available in the documentation: [Set Up Tax Integration Using SPI](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/tax-integration-via-spi.html).
*   `error` (_boolean_)

### SpiTaxSubmissionRequest

*   `cartId` (_string_, required) Unique identifier for the cart.
*   `editOrderId` (_string_) Order ID for the order being edited.
*   `orderId` (_string_) The order ID corresponding to the transaction which involved the tax calculations with the merchant's tax engine.
*   `taxBuckets` (_array of SpiBucket_) The list of tax buckets which include products , their tax rates, source and destination addresses and tax exemptions if any.

### SpiPSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

### SpiTaxExemptionResponse

*   `taxExemptions` (_array of SpiTaxExemption_) List of tax exemptions that are supported by the Merchant's tax engine and can be used for tax calculations.Tax exemptions are optional, can have empty response.

### SpiTaxBucket

All products that require tax calculations are grouped based on their origin and destination addresses, and provided in these tax buckets, along with any applicable tax exemptions.

*   `products` (_array of TaxProduct_, required) List of Products that have the same originating and destination address.
*   `taxExemptions` (_array of SpiTaxExemptionRequest_, nullable) The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT.
*   `originStoreId` (_string_, nullable) The originating store ID where the transaction is occurring.
*   `fromAddress` (_SPIAddress_, required)
*   `toAddress` (_SPIAddress_, required)

### TaxOrVatRecord

List of products and their tax rates.

*   `amount` (_number_, required) Product Amount.
*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Product Quantity.
*   `orderItemId` (_string_, required) Order item ID of the product. This must match the orderItemId sent in the request. Used as a line identifier to resolve conflicts when two line items have the same productId.
*   `description` (_string_, nullable) Product name.
*   `taxClass` (_string_, nullable) Tax class of this product. Can be used for tax calculation. It will be sent if the product feed has it.
*   `taxRecord` (_SpiTax_)
*   `vatRecord` (_SpiVat_)

### SpiBucket

The list of tax buckets which include products, their tax rates, source and destination addresses, and tax exemptions if any.

*   `products` (_array of TaxProduct_, required) List of Products that have the same originating and destination address.
*   `taxExemptions` (_array of SpiTaxExemptionRequest_, nullable) The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT.
*   `originStoreId` (_string_, nullable) The originating store ID where the transaction is occurring.
*   `fromAddress` (_SPIAddress_, required)
*   `toAddress` (_SPIAddress_, required)
*   `records` (_array of TaxOrVatRecord_, required) List of products and their tax rates.

### SpiTaxExemption

List of tax exemptions that are supported by the merchant's tax engine and can be used for tax calculations. Tax exemptions are optional and can have an empty response.

*   `taxExemptCode` (_string_, required) Tax exemption code to be applied, for example, 100, 05, A, or CED.
*   `taxExemptName` (_string_, required) Tax exemption long name, for example, RESALE or TRIBAL GOVERNMENT.
*   `taxExemptionRate` (_number_, required) Tax exemption rate percentage.
*   `taxType` (_string_, nullable) Tax Type.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`.
*   `taxClasses` (_array of string_, nullable) Tax classes to which the exemption applies.
*   `countryCode` (_string_, nullable) Country Code where the exemption is applicable.
*   `state` (_string_, nullable) State where the exemption is applicable.
*   `city` (_string_, nullable) City where the exemption is applicable.
*   `postalCode` (_string_, nullable) Postal Code where the exemption is applicable.

### TaxProduct

List of Products that have the same originating and destination address.

*   `amount` (_number_, required) Product Amount.
*   `productId` (_string_, required) Product ID.
*   `quantity` (_integer (int32)_, required) Product Quantity.
*   `orderItemId` (_string_, required) Order item ID of the product. This must match the orderItemId sent in the request. Used as a line identifier to resolve conflicts when two line items have the same productId.
*   `description` (_string_, nullable) Product name.
*   `taxClass` (_string_, nullable) Tax class of this product. Can be used for tax calculation. It will be sent if the product feed has it.

### SpiTaxExemptionRequest

The list of tax exemptions to be applied during tax calculation, this is optional. It is applicable only for tax regions and not applicable for VAT.

*   `customerName` (_string_, required) Customer name for customer having tax exemption applied.
*   `cardNumber` (_string_, required) Customer tax exemption card number.
*   `taxExemptCode` (_string_, required) Tax exemption code to be applied, for example, 100, 05, A, or CED.
*   `taxExemptName` (_string_, required) Tax exemption long name, for example, RESALE or TRIBAL GOVERNMENT.
*   `taxType` (_string_, nullable) Tax Type.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`.

### SPIAddress

The full address of the destination of transaction.

*   `firstName` (_string_) Customer first name saved for address.
*   `lastName` (_string_) Customer last name saved for address.
*   `addressLine1` (_string_, required) Address Line 1.
*   `addressLine2` (_string_) Address Line 2.
*   `city` (_string_, required) City.
*   `state` (_string_) State.
*   `postalCode` (_string_, required) Postal Code.
*   `countryCode` (_string_, required) Country Code.
*   `phone` (_string_) Phone.
*   `storeId` (_string_) Store ID if it is store address.
*   `emailAddress` (_string_) Customer Email Address.

### SpiTax

Tax details for this product. Populate either tax or VAT.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries. Maps to productList.productTax.totalTax in Order TLOG JSON.
*   `taxRates` (_array of ItemTax_, required) Tax rates. Maps to productList.productTax.taxRates\[\] in Order TLOG JSON.
*   `totalExemptionAmount` (_number_) Total tax exemption amount that was applied. Maps to productList.productTax.taxExemption in Order TLOG JSON.

### SpiVat

VAT details for this product. Populate either tax or VAT.

*   `totalVat` (_number_, required) Total VAT. Required in case of VAT countries. Maps to productList.productTax.valueAddedTax in Order/Cart.
*   `vatRates` (_array of ItemTax_, required) VAT rates. Maps to productList.productTax.vatRates\[\] in Order TLOG JSON.
*   `totalExemptionAmount` (_number_, required) Total tax exemption amount that was applied. Maps to productList.productTax.taxExemption in Order TLOG JSON.

### ItemTax

Individual tax rates and their details. After the sale transaction, the TLog JSON will contain the product's tax rates corresponding to this class in productList\[\].productTax.taxRates and orderProductList\[\].productTax.taxRates.

*   `taxRate` (_number_, required) % tax/vat rate.
*   `taxAmount` (_number_, required) Sum of tax amounts of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) at the time of purchase. This represents the total line tax and should be calculated considering the quantity sent in the request.
*   `taxType` (_string_, required) Indicates tax type, such as COUNTRY, CITY, or STATE.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `SPECIAL`.
*   `taxCode` (_string_, required) Tax identifier. This is a unique identifier for tax rate per item.
*   `taxClass` (_string_, required) Tax class to which this tax rate belongs, for example, 1025 or T1C.
*   `perUnitTaxAmount` (_number_, required) The tax amount per unit in the case of multiple quantities of the product.
*   `highPrecisionTaxAmount` (_number_, nullable) Tax amount of a particular type (group of TaxType, TaxClass, TaxName, TaxRate) at the time of purchase with high precision (Scale / Number of decimal digits = 5). Required for Portugal region.
*   `taxName` (_string_, nullable) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.
*   `isExempt` (_boolean_) Indicates whether tax is exempted.  
    Default: `false`.
*   `taxExemptCode` (_string_, nullable) Tax Exemption Identifier to be provided in case this tax was exempted.
*   `taxExemptionAmount` (_number_, nullable) The tax amount value that was exempted.
*   `countryCode` (_string_, required) Country code.
*   `state` (_string_, required) State.
*   `postalCode` (_string_, required) Postal code.

<!-- document id=1d59d5ebe2a2a032fca03d0ba14cd99edc6de92b13f005bfc65ed580f845ee96 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-data-model-tax.md -->

# Tax Data Model

The Tax data model connects objects with relationships that support tax calculation throughout the cart-to-checkout sequence.

| Required Editions                                                       |
| ----------------------------------------------------------------------- |
| Available in: **Enterprise**, **Unlimited**, and **Developer** Editions |
| Available in: B2B Commerce                                              |

Commerce standard objects in the Tax data model require at least one of the following licenses: B2B Commerce.

![Diagram of the Tax data model.](https://developer.salesforce.com/media/d2c-commerce/commerce_cloud_tax_zh.png)

- [Product (Product2)](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_product2.htm) - used for subscription management only.
- [WebStore](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_webstore.htm)(Store Settings)
- [TaxPolicy](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_taxpolicy.htm)
- [TaxTreatment](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_taxtreatment.htm)
- [LegalEntity](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_legalentity.htm)
- [TaxRate](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_taxrate.htm)
- [GeoState](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_geostate.htm)
- [GeoCountry](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_geocountry.htm)

<!-- document id=7a1e38d1bacab7ed6cf764b9f8caef5f6390a9dc0e0a0d89ad5303ac06566638 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-technical-audit.md -->

# Technical Audit

Before you enable UCP, audit your existing checkout. UCP isn't a second checkout to build: a checkout session is a headless view on a standard Commerce Cloud Basket, and completing it creates an Order. Storefront UI, SFRA/SiteGenesis controllers, and **other SCAPI resources you use today** don't run in this flow.

Use this page to decide what you must move or bridge. How to write the hooks is in [Implementation Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md). Transaction boundaries are in [Transaction Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-transaction-management.md).

## What Runs and What Doesn't

**These standard hooks do run** on UCP checkout sessions, because they operate on the Basket and Order:

- `dw.order.calculate`
- `dw.order.calculateTax`
- `dw.order.calculateShipping`
- `dw.ocapi.shop.basket.validateBasket`
- `dw.order.createOrderNo`

If your pricing, tax, shipping, and validation already live in those hooks, that logic is reused.

**These don't run:**

- SFRA or SiteGenesis controllers
- Shopper Baskets, Shopper Orders, and other SCAPI `before` / `after` / `modifyResponse` hooks registered for those resources
- OCAPI resource hooks other than `validateBasket` (for example basket `beforePOST` / `afterPOST` on Shopper Baskets)

UCP calls the Checkout Session APIs (`POST/GET/PUT /checkout-sessions`, `complete`, `cancel`), not the Shopper Baskets or Shopper Orders APIs. Logic you attached to those endpoints must be copied or bridged onto the UCP checkout-session hooks. See the [extension hooks reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#extension-hooks-reference).

**note:** **Enable Salesforce Commerce API Hook Execution**

UCP checkout hooks only run when this feature toggle is on in Business Manager. If it is off, none of the UCP-specific hooks execute—including third-party payment hooks. Enable it before you rely on custom code in this flow.

## Path Chooser

Complete the hook inventory below. The path only changes how much you expect to move.

| Your storefront checkout today             | What to expect                                                                                                                                                                      |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SCAPI Shopper Baskets / Shopper Orders     | Native Basket/Order hooks still run. Anything in resource-specific SCAPI hooks for those APIs must be remapped to UCP checkout-session hooks.                                       |
| SFRA or SiteGenesis                        | Controllers are bypassed. Move tax, shipping, address verification, loyalty, custom fields, and similar logic out of controllers into the standard Basket/Order hooks or UCP hooks. |
| Custom OCAPI or other non-SCAPI order APIs | Write a bridge: call your existing Script API logic from the UCP checkout-session hooks. Confirm that logic doesn't require storefront-only or UI-only input.                       |

## Hook Inventory

Walk your current checkout and ask, for each behavior:

1. Does it already live in `calculate`, `calculateTax`, `calculateShipping`, `validateBasket`, or `createOrderNo`? If yes, verify it with a UCP checkout session—don't assume a SCAPI basket test covers it.
2. Does it live on Shopper Baskets, Shopper Orders, or another SCAPI/OCAPI resource? If yes, copy or bridge it to the matching UCP hook (`beforePOST` / `afterPOST` / `modifyPOSTResponse`, and the PUT/GET/complete/cancel equivalents).
3. Does it live in an SFRA/SiteGenesis controller? If yes, move it into a server-side hook. The platform never calls that controller.
4. Does the hook require extra input the UCP payload can't provide (form fields, browser cookies, client-side payment setup)? If yes, redesign it for a headless, server-side session or handle it with Continue URL handoff. See [Continue URL](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#continue-url-limitations).

For hook names, arguments, diagrams, and samples, see [Implementation Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md).

## Payment Path

A UCP checkout is paid with a **single** payment instrument. Select a path in Business Manager (**Merchant Tools > AI & Social Integrations > UCP**):

| Path                          | Audit questions                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Salesforce Payments (default) | Is the Salesforce Payments SKU provisioned? Is Google Pay configured for your gateway? If the same Adyen merchant account also serves your storefront cartridge, you must filter webhooks so that cartridge ignores UCP/SFP orders. See [Adyen Webhook Filtering](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#adyen-webhook-filtering-for-shared-merchant-accounts). |
| Third Party Provider (DIY)    | You must advertise handlers on the business profile and authorize in `sfcc.app.ucp.payment.authorize`. Any PSP flow that assumes a shopper browser (for example a client-created payment intent) must be rewritten to complete server-side. See [Third-Party Payment Providers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#third-party-payment-providers).          |

Google Pay is the payment method the native Salesforce Payments handler advertises. DIY merchants supply their own handlers; Google as a platform still expects Google Pay today.

## Headless Side Effects

Because no storefront controller runs, work that today happens "after place order" in the storefront can be missing:

| If you do this on the storefront today                     | What to plan for UCP                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Send the order confirmation email from a controller        | Salesforce Payments can use `dw.extensions.payments.sendOrderConfirmationEmail`. DIY merchants can send it from `complete.afterPOST` (the order is already placed) or from a job. See [Post-Placement Actions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#post-placement-actions). |
| Export the order to an OMS from a controller               | Same: hook or job. Salesforce OMS and a [third-party OMS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/commerce-apps/connect-third-party-oms.md) are optional. Use one of them if you want lifecycle events on the platform. See [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md).                                                                                                              |
| Offer store pickup                                         | Filter pickup methods in `modifyResponse` hooks if the platform doesn't show them. See [Filtering Store Pickup](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#filtering-store-pickup-fulfillment-methods).                                                                            |
| Handoff to the storefront (age checks, complex promotions) | Configure Continue URL. Without a storefront plugin, the buyer can land with an empty cart. See [Continue URL](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md#continue-url-limitations).                                                                                                               |

## Next Steps

1. Close the gaps you found—[Implementation Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md) for hooks and samples, [Transaction Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-transaction-management.md) before you put callouts or `Transaction.wrap()` in complete-flow hooks.
2. Enable UCP and publish the business profile—[Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md).
3. Create a SLAS private client for Checkout Session APIs—[Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md).
4. If you are transacting with Google, complete [Enabling Google as a Platform](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md).

<!-- document id=1658e731c8975a45686ecde8b906ab1928cb61e9d61ce60d4b592175cacf9974 url=/developer/current/en-us/commerce-cloud/commerce-vibes/guides/cv-telemetry.md -->

# Telemetry in Agentforce Commerce Vibes

Agentforce Commerce Vibes collects anonymized usage telemetry, including extension lifecycle events, feature usage, and error rates, to improve the product. No source code, file contents, workspace paths, environment variables, or personally identifiable information is included. Telemetry follows the [Salesforce Privacy Policy](https://www.salesforce.com/company/privacy/).

To opt out, add this configuration to your VS Code `settings.json` file:

```json
{
  "telemetry.telemetryLevel": "off"
}
```

This configuration is a user-level setting and applies to all your VS Code workspaces.

<!-- document id=b674a53563987c301157107c340fcbd463f2a80ae1ff778c1b4e93445da5dfce url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/template-extensibility.md -->

# Template Extensibility

Template extensibility is a feature introduced in [PWA Kit v3](https://github.com/SalesforceCommerceCloud/pwa-kit/releases/tag/v3.0.0). The goal of this feature is to empower you to build PWA Kit projects more easily by customizing templates. You can customize existing base templates, such as the Retail React App, or you can [create your own](#create-a-base-template). We encourage members of the PWA Kit community to share their base templates with each other.

Template extensibility helps you modify a chosen template without having to duplicate every file within it.

**note:** Template extensibility is an optional feature. However, new projects generated after June 15, 2023 are automatically configured to use template extensibility.

## How It Works

In PWA Kit v3, a project can have a base template and an overrides directory, both of which can be configured in the project’s `package.json` file. To use template extensibility, you must declare a base template with `ccExtensibility.extends` in `package.json` and you must declare an overrides directory with `ccExtensibility.overridesDir`. (Configuration details are covered in the next section.)

A base template is an npm module that contains a fully functional PWA Kit project that has been preconfigured so that another PWA Kit project can override some of its files. Sometimes a base template is also called an "extensible app" or an "extendable app."

The overrides directory is a directory within your project where you can store files that override corresponding files in the base template.

Assume that you've already defined an override directory and defined the Retail React App as your base template. Let's say that you want to override the home page component of the Retail React App. In the Retail React App, the code for the home page component is in `app/pages/home/index.jsx` within the `@salesforce/retail-react-app` package. To override that file, you must recreate that same file in the directory declared via `ccExtensibility.overridesDir` in `package.json`. Therefore, the path for the new file is `<ccExtensibility.overridesDir>/app/pages/home/index.jsx`.

Now, whenever `index.jsx` is imported into any of the files within the `@salesforce/retail-react-app` package, the file in the overrides directory is loaded instead of the file in the package. Only the base of the filename needs to be the same for the override to happen. The file extensions can be different.

As you build your app, you can gradually add files from the base template to your overrides directory.

**warning:** The more files that you override, the more effort is required to keep up with changes in the base template.

To see template extensibility in action, generate a fresh PWA Kit v3 project by running `npx @salesforce/pwa-kit-create-app@latest --outputDir <path/to/new/local/project>`.

The generated project uses Retail React App base template, which gives you an app that looks mostly the same as the one found at https://pwa-kit.mobify-storefront.com/.

## Tutorials

In the template extensibility tutorials you’ll learn how to add some common customizations to your site:

- [Customize a Component](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/create-a-custom-component.md) — component-level extensibility
- [Customize a Page](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/customize-a-page.md) — page-level extensibility

## Configuration

**note:** The instructions in this section assume that you want to enable template extensibility for an existing project that wasn't generated with the feature already enabled.

### Upgrade Your Retail React App Version

To upgrade to the latest version of the Retail React App, run this command:

`npm install @salesforce/retail-react-app@latest`

After running that command, we recommend that you test your site to confirm that it works as expected.

### Define a Base Template

To define a base template, add `@salesforce/retail-react-app` (or a different template) as an npm dependency in your project's `package.json` file.

Then add a `ccExtensibility` key to `package.json` with the following keys and values:

```json
  "ccExtensibility": {
    "extends": "@salesforce/retail-react-app",
    "overridesDir": "overrides"
  }
```

If you’re using a base template other than the Retail React App, don't forget to replace `@salesforce/retail-react-app` with the other template's package identifier.

You can replace the values for `overridesDir` with a custom directory name, but we recommend using `overrides` for the sake of consistency among projects (and our example code).

**warning:** Don’t list the same npm dependencies in both the main project and the base template. Confirm that the dependencies listed in your project's `package.json` are different from those in the base template. This ensures that `@salesforce/pwa-kit-dev` can differentiate between the two in dependency resolution. Define a base template in the main project’s `package.json` as described under [Configuration](#configuration). The main project can’t inherit from itself.

### Version Conflicts

Your project must not have version clashes with the base template's npm dependencies listed in its `package.json` file. If the underlying template uses `@chakra-ui`, your project must also have it as a dependency, and it must be the same version. This precaution prevents accidental bloat in your bundle (not to mention functional breakage) due to conflicting versions of the same package. There is one exception to this rule: When you have added overrides for all of the files in the base template that imports a given dependency. In that case, the base template’s version of the dependency is never imported in your project because you have eliminated all files that import it via overrides.

Adding additional npm dependencies that are not used in the underlying template is just fine. 👌

## Required Project Files

Every PWA Kit project deployed to Managed Runtime must have the following files:

- `<overridesDir>/app/main.jsx`
- `<overridesDir>/app/ssr.js`
- `<overridesDir>/app/routes.jsx`
- `<overridesDir>/app/request-processor.js`
- `config/default.js` (exception: if you are using the `mobify` key in `package.json` to store your site config data)

To customize behaviors in the project, it is common to override these files in `@salesforce/retail-react-app`:

- `app/pages/home/index.jsx`: Removing the default Salesforce marketing content from the home page is a first step almost all projects.
- `app/static/*`: These files are defaults that serve icons used by desktop and mobile browsers to brand your site. Update them to match your brand.
- `app/constants.js`
- `app/assets/svg/brand-logo.svg`: This file is overridden in the generator project. Follow this example to override other icons in your project.

## Imports and Exports

The intent of this "filesystem as an API" setup is to help you find the underlying files, copy them, then customize the behavior and logic. Breaking down code into smaller files that orchestrate many subcomponents makes it easier to target only the behavior that you intend to override.

That being said, you sometimes have to copy a file into your overrides to change only a portion of the behavior of that file. Whenever possible, it's best to import the underlying template exports and re-export them so that changes to the template version don't require manual code updates in your extended project.

For example, in the `routes.jsx` file [in a generated project](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/release-3.0.x/packages/pwa-kit-create-app/assets/bootstrap/js/overrides/app/routes.jsx.hbs), notice that the default routes are imported via `import {routes as _routes} from '@salesforce/retail-react-app/app/routes'` with `_routes` intended as a convention to indicate that these default routes are managed by an external dependency. Just like the file `@salesforce/retail-react-app/app/routes.jsx`, our custom implementation of `routes.jsx` exports routes; it adds a `/` (Home) route. The new route takes precedence over the default route because React Router finds the first item of a given pathname in the routes array.

### Relative Imports

Relative imports are the best approach for most projects that use template extensibility. The import behavior for the files in your base template (for example, `@salesforce/retail-react-app`) has special logic that gives precedence to the file in your overrides directory. This import logic **does not apply** to the files in your overrides directory. Therefore, we recommend using relative imports for most implementations.

### Avoid Importing Conflicting Files

Template extensibility can be complex to think about in terms of the "mental model", but an unexpected "gotcha" that can come up is accidentally importing two different conflicting files. A PWA Kit project is built via `@salesforce/pwa-kit-dev`, which uses [webpack](https://webpack.js.org/) internally. There is a plug-in in `@salesforce/pwa-kit-dev` that enables the "override" functionality of template extensibility. This plug-in inspects all webpack file requests and asks two questions:

1. Does this file request originate in the base template?
2. Does this file exist in the overrides directory?

If the answer to both questions is "yes", the file request is rewritten at build time to point to the file in the overrides directory.

This logic does not come into play for webpack file requests that originate in the overrides directory. As such, it is possible to import **the same file** from both the overrides directory and the base template. If this situation happens with, for example, `@saleforce/retail-react-app/my-file` and `<overrides directory>/my-file` being imported in the same bundle, webpack throws a confusing error along the lines of `can’t find <export name> from <filename>`. Webpack throws this error because the bundle doesn’t know which import is the intended target for bundle inclusion.

It’s important to avoid importing files from the base template when an equivalent file exists in overrides, with **one notable exception**. As covered earlier in the code example in the [Special Files](#special-files) section and demonstrated with `constants.js`, it's better to import the underlying template and re-export all of its exports, overriding or appending as few exports as are needed.

## Global Components

When you need to override the `app/components/_app/index.jsx` component, there are many global components, such as `Header`, `Footer`, and `DrawerMenu`. After the `_app/index.jsx` override is in place, any attempts by the base template to import this component will reroute the file request to `<ccExtensibility.overridesDir>/app/components/_app/index.jsx`. But there’s a catch! Because `Header` and `Footer` are imported by `app/components/_app/index.jsx`, the import must be updated in `_app/index.jsx` too! Otherwise, `_app/index.jsx` imports `Header` and `Footer` from the base template.

**important:** ECMAScript imports originating in `ccExtensibility.extends` are "magical" in that `@salesforce/pwa-kit-dev` checks in multiple places for a file of that name, with `ccExtensibility.overridesDir` taking precedence.

On the other hand, imports originating in `<ccExtensibility.overridesDir>/*` do not have magical behavior, thus you must target the files you mean to, and so `<ccExtensibility.overridesDir>/app/components/header/index.jsx` must be imported explicitly in `<ccExtensibility.overridesDir>/app/components/_app/index.jsx` like this:

```javascript
// <ccExtensibility.overridesDir>/app/components/_app/index.jsx

import Header from "../header";
```

Do not import from the package like this because it bypasses the header in your overrides directory:

```javascript
// <ccExtensibility.overridesDir>/app/components/_app/index.jsx

import Header from "@salesforce/retail-react-app/components/header";
```

## Special Files

Take note that `routes.jsx` is a special file. It forms the "entryPoint," in webpack terminology, for the entire application. If you have anything set up incorrectly in `routes.jsx`, it causes your whole app to fail in the compile phase as the route-based chunking in `pwa-kit-dev` does not resolve properly. For this reason, we include an example of how to properly extend routes properly by mixing imports from the default `@salesforce/retail-react-app/app/routes.jsx` and a local `routes.jsx` in the `overridesDir`.

Because the imports here are at "the top of the tree", if you override these files and then override `footer.jsx`, you must come back to `_app/index.jsx` and modify that import to point to your relative template import.

## Maintain Consistent Exports

A known limitation of the template extensibility system is that, by virtue of magically pulling in, for example `retail-react-app/constants`, anytime the base template (`@salesforce/retail-react-app`) imports this file, it expects the same values to be exported.

**warning:** A file in overrides that fails to export the same ECMAScript exports as its equivalent in the base template can cause unexpected errors like the one below.

Adding a `constants.js` file to your overrides directory like this causes an error:

```javascript
// constants.js
export const CUSTOM_MESSAGE = "CUSTOM MESSAGE";
```

Example error message:

```
WARNING in ../template-retail-react-app/app/components/_app/index.jsx 74:10-40
  export 'CAT_MENU_DEFAULT_ROOT_CATEGORY' (imported as 'CAT_MENU_DEFAULT_ROOT_CATEGORY') was not found in 'retail-react-app/app/constants' (possible exports: CUSTOM_MESSAGE)
@ ../pwa-kit-react-sdk/dist/ssr/browser/main.js 13:34-73
@ ./overrides/app/main.jsx 9:0-82 12:22-27 12:31-52
```

The reason for this error is that `CAT_MENU_DEFAULT_ROOT_CATEGORY` is an expected export in `@salesforce/retail-react-app/components/_app/index.jsx` and in the process of overriding it with the sole export `CUSTOM_MESSAGE` above, your override breaks the underlying "API contract" (the ability of files to depend upon a given value, in this case `CAT_MENU_DEFAULT_ROOT_CATEGORY`) being exported by `constants.js`

The correct approach would be as follows. This approach avoids the omission of `CAT_MENU_DEFAULT_ROOT_CATEGORY` as a required and expected export. Thus we maintain the consistency of the exported API.

This approach only works for additive changes. In the following example, we add a `CUSTOM_MESSAGE` export that is not in the underlying `retail-react-app/constants.js` file’s exports.

```javascript
// constants.js
export * from "retail-react-app/constants";
export const CUSTOM_MESSAGE = "CUSTOM MESSAGE";
```

This approach works for the following scenario, where `DEFAULT_LOCALE` is exported by `retail-react-app/constants`, and we are mutating that value:

```javascript
// constants.js
import {
  DEFAULT_LIMIT_VALUES,
  DEFAULT_SEARCH_PARAMS,
} from "@salesforce/retail-react-app/app/constants";

// original value is 25
DEFAULT_LIMIT_VALUES[0] = 3;
DEFAULT_SEARCH_PARAMS.limit = 3;

export { DEFAULT_LIMIT_VALUES, DEFAULT_SEARCH_PARAMS };

export * from "@salesforce/retail-react-app/app/constants";
```

## Template Hooks

Template hooks are a new way to interact with the Retail React App template that has historically been available via the command `npx pwa-kit-create-app` (now renamed to `npx @salesforce/pwa-kit-create-app`).

As part of the template extensibility feature, new "template hooks" have been added to `@salesforce/retail-react-app` that support global addition of a small subset of components, enumerated in the following list. By default, each of these components return `null` and is intentionally empty in order to avoid adding unneeded bloat to a completed PWA Kit implementation project. The base `@salesforce/retail-react-app` never adds any functionality to these components. Template hooks always return `null` in order to ensure that customer implementations can "hook" into the template in these places to customize the project without having to override more files than necessary.

As of `@salesforce/retail-react-app@1.0.0` the following template hooks are available:

- `app/components/_app/partials/above-header.jsx`
- `app/pages/product-list/partials/above-page-header.jsx`

## Create a Base Template

At the time of PWA Kit v3's release, there is only one extensible base template that is publicly available: `@salesforce/retail-react-app` (more are expected later).

To be used as a base template, a PWA Kit project must be published to npm and all of its ECMAScript imports must be prefixed with a value that matches the package name. For example, `@salesforce/retail-react-app` is published on npm, and its imports are prefixed with `@salesforce/retail-react-app`. This prefix is a reference to the package's root directory, which is necessary for it to work properly as a base template.

To use a PWA Kit project as an extensible base template, it must use `<npm package name>` for all of its imports. For example, `@salesforce/retail-react-app` adds `ccExtensibility` in `package.json`, which ensures that local IDE references (for example, `@salesforce/retail-react-app/app/components/_app`) resolve properly.

## Template Extensibility Best Practices

- Use template extensibility instead of copying the [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.html) template and editing it.
- As you make changes, test your project regularly to identify and fix any issues that come up.
- Test the customized functionality in a non-production environment before deploying it to production.
- Iterate on your overrides as needed to refine the behavior.

## Troubleshoot Template Extensibility

This section provides suggested solutions for common errors that you might encounter while using template extensibility.

### Customizations Don’t Appear on Your Site

After you changed files in your project the updates don’t appear when you preview your site.

**Cause:** You didn’t restart your local server.

**Suggested Solution:** Run `npm start` then preview your site again.

### Configuration Incomplete

This applies only if you’re using a version of PWA Kit older than version 3.

**Cause:** Your `package.json` file is missing the required `ccExtensibility `configuration.

**Suggested Solution:** Complete this [Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html#configuration) in `package.json`.

### Required Project Files Missing

**Cause:** Required files are missing from the the overrides directory (`overridesDir`).

**Suggested Solution:** Ensure that your project includes all the required files in the `overrides `directory. See [Required Project Files](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html#required-project-files).

### Version Conflicts

**Cause:** There are conflicting versions of dependencies between the base template and your project

**Suggested Solution:** Ensure both the base template and your project use the same version of shared dependencies. See [Version Conflicts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html#version-conflicts).

## See Also

- [Retail React App](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/retail-react-app.html)
- [Debug PWA Kit Apps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html)
- [Customization with Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)
- [Custom APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html)

<!-- document id=5f85ab32b188a7b73aea7c377b7acb260792b4f4c82d8fee9ec4c4cdb761f812 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-working-with-templates.md -->

# Templates

B2C Commerce uses ISML templates to generate dynamic storefront pages. Templates combine HTML with a proprietary language extension called Internet Store Markup Language (ISML). An ISML template consists of standard HTML markup, ISML tags, and script expressions. ISML templates are similar to Java Server Pages in that both are used to present dynamically generated web content.

**note:** ISML templates don’t support JSP syntax or directives.

## How Templates Work

Templates convert the result of business processes (for example, product details) into a response that can be returned to the client (for example, a list of product specifications and an image).

1.  The first time a template is requested it's converted into an internal structure for processing.
2.  The Template Processor processes the ISML tags and expressions and parses any attributes and values stored in the Pipeline Dictionary.
3.  The resulting data is added to the output stream and pure, static HTML pages are sent to the browser.

Templates are always triggered by a pipeline. They implement the presentation logic (web design). Cache execution results as an HTML file (page caching).

## Template Files

Templates contain:

- Browser-ready content of web pages
- Special markup tags for handling variables that are looked up in the Pipeline Dictionary on demand for dynamic content
- Other instructional markup tags for processing and information flow
- Style information for formatting the requested page

Templates are stored as `*.isml` files that consist mainly of HTML and ISML code. They’re located in a locale-specific folder under the `/cartridge/templates/` folder, with `/cartridge/templates/default` being the default locale. Each local-specific folder can contain for subdirectories organized around areas of functionality. If you support multiple locales, each locale must have a separate subdirectory under `/templates/`. All templates must be in a subdirectory of the `templates` directory, either the `default` directory or a locale directory, and can't be stored in the `templates` directory itself.

**note:** Each cartridge has its own `templates` directory.

Templates used to show information in the storefront are represented by an interaction node in a pipeline. Information about them also appears in the Properties view. If you want to modify how information is presented in a storefront, edit a template or create one.

## Before Editing or Creating a Template

Before you edit a template, you must define the layout or design of a web page. You must also identify information about the pipeline that uses your template and the data to appear by the template. After you collect this information, modify the template using UX Studio.

### Pipeline Information

This is the information you need about the pipeline that calls a template:

- The name of the pipeline that calls the template
- The name of the template you’re modifying
- The name of the template variables you need to show the data in a template

### Data Information

The interaction between the storefront and the buyer is defined by _input_ and _output_ data delivered by a pipeline.

Input Data:

- Order information
- Shipping information
- UPS built-in gateway integration
- Payment information
- Built-in gateway integration for: Cybersource, Paypal, Verisign, BillMeLater
- Tax information
- Gift certificates|
- Catalog data

Output Data:

- Inventory
- Pricing
- Promotions, coupons, source codes
- Customer profile management
- Customer address book
- Payment preferences
- Order status

Templates either deliver input data or show a pipeline's output data on the browser.

## Template Best Practices

Building a secure custom website with Salesforce B2C Commerce requires paying attention to all areas that are vulnerable to attack and preventing it.

To prevent malicious attacks through content manipulation, make sure that all shown content is encoded.

If a script expression such as `${pdict.ProductSearchResult.searchPhrase}` is used in an ISML template, where the content type is set via the following:

```
<iscontent type="text/html" charset="UTF-8" compact="true">
```

The script result is automatically HTML encoded.

But if the same expression is used in an ISML template that is included via `<isinclude template="">` and no content type is set in the included ISML snippet, the content type _text/plain_ is assumed and no HTML encoding takes place. This inconsistency can lead to XSS problems.

To correct this situation, you must explicitly set the content type or use `<isprint value="{}"/>` to make sure the resulting HTML is encoded.

### Setting the Content Type

To make sure that a script expression is HTML encoded, you must set the included page's content type to _text/html_ via the following statement:

```
<iscontent type="text/html" charset="UTF-8" compact="true">
```

**note:** If you include pages, make sure you set the content type, as described.

Using `<isprint>`

In SiteGenesis, we’ve addressed this problem by using the `<isprint>` element instead of merely using the following:

```
${pdict.ProductSearchResult.searchPhrase}
```

The `<isprint>` element ensures that special characters are HTML encoded.

For example:

```
<isprint value="${pdict.ProductSearchResult.searchPhrase}"/>
```

Results in:

```
&#39;;alert&#40;&#39;hallo welt!&#39;&#41;;x=&#39;
```

This notation avoids cross-side scripting attacks, because the alert() function is obfuscated for the browser.

**note:** Check all areas in your code where `${pdict.ProductSearchResult.searchPhrase}` is used and add the `<isprint>` function, as described.

### Example - searchresultheader.isml

In a customized `searchresultheader.isml` template, use the following:

```html
<span class="term"
  >"
  <isif condition="${!empty(pdict.ProductSearchResult.searchPhrase)}">
    <isprint value="${pdict.ProductSearchResult.searchPhrase}" />
  </isif>
</span>
```

Instead of this:

```html
<span class="term">
  "${!empty(pdict.ProductSearchResult.searchPhrase)?pdict.ProductSearchResult.searchPhrase:''}"
</span>
```

## Page Content from Templates

Templates let you separate page content into static and dynamic.

| Page Content | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Static       | Web page elements such as HTML headings and text, images called with HTML tags, and any other part of the page that is unaffected by the ISML conversion process, are considered static content.                                                                                                                                                                                                                                    |
| Dynamic      | When ISML tags call variables to generate a specific list at run time (for example, a list of products), they look up object properties in the Pipeline Dictionary to present product details or other session-dependent data _dynamically._ This is called _dynamic content._ URLs are another example of dynamic content. The system parses this information at run time to compose content that changes from session to session. |

Certain ISML tags facilitate dynamic and conditional page generation.

| ISML Tag       | Used to...                                                                                                                                                                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `<iscontent>`  | Set up the content type.                                                                                                                                                                                                                                                                                                             |
| `<isdecorate>` | Decorate the enclosed content with the contents of the specified _decorator_ template.                                                                                                                                                                                                                                               |
| `<isinclude>`  | Enable content inclusion from an additional source. Allows for the inclusion of content from an additional source to a template. Either from another template file (local include, or by executing a second pipeline that returns the information (remote include)                                                                   |
| `<ismodule>`   | Build units of reusable template functionality that are inserted into the template using custom ISML tags. When `<ismodule>` specifies a template, the specified template is included and user-defined attributes and custom ISML tags are accessible. See [ismodule element](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/isml/b2c-ismodule.md) for examples of isml modules. |

## Page Caching in Templates

Page caching is when pages (or parts of pages) are stored for immediate browser display, without having to call the server.

The nature of the Internet is that a page is served to the browser, then the connection to the server is dropped.

Design a site that caches portions of pages for data that doesn't change frequently or is generic (not dependent on who is viewing the page). By caching portions of pages, merchants can manage the customer experience, while satisfying business requirements related to timely data changes such as pricing and promotions.

**note:** Pipeline caching is site-based. If you turn off _pipeline caching,_ you turn it off for all pipelines for that site.

### B2C Commerce Web Server Page Caching

B2C Commerce uses the B2C Commerce Web Server to perform page caching.

1.  A browser client makes a request to the B2C Commerce Web Server. Because the page isn't in the cache, the request is dispatched to the Application Server.
2.  The Application Server returns the page to the B2C Commerce Web Server. The B2C Commerce Web Server caches the page and returns the page to client.
3.  The client makes a request to the B2C Commerce Web Server for the same page.
4.  B2C Commerce Web Server finds the page in the cache and delivers it to the client.

![Diagram of the B2C Commerce Web Server page caching flow showing a browser request being served from cache on subsequent visits](https://developer.salesforce.com/media/b2c-commerce/b2c_page_caching.gif)

### Cacheable vs. Dynamic Requests

All the data served to a browser doesn't have to be present each time a button is clicked or an entry made in a field. Some content (often, most of it) can be cached for immediate redisplay. Web page elements such as HTML headings and text, images called with HTML tags, and any other part of the page that is unlikely to change, can be cached. This content is considered static.

By contrast, when ISML tags call variables to generate a specific list at run time (for example, a list of products), they look up object properties in the Pipeline Dictionary to present product details or other session-dependent data on-the-fly. This content is dynamic in that it changes each time a request is made from the browser.

URLs are also dynamic because the system uses them at run time to compose content that changes from session to session.

### Implementing Page Caching

Enable page caching in Business Manager; and use the `<iscache>`ISML tag within a template to control what parts of a page are cached and for how long.

## Templates and the Pipeline Dictionary

When a controller or a pipeline is processed, the Pipeline Dictionary accepts and stores parameters in key-value pairs. A template can show only the dynamic information that is stored in the Pipeline Dictionary at the time the template is called.

The value of a key-value pair stored in the Pipeline Dictionary can be:

- Simple values, stored as strings

  Some key-value pairs are delivered in their simplest form, for example, ProductID = 4569. You could parse the value of the ProductID key and use an `<isprint>` statement in the template to show the product number directly in the storefront, as shown:

```
	<isprint value = "${pdict.ProductID}">
```

- Complex objects, containing more attributes and values

  Many keys have as their value a complex object that acts as a container for many other key-value pairs. However, templates can't show complex objects; they only show simple values, such as strings or numbers. To obtain the values of complex objects' properties, a special notation is used describing the path through the object to the simple property that the template can show.

  The following `<isprint>` statement shows how to show the value of the FirstName variable on the DataSheet form of the Buyer object:

```
	<isprint value = "${pdict.Buyer.dataSheet.firstName}">
```

### Pipeline Dictionary and Controllers

Controllers don’t manipulate the Pipeline Dictionary directly; instead, they construct an object that is passed to a template. This object consists of name-value pairs.

Use the UX Studio debugger to view the contents of the object before it’s passed into a template. Within the template context, the variable `pdict` is used to reference this object.

### Pipeline Dictionary and Pipelets

Information on available key-value pairs in the Pipeline Dictionary can be found in the Properties editor of the pipelet that produces the appropriate key as an output parameter and puts it in the Pipeline Dictionary.

If the value of a key-value pair is a complex object, you must know the name of its attributes that contain the values you want to appear in a template.

- To determine the key-value pair's key attributes

1.  Open UX Studio.
2.  Select the pipelet.
3.  Look in the Properties editor.
4.  Observe the Dictionary Input and Output keys, which are the key-value pairs.

    For example, for _AddGiftCertificateToBasket (bc_api)_ it would be:

| Dictionary | Key                     | Value                                             |
| ---------- | ----------------------- | ------------------------------------------------- |
| Input      | Amount                  | CurrrentForms.giftcert.purchase.​amount.value     |
|            | Basket                  | Basket                                            |
|            | Message                 | CurrrentForms.giftcert.purchase.​message.value    |
|            | ProductListItem         | ProductListItem                                   |
|            | RecipientEmail          | CurrrentForms.giftcert.purchase.​email.​value     |
|            | RecipientName           | CurrrentForms.giftcert.purchase.​recipient.​value |
|            | SenderName              | CurrrentForms.giftcert.purchase.​from.​value      |
|            | Shipment                | Shipment                                          |
| Output     | AddGCErrorMessage       | null                                              |
|            | GiftCertificateLineItem | GiftCertificateLineItem                           |

The available key-value pairs of the selected attribute appear.

## JQuery in ISML Templates

jQuery is frequently used in ISML templates. B2C Commerce supports versions up to and including jQuery 1.3.2.

Avoid using the # character in jQuery or JavaScript because it's reserved in ISML templates and can cause problems.

**note:** Generally, if you follow the best practices of unobtrusive JavaScript and progressive enhancement, you don't mix HTML and JavaScript behavior, so this is unnecessary.

However, there might be cases where you must use the # character. In these cases, instead of the following code:

```javascript
<a id="id-to-select" href="...">...</a>

<script type="text/javascript">
jQuery("#id-to-select").click(function() {
    // Code here
});
</script>
```

Use the following code:

```javascript
<script type="text/javascript">
  jQuery("a[id='id-to-select']").click(function(){" "}
  {
    // Code here
  }
  );
</script>
```

Alternatively, the following notation:

```
<a href="#">Link</a>
```

is correctly written in ISML as

```
<a href="${'#'}">Link</a>
```

## Template Debugging

Determining which template is causing an issue requires knowing the template name. The process of determining the name depends on whether the template is static or dynamic.

| Template type | Where to find information                                                                                                                                                                                                                                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Static        | Check the interaction node properties. The Interaction Template Name property shows the name of the template called by the interaction node. This is the file name of the template you must modify.                                                                                                                                     |
| Dynamic       | The template to be called by an interaction node isn't always hard-coded in the node. Instead, the name can be determined dynamically during run time from the Pipeline Dictionary. Usually, if products and categories are visible, the storefront is using a dynamic template, indicated by a D in the symbol of an interaction node. |

Use the Storefront Toolkit to identify which parts of a page belong to which templates.

<!-- document id=84b8ff3a79facf612b2f1962b27cbef10d7ad4e172fe1de4d553de94719cad1a url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/tender-types-attributes-in-jsonxml.md -->

# Tender Types Attributes in JSON/XML

## Overview

This article lists all available Point of Sale tender types and their respective attributes in JSON/XML files. This can assist in streamlining order and payment mapping.

| **Tender**                              | **Field (JSON)**                                                          |
| --------------------------------------- | ------------------------------------------------------------------------- |
| Credit_card_payment: Visa               | paymentMethod: CreditCard tenders.cardType: visa                          |
| Credit_card_payment: Mastercard         | paymentMethod: CreditCard tenders.cardType: mc                            |
| Credit_card_payment: Amex               | paymentMethod: CreditCard tenders.cardType: amex                          |
| Credit_card_payment: Discover           | paymentMethod: CreditCard tenders.cardType: discover                      |
| Credit_card_payment: Diners             | paymentMethod: CreditCard tenders.cardType: diners                        |
| Debit_card_payment: visa                | paymentMethod: CreditCard tenders.cardType: visa paymentSource: DebitCard |
| Gift_card_payment                       | paymentMethod: GiftCard tenders.cardType: svs                             |
| Miscellaneous_payment (goodwill)        | paymentMethod: Miscellaneous                                              |
| Miscallaneous_payment (deposit)         | paymentMethod: Miscellaneous                                              |
| Split_payment (gift card + credit card) | paymentMethod: GiftCard tenders.cardType: svs                             |
| In_store_paybylink (manual entry)       | paymentMethod: PayByLink tenders.cardType: mc                             |
| In_store_paybylink (Apple Pay)          | paymentMethod: PayByLink tenders.cardType: visa_applepay                  |
| In_store_paybylink (Google Pay)         | paymentMethod: PayByLink tenders.cardType: visa                           |
| Remote_paybylink (manual entry)         | paymentMethod: RemotePayByLink tenders.cardType: mc                       |
| Remote_paybylink (Apple Pay)            | paymentMethod: RemotePayByLink tenders.cardType: visa_applepay            |
| Remote_paybylink (Google Pay)           | paymentMethod: RemotePayByLink tenders.cardType: visa                     |
| Taptopay                                | paymentMethod: creditCard tenders.cardType: visa                          |

<!-- document id=c1fb05754e3526d717f3bb3a1ecd02368123e60a8ab31c80491b87894e3e974a url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/test-launch.md -->

# Test and Launch

Discover the keys to a smooth site launch and make sure shoppers have a positive experience from Day 1. This section contains these guides.

- [Custom Storefront Error Pages](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/site-development/b2c-custom-error-pages.md)
- [Unit Testing](https://trailhead.salesforce.com/content/learn/modules/b2c-build-processes-and-tests-for-technical-architects)
- [Load Testing](https://help.salesforce.com/s/articleView?id=000391214&type=1)
- [Load Testing Checklist](https://help.salesforce.com/s/articleView?id=000391855&type=1)
- [Open a Go Live Ticket](https://help.salesforce.com/s/articleView?id=000391578&type=1)
- [Launch Readiness](https://trailhead.salesforce.com/content/learn/modules/b2c-solution-functional-launch-readiness?trailmix_creator_id=strailhead&trailmix_slug=commerced-cloud-gen-900-introduction-to-commerce-cloud-businessd)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=7ce73977db7e0140f0e8b62e8923efdd1d648ba09885565d60d9ac0f90438405 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/testing-and-operations.md -->

# Test and Validate

Apply UI automation and testing strategies.

## In this section

- [Appium Setup for POS UI Automation Testing](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/appium-setup-for-pos-ui-automation-testing.html)
- [Writing UI Automation Tests for POS](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/writing-ui-automation-tests-for-pos.html)

## See also

- [View App API Logs Report in Point of Sale](https://help.salesforce.com/s/articleView?id=commerce.rt_pos_reports_app_api_logs.htm) in _Salesforce Help_
- [Configure Monitoring for SPIs and Webhooks in Point of Sale CMS](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/spi-webhook-monitoring.html)
- [Monitoring Webhook and SPI Integration Health in Point of Sale](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/monitor-webhook-spi-integration-health.html)

<!-- document id=581a8b0de1249622ef47f7a5bc919b58ccfe1cd0096b9df72755a6137f715bf3 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-storybook-test.md -->

# Test Components in Storybook

Test components in the browser by using stories. View stories and their automated tests in the Storybook component library, or run tests via the command line.

## Create a Snapshot with the Snapshot Test

The snapshot is the base copy of the components, their properties, labels, and behaviors. Tests use the snapshot to compare component changes. If a test fails, it can indicate a regression bug or an intended change. After making component changes or adding new components, update the snapshot so it becomes the new base for future tests.

To create a snapshot, run this command.

```
pnpm test-storybook:snapshot
```

To update a snapshot, run this command.

```
pnpm test-storybook:snapshot:update
```

## Run Interaction Tests

An interaction test verifies that a component behaves correctly when a user interacts with it through clicks, typing, and hovers. It simulates these actions within the isolated Storybook environment, often by using the play function and testing library for powerful, reliable component testing.

To run an interaction test in the browser, click a story under a component. The interaction tests for that component run and show the results.

![Storybook Address Card component testing in the browser](https://developer.salesforce.com/docs/media/sfnext/sfnext-storybook-address-card.png '{"class": "image-xl"}')

To run interaction tests via the command line, use this command.

```
pnpm test-storybook:interaction
```

## Run Accessibility Tests

Storybook accessibility tests check for Web Content Accessibility Guidelines (WCAG) violations in a component. They help you catch accessibility issues in a component and report issues like low contrast, missing alt text, and keyboard navigation problems during development. Accessibility tests help make sure that components are usable by everyone, even simulating vision impairments like color blindness.

To run an accessibility test in the browser, click a story under a component. The accessibility tests for that component run and show the results.

To run accessibility tests via the command line, use this command.

```
pnpm test-storybook:a11y
```

## See Also

- [GitHub: Storybook Readme](https://github.com/SalesforceCommerceCloud/storefront-next-template/blob/latest/docs/README-STORYBOOK.md)
- [Build and Test Components with Storybook](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-storybook.md)

<!-- document id=f1058a7488af4cf78f323813ecae95043a06ebe26c14b6cede6aee406207f1a8 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/test-launch-monitor.md -->

# Test, Launch, and Monitor

Discover the keys to a smooth site launch and ensure a positive shopper experience from Day 1. Learn how to monitor key metrics to keep your Progressive Web App (PWA) Kit site running smoothly after launch. This section contains the following guides.

- [Debug PWA Kit Apps](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.md)
- [Launch Your Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.md)
- [Monitor Your Site](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/monitor-site.md)

### See Also

- [Get Started with Composable Storefront](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-developer-workflow.md)
- [Pre-Build and Go-Live Best Practices Checklist](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pwa-best-practices.md)

<!-- document id=1e6093b294cfcaba168de744eac503fee96cb729e1ba68aff1707b2ff7ed2393 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/commerce-apps/testing-validation.md -->

# Testing and Validation

Validate your Commerce App on a sandbox before you ship it. The install, uninstall, multi-site, and storefront loop in this topic is the SI end-to-end path as well as the ISV pre-submission path.

The [Review Checklist](#review-checklist) and [Common Rejection Reasons](#common-rejection-reasons) apply to **registry submission**. Private apps are not reviewed by the registry team; still follow the same quality bar.

## Validating with Claude Code Skills

Before testing on a sandbox, use the Claude Code skills to catch structural issues early:

- `/validate-app` — Comprehensive validation of ZIP structure, manifest, SHA256, IMPEX, icons, and translations
- `/validate-impex` — Deep validation of IMPEX XML files for syntax, missing `mode="delete"` on uninstall, naming conventions, and install/uninstall pairing

These skills catch the most common structural issues before you install or submit.

## Testing Your App

Thoroughly test your Commerce App on a sandbox environment:

### Installation and Uninstallation

- Install via CLI (`b2c cap install`) to simulate the full installation flow
- Use `b2c cap list --site-id <site-id>` to confirm the app appears as installed on the target site
- Use `b2c cap tasks <app-name> --site-id <site-id>` to verify configuration task status
- Verify all configuration tasks complete correctly in Business Manager
- Verify cartridges appear in the site's cartridge path after installation
- Verify every prerequisite feature toggle is enabled and the app's hooks execute. Installation doesn't enable prerequisite toggles automatically.
- Test uninstall and verify clean removal: cartridges removed from path, IMPEX cleanup (services, custom objects)
- Test re-install after uninstall to verify idempotency

### Multi-Site Testing

- Install the app on two different sites within the same realm
- Uninstall from one site and verify the other site is unaffected (cartridge files remain and hooks continue to execute)
- Uninstall from the last site and verify full cleanup occurs (cartridge files are deleted and uninstall IMPEX runs)

### Functional Testing

- Test the end-to-end shopper flow on the Storefront Next storefront
- For backend-only apps (extension points): test with realistic data, error conditions, and edge cases specific to your domain
- For fullstack apps (custom SCAPI): verify that your components render correctly with data from your SCAPI
- For UI-only and fullstack apps (Storefront Next extensions): test component rendering across all targeted surfaces, responsive behavior, and accessibility
- Test on a replicated Production-like instance to validate code and data replication

## Review Checklist

For apps submitted to the App Registry, your app is validated against these criteria during review. Private apps skip registry review but should meet the same bar:

### Functional requirements

- The app does what it claims to do across all documented features
- Extension point implementations return valid responses for all contract methods
- Error states are handled gracefully (timeouts, service unavailability, bad data)

### Packaging requirements

- CAP structure conforms to the specification (see [Architecture Overview](/docs/commerce/b2c-commerce/guide/architecture.md#commerce-app-package-cap-structure))
- All required files are present and valid
- IMPEX data is well-formed and uses proper site-scoped patterns
- No hardcoded site IDs, instance URLs, or credentials in code or IMPEX

### Security requirements

- No exposed credentials or secrets in code or configuration files
- Proper use of service credentials for external API calls
- Input validation on all user-supplied data
- Output encoding to prevent XSS in UI components

### Performance requirements

- Extension point implementations respond within acceptable timeouts
- UI components render efficiently without blocking the main thread
- No excessive API calls or data fetching

### Documentation requirements

- README.md provides clear installation and configuration instructions
- All configuration options are documented
- Known limitations are disclosed

## Common Rejection Reasons

Known areas of attention:

- Hardcoded credentials or site-specific values in IMPEX files
- Missing uninstall IMPEX (cleanup must be as thorough as installation)
- Extension point implementations that don't handle error cases
- Storefront components that break the merchant's existing layout or styling

<!-- document id=2bdcb7a2ca166d73ddbf95a4a2f2f63294d35b92b1f2001899fa22c37708bcab url=/developer/current/en-us/commerce-cloud/commerce-api/guides/why-use-scapi.md -->

# The Advantages of SCAPI

SCAPI represents a cloud-native, headless-first evolution that modernizes how developers build and customers experience commerce.

The transition to SCAPI is more than a version update; it is a foundational shift in how Salesforce Commerce Cloud enables digital interactions. SCAPI is architected as a set of RESTful APIs designed for high-scale, customer-facing storefronts, merchant tools, and complex backend integrations. Unlike its predecessor, which often relied on session-based state and heavy server-side processing, SCAPI is built on a stateless foundation that prioritizes response times and platform stability.

SCAPI does not simply plumb systems together; it is more about transforming our feature rich and scalable commerce engine into an autonomous, data-driven "brain" for your enterprise by utilizing Einstein and Data-Cloud. Salesforce Commerce API provides a level of global stability and scalability that our customers ask for to be successful in their business.

## Architectural Differences of SCAPI's Multi-Service Capabilities

| Feature                     | SCAPI (Modern)                                                                                                          | OCAPI (Legacy - deprecated)                                                                                     |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| **Infrastructure**          | Multi-service: Decoupled architecture using a CDN Gateway for AuthN/Z and routing, offloading processing from services. | ECOM-centric: Runs on the application tier, competing with Business Manager and storefront logic for resources. |
| **Scalability/Performance** | Highly scalable due to Web-Tier Caching. 40-50% of requests are served from web cache.                                  | Higher overhead; every request hits the application server.                                                     |
| **Authentication**          | Standard OAuth2 (SLAS): Modern JWT-based auth with refresh tokens for Shopper APIs.                                     | Proprietary Shopper AuthN; no native refresh token support.                                                     |

## Future-Proofing: Innovation vs. Maintenance

Salesforce Commerce has pivoted its entire development focus to SCAPI:

- **AI & Composable First**: Future platform innovations, including AI-powered "Agentic Merchandising" (planned for 2026) and the Composable Storefront, are built natively on SCAPI.
- **Versioning Policy**: SCAPI uses a Forward Compatibility policy, meaning additive changes (new attributes) do not require a version bump, reducing the "version upgrade" fatigue common with OCAPI's strict policy and hence the potential of breaking changes. In fact SCAPI is running on the same version since the beginning while still being constantly enhanced with new features and updates.
- **Maintenance Mode for OCAPI**: OCAPI is strictly in maintenance-only mode; new features (like AI-assisted updates or OCI integrations) are exclusive to SCAPI.

## Operational Excellence: Scalability & Personalization

For customers and business owners, the shift to SCAPI translates to a more resilient and personalized storefront:

- **Native Personalization**: SCAPI's Shopper Context API's defining technical advantage is its ability to handle complex real-time personalization natively (device type, shopper segment, geolocation, store ID) without the custom hook "hacks" required in OCAPI.
- **Traffic Resilience**: SCAPI features Load Shedding (for ECOM endpoints) and Rate Limiting (for non-ECOM endpoints) to protect the backend during high-traffic peaks. OCAPI does not support anything like this.
- **Hybrid Power**: The new Hybrid Auth allows seamless session syncing between legacy SFRA/SiteGenesis pages and modern PWA storefronts, preventing "lost baskets" during transitions.
- **Future-Proof Capabilities**: All Salesforce Commerce Cloud innovation is focused on SCAPI.

## Modern Developer Experience (DX): Faster & Standardized

SCAPI is built to reduce the "friction" common in OCAPI development:

- **Standards-Based**: Uses OpenAPI Spec (OAS3), standard OAuth2 and standard error formats, allowing developers to use industry-standard tools instead of proprietary Salesforce protocols.
- **Enhanced SDKs**: Provides modern JavaScript SDKs (isomorphic-sdk, commerce-sdk) that streamline integration with React/Next.js frameworks like sf.next our next generation composable storefront.
- **Custom Extensibility**: Unlike OCAPI, SCAPI supports Custom APIs (based on OAS3), allowing developers to expose custom script logic as first-class REST endpoints with built-in auth. Because Custom APIs are integrated into the SCAPI gateway, they benefit from native eCDN layer validation, server-side caching, and circuit-breaking mechanisms that protect the backend from runaway processes. It is highly regarded by partners and customers as a fully fledged customization capability to fulfill customer specific process requirements, rather than being a gap filler only.
- **Frictionless Engineering**: The new B2C commerce CLI provides over 200 commands that replace tedious, manual Business Manager tasks. It not only uses SCAPI capabilities to discover SCAPI endpoints easily, it also helps with instant Code Generation, ie for custom APIs and Hooks.
- **Debugging & Observability**: Offers Verbose Logging, external correlation IDs, and real-time metrics via LogCenter, which are often missing or limited in OCAPI. End to end tracking and tracing from Frontend, via SCAPI to the commerce cloud backend provides full request insights.

## Migrate to SCAPI: The Modern Standard for B2C Commerce

Open Commerce API (OCAPI) has been in the platform since 2014 and is used by many customers on the B2C Commerce platform. B2C Commerce API (SCAPI) was introduced in 2020 as a new API infrastructure built for headless commerce.

**important:** OCAPI is marked deprecated as of April 2026. The provisions described in our versioning and deprecation policy fully apply. To ensure continued support, security, and access to new features, Salesforce customers should migrate existing implementations to SCAPI.

Our emphasis on headless commerce and our Composable Storefront drives a need for superior APIs and channeling our efforts into SCAPI. New endpoints and features are being added regularly to SCAPI only.

### Transition Guidance

- **New Projects**: All new implementations must use SCAPI exclusively.
- **Existing Projects**: If you are currently using OCAPI, you must begin planning your migration to SCAPI.
- **Note**: Per the [OCAPI versioning and deprecation policy](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/versioninganddeprecationpolicy.html), Salesforce isn't establishing an end-of-life (EOL) date to retire OCAPI. This decision is subject to annual review. Salesforce sets any designated EOL date no earlier than two years from the date it formally decides to retire OCAPI. Until then, OCAPI receives bug fixes and security updates where applicable, and no further innovations.
- **Hybrid Transition**: During your migration, use the Shopper Login and API Access Service (SLAS) to bridge both API sets. SLAS allows you to use a single authentication token across both OCAPI and SCAPI, enabling a phased, low-risk transition.

### Key Architectural Shifts

When mapping your integration, keep these three structural changes in mind:

#### Authentication: From JWT to SLAS

In OCAPI, you often managed JWTs directly. In SCAPI, SLAS is the mandatory gatekeeper. It provides a standard OAuth2 flow that allows you to share sessions between a headless storefront (PWA Kit) and legacy OCAPI hooks if necessary.

#### Performance: From Response Caching to Object Caching

OCAPI caches the entire API response. If one small piece of data changes, the whole cache is invalidated. SCAPI uses Object-Level Caching. If you request a product, SCAPI caches the product object itself. If a later request asks for that same product as part of a different set, it is pulled from the cache instantly.

#### Personalization: From Hooks to Context

In OCAPI, personalizing a price usually required a "Modify Response" hook (server-side script). In SCAPI, you use the Shopper Context API. You send the shopper's attributes (like "Member Level" or "Region") to the API, and SCAPI returns the correct price or promotion natively without running custom code.

### What is NOT in SCAPI?

As of May 2026, the following items are still best handled via OCAPI:

- **System information**: Low-level server status and maintenance indicators.
- **Complex Data API Tasks**: Certain niche administrative tasks for which an Admin SCAPI service hasn't been released.

We will continue to provide SCAPI functionality for selected use cases for system information and complex Data API tasks.

### Next Steps for Migration

1. **Audit your OCAPI usage**: Identify all endpoints currently in use.
2. **Map to SCAPI**: Use our OCAPI to SCAPI Mapping Reference to find equivalent services.
3. **Implement SLAS**: Switch your authentication layer to SLAS to begin a unified token approach.
4. **Review SDKs**: Leverage the Salesforce Commerce SDK or Commerce SDK React to accelerate your refactoring.

## OCAPI to SCAPI Mapping

| OCAPI Resource                                 | SCAPI Resource                     | Notes                                                                               |
| :--------------------------------------------- | :--------------------------------- | :---------------------------------------------------------------------------------- |
| Shop Baskets                                   | Shopper Baskets V1 / V2            |                                                                                     |
| Shop Categories                                | Shopper Products                   |                                                                                     |
| Shop Content                                   | Shopper Experience                 |                                                                                     |
| Shop ContentSearch                             | Shopper Experience                 |                                                                                     |
| Shop Customers                                 | Shopper Customers                  |                                                                                     |
| Shop CustomObjects                             | Shopper Custom Objects             |                                                                                     |
| Shop Folders                                   | Shopper Experience                 |                                                                                     |
| Shop GiftCertificate                           | Shopper Gift Certificates          |                                                                                     |
| Shop Orders                                    | Shopper Orders                     |                                                                                     |
| Shop OrderSearch                               | Shopper Orders                     |                                                                                     |
| Shop ProductLists                              | Shopper Customers                  |                                                                                     |
| Shop Products                                  | Shopper Products                   |                                                                                     |
| Shop ProductSearch                             | Shopper Search                     |                                                                                     |
| Shop Promotions                                | Shopper Promotions                 |                                                                                     |
| Shop SearchSuggestion                          | Shopper Search                     |                                                                                     |
| Shop Sessions                                  |                                    | Covered by Hybrid Auth                                                              |
| Shop Site                                      | Shopper Configurations             |                                                                                     |
| Shop Stores                                    | Shopper Stores                     |                                                                                     |
|                                                | Shopper Agents                     |                                                                                     |
|                                                | Shopper Consents                   |                                                                                     |
|                                                | Shopper Context                    |                                                                                     |
|                                                | Shopper Login (SLAS)               |                                                                                     |
|                                                | Shopper Login (SLAS) Admin         |                                                                                     |
|                                                | Shopper SEO                        |                                                                                     |
| Data Campaigns                                 | Admin Campaigns                    |                                                                                     |
| Data CampaignSearch                            | Admin Campaigns                    |                                                                                     |
| Data Catalogs                                  | Admin Catalogs                     |                                                                                     |
| Data CatalogSearch                             | Admin Catalogs                     |                                                                                     |
| Data Categories                                | Admin Catalogs                     |                                                                                     |
| Data CategoryProductAssignmentSearch           | Admin Catalogs                     |                                                                                     |
| Data CategorySearch                            | Admin Catalogs                     |                                                                                     |
| Data CodeVersions                              | Admin Scripts                      |                                                                                     |
| Data CouponRedemptionSearch                    | Admin Coupons                      |                                                                                     |
| Data Coupons                                   | Admin Coupons                      |                                                                                     |
| Data CouponSearch                              | Admin Coupons                      |                                                                                     |
| Data CustomerGroups                            | Admin Customers                    |                                                                                     |
| Data CustomerGroupSearch                       | Admin Customers                    |                                                                                     |
| Data CustomerLists                             | Admin Customers                    |                                                                                     |
| Data GiftCertificates                          | Admin Gift Certificates            |                                                                                     |
| Data GiftCertificateSearch                     | Admin Gift Certificates            |                                                                                     |
| Data GlobalPreferences                         | Admin Preferences                  |                                                                                     |
| Data InventoryLists                            | Admin Inventory Lists              |                                                                                     |
| Data InventoryListSearch                       | Admin Inventory Lists              |                                                                                     |
| Data JobExecutionSearch                        | Admin Jobs                         |                                                                                     |
| Data Jobs                                      | Admin Jobs                         |                                                                                     |
| Data Libraries                                 | Admin Experiences                  |                                                                                     |
| Data Metrics                                   |                                    | Replaced by the new distributed tracking and tracing feature, planned for 26.4      |
| Data OcapiConfigs                              |                                    | Not applicable for SCAPI anymore, permission setting done via Scopes in AM and SLAS |
| Data Products                                  | Admin Products                     |                                                                                     |
| Data ProductSearch                             | Admin Products                     |                                                                                     |
| Data PromotionCampaignAssignmentSearch         | Admin Assignments                  |                                                                                     |
| Data Promotions                                | Admin Promotions                   |                                                                                     |
| Data PromotionSearch                           | Admin Promotions                   |                                                                                     |
| Data Roles                                     | Admin Roles                        |                                                                                     |
| Data RoleSearch                                | Admin Roles                        |                                                                                     |
| Data SitePreferences                           | Admin Preferences                  |                                                                                     |
| Data Sites                                     | Admin Sites                        |                                                                                     |
| Data SiteSearch                                | Admin Sites                        |                                                                                     |
| Data SlotConfigurationCampaignAssignmentSearch | Admin Experiences                  |                                                                                     |
| Data SlotConfigurations                        | Admin Experiences                  |                                                                                     |
| Data SlotConfigurationSearch                   | Admin Experiences                  |                                                                                     |
| Data Slots                                     | Admin Experiences                  |                                                                                     |
| Data SlotSearch                                | Admin Experiences                  |                                                                                     |
| Data SourceCodeGroups                          | Admin Source Code Groups           |                                                                                     |
| Data SourceCodeGroupSearch                     | Admin Source Code Groups           |                                                                                     |
| Data Stores                                    | Admin Stores                       |                                                                                     |
| Data StoreSearch                               | Admin Stores                       |                                                                                     |
| Data SystemObjectDefinitions                   | Admin Object Definitions           |                                                                                     |
| Data SystemObjectDefinitionSearch              | Admin Object Definitions           |                                                                                     |
| Data Users                                     | Admin Users                        |                                                                                     |
| Data UserSearch                                | Admin Users                        |                                                                                     |
|                                                | Admin CDN Zones                    |                                                                                     |
|                                                | Admin Commerce Delivery Service    |                                                                                     |
|                                                | Admin CORS                         |                                                                                     |
|                                                | Admin Custom                       |                                                                                     |
|                                                | Admin Orders                       |                                                                                     |
|                                                | Admin Replications                 |                                                                                     |
|                                                | Admin Schemas                      |                                                                                     |
|                                                | Admin Timeouts                     |                                                                                     |
|                                                | Admin SEO                          |                                                                                     |
|                                                | Admin Store Redirect Mappings      |                                                                                     |
|                                                | Admin Inventory Availability (OCI) |                                                                                     |
|                                                | Admin Inventory Impex (OCI)        |                                                                                     |
|                                                | Admin Inventory Reservation (OCI)  |                                                                                     |
|                                                | Admin Price Books                  |                                                                                     |

<!-- document id=b7b32c8fa9d017c777864993640f9e53bc5d96687811b38927810ea9e6b8e2d7 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/scriptprogramming/thescriptingpipeletexplained.md -->

# The Scripting Pipelet

There’s only one scripting pipelet, located in the Scripting folder in the B2C Commerce API. This pipelet executes a Server-Side JavaScript, which might require a database transaction.

The pipelet's configuration parameters are:

| Properties    | Description                                                                           |
| ------------- | ------------------------------------------------------------------------------------- |
| OnError       | Calls PIPELET_ERROR to process the error                                              |
| ScriptFile    | The name of the actual script relative to the script's folder containing the pipeline |
| Timeout       | Timeout in seconds. Default is 30 seconds.                                            |
| Transactional | Selection of false or true                                                            |

## Using ScriptLog

`ScriptLog` is a transient object for retrieving detailed log information during script execution. Use ScriptLog information during development to report any errors.

**note:** Put this object into the Pipeline Dictionary before using it. To add it to the pipeline dictionary, in the script node, under Dictionary Output, add a variable name to the `ScriptLog` property. For example, add `myLog` as the variable name.

Display ScriptLog data in any template with a simple ISML statement.

```
<pre>
<isprint value="${myLog}">
<pre>
```

**note:** To generate persistent log information, use `dw.system.Logger`.

## Using Trace()

Write your own information with the `trace()` function.

Use the following syntax:

```
trace(msg : String, params : Object...)
```

To use the `trace()` command, you must first specify the variable and then show it in a window, as shown here:

```
var res = googlesvc.doGoogleSearch(
...
);
trace( res );
```

This example writes to the ScriptLog output.

<!-- document id=0500065c700dc3cd2c4d0f45d89629fb37d74b37fedf81477b81585d0602ec32 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/third-party/b2c-third-party.md -->

# Third-Party Applications

Integrate third-party applications such as product reviews, geotracking, Facebook, and Google Pay with Salesforce B2C Commerce.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Product Reviews

Integrate a third-party product review application into Salesforce B2C Commerce. The Storefront Reference Architecture (SFRA) includes a product decorator function that you can modify to meet your requirements.

The `rating` function is located in the following SFRA file:

```txt
app_storefront_base/cartridge/models/product/decorators/ratings.js
```

The object property decorator function (value) generates a random rating based on the product ID. Replace the following code with a call to get the rating:

```javascript
object property
        value function
```

## Geotracking

Salesforce B2C Commerce supports geotracking through the IP address customer lookup feature.

Use the `dw.util.Geolocation` class and `dw.system.Request.getGeolocation()` method to populate the `pdict.CurrentRequest.httpRemoteAddress`, then take action based on the associated country.

**note:** If the `dw.system.Request.getGeolocation()` method can't return a geolocation, it returns null. If the IP address can't be found in the database, for example, the method returns null.

The geolocation feature is turned on by default, but Support can disable the feature per customer request.

If the IP address is associated with a country you support with one of your sites, redirect to that site. If the IP address is associated with a country you don’t support with one of your sites, direct to a "site selector" page. The site selector page lets the visitor select a specific site by region. If a visitor explicitly selects a site, consider also offering the option of saving a cookie to remember the selection for subsequent sessions.

On subsequent visits, if a cookie on the browser's computer indicates that the customer has previously selected a preferred site, your app can redirect to that site regardless of the IP address. If you provide cookie-based site preference, it's important to let the visitor change that preference. Present a link to the site selector page in the global user interface of the site. Geotracking can be used to delegate users from specific countries to country-specific landing pages.

Alternatively, check our LINK partners for pre-built integrations with geotracking functionality.

## Apple Pay on the Web

Apple Pay on the Web can help convert mobile shoppers into mobile buyers. Apple Pay decreases friction in an ecommerce transaction, especially on iPhones, iPads, and Macs. Salesforce B2C Commerce supports Apple Pay on the Web Version 1.

Merchants can incorporate the ability to pay using Apple Pay on their storefront. Merchants can determine whether to show the Apple Pay button on their Product Detail Pages, Cart, and mini-Cart. The Apple Pay on the Web feature is enabled by default.

When Apple Pay is enabled on a merchant's storefront, the customer can click the Apple Pay button. Customers then use their iPhones to complete payment, just as they would in the store.

Integrating Apple Pay on a site involves:

- merchant use of B2C Commerce functionality
- engagement with Apple
- use of a participating payment service provider (PSP)

For B2C Commerce merchants, the process of enabling Apple Pay depends on how their PSP enables Apple Pay on the Web. There are two possibilities:

- the PSP uses the B2C Commerce API to implement Apple Pay

  In this case, the merchant configures Apple Pay on the Web in Business Manager.

- the PSP supports Apple Pay on the Web via their LINK cartridge

  In this case, the merchant installs and configures the updated LINK cartridge and provides some configuration information in Business Manager.

### Apple Pay Roles

There are several entities involved in enabling and using Apple Pay on B2C Commerce merchant sites:

- B2C Commerce merchant (merchant)

  If the merchant already uses a supported PSP, they simply configure Apple Pay on the Web in Business Manager.

- Payment Service Provider (PSP)

  B2C Commerce provides the API interface and works directly with key PSPs to enable Apple Pay on the Web. Each PSP determines whether to support this capability and which integration method (standard API or updated cartridge) they wish to support.

- B2C Commerce merchant's customer (shopper)

### Apple Pay on the Web Experience

The shopper's experience depends on what device they’re using:

- iPhone or iPad experience: If the shopper has Apple Pay on their iPhone or iPad, they see the Apple Pay button on the pages where the Merchant has added it. The shopper can then begin the checkout and payment process. The shopper taps the Apple Pay button and confirms the order details (payment, shipping option, totals) in the Apple Pay payment screen. The shopper completes the purchase via Touch ID or passcode.
- Mac experience: To pay using Apple Pay, the shopper must be browsing the site on a 2012 or newer Mac desktop or laptop, running Safari. The shopper must have an iPhone or Apple Watch with Apple Pay setup. While browsing using Safari on their Mac, the shopper clicks the Apple Pay button and confirms the order details in the Apple Pay payment screen. The shopper then uses their iPhone or Apple Watch to complete the purchase via Touch ID or by clicking the side button on their Apple Watch.

**note:** When a shopper clicks the Apple Pay button on a Product Detail Page, the quantity is automatically set to one. To purchase more than one of an item, the shopper adds the items to the cart and follows the standard checkout process for any payment type.

The default order of the shipping methods on the Apple Pay payment sheet shows the currently selected shipping method in the basket first. The currently selected methods are followed by the remaining applicable methods in the same order.

### Apple Pay on the Web Process

To ensure that the transaction is secure, Apple verifies the domain association. The verification occurs one time, although reverification can occur again later. For every payment request, Apple verifies the server source of the request using TLS validation through the session validation key. Apple encrypts the payment data with the encryption key.

The merchant runs any verification they need on the billing address, just as they would for a non-apple Pay transaction. The billing address information can be provided with the payment object as non-encrypted and isn't required for the processing of Apple Pay transactions.

**Process Flow**

1.  Shopper visits the storefront using an Apple Pay on the Web enabled device.
2.  The storefront detects the device and other conditions necessary for Apple Pay and, if all conditions are met, shows the Apple Pay button.
3.  The shopper clicks the Apple Pay button.
4.  The storefront provides the necessary information to Apple Pay.
5.  The shopper checks out using Apple Pay.
6.  The storefront updates the basket with Apple Pay information.
7.  The shopper authorizes payment on their Apple Pay enabled device.
8.  Apple Pay provides the storefront with encrypted payment information.
9.  The storefront makes the authorization request to the PSP.
10. The storefront stores the transaction ID that is in the authorization response from the PSP.
11. The storefront notifies Apple Pay of successful authorization.
12. The storefront shows the order confirmation.
13. The order, including the PSP transaction ID, is exported to the OMS.
14. The OMS sends post order updates to the shopper.

![Apple Pay Sequence Diagram](https://developer.salesforce.com/media/b2c-commerce/b2c_apw_payment_negotiation.gif)

### Enable Apple Pay in Your Storefront

The merchant can use a PSP that has enabled Apple Pay for use on B2C Commerce sites using the Standard Payment API from B2C Commerce. Alternatively, the merchant can use a LINK cartridge to enable Apple Pay for storefronts.

The standardized B2C Commerce and PSP Apple Pay integration model creates a seamless enablement process for B2C Commerce merchants to enable Apple Pay. This approach requires minimal client code customizations or LINK cartridge updates. In Business Manager, the merchant identifies the PSP to use, and the API version, API URL, API username and password, and PSP merchant account ID.

If the site is using a LINK cartridge, to enable customers to pay using Apple, the merchant updates the LINK cartridge for payment.

No matter which method the merchant uses to implement Apple Pay for the Web, the merchant must:

- have at least one storefront in a location where Apple Pay is supported
- register for an Apple Merchant ID

  Apple recommends that merchants who already have a Merchant ID use the same Merchant ID and certificate to support Apple Pay on the web. You enter the merchant ID into Business Manager.

- generate an Apple certificate

  The PSP gives the merchant a certificate request which they upload to the Apple developer portal to generate the certificate.

- configure Apple Pay for the Web in Business Manager

#### Register for an Apple Merchant ID

1.  Log in to developer.apple.com.
2.  Create an Apple Merchant ID.

**note:** When you set up and configure services for your merchant ID, you don't specify the Merchant Domains or Apple Pay Merchant Identity (in the lower portion of the iOS Merchant ID Setting page). However, to register the correct domain name of your site with Apple, make sure that your site's alias file contains the alias mapping for your https URL in the settings section. For details about Apple Merchant IDs, browse to https://developer.apple.com/support/apple-pay-domain-verification/.

#### Generate an Apple Payment Processing Certificate

1.  Obtain a CSR (certificate signing request) file from your PSP.
2.  Use this CSR to generate a certificate through Apple.

    For details, browse to https://developer.apple.com/support/apple-pay-domain-verification/.

3.  Upload the certificate back to your PSP.

#### Configure Apple Pay on the Web in Business Manager

To enable Apple Pay for use on B2C Commerce sites using the Standard Payment API from B2C Commerce, the merchant must configure Apple Pay in Business Manager.

### Configure Apple Pay on the Web in Business Manager

You must enable the Apple Pay on the Web feature in Business Manager. Delete the configuration later if needed. Configuration information is deleted only for the instance type currently selected in the dropdown and not others.

Make sure that host name aliases are configured properly, as detailed in [Hostname Aliases](https://help.salesforce.com/s/articleView?id=cc.b2c_hostname_aliases.htm).

**note:** You don't need to manually register your merchant domain on Apple's developer account portal. Registration is handled by the B2C Commerce. Start testing on your sandbox instance (no need to use staging or development instance) using iOS 10 and macOS Sierra. Also, use the Register Apple Sandbox button on your Apple Pay Business Manager screen.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Site Preferences** > **Apple Pay**.

2.  Select the environment that you want to configure (Production, Staging, Development).

3.  Check **Apple Pay Enabled?.**

4.  Enter your _Apple Pay Merchant ID_ that you created or that you already use for Apple Pay.

5.  Enter your _Apple Merchant Name_, which appears on the payment sheet.

    This value is the brand name you would like to appear on the payment sheet.

6.  Enter the _Country Code_ for the locale of your site.

    The country code is a two letter ISO 3166 country code.

7.  For Merchant Capabilities, check 3DS and leave other fields unchecked.

8.  Select the types of payment you support.

    The payment types are sent to Apple Pay on button click and accepted by the sheet as valid payment types. Shoppers can submit a payment only with a card in one of the accepted payment types. It's up to the PSP what types are supported.

9.  Select the **Supported Networks**.

    The networks are sent to Apple Pay on button click and accepted by the sheet as valid payment networks. Shoppers can submit a payment only with a card in one of the accepted payment networks (Discover, Visa, or other network). It’s up to the PSP what networks are supported.

10. Select the **Required Shipping Address Fields** that are required on the shipping forms.

11. For the **Required Billing Address Fields** select Name and Postal Address.

12. Turn on the Apple Pay Payment API.

13. Check whether to place the Apple Pay button on the cart and mini-cart pages.

14. Select whether to enable automatic redirect of product detail pages to HTTPS.

    Because pages where the Apple Pay button appears must be served via HTTPS, it might be necessary to redirect certain pages on your site. Only pages that don't contain "sc.html" in the URL can be redirected using HTTPS redirection. Because of this, enabling HTTPS redirection might not result in the Apple Pay button appearing on all the pages you expect it should.

15. Specify **Payment Provider URL**.

16. Specify **Payment Provider Merchant ID**.

17. The API Version is v1.

    This version is the version of the B2C Commerce Apple Pay PSP API that is specified by Salesforce and implemented by PSPs. In addition, there’s the Apple Pay JS API provided by Apple in Safari. B2C Commerce supports only version 1, not the later versions that Apple has made available.

18. If you’re using Cybersource, leave **Use Basic Authorization?** unchecked. However, if you’re using World Pay or Adyen, check **Use Basic Authorization?**.

19. If you checked **Use Basic Authorization**, enter the username and password for the merchant issued by the payment provider.

20. Enter the identifier for the merchant issued by the payment provider.

21. If you’re using Cybersource, for **Use JWS?** Check Yes. If you’re using World Pay or Adyen don't check Yes.

22. If you checked Yes for **Use JWS?**, for **JWS Private Key Alias** enter the merchant’s _.p12 Key Alias_. The private key alias is created when a merchant uploads their .p12 key file to Business Manager Module, Private Keys and Certificates. This private key can be obtained by going to Cybersource Business Center -> Account Management -> Transaction Security Keys -> Security Keys for Simple Order API.

23. Click **Submit**.

    After you click Submit, a domain name appears in the Registration section. If you don't have an alias registered, a domain similar to one of the following appears:

    - staging-merchant.\<domain>
    - production-merchant.\<domain>
      If you do have an alias registered, the domain is something like mystore.com.

24. Register with the Apple sandbox or the Apple production server.

    You need just one merchant ID to register with both servers. If your domain is registered with the Apple sandbox, the only device that can make payments on that domain is a device that is signed in to an i[Cloud Sandbox Tester Account](https://developer.apple.com/library/content/documentation/LanguagesUtilities/Conceptual/iTunesConnect-Guide/Chapters/SettingUpUserAccounts.html); if your domain is registered with the Apple production server, any regular iCloud account can pay on that site. If you configure HTTPS, the HTTPS host name is used instead of the instance domain name. If you have multiple domain names for your site, register them; contact Commerce Cloud Support for details.

    Apple lets multiple domains be registered for the same Apple merchant ID. To register multiple domains, set the HTTPS URL, register it with Apple Pay, and repeat for any number of domains. When registration is complete, remove the HTTPS URL from the Aliases screen

### Apple Pay Button Injection

Use several different methods to inject the Apple Pay button into the storefront.

The Apple Pay button can be either:

- automatically injected in the storefront via configuration

  When the shopper's browser supports Apple Pay and there’s a place in the page for a button to be injected, Salesforce B2C Commerce determines if it's appropriate to inject the button. If so, iB2C Commerce inserts the Apple Pay button on the page.

- injected manually by a storefront developer

  B2C Commerce supports customization of the storefront presentation of the controls to initiate payment via Apple Pay. This customization includes not only where the button appears, but also how the button should look, and if a product is to be added to the basket before checkout commences.

  The Apple Pay button is injected when:

  - The browser supports Apple Pay payment
  - The page contains configured places to show an Apple Pay button
  - The customer basket and additional information from the B2C Commerce server indicate that Apple Pay payment is supported
    The Apple Pay button should never be unavailable. The web page should prompt the user to provide the additional information if the user taps the button without completing their input selection. That prompt should guide the user to the part of the form that requires completion. For details, review the Apple Human Interface Guidelines and success stories to design your UI and UX for Apple Pay on the web.

A new tag ( \<isapplepay> ) is added to ISML to inject an Apple Pay control in the HTML page supports optional attributes to:

- add the product to the basket
- specify the look of the button, among possible choices
- specify the ID of the element

The \<isapplepay> tag must have a closing tag.

If there are already items in the shopper's basket and they click the Apple Pay button for an individual product, the items currently in the basket are stored temporarily during the purchase of the individual item; the original items are then restored to the basket.

There are two places where a button can be injected via configuration:

- Cart
- Mini Cart

Each is represented by a CSS selector plus additional information about how to inject. The CSS selectors are based on SiteGenesis DOM and CSS class names, but can work on sites other than SiteGenesis.

If a site is configured to inject, one of these selectors finds a match, and the **SYSTEM**ApplePay-GetRequest pipeline responds with a valid JSON for an ApplePaySession payment request, the button is injected. These buttons check out the current basket (as opposed to buttons to buy a single specific product) so the basket must not be empty to inject the button.

When the **SYSTEM**ApplePay-GetRequest pipeline runs, it retrieves the shopper's current basket. If no basket exists, the pipeline creates a new basket even when the shopper hasn't added any items. This behavior can affect basket metrics.

For Cart, the Apple Pay button is injected after “button[name=dwfrm_cart_checkoutCart]” and its margin and width are copied for Apple Pay UI guidelines reasons. The CSS classes “dw-apple-pay-button” and “dw-apple-pay-cart” are put on the injected button, and (if necessary) a CSS class corresponding to the configured button style.

For MiniCart, B2C Commerce appends “.mini-cart-totals”. Margin, width, or any other attributes aren’t copied. B2C Commerce puts “dw-apple-pay-button” and “dw-apple-pay-mini-cart” plus configured style CSS classes. Not all sites support automatic injection, and sites that do support automatic injection might find they don’t like the way the button is automatically injected. In that case, a customer developer should choose where to inject by using \<isapplepay>\</isapplepay> in their templates.

The process of injecting the Apple Pay button is as follows:

![Injecting Apple Pay Button Sequence Diagram](https://developer.salesforce.com/media/b2c-commerce/b2c_ap_wpayment_processing_authorization.gif)

### Enable Apple Pay on the Web Using a LINK Cartridge

If the merchant enables Apple Pay through a LINK cartridge, the merchant must meet minimum requirements.

The merchant must:

- have a supported iOS device
- create an Apple Developer account
- become a member of the iOS Developer program
- be running Xcode 6.1 or later

  In Xcode, enable Apple Pay under Capabilities in your Project Settings and enable both Apple Merchant IDs.

- update the LINK cartridge

**note:** B2C Commerce currently supports only version 1 of the Apple Pay JS API that is provided by Apple in Safari.

#### Salesforce B2C Commerce Extensions

B2C Commerce provides the constant METHOD_DW_APPLE_PAY to the new Apple Pay system Payment Method.

B2C Commerce provides hooks for payment authorization:

- dw.extensions.applepay.getRequest
- dw.extensions.applepay.prepareBasket
- dw.extensions.applepay.shippingContactSelected
- dw.extensions.applepay.shippingMethodSelected
- dw.extensions.applepay.paymentAuthorized.createOrder
- dw.extensions.applepay.paymentAuthorized.authorizeOrderPayment
- dw.extensions.applepay.paymentAuthorized.placeOrder
- dw.extensions.applepay.paymentAuthorized.failOrder
- dw.extensions.applepay.cancel
- dw.extensions.paymentapi.beforeAuthorization (If not implemented, custom data won't be included in the request or handled in the response as before.)
- dw.extensions.paymentapi.afterAuthorization (If not implemented, custom data won't be included in the request or handled in the response as before.)

**note:** Several Apple Pay hooks can optionally trigger a client-side DOM event after executing. Supported hooks are:

- applepay.prepareBasket
- applepay.shippingContactSelected
- applepay.shippingMethodSelected
- applepay.paymentMethodSelected
- applepay.cancel

**note:** The dw.extensions.applepay.shippingMethodSelected can return a status of INVALID_SHIPPING_ADDRESS. The dw.extension.applepay.paymentAuthorized hook can also return a status of INVALID_SHIPPING_ADDRESS if the street address field is invalid; however, if the name, email, or phone number is invalid, dw.extension.applepay.paymentAuthorized returns INVALID_SHIPPING_CONTACT.

**note:** The cartridge that contains the hook must be in the site cartridge path (not the Business Manager cartridge path).

The API class dw.extensions.applepay.ApplePayHookResult indicates error reasons.

The \<isapplepay> ISML tag injects a default black Apple Pay button into the HTML page.

Use the following CSS class names on pages where Apple Pay for the Web is enabled:

- dw-apple-pay-button
- dw-apple-pay-mini-cart
- dw-apple-pay-cart
- dw-apple-pay-logo-white
- dw-apple-pay-border

#### Testing Your Apple Pay on the Web Implementation

You use the Apple Pay Sandbox to test integration and payment sheet configuration. For more details, see Apple Pay Sandbox Testing (at https://developer.apple.com/support/apple-pay-sandbox/).

### Enable Apple Pay on the Web for PSPs

Salesforce B2C Commerce provides the API interface and works directly with key PSPs to enable Apple Pay. Each PSP determines whether to support this capability.

**important:** Apple Pay PSP API doesn't support split instrument payments or gift certificates. Payment Authorization is always for the full amount of an order.

The PSP sets up an endpoint that can accept the request from B2C Commerce. The B2C Commerce server makes a call to the PSP to enable them to authorize the payment. The PSP puts the request into a format that they can accept, if necessary. The PSP returns the response in the correct format to the B2C Commerce server.

Alternatively, PSPs can update their LINK cartridge.

Each PSP determines which integration method (standard API or updated cartridge) they wish to support.

To handle Apple Pay payments, the merchant sends a request to the PSP. The PSP handles the request, and returns a response and an HTTPS status.

#### Apple Pay Request

In the request for authorization from the PSP, the following is passed. For Apple Pay, the merchant should request only the fields that are required to process the transaction.

**note:** The addition of properties to the available properties doesn't require you to update your implementation of Apple Pay on the Web. However, if there are changes to any existing properties you must update your Apple Pay on the Web implementation.

| Property                      | Type                  | Required | Notes                        | Description                                        | B2C Commerce Mapping                                                   | Apple Mapping                                                                                                                             |
| ----------------------------- | --------------------- | -------- | ---------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| \_v                           | string enumeration    | required | Only "1" currently supported | B2C Commerce request document version number       |                                                                        |                                                                                                                                           |
| merchant_account_id           | string                | required | 256 characters maximum       | PSP merchant account identifier                    | configuration data                                                     |                                                                                                                                           |
| session_id                    | string                | required | 256 characters maximum       | B2C Commerce unique shopper session ID             | session.sessionID                                                      |                                                                                                                                           |
| order_no                      | string                | required | 256 characters maximum       | B2C Commerce storefront order number               | order.orderNo                                                          |                                                                                                                                           |
| payment.payment_id            | hex encoded string    | required | 28 characters maximum        | B2C Commerce unique payment ID                     | paymentTransaction.UUID                                                |                                                                                                                                           |
| payment.type                  | string enumeration    | required |                              | The type of payment to authorize                   | "ApplePay" for Apple Pay transactions                                  |                                                                                                                                           |
| payment.amount                | number                | required | between 1 and 999999999999   | Amount to auth in cents or equivalent minor unit   | paymentTransaction.amount.value \* 10 ^ currency.defaultFractionDigits | PaymentRequest.total.amount                                                                                                               |
| payment.currency              | string                | required | 3 characters                 |                                                    | paymentTransaction.amount.currency                                     | PaymentRequest.currencyCode                                                                                                               |
| payment.token                 | base64 encoded string | required |                              | Apple Pay payment token                            | not stored on B2C Commerce                                             | ApplePayPaymentAuthorizedEvent.payment.token                                                                                              |
| client.ip_address             | string                |          | 40 characters maximum        | IP address of shopper browser                      | request.httpRemoteAddress                                              |                                                                                                                                           |
| client.user_agent             | string                |          | 2000 characters maximum      | User agent of shopper browser                      | request.httpUserAgent                                                  |                                                                                                                                           |
| client.accept_header          | string                |          | 2000 characters maximum      | Accept header of shopper browser                   | request.httpHeaders.accept                                             |                                                                                                                                           |
| customer_info.customer_no     | string                |          | 256 characters maximum       | B2C Commerce shopper customer number               | order.customerNo                                                       |                                                                                                                                           |
| customer_info.email           | string                |          | 256 characters maximum       | B2C Commerce shopper email address                 | order.customerEmail                                                    | ApplePayPaymentAuthorizedEvent.payment.billingContact.emailAddress                                                                        |
| customer_info.customer_name   | string                |          | 256 characters maximum       | B2C Commerce shopper name                          | order.customerName                                                     | ApplePayPaymentAuthorizedEvent.payment..billingContact.givenName + " " + ApplePayPaymentAuthorizedEvent.payment.billingContact.familyName |
| shipping_address.first_name   | string                |          | 256 characters maximum       | Apple Pay provided shipping contact name           | order.defaultShipment.shippingAddress.firstName                        | ApplePayPaymentAuthorizedEvent.payment.shippingContact.givenName                                                                          |
| shipping_address.last_name    | string                |          | 256 characters maximum       | Apple Pay provided shipping contact name           | order.defaultShipment.shippingAddress.lastName                         | ApplePayPaymentAuthorizedEvent.payment.shippingContact.familyName                                                                         |
| shipping_address.address1     | string                |          | 256 characters maximum       | Apple Pay provided shipping contact street address | order.defaultShipment.shippingAddress.address1                         | ApplePayPaymentAuthorizedEvent.payment.shippingContact.addressLines[0]                                                                    |
| shipping_address.city         | string                |          | 256 characters maximum       | Apple Pay provided shipping contact city           | order.defaultShipment.shippingAddress.city                             | ApplePayPaymentAuthorizedEvent.payment.shippingContact.locality                                                                           |
| shipping_address.state_code   | string                |          | 256 characters maximum       | Apple Pay provided shipping contact state          | order.defaultShipment.shippingAddress.stateCode                        | ApplePayPaymentAuthorizedEvent.payment.shippingContact.administrativeArea                                                                 |
| shipping_address.postal_code  | string                |          | 256 characters maximum       | Apple Pay provided shipping contact postal code    | order.defaultShipment.shippingAddress.postalCode                       | ApplePayPaymentAuthorizedEvent.payment.shippingContact.postalCode                                                                         |
| shipping_address.country_code | string                |          | 256 characters maximum       | Apple Pay provided shipping contact country        | order.defaultShipment.shippingAddress.countryCode                      | ApplePayPaymentAuthorizedEvent.payment.shippingContact.countryCode                                                                        |
| billing_address.first_name    | string                |          | 256 characters maximum       | Apple Pay provided billing contact name            | order.billingAddress.firstName                                         | ApplePayPaymentAuthorizedEvent.payment.billingContact.givenName                                                                           |
| billing_address.last_name     | string                |          | 256 characters maximum       | Apple Pay provided billing contact name            | order.billing Address.lastName                                         | ApplePayPaymentAuthorizedEventt.payment.billingContact.familyName                                                                         |
| billing_address.address1      | string                |          | 256 characters maximum       | Apple Pay provided billing contact street address  | order.billing Address.address1                                         | ApplePayPaymentAuthorizedEvent.payment.billingContact.addressLines[0]                                                                     |
| billing_address.city          | string                |          | 256 characters maximum       | Apple Pay provided billing contact city            | order.billing Address.city                                             | ApplePayPaymentAuthorizedEvent.payment.billingContact.locality                                                                            |
| billing_address.state_code    | string                |          | 256 characters maximum       | Apple Pay provided billing contact state           | order.billing Address.stateCode                                        | ApplePayPaymentAuthorizedEvent.payment.billingContact.administrativeArea                                                                  |
| billing_address.postal_code   | string                |          | 256 characters maximum       | Apple Pay provided billing contact postal code     | order.billing Address.postalCode                                       | ApplePayPaymentAuthorizedEvent.payment.billingContact.postalCode                                                                          |
| billing_address.country_code  | string                |          | 256 characters maximum       | Apple Pay provided billing contact country         | order.billing Address.countryCode                                      | ApplePayPaymentAuthorizedEvent.payment.billingContact.country                                                                             |

A sample request is as follows:

```javascript
{
    "_v" : "1",
    "merchant_account_id" : "example-merchant-account-id",
    "session_id" : "XyY8azgOHUE47HCz6fSBn3AsepzRXE3RbbZc5E5jsWO_xEymN7DlS4ktBrJPQzBY_nBUwSavMyc0fSWNJzu0SA==",
    "order_no" : "0000001",
    "payment" : {
        "payment_id" : "089e4cd378bff63d9d7bd63f8f",
        "type" : "ApplePay",
        "amount" : 1999,
        "currency" : "USD",
        "token": "c90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ecc90a1cc41f75098afee7d22437479cce29a036ba10452301af65243f57b937ec=="
    },
    "client" : {
        "ip_address" : "127.0.0.1",
        "user_agent" : "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0",
        "accept_header" : "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
    },
    "customer_info" : {
        "customer_no" : "1234567890",
        "email" : "john@doe.com",
        "customer_name" : "John Doe"
    },
    "shipping_address" : {
        "first_name" : "John",
        "last_name" : "Doe",
        "address1" : "5 Wall Street",
        "city" : "Burlington",
        "state_code" : "MA",
        "postal_code" : "12345",
        "country_code" : "US"
    },
    "billing_address" : {
        "first_name" : "John",
        "last_name" : "Doe",
        "address1" : "5 Wall Street",
        "city" : "Burlington",
        "state_code" : "MA",
        "postal_code" : "12345",
        "country_code" : "US"
    },
    "custom" : {
        "avs" : true,
        "fraud" : {
            "profile" : "strict",
            "max_score" : 72,
            "filters" : ["ml", "review"]
        }
    }
}
```

#### Response

The response is as follows:

| Property       | Description                                   | B2C Commerce Mapping             | Notes                                                                                                                |
| -------------- | --------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| \_v            | B2C Commerce response document version number |                                  |                                                                                                                      |
| transaction_id | PSP unique transaction identifier             | paymentTransaction.transactionID |                                                                                                                      |
| status         | Enum of possible logical statuses             | order.paymentStatus              | Possible values are: <ul><li>authorized (HTTP 200)</li><li>refused (HTTP 200)</li><li>error (HTTP not 200)</li></ul> |
| custom         | Contains custom data.                         |
| reason_code    | Enum of possible reasons for status           |                                  | Logged on the B2C Commerce side For "refused" or "error" status                                                      |
| message        | Optional detail message                       |                                  | Logged on the B2C Commerce side                                                                                      |

A sample response for authorization appears as follows:

```json
HTTP 200
{
    "_v" : "1",
    "transaction_id" : "8989127187123781",
    "status" : "authorized"
}
```

A sample response for refusal appears as follows:

```json
HTTP 200
{
    "_v" : "1",
    "transaction_id" : "7123781898912718",
    "status" : "refused",
    "reason_code" : "declined"
}
```

A sample response for an error appears as follows:

```json
HTTP 400
{
    "_v" : "1",
    "status" : "error",
    "reason_code" : "invalid",
    "message" : "Missing required field: payment.token.payment_data"
}
```

A sample response that includes customization appears as follows:

```json
{
  "_v": "1",
  "transaction_id": "8989127187123781",
  "status": "authorized",
  "custom": {
    "auth_code": 1,
    "card_type": "Visa",
    "masked_number": "XXXX-XXXX-XXXX-1111",
    "fraud": {
      "score": 51,
      "status": "REVIEW"
    }
  }
}
```

#### HTTPS Statuses

The HTTPS statuses include:

<table><col /><col /><col /><col /><tbody><tr><td>Status</td><td>Description</td><td>Notes</td><td>Example Cases</td></tr><tr><td>200 OK</td><td>Request handled normally</td><td>Possible statuses are:<ul><li><p>authorized</p></li><li><p>refused</p></li></ul> <p>Omit message property</p></td><td><p>Successful authorization</p> <p>Over credit limit</p> <p>Insufficient funds</p> <p>Fraud suspected</p></td></tr><tr><td>3xx Redirects</td><td>B2C Commerce will follow redirects</td><td>PSP should avoid in practice</td><td>PSP operations need</td></tr><tr><td>400 Bad Request</td><td>Request could not be handled</td><td>Error status only</td><td><p>Malformed document</p> <p>Missing required property, including merchant account identifier</p> <p>Invalid property value</p></td></tr><tr><td>401 Unauthorized</td><td>Request wasn't authorized</td><td>Unauthorized HTTP request, not unauthorized payment</td><td><p>Authorization: Basic header missing</p> <p>Authorization: Basic header not authorized</p></td></tr><tr><td>403 Forbidden</td><td>Credentials aren't permitted access</td><td>Need correct PSP credentials</td><td><p>Authorization: Basic header authorized but not permitted use of this API</p> <p>Merchant account identifier not permitted use of this API</p></td></tr><tr><td>404 Not Found</td><td>Incorrect URL</td><td> </td><td>B2C Commerce bug or configuration error</td></tr><tr><td>405 Method Not Allowed</td><td>Incorrect HTTP method used</td><td>Should always be POST</td><td>B2C Commerce bug</td></tr><tr><td>500 Internal Server Error</td><td>Unknown error on PSP side</td><td>B2C Commerce will retry at least once</td><td>PSP bug</td></tr></tbody></table></sfdocstbl>

#### Reason Codes

| Code             | Status  | Notes                                                         | Apple                                                    |
| ---------------- | ------- | ------------------------------------------------------------- | -------------------------------------------------------- |
| parse            | error   | 400 Bad Request responses                                     |                                                          |
| invalid          | error   | 400 Bad Request responsesInclude message property if possible |                                                          |
| billing_address  | refused | Invalid billing postal address                                | ApplePaySession.STATUS_INVALID_ID_BILLING_POSTAL_ADDRESS |
| shipping_address | refused | Invalid shipping postal address                               | ApplePaySession.STATUS_INVALID_SHIPPING_POSTAL_ADDRESS   |
| shipping_contact | refused | Invalid shipping contact                                      | ApplePaySession.STATUS_INVALID_SHIPPING_CONTACT          |
| pin_required     | refused | PIN required                                                  | ApplePaySession.STATUS_PIN_REQUIRED                      |
| pin_incorrect    | refused | PIN incorrect                                                 | ApplePaySession.STATUS_PIN_INCORRECT                     |
| pin_lockout      | refused | PIN lockout                                                   | ApplePaySession.STATUS_PIN_LOCKOUT                       |
| declined         | refused | All other declined transactions                               | ApplePaySession.STATUS_FAILURE                           |
| fraud            | refused | All fraud related refusals                                    | ApplePaySession.STATUS_FAILURE                           |
| canceled         | refused | All canceled transactions                                     | ApplePaySession.STATUS_FAILURE                           |

### Apple Pay on the Web Payment Authorization

B2C Commerce provides Apple Pay with information about the customer and basket: line items, shipping methods, and stored contact information. When the shopper authorizes payment, Apple Pay provides B2C Commerce with a token containing the encrypted payment information.

B2C Commerce creates an order from the basket, and provides the encrypted payment information to the storefront payment service provider in an authorization request. B2C Commerce updates the order with the transaction information in the authorization response.

B2C Commerce provides Apple Pay with the outcome of the authorization, and if successful, shows the storefront order confirmation page.

To authorize Apple Pay payment:

1.  The shopper clicks or taps the Buy with Apple Pay button.
2.  B2C Commerce creates the payment request.
3.  B2C Commerce creates a merchant session, requested from the B2C Commerce Web Server to Apple.
4.  The session is returned to B2C Commerce and is forwarded with the payment request.
5.  The app shows the Apple Pay sheet.
6.  The shopper uses their Touch ID or passcode.
7.  Payment data is generated.

The Apple Pay payment processing authorization process looks as follows:

![Apple Pay Payment Process Authorization Sequence Diagram](https://developer.salesforce.com/media/b2c-commerce/b2c_ap_wpayment_processing_authorization.gif)

#### Merchant Validation

The following is an example of merchant validation:

```javascript
session.onvalidatemerchant = function (event) {
   var promise = performValidation(event.validationURL0;

   promise,then(function (merchantSession) {
      session.completeMerchantValidation(merchantSession);
});
}
```

1.  A valid merchant DOM event is dispatched to the session.
2.  The event has a validationURL property.
3.  Validation is performed.
4.  Call completeMerchantValidation.

#### Authorize Payment

The following is an example of authorizing payment:

```javascript
session.onpaymentauthorized = function (event) {
  var promise = sendPaymentToken(event.payment.token);

  promise.then(function (success) {
    var status;
    if (success) status - ApplePaySession.STATUS_SUCCESS;
    else (status = ApplePaySession), STATUS_FAILURE;

    session.completePayment(status);
    showConfirmation();
  });
};
```

### Apple Pay on the Web Integration into Salesforce B2C Commerce Processes

Payments made using Apple Pay are processed in the usual manner through a merchant's PSP.

Use of Apple Pay doesn’t change fulfillment or customer service, and the like. The merchant continues to own the relationship with the customer, including all aspects of fulfillment and customer service.

Use of Apple Pay doesn’t change how returns are handled. The merchant’s business handles questions about orders or returns. The PSPs provide all transaction information needed for returns as for all other transactions.

As long as the merchant continues to use the same PSP, no changes are required to the order management system or the payment settlement process.

Existing B2C Commerce storefront capabilities or integrations are used for shipping and tax calculations. If the merchant uses B2C Commerce tax tables, for example, these tables work “out of the box” after enabling Apple Pay.

## Server-Side Activity Tracking for Facebook

Chrome and other major browsers are retiring support for third-party cookies, which negates the effectiveness of the current pixel-based tracking needed for the Facebook Dynamic Ads feature. To address this change, Salesforce now provides server-side activity tracking for Facebook.

**note:** The B2C Commerce server-side activity tracking for Facebook is only applicable to instances that use B2C Commerce to inject the Facebook pixel. B2C Commerce Activity Tracking for Facebook isn’t adaptable to third-party tracking solutions that implement custom events to Facebook. Because custom events implemented by a third-party tracking solutions aren’t know to B2C Commerce, using the b2c commerce server side tracking isn’t a like for like replacement to the third party tracking.

When enabled in Business Manager, server-side activity tracking for Facebook completes the following process.

1.  Collects shopper viewPage, viewProduct, addToCart, and Finish checkout events using the existing Commerce Einstein tracking mechanism.
2.  Transforms the events to the Facebook format.
3.  In real time, sends the events to the Facebook Conversions API.

To enable the server-side activity tracking and use the Facebook Conversion API with your B2C Commerce instance, you must:

- Integrate your instance of B2C Commerce with a Facebook Business Manager account
- Enable Commerce Einstein tracking in your B2C Commerce instance
- Set up server-side tracking for Facebook in Business Manager

**Set Up Server-Side Activity Tracking for Facebook**

If you inject the Facebook pixel using B2C Commerce, set up server-side tracking for Facebook.

**note:** The B2C Commerce server-side activity tracking for Facebook is only applicable to instances that use B2C Commerce to inject the Facebook pixel. B2C Commerce Activity Tracking for Facebook isn’t adaptable to third-party tracking solutions that implement custom events to Facebook. Because custom events implemented by a third-party tracking solutions aren’t known to B2C Commerce, using the b2c commerce server side tracking isn’t a like for like replacement to the third-party tracking.

When server-side activity tracking for Facebook is enabled in Business Manager, B2C Commerce uses the existing Commerce Einstein tracking that collects shopper activities. Commerce Einstein data is converted to the Facebook format and sent server-side to Facebook.

**note:** Before enabling server-side activity tracking, complete the following:

- Create a Facebook Business Manager Account
- Enable Commerce Einstein tracking
- Integrate your B2C Commerce instance with Facebook

1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Site** > **Site Preferences** > **Facebook**.

    The Facebook option is available only after you integrate your B2C Commerce instance with Facebook.

2.  Under Local Configuration, select **Enable Server-side Activity Tracking using Conversions API**.

3.  In Facebook Business Manager, navigate to **Events manager**, select the desired pixel, and click the **Settings tab**.

4.  Under Conversions API, select **Generate access token**, and copy the token.

5.  In Business Manager, navigate to **Merchant Tools** > **Site** > **Site Preferences** > **Facebook**, and paste the token in the Pixel Conversions API Token field.

6.  Click **Submit**.

    **note:** After configuring, data pushed to Facebook is available through your Facebook Business Manager account.

## Facebook and Instagram Catalog Ads Integration

Salesforce B2C Commerce's integration of Facebook Dynamic Ads allows merchants to quickly and easily get started using the Facebook Dynamic Ads product.

Use the B2C Commerce integration to Facebook Dynamic Ads to embed the Facebook Tracking Pixel into your site and generate a daily product catalog feed, which is exported to Facebook. Merchants can then create ads for products, which appear on Facebook. (When you place ads, you place them in Facebook not Business Manager.)

The Facebook Pixel integration to support Dynamic Ads now automatically tracks:

- PageView
- ViewContent
- AddToCart
- Purchase

To take advantage of tracking these events, Facebook must be enabled for your site and Facebook Pixel injection must also be enabled.

**note:** To enable Facebook integration, contact your B2C Commerce Support representative.

To complete integration:

- Business Manager: (done by a user with Admin access to Facebook Business Manager)

  1.  Enable Facebook integration – pixel injection for the specified environment (production)

      **note:** Only one instance of the Facebook pixel is allowed per site. If you previously integrated the pixel, but want to use the Commerce Cloud integration, you must back out the current pixel code. Alternatively, if you want to continue with your existing pixel opt to export only the product catalog to Facebook. Disable Automatically inject Facebook Pixel code in site when you configure the feed in Business Manager.

  2.  Complete the Facebook Business Account settings – You must have access to this information (Facebook Business Account ID, Page ID, Pixel ID. Get this information from the Facebook Business Manager setup.)
  3.  Complete the setup of the Product Feed Configuration, including identifying which products are in the feed

      **note:** You configure Facebook on each instance independently, or use site import or export to copy configuration data from instance to instance. Export and import configuration data of the Facebook integration through site import or export. Customize the feed by performing any necessary post processing using B2C Commerce hooks

- Facebook Business Manager Activity:

  1.  Create a Facebook Business account and accept the Terms and Conditions.

      Create the Facebook Business Account, the Facebook Page, the Facebook Ad Account, and the Facebook Pixel.

  2.  Create retargeting campaigns in Facebook Business Manager.
  3.  Buy Ads for this campaign

### Integrate with Facebook

To integrate with Facebook, create a Facebook Business Manager account and a Facebook page.

1.  Create the Facebook Business Manager account by browsing to [https://business.facebook.com](https://business.facebook.com) and clicking **Create Account**.

2.  Create a Facebook page.

    If you’ve already integrated with Facebook, you might have multiple Facebook "page" objects for which you would like to have one shared Facebook product catalog. However, because a product catalog is owned by a single Facebook page, you have to choose which page to integrate with B2C Commerce.

3.  Make sure the daily product feeds to Facebook contain the merchant’s product catalog and match what is expected by Facebook.

4.  Create a catalog in Facebook.

### Configure Facebook Dynamic Ads

Use B2C Commerce to write catalog feed files in a Facebook supported format. Customize feed exports by using hooks, which you implement in a custom cartridge you create. Typically, products feeds reach Facebook Business Manager within 24 hours.

**note:** Configure at least one product feed to enable Facebook integration; the Run Now button doesn’t appear until you create a feed.

**important:** B2C Commerce injects the Facebook Pixel only if the site is online. If the site is offline or password protected, the Facebook Pixel isn’t injected.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Site Preferences** > **Facebook**.

2.  Check **Enable Integration**.

3.  Enter your site information. Make sure that products that are enabled, online, have both pricing and a Product Image View Type specified to be able to create a product feed.

<table>
<tr><td> Option</td><td>Description</td></tr>
<tr><td><strong>Facebook Business ID</strong></td><td>ID of the Facebook business account, listed as "Business Manager ID" in Facebook Business Manager on the Business Info tab. Create a Facebook Business Manager account at business.facebook.com. You select the Business ID from a list.</td></tr>
<tr><td> <strong>Facebook Page ID</strong></td><td>The ID of the merchant's Facebook page. Provide an existing Facebook page to create a Facebook product catalog in Business Manager. Facebook limitation is one Page ID per Facebook product catalog. Facebook supports multiple product catalogs per page, but only one page per product catalog. You select the Page ID from a list.</td></tr>
<tr><td> <strong>Facebook Pixel ID</strong></td><td>ID of the Facebook Pixel to inject in pages for the site. You create the Pixel ID in Facebook Ads Manager on the Facebook Pixel tab at business.facebook.com. Listed when you click View Pixel Code in Facebook Ads Manager on the Facebook Pixel tab. Facebook limitation is one Pixel ID per Facebook Ads account. You select the Facebook Pixel from the list.</td></tr>
<tr><td> <strong>Automatically inject Facebook Pixel Code in Site</strong></td><td>If you already instrumented your storefront to use a Facebook Pixel, previous to implementing Commerce Cloud Facebook Dynamic Ads integration, and only want to export the product catalog without Commerce Cloud injecting Facebook Pixel code in your storefront then uncheck this option.</td></tr>
<tr><td> <strong>Enable Site Products for Feed by default</strong></td><td>If all products for the site are enabled for Facebook feed, export by default. When unchecked, you explicitly configure which products are enabled for the site. When checked, configure which products are disabled for the site. When checked, products which are disabled explicitly at site level are ignored in the Facebook feed. This flag doesn't override the site specific value for <strong>Facebook Enabled: attribute on product</strong>.</td></tr>
<tr><td> <strong>Product Image View Type</strong></td><td>Both DIS and external images are supported, as long as the product image model is used. Legacy thumbnail or alternative image sources like custom attributes are supported, but require custom code. If you don't enter a view type, or you enter a view type for which products don't have images of that type, those products are without images in the feed. Facebook skips products in the feed that are missing images. Create custom code by writing a hook that sets the desired image for some or all products. Make sure that the type matches the types in the catalog. </td></tr>
<tr><td> <strong>Color Variation Attribute ID</strong></td><td>Both local and shared variation attributes are supported through this configuration; use of two or more variation attributes requires custom code.</td></tr>
<tr><td> <strong>Size Variation Attribute ID</strong></td><td>Both local and shared variation attributes are supported through this configuration; use of two or more variation attributes requires custom code.</td></tr>
<tr><td> <strong>Material Variation Attribute ID</strong></td><td>Both local and shared variation attributes are supported through this configuration; use of two or more variation attributes requires custom code.</td></tr>
<tr><td> <strong>Pattern Variation Attribute ID</strong></td><td>Both local and shared variation attributes are supported through this configuration; use of two or more variation attributes requires custom code.</td></tr>
<tr><td> <strong>Notification Email Address</strong></td><td>Email address to send status of catalog feed.</td></tr>
<tr><td> <strong>Notification Status</strong></td><td>Select the job statuses for which to receive feed job notifications. The choices are error, exception, and success, similar to the notification choices for custom jobs.</td></tr>
<tr><td> <strong>Start Time</strong></td><td>Time of day, in site time zone, to run the Facebook catalog feed export. To run a feed immediately, click <strong>Run Now</strong>. This feature is intended for testing changes to catalog data and custom hook implementations as part of feed development; the button isn't available on Production instances.</td></tr>
<tr><td> <strong>Feed ID</strong></td><td>A name assigned to the feed. It can be anything, and doesn't affect the set up in Facebook in any way. Does _not_ appear after B2C Commerce creates the feed, but is assigned by the user.</td></tr>
<tr><td> <strong>Facebook Product Catalog ID</strong></td><td>Appears after B2C Commerce creates the catalog. Is pulled by B2C Commerce through API calls when creating the feed.</td></tr>
<tr><td> <strong>Facebook Product Feed ID</strong></td><td>Appears after B2C Commerce creates the product feed. Is pulled by B2C Commerce through API calls when creating the feed.</td></tr>
<tr><td> <strong>Country Code</strong></td><td>Two-digit country code where the products in the Facebook product feed for the Facebook product catalog can be sold. There’s only one Facebook page per site. </td></tr>
<tr><td> <strong>Product Link Redirect Action</strong></td><td>Select whether shoppers who click Facebook Dynamic Ads view the product page or add the product to the cart by default. URL parameters added when creating the ad in Facebook are now preserved in the redirect URL. As previously, provide custom links in the Facebook feed to override the default behavior.</td></tr>
<tr><td> <strong>Channel Type</strong></td><td>Select either Facebook Ads or Instagram Commerce.</td></tr></table>

4.  Click **Submit**.

5.  To run a feed immediately, click **Run Now**.

    When you run a feed, Business Manager shows the status of the product feed, including the number of products in the Facebook catalog, and any errors or warnings raised by Facebook for the products in the feed. The errors and warnings include the cause of the problem and how to fix them. Typically, any product with an error isn’t exported. Files with warnings are often exported, but still need attention.

6.  To download the most recent export log file, click **Download Log File**.

7.  To configure a feed:

    1.  Click **+** next to the existing feed tabs.

    2.  Enter the `Feed ID`.

    3.  Select the **Channel Type**, which specifies whether the feed is for use in Facebook or Instagram.

    4.  Enter the `Facebook Product Feed ID`.

    5.  Select the **Country Code**.

    6.  Select the **Product Redirect Action**, which specifies whether to add the product to the cart or show the Product Detail Page when the customer clicks the product link.

    7.  Click **Submit**.

### Facebook Product Feed

Specify whether to include products on a site when you configure the Facebook product feed.

Before you configure your Facebook feed, make sure your products are eligible. Products that meet the following criteria are eligible for Facebook feed.

- Product isn’t:
  - A base product
  - A product bundle
  - A product set
  - An option product
- Base product or variation isn’t disabled at the site level
- Product is accessible from the storefront

To include or exclude a product from the product feed:

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Products and Catalogs** > **Products**.
2.  Search for and select the product.
3.  To change the default for this product, click **All Site Values**.
4.  Specify the default value for this product for all sites.
5.  To change the default for this product on an individual site, unselect **Use Default** and select the value to use for that site.
6.  Click **Apply**.

The following fields can be included in the product feed for any item for sale on Facebook. The values in the B2C Commerce Value column represent what is copied into your feed by default without custom code.

**note:** Salesforce B2C Commerce doesn't upload an empty Facebook catalog feed export file. The Facebook export logs indicate when the catalog feed export job resulted in an empty file. An empty file can occur when no products are enabled for Facebook. Data from the catalog feed that is known to be invalid, for example, products missing a title, description, or images, are now included in the feed export file. The Facebook Business Manager product shows what data is missing from which products in the feed. The B2C Commerce export logs for the Facebook feed contain warnings about products missing data required by Facebook.

**note:** To consistently import products, Facebook requires the quote (") characters in feed content, such as product names and descriptions, be doubled ("") and surrounded by single quotes. B2C Commerce automatically makes these changes for Facebook catalog feed exports.

<table><caption>Table 1. Catalog Feed</caption><col /><col /><col /><col /><tbody><tr><td>Facebook Column</td><td>B2C Commerce Value</td><td>Description</td><td>Required</td></tr><tr><td>id</td><td>Product.getSKU()</td><td>Unique identifier for this item Not customizable.</td><td>Yes</td></tr><tr><td>availability</td><td><p>FacebookProduct.AVAILABILITY_PREORDER</p> <p>FacebookProduct.AVAILABILITY_IN_STOCK</p> <p>FacebookProduct.AVAILABILITY_IN_STOCK</p></td><td>Whether the item is in stock. Acceptable values are: in stock, out of stock, preorder, available for order, and discontinued.</td><td>Yes</td></tr><tr><td>condition</td><td>FacebookProduct.CONDITION_NEW</td><td>Accepted values are new, refurbished, or used.</td><td>Yes</td></tr><tr><td>description</td><td>Product.getShortDescription()</td><td>Falls back to base product value for variation product with null value. Line breaks, tab characters, and HTML tags are removed.</td><td>Yes</td></tr><tr><td>image_link</td><td>Product.getImageModel().getImages(viewType).get(0)<p>null</p></td><td>viewType is the configured product_image_view_type in the Facebook configuration. If there’s no image_link, the product is excluded from the catalog feed.</td><td>Yes</td></tr><tr><td>additional_image_link</td><td>Product.getImageModel().getImages(viewType)<p>null</p></td><td>viewType is the configured product_image_view_type in the Facebook configuration.</td><td>No</td></tr><tr><td>link</td><td>Absolute URL to \_\_SYSTEM\_\_Facebook-ProductRedirect pipeline with parameter pid=Product.getSKU()</td><td>Customer can customize the r parameter value, not the rest of the URL. Because an r parameter isn't provided by default, the redirect is to Cart-Show.</td><td>Yes</td></tr><tr><td>title</td><td>Product.getName()</td><td>Falls back to base product value for variation product with null value.</td><td>Yes</td></tr><tr><td>price</td><td>Product.getPriceModel().getPrice().getValue()<p>null</p></td><td>The cost of the item and currency. Specify currency as the ISO 4217 currency code, for example, 9.99 USD. If the price is null, the product is excluded from the catalog feed.</td><td>Yes</td></tr><tr><td>gtin</td><td>Product.getUPC()</td><td>The Global Trade Item Number (GTINs) can include UPC, EAN, JAN, and ISBN. <p>gtin, mpn, or brand is required.</p></td><td>Yes</td></tr><tr><td>mpn</td><td>Product.getManufacturerSKU()</td><td>The number which uniquely identifies the product to its manufacturer.<p>gtin, mpn, or brand is required.</p></td><td>Yes</td></tr><tr><td>brand</td><td>Product.getBrand()</td><td>The name of the brand.<p>gtin, mpn, or brand is required.</p></td><td>Yes</td></tr><tr><td>color</td><td>Product.getVariationModel().getVariationValue(product, variationAttribute).getDisplayValue()<p>null</p></td><td>variationAttribute is the attribute with ID color_variation_attribute_id in the Facebook configuration. If color is null, the value is blank in the feed.</td><td>No</td></tr><tr><td>size</td><td>Product.getVariationModel().getVariationValue(product, variationAttribute).getDisplayValue()<p>null</p></td><td>variationAttribute is the attribute with ID size_variation_attribute_id in the Facebook configuration. If size is null, the value is blank in the feed.</td><td>No</td></tr><tr><td>expiration_date</td><td>Product.getValidTo()</td><td>Expiration date of the product in the catalog.</td><td>No</td></tr><tr><td>gender</td><td>null</td><td>Acceptable values are male, female, and unisex.</td><td>No</td></tr><tr><td>item_group_id</td><td>Product.getMasterProduct().getSKU()<p>null</p></td><td>If this item is a variation product, all items in a group should share an item_group_id. If null, the value is blank in the feed.</td><td>No</td></tr><tr><td>google_product_category</td><td>null</td><td>Predefined values from Google's product taxonomy. For example, Apparel & Accessories > Clothing > Dresses. If null, the value is blank in feed.</td><td>No</td></tr><tr><td>material</td><td>Product.getVariationModel().getVariationValue(product, variationAttribute).getDisplayValue()<p>null</p></td><td>The material or fabric that a product is made out of. If null, the value is blank in the feed.</td><td>No</td></tr><tr><td>pattern</td><td>Product.getVariationModel().getVariationValue(product, variationAttribute).getDisplayValue()<p>null</p></td><td>The pattern or graphic print featured on a product. If null, the value is blank in the feed.</td><td>No</td></tr><tr><td>product_type</td><td> </td><td><p>Category path from child of root to product category:</p> <p>Mens>Clothing>Shorts</p> <p>If product is assigned to root category, its name alone is used:</p> <p>Apparel</p></td><td>No</td></tr><tr><td>sale_price</td><td>null</td><td> </td><td> </td></tr><tr><td>sale_price_effective_date</td><td>null</td><td> </td><td> </td></tr><tr><td>shipping</td><td>null</td><td> </td><td> </td></tr><tr><td>shipping_weight</td><td>null</td><td> </td><td> </td></tr><tr><td>shipping_size</td><td>null</td><td> </td><td> </td></tr><tr><td>custom_label_0</td><td>null</td><td> </td><td> </td></tr><tr><td>custom_label_1</td><td>null</td><td> </td><td> </td></tr><tr><td>custom_label_2</td><td>null</td><td> </td><td> </td></tr><tr><td>custom_label_3</td><td>null</td><td> </td><td> </td></tr><tr><td>custom_label_4</td><td>null</td><td> </td><td> </td></tr></tbody></table></sfdocstbl>

### Customize the Facebook Feed

`dw.extensions.facebook.FacebookProduct`defines a data structure that contains the Facebook representation of a B2C Commerce product. The product is passed to a hook to customize the default transformation of a product in the B2C Commerce schema to the Facebook catalog feed export schema.

In addition, a customization hook, com.demandware.plugin.facebook.FacebookFeedHooks, is included for optional implementation in customer custom cartridges. This interface defines the hooks that can be implemented to customize the data included in Facebook feed exports.

|Name|Signature|Description|
|dw.extensions.facebook.feed.transformProduct|dw.system.Status transformProduct( dw.catalog.Product product, dw.extensions.facebook.FacebookProduct facebookProduct )|Called after default transformation of given B2C Commerce product to Facebook product as part of the catalog feed export.|

The feed export generates a Facebook tab-delimited file. Implement the hooks described previously to customize the default transformation from Product system attributes.

**note:** The cartridge that contains the hook must be in the site cartridge path (not the Business Manager cartridge path).

**Example**

Following is an example of how to define a hook to map product attributes to Facebook product feed attributes:

1.  In a custom cartridge, include a file package.json at the root (sibling to the "cartridge" folder containing "scripts", "templates", and the like, with this content:

    ```json
    {
      "hooks": "./cartridge/scripts/hooks.json"
    }
    ```

    **note:** If a custom cartridge registers other custom hook implementations, the JSON file already exists.

2.  In that custom cartridge, include a file hooks.json in "cartridge/scripts" with this content:

    ```json
    {
      "hooks": [
        {
          "name": "dw.extensions.facebook.feed.transformProduct",
          "script": "./facebook.js"
        }
      ]
    }
    ```

    **note:** If a custom cartridge already registers other custom hook implementations, instead of performing this step, add the object with "name" and "script" to the existing array of registered hooks, for example:

    ```json
    {
      "hooks": [
        {
          "name": "some.other.hook.name",
          "script": "./some-file.js"
        },
        {
          "name": "dw.extensions.facebook.feed.transformProduct",
          "script": "./facebook.js"
        }
      ]
    }
    ```

3.  In that custom cartridge, include a file facebook.js in the cartridges/scripts folder with this content:

    ```javascript
    exports.transformProduct = function (product, facebookProduct) {
      // Map the Product "shortDescription" system attribute value to the Facebook product feed "title"
      // by default the Product "name" system attribute value is mapped to "title" so B2C Commerce overrides this
      facebookProduct.setTitle(product.shortDescription.markup);

      // Map the Product "facebookDescription" custom attribute value to the Facebook product feed "description"
      // by default the Product "shortDescription" system attribute value is mapped to "description" so B2C Commerce overrides this
      facebookProduct.setDescription(product.custom.facebookDescription);
    };
    ```

    Put whatever code you want in the exports.transformProduct function. The code in the example is just to show how it works.

    **note:** The parameters to the hook function are specified in the FacebookFeedHooks Script API documentation:

    - The first parameter is a standard dw.catalog.Product API object to be mapped
    - The second parameter is a dw.extensions.facebook.FacebookProduct API object
    - The FacebookProduct is an object representation of a row in the feed.
    - The Script API documentation for FacebookProduct specifies what attributes it contains, thus what we support to be included in a Facebook product feed.
    - There are constants available in FacebookProduct for the values that Facebook supports for columns with enumerated values, such as condition ("new", "refurbished", and "used").
    - The FacebookProduct passed to this function already has values set based on a default mapping B2C Commerce performs. A developer can set values in a FacebookProduct to override the B2C Commerce default mapping, or supply a value for a field that B2C Commerce doesn't map by default, such as shipping weight or custom label 0-4. Consult Facebook documentation for what the fields mean, and the constraints placed on them by Facebook.
    - The hook function is only called for products that are enabled for Facebook in Business Manager. If the Enabled checkbox is checked in the Facebook cofiguration page in Business Manager, all products in the storefront catalog are included in the feed except products that are explicitly excluded using the site-specific system attribute named "FacebookEnabled". If unchecked, products to include in the feed must be explicitly included using the "FacebookEnabled" attribute.
    - The Facebook feed export job automatically skips rows that don't have the values required per Facebook documentation. If a row is skipped for this reason, its SKU is logged in the export job log. These logs are in the Impex logs area like other export logs.
      You don't have to use the script name "facebook.js" to contain the hook. However, if you already have hooks in your custom cartridge that are all implemented in an existing script file, you could add this Facebook code in that script file and not create a new one.

## Facebook and Instagram Shop Ads Integration

**note:** An out of the box feature is available for Facebook and Instagram shopping integration. To activate the feature, contact Salesforce Support.

Use the Facebook and Instagram module to improve product discoverability, retarget existing shoppers, acquire new shoppers, and direct shoppers to your storefront for checkout. The module is built from a set of Business Manager cartridges and is included in the [Social Channels Extension](https://github.com/SalesforceCommerceCloud/social_channel_integrations/social_channels). With this integration, you can:

- Launch the [Meta Business Extension (MBE)](https://developers.facebook.com/products/business-apps/) tool from Business Manager.
- Publish and sync an entire site catalog or a specific category of products into Facebook and Instagram, and apply catalog refreshes as frequently as every 15 minutes with no additional steps needed.
- Publish the full category tree into Facebook and Instagram.
- Synchronize promotions with Facebook and Instagram, so that Instagram shoppers can make use of the same promotions set up for your storefront.
- Synchronize shipping profiles, so shoppers can place orders on Instagram using their shipping information from your storefront.
- Synchronize orders and order statuses between Meta and Salesforce, so that the shopper can view and get accurate order updates from Meta.

**important:** This integration doesn't support sites that use the Gross Tax Policy.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


### Prerequisites

Before you integrate with Facebook and Instagram:

1. Contact B2C Commerce Support to enable the Facebook feature toggle.
2. Make sure you have met the [SFCC Prerequisites](https://github.com/SalesforceCommerceCloud/social_channel_integrations?tab=readme-ov-file#prerequisites).
3. Create a [Meta Developer Account](https://developers.facebook.com/).
4. Optional: Create a [Meta Business Account](https://business.facebook.com/).
   - This step is optional because you can add your developer account to a pre-existing business account before starting the onboarding process.
5. Make sure you have:
   - A Salesforce B2C Commerce site catalog
   - A Salesforce B2C Commerce business user account

### Install the Facebook and Instagram Cartridges

1. Clone the Instagram repository, which requires access to the Salesforce CommerceCloud repositories on GitHub. If you don’t have a GitHub account, see [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html).
2. Sign in to [Salesforce CommerceCloud GitHub](https://github.com/orgs/SalesforceCommerceCloud/sso).
3. Search for the [Social Channels Integrations](https://github.com/SalesforceCommerceCloud/social_channel_integrations) repository, and click **Clone**.
4. [Install Dependencies and Create dw.json](https://github.com/SalesforceCommerceCloud/social_channel_integrations?tab=readme-ov-file#install-dependencies-and-create-dwjson).
5. From the root of the `social_channel_integrations` repo, manually upload the following Facebook and Instagram cartridges using the instructions in [Uploading SFCC Cartridges](https://github.com/SalesforceCommerceCloud/social_channel_integrations?tab=readme-ov-file#uploading-sfcc-cartridges).

   - `int_social_base`: This cartridge contains code shared by all the social channels. Apply this cartridge to both the storefront and Business Manager cartridge paths.
   - `bm_socialchannels`: This cartridge contains the Business Manager controllers/UI logic for a new Business Manager extension that integrates with Facebook and Instagram.
   - `int_instagram`: This cartridge contains the logic to integrate with Facebook and Instagram. It contains the service definitions, logic to handle the customer object that stores the Facebook and Instagram details, and the jobs which sync the B2C Commerce product categories, order, etc with Facebook and Instagram.
   - `int_social_checkout`: This cartridge contains the logic to synchronize orders and order statuses between Facebook/Instagram and Salesforce.
   - `bc_library`: This library contains all shared code for various demandware community projects. Ported from [demandware-library](https://github.com/SalesforceCommerceCloud/demandware-library).
   - `bm_socialfeeds`: The custom feeds Business Manager module allows merchants to easily create catalog feeds according to their needs. The framework uses a powerful generic export model which ensures reasonable performance while more feeds are added. The extension comes with a BM UI which is easily usable and doesn't require any technical background.
   - `int_socialfeeds`: The custom feeds module allows merchants to easily create catalog feeds according to their needs. The framework uses a powerful generic export model which ensures reasonable performance while more and more feeds are added.
     **note:** In order to upload cartridges via npm scripts, you must replicate the dw.json in the `social_channels`, `social_checkout`, and `social_feeds` directories. The npm scripts attempt to create a symlink, but you might need to manually create this symlink for your operating system.

6. Update the Facebook and Instagram cartridge paths:
   - Update your **Business Manager** cartridge path:
     1. Log in to Business Manager.
     2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.
     3. Within **Business Manager Site**, select the **Manage the Business Manager site** link.
     4. Select the **Settings** tab.
     5. In the **Cartridges** field, add paths for the following cartridges, for example: `int_socialfeeds:bm_socialfeeds:bc_library:bm_socialchannels:int_social_base`.
        - `int_socialfeeds`
        - `bm_socialfeeds`
        - `bc_library`
        - `bm_socialchannels`
        - `int_social_base`
        - `int_instagram`
        - `int_social_checkout`
   - Update your **Site** cartridge path:
     1. Log in to Business Manager.
     2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.
     3. Select the site that you want to use, for example: site `RefArch`.
     4. Select the **Settings** tab.
     5. In the **Cartridges** field, add the following new cartridges so that they precede `app_storefront_base`. For example: `int_instagram:int_socialfeeds:int_social_checkout:bc_library:int_social_base:app_storefront_base`.
        - `int_socialfeeds`
        - `bm_socialfeeds`
        - `bc_library`
        - `bm_socialchannels`
        - `int_social_base`
        - `int_instagram`
        - `int_social_checkout`
     6. Determine if you are using Salesforce OMS, and add the final required cartridge according to your environment:
        - `int_order_som` for Salesforce OMS users. The final path should look like: `int_order_som:int_instagram:int_socialfeeds:int_social_checkout:bc_library:int_social_base:app_storefront_base`.
        - `int_order_no_oms` for **_non_** Salesforce OMS users. The final path should look like: `int_order_no_oms:int_instagram:int_socialfeeds:int_social_checkout:bc_library:int_social_base:app_storefront_base`.
        - For details, see [OMS documentation](https://github.com/SalesforceCommerceCloud/docs/oms.md#salesforce-order-management).

### Configure an Account Manager API Client ID and Secret

Meta requires the access token from the Account Manager (AM) client credentials to access feed files from Web-based Distributed Authoring and Versioning (WebDAV).

1. Create an Account Manager API Client ID for this integration using the instructions in [Create an API Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html#create-an-api-client).
2. Make sure you have the following required environments on the **_Salesforce Commerce API_** role:
   - `abcd.001.dx.commercecloud.salesforce.com`
   - `abcd.002.dx.commercecloud.salesforce.com`
   - `abcd.003.dx.commercecloud.salesforce.com`
   - `abcd.004.dx.commercecloud.salesforce.com`
   - `(SANDBOXES).ccdx.abcd.demandware.net`
3. Add the following scopes:
   - `sfcc.catalogs.rw`
   - `sfcc.orders.rw`
   - `sfcc.promotions`
   - `sfcc.promotions.rw`

### Import Facebook and Instagram Common and Global Data

- To import Facebook and Instagram common data, perform the steps in [Import and Update Configuration Data -> Import Common Data](https://github.com/SalesforceCommerceCloud/social_channel_integrations/tree/main?tab=readme-ov-file#white_check_mark-import-common-data).
- To import Facebook and Instagram global data:

  1. Zip the [data/instagram/instagram_global](https://github.com/SalesforceCommerceCloud/social_channel_integrations/tree/main/data/instagram/instagram_global) folder by running `npm run data:instagram:global:zip` from the root of the repo, or manually zipping up the folder. Pay attention to `data/instagram/instagram_global/sites/{SiteID}`, this should be your current site ID.
  2. Log in to Business Manager.
  3. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Site Import & Export**.
  4. Select **Browse**.
  5. Select the `instagram_global.zip` file from the root of the repo.
  6. Select **Upload**.
  7. Select `instagram_global.zip`.
  8. Select **Import**.
  9. Select **OK**.

### Configure Facebook and Instagram Business Manager Permissions

1. Log in to Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Organization** > **Roles & Permissions**.
3. Select the role of your Business Manager user(s).
4. Select the **Business Manager Modules** tab.
5. Select the specified Sites under **Sites**, for example: RefArch and RefArchGlobal.
6. Select **Apply**.
   ![Select Context Sites](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_select_context_sites.png)
7. For **Custom Objects**, select the _write_ checkbox for `Custom Object Editor`.
   ![Select Custom Objects](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_role_custom_object_editor.png)
8. For **Social Channels**, select the _write_ checkbox for `Facebook and Instagram`.
   ![Select Social Channels](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_role.png)
9. Select **Update**.
10. In the **Business Manager Modules** tab, switch the context to **Organization**.
11. Select **Apply**.
    ![Select Organization](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_select_context_org.png)
12. For **Operations**, select the _write_ checkbox for `Jobs`.
13. For **Operations**, select the _write_ checkbox for `Job History`.
    ![Select Operations](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_role_jobs.png)
14. For **Social Product Feeds**, select the _write_ checkbox for **Social Product Feeds Definition**.
    ![Select Social Product Feeds](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_role_social_product_feeds_definition.png)
15. Select **Update**.
16. Select the **WebDAV Permissions** tab.
17. Scroll to the **Impex** section.
18. Select the **Manage custom folders** link.
19. In the text box, enter: `src/feeds/export`.
    ![Select WebDAV custom folders](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_role_webdav_manage_custom_folders.png)
20. Select **Apply**.
21. For **Impex**, select the _write_ checkbox for `/impex/src/feeds/export/*`.
    ![Select WebDAV path](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_role_webdav_permissions.png)
22. Select **Update**.

### Configure WebDAV Permissions

Follow the steps in [Configure WebDAV Permissions](https://github.com/SalesforceCommerceCloud/social_channel_integrations/tree/main?tab=readme-ov-file#white_check_mark-configure-webdav-permissions).

### Configure Job Permissions

Use the same client ID from the previous step to add the following configuration to your sandbox OCAPI settings. Meta uses this permission information to trigger the product feed jobs when needed.

1. Log in to Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Open Commerce API Settings**.
3. Select `Data` in the `Select Type` field, and let the context as `Global (organization-wide)`.
   ![Select Data setting](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_data_settings_field.png)
4. Paste and merge the following configuration information for your `clientID`:
   ```json
   ...
   {
     "client_id": "<YOUR_CLIENT_ID>",
     resources": [
       {
         "resource_id": "/jobs/*/executions",
         "methods": ["post"],
         "read_attributes": "(**)",
         "write_attributes": "(**)"
       }
     ]
   }
   ...
   ```
   For more information, refer to [Instagram Shopping with Commerce Cloud](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/Commerce_Cloud_Shopping_on_Instagram.pdf).

### Configure SCAPI Hooks

Enable SCAPI Hook execution in Salesforce Commerce Cloud Business Manager to create a basket or place an order through OCAPI endpoints when the access token is generated through SCAPI TSOB:

1. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Global Preferences** > **Feature Switches**.
2. Check the `Enable Salesforce Commerce API Hook Execution` box.
   ![Select SCAPI hook enable setting](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_oci_scapi_hooks_enabled.png)
3. Select **Apply**.

### Verify Environment Setup

Before continuing, verify that you have completed the required modifications to your environment:

- The custom cartridges provided must be available inside your active code version.
- The Cartridge Path for **_Business Manager_** must be updated to include the required cartridges:
  - `int_socialfeeds:bm_socialfeeds:bc_library:bm_socialchannels:int_social_base`
- The Cartridge Path for your current **_Site_** must be updated to include the required cartridges:
  - for Salesforce OMS users: `int_order_som:int_instagram:int_socialfeeds:int_social_checkout:bc_library:int_social_base:app_storefront_base`
  - for **_non_** Salesforce OMS users: `int_order_no_oms:int_instagram:int_socialfeeds:int_social_checkout:bc_library:int_social_base:app_storefront_base`
- The metadata **_system-objecttype-extensions_** file from **_data/common_** folder must be imported (`Basket`, `Order`, `ProductLineItem` and `ShippingLineItem` extensions).
- The metadata **_custom-objecttype-definitions_** file from **_data/common_** folder must be imported (`SalesChannelFeedConfig` and `SocialChannels` definitions).
- The metadata **_system-objecttype-extensions_** file from **_data/instagram/instagram_global_** folder must be imported (`Basket` and `Order` extensions like `Opt-In` attributes).
- Permissions on **Administration** > **Organization** > **Roles & Permissions** > **Business Manager Modules (organization context)** to view the feed definition module in the required profiles must be configured.
- Permissions on **Administration** > **Organization** > **Roles & Permissions** > **Business Manager Modules (site context)** to view the onboarding module in the required profiles must be configured.
- Permissions on **Administration** > **Organization** > **Roles & Permissions** > **WebDAV Permissions** to WebDAV folders for the required profiles must be configured.
- Permissions on **Administration** > **Organization** > **WebDAV Client Permissions** to the integration Client ID access to WebDAV folders must be configured.
- Permissions on **Administration** > **Site Development** > **Open Commerce API Settings** to the integration Client ID for jobs must be configured.
- The `Enable Salesforce Commerce API Hook Execution` on **Administration** > **Global Preferences** > **Feature Switches** must be checked to allow hook executions on basket and order requests.
- The payment method `META_SOCIAL_PAY` must be imported to your current site .
- The custom object **_SalesChannelFeedConfig_** `instagram-feed` or a similar one must be imported and updated to configure a feed template for your current site.
- The jobs on **Administration** > **Operations** > **Jobs**, including `Instagram-ExportCategories`, `Instagram-ExportFullFeeds`, `Instagram-ExportOrders`, `Instagram-ExportPartialFeeds`, `Instagram-ExportPromotions` and `Instagram-ExportShippingProfiles`, must be imported and configured for your current site **_scope_** and **_preferences_** if you are using multisites, desired schedule, and so on.
- The services on **Administration** > **Operations** > **Services**, including `facebook.graph` and `som.order.details` if you are using Salesforce OMS, must be imported.

### Configure B2C Commerce for Facebook and Instagram

1. Log in to Business Manager.
2. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Social Channels** > **Facebook and Instagram**.
3. Select the **Accept Terms** button.
4. Fill out the form. If you need help, refer to the [Salesforce B2C Commerce Details](#salesforce-b2c-commerce-configuration-details) or select the small help icon for a field to learn about the required values.
   ![Onboarding form](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_onboarding_form.png)
5. Select **Save**.
6. If all required fields are defined and valid, the **Onboarding** tab is displayed.
   ![Onboarding tab](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_onboarding_filled.png)
7. Select **Get Started**.
   ![Get Started](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus-mgr_facebook_onboarding_splash.png)
8. Log in with your Facebook account (this should be part of a Meta Business Account).
   ![Login with Facebook credentials](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_login.png)
9. Select **Continue as _[Your Name]_**.
   ![Continue with Facebook credentials](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_auth_business.png)
10. Select the following options from your Meta Business account:
    - Check **_Shops_** to configure the integration related to your shop.
    - Check **_Facebook Ads_** to configure the integration related to your ad account.
      ![Select Shops and Facebook Ads options](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_select_options.png)
11. Select the environment for this integration:
    - Choose **_Production_** to be connected to your live assets.
    - Choose **_Test_** to validate this integration with test assets.
      ![Select integration environment](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_environment.png)
12. Select a business **_Page_** from your Meta Business Account:
    - Connect to an _existing_ Page by selecting any entry you want to use.
    - Create a _new_ Page by selecting **Create New**.
      ![Select business page](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_assets.png)
13. Choose an **_ad account_** if you checked this option on the first step. Otherwise, skip this step.
    - Connect to an _existing_ ad account by selecting any entry you want to use.
    - Create a _new_ ad account by selecting **Create New**.
      ![Select ad account](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_ad_account.png)
14. Fill in required **_Shop details_**.
    ![Enter contact email and return timeframe](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_shop_details.png)
15. Confirm the commerce account being used and select **Next**.
16. Check all required permissions for the B2C Commerce application.
    ![Verify permission information](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_permissions.png)
17. Select **Confirm** to perform the linking.
    ![Linking in progress](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_linking.png)
18. Set any additional desired information, or skip this step. **Wait for the onboarding to complete before closing or refreshing the page.**
    ![Optional business information, address, category, and bank account](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_additional_info.png)
19. After completing the onboarding process, B2C Commerce automatically attempts to share additional post onboarding data with Meta. If this fails, resend this information by selecting **Share Data**. If the automated process was executed successfully, **Share Data** not visible.
20. When everything completes, check the connected Meta application details on Business Manager. This information is used to process all features available in this integration.
    - `Business Manager ID`
    - `External Business ID`
21. The new **_Meta_** tab contains information you need to manage your connection.
    ![Meta tab with Overview and Settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_meta.png)

#### Salesforce B2C Commerce Configuration Details

| **Field Name**                  | **Details**                                                                                                                                                                                                                                                                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Salesforce AM Client ID**     | The Account Manager API Client ID, used for operations like accessing WebDAV folders to read feed files (categories, products, etc)                                                                                                                                                                                                         |
| **Salesforce AM Client Secret** | The Account Manager API Client Secret                                                                                                                                                                                                                                                                                                       |
| **Salesforce SLAS ID**          | The SLAS Credential ID, used for operations like syncing Orders from Meta to Salesforce B2C Commerce                                                                                                                                                                                                                                      |
| **Salesforce SLAS Secret**      | The SLAS Credential Secret                                                                                                                                                                                                                                                                                                                  |
| **Short Code**                  | The environment short code, available by selecting the help icon or accessing _Administration > Site Development > Salesforce Commerce API Settings_.                                                                                                                                                                                       |
| **Organization ID**             | The environment organization ID, available by selecting the help icon or accessing _Administration > Site Development > Salesforce Commerce API Settings_.                                                                                                                                                                                  |
| **Current Site Hostname**       | The hostname used by the current Site to access the environment APIs, for example: `dev.mysite.com`. This is important information, especially if this integration is running in a development or production instance. If you have a custom hostname registered, check the correct value in **Merchant Tools** > **SEO** > **Aliases**.     |
| **Product Feed Job ID**         | The job ID used by the current Site to export full product feeds, for example: `Instagram-ExportFullFeeds`). This is used to trigger this job immediately after onboarding. If you have more than one storefront site, check the correct job ID (according to the defined job step scope) in **Administration** > **Operations** > **Jobs** |

### Synchronize the Product Catalog, Promotions, Shipping Profiles, and Orders

Enable product catalog synchronization by reviewing catalog feed configuration and enabling the B2C Commerce job that sends the products to Facebook and Instagram. Other jobs perform synchronization for promotions, shipping profile information, and order status.

#### Review Catalog Feed Configuration

Catalog feed configurations are based on the [custom feeds module](https://github.com/SalesforceCommerceCloud/custom-feeds), for easily creating catalog feeds according to your needs. After you define the template, schedule the feed to run at desired intervals. It is recommended to run this job at the same frequency you anticipate changes to your catalog, or whenever you replicate to production.

1. Log in to Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Social Product Feeds** > **Social Product Feeds Definition**:
   | **Field** | **Description** |
   |------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   | **Template** | The default feed configuration is loaded into the `instagram-feed` record within the **SalesChannelFeedConfig** custom object. Initial configuration is based on the SFRA reference website. Review the header and field mapping according to the catalog setup for your storefront and update it as required. Product field mappings can be found in [Social Product Feeds](https://github.com/SalesforceCommerceCloud/social_channel_integrations/docs/feedConfig.md). Possible areas of interest: `imageJsonData type="large"`: configure proper image view type that should be exported `price type="usd-m-list-prices"`: configure the list pricebook |
   | **Folder Name** | `IMPEX/src/feeds/export/social/instagram/catalogs` |
   | **File Name** | `instagram-feed-{{site_id}}-{{timestamp}}-{{locale}}.txt` |
   | **Category Specific Export** | The category to export. Enter `root` to export all products or enter a specific category, for example: `social-instagram`. Make sure the category you select is marked as "online". |
   | **Channel Type** | `Instagram` |
   | **Google Shopping Category** | Category based on the kind of products that are sold on your site |
   | **Available for Sites** | The site(s) for which products need to be exported. Make sure you run and configure a feed template once per site. Custom object IDs can be defined in the `CustomObjectIds` job parameter within the **Product Full Feed** job step in the `Instagram-ExportFullFeeds` scheduled job. |

#### Schedule Jobs

Review all job configurations, and then enable scheduling and execution according to your needs.

- Export Categories Job

  1. Log in to Business Manager.
  2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.
  3. Select the **Instagram-ExportCategories** job.
  4. Select the **Job Steps** tab and configure the following job steps:

     - **Export Categories**

       - The following table shows important attributes:
         | **Step Parameter** | **Description** |
         |--------------------|---------------------------------------------------------------------------------------------|
         | Is Disabled | A flag to disable this step from the job execution flow (for test purposes) |
         | CatalogId | The catalog ID for the catalog from which to extract the category tree. Use `*` for all catalogs. |
         | Locale | A specific locale for extracting category attributes or `ALL` to generate one file for each locale |
         | FolderPath | The folder in which to generate the feed. This path is relative to `_IMPEX/_`. |
       - Set values for the attributes as needed and then select **Assign**.

         ![Export Categories job settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_export_feeds_categories.png '{"class": "image-md"}')

     - **Notify Feed**

       - Set **FeedType** to `PRODUCT_SETS`.
       - Set **UpdateType** to `CREATE`.
       - Set **FileFolder** to the folder location in which to generate the feeds. This path is relative to `_IMPEX/_`.
       - Select **Assign**.

         ![Export Categories feed settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_notify_feeds_categories.png '{"class": "image-md"}')

  5. Select **Run Now** or select the **Schedule and History** tab to schedule the job.

- Export Full Feeds Job

  1. Log in to Business Manager.
  2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.
  3. Select the **Instagram-ExportFullFeeds** job.
  4. Select the **Job Steps** tab and configure the following job steps:

     - **Product Feed**

       - The following table shows important attributes:
         | **Step Parameter** | **Description** |
         |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
         | Is Disabled | A flag to disable this step from the job execution flow (for test purposes). |
         | ExportCatalogs | A flag to enable exporting products from catalogs. Set this to activated unless you want to generate only a delete feed file. |
         | Locales | Comma-separated locales to extract product attributes. An empty value specifies to only use the default site locale. |
         | GroupLocaleExport | If checked, the product attributes are grouped by locales when generating the feeds. |
         | GenerateDeleteFeed | If checked, a delete feed is also generated. It uses the last feed execution information contained in tracking files to generate the delete feed. A separate file is created for deleted products, which informs Facebook and Instagram about products that are deleted. - **NOTE**: If you manually create a delete file for Facebook and Instagram, specify line endings as line feed, `LF` (`\n`) instead of carriage return `CR` (`\r`) or `CRLF` (`\r\n`). |
         | CustomObjectIds | Comma-separated `SalesChannelFeedConfig` IDs that store instructions on how to generate each feed, for example: `instagram-feed`. |
         | Hostname | If informed, this composes the URL path of images on the resulting feed. |
       - This job step requires a pre-built product index when you set a specific category (instead of `root`) in your feed configuration object.
       - Set values for the attributes as needed and then select **Assign**.

         ![Export Full Feeds job settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_export_feeds_product_full.png '{"class": "image-md"}')

     - **Notify Feed**

       - Set **FeedType** to `PRODUCTS`.
       - Set **UpdateType** to `CREATE`.
       - Set **FileFolder** to the folder location in which to generate the feeds. This path is relative to `_IMPEX/_`.
       - Select **Assign**.

         ![Export Full Feeds feed settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_notify_feeds_product_full.png '{"class": "image-md"}')

  5. Select **Run Now** or select the **Schedule and History** tab to schedule the job.

- Export Orders job

  1. Log in to Business Manager.
  2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.
  3. Select the **Instagram-ExportOrders** job.
  4. Select the **Job Steps** tab and configure the following job steps:

     - **Export Orders**

       - The following table shows important attributes:
         | **Step Parameter** | **Description** |
         |--------------------|-----------------------------------------------------------------------------|
         | Is Disabled | A flag to disable this step from the job execution flow (for test purposes) |
         | FileFolder | The folder in which to generate the feed file. This path is relative to `_IMPEX/_`. |
       - Set values for the attributes as needed and then select **Assign**.

         ![Export Orders job settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_export_feeds_orders.png '{"class": "image-md"}')

     - **Notify Feed**

       - Set **FeedType** to `ORDERS`.
       - Set **UpdateType** to `UPDATE`.
       - Set **FileFolder** to the folder location in which to generate the feeds. This path is relative to `_IMPEX/_`.
       - Select **Assign**.

         ![Export Orders feed settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_notify_feeds_orders.png '{"class": "image-md"}')

  5. Select **Run Now** or select the **Schedule and History** tab to schedule the job.

- Export Delta Feeds Job

  1. Log in to Business Manager.
  2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.
  3. Select the **Instagram-ExportPartialFeeds** job.
  4. Select the **Job Steps** tab and configure the following job steps:

     - **Product Feed**

       - The following table shows important attributes:
         | **Step Parameter** | **Description** |
         |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
         | Is Disabled | A flag to disable this step from the job execution flow (for test purposes). |
         | ExportCatalogs | A flag to enable exporting products from catalogs. Set this to activated unless you want to generate only a delete feed file. |
         | DeltaCatalogInDays | Delta for a specified number of days. Valid values include `0.1` through `1`. `0.1` = 2.4 hours; `0.2` = 4.8 hours;...; `1` = 24 hours. For example, set 0.1 to do delta updated products for the last 2.4 hours. |
         | Locales | Comma-separated locales to extract product attributes. An empty value indicates to only use the default site locale. |
         | GroupLocaleExport | If checked, the product attributes are grouped by locales when generating the feeds. |
         | GenerateDeleteFeed | If checked, a delete feed is also generated. It uses the last feed execution information contained in tracking files to generate the delete feed. A separate file is created for deleted products, which lets Facebook and Instagram know about products that are deleted. **NOTE**: If you manually create a delete file for Facebook and Instagram, specify line endings as line feed, `LF` (`\n`) instead of carriage return `CR` (`\r`) or `CRLF` (`\r\n`). |
         | CustomObjectIds | Comma-separated `SalesChannelFeedConfig` IDs that store instructions on how to generate each feed, for example: `instagram-feed`. |
         | Hostname | If informed, this is used to compose the URL path of images on the resulting feed. |
       - This job step requires a pre-built product index when you set a specific category (instead of `root`) in your feed configuration object.
       - Set values for the attributes as needed and then select **Assign**.

         ![Export Delta Feeds job settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_export_feeds_product_delta.png '{"class": "image-md"}')

     - **Notify Feed**

       - Set **FeedType** to `PRODUCTS`.
       - Set **UpdateType** to `UPDATE`.
       - Set **FileFolder** to the folder location for the feeds. This path is relative to `_IMPEX/_`.
       - Select **Assign**.

         ![Export Delta Feeds feed settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_notify_feeds_product_delta.png '{"class": "image-md"}')

  5. Select **Run Now** or select the **Schedule and History** tab to schedule the job.

- Export Promotions Job

  1. Log in to Business Manager.
  2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.
  3. Select the **Instagram-ExportPromotions** job.
  4. Select the **Job Steps** tab and configure the following job steps:

     - **Export Promotions**

       - The following table shows important attributes:
         | **Step Parameter** | **Description** |
         |--------------------------------|---------------------------------------------------------------------------------------------|
         | ExportFile | Optional. If used, the generated file receives the same name. |
         | FileNamePrefix (recommended) | A name prefix that can contain a path and is used to generate different files with a timestamp. This is the prefix for the file and folder where the feed is to be generated. This path is relative to `_IMPEX/src/_`.|
         | OverwriteExportFile | If checked, the resulting file can overwrite an older file on the same directory. |
       - Select **Assign**.

         ![Export Promotions job settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_export_feeds_promotions.png '{"class": "image-md"}')

     - **Notify Feed**

       - Set **FeedType** to `PROMOTIONS`.
       - Set **UpdateType** to `CREATE`.
       - Set **FileFolder** to a folder location for the generated feeds. This path is relative to `_IMPEX/_`.
       - Set values for the attributes as needed and then select **Assign**.

         ![Export Promotions feed settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_notify_feeds_promotions.png '{"class": "image-md"}')

  5. Select **Run Now** or select the **Schedule and History** tab to schedule the job.

- Export Shipping Profiles Job

  1. Log in to Business Manager.
  2. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.
  3. Select the **Instagram-ExportShippingProfiles** job.
  4. Select the **Job Steps** tab and configure the following job steps:

     - **Export Shipping Methods**

       - The following table shows important attributes:
         | **Step Parameter** | **Description** |
         |--------------------------------|---------------------------------------------------------------------------------------------|
         | ExportFile | Optional. If used, the generated file receives the same name. |
         | FileNamePrefix (recommended) | A name prefix that can contain a path and be used to generate different files with a timestamp. This is the prefix for the file and folder where the feed is to be generated. This path is relative to `_IMPEX/src/_`.|
         | OverwriteExportFile | If checked, the resulting file can overwrite an older file on the same directory. |
       - Set values for the attributes as needed and then select **Assign**.

         ![Export Shipping Profiles job settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_export_feeds_shipping.png '{"class": "image-md"}')

     - **Notify Feed**

       - Set **FeedType** to `SHIPPING_PROFILES`.
       - Set **UpdateType** to `CREATE`.
       - Set **FileFolder** to the folder location where the feeds are generated. This path is relative to `_IMPEX/_`.
       - Select **Assign**.

         ![Export Shipping Profiles feed settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_notify_feeds_shipping.png '{"class": "image-md"}')

  5. Select **Run Now** or select the **Schedule and History** tab to schedule the job.

### Configure Jobs for Multi-Site Environments

When you configure jobs for more than one site, pay attention to the following job-specific information. Use the following screenshot as a guide when setting folder information for each job:

![Export Orders feed settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_export_feeds_categories_multi.png)

- Instagram-ExportCategories job:
  - The **Export Categories** step generates the category tree feed and can create multiple files, depending on the selected locales.
  - The **Notify Feed** step attempts to send all files generated in the previous steps (observing the correct folder) to each site within the scope of this step.
  - For each site:
    - Create a sequential flow with the required steps.
    - Set a different folder for **Export Categories** and **Notify Feed**.
- Instagram-ExportFullFeeds job:
  - The **Product Feed** step generates the catalog feed and can create multiple files, depending on the specified parameters.
  - The **Notify Feed** step attempts to send all files generated in the previous steps (observing the correct folder) to each site within the scope of this step.
  - For each site:
    - Create a sequential flow with the required steps.
    - Set a different `CustomObjectId` (a feed configuration id that includes folder and site) for **Product Feed** and a different folder for **Notify Feed**.
- Instagram-ExportOrders job:
  - The **Export Orders** step generates the order feed and creates just one file in the specified folder.
  - The **Notify Feed** step attempts to send all files generated in the previous steps (observing the correct folder) to each site within the scope of this step.
  - For each site:
    - Create a sequential flow with the required steps.
    - Set a different folder for **Export Orders** and **Notify Feed**.
- Instagram-ExportPartialFeeds job:
  - The **Product Feed** step generates the catalog feed and can create multiple files, depending on the specified parameters.
  - The **Notify Feed** step attempts to send all files generated in the previous steps (observing the correct folder) to each site within the scope of this step.
  - For each site:
    - Create a sequential flow with the required steps.
    - Set a different CustomObjectId (a feed configuration id that includes folder and site) for **Product Feed** and a different folder for **Notify Feed**.
- Instagram-ExportPromotions job:
  - The **Export Promotions** step generates the promotion feed and creates just one file in the specified folder.
  - The **Notify Feed** step attempts to send all files generated in the previous steps (observing the correct folder) to each site within the scope of this step.
  - For each site:
    - Create a sequential flow for each site with the required steps.
    - Set a different folder for **Export Promotions** and **Notify Feed**.
- Instagram-ExportShippingProfiles job:
  - The **Export Shipping Methods** step generates the order feed and creates just one file in the specified folder.
  - The **Notify Feed** step attempts to send all files generated in the previous steps (observing the correct folder) to each site within the scope of this step.
  - For each site:
    - Create a sequential flow with the required steps.
    - Specify a different folder for **Export Shipping Methods** and **Notify Feed**.

### Configure Permalink Checkout URLs for Social Sites

Send shoppers from Facebook and Instagram to your B2C Commerce storefront by adding checkout URLs.

**important:** Create permalinks only for SFRA and hybrid storefronts.

1. In your Meta Commerce Business product catalog, make sure that your product IDs (called content IDs in Meta) match your SKU IDs.
2. Enable permalinks.

   1. In Business Manager, from App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png), go to **Administration** > **Global Preferences** > **Feature Switches**.
   2. Select **Enable Permalinks Integration**.

3. Add a URL pipeline to route shoppers to checkout.
   **note:** Add a storefront link for simple and variant products, and each cart can include one coupon. Links can’t be created for a bundle, option, bonus, subscriptions, or gift card product. All transactions must be in US currency.
   1. Select **Merchant Tools** > **Site** > **SEO** > **URL Rules**.
   2. Go to the **Pipeline URLs** tab.
   3. For New Alias, enter a term to represent the pipeline in the URL. For example, to show the URL as hostnamealias/s/sitename/permalink-checkout instead of hostnamealias/s/sitename/Checkout-Start, enter permalink-checkout.
   4. For Resolves To, enter **PermalinkCheckout-Begin**.
      ![Pipeline URL settings](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_facebook_pipeline_url.png)
   5. Click **Apply**.

### Implement and Test Transaction Flows

For Meta transaction flow details, see [Checkout Scenarios on Meta Flows](https://github.com/SalesforceCommerceCloud/social_channel_integrations/blob/main/docs/instagram.md#checkout-scenarios-on-meta-flows).

### Disconnect Facebook and Instagram Integration

1. Log in to Business Manager.
2. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Social Channels** > **Facebook and Instagram**.
3. If you are connected, the **Disconnect** button is displayed.
4. Selecting the **Disconnect** button calls the disconnect process and clears your data in this environment.
   ![Disconnect button](https://developer.salesforce.com/media/b2c-commerce/b2c_instagram_bus_mgr_facebook_connected.png)

## TikTok for Business Integration

To enable centralization of product catalog synchronization and optimize audience engagement with TikTok users, integrate TikTok for Business with your SiteGenesis or Storefront-Reference-Architecture (SFRA) site.

### Get Started

TikTok for Business requires that you have a SiteGenesis or Storefront-Reference-Architecture (SFRA).

You also need:

- A Salesforce B2C Commerce site catalog
- A Salesforce B2C Commerce business user account
- A Salesforce Commerce API client setup within Account Manager

| A-E       | F-K        | L-Q         | R-V                  |
| --------- | ---------- | ----------- | -------------------- |
| Argentina | Finland    | Lebanon     | Romania              |
| Australia | France     | Malaysia    | Saudi Arabia         |
| Austria   | Greece     | Mexico      | Singapore            |
| Bahrain   | Germany    | Morocco     | South Africa         |
| Belarus   | Hungary    | Netherlands | South Korea          |
| Belgium   | Indonesia  | New Zealand | Spain                |
| Brazil    | Iraq       | Norway      | Sweden               |
| Cambodia  | Ireland    | Oman        | Switzerland          |
| Canada    | Israel     | Pakistan    | Taiwan               |
| Chile     | Italy      | Peru        | Thailand             |
| Colombia  | Japan      | Philippines | Turkey               |
| Czech     | Jordan     | Poland      | United Arab Emirates |
| Denmark   | Kazakhstan | Portugal    | United Kingdom       |
| Egypt     | Kuwait     | Qatar       | United States        |
|           |            |             | Vietnam              |

### Clone the TiKTok for Business Repository

TikTok for Business requires that you have a SiteGenesis or Storefront-Reference-Architecture (SFRA).

To clone the repository, you need access to the Salesforce CommerceCloud repositories on GitHub. If you don’t have a GitHub account, see [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html).

1.  Sign in to [Salesforce CommerceCloud GitHub](https://github.com/orgs/SalesforceCommerceCloud/sso).

2.  To copy the repository to your local system, search for the [Social Channels Integrations](https://github.com/SalesforceCommerceCloud/social_channel_integrations) repository, and click **Clone**.

    To integrate with TikTok for Business, you need two cartridges:

    - `bm_socialchannels`: This cartridge contains the Business Manager controllers and UI logic for the Business Manager extension that a site administrator can use to integrate with different social channels like TikTok, and Snapchat.
    - `int_tiktok`: This cartridge contains the logic to integrate with TikTok. It includes the service definitions, logic to handle the customer object that stores the TikTok details, and the job that syncs the B2C Commerce product catalog with TikTok.

3.  Upload the cartridges to your sandbox and import the metadata. Follow the instructions in the README file from the social_channels folder.

    **note:** Always install the cartridge in a staging instance, test the setup process with the staging Instance Id, orgId, and catalog. Then, replicate the code to production, change the instance Id, orgId in the setup process. Point staging and production instances to different catalogs, and pixels on TikTok. Use the same business center account and TikTok Ad account.

4.  Upload both `bm_socialchannels` and `int_tiktok` cartridges to your active code version.

5.  Add `bm_socialchannels` cartridge to the Business Manager cartridge path.

    1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

    2.  On the Storefront Sites page, click **Business Manager**.

    3.  Add `int_socialchannels`to the cartridge path.

    4.  Click **Apply**

6.  Add `int_tiktok` cartridge to the Business Manager cartridge path.

    1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Sites** > **Manage Sites**.

    2.  From the list of sites, select your site.

    3.  Click the **Settings**tab.

    4.  Add `int_tiktok`to the cartridge path.

    5.  Click **Apply**

        The export catalog job directly calls the TikTok API.

7.  Zip the contents of the data folder and import the zip file.

    1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Site Import & Export**

    2.  Click **Choose File**.

    3.  Select the zip file and click **Import**.

8.  Give permission to the TikTok for Business Manager menu to the required users.

### Set Up the TikTok for Business Integration

You integrate TikTok for Business with your B2C Commerce SiteGenesis or SFRA storefronts.

1.  Log in to your business TikTok account using the [Advertising on TikTok](https://ads.tiktok.com/i18n/login/) page.

2.  On the same computer, log in to Business Manager. click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Social Channels** > **TikTok for Business**.

3.  Accept the data sharing agreements.

4.  Complete Salesforce B2C Commerce and TikTok details form.

    **Salesforce B2C Commerce Details**

    - **Account Manager Client id**–The commerce API client you set up in Account Manager.
    - **Account manager Client Secret**–The secret for the API client.
    - **Tennent Id**–The realm_instance. For example, zzie_047.
    - **Org Id**–Available in Business Manager. Select, **Administration** > **Site Development** > **Salesforce Commerce API settings**
      **TikTok Details**

    - **Email**–The email for the marketing team that uses the account.
    - **Phone**–The phone number for the marketing team that uses the account.
    - **Country Code**–The region where the website is set up.
    - **WebSite URL**–The URL for the site.
    - **Industry Id**–The industry for the site.
      ![TikTok for Business details form.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_0.png)

5.  Click **Launch**.

    You’re directed to the TikTok for Business site where you previously logged in.

    ![TikTok login.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_1.png)

6.  In the TikTok for Business site, select an account.

    ![Select an account.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_2.png)

7.  Click **Connect Account**.

    The TikTok for Business plugin and integration app is launched.

    ![Connect Account](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_3.png)

8.  In the app, connect or create a business center.

    Connect only to existing business centers for which you have admin or owner access permission.

    - To connect to an existing business center, click **Connect**.
    - To create a Business Center, click **Create New**.
      ![Set up TikTok for Business](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_4.png)

9.  Connect or create an ad account

    Connect only to ad accounts for which you have admin or owner access permission.

    - To connect to an existing ad account, click **Connect**.
    - To create an ad account, click **Create New**.
      ![Create an ad account.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_5.png)

10. Connect or create a pixel.

    Connect only to a pixel for which you have admin or owner access permissions.

    - To connect a pixel, click **Connect**.
    - To create a pixel, click **Create New**.
      The pixel code isn't injected on your storefront. To enable event tracking, see [Sync Shopper Activities and Monitor Web Events](#sync-shopper-activities-and-monitor-web-events).

    ![Create a pixel.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_6.png)

11. Connect or create a catalog.

    - To connect an existing catalog, click **Connect**.
    - To create a catalog, click **Create New**.
      ![Create a catalog.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_7.png)

12. Click **Finish Setup**.

    ![Finish step.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_9.png)

13. On the setup success screen, click **Start Later**.

    ![Completion screen. Click Start later.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_10.png)

    You’re redirected to the Business Manager, TikTok for Business screen. The screen lists the TikTok application details created or connected during the setup.

    ![List TikTok Application Details](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_11.png)

14. To launch, Click **Manage your TikTok App**.

    The Plugin Overview page is displayed. From the Plugin Overview, launch ad campaigns, and get quick links to your TikTok for Business assets. For example, ad account, catalog sync status, and other settings.

### Sync a Product Catalog

To synchronize your product catalog with TikTok for Business, you enable a B2C Commerce job to send products to TikTok. Complete this process after you integrate B2C Commerce and TikTok.

1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.

2.  In the Search field, enter “TikTok-ExportCatalog job.”

    ![Jobs screen.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_12.png)

3.  Select and open the TikTok-ExportCatalog job.

4.  Select the **Job Steps** tab.

5.  Set ProductImageView Type to the view type that is set in the catalog.

    The value can be _large_ or _hi-res_.

    ![Set ProductImageView Type.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_13.png)

    Find the value in the main catalog image settings.

    ![Set the value.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_14.png)

6.  Click **Assign**.

7.  Select the **Schedule and History** tab.

    ![Select Schedule and History tab.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_15.png)

8.  Start the job or set a schedule and frequency.

    - To immediately start the job, click **Run Now**.
    - To Schedule the job, complete the Active and Run Time settings and click **Run Now**.

### Monitor Export Catalog Details

Monitor the details of your TikTok export catalog with Manage your TikTok App.

1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Social Channels** > **TikTok for Business**.

2.  Click **Manager your TikTok App**.

    The plugin and integration app is loaded.

    ![Manage your TikTok app.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_16.png)

3.  Click **Manage your TikTok App**.

    The TikTok Catalog Manager opens.

4.  Review the synced product details.

    ![TikTok Catalog Manager.](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_17.png)

### Sync Shopper Activities and Monitor Web Events

Send shopper activities to TikTok, track conversions, and build custom audiences for optimized product discovery. Two options are available. Complete the TikTok for Business integration and sync your product catalog before you begin.

#### Option 1

Events API Based tracking queues the events by storing them inside custom objects. Events call the TikTok batch API to push or send them to TikTik. The ViewContent event is the only real-time API call to TikTok.

1.  To make sure you have the latest code changes for `int_tiktok` cartridge, pull the latest code version from [GitHub](https://github.com/SalesforceCommerceCloud/social_channel_integrations/tree/main).
2.  Upload the code to your sandbox or instance. If you haven’t completed the TikTok for Business integration and synced your product catalog, complete those processes before you continue.
3.  Import the metadata for the server-side event tracking. The files are in the data-pixel folder.
4.  Add the `int_tiktok_pixel` cartridge to your cartridge path. The cartridge tracks the following events:

    - `View Content` (Product Show)
    - `AddToCart` (add item to carat)
    - `InitiateCheckout` (begin checkout)
    - `CompletePayment` (place order)
      ![Cartridges and Effective Cartridge Path](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_20.png)

5.  Enable or disable events tracked by the tiktok-settings custom object.

    1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Custom Objects** > **Custom Objects Editor**.
    2.  From the Object Type dropdown, select **SocialChannels**.
    3.  From the object list, select the **tiktok-settings** object.
    4.  Click **Edit Selected**. The tiktok-settings reflect how the TikTok for Business app links to TikTok. The Tracking section lists the toggles to enable or disable.
        ![Business Manager Manage Custom Objects page](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_21.png)

6.  (Optional) Set the View Content event tracking. The default setting is None and the event isn’t queued. Setting the option to either Real Time or Queue Events, isn’t recommended for high traffic sites or during a flash sale. If you set the Queue Event option, run or schedule the TikTok-WebEvents-Push job more frequently. The job pushes the events to TikTok and clears the custom objects.

    **note:** When you deselect the Enable Events API Based Tracking all events are disabled.

    ![TikTok tracking settings](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_22.png)

    ![View Content event Tracking dropdown](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_23.png)

7.  When the setup is complete, use the [Test Event Function](https://ads.tiktok.com/marketing-api/docs?rid=5ipocbxyw8v&id=1724255493685249) to verify your event setup.

    ![TikTok Ads Manager](https://developer.salesforce.com/media/b2c-commerce/b2c_tiktok_24.png)

#### Option 2

Embed the TikTok pixel into your site to send shopper activities into TikTok. For detailed steps, see [TikTok documentation](https://ads.tiktok.com/help/article?aid=10010829).

- `int_tiktok` exposes a hook `app.template.htmlHead`. Use the hook to inject the TikTok pixel directly into an SFRA storefront that manually installs the pixel to a site. To enable the pixel, add the following code snippet in `htmlhead.isml`.

  ```html
  <isprint
    value="${dw.system.HookMgr.callHook('app.template.htmlHead',
                              'htmlHead', pdict) || ''}"
    encoding="off"
  ></isprint>
  ```

After you inject the TikTok pixel base code across the storefront, add event codes to track and report on specific user actions. You use both TikTok pixel base code and event scripts to successfully track and report conversions.

## Google Channels Integration

Use the Google Channels integration to list your local store product availability on Google Surfaces. If you use Salesforce Omnichannel Inventory(OCI), list inventory directly from your OCI service. Inventory exposure on Google Surfaces improves product discoverability, and drives foot traffic to your local stores.

### Social Feed Cartridge

Use the Salesforce Commerce Cloud (SFCC) social feeds cartridge for Google Surfaces to publish to Google Surfaces:

- An entire site catalog, or a category of products.
- Information from inventory lists that are imported into B2C Commerce.
- Information from the Omnichannel Inventory(OCI) service.
- List of stores with mapping to inventory lists.
- Price books for products in each store.

### Prerequisites

Before you configure Google Channels integration with B2C Commerce, complete the following prerequisites.

- Make sure you have met the required [_SFCC Prerequisites_](https://github.com/SalesforceCommerceCloud/social_channel_integrations/blob/main/README.md#prerequisites).
- Create a [_Google Merchant Account_](https://www.google.com/retail/solutions/merchant-center).

### Install Dependencies

See Install [_Dependencies and Create dw.json_](https://github.com/SalesforceCommerceCloud/social_channel_integrations/blob/main/README.md#install-dependencies-and-create-dwjson).

### Upload Cartridges

Upload the following cartridges.

- **bm_socialchannels**: This cartridge contains the Business Manager controllers and UI logic to provide a newBusiness Manager extension that the site admin can use to integrate with Google.
- **int_google**: This cartridge contains the logic to integrate with Google.
- **bc_library**: This library contains all shared code for various B2C Commerce community projects. Ported from demandware-library
- **bm_socialfeeds**: The custom feeds Business Manager module allows merchants to easily create catalog feeds according to their needs. The framework uses a powerful generic export model. The model ensures reliable performance while more feeds are added. The extension integrates with a Business Manager for easy modifications.
- **int_socialfeeds**: The custom feeds module allows merchants to easily create catalog feeds according to their needs. The framework uses a powerful generic export model that ensures reliable performance while more and more feeds are added.

**note:** In order to upload cartridges via npm scripts, replicate the dw.json in `thesocial_channels`, `social_checkout`, and `social_feeds` directories. The npm scripts create a symlink. If the scripts fail, manually create the symlink for your operating system.

1. From the root of the repo (`social_channel_integrations`), `run: npm run code:upload:google` to upload the bm_socialchannels, `int_google, bc_library, bm_socialfeeds,` and `int_socialfeeds` cartridges to your instance.
2. (Optional) Manually upload the cartridge. See [_Uploading SFCC Cartridges_](https://github.com/SalesforceCommerceCloud/social_channel_integrations/blob/main/README.md#uploading-sfcc-cartridges).

### Update Cartridge Paths

1. In **Business Manager**, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Sites > Manage Sites**.
2. Select your site.
3. Click **Settings**.
4. In the Cartridges field, add the new cartridges. For example, `path:int_socialfeeds:bm_socialfeeds:bc_library:bm_socialchannelsint_socialfeeds`

   - `bm_socialfeeds`
   - `bc_library`
   - `bm_socialchannels`

5. Update your Site cartridge path:

   1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Sites > Manage Sites**.
   2. Select your site.
   3. Click **Settings**.
   4. In the Cartridges field, add the following cartridges.

   For example, `path: int_google:int_socialfeeds:bc_library:app_storefront_baseint_google`

   - `int_google`
   - `int_socialfeeds`
   - `bc_library`

### Import Common Data

To import common data, see [_Import Common Data_](https://github.com/SalesforceCommerceCloud/social_channel_integrations/blob/main/README.md#white_check_mark-import-common-data).

### Import Google Data

To import Google data, use one of the following options.

1. (Optional) Import with npm scripts.

   From the root of the repo (social_channel_integrations), run: npm run data:import:google:global

   The data files are uploaded and imported into the sandbox specified in your dw.json file.

2. (Optional) Use Business Manager to zip, upload, and import data.
   1. Zip the data/google/google_global folder
   2. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Site Development > Site Import & Export**.
   3. Click **Browse** and select the google_global.zip file. The file is at the root of the repo.
   4. Click **Upload**.
   5. Select google_global.zip
   6. Click **Import**.
   7. Click **OK**.

### Assign Business Manager Permissions

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Organization > Roles & Permissions**.
2. Select the Business Manager user role to assign.
3. Click **Business Manager Modules**.
4. Select the Sites to which the assigned permissions apply.
5. Click **Apply**.
6. In the **custom Objects > Custom Object Editor**, assign the write permission.
7. In the Social channel list, locate the Google Channel and assign the write permission.
8. Click **update**.
9. Select the Organization tab and Apply the permissions settings.
10. In the Operations list, locate the Jobs and Jobs History listings and for each, assign the write permission.
11. In the Social Product Feeds Definition list, locate the Social Product Feeds listing and assign the write permission.
12. Click **Update**.
13. Click the WebDAV permissions tab.
14. Scroll to the Impex section and click **Manage custom folders**.
15. Enter `src/feeds/export`.
16. Apply your changes.
17. In the Impex listings, locate `/impex/src/feeds/export/*` and assign the write permission.
18. Update your changes.

### Configure WebDAV Permissions

To import common data, see [_Configure WebDAV Permissions_](https://github.com/SalesforceCommerceCloud/social_channel_integrations/blob/main/README.md#white_check_mark-configure-webdav-permissions).

### Service Configuration

1. From Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Operations > Services**.
2. Click **Services**, and select **google.merchant.create**.
3. Update the following credentials:

   - For sandboxed, Development, and Staging instances use `google-surfaces-api-preprod`.
   - For Production instances use `google-surfaces-api-prod`

4. Apply your changes.
5. Click **Back to List**.
6. Click **Services**, and select **google.merchant.get**.
7. Update the following credentials:

   - For sandboxed, Development, and Staging instances use `google-surfaces-api-preprod`.
   - For Production instances use `google-surfaces-api-prod`

8. Apply your changes.

## Sync Product Catalog, Inventory, and Pricing

Catalog feed configurations are based on the custom feeds module. To use the module, define a template and schedule the feed to run at desired intervals. Sites with multiple locations require one feed file per locale. Prices for each locale are generated from the price book associated with the currency assigned to the locale. Salesforce recommends that you schedule the job to run in parallel with changes to your catalog, and when you replicate to production.

### Configure Catalog Feed

1. In Business Manager, select **Administration > Social Product Feeds > Product Feeds Definition**.
2. Configure each field to meet your custom feed requirements. The default template values already represent the attributes that Google is looking for in the product feed.

### Configure Job

1. In **Business Manager**, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Operations > Jobs**
2. Click the **Google-ExportFullFeeds** job.
3. From the Jobs tab, select configure job steps.
4. Complete the ExportPriceBook form.

   1. Enter the PriceBook IDs.
   2. Enter the FileNamePrefix. For example, `feeds/export/social/google/pricebook/pricebook`.
   3. Select **OverwriteExportFile**.
   4. Assign your settings.

      ![Select and Configure Step](https://developer.salesforce.com/media/b2c-commerce/b2c_export_stores.png)

5. Complete the ExportInventoryLists form.

   1. Enter the InventoryList IDs. If the full list doesn’t fit, create a duplicate job step and split the list.
   2. Enter the FileNamePrefix. For example, `feeds/export/social/google/inventory/inventory`.
   3. Select **OverwriteExportFile**.
   4. Assign your settings.

      ![Export Inventory List](https://developer.salesforce.com/media/b2c-commerce/b2c_export_inventory_list.png)

6. Complete the ExportStores form.

   1. Enter the StoreID. Use the ID of the store to be exported or \* to export all stores.
   2. Enter the FileNamePrefix. For example, `feeds/export/social/google/inventory/inventory`.
   3. Select **OverwriteExportFile**.
   4. Assign your settings.

      ![Export Store](https://developer.salesforce.com/media/b2c-commerce/b2c_export_stores.png)

7. Complete the ExportProducts FullFeed form.

   1. Select **ExportCatalogs**.
   2. Select **GenerateDeleteFeed**. A separate file is created for deleted products.
   3. Add the CustomObjectids. Use a comma to separate IDs
   4. Configure the Hostname.
   5. Assign your settings.

      ![Export Product Feeds](https://developer.salesforce.com/media/b2c-commerce/b2c_export_product_feed.png)

8. (Optional) From the Schedule and History tab, schedule the job to run.
9. (Optional) Click **Run Now**.

   ![Export Price Books](https://developer.salesforce.com/media/b2c-commerce/b2c_export_price_books.png)

## Omnichannel Inventory Integration

When you use Salesforce Omni Channel Inventory Integration for a store, the native inventory export doesn’t generate accurate inventory. To integrate Omnichannel Inventory, complete the steps in the Omnichannel Inventory Integration document.

When the integration steps are complete, remove the standard inventory export from the Google-ExportFullFeeds job.

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Operations > Jobs**.
2. Click **Google-ExportFullFeeds**.
3. Click **Job Steps**.
4. Delete the ExportInventoryList step.

### Store-Specific Pricing Exports

To export store-specific prices, you assign price books to stores, see [_Assign a Price Book or Promotion to a Specific Store_](https://help.salesforce.com/s/articleView?id=cc.b2c_assigning_a_pricebook_or_promotion_specific.htm&type=5).

After price book assignments are imported, use the `Google-StorePricing` Export job to export store price books to Google.

### Configure ExportAssignments Job

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Operations > Jobs**.
2. Select **Google-StorePricingExport**.
3. Configure the job steps.
   1. Click **Job Steps**.
   2. Enter the ExportFile. For example, `feeds/export/social/google/assignments/assignments`.
   3. Select **OverwriteExportFile**.
   4. Assign your settings.
4. Configure GoogleLIA Store Pricing Export.
   1. Enter the folder path. For example, `feeds/export/social/google`.
   2. Select **OverwriteExportFile**.
   3. Assign your settings.

## Configure Social Channels Integration

1. In Business Manager, check that Google-ExportFullFeeds has completed one or more runs.

   Check that the feed is available in the WebDAV folder,
   `webdav/Sites/Imped?src/feeds/export/social/google/`.

2. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools > Social Channels > Google Channel**.
3. Accept the terms.
4. Complete the Initialization form fields.

   - Name: Your business username.
   - Email: Your business email.
   - Country Calling Code: The business country calling code.
   - Phone: A business phone number.
   - Account manager Client ID: The client ID created in Account Manager.
   - Account Manager Client Secret: Client ID password.
   - Org ID: Salesforce Commerce API org ID. Find in **Business Manager > Site Development > Salesforce Commerce API Settings**.
   - Google Merchant Center ID: User ID established with Google. Find in the Google Merchant Center.

5. Submit your changes.

<!-- document id=91c74c308dcc6f360ff1d7820c40a9a05d1fdadab43f412308a375dab5d1d8ae url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/timeouts.md -->

Timeouts

# Timeouts

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/timeouts/timeouts-oas-v1-public.yaml)

## API Overview

Use the Timeouts API to manage SCAPI timeouts.

You can specify individual timeout values for specific APIs. Note that you can't set timeouts at the API family level.

### Authentication & Authorization

For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.

You must include `sfcc.timeouts.rw` (read-write access) or `sfcc.timeouts` (read-only access) in the client ID used to generate the token. For a full list of permissions, see the [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For detailed setup instructions, see the [Authorization for Admin APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html) guide.

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Manage Timeouts

Use the timeouts endpoint to retrieve, set, or delete your configuration for timeouts.

### Usage Notes

1.  Timeout configuration is set per instance type (development, staging, and production), not per site. Updating the configuration for one instance type does not affect the others.
2.  Configure timeouts for an individual API, not an API family.
3.  Wildcards are not allowed.
4.  Max timeout value is 120 seconds.

**Version:** 1.0.7

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/configuration/timeouts/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `AmOAuth2` (oauth2) Account Manager OAuth 2.0 bearer token authentication
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.timeouts: Timeouts READONLY scope
    *   Scope sfcc.timeouts.rw: Timeouts scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Return a set of SCAPI timeout overrides.

`GET /organizations/{organizationId}/timeouts`

Operation ID: `getTimeouts`. Security: AmOAuth2 (sfcc.timeouts, sfcc.timeouts.rw).

Return a set of SCAPI timeout overrides.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **200** Successfully returned SCAPI timeout overrides.
    
    Media type: `application/json`. Schema: `TimeoutConfigurations`.
    
    _Example: TimeoutExample_
    
    ```
    {
      "timeouts": {
        "product/shopper-products": 77,
        "checkout/orders": 88
      }
    }
    ```
    

### PUT Create or replace the full set of SCAPI timeout overrides.

`PUT /organizations/{organizationId}/timeouts`

Operation ID: `putTimeouts`. Security: AmOAuth2 (sfcc.timeouts.rw).

Create or replace the full set of SCAPI timeout overrides.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Request body (required)

Media type: `application/json`. Schema: `TimeoutConfigurations`.

_Example: TimeoutExample_

```
{
  "timeouts": {
    "product/shopper-products": 77,
    "checkout/orders": 88
  }
}
```

#### Responses

*   **200** Successful update of SCAPI Timeout overrides.
    
    Media type: `application/json`. Schema: `TimeoutConfigurations`.
    
    _Example: TimeoutExample_
    
    ```
    {
      "timeouts": {
        "product/shopper-products": 77,
        "checkout/orders": 88
      }
    }
    ```
    
*   **201** Successful creation of SCAPI Timeout overrides.
    
    Media type: `application/json`. Schema: `TimeoutConfigurations`.
    
    _Example: TimeoutExample_
    
    ```
    {
      "timeouts": {
        "product/shopper-products": 77,
        "checkout/orders": 88
      }
    }
    ```
    
*   **400** Invalid SCAPI timeout override values (e.g., incomplete JSON or key not in "api-family/api" format).
    
    Media type: `application/json`. Schema: `ErrorResponse`.
    
    _Example: InvalidTimeoutExample_
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Submitted content was invalid: API paths can only consist of an API family, followed by a slash, followed by a single API."
    }
    ```
    

### DELETE Delete all SCAPI timeout override values.

`DELETE /organizations/{organizationId}/timeouts`

Operation ID: `deleteTimeouts`. Security: AmOAuth2 (sfcc.timeouts.rw).

Delete all SCAPI timeout override values.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    

#### Responses

*   **204** Successfully deleted all SCAPI timeout values.

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### TimeoutConfigurations

*   `timeouts` (_TimeoutMappings_)

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### TimeoutMappings

Configuration object for timeout feature

Additional properties: `integer (int32)`.

Map of APIs and their respective timeout values in seconds. Max timeout value is 120.

<!-- document id=6b17ae7af6f2d08aab5d81e2194bf42d21209f5217a05dea87d7cf55d2b679a8 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/timeouts-limits.md -->

# Timeouts and Limits

SCAPI enforces timeout thresholds and size limits to ensure optimal performance and system stability.

## Default Timeouts

**note:** Some API families, such as SLAS and Omnichannel Inventory (OCI), do not have gateway timeouts.

| Type                                                                                                                                                    | Timeout | HTTP status code if exceeded | Customizable                                                                                                                                                                                                                                                     |
| :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ | :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Client → SCAPI Gateway**                                                                                                                          |         |                              |                                                                                                                                                                                                                                                                  |
| Connection Idle                                                                                                                                         | 400s    | -                            | No                                                                                                                                                                                                                                                               |
| [**SCAPI > Troubleshoot > (default) Timeouts**](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeout-troubleshoot.html) |         |                              |                                                                                                                                                                                                                                                                  |
| Shopper-API Read/Write                                                                                                                                  | 10s     | 504                          | [Yes](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary)                                                                                                                                                              |
| Custom-API Read/Write (Shopper)                                                                                                                         | 60s (10s recommended) | 504                          | Yes. For details, see [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary) and [Custom API Limitations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html#limitations). |
| Custom-API Read/Write (Admin)                                                                                                                           | 60s     | 504                          | Yes. For details, see [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary) and [Custom API Limitations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-apis.html#limitations). |
| Admin-API Read/Write                                                                                                                                    | 60s     | 504                          | Yes. For details, see [Timeouts API](https://developer.salesforce.com/docs/commerce/commerce-api/references/timeouts?meta=Summary).                                                                                                                              |
| **Hook Execution (per hook)**                                                                                                                           |         |                              |                                                                                                                                                                                                                                                                  |
| Shopper-API                                                                                                                                             | 10s     | 500                          | Yes                                                                                                                                                                                                                                                              |
| Admin-API                                                                                                                                               | 60s     | 500                          | Yes                                                                                                                                                                                                                                                              |

## Limits

SCAPI enforces the following request and response size constraints to ensure optimal performance and system stability.

| Type                                                                                                                                                  | Limit                                                                                                                                           | HTTP status code if exceeded | Customizable                                                                                                                                                                        |
| :---------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**SCAPI \> Troubleshoot \> Timeouts and Limits**](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.html) |                                                                                                                                                 |                              |                                                                                                                                                                                     |
| Max. request line (URL) and headers                                                                                                                   | 24kB                                                                                                                                            | 400                          | No                                                                                                                                                                                  |
| Max request payload                                                                                                                                   | 5MB                                                                                                                                             | 413                          | No                                                                                                                                                                                  |
| Max response payload                                                                                                                                  | 10MB                                                                                                                                            | 500                          | No                                                                                                                                                                                  |
| **Script API \- Quotas** (Hooks & Custom APIs)                                                                                                        |                                                                                                                                                 |                              |                                                                                                                                                                                     |
| Default limit                                                                                                                                         | [API Quotas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/API_Quotas.html)                                     | 400                          | Yes. For details, see [Implement Quota Overrides](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/b2c-governance-and-quotas.html#implement-quota-overrides) |
| Storefront Limit                                                                                                                                      | [API Quotas](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/quota/html/API_Quotas.html)                                     | 400                          | Yes. For details, see [Implement Quota Overrides](https://developer.salesforce.com/docs/commerce/commerce-solutions/guide/b2c-governance-and-quotas.html#implement-quota-overrides) |
| **Hook Circuit Breaker**                                                                                                                              |                                                                                                                                                 |                              |                                                                                                                                                                                     |
| 50 hook errors within last 100 requests                                                                                                               | [OCAPI Hook Circuit Breaker](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/hookcircuitbreaker.html) | 503                          | No                                                                                                                                                                                  |

<!-- document id=b55344a0547b449440450ecf70cd1133348e1007a5977ef188e28573251b8e39 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/track-analytics.md -->

# Track Analytics

Make data-driven decisions with analytics tools. This section contains these guides.

- [Analytics Reporting Integration](https://help.salesforce.com/s/articleView?id=cc.b2c_analytics_reporting_integration.htm&type=5)
- [Reports & Dashboards](https://help.salesforce.com/s/articleView?id=cc.b2c_reports_and_dashboards.htm&type=5)

### See Also

- [Get Started with B2C Commerce](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/developer-workflow.md)

<!-- document id=6a08b997df5912705ce52e8fc6323c93a7ec8405ee31b9b035245695572d1ea6 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-analytics.md -->

# Track Storefront Next Activity with Analytics

Monitor your storefront activity by collecting analytics data. Storefront Next provides a built-in solution for analytics, which is integrated with Einstein, Active Data, and Data 360 (formerly Data Cloud). Implement analytics by using the analytics hook and events. Also, you can create integrations with other analytics systems.

## How It Works

Storefront Next pages invoke the analytics hook to trigger the creation of `AnalyticsEvent` objects.

For example, on the product details page, you see this script.

```tsx
const analytics = useAnalytics();

...
useEffect(() => {
	...
  void analytics.trackViewProduct({
    product: productData,
  });
	...
}
```

The `trackViewProduct` method creates a ViewProduct AnalyticsEvent that's passed into an internal `track` function. This `track` function sends the AnalyticsEvent to registered EngagementAdapters that handle the process of sending the event through to a target analytics system.

## Tracking Consent

No analytics events are sent until a shopper grants consent, which helps you avoid tracking that violates privacy regulations such as the General Data Protection Regulation (GDPR).

Storefront Next supports a two-layer consent model:

- **Binary consent (default):** A consent banner asks the shopper to accept or decline all tracking. This choice is persisted through the SLAS token (stored in the `dw_dnt` cookie). This is the default behavior.
- **Per-adapter consent categories:** Each engagement adapter can declare the consent category it requires (for example, `analytics` or `marketing`). An event reaches an adapter only if the shopper has granted that category, which supports GDPR-style, category-level consent.

When a shopper accepts the consent banner, Storefront Next builds a set of consent preferences (the granted categories) and forwards them to every adapter. Each adapter checks those preferences before sending an event. Until the shopper accepts, the consent preferences are undefined and no events are sent.

### Configure Consent Categories

Enable tracking consent and declare the categories your storefront supports in `config.server.ts`. The `consentCategories` array defines which categories are granted when a shopper accepts the consent banner.

```ts
analytics: {
    trackingConsent: {
        enabled: true,
        defaultTrackingConsent: TrackingConsent.Declined,
        consentCategories: ['necessary', 'analytics', 'marketing', 'personalization'],
        position: 'bottom-right',
    },
},
```

The default configuration defines four categories that align with common consent-management conventions:

- `necessary`: Essential cookies and tracking required for site functionality
- `analytics`: Usage analytics and performance measurement
- `marketing`: Advertising, retargeting, and campaign tracking
- `personalization`: Product recommendations and personalized experiences

Category values are arbitrary strings, so you can define whatever categories match your consent-management platform (for example, OneTrust, Cookiebot, or Usercentrics). There's no hard-coded set.

**note:** If `trackingConsent.enabled` is `true` but `consentCategories` isn't configured, the consent banner has no categories to grant when a shopper accepts, so adapters that require a category never fire. Configure `consentCategories` to specify the categories your storefront grants on acceptance.

### Require a Consent Category per Adapter

To send events to an adapter only when the shopper has granted a specific category, set the `consentCategory` field on that adapter in `config.server.ts`.

```ts
engagement: {
    adapters: {
        einstein: {
            enabled: true,
            consentCategory: 'personalization',
            // ... other config
        },
        activeData: {
            enabled: true,
            consentCategory: 'analytics',
            // ... other config
        },
    },
}
```

This table shows when an adapter that declares a `consentCategory` fires.

| Shopper Consent              | Granted Categories                                           | Adapter Fires?                                          |
| ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
| Accepts all                  | `['necessary', 'analytics', 'marketing', 'personalization']` | Yes                                                     |
| Accepts only some categories | for example, `['necessary']`                                 | Only when the adapter's category is in the granted list |
| Declines                     | `[]`                                                         | No                                                      |
| Not yet decided              | `undefined`                                                  | No                                                      |

If you omit `consentCategory`, the adapter doesn't apply its own category check and fires for every event that reaches the adapter. No events flow until the shopper accepts the consent banner, so omitting `consentCategory` doesn't bypass consent. This is useful for adapters that manage consent internally, such as a Google Tag Manager adapter that uses Google Consent Mode.

By default, all built-in adapters—Einstein, Data 360, and Active Data—set `consentCategory: 'analytics'`, so each fires only after the shopper grants the `analytics` category. With the default binary consent banner, granting consent maps to all configured categories, so `'analytics'` effectively means the shopper accepted tracking. The gate matters once you offer granular, per-category consent: an adapter set to `'analytics'` then stays silent for a shopper who accepted, say, only `'marketing'`.

## Set Up Einstein Activities

To receive Einstein Activities events, set up Einstein Activities.

1. Set up Einstein by using the Einstein Configurator. See [Einstein Activities](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-activities-overview.html) in the _B2C Commerce Einstein API Guide_.
2. In `config.server.ts`, update the Einstein configuration. In the `einsteinId` field, specify the ID of the API client you created in the Einstein Configurator.

   ```
               engagement: {
                adapters: {
                    einstein: {
                        enabled: true,
                        host: 'https://api.cquotient.com',
                        einsteinId: '<API Client ID from Einstein Configurator>',
   ```

## Set Up Active Data

To receive Active Data events, set up Active Data in Business Manager. Active Data in Storefront Next supports product views on the Product Detail Page (PDP) and product impressions on a Product List Page (PLP) or recommendation.

### Prerequisites

- Configure Active Data in Business Manager by following the steps in the next sections.

### Step 1: Enable Data Collection

Open a support case asking Salesforce Customer Support to enable data collection.

### Step 2: Confirm That Sites Are Online

1. Log into Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Administration > Sites > Manage Sites**.
3. Confirm that the status is **Online** for the sites for which you want to track metrics. Active Data is collected only for live (online) sites.

### Step 3: Confirm that Tracking (Default for New Storefront Session) Is Enabled

1. Log into Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/sfnext/shared/appLauncher.png) and then select **Merchant Tools > Site Preferences > Privacy**.
3. Confirm that Tracking (Default for New Storefront Session) is set to **Enabled**.
   Active data events are sent from Storefront Next to the `__Analytics-Start` controller in B2C Commerce. One way you can confirm that active data tracking is working is by viewing network requests and checking if the request to `__Analytics-Start` is responding with an `HTTP 200` code.

### Step 4: Configure Active Data

1. In `config.server.ts`, enter the Active Data host. In the `host` field, specify the URL of the B2C Commerce instance.

   ```
                       activeData: {
                           enabled: true,
                           host: 'https://{instance}.dx.commercecloud.salesforce.com',
                           siteUUID: '8bb1ea1b04ac3454d36b83a888',
                           eventToggles: {
                               view_page: true,
                               view_product: true,
   ```

2. If you have a hybrid storefront, specify the site UUID in the `siteUUID` field. In SFRA, get the site UUID from the value that comes after `dwac_` in the cookie in SFRA. This cookie appears only when a user is logged into SFRA.

   **note:** If `siteUUID` isn't set for the hybrid storefront, all Active Data events are treated as having come from anonymous guest users. In pure Storefront Next and PWA Kit Composable implementations, there is no `dwac_ cookie`, so all events are treated as coming from anonymous users.

## Set Up Data 360

The Data 360 adapter streams view and impression interactions to a Data 360 Website connector. It maps only view and impression events—`view_page`, `view_product`, `view_search`, `view_category`, and `view_recommender`. Cart, checkout, wishlist, and click events have no Data 360 mapping and ship disabled.

For how to provision Data 360, connect your storefront, and get the tenant and app source IDs, see [Send Storefront Next Analytics Events to Data 360](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-data360.md).

The adapter is configured in `config.server.ts` under `engagement.adapters.data360`.

```ts
engagement: {
    adapters: {
        data360: {
            enabled: true,
            appSourceId: '<your-app-source-id>',
            tenantId: '<your-tenant-id>',
            siteId: '<your-site-id>',
            webStoreId: 'sfnext',
            consentCategory: 'analytics',
            eventToggles: {
                view_page: true,
                view_product: true,
                view_search: true,
                view_category: true,
                view_recommender: true,
                // Cart, checkout, wishlist, and click events have no Data 360
                // mapping and ship disabled.
            },
        },
    },
}
```

- `<your-app-source-id>` and `<your-tenant-id>` come from the provisioned Website connector.
- `<your-site-id>` is the B2C Commerce site ID, sent as `siteId`/`internalOrganizationId` on every interaction.
- `webStoreId` The default value is `sfnext`. It separates Storefront Next traffic from PWA Kit's (`pwa`) in a shared data lake object (DLO).
- `consentCategory` defaults to `analytics`. Because Data 360 does identity resolution and marketing activation, merchants using granular consent can gate it on `marketing` or `personalization` instead.

## Analytics Events

Storefront Next provides these built-in event types.

- ViewPageEvent
- ViewProductEvent
- ViewSearchEvent
- ViewCategoryEvent
- ViewRecommenderEvent
- ClickProductInCategoryEvent
- ClickProductInSearchEvent
- ClickProductInRecommenderEvent
- CartItemAddEvent
- CheckoutStartEvent
- CheckoutStepEvent

Each event type defines different fields corresponding to the data required by that specific event.

All types extend `BaseEvent`, which provides the customer fields that are shared across all events, such as `usid` or `customerId`. All events also define a string `eventType` field that EngagementAdapters use during event handling. All types are included as part of the union type `AnalyticsEvent`.

For example, a `ViewProductEvent` Analytics event triggers both an Einstein ViewEvent and an Active Data product view with the default setup. The `ViewSearchEvent` and `ViewCategoryEvent` Analytics events similarly send the ViewSearch and ViewCategory Einstein events alongside Active Data product impressions.

### Adding More Event Types

Storefront Next uses typescript module augmentation to extend existing events and add new event types. To add new event types, use the `AnalyticsEventExtensions` interface. Types added to `AnalyticsEventExtensions` are included in the `AnalyticsEvent` union type.

For example, let's add a new `CartItemRemove` event that triggers when a shopper removes items from the basket.

1. In a TypeScript declaration file, define our new event type. The new event must extend BaseEvent and define the `eventType` field. We also include a `cartItems` field for the items we're removing from cart.

```ts
declare module "@salesforce/storefront-next-runtime/events" {
  interface AnalyticsEventExtensions {
    CartItemRemove: BaseEvent & {
      eventType: "cart_item_remove";
      cartItems: Array<BasketProductItem>;
    };
  }
}
```

2. Update the analytics hook to support the new event.

```ts
/**
 * Track removing items from cart
 */
const trackCartItemRemove = async (data: {
  cartItems: ShopperBasketsV2.schemas["ProductItem"][];
}) => {
  return trackEvent(authPromiseRef.current, appConfig, trackingConsent, "cart_item_remove", {
    cartItems: data.cartItems,
  });
};
```

The `trackEvent` function creates the `CartItemRemove` event from the event type, handles Do Not Track, and adds session information such as the `usid` to the event.

3. Update engagement adapters to handle the new event type.

The `track` function sends `CartItemRemove` events to all registered engagement adapters. Therefore, the adapters need to know if they must handle or ignore `CartItemRemove` events.

4. Configure Engagement adapters to handle or ignore an event in `config.server.ts`. To have the Einstein adapter process `CartItemRemove` while having the Active Data adapter ignore the event, make the following changes inside `config.server.ts`.

```ts
engagement: {
    adapters: {
        einstein: {
            // ... other config
            eventToggles: {
                // ... existing events
                cart_item_remove: true,  // ← Enable for Einstein
            },
        },
        activeData: {
            // ... other config
            eventToggles: {
                // ... existing events
                cart_item_remove: false,  // ← Disable for Active Data
            },
        },
    },
}
```

5. Next, update the existing adapters that process `CartItemRemove`. Each adapter handles the event differently. For example, if we want to send `CartItemRemove` to a non-existent Einstein activity called `removeFromCart`, make this change.

```ts
// Maps event types to Einstein Activity API endpoints
const einsteinEventToEndpointMap: Record<AnalyticsEvent['eventType'], string> = {
    // ... other event mappings
    cart_item_remove: 'removeFromCart'
};

// Converts events into a payload that aligns with Einstein Activity API
function convertEventToEinsteinActivity(event: AnalyticsEvent, realm: string, isProduction: boolean): EinsteinActivity {
  // ... other events
  case 'cart_item_remove':
      return {
          ...baseActivity,
          products: event.cartItems.map((item: ShopperBasketsV2.schemas['ProductItem']) =>
              extractEinsteinItemInfoFromCartItem(item)
          ),
      };
```

**note:** Einstein doesn't have a `removeFromCart` endpoint. If this event is sent from your browser, you see Einstein return an HTTP 400 response.

6. Update the pages that fire the new event.

Now, our `CartItemRemove` event is ready to be used. The next steps are to update the components that handle cart item removal to invoke the analytics hook and test.

```ts
void analytics.trackCartItemRemove({
  cartItems: [removedItem],
});
```

## Engagement Adapters

Engagement Adapters define how an event are sent to an analytics system. Storefront Next includes adapters for Einstein Activities, Active Data, and Data 360 (a Salesforce Data 360 adapter that streams view and impression interactions to a Data 360 Website connector).

Engagement adapters follow the `EngagementAdapter` interface:

```ts
export interface EngagementAdapter extends EventAdapter {
  name: string;
  sendEvent?: (event: AnalyticsEvent) => Promise<unknown>;
  send?: (url: string, options?: RequestInit) => Promise<Response>;
}
```

The key method used by the analytics system is the `sendEvent` function. The internal `track` function invokes this method when an event is received. The `sendEvent` function takes an `AnalyticsEvent` and converts that event into a payload that can be sent to the target analytics system.

As a best practice, Storefront Next uses the [Beacon API](https://developer.mozilla.org/en-US/docs/Web/API/Beacon_API) (`navigator.sendBeacon`) to send analytics events to target systems because it's non-blocking.

**note:** Because Storefront Next sends analytics events with the Beacon API instead of `fetch` or `XMLHttpRequest`, these requests don't appear under the **Fetch/XHR** filter in your browser's Network tab, and tools that inspect only fetch requests, such as the Einstein Chrome extension, don't capture them. To verify that events are being sent, look for requests to the analytics endpoints (for example, `api.cquotient.com` for Einstein, or the `__Analytics-Start` controller for Active Data) in the Network tab's full request list or under its **Other** filter.

### Adding More Adapters

Keep the following in mind when implementing your own EngagementAdapter.

- Use `eventToggles` to determine which events the adapter processes. This helps fine-tune the adapter to only handle the events the target analytics system supports.

- `sendEvent` has two main tasks. Consider implementing these tasks as separate functions that `sendEvent` invokes. These tasks are:

* Converting an AnalyticsEvent object into the appropriate payload for the target analytics system
* Sending the payload to the target system

- Register the EngagementAdapter so that it receives AnalyticsEvents from the internal `track` function. To register an EngagementAdapter, modify the `src/adapters.index.ts` file and invoke the `addAdapter` method.

  ```ts
  export function initializeEngagementAdapters(appConfig: AppConfig) {
    // ... other adapters

    addAdapter(
      'custom-adapter', {
        name: 'custom-adapter'
          sendEvent: async (event: AnalyticsEvent) => Promise.resolve({}),
      }
    )
  ```

As a best practice, adapters provide a function for creating the adapter so you're more likely to see this script.

```ts
import {createCustomAdapter} from './customAdapter'

export function initializeEngagementAdapters(appConfig: AppConfig) {

  // ... other adapters

  addAdapter(
    'custom-adapter',
    createCustomAdapter()
  )
```

## See Also

[Einstein Activities](https://developer.salesforce.com/docs/commerce/einstein-api/guide/einstein-activities-overview.html)
[Active Merchandising](https://help.salesforce.com/s/articleView?id=cc.b2c_active_merchandising.htm)

<!-- document id=e90dc89754d00308d812ebafec9118c89aa76da5121b6c35d5487bd2d3289ac4 url=/developer/current/en-us/commerce-cloud/solutions/guides/traffic-management-sk.md -->

# Traffic Management for Flash Sales

Looking for a way to quickly generate ecommerce revenue? Consider a flash sale! During a flash sale (also called a high volume or hype sale), a large amount of traffic is driven to a storefront for a limited number of products. Like with a brick-and-mortar event of this type, traffic management is a key consideration when planning a flash sale. Although flash sales can put an unprecedented load on your site, pushing the boundaries of scalability and availability, your site can handle the traffic with the right preparation. When you hold a flash sale on Salesforce B2C Commerce, consider these best practices

## Engage Salesforce Early

When you start planning for a flash sale, it’s always a good idea to engage the Salesforce B2C Commerce team. Our systems are designed and built for high scale and availability. Making sure our teams know about your upcoming spike in traffic and orders can create a smoother experience for you and your shoppers. We can guide you through the best practices and help you with factors unique to your situation. In addition to the guidelines and considerations provided here, it’s vital that you notify B2C Commerce Support in advance of your upcoming flash events. Open a case in the Support Portal and provide the details listed in the following article: [Sales Event Preparation checklist / Assessment for a B2C Commerce Storefront](https://help.salesforce.com/s/articleView?id=000391437&type=1).

## Disable or Reschedule Jobs

To make sure that critical resources are available when shoppers visit your storefront during a flash sale, disable or reschedule non-critical jobs until after the sale concludes. This includes code and data replications, order export jobs, catalog and inventory imports, and index rebuilding.

## Schedule Replication and Caching Activities Well before Your Sale

To make sure that the cache has adequate time to warm up before your flash sale starts, don’t clear or invalidate the page cache close to the start of your sale. Likewise, schedule replication activities at least four hours prior to the start of the flash sale.

## Block Unwanted Traffic by Using Built-in eCDN Functionality

Use the built-in eCDN functionality and consider increasing the threat level or even enabling Under Attack mode during a flash sale. Under Attack mode presents a CAPTCHA to every unique user before they're allowed to see the storefront. For more information, see [Configure the Embedded CDN](https://help.salesforce.com/s/articleView?id=cc.b2c_configure_the_embedded_cdn.htm&type=5).

On a storefront that runs on Managed Runtime (Composable Storefront or Storefront Next), bots can also skip the storefront CDN and call Shopper APIs directly. Starting with B2C Commerce 26.10, block that path on the SCAPI zone. Enable **Managed Runtime SCAPI Request Identification**. Salesforce adds a locked allow rule on the zone's **Security Rules** tab. You add the block rule on that tab. Scope it to that instance's org-specific path segment and to Shopper API paths (`/shopper`), so Admin API and B2C CLI calls aren't affected. Place it directly after that instance's allow rule. To protect one custom endpoint instead, use the org segment and `/custom/<api>`. Use `block`, not Managed Challenge. Run the rule in `log` mode before the sale, and don't switch it to `block` during the event. Enabling the feature switch alone doesn't stop direct Shopper API calls. See [How do I restrict SCAPI to Managed Runtime traffic?](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/bot-management.md#how-do-i-restrict-scapi-to-managed-runtime-traffic), [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-request-identification.html) for Composable Storefront, and [Restrict SCAPI Access to Managed Runtime Traffic](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-scapi-request-identification.html) for Storefront Next.

## Leverage the Web Services Framework for Third-Party Integrations

When planning for spikes related to flash sales, it’s easy to overlook third-party integrations across your site, in particular in the checkout flow. These integrations might not be designed for high scalability like B2C Commerce. Consider leveraging our services integration framework for defining third-party integrations. When performance degrades for these integrations, our services framework is designed for non-disruptive failover and rate limiting. The B2C Commerce platform provides a framework that wraps requests to third-party services (frequently made as part of a checkout flow) to provide monitoring and guardrails for them.

Third-party service calls can have a significant performance impact on your entire site when the third-party service stops responding or responds slowly. With the services framework provided by Commerce Cloud, adjust the response timeout settings and locking settings for individual services, or disable a service altogether. A single slow-responding service, when not properly safeguarded, has the ability to severely impact the usability of your storefront for all shoppers. In the worst case scenario, a slow-responding service can render your site unusable. Set timeouts for all third-party service requests, based on the typical responsiveness of the service. Generally, B2C Commerce guidelines suggest two seconds or less for non-checkout services, and five to 10 seconds or less for checkout services. For more information, see [Web Services](https://help.salesforce.com/s/articleView?id=cc.b2c_web_services.htm&type=5). We also recommended that you contact all third-party service providers ahead of your flash sale, so they can make preparations. To prevent overloading database resources if a third-party integration stops working, avoid placing web services in business logic that opens a database transaction.

## Avoid Making Product IDs Available Before the Sale

When product IDs are available prior to a flash sale, shoppers can make preparations to bypass normal page and checkout flows, resulting in an unfair advantage. This behavior affects the scalability of the flash sale, because requests to add a product to a cart and checkout are resource-intensive operations on the platform. During a flash sale, these operations occur at a much greater ratio than usual. In addition, not providing product IDs makes the creation of automated bots and scripts more challenging.

## Set Up Real-time Rate Limiting Capabilities

Set up the ability to rate limit requests made to the storefront and adjust the rate limit configuration in real time. Often a bot or script can make a large number of requests in a short amount of time (much greater than that of human shoppers). When properly configured, throttling or rate limiting incoming requests typically impacts only the bot or script requests and not your actual shoppers. Many CDNs have the capability to rate limit incoming requests based on a number of configuration parameters, and a Web Application Firewall (WAF) can do real-time analysis of incoming requests based on a predefined set of rules.

During a volumetric attack that affects availability or performance, B2C Commerce implements mitigations—such as rate limiting or managed challenges—to block bad actors from continuing their attacks, with as little impact to legitimate shoppers as possible, often none at all. Engaging Salesforce Support before your sale (see [Engage Salesforce Early](#engage-salesforce-early)) helps distinguish your expected traffic from an attack pattern.

## Plan for Bot Mitigation

To help make sure human shoppers are buying products during your flash sale, plan ahead for bot mitigation. Flash sales that offer deeply discounted or strictly limited stock tend to attract malicious users, who try to amass a large inventory of the discounted products to resell later for a profit. The deeper the discount and the more limited the inventory, the higher the risk of bot traffic overwhelming your site. Consider the following strategies to reduce bots from getting large amounts of inventory.

1. Wait until the last minute to announce the sale. Bots take time to write and must be customized to your checkout process. Segment the sale to a separate portion of your site and send out the sale announcement via social media only.
2. Change a portion of the checkout flow during the flash sale. For example, add an interstitial page that requires the shopper to click something, or enable CAPTCHA. CAPTCHA is extremely useful in mitigating bot traffic. Placing the CAPTCHA implementation before the add-to-cart operation provides the added benefit of controlling the flow of requests to the add-to-cart pages.
3. Require an account to make a purchase. This option works only if you implement custom code rate limits. For example, consider placing limits on how many orders can be placed per second, per account, or how many credit cards are allowed per account.
4. Consider deploying a bot mitigation service, especially if you’re selling collectibles or other desired products. Services that we offer in our LINK Partnership include PerimeterX and DataDome. Bot management solutions offer advanced detection features to identify human users without negatively impacting the shopper experience and advanced mitigation options, like honeypots for huge downloads that increase the cost to the bot owner.
5. Require preregistration that includes payment authorization to make sure there is real interest in your flash sale

   - For payment processing:
     - Integrate your site with a payment or fraud detection provider.
     - Create a specific risk profile with more strict rules for purchasing. For example, place an order limit for each shipping address, IP address, or email. Such a profile also can block known fraudulent users based on ZIP code, email, and so on.
     - Activate the risk profile only for the duration of the sale to avoid impacting regular business.
   - During presale processes, monitor site behaviors as soon as sale products are announced. You can potentially discover endpoints that bots exploit, or patterns that they might use on the day of your hype sale.

## Consider a Lite Version of the PDP

Consider presenting a lightweight version of the product details page (PDP) prior to the product being available, such as a PDP without an Add to Cart button or link. This approach supports the caching of key page elements prior to the product being available for purchase, which improves page performance during the sale. Plan ahead for the proper segmentation of cacheable elements (using remote includes) and allow enough time for caching (in general, 24 hours or more for most PDP elements).

## Manage When Inventory Reservation Occurs

As a best practice for flash sales, avoid reserving the inventory when shoppers add products to the cart. Reserving products when they are in the cart tends to result in a higher number of abandoned carts and aborted checkouts compared to reserving the product inventory when the order is submitted.

Moving the inventory calculation logic to the very end of the checkout process helps to make sure there is high order throughput and low contention by selling on a first-come-first-serve basis. However, if your business requirements support inventory reservation in the cart, consider the following tips:

- Make the reservation time as short as possible to avoid aborted sessions from blocking the checkout for other shoppers. Longer reservation times increase the chance of artificially prolonged or abandoned events.
- Consider using a different checkout flow just for flash sale products. Allowing carts with a mix of flash sale and regular products adds overhead, because all items in the cart are reserved. In this case, the size of the cart directly impacts the possible throughput for the high-demand sale products.

## Set up a Raffle or Reservation System

Just like with brick-and-mortar flash events when a large amount of foot traffic is expected at a physical location, using a raffle system can help manage the traffic that’s allowed into a virtual storefront. A raffle or reservation system generates flash around your promotion but reduces traffic to the specific products that are available in limited quantities. Only certain shoppers, like raffle winners or those with reservations, are granted access to purchase those products.

## Create a Virtual Waiting Room

To help make sure your backend systems aren’t overwhelmed by demand for popular products in limited stock, create a virtual waiting room. Waiting rooms limit the number of shoppers allowed to purchase products at a given time. When the maximum number of shoppers is reached on designated pages, new shoppers receive a waiting page that doesn’t access backend systems. When paired with presale load testing and traffic forecasting, waiting rooms help control the storefront load while maintaining a positive shopper experience.

Implement the waiting room for more than just your home page. When you include all the pages that a shopper visits to purchase flash sale products, you help prevent shoppers from bypassing the waiting room. To control storefront traffic, you also can apply waiting rooms in front of the storefront.

In addition, configure the number of shoppers allowed in a waiting room at a given time. This number can even be dynamic based on the percentage of shoppers on your site. Visitor Prioritization Cloudlet from Akamai offers such a solution. For example, you can specify that only 1% of shoppers are allowed into the waiting room. If you have 100,000 shoppers on your site, only 1,000 are allowed into the waiting room.

By implementing these traffic management best practices, you can host a flash sale knowing that your site can scale to handle the additional traffic. And remember: When you start planning for a flash sale, engage the Salesforce B2C Commerce team. We’re here to help!

<!-- document id=fc87fdecc39f021b78b5d2d20037f3753fb2450cb327aff3d7b672113b9d3251 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-transaction-management.md -->

# Transaction Management for Checkout Session APIs

The UCP Checkout Session APIs are Salesforce Commerce API (SCAPI) resources, not storefront controllers or OCAPI endpoints. That means when you extend the UCP Checkout Session APIs with hooks, your custom code runs inside a database transaction that the platform manages for you. Understanding where the transaction boundaries are — what is committed, what is rolled back, and where your hook runs relative to those boundaries — is essential to writing correct customizations for the create, get, update, complete, and cancel operations.

The Checkout Session APIs power headless checkout. Because the flow is headless, no storefront controller logic runs—only the server-side hooks described in this topic execute. Your customizations must live in these hooks.

**note:** The transaction behavior described in this topic is a platform implementation detail. Hook extension points and ordering reflect the current implementation and can change. This topic covers B2C Commerce transaction management; it doesn't describe the checkout protocol itself.

## The Checkout Session APIs Are SCAPI APIs

Like all SCAPI resources, each UCP state-changing request runs its system logic and hooks inside one platform-managed transaction—the standard contract described in [Extensibility via Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html). Two things make UCP different from a typical SCAPI resource, and both matter when you adapt existing hook code:

- The `complete` operation departs from the one-transaction-per-request model that the other operations follow (see [The Complete Transaction Model](#the-complete-transaction-model)).
- `Transaction.wrap()` behaves differently across channels. An SFRA storefront hook opens its own script transaction, and so can the Checkout Session `create`, `update`, and `cancel` hooks—but the `complete` flow already runs inside a platform-managed transaction where no script transaction is open, so calling `Transaction.wrap()` there can fail. Shared helper code must account for the channel it runs in (see [Sharing Hook Code Between SFRA and Checkout Session APIs](#sharing-hook-code-between-sfra-and-checkout-session-apis)).

## Transaction Responsibilities

Transaction management for Checkout Session hooks is a shared responsibility:

| Responsibility                                           | Owner                     |
| -------------------------------------------------------- | ------------------------- |
| Beginning, committing, and rolling back transactions     | Salesforce (the platform) |
| Returning a `Status` to signal success or failure        | You                       |
| Correctness and performance of the code inside your hook | You                       |
| Placing external callouts in the correct hook            | You                       |

You never call `begin()`, `commit()`, or `rollback()` yourself. Instead, you return a `Status` object, and the platform commits or rolls back the surrounding transaction based on that status.

## The Standard Transaction Model

For create, update, and cancel, the entire operation runs inside a single database transaction. The system logic that modifies the basket and the `after` hook both participate in that one transaction. Either everything commits, or nothing does.

This is the same contract documented for OCAPI and other SCAPI customizations: for state-changing HTTP methods like POST, PUT, PATCH, and DELETE, the server executes the `after` hook logic plus the system logic in the context of one database transaction. The transaction commits everything into the database, or nothing.

The processing flow for a create request:

| Processing Step                            | Comment                                                                                                                                                      |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Server receives the `create` request       | The server begins the transaction.                                                                                                                           |
| Server applies system logic                | The server creates the basket and applies line items, discounts, and defaults.                                                                               |
| Server calls the `beforePOST` hook         | Your code can observe the basket before it is fully populated. Returning an `ERROR` status stops processing and rolls back the transaction.                  |
| Server calls the `afterPOST` hook          | Your code can adjust the basket. The platform runs the basket calculation here. Returning an `ERROR` status stops processing and rolls back the transaction. |
| Server commits the transaction             | All basket changes from the steps above are persisted together.                                                                                              |
| Server calls the `modifyPOSTResponse` hook | Runs **after** the commit, outside any transaction. Use it to shape the response document only.                                                              |
| Server sends the response                  | The server renders and returns the response document.                                                                                                        |

The update operation follows the same pattern with `beforePUT`, `afterPUT`, and `modifyPUTResponse`. The get operation is a read and doesn't run in a state-changing transaction.

**note:** Don't modify a Script API object in an HTTP GET request or a `modifyResponse` hook, because they aren't executed in a transaction. Doing so can cause an `ORMTransactionException` and an HTTP 500 fault response. To persist a change, make it in a `before`/`after` hook, `complete.beforePOST`, `complete.afterPOST`, or a payment hook instead.

## The Complete Transaction Model

The complete operation combines several traditionally separate operations—order creation, payment authorization, and order placement—and therefore uses **more than one** transaction. Atomicity does **not** span the whole request. This is the most important difference to understand before you customize the complete flow.

| Transaction                  | Steps                                                                                                                     | Your hooks                                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Transaction 1                | Update billing address, build payment instruments, create the order from the basket                                       | `complete.beforePOST`, `payment.buildPaymentInstrumentRequest` (DIY), `payment.beforeOrderCreate` |
| Transaction 2                | Authorize payment and place the order if fully authorized                                                                 | `payment.authorize` (DIY only)                                                                    |
| Transaction 3 (compensating) | Runs only if Transaction 2 fails: clean up the basket and fail the order, reopening the basket                            | —                                                                                                 |
| After Transaction 2          | Own nested transaction after Transaction 2 has committed (order is placed on DIY; still `CREATED` on Salesforce Payments) | `complete.afterPOST`                                                                              |

If Transaction 3 also fails, the scheduled Auto-Fail-Orders job is the backstop.

The consequences for your custom code:

- A hook error in **Transaction 1** (for example, `complete.beforePOST` returns `ERROR`) rolls back Transaction 1. No order is created and no payment is authorized. Because no external payment provider has been called yet, nothing is left stranded.
- A failure in **Transaction 2** does **not** roll back the order created in Transaction 1—the order already exists. Instead, the platform runs the compensating Transaction 3 to fail the order and reopen the basket. `complete.afterPOST` doesn't run.
- Place any hook logic that has an **external payment side effect** (such as a call to a payment service provider) in the **`authorize`** hook, which runs in Transaction 2. That way a rollback of the order-creation transaction can't leave a dangling authorization.
- **`complete.afterPOST`** runs after Transaction 2 has committed. A failure there doesn't un-place the order, but it can still fail the `/complete` HTTP response. See [Post-Placement Actions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#post-placement-actions).

On the **third-party (DIY)** path, Transaction 2 places the order when `authorize` succeeds and the authorized amount covers the total.

On **Salesforce Payments**, Transaction 2 still runs and starts authorization, but the order is **not** placed in Transaction 2. The order stays `CREATED` until the gateway webhook arrives:

- **Adyen via Salesforce Payments:** `AUTHORISATION`
- **Stripe via Salesforce Payments:** `payment_intent.succeeded`

Don't treat a successful `/complete` response as a placed order on the Salesforce Payments path. `complete.afterPOST` still fires after `/complete` succeeds—with a `CREATED` order—so don't send the confirmation email from that hook on Salesforce Payments.

## Hook Catalog

The hook catalog—grouped by create/get/update, cancel, complete, and payment—is in [Extension Hooks Reference](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#extension-hooks-reference). This page covers only the transaction contract around those hooks.

## Controlling the Transaction from Your Hook

Your hook controls the transaction through its return value, following the same contract as other SCAPI hooks:

- If your hook returns an `OK` status, the server continues processing and commits the transaction.
- If your hook returns an `ERROR` status (a handled error), the server stops further processing and rolls back **that hook's** transaction. For create, update, cancel, and complete Transactions 1 and 2, that rolls back the work in that transaction. For Checkout Session APIs, the error is surfaced in the checkout session response.
- If your hook throws an uncaught exception, the server rolls back the transaction and returns an internal error.
- **`complete.afterPOST` is different:** Transaction 2 has already committed. Returning `ERROR` or throwing doesn't un-place the order, but it can still fail the `/complete` HTTP response. Don't return `ERROR` for a failed confirmation email; log it and let a job retry.

```js
var Status = require("dw/system/Status");

exports.afterPOST = function (basket) {
  // Returning ERROR rolls back the transaction — no basket changes
  // from this request are persisted.
  if (shouldBlockCheckout(basket)) {
    return new Status(Status.ERROR, "MY_ERROR_CODE", "Explain what went wrong.");
  }

  // Safe to modify the basket here; changes participate in the transaction.
  // basket.custom.myAttribute = '...';

  return new Status(Status.OK);
};
```

**note:** Return a `Status` object from every hook. If your hook code doesn't return a `Status`, multiple registered hook scripts might be executed, including the overridden base implementation, and one of their return values is used instead of yours.

### Do and Don't

Do:

- Return a `Status` object from every hook.
- Modify persistent objects (the basket or order) only in a `before`/`after` hook (`beforePOST`, `afterPOST`, `beforePUT`, `afterPUT`), `complete.beforePOST`, `complete.afterPOST`, or a payment hook.
- Place external payment callouts in the `authorize` hook so that a rollback of Transaction 1 can't strand them.

Don't:

- Don't begin, commit, or roll back transactions yourself. The platform owns the transaction boundary.
- Don't modify persistent objects in a `modifyResponse` hook or a get flow. It causes an `ORMTransactionException` and an HTTP 500 fault.
- Don't assume complete is atomic end to end. It spans multiple transactions.
- Don't set a payment transaction to `CAPTURED` inside the `authorize` hook.
- Don't treat `complete.afterPOST` as a rollback point for placement, and don't send the confirmation email from that hook on Salesforce Payments.

## Sharing Hook Code Between SFRA and Checkout Session APIs

Many implementations share helper scripts (for example, cart and pricing helpers) between an SFRA storefront and the Checkout Session API hooks. This introduces a subtle transaction-management difference that can cause runtime errors if you aren't aware of it.

`dw.system.Transaction.wrap()` (and `begin()`) doesn't create a transaction on its own—it expects a script transaction to already be open and joins it. The available transaction context differs by execution channel:

| Execution context                           | Transaction context available to your script                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SFRA / SiteGenesis controller               | The request pipeline opens a script transaction for the request, so `Transaction.wrap()` works.                                                                                                                                                                                                                                                             |
| Checkout Session create, update, and cancel | A script transaction is open around the hook, so `Transaction.wrap()` works.                                                                                                                                                                                                                                                                                |
| Checkout Session complete                   | The operation runs inside platform-managed transactions, but a _script_ transaction is not open around every hook. Calling `Transaction.wrap()` from a hook in this flow (including `dw.order.calculate`, `complete.beforePOST`, `complete.afterPOST`, and the payment hooks) can fail with `IllegalStateException: No transaction set for current thread.` |

Because your persistent changes in the complete flow already run inside a platform-managed transaction, they are committed with the operation. Wrapping them again in `Transaction.wrap()` is unnecessary in that flow, and can cause the error above.

**note:** The Script API doesn't expose a way to test whether a transaction is currently open. To decide whether to wrap, detect the execution channel with `dw.system.Request.isSCAPI()` instead. This method returns `true` for Checkout Session API requests and `false` for SFRA storefront requests.

To keep one shared helper working correctly in both channels, wrap only when the code is running outside a Checkout Session API request:

```js
var Transaction = require("dw/system/Transaction");

function persistDerivedValues(lineItem, value) {
  lineItem.custom.myDerivedValue = value;
}

if (request.isSCAPI()) {
  // Checkout Session flow: already inside a platform-managed transaction — write directly.
  persistDerivedValues(lineItem, value);
} else {
  // SFRA and other storefront entry points: open a script transaction.
  Transaction.wrap(function () {
    persistDerivedValues(lineItem, value);
  });
}
```

Guidance for shared helpers:

- Keep the persistence logic in a single function and choose whether to wrap it at the call site based on `request.isSCAPI()`, rather than duplicating the logic.
- Prefer to persist derived values in an `after` hook rather than in a frequently-invoked hook like `dw.order.calculate`, which runs on every recalculation.
- Don't rely on `request.isSCAPI()` as a general "no transaction is open" signal outside of the checkout hook context. In a Custom API that doesn't open a transaction, a direct persistent write would still fail. Use it specifically to distinguish the SFRA and Checkout Session channels for a shared hook helper.

## Performance Considerations

Your hook code runs inside these transactions and, for `modifyResponse` hooks, on the response path. Its execution time is added directly to the API's response time. Shopper APIs must respond in under 10 seconds, or an HTTP 504 timeout is returned and the shopper can't complete the transaction.

- Hooks are always slower than the API alone, because both the API code and your customization run. You're responsible for the performance of the code you add — performance-test your hooks.
- Minimize calls to external systems. If a hook must call an external service, use the [service framework](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html) with aggressive timeout and circuit-breaking settings. Holding a transaction open while waiting on a slow external service risks the 10-second limit — this is especially relevant for the `authorize` hook.
- Cache expensive operations in [custom caches](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-custom-caches.html) rather than recomputing them on every request.
- Use the [code profiler](https://developer.salesforce.com/docs/commerce/commerce-api/guide/code-profiler.html) to find bottlenecks in your hook execution.
- Keep response-shaping logic in `modifyResponse` hooks lightweight, because it runs on every uncached response.

## Summary

| Concern                                 | Answer                                                                                                                                                                                                          |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Who manages the transaction?            | The platform. Never begin, commit, or roll back in a hook.                                                                                                                                                      |
| Where does my code run?                 | Inside the operation's transaction for `before`/`after` and payment hooks; in its own nested transaction for `complete.afterPOST` (after T2 has committed); outside a transaction for `modifyResponse` and get. |
| How do I abort and roll back?           | Return an `ERROR` status, or throw. For `complete.afterPOST`, that does not un-place the order.                                                                                                                 |
| Are create, update, and cancel atomic?  | Yes. One transaction covers the whole operation.                                                                                                                                                                |
| Is complete atomic?                     | No. It spans order-creation, authorization, and compensating fail-order transactions.                                                                                                                           |
| Can I persist data in `modifyResponse`? | No. It's non-transactional. Use a `before`/`after`, `complete.beforePOST`, `complete.afterPOST`, or payment hook.                                                                                               |
| Where do external payment callouts go?  | The DIY `authorize` hook, which runs in Transaction 2.                                                                                                                                                          |
| When is the order placed?               | DIY: Transaction 2. Salesforce Payments: later, on the gateway webhook.                                                                                                                                         |

## See Also

- [Implementation Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md) - Hook architecture, extensibility, and the [hook catalog](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#extension-hooks-reference)
- [Post-Placement Actions](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#post-placement-actions) - Confirmation email and OMS export after complete
- [Third-Party Payment Providers](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md#third-party-payment-providers) - The payment hooks that run in the complete flow
- [Extensibility via Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) - The SCAPI hook execution and transaction contract

<!-- document id=8df4d24a18076b3cbe045d2025767b047addb0fa36594b67dfc874d59e261315 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/transaction-spi.md -->

Transaction SPI

# Transaction SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/transaction-spi/transaction-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are based on lean payload and must be configured in the POS system. These endpoints are the best alternative to the 'Order SPI' as they are based on lean payload.

**Prerequisite:** Make sure that CMS is configured to support the lean input model by setting the property `enableTransactionExport` to `true` in the CMS configuration.

**CMS Configuration:** **CMS** > **Store Management** > **Store Settings** > **Advanced** > **Enable Transaction Export**

**Version:** 2.3.4

## Tags

### Transaction SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/transaction-spi/transaction-spi-oas-public.yaml)

Sample SPIs that demonstrate how to implement SPI endpoints in the merchant's system. These endpoints are based on lean payload and must be configured in the POS system. These endpoints are the best alternative to the 'Order SPI' as they are based on lean payload.

**Prerequisite:** Make sure that CMS is configured to support the lean input model by setting the property `enableTransactionExport` to `true` in the CMS configuration.

**CMS Configuration:** **CMS** > **Store Management** > **Store Settings** > **Advanced** > **Enable Transaction Export**

## Operations

### POST Export transaction.

`POST /merchant/spi/sample/endpoint/sa/orders/transaction/to/export/sale/order/to/external/system`

Operation ID: `exportTransaction`. Tags: Transaction SPI.

Export the POS sale transaction to an external endpoint. This specification provides details for the external endpoint to consume the POS sale transaction. **Prerequisite:** Make sure to configure CMS setting mentioned below: **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `TRANSACTION`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/to/export/sale/order/to/external/system](https://sample/external/to/export/sale/order/to/external/system)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"}
    *   The endpoint with OAuth authorization is supported. For more details, refer to documentation. **Use Case:** The endpoint is used to post the recent transaction to external system or OMS.

#### Request body

Media type: `application/json`. Schema: `ExternalTransaction`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `HttpResponse`.
    

### GET Retrieve BORIS transaction.

`GET /merchant/spi/sample/endpoint/sa/orders/transaction/to/get/boris/order/from/external/system/{orderId}`

Operation ID: `getBorisOrder_1`. Tags: Transaction SPI.

Retrieve a specifically BORIS order from merchant's system in the form of lean payload. Make sure orderId is provided as a path parameter. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `BORIS_GET_TRANSACTION_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from an external system during BORIS flow for merchants that use POS.

****Note:**** For a BORIS order, if the customer initiates the return with an external or alternate receipt ID, this SPI is expected to return the POS Order ID in the field 'borisOrderId'. Either a full Order object is expected or just 'borisOrderId' in the response.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ExternalTransaction`.
    

### GET Retrieve transaction.

`GET /merchant/spi/sample/endpoint/sa/orders/transaction/{orderId}`

Operation ID: `getOrder_2`. Tags: Transaction SPI.

Retrieve order from merchant's system using lean payload. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `GET_TRANSACTION_DETAIL`
    *   **API Endpoint:** Provide the external endpoint to get the order, for example: [https://sample/external/endpoint/to/get/order/from/external/system/456709](https://sample/external/endpoint/to/get/order/from/external/system/456709)
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_GET`
    *   **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the order from merchant's system during return flow if merchant's system is master of record.

#### Parameters

*   `orderId` (path, string, required)

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `ExternalTransaction`.
    

## Schemas

### ExternalTransaction

*   `transactionId` (_string_, required) Transaction Id.
*   `transactionType` (_string_, required) Transaction type.  
    Allowed values: `SALE`, `RETURN`, `EXCHANGE`, `EDIT`, `EDIT_SALE`, `EDIT_REFUND`.
*   `orderId` (_string_, required) Order ID corresponding to the transaction.
*   `externalOrderId` (_string_, nullable) External reference ID if the transaction is captured externally and has a different identifier than orderId.  
    Maximum length: 128.
*   `storeAttribution` (_ExternalStoreAttribution_, required)
*   `tenderList` (_array of ExternalTender_, required) Payment method used towards the sale transaction.
*   `refundTenderList` (_array of ExternalRefundTender_, nullable) Payment method used towards the return transaction.
*   `productList` (_array of ExternalProduct_, required) Products.
*   `returnProductList` (_array of ExternalReturnProduct_, nullable) Returned products.
*   `profile` (_ExternalCustomerProfile_)
*   `deliveryGroupList` (_array of ExternalDeliveryGroup_) In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.
*   `pickUpDetailList` (_array of ExternalPickUpDetail_, nullable) Pickup details.
*   `billingAddress` (_ExternalAddress_)
*   `lastDateToReturn` (_integer (int64)_, nullable) The last date by which the item(s) from the transaction can be returned. If not provided, the item can be returned without any time limitation. The date is in milliseconds since epoch.  
    Example: `1653078974310`.
*   `saleSummary` (_ExternalTransactionSummary_, required)
*   `orderSource` (_string_, required) Channel of the transaction.  
    Allowed values: `DEFAULT`, `IN_STORE`, `POPUP_STORE`, `WEB`, `APP`, `OUTLET_STORE`, `ONLINE`, `POS_EA`.
*   `orderType` (_string_, nullable) Order type. It is needed if the order is fulfilled by store. For example, BOPIS, BOFIS.  
    Allowed values: `STORE_PICKUP`, `STORE_FULFILLMENT`, `LAYAWAY`, `MIXED_MODE`, `ONLINE`, `ONLINE_RESERVE`.
*   `status` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`.
*   `noteList` (_array of ExternalNote_, nullable) Notes for the transaction.
*   `originalOrderId` (_string_) An exchange involves both returning items from the original sale and purchasing new items, resulting in a new sale. The original order ID will provide the order ID for the original sale for the exchanges.
*   `orderFulfillmentType` (_string_, nullable) Order Fulfillment Type, It is indicate of fulfillment type of order level Eg. IN\_STORE, ONLINE or MIXED\_CART.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `taxExemptionList` (_array of ExternalTaxExemption_, nullable) Applied tax exemptions.
*   `tariff` (_number_, nullable) The tariff amount at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs** and is included only when the tariff configuration is available in CMS.
*   `tariffRate` (_number_, nullable) The tariff rate at the time of sale. This value is retrieved from **CMS** > **Store Settings** > **Tariffs and** is included only when the tariff configuration is available in CMS.

### HttpResponse

*   `statusLine` (_StatusLine_)
*   `statusCode` (_integer (int32)_, write-only)
*   `reasonPhrase` (_string_, write-only)
*   `entity` (_HttpEntity_)
*   `locale` (_object_)
    *   `language` (_string_)
    *   `script` (_string_)
    *   `country` (_string_)
    *   `variant` (_string_)
    *   `unicodeLocaleAttributes` (_array of string_)  
        Unique items.
    *   `unicodeLocaleKeys` (_array of string_)  
        Unique items.
    *   `displayLanguage` (_string_)
    *   `displayScript` (_string_)
    *   `displayCountry` (_string_)
    *   `displayVariant` (_string_)
    *   `displayName` (_string_)
    *   `extensionKeys` (_array of string_)  
        Unique items.
    *   `iso3Language` (_string_)
    *   `iso3Country` (_string_)
*   `protocolVersion` (_ProtocolVersion_)
*   `allHeaders` (_array of Header_)
*   `headers` (_array of Header_, write-only)
*   `header` (_Header_)
*   `params` (_HttpParams_)

### ExternalStoreAttribution

Store details.

*   `storeAssociateId` (_string_, required) Store associate ID who is ringing the transaction.
*   `storeId` (_string_, required) Store ID.  
    Maximum length: 128.
*   `storeRegisterId` (_string_, required) Store register ID where the transaction is performed.  
    Maximum length: 128.
*   `eventTimeStamp` (_integer (int64)_, required) Transaction timestamp in epoch millis.
*   `storeAssociateRole` (_string_, required) Store Associate's Role.
*   `secondsFromGMT` (_integer (int64)_, required) Time offset of the register's timezone from UTC in seconds.
*   `tillSessionId` (_string_, required) Till session ID.
*   `tillId` (_string_, required) Till ID.
*   `installationId` (_string_, nullable) Device identifier which was used to place the order. It is mandatory for transactions performed in the store. For external transactions, it will be defaulted to 'EXTERNAL' if it is not provided.  
    Maximum length: 128.
*   `registerMode` (_string_, required) The mode of the register operation.  
    Allowed values: `ONLINE`, `OFFLINE`. Default: `ONLINE`.

### ExternalTender

Payment method used towards the sale transaction.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `paymentId` (_string_, required) Unique identifier for a payment/tender. As the order can have multiple payments, each payment has a unique payment ID.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `paymentStatus` (_string_, required) Payment status. UNPROCESSED is used internally by cloud services as a transient state. DISCARDED is used when cash tender is in multi-tender and deleted by swiping right. ABORTED is used where we internally remove tender from our tender list and add a new tender, for example, gift card.  
    Allowed values: `UNPROCESSED`, `APPROVED`, `PENDING`, `DECLINED`, `CANCELED`, `REVERTED`, `REVERSAL_FAILURE`, `UNKNOWN`, `NOT_FOUND`, `NOT_APPLICABLE`, `ABORTED`, `DISCARDED`, `FAILED`, `UNVERIFIED`, `EXPIRED`, `SAF_DECLINED`, `SAF_UNKNOWN`.
*   `paymentDevice` (_string_, required) Identifies the payment device through which the payment is made. If payment data is manually entered, this field should be set to NoReader. If payment is made in an external system, payment device should be set to External.  
    Allowed values: `Adyen`, `PayPal`, `VerifonePSDK`, `Square`, `CheckReader`, `NoReader`, `External`, `StoredCard`, `Stripe`, `Elavon`, `Aurus`.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry). Mandatory for CreditCard, GiftCard.  
    Maximum length: 128.
*   `cardType` (_string_) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `amountAuthorized` (_number_, required) Amount paid using this tender.
*   `authorizationToken` (_string_) Payment authorization token.  
    Maximum length: 128.
*   `authorizationDate` (_integer (int64)_) Payment authorization timestamp in EPOCH millis.
*   `captureToken` (_string_) Payment capture token.  
    Maximum length: 128.
*   `captureDate` (_integer (int64)_) Payment capture timestamp in EPOCH millis.
*   `firstName` (_string_) First name to use for billing using this tender.  
    Maximum length: 64.
*   `lastName` (_string_) Last name to use for billing using this tender.  
    Maximum length: 64.
*   `addressLine1` (_string_) Address line 1 to use for billing using this tender.  
    Maximum length: 256.
*   `addressLine2` (_string_) Address line 2 to use for billing using this tender.  
    Maximum length: 256.
*   `city` (_string_) City to use for billing using this tender.  
    Maximum length: 64.
*   `state` (_string_) State to use for billing using this tender.  
    Maximum length: 32.
*   `postalCode` (_string_) Postal code to use for billing using this tender.
*   `country` (_string_) Country code to use for billing using this tender.  
    Maximum length: 16.
*   `requestId` (_string_, nullable) Payment request identification issued by the payment gateway/terminal.  
    This field is typically used for referenced refunds that are performed automatically  
    by the POS without the customer presenting the card during a refund.  
    In the case of Adyen payments, this field maps to pspReference.  
    It is mandatory for credit cards.  
    Maximum length: 256.
*   `alternateRequestId` (_string_, nullable) When a payment terminal is in store and forward mode,  
    it generates a temporary payment ID, which is provided in the alternate payment  
    request ID attribute. For instance, the Adyen terminal generates a temporary ID  
    called a 'tender reference' whenever it goes into a store and forward mode.  
    This tender reference is then populated in the alternate payment request ID attribute.  
    Maximum length: 50.
*   `copiedFromOrderId` (_string_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried forward to  
    the new order. This attribute provides the original order ID if the tender is carried  
    over to the new order during the exchange.  
    Maximum length: 128.
*   `totalRefundedAmount` (_number_, nullable) Total Refunded Amount if any which is already paid back due to returns + exchanges. Not applicable, if no refund issued yet.  
    Default: `0`.
*   `totalAmountCarriedOverForExchange` (_number_, nullable) When an item is exchanged, a new order is created for the replacement item,  
    and the original order is updated to a returned/exchanged status.  
    Additionally, the tender value of the replacement item's cost is carried over to  
    the new order. This carried over amount is provided in this attribute. It is mandatory if the order is exchanged and tender is carried over to new order.  
    Default: `0`.
*   `receiptLines` (_array of PaymentReceiptLine_) Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.
*   `paymentSequenceNumber` (_integer (int32)_, required) Payment sequence indicating the order of payment. For example, if customer pays partially with cash first and remaining with credit card, then cash tender should have paymentSequenceNumber as 1 and credit card tender should have paymentSequenceNumber as 2.
*   `paymentDeviceId` (_string_) Unique identifier like serial number for payment reader. Used in case of client/app side card encryption by readers like Verifone.  
    Maximum length: 32.
*   `routingNumber` (_string_) Bank routing number.  
    Maximum length: 32.
*   `accountNumber` (_string_) Account number. Used for payment through banking system.  
    Maximum length: 32.
*   `checkNumber` (_string_) Check number. Used for payment through checks.  
    Maximum length: 50.
*   `cardToken` (_string_) This is the tokenized value for payments made via Credit Card, Pay By Link, or Remote Pay By Link. Please note that tokenization is only supported for Adyen and must be configured in the CMS (**CMS** > **Integration** > **Payment Gateways** > **Adyen** > **Payment Tokenization Events**).  
    Maximum length: 128.
*   `personalIdType` (_string_, nullable) Personal identification type. Applicable for Check and Finance.  
    Allowed values: `DriversLicense`, `StateID`, `MilitaryID`, `Passport`, `StudentID`, `PermanentResidentID`, `TribalID`, `BusinessPhone`.
*   `personalIdIssuedBy` (_string_) Authority that issued the personal identification. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdNumber` (_string_) Personal identification number. Applicable for Check and Finance.  
    Maximum length: 32.
*   `personalIdExpiryDate` (_integer (int64)_) Personal identification expiry date represented as milliseconds since epoch. Typically expiry date is end of the day and milliseconds since epoch should reflect it accordingly. Applicable for Check and Finance.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month. Applicable for credit card.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year. Applicable for credit card.
*   `externalPaymentSystemId` (_string_) External payment system identifier in case of External tender.  
    Maximum length: 32.
*   `externalPaymentReferenceId` (_string_) External payment reference identifier in case of External tender.  
    Maximum length: 32.
*   `checkType` (_string_) Type of the check - Personal or Business.  
    Allowed values: `Personal`, `Business`.
*   `manualAuthorizationCode` (_string_, nullable) Manual authorization code for a tender.  
    Normally it is received after calling a call center agent of a payment processor.  
    Eg. Call for auth code after check denial/ referral,  
    manual auth code for credit card when offline.  
    Maximum length: 50.
*   `cashDrawerUrl` (_string_, nullable) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `roundingAmount` (_number_, nullable) Rounding amount for the payment. Applicable for cash tender  
    in regions where rounding is applicable.
*   `refundFeeAmount` (_number_, nullable) Refund fee like restocking fee.  
    Applicable when order is returned and refund fee is configured.
*   `authStatus` (_string_) Auth status of Credit card payment.  
    Allowed values: `PRE_AUTH`, `AUTH`, `SALE`, `VOID`, `VOID_FAILED`.
*   `tip` (_number_, nullable) Tip amount. Applicable when tipping is enabled.
*   `captureStatus` (_string_) Capture status of authorized amount.  
    Allowed values: `CAPTURED`, `CAPTURE_FAILED`, `NON_CAPTURED`, `PARTIALLY_CAPTURED`, `VOID`, `VOID_FAILED`.
*   `financeOrderNo` (_string_) Refers to Finance approval/order/confirmation no. in external system.  
    Maximum length: 32.
*   `financeInstruction` (_string_) Refers to Finance processing related result/instruction long text from external system.  
    Maximum length: 4096.
*   `primaryAccountHolder` (_string_) Primary owner on the account.  
    Maximum length: 128.
*   `fundingSource` (_string_, nullable) Funding source, for example, PREPAID, DEBIT, or CREDIT. Applicable for credit cards.  
    Allowed values: `CHARGED`, `CREDIT`, `DEBIT`, `PREPAID`, `DEFFERED_DEBIT`, `PREPAID_RELOADABLE`, `PREPAID_NONRELOADABLE`, `STORE_VALUE`, `EBT`, `ALTERNATE_TYPE`, `CHECK`, `MOBILE`, `CASH`.
*   `paymentLink` (_string_) Payment Link.  
    Maximum length: 128.
*   `paymentLinkExpiryDate` (_integer (int64)_) Payment link expiry timestamp in EPOCH millis.
*   `captureAmount` (_number_, nullable) Amount captured for credit card. Applicable, if capture flow is enabled.
*   `requestTokenExpireDate` (_integer (int64)_) Request token expire date in EPOCH millis.
*   `termsAndConditions` (_string_, nullable) Terms and conditions. Used for finance tender.  
    Maximum length: 4096.
*   `tenderBalance` (_number_, nullable) Balance amount remaining in the gift card tender.
*   `tenderedAmount` (_number_, nullable) The cash amount tendered for this transaction.
*   `changeBackAmount` (_number_) The remaining change amount in case of cash tender.
*   `cardAlias` (_string_, nullable) Card alias provided in the payment response by gateway. In adyen - a value that uniquely represents the shopper's card number (PAN).
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.

### ExternalRefundTender

Payment method used towards the return transaction.

*   `transactionId` (_string_, required) It is a unique identifier for a transaction that completes the order.  
    This is particularly helpful in cases where a payment is made in multiple transactions  
    such as in the case of a deposit. In POS, the transaction ID will  
    correspond to the sale transaction when you place an order. However, if you import an  
    order from an external system, the transaction ID should correspond to the order in  
    the external system and can be the same as the OrderID.  
      
    Maximum length: 128.
*   `originalTransactionId` (_string_, required) Transaction identifier as part of which this payment was initiated originally and now being refunded.
*   `originalPaymentId` (_string_, required) Payment Identifier as part of which this payment was initiated originally and now being refunded.
*   `paymentMethod` (_string_, required) Identifies the payment method.  
    Allowed values: `Cash`, `CreditCard`, `GiftCard`, `PLCC`, `Check`, `ACH`, `Miscellaneous`, `ApplePay`, `AndroidPay`, `Finance`, `RewardCard`, `PayPal`, `StoreCredit`, `CreditCard_Visa`, `CreditCard_MasterCard`, `CreditCard_Amex`, `CreditCard_Discover`, `eGiftCard`, `WeChatPay`, `AliPay`, `PayByLink`, `RemotePayByLink`, `Installments`, `Reward`, `GooglePay`, `Affirm`, `Afterpay`.
*   `cardNumber` (_string_) Card number. Could be either partial (last 4 digits) or complete card number (in case of manual credit card data entry). Mandatory for CreditCard, GiftCard.  
    Maximum length: 128.
*   `cardType` (_string_) Card type, for example, Visa, Mastercard, Amex, or Discover. Required for CreditCard.  
    Maximum length: 128.
*   `cardBin` (_string_, nullable) Card BIN (Bank Identification Number) - first 6 or 8 digits of the card number.
*   `refundRequestId` (_string_, required) Refund ID issued by the payment gateway. Mandatory for refund on credit card.
*   `refundedAmount` (_number_, required) Amount refunded.
*   `cardExpirationMonth` (_integer (int32)_) Card expiry month.
*   `cardExpirationYear` (_integer (int32)_) Card expiry year.
*   `cashDrawerUrl` (_string_) Represents custom URL using which cash drawer in the network can be accessed. Mandatory for cash payment with cash drawer having URL\_VIA\_QR\_CODE mode.  
    Maximum length: 256.
*   `cardAlias` (_string_, nullable) Card alias associated with Refund Tender. In adyen - a value that uniquely represents the shopper's card number (PAN).

### ExternalProduct

Products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.

### ExternalReturnProduct

Returned products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.
*   `exchangedForOrderId` (_string_, nullable) Applicable for exchange of the item. A separate order will be generated for the new item when an exchange occurs. The order ID corresponding to the new item related to the exchange will be provided here.  
    Maximum length: 128.
*   `exchangedForProductId` (_string_, nullable) Applicable for exchange of the item. A separate order will be generated for the new item when an exchange occurs. Please provide the order ID for the new item related to the exchange.  
    Maximum length: 128.

### ExternalCustomerProfile

Customer profile. It is mandatory for customer logged-in during the transaction. It is optional for guest customer.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.  
    Maximum length: 128.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.  
    Maximum length: 128.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.

### ExternalDeliveryGroup

In the event that the transaction comprises any delivery item, a list of delivery groups is required. Each delivery item is associated with a delivery group via a deliveryGroupId link.

*   `deliveryGroupId` (_string_, required) Delivery group ID.
*   `fulfillmentType` (_string_, required) Fulfillment type.  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup, i.e., buy online ship to store |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `BOSS`, `BOPIS`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `shippingMethod` (_ShippingMethod_, required)
*   `shippingAddress` (_ExternalAddress_, required)
*   `dateTimeSlot` (_DateTimeSlot_, required)
*   `fulfillmentAddress` (_ExternalAddress_)
*   `externalDeliveryGroupId` (_string_, nullable) External delivery group id: This ID can be provided when importing an order into POS from an external system. While POS does not use this ID for internal processing, it saves the ID and relays it back to the external system during order posting after any modification.  
    Maximum length: 128.

### ExternalPickUpDetail

Pickup details.

*   `pickupDetailId` (_string_)
*   `storeId` (_string_)
*   `storeAssociateId` (_string_)
*   `firstName` (_string_)
*   `lastName` (_string_)
*   `email` (_string_)
*   `phone` (_string_)

### ExternalAddress

Billing address.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, required, nullable) Customer first name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `addressLine1` (_string_, required, nullable) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required, nullable) City.  
    Maximum length: 64.
*   `state` (_string_, required, nullable) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required, nullable) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, required, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `addressType` (_string_, nullable) Address type- Home, Business.
*   `emailAddress` (_string_, nullable) Customer Email Address.  
    Maximum length: 64.
*   `country` (_string_, nullable) Country.

### ExternalTransactionSummary

Payload that contains a transaction (Sale or Return) summary.

*   `subTotal` (_number_, required) Total Item price.
*   `discount` (_number_, nullable) Total price override and promo coupons applied. Applicable if any item level price override applied or any promotion (auto or coupon) applied.
*   `transactionDiscountAmount` (_number_, nullable) Total transaction discount. Applicable if any transaction discount is applied.
*   `rewardAmount` (_number_, nullable) Total reward amount. Applicable if any reward coupon is applied.
*   `tax` (_number_, nullable) Total Tax.
*   `taxExemption` (_number_, nullable) Total Tax Exemption.
*   `valueAddedTax` (_number_, nullable) Total Value Added Tax.
*   `shippingCharges` (_number_, nullable) Total shipping charges.
*   `total` (_number_, required) Item total inclusive of all charges like taxes and discounts and exclusive of tip amount.
*   `roundingAmount` (_number_, read-only) The delta amounts because of rounding applied on grand total or refund total of the cart.
*   `paidAmount` (_number_, read-only) The amount paid already towards the ongoing transaction. It is used during deposits,layway and edit order.
*   `amountToBeCharged` (_number_, read-only) Net amount that customer is going to pay as charges or receive as refund. It is derived based on this formula = (Total Sale - Paid amount - Total Refund).
*   `refundFeeAmount` (_number_) Refund fees applied when cancelling items from an order during the edit order flow. Not applicable for sale transactions and not populated in the sale summary.
*   `minTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Minimum transaction discount that must be applied to cover for transaction discount already applied on already fulfilled products.
*   `maxTransactionDiscountAmount` (_number_) Used in edit order flow and will be populated only in net summary of the cart. Maximum transaction discount that can be applied.
*   `netSubTotal` (_number_) Net SubTotal- represents Item sub total minus the discounts/price overrides if any.
*   `nonMerchTotal` (_number_, nullable) Total of non merchandising items.
*   `tipTotal` (_number_, nullable) Total Tip.
*   `inStoreTotal` (_number_, nullable) In store total.

### ExternalNote

Notes for the transaction.

*   `cartId` (_string_)
*   `noteId` (_string_)
*   `noteText` (_string_)
*   `transactionId` (_string_)

### ExternalTaxExemption

Applied tax exemptions.

*   `taxExemptCode` (_string_, required) Tax exemption code.  
    Maximum length: 128.
*   `customerName` (_string_, required) Customer name for an individual who has tax exemption applied.  
    Maximum length: 128.
*   `cardNumber` (_string_, required) Customer's tax-exemption card number.  
    Maximum length: 64.
*   `notes` (_string_, nullable) Optional notes for tax exemption entered during checkout on the POS.  
    Maximum length: 128.
*   `taxExemptionRate` (_number_, required) Tax exemption rate.  
    Example: `7.25`.
*   `taxType` (_string_, nullable) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `taxExemptName` (_string_, nullable) Tax exemption name.  
    Maximum length: 128.

### StatusLine

*   `reasonPhrase` (_string_)
*   `protocolVersion` (_ProtocolVersion_)
*   `statusCode` (_integer (int32)_)

### HttpEntity

*   `repeatable` (_boolean_)
*   `streaming` (_boolean_)
*   `chunked` (_boolean_)
*   `content` (_object_)
*   `contentLength` (_integer (int64)_)
*   `contentType` (_Header_)
*   `contentEncoding` (_Header_)

### ProtocolVersion

*   `protocol` (_string_)
*   `major` (_integer (int32)_)
*   `minor` (_integer (int32)_)

### Header

*   `name` (_string_)
*   `value` (_string_)
*   `elements` (_array of HeaderElement_)

### HttpParams

### PaymentReceiptLine

Receipt lines. For information to be shown on receipt. Mandatory for CreditCard payment using Adyen.

*   `key` (_string_, required) Key of the line item.  
    Example: `Total`.
*   `value` (_string_, required) Value of the line item.  
    Example: `34.5699`.
*   `display` (_string_, required) Display value of the line item.  
    Example: `34.57`.

### ExternalStoreAssociateAttribution

Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.

*   `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction.
*   `contributionPercentage` (_number_, required) Associate's contribution towards sales.
*   `attributionNote` (_string_) Note related to attribution.
*   `firstName` (_string_, required) Associate's first name.
*   `lastName` (_string_, required) Associate's last name.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item.
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request.

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### ExternalProductTax

Tax/Vat details.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption.
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates.
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates.
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### ExternalPriceAdjustment

Price adjustments applied on the item.  
It includes all the price adjustments like transaction discount, price override etc...  
Mandatory if any type of price adjustments is applied.

*   `description` (_string_, required) Price adjustment description.
*   `adjustment` (_string_, required) Price adjustment.
*   `id` (_string_) Promotion Id for applied coupon or auto promotion.
*   `price` (_number_, required) Price adjustment amount.
*   `priceAdjustmentType` (_string_, required) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reason` (_Reason_)
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied.  
    Not applicable for auto promotions,  
    manual price adjustments like price override & transaction discount.
*   `auto` (_boolean_, nullable) Applied promotion is auto or not.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system.  
    If an order is placed directly in the POS, this identifier will not be available.  
    The external system provides this identifier, which will then be replayed to that  
    external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.

### ShippingMethod

Available shipping methods corresponding to this delivery group.

*   `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method.  
    Maximum length: 45. Example: `001`.
*   `name` (_string_, required) Shipping Method Name.  
    Maximum length: 128. Example: `Standard Shipping`.
*   `description` (_string_, nullable) Shipping Method Description.  
    Maximum length: 128.
*   `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL.  
    Maximum length: 32. Example: `UPS`.
*   `serviceLevel` (_string_, nullable) Service Level Description.  
    E.g. 3-5 Days, 1-Day, Express, Standard, Overnight.  
    Maximum length: 128. Example: `3-5 Days`.
*   `price` (_number_, required) Shipping cost.
*   `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only.
*   `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount.
*   `sortOrder` (_integer (int32)_) Display Order.  
    Default: `0`.
*   `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.
*   `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable.
*   `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable.
*   `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class.
*   `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied.
*   `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis.
*   `deliveryTimeSlot` (_string_, required) Expected delivery time slot.  
    Example: `09:00 - 12:00`.
*   `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount.

### HeaderElement

*   `name` (_string_)
*   `value` (_string_)
*   `parameterCount` (_integer (int32)_)
*   `parameters` (_array of NameValuePair_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

### PriceAdjustment

Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only.

*   `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional.  
    Maximum length: 1500.
*   `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items.  
    Example: `-155.5`.
*   `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID.
*   `priceAdjustmentType` (_string_) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions.
*   `fulfillmentType` (_string_)  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions.
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT.
*   `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.
*   `adjustmentAmount` (_number_)
*   `referenceAdjustmentId` (_string_)
*   `referenceAdjustmentID` (_string_, write-only)
*   `adjustmentType` (_string_)  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reasonText` (_string_)

### ItemLevelCharge

Item level breakdown for the shipping cost and shipping discount.

*   `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group.  
    Example: `It can have values like 1, 2, 3, etc...<br> which represents line item number within the order or Delivery Group.`.
*   `itemShippingCharge` (_number_) Item level shipping charge.
*   `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward.
*   `discountText` (_string_, nullable) Discount text of an applied promotion.  
    Maximum length: 1500.
*   `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion.

### NameValuePair

*   `name` (_string_)
*   `value` (_string_)

<!-- document id=42d99c536b5f876a5043354233918e5b07ef2ac5be4268cae1d321a7af450b12 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-redirects.md -->

# Trigger Redirects In PWA Kit

:::Note
To redirect whole pages or assets, use the Redirect functionality provided by Runtime Admin or the Managed Runtime API. See [Redirects](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html#redirects).
:::

The Progressive Web App (PWA) Kit uses [React Router](https://v5.reactrouter.com/web/guides/quick-start) redirects.
However, the React Router [Redirect](https://v5.reactrouter.com/web/api/Redirect) component does not let you set a status code.

In PWA Kit 3.9, we added a `RedirectWithStatus` component that builds on top of the React Router Redirect component and allows you to create redirects with a status code.

### Example

The example below shows how you would add a redirect with an HTTP 301 status from an example page to the login page in your PWA Kit project. 

```
import React from 'react'
import RedirectWithStatus from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/redirect-with-status'

const ExamplePage = () => {
    return (
        <RedirectWithStatus status={301} to='/login' />
    )
}
```

<!-- document id=173f442daffccf664b8ab460edbd98b860d13b234597d642b80a1c2e6aa75138 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/troubleshoot.md -->

# Troubleshoot

Navigate through our API troubleshooting information to efficiently address and resolve issues you encounter.

## Quick Triage: Find Your Solution

Use this table as a first-stop navigation aid. It points to likely starting resources, not definitive root causes.

| Symptom                                     | Start Here                                                                                             | Next Check                                                                                                                                                                                            |
| :------------------------------------------ | :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **504 Gateway Timeout**                     | [Troubleshoot Request Timeouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeout-troubleshoot.md)                                               | [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.md), [Code Profiler](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/code-profiler.md)                                                                                                                          |
| **429 Too Many Requests**                   | [Throttle Rates](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/throttle-rates.md)                                                                    | [Error Response Codes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/error-response-codes.md)                                                                                                                                                       |
| **401/403 authorization errors**            | [Authorization](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/authorization.md)                                                                      | [Authorization Scopes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/auth-z-scope-catalog.md), [SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/slas.md)                                                                                                                                      |
| **400 request validation errors**           | [Error Response Codes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/error-response-codes.md)                                                        | [Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references)                                                                                                     |
| **500/internal errors**                     | [SCAPI Logs and Request Tracking](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md)                                      | [Code Profiler](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/code-profiler.md)                                                                                                                                                                     |
| **Unexpected response behavior**            | [Response Handling](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/response-handling.md)                                                              | [Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references)                                                                                                     |
| **Wrong or stale personalized response**    | [Troubleshoot Personalized Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md#troubleshoot-personalized-caching) | [Personalization and Custom Code](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md#personalization-and-custom-code)                                                                                                    |
| **Stale SCAPI data after a content update** | [Cache Invalidation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md#cache-invalidation)                               | [SCAPI zone](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5) or [cachePurge](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=cachePurge) |
| **Low SCAPI cache hit rates**               | [View Cache Statistics](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md#view-cache-statistics)                         | [Improve the Cache Hit Ratio](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md#improve-the-cache-hit-ratio)                                                                                                            |

## Troubleshooting Resources

The B2C Commerce APIs provide capabilities to help you:

- [Analyze response bodies to identify maintenance issues and actions to take](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/response-handling.md).
- [Check error response codes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/error-response-codes.md).
- [Set rate limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/throttle-rates.md).
- [Timeouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeout-troubleshoot.md).
- [Monitor SCAPI API performance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/code-profiler.md).
- [View SCAPI logs and track requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md).
- [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.md).
- If data stays stale after [cache invalidation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md#cache-invalidation), purge the cache by tag or path in the [SCAPI zone](https://help.salesforce.com/s/articleView?id=cc.b2c_scapi_zone.htm&type=5) or with [cachePurge](https://developer.salesforce.com/docs/commerce/commerce-api/references/zones?meta=cachePurge).

## Step-by-Step Troubleshooting Process

When you encounter an API issue, follow these steps:

### 1. Identify the Request

Every SCAPI response includes a `correlationID` header. Use this to [track and investigate request details](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id).

### 2. Check the Response

- Review the HTTP status code and response body
- Look for error messages and error details in the response
- See [Error Response Codes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/error-response-codes.md) for common status codes

### 3. Review Logs

Use Log Center in Business Manager to:

- Search by `correlationID`
- Enable `verbose` logging for detailed request traces
- Filter for errors and exceptions
- See [SCAPI Logs and Request Tracking](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md)

<!-- document id=bf13e1f8c201775631600e7c556fe98ed46212692b0e1d0c7bac45fe2efaa54f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_troubleshoot_clone.md -->

# Troubleshoot Clone Operations for On-Demand Sandboxes

Resolve common issues that can occur when cloning on-demand sandboxes.

## Clone Taking Longer Than Expected

Expected duration is 10-30 minutes for most sandboxes. If cloning exceeds 45 minutes:

- Check the Activity Timeline for the current progress stage.
- Verify the source sandbox size (larger sandboxes take longer).
- Wait for completion or automatic timeout (60 minutes).
- Contact Salesforce Support if the clone exceeds 60 minutes.

## Source Sandbox Stuck in Cloning State

If the source sandbox remains in **Cloning** state after the clone completes or fails:

- Refresh the Control Center page.
- Check the Activity Timeline for clone completion status.
- Contact Salesforce Support if the state doesn't update within 5 minutes.

## Clone Status Shows Failed

To diagnose a failed clone:

- Click the failed clone in the Activity Timeline.
- Review which stage the clone failed at.

Failure stages and their causes:

| Stage           | Possible Causes                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| Prep Instance   | Source sandbox not in correct state (must be Running or Stopped), or insufficient permissions.                     |
| Data Backup     | Large dataset causing timeout.                                                                                     |
| Data Restore    | Large dataset causing timeout, insufficient credits for target sandbox, or sandbox quota exceeded in target realm. |
| Post Validation | Network connectivity issues, or target sandbox health check failed.                                                |

## Resolution Steps

- For large datasets, consider cloning during off-peak hours.
- For permission or state issues, verify source sandbox state and your access permissions.
- For credit or quota issues, add credits or free up storage space.
- Retry the clone operation after addressing the root cause.
- Contact Salesforce Support if the issue persists after retry.

<!-- document id=2b74fb332676fb4851b24c9d1ea365d4a92265575ef3c6992ce1db141949fa93 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/storefront-preview-troubleshoot.md -->

# Troubleshoot Common Storefront Preview Errors

This section provides suggested solutions for common errors that you might encounter while using Storefront Preview.

## Third-party cookies aren't enabled

Depending on your browser, you may encounter different behavior when third-party cookies aren't enabled.

- **Chrome:** A modal appears stating "Preview is not enabled on this storefront", and the storefront displays a `SecurityError`.
- **Safari:** A modal appears stating "Failed to initialize Storefront Preview", and the storefront isn't visible.

**Cause:** Your browser doesn't allow third-party cookies on `https://runtime.commercecloud.com`.

**Suggested Solution:** Update your browser settings and any extensions you may use to allow third-party cookies on `https://runtime.commercecloud.com`.

## Storefront is missing the script that enables the communication layer

Error message when loading Storefront Preview: `"Preview is not enabled on this storefront!"`

**Cause:** The storefront is missing the script file that enables communication with Runtime Admin.

**Suggested Solution:** Follow the instructions shown in the error message window or complete the configurations in [Step 4](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#4-add-the-storefrontpreview-component-to-your-storefront#4-add-the-storefrontpreview-component-to-your-storefront).

## MRT environment is missing required environment variables

Response error message when clicking the **Preview** button:

```html
400 error: Missing required environment variables:
CC_SHORT_CODE,SLAS_PRIVATE_CLIENT_ID,SLAS_PRIVATE_CLIENT_SECRET
```

**Suggested Solution:** Complete the configurations in [Step 1](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#1-create-a-slas-private-client-for-your-b2c-commerce-instances) and [Step 2](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#2-create-mrt-environment-variables-with-the-slas-private-client-details-and-the-commerce-api-short-code).

## Content Security Policy is incorrect

Depending on your browser, you may encounter an error when you don’t have the correct Content Security Policy.

- **Chrome:** A modal appears stating "Preview is not enabled on this storefront", and the storefront shows an error page stating "refused to connect".
- **Safari:** A modal appears stating "Preview is not enabled on this storefront", and the storefront isn't visible.

**Cause:** Your storefront doesn’t permit Runtime Admin in its Content Security Policy.

**Suggested Solution:** Follow the instructions in [Step 5](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#5-update-the-storefront-content-security-policy-headers) to correctly configure your Content Security Policy.

## Storefront Preview loads the wrong domain

The initial page loaded by Storefront Preview is the domain configured as the External Hostname for the environment.

**Cause:** External Hostname isn't configured correctly in your environment settings.

**Suggested Solution:** Configure the External Hostname in the **Advanced** section of your [environment settings](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.md#edit-environment-settings) to point to the correct domain.

## Account Manager user is missing permissions for B2C Commerce instance

Response error message seen when clicking the **Preview** button:

```html
403 error: You don't have access to the shopper's tenant
```

**Suggested Solution:** Complete [Step 3](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#3-confirm-that-your-account-manager-user-has-access-to-the-b2c-commerce-instance).

## Failed to set shopper context

Response error message seen when clicking the **Preview** button:

```html
400 error: Failed to get trusted system token, check your SLAS private client
```

**Cause:** Incorrect values in the MRT environment variables `SLAS_PRIVATE_CLIENT_ID` and `SLAS_PRIVATE_CLIENT_SECRET` or wrong SLAS private client configuration.

**Suggested Solution:** Complete [Step 1](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#1-create-a-slas-private-client-for-your-b2c-commerce-instances) and [Step 2](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#2-create-mrt-environment-variables-with-the-slas-private-client-details-and-the-commerce-api-short-code).

## Errors occurred after adding the onContextChange prop

While previewing your site after you added the `onContextChange` prop to the `StorefrontPreview` component, you may get error messages or unexpected results.

**Cause:** There may be an issue with the function called by the `onContextChange` prop.

**Suggested Solution:** Remove the `onContextChange` prop and the function it calls from the StorefrontPreview component. Then preview your site and see if the same issues occur. If they don’t, debug your function to resolve any errors. For example, you can:

- Add the `onContextChange` prop and the function it calls back to the StorefrontPreview component. See [Integrate with a Third-Party CMS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#integrate-with-a-third-party-cms).
- Inspect the network activity while previewing your site and see if the fetch request is sending the expected data.

If you still have issues after removing the `onContextChange` prop and the function it calls, open a support case.

## Other Unexpected Behavior

While previewing your site, content isn't displayed as expected and none of the above errors occur. For example, prices don't change based on the values you entered in Storefront Preview.

**Cause:** It's possible that you didn't complete one or more of the prerequisites.

**Suggested Solution:** Confirm that you've completed all of the [prerequisites](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/storefront-preview.md#prerequisites). If you did and you still encounter issues, open a support case.

<!-- document id=8909adf33f239178bf927ff03fde9214117faf45dc4366d69298c7ffa5147bb3 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-passwordless-login-troubleshoot.md -->

# Troubleshoot Passwordless Login

Review these troubleshooting steps for issues with the Shopper Login and API Access Service (SLAS) passwordless login and email verification features.

## One-time Password Not Delivered (Email Mode)

**Potential causes:**

- You haven’t configured the sender email in SLAS.
- You haven’t verified the sender email address.
- You haven’t set the password action email template in SLAS.

**Suggested solution:** Verify your SLAS email configuration. See [Passwordless Login with Email](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login-email.html).

## One-time Password Not Delivered (Callback Mode)

**Potential cause:** The `callbackUri` isn’t allowlisted in the SLAS client, or the callback endpoint can’t be reached.

**Suggested solution:** Confirm that the `callbackUri` in `config.server.ts` exactly matches an allowlisted URL in the SLAS client. Don’t use wildcards—the full URL including protocol must match. Verify that your callback endpoint is publicly accessible and returns a successful response.

## One-time Password Has Wrong Number of Digits

**Potential cause:** The `auth.otpLength` value in `config.server.ts` doesn’t match the one-time password (OTP) length configured in your SLAS client. SLAS generates the token at the length set in the client, so a mismatch causes the storefront to expect a different length than what the shopper receives.

**Suggested solution:** Make sure that `auth.otpLength` in `config.server.ts` matches the OTP length set in your SLAS private client configuration. Valid values are `6` and `8`. See [Configure a SLAS Private Client](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/slas-passwordless-login-email.html#1-configure-a-slas-private-client).

## Passwordless Registration Form Not Shown

**Potential cause:** Your site doesn’t have the **Enable Email Verification** site preference turned on, so the registration page renders the standard password form.

**Suggested solution:** In Business Manager, go to **Merchant Tools \> Site Preferences \> Storefront Login Preferences** and turn on **Enable Email Verification**. Wait up to 5 minutes for changes to reflect in your storefront. When you turn on this preference, passwordless registration becomes the default mode.

## Email Verification Badge or Change Email Button Not Shown

**Potential cause:** Your site doesn’t have the **Enable Email Verification** site preference turned on, or the preference change hasn’t propagated yet.

**Suggested solution:** In Business Manager, go to **Merchant Tools \> Site Preferences \> Storefront Login Preferences** and turn on **Enable Email Verification**. Wait up to 5 minutes for the changes to reflect in your storefront.

## Customer Can’t Log in with Updated Email

**Potential cause:** Your site doesn’t have the **Enable Loginid Updates for SCAPI** feature switch turned on. When this feature is turned off, the B2C Commerce API (SCAPI) accepts email updates but doesn’t sync the change to the shopper's login ID, causing a mismatch between the display email and the credentials used to log in.

**Suggested solution:** Contact support to enable the **Enable Loginid Updates for SCAPI** feature switch.

<!-- document id=1d761d0da9ad3fab45e921d014b6dd55ca3b441eeae383f6199761d44d03a0bb url=/developer/current/en-us/commerce-cloud/commerce-api/guides/timeout-troubleshoot.md -->

# Troubleshoot Request Timeouts

Gateway timeouts can occur for various reasons. Use the following steps to identify the root cause of a timeout:

For detailed information on timeouts, see [Timeouts and Limits](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/timeouts-limits.md).

## Step 1: Identify Your Request

Every SCAPI response has a `correlationID` response header that you can use to [identify and track request details](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id) for the request.

Determine the `correlationID` from your request with the timeout and gather log information:

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup**.
2. In the **Log Files** section, select **Log Center**.
3. Select the **Day of Year**.
4. For **LCQL**, enter `correlationID`.
5. Make a note of the **API-Family** and **API** values for the next step.

## Step 2: View Request Processing Time

Check for response times or processing times that are close to the timeout limits using Reports & Dashboards (CIP) data:

1. In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Merchant Tools** > **Select your site**.
2. Go to **Analytics** > **Reports and Dashboards**.
3. Check the **Average Response time** for your API.

An average response time that is close to the timeout threshold might exceed the limit under high load.
Timeout errors with a low average response time indicates occasional responses exceeding the limit.
Although uncommon, network issues can also cause timeout issues.

## Step 3: Gather Additional Request Details

To find the root cause of a gateway timeout, additional request details are needed:

- request details
- response details
- **customApi script**, if the request is a custom API request
- **hooks** executed during request processing including **hook execution time for each hook**

Try to reproduce the suspicious request with `verbose` logging enabled. For details, see: [Additional request details](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id).
The Log Center provides request details via `verbose` log filter. Therefore, use the `correlationID` and the log level category `scapi.verbose` together.

## Step 4: Check For Errors

In Log Center, using the query hits, filter for `errors` to find errors that occurred during request processing.

[Investigating script errors](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-circuit-breaker.md#investigate-script-errors)

Check if those errors occur regularly and try to correlate them to long running requests.

## Step 5: Identify Customized Code Executed During Request Processing

Hooks or custom scripts executed in Custom APIs might be the root cause of the timeout.

APIs that include hooks are always slower than APIs without hooks, because there is additional code to execute. Furthermore, Custom APIs and hooks contain a Circuit Breaker mechanism, which blocks API requests when a specific error threshold is exceeded.

[Circuit-breaker](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-circuit-breaker.md#how-it-works)

Check the Log Center query hits for the following exception types:

- HookInvocationException
- HookCircuitBreakerException
- CustomApiInvocationException

Select the stacktrace to locate the `Caused by` section, which can contain information about the root cause of failures. Some possible causes include:

- External requests that exceed a timeout
- Complex computations
- Script errors

**note:** A 504 response code returned by the API gateway might not be the same response code as displayed in the Log Center.

## Step 6: Improve Code and Customizations

Use the [code profiler](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/code-profiler.md) to monitor performance and locate performance bottlenecks.

Use additional log statements and metrics to gather more details.

General guidance:

- Check requested expansions and only select required data. For details, see [SCAPI Caching](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/server-side-web-tier-caching.md).
- Only request required availability and personalized data.
- Use caution with resource identifiers that allow multiple values such as category IDs or product IDs. These can result in a large amount of response data and increased response time.

Client side guidance:

- [Use compression](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-site-performance.html#use-compression).
- Reuse authentication tokens.
- Avoid external requests or use async processing (jobs).
- Avoid complex processing and computations.

<!-- document id=7d13c4b983beab42dfd09e119e976a99bd508019b384e5e63fa3e586aa940992 url=/developer/current/en-us/commerce-cloud/sfra/guides/b2c-troubleshooting-sfra.md -->

# Troubleshoot SFRA

Troubleshoot common SFRA issues.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Debugging

If you want Salesforce B2C Commerce script debugging capabilities in an IDE other than Eclipse, you must use one of the IDEs supported by the [Dwdebugger](https://github.com/SalesforceCommerceCloud/dwdebugger) repository.

## After Updating the Base Cartridge

In GitHub, you can see the differences between two versions of Nobile_First Reference Architecture (SFRA). This ability lets you quickly identify code that has changed.

Create SFRA as a separate site and import the data for the site to see if the behavior remains the same.

## After Adding SFRA to a New Sandbox

If you've added SFRA to a new sandbox and it doesn't appear to work, check the following:

- Are you on the correct code compatibility version?

- Are you sure that your cartridge path is the same as the cartridges in your workspace?
- If you're using Eclipse, did you check your project references?

## Add an Extra Code Version

If you aren't seeing your changes reflected on the server, try activating a different code version and then reactivating the current code version. If you immediately add an empty code version, you're ready to troubleshoot from the start.

1.  Select **Administration > Code Deployment**.
2.  Click **Add** and enter a name for your new code version.

<!-- document id=40b82d3975d3853e6d7d309489a0b279831c859f3b8067e33cffe70fa508ae7f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ops-troubleshooting/b2c-troubleshooting.md -->

# Troubleshooting

If a problem occurs with your Salesforce B2C Commerce installation, knowing the best ways to approach it will minimize customer impact and avoid frustration.

1. Can you see an error on a web page?

   - Document your most recent actions leading up to the problem.
   - If it's a non-production system, use the Show Request Log to get more detailed error information.
   - If it's a production system, note the session ID, URL, and exact time. Use them to identify the corresponding error in log files.

1. Did a user report an error?

   - Are session ID, URL, exact time, performed activity information available? Try to correlate this information with the log messages.
   - Review error log files daily during the QA phase and production.

1. Try to reproduce the error. Then document your findings clearly and precisely. The more details, the better.
1. Review the available log files and use them to identify the click stream and the original referrer.
1. In more complex situations, use _code instrumentation_ to capture more detailed information.

**tip:** Code instrumentation: adding extra statements to source code for the purposes of testing, debugging, tuning, or tracing.

## Speed Up Diagnostics with the B2C Commerce CLI

The [B2C Commerce CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md) lets you stream, filter, and search logs from your terminal, so you can correlate errors without logging into Business Manager. To install the tool and authenticate, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md).

```bash
# Watch ERROR- and FATAL-level entries in real time
b2c logs tail --level ERROR --level FATAL

# Filter the tail to a specific string
b2c logs tail --search "OrderMgr"

# Pull the last 200 error entries as JSON for further processing
b2c logs get --count 200 --level ERROR --json

# Look at the last hour of errors matching a keyword
b2c logs get --since 1h --level ERROR --search "PaymentProcessor"

# Inspect the most recent job execution log (or only failed executions)
b2c job log my-custom-job
b2c job log my-custom-job --failed
```

For the full command reference, see [Logs Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/logs.html) and [Job Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/jobs.html) in the Agentic B2C Developer Toolkit documentation.

## Considerations

| Item to consider                                                        | Helps you understand                                                      |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [Infrastructure](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-troubleshooting-infrastructure.md)                 | How the various components work together.                                 |
| [Session ID / Request ID](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-troubleshooting-session-id-request-id.md) | How to track requests and sessions.                                       |
| [Log Files / Log Levels](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/site-development/b2c-log-files-overview.md) | How to glean important information from the log file.                     |
| [Remote Includes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-understanding-remote-includes.md)                 | Additional Application Server requests.                                   |
| [Staging Problems](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-identifying-staging-problems.md)                 | How to identify and correct staging problems.                             |
| [Reporting to B2C Commerce Support](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/b2c-reporting-to-support.md)      | Whom to notify concerning specific types of issues and how to notify them |

<!-- document id=506fd6ef62e649b96ad5eea721d6d172e04f8cd5e97dd305d4b8917958878a0a url=/developer/current/en-us/commerce-cloud/commerce-api/guides/custom-api-troubleshooting.md -->

# Troubleshooting

When a Custom API endpoint is not accessible as expected, this page can help to find the root cause. The following checklist is meant to verify the structure of the cartridge (for example, the folder structure), the required files and the request. However, it doesn’t include the implementation itself.

## Issues During Endpoint Registration

Since these issues prevent the endpoint from being registered, an incoming request results in a **404 - Not Found** response with this payload:

```json
{
  "title": "Resource Not Found",
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found",
  "detail": "Could not find requested resource"
}
```

Recommended Approach: Use the [Custom API status report](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-status-report.md) to investigate endpoint registration issues. This status report provides detailed error information for endpoints that could not be registered, including specific error codes that help you quickly identify and resolve problems.

If the Custom API status report doesn't provide sufficient information to resolve the issue, verify the following items manually:

1. Is the code version to which the Custom API components were uploaded the active code version?
2. Does the cartridge that includes the Custom API components have the correct structure?
   1. Is the `rest-apis` folder included?
   2. Does the `rest-apis` folder contain at least one subfolder?
   3. Does the subfolder name of `rest-apis` consist of only alphanumeric lowercase characters or hyphens?
   4. Does the subfolder of `rest-apis` contain the mapping file and at least one schema file and implementation script?
3. Is the cartridge that includes the Custom API components uploaded to the correct SFCC instance?
4. Is the cartridge that includes the Custom API components assigned to the correct site?
5. Is the version used in the request correct?
   1. Is the corresponding API version defined in the schema file?
   2. Does the API version match? API version and URL version have different formats (for example, API version `1.0.1` → URL version `v1`)
6. Is the schema file correct?
   1. Is the structure of this file correct?
   2. Is a version given?
   3. Is the `securitySchemes` part given?
   4. Is at least one endpoint given, including the attribute `operationId`?
   5. Is the `security` field given, either globally or per endpoint?
   6. Are `ShopperToken` or `AmOAuth2` used as a security scheme?
   7. Does the corresponding security scheme define exactly one scope?
   8. Does the scope name start with the prefix `c_` and consist of only alphanumeric characters, hyphens, periods or underscores? The custom scope name should also be 25 characters or less.
   9. Are all parameters (system parameter and custom parameter) defined in the schema file?
   10. Are the system parameters `siteId` and `locale` defined in the schema file?
       1. Do the system parameters have a `schema` field with `type: string` and `minLength: 1`?
   11. Do custom parameters start with the prefix `c_`?
   12. Do all parameters have a defined type?
   13. Does the definition of all parameters match the expected structure of parameter definitions?
7. Is the implementation script correct?
   1. Are the respective endpoints exported in this implementation script? → see mapping file and schema file (attribute `operationId`) which endpoints should be exported by this script file.
   2. Does the endpoint return a response in JSON format?
8. Is the mapping file correct?
   1. Is the structure of this file correct?
   2. Are no file extensions included in the name of the implementation scripts?
   3. Are the schema files and implementation scripts in the same folder as the mapping file?
   4. Does a schema file for this version exist?
   5. Does an implementation script for this version exist?
   6. Are the given endpoints referenced in the related schema file and the implementation script?
   7. Does the value of the `endpoint` property match the function name in the script and the `operationId` in the schema?

### Investigate Registration Errors

If the previous checklist does not help determine the error, review the log messages. Each registration failure creates a corresponding log message.

1. In Business Manager, navigate to **Administration** > **Site Development** > **Development Setup**.
2. In the _Log Files_ section, click _Log Center_.
3. Select the Day of Year.
4. In the **LCQL** field, enter `CustomApiRegistry`.
5. The message text of the query hits should provide enough details to fix the issue in the correct file.

## Issues During Request Processing

Incoming requests are processed and validated against the contract, which can result in the following errors:

### 400 - Bad Request

- Example
  - :
    ```json
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/undefined-query-parameter",
      "detail": "Found query parameter(s) not defined in the schema: 'c_type'"
    }
    ```
- Reason
  - : Errors of this type are typically caused by contract violations, for example: missing or unknown request parameters, or invalid parameter length.
- Solution
  - : The response body should give a clear indication of the reason.

### 401 - Unauthorized

- Example
  - :
    ```json
    {
      "title": "Unauthorized",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized",
      "detail": "Invalid token provided."
    }
    ```
- Reason
  - : Errors of this type are caused by failed authentication, for example: missing or invalid authentication tokens.
- Solution
  - : Verify the following items:
    1.  Does the request have an authentication token in the `Authorization` header?
    2.  Is the token (still) valid?

### 403 - Forbidden

- Example
  - :
    ```json
    {
      "title": "Forbidden",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden",
      "detail": "Request path is not allowed, because of missing or invalid permissions."
    }
    ```
- Reason
  - : Errors of this type are caused by failed authorization, typically a scope error.
- Solution
  - : Verify the following items:
    1. Is the token correctly configured with custom scopes?
    2. Is one of the token scopes defined for the endpoint in the contract?

### 405 - Method Not Allowed

- Example
  - :
    ```json
    {
      "title": "Method Not Allowed",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/method-not-allowed",
      "detail": "The request method is not allowed for the requested resource"
    }
    ```
- Reason
  - : Errors of this type are returned if the endpoint path exists, but the request method is not defined in the contract.
- Solution
  - : If this method is valid, add the corresponding operation to the contract. If it is not, change the request to use a different method.

### 406 - Not Acceptable

- Example
  - :
    ```json
    {
      "title": "Unsupported Media Type",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-media-type",
      "detail": "The media type 'application/xml' in the Accept header isn't supported.",
      "mediaType": "application/xml"
    }
    ```
- Reason
  - : Errors of this type are returned if the response media type defined in the contract is not acceptable by the client (for example: the endpoint always returns `application/json` but the client only accepts `application/xml` as defined in the `Accept` header.)
- Solution
  - : If the requested media type is valid, add it to the corresponding operation in the contract. If it is not, change the request to use a supported media type, perhaps by using a wildcard. See the [specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept) for details.

### 415 - Unsupported Media Type

- Example
  - :
    ```json
    {
      "title": "Unsupported Content Type",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-content-type",
      "detail": "The media type 'application/xml' in the Content-Type header isn't supported. Note: Only the UTF-8 charset is supported.",
      "contentType": "application/xml"
    }
    ```
- Reason
  - : Errors of this type are returned if the media type of the request payload doesn't match the media type defined in the contract (for example: the payload is `application/xml` as indicated by the `Content-Type` header, but the endpoint expects `application/json`).
- Solution
  - : If the supplied media type is valid, add it to the corresponding operation in the contract. If it is not, change the request to use a supported media type. See the [specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-type) for details.

---

### 500 - Internal Server Error

- Example
  - :
    ```json
    {
      "title": "Custom API Internal Server Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-api-internal-server-error"
    }
    ```
- Reason
  - : Errors of this type could indicate generic server errors during request processing. However, errors resulting from the implementation script will also return them with the type `custom-api-internal-server-error` like in the example above.
- Solution
  - : Investigate the log messages to discover the reasons for these errors as described [here](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-circuit-breaker.md#investigate-script-errors).

### 503 - Service Unavailable

- Example
  - :
    ```json
    {
      "title": "Custom API Circuit Breaker Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-api-circuit-breaker-error"
    }
    ```
- Reason
  - : Errors of this type indicate an open circuit breaker due to a high number of script errors.
- Solution
  - : For more information on this protective mechanism and how to address these errors, see [Circuit Breaker](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/custom-api-circuit-breaker.md).

## Issues with Remote Includes

- SCAPI error responses:

  - If a 404 response code is received from the included resource, an empty JSON object '{}' is supplied in the final JSON.
  - For any other 4xx or 5xx response code that is received from the included resource, the final response status is 500 'Internal Server Error'.

- Controller error responses:
- The error response code is directly embedded into the resulting JSON. If your error responses are not valid JSON, the final response is invalid JSON.

<!-- document id=6c7949da5826f42888ce4edaf2079b9cbfd33691d27f1946491ab37dbc4309c4 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-troubleshooting.md -->

# Troubleshooting Checkout Issues

Common issues encountered during the B2B Commerce checkout process and provides guidance to help identify and resolve them.

1. OOTB Checkout, Payment, or Place Order API Fails

| Action                                  | Troubleshooting Notes                                                                                                         |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Check for concurrent modifications      | Verify if other endpoints or custom code are concurrently modifying WebCart.                                                  |
| Validate last `/checkouts` API response | Last operation on checkout should return 200.                                                                                 |
| Handle 202 response                     | If last `/checkouts` API returned 202, wait until GET `/checkouts` returns 200, indicating asynchronous operations completed. |

2. Custom Components Can’t Update Checkout Information

| Action                           | Troubleshooting Notes                                                                                                         |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Verify checkout page load status | Check result of last GET `/checkouts` call. 202 response means checkout wasn't completely loaded.                             |
| Update customization logic       | Modify customization to wait for GET `/checkouts` to return 200 before attempting updates.                                    |
| Use out-of-the-box APIs          | Use OOTB APIs whenever possible. For example, OOTB API for updating phone number includes necessary validation at invocation. |

3. Payment or Billing Information Gets Overridden

| Action                                   | Troubleshooting Notes                                                                                                                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Review API orchestration                 | Observe API call sequence and compare against standard OOTB Checkout flow.                                                                                                                 |
| Identify post-payment checkout API usage | Check if any Checkout API is used after entering payment/billing information. For example, updating shipping address re-runs calculators and invalidates payments if total amount changes. |
| Check custom Apex calls                  | Inspect all custom Apex calls made after entering payment/billing information. A customization might be overriding fields.                                                                 |

4. Payments Created But Not Updated on WebCart

| Action                                           | Troubleshooting Notes                                                                                                       |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Examine `/checkouts/payments` PostAuth responses | Look for failures in PostAuth API response.                                                                                 |
| Identify concurrent modifications                | Most frequent cause is concurrent modification. Look for concurrent custom code modifying cart state.                       |
| Avoid concurrent cart modifications              | Eliminate concurrent calls modifying cart state.                                                                            |
| Verify pre-payment /checkouts status             | Verify last `/checkouts` call returned 200 before invoking payments. If not, modify orchestration to wait for 200 response. |

5. Order or Order Summaries Not Created

| Action                                  | Troubleshooting Notes                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Check Checkout API failures             | Review responses of all Checkout APIs for failures.                                                                    |
| Focus on CheckoutPayment PostAuth API   | Common point of failure. Refer to troubleshooting steps in "Payments Created But Not Updated on WebCart."              |
| Verify subsequent API success           | Ensure APIs following payment step (PlaceOrder/SubmitOrder) were successful.                                           |
| Review process exceptions               | Navigate to Setup > Process Exceptions and check for recent exceptions. See Process Exceptions for more details.       |
| Troubleshoot high scale order ingestion | If High Scale Order Ingestion is enabled, try disabling and re-enabling Order Ingestion from Setup > Order Management. |

6. "Payment Method Isn't Authorized" Error

| Action                                                  | Troubleshooting Notes                                                                                                                                                                                                          |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Check `paymentMethodId` and `paymentGroupId` on WebCart | Verify both fields are present on WebCart. This applies to Commerce Webstore Checkout Orders API.                                                                                                                              |
| Validate payment amount sum                             | Ensure: PaymentGroup.TotalAuthAndSaleAmount + PaymentGroup.PendingAuthAndSaleAmount = WebCart.GrandTotalAmount (or FirstPymtGrandTotalAmount for subscriptions). Applies to Commerce Webstore Checkout Place Order Action API. |
| Validate custom solution                                | If using custom payment solution, ensure it incorporates required field validations.                                                                                                                                           |
| Verify OOTB solution                                    | If using OOTB payments, verify CheckoutPayment APIs response was successful.                                                                                                                                                   |

7. Order Summary Displays $NaN for $0.00 Line Items

| Action                               | Troubleshooting Notes                                                                |
| ------------------------------------ | ------------------------------------------------------------------------------------ |
| Check for custom calculator          | Determine if custom calculator is used for price or promotion logic.                 |
| Identify null/undefined price fields | Check if any price fields are left as null or undefined instead of being set to 0.   |
| Fix custom calculator                | Update custom calculator to explicitly set fields to 0 instead of null or undefined. |

8. Shipping Options or Delivery Methods Don’t Load (No Errors)

| Action                                     | Troubleshooting Notes                                                                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| Check for custom shipping calculator       | Determine if shipping calculator is custom implementation.                                                               |
| Verify shipping method generation (custom) | If custom, ensure calculator successfully generates and returns shipping methods.                                        |
| Verify CartValidationOutput (custom)       | If custom, ensure it creates CartValidationOutput for failure scenarios. Otherwise, checkout may get stuck in bad state. |

9. Phone Numbers Converted to E164 Format

| Action                             | Troubleshooting Notes                                                |
| ---------------------------------- | -------------------------------------------------------------------- |
| Understand phone number validation | Default validation converts input to E.164 format, removing hyphens. |
| Disable validation (workaround)    | Enable org permission CheckoutSkipPhoneValidation.                   |

10. ListPrice on OrderItem Doesn’t Map from CartItem

| Action                     | Troubleshooting Notes                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Understand default mapping | By default, CartItem.SalesPrice maps to OrderItem.ListPrice.                                                 |
| Change mapping             | Enable org permission SalesPriceToListPriceMap. This maps CartItem.ListPrice to OrderItem.ListPrice instead. |

11. "Cart is Currently in Use" Error

[Salesforce Knowledge Article Number: 002722661](https://help.salesforce.com/s/articleView?id=002722661&type=1)

| Action                     | Troubleshooting Notes                                                      |
| -------------------------- | -------------------------------------------------------------------------- |
| Identify source API        | Pinpoint which API is returning this error.                                |
| Check for concurrent calls | Error indicates multiple concurrent calls attempting to update cart state. |
| Eliminate concurrent calls | Refactor process to eliminate concurrent calls modifying cart state.       |

12. CartCheckoutSession Not Created

| Action                          | Troubleshooting Notes                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| Check for custom creation logic | Determine if customization creates CartCheckoutSession before invoking Checkout API.       |
| Use single creation method      | If custom logic exists, use only one method. Use standard Checkout API for this operation. |

13. Orders Created Even When Payment Fails in B2B LWR Store

| Action                                            | Troubleshooting Notes                                                                                                                                                         |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identify Payment Provider and Webhook Usage       | Check if a payment provider, such as Adyen is used, which confirms payment via a webhook.                                                                                     |
| Check for Place Order API Usage                   | If the webstore uses Place Order API, orders are created immediately without waiting for the payment confirmation webhook, leading to order creation even on failed payments. |
| Switch to Place order Action API (Recommendation) | The recommended solution is to switch to Place order Action API, which only creates Orders after payment is confirmed by the webhook.                                         |

1.  Out of Stock Error When Inventory Available

| Action                       | Troubleshooting Notes                                                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Check cart size limit        | B2B stores have hard limit of 500 line items per order.                                                                      |
| Check OCI limit (if enabled) | If Order Confirmation Integration (OCI) is enabled, there's a limit of 100 product ID and location combinations per request. |

15."Invalid checkout session status. Expect: PendingClosed, actual: Active" with cartToOrderSummary

| Action                           | Notes                                                                                                                      |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Check for Place Order Action API | Determine if Place Order Action is enabled. See Streamline Place Order.                                                    |
| Compatibility issue              | If Place Order Action API is enabled, Apex method `Sfdc_Checkout.CheckoutOrderService.cartToOrderSummary` isn't supported. |

16. Incorrect Payment Amount

| Action                         | Troubleshooting Notes                                                                                          |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Check API orchestration timing | Payment was likely initiated before waiting for all Checkout APIs to complete (before receiving 200 response). |
| Potential amount changes       | Amount fields on WebCart can change after asynchronous calculators complete. Always wait for 200 status.       |

17. "We Can't Find Checkout" Error

| Action                            | Troubleshooting Notes                                                                                                           |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Check OptionsCartCalculateEnabled | If OptionsCartCalculateEnabled is disabled, this error is expected. New CartCheckoutSession is required after cart is modified. |

18. Orders Created in Draft Status

[Salesforce Knowledge Article Number: 000393690](https://help.salesforce.com/s/articleView?id=000393690&type=1)

| Action                     | Troubleshooting Notes                                                                                                                                             |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Check for concurrent calls | Concurrent calls modifying Cart and Checkout entities compete with Order Activation process, resulting in activation failure and order remaining in Draft status. |
| Eliminate competition      | Ensure no concurrent processes modify Cart/Checkout entities during Order Activation phase.                                                                       |

<!-- document id=4c3ff43c59eb3ab02dbde98491e25bde17313ecdd534708f2b02ba81e736d544 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ops-troubleshooting/b2c-troubleshooting-infrastructure.md -->

# Troubleshooting Infrastructure

To effectively troubleshoot B2C Commerce, you must understand its infrastructure.
Start by familiarizing yourself with the basic components of the Salesforce B2C Commerce infrastructure for a *Production *instance, which include:

| Component                                                                             | Description                                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Firewall Load Balancer                                                                | A device that controls what requests can enter or leave the B2C Commerce infrastructure.                                                                                                                                                    |
| Requests are distributed to one or more web servers.                                  |
| Web Server                                                                            | A computer that is responsible for accepting HTTP requests from clients and serving them HTTP responses.                                                                                                                                    |
| At least two web servers are provisioned for a production instance.                   |
| Web Adapter                                                                           | B2C Commerce proprietary web server plugin.                                                                                                                                                                                                 |
| Deals with page caching, page assembly, and load distribution to application servers. |
| Local Page Cache                                                                      | A local storage area where frequently accessed data can be stored for rapid access. The local cached copy of data can be accessed instead of recomputing it or retrieving it from the application server, reducing the average access time. |
| Application Servers                                                                   |

Software that executes business logic and presentation.
There are at least two application servers provisioned for a production instance. |
|Shared Database Schema |All application servers of a B2C Commerce instance access the same database schema. Different instances use different schemas. |
|Shared File System (Cartridges, Images, Log Files) |Part of the file system that all application servers of a B2C Commerce instance can access. |

## Session Affinity

It is important to understand how HTTP session affinity works within the infrastructure

- For Web Servers / Web Adapter:
  - Web Servers / Web Adapters are stateless in regard to sessions. Thus, they treat each request as an independent transaction that is unrelated to any previous request.
  - The load balancer randomly distributes a session's requests to the Web Servers. One request can go to one Web Server, and the next request to another.
- For Application Servers
  - Application servers _are_ session-aware because they deal with things like session attributes, authentication information, form data, clickstream data, and the Pipeline Dictionary at an Interaction Continue Node.
  - All the requests of a particular session go to the same application server.

<!-- document id=367245cef708f1904508a75992db97ee7e30379d30ce213663315517ae97871e url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ops-troubleshooting/b2c-troubleshooting-platform-performance.md -->

# Troubleshooting Salesforce B2C Commerce Performance

When you face performance problems, the following guidelines and steps help resolve the issue without needing to contact your support provider. However, if you still need assistance, the gathered information is helpful while raising a case.
Use the Pipeline Profiler and Reports & Dashboards to monitor and review deployed code performance, and identify or prevent performance problems. When a performance issue occurs, take several steps to identify the cause and quickly resolve the issue.
Grid-wide median responses for the most critical pipelines are:

- Search-Show : 400 ms
- Product-HitTile : 10 ms
- Product-Show : 300 ms
- Home-Show : 90 ms
- Page-Show : 90 ms
- Cart-Show : 400 ms
- OCAPI-Request\* : 250 ms

  \*Catch-all for OCAPI requests. View statistics in the CCAC Technical Dashboard.

If the response times for these critical controllers are around the mentioned median response time, the site is scalable.
Validate the controller response time by executing the Pipeline Profilers or CCAC Reports and Dashboards.To analyze and narrow down the line of code causing the issue, use Pipeline Profiler.
**Note:** The end to end response time of any controller, as measured by external monitoring tools, is expected to be much higher as it depends on network, browser rendering, and so on.

**Pipeline Profiler**

When you push a new version of your storefront code, or receive a new B2C Commerce version, monitor performance to see if the new code affects it with the Pipeline Profiler. Also monitor job performance and search indexing, and optimize when possible.

1. To access the Pipeline Profiler, navigate to **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Pipeline Profiler**.
   The Pipeline Profiler displays a high-level view of response times per script, such as hits, total time for a page to be generated, and average time. Use the Pipeline Profiler to identify the most expensive pipeline or controllers, and the most expensive component within that pipeline or controller. Drill down into script data within a pipeline or controller to identify expensive scripts running on the storefront.
2. Look for scripts with high average run-times and high hit-counts.
   These are the first metrics to focus on for troubleshooting performance.
3. To view more detailed data for a specific script, click the script name.

While the profiler is running, similar metrics are provided for all Server-Side JavaScript (whether it is in a script file, in an `${expression}`, or between `<isscript>` tags). When you stop the profiler, script data is no longer provided.
Look at the pipeline technical reports to identify which recent code deployments are related to performance issues. If a new script or pipeline was recently deployed, roll back the code. Use a code replication of type Undo, or change the active version in production.

**Code Profiler**

The Code Profiler provides insight into run-time performance. Unlike Pipeline Profiler data, the information is kept and can be exported. For more information, see [Using Code Profiler](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-site-performance.html#use-code-profiler).
Are you currently facing a performance issue? Use the following information to troubleshoot in real time or review the performance of your site.

## Troubleshooting Real-Time Performance Issues

We recommend you follow a sequential approach to narrow down the origin of the issue before reaching out to support. The following documentation leads you towards a possible root cause and solution for your real-time performance issue.

![Real-Time Performance Issue Flow 1](https://developer.salesforce.com/media/b2c-commerce/b2c_admin_troubleshooting_flow1.png)

**Specific Location or User Issues**

To check for B2C Commerce disruptions or service degradations, check the [Trust Status Page](https://status.salesforce.com/products/B2C_Commerce_Cloud).

### Network-Related Issues

**Note:** If the issue is only seen from a specific location, or the whole internet is slow, it's highly likely to be a local network issue.

Check the following issues and record the answers for communication with technical support:

1. Is the slowness seen by a single user, a specific location, or is it seen sporadically across the regions?
2. Are you seeing slowness only on the B2C Commerce storefront, or on other external websites?
3. Is this slowness common across all instances, or restricted to one instance?
4. Is the slowness reported for a specific page, search result, component, or across the site?
5. Is the slowness reported by an actual user or by a monitoring bot?
6. Is the issue seen all the time or happening sporadically?
7. Is the issue happening at a specific time of day?

**Verify Network Issues**

To verify network issues, consider the following:

- Check for a browser proxy. If that doesn't resolve the issue, then contact your network administrator.
- Perform a `traceroute`. This can identify a bottleneck in your network chain.
- Run a Firebug analysis. Check the network view to do analysis of requests with long response times.
  - Waiting Time: If waiting time is highest in the graph, the issue is most likely on the server-side and the code needs further investigation.
  - Receiving: If receiving time is highest in the graph, the issue is probably with a local network or browser.
  - Connecting: If a request spends a long time connecting, it often indicates a network issue.
- Check eCDN or DNS in **Business Manager** by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting > **Administration** > **Sites** > **Embedded CDN Settings**.

### Increase in Session or Requests

Use the Real-Time Performance tab in **Business Manager** by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Merchant Tools** > **Analytics** > **Reports and Dashboards (New!)**.

**Sudden Increase in Orders**

- Is there an on-going Sale or Promotion?
- Is there a case raised with Support regarding this sale event?
- If it’s a promotion, make sure there is no email blast with unique URL parameters.
- Are the promotions configured optimally by category rather than a list of applicable products?

**Increase in System Workload Without Significant Order Change**

- Do you have a potential bot or crawler issue?
- Check the eCDN settings for WAF rules in **Business Manager** by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Sites** > **Embedded CDN Settings**.
- Consider Rate Limiting or Captchas.

**Increase in System Workload and Decrease in Orders**

- Check for recent code or data replications if the time matches.
- Is there an issue with Cache Clear?
- Cache Clears can lead to suboptimal performance during high traffic.

**What Can Cause a Cache Clear?**

- Code replication, code activation, and data replication clear the cache unless you specify not to in the job. If the cache isn't cleared, however, replicated data isn't shown on the storefront until pages refresh their cache normally.
  **Note:** Unlike most other types of data replication, geolocation data and coupons don't clear the cache.
- Manually clearing the cache.
- `iscache` tags of type `daily` in your storefront pages clear all pages of a specific type at the same time every day.

**Common Caching Mistakes**

- Invalidating cache just before an expected sales peak.
- Invalidating cache several times throughout the day just to bring a specific product or small number of changes online. If that happens frequently, investigate page cache partitioning.
- Invalidating page cache just to bring a piece of static content online.

**Changes During Replication**

- Have any site or global preferences changed?
- Have there been any recent changes to catalogs or integrations?
- Have there been any changes to promotions, slots, or content assets?

**Long Running Jobs?**

Check for long running jobs that can be causing thread exhaustion.

### Increase in Errors and Warnings in Log Center

1. Navigate to **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select > **Administration** > **Site Development** > **Development Setup** > **Log Center**.
2. Select the current date, and errors and warnings to assess the pattern. If required, select up to the previous 4 days in order to assess the pattern.

**Potential Causes**

- Custom code
  Are the errors related to custom code? Check for recent code releases or activation. Work with the Development team to debug the recent code.
- System error
  If errors are related to the system, fetch log and raise a case with support.
- Third-party timeout
  Verify the respective web services and refer to [Configuring Web Services in Business Manager](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-webservices.html).
- Resource Lock
  Some tasks or jobs are prioritized in their capability to lock resources on a higher level. For example, if a job has the right to lock the site's resource it will automatically release all underlying resources before. So now the workflow job loses the exclusivity of the assigned locks and will fail as it isn't able to get the resources again (as it is currently locked by an overlying job).
  To prevent the correlation between such jobs, determine which jobs are affecting others and if it is possible that the other jobs are locking the needed resources.
  This can be done by reviewing the Job History to see if possible system and custom jobs are running longer than without the own job before. Search in the log center by ‘resource lock’. If the own defined job is failing regularly, and is followed by a system job, contact B2C Support to reschedule the system job to a runtime which wouldn't interfere with the workflow job. If the locking is due to a custom job, consider rescheduling to avoid overlapping.

## Troubleshooting General Performance Issues

We recommend you follow a sequential approach to narrow down the origin of the issue before reaching out to support. The following documentation leads you towards a possible root cause and solution for your general performance issue.

![General Performance Issue Flow 2](https://developer.salesforce.com/media/b2c-commerce/b2c_admin_troubleshooting_flow2.png)

**Specific Page Slowness**

Capture an HTTP Archive (HAR) file to pinpoint where the time is spent. A HAR file contains lots of trace information from within a browser. It records all web requests made by the browser tab, including the request and response headers, the body, and the time it took to load. HAR files are useful when troubleshooting issues relating to speed, caching, and issues that are harder to replicate.

### Increase in Session or Request, System Workload, and Orders

If you see an increase in session or requests, system workload, and orders, reach out to the support team with information on the workload increase. Your realm resourcing can be fine-tuned, if necessary.
Order Throughput Remains the Same
Potential Bot or Crawler Issue

1. Navigate to **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Analytics Reports and Dashboards (New!)** > **Traffic tab** > **Top Robots**.
2. Validate the trend of bots, and the number of bots compared to actual storefront visits.

**Verify Controller Performance Metrics**

1. Navigate to the Technical Tab in **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **Analytics Reports and Dashboards (New!)** > **.**
2. Verify Controller performance metrics such as cache hit ratio, response time, and OCAPI Response.
3. Select **Main Controller Requests**, sort the requests in descending order, and show the controllers that have been requested the most and with high response time.
   Click into the controllers and view remote-includes controllers to understand where the time is most spent.
4. For OCAPI controllers, check the **OCAPI Tab** and sort based on request and response time.

**Long Running Jobs**

To monitor job runtimes, navigate to **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Jobs**.

We recommend monitoring jobs regularly, and to analyze any jobs running over one hour to identify possible optimizations.
Data import best practices:

- Don't include static data (resources) in daily scheduled backups. A site can be exported without static content.
- Run impex jobs sparingly.
- Keep a main record of median job runtimes.
- Calculate the job load factor: total number of seconds job execution time on an instance on a day, divided by 86,400 (number of seconds in a day).
- When modifying objects, always favor standard imports over customizations.
- Design impex jobs so that they recover automatically by recognizing which files haven't been imported yet during subsequent execution.

### Increase in Errors and Warnings in Log Center

- Check for errors in Log Center that may correlate with your issue.
  Navigate to **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup** > **Log Center**.
- Check your quotas and deprecated APIs.
  Navigate to **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Deprecated API Usage**.
- Check if you’re experiencing a real-time performance issue flow.
  Resource lock occurs when two jobs are executed simultaneously, locking on the same resource.
- Check for third-party services for any third-party issues.
  Navigate to **Business Manager**. Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Services**.

## Reports and Dashboards

Reports and Dashboards can help you drill into insights on technical operations, site traffic, real-time performance metrics, and other aspects of your B2C Commerce sites.
If you notice an increase in system workload at a certain time, review what changes were made on the instance at the time such as, code and data deployment, replication, long running jobs, or ongoing sales or promotions.
If you notice an increase in sessions or requests without many changes in orders, this can generally point to an issue with BOT traffic. The Traffic dashboard shows data about the visitors to your site, and can be used to investigate issues related to BOT traffic, which may be causing performance issues to your site.
Performance of a controller has a direct correlation with the performance of your site, in particular your page load time. Therefore, it’s important to make sure that controllers are tuned to give the best response time.
The Technical Reports dashboard gives you insights about your site’s server-side technical operations data, including pipelines and controllers. To maximize the scalability and stability of your customization, particularly when the environment is under increased load, the critical storefront controllers should be at or below the average processing times suggested.

1. Open **Main Controller Requests** > **Technical tab**, and sort by requests in descending order and show the controllers that have been requested the most.
   It is important to have such controllers tuned to the finest.
2. Click into the controllers and view remote-includes controllers to understand where the time is most spent.

**Page Cache and Performance**

- An uncached request takes longer, as it must pass through multiple servers (web > application > database). Each layer amounts to more work, lengthening response time.
- A controller that uses fully cached templates optimizes the processing of requests, serving from cache right away and eliminating execution delay.
- The more templates that are cached, the faster the site loads and the less stress that is placed on the environment -- increasing scalability.

Use the Technical tab to view the cache hit, cache miss, and cache miss and store of each controller. If you have poor cache hit ratio for certain controllers, review the caching strategy.

## Gathering Data Before Entering a Ticket

Gathering good data is the most helpful thing to do before contacting Support.
Identify changes to your code or data to narrow down the possible causes of the problem:

1. Is the problem reproducible or intermittent?
2. If reproducible, what are the steps to reproduce?
3. Did any of the following happen right before the performance issues started:

   - Replication of data or code:
     - In **Business Manager**, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration**> **Replication**> **Data Replication**
     - In **Business Manager**, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration**> **Replication**> **Code Replication**
   - Manual editing of data on the Production instance.
   - Manual clearing of the cache or a cache partition on the Production instance.
   - Import of a large data feed.

4. Capture HAR file while reproducing the issue.
5. Capture the DWSID to be shared in the support ticket.

<!-- document id=91996214a9df3d05b74028a3b88869025ba550c38a6ffd26ffc8317a4b68704d url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-debug-troubleshoot.md -->

# Troubleshooting Tips for Storefront Next

Before following the targeted advice in this guide, try these general troubleshooting steps.

- Double-check that you’re running a supported version of Node before starting your local development server.
- Confirm that your development server is still running and the port hasn’t been taken over by another process.
- After saving a code change, the browser updates automatically via Hot Module Replacement (HMR). If the change doesn't appear, check the terminal for build errors before forcing a reload.
- Look for errors in both the browser console and in the terminal.
- Look for network error responses using your browser’s developer tools. (In Chrome’s DevTools, go to the **Network** tab.)
- To help identify syntax errors and typos, run a code formatter and a linter. The command for running lint is `pnpm lint` for checking and `pnpm lint:fix` for auto-fixing lint issues. Configuration files are provided for both [Prettier](https://prettier.io/) (code formatter) and [ESLint](https://eslint.org/) (linter) in the Storefront Next app.
- To catch TypeScript errors that don't show up at run time, run `pnpm typecheck`.
- To see SCAPI requests and internal state changes, run `SFCC_LOG_LEVEL=debug pnpm dev` to increase log verbosity.
- Check your computer’s antivirus and firewall settings for anything that is preventing your code from running or blocking network requests.
- To identify and analyze performance issues, use the Profiler in Chrome’s DevTools. For more information, see this guide from Google: [Analyze Runtime Performance](https://developer.chrome.com/docs/devtools/performance). You can also install the React Developer Tools extension for Chrome to get another Profiler tab where you can see similar info but at the component level.

<!-- document id=9727d96be102907117c9dabaca88dcb9552e6eb2a4123bfcc68de3b9cd3317e4 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ops-troubleshooting/b2c-troubleshooting-session-id-request-id.md -->

# Troubleshooting with the Session ID and Request ID

When troubleshooting an issue, the session and request IDs can help you uncover key information.

The session and request IDs can help you uncover key information about what is going wrong.

## Session ID

The session ID is created by the Web Adapter during the first request. It's stored in a cookie and consists of:

- a random part
- the selected application server
- its creation time
- the check sum

```
Example: KEtLmGyI43gRwyow53NbmmyCjJy1Vshf1oU=
```

## Request ID

The request ID is also created by the Web Adapter, but as a random series of characters. It's passed with the request to the Application Server.

```
Example: y2PuahYWlogkQAgAKk
```

## Troubleshooting Client Side

Find the session ID and request ID on the client.

### Session ID

In browser address field: JavaScript:alert(document.cookie)

The cookie name is _sid._

### Request ID

To view information about request ID information on non-production systems with page caching _disabled,_ use the "Show Request Log".

## Troubleshooting Server Side

Find the session ID and request ID on the server.

On the server side, use the Salesforce B2C Commerce APIs to retrieve the session and request IDs.

| ID      | API                                  |
| ------- | ------------------------------------ |
| Session | dw.system.Session.sessionID : String |
| Request | dw.system.Request.requestID : String |

Important storefront Application pipelines:

- OnSession-Do - called during first request of session, also if a cached page is delivered
- OnRequest-Do - called for each request, also if a cached page is delivered
- Prefix-Start - called before the actual pipeline if dynamic response is delivered

Important parameters for code instrumentation:

- Request.gethttpQueryString
- Request.gethttpReferer
- Request.gethttpUserAgent

See the B2C Commerce API Documentation for more information.

<!-- document id=12fda1bdc385e1684c023ece544fddce99f2a1f6bcdf60530e7f75486af4df62 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-trusted-agent.md -->

# Trusted Agent Authorization

Trusted Agent on Behalf (TAOB) authorization allows an agent to perform actions on behalf of a registered or guest shopper.

**note:** By default, shopper tracking preferences are disabled for all TAOB flows, which means that `dnt` is set to `true`. This differs from other SLAS token requests, in which `dnt` is set to `false`.

## Configure Trusted Agent Authorization

1. Configure Business Manager permissions:

- In Business Manager, configure the following functional permissions for one or more agents in your organization: `Login_On_Behalf` and `Create_Order_On_Behalf`.
- For detailed instructions, see the [Business Manager Functional Permissions](https://help.salesforce.com/s/articleView?id=cc.b2c_administrator_role.htm&type=5) article in the B2C Commerce documentation.

2. Configure SLAS:

- Create a dedicated public client ID to use in the OAuth `auth_code` PKCE flow. For details, see [Public SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html).
- Add the `sfcc.ta_ext_on_behalf_of` scope to your SLAS client.
- Set a redirect URI.

3. Perform the steps for registered and guest shoppers in the following sections, as applicable.
4. To initialize an Agentforce session, obtain a SLAS shopper access token that includes the `sfcc.shopper-agents.rw` scope, and then call the [Shopper Agents API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-agents?meta=Summary) with the `sessionInitKey` received at session start.

### Specify TAOB Parameters for Guest Shoppers

**note:** Make sure you use the public client ID created when configuring SLAS.

1. Set `login_id` to `guest`.
2. Set `idp_origin` to `slas`. This is standard for SLAS Guest requests. If any other `idp_origin` value is used, SLAS returns a bad request.
3. If the trusted agent needs access to the existing basket of a guest shopper (viewing or updating), you must pass the same USID that was included in the shopper token.
4. You must pass the `state` parameter in the TAOB guest Token request to get the TAOB `access_token` to transfer the state from the authorization call to the token call. The `state` parameter value is returned with the authorization code in the response url from the TAOB guest authorization call, for example:
   `.../taob/callback?code=HETXpvg5LKBNIHjDTWkRrf2MLVU&state=taob.gst.7bc7fb7f-e646-44fd-bc73-dfd5c3c9019b`

![SLAS trusted agent authentication for guest users](https://developer.salesforce.com/docs/media/commerce-api/slas-trusted-agent-guest.png)

#### Example: TAOB Authorization Request for a Guest Shopper

```bash
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organization/$ORG/oauth2/trusted-agent/authorize'
\--get
\--data "client_id=$CLIENT"
\--data "channel_id=$SITE"
\--data "redirect_uri=$REDIRECT"
\--data 'response_type=code'
\--data 'idp_origin=slas'
\--data-urlencode "login_id=guest"
\--data "code_challenge=$CHALLENGE'
```

#### Example: TAOB Token Request for a Guest Shopper

In the authorization header, use the value from the `code` query parameter that was returned when the agent authenticated with Account Manager:

```bash
curl 'https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organization/$ORG/oauth2/trusted-agent/token' \
--header 'Authorization: Bearer jpsM6DNwzFtrUIZJDwyRihkRX1g' \
--data "client_id=$CLIENT" \
--data "channel_id=$SITE" \
--data 'grant_type=client_credentials' \
--data 'idp_origin=slas' \
--data-urlencode 'login_id=guest' \
--data-urlencode 'agent_id=example@yourdomain.com' \
--data-urlencode 'channel_id=SiteGenesis' \
--data 'code_verifier=`$VERIFIER' \
--data 'state=taobgst.3ebdcbb6-ef87-4f41-8173-67728636e513'
```

### Specify TAOB Parameters for Registered Shoppers

**note:** Make sure you use the public client ID created when configuring SLAS.

1. Set `login_id` to the shopper's credentials.
2. Set `idp_origin` to `ecom`.

Consider the following scenario where trusted agent authorization is used to help a registered shopper:

1. Lauren is a call center agent who helps shoppers with their orders.
2. Tim is a shopper who contacts the call center. He wants to update the quantity of shirts in his order but is having difficulty doing it himself.
3. Using the SLAS TAOB flow, Lauren gains access to Tim’s account, which gives her access to the items added to the cart.
4. Lauren successfully updates the quantity of shirts in Tim’s order.
5. Tim is pleased with the Lauren’s help and completes his order.

**note:** This flow is specifically for Account Manager when it serves as the IDP for agents. For agents using a different IDP, consider using the [SLAS Trusted System On-behalf (TSOB)](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-trusted-system.html) call flow to provide the SLAS shopper JSON Web Token (JWT) in your custom agent solution.

The following diagram shows the typical API requests and responses used in the trusted agent authorization flow for a registered shopper:

![SLAS trusted agent authentication and authorization process](https://developer.salesforce.com/docs/media/commerce-api/slas-trusted-agent.png)

#### Example: TAOB Authorization Request for a Registered Shopper

The following commands demonstrate how to authorize a trusted agent using a public client.

**important:** When running the sample code provided, don’t forget to replace the placeholder values with actual values.

Start by requesting an authorization code for a trusted agent using [getTrustedAgentAuthorizationToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedAgentAuthorizationToken):

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organization/$ORG/oauth2/trusted-agent/authorize" \
--get \
--data "client_id=$CLIENT" \
--data "channel_id=$SITE" \
--data "redirect_uri=$REDIRECT" \
--data 'response_type=code' \
--data 'idp_origin=ecom' \
--data-urlencode "login_id=jack.shopper" \
--data-urlencode 'agent_id=example@yourdomain.com' \
--data-urlencode 'channel_id=SiteGenesis' \
--data "code_challenge=$CHALLENGE"
```

The request redirects you to Account Manager for authentication. After a successful login, you are redirected to the address provided in the `redirect_uri` parameter of the previous request. When redirecting, the authorization code is included in the `code` query parameter.

Now request a trusted agent token using [getTrustedAgentAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedAgentAccessToken). In the authorization header, use the value from the `code` query parameter that was returned when the agent authenticated with Account Manager:

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/shopper/auth/v1/organization/$ORG/oauth2/trusted-agent/token" \
--header 'Authorization: Bearer jpsM6DNwzFtrUIZJDwyRihkRX1g' \
--data "client_id=$CLIENT" \
--data "channel_id=$SITE" \
--data 'grant_type=client_credentials' \
--data 'idp_origin=ecom' \
--data-urlencode 'login_id=jack.shopper' \
--data "code_verifier=$VERIFIER"
```

**note:** Trusted agent tokens expire after 15 minutes and are not refreshable. _To get a new token, restart the authorization flow._

<!-- ## Constraints

Trusted agent tokens work with all SCAPI Shopper endpoints but are only supported by a subset of OCAPI Shop endpoints:

| Required Business Manager Role | Endpoint                             | HTTP Methods                  |
| ------------------------------ | ------------------------------------ | ----------------------------- |
| `Create_Order_On_Behalf_Of`    | `/orders/**`                         | GET, POST, DELETE, PATCH, PUT |
| `Create_Order_On_Behalf_Of`    | `/baskets/**`                        | POST, PUT, DELETE, PATCH, GET |
| `Create_Order_On_Behalf_Of`    | `/customers/**`                      | GET, POST, PATCH, PUT         |
| `Create_Order_On_Behalf_Of`    | `/customers/*/addresses/*`           | DELETE                        |
| `Create_Order_On_Behalf_Of`    | `/customers/*/payment_instruments/*` | DELETE                        |
| `Create_Order_On_Behalf_Of`    | `/customers/*/product_lists/**`      | DELETE                        |
| `Create_Order_On_Behalf_Of`    | `/gift_certificate`                  | POST                          |
| `Create_Order_On_Behalf_Of`    | `/customers/**`                      | GET, POST, PATCH              |
| `Create_Order_On_Behalf_Of`    | `/customer_lists/**`                 | GET, POST                     |
| `Search_Orders`                | `/order_search/*`                    | POST                          |
| `Handle_External_Orders`       | `/baskets/calculate`                 | POST                          |
| `Handle_External_Orders`       | `/baskets/shipping_methods`          | POST                          |

Calling non-supported OCAPI Shop endpoints results in a HTTP 403 `user-access-forbidden` response.

To call non-supported OCAPI Shop endpoints use a second token from [getTrustedSystemAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getTrustedSystemAccessToken) or [getAccessToken](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getAccessToken). -->

## Troubleshoot

- If you receive the following response code, verify the SLAS configuration and Business Manager permissions:
  ```json
  {
  "status_code": "403 FORBIDDEN",
  "message": "AM SSO Unauthorized!"
  }
  ```
- The following response code indicates that the `agent_id` and the `login_id` are the same, which is not allowed:
  ```json
  {
    "status_code": "403 FORBIDDEN",
    "message": "Agent Id - AM SSO Unauthorized!"
  }
  ```

<!-- document id=339ab88a304e078e8dd50dbd81cee7eebc1548f5276cc6eecd5addde5d24913c url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-ui-styling.md -->

# UI Styling

UI styling shapes the storefront's look and feel, including layout, spacing, colors, typography, and interactive states. It provides a consistent, accessible, and responsive shopping experience for your storefront across devices.

## Technology Stack

Storefront Next uses [Tailwind CSS](https://tailwindcss.com/) (v4) for utility-first styling and [shadcn/ui](https://ui.shadcn.com/) patterns, and [Radix UI](https://www.radix-ui.com/) for headless accessible components.

Here are the Tailwind-related dependencies in this package.

Verify dependency versions against the template package.json before each release to ensure version numbers are current.

| Dependency               | Version | Purpose                            |
| ------------------------ | ------- | ---------------------------------- |
| tailwindcss              | 4.x.x+  | Utility-first CSS framework        |
| @radix-ui/\*             | Various | Headless UI primitives             |
| class-variance-authority | 0.7.1   | Component variant management       |
| clsx                     | 2.1.1   | Conditional class composition      |
| tailwind-merge           | 3.4.0   | Tailwind class conflict resolution |

## Tailwind CSS Rules

- Use **Tailwind utility classes** in component JSX for layout, spacing, typography, and colors.
- Use the **`cn()` utility** for conditional or combined class names: `import { cn } from '@/lib/utils'`. Example: `cn('rounded p-4', isActive && 'ring-2')`.
- Follow **mobile-first** responsive patterns using breakpoint prefixes: `sm:`, `md:`, `lg:`, `xl:`, `2xl:`.
- **Do not use inline styles** (`style={{ ... }}`) for styling.
- **Do not use CSS modules** (`.module.css`) or separate CSS files for component-level styles.
- **Global and theme styles** belong in `src/theme/` only. The entry point is `src/theme/index.css`, with tokens split across `src/theme/tokens/`, base resets in `src/theme/base.css`, and component overrides in `src/theme/overrides/`.

## Design Tokens

Colors and theme values are defined as CSS variables (design tokens). Use semantic token-based classes instead of hard-coded colors:

- Backgrounds: `bg-background`, `bg-muted`, `bg-card`
- Text: `text-foreground`, `text-muted-foreground`, `text-primary`
- Borders: `border-border`
- Interactive: `bg-primary`, `text-primary-foreground`, `hover:bg-primary/90`

Avoid raw color utilities (e.g. `bg-[#hex]`) so the app stays consistent with the theme.

## Global Styles and CSS Variables

The global and theme styles are in `src/theme/` only. The entry point is `src/theme/index.css`, with tokens split across `src/theme/tokens/`, base resets in `src/theme/base.css`, and component overrides in `src/theme/overrides/`.

```css
@import "tailwindcss";
@import "tw-animate-css";

@theme inline {
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... more semantic tokens */
}

:root {
  --radius: 0.625rem;
  --background: #ffffff;
  --foreground: #3f3f46;
  --primary: #2563eb;
  --primary-foreground: #ffffff;
  --secondary: #f3f4f6;
  --muted: #f9fafb;
  --accent: #dbeafe;
  --destructive: #b91c1c;
  --border: #fafafa;
  --ring: #3b82f6;
  /* ... more tokens */
}
```

## shadcn/ui

Presentational UI components are built on **Radix UI primitives** with **shadcn/ui** as the styling layer. They live in `src/components/ui/`.

### Adding Components

Add new components only via the official CLI so they are ejected with the correct config and Tailwind setup:

```bash
npx shadcn@latest add <component-name>
```

This ejects the component into `src/components/ui/` with the right dependencies and styles.

### Rules

- **Do** add and customize shadcn components by editing the files in `src/components/ui/`.
- **Do not** create custom components inside `src/components/ui/`; keep that directory for ejected shadcn components only.
- **Do not** manually copy components from the shadcn docs; always use the CLI so configuration (e.g. `components.json`) stays in sync.

Keeping `src/components/ui/` limited to ejected shadcn components makes upgrades and maintenance predictable. For custom UI, use `src/components/` (or another feature directory) and compose or wrap shadcn components as needed.

## UI Component Architecture

Components are stored in `src/components/ui/` and follow the shadcn/ui pattern.

- Built on Radix UI primitives for accessibility.
- Styled with Tailwind utility classes.
- Variants managed with `class-variance-authority` (cva).
- Classes composed using `cn()` utility (clsx + tailwind-merge).

## The cn() Utility

A helper function that combines `clsx` for conditional classes with `tailwind-merge` to resolve conflicting utilities.

```ts
// src/lib/utils.ts
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
    return twMerge(clsx(inputs));
}
```

## Component Styling Patterns

Style patterns for components include variant-based components with CVA, compound components, and direct utility class usage.

### Variant-Based Components with CVA

With CVA, you can create variants of an existing component by extending its Tailwind classes without overriding them. Here's a minimal example.

```ts
// src/components/ui/button.tsx (simplified example)
import { cn } from "@/lib/utils";

type ButtonVariant = "default" | "outline";
type ButtonSize = "default" | "sm";

const variantClasses: Record<ButtonVariant, string> = {
  default: "bg-primary text-primary-foreground hover:bg-primary/90",
  outline: "border bg-background hover:bg-accent hover:text-accent-foreground",
};

const sizeClasses: Record<ButtonSize, string> = {
  default: "h-9 px-4 py-2",
  sm: "h-8 px-3 text-xs",
};

function Button({
  variant = "default",
  size = "default",
  className,
  ...props
}: React.ComponentProps<"button"> & {
  variant?: ButtonVariant;
  size?: ButtonSize;
}) {
  return (
    <button
      className={cn(
        "inline-flex items-center justify-center rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50",
        variantClasses[variant],
        sizeClasses[size],
        className,
      )}
      {...props}
    />
  );
}
```

### Compound Components

Multi-part components are organized as separate functions:

```ts
// src/components/ui/card.tsx
function Card({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      className={cn(
        "bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm",
        className,
      )}
      {...props}
    />
  );
}

function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
  return (
    <div
      className={cn(
        "@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6",
        className,
      )}
      {...props}
    />
  );
}
```

### Direct Utility Class Usage

Feature components apply Tailwind classes directly.

```tsx
<Card
  className={cn(
    "group border rounded-xl overflow-hidden w-full min-w-0 max-w-full",
    "flex flex-col-reverse h-full shadow-sm gap-0 py-0",
    "transition-all duration-200 hover:shadow-md",
    className,
  )}
>
  {/* ... */}
</Card>
```

## Responsive Design

Tailwind uses prefix-based responsive modifiers.

```tsx
<div className="px-4 sm:px-6 lg:px-8 py-8">
  <div className="grid md:grid-cols-2 gap-6">{/* Content */}</div>
  <div className="flex flex-col sm:flex-row gap-4 justify-center">{/* Buttons */}</div>
</div>
```

## Color Utility Enforcement

Hardcoded Tailwind color utilities like `bg-red` and `text-green` are blocked via an ESLint rule. Use semantic tokens (for example, `bg-primary`, `text-foreground`) or CSS variable classes instead.

## Component Library and Icons

- **Radix UI**: Use Radix primitives for accessible behavior (focus, keyboard, ARIA).
- **Icons**: Use **Lucide React** and **React Simple Icons** for iconography.

## CSS-Only Decorative Icons

When you want a purely decorative icon in front of (or after) an element whose component you shouldn't fork — a shared title, a label rendered deep in a shadcn primitive — add it with a `::before` or `::after` pseudo-element in theme CSS instead of editing the JSX. This keeps component-level styling out of components and lets you hook a stable `data-slot` or structural selector rather than threading a prop through.

The tokens, selectors, and icons below are examples only. Adapt them to your own storefront. The file paths (`src/theme/tokens/core.css`, and `src/theme/base.css`) are where global tokens and base rules live.

**Use `mask` + `background-color`, not `content: url(...)`.** A masked SVG is tintable: `background-color: currentColor` paints the icon in the element's text color, so it tracks light/dark and theme changes automatically. A `content: url(...)` image renders at its baked-in colors and can't inherit `currentColor`.

Define the SVG once as a token so it's reusable and themeable. Percent-encode the SVG so characters like `#`, `%`, `<`, `>`, and quotes survive the data URI intact — an unencoded `#` or `%` truncates the URI and the mask silently fails to load. Inside a mask, the SVG's alpha channel is what matters; the stroke color is never painted, so use a literal `black` as the stroke value (not `currentColor`, which doesn't resolve inside a mask). The visible color comes from `background-color` on the pseudo-element.

```css
/* src/theme/tokens/core.css */
--icon-star: url("data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2224%22%20height%3D%2224%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%20stroke%3D%22black%22%20stroke-width%3D%222%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Cpath%20d%3D%22M11.525%202.295a.53.53%200%200%201%20.95%200l2.31%204.679a2.123%202.123%200%200%200%201.595%201.16l5.166.756a.53.53%200%200%201%20.294.904l-3.736%203.638a2.123%202.123%200%200%200-.611%201.878l.882%205.14a.53.53%200%200%201-.771.56l-4.618-2.428a2.122%202.122%200%200%200-1.973%200L6.28%2021.28a.53.53%200%200%201-.77-.56l.881-5.139a2.122%202.122%200%200%200-.611-1.879L2.045%209.865a.53.53%200%200%201%20.294-.904l5.166-.755a2.122%202.122%200%200%200%201.597-1.16z%22%2F%3E%3C%2Fsvg%3E");
--icon-check: url("data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%2224%22%20height%3D%2224%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%20stroke%3D%22black%22%20stroke-width%3D%222%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%3E%3Cpath%20d%3D%22M20%206%209%2017l-5-5%22%2F%3E%3C%2Fsvg%3E");
```

Apply the icon using `::before` or `::after` in `src/theme/base.css`. Set `content: ""` to activate the pseudo-element, then apply the mask and let `background-color: currentColor` tint it to match the surrounding text color.

```css
/* src/theme/base.css */
[data-slot="section-title"] {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
}

[data-slot="section-title"]::before {
  content: "";
  display: inline-block;
  flex-shrink: 0;
  width: 1rem;
  height: 1rem;
  background-color: currentColor;
  -webkit-mask: var(--icon-star) center / contain no-repeat;
  mask: var(--icon-star) center / contain no-repeat;
}
```

**Swap icons on state by toggling only the mask.** Have the component set a `data-*` attribute on an ancestor when state changes, then add a rule that overrides just the mask image — the size and tint stay in place.

```css
[data-slot="section-title"][data-complete]::before {
  -webkit-mask: var(--icon-check) center / contain no-repeat;
  mask: var(--icon-check) center / contain no-repeat;
}
```

**note:** Keep the decorated structure stable. Decoration hooked to structural selectors (`data-slot`, `:first-child`, `> span`) breaks if that structure shifts. Keep anchored elements mounted — render them empty rather than conditionally removing them — so the icon doesn't detach. If you decorate by position, don't conditionally add or remove the siblings around the decorated element.

## Accessibility and Design System

- Use **semantic HTML** (`<button>`, `<nav>`, `<main>`, etc.) and appropriate **ARIA** where needed.
- Ensure **keyboard navigation** and visible **focus states** for interactive elements.
- Aim for **WCAG** compliance (contrast, focus order, labels).
- Keep **spacing and typography** consistent with the design system defined in `src/theme/` and Tailwind config.

## Reusing Styles: When to Extract

Tailwind's utility-first approach means most styling lives inline in JSX. Before extracting a reusable abstraction, read the official guide on [managing reuse](https://tailwindcss.com/docs/styling-with-utility-classes#managing-duplication) — it covers multi-cursor editing, loops, and component extraction as the **preferred** strategies before reaching for CSS abstractions.

**Use a React component** (the default choice) when:

- The pattern involves markup structure—multiple elements, slots, children
- There is logic, state, or event handling
- It accepts props that change behavior or content
- It composes other components (shadcn, Radix, etc.)

**Use a CSS component class** (`@layer components` in `src/theme/base.css`) only when:

- The pattern is pure layout/styling—padding, max-width, centering, typography presets
- There is no logic, state, or props—just a bag of CSS properties
- It needs to be applied to many different HTML elements across the codebase (divs, sections, wrappers)
- Utilities need to override it in specific contexts (the components layer is lower specificity than utilities)

Example: `section-container`—consolidates `px-4 sm:px-8 lg:px-16 max-w-screen-2xl mx-auto` into one class, used by 30+ files. A page can add `max-w-4xl` alongside it and the utility wins.

**Rule of thumb**: if you can express it as a single `className` string with no JSX children, it's a CSS class. If it renders elements or accepts props, it's a React component.

```css
/* src/theme/base.css — CSS component class */
@layer components {
  .section-container {
    @apply px-4 sm:px-8 lg:px-16 max-w-screen-2xl mx-auto;
  }
}
```

```tsx
/* React component — has structure, props, and children */
function CategoryBanner({ title, image }: CategoryBannerProps) {
  return (
    <div className="section-container">
      <img src={image} alt="" />
      <h1>{title}</h1>
    </div>
  );
}
```

**note:** Don't use `@utility` for multi-property compositions that need to be overridable. The utility layer has the highest specificity, so any override attempt (e.g., adding `max-w-4xl` alongside a `@utility` class) would lose. Use `@layer components` instead.

## Summary

Quick reference:

| Do                                                       | Don't                                                           |
| -------------------------------------------------------- | --------------------------------------------------------------- |
| Tailwind utility classes                                 | Inline styles, CSS modules, component-level `.css` files        |
| `cn()` for conditional classes                           | Manual string concatenation for `className`                     |
| Design tokens (`bg-background`, `text-muted-foreground`) | Hard-coded colors                                               |
| `npx shadcn@latest add <name>`                           | Manually copying or creating components in `src/components/ui/` |
| Global/theme styles in `src/theme/`                      | Scattered or duplicate global CSS                               |

<!-- document id=3de7014c7e437593465606a8a13c2094d0a8c11b4a34641dfd6fa9acbd58c23f url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-place-order-apis-overview.md -->

# Understanding B2B Checkout Place Order APIs

Choose between two Place Order implementations based on your requirements.

- [Commerce Webstore Checkout Orders API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-orders-api.md)
- [Commerce Webstore Place Order Action API](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order-action-api.md)
- [API Comparison](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/b2b-comm-checkout-place-order-api-comparison.md)

<!-- document id=d6dedf8965ecb0d0f596971c39b37dbea03ce6a0d96adf4eb45847f8ea8f873d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ops-troubleshooting/b2c-understanding-remote-includes.md -->

# Understanding Remote Includes

Understanding how remote includes work can help trace problems.

Each remote include is an additional request to the Application Server, and can be cached. The Web Adapter actually assembles the page. Remote includes can include other remote includes.

## Request ID

The Web Adapter assigns a request ID to the client request. For remote includes, the request ID has been extended to uniquely identify requests that go to the Application Server with this format:

```
requestID-includeDepth-includeNumber
```

## Example

```
main request: ZAm5zUVvcQ4KAgAK-0-00
1st remote include on main page: ZAm5zUVvcQ4KAgAK-1-01
2nd remote include on main page: ZAm5zUVvcQ4KAgAK-1-02
3rd remote include on main page: ZAm5zUVvcQ4KAgAK-1-03
Remote include on 3rd remote include on main page: ZAm5zUVvcQ4KAgAK-2-04
```

<!-- document id=e80399572cba323205d575153b2fd2969ec337c8a12a2c140864e23957ff79b7 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/scriptprogramming/understandingserversidejavascript.md -->

# Understanding Server-Side JavaScript

The B2C Commerce development components give you a great deal of flexibility in how you customize your ecommerce application. You develop your application locally, but run it on the server. A JavaScript interpreter runs on the application server to process each JavaScript class or method.

![Diagram showing how a JavaScript interpreter on the B2C Commerce application server processes scripts and API calls](https://developer.salesforce.com/media/b2c-commerce/scriptcompile.gif)

Use the B2C Commerce APIs (a combination of Javascripts and pipelets) to make scripting calls. Standard pipelets uses the APIs internally. To the JavaScript interpreter, the source of the script call is irrelevant.

B2C Commerce development components that can make JavaScript calls include the following:

| Component | Description                                                                                                                                                                                                                                                                                                                                                                           | Scripting Usage                                                                                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Pipeline  | Models the business process of the storefront application, including the actual business process, page display, and data input and validation. For example, the _stores_ pipeline locates the nearest stores and lists them on the browser.                                                                                                                                           | Use an EVAL pipelet to evaluate an expression.                                                                                                                     |
| Pipelet   | Small, reusable units or building blocks that define B2C Commerce business logic. For example, the addProductToBasket pipelet within the cart pipeline creates and returns a ProductLineItem by assigning the specified Product and Quantity to the specified Basket.                                                                                                                 | Custom: Create a pipelet within a pipeline that calls a`script.ds` file to invoke a new business process. Standard: Access JavaScript for commonly used processes. |
| Template  | Templates define how data and page information is transformed into the HTML that is rendered on a browser. For example, the cart template defines how the cart page appears, which includes basket contents, shipping types, product variations, availability, promotions, and shipping and tax calculations. This template uses `<isscript>` to run through odd and even row colors. | Access a business process via an `<isscript>` tag, or wherever B2C Commerce JavaScript APIs are used.                                                              |

How you use each of these elements depends on your application requirements.

For more information on the APIs, refer to the B2C Commerce Script API documentation.

## Cartridge Storage

B2C Commerce JavaScript must be stored in the /cartridge/scripts folder of a cartridge, with the .ds extension. However, it's possible to call a script from a different cartridge using the following syntax:

```
cartridge:folder\subfolder\scriptfile.ds
```

**note:** When you specify a script in this way, it doesn't search the cartridge path the way it would for a template, pipeline, js, or css file.

## Script Access Examples

Use examples to understand how to incorporate script into your storefront.

Consider the following examples, taken from the SiteGenesis application:

### Pipeline

The following is an example of using the _EVAL_ pipelet in a pipeline to evaluate an expression, which in this case is confirms the order status.

Pipeline: COPlaceOrder-PlaceOrder

Pipelet: EVAL: Confirm order

Expression: Order.setConfirmationStatus(Order.CONFIRMATION_STATUS_CONFIRMED)

### Pipelet: Custom

The `continueshopping.ds` script file is called by a `Script` pipelet in the `Cart-ContinueShipping` pipeline to find the last catalog click and return it as the target for the continue shopping button redirect.

```
/**
* The script finds the last catalog click and returns it
* as the target for a redirect.
*
* @output Location : String
*/
 importPackage( dw.system );
 importPackage( dw.web );
 importPackage( dw.util );
 function execute( pdict : PipelineDictionary ) : Number
{
 // find the last catalog related click
 var list : List = session.clickStream.clicks;
 for( var i = list.size()-1; i >= 0; i-- )
{
 var click : ClickStreamEntry = list[i];
 switch( click.pipelineName )
{
 case "Product-Show":
 // product detail page click
 pdict.Location = click.url.replace(/source=/g, "src=").replace(/format=/g, "frmt=");
 // hack to change product URL if it was viewed from search
 return PIPELET_NEXT;
 case "Search-Show":
 // catalog related click
 pdict.Location = click.url.replace(/source=/g, "src=").replace(/format=/g, "frmt=");
 // avoid showing product grid only
 return PIPELET_NEXT;
}
}
 // nothing found, go to the home page
 pdict.Location = URLUtils.httpHome().toString();
 return PIPELET_NEXT;
}
```

In the example, the script imports and uses API calls from `dw.system,` `dw.web,` and `dw.util.` The JavaScript class URLUtils.url is located in the `dw.util` package.

### Pipelet: Standard

The JavaScript used in a standard pipelet isn't public. For example, the `GetProduct` pipelet returns the product that is identified by a supplied product ID. The actual internal JavaScript code is unavailable to the developer.

### Template

The following portion of the `ordertotals.isml` template uses `<isscript>` to calculate order-level discounts as part of the order total.

```
<iscomment>calculate order level discounts</iscomment>
<isscript>
	var merchTotalExclOrderDiscounts : dw.value.Money = LineItemCtnr.getAdjustedMerchandizeTotalPrice(false);
	var merchTotalInclOrderDiscounts : dw.value.Money = LineItemCtnr.getAdjustedMerchandizeTotalPrice(true);
	var orderDiscount : dw.value.Money = merchTotalExclOrderDiscounts.subtract( merchTotalInclOrderDiscounts );
 </isscript>
```

The example uses the `getAdjustedMerchandizeTotalPrice` method.

## Using Input and Output Variables

Using standard JavaScript comment techniques, declare input and output variables to be used within a script.

### Defining Input and Output Variables in Scripts

You pass data into Salesforce B2C Commerce scripts using the `@input` annotation. You pass data out of a B2C Commerce script using the `@output` annotation.

#### Example: Input Variable Definition

In your script file, such as `GetDefaultVariant.ds`, you define the input variables and save the script file.

```
*   @input Prod : dw.catalog.Product
*   @input CurrentVariationModel : dw.catalog.ProductVariationModel
```

The example defines two input variables, `Product` and `CurrentVariationModel`, which contain string values. The last part of the variable definition is a description of the variable.

#### Example: Output Variable Definition

In your script file, such as `GetDefaultVariant.ds`, you define the output variables and save the script file.

```
*   @output newProduct : dw.catalog.Product
```

The example defines an output variable, `newProduct`, which contains a product object.

### Adding Dictionary Bindings

When you’ve saved the script files with the input and output variables defined, script node pipelet using the script adds a Dictionary Input section to the pipelet properties with the name of the input variables and a Dictionary Output section to the pipelet properties with the names of the output variables.

#### Example: Script Node Dictionary Input and Output Bindings

You bind values to the parameters by entering a string, a variable name, or an expression.

![Example of script node dictionary input and output bindings showing Prod bound to Product and CurrentVariationModel in the Pipeline Dictionary](https://developer.salesforce.com/media/b2c-commerce/InputandOutputVariableBindings.gif)

In the example above, the input variable `Prod` defined in your script file is bound to the `Product` variable in the Pipeline Dictionary. The input variable `CurrentVariationModel` defined in your script file is bound to the `Product` variable in the Pipeline Dictionary.

### Fixing Orphaned Dictionary Bindings

When you bind a value to a parameter, the binding is stored in the pipeline file. If you remove script parameters, the pipeline file sometimes retains bindings for these removed parameters. To correct this, UX Studio checks pipelines and identifies orphaned bindings. The orphaned bindings are reported as `Warnings` in the Problems and Markers views. Correct the problem by right-clicking the `Warning` and selecting the **Quick Fix** menu option.

## Library and Package Import

Library and package import features can speed development.

JavaScript libraries can be shared across cartridges using the importScript("cartridgename:path/scriptname.ds") syntax (the cartridge name is optional if the script is located in the current cartridge). Share JavaScript pipelets, which can be stored in a dedicated cartridge so they can be used from other cartridges.

**note:** To specify the script, use the file name of the actual script (name.ds), relative to the _scripts_ folder containing the pipeline or the scripts folder of another cartridge. A simple path refers to the pipeline cartridge and a prefix such as 'cartridgename:' refers to a specific cartridge.

| Feature           | Call                                               | Description                                   |
| ----------------- | -------------------------------------------------- | --------------------------------------------- |
| Import packages   | `importPackages( dw.util );`                       | Reuse processes that are outside the pipeline |
| Import class      | `importClass( dw.util.HashMap );`                  | Reuse classes that are outside the pipeline   |
| Library mechanism | `importScript( "mylib:export/orderhandling.ds" );` | Reuse scripts that are outside the pipeline   |

### Importing Packages

Use the B2C Commerce API `Import Package` as you would use a Java `Import` within a B2C Commerce JavaScript.

For example, consider the following statement:

![Script Package Support](https://developer.salesforce.com/media/b2c-commerce/scriptpackagesupport.gif)

## Iterating Over Objects

JavaScript 1.7 supports an Iterator class. This class is used in B2C Commerce for all `Collection` classes, for all `Map` classes, and for the `Iterator` (`dw.util.Iterator`) class.

When the `dw.util.Iterator` class isn't imported, "`Iterator`" refers to the native `Iterator` class. If `dw.util.Iterator` is imported, for example, with `importPackage( dw.util )`, then "`Iterator`" refers to the `dw.util.Iterator`.

These examples demonstrate iterating over objects.

```

		// iteration over all values in a list
			var l = new ArrayList( ... );
			for each( e in l ) {
				trace( e );
			}

		// iteration over all keys in a map
			var m = new SortedMap();
			m.put( "Joe", "111" );
			m.put( "Mary", "222" );
			m.put( "Jim", "333" );
			for( k in m ) {
				trace( k );
			}

		// --> Jim, Joe, Mary
		// iteration over all values in a map
			for each( v in m ) {
				trace( v );
			}

		// --> 333, 111, 222
		// iterating a SeekableIterator in a loop
			var result = queryCustomObjects( ... );
			for each( c in result ) {
				... do something with c ...
			}
```

## Iteration and Transaction Boundaries

When iterating over objects, make sure that you retrieve the object as part of the same transaction that acts on the object. Otherwise, B2C Commerce returns an error to prevent you from accidentally overwriting the object with stale data.

### Updating Objects Using Iterators

If a node has the Transactional property set to **True**, it executes as a separate transaction. Script nodes, by default, have the Transactional property set to `true`.

To successfully update objects, use one of the following methods:

#### Method 1: Commit Each Object in a Separate Transaction

Identify all objects to update, retrieve each object one at a time, and then update each object in a separate transaction. We recommended this method for updating objects.

An example is a pipeline that does the following:

1.  Assign node From_0 `dw.catalog.ProductMgr.queryAllSiteProducts()` To_0 `products`
2.  Loop node that iterates through products where the element key is `CurrentProduct` and the iterator key is `products`
    1.  GetProduct pipelet node supplies a ProductID of `CurrentProduct.ID` to retrieve a `Product`
    2.  Script pipelet node runs ScriptFile UpdateProducts.ds, a custom script file, which opens a transaction, updates the `Product,` and commits the transaction.

**note:** If you use this method, it's important to be aware if a transaction removes or modifies an object. If the object is referenced in later transactions, it might not exist.

#### Method 2: Commit in a Single Transaction

Update all objects in a single transaction. Use this method if you have only a few objects to update and you want changes to be made to all or none of the objects.

An example is a pipeline that does the following:

1.  Assign node From_0 `dw.catalog.ProductMgr.queryAllSiteProducts()` To_0 `products`
2.  Script pipelet node runs ScriptFile UpdateProducts.ds, a custom script file, which opens a transaction, iterates through each `product,` updates it, and commits the transaction.

**note:** If you use this method, it's important to be aware that:

- the transaction might become large, with a risk of exceeding the allowed transaction size and using a large amount of system resources.
- the transaction commit might fail due to other concurrent threads. If the commit fails, none of the objects are updated.

### Reusing Iterators

As a best practice, don’t reuse the same iterator in multiple pipelets in the same pipeline. Doing so can cause an `IllegalStateException: Iterator is invalid` error.

Iterators in this state don't return accurate results. Any attempt to use them results in a WARN log message that says `Iterator is invalid`. Scripts and pipelines that generate this error should be rewritten to make sure they generate correct and complete results.

For example:

1.  The `SearchSystemObject` pipelet creates a SearchResult iterator.
2.  The `ExportCustomers` pipelet uses that iterator to export the results to a file. As a side effect, the iterator moves to the end of the collection.
3.  A second pipelet attempts to use the same iterator. At this point, the iterator has been consumed so a warning is logged, and the results are inconsistent.

The correct way to reuse iterators is to repeat the `SearchSystemObject` step so that the second pipelet gets a fresh iterator.

## Error Handling in Scripts

JavaScript comes with built-in exception handling capabilities. These exception handlers make it possible to catch errors and resolve them internally, which insulates the user from complex decisions and cryptic technical information.

Throw exceptions using the `throw` statement and handle them using the `try...catch` statements (JavaScript 1.5 or higher).

| Statement     | Description                                                                                                                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `throw`       | Use the `throw` statement to throw an exception. When you throw an exception, you specify an expression containing the value of the exception:throw expression                                      |
| `try...catch` | The `try...catch` statement marks a block of statements to try, and specifies one or more responses should an exception be thrown. If an exception is thrown, the try...catch statement catches it. |

### Conditional Catch Statements

The B2C Commerce JavaScript Engine supports Mozilla's proprietary extension of conditional catch statements. Conditional catch statements can be compared with typed catch statements in Java.

```
try {
   ...
}
catch( e if e instanceof IOError ) {
   ...
}
```

In this example, the exception is only caught if the thrown object is an IOError. All other exception objects that don't meet the condition bubble up to other exception handlers. The condition can be any boolean expression, even an expression as in the following code example:

```
try {
   ...
}
catch( e if e instanceof IOError && e.javaName == 'TimeoutException' ) {
   ..
}
```

In this example, B2C Commerce's extension to the error classes, which adds information about the underlying Java exception, is used to further constrain the catch statement.

### Server-Side JavaScript Error Handing

Specific classes in the top-level API script package handle server-side JavaScript errors, as follows:

| Exception Type   | Description                                                                                                                                                                                                                                                                       |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Conversion Error | Represents a conversion error. For example, between string and JavaScript objects.                                                                                                                                                                                                |
| Error            | Error represents a generic exception.                                                                                                                                                                                                                                             |
| _EvalError_      | Represents an evaluation error. The eval() function is used in an incorrect manner.                                                                                                                                                                                               |
| Fault            | Indicates an RPC-related error in the system. It's always related to a systems internal Java exception. In particular, it provides details about the error sent from the remote system.                                                                                           |
| InternalError    | Represents an internal error.                                                                                                                                                                                                                                                     |
| IOError          | Indicates an I/O related error in the system. It's always related to a systems internal Java exception. The class provides access to more details about this internal Java exception.                                                                                             |
| _RangeError_     | Represents a range error. A numeric variable exceeds its allowed range.                                                                                                                                                                                                           |
| _ReferenceError_ | Represents a reference error. An invalid reference is used.                                                                                                                                                                                                                       |
| _SyntaxError_    | Represents a syntax error. A syntax error occurs while parsing JavaScript code.                                                                                                                                                                                                   |
| SystemError      | This error is always related to a systems internal Java exception. This error indicates an error in the system, which doesn't fall into any of the other categories, such as, IOError. The class provides access to more details about this internal Java exception.              |
| _TypeError_      | The type of a variable isn't as expected.                                                                                                                                                                                                                                         |
| _URIError_       | The encodeURI() or decodeURI() functions are used in an incorrect manner.                                                                                                                                                                                                         |
| XMLStreamError   | This error is always related to a systems internal Java exception. This error indicates an XML streaming-related error in the system. The class provides access to more details about this internal Java exception. In particular, the class describes the location of the error. |

**note:** The italicized errors are the six primary ECMAScript exception types defined by the JavaScript 1.5 specification.

### Internal JavaExceptions

Beyond the standard JavaScript error classes, B2C Commerce maps internal JavaExceptions to the following errors in JavaScript:

| Error          | Description                                    |
| -------------- | ---------------------------------------------- |
| IOError        | IOException, SOAPException, and all subclasses |
| Fault          | SOAP fault                                     |
| XMLStreamError | Errors related to an XML stream                |
| SystemError    | All other Java Exceptions                      |

**note:** In general, Java errors such as an OutOfMemoryException, can't be caught in scripting code. See Java concerning exception versus error.

## Script Timeout Configuration

The timeout values for `SFTPClient`, `HTTPClient`, and `webreference` objects are based on the timeout value of the calling script. The script timeout value is used as an upper bound for the timeout that is configured for the `SFTPClient` and `HTTPClient`.

It’s recommended to use the service framework, which has multiple monitoring and management features for web services. Nevertheless, for HTTPClient or SFTPClient, the timeouts can also be set as part of the function call.

To view the default global timeout:

1.  Select **Administration** > **Global Preferences** > **Global Timeouts**.

If you’re having difficulty with scripts timing out while calling a third-party system or service, contact Customer Support to change the timeouts temporarily.

## Custom Log Categories

B2C Commerce logging supports log categories in a way that is similar to Log4J2 (a Java-based logging utility supported by Apache Software Foundation). A log category is basically a name, where a dot in the name is interpreted as a hierarchical structure. For example, the log category "product.import" would be a subcategory of "product". All categories are subcategories of a "root" category.

B2C Commerce's category rules are:

- If logging is enabled for a category, it’s also enabled for all of its subcategories
- If logging is enabled for a specific severity level, then it's also enabled for all the higher severity levels

Examples:

| If...                                                                | Then...                                                                                                                                 |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Logging is enabled for "product"                                     | It's also enabled for "product.import"                                                                                                  |
| logging is enabled for the root logger                               | It's enabled for all custom log categories                                                                                              |
| WARN logging is enabled for "product"                                | WARN and ERROR are logged for "product" and all its subcategories                                                                       |
| WARN logging is enabled for "product" and DEBUG for "product.import" | WARN and ERROR are logged for "product" and all its subcategories, for the subcategory "product.import" also DEBUG and INFO are logged. |

Example: :

```
function sendOrder() {
   var logger = Logger.getLogger( "order.send" );
   ...
   logger.debug( "Sending order #{}", order.getOrderNumber() );
   ...
}
```

### NDC Support

With Nested Diagnostic Context (NDC), the application can provide more context information, which is associated with the current running thread. A simple string can be provided as NDC, which is organized like a stack. Both the NDC and log category are reported as a standard element of the actual log message. The following example shows how to use this feature.

```
function process() {
   Log.getNDC().push( "order.processing" );
   try
   {
      ...
   }
   finally
   {
      Log.getNDC().pop();
   }
}
```

### Message Format

Message formatting supports a simple '{}' for inserting an argument. The method is tolerant if more argument placeholders are provided then arguments exist. In that case, the placeholder isn't replaced but remains a '{}'.

For backwards compatibility, B2C Commerce also supports Java message formatting.

### Configure Custom Log Categories

Using log category-specific filters, decide which messages are made available to log targets. Use filter rules to define which log messages are generated. The changes you make become active after you click **Save**.

The hierarchy of logging levels in B2C Commerce is Fatal, Error, Warn, Info, and Debug. Create your own categories of messages that are specific to the scripts you’re developing.

**note:** System log messages aren’t configurable.

We recommend that you plan a simple hierarchy of logging messages before creating logging categories. For example, you might want to plan category names that include the script name, object, and method as a standard. Having a standard set of logging names can make code maintenance easier.

B2C Commerce's custom logging is modeled after log4j logging. Logging uses hierarchical category names, granular logging, and similar methods for creating log statements in your code. For example, if you create three logging categories: product, product.import, and product.feed, product is considered the ancestor category and, if enabled, includes all messages logged to product.import and product.feed. The two descendant categories, if enabled, log only those messages assigned to them. Control the granularity of logging by enabling or disabling categories.

The root filter rule is always present. It defines the base level for all custom logs (corresponds to 'ALL' in the old configuration). Disable custom logging by setting the root level to OFF. If the filters contain just the root rule, all the custom logs are filtered by this rule. The defined level is the minimum level. If Info is set, then all the levels above Info are also generated (Warn, Error, Fatal).

**note:** To prevent excessive log size, maximum size of SOAP-related log messages in the custom debug log is 20,000 characters.

1.  Select **Administration** > **Operations** > **Custom Log Settings**.

2.  On the Custom Log Settings page, configure custom log setting filters:

    1.  Enter a log category name.

        **note:** Custom log category names can't include 'custom' as a prefix.

        For each category, define a special logging rule. The level that you set on this rule applies to the defined category and to the subcategories of that category. The category rule is considered first, and then the root rule. Only one rule can be defined per category. Disable a rule by unchecking the active checkbox of that rule. `All` is a reserved category name and can't be used in category rules.

    2.  Select the Log Level.

        If you set the log to OFF, no log messages for that category are logged, not even Fatal.

        You can't configure the Debug level on a Production instance.

    3.  Click **Add**.

        The log category appears in the list.

    4.  To enable a specific category, check the **Active** box.

    5.  To delete a log category, click the trash icon beside it.

        You can't delete the root log category.

3.  In the Custom Log Targets section:

    Only the messages that pass the filters are available for the log targets.

    1.  Enter an email address for Fatal messages.

        One email is sent per minute. Messages with a Fatal log level can be sent to email recipients. Enter a maximum of 1000 characters for all email addresses.

    2.  Select the log levels that are written to the files:

        Different log files are created for each log level. The exception is that when log messages are written using a developer-provided file prefix, all messages for that log category are written to the same file, regardless of the log level.

        Custom log files are constrained to 10 MB per day.

        The Debug log level can't be enabled on a Production instance.

    3.  View log messages in a log search web application, such as Log Center.

        There is a limit to number of log messages per realm per day that can be viewed in Log Center. A message appears when the limit is exceeded.

    4.  View log messages using the [Request Log Viewer](https://help.salesforce.com/s/articleView?id=cc.b2c_using_the_request_log.htm) in the [Storefront Toolkit](https://help.salesforce.com/s/articleView?id=cc.b2c_sftk_container.htm) on instances other than Development and Production.

4.  Click **Save** to save your changes.

#### Sample Configurations

The following examples show how log messaging is enabled and disabled using settings that take advantage of the log hierarchy:

<table><col /><col /><col /><col /><col /><thead><tr><th>Configuration</th><th>Active</th><th>Category</th><th>Level</th><th>Generated logs</th></tr></thead><tbody><tr><td>1</td><td><p>-</p> <p>yes</p></td><td><p>root</p> <p>category1</p></td><td><p>WARN</p> <p>INFO</p></td><td><p>category1: INFO, WARN, ERROR, FATAL</p> <p>category1.subcategory: INFO, WARN, ERROR, FATAL</p> <p>other custom categories: WARN, ERROR, FATAL</p></td></tr><tr><td>2</td><td><p>-</p> <p>no</p></td><td><p>root</p> <p>category1</p></td><td><p>WARN</p> <p>INFO</p></td><td><p>category1: WARN, ERROR, FATAL</p> <p>category1.subcategory: WARN, ERROR, FATAL</p> <p>other custom categories: WARN, ERROR, FATAL</p></td></tr><tr><td>3</td><td><p>-</p> <p>yes</p></td><td><p>root</p> <p>category1</p></td><td><p>OFF</p> <p>INFO</p></td><td><p>category1: INFO, WARN, ERROR, FATAL</p> <p>category1.subcategory: INFO, WARN, ERROR, FATAL</p> <p>other custom categories: no logs</p></td></tr><tr><td>4</td><td><p>-</p> <p>yes</p></td><td><p>root</p> <p>category1</p></td><td><p>WARN</p> <p>ERROR</p></td><td><p>category1: ERROR, FATAL</p> <p>category1.subcategory: ERROR, FATAL</p> <p>other custom categories: WARN, ERROR, FATAL</p></td></tr><tr><td>5</td><td><p>-</p> <p>yes</p></td><td><p>root</p> <p>category1</p></td><td><p>WARN</p> <p>OFF</p></td><td><p>category1: no logs</p> <p>category1.subcategory: no logs</p> <p>other custom categories: WARN, ERROR, FATAL</p></td></tr><tr><td>6</td><td><p>-</p> <p>yes</p> <p>yes</p></td><td><p>root</p> <p>category1</p> <p>category1.subcategory</p></td><td><p>WARN</p> <p>INFO</p> <p>DEBUG</p></td><td><p>category1: INFO, WARN, ERROR, FATAL</p> <p>category1.subcategory: DEBUG, INFO, WARN, ERROR, FATAL</p> <p>other custom categories: WARN, ERROR, FATAL</p></td></tr></tbody></table></sfdocstbl>

### Adding Logging to Your Scripts

Add logging to scripts.

The dw.system.Logger class includes the following methods:

- getRootLogger() : Log - A static method for retrieving a category logger.
- getLogger( String category ) : Log - A method for logging to this category logger. A category name must only consist of alpha numeric characters and a ".".

Use the dw.system.Log class to write to a specific log level and category. This class has the following methods:

- public void debug( String msg, Object... args );
- public boolean isDebugEnabled();
- ... similar methods for info, warn, and error
- public void fatal( ... );

For NDC support, the static method LogNDC getNDC() provides access to the NDC. The NDC property supports access to the nested diagnostic context.

The following methods are instance methods and not class methods:

- debug( String msg, Object... args ) : void
- isDebugEnabled() : boolean
- info( String msg, Object... args ) : void
- isInfoEnabled() : boolean
- warn( String msg, Object... args ) : void
- isWarnEnabled() : boolean
- error( String msg, Object... args ) : void
- isErrorEnabled() : boolean
- fatal( ... );

**note:** Fatal is always enabled.

The API class dw.system.LogNDC has the following methods.

| Method                        | Description                                                                                                                                                                                              |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| push( String message ) : void | Pushes new diagnostic context information for the current script execution.                                                                                                                              |
| peek() : String               | Looks at the last diagnostic context at the top of this NDC without�removing it. The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned. |
| pop() : String                | Call this method before leaving a diagnostic context. The returned value is the value that was pushed last. If no context is available, then the empty string "" is returned.                            |
| remove() : void               | Removes the diagnostic context for this script call.                                                                                                                                                     |

## Scripting: Maintaining State

A script can't maintain state from one execution to the next. After the execution of a script, all variables are erased from the system.

To maintain state across calls, use other mechanisms such as:

- The Session
- Persistent Business Objects
- Client-side cookies

### Using the Session

Use the `Session` class to access details about browser actions, such as:

- The current click stream if it's an HTTP or HTTPS session
- The session's custom attributes (stored for the lifetime of the session and aren’t cleared when the customer logs out)
- The current customer associated with the storefront session
- If the customer associated with the session is authenticated
- The session's custom privacy attributes (stored for the lifetime of the session and cleared when the customer logs out)
- The unique session identifier

### Using Persistent Business Objects

The SiteGenesis application handles most general ecommerce processing situations. However, as you develop your storefront, you might identify a particular processing need that isn't implemented. In that case, you might want to create a custom business object to handle the transaction. For example, you might want to offer customers the ability to add a monogram or personalized name to certain products such as tote bags or camera cases.

### Using Client-Side Cookies

Using the Salesforce B2C Commerce APIs, collect information about the cookies that are bound to a session, and track all associated cookies via an array.

## JavaScript Scope

If one script sets the prototype of an object, it provides shared access for all instances of the object. Each request gets it own copy of the object, so that changes to `Object X` don't influence `Object Y.` If user or request A changes the prototype of `Object X,` it doesn't influence `Object Y` of user or request B, even if they are of the same type.

### Prototype Objects

In JavaScript, every object includes an internal reference to another object. This object is known as a prototype object. This system allows inheritance in JavaScript.

#### Example

Consider the following function:

```
function Name(first,last){
    this.first = first;
    this.last = last;
}
```

Create a prototype object to which all instances of `name` have access. Create the prototype object anywhere in the code at any time; all instances of the object inherit.

```
Name.prototype.completename = function() {return this.first + this.last;}
```

So the following is true.

```
var me = new Name("Ken","Mack");
me.hasOwnProperty("first");        //true: first is a direct property of me
me.hasOwnProperty("completename"); // false: completename is an inherited property of me, so it accesses a shared copy of the completename function.
```

So if you create 10 objects of type `Name,` only one object of `completename` is created, because it's shared (inherited) for all instances of `Name.`

Where it gets confusing is when you create a property that you can write to, with shared across all _me_ instances. If you create a prototype property of `middlename,` for `Name`: `Name.prototype.middlename="middlename",` then do the following, because properties are read/write.

```
Name.prototype.middlename="middlename";
var me = new Name("Ken","Mack");
middlename = me.middlename;
var mywife = new Name("Laurie","Mack");
wifesmiddlename = mywife.middlename;
```

This example returns the string `middlename` for both instances, because they inherit that property and the value. While there are two instances of the `Name` object, `me` and `mywife,`, there’s only one instance of middlename, and it's set to "middlename". However, you can then set middlename for `me` as follows:

```
me.middlename="Joseph";
middlename = me.middlename;          // middlename now equals "Joseph"
wifesmiddlename = mywife.middlename; //middlename is still "middlename"
mywife.middlename = "Epps";
wifesmiddlename = mywife.middlename; // wife's middlename is now "Epps"
middlename = me.middlename;          // middlename is still "Joseph"
```

Now there are two instances of `Name`, `me` and `mywife,` and two instances of middlename, one set to "Joseph" and one set to "Epps".

The prototype object is a way for instances of an object to inherit "shared" objects. However, when the object that is being inherited is a writeable property and the property is written to, updated or changed, the object gets its own copy of that object, so as not to interfere with each object's version of the property.

## JavaScript Expressions in ISML

To simplify coding, we recommend that you use B2C Commerce JavaScript expressions within ISML templates.

### Examples

This example prints the product display name from the Pipeline Dictionary:

```
<isprint value="${pdict.Product.displayName}"/>
```

The product SKU is:

```
${pdict.Product.sku}
```

This example checks if there are any items or gift certificates in the cart (as entered by the customer):

```
<isif condition="${empty(pdict.CurrentForms.cart.items) && empty(pdict.CurrentForms.cart.giftcerts)}">
<!--- empty basket --->
<div id="infoBox">Your shopping cart is empty.</div>
<iselse>
```

### The Empty Operator

`Empty` has a particular significance when accessing an object, as follows:

<table><col /><col /><thead><tr><th>Operator</th><th>Purpose</th></tr></thead><tbody><tr><td><p>`empty()`</p></td><td><p>Returns true if the object is empty. Empty is defined as:</p> <ul><li><p>null</p></li><li><p>undefined</p></li><li><p>a string with zero length</p></li><li><p>an array with no elements</p></li><li><p>a collection with no elements</p></li></ul> <p>If the object is never declared, the JavaScript throws a `ReferenceError` so `Empty(object)` isn't `true`. </p></td></tr><tr><td><p>`isEmpty()`</p></td><td><p>Returns true if the collection is empty.</p></td></tr><tr><td><p>`isNotEmpty()`</p></td><td><p>If the object is empty, propagates an assertion using the specified message.</p> <p>Parameters:</p> <ul><li><p>arg - the object to check.</p></li><li><p>msg - the assertion message.</p></li></ul></td></tr></tbody></table></sfdocstbl>

## Shared Sessions for a Site with Multiple Domain Aliases

Your company has multiple brands and each brand has its own host name, but they’re all part of the same site. Let customers share baskets and other session information when they switch between brands via a redirect link.

This approach has several advantages, including:

- customers can shop several brands and only need one checkout
- registered customers don't have to log in again when switching brands
- create cross-brand campaigns and promotions related to qualifying products in the basket

To retain session information, the customer clicks a redirect link in the storefront to switch from brand A (host name) to brand B. When clicking a redirect link, the customer stays in the same Salesforce B2C Commerce site and the same session, and the basket is preserved.

**note:** This feature only works within one B2C Commerce site: you can't share sessions and baskets across B2C Commerce sites.

Use this API method to provide links between brands on storefront pages:

```
URL dw.web.URLUtils.sessionRedirect(String host, URL url)
```

This method generates redirect URLs to the target host names, and preserves the current storefront session. It doesn't work with direct storefront links, only via redirects. If the customer changes the URL, rather than clicking the redirect link, the session isn't preserved.

For example, if a customer goes from brand A to brand B through a direct link (or by typing the URL manually), B2C Commerce creates a session. Going back to brand A brings the customer to the old session. The cart isn't discarded. However, if the customer goes back to brand A through a redirect link, the customer session from brand B is used and the cart in brand A is discarded.

### Code Example

```
<a href="${URLUtils.sessionRedirect('www.a-brand.com',URLUtils.home())}">Brand A</a>
```

This example redirects to storefront homepage for hostname `www.a-brand.com`. Substitute the second parameter with any object of type URL, such as a direct link to a product within another brand.

<!-- document id=5ab86f6c9383a48bbc18633b098c2fa30bb2a0a4a5d065ad25c7b85f45db10b5 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/search-and-navigation/b2c-understanding-the-search-pipeline.md -->

# Understanding the Search Pipeline

When indexes are created, the storefront must include the controls that access a search pipeline that uses the indexes. Create your own pipeline for processing search queries or use the Search pipeline provided in the SiteGenesis application.

The Search pipeline allows configuration of recursive search, paging models, and error handling, among other options. Extend the Search pipeline to include any additional logic you want for query processing. The Search pipeline returns a results page using templates defined in UX Studio. Different templates are used to present product results, content results, and a no matches found page.

Sorting is the arranging of items in a sequence based on one or more characteristics. Sorting methods are site-wide and override other methods of presenting search results, because they are typically selected by the customer. Specify a specific sorting rule for keyword searches. Create sorting rules that are associated with specific categories. Create sorting rules that are used only for a call to the search pipeline in a content asset or slot. For example, if you wanted to let users search for items related to a specific promotion.

Salesforce B2C Commerce returns a result set, which is then sorted. If no sorting rule is specified in the call to the Search pipeline, then results are sorted based on the sorting rule used for the keyword search, which is associated with the root category of the navigation catalog for the site. If no sorting rules are configured, then results are returned in the order of most to least frequent use of the query term in the indexed fields of the product or content.

## SiteGenesis Pipeline Example

The storefront includes a keyword search box and category navigation links. When a customer clicks a category link, a query is generated against the category and submitted to the Search pipeline. When a customer enters a search term, this also generates a query that is submitted to the Search pipeline.

The Search pipeline processes the query and accesses the index files and ranking criteria. The Search pipeline returns the results to the storefront.

![Diagram of the SiteGenesis Search pipeline flow processing keyword and category queries against search indexes](https://developer.salesforce.com/media/b2c-commerce/b2c_search_slide_10.gif)

If the Search pipeline finds a merchant-defined redirect, it returns the page specified in the redirect definition. If no redirect is found and search results are found, it returns the search results. By default, in the SiteGenesis application, if both products and contents are found, the product search results are shown, with a link to the content search results. The following graphic shows how content appears in the SiteGenesis application search results. See this link by searching on "customer support" in SiteGenesis.

![SiteGenesis search results page showing a content link alongside product search results](https://developer.salesforce.com/media/b2c-commerce/b2c_search_and_navigation_sf_content_link.gif)

In the SiteGenesis application, if no results are found, the `nohits.isml` template checks for a spelling suggestion. If one exists, it shows a "Did you mean?" message. If there are no spelling suggestions, then it shows a message indicating that there are no results. Change the spelling suggestion settings so that the message for no results is never shown, or so that only reasonable spelling suggestions are shown.

Configurable querying features include:

- Search redirects: the merchant can redirect searches for a specific term to a landing page or category page, rather than performing a product search. For example, if a customer searches for "customer service" they can be directed to a customer service page or if they search for "jobs" they can be directed to a career opportunities page.
- Search refinements: the merchant can configure a refinement bar that lets customers refine results based on an attribute. For example, they might want to only see items in red or with a specific size.
- Orderable Products Only: this setting excludes unorderable products (having an inventory record with `ATS=0`) from search results.
- Availability Low Ranking Threshold: the percentage of availability from which products are to be ranked lower and pushed to the end of search results.

<!-- document id=394ba69b5d19ebe2a1274d6f14e706d147fce5c272879755f416b505876fd07f url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/ucp/ucp-index.md -->

# Universal Commerce Protocol (UCP) Integration

Enable Universal Commerce Protocol (UCP) for your site so platforms that support UCP can discover and sell your products, while you remain Merchant of Record. Google is the first live platform at general availability (GA). The Salesforce implementation is platform-agnostic—one business profile, checkout lifecycle, and post-purchase webhook sync for any compatible platform.

## UCP Overview

The Universal Commerce Protocol (UCP) is a common language for platforms, agents, and businesses to conduct agent commerce across industries. Within UCP there are two main players:

1. The **platform**: any entity that consumes capabilities—an app, an AI agent, a procurement system, or another business
2. The **business**: any entity that exposes capabilities—this is you (the merchant) powered by Salesforce Commerce Cloud

The protocol defines a common language and functional primitives so these two parties can interoperate securely and reliably across commercial verticals. A business declares what it offers and how it operates; any compatible platform can discover and use that without a bespoke, per-platform implementation. For example, enabling UCP for your site lets buyers on platforms such as Google Gemini programmatically discover your products and complete checkout without leaving the platform.

Platforms find your business by fetching the **business profile** Salesforce publishes from your Business Manager UCP settings—they don't start at checkout. Configure that profile in [Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md). Each platform can also have its own product-discovery setup; for Google, see [Enabling Google as a Platform](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md).

### Business Benefits

- **New sales channel:** Reach customers where they're already shopping—in conversational AI, search, ads, and other surfaces
- **Integrated experience:** Customers complete purchases without leaving the platform (for example, Gemini), boosting conversion
- **Merchant control:** Merchants remain the Merchant of Record with full control over pricing, inventory, and fulfillment
- **Dynamic pricing:** Real-time tax and shipping calculations make pricing accurate
- **Native integration:** Uses existing B2C Commerce infrastructure and business logic

## Audience

This guide is for developers and technical architects who are implementing the UCP integration with Salesforce B2C Commerce.

## Guide Contents

- [Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md) - Business Manager setup, business profile, Order Management System (OMS), Payment Provider Support
- [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md) - SLAS private client and `dev.ucp.shopping.checkout:manage` scope for Checkout Session APIs
- [Technical Audit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-technical-audit.md) - Decide what checkout logic you must move or bridge onto UCP hooks
- [Implementation Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md) - Hook architecture, extensibility, and code examples
- [Transaction Management](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-transaction-management.md) - Transaction boundaries for Checkout Session hooks
- [Enabling Google as a Platform](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md) - Google onboarding, Merchant Center product discovery, test users, and Google UCP support
- [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md) - How shipment, cancellation, and return updates reach the agent platform as signed full-order snapshots

## Implementation Workflow

Follow these phases to enable UCP for your organization:

### Phase 1: Prerequisites and Planning

Review these prerequisites and restrictions:

- Generally available (GA) in B2C Commerce 26.9 and later
- UCP is currently limited to en-US sites only
- Salesforce OMS is optional—or connect a third-party OMS via [Connect a Third-Party OMS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/commerce-apps/connect-third-party-oms.md) if you want lifecycle events on the platform. See [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md) for how those events become UCP snapshots.
- Salesforce Payments (SFP) SKU provisioned—or a third-party payments implementation
- If using SFP—Adyen or Stripe via Salesforce Payments, with Google Pay enabled in the gateway
- Native Salesforce Payments advertises Google Pay; Google as a platform still expects Google Pay today

### Phase 2: Technical Audit

Complete the [Technical Audit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-technical-audit.md) to:

- Confirm which Basket/Order hooks already run in the UCP flow
- Remap Shopper Baskets, Shopper Orders, SFRA controller, or other resource-specific logic onto UCP hooks
- Select a payment path (Salesforce Payments vs DIY) and note headless side effects (email, OMS, Continue URL)

### Phase 3: Implementation

Review [Implementation Considerations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-implementation-considerations.md) and:

- Implement custom hooks if needed
- Add address verification or custom validation
- Configure third-party Adyen webhooks if you share an Adyen merchant account with Salesforce Payments
- Test hook execution flow

### Phase 4: Configuration

Complete [Configuration and Discovery](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-configuration.md):

- Configure Business Manager UCP settings
- Set up chosen Payment Provider
- Configure OMS event sync. See [Order Post-Processing Events](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-order-post-processing-events.md)
- GET `/.well-known/ucp` and confirm the published business profile

Complete [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md):

- Create a SLAS private client with the `dev.ucp.shopping.checkout:manage` scope

Complete [Enabling Google as a Platform](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md) if you are transacting with Google:

- Join Google's UCP waitlist (do this first—even before Salesforce UCP or the Merchant Center feed is finished)
- Configure Google Merchant Center product feeds and enable the `native_commerce` attribute on products
- After Google accepts you, complete [End-to-End Testing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md#end-to-end-testing) (checkout API secrets, tester allowlisting, live payments, sandbox → staging → production)

### Phase 5: Validation

- Confirm the business profile at `/.well-known/ucp` (version, capabilities, payment handlers, signing keys)
- Request a SLAS guest token with `dev.ucp.shopping.checkout:manage` and test the Checkout Session APIs using Postman or similar API testing tools. Headless testing can use test payments. See [Checkout Session Authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-authentication.md).
- After Google allowlists your testers, walk through discovery and checkout in Gemini with a personal `@gmail.com` account. Start on sandbox, then staging, then production—Google must retarget their toggle and allow lists between environments. Google supports live mode payments only for that Buy-button flow. See [End-to-End Testing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/ucp-google-gmc-configuration.md#end-to-end-testing).
- Verify order creation and fulfillment events
- Confirm pricing, tax, and shipping calculations

<!-- document id=d364881a96c53c5ad873e20a4e74c4068d23c087ac73a83f40d235d6b5c24254 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-einstein-b2c-reco-api-ref.md -->

<!--# D2C Commerce Einstein Product Recommendations API

Calls to the Product Recommendation API deliver Einstein recommendations. The API is accessed using a wire adapter to provide data to a Lightning web component. In this case, the Product Recommendation API returns a set of products to populate the Einstein Recommendations component.-->

## ProductRecommendationsAdapter Wire Adapter

The ProductRecommendationsAdapter returns Einstein product recommendations. Implement this wire adapter by importing it from the `einsteinAPI` module within the commerce namespace (`commerce/einsteinAPI`) and then declaring its required parameters with the `@wire` decorator.

Parameters

- Recommender Name—The name of the recommender. This parameter determines what kind of product results you see. It must be one of the recommender names listed in the Recommender Names and Anchors table.
- Anchor Type—The anchor type is either PRODUCT, CATEGORY, or NO_CONTEXT. A product recommendation with an anchor type PRODUCT bases its results on the product IDs that you pass.
- Anchor Value—If the anchor type is PRODUCT, the value is a list of 18-character product IDs. If the anchor type is CATEGORY, the value is a list of 18-character category IDs. If the anchor type is NO_CONTEXT, there’s no anchor value; it can be null or undefined.

Result

- products—A list of product details.
- recoUUID—A string representing the unique ID for the recommendation response. Use this value when you trigger the viewReco and clickReco activities.

Constants

- ANCHOR_TYPE.PRODUCT
- ANCHOR_TYPE.CATEGORY
- ANCHOR_TYPE.NO_CONTEXT

## Recommender Names and Anchors

Each recommender name requires a specific anchor type and anchor value. For example, if you use the recommender name “similar-products,” the anchor type must be PRODUCT, and the anchor value must be a list of product IDs. This table shows the anchor type and value associated with each recommender name.

| Anchor Type | Anchor Value                                                                                                                        | Recommender Names                                                                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| NO_CONTEXT  | Any value that evaluates to false. For example: null or undefined.                                                                  | <ul><li>personalized-for-shopper</li><li>recently-viewed</li><li>top-selling</li></ul>                                                            |
| PRODUCT     | A list of one or more 18-character product IDs. For example: `['01t000000000000001', '01t000000000000002', '01t000000000000003']`.  | <ul><li>complementary-products</li><li>customers-who-bought-also-bought</li><li>recently-viewed</li><li>similar-products</li><li>upsell</li></ul> |
| CATEGORY    | A list of one or more 18-character category IDs. For example: `['0ZG000000000000001', '0ZG000000000000002', '0ZG000000000000003']`. | <ul><li>most-viewed-by-category</li><li>recently-viewed</li><li>top-selling-by-category</li></ul>                                                 |

**See Also**

- [Einstein Recommendations Component (LWR) for B2C Stores](https://help.salesforce.com/s/articleView?id=commerce.comm_einstein_component.htm)
- [Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_einstein_apis.htm)
- [Prepare Commerce Einstein to Use Custom Components](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_prepare_einstein_custom_comps.htm)
- [Create a Custom Recommendations Component for B2C Stores Using Commerce Einstein APIs](https://developer.salesforce.com/docs/atlas.en-us.b2b_b2c_comm_dev.meta/b2b_b2c_comm_dev/b2b_b2c_comm_create_b2c_cust_ein_reco_comp.htm)

<!-- document id=1daddf36e3fea0b3a98f4726f0dfa30c0a4ba1b1ea38da31b07b34300b05ba21 url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mrt-env-var-troubleshoot.md -->

## Troubleshoot Environment Variables

Find suggested solutions for common errors while working with environment variables.

### PUBLIC\_\_ variable not available in client code.

Your client-side code can't access a variable that you prefixed with PUBLIC\_\_.

**Cause:** A single underscore or missing prefix means the variable is treated as server-only.

**Suggested Solution:** Verify the variable name starts with PUBLIC\_\_ (two underscores).

### Config path error on startup.

Your app fails to start and displays a config path error.

**Cause:** The path in your PUBLIC\_\_ variable name isn't found in config.server.ts.

**Suggested Solution:** The path in your PUBLIC\_\_ variable name must exist in config.server.ts. Add the field and its default value to the config before setting the environment variable.

### Environment Variable Isn’t Set

Your code throws an `Error` stating that a variable is missing.

**Cause:** The environment variable that the code calls isn’t set.

**Suggested Solution:** Call the [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update) API endpoint to set the applicable environment variable.

### Incorrect Environment Variable Name

Your code logs an error message stating that the environment variable wasn’t found.

**Cause:** The code couldn’t find the environment variable because of a typo or incorrect variable name.

**Suggested Solution:** Confirm that you spelled the environment variable name correctly and that you’re using the right name. To see all set variables, call the [projects_target_env_var_list](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_list) API endpoint.

### Unsupported Environment Variable Name

Your API call to set an environment variable fails.

**Cause:** The environment variable name doesn’t comply with the [constraints](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md#constraints). For example, the variable value exceeds 32 KB.

**Suggested Solution:** Confirm that your environment variable complies with the [constraints](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-mrt-environment-vars.md#constraints).

### Invalid API Key Format

Authentication errors occur when you execute code that uses an API key.

**Cause:** The API key that you used when you set the environment variable isn’t in the expected format or is missing.

**Suggested Solution:** Confirm that the API key stored by an environment variable is correct. If needed, call the [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update) API endpoint to correct the API key.

### Invalid URL for an API Endpoint

A `fetch` request fails with a network error.

**Cause:** A URL for an API endpoint in your code is missing or invalid. For example, the URL for a content management system (CMS) endpoint is incorrect.

**Suggested Solution:** Confirm that any URLs for API endpoints in your code are correct.

### Variable Has No Effect After Being Set

**Cause:** Environment variables load at startup. A running server doesn't pick up changes automatically.

**Suggested Solution:** Restart your dev server.

### `PUBLIC__` Variable Not Available in Client Code

**Cause:** A single underscore or missing prefix marks the variable as server-only.

**Suggested Solution:** Verify that the variable name starts with `PUBLIC__` (two underscores).

### Config Path Error on Startup

**Cause:** The path in your `PUBLIC__` variable name isn't found in `config.server.ts`.

**Suggested Solution:** Add the path and its default value to `config.server.ts` before setting the environment variable.

### Variable Value Is the Wrong Type

**Cause:** The variable value isn't formatted correctly for its type. The app parses values automatically.

**Suggested Solution:** For booleans, use the string true or false. For arrays and objects, use valid JSON. Confirm the value is formatted correctly in your .env file or in Runtime Admin.

### API Call to Update Variables Fails

**Cause:** This error can be caused by insufficient permissions, an invalid API key, or a reserved prefix.

**Suggested Solution:** Confirm that you have the developer or admin role on the project. Verify that your MRT API key is valid. Check that the variable name doesn't use a reserved prefix.

### Variable Set in Runtime Admin Is Not Available After Deployment

**Cause:** You likely didn't deploy the bundle after setting the variable.

**Suggested Solution:** Make sure that you deployed your bundle after setting the variable. Existing running instances use the variables that were active at deploy time.

<!-- document id=9f225f6d08d74c2975287c2becf21580a368344d896d9bb5ff174e98a3898c9c url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-checkout-update-information.md -->

# Update Checkout Information

Update contact details, delivery information, or delivery method.

**Note:** You can't update custom fields independently.

![Diagram of the update checkout information flow in B2B Commerce showing how checkout data is modified](https://developer.salesforce.com/media/d2c-commerce/commerce-update-checkout.png '{"class": "image-lg", "title": "Update Checkout"}')

**Endpoint:** PATCH [`/commerce/webstores/{webstoreId}/checkouts/{activeOrCheckoutId}`](https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/connect_resources_commerce_webstore_checkouts.htm)

**Request parameters:**

- `deliveryMethodId`
- `desiredDeliveryDate`
- `shippingInstructions`
- `deliveryAddress`
- `contactInfo`
- `customFields`

## Supported updates

##### Contact Information

- **Field:** `contactInfo`
- **Triggers:** No calculators

##### Delivery Information

- **Fields:** `deliveryAddress`, `desiredDeliveryDate`, and `shippingInstructions`
- **Triggers:** Shipping and tax calculators

**Note:** The shipping calculator generates shipping methods. By default, the system selects the lowest-cost shipping method.

##### Delivery Method

- **Field:** `deliveryMethodId`
- **Triggers:** Tax calculator

**Response codes:**

- 200 OK – Update complete
- 202 Accepted – Processing in progress, poll GET endpoint
- 409 Conflict – Previous operation still in progress

<!-- document id=046279aee1688e4d3a232b27d7753ec1e6cb93779c465f94afea077c560dd555 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/upgrade-node-version.md -->

# Upgrade Node Version

**important:** You _must_ upgrade to Node.js 20 or higher, or you will _not_ be able to deploy your site. For more information, see the table below.

Customers control which version of Node.js is used to run a Managed Runtime environment. Every two years, customers must upgrade Node.js versions, as support for older versions is removed to maintain security.

## Supported Node Versions

**Support date definitions**

- **End of Life**: Customers will no longer be able to deploy bundles using this version of Node.js after this date.
- **Deprecation**: Customers will start seeing a warning that a Node.js version upgrade will be required in the future for uninterrupted deployments.
- **Availability**: When this version of Node.js was first supported.

**The current recommended version is Node.js 24.**

| Version | Availability date  | Deprecation date   | End of Life date   |
| ------- | ------------------ | ------------------ | ------------------ |
| 24.x    | March 12, 2026     |                    |                    |
| 22.x    | January 31, 2025   | October 1, 2026    | June 1, 2027       |
| 20.x    | January 19, 2024   | August 21, 2025    | April 30, 2026     |
| 18.x    | June 21, 2023      | January 31, 2025   | September 1, 2025  |
| 16.x    | March 3, 2023      | June 21, 2023      | September 13, 2023 |
| 14.x    | September 18, 2021 | April 30, 2023     | September 13, 2023 |
| 12.x    | September 18, 2021 | September 20, 2022 | November 14, 2022  |

## Upgrade Steps

To update an environment to the latest supported version of Node.js:

- Edit your project’s `package.json` file.
- Upgrade your project to [the latest minor version of PWA Kit 2.x or 3.x](https://github.com/SalesforceCommerceCloud/pwa-kit/releases).
- Update `ssrParameters.ssrFunctionNodeVersion` to the latest supported version of Node.js. _This attribute sets the version of Node.js used by Managed Runtime environments._
- Update your local development environments, continuous integration servers, and anything that builds bundles to use the latest supported version of Node.js. _Reinstall all of your project's packages using the new Node.js version._
- Test that your project works as expected in a local development environment.
- Push a new bundle and deploy it to a non-production environment.
- Confirm that the environment works as expected.
- Deploy the new bundle to your production environment.

## Opt Out of Email Notifications

By default, project teams receive automated email notifications when their environments are using deprecated or end-of-life Node.js versions. These notifications help ensure timely upgrades and avoid deployment disruptions.

To opt out of these notifications:

1. Log into [Runtime Admin](https://runtime.commercecloud.com) and then click **Account Settings**.
2. In the **Email Notifications** section, deselect the notification you want to opt out of.

**note:** We recommend keeping these notifications enabled to ensure your team stays informed about required Node.js upgrades. Opting out may result in unexpected deployment failures when Node.js versions reach end of life.

<!-- document id=2a1bbebfee8871cefd18864d641b8bb6a4c51ca35070122018d1b22aed872fe0 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/upgrade-shopper-baskets-to-v2.md -->

# Upgrade to Shopper Baskets V2

Upgrade to the Shopper Baskets V2 API for basket imports for all customized template files to prevent cache inconsistencies and keep your basket data synchronized for shoppers. Shopper Baskets V2 is now the default API for imports. Shopper Baskets V1 remains the default API for all basket exports.

To use the Shopper Baskets V2 aliased hooks, make sure that your B2C Commerce instance supports the Shopper Baskets V2 API, and then update your imports from @salesforce/commerce-sdk-react.

Example:

```
// Before:
import {useShopperBasketsMutation} from '@salesforce/commerce-sdk-react'
// After:
import {useShopperBasketsV2Mutation as useShopperBasketsMutation} from '@salesforce/commerce-sdk-react'
```

## Commerce-sdk-react Package

The Shopper Basket V1 API remains the default for all basket exports. If you want to continue using the Shopper Basket V1 API for imports, you can import useShopperBasketsMutation, useBasket, and so on as usual. These imports still resolve to V1. To use the Shopper Basket V2 API, you can opt in by importing the V2 suffixed names.

## Default Retail React App Template Files

All default Retail React App template files now import V2 hooks. If your B2C Commerce instance supports the Shopper Baskets V2 API and you pull in a new template version, you’ll automatically use V2 baskets.

## Customized Retail React App Template Files

If you’ve overridden a template file, the template will use the V1 basket for imports. This setup can cause issues. Default templates will use V2 hooks backed by the shopperBaskets V2 client and key shopperBaskets V2. Customized templates will use V1 hooks backed by the shopperBaskets client and cache key shopperBaskets.

V1 and V2 use separate React Query cache keys. For example, a mutation done through V2, such as adding an item to the basket, won’t invalidate V1 query caches. This can lead to stale basket data in the user interface.

See the impacted template files.

<table style="width: 100%; border-collapse: collapse; font-family: Arial, sans-serif; color: #4f4f4f;">
  <thead>
    <tr style="background-color: #f4f4f4; font-weight: bold;">
      <th style="border: 1px solid #ddd; padding: 10px 15px; text-align: left;"><b>Area</b></th>
      <th style="border: 1px solid #ddd; padding: 10px 15px; text-align: left;"><b>Template Files Changed</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        Cart
      </td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        <ul>
        <li>pages/cart/index.jsx</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">Checkout</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        <ul>
        <li>pages/checkout/index.jsx</li>
        <li>partials/payment.jsx</li>
        <li>partials/contact-info.jsx</li>
        <li>partials/shipping-address.jsx</li> 
        <li>partials/shipping-methods.jsx</li>
        <li>partials/shipping-method-options.jsx</li> 
        <li>partials/sf-payments-sheet.jsx</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">Product</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        <ul>
        <li>pages/product-detail/index.jsx</li>
        <li>components/product-view/index.jsx</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        Login/Auth
      </td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        <ul>
        <li>pages/login/index.jsx</li>
        <li>pages/social-login-redirect/index.jsx</li>
        <li>hooks/use-auth-modal.js</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">Shared Hooks</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        <ul>
        <li>hooks/use-pickup-shipment.js</li>
        <li>hooks/use-shipment-operations.js</li>
        <li>hooks/use-item-shipment-management.js</li>
        <li>hooks/use-cleanup-temporary-baskets.js</li> 
        <li>hooks/use-multiship.js</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">Components</td>
      <td style="border: 1px solid #ddd; padding: 10px 15px;">
        <ul>
        <li>components/_app/index.jsx</li>
        <li>components/promo-code/index.jsx</li>
        <li>components/bonus-product-view-modal/index.jsx</li>
        <li>components/sf-payments-express-buttons/index.jsx</li> 
        <li>pages/account/wishlist/partials/wishlist-primary-action.jsx</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

**important:** To resolve issues, you must upgrade all basket-related files together. You can’t partially adopt V2.

If you’ve customized any template files, update the overrides to use V2 imports.

Example:

```
useShopperBasketsMutation → useShopperBasketsV2Mutation as useShopperBasketsMutation
useShippingMethodsForShipment → useShippingMethodsForShipmentV2 as useShippingMethodsForShipment
useShopperBasketsMutationHelper → useShopperBasketsV2MutationHelper as useShopperBasketsMutationHelper
```

<!-- document id=018aaf173e06db92b519772fdf1734d26e4a32aa01baac71cfd5511e051f29c8 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/upgrade-to-v2.md -->

# Upgrade to v2

Upgrade a project that was generated before v2 of PWA Kit to take advantage of the framework and tooling improvements made in v2.

**note:** Upgrading doesn’t automatically add any new storefront features from the Retail React App template, but you can manually add them using the latest Retail React App code as a reference.

## What’s New

We’ve added lots of new features to PWA Kit v2, including:

🥳 **TypeScript support**. The build tools now support TypeScript by default—without having to update the configuration files for Babel or Webpack.

🧰 **An** **updated development server** that supports hot reloading on the server side and makes it possible to support hot reloading on the client side in a future release.

🤓 **An all-new command-line tool** called `pwa-kit-dev` that bundles our recommended development tools like Webpack, Babel, and Jest to support zero-config project templates.

🖌️ **Experimental support for non-React apps** for those users interested in using Managed Runtime to host other Express-based apps (not just the Retail React App).

## Upgrade Process

**note:** If you haven’t generated a PWA Kit project yet, see the [Quick Start](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/quick-start.html) guide to generate a new project using v2.

We made the upgrade process from v1.5 to v2 as easy as possible—with changes required to only a small number of existing project files.

If you’re upgrading from v1.4 (or earlier), the process is the same as upgrading from v1.5, but with one extra step. Update all `import` statements involving `pwa-kit-react-sdk` so that the import path doesn’t include the `dist/` folder anymore.

```javascript
// Import with old path
- import {getAssetUrl} from 'pwa-kit-react-sdk/dist/ssr/universal/utils'

// Import with new path
+ import {getAssetUrl} from 'pwa-kit-react-sdk/ssr/universal/utils'
```

Read on to complete the remaining upgrade tasks (for both v1.5 and v1.4 users).

## Changes to package.json

To start the upgrade process, open `package.json` from the root directory of your project.

Add and install three new `pwa-kit-*` packages:

```json
"pwa-kit-dev": "2.0.0",
"pwa-kit-react-sdk": "2.0.0",
"pwa-kit-runtime": "2.0.0",
```

Remove the following dependencies. The new `pwa-kit-dev` tool now takes care of these dependencies for you. (If the version numbers don’t exactly match the ones you have in your project, remove them anyway.)

```json
"@babel/cli": "^7.4.4",
"@babel/core": "^7.4.5",
"@babel/parser": "^7.5.5",
"@babel/plugin-proposal-object-rest-spread": "^7.4.4",
"@babel/plugin-transform-async-to-generator": "^7.7.0",
"@babel/plugin-transform-modules-commonjs": "^7.4.4",
"@babel/plugin-transform-object-assign": "^7.2.0",
"@babel/plugin-transform-runtime": "^7.6.2",
"@babel/preset-env": "^7.4.5",
"@babel/preset-react": "^7.0.0",
"@babel/register": "^7.4.4",
"@babel/runtime": "^7.7.2",
"@babel/runtime-corejs2": "^7.4.5",
"@babel/traverse": "^7.5.5",
"babel-eslint": "^10.1.0",
"babel-jest": "^26.6.3",
"babel-loader": "^8.0.6",
"babel-plugin-dynamic-import-node-babel-7": "^2.0.7",
"babel-plugin-formatjs": "^10.2.3",
"@loadable/babel-plugin": "^5.13.2",
"@loadable/server": "^5.15.0",
"@loadable/webpack-plugin": "5.15.0",
"eslint": "7.31.0",
"eslint-config-prettier": "4.0.0",
"eslint-import-resolver-webpack": "0.10.0",
"eslint-plugin-header": "^3.1.1",
"eslint-plugin-import": "2.23.4",
"eslint-plugin-jsx-a11y": "6.4.1",
"eslint-plugin-prettier": "3.0.1",
"eslint-plugin-react": "7.24.0",
"jest": "^26.6.3",
"jest-cli": "^26.6.3",
"webpack": "^5.39.1",
"webpack-cli": "^4.7.2"
```

Convert these NPM scripts to use the new `pwa-kit-dev`:

```json
"scripts": {
    ...
    "format": "pwa-kit-dev format '\"**/*.{js,jsx}\"'",
    "lint": "pwa-kit-dev lint '\"**/*.{js,jsx}\"'",
    "prod:build": "npm run build-translations && pwa-kit-dev build",
    "push": "npm run prod:build && pwa-kit-dev push",
    "save-credentials": "pwa-kit-dev save-credentials",
    "start": "cross-env NODE_ICU_DATA=node_modules/full-icu pwa-kit-dev start",
    "test": "pwa-kit-dev test",
    ...
},
```

## Changes to babel.config.js

Open `babel.config.js` from the root directory of your project and **replace the entire file** with this one line:

```javascript
module.exports = require('pwa-kit-dev/configs/babel/babel-config')
```

If you have made any customizations to your Babel configuration, add them below the call to the `require()` function.

## Changes to webpack.config.js

If you haven’t customized the `webpack.config.js` file from the root directory of your project, delete it. A default configuration file is loaded automatically for you.

If you do have customizations, you must add them after calling the `require()` function first to get the base configuration:

```javascript
const config = require('pwa-kit-dev/configs/webpack/config')

// Add your customizations here
const clientConfig = config.find((cnf) => cnf.name === 'client')

module.exports = config
```

## Changes to ssr.js

In v2, the method being used to create the Express server has been changed. The `createApp` method has been deprecated and replaced with a method called `getRuntime`.

The `getRuntime` method returns a runtime object. You can use the `createHandler` method to create Managed Runtime compatible lambda handlers. The second argument is a callback function that gives you access to the Express app, allowing you to customize the Express app. For example you can use the callback function to implement custom endpoints.

```javascript
- import {createApp} from 'pwa-kit-react-sdk/ssr/server/express'
+ import {getRuntime} from 'pwa-kit-runtime/ssr/server/express'

const options = {
    // For example, if you have a different build directory, make sure this buildDir is correct
    buildDir: path.resolve(process.cwd(), 'my-build-dir'),
    ...
}

- const app = createApp(options)
+ const runtime = getRuntime()

const {handler} = runtime.createHandler(options, (app) => {
    ...
    // For example, if you have added a custom endpoint, you can bring its implementation to here
    app.get('/custom-endpoint', () => {})

    app.get('*', runtime.render)
})
// SSR requires that we export a single handler function called 'get', that
// supports AWS use of the server that we created above.
export const get = handler
```

In v2, `body-parser` library is removed from the express app. If you have custom endpoints that requires `req.body` parsed and populated, install the `body-parser` library by running `npm install body-parser` and include the body parser library in ssr.js:

```javascript
import bodyParser from 'body-parser'

const {handler} = runtime.createHandler(options, (app) => {
  // add this before the custom endpoints which access `req.body`
  app.use(bodyParser.json())
})
```

## Import getConfig Differently

Whenever `getConfig` is used, import it from the new `pwa-kit-runtime` package:

```javascript
- import {getConfig} from 'pwa-kit-react-sdk/ssr/universal/utils' // Old package
+ import {getConfig} from 'pwa-kit-runtime/utils/ssr-config' // New package
```

## Changes to worker/main.js

Open `worker/main.js` and add this new route:

```javascript
// Place your Workbox route configurations here, eg:
// workbox.routing.registerRoute(...)

// Never cache dev-server internals.
workbox.routing.registerRoute(
  /^http:\/\/localhost:3000\/__mrt/,
  new workbox.strategies.NetworkOnly()
)
```

## Proxy Settings

In v2, the proxy settings for each Managed Runtime environment must be defined explicitly. In v1, there was a fallback mechanism that allowed a Managed Runtime environment to use the same proxy settings as the local development environment. The fallback mechanism is not supported for v2 projects due to performance and maintenance issues.

To learn how to configure proxy settings for Managed Runtime environments using the Runtime Admin tool or the Managed Runtime API, see [Proxy Requests](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/proxying-requests.md).

You can also take advantage of the new [environment-specific configurations](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configuration-options.md#environment-specific-configurations) feature in v2 to configure proxy settings for your Managed Runtime environments.

## Node 14 Support

Before v2, PWA Kit supported Node 12.x. With v2, you must ensure that your code works with Node 16+.

## Testing Your Changes

To test whether your changes have been made successfully, run the following commands:

1. `npm start` to verify that the app is able to run locally.
2. `npm run build` for verifying that the build process is successful.
3. `npm run push` (and deploy via Runtime Admin) to verify that deploying a bundle is successful.

<!-- document id=58785f6c578d05221b13b36af5dc2ee74fef99f7aef5763ee16167da6c71cda1 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/upgrade-to-v2-3.md -->

# Upgrade to v2.3

**important:** If you are upgrading a PWA Kit project that was created before the availability of v2, follow the instructions in the [Upgrade to v2](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/upgrade-to-v2.md) guide first.

To take advantage of the opt-in features available in v2.3, specifically the `react-query` integration, you must make a few changes to `_app-config/index.js`, `_app/index.js` and `package.json` in your PWA Kit project.

## Changes to \_app-config/index.js

Open `_app-config/index.js` and make the following changes.

Import the higher-order components required to enable `react-query` and retain `getProps` support.

```javascript
- import {withLegacyGetProps} from 'pwa-kit-react-sdk/ssr/universal/components/with-legacy-get-props'
+ import {withReactQuery} from 'pwa-kit-react-sdk/ssr/universal/components/with-react-query'
```

Add the `options` object with the recommended React Query configuration.

```javascript
// Determine whether the code is running server-side or client-side based on the presence of the window object. Set isServerSide to true if running server-side or false if running client-side.
const isServerSide = typeof window === 'undefined'

// Recommended settings for PWA-Kit usages.
// NOTE: They will be applied server-side and client-side.
const options = {
  queryClientConfig: {
    defaultOptions: {
      queries: {
        retry: false,
        staleTime: 2 * 1000,

        // If isServerSide is true, disable retries on mount.
        ...(isServerSide ? {retryOnMount: false} : {})
      },
      mutations: {
        retry: false
      }
    }
  }
}
```

Update the exported `AppConfig` component definition.

```javascript
- export default AppConfig
+ export default withReactQuery(withLegacyGetProps(AppConfig), options)
```

## Changes to \_app/index.js

Open `_app/index.js` and make the following changes.

Declare a variable named `DEFAULT_LOCALE` to store the default locale for displaying messages in your application. For a newly generated project, the default messages are written in English for the United States locale. If you haven’t rewritten the default messages, then `en-US` is the right value for `DEFAULT_LOCALE`. Otherwise, set `DEFAULT_LOCALE` to a different value, such as `fr-fr` or `ja-jp`.

```javascript
+ const DEFAULT_LOCALE = 'en-US'
```

Assign `DEFAULT_LOCALE` as the default value for the `targetLocale` property.

```javascript
- const {children, targetLocale, messages, categories: allCategories = {}} = props
+ const {
+     children,
+     targetLocale = DEFAULT_LOCALE,
+     messages = {},
+     categories: allCategories = {}
+ } = props
```

Replace `defaultLocale` with the new static value.

```javascript
- defaultLocale="en-US"
+ defaultLocale={DEFAULT_LOCALE}
```

**note:** If enabled, `useQuery` and `getProps` functions are run in parallel. A side effect of running in parallel is that conditionally rendering a component based on the return value of `getProps` can cause some `useQuery` hooks not to run on the server. For simplicity sake, we recommend that you choose either `getProps` or `useQuery` for data fetching.

## Changes to package.json

Add `react-query` to your `devDependencies`.

```javascript
+ "@tanstack/react-query": "^4.0.10",
```

## Testing Your Changes

To test whether your changes have been made successfully, run the following commands:

1. `npm install` to install the required `react-query` dependency.
2. `npm start` to verify that the app is able to run locally.
3. `npm run build` for verifying that the build process is successful.
4. `npm run push` (and deploy via Runtime Admin) to verify that deploying a bundle is successful.

## Further Reading

To learn more about React Query and how to use it, see the [React Query documentation](https://tanstack.com/query/latest).

<!-- document id=0c0f54c8856fedef5204b66a886798c8b3d452e8bb06ce338c6a11e2d061eed4 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/upgrade-to-v3.md -->

# Upgrade to v3

As of v3, it's now possible to consume `@salesforce/retail-react-app` updates by adding it as an npm dependency and enabling [template extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.html) in your project.

This guide covers how to update a PWA Kit project from v2.7.x to v3.

**note:** After completing the steps in this upgrade guide, we recommend that you test your site to confirm that it works as expected.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## What’s New in v3

We’ve added lots of new features to PWA Kit v3, including:

⚛️ **Required**:

- `getProps` breaking change
- Major library updates, including support for **React 18**, **Node 22**, **Chakra 2**, and more

🔨 **Optional: Template extensibility** &mdash; Greatly reduce your project's code footprint and reduce development toil, cost of ownership, and future upgrade headaches. For more details, see the [Template Extensibility](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/template-extensibility.md) guide!

**🪝 Optional:** **@salesforce/commerce-sdk-react "hooks" integration** &mdash; Decouples API calls from a project's implementation, allows API calls to be upgraded as an npm library dependency, and brings along many of the great features (including state management, and others) via [TanStack Query](https://tanstack.com/query/latest). See the [the Commerce SDK React docs](https://salesforcecommercecloud.github.io/pwa-kit/index.html) to get started!

## What’s New in All v3.x Versions

To learn about the features in all PWA Kit v3.x versions, see [pwa-kit](https://github.com/SalesforceCommerceCloud/pwa-kit/releases?q=v3&expanded=true) on GitHub. Also, check out the PWA Kit release notes in [Composable Storefront Release Notes](/docs/commerce/pwa-kit-managed-runtime/references/about-pwa-kit-managed-runtime/about.html).

## Required Changes for Upgrading From v2

### New SDK Packages

The PWA Kit SDKs have been moved to the `@salesforce` NPM organization. To upgrade to v3, install the new packages and replace all import statements for the following packages:

- `pwa-kit-react-sdk` -> `@salesforce/pwa-kit-react-sdk@^3`
- `pwa-kit-runtime` -> `@salesforce/pwa-kit-runtime@^3`
- `pwa-kit-dev` -> `@salesforce/pwa-kit-dev@^3`
- `pwa-kit-create-app` -> `@salesforce/pwa-kit-create-app@^3`
- `retail-react-app` -> `@salesforce/retail-react-app@^3`

### Breaking Change for `getProps`

As of v3.0.0, PWA Kit introduces a new data fetching strategy `withReactQuery`. This strategy uses the react-query library and allows you to write React hooks to fetch data isomorphically. Unlike with `getProps`, you no longer need to duplicate the data fetching logic for the client side and the server side. In this version, by default, `@salesforce/retail-react-app` uses [`@salesforce/commerce-sdk-react`](https://salesforcecommercecloud.github.io/pwa-kit/) which is powered by [`react-query`](https://tanstack.com/query/latest).

```javascript
// app/components/_app-config/index.jsx

import {withLegacyGetProps} from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/with-legacy-get-props'

const AppConfig = ({children}) => {
  return <div>My AppConfig</div>
}

export default withLegacyGetProps(AppConfig)
```

**note:** - You can use both `withReactQuery` and `withLegacyGetProps` at the same time.
- `getProps` and `shouldGetProps` were removed from the default template of pages of the Retail React App, but aren’t deprecated. Long-term support for these methods remains.

### Package Dependencies Upgrades

Change dependencies in package.json as shown below. Remove `@chakra-ui/system` from `peerDependencies` and include it under `dependencies` or `devDependencies`.

```json
"@chakra-ui/icons": "^2.0.19",
"@chakra-ui/react": "^2.6.0",
"@chakra-ui/skip-nav": "^2.0.15",
"@chakra-ui/system": "^2.5.6",
"framer-motion": "^10.12.9",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-hook-form": "^7.43.9"
```

Update engines in package.json to support Node 22 and npm 9.

```json
"engines": {`
    "node": "^18.0.0",`
    "npm": "^8.0.0 || ^9.0.0"`
}
```

Reinstall dependencies for your project with `npm i`.

## Optional: Use Template Extensibility

When migrating from v2.7.x to v3.x you can choose whether you want to use Template Extensibility. To benefit from it, you must import at least one file from `@salesforce/retail-react-app` (or another extendable template in the future).

From there, consider how many files you have modified in from the original project that you generated via `npx pwa-kit-create-app@2.x`. Some customers have large numbers (perhaps hundreds) of files, but even then, a significant number can be unmodified. Those unmodified files are a good candidate for importing from `@salesforce/retail-react-app`, but we recommend doing this process carefully and gradually. Many files in `@salesforce/retail-react-app` are similar but have been changed from their previous state in `v2.x` of the PWA Kit Retail React App. In particular, the `@salesforce/commerce-sdk-react` integration (migration details covered in more detail later) has caused a large number of files to change in terms of their imports as well as their file structure, removing the entire `commerce-api` directory from the app, as a starting point that is in itself a significant change.

**note:** When migrating a project to use template extensibility, please note that version 2.x of the PWA Kit SDKs and projects generated via `npx pwa-kit-create-app@2.x` do not have a dependency on `@salesforce/commerce-sdk-react` whereas the newer code `@salesforce/retail-react-app@^1.x` makes heavy use of this library, which touches and changes many files. To get a sense of the magnitude of the changes, you can compare `release-2.7.x` → `release-3.0.x` in this Github diff <https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket> and search for `@salesforce/commerce-sdk-react` and take note of all the additions that add this import.

**warning:** If your app attempts to share code with version `2.x` (which includes the `app/commerce-api` directory), you risk adding unnecessary code to your bundle where that code exists (in two very different forms) in both the `commerce-api` folder and the `@salesforce/commerce-sdk-react` npm module.

## Optional: Consume the commerce-sdk-react Hooks Library

As of v3.0.0, PWA Kit uses a different fetch strategy `withReactQuery`. This strategy leverages the react-query library and enables queries in the SSR rendering pass. The `@salesforce/retail-react-app` uses [`@salesforce/commerce-sdk-react`](https://salesforcecommercecloud.github.io/pwa-kit/) which is powered by [`react-query`](https://tanstack.com/query/latest).

In order for hooks to work on the server side, you need to wrap your `AppConfig` component with the new higher-order component `withReactQuery`.

**warning:** As part of the migration to ReactQuery as the default fetch strategy, `@salesforce/retail-react-app@^1` a change is required to ensure legacy `getProps()` calls continue to work.

```javascript
// app/components/_app-config/index.jsx

import {CommerceApiProvider} from '@salesforce/commerce-sdk-react'
import {withReactQuery} from '@salesforce/pwa-kit-react-sdk/ssr/universal/components/with-react-query'

const AppConfig = ({children}) => {
  return (
    <CommerceApiProvider
      clientId="12345678-1234-1234-1234-123412341234"
      organizationId="f_ecom_aaaa_001"
      proxy="localhost:3000/mobify/proxy/api"
      redirectURI="localhost:3000/callback"
      siteId="RefArch"
      shortCode="12345678"
      locale="en-US"
      currency="USD"
    >
      {children}
    </CommerceApiProvider>
  )
}

export default withReactQuery(AppConfig)
```

## Troubleshooting and Optimization

When you complete the dependency upgrades described above you may encounter issues in your project related to the below libraries. In the sections below we propose solutions for resolving these issues. The particulars of your project will vary and proposed solutions should be treated as guidelines and not absolute rules.

### Upgrade `react-hook-form`

For the `react-hook-form` migration, read the react-hook-form official doc [here](https://legacy.react-hook-form.com/migrate-v6-to-v7/). In the PWA project, there are two places that require changes:

1.  Move form `errors` object into one more layer of destructing for hooks in `app/components/forms/` as the `errors` object has been moved into the `formState` object.

```javascript
   // app/components/forms/useAddressFields.jsx

    //before
    export default function useAddressFields({form: {watch, control, errors}, prefix = ''}) {

    //after
    export default function useAddressFields({
        form: {
            watch,
            control,
            formState: {errors}
        },
        prefix = ''
    })
```

2.  Move the render props in `Controller`into the `field` prop. `Render`'s callback signature returns an object that contains `field` and `fieldState`.

```javascript
// app/components/field/index.jsx

    // before
    <Controller
        name={name}
        control={control}
        rules={rules}
        defaultValue={defaultValue}
        render={({onChange, value, ref}) => {
          // other code
        }}
    />

    // after
    <Controller
        name={name}
        control={control}
        rules={rules}
        defaultValue={defaultValue}
        render={({field: {onChange, value, ref}}) => {
          // other code
        }}
    />
```

### React 18 Hydration Error

As of React 18, hydration warnings are surfaced as errors instead of warnings as they had been in React 17. Some code updates were required to suppress these potential errors that prevent the application from building when there are hydration errors. It is essential to fix these errors to ensure the app can render isomorphically. This error occurs because there is a mismatch between server or client. If a component or a page happens to render conditionally, you must make sure that the hydration is finished before rendering any client-specific code.

In your project, create a utility function to determine if the hydration has finished. you can use a built-in variable provided by `window.__HYDRATING__` in `pwa-kit-react-sdk`.

```javascript
/**
 * This utility function determines if the app has finished hydration
 * @return {boolean}
 */
export const isHydrated = () => typeof window !== 'undefined' && !window.HYDRATING
```

### Chakra 2

**important:** If your project uses components and APIs from the `@chakra-ui/react` library that are different than the Retail React App template, review the official [Chakra migration docs](https://www.chakra-ui.com/docs/get-started/migration).

To support Chakra 2, there are a few files that require updates for projects based on the Retail React App template:

Remove `allowToggle` in the `Accordion` component because `allowMultiple` and `allowToggle` can't be used at the same time in Chakra 2.

In the `Footer` component, importing `StylesProvider` directly from `@chakra-ui/react` is deprecated. You must create it via `createStylesContext('Footer')` instead.

```javascript
import {createStylesContext} from '@chakra-ui/react'

const [StylesProvider, useStyles] = createStylesContext('Footer')
```

### @testing-library/react

Set up `userEvent` before calling any action, and await the action in unit tests that uses `userEvent`because in React testing library v14.0.0, all the user actions are async, and it requires calling `setup`before performing user actions.

For example:

```javascript
const user = userEvent.setup()`
// Import `render`and`screen` from the framework library of your choice.
// See https://testing-library.com/docs/dom-testing-library/install#wrappers
render(<MyComponent />)

await user.click(screen.getByRole('button', {name: /click me!/i}))
```

For more details, see the official docs for [userEvent](https://testing-library.com/docs/user-event/intro) from testing-library.

Alternatively, to avoid repetitively calling setup()`in many unit tests, you can set up your`userEvent `in`app/utils/test-util.js`right before rendering the test component and return it along with render results so that the test can perform the user actions without having to call` setup()`.

```javascript
export const renderWithProvider = (children, options) => {
   // some code here
   const user = userEvent.setup()
   const res = render(children, {
        wrapper: () => (
            <TestProvidersWithDataAPI {...options?.wrapperProps} locals={locals}>
                {children}
            </TestProvidersWithDataAPI>
        ),
        ...options
    })
    return {user, ...res}
}

//usage
test('some test', async () => {
   const {user} = renderWithProviders(<MyComponent />
   const button = screen.getByText(/button/)
   await user.click(button)
}
```

### Jest-setup

In jest-setup, there is a mock dependency that can throw an error about `TextDecoder` being undefined in `jest-setup.js.` Add the following to `jest-setup.js`:

```javascript
global.TextDecoder = require('util').TextDecoder
```

## Other Improvements

When migrating from version 2.x of the PWA Kit SDKs or projects generated via `npx pwa-kit-create-app@2.x`, the `@salesforce/commerce-sdk-react` code has been significantly refactored to remove the `app/commerce-api/` directory. Instead of those files handling API request and acting as an SDK, `@salesforce/commerce-sdk-react` supersedes that functionality. The v3 release of the SDKs correlates with the first release of `@salesforce/retail-react-app@^1.x` because the SDKs use this library a lot.

The implementation of `@salesforce/commerce-sdk-react` changes many files in the Retail React App. To get a sense of the size of the changes, compare `release-2.7.x` to `release-3.0.x` in this [GitHub diff](https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket) and search for `@salesforce/commerce-sdk-react`. In the diff, take note of all the additions that include this import.

<!-- document id=50064bb87cd13dca53b425e22dc59dbd7f3c72eecf15167807d607952dd5e50c url=/developer/current/en-us/commerce-cloud/commerce-api/guides/url-resolution.md -->

# URL Mapping

The [getUrlMapping](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=getUrlMapping) endpoint allows headless storefronts to support localized, user-friendly URLs based on [URL rules](https://help.salesforce.com/s/articleView?id=cc.b2c_using_url_rules_for_seo.htm&type=5) and [URL redirects](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&type=5) set up in Business Manager. This endpoint helps you to increase your site traffic and improve site navigation.

For example, you identify “new arrivals” as a valuable search term and you add a route (URL: `www.example.com/new-arrivals`) to your storefront. You can use a rule in Business Manager to map that URL to a category list page for new arrivals. Then you can use the getUrlMapping endpoint to apply the rule when a shopper:

- Searches for new arrivals
- Clicks or types in this URL: `www.example.com/new-arrivals`

## Prerequisites

Before you use the getUrlMapping endpoint:

- If you want to use the getUrlMapping to apply rules and redirects, set up your [URL rules](https://help.salesforce.com/s/articleView?id=cc.b2c_using_url_rules_for_seo.htm&type=5) and/or [URL redirects](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&type=5) in Business Manager.
- Add the `sfcc.shopper-seo` scope to a [SLAS API Client](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-shopper-apis.html).

## Sample Call

In this example, we use a cURL command to call the getUrlMapping endpoint to resolve this URL that a shopper clicked or typed in: `www.example.com/blue/new-arrivals/tops`.

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/site/shopper-seo/v1/organizations/$ORG/url-mapping' \
  --get \
  --header "Authorization: Bearer $TOKEN" \
  --data "siteId=$SITE" \
  --data "locale=en-GB" \
  --data-urlencode "urlSegment=blue/new-arrivals/tops"
```

The URL's path without a leading slash is passed as the `urlSegment` parameter.

## Sample Response

As shown in the response, the URL is mapped to a category called new-arrivals-tops:

```json
{
    "refinements": {
        "refinementColor": "Blue"
    }
    "resourceId": "new-arrivals-tops",
    "resourceType": "category"
}
```

## URL Redirects

You can also use the getUrlMapping endpoint to apply URL redirects that you set up in Business Manager. This helps you to carry out temporary product launches or seasonal campaigns and improve shopper experience.

For more information, see:

- [URL Redirects for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_url_redirects.htm&type=5)
- [Create a Redirect from a B2C Commerce URL](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5)

### Sample Call

In this example, we use a cURL command to call the getUrlMapping endpoint to redirect this URL that a shopper clicked or typed in: `www.example.com/cyber-monday`. For instance, you had a campaign for a past Cyber Monday. That page accumulated significant SEO rank that you want to keep. You set up a redirect to temporarily send shoppers from the old Cyber Monday URL to a new campaign page you're launching until your new Cyber Monday page is available.

```bash
curl "https://$CODE.api.commercecloud.salesforce.com/site/shopper-seo/v1/organizations/$ORG/url-mapping' \
  --get \
  --header "Authorization: Bearer $TOKEN" \
  --data "siteId=$SITE" \
  --data "locale=en-GB" \
  --data-urlencode "urlSegment=cyber-monday"
```

### Sample Response

In this sample response, the `urlSegment` redirects to a category called sales. The statusCode 302 tells you that it’s a temporary redirect and the destinationUrl field tells you where to redirect the shopper. Since `copySourceParams` is set to `true` (Yes in Business Manager), the `additionalUrlParams` value set to `utm_source=newsletter` is added to the end of the `destinationUrl`. In this example, we use UTM (Urchin Tracking Module) parameters to track marketing efforts and indicate that traffic came from a newsletter.

```json
{
  "additionalUrlParams": "utm_source=newsletter",
  "copySourceParams": true,
  "destinationUrl": "/sales?lang=en_GB&utm_source=newsletter",
  "resourceId": "sales",
  "resourceType": "category",
  "statusCode": "302"
}
```

## Considerations

- The getUrlMapping endpoint:
  - Can resolve URLs for these types of resources: product, category (including category refinements), and content assets (Page Designer or Content Slot assets).
  - Applies only to the types of rules and redirects described in [URL Rules for SEO](https://help.salesforce.com/s/articleView?id=cc.b2c_using_url_rules_for_seo.htm&type=5) and [Create a Redirect from a B2C Commerce URL](https://help.salesforce.com/s/articleView?id=cc.b2c_creating_a_redirect_from_a_digital_url.htm&type=5).
- You can pass a locale into the getUrlMapping endpoint. However, if you don’t, the endpoint falls back to the default locale of the site as configured in Business Manager.
- URL Redirects:
  - If there’s a conflict between your URL redirects and your URL rules for SEO, the URL redirects take precedence. In this scenario, the `resourceId` and `resourceType` will refer to the Commerce Cloud object (product, category, or content asset) and destination type that you configured in Business Manager.
  - Make sure that, before executing routing logic, your code considers the presence of these redirect-related outputs: `additionalUrlParams`, `copySourceParams`, `destinationUrl`, and `statusCode`. The presence of these fields means that a redirect is configured for the requested path. For more details, see the [getUrlMapping API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=getUrlMapping).
  - If there's a URI redirect, `resourceId` and `resourceType`are null.
  - The `destinationUrl` is based on your configuration in Business Manager: it's either a calculated value indicating the Commerce object (product, category, or content asset) URL or your specified URI. Note that an object's path may not necessarily match your headless storefront URLs but can be used as a reference for calculating your desired redirect path.

## Best Practices

These best practices apply to integrating getUrlMapping into a headless site:

- Add wildcard mappings to your routes flow as the final step in the sequence.
- By inserting this endpoint into your routes flow you‘re adding another database call to resolve requests on your website. To optimize for performance, we recommend that you:
  - Set long time-to-live (TTL) values for the getUrlMapping endpoint. (The default TTL is 12 hours.)
  - Use this endpoint as a fallback after attempting to resolve URLs with your routing engine. First try to use routes that are semantic and interpretable by your routing engine. For example: /categories/[categoryFriendlyName]/[categoryId].

## Troubleshooting

To resolve URL conflicts for generated URLs, see:

- [URL Generation and Conflict Resolution for B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_url_generation_and_conflict_resolution.htm&language=en_us&type=5)
- [Use the SEO URL General Tab](https://help.salesforce.com/s/articleView?id=cc.b2c_using_the_seo_url_general_tab.htm&language=en_us&type=5)

## Advanced Usage

You can customize the behavior of the getUrlMapping endpoint by using these hooks:

- `dw.shop.seo.url_mapping.beforeGET`
- `dw.shop.seo.url_mapping.modifyGETResponse`

See [Customization with Hooks](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) and the hooks for getUrlMapping in the [Hook List](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook_list.html).

## See Also

- [getUrlMapping API reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=getUrlMapping)
- [UrlMapping type reference](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-seo?meta=type%3AUrlMapping)
- [Routing](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/routing.html)
- [PWA Kit Documentation](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/getting-started.html)

<!-- document id=474a798859442a3573ada6287cfa1804d8344c9a2409281fa4a42b92ac4bb825 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/use-a-slas-private-client.md -->

# Use a SLAS Private Client

[Shopper Login and API Access (SLAS) API Clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) allow your application to authenticate and authorize shoppers. SLAS clients come in two types: public and private.

SLAS private clients offer several advantages over a public client, including:

- Pre-authorize guest shoppers to request access to a store which results in faster page load times.
- Enable the use of features not available to SLAS public clients including passwordless login and password reset. See [Private SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html).

To take advantage of a SLAS private client, your project must be able to securely store a client secret.

Consider using a public client if your project runs client-side and must communicate with SLAS directly.

PWA Kit 3.5 and above supports the use of both SLAS public and and private clients.

**note:** All PWA versions prior to PWA Kit 3.5 support only SLAS _public_ clients.

If you have an existing PWA Kit site using a SLAS public client, we encourage you to [read on](#set-up-a-slas-private-client) and consider switching to a private client.

Before running the commands in this guide, replace any placeholders with actual values. Placeholders are formatted like this: \$PLACEHOLDER.

## Private Client Secrets

When working with private clients, care should be taken to not expose the client secret to shoppers and client-side browsers.

To help secure the client secret, the PWA Kit Retail React App stores the secret server-side through the use of environment variables. See [Set Environment Variables](#set-environment-variables) for information on how to store the client secret.

## Set up a SLAS Private Client

At a high level, you'll do the following to set up a SLAS private client with your PWA Kit site.

- Create the SLAS private client
- Configure the PWA Kit
- Set environment variables

This video shows you how to set up a SLAS private client for the PWA Kit and a [phased Headless rollout](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html).

::video{src="https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/FqwkbNxGVXVsLCxQDGMP3g" title="SLAS Private Client in a Composable Storefront" type="vidyard"}

### Create a SLAS Private Client

Start by completing the instructions in [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md) and [Set Up API Access](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/setting-up-api-access.md) to create your SLAS Private Client.

To initialize an Agentforce session, obtain a SLAS shopper access token that includes the `sfcc.shopper-agents.rw` scope, and then call the [Shopper Agents API](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-agents?meta=Summary) with the `sessionInitKey` received at session start.
The Shopper Agent API starts the Agentforce session and associates it with the shopper context that `sessionInitKey` references. It doesn't move profile or basket data. Any access to shopper data continues via standard Shopper APIs, governed by your SLAS token’s scopes.

For CLI client creation, see [Authorization for Shopper APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guides/authorization-for-shopper-apis.md#slas-admin-ui-create-a-slas-client).

### Configure the PWA Kit

Once you have created your SLAS private client, follow the steps below to use it with your PWA Kit site:

1. If you haven't already done so, upgrade to PWA Kit v3.5 or above.
2. In your PWA Kit configuration file (`config/default.js`), set your commerceAPI clientId to your SLAS private client ID.

   ```jsx
   clientId: '$YOUR_SLAS_PRIVATE_CLIENT_ID',
   ```

3. In your `_app-config/index.js`, set the `enablePWAKitPrivateClient` prop of `<CommerceAPIProvider>` to `true`.
   ```jsx
   CommerceApiProvider enablePWAKitPrivateClient={true}
   ```
4. In your `ssr.js`, set the `useSLASPrivateClient` property of options pass to `runtime.createHandler` to `true`:

   ```js
   const options = {useSLASPrivateClient: true}
   const {handler} = runtime.createHandler(options, callback)
   ```

### Set Environment Variables

#### Local Environment

Run the following command to set the `PWA_KIT_SLAS_CLIENT_SECRET` environment variable locally in an active command prompt:

- On Mac / Unix, run `export PWA_KIT_SLAS_CLIENT_SECRET=$YOUR_CLIENT_SECRET`
- On Windows, run `set PWA_KIT_SLAS_CLIENT_SECRET=$YOUR_CLIENT_SECRET`

**note:** In a local development environment, you will want to set the `PWA_KIT_SLAS_CLIENT_SECRET` more permanently so that it is included automatically when you open a new command prompt.

On Mac / Unix, you can do this by setting the `PWA_KIT_SLAS_CLIENT_SECRET` environment variable in your machine's `.bashrc` file.
On Windows, you can do this by setting the `PWA_KIT_SLAS_CLIENT_SECRET` environment variable via Control Panel -> System -> Advanced -> Environment Variables.

#### MRT (Managed Runtime) Environment

If you are running your PWA Kit site remotely on Managed Runtime, you can set the `PWA_KIT_SLAS_CLIENT_SECRET` environment variable by running the following command in your terminal after replacing the variables to match with your environment.

For details on how to get a Managed Runtime API key and other properties of your remote environment, refer to our [Push and Deploy Bundles guide](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html).

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECTID/target/$ENVIRONMENTID/env-var/" \
  --request 'PATCH' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $RUNTIME_ADMIN_API_KEY" \
  --data '{ "PWA_KIT_SLAS_CLIENT_SECRET": {"value": "'$PWA_KIT_SLAS_CLIENT_SECRET'"} }'
```

For more information, see [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

### Setup for Phased Headless Rollouts

**note:** This setup applies to a hybrid storefront that uses Plugin SLAS. It doesn't apply if you're using [hybrid authentication](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md).

In addition to the PWA Kit setup steps described above, on a Phased Launch storefront that is using both PWA Kit and SFRA, you will also want to update Plugin SLAS to use your SLAS private client. See the [Plugin SLAS readme](https://github.com/SalesforceCommerceCloud/plugin_slas) for instructions on how to set up a SLAS private client to work with SFRA.

## Additional Endpoint

If you're extending your PWA Kit implementation to use other SLAS endpoints that require private clients like Passwordless Login, you can extend the set of endpoints available using the `applySLASPrivateClientToEndpoints` option for `runtime.createHandler`:

```js
const options = {
  useSLASPrivateClient: true,
  applySLASPrivateClientToEndpoints: /oauth2\/(token|passwordless\/(login|token))/
}
const {handler} = runtime.createHandler(options, callback)
```

## Troubleshooting

- If you see HTTP 400 calls to SLAS [/authorize](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=authorizeCustomer), the PWA Kit site is using the SLAS public client flows with your private client ID. In your `_app-config/index.js` file, set the `enablePWAKitPrivateClient` prop inside the CommerceAPIProvider to `true`.

- On a local development environment, the PWA Kit server will not start if the `useSLASPrivateClient` property is enabled in `ssr.js` and the `PWA_KIT_SLAS_CLIENT_SECRET` environment variable has not been set. [Set the environment variable](#set-environment-variables) to your SLAS client secret to continue.

- After deploying your PWA Kit site to Managed Runtime, if you see an HTTP 501 error when making a call to SLAS, it could mean the `PWA_KIT_SLAS_CLIENT_SECRET` environment variable has not been set. After setting it, please wait e a few minutes for the change to apply.

## See Also

- [Public SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html)
- [Private SLAS Client Use Cases](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html)
- [Phased Headless Rollouts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.html)
- [Passwordless Login](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-passwordless-login.html)
- [Password Reset](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-password-reset.html)

<!-- document id=8215e7890436e28ae6f6001e542f13c2c7db05a1f9a95fdfa1e9b1df25e138ef url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/hybrid-implementation.md -->

# Use Composable Storefront in a Hybrid Implementation

A hybrid storefront allows the combination of traditional storefronts built on Salesforce B2C Commerce with decoupled, headless Composable Storefront sites. B2C Commerce supports hybrid storefront implementations so that you can execute on your headless strategy with reduced cost and faster time to market.

**tip:** Only existing customers can access some of the links on this page. Visit [Salesforce Commerce Cloud GitHub Repositories and Access](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-github-repo-access.html) for information about how to get access to the repositories.


## Hybrid Authentication

Starting with B2C Commerce version 25.3, [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md) replaces Plugin SLAS. Hybrid Auth is a standalone solution for implementations that need both SFRA/SiteGenesis authorization and Shopper Login and API Access Service (SLAS) authorization. This means you need both a `dwsid` (SFRA/SiteGenesis) and a JSON Web Token (SLAS), and these tokens must be kept in sync. Hybrid Auth is an improvement over the Plugin SLAS approach, offering enhanced performance and stability of hybrid storefronts by moving the feature directly into the B2C Commerce platform.

Hybrid storefronts that use Plugin SLAS will continue to work, but we highly encourage adopting Hybrid Auth.

For complete implementation details, see [Hybrid Authentication](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md).

### Hybrid Authentication Benefits

#### Platform-Native Data Synchronization

Launch faster with out-of-the-box authentication, ensuring automatic data synchronization between SFRA and Composable Storefront pages. You no longer need Plugin_SLAS!

#### Seamless Shopper Experience

Shoppers can navigate across your hybrid site with no disruption or loss of data. Synchronization is expanded to include Shopper Context session attributes and support for consistent analytics.

#### Full Support for All Templates

Whether you are using SiteGenesis or SFRA, we have you covered with a fully supported and productized solution to ease your path to Composable Storefront success.

### Supported Configurations

B2C Commerce version 25.6 Hybrid Auth support includes:

- SLAS public and private clients
- SFRA and SiteGenesis templates
- PWA Kit v3.10.0 or later
  - More specifically, `@salesforce/commerce-sdk-react`: v3.3.0, which comes packaged with PWA Kit v3.10.0
- Third-party IDP login with SLAS:
  - Configure third-party IDP logins using SLAS, not Business Manager.
  - Perform all third-party IDP interactions using SLAS.
  - SFRA third-party IDP logins are only supported when using SLAS.

## Hybrid Storefront Considerations

### Cost to Maintain

Decide on the goals, scope, and timeline for your hybrid (phased headless) rollout. Keep in mind that the longer your site is in hybrid mode, the more time you have to spend on the operating complexity involved. Set a due date for transitioning to a 100% Composable site.

### Performance Optimization

A principal benefit of a single page application (SPA) like PWA Kit is that the app bundle is sent to the client and subsequent page requests can often be served without server requests. For this reason, we highly recommend having more than 1 page on PWA Kit to gain performance and shopper UX efficiencies, for example: instead of just your homepage - migrate your homepage and next 1-2 most common journey steps (homepage & search; homepage & our brand). Use the analytics tools at your disposal to chart these common customer journey paths through your site.

## Next Steps

- For hybrid implementation details that apply to Hybrid Authentication, see [Configure a Hybrid Storefront with Hybrid Auth](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/hybrid-auth.md).
- For working with SCAPI in a hybrid implementation, see [Hybrid Guidance](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hybrid-storefront-baskets.html).
- For hybrid implementation details that apply to Plugin SLAS, see [Configure a Hybrid Storefront with Plugin SLAS](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/phased-headless-rollouts.md).

<!-- document id=9f82cb6884c3a10b56872e9799b062fa7600bed09e1754c3d73838585ac353b2 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/custom-objects/b2c-business-objects.md -->

# Use Custom Object Definitions

Use custom object definitions to greatly speed implementation and enable you to take advantage of functionality developed for these objects.

Business objects define the data structure of the catalog and other data used by Salesforce B2C Commerce. B2C Commerce provides a rich library of objects that are designed to address almost all data needed by ecommerce applications. You can also customize your data by creating custom attributes for system objects and custom objects.

## System Objects

Extending objects can help you gather more information from your customers, tailor your storefront site to show more information to the consumer, and enable you to process orders more efficiently, depending upon your back office needs.

Using the System Object Type module you can:

- View all of the system object types
- View all of the attributes defined to a system object
- Edit those attributes including creating new attribute values
- View attribute groupings
- Create new attribute groups

Customize attribute definitions of some system objects to suit your individual site needs. For instance, you can add an additional attribute to the CustomerAddress system object to record an evening phone number or modify custom preferences as custom attributes of the system objects: OrganizationPreferences and SitePreferences (which govern global preferences for all sites and site-specific preferences, respectively).

In addition to adding a customized attribute, you can also choose how to group those attributes through this same module.

**note:** Custom preference attributes that have been marked as _mandatory_ can't be updated with empty values in either Business Manager or import.

### Creating System Object Attribute Definitions

Extending system objects can help you gather more information from your customers, tailor your storefront site to show more information to the consumer, and enable you to process orders more efficiently, depending upon your back office needs.

Customize attribute definitions of some system objects to suit your individual site needs. For instance, you can add an additional attribute to the `CustomerAddress` system object to record an evening phone number.

In addition to adding a customized attribute, you can also choose how to group those attributes.

System objects can be stored globally, which makes the instances available to the entire organization and all sites, or local (per site). The system object type itself is always available to the entire organization.

**note:** Custom attributes that have been marked as _mandatory_ can't be updated with empty values in either Business Manager or import.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **System Object Types.**

2.  On the System Object Type List page, click the name of the object you want to edit.

3.  Click the **Attribute Definitions** tab.

4.  On the Attribute Definitions tab, click **New** to begin the definition process.

5.  On the Attribute Definition Details page, enter or select the following information:

    1.  ID: enter a unique ID for the attribute. We recommend not using alphanumeric characters only for the ID.

        You can use the following special characters in the attribute ID: `"+", "-", "$", ".", "%", "§", "&", "*", "#", "/"`.

    2.  Display Name: enter a display name. This is the name shown in Business Manager and in the storefront.

    3.  Value Type: select a data type. The data type changes the other configuration options for the attribute once you apply it.

    If you change the language or type, you must confirm the change before it's applied. Changing the language or type of an attribute causes existing values of that attribute to be lost.

    Click **Apply.** Additional fields appear depending on the data type you select.

6.  Add information for the fields required by the data type you selected and click **Apply.**

7.  Click **\<\< Back** to see attribute you just created on the Attribute Definitions tab.

### Editing Custom Object Attribute Properties

You can add custom attributes to custom objects or change property flags for attributes.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Site Development > Custom Object Types.**

2.  On the Custom Object Type List page, click the name of the object you want to edit.

3.  Click the **Attribute Definitions** tab.

4.  Click the **[attribute name]** or the **Edit** button to edit the attribute.

5.  On the Attribute Definition Details page, edit the attributes and click **Apply** to save your changes.

    Salesforce recommends backing up your data before changing the Value Type property. If you change the value type, all data is lost for the attribute. The existing values for the attribute are lost because Salesforce B2C Commerce must create a new, empty attribute and delete the old attribute.

### Grouping Business Object Attributes

In Business Manager, attributes appear in groups. These groups are system-defined, via the System Object Types module. To show a system attribute, the attribute must belong to a group. Otherwise, it doesn't appear on a page within Business Manager.

This topic provides an example of how to group attributes that appear on the Product details page. The example adds attributes that are specific to digital cameras.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **System Object Types** > **Product** > **Attribute Grouping tab.**

    A list of existing groups appears. You can either create a new group for the attribute, or select an existing group.

2.  Create a new group (Digital Camera).

    1.  In the ID field, enter a group ID (`DigCamera`)

    2.  In the Name field, enter a group name (`Digital Camera`).

    3.  Click **Add.**

3.  Click the **Edit** link for the new group (Digital Camera).

    You can see that there are no attributes assigned to this group.

4.  Click the ellipsis **(...)** to access a list of all Product (system object) attributes available to this group. Enter `Digital` in the Search box and click **Find.**

5.  Click **Select All**and **Select.**

    All available attributes are now assigned to the group.

6.  To see the additional attributes, select **_site_** > **Merchant Tools** > **Products and Catalogs** > **Products**. Select any product.

7.  Click the **Attributes** tab.

    The new attributes (in the new group) are listed toward the bottom of the page.

### System Objects Custom Attribute Tutorial

You can create a new custom attribute of the Product object: to reflect that shoes are made up of multiple materials. The new attribute is named Upper Material.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Adminstration** > **Site Development** > **System Object Types**.
2.  Select the **Product** object link and then the _Attribute Definitions_ tab.

    Notice the list of attribute definitions already created for this system object.

3.  Click **New** to create a new attribute for this system object.
4.  Supply an ID, Name, and Value Type for the new attribute and click **Apply.** In this case, because we need many string values for the attribute, we select "Enum of Strings" as the value type:

    | Field        | Value          |
    | ------------ | -------------- |
    | ID           | UpMaterial     |
    | Display Name | Upper Material |
    | Value Type   | Set of String  |

    **note:** If you change the language or type, you must confirm the change before it's applied. Changing the language or type of an attribute causes existing values of that attribute to be lost.

5.  In the Attribute Value Range Definition, enter the values, one-by-one and click **Apply.**

    | Value   | Display Value           |
    | ------- | ----------------------- |
    | leather | Leather                 |
    | vinyl   | EZ-clean Pseudo Leather |
    | cotton  | Cotton                  |

    **note:** Important: remember to assign the new attribute to an attribute group.

## Custom Objects

Custom objects enable you to extend the Salesforce B2C Commerce model to suit your business needs.

Custom object types are created for an organization and are then available to use in all storefronts defined for the organization. You can choose, when creating instances of the object, whether to make the instances site-specific or organization-wide.

Custom objects can be stored globally, which makes the instances available to the entire organization and all sites; or locally, that is, per site. The custom object type itself is always available to the entire organization.

**note:** Custom object attributes can't be used in search refinement.

You use two Business Manager modules to create and manage custom objects:

- Custom Object Types: Use to create custom object types by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Site Development** > **Custom Object Types.**
- Custom Objects: Use to create custom objects by selecting **_site_** > **Custom Objects** > **Custom Object Editor.**

**note:** Localizable attributes for custom objects are deprecated.

### Creating Custom Object Types

You create and manage custom object types for additional business objects required by your storefront or business logic to extend the Salesforce B2C Commerce model.

Custom object types must be created in a stage instance, then replicated to production. For example, you could create an object type of 'Sample'. You create the custom object type 'Sample' and then give it attributes, for instance, 'SKU' and 'Date.' Never define custom object types directly in a dev or production instance, because the replication process will remove them. To include custom object types in replication, select the Object Definitions setting in Global Data Replication Settings.

Custom objects can be stored globally (which makes the instances available to the entire organization and all sites), or local (that is, per site). The custom object type itself is always available to the entire organization.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Custom Object Types** to view a table of custom object types.

2.  Click **New** to define a custom object.

3.  On the New Custom Object Type page General tab, enter the following information and click **Apply**.

    - ID: Enter a unique ID for the custom object type. This is the name that you select in Business Manager when you want to create objects of this for the new object type you are defining.
    - Key Attribute: The name of the attribute that is used to provide a unique key for every custom object of this type. The attribute doesn't have to exist when you specify it, but it must exist before any custom objects of this type are created.
    - Data Replication: Select whether you want the custom object to be replicable between instances. This selection can't be changed after the custom object type has been created.
    - Storage Scope: Select whether you want the custom object to be available for the entire organization (all sites) or a specific site.

4.  To create new attributes and assign attributes to the custom object type, click the **Attribute Definitions** tab.

    You can add or remove object attributes on this page.

5.  Click **New** to add a new custom attribute or **Edit**to edit an existing attribute.

    Localizable attributes for custom objects are deprecated.

6.  On the Attribute Definition Details page, enter the following information:

    1.  ID: Enter a unique ID for the attribute. The pipe symbol '|' isn't allowed in attribute definition IDs, as it's used internally for versioning purposes. Salesforce recommends using alphanumeric characters only for the ID.

    2.  Display Name: Enter a display name. This is the name shown in Business Manager and in the storefront.

    3.  Value Type: Select a data type. The data type changes the other configuration options for the attribute once you apply it.

    If you change the language or type, you must confirm the change before it's applied. Changing the language or type of an attribute causes existing values of that attribute to be lost.

    Additional fields appear depending on the data type you selected. Enter the relevant information and click **Apply.** After you create attributes, you must add the attribute to an Attribute Group in order to manage the custom object through the Business Manager (Custom Object module for the storefront).

7.  Click **\<\< Back**, and then click the **Attribute Grouping** tab.

8.  On the Attribute Grouping tab, specify a name and ID for the attribute group and click **Add.**

    The new attribute group appears in the grid below.

9.  Click the **Edit** link for the group to add attributes to the group.

    Make sure to add the key attribute you specified on the New Custom Object Type page General tab. Custom objects can't be created for this definition unless the key attribute is included in an attribute group. Don't add the creationDate or lastModified attribute, as these values are automatically supplied by B2C Commerce and don't need to be specified when creating custom objects of this type definition.

10. On the Custom Object Attribute Definition Assignments page, no attributes are assigned to the group at first. Click the ellipsis **( ... )** to see the attributes that exist for this custom object type:

11. On the Select Object Type Attribute for Custom Object page, select the boxes for the attributes you want and click **Add.**

12. You can sort the attributes in the Custom Object Attribute Definition Assignments Page, to define the order in which the attributes are presented.

    To manage the custom object type that you have just created, use the Custom Objects module under the site area in the Business Manager. See [Custom Objects.](#custom-objects)

### Creating Custom Objects

A custom object is a specific instance of a custom object type.

You must create [custom object types](#creating-custom-object-types) before you create custom objects.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Custom Objects** > **Custom Object Editor**.

2.  On the Manage Custom Objects page, in the **Object Type** list, select the object definition you want to create a new object for.

3.  Click **New** to create a new object of the type selected.

4.  On the New Custom Object page, enter values for any attributes required by the custom object. Click the ? icon beside each attribute for more information.

5.  Click **Apply** to create the object.

### Deleting Custom Objects

You can delete custom objects individually or in a bulk action.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Merchant Tools** > **_site_** > **Custom Objects** > **Custom Object Editor**.

2.  On the Manage Custom Objects page, enter a search string and click **Find**.

3.  Select the box of any object you want to delete.

4.  Click **Edit All** or **Edit**.

5.  On the Process Custom Objects Search Result - Step 1: Select Action page, select **Delete Custom Objects** and click **Next>>**.

6.  On the Step 2: Delete Custom Objects - Confirmation page, click **Finish**.

7.  On the Batch Processes page, click **Refresh.**

    The Batch Processes page doesn't automatically refresh. You must click **Refresh** to see a status change.

### Making a Custom Attribute Editable or Uneditable

You can have a custom attribute that is fed directly into Salesforce B2C Commerce from a backend system-of-record.

You can set the externally-managed flag to indicate to Business Manager users that they shouldn't edit these attribute directly. Such an attribute is considered externally managed, because the attribute values are set in an external system. If the feed for an uneditable attribute contains an incorrect value, you can fix the value by deselecting the _Externally Managed_ option and manually fixing it. When the value is fixed, reselect the _Externally Managed_ option.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Custom Object Types** > **System Object Types** .

    The Custom Object Type List page opens or the System Object Type List page opens.

2.  Click the name of the object with the attribute that you want to restrict access to.

    The Custom Object Types > (custom object) page appears or the System Object Types > (system object) page opens.

3.  Click the **Attribute Definitions** tab.

4.  Click the name of the attribute to restrict access to.

    You can't restrict access to system attributes, only custom attributes.

5.  Select the **Externally Managed** box.

6.  Click **Apply.**

### Editing Custom Object Attribute Properties

You can add custom attributes to custom objects or change property flags for attributes.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Custom Object Types.**

2.  On the Custom Object Type List page, click the name of the object you want to edit.

3.  Click the **Attribute Definitions** tab.

4.  Click the **[attribute name]** or the **Edit** button to edit the attribute.

5.  On the Attribute Definition Details page, edit the attributes and click **Apply** to save your changes.

    Salesforce recommends backing up your data before changing the Value Type property. If you change the value type, all data is lost for the attribute. The existing values for the attribute are lost because Salesforce B2C Commerce must create a new, empty attribute and delete the old attribute.

## Creating Custom Attributes for Business Objects

You can create custom attributes for system objects or custom objects.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** select one of these options:

    - **System Object Types**
    - **Custom Object Types**

2.  Click the **object name** > **Attribute Definitions** tab and click **New.**

3.  On the Attribute Definition Details page, enter an ID and name for your attribute.

    Salesforce recommends including only alphanumeric characters in IDs. IDs must be unique, but names can be duplicates. If an attribute is configured for appear in Business Manager or the storefront, the name appears.

4.  Select a data type for the attribute.

    The data type controls additional configuration items for the attribute.

5.  Click **Apply.**

    Additional fields appear that let you configure how values are managed for the attribute. These fields are different depending on the data type selected.

## Custom Attribute Definition Limits

B2C Commerce limits the number of custom attribute definitions you can add to each object type. The limit depends on the object type. Localizable custom attribute definitions count toward the limit.

| Object type                                        | Maximum custom attribute definitions |
| -------------------------------------------------- | ------------------------------------ |
| Product (including SKUs)                            | 500                                  |
| Site Preferences and Organization Preferences      | 500                                  |
| Content                                            | 50                                   |
| Custom object                                      | 50                                   |
| Line Item Tax                                       | 10                                   |
| Other extensible system objects                    | 50                                   |

A single multi-value attribute can hold between 120 and 200 values, depending on the attribute's value type.

For a full list of platform quotas and how to monitor them, see [Governance and Quotas](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/quotas/b2c-governance-and-quotas.md).

<!-- document id=52b3f8982fe4f9bd71cdc6f7bd1f3785a1c674d9fcbe7e454b642010beae7b09 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/env-var-feature-access.md -->

# Use Environment Variables in React.js

Managed Runtime environment variables allow you to add variables to the application process running in an environment, without having to make code changes. Environment variables are stored securely, making them ideal for use cases such as:

- Calling third-party resources that are protected by API keys
- Conditionally changing React.js rendering


For more details, see [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

In this tutorial, we'll use environment variables to alter React.js rendering without changing code. You access environment variables through [`process.env`](https://nodejs.org/docs/latest/api/process.html#processenv), which is only available in Node.js and not in browsers. PWA Kit rendering is isomorphic, in that it renders on both the client and the server. So to make environment variables available in React.js, you can add them to your PWA Kit configuration files as shown in this tutorial.

In this example, we'll use an environment variable to enable a feature on your site. For instance, for a limited time, you can test a new feature such as express checkout. You can then monitor shopper engagement with the feature to understand its impact.

## Prerequisites

To complete this tutorial, first:

- Get access to Managed Runtime and Runtime Admin. See [Managed Runtime Administration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/managed-runtime-administration.html).
- Have an API key to use the Managed Runtime API. To find your API key, log in to the [Runtime Admin](https://runtime.commercecloud.com/) tool and go to the [Account Settings](https://runtime.commercecloud.com/account/settings) page.
- Have a developer or admin role on the project for which you’re setting environment variables. If you don't have access, ask someone in a Managed Runtime admin role to help you with that.


## On Your Local Machine

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

### Local Testing Prerequisite

In your project, create your chosen content or feature. For example, create a hero banner on your homepage.

### Test the Environment Variable Locally

1. To set the environment variable in the current session, open a terminal and run this command:

   - **Windows:** `set ENABLE_FEATURE='true'`
   - **Most Unix-like operating systems, including macOS:** `export ENABLE_FEATURE=‘true’`

2. Check if the environment variable is set correctly by running:

   - **Windows:** `echo %$ENABLE_FEATURE%`
   - **Most Unix-like operating systems, including macOS:** `echo $ENABLE_FEATURE`

   The command returns this output: `true`

3. Add this JavaScript code to the configuration file in your project &mdash; `config/default.js`:

```jsx
function parseEnvVar(envVarName) {
  const val = process.env[envVarName];
  if (val === undefined) {
    throw new Error(`Environment variable ${envVarName} is required.`);
  }
  try {
    return JSON.parse(val);
  } catch (err) {
    throw new Error(
      `Environment variable ${envVarName} must be a valid JSON string.`
    );
  }
}
module.exports = {
  app: {
    enableFeature: parseEnvVar("ENABLE_FEATURE") || false,
  },
};
```

4. Add this JavaScript code to the home page in your project &mdash; `app/pages/home/index.jsx`:

```jsx
import { getConfig } from "@salesforce/pwa-kit-runtime/utils/ssr-config";

const Home = () => {
  const config = getConfig();
  const enableFeature = config.app.enableFeature;
  return enableFeature && <h1>My New Feature</h1>
};

export default Home;

```

5. Start the development server using `npm start` then navigate to the homepage locally to see your feature rendered.

## In a Non-production or Production Environment

We recommend testing these steps in a non-production environment before deploying your changes to production.

Before running the commands in this tutorial, replace any placeholders with actual values. Placeholders are formatted like this: `$PLACEHOLDER`.

1. Call the [projects_target_env_var_partial_update](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/references/mrt-admin?meta=projects_target_env_var_partial_update) API endpoint and set a feature flag as an environment variable. This deploys your bundle. Wait for the environment to redeploy before using the environment variable in your code. You can also use Runtime Admin to manage environment variables. See [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md).

Use the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md):

```bash
export MRT_API_KEY='your-runtime-admin-api-key'
npx @salesforce/b2c-cli mrt env var set 'ENABLE_FEATURE=true' \
  --project my-storefront --environment staging
```

Alternatively, use the API:

```bash
curl "https://cloud.mobify.com/api/projects/$PROJECT_ID/target/$ENVIRONMENT_ID/env-var/" \
  --request 'PATCH' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $MOBIFY_API_KEY" \
  --data   '{"ENABLE_FEATURE": {"value": "true"}}'
```

2. [Deploy your bundle](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/pushing-and-deploying-bundles.html) from your local machine to your chosen environment.

## See Also

- [Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md)
- [Environment Variable Tutorials](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md#tutorials)
- [Troubleshoot Environment Variables](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/environment-variables.md#troubleshoot-environment-variables)
- [Debugging Locally](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/debugging.html#debugging-locally)

<!-- document id=1430bd2e047115706b08d76c272f0bd039fa643e85036962170be9f258631632 url=/developer/current/en-us/commerce-cloud/pwa-kit-managed-runtime/guides/pwa-httponly-cookie.md -->

# Use HttpOnly Session Cookies for Improved Storefront Security

When you enable HttpOnly session cookies, the storefront stores Shopper Login and API Access Service (SLAS) access and refresh tokens as HttpOnly cookies instead of local storage. The server-side SLAS proxy layer handles token injection transparently. Only browsers can read and send HttpOnly cookies. JavaScript code that runs on the page can't access them. Using HttpOnly cookies prevents client-side scripts from exploiting the storefront and makes the storefront more secure.

## Prerequisite

PWA Kit version 3.19 or later. See the [pwa-kit](https://github.com/SalesforceCommerceCloud/pwa-kit) GitHub repository.

For more information about HttpOnly cookies and how to configure them in composable storefronts, see [pwa-kit GitHub: HttpOnly Session Cookies — Architecture](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/httponly-cookies-architecture.md). For more information about HttpOnly cookie storage, see [pwa-kit GitHub: HttpOnly Mode: SLAS Property Storage Mapping](https://github.com/SalesforceCommerceCloud/pwa-kit/blob/develop/docs/httponly-storage-mapping.md).

<!-- document id=21d62e232f1a6e9683eec5cfd0cff37a058de0fdea9b5ec73d69402bc6f0c8ca url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-mcp-server.md -->

# Use MCP and Agent Skills for Storefront Next

Connect your AI assistant to B2C Commerce with the [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md). Use the B2C MCP to search official documentation, investigate logs, debug cartridge code, and work with SCAPI Admin APIs while developing your storefront.

## Connect Your Assistant

[Install the B2C MCP through an agent plugin](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md#connect-your-ai-assistant) in supported clients. It includes guidance from the `b2c`, `b2c-cli`, `storefront-next`, and `b2c-ops` skill collections, available to your assistant through MCP tools. You don't need a separate skills installation.

You can also [install Agent Skills separately](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling-agent-skills.md), alongside the MCP or on their own. Storefront Next skills cover routes, components, Page Designer, and deployment. CLI skills help your assistant use the B2C CLI for tasks such as SLAS client configuration and Managed Runtime administration.

Configure the credentials needed for your task using the shared [configuration and authentication options](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md#configuration-and-authentication).

## Try a Task

> Find the official guidance for Storefront Next hybrid routing and help me plan the eCDN rules for my storefront.

> Check my Custom API registration and help me investigate any errors before I deploy the storefront.

> Review the logs for this incident and summarize the evidence and next steps before making changes.

## Agentforce Commerce Vibes

For AI-assisted storefront development in VS Code, see [Agentforce Commerce Vibes](https://developer.salesforce.com/docs/commerce/commerce-vibes/guides/cv-agentforce-commerce-vibes.md). Commerce Vibes brings a conversational development experience together with B2C Commerce tools and skills.

<!-- document id=c69249f537cf7456a085f323d8278ab41de80158bbd591570d3ebf1afd8f13a6 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-comm-spm-client-side-apex-sale-transaction.md -->

# Use Saved Payment Method in Sale Transactions

After you create a Saved Payment Method (SPM), you can use it for Sale transactions by implementing the sale request processing in a class that implements `commercepayments.PaymentGatewayAdapter`.

If the SPM record is created with a `Type` value of `ExtendedAPM` or `ExtendedWallet` and includes an `ExtendedPaymentMethodType`, you can access these fields in the Sale request with the Apex layer using a query like the following:

```apex
private static SavedPaymentMethod fetchSavedPaymentMethod(Id idToProcess) {
    QueryUtils q = new QueryUtils(SavedPaymentMethod.SObjectType);
    q.getSelectClause().addField('GatewayToken', false);
    q.getSelectClause().addField('GatewayReference', false);
    q.getSelectClause().addField('ExtendedPaymentMethodType', false);
    q.getSelectClause().addField('type', false);
    q.setWhereClause(' WHERE Id = \'' + idToProcess + '\'');
    return (SavedPaymentMethod) Database.query(q.buildSOQL())[0];
}

//Sample Adyen sale transaction request.
private String buildSaleRequest(commercepayments.SaleRequest saleRequest) {
    String currencyIso = saleRequest.currencyIsoCode;
    commercepayments.SaleApiPaymentMethodRequest paymentMethod = saleRequest.paymentMethod;
    if (currencyIso == null) {
        currencyIso = UserInfo.getDefaultCurrency();
    }
    JSONGenerator jsonGeneratorInstance = JSON.createGenerator(true);
    jsonGeneratorInstance.writeStartObject();
    jsonGeneratorInstance.writeStringField('merchantAccount', '{!$Credential.Username}');
    jsonGeneratorInstance.writeStringField('reference', String.valueOf(Datetime.now().getTime()) + String.valueOf(Math.random()).substring(2, 8));

    jsonGeneratorInstance.writeFieldName('amount');
    jsonGeneratorInstance.writeStartObject();
    jsonGeneratorInstance.writeStringField('value', String.ValueOf((saleRequest.amount * 100.0).intValue()));
    jsonGeneratorInstance.writeStringField('currency', currencyIso);
    jsonGeneratorInstance.writeEndObject();

    jsonGeneratorInstance.writeFieldName('paymentMethod');
    jsonGeneratorInstance.writeStartObject();
    String shopperReference;
    String token;
    String type = 'scheme';
    Id idToProcess = saleRequest.paymentMethod.id;
    Map < String, String > paymentTypeMap = new Map < String, String > {
        'us_bank_account' => 'ach',
        'sepa_debit' => 'sepadirectdebit',
        'au_becs_debit' => 'directdebit_AU',
        'bacs_debit' => 'directdebit_GB',
        'amazon_pay' => 'amazonpay',
        'googlepay' => 'paywithgoogle'
    };
    if (idToProcess.getSObjectType() == SavedPaymentMethod.SObjectType) {
        SavedPaymentMethod savedPaymentMethod = fetchSavedPaymentMethod(idToProcess);
        token = savedPaymentMethod.GatewayToken;
        shopperReference = savedPaymentMethod.GatewayReference;
        String paymentMethodType = savedPaymentMethod.type;
        String extendedPaymentMethodType = savedPaymentMethod.ExtendedPaymentMethodType;
        System.debug('Queried SPM record for QA override');
        type = determinePaymentType(paymentMethodType, extendedPaymentMethodType, paymentTypeMap);
    }
    // Common JSON field population
    jsonGeneratorInstance.writeStringField('type', type);
    jsonGeneratorInstance.writeStringField('storedPaymentMethodId', token);
    jsonGeneratorInstance.writeEndObject();
    jsonGeneratorInstance.writeStringField('shopperInteraction', 'ContAuth');
    jsonGeneratorInstance.writeStringField('recurringProcessingModel', 'UnscheduledCardOnFile');
    jsonGeneratorInstance.writeStringField('shopperReference', shopperReference);
    //jsonGeneratorInstance.writeStringField('holderName', 'John Smith');
    jsonGeneratorInstance.writeNumberField('captureDelayHours', 0);
    jsonGeneratorInstance.writeEndObject();
    return jsonGeneratorInstance.getAsString();
}
```

**See Also**

- [_Apex Reference Guide_: PaymentGatewayAdapter Interface](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_interface_commercepayments_PaymentGatewayAdapter.htm)
- [_Apex Reference Guide_: CommercePayments Namespace](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_namespace_commercepayments.htm)

<!-- document id=c7a5c6aae4b19516000cf7d9c280b192d4924370557b25a22a49325c5a5c53cd url=/developer/current/en-us/commerce-cloud/commerce-api/guides/use-scapi-with-mulesoft.md -->

# Use SCAPI with MuleSoft

The Salesforce B2C Commerce Data Connector and Salesforce B2C Commerce Shop Connector are deprecated and replaced with the MuleSoft HTTP Connector.

For MuleSoft HTTP Connector details, see the following documentation:

- [HTTP Connector 1.10 - Mule 4](https://docs.mulesoft.com/http-connector/latest/)
- [Configure HTTP Request Operation](https://docs.mulesoft.com/http-connector/latest/http-request-ref)

If you have existing Mule apps that currently use the Salesforce B2C Commerce Connectors, use the steps in [Migrate to the MuleSoft HTTP Connector](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/migrate-mulesoft-http-connector.md) as a blueprint to migrate to the MuleSoft HTTP Connector.

<!-- document id=4c1aa8e1191c9e767d7f7ee3f0228453eefe3c9f1136a35595199f746dc3a4cc url=/developer/current/en-us/commerce-cloud/sfnext/guides/sfnext-hybrid.md -->

# Use Storefront Next in a Hybrid Implementation

Hybrid Auth is a standalone solution for implementations that need both Storefront Reference Architecture (SFRA) or SiteGenesis authorization and Shopper Login and API Access Service (SLAS) authorization. Hybrid Auth maintains both a `dwsid` (SFRA or SiteGenesis) and a JSON Web Token (SLAS), keeping these tokens in sync.

Hybrid Auth is designed for various use cases, all of which involve using both SFRA or SiteGenesis and SLAS.

**note:** This guide covers the Storefront Next implementation path on Primary Instance Group (PIG) instances (production, staging, and development). For on-demand sandbox (ODS) instances, see [Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-ods.md). For local development, see [Set Up Hybrid Proxy Locally in Secondary Instance Group (SIG) Environments](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-proxy-local-dev.md).

**note:** For the architecture-neutral shared setup (SLAS client, session bridging, third-party IDP, Business Manager configuration, and Plugin SLAS removal), see [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md). For the PWA Kit and SFRA/SiteGenesis implementation paths, see [Hybrid Authentication Overview](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-authentication.md).

## Hybrid Authentication Benefits

Hybrid Auth provides key advantages for implementing storefronts alongside traditional SFRA or SiteGenesis pages.

### Platform-Native Data Synchronization

Launch faster with out-of-the-box authentication, ensuring automatic data synchronization between SFRA and Storefront Next pages.

### Seamless Shopper Experience

Shoppers can navigate across your hybrid site with no disruption or loss of data. Synchronization is expanded to include Shopper Context session attributes and support for consistent analytics.

### Full Support for All Templates

Whether you're using SiteGenesis or SFRA, we have you covered with a fully supported and productized solution to ease your path to Storefront Next success.

## Supported Configurations

B2C Commerce version 25.6 Hybrid Auth support includes:

- Storefront Next
- SLAS public and private clients
- SFRA and SiteGenesis templates
- Third-party IDP login with SLAS:
  - Configure third-party IDP logins by using SLAS, not Business Manager.
  - Perform all third-party IDP interactions by using SLAS.
  - SFRA third-party IDP logins are only supported when using SLAS.

## Set Up a Hybrid Storefront with Storefront Next

### Step 1: Set Up Your Storefront with Hybrid Auth

Before you configure Storefront Next, complete the [Shared Hybrid Auth Setup](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md). It covers the architecture-neutral configuration that every hybrid storefront needs:

- Set up a SLAS client (public or private) and add the `sfcc.session_bridge` scope for session bridging. Use the same client ID in Hybrid Auth and in your Storefront Next application. See [Shared Hybrid Auth Setup, Steps 1–2](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-1-set-up-a-slas-client).
- (Optional) Configure third-party IDP and Social Login with SLAS, not Business Manager. The IDP name in the SLAS Admin configuration is case sensitive and must match the OAuth Provider ID in SFRA/SiteGenesis. See [Shared Hybrid Auth Setup, Step 3](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-3-optional-configure-third-party-idp-and-social-login).
- Configure Business Manager: enable the **Hybrid Auth** toggle, enter your SLAS client ID (select **Is Public Client** for a public client, or enter the client secret for a private client), and set optional features as needed—**Shopper Context**, **Do-Not-Track Synchronization**, **HTTPOnly True**, guest and registered refresh token TTL overrides, and the cookie domain level. Then enforce HTTPS. See [Shared Hybrid Auth Setup, Step 4](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-4-configure-business-manager).
- Remove Plugin SLAS from the cartridge path if you previously used it, and review any Plugin SLAS-specific code customizations. Make sure no custom cartridge code calls session bridging endpoints; Hybrid Auth handles session bridging for you. See [Shared Hybrid Auth Setup, Step 5](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-auth-shared-setup.md#step-5-remove-plugin-slas-if-migrating).

**note:** If you used [Storefront Next Automated Setup](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/hybrid-auth-quick-start.md), the SLAS client is already configured. Skip creating a SLAS client, and just confirm that it includes the `sfcc.session_bridge` scope. Complete the SLAS client setup only if you set up your storefront manually.

Then configure the Storefront Next-specific routing and application settings:

1. For Storefront Next: Set up Embedded Content Delivery Network (eCDN) origin rules:

   - Configure the embedded content delivery network (eCDN) to send page requests at the top of the funnel to the Storefront Next: home page (`/`), the category listing page (`/category`), and the product details page (`/product`). These pages are deployed to a Managed Runtime (MRT) environment running on mystorefront.mobify-storefront.com. When the shopper decides to make a purchase, the eCDN redirects the shopper to the existing SFRA/SG checkout page running on `www.mystorefront.com`.
   - To compare route split patterns, see [Choose a Hybrid Routing Matrix](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-hybrid-routing-matrix.md).
   - To configure eCDN routing rules in the Business Manager UI (recommended), see [CDN Routing Rules for Hybrid Implementations](https://developer.salesforce.com/docs/commerce/commerce-api/guide/ecdn-rules-for-phased-headless-rollout.html). To automate or script rule management instead, use the CDN Zones API documented in the same guide.
     - Provide these values for new rules:
       - **Rule Name**: Any name that helps you identify that this ruleset is for hybrid storefronts. A storefront can have more than one ruleset.
       - **Enable Rule Once Saved**: Select this checkbox to immediately apply the ruleset when you click **Save**.
       - **Hostnames**: Click **Select Hostnames** and select the hostname for your hybrid storefront.
       - **MRT Origin**: Your MRT storefront domain, which you can find in **Environment Settings** in Runtime Admin.
       - **Rule Expression**: Your origin ruleset.

   **note:** For hybrid storefronts with Storefront Next, always include `/resource/auth/.*` and `^/action/.*` paths to your eCDN rule expression to route all requests to server resources and actions to Storefront Next on MRT.

   - For more information about routing traffic to MRT, see:

     - [TLS Certificates](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#3-tls-certificates)
     - [DNS CNAME](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#4-dns-cname)
     - [Configure Your Environment](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/launching-your-storefront.html#5-configure-your-environment)

2. For Storefront Next: Update Storefront Next configuration.

   **note:** This guide assumes that you've already set up a Storefront Next application. If you haven't created a Storefront Next application yet, complete the initial setup before proceeding with hybrid configuration.

   To enable hybrid mode in your Storefront Next application, update your `config.server.ts` file to set `hybrid.enabled: true` and specify which routes to redirect to SFRA/SiteGenesis using `legacyRoutes`:

   ```typescript
   site: {
       hybrid: {
           enabled: true,
           legacyRoutes: [
               '/cart',
               '/checkout',
               '/checkout/:confirmationId',
           ],
       },
   }
   ```

   **Configuration options:**

   - **`enabled`**: Set to `true` to enable hybrid mode. This setting allows your Storefront Next application to coexist with SFRA/SiteGenesis pages.
   - **`legacyRoutes`**: An array of route patterns to redirect to SFRA/SiteGenesis instead of being handled by Storefront Next.

   **Route parameterization:**

   The `legacyRoutes` configuration supports parameterization using React Router syntax:

   - **Exact path matches**: `/checkout`, `/cart` — Matches only the exact path
   - **Dynamic segments**: `/checkout/:confirmationId`, `/product/:id` — The `:parameter` syntax matches any value in that segment
   - **Multiple parameters**: `/category/:categoryId/item/:itemId` — Supports multiple dynamic segments in a single route

   Any request matching a pattern in `legacyRoutes` is redirected to the corresponding SFRA/SiteGenesis page, maintaining the full URL path and query parameters.

   **note:** Update the configuration directly in `config.server.ts` or use environment variable overrides for per-environment customization. To override via environment variables:

   ```bash
   PUBLIC__app__hybrid__enabled=true
   PUBLIC__app__hybrid__legacyRoutes=["/cart","/checkout","/checkout/:confirmationId"]
   ```

   For more information about configuration options and environment variable overrides, see [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md).

### Required Route Patterns

Include these patterns so React Router server endpoints continue to work.

| Pattern        | Required for                          |
| -------------- | ------------------------------------- |
| `^/resource.*` | React Router resource routes          |
| `^/action/.*`  | React Router actions                  |
| `.*\.data.*`   | Production parity in shared rule sets |

### Page Route Patterns (Optional)

Add patterns for Storefront Next pages that your team has already migrated.

| Pattern               | Route                  |
| --------------------- | ---------------------- |
| `^/$`                 | Homepage               |
| `^/login.*`           | Login page             |
| `^/logout.*`          | Logout                 |
| `^/signup.*`          | Registration           |
| `^/reset-password.*`  | Password reset         |
| `^/account.*`         | Account pages          |
| `^/product.*`         | Product detail pages   |
| `^/category.*`        | Category and PLP pages |
| `^/search.*`          | Search results         |
| `^/social-callback.*` | Social login callback  |

### Full Rule Set Example

This example keeps homepage, auth, product, category, search, account, and server endpoints on Storefront Next.

```bash
HYBRID_ROUTING_RULES='(http.request.uri.path matches "^/$" or http.request.uri.path matches "^/reset-password.*" or http.request.uri.path matches "^/signup.*" or http.request.uri.path matches "^/logout.*" or http.request.uri.path matches "^/login.*" or http.request.uri.path matches "^/category.*" or http.request.uri.path matches "^/product.*" or http.request.uri.path matches "^/search.*" or http.request.uri.path matches "^/account.*" or http.request.uri.path matches "^/social-callback.*" or http.request.uri.path matches "^/resource.*" or http.request.uri.path matches "^/action/.*" or http.request.uri.path matches ".*\\.data.*")'
```

### Step 2: Configure Basket Management for Hybrid Auth

Storefront Next implements merging basket on Shopper Login. The B2C Commerce platform provides a default, out-of-the-box implementation for merging baskets. Some customers need further customization and can use the sample implementation in [Github GIST](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f), which behaves like the default implementation, making it an ideal starting point for customization.

After a guest shopper logs in as a registered shopper, manage the shopper basket with the `dw.order.mergeBasket` hook (added in B2C Commerce version 25.10). Invoke this merge hook using either of these options:

- With a REST API call for headless storefronts
- Within the controller logic for non-headless storefronts

After invoking the hook, verify that the guest shopper's basket is appropriately combined with the registered shopper's basket.

### Hook Invocation Using REST API

When you use the `transferBasket` endpoint with the parameter `merge=true`, the guest basket is transferred and becomes the current basket. The `dw.order.mergeBasket` hook is then invoked, merging the registered shopper's basket into the current basket. This API behavior is described in the [`transferBasket`](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-baskets-v2?meta=transferBasket) specification.

### Hook Invocation With Custom Controller Implementation

To add the basket merge hook into an existing controller, use the [Script API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html) to transfer the basket from the guest shopper to the registered shopper by calling `BasketMgr.getCurrentBasket()`. Personal information, such as payment/address information, is removed from the guest basket, and it becomes the current basket. Invoke the `dw.order.mergeBasket` hook to process the merge ensuring a seamless and consistent shopper experience. Use `BasketMgr.getStoredBasket()` to access the registered shopper's basket, which is deleted when the request ends.

For example: to add the basket merge hook for `Account-Login`, append the merge handling to the login function. The [Github GIST](https://gist.github.com/sf-thomas-loesche/3446c7d71a97e559bf1caee96ae56d9f) contains a detailed explanation of how to accomplish this, but the following example provides a quick summary of how baskets can be obtained and merged using Script API with the `dw.order.mergeBasket` hook:

```javascript
// the (transferred) basket from the previous guest shopper
var currentBasket = BasketMgr.getCurrentBasket();

// the basket from the registered shopper which was attached before the login (will be deleted when request ends)
var storedBasket = BasketMgr.getStoredBasket();

if (storedBasket && currentBasket) {
  dw.system.HookMgr.callHook("dw.order.mergeBasket", "mergeBasket", storedBasket, currentBasket);
}
```

For basket best practices in a hybrid implementation, see [Hybrid Storefront Basket Guidance](https://developer.salesforce.com/docs/commerce/commerce-api/guides/hybrid-storefront-baskets.md#hybrid-storefront-best-practices-for-working-with-baskets).

### Step 3: (Optional) Set Shopper Context for Hybrid Auth

For Hybrid Auth, we recommend the use of [Shopper Context](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary) to drive geolocation-based personalizations for:

- Promotions and other experiences based on `request.geolocation.*` attributes in Customer Groups
- Region-specific content based on client IP

To maintain consistency across a hybrid storefront, use the same geolocation for both SCAPI and controller calls:

- Call Shopper Context with the `clientIp`.
- Set the `evaluateContextWithClientIp` query parameter to `true`. Set `&evaluateContextWithClientIp=true` for the IP-related context features to work correctly.
- For example:

  ```http
    PUT https://<shortCode>.api.commercecloud.salesforce.com/shopper/shopper-context
    /v1/organizations/f_ecom_<tenantId>/shopper-context/<usid>
    ?siteId=<siteId>&evaluateContextWithClientIp=true

    {
        "clientIp":"73.4.153.145"
    }
  ```

For additional details, see:

- [Shopper Context Guides](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html)
- [Shopper Context API Docs](https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-context?meta=Summary)
- [Shopper Context Script API](https://salesforcecommercecloud.github.io/b2c-dev-doc/docs/current/scriptapi/html/index.html) You can use the Shopper Context Script API to personalize shopper experiences for hybrid implementations that use SFRA/SiteGenesis pages.

### Step 4: (Optional) Enable or Disable Do Not Track Synchronization

To enable or disable DNT synchronization in Business Manager, navigate to **Merchant Tools > Select Site > Site Preferences > Hybrid Auth Settings**.

SFRA-only sites: The DNT value is automatically synchronized to the extended session, providing a seamless experience across sessions.

SFRA and Storefront Next hybrid implementations: When you enable both Hybrid Auth and DNT synchronization, the tracking consent provided by a shopper on one site is automatically synchronized with the other site. For example, in a hybrid site where the home page runs on Storefront Next and the cart page runs on SFRA:

- On the home page (Storefront Next), the shopper is presented with a consent form and provides their tracking preference.
- When the shopper navigates to the cart page (SFRA), the DNT value from Storefront Next is synchronized with SFRA.
- As a result, the SFRA cart page doesn't prompt the shopper for tracking consent again.

**note:** Tracking consent is enabled by default in Storefront Next. You can manage tracking consent settings in `config.server.ts`:

```typescript
engagement: {
    analytics: {
        trackingConsent: {
            enabled: true,
            defaultTrackingConsent: TrackingConsent.Declined,
            position: 'bottom-right',
        },
    },
}
```

Configuration options:

- **`enabled`**: Set to `true` to enable tracking consent prompts (enabled by default).
- **`defaultTrackingConsent`**: Default consent state — `TrackingConsent.Declined` (default) or `TrackingConsent.Accepted`.
- **`position`**: Position of the consent banner — options include `'bottom-right'`, `'bottom-left'`, `'top-right'`, `'top-left'`.

For more information about configuration options, see [Project Configuration](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-project-config.md).

In this section:

- [Login and Registration Support for Hybrid Storefront Next Storefronts](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/sfnext-login-support-hybrid.md)

<!-- document id=5ada884b85653bdf936be584b95a03b6f6c4b202d90bce59cbdce567cbed678b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/sandboxes/b2c-manage-sb.md -->

# Use the Sandbox API to Manage On-Demand Sandboxes

Use the Sandbox API to create and manage on-demand sandboxes.

## Manage Sandboxes with the B2C Commerce CLI

The [B2C Commerce CLI](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md) wraps the Sandbox API with an easy-to-use workflow, so you can manage sandbox lifecycle from your terminal without writing raw API calls. To install the tool and authenticate, see [Agentic B2C Developer Toolkit](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/b2c-developer-tooling.md).

```bash
# Create a new on-demand sandbox in a realm and wait for it to be ready
b2c sandbox create --realm abcd --wait

# Create a larger sandbox with a 48-hour TTL and auto-scheduled start/stop
b2c sandbox create --realm abcd --profile large --ttl 48 --auto-scheduled

# List your sandboxes
b2c sandbox list

# Get sandbox details (including hostname and state)
b2c sandbox get <sandbox-id>

# Start, stop, or restart a sandbox
b2c sandbox start <sandbox-id>
b2c sandbox stop <sandbox-id>
b2c sandbox restart <sandbox-id>

# Reset a sandbox to a clean state
b2c sandbox reset <sandbox-id>

# Delete a sandbox when you're done
b2c sandbox delete <sandbox-id>
```

For the full command reference, see [Sandbox Commands](https://salesforcecommercecloud.github.io/b2c-developer-tooling/cli/sandbox.html) in the Agentic B2C Developer Toolkit documentation.

## Access the Sandbox API

Access documentation for the Sandbox API and issue API calls from the Sandbox API user interface.

The Sandbox API user interface is available here:

[https://admin.dx.commercecloud.salesforce.com/](https://admin.dx.commercecloud.salesforce.com/)

Click **Authorize** to log in with the API Client ID you configured using Account Manager.

For details about the API call, expand the API method and click the Model for each call. To issue an API call from the Sandbox API user interface, click **Try it out** for any method. Edit the Example Values in the request body and click **Execute**.

![Sandbox API user interface showing the Authorize button and expandable API methods with Model and Try it out options](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_api_model1.png)

## Get the On-Demand Sandbox ID

Many of the Sandbox API calls require you to provide a sandbox’s ID. Get the ID using the `GET/sandboxes` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Sandboxes section of the Sandbox API user interface, click to expand the `GET/sandboxes` method.

6.  From the include_deleted dropdown menu, select **true** to include deleted sandboxes in the list of sandboxes returned.

7.  In the filter_params field, specify criteria to narrow the sandbox results. This table lists the supported filter values:

    **note:** If no filter parameters are provided, the API returns all matching sandboxes. The realm filter only shows sandboxes from realms you can access.

    | Filter Name       | Description                                                                                                                                 | Example                  |
    | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
    | `realm`           | Filter sandboxes by realm name (case-insensitive).                                                                                          | `realm=zzzt`             |
    | `state`           | Filter sandboxes by their current state. Possible values are: `deleted`, `failed`, `new`, `started`, `stopped`, `unknown`, and `upgrading`. | `state=started`          |
    | `resourceProfile` | Filter sandboxes by resource profile.                                                                                                       | `resourceProfile=medium` |
    | `createdBy`       | Filter sandboxes by the user who created them.                                                                                              | `createdBy=user1`        |
    | `tags`            | Filter sandboxes by tags (comma-separated within square brackets).                                                                          | `tags=[tag1,tag2]`       |

    Examples:

    - Filter by realm and state: `realm=testrealm&state=active`
    - Filter by realm and resource profile: `realm=production&resourceProfile=large`
    - Filter by realm, state, resource profile, created by, and tags: `realm=testrealm&state=active&resourceProfile=medium&createdBy=admin&tags=[tag1,tag2]`

8.  Click **Try it out**.

9.  Click **Execute**.

    ![Sandbox API showing the GET/sandboxes method response listing available sandboxes with their IDs and states](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_get_sb.png)

## Assign Profiles to Define Sandbox Resources

Manage your sandboxes more efficiently by assigning resource profiles to them based on your needs. Resource profiles define the disk, CPU, and memory allocation for their assigned sandboxes.

Assigning resource profiles to sandboxes provides several benefits:

- Assign different size resource profiles to sandboxes according to your performance needs.
- Developers can more easily maintain sandbox content, ensuring that configuration is aligned with the production environment.
- When running automated tests, use the full data set.
- View sandbox usage information by profile using the `GET/realm/{realm}/usage` method.

Assign one of three discrete profiles to each on-demand sandbox. This table describes the settings for each resource profile:

| Resource Profile   | CPU & Memory Units | Storage | Running Cost (Credits/Minute) | Stopped Cost (Credits/Minute) |
| ------------------ | ------------------ | ------- | ----------------------------- | ----------------------------- |
| `medium` (Default) | 1                  | 10 GB   | 1                             | 0.3                           |
| `large`            | 2                  | 20 GB   | 2                             | 0.3                           |
| `xlarge`           | 4                  | 50 GB   | 4                             | 0.3                           |
| `xxlarge`          | 8                  | 100 GB  | 8                             | 0.3                           |

Define an on-demand sandbox with a resource profile using the `POST/sandboxes` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Sandboxes section of the Sandbox API user interface, click to expand the `POST/sandboxes` method.

6.  Click **Try it out**.

7.  In the request body, specify the desired resource profile.

8.  If you're using an Operation Scheduler to manage this sandbox, change the `autoScheduled` parameter to `true`.

9.  If applicable, enter values for OCAPI or WebDAV settings, or delete those sections of the request body.

10. Click **Execute**.

    ![Sandbox API showing the POST/sandboxes method with resource profile and autoScheduled parameters in the request body](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_res_prof_post_sandboxes_method.png)

## Check the Status of a Sandbox

To check a sandbox’s status use the `GET/sandboxes/{sandboxId}` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Sandboxes section of the Sandbox API user interface, click to expand the `GET/sandboxes/{sandboxId}` method.

6.  Click **Try it out**.

7.  Enter the sandbox ID.

8.  Click **Execute**.

    ![Sandbox API showing the GET/sandboxes/{sandboxId} response with the current status of the specified sandbox](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_get_status_with_value.png)

## Create an Operation Scheduler for On-Demand Sandboxes

Realm administrators can configure when to start and stop sandboxes to better manage on-demand sandbox usage. For example, with an Operation Scheduler, turn sandboxes on or off at specific times on specified weekdays.

When creating an Operation Scheduler, keep these considerations in mind:

- For the scheduler to manage an on-demand sandbox, you must set the sandbox `autoScheduled` parameter to `true`.
- Scheduler times use Zulu (Coordinated Universal Time) or Greenwich Mean Time (+offset) format.
- Default Operation Scheduler settings turn all auto-scheduled sandboxes on Monday through Friday at 08:00:00+03:00 and off on the same weekdays at 19:00:00Z.
- To turn off the scheduler, set the `startScheduler` and `stopScheduler` parameters to `null`. For example:

  ![JSON example showing startScheduler and stopScheduler parameters set to null to disable the Operation Scheduler](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_turn_off_scheduler.png)

Create an Operation Scheduler using the `PATCH/realms/{realm}/configuration` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  (Optional) In the Realms section of the Sandbox API user interface, click to expand the `PATCH/realms/{realm}/configuration` method.

6.  (Optional) In the Sandbox section of the Sandbox API user interface, click to expand the `POST/sandboxes` method.

7.  (Optional) To update an operation scheduled, In the Sandbox section of the Sandbox API user interface, click to expand the `PATCH /sandboxes/{sandboxId}` method.

8.  Click **Try it out**.

9.  In the request body, modify the `startScheduler` and `stopScheduler` weekdays and times to when you want to start and stop auto-scheduled sandboxes.

10. Specify the four-letter ID for the realm.

11. Click **Execute**.

    The API creates an Operation Scheduler that manages all sandboxes in the realm with their `autoScheduled` parameter set to `true`.![Realm PATCH method.](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_op_sched_patch_realm_method.png)

    ![Sandbox POST method.](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_sandbox_post.png)

    ![Sandbox PATCH method.](https://developer.salesforce.com/media/b2c-commerce/b2c_sandbox_sandbox_patch.png)

## Start, Stop, Reset (DBINIT), and Restart an On-Demand Sandbox

To stop, start, or reset (DBINIT) a sandbox, use the `POST/sandboxes/{sandboxId}/operations` method. Stopped sandboxes consume fewer credits than running sandboxes.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Sandboxes section of the Sandbox API user interface, click to expand the `POST/sandboxes/{sandboxId}/operations` method.

6.  Click **Try it out**.

7.  Edit the operation in the request body to specify what you want to do.

    - **start**: Makes a sandbox in a stopped state accessible again.
    - **stop**: Stops a sandbox.
    - **reset**: Refreshes a sandbox instance with a new database using the DBINIT process.
    - **restart**: Makes a sandbox that is in a stopped state accessible again. Stops an active sandbox and starts it again.

8.  Enter the sandbox ID.

9.  Click **Execute**.

    ![Sandbox API showing the POST/sandboxes/{sandboxId}/operations response after executing a start or stop operation](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_stop_start.png)

10. Check the status of the sandbox to make sure it has changed accordingly. See [Check the Status of a Sandbox](#check-the-status-of-a-sandbox).

## Allowlist On-Demand Sandbox IP Addresses

You currently don't have to allowlist On-Demand Sandbox IP addresses to gain access to them. However, you might need to allowlist On-Demand Sandbox IP addresses on other systems or firewalls to communicate with On-Demand Sandboxes.

When allowlisting sandbox IP addresses, keep the following in mind:

- We don't restrict sandbox outbound data. If your receiving systems reside within the same VPN or an unrestricted network,allowlisting the On-Demand Sandbox IP addresses is unnecessary.
- When allowlisting IP addresses for On-Demand Sandbox access, include all outboundIps and systemIps addresses to make sure the system can access them.

If you want to allowlist sandbox IP addresses on another system, get the IP addresses using the `GET/system` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Common section of the Sandbox API user interface, click to expand the `GET/system` method.

6.  Click **Try it out**.

7.  Click **Execute**.

    ![Sandbox API showing the GET/system response with outbound and system IP addresses for allowlisting](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_get_system_method.png)

8.  Use the retrieved outbound IP addresses when allowlisting addresses on an external system.

## Use an Alias for an On-Demand Sandbox

Test storefronts by reusing a hostname alias for multiple sandboxes, or create a hostname alias that is unique to one sandbox.

### Reuse a Hostname Alias

Reuse a hostname over multiple sandboxes by creating a non-unique alias and generating a registration link to access the sandbox.

Reuse a hostname alias to do local testing by accessing the sandbox without a proxy or CDN between the node and the sandbox. This option requires sending a cookie manually with every request or by using a registration link.

**note:** Before defining a sandbox alias, define a custom host name, such as `www.merchant.com`, in your site’s alias configuration under **Merchant Tools** > **SEO** > **Aliases**.

Define a reusable on-demand sandbox alias using the `POST /sandboxes/{sandboxId}/aliases` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Common section, click to expand the `GET/realms/{realm}/system` method.

6.  Click **Try it out**.

7.  Click **Execute**.

    ![Sandbox API showing the GET/realms/{realm}/system response with system IP addresses for hostname alias configuration](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_get_system_method.png)

    The results contain one or more string values. These values appear as IP addresses surrounded by quotation marks, for example, "3.210.241.243".

8.  Copy a string value under `systemIps` and add it, along with the custom hostname, to your local `hosts` file, for example, `3.210.241.243 www.merchant.com`. You need admin rights to edit this file.

9.  In the Sandboxes section of the Sandbox API user interface, click to expand the `GET /sandboxes` method

10. Click **Try it out**.

11. Click **Execute**.

    ![Sandbox API showing the GET/sandboxes method response with sandbox IDs available for alias assignment](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_get_sb_method.png)

12. From the results, copy the desired Sandbox ID.

13. In the Sandboxes section, click to expand the `POST /sandboxes/{sandboxId}/aliases` method

14. Click **Try it out**.

15. Register the hostname by editing the alias value (1), adding the hostname (2), and specifying the Sandbox ID copied (3).

    ![Sandbox API showing the POST/sandboxes/{sandboxId}/aliases method with hostname alias value and sandbox ID fields filled in](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_post_sb_hostname_aliases_method.png)

    **note:** The API payload supports a unique hostname parameter. Unless you explicitly set it, the unique parameter is assumed to be `false`. If you're using one hostname for multiple sandboxes, either omit the unique setting from the payload or specify a value of `false`.

    ```
    {
    "name": "www.merchant.com",
    "unique": false
    }
    ```

16. Click **Execute**.

    The call response generates a cookie and provides a registration URL.

17. Copy the registration URL from the call response, and paste the link into a browser.

    After a short time, the browser redirects to the sandbox alias where you can perform SEO testing.

#### What If I Don’t Use a Browser?

When testing REST APIs, you typically don’t use default browser access to a site. When using tools like Curl or Postman, you define a cookie header manually using the hostname and information that you obtain from the `GET /system` API response.

For example,

```
curl -X GET -k -H 'Cookies:
b2codds_df69b6df-a4fb-3e8b-ada3-d0ded26e9fe0=83f05593-6272-382f-be1c-bc8e5021a243'
'https://www.merchant.com/dw/shop/v20_1/products/foo'
```

### Use a Unique Host Name Alias

To use a unique hostname alias to access a sandbox, create or use an already existing DNS CNAME record that points to the sandbox origin, or create a unique hostname alias using the aliases API.

**note:** Creating or using an already existing DNS CNAME record provides a global, one-to-one mapping to the sandbox. For this option, you don’t need to use the aliases API.

If you choose to create a unique hostname alias using the aliases API, you must add a text record containing a unique `domainVerificationRecord` value to either the DNS sub- or root-domain. Unlike reusing a hostname alias, this option doesn't require using a registration link or any cookies.

**note:** Before defining a sandbox alias, define a custom host name, such as `www.merchant.com`, in your site’s alias configuration under **Merchant Tools** > **SEO** > **Aliases**.

Define a unique on-demand sandbox alias using the `POST /sandboxes/{sandboxId}/aliases` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  To test directly from any local system, add the string value, along with the custom hostname, as an address record, to your DNS subdomain or root domain. For example if your realm id is "abcd", your DNS Record will be:

    ```
    www.merchant.com CNAME abcd.dx.commercecloud.salesforce.com
    ```

6.  Click **Try it out**.

7.  Click **Execute**.

    ![Sandbox API showing the GET/realms/{realm}/system response with system IP addresses for unique hostname alias DNS configuration](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_get_system_method_2.png)

8.  From the results, copy the desired Sandbox ID.

9.  In the Sandboxes section of the Sandbox API user interface, click to expand the `POST /sandboxes/{sandboxId}/aliases` method

10. Click **Try it out**.

11. Register the hostname by editing the alias value (1), adding the hostname (2), and specifying the copied Sandbox ID (3), along with a uniqueness value of true.

    ```
    {
    "name": "www.merchant.com",
    "unique": true
    }
    ```

    ![Sandbox API showing the POST/sandboxes/{sandboxId}/aliases method with unique set to true for a one-to-one hostname alias](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_post_sb_hostname_aliases_unique_true.png)

12. Click **Execute**.

13. Using the `domainVerificationRecord` value from the response body, add a verification text record to either the DNS subdomain or root domain.

    ```
    www.merchant.com  TXT  "sfcc_verification_abcd=8ee12469a9f6cf17af34eea237595d53608475f8a04840f03c2434bbbd51288d"
    ```

    **note:** If your domain registrar doesn’t allow a TXT entry and a CNAME entry for the same subdomain, add the same text record entry to the root domain and subdomain. See, [RFC 1912–Common DNS Operational and Configuration Errors](https://datatracker.ietf.org/doc/html/rfc1912#section-2.4)

    ```
    dev.merchant.com 3600 IN CNAME abcd.dx.commercecloud.salesforce.com.@ 3600 IN TXT "sfcc_verification_abcd=8ee12469a9f6cf17af34eea237595d53608475f8a04840f03c2434bbbd51288d"
    ```

14. Use the hostname to access the sandbox alias directly and perform SEO testing.

## Automatically Generate a Domain Certificate

To automatically generate a certificate for your alias, set `requestLetsEncryptCertificate` to true . The generated certificate certifies the specific host used during alias creation. The certificate is required to show the storefront as secure. If you don’t generate a certificate, your storefront shows as insecure.

```
{
"name": "www.example.com",
"unique": true,
"requestLetsEncryptCertificate": true
}
```

![Sandbox API response showing automatic domain certificate generation with requestLetsEncryptCertificate set to true](https://developer.salesforce.com/media/b2c-commerce/b2c_sandbox_auto_gen_domain_cert.png)

**important:** ODS sets the certificate quota at 10 certificates generated per week. When you generate a certificate for my-sbx.production.domain.com you consume Let’s Encrypt quotas from production.domain.com. The quota count applies to any certificate issued, whether through ODS or any other internal tool.

Salesforce recommends that you familiarize yourself with the Let’s Encrypt policy.

## Delete an On-Demand Sandbox

To delete a sandbox, use the `DELETE/sandboxes/{sandboxId}` method. Save credits by deleting a sandbox when you don’t need it anymore.

**important:** When you delete a sandbox, it is permanently deleted. The sandbox and its data are no longer available.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  In the Sandboxes section of the Sandbox API user interface, click to expand the `POST/sandboxes/{sandboxId}` method.

6.  Click **Try it out**.

7.  Enter the sandbox ID.

8.  Click **Execute**.

    ![Sandbox API showing the DELETE/sandboxes/{sandboxId} method response confirming the sandbox deletion](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_delete_sb.png)

## Check On-Demand Sandbox Credits

To check the status of credits on the realm, use the `GET/realm/{realm}/usage` method. To check the status of credits for a specific sandbox, use the `GET/sandboxes/{sandboxId}/usage` method.

1.  To open the Sandbox API user interface, go to [B2C Commerce Sandbox API](https://admin.dx.commercecloud.salesforce.com/).

2.  Click **Authorize**.

3.  Enter the API client ID for the Sandbox API.

4.  To dismiss the authorization window and return to the Sandbox API user interface, click **Close**.

5.  To check the status of credits for the realm, click to expand the `GET/realm/{realm}/usage` method.

6.  Click **Try it out**.

7.  Enter the realm ID.

8.  Enter the begin and end date for the usage report.

9.  Click **Execute**.

    ![Sandbox API showing the GET/realm/{realm}/usage response with credit usage data for the realm](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_realm_usage.png)

10. To check the status of credits for a sandbox, click to expand the `GET/sandboxes/{sandboxId}/usage` method.

11. Click **Try it out**.

12. Enter the realm ID.

13. Enter the begin and end date for the usage report.

14. Click **Execute**.

    ![Sandbox API showing the GET/sandboxes/{sandboxId}/usage response with credit usage data for the specific sandbox](https://developer.salesforce.com/media/b2c-commerce/b2c_sandboxes_sb_usage.png)

## On-Demand Sandbox Email Notifications

The on-demand sandbox (ODS) platform sends an email notification when the following events happen.

- **The License has expired:** The on-demand sandbox platform sends an email notification when the following events happen.
- **Sandbox is about to expire (TTL):** When a TTL is defined for the sandbox, the ODS sends two notifications to the email addresses associated with the sandbox. The first notification is sent approximately 48 hours before the TTL expires. The second notification is sent approximately 24 hours before the TTL expires.
  The email addresses that receive the message are the email addresses associated with the Sandbox. If there are no email addresses associated with the Sandbox, the system uses the emails associated with the Realm.
- **Sandbox has expired (TTL):** When a TTL is defined for the sandbox and the TTL is expired, the on-demand sandbox sends an email notification and the sandbox is deleted.

  The email addresses that receive the message are the email addresses associated with the Sandbox. If there are no email addresses associated with the Sandbox, the system uses the emails associated with the Realm.

To receive email notifications of these events, you associate your email with your realm and sandboxes.

## Verify the Email Addresses Associated witha Realm and On-Demand Sandbox

Use the [B2C Commerce Developer Sandbox REST API](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api) to verify email addresses associated with your realm and ODS.

### Realm

To check if you have emails associated with your realm, use the [getRealmConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api?meta=getRealmConfiguration) GET endpoint. To update the associated email addresses, use the [patchRealmConfiguration](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api?meta=patchRealmConfiguration) PATCH endpoint.

### Sandbox

To check if you have emails associated with your ODS, use the [getSandbox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api?meta=getSandbox) GET endpoint. To update the associated email addresses use the [patchSandbox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api?meta=patchSandbox) PATCH endpoint. Define the emails during the creation of the sandbox as detailed in the [postSandbox](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ods-rest-api?meta=createSandbox) POST endpoint.

## Access On-Demand Sandbox Logs in Log Center

Salesforce B2C Commerce On-Demand Sandbox (ODS) logs are available in Log Center. This enhancement eliminates the need to use a separate URL to access ODS logs for the first-party instance of Log Center.

1. Start Log Center.

2. Select a region.

3. Select a realm, if you're unsure of your realm ID, ask your Account Executive (AE) or Customer Service manager (CMS) for assistance.

4. Click **Show filtered results**.

5. Select **Search > Current Search**.

6. Under Service Type, select **ecom** or **jwa**.

7. To view the ODS logs, from the Host dropdown, select a host.

<!-- document id=3dc9bba387c9ad8d70cb956899c3e0c5ac1b78e46a18e2a85cc71150cf7ca001 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/use-admin-api.md -->

# Use the SCAPI Admin APIs

This section contains guidance and information for specific APIs in the SCAPI Admin API family.

## Admin API Overview

The SCAPI Admin APIs enable backend operations, integrations, and automation for your B2C Commerce implementation. All Admin APIs require Account Manager authentication.

For the full, current list of Admin APIs and endpoint details, use the [B2C Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references).

## Authentication Prerequisites

Before using SCAPI Admin APIs, ensure you have:

1. **Account Manager credentials** - Set up through Account Manager in Business Manager
2. **Appropriate permissions** - Admin APIs require specific role-based permissions
3. **API client configuration** - Some Admin APIs require dedicated API client setup
4. **Base URL and organization ID** - Obtain from your Business Manager instance

For authentication setup details, see [Authorization](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization.html).

## Common Automation Scenarios

These scenarios are implementation patterns you can adapt. API capabilities and surfaces evolve over time, so always validate endpoint details against the [B2C Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references).

### Scenario 1: Automated Inventory Synchronization
**Goal:** Sync inventory levels from an external warehouse management system (WMS) to B2C Commerce

**Implementation:**
1. **Extract:** Retrieve inventory data from your WMS
2. **Transform:** Map WMS data to OCI inventory record format
3. **Load:** Use **Admin Inventory API** to bulk update availability
4. **Monitor:** Track sync status and handle errors

**Key APIs:** Admin Inventory

### Scenario 2: CDN Configuration Management
**Goal:** Automate CDN zone configuration across multiple environments

**Implementation:**
1. **Define:** Create CDN zone configuration templates
2. **Deploy:** Use **Admin CDN API** to create and configure zones
3. **Configure:** Set up WAF rules, SSL certificates, and cache policies
4. **Monitor:** Enable log forwarding for CDN analytics

**Key APIs:** Admin CDN

### Scenario 3: Product Catalog Updates
**Goal:** Automate daily product data synchronization from a Product Information Management (PIM) system

**Implementation:**
1. **Extract:** Get product updates from PIM system
2. **Validate:** Verify product data format and required fields
3. **Update:** Use **Admin Product API** to update product attributes, prices, and availability
4. **Verify:** Confirm updates through **Shopper Product API**

**Key APIs:** Admin Product, Admin Pricing, Admin Inventory

### Scenario 4: Customer Data Integration
**Goal:** Sync customer profiles between B2C Commerce and a Customer Data Platform (CDP)

**Implementation:**
1. **Identify changes:** Detect customer profile updates in either system
2. **Sync:** Use **Admin Customer API** for bulk updates or individual profile changes
3. **Reconcile:** Handle conflicts and maintain data consistency
4. **Audit:** Log all sync operations for compliance

**Key APIs:** Admin Customer

### Scenario 5: Multi-Site Configuration Deployment
**Goal:** Deploy consistent site settings across multiple B2C Commerce sites

**Implementation:**
1. **Define:** Create configuration templates for site preferences
2. **Deploy:** Use **Admin Site API** to apply settings across sites
3. **Validate:** Verify configurations through API calls
4. **Document:** Track configuration changes for audit purposes

**Key APIs:** Admin Site, Admin Configuration

## Additional Resources

- For ongoing API additions and changes, monitor the [Commerce API release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html).
- For Storefront Next operational context, see [Managed Runtime in Storefront Next](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-mrt-section.html).
- [CDN zones:](https://developer.salesforce.com/docs/commerce/commerce-api/guide/cdn-zones.html) Configure content delivery settings, including web application firewall (WAF) rules, and log forwarding, and also configure certificates.
- [Omnichannel Inventory (OCI):](https://developer.salesforce.com/docs/commerce/commerce-api/guide/inventory-impex-best-practices.html) Manage product inventory for products.
- The Shopper Login Admin API information is categorized as part of the Shopper APIs. For details, see [SLAS Admin.](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth-admin?meta=Summary)

## Next Steps

Use the following links to optimize your storefront's performance and security:

- [Test and Measure Your APIs](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html#test-and-measure-your-apis)
- [Security](https://developer.salesforce.com/docs/commerce/commerce-api/guide/security.html)

<!-- document id=1e38d3f852a4c619fdd0b681263cd7d03f787c7a3c91007a86c085fb23447aef url=/developer/current/en-us/commerce-cloud/commerce-api/guides/use-shopper-api.md -->

# Use the Shopper APIs

This section contains guidance and information for specific APIs in the Shopper API family.

For the full, current API list, use the [B2C Commerce API references](https://developer.salesforce.com/docs/commerce/commerce-api/references).

## Common Use Case Mappings

### Building a Product Listing Page (PLP)
1. **Shopper Search** - Get search results with filters and facets
2. **Shopper Products** - Retrieve product details for search results
3. **Shopper Context** - Apply customer-specific pricing/availability

### Building a Product Detail Page (PDP)
1. **Shopper Products** - Get product details, variations, images
2. **Shopper Promotions** - Show applicable promotions
3. **Shopper Baskets** - Enable add-to-cart functionality

### Building a Checkout Flow
1. **Shopper Login** - Authenticate customer or continue as guest
2. **Shopper Checkout (Baskets)** - Display cart contents and calculate totals
3. **Shopper Customers** - Retrieve/update shipping and billing addresses
4. **Shopper Checkout (Orders)** - Submit and confirm order

### Implementing Personalization
1. **Shopper Login** - Authenticate shopper
2. **Shopper Context** - Set customer groups, effective dates, source codes
3. **Shopper Products/Search** - Retrieve personalized results based on context

## Additional Resources

- For ongoing changes and newly added APIs, monitor the [Commerce API release notes](https://developer.salesforce.com/docs/commerce/commerce-api/references/about-commerce-api/about.html).
- For Storefront Next implementation guidance, see [Storefront Next Developer Guide](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-get-started-section.html) and [Login and Registration Support in Storefront Next](https://developer.salesforce.com/docs/commerce/sfnext/guide/sfnext-login-support.html).
- [Shopper Login (SLAS):](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html) Get tokens for interacting with B2C Commerce API and what is needed for different types of logins, such as logging in as an agent on behalf of a customer, logging in as a system on behalf of a customer, or merging shopper profiles between different login providers, for example: Facebook or Google.
- [Shopper Context:](https://developer.salesforce.com/docs/commerce/commerce-api/guide/shopper-context-api.html) Maintain a shopper’s state as the shopper navigates across the site, for example: set specific customer groups, specific source codes, or other things that would change the experience for the shopper.
- [Shopper SEO:](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-resolution.html) Allows headless implementations or customer implemented storefronts to determine whether a given URL should reference a product category or content asset.

## Next Steps

Use the following links to optimize your storefront's performance and security:

- [Shopper API Performance and Best Practices](https://developer.salesforce.com/docs/commerce/commerce-api/guide/performance.html)
- [Security](https://developer.salesforce.com/docs/commerce/commerce-api/guide/security.html)

<!-- document id=feb217e49f501ccdffa7dc72793b41d42d9dbf6c3eadbf46cda8d2c413b1f6fd url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/d2c-commerce/b2b-b2c-comm-checkout-checkoutsavable.md -->

# UseCheckoutComponent Interface

On the checkout page for a B2B or B2C store created with an LWR template, child checkout components implement the `useCheckoutComponent` mixin interface.

The component API is used to create custom components that integrate with the checkout process of form validation and the synchronization of external API validations.

```javascript
/**
 * Applies mixin for base class for any checkout dedicated building block.
 *
 * example:
 * export default class MyCheckoutInput extends useCheckoutComponent(LightningElement) {
 *     setAspect(newAspect: CheckoutContainerAspect): void {
 *         console.log(`dbb newAspect`, JSON.stringify(newAspect));
 *     }
 *     private handleButton(): void {
 *         this.dispatchCommit();
 *     }
 * }
 */
 export function useCheckoutComponent(
    superclass: Constructor<LightningElement>
): Constructor<LightningElement & CheckoutComponent>;
```

This component API adds these helper methods to a LightningElement.

```javascript
/**
 * interface implemented by CheckoutComponentMixin
 * and required to exist for CheckoutContainerMixin
 */
export interface CheckoutComponent extends CheckoutComponentHandlers {
  /**
   * notify the container the child component has modified data to put in the form store
   * the container should start 'dirty form' processing:
   * - optionally stageAction on this and other components
   * - save form store data to the server
   * - report errors
   */
  dispatchCommit(): void;
  /**
   * notify the DataProvider to update the form with the supplied changes.
   * the DataProvider catches updateForm errors so components do not need to.
   * unlike most dispatch functions this one is awaitable.
   */
  dispatchUpdateAsync(formRequest: CheckoutFormRequest): Promise<void>;
  /**
   * specialized version of dispatchUpdateAsync for setting client side errors.
   * note: this will never reject or throw, so it's safe not to await if circumstances permit
   */
  dispatchUpdateErrorAsync(errorRequest: CheckoutException): Promise<void>;
  /**
   * notify the DataProvider to start 'final' processing (the place order button pressed)
   * returns a Promise to facilitate advanced payment integrations.
   */
  dispatchFinalizeAsync(): Promise<void>;
  /**
   * notify the DataProvider to call place order API
   * unlike most dispatch fns this one is awaitable.
   */
  dispatchPlaceOrderAsync(): Promise<OrderConfirmation>;
  /**
   * ask our container to change our display such as put us in summary mode
   */
  dispatchRequestAspect(desiredAspect: CheckoutContainerAspectRequest): void;
}
```

The component API also adds these default implementations for container-initiated actions. The component designer can override these implementations as needed.

```javascript
/**
 * ComponentRegistration delegates CheckoutContainerSubscriptionPayload to these handlers in the derived component implementation
 */
export interface CheckoutComponentHandlers {
    /**
     * called on connect. derived classes should expose this key the DOM
     * if DOM ordering of container children is needed.
     * container classes combine a DOM query with sortSubscribers to break
     * through the otherwise opaque CheckoutComponentReference.
     * e.g. this.setAttribute('data-checkout-domkey', suggestedDomKey)
     */
    setDomKey(suggestedDomKey: string): string;
    /**
     * display hints from container such as summary mode, stencil, etc.
     * @param newAspect update checkout mode and stage
     */
    setAspect(newAspect: CheckoutContainerAspect): void;
    /**
     * derived class must implement REPORT_VALIDITY_SAVE calls reportValidity if defined.
     * derived class must implement CHECK_VALIDITY_UPDATE or do equivalent before dispatchCommit.
     * unsummarize if an error encountered to ensure it is seen
     *
     * aside: this subsumes all of CheckoutSavable's reportValidity, checkValidity, checkoutSave, placeOrder
     *
     * @param _checkoutStage used to synchronize processing and responses across components
     * @returns a Promise that resolves false if processing should be blocked
     *          should always return true if uninterested in a stage.
     */
    stageAction(checkoutStage: CheckoutStage): Promise<boolean>;
```

## Checkout Stages

These are the currently defined checkout stages.

```javascript
/**
 * where in the linear steps of checkout process, affects stageAction/reportValidity responses
 * note: these are unordered, stageAction should only use equality checks.
 */
export enum CheckoutStage {
    // commit (user edit) stages that lead to form save (checkout API update)
    //
    // CHECK_VALIDITY_UPDATE may skip update if component updates itself on each change before dispatchCommit
    CHECK_VALIDITY_UPDATE = 'CHECK_VALIDITY_UPDATE',
    REPORT_VALIDITY_SAVE = 'REPORT_VALIDITY_SAVE',
    // finalize stages that lead to place order
    BEFORE_PAYMENT = 'BEFORE_PAYMENT',
    PAYMENT = 'PAYMENT',
    BEFORE_PLACE_ORDER = 'BEFORE_PLACE_ORDER',
    PLACE_ORDER = 'PLACE_ORDER',
}
```

## Aspect Type Definitions

These aspect type definitions are referenced by the helper methods.

```javascript
/**
 * Used for nested checkout containers to specify how they are displayed
 */
export type CheckoutContainerAspect = {
  /**
   * truthy indicates DP is initializing, preparing for the place order step,
   * or reached an unrecoverable error.
   * input controls should render as readonly
   *
   * WARNING! when disabled or readonly lightning-input.reportValidity always
   *          returns true; therefore, defer setting controls to read-only
   *          unless they pass checkValidity.
   *          Otherwise they break stageAction(REPORT_VALIDITY_SAVE)
   */
  readOnlyIfValid: boolean,
  /**
   * truthy indicates expandable child sections should show as collapsed
   * typically this indicates the section is in a future accordion step, or in
   * a past or future subway step.
   */
  collapse: boolean,
  /**
   * truthy indicates summarizable components should render as summarized
   *
   * component may ignore summary: true requests, and if needed respond
   * with dispatchRequestAspect(false) to ask their containers to become unsummarized;
   * useful because errors are not typically rendered nor fixable in
   * summarized components.
   */
  summary: boolean,
};
/**
 * Used by components to ask their container to change how they are displayed
 */
export type CheckoutContainerAspectRequest = {
  /**
   * true container should enter summary mode, false should leave it
   * Children inform containers they can be summarized.
   */
  summarizable: boolean,
  /**
   * if truthy there are no options and summarized container can hide edit button
   */
  uneditable?: boolean,
};
```

## Checkout Data Provider with Form Data

The checkout data provider is used to access checkout session API data and local, not-yet-persisted form changes. The data provider `Checkout.Details` publishes an object of type `CheckoutFormOverlay`.

```javascript
/**
 * holds current state of checkout from the checkout api overlayed with
 * with unpersisted client side changes and related meta-data.
 */
export type CheckoutFormOverlay = CheckoutInformation & {
  /**
   * captured billing details
   */
  billingInfo?: CheckoutBillingInfo,
  /**
   * captured client side exceptions
   */
  notifications?: FormNotification[],
  /**
   * computed meta information about the overlay
   */
  formStatus?: CheckoutFormStatus,
};
/**
 * billing information that is not necessarily represented
 * in the checkout session
 */
export type CheckoutBillingInfo = {
  address?: Address,
  email?: string,
};
/**
 * computed meta information about the form like is
 * there data that should be saved
 */
export type CheckoutFormStatus = CheckoutFormActivity & {
  /**
   * true if persistForm should be called
   * does not  account for inconguent data, billing info, etc.
   * cleared by persistForm (sometimes) and revertForm
   */
  dirty: boolean,
  /**
   * true if some data typically saved by persistForm is incomplete
   * for example only some of the fields required to save
   * contactInfo have been set.
   * promoted (cleared) to dirty (set) when updateform gets missing data.
   * cleared by revertForm
   */
  incongruent: boolean,
  /**
   * indicates if billingInfo.address explicitly set
   */
  useShippingAddressForBilling: boolean,
};
/**
 * used to add and remove client side notifications returned in the overlay.
 * note: overlay's server side errors are not affected by adding or removing these.
 * note: new client side notifications are appended to the overlay array
 */
export type FormNotification = {
  /**
   * unique ID used to clear all client notifications added in previous requests that
   * had the same groupId.
   */
  groupId: string,
  /**
   * pass a unique type that can control where in the UI the exception renders.
   */
  type?: RequestErrorType,
  /**
   * the l10n string to display in the UI as the notification body.
   * when detail falsey clear all client side set exceptions of this groupId.
   */
  detail?: string,
  /**
   * optional unique error class identifier which can be used to further customize
   * the notification.
   *
   * Examples are the Error.name (PaymentAuthorizationError)
   * or Error.message (CheckoutError.NO_DELIVERY_ADDRESSES)
   */
  code?: string,
};
```

## Updating Checkout Form Data

The checkout data provider published data is updated using the provided component API `dispatchUpdateAsync`. It accepts an object of type `CheckoutFormRequest` with the list of fields to update.

```javascript
/**
 * used by components to update the unpersisted client side data.
 * assumes all contents are "validated" with checkValidity
 */
export type CheckoutFormRequest = {
  /**
   * caller short hand for deliveryGroups.items[0]
   */
  defaultDeliveryGroup?: CheckoutFormRequestDeliveryGroup,
  contactInfo?: ContactInfo,
  billingInfo?: {
    /**
     * in FormRequest send null to revert to useShippingAddressForBilling
     */
    address?: Address | null,
    email?: string,
  },
  notifications?: FormNotification[],
};
/**
 * selectable fields of a DeliveryGroup
 */
export type CheckoutFormRequestDeliveryGroup = {
  /**
   * notice changing the deliveryAddress results in all existing
   * availableDeliveryMethods and any selectedDeliveryMethod (even
   * an explictly set one) to be removed from the overlay until the
   * new deliveryAddress is saved.
   */
  deliveryAddress?: Address,
  desiredDeliveryDate?: string,
  shippingInstructions?: string,
  /**
   * in FormRequest send null to revert to existing selection
   *
   * notice an invalid (or no longer valid) delivery method selection
   * is ignored (the xisting selection (if any) shows in the overlay
   *
   * notice that by default changing the deliveryAddress will not
   * clear any explicitly set selectedDeliveryMethodId.  if a caller
   * wants to reset to the default (cheapest) delivery method when
   * changing addresses they must also explicitly clear any previous
   * selectedDeliveryMethodId setting.
   */
  selectedDeliveryMethodId?: string | null,
};
```

<!-- document id=1dc8b7ee4f32fdd1f14e529c206f3528877f72c6bfb9734a360bde4d5321c4ac url=/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/users.md -->

Users

# Users

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/users/users-oas-v1-public.yaml)

## API Overview

The Users API provides endpoints for managing Business Manager users and their access keys within Salesforce Commerce Cloud.

### Overview

This API allows administrators to create, retrieve, update, and delete users. It also supports managing access keys for users, retrieving password expiration information, and changing user passwords.

### Key Features

*   **User Management**: Create, retrieve, update, and delete Business Manager users
*   **Access Key Management**: Create, retrieve, enable/disable, and delete access keys for users
*   **Password Management**: Retrieve password expiration information and change passwords
*   **User Listing**: Retrieve all users with no filtering

### Access Key Scopes

Access keys can be created for the following scopes:

*   `WEBDAV_AND_STUDIO`: Access for WebDAV and Studio operations
*   `AGENT_USER_AND_OCAPI`: Access for Agent User and OCAPI operations
*   `STOREFRONT`: Access for storefront operations

### Use Cases

*   **Provisioning**: Create and configure Business Manager users programmatically
*   **Key Rotation**: Manage access keys for automated integrations
*   **Security Auditing**: Review user accounts and their access configurations
*   **Password Policies**: Monitor password expiration and enforce password changes

### Authentication

This API requires OAuth 2.0 authentication with the appropriate scopes:

*   `sfcc.users` - Read access to user resources
*   `sfcc.users.rw` - Read and write access to user resources

### Best Practices

1.  Use access keys instead of passwords for automated integrations
2.  Regularly rotate access keys for security
3.  Monitor password expiration dates and enforce timely password changes
4.  Use the PATCH endpoint for partial updates instead of PUT for full overwrites
5.  Only externally managed users can have access keys

**Version:** 1.0.0

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/merchant/users/v1`
    *   `shortCode (default 123456gf)`

## Security

*   `AmOAuth2` (oauth2) OAuth 2.0 security scheme for Admin API access using Account Manager. Requires appropriate scopes for user management operations.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dw/oauth2/access\_token)
    *   Scope sfcc.users: Read access to user resources
    *   Scope sfcc.users.rw: Read and write access to user resources

## Operations

### GET Get Users

`GET /organizations/{organizationId}/users`

Operation ID: `getUsers`. Security: AmOAuth2 (sfcc.users, sfcc.users.rw).

Retrieves all users with no filtering.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `select` (query, Select)
    
    _Example: select_
    
    ```
    (**)
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 25.  
    Default: `25`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Returns the collection of users
    
    Media type: `application/json`. Schema: `UserSearch`.
    
    _Example: UserSearchResponse_ User collection
    
    Example of a user search response with `select=(**)`.
    
    ```
    {
      "limit": 3,
      "offset": 0,
      "total": 3,
      "data": [
        {
          "login": "admin-user",
          "email": "admin@example.com",
          "firstName": "John",
          "lastName": "Doe",
          "externalId": "ext-12345",
          "disabled": false,
          "locked": false,
          "lastLoginDate": "2024-10-14",
          "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
          "passwordModificationDate": "2024-10-14T10:00:00.000Z",
          "preferredDataLocale": "en-US",
          "preferredUiLocale": "en-US",
          "roles": [
            "Administrator"
          ]
        },
        {
          "login": "editor-user",
          "email": "editor@example.com",
          "firstName": "Jane",
          "lastName": "Smith",
          "externalId": "ext-67890",
          "disabled": false,
          "locked": false,
          "lastLoginDate": "2024-10-13",
          "passwordExpirationDate": "2025-01-13T00:00:00.000Z",
          "passwordModificationDate": "2024-10-13T08:00:00.000Z",
          "preferredDataLocale": "en-US",
          "preferredUiLocale": "en-US",
          "roles": [
            "ContentEditor"
          ]
        },
        {
          "login": "manager-user",
          "email": "manager@example.com",
          "firstName": "Bob",
          "lastName": "Wilson",
          "externalId": "ext-11111",
          "disabled": true,
          "locked": false,
          "lastLoginDate": "2024-09-01",
          "passwordExpirationDate": "2024-12-01T00:00:00.000Z",
          "passwordModificationDate": "2024-09-01T07:00:00.000Z",
          "preferredDataLocale": "default",
          "preferredUiLocale": "default",
          "roles": [
            "CustomManager"
          ]
        }
      ]
    }
    ```
    

### GET Get User

`GET /organizations/{organizationId}/users/{login}`

Operation ID: `getUser`. Security: AmOAuth2 (sfcc.users, sfcc.users.rw).

Retrieves a single user by their login.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `login` (path, string, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.

#### Responses

*   **200** Returns the user details
    
    Media type: `application/json`. Schema: `User`.
    
    _Example: UserDetails_ Single user details
    
    Example of a successful retrieval of a single user
    
    ```
    {
      "login": "admin-user",
      "email": "admin@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "externalId": "ext-12345",
      "disabled": false,
      "locked": false,
      "lastLoginDate": "2024-10-14",
      "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
      "passwordModificationDate": "2024-10-14T10:00:00.000Z",
      "preferredDataLocale": "en-US",
      "preferredUiLocale": "en-US",
      "roles": [
        "Administrator"
      ]
    }
    ```
    
*   **404** User not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UserNotFound_ User not found
    
    Example of an error when the specified user does not exist
    
    ```
    {
      "title": "User Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/user-not-found",
      "detail": "No user with login 'nonexistent-user' could be found."
    }
    ```
    

### PUT Create or Replace User

`PUT /organizations/{organizationId}/users/{login}`

Operation ID: `createOrReplaceUser`. Security: AmOAuth2 (sfcc.users.rw).

Creates or overwrites a user. If a user with the given login already exists, the existing user will be overwritten. If no such login exists, a new user is created.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `login` (path, string, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.

#### Request body (required)

The user to create or replace

Media type: `application/json`. Schema: `User`.

_Example: CreateUser_ Create a user

Example of creating a new Business Manager user

```
{
  "login": "new-user",
  "email": "newuser@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "externalId": "ext-67890",
  "password": "SecurePassword123!",
  "preferredDataLocale": "en-US",
  "preferredUiLocale": "en-US"
}
```

#### Responses

*   **200** The user was successfully updated
    
    Media type: `application/json`. Schema: `User`.
    
    _Example: UserCreated_ Newly created user
    
    Example of a successfully created user
    
    ```
    {
      "login": "new-user",
      "email": "newuser@example.com",
      "firstName": "Jane",
      "lastName": "Smith",
      "externalId": "ext-67890",
      "disabled": false,
      "locked": false,
      "passwordExpirationDate": "2025-06-01T00:00:00.000Z",
      "passwordModificationDate": "2025-03-01T12:00:00.000Z",
      "preferredDataLocale": "en-US",
      "preferredUiLocale": "en-US",
      "roles": []
    }
    ```
    
*   **201** The user was successfully created
    
    Media type: `application/json`. Schema: `User`.
    
    _Example UserCreated: same as PUT /organizations/{organizationId}/users/{login} 200 response._ Newly created user
    
    Example of a successfully created user
    
    _Example: UserCreated_ Newly created user
    
    Example of a successfully created user
    
*   **400** Bad Request - Invalid user request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BadRequest_ Bad request
    
    Example of an error when a required field constraint is violated
    
    ```
    {
      "title": "Bad Request",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "An error occurred while decoding the request. There's a value constraint violation of property '$.email' in document 'User'."
    }
    ```
    
    _Example: IdConflict_ ID conflict
    
    Example of an error when the ID in the request body does not match the ID in the URL
    
    ```
    {
      "title": "Id Conflict",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/id-conflict",
      "detail": "The ID in the request body ('different-login') doesn't match the ID in the URL ('scapi-id-conflict-test')."
    }
    ```
    
    _Example: LocalUserCreation_ Local user creation not allowed
    
    Example of an error when creating a local user is not allowed with the current server settings
    
    ```
    {
      "title": "Local User Creation",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/local-user-creation",
      "detail": "The creation of a local Business Manager user isn't allowed with the current server settings."
    }
    ```
    
    _Example: PasswordPolicyViolation_ Password policy violation
    
    Example of an error when the password does not meet policy requirements
    
    ```
    {
      "title": "Password Policy Violation",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/password-policy-violation",
      "detail": "The provided new password doesn't meet the requirements."
    }
    ```
    

### DELETE Delete User

`DELETE /organizations/{organizationId}/users/{login}`

Operation ID: `deleteUser`. Security: AmOAuth2 (sfcc.users.rw).

Deletes a single user.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `login` (path, string, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.

#### Responses

*   **204** The user was successfully deleted
*   **404** User not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UserNotFound_ User not found
    
    Example of an error when the specified user does not exist
    
    ```
    {
      "title": "User Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/user-not-found",
      "detail": "No user with login 'nonexistent-user' could be found."
    }
    ```
    

### PATCH Update User

`PATCH /organizations/{organizationId}/users/{login}`

Operation ID: `updateUser`. Security: AmOAuth2 (sfcc.users.rw).

Updates a user. The locked flag and the user password cannot be updated with this resource.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the organization the request is being made by
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `login` (path, string, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.

#### Request body (required)

The user fields to update

Media type: `application/json`. Schema: `UserUpdateRequest`.

_Example: UpdateUser_ Update a user

Example of updating an existing user

```
{
  "email": "updated@example.com",
  "firstName": "Jane",
  "lastName": "Smith-Updated",
  "preferredDataLocale": "de-DE"
}
```

#### Responses

*   **200** The user was successfully updated
    
    Media type: `application/json`. Schema: `User`.
    
    _Example: UserUpdated_ Updated user
    
    Example of a successfully updated user
    
    ```
    {
      "login": "admin-user",
      "email": "updated@example.com",
      "firstName": "Jane",
      "lastName": "Smith-Updated",
      "externalId": "ext-12345",
      "disabled": false,
      "locked": false,
      "lastLoginDate": "2024-10-14",
      "passwordExpirationDate": "2025-01-14T00:00:00.000Z",
      "passwordModificationDate": "2024-10-14T10:00:00.000Z",
      "preferredDataLocale": "de-DE",
      "preferredUiLocale": "en-US",
      "roles": [
        "Administrator"
      ]
    }
    ```
    
*   **400** Bad Request - Invalid user update request
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example BadRequest: same as PUT /organizations/{organizationId}/users/{login} 400 response._ Bad request
    
    Example of an error when a required field constraint is violated
    
    _Example IdConflict: same as PUT /organizations/{organizationId}/users/{login} 400 response._ ID conflict
    
    Example of an error when the ID in the request body does not match the ID in the URL
    
    _Example: BadRequest_ Bad request
    
    Example of an error when a required field constraint is violated
    
    _Example: IdConflict_ ID conflict
    
    Example of an error when the ID in the request body does not match the ID in the URL
    
*   **404** User not found
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: UserNotFound_ User not found
    
    Example of an error when the specified user does not exist
    
    ```
    {
      "title": "User Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/user-not-found",
      "detail": "No user with login 'nonexistent-user' could be found."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the organization the request is being made by

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `f_ecom_zzxy_prd`.

### Select

The property selector declaring which fields are included into the response payload. You can specify a single field name, a comma-separated list of names or work with wildcards. You can also specify array operations and filter expressions. The actual selector value must be enclosed within parentheses. For more information, please read the documentation about property selectors [here](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-property-selection.html).

Type: `string`.

Minimum length: 1. Pattern: ^\[(\].\*\[)\]$. Example: `(name,id,variationAttributes.(**))`.

### UserSearch

Document representing a collection of users.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of User_, required) The collection of users.

### User

Document representing a user.

*   `login` (_string_, required) The login of the user.  
    Minimum length: 1. Maximum length: 256. Example: `admin-user`.
*   `password` (_string_) The password of the user.  
    Maximum length: 256. Example: `password`.
*   `email` (_string_, required) The email address of the user.  
    Maximum length: 256. Example: `admin@example.com`.
*   `firstName` (_string_) The first name of the user.  
    Maximum length: 256. Example: `John`.
*   `lastName` (_string_) The last name of the user.  
    Maximum length: 256. Example: `Doe`.
*   `externalId` (_string_) The external identifier for the user.  
    Maximum length: 256. Example: `ext-12345`.
*   `disabled` (_boolean_) Indicates whether the user is disabled.  
    Example: `false`.
*   `locked` (_boolean_) Indicates whether the user is locked.  
    Example: `false`.
*   `lastLoginDate` (_string (date)_) The date of the user's last login.  
    Example: `2024-10-14`.
*   `passwordExpirationDate` (_string (date-time)_) The date and time when the user's password expires.  
    Example: `2025-01-14T00:00:00.000Z`.
*   `passwordModificationDate` (_string (date-time)_) The date and time when the user's password was last modified.  
    Example: `2024-10-14T10:00:00.000Z`.
*   `preferredDataLocale` (_object_) The preferred data locale for the user.
    
    Includes all fields of `LocaleCode`.
    
*   `preferredUiLocale` (_object_) The preferred UI locale for the user.
    
    Includes all fields of `LocaleCode`.
    
*   `roles` (_array of string_) The list of role identifiers assigned to the user.  
    Items: Maximum length: 256. Example: `Administrator`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### UserUpdateRequest

Document representing a request to update a user. The locked flag and user password cannot be updated with this resource.

*   `email` (_string_) The email address of the user.  
    Maximum length: 256. Example: `updated@example.com`.
*   `firstName` (_string_) The first name of the user.  
    Maximum length: 256. Example: `Jane`.
*   `lastName` (_string_) The last name of the user.  
    Maximum length: 256. Example: `Smith-Updated`.
*   `externalId` (_string_) The external identifier for the user.  
    Maximum length: 256. Example: `ext-updated`.
*   `preferredDataLocale` (_object_) The preferred data locale for the user.
    
    Includes all fields of `LocaleCode`.
    
*   `preferredUiLocale` (_object_) The preferred UI locale for the user.
    
    Includes all fields of `LocaleCode`.
    

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

<!-- document id=17167f4ada3761942391817213ba8e6b6e29e9540fe321c06baba3313fe99086 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/isml/b2c-function-reference.md -->

# Utility Functions

B2C Commerce includes utility functions used frequently in templates.

## Object: dw.system.Request

Because you are working in a template, and templates use _request_ as a top-level variable, you can immediately call methods of this object.

**note:** Top-level variables include pdict, out, request and session.

The following are some frequently used methods. See the B2C Commerce Script API documentation for the complete documentation.

| Method                       | Description                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| getHttpCookies() : Cookies   | Returns the Cookies object, which can be used to manipulate the client-side cookies. |
| getHttpHeaders() : Map       | Returns a map containing all HTTP header values.                                     |
| isHttpSecure() : Boolean     | Identifies if the request is secure.                                                 |
| request.isSCAPI()  : Boolean | Distinguishes between OCAPI and SCAPI requests in extension points (hooks).          |

### Example

```
<td class="price merchandizetotal"><isprint value="${request.custom.Container.adjustedMerchandiseTotalNetPrice}"></td>
```

## Object: dw.system.Session

Because you are working in a template, and templates use _session_ as a top-level variable, you can immediately call methods in this class.

| Methods                             | Description                                                                                                                     |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| getCustomer() : Customer            | Returns the current customer associated with this storefront session. For a Business Manager session, this method returns null. |
| isCustomerAuthenticated() : Boolean | Identifies if the customer associated with this session is authenticated. This call is equivalent to customerisAuthenticated(). |

### Example

```
<isprint value="${session.getCustomer().firstname}"/>
```

## Object: dw.util.StringUtils

The Template Processor pre-imports _dw.util.StringUtils,_ so the StringUtils class can be used within a template by its simple name.

| Methods                                                                                    | Description                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| static formatDate(date : Date) : String                                                    | Formats a date with the default date format of the current site.                                                                                                                                                                   |
| static formatInteger(number : Number) : String                                             | Returns a formatted integer number using the default integer format of the current site. The method can also be called to format a floating point as an integer.                                                                   |
| static formatNumber(number : Number) : String                                              | Returns a formatted number using the default number format of the current site.                                                                                                                                                    |
| static garble(str : String, replaceChar : String, suffixLength : Number) : String          | Return a string in which a specified number of characters in the suffix isn't changed, and the rest of the characters are replaced with the specified character.                                                                   |
| static pad(str : String, width : Number) : String                                          | Provides cell padding functionality to the template.                                                                                                                                                                               |
| static stringToHtml(str : String) : String                                                 | Converts a given string to an HTML-safe string. This method substitutes characters that conflict with HTML syntax (\<,>,&,") and characters that are beyond the ASCII chart (Unicode 160-255) to HTML4.0 named character entities. |
| static stringToWml(str : String) : String                                                  | Converts a given string to a WML-safe string. This method substitutes characters that conflict with WML syntax (\<,>,&,&apos;,"$) to WML named entities.                                                                           |
| static stringToXml(str : String) : String                                                  | Converts a given string to an XML-safe string. This method substitutes characters that conflict with HTML syntax (\<,>,&,") and characters that are beyond the ASCII chart (Unicode 160-255) to HTML4.0 named character entities.  |
| static trim(str : String) : String                                                         | Returns the string with leading and trailing white space removed.                                                                                                                                                                  |
| static truncate(str : String, maxLength : Number, mode : String, suffix : String) : String | Truncates the string to the specified length using specified truncate mode. Optionally, appends the suffix to a truncated string.                                                                                                  |

### Example

```
<isprint value="${StringUtils.pad("abc", 5)}"/>
```

## Object: dw.web.URLUtils

The Template Processor pre-imports _dw.web.URLUtils,_ so the URLUtils class can be used within a template by its simple name.

| Method                                                         | Description                                                                                                                                                                                                                                           |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| static abs(action : String, namesAndParams : String...) : URL  | Returns an absolute URL with protocol and host from calling context request.                                                                                                                                                                          |
| static http(action : String, namesAndParams : String...) : URL | Returns an absolute URL with HTTP protocol. If an insecure host is specified in preferences, the returned URL includes that host. Otherwise, it uses the host from the calling context request.                                                       |
| static https(action : String, namesAndParms : String...) : URL | Returns an absolute URL with HTTPS protocol. If an insecure host is specified in preferences, the returned URL includes that host. Otherwise, it uses the host from the calling context request.                                                      |
| static httpsWebRoot() : URL                                    | Returns an absolute web root URL with HTTPS protocol and host and domain information from calling context request. If a secure host is specified in preferences, the returned URL includes that host. Otherwise, it uses the host from the request.   |
| static httpWebRoot() : URL                                     | Returns an absolute web root URL with HTTP protocol and host and domain information from calling context request. If an insecure host is specified in preferences, the returned URL includes that host. Otherwise, it uses the host from the request. |
| static url(action : String, namesAndParams : String...) : URL  | Returns a relative URL.                                                                                                                                                                                                                               |
| static webRoot() : URL                                         | Returns a relative web root URL. It uses a web root URL to access all static media context for the site. It can reference the actual media file by appending a relative path.                                                                         |

### Example

```
<form action="${URLUtils.httpsContinue()}" method="post" id="${pdict.CurrentForms.login.login.htmlName}">
```

<!-- document id=0e81a33049c17b9ae35bf778782fd3c7fdebce59b1cadaea9dbc0a6b941de5fe url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-ux-for-checkout-and-cart.md -->

# UX for Checkout and Cart (Deprecated)

We have prepared some resources to help you optimize your users’ experience with checkout and cart.

- [UX Series Part 3: Cart &Checkout Webinar Recording](https://salesforce.vidyard.com/watch/9zDPHt5SWd2uZQPg82PyFy): In this webinar series, B2C Commerce experts share UX best practices for optimizing site performance. We provide recommendations based on data insights and testing for navigation, header, homepage, product listing, product detail, cart, and checkout pages.
- [Elements of a High Performing Shopping Cart](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/B2CCommerceUXPlaybook-ElementsofaHighPerformingShoppingCart.pdf): This document provides best practices for elements in the shopping cart. Recommendations are based on the review of thousands of websites, extensive heat-mapping studies, B2C Commerce benchmarking data, and industry statistics.
- [Optimizations for the Checkout Flow](https://resources.docs.salesforce.com/rel1/doc/en-us/static/pdf/B2CCommerceUXPlaybook-OptimizationsfortheCheckoutFlow.pdf): This document includes checkout best practices based on the review of thousands of websites, extensive heat-mapping studies, B2C Commerce benchmarking data, and industry statistics.

<!-- document id=5c4f09b1548700eaecc2ac0799f800c9e8dd96177f66a1c4698fd3a4de5d94e0 url=/developer/current/en-us/commerce-cloud/commerce-api/guides/slas-validate-jwt-with-jwks.md -->

# Validate SLAS JWTs

A JSON Web Key Set (JWKS) is a set of cryptographic public keys in a JSON-based format, commonly used to validate the authenticity of JSON Web Tokens (JWTs). Each JWKS key is represented as a JSON Web Key (JWK), which includes the key type (`kty`), algorithm (`alg`), and key ID (`kid`). This format allows servers to securely share their public keys through a JWKS endpoint, which clients can access to validate JWTs without needing the private key used to sign the tokens. This public-private key pair ensures the integrity and trustworthiness of the transmitted JWTs.

JWKS plays a crucial role in distributed systems that rely on token-based authentication, especially for OAuth 2.0 and OpenID Connect protocols. By providing a central, trusted repository for public keys, the use of JWKS simplifies key management and enhances security. Systems using JWKS can dynamically retrieve keys and handle key rotation without service interruptions, making it a preferred method for validating signatures and safeguarding data in modern authentication systems. For additional information, see:

- [JSON Web Key](https://datatracker.ietf.org/doc/html/rfc7517)
- [Understanding JWKS](https://stytch.com/blog/understanding-jwks)

To validate a SLAS JWT using JWKS:

1. Fetch the JWKS from the [SLAS JWKS endpoint](https://developer.salesforce.com/docs/commerce/commerce-api/references/auth?meta=getJwksUri).
2. After parsing the JWT's header, retrieve the key ID (`kid`).
3. Locate the key in your JWKS that matches the `kid`.
4. Verify the JWT signature using the matching public key.

For a newly created tenant, the SLAS JWKS endpoint typically returns 2 keys. After the first successful rotation of the keys is completed, and from then on, the endpoint returns 3 keys per tenant. This makes it possible to validate JWTs even if SLAS rotates its signing keys.

**note:** To enhance performance and avoid rate limits, consider caching your signing keys. If a token fails to decode, invalidate the cache, retrieve new signing keys, and try the verification again **_only one time_**.

## Example: Validate SLAS JWT with JWKS

```java
@Slf4j
@Component
public class JwksValidatorExample {

    @PostConstruct
    public void init() throws Exception {
        // This method runs when the application starts
        log.info("Application started, initializing JWT Validator...");

        // Example JWTs for testing purposes
        String validJwt = "eyJ2ZXIiOiIxLjAiLCJqa3UiOiJzbGFzL2Rldi9iY2dsX3N0ZyIsImtpZCI6IjdlOWYyZWNhLTQyZDMtNDEzNS1hYmJmLWY5N2NhMTk5MDFhNSIsInR5cCI6Imp3dCIsImNsdiI6IkoyLjMuNCIsImFsZyI6IkVTMjU2In0.eyJhdXQiOiJHVUlEIiwic2NwIjoic2ZjYy5zaG9wcGVyLWJhc2tldHMtb3JkZXJzIHNmY2Muc2hvcHBlci1iYXNrZXRzLW9yZGVycy5ydyBzZmNjLnNob3BwZXItY2F0ZWdvcmllcyBzZmNjLnNob3BwZXItY3VzdG9tZXJzLmxvZ2luIHNmY2Muc2hvcHBlci1jdXN0b21lcnMucmVnaXN0ZXIgc2ZjYy5zaG9wcGVyLWRpc2NvdmVyeS1zZWFyY2ggc2ZjYy5zaG9wcGVyLWdpZnQtY2VydGlmaWNhdGVzIHNmY2Muc2hvcHBlci1teWFjY291bnQgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5hZGRyZXNzZXMgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5hZGRyZXNzZXMucncgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5iYXNrZXRzIHNmY2Muc2hvcHBlci1teWFjY291bnQub3JkZXJzIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzLnJ3IHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzIHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzLnJ3IHNmY2Muc2hvcHBlci1teWFjY291bnQucncgc2ZjYy5zaG9wcGVyLXByb2R1Y3Qtc2VhcmNoIHNmY2Muc2hvcHBlci1wcm9kdWN0bGlzdHMgc2ZjYy5zaG9wcGVyLXByb2R1Y3RzIHNmY2Muc2hvcHBlci1wcm9tb3Rpb25zIHNmY2Muc2hvcHBlci1zdG9yZXMiLCJzdWIiOiJjYy1zbGFzOjpiY2dsX3N0Zzo6c2NpZDphNGYzODExYS04YTZjLTQwNzUtYTEyMy04MjQ5MDE5ZmI4NWM6OnVzaWQ6Y2I0NTk3OGQtY2M4MC00YTg3LWI2MGYtNDlkNjA2Y2E2YWUzIiwiY3R4Ijoic2xhcyIsImlzcyI6InNsYXMvZGV2L2JjZ2xfc3RnIiwiaXN0IjoxLCJkbnQiOiIwIiwiYXVkIjoiY29tbWVyY2VjbG91ZC9kZXYvYmNnbF9zdGciLCJuYmYiOjE3Mjc3MzE0NzAsInN0eSI6IlVzZXIiLCJpc2IiOiJ1aWRvOnNsYXM6OnVwbjpHdWVzdDo6dWlkbjpHdWVzdCBVc2VyOjpnY2lkOmFidzBnWWxySTFtZW9SdzBrMmthWVl3ckUxOjpjaGlkOlJlZkFyY2giLCJleHAiOjE3Mjc3MzMzMDAsImlhdCI6MTcyNzczMTUwMCwianRpIjoiQzJDODY5NDcyMDc1MC0xMDA4Mjk4MDUyMzM4MzgyOTA5ODIxODA4OCJ9.TtzVB8NQt4vKv41lP6Fj3Wn83wa3_jMQceDBcYZEDni5_4foNMvTXPi7yaJ6N8qGV-Jx6op6DPdbZM_e7YlRZg";
        String invalidJwtSignature = "eyJ2ZXIiOiIxLjAiLCJqa3UiOiJzbGFzL2Rldi9iY2dsX3N0ZyIsImtpZCI6IjdlOWYyZWNhLTQyZDMtNDEzNS1hYmJmLWY5N2NhMTk5MDFhNSIsInR5cCI6Imp3dCIsImNsdiI6IkoyLjMuNCIsImFsZyI6IkVTMjU2In0.eyJhdXQiOiJHVUlEIiwic2NwIjoic2ZjYy5zaG9wcGVyLWJhc2tldHMtb3JkZXJzIHNmY2Muc2hvcHBlci1iYXNrZXRzLW9yZGVycy5ydyBzZmNjLnNob3BwZXItY2F0ZWdvcmllcyBzZmNjLnNob3BwZXItY3VzdG9tZXJzLmxvZ2luIHNmY2Muc2hvcHBlci1jdXN0b21lcnMucmVnaXN0ZXIgc2ZjYy5zaG9wcGVyLWRpc2NvdmVyeS1zZWFyY2ggc2ZjYy5zaG9wcGVyLWdpZnQtY2VydGlmaWNhdGVzIHNmY2Muc2hvcHBlci1teWFjY291bnQgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5hZGRyZXNzZXMgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5hZGRyZXNzZXMucncgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5iYXNrZXRzIHNmY2Muc2hvcHBlci1teWFjY291bnQub3JkZXJzIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzLnJ3IHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzIHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzLnJ3IHNmY2Muc2hvcHBlci1teWFjY291bnQucncgc2ZjYy5zaG9wcGVyLXByb2R1Y3Qtc2VhcmNoIHNmY2Muc2hvcHBlci1wcm9kdWN0bGlzdHMgc2ZjYy5zaG9wcGVyLXByb2R1Y3RzIHNmY2Muc2hvcHBlci1wcm9tb3Rpb25zIHNmY2Muc2hvcHBlci1zdG9yZXMiLCJzdWIiOiJjYy1zbGFzOjpiY2dsX3N0Zzo6c2NpZDphNGYzODExYS04YTZjLTQwNzUtYTEyMy04MjQ5MDE5ZmI4NWM6OnVzaWQ6Y2I0NTk3OGQtY2M4MC00YTg3LWI2MGYtNDlkNjA2Y2E2YWUzIiwiY3R4Ijoic2xhcyIsImlzcyI6InNsYXMvZGV2L2JjZ2xfc3RnIiwiaXN0IjoxLCJkbnQiOiIwIiwiYXVkIjoiY29tbWVyY2VjbG91ZC9kZXYvYmNnbF9zdGciLCJuYmYiOjE3Mjc3MzE0NzAsInN0eSI6IlVzZXIiLCJpc2IiOiJ1aWRvOnNsYXM6OnVwbjpHdWVzdDo6dWlkbjpHdWVzdCBVc2VyOjpnY2lkOmFidzBnWWxySTFtZW9SdzBrMmthWVl3ckUxOjpjaGlkOlJlZkFyY2giLCJleHAiOjE3Mjc3MzMzMDAsImlhdCI6MTcyNzczMTUwMCwianRpIjoiQzJDODY5NDcyMDc1MC0xMDA4Mjk4MDUyMzM4MzgyOTA5ODIxODA4OCJ9.TtzVB8NQt4vKv41lWn83wa3_jMQceDBcYZEDni5_4foNMvTXPi7yaJ6N8qGV-Jx6op6DPdbZM_e7YlRZg";
        String invalidJwtKid = "eyJ2ZXIiOiIxLjAiLCJqa3UiOiJzbGFzL2Rldi9iY2dsX3N0ZyIsImtpZCI6IjdlOWYyZWNhLTQyZDMtNDEzNS15N2NhMTk5MDFhNSIsInR5cCI6Imp3dCIsImNsdiI6IkoyLjMuNCIsImFsZyI6IkVTMjU2In0.eyJhdXQiOiJHVUlEIiwic2NwIjoic2ZjYy5zaG9wcGVyLWJhc2tldHMtb3JkZXJzIHNmY2Muc2hvcHBlci1iYXNrZXRzLW9yZGVycy5ydyBzZmNjLnNob3BwZXItY2F0ZWdvcmllcyBzZmNjLnNob3BwZXItY3VzdG9tZXJzLmxvZ2luIHNmY2Muc2hvcHBlci1jdXN0b21lcnMucmVnaXN0ZXIgc2ZjYy5zaG9wcGVyLWRpc2NvdmVyeS1zZWFyY2ggc2ZjYy5zaG9wcGVyLWdpZnQtY2VydGlmaWNhdGVzIHNmY2Muc2hvcHBlci1teWFjY291bnQgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5hZGRyZXNzZXMgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5hZGRyZXNzZXMucncgc2ZjYy5zaG9wcGVyLW15YWNjb3VudC5iYXNrZXRzIHNmY2Muc2hvcHBlci1teWFjY291bnQub3JkZXJzIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzIHNmY2Muc2hvcHBlci1teWFjY291bnQucGF5bWVudGluc3RydW1lbnRzLnJ3IHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzIHNmY2Muc2hvcHBlci1teWFjY291bnQucHJvZHVjdGxpc3RzLnJ3IHNmY2Muc2hvcHBlci1teWFjY291bnQucncgc2ZjYy5zaG9wcGVyLXByb2R1Y3Qtc2VhcmNoIHNmY2Muc2hvcHBlci1wcm9kdWN0bGlzdHMgc2ZjYy5zaG9wcGVyLXByb2R1Y3RzIHNmY2Muc2hvcHBlci1wcm9tb3Rpb25zIHNmY2Muc2hvcHBlci1zdG9yZXMiLCJzdWIiOiJjYy1zbGFzOjpiY2dsX3N0Zzo6c2NpZDphNGYzODExYS04YTZjLTQwNzUtYTEyMy04MjQ5MDE5ZmI4NWM6OnVzaWQ6Y2I0NTk3OGQtY2M4MC00YTg3LWI2MGYtNDlkNjA2Y2E2YWUzIiwiY3R4Ijoic2xhcyIsImlzcyI6InNsYXMvZGV2L2JjZ2xfc3RnIiwiaXN0IjoxLCJkbnQiOiIwIiwiYXVkIjoiY29tbWVyY2VjbG91ZC9kZXYvYmNnbF9zdGciLCJuYmYiOjE3Mjc3MzE0NzAsInN0eSI6IlVzZXIiLCJpc2IiOiJ1aWRvOnNsYXM6OnVwbjpHdWVzdDo6dWlkbjpHdWVzdCBVc2VyOjpnY2lkOmFidzBnWWxySTFtZW9SdzBrMmthWVl3ckUxOjpjaGlkOlJlZkFyY2giLCJleHAiOjE3Mjc3MzMzMDAsImlhdCI6MTcyNzczMTUwMCwianRpIjoiQzJDODY5NDcyMDc1MC0xMDA4Mjk4MDUyMzM4MzgyOTA5ODIxODA4OCJ9.TtzVB8NQt4vKv41lP6Fj3Wn83wa3_jMQceDBcYZEDni5_4foNMvTXPi7yaJ6N8qGV-Jx6op6DPdbZM_e7YlRZg";

        // Validate the JWT and log the result
        String validationResult = validateJwt(validJwt);
        log.info("*** JWT Validation Result: {}", validationResult);
    }

    // Fetch public EC keys from the JWKS endpoint
    public List<ECKey> getPublicKeysFromJwksEndpoint(String jwksUrl) throws Exception {
        // Fetch the JWKS JSON data from the specified URL, using Spring's RestTemplate
        RestTemplate restTemplate = new RestTemplate();
        String jwkSetJson = restTemplate.getForObject(jwksUrl, String.class);

        // Parse the JSON response into a JWKSet
        JWKSet jwkSet = JWKSet.parse(JSONObjectUtils.parse(jwkSetJson));

        // Extract EC keys from the JWKS
        List<ECKey> ecKeys = jwkSet.getKeys().stream()
                .filter(key -> key instanceof ECKey)  // Filter only EC keys
                .map(key -> (ECKey) key)
                .collect(Collectors.toList());

        // Log the Key IDs (kid) for demo purposes
        for (ECKey ecKey : ecKeys) {
            log.info("Public Key ID from JWKS: " + (ecKey.getKeyID().substring(0, 5)) + "...");
        }

        return ecKeys;
    }

    // Find the corresponding ECKey for a given JWT's 'kid'
    public Optional<ECKey> findPublicKeyForJwt(List<ECKey> publicKeys, String jwtToken) throws ParseException {
        // Parse the JWT and extract its header
        SignedJWT signedJwt = SignedJWT.parse(jwtToken);
        JWSHeader header = signedJwt.getHeader();

        // Extract the Key ID (kid) from the JWT header
        String jwtKid = header.getKeyID();

        // Match the JWT 'kid' with the appropriate ECKey 'kid'
        return publicKeys.stream()
                .filter(ecKey -> ecKey.getKeyID().equals(jwtKid))
                .findFirst();
    }

    // Verify the JWT using the matched EC public key
    public boolean verifyJwtSignature(String jwtToken, ECKey publicKey) throws ParseException, JOSEException {
        // Parse the JWT
        SignedJWT signedJwt = SignedJWT.parse(jwtToken);

        // Convert the ECKey to a usable public key
        ECPublicKey ecPublicKey = publicKey.toECPublicKey();

        // Verify the JWT using the public key and algorithm specified in the JWT header
        return signedJwt.verify(new com.nimbusds.jose.crypto.ECDSAVerifier(ecPublicKey));
    }

    // Main method to validate the JWT
    public String validateJwt(String jwtToken) throws Exception {
        // The JWKS endpoint URL
        String jwksUrl = "https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/jwks";

        // Step 1: Retrieve the EC keys from the JWKS endpoint
        // IMPORTANT: You should cache the public keys and retrieve them from the cache
        // instead of calling getPublicKeysFromJwksEndpoint each time, to improve performance.
        List<ECKey> publicKeys = getPublicKeysFromJwksEndpoint(jwksUrl);

        // If no public keys are found, return an error message
        if (publicKeys.isEmpty()) {
            log.info("No public keys found at JWKS endpoint.");
            return "No public keys found in JWKS, unable to validate JWT.";
        }

        // Step 2: Find the public key that matches the JWT's 'kid'
        Optional<ECKey> matchingKey = findPublicKeyForJwt(publicKeys, jwtToken);
        if (matchingKey.isEmpty()) {
            return "No matching Key ID found in JWT, unable to validate JWT.";
        }

        // Step 3: Verify the JWT signature using the matching public key
        log.info("JWT Key ID: " + (matchingKey.get().getKeyID().substring(0, 5)) + "...");
        boolean isSignatureValid = verifyJwtSignature(jwtToken, matchingKey.get());

        // Return the result of the verification
        return isSignatureValid ? "JWT signature is valid." : "Invalid JWT signature.";
    }
}
```

## Example: JWT Validation Output

### Validation Demo Run

```text
JwksValidatorExample Application started, initializing JWT Validator...
JwksValidatorExample Public Key ID from JWKS: 7e9f2...
JwksValidatorExample Public Key ID from JWKS: a5fdc...
JwksValidatorExample Public Key ID from JWKS: 4f3df...
JwksValidatorExample JWT Key ID: 7e9f2...
JwksValidatorExample *** JWT Validation Result: JWT signature is valid.
```

### After a Key Rotation

Note that `kid` “4f3df” is no longer in the JWKS output. The JWT still validates.

```text
JwksValidatorExample Application started, initializing JWT Validator...
JwksValidatorExample Public Key ID from JWKS: a5fdc...
JwksValidatorExample Public Key ID from JWKS: a4d21...
JwksValidatorExample Public Key ID from JWKS: 7e9f2...
JwksValidatorExample JWT Key ID: 7e9f2...
JwksValidatorExample *** JWT Validation Result: JWT signature is valid.
```

### JWT Minted with the Latest Key

Note that `kid` “a5fdc” is found in the JWKS output and the signature validates.

```text
JwksValidatorExample Application started, initializing JWT Validator...
JwksValidatorExample Public Key ID from JWKS: a5fdc...
JwksValidatorExample Public Key ID from JWKS: a4d21...
JwksValidatorExample Public Key ID from JWKS: 7e9f2...
JwksValidatorExample JWT Key ID: a5fdc...
JwksValidatorExample *** JWT Validation Result: JWT signature is valid.
```

## Example: Validate SLAS JWT with B2C Commerce Script APIs

Note: When retrieving the JWKS to be passed into this function, cache it using `dw.system.Cache` to avoid rate limits and improve performance.

```javascript
/**
 * Validates the SLAS token via the JWKS
 * @param {string} jwt - the JWT token to validate
 * @param {Array<object>} keys - array of keys
 * @return {boolean} true if the token is valid, false otherwise
 */
const validateSLASToken = (jwt, keys) => {
  const CertificateUtils = require("dw/crypto/CertificateUtils");
  const Encoding = require("dw/crypto/Encoding");
  const JWS = require("dw/crypto/JWS");
  const JWSHeader = require("dw/crypto/JWSHeader");
  const Logger = require("dw/system/Logger");

  try {
    const jwtParts = jwt.split(".");
    if (jwtParts.length !== 3) {
      Logger.error("Invalid JWT format - must have 3 parts");
      return false;
    }

    const encodedHeader = jwtParts[0];
    const encodedPayload = jwtParts[1];

    const jwsHeader = JWSHeader.parseEncoded(encodedHeader);
    const kid = jwsHeader.toMap().get("kid");

    if (!kid) {
      Logger.error("JWT header missing kid");
      return false;
    }

    // Find the matching key by kid; SLAS rotates keys and provides a key set
    const jwk = keys.find((key) => key.kid === kid);
    if (!jwk) {
      Logger.error("No matching key found in JWKS for kid: " + kid);
      return false;
    }

    // Parse the public key from JWK (needs string form)
    const publicKey = CertificateUtils.parsePublicKeyFromJWK(JSON.stringify(jwk));

    const jws = JWS.parse(jwt);

    const isValid = jws.verify(publicKey);

    if (isValid) {
      const base64urlDecode = (str) => {
        let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
        while (base64.length % 4) {
          base64 += "=";
        }
        return Encoding.fromBase64(base64);
      };

      const payloadJson = base64urlDecode(encodedPayload);
      const payload = JSON.parse(payloadJson);

      // Check expiration
      const currentTime = Math.floor(Date.now() / 1000);
      if (payload.exp && payload.exp < currentTime) {
        Logger.error("JWT has expired");
        return false;
      }

      return true;
    }
    Logger.error("JWT signature verification failed");
    return false;
  } catch (error) {
    Logger.error("Error validating JWT: " + error.toString());
    return false;
  }
};

module.exports = {
  validateSLASToken,
};
```

<!-- document id=93d9f10c0395e7ad44d0df9880f9d9bb417b89e71ac2bf0b770c83aa6d4d8479 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/site-development/b2c-velocity-templates.md -->

# Velocity Templates

Apache Velocity is a Java-based server-side templating language. ISML templates are contained in your code cartridge and can't be changed without activating a new version of code. Change Velocity templates by uploading a new version of the file to a WebDAV directory on your instance. Using Velocity templates, publish section or page layouts and their content assets to your storefront. You don't have to change your storefront code, effectively decoupling code development and content design.

## Publish Content Layouts as Velocity Templates

Velocity templates are most useful for content rich sections of your site whose functionality doesn't change. For example: the home page, category pages, designer blogs, lookbooks, sponsored event pages, or loyalty program pages. Publish layouts to external communications, such as email or social media posts. Velocity templates are treated like content and not code. Change them frequently without the considerations necessary when changing code that can affect the functionality of a site.

This feature is most useful with an external Content Management System (CMS) to design the layout and publish it as a Velocity template.

**note:** If you have another way to generate the Velocity templates used by B2C Commerce, a CMS isn't required. For example, work with a web design firm that can provide Velocity templates as part of their design

![Content Publishing Overview](https://developer.salesforce.com/media/b2c-commerce/b2c_cms_slide_1.gif)

The process for creating and publishing a new layout is:

- Design the layout. If you are using a CMS, design the layout and preview the page as it appears in the storefront. A CMS to B2C Commerce connector gets information from B2C Commerce via OCAPI.

  **note:** To preview the page for both the current storefront and the next version of the storefront, use different connectors for staging and production instances.

- Publish the layout and images to your Staging instance for testing via WebDAV and the content assets via import or export. Automate this functionality in your CMS to publish in a single step.
- After testing, transfer data to your production site. Replicate Velocity templates and images to your Production Instance and use import or export to add content assets to B2C Commerce.

Velocity Template Limitations

- While it's technically possible to include content slots in Velocity templates, it isn't officially supported. Slots added to Velocity templates aren't listed in Business Manager and can't be previewed in the Storefront Toolkit.
- Page tracking and active data aren't supported for Velocity templates.
- UX Studio doesn't support editing Velocity templates. Velocity templates are shown in the Storefront Toolkit, but the toolkit links to the template location in WebDav, rather than opening it in Studio.
- All variables must be passed to the template for rendering. Velocity has no access to the B2C Commerce API or the implicit variables (such as pdict) available to any ISML template. This situation is similar to the way that ISML is rendered in controllers.

Velocity Template Quotas

- Include depth: 10
- Loop limit: 1000
- Max template size: 100 KB
- Timeout: 100 sec

**note:** All quotas are enforced. All other quotas, such as the 10-MB web adapter limit, still apply.

Velocity and Performance

B2C Commerce performance tests found that the performance of Velocity and ISML is comparable for both cached and uncached pages.

Velocity and Content

Velocity templates can contain text directly and also include text from content slots. If you are using a CMS, it's usually more convenient to edit text in your preview page and publish the Velocity template with the text from your CMS.

## Implementing Content Publishing

![Content Publishing Implementation](https://developer.salesforce.com/media/b2c-commerce/b2c_cms_slide_2.gif)

1.  Create the Velocity files, content assets, and image files you intend to use. If you have a CMS, obtain and configure the CMS connector. Consult the connector documentation for information on how to configure the connector.
2.  Upload Velocity templates to use for your content layout into the Dynamic WebDAV directory. Velocity templates can be generated from a CMS or developed independently. If you are using a CMS, it must meet the requirements for a system that can integrate with B2C Commerce and provide a B2C Commerce connector. See the following sections for information on selecting a CMS and uploading Velocity templates.
3.  Create code to render the Velocity template or snippet. Use either a pipeline or a controller to render Velocity. Render Velocity templates stored in the WebDav directory, template snippets included inline in a script or controller, or Velocity as part of an ISML template.

4.  Create jobs to replicate images and templates from Staging to production. You might also need to add content assets created by your CMS to your import/export jobs.

## Selecting a CMS

Ask your CMS vendor to provide a connector to B2C Commerce that supports the following:

- contextual editing of content sections within pages
- managing and previewing pages in the CMS
- a media library that is integrated in the content editing process
- including data from the media library into the publishing process
- Velocity template output
- WebDAV capability

The vendor must offer a B2C Commerce connector to let them integrate with B2C Commerce to achieve this functionality.

## Uploading Your Velocity Template

Upload Velocity templates via WebDAV or site import.

Upload via WebDAV

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Development Setup**.

    Take note of the WebDAV path under the Velocity Templates section. Add the name of your site to this path. For example: `https://www.mystore.com/on/demandware.servlet/webdav/Sites/dynamic/SiteGenesis`

2.  Upload your templates using WebDAV. Upload a file structure as well as individual templates. All paths in code are always relative to the dynamic WebDAV directory.

Upload via Site Import

Use site import to publish a hierarchy of templates as a .zip file to the dynamic directory.

## Render Velocity Templates

Render Velocity templates using controllers or pipelines. If you want to share functionality between new and legacy cartridges, we recommend adding your rendering functionality in a utility script that can be used from either controllers or pipeline script nodes. We encourage you to use a controller, even if you intend to overwrite existing functionality that is currently in a pipeline.

### Script Rendering Examples

Render the Velocity template using the `dw.Template.Velocity.render` method. If you use a B2C Commerce script to render a template, call the script from either pipelines or controllers.

Hello World - Inline Velocity in a Script File

The following example renders an inline Velocity template using the `dw.Template.Velocity.render`class in a script module file. This code can be included directly in a controller or required as a script module from a controller or pipeline script node.

```javascript
var velocity = require("dw/template/Velocity");
velocity.render("Hello $message", { message: "World" });
```

Hello World - Rendering a Template Stored in the Dynamic WebDav Directory

The second example shows a similar 'hello world' example that relies on the Velocity template being located in the file system. Supply the file name directly:

```javascript
var velocity = require("dw/template/Velocity");

// assume template source to be 'Hello $message'
velocity.renderFile("hello-world-1.vs", { message: "World" });
```

Look up the file manually to check whether the file exists.

```javascript
var velocity = require("dw/template/Velocity");

// assume template source to be 'Hello $message'
var template = new File(File.getRootDirectory(File.DYNAMIC), "hello-world-1.vs");
velocity.renderFile(template, { message: "World" });
```

**note:** There is no caching involved in this example.

Velocity Hello World - Callbacks

Pass any objects used by the Velocity template during rendering in a JavaScript Map as a parameter of the rendering method. These include, but aren't limited to, B2C Commerce Script API objects. The engine also supports invoking methods on those objects. The following example passes the B2C Commerce Script API `URLUtils` object to render a B2C Commerce product URL within a Velocity template. In the example, this is passed as string literal for better readability.

This example shows how to invoke the template and render the generated content into a string for further processing. For example, if you want to use it in an email.

```javascript
var File = require("dw/io/File");
var velocity = require('dw/template/Velocity');
var writer = new dw.io.StringWriter();

velocity.render("Hello $message", {message : 'World'}, writer );
var global.html = writer.toString();
```

Calling URLUtils in Templates

```javascript
var velocity = require("dw/template/Velocity");
var urlUtil = require("dw/web/URLUtils");

// this renders something like 'http://.../Product-Show?cgid=1234'
velocity.render("$url.abs('Product-Show', 'cgid', '1234')", { url: urlUtil });

// this renders something similar with the pid taken from the current request
velocity.render(
  "$url.abs('Product-Show', 'cgid', $request.CurrentHttpParameterMap.pid.stringValue)",
  {
    url: urlUtil,
    request: request,
  },
);
```

Localizing Text

Add the Resource class as a parameter to localize text from a resource bundle.

```javascript
var web = require("dw/web");
var velocity = require('dw/template/Velocity');
var res = require('dw.web.Resource'); //include to localize resource messages

// render some text taken from a resource bundle
velocity.render("Hello $res.msg('test.key1','test')"), {'res' : Resource});
```

It is possible to deploy text resource bundles alongside the Velocity templates in the `dynamic` file location on WebDAV in a `resources` directory. Just like Velocity templates, they follow the content lifecycle and aren't part of a code deployment. These text resource bundles are used with the normal `dw.web.Resource class`, as they would be in ISML template. You add `dw.web.Resource` as a parameter to the template and then call it.

The resource bundles in your code cartridges assigned to your site are checked first and then the `dynamic` file location on WebDAV. B2C Commerce uses the first resource bundle it finds with a specific ID. B2C Commerce searches cartridges in the order set by the cartridge path and then the `dynamic` file location on WebDAV. This means if there are two resource bundles with the same ID, the resource bundle in the cartridge wins over the resource bundle in the WebDAV location.

Escaping and VelocityTools

In ISML, all values written to the response are automatically escaped based on the response MIME type, except when the encoding is turned off in ISPRINT. However, Velocity requires the template developer to explicitly escape all dynamic values using the VelocityTools EscapeTool. B2C Commerce supports the EscapeTool in context. To escape a value, add a line similar to the following to your Velocity template:

```html
$esc.html($object.myProperty2)
```

`esc` in the example is the EscapeTool.

Supported Velocity Tools

B2C Commerce supports the following Velocity tools:

- AlternatorTool
- ComparisonDateTool
- ConversionTool
- DisplayTool
- EscapeTool
- MathTool
- NumberTool
- ResourceTool
- SortTool
- LinkTool
- LoopTool

For more information about Velocity [Http://Velocity.Apache.Org/Tools/Devel/Generic.Html](http://velocity.apache.org/tools/devel/generic.html)​

Adding Remote Includes to Your Velocity Template

Add a remote include to your Velocity template using the `Velocity.remoteInclude` method.

```javascript
var system = require("dw/system");
var urlUtil = require("dw/web/URLUtils"); //include to use remote includes to call pipeline or controllers

function execute(pdict: PipelineDictionary): Number {
  var velocity = require("dw/template/Velocity");

  velocity.render("before $velocity.remoteInclude('MyPipeline-Subpipeline') after", {
    velocity: velocity,
  });
  return PIPELET_NEXT;
}
```

Using caching with Velocity

Use caching with Velocity by setting the expiration on the response.

```javascript
var system = require("dw/system");
function execute(args: PipelineDictionary): Number {
  var velocity: dw.template.Velocity = require("dw/template/Velocity");
  response.setExpires(Date.now() / 1000 + 180); //3 minutes
  velocity.render(
    '<html><head><title>It Works!</title></head><body><h1 style="text-align:center">It Works! Yay!</h1></body></html>',
    {},
  );
  return PIPELET_NEXT;
}
```

Wrapping Velocity with ISML

Most of your storefront is written in ISML, because of the features that ISML offers in terms of consistent styling and caching (`isdecorate` and `iscache` tags). ISML also supports content slots, which let promotions be scheduled and associated with specific customer groups and previewed for any date. Velocity doesn't support content slots.

In some cases, you might want to wrap your Velocity template in ISML, to take advantage of the features of ISML and the ability to change your layout without affecting code functionality. The following example renders a Velocity segment and includes it in an ISML template.

ContentRender.ds

```javascript
*
*	@input content : dw.content.Content
*	@output velocitySegment : String
*/
importPackage( dw.system );
importPackage( dw.io );
importPackage( dw.util );
importPackage( dw.content );
importPackage( dw.template );


function execute( args : PipelineDictionary ) : Number {

	var content : Content;
	try {
		if (args.content != null) {
			content = args.content;
		}
		// Create the Global scope that can be accessed via $VARIABLE in the original template
		var global = {
			asset : content,
			CurrentPageMetaData : request.pageMetaData,
			CurrentHttpParameterMap : request.httpParameterMap,
			request    : request
    	};
		// Render the HTML by adding it to PDICT so that you can get the value later in ISML
		if (content.custom.body) {
			var html = new StringWriter();
			Velocity.render(content.custom.body, global, html)
			args.velocitySegment = html.toString();
		}
	} catch (e) {
		Logger.error("[int_aem_core] Error Rendering Content: " + e);
		return PIPELET_ERROR;
	}
	return PIPELET_NEXT;
}
```

The script renders the Velocity template and writes it to an object available to the ISML template. The following is added to the ISML template to include the segment if it exists. The script assumes you are using a pipeline to render the ISML.

```html
<isif condition="${empty(pdict.velocitySegment)}">
  <isinclude template="content/content/htmlcontentasset" />
  <iselse>
    <div style="margin-bottom:26px;margin-left:14px;margin-right:14px;">
      <isprint value="${pdict.velocitySegment}" encoding="off"></isprint>
    </div>
  </iselse>
</isif>
```

Writing out the rendered Velocity Template

If you don't want to write the result directly to the response, include a string writer. This is useful for email templates or including snippets of rendered Velocity in ISML templates.

Example: writing a template to the "contact us" Email

This example can be used with the SiteGenesis contact us email template.

email/contactus.isml

Replace the contactus.isml template in your SiteGenesis instance with an identically named template with the following contents:

```html
<isscript>
  importPackage( dw.io ); importPackage( dw.web ); var velocity = require('dw/template/Velocity');
  var urlUtil = require('dw/web/URLUtils'); response.setContentType('text/html') // Set the content
  type to HTML velocity.renderTemplate('contactus.vs', { // Render the template res : Resource, //
  Pass the Resource object to the template (for localized messages) url: urlUtil, // Pass the
  URLUtils object to the template (for rendering URLs) customer: pdict.CurrentCustomer, // Pass the
  customer to the template (for 'personalizing') subject: pdict.MailSubject, form:
  pdict.CurrentForms.contactus // Pass the form to the template } );
</isscript>
```

contactus.vs

This example assumes you have a Velocity template file named `contactus.vs` with the following contents:

```html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
  <subject>#if($subject)$subject#else $form.myquestion#end</subject>
  <head></head>
  <body>
    <table width="100%" cellpadding="0" cellspacing="0">
      <tr>
        <td align="center" style="background:#e0e0e0;padding:50px 0;">
          <center>
            <table style="background:#ffffff;border:1px solid #999999;width:680px;">
              <tr>
                <td style="font-size:12px;font-family:arial;padding:20px 10px;vertical-align:top;">
                  <p style="font-family:georgia;font-size:20px;">B2C Commerce (Velocity)</p>

                  <!-- Render the form fields and their localized descriptions -->
                  <p>$res.msg('contactus.name', 'email', null) $form.firstname $form.lastname</p>
                  <p>$res.msg('contactus.email', 'email', null) $form.email</p>
                  <p>$res.msg('contactus.phone', 'email', null) $!form.phone</p>
                  <p>$res.msg('contactus.ordernumber', 'email', null) $!form.ordernumber</p>
                  <p>$res.msg('contactus.myquestion', 'email', null) $!form.myquestion</p>
                  <p>$res.msg('contactus.comment', 'email', null) $!form.comment</p>

                  <!-- Print a message based on the users authentication state -->
                  #if(!$customer.isAuthenticated())
                  <p>
                    <b>Become a customer <a href="$url.abs('Account-StartRegister')">here</a>!</b>
                  </p>
                  #else
                  <p><b>Thank you for being a customer!</b></p>
                  #end
                </td>
              </tr>
            </table>
          </center>
        </td>
      </tr>
    </table>
  </body>
</html>
```

This template illustrates:

- rendering localized messages (`$res.msg('contactus.name', 'email', null)`)
- displaying values (`$form.email` or `$!form.phone`)
- rendering URLs (`$url.abs('Account-StartRegister')`)
- using decisions (`#if(...) ... #else ... #end`)
- accessing object data (`!$customer.isAuthenticated()`)

**note:** This template must be uploaded via WebDAV to `/on/demandware.servlet/webdav/Sites/Dynamic/SiteGenesis`

Testing Information

`$res.msg('contactus.email', 'email', null)` gets the localized message for contactus.email from the email resource bundle without using a default message (null).

`$!form.phone` shows the phone number only if provided. Without the exclamation mark and no phone number provided, it shows the text '`$form.phone'`.

To test the contactus template:

1.  Open the contactus page in SiteGenesis (/`SiteGenesis/contactus`).

2.  Fill in the form.

3.  Click **submit**.

    You receive the updated email at the specified address with the template information.

### Using Controllers or Pipelines

A controller can render a Velocity template directly or call a script to render the template. A pipeline must call a script to render a pipeline, either through a script node or in the `isscript` tag of an ISML template.

Creating a controller to render a Velocity template or Snippet

Create a controller with a public function that contains the same code as a script or requires a script module. Salesforce recommends creating a script module as a helper function and calling it from your pipeline. The following is a sample helper function:

Creating a pipeline to render a velocity template or Snippet

Salesforce recommends using controllers rather than pipelines,. However, this section describes what to do if you want to add the ability to publish a layout to your existing storefront, which uses pipelines.

If you want to enhance an ISML template with sections of the page rendered using Velocity snippets, create a pipeline with an:

- interaction node - use this to render the ISML template and include the snippets in the ISML template.
- interaction continue node - use this to render the ISML template and include the snippets in the ISML template for forms.

If you want to render a Velocity directly, create a pipeline with:

- one or more script nodes and a stop node - In general, if you don't want to use an existing pipeline or ISML, it's highly recommended that you use a controller in place of this solution. However, if you don't want your Velocity template wrapped in an ISML template and you want to use an existing pipeline, use one or more script nodes to render different parts of the page, such as the header, body, and footer.

  Rendering different parts of the page in different script nodes effectively replaces the way `isdecorate` is used in ISML. Use script logic to select different templates for different sections of a page, such as different header templates for an event-driven sale category or an exclusive page for members of a loyalty program.

## ISML Equivalents in Velocity

When referencing property values in Velocity, make sure to use the correct case for the actual property name. Using an uppercase letter when the property name starts with a lowercase letter generates an error.

ISML Patterns

The # notation in ISML and ISPRINT replace references that can't be resolved with an empty string. Velocity by default prints the reference itself. To avoid that, use the \$!VAR notation.

ISML by default escapes all dynamic content written to the output according to the content type (HTML by default) to avoid any XSS problems. Velocity doesn't do that. So all dynamic content needs to be handled by the EscapeTools provided by Velocity. The syntax then becomes: `$esc.html($!VAR)`.

Comments in ISML are converted to lines starting with '`##`' in Velocity.

The notation for conditions is:

```html
#if($VAR==1) true #elseif($FOO && $BAR) more true #else false #end
```

An '`isDefined(VAR)`' test is now '`#if($VAR)`', and "`hasLoopElements(ITER)`' gets replaced as '`#if($IT.hasNext())`'.

For remote includes, a directive needs to be written manually.

### ISML Tags and Their Velocity Equivalents

| ISML tag              | Velocity tag                                                                                                           |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `isactivedatacontent` | NONE                                                                                                                   |
| `isactivedatahead`    | NONE                                                                                                                   |
| `isanalyticsoff`      | NONE                                                                                                                   |
| `isbreak`             | `#break` inside a `#foreach`                                                                                           |
| `iscache`             | use `Response.setExpires()`and `Response.setVaryBy()`                                                                  |
| `iscomment`           | comments in Velocity start with `##`                                                                                   |
| `iscomponent`         | <code>'&lt;wainclude&gt;'</code>                                                                                       |
| `iscontent`           | use `Response.setHeader('Content-Disposition')` to set the content type, use `$esc.html($VAR)` to handle HTML escaping |
| `iscontinue`          | NONE                                                                                                                   |
| `iscookie`            | `Response.addHttpCookie()`                                                                                             |
| `isdecorate`          | NONE                                                                                                                   |
| `iselse`              | `#if(CONDITION)true#else false#end`                                                                                    |
| `iselseif`            | `#if(COND1)true #elseif(COND2)more true#end`                                                                           |
| `isif`                | `#if(CONDITION)true#else false#end`                                                                                    |
| `isinclude`           | #parse for template includes <code>&lt;wainclude&gt;</code> for remote includes                                        |
| `isloop`              | `#foreach(ITERATOR)`                                                                                                   |
| `ismodule`            | NONE, use Velocity Macros. Calling `ISMODULES` from Velocity templates isn't supported.                                |
| `isnext`              | NONE                                                                                                                   |
| `isobject`            | NONE                                                                                                                   |
| `isprint`             | `$VAR` syntax. For formatting, use the Velocity Tools                                                                  |
| `isredirect`          | `Response.redirect()`                                                                                                  |
| `isremove`            | NONE, removing variables isn't supported in Velocity                                                                   |
| `isreplace`           | NONE                                                                                                                   |
| `isscript`            | NONE, scripting isn't supported in Velocity                                                                            |
| `isselect`            | NONE, can be done with Velocity                                                                                        |
| `isset`               | `#set`                                                                                                                 |
| `isslot`              | NONE                                                                                                                   |
| `isstatus`            | `Response.setStatus()`                                                                                                 |

<!-- document id=ca7accd1fbdf4d34bed0474142525e80bdb2463f13d3f2dcac1e0fecd132d6c6 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_view_clone_history.md -->

# View Clone History for On-Demand Sandboxes

View all clone operations associated with a specific sandbox, including details about source and target instances, status, and data copied.

1. Log in to Control Center.
2. Click the sandbox instance you want to view.
3. Navigate to the **Activity Timeline** tab. All clone operations associated with this sandbox are listed chronologically. The top right displays a summary count of clones by status: Completed, Failed, and In Progress.
4. Click **Expand** on any clone entry to view details.
   - Clone details include:
     - Source and target instance identifiers
     - Clone status and progress
     - Duration and timestamps
     - Data copied over
     - Storefront copied
     - Active code version

<!-- document id=ace7966dfc2d53dc6c237f4b8340c98121c15faa4666253c6134ae4156d3245d url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/control_center/b2c_cc_view_ods_statistics.md -->

# View On-Demand Sandbox Usage Statistics

In Control Center, analyze your ODS usage by looking at the usage statistics.

1. Log into Control Center.
2. Select the realm you want to review.
3. View the ODS usage for the realm, which shows activity based on minutes up and down. Specify a date range, view usage daily, weekly, or monthly, and view by credits or minutes. Optionally, export the information to a CSV file.
4. To view ODS usage for a specific sandbox, select the instance, then click **Statistics**.

<!-- document id=397190111fb5697bd35c138e6ea51102c7e01c0b21e2e833d31e5f2cb330239c url=/developer/current/en-us/commerce-cloud/commerce-api/guides/scapi-logs-request-tracking.md -->

# View SCAPI Logs and Track Requests

Log Center provides comprehensive logging and monitoring capabilities for B2C Commerce API (SCAPI) operations. Use Log Center to troubleshoot issues, monitor performance, and analyze API behavior across your B2C Commerce instances.

**note:** For related custom cartridge errors, the [B2C CLI](https://developer.salesforce.com/docs/commerce/b2c-commerce/guides/b2c-developer-tooling.md#configuration-and-authentication) can read and filter instance log files over WebDAV. For example, after configuring your instance and WebDAV access, use `b2c logs get --since 1h --search "your-correlation-id"`. These commands don't query Log Center; use the steps below for SCAPI request logs.

## Access Log Center

1. Log in to Business Manager.
2. Click App Launcher ![App Launcher](https://developer.salesforce.com/docs/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **Development Setup**. If you built your site using Progressive Web App (PWA) Kit, first complete the prerequisites described in [Debug Using Log Center](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guides/debugging.md#debug-using-log-center).

For general information on Log Center, see [Centralized Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5).

## Search for SCAPI Logs

In Log Center, navigate to **Search**.

**note:** SCAPI logs appear in Log Center with a delay of up to 5 minutes.

### Investigate By Correlation ID

You can use correlation IDs to match a particular request to a particular response, making it easier to troubleshoot unexpected issues, such as internal server errors.

If a `correlation-id` header is provided in a request to a SCAPI endpoint, the response contains an `correlation-id` header that contains the value of `correlation-id`. The API also generates its own correlation ID for each response. This generated ID is provided in the `sfdc_correlation_id` response header.

Example headers:

```bash
# Request
correlation-id: 40e1feef-c454-49cd-9abc-cc995e1f960e

# Response header - DEPRECATED, will be removed
x-correlation-id: 40e1feef-c454-49cd-9abc-cc995e1f960e,7672402e9add1b37

# Response header - replacement for x-correlation-id
sfdc_correlation_id: 7672402e9add1b37
```

The value of `correlation-id` must only contain word characters, hyphens (-), and commas (,). Other characters may prevent you from searching for that correlation ID string in Log Center.

For most Commerce API endpoints, the `correlation-id` can be automatically added to log messages with a hook. Query these messages in Log Center with an LCQL (Log Center Query Language) expression that filters messages based on the `externalID` field. The `externalID` field contains the value of the `correlation-id` response header, so query for the user-provided correlation ID, the SCAPI-generated correlation ID, or the combined string.

If you can reproduce an issue, you might be able to identify the problem either by attaching your own correlation ID or by observing the automatically generated correlation ID in the response.

Use this correlation ID to trace specific requests:

1. In Log Center search, enter the correlation ID in the search field or use a Log Center Query Language (LCQL) expression on the `externalID` field, for example: `externalID:(9527f1869f95a32d)`.
2. Filter by relevant service types for more focused results, which is only recommended if the result set is very large.

```javascript
const Logger = require("dw/system/Logger");

exports.beforeGET = function () {
  // When you log, correlation IDs are automatically associated with your message, so you don't need to provide the correlation ID to the log function.
  Logger.log("Hello!");
  return new Status(Status.OK);
};
```

**note:** Some groups of Commerce API endpoints are not used exclusively with B2C Commerce and therefore can't log requests and responses to Log Center. These API groups include CDN Zones, Inventory Availability, Inventory Impex, Inventory Reservation, Shopper Context, and Shopper Login.

### Identify Error Patterns

You can also use the SCAPI logs in Log Center to investigate patterns of frequent errors:

1. Select the SCAPI category or categories from the dropdown menu.
   - Select `scapi-http` to identify requests with specific error response codes.
   - Select `scapi` to find error messages about how the SCAPI requests are processed, for example: incorrect requests, failing authentication, or routing issues.
2. Execute a search to identify error status types that occur.
3. To dig deeper into a specific error, obtain one or multiple correlation IDs from the results and search for further entries with the same correlation ID. For details, see [Investigating By Correlation ID](#investigate-by-correlation-id).

## Collect Detailed Request Information

Use SCAPI verbose logging to investigate errors, long latencies, hook execution errors, and remote service call errors within a single request context. Enable verbose logging in two ways:

- **Automatic setup** - Configure conditions that automatically trigger verbose logging (recommended for production environments where code changes are difficult).
- **Request header** - Add the `sfdc_verbose` header to individual requests (recommended for development environments where flexibility is needed).

The header method always takes precedence over automatic settings.

### Enable Verbose Logging with a Header

With B2C Commerce version 24.7, generate a JSON document that contains comprehensive information about the request. This JSON document is beneficial for troubleshooting, because it provides detailed information that is not included with standard logging, such as request authorization, hook execution, request query parameters, headers, and body.

**important:** To mitigate potential performance issues, the usage of the header is subject to rate limiting. Headers should only be used for individual test requests when a detailed investigation is necessary.

To enable this feature, include the following header in your request:

- **Header:** `sfdc_verbose: true`

Upon the completion of the request, a JSON document is created and logged within the INFO log associated with the [correlation ID](#investigate-by-correlation-id) of that request.

Additionally, a request with the `sfdc_verbose` header creates `scapi-http` log entries in Log Center for all responses, while only error logs are available for non-verbose requests.

In combination with the `correlation-id`, the `sfdc_verbose` header can be used to generate and find verbose log output in the Log Center.

### Enable Automatic Verbose Logging

With B2C Commerce version 26.6, verbose logging has been enhanced to always track verbose logs automatically for a selected set of conditions.

Verbose logging automatically captures logs when:

This feature is enabled via a feature toggle from SFCC during rollout and remains enabled.

- SCAPI requests that call 3rd parties via remote service calls which return errors
- SCAPI requests ending with 4xx/5xx responses caused by hook execution errors

This feature is enabled via a feature toggle from SFCC during rollout and remains enabled.

Once a condition described above is met, a JSON document is created and logged within the INFO log associated with the [correlation ID](https://developer.salesforce.com/docs/commerce/commerce-api/guide/scapi-logs-request-tracking.md#investigate-by-correlation-id) of that request.

### Find Verbose Log Entries

1. Log in to Log Center as described in [Start Log Center](https://help.salesforce.com/s/articleView?id=cc.b2c_start_log_center.htm&type=5).
2. Use the [correlation ID](https://developer.salesforce.com/docs/commerce/commerce-api/guide/identifying-requests-and-responses.html) or the category `scapi.verbose` in combination with the [Log Center Search](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center_search.htm&type=5) to find the corresponding log entry.

### Verbose Log Entry Schema

The following example shows the objects (`auth`, `request`, `response`, `customApi`, `hooks`, `services`) that can be present in a verbose log entry:

```json
{
  "auth": {
    "clientId": "<client-id>",
    "customer": {
      "customerId": "<customer-id>",
      "customerIdp": "slas",
      "customerLogin": "Guest",
      "customerType": "guest",
      "sessionBridgeToken": false
    },
    "grantedScopes": ["c_loyaltyInfo_rw"],
    "tokenType": "ShopperToken",
    "user": {
      "agentOnBehalfOfUser": "<user-id>",
      "taobToken": false
    }
  },
  "request": {
    "encodedQueryString": "siteId=RefArch",
    "headers": {
      "sfdc_verbose": "true"
    },
    "httpMethod": "GET",
    "queryParameters": {
      "siteId": "TestWapi-Customization",
      "c_responseHeader": "correct"
    },
    "requestUrl": "<request-url>",
    "runtimeInMillis": 124,
    "type": "on-request"
  },
  "response": {
    "headers": {
      "c_ResponseHeader": "test"
    },
    "httpStatus": "OK",
    "httpStatusCode": 200
  },
  "customApi": {
    "implementation": "test_bc_wapi/cartridge/rest-apis/sample/Sample.js#sampleFunction",
    "locale": "default",
    "mapping": "test_bc_wapi/cartridge/rest-apis/sample/api.json",
    "runtimeInMillis": 8
  },
  "hooks": [
    {
      "name": "dw.ocapi.shop.store.beforeGET",
      "result": "OK",
      "runtimeInMillis": 10,
      "scripts": ["test_bc_wapi/cartridge/scripts/store_shop_script.js"]
    },
    {
      "name": "dw.ocapi.shop.store.modifyGETResponse",
      "result": "OK",
      "runtimeInMillis": 4,
      "scripts": ["test_bc_wapi/cartridge/scripts/store_shop_script.js"]
    }
  ],
  "services": [
    {
      "name": "test.payment.service",
      "result": "OK",
      "runtimeInMillis": 123
    },
    {
      "name": "test.inventory.service",
      "result": "OK",
      "runtimeInMillis": 192
    }
  ]
}
```

## Review SCAPI Metrics

You can view SCAPI and SCAPI hook metrics in the Metrics Dashboard. To view the metrics, click **Metrics** in Log Center, and then click **SCAPI** or **SCAPI Hooks**. See [Metrics Dashboard](https://help.salesforce.com/s/articleView?id=cc.b2c_metrics_dashboard.htm&type=5).

Additional SCAPI metrics are provided in the [CCAC SCAPI Dashboard](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-troubleshooting-platform-performance.html)

For additional details, see [Log Center Metrics Documentation](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center.htm&type=5).

## Related Resources

- [Log Center Search Documentation](https://help.salesforce.com/s/articleView?id=cc.b2c_log_center_search.htm&type=5)
- [CCAC SCAPI Dashboard](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-troubleshooting-platform-performance.html)
- [Monitor SCAPI API performance](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/code-profiler.md)
- [Analyze response bodies to identify maintenance issues](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/response-handling.md)
- [Check error response codes](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/error-response-codes.md)

<!-- document id=bc794e1368aca7ebe6902c141e2c10a08ec42013986c5b70e861cbb0a47db2cd url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/visual-search-spi.md -->

Visual Search SPI

# Visual Search SPI

**Partial reference:** 2 operation(s) were omitted because their source references could not be resolved.

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/visual-search-spi/visual-search-spi-oas-public.yaml)

Merchant SPI for visual product search powered by an external image recognition provider. Enables store associates to search products by photographing them with the POS device camera. The Retail Cloud backend forwards the image and search parameters to this SPI endpoint and expects matching product IDs in return.

**Version:** 2.3.4

## Tags

### Visual Search SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/visual-search-spi/visual-search-spi-oas-public.yaml)

Merchant SPI for visual product search powered by an external image recognition provider. Enables store associates to search products by photographing them with the POS device camera. The Retail Cloud backend forwards the image and search parameters to this SPI endpoint and expects matching product IDs in return.

<!-- document id=f0163169c67dc5988196394e21a5dd9a2e89ed98a0904a90b0232d472f749d82 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/visual-search-via-spi.md -->

# Visual Search using SPI

With the Point of Sale Visual Search SPI, the POS app sends an image captured by a store associate to an external image-recognition provider and receives a ranked list of matching product IDs. Results are resolved against the local product catalog and displayed in the POS app. Optionally, the provider can return filters, sort options, and pagination to enable server-side refinement of results.

- Modern POS app build: 10.7.1 or later
- Platform support: iPad and iPhone
- Offline support: No

**note:** For a complete list of Point of Sale APIs and SPIs, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

## Interaction Flow

This diagram shows how the store associate, Point of Sale, and the SPI implementer interact during a visual search session.

![Sequence diagram showing the interaction flow between the store associate, Point of Sale, and the SPI implementer during a visual search session.](https://developer.salesforce.com/docs/media/retail-cloud/visual-search-interaction-flow.png)

### Required Flow (Steps 1–4)

1. The store associate captures an image in the POS app.
2. Point of Sale sends the image to the SPI provider via the `VISUAL_SEARCH_UPLOAD` connector.
3. The provider performs image recognition and returns a `searchId` along with a ranked list of matching product IDs. Optionally, the response can include `filters`, `sortOptions`, and `pagination`. See [POS Experience Based on SPI Response](#pos-experience-based-on-spi-response).
4. Point of Sale resolves the product IDs against the local product catalog and displays results to the store associate.

### Optional Flow (Steps 5–8)

If the SPI response from step 3 includes `filters`, `sortOptions`, or `pagination`, and the `VISUAL_SEARCH` connector is configured, Point of Sale renders the corresponding UI controls (filter panel, sort dropdown, page navigation).

5. The store associate applies a filter, changes sort order, or navigates to the next page.
6. Point of Sale sends a request to the SPI provider via the `VISUAL_SEARCH` connector, passing the `searchId` and the selected criteria.
7. The provider applies the criteria to the stored result set and returns an updated list of product IDs (with optionally updated filters, sort, and pagination reflecting the new state).
8. Point of Sale displays the refined results.

**note:** The second SPI call is entirely optional. If your provider doesn't support server-side filtering, sorting, or pagination, omit `filters`, `sortOptions`, and `pagination` from the upload response. The POS doesn't render these controls, and the `VISUAL_SEARCH` connector doesn't need to be configured.

## Configure Visual Search SPI

Configure one or both SPI connectors in CMS depending on whether your provider supports server-side refinement.

### Configure VISUAL_SEARCH_UPLOAD Connector

1. In CMS, go to **Integrations** | **Custom Connectors**.

2. Click **Create**.

3. For Connector Type, select **SPI**.

4. For Endpoint Name, select **VISUAL_SEARCH_UPLOAD**.

5. For API Endpoint, specify the external endpoint for image upload and recognition.

6. For Integration Type, select **MULTIPART_FORM_POST**.

7. Specify any required JSON headers. For examples, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html).

8. Configure the remaining fields as needed.

9. Save your changes.

### Configure VISUAL_SEARCH Connector (Optional)

Configure this connector only if your SPI provider supports server-side filtering, sorting, or pagination.

1. In CMS, go to **Integrations** | **Custom Connectors**.

2. Click **Create**.

3. For Connector Type, select **SPI**.

4. For Endpoint Name, select **VISUAL_SEARCH**.

5. For API Endpoint, specify the external endpoint for search refinement.

6. For Integration Type, select **HTTP_POST**.

7. Specify any required JSON headers. For example, `{"Content-Type":"application/json"}`.

8. Configure the remaining fields as needed.

9. Save your changes.

### Enable Custom API Headers (Optional)

Enable the `populateNewCustomAPIHeaders` toggle to inject contextual headers into every SPI request. For details, see [Headers Sent by Point of Sale](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html#headers-sent-by-point-of-sale).

## POS Experience Based on SPI Response

The POS experience varies depending on the content of the SPI response.

### Minimal Response (VISUAL_SEARCH_UPLOAD Only)

With a minimal response, the store associate sees a flat list of visually similar products. No pagination, filters, or sorting controls appear. This is the simplest implementation: image in, products out.

```json
{
  "searchId": "44c66064-52fb-4d60-b5f0-97ddd34b3701",
  "results": [
    "1010183BKIAD4",
    "1010183BKIADY",
    "1010183BKIAEE",
    "1010183BKIAEJ"
  ]
}
```

### Full Response (VISUAL_SEARCH_UPLOAD and VISUAL_SEARCH)

With a full response, the store associate sees product results with page navigation, a filter panel, and a sort dropdown. Selecting a filter, changing sort, or navigating pages triggers a call to the `VISUAL_SEARCH` connector.

```json
{
  "searchId": "44c66064-52fb-4d60-b5f0-97ddd34b3701",
  "results": [
    "1010183BKIAD4",
    "1010183BKIADY",
    "1010183BKIAEE",
    "1010183BKIAEJ",
    "5123274",
    "5123393",
    "6010002-1",
    "6010002-12",
    "6010002-24",
    "6010002-6",
    "6010004-12",
    "6010004-24",
    "6010004-6"
  ],
  "pagination": {
    "start": 0,
    "limit": 100,
    "totalResults": 106
  },
  "filters": [
    {
      "name": "Category",
      "displayName": "Category",
      "type": "FIELD",
      "values": [
        { "value": "Jackets" },
        { "value": "Hoodies" },
        { "value": "Vests" },
        { "value": "Cycling Computers" },
        { "value": "Cycling Locks" },
        { "value": "Coffee" },
        { "value": "Smart Dispensers" },
        { "value": "Coffee Machines" },
        { "value": "Energy Drinks" },
        { "value": "Energy Bars" },
        { "value": "Energy Gels" }
      ]
    },
    {
      "name": "Size",
      "displayName": "Size",
      "type": "FIELD",
      "values": [
        { "value": "M" },
        { "value": "L" },
        { "value": "S" },
        { "value": "XL" },
        { "value": "XS" },
        { "value": "XXL" },
        { "value": "Single Bag" },
        { "value": "12 Pack" },
        { "value": "24 Pack (Case)" },
        { "value": "6 Pack" }
      ]
    }
  ],
  "sortOptions": {
    "current": "RELEVANCE",
    "options": [
      { "key": "RELEVANCE", "label": "Relevance" },
      { "key": "PRICE_LOW_TO_HIGH", "label": "Price: Low to High" },
      { "key": "PRICE_HIGH_TO_LOW", "label": "Price: High to Low" }
    ]
  },
  "responseTime": 150
}
```

### Filter Panel

Each entry in `filters[]` becomes a section in the filter panel. The `displayName` value is the section title. Each entry in `values[]` renders as a selectable option. The order of values in the array determines the display order.

![The filter panel in the POS app showing Category and Size sections with selectable options.](https://developer.salesforce.com/docs/media/retail-cloud/pos-visual-search-filter-panel.png)

### Sort Dropdown

The `sortOptions.options[]` array renders as a dropdown list. Each option's `label` is the row text. The `key` is the value sent back to the SPI when selected. The option whose `key` matches `sortOptions.current` is pre-selected.

![The sort dropdown in the POS app showing Relevance selected, with Price: Low to High and Price: High to Low as additional options.](https://developer.salesforce.com/docs/media/retail-cloud/pos-visual-search-sort-dropdown.png)

<!-- document id=4d9665a4e3147b2f2dba69ade2ca8b87b8246730180d02536694c20399a97655 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/warranty-spi.md -->

Warranty SPI

# Warranty SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/warranty-spi/warranty-spi-oas-public.yaml)

Merchant SPI for warranty eligibility checks. Merchants implement this endpoint and configure it in CMS so the POS can retrieve eligible warranty products for merchandise items in the cart.

**Version:** 2.3.4

## Tags

### Warranty SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/warranty-spi/warranty-spi-oas-public.yaml)

Merchant SPI for warranty eligibility checks. Merchants implement this endpoint and configure it in CMS so the POS can retrieve eligible warranty products for merchandise items in the cart.

## Operations

### POST Warranty Lookup SPI

`POST /merchant/spi/sample/endpoint/sa/warranty`

Operation ID: `checkWarrantyEligibility`. Tags: Warranty SPI.

Checks warranty eligibility for merchandise items in the cart.

The POS sends cart context (store address, shipping address, customer profile, and merchandise items) to the merchant's warranty engine. The engine evaluates eligibility rules (jurisdiction, product category, loyalty tier, etc.) and returns a list of available warranty products.

Merchants must implement this endpoint per this specification and configure it in CMS under: **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**

Make sure to create the endpoint in CMS with following details

1.  Under **API Config**
    
    *   **API Key:** WARRANTY\_LOOKUP
    *   **API Endpoint:** Provide the external endpoint URL
2.  Under **JSON Config**
    
    *   **Integration Type:** HTTP\_POST
    *   **JSON Headers:** Provide the header for the api. Headers can be Content-Type eg.{"contentType": "application/json"}

**Invoke:** Called when the associate taps 'Check Warranties' on the POS cart screen. Only merchandise items are sent; warranty SKUs already in the cart are filtered out.

**Response:**

*   Return `eligibleWarrantyList` with warranty products when warranties apply
*   Return empty `eligibleWarrantyList` when no warranties apply
*   Return `errorMessage` and `errorCode` on failure (POS will surface the error)

**Notes:**

*   `warrantyProductId` must match a product in CMS configured with ProductClass rule WARRANTY\_SKU
*   `coveredProductIds` must reference `productId` values from the request's `cartItemList`
*   For CATEGORY\_BASED pricing (MVP), `quantity` should always be 1.

#### Request body

Media type: `application/json`. Schema: `SpiWarrantyCheckRequest`.

#### Responses

*   **default** default response.
    
    Media type: `application/json`. Schema: `SpiWarrantyCheckResponse`.
    

## Schemas

### SpiWarrantyCheckRequest

*   `cartId` (_string_, required) Unique identifier for the active cart session.
*   `storeAddress` (_ExternalAddress_, required)
*   `shippingAddress` (_ExternalAddress_)
*   `profile` (_ExternalCustomerProfile_)
*   `cartItemList` (_array of ExternalProduct_, required) Merchandise items currently in the cart. Warranty items (warrantySKU=true) are filtered out before this payload is sent.

### SpiWarrantyCheckResponse

*   `eligibleWarrantyList` (_array of SpiWarrantyCheckResponseItem_) Array of eligible warranty products. Empty array if no warranties apply.
*   `errorMessage` (_string_) Human-readable error message. Presence causes POS to surface an error and abort warranty application.
*   `errorCode` (_string_) Machine-readable error code, for example, SERVICE\_UNAVAILABLE or INVALID\_REQUEST.
*   `error` (_boolean_)

### ExternalAddress

Billing address.

*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, required, nullable) Customer first name saved for address.  
    Maximum length: 64.
*   `lastName` (_string_, nullable) Customer last name saved for address.  
    Maximum length: 64.
*   `addressLine1` (_string_, required, nullable) Address Line 1.  
    Maximum length: 256.
*   `addressLine2` (_string_, nullable) Address Line 2.  
    Maximum length: 256.
*   `city` (_string_, required, nullable) City.  
    Maximum length: 64.
*   `state` (_string_, required, nullable) State.  
    Maximum length: 32.
*   `postalCode` (_string_, required, nullable) Postal Code.  
    Maximum length: 16.
*   `countryCode` (_string_, required, nullable) Country Code.  
    Maximum length: 32.
*   `phone` (_string_, nullable) Phone.  
    Maximum length: 24.
*   `storeId` (_string_, nullable) Store ID if it is store address.
*   `addressType` (_string_, nullable) Address type- Home, Business.
*   `emailAddress` (_string_, nullable) Customer Email Address.  
    Maximum length: 64.
*   `country` (_string_, nullable) Country.

### ExternalCustomerProfile

Customer profile. It is mandatory for customer logged-in during the transaction. It is optional for guest customer.

*   `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer.  
    Maximum length: 128.
*   `alternateCustomerId` (_string_, nullable) Alternate Customer ID.  
    Maximum length: 128.
*   `email` (_string_, nullable) Customer Email ID.  
    Optional for guest customer. Mandatory for logged-in customer.
*   `salutation` (_string_, nullable) Salutation.
*   `firstName` (_string_, nullable) Customer first name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `secondName` (_string_, nullable) Customer second name.
*   `lastName` (_string_, nullable) Customer last name  
    Optional for guest customer. Mandatory for logged-in customer.
*   `suffix` (_string_, nullable) Suffix.
*   `phoneHome` (_string_, nullable) Phone Home.
*   `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer.
*   `phoneBusiness` (_string_, nullable) Phone Business.
*   `fax` (_string_, nullable) Fax.
*   `loyaltyId` (_string_, nullable) Loyalty Id of the customer.

### ExternalProduct

Products.

*   `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU.
*   `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID.
*   `name` (_string_, required) Name of the item.
*   `price` (_number_, required) Price of the item.
*   `quantity` (_integer (int32)_, required) Item's Quantity.
*   `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string.  
    Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`.
*   `imageURL` (_string_, required) Image URL of the item.
*   `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT.
*   `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied.
*   `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts.
*   `size` (_string_, required) Item's size.  
    Example: `39-42 or M or 38 etc...`.
*   `color` (_string_, required) Item's color.  
    Example: `Light Grey or Black etc...`.
*   `itemStatus` (_string_, required)
    
    Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below.  
    The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item.  
    To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility  
      
    
    | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility |
    | --- | --- | --- | --- | --- |
    | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. |
    | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. |
    | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. |
    | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. |
    | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. |
    | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. |
    
      
    Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`.
*   `gtin` (_string_, required) Item's GTIN.
*   `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item).  
    Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`.
*   `fulfillmentSubType` (_string_, required)
    
    1.  DEFAULT: Either item will be available from the current store for  
         cash & carry or for delivery to shipping address from a warehouse.  
          Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item  
        2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items.  
        3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store.  
        4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse.  
        5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store.  
        \----------------------------------------------------------------------------------  
        
    
    | Fulfillment Type | Fulfillment SubType | Item |
    | --- | --- | --- |
    | IN\_STORE | DEFAULT | Cash & carry |
    | ONLINE | DEFAULT | Ship to home from warehouse |
    | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out |
    | IN\_STORE | PICKUP\_LATER | Pickup from current store |
    | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store |
    | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup |
    | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) |
    | IN\_STORE | PICKUP\_NEARBY | Pickup from another store |
    
    .
    
      
    Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`.
*   `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.
*   `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID.
*   `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart.  
    Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items.
*   `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items.
*   `productClass` (_string_, required) Product class of the item.
*   `serialNumber` (_string_) Serial number of the item (if applicable).
*   `productCondition` (_string_) Product condition.  
    Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`.
*   `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item.
*   `dateTimeSlot` (_DateTimeSlot_)
*   `priceCorrection` (_ExternalProductPriceCorrection_)
*   `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items.  
    Maximum length: 32.
*   `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product.
*   `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product.  
    Points to the corresponding pickup details  
    from pickupDetailList in the transaction.  
      
    Maximum length: 128.
*   `productTax` (_ExternalProductTax_)
*   `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item.  
    It includes all the price adjustments like transaction discount, price override etc...  
    Mandatory if any type of price adjustments is applied.
*   `returnsEligibility` (_string_, nullable) Returns eligibility of the item.  
    Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`.
*   `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'.  
    Maximum length: 128.
*   `pickupStoreId` (_string_, nullable) Pickup store ID.
*   `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID.
*   `totalAdditionalCharge` (_number_, nullable) Total additional charges.
*   `tlogCustomProductAttributes` (_string_, nullable) Custom attributes.
*   `externalId` (_string_, nullable) External ID of the product.  
    Maximum length: 128.
*   `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle.
*   `noteList` (_array of ExternalNote_, nullable) Note associated with the product.
*   `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product.  
    All these attributes will be available at item level that are  
    configured in Store Setting: spiCustomProductAttributes.
    
    _Example_
    
    ```
    [
      {
        "key": "color",
        "value": "red"
      }
    ]
    ```
    
*   `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item.
*   `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store.
*   `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store.

### SpiWarrantyCheckResponseItem

Array of eligible warranty products. Empty array if no warranties apply.

*   `warrantyProductId` (_string_) Product ID of the warranty SKU. Must match a product configured in CMS.
*   `name` (_string_) Display name of the warranty shown in the warranty panel and on the receipt.
*   `price` (_number_) Total warranty price for this item.
*   `description` (_string_) Entitlement/terms text shown in the warranty panel and printed on the receipt.
*   `coveredProductIds` (_array of string_) One or more productId values from cartItemList covered by this warranty.
*   `pricingType` (_string_) Pricing type: CATEGORY\_BASED (MVP).
*   `quantity` (_integer (int32)_) Quantity. For CATEGORY\_BASED always 1.

### ExternalStoreAssociateAttribution

Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate.

*   `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction.
*   `contributionPercentage` (_number_, required) Associate's contribution towards sales.
*   `attributionNote` (_string_) Note related to attribution.
*   `firstName` (_string_, required) Associate's first name.
*   `lastName` (_string_, required) Associate's last name.

### Reason

Reason for returning the item.

*   `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT.  
    Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64.
*   `reasonCode` (_string_, required) Reason code.  
    Maximum length: 64.
*   `reasonText` (_string_, nullable) Reason text.  
    Maximum length: 256.

### DateTimeSlot

Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings.

*   `slotId` (_string_) Slot ID.  
    Example: `1234`.
*   `slotDate` (_integer (int64)_, required) Delivery date in epoch.
*   `selectedTimeSlot` (_string_, required) Time slot.  
    Example: `09:00 - 12:00`.
*   `dateTimeSlotType` (_string_, nullable) Time slot type.  
    Allowed values: `Delivery`, `Pickup`. Default: `Delivery`.

### ExternalProductPriceCorrection

Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price.

*   `originalPrice` (_number_) Original price of the item.
*   `approvingManagerId` (_string_) ID of the manager who approved the price correction request.

### ProductFormAttribute

Details about a product form attribute.

*   `key` (_string_) The identifier of the attribute.  
    Example: `color`.
*   `value` (_string_) The value associated with the key.  
    Example: `blue`.

_Example_

```
[
  {
    "key": "color",
    "value": "red"
  }
]
```

### ExternalProductTax

Tax/Vat details.

*   `totalTax` (_number_, required) Total tax. Required in case of tax countries.
*   `taxExemption` (_number_, nullable) Tax Exemption.
*   `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates.
*   `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates.
*   `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries.
*   `taxableAmount` (_number_, required) Taxable amount.

### ExternalPriceAdjustment

Price adjustments applied on the item.  
It includes all the price adjustments like transaction discount, price override etc...  
Mandatory if any type of price adjustments is applied.

*   `description` (_string_, required) Price adjustment description.
*   `adjustment` (_string_, required) Price adjustment.
*   `id` (_string_) Promotion Id for applied coupon or auto promotion.
*   `price` (_number_, required) Price adjustment amount.
*   `priceAdjustmentType` (_string_, required) Price adjustment type.  
    Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`.
*   `reason` (_Reason_)
*   `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion.  
    It is used to identify the promotion in external system and is relevant  
    only if it is configured in CMS  
    Applicable only for promotions.
*   `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied.  
    Not applicable for auto promotions,  
    manual price adjustments like price override & transaction discount.
*   `auto` (_boolean_, nullable) Applied promotion is auto or not.
*   `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format.
*   `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price.  
    Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`.
*   `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system.  
    If an order is placed directly in the POS, this identifier will not be available.  
    The external system provides this identifier, which will then be replayed to that  
    external system during order posting for any subsequent modifications like returns.  
    Maximum length: 128.

### ExternalNote

Notes for the transaction.

*   `cartId` (_string_)
*   `noteId` (_string_)
*   `noteText` (_string_)
*   `transactionId` (_string_)

### ProductTaxRate

VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable.

*   `countryCode` (_string_, required) Country Code.  
    Maximum length: 2. Example: `US`.
*   `state` (_string_, nullable) State. Applicable if the tax rate is specific to state.  
    Maximum length: 128.
*   `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code.  
    Maximum length: 10.
*   `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT.  
    Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`.
*   `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE.  
    Allowed values: `TAX`, `FEE`. Default: `TAX`.
*   `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable.  
    Default: `false`.
*   `taxRate` (_number (float)_, required) % tax/vat rate.  
    Example: `7.25`.
*   `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate.  
    Example: `Tax Class for Shoes and Clothing - PS0001`.
*   `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item.
*   `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate.  
    Example: `7.25`.
*   `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate.  
    Example: `1.25`.
*   `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag.  
    Maximum length: 64.
*   `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%.
*   `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number.  
    Example: `HST-74252RT0001`.
*   `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%.
*   `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems.
*   `isExempt` (_boolean_, nullable) Indicates if tax is exempted.  
    Default: `false`.
*   `taxDescription` (_string_, nullable) Tax Description text.
*   `jurisdiction` (_string_, nullable) Jurisdiction.  
    Maximum length: 128.
*   `registrationNumber` (_string_, nullable) Registration Number.  
    Maximum length: 128.
*   `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns.  
    Maximum length: 128.

<!-- document id=01665990e0bccfdf4a7409c4a8efdd583d537db83bb4f7678c9fa8eed1d7c170 url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/web-services/b2c-webservices.md -->

# Web Services

Salesforce B2C Commerce provides a web service framework, which helps you manage calls to web services and analyze service performance. The framework enforces limits that you configure ― limits on the overall number of calls allowed in a time interval, and limits on the number of failed calls allowed in a time interval. It also collects analytics on your web service calls.

## Overview

For each web service, the framework requires a service configuration, a service profile configuration, and a service credential configuration. You create these configurations in Business Manager.

The service configuration generates a `ServiceConfig` object. The service credential is used for basic authentication. The service profile determines how B2C Commerce manages timeouts and rate limits for the web service.

![Web service overview](https://developer.salesforce.com/media/b2c-commerce/b2c_web_services_web_services_ovr.gif)

The Web Service Script

A web service script obtains a `Service` object by calling the `LocalServiceRegistry.createService` method. The method takes two arguments: the name of a service configuration, and a script object that contains callback code that you provide.

Your script then invokes the service by calling `Service.call`. When you call this method, the framework checks if the configured rate limit or circuit breaker limit has been exceeded. If not, the framework executes the callbacks you implemented in the Service object.

When the call is complete, your script either passes the result of the successful call to the pipeline dictionary or throws an error.

**note:** If your storefront uses pipelines to call web services, the web service script is invoked by a script node within the pipeline. If your storefront uses SFRA controllers to call web services, the web service script doesn’t have to be a separate script file: it can be embedded in the controller itself.

## Creating a New Web Service

To create a web service:

1.  [Configure Web Services in Business Manager](#configuring-web-services-in-business-manager)
2.  [Code Your Web Service](#code-the-web-service-call).
3.  [Set Up Logging and Troubleshoot Your Web Service.](#web-service-logging-and-troubleshooting)
4.  Get the web service ready to go live.

## Getting the Web Service Ready to Go Live

1.  Configure credentials, private keys and certificates on the Development and Production instance. These can't be imported or exported and must be manually created on each instance.
2.  Use code replication to push your code to the Development and Production instance.
3.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Import & Export** > **Service**. Select the **Service** option to export your service, profile, and credential configurations and import them into the Development and Production instances.

## Web Service Performance and Incident Analysis

If you experience reports of problems with a specific web service on your site, in addition to logging, investigate the incident using the analytics for registered web services.

The analytics are available at Business Manager: Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Service Status**. ![Service Status](https://developer.salesforce.com/media/b2c-commerce/b2c_web_services_service_status.gif)

Click any web service name to drill down to see information about the performance of that web service. Data for a web service is available in near real time. Data is stored for up to 10 days.

![Real-Time Trend](https://developer.salesforce.com/media/b2c-commerce/b2c_web_services_service_status_trends.gif)

## Configuring Web Services in Business Manager

Use Business Manager to configure a web service.

### Create a Web Service Profile

The web service profile defines how B2C Commerce detects and manages high numbers of requests to and responses from the service, as well as its availability. Different services with similar requirements can all use the same service profile.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Services**.

2.  On the Services page, click the **Profiles** tab.

3.  On the Service Profiles page, click **New**.

4.  On the New Service Profile page, enter a descriptive name for the profile.

5.  Enter the number of milliseconds for the client connection timeout. B2C Commerce waits this number of milliseconds for a response from the web service before throwing an error.

6.  Check the **Enable Circuit Breaker** box if you want to enable the circuit breaker to identify when a service is unavailable and stop making calls to the web service.

    By default, the Enable Circuit Breaker box is checked.

    We recommend that you always enable the circuit breaker, but keep the number of calls set to zero (or blank). This enables the system-level circuit breaker.

7.  (Optional) Enter the number of calls that must fail to trigger the circuit breaker into the Max Circuit Breaker Calls field.

    If you set a value for this field, you must also set a value for the Circuit Breaker Interval (ms) field. Otherwise, leave both fields empty.

8.  (Optional) Enter the number of milliseconds in which the maximum number of calls can fail into the Circuit Breaker Interval (ms) field.

    If you set a value for this field, you must also set a value for the Max Circuit Breaker Calls field. Otherwise, leave both fields empty.

9.  Check the **Enable Rate Limit** box if you want to limit the number of outgoing calls within a specific interval.

10. Enter the maximum number of calls that B2C Commerce makes for the rate limit interval into the Max Rate Limit Calls field.

11. Enter the number of milliseconds in which B2C Commerce can make the maximum number of calls to the web service into the Rate Limit Interval (ms) field.

### Create a Web Service Credential

The web service credentials are used for basic authentication.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Services**.

2.  On the Services page, click the **Credentials** tab.

3.  On the Service Credentials page, click **New**.

4.  On the New Service Credential page, enter a name for the credential. This name can't contain spaces. Use a descriptive name, but don’t include user or password information. For example: `http.mysite.myservice.cred`.

5.  Enter the URL to the service, including the protocol. For example: `ftp://51.134.145.10`

    To use one service configuration for several URIs, extend or alter this URL using the getURL callback in the service registry definition.

6.  Enter the username for the credential.

7.  Enter the password. The password is masked after you type it and can't be retrieved from the Business Manager, so be sure to store the value securely elsewhere.

### Create a Web Service Configuration

The web service configuration specifies the credentials and web service profile that B2C Commerce uses when calling a web service.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Services**.

2.  On the Services page, click **New**.

3.  On the New Service page, enter a name for the service.

    We recommend the naming pattern `{cartridge}.{protocol}.{service}.{operation}`.

    For example: `mycartridge.http.payment.get` or `mycartridge.ftp.partner.getPriceList`.

    If service names contain periods, the period-delimited name segments become part of the logging hierarchy. Including the cartridge in the name is useful when you have multiple web service integrations, because it groups logging information and ensures unique service names.

4.  Select the service type to use for your web service. The type determines the underlying class used to call your web service and adds methods to the methods inherited from the Service class.

5.  If the web service is available and you want to make calls to it, select **Enabled**. It isn't enabled by default.

6.  In the Service Mode list, to make calls to a live web service, select **Live**. To use the mocked call configured in your service registry to simulate the expected response from the web service, select **Mocked**.

7.  Enter the name of a prefix for the log file for this service.

    If you don't enter a prefix, the log name defaults to `main`. All logs are written in the shared log directory to a file named `service-prefix-internalID-date.log`. If you don’t enter a prefix, the file is named `service-main-serviceID-date`.

8.  If you want data in the request and response of the web service call to be logged, select **Communication Log Enabled** .

    If you enable the communications log, Salesforce strongly recommends using the log filtering callback methods to remove private or sensitive data from the log messages.

9.  If you want to prevent unfiltered communication logs from being written on non-production instances, select **Force PRD behavior in non-PRD environments**.

    If you enable this setting on a non-production instance, communication logs are disallowed unless a filter is configured. If you disable this setting on a non-production instance, communication logs are allowed regardless of whether a filter is configured. This setting has no effect on production instances.

10. Select one of the service profiles.

11. Select one of the service credentials.

### Timeout for Web Services

Specify the timeout in milliseconds. This value is used for both the connection and socket timeout of any internal connection. If B2C Commerce receives no response within this time, it throws an error.

The total run time of a service can be longer than the timeout, as long as individual responses don't exceed it. For example, consider a 5000-ms timeout. A 4-second connection attempt, followed by reading two chunks of data at 4 seconds apiece, takes about 13 seconds total. Because none of the individual communications exceeded 5 seconds, the process doesn’t time out.

### Create Custom Attributes for Web Services

Customize web service configurations, credentials, and profiles by adding custom attributes to their system objects. When added to an attribute group, these custom attributes can be edited in Business Manager.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Site Development** > **System Object Types**.

2.  On the System Object Type List page, select **ServiceConfig**, **ServiceCredential**, or **ServiceProfile.**

3.  On the System Object Type List page, click the **Attribute Definitions** tab.

    If you’ve already created a custom attribute, find and add it, otherwise, proceed to the next step.

4.  On the System Object Type List page Attribute Definitions tab, click **New**.

5.  Enter the properties for the custom attribute and click **Apply**.

    These attributes are created identically to any other custom attributes.

6.  Click **\<\< Back**.

7.  Click the **Attribute Grouping** tab.

8.  On the System Object Type List page Attribute Groupings tab, click **Edit** for the section on the tab where you want to add your attributes.

    **note:** You must add the attribute to a grouping to see it in Business Manager.

9.  Click ![Browse button](https://developer.salesforce.com/media/b2c-commerce/b2c_active_merchandising_elipse_btn.gif) to browse for the custom attribute you created, check its checkbox, and click **Select**.

### Service Types

When creating a web service configuration in Business Manager, you must select a service type. The type determines the underlying class used to call your web service and adds methods to those inherited from the Service class.

- HTTP - uses `dw.net.HTTPClient`.

  Has additional methods to set authentication, encoding, output file, request method (defaults to POST), an HTTP header, and additional parameters for the URI.

  The `parseResponse` method gives the `HTTPClient` as its extra argument.

- HTTP Form - uses `dw.net.HTTPClient`.

  The createRequest method takes the parameters given to call() and construct a URL encoded form POST by default.

  Has the same additional methods as the HTTP type, allowing you to set authentication, encoding, output file, request method (defaults to POST), an HTTP header, and additional parameters for the URI.

  As with the HTTP type, the `parseResponse` method gives the `HTTPClient` as its extra argument.

- FTP - uses `dw.net.FTPClient`.

  Has a `setOperation(String, Object...)` method to set the operation to perform when executing the call to the web service. If the `setOperation` method isn't called, the execute callback defined in the web service registry is executed when the web service is called. The callback can define any number of operations to perform.

  The `parseResponse` method gives the output of the method call specified by `setOperation`, or whatever object was returned by the custom execute callback.

- SFTP - uses `dw.net.SFTPClient`. It’s otherwise identical to the `FTP` type.

- SOAP - uses `dw.ws.webReference2`.

  Requires additional methods to get the port

- Generic - Doesn’t wrap any class. Used to define custom calls.

### Web Service Rate Limiter and Circuit Breaker

The rate limiter and circuit breaker determine how many calls can be made to a web service.

#### Rate Limiter

The rate limiter allows a maximum number of calls to a web service in a specified time interval. The rate limit is checked prior to every invocation of the web service. If the rate limit is reached, a `ServiceUnavailableException` is thrown.

The timeout behavior for the rate limiter is similar to the circuit breaker timeout behavior.

#### Circuit Breaker

The circuit breaker suspends calls to a web service if a certain number of calls fail within a specified time interval.

Enable a circuit breaker for any service. The circuit breaker checks whether the limit of failed calls is reached prior to every invocation of the web service. If the limit is reached, B2C Commerce throws a `ServiceUnavailableException` rather than execute the service. Otherwise, B2C Commerce calls the web service as usual.

If the web service fails due to something detected as a misconfiguration or remote problem, then the circuit breaker is notified. These problems include:

- Issues at initial connection:
  - Unknown host
  - Connection timeout
  - Connection refused
- Protocol-specific errors, such as HTTP 500 - internal server error or HTTP 503 - service unavailable.
- Exceptions explicitly thrown as part of the service call

**note:** This list doesn't include HTTP 4xx errors. These are used to indicate the client is doing something wrong, but the remote server itself is fine. Assuming whatever underlying issue is causing problems is addressed, service calls return to normal as the circuit breaker timeouts expire.

Circuit Breaker Timeout Behavior

The timeout caused when the circuit breaker reaches its limit is calculated dynamically. Each time a registered web service wrapper is called, the circuit breaker is checked. If the circuit breaker is triggered, then the call isn't made. In the example below, a web service is triggered every millisecond. In this example, the circuit breaker is configured with a maximum of three failed calls per 6 milliseconds.

![Circuit breaker timeout behavior](https://developer.salesforce.com/media/b2c-commerce/b2c_web_services_web_services.gif)

## Create a Service Instance

A service instance is a single-use object used to call a remote web service.

Use the `dw.svc.LocalServiceRegistry.createService()` method to create a service instance. This method takes two arguments:

- The ID of a service configured in Business Manager
- A configuration object with callback handlers that you implement

The callbacks contain code that is executed at appropriate times by the service framework. For example, an HTTP or FTP service instance typically implements three callbacks: `createRequest`, `parseResponse`, and (for testing) `mockCall`.

A SOAP service implements two more callbacks: `initServiceClient` and `execute`.

## Example: Create an FTP Service Instance

The following FTP service instance executes a single FTP operation (list):

```javascript
//LocalServiceRegistry.createService creates an instance of MyFTPService

var myFTPService = LocalServiceRegistry.createService("MyFTPService", {
  // Three callback handlers are invoked by the Service Framework
  // for FTP services at appropriate times

  // Callback handler to construct request

  createRequest: function (svc: FTPService, params) {
    svc.setOperation("list", "/");
  },

  // Callback handler to parse response

  parseResponse: function (svc: FTPService, params) {
    var x: Array = [];
    var resp: Array = params;
    for (var i = 0; i < resp.length; i++) {
      var f = resp[i];
      x.push({ name: f["name"], timestamp: f["timestamp"] });
    }
    return x;
  },

  // Callback handler to test the service using a mock response

  mockCall: function (svc: FTPService, params) {
    return [
      { name: "file1", timestamp: new Date(2011, 02, 21) },
      { name: "file2", timestamp: new Date(2012, 02, 21) },
      { name: "file3", timestamp: new Date(2013, 02, 21) },
    ];
  },
});
```

## Creating Service Callbacks

When you use `dw.svc.Service.call(Object...)` to invoke a web service, the service framework checks whether the call exceeds either the rate limiter or circuit breaker thresholds and, if not, makes the call. When making a call, the framework invokes the callbacks you implemented in your service instance.

Each callback corresponds to one of the callback methods defined by the `dw.svc.ServiceCallback` class. These methods are called in the following order:

1.  `initServiceClient(Service)` ― Creates the underlying client used to make the call. Required only for SOAP Services. Other client types are created automatically.
2.  `createRequest(Service, Object...)` ― Given arguments to the `Service.call(Object...)`, configure the actual service request. This may include setting request headers, defining the message body, and so on.
3.  `execute(Service, Object)` ― Perform the actual request. At this point the client has been configured with the relevant credentials, so the call should be made. This is required for SOAP services.
4.  `parseResponse(Service, Object)` ― Convert the result of the call into an object to be returned from the `Service.call(Object...)` method.

Some callback methods may be optional, depending on the type of service.

Every callback method requires a `Service` object (for a generic service) or one of its subclasses (`FTPService`, `HTTPFormService`, `HTTPService`, `or SOAPService`).

### HTTP and HTTP Form Callbacks

For an HTTP service, pass in `HTTPService` objects. For an HTTP form, pass in `HTTPFormService` objects.

Recommended callbacks for HTTP services:

- `createRequest`: Required to create a `requestData` object. If you need additional processing, pass the `requestData` object to the `execute` callback. Otherwise, the `requestData` object is used to call the web service when the `Service` object is invoked.
- `parseResponse`: Gives the `HTTPClient` as its extra argument. Use to parse the response contained in the `Service` object.

### FTP and SFTP Callbacks

For an FTP or SFTP service, pass in `FTPService` objects.

Recommended callbacks

- `createRequest`: Required to create a `requestData` object. If you need additional processing, pass the `requestData` object to the execute callback. Otherwise, the `requestData` object is used to call the web service when the `Service` object is called.
- `parseResponse`: Gives the `FTPClient` as its extra argument. Use to parse the response contained in the `Service` object.
- `execute`: If the `setOperation` method isn't called in the web service script, operations defined in the execute callback are executed when the web service is invoked. Use the execute method to perform multiple operations in sequence.

### SOAP Callbacks

For any SOAP service, pass in a `SOAPService` object.

Recommended callbacks

- `initServiceClient`: Implement to return a `dw.ws.port` and `webreferences2` object.
- `createRequest`: Required to create a `requestData` object. This object must be passed to the execute method.
- `execute`: Specifies additional processing for the web service request.

  **note:** If you get your port in this step, instead of in the `initServiceClient` callback, any timeouts you set will override those set in the service configuration. This isn't recommended.

- `parseResponse`: Use this method to parse the response in the `Service` object.

### Generic Callbacks

Doesn’t wrap any class. Used to define custom calls.

- `createRequest:` Required to create a `requestData` object. If you need additional processing, pass the `requestData` object to the execute callback. Otherwise, the `requestData` object is used to call the web service when the `Service` object is called.
- parseResponse: Use to parse the response contained in the `Service` object.

**note:** You must pass a plain Service object, rather than a subclass, for this callback method.

### Mock Callbacks

Mock web service responses in two ways.

First, configure the web service to use mock responses:

1.  In Business Manager, click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Operations > Services**. For the Service Mode, select **Mocked**.
2.  Provide a `mockCall` callback handler. For example, in your web service script:

```javascript
mockCall: function(svc:HTTPService, client:HTTPClient){
    return {
        statusCode: 200,
        statusMessage: "Success",
        text: "MOCK RESPONSE (" + svc.url + ")"
        };
    }
```

Force a mock call, regardless of configuration. Add a mock method to your service definition and then call it explicitly in your web service script. Remove this method from your script when testing live web service calls.

```javascript
result = service.setMock().call();
```

## Code the Web Service Call

The general approach to coding web services in Salesforce B2C Commerce involves writing a script for a RESTful web service and storing credentials or certificates in the Business Manager.

The web service script:

- gets `Service` objects from the registry
- provides input parameters for the `createRequest` callback used to construct the URL to call the web service
- provides error handling based on the `Result` of the web service call
- writes output variables to the pipeline dictionary to be used by the rendering template

If you’re implementing a SOAP web service or require WS-Security features, write a script that uses the `dw.ws` package to implement web services. In this case, certificates must be stored in your cartridge.

### Creating a Controller for Web Services

When creating a controller for web services, you usually must include error handling and render the results of the web service call.

### Understanding Pipelines for Web Services in Legacy Implementations

If you’re maintaining an older cartridge that uses pipelines, web services are implemented in a pipeline with a script node for the web service script. The script node must have an error transition for error handling and a transition to a rendering template if you must render the results of the web service call.

### Creating a Web Service Script

Your web service script must import the `dw.svc`package.

Use `LocalServiceRegistry.createService` to create a `Service` object. Your script can modify or extend the `Service` object. Also include business logic to control the parameters used to invoke the web service.

Use `Service.call` to invoke the web service.

When the service is invoked, the service framework checks the circuit breaker and rate limiter. If either the circuit breaker or rate limiter are triggered, then no call is made and the appropriate errors are logged. If neither are triggered, then the callback methods in the service instance are executed, and the `dw.svc.Result` object is stored in the `Service`.

Example 1: Simple FTP Service Call

In this example, the operation invoked for the web service is determined by an input variable passed from the pipeline. In the dictionary bindings for the script node, the `numCalls` variable is bound to `CurrentHttpParameterMap.numCalls.stringValue` and the `testType` variable is bound to `CurrentHttpParameterMap.testType.stringValue`.

```javascript
/**
 *  testFTPClient.ds
 *

 *   @input testType : String
 *   @input numCalls : String
 *   @output svcConfig : dw.svc.Service
 *   @output ftpResult : dw.svc.Result
 *
 */
importPackage(dw.util);
importPackage(dw.svc);
importPackage(dw.net);
importPackage(dw.io);

function execute(args: PipelineDictionary): Number {
  var service: Service;
  var result: Result;
  var counter = args.numCalls;
  var mockCall = false;
  var pipelineError = false;

  var callTestFTP = LocalServiceRegistry.createService("test.ftp", {
    mockCall: function (svc: FTPService, params) {
      return [
        {
          name: "testfile1",
          timestamp: new Date(2011, 02, 21),
        },
        {
          name: "testfile2",
          timestamp: new Date(2012, 02, 21),
        },
        {
          name: "testfile3",
          timestamp: new Date(2013, 02, 21),
        },
      ];
    },
    createRequest: function (svc: FTPService, args) {
      return svc;
    },
    parseResponse: function (svc: FTPService, result: Array) {
      var ret: Array = [];
      for (var i = 0; i < result.length; i++) {
        ret.push(result[i].name);
      }
      ret.sort();
      return ret;
    },
  });

  // Execute the request on the service configuration
  function makeCall(svcConfig: Service, params: Object) {
    if (counter == null) {
      counter = 1;
    }

    while (counter != 0) {
      if (mockCall) {
        result = service.setMock().call(params);
      } else if (pipelineError) {
        result = service.setThrowOnError().call(params);
      } else {
        result = service.call(params);
      }
      counter--;
    }

    // Set pdict out values
    args.svcConfig = service;
    args.ftpResult = result;
  }

  switch (args.testType) {
    case "LIST":
      service = callTestFTP;
      service.setOperation("list");
      break;
    case "CD":
      service = callTestFTP;
      service.setOperation("cd", "/");
      break;
    case "MKDIR":
      service = callTestFTP;
      service.setOperation("mkdir", "test");
      break;
    case "DELETE":
      service = callTestFTP;
      service.setOperation("del", "test");
      break;
  }

  makeCall(service);

  if (result == null || service == null) {
    return PIPELET_ERROR;
  }

  return PIPELET_NEXT;
}
```

Example 2: Modifying the Service Object for an HTTP Service

This example demonstrates how to use the methods on the `Service` object to modify the `Service` object before invoking the service. The ENCODING case in this example adds a header, URL parameters, and changes the encoding before invoking the service.

```javascript
/**
 * testHTTPClient.ds
 *
 *   @input testType : String the type of test to run.
 *	 @input numCalls : String the number of calls to make.
 *   @input returnCode : String the simulated http return code.
 *	 @output svcConfig : dw.svc.Service the service configuration object.
 *   @output httpResult : dw.svc.Result the http result object.
 *
 */
importPackage(dw.system);
importPackage(dw.svc);
importPackage(dw.net);
importPackage(dw.io);

function execute(args: PipelineDictionary): Number {
  var service: Service;
  var result: Result;
  var counter = args.numCalls;
  var mockCall = false;
  var pipelineError = false;
  var returnCode = args.returnCode;
  var requestBody = {
    testString: "foo",
    testNum: 5,
    testBool: true,
  };

  var callTestGet = LocalServiceRegistry.createService("test.http.get", {
    createRequest: function (svc: HTTPService, args) {
      svc.setRequestMethod("GET");
    },
    parseResponse: function (svc: HTTPService, client: HTTPClient) {
      return client.text;
    },
    mockCall: function (svc: HTTPService, client: HTTPClient) {
      return {
        statusCode: 200,
        statusMessage: "Success",
        text: "MOCK RESPONSE (" + svc.URL + ")",
      };
    },
    filterLogMessage: function (msg: String) {
      return msg.replace("headers", "OFFWITHTHEHEADERS");
    },
  });

  var callTestPost = LocalServiceRegistry.createService("test.http.post", {
    createRequest: function (svc: HTTPService, args) {
      // Default request method is post
      // No need to setRequestMethod
      if (args) {
        svc.addHeader("Content-Type", "text/json");
        return JSON.stringify(args);
      } else {
        return null;
      }
    },
    parseResponse: function (svc: HTTPService, client: HTTPClient) {
      return client.text;
    },
  });

  var callTestPut = LocalServiceRegistry.createService("test.http.put", {
    createRequest: function (svc: HTTPService, args) {
      svc.setRequestMethod("PUT");
      if (args) {
        svc.addHeader("Content-Type", "text/json");
        return JSON.stringify(args);
      } else {
        return null;
      }
    },
    parseResponse: function (svc: HTTPService, client: HTTPClient) {
      return client.text;
    },
  });

  var callTestDelete = LocalServiceRegistry.createService("test.http.delete", {
    createRequest: function (svc: HTTPService, args) {
      svc.setRequestMethod("DELETE");
    },
    parseResponse: function (svc: HTTPService, client: HTTPClient) {
      return client.text;
    },
  });

  var callTestBasicAuth = LocalServiceRegistry.createService("test.http.basicauth", {
    createRequest: function (svc: HTTPService, args) {
      svc.setRequestMethod("GET");
      svc.setAuthentication("BASIC");
    },
    parseResponse: function (svc: HTTPService, client: HTTPClient) {
      return client.text;
    },
  });

  var callTestTimeout = LocalServiceRegistry.createService("test.http.timeout", {
    createRequest: function (svc: HTTPService, args) {
      svc.setRequestMethod("GET");
    },
    parseResponse: function (svc: HTTPService, client: HTTPClient) {
      return client.text;
    },
  });

  var callTestStatus = LocalServiceRegistry.createService("test.http.status", {
    createRequest: function (svc: HTTPService, args) {
      svc.setRequestMethod("GET");
    },
    parseResponse: function (svc: HTTPService, client: HTTPClient) {
      return client.text;
    },
  });

  // Execute the request on the service configuration
  function makeCall(svcConfig: Service, params: Object) {
    if (counter == null) {
      counter = 1;
    }

    while (counter != 0) {
      if (mockCall) {
        result = service.setMock().call(params);
      } else if (pipelineError) {
        result = service.setThrowOnError().call(params);
      } else {
        result = service.call(params);
      }
      counter--;
    }

    // Set pdict out values
    args.svcConfig = svcConfig;
    args.httpResult = result;
  }

  switch (args.testType) {
    // make a GET request with additional headers, query param, json payload
    case "GET":
      service = callTestGet;
      service.URL += "/get";
      service.addHeader("testHeader", "testHeaderValue").addParam("filter", true);
      break;

    // make a POST request with additional headers, query param, json payload
    case "POST":
      service = callTestPost;
      service.URL += "/post";
      service.addHeader("testHeader", "testHeaderValue");
      break;

    // make a POST request with additional headers, query param, json payload, using UTF-16 encoding
    case "ENCODING":
      service = callTestPost;
      service.setEncoding("UTF-16");
      break;

    // make a PUT request with additional headers, query param concatenation, json payload
    case "PUT":
      service = callTestPut;
      service.URL += "/put";
      service.addParam("filter", true).addParam("secondParamAmpersand", 1);
      break;

    // make a DELETE request with additional headers, query param, json payload
    case "DELETE":
      service = callTestDelete;
      service.URL += "/delete";
      service.addHeader("testHeader", "testHeaderValue").addParam("filter", true);
      break;

    // make an HTTP post with BASIC auth.
    case "BASICAUTH":
      service = callTestBasicAuth;
      service.URL += "/basic-auth/user/passwd";
      break;

    // make a GET request with timeout
    case "TIMEOUT":
      service = callTestTimeout;
      service.URL += "/delay/6";
      break;

    // make a GET request and write result object to file
    case "OUTFILE":
      service = callTestGet;
      service.setOutFile(File("TEMP/" + Math.random()));
      break;

    // make a GET request in explicit mock mode
    case "MOCKED":
      service = ServiceRegistry.get("test.http.get");
      mockCall = true;
      break;

    // make a GET request and test ratelimit
    case "RATELIMIT":
      service = callTestGet;
      service.URL += "/get";
      break;

    // make a GET request with status code return as specified by returnCode pipeline query param
    case "STATUS":
      service = callTestStatus;
      if (returnCode == null) {
        trace("No return code provided");
      }
      service.URL += "/status/" + returnCode;
      break;

    // make a GET request and throwOnError() to have PIPELINE handle response error.
    case "THROWONERROR":
      service = callTestStatus;
      service.URL += "/status/" + 500;
      counter = 20;
      pipelineError = true;
      break;
  }

  // Make the service call here
  makeCall(service, requestBody);

  if (result == null || service == null) {
    return PIPELET_ERROR;
  }

  return PIPELET_NEXT;
}
```

### Error Handling

Information on the service status is stored in the Result object. Use methods on the object to determine the status of the service and any error it has returned:

- `result.error`- service-type specific error code, such as a 404 for an HTTP service.
- `result.errorMessage` - error message information, such as a Java exception

Call .setThrowOnError when calling the service to throw a JavaScript error if the result status isn’t OK:

```javascript
result = service.setThrowOnError().call();
```

## Configure Underlying Clients

The service framework wraps most functionality of the underlying clients (FTPClient, HTTPClient, and so on), but directly configure the underlying clients when needed.

For example, if you want to cache web service calls for `HTTPService`, in your `createRequest` callback, use the `getClient` method to get the underlying `HTTPClient` object for the service and use the `HTTPClient` class `enableCaching` method to cache the request.

```javascript
LocalServiceRegistry.createService("yourService", {
     createRequest: function(svc:HTTPService, args) {
          svc.client.enableCaching(1000);
[...]
```

**note:** Make sure to use getClient and any HTTPClient methods in the createRequest callback or later callbacks, not when you get the service object from the registry. This is because the underlying HTTPclient object isn't initialized until you call the service using the createRequest object. Before calling the service, using getClient only returns null.

Cached requests are seen in the dashboard and expect lower average execution times after caching is enabled. Cached requests are counted toward rate limits, circuit breakers, and statistics, because all of these are measured at the service level and are triggered by calls to the service.

## Web Service Logging and Troubleshooting

View generated logs by navigating in Business Manager to **Administration** > **Site Development** and clicking the link for Log files.

The log file name for a web service always starts with "service" then the log prefix set in the web service profile, and then internal information. For example: `service-logprefix-blade2-4-appserver-20150206.log.`

Salesforce B2C Commerce logs messages to a custom log category with the following format:

```javascript
service.serviceName.type;
```

Type is one of the following:

- head: After every service call, logs a message indicating success or failure.
- comm: After every service call, logs data passed to the underlying transport and the response received from it. Communication logs are disabled by default and log at the INFO level when enabled. This means in order to see communication logs, a service must have its **Communication Log Enabled** box checked and its log level must be `info` or `debug`.

  The comm logging is filtered to prevent sensitive data from being accidentally logged on a Production instance. The logging of filtered data is possible, but only by enabling communication logging for the service and also applying the `filterLogMessage` function or applying both the `getRequestLogMessage` and `getResponseLogMessage` functions in the service initialization. Importing a service definition with communication logging enabled on a Production system doesn't enable this logging and throws a warning message in the import log indicating that communication logging is disabled. This is a fail-safe to prevent accidentally enabling communication logging that could contain sensitive data. Force non-production instances to behave like production instances by checking the **Force PRD behavior in non-PRD environments** box.

- log: Logs miscellaneous messages, such as service initialization and error traces

For example, given three services: `mycartridge.http.payment.list`, `mycartridge.http.payment.get`, and `mycartridge.ftp.getPriceList`; this creates the following logging structure:

```txt
service
  .mycartridge
    .ftp
      .getPriceList
          .comm
          .head
          .log
   .http
      .payment
          .get
             .comm
             .head
             .log
          .list
             .comm
             .head
             .log
```

**note:** There are two custom log quotas, one for size (10MB) and one for log file prefixes (40). Although service logs are created and managed in the same place, unlike custom logs, service logs only count toward the size quota (10MB).

Setting Log Levels

Log levels are adjusted by clicking App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then selecting **Administration** > **Operations** > **Custom Log Settings**.

**note:** If a logging category doesn't have a log level specified, it inherits its parent log levels. This allows groups of services to have their logging enabled/disabled at the same time.

For example: for the services described above, you might create the following log categories.

Warn

| Enable | Log Category            |
| ------ | ----------------------- |
|        | services                |
| ✔      | mycartridge.service.ftp |

Info

| Enable | Log Category                          |
| ------ | ------------------------------------- |
|        | mycartridge.service.http.payment      |
| ✔      | mycartridge.service.http.payment.list |

Debug

| Enable | Log Category                              |
| ------ | ----------------------------------------- |
| ✔      | mycartridge.service.http.payment.get      |
| ✔      | mycartridge.service.http.payment.list.log |

In this example, everything in the `services.ftp` category is set to the `warning` log level, so `comm` logs aren't generated for the `mycartridge.ftp.getPriceList` service. The `mycartridge.http.payment.get` category generates `head`, `comm`, and `log` logs with `debug` level logging. The `mycartridge.http.payment.list` category generates `head` and `comm` logs with `info` level logging and a `log` log with `debug` level logging.

Filtering Logs

You might need to filter sensitive or private data, such as credit card numbers, so that it's not logged. Do this in two ways:

Example 1: Filter a System-Provided Log Message

This example shows how to add a `filterLogMessage` callback to the service definition to filter log messages.

```javascript
ServiceRegistry.configure("my.service", {
    createRequest: ...,
    parseResponse: ...,
    filterLogMessage: function(msg:String): {
        return msg.replace(/CreditCardNo\: \".*?\"/, "CreditCardNo:********");
    }
});
```

Example 2: let the `ServiceCallback` provide the log message

This example shows how to capture log messages using `getRequestLogMessage`, convert them to log messages and filter or edit them.

```javascript
ServiceRegistry.configure("my.service", {
    createRequest: ...,
    parseResponse: ...,
    getRequestLogMessage: function(reqObj:Object): {
        // Convert to a String here, doing any filtering...
        return msg;
    },
    getResponseLogMessage: function(respObj:Object): {
        // Convert to a String here, doing any filtering...
        return msg;
    }
});
```

Web service response Examples

This section shows typical responses from a simple web service.

Using HTTPResult as an example (all other result objects for other service types follow the same schema):

for a Simple HTTP GET Request That Was Successful, You Get Back:

```txt
[ error=0, errorMessage=null, mockResult=false, msg=OK, object=<html>…</html>, ok=true, status=OK ]
```

for a Simple HTTP GET Request That Failed, You Get Back:

```txt
[ error=500, errorMessage=null, mockResult=false, msg=INTERNAL SERVER ERROR, object=null, ok=false, status=ERROR ]
```

for a Simple HTTP GET Request That Failed Due to 404, You Get Back:

```txt
[ error=404, errorMessage=null, mockResult=false, msg=NOT FOUND, object=null, ok=false, status=ERROR ]
```

When You Hit the Rate Limit, You Get Back:

```txt
[ error=0, errorMessage=Rate Limit Exceeded, mockResult=false, msg=null, object=null, ok=false, status=SERVICE_UNAVAILABLE ]
```

When You Hit the Circuit Breaker, You Get Back:

```txt
[ error=0, errorMessage=Failure Count Exceeded, mockResult=false, msg=null, object=null, ok=false, status=SERVICE_UNAVAILABLE ]
```

When You Hit the Timeout, You Get Back:

```txt
[ error=0, errorMessage=SocketTimeoutException:Read timed out, mockResult=false, msg=Read timed out, object=null, ok=false, status=SERVICE_UNAVAILABLE ]
```

### Troubleshooting Web Services

In Business Manager:

- make sure the cartridge containing your script is in the cartridge path.
- make sure that the web service is enabled.
- make sure that the web service is set to **Live** and not **Mocked**.

In UX Studio:

- make sure that you point to your initialization script in your package.json.
- make sure that your initialization script has a service definition for your web service.
- make sure that your service definition includes callback objects that handle the web service response.
- make sure that you’ve written a script that calls your web service
- Make sure that your web service is available.

## SOAP Web Services

When you upload and run a pipeline with a script node that uses a `WebReference2` object to invoke a WSDL file, Salesforce B2C Commerce automatically generates classes from the WSDL using Apache CXF.

The generated classes are automatically added to the `webreferences2` package. You use the generated classes in a B2C Commerce script to call the web service operations and process any response from the web service.

B2C Commerce implements SOAP web services through the `dw.ws` package `port`, `webreference2`, and `WSUtil` classes.

Overview

The diagram below assumes you’re using the `dw.ws` package to implement web services.

![Web Services SOAP Overview](https://developer.salesforce.com/media/b2c-commerce/b2c_web_services_soap_ovr.gif)

For additional information about transport-layer and application-layer security, see [Web Service Security](#web-service-security.

B2C Commerce also maintains a legacy implementation that uses the `webreferences` object and Axis 1.4 to generate classes from the WSDL. This legacy implementation is deprecated and will be removed in a future release.

### Supported Standards

- SOAP 1.1 and SOAP 1.2
- WSDL 1.1
- Apache CXF
- JAX-WS for all features except WS-addressing, attachments, or asynchronous calls.
- https 1.0 and 1.1

**note:** RPC/Encoded WSDLs aren’t supported. However, we do support RPC/Literal, Document/Encoded, and Document/Literal WSDLs.

### SOAP Web Service Implementation

Integrating a web service into your storefront is relatively straightforward.

1.  Create the following files:

    - _filename_.wsdl - the WSDL file for the web service.
    - _filename_.jks - (optional) if you’re using a java keystore file for WS-Security, it must have the same filename as the WSDL.
    - _filename_.wsdl.properties - (optional) if you’re using the properties file to generate fully qualified class names to avoid class name collisions.See [Resolving Namespace Collisions for WSDLs and Associated Files](#resolving-namespace-collisions-for-wsdls-and-associated-files) below.

    **note:** The _filename_ for all three files must be identical for the files to be used by B2C Commerce. For example, if your WSDL file is named `HelloWorld.wsdl`, then the other files in the directory must be named `HelloWorld.wsdl.properties`, and `HelloWorld.jks`.

    **important:** If you have elements in a WSDL schema that contain the underscore character, Webreferences2 can encounter problems during code generation. To resolve this problem, use the `underscoreBinding=asCharInWord` property to control code generation. To direct Webreferences2 to use the `underscoreBinding` property, create a properties file in the same directory as the WSDL file. The name of the property file is `<wsdl_name>.wsdl.properties`, where `<wsdl_name>` is the name of the WSDL file. Also, if you’re migrating from Webreferences to Webreferences2, expedite the process by directing Webreferences2 to generate arrays instead of lists. To specify that you want to use arrays instead of lists, set `collectionType=indexed` in the `<wsdl_name>.wsdl.properties` properties file.

2.  Place the files in the `webreferences2` folder in your cartridge.
3.  Add a service definition to your service registry script for the SOAP web service.

    Example; Simple SOAP ServiceDefinition

    ```javascript
    {
        initServiceClient: function() {
            // Storing this in a custom attribute so it can be used later
            this.webReference = webreferences.LuhnChecker;
            // The return here is the 'svc.serviceClient' in subsequent calls
            return webReference.getDefaultService();
        }
        createRequest: function(svc:SOAPService, param1) {
            var requestObject = new this.webReference.CheckCC();
            requestObject.setCardNumber(param1);
            return requestObject;
        },
        execute: function(svc:SOAPService, requestObject) {
            return svc.serviceClient.checkCC(requestObject);
        },
        parseResponse: function(svc:SOAPService, responseObject) {
            var responseWrapper = {};
            responseWrapper.type = responseObject.checkCCResult.cardType;
            responseWrapper.valid = responseObject.checkCCResult.cardValid;
            return responseWrapper;
        }

    }
    ```

    The ServiceDefinition must specify:

    - initServiceClient callback to get the following using the `dw.ws` package:

      - a `WebReference2` object
      - a service port
      - WSDL request parameters
        This callback must also set the serviceClient property for the Service.

      The webreference2 object is required to generate the classes for the WSDL, which you must use to call the web service. When you’ve created this callback call the pipeline to generate the API for the WSDL. You might want to skip to the steps where you develop the pipeline and run it, so that you have the WSDL API available, and then finish the task of creating the service definition.

    - createRequest callback to set the WebReferences2 method to call and return a requestData object. If you’re using WS-Security, this is where you’ll construct the security hashmap.

      1.  To implement transport layer security for TLS/SSL, add the certificates that you want to use for your SSL connection, to your instance using Business Manager. See [Importing Certificates for an Instance.](#import-3rd-party-private-keys-and-certificates-for-an-instance)
      2.  To implement WS-Security to sign, encrypt or decrypt soap messages:

          - for a JAX-WS web service, using the `dw.ws` package:

            1.  Get a certificate from a known certificate authority or trusted provider to sign the SOAP message to the web service. You must provide a keystore for the WS-Security actions: Signature, Encryption, and Decryption.
            2.  Place the keystore in the webreferences2 folder in the same cartridge as the WSDL file.

                **note:** The name of the keystore must be the same as the WSDL file and the file extension must be that of the keystore type (jks or pkcs12). For example, for the `CheckFraud.WSDL` service and a pkcs12 keystore type, the keystore must be named `CheckFraud.pkcs12`.

            3.  In your B2C Commerce script that invokes the web service, create a request and response security configuration. The security configuration is a HashMap, whose first element defines the actions you want B2C Commerce to take: whether to add a timestamp, encrypt the message, sign the message, or other actions. The other elements in the HashMap assign a value to constants defined for the WSUtil class.

                Create a separate security configuration for the request messages and the response messages and pass them both into the `setWSSecurityConfig(port : Object, requestConfigMap : Map, responseConfigMap : Map)` class to set the request and response security configuration for the web service.

                Example:

                ```javascript
                // define a map with all the secrets
                var secretsMap: Map = new HashMap();
                secretsMap.put("myclientkey", "ckpass");
                secretsMap.put("myservicekey", "ckpass");
                secretsMap.put("username", "password");

                var requestCfg: Map = new HashMap();

                // define the ws actions to be performed - in this case add a username token, timestamp,
                // sign and encrypt the message
                requestCfg.put(
                  WSUtil.WS_ACTION,
                  WSUtil.WS_USERNAME_TOKEN +
                    " " +
                    WSUtil.WS_TIMESTAMP +
                    " " +
                    WSUtil.WS_SIGNATURE +
                    " " +
                    WSUtil.WS_ENCRYPT,
                );
                requestCfg.put(WSUtil.WS_USER, "username");
                requestCfg.put(WSUtil.WS_PASSWORD_TYPE, WSUtil.WS_PW_DIGEST);
                requestCfg.put(
                  WSUtil.WS_SIG_DIGEST_ALGO,
                  "http://www.w3.org/2001/04/xmlenc#sha256",
                );

                // define signature properties
                // the keystore file has the basename of the WSDL file and the
                // file extension based on the keystore type (for example, HelloWorld.jks).
                // The keystore file has to be placed beside the WSDL file.
                requestCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_TYPE, "jks");
                requestCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_PW, "cspass");
                requestCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_ALIAS, "myclientkey");

                requestCfg.put(WSUtil.WS_SIGNATURE_USER, "myclientkey");

                // define enrcryption properties
                requestCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_TYPE, "jks");
                requestCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_PW, "cspass");
                requestCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_ALIAS, "myservicekey");

                requestCfg.put(WSUtil.WS_ENCRYPTION_USER, "myservicekey");
                requestCfg.put(
                  WSUtil.WS_SIGNATURE_PARTS,
                  "{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body",
                );
                requestCfg.put(
                  WSUtil.WS_ENCRYPTION_PARTS,
                  "{Element}{" +
                    WSU_NS +
                    "}Timestamp;" +
                    "{Content}{http://schemas.xmlsoap.org/soap/envelope/}Body",
                );

                // set the secrets for the callback
                requestCfg.put(WSUtil.WS_SECRETS_MAP, secretsMap);

                var responseCfg: Map = new HashMap();

                // define the ws actions to be performed for the response
                responseCfg.put(
                  WSUtil.WS_ACTION,
                  WSUtil.WS_TIMESTAMP + " " + WSUtil.WS_SIGNATURE + " " + WSUtil.WS_ENCRYPT,
                );

                // define signature properties
                responseCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_TYPE, "jks");
                responseCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_PW, "cspass");
                responseCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_ALIAS, "myservicekey");

                responseCfg.put(WSUtil.WS_SIGNATURE_USER, "myservicekey");

                // define decryption properties
                responseCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_TYPE, "jks");
                responseCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_PW, "cspass");
                responseCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_ALIAS, "myclientkey");

                responseCfg.put(WSUtil.WS_ENCRYPTION_USER, "myclientkey");

                // set the secrets for the callback
                responseCfg.put(WSUtil.WS_SECRETS_MAP, secretsMap);

                // set the security
                WSUtil.setWSSecurityConfig(port, requestCfg, responseCfg);
                ```

          **note:** You must create a pipeline, even if you intend to call the script using a hook for an OCAPI application, because you must run the pipeline to generate the classes for the WSDL. To generate the classes, the script must get a `webreferences2` object. When the classes are generated, however, call the script using an OCAPI hook. However, if the WSDL changes and you need to generate a new version of the classes, you must run the pipeline again.

    - execute callback to make the service call.
    - parseResponse to parse the result of the call.

4.  Make sure your cartridge is in the path for your instance and upload the cartridge to the server. This initializes the Service objects, so that they can be accessed when calling web services.
5.  Develop a pipeline to call the web service and create a script node that points to your web service script.
6.  Execute the pipeline in the storefront, either by navigating to a page that calls the pipeline or by calling the pipeline manually, by adding the pipeline to the end of the URL after the site name. For example: `www.mycompany.com/default/Pipeline-Start`
7.  Download the classes generated by B2C Commerce in Studio. Click ![Site Development DW Server Connection](https://developer.salesforce.com/media/b2c-commerce/b2c_site_development_dw_server_connection.gif), select your server connection, select **CommerceCloudServer**, and then **Download Web Service API**.

    **note:** You must execute the pipeline at least once to generate the classes.

    **tip:** You must create a pipeline, even if you intend to call the script using a hook for an OCAPI application, because you must run the pipeline to generate the classes for the WSDL. To generate the classes, the script must get a `webreferences2` object. When the classes are generated, however, call the script using an OCAPI hook. However, if the WSDL changes and you must generate a new version of the classes, you must run the pipeline again.

    **important:** The `WebReference2` script class generation process uses the name of the WSDL service and port elements to create a class representing the service or port. If the service or port name contains an underscore character, the generated class name might or might not contain the underscore character based on naming rules used in the code generation process. Regardless of this, calling `WebReferences2.getDefaultService()` or `WebReferences2.getService(String, String)` resolves the service and port element names to the corresponding script classes.

8.  Create an ISML template to show the results of the web service and trigger a page refresh when the information shown changes.
9.  Troubleshoot any errors using the request log and customerror development logs. See [Troubleshooting Web Services](#troubleshooting-web-services) below.

See [Web Service Security](#web-service-security).

### Application-Layer Security with X509 Certificates for Signing and Encryption

Some web service integrations require the use of public key infrastructure (PKI) for application-layer web security, in which any messages exchanged are signed or encrypted to make sure that messages aren’t tampered with. A web service might also require secure communication with certificates issued by a known certificate authority, such as VeriSign, GoDaddy, or Comodo.

**note:** X509 certificates are used for application layer security. See [Web Service Security](#web-service-security).

### Resolving Namespace Collisions for WSDLs and Associated Files

When calling a web service from a script file, B2C Commerce generates `dw.ws.Port` and supporting classes, using the default namespace `webreferences2.<wsdl_file_name>.`

If your web service WSDL has many different types with the same name, compilation errors can occur because the type classes are all put in the same namespace package. To resolve this issue, specify that you want B2C Commerce to generate a namespace-aware `Port` and supporting classes, by including a properties file in the same location as your WSDL file. In this properties file, you specify the property as follows:

```javascript
namespace = true;
```

For B2C Commerce to apply namespace support, the properties file name must be specified as follows:

```txt
{wsdl_file_name}.wsdl.properties
```

For example, if your WSDL file is `HelloWorld.wsdl`, the properties file must be `HelloWorld.wsdl.properties` and it must be placed in the same `webreferences2` directory as the WSDL file itself.

In your B2C Commerce script file, create objects using the WebReference2 class. For example, if the namespace for `HelloWorld.wsdl` is `com.test.wsdl`, creating objects for the namespace requires the qualified name to be:

```javascript
var webRef : WebReferences2 = webreference2.HelloWorld;
var request : new webRef.com.test.wsdl.HelloRequest();
var svc = webRef.getDefaultService();
var response = webRef.hello(request);
```

### Troubleshooting Web Services

Q: I’m seeing an error that references security headers and is similar to the following: "com.ibm.wsspi.wssecurity.SoapSecurityException: WSEC....."

A: The request requires a username and password token in the request header. Make sure when constructing this request that the correct credentials (as provided by the web service being connected to) are included.

Q: I’m seeing an error that references 'FaultMessage', however, everything looks syntactically correct. What is wrong and how can I fix it?

A: When the Java files get created, the classes get created with an '`_Elemen`t' suffix. What this means is that, for a WSDL element '`fmt_FaultMessage`' there’s a class with the name '`Fmt_FaultMessage_Element.java`' created (when executing wsdl2java). The WSDL and code to reference this must be adjusted accordingly. To do this, modify the WSDL to change all references to (in this example) `'fmt_FaultMessage`':

```xml
<xsd:element name="fmt_FaultMessage"> <wsdl:message name="fmt_FaultMessage">
```

Q: I’m seeing an error that the WSDL file can't be located in B2C Commerce, but I know the WSDL file is there. The error is: "Script exception in line 42:org.mozilla.javascript.EcmaError: ReferenceError: WSDL file for webreference2 'example' doesn't exist"

A: Make sure that the WSDL file is in the cartridge’s `webreferences2` directory and make sure the pipeline executing/calling it's in the same cartridge (as the WSDL file).

Q: I’m having difficulty invoking a method that expects an ArrayOf type as a parameter, how can I get this to work?

A: To pass an ArrayOf structure as a parameter to a method in a script, one should follow the following conventions (keeping in mind that the exact implementation will vary depending on your specific code/logic): `request.setSomething([theArray]);` or `request.setSomething(new Array(x))`;

Q: I’m trying to integrate with a web service that has fields defined as dateTime and keep getting this error: "Cannot convert [Calendar id=19206138] to java.util.Calendar "

A: All variables have setter methods. Salesforce recommends always using setter methods. However, when using primitive types it isn't necessary, but by using setters you’ll always be safe.

Q: I’m running into some data-type specific issues. Which data-types aren’t supported?

A: The following data types aren’t supported:

- NonNegativeInteger
- NonPositiveInteger
- UnsignedByte
- UnsignedInt
- UnsignedLong
- UnsignedShort

### Tip for Accessing Elements with the Name 'Return'

The following is an example element in a WSDL document with a name of 'return':

```xml
<element name="NewOrderResponse">
   <complexType>
    <sequence>
    <element name="return" type="ns:NewOrderResponseElement" minOccurs="1" maxOccurs="1"/>
    </sequence>
   </complexType>
  </element>
```

In order to access an element with the name "return" you must add an underscore to the name.

```javascript
response = service.newOrder(newOrder);
var result = response.['_return'];
```

With an underscore in the name, access all the properties in the object.

Errors shown for names without an Underscore

Attempting to access the element causes some of the following errors:

Example 1:

Using the following pseudocode:

```javascript
response = service.newOrder(newOrder);
var result = response.return;
```

Throws the following error:

```txt
org.mozilla.javascript.EvaluatorException: missing
```

Example 2:

Using the following pseudocode:

```javascript
response = service.newOrder(newOrder);
```

Throws the following error:

```txt
var result = response.['return']; Unknown dynamic property 'return' for class
```

## Web Service Timeouts

Carefully consider a timeout strategy for web services.

### SOAP Timeout for Unresponsive Server

SOAP web service connections use a default timeout of 2 minutes for storefront and B2C Commerce tool requests and 15 minutes for jobs. If the timeout of the calling script is less than the default, the script timeout is used.

**tip:** To maintain the site's responsiveness, configure a low timeout.

### HTTPClient Timeout

The HTTPClient method times out at 2 minutes for storefront and B2C Commerce tool requests and 15 minutes for jobs.

### Setting Timeouts

Salesforce recommends setting timeout values through the service configuration.

The timeout you configure for a service is a connection and read timeout. If each connection/read duration is just below the timeout duration, the total time of the service might be much larger than the timeout value. For example, with a 5-second timeout, with a 4-second connection attempt, followed by reading two chunks of data at 4 seconds apiece, takes about 13 seconds total, but doesn’t time out.

If you don't configure the service timeout values, it’s also possible to set port timeouts using API methods, but these aren’t monitored or included in the service status analytics. However, information about these timeouts is included below.

Port Timeouts for SOAP Web Services

Use the `dw.ws.WSUtil` class to set read/connection timeouts for ports using the `setConnectionTimeout(timeout, port)` and `setRequestTimeout(timeout, port)` methods. The minimum connection timeout is 100 miliseconds and the maximum connection timeout is 15 seconds.

## Web Service Security

There are two layers of security to configure for communication between your storefront and an external web service. At the transport layer, use certificates to identify both parties of a transaction. At the application layer, encrypt or sign content with another certificate (X.509) to make sure the contents of your messages aren’t tampered with.

### Overview of Web Service Security

The diagram below shows the communication between a Salesforce B2C Commerce pipeline and an external web service. This diagram assumes you’ve created a custom pipeline and script that invokes the web service, creates SOAP messages, and signs or encrypts messages to the web service.

When the web service is invoked via https, B2C Commerce automatically uses the client private key that you’ve stored in your instance via Business Manager, using the host name you’ve provided for that key. Import SSL certificates used for two-factor authentication into your instance. TLS certificates are used for communication with web services or when using `dw.net.HTTPClient`.

When the transport layer negotiation and handshake is complete, your B2C Commerce script sends a SOAP message to the web service.

If you use the B2C Commerce implementation of web services in the `dw.ws` package, then If the web service requires encryption or signing of SOAP messages, B2C Commerce uses the X509 certificate stored in the instance keystore with the WSDL in the `webreference2` folder in your cartridge. In this case, the private key is usually stored in Business Manager in a site preference or custom attribute and referenced in the script, so that the private key doesn't have to be included directly in the script.

Use `dw.net.httpClient` and the crypto package to send and sign a SOAP message if you can't use the B2C Commerce implementation of web services. This isn't recommended and only necessary if you require that the web service X509 certificate be stored in the Business Manager instance.

![Web Service Security Architecture](https://developer.salesforce.com/media/b2c-commerce/b2c_web_service_arch_144.gif)

### Storing Certificates

For both transport layer and application layer security, you import private keys with certificates and trusted certificates into the Business Manager instance keystore. However, if you want to use WS-Security to automatically encrypt and decrypt SOAP messages, these certificates must be stored in a cartridge.

When you import certificates into Business Manager, you also configure additional information required when using the keys and certificates, such as an alias or a service provider host name. The alias indicates to B2C Commerce which URL requires the certificate.

Private keys and certificates are stored per instance and can be used across all sites and organizations for that instance. Store up to 50 entries (keys or certificates) in an instance key store. Each entry in the key store must have an alias. Once given, the alias can't be changed. To change an alias, you must remove the certificate from the keystore and reimport it.

Each private key can be associated with up to five host names. Import the following private key file types: .pfx or .p12. Import the following types of trusted certificates: .pem,.cer,.crt,.der. Import X509 certificates as well.

Once imported, the certificates are used whenever communicating with a web service via https.

**note:** In releases before B2C Commerce 14.4, X509 certificates were stored with the .wsdl file in a keystore in the `webreferences2` folder. It's still possible to do this, but it isn't recommended if you’re only signing messages and not encrypting them, as storing certificates in the instance keystore is more secure and makes managing certificate expiration easier.

Script methods used for X509 certificates stored in the instance Keystore

To perform signing and verification using certificates stored in the instance keystore, you must use methods that include KeyRef parameter in the method signature.

These methods include:

- `dw.crypto.Signature.sign(String message, KeyRef privateKey, String digestAlgorithm)`
- `dw.crypto.Signature.signBytes(Bytes contentToSign, KeyRef privateKey, String digestAlgorithm)`
- `dw.crypto.Signature.verifySignature(String signature, String contentToVerify, CertificateRef certificate, String digestAlgorithm)`
- `dw.crypto.Signature.verifyBytesSignature(Bytes signature, Bytes contentToVerify, CertificateRef certificate, String digestAlgorithm)`
- `dw.crypto.KeyRef(String aliasS)`
- `dw.crypto.KeyRef(String alias, String password)`

Use the helper classes `KeyRef` and `CertificateRef` as references to keys in the keystore. They have a constructor that takes a string that is an alias of a private key `KeyRef` or a trusted certificate `CertificateRef` in the keystore.

### Web Service Security FAQ

Q: What features of WS-Security does B2C Commerce Support?

A: B2C Commerce supports all features of the WS-Security standard except addressing.

Q: What is a key store?

A: A keystore is a storage facility for cryptographic keys and certificates.

Q: What's the difference between a certificate and a trusted certificate?

A: A certificate is private; a trusted certificate is a public certificate issued from a trusted certificate authority.

Q: Why can't I see the Certificates & Private Keys module?

A: You must have the required permissions to see the module. Request permission for the Private Keys and Certificates Business Manager module from your administrator.

Q: How many TLS certificates can be imported per instance?

A: Up to 50 key entries can be stored per B2C Commerce instance and organization. Key entries include both private keys and certificates.

Q: How many host names can a private key be associated with in Business Manager?

A: Each private key can be associated with up to five host names.

Q: If there’s an error when using a certificate, where is it logged?

A: See the error log files under **Administration > Site Development > Development Setup > Log Files.**

Q: How do I scrub logs for sensitive information?

A: When URLs written to the service framework's communication logs must be scrubbed for sensitive information, use `dw.svc.ServiceCallback.filterLogMessage` to filter the request URL as well as the request and response bodies.

Q: Can I use the signatureKeyIdentifier and encryptionKeyIdentifier?

A: Use the WebReferences2 integration with WS-Security to set values for `signatureKeyIdentifier` and `encryptionKeyIdentifier` using constants in the `WSUtil` class. For `signatureKeyIdentifier`, use the `WS_SIG_KEY_ID` and for `encryptionKeyIdentifer`, use `WS_ENC_KEY_ID`. s

**note:** See the B2C Commerce Script API documentation for the default values that `WebReferences2` uses and its permissible options.

Q: Is sensitive data included in web service logging?

A: By default, logging data is filtered to prevent logging sensitive data. It's possible to enable logging this information if it's required. For more information, see the description of the comm logging level in .

### Import 3rd Party Private Keys and Certificates for an Instance

Import Private Keys and SSL certificates used for two-factor authentication into your instance. TLS certificates are used for communication with web services, file transfer over WebDAVClient, or when using `dw.net.HTTPClient` or any of the `dw.crypto` classes that use a `KeyRef` parameter. Salesforce B2C Commerce uses an internal password to encrypt the instance keystore.

If you have an integration to an external server using SSL/TLS, the SSL certificate that is installed at the external server must be issued by a Certification Authority (CA) that the Commerce Cloud B2C Commerce server recognizes. By default, B2C Commerce only recognizes the root CAs that ship with Oracle's Java platform. However, add additional CA certificates to the customer keystore. Certificates added to the customer keystore are checked when establishing outbound SSL connections.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration > Operations > Private Keys and Certificates.**

2.  On the Private Keys and Certificates page, search for a certificate or navigate the grid to select one.

    Select 10, 25, 50, or 100 items to appear on a page.

3.  If you’re importing a new version of an existing certificate and want to use the same alias, you must first delete the existing certificate. Aliases for all entries in the keystore must be unique.

4.  To add a new certificate or private key:

    1.  Click **Import** or **Upload a new private key or certificate.**

    2.  In the Import Private Key or Certificate window, enter a certificate or private key file name, or click **Select...** to open the File Upload window and select the file to import.

        Only the following file types are allowed:

        - Trusted certificates: .crt .pem .cer .der
        - Private Keys: .p12 .pfx
          The certificate appears in the certificate list..

5.  To add host names to a private key:

    1.  Click the dropdown to the right of a private key and select **Manage Hosts**.

    2.  On the Manage Hostnames window, enter the host name, for example, `www.sitegenesis.com`, and click **Add**.

    3.  Click **Save**.

6.  If you’re importing:

    - A trusted certificate (\*.crt): enter the following:
      - Alias: Enter an alias used to refer to this certificate when using any of the B2C Commerce script dw.crypto package methods that specify an alias. The alias shouldn't contain spaces or special characters in B2C Commerce script. B2C Commerce tells you if the alias isn't unique for your instance.
    - A private key (\*.p12): enter the following: - Source Password: Enter a password for the encryption of the key file entered in the instance keystore. - Alias: enter an alias used to refer to this certificate when using any of the B2C Commerce script dw.crypto package methods that specify an alias. The alias shouldn't contain spaces or special characters in B2C Commerce script. B2C Commerce tells you if the alias isn't unique for your instance. You might want to include the web service name or service provider name. - Host Names: If you’re using the key or certificate for transport layer security, enter the DNS name of the server as reached by the client. For example: `www.paypal.com`. B2C Commerce uses the host name to determine what certificate to use. Add two or more host names, separated by a comma. If you importing a certificate specified by one of the `dw.crypto` package methods that takes a KeyRef argument, you don't need to enter a hostname.
      If you’ve more than one private key in your keystore, the host name must be set to the target host you call via `dw.net.HTTPClient` or `dw.ws.WSUtil`. Otherwise, B2C Commerce can't guarantee that the correct client certificate is used for the call.

### Delete Certificates

If you’re importing a new version of an existing certificate and want to use the same alias, you must first delete the existing certificate. Aliases for all entries in the keystore must be unique.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Private Keys and Certificates**.

2.  On the Private Keys and Certificates page, search for a certificate or navigate the grid to select one.

3.  To delete a certificate (alias or host name):

    - Click the **Alias** checkbox (to select all certificates) or select one or more certificates, and then click **Delete**.
    - Click the ![Action Select Icon](https://developer.salesforce.com/media/b2c-commerce/b2c_action_select_icon.gif) icon to the right of a certificate and select **Delete**.

### Monitor Credit Card Encryption Keys

Credit card encryption is performed internally on Salesforce B2C Commerce for secure storage of sensitive information. Credit card encryption, key generation, and re-encryption is automatic. B2C Commerce provides the ability to monitor this process for customers undergoing a PCI audit, to demonstrate the current state of the system.

1.  Click App Launcher ![App Launcher](https://developer.salesforce.com/media/shared/appLauncher.png) and then select **Administration** > **Operations** > **Payment Instrument Encryption Keys**.

    The Payment Instrument Encryption Keys Page appears.

2.  Use the page to determine the status of your encryption keys and the dates when keys are generated.

### Using X509 Certificates for Signing or Encryption

Some web service integrations require the use of public key infrastructure for application layer web security, in which any messages exchanged are signed or encrypted to ensure that messages aren’t tampered with. A web service might also require secure communication with certificates issued by a known certificate authority, such as VeriSign, GoDaddy, or Comodo.

#### Overview

**note:** X509 certificates are used for application layer security.

![Web Service Overview](https://developer.salesforce.com/media/b2c-commerce/b2c_web_service_ovr_144.gif)

1.  Get a certificate from a known certificate authority or trusted provider to sign the SOAP message to the web service. You must provide a keystore for the WS-Security actions: Signature, Encryption, and Decryption.
2.  Place the keystore in the webreferences2 folder in the same cartridge as the WSDL file.

    **note:** The name of the keystore must be the same as the WSDL file and the file extension must be that of the keystore type (jks or pkcs12). For example, for the `CheckFraud.WSDL` service and a pkcs12 keystore type, the keystore must be named `CheckFraud.pkcs12`.

3.  If you have additional certificates that you want to use for your SSL connection, add them to your instance using Business Manager.
4.  Create a DWScript that does the following:
    - Defines a HashMap and put your client key and password, service key and password, username and password into it.
    - Defines a HashMap for the web service request that configures the actions of the interceptor actions when a call is made to the web service. Interceptor actions are defined through methods in the WSUtil class.
    - Defines a HashMap for the web service response that configures the interceptor actions for the return message.
    - Uses the `WSUtil.setWSSecurityConfig` method to configure the actions on the server
    - Calls the web service
5.  Create a custom pipeline with a script node and assign it to the script you’ve created.

#### WS-Security Web Service Template

This template shows how to use the WSUtil class to configure WS-Security for a Web service call in Salesforce B2C Commerce. However, it doesn't use sample data and can't be used to run an actual web service.

```javascript
importPackage(dw.system);
importPackage(dw.util);
importPackage(dw.ws);

var WSU_NS: String =
  "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";

function execute(args: PipelineDictionary): Number {
  // define a map with all the secrets
  var secretsMap: Map = new HashMap();
  secretsMap.put("myclientkey", "ckpass");
  secretsMap.put("myservicekey", "ckpass");
  secretsMap.put("username", "password");

  var requestCfg: Map = new HashMap();

  // define the ws actions to be performed
  requestCfg.put(
    WSUtil.WS_ACTION,
    WSUtil.WS_USERNAME_TOKEN +
      " " +
      WSUtil.WS_TIMESTAMP +
      " " +
      WSUtil.WS_SIGNATURE +
      " " +
      WSUtil.WS_ENCRYPT,
  );

  requestCfg.put(WSUtil.WS_USER, "username");
  requestCfg.put(WSUtil.WS_PASSWORD_TYPE, WSUtil.WS_PW_DIGEST);
  requestCfg.put(WSUtil.WS_SIG_DIGEST_ALGO, "http://www.w3.org/2001/04/xmlenc#sha256");

  // define signature properties
  // the keystore file has the basename of the WSDL file and the
  // file extension based on the keystore type (for example, HelloWorld.jks).
  // The keystore file has to be placed beside the WSDL file.
  requestCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_TYPE, "jks");
  requestCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_PW, "cspass");
  requestCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_ALIAS, "myclientkey");

  requestCfg.put(WSUtil.WS_SIGNATURE_USER, "myclientkey");

  // define enrcryption properties
  requestCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_TYPE, "jks");
  requestCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_PW, "cspass");
  requestCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_ALIAS, "myservicekey");

  requestCfg.put(WSUtil.WS_ENCRYPTION_USER, "myservicekey");
  requestCfg.put(
    WSUtil.WS_SIGNATURE_PARTS,
    "{Element}{http://schemas.xmlsoap.org/soap/envelope/}Body",
  );
  requestCfg.put(
    WSUtil.WS_ENCRYPTION_PARTS,
    "{Element}{" +
      WSU_NS +
      "}Timestamp;" +
      "{Content}{http://schemas.xmlsoap.org/soap/envelope/}Body",
  );

  // set the secrets for the callback
  requestCfg.put(WSUtil.WS_SECRETS_MAP, secretsMap);

  var responseCfg: Map = new HashMap();

  // define the ws actions to be performed for the response
  responseCfg.put(
    WSUtil.WS_ACTION,
    WSUtil.WS_TIMESTAMP + " " + WSUtil.WS_SIGNATURE + " " + WSUtil.WS_ENCRYPT,
  );

  // define signature properties
  responseCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_TYPE, "jks");
  responseCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_PW, "cspass");
  responseCfg.put(WSUtil.WS_SIG_PROP_KEYSTORE_ALIAS, "myservicekey");

  responseCfg.put(WSUtil.WS_SIGNATURE_USER, "myservicekey");

  // define decryption properties
  responseCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_TYPE, "jks");
  responseCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_PW, "cspass");
  responseCfg.put(WSUtil.WS_ENC_PROP_KEYSTORE_ALIAS, "myclientkey");

  responseCfg.put(WSUtil.WS_ENCRYPTION_USER, "myclientkey");

  // set the secrets for the callback
  responseCfg.put(WSUtil.WS_SECRETS_MAP, secretsMap);

  // do the service call
  var helloWorldService: WebReference = webreferences.HelloWorld;
  var helloSvc: Stub = helloWorldService.getDefaultService();

  WSUtil.setWSSecurityConfig(helloSvc, requestCfg, responseCfg);

  var parameter = new helloWorldService.Hello2();
  parameter.setName("Send Text from client...");
  var result = helloSvc.hello2(parameter);
  var responseMessage = result.getHello2Return();

  return PIPELET_NEXT;
}
```

## Working with JSON

JSON (JavaScript Object Notation) is a human-readable, easily parsed or generated data-interchange language. Salesforce B2C Commerce provides a top level JSON class to make it simple to exchange objects between your server and client. The B2C Commerce implementation is based on the json2.js implementation of JSON.

JSON objects are useful if you need to create a complex data object of an arbitrary depth. For example, if you have a main product with options that depend on other attributes, such as gender or size.

B2C Commerce provides a parsing method that can be used to construct a JSON object from a JSON string used as the value of an attribute field. Salesforce recommends using the `parse(json : String, reviver : Function) : Object` function for this purpose.

The object can then be further manipulated using any ECMA-compliant language, such as JavaScript . The object can then be stringified using the B2C Commerce-provided stringify() method and transferred to the client.

Alternatively, a JSON string used as the value of an attribute field can be transferred to the client and then parsed to create an object for further operations.

JSON objects aren't recommended for general use, because JSON doesn't handle recursive structures effectively.

## Working with XML Data

Salesforce B2C Commerce JavaScript supports the E4X extension to JavaScript. This extension supports the direct manipulation of XML data in scripts, without the need to work DOM or other intermediate structures. It's standardized as ECMA-357.

- To create an XML object

1.  Specify the following:

    ```javascript
    var order = <order><item
    quantity="1">Apple<item><item
    quantity="2">Peach<item></order>
    ```

2.  Read values from an XML object the same way you would from standard ECMAScript objects:

    ```javascript
    var items = order.item;
    var item = order.item(0);
    var quantity = order.item(0).@quantity;
    var singleItem = order.item.(@quantity == 1);
    ```

3.  Directly modify an XML object:

    ```javascript
    var order.item += <item
    quantity="1">Orange</item>;var order.item += <item
    quantity={quantity}>Orange</item>;delete order.item(2);
    ```

### Calling an Amazon.Com Service

As a working example, the next section shows how to call an amazon.com service. Amazon supports Web Service-based calls and REST calls. REST services can be called as a straight URL and return XML. The XML language support is used here to parse the returned result from the amazon.com service.

See the _Amazon Simple Services Developer's Guide_ \(www.docs.amazonwebservices.com\) for more information on developing Web Services for Amazon.

- To call the amazon.com REST service, specify

```javascript
// send the http request to amazon.com
var httpSvc = new HTTPClient();
httpSvc.open(
  "GET",
  "http://webservices.amazon.com/onca/xml?Service=AWSECommerceService&" +
    "SubscriptionId=YOUR-SUBSCRIPTION-ID&Operation=ItemSearch&" +
    "SearchIndex=Video&Keywords=potter%20harry&ResponseGroup=Images",
  false,
  null,
  null,
);
httpSvc.send();
// convert the result into an XML object
var result = new XML(httpSvc.text);
// print some values from the result.
// We must use namespace qualified access to read the values.
var ns = new Namespace("http://webservices.amazon.com/AWSECommerceService/2005-07-26");
trace(result.ns::Items.ns::Request.ns::IsValid);
trace(result.ns::Items.ns::TotalResults);
trace(result.ns::Items.ns::Item[0].ns::ASIN);
```

If you don't see a result, validate that amazon.com still returns data with the same XML format, particularly with the same namespace identifier.

<!-- document id=c51d6ed2411077c92ad5d51fc370740b9ba2093c1a6b7fd92286fbbdc3147c1b url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/webhook-monitoring-event-webhook.md -->

Webhook Monitoring Event Webhook

# Webhook Monitoring Event Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/webhook-monitoring-event-webhook/webhook-monitoring-event-webhook-oas-public.yaml)

The specification to implement a webhook in the merchant's system to export webhook monitoring events from Salesforce POS to the merchant's downstream system.

The Webhook Monitoring events are listed below and are related to Custom SPI and Webhook:

1.  Received Error
    
    1.  Webhook/SPI Response Error: Webhook/SPI response 4xx/5xx error.
    2.  Webhook/SPI Response contains errors: Webhook/SPI response contains error messages with 200 status code.
2.  Threshold Exceed
    
    1.  Webhook/SPI response timeout: Webhook/SPI response times out.
    2.  Webhook/SPI response time exceeded: Webhook/SPI response time exceeds latency config in Custom Webhook/SPI.

**Version:** 2.3.4

## Tags

### Webhook Monitoring Event Webhook

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/webhook-monitoring-event-webhook/webhook-monitoring-event-webhook-oas-public.yaml)

The specification to implement a webhook in the merchant's system to export webhook monitoring events from Salesforce POS to the merchant's downstream system.

The Webhook Monitoring events are listed below and are related to Custom SPI and Webhook:

1.  Received Error
    
    1.  Webhook/SPI Response Error: Webhook/SPI response 4xx/5xx error.
    2.  Webhook/SPI Response contains errors: Webhook/SPI response contains error messages with 200 status code.
2.  Threshold Exceed
    
    1.  Webhook/SPI response timeout: Webhook/SPI response times out.
    2.  Webhook/SPI response time exceeded: Webhook/SPI response time exceeds latency config in Custom Webhook/SPI.

## Operations

### POST Export webhook monitoring events.

`POST /merchant/webhook/monitoring/sa/sample/endpoint/to/export/webhook/monitoring/events/to/external/system`

Operation ID: `exportMessage`. Tags: Webhook Monitoring Event Webhook.

Export ExternalWebhookMonitoringMessage to merchant's system. Merchants must implement the endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details:

1.  Under **API Config**:
    *   **API Key:** `MONITORING`
    *   **API Endpoint:** Provide the external endpoint to receive the message
2.  Under **JSON Config**:
    *   **Integration Type:** `HTTP_POST` or HTTP\_PUT.

#### Request body

Media type: `application/json`. Schema: `ExternalWebhookMonitoringMessage`.

#### Responses

*   **default** Default response.
    
    Media type: `application/json`. Schema: `PSResponse`.
    

## Schemas

### ExternalWebhookMonitoringMessage

*   `monitoringEvent` (_string_)  
    Allowed values: `THRESHOLD_EXCEED`, `RECEIVED_ERROR`.
*   `latencyThreshold` (_integer (int64)_)
*   `responseTime` (_integer (int64)_)
*   `httpErrorCode` (_integer (int32)_)
*   `integrationType` (_string_)  
    Allowed values: `FORM_POST`, `HTTP_GET`, `HTTP_PUT`, `HTTP_POST`, `HTTP_DELETE`.
*   `url` (_string_)
*   `apiKey` (_string_)

### PSResponse

*   `errorMessage` (_string_, nullable) Error message shown to the user.  
    Example: `Invalid request. Please check the request and try again.`.
*   `errorCode` (_string_, nullable) Error code shown to the user.  
    Example: `INTERNAL_ERROR`.
*   `error` (_boolean_)

<!-- document id=3d5a1f613c58ff3d8cc61886e82ba2f32c1c3446e0d9640c2c4d466381d6b34b url=/developer/current/en-us/commerce-cloud/b2c-commerce/guides/customer-service-center/b2c-csc-widgets.md -->

# Widgets

Use widgets in any Customer Service Center customizable area. Commonly used widgets include `attribute_layout`, `attribute_form`, `attribute_listing`, `text`, `link`, and `tabs`.

Widgets are always named directly and configured by registering them with a type.

| Name     | Type   | Description                                            |
| -------- | ------ | ------------------------------------------------------ |
| `config` | object | an object that contains widget-specific configurations |
| `type`   | string | the required widget type                               |

Example of widget registration:

```json
"widgets": {
  "description": {
    "type": "attribute_listing",
    "config": {
      "attributes": [
        "system_attribute",
        "c_customAttribute"
      ],
      "columns": 2
    }
  },
  "my_layout" : {
    "type" : "attribute_layout"
  },
  "option-selector": {
    "type": "product_option"
  },
  "quantity-selector": {
    "type": "product_quantity"
  }
}
```

Details on customizing each widget are included in the remaining sections of this guide.

## Attribute_form Widget

The `attribute_form` widget provides a form element for attributes depending on metadata. The metadata are either derived from attributes or through metadata overwrite in layout.

The attribute_form widget is only configured through layout and its subelements.

```json
{
  "layout": [
    {
      "condition":"data",
      "layout": [
        {
          "id":"address",
          "layout": [
            {
              "attribute":"first_name",
              "meta": {
                "maxLength":50
              },
              "width":6
            },
            {
              "attribute":"last_name",
              "meta": {
                "maxLength":50,
                "required":true
              },
              "width":6
            }
          }
        ]
    }
  ],
  "widgets": {
    "address": {
      "type":"attribute_form"
    }
  }
}
```

With the customization, it's also possible to override the metadata of attributes to:

- Provide or restrict options of values, for example, the state codes for certain countries
- Change the type, format or constraints of attributes, for example, the format of the credit card expiration month or the maximum input length
- Mark an attribute as required

This table lists the options of overriding meta data.

<table><tbody><tr><td><p>label</p></td><td><p>Metadata can be adjusted to show different localized text as coming from the Salesforce B2C Commerce platform metadata</p></td></tr><tr><td><p>required</p></td><td>

If an attribute is required in a form, it can be marked accordingly for mark in the UI and verify it.

```json
{
  "attribute": "payment_card.holder",
  "meta": {
    "required": true
  }
}
```

</td></tr><tr><td><p>disabled</p></td><td>

A form element can be disabled for read-only purposes with `disabled`.

```json
{
  "attribute": "customer_no",
  "meta": {
    "disabled": true
  }
}
```

</td></tr><tr><td><p>type & format</p></td><td>

The `format` attribute lets you override the default display, for example, to show a string in a textbox only. ("format": "text")

The format requires an explicit type declaration.

```json
{
  "attribute": "note",
  "meta": {
    "type" : "string",
    "format": "text",
    ...
  }
}
```

Currently supported are:

- string: text, password, email, html, null, date, date-time, and time

- number: int32, int64, float, double, byte, and null

- integer: int32, int64, byte, and null

</td></tr><tr><td><p>maxLength</p></td><td>

The maximum length of an attribute can be restricted with `maxLength`.

```json
{
  "attribute": "postal_code",
  "meta": {
    "maxLength": 5
  }
}
```

</td></tr><tr><td><p>enum</p></td><td>

The configuration of an `attribute_form` widget allows the override of enumeration values to either limit enum values in a certain dropdown based on conditions or localize values differently.

The current example would lead to a dropdown with three items (Price Match, Appeasement, Other) regardless the number of items declared in the meta data. The condition makes sure that this enum is active for product level only.

Each enum element has a separate label attribute including localization.

```json
{
  "attribute": "reason_code",
  "condition": "data.level === 'product'",
  "meta": {
    "enum": [
      {
        "code": "PRICE_MATCH",
        "label": {
          "default": "Price match",
          "de": "Preisänderung"
        }
      },
      {
        "code": "Appeasement",
        "label": {
          "default": "Appeasement"
        }
      },
      {
        "code": "Other"
      }
    ],
    "required": true
  },
  "width": 6
}
```

</td></tr><tr><td><p>regex</p></td><td>

The attribute form widget recognized regex configured in the meta data. The values can be overwritten if they are more specific to CSC.

```json
{
  "attribute": "postal_code",
  "meta": {
    "required": true,
    "maxLength": 5,
    "pattern": "^[0-9]{5}$"
  }
}
```

</td></tr><tr><td><p>dynamic_enum</p></td><td>

The `dynamic_enum` option refers to a particular property that contains the allowed values for a certain attribute. Those values could be determined during the request processing.

```json
{
  "attribute": "c_shipping_schedule",
  "meta": {
    "type": "string",
    "format": "date",
    "dynamic_enum": {
      "code_property": "c_shipping_schedule_selection_codes",
      "label_property": "c_shipping_schedule_selection_labels"
    }
  }
}
```

</td></tr></tbody></table>

For example, To avoid errors when entering the state code, the state code values are provided as a selection for the US. For Canada and France, a simple input field is shown:

```json
{
  "layout" : [
    {
      "layout": [
        {
          "id": "address",
          "layout": [
            {
            ... more attributes ...
            },
            {
              "attribute": "state_code",
              "condition": "data.country_code === 'FR' || data.country_code === 'CA'",
              "width": 6
            },
            {
              "attribute": "state_code",
              "condition": "data.country_code === 'US'",
              "meta": {
                 "required": true,
                 "enum": [
                   {"code":"AL", "label":{"default":"AL-Alabama"}},
                   {"code":"AK", "label":{"default":"AK-Alaska"}},
                   ... more states ...
                 ]
              },
              "width": 6
            }
          ]
        }
      ]
    }
  ],
  "widgets" : {
    "address" : {
      "type" : "attribute_form"
    }
  }
}
```

## Attribute_layout Widget

The `attribute_layout` widget prints the content of a certain attribute.

This widget is only configured through layout and its subelements and needs only a simple widget registration. The following example shows how the attributes `first_name`, `last_name`, `postal_code`, and `city` can be arranged in a layout using the default width, which results in a line break after each attribute.

```json
{
  "layout": [
    {
      "id": "address",
      "layout": [
        {
          "layout": [
            {
              "attribute": "first_name"
            },
            {
              "attribute": "last_name"
            }
          ]
        },
        {
          "layout": [
            {
              "attribute": "postal_code"
            },
            {
              "attribute": "city"
            }
          ]
        }
      ]
    }
  ],
  "widgets": {
    "address": {
      "type": "attribute_layout"
    }
  }
}
```

This example result in the following view of the billing address at an order, in which the grid distributes the cells automatically.

![Example billing address rendered with the attribute_layout widget using automatic grid distribution](https://developer.salesforce.com/media/b2c-commerce/b2c_customer_service_center_billing_address_without_anything.png)

## Attribute_listing Widget

The `attribute_listing` widget can show system and custom attributes in either one, two or three columns in the order of the configuration.

| Name         | Type             | Description                                                           |
| ------------ | ---------------- | --------------------------------------------------------------------- |
| `columns`    | integer          | the number of columns (1, 2, or 3) to use                             |
| `attributes` | array of strings | the attributes to display                                             |
| `show_empty` | Boolean          | whether an attribute appears when no value's defined default is false |

```json
{
  "columns": 2,
  "attributes": ["attribute1", "attribute2"]
}
```

## Link Widget

A link widget shows a link with an href and text information.

```json
"product_link": {
  "link": {
   "type": "link",
     "data": {
        "href": {
           "template": "/s/{0}/dw/shop/v16_9/products/{1}",
           "attributes": ["SITE_ID", "id"]
        },
        "text": {
           "template": {"default":"Product {0}"},
           "attributes": ["id"]
        }
     }
  }
}
```

## Tabs Widget

Use the tabs widget to place tabs somewhere in the layout. Each tab can be of type widget_tab or form_tab.

Tabs can contain available widgets and forms.

<table><thead><tr><th>Name</td><th>Type</td><th>Description</td></tr></thead><tbody><tr><td><p>type</p></td><td><p>string</p></td><td><p>Declares the type of tab:</p><ul><li><p><code>widget_tab</code> - to reference a widget directly</p></li><li><p><code>form_tab</code> - to reference a particular configured area</p></li></ul></td></tr><tr><td><p>caption</p></td><td> </td><td><p>a template to define localized meta data</p>

```json
"caption": {
  "template": {
    "de": "Kunde (de)",
    "default": "Customer Data",
    "de-DE": "Kundendaten (de-DE)"
  }
}
```

</td></tr><tr><td><p>config</p></td><td> </td><td><p>A configuration for <code>form_tab</code> tabs:</p><ul><li><p><code>area_id</code> (string): Specifies the area id to appear in this tab.</p></li><li><p><code>default_data_provider</code> (string): A data provider to access the data in the form</p></li><li><p><code>query_params</code> (Boolean): query params for the particular data provider</p></li></ul></td></tr></tbody></table>

```json
"tabs": {
  "type": "tabs",
  "config": {
    "tabs": [
      {
        "type": "widget_tab",
        "caption": {
          "template": {
            "default": "Coupons"
          }
        },
        "widget_id": "basket_coupons"
      },
      {
        "type": "form_tab",
        "caption": {
          "template": {
            "default": "Customer Data"
          }
        },
        "config": {
          "area_id": "customer_view",
          "default_data_provider": "Customer",
          "query_params": {
            "customer_id": {
              "attribute": "customer_info.customer_id"
            }
          }
        }
      }
    ]
  }
}
```

The main layout section needs a reference to the tabs widget only to show the configured tabs with their content.

```json
"layout": [
  {
    "layout": [
      {
        "id": "tabs",
        "width": 8
      }
    ]
  }
]
```

## Text Widget

The text widget shows localized and parametrized text.

```json
"text_id": {
  "type": "text",
  "data": {
    "template": {
      "default": "Hello World - {0} - {1}:"
    },
    "attributes": [
      "order_no",
      "site_id"
    ]
  }
}
```

![Example rendering of a Customer Service Center text widget showing localized and parametrized text output](https://developer.salesforce.com/media/b2c-commerce/b2c_customer_service_center_text_widget.png)

<!-- document id=28162e1a30971e453468d86e9a90ba41eeb8186decfbb9ebdeaf067ebc43f7d0 url=/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/wishlist-spi.md -->

Wishlist SPI

# Wishlist SPI

**Partial reference:** 3 operation(s) were omitted because their source references could not be resolved.

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/wishlist-spi/wishlist-spi-oas-public.yaml)

Merchant SPI to perform wishlist operations via a customer-managed provider adapter. This SPI allows retailers to integrate any wishlist provider without Retail Cloud engineering involvement. APIs include get wishlist, add products, and remove products. The API returns product IDs only; POS enriches them with full details from Solr.

**Version:** 2.3.4

## Tags

### Wishlist SPI

[Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/wishlist-spi/wishlist-spi-oas-public.yaml)

Merchant SPI to perform wishlist operations via a customer-managed provider adapter. This SPI allows retailers to integrate any wishlist provider without Retail Cloud engineering involvement. APIs include get wishlist, add products, and remove products. The API returns product IDs only; POS enriches them with full details from Solr.

<!-- document id=bdef7854ff0dc47ca9401c94b3d7d9f98bc1ee812eabd1e6adee1f76f23c1a81 url=/developer/current/en-us/commerce-cloud/salesforce-commerce/guides/write-tests-for-an-extension-provider.md -->

# Write Tests for an Extension Provider

Writing tests for an extension provider is an essential step in the development process. These tests ensure that the functionality of the extension class is working as intended and that any changes made to the class do not break existing functionality. It is a best practice to write tests before writing the actual code to have a clear understanding of the requirements and to have a reliable set of tests in place to verify that the code is working correctly.

In this guide, we describe the process of creating tests for extension providers.

## 1. Testing and Code Coverage

Testing code coverage is a measure of how much of the Apex code in your org has been executed by your test methods. You are required to have at least 75% code coverage for your Apex classes and triggers. When you run your test methods, Salesforce calculates the code coverage and displays it in the Developer Console and the Apex Test Execution page.

Refer to [Testing and Code Coverage](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_code_coverage_intro.htm) for more information.

Consider the following base Apex class and extension provider class.

### Base Apex Class

```java
global virtual class CommerceDX_Inventory {
    global virtual Integer calculateInventory(String webstoreName, String eventName){
        return 10;
    }
}
```

### Extension Provider Class

```java
public class Custom_Inventory extends CommerceDX_Inventory {
    public override Integer calculateInventory(String webstoreName, String eventName) {
        return super.calculateInventory(webstoreName, eventName);
    }
}
```

### Test Apex Class

```java
@isTest
public class Custom_InventoryTest {
    @isTest
    static void testCalculateInventory() {
        String webstoreName = 'myWebstore';
        String eventName = 'dreamforce';
        Integer inventory = new Custom_Inventory().calculateInventory(webstoreName, eventName);
        System.assertEquals(10, inventory, 'Correct inventory calculation for non-blank webstoreName and eventName');
    }
}
```

## 2. Test with the Database

When testing an Apex class that interacts with the database, you can use test data to set up the test context and assert that the class is behaving as expected. Here's an example of an Apex test class that tests an Apex class that interacts with the database.

### Extension Provider Class

```java
public class Custom_InventoryDB extends CommerceDX_Inventory{
    public override Integer calculateInventory(String webstoreName, String eventName) {
        Integer inventory = super.calculateInventory(webstoreName, eventName);
        List<Product2> product = [SELECT ProductCode FROM Product2];
        System.debug(product);
        if(product.size() > 0){
            return inventory;
        }
        return -1;
    }
}
```

### Test Apex Class

```java
@isTest
public class Custom_InventoryDBTest {
    @isTest
    static void testCalculateInventory() {
        String eventName = 'dreamforce';
    	String webstoreName = 'myWebstore';

        // Verify NO DATA before testing
        List<Product2> product = [SELECT ProductCode FROM Product2 WHERE Name =:eventName];
        System.assertEquals(0, product.size());
        Integer inventory = new Custom_InventoryDB().calculateInventory(webstoreName, eventName);
        System.assertEquals(-1, inventory);

        // Create test data
        Product2 testProduct = new Product2(Name ='dreamforce');
        insert testProduct;

        // Verify result after insterting data
        inventory = new Custom_InventoryDB().calculateInventory(webstoreName, eventName);
        product = [SELECT ProductCode FROM Product2 WHERE Name =:eventName];
        System.assertEquals(1, product.size());
        System.assertEquals(10, inventory);
    }
}
```

To verify the test data is not persistent, we can create another test like the following.

```java
@isTest
static void verifyTestDataAreNotPersistent() {
    List<Product2> product = [SELECT ProductCode FROM Product2 WHERE Name =:eventName];
    System.assertEquals(0, product.size());
    Integer inventory = new Custom_InventoryDB().calculateInventory(webstoreName, eventName);
    System.assertEquals(-1, inventory);
}
```

Refer to [the Understanding Test Data](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing_data.htm) for more information.

## 3. Mock HTTP callout

Mocking HTTP callout is a feature in Apex that allows you to simulate an HTTP callout in a test method, without actually calling an external service. Mocking the callout is useful for testing Apex code that makes HTTP callouts because it allows you to test the code in isolation, without depending on the availability or behavior of the external service.

### Extension Provider Class

```java
public class Custom_InventoryCallOut extends CommerceDX_Inventory {
    public override Integer calculateInventory(String webstoreName, String eventName) {
        Integer inventory = super.calculateInventory(webstoreName, eventName);
        HttpResponse res = makeCallout();
        if(res.getStatusCode() == 200){
            return 2 * inventory;
        }
        return inventory;
    }
    private HttpResponse makeCallOut() {
        HttpRequest req = new HttpRequest();
        req.setEndpoint('https://example.com/example/test');
        req.setMethod('GET');
        Http h = new Http();
        HttpResponse res = h.send(req);
        return res;
    }
}
```

### HttpCalloutMock Implementation

```java
public class myCallOutMock implements HttpCalloutMock {
    public HttpResponse respond(HttpRequest req) {
        HttpResponse res = new HttpResponse();
        res.setBody('{ "message": "Hello from the mock callout!" }');
        res.setHeader('Content-Type', 'application/json');
        res.setStatusCode(200);
        return res;
    }
}
```

### Test Apex Class

```java
@isTest
public class Custom_InventoryCallOutTest {
    @isTest
    static void testMakeCallout() {
        String eventName = 'dreamforce';
    	String webstoreName = 'myWebstore';
        Test.setMock(HttpCalloutMock.class, new myCalloutMock());
        Integer inventory = new Custom_InventoryCallOut().calculateInventory(webstoreName,eventName);
        System.assertEquals(20, inventory);
    }
}
```

Refer to [Testing HTTP Callouts by Implementing the HttpCalloutMock Interface](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_testing_httpcalloutmock.htm) for more information.

## 4. Mock file-based Apex

Refer to [Mock the Base Apex Class](https://developer.salesforce.com/docs/commerce/salesforce-commerce/guide/mock-the-base-apex-class.md) for more information.

## 5. Observing Governor Limit Metrics for a Test

Governor limits are a set of limits enforced by Salesforce to ensure that Apex code doesn't consume too many resources. In an Apex test class, you can use the Test.startTest() and Test.stopTest() methods to set an isolated environment between them so that you can see how your code behaves under different conditions. The Test.startTest() and Test.stopTest() methods also reset side governor limits between them, which are independent of the limits outside of it. Here's an example of how you can observe governor limits in the test:

### Extension Provider Class

```java
public class Custom_InventoryLimit extends CommerceDX_Inventory{
    public override Integer calculateInventory(String webstoreName, String eventName) {
        return [SELECT count() FROM Product2 WHERE Name =:eventName];
    }
}
```

### Test Apex Class

```java
@isTest
public class Custom_InventoryLimitsTest {
    @isTest
    static void testGovernorLimits() {
        // Test env starts
        Test.startTest();

        // Code that you want to test goes here
        String webstoreName = 'myWebstore';
        String eventName = 'dreamforce';

        // Query once through the extension provider class
        Integer count = new Custom_InventoryLimit().calculateInventory(webstoreName, eventName);
        System.assertEquals(Limits.getQueries(), 1);

        // Test env ends
        Test.stopTest();

        // verify governor limits reset to 0 out side of Test suites
        System.assertEquals(Limits.getQueries(), 0);
    }
}
```

In this example, the test class starts the test environment using the `Test.startTest()` method and the code that you want to test goes in between the start and stop test methods. Then, the test class stops the test environment using the `Test.stopTest()` method.

Refer to [Using Limits, startTest, and stopTest](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_testing_tools_start_stop_test.htm) for more information.

After that, the test class checks the governor limits. The `Limits.getQueries()` method returns the number of SOQL queries executed within the test method’s pairs. You can use other methods to check governor limits, including `Limits.getCpuTime()` and `Limits.getLimitContexts()`.

Refer to [Apex Governor Limits](https://developer.salesforce.com/docs/atlas.en-us.salesforce_app_limits_cheatsheet.meta/salesforce_app_limits_cheatsheet/salesforce_app_limits_platform_apexgov.htm) for more information.

## 5.1 Read-only Governor Limits

A read-only class is a class that only performs read operations, such as queries, but does not modify the data. To guarantee that your extension provider class is executed in read-only mode, write a test that checks the DML operation for your Apex class.

### Extension Provider Class

```java
public class Custom_InventoryReadOnly extends CommerceDX_Inventory {
    public override Integer calculateInventory(String webstoreName, String eventName) {
        Product2 testProduct = new Product2(Name ='dreamforce');
        insert testProduct;
        return 0;
    }
}
```

### Apex Class Test

```java
@isTest
public class Custom_InventoryReadOnlyLimitsTest {
    @isTest
    private static void testSOQLQueriesLimitWithReadOnlyClass() {
        String webstoreName = 'myWebstore';
        String eventName = 'TestProduct';
        Integer result = new Custom_InventoryReadOnly().calculateInventory(webstoreName, eventName);
        // Assertion to make sure you don't accidentally write a DML operation in your Apex class!
        System.assertEquals(0,Limits.getDmlStatements(), 'Extension provider class should be read only');
    }
}
```

## Next Steps

Now you that you have written your test code, you can run it on your extension provider class and make any necessary changes.

Refer to [Exception Statements](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_exception_statements.htm) for more information.

<!-- document id=df5f7630fe260b0c89a04656de247473e5462d1d5b51da3c6f49c9934adf3a28 url=/developer/current/en-us/commerce-cloud/retail-cloud/guides/writing-ui-automation-tests-for-pos.md -->

# Writing UI Automation Tests for POS

This article outlines the guidelines for customers interested in crafting their own automation test scripts to streamline testing scenarios. Our aim is to maintain a consistent approach to accessibility identifiers within the app for similar widgets.

## Prerequisites

To successfully execute UI Automation scripts with any chosen tool, the following prerequisites must be met:

- Acquisition of the IPA from the AppStore or install build from Testflight
- POS app version 9.8.1 or greater to ensure all UI elements within the POS app can be accurately identified.
- Bundle Id to use for the Testflight app: **com.psstore.beta.ios**

## Certified Tools

Point of Sale has certified the following tools for UI automation:

**XCUITests**

This is the tool used by the Point of Sale dev team for UI automation testing.

### Appium

Highlighted for its ability to efficiently recognize and interact with the App UI Elements, as demonstrated by the below Appium Inspector screenshots.

Detailed Setup Instructions [here](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/appium-setup-for-pos-ui-automation-testing.html)

![writing-ui-automation-tests-for-pos-sc1.png](https://developer.salesforce.com/docs/media/retail-cloud/writing-ui-automation-tests-for-pos-sc1.png)

## Known Issues

The POS app cannot be bootstrapped on a Simulator as you require camera to scan the activation QR Code for your merchant.

## POS App UI

The POS app UI is crafted from two main sources: layouts generated from CMS and native screens directly implemented within the app. Both avenues employ UI elements. This section details the UI elements from these distinct sources, focusing on their identification for UI automation purposes.

Each UI element is assigned a unique identifier, facilitating their identification and interaction during automation processes.

To distinguish these elements effectively, they are tagged with accessibility identifiers. We employ specific strategies to determine these identifiers; expect this list of strategies to expand as our team further optimizes the accessibility identifier heuristics.

## Native UI Screens

This section discusses the native UI screens. UI elements found here are also present in the Layout UI, though it's important to note that Layout UI elements feature dynamic accessibility identifiers. More details on this are provided in the Layout Elements section.

## UI Elements

| **Element**             | **Identifier Pattern**                          | **Example**                                                                     |
| ----------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
| UIBarButtonItem         | <Function>BarButton                             | HomeBarButton, ToggleCameraBarButton                                            |
| UISwitch                | <Function>Switch                                | BillingSameAsShippingSwitch, SaveToProfileSwitch                                |
| UIButton                | <Function>Button                                | SelectButton, EditCustomProductButton                                           |
| UITableViewCell         | For list of cells: <Function>Cell-Index         | AlterationOptionsCell-1, OrderEntityCell-1                                      |
|                         | For individual cells or headers: <Function>Cell | SummaryCell, TransferDestinationCell                                            |
| UITextField             | <Function>Field                                 | ActualCashInDrawerField, CouponCodeField                                        |
| UITextView              | <Function>View                                  | AssociateDetailsView, -AdditionalFeedbackMessageView                            |
| UISegmentedControl      | <Function>Control                               | FulfillmentTypeControl, StoreAnalyticsTimePeriodControl                         |
| UIPickerView            | <Function>Picker                                | AnalyticsTimePeriodPicker, PaymentMethodPicker                                  |
| UIDatePicker            | <Function>DatePicker                            | StoreAnalyticsDatePicker, GenericDatePicker                                     |
| UIPageControl           | <Function>PageControl                           | LaunchImagesPageControl, ProductImagesPageControl                               |
| UIActivityIndicatorView | <Function>ActivityIndicator                     | FetchOrderHistoryActivityIndicator, CheckPSBackendConnectivityActivityIndicator |
| UISearchBar             | <Function>SearchBar                             | LayoutSearchBar, StoreSearchBar                                                 |

## Layout Elements

| **Element**                                                                                                                                                 | **Identifier Pattern**                                                                                                                                                                                                                                                        | **Example (9.8.1 and onwards)**                                                                                                                                                                          | **Example (prior to 9.8.1)**                                                                                                                                                                                                        |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Layout Cells (these are views in landing screens of tabs that are used to navigate to other functionality in the app like tills, search, clienteling, etc.) | <Deeplink>Cell                                                                                                                                                                                                                                                                | 1. ProductSearchCell<br>2. CustomerSearchCell<br>3. ExpressCheckoutCell<br>4. CashPickupCell<br>5. VendorReturnCell                                                                                      | 1. productSearch/listStyle=grid&preselectedVariantOptions=Color&productQuery=%2A&showControls=true&sort=<br>2. storeCRM<br>3. scanToCart<br>4. currentDrawer/pickup<br>5. vendorReturn/vendorreturn                                 |
| Layout Cells (that point to other layouts)                                                                                                                  | LayoutCell-<Function><br><br>**Note:** Function is derived from the **Alt Text for ADA** defined in the CMS for this layout. Since a layout can be a hosting view for any functionality, these have to be derived from CMS configs and are bound to change if updated on CMS. | 1. LayoutCell-StyleQuiz<br>2. LayoutCell-BOPISBOFISOrders                                                                                                                                                | 1. Style Quiz<br>2. BOPIS & BOFIS Orders                                                                                                                                                                                            |
| Layout-Driven Text Fields / Pickers                                                                                                                         | <Function>Field<br><br>**Note:** These are generated from CMS and the app makes a best attempt to keep this consistent with similar fields throughout the app. However, if configured with a custom field, we will add it to the **accessibilityId**.                         | 1. UsernameField<br>2. PasswordField<br>3. FirstNameField<br>4. FirstNameField                                                                                                                           | 1. UseridField<br>2. PasswordField<br>3. FirstnameField<br>4. Profile.FirstnameField                                                                                                                                                |
| Layout Drive Text Fields (multiline)                                                                                                                        | <Function>View                                                                                                                                                                                                                                                                | NotesView                                                                                                                                                                                                | Order.NotesView                                                                                                                                                                                                                     |
| Layout Driven Buttons                                                                                                                                       | <ButtonAction>Button<br><br>**Note:** This is the button action defined in CMS. If **Button Action** is missing, we will derive this from the deep link configured for the button.                                                                                            | 1. SignUpButton<br>2. SkipcustomerloginButton<br>3. PrintReceiptButton                                                                                                                                   | 1. SignupButton<br>2. SkipcustomerloginButton<br>3. NoneButton                                                                                                                                                                      |
| Layout Driven Checkboxes                                                                                                                                    | <Function>Toggle                                                                                                                                                                                                                                                              | 1. CheckButton<br>2. CheckButton<br>3. isPickupForAllItems                                                                                                                                               | 1. NewslettersignupToggle<br>2. TermsToggle<br>3. IspickupforallitemsToggle                                                                                                                                                         |
| Hamburger Menu Items                                                                                                                                        | <Deeplink>                                                                                                                                                                                                                                                                    | 1. AdvancedCartOptions<br>2. SuspendedCarts<br>3. SuspendedCarts-Customer-Current<br>4. QuoteLookup<br>5. QuoteLookup-Customer-Current<br>6. StoreSearch<br>7. SwitchCardReader<br>8. More<br>9. Drawers | 1. advancedCartOptions<br>2. storeSavedCarts<br>3. storeSavedCarts<br>4. quoteLookup<br>5. quoteLookup<br>6. storeSearch<br>7. switchCardReader<br>8. unknown (a submenu for more items)<br>9. unknown (a submenu for drawer stuff) |

### Composite UI Views

In the POS app, there are various types of views, ranging from complex groupings like cart product lists to simpler lists, such as customer views. For these situations, top-level elements are indexed for easy access, for example, **InStoreCartProductCell-1** or **SelectAddressButton1**.

To interact with specific elements within these groups, such as a delete product button, you should reference the primary grouped view and then locate the desired element. It's not necessary to append an index prefix to every element within a group.

The example below adjusts the quantity of the second item in a cart and validates the change:

```javascript
func validateIncreaseProductQuantity() throws {
    let cartCell = TransactionElement.instoreProductCellTwo.element //"InStoreCartProductCell-2"
    let increaseQtyButton = cartCell.buttons[ "IncreaseProductQuantityButton"]
    increaseQtyButton.tap()

    let blockViewSpinner = CommonElement.blockViewSpinner.element
    XCTAssertTrue(testCaseInstance.waitForElementToDisappear(blockViewSpinner, 120), "Could not wait until checking for scanned product spinner disappears")
    let productQtyField = cartCell.textFields["QuantityField"]
    if let qtyValue = productQtyField.value as? String {
        XCTAssertEqual(qtyValue, "2", "Quantity increased successfully.")
    } else {
        XCTFail("No text field value")
    }
}
```

**note:** The above test case is written using XCUITest framework in Swift language.

### Waiting for Network Call

The POS app displays a spinner on the UI during network calls, which disappears once the call is complete. Test cases account for this by pausing until the spinner vanishes, ensuring the network activity has concluded. This behavior is demonstrated in the provided example.

```javascript
let blockViewSpinner = CommonElement.blockViewSpinner.element; //"BlockViewSpinner"
XCTAssertTrue(
  testCaseInstance.waitForElementToDisappear(blockViewSpinner, 120),
  "Could not wait until checking for scanned product spinner disappears",
);
```

### Hardware Peripherals

We cannot simulate hardware peripherals like card reader or printer to test the full functionality.

**Cash Drawer** - Set the test register Cash Drawer Mode to External if you don't want the register to wait for a physical drawer to be opened.

**Hardware Scanner** - We recommend using the Camera Scanner for automation. Work with your testing tool to see if they support simulating barcode scans.

## Tests

This section covers the essential aspects of creating and structuring UI automation tests for the POS app. It includes guidance on identifying UI elements, structuring test cases, and implementing best practices to ensure reliable and maintainable automation scripts.

### Process of Identification

The initial phase of writing UI automation involves identifying the specific UI screen and cataloging all its UI elements. With these elements identified, scripts can then be developed to interact with and manipulate the UI elements within that screen.

### Test Case Structure

Leverage a Test Management Tool to systematically create a test case for each unique ID in your suite. This approach facilitates the alignment and comparison of results with your existing test cases. Below is an example illustrating how we structured our test cases for scenarios involving cart screen interactions.

![writing-ui-automation-tests-for-pos-sc2.png](https://developer.salesforce.com/docs/media/retail-cloud/writing-ui-automation-tests-for-pos-sc2.png)

## Best Practices

- **Device Preparation:** Install the TestFlight app on your iOS device and enable it for your merchant account prior to testing. This eliminates the need for environment setup through test scripts. **NOTE**: If your automation tool is capable of scanning codes via device camera, you can indeed automate the bootstrapping and environment setup process.
- **App Environment:** Make sure to switch to staging environment and have this register created in our CMS before executing your tests. This should be a one time step. **NOTE**: If you are okay executing tests in production, this step is optional. This is left to the customer's choice
- **Till Management:** Reconcile the previous day's transactions and set up a new till early to prevent unexpected alert prompts during testing. This should be done daily or you can write scripts to do this first thing every day.
- **Minimize Coordinate Usage:** Avoid excessive reliance on coordinates for interacting with elements, as this practice can result in fragile tests.
- **Issue Reporting:** Immediately report any problems with element detection or inconsistency to the Point of Sale team for resolution.

<!-- document id=dccf2661ed13236b378cc2c214f461c55cf4d0a1c92e7a354c9626ca20e1b2bd url=/developer/current/en-us/commerce-cloud/einstein/guides/einstein-recommendations/zone-component.md -->

# Zone Component

A _zone_ is defined as one recommendation slot. Using zones for recommendations is optional, but zones offer added flexibility. For example, your product details page can have two zones: one for the "You may also like” recommender and another for the "Complete the set" recommender. Using zones, easily switch between recommenders in Einstein Configurator.

Unlike with content slots, implementing recommendations with the Einstein Recommendations API requires some coding to enable switching among recommenders.

**note:** When changing the recommenders for a zone, limit the change to other recommenders within the same recommender type. With this action, avoid the need to change the recommendation anchor.

## Comparison Between API Setup With or Without Zones

|                                       | With Zones                                                                                                                                              | Without Zones                                                                                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Changing recommenders for a zone**  | In Einstein Configurator, change the recommender linked to the zone.                                                                                    | Use a code change to update the API call with the new Recommender.                                                                             |
| **API endpoint**                      | [Get zone recommendations](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=getZoneRecommendations) | [Get recommendations](https://developer.salesforce.com/docs/commerce/einstein-api/references/einstein-recommendations?meta=getRecommendations) |
| **Recommendations endpoint response** | `{recs: [], recoUUID: '', recommenderName: '', displayMessage: ''}`                                                                                     | `{recs: [], recoUUID: ''}`                                                                                                                     |

The activities endpoint is always the same whether you are using zones or not. The `viewReco` and `clickReco` activities always require a `recommenderName` parameter. When using zones, the `recommenderName` parameter in `viewReco` and `clickReco` activities must come from the response of of a request to the Zone Recommendations API.

## How to Set up Zones in Einstein Configurator

After enabling access to the API in the [Einstein Configurator](https://configurator.cquotient.com/), the Site Recommendations tab changes to a menu for site admin users. Using this menu, view and configure Recommenders or Zones.

Site administrators can enable access to zones for other users from the User Management tab by locating and selecting the user, and selecting **Edit Actions** from the menu.

The Recommenders tab is where you set up, edit, and delete recommenders, the same as using the Site Recommendations page without API access configured. The Zones tab is for setting up, editing, and deleting zones.

To create a zone:

1. Select **Zones** from the Site Recommendations menu.
2. Click **+New Zone**.
3. Specify a Zone Name, and provide an optional description of the zone.
   - After it’s saved, the Zone Name can’t be changed.
4. Use the menu to select an available recommender for use in the zone.
   - If you don’t have any recommenders configured, or haven’t decided which recommender to use for a zone, save this step for later. For information about how to create recommenders, see [Commerce Cloud Einstein Product Recommendations](https://help.salesforce.com/s/articleView?id=cc.b2c_einstein_site_recommendations.htm&type=5).

5. Click **Save**.

Create multiple zones for use through the Einstein API.

## How to Use Zone Components Through the Einstein API

After you set up zones in the Einstein Configurator, a developer uses the configured zone name as the `zoneName` path parameter in the zone API request (see `API Specification` - `Endpoints` - `Zone Recommendations`).

The response contains a `recommenderName` that identifies the name of the recommender currently configured for the zone. Pass this value as the `recommenderName` body parameter in subsequent `viewReco` and `clickReco` activity requests.